CodexBar 是一个 macOS 菜单栏应用,用于查看本机 Codex 账号状态、额度、Token 用量、详细统计信息
Swift appkitcodexcodex-clideveloper-toolsmacosmacos-appmenu-bar-appopenai-codexproductivityswiftswiftuiusage-tracker
feat: 菜单栏图标区分防休眠状态并发布 3.5.3
Bob78e87ab153bf
diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.mdindex 582d9f4..9cd78c7 100644--- a/.github/ISSUE_TEMPLATE/bug.md+++ b/.github/ISSUE_TEMPLATE/bug.md@@ -7,7 +7,7 @@ assignees: ''---**问题描述**-请清晰、简洁地描述遇到的问题+请清晰, 简洁地描述遇到的问题**复现步骤**请按顺序列出复现该问题的步骤:@@ -32,4 +32,4 @@ assignees: ''- Codex App 版本:**补充信息**-请添加其他有助于定位问题的上下文, 例如日志窗口中的相关记录、问题是否稳定复现、最近是否升级过 CodexBar 或 Codex+请添加其他有助于定位问题的上下文, 例如日志窗口中的相关记录, 问题是否稳定复现, 最近是否升级过 CodexBar 或 Codexdiff --git a/.github/ISSUE_TEMPLATE/feature.md b/.github/ISSUE_TEMPLATE/feature.mdindex 751934c..295b64a 100644--- a/.github/ISSUE_TEMPLATE/feature.md+++ b/.github/ISSUE_TEMPLATE/feature.md@@ -1,13 +1,13 @@---name: 功能请求-about: 提出 CodexBar 的新功能、改进建议或体验优化+about: 提出 CodexBar 的新功能, 改进建议或体验优化title: '[Feature] 'labels: enhancementassignees: ''---**需求描述**-请清晰、简洁地描述你希望新增或改进的功能+请清晰, 简洁地描述你希望新增或改进的功能**使用场景**请说明这个功能会在什么场景下使用, 以及希望它解决什么问题@@ -19,4 +19,4 @@ assignees: ''如果你考虑过其他方案或临时解决办法, 请在这里说明**补充信息**-请添加其他有助于理解需求的上下文, 例如截图、录屏、相关配置、相似产品参考或具体工作流+请添加其他有助于理解需求的上下文, 例如截图, 录屏, 相关配置, 相似产品参考或具体工作流diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.mdindex 6b55b93..6402c85 100644--- a/.github/ISSUE_TEMPLATE/question.md+++ b/.github/ISSUE_TEMPLATE/question.md@@ -1,16 +1,16 @@---name: 一般问题-about: 询问 CodexBar 的使用方式、配置、兼容性或排查思路+about: 询问 CodexBar 的使用方式, 配置, 兼容性或排查思路title: '[Question] 'labels: questionassignees: ''---**问题**-请清晰、简洁地描述你想咨询的问题+请清晰, 简洁地描述你想咨询的问题**相关背景**-请说明你正在做什么、遇到了什么现象, 以及你已经尝试过哪些操作+请说明你正在做什么, 遇到了什么现象, 以及你已经尝试过哪些操作**截图或录屏**如果适用, 请添加截图或录屏来帮助说明问题@@ -24,4 +24,4 @@ assignees: ''- Codex App 版本:**补充信息**-请添加其他有助于回答问题的上下文, 例如截图、日志窗口中的相关记录、Codex Hook 或跨设备同步是否开启。+请添加其他有助于回答问题的上下文, 例如截图, 日志窗口中的相关记录, Codex Hook 或跨设备同步是否开启diff --git a/.swiftlint.yml b/.swiftlint.ymlindex 4174cd9..d9a97e0 100644--- a/.swiftlint.yml+++ b/.swiftlint.yml@@ -10,8 +10,8 @@ line_length:ignores_interpolated_strings: truefile_length:- warning: 900- error: 1200+ warning: 1200+ error: 1500ignore_comment_only_lines: truetype_body_length:diff --git a/AGENTS.md b/AGENTS.mddeleted file mode 100644index 6867d2c..0000000--- a/AGENTS.md+++ /dev/null@@ -1,129 +0,0 @@-# AGENTS.md--本文件面向在本仓库工作的编码代理。优先遵循这里的项目约定;需要更细背景时再阅读 `Docs/` 下的专题文档。--## 项目概览--CodexBar 是一个 macOS 15+ 菜单栏应用,使用 Swift 6、SwiftUI + AppKit + MVVM。应用通过本机 Codex app-server 读取账号、额度和 token 用量,通过可选 Codex Hook 记录本机 Codex 工作流事件,并在菜单栏面板、设置窗口和日志窗口中展示状态。--工程包含主 App target `CodexBar` 和随 App 嵌入的命令行 helper target `CodexBarHelper`。当前没有独立测试 target 或 `*Tests*` 目录。--## 重要边界--- 应用是 `LSUIElement` 菜单栏 App,不显示 Dock 图标,也不依赖主窗口。-- 最低系统版本是 macOS 15.0。-- App Sandbox 关闭,因为需要启动本机 `codex`、读取用户 Codex 登录状态,并写入用户级 Hook 配置。-- `CodexBarHelper` 只允许已签名的 CodexBar 通过 XPC 请求切换 `/usr/bin/pmset -a disablesleep`,并只在 `/Library/Application Support/CodexBar/` 维护恢复哨兵;不要给 root helper 增加网络、任意命令或其他文件访问能力。-- 除手动重置机会过期时间查询、Sparkle 更新、用户显式开启跨设备同步后的 CloudKit private database 同步外,App 自身不应新增网络请求。-- Codex 账号、额度、token 用量只在本机处理。Hook 工作流统计默认只写本机文件,跨设备同步只上传 daily 聚合数据,不上传原始事件、会话 ID、轮次 ID、请求日志或认证文件。-- 不要回滚或清理与当前任务无关的未提交变更;仓库可能处于脏工作树状态。--## Git 规则--- 不要主动 push。-- 不要回滚或覆盖你没做的未提交改动。-- 提交 Git 时候**禁止**任何改动任何内容,仅对目前代码进行提交即可。-- 提交 message 使用 Conventional Commits 前缀 + 中文标题 + 空行 + 4 空格缩进 bullet body。-- 提交 body 中多条 bullet 必须连续排列,bullet 之间不要空行;使用命令提交时,将完整 body 放在同一个 `-m` 参数或 `git commit -F` 文件中,不要为每条 bullet 单独使用 `-m`。-- 标题格式:`<type>: <中文描述>`,不加句号。-- 常用 type:`feat`、`fix`、`chore`、`refactor`、`docs`。-- 功能、修复、发布类提交必须写 body;简单文档或杂项可只写标题行。--示例:--```text-fix: 修复 Codex 状态刷新-- - 合并设置页 onAppear 和 didBecomeActive 的重复版本探测- - 保留当前运行版本与磁盘安装版本不一致时的更新提示-```--Tag:--- tag 名格式 `v{MARKETING_VERSION}`。-- 使用附注 tag:`git tag -a v{MARKETING_VERSION} -m "Release v{MARKETING_VERSION}"`。--## 目录结构--- `CodexBar/App/`: SwiftUI 入口和 AppDelegate 启动分流。-- `CodexBar/Controllers/`: 菜单栏、菜单面板、侧边详情面板、设置窗口、日志窗口和窗口行为。-- `CodexBar/Models/`: account、quota、usage、workflow、日期网格、快捷键和错误模型。-- `CodexBar/Services/`: app-server、Codex CLI 解析、Codex 版本探测、Hook 设置、工作流统计、同步、日志、登录项和更新服务。-- `CodexBar/Views/`: 菜单面板、设置窗口、日志窗口和共享 Liquid Glass 样式。-- `CodexBar/Resources/`: Info.plist、entitlements、图标和 asset catalog。-- `Shared/`: 主 App 与 root helper XPC 契约。-- `CodexBarHelper/`: 防休眠 root helper 入口和 LaunchDaemon plist。-- `Docs/`: app-server、Codex Hook、跨设备同步和开发文档。-- `Scripts/`: Release 构建、公证、DMG 和 Sparkle appcast 发布脚本。--## 构建与验证--日常编译验证:--```bash-xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/platform=macOS' build-```--也可以直接用 Xcode 打开 `CodexBar.xcodeproj` 运行。--发布相关脚本:--```bash-Scripts/build.sh-Scripts/dmg.sh-Scripts/appcast.sh-```--`Scripts/build.sh` 默认执行 Release archive、导出 Developer ID app、公证、staple 和 Gatekeeper 校验。没有发布凭据或不需要完整发布流程时,不要把它当作普通本地验证命令。--当前没有自动化测试套件。修改后至少跑一次 `xcodebuild ... build`;如果改动涉及菜单面板、窗口焦点、Hook、同步或防休眠逻辑,需要手动说明还应覆盖的交互场景。防休眠还应检查 App 包内 helper/plist 位置、签名、首次系统授权、运行/等待切换和异常退出后的恢复。--## Swift 与并发约定--- 项目使用 Swift 6,`SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`。UI 和 ViewModel 默认按 MainActor 思考。-- 服务共享状态优先使用 `actor` 管理。-- DTO、纯模型、静态工具、日期/格式化辅助、跨 actor 传递类型应根据需要显式标注 `nonisolated` 或保证 `Sendable` 语义清晰。-- 不要用阻塞式 I/O 或长耗时操作卡住 MainActor;从服务层异步返回后再回写 UI 状态。-- 已有防重入和过期结果丢弃逻辑要保留,例如 `RefreshTaskCoordinator` 保护刷新结果只让最新 generation 提交。-- 注释保持克制,只解释非显然的生命周期、焦点、actor 或系统 API 约束。--## UI 与窗口约定--- 菜单栏按钮左键切换主面板;右键或 Control+点击打开上下文菜单。-- `⌘,` 打开自定义设置窗口;菜单面板打开时 `⌘L` 打开日志窗口。-- 默认全局快捷键是 `⌘⇧W`,由 `GlobalHotKeySettings` 和 `GlobalHotKeyController` 管理。-- 主菜单面板可能通过 `NSPopover` 锚定 status item,也可能在锚点不可信时使用 fallback `NSPanel`。处理快捷键、屏幕选择和焦点时要保留这些分支。-- 设置窗口和日志窗口复用 `HostingWindowController` / `AuxiliaryHostingWindow` 行为。它们可以成为 key window,但不应成为 main window。-- 侧边详情面板共享 `SidePanelSupport.swift` 的定位、动画、挂载和 chrome 行为;新增侧边面板能力时优先复用共享支持代码。-- 保持现有 Liquid Glass 视觉风格,避免引入与系统菜单栏工具不一致的重装饰 UI。--## Hook、同步与数据文件--- Hook 子进程入口在 `CodexBarApp.init()` 中最先调用 `WorkflowHookEventRecorder.handleIfRequested()`;Hook 模式要快速读取 stdin 并退出,不进入普通 App 启动流程。-- CodexBar 只追加或移除属于当前 CodexBar 可执行文件的 Hook,不应删除用户已有的其他 Codex Hook。-- 本机 Hook 事件默认写入:--```text-~/Library/Application Support/CodexBar/HookEvents/-```--- 跨设备同步依赖用户开启 Codex Hook 且 iCloud 可用;只同步脱敏 daily 聚合行。同步范围变更时必须同时更新 `Docs/CrossDeviceSync.md`。-- Hook 事件口径、字段或聚合方式变更时必须同步更新 `Docs/CodexHook.md`。--## 文档同步--涉及这些行为时,需要更新对应文档:--- app-server 请求、错误处理或通信合约:`Docs/AppServer.md`-- Hook 注册、事件存储、统计口径:`Docs/CodexHook.md`-- CloudKit 同步范围、冲突处理、隐私边界:`Docs/CrossDeviceSync.md`-- 架构、启动流程、窗口焦点或模块边界:`Docs/DevelopmentGuide.md`-- 用户可见功能、安装或隐私说明:`README.md`--## 代码修改原则--- 优先贴合现有文件结构和类型职责,不为了小改动新建抽象。-- 修改 shared controller、shared service、模型解析或持久化 key 时,要考虑旧数据和降级路径。-- 处理用户设置时保持默认值、持久化 key 和旧版本迁移兼容。-- 处理窗口、菜单、快捷键、App 激活或事件监听时,要特别注意 `LSUIElement` App 的焦点行为。-- 不要把发布产物、DerivedData、临时 DMG、签名文件或个人凭据提交进仓库。diff --git a/CLAUDE.md b/CLAUDE.mdindex 9a38004..b4380d2 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -2,46 +2,66 @@This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.+## 写作风格++本仓库的中文文本 (提交信息; 代码注释; 文档) 统一遵守++- 禁止使用中文标点, 一律使用半角标点+- 行末禁止使用标点+- 行内标点后如果还有文字, 间隔一个英文空格+- 行内代码后尽量不要紧跟标点, 需要断句时补一个词或者使用空格再断+## 项目概述-CodexBar 是一个 macOS 菜单栏应用 (`LSUIElement`, 无 Dock 图标),用于展示本机 Codex 的账号状态、额度、Token 用量和工作流统计。技术栈: Swift 6 + SwiftUI + AppKit + MVVM,唯一外部依赖是 Sparkle (SwiftPM)。最低系统版本 macOS 15.0,App Sandbox 保持关闭(需要启动本机 `codex` 进程并写入用户级 Hook 配置)。+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 配置## 常用命令```bash-# 构建(唯一 scheme 是 CodexBar,无测试 target)+# 日常编译验证 (唯一 scheme 是 CodexBar)xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/platform=macOS' build-# 格式化(配置在 .swiftformat,Swift 6 语言模式、4 空格缩进)+# 格式化: 配置在 .swiftformat, 覆盖整个仓库 (Swift 6 语言模式, 4 空格缩进)swiftformat .-# Lint(配置在 .swiftlint.yml,只检查 CodexBar/ 目录)+# Lint: 配置在 .swiftlint.yml, included 只有 CodexBar/+# 即 Shared/; CodexBarHelper/; Scripts/ 不在 lint 范围内swiftlint-# 发布脚本-Scripts/build.sh # archive + Developer ID 导出 + notarize+# 发布流程 (需要 Developer ID 凭据, 不要当普通本地验证跑)+Scripts/build.sh # Release archive + Developer ID 导出 + notarize + staple + Gatekeeper 校验Scripts/dmg.sh # 打包 DMG-Scripts/appcast.sh # 签名并更新 Sparkle appcast+Scripts/appcast.sh # sign_update 签名并写入 appcast.xml++# 注销 KeepAlive LaunchDaemon; 清理前需先退出所有 CodexBar 实例+# 常用: --dry-run 只显示目标, --check 只验证临时清理 App,+# --release-only / --debug-only 限定范围, --sign-identity 指定签名身份+Scripts/cleanup.swift --help```-本仓库没有测试 target;验证改动依靠构建通过 + 实际运行。+日常调试直接 `open CodexBar.xcodeproj` 用 Xcode 跑 Debug scheme; 注意 Debug 产物用的是 `app.zabrian.codexbar.debug` 这个 bundle ID, 与 Release 安装版可以共存, 排查防休眠问题时要确认自己看的是哪一套 helper-## Git 规则+`Scripts/build.sh` 会先清空 `build/` 目录, 成功后只留最终产物 `.app` 文件; 凭据推荐用 keychain profile, 先跑一次 `xcrun notarytool store-credentials "codexbar-notary" --apple-id "<Apple ID>" --team-id "<Team ID>"` 存好, 之后构建加上 `--notary-profile codexbar-notary`-基本约束:+Debug 与 Release 使用不同 bundle ID, 分别是 `app.zabrian.codexbar.debug` 与 `app.zabrian.codexbar` 两个, helper 相应带 `.debug.helper` 与 `.helper` 后缀, 所以 `CodexBarHelper/` 下有两份 LaunchDaemon plist, `cleanup.swift` 也需要同时处理两套-- 不要主动 push,除非用户明确要求。-- 不要回滚、覆盖或丢弃不是你产生的未提交改动。-- 被要求提交时,**禁止**顺带修改任何文件内容:不做格式化、不做清理、不补文档,只把当前已有改动原样提交。+## Git 规则-Commit message 格式: Conventional Commits 前缀 + 中文标题,需要 body 时空一行后写 4 空格缩进的 bullet。+- 不要主动 push, 除非用户明确要求+- 不要回滚; 覆盖或丢弃不是你产生的未提交改动, 工作树可能是脏的+- 被要求提交时, **禁止**顺带修改任何文件内容: 不格式化; 不清理; 不补文档, 只把当前已有改动原样提交-- 标题格式 `<type>: <中文描述>`,不加句号;常用 type: `feat`、`fix`、`chore`、`refactor`、`docs`。-- 功能、修复、发布类提交必须写 body;简单文档或杂项改动可只写标题行。-- body 中多条 bullet 连续排列,bullet 之间不空行。-- 用命令行提交时,完整 body 放在同一个 `-m` 参数里或用 `git commit -F` 传文件,不要为每条 bullet 单独 `-m`。+Commit message: Conventional Commits 前缀 + 中文标题, 需要 body 时空一行后写 4 空格缩进 bullet-示例:+- 标题写成 `<type>: <中文描述>` 的形式, 不加句号; 常用 type 有 `feat` `fix` `chore` `refactor` `docs`+- 功能; 修复; 发布类提交必须写 body; 简单文档或杂项可只写标题行+- body 中多条 bullet 连续排列, bullet 之间不空行+- 命令行提交时把完整 body 放进同一个 `-m` 参数或改用 `git commit -F` 传文件, 不要为每条 bullet 单独 `-m`+- message 中禁止使用中文标点, 行末禁止使用标点, 行内标点后如果有文字则间隔一个英文空格```textfix: 修复 Codex 状态刷新@@ -50,73 +70,116 @@ fix: 修复 Codex 状态刷新- 保留当前运行版本与磁盘安装版本不一致时的更新提示```-Tag:+Tag 名 `v{MARKETING_VERSION}` 里的版本号从 Xcode build settings 读取, 使用附注 tag `git tag -a v3.x.y -m "Release v3.x.y"`++## 架构++### 启动分流 (关键设计)++`CodexBar/App/CodexBarApp.swift` 的 `init()` 最先调用 `WorkflowHookEventRecorder.handleIfRequested()`++- 带 `--hook-event` 启动 -> **Hook 子进程模式**: 从 stdin 读 JSON payload, 在 `flock` 锁内追加一行 JSONL 后立即 `exit(EXIT_SUCCESS)` 退出, 绝不初始化菜单栏 UI; 写入失败静默吞掉, 不阻断 Codex; Hook handler 超时由 `hookTimeoutSeconds` 定为 5 秒, 等锁预算据此推算为 3 秒, 两者必须一起改+- 普通启动 -> `CodexBarAppDelegate` 创建全部长期对象, 它在 `Controllers/StatusItemController.swift` 内, 再由 `StatusItemController.install()` 装配菜单栏; AppDelegate 是唯一的装配点, 新增服务在这里注入++### 三条数据链路-- tag 名格式 `v{MARKETING_VERSION}`(版本号从 Xcode build settings 读取)。-- 使用附注 tag: `git tag -a v{MARKETING_VERSION} -m "Release v{MARKETING_VERSION}"`。+**链路一: app-server (额度/用量)**-## 架构总览+`CodexStatusService` (actor) -> `CodexCLIResolver` 解析 `codex` 可执行文件, PATH 全局优先, 回退 `/Applications/ChatGPT.app` 或 `Codex.app` 内置 -> 启动 `codex app-server --listen stdio://` -> `AppServerSession` 做 stdio JSON-RPC -> 合成 `CodexQuotaSnapshot` -> `CodexStatusViewModel` 发布给 UI-详细流程(含时序图、错误处理矩阵、UI 尺寸常量)见 `Docs/DevelopmentGuide.md`,这是最权威的参考。协议细节见 `Docs/AppServer.md`(app-server JSON-RPC 合约)、`Docs/CodexHook.md`(Hook 统计口径)、`Docs/CrossDeviceSync.md`(CloudKit 同步链路)。+- 刷新间隔 60 秒, 请求超时 20 秒, 连接最长复用 1 小时, 让后台升级的 codex 二进制有机会生效+- 主要方法有 `initialize` `account/read` `account/rateLimits/read` `account/usage/read` `config/read` `config/batchWrite` `hooks/list`+- `SIGPIPE` 被忽略, app-server 退出后写管道由 write 抛错走重建路径+- stdout 可能混有无关日志行, `AppServerSession` 先用轻量 `RPCIDEnvelope` 匹配 id 再完整解码-### 启动分流(关键设计)+**链路二: Hook 统计 (历史聚合)**-入口 `CodexBar/App/CodexBarApp.swift` 的 `init()` 最先调用 `WorkflowHookEventRecorder.handleIfRequested()`:+Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/events/YYYY-MM-DD.jsonl` 这类文件, 主 App 的 `WorkflowService` (actor) 增量聚合出 `daily.jsonl` 与 `WorkflowSnapshot` 供热力图详情面板展示; 可选跨设备同步由 `WorkflowSyncScheduler` (唯一调度者) 与 `WorkflowSyncService` 负责, 走 `iCloud.app.zabrian.codexbar` 容器的 CloudKit private database, 只上传脱敏 daily 聚合-- 带 `--hook-event` 参数启动 → Hook 子进程模式:从 stdin 读 JSON payload,在 `flock` 锁内追加一行 JSONL 后立即退出,绝不初始化菜单栏 UI。写入失败静默吞掉,不阻断 Codex。-- 普通启动 → `CodexBarAppDelegate` 创建长期对象(`CodexStatusViewModel`、`WorkflowViewModel`、各 Settings、`AppUpdater`),由 `StatusItemController.install()` 装配菜单栏。+`WorkflowStorage` 管理的存储目录含 `events/` `daily.jsonl` `stats.lock` `maintenance.json` `Sync/` 五项; 保留期 210 天, 对原始事件文件和 daily 聚合同时生效, 清理由 `pruneExpiredEventFiles` 执行; 聚合里的会话与轮次标识额外只保留 3 天, 过期后被 compact 掉-### 两条主数据链路+**链路三: 实时任务, 由 `CodexActivityMonitor` 驱动**-1. **app-server 链路**:`CodexStatusService`(actor)通过 `CodexCLIResolver` 解析出 `codex` 可执行文件(PATH 全局优先,回退 Codex.app 内置),启动 `codex app-server --listen stdio://`,用 `AppServerSession` 做 stdio JSON-RPC,合成 `CodexQuotaSnapshot` 交给 `CodexStatusViewModel` 发布。刷新间隔 60 秒,请求超时 20 秒,连接最长复用 1 小时。-2. **Hook 链路**:Hook 子进程写入 `~/Library/Application Support/CodexBar/HookEvents/events/YYYY-MM-DD.jsonl`;主 App 的 `WorkflowService`(actor)串行做增量聚合,产出 `daily.jsonl` 和 `WorkflowSnapshot` 供热力图详情面板展示。可选的跨设备同步由 `WorkflowSyncScheduler`(唯一调度者)+ `WorkflowSyncService` 走 CloudKit private database,只上传脱敏的 daily 聚合。+`CodexActivityMonitor` 是菜单栏图标; 活动卡片; 通知; 触觉反馈和防休眠的**唯一任务状态来源**, 由两个 reader 供料++- `HookEventTailReader` (actor) 的 bootstrap 覆盖滚动 24 小时并作为单次事务发送, 之后按当日文件 offset 增量 tail+- `CodexSessionLifecycleReader` (actor) 增量读取 `~/.codex/sessions` 与 `archived_sessions` 下的 rollout JSONL, 只提取 turn 生命周期字段, 不解码会话或工具内容++系统唤醒时 `NSWorkspace.didWakeNotification` 会触发立即 drain 并重置生命周期解析回退++### 防休眠 (KeepAlive) 与 root helper++两套机制叠加, 职责不同++- `SystemSleepService` 用进程内 `IOPMAssertion` 建立 `PreventUserIdleSystemSleep` 断言, 只挡空闲休眠, 不需要提权; 断言名必须是 ASCII, 否则 `pmset -g assertions` 显示不出标识+- `CodexBarHelper` 是 root LaunchDaemon, 通过 XPC 接受 `setSleepDisabled` 请求, 执行 `/usr/bin/pmset -a disablesleep` 覆盖合盖休眠++链路: `KeepAliveController` (MainActor) 订阅 `activityMonitor.$snapshot` 与 `codexHookSettings.$isEnabled` -> `SMAppService.daemon(plistName:)` 注册 -> `NSXPCConnection` -> helper++关键约束++- `shouldDisableSleep` 是用户意图与依赖可用性的唯一汇合点, 要求 `isEnabled && codexHookSettings.isEnabled && hasRunningTasks && helperStatus == .enabled && !hasReachedMaximumDuration` 同时成立; **依赖不满足只让效果失效, 绝不回写用户保存的 `isEnabled`**+- 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 分钟) 即放弃, 瞬时抖动能自愈, 权限类故障不该无限重试++### 通知++- `CodexNotificationService` 是集中式的 MainActor 服务, 订阅额度快照与实时活动, 负责阈值穿越判定; 去重, dedup key 落 UserDefaults; 额度重置识别; 触觉反馈和本地通知+- `NotificationSettings` 管 CodexBar 自身通知; `CodexCLINotificationSettings` 是另一回事, 它通过 app-server `config/read` 与 `config/batchWrite` 读写 Codex 自己的用户级 `config.toml`### 并发与隔离-工程开启 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`:所有类型默认 MainActor 隔离。因此:+工程开启 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor` 设置, 所有类型默认 MainActor 隔离-- UI、控制器、ViewModel、设置、更新类直接依赖默认 MainActor,不需要额外标注-- 服务共享状态用 actor 管理(`CodexStatusService`、`WorkflowService`、`CodexCLIVersionService`)-- DTO、模型、同步辅助类型和静态工具必须显式标注 `nonisolated`-- 后台同步写入用锁:`RequestLogStorage` 用 `OSAllocatedUnfairLock`,Hook 写入用 `stats.lock` + `flock`-- 非 Sendable 的管道 IO 集中在 `PipeReadBuffer`(`JSONLineReader` / `PipeDrain` 复用它)+- UI; 控制器; ViewModel; Settings; 更新类直接依赖默认隔离, 不需要额外标注+- 服务共享状态用 actor 管理, 包括 `CodexStatusService` `WorkflowService` `WorkflowSyncService` `CodexCLIVersionService` `HookEventTailReader` `CodexSessionLifecycleReader`+- DTO; 纯模型; 静态工具; 跨 actor 传递的类型必须显式标注 `nonisolated`+- 跨进程写统计文件用 `stats.lock` 加 `flock` 保护, Hook 子进程有等待上限, 主 App 无限等待; `RequestLogStorage` 用 `OSAllocatedUnfairLock`+- 非 Sendable 的管道 IO 集中在 `PipeReadBuffer` 里, `JSONLineReader` 与 `PipeDrain` 复用它+- 保留既有防重入与过期结果丢弃逻辑, 例如 `RefreshTaskCoordinator` 只让最新 generation 提交结果+- 不要用阻塞 I/O 或长耗时操作卡住 MainActor### 错误处理原则-- 菜单面板只暴露三种结果(`CodexFetchOutcome`):有数据、未登录、初始化失败;启动失败/超时/断连/解析失败等细节全部只进请求日志窗口(`RequestLogStorage`,上限 500 条)-- 账号有效时 rate limits 和 usage 允许单独失败:复用同账号旧缓存并标记 stale(UI 半透明),无缓存则该区域不显示-- Hook 子进程任何失败都静默退出,优先保证不拖慢 Codex+- 菜单面板的 `CodexFetchOutcome` 只暴露有数据; 未登录; 初始化失败三种结果, 而启动失败; 超时; 断连; 解析失败等细节全部只进日志窗口, 由 `RequestLogStorage` 保存, 上限 500 条+- 账号有效时 rate limits 和 usage 允许单独失败, 复用同账号旧缓存并标记 stale, UI 显示为半透明, 无缓存则该区域不显示; 账号变化时整体丢弃缓存避免串号+- 各 Settings 类把读取类错误与操作类错误分开存储, 定时 refresh 不能抹掉用户操作或校验的结论, 参见 `CodexHookSettings` 与 `KeepAliveController`+- Hook 子进程任何失败都静默退出, 优先保证不拖慢 Codex-### 菜单面板与侧边面板+## UI 与窗口约定-- 菜单面板是 `NSPopover`(status item 锚点不可信时回退屏幕顶部居中的 `NSPanel`),关闭逻辑由 `MenuSurfaceDismissMonitor` 统一管理-- 两个侧边详情面板(热力图详情、重置次数)是菜单面板的 borderless nonactivating child panel,公共行为集中在 `Controllers/SidePanelSupport.swift`(panel 工厂、定位夹紧、抽屉动画、child window 挂载),玻璃皮肤共用 `Views/Shared/LiquidGlassStyle.swift`-- ⚠️ `HeatmapDetailPanelController` 每次 hover 内容变化必须替换 `hostingController.rootView` 并同步 `setContentSize`,不要用常驻 ObservableObject 推送 hover context——Hook 开关切换会导致面板在两种尺寸间变化,复用同一棵 SwiftUI 布局树会触发 AppKit layout 递归+- 菜单栏按钮左键切换主面板; 右键或 Control+点击打开上下文菜单; `⌘,` 打开自定义设置窗口, 菜单面板打开时 `⌘L` 打开日志窗口; 默认全局快捷键 `⌘⇧W` 由 `GlobalHotKeySettings` 与 `GlobalHotKeyController` 管理+- 主面板是锚定 status item 的 `NSPopover` 弹窗, 锚点不可信时回退到 `FallbackPanelController` 提供的屏幕顶部居中 `NSPanel` 面板, 处理快捷键; 屏幕选择和焦点时要保留这两个分支+- 关闭逻辑统一由 `MenuSurfaceDismissMonitor` 管理, 淡出由 `MenuSurfaceFadeCoordinator` 负责+- 侧边详情面板 (热力图详情; 重置次数) 是主面板的 borderless nonactivating child panel, 公共能力集中在 `Controllers/SidePanelSupport.swift` 里, 含 `SidePanelContentHost` `SidePanelDrawerAnimator` panel 工厂和定位夹紧; 新增侧边面板优先复用, 不要另起一套+- 设置窗口 (通用/高级/关于三页) 和日志窗口复用 `HostingWindowController` 的行为, 可以成为 key window, 但不应成为 main window+- 视觉风格统一走 `Views/Shared/LiquidGlassStyle.swift` 这一套, 避免引入与系统菜单栏工具不一致的重装饰 UI-### 修改 Hook 配置的约束+## Hook 配置改写约束-`~/.codex/hooks.json` 的读写在 `CodexHookSettings`:只识别并移除 command 同时包含「当前 CodexBar 可执行路径 + `--hook-event`」的 handler,必须保留用户已有 Hook、其他 App 的 Hook 和同事件下的其他 handler。写入前需通过 app-server `config/read` 确认全局未禁用 Hook,写入后用 `hooks/list` 验证。+`~/.codex/hooks.json` 的读写全部在 `CodexHookSettings` 里完成, Codex 目录优先取 `CODEX_HOME` 环境变量, 找不到时回退真实用户 HOME 下的 `.codex` 目录-## 隐私与数据边界--改动涉及网络或日志时必须遵守:+- 只识别并移除 command 同时包含当前 CodexBar 可执行路径与 `--hook-event` 的 handler, 必须保留用户已有 Hook 以及其他 App 的 Hook 和同事件下的其他 handler+- 写入前通过 app-server `config/read` 确认全局未禁用 Hook, 写入后用 `hooks/list` 验证+- 读取失败 (I/O 或 JSON 格式错误) 不提供 Hook 装没装的信息, 必须保留上次已知值, 不能当成用户关闭了 Hook-- App 只发起四类网络请求:本机 app-server stdio 通信(不算网络)、重置机会过期时间只读查询(`chatgpt.com/backend-api/wham/rate-limit-reset-credits`)、Sparkle 更新、用户显式开启后的 CloudKit 同步-- 不展示 app-server stderr;不展示或记录 Codex OAuth token / `auth.json` 内容-- 不把原始敏感 RPC 响应写进文档或测试夹具-- CloudKit 只同步去掉 `sessionIds` / `turnIds` 的 daily 聚合,不同步原始 Hook events、账号、额度或 Token 用量+## 隐私与数据边界-## 目录职责+改动涉及网络; 日志或同步时必须遵守-| 目录 | 职责 |-| ----------------------- | -------------------------------------------------------------- |-| `CodexBar/App/` | SwiftUI 入口和启动分流 |-| `CodexBar/Controllers/` | 菜单栏、菜单面板、侧边 child panel、设置/日志窗口控制器 |-| `CodexBar/Models/` | account、quota、usage、workflow、日期网格和错误模型 |-| `CodexBar/Services/` | app-server、Codex CLI 解析、Hook、统计维护、同步、更新、登录项 |-| `CodexBar/Views/` | 菜单面板、设置窗口、日志窗口和共享 Liquid Glass 样式 |-| `Scripts/` | 构建、DMG 和 appcast 发布脚本 |+- 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 用量-## 文档同步+## 代码修改原则-改动涉及流程、错误处理、UI 常量或数据边界时,同步更新 `Docs/DevelopmentGuide.md` 中对应章节;协议或统计口径变化时更新 `Docs/AppServer.md` / `Docs/CodexHook.md` / `Docs/CrossDeviceSync.md`。+- 优先贴合现有文件结构和类型职责, 不为小改动新建抽象+- 改 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 7e28770..8c738cb 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 = 56;+ CURRENT_PROJECT_VERSION = 57;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.2;+ MARKETING_VERSION = 3.5.3;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 = 56;+ CURRENT_PROJECT_VERSION = 57;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.2;+ MARKETING_VERSION = 3.5.3;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 768f7bf..bdfbc31 100644--- a/CodexBar/Controllers/StatusItemController.swift+++ b/CodexBar/Controllers/StatusItemController.swift@@ -199,25 +199,51 @@ private final class StatusItemController: NSObject, NSMenuDelegate {super.init()}- /// 无状态点和额度条时使用模板渲染, 由系统按菜单栏外观着色+ /// 无状态点; 额度条和符号着色时使用模板渲染, 由系统按菜单栏外观着色+ /// keepAliveFraction: 0 为常态, 1 为阻止休眠态, 中间值是过渡帧private static func makeStatusImage(_ symbolName: String,- indicatorTint: NSColor? = nil,+ keepAliveFraction: CGFloat,+ indicatorTint: NSColor?,indicatorVisibility: CGFloat = 1,- progress: StatusIconProgress? = nil,+ progress: StatusIconProgress?,progressVisibility: CGFloat = 1) -> NSImage? {guard let symbolImage = makeStatusSymbolImage(symbolName) else {return nil}- let usesTemplateRendering = indicatorTint == nil && progress == 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 : 1let 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: usesTemplateRendering ? .black : .labelColor,- alpha: progress?.isStale == true ? Metrics.staleIconAlpha : 1+ tint: tint,+ // 两个来源相乘: stale 时在符号自身透明度基础上再淡一档+ alpha: symbolAlpha * staleAlpha)if let progress {Self.drawProgress(@@ -336,6 +362,38 @@ 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,+ _ destination: NSColor,+ progress: CGFloat+ ) -> NSColor {+ let progress = clampedVisibility(progress)+ return source.blended(withFraction: progress, of: destination)+ ?? (progress < 0.5 ? source : destination)+ }++ /// 图标动画中一条 0↔1 的过渡: 起止由布尔状态决定, 按动画进度取中间值+ private static func transitionValue(+ from source: Bool,+ to destination: Bool,+ progress: CGFloat+ ) -> CGFloat {+ interpolated(from: visibility(source), to: visibility(destination), progress: progress)+ }+private static func easedVisibility(_ value: CGFloat) -> CGFloat {let value = clampedVisibility(value)return value * value * (3 - 2 * value)@@ -345,6 +403,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {let usesErrorImage: Boollet progress: StatusIconProgress?let activity: CodexActivitySnapshot+ let isPreventingSleep: Boolvar symbolName: String {usesErrorImage ? Metrics.errorStatusSymbolName : Metrics.normalStatusSymbolName@@ -365,7 +424,12 @@ private final class StatusItemController: NSObject, NSMenuDelegate {/// 只包含影响图像像素的字段; tooltip 文本变化不应触发重绘var renderState: StatusIconRenderState {- StatusIconRenderState(symbolName: symbolName, indicator: indicator, progress: progress)+ StatusIconRenderState(+ symbolName: symbolName,+ indicator: indicator,+ progress: progress,+ isPreventingSleep: isPreventingSleep+ )}var hasLiveDuration: Bool {@@ -431,6 +495,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {let symbolName: Stringlet indicator: ActivityIndicator?let progress: StatusIconProgress?+ let isPreventingSleep: Bool}private enum ActivityIndicator: Equatable {@@ -596,11 +661,14 @@ private final class StatusItemController: NSObject, NSMenuDelegate {menuBarQuotaSettings.$selection,activityMonitor.$snapshot)- .map { loadState, snapshot, selection, activity in- StatusIconState(+ .combineLatest(keepAliveController.isActivelyPreventingSleepPublisher)+ .map { base, isPreventingSleep in+ let (loadState, snapshot, selection, activity) = base+ return StatusIconState(usesErrorImage: loadState.isError || snapshot?.hasTrustedData == false,progress: StatusIconProgress(snapshot: snapshot, selection: selection),- activity: snapshot == nil ? .empty : activity+ activity: snapshot == nil ? .empty : activity,+ isPreventingSleep: isPreventingSleep)}.removeDuplicates()@@ -731,7 +799,8 @@ private final class StatusItemController: NSObject, NSMenuDelegate {statusIconAnimationTask?.cancel()let progressVisibilityChanged = (previousState.progress == nil) != (state.progress == nil)- if previousState.indicator != state.indicator || progressVisibilityChanged {+ let symbolTintChanged = previousState.isPreventingSleep != state.isPreventingSleep+ if previousState.indicator != state.indicator || progressVisibilityChanged || symbolTintChanged {animateStatusImage(from: previousState, to: state)return}@@ -742,6 +811,7 @@ 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)@@ -749,10 +819,6 @@ private final class StatusItemController: NSObject, NSMenuDelegate {private func animateStatusImage(from previousState: StatusIconState, to finalState: StatusIconState) {let renderedProgress = finalState.progress ?? previousState.progress- let fromProgressVisibility: CGFloat = previousState.progress == nil ? 0 : 1- let toProgressVisibility: CGFloat = finalState.progress == nil ? 0 : 1- let fromIndicatorVisibility: CGFloat = previousState.indicator == nil ? 0 : 1- let toIndicatorVisibility: CGFloat = finalState.indicator == nil ? 0 : 1statusIconAnimationTask = Task { @MainActor [weak self] infor frame in 0 ... Metrics.statusIconAnimationFrameCount {@@ -764,20 +830,29 @@ private final class StatusItemController: NSObject, NSMenuDelegate {let rawProgress = CGFloat(frame) / CGFloat(Metrics.statusIconAnimationFrameCount)let easedProgress = Self.easedVisibility(rawProgress)- let progressVisibility = fromProgressVisibility- + (toProgressVisibility - fromProgressVisibility) * easedProgress- let indicatorVisibility = fromIndicatorVisibility- + (toIndicatorVisibility - fromIndicatorVisibility) * easedProgressstatusItem.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,progress: easedProgress),- indicatorVisibility: indicatorVisibility,+ indicatorVisibility: Self.transitionValue(+ from: previousState.indicator != nil,+ to: finalState.indicator != nil,+ progress: easedProgress+ ),progress: renderedProgress,- progressVisibility: progressVisibility+ progressVisibility: Self.transitionValue(+ from: previousState.progress != nil,+ to: finalState.progress != nil,+ progress: easedProgress+ ))if frame < Metrics.statusIconAnimationFrameCount {@@ -826,13 +901,12 @@ private final class StatusItemController: NSObject, NSMenuDelegate {) -> NSColor? {switch (source, destination) {case let (source?, destination?):- let progress = clampedVisibility(progress)- return source.color.blended(withFraction: progress, of: destination.color)- ?? (progress < 0.5 ? source.color : destination.color)+ // 只在两端都有指示点时混色; 单端的显隐交给 indicatorVisibility+ blendedColor(source.color, destination.color, progress: progress)case let (indicator?, nil), let (nil, indicator?):- return indicator.color+ indicator.colorcase (nil, nil):- return nil+ nil}}@@ -1329,6 +1403,11 @@ 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 0aa35ca..ff62971 100644--- a/CodexBar/Services/KeepAlive/KeepAliveController.swift+++ b/CodexBar/Services/KeepAlive/KeepAliveController.swift@@ -24,6 +24,18 @@ final class KeepAliveController: ObservableObject {registrationErrorMessage ?? operationErrorMessage}+ /// 用户开关仍开着, 且 helper 已经真的把休眠关掉+ /// isPreventingSleep 在稳态下已隐含 isEnabled (shouldDisableSleep 要求它),+ /// 叠这一层是为了关开关到 helper 回调之间的异步空窗: 用户意图先落地+ var isActivelyPreventingSleepPublisher: AnyPublisher<Bool, Never> {+ Publishers.CombineLatest($isEnabled, $isPreventingSleep)+ .map { isEnabled, isPreventingSleep in+ isEnabled && isPreventingSleep+ }+ .removeDuplicates()+ .eraseToAnyPublisher()+ }+private let activityMonitor: CodexActivityMonitorprivate let codexHookSettings: CodexHookSettingsprivate let defaults: UserDefaults@@ -104,7 +116,6 @@ final class KeepAliveController: ObservableObject {if connection != nil {applySleepDisabled(false)}- _ = systemSleepService.endPreventingIdleSleep()invalidateConnection()}@@ -319,8 +330,7 @@ final class KeepAliveController: ObservableObject {// 操作类结果 (例如重试耗尽) 必须留到下一次操作有结论为止registrationErrorMessage = nil} else if helperStatus != .requiresApproval {- _ = systemSleepService.endPreventingIdleSleep()- isPreventingSleep = false+ releaseSleepPrevention()resetMaximumDurationState()}}@@ -333,7 +343,7 @@ final class KeepAliveController: ObservableObject {if connection != nil, appliedSleepDisabled != false || isPreventingSleep {applySleepDisabled(false)} else {- _ = systemSleepService.endPreventingIdleSleep()+ releaseSleepPrevention()}return}@@ -385,9 +395,7 @@ final class KeepAliveController: ObservableObject {}self.requestInFlight = falseguard exitCode == 0 else {- if disabled {- _ = self.systemSleepService.endPreventingIdleSleep()- }+ // invalidateConnection 会连同 assertion 一起收self.invalidateConnection()self.operationErrorMessage = "切换休眠状态失败 (\(exitCode))"self.scheduleRetryIfNeeded(for: disabled)@@ -505,10 +513,8 @@ final class KeepAliveController: ObservableObject {}let shouldRetry = self.requestInFlight || self.isPreventingSleeplet desiredSleepDisabled = self.shouldDisableSleep- self.connection = nil- self.appliedSleepDisabled = nil- self.requestInFlight = false- self.isPreventingSleep = false+ // 复用统一清理: 连接失效同样要释放 assertion, 否则空闲休眠会被永久阻止+ self.invalidateConnection()if shouldRetry {self.scheduleRetryIfNeeded(for: desiredSleepDisabled)}@@ -543,6 +549,14 @@ final class KeepAliveController: ObservableObject {connection?.invalidate()appliedSleepDisabled = nilrequestInFlight = false+ releaseSleepPrevention()+ }++ /// assertion 与 isPreventingSleep 同进同退的唯一出口+ /// 两者必须一起收: 只清标志会让菜单栏图标显示成未防休眠, 而这条 assertion 仍在阻止空闲休眠,+ /// 且没有任何后续路径会释放它; 仍需要防休眠时由重试经 applySleepDisabled(true) 重建+ private func releaseSleepPrevention() {+ _ = systemSleepService.endPreventingIdleSleep()isPreventingSleep = false}diff --git a/CodexBar/Services/KeepAlive/SystemSleepService.swift b/CodexBar/Services/KeepAlive/SystemSleepService.swiftindex 6f5f75c..464edee 100644--- a/CodexBar/Services/KeepAlive/SystemSleepService.swift+++ b/CodexBar/Services/KeepAlive/SystemSleepService.swift@@ -13,6 +13,8 @@ final class SystemSleepService {}}+ private static let idleSleepAssertionName = "CodexBar - Codex task running"+private var idleSleepAssertionID = IOPMAssertionID(kIOPMNullAssertionID)func beginPreventingIdleSleep() -> IOReturn {@@ -21,10 +23,12 @@ final class SystemSleepService {}var assertionID = IOPMAssertionID(kIOPMNullAssertionID)+ // 名称必须是 ASCII: 含中文时 pmset -g assertions 会把 named 显示成空串,+ // 这条断言在诊断输出里就失去了标识, 只能靠进程名辨认let result = IOPMAssertionCreateWithName(kIOPMAssertionTypePreventUserIdleSystemSleep as CFString,IOPMAssertionLevel(kIOPMAssertionLevelOn),- "Codex 任务正在运行" as CFString,+ Self.idleSleepAssertionName as CFString,&assertionID)if result == kIOReturnSuccess {diff --git a/CodexBar/Services/Workflow/WorkflowService.swift b/CodexBar/Services/Workflow/WorkflowService.swiftindex cbbce2b..235aa8a 100644--- a/CodexBar/Services/Workflow/WorkflowService.swift+++ b/CodexBar/Services/Workflow/WorkflowService.swift@@ -68,7 +68,7 @@ actor WorkflowService {}// 单日失败不中止整批: 失败的日期已被 rebuildLocalData 标脏, 常规维护会自动重建- // 中止会让「前几天已改写、后几天没碰」这个事实完全不被上报+ // 中止会让「前几天已改写, 后几天没碰」这个事实完全不被上报var rebuildResults = [WorkflowMaintenanceResult]()var failedDateKeys = [String]()var firstFailure: Error?diff --git a/Docs/AppServer.md b/Docs/AppServer.mddeleted file mode 100644index 56ef333..0000000--- a/Docs/AppServer.md+++ /dev/null@@ -1,110 +0,0 @@-# Codex app-server--CodexBar 通过本机 Codex app-server 读取账号, 额度, Token 用量和部分用户配置; 通信使用子进程标准输入输出, 每条消息占一行 JSON--## Codex 解析--CodexBar 按以下顺序选择可执行文件--1. `PATH` 中的全局 `codex`-2. `/Applications/ChatGPT.app/Contents/Resources/codex`-3. `/Applications/Codex.app/Contents/Resources/codex`--菜单栏 App 的环境会补充 Homebrew, npm, `~/.local`, Volta 和系统命令目录; `HOME` 使用当前真实用户目录; Codex 配置目录优先取 `CODEX_HOME`, 否则使用 `~/.codex`--启动命令固定为--```text-codex app-server --listen stdio://-```--设置窗口会同时探测全局 Codex 和 App 内置 Codex 的版本, 并根据当前 app-server 握手结果标记实际使用来源--## 会话生命周期--新会话依次执行--1. 发送 `initialize`-2. 发送 `initialized` 通知-3. 发送 `account/read`, 确认账号已登录--连接在刷新之间复用, 最长保留 1 小时; 进程退出, 写入失败, 响应超时或响应无法解析时, 连接会关闭; 复用连接发生传输故障时, 本轮读取最多重建并重试一次--单次请求超时为 20 秒; stdout 读取器只向上层返回完整非空行, 并按响应 `id` 过滤; stderr 持续排空, 避免子进程因管道写满而阻塞--关闭会话时先结束管道并请求进程退出, 必要时再强制终止--## 使用的接口--| 方法 | 用途 |-| --- | --- |-| `initialize` | 建立客户端会话并读取运行版本 |-| `initialized` | 完成初始化通知 |-| `account/read` | 读取账号; 可请求刷新认证 |-| `account/rateLimits/read` | 读取额度限制, 窗口和可用重置次数 |-| `account/usage/read` | 读取 Token 摘要和每日用量 |-| `config/read` | 读取 Hook, 信任状态和 Codex TUI 通知配置 |-| `config/batchWrite` | 写入 Hook 信任状态和 TUI 通知配置 |-| `hooks/list` | 验证 Codex 实际解析出的 Hook |--`config/batchWrite` 始终设置 `reloadUserConfig: true`, 由 Codex 重新加载用户配置--## 刷新与缓存--UI 默认每 60 秒触发一次读取; 一次刷新按以下顺序处理--1. 复用连接时重新读取账号状态-2. 读取额度-3. 读取 Token 用量-4. 组装菜单面板快照--额度和用量是独立的补充数据--- 成功读取时更新当前账号的内存缓存-- 普通业务错误时可以回退到同一账号的缓存, 并标记为陈旧数据-- 方法不支持, 认证失败或连接故障时不使用该项缓存-- 账号变化时清空全部补充缓存--app-server 返回认证错误时, 本轮最多执行一次 `account/read(refreshToken: true)`; 刷新后仍未认证则进入"未登录"状态--app-server 明确表示方法不支持后, 当前会话会记住该方法, 后续不再重复请求; 可重试的服务端业务错误在会话层重试一次--## 手动重置机会--`account/rateLimits/read` 返回可用重置次数且数量大于 0 时, CodexBar 会读取当前 Codex 配置目录下的 `auth.json`, 向以下只读接口查询每次机会的过期时间--```text-https://chatgpt.com/backend-api/wham/rate-limit-reset-credits-```--请求超时为 4 秒, 只保留状态为 `available` 且尚未过期的时间; 401 或 403 时, 如果本轮尚未刷新认证, 会先通过当前 app-server 刷新一次账号认证再重试; 查询失败不影响额度和可用次数展示, 只是不提供具体过期时间--## 配置读写--CodexBar 通过 app-server 管理两类用户配置--- `hooks.state`: 只新增, 更新或移除当前 CodexBar Hook 对应的信任项-- `tui.notifications`: 写入布尔值控制 Codex TUI 通知--Hook 事件注册本身保存在 `${CODEX_HOME}/hooks.json`, 由 CodexBar 直接按 JSON 文件读写; 注册后再通过 `hooks/list` 验证; 详见 [Codex Hook 与工作流统计](CodexHook.md)--## 交互日志--日志窗口保存本次运行期间最近 500 条记录, 包括--- 请求方法和请求 JSON-- 响应 JSON-- 传输, 解析, 业务和进程错误-- 无响应通知--合法 JSON 会按稳定键序规范化; 日志只保存在进程内存中, 可以在窗口内清空, 不写入工作流文件, 也不参与跨设备同步--## UI 状态--服务层向 UI 归并为三类结果--- 数据可用-- 未登录-- 初始化失败--更具体的请求错误保留在交互日志中; 陈旧的额度或用量仍可展示, 但会降低透明度, 且不会用于额度通知判断diff --git a/Docs/CodexHook.md b/Docs/CodexHook.mddeleted file mode 100644index 553c41f..0000000--- a/Docs/CodexHook.md+++ /dev/null@@ -1,153 +0,0 @@-# Codex Hook 与工作流统计--CodexBar Hook 是可选功能, 用于记录本机 Codex 工作流事件; 它为实时任务, 任务中心, 任务通知, 防休眠, 每日工作流统计和跨设备同步提供数据--## 注册与关闭--Hook 配置文件位于--```text-${CODEX_HOME}/hooks.json-```--未设置 `CODEX_HOME` 时使用--```text-~/.codex/hooks.json-```--开启 Hook 时, CodexBar 会--1. 通过 app-server 确认 Codex 没有全局禁用 Hook-2. 保留现有配置, 只移除当前 CodexBar 可执行文件的旧条目-3. 为全部受支持事件追加独立 command handler-4. 原子写回 `hooks.json`-5. 通过 `hooks/list` 验证事件, 命令, 来源和启用状态-6. 必要时通过 `config/batchWrite` 更新 `hooks.state` 中对应的信任哈希--handler 命令格式为--```text-'<CodexBar 可执行文件>' --hook-event-```--单个 handler 超时为 5 秒--关闭 Hook 时, CodexBar 只删除同时匹配当前可执行路径和 `--hook-event` 的 handler, 并只清理这些 Hook 的信任项; 其他应用或用户自行配置的 Hook 保持不变--## 事件范围--CodexBar 注册以下事件--| 事件 | 用途 |-| --- | --- |-| `SessionStart` | 会话开始 |-| `UserPromptSubmit` | 新任务或新轮次开始 |-| `PreToolUse` | 工具调用开始 |-| `PostToolUse` | 工具调用结束 |-| `PermissionRequest` | 权限审批请求 |-| `PreCompact` | 上下文压缩开始 |-| `PostCompact` | 上下文压缩结束 |-| `Stop` | 任务完成 |-| `SubagentStart` | 子 Agent 开始 |-| `SubagentStop` | 子 Agent 结束 |--事件名解析会忽略大小写, 下划线和连字符差异--## Hook 子进程--应用启动入口最先检查 `--hook-event`; 处于 Hook 模式时不会创建菜单栏, 窗口或普通服务, 而是--1. 从 stdin 读取一份 JSON payload-2. 归一化事件字段-3. 追加一行本地 JSONL-4. 立即退出--原始事件行包含--```text-timestamp, event, model, effort, permission, approval,-session, turn, agent, tool, cwd-```--除事件名外, 其余字段允许缺失; 时间戳缺失时使用当前时间, 工作目录缺失时使用子进程当前目录--`PermissionRequest` 和 `UserPromptSubmit` 可以从 payload 中的 rollout 路径读取对应 `turn_context`, 补充审批路由和推理强度; 只有审批路由为 `user` 时, 实时任务才进入"等待批准"; `auto_review` 和 `guardian_subagent` 仍按运行状态处理--## 本地文件--工作流数据目录为--```text-~/Library/Application Support/CodexBar/HookEvents/-```--| 文件 | 内容 |-| --- | --- |-| `events/YYYY-MM-DD.jsonl` | 按本地日期拆分的原始 Hook 事件 |-| `daily.jsonl` | 每日聚合结果 |-| `maintenance.json` | 维护 schema, 文件位置, 待增量和待重建状态 |-| `stats.lock` | Hook 子进程与主 App 共用的进程级文件锁 |-| `Sync/` | 开启跨设备同步后使用的本地同步状态和缓存 |--Hook 子进程在跨进程排他锁内完成文件追加和维护状态更新; 主 App 的聚合读取在锁外执行, 提交前后再检查源文件大小, inode 和边界哈希, 避免把截断, 替换或并发写入误认为连续追加--JSONL 中的坏行会被跳过并计数, 不会使整天数据失效--## 每日聚合--主 App 根据维护状态执行两类任务--- `pending`: 从已记录的文件 offset 增量读取新增事件-- `dirty`: 从当天事件文件开头重新构建聚合--以下情况会触发全量重建: 维护 schema 不匹配, 每日聚合缺失或损坏, 事件文件被截断或替换, 已处理边界发生变化--每日聚合保存--- 事件总数-- 各 Hook 事件计数-- 会话数和轮次数-- 项目计数-- 模型计数-- 来源 generation--统计口径--| 展示指标 | 计算方式 |-| --- | --- |-| 会话总数 | 优先使用去重会话 ID 或压缩后的计数, 回退到 `SessionStart` 数量 |-| 对话轮次 | 优先使用去重轮次 ID 或压缩后的计数, 回退到 `Stop` 数量 |-| 工具调用 | `PreToolUse` 与 `PostToolUse` 的较大值 |-| 上下文压缩 | `PreCompact` 与 `PostCompact` 的较大值 |-| 子 Agent | `SubagentStart` 与 `SubagentStop` 的较大值 |-| 权限请求 | `PermissionRequest` 数量 |-| 最热模型 | 模型事件计数最高者; 并列时按名称排序 |--会话 ID 和轮次 ID 只在最近 3 个本地自然日的聚合中保留, 用于持续去重; 更早日期只保存计数; 原始事件和每日聚合最多保留最近 210 天, 维护时删除过期的原始事件文件--## 实时任务--`HookEventTailReader` 启动时读取最近 24 小时事件, 然后每 2 秒增量读取当天文件; 日期切换时会先读完旧文件, 再开始新文件--实时任务以 `session + turn` 为主要标识, 缺少字段时回退到 session 或项目; 状态由 Hook 事件和 Codex rollout 生命周期共同确定--- `UserPromptSubmit` 创建运行任务-- 工具, 压缩和子 Agent 事件更新运行状态-- `PermissionRequest` 在审批路由为用户时进入等待状态-- `Stop` 记录完成-- rollout 中的 `task_complete` 和 `turn_aborted` 补充可靠终态与时长--rollout reader 每秒检查活跃任务, 只读取任务开始, 上下文, 完成和终止字段, 不解析对话正文或工具内容--任务中心保留最近 10 分钟的完成和终止记录; 菜单栏完成状态高亮约 30 秒; 实时恢复窗口为最近 24 小时--## 手动重建--设置中的"重建数据"允许选择最近 210 天内的日期范围; CodexBar 只处理范围内存在非空原始事件文件的日期, 并逐日重建 `daily.jsonl`--单日失败不会中止其他日期; 失败日期保持为待重建状态, 后续维护会继续处理; 跨设备同步开启时, 所选日期还会登记为当前设备的待替换数据; 详见 [跨设备同步](CrossDeviceSync.md)--## 隐私--Hook 原始事件和本地聚合默认只保存在本机; CodexBar 不记录对话正文, 工具输入输出或认证内容; 跨设备同步仅使用每日脱敏聚合, 不上传原始事件, session ID, turn ID 或 agent IDdiff --git a/Docs/CrossDeviceSync.md b/Docs/CrossDeviceSync.mddeleted file mode 100644index 9bd7636..0000000--- a/Docs/CrossDeviceSync.md+++ /dev/null@@ -1,147 +0,0 @@-# 跨设备同步--CodexBar 使用 CloudKit 私有数据库同步每日工作流聚合; 同步是可选功能, 仅在 CodexBar Hook 已开启, 用户打开同步开关且当前 iCloud 账号可用时生效--## 同步范围--每台设备按日期上传一条或多条来源明确的聚合记录, 内容包括--- 日期和来源 generation-- Hook 事件总数-- 会话开始和任务完成计数-- 工具调用前后计数-- 权限请求计数-- 上下文压缩前后计数-- 子 Agent 开始和结束计数-- 已压缩的会话数和轮次数-- 项目计数字典-- 模型计数字典-- 设备标识和更新时间--以下内容不会同步--- 原始 Hook 事件-- session ID, turn ID, agent ID-- 对话正文, 工具输入输出和 Codex rollout 文件-- app-server 请求日志-- Codex `auth.json`, access token 或其他认证文件-- 账号额度和 Token 用量--## CloudKit 结构--容器--```text-iCloud.app.zabrian.codexbar-```--数据库和自定义 zone--```text-privateCloudDatabase / CodexBarZone-```--记录类型--| 类型 | 内容 |-| --- | --- |-| `CodexBarSyncMetadata` | 账号级随机 salt 和同步 schema |-| `CodexBarDailyAggregate` | 单台设备, 单个日期, 单个来源 generation 的每日聚合 |--当前写入的 CloudKit schema 版本为 `4`--## 设备标识--CodexBar 不直接上传 Mac 的 `IOPlatformUUID`; 应用先在当前 iCloud 私有 zone 中创建或读取 32 字节随机 salt, 再计算--```text-HMAC-SHA256(IOPlatformUUID, account salt)-```--计算结果作为同步设备标识; 不同 iCloud 私有数据库使用不同 salt, 原始硬件 UUID 不写入 CloudKit--## 本地同步状态--同步目录位于--```text-~/Library/Application Support/CodexBar/HookEvents/Sync/-```--| 文件 | 内容 |-| --- | --- |-| `state.json` | schema, 当前设备 ID, 各日期确认 hash, 待替换日期和最近上传时间 |-| `cache.jsonl` | 保留范围内所有设备的 CloudKit 每日记录缓存 |-| `cursor.data` | CloudKit zone 增量变化游标 |--当前本地同步 state schema 为 `4`, 可读取上一版 schema `3` 并通过全量远端缓存重建迁移--## 同步流程--一次同步按以下顺序执行--1. 确认自定义 zone 存在-2. 创建或读取账号级 salt, 并计算当前设备 ID-3. 设备 ID 变化时清理本地游标和远端缓存-4. 使用 zone 游标拉取增量变化; 没有游标或增量失败时全量查询-5. 将本机 `daily.jsonl` 转换为同步聚合并计算稳定 hash-6. 上传尚未确认的日期-7. 再次拉取 CloudKit 变化并更新本地缓存-8. 每天清理当前设备超过 210 天的云端记录--单批最多处理 25 条上传, 每轮上传预算为 20 秒; 未处理完成的日期保留为待同步状态, 由后续刷新继续--首次开启同步会请求补传保留范围内的本机聚合; 日常同步由工作流调度器合并, 主要触发来源包括--- app-server 自动刷新后的工作流维护-- 同步开关开启-- Codex Hook 重新开启-- iCloud 同步账号恢复可用--连续同步之间使用 8 秒冷却窗口, 期间的新请求合并为一次后续同步--## 合并规则--界面展示会合并本机聚合和 `cache.jsonl` 中的远端记录--- 其他设备的记录按日期累加-- 当前设备与本机相同 generation 的远端副本不会重复累加-- 相同来源中 `eventCount` 更大的记录作为较完整版本-- 没有 generation 的旧记录只有在全部同步字段一致时才视为本机副本-- 明确从空文件开始的新 generation 可以作为独立来源累加-- 来源不明确的替换优先保留已有远端记录, 避免把同一批数据重复计数--上传同样遵循来源连续性; 相同来源的远端记录事件数更大时, 本机不会用较小聚合覆盖它--## 数据重建与替换--用户在设置中重建日期范围后, CodexBar 将这些日期登记为当前设备的待替换数据; 下一次可用同步会--1. 全量刷新 CloudKit 本地缓存-2. 删除当前设备在对应日期的旧记录, 包括 legacy 和 generation 记录-3. 从本地缓存移除这些旧副本-4. 上传重建后的新 generation-5. 新记录确认后清除待替换标记--替换只影响当前设备和所选日期, 不删除其他设备或范围外记录; 删除, 上传或网络请求中断时, 待替换标记会保留并在后续同步继续--## 保留期--本地工作流聚合和 CloudKit 缓存只参与最近 210 天的展示; CodexBar 每天清理当前设备超过保留期的 CloudKit 记录, 并从本地同步状态中移除对应确认 hash--其他设备的过期记录由对应设备在同步时清理; 即使远端仍存在, 当前设备加载缓存时也会过滤保留期外的数据--## 状态与错误--设置页显示最近一次实际上传时间; 主面板底部 iCloud 图标表示--- 同步未开启-- 正在同步-- 同步可用及最近上传时间-- 网络, 账号, 服务或重试类错误--同步失败会保留本地数据和待处理状态; zone 与账号 salt 的进程内缓存会失效, 下一轮重新确认当前 iCloud 账号状态--## 发布要求--CloudKit Production 环境必须包含当前 `CodexBarSyncMetadata` 和 `CodexBarDailyAggregate` 字段; 代码不会在运行时把 Development schema 部署到 Productiondiff --git a/Docs/DevelopmentGuide.md b/Docs/DevelopmentGuide.mddeleted file mode 100644index 4e98aca..0000000--- a/Docs/DevelopmentGuide.md+++ /dev/null@@ -1,382 +0,0 @@-# CodexBar 开发指南--CodexBar 是 macOS 15+ 菜单栏应用, 使用 Swift 6, SwiftUI, AppKit 和 MVVM; 工程包含主 App 与一个随 App 嵌入的 root helper--## 工程配置--| 项目 | 配置 |-| --- | --- |-| Xcode 工程 | `CodexBar.xcodeproj` |-| Scheme | `CodexBar` |-| 最低系统 | macOS 15.0 |-| Swift | 6.0 |-| UI | SwiftUI + AppKit |-| 默认 actor isolation | `MainActor` |-| App Sandbox | 关闭 |-| Hardened Runtime | 开启 |-| 更新 | Sparkle |-| 同步 | CloudKit private database |--主 App 是 `LSUIElement`, 没有 Dock 图标和传统主窗口; App Sandbox 关闭, 以便启动本机 Codex, 读取用户 Codex 配置并管理 Hook; 应用启用 Hardened Runtime--## Targets--### CodexBar--主菜单栏应用, 负责--- app-server 通信-- 账号, 额度和 Token 用量展示-- Hook 注册, 实时任务和工作流聚合-- 通知, 设置, 日志和更新-- CloudKit 同步-- 防休眠状态控制和 helper 注册--Bundle identifier--```text-Debug: app.zabrian.codexbar.debug-Release: app.zabrian.codexbar-```--### CodexBarHelper--随 App 嵌入的 root LaunchDaemon, 只接受签名匹配的 CodexBar XPC 客户端请求, 并使用 `pmset` 切换 `disablesleep`; 详细边界见 [阻止系统休眠](KeepAlive.md)--Bundle identifier--```text-Debug: app.zabrian.codexbar.debug.helper-Release: app.zabrian.codexbar.helper-```--## 目录结构--```text-.-├── CodexBar/-│ ├── App/-│ │ └── CodexBarApp.swift SwiftUI 入口和 AppDelegate 启动装配-│ ├── Controllers/-│ │ ├── StatusItemController.swift 状态栏入口, 主面板和应用级 UI 装配-│ │ ├── FallbackPanelController.swift 状态栏锚点不可用时的备用主面板-│ │ ├── GlobalHotKeyController.swift 全局快捷键注册和事件处理-│ │ ├── ActivityCenterPanelController.swift 任务中心侧边面板-│ │ ├── HeatmapDetailPanelController.swift 热力图日期详情侧边面板-│ │ ├── NotificationOptionsPanelController.swift 通知选项侧边面板-│ │ ├── ResetCreditsPanelController.swift 手动重置机会侧边面板-│ │ ├── SidePanelSupport.swift 侧边面板定位, 挂载, 动画和外观支持-│ │ ├── HostingWindowController.swift SwiftUI 辅助窗口通用控制-│ │ ├── SettingsWindowController.swift 设置窗口生命周期-│ │ ├── LogWindowController.swift 日志窗口生命周期-│ │ ├── MenuSurfaceDismissMonitor.swift 外部点击, 焦点和快捷键关闭处理-│ │ ├── MenuSurfaceFadeCoordinator.swift 主面板与侧边面板淡入淡出协调-│ │ └── ScreenGeometry.swift 屏幕选择, 锚点和可见区域计算-│ ├── Models/-│ │ ├── CodexAccountModels.swift 账号和订阅模型-│ │ ├── CodexQuotaModels.swift 额度限制和时间窗口模型-│ │ ├── CodexUsageModels.swift Token 用量模型-│ │ ├── CodexActivityModels.swift 实时任务和任务快照模型-│ │ ├── CodexHookEvent.swift Hook 原始事件模型-│ │ ├── CodexWorkflowModels.swift 每日聚合和同步模型-│ │ ├── CodexStatusError.swift 状态读取错误分类-│ │ ├── CodexWeekGrid.swift 周视图和日期网格模型-│ │ ├── UsageHeatmapDay.swift 热力图日期展示模型-│ │ ├── GlobalHotKeyShortcut.swift 快捷键组合模型-│ │ └── DateFormatter.swift 日期解析和显示格式-│ ├── Services/-│ │ ├── CodexCLI/-│ │ │ ├── CodexCLIResolver.swift Codex 路径和配置目录解析-│ │ │ └── CodexCLIVersionService.swift CLI 版本和实际使用来源探测-│ │ ├── CodexStatus/-│ │ │ ├── AppServerSession.swift app-server stdio 会话和 JSON 请求-│ │ │ ├── AppServerPipeReaders.swift stdout 和 stderr 异步读取-│ │ │ ├── CodexStatusService.swift 账号, 额度和用量读取与缓存-│ │ │ ├── CodexStatusViewModel.swift 主面板状态和刷新协调-│ │ │ ├── CodexResetCreditsService.swift 手动重置机会过期时间查询-│ │ │ ├── CodexHookAppServerModels.swift Hook 和配置接口 DTO-│ │ │ └── RequestLog.swift app-server 交互日志模型和内存存储-│ │ ├── KeepAlive/-│ │ │ ├── KeepAliveController.swift 任务驱动的防休眠和 helper 管理-│ │ │ └── SystemSleepService.swift IOKit assertion 和系统休眠请求-│ │ ├── Notifications/-│ │ │ ├── CodexNotificationService.swift 额度, 任务和重置机会通知-│ │ │ └── NotificationSoundOption.swift 通知声音选项和资源映射-│ │ ├── Process/-│ │ │ └── ProcessTermination.swift 子进程退出和强制终止支持-│ │ ├── Settings/-│ │ │ ├── CodexHookSettings.swift Hook 开关, 注册和验证状态-│ │ │ ├── CodexCLINotificationSettings.swift Codex TUI 通知设置-│ │ │ ├── GlobalHotKeySettings.swift 全局快捷键持久化-│ │ │ ├── LoginItemSettings.swift 开机启动设置-│ │ │ ├── MainPanelSettings.swift 主面板任务中心设置-│ │ │ ├── MenuBarQuotaSettings.swift 菜单栏额度窗口设置-│ │ │ ├── NotificationSettings.swift 系统通知, 阈值和声音设置-│ │ │ └── WorkflowSyncSettings.swift 跨设备同步设置和状态-│ │ ├── Support/-│ │ │ └── RefreshTaskCoordinator.swift 刷新任务取消和过期结果丢弃-│ │ ├── Updates/-│ │ │ └── AppUpdater.swift Sparkle 更新状态和操作-│ │ └── Workflow/-│ │ ├── WorkflowHookEventRecorder.swift Hook 子进程入口和事件写入-│ │ ├── HookEventTailReader.swift Hook JSONL 实时增量读取-│ │ ├── CodexSessionLifecycleReader.swift rollout 任务生命周期读取-│ │ ├── CodexActivityMonitor.swift Hook 与 rollout 实时任务合并-│ │ ├── WorkflowService.swift 本地聚合, 维护和手动重建-│ │ ├── WorkflowSyncService.swift CloudKit 上传, 拉取和合并-│ │ ├── WorkflowSyncScheduler.swift 维护, 重建和同步串行调度-│ │ └── JSONLines.swift JSONL 编解码和稳定序列化-│ ├── Views/-│ │ ├── Menu/-│ │ │ ├── CodexStatusMenuView.swift 主面板根视图-│ │ │ ├── CodexStatusMenuSections.swift 账号, 额度, 用量和底部区域-│ │ │ ├── CodexActivityCard.swift 主面板任务卡片-│ │ │ ├── CodexActivityCenterView.swift 任务中心列表-│ │ │ ├── QuotaRow.swift 额度窗口行-│ │ │ ├── ResetCreditsPanelView.swift 重置机会详情-│ │ │ ├── UsageHeatmap.swift Token 热力图-│ │ │ ├── AutoRefreshCountdownView.swift 自动刷新倒计时-│ │ │ ├── TokenCountText.swift Token 数量格式化视图-│ │ │ └── ScreenFrameReader.swift SwiftUI 屏幕坐标读取-│ │ ├── Settings/-│ │ │ ├── AppSettingsView.swift 通用, 高级和关于设置页-│ │ │ ├── CodexVersionSection.swift Codex 路径和版本信息-│ │ │ ├── HotKeyRecorderRow.swift 快捷键录制控件-│ │ │ ├── NotificationOptionsView.swift 通知分类, 阈值和声音选项-│ │ │ ├── SettingsToggleRow.swift 设置开关通用行-│ │ │ └── SettingsIndentedRow.swift 设置缩进行布局-│ │ ├── Log/-│ │ │ └── LogView.swift app-server 交互日志窗口-│ │ └── Shared/-│ │ ├── LiquidGlassStyle.swift Liquid Glass 通用样式-│ │ ├── QuotaPalette.swift 额度颜色映射-│ │ └── PasteboardWriter.swift 剪贴板写入支持-│ └── Resources/ 应用资源文件-├── Shared/-│ └── CodexBarHelperXPC.swift App 与 helper 共用的 XPC 契约-├── CodexBarHelper/-│ ├── main.swift root helper 入口, XPC 和恢复逻辑-│ ├── app.zabrian.codexbar.helper.plist Release LaunchDaemon 配置-│ └── app.zabrian.codexbar.debug.helper.plist Debug LaunchDaemon 配置-├── Docs/-│ ├── UserGuide.md 用户操作和设置说明-│ ├── AppServer.md app-server 通信说明-│ ├── CodexHook.md Hook 和工作流统计说明-│ ├── CrossDeviceSync.md CloudKit 同步说明-│ ├── KeepAlive.md 防休眠和 root helper 说明-│ └── DevelopmentGuide.md 架构, 构建和发布说明-├── Scripts/-│ ├── build.sh Release 构建, 签名和公证-│ ├── dmg.sh DMG 打包-│ ├── appcast.sh Sparkle appcast 生成-│ └── cleanup.swift KeepAlive helper 注销和检查-├── README.md 项目入口文档-├── AGENTS.md 编码代理项目约定-├── CLAUDE.md 代理入口说明-├── .swiftformat SwiftFormat 配置-├── .swiftlint.yml SwiftLint 配置-├── .gitignore Git 忽略规则-├── appcast.xml Sparkle 更新源-└── LICENSE GPL-3.0 许可证-```--## 启动流程--### Hook 模式--`CodexBarApp.init()` 首先调用 `WorkflowHookEventRecorder.handleIfRequested()`; 命令行包含 `--hook-event` 时, 进程读取 stdin, 写入一条本地事件并直接退出, 不进入普通 App 生命周期--### 普通模式--1. `CodexBarApp` 安装自定义 `⌘,` 设置命令-2. `CodexBarAppDelegate` 创建共享服务, 设置对象和 ViewModel-3. `StatusItemController.install()` 创建状态栏入口, 主面板, 快捷键和刷新订阅-4. `CodexNotificationService` 订阅额度和任务变化-5. `CodexActivityMonitor` 启动 Hook 事件尾读和 rollout 生命周期读取-6. `KeepAliveController` 订阅实时任务并刷新 helper 状态--App 退出时依次卸载状态栏入口, 恢复防休眠状态并停止活动监控--## 主要数据流--| 数据 | 来源 | 处理 | 展示或输出 |-| --- | --- | --- | --- |-| 账号, 额度, Token | 本机 Codex app-server | `CodexStatusService` 读取并缓存 | 菜单栏图标, 主面板, 通知 |-| Hook 事件 | Codex 调用当前 App 的 Hook 模式 | 追加本地 JSONL | 实时任务和每日聚合 |-| rollout 生命周期 | `CODEX_HOME/sessions` 与 `archived_sessions` | 增量读取任务起点, 审批, 完成和终止 | 实时任务状态与时长 |-| 每日工作流 | 本地 Hook 事件 | `WorkflowService` 增量维护 | 热力图详情和任务统计 |-| 跨设备聚合 | CloudKit private database | `WorkflowSyncService` 缓存与合并 | 多设备工作流统计 |-| 休眠状态 | 实时运行任务 | Main App assertion + root helper | 系统电源策略 |--app-server 细节见 [Codex app-server](AppServer.md), Hook 与统计见 [Codex Hook 与工作流统计](CodexHook.md), 同步见 [跨设备同步](CrossDeviceSync.md)--## UI 与窗口--### 菜单栏入口--`StatusItemController` 是应用级装配点, 统一管理--- 状态栏图标与 tooltip-- `NSPopover` 主面板-- 无可信状态栏锚点时的 fallback `NSPanel`-- 右键上下文菜单-- 全局 Carbon hot key-- 侧边详情面板-- 设置和日志窗口--左键切换主面板; 右键或 `Control` + 左键打开上下文菜单; 全局快捷键默认 `⌘⇧W`, 打开时优先使用鼠标所在屏幕--### 主面板--主面板使用 SwiftUI, 固定宽度, 按顺序展示账号, 可选任务卡片, 额度, Token/热力图和底部状态; 数据不可用时保留账号状态和任务卡片位置, 并显示统一空状态--`MenuSurfaceDismissMonitor` 处理外部点击, `Esc`, `⌘L`, App 激活变化和 key window 变化; `⌘Space` 会短暂抑制失活关闭, `⌘Tab` 会关闭面板--### 侧边面板--热力图详情, 重置机会, 任务中心和通知选项复用 `SidePanelSupport` 的定位, 父子窗口挂载, 圆角和抽屉动画; 面板优先显示在请求侧, 空间不足时换边, 并限制在当前屏幕可见区域内--### 辅助窗口--设置和日志窗口继承 `HostingWindowController`; `AuxiliaryHostingWindow` 可以成为 key window, 但不会成为 main window; 重新打开时移动到当前 Space, 并按菜单栏所在屏幕或当前屏幕定位--设置窗口包含"通用""高级""关于"三页, 按当前内容高度调整窗口; 超过可用高度时由内部滚动视图承载--## 服务边界--### CodexStatusService--actor 持有一条 app-server stdio 会话, 负责连接复用, 认证刷新, 请求分类和同账号缓存; UI 只接收数据可用, 未登录和初始化失败三类状态--### WorkflowService--actor 负责每日聚合维护, 文件连续性检查, 保留期清理, 手动重建和同步快照合并; Hook 子进程与主 App 通过 `flock` 保护共享状态--### CodexActivityMonitor--MainActor 对象, 合并 Hook JSONL 和 rollout 生命周期, 发布统一任务快照和等待/完成 transition; 通知, 防休眠, 菜单栏状态点和任务中心都消费这份状态--### WorkflowSyncService--actor 使用 CloudKit 私有数据库, 维护设备 ID, zone 游标, 本地缓存, 上传确认 hash 和重建替换状态--### CodexNotificationService--MainActor 服务, 订阅额度快照和任务 transition, 负责通知权限, 阈值, 去重, 提示音, 触觉反馈和通知点击回调--### AppUpdater--封装 Sparkle 更新状态和设置; Feed URL, EdDSA 公钥和检查间隔来自 `Info.plist`; 自动检查间隔为 1 小时--## 并发约定--- App target 使用 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`-- UI, 窗口控制器, 设置对象和 ViewModel 在 MainActor 上运行-- app-server, 聚合, CloudKit 等共享服务使用 actor 串行管理状态-- DTO, 纯模型, 格式化工具和跨 actor 数据根据用途标注 `nonisolated` 或满足 `Sendable`-- 管道读取器和锁封装自行保护非 Sendable 底层对象-- `RefreshTaskCoordinator` 和各类 generation 标记用于取消旧任务并丢弃过期结果-- 工作流维护, 同步和手动重建由 `WorkflowSyncScheduler` 串行调度-- 长时间文件和进程操作不应阻塞 MainActor--## 本地数据与设置--主要文件位置--| 路径 | 内容 |-| --- | --- |-| `${CODEX_HOME}/auth.json` | Codex 认证文件, 只用于本机手动重置机会查询 |-| `${CODEX_HOME}/hooks.json` | Codex Hook 配置 |-| `${CODEX_HOME}/sessions/` | Codex rollout 会话文件, 只增量读取生命周期字段 |-| `~/Library/Application Support/CodexBar/HookEvents/` | Hook 原始事件, 每日聚合和同步缓存 |-| `/Library/Application Support/CodexBar/` | root helper 恢复哨兵 |--用户设置通过 `UserDefaults`, `SMAppService`, Sparkle 和 Codex app-server 分别持久化; 修改设置 key 时需要保留缺省值和已有数据的兼容读取--主要缺省值--| 设置 | 默认值 |-| --- | --- |-| 全局快捷键 | `⌘⇧W` |-| 菜单栏额度指示 | 开启, 主额度窗口 |-| 主面板任务中心 | 开启 |-| 防休眠最长时限 | 12 小时 |-| 低额度阈值 | 10% |-| 长任务通知阈值 | 60 秒 |-| 跨设备同步 | 关闭 |--## 网络范围--除本机 app-server 通信外, 主 App 只在以下场景访问网络--- 查询手动重置机会过期时间-- Sparkle 更新检查和下载-- 用户开启跨设备同步后的 CloudKit private database 请求--root helper 不执行网络请求--## 构建与检查--日常编译--```bash-xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/platform=macOS' build-```--也可以直接用 Xcode 打开 `CodexBar.xcodeproj`--当前工程没有独立测试 target; 修改后至少完成一次构建, 并按影响范围手动检查--- 菜单栏左键, 右键和全局快捷键-- popover 与 fallback panel 的屏幕和焦点行为-- `⌘,`, `⌘L`, 设置和日志窗口-- Hook 注册, 验证, 事件写入和任务状态-- CloudKit 开关, 同步状态和多设备合并-- 防休眠授权, 运行/等待切换, 上限和异常恢复--SwiftLint 配置位于 `.swiftlint.yml`, 检查范围为 `CodexBar/`--## 发布脚本--### 构建与公证--```bash-Scripts/build.sh --notary-profile <profile>-```--脚本执行 Release archive, Developer ID 导出, 签名验证, 公证, staple 和 Gatekeeper 校验; 默认清理 `build/`, 成功后只保留最终 `.app`; 没有发布凭据时可用 `--skip-notarization`, 但产物不是完整发布包--### DMG--```bash-Scripts/dmg.sh [App.app] [Output.dmg]-```--脚本复制 App, 创建 Applications 别名, 写入 Finder 布局, 并输出压缩 DMG; 默认文件名包含 `MARKETING_VERSION`--### Sparkle appcast--```bash-Scripts/appcast.sh [CodexBar-vX.Y.Z.dmg]-```--脚本读取 `MARKETING_VERSION` 和 `CURRENT_PROJECT_VERSION`, 调用 Sparkle `sign_update`, 在 `appcast.xml` 顶部写入当前版本条目, 并校验 XML; 默认下载地址和发布说明地址来自脚本环境变量--### Helper 清理--```bash-Scripts/cleanup.swift [options]-```--脚本只注销 CodexBar Debug 和 Release KeepAlive LaunchDaemon, 并关闭对应防休眠偏好; 运行前需要退出所有 CodexBar 实例--## 发布检查--发布包至少确认--1. 主 App, helper 和 Sparkle framework 签名有效-2. App 包内 helper 与 LaunchDaemon plist 路径正确-3. `Info.plist` 的 Sparkle feed 和公钥有效-4. CloudKit entitlement 使用 `iCloud.app.zabrian.codexbar`-5. DMG 可挂载并可将 App 拖入 `/Applications`-6. appcast 的版本, build, 下载地址, 文件长度和 EdDSA 签名匹配产物diff --git a/Docs/KeepAlive.md b/Docs/KeepAlive.mddeleted file mode 100644index bbee136..0000000--- a/Docs/KeepAlive.md+++ /dev/null@@ -1,149 +0,0 @@-# 阻止系统休眠--"阻止系统休眠"根据 Codex Hook 的实时任务状态临时保持 Mac 唤醒; 功能关闭或没有运行任务时, CodexBar 不修改系统休眠策略--## 生效条件--以下条件必须同时满足--- CodexBar 正在运行-- CodexBar Hook 已开启-- 用户已开启"阻止系统休眠"-- 至少有一个 Codex 任务处于运行状态-- CodexBarHelper 已注册并获得系统授权-- 当前连续防休眠时限尚未到达--任务等待用户批准时不属于运行状态; 如果同时还有其他任务运行, 防休眠继续生效; 否则立即恢复系统休眠--## 最长时限--可选时限为--- 1 小时-- 2 小时-- 4 小时-- 8 小时-- 12 小时-- 24 小时-- 无限制--默认值为 12 小时; 以下事件会重新开始计时--- 新任务进入运行状态-- 等待批准的任务恢复运行--普通工具, 压缩和子 Agent 活动不会延长时限; 到达上限后, 即使任务仍在运行, 也会恢复系统休眠; 后续新任务或等待批准后恢复运行可以开始新的计时周期--## 系统休眠控制--功能生效时, 主 App 同时执行两项操作--1. 创建 `PreventUserIdleSystemSleep` IOKit assertion, 阻止空闲系统休眠-2. 通过 root helper 执行 `/usr/bin/pmset -a disablesleep 1`--恢复时按相反顺序处理--1. helper 将 `SleepDisabled` 恢复为功能生效前的值-2. 主 App 释放 IOKit assertion-3. 如果 MacBook 当前合盖, 系统配置认为合盖应休眠, 且原始 `SleepDisabled` 为关闭状态, 主 App 主动请求一次系统休眠--如果系统在 CodexBar 介入前已经禁用休眠, 恢复时会保留该状态--## Helper 注册--CodexBar 使用 `SMAppService.daemon` 注册随 App 打包的 LaunchDaemon; 首次开启时, macOS 可能要求用户在"系统设置 → 通用 → 登录项与扩展"中允许 CodexBar 后台项目--Release 标识--```text-App: app.zabrian.codexbar-Helper: app.zabrian.codexbar.helper-```--Debug 标识--```text-App: app.zabrian.codexbar.debug-Helper: app.zabrian.codexbar.debug.helper-```--App 包内文件位置--```text-Contents/Resources/CodexBarHelper-Contents/Library/LaunchDaemons/<helper bundle id>.plist-```--CodexBar 会对 helper 可执行文件和 plist 计算指纹; App 更新后指纹变化时, 已注册服务会注销并重新注册, 确保 launchd 使用当前版本--## XPC 边界--主 App 通过 privileged XPC Mach service 调用唯一接口--```swift-setSleepDisabled(_ disabled: Bool, reply: (Int32, Bool) -> Void)-```--helper 只允许与自身相同 Team ID, 且 bundle identifier 为对应 CodexBar App 的已签名客户端连接--helper 的权限范围仅包括--- 读取当前 `SleepDisabled`-- 执行 `/usr/bin/pmset -a disablesleep 0|1`-- 在固定目录维护一份恢复哨兵-- 接受上述 XPC 开关请求--helper 不提供网络, 任意命令执行或任意文件访问接口--## 恢复哨兵--helper 在修改系统设置前, 将原始 `SleepDisabled` 写入--```text-/Library/Application Support/CodexBar/<helper bundle id>.state-```--文件内容只能是 `0` 或 `1`; 目录要求由 root 所有且不可由 group 或 other 写入; 哨兵文件权限设置为 `0600`--恢复成功后删除哨兵; 以下路径都会尝试恢复--- 主 App 主动请求-- 最后一个 XPC 连接断开 15 秒后-- helper 启动时发现遗留哨兵-- 无连接时每 60 秒检查一次-- helper 收到 `SIGTERM` 或 `SIGINT`--哨兵损坏或不可读时, helper 按允许休眠恢复, 避免把 `SleepDisabled=1` 长期留在系统中; 哨兵损坏时不会继续执行新的禁用休眠操作--## 故障处理--主 App 在休眠切换失败后重新建立 XPC 连接并按递增间隔重试, 累计约 8.5 分钟后停止; 重新出现任务状态变化或用户操作后, 可以启动新的切换流程--设置页可能显示--- 需要后台项目授权-- helper 未注册或资源缺失-- IOKit assertion 创建或释放失败-- XPC 连接失败-- `pmset` 执行失败-- 已达到最长防休眠时限--## 开发与验证--日常构建会把 helper 和对应配置的 LaunchDaemon plist 嵌入 App; 修改相关代码后至少检查--1. App 包内 helper 和 plist 路径正确-2. App, helper 和 XPC 客户端签名匹配-3. 首次开启可以完成后台项目授权-4. 运行任务时 `pmset -g` 显示 `SleepDisabled 1`-5. 等待批准, 任务完成, 关闭 Hook, 关闭功能和达到时限后恢复原值-6. App 或 XPC 异常退出后, watchdog 或定时检查能够恢复-7. Debug 和 Release helper 不互相注册--只需要注销 CodexBar 的 KeepAlive LaunchDaemon 时, 可在退出所有 CodexBar 实例后运行--```bash-Scripts/cleanup.swift-```--使用 `--dry-run` 查看目标, 使用 `--check` 只验证临时清理 App 和签名, 不执行注销diff --git a/Docs/UserGuide.md b/Docs/UserGuide.mddeleted file mode 100644index f34bdb1..0000000--- a/Docs/UserGuide.md+++ /dev/null@@ -1,208 +0,0 @@-# CodexBar 使用指南--CodexBar 常驻 macOS 菜单栏, 不显示 Dock 图标; 启动后, 菜单栏人物图标是应用的主要入口--## 快速开始--1. 确认本机已安装并登录 Codex CLI, ChatGPT App 或 Codex App-2. 启动 CodexBar, 左键点击菜单栏图标查看账号, 额度和 Token 用量-3. 右键点击图标打开设置, 根据需要开启 Codex Hook, 通知, 阻止系统休眠和跨设备同步--应用要求 macOS 15.0 或更高版本--## 常用操作--| 操作 | 结果 |-| --- | --- |-| 左键点击菜单栏图标 | 打开或关闭主面板 |-| 右键或 `Control` + 左键点击菜单栏图标 | 打开设置, 日志和退出菜单 |-| 默认全局快捷键 `⌘⇧W` | 打开或关闭主面板 |-| `⌘,` | 打开设置窗口 |-| 主面板打开时按 `⌘L` | 打开 app-server 日志窗口 |-| 双击账号图标 | 立即刷新数据 |-| 双击账号邮箱 | 模糊或恢复邮箱显示 |-| 点击任务卡片 | 打开或关闭任务中心 |-| 点击"重置次数" | 查看手动重置机会的过期时间 |-| 悬停热力图日期 | 查看当天详细数据 |--点击主面板和侧边面板以外的区域, 或按 `Esc`, 会关闭主面板--## 菜单栏图标--人物图标表示账号状态--- 带对勾: 账号数据可用-- 带叉: 未登录, 初始化失败或当前数据不可用--开启"菜单栏额度指示"后, 图标左侧显示所选额度窗口的剩余比例; 颜色按剩余额度分档--| 剩余额度 | 颜色 |-| --- | --- |-| 80% 及以上 | 绿色 |-| 60%–79% | 蓝色 |-| 40%–59% | 黄色 |-| 20%–39% | 橙色 |-| 低于 20% | 红色 |--开启 Codex Hook 后, 图标右下角可显示任务状态: 橙色表示等待批准, 蓝色表示运行中, 绿色表示刚刚完成; 多个状态同时存在时, 等待批准优先于运行中, 运行中优先于刚完成--将鼠标停在图标上, 可以查看账号异常, 任务状态, 任务时长和所选额度窗口的摘要--## 主面板--### 账号与刷新--账号卡片显示账号邮箱或名称, 订阅类型和刷新状态; CodexBar 默认每 60 秒刷新一次账号, 额度和 Token 用量; 底部圆环显示下一次刷新进度--状态含义--- "未登录": 当前 Codex 没有可用登录账号-- "初始化失败": 无法找到, 启动或连接本机 Codex app-server-- "暂无数据": 账号有效, 但当前没有额度或用量数据-- 内容变淡: 当前显示的是前一次成功读取的缓存数据--### 额度与重置机会--每个额度窗口显示名称, 剩余比例和重置时间; 一个账号可以同时返回多个额度限制和多个时间窗口--账号存在可用的手动重置机会时, 额度区会显示"重置次数"; 侧边面板按过期时间汇总这些机会; 查询不到过期时间时仍保留可用次数; CodexBar 只展示信息, 不执行重置操作--### Token 用量--用量区显示--- 全时累计 Token-- 单日峰值-- 当前连续使用天数-- 最长连续使用天数-- 最长任务时长-- 近 30 周日历热力图--热力图颜色深浅按当前可见范围内的 Token 峰值计算; 开启 Codex Hook 后, 日期详情还会显示会话, 轮次, 工具调用, 权限请求, 上下文压缩, 子 Agent 和常用模型等工作流统计--### 任务卡片与任务中心--任务卡片需要同时开启"CodexBar Hook"和"主面板任务中心"; 卡片显示当前最重要的任务状态, 以及项目, 模型, 推理强度, 工具, 时长和子 Agent 数量等可用信息--点击卡片打开任务中心, 可查看--- 等待确认的任务-- 正在运行的任务-- 最近 10 分钟内完成的任务-- 最近 10 分钟内终止的任务--只有 Codex 将审批明确路由给用户时, 任务才显示为等待批准; 自动审核和 guardian subagent 审批不会进入用户等待状态--### 底部状态--底部显示数据更新时间, 自动刷新倒计时, 同步状态和可用更新; 悬停 iCloud 图标可查看同步说明; 双击更新提示可开始安装更新--## 设置--### 通用--- 开机自动启动-- 自动检查更新-- 菜单栏额度指示及额度窗口选择-- 全局快捷键--全局快捷键默认是 `⌘⇧W`; 录制快捷键需要至少两个修饰键; `⌘Space` 和 `⌘Tab` 不可使用; 要更换已有快捷键, 先清除, 再录制新组合--### 高级--#### CodexBar Hook--开启后, CodexBar 在当前 `CODEX_HOME` 的 `hooks.json` 中注册十类工作流事件, 并通过 app-server 验证和维护对应信任状态; 关闭时只移除属于当前 CodexBar 可执行文件的配置, 不修改其他 Hook--Hook 提供实时任务, 任务中心, 工作流统计, 任务通知, 阻止系统休眠和跨设备同步所需的数据; 详细说明见 [Codex Hook 与工作流统计](CodexHook.md)--#### 系统通知--首次开启时需要允许 macOS 通知权限; 通知选项包括--- 任务完成: 任务达到 30 秒, 1 分钟, 2 分钟或 5 分钟后提醒-- 任务等待: 任务等待用户批准时提醒-- 额度预警: 剩余额度到达 5%, 10% 或 25% 时提醒-- 额度重置: 已消耗的额度窗口恢复为 0% 使用量时提醒-- 重置临期: 手动重置机会过期前 7 天至 1 天每天提醒一次-- 任务触觉反馈-- Codex TUI 通知开关--每类系统通知都可以单独选择默认声音, 静音或随应用提供的提示音; 点击通知会打开 CodexBar 主面板--#### 阻止系统休眠--该功能依赖 Codex Hook 和 macOS 后台项目授权; 只有存在运行中的任务时才阻止休眠; 任务等待批准, 全部结束, Hook 关闭, 功能关闭或达到最长时限后会恢复原系统设置--最长时限可选 1, 2, 4, 8, 12, 24 小时或无限制, 默认 12 小时; 新任务开始或等待批准后恢复运行时重新计时--首次开启后如果显示"需要授权允许 CodexBar 后台运行", 点击"打开系统设置", 在"登录项与扩展"中允许 CodexBar; 详细说明见 [阻止系统休眠](KeepAlive.md)--#### 跨设备同步--跨设备同步要求--- CodexBar Hook 已开启-- 已开启"跨设备同步"-- 当前 iCloud 账号可用--同步使用应用的 CloudKit 私有数据库, 只上传每日聚合; 开启后会补传本机保留范围内尚未确认的聚合数据; 详细说明见 [跨设备同步](CrossDeviceSync.md)--#### 重建数据--"重建数据"从本机原始 Hook 事件重新生成所选日期的每日统计; 日期范围限制在最近 210 天, 实际只处理存在非空事件文件的日期--如果跨设备同步已开启, 重建后的当前设备聚合会在后续同步中替换对应日期的旧云端记录; 其他设备的数据不受影响--### 关于--"关于"页显示--- 全局 Codex CLI 与 App 内置 Codex 的版本和路径-- 当前 app-server 实际使用的 Codex-- CodexBar 版本和更新状态-- 检查更新与退出操作--点击 Codex 路径可以复制完整路径--## 日志--日志窗口记录本次运行期间最近 500 条 app-server 请求, 响应和错误; 列表可以展开, 完整内容支持 JSON 格式化预览和复制; 点击"清空"只清除内存中的交互日志--日志不包含 Hook 原始事件, 也不会上传到 CloudKit--## 常见问题--### 显示"未登录"--在 Codex CLI 或 Codex App 中完成登录, 然后双击账号图标刷新--### 显示"初始化失败"--打开设置的"关于"页, 确认至少存在一个可用 Codex 路径, 并在日志中查看 `initialize` 或 `account/read` 错误--### Hook 开启失败--确认当前 `CODEX_HOME` 可写, `hooks.json` 是有效 JSON, 且 Codex 配置没有全局关闭 Hook; 设置页会显示验证结果--### 同步不可用--确认系统已登录 iCloud, CloudKit 账号可用且 CodexBar Hook 已开启; 同步错误会显示在主面板底部 iCloud 图标的说明中--### 阻止系统休眠未生效--确认 Hook 已开启, 当前确实有运行中的任务, 最长时限未到, 并在系统设置中允许 CodexBar 后台项目--### 菜单栏没有额度条--确认"菜单栏额度指示"已开启, 且所选额度窗口当前有数据; 主面板可同时显示多个窗口, 菜单栏只显示选中的一个--## 数据范围--账号, 额度, Token 用量和认证文件只在本机处理; Hook 原始事件和每日聚合默认保存在--```text-~/Library/Application Support/CodexBar/HookEvents/-```--跨设备同步只上传每日统计字段, 不上传原始事件, 会话 ID, 轮次 ID, 请求日志或认证文件diff --git a/Images/icon.png b/Images/icon.pngnew file mode 100644index 0000000..caf129bBinary files /dev/null and b/Images/icon.png differdiff --git a/README.md b/README.mdindex f033fea..ac61551 100644--- a/README.md+++ b/README.md@@ -1,85 +1,197 @@+<div align="center">++<img src="Images/icon.png" width="128" alt="CodexBar">+# CodexBar-CodexBar 是一款 macOS 菜单栏应用, 用于查看本机 Codex 账号, 额度, Token 用量和任务状态; 应用不显示 Dock 图标, 主要数据通过本机 Codex app-server 获取+**在 macOS 菜单栏一眼看清 Codex 的账号; 额度; 用量与实时任务**-<p align="center">- <img src="Images/preview.gif" width="600" alt="CodexBar 预览">-</p>+[](https://www.apple.com/macos/)+[](https://swift.org)+[](https://github.com/bob-zebedy/CodexBar/releases)+[](https://github.com/bob-zebedy/CodexBar/releases)+[](LICENSE)-## 功能+[安装](#安装) | [使用](#使用) | [隐私](#隐私) | [实现](#实现)-- 查看账号, 订阅类型, 额度窗口, 剩余比例和重置时间-- 查看手动重置机会及其过期时间-- 查看 Token 摘要和近 30 周用量热力图-- 通过可选 Codex Hook 展示运行中, 等待批准, 最近完成和最近终止的任务-- 按天统计会话, 轮次, 工具调用, 权限请求, 上下文压缩, 子 Agent 和常用模型-- 提供额度, 任务和重置机会通知, 可分别选择通知声音-- 在 Codex 任务运行时按需阻止系统休眠-- 通过 iCloud 私有数据库同步脱敏的每日工作流聚合-- 支持菜单栏额度指示, 全局快捷键, 开机启动, 交互日志和 Sparkle 更新+<img src="Images/preview.gif" width="640" alt="CodexBar 预览">-## 运行要求+</div>-- macOS 15.0 或更高版本-- 已安装并登录 [Codex CLI](https://github.com/openai/codex), ChatGPT App 或 Codex App+---++CodexBar 把 Codex 的运行状态收进菜单栏: 剩余额度; 下次重置时间; 当日 Token 用量, 以及当前任务是在运行还是在等待批准++应用以 `LSUIElement` 方式运行, 没有 Dock 图标; 数据全部在本机采集与聚合, 对外通信仅有四项, 详见[隐私](#隐私)++## 特性++其中实时任务; 工作流统计与防休眠依赖 CodexBar Hook, 开启方式见[关于 Hook](#关于-hook)++### 额度与用量++- 分时间窗口展示剩余额度; 重置时间与可用的手动重置次数+- 菜单栏可常驻显示主要或次要窗口的额度百分比, 无需展开面板+- 30 周日历热力图呈现每日 Token 用量, 点击任意一格展开当天明细+- 账号有效时额度与用量允许单独失败, 失败项沿用同账号缓存并标记为陈旧++### 实时任务++- 开启 CodexBar Hook 后, 菜单栏图标随任务状态实时变化+- 任务中心区分运行中; 等待批准; 最近完成; 已终止四种状态+- 状态同时取自 Hook 事件流与 `~/.codex/sessions` 下的 rollout 记录, 前者覆盖工具调用与批准请求, 后者补齐对话轮次的起止-CodexBar 优先使用 `PATH` 中的全局 `codex`, 找不到时依次检查 ChatGPT App 和 Codex App 内置的 Codex 可执行文件+### 工作流统计++- 按天聚合会话; 对话轮次; 工具调用; 权限请求; 上下文压缩; 子 Agent 等指标+- 原始事件与每日聚合保留 210 天, 可按日期区间从原始事件重新统计+- 可选开启 iCloud 同步, 汇总多台 Mac 的数据++### 防休眠++- 仅在任务运行期间阻止空闲休眠与合盖休眠, 任务结束即恢复+- 最长时长可选 1; 2; 4; 8; 12; 24 小时或无限制, 默认 12 小时+- 等待批准; 任务结束与时长到期都会还原系统原有设置, 交由 macOS 重新判断++### 通知与提醒++- 五类本地通知: 额度告急; 额度重置; 任务等待批准; 长任务完成; 重置机会即将过期+- 告急百分比与长任务时长阈值可调, 每类通知的音效独立可选+- 阈值穿越带去重判定, 同一事件不会重复提醒; 任务状态变化另有触觉反馈+- 可直接读写 Codex CLI 自身的通知配置, 无需手动编辑 `config.toml`++### 系统集成++- 全局快捷键唤起 (默认 `⌘⇧W`, 可自定义); 开机自启; Sparkle 自动更新+- 内置日志窗口保留最近 500 条请求记录, 连接失败与解析异常均可追溯+- 界面风格贴近系统菜单栏工具, 不作额外装饰## 安装-使用 Homebrew+推荐通过 Homebrew 安装```bashbrew install --cask bob-zebedy/tap/codexbar```-也可以从 [Releases](https://github.com/bob-zebedy/CodexBar/releases) 下载 DMG, 并将 `CodexBar.app` 拖入 `/Applications`+也可以从 [Releases](https://github.com/bob-zebedy/CodexBar/releases) 下载 DMG, 将 `CodexBar.app` 拖入 `/Applications`++运行要求++- macOS 15.0 或更高版本+- 已安装并登录 [Codex CLI](https://github.com/openai/codex), 或安装了内置 Codex 的 ChatGPT App++> [!TIP]+> CodexBar 优先使用 PATH 中的 `codex`, 找不到时回退到 `ChatGPT.app` 或 `Codex.app` 的内置版本-## 基本使用+## 使用-- 左键点击菜单栏图标: 打开或关闭主面板-- 右键或 `Control` + 左键点击: 打开设置, 日志和退出菜单-- 全局快捷键: 默认 `⌘⇧W`-- 打开设置: `⌘,`-- 主面板打开时打开日志: `⌘L`+| 操作 | 效果 |+| ------------------- | ------------------------------ |+| 左键点击菜单栏图标 | 打开主面板 |+| 右键或 Control 点击 | 打开上下文菜单 |+| `⌘⇧W` | 全局唤起主面板, 可在设置中改键 |+| `⌘,` | 打开设置窗口 |+| `⌘L` | 主面板打开时, 打开日志窗口 |-完整说明见 [使用指南](Docs/UserGuide.md)+### 关于 Hook-## 数据与隐私+实时任务; 工作流统计与防休眠都依赖 CodexBar Hook, 在设置中开启即可写入 `~/.codex/hooks.json`-账号, 额度和 Token 用量由本机 Codex app-server 返回; Hook 原始事件默认只保存在本机+> [!NOTE]+> 写入只追加 CodexBar 自身的 handler, 关闭时也只移除这一条; 已有的 Hook 与其他工具注册的 Hook 原样保留-```text-~/Library/Application Support/CodexBar/HookEvents/+### 关于防休眠++覆盖合盖休眠需要一个 root LaunchDaemon 执行 `pmset`, 因此首次开启时 macOS 会要求授权后台项目; 该功能同样依赖 Hook, 关闭 Hook 会将其一并关闭并置灰++> [!WARNING]+> 合盖状态下持续运行任务会明显增加耗电与发热, 请保证 Mac 通风良好, 不要在密闭背包内使用++## 隐私++CodexBar 的对外通信只有以下四项, 其中真正经过网络的是后三项++| 行为 | 说明 |+| ------------------------------ | ------------------------------------------ |+| 与本机 `codex app-server` 通信 | 经由管道, 不经过网络 |+| 查询额度重置机会的过期时间 | 只读请求, 全仓库唯一的 `URLSession` 调用点 |+| Sparkle 更新检查 | 拉取 appcast |+| CloudKit 同步 | 仅在显式开启后进行 |++账号; 额度; Token 用量与原始 Hook 事件都不会离开本机; 跨设备同步只上传去掉会话与轮次标识的每日聚合; Codex 的 OAuth token 与 `auth.json` 内容既不展示也不记录++## 实现++Swift 6 + SwiftUI + AppKit, MVVM, 唯一的外部依赖是 Sparkle++工程开启了 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`, 所有类型默认 MainActor 隔离; 共享状态收敛进 actor, 跨进程写统计文件由 `flock` 保护++三条数据链路各自独立++```mermaid+flowchart LR+ subgraph L1["额度与用量"]+ AS["codex app-server"] -->|"stdio JSON-RPC"| SS["CodexStatusService"]+ SS --> VM["CodexStatusViewModel"]+ end++ subgraph L2["历史统计"]+ HK["Hook 子进程"] -->|"JSONL"| WS["WorkflowService"]+ WS -->|"增量聚合"| DA["daily.jsonl"]+ end++ subgraph L3["实时任务"]+ EV["Hook 事件流"] --> AM["CodexActivityMonitor"]+ RO["sessions rollout"] --> AM+ end++ VM --> UI["菜单面板"]+ DA --> UI+ AM --> UI+ AM --> NT["通知与触觉反馈"]+ AM --> KA["防休眠"]```-跨设备同步关闭时, 工作流数据不会上传; 开启后只同步每日聚合, 不上传原始事件, 会话 ID, 轮次 ID, app-server 日志或 Codex 认证文件+<details>+<summary><b>两处关键设计</b></summary>++<br>++**Hook 子进程模式**++App 二进制带 `--hook-event` 启动时不初始化任何 UI, 只从 stdin 读一行 JSON, 在文件锁内追加到当日 JSONL 后立即退出-应用自身的网络访问仅用于+写入失败一律静默返回, 任何情况下都不阻断也不拖慢 Codex-- 查询手动重置机会的过期时间-- Sparkle 更新检查与下载-- 用户开启后的 CloudKit 私有数据库同步+**root helper 的最小权限**-## 开发+`CodexBarHelper` 是随 App 嵌入的 LaunchDaemon, 只暴露一个 XPC 方法, 只执行 `pmset -a disablesleep`; 没有网络访问, 没有命令执行, 也没有其他文件读写能力-使用 Xcode 打开 `CodexBar.xcodeproj`, 或运行+调用方由代码签名强制校验: helper 启动时读取自身签名拼出 requirement 交给 XPC listener, 修改签名或 bundle ID 都会导致连接被拒++此外还有磁盘哨兵与 watchdog 兜底, 确保 App 异常退出后休眠设置仍能还原++</details>++## 从源码构建```bash+git clone https://github.com/bob-zebedy/CodexBar.git+cd CodexBarxcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/platform=macOS' build```-工程结构, 构建和发布说明见 [开发指南](Docs/DevelopmentGuide.md)+也可以直接 `open CodexBar.xcodeproj` 在 Xcode 中运行 Debug scheme; Debug 产物的 bundle ID 为 `app.zabrian.codexbar.debug`, 与 Release 安装版可以共存++格式化与静态检查使用 `swiftformat` 和 `swiftlint`, 配置位于仓库根目录++`Scripts/` 下是归档; 公证; DMG 打包与 appcast 签名等发布脚本, 它们需要 Developer ID 凭据, 不适合用于日常验证-## 文档+## 反馈-- [使用指南](Docs/UserGuide.md)-- [Codex app-server](Docs/AppServer.md)-- [Codex Hook 与工作流统计](Docs/CodexHook.md)-- [跨设备同步](Docs/CrossDeviceSync.md)-- [阻止系统休眠](Docs/KeepAlive.md)-- [开发指南](Docs/DevelopmentGuide.md)+Bug; 功能建议与使用问题都欢迎通过 [Issues](https://github.com/bob-zebedy/CodexBar/issues) 反馈, 仓库已备好对应模板## 许可证-本项目采用 [GNU General Public License v3.0](LICENSE)+[GNU General Public License v3.0](LICENSE)diff --git a/appcast.xml b/appcast.xmlindex 67a51b7..76075ae 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.3</title>+ <sparkle:version>57</sparkle:version>+ <sparkle:shortVersionString>3.5.3</sparkle:shortVersionString>+ <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>+ <sparkle:releaseNotesLink>https://codexbar.zabrian.app/notes#3.5.3</sparkle:releaseNotesLink>+ <pubDate>Sun, 26 Jul 2026 12:41:46 +0800</pubDate>+ <enclosure url="https://codexbar.zabrian.app/download/CodexBar-v3.5.3.dmg" sparkle:edSignature="UvbfP+3O+lrBf3dRWJ2ghCcz1+LVSxGTZQf0Sr3qidbgmhH5Ho7UFUNijSTG+uXmTVc7L9DhNzg6sopc3YCHBg==" length="5865018" type="application/octet-stream"/>+ </item><item><title>CodexBar.app 3.5.2</title><sparkle:version>56</sparkle:version>