Skip to content

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

docs: 整理 README 产品介绍文档

Bobefdffbdc7e71
diff --git a/README.md b/README.md
index 9af63d2..80273ad 100644
--- a/README.md
+++ b/README.md
@@ -1,73 +1,108 @@
# CodexBar
-> 在 macOS 菜单栏实时查看 Codex 账号额度、token 用量和工作流数据统计。
+> 常驻 macOS 菜单栏的 Codex 状态看板
-CodexBar 是一个轻量级 macOS 菜单栏应用。它直接连接本机 Codex 的 app-server,定期读取额度信息;也可以通过 Codex Hook 记录本机工作流数据,让你不用打开终端就能随时知道: 还剩多少额度、什么时候重置、最近用了多少 token,以及今天的会话、对话轮次、工具调用等情况。
+CodexBar 在不打开 Codex CLI 或 Codex App 的情况下快速查看 Codex 账号状态、额度重置时间、Token 用量和本机使用情况统计。它连接本机 Codex app-server 获取账号与用量信息,也可以通过 Codex Hook 记录本机 Codex 事件,让菜单栏成为一个轻量、实时、的 Codex 仪表盘。
<p align="center">
<img src="Images/record.gif" width="532">
</p>
-## 特性
+## 为什么需要 CodexBar
-- **额度一目了然**: 分段电量条展示各时间窗口 (如 5 小时、7 天) 的剩余额度,附剩余百分比和重置时间
-- **用量热力图**: 展示近 30 周的每日 token 用量,鼠标悬停可查看单日明细
-- **详细统计**: 开启 Codex Hook 后,热力图会展示会话总数、对话轮次、子智能体调用次数、工具调用次数、权限请求次数和上下文压缩次数
-- **跨设备同步**: 开启 Codex Hook 后可选择把脱敏后的每日工作流聚合同步到当前 iCloud 账号
-- **自动刷新**: 每分钟后台刷新一次,弹窗未打开也保持最新;双击账号图标可手动刷新
-- **自动更新**: 内置 Sparkle 更新检查,新版本自动更新
-- **本地优先**: 账号、额度和 token 用量只与本机 Codex app-server 通信;Hook 工作流统计默认只保存在本机,只有用户开启「跨设备同步」后才通过 CloudKit private database 同步脱敏每日聚合
+Codex 的额度、Token 用量和使用情况通常分散在终端、App 或 Session 中。CodexBar 把这些信息放到一个可随时呼出的菜单栏面板中,适合需要频繁使用 Codex、关注剩余额度和使用情况的 macOS 用户。
+
+- 查看当前账号是否已登录,以及 Codex CLI / Codex.app 的运行版本
+- 跟踪不同时间窗口的额度剩余比例和下一次重置时间
+- 用 30 周热力图回顾每日 Token 用量
+- 在开启 Codex Hook 后在 30 周热力图中可查看会话、对话轮次、工具调用、权限请求、上下文压缩和子智能体统计 (仅在开启后可记录查看,无法查看到历史数据)
+- 通过可选 iCloud 私有数据库同步实现跨平台数据合并
+
+## 有什么功能
+
+### 菜单栏即状态中心
+
+CodexBar 是一个无 Dock 图标的 macOS 菜单栏应用。
+
+左键点击菜单栏图标即可打开状态面板。
+
+右键 (或者 `⌃ + 鼠标左键点击`) 可进入设置、日志或退出应用。
+
+使用默认全局快捷键 `⌘ ⇧ W` 适合在任何工作区快速查看当前 Codex 状态。
+
+### 额度与重置时间一眼可见
+
+额度区用分段电量条展示不同时间窗口的剩余额度,并显示剩余百分比和重置时间
+
+### 近 30 周 Token 热力图
+
+热力图以周为列、日为行展示近 30 周的每日 Token 用量。
+
+鼠标悬停到任意日期时,会打开侧边详情面板展示当天 Token 数和用量强度。
+
+开启 Codex Hook 后,同一面板还会展示当天的使用详情统计。
+
+### Codex Hook 使用详情
+
+在设置中开启「启用 Codex Hook」后,CodexBar 会把自身注册为本机 Codex Hook 用于记录会话开始、回复结束、工具调用、权限请求、上下文压缩和子智能体事件。
+
+统计结果会汇总到热力图详情面板中,不打断正常的 Codex 使用流程。
+
+CodexBar 只会追加或移除属于当前 CodexBar 可执行文件的 Hook 处理器,不会删除用户已有的其他 Codex Hook。
+
+更详细的配置、存储和统计口径见 [Codex Hook 文档](Docs/CodexHook.md)
+
+### 可选跨设备同步
+
+如果已经开启 Codex Hook,且当前 iCloud 账号可用,可以在设置里开启「跨设备同步」
+
+CodexBar 会把该设备的使用详情数据同步到当前 iCloud 账号的 CloudKit private database,用于在多台 Mac 上合并查看工作流统计。
+
+同步不会上传 Codex 账号、额度、Token 用量、原始 Hook events、会话 ID、轮次 ID、请求日志或 Codex 认证文件。
+
+完整同步范围见 [跨设备同步文档](Docs/CrossDeviceSync.md)
+
+### 日志与版本信息
+
+CodexBar 内置请求日志窗口,用于查看 app-server 请求状态和排查刷新问题。设置页会展示 CodexBar 版本、当前 Codex CLI / Codex.app 版本、运行来源和本地安装路径,路径点击即可复制。
+
+### 自动更新
+
+CodexBar 使用 Sparkle 检查更新。安装后,新版本会通过内置更新流程推送;也可以从设置窗口手动检查更新。
## 安装
-### 下载 DMG
+### 下载
-从 [Releases](https://github.com/bob-zebedy/CodexBar/releases) 下载。
+从 [Releases](https://github.com/bob-zebedy/CodexBar/releases) 下载最新 DMG,打开后把 `CodexBar.app` 拖入 `/Applications`。
-之后的新版本会通过内置的 Sparkle 自动更新推送。
+后续版本会通过内置 Sparkle 自动更新推送。
### 运行要求
- macOS 15.0 或更高版本
-- 已安装 [Codex CLI](https://github.com/openai/codex) (全局 `codex` 命令或 `Codex.app`)
+- 已安装 [Codex CLI](https://github.com/openai/codex),或已安装 `Codex.app`
- 已在 Codex 中完成登录
-> 提示: 如果把应用移动到 `/Applications` 后才开启开机自启,建议重新开关一次「开机启动」让 macOS 记录最终路径。
-
-## 启用 Codex Hook
-
-CodexBar 可以在设置中开启「启用 Codex Hook」
-
-开启后会在全局 `~/.codex/hooks.json` 中增加以下 Hook,用于接收 Codex 的会话、工具调用、权限请求、上下文压缩和子智能体事件。
+> 如果移动应用位置后才开启开机自启,建议重新开关一次「开机启动」,让 macOS 记录最终应用路径。
-开启前会通过本机 Codex app-server 检查全局 `config.toml` 是否禁用了 Hook;如果已禁用,CodexBar 不会写入配置,并会在 Hook 选项下方提示。写入后还会用 `hooks/list` 确认 CodexBar 自己的 Hook 命令、事件、来源、启用状态、信任状态以及 Codex 返回的警告或错误;未信任或已修改时只会把当前 CodexBar Hook 的 key/hash 写入 `hooks.state` 后再次验证。
+## 隐私
-- `SessionStart`: 记录一次 Codex 会话开始,用于统计会话总数
-- `UserPromptSubmit`: 记录用户提交提示词事件,保留为原始活动事件
-- `PreToolUse`: 记录工具调用开始
-- `PostToolUse`: 记录工具调用结束,和 `PreToolUse` 一起用于统计工具调用次数
-- `PermissionRequest`: 记录 Codex 发起权限请求的次数
-- `PreCompact`: 记录上下文压缩开始
-- `PostCompact`: 记录上下文压缩结束,和 `PreCompact` 一起用于统计上下文压缩次数
-- `Stop`: 记录一次回复/任务结束,用于统计对话轮次
-- `SubagentStart`: 记录子智能体开始
-- `SubagentStop`: 记录子智能体结束,和 `SubagentStart` 一起用于统计子智能体次数
+CodexBar 默认只和本机 Codex app-server 通信,用于读取账号、额度和 Token 用量。这些数据不会发送到任何人或第三方服务。
-每个事件都会追加一个 `command` 类型的 Hook,命令形如:
+Codex Hook 工作流数据默认只保存在本机:
-```bash
-'/Applications/CodexBar.app/Contents/MacOS/CodexBar' --hook-event
+```text
+~/Library/Application Support/CodexBar/HookEvents/
```
-开启后,用量热力图会包含今天;鼠标悬停到任意一天时,弹窗会在 token 数之外展示当天的会话总数、对话轮次、子智能体、工具调用、权限请求和上下文压缩次数。关闭 Hook 时,弹窗只展示日期和 token 数;如果 app-server 尚未返回当天 token 数据,热力图不会额外占位展示今天。
-
-CodexBar 只会追加或移除 command 中包含当前 CodexBar 可执行路径的 Hook,不会删除其他 Codex Hook。
+只有在用户开启「跨设备同步」后,CodexBar 才会通过 `CloudKit private database` 同步每日使用详情数据; 同步的数据副本只包含各个事件数量,不包含事件具体的数据。
-统计数据默认只保存在本机 `~/Library/Application Support/CodexBar/HookEvents/`。开启「跨设备同步」后,CodexBar 会通过 CloudKit private database 把去掉 `sessionIds` / `turnIds` 的每日聚合副本同步到当前 iCloud 账号;iCloud 不可用时该开关不可操作,并在设置页显示「iCloud 不可用」。
+除 Sparkle appcast / DMG 下载,以及用户开启跨设备同步后的 CloudKit 请求外,CodexBar 自身不发起其他网络请求。
## 从源码构建
-项目使用 Swift 6、SwiftUI + AppKit + MVVM,依赖 Sparkle (SwiftPM)。
+项目使用 Swift 6、SwiftUI + AppKit + MVVM,依赖 Sparkle (SwiftPM)
```bash
git clone [email protected]:bob-zebedy/CodexBar.git
@@ -77,24 +112,21 @@ xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/pl
也可以直接用 Xcode 打开 `CodexBar.xcodeproj` 运行。
-## 源码结构
+## 项目文档
-Swift 源码按职责放在 `CodexBar/` 下的子目录中:
+- [app-server 通信合约](Docs/AppServer.md)
+- [Codex Hook 工作流统计](Docs/CodexHook.md)
+- [跨设备同步](Docs/CrossDeviceSync.md)
+- [开发文档](Docs/DevelopmentGuide.md)
+
+Swift 源码按职责放在 `CodexBar/` 下:
- `App/`: 应用入口
- `Controllers/`: 菜单栏、菜单面板和独立窗口控制器
-- `Models/`: account、quota、usage、工作流统计、共享日期网格和错误分类模型
-- `Services/`: actor 隔离的 app-server 会话、Codex CLI 解析、版本探测、Hook 设置、工作流统计、日志存储、开机自启和 Sparkle 更新
+- `Models/`: 账号、额度、用量、工作流统计和错误模型
+- `Services/`: app-server、Codex CLI、设置、Hook、统计、日志、开机自启和更新服务
- `Views/`: 菜单面板、设置窗口、日志窗口和共享 Liquid Glass 样式
-更详细的启动、刷新、Hook 统计、跨设备同步、设置、日志、更新和发布流程见 [开发文档](Docs/DevelopmentGuide.md) 与 [跨设备同步文档](Docs/CrossDeviceSync.md)。
-
-## 隐私
-
-CodexBar 只通过本机 Codex app-server 读取账号信息、额度数据和 token 用量,这些数据不会发送给第三方服务。Hook 工作流数据默认只保存在本机;用户显式开启「跨设备同步」后,CloudKit 仅保存脱敏后的每日聚合副本,不保存原始 Hook events、`sessionIds` 或 `turnIds`。
-
-除用户开启「跨设备同步」后的 CloudKit 请求外,只有检查和下载 App 更新时会产生额外网络请求,请求范围仅包含 [appcast](https://codexbar.zabrian.app/appcast.xml) 和 appcast 中对应的 DMG 下载地址。
-
## 许可证
-本项目采用 [GNU General Public License v3.0](LICENSE)
+本项目采用 [GNU General Public License v3.0](LICENSE)。