Skip to content

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

docs: 增加开发流程文档

Bob42ecf690186d
diff --git a/Docs/DevelopmentGuide.md b/Docs/DevelopmentGuide.md
new file mode 100644
index 0000000..5a15d59
--- /dev/null
+++ b/Docs/DevelopmentGuide.md
@@ -0,0 +1,915 @@
+# CodexBar 开发文档
+
+本文面向继续开发 CodexBar 的维护者, 记录当前 App 的主要流程, 数据边界和模块协作方式
+
+更细的 app-server 协议见 [AppServer.md](AppServer.md), Codex Hook 统计口径见 [CodexHook.md](CodexHook.md)
+
+## 1. 应用定位与工程边界
+
+CodexBar 是一个 macOS 菜单栏应用, 使用 SwiftUI + AppKit + MVVM
+
+App 通过本机 Codex app-server 读取账号, 额度和 token 用量, 通过 Codex Hook 记录本机工作流事件, 并把这些数据展示在菜单栏 popover, 设置窗口和日志窗口中
+
+关键边界:
+
+- 应用形态是 `LSUIElement`, 不显示 Dock 图标, 不依赖主窗口
+- 最低系统版本是 macOS 15.0
+- App Sandbox 保持关闭, 因为需要启动本机 `codex`, 读取真实用户 Codex 登录状态, 并写入用户级 Hook 配置
+- 除 Sparkle 检查和下载更新外, App 自身不发起网络请求
+- 账号, 额度, token 用量和 Hook 工作流统计都只在本机处理, 不发送给第三方
+- Swift 工程开启 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`, 服务和模型中需要被后台队列同步访问的类型显式使用 `nonisolated`
+
+源码目录职责:
+
+| 目录 | 职责 |
+| ----------------------- | ----------------------------------------------------------------------- |
+| `CodexBar/App/` | SwiftUI 入口和 AppDelegate 启动分支 |
+| `CodexBar/Controllers/` | 菜单栏, popover, 设置窗口, 日志窗口和窗口行为 |
+| `CodexBar/Models/` | account, quota, usage, workflow stats, 日期网格和错误模型 |
+| `CodexBar/Services/` | app-server, Codex CLI 解析, 版本探测, Hook 设置, 统计维护, 更新, 登录项 |
+| `CodexBar/Views/` | popover, 设置窗口, 日志窗口和共享 Liquid Glass 样式 |
+| `Docs/` | app-server, Hook 和开发文档 |
+| `Scripts/` | DMG 和 appcast 发布脚本 |
+
+## 2. 总体架构
+
+两条主数据链路:
+
+- Codex app-server 链路: `CodexStatusService` 启动或复用本机 app-server, 生成 `CodexQuotaSnapshot`, 由 `CodexStatusViewModel` 发布给菜单栏 UI
+- Codex Hook 链路: Codex 进程触发 Hook 命令, CodexBar 以 `--hook-event` 模式快速写入 JSONL; 主 App 后续维护聚合并生成 `WorkflowStatsSnapshot`
+
+## 3. 启动流程
+
+入口在 `CodexBar/App/CodexBarApp.swift`
+
+`CodexBarApp.init()` 最先调用 `WorkflowHookEventRecorder.handleIfRequested()`, 用于区分普通 App 启动和 Hook 子进程启动
+
+```mermaid
+sequenceDiagram
+ participant OS as macOS
+ participant App as 启动分流
+ participant Hook as Hook 记录器
+ participant Delegate as App 启动协调
+ participant Controller as 菜单栏控制器
+ participant VM as 账号额度状态
+
+ OS->>App: 启动 CodexBar
+ App->>Hook: 检查是否为 Hook 记录模式
+ alt Hook 记录模式
+ Hook->>Hook: 读取标准输入并写入本机事件
+ App-->>OS: 正常退出
+ else 普通菜单栏启动
+ App->>Delegate: 进入 App 启动流程
+ Delegate->>Controller: 创建菜单栏控制器
+ Controller->>Controller: 安装菜单栏按钮和 popover
+ Controller->>VM: 启动自动刷新
+ end
+```
+
+普通启动时, `CodexBarAppDelegate` 创建四个长期对象:
+
+- `CodexStatusViewModel`: app-server 刷新状态
+- `WorkflowStatsViewModel`: Hook 工作流统计快照
+- `CodexHookSettings`: Hook 配置状态和写入操作
+- `AppUpdater`: Sparkle 更新状态
+
+`StatusItemController.install()` 负责:
+
+- 配置菜单栏按钮图标, tooltip 和点击事件
+- 配置 popover 的 SwiftUI 根视图
+- 订阅状态变化并切换菜单栏图标
+- 开始每 60 秒自动刷新
+
+App 退出时, `applicationWillTerminate` 调用 `StatusItemController.uninstall()`, 关闭 popover, 移除订阅并从系统状态栏移除 status item
+
+## 4. 菜单栏, Popover 与窗口流程
+
+菜单栏按钮由 `NSStatusBar.system.statusItem(withLength:)` 创建
+
+正常图标是 `person.fill.checkmark`, 错误图标是 `person.fill.xmark`
+
+错误图标触发条件:
+
+- `loadState` 是 `.notLoggedIn` 或 `.initializationFailed`
+- 当前 snapshot 没有可信额度和用量数据, 即 `snapshot?.hasTrustedData == false`
+
+点击行为:
+
+| 操作 | 行为 |
+| ---------------- | ---------------- |
+| 左键点击 | 切换 popover |
+| 右键点击 | 打开上下文菜单 |
+| Control + 点击 | 打开上下文菜单 |
+| 上下文菜单"设置" | 打开独立设置窗口 |
+| 上下文菜单"日志" | 打开独立日志窗口 |
+| 上下文菜单"退出" | 终止 App |
+
+打开 popover 的顺序:
+
+- 取消正在等待的延迟刷新和淡入淡出任务
+- 设置状态为 `opening`, 准备透明度淡入
+- 显示 `NSPopover`, 把 `PopoverVisibilityState.isVisible` 设为 `true`
+- 调用 `refreshWorkflowStatsIfHookEnabled(performMaintenance: false)`, 只读取已有 `daily.jsonl`, 不做重维护
+- 安装 `PopoverDismissMonitor`
+- 执行 0.24 秒淡入
+- 延迟 160 ms 后调用 `viewModel.refreshIfNeeded()`
+
+关闭 popover 的顺序:
+
+- 移除本地和全局事件监听
+- 将 `isVisible` 设为 `false`, 让倒计时停止 `TimelineView` 每秒 tick
+- 默认执行 0.18 秒淡出, 无法淡出时直接关闭
+
+`PopoverDismissMonitor` 监听这些 dismiss 条件:
+
+- popover 外部鼠标点击
+- Escape
+- Command-Tab 或 Command-Space 等系统切换快捷键
+- App 失去 active
+- 其他应用被激活
+- popover window 失去 key
+
+设置窗口和日志窗口都继承 `HostingWindowController` 的行为: 懒创建, 关闭后不释放, 重新打开复用, 按当前屏幕居中, 重新打开时移动到当前桌面并置前
+
+## 5. Codex 状态刷新流程
+
+刷新入口在 `CodexStatusViewModel`:
+
+- `startAutoRefresh()` 先尝试一次 `refreshIfNeeded()`, 之后按 `autoRefreshDelay` 循环
+- 刷新间隔是 60 秒
+- `refreshIfNeeded()` 会比较 `autoRefreshCountdownStartedAt`, 避免 popover 打开和自动刷新同时触发重复请求
+- `refresh()` 通过 `isRefreshing` 防重入
+
+下面的时序图展示刷新, app-server 握手, 额度与用量读取, 以及常见错误后的重试或降级
+
+```mermaid
+sequenceDiagram
+ participant UI as 刷新入口
+ participant State as 后台状态服务
+ participant Finder as Codex 命令解析
+ participant Pipe as 标准输入输出会话
+ participant Server as 本机 Codex 服务
+ participant Cache as 同账号旧缓存
+ participant Log as 请求日志
+
+ UI->>State: 请求刷新账号, 额度和用量
+ State->>State: 进入串行队列并检查连接是否可复用
+
+ alt 没有可复用连接
+ State->>Finder: 查找全局 Codex 或 App 内置 Codex
+ alt 找不到可执行文件
+ Finder-->>State: 返回无法启动
+ State->>Log: 记录初始化失败原因
+ State-->>UI: 显示初始化失败
+ else 找到可执行文件
+ Finder-->>State: 返回启动路径和来源
+ State->>Server: 启动本机 app-server
+ alt 进程启动失败
+ State->>Log: 记录启动失败
+ State-->>UI: 显示初始化失败
+ else 进程启动成功
+ State->>Pipe: 建立标准输入输出会话
+ Pipe->>Log: 记录初始化请求
+ Pipe->>Server: 初始化客户端
+ alt 初始化失败或响应无法解析
+ Pipe->>Log: 回填错误
+ State->>Pipe: 关闭会话
+ State-->>UI: 显示初始化失败
+ else 初始化成功
+ Server-->>Pipe: 返回运行版本
+ Pipe->>Server: 发送初始化完成通知
+ Pipe->>Log: 记录无响应通知
+ Pipe->>Server: 读取当前账号
+ alt 当前账号为空
+ Server-->>Pipe: 返回未登录状态
+ State->>Pipe: 关闭会话
+ State-->>UI: 显示未登录
+ else 当前账号有效
+ Server-->>Pipe: 返回账号状态
+ end
+ end
+ end
+ end
+ else 复用现有连接
+ State->>Pipe: 读取当前账号确认登录状态
+ alt 账号为空
+ State->>Cache: 清空同账号旧缓存
+ State->>Pipe: 关闭会话
+ State-->>UI: 显示未登录
+ else 账号有效
+ Pipe-->>State: 继续读取补充数据
+ end
+ end
+
+ opt 账号有效
+ State->>Pipe: 请求额度数据
+ alt 认证过期
+ State->>Pipe: 刷新登录凭据一次
+ alt 刷新后仍失败
+ State->>Cache: 清空同账号旧缓存
+ State->>Pipe: 关闭会话
+ State-->>UI: 显示未登录
+ else 刷新成功
+ State->>Pipe: 重试额度读取
+ end
+ else 方法不支持
+ State->>Log: 记录不支持的接口
+ State->>State: 本连接后续跳过额度接口
+ else 业务错误
+ State->>Pipe: 立即重试一次
+ alt 重试仍失败且有旧缓存
+ State->>Cache: 复用旧额度并标记陈旧
+ else 重试仍失败且没有旧缓存
+ State->>Log: 只保留错误日志
+ end
+ else 传输错误或超时
+ State->>Pipe: 关闭会话
+ State->>Server: 重建连接并只重试一次
+ else 读取成功
+ State->>Cache: 更新额度缓存
+ end
+
+ State->>Pipe: 请求 token 用量
+ alt 认证过期
+ State->>Pipe: 刷新登录凭据一次
+ alt 刷新后仍失败
+ State->>Cache: 清空同账号旧缓存
+ State->>Pipe: 关闭会话
+ State-->>UI: 显示未登录
+ else 刷新成功
+ State->>Pipe: 重试用量读取
+ end
+ else 方法不支持
+ State->>Log: 记录不支持的接口
+ State->>State: 本连接后续跳过用量接口
+ else 业务错误或临时失败
+ State->>Pipe: 立即重试一次
+ alt 重试仍失败且有旧缓存
+ State->>Cache: 复用旧用量并标记陈旧
+ else 重试仍失败且没有旧缓存
+ State->>Log: 只保留错误日志
+ end
+ else 传输错误或超时
+ State->>Pipe: 关闭会话
+ State->>Server: 重建连接并只重试一次
+ else 读取成功
+ State->>Cache: 更新用量缓存
+ end
+
+ State->>State: 合成账号快照
+ State-->>UI: 更新 loaded, 数据和倒计时
+ end
+```
+
+`CodexStatusService` 的连接策略:
+
+- 所有连接状态只在 `CodexBar.app-server` 串行队列上访问
+- 请求超时是 20 秒
+- 连接最大复用时间是 1 小时, 超过后重建, 便于后台升级后的 `codex` 二进制生效
+- 忽略 `SIGPIPE`, 断管由 `write` 抛错后走连接重建
+- 复用连接发生传输故障时只重建并重试一次, 避免故障状态下反复拉起进程
+- 新连接初始化失败直接返回 `.initializationFailed`
+
+`CodexFetchOutcome` 只向 UI 暴露三种结果:
+
+| outcome | UI 状态 |
+| ----------------------- | -------------------------------------- |
+| `.data(snapshot)` | `.loaded` 并展示数据 |
+| `.notLoggedIn` | `.notLoggedIn`, snapshot 清空 |
+| `.initializationFailed` | `.initializationFailed`, snapshot 清空 |
+
+更细的启动失败, 请求失败, 超时, 断连, 解析失败, 业务错误都只进入请求日志
+
+## 6. app-server 会话与日志
+
+app-server 启动命令必须通过 `CodexCLIResolver.resolveAppServerCommand()` 解析, 最终参数是:
+
+```bash
+codex app-server --listen stdio://
+```
+
+解析优先级:
+
+- PATH 中的全局 `codex`
+- 如果 PATH 中的 `codex` 等价于 `/Applications/Codex.app/Contents/Resources/codex`, 它被视为 Codex APP 内置 CLI, 不算全局 CLI
+- 全局 CLI 不存在时回退 Codex APP 内置 CLI
+- 两者都不存在时抛出 `CodexStatusError.executableNotFound`
+
+环境变量由 `CodexCLIResolver.environment` 构造:
+
+- 保留当前环境
+- `HOME` 使用 `getpwuid(getuid())` 获取真实用户 home
+- 同步设置 `USER` 和 `LOGNAME`
+- 合并 Homebrew, npm global, `.local`, Volta 和系统路径
+- 确保 `TERM` 有值
+
+`AppServerSession` 负责 JSON-RPC 读写:
+
+- 每个带 id 的请求先写入 `RequestLogStore.beginRequest`
+- 请求 JSON 使用 sorted keys 和不转义斜杠序列化
+- 写入 stdin 时追加换行
+- `JSONLineReader` 从 stdout 读取按行 JSON, 只处理 id 匹配的响应, 其他行忽略
+- 收到 JSON-RPC error 时转成 `CodexStatusError.serverError(message)`
+- 响应不能解析成期望类型时归为 `.invalidServerResponse`
+- `initialized` 是无 id 通知, 不等待响应, 但记录为"请求"
+- `PipeDrain` 只 drain stderr, 不把子进程 stderr 展示给用户
+
+请求错误分类:
+
+| 错误 | 处理 |
+| ---------------------------- | ----------------------------------------------------------------- |
+| 认证失败 | 同一轮最多 `account/read(refreshToken:true)` 一次, 然后重试原读取 |
+| unsupported method | 当前连接记住该 method, 后续跳过 |
+| 非认证业务错误 | `AppServerSession` 先重试同请求一次, 仍失败后不阻断整轮刷新 |
+| 连接断开, 超时, 响应解析失败 | 视为传输故障, 外层重建连接 |
+
+`RequestLogStore` 是常驻全局日志:
+
+- 容量上限 500 条
+- 单条详情上限 4000 字符
+- 合法 JSON 会稳定化显示, 非 JSON 错误消息保持原样
+- storage 用 `NSLock` 保护, SwiftUI 通知切回主线程发送
+- 日志窗口关闭不会清空日志
+
+日志状态标签:
+
+| Kind | UI 标签 |
+| ---------------- | ------- |
+| `.pending` | 进行 |
+| `.response` | 完成 |
+| `.failure` | 错误 |
+| `.emptyResponse` | 请求 |
+
+## 7. 错误处理总览
+
+错误处理的基本原则:
+
+- Popover 只展示"未登录"和"初始化失败"两类特殊状态
+- 具体启动失败, 请求失败, 超时, 断连, 解析失败和业务错误进入日志窗口
+- 账户有效时, rate limits 和 usage 可以单独失败, 失败区域按缓存或无数据处理
+- 涉及本机配置写入的错误显示在设置窗口底部状态区
+- Hook 子进程尽量快速退出, 事件记录失败不会阻断 Codex 自身流程
+
+app-server 与状态刷新错误:
+
+| 错误来源 | 检测位置 | 用户可见状态 | 日志或存储 | 重试或降级 |
+| -------------------------------------------- | -------------------------------------------- | ---------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------- |
+| 找不到全局 Codex CLI 和 Codex APP 内置 CLI | `CodexCLIResolver.resolveAppServerCommand()` | `初始化失败` | `RequestLogStore.recordFailure` 记录可读错误 | 不启动 app-server, 下轮刷新重新解析 |
+| app-server 进程启动失败 | `Process.run()` | `初始化失败` | 记录"app-server 启动失败" | 不复用本次进程, 下轮刷新重试 |
+| `initialize` 或首次 `account/read` 失败 | `CodexStatusService.openConnection` | `初始化失败` | 对应 JSON-RPC 请求进入日志 | 关闭本次 session, 不重复完整握手 |
+| 首次 `account/read` 返回 `account == nil` | `CodexStatusService.openConnection` | `未登录` | 请求响应进入日志 | 关闭本次 session, 不生成 snapshot |
+| 复用连接刷新 account 后返回 `account == nil` | `CodexStatusService.fetchData` | `未登录` | 请求响应进入日志 | 清空 supplemental cache, teardown connection |
+| JSON-RPC 认证失败 | `CodexStatusError.isAuthenticationRequired` | 取决于刷新后结果 | 失败响应进入日志 | 同一轮最多 `account/read(refreshToken:true)` 一次, 然后重试原读取 |
+| refresh token 后仍认证失败 | `ReadResult.resultAfterAuthAttempt` | `未登录` | 失败响应进入日志 | 清空 cache, teardown connection |
+| unsupported method | `CodexStatusError.isUnsupportedMethod` | 对应区域可能显示无数据 | 失败响应进入日志 | 当前 session 记住 method, 后续跳过, 不复用旧缓存 |
+| 非认证业务错误 | `CodexStatusError.isRetriableServerError` | 通常不改变整体状态 | 失败响应进入日志 | 同请求立即重试一次, 仍失败则 supplemental 读取按失败处理 |
+| rate limits 读取失败 | `CodexStatusService.cachedRead` | 有旧缓存时区域半透明, 无旧缓存时无额度区 | 失败进入日志 | 同账号旧缓存复用并标记 `isRateLimitsStale` |
+| usage 读取失败 | `CodexStatusService.cachedRead` | 有旧缓存时区域半透明, 无旧缓存时无用量区 | 失败进入日志 | 同账号旧缓存复用并标记 `isUsageStale` |
+| 连接断开, 请求超时, 响应解析失败 | `CodexStatusError.isTransportFailure` | 复用连接重建失败后为 `初始化失败` | 请求标记为错误 | 复用连接只重建重试一次, 新连接失败不再重试 |
+| app-server 关闭超时 | `AppServerSession.close()` | 不直接改变 UI | 记录强制结束或仍在后台运行 | 先 terminate 等 1 秒, 再 SIGKILL 等 0.5 秒 |
+| snapshot 无可信 quota 和 usage | `CodexQuotaSnapshot.hasTrustedData` | 菜单栏切换错误图标 | 不新增日志 | 仍可展示 stale 数据或无数据面板 |
+
+日志错误处理:
+
+| 场景 | 行为 |
+| ------------------------ | ------------------------------------ |
+| 请求发送后等待响应 | 日志先显示"进行" |
+| 收到正常响应 | 回填同一条日志为"完成" |
+| 请求失败或响应解析失败 | 回填同一条日志为"错误" |
+| `initialized` 无 id 通知 | 记录为"请求", 不等待响应 |
+| 进程级错误没有 method | 日志行直接预览错误文本 |
+| 合法 JSON 内容 | 重新序列化为稳定顺序并保留未转义斜杠 |
+| 超长详情 | 截断到 4000 字符 |
+
+设置, Hook 和更新错误:
+
+| 错误来源 | 检测位置 | 用户可见状态 | 重试或降级 |
+| -------------------------------- | -------------------------------------------------------- | -------------------------------------- | ------------------------------------------------ |
+| 登录项注册或取消失败 | `LoginItemSettings.setEnabled` | 设置窗口底部显示"设置开机启动失败" | 调用 `refresh()` 恢复实际状态 |
+| `hooks.json` 读取失败或结构非法 | `CodexHookSettings.refresh` | Hook 开关视为关闭, 底部显示读取失败 | 不写配置 |
+| Hook 开关写入失败 | `CodexHookSettings.setEnabled` | 底部显示"设置 Codex Hook 失败" | 调用 `refresh()` 恢复实际状态 |
+| Hook 子进程 payload 不是 JSON | `WorkflowHookEventRecorder.stdinPayload` | 无 UI 提示 | 使用空 payload 和 fallback 字段继续记录 |
+| Hook 子进程写入失败 | `WorkflowHookEventRecorder.handleIfRequested` | 无 UI 提示 | `try? record` 吞掉错误并正常退出, 避免阻断 Codex |
+| `daily.jsonl` 缺失, 空文件或坏行 | `WorkflowStatsService.prepareMaintenanceTasksOnQueue` | tooltip 可能暂时显示 0 | 标记 dirty, 后续从 events 文件重建 |
+| events 文件变小或 offset 不一致 | `WorkflowStatsService.reconcileEventFiles` | tooltip 可能暂时显示旧聚合 | 标记 dirty, 从头重建当天聚合 |
+| 单个维护任务失败 | `WorkflowStatsService.performMaintenanceIfNeededOnQueue` | 使用已有 daily 或空 snapshot | 对应日期标记 dirty |
+| Sparkle 配置缺失 | `AppUpdater.init` | 更新开关禁用, 操作显示"未配置更新资源" | 不创建 updater controller |
+| 手动检查没有更新 | `updaterDidNotFindUpdate` | 显示"没有可用更新" | 1 秒后自动清理状态 |
+| 手动检查失败 | `didAbortWithError` | 显示"检查更新失败" | 不展示底层错误细节 |
+
+Codex 版本探测错误:
+
+| 错误来源 | 显示文本 | 处理 |
+| ------------------------------- | ---------------------------------------- | ----------------------------------------- |
+| 对应安装源不存在 | `未找到 Codex CLI` 或 `未找到 Codex APP` | 不启动探测进程 |
+| `codex --version` 启动失败 | `启动失败` | 该来源显示错误, 另一个来源继续 |
+| 版本探测超时 | `读取超时` | terminate 后 SIGKILL, 停止 pipe collector |
+| 进程退出码非 0 | `读取失败` | 不展示 stderr 细节 |
+| stdout 和 stderr 都没有可用版本 | `版本未知` | 保留路径, 版本列显示错误 |
+
+发布脚本错误:
+
+| 脚本 | 失败条件 | 行为 |
+| -------------------- | --------------------------------------------------------------- | -------------------------------------- |
+| `Scripts/dmg.sh` | 找不到唯一 App, 版本号缺失, DMG 挂载失败, 缺少必要命令 | `set -euo pipefail` 直接退出并打印错误 |
+| `Scripts/appcast.sh` | 找不到 DMG, appcast, Xcode 工程, build setting 或 `sign_update` | 直接退出并打印错误 |
+| `Scripts/appcast.sh` | 无法解析 `sparkle:edSignature` | 打印 sign_update 原始输出并退出 |
+| `Scripts/appcast.sh` | appcast 缺少插入点或 XML 校验失败 | 退出, 不继续发布 |
+
+## 8. Snapshot 合成流程
+
+`CodexQuotaSnapshot` 是 popover 展示 app-server 数据的唯一入口
+
+它由 `AccountReadResponse`, 可选的 `AccountRateLimitsResponse` 和可选的 `AccountUsageResponse` 合成
+
+账户规则:
+
+- `AccountReadResponse.account` 必须存在, 否则视为未登录
+- 账户存在时, 即使 rate limits 和 usage 都没有数据, 也生成 snapshot, 让 UI 展示"暂无数据"
+- `CodexAccount.displayName` 优先使用 email, 没有 email 时按 account type 映射为 `API Key`, `ChatGPT`, `Amazon Bedrock` 或原始 type
+
+额度规则:
+
+- 优先读取 `rateLimitsByLimitId`, 为空时回退顶层 `rateLimits`
+- 顶层 `rateLimits.limitId` 指向的主 limit 置顶, 缺省为 `codex`
+- 其他 limit 按 `limitName ?? limitId` localized standard 排序, 再按 `limitId` 稳定排序
+- 每个 limit 的 `primary` 和 `secondary` 合成 `[QuotaWindow]`
+- 没有窗口的 limit 被过滤
+- `remainingPercent = clamp(100 - usedPercent, 0...100)`
+- `windowDurationMins` 标签按天, 小时, 分钟格式化, 缺失或非正数显示"额度"
+- 本轮 rate limits 请求失败但同账号有旧缓存时复用旧值, 并把 `isRateLimitsStale` 设为 `true`
+
+用量规则:
+
+- `AccountUsageResponse.summary` 提供全时累计, 单日峰值, 当前连胜, 最长连胜, 最长任务
+- `dailyUsageBuckets` 按 `startDate` 汇总 token
+- `CodexUsageSnapshot.recentWeekGrid` 使用 `CodexWeekGrid` 生成周日到周六排列的日期网格
+- 本轮 usage 请求失败但同账号有旧缓存时复用旧值, 并把 `isUsageStale` 设为 `true`
+
+热力图日期规则由 `UsageHeatmapDay.grid` 合并 token 和 workflow stats:
+
+- 固定 30 列 x 7 行
+- Hook 开启时包含今天
+- Hook 关闭但 app-server 已返回当天 token bucket 时包含今天
+- Hook 关闭且没有当天 token bucket 时结束于昨天
+- `nil` 表示未来日期或无法生成日期, UI 不绘制方块, 也不参与峰值计算
+- 今天没有 token bucket 但 Hook 开启时, 今天 token 显示 `--`
+
+## 9. Popover UI 展示流程
+
+`CodexStatusMenuView.menuWidth` 由热力图宽度和 padding 推导:
+
+```swift
+Metrics.padding * 2 + MenuMetrics.panelPadding * 2 + UsageHeatmap.Metrics.totalWidth
+```
+
+UI 状态分支:
+
+```mermaid
+flowchart TD
+ Start["渲染菜单栏弹窗"] --> HasSnapshot{"是否有账号快照"}
+ HasSnapshot -- "否" --> StatusCard["显示未登录或初始化失败"]
+ StatusCard --> Empty["显示暂无数据面板"]
+ HasSnapshot -- "是" --> Account["显示账号和计划"]
+ Account --> HasData{"是否有额度或用量数据"}
+ HasData -- "否" --> Empty2["显示暂无数据面板"]
+ HasData -- "是" --> Quota["按需显示额度区域"]
+ HasData -- "是" --> Usage["按需显示用量区域"]
+ Quota --> Updated["显示数据更新时间"]
+ Usage --> Updated
+ Empty2 --> Updated
+```
+
+账号区:
+
+- 正常状态显示账号, 计划和刷新进度
+- 账号图标双击触发刷新
+- 邮箱文本双击切换模糊显示
+- 计划名是右侧加粗纯文字, 颜色由 `planBadgeTint(for:)` 按 enterprise, team/business, pro, plus, edu, free, 默认 cyan 匹配
+- 没有 snapshot 时只展示"未登录"或"初始化失败"两种特殊状态
+
+额度区:
+
+- 多个 limit 间用 `LiquidGlassDivider` 分隔
+- 每个 quota window 展示标签, 50 段电量条, 剩余百分比和重置时间
+- 重置时间格式为 `MM-dd HH:mm`
+- 无数据时百分比和重置时间显示 `--`, 电量条用占位色
+- stale 数据通过 `.markStale(true)` 降低透明度到 0.55
+
+用量区:
+
+- 指标行展示"全时累计", "单日峰值", "当前连胜", "最长连胜", "最长任务"
+- token 文本由 `TokenCountText` 格式化, 1K 以下完整显示, 1K 起显示 K/M/B
+- 热力图方块强度按当天 token 相对当前 30 周峰值计算, 并用 `pow(percent, 0.62)` 调整视觉强度
+- hover 时显示 tooltip, 并根据方块位置自动放在左, 右, 上, 下的可用空间内
+
+tooltip 分两种:
+
+| Hook 状态 | tooltip 内容 | 尺寸 |
+| --------- | ---------------------------------------------------------------------------- | ----------- |
+| 关闭 | 日期和 token 数 | `92 x 40` |
+| 开启 | 日期, token 数, 会话总数, 对话轮次, 子智能体, 工具调用, 权限请求, 上下文压缩 | `132 x 116` |
+
+更新时间行:
+
+- 显示倒计时圆环, "数据更新时间"和 `HH:mm:ss`
+- popover 可见时使用 `TimelineView(.periodic(..., by: 1))` 每秒 tick
+- popover 不可见时只渲染一次静态圆环
+- 普通 tick 不做连续动画, 只有刷新起点变化时播放 0.5 秒恢复动画
+- 如果 Sparkle 自动发现新版, 右侧显示 `panelUpdateMessage`, 双击该文本调用 `startUpdate()`
+
+## 10. Codex Hook 开启后完整流程
+
+设置页"启用 Codex Hook"由 `CodexHookSettings` 管理, 配置文件是:
+
+```text
+~/.codex/hooks.json
+```
+
+下面的时序图展示开启 Hook, Codex 触发事件, 本机写入, 后台维护, 以及常见错误后的处理
+
+```mermaid
+sequenceDiagram
+ participant User as 用户
+ participant Settings as 设置界面
+ participant Config as Hook 配置读写
+ participant File as 全局 Hook 配置
+ participant Codex as Codex 运行过程
+ participant HookApp as Hook 记录进程
+ participant Store as 本机事件存储
+ participant Stats as 统计维护
+ participant Tooltip as 热力图提示
+
+ User->>Settings: 打开启用 Hook
+ Settings->>Config: 请求写入 Hook 配置
+ Config->>File: 读取现有配置
+
+ alt 配置结构非法或读取失败
+ Config-->>Settings: 开关恢复实际状态并显示错误
+ else 文件不存在或读取成功
+ Config->>Config: 使用空配置或现有配置
+ Config->>Config: 移除当前 App 路径的旧处理器
+ Config->>Config: 保留用户已有处理器和其他 App 处理器
+ Config->>Config: 为 10 个事件追加命令处理器
+ Config->>File: 原子写回配置
+ alt 写入失败
+ Config-->>Settings: 刷新实际状态并显示设置失败
+ else 写入成功
+ Config-->>Settings: 开关显示已启用
+ end
+ end
+
+ opt Hook 已启用且 Codex 触发事件
+ Codex->>HookApp: 执行 Hook 命令并传入事件内容
+ HookApp->>HookApp: 解析事件名, 时间, 目录, 工具和会话字段
+ alt 标准输入为空或不是 JSON
+ HookApp->>HookApp: 使用当前时间和工作目录兜底
+ else 事件内容可解析
+ HookApp->>HookApp: 转成本机事件记录
+ end
+
+ HookApp->>Store: 获取写入锁
+ alt 获取锁或写入失败
+ HookApp-->>Codex: 吞掉记录错误并正常退出
+ else 写入成功
+ HookApp->>Store: 追加当天原始事件
+ HookApp->>Store: 标记当天等待维护
+ HookApp->>Store: 释放写入锁
+ HookApp-->>Codex: 正常退出
+ end
+ end
+
+ opt App 后台刷新触发维护
+ Stats->>Store: 读取维护状态和每日聚合
+ alt 每日聚合缺失, 坏行或事件文件状态不一致
+ Stats->>Store: 标记当天需要重建
+ else 只有新增事件
+ Stats->>Store: 从上次位置增量读取
+ end
+
+ Stats->>Stats: 合并事件计数, 会话去重和工具统计
+ alt 单日维护失败
+ Stats->>Store: 标记当天下次重建
+ Stats-->>Tooltip: 继续使用已有聚合或空数据
+ else 维护成功
+ Stats->>Store: 原子写回每日聚合
+ Stats->>Store: 更新维护状态并清理过期事件
+ Stats-->>Tooltip: 展示最新统计
+ end
+ end
+```
+
+当前安装事件:
+
+- `SessionStart`
+- `UserPromptSubmit`
+- `PreToolUse`
+- `PostToolUse`
+- `PermissionRequest`
+- `PreCompact`
+- `PostCompact`
+- `Stop`
+- `SubagentStart`
+- `SubagentStop`
+
+每个处理器形如:
+
+```bash
+'<当前 CodexBar 可执行文件路径>' --hook-event SessionStart
+```
+
+识别和移除 CodexBar 自己的 Hook 时必须同时满足:
+
+- handler 是 JSON 对象
+- `type == "command"`
+- `command` 等于当前 App 可执行路径生成的命令
+
+这意味着:
+
+- 用户已有 Hook 会被保留
+- 其他 App Hook 会被保留
+- 其他路径的 CodexBar Hook 不会被当作当前 App Hook 删除
+- 同一事件下其他处理器会被保留
+
+检测是否已开启时, 要求全部 CodexBar 事件都存在当前 App 路径对应的 handler
+
+## 11. Hook 事件写入流程
+
+Hook 子进程写入路径追求轻量, 避免超过 Codex Hook timeout
+
+```mermaid
+sequenceDiagram
+ participant Codex as Codex
+ participant App as Hook 记录进程
+ participant Recorder as 事件记录器
+ participant Lock as 写入锁
+ participant Events as 当天事件日志
+ participant State as 维护状态文件
+
+ Codex->>App: 执行 Hook 命令并传入事件内容
+ App->>Recorder: 进入快速记录分支
+ Recorder->>Recorder: 解析事件名和顶层字段
+ Recorder->>Lock: 获取独占锁
+ Recorder->>Events: 追加一行事件 JSONL
+ Recorder->>State: 标记当天等待维护
+ Recorder->>Lock: 释放独占锁
+ App-->>Codex: 正常退出
+```
+
+读取字段:
+
+| Hook payload 字段 | 写入字段 |
+| ----------------------- | ----------------------------------------------- |
+| `timestamp` | `timestamp`, 本机时间 `yyyy-MM-dd HH:mm:ss.SSS` |
+| `cwd` | `cwd` |
+| `tool_name` | `tool` |
+| `model` | `model` |
+| `permission_mode` | `permission` |
+| `session_id` | `session` |
+| `turn_id` | `turn` |
+| 命令参数 `--hook-event` | `event` |
+
+缺失字段不阻断写入:
+
+- `timestamp` 缺失或无法解析时使用当前时间
+- `cwd` 缺失时使用当前工作目录
+- 其他字段缺失写为 `null`
+
+Hook 数据目录:
+
+```text
+~/Library/Application Support/CodexBar/HookEvents/
+```
+
+文件职责:
+
+| 文件 | 职责 |
+| ------------------------- | ------------------------------------------------ |
+| `events/YYYY-MM-DD.jsonl` | 按本机日期拆分的原始 Hook 事件 |
+| `daily.jsonl` | 每日聚合结果, UI 优先读取 |
+| `stats.lock` | `flock` 锁文件 |
+| `maintenance.json` | pending, dirty, offset, size, corrupt 等维护状态 |
+
+## 12. Workflow Stats 维护与聚合流程
+
+`WorkflowStatsViewModel` 刷新规则:
+
+- `refreshIfNeeded(performMaintenance: false)` 至少间隔 5 秒
+- `performMaintenance: true` 时跳过 5 秒节流, 直接刷新
+- 打开 popover 时如果 Hook 开启, 只读取现有 `daily.jsonl`, 不维护
+- app-server 自动刷新倒计时重置时, 如果 Hook 开启, 触发一次带维护的 workflow stats 刷新
+
+维护流程在 `WorkflowStatsService` 的 `CodexBar.workflow-stats` 串行队列执行
+
+```mermaid
+flowchart TD
+ Start["刷新工作流统计"] --> Maintenance{"是否执行维护"}
+ Maintenance -- "否" --> LoadDaily["读取每日聚合"]
+ Maintenance -- "是" --> Prepare["准备维护任务"]
+ Prepare --> Lock1["短暂持锁读取并修正维护状态"]
+ Lock1 --> Tasks{"有任务?"}
+ Tasks -- "否" --> LoadDaily
+ Tasks -- "是" --> Build["按待重建或待增量日期构建当天聚合"]
+ Build --> ReadEvents["从原始事件增量读取"]
+ ReadEvents --> Aggregate["记录事件计数, 去重 ID, 项目计数"]
+ Aggregate --> WriteDaily["锁外原子写回每日聚合"]
+ WriteDaily --> Lock2["短暂持锁提交维护状态"]
+ Lock2 --> Prune["清理 210 天外原始事件"]
+ Prune --> LoadDaily
+ LoadDaily --> Snapshot["生成工作流统计快照"]
+```
+
+任务类型:
+
+| 类型 | 触发条件 | 读取方式 |
+| ------- | ---------------------------------------------------------- | ------------------------------- |
+| dirty | schema 变化, daily 缺失或坏行, events 状态不一致, 文件缩小 | 从当天 events 文件开头重建 |
+| pending | Hook 新增事件或 events 文件变大 | 从 `days[date].offset` 增量读取 |
+
+聚合规则:
+
+- 事件名先去掉 `_` 和 `-`, 再转小写
+- `sessionStartCount`, `stopCount`, `preToolUseCount` 等按归一化事件名增加
+- 最近 7 天保留 `sessionIds` 和 `turnIds`, 用于继续去重
+- 7 天前把 ID 集合压缩为 `sessionCount` 和 `turnCount`, 随后移除 ID 列表
+- 最多保留最近 210 天数据
+- 210 天外的 `events/YYYY-MM-DD.jsonl` 在主 App 维护流程中删除
+- 坏 JSONL 行跳过并计入 `corrupt`, 不阻断整天聚合
+
+UI 展示指标来自 `WorkflowDailyAggregate.stats`:
+
+| UI 字段 | 生成规则 |
+| ---------- | ------------------------------------------------------- |
+| 会话总数 | `sessionCount ?? sessionIds.count ?? sessionStartCount` |
+| 对话轮次 | `turnCount ?? turnIds.count ?? stopCount` |
+| 子智能体 | `max(subagentStartCount, subagentStopCount)` |
+| 工具调用 | `max(preToolUseCount, postToolUseCount)` |
+| 权限请求 | `permissionRequestCount` |
+| 上下文压缩 | `max(preCompactCount, postCompactCount)` |
+
+## 13. 设置窗口流程
+
+设置窗口由 `SettingsWindowController` 打开, 内容是 `AppSettingsView`
+
+`onAppear` 时刷新:
+
+- `LoginItemSettings.refresh()`
+- `CodexHookSettings.refresh()`
+- `AppUpdater.refreshAutomaticCheckSetting()`
+- `CodexCLIVersionViewModel.refresh()`
+- `CodexStatusViewModel.refreshCodexConnectionInfo()`
+
+App 再次成为 active 时, 也会刷新 Codex 版本区
+
+版本探测内部有 60 秒节流, 避免 `onAppear` 和 `didBecomeActive` 连续触发时重复启动子进程
+
+设置项:
+
+| 设置项 | 状态源 | 写入行为 |
+| --------------- | ---------------------------------------------------- | ------------------------------------ |
+| 开机自动启动 | `SMAppService.mainApp.status` | `register()` / `unregister()` |
+| 自动检查更新 | Sparkle updater | 设置 `automaticallyChecksForUpdates` |
+| 启用 Codex Hook | `~/.codex/hooks.json` | 追加或移除当前 CodexBar command hook |
+| CodexBar 版本 | Bundle + AppUpdater 状态 | 有更新状态时优先显示动态消息 |
+| Codex 版本 | `CodexCLIVersionSnapshot` + 当前 app-server 握手信息 | 路径点击复制到剪贴板 |
+
+错误显示:
+
+- 开机启动失败显示在底部状态区
+- Hook 设置失败显示在底部状态区
+- 更新检查状态显示在 CodexBar 版本行
+- Hook 开关说明只展示辅助说明, 不展示启用或关闭状态文案
+
+## 14. Codex CLI 解析与版本探测
+
+`CodexCLIResolver` 同时服务于 app-server 启动和版本探测
+
+安装源模型:
+
+- `.global`: PATH 中真实全局 `codex`
+- `.bundled`: `/Applications/Codex.app/Contents/Resources/codex` 或等价路径
+
+`CodexCLIInstallations.activeSource` 与启动优先级一致: 全局优先, 内置回退
+
+`CodexCLIVersionService` 的版本探测:
+
+- 在 `CodexBar.codex-version` 串行队列执行
+- 先解析安装源
+- 全局和内置版本探测先并发启动, 再收集结果, 避免两个 5 秒超时串行叠加
+- 每个探测运行 `codex --version`
+- stdout 和 stderr 都收集, 最多各 64 KiB
+- 进程超时时先 terminate, 再 SIGKILL
+- 第一行中第一个以数字开头的 token 作为显示版本
+
+`CodexCLIVersionDisplay` 合并磁盘探测结果和当前 app-server 连接信息:
+
+- 当前运行来源优先显示 app-server `initialize` 握手里的版本
+- 非当前来源显示磁盘探测版本
+- 当前运行版本低于磁盘安装版本时, 显示"已更新至 <version>"
+- 路径点击复制到剪贴板, 1.5 秒后恢复路径显示
+
+## 15. Sparkle 更新流程
+
+`AppUpdater` 是 `@MainActor ObservableObject`
+
+初始化时先检查 Bundle 中的 Sparkle 配置:
+
+- `SUFeedURL` 必须是 http 或 https
+- `SUPublicEDKey` 必须非空
+
+配置不可用时:
+
+- 不创建 `SPUStandardUpdaterController`
+- `canConfigureAutomaticChecks == false`
+- 手动检查或启动更新显示"未配置更新资源"
+
+配置可用时:
+
+- 创建 `SPUStandardUpdaterController(startingUpdater: true, updaterDelegate: self, userDriverDelegate: nil)`
+- 从 updater 读取自动检查设置
+
+手动检查:
+
+- `checkForUpdates()` 设置 `isManualCheckInProgress = true`
+- 设置页显示"正在检查更新"
+- 调用 `checkForUpdateInformation()`
+- delegate 回调发现新版时设置 `availableUpdateMessage`, 手动检查时同时保持设置页消息
+- 没有新版时显示"没有可用更新"1 秒
+- 失败时显示"检查更新失败"
+
+被动发现新版:
+
+- 自动检查发现新版时设置 `panelUpdateMessage`
+- popover 底部更新时间行显示该消息
+- 双击消息调用 `startUpdate()`, 激活 App 并打开 Sparkle 更新流程
+
+## 16. 日志窗口流程
+
+日志窗口由右键菜单"日志"打开, 内容是 `LogView(store: RequestLogStore.shared)`
+
+展示规则:
+
+- 顶部显示标题和当前日志条数
+- "清空"按钮调用 `RequestLogStore.clear()`
+- 空状态显示"暂无日志"
+- 有日志时使用 `ScrollView + LazyVStack`, 最新日志在前
+- 每行默认显示时间, 状态标签, method 或无 method 记录的详情预览
+- 点击行展开请求和响应或错误详情
+- 详情文本开启 `.textSelection(.enabled)`
+
+日志只记录经过 `RequestLogStore` 的请求和错误
+
+为了保护隐私, 不直接展示 app-server stderr, Codex auth 文件内容或未截断的长响应
+
+## 17. 发布脚本流程
+
+发布脚本位于 `Scripts/`, 修改后至少运行 shell 语法检查
+
+`Scripts/dmg.sh [App.app] [Output.dmg]`:
+
+- 解析 App 路径, 未指定时从项目根查找唯一 `.app`
+- 读取 `MARKETING_VERSION`, 优先从 Xcode build settings 读取, 失败后回退 `project.pbxproj` 和 App `Info.plist`
+- 准备临时 staging 目录, 复制 `.app` 并创建 `/Applications` 符号链接
+- 创建可写 DMG
+- 挂载 DMG 并用 AppleScript 写 Finder icon view 布局
+- 压缩为最终 UDZO DMG
+
+`Scripts/appcast.sh [CodexBar-vX.Y.Z.dmg]`:
+
+- 解析 DMG, appcast, 下载地址, release notes 地址和 Xcode 工程
+- 读取 Release 配置中的 `MARKETING_VERSION`, `CURRENT_PROJECT_VERSION` 和 `PRODUCT_NAME`
+- 查找 Sparkle `sign_update`
+- 对 DMG 签名并解析 `sparkle:edSignature` 和长度
+- 生成新的 appcast `<item>`
+- 移除同 build version 旧 item, 再插入新 item
+- 如果存在 `xmllint`, 校验 appcast XML
+
+## 18. 并发, 隔离与文件安全
+
+主要并发边界:
+
+| 模块 | 并发策略 |
+| --------------------------------- | ------------------------------------------------- |
+| UI, 控制器, ViewModel, 设置, 更新 | `@MainActor` |
+| `CodexStatusService` | `DispatchQueue(label: "CodexBar.app-server")` |
+| `CodexCLIVersionService` | `DispatchQueue(label: "CodexBar.codex-version")` |
+| `WorkflowStatsService` | `DispatchQueue(label: "CodexBar.workflow-stats")` |
+| `RequestLogStore` | `NSLock` 保护 storage, 主线程发送 SwiftUI 通知 |
+| Hook 写入 | `stats.lock` + `flock(LOCK_EX)` |
+| app-server stdout | `JSONLineReader` 使用锁和 semaphore |
+| 版本探测输出 | `PipeCollector` 使用锁和 semaphore |
+
+文件写入安全:
+
+- Hook 子进程只在锁内追加当天 `events/YYYY-MM-DD.jsonl` 并更新 `maintenance.json`
+- 主 App 维护 `daily.jsonl` 时, 先锁外原子写 daily, 再短暂持锁提交维护状态, 减少阻塞 Hook 写入
+- `maintenance.json` 和 `daily.jsonl` 使用 atomic write
+- 设置 Hook 时 pretty printed 写回 `~/.codex/hooks.json`, 但只移除当前 App 可执行路径对应的 handler
+
+隐私和敏感信息边界:
+
+- 不展示 app-server stderr
+- 不读取或展示 Codex auth 文件内容
+- 不把原始敏感 RPC 响应写入文档或测试夹具
+- 日志详情截断到 4000 字符
+- Hook 统计只保存在用户 Application Support 的 CodexBar 目录
diff --git a/README.md b/README.md
index d03da18..bb64c47 100644
--- a/README.md
+++ b/README.md
@@ -82,6 +82,8 @@ Swift 源码按职责放在 `CodexBar/` 下的子目录中:
- `Services/`: app-server 会话、Codex CLI 解析、版本探测、Hook 设置、工作流统计、开机自启和 Sparkle 更新
- `Views/`: 菜单栏弹窗、设置窗口、日志窗口和共享 Liquid Glass 样式
+更详细的启动、刷新、Hook 统计、设置、日志、更新和发布流程见 [开发文档](Docs/DevelopmentGuide.md)。
+
## 隐私
CodexBar 只与本机 Codex app-server 进程通信。账号信息、额度数据、token 用量和 Hook 工作流数据不会被收集或发送给任何个人或服务。