CodexBar 是一个 macOS 菜单栏应用,用于查看本机 Codex 账号状态、额度、Token 用量、详细统计信息
Swift appkitcodexcodex-clideveloper-toolsmacosmacos-appmenu-bar-appopenai-codexproductivityswiftswiftuiusage-tracker
feat: 防休眠状态改由活动卡片呈现
Bobf52f1d984f51
diff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 0000000..426acb1--- /dev/null+++ b/AGENTS.md@@ -0,0 +1,56 @@+# Repository Guidelines++## 项目结构与模块组织++CodexBar 是面向 macOS 15+ 的 `LSUIElement` 菜单栏应用, 使用 Swift 6, SwiftUI, AppKit 和 MVVM. 工程只有 `CodexBar` scheme, 包含主 App 与 `CodexBarHelper` 两个 target++`CodexBar/` 按 `App/` `Views/` `Controllers/` `Models/` `Services/` 和 `Resources/` 分层. root LaunchDaemon 位于 `CodexBarHelper/` 目录, 跨 target XPC 接口位于 `Shared/` 目录. `Scripts/` 提供发布和 helper 清理工具, `Images/` 存放 README 资源++## 构建, 测试与开发命令++- `open CodexBar.xcodeproj` 在 Xcode 中运行 Debug scheme+- `xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/platform=macOS' build` 执行日常构建验证+- `swiftformat .` 按 `.swiftformat` 格式化全部 Swift, 使用 Swift 6 和 4 空格缩进+- `swiftlint` 按 `.swiftlint.yml` 检查 `CodexBar/`+- `Scripts/cleanup.swift --help` 查看 KeepAlive helper 清理选项++`Scripts/build.sh` `dmg.sh` 和 `appcast.sh` 需要 Developer ID 与公证凭据, 不用于日常验证++## 写作风格++本仓库的中文文本 (提交信息, 代码注释, 文档) 统一遵守++- 禁止使用中文标点, 一律使用半角标点+- 句中停顿和并列项使用空格或者逗号, 顿号的位置也用空格或者逗号+- 分号只用来断开完整句子, 相当于句号; 拿不准就把它换成句号读一遍, 两边都能独立成句才保留+- 行末禁止使用标点+- 行内标点后如果还有文字, 间隔一个英文空格+- 行内代码后尽量不要紧跟标点, 需要断句时补一个词或者使用空格再断+- 一条 bullet 只讲一件事, 需要两个以上完整句子时拆成多条++## 架构与编码约定++启动时必须先调用 `WorkflowHookEventRecorder.handleIfRequested()` 方法. `--hook-event` 模式只读取 stdin, 加锁写入 JSONL 并立即退出, 不初始化 UI, 失败也不能阻断 Codex. 普通模式由 `CodexBarAppDelegate` 统一装配长期服务++工程默认采用 `MainActor` 隔离. UI, Controller, ViewModel 和 Settings 依赖默认隔离, 共享可变状态放入 actor, DTO 和跨 actor 值类型按需添加 `nonisolated` 标记, 禁止在主 actor 执行阻塞 I/O. 类型命名使用 `UpperCamelCase` 风格, 成员命名使用 `lowerCamelCase` 风格. 注释只解释非显然的生命周期, 焦点, actor 或系统 API 约束++保持三条数据链路独立: app-server 额度与用量, Hook 历史聚合, `CodexActivityMonitor` 实时任务; helper 只能控制休眠, 不得增加网络, 任意命令执行或额外文件访问; 修改 Hook 配置时必须保留用户和其他应用已有的 handler; 新增网络访问, 日志数据或 CloudKit 字段前先核对隐私边界++## 测试规范++仓库没有 XCTest target 或覆盖率门槛. 每次改动至少应完成构建, 运行 `swiftformat` 和 `swiftlint` 两项检查, 并手动验证受影响流程. 菜单, 窗口焦点, Hook, 同步, 通知和防休眠改动必须说明手动验证场景. Debug 与 Release 使用不同 App 和 helper bundle ID, 排查时不要混用++## Commit 与 Pull Request 规范++不要主动 push, 不要回滚, 覆盖或丢弃他人的未提交修改. 用户只要求提交时, 不要顺带格式化或修改文件++提交标题使用 `<type>: <中文描述>` 格式++- 常用 type 包括 `feat` `fix` `chore` `refactor` `docs`+- message 里不要出现版本号或发布字样, 只描述改动本身, 版本信息由 tag 承载+- 修复和发布提交需要 body+- 标题与 body 之间空一行+- body 中的 bullet 连续排列, 每条缩进 4 个空格+- commit message 中不要出现版本号, Release 标记或其他发布版本相关内容++PR 应说明用户影响, 实现范围, 关联 issue 和验证结果, UI 改动附截图或录屏. 涉及旧数据, 持久化 key, 云端格式, 最低系统版本或新旧共存的兼容性决策, 必须先说明选项与代价并询问用户diff --git a/CLAUDE.md b/CLAUDE.mdindex b4380d2..16ab6f3 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -4,20 +4,23 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co## 写作风格-本仓库的中文文本 (提交信息; 代码注释; 文档) 统一遵守+本仓库的中文文本 (提交信息, 代码注释, 文档) 统一遵守- 禁止使用中文标点, 一律使用半角标点+- 句中停顿和并列项使用空格或者逗号, 顿号的位置也用空格或者逗号+- 分号只用来断开完整句子, 相当于句号; 拿不准就把它换成句号读一遍, 两边都能独立成句才保留- 行末禁止使用标点- 行内标点后如果还有文字, 间隔一个英文空格- 行内代码后尽量不要紧跟标点, 需要断句时补一个词或者使用空格再断+- 一条 bullet 只讲一件事, 需要两个以上完整句子时拆成多条## 项目概述-CodexBar 是一个 macOS 菜单栏应用, 以 `LSUIElement` 方式运行, 没有 Dock 图标, 展示本机 Codex 的账号状态; 额度; Token 用量; 实时任务和工作流统计; 技术栈 Swift 6 + SwiftUI + AppKit + MVVM, 唯一外部依赖是 Sparkle 2.9.3+ (SwiftPM); 最低系统版本 macOS 15.0+CodexBar 是一个 macOS 菜单栏应用, 以 `LSUIElement` 方式运行, 没有 Dock 图标, 展示本机 Codex 的账号状态, 额度, Token 用量, 实时任务和工作流统计; 技术栈 Swift 6 + SwiftUI + AppKit + MVVM, 唯一外部依赖是 Sparkle 2.9.3+ (SwiftPM); 最低系统版本 macOS 15.0Xcode 工程有两个 target: 主 App `CodexBar` 和随 App 嵌入的 root helper `CodexBarHelper` (command-line tool + LaunchDaemon); **没有测试 target**, 验证靠构建通过 + 实际运行-App Sandbox 未开启, entitlements 只声明 iCloud/CloudKit, 因为需要启动本机 `codex` 进程; 读取用户 Codex 登录状态; 写入用户级 Hook 配置+App Sandbox 未开启, entitlements 只声明 iCloud/CloudKit, 因为需要启动本机 `codex` 进程, 读取用户 Codex 登录状态, 写入用户级 Hook 配置## 常用命令@@ -29,7 +32,7 @@ xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/plswiftformat .# Lint: 配置在 .swiftlint.yml, included 只有 CodexBar/-# 即 Shared/; CodexBarHelper/; Scripts/ 不在 lint 范围内+# 即 Shared/ CodexBarHelper/ Scripts/ 不在 lint 范围内swiftlint# 发布流程 (需要 Developer ID 凭据, 不要当普通本地验证跑)@@ -52,13 +55,14 @@ Debug 与 Release 使用不同 bundle ID, 分别是 `app.zabrian.codexbar.debug`## Git 规则- 不要主动 push, 除非用户明确要求-- 不要回滚; 覆盖或丢弃不是你产生的未提交改动, 工作树可能是脏的-- 被要求提交时, **禁止**顺带修改任何文件内容: 不格式化; 不清理; 不补文档, 只把当前已有改动原样提交+- 不要回滚, 覆盖或丢弃不是你产生的未提交改动, 工作树可能是脏的+- 被要求提交时, **禁止**顺带修改任何文件内容: 不格式化, 不清理, 不补文档, 只把当前已有改动原样提交Commit message: Conventional Commits 前缀 + 中文标题, 需要 body 时空一行后写 4 空格缩进 bullet- 标题写成 `<type>: <中文描述>` 的形式, 不加句号; 常用 type 有 `feat` `fix` `chore` `refactor` `docs`-- 功能; 修复; 发布类提交必须写 body; 简单文档或杂项可只写标题行+- message 里不要出现版本号或发布字样, 只描述改动本身, 版本信息由 tag 承载+- 功能 修复 发布类提交必须写 body; 简单文档或杂项可只写标题行- body 中多条 bullet 连续排列, bullet 之间不空行- 命令行提交时把完整 body 放进同一个 `-m` 参数或改用 `git commit -F` 传文件, 不要为每条 bullet 单独 `-m`- message 中禁止使用中文标点, 行末禁止使用标点, 行内标点后如果有文字则间隔一个英文空格@@ -100,7 +104,7 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev**链路三: 实时任务, 由 `CodexActivityMonitor` 驱动**-`CodexActivityMonitor` 是菜单栏图标; 活动卡片; 通知; 触觉反馈和防休眠的**唯一任务状态来源**, 由两个 reader 供料+`CodexActivityMonitor` 是菜单栏图标, 活动卡片, 通知, 触觉反馈和防休眠的**唯一任务状态来源**, 由两个 reader 供料- `HookEventTailReader` (actor) 的 bootstrap 覆盖滚动 24 小时并作为单次事务发送, 之后按当日文件 offset 增量 tail- `CodexSessionLifecycleReader` (actor) 增量读取 `~/.codex/sessions` 与 `archived_sessions` 下的 rollout JSONL, 只提取 turn 生命周期字段, 不解码会话或工具内容@@ -119,23 +123,25 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev关键约束- `shouldDisableSleep` 是用户意图与依赖可用性的唯一汇合点, 要求 `isEnabled && codexHookSettings.isEnabled && hasRunningTasks && helperStatus == .enabled && !hasReachedMaximumDuration` 同时成立; **依赖不满足只让效果失效, 绝不回写用户保存的 `isEnabled`**-- helper 只做一件事; 不要给 root helper 增加网络; 任意命令执行或其他文件访问能力+- helper 只做一件事; 不要给 root helper 增加网络, 任意命令执行或其他文件访问能力- 调用方校验由 XPC 层强制; helper 启动时用 `SecCodeCopySelf` 读自身签名, 拼出形如 `anchor apple generic and certificate leaf[subject.OU] = "<team>" and identifier "<主 App identifier>"` 的 requirement 字符串, 交给 `NSXPCListener.setConnectionCodeSigningRequirement` 生效; 没有逐次连接的 audit token 检查, 改签名或改 bundle ID 会直接连不上- 恢复哨兵放在 `/Library/Application Support/CodexBar/<machService>.state` 这个路径, **必须保持 `absent` `present` `unreadable` 三态**, 把读取失败折叠成 nil 会让恢复流程以为无需恢复, 使 `SleepDisabled=1` 永久残留; watchdog 宽限 15 秒, 哨兵自检 60 秒一次- 切换失败按 2/4/8...256 秒重试, 列表耗尽 (约 8.5 分钟) 即放弃, 瞬时抖动能自愈, 权限类故障不该无限重试+- 状态只呈现在主面板活动卡片右侧的咖啡杯标记, 由 `KeepAliveController.isActivelyPreventingSleep` 驱动, 卡片折叠成"暂无数据"时标记要跟着一起收+- **菜单栏图标不承载防休眠状态**, 它要保持模板渲染让系统按菜单栏外观着色, 自行着色在深浅和带染色的菜单栏下都会失控### 通知-- `CodexNotificationService` 是集中式的 MainActor 服务, 订阅额度快照与实时活动, 负责阈值穿越判定; 去重, dedup key 落 UserDefaults; 额度重置识别; 触觉反馈和本地通知+- `CodexNotificationService` 是集中式的 MainActor 服务, 订阅额度快照与实时活动, 负责阈值穿越判定, 去重, 额度重置识别, 触觉反馈和本地通知; dedup key 落 UserDefaults- `NotificationSettings` 管 CodexBar 自身通知; `CodexCLINotificationSettings` 是另一回事, 它通过 app-server `config/read` 与 `config/batchWrite` 读写 Codex 自己的用户级 `config.toml`### 并发与隔离工程开启 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor` 设置, 所有类型默认 MainActor 隔离-- UI; 控制器; ViewModel; Settings; 更新类直接依赖默认隔离, 不需要额外标注+- UI, 控制器, ViewModel, Settings, 更新类直接依赖默认隔离, 不需要额外标注- 服务共享状态用 actor 管理, 包括 `CodexStatusService` `WorkflowService` `WorkflowSyncService` `CodexCLIVersionService` `HookEventTailReader` `CodexSessionLifecycleReader`-- DTO; 纯模型; 静态工具; 跨 actor 传递的类型必须显式标注 `nonisolated`+- DTO, 纯模型, 静态工具, 跨 actor 传递的类型必须显式标注 `nonisolated`- 跨进程写统计文件用 `stats.lock` 加 `flock` 保护, Hook 子进程有等待上限, 主 App 无限等待; `RequestLogStorage` 用 `OSAllocatedUnfairLock`- 非 Sendable 的管道 IO 集中在 `PipeReadBuffer` 里, `JSONLineReader` 与 `PipeDrain` 复用它- 保留既有防重入与过期结果丢弃逻辑, 例如 `RefreshTaskCoordinator` 只让最新 generation 提交结果@@ -143,7 +149,7 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev### 错误处理原则-- 菜单面板的 `CodexFetchOutcome` 只暴露有数据; 未登录; 初始化失败三种结果, 而启动失败; 超时; 断连; 解析失败等细节全部只进日志窗口, 由 `RequestLogStorage` 保存, 上限 500 条+- 菜单面板的 `CodexFetchOutcome` 只暴露有数据, 未登录, 初始化失败三种结果, 而启动失败, 超时, 断连, 解析失败等细节全部只进日志窗口, 由 `RequestLogStorage` 保存, 上限 500 条- 账号有效时 rate limits 和 usage 允许单独失败, 复用同账号旧缓存并标记 stale, UI 显示为半透明, 无缓存则该区域不显示; 账号变化时整体丢弃缓存避免串号- 各 Settings 类把读取类错误与操作类错误分开存储, 定时 refresh 不能抹掉用户操作或校验的结论, 参见 `CodexHookSettings` 与 `KeepAliveController`- Hook 子进程任何失败都静默退出, 优先保证不拖慢 Codex@@ -151,9 +157,9 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev## UI 与窗口约定- 菜单栏按钮左键切换主面板; 右键或 Control+点击打开上下文菜单; `⌘,` 打开自定义设置窗口, 菜单面板打开时 `⌘L` 打开日志窗口; 默认全局快捷键 `⌘⇧W` 由 `GlobalHotKeySettings` 与 `GlobalHotKeyController` 管理-- 主面板是锚定 status item 的 `NSPopover` 弹窗, 锚点不可信时回退到 `FallbackPanelController` 提供的屏幕顶部居中 `NSPanel` 面板, 处理快捷键; 屏幕选择和焦点时要保留这两个分支+- 主面板是锚定 status item 的 `NSPopover` 弹窗, 锚点不可信时回退到 `FallbackPanelController` 提供的屏幕顶部居中 `NSPanel` 面板, 处理快捷键, 屏幕选择和焦点时要保留这两个分支- 关闭逻辑统一由 `MenuSurfaceDismissMonitor` 管理, 淡出由 `MenuSurfaceFadeCoordinator` 负责-- 侧边详情面板 (热力图详情; 重置次数) 是主面板的 borderless nonactivating child panel, 公共能力集中在 `Controllers/SidePanelSupport.swift` 里, 含 `SidePanelContentHost` `SidePanelDrawerAnimator` panel 工厂和定位夹紧; 新增侧边面板优先复用, 不要另起一套+- 侧边详情面板 (热力图详情, 重置次数) 是主面板的 borderless nonactivating child panel, 公共能力集中在 `Controllers/SidePanelSupport.swift` 里, 含 `SidePanelContentHost` `SidePanelDrawerAnimator` panel 工厂和定位夹紧; 新增侧边面板优先复用, 不要另起一套- 设置窗口 (通用/高级/关于三页) 和日志窗口复用 `HostingWindowController` 的行为, 可以成为 key window, 但不应成为 main window- 视觉风格统一走 `Views/Shared/LiquidGlassStyle.swift` 这一套, 避免引入与系统菜单栏工具不一致的重装饰 UI@@ -167,19 +173,19 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev## 隐私与数据边界-改动涉及网络; 日志或同步时必须遵守+改动涉及网络, 日志或同步时必须遵守-- App 只有四类出网行为, 分别是本机 app-server stdio 通信 (不算网络); 重置机会过期时间只读查询; Sparkle 更新; 用户显式开启后的 CloudKit 同步, 新增网络请求需要非常明确的理由+- App 只有四类出网行为, 分别是本机 app-server stdio 通信 (不算网络), 重置机会过期时间只读查询, Sparkle 更新, 用户显式开启后的 CloudKit 同步, 新增网络请求需要非常明确的理由- 只读查询打到 `https://chatgpt.com/backend-api/wham/rate-limit-reset-credits` 这一个地址, 也是全仓库唯一的 `URLSession` 调用点, 位于 `CodexResetCreditsService` 内; Sparkle 更新走 `https://codexbar.zabrian.app/appcast.xml` 这个 feed- 不展示 app-server stderr; 不展示或记录 Codex OAuth token 与 `auth.json` 内容; 不把原始敏感 RPC 响应写进文档-- CloudKit 只同步去掉 `sessionIds` 与 `turnIds` 的 daily 聚合, 不同步原始 Hook events; 账号; 额度或 Token 用量+- CloudKit 只同步去掉 `sessionIds` 与 `turnIds` 的 daily 聚合, 不同步原始 Hook events, 账号, 额度或 Token 用量## 代码修改原则- 优先贴合现有文件结构和类型职责, 不为小改动新建抽象-- 改 shared controller; shared service; 模型解析或持久化 key 时, 要考虑旧数据和降级路径; 用户设置要保持默认值; 持久化 key 和旧版本迁移兼容-- **任何兼容性问题都必须主动询问用户, 不要自行拍板**; 只要改动会影响新旧共存就适用, 不限于旧数据迁移或丢弃; 持久化 key 改名或改结构; 老版本升上来的降级路径; 最低系统版本与 API 可用性取舍; 云端记录格式变更; 先说清影响面和几种做法的代价, 等用户选定再动手-- 处理窗口; 菜单; 快捷键; App 激活或事件监听时, 特别注意 `LSUIElement` 应用特有的焦点行为-- 注释保持克制, 只解释非显然的生命周期; 焦点; actor 或系统 API 约束; 现有注释多为解释为什么的类型, 沿用同样风格-- 改动涉及菜单面板; 窗口焦点; Hook; 同步; 通知或防休眠时, 构建通过之外还要说明应手动覆盖的交互场景; 防休眠额外要验证 App 包内 helper 与 plist 位置; 签名; 首次系统授权; 运行/等待切换和异常退出后的恢复-- 不要把发布产物; DerivedData; 临时 DMG; 签名文件或个人凭据提交进仓库+- 改 shared controller, shared service, 模型解析或持久化 key 时, 要考虑旧数据和降级路径; 用户设置要保持默认值; 持久化 key 和旧版本迁移兼容+- **任何兼容性问题都必须主动询问用户, 不要自行拍板**; 只要改动会影响新旧共存就适用, 不限于旧数据迁移或丢弃, 持久化 key 改名或改结构, 老版本升上来的降级路径, 最低系统版本与 API 可用性取舍, 云端记录格式变更; 先说清影响面和几种做法的代价, 等用户选定再动手+- 处理窗口, 菜单, 快捷键, App 激活或事件监听时, 特别注意 `LSUIElement` 应用特有的焦点行为+- 注释保持克制, 只解释非显然的生命周期, 焦点, actor 或系统 API 约束; 现有注释多为解释为什么的类型, 沿用同样风格+- 改动涉及菜单面板, 窗口焦点, Hook, 同步, 通知或防休眠时, 构建通过之外还要说明应手动覆盖的交互场景; 防休眠额外要验证 App 包内 helper 与 plist 位置, 签名, 首次系统授权, 运行/等待切换和异常退出后的恢复+- 不要把发布产物, DerivedData, 临时 DMG, 签名文件或个人凭据提交进仓库diff --git a/CodexBar.xcodeproj/project.pbxproj b/CodexBar.xcodeproj/project.pbxprojindex 8c738cb..ce7a156 100644--- a/CodexBar.xcodeproj/project.pbxproj+++ b/CodexBar.xcodeproj/project.pbxproj@@ -424,7 +424,7 @@"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";CODE_SIGN_STYLE = Automatic;COMBINE_HIDPI_IMAGES = YES;- CURRENT_PROJECT_VERSION = 57;+ CURRENT_PROJECT_VERSION = 58;DEAD_CODE_STRIPPING = YES;DEVELOPMENT_TEAM = 4KJ362VJW5;ENABLE_APP_INTENTS_METADATA_GENERATION = NO;@@ -441,7 +441,7 @@"$(inherited)","@executable_path/../Frameworks",);- MARKETING_VERSION = 3.5.3;+ MARKETING_VERSION = 3.5.4;PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar.debug;PRODUCT_NAME = "$(TARGET_NAME)";REGISTER_APP_GROUPS = YES;@@ -464,7 +464,7 @@"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";CODE_SIGN_STYLE = Automatic;COMBINE_HIDPI_IMAGES = YES;- CURRENT_PROJECT_VERSION = 57;+ CURRENT_PROJECT_VERSION = 58;DEAD_CODE_STRIPPING = YES;DEVELOPMENT_TEAM = 4KJ362VJW5;ENABLE_APP_INTENTS_METADATA_GENERATION = NO;@@ -481,7 +481,7 @@"$(inherited)","@executable_path/../Frameworks",);- MARKETING_VERSION = 3.5.3;+ MARKETING_VERSION = 3.5.4;PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar;PRODUCT_NAME = "$(TARGET_NAME)";PROVISIONING_PROFILE_SPECIFIER = "";diff --git a/CodexBar/Controllers/StatusItemController.swift b/CodexBar/Controllers/StatusItemController.swiftindex bdfbc31..341a024 100644--- a/CodexBar/Controllers/StatusItemController.swift+++ b/CodexBar/Controllers/StatusItemController.swift@@ -199,11 +199,9 @@ private final class StatusItemController: NSObject, NSMenuDelegate {super.init()}- /// 无状态点; 额度条和符号着色时使用模板渲染, 由系统按菜单栏外观着色- /// keepAliveFraction: 0 为常态, 1 为阻止休眠态, 中间值是过渡帧+ /// 无状态点和额度条时使用模板渲染, 由系统按菜单栏外观着色private static func makeStatusImage(_ symbolName: String,- keepAliveFraction: CGFloat,indicatorTint: NSColor?,indicatorVisibility: CGFloat = 1,progress: StatusIconProgress?,@@ -213,37 +211,13 @@ private final class StatusItemController: NSObject, NSMenuDelegate {return nil}- let keepAliveFraction = clampedVisibility(keepAliveFraction)- let symbolAlpha = interpolated(- from: 1,- to: Metrics.keepAliveActiveSymbolAlpha,- progress: keepAliveFraction- )- // fraction 大于 0 就要自行着色, 与具体色值无关- let usesTemplateRendering = indicatorTint == nil && progress == nil && keepAliveFraction <= 0- let staleAlpha = progress?.isStale == true ? Metrics.staleIconAlpha : 1+ let usesTemplateRendering = indicatorTint == nil && progress == nillet statusImage = NSImage(size: Metrics.progressStatusImageSize, flipped: false) { _ in- // 两端用动态色以跟随菜单栏外观, 只有过渡帧需要混成静态色- // 三种情况都必须在 handler 内求值: blended 会把 labelColor 与 systemRed- // 按 App 当前外观冻结, 而不是菜单栏外观- let tint: NSColor = switch keepAliveFraction {- case ...0:- usesTemplateRendering ? .black : .labelColor- case 1...:- Metrics.keepAliveActiveSymbolColor- default:- Self.blendedColor(- .labelColor,- Metrics.keepAliveActiveSymbolColor,- progress: keepAliveFraction- )- }Self.drawStatusSymbol(symbolImage,in: Metrics.progressStatusSymbolRect,- tint: tint,- // 两个来源相乘: stale 时在符号自身透明度基础上再淡一档- alpha: symbolAlpha * staleAlpha+ tint: usesTemplateRendering ? .black : .labelColor,+ alpha: progress?.isStale == true ? Metrics.staleIconAlpha : 1)if let progress {Self.drawProgress(@@ -362,18 +336,6 @@ private final class StatusItemController: NSObject, NSMenuDelegate {min(max(value, 0), 1)}- private static func visibility(_ isVisible: Bool) -> CGFloat {- isVisible ? 1 : 0- }-- private static func interpolated(- from source: CGFloat,- to destination: CGFloat,- progress: CGFloat- ) -> CGFloat {- source + (destination - source) * progress- }-/// 色彩空间转换失败时 blended 返回 nil, 统一退到较近的一端private static func blendedColor(_ source: NSColor,@@ -391,7 +353,9 @@ private final class StatusItemController: NSObject, NSMenuDelegate {to destination: Bool,progress: CGFloat) -> CGFloat {- interpolated(from: visibility(source), to: visibility(destination), progress: progress)+ let start: CGFloat = source ? 1 : 0+ let end: CGFloat = destination ? 1 : 0+ return start + (end - start) * progress}private static func easedVisibility(_ value: CGFloat) -> CGFloat {@@ -403,7 +367,6 @@ private final class StatusItemController: NSObject, NSMenuDelegate {let usesErrorImage: Boollet progress: StatusIconProgress?let activity: CodexActivitySnapshot- let isPreventingSleep: Boolvar symbolName: String {usesErrorImage ? Metrics.errorStatusSymbolName : Metrics.normalStatusSymbolName@@ -424,12 +387,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {/// 只包含影响图像像素的字段; tooltip 文本变化不应触发重绘var renderState: StatusIconRenderState {- StatusIconRenderState(- symbolName: symbolName,- indicator: indicator,- progress: progress,- isPreventingSleep: isPreventingSleep- )+ StatusIconRenderState(symbolName: symbolName, indicator: indicator, progress: progress)}var hasLiveDuration: Bool {@@ -495,7 +453,6 @@ private final class StatusItemController: NSObject, NSMenuDelegate {let symbolName: Stringlet indicator: ActivityIndicator?let progress: StatusIconProgress?- let isPreventingSleep: Bool}private enum ActivityIndicator: Equatable {@@ -600,6 +557,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {mainPanelSettings: mainPanelSettings,activityMonitor: activityMonitor,syncSettings: syncSettings,+ keepAliveController: keepAliveController,menuSurfaceVisibility: menuSurfaceVisibility,activityCenterPresentationState: activityCenterPresentationState,onUsageHeatmapHoverChange: { [weak self] context in@@ -661,14 +619,11 @@ private final class StatusItemController: NSObject, NSMenuDelegate {menuBarQuotaSettings.$selection,activityMonitor.$snapshot)- .combineLatest(keepAliveController.isActivelyPreventingSleepPublisher)- .map { base, isPreventingSleep in- let (loadState, snapshot, selection, activity) = base- return StatusIconState(+ .map { loadState, snapshot, selection, activity in+ StatusIconState(usesErrorImage: loadState.isError || snapshot?.hasTrustedData == false,progress: StatusIconProgress(snapshot: snapshot, selection: selection),- activity: snapshot == nil ? .empty : activity,- isPreventingSleep: isPreventingSleep+ activity: snapshot == nil ? .empty : activity)}.removeDuplicates()@@ -799,8 +754,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {statusIconAnimationTask?.cancel()let progressVisibilityChanged = (previousState.progress == nil) != (state.progress == nil)- let symbolTintChanged = previousState.isPreventingSleep != state.isPreventingSleep- if previousState.indicator != state.indicator || progressVisibilityChanged || symbolTintChanged {+ if previousState.indicator != state.indicator || progressVisibilityChanged {animateStatusImage(from: previousState, to: state)return}@@ -811,7 +765,6 @@ private final class StatusItemController: NSObject, NSMenuDelegate {private func renderStatusImage(_ state: StatusIconState) {statusItem.button?.image = Self.makeStatusImage(state.symbolName,- keepAliveFraction: Self.visibility(state.isPreventingSleep),indicatorTint: state.indicator?.color,progress: state.progress)@@ -832,11 +785,6 @@ private final class StatusItemController: NSObject, NSMenuDelegate {let easedProgress = Self.easedVisibility(rawProgress)statusItem.button?.image = Self.makeStatusImage(finalState.symbolName,- keepAliveFraction: Self.transitionValue(- from: previousState.isPreventingSleep,- to: finalState.isPreventingSleep,- progress: easedProgress- ),indicatorTint: Self.interpolatedIndicatorTint(from: previousState.indicator,to: finalState.indicator,@@ -1403,11 +1351,6 @@ private final class StatusItemController: NSObject, NSMenuDelegate {private enum Metrics {static let normalStatusSymbolName = "person.fill.checkmark"static let errorStatusSymbolName = "person.fill.xmark"- /// 正在阻止系统休眠时的符号颜色; 动态色会跟随菜单栏外观调整- static let keepAliveActiveSymbolColor = NSColor.systemRed- /// 让红色透出一点菜单栏底色, 比满色红柔和- /// 用真实 alpha 而不是调淡的固定色: 深浅菜单栏下各自融进底色- static let keepAliveActiveSymbolAlpha: CGFloat = 0.75static let fadeInDuration: TimeInterval = 0.24static let fadeOutDuration: TimeInterval = 0.18static let auxiliaryWindowKeyFocusRestoreDelayMilliseconds: UInt64 = 120diff --git a/CodexBar/Services/KeepAlive/KeepAliveController.swift b/CodexBar/Services/KeepAlive/KeepAliveController.swiftindex ff62971..fb23e93 100644--- a/CodexBar/Services/KeepAlive/KeepAliveController.swift+++ b/CodexBar/Services/KeepAlive/KeepAliveController.swift@@ -27,13 +27,8 @@ final class KeepAliveController: ObservableObject {/// 用户开关仍开着, 且 helper 已经真的把休眠关掉/// isPreventingSleep 在稳态下已隐含 isEnabled (shouldDisableSleep 要求它),/// 叠这一层是为了关开关到 helper 回调之间的异步空窗: 用户意图先落地- var isActivelyPreventingSleepPublisher: AnyPublisher<Bool, Never> {- Publishers.CombineLatest($isEnabled, $isPreventingSleep)- .map { isEnabled, isPreventingSleep in- isEnabled && isPreventingSleep- }- .removeDuplicates()- .eraseToAnyPublisher()+ var isActivelyPreventingSleep: Bool {+ isEnabled && isPreventingSleep}private let activityMonitor: CodexActivityMonitor@@ -317,6 +312,19 @@ final class KeepAliveController: ObservableObject {}}+ /// @Published 在 willSet 无条件发信号, 不比较新旧值+ /// refreshHelperStatus 每次 App 激活跑, releaseSleepPrevention 每条活动快照都会经过+ /// 同值赋值会让菜单面板和设置页反复空转, 所有 @Published 的写入都走这里+ private func assign<Value: Equatable>(+ _ value: Value,+ to keyPath: ReferenceWritableKeyPath<KeepAliveController, Value>+ ) {+ guard self[keyPath: keyPath] != value else {+ return+ }+ self[keyPath: keyPath] = value+ }+private static func isTransientHelperRegistrationError(_ error: Error) -> Bool {let error = error as NSErrorreturn error.domain == SMAppServiceErrorDomain@@ -324,11 +332,11 @@ final class KeepAliveController: ObservableObject {}private func refreshHelperStatus() {- helperStatus = HelperStatus(Self.helperService.status)+ assign(HelperStatus(Self.helperService.status), to: \.helperStatus)if helperStatus == .enabled {// 注册已正常, 只撤回注册类抱怨// 操作类结果 (例如重试耗尽) 必须留到下一次操作有结论为止- registrationErrorMessage = nil+ assign(nil, to: \.registrationErrorMessage)} else if helperStatus != .requiresApproval {releaseSleepPrevention()resetMaximumDurationState()@@ -486,7 +494,7 @@ final class KeepAliveController: ObservableObject {private func resetMaximumDurationState() {cancelMaximumDurationTask()maximumDurationStartedAt = nil- hasReachedMaximumDuration = false+ assign(false, to: \.hasReachedMaximumDuration)}private func cancelMaximumDurationTask() {@@ -557,7 +565,7 @@ final class KeepAliveController: ObservableObject {/// 且没有任何后续路径会释放它; 仍需要防休眠时由重试经 applySleepDisabled(true) 重建private func releaseSleepPrevention() {_ = systemSleepService.endPreventingIdleSleep()- isPreventingSleep = false+ assign(false, to: \.isPreventingSleep)}private func cancelRetryTask() {diff --git a/CodexBar/Views/Menu/CodexActivityCard.swift b/CodexBar/Views/Menu/CodexActivityCard.swiftindex ffe6f7a..6b49513 100644--- a/CodexBar/Views/Menu/CodexActivityCard.swift+++ b/CodexBar/Views/Menu/CodexActivityCard.swift@@ -2,9 +2,11 @@ import SwiftUI/// Hook 开启时常驻的固定高度活动摘要, 使用菜单面板共享的逐秒时间/// 在卡片内部观察 activityMonitor 与逐秒时间, 让 1Hz 失效范围只覆盖本卡片而不是整个菜单树+/// keepAliveController 同理, 它的 helperStatus 等字段与菜单树无关却会无条件发信号struct CodexActivityCard: View {@ObservedObject var activityMonitor: CodexActivityMonitor@ObservedObject var presentationState: CodexActivityCenterPresentationState+ @ObservedObject var keepAliveController: KeepAliveControllerlet showsUnavailableState: Boollet onTaskCenterTap: (ScreenFrameProvider) -> Void@State private var frameProvider = ScreenFrameProvider()@@ -22,6 +24,12 @@ struct CodexActivityCard: View {presentationState.isPresented}+ /// 额度数据不可用时卡片整体退到"暂无数据", 徽标属于活动信息, 必须跟着一起收+ /// 否则会出现"暂无数据"配上防休眠徽标的自相矛盾画面+ private var showsKeepAliveBadge: Bool {+ keepAliveController.isActivelyPreventingSleep && !showsUnavailableState+ }+var body: some View {Group {if snapshot.hasTaskCenterContent {@@ -68,16 +76,29 @@ struct CodexActivityCard: View {Spacer(minLength: 0)+ if showsKeepAliveBadge {+ // 防休眠只在任务运行期间生效, 所以状态挂在活动卡片上而不是单独占一行+ Image(systemName: "cup.and.saucer.fill")+ .font(.system(size: 11, weight: .semibold))+ .foregroundStyle(Color.teal)+ .transition(.opacity)+ }+if content.otherTaskCount > 0 {Text("+\(content.otherTaskCount)").font(.caption2.monospacedDigit().weight(.semibold)).foregroundStyle(.secondary)+ .numericRollTransition(value: Double(content.otherTaskCount)).padding(.horizontal, 6).padding(.vertical, 3).background(.secondary.opacity(0.12), in: Capsule())+ .transition(.opacity).help("另有 \(content.otherTaskCount) 个任务")}}+ .animation(.codexStatus, value: showsKeepAliveBadge)+ // 任务数变化会让 +N 增删, 咖啡杯跟着横移; 两者一起纳入动画上下文才不会跳+ .animation(.codexStatus, value: content.otherTaskCount).padding(.horizontal, MenuMetrics.panelPadding).frame(maxWidth: .infinity, minHeight: Metrics.height, maxHeight: Metrics.height).liquidGlassSurface(cornerRadius: MenuMetrics.panelCornerRadius)diff --git a/CodexBar/Views/Menu/CodexStatusMenuView.swift b/CodexBar/Views/Menu/CodexStatusMenuView.swiftindex 651833b..4880f13 100644--- a/CodexBar/Views/Menu/CodexStatusMenuView.swift+++ b/CodexBar/Views/Menu/CodexStatusMenuView.swift@@ -18,6 +18,8 @@ struct CodexStatusMenuView: View {// 活动状态与逐秒时间只被活动卡片消费, 由卡片自行观察, 避免 1Hz tick 让整个菜单树每秒重算let activityMonitor: CodexActivityMonitor@ObservedObject var syncSettings: WorkflowSyncSettings+ // 同 activityMonitor, 交给活动卡片自行观察, 不让 helper 状态变化重算整个菜单树+ let keepAliveController: KeepAliveController@ObservedObject var menuSurfaceVisibility: MenuSurfaceVisibilityStatelet activityCenterPresentationState: CodexActivityCenterPresentationStatelet onUsageHeatmapHoverChange: (UsageHeatmapHoverContext?) -> Void@@ -80,6 +82,7 @@ private extension CodexStatusMenuView {CodexActivityCard(activityMonitor: activityMonitor,presentationState: activityCenterPresentationState,+ keepAliveController: keepAliveController,showsUnavailableState: viewModel.snapshot == nil,onTaskCenterTap: { anchorProvider inonActivityCenterTap(diff --git a/README.md b/README.mdindex ac61551..d3b5b8a 100644--- a/README.md+++ b/README.md@@ -4,7 +4,7 @@# CodexBar-**在 macOS 菜单栏一眼看清 Codex 的账号; 额度; 用量与实时任务**+**在 macOS 菜单栏一眼看清 Codex 相关信息**[](https://www.apple.com/macos/)[](https://swift.org)@@ -20,17 +20,17 @@----CodexBar 把 Codex 的运行状态收进菜单栏: 剩余额度; 下次重置时间; 当日 Token 用量, 以及当前任务是在运行还是在等待批准+CodexBar 把 Codex 的运行状态收进菜单栏: 剩余额度, 下次重置时间, 当日 Token 用量, 以及当前任务是在运行还是在等待批准应用以 `LSUIElement` 方式运行, 没有 Dock 图标; 数据全部在本机采集与聚合, 对外通信仅有四项, 详见[隐私](#隐私)## 特性-其中实时任务; 工作流统计与防休眠依赖 CodexBar Hook, 开启方式见[关于 Hook](#关于-hook)+其中实时任务, 工作流统计与防休眠依赖 CodexBar Hook, 开启方式见[关于 Hook](#关于-hook)### 额度与用量-- 分时间窗口展示剩余额度; 重置时间与可用的手动重置次数+- 分时间窗口展示剩余额度, 重置时间与可用的手动重置次数- 菜单栏可常驻显示主要或次要窗口的额度百分比, 无需展开面板- 30 周日历热力图呈现每日 Token 用量, 点击任意一格展开当天明细- 账号有效时额度与用量允许单独失败, 失败项沿用同账号缓存并标记为陈旧@@ -38,31 +38,32 @@ CodexBar 把 Codex 的运行状态收进菜单栏: 剩余额度; 下次重置时### 实时任务- 开启 CodexBar Hook 后, 菜单栏图标随任务状态实时变化-- 任务中心区分运行中; 等待批准; 最近完成; 已终止四种状态+- 任务中心区分运行中, 等待批准, 最近完成, 已终止四种状态- 状态同时取自 Hook 事件流与 `~/.codex/sessions` 下的 rollout 记录, 前者覆盖工具调用与批准请求, 后者补齐对话轮次的起止### 工作流统计-- 按天聚合会话; 对话轮次; 工具调用; 权限请求; 上下文压缩; 子 Agent 等指标+- 按天聚合会话, 对话轮次, 工具调用, 权限请求, 上下文压缩, 子 Agent 等指标- 原始事件与每日聚合保留 210 天, 可按日期区间从原始事件重新统计- 可选开启 iCloud 同步, 汇总多台 Mac 的数据### 防休眠- 仅在任务运行期间阻止空闲休眠与合盖休眠, 任务结束即恢复-- 最长时长可选 1; 2; 4; 8; 12; 24 小时或无限制, 默认 12 小时-- 等待批准; 任务结束与时长到期都会还原系统原有设置, 交由 macOS 重新判断+- 最长时长可选 1, 2, 4, 8, 12, 24 小时或无限制, 默认 12 小时+- 等待批准, 任务结束与时长到期都会还原系统原有设置, 交由 macOS 重新判断+- 生效期间主面板的任务卡片右侧显示一个咖啡杯标记### 通知与提醒-- 五类本地通知: 额度告急; 额度重置; 任务等待批准; 长任务完成; 重置机会即将过期+- 五类本地通知: 额度告急, 额度重置, 任务等待批准, 长任务完成, 重置机会即将过期- 告急百分比与长任务时长阈值可调, 每类通知的音效独立可选- 阈值穿越带去重判定, 同一事件不会重复提醒; 任务状态变化另有触觉反馈- 可直接读写 Codex CLI 自身的通知配置, 无需手动编辑 `config.toml`### 系统集成-- 全局快捷键唤起 (默认 `⌘⇧W`, 可自定义); 开机自启; Sparkle 自动更新+- 全局快捷键唤起 (默认 `⌘⇧W`, 可自定义), 开机自启, Sparkle 自动更新- 内置日志窗口保留最近 500 条请求记录, 连接失败与解析异常均可追溯- 界面风格贴近系统菜单栏工具, 不作额外装饰@@ -96,7 +97,7 @@ brew install --cask bob-zebedy/tap/codexbar### 关于 Hook-实时任务; 工作流统计与防休眠都依赖 CodexBar Hook, 在设置中开启即可写入 `~/.codex/hooks.json`+实时任务, 工作流统计与防休眠都依赖 CodexBar Hook, 在设置中开启即可写入 `~/.codex/hooks.json`> [!NOTE]> 写入只追加 CodexBar 自身的 handler, 关闭时也只移除这一条; 已有的 Hook 与其他工具注册的 Hook 原样保留@@ -119,7 +120,7 @@ CodexBar 的对外通信只有以下四项, 其中真正经过网络的是后三| Sparkle 更新检查 | 拉取 appcast || CloudKit 同步 | 仅在显式开启后进行 |-账号; 额度; Token 用量与原始 Hook 事件都不会离开本机; 跨设备同步只上传去掉会话与轮次标识的每日聚合; Codex 的 OAuth token 与 `auth.json` 内容既不展示也不记录+账号, 额度, Token 用量与原始 Hook 事件都不会离开本机; 跨设备同步只上传去掉会话与轮次标识的每日聚合; Codex 的 OAuth token 与 `auth.json` 内容既不展示也不记录## 实现@@ -186,11 +187,11 @@ xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/pl格式化与静态检查使用 `swiftformat` 和 `swiftlint`, 配置位于仓库根目录-`Scripts/` 下是归档; 公证; DMG 打包与 appcast 签名等发布脚本, 它们需要 Developer ID 凭据, 不适合用于日常验证+`Scripts/` 下是归档, 公证, DMG 打包与 appcast 签名等发布脚本, 它们需要 Developer ID 凭据, 不适合用于日常验证## 反馈-Bug; 功能建议与使用问题都欢迎通过 [Issues](https://github.com/bob-zebedy/CodexBar/issues) 反馈, 仓库已备好对应模板+Bug, 功能建议与使用问题都欢迎通过 [Issues](https://github.com/bob-zebedy/CodexBar/issues) 反馈, 仓库已备好对应模板## 许可证diff --git a/appcast.xml b/appcast.xmlindex 76075ae..a55a849 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 3.5.4</title>+ <sparkle:version>58</sparkle:version>+ <sparkle:shortVersionString>3.5.4</sparkle:shortVersionString>+ <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>+ <sparkle:releaseNotesLink>https://codexbar.zabrian.app/notes#3.5.4</sparkle:releaseNotesLink>+ <pubDate>Sun, 26 Jul 2026 21:50:11 +0800</pubDate>+ <enclosure url="https://codexbar.zabrian.app/download/CodexBar-v3.5.4.dmg" sparkle:edSignature="rd23OmvFIlTEZT+SA7mZ05uw8v24PmYixMFsiRBqlEFN3i9HFM42cWg4/IzfscYwNHl1OG0hQCVdksltgIYgBw==" length="5864512" type="application/octet-stream"/>+ </item><item><title>CodexBar.app 3.5.3</title><sparkle:version>57</sparkle:version>