Skip to content

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

docs: 重构项目文档结构

Bobcc05cd14261a
diff --git a/Docs/DeveloperGuide/README.md b/Docs/DeveloperGuide/README.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 2038c94..07e40c7 100644
--- a/README.md
+++ b/README.md
@@ -4,15 +4,14 @@
# CodexBar
-**在 macOS 菜单栏一眼看清 Codex 相关信息**
+**在 macOS 菜单栏一眼看清 Codex**
[![macOS](https://img.shields.io/badge/macOS-15.0+-000000?logo=apple&logoColor=white)](https://www.apple.com/macos/)
-[![Swift](https://img.shields.io/badge/Swift-6-F05138?logo=swift&logoColor=white)](https://swift.org)
[![Release](https://img.shields.io/github/v/release/bob-zebedy/CodexBar?color=1F6FEB)](https://github.com/bob-zebedy/CodexBar/releases)
[![Downloads](https://img.shields.io/github/downloads/bob-zebedy/CodexBar/total?color=2EA043)](https://github.com/bob-zebedy/CodexBar/releases)
[![License](https://img.shields.io/github/license/bob-zebedy/CodexBar?color=8957E5)](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
```bash
brew 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) 反馈
## 许可证