Skip to content

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

docs: 修改文档

Bobba33cbdd3d36
diff --git a/AGENTS.md b/AGENTS.md
index 3257af8..81bc24a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,44 +1,38 @@
-# CodexBar 项目记忆
+# AGENTS.md
+
+此文件为 Codex 等代码代理在本仓库工作时提供上下文和约定。请优先遵循这里的项目事实、构建命令和实现边界。
## 项目概览
-CodexBar 是一个 macOS 菜单栏应用,用来展示当前本机 Codex 账号的额度信息。应用使用 SwiftUI + MVVM,主入口是 `MenuBarExtra`,弹窗使用 `.menuBarExtraStyle(.window)`。
+CodexBar 是一个 macOS 菜单栏应用(SwiftUI + MVVM,最低 macOS 15.0),通过本机 Codex app-server 展示当前 Codex 账号的额度和 token 用量。主入口是 `MenuBarExtra`,弹窗使用 `.menuBarExtraStyle(.window)`。唯一外部依赖是 Sparkle(SwiftPM)。
+
+## 构建验证
-当前最低系统版本是 macOS 15.0。
+修改后运行以下命令,确保无 error 和 warning:
-## 核心功能
+```bash
+xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/platform=macOS' build
+```
-- 菜单栏图标:正常时显示 `person.fill.checkmark`,任何错误(包括未登录)时显示 `person.fill.xmark`,切换使用 `.contentTransition(.symbolEffect(.replace))` 动画。App 图标使用白底黑色 `timelapse`。
-- 弹窗第一行展示账号信息和套餐。
-- 弹窗展示两行分段电量条,额度行标签根据 `windowDurationMins` 动态生成。
-- 每行额度在进度条右侧展示剩余百分比和重置时间。
-- 弹窗展示 30 周宽度的完整自然日 token 蓝色贡献墙、累计 token 和单日峰值 token。
-- 鼠标划过 token 贡献墙中的单日方块时,在鼠标旁展示对应日期和用量。
-- 应用运行时每分钟自动刷新,即使弹窗未打开也会刷新。
-- 双击账号图标可手动刷新。
-- 按住 Option/Alt 点击菜单栏图标时,才展示设置区。设置区为单行布局:左侧「开机自动启动」开关,右侧「退出」按钮,不展示刷新按钮。
-- 更新时间行右侧展示当前 App 版本(`App 版本: v{version} ({build})`),双击该文案触发 Sparkle 检查更新;检查期间该位置改为状态文案,3 秒后自动复位。
-- 集成 Sparkle 自动更新:启动时按 `SUScheduledCheckInterval`(Info.plist 配置,当前 3600 秒)后台静默检查,用户也可手动触发。
-- 没有通知功能:不监听 `account/rateLimits/updated`,不发送 macOS 本地通知(该功能已整体移除,不要恢复)。
-- 弹窗错误只展示普通错误文案,不包含 Debug 明细或环境变量模拟入口。
+SourceKit 经常对跨文件类型误报「Cannot find type ... in scope」(索引滞后),以 `xcodebuild` 实际编译结果为准。
-## Codex 数据来源与常驻连接
+工程使用文件系统同步组(`PBXFileSystemSynchronizedRootGroup`):新增/删除源文件无需修改 `project.pbxproj`,只有依赖变更才需要改它。
-应用通过本机 Codex app-server 读取数据。启动优先级:
+## 架构
-1. 如果全局 Codex CLI 可用,优先使用:
+数据流:`CodexRateLimitService`(JSON-RPC 常驻连接)→ `RateLimitsViewModel`(状态发布)→ `MenuBarStatusView`(菜单栏图标 + 在 `.task` 中驱动每分钟自动刷新)/ `RateLimitsMenuView`(弹窗)。
-```bash
-codex app-server --listen stdio://
-```
+- `CodexBarApp.swift`:入口,创建 `RateLimitsViewModel` 和 `@StateObject AppUpdater`,后者以 `environmentObject` 注入弹窗。
+- `CodexRateLimitService.swift`:app-server 常驻连接管理 + JSON-RPC 请求/响应。
+- `RateLimitModels.swift`:响应模型、业务快照模型、`CodexRateLimitError`(含 `requiresLogin`、`isAuthenticationRequired` 分类属性)。
+- `RateLimitsViewModel.swift`:错误状态单一来源——只发布 `lastError: CodexRateLimitError?`,`errorMessage`、`requiresLogin`、`hasError` 都是派生计算属性,**不要再加并列的错误布尔**。
+- `QuotaRow.swift`:额度行和分段进度条;`LoginItemSettings.swift`:`SMAppService.mainApp` 开机自启;`AppUpdater.swift`:Sparkle 封装。
-2. 如果找不到全局 CLI,则回退到 Codex.app 内置二进制:
+## Codex app-server 连接(核心逻辑)
-```bash
-/Applications/Codex.app/Contents/Resources/codex app-server --listen stdio://
-```
+启动优先级:全局 `codex` CLI 优先,找不到则回退 `/Applications/Codex.app/Contents/Resources/codex`;两者都没有时弹窗展示「找不到 Codex CLI 或 Codex App」。启动命令:`codex app-server --listen stdio://`。
-应用与 app-server 维持**一条常驻连接**:首次拉取时启动进程,按顺序完成握手:
+应用维持**一条常驻连接**,首次握手顺序(必须在请求额度前完成,否则 app-server 拒绝请求):
```json
{"method":"initialize","id":1,"params":{"clientInfo":{"name":"codex_bar","title":"Codex Bar","version":"1.0.0"}}}
@@ -46,124 +40,60 @@ codex app-server --listen stdio://
{"method":"account/read","id":2,"params":{"refreshToken":false}}
```
-之后每分钟在同一会话上请求 `account/rateLimits/read` 和 `account/usage/read`。注意:不能在 `initialize` 和 `initialized` 完成前请求额度,否则 app-server 会拒绝请求。
+之后每分钟在同一会话上请求 `account/rateLimits/read` 和 `account/usage/read`。
-连接重建规则(`CodexRateLimitService.ensureConnection`):
+连接重建规则(`CodexRateLimitService.ensureConnection`):
- 进程已退出 → 重建。
-- 连接存活超过 `connectionMaxAge`(1 小时)→ 定期回收重建,覆盖 codex 全局升级后切换新二进制、服务端状态漂移等陈旧问题。
-- **复用的**连接上请求失败 → 丢弃重建一次再试;**全新**连接上的失败直接抛出,不做二次重试(避免故障时整套握手做两遍)。
-- 登录类错误(`requiresLogin`)→ 丢弃连接但不重试;下一次轮询起新进程读取最新 `~/.codex/auth.json`,用户重新登录后最多一分钟自动恢复。
+- 连接存活超过 `connectionMaxAge`(1 小时)→ 定期回收重建(覆盖 codex 全局升级、服务端状态漂移)。
+- **复用的**连接上请求失败 → 丢弃重建一次再试;**全新**连接上的失败直接抛出,不做二次重试。
+- 登录类错误(`requiresLogin`)→ 丢弃连接但不重试;下次轮询起新进程读取最新 `~/.codex/auth.json`,用户重新登录后最多一分钟自动恢复。
-认证重试:`account/rateLimits/read` 返回认证错误时,先在同一会话上调 `account/read`(`refreshToken: true`)刷新 token 再重试一次;仍失败抛 `authenticationRequired`。
+认证重试:`account/rateLimits/read` 返回认证错误时,先在同一会话上调 `account/read`(`refreshToken: true`)再重试一次;仍失败抛 `authenticationRequired`。
-每日 token 统计使用 `account/usage/read`,读取 `summary.lifetimeTokens`、`summary.peakDailyTokens` 和 `dailyUsageBuckets`。如果本机 app-server 不支持该方法,token 统计区域不展示,额度信息仍正常显示。
+token 统计来自 `account/usage/read`(`summary.lifetimeTokens`、`summary.peakDailyTokens`、`dailyUsageBuckets`);本机 app-server 不支持该方法时,token 区域不展示,额度信息仍正常显示。
## 并发约定
-工程开启了 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`:没有显式标注的类型一律推断为 MainActor 隔离。因此**所有非 UI 类型必须显式标 `nonisolated`**(`CodexRateLimitService`、`AppServerSession`、模型类型等都已标注),否则会出现「Call to main actor-isolated initializer in a synchronous nonisolated context」一类的错误。
+工程开启了 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`:未显式标注的类型一律推断为 MainActor 隔离。因此**所有非 UI 类型必须显式标 `nonisolated`**,否则会报「Call to main actor-isolated initializer in a synchronous nonisolated context」。
-`CodexRateLimitService` 是 `nonisolated final class` + `@unchecked Sendable`,连接状态只在私有串行 `DispatchQueue` 上读写,对外暴露 async 接口。
+`CodexRateLimitService` 是 `nonisolated final class` + `@unchecked Sendable`,连接状态只在私有串行 `DispatchQueue` 上读写,对外暴露 async 接口。
## 认证和沙盒
-CodexBar 必须使用真实 macOS 用户的 Codex 登录数据。之前遇到过 Xcode 运行时 `HOME` 指向 app container,导致 app-server 读取不到 `/Users/{username}/.codex`,报错:
+Xcode target 已关闭 App Sandbox(需要启动本机 Codex CLI 并读取用户登录状态)。服务层用真实用户 home(`getpwuid`)运行 app-server——Xcode 运行时 `HOME` 可能指向 app container,导致读不到 `~/.codex` 而报 "codex account authentication required"。
-```text
-codex account authentication required to read rate limits
-```
-
-当前服务层会用真实用户 home(`getpwuid`)运行 app-server,避免读到沙盒容器路径。
-
-Xcode target 已关闭 App Sandbox,因为应用需要启动本机 Codex CLI 并访问用户的 Codex 登录状态。
-
-如果既找不到全局 Codex CLI,也找不到 Codex.app 内置二进制,弹窗会展示 `找不到 Codex CLI 或 Codex App` 错误。
-
-## 自动更新(Sparkle)
+## UI 与错误展示约定
-应用通过 Sparkle 框架(SwiftPM 依赖)实现自动更新,由 `AppUpdater`(`@MainActor`、`ObservableObject`)封装:
+- 菜单栏正常图标 `person.fill.checkmark`,错误图标 `person.fill.xmark`,切换用 `.contentTransition(.symbolEffect(.replace))`。菜单栏不展示额度数字,详情只在弹窗中展示。
+- App 图标保持白底黑色 `timelapse`。
+- 不要给 symbol API 加低版本 fallback,最低系统版本已是 macOS 15.0。
+- 分段条展示**剩余**额度(`100 - usedPercent`);额度行标签由 `windowDurationMins` 动态生成(如 `300` → `5 小时`,`10080` → `7 天`)。重置时间格式 `MM-dd HH:mm`,更新时间格式 `HH:mm:ss`。
+- token 贡献墙为 30 列 × 7 行蓝色方块热力图,token 数按 `M`/`B` 紧凑单位展示。
+- 设置区仅在按住 Option 点击菜单栏图标时展示。
+- 登录类错误(`requiresLogin`):弹窗顶部橙色提示「Codex 未登录」,旧快照置灰(opacity 0.4)保留,红色错误行被抑制。其他错误:红色小字展示 `errorDescription`,旧快照保持全亮度。
+- 错误文案保持显示直到某次刷新成功(`refresh()` 开始时不清空 `lastError`);旧额度快照永远不清空。
-- `CodexBarApp` 创建 `@StateObject AppUpdater()` 并以 `environmentObject` 注入弹窗,`RateLimitsMenuView` 通过 `@EnvironmentObject` 读取。
-- 初始化时先校验 Info.plist 的 `SUFeedURL`(必须为 http/https)和 `SUPublicEDKey`(非空),任一缺失则**不创建** `SPUStandardUpdaterController`。此时双击版本文案展示「未配置更新资源」,方便 Debug/未签名构建下静默降级。
-- 配置齐全时创建 `SPUStandardUpdaterController(startingUpdater: true)`,`AppUpdater` 自身作为 `SPUUpdaterDelegate`。
-- `statusMessage` 是唯一发布的 UI 状态,由 `showStatusMessage` 设置并在 3 秒后用一个可取消的 `Task` 自动清空(新消息会先取消旧 Task)。状态文案:`正在检查更新`、`未配置更新资源`、`发现新版本 v{x}`、`已是最新版本`。
-- 当前 Info.plist 配置:`SUFeedURL = https://codexbar.zabrian.app/appcast.xml`,`SUScheduledCheckInterval = 3600`。
+## 自动更新(Sparkle)
-## 代码组织
+`AppUpdater`(`@MainActor`、`ObservableObject`)初始化时先校验 Info.plist 的 `SUFeedURL`(http/https)和 `SUPublicEDKey`(非空),任一缺失则不创建 `SPUStandardUpdaterController`,双击版本文案显示「未配置更新资源」(Debug/未签名构建静默降级)。`statusMessage` 是唯一发布的 UI 状态,3 秒后由可取消的 `Task` 自动清空。Info.plist 位于 `CodexBar/Resources/Info.plist`(`SUFeedURL = https://codexbar.zabrian.app/appcast.xml`,检查间隔 3600 秒)。
-- `CodexBarApp.swift`:应用入口,创建 `RateLimitsViewModel`,配置 `MenuBarExtra`。
-- `RateLimitsViewModel.swift`:视图模型。错误状态单一来源:只发布 `lastError: CodexRateLimitError?`,`errorMessage`、`requiresLogin`、`hasError` 都是从它派生的计算属性,不要再加并列的错误布尔。
-- `CodexRateLimitService.swift`:常驻 app-server 连接管理 + JSON-RPC 请求/响应。
-- `RateLimitModels.swift`:Codex 响应模型、业务快照模型、`CodexRateLimitError`(含 `requiresLogin`、`isAuthenticationRequired` 分类属性)。
-- `MenuBarStatusView.swift`:菜单栏常驻图标(checkmark/xmark 切换 + 动画),并在 `.task` 中启动自动刷新。
-- `RateLimitsMenuView.swift`:点击菜单栏后的弹窗内容,含未登录橙色提示和设置区。
-- `QuotaRow.swift`:额度行和分段进度条。
-- `LoginItemSettings.swift`:使用 `SMAppService.mainApp` 管理开机自启。
-- `AppUpdater.swift`:封装 Sparkle 更新检查、状态文案与 `SPUUpdaterDelegate` 回调。
-- `Resources/Info.plist`:应用 Info.plist,含 `SUFeedURL`、`SUPublicEDKey`、`SUScheduledCheckInterval` 等 Sparkle 配置(`INFOPLIST_FILE` 指向此处)。
-- `Resources/Assets.xcassets/AppIcon.appiconset`:App 图标资源,白底黑色中心符号使用 `timelapse`。
-- `Scripts/create-dmg.sh`:将项目根目录下导出的 `.app` 打包成拖拽安装 DMG,结尾提示用 `update-appcast.sh` 更新 appcast。
-- `Scripts/update-appcast.sh`:对 DMG 签名(Sparkle `sign_update`)并把版本条目写入 `Updates/appcast.xml`。
-- `Updates/appcast.xml`:Sparkle appcast feed 源文件,发布时由 `update-appcast.sh` 维护。
+## Git 提交规范
-工程使用文件系统同步组(`PBXFileSystemSynchronizedRootGroup`),新增/删除源文件无需修改 `project.pbxproj`。源码与资源已统一收纳在 `CodexBar/` 下(资源在 `CodexBar/Resources/`)。Sparkle 通过 SwiftPM 引入,依赖变更才需改 `project.pbxproj`。
+- 提交 message 使用 **Conventional Commits 前缀 + 中文描述**,格式:`<type>: <中文描述>`。
+- 常用 type:`feat`(新功能)、`fix`(修复)、`chore`(杂项/发布)、`refactor`(重构)、`docs`(文档)。
+- 描述简洁一行,不加句号。
+- **提交后不要主动 push,必须等用户明确同意后才能推送。**
-## UI 约定
+### Tag 规范
-- 菜单栏正常图标 `person.fill.checkmark`,错误图标 `person.fill.xmark`,切换用 `.contentTransition(.symbolEffect(.replace))` + `.animation(.default, value:)`。
-- 不要给 symbol API 加低版本 fallback;最低系统版本已经定为 macOS 15.0。
-- App 图标保持白底黑色 `timelapse`,不要恢复成蓝绿色图标。
-- 菜单栏不展示额度数字、窗口标签或外层圈数;额度详情只在弹窗中展示。
-- 弹窗账号图标使用 `person.fill`,双击该图标刷新数据。
-- 弹窗字体要保持紧凑,避免菜单栏弹窗内容被截断。
-- 分段条展示剩余额度,剩余额度计算方式是 `100 - usedPercent`。
-- 额度行标签示例:`300` 分钟显示 `5 小时`,`10080` 分钟显示 `7 天`;缺少 `windowDurationMins` 时再回退到默认文案。
-- 重置时间格式使用 `MM-dd HH:mm`;更新时间格式使用 `HH:mm:ss`。
-- 版本文案格式 `App 版本: v{CFBundleShortVersionString} ({CFBundleVersion})`,用 `monospacedDigit` 字体、`lineLimit(1)`;有 `statusMessage` 时优先展示状态文案。读取 Info.plist 统一用 `Bundle.main.object(forInfoDictionaryKey:)`。
-- token 数按 `M`、`B` 紧凑单位展示;token 贡献墙使用蓝色方块,7 行 30 列布局,单日用量越高颜色越深
+- tag 名格式:`v{MARKETING_VERSION}`(如 `v1.2.1`),与 Xcode target 的 `MARKETING_VERSION` 保持一致。
+- 使用**附注 tag**(`git tag -a`),message 格式:`Release v{version}`(如 `git tag -a v1.2.1 -m "Release v1.2.1"`)。
+- tag 同样不要主动 push,等用户明确同意。
-## 错误展示约定
+## 发布流程
-- 登录类错误(`requiresLogin` 为 true:`notLoggedIn`、`authenticationRequired`、消息含 "authentication required" 的 `serverError`):弹窗顶部橙色提示「Codex 未登录」+ 图标 `person.crop.circle.badge.exclamationmark`;旧快照置灰(opacity 0.4)保留展示;红色错误行被抑制,避免重复文案。
-- 其他错误:弹窗红色小字展示 `errorDescription`;旧快照保持全亮度。
-- 错误文案保持显示直到某次刷新成功(`refresh()` 开始时不清空 `lastError`)。
-- 旧额度快照永远不清空,弹窗继续显示上一次成功读取的数据和更新时间。
-- 开机启动设置失败会展示 `设置开机启动失败: ...`,属于 `LoginItemSettings` 的独立错误位,与额度错误互不影响。
-
-## 构建验证
-
-修改后运行确保无 error 和 warning
-
-```bash
-xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/platform=macOS' build
-```
-
-SourceKit 经常对跨文件类型报「Cannot find type ... in scope」,属索引滞后误报,以 `xcodebuild` 实际编译结果为准。
-
-## 分发备注
-
-项目用于直接分发时,应使用 `Developer ID Application` 证书签名,并进行 notarization。
-
-Xcode 导出 `CodexBar.app` 到项目根目录后,可以运行:
-
-```bash
-Scripts/create-dmg.sh
-```
-
-脚本会自动查找当前目录下唯一的 `.app`,根据 Xcode target 的 `MARKETING_VERSION` 生成 `CodexBar-v{version}.dmg`。脚本会在 DMG 中放入 `CodexBar.app` 和 `Applications -> /Applications` 快捷方式,并写入 Finder 布局:app 在左侧,Applications 在右侧。若有多个工程或 scheme,可用 `XCODE_PROJECT`、`XCODE_SCHEME` 环境变量指定。
-
-打包 DMG 后用 `update-appcast.sh` 更新 Sparkle appcast:
-
-```bash
-Scripts/update-appcast.sh CodexBar-v1.2.0.dmg # 省略参数时自动取根目录下唯一 .dmg
-```
-
-脚本流程:用 Sparkle `sign_update`(PATH 中没有则在 DerivedData 内查找)对 DMG 签名得到 `edSignature` 和长度,从 `xcodebuild -showBuildSettings` 读取 `MARKETING_VERSION`/`CURRENT_PROJECT_VERSION`,生成 `<item>` 并插入 `Updates/appcast.xml`(按 `sparkle:version` 去重同版本旧条目,插在 `<language>` 之后),最后用 `xmllint` 校验。常用环境变量:`DOWNLOAD_BASE_URL`、`RELEASE_NOTES_BASE_URL`、`INCLUDE_RELEASE_NOTES`、`MINIMUM_SYSTEM_VERSION`、`SIGN_UPDATE`、`APPCAST_PATH`。发布时需把 DMG 上传到 `SUFeedURL` 对应的下载站点,并发布更新后的 `appcast.xml`。
-
-## Git 远端
-
-当前远端仓库:
-
-```text
[email protected]:bob-zebedy/CodexBar.git
-```
+1. 用 `Developer ID Application` 证书签名并 notarization,Xcode 导出 `CodexBar.app` 到项目根目录。
+2. `Scripts/create-dmg.sh`:自动找到根目录唯一 `.app`,按 `MARKETING_VERSION` 生成 `CodexBar-v{version}.dmg`(含 Applications 快捷方式和 Finder 布局)。
+3. `Scripts/update-appcast.sh [dmg]`:用 Sparkle `sign_update` 签名 DMG,从 build settings 读版本号,将 `<item>` 写入 `Updates/appcast.xml`(同版本去重,`xmllint` 校验)。常用环境变量:`DOWNLOAD_BASE_URL`、`INCLUDE_RELEASE_NOTES`、`MINIMUM_SYSTEM_VERSION` 等。
+4. 上传 DMG 和更新后的 `appcast.xml` 到 `SUFeedURL` 对应站点。
diff --git a/CLAUDE.md b/CLAUDE.md
index 3cd7682..4c8adba 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,3 +1,99 @@
# CLAUDE.md
-完整项目记忆(架构、JSON-RPC 协议、UI 约定、错误展示规则)见 @AGENTS.md,两份文档以它为准,更新记忆时优先改它。
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 项目概览
+
+CodexBar 是一个 macOS 菜单栏应用(SwiftUI + MVVM,最低 macOS 15.0),通过本机 Codex app-server 展示当前 Codex 账号的额度和 token 用量。主入口是 `MenuBarExtra`,弹窗使用 `.menuBarExtraStyle(.window)`。唯一外部依赖是 Sparkle(SwiftPM)。
+
+## 构建验证
+
+修改后运行以下命令,确保无 error 和 warning:
+
+```bash
+xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/platform=macOS' build
+```
+
+SourceKit 经常对跨文件类型误报「Cannot find type ... in scope」(索引滞后),以 `xcodebuild` 实际编译结果为准。
+
+工程使用文件系统同步组(`PBXFileSystemSynchronizedRootGroup`):新增/删除源文件无需修改 `project.pbxproj`,只有依赖变更才需要改它。
+
+## 架构
+
+数据流:`CodexRateLimitService`(JSON-RPC 常驻连接)→ `RateLimitsViewModel`(状态发布)→ `MenuBarStatusView`(菜单栏图标 + 在 `.task` 中驱动每分钟自动刷新)/ `RateLimitsMenuView`(弹窗)。
+
+- `CodexBarApp.swift`:入口,创建 `RateLimitsViewModel` 和 `@StateObject AppUpdater`,后者以 `environmentObject` 注入弹窗。
+- `CodexRateLimitService.swift`:app-server 常驻连接管理 + JSON-RPC 请求/响应。
+- `RateLimitModels.swift`:响应模型、业务快照模型、`CodexRateLimitError`(含 `requiresLogin`、`isAuthenticationRequired` 分类属性)。
+- `RateLimitsViewModel.swift`:错误状态单一来源——只发布 `lastError: CodexRateLimitError?`,`errorMessage`、`requiresLogin`、`hasError` 都是派生计算属性,**不要再加并列的错误布尔**。
+- `QuotaRow.swift`:额度行和分段进度条;`LoginItemSettings.swift`:`SMAppService.mainApp` 开机自启;`AppUpdater.swift`:Sparkle 封装。
+
+## Codex app-server 连接(核心逻辑)
+
+启动优先级:全局 `codex` CLI 优先,找不到则回退 `/Applications/Codex.app/Contents/Resources/codex`;两者都没有时弹窗展示「找不到 Codex CLI 或 Codex App」。启动命令:`codex app-server --listen stdio://`。
+
+应用维持**一条常驻连接**,首次握手顺序(必须在请求额度前完成,否则 app-server 拒绝请求):
+
+```json
+{"method":"initialize","id":1,"params":{"clientInfo":{"name":"codex_bar","title":"Codex Bar","version":"1.0.0"}}}
+{"method":"initialized"}
+{"method":"account/read","id":2,"params":{"refreshToken":false}}
+```
+
+之后每分钟在同一会话上请求 `account/rateLimits/read` 和 `account/usage/read`。
+
+连接重建规则(`CodexRateLimitService.ensureConnection`):
+
+- 进程已退出 → 重建。
+- 连接存活超过 `connectionMaxAge`(1 小时)→ 定期回收重建(覆盖 codex 全局升级、服务端状态漂移)。
+- **复用的**连接上请求失败 → 丢弃重建一次再试;**全新**连接上的失败直接抛出,不做二次重试。
+- 登录类错误(`requiresLogin`)→ 丢弃连接但不重试;下次轮询起新进程读取最新 `~/.codex/auth.json`,用户重新登录后最多一分钟自动恢复。
+
+认证重试:`account/rateLimits/read` 返回认证错误时,先在同一会话上调 `account/read`(`refreshToken: true`)再重试一次;仍失败抛 `authenticationRequired`。
+
+token 统计来自 `account/usage/read`(`summary.lifetimeTokens`、`summary.peakDailyTokens`、`dailyUsageBuckets`);本机 app-server 不支持该方法时,token 区域不展示,额度信息仍正常显示。
+
+## 并发约定
+
+工程开启了 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`:未显式标注的类型一律推断为 MainActor 隔离。因此**所有非 UI 类型必须显式标 `nonisolated`**,否则会报「Call to main actor-isolated initializer in a synchronous nonisolated context」。
+
+`CodexRateLimitService` 是 `nonisolated final class` + `@unchecked Sendable`,连接状态只在私有串行 `DispatchQueue` 上读写,对外暴露 async 接口。
+
+## 认证和沙盒
+
+Xcode target 已关闭 App Sandbox(需要启动本机 Codex CLI 并读取用户登录状态)。服务层用真实用户 home(`getpwuid`)运行 app-server——Xcode 运行时 `HOME` 可能指向 app container,导致读不到 `~/.codex` 而报 "codex account authentication required"。
+
+## UI 与错误展示约定
+
+- 菜单栏正常图标 `person.fill.checkmark`,错误图标 `person.fill.xmark`,切换用 `.contentTransition(.symbolEffect(.replace))`。菜单栏不展示额度数字,详情只在弹窗中展示。
+- App 图标保持白底黑色 `timelapse`。
+- 不要给 symbol API 加低版本 fallback,最低系统版本已是 macOS 15.0。
+- 分段条展示**剩余**额度(`100 - usedPercent`);额度行标签由 `windowDurationMins` 动态生成(如 `300` → `5 小时`,`10080` → `7 天`)。重置时间格式 `MM-dd HH:mm`,更新时间格式 `HH:mm:ss`。
+- token 贡献墙为 30 列 × 7 行蓝色方块热力图,token 数按 `M`/`B` 紧凑单位展示。
+- 设置区仅在按住 Option 点击菜单栏图标时展示。
+- 登录类错误(`requiresLogin`):弹窗顶部橙色提示「Codex 未登录」,旧快照置灰(opacity 0.4)保留,红色错误行被抑制。其他错误:红色小字展示 `errorDescription`,旧快照保持全亮度。
+- 错误文案保持显示直到某次刷新成功(`refresh()` 开始时不清空 `lastError`);旧额度快照永远不清空。
+
+## 自动更新(Sparkle)
+
+`AppUpdater`(`@MainActor`、`ObservableObject`)初始化时先校验 Info.plist 的 `SUFeedURL`(http/https)和 `SUPublicEDKey`(非空),任一缺失则不创建 `SPUStandardUpdaterController`,双击版本文案显示「未配置更新资源」(Debug/未签名构建静默降级)。`statusMessage` 是唯一发布的 UI 状态,3 秒后由可取消的 `Task` 自动清空。Info.plist 位于 `CodexBar/Resources/Info.plist`(`SUFeedURL = https://codexbar.zabrian.app/appcast.xml`,检查间隔 3600 秒)。
+
+## Git 提交规范
+
+- 提交 message 使用 **Conventional Commits 前缀 + 中文描述**,格式:`<type>: <中文描述>`。
+- 常用 type:`feat`(新功能)、`fix`(修复)、`chore`(杂项/发布)、`refactor`(重构)、`docs`(文档)。
+- 描述简洁一行,不加句号。
+- **提交后不要主动 push,必须等用户明确同意后才能推送。**
+
+### Tag 规范
+
+- tag 名格式:`v{MARKETING_VERSION}`(如 `v1.2.1`),与 Xcode target 的 `MARKETING_VERSION` 保持一致。
+- 使用**附注 tag**(`git tag -a`),message 格式:`Release v{version}`(如 `git tag -a v1.2.1 -m "Release v1.2.1"`)。
+- tag 同样不要主动 push,等用户明确同意。
+
+## 发布流程
+
+1. 用 `Developer ID Application` 证书签名并 notarization,Xcode 导出 `CodexBar.app` 到项目根目录。
+2. `Scripts/create-dmg.sh`:自动找到根目录唯一 `.app`,按 `MARKETING_VERSION` 生成 `CodexBar-v{version}.dmg`(含 Applications 快捷方式和 Finder 布局)。
+3. `Scripts/update-appcast.sh [dmg]`:用 Sparkle `sign_update` 签名 DMG,从 build settings 读版本号,将 `<item>` 写入 `Updates/appcast.xml`(同版本去重,`xmllint` 校验)。常用环境变量:`DOWNLOAD_BASE_URL`、`INCLUDE_RELEASE_NOTES`、`MINIMUM_SYSTEM_VERSION` 等。
+4. 上传 DMG 和更新后的 `appcast.xml` 到 `SUFeedURL` 对应站点。
diff --git a/Images/screenshot.png b/Images/screenshot.png
new file mode 100644
index 0000000..e0b7952
Binary files /dev/null and b/Images/screenshot.png differ
diff --git a/README.md b/README.md
index a0f66c5..7e6f70d 100644
--- a/README.md
+++ b/README.md
@@ -1,168 +1,48 @@
# CodexBar
-CodexBar 是一个轻量级 macOS 菜单栏应用,用来查看当前本机 Codex 账号的额度使用情况。
-
-它会启动本机 Codex 的 app-server 并维持一条常驻 JSON-RPC 连接,完成初始化握手后定期读取账号信息和额度信息,并在菜单栏弹窗中展示不同时间窗口的额度。
-
-## 功能
-
-- 菜单栏图标:正常时显示 `person.fill.checkmark`,任何错误(包括未登录)时切换为 `person.fill.xmark`,切换带 symbol 替换动画
-- App 图标是白底黑色 `timelapse`
-- 弹窗第一行展示账号信息和套餐
-- 弹窗使用两行分段电量条展示额度窗口,标签根据 `windowDurationMins` 动态生成
-- 每行额度在进度条右侧展示剩余百分比和重置时间
-- 弹窗展示 30 周宽度的完整自然日 token 蓝色贡献墙、累计 token 和单日峰值 token
-- 鼠标划过 token 贡献墙中的单日方块时,在鼠标旁展示对应日期和用量
-- 更新时间显示在额度行下方,并使用 `HH:mm:ss` 格式
-- 应用运行时每分钟自动刷新额度,即使弹窗未打开也会刷新
-- 双击账号图标可手动刷新
-- 不按 Option/Alt 点击菜单栏图标时,只展示额度内容
-- 按住 Option/Alt 点击菜单栏图标时,才展示设置区;设置区为单行布局,左侧「开机自动启动」开关,右侧「退出」按钮
-- 未登录或认证失效时,弹窗顶部展示橙色提示,旧额度数据置灰保留展示
-- 更新时间行右侧展示当前 App 版本,双击即可通过 Sparkle 检查更新
-- 集成 Sparkle 自动更新,启动后会定期在后台静默检查新版本
-
-## 运行要求
+> 在 macOS 菜单栏实时查看 Codex 账号额度和 token 用量。
-- macOS 15.0 或更高版本
-- 已安装全局 Codex CLI,或已安装 Codex.app
-- 当前 macOS 用户已在 Codex 中完成登录
-
-CodexBar 会优先使用全局 Codex CLI 启动本机 app-server:
-
-```bash
-codex app-server --listen stdio://
-```
-
-如果找不到全局 `codex` 命令,会回退到 Codex.app 内置的二进制:
-
-```bash
-/Applications/Codex.app/Contents/Resources/codex app-server --listen stdio://
-```
-
-如果两个入口都不可用,弹窗中会展示「找不到 Codex CLI 或 Codex App」的错误。
-
-## 连接与刷新
-
-应用与 app-server 维持一条常驻连接:首次拉取时启动进程并完成握手,之后所有额度读取复用同一会话。
-
-建立连接时按顺序发送:
+CodexBar 是一个轻量级 macOS 菜单栏应用。它直接连接本机 Codex 的 app-server,定期读取额度信息,让你不用打开终端就能随时知道: 还剩多少额度、什么时候重置、最近用了多少 token。
-```json
-{"method":"initialize","id":1,"params":{"clientInfo":{"name":"codex_bar","title":"Codex Bar","version":"1.0.0"}}}
-{"method":"initialized"}
-{"method":"account/read","id":2,"params":{"refreshToken":false}}
-```
-
-之后每分钟在同一会话上读取额度和用量:
-
-```json
-{"method":"account/rateLimits/read","id":3}
-{"method":"account/usage/read","id":4}
-```
-
-连接会在以下情况自动重建:
-
-- app-server 进程已退出
-- 连接存活超过 1 小时(定期回收,覆盖 codex 全局升级后切换新二进制、服务端状态漂移等陈旧问题)
-- 复用连接上的请求失败(重建一次再试;全新连接上的失败直接报错,不做二次重试)
-
-认证处理:`account/rateLimits/read` 返回认证错误时,会先用 `account/read`(`refreshToken: true`)刷新 token 再重试一次;仍然失败则按「需要重新登录」处理,丢弃当前连接——下一次轮询会起新进程读取最新的登录凭证,因此用户重新登录后最多一分钟自动恢复。
+<p align="center">
+ <img src="Images/screenshot.png" alt="CodexBar" width="532">
+</p>
-## 额度数据
+## 特性
-额度窗口来自 Codex app-server 返回的 `primary` 和 `secondary`:
+- **额度一目了然**: 分段电量条展示各时间窗口(如 5 小时、7 天)的剩余额度,附剩余百分比和重置时间
+- **token 贡献墙**: 30 周的每日 token 用量热力图,鼠标悬停查看单日明细,同时展示累计 token 和单日峰值
+- **自动刷新**: 每分钟后台刷新一次,弹窗未打开也保持最新;双击账号图标可手动刷新
+- **开机自启**: 按住 Option 点击菜单栏图标打开设置区
+- **本地优先**: 只与本机 Codex app-server 进程通信,不向任何第三方服务发送账号或额度数据
-- `usedPercent`:已用百分比
-- `windowDurationMins`:额度窗口分钟数,用来生成 `5 小时`、`7 天` 等标签
-- `resetsAt`:秒级 Unix 时间戳,弹窗中显示为 `MM-dd HH:mm`
+## 安装
-剩余额度统一按 `100 - usedPercent` 计算。
+### 下载 DMG
-token 使用量来自 `account/usage/read`:
+从 [Releases](https://github.com/bob-zebedy/CodexBar/releases) 下载。
-- `summary.lifetimeTokens`:累计 token
-- `summary.peakDailyTokens`:单日峰值 token
-- `dailyUsageBuckets`:按天聚合的 token 使用量,日期字段为 `startDate`
+之后的新版本会通过内置的 Sparkle 自动更新推送。
-如果本机 Codex app-server 不支持 `account/usage/read`,token 统计区域不会展示,额度信息仍会正常显示。
+### 运行要求
-token 数使用 `M`、`B` 紧凑单位展示。
-token 贡献墙使用蓝色方块,7 行 30 列布局,单日用量越高颜色越深。
-
-## 错误展示
-
-错误分为两类,展示方式不同:
-
-- **登录类错误**(未登录、认证失效):菜单栏图标切换为 `person.fill.xmark`;弹窗顶部展示橙色提示「Codex 未登录」;如果之前成功读取过额度,旧快照置灰保留展示,表示数据已过期。
-- **其他错误**(未安装 Codex、app-server 启动失败、响应超时、响应中缺少额度窗口等):菜单栏图标同样切换为 `person.fill.xmark`;弹窗中用红色小字展示错误文案;旧快照保持正常亮度展示,可通过更新时间判断数据新旧。
-
-错误文案会保持显示,直到某次刷新成功才清除。应用不包含调试模拟入口,也不会在窗口里展示 Debug 明细。
+- macOS 15.0 或更高版本
+- 已安装 [Codex CLI](https://github.com/openai/codex) (全局 `codex` 命令) 或 Codex.app
+- 当前 macOS 用户已在 Codex 中完成登录
-## 构建
+> 提示: 如果把应用移动到 `/Applications` 后才开启开机自启,建议重新开关一次「开机启动」让 macOS 记录最终路径。
-可以直接用 Xcode 打开 `CodexBar.xcodeproj`,也可以使用命令行构建:
+## 从源码构建
```bash
+git clone [email protected]:bob-zebedy/CodexBar.git
+cd CodexBar
xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/platform=macOS' build
```
-## 分发
-
-如果不通过 App Store 分发,可以在 Xcode 中 Archive,然后使用 `Developer ID Application` 证书导出应用。
-
-分享给其他用户前,建议完成 notarization,这样 macOS Gatekeeper 可以正常校验应用来源。
-
-导出 `CodexBar.app` 到项目根目录后,可以用脚本生成拖拽安装 DMG:
-
-```bash
-Scripts/create-dmg.sh
-```
-
-脚本会自动查找当前目录下唯一的 `.app`,生成项目根目录下的 `CodexBar-v{version}.dmg`,并在 DMG 中放入:
-
-- `CodexBar.app`
-- `Applications -> /Applications` 快捷方式
-
-DMG 文件名中的版本号来自 Xcode target 的 `MARKETING_VERSION`,读取失败时才会回退到 app 的 `Info.plist`。如果项目中有多个 Xcode 工程或 scheme,可以通过环境变量指定:
-
-```bash
-XCODE_PROJECT=CodexBar.xcodeproj XCODE_SCHEME=CodexBar Scripts/create-dmg.sh
-```
-
-脚本会写入 Finder 布局:打开 DMG 后 `CodexBar.app` 在左侧,`Applications` 快捷方式在右侧。
-
-也可以显式指定输入 app 和输出路径:
-
-```bash
-Scripts/create-dmg.sh CodexBar.app CodexBar-v1.0.0.dmg
-```
-
-如果把应用移动到 `/Applications` 后再使用开机自启,建议打开应用后重新开启一次「开机启动」,让 macOS 记录最终的应用路径。
-
-## 自动更新
-
-CodexBar 内置 [Sparkle](https://sparkle-project.org) 自动更新。应用会按 Info.plist 中 `SUScheduledCheckInterval`(默认 1 小时)在后台静默检查,更新源为 `SUFeedURL` 指向的 appcast。弹窗更新时间行右侧也会显示当前版本,双击即可手动检查。
-
-发布新版本时,打包 DMG 后用脚本更新 appcast:
-
-```bash
-Scripts/update-appcast.sh CodexBar-v1.2.0.dmg
-```
-
-脚本会用 Sparkle 的 `sign_update` 对 DMG 签名,从 Xcode build settings 读取版本号,生成条目并写入 `Updates/appcast.xml`(自动去重同版本旧条目,并用 `xmllint` 校验)。省略参数时会自动取项目根目录下唯一的 `.dmg`。常用环境变量:
-
-- `DOWNLOAD_BASE_URL`:DMG 下载地址前缀
-- `RELEASE_NOTES_BASE_URL` / `INCLUDE_RELEASE_NOTES`:发行说明链接前缀,置 `0` 可省略
-- `MINIMUM_SYSTEM_VERSION`:最低系统版本(默认 15.0)
-- `SIGN_UPDATE`:`sign_update` 工具路径(默认从 PATH 或 DerivedData 查找)
-
-随后把 DMG 上传到下载站点,并发布更新后的 `appcast.xml`,客户端即可收到更新。
+也可以直接用 Xcode 打开 `CodexBar.xcodeproj` 运行。项目使用 SwiftUI + MVVM 依赖 Sparkle (SwiftPM)
## 隐私
-CodexBar 只会和本机 Codex app-server 进程通信,不会把账号信息或额度数据发送给任何第三方服务。
-
-## 友情链接
-
-[感谢 Linux DO 社区的大力支持](https://linux.do)
+CodexBar 只与本机 Codex app-server 进程通信。账号信息和额度数据不会被收集和发送到任何个人和服务
+只有更新 App 会产生额外的网络请求仅包含 [appcast](https://codexbar.zabrian.app/appcast.xml) 和 appcast 中对应的 DMG 下载地址