Skip to content

CodexBar 是一个 macOS 菜单栏应用,用于查看本机 Codex 账号状态、额度、Token 用量、详细统计信息

feat: 添加 Codex Hook 工作流统计

Bob1c61b089c52f
diff --git a/AGENTS.md b/AGENTS.md
index 3519a2d..89234dc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,7 +6,7 @@
## 目标
-CodexBar 是一个 macOS 菜单栏应用, 通过本机 Codex app-server 展示当前 Codex 账号、额度、token 用量、Codex CLI/APP 版本和交互日志。你的目标是交付可验证、范围清晰、贴合现有 SwiftUI/AppKit/MVVM 架构的修改, 并保护本地认证、隐私、菜单栏体验、Sparkle 更新和发布流程。
+CodexBar 是一个 macOS 菜单栏应用, 通过本机 Codex app-server 展示当前 Codex 账号、额度、token 用量、Codex CLI/APP 版本和交互日志, 并可通过 Codex Hook 统计本机工作流数据。你的目标是交付可验证、范围清晰、贴合现有 SwiftUI/AppKit/MVVM 架构的修改, 并保护本地认证、隐私、菜单栏体验、Hook 配置、Sparkle 更新和发布流程。
## 成功标准
@@ -79,123 +79,46 @@ CodexStatusService(JSON-RPC app-server)
-> CodexStatusViewModel(@MainActor 状态发布)
-> StatusItemController(菜单栏图标、popover、窗口入口)
-> CodexStatusMenuView / AppSettingsView / LogView
-```
-
-关键文件职责:
-
-- `App/CodexBarApp.swift`: `@main` 入口、空 `Settings` scene、`Bundle.displayVersionLabel`。
-- `Controllers/StatusItemController.swift`: `NSStatusItem`、`NSPopover` 状态切换、右键菜单、设置/日志窗口入口、自动刷新启动。
-- `Controllers/PopoverDismissMonitor.swift`: popover 外部点击关闭监控, 并稳定 `NSVisualEffectView` inactive 外观。
-- `Controllers/PopoverFadeCoordinator.swift`: popover 淡入淡出、alpha 重置和动画任务取消。
-- `Controllers/HostingWindowController.swift`: 设置和日志窗口的懒创建、居中、置顶和跨桌面打开行为。
-- `Controllers/SettingsWindowController.swift`: 独立设置窗口。
-- `Controllers/LogWindowController.swift`: 独立日志窗口。
-- `Services/CodexStatus/CodexStatusViewModel.swift`: `@MainActor ObservableObject`, 发布 `snapshot`、`isRefreshing`、`loadState`、`codexConnectionInfo`、`autoRefreshCountdownStartedAt`。
-- `Services/CodexStatus/CodexStatusService.swift`: app-server 连接生命周期、连接复用、认证刷新、rate limits/usage 降级和连接信息。
-- `Services/CodexStatus/AppServerSession.swift`: JSON-RPC 请求/通知、请求日志回填、业务错误重试、unsupported method 记录。
-- `Services/CodexStatus/AppServerPipeReaders.swift`: stdout 按行读取和 stderr drain, 不把子进程 stderr 展示给用户。
-- `Services/CodexStatus/RequestLog.swift`: 常驻交互日志存储, 记录请求、响应、错误和无响应请求。
-- `Services/CodexCLI/CodexCLIResolver.swift`: 解析全局 `codex` 与 `/Applications/Codex.app/Contents/Resources/codex`, 并构造真实用户环境。
-- `Services/CodexCLI/CodexCLIVersionService.swift`: 并发探测全局 CLI 与 Codex APP 内置 CLI 的磁盘版本, 合成当前运行版本和「已更新至」提示。
-- `Services/Settings/LoginItemSettings.swift`: 开机自启状态读取和注册/注销。
-- `Services/Updates/AppUpdater.swift`: Sparkle 封装, 更新状态按设置窗、popover 和可用更新拆分。
-- `Models/CodexAccountModels.swift`: account/read 响应和账号展示名。
-- `Models/CodexQuotaModels.swift`: rate limits DTO、quota 业务快照、limit/window 转换和排序。
-- `Models/CodexUsageModels.swift`: usage DTO、token summary、daily bucket 和近 30 周日期网格。
-- `Models/CodexStatusError.swift`: app-server、传输、认证和 unsupported method 错误分类。
-- `Views/Menu/CodexStatusMenuView.swift`: popover 主 UI 装配。
-- `Views/Menu/CodexStatusMenuSections.swift`: 账号卡片、状态卡片、额度区、空数据和更新时间行。
-- `Views/Menu/AutoRefreshCountdownView.swift`: 更新时间倒计时圆环和 popover 可见时的 `TimelineView` tick。
-- `Views/Menu/QuotaRow.swift`: 单个 quota window 行和分段额度条。
-- `Views/Menu/UsageHeatmap.swift` / `Views/Menu/TokenCountText.swift`: token 汇总、近 30 周热力图、hover tooltip 和 K/M/B 紧凑数字格式。
-- `Views/Settings/AppSettingsView.swift`: 设置窗口主布局、开机自启、CodexBar 版本和更新操作入口。
-- `Views/Settings/CodexVersionSection.swift`: Codex CLI/Codex APP 版本、当前使用标记、路径复制和「已更新至」提示。
-- `Views/Settings/SettingsToggleRow.swift`: 设置页通用开关行。
-- `Views/Log/LogView.swift`: 日志窗口 UI, 状态标签为「进行」「完成」「错误」「请求」。
-- `Views/Shared/LiquidGlassStyle.swift`: 自绘 Liquid Glass 视觉入口。
-
-## app-server 合约
-
-启动命令统一是:
-```bash
-codex app-server --listen stdio://
+Codex Hook
+ -> WorkflowHookEventRecorder(--hook-event)
+ -> WorkflowStatsStorage(events.jsonl / daily.jsonl)
+ -> WorkflowStatsService
+ -> WorkflowStatsViewModel
+ -> UsageSummaryView / UsageHeatmap
```
-必须通过 `CodexCLIResolver.resolveAppServerCommand()` 解析:
-
-- 优先 PATH 中的全局 `codex`。
-- 如果 PATH 中的 `codex` 等价于 `/Applications/Codex.app/Contents/Resources/codex`, 当作内置 Codex APP CLI, 不当作全局 CLI。
-- 全局 CLI 不存在时回退 Codex APP 内置 CLI。
-- 两者都不存在时返回 `CodexStatusError.executableNotFound`, UI 归为「初始化失败」, 日志记录具体错误。
-
-启动环境由 `CodexCLIResolver.environment` 构造:
-
-- 保留当前环境。
-- `HOME` 必须来自 `getpwuid(getuid())` 的真实用户 home。
-- 同步设置 `USER`、`LOGNAME`。
-- 合并 Homebrew、npm global、`.local`、Volta 和系统路径。
-- 确保 `TERM` 有值。
-- 不要改回 Xcode sandbox/container 的 `HOME`, 否则会读不到真实 `~/.codex/auth.json`。
-
-首次连接流程:
+目录职责:
-```json
-{"method":"initialize","id":1,"params":{"clientInfo":{"name":"codex_bar","title":"Codex Bar","version":"<Bundle MARKETING_VERSION 或 1.0.0>"}}}
-{"method":"initialized"}
-{"method":"account/read","id":2,"params":{"refreshToken":false}}
-```
+- `App/`: 入口和全局启动分支。
+- `Controllers/`: 菜单栏、popover、设置窗口和日志窗口控制。
+- `Models/`: account、quota、usage、workflow stats、共享日期网格和错误模型。
+- `Services/`: app-server、Codex CLI、设置、Hook 统计、更新和日志服务。
+- `Views/`: popover、设置、日志和共享 Liquid Glass 样式。
-`initialized` 是无 id 请求, 不等待响应; 日志中记录为空响应请求, 不归为通知类型。
+Hook 统计的配置、存储、保留策略和统计口径见 [Docs/CodexHook.md](Docs/CodexHook.md)。
-同一会话后续读取:
+## app-server 合约
-- `account/read` 每轮复用连接时用 `refreshToken: false` 更新账户状态。
-- `account/rateLimits/read` 读取额度。
-- `account/usage/read` 读取 `summary.lifetimeTokens`、`summary.peakDailyTokens`、`dailyUsageBuckets`。
-- 认证失败时同会话最多调用一次 `account/read`(`refreshToken: true`) 后重试原读取。
-- 所有走 `AppServerSession.request` 的方法, 收到方法不支持错误后都记录到当前会话的 `unsupportedMethods`, 本连接后续不再请求该方法。
-- 方法不支持必须是 JSON-RPC error, 且 message 包含 `Invalid request: unknown variant`。
-- 请求有 JSON-RPC error 响应, 且不是认证失败、不是方法不支持、不是传输/解析故障时, 先立即重试同一个请求一次。
-- 非认证业务错误重试后仍失败时不阻断整轮刷新, 详情只进日志。
-- `account/rateLimits/read` 和 `account/usage/read` 重试后仍失败时, 若同账号有上次成功数据则复用旧数据并标记为 stale; 没有旧数据则不展示对应区域。
-- 方法不支持不复用旧数据; 对应读取结果视为空。
-- 传输/解析故障归为需要重建连接。
+- 详细合约见 [Docs/AppServer.md](Docs/AppServer.md)。
+- 必须通过 `CodexCLIResolver.resolveAppServerCommand()` 解析, 不要绕过 resolver 直接启动。
+- app-server 环境必须使用真实用户 `HOME`、`USER`、`LOGNAME`; 不要改回 Xcode sandbox/container 的 `HOME`。
+- 保留认证失败 refresh token、unsupported method、业务错误重试、stale cache 和连接重建语义。
+- 不要把子进程 stderr、认证文件或原始敏感 RPC 响应展示给用户。
-连接细节:
+## Codex Hook 合约
-- `requestTimeout` 是 20 秒。
-- `connectionMaxAge` 是 1 小时。
-- `SIGPIPE` 已被忽略, 写入断管后应由 `write` 抛错并走重建。
-- 复用连接出现传输故障时只重建重试一次。
-- 全新连接初始化失败直接返回「初始化失败」, 不重复完整握手。
-- `initialize` 响应 `userAgent` 首个 token 形如 `codex_bar/0.139.0 (...)`; 取 `/` 后版本号作为当前运行版本。
+- 详细设计见 [Docs/CodexHook.md](Docs/CodexHook.md)。
+- 设置开关只能追加或移除 CodexBar 自己的 Hook 处理器, 不能破坏用户已有 Hook。
+- Hook 命令只支持 `--hook-event`。
+- Hook 数据只保存在 `~/Library/Application Support/CodexBar/HookEvents/`。
+- Hook 写入可能并发触发, 更新 `events.jsonl`、`daily.jsonl` 和 `maintenance.json` 时必须通过 `stats.lock` 加锁。
## UI 状态与日志
-`CodexLoadState` 只有四种:
-
-- `loading`
-- `loaded`
-- `notLoggedIn`
-- `initializationFailed`
-
-UI 只展示「未登录」和「初始化失败」两类特殊状态; 具体请求错误、启动错误、超时、断连、解析失败都进入日志。
-
-日志状态标签:
-
-- `.pending` ->「进行」
-- `.response` ->「完成」
-- `.failure` ->「错误」
-- `.emptyResponse` ->「请求」
-
-日志规则:
-
-- 带 id 的 JSON-RPC 请求先记录为进行, 响应或错误到达后回填到同一条。
-- `initialized` 这类无 id 请求记录为空响应。
-- 日志容量上限 500 条, 单条详情上限 4000 字符。
-- 合法 JSON 通过 `JSONSerialization` 重新序列化, 使用 `.sortedKeys` 和 `.withoutEscapingSlashes`; 非 JSON 错误消息保持原样。
-- 不要把子进程 stderr 直接展示给用户。
+- app-server 状态和请求日志规则见 [Docs/AppServer.md](Docs/AppServer.md)。
+- UI 只展示「未登录」和「初始化失败」两类特殊状态; 具体请求错误、启动错误、超时、断连、解析失败都进入日志。
+- 日志窗口状态标签为「进行」「完成」「错误」「请求」。
## 数据模型
@@ -214,9 +137,14 @@ UI 只展示「未登录」和「初始化失败」两类特殊状态; 具体请
`CodexUsageSnapshot`:
- `recentWeekGrid(columnCount:endingDaysAgo:today:)` 基于本地当天零点生成按周排列的日期网格, 每列从周日开始。
-- UI 使用 30 列、7 行, 默认 `endingDaysAgo = 1`, 不包含今天。
+- UI 使用 30 列、7 行; Hook 开启或 app-server 已返回当天 token bucket 时包含今天, 否则不包含今天。
- `nil` 表示未来日期或不可生成日期; 热力图不绘制方块也不参与峰值计算。
+工作流统计:
+
+- 统计口径、字段兼容和保留策略见 [Docs/CodexHook.md](Docs/CodexHook.md)。
+- UI 展示字段为「会话总数」、「对话轮次」、「子智能体」、「工具调用」、「权限请求」、「上下文压缩」。
+
## 并发与隔离
工程开启 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`; 未显式标注的类型会推断为 MainActor 隔离。
@@ -227,6 +155,8 @@ UI 只展示「未登录」和「初始化失败」两类特殊状态; 具体请
- `CodexStatusService` 使用 `CodexBar.app-server` 队列。
- `CodexCLIVersionService` 使用 `CodexBar.codex-version` 队列, 全局和内置版本探测先并发启动再收集。
- `RequestLogStore` 可从后台队列写入, storage 用锁保护, SwiftUI 通知切回主线程发送。
+- `WorkflowStatsService` 使用 `CodexBar.workflow-stats` 队列读取快照。
+- Hook 写入可能由多个 Codex 进程并发触发, 必须通过 `stats.lock` 和 `flock` 保护 `events.jsonl`、`daily.jsonl`、`maintenance.json` 的一致性。
## UI 约束
@@ -250,7 +180,11 @@ Popover:
- 更新时间行显示倒计时圆环、「数据更新时间」和 `HH:mm:ss`。
- 倒计时只在 popover 可见时用 `TimelineView` 每秒 tick; 普通 tick 不做连续动画, 仅刷新起点变化时播放恢复动画。
- token 区域显示「单日峰值」和「全时累计」; `TokenCountText` 对 1K 以下显示完整整数, 1K 起显示 K/M/B。
-- 热力图是近 30 周、30 列 x 7 行、周日到周六排列、默认不包含今天。
+- token 区域还显示「当前连胜」、「最长连胜」和「最长任务」。
+- 热力图是近 30 周、30 列 x 7 行、周日到周六排列; Codex Hook 开启时包含今天, Hook 关闭时仅在 app-server 已返回当天 token bucket 时包含今天。
+- Hook 关闭时热力图 tooltip 只显示日期和 token 数; 宽度使用 `tokenTooltipWidth`。
+- Hook 开启时热力图 tooltip 首行左侧显示日期、右侧显示 token 数, 当天 token 数显示 `--`; 后续逐行显示「会话总数」、「对话轮次」、「子智能体」、「工具调用」、「权限请求」、「上下文压缩」。
+- 工作流统计只展示在用量热力图 tooltip 中, 不再有单独的工作流统计区。
设置窗口:
@@ -262,6 +196,8 @@ Popover:
- 当前行优先展示 app-server 握手自报版本; 非当前行展示磁盘安装版本。
- 当前运行版本与磁盘安装版本不同时, 显示「已更新至 <version>」。
- 路径点击复制到剪贴板, 对应来源显示「已复制」1.5 秒; 保留路径文本布局宽度避免跳动。
+- 设置页包含「启用 Codex Hook」开关; 开启后会写入全局 Codex Hook 配置, 用于热力图展示更多本机统计数据。
+- Codex Hook 开关下方说明文案为小号辅助文字; 不展示启用/关闭状态文案, 只在失败时展示错误消息。
日志窗口:
@@ -284,6 +220,7 @@ Popover:
## 认证、隐私与沙盒
- CodexBar 只与本机 Codex app-server 通信; 账号、额度和 token 使用量不发往第三方服务。
+- Codex Hook 工作流统计只写入本机 `~/Library/Application Support/CodexBar/HookEvents/`, 不发往第三方服务。
- 除 Sparkle appcast/DMG 下载外, 应用自身不做网络请求。
- App Sandbox 必须保持关闭。
- app-server 和版本探测必须使用真实用户 home。
@@ -300,7 +237,7 @@ Popover:
- 不要主动 push。
- 不要回滚或覆盖你没做的未提交改动。
-- 提交代码的时候不要做任何额外的改动,仅对目前代码进行提交即可。
+- 提交 Git 时候**禁止**任何改动任何内容,仅对目前代码进行提交即可。
- 提交 message 使用 Conventional Commits 前缀 + 中文标题 + 空行 + 4 空格缩进 bullet body。
- 提交 body 中多条 bullet 必须连续排列, bullet 之间不要空行; 使用命令提交时, 将完整 body 放在同一个 `-m` 参数或 `git commit -F` 文件中, 不要为每条 bullet 单独使用 `-m`。
- 标题格式: `<type>: <中文描述>`, 不加句号。
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..b9ce415
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,74 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+> 本仓库已有一份详尽的 `AGENTS.md`,它是 app-server / Codex Hook / UI / 数据模型 / 发布 / Git 等各项合约的**权威来源**。本文件只做精炼导航,遇到具体行为约束请优先查 `AGENTS.md`、`Docs/AppServer.md` 与 `Docs/CodexHook.md`,不要凭记忆推断。
+
+## 构建与验证
+
+涉及 Swift/Xcode 工程、资源、build setting、Info.plist、SwiftPM、脚本或 UI 行为的改动后必须运行构建,要求无 error 和 warning:
+
+```bash
+xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination generic/platform=macOS -derivedDataPath /tmp/CodexBarDerivedData build
+```
+
+- 没有测试 target;不存在单测可跑,验证以构建通过为准。
+- `Metadata extraction skipped. No AppIntents.framework dependency found.` 是预期 warning,不算项目代码 warning。
+- SourceKit 对跨文件类型偶有误报(新建文件时尤其明显),以 `xcodebuild` 结果为准,不要据此回退正确改动。
+- 纯文档改动只需 `git diff --check`。
+- 发布脚本改动后至少 `bash -n Scripts/dmg.sh` / `bash -n Scripts/appcast.sh`。
+
+## 工程约定(影响如何改代码,非显而易见)
+
+- **App Sandbox 必须保持关闭**(`ENABLE_APP_SANDBOX = NO`):应用要启动本机 Codex CLI 并读取真实用户的 Codex 登录状态。
+- app-server 与版本探测**必须使用真实用户 `HOME`/`USER`/`LOGNAME`**,不能回退到 Xcode sandbox/container 的 home。
+- 工程使用 `PBXFileSystemSynchronizedRootGroup`:新增/删除 `CodexBar/` 下的 Swift 文件**通常无需改 `project.pbxproj`**;只有依赖、target/build settings、资源归属变更才动工程文件。仅 `Resources/Info.plist` 在同步组里被排除。
+- 源码按目录分层:`App/` `Controllers/` `Models/` `Services/` `Views/`。新文件放入对应子目录,不要丢回 `CodexBar/` 根层。
+- `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`:未标注的类型会被推断为 MainActor 隔离。UI 层保持 `@MainActor`;**DTO、模型、服务辅助类型、静态工具必须显式 `nonisolated`**,否则 main actor 隔离会泄漏进同步的服务代码。
+- 最低 macOS 15.0;不要为 15 以下添加 SF Symbols 或 SwiftUI API 的 fallback。
+
+## 架构(两条独立数据流)
+
+应用是 `LSUIElement` 菜单栏程序(无 Dock 图标、无主窗口),入口 `CodexBarApp` 在启动时先分流:若带 `--hook-event` 参数则走 `WorkflowHookEventRecorder` 记录一条 Hook 事件并立即退出,否则正常起 UI。
+
+**1. 状态/额度流**(实时数据)
+
+```
+CodexStatusService (JSON-RPC over `codex app-server --listen stdio://`)
+ → CodexStatusViewModel (@MainActor 发布 CodexLoadState / CodexQuotaSnapshot)
+ → StatusItemController (菜单栏图标、popover、设置/日志窗口入口)
+ → CodexStatusMenuView / AppSettingsView / LogView
+```
+
+- app-server 启动命令统一由 `CodexCLIResolver.resolveAppServerCommand()` 解析(优先全局 `codex`,否则回退 Codex.app 内置 CLI),**不要绕过 resolver**。
+- 握手与读取顺序、超时/重连、token 刷新、stale 缓存等约束见 `Docs/AppServer.md` 与 `AGENTS.md` 的「app-server 合约」。
+- 错误处理哲学:UI 只暴露 `notLoggedIn` / `initializationFailed` 两类特殊状态;所有具体请求/启动/超时/解析错误进 `RequestLogStore.shared`(容量 500、单条 4000 字符),不直接展示子进程 stderr。
+
+**2. Codex Hook 工作流统计流**(本机统计)
+
+```
+WorkflowHookEventRecorder (--hook-event 子进程)
+ → WorkflowStatsStorage (events.jsonl / daily.jsonl,~/Library/Application Support/CodexBar/HookEvents/)
+ → WorkflowStatsService → WorkflowStatsViewModel
+ → UsageSummaryView / UsageHeatmap (统计只在热力图 tooltip 中展示)
+```
+
+- 设置开关只能追加/移除 CodexBar 自己的 Hook 处理器,绝不破坏用户已有 Hook。
+- Hook 写入可能由多个 Codex 进程并发触发,更新 `events.jsonl`/`daily.jsonl`/`maintenance.json` 必须经 `stats.lock` + `flock` 加锁。
+- 字段兼容、保留策略、统计口径见 `Docs/CodexHook.md`。
+
+## 并发分工
+
+服务层对外暴露 async API,内部各用串行 `DispatchQueue` 管理 `Process`/`Pipe`/连接:`CodexBar.app-server`、`CodexBar.codex-version`(全局+内置版本并发探测后收集)、`CodexBar.workflow-stats`。`RequestLogStore` 可后台写入、用锁保护、通知切回主线程。
+
+## 外部依赖与更新
+
+- 唯一外部依赖:Sparkle(SwiftPM)。
+- `AppUpdater` 初始化先校验 `SUFeedURL` 与 `SUPublicEDKey`,缺失则不创建 updater 并提示「未配置更新资源」。当前 `SUFeedURL = https://codexbar.zabrian.app/appcast.xml`。
+- 发布:`Scripts/dmg.sh` 打 DMG、`Scripts/appcast.sh` 更新 `appcast.xml`(需 Sparkle `sign_update`)。tag、push、上传 DMG、改 appcast **均需用户明确同意**。
+
+## Git
+
+- 不主动 push;不回滚/覆盖非自己产生的未提交改动;提交时只提交当前代码、不附带额外改动。
+- 提交信息:Conventional Commits 前缀 + 中文标题(`<type>: <描述>`,无句号),功能/修复/发布类需写 body(空行后 4 空格缩进 bullet,bullet 间不空行,整段 body 放进同一个 `-m` 或用 `git commit -F`)。type 常用 `feat`/`fix`/`chore`/`refactor`/`docs`。
+- tag 格式 `v{MARKETING_VERSION}`,使用附注 tag。
diff --git a/CodexBar.xcodeproj/project.pbxproj b/CodexBar.xcodeproj/project.pbxproj
index 0619432..d48a3f8 100644
--- a/CodexBar.xcodeproj/project.pbxproj
+++ b/CodexBar.xcodeproj/project.pbxproj
@@ -275,7 +275,7 @@
"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";
CODE_SIGN_STYLE = Automatic;
COMBINE_HIDPI_IMAGES = YES;
- CURRENT_PROJECT_VERSION = 12;
+ CURRENT_PROJECT_VERSION = 13;
DEVELOPMENT_TEAM = 4KJ362VJW5;
ENABLE_APP_INTENTS_METADATA_GENERATION = NO;
ENABLE_APP_SANDBOX = NO;
@@ -290,7 +290,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
- MARKETING_VERSION = 2.2.0;
+ MARKETING_VERSION = 2.3.0;
PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar;
PRODUCT_NAME = "$(TARGET_NAME)";
REGISTER_APP_GROUPS = YES;
@@ -312,7 +312,7 @@
"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";
CODE_SIGN_STYLE = Automatic;
COMBINE_HIDPI_IMAGES = YES;
- CURRENT_PROJECT_VERSION = 12;
+ CURRENT_PROJECT_VERSION = 13;
DEVELOPMENT_TEAM = 4KJ362VJW5;
ENABLE_APP_INTENTS_METADATA_GENERATION = NO;
ENABLE_APP_SANDBOX = NO;
@@ -327,7 +327,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
- MARKETING_VERSION = 2.2.0;
+ MARKETING_VERSION = 2.3.0;
PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar;
PRODUCT_NAME = "$(TARGET_NAME)";
PROVISIONING_PROFILE_SPECIFIER = "";
diff --git a/CodexBar/App/CodexBarApp.swift b/CodexBar/App/CodexBarApp.swift
index f20202c..1cbc0f7 100644
--- a/CodexBar/App/CodexBarApp.swift
+++ b/CodexBar/App/CodexBarApp.swift
@@ -1,10 +1,17 @@
import AppKit
+import Darwin
import SwiftUI
@main
struct CodexBarApp: App {
@NSApplicationDelegateAdaptor(CodexBarAppDelegate.self) private var appDelegate
+ init() {
+ if WorkflowHookEventRecorder.handleIfRequested() {
+ exit(EXIT_SUCCESS)
+ }
+ }
+
var body: some Scene {
// 菜单栏 UI 由 AppDelegate 驱动; 空 Settings scene 仅用于保留系统设置入口
Settings {
diff --git a/CodexBar/Controllers/SettingsWindowController.swift b/CodexBar/Controllers/SettingsWindowController.swift
index 281fb77..74818d4 100644
--- a/CodexBar/Controllers/SettingsWindowController.swift
+++ b/CodexBar/Controllers/SettingsWindowController.swift
@@ -5,20 +5,23 @@ import SwiftUI
final class SettingsWindowController: HostingWindowController {
private let viewModel: CodexStatusViewModel
private let appUpdater: AppUpdater
+ private let codexHookSettings: CodexHookSettings
init(
viewModel: CodexStatusViewModel,
appUpdater: AppUpdater,
+ codexHookSettings: CodexHookSettings,
screenProvider: @escaping () -> NSScreen?
) {
self.viewModel = viewModel
self.appUpdater = appUpdater
+ self.codexHookSettings = codexHookSettings
super.init(screenProvider: screenProvider)
}
override func makeWindow() -> NSWindow {
let hostingController = NSHostingController(
- rootView: AppSettingsView()
+ rootView: AppSettingsView(codexHookSettings: codexHookSettings)
.environmentObject(viewModel)
.environmentObject(appUpdater)
)
diff --git a/CodexBar/Controllers/StatusItemController.swift b/CodexBar/Controllers/StatusItemController.swift
index 7461d6a..2fcce39 100644
--- a/CodexBar/Controllers/StatusItemController.swift
+++ b/CodexBar/Controllers/StatusItemController.swift
@@ -5,12 +5,19 @@ import SwiftUI
@MainActor
final class CodexBarAppDelegate: NSObject, NSApplicationDelegate {
let viewModel = CodexStatusViewModel()
+ let workflowStatsViewModel = WorkflowStatsViewModel()
+ let codexHookSettings = CodexHookSettings()
let appUpdater = AppUpdater()
private var statusItemController: StatusItemController?
func applicationDidFinishLaunching(_ notification: Notification) {
- let controller = StatusItemController(viewModel: viewModel, appUpdater: appUpdater)
+ let controller = StatusItemController(
+ viewModel: viewModel,
+ workflowStatsViewModel: workflowStatsViewModel,
+ codexHookSettings: codexHookSettings,
+ appUpdater: appUpdater
+ )
controller.install()
statusItemController = controller
}
@@ -23,6 +30,8 @@ final class CodexBarAppDelegate: NSObject, NSApplicationDelegate {
@MainActor
private final class StatusItemController: NSObject {
private let viewModel: CodexStatusViewModel
+ private let workflowStatsViewModel: WorkflowStatsViewModel
+ private let codexHookSettings: CodexHookSettings
private let appUpdater: AppUpdater
private let statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength)
private let popover = NSPopover()
@@ -30,7 +39,8 @@ private final class StatusItemController: NSObject {
private lazy var settingsWindowController = SettingsWindowController(
viewModel: viewModel,
- appUpdater: appUpdater
+ appUpdater: appUpdater,
+ codexHookSettings: codexHookSettings
) { [weak self] in
self?.statusItem.button?.window?.screen
}
@@ -49,8 +59,15 @@ private final class StatusItemController: NSObject {
private static let normalImage = makeStatusImage("person.fill.checkmark")
private static let errorImage = makeStatusImage("person.fill.xmark")
- init(viewModel: CodexStatusViewModel, appUpdater: AppUpdater) {
+ init(
+ viewModel: CodexStatusViewModel,
+ workflowStatsViewModel: WorkflowStatsViewModel,
+ codexHookSettings: CodexHookSettings,
+ appUpdater: AppUpdater
+ ) {
self.viewModel = viewModel
+ self.workflowStatsViewModel = workflowStatsViewModel
+ self.codexHookSettings = codexHookSettings
self.appUpdater = appUpdater
super.init()
}
@@ -96,6 +113,8 @@ private final class StatusItemController: NSObject {
private func configurePopover() {
let rootView = CodexStatusMenuView(
viewModel: viewModel,
+ workflowStatsViewModel: workflowStatsViewModel,
+ codexHookSettings: codexHookSettings,
popoverVisibility: popoverVisibility
)
.environmentObject(appUpdater)
@@ -119,6 +138,16 @@ private final class StatusItemController: NSObject {
self?.updateStatusImage(usesErrorImage: usesErrorImage)
}
.store(in: &cancellables)
+
+ viewModel.$autoRefreshCountdownStartedAt
+ .compactMap { $0 }
+ .sink { [weak self] _ in
+ guard let self, self.popover.isShown else {
+ return
+ }
+ self.refreshWorkflowStatsIfHookEnabled()
+ }
+ .store(in: &cancellables)
}
private func updateStatusImage() {
@@ -173,6 +202,7 @@ private final class StatusItemController: NSObject {
popoverFadeCoordinator.prepareForFadeIn()
popover.show(relativeTo: button.bounds, of: button, preferredEdge: .minY)
popoverVisibility.isVisible = true
+ refreshWorkflowStatsIfHookEnabled()
popoverDismissMonitor.install { [weak self] in
self?.closePopover()
}
@@ -292,6 +322,13 @@ private final class StatusItemController: NSObject {
}
}
+ private func refreshWorkflowStatsIfHookEnabled() {
+ codexHookSettings.refresh()
+ if codexHookSettings.isEnabled {
+ workflowStatsViewModel.refreshIfNeeded()
+ }
+ }
+
private enum Metrics {
static let fadeInDuration: TimeInterval = 0.24
static let fadeOutDuration: TimeInterval = 0.18
diff --git a/CodexBar/Models/CodexUsageModels.swift b/CodexBar/Models/CodexUsageModels.swift
index e7b3653..1b3a455 100644
--- a/CodexBar/Models/CodexUsageModels.swift
+++ b/CodexBar/Models/CodexUsageModels.swift
@@ -24,62 +24,33 @@ nonisolated struct CodexUsageSnapshot: Equatable {
let summary: UsageSummary
let dailyBuckets: [DailyUsageBucket]
+ func tokenCount(on date: Date) -> Int? {
+ let startDate = DateFormatter.codexDay.string(from: date)
+ return tokensByDate[startDate]
+ }
+
// 给热力图生成按周排列的最近日期网格, 每列从周日开始
func recentWeekGrid(columnCount: Int, endingDaysAgo: Int = 0, today: Date = Date()) -> [DailyUsageBucket?] {
- guard columnCount > 0 else {
- return []
- }
-
- let calendar = Calendar.current
- let todayStart = calendar.startOfDay(for: today)
- let lastVisibleDate = calendar.date(
- byAdding: .day,
- value: -max(endingDaysAgo, 0),
- to: todayStart
- ) ?? todayStart
- let currentWeekStart = Self.sundayStartOfWeek(containing: lastVisibleDate, calendar: calendar)
- guard let firstWeekStart = calendar.date(
- byAdding: .weekOfYear,
- value: -(columnCount - 1),
- to: currentWeekStart
- ) else {
- return []
- }
-
- let tokensByDate = dailyBuckets.reduce(into: [String: Int]()) { result, bucket in
- result[bucket.startDate, default: 0] += bucket.tokens
- }
-
- return (0..<columnCount).flatMap { column -> [DailyUsageBucket?] in
- guard let weekStart = calendar.date(byAdding: .weekOfYear, value: column, to: firstWeekStart) else {
- return Array(repeating: nil, count: 7)
- }
-
- return (0..<7).map { weekdayOffset -> DailyUsageBucket? in
- guard let date = calendar.date(byAdding: .day, value: weekdayOffset, to: weekStart) else {
- return nil
- }
-
- guard date <= lastVisibleDate else {
- return nil
- }
-
- let startDate = Self.dayFormatter.string(from: date)
- return DailyUsageBucket(startDate: startDate, tokens: tokensByDate[startDate] ?? 0)
+ let tokenCountsByDate = tokensByDate
+ return CodexWeekGrid.dates(
+ columnCount: columnCount,
+ endingDaysAgo: endingDaysAgo,
+ today: today
+ )
+ .map { date in
+ date.map {
+ let startDate = DateFormatter.codexDay.string(from: $0)
+ return DailyUsageBucket(
+ startDate: startDate,
+ tokens: tokenCountsByDate[startDate] ?? 0
+ )
}
}
}
- private static func sundayStartOfWeek(containing date: Date, calendar: Calendar) -> Date {
- let weekday = calendar.component(.weekday, from: date)
- let daysSinceSunday = weekday - 1
- return calendar.date(byAdding: .day, value: -daysSinceSunday, to: date) ?? date
+ private var tokensByDate: [String: Int] {
+ dailyBuckets.reduce(into: [String: Int]()) { result, bucket in
+ result[bucket.startDate, default: 0] += bucket.tokens
+ }
}
-
- private nonisolated static let dayFormatter: DateFormatter = {
- let formatter = DateFormatter()
- formatter.locale = Locale(identifier: "en_US_POSIX")
- formatter.dateFormat = "yyyy-MM-dd"
- return formatter
- }()
}
diff --git a/CodexBar/Models/CodexWeekGrid.swift b/CodexBar/Models/CodexWeekGrid.swift
new file mode 100644
index 0000000..3fa2a4b
--- /dev/null
+++ b/CodexBar/Models/CodexWeekGrid.swift
@@ -0,0 +1,52 @@
+import Foundation
+
+nonisolated enum CodexWeekGrid {
+ static let rowCount = 7
+
+ static func dates(
+ columnCount: Int,
+ endingDaysAgo: Int = 0,
+ today: Date = Date(),
+ calendar: Calendar = .current
+ ) -> [Date?] {
+ guard columnCount > 0 else {
+ return []
+ }
+
+ let todayStart = calendar.startOfDay(for: today)
+ let lastVisibleDate = calendar.date(
+ byAdding: .day,
+ value: -max(endingDaysAgo, 0),
+ to: todayStart
+ ) ?? todayStart
+ let currentWeekStart = sundayStartOfWeek(containing: lastVisibleDate, calendar: calendar)
+ guard let firstWeekStart = calendar.date(
+ byAdding: .weekOfYear,
+ value: -(columnCount - 1),
+ to: currentWeekStart
+ ) else {
+ return []
+ }
+
+ return (0..<columnCount).flatMap { column -> [Date?] in
+ guard let weekStart = calendar.date(byAdding: .weekOfYear, value: column, to: firstWeekStart) else {
+ return Array(repeating: nil, count: rowCount)
+ }
+
+ return (0..<rowCount).map { weekdayOffset -> Date? in
+ guard let date = calendar.date(byAdding: .day, value: weekdayOffset, to: weekStart),
+ date <= lastVisibleDate else {
+ return nil
+ }
+
+ return date
+ }
+ }
+ }
+
+ private static func sundayStartOfWeek(containing date: Date, calendar: Calendar) -> Date {
+ let weekday = calendar.component(.weekday, from: date)
+ let daysSinceSunday = weekday - 1
+ return calendar.date(byAdding: .day, value: -daysSinceSunday, to: date) ?? date
+ }
+}
diff --git a/CodexBar/Models/CodexWorkflowStatsModels.swift b/CodexBar/Models/CodexWorkflowStatsModels.swift
new file mode 100644
index 0000000..498e138
--- /dev/null
+++ b/CodexBar/Models/CodexWorkflowStatsModels.swift
@@ -0,0 +1,484 @@
+import Foundation
+
+// Hook 事件类型: 由归一化后的事件名 (去除 _/-、小写) 映射, 是名称到聚合计数的唯一映射来源
+nonisolated enum WorkflowEventKind: String {
+ case sessionStart = "sessionstart"
+ case stop = "stop"
+ case preToolUse = "pretooluse"
+ case postToolUse = "posttooluse"
+ case permissionRequest = "permissionrequest"
+ case preCompact = "precompact"
+ case postCompact = "postcompact"
+ case subagentStart = "subagentstart"
+ case subagentStop = "subagentstop"
+
+ init?(normalizedName: String) {
+ self.init(rawValue: normalizedName)
+ }
+}
+
+nonisolated struct WorkflowHookEvent: Decodable, Equatable {
+ let occurredAt: Date
+ let name: String
+ let directoryPath: String?
+ let toolName: String?
+ let modelName: String?
+ let permissionMode: String?
+ let sessionId: String?
+ let turnId: String?
+
+ init(
+ occurredAt: Date,
+ name: String,
+ directoryPath: String?,
+ toolName: String?,
+ modelName: String?,
+ permissionMode: String?,
+ sessionId: String?,
+ turnId: String?
+ ) {
+ self.occurredAt = occurredAt
+ self.name = name
+ self.directoryPath = directoryPath
+ self.toolName = toolName
+ self.modelName = modelName
+ self.permissionMode = permissionMode
+ self.sessionId = sessionId
+ self.turnId = turnId
+ }
+
+ init(from decoder: Decoder) throws {
+ let container = try decoder.container(keyedBy: CodingKeys.self)
+ guard let timestamp = Self.string(from: container, key: .timestamp),
+ let occurredAt = Self.date(from: timestamp) else {
+ throw DecodingError.dataCorrupted(
+ .init(codingPath: decoder.codingPath, debugDescription: "Missing or invalid hook event timestamp")
+ )
+ }
+ guard let name = Self.string(from: container, key: .event) else {
+ throw DecodingError.dataCorrupted(
+ .init(codingPath: decoder.codingPath, debugDescription: "Missing hook event name")
+ )
+ }
+
+ self.occurredAt = occurredAt
+ self.name = name
+ self.directoryPath = Self.string(from: container, key: .cwd)
+ self.toolName = Self.string(from: container, key: .toolName)
+ self.modelName = Self.string(from: container, key: .modelName)
+ self.permissionMode = Self.string(from: container, key: .permissionMode)
+ self.sessionId = Self.string(from: container, key: .sessionId)
+ self.turnId = Self.string(from: container, key: .turnId)
+ }
+
+ var kind: WorkflowEventKind? {
+ WorkflowEventKind(normalizedName: normalizedName)
+ }
+
+ var projectDisplayName: String? {
+ guard let directoryPath, !directoryPath.isEmpty else {
+ return nil
+ }
+
+ let url = URL(fileURLWithPath: directoryPath).standardizedFileURL
+ let lastComponent = url.lastPathComponent
+ return lastComponent.isEmpty ? directoryPath : lastComponent
+ }
+
+ private var normalizedName: String {
+ name
+ .replacingOccurrences(of: "_", with: "")
+ .replacingOccurrences(of: "-", with: "")
+ .lowercased()
+ }
+
+ private static func string(
+ from container: KeyedDecodingContainer<CodingKeys>,
+ key: CodingKeys
+ ) -> String? {
+ if let value = try? container.decode(String.self, forKey: key) {
+ let trimmedValue = value.trimmingCharacters(in: .whitespacesAndNewlines)
+ if !trimmedValue.isEmpty {
+ return trimmedValue
+ }
+ }
+
+ return nil
+ }
+
+ private static func date(from string: String) -> Date? {
+ if let date = ISO8601DateFormatter.codexFractional.date(from: string) {
+ return date
+ }
+
+ if let date = iso8601Formatter.date(from: string) {
+ return date
+ }
+
+ return nil
+ }
+
+ static func decodeJSONLines(from data: Data) -> [WorkflowHookEvent] {
+ JSONLines.decode(from: data)
+ }
+
+ static func decodeJSONLinesWithFailures(from data: Data) -> JSONLinesDecodeResult<WorkflowHookEvent> {
+ JSONLines.decodeWithFailures(from: data)
+ }
+
+ func jsonLineData() throws -> Data {
+ let fields = [
+ "\"timestamp\":\(try Self.jsonValue(ISO8601DateFormatter.codexFractional.string(from: occurredAt)))",
+ "\"event\":\(try Self.jsonValue(name))",
+ "\"model\":\(try Self.jsonValue(modelName))",
+ "\"permission\":\(try Self.jsonValue(permissionMode))",
+ "\"session\":\(try Self.jsonValue(sessionId))",
+ "\"turn\":\(try Self.jsonValue(turnId))",
+ "\"cwd\":\(try Self.jsonValue(directoryPath))",
+ "\"tool\":\(try Self.jsonValue(toolName))"
+ ]
+ let json = "{\(fields.joined(separator: ","))}"
+
+ return Data(json.utf8) + Data([0x0A])
+ }
+
+ private static func jsonValue(_ value: String?) throws -> String {
+ guard let value else {
+ return "null"
+ }
+
+ return try jsonValue(value)
+ }
+
+ private static func jsonValue(_ value: String) throws -> String {
+ let encoder = JSONEncoder()
+ encoder.outputFormatting = [.withoutEscapingSlashes]
+ let data = try encoder.encode(value)
+ return String(decoding: data, as: UTF8.self)
+ }
+
+ private static let iso8601Formatter: ISO8601DateFormatter = {
+ let formatter = ISO8601DateFormatter()
+ formatter.formatOptions = [.withInternetDateTime]
+ return formatter
+ }()
+
+ private enum CodingKeys: String, CodingKey {
+ case timestamp
+ case event
+ case cwd
+ case toolName = "tool"
+ case modelName = "model"
+ case permissionMode = "permission"
+ case sessionId = "session"
+ case turnId = "turn"
+ }
+}
+
+nonisolated struct WorkflowDailyStats: Equatable, Identifiable {
+ let startDate: String
+ let sessionCount: Int
+ let turnCount: Int
+ let toolCallCount: Int
+ let permissionRequestCount: Int
+ let mostActiveProject: String?
+ let contextCompactionCount: Int
+ let subagentCount: Int
+ let eventCount: Int
+
+ var id: String { startDate }
+
+ static func empty(startDate: String) -> WorkflowDailyStats {
+ WorkflowDailyStats(
+ startDate: startDate,
+ sessionCount: 0,
+ turnCount: 0,
+ toolCallCount: 0,
+ permissionRequestCount: 0,
+ mostActiveProject: nil,
+ contextCompactionCount: 0,
+ subagentCount: 0,
+ eventCount: 0
+ )
+ }
+}
+
+nonisolated struct WorkflowStatsSnapshot: Equatable {
+ let generatedAt: Date
+ let dailyStats: [WorkflowDailyStats]
+
+ static let empty = WorkflowStatsSnapshot(generatedAt: Date(), dailyStats: [])
+
+ init(generatedAt: Date = Date(), dailyStats: [WorkflowDailyStats]) {
+ self.generatedAt = generatedAt
+ self.dailyStats = dailyStats
+ }
+
+ init(dailyAggregates: [WorkflowDailyAggregate], generatedAt: Date = Date()) {
+ self.generatedAt = generatedAt
+ self.dailyStats = dailyAggregates
+ .map(\.stats)
+ .sorted { $0.startDate < $1.startDate }
+ }
+
+ init(events: [WorkflowHookEvent], generatedAt: Date = Date()) {
+ self.init(
+ dailyAggregates: WorkflowDailyAggregate.aggregates(from: events),
+ generatedAt: generatedAt
+ )
+ }
+
+ func recentWeekGrid(columnCount: Int, endingDaysAgo: Int = 0, today: Date = Date()) -> [WorkflowDailyStats?] {
+ let statsByDate = dailyStats.reduce(into: [String: WorkflowDailyStats]()) { result, stats in
+ result[stats.startDate] = stats
+ }
+
+ return CodexWeekGrid.dates(
+ columnCount: columnCount,
+ endingDaysAgo: endingDaysAgo,
+ today: today
+ )
+ .map { date in
+ date.map {
+ let startDate = DateFormatter.codexDay.string(from: $0)
+ return statsByDate[startDate] ?? WorkflowDailyStats.empty(startDate: startDate)
+ }
+ }
+ }
+}
+
+nonisolated struct WorkflowDailyAggregate: Codable, Equatable, Identifiable {
+ let date: String
+ var eventCount: Int
+ var sessionStartCount: Int
+ var stopCount: Int
+ var preToolUseCount: Int
+ var postToolUseCount: Int
+ var permissionRequestCount: Int
+ var preCompactCount: Int
+ var postCompactCount: Int
+ var subagentStartCount: Int
+ var subagentStopCount: Int
+ var sessionIds: [String]?
+ var turnIds: [String]?
+ var sessionCount: Int?
+ var turnCount: Int?
+ var projectCounts: [String: Int]
+
+ var id: String { date }
+
+ init(date: String) {
+ self.date = date
+ self.eventCount = 0
+ self.sessionStartCount = 0
+ self.stopCount = 0
+ self.preToolUseCount = 0
+ self.postToolUseCount = 0
+ self.permissionRequestCount = 0
+ self.preCompactCount = 0
+ self.postCompactCount = 0
+ self.subagentStartCount = 0
+ self.subagentStopCount = 0
+ self.sessionIds = []
+ self.turnIds = []
+ self.sessionCount = nil
+ self.turnCount = nil
+ self.projectCounts = [:]
+ }
+
+ init(from decoder: Decoder) throws {
+ let container = try decoder.container(keyedBy: CodingKeys.self)
+ self.date = try container.decode(String.self, forKey: .date)
+ self.eventCount = try container.decodeIfPresent(Int.self, forKey: .eventCount) ?? 0
+ self.sessionStartCount = try container.decodeIfPresent(Int.self, forKey: .sessionStartCount) ?? 0
+ self.stopCount = try container.decodeIfPresent(Int.self, forKey: .stopCount) ?? 0
+ self.preToolUseCount = try container.decodeIfPresent(Int.self, forKey: .preToolUseCount) ?? 0
+ self.postToolUseCount = try container.decodeIfPresent(Int.self, forKey: .postToolUseCount) ?? 0
+ self.permissionRequestCount = try container.decodeIfPresent(Int.self, forKey: .permissionRequestCount) ?? 0
+ self.preCompactCount = try container.decodeIfPresent(Int.self, forKey: .preCompactCount) ?? 0
+ self.postCompactCount = try container.decodeIfPresent(Int.self, forKey: .postCompactCount) ?? 0
+ self.subagentStartCount = try container.decodeIfPresent(Int.self, forKey: .subagentStartCount) ?? 0
+ self.subagentStopCount = try container.decodeIfPresent(Int.self, forKey: .subagentStopCount) ?? 0
+ self.sessionIds = try container.decodeIfPresent([String].self, forKey: .sessionIds)
+ self.turnIds = try container.decodeIfPresent([String].self, forKey: .turnIds)
+ self.sessionCount = try container.decodeIfPresent(Int.self, forKey: .sessionCount)
+ self.turnCount = try container.decodeIfPresent(Int.self, forKey: .turnCount)
+ self.projectCounts = try container.decodeIfPresent([String: Int].self, forKey: .projectCounts) ?? [:]
+ }
+
+ mutating func record(_ event: WorkflowHookEvent, keepsIdentifiers: Bool) {
+ eventCount += 1
+
+ switch event.kind {
+ case .sessionStart: sessionStartCount += 1
+ case .stop: stopCount += 1
+ case .preToolUse: preToolUseCount += 1
+ case .postToolUse: postToolUseCount += 1
+ case .permissionRequest: permissionRequestCount += 1
+ case .preCompact: preCompactCount += 1
+ case .postCompact: postCompactCount += 1
+ case .subagentStart: subagentStartCount += 1
+ case .subagentStop: subagentStopCount += 1
+ case .none: break
+ }
+
+ if keepsIdentifiers {
+ if let sessionId = event.sessionId {
+ sessionIds = Self.inserting(sessionId, into: sessionIds)
+ }
+
+ if let turnId = event.turnId {
+ turnIds = Self.inserting(turnId, into: turnIds)
+ }
+ }
+
+ if let projectDisplayName = event.projectDisplayName {
+ projectCounts[projectDisplayName, default: 0] += 1
+ }
+ }
+
+ mutating func compactIdentifiersIfNeeded(keepsIdentifiers: Bool) {
+ guard !keepsIdentifiers else {
+ sessionIds = sessionIds ?? []
+ turnIds = turnIds ?? []
+ return
+ }
+
+ sessionCount = resolvedSessionCount
+ turnCount = resolvedTurnCount
+ sessionIds = nil
+ turnIds = nil
+ }
+
+ // 会话/轮次最终值: 在 id 集合、已压缩计数、起止事件计数之间取最大, 三处来源互为兜底
+ private var resolvedSessionCount: Int {
+ max(sessionCount ?? 0, sessionIds?.count ?? 0, sessionStartCount)
+ }
+
+ private var resolvedTurnCount: Int {
+ max(turnCount ?? 0, turnIds?.count ?? 0, stopCount)
+ }
+
+ var stats: WorkflowDailyStats {
+ let sessionTotal = resolvedSessionCount
+ let turnTotal = resolvedTurnCount
+ let toolCallCount = max(preToolUseCount, postToolUseCount)
+ let contextCompactionCount = max(preCompactCount, postCompactCount)
+ let subagentCount = max(subagentStartCount, subagentStopCount)
+
+ return WorkflowDailyStats(
+ startDate: date,
+ sessionCount: sessionTotal,
+ turnCount: turnTotal,
+ toolCallCount: toolCallCount,
+ permissionRequestCount: permissionRequestCount,
+ mostActiveProject: mostActiveProject,
+ contextCompactionCount: contextCompactionCount,
+ subagentCount: subagentCount,
+ eventCount: eventCount
+ )
+ }
+
+ static func aggregates(
+ from events: [WorkflowHookEvent],
+ today: Date = Date(),
+ calendar: Calendar = .current
+ ) -> [WorkflowDailyAggregate] {
+ let retentionCutoffDate = WorkflowStatsStorage.retentionCutoffDate(today: today, calendar: calendar)
+ let identifierCutoffDate = WorkflowStatsStorage.identifierRetentionCutoffDate(today: today, calendar: calendar)
+
+ let aggregates = events.reduce(into: [String: WorkflowDailyAggregate]()) { result, event in
+ let eventStartDate = calendar.startOfDay(for: event.occurredAt)
+ guard eventStartDate >= retentionCutoffDate else {
+ return
+ }
+
+ let startDate = DateFormatter.codexDay.string(from: eventStartDate)
+ result[startDate, default: WorkflowDailyAggregate(date: startDate)]
+ .record(event, keepsIdentifiers: eventStartDate >= identifierCutoffDate)
+ }
+
+ return normalized(
+ aggregates: Array(aggregates.values),
+ today: today,
+ calendar: calendar
+ )
+ }
+
+ static func normalized(
+ aggregates: [WorkflowDailyAggregate],
+ today: Date = Date(),
+ calendar: Calendar = .current
+ ) -> [WorkflowDailyAggregate] {
+ let retentionCutoffDate = WorkflowStatsStorage.retentionCutoffDate(today: today, calendar: calendar)
+ let identifierCutoffDate = WorkflowStatsStorage.identifierRetentionCutoffDate(today: today, calendar: calendar)
+
+ return aggregates.compactMap { aggregate in
+ guard let date = Self.date(from: aggregate.date), date >= retentionCutoffDate else {
+ return nil
+ }
+
+ var mutableAggregate = aggregate
+ mutableAggregate.compactIdentifiersIfNeeded(keepsIdentifiers: date >= identifierCutoffDate)
+ return mutableAggregate
+ }
+ .sorted { $0.date < $1.date }
+ }
+
+ static func decodeJSONLines(from data: Data) -> [WorkflowDailyAggregate] {
+ JSONLines.decode(from: data)
+ }
+
+ static func encodeJSONLines(_ aggregates: [WorkflowDailyAggregate]) throws -> Data {
+ let encoder = JSONEncoder()
+ encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]
+
+ return try aggregates.reduce(into: Data()) { result, aggregate in
+ let lineData = try encoder.encode(aggregate)
+ result.append(lineData)
+ result.append(0x0A)
+ }
+ }
+
+ private static func inserting(_ identifier: String, into identifiers: [String]?) -> [String] {
+ var identifierSet = Set(identifiers ?? [])
+ identifierSet.insert(identifier)
+ return identifierSet.sorted()
+ }
+
+ private var mostActiveProject: String? {
+ projectCounts
+ .sorted { lhs, rhs in
+ if lhs.value != rhs.value {
+ return lhs.value > rhs.value
+ }
+
+ return lhs.key.localizedStandardCompare(rhs.key) == .orderedAscending
+ }
+ .first?
+ .key
+ }
+
+ private static func date(from string: String) -> Date? {
+ DateFormatter.codexDay.date(from: string)
+ }
+
+ private enum CodingKeys: String, CodingKey {
+ case date
+ case eventCount
+ case sessionStartCount
+ case stopCount
+ case preToolUseCount
+ case postToolUseCount
+ case permissionRequestCount
+ case preCompactCount
+ case postCompactCount
+ case subagentStartCount
+ case subagentStopCount
+ case sessionIds
+ case turnIds
+ case sessionCount
+ case turnCount
+ case projectCounts
+ }
+}
diff --git a/CodexBar/Models/DateFormatter.swift b/CodexBar/Models/DateFormatter.swift
new file mode 100644
index 0000000..5d0d019
--- /dev/null
+++ b/CodexBar/Models/DateFormatter.swift
@@ -0,0 +1,20 @@
+import Foundation
+
+extension DateFormatter {
+ // yyyy-MM-dd, 作为热力图与按日聚合统一的稳定日期键
+ nonisolated static let codexDay: DateFormatter = {
+ let formatter = DateFormatter()
+ formatter.locale = Locale(identifier: "en_US_POSIX")
+ formatter.dateFormat = "yyyy-MM-dd"
+ return formatter
+ }()
+}
+
+extension ISO8601DateFormatter {
+ // 带小数秒的 ISO8601, Hook 事件时间戳的统一读写格式
+ nonisolated static let codexFractional: ISO8601DateFormatter = {
+ let formatter = ISO8601DateFormatter()
+ formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+ return formatter
+ }()
+}
diff --git a/CodexBar/Models/UsageHeatmapDay.swift b/CodexBar/Models/UsageHeatmapDay.swift
new file mode 100644
index 0000000..b4a255e
--- /dev/null
+++ b/CodexBar/Models/UsageHeatmapDay.swift
@@ -0,0 +1,60 @@
+import Foundation
+
+nonisolated struct UsageHeatmapDay: Equatable, Identifiable {
+ let startDate: String
+ let tokenCount: Int?
+ let workflowStats: WorkflowDailyStats
+
+ var id: String { startDate }
+
+ var tokensForHeatmap: Int {
+ tokenCount ?? 0
+ }
+
+ static func grid(
+ usage: CodexUsageSnapshot,
+ workflowStats: WorkflowStatsSnapshot,
+ showsWorkflowStats: Bool,
+ columnCount: Int,
+ today: Date
+ ) -> [UsageHeatmapDay?] {
+ let todayTokenCount = usage.tokenCount(on: today)
+ let endingDaysAgo = showsWorkflowStats || todayTokenCount != nil ? 0 : 1
+ let tokenDays = usage.recentWeekGrid(
+ columnCount: columnCount,
+ endingDaysAgo: endingDaysAgo,
+ today: today
+ )
+ let workflowDays = workflowStats.recentWeekGrid(
+ columnCount: columnCount,
+ endingDaysAgo: endingDaysAgo,
+ today: today
+ )
+
+ return merge(
+ tokenDays: tokenDays,
+ workflowDays: workflowDays,
+ todayString: DateFormatter.codexDay.string(from: today),
+ todayTokenCount: todayTokenCount
+ )
+ }
+
+ private static func merge(
+ tokenDays: [DailyUsageBucket?],
+ workflowDays: [WorkflowDailyStats?],
+ todayString: String,
+ todayTokenCount: Int?
+ ) -> [UsageHeatmapDay?] {
+ zip(tokenDays, workflowDays).map { tokenDay, workflowDay in
+ guard let startDate = tokenDay?.startDate ?? workflowDay?.startDate else {
+ return nil
+ }
+
+ return UsageHeatmapDay(
+ startDate: startDate,
+ tokenCount: startDate == todayString ? todayTokenCount : tokenDay?.tokens ?? 0,
+ workflowStats: workflowDay ?? .empty(startDate: startDate)
+ )
+ }
+ }
+}
diff --git a/CodexBar/Services/CodexCLI/CodexCLIVersionService.swift b/CodexBar/Services/CodexCLI/CodexCLIVersionService.swift
index 9a8fb64..aaf5671 100644
--- a/CodexBar/Services/CodexCLI/CodexCLIVersionService.swift
+++ b/CodexBar/Services/CodexCLI/CodexCLIVersionService.swift
@@ -65,12 +65,37 @@ nonisolated struct CodexCLIVersionDisplay: Equatable {
self.displayVersion = version ?? item.displayVersion
self.path = (isCurrent ? connection?.executablePath : nil) ?? item.path
- if let runningVersion, let installed = item.version, installed != runningVersion {
+ if let runningVersion,
+ let installed = item.version,
+ Self.isInstalledVersionNewer(installed, than: runningVersion) {
self.newerInstalledVersion = installed
} else {
self.newerInstalledVersion = nil
}
}
+
+ private static func isInstalledVersionNewer(
+ _ installedVersion: String,
+ than runningVersion: String
+ ) -> Bool {
+ guard let installedComponents = normalizedVersionComponents(from: installedVersion),
+ let runningComponents = normalizedVersionComponents(from: runningVersion) else {
+ return false
+ }
+
+ return runningComponents.lexicographicallyPrecedes(installedComponents)
+ }
+
+ private static func normalizedVersionComponents(from version: String) -> [Int]? {
+ let components = version
+ .components(separatedBy: CharacterSet.decimalDigits.inverted)
+ .compactMap { $0.isEmpty ? nil : Int($0) }
+ guard !components.isEmpty else {
+ return nil
+ }
+
+ return Array(components.reversed().drop(while: { $0 == 0 }).reversed())
+ }
}
nonisolated final class CodexCLIVersionService: @unchecked Sendable {
diff --git a/CodexBar/Services/Settings/CodexHookSettings.swift b/CodexBar/Services/Settings/CodexHookSettings.swift
new file mode 100644
index 0000000..68e77e0
--- /dev/null
+++ b/CodexBar/Services/Settings/CodexHookSettings.swift
@@ -0,0 +1,278 @@
+import Combine
+import Foundation
+
+@MainActor
+final class CodexHookSettings: ObservableObject {
+ @Published private(set) var isEnabled = false
+ @Published private(set) var errorMessage: String?
+
+ private let hooksURL: URL
+ private let fileManager: FileManager
+
+ init(
+ hooksURL: URL = CodexHookSettings.defaultHooksURL(),
+ fileManager: FileManager = .default
+ ) {
+ self.hooksURL = hooksURL
+ self.fileManager = fileManager
+ }
+
+ func refresh() {
+ do {
+ let config = try readConfigIfPresent()
+ isEnabled = Self.containsCodexBarHooks(
+ in: config,
+ executablePath: currentExecutablePath
+ )
+ errorMessage = nil
+ } catch {
+ isEnabled = false
+ errorMessage = "读取 Codex Hook 配置失败: \(error.localizedDescription)"
+ }
+ }
+
+ func setEnabled(_ enabled: Bool) {
+ errorMessage = nil
+
+ do {
+ var config = try readConfigIfPresent()
+ try Self.removeCodexBarHooks(from: &config)
+
+ if enabled {
+ try Self.installCodexBarHooks(
+ in: &config,
+ executablePath: currentExecutablePath
+ )
+ }
+
+ try write(config)
+ isEnabled = enabled
+ } catch {
+ refresh()
+ errorMessage = "设置 Codex Hook 失败: \(error.localizedDescription)"
+ }
+ }
+}
+
+private extension CodexHookSettings {
+ typealias JSONObject = [String: Any]
+ typealias JSONArray = [Any]
+
+ enum HookConfigError: LocalizedError {
+ case invalidRoot
+ case invalidHooks
+ case invalidEvent(String)
+
+ var errorDescription: String? {
+ switch self {
+ case .invalidRoot:
+ return "hooks.json 顶层必须是 JSON 对象"
+ case .invalidHooks:
+ return "hooks 字段必须是 JSON 对象"
+ case .invalidEvent(let event):
+ return "\(event) 配置必须是数组"
+ }
+ }
+ }
+
+ static let codexBarEvents = [
+ "SessionStart",
+ "UserPromptSubmit",
+ "PreToolUse",
+ "PostToolUse",
+ "PermissionRequest",
+ "PreCompact",
+ "PostCompact",
+ "Stop",
+ "SubagentStart",
+ "SubagentStop"
+ ]
+
+ nonisolated static func defaultHooksURL() -> URL {
+ FileManager.default
+ .homeDirectoryForCurrentUser
+ .appendingPathComponent(".codex", isDirectory: true)
+ .appendingPathComponent("hooks.json")
+ }
+
+ var currentExecutablePath: String {
+ Bundle.main.executableURL?.path
+ ?? CommandLine.arguments.first
+ ?? "/Applications/CodexBar.app/Contents/MacOS/CodexBar"
+ }
+
+ func readConfigIfPresent() throws -> JSONObject {
+ guard fileManager.fileExists(atPath: hooksURL.path) else {
+ return [:]
+ }
+
+ return try readConfig()
+ }
+
+ func readConfig() throws -> JSONObject {
+ let data = try Data(contentsOf: hooksURL)
+ guard !data.isEmpty else {
+ return [:]
+ }
+
+ let object = try JSONSerialization.jsonObject(with: data)
+ guard let config = object as? JSONObject else {
+ throw HookConfigError.invalidRoot
+ }
+
+ return config
+ }
+
+ func write(_ config: JSONObject) throws {
+ try fileManager.createDirectory(
+ at: hooksURL.deletingLastPathComponent(),
+ withIntermediateDirectories: true
+ )
+
+ let data = try JSONSerialization.data(
+ withJSONObject: config,
+ options: [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes]
+ )
+ try data.write(to: hooksURL, options: .atomic)
+ }
+
+ static func containsCodexBarHooks(in config: JSONObject, executablePath: String) -> Bool {
+ guard let hooks = config["hooks"] as? JSONObject else {
+ return false
+ }
+
+ return codexBarEvents.allSatisfy { event in
+ guard let groups = hooks[event] as? JSONArray else {
+ return false
+ }
+
+ return groups.contains { group in
+ guard let group = group as? JSONObject,
+ let handlers = group["hooks"] as? JSONArray else {
+ return false
+ }
+
+ return handlers.contains {
+ isCurrentCodexBarHandler($0, event: event, executablePath: executablePath)
+ }
+ }
+ }
+ }
+
+ static func installCodexBarHooks(in config: inout JSONObject, executablePath: String) throws {
+ var hooks = try hooksObject(from: config)
+
+ for event in codexBarEvents {
+ var groups = try eventGroups(named: event, from: hooks)
+ groups.append([
+ "hooks": [
+ [
+ "type": "command",
+ "command": hookCommand(for: event, executablePath: executablePath),
+ "timeout": 5
+ ]
+ ]
+ ])
+ hooks[event] = groups
+ }
+
+ config["hooks"] = hooks
+ }
+
+ static func removeCodexBarHooks(from config: inout JSONObject) throws {
+ guard config["hooks"] != nil else {
+ return
+ }
+
+ var hooks = try hooksObject(from: config)
+
+ for (event, value) in hooks {
+ guard let groups = value as? JSONArray else {
+ throw HookConfigError.invalidEvent(event)
+ }
+
+ let filteredGroups = groups.compactMap { group -> Any? in
+ guard var groupObject = group as? JSONObject,
+ let handlers = groupObject["hooks"] as? JSONArray else {
+ return group
+ }
+
+ let filteredHandlers = handlers.filter { !isCodexBarHandler($0) }
+ guard !filteredHandlers.isEmpty else {
+ return nil
+ }
+
+ groupObject["hooks"] = filteredHandlers
+ return groupObject
+ }
+
+ if filteredGroups.isEmpty {
+ hooks.removeValue(forKey: event)
+ } else {
+ hooks[event] = filteredGroups
+ }
+ }
+
+ config["hooks"] = hooks
+ }
+
+ static func hooksObject(from config: JSONObject) throws -> JSONObject {
+ guard let value = config["hooks"] else {
+ return [:]
+ }
+
+ guard let hooks = value as? JSONObject else {
+ throw HookConfigError.invalidHooks
+ }
+
+ return hooks
+ }
+
+ static func eventGroups(named event: String, from hooks: JSONObject) throws -> JSONArray {
+ guard let value = hooks[event] else {
+ return []
+ }
+
+ guard let groups = value as? JSONArray else {
+ throw HookConfigError.invalidEvent(event)
+ }
+
+ return groups
+ }
+
+ static func isCurrentCodexBarHandler(
+ _ handler: Any,
+ event: String,
+ executablePath: String
+ ) -> Bool {
+ commandIfCommandHandler(handler) == hookCommand(for: event, executablePath: executablePath)
+ }
+
+ static func isCodexBarHandler(_ handler: Any) -> Bool {
+ guard let command = commandIfCommandHandler(handler) else {
+ return false
+ }
+
+ return command.contains("/Contents/MacOS/CodexBar")
+ && command.contains("--hook-event")
+ }
+
+ // 仅当 handler 是 type == "command" 时返回其 command 字符串, 否则 nil
+ private static func commandIfCommandHandler(_ handler: Any) -> String? {
+ guard let handler = handler as? JSONObject,
+ handler["type"] as? String == "command",
+ let command = handler["command"] as? String else {
+ return nil
+ }
+
+ return command
+ }
+
+ static func hookCommand(for event: String, executablePath: String) -> String {
+ "\(shellQuoted(executablePath)) --hook-event \(event)"
+ }
+
+ static func shellQuoted(_ value: String) -> String {
+ "'\(value.replacingOccurrences(of: "'", with: "'\\''"))'"
+ }
+}
diff --git a/CodexBar/Services/WorkflowStats/JSONLines.swift b/CodexBar/Services/WorkflowStats/JSONLines.swift
new file mode 100644
index 0000000..f6bd5d1
--- /dev/null
+++ b/CodexBar/Services/WorkflowStats/JSONLines.swift
@@ -0,0 +1,40 @@
+import Foundation
+
+nonisolated enum JSONLines {
+ // 按行解码 JSONL: 切分换行、trim、跳过空行与解码失败的行
+ static func decode<T: Decodable>(_ type: T.Type = T.self, from data: Data) -> [T] {
+ decodeWithFailures(type, from: data).values
+ }
+
+ static func decodeWithFailures<T: Decodable>(
+ _ type: T.Type = T.self,
+ from data: Data
+ ) -> JSONLinesDecodeResult<T> {
+ let text = String(decoding: data, as: UTF8.self)
+ let decoder = JSONDecoder()
+ var failedLineCount = 0
+
+ let values = text
+ .split(whereSeparator: \.isNewline)
+ .compactMap { line -> T? in
+ let trimmedLine = line.trimmingCharacters(in: .whitespacesAndNewlines)
+ guard !trimmedLine.isEmpty, let lineData = trimmedLine.data(using: .utf8) else {
+ return nil
+ }
+
+ if let value = try? decoder.decode(T.self, from: lineData) {
+ return value
+ }
+
+ failedLineCount += 1
+ return nil
+ }
+
+ return JSONLinesDecodeResult(values: values, failedLineCount: failedLineCount)
+ }
+}
+
+nonisolated struct JSONLinesDecodeResult<T> {
+ let values: [T]
+ let failedLineCount: Int
+}
diff --git a/CodexBar/Services/WorkflowStats/WorkflowHookEventRecorder.swift b/CodexBar/Services/WorkflowStats/WorkflowHookEventRecorder.swift
new file mode 100644
index 0000000..28ad1ad
--- /dev/null
+++ b/CodexBar/Services/WorkflowStats/WorkflowHookEventRecorder.swift
@@ -0,0 +1,257 @@
+import Darwin
+import Foundation
+
+nonisolated enum WorkflowHookEventRecorder {
+ static func handleIfRequested(arguments: [String] = CommandLine.arguments) -> Bool {
+ guard let eventName = hookEventName(from: arguments) else {
+ return false
+ }
+
+ try? record(eventName: eventName)
+ return true
+ }
+
+ private static func hookEventName(from arguments: [String]) -> String? {
+ for argument in arguments.dropFirst() {
+ if argument.hasPrefix("--hook-event=") {
+ let value = String(argument.dropFirst("--hook-event=".count))
+ .trimmingCharacters(in: .whitespacesAndNewlines)
+ return value.isEmpty ? nil : value
+ }
+ }
+
+ if let optionIndex = arguments.firstIndex(of: "--hook-event"),
+ arguments.indices.contains(arguments.index(after: optionIndex)) {
+ let value = arguments[arguments.index(after: optionIndex)]
+ .trimmingCharacters(in: .whitespacesAndNewlines)
+ return value.isEmpty ? nil : value
+ }
+
+ return nil
+ }
+
+ private static func record(eventName: String) throws {
+ let occurredAt = Date()
+ let payload = stdinPayload()
+ let cwd = payload.string(for: "cwd") ?? FileManager.default.currentDirectoryPath
+ let tool = payload.string(for: "tool_name")
+ let model = payload.string(for: "model")
+ let permission = payload.string(for: "permission_mode")
+ let sessionId = payload.string(for: "session_id")
+ let turnId = payload.string(for: "turn_id")
+ let event = WorkflowHookEvent(
+ occurredAt: occurredAt,
+ name: eventName,
+ directoryPath: cwd,
+ toolName: tool,
+ modelName: model,
+ permissionMode: permission,
+ sessionId: sessionId,
+ turnId: turnId
+ )
+
+ try recordStatsTransaction(event: event)
+ }
+
+ private static func recordStatsTransaction(event: WorkflowHookEvent) throws {
+ try WorkflowStatsStorage.withExclusiveLock {
+ let eventLogURL = WorkflowStatsStorage.eventsURL()
+ let dailyLogURL = WorkflowStatsStorage.dailyURL()
+ var maintenanceState = WorkflowStatsStorage.loadMaintenanceState()
+ let eventLogSizeBeforeAppend = WorkflowStatsStorage.fileSize(at: eventLogURL)
+ let needsDailyRebuild = maintenanceState.needsDailyRebuild(
+ eventLogSize: eventLogSizeBeforeAppend,
+ dailyLogURL: dailyLogURL
+ )
+ let maintenanceDate = DateFormatter.codexDay.string(from: Calendar.current.startOfDay(for: event.occurredAt))
+ let shouldRunMaintenance = maintenanceState.lastMaintenanceDate != maintenanceDate
+
+ try append(event.jsonLineData(), to: eventLogURL)
+ if shouldRunMaintenance {
+ try pruneExpiredEventsIfNeeded(at: eventLogURL)
+ maintenanceState.lastMaintenanceDate = maintenanceDate
+ }
+
+ guard !needsDailyRebuild else {
+ maintenanceState.markDailyRebuildNeeded()
+ try WorkflowStatsStorage.saveMaintenanceState(maintenanceState)
+ return
+ }
+
+ do {
+ try updateDailyAggregates(
+ with: event,
+ eventLogURL: eventLogURL,
+ dailyLogURL: dailyLogURL,
+ runsMaintenance: shouldRunMaintenance
+ )
+
+ maintenanceState.markDailyCacheUpdated(eventLogSize: WorkflowStatsStorage.fileSize(at: eventLogURL))
+ try WorkflowStatsStorage.saveMaintenanceState(maintenanceState)
+ } catch {
+ maintenanceState.markDailyRebuildNeeded(error: error)
+ try? WorkflowStatsStorage.saveMaintenanceState(maintenanceState)
+ throw error
+ }
+ }
+ }
+
+ private static func append(_ data: Data, to url: URL) throws {
+ if !FileManager.default.fileExists(atPath: url.path) {
+ FileManager.default.createFile(atPath: url.path, contents: nil)
+ }
+
+ let fileHandle = try FileHandle(forWritingTo: url)
+ defer {
+ try? fileHandle.close()
+ }
+
+ try fileHandle.seekToEnd()
+ try fileHandle.write(contentsOf: data)
+ }
+
+ private static func pruneExpiredEventsIfNeeded(at url: URL) throws {
+ guard FileManager.default.fileExists(atPath: url.path) else {
+ return
+ }
+
+ let fileHandle = try FileHandle(forUpdating: url)
+ defer {
+ try? fileHandle.close()
+ }
+
+ let cutoffDate = WorkflowStatsStorage.retentionCutoffDate()
+ guard try shouldPruneEvents(in: fileHandle, cutoffDate: cutoffDate) else {
+ return
+ }
+
+ try fileHandle.seek(toOffset: 0)
+ let currentData = try fileHandle.readToEnd() ?? Data()
+ let retainedData = try retainedEventLogData(from: currentData, cutoffDate: cutoffDate)
+
+ try fileHandle.truncate(atOffset: 0)
+ try fileHandle.seek(toOffset: 0)
+ try fileHandle.write(contentsOf: retainedData)
+ }
+
+ private static func shouldPruneEvents(in fileHandle: FileHandle, cutoffDate: Date) throws -> Bool {
+ try fileHandle.seek(toOffset: 0)
+ guard let firstChunk = try fileHandle.read(upToCount: 64 * 1024), !firstChunk.isEmpty else {
+ return false
+ }
+
+ let firstLineEnd = firstChunk.firstIndex(of: 0x0A) ?? firstChunk.endIndex
+ let firstLine = Data(firstChunk[..<firstLineEnd])
+ guard !firstLine.isEmpty else {
+ return false
+ }
+
+ guard let event = try? JSONDecoder().decode(WorkflowHookEvent.self, from: firstLine) else {
+ return true
+ }
+
+ return event.occurredAt < cutoffDate
+ }
+
+ private static func retainedEventLogData(from data: Data, cutoffDate: Date) throws -> Data {
+ var retainedData = Data()
+ for event in WorkflowHookEvent.decodeJSONLines(from: data) where event.occurredAt >= cutoffDate {
+ retainedData.append(try event.jsonLineData())
+ }
+
+ return retainedData
+ }
+
+ private static func updateDailyAggregates(
+ with event: WorkflowHookEvent,
+ eventLogURL: URL,
+ dailyLogURL: URL,
+ runsMaintenance: Bool
+ ) throws {
+ var aggregates = loadDailyAggregates(from: dailyLogURL)
+
+ if aggregates.isEmpty {
+ aggregates = rebuildDailyAggregates(from: eventLogURL)
+ } else {
+ aggregates = adding(event, to: aggregates)
+ aggregates = runsMaintenance
+ ? WorkflowDailyAggregate.normalized(aggregates: aggregates)
+ : aggregates.sorted { $0.date < $1.date }
+ }
+
+ let data = try WorkflowDailyAggregate.encodeJSONLines(aggregates)
+ try data.write(to: dailyLogURL, options: .atomic)
+ }
+
+ private static func adding(
+ _ event: WorkflowHookEvent,
+ to aggregates: [WorkflowDailyAggregate]
+ ) -> [WorkflowDailyAggregate] {
+ let calendar = Calendar.current
+ let eventStartDate = calendar.startOfDay(for: event.occurredAt)
+ guard eventStartDate >= WorkflowStatsStorage.retentionCutoffDate(calendar: calendar) else {
+ return WorkflowDailyAggregate.normalized(aggregates: aggregates, calendar: calendar)
+ }
+
+ let startDate = DateFormatter.codexDay.string(from: eventStartDate)
+ let keepsIdentifiers = eventStartDate >= WorkflowStatsStorage.identifierRetentionCutoffDate(calendar: calendar)
+ var aggregatesByDate = aggregates.reduce(into: [String: WorkflowDailyAggregate]()) { result, aggregate in
+ result[aggregate.date] = aggregate
+ }
+ aggregatesByDate[startDate, default: WorkflowDailyAggregate(date: startDate)]
+ .record(event, keepsIdentifiers: keepsIdentifiers)
+
+ return Array(aggregatesByDate.values)
+ }
+
+ private static func loadDailyAggregates(from url: URL) -> [WorkflowDailyAggregate] {
+ guard let data = try? Data(contentsOf: url), !data.isEmpty else {
+ return []
+ }
+
+ return WorkflowDailyAggregate.decodeJSONLines(from: data)
+ }
+
+ private static func rebuildDailyAggregates(from url: URL) -> [WorkflowDailyAggregate] {
+ guard let data = try? Data(contentsOf: url), !data.isEmpty else {
+ return []
+ }
+
+ return WorkflowDailyAggregate.aggregates(from: WorkflowHookEvent.decodeJSONLines(from: data))
+ }
+
+ private static func stdinPayload() -> WorkflowHookPayload {
+ guard isatty(STDIN_FILENO) == 0 else {
+ return WorkflowHookPayload(values: [:])
+ }
+
+ let data = FileHandle.standardInput.readDataToEndOfFile()
+ guard !data.isEmpty,
+ let object = try? JSONSerialization.jsonObject(with: data),
+ let values = object as? [String: Any] else {
+ return WorkflowHookPayload(values: [:])
+ }
+
+ return WorkflowHookPayload(values: values)
+ }
+}
+
+private nonisolated struct WorkflowHookPayload {
+ let values: [String: Any]
+
+ func string(for key: String) -> String? {
+ Self.normalizedString(values[key])
+ }
+
+ private static func normalizedString(_ value: Any?) -> String? {
+ switch value {
+ case let string as String:
+ let trimmedString = string.trimmingCharacters(in: .whitespacesAndNewlines)
+ return trimmedString.isEmpty ? nil : trimmedString
+ case let number as NSNumber:
+ return number.stringValue
+ default:
+ return nil
+ }
+ }
+}
diff --git a/CodexBar/Services/WorkflowStats/WorkflowStatsService.swift b/CodexBar/Services/WorkflowStats/WorkflowStatsService.swift
new file mode 100644
index 0000000..04709be
--- /dev/null
+++ b/CodexBar/Services/WorkflowStats/WorkflowStatsService.swift
@@ -0,0 +1,442 @@
+import Combine
+import Darwin
+import Foundation
+
+nonisolated final class WorkflowStatsService: @unchecked Sendable {
+ private static let maxEventLogReadSize: UInt64 = 5 * 1024 * 1024
+
+ private let queue = DispatchQueue(label: "CodexBar.workflow-stats", qos: .utility)
+ private let eventLogURL: URL
+ private let dailyLogURL: URL
+
+ init(
+ eventLogURL: URL = WorkflowStatsStorage.eventsURL(),
+ dailyLogURL: URL = WorkflowStatsStorage.dailyURL()
+ ) {
+ self.eventLogURL = eventLogURL
+ self.dailyLogURL = dailyLogURL
+ }
+
+ func loadSnapshot() async -> WorkflowStatsSnapshot {
+ await withCheckedContinuation { continuation in
+ queue.async {
+ continuation.resume(returning: self.loadSnapshotOnQueue())
+ }
+ }
+ }
+
+ private func loadSnapshotOnQueue() -> WorkflowStatsSnapshot {
+ if let repairedSnapshot = repairDailyCacheIfNeededOnQueue() {
+ return repairedSnapshot
+ }
+
+ if let aggregates = loadDailyAggregatesOnQueue(), !aggregates.isEmpty {
+ return WorkflowStatsSnapshot(dailyAggregates: aggregates)
+ }
+
+ guard let data = loadEventLogDataOnQueue(), !data.isEmpty else {
+ return .empty
+ }
+
+ return WorkflowStatsSnapshot(events: WorkflowHookEvent.decodeJSONLines(from: data))
+ }
+
+ private func repairDailyCacheIfNeededOnQueue() -> WorkflowStatsSnapshot? {
+ guard dailyCacheNeedsRebuildOnQueue() else {
+ return nil
+ }
+
+ do {
+ let eventLogData = try loadEventLogDataForRebuildOnQueue()
+ let eventLogStateAfterRead = WorkflowStatsStorage.fileState(at: eventLogURL)
+ guard eventLogStateAfterRead.size == UInt64(eventLogData.count) else {
+ throw WorkflowStatsRebuildError.eventsChangedDuringRebuild
+ }
+
+ let decodedEvents = WorkflowHookEvent.decodeJSONLinesWithFailures(from: eventLogData)
+ if eventLogStateAfterRead.size > 0,
+ decodedEvents.values.isEmpty,
+ decodedEvents.failedLineCount > 0 {
+ throw WorkflowStatsRebuildError.noReadableEvents(corruptLineCount: decodedEvents.failedLineCount)
+ }
+
+ let aggregates = WorkflowDailyAggregate.aggregates(from: decodedEvents.values)
+
+ return try WorkflowStatsStorage.withExclusiveLock {
+ let currentEventLogState = WorkflowStatsStorage.fileState(at: eventLogURL)
+ guard currentEventLogState == eventLogStateAfterRead else {
+ throw WorkflowStatsRebuildError.eventsChangedDuringRebuild
+ }
+
+ var state = WorkflowStatsStorage.loadMaintenanceState()
+ guard state.needsDailyRebuild(
+ eventLogSize: currentEventLogState.size,
+ dailyLogURL: dailyLogURL
+ ) else {
+ return loadDailyAggregatesOnQueue().map { WorkflowStatsSnapshot(dailyAggregates: $0) } ?? .empty
+ }
+
+ let data = try WorkflowDailyAggregate.encodeJSONLines(aggregates)
+ try data.write(to: dailyLogURL, options: .atomic)
+
+ state.markDailyRebuildSucceeded(
+ eventLogSize: currentEventLogState.size,
+ corruptEventLineCount: decodedEvents.failedLineCount
+ )
+ try WorkflowStatsStorage.saveMaintenanceState(state)
+
+ return WorkflowStatsSnapshot(dailyAggregates: aggregates)
+ }
+ } catch {
+ recordDailyRebuildFailureOnQueue(error)
+ return nil
+ }
+ }
+
+ private func dailyCacheNeedsRebuildOnQueue() -> Bool {
+ WorkflowStatsStorage.loadMaintenanceState().needsDailyRebuild(
+ eventLogSize: WorkflowStatsStorage.fileSize(at: eventLogURL),
+ dailyLogURL: dailyLogURL
+ )
+ }
+
+ private func loadEventLogDataForRebuildOnQueue() throws -> Data {
+ guard FileManager.default.fileExists(atPath: eventLogURL.path) else {
+ return Data()
+ }
+
+ return try Data(contentsOf: eventLogURL)
+ }
+
+ private func recordDailyRebuildFailureOnQueue(_ error: Error) {
+ try? WorkflowStatsStorage.withExclusiveLock {
+ var state = WorkflowStatsStorage.loadMaintenanceState()
+ state.markDailyRebuildNeeded(error: error)
+ try WorkflowStatsStorage.saveMaintenanceState(state)
+ }
+ }
+
+ private func loadDailyAggregatesOnQueue() -> [WorkflowDailyAggregate]? {
+ guard let data = try? Data(contentsOf: dailyLogURL), !data.isEmpty else {
+ return nil
+ }
+
+ let aggregates = WorkflowDailyAggregate.decodeJSONLines(from: data)
+ guard !aggregates.isEmpty else {
+ return nil
+ }
+
+ return WorkflowDailyAggregate.normalized(aggregates: aggregates)
+ }
+
+ private func loadEventLogDataOnQueue() -> Data? {
+ guard let attributes = try? FileManager.default.attributesOfItem(atPath: eventLogURL.path),
+ let fileSize = attributes[.size] as? NSNumber else {
+ return try? Data(contentsOf: eventLogURL)
+ }
+
+ let size = fileSize.uint64Value
+ guard size > Self.maxEventLogReadSize else {
+ return try? Data(contentsOf: eventLogURL)
+ }
+
+ guard let fileHandle = try? FileHandle(forReadingFrom: eventLogURL) else {
+ return nil
+ }
+ defer {
+ try? fileHandle.close()
+ }
+
+ guard (try? fileHandle.seek(toOffset: size - Self.maxEventLogReadSize)) != nil,
+ let tailData = try? fileHandle.readToEnd() else {
+ return nil
+ }
+
+ return Self.droppingPartialFirstLine(from: tailData)
+ }
+
+ private static func droppingPartialFirstLine(from data: Data) -> Data {
+ guard let newlineIndex = data.firstIndex(of: 0x0A),
+ newlineIndex < data.endIndex else {
+ return data
+ }
+
+ return Data(data[data.index(after: newlineIndex)...])
+ }
+
+}
+
+nonisolated enum WorkflowStatsStorage {
+ private static let retentionDayCount = 210
+ private static let identifierRetentionDayCount = 7
+
+ static func eventsURL() -> URL {
+ directoryURL()
+ .appendingPathComponent("events.jsonl", isDirectory: false)
+ }
+
+ static func dailyURL() -> URL {
+ directoryURL()
+ .appendingPathComponent("daily.jsonl", isDirectory: false)
+ }
+
+ static func lockURL() -> URL {
+ directoryURL()
+ .appendingPathComponent("stats.lock", isDirectory: false)
+ }
+
+ static func maintenanceURL() -> URL {
+ directoryURL()
+ .appendingPathComponent("maintenance.json", isDirectory: false)
+ }
+
+ static func directoryURL() -> URL {
+ let applicationSupportURL = FileManager.default.urls(
+ for: .applicationSupportDirectory,
+ in: .userDomainMask
+ ).first ?? URL(fileURLWithPath: NSHomeDirectory())
+ .appendingPathComponent("Library", isDirectory: true)
+ .appendingPathComponent("Application Support", isDirectory: true)
+
+ return applicationSupportURL
+ .appendingPathComponent("CodexBar", isDirectory: true)
+ .appendingPathComponent("HookEvents", isDirectory: true)
+ }
+
+ static func withExclusiveLock<T>(_ work: () throws -> T) throws -> T {
+ try FileManager.default.createDirectory(
+ at: directoryURL(),
+ withIntermediateDirectories: true
+ )
+
+ let lockURL = lockURL()
+ if !FileManager.default.fileExists(atPath: lockURL.path) {
+ FileManager.default.createFile(atPath: lockURL.path, contents: nil)
+ }
+
+ let lockHandle = try FileHandle(forUpdating: lockURL)
+ defer {
+ try? lockHandle.close()
+ }
+
+ if flock(lockHandle.fileDescriptor, LOCK_EX) != 0 {
+ throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)
+ }
+
+ defer {
+ flock(lockHandle.fileDescriptor, LOCK_UN)
+ }
+
+ return try work()
+ }
+
+ static func loadMaintenanceState() -> WorkflowStatsMaintenanceState {
+ let url = maintenanceURL()
+ guard let data = try? Data(contentsOf: url), !data.isEmpty,
+ let state = try? JSONDecoder().decode(WorkflowStatsMaintenanceState.self, from: data) else {
+ return WorkflowStatsMaintenanceState()
+ }
+
+ return state
+ }
+
+ static func saveMaintenanceState(_ state: WorkflowStatsMaintenanceState) throws {
+ try FileManager.default.createDirectory(
+ at: directoryURL(),
+ withIntermediateDirectories: true
+ )
+
+ let encoder = JSONEncoder()
+ encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]
+ let data = try encoder.encode(state)
+ try data.write(to: maintenanceURL(), options: .atomic)
+ }
+
+ static func fileSize(at url: URL) -> UInt64 {
+ fileState(at: url).size
+ }
+
+ static func fileState(at url: URL) -> WorkflowStatsFileState {
+ guard let attributes = try? FileManager.default.attributesOfItem(atPath: url.path),
+ let fileSize = attributes[.size] as? NSNumber else {
+ return WorkflowStatsFileState(size: 0, modifiedAt: nil)
+ }
+
+ return WorkflowStatsFileState(
+ size: fileSize.uint64Value,
+ modifiedAt: attributes[.modificationDate] as? Date
+ )
+ }
+
+ static func retentionCutoffDate(today: Date = Date(), calendar: Calendar = .current) -> Date {
+ let todayStart = calendar.startOfDay(for: today)
+ return calendar.date(
+ byAdding: .day,
+ value: -(retentionDayCount - 1),
+ to: todayStart
+ ) ?? todayStart
+ }
+
+ static func identifierRetentionCutoffDate(today: Date = Date(), calendar: Calendar = .current) -> Date {
+ let todayStart = calendar.startOfDay(for: today)
+ return calendar.date(
+ byAdding: .day,
+ value: -(identifierRetentionDayCount - 1),
+ to: todayStart
+ ) ?? todayStart
+ }
+}
+
+nonisolated struct WorkflowStatsFileState: Equatable {
+ let size: UInt64
+ let modifiedAt: Date?
+}
+
+nonisolated struct WorkflowStatsMaintenanceState: Codable, Equatable {
+ private static let maxErrorSummaryLength = 240
+
+ var lastMaintenanceDate: String?
+ var lastAggregatedEventLogSize: UInt64?
+ var needsDailyRebuild: Bool
+ var lastDailyRebuildAt: String?
+ var lastDailyRebuildFailedAt: String?
+ var lastDailyRebuildError: String?
+ var corruptEventLineCount: Int
+
+ init(
+ lastMaintenanceDate: String? = nil,
+ lastAggregatedEventLogSize: UInt64? = nil,
+ needsDailyRebuild: Bool = false,
+ lastDailyRebuildAt: String? = nil,
+ lastDailyRebuildFailedAt: String? = nil,
+ lastDailyRebuildError: String? = nil,
+ corruptEventLineCount: Int = 0
+ ) {
+ self.lastMaintenanceDate = lastMaintenanceDate
+ self.lastAggregatedEventLogSize = lastAggregatedEventLogSize
+ self.needsDailyRebuild = needsDailyRebuild
+ self.lastDailyRebuildAt = lastDailyRebuildAt
+ self.lastDailyRebuildFailedAt = lastDailyRebuildFailedAt
+ self.lastDailyRebuildError = lastDailyRebuildError
+ self.corruptEventLineCount = corruptEventLineCount
+ }
+
+ init(from decoder: Decoder) throws {
+ let container = try decoder.container(keyedBy: CodingKeys.self)
+ self.lastMaintenanceDate = try container.decodeIfPresent(String.self, forKey: .lastMaintenanceDate)
+ self.lastAggregatedEventLogSize = try container.decodeIfPresent(UInt64.self, forKey: .lastAggregatedEventLogSize)
+ self.needsDailyRebuild = try container.decodeIfPresent(Bool.self, forKey: .needsDailyRebuild) ?? false
+ self.lastDailyRebuildAt = try container.decodeIfPresent(String.self, forKey: .lastDailyRebuildAt)
+ self.lastDailyRebuildFailedAt = try container.decodeIfPresent(String.self, forKey: .lastDailyRebuildFailedAt)
+ self.lastDailyRebuildError = try container.decodeIfPresent(String.self, forKey: .lastDailyRebuildError)
+ self.corruptEventLineCount = try container.decodeIfPresent(Int.self, forKey: .corruptEventLineCount) ?? 0
+ }
+
+ func needsDailyRebuild(eventLogSize: UInt64, dailyLogURL: URL) -> Bool {
+ if needsDailyRebuild {
+ return true
+ }
+
+ guard eventLogSize > 0 else {
+ return false
+ }
+
+ guard let lastAggregatedEventLogSize else {
+ return true
+ }
+
+ if lastAggregatedEventLogSize != eventLogSize {
+ return true
+ }
+
+ return WorkflowStatsStorage.fileSize(at: dailyLogURL) == 0
+ }
+
+ mutating func markDailyCacheUpdated(eventLogSize: UInt64) {
+ needsDailyRebuild = false
+ lastAggregatedEventLogSize = eventLogSize
+ }
+
+ mutating func markDailyRebuildSucceeded(eventLogSize: UInt64, corruptEventLineCount: Int) {
+ markDailyCacheUpdated(eventLogSize: eventLogSize)
+ lastDailyRebuildAt = Self.timestampString()
+ lastDailyRebuildFailedAt = nil
+ lastDailyRebuildError = nil
+ self.corruptEventLineCount = corruptEventLineCount
+ }
+
+ mutating func markDailyRebuildNeeded(error: Error? = nil) {
+ needsDailyRebuild = true
+
+ guard let error else {
+ return
+ }
+
+ lastDailyRebuildFailedAt = Self.timestampString()
+ lastDailyRebuildError = Self.errorSummary(error)
+ }
+
+ static func timestampString(from date: Date = Date()) -> String {
+ ISO8601DateFormatter.codexFractional.string(from: date)
+ }
+
+ private static func errorSummary(_ error: Error) -> String {
+ let message = error.localizedDescription
+ guard message.count > maxErrorSummaryLength else {
+ return message
+ }
+
+ return String(message.prefix(maxErrorSummaryLength))
+ }
+}
+
+private nonisolated enum WorkflowStatsRebuildError: LocalizedError {
+ case eventsChangedDuringRebuild
+ case noReadableEvents(corruptLineCount: Int)
+
+ var errorDescription: String? {
+ switch self {
+ case .eventsChangedDuringRebuild:
+ return "events.jsonl changed during daily rebuild"
+ case .noReadableEvents(let corruptLineCount):
+ return "events.jsonl has no readable events (\(corruptLineCount) corrupt lines)"
+ }
+ }
+}
+
+@MainActor
+final class WorkflowStatsViewModel: ObservableObject {
+ @Published private(set) var snapshot = WorkflowStatsSnapshot.empty
+
+ private static let minimumRefreshInterval: TimeInterval = 5
+
+ private let service: WorkflowStatsService
+ private var isRefreshing = false
+ private var lastRefreshedAt: Date?
+
+ init(service: WorkflowStatsService = WorkflowStatsService()) {
+ self.service = service
+ }
+
+ func refreshIfNeeded() {
+ guard Date().timeIntervalSince(lastRefreshedAt ?? .distantPast) > Self.minimumRefreshInterval else {
+ return
+ }
+
+ refresh()
+ }
+
+ func refresh() {
+ guard !isRefreshing else {
+ return
+ }
+
+ isRefreshing = true
+
+ Task {
+ snapshot = await service.loadSnapshot()
+ lastRefreshedAt = Date()
+ isRefreshing = false
+ }
+ }
+}
diff --git a/CodexBar/Views/Log/LogView.swift b/CodexBar/Views/Log/LogView.swift
index 9d39c34..72710a5 100644
--- a/CodexBar/Views/Log/LogView.swift
+++ b/CodexBar/Views/Log/LogView.swift
@@ -24,7 +24,7 @@ struct LogView: View {
Image(systemName: "doc.text.magnifyingglass")
.foregroundStyle(.tint)
- Text("Codex 日志")
+ Text("Codex app-server 日志")
.font(.headline)
Text("\(entries.count)")
diff --git a/CodexBar/Views/Menu/CodexStatusMenuView.swift b/CodexBar/Views/Menu/CodexStatusMenuView.swift
index 9321655..9325b93 100644
--- a/CodexBar/Views/Menu/CodexStatusMenuView.swift
+++ b/CodexBar/Views/Menu/CodexStatusMenuView.swift
@@ -10,6 +10,8 @@ struct CodexStatusMenuView: View {
static let menuWidth: CGFloat = Metrics.padding * 2 + MenuMetrics.panelPadding * 2 + UsageHeatmap.Metrics.totalWidth
@ObservedObject var viewModel: CodexStatusViewModel
+ @ObservedObject var workflowStatsViewModel: WorkflowStatsViewModel
+ @ObservedObject var codexHookSettings: CodexHookSettings
@ObservedObject var popoverVisibility: PopoverVisibilityState
@EnvironmentObject private var appUpdater: AppUpdater
@@ -20,6 +22,7 @@ struct CodexStatusMenuView: View {
.padding(Metrics.padding)
.liquidGlassSurface(cornerRadius: Metrics.surfaceCornerRadius, isOuterSurface: true)
.animation(Metrics.statusAnimation, value: viewModel.loadState)
+ .animation(Metrics.statusAnimation, value: codexHookSettings.isEnabled)
}
}
@@ -66,7 +69,12 @@ private extension CodexStatusMenuView {
}
if let usage = snapshot.usage {
- UsageSummaryView(usage: usage, isStale: snapshot.isUsageStale)
+ UsageSummaryView(
+ usage: usage,
+ workflowStats: workflowStatsViewModel.snapshot,
+ showsWorkflowStats: codexHookSettings.isEnabled,
+ isStale: snapshot.isUsageStale
+ )
}
}
diff --git a/CodexBar/Views/Menu/TokenCountText.swift b/CodexBar/Views/Menu/TokenCountText.swift
index ca8c223..60476a5 100644
--- a/CodexBar/Views/Menu/TokenCountText.swift
+++ b/CodexBar/Views/Menu/TokenCountText.swift
@@ -2,10 +2,11 @@ import SwiftUI
struct TokenCountText: View {
let tokens: Int
+ var font: Font = .caption.monospacedDigit().weight(.semibold)
var body: some View {
Text(TokenCountFormatter.string(from: tokens))
- .font(.caption.monospacedDigit().weight(.semibold))
+ .font(font)
.lineLimit(1)
.minimumScaleFactor(0.8)
}
diff --git a/CodexBar/Views/Menu/UsageHeatmap.swift b/CodexBar/Views/Menu/UsageHeatmap.swift
index 0ce65d7..43c82ba 100644
--- a/CodexBar/Views/Menu/UsageHeatmap.swift
+++ b/CodexBar/Views/Menu/UsageHeatmap.swift
@@ -3,20 +3,38 @@ import SwiftUI
struct UsageSummaryView: View {
let usage: CodexUsageSnapshot
let isStale: Bool
- private let days: [DailyUsageBucket?]
- @State private var hoveredDay: DailyUsageBucket?
+ let showsWorkflowStats: Bool
+ private let days: [UsageHeatmapDay?]
+ @State private var hoveredDay: UsageHeatmapDay?
- init(usage: CodexUsageSnapshot, isStale: Bool = false) {
+ init(
+ usage: CodexUsageSnapshot,
+ workflowStats: WorkflowStatsSnapshot,
+ showsWorkflowStats: Bool,
+ isStale: Bool = false
+ ) {
self.usage = usage
self.isStale = isStale
- self.days = usage.recentWeekGrid(columnCount: UsageHeatmap.Metrics.columnCount, endingDaysAgo: 1)
+ self.showsWorkflowStats = showsWorkflowStats
+
+ self.days = UsageHeatmapDay.grid(
+ usage: usage,
+ workflowStats: workflowStats,
+ showsWorkflowStats: showsWorkflowStats,
+ columnCount: UsageHeatmap.Metrics.columnCount,
+ today: Date()
+ )
}
var body: some View {
VStack(alignment: .leading, spacing: 8) {
metricsGrid
- UsageHeatmap(days: days, hoveredDay: $hoveredDay)
+ UsageHeatmap(
+ days: days,
+ showsWorkflowStats: showsWorkflowStats,
+ hoveredDay: $hoveredDay
+ )
}
.markStale(isStale)
.padding(10)
@@ -108,16 +126,22 @@ struct UsageSummaryView: View {
}
struct UsageHeatmap: View {
- let days: [DailyUsageBucket?]
- @Binding var hoveredDay: DailyUsageBucket?
+ let days: [UsageHeatmapDay?]
+ let showsWorkflowStats: Bool
+ @Binding var hoveredDay: UsageHeatmapDay?
@State private var hoveredSquareFrame: CGRect = .zero
// hover 期间 body 频繁重算, 峰值只在构建时求一次
private let peakTokens: Int
- init(days: [DailyUsageBucket?], hoveredDay: Binding<DailyUsageBucket?>) {
+ init(
+ days: [UsageHeatmapDay?],
+ showsWorkflowStats: Bool,
+ hoveredDay: Binding<UsageHeatmapDay?>
+ ) {
self.days = days
+ self.showsWorkflowStats = showsWorkflowStats
self._hoveredDay = hoveredDay
- self.peakTokens = max(days.lazy.compactMap { $0?.tokens }.max() ?? 0, 1)
+ self.peakTokens = max(days.lazy.compactMap { $0?.tokensForHeatmap }.max() ?? 0, 1)
}
var body: some View {
@@ -125,7 +149,7 @@ struct UsageHeatmap: View {
heatmapGrid
if let hoveredDay {
- UsageHeatmapTooltip(day: hoveredDay)
+ UsageHeatmapTooltip(day: hoveredDay, showsWorkflowStats: showsWorkflowStats)
.id(hoveredDay.id)
.allowsHitTesting(false)
.offset(tooltipOffset)
@@ -163,7 +187,7 @@ struct UsageHeatmap: View {
if days.indices.contains(index), let day = days[index] {
UsageHeatmapSquare(
day: day,
- percent: Double(day.tokens) / Double(peakTokens),
+ percent: Double(day.tokensForHeatmap) / Double(peakTokens),
isHovered: hoveredDay?.id == day.id
) { frame in
if hoveredDay?.id != day.id {
@@ -193,30 +217,35 @@ struct UsageHeatmap: View {
.frame(maxWidth: .infinity, alignment: .leading)
}
- private var visibleDays: [DailyUsageBucket] {
+ private var visibleDays: [UsageHeatmapDay] {
days.compactMap { $0 }
}
private var tooltipOffset: CGSize {
- let aboveY = hoveredSquareFrame.minY - Metrics.tooltipSquareSpacing - Metrics.tooltipHeight
+ let aboveY = hoveredSquareFrame.minY - Metrics.tooltipSquareSpacing - tooltipHeight
let tooltipY = aboveY >= 0 ? aboveY : hoveredSquareFrame.maxY + Metrics.tooltipSquareSpacing
return CGSize(
width: tooltipX(for: hoveredSquareFrame),
- height: min(max(tooltipY, 0), max(0, Metrics.height - Metrics.tooltipHeight))
+ height: min(max(tooltipY, 0), max(0, Metrics.height - tooltipHeight))
)
}
+ private var tooltipHeight: CGFloat {
+ Metrics.tooltipHeight(showsWorkflowStats: showsWorkflowStats)
+ }
+
private func tooltipX(for squareFrame: CGRect) -> CGFloat {
let trailingX = squareFrame.maxX + Metrics.tooltipSquareSpacing
- let leadingX = squareFrame.minX - Metrics.tooltipSquareSpacing - Metrics.tooltipWidth
- let maxX = max(0, Metrics.totalWidth - Metrics.tooltipWidth)
+ let tooltipWidth = Metrics.tooltipWidth(showsWorkflowStats: showsWorkflowStats)
+ let leadingX = squareFrame.minX - Metrics.tooltipSquareSpacing - tooltipWidth
+ let maxX = max(0, Metrics.totalWidth - tooltipWidth)
if leadingX >= 0 {
return leadingX
}
- if trailingX + Metrics.tooltipWidth <= Metrics.totalWidth {
+ if trailingX + tooltipWidth <= Metrics.totalWidth {
return trailingX
}
@@ -228,23 +257,33 @@ extension UsageHeatmap {
enum Metrics {
static let coordinateSpaceName = "usageHeatmap"
static let columnCount = 30
- static let rowCount = 7
+ static let rowCount = CodexWeekGrid.rowCount
static let squareSize: CGFloat = 12
static let squareSpacing: CGFloat = 3
static let height: CGFloat = 120
- static let tooltipWidth: CGFloat = 78
- static let tooltipHeight: CGFloat = 38
+ static let workflowTooltipWidth: CGFloat = 132
+ static let tokenTooltipWidth: CGFloat = 92
+ static let workflowTooltipHeight: CGFloat = 116
+ static let tokenTooltipHeight: CGFloat = 40
static let tooltipSquareSpacing: CGFloat = 2
static let tooltipFadeDuration: TimeInterval = 0.15
static var totalWidth: CGFloat {
CGFloat(columnCount) * squareSize + CGFloat(columnCount - 1) * squareSpacing
}
+
+ static func tooltipWidth(showsWorkflowStats: Bool) -> CGFloat {
+ showsWorkflowStats ? workflowTooltipWidth : tokenTooltipWidth
+ }
+
+ static func tooltipHeight(showsWorkflowStats: Bool) -> CGFloat {
+ showsWorkflowStats ? workflowTooltipHeight : tokenTooltipHeight
+ }
}
}
private struct UsageHeatmapSquare: View {
- let day: DailyUsageBucket
+ let day: UsageHeatmapDay
let percent: Double
let isHovered: Bool
let onActive: (CGRect) -> Void
@@ -279,7 +318,7 @@ private struct UsageHeatmapSquare: View {
}
private var fillColor: Color {
- guard day.tokens > 0 else {
+ guard day.tokensForHeatmap > 0 else {
return Color.blue.opacity(isHovered ? 0.16 : 0.08)
}
@@ -293,25 +332,110 @@ private struct UsageHeatmapSquare: View {
return Color.blue.opacity(0.78)
}
- return Color.blue.opacity(day.tokens > 0 ? 0.18 : 0.10)
+ return Color.blue.opacity(day.tokensForHeatmap > 0 ? 0.18 : 0.10)
}
}
private struct UsageHeatmapTooltip: View {
- let day: DailyUsageBucket
+ let day: UsageHeatmapDay
+ let showsWorkflowStats: Bool
+ @Environment(\.colorScheme) private var colorScheme
var body: some View {
- VStack(alignment: .leading, spacing: 2) {
- Text(day.startDate)
- .font(.caption2.monospacedDigit())
- .foregroundStyle(Color.codexSecondaryLabel)
+ VStack(alignment: .leading, spacing: 3) {
+ if showsWorkflowStats {
+ HStack(alignment: .firstTextBaseline, spacing: 4) {
+ dateText
+
+ Spacer(minLength: 4)
+
+ tokenText
+ }
+
+ metricRow("会话总数", value: "\(day.workflowStats.sessionCount)")
+ metricRow("对话轮次", value: "\(day.workflowStats.turnCount)")
+ metricRow("子智能体", value: "\(day.workflowStats.subagentCount)")
+ metricRow("工具调用", value: "\(day.workflowStats.toolCallCount)")
+ metricRow("权限请求", value: "\(day.workflowStats.permissionRequestCount)")
+ metricRow("上下文压缩", value: "\(day.workflowStats.contextCompactionCount)")
+ } else {
+ dateText
+ tokenText
+ }
+ }
+ .padding(.horizontal, 8)
+ .padding(.vertical, 6)
+ .frame(
+ width: tooltipWidth,
+ height: tooltipHeight,
+ alignment: .leading
+ )
+ .background {
+ RoundedRectangle(cornerRadius: 7, style: .continuous)
+ .fill(tooltipFill)
+ }
+ .liquidGlassSurface(cornerRadius: 7)
+ }
+
+ private var tooltipHeight: CGFloat {
+ UsageHeatmap.Metrics.tooltipHeight(showsWorkflowStats: showsWorkflowStats)
+ }
+
+ private var tooltipWidth: CGFloat {
+ UsageHeatmap.Metrics.tooltipWidth(showsWorkflowStats: showsWorkflowStats)
+ }
+
+ private var dateText: some View {
+ Text(day.startDate)
+ .font(dateFont)
+ .foregroundStyle(Color.codexSecondaryLabel)
+ .lineLimit(1)
+ .fixedSize(horizontal: true, vertical: false)
+ .layoutPriority(1)
+ }
+
+ @ViewBuilder
+ private var tokenText: some View {
+ if let tokenCount = day.tokenCount {
+ TokenCountText(tokens: tokenCount, font: tokenFont)
+ .foregroundStyle(Color.codexLabel)
+ } else {
+ Text("--")
+ .font(tokenFont)
+ .foregroundStyle(Color.codexLabel)
+ }
+ }
+
+ private var dateFont: Font {
+ showsWorkflowStats
+ ? .system(size: 10).monospacedDigit()
+ : .caption2.monospacedDigit()
+ }
+
+ private var tokenFont: Font {
+ showsWorkflowStats
+ ? .system(size: 10).monospacedDigit().weight(.semibold)
+ : .caption.monospacedDigit().weight(.semibold)
+ }
+
+ private func metricRow(_ label: String, value: String) -> some View {
+ HStack(spacing: 6) {
+ Text(label)
+ .foregroundStyle(.secondary)
+ .frame(width: 54, alignment: .leading)
- TokenCountText(tokens: day.tokens)
+ Text(value)
.foregroundStyle(Color.codexLabel)
+ .monospacedDigit()
+ .lineLimit(1)
+ .truncationMode(.tail)
+ .frame(maxWidth: .infinity, alignment: .trailing)
}
- .padding(.horizontal, 7)
- .padding(.vertical, 5)
- .frame(width: UsageHeatmap.Metrics.tooltipWidth, alignment: .leading)
- .liquidGlassSurface(cornerRadius: 7)
+ .font(.system(size: 10))
+ }
+
+ private var tooltipFill: Color {
+ Color(nsColor: .windowBackgroundColor)
+ .opacity(colorScheme == .dark ? 0.88 : 0.82)
}
}
diff --git a/CodexBar/Views/Settings/AppSettingsView.swift b/CodexBar/Views/Settings/AppSettingsView.swift
index 73bbc48..19bcfb2 100644
--- a/CodexBar/Views/Settings/AppSettingsView.swift
+++ b/CodexBar/Views/Settings/AppSettingsView.swift
@@ -6,6 +6,7 @@ struct AppSettingsView: View {
@EnvironmentObject private var appUpdater: AppUpdater
@StateObject private var loginItemSettings = LoginItemSettings()
@StateObject private var codexVersions = CodexCLIVersionViewModel()
+ @ObservedObject var codexHookSettings: CodexHookSettings
var body: some View {
VStack(alignment: .leading, spacing: Metrics.sectionSpacing) {
@@ -14,6 +15,8 @@ struct AppSettingsView: View {
LiquidGlassDivider()
automaticUpdateCheckRow
LiquidGlassDivider()
+ codexHookRow
+ LiquidGlassDivider()
versionRow
LiquidGlassDivider()
codexVersionSection
@@ -28,6 +31,7 @@ struct AppSettingsView: View {
checkUpdateButton
}
.animation(Metrics.statusAnimation, value: loginItemSettings.errorMessage)
+ .animation(Metrics.statusAnimation, value: codexHookSettings.errorMessage)
.padding(Metrics.panelPadding)
.liquidGlassSurface(cornerRadius: Metrics.panelCornerRadius)
}
@@ -44,6 +48,7 @@ struct AppSettingsView: View {
)
.onAppear {
loginItemSettings.refresh()
+ codexHookSettings.refresh()
appUpdater.refreshAutomaticCheckSetting()
refreshCodexVersionSection()
}
@@ -89,6 +94,29 @@ private extension AppSettingsView {
)
}
+ var codexHookRow: some View {
+ VStack(alignment: .leading, spacing: 4) {
+ SettingsToggleRow(
+ icon: "link",
+ title: "启用 Codex Hook",
+ isOn: Binding(
+ get: { codexHookSettings.isEnabled },
+ set: { codexHookSettings.setEnabled($0) }
+ )
+ )
+
+ HStack(alignment: .top, spacing: 10) {
+ Color.clear
+ .frame(width: Metrics.iconWidth)
+
+ Text("开启后将会写入全局 Codex Hook 配置\n用于热力图中展示更多数据, 数据仅保存在本机")
+ .font(.caption)
+ .foregroundStyle(.secondary)
+ .fixedSize(horizontal: false, vertical: true)
+ }
+ }
+ }
+
var versionRow: some View {
let status = versionStatus
@@ -154,6 +182,12 @@ private extension AppSettingsView {
.foregroundStyle(.red)
.fixedSize(horizontal: false, vertical: true)
.transition(.opacity)
+ } else if let message = codexHookSettings.errorMessage {
+ Text(message)
+ .font(.caption)
+ .foregroundStyle(.red)
+ .fixedSize(horizontal: false, vertical: true)
+ .transition(.opacity)
}
}
diff --git a/Docs/AppServer.md b/Docs/AppServer.md
new file mode 100644
index 0000000..23f1d16
--- /dev/null
+++ b/Docs/AppServer.md
@@ -0,0 +1,116 @@
+# app-server 通信合约
+
+本文档记录 CodexBar 与本机 Codex app-server 的连接、请求、错误处理和日志规则。`AGENTS.md` 只保留开发时必须遵守的边界,具体实现细节以本文档为准。
+
+## 启动命令
+
+启动命令统一是:
+
+```bash
+codex app-server --listen stdio://
+```
+
+必须通过 `CodexCLIResolver.resolveAppServerCommand()` 解析:
+
+- 优先 PATH 中的全局 `codex`。
+- 如果 PATH 中的 `codex` 等价于 `/Applications/Codex.app/Contents/Resources/codex`,当作内置 Codex APP CLI,不当作全局 CLI。
+- 全局 CLI 不存在时回退 Codex APP 内置 CLI。
+- 两者都不存在时返回 `CodexStatusError.executableNotFound`,UI 归为「初始化失败」,日志记录具体错误。
+
+不要绕过 `CodexCLIResolver` 直接启动 app-server。
+
+## 启动环境
+
+启动环境由 `CodexCLIResolver.environment` 构造:
+
+- 保留当前环境。
+- `HOME` 必须来自 `getpwuid(getuid())` 的真实用户 home。
+- 同步设置 `USER`、`LOGNAME`。
+- 合并 Homebrew、npm global、`.local`、Volta 和系统路径。
+- 确保 `TERM` 有值。
+- 不要改回 Xcode sandbox/container 的 `HOME`,否则会读不到真实 `~/.codex/auth.json`。
+
+## 首次连接
+
+首次连接流程:
+
+```json
+{"method":"initialize","id":1,"params":{"clientInfo":{"name":"codex_bar","title":"Codex Bar","version":"<Bundle MARKETING_VERSION 或 1.0.0>"}}}
+{"method":"initialized"}
+{"method":"account/read","id":2,"params":{"refreshToken":false}}
+```
+
+`initialized` 是无 id 请求,不等待响应;日志中记录为空响应请求,不归为通知类型。
+
+`initialize` 响应的 `userAgent` 首个 token 形如 `codex_bar/0.139.0 (...)`;取 `/` 后版本号作为当前运行版本。
+
+## 后续读取
+
+同一会话后续读取:
+
+- `account/read` 每轮复用连接时用 `refreshToken: false` 更新账户状态。
+- `account/rateLimits/read` 读取额度。
+- `account/usage/read` 读取 `summary.lifetimeTokens`、`summary.peakDailyTokens`、`dailyUsageBuckets`。
+
+认证失败时,同会话最多调用一次 `account/read(refreshToken:true)` 后重试原读取。
+
+## 错误处理
+
+所有走 `AppServerSession.request` 的方法,收到方法不支持错误后都记录到当前会话的 `unsupportedMethods`,本连接后续不再请求该方法。
+
+方法不支持必须是 JSON-RPC error,且 message 包含:
+
+```text
+Invalid request: unknown variant
+```
+
+请求有 JSON-RPC error 响应,且不是认证失败、不是方法不支持、不是传输/解析故障时,先立即重试同一个请求一次。
+
+非认证业务错误重试后仍失败时,不阻断整轮刷新,详情只进日志。
+
+`account/rateLimits/read` 和 `account/usage/read` 重试后仍失败时:
+
+- 若同账号有上次成功数据,则复用旧数据并标记为 stale。
+- 没有旧数据则不展示对应区域。
+- 方法不支持不复用旧数据,对应读取结果视为空。
+
+传输/解析故障归为需要重建连接。
+
+## 连接生命周期
+
+连接细节:
+
+- `requestTimeout` 是 20 秒。
+- `connectionMaxAge` 是 1 小时。
+- `SIGPIPE` 已被忽略,写入断管后应由 `write` 抛错并走重建。
+- 复用连接出现传输故障时只重建重试一次。
+- 全新连接初始化失败直接返回「初始化失败」,不重复完整握手。
+
+## UI 状态
+
+`CodexLoadState` 只有四种:
+
+- `loading`
+- `loaded`
+- `notLoggedIn`
+- `initializationFailed`
+
+UI 只展示「未登录」和「初始化失败」两类特殊状态;具体请求错误、启动错误、超时、断连、解析失败都进入日志。
+
+## 请求日志
+
+日志状态标签:
+
+- `.pending` ->「进行」
+- `.response` ->「完成」
+- `.failure` ->「错误」
+- `.emptyResponse` ->「请求」
+
+日志规则:
+
+- 带 id 的 JSON-RPC 请求先记录为进行,响应或错误到达后回填到同一条。
+- `initialized` 这类无 id 请求记录为空响应。
+- 日志容量上限 500 条,单条详情上限 4000 字符。
+- 合法 JSON 通过 `JSONSerialization` 重新序列化,使用 `.sortedKeys` 和 `.withoutEscapingSlashes`。
+- 非 JSON 错误消息保持原样。
+- 不要把子进程 stderr 直接展示给用户。
diff --git a/Docs/CodexHook.md b/Docs/CodexHook.md
new file mode 100644
index 0000000..567fa27
--- /dev/null
+++ b/Docs/CodexHook.md
@@ -0,0 +1,187 @@
+# Codex Hook 工作流统计
+
+本文档记录 CodexBar 接入 Codex Hook 后的配置、存储和统计口径。`AGENTS.md` 只保留开发时必须遵守的边界,具体实现细节以本文档为准。
+
+## 开关行为
+
+设置页「启用 Codex Hook」由 `CodexHookSettings` 管理。开启后,CodexBar 会把当前 App 的可执行文件路径写入全局配置:
+
+```text
+~/.codex/hooks.json
+```
+
+写入前会先移除 CodexBar 自己旧的 Hook 处理器,再按当前 App 路径安装新处理器。关闭时只移除 CodexBar 自己的处理器,用户自定义 Hook、其他 App Hook 和同事件下的其他处理器必须保留。
+
+CodexBar 处理器的识别条件:
+
+- `type` 是 `command`
+- `command` 包含 `/Contents/MacOS/CodexBar`
+- `command` 包含 `--hook-event`
+
+检测是否已开启时,要求全部 CodexBar 事件都存在当前 App 路径对应的处理器。
+
+## Hook 事件
+
+当前安装的事件:
+
+```text
+SessionStart
+UserPromptSubmit
+PreToolUse
+PostToolUse
+PermissionRequest
+PreCompact
+PostCompact
+Stop
+SubagentStart
+SubagentStop
+```
+
+命令格式:
+
+```bash
+'/Applications/CodexBar.app/Contents/MacOS/CodexBar' --hook-event SessionStart
+```
+
+Hook timeout 为 5 秒。App 启动最早阶段会调用 `WorkflowHookEventRecorder.handleIfRequested()`,如果命中 Hook 参数,只记录数据并立即退出正常 App 启动流程。
+
+支持的参数形式:
+
+```bash
+--hook-event SessionStart
+--hook-event=SessionStart
+```
+
+旧的 `codexbar_event` 参数已经删除,不再兼容。
+
+## Payload 解析
+
+Hook stdin 会尝试解析为 Codex 官方 JSON 对象,只读取顶层字段。缺少字段时尽量兜底,不阻断记录。
+
+读取字段:
+
+- 目录: `cwd`
+- 工具: `tool_name`
+- 模型: `model`
+- 权限模式: `permission_mode`,写入 `events.jsonl` 时保存为 `permission`
+- 会话: `session_id`
+- 轮次: `turn_id`
+
+事件名来自 Hook 命令参数 `--hook-event`,时间戳由 CodexBar 记录时生成。`events.jsonl` 每行按固定顺序写入 `timestamp`、`event`、`model`、`permission`、`session`、`turn`、`cwd`、`tool`;缺失值写为 `null`。每日维护裁剪 `events.jsonl` 时也会用同一编码入口重写保留行,确保字段顺序稳定。
+
+事件名统计时会去掉 `_` 和 `-` 并转小写,因此 `PreToolUse`、`pre_tool_use`、`pre-tool-use` 会归为同一个事件。
+
+常用项目名称只取目录最后一层,不过当前 popup 不展示该字段。
+
+## 本机存储
+
+Hook 数据目录:
+
+```text
+~/Library/Application Support/CodexBar/HookEvents/
+```
+
+文件职责:
+
+- `events.jsonl`: 原始 Hook 事件日志
+- `daily.jsonl`: 每日聚合结果,UI 优先读取它
+- `stats.lock`: 并发写入锁文件,只用于 `flock`
+- `maintenance.json`: 记录上次每日维护日期、`daily.jsonl` 重建标记、事件日志聚合高水位和最近重建错误
+
+`WorkflowStatsStorage` 定义这些路径和保留策略。UI 读取时优先加载 `daily.jsonl`;如果聚合文件缺失、为空、事件日志高水位不一致或已标记为 dirty,会先尝试后台重建,重建失败时再回退读取 `events.jsonl` 末尾 5MB 生成临时快照。
+
+## 写入事务
+
+Hook 可能由多个 Codex 进程并发触发。`WorkflowHookEventRecorder` 会在同一个 `flock(LOCK_EX)` 中完成轻量写入事务:
+
+1. 追加当前事件到 `events.jsonl`
+2. 如当天第一次写入,裁剪超过 210 天的 `events.jsonl` 并更新 `maintenance.json` 中的维护日期
+3. 如果 `daily.jsonl` 可信,增量更新当天聚合并记录 `lastAggregatedEventLogSize`
+4. 如果发现 `daily.jsonl` 缺失、为空、事件日志高水位不一致或之前已标记 dirty,只写入 `needsDailyRebuild = true`
+
+这样可以避免并发写入导致 `events.jsonl` 或 `daily.jsonl` 丢失数据,也避免在 Hook timeout 内执行全量重建。
+
+`WorkflowStatsService` 在 App 自动刷新、手动刷新或打开 popover 读取工作流统计时检查 `maintenance.json`。如果 `needsDailyRebuild = true` 或事件日志高水位不一致,会在 `CodexBar.workflow-stats` 后台队列中从 `events.jsonl` 重建 `daily.jsonl`。重建时逐行容错,坏行会被跳过并计入 `corruptEventLineCount`; 重建失败时保留旧 `daily.jsonl` 和 dirty 标记, 下次刷新继续重试。
+
+## 保留策略
+
+CodexBar 最多保留最近 210 天数据。
+
+最近 7 天的每日聚合保留 `sessionIds` 和 `turnIds`,用于继续去重。7 天前的日期会把 ID 集合压缩成 `sessionCount` 和 `turnCount`,之后不再保存 ID。210 天外的数据会在每天第一次 Hook 写入时删除。
+
+如果 `daily.jsonl` 缺失、为空、事件日志高水位不一致或之前已标记 dirty,Hook 只会标记 `needsDailyRebuild`; 后续 App 自动刷新、手动刷新或打开 popover 时由后台服务重建每日聚合。
+
+## 统计口径
+
+`events.jsonl` 是统计源。重建或增量更新 `daily.jsonl` 时,每条事件先按 `timestamp` 落到本地时区的自然日,再按 `event` 名称归类。`event` 归类时会去掉 `_` 和 `-` 并转小写,例如 `PreToolUse`、`pre_tool_use`、`pre-tool-use` 都会归为 `pretooluse`。
+
+能参与统计的事件行必须至少满足:
+
+- `timestamp` 能解析为 ISO8601 时间
+- `event` 是非空字符串
+
+不满足这两个条件的坏行在重建时会被跳过。其他字段缺失不会阻断统计,只会影响依赖该字段的去重或项目统计。
+
+从 `events.jsonl` 到页面指标的判定规则如下:
+
+| 页面展示名 | 会被计入的 `events.jsonl` 行 | 不会计入的典型情况 | 计数方式 |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| 会话总数 | 最近 7 天内,任意带非空 `session` 的事件行都会把该 `session` 加入当天去重集合;另外 `event` 归一化为 `sessionstart` 的行会增加 `sessionStartCount`。 | `session` 为 `null` 且 `event` 不是 `SessionStart`;坏行。 | `max(sessionCount ?? 0, sessionIds.count, sessionStartCount)` |
+| 对话轮次 | 最近 7 天内,任意带非空 `turn` 的事件行都会把该 `turn` 加入当天去重集合;另外 `event` 归一化为 `stop` 的行会增加 `stopCount`。 | `turn` 为 `null` 且 `event` 不是 `Stop`;坏行。 | `max(turnCount ?? 0, turnIds.count, stopCount)` |
+| 子智能体 | `event` 归一化为 `subagentstart` 或 `subagentstop` 的行。 | 其他事件名;坏行。 | `max(subagentStartCount, subagentStopCount)` |
+| 工具调用 | `event` 归一化为 `pretooluse` 的行会增加 `preToolUseCount`;归一化为 `posttooluse` 的行会增加 `postToolUseCount`。`tool` 可以是具体工具名,也可以是 `null`。 | `SessionStart` 这类非工具事件,即使 `tool` 是 `null` 或存在也不会计入;坏行。 | `max(preToolUseCount, postToolUseCount)` |
+| 权限请求 | `event` 归一化为 `permissionrequest` 的行。 | `permission` 字段本身不会触发计数;只有事件名是 `PermissionRequest` 才计入。 | `permissionRequestCount` |
+| 上下文压缩 | `event` 归一化为 `precompact` 或 `postcompact` 的行。 | 其他事件名;坏行。 | `max(preCompactCount, postCompactCount)` |
+
+逐字段统计口径如下:
+
+| `daily.jsonl` 字段 | 从 `events.jsonl` 读取什么 | 写入 / 更新规则 | 页面关系 |
+| ------------------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `date` | `timestamp` | 先把事件时间解析为绝对时间,再用 `Calendar.current.startOfDay(for:)` 落到当前本地时区的自然日,最后格式化为 `yyyy-MM-dd`。同一天所有事件合并到同一行。早于最近 210 天保留窗口的事件不会进入聚合。 | 热力图日期键;tooltip 日期。 |
+| `eventCount` | 每条成功解码并保留下来的事件行 | 每处理一条事件就 `+1`,发生在具体事件类型判断之前。因此 `UserPromptSubmit`、未知 `event`、`tool: null`、`session: null` 等行都会计入,只要 `timestamp` 和 `event` 可解析。 | 进入 `WorkflowDailyStats.eventCount`,当前页面不展示。 |
+| `sessionStartCount` | `event` | `event` 归一化后等于 `sessionstart` 时 `+1`。不要求 `session` 非空。 | 作为「会话总数」兜底来源。 |
+| `stopCount` | `event` | `event` 归一化后等于 `stop` 时 `+1`。不要求 `turn` 非空。 | 作为「对话轮次」兜底来源。 |
+| `preToolUseCount` | `event` | `event` 归一化后等于 `pretooluse` 时 `+1`。不读取 `tool` 做过滤,`tool` 为 `null` 也计入。 | 参与「工具调用」。 |
+| `postToolUseCount` | `event` | `event` 归一化后等于 `posttooluse` 时 `+1`。不读取 `tool` 做过滤,`tool` 为 `null` 也计入。 | 参与「工具调用」。 |
+| `permissionRequestCount` | `event` | `event` 归一化后等于 `permissionrequest` 时 `+1`。不读取 `permission` 字段做过滤,`permission` 只是记录当时的权限模式。 | 直接显示为「权限请求」。 |
+| `preCompactCount` | `event` | `event` 归一化后等于 `precompact` 时 `+1`。 | 参与「上下文压缩」。 |
+| `postCompactCount` | `event` | `event` 归一化后等于 `postcompact` 时 `+1`。 | 参与「上下文压缩」。 |
+| `subagentStartCount` | `event` | `event` 归一化后等于 `subagentstart` 时 `+1`。 | 参与「子智能体」。 |
+| `subagentStopCount` | `event` | `event` 归一化后等于 `subagentstop` 时 `+1`。 | 参与「子智能体」。 |
+| `sessionIds` | `session` | 仅最近 7 个本地自然日保留。任意事件行只要 `session` 是非空字符串,就插入当天集合并去重、排序;不要求事件类型是 `SessionStart`。超过 7 天后会被压缩为 `sessionCount` 并写成 `null` / 缺失。 | 参与「会话总数」去重。 |
+| `turnIds` | `turn` | 仅最近 7 个本地自然日保留。任意事件行只要 `turn` 是非空字符串,就插入当天集合并去重、排序;不要求事件类型是 `Stop`。超过 7 天后会被压缩为 `turnCount` 并写成 `null` / 缺失。 | 参与「对话轮次」去重。 |
+| `sessionCount` | `sessionIds`、旧 `sessionCount`、`sessionStartCount` | 最近 7 天通常为 `null`;日期进入 7 天外窗口后,归一化时写成 `max(sessionCount ?? 0, sessionIds.count, sessionStartCount)`,然后移除 `sessionIds`。这样旧日期不用继续保存完整 ID,也能保留会话总数。 | 参与「会话总数」。 |
+| `turnCount` | `turnIds`、旧 `turnCount`、`stopCount` | 最近 7 天通常为 `null`;日期进入 7 天外窗口后,归一化时写成 `max(turnCount ?? 0, turnIds.count, stopCount)`,然后移除 `turnIds`。这样旧日期不用继续保存完整 ID,也能保留轮次总数。 | 参与「对话轮次」。 |
+| `projectCounts` | `cwd` | 任意事件行只要 `cwd` 非空,就取标准化路径的最后一层目录名作为项目名并 `+1`;如果最后一层为空,回退使用完整路径字符串。统计的是事件数,不是会话数或工具调用数。未知事件也会计入。 | 用于计算 `mostActiveProject`,当前页面不展示。 |
+
+读取旧 `daily.jsonl` 时,缺失的数字字段按 `0` 处理,缺失的 `projectCounts` 按空字典处理,缺失的 `sessionIds` / `turnIds` / `sessionCount` / `turnCount` 保持为 `nil`。后续归一化会按当前保留策略补齐或压缩这些字段。
+
+UI 不直接展示所有原始字段,而是先生成 `WorkflowDailyStats`:
+
+| 页面展示名 | 生成规则 |
+| ---------- | ------------------------------------------------------------- |
+| 会话总数 | `max(sessionCount ?? 0, sessionIds.count, sessionStartCount)` |
+| 对话轮次 | `max(turnCount ?? 0, turnIds.count, stopCount)` |
+| 子智能体 | `max(subagentStartCount, subagentStopCount)` |
+| 工具调用 | `max(preToolUseCount, postToolUseCount)` |
+| 权限请求 | `permissionRequestCount` |
+| 上下文压缩 | `max(preCompactCount, postCompactCount)` |
+
+`mostActiveProject` 和 `eventCount` 会进入 `WorkflowDailyStats`,但当前页面没有展示。`UserPromptSubmit` 和未知事件不会增加上述 6 个页面指标,只会进入 `eventCount`,有 `cwd` 时也会进入 `projectCounts`。
+
+## UI 展示
+
+用量热力图固定为近 30 周、30 列 x 7 行、周日到周六排列。`account/usage/read` 返回当天 `dailyUsageBuckets` 时, 热力图展示今天的小方块和对应 token 数; 没有当天 bucket 时再按 Hook 开关决定是否包含今天。
+
+Codex Hook 关闭时:
+
+- 默认不包含今天
+- tooltip 只显示日期和 token 数
+- tooltip 使用较窄宽度
+
+Codex Hook 开启时:
+
+- 热力图包含今天
+- 没有当天 token bucket 时, 今天的 token 数显示为 `--`
+- tooltip 首行左侧显示日期、右侧显示 token 数
+- 后续逐行显示「会话总数」、「对话轮次」、「子智能体」、「工具调用」、「权限请求」、「上下文压缩」
diff --git a/README.md b/README.md
index 7a8fd0e..d03da18 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,8 @@
# CodexBar
-> 在 macOS 菜单栏实时查看 Codex 账号额度和 token 用量。
+> 在 macOS 菜单栏实时查看 Codex 账号额度、token 用量和工作流数据统计。
-CodexBar 是一个轻量级 macOS 菜单栏应用。它直接连接本机 Codex 的 app-server,定期读取额度信息,让你不用打开终端就能随时知道: 还剩多少额度、什么时候重置、最近用了多少 token。
+CodexBar 是一个轻量级 macOS 菜单栏应用。它直接连接本机 Codex 的 app-server,定期读取额度信息;也可以通过 Codex Hook 记录本机工作流数据,让你不用打开终端就能随时知道: 还剩多少额度、什么时候重置、最近用了多少 token,以及今天的会话、对话轮次、工具调用等情况。
<p align="center">
<img src="Images/screenshot.png" alt="CodexBar" width="532">
@@ -11,10 +11,11 @@ CodexBar 是一个轻量级 macOS 菜单栏应用。它直接连接本机 Codex
## 特性
- **额度一目了然**: 分段电量条展示各时间窗口 (如 5 小时、7 天) 的剩余额度,附剩余百分比和重置时间
-- **token 贡献墙**: 展示近 30 周的每日 token 用量热力图,鼠标悬停可查看单日明细
+- **用量热力图**: 展示近 30 周的每日 token 用量,鼠标悬停可查看单日明细
+- **详细统计**: 开启 Codex Hook 后,热力图会展示会话总数、对话轮次、子智能体调用次数、工具调用次数、权限请求次数和上下文压缩次数
- **自动刷新**: 每分钟后台刷新一次,弹窗未打开也保持最新;双击账号图标可手动刷新
- **自动更新**: 内置 Sparkle 更新检查,新版本自动更新
-- **本地优先**: 只与本机 Codex app-server 进程通信,不向任何第三方服务发送账号或额度数据
+- **本地优先**: 只与本机 Codex app-server 进程通信,不向任何第三方服务发送账号、额度、token 或工作流统计数据
## 安装
@@ -32,6 +33,35 @@ CodexBar 是一个轻量级 macOS 菜单栏应用。它直接连接本机 Codex
> 提示: 如果把应用移动到 `/Applications` 后才开启开机自启,建议重新开关一次「开机启动」让 macOS 记录最终路径。
+## 启用 Codex Hook
+
+CodexBar 可以在设置中开启「启用 Codex Hook」
+
+开启后会在全局 `~/.codex/hooks.json` 中增加以下 Hook,用于接收 Codex 的会话、工具调用、权限请求、上下文压缩和子智能体事件。
+
+- `SessionStart`: 记录一次 Codex 会话开始,用于统计会话总数
+- `UserPromptSubmit`: 记录用户提交提示词事件,保留为原始活动事件
+- `PreToolUse`: 记录工具调用开始
+- `PostToolUse`: 记录工具调用结束,和 `PreToolUse` 一起用于统计工具调用次数
+- `PermissionRequest`: 记录 Codex 发起权限请求的次数
+- `PreCompact`: 记录上下文压缩开始
+- `PostCompact`: 记录上下文压缩结束,和 `PreCompact` 一起用于统计上下文压缩次数
+- `Stop`: 记录一次回复/任务结束,用于统计对话轮次
+- `SubagentStart`: 记录子智能体开始
+- `SubagentStop`: 记录子智能体结束,和 `SubagentStart` 一起用于统计子智能体次数
+
+每个事件都会追加一个 `command` 类型的 Hook,命令形如:
+
+```bash
+'/Applications/CodexBar.app/Contents/MacOS/CodexBar' --hook-event SessionStart
+```
+
+开启后,用量热力图会包含今天;鼠标悬停到任意一天时,弹窗会在 token 数之外展示当天的会话总数、对话轮次、子智能体、工具调用、权限请求和上下文压缩次数。关闭 Hook 时,弹窗只展示日期和 token 数;如果 app-server 尚未返回当天 token 数据,热力图不会额外占位展示今天。
+
+CodexBar 只会追加或移除自己安装的 Hook,不会删除你已有的其他 Codex Hook。
+
+统计数据只保存在本机 `~/Library/Application Support/CodexBar/HookEvents/`,不会发送给任何个人或第三方服务。
+
## 从源码构建
```bash
@@ -48,12 +78,12 @@ Swift 源码按职责放在 `CodexBar/` 下的子目录中:
- `App/`: 应用入口
- `Controllers/`: 菜单栏、popover 和独立窗口控制器
-- `Models/`: account、quota、usage 和错误分类模型
-- `Services/`: app-server 会话、Codex CLI 解析、版本探测、开机自启和 Sparkle 更新
+- `Models/`: account、quota、usage、工作流统计、共享日期网格和错误分类模型
+- `Services/`: app-server 会话、Codex CLI 解析、版本探测、Hook 设置、工作流统计、开机自启和 Sparkle 更新
- `Views/`: 菜单栏弹窗、设置窗口、日志窗口和共享 Liquid Glass 样式
## 隐私
-CodexBar 只与本机 Codex app-server 进程通信。账号信息和额度数据不会被收集或发送给任何个人或服务。
+CodexBar 只与本机 Codex app-server 进程通信。账号信息、额度数据、token 用量和 Hook 工作流数据不会被收集或发送给任何个人或服务。
只有检查和下载 App 更新时会产生额外网络请求,请求范围仅包含 [appcast](https://codexbar.zabrian.app/appcast.xml) 和 appcast 中对应的 DMG 下载地址。
diff --git a/appcast.xml b/appcast.xml
index e8a2bfe..8ba386e 100644
--- a/appcast.xml
+++ b/appcast.xml
@@ -7,6 +7,15 @@
<link>https://codexbar.zabrian.app/appcast.xml</link>
<description>CodexBar appcast feed</description>
<language>zh-CN</language>
+ <item>
+ <title>CodexBar.app 2.3.0</title>
+ <sparkle:version>13</sparkle:version>
+ <sparkle:shortVersionString>2.3.0</sparkle:shortVersionString>
+ <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+ <sparkle:releaseNotesLink>https://codexbar.zabrian.app/notes/2.3.0.html</sparkle:releaseNotesLink>
+ <pubDate>Sun, 21 Jun 2026 11:46:37 +0800</pubDate>
+ <enclosure url="https://codexbar.zabrian.app/download/CodexBar-v2.3.0.dmg" sparkle:edSignature="n8vjt1rxRaJwa261pU5Fo0BNaETL6nygdfkLLfnK+K+fd1XWk8SJMzVCp/w536MTWtSN8W3+L118jCb8LV+QDA==" length="2849403" type="application/octet-stream"/>
+ </item>
<item>
<title>CodexBar.app 2.2.0</title>
<sparkle:version>12</sparkle:version>