CodexBar 是一个 macOS 菜单栏应用,用于查看本机 Codex 账号状态、额度、Token 用量、详细统计信息
Swift appkitcodexcodex-clideveloper-toolsmacosmacos-appmenu-bar-appopenai-codexproductivityswiftswiftuiusage-tracker
docs: 更新 README - 更新预览 gif - 更新数据链路图 - 精简特性 安装 隐私与实现各节的表述
Bob2668f108a4ec
diff --git a/Images/preview.gif b/Images/preview.gifindex f9bdbe0..458e04a 100644Binary files a/Images/preview.gif and b/Images/preview.gif differdiff --git a/README.md b/README.mdindex d3b5b8a..8ade6d4 100644--- a/README.md+++ b/README.md@@ -20,62 +20,66 @@----CodexBar 把 Codex 的运行状态收进菜单栏: 剩余额度, 下次重置时间, 当日 Token 用量, 以及当前任务是在运行还是在等待批准--应用以 `LSUIElement` 方式运行, 没有 Dock 图标; 数据全部在本机采集与聚合, 对外通信仅有四项, 详见[隐私](#隐私)+CodexBar 把 Codex 的运行状态收进菜单栏: 账户信息, 剩余额度, 任务状态, 重置时间, Token 用量, 使用详细信息等## 特性-其中实时任务, 工作流统计与防休眠依赖 CodexBar Hook, 开启方式见[关于 Hook](#关于-hook)+其中实时任务, 热力图面板中的详细统计数据与阻止系统休眠功能依赖 CodexBar Hook, 开启方式见[关于 Hook](#关于-hook)++### 账户信息++- 展示当前登录的账号+- 右侧套餐徽章区分 Enterprise, Team, Pro, Plus, Edu, Free+- 双击邮箱可模糊遮挡+- 双击头像立即刷新### 额度与用量- 分时间窗口展示剩余额度, 重置时间与可用的手动重置次数- 菜单栏可常驻显示主要或次要窗口的额度百分比, 无需展开面板- 30 周日历热力图呈现每日 Token 用量, 点击任意一格展开当天明细-- 账号有效时额度与用量允许单独失败, 失败项沿用同账号缓存并标记为陈旧### 实时任务- 开启 CodexBar Hook 后, 菜单栏图标随任务状态实时变化- 任务中心区分运行中, 等待批准, 最近完成, 已终止四种状态-- 状态同时取自 Hook 事件流与 `~/.codex/sessions` 下的 rollout 记录, 前者覆盖工具调用与批准请求, 后者补齐对话轮次的起止-### 工作流统计+### 热力图统计-- 按天聚合会话, 对话轮次, 工具调用, 权限请求, 上下文压缩, 子 Agent 等指标-- 原始事件与每日聚合保留 210 天, 可按日期区间从原始事件重新统计-- 可选开启 iCloud 同步, 汇总多台 Mac 的数据+- GitHub 贡献墙样式展示每日 Token 用量+- 开启 CodexBar Hook 后的会话还可统计对话轮次, 工具调用, 权限请求, 上下文压缩, 子 Agent 等指标+- 可选开启 iCloud 同步, 在多台 Mac 之间同步数据-### 防休眠+### 阻止系统休眠-- 仅在任务运行期间阻止空闲休眠与合盖休眠, 任务结束即恢复-- 最长时长可选 1, 2, 4, 8, 12, 24 小时或无限制, 默认 12 小时-- 等待批准, 任务结束与时长到期都会还原系统原有设置, 交由 macOS 重新判断-- 生效期间主面板的任务卡片右侧显示一个咖啡杯标记+需要长时间运行 Codex 任务但是怕系统自动休眠?++- 仅在任务运行期间阻止系统休眠, 任务结束恢复系统休眠设置+- 可设置最长阻止休眠时间 1, 2, 4, 8, 12, 24 小时或无限制+- 阻止休眠状态可在主面板的任务卡片右侧显示一个咖啡杯标记### 通知与提醒-- 五类本地通知: 额度告急, 额度重置, 任务等待批准, 长任务完成, 重置机会即将过期-- 告急百分比与长任务时长阈值可调, 每类通知的音效独立可选-- 阈值穿越带去重判定, 同一事件不会重复提醒; 任务状态变化另有触觉反馈-- 可直接读写 Codex CLI 自身的通知配置, 无需手动编辑 `config.toml`+- 本地通知: 额度预警, 额度重置, 任务等待批准, 任务完成, 手动重置即将过期+- 通知音效独立设置+- 任务状态变化可设置触摸板震动反馈通知### 系统集成-- 全局快捷键唤起 (默认 `⌘⇧W`, 可自定义), 开机自启, Sparkle 自动更新-- 内置日志窗口保留最近 500 条请求记录, 连接失败与解析异常均可追溯-- 界面风格贴近系统菜单栏工具, 不作额外装饰+- 全局快捷键唤起+- 内置日志窗口保留最近 500 条 app-server 请求记录## 安装-推荐通过 Homebrew 安装+### 通过 Homebrew```bashbrew install --cask bob-zebedy/tap/codexbar```-也可以从 [Releases](https://github.com/bob-zebedy/CodexBar/releases) 下载 DMG, 将 `CodexBar.app` 拖入 `/Applications`+### 通过 DMG++[Releases](https://github.com/bob-zebedy/CodexBar/releases)运行要求@@ -83,7 +87,7 @@ brew install --cask bob-zebedy/tap/codexbar- 已安装并登录 [Codex CLI](https://github.com/openai/codex), 或安装了内置 Codex 的 ChatGPT App> [!TIP]-> CodexBar 优先使用 PATH 中的 `codex`, 找不到时回退到 `ChatGPT.app` 或 `Codex.app` 的内置版本+> CodexBar 会自动寻找可用的 codex 实例## 使用@@ -97,81 +101,72 @@ brew install --cask bob-zebedy/tap/codexbar### 关于 Hook-实时任务, 工作流统计与防休眠都依赖 CodexBar Hook, 在设置中开启即可写入 `~/.codex/hooks.json`+实时任务展示, 热力图统计数据与防休眠都依赖 CodexBar Hook> [!NOTE]-> 写入只追加 CodexBar 自身的 handler, 关闭时也只移除这一条; 已有的 Hook 与其他工具注册的 Hook 原样保留+> 不会影响任何原本的 Codex Hook-### 关于防休眠+### 关于阻止系统休眠-覆盖合盖休眠需要一个 root LaunchDaemon 执行 `pmset`, 因此首次开启时 macOS 会要求授权后台项目; 该功能同样依赖 Hook, 关闭 Hook 会将其一并关闭并置灰+开启后需要一个 Helper 进行守护, 因此首次开启时 macOS 会要求授权后台项目; 该功能同样依赖 CodexBar Hook> [!WARNING]-> 合盖状态下持续运行任务会明显增加耗电与发热, 请保证 Mac 通风良好, 不要在密闭背包内使用+> 为了避免异常任务导致系统长时间处于阻止休眠的状态, 建议设置最长阻止休眠时间## 隐私CodexBar 的对外通信只有以下四项, 其中真正经过网络的是后三项-| 行为 | 说明 |-| ------------------------------ | ------------------------------------------ |-| 与本机 `codex app-server` 通信 | 经由管道, 不经过网络 |-| 查询额度重置机会的过期时间 | 只读请求, 全仓库唯一的 `URLSession` 调用点 |-| Sparkle 更新检查 | 拉取 appcast |-| CloudKit 同步 | 仅在显式开启后进行 |--账号, 额度, Token 用量与原始 Hook 事件都不会离开本机; 跨设备同步只上传去掉会话与轮次标识的每日聚合; Codex 的 OAuth token 与 `auth.json` 内容既不展示也不记录+| 行为 | 说明 |+| ------------------------------ | ----------------------------------------------- |+| 与本机 `codex app-server` 通信 | 获取账户, 额度信息, 获取&修改本机 codex 配置等 |+| 查询额度重置机会的过期时间 | 请求 OpenAI 接口获取数据 |+| CloudKit 同步 | 私有数据: 同步用量数据 |## 实现-Swift 6 + SwiftUI + AppKit, MVVM, 唯一的外部依赖是 Sparkle+Swift 6 + SwiftUI + AppKit, MVVM, 外部依赖 Sparkle-工程开启了 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`, 所有类型默认 MainActor 隔离; 共享状态收敛进 actor, 跨进程写统计文件由 `flock` 保护+工程开启了 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor` 所有类型默认 MainActor 隔离; 共享状态收敛进 actor, 跨进程写统计文件由 `flock` 保护三条数据链路各自独立```mermaidflowchart LR- subgraph L1["额度与用量"]- AS["codex app-server"] -->|"stdio JSON-RPC"| SS["CodexStatusService"]- SS --> VM["CodexStatusViewModel"]+ subgraph L1["额度与用量 (每分钟刷新)"]+ A1["本机 codex 进程"] -->|"通过 app-server"| A2["获取剩余额度<br/>和 Token 用量"]endsubgraph L2["历史统计"]- HK["Hook 子进程"] -->|"JSONL"| WS["WorkflowService"]- WS -->|"增量聚合"| DA["daily.jsonl"]+ B1["Codex 触发 Hook"] -->|"新增记录"| B2["按天汇总数据"]endsubgraph L3["实时任务"]- EV["Hook 事件流"] --> AM["CodexActivityMonitor"]- RO["sessions rollout"] --> AM+ C1["Hook 事件"] --> C3["判断任务状态"]+ C2["Codex Rollout 数据"] --> C3end- VM --> UI["菜单面板"]- DA --> UI- AM --> UI- AM --> NT["通知与触觉反馈"]- AM --> KA["防休眠"]+ A2 --> UI["菜单栏和主面板"]+ B2 --> UI+ C3 --> UI+ C3 --> N["通知事件"]+ C3 --> K["阻止休眠"]```<details>-<summary><b>两处关键设计</b></summary>+<summary><b>关键设计</b></summary><br>**Hook 子进程模式**-App 二进制带 `--hook-event` 启动时不初始化任何 UI, 只从 stdin 读一行 JSON, 在文件锁内追加到当日 JSONL 后立即退出--写入失败一律静默返回, 任何情况下都不阻断也不拖慢 Codex+App 使用 `--hook-event` 参数启动时不初始化任何 UI, 只从 stdin 读一行 JSON, 在文件锁内追加到当日 JSONL 后立即退出-**root helper 的最小权限**+**root helper 权限**-`CodexBarHelper` 是随 App 嵌入的 LaunchDaemon, 只暴露一个 XPC 方法, 只执行 `pmset -a disablesleep`; 没有网络访问, 没有命令执行, 也没有其他文件读写能力+`CodexBarHelper` 是随 App 嵌入的 LaunchDaemon, 只暴露一个 XPC 方法, 只执行 `pmset -a disablesleep`-调用方由代码签名强制校验: helper 启动时读取自身签名拼出 requirement 交给 XPC listener, 修改签名或 bundle ID 都会导致连接被拒--此外还有磁盘哨兵与 watchdog 兜底, 确保 App 异常退出后休眠设置仍能还原+签名强制校验: helper 启动时读取自身签名拼出 requirement 交给 XPC listener, 修改签名或 bundle ID 都会导致连接被拒</details>@@ -183,15 +178,13 @@ cd CodexBarxcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/platform=macOS' build```-也可以直接 `open CodexBar.xcodeproj` 在 Xcode 中运行 Debug scheme; Debug 产物的 bundle ID 为 `app.zabrian.codexbar.debug`, 与 Release 安装版可以共存--格式化与静态检查使用 `swiftformat` 和 `swiftlint`, 配置位于仓库根目录+区分 Debug 和 Release 构建产物-`Scripts/` 下是归档, 公证, DMG 打包与 appcast 签名等发布脚本, 它们需要 Developer ID 凭据, 不适合用于日常验证+格式化与静态检查使用 `swiftformat` 和 `swiftlint`## 反馈-Bug, 功能建议与使用问题都欢迎通过 [Issues](https://github.com/bob-zebedy/CodexBar/issues) 反馈, 仓库已备好对应模板+Bug, 功能建议或使用问题都欢迎通过 [Issues](https://github.com/bob-zebedy/CodexBar/issues) 反馈## 许可证