CodexBar 是一个 macOS 菜单栏应用,用于查看本机 Codex 账号状态、额度、Token 用量、详细统计信息
Swift appkitcodexcodex-clideveloper-toolsmacosmacos-appmenu-bar-appopenai-codexproductivityswiftswiftuiusage-tracker
docs: 重构项目文档结构
Bobcc05cd14261a
diff --git a/Docs/DeveloperGuide/README.md b/Docs/DeveloperGuide/README.mdnew file mode 100644index 0000000..8354571--- /dev/null+++ b/Docs/DeveloperGuide/README.md@@ -0,0 +1,53 @@+# CodexBar 开发者指南++本指南面向希望理解 CodexBar 架构,调试数据链路或参与开发的开发者。++内容覆盖 CodexBar 的架构,数据链路,核心状态机和系统集成。产品功能和操作方式见 [用户指南](../UserGuide/README.md)++## 阅读路线++第一次了解项目时,建议按以下顺序阅读:++1. [整体架构](architecture.md)+2. [app-server 数据链路](app-server.md)+3. [Hook 采集与历史聚合](hook-and-aggregation.md)+4. [实时任务监控](activity-monitor.md)+5. [防睡眠系统](sleep-prevention.md)+6. [CloudKit 同步](sync.md)++## 按职责查找++| 文档 | 内容 |+| --- | --- |+| [整体架构](architecture.md) | 进程,模块,生命周期,actor 边界和 3 条数据链路 |+| [app-server 数据链路](app-server.md) | CLI 定位,JSON-RPC 会话,账户,额度和用量刷新 |+| [Hook 采集与历史聚合](hook-and-aggregation.md) | Hook 安装,事件落盘,聚合,保留期和 schema 演进 |+| [实时任务监控](activity-monitor.md) | 增量读取,rollout 对账,状态机和异常会话保护 |+| [防睡眠系统](sleep-prevention.md) | IOKit assertion,CodexBarHelper,XPC 租约和恢复策略 |+| [CloudKit 同步](sync.md) | 私有数据库,设备匿名化,上传,合并和重建 |+| [通知系统](notifications.md) | 通知触发,去重,声音,触觉和点击行为 |+| [UI 与应用生命周期](ui-and-lifecycle.md) | 菜单栏,面板,焦点,全局快捷键和服务装配 |+| [数据与隐私边界](data-and-privacy.md) | 本地文件,网络访问,云端字段和日志边界 |+| [开发与验证](development.md) | 工程结构,构建检查,调试和变更验收 |++## 核心设计约束++- 启动时必须先处理 `--hook-event` 模式,该模式不能初始化 UI+- app-server 额度与用量,Hook 历史聚合,实时任务监控是 3 条独立数据链路+- `CodexActivityMonitor` 是任务状态的唯一来源+- UI,Controller,ViewModel 和 Settings 默认在 `MainActor` 上运行+- 阻塞 I/O 和共享可变状态必须离开主 actor+- CodexBarHelper 只负责睡眠控制,不增加网络,任意命令执行或额外文件访问+- Hook 配置修改必须保留用户和其他应用已有的 handler+- 聚合语义变化必须递增聚合 schema,并从原始事件完整重建+- 缺失的 Hook 计数字段表示历史来源不可用,不能解释为明确的 `0`++## 主要入口++- App 启动入口:[`CodexBarApp.swift`](../../CodexBar/App/CodexBarApp.swift)+- 服务装配入口:[`StatusItemController.swift`](../../CodexBar/Controllers/StatusItemController.swift)+- app-server 服务:[`CodexStatusService.swift`](../../CodexBar/Services/CodexStatus/CodexStatusService.swift)+- Hook 子进程入口:[`WorkflowHookEventRecorder.swift`](../../CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift)+- 实时任务状态机:[`CodexActivityMonitor.swift`](../../CodexBar/Services/Workflow/CodexActivityMonitor.swift)+- 防睡眠编排:[`KeepAliveController.swift`](../../CodexBar/Services/KeepAlive/KeepAliveController.swift)+- CodexBarHelper: [`main.swift`](../../CodexBarHelper/main.swift)diff --git a/Docs/DeveloperGuide/activity-monitor.md b/Docs/DeveloperGuide/activity-monitor.mdnew file mode 100644index 0000000..7407b97--- /dev/null+++ b/Docs/DeveloperGuide/activity-monitor.md@@ -0,0 +1,195 @@+# 实时任务监控++## 目标++实时任务链路需要回答 4 个问题:++- 当前是否有任务正在运行+- 当前是否在等待用户批准+- 最近任务是完成还是中断+- 哪些运行任务已经长时间没有进展++Hook 事件提供低延迟信号,rollout 文件提供权威生命周期补充。[`CodexActivityMonitor.swift`](../../CodexBar/Services/Workflow/CodexActivityMonitor.swift) 合并两者并发布唯一任务快照:++```text+Hook JSONL -> HookEventTailReader -----++ +-> CodexActivityMonitor -> ActivitySnapshot+rollout JSONL -> SessionLifecycleReader++```++## HookEventTailReader++[`HookEventTailReader.swift`](../../CodexBar/Services/Workflow/HookEventTailReader.swift) 是 actor,默认每 2 秒检查 Hook 事件文件。++### Bootstrap++首次启动读取最近 24 小时文件以建立任务基线:++- 每块最多读取 512 KB+- 最多尝试 3 次获得稳定文件边界+- 使用 inode 和 size 判断读取期间是否发生替换或追加+- bootstrap 结果不会触发历史完成或等待通知++如果无法得到稳定边界,reader 会跳到当前文件末尾并发布显式不健康状态。这样不会把不完整历史误解释为真实任务变化。++### 跨日与文件替换++正常跨日时先排空旧日期文件,再切换到新日期文件。inode 改变或文件缩小时重新 bootstrap,不沿用旧游标。++当 `UserPromptSubmit` 早于当前增量窗口时,reader 可以向前回查最多 8 MB,为现存任务补齐 prompt 起点。++### drainNow 读取屏障++`drainNow()` 不是普通的立即刷新提示。每个调用方必须等待一轮在本次请求之后开始的读取:++```text+调用 drainNow+ -> 记录请求代际+ -> 等待下一轮新读取开始+ -> 等待该轮读取完成+ -> 返回该轮结果+```++调用发生前已经在执行的读取不能满足屏障。reader 被替换,数据源不可用或任务取消时,调用方不能使用旧快照继续判定。++## Rollout 生命周期读取++[`CodexSessionLifecycleReader.swift`](../../CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift) 读取 `$CODEX_HOME/sessions` 和 `$CODEX_HOME/archived_sessions`++读取规则如下:++- 默认每 1 秒检查一次+- 初始尾部窗口为 512 KB+- effort 等 turn context 字段最多回查 8 MB+- 只解析生命周期,turn,progress,effort 和 reviewer+- 不读取或保存对话内容用于产品展示++Hook 的 `Stop` 只是完成候选。rollout 中的 terminal 状态用于区分真正完成,用户取消和异常中断。++## 任务身份++任务 key 按可用信息选择最精确身份:++1. `session ID + turn ID`+2. `session ID`+3. 匿名 project key++新的 prompt 会替代同一 session 的旧 turn。旧 turn 进入最长 5 秒 terminal grace,给迟到的结束事件留出对账时间。++subagent 事件更新父任务的 subagent 活动,不创建独立顶层任务卡片。++## 状态机++内部活动任务主要有以下状态:++| 状态 | 含义 |+| --- | --- |+| `running` | Codex 正在处理当前 turn |+| `waitingApproval` | 当前 turn 明确等待用户批准 |+| `suppressed` | 任务被异常会话保护隐藏,等待新进展恢复 |++`PermissionRequest` 只有在 reviewer 是用户时才进入 `waitingApproval`。自动审批或策略审批不会被视为用户等待。++终止信号按可靠性对账:++- `SessionEnd` 结束 session+- rollout terminal 区分完成和中断+- `Stop` 在缺少更强信号时形成完成候选+- 新 prompt 可以结束旧 turn 的展示生命周期++## 快照优先级++多个任务和短时状态同时存在时,对外快照按以下优先级表达:++```text+等待批准 > 运行中 > 最近完成 > 最近中断 > 空闲+```++完成状态在菜单栏保留 30 秒绿色提示。活动中心保留最近 10 分钟任务,terminal 去重记忆保留 24 小时。++快照由以下模块消费:++- 菜单栏状态点+- 主面板任务卡片+- 活动中心+- 通知系统+- 防睡眠控制器++## 系统睡眠与唤醒++系统即将睡眠时暂停异常会话保护判断。唤醒后执行严格恢复顺序:++1. 进入恢复状态并继续暂停保护+2. 等待 `HookEventTailReader.drainNow()` 成功+3. 重置 rollout 生命周期解析的 fallback+4. 使用新 Hook 结果和 rollout 结果统一对账+5. 恢复异常会话保护判断++如果新一轮读取失败,reader 被更换或数据源不可用,不得使用睡眠前快照继续判断任务静默。++## 异常会话保护++异常会话保护只在防睡眠主开关开启时工作,只处理 `running` 任务。++等待批准任务不参与静默阈值判断。原因是等待批准本身就是一个合法的无进展状态。++可选阈值为:++- 30 分钟+- 1 小时,默认值+- 2 小时+- 4 小时++任务达到阈值后:++1. 先持久化保护记录+2. 从活动快照中隐藏任务+3. 尝试发送保护通知+4. 如果任务出现新进展,清除抑制并恢复展示++通知提交有 3 秒宽限,但隐藏任务不依赖通知成功。这可以保证通知权限或系统服务失败时,防睡眠仍能释放。++保护判断在以下阶段暂停:++- Hook bootstrap+- 系统睡眠+- 唤醒恢复+- Hook 数据源不可用+- reader 正在更换++## 保护状态持久化++[`ActivityProtectionStateStore.swift`](../../CodexBar/Services/Workflow/ActivityProtectionStateStore.swift) 保存到:++```text+~/Library/Application Support/CodexBar/ActivityProtection/state.json+```++- 当前 schema 为 `1`+- 只保存哈希任务身份和时间戳+- 文件权限为 `0600`+- Debug 与 Release 通过 `flock` 共用文件+- 记录最长保留到最后进展后的 24 小时++任务身份使用 SHA-256 摘要,不把 session ID 或 turn ID 原文写入该状态文件。++## 代际和旧结果隔离++Monitor 为 reader 和异步恢复任务维护 generation:++- reader 更换后丢弃旧 reader 的迟到结果+- bootstrap 未完成时不发布转场副作用+- 取消的 drain 不满足恢复屏障+- 数据源显式不健康时不沿用最后健康快照做静默判断++这些约束避免系统唤醒,Hook 重装或 `CODEX_HOME` 变化时出现错误完成通知和错误释放。++## 关键源码++- [`CodexActivityMonitor.swift`](../../CodexBar/Services/Workflow/CodexActivityMonitor.swift)+- [`CodexActivityTask.swift`](../../CodexBar/Services/Workflow/CodexActivityTask.swift)+- [`CodexActivityTerminalResolution.swift`](../../CodexBar/Services/Workflow/CodexActivityTerminalResolution.swift)+- [`HookEventTailReader.swift`](../../CodexBar/Services/Workflow/HookEventTailReader.swift)+- [`CodexSessionLifecycleReader.swift`](../../CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift)+- [`CodexActivityProtection.swift`](../../CodexBar/Services/Workflow/CodexActivityProtection.swift)+- [`ActivityProtectionStateStore.swift`](../../CodexBar/Services/Workflow/ActivityProtectionStateStore.swift)diff --git a/Docs/DeveloperGuide/app-server.md b/Docs/DeveloperGuide/app-server.mdnew file mode 100644index 0000000..4159c99--- /dev/null+++ b/Docs/DeveloperGuide/app-server.md@@ -0,0 +1,141 @@+# app-server 数据链路++## 职责++app-server 链路负责读取 Codex 账户和服务端状态:++- 当前账户和套餐+- 5 小时额度和周额度+- token 用量与用量历史+- Reset Credits 状态+- Hook 功能开关,handler 列表和配置写入能力++这条链路不负责 Hook 历史统计,也不负责实时任务状态。++## Codex CLI 定位++[`CodexCLIResolver.swift`](../../CodexBar/Services/CodexCLI/CodexCLIResolver.swift) 先从进程 `PATH` 查找全局 `codex`,再检查 App 内置路径:++```text+/Applications/ChatGPT.app/Contents/Resources/codex+/Applications/Codex.app/Contents/Resources/codex+```++菜单栏 App 从 Finder 启动时可能没有交互式 shell 的完整 `PATH`,因此 resolver 还会补充常见安装目录:++```text+/opt/homebrew/bin+/usr/local/bin+~/.npm-global/bin+~/.local/bin+~/.volta/bin+/usr/bin+/bin+/usr/sbin+/sbin+```++数据目录优先使用 `CODEX_HOME`,未设置时使用真实用户主目录下的 `~/.codex`++## 进程与协议++CodexBar 启动以下命令并通过 stdio 通信:++```bash+codex app-server --listen stdio://+```++协议是逐行 JSON-RPC。建立连接后先发送 `initialize`,再发送 `initialized`,然后读取账户:++```text+启动子进程+ -> initialize(clientInfo)+ -> initialized+ -> account/read+ -> account/rateLimits/read+ -> account/usage/read+```++stdout 可能包含非 JSON 输出。pipe reader 会持续读取完整行,只把能够解码且 response id 匹配的消息交给等待中的请求。stderr 独立排空,防止子进程因管道写满而阻塞。++## API 使用范围++| 方法 | 用途 |+| --- | --- |+| `account/read` | 读取账户,套餐和认证状态 |+| `account/rateLimits/read` | 读取额度窗口 |+| `account/usage/read` | 读取 token 和历史用量 |+| `config/read` | 读取 Codex 配置 |+| `hooks/list` | 校验 Hook 来源和事件能力 |+| `config/batchWrite` | 修改 Hook 或 TUI 通知相关配置 |++每个 session 会缓存不支持的方法。一旦 app-server 明确返回 method unsupported,当前连接后续不会重复请求该方法。++## 会话生命周期++[`CodexStatusService.swift`](../../CodexBar/Services/CodexStatus/CodexStatusService.swift) 是 actor,持有连接和刷新状态:++- 单次请求超时为 20 秒+- 连接最长复用 1 小时+- 业务错误在 session 内最多重试 1 次+- transport 失败最多重建连接 1 次+- 认证需要刷新时,`account/read` 最多使用 `refreshToken = true` 再试 1 次+- service 关闭或进程退出时终止子进程并完成所有挂起请求++业务错误与 transport 错误分开处理。前者可能是某个方法暂时失败,后者代表当前 stdio 会话已经不可信。++## 刷新模型++状态 ViewModel 默认每 60 秒刷新。用户也可以在主面板双击刷新按钮立即触发。++一次刷新先解析账户,再读取额度和用量。补充数据缓存严格绑定到账户身份:++- 账户不变且补充请求失败时可以继续展示缓存值+- 账户变化时立即清空旧账户缓存+- 服务端明确不支持的方法显示为来源缺失+- 来源缺失不能转换为业务值 `0`++刷新任务通过协调器合并,避免定时刷新,面板打开和手动刷新并发创建重复请求。++## Reset Credits++Reset Credits 到期时间不来自 app-server。当可用数量大于 `0` 时,[`CodexResetCreditsService.swift`](../../CodexBar/Services/CodexStatus/CodexResetCreditsService.swift) 使用现有 `auth.json` token 请求:++```text+https://chatgpt.com/backend-api/wham/rate-limit-reset-credits+```++- 请求超时为 4 秒+- 首次请求只读取现有 token+- 收到 `401` 或 `403` 时,复用本轮统一认证刷新额度最多刷新 1 次,再重新读取 `auth.json`+- 不把 token 写入其他位置+- 数量为 `0` 时不发起请求+- 请求失败不会影响主账户和额度刷新++## Hook 版本与配置校验++Hook 设置也复用 app-server 链路,但采用独立的可用性状态:++- `isEnabled` 表示目标 handler 已安装+- `isVerified` 表示最近一次 app-server 显式校验通过+- `isOperable` 只有在两者都为 `true` 时成立+- 短暂 RPC 失败保留上一次明确校验结果++启用或校验 Hook 时必须确认实际 app-server 版本不低于 `0.145.0`++详细配置流程见 [Hook 采集与历史聚合](hook-and-aggregation.md)++## 请求日志++[`RequestLog.swift`](../../CodexBar/Services/CodexStatus/RequestLog.swift) 在内存中保留最近 500 条请求日志,用于 App 内日志窗口诊断。++日志用于观察进程启动,JSON-RPC 方法,重试和错误分类。不应写入 access token 或 Hook prompt 内容。++## 关键源码++- [`CodexCLIResolver.swift`](../../CodexBar/Services/CodexCLI/CodexCLIResolver.swift)+- [`AppServerSession.swift`](../../CodexBar/Services/CodexStatus/AppServerSession.swift)+- [`AppServerPipeReaders.swift`](../../CodexBar/Services/CodexStatus/AppServerPipeReaders.swift)+- [`CodexStatusService.swift`](../../CodexBar/Services/CodexStatus/CodexStatusService.swift)+- [`CodexStatusViewModel.swift`](../../CodexBar/Services/CodexStatus/CodexStatusViewModel.swift)+- [`CodexResetCreditsService.swift`](../../CodexBar/Services/CodexStatus/CodexResetCreditsService.swift)diff --git a/Docs/DeveloperGuide/architecture.md b/Docs/DeveloperGuide/architecture.mdnew file mode 100644index 0000000..4d92f45--- /dev/null+++ b/Docs/DeveloperGuide/architecture.md@@ -0,0 +1,152 @@+# 整体架构++## 技术基线++CodexBar 是 macOS 15+ 菜单栏应用,使用 Swift 6,SwiftUI,AppKit 和 MVVM。++工程只有 `CodexBar` scheme,包含两个 target:++| Target | 职责 |+| --- | --- |+| `CodexBar` | 菜单栏 UI,Codex 数据采集,通知,同步和防睡眠编排 |+| `CodexBarHelper` | 以 root LaunchDaemon 运行,仅负责系统睡眠开关 |++两个 target 通过 [`CodexBarHelperXPC.swift`](../../Shared/CodexBarHelperXPC.swift) 共享 XPC 协议。++App 使用 Sparkle 检查更新。工程默认启用 `MainActor` 隔离,Debug 和 Release 使用不同的 App 与 CodexBarHelper bundle ID。++## 目录职责++```text+CodexBar/+ App/ App 入口+ Controllers/ AppKit 窗口, 菜单栏和面板控制器+ Models/ DTO, 状态快照和展示模型+ Services/ 数据获取, 状态机, 设置, 通知和系统服务+ Views/ SwiftUI 视图+ Resources/ Info.plist, entitlement, 本地化和声音资源+CodexBarHelper/ root LaunchDaemon+Shared/ 跨 target XPC 接口+Config/ 版本配置+Scripts/ 构建, DMG, appcast 和 CodexBarHelper 清理脚本+```++## 启动顺序++[`CodexBarApp.swift`](../../CodexBar/App/CodexBarApp.swift) 的初始化顺序是架构约束,不是实现细节:++```text+进程启动+ -> WorkflowHookEventRecorder.handleIfRequested()+ -> 命中 --hook-event 时读取 stdin, 写入 JSONL, 立即退出+ -> 普通启动时继续+ -> 创建 CodexBarAppDelegate+ -> AppDelegate 装配长期服务+ -> 创建菜单栏和辅助窗口+ -> 启动刷新, 活动监控, 通知和防睡眠协调+```++`--hook-event` 是 Codex 调用的短命子进程模式。它必须在任何 UI,CloudKit,通知或长期服务初始化之前完成。采集失败也不能阻断 Codex 主流程。++普通模式由 `CodexBarAppDelegate` 统一创建和持有长期对象,主要包括:++- `CodexStatusService` 和 `CodexStatusViewModel`+- `WorkflowService` 和对应 ViewModel+- `CodexHookSettings`+- `CodexActivityMonitor`+- `KeepAliveController`+- `WorkflowSyncSettings` 和同步调度器+- `CodexNotificationService`+- 菜单栏,快捷键,设置窗口和更新服务++App 退出时需要先释放防睡眠状态。如果 CodexBarHelper 尚未确认恢复,终止流程会等待或取消退出,避免遗留系统级睡眠状态。++## 3 条独立数据链路++CodexBar 不使用一个聚合服务承载所有状态。3 条链路的输入,时效和失败语义不同:++| 链路 | 输入 | 输出 | 主要消费者 |+| --- | --- | --- | --- |+| app-server | `codex app-server` JSON-RPC | 账户,额度,token 用量,Hook 配置能力 | 主面板,菜单栏额度,设置 |+| Hook 历史 | Hook JSONL | 日级事件,session,turn,tool,model 聚合 | 活跃度热力图,历史统计,CloudKit |+| 实时任务 | Hook 增量事件加 rollout 生命周期 | 运行,等待批准,完成,中断 | 菜单栏状态,任务中心,通知,防睡眠 |++链路之间可以共享基础设施和模型,但不能互相替代:++- app-server 不提供完整的实时任务状态+- 历史聚合允许延迟和重建,实时任务不能等待聚合完成+- 实时任务快照不可作为历史统计的持久来源+- 某条链路不可用时,其他链路仍应保持可用++## 并发边界++工程启用 Swift 6 严格并发和默认 `MainActor` 隔离。++### MainActor 对象++- SwiftUI ViewModel 和 Settings+- AppKit Controller+- `CodexActivityMonitor`+- `KeepAliveController`+- `CodexNotificationService`++这些对象负责可观察状态和 UI 协调,不应直接执行阻塞 I/O。++### Actor 服务++- `CodexStatusService` 管理 app-server 连接和刷新+- `WorkflowService` 管理历史聚合+- `HookEventTailReader` 管理 Hook 文件游标+- `CodexSessionLifecycleReader` 管理 rollout 文件游标+- `WorkflowSyncService` 管理 CloudKit 状态+- `ActivityProtectionStateStore` 管理跨进程保护记录++跨 actor 传递的 DTO 必须是不可变值类型,并按需要声明 `Sendable` 或 `nonisolated`++## 状态所有权++实时任务状态只有一个权威来源,即 [`CodexActivityMonitor.swift`](../../CodexBar/Services/Workflow/CodexActivityMonitor.swift)++它的快照被以下模块消费:++- 菜单栏图标和主面板任务卡片+- 活动中心+- 完成和等待批准通知+- 防睡眠是否存在有效任务的判断+- 异常会话保护++消费者只能基于快照展示或执行副作用,不能各自重建一套任务状态机。++## 错误和降级原则++- 短暂网络或 RPC 失败优先保留上一次可解释的状态+- 数据源不可用必须显式表达,不能伪装为空数据+- bootstrap 阶段只建立基线,不发送历史状态变化通知+- reader 更换或数据源代际变化时丢弃旧异步结果+- 恢复流程必须完成新的读取屏障后才能继续判定+- 持久化文件写入需要原子替换或文件锁,避免 Debug 与 Release 并发破坏++## 系统集成++| 能力 | 系统接口 |+| --- | --- |+| 菜单栏 | `NSStatusItem` |+| 主面板 | `NSPopover` 和浮动备用面板 |+| 全局快捷键 | Carbon Hot Key API |+| App 防空闲睡眠 | IOKit power assertion |+| 系统睡眠控制 | CodexBarHelper 调用固定参数的 `/usr/bin/pmset` |+| CodexBarHelper 安装和启动 | `SMAppService` |+| App 与 CodexBarHelper 通信 | XPC |+| 通知 | `UNUserNotificationCenter` |+| 云同步 | CloudKit private database |+| 自动更新 | Sparkle |++## 关键源码++- [`CodexBarApp.swift`](../../CodexBar/App/CodexBarApp.swift) 定义启动入口+- [`StatusItemController.swift`](../../CodexBar/Controllers/StatusItemController.swift) 包含 AppDelegate 和菜单栏编排+- [`CodexStatusService.swift`](../../CodexBar/Services/CodexStatus/CodexStatusService.swift) 管理 app-server+- [`WorkflowService.swift`](../../CodexBar/Services/Workflow/WorkflowService.swift) 管理 Hook 历史聚合+- [`CodexActivityMonitor.swift`](../../CodexBar/Services/Workflow/CodexActivityMonitor.swift) 管理实时任务+- [`KeepAliveController.swift`](../../CodexBar/Services/KeepAlive/KeepAliveController.swift) 管理防睡眠策略+- [`WorkflowSyncService.swift`](../../CodexBar/Services/Workflow/WorkflowSyncService.swift) 管理 CloudKit 同步diff --git a/Docs/DeveloperGuide/data-and-privacy.md b/Docs/DeveloperGuide/data-and-privacy.mdnew file mode 100644index 0000000..f378342--- /dev/null+++ b/Docs/DeveloperGuide/data-and-privacy.md@@ -0,0 +1,185 @@+# 数据与隐私边界++## 原则++CodexBar 只读取实现账户展示,Hook 统计,实时任务和防睡眠所需的数据:++- 原始数据能留在本机时不上传+- 可以保存聚合时不保存正文+- 可以保存哈希身份时不保存原始身份+- 数据源不可用时显式标记缺失++## 数据流总览++| 来源 | CodexBar 使用方式 | 是否持久化 | 是否上传 CloudKit |+| --- | --- | --- | --- |+| app-server 账户和额度 | 主面板和通知判断 | 仅设置和短期状态 | 否 |+| Hook 结构化事件 | 历史聚合和实时任务 | 是,最长 210 天 | 只上传日聚合 |+| rollout 生命周期 | terminal 和进展对账 | 不单独持久化 | 否 |+| `auth.json` token | 查询 Reset Credits 到期时间 | 不复制 | 否 |+| App 设置 | 功能开关和阈值 | UserDefaults | 否 |+| Activity Protection | 异常会话恢复 | 哈希身份,最长 24 小时 | 否 |+| CodexBarHelper ownership | 系统睡眠恢复 | root 状态文件 | 否 |++## 本地读取++### Codex app-server++App 通过本机 `codex app-server --listen stdio://` 获取账户,额度,token 用量和 Codex 配置。++CodexBar 不自行实现账户登录。app-server 是否访问 OpenAI 服务由 Codex CLI 的正常认证和协议行为决定。++### Hook 事件++Hook 子进程从 stdin 提取:++- 时间和事件类型+- 工作目录+- tool,model 和 effort+- permission 和 reviewer+- session,turn 和 agent 身份++不把 prompt,response,tool 参数或 tool 输出写入 CodexBar Hook 文件。++### Rollout 文件++实时活动 reader 会访问 `$CODEX_HOME/sessions` 和 `$CODEX_HOME/archived_sessions`++它只解析生命周期,时间,turn context,progress,effort 和 reviewer 等结构字段。不把对话正文复制到 CodexBar 存储或展示到 UI。++### Codex 凭据++Reset Credits 数量大于 `0` 时,App 读取现有 `auth.json` access token,只用于调用到期时间接口:++- 不修改 `auth.json`+- 不保存 token 副本+- 不把 token 写入 UserDefaults,Hook 文件,CloudKit 或日志+- 请求结束后只保留解析出的业务结果++## 本地持久化++### App 用户目录++```text+~/Library/Application Support/CodexBar/+ HookEvents/+ events/YYYY-MM-DD.jsonl+ daily.jsonl+ maintenance.json+ stats.lock+ Sync/+ ActivityProtection/+ state.json+```++| 路径 | 内容 | 生命周期 |+| --- | --- | --- |+| `HookEvents/events` | 原始结构化 Hook 事件 | 210 天 |+| `HookEvents/daily.jsonl` | 日级聚合 | 210 天 |+| `HookEvents/maintenance.json` | 文件游标,generation 和维护状态 | 持续更新 |+| `HookEvents/Sync` | CloudKit 缓存和游标 | 同步状态有效期间 |+| `ActivityProtection/state.json` | 哈希任务身份和时间戳 | 最后进展后最长 24 小时 |++最近 3 天的日聚合可以保留 session 和 turn ID 明细用于准确去重。更早数据只保留计数。++### UserDefaults++UserDefaults 保存:++- 功能开关和设置选项+- 通知阈值和声音名称+- 全局快捷键+- 菜单栏显示选择+- 有界的通知去重 key+- CodexBarHelper fingerprint 等运行配置++持久化 key 改名,结构变化或默认值变化需要考虑旧版本升级行为。++### CodexBarHelper 目录++```text+/Library/Application Support/CodexBar/helper-state.json+```++文件只保存 CodexBarHelper 是否拥有 `SleepDisabled` 的恢复事务,不包含 Codex 任务,账户或 Hook 数据。++目录和文件由 root 管理。详细权限和恢复策略见 [防睡眠系统](sleep-prevention.md)++## 内存日志和系统日志++App 内 [`RequestLog.swift`](../../CodexBar/Services/CodexStatus/RequestLog.swift) 是最多 500 条的内存 ring buffer,进程退出后消失。++请求日志用于诊断 app-server 协议。即使只存在内存,也不应写入 OAuth token 或 Hook 内容。++统一系统日志 subsystem 为 `app.zabrian.codexbar`,Debug 版本带 `.debug` 后缀。++系统日志只应记录:++- 操作阶段和结果+- 状态分类+- 不敏感计数+- 可定位模块的错误信息++系统日志不应记录:++- OAuth token+- prompt,response 或 tool 内容+- session ID,turn ID 或 agent ID+- 完整项目路径或敏感项目名+- 账户额度和 token 用量明细++## 网络访问++| 目标 | 用途 | 触发条件 |+| --- | --- | --- |+| OpenAI Reset Credits endpoint | 查询手动重置次数到期时间 | 可用数量大于 `0` |+| CloudKit private database | 同步日级 Hook 聚合 | 用户主动开启同步 |+| Sparkle appcast 和更新资源 | 检查或安装更新 | 自动检查或用户手动检查 |++账户,额度和 token 用量通过本机 app-server stdio 获取,CodexBar 不直接请求对应账户 API。++CodexBarHelper 不进行任何网络访问。++## CloudKit 边界++CloudKit 只上传日级聚合字段:++- 设备 pseudonym+- 日期和 source generation+- Hook 事件计数+- session 和 turn 计数+- project 显示名计数+- model 计数+- 更新时间++CloudKit 不上传:++- 原始 Hook JSONL+- session,turn 或 agent ID+- 完整工作目录+- prompt,response,tool 参数或输出+- Codex 账户,额度和 token 用量+- access token+- App 请求日志+- Activity Protection 状态++project 显示名可能由目录名派生,仍可能包含用户敏感信息。同步开关必须保持用户主动选择。++## 文件安全++- Hook 子进程和 App 聚合器通过 `flock` 协调写入+- JSONL 只追加完整行+- 聚合和状态文件使用可恢复写入流程+- Activity Protection 文件权限为 `0600`+- CodexBarHelper 状态通过 root owner,权限检查,full sync 和原子 rename 提交+- Debug 和 Release 共享的数据必须使用锁和兼容 schema++## 关键源码++- [`WorkflowHookEventRecorder.swift`](../../CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift)+- [`WorkflowService.swift`](../../CodexBar/Services/Workflow/WorkflowService.swift)+- [`CodexSessionLifecycleReader.swift`](../../CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift)+- [`WorkflowSyncService.swift`](../../CodexBar/Services/Workflow/WorkflowSyncService.swift)+- [`ActivityProtectionStateStore.swift`](../../CodexBar/Services/Workflow/ActivityProtectionStateStore.swift)+- [`RequestLog.swift`](../../CodexBar/Services/CodexStatus/RequestLog.swift)+- [`CodexBarHelper/main.swift`](../../CodexBarHelper/main.swift)diff --git a/Docs/DeveloperGuide/development.md b/Docs/DeveloperGuide/development.mdnew file mode 100644index 0000000..db0600e--- /dev/null+++ b/Docs/DeveloperGuide/development.md@@ -0,0 +1,214 @@+# 开发与验证++## 环境要求++- macOS 15 或更高版本+- Xcode 和 macOS SDK+- Swift 6 toolchain+- `swiftformat`+- `swiftlint`+- 本机可用的 Codex CLI 或包含内置 Codex 的 App++工程使用 `CodexBar` scheme,日常构建不需要 Developer ID 或公证凭据。++## 工程结构++| 目录 | 职责 |+| --- | --- |+| `CodexBar/App` | App 启动入口 |+| `CodexBar/Controllers` | AppKit 生命周期,菜单栏和窗口控制 |+| `CodexBar/Models` | 业务 DTO,快照和展示模型 |+| `CodexBar/Services` | app-server,Hook,任务,同步,通知和系统服务 |+| `CodexBar/Views` | SwiftUI 界面 |+| `CodexBar/Resources` | plist,entitlement,本地化和资源 |+| `CodexBarHelper` | root LaunchDaemon |+| `Shared` | XPC 共享接口 |+| `Config` | 版本配置 |+| `Scripts` | 发布和维护脚本 |++## 日常检查++### 构建++```bash+xcodebuild \+ -project CodexBar.xcodeproj \+ -scheme CodexBar \+ -destination 'generic/platform=macOS' \+ build+```++### 格式化++```bash+swiftformat .+```++工程使用 Swift 6 和 4 空格缩进,配置位于 `.swiftformat`++### 静态检查++```bash+swiftlint+```++规则位于 `.swiftlint.yml`++仓库当前没有 XCTest target 或覆盖率门槛。构建,格式化和 lint 不能替代受影响流程的手动验证。++## 日志++查看 Release 系统日志:++```bash+/usr/bin/log stream \+ --predicate 'subsystem == "app.zabrian.codexbar"' \+ --style compact+```++Debug subsystem 带 `.debug` 后缀。++App 内日志窗口展示当前进程最近 500 条 app-server 交互日志,适合排查 CLI 定位,handshake,method unsupported 和重试。++## Debug 与 Release++两种配置使用不同身份:++| 配置 | App bundle ID | CodexBarHelper bundle ID |+| --- | --- | --- |+| Release | `app.zabrian.codexbar` | `app.zabrian.codexbar.helper` |+| Debug | `app.zabrian.codexbar.debug` | `app.zabrian.codexbar.debug.helper` |++排查 CodexBarHelper 安装,LaunchDaemon 或系统授权时不要混用两个配置。++Hook handler 绑定当前 App 可执行文件路径。在 Debug 和 Release 之间切换时,先确认实际安装的 handler 指向目标版本。++## 架构规则++### 启动入口++`WorkflowHookEventRecorder.handleIfRequested()` 必须是 App 初始化的第一项工作。++`--hook-event` 模式只读取 stdin,加锁写入 JSONL 并立即退出。不初始化 UI,通知,CloudKit 或其他长期服务。++### MainActor++UI,Controller,ViewModel 和 Settings 依赖默认隔离。阻塞文件,子进程和网络 I/O 放入 actor 或异步服务。++共享可变状态放入 actor。DTO 和跨 actor 值类型按需要补充并发声明,不通过关闭检查绕过 Swift 6 诊断。++### 数据链路++保持以下链路独立:++- app-server 账户,额度与用量+- Hook 历史聚合+- `CodexActivityMonitor` 实时任务++新增 UI 可以组合 3 条链路的快照,但不能让一条链路成为另一条链路的隐式前置条件。++### Hook++- handler 修改保留现有用户和第三方配置+- 启用与校验检查实际 app-server 版本不低于 `0.145.0`+- Hook 子进程失败不能阻断 Codex+- `SessionEnd` 超时为 3 秒,其他事件为 5 秒+- `drainNow()` 必须维持读取屏障语义+- 数据源不可用时不能使用旧快照继续判定++### 聚合++原始事件到聚合结果的算法,字段,含义或去重规则变化时:++1. 递增 `WorkflowMaintenanceState.currentAggregationSchema`+2. 从保留期内原始 JSONL 完整重建+3. 不增加字段级历史迁移+4. 保留 missing 与 `0` 的区别+5. 标记 CloudKit 当前设备 replacement 日期++### 防睡眠++- CodexBarHelper 只控制睡眠+- CodexBarHelper 不增加网络或任意命令能力+- 外部 `SleepDisabled=1` 不能被 CodexBar 声明或恢复+- 租约,watchdog 和 owned 持久化必须共同成立+- App 退出前确认系统状态恢复++### 兼容性++以下变化属于兼容性问题:++- 持久化 key 改名或结构变化+- 本地 schema 变化+- CloudKit record 或字段变化+- CodexBarHelper ownership 格式变化+- Debug 与 Release 共享身份计算变化+- 最低系统版本或 API 可用性变化++这些变化会影响旧数据,旧 App 或 Debug 与 Release 共存,需要配套的迁移和降级设计。++## 按改动类型验证++### 菜单和窗口++- 左键,右键和 Control 点击行为+- popover 外部点击关闭+- 侧边面板 hit region 和互斥+- 设置与日志窗口焦点+- 全局快捷键和 fallback panel+- 多显示器与不同菜单栏位置++### Hook 和聚合++- 保留已有 handler+- 版本不满足时拒绝启用+- 所有事件能在超时内落盘+- 文件替换,截断和跨日读取+- schema 升级完整重建+- missing 字段不会显示为 `0`++### 实时任务++- 运行,等待批准,完成和中断转场+- auto review 不进入等待状态+- subagent 归属父任务+- bootstrap 不发送通知+- 系统唤醒完成新读取后再对账+- reader 更换时丢弃旧结果++### 同步++- 首次 backfill+- 多设备合并不重复本机贡献+- 重建只替换当前设备日期+- iCloud 离线,账户切换和恢复+- 保留期清理++### 通知++- 系统权限允许和拒绝+- 阈值 crossing 和持久化去重+- 前台展示与点击激活+- 自定义声音缺失回退+- TUI 通知与 App 通知互不影响++### 防睡眠++- App 包内 CodexBarHelper 和 plist 位置+- App 与 CodexBarHelper 签名+- 首次系统授权+- 运行与等待批准切换+- 低电量和最长时长停止+- 外部 `SleepDisabled` 共存+- 正常退出和异常退出恢复+- Debug 与 Release 分离++## 发布脚本++以下脚本需要 Developer ID,签名,公证或 appcast 凭据,不用于日常验证:++- `Scripts/build.sh`+- `Scripts/dmg.sh`+- `Scripts/appcast.sh`++版本号从 [`Version.xcconfig`](../../Config/Version.xcconfig) 读取diff --git a/Docs/DeveloperGuide/hook-and-aggregation.md b/Docs/DeveloperGuide/hook-and-aggregation.mdnew file mode 100644index 0000000..8804a6a--- /dev/null+++ b/Docs/DeveloperGuide/hook-and-aggregation.md@@ -0,0 +1,211 @@+# Hook 采集与历史聚合++## 链路职责++Hook 链路把 Codex 生命周期事件转换为可重建的本地历史统计:++```text+Codex Hook+ -> CodexBar --hook-event+ -> 原始 JSONL+ -> WorkflowService 增量聚合+ -> daily.jsonl+ -> 活跃度 UI 和 CloudKit 同步+```++原始事件是事实来源,日级聚合是可重建缓存。聚合算法或字段语义变化时,必须从保留期内的原始事件完整重建。++## 安装与校验++[`CodexHookSettings.swift`](../../CodexBar/Services/Settings/CodexHookSettings.swift) 通过 app-server 读取和修改 Hook 配置。++启用前必须满足:++- 当前可执行文件路径可解析+- 实际 app-server 版本不低于 `0.145.0`+- `features.hooks` 可用+- `hooks/list` 返回可信来源+- 所需事件集合完整++目标配置文件位于 `$CODEX_HOME/hooks.json`,未设置 `CODEX_HOME` 时位于 `~/.codex/hooks.json`++安装逻辑把 CodexBar handler 作为独立命令加入现有配置。它不会用一份模板覆盖整个文件:++- 保留用户已有字段+- 保留其他应用已有 handler+- 只更新与当前可执行文件和 `--hook-event` 匹配的 handler+- 禁用时只移除精确匹配的 CodexBar handler+- 无法识别的配置保持原样++`isEnabled` 只表示 handler 存在,`isVerified` 表示最近一次 app-server 校验通过。UI 只有在 `isOperable` 成立时把 Hook 当作可工作数据源。++## 支持的事件++CodexBar 订阅以下 Hook 事件:++| 事件 | 聚合或实时用途 |+| --- | --- |+| `SessionStart` | 建立 session 生命周期 |+| `SessionEnd` | 结束 session |+| `UserPromptSubmit` | 建立 turn 和任务起点 |+| `PreToolUse` | 记录工具调用开始 |+| `PostToolUse` | 记录工具调用结束 |+| `PermissionRequest` | 识别用户批准等待 |+| `PreCompact` | 记录上下文压缩开始 |+| `PostCompact` | 记录上下文压缩结束 |+| `Stop` | 形成任务完成候选 |+| `SubagentStart` | 记录 subagent 启动 |+| `SubagentStop` | 记录 subagent 结束 |++## Hook 子进程++[`WorkflowHookEventRecorder.swift`](../../CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift) 在 App 启动最早阶段检查 `--hook-event`++命中后只执行以下工作:++1. 从 stdin 读取事件 JSON+2. 提取统计和状态机需要的最小字段+3. 获取文件锁+4. 追加一条完整 JSONL+5. 在同一个锁事务中标记维护状态+6. 立即退出++handler 超时由事件决定:++| 事件 | 超时 |+| --- | --- |+| `SessionEnd` | 3 秒 |+| 其他事件 | 5 秒 |++锁等待预算为 handler 超时减 2 秒。获取锁时从 1 ms 开始指数退避,单次等待最多 20 ms。++stdin 无效,文件锁超时或写入失败都会被吞掉。Hook 子进程不能因为统计失败而阻断 Codex。++## 采集字段++原始记录只保留计算统计和实时状态所需的信息:++- 时间戳和事件名+- 工作目录+- tool 名称+- model 和 reasoning effort+- permission 与 approval reviewer+- session ID 和 turn ID+- agent 与 parent 关系++对于 `UserPromptSubmit` 和 `PermissionRequest`,输入事件可能不包含 reviewer 或 effort。recorder 会在必要时从 rollout transcript 尾部回查匹配的 `turn_context`++回查范围如下:++- 单次最多读取 512 KB+- 只提取 reviewer 和 effort 等结构字段+- 不把 prompt 或 response 内容写入 Hook 统计++## 本地文件++默认数据根目录是:++```text+~/Library/Application Support/CodexBar/HookEvents/+```++目录结构如下:++```text+HookEvents/+ events/+ YYYY-MM-DD.jsonl+ daily.jsonl+ maintenance.json+ stats.lock+ Sync/+ state.json+ cache.jsonl+ cursor.data+```++| 文件 | 作用 |+| --- | --- |+| `events/YYYY-MM-DD.jsonl` | 按天保存原始 Hook 事件 |+| `daily.jsonl` | 按日期和来源代际保存聚合结果 |+| `maintenance.json` | 保存待处理维护和 schema 状态 |+| `stats.lock` | 协调 Hook 子进程和 App 维护任务 |+| `Sync/*` | CloudKit 同步游标和缓存 |++原始事件和日聚合最长保留 210 天。session ID 和 turn ID 的明细列表只保留 3 天,更早日期压缩为计数,降低本地文件体积和身份信息留存。++## 增量读取与来源代际++聚合器记录每个原始文件的 inode,size,offset 和 source generation:++- 正常追加时从上次 offset 继续读取+- inode 改变表示文件被替换+- size 小于 offset 表示文件被截断+- 替换或截断会创建新的 source generation++source generation 让同一天的来源替换可被显式表达,避免把旧文件贡献和新文件贡献直接相加。++## 聚合规则++日级结果包括:++- Hook 事件总数和各事件计数+- session 数和 turn 数+- tool call 数+- compaction 数+- subagent 数+- project 分布+- model 分布++成对事件可能只有一侧成功落盘。因此计数使用能够避免重复且允许缺失的规则:++- tool call 使用 `max(PreToolUse, PostToolUse)`+- compaction 使用 `max(PreCompact, PostCompact)`+- subagent 使用 `max(SubagentStart, SubagentStop)`++字段缺失与数值 `0` 的含义不同:++- 缺失表示该日期的历史来源无法提供该指标+- `0` 表示来源可用且明确没有发生++解码和 UI 展示必须保留这个区别。++## Schema 演进与重建++当前聚合 schema 为 `5`,由 `WorkflowMaintenanceState.currentAggregationSchema` 管理。++以下变化必须递增 schema:++- 原始事件到聚合结果的算法变化+- 输出字段增删+- 字段含义变化+- 去重规则变化+- 来源代际合并语义变化++升级后统一从 210 天保留期内的原始 JSONL 完整重建,不做字段级历史迁移。这种策略让聚合缓存始终能够由同一套当前算法生成。++用户手动重建时也走同一条完整重算路径,并向同步层标记需要替换的日期。++## 维护调度++[`WorkflowService.swift`](../../CodexBar/Services/Workflow/WorkflowService.swift) 是 actor,串行执行读取,聚合,清理和重建。++维护任务与额度刷新周期协调,但两条数据链路没有数据依赖。Workflow ViewModel 对 UI 的最短刷新间隔为 5 秒,避免频繁文件变更造成重复渲染。++## 故障边界++- 单条损坏 JSONL 不应让整个保留期不可读+- 文件来源改变后不能继续使用旧 offset+- 重建失败时保留最后一份可用聚合+- 维护中断不能把部分结果当作完整日期提交+- Hook 不可用时 UI 应表达来源不可用,而不是清空为 `0`+- 配置写入失败不能破坏原有 handler++## 关键源码++- [`CodexHookSettings.swift`](../../CodexBar/Services/Settings/CodexHookSettings.swift)+- [`WorkflowHookEventRecorder.swift`](../../CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift)+- [`CodexHookEvent.swift`](../../CodexBar/Models/CodexHookEvent.swift)+- [`JSONLines.swift`](../../CodexBar/Services/Workflow/JSONLines.swift)+- [`WorkflowService.swift`](../../CodexBar/Services/Workflow/WorkflowService.swift)+- [`CodexWorkflowModels.swift`](../../CodexBar/Models/CodexWorkflowModels.swift)diff --git a/Docs/DeveloperGuide/notifications.md b/Docs/DeveloperGuide/notifications.mdnew file mode 100644index 0000000..71eef55--- /dev/null+++ b/Docs/DeveloperGuide/notifications.md@@ -0,0 +1,157 @@+# 通知系统++## 职责++[`CodexNotificationService.swift`](../../CodexBar/Services/Notifications/CodexNotificationService.swift) 是通知副作用的统一入口。++它观察两类状态:++- app-server 账户,额度和 Reset Credits 快照+- `CodexActivityMonitor` 任务转场和防睡眠恢复事件++View 和其他服务不直接创建系统通知。它们发布状态变化,通知服务负责资格判断,去重,声音和点击行为。++## 通知开关++通知总开关默认关闭。各分类子开关默认开启,触觉反馈默认关闭。++总开关关闭时不会申请系统通知权限,也不会发送任何分类通知。子开关用于在总开关开启后选择具体类型:++| 分类 | 数据来源 |+| --- | --- |+| 额度重置 | app-server 额度窗口 |+| 低额度 | app-server 剩余额度 |+| Reset Credits 到期 | Reset Credits endpoint |+| 任务完成 | 实时任务 terminal 转场 |+| 等待批准 | 实时任务 waiting 转场 |+| 异常会话保护 | Activity Protection |+| 防睡眠停止 | KeepAlive 恢复结果 |++## 额度重置++额度重置通知需要先观察到窗口被消费,再观察到新窗口恢复为未消费状态。++这避免 App 第一次启动时仅因为当前额度是 100% 就发送重置通知。++判断状态按账户和额度窗口隔离。账户变化时不把前一账户的消费状态延续到新账户。++## 低额度++低额度阈值可选 5%, 10% 或 25%,默认 10%。++通知只在剩余额度从阈值上方跨到阈值或下方时发送。持续停留在低额度区域不会每次刷新都重复通知。++额度恢复到阈值上方后,下一次向下跨越可以再次通知。++## Reset Credits 到期++当 Reset Credits 数量大于 `0` 且能够读取到期日时,通知服务在到期前 7 天到 1 天按天提醒。++去重 key 包含账户,到期日和剩余天数。同一天多次刷新不会重复发送。++## 任务完成++任务通知只响应 monitor 发布的新 terminal 转场,不扫描历史列表推导:++- bootstrap 建立的历史任务不发送通知+- terminal ID 在活动监控层保留 24 小时去重+- 通知服务还维护自己的已发送 key+- 同一 turn 的 `Stop` 和 rollout terminal 对账后只发送一次++任务完成最短持续时间可选 30, 60, 120 或 300 秒,默认 60 秒。持续时间较短的完成任务不会通知,但仍可以在 UI 中短暂展示。++## 等待批准++只有 `PermissionRequest` 的 reviewer 确认是用户时才发送等待批准通知:++- 自动审批不通知+- 同一等待项只通知一次+- 任务离开等待状态后从相关集合移除+- bootstrap 中已存在的等待状态不补发历史通知++等待状态是否维持防睡眠是独立设置,不影响是否可以发送等待批准通知。++## 异常会话保护++任务静默达到阈值时,Activity Protection 先保存保护记录并隐藏任务,然后请求通知。++通知服务在提交前再次检查任务是否仍然被保护。如果 3 秒宽限内出现新进展,过时通知会被取消。++保护通知使用固定默认声音,不复用任务完成分类声音。通知发送失败不撤销已经完成的保护动作。++## 防睡眠停止++低电量或最长时长导致防睡眠停止时,`KeepAliveController` 先释放 App assertion 和 CodexBarHelper 租约。++只有系统状态恢复得到确认后才发布通知事件。这保证通知文字描述的是已经完成的结果。++## 声音++[`NotificationSoundOption.swift`](../../CodexBar/Services/Notifications/NotificationSoundOption.swift) 汇总 3 类选择:++- 无声音+- macOS 可用系统声音+- App bundle 内置声音++内置声音位于 [`NotificationSounds`](../../CodexBar/Resources/NotificationSounds)++已保存的声音名称在新系统或新版 App 中不存在时,回退到默认声音,不阻断通知。++不同通知分类可以保存各自的声音设置。++## 触觉反馈++触觉反馈默认关闭。开启后使用 10 次脉冲,每次间隔约 100 ms。++触觉是系统通知之外的可选本地反馈。不应在没有对应有效通知事件时单独触发。++## 提交与去重++通知通过 `UNUserNotificationCenter` 提交:++- 单次提交失败最多重试 1 次+- 已发送 dedup key 保存到 UserDefaults+- 最多保留 300 个 key+- key 必须包含足够的账户或任务范围,避免不同对象相互压制+- 过期或不再相关的 waiting key 会被移除++持久化去重避免 App 重启后立即重复发送同一事件,但不能替代上游任务 terminal 去重。++## 前台展示与点击++App 是 `LSUIElement`,通知中心 delegate 明确允许 App 在前台时继续展示 banner 和声音。++用户点击通知后打开主面板。打开动作通过状态栏控制器执行,复用现有 popover 或 fallback panel 逻辑。++## Codex TUI 通知++设置页中的 Codex TUI 通知是 Codex 自身配置,通过 app-server 的 `config/batchWrite` 读写。++它与 CodexBar 系统通知完全独立:++- 关闭 CodexBar 通知不代表关闭 TUI 通知+- TUI 设置失败不影响 App 通知状态+- UI 必须清楚区分两个开关的作用域++## 手动验证矩阵++- 首次开启总开关时正确请求系统权限+- 系统拒绝权限时设置页展示可理解状态+- 低额度只在向下跨越阈值时通知+- 初次加载 100% 额度不误报重置+- 完成时长低于和高于阈值时行为正确+- `Stop` 与 rollout terminal 同时出现时只通知一次+- 自动审批不发送等待批准通知+- App 前台时仍展示配置允许的通知+- 点击通知能够激活 `LSUIElement` App 并打开主面板+- 已保存声音资源缺失时回退正确+- App 重启后不重复发送已经持久化的事件++## 关键源码++- [`CodexNotificationService.swift`](../../CodexBar/Services/Notifications/CodexNotificationService.swift)+- [`NotificationSettings.swift`](../../CodexBar/Services/Settings/NotificationSettings.swift)+- [`NotificationSoundOption.swift`](../../CodexBar/Services/Notifications/NotificationSoundOption.swift)+- [`CodexCLINotificationSettings.swift`](../../CodexBar/Services/Settings/CodexCLINotificationSettings.swift)+- [`CodexActivityMonitor.swift`](../../CodexBar/Services/Workflow/CodexActivityMonitor.swift)+- [`KeepAliveController.swift`](../../CodexBar/Services/KeepAlive/KeepAliveController.swift)diff --git a/Docs/DeveloperGuide/sleep-prevention.md b/Docs/DeveloperGuide/sleep-prevention.mdnew file mode 100644index 0000000..8e56665--- /dev/null+++ b/Docs/DeveloperGuide/sleep-prevention.md@@ -0,0 +1,200 @@+# 防睡眠系统++## 设计目标++防睡眠功能需要同时满足 3 个目标:++- 有符合条件的 Codex 任务时阻止 Mac 空闲睡眠+- App 退出,崩溃或失联后可靠恢复系统设置+- 不覆盖用户或其他应用已经设置的系统级防睡眠状态++普通 App 进程负责策略和用户界面,CodexBarHelper 只执行受限的系统睡眠操作:++```text+CodexActivityMonitor+ -> KeepAliveController+ -> App IOKit assertion+ -> XPC lease+ -> CodexBarHelper+ -> /usr/bin/pmset+```++## 生效条件++[`KeepAliveController.swift`](../../CodexBar/Services/KeepAlive/KeepAliveController.swift) 只有在以下条件全部成立时才建立防睡眠:++- 防睡眠主开关已开启+- Hook 已启用且校验通过+- 至少存在一个符合设置的实时任务+- CodexBarHelper 已安装并可连接+- 未触发低电量阈值+- 未达到单次最长防睡眠时长+- App 不在终止流程++等待批准任务默认不计入有效任务,用户可以单独开启。异常会话保护抑制的任务也不再维持防睡眠。++控制器会发布明确的阻塞原因:++| 原因 | 含义 |+| --- | --- |+| `notStarted` | 服务尚未启动 |+| `userOff` | 用户关闭主开关 |+| `hookDisabled` | Hook 不可工作 |+| `noTasks` | 没有符合条件的任务 |+| `helperUnavailable` | CodexBarHelper 未安装或不可连接 |+| `helperRefreshing` | CodexBarHelper 状态正在恢复或确认 |+| `terminating` | App 正在退出 |+| `lowBattery` | 电池低于阈值 |+| `limitReached` | 达到单次时长上限 |++## App 侧 assertion++[`SystemSleepService.swift`](../../CodexBar/Services/KeepAlive/SystemSleepService.swift) 使用 IOKit 建立 `PreventUserIdleSystemSleep` assertion。++如果用户开启保持显示器唤醒,还会建立 `NoDisplaySleep` assertion,并每 30 秒调用一次用户活动声明,避免显示器空闲计时提前生效。++App 侧 assertion 只覆盖当前进程生命周期。系统级 `SleepDisabled` 由 CodexBarHelper 管理,用于覆盖 assertion 无法保证的系统睡眠路径。++## CodexBarHelper 安装与通信++CodexBarHelper 通过 `SMAppService` 注册为 LaunchDaemon。App 和 CodexBarHelper 使用 [`CodexBarHelperXPC.swift`](../../Shared/CodexBarHelperXPC.swift) 定义的 XPC 接口。++接口只提供 3 类能力:++- 设置或撤销 App 租约+- 查询 CodexBarHelper 运行和拥有状态+- App 更新后重置 CodexBarHelper 状态++每个 App 进程生成稳定的 `clientSessionID`,XPC 重连期间保持不变。每次租约变更带单调递增 generation,CodexBarHelper 只接受更新的请求,避免迟到消息覆盖新状态:++- 单次 XPC 请求超时为 10 秒+- 连接丢失后 watchdog 宽限为 15 秒+- CodexBarHelper 每 5 秒检查租约和系统状态+- 异常状态每 60 秒尝试恢复++## CodexBarHelper 权限边界++[`CodexBarHelper/main.swift`](../../CodexBarHelper/main.swift) 以 root 运行,但能力被刻意限制:++- 只执行固定路径 `/usr/bin/pmset`+- 只使用固定参数读取或切换 `disablesleep`+- 不接受任意命令或参数+- 不访问 Hook,rollout,账户或日志数据+- 不进行网络访问+- 不负责判断 Codex 任务状态++CodexBarHelper 从自身签名派生客户端 code-signing requirement,并应用到 XPC listener。未通过签名要求的客户端不能建立控制连接。++## 系统状态所有权++CodexBarHelper 先通过以下命令读取当前值:++```bash+/usr/bin/pmset -g+```++需要系统级防睡眠时只会执行固定操作:++```bash+/usr/bin/pmset -a disablesleep 1+```++释放时执行:++```bash+/usr/bin/pmset -a disablesleep 0+```++所有权规则是防止破坏外部状态的关键:++- 如果 CodexBarHelper 观察到初始值已经是 `1`,它把状态标记为 external+- external 状态不会被 CodexBar 声明为自己拥有+- CodexBar 只在亲自完成 `0 -> 1` 切换后记录 owned+- 只有 owned 状态才允许在租约结束时恢复为 `0`++因此,用户或其他工具预先开启的 `SleepDisabled=1` 不会在 CodexBar 退出时被关闭。++## CodexBarHelper 状态持久化++CodexBarHelper 把系统所有权记录保存在:++```text+/Library/Application Support/CodexBar/helper-state.json+```++安全和可靠性要求如下:++- 当前 schema 为 `1`+- 目录由 root 拥有,权限为 `0755`+- 目录不能被 group 或 world 写入+- 文件由 root 拥有,权限为 `0600`+- 使用临时文件,full sync 和原子 rename 提交+- 启动时无法读取可信 owned 记录会执行恢复到 `disablesleep 0`++该文件记录 CodexBar 对系统睡眠设置的所有权。++## 租约与故障恢复++App 持有有效任务时定期续租。CodexBarHelper 不把一次 XPC 请求解释为永久授权:++```text+租约有效 -> 保持 owned 状态+连接短暂断开 -> 等待 15 秒 watchdog+宽限内重连 -> 使用相同 clientSessionID 继续+宽限超时 -> 撤销租约并恢复 owned 状态+```++异常退出后,CodexBarHelper 依靠连接失效,watchdog 和持久化所有权共同恢复系统设置。++App 正常退出时先撤销租约和 IOKit assertion。如果 CodexBarHelper 尚未确认恢复,App 终止流程会等待,避免在不确定状态下直接离开。++## 时长和电池策略++单次时长只统计实际处于防睡眠的时间:++- 没有任务时暂停或重置周期+- 新一轮任务可以开始新的周期+- 默认上限为 12 小时+- 可选 1, 2, 4, 8, 12, 24 小时或无限制++低电量停止只在使用电池供电时生效:++- 可选阈值为 5%, 10%, 15%, 20%, 25%+- 默认关闭+- 恢复使用 5 个百分点滞回,避免电量在阈值附近反复切换++防睡眠因低电量或时长上限结束时,通知必须在睡眠状态已经恢复后发送。++## CodexBarHelper 更新++App 更新可能改变内嵌 CodexBarHelper 的签名或内容。App 会记录 CodexBarHelper fingerprint,检测变化后通过 `SMAppService` 和重置接口刷新安装状态。++验证更新时需要同时检查:++- CodexBarHelper 位于 App 包的正确位置+- LaunchDaemon plist 与 Debug 或 Release bundle ID 匹配+- App 和 CodexBarHelper 签名匹配预期+- 首次系统授权流程可完成+- 更新后旧 owned 状态能够安全恢复++## 手动验证矩阵++- 运行任务开始和结束时,App assertion 与 CodexBarHelper 租约同步切换+- 等待批准设置关闭和开启时,有效任务判断正确+- 外部先设置 `disablesleep 1` 时,CodexBar 不声明所有权也不恢复为 `0`+- App 正常退出时恢复 owned 状态+- App 强制退出或 XPC 断开后,watchdog 恢复 owned 状态+- 达到时长上限后先恢复睡眠再通知+- 低电量触发和 5% 滞回恢复正确+- 异常会话保护隐藏任务后释放防睡眠+- Debug 与 Release 版本的 CodexBarHelper 不混用++## 关键源码++- [`KeepAliveController.swift`](../../CodexBar/Services/KeepAlive/KeepAliveController.swift)+- [`SystemSleepService.swift`](../../CodexBar/Services/KeepAlive/SystemSleepService.swift)+- [`HelperRuntimeStatusMonitor.swift`](../../CodexBar/Services/KeepAlive/HelperRuntimeStatusMonitor.swift)+- [`KeepAliveDurationLimiter.swift`](../../CodexBar/Services/KeepAlive/KeepAliveDurationLimiter.swift)+- [`PowerSourceMonitor.swift`](../../CodexBar/Services/KeepAlive/PowerSourceMonitor.swift)+- [`CodexBarHelperXPC.swift`](../../Shared/CodexBarHelperXPC.swift)+- [`CodexBarHelper/main.swift`](../../CodexBarHelper/main.swift)diff --git a/Docs/DeveloperGuide/sync.md b/Docs/DeveloperGuide/sync.mdnew file mode 100644index 0000000..d5a9774--- /dev/null+++ b/Docs/DeveloperGuide/sync.md@@ -0,0 +1,181 @@+# CloudKit 同步++## 同步范围++CloudKit 同步用于在同一 iCloud 账户的 Mac 之间合并 Hook 日级统计。++同步对象是聚合结果,不是原始 Hook 事件:++```text+本机原始 Hook JSONL+ -> 本机日级聚合+ -> 当前设备 CloudKit 记录+ -> 下载其他设备记录+ -> 按日期合并展示+```++账户,额度,token 总量,实时任务和防睡眠状态不参与同步。++## CloudKit 结构++[`WorkflowSyncService.swift`](../../CodexBar/Services/Workflow/WorkflowSyncService.swift) 使用 App 的 CloudKit private database:++| 项目 | 值 |+| --- | --- |+| Container | `iCloud.app.zabrian.codexbar` |+| Custom zone | `CodexBarZone` |+| 元数据 record type | `CodexBarSyncMetadata` |+| 日聚合 record type | `CodexBarDailyAggregate` |++private database 中的数据只属于当前 iCloud 账户,不写入 public database。++## 启用条件++同步只有在以下条件全部成立时运行:++- 用户打开 CloudKit 同步+- Hook 已启用并校验通过+- 当前 iCloud 账户可用+- 本地聚合服务可用++首次启用会标记 backfill,上传本地保留期内需要同步的日期。同步调度有最短 8 秒冷却,合并短时间内的多次本地变化。++## 设备匿名化++同步需要区分设备贡献,但不能直接上传硬件标识:++1. 在 private database 创建 32 字节随机账户 salt+2. 读取本机 `IOPlatformUUID`+3. 使用账户 salt 对 UUID 执行 HMAC-SHA256+4. 把结果作为云端 `deviceId`++原始 `IOPlatformUUID` 不会上传。同一设备在同一 iCloud 账户中得到稳定 pseudonym,不同账户得到不同结果。++## 日聚合字段++每条日记录包含:++- schema+- device ID pseudonym+- 日期+- source generation+- Hook 事件计数+- session 数和 turn 数+- project 计数+- model 计数+- 更新时间++不会上传:++- 原始 Hook JSONL+- session ID 或 turn ID 原文+- 完整工作目录+- prompt 或 response 内容+- Codex 账户和额度+- token 或 `auth.json`+- App 请求日志+- 异常会话保护状态++更完整的数据边界见 [数据与隐私边界](data-and-privacy.md)++## 一次同步的阶段++```text+确认 iCloud 账户+ -> 创建或确认 custom zone+ -> 读取账户 salt 并解析设备 pseudonym+ -> 读取本地同步状态和缓存+ -> 上传当前设备变化日期+ -> 拉取远端变更+ -> 更新本地 CloudKit 缓存+ -> 清理超过保留期的记录+ -> 发布合并结果+```++- 上传每批最多 25 条记录+- 单批操作最长等待 20 秒+- 拉取单页最多 200 条变更+- 本地内容使用 SHA-256 hash 跳过未改变记录++## 合并语义++同一天可能有多个设备记录,也可能有当前设备尚未上传的最新本地结果。++合并规则是:++- 其他设备贡献按字段相加+- 当前设备使用最新本地聚合替换云端同设备贡献+- 同一设备同一天只取当前 source generation+- 当前设备本地数据缺失时才使用云端缓存贡献++用本地值替换当前设备云端值可以避免同步刚上传但本地 UI 已更新时发生双重计数。++## 来源替换与重建++Hook 原始文件被替换或完整重建时,聚合层会改变 source generation。同步层必须把这个变化解释为替换,不能把新旧代际相加。++用户执行重新扫描时:++1. 本地聚合从原始 JSONL 重建+2. 受影响日期标记为 replacement+3. 当前设备对应日期的云端记录被覆盖或删除后重建+4. 其他设备记录保持不变++这种设计让重建只修正当前设备贡献。++## 增量游标与本地缓存++同步状态位于:++```text+~/Library/Application Support/CodexBar/HookEvents/Sync/+```++| 文件 | 作用 |+| --- | --- |+| `state.json` | 同步 schema,本地 hash,backfill 和替换状态 |+| `cache.jsonl` | 远端设备日聚合缓存 |+| `cursor.data` | CloudKit zone change token |++当前 CloudKit record schema 为 `5`。本地同步状态 schema 为 `4`,能读取上一版 schema `3`++## 保留与清理++CloudKit 记录保留期与本地 Hook 历史一致,最长 210 天:++- 本地原始和日聚合过期后删除+- 当前设备过期云端记录进入清理+- 本地远端缓存同步移除过期日期+- 清理失败不影响仍在保留期内的数据展示++## 错误分类++同步层区分以下状态,供设置页展示和通知:++- 网络不可用+- iCloud 账户不可用+- CloudKit 服务不可用+- 服务端要求稍后重试+- 本地数据或 schema 不兼容+- 同步成功或无需变化++临时错误保留最后一份可用远端缓存。账户切换或身份失效时不能继续把旧账户缓存当作当前账户数据。++## 手动验证矩阵++- 首次启用后上传保留期内本机聚合+- 第二台设备能够合并显示,不重复当前设备贡献+- 关闭同步后只显示本地统计+- iCloud 未登录时显示明确状态,本地统计继续工作+- 网络断开后使用最后缓存,恢复后完成增量同步+- 本机重建后只替换当前设备记录+- 超过 210 天的本地和远端缓存被清理+- iCloud 账户切换后不显示前一账户缓存++## 关键源码++- [`WorkflowSyncService.swift`](../../CodexBar/Services/Workflow/WorkflowSyncService.swift)+- [`WorkflowSyncScheduler.swift`](../../CodexBar/Services/Workflow/WorkflowSyncScheduler.swift)+- [`WorkflowSyncSettings.swift`](../../CodexBar/Services/Settings/WorkflowSyncSettings.swift)+- [`CodexWorkflowModels.swift`](../../CodexBar/Models/CodexWorkflowModels.swift)+- [`CodexBar.entitlements`](../../CodexBar/Resources/CodexBar.entitlements)diff --git a/Docs/DeveloperGuide/ui-and-lifecycle.md b/Docs/DeveloperGuide/ui-and-lifecycle.mdnew file mode 100644index 0000000..d1f764e--- /dev/null+++ b/Docs/DeveloperGuide/ui-and-lifecycle.md@@ -0,0 +1,148 @@+# UI 与应用生命周期++## LSUIElement 约束++CodexBar 在 [`Info.plist`](../../CodexBar/Resources/Info.plist) 中配置为 `LSUIElement`++它没有 Dock 图标和普通主窗口生命周期。菜单栏,popover,浮动面板,设置窗口和通知点击都必须显式处理 App 激活与焦点。++普通 SwiftUI Window 的默认行为不足以覆盖这些场景,因此 UI 采用 SwiftUI 内容加 AppKit Controller 的组合。++## 服务装配++[`StatusItemController.swift`](../../CodexBar/Controllers/StatusItemController.swift) 同时包含 AppDelegate 和菜单栏主控制器。++AppDelegate 负责:++- 创建长期 service,ViewModel 和 settings+- 建立 monitor 与通知,防睡眠的观察关系+- 启动状态刷新和 Hook 活动读取+- 创建状态栏控制器+- 安装全局快捷键+- 配置 Sparkle 更新+- 在 App 终止时协调防睡眠释放++对象由 composition root 显式持有,避免 SwiftUI View 生命周期意外销毁长期服务。++## 状态栏图标++状态图标综合 app-server 加载状态,菜单栏额度设置和任务活动快照。++任务状态点的优先级是:++```text+等待批准 > 运行中 > 最近完成 > 最近中断 > 空闲+```++图标生成结果按输入状态缓存,避免每次定时刷新重复绘制。非激活或不可用状态通过 alpha 表达。++左键打开主面板。右键或按住 Control 点击打开上下文菜单。++## 主面板++主面板优先使用 `NSPopover`,`behavior` 设为 `applicationDefined`++CodexBar 自己管理 dismiss,原因包括:++- 主面板可以打开设置,日志和侧边详情面板+- `LSUIElement` 激活切换会制造普通 transient popover 的误关闭+- 侧边面板需要被视为同一个交互表面+- 关闭动画需要统一淡出++[`MenuSurfaceDismissMonitor.swift`](../../CodexBar/Controllers/MenuSurfaceDismissMonitor.swift) 监听全局和本地事件,[`MenuSurfaceFadeCoordinator.swift`](../../CodexBar/Controllers/MenuSurfaceFadeCoordinator.swift) 统一协调关闭动画。++## Fallback panel++全局快捷键触发时,状态栏按钮的屏幕位置可能不可用或不可信。此时 [`FallbackPanelController.swift`](../../CodexBar/Controllers/FallbackPanelController.swift) 在鼠标所在屏幕显示浮动面板。++popover 和 fallback panel 承载同一份 SwiftUI 内容和状态。业务逻辑不能依赖具体容器类型。++## 侧边详情面板++主面板可以打开:++- 活跃度热力图详情+- Reset Credits 详情+- 活动中心++这些面板互斥,打开一个时关闭其他侧边面板。它们会把自己的屏幕区域加入主表面的额外 hit region,用户在主面板和侧边面板之间移动或点击时不会触发误关闭。++相关控制器包括:++- [`HeatmapDetailPanelController.swift`](../../CodexBar/Controllers/HeatmapDetailPanelController.swift)+- [`ResetCreditsPanelController.swift`](../../CodexBar/Controllers/ResetCreditsPanelController.swift)+- [`ActivityCenterPanelController.swift`](../../CodexBar/Controllers/ActivityCenterPanelController.swift)+- [`SidePanelSupport.swift`](../../CodexBar/Controllers/SidePanelSupport.swift)++## 设置和日志窗口++设置与日志使用独立 `NSWindowController`++`LSUIElement` App 打开普通窗口时需要暂时允许窗口成为 key,激活 App,再把焦点交给目标控件。关闭后恢复菜单栏 App 的非前台行为。++焦点恢复使用约 120 ms 延迟,给 AppKit 完成窗口和 activation 状态切换。这类延迟属于系统生命周期协调,不能简单删除为同步调用。++上下文菜单 action 会延迟到 menu tracking 结束后执行,避免 AppKit 仍在菜单事件循环中时创建或激活窗口。++## 全局快捷键++[`GlobalHotKeyController.swift`](../../CodexBar/Controllers/GlobalHotKeyController.swift) 使用 Carbon Hot Key API。++快捷键约束:++- 至少包含 2 个修饰键+- 拒绝 `Command-Space`+- 拒绝 `Command-Tab`+- 系统注册冲突时回滚到之前可用设置+- 设置变更立即重新注册++Carbon API 适合无 Dock 菜单栏 App,不需要安装全局键盘事件 tap 或请求输入监控权限。++## 自动刷新与面板打开++app-server 状态默认每 60 秒刷新。面板打开时会安排约 160 ms 的延迟刷新,先完成动画和焦点切换,再更新数据。++主面板显示倒计时。手动刷新由双击触发,避免单击状态栏本身与按钮动作产生歧义。++刷新协调器合并并发触发,防止定时器,面板打开和用户操作重复创建相同请求。++## 本地化和格式化++简体中文和英文界面字符串位于 [`Localizable.xcstrings`](../../CodexBar/Resources/Localizable.xcstrings)++日期,数字和百分比使用系统自动更新 locale。不在业务模型中固定中文格式,也不把本地化后的字符串作为状态机输入。++## 自动更新++[`AppUpdater.swift`](../../CodexBar/Services/Updates/AppUpdater.swift) 封装 Sparkle:++- appcast URL 来自 App 配置+- 自动检查间隔为 3600 秒+- 更新 UI 由设置页和上下文菜单触发+- CodexBarHelper 变化在更新后单独执行 fingerprint 和注册状态检查++发布脚本需要 Developer ID,签名和公证凭据,不属于日常本地构建流程。++## 手动验证矩阵++- 左键打开主面板,右键和 Control 点击打开上下文菜单+- 点击主面板外部正确关闭,点击侧边面板不误关闭+- 热力图,Reset Credits 和活动中心保持互斥+- 全局快捷键在状态栏锚点有效和无效场景都能打开面板+- 从通知点击激活 App 并打开面板+- 设置窗口首次打开,关闭和再次打开时焦点正确+- 上下文菜单打开设置或日志时没有焦点丢失+- 多显示器和不同菜单栏位置下 fallback panel 位于鼠标屏幕+- 快捷键冲突后原快捷键仍可用+- 面板打开刷新不会造成动画卡顿或重复请求++## 关键源码++- [`StatusItemController.swift`](../../CodexBar/Controllers/StatusItemController.swift)+- [`FallbackPanelController.swift`](../../CodexBar/Controllers/FallbackPanelController.swift)+- [`MenuSurfaceDismissMonitor.swift`](../../CodexBar/Controllers/MenuSurfaceDismissMonitor.swift)+- [`MenuSurfaceFadeCoordinator.swift`](../../CodexBar/Controllers/MenuSurfaceFadeCoordinator.swift)+- [`GlobalHotKeyController.swift`](../../CodexBar/Controllers/GlobalHotKeyController.swift)+- [`SettingsWindowController.swift`](../../CodexBar/Controllers/SettingsWindowController.swift)+- [`LogWindowController.swift`](../../CodexBar/Controllers/LogWindowController.swift)+- [`CodexStatusMenuView.swift`](../../CodexBar/Views/Menu/CodexStatusMenuView.swift)diff --git a/Docs/README.md b/Docs/README.mdnew file mode 100644index 0000000..3aaebae--- /dev/null+++ b/Docs/README.md@@ -0,0 +1,58 @@+# CodexBar 文档++CodexBar 文档按读者和职责分成两套,使用说明与实现细节保持独立:++| 文档 | 目标读者 | 解决的问题 |+| --- | --- | --- |+| [用户手册](UserGuide/README.md) | 使用 CodexBar 的普通用户 | 如何安装,使用功能,理解设置和排查常见问题 |+| [开发者指南](DeveloperGuide/README.md) | 贡献者和代码阅读者 | App 如何实现,数据如何流动,核心约束如何验证 |++## 推荐阅读路径++### 第一次使用 CodexBar++1. 阅读 [安装与快速开始](UserGuide/getting-started.md)+2. 了解 [主面板与菜单栏](UserGuide/main-panel.md)+3. 按需开启 [实时任务与 CodexBar Hook](UserGuide/activity-and-hook.md)+4. 在 [设置参考](UserGuide/settings.md) 中确认各选项的作用++### 排查使用问题++1. 先查看 [常见问题与排查](UserGuide/troubleshooting.md)+2. 再从 App 的日志窗口确认 app-server 请求状态+3. 涉及本机文件或网络边界时查看 [数据,同步与隐私](UserGuide/sync-data-privacy.md)++### 阅读或修改代码++1. 从 [整体架构](DeveloperGuide/architecture.md) 建立全局视图+2. 按改动范围进入对应的数据链路或服务文档+3. 在 [开发与验证](DeveloperGuide/development.md) 中查看构建,调试和验证方式+4. 在 [数据与隐私边界](DeveloperGuide/data-and-privacy.md) 中查看本地与云端数据范围++## 目录结构++```text+Docs+├── UserGuide+│ ├── README.md+│ ├── getting-started.md+│ ├── main-panel.md+│ ├── activity-and-hook.md+│ ├── notifications.md+│ ├── sleep-prevention.md+│ ├── sync-data-privacy.md+│ ├── settings.md+│ └── troubleshooting.md+└── DeveloperGuide+ ├── README.md+ ├── architecture.md+ ├── app-server.md+ ├── hook-and-aggregation.md+ ├── activity-monitor.md+ ├── sleep-prevention.md+ ├── sync.md+ ├── notifications.md+ ├── ui-and-lifecycle.md+ ├── data-and-privacy.md+ └── development.md+```diff --git a/Docs/UserGuide/README.md b/Docs/UserGuide/README.mdnew file mode 100644index 0000000..6c6b5e6--- /dev/null+++ b/Docs/UserGuide/README.md@@ -0,0 +1,35 @@+# CodexBar 用户手册++## 文档目录++| 文档 | 内容 |+| --- | --- |+| [安装与快速开始](getting-started.md) | 运行要求,安装方式,基本操作和功能依赖 |+| [主面板与菜单栏](main-panel.md) | 菜单栏状态,账户,额度,Token 热力图和任务中心 |+| [实时任务与 CodexBar Hook](activity-and-hook.md) | Hook 的作用,启用方式,任务状态和历史统计 |+| [通知与提醒](notifications.md) | 每类通知的触发条件,默认值,音效和触觉反馈 |+| [防止系统睡眠](sleep-prevention.md) | 生效条件,全部保护选项,CodexBarHelper 授权和外部来源共存 |+| [数据,同步与隐私](sync-data-privacy.md) | 本机数据,iCloud 同步,重建数据和网络边界 |+| [设置参考](settings.md) | 通用,高级和关于页面中每一个设置的作用 |+| [常见问题与排查](troubleshooting.md) | 登录,Hook,通知,防睡眠,同步和日志问题 |++## 按目标快速查找++- 只想查看账户和额度,从 [安装与快速开始](getting-started.md) 开始+- 想看正在运行或等待批准的任务,阅读 [实时任务与 CodexBar Hook](activity-and-hook.md)+- 想在长任务期间阻止 Mac 睡眠,阅读 [防止系统睡眠](sleep-prevention.md)+- 想知道某个开关是否会上传数据,阅读 [数据,同步与隐私](sync-data-privacy.md)+- 已经遇到错误提示,直接进入 [常见问题与排查](troubleshooting.md)++## 术语约定++| 术语 | 含义 |+| --- | --- |+| Codex | Codex CLI,ChatGPT App 或 Codex App 中运行的 Codex 能力 |+| app-server | CodexBar 在本机启动并连接的 Codex 数据接口进程 |+| CodexBar Hook | CodexBar 安装到 Codex 配置中的事件处理器 |+| 实时任务 | CodexBar 根据 Hook 事件和本机会话状态判断出的运行中或等待批准任务 |+| Hook 聚合 | 从本机 Hook 原始事件计算出的每日会话,轮次和工具等统计 |+| CodexBarHelper | 只负责系统级睡眠状态切换的 CodexBar 后台服务 |++返回 [CodexBar README](../../README.md)diff --git a/Docs/UserGuide/activity-and-hook.md b/Docs/UserGuide/activity-and-hook.mdnew file mode 100644index 0000000..ad3d86b--- /dev/null+++ b/Docs/UserGuide/activity-and-hook.md@@ -0,0 +1,118 @@+# 实时任务与 CodexBar Hook++## Hook 解决什么问题++账户,额度和 Token 用量是周期性快照,无法说明一轮 Codex 任务正在运行,等待批准还是已经结束。++CodexBar Hook 会在 Codex 的关键事件发生时记录少量结构化字段,为 CodexBar 提供以下能力:++- 菜单栏任务状态点和任务提示+- 主面板活动卡片和并发任务中心+- 任务完成,等待批准和异常会话提醒+- 任务触觉反馈+- 每日会话,轮次,工具调用,权限请求,上下文压缩和子 Agent 统计+- 按实时任务自动防止系统睡眠+- 跨设备同步每日 Hook 聚合+- 从原始事件重建历史聚合++## 启用条件++开启 CodexBar Hook 前需要满足以下条件:++- CodexBar 能连接当前运行的 Codex app-server+- app-server 实际运行版本为 `0.145.0` 或更高版本+- Codex 配置中的 `features.hooks` 没有被全局关闭+- 当前 `hooks.json` 是有效 JSON++版本检查以当前已连接 app-server 的握手版本为准,不是磁盘上刚安装的版本。++更新 Codex 后如果仍提示版本过低,退出并重新打开 CodexBar 以建立新连接。++## 开启方法++1. 右键或 Control 点击菜单栏图标+2. 选择 `设置`+3. 打开 `高级` 页面+4. 开启 `CodexBar Hook`+5. 等待开关完成配置和校验++CodexBar 会在每次打开设置窗口或 App 重新激活时重新检查已安装 Hook。++## 配置文件会发生什么变化++CodexBar 使用 `$CODEX_HOME/hooks.json`,未设置 `CODEX_HOME` 时使用 `~/.codex/hooks.json`++开启时会完成以下操作:++1. 读取并保留已有配置+2. 为 CodexBar 追加独立的 command handler+3. 让 Codex 校验事件列表,来源和信任状态+4. 只更新与当前 CodexBar handler 匹配的信任项++关闭时只删除同时匹配当前 CodexBar 可执行路径和 `--hook-event` 参数的 handler。++用户自己的 handler,其他 App 的 handler,未识别字段和无关信任项都会保留。++## 任务状态如何理解++| 状态 | 含义 | 是否算作活跃任务 |+| --- | --- | --- |+| 运行中 | 当前任务仍在产生进展 | 是 |+| 等待批准 | 当前任务正在等待用户批准下一步操作 | 是 |+| 最近完成 | 一轮任务已确认结束 | 否 |+| 最近终止 | 一轮任务被确认终止 | 否 |+| 已隐藏 | 运行中任务超过异常会话静默阈值 | 否 |++完成只表示一轮任务结束,不代表执行结果一定成功。++等待批准只用于真正由用户处理的批准请求,自动审核不会被显示成用户等待状态。++子 Agent 事件会更新所属顶层任务,不会独立显示为另一条并发任务。++## Hook 事件与用途++| 事件 | 主要用途 |+| --- | --- |+| `SessionStart` 和 `SessionEnd` | 会话生命周期,会话统计和任务收尾 |+| `UserPromptSubmit` 和 `Stop` | 对话轮次,任务开始和完成候选 |+| `PreToolUse` 和 `PostToolUse` | 工具调用统计和任务进展 |+| `PermissionRequest` | 用户等待状态和权限请求统计 |+| `PreCompact` 和 `PostCompact` | 上下文压缩统计和任务进展 |+| `SubagentStart` 和 `SubagentStop` | 子 Agent 数量,状态和任务进展 |++## 每日统计如何计算++| 指标 | 含义 |+| --- | --- |+| 会话 | 当天不同 Codex session 的数量 |+| 对话轮次 | 当天不同 turn 的数量 |+| 工具调用 | `PreToolUse` 和 `PostToolUse` 两类计数中的较大值 |+| 权限请求 | `PermissionRequest` 事件数量 |+| 上下文压缩 | `PreCompact` 和 `PostCompact` 两类计数中的较大值 |+| 子 Agent | `SubagentStart` 和 `SubagentStop` 两类计数中的较大值 |+| 最常用模型 | 当天 Hook 事件中出现次数最多的模型 |++使用较大值可以在成对事件缺少一端时保留已经观察到的操作数量。++## 关闭 Hook 的影响++关闭 Hook 后以下功能停止更新:++- 实时任务和任务中心+- 菜单栏任务状态点+- 任务类通知和触觉反馈+- Hook 每日统计+- 防止系统睡眠+- 跨设备 Hook 聚合同步++账户,额度,Token 热力图,更新检查和日志窗口仍然可以使用。++## 数据边界++Hook 原始事件只保存时间,事件名,模型,推理强度,权限模式,reviewer,session,turn,agent,工具名和工作目录等结构化字段。++CodexBar 不保存 prompt 文本,Codex 回复,工具参数或工具输出。++完整存储和同步边界见 [数据,同步与隐私](sync-data-privacy.md)++返回 [用户手册](README.md)diff --git a/Docs/UserGuide/getting-started.md b/Docs/UserGuide/getting-started.mdnew file mode 100644index 0000000..49a41a1--- /dev/null+++ b/Docs/UserGuide/getting-started.md@@ -0,0 +1,78 @@+# 安装与快速开始++## 运行要求++- macOS 15.0 或更高版本+- 已安装并登录 [Codex CLI](https://github.com/openai/codex) 或安装了内置 Codex 的 ChatGPT App 或 Codex App+- 使用 Hook 相关功能时,当前运行的 Codex app-server 版本需要为 `0.145.0` 或更高版本+- 使用跨设备同步时,Mac 需要登录可用的 iCloud 账户++CodexBar 会优先使用全局安装的 Codex CLI,找不到时再尝试 ChatGPT App 和 Codex App 内置的 Codex。++## 安装++### 通过 Homebrew++```bash+brew install --cask bob-zebedy/tap/codexbar+```++### 通过 DMG++1. 从 [GitHub Releases](https://github.com/bob-zebedy/CodexBar/releases) 下载最新 DMG+2. 打开 DMG 并将 CodexBar 拖入 Applications+3. 从 Applications 启动 CodexBar++## 第一次启动++CodexBar 是菜单栏 App,启动后不会在 Dock 中显示图标:++1. 在屏幕顶部菜单栏找到 CodexBar 图标+2. 左键点击图标打开主面板+3. 等待首次账户和用量刷新完成+4. 如果显示未登录,先在当前 Codex 中完成登录+5. 如果需要实时任务,通知或防睡眠,在 `设置 > 高级` 中开启 CodexBar Hook++CodexBar 每 60 秒自动刷新一次账户,额度和 Token 用量,双击主面板中的账户图标可以立即刷新。++## 基本操作++| 操作 | 结果 |+| --- | --- |+| 左键点击菜单栏图标 | 打开或关闭主面板 |+| 右键或 Control 点击菜单栏图标 | 打开设置,日志和退出菜单 |+| `⌘⇧W` | 使用默认全局快捷键打开或关闭主面板 |+| `⌘,` | 打开设置窗口 |+| `⌘L` | 主面板打开时关闭面板并打开日志窗口 |+| 双击账户图标 | 立即刷新账户,额度和用量 |+| 双击账户邮箱 | 切换邮箱模糊显示 |+| 悬停热力图方块 | 查看当天 Token 和 Hook 统计 |+| 点击活动卡片 | 打开并发任务中心 |+| 点击手动重置次数 | 查看各批次过期时间 |++全局快捷键优先在鼠标所在屏幕打开主面板,菜单栏锚点不可用时会使用独立浮动面板。++## 功能依赖++| 功能 | CodexBar Hook | 其他条件 |+| --- | --- | --- |+| 账户,套餐和额度 | 不需要 | Codex 已登录 |+| Token 汇总和热力图 | 不需要 | 当前 Codex 支持用量接口 |+| 实时任务和任务中心 | 需要 | Hook 已通过校验 |+| 每日 Hook 统计 | 需要 | 本机存在 Hook 原始事件 |+| 额度类通知 | 不需要 | 系统通知总开关和权限已开启 |+| 任务类通知 | 需要 | Hook 已通过校验且通知已开启 |+| 防止系统睡眠 | 需要 | CodexBarHelper 已注册并获得系统批准 |+| 跨设备同步 | 需要 | iCloud 可用且用户主动开启同步 |++关闭 CodexBar Hook 不影响账户,额度,Token 热力图,更新检查或日志窗口。++## 语言与地区++CodexBar 提供简体中文和英文界面,默认跟随 macOS 的 App 语言偏好。++需要单独切换时,可在 macOS 系统设置的语言与地区页面为 CodexBar 指定 App 语言。++日期,时间,时长,百分比,月历和星期顺序始终跟随当前地区格式。++下一步可以阅读 [主面板与菜单栏](main-panel.md) 或 [设置参考](settings.md)diff --git a/Docs/UserGuide/main-panel.md b/Docs/UserGuide/main-panel.mdnew file mode 100644index 0000000..4023932--- /dev/null+++ b/Docs/UserGuide/main-panel.md@@ -0,0 +1,119 @@+# 主面板与菜单栏++## 菜单栏图标++CodexBar 用图标,状态点和可选额度条同时表达账户,任务和额度状态:++| 外观 | 含义 |+| --- | --- |+| 正常账户图标 | 账户数据可用 |+| 错误账户图标 | 未登录,初始化失败或缺少可信额度与用量数据 |+| 蓝色状态点 | 至少有一个任务正在运行 |+| 橙色状态点 | 至少有一个任务正在等待用户批准 |+| 绿色状态点 | 任务刚刚完成,高亮持续 30 秒 |+| 图标旁额度条 | 所选额度窗口的剩余比例 |++多个状态同时存在时,等待批准优先于运行中,运行中优先于最近完成。++鼠标悬停在菜单栏图标上可以查看当前任务状态,项目名,持续时间,并发任务数量和额度窗口剩余比例。++额度数据来自缓存时,图标和进度条会降低透明度,表示当前看到的不是最新快照。++## 账户区域++- 展示当前登录账户或账户类型+- 展示 Enterprise,Team,Business,Pro,Plus,Edu 和 Free 等套餐标识+- 双击账户图标会立即刷新账户,额度和用量+- 双击邮箱会切换模糊显示+- 未登录时显示 `未登录`+- app-server 无法初始化时显示 `初始化失败`++主面板只展示适合用户判断的状态,具体请求错误保留在日志窗口。++## 额度区域++CodexBar 会展示 Codex 返回的全部额度分组和窗口。++每个额度窗口包含以下信息:++- 窗口名称,例如 `5h` 或 `7d`+- 剩余比例+- 分段进度条+- 下一次重置时间++主额度分组还可能展示以下信息:++- 可用积分或无限积分状态+- 可用手动重置次数+- 每批重置次数的过期时间++点击手动重置次数可以打开详情面板,只有 Codex 返回可用次数时才会显示这个入口。++## Token 用量与热力图++汇总区域会展示以下指标:++- 全时累计 Token+- 单日 Token 峰值+- 当前连续使用天数+- 最长连续使用天数+- 最长任务时长++热力图使用 30 列乘 7 行方块展示近 30 周每日 Token 用量,颜色强度相对于当前热力图中的峰值计算。++悬停日期方块时会显示日期,Token 数量和用量强度。++CodexBar Hook 开启且当天有数据时,日期详情还会显示以下统计:++- 最常用模型+- 会话数+- 对话轮次+- 子 Agent 数+- 工具调用次数+- 权限请求次数+- 上下文压缩次数++## 活动卡片++活动卡片的状态优先级为等待批准,运行中,最近完成,最近终止。++卡片会按实际可用字段展示以下内容:++- 项目名+- 模型和推理强度+- 当前工具或执行阶段+- 已运行或已等待时间+- 活跃子 Agent 数+- 其他并发任务数++防睡眠实际生效时,活动卡片右侧会显示咖啡杯标记。++点击有内容的活动卡片可以打开任务中心。++## 任务中心++任务中心按状态分组展示以下内容:++- 等待确认+- 运行中+- 最近完成+- 最近终止++最近完成和最近终止记录在任务中心保留 10 分钟,完成与终止是不同状态。++完成表示一轮任务已经结束,不代表执行结果一定成功。++终止不会触发任务完成通知。++## 底部状态++主面板底部包含以下信息:++- 数据更新时间+- 距离下一次自动刷新的倒计时+- iCloud 同步关闭,同步中,已同步或失败状态+- 可用更新提示++发现新版本时,双击更新提示可以开始更新。++返回 [用户手册](README.md)diff --git a/Docs/UserGuide/notifications.md b/Docs/UserGuide/notifications.mdnew file mode 100644index 0000000..9f827c3--- /dev/null+++ b/Docs/UserGuide/notifications.md@@ -0,0 +1,74 @@+# 通知与提醒++## 开启通知++1. 打开 `设置 > 高级`+2. 开启 `系统通知`+3. 在 macOS 授权窗口中允许通知+4. 点击右侧滑杆按钮配置各类通知++如果系统权限被拒绝,设置页会显示 `打开系统设置` 按钮。++通知总开关默认关闭,关闭时所有 CodexBar 系统通知和任务触觉反馈都停止。++## 通知类型++| 通知 | 触发条件 | 默认子开关 | 额外依赖 |+| --- | --- | --- | --- |+| 任务完成 | 任务完成且运行时长达到所选阈值 | 开启,1 分钟 | CodexBar Hook |+| 任务等待 | 任务进入等待用户批准状态 | 开启 | CodexBar Hook |+| 额度预警 | 可信额度首次跌到阈值或以下 | 开启,10% | 无 |+| 额度重置 | 已观察到消耗的额度窗口回到未消耗状态 | 开启 | 无 |+| 重置临期 | 手动重置次数进入过期前 7 天窗口 | 开启 | 存在可用重置次数 |+| 低电量保护 | 低电量保护成功恢复系统睡眠 | 开启 | 防睡眠和低电量保护 |+| 防睡眠上限 | 达到时长上限并成功恢复系统睡眠 | 开启 | 防睡眠和有限时长上限 |+| 异常会话保护 | 运行中任务超过静默阈值且候选仍有效 | 固定行为 | CodexBar Hook 和防睡眠主开关 |++异常会话保护没有独立通知开关,使用系统默认声音。++即使系统通知没有发送成功,已确认超时的异常任务仍会被隐藏并停止参与防睡眠。++## 可选阈值++| 设置 | 可选值 |+| --- | --- |+| 任务完成最短时长 | 30 秒, 1 分钟, 2 分钟, 5 分钟 |+| 低额度阈值 | 5%, 10%, 25% |++额度预警只在剩余比例从阈值上方跨到阈值或以下时触发,不会在每次 60 秒刷新时重复发送。++手动重置次数会在过期前 7, 6, 5, 4, 3, 2 和 1 天分别判断是否需要提醒。++## 通知音效++每类可配置通知都可以选择以下声音:++- 默认通知音+- 静音+- 当前 Mac 可用的系统提示音+- CodexBar 内置的 Modern 和 Material 提示音++非默认且非静音的声音可以在设置面板中试听。++如果已经保存的声音在当前 Mac 上不存在,CodexBar 会回退到默认通知音。++## 触觉反馈++开启 `任务触觉反馈` 后,任务完成或进入等待批准时会触发触摸板震动。++触觉反馈不依赖 macOS 通知授权,但仍然服从 CodexBar 的系统通知总开关和 CodexBar Hook 状态。++## Codex TUI 通知++`Codex TUI 通知` 修改的是 Codex 用户配置中的 `tui.notifications`++它与 CodexBar 本地通知相互独立,开启其中一个不会自动开启另一个。++## 通知交互++- CodexBar 位于前台时仍会显示通知横幅,通知列表项和声音+- 点击任意 CodexBar 通知会打开主面板+- 任务不再等待批准时,对应等待通知会从通知中心撤回+- 异常任务恢复进展或候选失效时,对应保护通知会从通知中心撤回++返回 [用户手册](README.md)diff --git a/Docs/UserGuide/settings.md b/Docs/UserGuide/settings.mdnew file mode 100644index 0000000..b65b9c5--- /dev/null+++ b/Docs/UserGuide/settings.md@@ -0,0 +1,124 @@+# 设置参考++右键或 Control 点击菜单栏图标并选择 `设置`,或按 `⌘,` 打开设置窗口。++设置窗口包含 `通用`,`高级` 和 `关于` 三个页面。++## 通用设置++| 设置 | 作用 | 默认或初始状态 |+| --- | --- | --- |+| 开机自动启动 | 通过 macOS 登录项自动启动 CodexBar | 跟随当前系统登录项状态 |+| 自动检查更新 | 由 Sparkle 定期检查可用更新 | 跟随 Sparkle 当前设置 |+| 菜单栏额度指示 | 在菜单栏图标旁显示所选额度窗口剩余比例 | 主额度 |+| 全局快捷键 | 在任意 App 中打开或关闭 CodexBar 主面板 | `⌘⇧W` |++### 菜单栏额度指示++- 可在当前 Codex 返回的额度窗口之间选择+- 关闭前会记住最后选择的窗口+- 再次开启时恢复上次选择+- 缓存额度会降低显示透明度++### 全局快捷键++- 录制结果至少需要两个修饰键+- `Command-Space` 和 `Command-Tab` 等系统保留组合不可使用+- 已被其他 App 占用的组合会提示冲突+- 可以清除快捷键+- 可以恢复默认值 `⌘⇧W`++## 高级设置++| 设置 | 作用 | 默认状态 |+| --- | --- | --- |+| CodexBar Hook | 安装并校验 Codex 事件 handler | 未安装时关闭 |+| 主面板任务中心 | 控制活动卡片和任务中心是否显示 | 开启,Hook 关闭时不可用 |+| 系统通知 | 控制 CodexBar 本地通知和任务触觉反馈 | 关闭 |+| 防止系统睡眠 | 根据实时 Codex 任务自动切换系统睡眠 | 关闭 |+| 跨设备同步 | 通过 iCloud 同步每日 Hook 聚合 | 关闭 |+| 重建数据 | 从所选日期的本机原始事件重新生成聚合 | 手动操作 |++### CodexBar Hook++开启后解锁实时任务,任务类通知,Hook 统计,防睡眠和跨设备同步。++开启和校验要求当前 app-server 为 `0.145.0` 或更高版本。++完整说明见 [实时任务与 CodexBar Hook](activity-and-hook.md)++### 主面板任务中心++关闭后,主面板不再显示活动卡片和任务中心入口。++这个设置不会关闭 Hook,不会停止 Hook 统计,通知或防睡眠。++Hook 关闭时该选项会显示为关闭并置灰,保存的选择不会被覆盖。++### 系统通知子选项++| 选项 | 默认值 | 其他可选值或说明 |+| --- | --- | --- |+| 任务完成通知 | 开启,1 分钟 | 最短时长可选 30 秒, 1, 2, 5 分钟 |+| 任务等待通知 | 开启 | 需要 CodexBar Hook |+| 额度预警通知 | 开启,10% | 阈值可选 5%, 10%, 25% |+| 额度重置通知 | 开启 | 只在观察到消耗后识别重置 |+| 重置临期通知 | 开启 | 提醒 7 天内到期的手动重置次数 |+| 低电量保护通知 | 开启 | 只有低电量保护实际可用时生效 |+| 防睡眠上限通知 | 开启 | 只有最长时间不是无限制时生效 |+| 任务触觉反馈 | 关闭 | 任务完成或等待批准时触发触摸板震动 |+| Codex TUI 通知 | 跟随 Codex 配置 | 独立于 CodexBar 通知 |++每类系统通知可以选择默认,静音,系统声音或 App 内置声音。++完整说明见 [通知与提醒](notifications.md)++### 防止系统睡眠子选项++| 选项 | 默认值 | 可选值 |+| --- | --- | --- |+| 等待批准时保持 | 关闭 | 开启或关闭 |+| 保持屏幕常亮 | 关闭 | 开启或关闭 |+| 最长防睡眠时间 | 12 小时 | 1, 2, 4, 8, 12, 24 小时或无限制 |+| 异常会话保护 | 1 小时 | 30 分钟, 1, 2, 4 小时 |+| 低电量保护 | 关闭 | 关闭或 5%, 10%, 15%, 20%, 25% |++没有内置电池的 Mac 不显示低电量保护。++完整说明见 [防止系统睡眠](sleep-prevention.md)++### 跨设备同步++- 只有 CodexBar Hook 已开启且 iCloud 可用时才能开启+- 首次开启会回填本机保留期内的每日 Hook 聚合+- 设置页显示同步状态和最近成功上传时间+- 关闭后停止网络同步,本机 Hook 数据仍然保留++完整说明见 [数据,同步与隐私](sync-data-privacy.md)++### 重建数据++- 日期选择器只允许选择原始 Hook 数据保留期内的日期+- 有原始事件的日期会显示数据标记+- 选择完整范围后才可执行重建+- 执行前会显示确认提示+- 完成后显示重建天数,事件数和跳过的无效行数+- 未完成的日期会在 Hook 可用时自动重试++## 关于页面++| 项目 | 作用 |+| --- | --- |+| Codex CLI | 展示全局 Codex CLI 的磁盘版本和路径 |+| Codex APP | 展示 ChatGPT App 或 Codex App 内置 CLI 的磁盘版本和路径 |+| 当前使用 | 标记当前 app-server 实际使用的 Codex 来源和运行版本 |+| CodexBar 版本 | 展示当前版本,更新状态和可用更新 |+| GitHub 项目 | 打开 CodexBar 项目页面 |+| 检查更新 | 手动触发 Sparkle 更新检查 |+| 退出 CodexBar | 先完成必要清理再退出 App |++磁盘中的 Codex 已更新但当前 app-server 还没有重连时,关于页面会同时提示新安装版本。++点击可执行文件路径可以复制完整路径。++返回 [用户手册](README.md)diff --git a/Docs/UserGuide/sleep-prevention.md b/Docs/UserGuide/sleep-prevention.mdnew file mode 100644index 0000000..8144556--- /dev/null+++ b/Docs/UserGuide/sleep-prevention.md@@ -0,0 +1,118 @@+# 防止系统睡眠++## 功能目标++macOS 进入系统睡眠后,正在本机运行的 Codex 任务可能被挂起。++CodexBar 会根据实时任务状态自动管理系统睡眠,让长任务在无人操作时继续运行,并在任务结束或保护条件触发后恢复系统原有行为。++这个功能不是永久保持唤醒的通用开关。++开启设置只表示允许 CodexBar 自动管理睡眠,没有符合条件的任务时不会修改系统睡眠。++## 生效条件++以下条件同时满足时,CodexBar 才会实际阻止系统睡眠:++1. CodexBar 正在运行且没有进入退出流程+2. `防止系统睡眠` 主开关已打开+3. CodexBar Hook 已安装并通过最近一次明确校验+4. 至少有一个运行中任务,或已开启等待批准时保持且存在等待任务+5. CodexBarHelper 已注册并获得系统批准+6. CodexBarHelper 当前不在更新过程中+7. 低电量保护当前没有生效+8. 本轮实际防睡眠时间没有达到上限++任一条件不满足时,CodexBar 会停止自己的防睡眠状态。++条件恢复后,仍有符合条件任务时会自动重新生效。++## 设置选项++| 选项 | 作用 | 默认值 | 可选值 |+| --- | --- | --- | --- |+| 等待批准时保持 | 等待用户批准的任务也参与防睡眠 | 关闭 | 开启或关闭 |+| 保持屏幕常亮 | 同时阻止显示器睡眠,屏保和闲置锁屏 | 关闭 | 开启或关闭 |+| 最长防睡眠时间 | 限制一轮实际防睡眠的累计时长 | 12 小时 | 1, 2, 4, 8, 12, 24 小时或无限制 |+| 异常会话保护 | 长时间无进展时隐藏任务并停止其防睡眠贡献 | 1 小时 | 30 分钟, 1, 2, 4 小时 |+| 低电量保护 | 使用电池且电量过低时恢复系统睡眠 | 关闭 | 关闭或 5%, 10%, 15%, 20%, 25% |++没有内置电池的 Mac 不显示低电量保护。++## 等待批准时保持++关闭时,任务从运行中进入等待批准后不再支撑防睡眠。++开启时,等待批准期间继续防止系统睡眠。++等待批准没有自然超时,无人值守时可能长时间保持唤醒,最长防睡眠时间仍然有效。++异常会话保护只判断运行中任务,不判断等待批准任务。++## 保持屏幕常亮++这个选项只在系统睡眠已经被 CodexBar 阻止时生效。++CodexBar 会同时阻止显示器睡眠,并定期声明用户活动以压住屏保和闲置锁屏。++任务结束,低电量保护生效,达到时长上限或防睡眠失败时会同步释放。++开启后可能让你离开电脑时仍保持解锁界面,因此默认关闭。++## 最长防睡眠时间++- 只累计真正阻止系统睡眠的时间+- 因低电量,CodexBarHelper 不可用或其他条件暂停的时间不计入上限+- 系统睡眠期间和系统时间调整不消耗上限+- 没有活跃任务时会重置计时+- 新运行任务出现或等待任务恢复运行时会开始新一轮计时+- 达到上限后恢复系统睡眠,直到下一轮任务开始++## 异常会话保护++异常会话保护用于处理任务已经没有真实进展,但缺少可靠终态而仍显示为运行中的情况:++- 跟随防睡眠主开关,没有独立开关+- 只判断运行中任务+- 最近进展来自 Hook 事件,子 Agent 事件和本机会话生命周期+- 达到阈值后保存保护记录,尝试通知并隐藏任务+- 被隐藏任务不显示在活动卡片和任务中心,也不参与防睡眠+- 后续出现新进展时自动恢复任务并撤回有效通知+- 修改为更长阈值后,未超过新阈值的隐藏任务会恢复+- Hook 历史回放,系统睡眠,唤醒对账和 Hook 数据源不可用期间暂停判断+- 保护记录最长保留到最后进展后的 24 小时++保护记录只包含哈希任务标识和时间戳,不包含原始 session,turn,项目名或任务内容。++## 低电量保护++- 只在 Mac 使用电池供电时生效+- 电量首次小于或等于所选阈值时恢复系统睡眠+- 电量需要回升到阈值加 5 个百分点才解除保护+- 接通电源会立即解除当前低电量阻断+- 仍有任务时会自动恢复防睡眠+- 只有 CodexBar 确实停止自己的防睡眠状态后才发送低电量通知++5 个百分点的恢复差值用于避免电量在阈值附近反复切换。++## CodexBarHelper 授权++防睡眠需要随 App 安装的 CodexBarHelper 修改系统级睡眠状态:++- 首次开启时由 macOS 注册后台服务+- 系统要求批准后台项目时,设置页会显示 `打开系统设置`+- CodexBarHelper 缺失或注册失败时不会执行防睡眠+- App 更新导致 CodexBarHelper 变化时会刷新注册并校验睡眠状态+- App 正常退出前会先释放 CodexBarHelper 租约并恢复由 CodexBar 修改的状态+- CodexBarHelper 连接意外中断后会在宽限期结束时释放失联客户端租约++## 与其他防睡眠来源共存++如果任务开始前系统睡眠已经被其他 App 或用户关闭,CodexBar 会把来源标记为外部:++- CodexBar 不会把外部设置据为己有+- 任务结束时不会恢复或覆盖外部设置+- 外部设置恢复后任务仍在运行时,CodexBar 会重新检查并按需接管+- 主面板仍显示咖啡杯,设置页会说明系统睡眠由其他来源关闭++返回 [用户手册](README.md)diff --git a/Docs/UserGuide/sync-data-privacy.md b/Docs/UserGuide/sync-data-privacy.mdnew file mode 100644index 0000000..556f911--- /dev/null+++ b/Docs/UserGuide/sync-data-privacy.md@@ -0,0 +1,129 @@+# 数据,同步与隐私++## 跨设备同步的内容++跨设备同步用于合并多台 Mac 的每日 Hook 聚合,不同步账户,额度或 Token 用量。++启用条件如下:++- CodexBar Hook 已开启+- 当前 iCloud 账户可用+- 用户主动打开 `跨设备同步`++开启后,CodexBar 会回填本机保留期内的每日 Hook 聚合,并在后续统计维护时上传变化的日期。++每台设备的同日数据独立保存,展示时会合并不同设备的贡献,同时避免重复叠加当前设备的本地副本和云端副本。++同步使用 `iCloud.app.zabrian.codexbar` 容器的 CloudKit private database。++## 同步状态++主面板底部和设置页会显示以下状态:++| 状态 | 含义 |+| --- | --- |+| 同步未开启 | 用户没有开启同步或 CodexBar Hook 已关闭 |+| 正在同步 | 正在读取或写入 CloudKit |+| 已同步 | 最近一轮同步成功 |+| 同步失败 | 网络,iCloud 账户或服务暂时不可用 |++设置页还会显示最近一次成功上传时间。++## 重建数据++`设置 > 高级 > 重建数据` 用于从本机原始 Hook 事件重新生成所选日期的每日聚合。++适合以下场景:++- 旧聚合缺少新版本新增的统计字段+- 某些日期统计异常+- 本机原始事件发生过替换或截断+- 需要用本机结果替换当前设备同日的云端贡献++重建流程如下:++1. 日期选择器只允许选择原始 Hook 数据保留期内的日期+2. 有原始数据的日期会显示标记+3. 确认后重新解析所选日期的本机 JSONL+4. 无法解析的行会跳过并计入结果+5. 开启同步时,重建日期会在后续同步中替换当前设备对应日期的云端贡献++重建不会修改 Codex 账户,额度或 Token 用量。++## 本机保存的数据++| 数据 | 内容 | 位置或生命周期 |+| --- | --- | --- |+| Hook 原始事件 | 选定的结构化事件字段 | `~/Library/Application Support/CodexBar/HookEvents/events`,保留 210 天 |+| Hook 每日聚合 | 事件计数,会话与轮次,项目名计数和模型计数 | `~/Library/Application Support/CodexBar/HookEvents/daily.jsonl`,保留 210 天 |+| Hook 维护状态 | 文件 offset,generation 和待处理日期 | `~/Library/Application Support/CodexBar/HookEvents/maintenance.json` |+| 同步缓存 | CloudKit 缓存,游标和上传状态 | `~/Library/Application Support/CodexBar/HookEvents/Sync` |+| 异常会话保护 | 哈希任务标识和时间戳 | `~/Library/Application Support/CodexBar/ActivityProtection/state.json`,最长 24 小时 |+| CodexBarHelper 所有权 | 睡眠所有权状态和恢复事务 | `/Library/Application Support/CodexBar/helper-state.json` |+| App 偏好 | 开关,阈值,快捷键和通知去重状态 | macOS UserDefaults |+| app-server 交互日志 | 最近 500 条请求和响应 | 只存在当前 App 进程内存 |++每日聚合只在最近 3 天保留 session 和 turn ID 列表,更早日期转换为计数并删除列表。++CodexBarHelper 所有权文件由 root 持有,用于 App 或 CodexBarHelper 异常退出后的睡眠状态恢复。++## CloudKit 上传字段++每条每日聚合记录可能包含以下内容:++- iCloud 账户范围内的设备伪标识+- 日期+- 本机 Hook 数据来源 generation+- 各类 Hook 事件计数+- 会话数和对话轮次数+- 项目显示名计数+- 模型名计数+- 更新时间++设备伪标识由设备 UUID 和 iCloud private database 中的随机 salt 计算,不直接上传原始设备 UUID。++## CloudKit 不上传的内容++- 原始 Hook 事件文件+- session ID,turn ID 和 agent ID+- 完整工作目录路径+- prompt,Codex 回复,工具参数或工具输出+- Codex 账户,额度和 Token 用量+- app-server 交互日志+- 异常会话保护记录+- Codex 认证 token++项目显示名和模型名属于同步内容,如果项目名本身包含敏感信息,不应开启跨设备同步。++## 数据读取边界++CodexBar 会读取以下本机数据:++- 通过本机 app-server 获取账户,额度,Token 用量和 Codex 配置+- 读取 Hook 原始事件以生成统计和实时任务+- 读取本机 Codex rollout 的生命周期字段以区分完成与终止并补充进展时间+- 在查询手动重置次数过期时间时读取 Codex `auth.json` 中的现有凭据++rollout 读取只提取生命周期,时间和推理强度等字段,不展示或保存会话正文和工具内容。++CodexBar 不复制或持久化 Codex 认证 token。++## 网络行为++| 网络访问 | 目的 | 触发条件 |+| --- | --- | --- |+| OpenAI 重置次数接口 | 查询可用手动重置次数的过期时间 | Codex 返回可用重置次数时 |+| Sparkle 更新源 | 检查并安装 CodexBar 更新 | 自动检查开启或用户手动检查时 |+| CloudKit private database | 同步多设备每日 Hook 聚合 | 用户开启跨设备同步时 |++账户,额度和 Token 用量通过本机 app-server 的 stdio 通信获取,不是由 CodexBar 直接请求对应 OpenAI 接口。++## 日志隐私++系统日志只记录操作结果,状态分类,计数和错误阶段。++系统日志不应记录账户额度数值,Token 用量,项目名,任务内容,session ID,turn ID 或 OAuth token。++App 内 app-server 交互日志可能包含请求和响应内容,但只存在当前进程内存,只有用户主动打开日志窗口时才显示。++返回 [用户手册](README.md)diff --git a/Docs/UserGuide/troubleshooting.md b/Docs/UserGuide/troubleshooting.mdnew file mode 100644index 0000000..03b1301--- /dev/null+++ b/Docs/UserGuide/troubleshooting.md@@ -0,0 +1,140 @@+# 常见问题与排查++## 菜单栏找不到 CodexBar++- CodexBar 是菜单栏 App,不显示 Dock 图标+- 在 macOS 控制中心设置中确认菜单栏项目没有被隐藏+- 从 Applications 再次启动不会创建第二个实例+- 仍然找不到时,在活动监视器中确认 CodexBar 是否正在运行++## 主面板显示未登录++1. 打开当前正在使用的 Codex CLI,ChatGPT App 或 Codex App+2. 完成 Codex 登录+3. 双击 CodexBar 主面板中的账户图标刷新+4. 仍然未登录时退出并重新打开 CodexBar++CodexBar 优先使用全局 Codex CLI,关于页面的 `当前使用` 标记可以确认实际来源。++## 主面板显示初始化失败++常见原因如下:++- 没有找到可执行的 Codex+- Codex app-server 启动失败+- app-server 没有在超时时间内响应+- app-server 返回了无法解析的响应++打开日志窗口查看最近失败的请求和错误详情,再到关于页面确认 Codex 路径和版本。++## 额度或 Token 显示变淡++变淡表示本轮读取失败后回退到了同一账户的缓存数据。++缓存用于保留上次可用信息,不代表数据已经成功刷新。++双击账户图标重试,如果持续变淡则查看日志窗口中的 `account/rateLimits/read` 和 `account/usage/read`++## Hook 无法开启或校验失败++| 提示 | 含义 | 建议处理 |+| --- | --- | --- |+| 需要更高 Codex 版本 | 当前 app-server 版本不足 | 更新 Codex 后重启 CodexBar |+| Codex Hook 已全局关闭 | `features.hooks` 已禁用 | 在 Codex 配置中重新启用 Hooks |+| CodexBar Hook 已不完整 | 至少一个必要事件缺少当前 handler | 关闭后重新开启 CodexBar Hook |+| CodexBar Hook 未被信任 | Codex 仍把 handler 判定为未信任或已修改 | 重新开启 Hook 并检查 Codex 配置 |+| CodexBar Hook 意外来源 | app-server 返回的来源不是当前配置文件 | 检查 `CODEX_HOME` 和当前 Codex 来源 |+| hooks.json 文件格式错误 | 顶层或 `hooks` 结构不是有效 JSON | 修复 JSON 后重新操作 |+| 无法验证 Codex Hook | app-server 暂时不可用或校验失败 | 查看日志并在 Codex 可用后重新打开设置 |++Hook 配置位于 `$CODEX_HOME/hooks.json`,未设置 `CODEX_HOME` 时位于 `~/.codex/hooks.json`++升级 CodexBar 后出现 Hook 不完整提示时,关闭并重新开启 Hook 会补齐当前版本要求的事件。++## 实时任务没有出现++1. 确认 CodexBar Hook 已开启且没有错误提示+2. 确认 `主面板任务中心` 已开启+3. 新建一轮 Codex 任务以产生实时事件+4. 打开设置窗口触发一次 Hook 重新校验++历史回放期间不会发送旧任务通知,数据源边界不稳定时会降级并跳过不可信历史。++## 收不到系统通知++按以下顺序检查:++1. `系统通知` 总开关是否开启+2. macOS 是否允许 CodexBar 发送通知+3. 对应通知子开关是否开启+4. 任务类通知所需的 CodexBar Hook 是否有效+5. 任务完成时长是否达到所选阈值+6. 通知音效是否选择了静音++触觉反馈不依赖 macOS 通知权限,但依赖 CodexBar 通知总开关。++## 防睡眠没有生效++按以下顺序检查:++1. CodexBar Hook 是否有效+2. `防止系统睡眠` 是否开启+3. 当前是否存在运行中任务+4. 只有等待任务时,`等待批准时保持` 是否开启+5. 设置页是否提示需要批准 CodexBar 后台运行+6. 是否正在触发低电量保护+7. 是否已经达到最长防睡眠时间++咖啡杯表示系统睡眠当前确实被阻止,开关打开但没有咖啡杯不一定是故障。++如果设置页显示 `系统睡眠已由其他来源关闭`,CodexBar 不会覆盖该来源。++## CodexBarHelper 无法注册++- 点击设置页中的 `打开系统设置` 并允许 CodexBar 后台运行+- 确认 CodexBar 位于 Applications 中且 App 包完整+- 如果提示服务异常或 CodexBarHelper 文件缺失,重新安装完整 CodexBar App+- 更新后持续失败时退出 CodexBar,重新打开并再次检查授权++## 跨设备同步不可用++- 确认 Mac 已登录 iCloud+- 确认 iCloud Drive 和 CloudKit 服务当前可用+- 确认 CodexBar Hook 已开启+- 确认 `跨设备同步` 开关已开启+- 将鼠标悬停在主面板底部 iCloud 图标上查看具体状态++同步失败不会删除本机 Hook 数据,后续维护会再次尝试。++## 更新 Codex 后仍显示旧版本++当前版本来自已经运行的 app-server 握手,磁盘版本来自重新执行 Codex `--version`++如果关于页面显示新安装版本但 `当前使用` 仍是旧版本,退出并重新打开 CodexBar。++## 使用日志窗口++打开方式如下:++- 右键菜单栏图标并选择 `日志`+- 主面板打开时按 `⌘L`++日志窗口保留当前进程最近 500 条 app-server 请求。++每条记录包含请求时间,方法,状态和响应时间,展开后可以查看请求,响应或错误预览。++完整内容可以在独立窗口中查看或复制,清空或退出 App 后不会恢复。++## 查看系统日志++在 Terminal 中执行以下命令:++```bash+/usr/bin/log stream --predicate 'subsystem == "app.zabrian.codexbar"' --style compact+```++Debug 版本的 subsystem 使用 `.debug` 后缀。++提交问题时请描述复现步骤和可见错误,分享日志前先检查 App 内交互日志是否包含不希望公开的请求内容。++返回 [用户手册](README.md)diff --git a/README.md b/README.mdindex 2038c94..07e40c7 100644--- a/README.md+++ b/README.md@@ -4,15 +4,14 @@# CodexBar-**在 macOS 菜单栏一眼看清 Codex 相关信息**+**在 macOS 菜单栏一眼看清 Codex**[](https://www.apple.com/macos/)-[](https://swift.org)[](https://github.com/bob-zebedy/CodexBar/releases)[](https://github.com/bob-zebedy/CodexBar/releases)[](LICENSE)-[功能总览](#功能总览) | [安装](#安装) | [基本使用](#基本使用) | [设置说明](#设置说明) | [CodexBar Hook](#codexbar-hook) | [防止系统睡眠](#防止系统睡眠) | [隐私与数据](#隐私与数据)+[功能](#功能) | [安装](#安装) | [快速开始](#快速开始) | [使用文档](#使用文档) | [隐私](#隐私)<img src="Images/preview.gif" width="640" alt="CodexBar 预览">@@ -20,606 +19,92 @@----CodexBar 是面向 macOS 15 及更高版本的菜单栏 App, 用于展示 Codex 账户 额度 Token 用量和实时任务状态, 并提供通知 跨设备 Hook 统计和按任务自动防睡眠等能力+CodexBar 是面向 macOS 15 及更高版本的菜单栏 App, 用于集中展示 Codex 账户, 额度, Token 用量和实时任务状态-CodexBar 会优先使用全局安装的 Codex CLI, 找不到时回退到 ChatGPT App 或 Codex App 内置的 Codex, 通过本机 `codex app-server` 获取账户 额度和 Token 用量+它可以在任务完成, 等待批准或额度变化时提醒你, 也能只在 Codex 任务运行期间自动防止系统睡眠-## 功能总览+## 功能-CodexBar 的功能来自三条彼此独立的数据链路+### 账户与额度一目了然-| 功能 | 主要作用 | 数据来源 | 是否依赖 CodexBar Hook |-| --- | --- | --- | --- |-| 账户与额度 | 展示账户 套餐 额度窗口 重置时间 积分和手动重置次数 | 本机 `codex app-server` | 否 |-| Token 用量 | 展示全时累计 峰值 连胜 最长任务和近 30 周热力图 | 本机 `codex app-server` | 否 |-| 实时任务 | 判断运行中 等待批准 最近完成和最近终止任务 | Hook 事件与本机 rollout 生命周期 | 是 |-| Hook 历史统计 | 按天统计会话 轮次 工具调用 权限请求 上下文压缩和子 Agent | 本机 Hook 原始事件 | 是 |-| 系统通知 | 提醒额度变化 任务变化 重置临期和防睡眠保护事件 | 额度链路与实时任务链路 | 部分依赖 |-| 防止系统睡眠 | 只在符合条件的 Codex 任务存在时阻止系统睡眠 | 实时任务链路与 CodexBar Helper | 是 |-| 跨设备同步 | 通过 iCloud 合并多台 Mac 的每日 Hook 聚合 | CloudKit private database | 是 |+- 展示当前 Codex 账户和套餐+- 展示全部额度窗口, 剩余比例和重置时间+- 展示可用积分和手动重置次数+- 可在菜单栏图标旁直接显示所选额度窗口-### 菜单栏图标+### 看见自己的 Codex 使用节奏-- 普通状态显示 Codex 图标, 账户或可信数据异常时切换为错误图标-- 运行中任务显示蓝色状态点, 等待批准显示橙色状态点, 刚完成任务显示绿色状态点-- 开启菜单栏额度指示后, 图标旁显示所选额度窗口的剩余比例-- 鼠标悬停可查看任务状态 项目名 运行或等待时长以及额度窗口剩余比例-- 额度数据来自缓存时会降低图标和进度条透明度, 避免把旧数据误认成最新状态--### 主面板+- 展示累计 Token, 单日峰值和连续使用天数+- 展示最长任务时长+- 通过 30 周热力图回顾每日 Token 用量+- 开启 CodexBar Hook 后可查看会话, 对话轮次, 工具调用和子 Agent 等每日统计-#### 账户信息+### 不错过正在发生的任务-- 展示当前登录账户和套餐标识-- 套餐标识支持 Enterprise Team Business Pro Plus Edu 和 Free 等类型-- 双击邮箱可切换模糊显示-- 双击账户图标可立即刷新账户 额度和用量-- 未登录或 app-server 初始化失败时显示对应状态, 具体请求错误保留在日志窗口+- 菜单栏状态点区分运行中, 等待批准和刚完成任务+- 主面板展示当前任务, 项目, 模型, 推理强度和持续时间+- 任务中心集中查看并发任务, 最近完成和最近终止记录+- 支持任务完成, 等待批准和异常会话提醒-#### 额度与重置次数+### 让长任务安心运行-- 展示 Codex 返回的全部额度分组和额度窗口-- 每个窗口展示名称 剩余比例 分段进度条和重置时间-- 展示可用积分或无限积分状态-- 展示可用手动重置次数-- 点击手动重置次数可查看各批次的过期时间和数量-- 手动重置次数将在 7 天内过期时按剩余天数提供通知提醒+- 只在符合条件的 Codex 任务存在时防止系统睡眠+- 可选择等待批准期间继续保持, 或同时保持屏幕常亮+- 支持最长防睡眠时间, 低电量保护和异常会话保护+- 任务结束或保护条件触发后自动恢复系统睡眠-#### Token 用量与热力图+### 融入 macOS 工作流-- 展示全时累计 Token-- 展示单日 Token 峰值-- 展示当前连续使用天数和最长连续使用天数-- 展示最长任务时长-- 使用 30 列乘 7 行热力图展示近 30 周每日 Token 用量-- 方块颜色强度相对于当前热力图中的峰值计算-- 鼠标移动到日期方块时展示日期 Token 数和用量强度-- Hook 开启时, 日期详情还会展示最常用模型 会话数 对话轮次 子 Agent 工具调用 权限请求和上下文压缩次数--#### 实时任务与任务中心--- 主面板活动卡片优先展示等待批准或运行中的任务, 没有活跃任务时展示最近完成或最近终止状态-- 活动卡片可展示模型 推理强度 项目名 工具名 运行时长 等待时长 活跃子 Agent 数和其他并发任务数-- 点击有内容的活动卡片可打开任务中心-- 任务中心分别列出等待确认 运行中 最近完成和最近终止任务-- 每条任务可展示项目 模型 推理强度 状态持续时间和完成或终止时间-- 防睡眠实际生效时, 活动卡片右侧显示咖啡杯标记--#### 底部状态--- 展示数据更新时间和距离下一次自动刷新的倒计时-- 账户 额度和 Token 用量每 60 秒自动刷新一次-- 展示 iCloud 同步关闭 同步中 已同步或同步失败状态-- 发现新版本时展示更新提示, 双击提示可开始更新--### 通知与提醒--CodexBar 通知总开关开启并获得 macOS 通知授权后, 支持以下通知--| 通知 | 触发条件 | 可配置项 | 额外依赖 |-| --- | --- | --- | --- |-| 任务完成 | 任务完成且运行时长达到阈值 | 开关 最短时长 音效 | CodexBar Hook |-| 任务等待 | 任务进入等待用户批准状态 | 开关 音效 | CodexBar Hook |-| 额度预警 | 剩余额度首次跌到阈值或以下 | 开关 阈值 音效 | 无 |-| 额度重置 | 已观察到消耗的额度窗口回到未消耗状态 | 开关 音效 | 无 |-| 重置临期 | 手动重置次数进入过期前 7 天窗口 | 开关 音效 | 无 |-| 低电量保护 | 低电量导致 CodexBar 成功恢复系统睡眠 | 开关 音效 | 防睡眠和低电量保护 |-| 防睡眠上限 | 达到时长上限并成功恢复系统睡眠 | 开关 音效 | 防睡眠和有限时长上限 |-| 异常会话保护 | 运行中任务超过静默阈值并仍然有效 | 固定使用系统默认声音 | CodexBar Hook 和防睡眠主开关 |--- 每类可配置通知都可选择默认 静音 系统声音或 App 内置声音-- 非默认且非静音的声音可在设置面板中试听-- 任务完成和任务等待可额外开启触摸板震动, 触觉反馈不依赖系统通知授权, 但服从 CodexBar 通知总开关-- 点击任意 CodexBar 通知会打开主面板-- App 位于前台时仍会显示通知横幅 列表项和声音-- 已经失效的等待批准或异常会话通知会从通知中心撤回-- Codex TUI 通知是 Codex 自己的设置, 与 CodexBar 本地通知相互独立--### 系统集成与辅助功能--- 作为 `LSUIElement` 菜单栏 App 运行, 不占用 Dock 图标-- 支持开机自动启动-- 支持可录制的全局快捷键-- 支持 Sparkle 自动检查 手动检查和应用内更新+- 作为菜单栏 App 运行, 不占用 Dock+- 支持全局快捷键, 开机启动和自动更新- 支持简体中文和英文界面-- 日期 时间 时长 百分比 月历和星期顺序跟随当前地区设置-- 提供 Codex CLI 和 Codex App 内置 CLI 的版本 来源和路径检查-- 提供最多 500 条的内存 app-server 交互日志+- 可选通过 iCloud 合并多台 Mac 的每日 Hook 统计## 安装-### 通过 Homebrew+### Homebrew```bashbrew install --cask bob-zebedy/tap/codexbar```-### 通过 DMG+### DMG-从 [Releases](https://github.com/bob-zebedy/CodexBar/releases) 下载并安装+从 [GitHub Releases](https://github.com/bob-zebedy/CodexBar/releases) 下载最新版本并拖入 Applications-### 运行要求+## 运行要求- macOS 15.0 或更高版本-- 已安装并登录 [Codex CLI](https://github.com/openai/codex), 或安装了内置 Codex 的 ChatGPT App 或 Codex App-- 使用 Hook 相关功能时, 当前连接的 Codex app-server 版本必须为 `0.145.0` 或更高版本-- 使用跨设备同步时, macOS 必须登录可用的 iCloud 账户--## 基本使用--| 操作 | 效果 |-| --- | --- |-| 左键点击菜单栏图标 | 打开或关闭主面板 |-| 右键或 Control 点击菜单栏图标 | 打开设置 日志和退出菜单 |-| `⌘⇧W` | 使用默认全局快捷键打开或关闭主面板 |-| `⌘,` | 打开设置窗口 |-| `⌘L` | 主面板打开时关闭面板并打开日志窗口 |-| 双击账户图标 | 立即刷新账户 额度和用量 |-| 双击账户邮箱 | 切换邮箱模糊显示 |-| 悬停热力图方块 | 查看当日 Token 和 Hook 统计详情 |-| 点击活动卡片 | 打开并发任务中心 |-| 点击手动重置次数 | 查看各批次过期时间 |--全局快捷键会优先在鼠标所在屏幕打开主面板, 菜单栏锚点不可用时使用独立浮动面板作为回退--## 设置说明--设置窗口包含通用 高级和关于三个页面--### 通用设置--| 设置 | 作用 | 当前默认或初始状态 |-| --- | --- | --- |-| 开机自动启动 | 通过 macOS 登录项启动 CodexBar | 跟随当前系统登录项状态 |-| 自动检查更新 | 由 Sparkle 定期检查 appcast | 跟随 Sparkle 当前设置 |-| 菜单栏额度指示 | 在菜单栏图标旁显示主额度或次额度剩余比例 | 主额度 |-| 全局快捷键 | 在任意 App 中打开或关闭 CodexBar 主面板 | `⌘⇧W` |--- 菜单栏额度指示会记住关闭前选择的窗口, 再次开启时恢复该选择-- 全局快捷键至少需要两个修饰键-- `Command-Space` 和 `Command-Tab` 等系统保留组合不可使用-- 快捷键可清除或恢复为默认值--### 高级设置--| 设置 | 作用 | 当前默认或初始状态 |-| --- | --- | --- |-| CodexBar Hook | 安装并校验 Codex 事件 handler | 未安装时关闭 |-| 主面板任务中心 | 控制活动卡片和任务中心是否显示 | 开启, Hook 关闭时不可用 |-| 系统通知 | 控制 CodexBar 本地通知和触觉反馈 | 关闭 |-| 防止系统睡眠 | 根据实时 Codex 任务自动切换系统睡眠 | 关闭 |-| 跨设备同步 | 通过 iCloud 同步每日 Hook 聚合 | 关闭 |-| 重建数据 | 从所选日期范围的本机 Hook 原始事件重新生成聚合 | 手动操作 |--#### 通知子选项--| 选项 | 可选值或默认值 |-| --- | --- |-| 任务完成通知 | 默认开启, 最短任务时长默认 1 分钟, 可选 30 秒 1 分钟 2 分钟或 5 分钟 |-| 任务等待通知 | 默认开启 |-| 额度预警通知 | 默认开启, 阈值默认 10%, 可选 5% 10% 或 25% |-| 额度重置通知 | 默认开启 |-| 重置临期通知 | 默认开启 |-| 低电量保护通知 | 默认开启, 仅在低电量保护实际可用时生效 |-| 防睡眠上限通知 | 默认开启, 仅在时长上限不是无限制时生效 |-| 任务触觉反馈 | 默认关闭 |-| Codex TUI 通知 | 读取并修改 Codex 用户配置中的 `tui.notifications` |--通知总开关首次开启时会请求 macOS 通知权限, 权限被拒绝时设置页会提供系统设置入口--#### 跨设备同步--- 只有 CodexBar Hook 已开启且 iCloud 可用时才能开启-- 开启后会回填保留期内的本机每日 Hook 聚合-- 设置页显示同步中状态和最近一次成功上传时间-- 主面板底部显示同步关闭 同步中 已同步或失败状态-- 每台设备的同日数据独立保存, 展示时会合并不同设备的贡献并避免重复叠加当前设备的本地副本-- CloudKit 使用 `iCloud.app.zabrian.codexbar` 容器的 private database--#### 重建数据--- 日期选择器只允许选择原始 Hook 数据保留期内的日期-- 有原始事件的日期会显示数据标记-- 执行前会确认所选日期范围-- 重建会重新计算本机每日聚合, 跳过无法解析的无效行并报告结果-- 开启跨设备同步后, 重建日期会在后续同步中替换当前设备对应日期的云端贡献-- 重建不修改账户 额度或 Token 用量数据--### 关于页面--- 分别检测全局 Codex CLI 和 Codex App 内置 CLI 的磁盘版本-- 标记当前 app-server 实际使用的 Codex 来源和运行版本-- 磁盘中的 Codex 已更新但当前 app-server 尚未重连时显示新安装版本-- 点击可执行文件路径可复制完整路径-- 展示 CodexBar 当前版本 更新检查状态和可用更新-- 提供 GitHub 项目入口 手动检查更新和退出 CodexBar 操作--## CodexBar Hook--### Hook 的作用+- 已安装并登录 [Codex CLI](https://github.com/openai/codex) 或安装了内置 Codex 的 ChatGPT App 或 Codex App+- 使用实时任务等 Hook 功能时, 当前运行的 Codex app-server 版本需要为 `0.145.0` 或更高版本+- 使用跨设备同步时, Mac 需要登录可用的 iCloud 账户-账户 额度和 Token 用量接口只能提供周期性快照, 不能完整表达一个 Codex 任务何时开始 何时等待批准 调用了多少工具或是否启动了子 Agent+## 快速开始-CodexBar Hook 把 Codex 在关键节点产生的事件追加到本机日志, 让 CodexBar 能够获得以下能力+1. 启动 CodexBar, 在菜单栏找到 CodexBar 图标+2. 左键点击图标查看账户, 额度和 Token 用量+3. 右键或按住 Control 点击图标打开设置, 日志或退出菜单+4. 在 `设置 > 高级` 中启用 CodexBar Hook, 解锁实时任务, 通知, 防睡眠和 Hook 统计-- 实时任务状态和并发任务中心-- 菜单栏任务状态点和任务 tooltip-- 任务完成 等待批准和异常会话保护通知-- 任务触觉反馈-- 按天统计会话 轮次 工具调用 权限请求 上下文压缩和子 Agent-- 基于任务状态自动防止系统睡眠-- 跨设备同步每日 Hook 聚合-- 从原始事件重建历史聚合+默认全局快捷键为 `⌘⇧W`, 可在设置中重新录制或关闭-关闭 Hook 不影响账户 额度 Token 热力图 更新检查或日志窗口, 但以上依赖实时事件的功能会停止工作+## 使用文档-### 启用条件--- CodexBar 必须能连接当前实际运行的 `codex app-server`-- app-server 握手版本必须为 `0.145.0` 或更高版本-- Codex 用户配置中的 `features.hooks` 不能被全局关闭-- Hook 配置文件必须是有效 JSON--版本检查使用当前连接的 app-server 运行版本, 不是磁盘上刚安装的版本--升级 Codex 后如果仍提示版本过低, 需要重启 CodexBar 以建立新连接--### 开启和关闭时修改的内容--CodexBar 使用 `$CODEX_HOME/hooks.json`, 未设置 `CODEX_HOME` 时使用 `~/.codex/hooks.json`--开启 Hook 时会完成以下操作--1. 读取并保留现有 `hooks.json` 内容-2. 为当前 CodexBar 可执行文件追加独立的 command handler-3. 通过 app-server 查询实际 Hook 列表-4. 只为命令 来源路径和事件都匹配当前 CodexBar 的 handler 更新信任状态-5. 再次查询并确认事件完整 启用 来源正确且已受信任--关闭 Hook 时只删除同时匹配当前 CodexBar 可执行路径和 `--hook-event` 参数的 handler, 并只清理对应信任项--用户自己配置的 handler 其他 App 的 handler 未识别的同级结构和无关信任项都会保留--### 监听的事件--| Hook 事件 | CodexBar 中的主要用途 |+| 文档 | 内容 || --- | --- |-| `SessionStart` `SessionEnd` | 会话生命周期 会话统计和任务收尾 |-| `UserPromptSubmit` `Stop` | 对话轮次 任务进展和完成候选 |-| `PreToolUse` `PostToolUse` | 工具调用统计和任务进展 |-| `PermissionRequest` | 用户审批状态 权限请求统计和等待通知 |-| `PreCompact` `PostCompact` | 上下文压缩统计和任务进展 |-| `SubagentStart` `SubagentStop` | 子 Agent 数量 状态和任务进展 |--`SessionEnd` 的 handler 超时为 3 秒, 其他事件为 5 秒--### 一次 Hook 事件如何处理--```text-Codex 触发事件- -> 启动 CodexBar --hook-event 子进程- -> 子进程只读取 stdin JSON- -> 提取统计和任务状态需要的字段- -> 在跨进程文件锁内追加到当日 JSONL- -> 立即退出- -> 主 App 增量读取并更新聚合和实时任务-```--- Hook 子进程不会初始化菜单栏 UI app-server CloudKit 通知或防睡眠服务-- 写入失败不会阻断 Codex, Hook 模式会忽略无效输入或本次记录失败并退出-- 主 App 同时读取 Hook 事件和本机 Codex rollout 生命周期, 用于区分准确的完成与终止状态并补充最近进展时间-- rollout 读取只提取生命周期 时间和推理强度等字段, 不展示或保存会话正文和工具内容--### Hook 本地数据--| 数据 | 路径 | 当前内容 | 保留规则 |-| --- | --- | --- | --- |-| 原始事件 | `~/Library/Application Support/CodexBar/HookEvents/events/YYYY-MM-DD.jsonl` | 时间 事件名 模型 推理强度 权限模式 reviewer session turn agent 工具和工作目录 | 210 天 |-| 每日聚合 | `~/Library/Application Support/CodexBar/HookEvents/daily.jsonl` | 每类事件计数 会话与轮次 项目名计数和模型计数 | 210 天 |-| 维护状态 | `~/Library/Application Support/CodexBar/HookEvents/maintenance.json` | 增量 offset 文件标识和待处理日期 | 跟随聚合维护 |--- 原始事件只保存选定的结构化字段, 不保存 prompt 文本 Codex 回复 工具参数或工具输出-- 原始事件中的 session turn 和 agent ID 会随对应 JSONL 一起保留 210 天-- 每日聚合只在最近 3 天保留 session 和 turn ID 列表, 之后转换为计数并删除列表-- 原始事件和每日聚合都只保存在本机-- CloudKit 不上传原始事件 session ID turn ID agent ID 完整工作目录 账户 额度或 Token 用量--### Hook 状态和排查--| 状态或提示 | 含义 | 处理方式 |-| --- | --- | --- |-| 需要更高 Codex 版本 | 当前运行的 app-server 版本不足 | 更新 Codex 后重启 CodexBar |-| Codex Hook 已全局关闭 | `features.hooks` 已禁用 | 在 Codex 配置中重新启用 Hooks |-| CodexBar Hook 已不完整 | 至少一个必要事件缺少当前 handler | 关闭后重新开启 CodexBar Hook |-| CodexBar Hook 未被信任 | app-server 仍将 handler 判定为未信任或已修改 | 重新开启 Hook 并检查 Codex 配置 |-| CodexBar Hook 意外来源 | app-server 返回的来源文件不是当前配置文件 | 检查 `CODEX_HOME` 和运行中的 Codex 来源 |-| hooks.json 文件格式错误 | 顶层或 `hooks` 结构不是有效 JSON 对象 | 修复 JSON 后重新操作 |-| 无法验证 Codex Hook | app-server 暂时不可用或校验请求失败 | 查看日志并在 Codex 可用后重新打开设置页 |--CodexBar 每次打开设置窗口或 App 重新激活时都会刷新配置并校验已安装 Hook--升级后出现 Hook 不完整提示时, 关闭后重新开启即可补齐当前代码要求的事件--## 防止系统睡眠--### 这个功能解决什么问题--macOS 进入系统睡眠后, 正在运行的本机 Codex 任务可能会被挂起--防睡眠功能根据 Codex 实时任务状态自动管理系统睡眠, 目标是让长任务在无人操作时继续运行, 同时在任务结束或保护条件触发后恢复系统原有睡眠行为--它不是一个永久保持唤醒的通用开关--打开设置只表示允许 CodexBar 自动管理睡眠, 没有符合条件的任务时不会修改系统睡眠--### 生效条件--以下条件同时满足时, CodexBar 才会实际阻止系统睡眠--1. CodexBar 正在运行且未进入退出流程-2. 防止系统睡眠主开关已打开-3. CodexBar Hook 已安装且最近一次明确校验有效-4. 至少有一个运行中任务, 或开启等待批准时保持后存在等待批准任务-5. CodexBarHelper 已注册并获得系统批准-6. Helper 当前不在更新过程中-7. 低电量保护当前没有生效-8. 本轮实际防睡眠时间尚未达到上限--任一条件不满足时只停止实际防睡眠--条件恢复后, 仍有符合条件任务时会自动重新生效--### 工作方式--```text-Hook 事件和 rollout 生命周期- -> CodexActivityMonitor 判断运行中或等待批准任务- -> KeepAliveController 检查 Hook Helper 电量和时长上限- -> App 建立空闲睡眠断言- -> CodexBarHelper 管理 pmset SleepDisabled- -> 可选建立显示睡眠断言并持续声明用户活动-```--- App 侧建立 IOKit 空闲睡眠断言-- CodexBarHelper 只通过受签名约束的 XPC 接口接受租约 状态查询和更新恢复请求-- helper 使用 `pmset -g` 查询状态, 只使用 `pmset -a disablesleep 1` 或 `pmset -a disablesleep 0` 修改状态-- 任务结束 设置关闭 Hook 失效 低电量或时长到期时会释放租约并恢复睡眠-- 如果 CodexBar 自己恢复睡眠时设备已经合盖, 且系统配置要求合盖睡眠, App 会补发一次系统睡眠请求--### 防睡眠子选项--| 选项 | 作用 | 当前默认 | 可选值 |-| --- | --- | --- | --- |-| 等待批准时保持 | 将等待用户批准的任务也计入防睡眠 | 关闭 | 开启或关闭 |-| 保持屏幕常亮 | 实际防睡眠期间同时阻止显示器睡眠 屏保和闲置锁屏 | 关闭 | 开启或关闭 |-| 最长防睡眠时间 | 限制一轮实际阻止睡眠的累计时长 | 12 小时 | 1 2 4 8 12 24 小时或无限制 |-| 异常会话保护 | 运行中任务长时间无进展时隐藏任务并停止其防睡眠贡献 | 1 小时 | 30 分钟 1 2 4 小时 |-| 低电量保护 | 使用电池且电量过低时恢复系统睡眠 | 关闭 | 关闭或 5% 10% 15% 20% 25% |--没有内置电池的 Mac 不显示低电量保护选项--#### 等待批准时保持--- 关闭时, 任务从运行中进入等待批准后不再支撑防睡眠-- 开启时, 等待批准期间继续防止系统睡眠-- 等待批准没有自然超时, 因此无人值守时可能长时间保持唤醒-- 最长防睡眠时间仍会限制等待批准期间的实际防睡眠时长-- 异常会话保护不处理等待批准任务--#### 保持屏幕常亮--- 只在系统睡眠实际被阻止时生效-- 除了阻止显示器睡眠, 还每 30 秒声明一次用户活动以压住屏保和闲置锁屏-- 任务结束 低电量保护生效 达到时长上限或防睡眠失败时会同步释放-- 开启后可能让离开电脑时仍保持解锁界面, 因此默认关闭--#### 最长防睡眠时间--- 默认 12 小时-- 只累计真正阻止系统睡眠的时间-- 因低电量 Helper 不可用或其他条件暂停防睡眠的时间不计入上限-- 使用可暂停时钟, 系统睡眠期间和系统时间调整不会消耗上限-- 没有活跃任务时重置计时-- 新运行任务出现或等待任务恢复运行时重新开始一轮计时-- 达到上限后恢复系统睡眠, 直到新一轮任务重新开始--#### 异常会话保护--异常会话保护用于处理任务已经没有真实进展, 但缺少可靠终态而仍显示为运行中的情况+| [用户手册](Docs/UserGuide/README.md) | 安装, 主面板, Hook, 通知, 防睡眠, 同步, 全部设置和问题排查 |+| [开发者指南](Docs/DeveloperGuide/README.md) | 架构, 数据链路, 核心状态机, 存储, 隐私边界和开发验证 |+| [文档导航](Docs/README.md) | 文档导航 |-- 跟随防睡眠主开关, 没有独立开关-- 只判定运行中任务, 不判定等待批准任务-- 最近进展时间来自 Hook 顶层事件 子 Agent 事件和 rollout 生命周期-- 达到阈值后先保存保护记录并尝试发送系统通知-- 无论通知是否开启或提交成功, 候选仍然有效时都会隐藏任务-- 被隐藏任务不显示在活动卡片和任务中心, 也不参与防睡眠计算-- 后续出现新进展时自动恢复任务并撤回仍有效的保护通知-- 修改为更长阈值后, 尚未超过新阈值的隐藏任务会恢复-- Hook 历史回放 系统睡眠 唤醒对账和 Hook 数据源不可用期间暂停判定-- 保护记录最长保留到最后进展后的 24 小时-- 保护记录只包含哈希任务标识和时间戳, 不包含原始 session ID turn ID 项目名或任务内容--#### 低电量保护--- 只在 Mac 使用电池供电时生效-- 电量首次小于或等于所选阈值时恢复系统睡眠-- 电量必须回升到阈值加 5 个百分点才解除保护, 避免在临界值附近反复切换-- 接通电源会立即解除当前阻断, 仍有任务时自动恢复防睡眠-- 只有 CodexBar 确实停止了自己持有的防睡眠状态后才发送低电量通知--### Helper 授权与状态--防睡眠需要随 App 嵌入的 `CodexBarHelper` LaunchDaemon 修改系统级睡眠状态--- 首次开启时通过 macOS `SMAppService` 注册-- macOS 要求批准后台项目时, 设置页显示打开系统设置按钮-- Helper 文件缺失或注册失败时, 设置页显示错误且不执行防睡眠-- App 更新导致 Helper 内容变化时会刷新注册并校验睡眠状态-- App 退出前会先释放 Helper 租约并恢复由 CodexBar 修改的睡眠状态-- XPC 连接意外中断后, Helper 会在宽限期结束后释放失联客户端租约-- Helper 自身启动和终止时会根据持久化所有权记录恢复未完成的睡眠状态--### 与其他防睡眠来源共存--如果任务开始前 `SleepDisabled` 已经由其他 App 或用户设为 1, CodexBar 会把来源标记为外部--- CodexBar 不会把外部设置据为己有-- 任务结束时不会写回 `pmset` 或恢复外部来源的设置-- 外部设置恢复为 0 而任务仍在运行时, CodexBar 会重新检查并按需接管-- 主面板仍显示咖啡杯, tooltip 和设置页会说明系统睡眠由其他来源关闭--## 语言与地区--CodexBar 提供简体中文和英文界面, 默认跟随 macOS 的 App 语言偏好--需要单独切换时, 可在 macOS 系统设置的语言与地区中为 CodexBar 指定 App 语言--日期 时间 时长 百分比 月历和星期顺序继续按照当前地区格式显示--## 日志与排查--- 右键菜单栏图标选择日志, 或在主面板打开时按 `⌘L`-- 日志窗口保留当前 App 进程最近 500 条 app-server 请求-- 每条记录展示请求时间 方法 状态和响应时间-- 展开后可查看请求 响应或错误的单行预览-- 完整内容可在独立窗口中查看或复制-- JSON 内容会格式化并提供基础语法高亮-- 日志存储只在内存中, 可手动清空, 退出 App 后不会保留--## 隐私与数据--### 数据访问和网络行为--| 行为 | 目的 | 数据边界 |-| --- | --- | --- |-| 与本机 `codex app-server` 通过 stdio 通信 | 获取账户 额度 Token 用量 Hook 列表和 Codex 配置 | 本机进程通信 |-| 请求 OpenAI 重置次数接口 | 查询手动重置次数的过期时间 | 只在存在可用重置次数时执行 |-| Sparkle 更新检查 | 获取 appcast 和安装更新 | 使用配置的 HTTPS feed |-| CloudKit 同步 | 同步多设备每日 Hook 聚合 | 仅在用户开启跨设备同步后使用 private database |--### 本机保存的数据--| 数据 | 内容 | 位置或生命周期 |-| --- | --- | --- |-| Hook 原始事件 | 选定的结构化事件字段, 不含 prompt 回复 工具参数或工具输出 | `~/Library/Application Support/CodexBar/HookEvents/events`, 保留 210 天 |-| Hook 每日聚合 | 事件计数 会话与轮次计数 项目名计数和模型计数 | `~/Library/Application Support/CodexBar/HookEvents/daily.jsonl`, 保留 210 天 |-| 异常会话保护 | 哈希任务标识和时间戳 | `~/Library/Application Support/CodexBar/ActivityProtection/state.json`, 最长 24 小时 |-| App 偏好 | 开关 阈值 快捷键和通知去重状态 | macOS UserDefaults |-| app-server 日志 | 最近 500 条请求和响应 | 仅当前进程内存 |--### CloudKit 上传内容--CloudKit 每条记录包含设备伪标识 日期 来源 generation 各类 Hook 事件计数 会话与轮次计数 项目显示名计数 模型计数和更新时间--CloudKit 不上传以下内容--- 原始 Hook 事件文件-- session ID turn ID 和 agent ID-- 完整工作目录路径-- prompt Codex 回复 工具参数或工具输出-- Codex 账户 额度 Token 用量和 app-server 交互日志-- 异常会话保护记录--### 日志隐私--- 系统日志只记录操作结果 状态分类 计数和错误阶段-- 系统日志不记录账户额度数值 Token 用量 项目名 任务内容 session ID turn ID 或 OAuth token-- app-server 交互日志可能包含请求和响应内容, 但只存在当前 App 进程内存并由用户主动打开查看--## 实现--Swift 6 + SwiftUI + AppKit, 使用 MVVM, 外部依赖为 Sparkle--工程开启 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`, 共享状态收敛进 actor, 跨进程 Hook 文件写入由 `flock` 保护--```mermaid-flowchart LR- subgraph L1["额度与用量"]- A1["本机 Codex"] -->|"app-server stdio"| A2["账户 额度 Token 用量"]- end-- subgraph L2["Hook 历史统计"]- B1["Codex Hook"] --> B2["本机按日 JSONL"]- B2 --> B3["每日聚合"]- end-- subgraph L3["实时任务"]- C1["Hook 事件"] --> C3["任务状态与异常会话保护"]- C2["本机 rollout 生命周期"] --> C3- end-- A2 --> UI["菜单栏和主面板"]- B3 --> UI- C3 --> UI- B3 --> Cloud["可选 CloudKit 同步"]- C3 --> Notice["通知和触觉反馈"]- C3 --> KeepAlive["按任务防睡眠"]-```--<details>-<summary><b>关键实现约束</b></summary>--<br>--**Hook 子进程模式**--App 使用 `--hook-event` 参数启动时不初始化 UI, 只从 stdin 读取 Hook payload, 在文件锁内追加到当日 JSONL 后立即退出--**历史聚合**--原始 Hook 事件与每日聚合保留 210 天--每日聚合只为最近 3 天保留 session 和 turn ID 列表, 更早日期只保留计数--聚合算法版本变化或已压缩日期收到新事件时, 从仍在保留期内的原始 JSONL 完整重建--**实时任务**--`CodexActivityMonitor` 是菜单栏图标 活动卡片 通知和防睡眠的统一任务状态来源--`HookEventTailReader` 增量读取 Hook JSONL, `CodexSessionLifecycleReader` 只从 rollout 提取任务生命周期和最近进展字段--**异常会话保护**--异常会话保护以 Hook 事件和 rollout 最近进展时间为依据--达到静默阈值后先尝试提交本地通知, 随后隐藏任务并让它退出防睡眠计算--新进展到达后恢复任务--系统睡眠 Hook 历史回放和 Hook 数据源不可用期间暂停判定--唤醒后等待新一轮 Hook 增量读取与 rollout 对账完成再恢复--**CodexBar Helper 权限**--`CodexBarHelper` 是随 App 嵌入的 LaunchDaemon, 只暴露防睡眠租约 状态查询和更新恢复 XPC--Helper 对外只执行 `/usr/bin/pmset`, 使用 `-g` 查询状态, 使用 `-a disablesleep 0/1` 修改状态--Helper 只在 CodexBar 自己将 `SleepDisabled` 从 0 改为 1 时取得所有权--任务开始时已经为 1 则视为外部来源, 不修改该值--Helper 启动时读取自身签名并生成 XPC 客户端 requirement, 修改签名或 bundle ID 会导致连接被拒绝--</details>--## 从源码构建--```bash-git clone https://github.com/bob-zebedy/CodexBar.git-cd CodexBar-xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/platform=macOS' build-```+## 隐私-Debug 和 Release 使用不同的 App 与 Helper bundle ID+CodexBar 所有数据都在本地处理, 只有在开启跨设备同步功能后才会将各种汇总的数据上传到 iCloud private database-格式化和静态检查使用 `swiftformat` 和 `swiftlint`+完整的数据访问, 本机存储和网络边界见 [数据, 同步与隐私](Docs/UserGuide/sync-data-privacy.md)## 反馈-Bug 功能建议或使用问题都欢迎通过 [Issues](https://github.com/bob-zebedy/CodexBar/issues) 反馈+Bug, 功能建议或使用问题欢迎通过 [GitHub Issues](https://github.com/bob-zebedy/CodexBar/issues) 反馈## 许可证