Skip to content

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

feat: 防休眠状态改由活动卡片呈现

Bobf52f1d984f51
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 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.md
index 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.0
Xcode 工程有两个 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/pl
swiftformat .
# 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.pbxproj
index 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.swift
index 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 == nil
let 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: Bool
let progress: StatusIconProgress?
let activity: CodexActivitySnapshot
- let isPreventingSleep: Bool
var 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: String
let 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.75
static let fadeInDuration: TimeInterval = 0.24
static let fadeOutDuration: TimeInterval = 0.18
static let auxiliaryWindowKeyFocusRestoreDelayMilliseconds: UInt64 = 120
diff --git a/CodexBar/Services/KeepAlive/KeepAliveController.swift b/CodexBar/Services/KeepAlive/KeepAliveController.swift
index 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 NSError
return 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.swift
index 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: KeepAliveController
let showsUnavailableState: Bool
let 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.swift
index 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: MenuSurfaceVisibilityState
let activityCenterPresentationState: CodexActivityCenterPresentationState
let onUsageHeatmapHoverChange: (UsageHeatmapHoverContext?) -> Void
@@ -80,6 +82,7 @@ private extension CodexStatusMenuView {
CodexActivityCard(
activityMonitor: activityMonitor,
presentationState: activityCenterPresentationState,
+ keepAliveController: keepAliveController,
showsUnavailableState: viewModel.snapshot == nil,
onTaskCenterTap: { anchorProvider in
onActivityCenterTap(
diff --git a/README.md b/README.md
index ac61551..d3b5b8a 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
# CodexBar
-**在 macOS 菜单栏一眼看清 Codex 的账号; 额度; 用量与实时任务**
+**在 macOS 菜单栏一眼看清 Codex 相关信息**
[![macOS](https://img.shields.io/badge/macOS-15.0+-000000?logo=apple&logoColor=white)](https://www.apple.com/macos/)
[![Swift](https://img.shields.io/badge/Swift-6-F05138?logo=swift&logoColor=white)](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.xml
index 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>