Skip to content

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

docs: 完善开发者指南设计说明

Bob80e34902fa93
diff --git a/Docs/DeveloperGuide/README.md b/Docs/DeveloperGuide/README.md
index 8354571..79be7f4 100644
--- a/Docs/DeveloperGuide/README.md
+++ b/Docs/DeveloperGuide/README.md
@@ -1,53 +1,126 @@
# CodexBar 开发者指南
-本指南面向希望理解 CodexBar 架构,调试数据链路或参与开发的开发者。
+本指南面向希望理解 CodexBar 架构, 调试数据链路或参与开发的开发者
-内容覆盖 CodexBar 的架构,数据链路,核心状态机和系统集成。产品功能和操作方式见 [用户指南](../UserGuide/README.md)
+内容不仅描述模块做什么, 还解释为什么这样划分职责, 哪些失败路径是刻意保守处理, 以及修改实现时必须继续维持哪些不变量
+
+产品功能和操作方式见 [用户指南](../UserGuide/README.md)
+
+## 文档目标
+
+开发者指南需要帮助读者完成 4 类工作
+
+- 建立系统模型, 理解数据从哪里来, 在哪里变成状态, 最终由谁消费
+- 定位修改入口, 知道某个行为的唯一状态所有者和副作用边界
+- 理解设计取舍, 避免把看似多余的 generation, stale 标记或恢复步骤简化掉
+- 验证改动, 能从不变量和故障场景推导验收范围
+
+每篇专题文档尽量按同一顺序组织
+
+```text
+目标与约束
+ -> 数据或控制流
+ -> 状态所有权
+ -> 关键设计理由
+ -> 失败与恢复
+ -> 修改指南
+ -> 验证场景
+```
## 阅读路线
-第一次了解项目时,建议按以下顺序阅读:
+第一次了解项目时, 建议按以下顺序阅读
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)
+2. [设计原则与关键决策](design-decisions.md)
+3. [app-server 数据链路](app-server.md)
+4. [Hook 采集与历史聚合](hook-and-aggregation.md)
+5. [实时任务监控](activity-monitor.md)
+6. [防睡眠系统](sleep-prevention.md)
+7. [CloudKit 同步](sync.md)
+8. [通知系统](notifications.md)
+9. [UI 与应用生命周期](ui-and-lifecycle.md)
+10. [数据与隐私边界](data-and-privacy.md)
+11. [开发与验证](development.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) | 工程结构,构建检查,调试和变更验收 |
+| [整体架构](architecture.md) | 进程, 模块, 生命周期, actor 边界和 3 条数据链路 |
+| [设计原则与关键决策](design-decisions.md) | 跨模块设计动机, 系统不变量, 失败优先级和实现小巧思 |
+| [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) | 工程结构, 构建检查, 调试和变更验收 |
+
+## 按修改目标查找
+
+| 修改目标 | 先读 | 同时核对 |
+| --- | --- | --- |
+| 新增账户或用量字段 | [app-server 数据链路](app-server.md) | [数据与隐私边界](data-and-privacy.md) |
+| 新增 Hook 事件或历史指标 | [Hook 采集与历史聚合](hook-and-aggregation.md) | [CloudKit 同步](sync.md) |
+| 修改任务状态或 terminal 判定 | [实时任务监控](activity-monitor.md) | [通知系统](notifications.md), [防睡眠系统](sleep-prevention.md) |
+| 修改菜单, 窗口或快捷键 | [UI 与应用生命周期](ui-and-lifecycle.md) | [开发与验证](development.md) |
+| 修改通知触发或去重 | [通知系统](notifications.md) | 对应的数据来源专题 |
+| 修改防睡眠策略或 helper | [防睡眠系统](sleep-prevention.md) | [数据与隐私边界](data-and-privacy.md) |
+| 修改同步字段或合并规则 | [CloudKit 同步](sync.md) | [Hook 采集与历史聚合](hook-and-aggregation.md) |
+| 修改持久化结构或默认值 | [开发与验证](development.md) | [设计原则与关键决策](design-decisions.md) |
## 核心设计约束
-- 启动时必须先处理 `--hook-event` 模式,该模式不能初始化 UI
-- app-server 额度与用量,Hook 历史聚合,实时任务监控是 3 条独立数据链路
+- 启动时必须先处理 `--hook-event` 模式, 该模式不能初始化 UI
+- app-server 额度与用量, Hook 历史聚合, 实时任务监控是 3 条独立数据链路
- `CodexActivityMonitor` 是任务状态的唯一来源
-- UI,Controller,ViewModel 和 Settings 默认在 `MainActor` 上运行
+- UI, Controller, ViewModel 和 Settings 默认在 `MainActor` 上运行
- 阻塞 I/O 和共享可变状态必须离开主 actor
-- CodexBarHelper 只负责睡眠控制,不增加网络,任意命令执行或额外文件访问
+- CodexBarHelper 只负责睡眠控制, 不增加网络, 任意命令执行或额外文件访问
- Hook 配置修改必须保留用户和其他应用已有的 handler
-- 聚合语义变化必须递增聚合 schema,并从原始事件完整重建
-- 缺失的 Hook 计数字段表示历史来源不可用,不能解释为明确的 `0`
+- 聚合语义变化必须递增聚合 schema, 并从原始事件完整重建
+- 缺失的 Hook 计数字段表示历史来源不可用, 不能解释为明确的 `0`
+
+## 核心术语
+
+| 术语 | 在本项目中的准确含义 |
+| --- | --- |
+| snapshot | 可重复读取的当前状态, 不代表刚刚发生了一次事件 |
+| transition | 由可信 live 输入产生的一次性状态变化, 可驱动通知等副作用 |
+| bootstrap | 从现有本地数据恢复内存基线, 不应补发历史副作用 |
+| stale | 有可展示旧值, 但本轮未能从来源确认 |
+| unavailable | 当前无法得到可信来源, 不能等价为空或 `0` |
+| generation | 数据源或异步操作的代际, 用于拒绝迟到结果 |
+| source generation | 某日原始 Hook 文件的来源身份, 与代码 schema 不同 |
+| owned | 系统状态由 CodexBar 完成切换并有权恢复 |
+| external | 系统状态已经由 CodexBar 之外的来源设置 |
+
+## 阅读源码的建议
+
+先确认状态所有者, 再沿消费者反向阅读
+
+例如修改等待批准行为时, 推荐顺序是
+
+```text
+CodexActivityTask
+ -> CodexActivityMonitor
+ -> CodexActivitySnapshot / transition
+ -> CodexNotificationService
+ -> KeepAliveController
+ -> SwiftUI View
+```
+
+从 View 开始搜索通常只能看到最终展示条件, 容易漏掉 bootstrap, 去重和恢复语义
## 主要入口
-- 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)
+- 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
index 01dd9df..34c2054 100644
--- a/Docs/DeveloperGuide/activity-monitor.md
+++ b/Docs/DeveloperGuide/activity-monitor.md
@@ -1,15 +1,28 @@
# 实时任务监控
+## 设计出发点
+
+实时任务不是 Hook 事件的直接映射
+
+同一个 turn 可能出现事件缺失, 迟到, 重复, 只有 session ID, 新 prompt 覆盖旧 turn, `Stop` 与 rollout terminal 先后到达, 或 App 在任务已经运行一段时间后才启动
+
+`CodexActivityMonitor` 的工作是把这些不完整观察合并成一个保守的任务状态机, 并同时提供两种不同输出
+
+- snapshot 表示现在可以展示什么
+- transition 表示刚刚发生了什么, 可以驱动一次性副作用
+
+如果消费者各自从 Hook 列表推断任务, 菜单栏, 通知和防睡眠会在边界场景下得出不同结论
+
## 目标
-实时任务链路需要回答 4 个问题:
+实时任务链路需要回答 4 个问题
- 当前是否有任务正在运行
- 当前是否在等待用户批准
- 最近任务是完成还是中断
- 哪些运行任务已经长时间没有进展
-Hook 事件提供低延迟信号,rollout 文件提供权威生命周期补充。[`CodexActivityMonitor.swift`](../../CodexBar/Services/Workflow/CodexActivityMonitor.swift) 合并两者并发布唯一任务快照:
+Hook 事件提供低延迟信号, rollout 文件提供权威生命周期补充. [`CodexActivityMonitor.swift`](../../CodexBar/Services/Workflow/CodexActivityMonitor.swift) 合并两者并发布唯一任务快照
```text
Hook JSONL -> HookEventTailReader -----+
@@ -17,30 +30,85 @@ Hook JSONL -> HookEventTailReader -----+
rollout JSONL -> SessionLifecycleReader+
```
+### 两种来源的分工
+
+| 信息 | 优先来源 | 补充来源 |
+| --- | --- | --- |
+| prompt, tool, compact, subagent 实时进展 | Hook | rollout progress |
+| 用户审批候选 | `PermissionRequest` | rollout reviewer 确认 |
+| turn 起点 | `UserPromptSubmit` | rollout startedAt 或历史回查 |
+| 完成候选 | `Stop` | rollout terminal |
+| 完成与中断分类 | rollout terminal | grace 到期 fallback |
+| effort | Hook recorder 回查 | rollout lifecycle backfill |
+
+Hook 优先解决低延迟, rollout 优先解决语义准确性. 两者不是简单按时间戳覆盖, 每个字段都有自己的可信来源
+
+### snapshot 和 transition 为什么分开
+
+snapshot 可以在 View 重建, 新消费者订阅或设置变化时反复读取. transition 只允许 live 数据产生一次
+
+例如 App 启动时 bootstrap 恢复出一个已经等待批准的任务
+
+- snapshot 应显示它正在等待
+- transition 不应发布等待事件
+- 通知服务因此不会补发一条历史通知
+
+任务完成也一样. 通知服务消费 `.completed` transition, 不扫描 `recentCompletions`, 避免 App 重启或 UI 刷新重复提醒
+
## HookEventTailReader
-[`HookEventTailReader.swift`](../../CodexBar/Services/Workflow/HookEventTailReader.swift) 是 actor,默认每 2 秒检查 Hook 事件文件。
+[`HookEventTailReader.swift`](../../CodexBar/Services/Workflow/HookEventTailReader.swift) 是 actor, 默认每 2 秒检查 Hook 事件文件
### Bootstrap
-首次启动读取最近 24 小时文件以建立任务基线:
+首次启动读取最近 24 小时文件以建立任务基线
- 每块最多读取 512 KB
- 最多尝试 3 次获得稳定文件边界
- 使用 inode 和 size 判断读取期间是否发生替换或追加
- bootstrap 结果不会触发历史完成或等待通知
-如果无法得到稳定边界,reader 会跳到当前文件末尾并发布显式不健康状态。这样不会把不完整历史误解释为真实任务变化。
+如果无法得到稳定边界, reader 会跳到当前文件末尾并发布显式不健康状态. 这样不会把不完整历史误解释为真实任务变化
+
+### bootstrap 是一个逻辑事务
+
+24 小时窗口可能跨两个自然日文件, 单个文件又会分成多个 512 KB batch 发送
+
+monitor 在 `.bootstrapStart` 时先清空上一次恢复态并暂停副作用, 接收所有 `.bootstrapEvents`, 最后在 `.bootstrapEnd` 才统一
+
+- 用 rollout 补齐生命周期
+- 应用持久化异常保护记录
+- 按当前阈值静默对账
+- 定向回查缺失 prompt 起点
+- 发布完整 snapshot
+
+中间 batch 不应让 UI 或通知看到半恢复状态
+
+### 稳定边界为什么要重试 3 次
+
+reader 在每次尝试开始时固定所有日期文件的 inode 和 size, 读取到这些上界后再次验证
+
+- 历史日期必须 inode 和 size 都不变
+- 当前日期允许在固定上界之后继续 append
+- 当前自然日不能在读取期间跨过零点
+
+任何条件不成立都从新的基线重试. 连续 3 次失败后跳到当前文件末尾, 是为了避免 App 永远卡在 bootstrap. 代价通过 degraded health 明确传给异常保护, 而不是假装成功
+
+### 为什么只推进完整行 offset
+
+Hook recorder 可能正在写最后一行. reader 只把最后一个 newline 之前的字节计入 `completeOffset`
+
+半行不会丢弃, 也不会被当作损坏事件. 下一轮从旧 offset 重新读取, 等行完整后再提交
### 跨日与文件替换
-正常跨日时先排空旧日期文件,再切换到新日期文件。inode 改变或文件缩小时重新 bootstrap,不沿用旧游标。
+正常跨日时先排空旧日期文件, 再切换到新日期文件. inode 改变或文件缩小时重新 bootstrap, 不沿用旧游标
-当 `UserPromptSubmit` 早于当前增量窗口时,reader 可以向前回查最多 8 MB,为现存任务补齐 prompt 起点。
+当 `UserPromptSubmit` 早于当前增量窗口时, reader 可以向前回查最多 8 MB, 为现存任务补齐 prompt 起点
### drainNow 读取屏障
-`drainNow()` 不是普通的立即刷新提示。每个调用方必须等待一轮在本次请求之后开始的读取:
+`drainNow()` 不是普通的立即刷新提示. 每个调用方必须等待一轮在本次请求之后开始的读取
```text
调用 drainNow
@@ -50,33 +118,104 @@ rollout JSONL -> SessionLifecycleReader+
-> 返回该轮结果
```
-调用发生前已经在执行的读取不能满足屏障。reader 被替换,数据源不可用或任务取消时,调用方不能使用旧快照继续判定。
+调用发生前已经在执行的读取不能满足屏障. reader 被替换, 数据源不可用或任务取消时, 调用方不能使用旧快照继续判定
+
+### 屏障的具体代际语义
+
+每次 `drainNow()` 都递增 `requestedDrainGeneration` 并注册独立 waiter
+
+如果读取已经在途, 新请求只把 `hasPendingDrain` 设为 true. 当前轮完成后 reader 必须再开始一轮, 这轮才会捕获该请求的 generation
+
+一轮读取可以同时满足在它开始前排队的多个 waiter, 但不能满足读取开始后才加入的 waiter. 这正是唤醒恢复需要的 happens-after 保证
+
+actor 在 `await` 期间可以重入, 因此 `isProcessingReads` 和 `hasPendingDrain` 共同把所有外部请求收敛成一个串行 drain loop, 避免两个读取同时推进 offset
## 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
+- 只解析生命周期, turn, progress, effort 和 reviewer
- 不读取或保存对话内容用于产品展示
-Hook 的 `Stop` 只是完成候选。rollout 中的 terminal 状态用于区分真正完成,用户取消和异常中断。
+Hook 的 `Stop` 只是完成候选. rollout 中的 terminal 状态用于区分真正完成, 用户取消和异常中断
+
+### session 文件如何定位
+
+reader 先检查最可能的少量目录
+
+1. 任务开始日期对应的 `sessions/YYYY/MM/DD`
+2. 当前日期目录
+3. `archived_sessions`
+
+resume 可能继续很早以前创建的 session. 快速路径找不到时, 每个活跃 session 生命周期最多执行一次递归兜底, 避免每秒 poll 都扫描整个 sessions 树
+
+文件被移到 archive 后, 已缓存 URL 不存在会清除 cursor 并允许重新完整定位
+
+### rollout cursor 为什么从尾部 512 KB 开始
+
+实时任务只需要活跃 turn 附近的 lifecycle, 全量读取一个长期 session 会增加常驻 I/O
+
+初始 cursor 从最后 512 KB 开始并丢弃第一条可能不完整的行. 如果 effort 仍缺失, 对具体 turn 再定向回查最多 8 MB
+
+effort backfill 只针对至少运行 2 秒, 尚未 terminal 且仍缺 effort 的任务, 同一 turn 重试间隔 10 秒. 这避免刚创建任务时立刻做大范围回查
+
+### 为什么只解析结构事件
+
+共享的 `CodexRolloutLineEnvelope` 只提取 turn context, lifecycle 和 progress 所需字段. prompt, response 和 tool 内容不会进入活动模型
+
+这既收紧隐私边界, 也降低大 rollout 的解码成本. 新增实时字段时应先扩展这份最小 envelope, 不应把完整 transcript 解码成通用 JSON 树
## 任务身份
-任务 key 按可用信息选择最精确身份:
+任务 key 按可用信息选择最精确身份
1. `session ID + turn ID`
2. `session ID`
3. 匿名 project key
-新的 prompt 会替代同一 session 的旧 turn。旧 turn 进入最长 5 秒 terminal grace,给迟到的结束事件留出对账时间。
+新的 prompt 会替代同一 session 的旧 turn. 旧 turn 进入最长 5 秒 terminal grace, 给迟到的结束事件留出对账时间
+
+subagent 事件更新父任务的 subagent 活动, 不创建独立顶层任务卡片
+
+### 身份选择为什么按精度降级
+
+`session ID + turn ID` 能精确区分同一 session 中顺序执行的 turn, 是首选身份
+
+某些事件只有 session ID. 此时 session key 允许事件仍然参与状态, 但终态匹配必须更保守. 如果同一 session 同时存在多个候选, monitor 返回 ambiguous 而不是猜一个任务结束
+
+完全没有 session ID 时只能使用 project key. 这个 key 可能把同项目并发匿名任务合并, 所以匿名任务只承担可撤销的 UI 展示, 不驱动通知, 防睡眠或持久化保护
-subagent 事件更新父任务的 subagent 活动,不创建独立顶层任务卡片。
+### 为什么新 prompt 不直接把旧 turn 判为中断
+
+同一 session 的 turn 顺序执行. 新 prompt 到来时旧 turn 必须立即离开活跃列表, 否则 UI 会短暂显示两个顶层任务
+
+但新 prompt 可能早于旧 turn 的 rollout terminal 到达. 直接记录中断会误判一个正常完成的任务
+
+因此旧 turn 被移到 `pendingTerminalTasks`
+
+- 从 active snapshot 立即移除
+- 保留原任务元数据和开始时间
+- 等待最多 5 秒 rollout terminal
+- terminal 到达时准确分类 completed 或 aborted
+- grace 到期仍无终态时按保守 fallback 收口
+
+`SessionEnd` 使用同一个终态确认窗口, 只是按 session 一次移动所有不晚于该事件的任务
+
+### 迟到事件如何被拒绝
+
+任务保存 `lastActivityAt`, terminal 记忆保存完成或中断时间
+
+- 早于当前任务最后活动的事件不覆盖新状态
+- 不晚于已记录 terminal 的新 prompt 不会复活旧任务
+- `Stop` 命中多个候选时不猜测
+- 已进入 terminal 去重记忆的 key 会清除异常顺序留下的恢复任务
+
+这种比较依赖事件自身时间, 而不是 batch 到达顺序, 因为跨进程文件写入和 rollout poll 都可能让旧事件晚到
### 匿名任务
@@ -88,36 +227,85 @@ subagent 事件更新父任务的 subagent 活动,不创建独立顶层任务
匿名任务不向通知消费者发布等待批准或完成 transition, 不触发任务触觉反馈, 不进入 KeepAlive 的运行中或等待任务集合, 不参与异常会话保护. `activityProtectionIdentifier` 对匿名 key 返回 nil, 保护状态文件不会保存匿名任务记录
+### 为什么匿名任务仍保留在 UI
+
+缺少 session ID 不等于任务不存在. 完全丢弃会让用户看到 Codex 正在工作, CodexBar 却显示空闲
+
+保留 UI 展示同时禁止高影响副作用, 是对不确定身份的分层处理
+
+- 可见性错误可以由后续事件自动修正
+- 错误通知会打扰用户
+- 错误防睡眠可能持续数小时
+- 持久化匿名 project key 可能压制未来另一个真实任务
+
+因此匿名任务使用橙色虚线人物图标明确表达能力受限, 而不是伪装成普通精确任务
+
## 状态机
-内部活动任务主要有以下状态:
+内部活动任务主要有以下状态
| 状态 | 含义 |
| --- | --- |
| `running` | Codex 正在处理当前 turn |
| `waitingApproval` | 当前 turn 明确等待用户批准 |
-| `suppressed` | 任务被异常会话保护隐藏,等待新进展恢复 |
+| `suppressed` | 任务被异常会话保护隐藏, 等待新进展恢复 |
-`PermissionRequest` 只有在 reviewer 是用户时才进入 `waitingApproval`。自动审批或策略审批不会被视为用户等待。
+`PermissionRequest` 只有在 reviewer 是用户时才进入 `waitingApproval`. 自动审批或策略审批不会被视为用户等待
-终止信号按可靠性对账:
+终止信号按可靠性对账
- `SessionEnd` 结束 session
- rollout terminal 区分完成和中断
- `Stop` 在缺少更强信号时形成完成候选
- 新 prompt 可以结束旧 turn 的展示生命周期
+### 事件到状态的主要转换
+
+| 当前状态 | 输入 | 新状态 | 额外动作 |
+| --- | --- | --- | --- |
+| 不存在 | `UserPromptSubmit` | running | 保存可信 startedAt |
+| 不存在 | 顶层 tool 或 compact | running | 恢复任务, startedAt 暂缺 |
+| running | tool, compact, subagent progress | running | 更新 last progress 和 generation |
+| running | `PermissionRequest` + reviewer user | waitingApproval | 发布 live waiting transition |
+| waitingApproval | 新进展 | running | 清除 pending approval 和保护记录 |
+| running 或 waiting | `Stop` | terminal candidate | 保存完成或等待 rollout 对账 |
+| active | 新 prompt 或 `SessionEnd` | pending terminal | 从快照移除并开启 5 秒 grace |
+| running | 静默超过阈值 | suppressed | 隐藏并退出防睡眠贡献 |
+| suppressed | 新进展 | running | 清除持久化保护与旧通知 |
+
+### waiting approval 为什么采用两阶段确认
+
+`PermissionRequest` 说明进入审批流程, 但 reviewer 可能是 user, policy 或 auto review
+
+Hook event 到达时如果已经带有 reviewer, task 可以立即确认. reviewer 缺失时先保存 `pendingApprovalRequestedAt`, rollout poll 补齐后再决定是否进入 `waitingApproval`
+
+只有 reviewer 明确为 user 才发布 waiting transition. 不确定时维持 running 比误报用户正在被等待更符合事实
+
+### effort 为什么可能变成 `mixed`
+
+同一 turn 的多个上下文事件可能报告不同 reasoning effort. Task 不让最后一条静默覆盖前一条, 而是在观察到冲突后标记为 `mixed`
+
+这向 UI 表达任务生命周期内确实出现过多个值, 避免展示一个看似精确但只代表最后观察的 effort
+
+### subagent 数为什么允许 unknown
+
+subagent 的 turn ID 属于 subagent 自己, 父任务只能通过共享 session 关联
+
+只有同 session 恰好有一个 active 父任务, 没有 pending terminal 歧义, 并且 start/stop 带稳定 agent ID 时, active subagent count 才可靠
+
+缺少 ID, 先看到 stop 或同 session 有多个候选时, monitor 将可靠性降为 false, UI 不展示伪精确数字
+
## 快照优先级
-多个任务和短时状态同时存在时,对外快照按以下优先级表达:
+多个任务和短时状态同时存在时, 对外快照按以下优先级表达
```text
等待批准 > 运行中 > 最近完成 > 最近中断 > 空闲
```
-完成状态在菜单栏保留 30 秒绿色提示。活动中心保留最近 10 分钟任务,terminal 去重记忆保留 24 小时。
+完成状态在菜单栏保留 30 秒绿色提示. 活动中心保留最近 10 分钟任务, terminal 去重记忆保留 24 小时
-快照由以下模块消费:
+快照由以下模块消费
- 菜单栏状态点
- 主面板任务卡片
@@ -125,9 +313,35 @@ subagent 事件更新父任务的 subagent 活动,不创建独立顶层任务
- 通知系统
- 防睡眠控制器
+### 为什么最近完成和最近中断有不同展示权重
+
+完成会在菜单栏保留 30 秒绿色高亮, 这是短时正反馈. 中断只进入最近记录, 不发布完成 transition, 也不显示绿色状态
+
+任务中心保留 terminal 10 分钟, 但用于防止迟到事件重复完成的 key 会保留 24 小时. 展示期限和去重期限解决不同问题, 不能为了"统一缓存"合并
+
+### 为什么只在快照变化时发布
+
+monitor 每秒 poll rollout, 还会按多个 deadline 自行刷新. 如果每轮都给 `@Published` 赋相同值, SwiftUI 和所有 Combine 消费者会重复计算
+
+新快照先与当前值比较, 只有结构变化才发布. 运行时长文案由 View 使用当前时间格式化, 不要求每秒修改任务对象
+
+### 排序为什么有稳定兜底
+
+同一 batch 中多个任务可能具有相同时间戳, Swift sort 又不是稳定排序
+
+所有列表先按最近时间降序, 时间相同再按 display UUID 字符串排序. 稳定顺序让 SwiftUI diff 不会因为等价任务随机交换位置而产生跳动
+
+### 清理采用最近 deadline
+
+monitor 同时管理完成高亮, terminal grace, 活动保留, 历史保留, terminal 去重和保护记录过期
+
+它不使用固定高频 timer 扫描所有状态, 而是收集所有未来 deadline, 只为最近一项安排 Task. 到点刷新后再计算下一项
+
+这种实现减少常驻菜单栏 App 的无意义唤醒, 也保证每种保留期都能在没有新 Hook 事件时准时生效
+
## 系统睡眠与唤醒
-系统即将睡眠时暂停异常会话保护判断。唤醒后执行严格恢复顺序:
+系统即将睡眠时暂停异常会话保护判断. 唤醒后执行严格恢复顺序
1. 进入恢复状态并继续暂停保护
2. 等待 `HookEventTailReader.drainNow()` 成功
@@ -135,31 +349,46 @@ subagent 事件更新父任务的 subagent 活动,不创建独立顶层任务
4. 使用新 Hook 结果和 rollout 结果统一对账
5. 恢复异常会话保护判断
-如果新一轮读取失败,reader 被更换或数据源不可用,不得使用睡眠前快照继续判断任务静默。
+如果新一轮读取失败, reader 被更换或数据源不可用, 不得使用睡眠前快照继续判断任务静默
+
+### 为什么系统睡眠期间必须暂停静默计时
+
+系统睡眠时 Hook 与 rollout 都不会正常产生进展. 如果只比较墙上时间, 一次两小时睡眠会让所有运行任务在唤醒瞬间被判为异常静默
+
+保护计时使用 `SuspendingClock` 安排下一次检查, 但系统时间变化和数据源恢复仍需要显式重算. will-sleep 先进入 recovery, did-wake 再通过新的数据读取屏障恢复判定
+
+### 唤醒顺序为何不能交换
+
+rollout 对账必须发生在 Hook drain 成功之后
+
+如果先读 rollout, 此时 monitor 中可能还没有睡眠期间刚追加的任务 key, lifecycle 结果无法关联. 如果先恢复保护判定, 则会基于睡前 last progress 误隐藏任务
+
+`readerGeneration` 防止唤醒 Task 返回时 reader 已因 Hook 设置变化被替换. `recoveryGeneration` 防止两次睡眠或设置变化交错后, 较早恢复流程提前解除暂停
## 异常会话保护
异常会话保护只在防睡眠主开关开启时工作, 只处理非匿名 `running` 任务
-等待批准任务不参与静默阈值判断。原因是等待批准本身就是一个合法的无进展状态。
+等待批准任务不参与静默阈值判断. 原因是等待批准本身就是一个合法的无进展状态
-可选阈值为:
+可选阈值为
- 30 分钟
-- 1 小时,默认值
+- 1 小时, 默认值
- 2 小时
- 4 小时
-任务达到阈值后:
+任务达到阈值后
1. 先持久化保护记录
-2. 从活动快照中隐藏任务
-3. 尝试发送保护通知
-4. 如果任务出现新进展,清除抑制并恢复展示
+2. 同时启动通知提交和 3 秒 grace
+3. 通知提交完成或 grace 到期后再次校验候选
+4. 候选仍有效时从活动快照隐藏任务
+5. 如果期间或之后出现新进展, 清除保护并恢复展示
-通知提交有 3 秒宽限,但隐藏任务不依赖通知成功。这可以保证通知权限或系统服务失败时,防睡眠仍能释放。
+隐藏任务不依赖通知成功. 3 秒只是等待解释性通知提交的最大时间, 到期后仍会释放防睡眠
-保护判断在以下阶段暂停:
+保护判断在以下阶段暂停
- Hook bootstrap
- 系统睡眠
@@ -167,9 +396,55 @@ subagent 事件更新父任务的 subagent 活动,不创建独立顶层任务
- Hook 数据源不可用
- reader 正在更换
+### 保护针对的故障模型
+
+Hook 或 Codex 异常退出后, 可能缺少 `Stop`, `SessionEnd` 和 rollout terminal. 任务会一直停在 running, 进而让防睡眠永久生效
+
+异常会话保护不是判断 Codex 是否"真的卡住", 它只处理一个可观察事实: 非匿名 running 任务在可信数据源下超过阈值没有任何 Hook 或 rollout 进展
+
+等待批准被排除, 因为等待用户本来就是合法静默. 匿名任务被排除, 因为 project key 不足以证明保护记录属于哪一个具体任务
+
+### progress generation 的作用
+
+只比较时间戳不足以保护异步尝试. 两条进展可能具有相同秒级时间, 设置阈值也可能在通知提交期间变化
+
+每次有效进展都会递增 `progressGeneration`. 保护候选保存
+
+- task display ID
+- last progress timestamp
+- progress generation
+- 当时的阈值
+
+通知返回或 3 秒 grace 到期时, 四项都必须仍匹配才允许 suppress. 任意新进展或阈值变化都会让旧尝试失效
+
+### 为什么先持久化再隐藏
+
+一旦任务从快照隐藏, App 可能随即退出或系统休眠. 如果保护记录还没有进入持久化队列, 重启 bootstrap 会再次展示并重新支撑防睡眠
+
+因此候选开始时先写入记录, 再等待通知提交, 最后隐藏. 通知权限或系统服务失败不影响 suppress, 因为释放错误防睡眠才是保护的核心目标
+
+### 3 秒通知宽限的含义
+
+保护通知是有价值的解释, 但不能无限阻塞释放防睡眠
+
+- 通知先成功提交时立即完成 suppress
+- 3 秒内仍未完成时直接 suppress
+- 通知稍后成功返回但 attempt 已失效时立即撤回
+- grace 内出现新进展时取消 attempt 和持久化记录
+
+这个窗口只约束通知副作用, 不改变静默阈值本身
+
+### 阈值改变如何对账
+
+阈值变短时, 已经超过新阈值的 running 任务会立即重新判定
+
+阈值变长时, 尚未超过新阈值的 suppressed 任务会静默恢复, 清除对应保护记录和通知. 已经仍超过新阈值的任务继续 suppressed, 不制造重复通知
+
+关闭防睡眠主开关会关闭异常保护并恢复全部 suppressed 任务, 因为保护存在的目的就是避免错误防睡眠, 不是永久隐藏任务
+
## 保护状态持久化
-[`ActivityProtectionStateStore.swift`](../../CodexBar/Services/Workflow/ActivityProtectionStateStore.swift) 保存到:
+[`ActivityProtectionStateStore.swift`](../../CodexBar/Services/Workflow/ActivityProtectionStateStore.swift) 保存到
```text
~/Library/Application Support/CodexBar/ActivityProtection/state.json
@@ -183,16 +458,72 @@ subagent 事件更新父任务的 subagent 活动,不创建独立顶层任务
任务身份使用 SHA-256 摘要, 不把 session ID 或 turn ID 原文写入该状态文件. 匿名任务没有保护标识, 不写入该文件
+### 哈希身份的构造
+
+turn 和 session key 先使用带类型前缀与 NUL 分隔的 canonical 字符串, 再加固定 domain separator `CodexBar.ActivityProtection.v1` 执行 SHA-256
+
+类型和分隔符避免不同字段拼接后产生边界歧义. domain separator 避免同一原始 ID 在其他用途中的 hash 被直接关联
+
+这不是用来抵抗已知 session ID 的穷举, 而是避免状态文件直接泄露可读身份并限制跨用途关联
+
+### Debug 与 Release 为什么共享文件还要加锁
+
+两个 App bundle ID 可以同时运行, 但都观察同一份 Codex Hook 数据. 如果各自保存独立保护状态, 一个版本隐藏的异常任务可能被另一个版本重新用于防睡眠
+
+状态 store 使用 actor 串行单进程访问, 再用 `flock` 保护跨进程 read-modify-write. removal 还可以附带 `matchingMarkedAt`, 防止旧进程的迟到删除误删另一进程刚写入的新记录
+
+写入按 task identifier 稳定排序并原子替换, 文件权限最终校正为 `0600`
+
## 代际和旧结果隔离
-Monitor 为 reader 和异步恢复任务维护 generation:
+Monitor 为 reader 和异步恢复任务维护 generation
- reader 更换后丢弃旧 reader 的迟到结果
- bootstrap 未完成时不发布转场副作用
- 取消的 drain 不满足恢复屏障
- 数据源显式不健康时不沿用最后健康快照做静默判断
-这些约束避免系统唤醒,Hook 重装或 `CODEX_HOME` 变化时出现错误完成通知和错误释放。
+这些约束避免系统唤醒, Hook 重装或 `CODEX_HOME` 变化时出现错误完成通知和错误释放
+
+### monitor 中的主要 generation
+
+| generation | 保护的异步路径 |
+| --- | --- |
+| `tailReaderGeneration` | reader batch, rollout poll 和 prompt backfill |
+| `bootstrapCompletionGeneration` | 多次 bootstrap 重试后的异步 lifecycle 补齐 |
+| `activityProtectionRecoveryGeneration` | 睡眠, 唤醒和数据源恢复 |
+| task `progressGeneration` | 通知宽限期间的保护候选 |
+
+每一项都对应不同的"当前性"问题, 不能合并成一个全局计数. 例如 reader 没变但任务有新进展时, 只需要让 protection attempt 失效, 不应丢弃整个 reader
+
+## 扩展任务状态机的步骤
+
+1. 先确定新输入是事实, metadata, progress 还是 terminal
+2. 定义 bootstrap 与 live 是否产生相同 snapshot, 是否允许 transition
+3. 定义事件缺少 turn 或 session ID 时的降级行为
+4. 定义迟到和重复输入如何用 timestamp, terminal memory 或 generation 拒绝
+5. 如果读取 rollout 新字段, 扩展最小 envelope 而不是读取正文
+6. 在 `CodexActivityTask` 中维护领域状态, 在 monitor 中维护跨任务关联
+7. 更新 snapshot 前确认通知和防睡眠是否应该消费新状态
+8. 为系统睡眠, reader 替换和数据源不健康定义恢复路径
+9. 匿名任务默认不能获得新的高影响副作用, 除非身份可靠性发生根本变化
+
+## 建议验证的故障场景
+
+- App 在任务已运行时启动, bootstrap 展示任务但不补发通知
+- bootstrap 文件持续追加时能重试并最终获得稳定边界
+- 连续 3 次不稳定后进入 degraded, 不启动异常静默判断
+- 新 prompt 立即替换旧 turn, rollout terminal 在 5 秒内准确补分类
+- 同 session 多个 terminal 候选时不猜测 `Stop` 归属
+- reviewer 缺失后由 rollout 确认为 user 才进入等待
+- auto review 始终不发布等待 transition
+- subagent 关联不可靠时 UI 不展示伪精确数量
+- reader 进行中调用 `drainNow()` 必须再执行一轮新读取
+- 唤醒 drain 失败时保护继续暂停
+- 静默候选在 3 秒窗口内出现进展后不隐藏, 迟到通知被撤回
+- 阈值调长后未超新阈值的 suppressed 任务恢复
+- Debug 与 Release 并发更新保护记录时新记录不被旧 removal 删除
+- 匿名任务始终不进入 transition, KeepAlive 和保护状态文件
## 关键源码
diff --git a/Docs/DeveloperGuide/app-server.md b/Docs/DeveloperGuide/app-server.md
index 4159c99..e34812f 100644
--- a/Docs/DeveloperGuide/app-server.md
+++ b/Docs/DeveloperGuide/app-server.md
@@ -1,27 +1,57 @@
# app-server 数据链路
+## 设计出发点
+
+CodexBar 不重新实现 Codex 登录, token 刷新和账户协议, 而是把本机 `codex app-server` 作为账户能力边界
+
+这样做的原因是
+
+- 认证和服务端协议由 Codex 自己维护, CodexBar 不复制一套容易漂移的客户端
+- App 通过 stdio 与本机子进程通信, 账户主链路不需要直接暴露额外网络实现
+- 当前真正运行的 Codex 版本可以从 handshake 获得, 能用于 Hook 能力判断
+- 全局 CLI 与 App 内置 CLI 可以共享同一套上层数据模型
+
+代价是菜单栏 App 必须自己解决 shell 环境缺失, 子进程生命周期, pipe 背压, 混杂 stdout, 超时和升级后的连接换代
+
## 职责
-app-server 链路负责读取 Codex 账户和服务端状态:
+app-server 链路负责读取 Codex 账户和服务端状态
- 当前账户和套餐
- 5 小时额度和周额度
- token 用量与用量历史
- Reset Credits 状态
-- Hook 功能开关,handler 列表和配置写入能力
+- Hook 功能开关, handler 列表和配置写入能力
+
+这条链路不负责 Hook 历史统计, 也不负责实时任务状态
-这条链路不负责 Hook 历史统计,也不负责实时任务状态。
+### 输入与输出边界
+
+```text
+CodexCLIResolver
+ -> AppServerCommand
+ -> CodexStatusService actor
+ -> AppServerSession
+ -> Process + stdin/stdout/stderr
+ -> CodexQuotaSnapshot
+ -> CodexStatusViewModel
+ -> 菜单栏与主面板
+```
+
+`CodexStatusService` 拥有连接和同账户缓存. `CodexStatusViewModel` 只拥有 UI 级加载状态, 自动刷新节奏和最后一次连接信息
+
+这个分工让设置页可以复用同一个 app-server session 读写 Hook 与 TUI 配置, 同时不让 View 直接持有 `Process` 或 pipe
## Codex CLI 定位
-[`CodexCLIResolver.swift`](../../CodexBar/Services/CodexCLI/CodexCLIResolver.swift) 先从进程 `PATH` 查找全局 `codex`,再检查 App 内置路径:
+[`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 还会补充常见安装目录:
+菜单栏 App 从 Finder 启动时可能没有交互式 shell 的完整 `PATH`, 因此 resolver 还会补充常见安装目录
```text
/opt/homebrew/bin
@@ -35,17 +65,35 @@ app-server 链路负责读取 Codex 账户和服务端状态:
/sbin
```
-数据目录优先使用 `CODEX_HOME`,未设置时使用真实用户主目录下的 `~/.codex`
+数据目录优先使用 `CODEX_HOME`, 未设置时使用真实用户主目录下的 `~/.codex`
+
+### 为什么不能直接信任进程环境
+
+从 Finder 或登录项启动的 `LSUIElement` App 通常没有用户交互式 shell 注入的完整 `PATH`. 如果只调用 `/usr/bin/env codex`, Homebrew, Volta 或 npm 全局安装会在 Terminal 中可用, 在 CodexBar 中却不可见
+
+resolver 会做 3 层归一化
+
+1. 使用 `getpwuid(getuid())` 解析真实登录用户主目录, 避免继承 Xcode 或容器环境的错误 `HOME`
+2. 保留现有 `PATH`, 再按顺序补充常见目录并去重
+3. 对候选路径解析 symlink 和 standardized URL, 避免同一内置 binary 同时被识别成 global 与 bundled
+
+全局 CLI 优先是一个明确的产品选择. 开发者主动安装的 CLI 通常代表其期望版本, 内置 CLI 只是找不到全局版本时的可用回退
+
+### 磁盘版本和运行版本为什么分开
+
+设置页可以读取磁盘上两个候选 CLI 的版本, 但 Hook 能力检查只使用 `initialize` 返回的 app-server `userAgent`
+
+原因是连接最长复用 1 小时. 用户在连接存活期间升级磁盘 binary 后, 当前进程仍然是旧版本. 用磁盘版本判断会让 UI 声称 Hook 可用, 实际调用的旧 app-server 却不支持对应方法
## 进程与协议
-CodexBar 启动以下命令并通过 stdio 通信:
+CodexBar 启动以下命令并通过 stdio 通信
```bash
codex app-server --listen stdio://
```
-协议是逐行 JSON-RPC。建立连接后先发送 `initialize`,再发送 `initialized`,然后读取账户:
+协议是逐行 JSON-RPC. 建立连接后先发送 `initialize`, 再发送 `initialized`, 然后读取账户
```text
启动子进程
@@ -56,50 +104,205 @@ codex app-server --listen stdio://
-> account/usage/read
```
-stdout 可能包含非 JSON 输出。pipe reader 会持续读取完整行,只把能够解码且 response id 匹配的消息交给等待中的请求。stderr 独立排空,防止子进程因管道写满而阻塞。
+stdout 可能包含非 JSON 输出. pipe reader 会持续读取完整行, 只把能够解码且 response id 匹配的消息交给等待中的请求. stderr 独立排空, 防止子进程因管道写满而阻塞
+
+### 一次建连的完整事务
+
+```text
+解析 executable
+ -> 创建 stdin/stdout/stderr pipe
+ -> 启动 Process
+ -> initialize(clientInfo)
+ -> 从 userAgent 保存实际版本
+ -> initialized notification
+ -> account/read(refreshToken: false)
+ -> account 存在: 提交 connection
+ -> account 缺失: 关闭进程并返回 notLoggedIn
+```
+
+只有 handshake 与首次账户读取都成功, connection 才进入 service 状态. 半初始化 session 不会被留给下一轮复用
+
+### 为什么 stdout reader 只暴露完整行
+
+app-server 的 framing 是一行一个 JSON message. pipe 回调收到的 `Data` 块可能
+
+- 只包含半行
+- 同时包含多行
+- 在 JSON 行之间混有普通日志
+- 在进程结束时留下没有换行的最后一行
+
+`PipeReadBuffer` 因而自己维护 byte buffer, 只在看到换行时发布完整非空行. 会话层先轻量解码 response id, 只有 id 匹配才完整解码 result 或 error
+
+这既避免把日志误判成协议错误, 也让大响应只进行一次完整泛型解码
+
+### 为什么 stderr 也必须持续读取
+
+即使 CodexBar 不展示 stderr 正文, 也必须 drain pipe. 子进程 pipe buffer 有上限, 如果父进程从不读取 stderr, app-server 写满后会阻塞, 随后的 stdout response 也不会到达
+
+`PipeDrain` 不解析内容, 只消除背压. 这是进程正确性要求, 不是日志功能
+
+### 关闭策略
+
+session 关闭时按以下顺序收口
+
+1. 停止 stdout 和 stderr reader
+2. 关闭 stdin 写端, 给 app-server 正常感知 EOF 的机会
+3. 最多等待 1 秒优雅退出
+4. 仍未退出时发送强制终止, 再等待 0.5 秒
+5. 仍存活则记录诊断错误
+
+进程提前退出后继续写 pipe 可能触发 `SIGPIPE`. service 在初始化时忽略该 signal, 让写入以 Swift error 返回并进入 transport failure 重建路径, 而不是杀死整个菜单栏 App
## API 使用范围
| 方法 | 用途 |
| --- | --- |
-| `account/read` | 读取账户,套餐和认证状态 |
+| `account/read` | 读取账户, 套餐和认证状态 |
| `account/rateLimits/read` | 读取额度窗口 |
| `account/usage/read` | 读取 token 和历史用量 |
| `config/read` | 读取 Codex 配置 |
| `hooks/list` | 校验 Hook 来源和事件能力 |
| `config/batchWrite` | 修改 Hook 或 TUI 通知相关配置 |
-每个 session 会缓存不支持的方法。一旦 app-server 明确返回 method unsupported,当前连接后续不会重复请求该方法。
+每个 session 会缓存不支持的方法. 一旦 app-server 明确返回 method unsupported, 当前连接后续不会重复请求该方法
+
+### 为什么 unsupported 只按 session 缓存
+
+method unsupported 通常代表当前 app-server 版本缺少能力. 每分钟重复调用只会制造日志和延迟
+
+但这个结论不能永久保存到 UserDefaults. 新连接可能来自升级后的 binary, 因此 unsupported 集合只属于 `AppServerSession`, 连接重建后重新探测
+
+### 为什么配置也复用这条连接
+
+`config/read`, `hooks/list` 和 `config/batchWrite` 需要与账户刷新使用同一个实际 app-server 来源
+
+如果设置页另起一套 resolver 或进程, 可能出现主面板连接全局 CLI, Hook 校验却连接内置 CLI 的分裂状态. 统一 service 保证能力检查, 配置来源和运行版本来自同一个进程选择
## 会话生命周期
-[`CodexStatusService.swift`](../../CodexBar/Services/CodexStatus/CodexStatusService.swift) 是 actor,持有连接和刷新状态:
+[`CodexStatusService.swift`](../../CodexBar/Services/CodexStatus/CodexStatusService.swift) 是 actor, 持有连接和刷新状态
- 单次请求超时为 20 秒
- 连接最长复用 1 小时
- 业务错误在 session 内最多重试 1 次
- transport 失败最多重建连接 1 次
-- 认证需要刷新时,`account/read` 最多使用 `refreshToken = true` 再试 1 次
+- 认证需要刷新时, `account/read` 最多使用 `refreshToken = true` 再试 1 次
- service 关闭或进程退出时终止子进程并完成所有挂起请求
-业务错误与 transport 错误分开处理。前者可能是某个方法暂时失败,后者代表当前 stdio 会话已经不可信。
+业务错误与 transport 错误分开处理. 前者可能是某个方法暂时失败, 后者代表当前 stdio 会话已经不可信
+
+### 连接状态机
+
+```text
+no connection
+ -> resolve CLI
+ -> open and initialize
+ -> ready
+
+ready
+ -> age < 1h and process alive: reuse
+ -> process exited: close and rebuild
+ -> age >= 1h: close and rebuild
+ -> transport failure: close and rebuild once
+ -> account missing after refresh: close and notLoggedIn
+```
+
+1 小时不是数据刷新周期, 而是连接最长寿命. 定期重建的主要价值是让后台升级后的 Codex binary 最迟在一个连接周期后生效
+
+### 错误分类矩阵
+
+| 错误 | 当前请求 | 当前连接 | 整轮刷新 |
+| --- | --- | --- | --- |
+| retriable server error | 同一方法再试 1 次 | 保留 | 根据第二次结果继续 |
+| method unsupported | 标记当前 session 不支持 | 保留 | 对应字段为 missing |
+| 普通业务失败 | 不再重试 | 保留 | 同账户缓存可降级 |
+| authentication required | 本轮统一刷新 token 后再试 | 保留或转未登录 | 全程最多刷新 1 次 |
+| timeout, pipe close, invalid transport | 失败 | 立即丢弃 | 仅复用连接时重建 1 次 |
+
+限制重建次数是为了避免故障状态下反复拉起子进程. 一轮刷新结束后, 下一次正常定时刷新仍有新的尝试机会
+
+### 为什么认证刷新全程只有一次
+
+一次刷新会读取 account, rate limits, usage 和 Reset Credits. 多个接口可能同时发现 token 过期
+
+`fetchData` 内部用同一个 `didRefresh` 锁存本轮刷新资格. 第一个认证失败触发 `account/read(refreshToken: true)`, 后续接口复用刷新结果. 再次需要认证时直接归类为未登录
+
+这避免一轮 UI 刷新对同一凭据连续触发多次 token refresh, 也让 Reset Credits 的 `401` 或 `403` 与 app-server 方法共享同一个认证预算
## 刷新模型
-状态 ViewModel 默认每 60 秒刷新。用户也可以在主面板双击刷新按钮立即触发。
+状态 ViewModel 默认每 60 秒刷新. 用户也可以在主面板双击刷新按钮立即触发
-一次刷新先解析账户,再读取额度和用量。补充数据缓存严格绑定到账户身份:
+一次刷新先解析账户, 再读取额度和用量. 补充数据缓存严格绑定到账户身份
- 账户不变且补充请求失败时可以继续展示缓存值
- 账户变化时立即清空旧账户缓存
- 服务端明确不支持的方法显示为来源缺失
- 来源缺失不能转换为业务值 `0`
-刷新任务通过协调器合并,避免定时刷新,面板打开和手动刷新并发创建重复请求。
+刷新任务通过协调器合并, 避免定时刷新, 面板打开和手动刷新并发创建重复请求
+
+### 一次刷新如何组装快照
+
+```text
+确认或新建 connection
+ -> 复用连接时 account/read
+ -> 确认 account identity
+ -> account/rateLimits/read
+ -> account/usage/read
+ -> 有 Reset Credits 时读取 expiration endpoint
+ -> 组合 CodexQuotaSnapshot
+ -> MainActor 提交 loadState 与连接信息
+```
+
+rate limits 与 usage 是补充数据. 只要账户有效, 即使两个接口都没有数据, 仍然生成快照让 UI 展示账户和明确的"暂无数据"
+
+如果因为补充接口缺失就把整轮标成未登录, 用户会看到身份状态在真实登录和错误之间抖动, 也无法区分认证问题与单个新接口不支持
+
+### 缓存决策表
+
+| 当前结果 | 同账户有缓存 | 输出 | stale |
+| --- | --- | --- | --- |
+| 成功 | 任意 | 新值并更新缓存 | `false` |
+| 普通请求失败 | 是 | 缓存值 | `true` |
+| 普通请求失败 | 否 | `nil` | 不适用 |
+| method unsupported | 任意 | `nil` | 不适用 |
+| 账户变化 | 旧账户缓存 | 先整体清空 | 不适用 |
+
+method unsupported 不使用旧缓存, 因为它是明确能力结论. 普通请求失败使用缓存, 因为来源可能只是一轮暂时故障
+
+### stale 如何影响消费者
+
+- UI 可以展示旧值, 但降低菜单栏和进度条透明度
+- `hasTrustedData` 只把非 stale 的额度或用量算作可信
+- 额度通知完全跳过 stale rate limits
+- 系统日志只记录 step 为 `cached`, 不记录实际额度数值
+
+stale 是数据可信度的一部分, 新增展示时不能只复制数值而丢掉标记
+
+### 刷新协调器为什么还需要 generation
+
+`isRefreshing` guard 可以阻止普通重复触发, 但 cancellation 和对象生命周期仍可能让旧 Task 返回
+
+`RefreshTaskCoordinator` 每次开始先推进 generation, 取消旧 Task, 最终只有 `canCommit(generation)` 成立的结果可以写回 UI. 这让"最后发起的刷新获胜"成为显式规则
+
+自动刷新每轮按距离上次完成的剩余时间等待. 手动刷新完成后倒计时自然重新对齐, 不会在几秒后又被原来的 timer 立刻刷新一次
+
+### 模型层的小优化
+
+`CodexUsageSnapshot` 构造时把可能重复的 daily bucket 聚合成 `tokensByDate`
+
+热力图在一次渲染中会反复查询日期. 提前构造索引避免每个方块都线性扫描原始 bucket, 同时保留原始数组用于快照相等比较
+
+额度 limit 的展示顺序也在模型层统一
+
+- app-server 顶层 `rateLimits` 指向的主 limit 优先
+- 其余按本地化名称和 limit id 稳定排序
+- primary 与 secondary 使用稳定枚举, View 不根据标签字符串猜测窗口类型
## Reset Credits
-Reset Credits 到期时间不来自 app-server。当可用数量大于 `0` 时,[`CodexResetCreditsService.swift`](../../CodexBar/Services/CodexStatus/CodexResetCreditsService.swift) 使用现有 `auth.json` token 请求:
+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
@@ -107,14 +310,22 @@ https://chatgpt.com/backend-api/wham/rate-limit-reset-credits
- 请求超时为 4 秒
- 首次请求只读取现有 token
-- 收到 `401` 或 `403` 时,复用本轮统一认证刷新额度最多刷新 1 次,再重新读取 `auth.json`
+- 收到 `401` 或 `403` 时, 复用本轮统一认证刷新额度最多刷新 1 次, 再重新读取 `auth.json`
- 不把 token 写入其他位置
- 数量为 `0` 时不发起请求
- 请求失败不会影响主账户和额度刷新
+### 为什么这是唯一单独的账户网络请求
+
+app-server 返回可用 Reset Credits 数量, 但不返回每一批的过期时间. UI 和临期通知需要过期日, 因此只在数量大于 `0` 时补充查询
+
+请求使用现有 `auth.json`, 不另建登录流程. 凭据只活在本次请求内, 返回模型只保留仍为 available 且晚于当前时间的日期并排序
+
+这个请求是增强信息, 不是账户快照的必要条件. 4 秒超时或任何解析错误只让过期日缺失, 不应让额度和用量一起失败
+
## Hook 版本与配置校验
-Hook 设置也复用 app-server 链路,但采用独立的可用性状态:
+Hook 设置也复用 app-server 链路, 但采用独立的可用性状态
- `isEnabled` 表示目标 handler 已安装
- `isVerified` 表示最近一次 app-server 显式校验通过
@@ -125,11 +336,55 @@ Hook 设置也复用 app-server 链路,但采用独立的可用性状态:
详细配置流程见 [Hook 采集与历史聚合](hook-and-aggregation.md)
+### 实际版本检查的时序
+
+启用或校验 Hook 时调用 `readyConnectionInfo()`
+
+- 没有连接时先建立连接
+- 有连接时复用当前真实进程
+- 从 handshake user agent 解析运行版本
+- 无法解析版本时按不支持处理, 不乐观放行
+
+这是能力安全边界. 如果未来新增依赖某个 app-server 方法的功能, 应把最低版本判断放在实际连接能力入口, 不能只在"关于"页面展示磁盘版本
+
## 请求日志
-[`RequestLog.swift`](../../CodexBar/Services/CodexStatus/RequestLog.swift) 在内存中保留最近 500 条请求日志,用于 App 内日志窗口诊断。
+[`RequestLog.swift`](../../CodexBar/Services/CodexStatus/RequestLog.swift) 在内存中保留最近 500 条请求日志, 用于 App 内日志窗口诊断
+
+日志用于观察进程启动, JSON-RPC 方法, 重试和错误分类. 不应写入 access token 或 Hook prompt 内容
+
+### 两套日志为什么分开
+
+系统统一日志只保存控制流分类, 适合长期排查 App 是否在刷新, 失败在哪个阶段
+
+App 内 `RequestLog` 保存最多 500 条请求交互预览, 只存在进程内存, 适合用户主动检查协议细节
+
+即使内存日志生命周期短, 也不能记录 Reset Credits Authorization header. 对新 RPC 增加日志时, 需要检查 payload 是否可能包含凭据或内容字段
+
+## 扩展 app-server 字段的步骤
+
+1. 在外部 DTO 中按协议可选性建模, 不先用展示默认值填充
+2. 在 `CodexStatusService` 决定该方法是账户核心还是补充数据
+3. 明确普通失败, unsupported 和认证失败各自如何降级
+4. 如果缓存该值, 必须绑定账户 identity 并携带 stale 语义
+5. 在领域 snapshot 中转换时间戳, 百分比和排序等稳定规则
+6. UI 只消费 snapshot, 不直接访问原始 response
+7. 通知等副作用只使用可信快照
+8. 核对请求和日志是否扩大隐私边界
+
+## 建议验证的故障场景
-日志用于观察进程启动,JSON-RPC 方法,重试和错误分类。不应写入 access token 或 Hook prompt 内容。
+- Finder 启动时仍能找到 Homebrew, npm 或 Volta 安装的 Codex
+- 全局 CLI 缺失时正确回退到 ChatGPT App 或 Codex App 内置 binary
+- stdout 混有普通文本时仍能匹配正确 response id
+- stderr 持续输出时请求不会因 pipe 背压卡住
+- 复用连接的 transport failure 只重建一次
+- 磁盘 CLI 升级后, 当前连接版本与磁盘版本能被区分
+- rate limits 失败但同账户有缓存时展示 stale, 通知不误触发
+- 账户切换后旧额度和用量立即清空
+- unsupported method 不会每分钟重复请求
+- Reset Credits `401` 后只共享一次认证刷新, 失败不影响主快照
+- 手动刷新后 60 秒倒计时重新对齐
## 关键源码
diff --git a/Docs/DeveloperGuide/architecture.md b/Docs/DeveloperGuide/architecture.md
index 4d92f45..94429ea 100644
--- a/Docs/DeveloperGuide/architecture.md
+++ b/Docs/DeveloperGuide/architecture.md
@@ -1,19 +1,65 @@
# 整体架构
+## 这套架构要解决什么
+
+CodexBar 的核心挑战不是绘制菜单栏界面, 而是在一个长期运行的 `LSUIElement` App 中同时协调短命 Hook 子进程, 本机 app-server, 持续追加的文件, CloudKit, 系统通知和 root helper
+
+架构需要持续满足以下目标
+
+- 任意一条数据链路失败时, 不连带关闭其他功能
+- 短命 Hook 模式和普通 App 模式共用可执行文件, 但生命周期完全隔离
+- UI 只观察可解释的快照, 不直接承担 I/O, 去重或恢复逻辑
+- 特权操作保持最小接口, 业务策略留在普通 App 进程
+- 每个异步结果都能证明自己仍属于当前配置和数据源代际
+- 可重建数据与不可重放副作用分开处理
+
+更完整的取舍背景见 [设计原则与关键决策](design-decisions.md)
+
## 技术基线
-CodexBar 是 macOS 15+ 菜单栏应用,使用 Swift 6,SwiftUI,AppKit 和 MVVM。
+CodexBar 是 macOS 15+ 菜单栏应用, 使用 Swift 6, SwiftUI, AppKit 和 MVVM
-工程只有 `CodexBar` scheme,包含两个 target:
+工程只有 `CodexBar` scheme, 包含两个 target
| Target | 职责 |
| --- | --- |
-| `CodexBar` | 菜单栏 UI,Codex 数据采集,通知,同步和防睡眠编排 |
-| `CodexBarHelper` | 以 root LaunchDaemon 运行,仅负责系统睡眠开关 |
+| `CodexBar` | 菜单栏 UI, Codex 数据采集, 通知, 同步和防睡眠编排 |
+| `CodexBarHelper` | 以 root LaunchDaemon 运行, 仅负责系统睡眠开关 |
-两个 target 通过 [`CodexBarHelperXPC.swift`](../../Shared/CodexBarHelperXPC.swift) 共享 XPC 协议。
+两个 target 通过 [`CodexBarHelperXPC.swift`](../../Shared/CodexBarHelperXPC.swift) 共享 XPC 协议
+
+App 使用 Sparkle 检查更新. 工程默认启用 `MainActor` 隔离, Debug 和 Release 使用不同的 App 与 CodexBarHelper bundle ID
+
+## 进程与信任边界
+
+```text
+Codex
+ | 启动 --hook-event 子进程, 通过 stdin 传入事件
+ v
+CodexBar executable
+ |-- Hook 模式: 最小解析 + flock + JSONL append + exit
+ |
+ `-- 普通模式
+ |-- stdio JSON-RPC <-> codex app-server
+ |-- 本地只读 <-> Hook JSONL / rollout JSONL
+ |-- HTTPS <-> Reset Credits / Sparkle
+ |-- CloudKit private database <-> 日级聚合
+ `-- signed XPC lease <-> root CodexBarHelper <-> fixed pmset commands
+```
-App 使用 Sparkle 检查更新。工程默认启用 `MainActor` 隔离,Debug 和 Release 使用不同的 App 与 CodexBarHelper bundle ID。
+边界设计有两个关键点
+
+- 同一个可执行文件承载 Hook 模式可以让 handler 始终指向当前 App 版本, 不需要额外部署采集工具
+- root helper 不知道 Codex 任务, 只知道经过签名校验的租约, 因而不会把业务输入直接带入特权边界
+
+### 进程生命周期差异
+
+| 进程 | 生命周期 | 可以做什么 | 不能做什么 |
+| --- | --- | --- | --- |
+| Hook 子进程 | 单个事件, 最长几秒 | 读取 stdin, 提取最小字段, 追加本地 JSONL | 初始化 UI, 建立网络连接, 等待长期服务 |
+| 主 App | 用户登录会话内长期运行 | 编排 UI, 数据链路和副作用 | 直接以 root 修改系统设置 |
+| app-server | 最长复用 1 小时 | 通过 JSON-RPC 提供账户和配置能力 | 成为 Hook 历史或实时任务的替代来源 |
+| CodexBarHelper | LaunchDaemon | 执行固定 `pmset` 操作并恢复所有权 | 访问账户, Hook, rollout, 网络或任意命令 |
## 目录职责
@@ -33,7 +79,7 @@ Scripts/ 构建, DMG, appcast 和 CodexBarHelper 清理脚本
## 启动顺序
-[`CodexBarApp.swift`](../../CodexBar/App/CodexBarApp.swift) 的初始化顺序是架构约束,不是实现细节:
+[`CodexBarApp.swift`](../../CodexBar/App/CodexBarApp.swift) 的初始化顺序是架构约束, 不是实现细节
```text
进程启动
@@ -46,9 +92,9 @@ Scripts/ 构建, DMG, appcast 和 CodexBarHelper 清理脚本
-> 启动刷新, 活动监控, 通知和防睡眠协调
```
-`--hook-event` 是 Codex 调用的短命子进程模式。它必须在任何 UI,CloudKit,通知或长期服务初始化之前完成。采集失败也不能阻断 Codex 主流程。
+`--hook-event` 是 Codex 调用的短命子进程模式. 它必须在任何 UI, CloudKit, 通知或长期服务初始化之前完成. 采集失败也不能阻断 Codex 主流程
-普通模式由 `CodexBarAppDelegate` 统一创建和持有长期对象,主要包括:
+普通模式由 `CodexBarAppDelegate` 统一创建和持有长期对象, 主要包括
- `CodexStatusService` 和 `CodexStatusViewModel`
- `WorkflowService` 和对应 ViewModel
@@ -57,30 +103,86 @@ Scripts/ 构建, DMG, appcast 和 CodexBarHelper 清理脚本
- `KeepAliveController`
- `WorkflowSyncSettings` 和同步调度器
- `CodexNotificationService`
-- 菜单栏,快捷键,设置窗口和更新服务
+- 菜单栏, 快捷键, 设置窗口和更新服务
+
+App 退出时需要先释放防睡眠状态. 如果 CodexBarHelper 尚未确认恢复, 终止流程会等待或取消退出, 避免遗留系统级睡眠状态
+
+### 为什么 Hook 判断必须放在 `App.init`
+
+`@NSApplicationDelegateAdaptor` 会把 AppKit 生命周期接入 SwiftUI App. 一旦普通生命周期开始, 可能创建菜单栏对象, 注册通知 delegate 或访问 CloudKit
+
+Hook handler 在 Codex 的关键路径上, 它需要的是接近命令行工具的行为. 因此 `WorkflowHookEventRecorder.handleIfRequested()` 必须在 `CodexBarApp.init()` 的第一段执行, 命中后直接 `exit(EXIT_SUCCESS)`
+
+这个顺序还保证 Hook 采集失败不会污染正常退出诊断. `AppProcessDiagnostics.install()` 只在 `applicationDidFinishLaunching` 中执行, Hook 子进程不会被误记为一次异常退出的完整 App
-App 退出时需要先释放防睡眠状态。如果 CodexBarHelper 尚未确认恢复,终止流程会等待或取消退出,避免遗留系统级睡眠状态。
+### 为什么由 AppDelegate 持有长期对象
+
+SwiftUI View 会因为布局, 条件分支和窗口重建而重复创建. 如果 service 的所有权落在 View 中, 一个看似普通的界面变化就可能终止 reader, app-server 或 XPC 连接
+
+`CodexBarAppDelegate` 因而承担 composition root 职责
+
+- 只在这里创建长期 service, settings 和 ViewModel
+- 在这里建立 monitor, notification 和 keep-alive 之间的回调
+- View 只接收已经创建好的引用
+- App 退出时从同一个所有者反向停止服务
+
+这不是要求所有逻辑都堆进 AppDelegate. 它只负责装配和生命周期, 业务规则仍在各自 service 或 controller 中
+
+### 退出为什么可以被取消
+
+`applicationShouldTerminate` 先调用 `KeepAliveController.prepareForTermination()` 并返回 `.terminateLater`
+
+如果 helper 明确确认 release, App 再回复允许退出. 如果释放失败, 本次退出被取消, controller 回到正常协调状态并继续尝试维持正在运行的任务
+
+直接在 `applicationWillTerminate` 中异步释放已经太晚, 因为该回调不能可靠延长进程寿命
## 3 条独立数据链路
-CodexBar 不使用一个聚合服务承载所有状态。3 条链路的输入,时效和失败语义不同:
+CodexBar 不使用一个聚合服务承载所有状态. 3 条链路的输入, 时效和失败语义不同
| 链路 | 输入 | 输出 | 主要消费者 |
| --- | --- | --- | --- |
-| app-server | `codex app-server` JSON-RPC | 账户,额度,token 用量,Hook 配置能力 | 主面板,菜单栏额度,设置 |
-| Hook 历史 | Hook JSONL | 日级事件,session,turn,tool,model 聚合 | 活跃度热力图,历史统计,CloudKit |
-| 实时任务 | Hook 增量事件加 rollout 生命周期 | 运行,等待批准,完成,中断 | 菜单栏状态,任务中心,通知,防睡眠 |
+| app-server | `codex app-server` JSON-RPC | 账户, 额度, token 用量, Hook 配置能力 | 主面板, 菜单栏额度, 设置 |
+| Hook 历史 | Hook JSONL | 日级事件, session, turn, tool, model 聚合 | 活跃度热力图, 历史统计, CloudKit |
+| 实时任务 | Hook 增量事件加 rollout 生命周期 | 运行, 等待批准, 完成, 中断 | 菜单栏状态, 任务中心, 通知, 防睡眠 |
-链路之间可以共享基础设施和模型,但不能互相替代:
+链路之间可以共享基础设施和模型, 但不能互相替代
- app-server 不提供完整的实时任务状态
-- 历史聚合允许延迟和重建,实时任务不能等待聚合完成
+- 历史聚合允许延迟和重建, 实时任务不能等待聚合完成
- 实时任务快照不可作为历史统计的持久来源
-- 某条链路不可用时,其他链路仍应保持可用
+- 某条链路不可用时, 其他链路仍应保持可用
+
+### 依赖方向
+
+```text
+CodexStatusService ----> CodexStatusViewModel ----+
+ |
+WorkflowService -------> WorkflowViewModel -------+--> UI
+ |
+Hook + rollout --------> CodexActivityMonitor ----+
+ | |
+ | +--> CodexNotificationService
+ `-------------> KeepAliveController --> helper
+```
+
+箭头表示数据或只读状态的消费方向. 下游不能反向成为上游的事实来源
+
+例如, 菜单栏可以把额度进度和任务状态画在同一个图标上, 但图标是否存在不能决定任务 monitor 是否运行. 同步 scheduler 可以复用历史维护的触发时机, 但 CloudKit 是否可用不能决定本地聚合是否执行
+
+### 共享触发不等于数据依赖
+
+历史维护默认挂在 60 秒额度刷新完成事件上, 这是为了减少常驻 timer 和日志噪音. 两条链路共享调度时机, 但没有共享事实
+
+因此修改刷新节奏时需要区分
+
+- 触发来源可以调整
+- 维护任务仍必须在 app-server 失败时具备独立执行能力
+- UI 打开时的轻量统计刷新不能隐式发起 CloudKit 网络操作
## 并发边界
-工程启用 Swift 6 严格并发和默认 `MainActor` 隔离。
+工程启用 Swift 6 严格并发和默认 `MainActor` 隔离
### MainActor 对象
@@ -90,7 +192,7 @@ CodexBar 不使用一个聚合服务承载所有状态。3 条链路的输入,
- `KeepAliveController`
- `CodexNotificationService`
-这些对象负责可观察状态和 UI 协调,不应直接执行阻塞 I/O。
+这些对象负责可观察状态和 UI 协调, 不应直接执行阻塞 I/O
### Actor 服务
@@ -101,13 +203,74 @@ CodexBar 不使用一个聚合服务承载所有状态。3 条链路的输入,
- `WorkflowSyncService` 管理 CloudKit 状态
- `ActivityProtectionStateStore` 管理跨进程保护记录
-跨 actor 传递的 DTO 必须是不可变值类型,并按需要声明 `Sendable` 或 `nonisolated`
+跨 actor 传递的 DTO 必须是不可变值类型, 并按需要声明 `Sendable` 或 `nonisolated`
+
+### 为什么 monitor 仍在 MainActor
+
+`CodexActivityMonitor` 的输入读取在 actor 中完成, 但状态机本身与多个 Combine 消费者紧密相连
+
+把 monitor 放在 `MainActor` 有以下收益
+
+- `@Published snapshot` 和 transition 发布顺序天然串行
+- 通知与防睡眠消费者看到相同的状态提交顺序
+- App 睡眠, 唤醒和 Hook 设置变化可以与 UI 生命周期统一排序
+
+前提是 monitor 不能直接执行阻塞文件读取. `HookEventTailReader`, `CodexSessionLifecycleReader` 和 `ActivityProtectionStateStore` 各自承担 I/O 边界
+
+### 非隔离 pipe reader 为什么使用锁
+
+app-server 是 stdio 协议, 底层需要组合 `FileHandle`, `DispatchSourceRead` 和 semaphore. 这些类型不是天然 `Sendable`, 也不适合每读取一行都跨 Swift actor hop
+
+`PipeReadBuffer` 把不安全边界收口在一个 `@unchecked Sendable` 类型中, 所有可变状态由 `NSLock` 保护, 读事件固定在专用 queue 上. 上层只看到完整行和关闭状态
+
+这里的 `@unchecked` 是经过封装的局部承诺, 不是关闭整个模块的并发检查
+
+### 跨进程文件不能只依赖 actor
+
+Hook recorder 是另一个进程, 所以 `WorkflowService` actor 无法保护它. `stats.lock` 使用 `flock` 对事件文件和维护状态的联合修改提供进程级排他事务
+
+同一个流程中会同时出现 actor 和 `flock`
+
+- actor 保证主 App 内多项维护不会并行改状态
+- `flock` 保证主 App 与短命 Hook 子进程不会同时提交冲突文件修改
+
+## 模型分层
+
+项目没有让 app-server DTO, 持久化模型和 View 直接共用同一个大对象
+
+| 模型类型 | 作用 | 设计要求 |
+| --- | --- | --- |
+| 外部 DTO | 解码 app-server, Hook, rollout 或 CloudKit | 宽容版本差异, 不承载 UI 副作用 |
+| 持久化模型 | 保存可恢复状态和 schema | 兼容旧值, 明确 missing 语义 |
+| 领域快照 | 向消费者表达当前可信状态 | 不可变, 可比较, 跨 actor 安全 |
+| transition | 表达一次 live 状态变化 | 不从历史快照反推, 需要上游去重 |
+| 展示格式 | 日期, 百分比, 文案和颜色 | 跟随 locale, 不反向参与业务判定 |
+
+例如 `CodexQuotaSnapshot` 可以同时携带当前值和 stale 标记. `CodexActivitySnapshot` 只保存展示需要的任务字段, 原始 session ID 不进入 View
+
+## 生命周期与保留时间
+
+不同状态有不同的生命周期, 不能用一个统一缓存期限替代
+
+| 状态 | 生命周期 | 原因 |
+| --- | --- | --- |
+| app-server connection | 最长 1 小时 | 复用降低启动成本, 定期重建让磁盘升级生效 |
+| app-server supplemental cache | 当前账户内 | 避免跨账户串值 |
+| Hook live bootstrap window | 24 小时 | 覆盖可能仍在运行的长任务 |
+| 完成高亮 | 30 秒 | 菜单栏短时反馈 |
+| 任务中心 terminal 历史 | 10 分钟 | 提供近期上下文但不长期占用 UI |
+| terminal 去重记忆 | 24 小时 | 防止迟到 Hook 或 rollout 复活旧任务 |
+| Hook 原始和日聚合 | 210 天 | 支持长期统计和重建 |
+| 日聚合身份明细 | 3 天 | 近期精确去重与隐私, 文件体积折中 |
+| Activity Protection 记录 | 最后进展后 24 小时 | 跨重启保持抑制, 同时限制身份留存 |
+
+修改其中一个时间窗口时, 要先确认是否存在配对不变量. 例如 tail reader bootstrap 窗口必须和活动任务保留窗口一致
## 状态所有权
-实时任务状态只有一个权威来源,即 [`CodexActivityMonitor.swift`](../../CodexBar/Services/Workflow/CodexActivityMonitor.swift)
+实时任务状态只有一个权威来源, 即 [`CodexActivityMonitor.swift`](../../CodexBar/Services/Workflow/CodexActivityMonitor.swift)
-它的快照被以下模块消费:
+它的快照被以下模块消费
- 菜单栏图标和主面板任务卡片
- 活动中心
@@ -115,16 +278,83 @@ CodexBar 不使用一个聚合服务承载所有状态。3 条链路的输入,
- 防睡眠是否存在有效任务的判断
- 异常会话保护
-消费者只能基于快照展示或执行副作用,不能各自重建一套任务状态机。
+消费者只能基于快照展示或执行副作用, 不能各自重建一套任务状态机
+
+### 状态所有权表
+
+| 状态 | 唯一所有者 | 其他模块的权限 |
+| --- | --- | --- |
+| app-server 连接与同账户缓存 | `CodexStatusService` | 请求只读结果 |
+| 主面板账户加载状态 | `CodexStatusViewModel` | 观察发布值 |
+| Hook 安装与验证 | `CodexHookSettings` | 读取 `isOperable` |
+| 历史聚合和维护游标 | `WorkflowService` | 请求快照或重建 |
+| 实时任务 | `CodexActivityMonitor` | 读取 snapshot 或 transition |
+| 同步游标与远端缓存 | `WorkflowSyncService` | 请求合并快照 |
+| 防睡眠策略与 App assertion | `KeepAliveController` | 读取派生状态或调用设置入口 |
+| root 睡眠所有权 | `CodexBarHelper` | 通过 XPC 请求和查询 |
+| 通知去重 | `CodexNotificationService` | 上游只发布候选事件 |
+
+新增消费者时, 优先订阅已有快照. 如果现有快照缺字段, 应在状态所有者处扩展稳定值类型, 不应让消费者重新读取原始文件
## 错误和降级原则
- 短暂网络或 RPC 失败优先保留上一次可解释的状态
-- 数据源不可用必须显式表达,不能伪装为空数据
-- bootstrap 阶段只建立基线,不发送历史状态变化通知
+- 数据源不可用必须显式表达, 不能伪装为空数据
+- bootstrap 阶段只建立基线, 不发送历史状态变化通知
- reader 更换或数据源代际变化时丢弃旧异步结果
- 恢复流程必须完成新的读取屏障后才能继续判定
-- 持久化文件写入需要原子替换或文件锁,避免 Debug 与 Release 并发破坏
+- 持久化文件写入需要原子替换或文件锁, 避免 Debug 与 Release 并发破坏
+
+### 错误分类比统一重试更重要
+
+| 错误类别 | 典型处理 | 不应采取的处理 |
+| --- | --- | --- |
+| 明确业务不支持 | 缓存 method unsupported, 显示来源缺失 | 每分钟重复请求或展示 `0` |
+| 短暂业务失败 | 同账户范围内使用 stale 缓存 | 清空整个账户快照 |
+| transport 失败 | 丢弃连接, 最多重建一次 | 在不可信 pipe 上继续请求 |
+| 数据源身份变化 | 新 generation, 从原始来源重建 | 沿用旧 offset 继续追加 |
+| 迟到异步结果 | generation 不匹配时丢弃 | 覆盖新设置或新 reader 状态 |
+| 特权状态不确定 | 保留可能租约并主动确认释放 | 假定 helper 没有执行 |
+| Hook recorder 失败 | 吞掉本次采集并退出成功 | 阻断 Codex 或弹 UI |
+
+### 日志为什么记录阶段而不是用户数据
+
+系统日志使用 `trigger`, `stage`, `reason`, `counts` 和 `elapsed` 解释流程, 避免记录额度数值, 项目路径或任务身份
+
+这种日志结构允许区分
+
+- 同步是在 zone, device, fetch, upload 还是 prune 阶段失败
+- app-server 使用新连接还是复用连接
+- 聚合是空转, 增量写入还是标脏重建
+- 防睡眠被哪一个条件阻断
+
+诊断需要的是控制流证据, 不需要复制用户数据
+
+## 变更一个核心流程时怎么落点
+
+### 新增数据来源
+
+1. 先确定它是否属于现有 3 条链路
+2. 定义来源缺失, stale 和失败语义
+3. 在 actor service 内完成 I/O 和缓存
+4. 通过不可变快照进入 MainActor
+5. 单独审查网络和隐私边界
+
+### 新增一次性副作用
+
+1. 找到能证明"刚刚发生"的 live transition
+2. 不从当前快照或历史列表反推
+3. 定义进程内和跨重启去重范围
+4. 提交前检查事件是否仍相关
+5. 定义副作用失败是否可以影响主状态
+
+### 新增持久化状态
+
+1. 说明为什么内存状态不足
+2. 定义 schema, 原子性和并发访问边界
+3. 定义旧版本读取新文件和新版本读取旧文件的行为
+4. 限制保存字段和保留时间
+5. 先确认兼容策略再修改格式
## 系统集成
diff --git a/Docs/DeveloperGuide/data-and-privacy.md b/Docs/DeveloperGuide/data-and-privacy.md
index 217773f..30e2519 100644
--- a/Docs/DeveloperGuide/data-and-privacy.md
+++ b/Docs/DeveloperGuide/data-and-privacy.md
@@ -2,60 +2,134 @@
## 原则
-CodexBar 只读取实现账户展示,Hook 统计,实时任务和防睡眠所需的数据:
+CodexBar 只读取实现账户展示, Hook 统计, 实时任务和防睡眠所需的数据
- 原始数据能留在本机时不上传
- 可以保存聚合时不保存正文
- 可以保存哈希身份时不保存原始身份
- 数据源不可用时显式标记缺失
+隐私边界不是一份静态字段黑名单, 而是每条数据链路的架构约束. 新字段即使技术上容易读取, 也必须先回答"它是否是完成产品目标所必需的"
+
+## 数据分类模型
+
+开发时把数据分成 4 类有助于决定存储和传播范围
+
+| 分类 | 示例 | 默认处理 |
+| --- | --- | --- |
+| 凭据 | OAuth token, `auth.json` | 只在请求期间使用, 不复制, 不记录 |
+| 内容 | prompt, response, tool 参数和输出 | 不采集 |
+| 身份和上下文 | session ID, 完整路径, project 名 | 仅在必要链路最小化使用, 上传前脱敏或删除 |
+| 聚合指标 | 每日事件数, model 计数 | 可本地持久化, 用户 opt-in 后上传规定字段 |
+
+"只保存在本机"不等于没有隐私成本. 本地日志, crash report, 备份和同机其他进程仍可能扩大暴露面, 所以不需要的数据应在解析入口就丢弃
+
+## 信任边界
+
+```text
+Codex hook stdin / rollout / auth.json / app-server
+ |
+ v
+ 普通用户权限的 CodexBar
+ | |
+ v v
+ CloudKit private DB 受限 XPC 接口
+ |
+ v
+ root CodexBarHelper
+```
+
+边界含义如下
+
+- Codex 输入文件和协议数据都视为外部输入, 解码失败不能扩大成任意文件访问或命令执行
+- CloudKit 是用户主动开启的远端边界, 即使使用 private database 也只允许规定聚合字段
+- root helper 是权限提升边界, 接口能力必须比 App 业务能力更窄
+- Debug 和 Release 是两个 App 身份, 但部分本地文件有意共享, 因此需要进程锁和兼容 schema
+
+## 最小化发生在采集入口
+
+只在上传时删除敏感字段不够, 因为原始字段可能已经进入本地 JSONL, 内存日志或错误信息
+
+CodexBar 的最小化顺序是
+
+1. Hook recorder 从 stdin 只提取白名单结构字段
+2. rollout reader 使用最小 Codable 结构跳过正文
+3. 聚合器把较老 identity 明细压成计数
+4. sync model 再投影成 CloudKit 允许字段
+5. 日志层只记录阶段, 分类和非敏感计数
+
+每一层都收窄一次数据形状, 因此下游新增一个字段不能自动获得上游所有原文
+
## 数据流总览
| 来源 | CodexBar 使用方式 | 是否持久化 | 是否上传 CloudKit |
| --- | --- | --- | --- |
| app-server 账户和额度 | 主面板和通知判断 | 仅设置和短期状态 | 否 |
-| Hook 结构化事件 | 历史聚合和实时任务 | 是,最长 210 天 | 只上传日聚合 |
+| Hook 结构化事件 | 历史聚合和实时任务 | 是, 最长 210 天 | 只上传日聚合 |
| rollout 生命周期 | terminal 和进展对账 | 不单独持久化 | 否 |
| `auth.json` token | 查询 Reset Credits 到期时间 | 不复制 | 否 |
| App 设置 | 功能开关和阈值 | UserDefaults | 否 |
-| Activity Protection | 异常会话恢复 | 哈希身份,最长 24 小时 | 否 |
+| Activity Protection | 异常会话恢复 | 哈希身份, 最长 24 小时 | 否 |
| CodexBarHelper ownership | 系统睡眠恢复 | root 状态文件 | 否 |
+### 为什么 3 条业务链路保持独立
+
+app-server, Hook 历史和实时活动读取不同事实, 具有不同的新鲜度与失败模式
+
+- app-server 失败不应让本地历史消失
+- Hook 聚合维护失败不应冻结实时任务
+- rollout 暂时不可用不应把额度标成错误
+- CloudKit 失败不应阻断当前设备聚合
+
+如果把它们压成一个"全局加载成功"状态, 任一低敏感度或低优先级链路都会扩大另一条链路的数据访问和可用性影响面
+
## 本地读取
### Codex app-server
-App 通过本机 `codex app-server --listen stdio://` 获取账户,额度,token 用量和 Codex 配置。
+App 通过本机 `codex app-server --listen stdio://` 获取账户, 额度, token 用量和 Codex 配置
+
+CodexBar 不自行实现账户登录. app-server 是否访问 OpenAI 服务由 Codex CLI 的正常认证和协议行为决定
-CodexBar 不自行实现账户登录。app-server 是否访问 OpenAI 服务由 Codex CLI 的正常认证和协议行为决定。
+CodexBar 只通过 stdio 与本机进程通信, 不从 app-server 响应中复制认证材料. request log 保存协议方法和结果摘要, 不是原始 wire dump
### Hook 事件
-Hook 子进程从 stdin 提取:
+Hook 子进程从 stdin 提取
- 时间和事件类型
- 工作目录
-- tool,model 和 effort
+- tool, model 和 effort
- permission 和 reviewer
-- session,turn 和 agent 身份
+- session, turn 和 agent 身份
-不把 prompt,response,tool 参数或 tool 输出写入 CodexBar Hook 文件。
+不把 prompt, response, tool 参数或 tool 输出写入 CodexBar Hook 文件
+
+工作目录只用于派生 project display name 和实时归属. 原始 Hook JSONL 仍可能包含 `cwd`, 因此它属于本地敏感上下文, 受保留期和文件权限约束. CloudKit 只上传派生后的 project 名计数, 并明确依赖用户 opt-in
### Rollout 文件
实时活动 reader 会访问 `$CODEX_HOME/sessions` 和 `$CODEX_HOME/archived_sessions`
-它只解析生命周期,时间,turn context,progress,effort 和 reviewer 等结构字段。不把对话正文复制到 CodexBar 存储或展示到 UI。
+它只解析生命周期, 时间, turn context, progress, effort 和 reviewer 等结构字段. 不把对话正文复制到 CodexBar 存储或展示到 UI
+
+rollout reader 从文件尾部按预算扫描, 一方面减少 I/O, 另一方面降低无关历史内容进入进程内存的范围. 解析 DTO 只声明所需字段, JSONDecoder 自动忽略其余内容
+
+这不是对 rollout 文件的完整隐私隔离, 因为 reader 仍需打开原文件. 因此如果未来加入全文搜索或 prompt 展示, 应视为新的产品隐私能力, 不能当作现有 reader 的自然扩展
### Codex 凭据
-Reset Credits 数量大于 `0` 时,App 读取现有 `auth.json` access token,只用于调用到期时间接口:
+Reset Credits 数量大于 `0` 时, App 读取现有 `auth.json` access token, 只用于调用到期时间接口
- 不修改 `auth.json`
- 不保存 token 副本
-- 不把 token 写入 UserDefaults,Hook 文件,CloudKit 或日志
+- 不把 token 写入 UserDefaults, Hook 文件, CloudKit 或日志
- 请求结束后只保留解析出的业务结果
+access token 只在 Reset Credits 数量大于 0 且需要到期信息时读取. 这个条件把凭据读取限制到确有业务价值的路径, 常规额度刷新不触碰 `auth.json`
+
+网络错误中可能包含请求描述, 记录前必须确认不会把 Authorization header 拼进错误文本. 当前日志只记录错误分类和非敏感 detail
+
## 本地持久化
### App 用户目录
@@ -76,17 +150,25 @@ Reset Credits 数量大于 `0` 时,App 读取现有 `auth.json` access token
| --- | --- | --- |
| `HookEvents/events` | 原始结构化 Hook 事件 | 210 天 |
| `HookEvents/daily.jsonl` | 日级聚合 | 210 天 |
-| `HookEvents/maintenance.json` | 文件游标,generation 和维护状态 | 持续更新 |
+| `HookEvents/maintenance.json` | 文件游标, generation 和维护状态 | 持续更新 |
| `HookEvents/Sync` | CloudKit 缓存和游标 | 同步状态有效期间 |
| `ActivityProtection/state.json` | 哈希任务身份和时间戳 | 最后进展后最长 24 小时 |
-最近 3 天的日聚合可以保留 session 和 turn ID 明细用于准确去重。更早数据只保留计数。
+最近 3 天的日聚合可以保留 session 和 turn ID 明细用于准确去重. 更早数据只保留计数
+
+3 天 identity 明细是精确去重与长期最小化之间的折中
+
+- 近期 Hook 文件仍可能补写或重复, 需要 identity 集合正确合并
+- 远期数据变化概率低, 只保留总数可显著缩小长期身份暴露
+- 压缩后不能从计数恢复 identity, 因此算法变化统一从仍在 210 天保留期内的原始 JSONL 重建
+
+原始事件和日聚合使用相同的 210 天上限, 避免派生数据已经清理但更敏感的原始数据仍无限保留
匿名任务不生成异常会话保护标识, 因此不会写入 `ActivityProtection/state.json`
### UserDefaults
-UserDefaults 保存:
+UserDefaults 保存
- 功能开关和设置选项
- 通知阈值和声音名称
@@ -95,7 +177,9 @@ UserDefaults 保存:
- 有界的通知去重 key
- CodexBarHelper fingerprint 等运行配置
-持久化 key 改名,结构变化或默认值变化需要考虑旧版本升级行为。
+持久化 key 改名, 结构变化或默认值变化需要考虑旧版本升级行为
+
+UserDefaults 不是无 schema 存储. 对已有 key 改名, 枚举 raw value 变化或缺失默认值变化都会改变升级用户行为. 这类修改属于兼容性问题, 必须先确定迁移和降级策略
### CodexBarHelper 目录
@@ -103,30 +187,32 @@ UserDefaults 保存:
/Library/Application Support/CodexBar/helper-state.json
```
-文件只保存 CodexBarHelper 是否拥有 `SleepDisabled` 的恢复事务,不包含 Codex 任务,账户或 Hook 数据。
+文件只保存 CodexBarHelper 是否拥有 `SleepDisabled` 的恢复事务, 不包含 Codex 任务, 账户或 Hook 数据
-目录和文件由 root 管理。详细权限和恢复策略见 [防睡眠系统](sleep-prevention.md)
+目录和文件由 root 管理. 详细权限和恢复策略见 [防睡眠系统](sleep-prevention.md)
## 内存日志和系统日志
-App 内 [`RequestLog.swift`](../../CodexBar/Services/CodexStatus/RequestLog.swift) 是最多 500 条的内存 ring buffer,进程退出后消失。
+App 内 [`RequestLog.swift`](../../CodexBar/Services/CodexStatus/RequestLog.swift) 是最多 500 条的内存 ring buffer, 进程退出后消失
-请求日志用于诊断 app-server 协议。即使只存在内存,也不应写入 OAuth token 或 Hook 内容。
+请求日志用于诊断 app-server 协议. 即使只存在内存, 也不应写入 OAuth token 或 Hook 内容
-统一系统日志 subsystem 为 `app.zabrian.codexbar`,Debug 版本带 `.debug` 后缀。
+ring buffer 的 500 条上限既控制内存, 也限制打开日志窗口时的渲染成本. 它不是审计日志, 不能承担跨启动问题追踪. 需要跨启动诊断时使用统一系统日志, 仍需遵守相同字段边界
-系统日志只应记录:
+统一系统日志 subsystem 为 `app.zabrian.codexbar`, Debug 版本带 `.debug` 后缀
+
+系统日志只应记录
- 操作阶段和结果
- 状态分类
- 不敏感计数
- 可定位模块的错误信息
-系统日志不应记录:
+系统日志不应记录
- OAuth token
-- prompt,response 或 tool 内容
-- session ID,turn ID 或 agent ID
+- prompt, response 或 tool 内容
+- session ID, turn ID 或 agent ID
- 完整项目路径或敏感项目名
- 账户额度和 token 用量明细
@@ -138,13 +224,13 @@ App 内 [`RequestLog.swift`](../../CodexBar/Services/CodexStatus/RequestLog.swif
| CloudKit private database | 同步日级 Hook 聚合 | 用户主动开启同步 |
| Sparkle appcast 和更新资源 | 检查或安装更新 | 自动检查或用户手动检查 |
-账户,额度和 token 用量通过本机 app-server stdio 获取,CodexBar 不直接请求对应账户 API。
+账户, 额度和 token 用量通过本机 app-server stdio 获取, CodexBar 不直接请求对应账户 API
-CodexBarHelper 不进行任何网络访问。
+CodexBarHelper 不进行任何网络访问
## CloudKit 边界
-CloudKit 只上传日级聚合字段:
+CloudKit 只上传日级聚合字段
- 设备 pseudonym
- 日期和 source generation
@@ -154,18 +240,34 @@ CloudKit 只上传日级聚合字段:
- model 计数
- 更新时间
-CloudKit 不上传:
+CloudKit 不上传
- 原始 Hook JSONL
-- session,turn 或 agent ID
+- session, turn 或 agent ID
- 完整工作目录
-- prompt,response,tool 参数或输出
-- Codex 账户,额度和 token 用量
+- prompt, response, tool 参数或输出
+- Codex 账户, 额度和 token 用量
- access token
- App 请求日志
- Activity Protection 状态
-project 显示名可能由目录名派生,仍可能包含用户敏感信息。同步开关必须保持用户主动选择。
+project 显示名可能由目录名派生, 仍可能包含用户敏感信息. 同步开关必须保持用户主动选择
+
+HMAC 设备 pseudonym 只降低硬件身份关联, 不会自动匿名化 project 名. private database 也不等于"数据不离开设备". 因此设置文案和开发文档都必须继续说明同步内容, 不能因为 CloudKit 属于用户账户就改成默认开启
+
+## root helper 的数据隔离
+
+CodexBarHelper 只需要知道 3 类状态
+
+- 哪个已验证客户端持有哪一代 lease
+- `SleepDisabled` 当前实测值
+- CodexBar 是否拥有恢复责任
+
+它不需要 task ID, project 名, Hook 路径, 账户状态或用户设置全文. XPC 只传布尔请求, client session ID, generation 和 update identifier
+
+这种能力最小化意味着即使普通 App 层以后新增网络或数据功能, root 进程也不会自动获得这些能力. 不应为了复用文件读取或网络代码把业务 service 链接进 helper
+
+helper 的 ownership 文件不是用户偏好, 而是 crash recovery 事务记录. 它必须由 root 拥有, 拒绝 group 或 world 可写目录, 并通过 full sync 加原子 rename 确保重启后能判断是否需要恢复
## 文件安全
@@ -173,9 +275,45 @@ project 显示名可能由目录名派生,仍可能包含用户敏感信息。
- JSONL 只追加完整行
- 聚合和状态文件使用可恢复写入流程
- Activity Protection 文件权限为 `0600`
-- CodexBarHelper 状态通过 root owner,权限检查,full sync 和原子 rename 提交
+- CodexBarHelper 状态通过 root owner, 权限检查, full sync 和原子 rename 提交
- Debug 和 Release 共享的数据必须使用锁和兼容 schema
+## 缺失, 陈旧和不可用的隐私含义
+
+数据不可用时不能用看似友好的默认值掩盖
+
+| 状态 | 正确表达 | 错误做法 |
+| --- | --- | --- |
+| 字段从旧来源缺失 | `nil` 或 unavailable | 解码成明确的 0 |
+| app-server 缓存过期 | stale 快照 | 继续触发通知 |
+| rollout reader 不可用 | 暂停实时判定 | 使用旧任务继续防睡眠 |
+| CloudKit 离线 | 保留带来源的旧 cache | 当作当前账户新数据 |
+| 电池读取失败 | 保留上次判定并标记 unreadable | 当作没有电池 |
+
+显式降级不仅提升正确性, 也避免为了填满 UI 而读取更多备用来源或保存额外数据
+
+## 新增数据字段前的审查清单
+
+1. 写明产品目标以及没有该字段时无法完成的行为
+2. 确认字段属于凭据, 内容, 身份上下文还是聚合指标
+3. 定义采集入口和最早可以丢弃原文的层
+4. 明确内存, UserDefaults, Application Support, system log 和 CloudKit 中的存在范围
+5. 定义保留期, 删除触发和失败后的清理行为
+6. 检查 Debug 与 Release 是否共享文件或 identity
+7. 检查字段缺失与明确空值的区别
+8. 检查日志和错误对象是否会间接复制原文
+9. 如涉及 CloudKit, 网络或日志数据, 先更新隐私说明并取得明确产品决策
+10. 如涉及 schema 或旧版本共存, 先确认兼容方案再改代码
+
+## 建议的隐私故障验证
+
+- 用包含明显标记字符串的 prompt 和 tool 参数运行任务, 确认 Hook JSONL, App 日志和 CloudKit cache 均没有该字符串
+- 让项目目录名包含敏感测试词, 确认它只出现在允许的本地展示和 opt-in 聚合字段
+- 模拟 Reset Credits 请求失败, 确认 access token 不出现在内存日志和 unified log
+- 检查 CloudKit record 不包含 session, turn, agent ID 或完整路径
+- 以非 root 用户验证 helper 状态目录不可写
+- 损坏各类缓存文件, 确认系统降级或重建, 而不是扩大到备用数据采集
+
## 关键源码
- [`WorkflowHookEventRecorder.swift`](../../CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift)
diff --git a/Docs/DeveloperGuide/design-decisions.md b/Docs/DeveloperGuide/design-decisions.md
new file mode 100644
index 0000000..c834499
--- /dev/null
+++ b/Docs/DeveloperGuide/design-decisions.md
@@ -0,0 +1,315 @@
+# 设计原则与关键决策
+
+这篇文档解释 CodexBar 为什么采用现在的结构, 以及这些结构在解决什么问题
+
+它不是源码目录索引, 也不是功能列表. 阅读目标是建立一套判断标准: 当实现需要变化时, 哪些只是可以替换的手段, 哪些是必须继续成立的系统不变量
+
+## 从产品目标推导架构
+
+CodexBar 看起来只是一个菜单栏 App, 但它同时横跨 4 个性质完全不同的边界
+
+- Codex 自己的本机协议和配置
+- 持续变化的 Hook 与 rollout 文件
+- macOS 窗口, 通知和电源管理
+- 带 root 权限的系统级睡眠控制
+
+这些边界不能用同一种失败策略处理
+
+例如, 额度刷新失败时保留上一次数据通常比清空更有价值. Hook 采集失败时必须立即放弃, 因为统计不能阻塞 Codex. 防睡眠释放失败时则不能静默退出, 因为系统设置可能仍被 CodexBar 持有
+
+因此项目没有追求一个包办所有工作的全局 service, 而是先按输入来源和失败语义拆开, 再在 UI 和副作用层组合只读快照
+
+## 决策优先级
+
+遇到实现取舍时, 按以下顺序判断
+
+1. 不阻断用户正在执行的 Codex 任务
+2. 不遗留或误改系统级状态
+3. 不把旧数据, 缺失数据或不确定状态伪装成当前事实
+4. 不让迟到的异步结果覆盖更新的用户意图
+5. 不扩大特权进程, 网络和持久化数据的边界
+6. 在上述条件成立后再优化延迟, 文件大小和 UI 动画
+
+这个顺序解释了很多看起来不对称的处理
+
+- Hook recorder 获取锁超时后丢弃本次统计, 而不是继续等待
+- App 退出时可以被延后, 直到 helper 确认释放由 CodexBar 拥有的睡眠状态
+- app-server 补充接口失败时可以展示带陈旧标记的缓存, 但 method unsupported 必须展示来源缺失
+- 唤醒恢复如果没有通过新的 Hook 读取屏障, 异常会话保护继续暂停
+
+## 事实, 快照与副作用
+
+项目中的状态分为 3 层
+
+| 层级 | 含义 | 示例 |
+| --- | --- | --- |
+| 事实 | 外部系统或本地日志已经发生的输入 | Hook 事件, rollout terminal, app-server 响应 |
+| 快照 | 对一组事实按当前规则得到的可展示状态 | `CodexQuotaSnapshot`, `WorkflowSnapshot`, `CodexActivitySnapshot` |
+| 副作用 | 因可信状态变化而执行的一次性动作 | 通知, 触觉反馈, XPC 租约, CloudKit 上传 |
+
+设计上刻意不让 View 从原始事实直接执行副作用
+
+例如, 通知服务不扫描任务中心列表猜测哪个任务刚完成, 而是消费 monitor 发布的 transition. 防睡眠控制器也不解析 Hook, 它只消费活动快照中的运行和等待任务
+
+这样做有两个原因
+
+- 快照可以重复读取, transition 必须最多消费一次
+- 同一个状态机可以统一处理 bootstrap, 去重, 迟到事件和 rollout 对账, 消费者不需要各自实现一套近似规则
+
+## 3 条数据链路为什么必须独立
+
+### app-server 链路
+
+app-server 提供账户, 额度和 token 用量的周期性快照. 它适合按分钟刷新, 允许在短暂故障时展示同账户缓存
+
+### Hook 历史链路
+
+历史链路把 append-only 原始事件转成日级聚合. 它允许延迟, 可以从原始 JSONL 重建, 主要目标是长期一致性
+
+### 实时任务链路
+
+实时链路关心秒级任务状态和一次性转场. 它需要组合 Hook 与 rollout, 不能等待日级聚合完成, 也不能把十分钟前的终态当成一条新通知
+
+如果把三者合并成一条链路, 会产生错误耦合
+
+- app-server 暂时失败会让本来仍可读取的本地任务状态消失
+- 聚合重建会阻塞实时任务更新
+- 为通知设计的 terminal 去重会污染历史计数
+- CloudKit 或网络故障会反向影响本地 Hook 展示
+
+允许它们在 UI 层组合, 但不允许互相充当事实来源, 是 CodexBar 最重要的架构边界之一
+
+## 用户意图, 依赖可用性与实际效果
+
+设置类功能通常同时存在 3 种状态
+
+```text
+用户意图 -> 依赖是否可用 -> 实际效果
+```
+
+防睡眠是最完整的例子
+
+- `isEnabled` 表示用户愿意让 CodexBar 管理睡眠
+- Hook, helper, 电量和时长共同决定当前是否具备执行条件
+- `isPreventingSleep` 表示 App 与 helper 已经确认实际效果
+
+依赖暂时不可用时不能把 `isEnabled` 写回 `false`. 否则一次 RPC 故障就会永久修改用户偏好, 恢复后也无法自动继续
+
+Hook 设置同样区分
+
+- `isEnabled` 表示配置文件中安装了 handler
+- `isVerified` 表示 app-server 最近一次给出明确可用结论
+- `isOperable` 才是下游依赖应使用的状态
+
+这个三层模型比一个布尔值多一些状态, 但避免了把配置, 诊断和效果混成不可解释的开关
+
+## 不确定性必须进入类型和 UI
+
+项目中多处保留 `nil`, stale 或 degraded, 而不是统一回落为零或空数组
+
+### 缺失不等于零
+
+旧 Hook 数据没有某个计数字段时, `nil` 表示当时没有采集能力. `0` 才表示数据源明确确认没有发生
+
+如果把两者合并, 历史图表会把不可知数据画成真实零值, 后续无法再修复解释
+
+### 陈旧不等于失败
+
+同一账户的 app-server 补充接口暂时失败时, 旧额度或用量仍有参考价值. 快照用 `isRateLimitsStale` 和 `isUsageStale` 标记它们, UI 通过透明度表达可信度下降, 通知则完全跳过陈旧额度
+
+### 降级 bootstrap 不等于空闲
+
+实时 reader 无法获得稳定文件边界时会跳到文件末尾, 但同时发布 degraded 和数据源不健康. 这不是"确认当前没有任务", 而是"无法可靠恢复现有任务"
+
+## 为什么大量使用 generation
+
+CodexBar 的 I/O 大多具有以下共同风险
+
+1. 请求 A 开始
+2. 用户改变设置或 reader 被替换
+3. 请求 B 开始并先完成
+4. 请求 A 最后返回
+
+只取消 Task 不足以解决这个问题. 某些系统 API 和同步桥接不能真正取消, 旧回调仍可能到达
+
+因此关键异步路径同时维护单调递增 generation
+
+- 刷新协调器只允许当前 generation 提交
+- Hook 设置只允许最新操作更新 UI
+- tail reader 替换后丢弃旧 reader batch
+- 唤醒恢复同时校验 reader generation 和 recovery generation
+- XPC 租约请求用 generation 防止迟到的 acquire 覆盖 release
+- helper 状态请求和 CloudKit 可用性检查也按 generation 丢弃旧结果
+
+generation 的价值不是"更容易取消", 而是让提交资格成为可以验证的显式条件
+
+## 为什么使用 actor, MainActor 和锁三种并发手段
+
+三者解决的问题不同
+
+| 手段 | 解决范围 | 典型对象 |
+| --- | --- | --- |
+| `MainActor` | UI 可观察状态和 AppKit 生命周期 | Controller, ViewModel, Settings, Monitor |
+| Swift actor | 单进程内异步可变状态 | app-server, 聚合, reader, CloudKit service |
+| `flock` | 多进程共享文件事务 | Hook recorder 与主 App 的统计文件 |
+
+actor 不能保护另一个 CodexBar Hook 子进程. `flock` 也不适合承载 UI 状态. 选择并发工具时先确认竞争发生在哪个边界, 不要因为项目已经使用 actor 就把所有同步问题都塞进 actor
+
+默认 `MainActor` 让 UI 类型更安全, 代价是任何阻塞式文件或 pipe 等待都必须显式移出主 actor. `AppServerSession` 和底层 pipe reader 使用受锁保护的非隔离边界, 上层 `CodexStatusService` actor 再串行管理连接
+
+## 为什么原始日志与派生缓存分开
+
+Hook 原始 JSONL 是可审计事实, `daily.jsonl` 是当前算法生成的缓存
+
+这种结构提供 3 个长期收益
+
+- 聚合算法修正后可以重建历史, 不需要为每个旧字段设计迁移
+- 写入关键路径只追加一行, 不需要在 Codex 等待的几秒内读改写整份统计
+- CloudKit 同步可以只上传聚合, 保持原始身份和路径留在本机
+
+代价是必须明确管理 schema, offset 和来源替换. 因此维护状态保存 `sourceGeneration`, inode, size, boundary hash 和 dirty/pending 状态
+
+## `sourceGeneration` 解决的不是版本号问题
+
+同一天的事件文件可能被替换, 截断或由用户重建. 日期相同并不代表它还是同一份事实来源
+
+`sourceGeneration` 给"这份日期数据来自哪一代原始文件"一个稳定身份
+
+- 正常追加保持同一 generation
+- inode 变化, 文件缩小或已消费边界被改写时创建新 generation
+- CloudKit record name 可以区分不同 generation
+- 展示层只把明确独立的贡献相加, 同源结果按替换处理
+
+如果只用日期作为身份, 重建后的新值会和旧云端值叠加, 产生永久双重计数
+
+## 为什么实时任务同时读取 Hook 和 rollout
+
+两种来源各自只解决一半问题
+
+| 来源 | 优势 | 缺口 |
+| --- | --- | --- |
+| Hook | 延迟低, 事件类型清楚, 适合实时 UI | `Stop` 不能总是区分完成与中断, 部分上下文字段可能缺失 |
+| rollout | terminal, effort 和 reviewer 更权威 | 文件定位和解析更慢, 不适合作为唯一低延迟信号 |
+
+monitor 先用 Hook 建立活动状态, 再用 rollout 补齐生命周期. `Stop` 形成完成候选, `SessionEnd` 或新 prompt 会把任务移入短暂终态确认窗口, rollout 在宽限期内给出准确分类
+
+这不是简单的"双源合并". 冲突时需要按语义决定谁更权威, 还要防止迟到事件复活已经完成的任务
+
+## 为什么特权 helper 只接受睡眠租约
+
+App 需要 root 权限修改 `pmset disablesleep`, 但任务识别, 网络和文件解析不需要 root
+
+把策略放进 helper 会显著扩大攻击面和故障恢复范围. 当前边界把 helper 限制为一个小型执行器
+
+- 输入只有租约, generation, 状态查询和更新恢复标识
+- 命令固定为 `/usr/bin/pmset` 的固定参数组合
+- 客户端通过 code-signing requirement 校验
+- helper 不读取 Codex 文件, 不访问网络, 不接受任意路径或命令
+
+App 决定"应该怎样", helper 只负责"以受限权限执行并验证"
+
+## 为什么租约还需要所有权记录
+
+租约解决"还有没有活跃 App 请求", 所有权解决"当前系统值是不是 CodexBar 改的"
+
+两者不能互相替代
+
+- 没有租约时 helper 应撤销自己的效果
+- 但如果 `SleepDisabled=1` 原本由用户或其他 App 设置, CodexBar 没有权恢复为 `0`
+- 如果 CodexBar 完成了 `0 -> 1`, helper 必须先持久化 owned, 崩溃后才能恢复
+
+因此释放条件是"最后一个租约结束并且 ownership 为 owned", 而不是简单看到没有客户端就写 `0`
+
+## 为什么 CloudKit 同步聚合而不是原始事件
+
+跨设备展示只需要日级统计. 上传原始事件会带来额外身份信息, 更大的数据量和更复杂的去重, 却不增加当前产品能力
+
+同步聚合的收益包括
+
+- session, turn 和 agent ID 保留在本机
+- 网络和 CloudKit 操作量由事件数降为日期数
+- 本机仍然可以独立重建, 云端只保存各设备贡献
+- 设备间合并规则可以围绕 `deviceId + date + sourceGeneration` 定义
+
+project 显示名仍可能敏感, 所以同步必须由用户主动开启, 不能因为已经登录 iCloud 就默认上传
+
+## 容易忽略的小巧思
+
+### `@Published` 回调参数比现场回读更可靠
+
+Combine 的发布发生在 `willSet`. 订阅闭包执行时, 属性本身可能仍是旧值
+
+因此 Hook 可用性, 同步 activation 和防睡眠依赖在订阅路径中使用闭包参数计算, 而不是立刻回读对象属性. 这是多个看似重复的状态镜像存在的原因
+
+### 边界 hash 只覆盖已经消费的尾部
+
+历史聚合不对每个文件每轮全量 hash. 它只保存 offset 前 4 KB 的 boundary hash, 再用 mtime 判断是否需要重算
+
+正常追加只发生在 offset 之后, 不会改变这个边界. 这既能发现已消费内容被原地改写, 又避免长期持有 `stats.lock`, 让 Hook 子进程更快落盘
+
+### 状态排序有 UUID 兜底
+
+多个任务时间戳可能相同, 而 Swift sort 不稳定. 快照在时间相等时再按 UUID 字符串排序, 避免 SwiftUI diff 因无意义的顺序抖动反复刷新
+
+### 通知提交前再次检查相关性
+
+等待批准和异常保护通知从判定到系统真正接收之间存在异步窗口. 任务可能已经恢复运行
+
+通知服务在每次提交和重试前调用 `isStillRelevant`, 失效则撤回 pending 与 delivered notification. 这比只在状态变化时尝试删除更可靠
+
+### XPC 请求超时不能清除"可能持有租约"
+
+请求超时只能说明回复没有到达, 不能证明 helper 没有执行 acquire. `mayHaveHelperLease` 因此一直保留到一次明确成功的 release
+
+如果超时就直接清零, App 退出时可能跳过释放, 让 helper 等到 watchdog 才恢复系统状态
+
+### 外部睡眠来源需要持续观察
+
+任务开始时如果系统已经 `SleepDisabled=1`, helper 将来源标记为 external. 但外部来源可能在任务仍运行时自行撤销
+
+helper 定期读取实际值. 一旦 external 消失而租约仍有效, CodexBar 可以安全完成自己的 `0 -> 1` 并取得 owned, 防睡眠不会悄悄失效
+
+### 菜单栏锚点必须先验证
+
+全局快捷键触发时, `NSStatusBarButton` 可能暂时没有可用 window 或位于另一块屏幕. 直接展示 popover 会出现位置错误或完全不显示
+
+控制器先验证锚点尺寸和屏幕交集, 不可信时在鼠标所在屏幕使用 fallback panel. 两种容器共享同一个 SwiftUI 内容, 业务层不用知道当前是哪一种
+
+### 只调度最近一个真实截止时间
+
+任务过期, 完成高亮, terminal grace 和异常静默都不是靠高频 UI timer 扫描. monitor 收集所有截止时间, 只为最近一个建立 Task, 到点后重算并安排下一次
+
+这样能减少菜单栏 App 常驻时的无意义唤醒, 也让每个保留期在代码中有明确来源
+
+## 修改设计时的检查方法
+
+新增功能或修改核心语义前, 依次回答以下问题
+
+1. 新数据来自哪条链路, 它的权威来源是什么
+2. 数据缺失, 旧值, 明确零值和失败是否被区分
+3. 这是可重复读取的状态, 还是最多执行一次的 transition
+4. 异步结果返回时如何证明自己仍属于当前 generation
+5. 是否扩大了网络, 持久化, CloudKit 或 root helper 的边界
+6. 是否影响旧 UserDefaults, 本地 schema, CloudKit record 或 Debug 与 Release 共存
+7. 崩溃, 强制退出, 系统睡眠和文件替换后如何恢复
+8. 哪些日志足以区分正常降级和真实故障, 同时不泄露用户数据
+9. 哪些手动场景能验证设计不变量, 而不只是验证理想路径
+
+如果其中任何一项没有明确答案, 说明实现还没有形成完整的生命周期设计
+
+## 不应轻易改变的不变量
+
+- Hook 子进程失败不能阻断 Codex
+- 3 条数据链路保持独立
+- `CodexActivityMonitor` 是实时任务唯一状态来源
+- bootstrap 不发布历史 transition
+- `drainNow()` 保证请求后的新读取屏障
+- 缺失的计数字段不解释为 `0`
+- 原始事件是聚合缓存的重建来源
+- 聚合语义变化递增 schema 并完整重建
+- root helper 不获得网络, 任意命令或额外文件读取能力
+- 只有 CodexBar 自己取得的睡眠所有权可以由 CodexBar 恢复
+- 通知描述系统效果时, 必须在效果已经确认后发送
+- 匿名任务不进入通知, 防睡眠和异常会话保护
+- 兼容性变化必须先确定迁移与降级策略
+
diff --git a/Docs/DeveloperGuide/development.md b/Docs/DeveloperGuide/development.md
index db0600e..70f4d6c 100644
--- a/Docs/DeveloperGuide/development.md
+++ b/Docs/DeveloperGuide/development.md
@@ -9,23 +9,77 @@
- `swiftlint`
- 本机可用的 Codex CLI 或包含内置 Codex 的 App
-工程使用 `CodexBar` scheme,日常构建不需要 Developer ID 或公证凭据。
+工程使用 `CodexBar` scheme, 日常构建不需要 Developer ID 或公证凭据
## 工程结构
| 目录 | 职责 |
| --- | --- |
| `CodexBar/App` | App 启动入口 |
-| `CodexBar/Controllers` | AppKit 生命周期,菜单栏和窗口控制 |
-| `CodexBar/Models` | 业务 DTO,快照和展示模型 |
-| `CodexBar/Services` | app-server,Hook,任务,同步,通知和系统服务 |
+| `CodexBar/Controllers` | AppKit 生命周期, 菜单栏和窗口控制 |
+| `CodexBar/Models` | 业务 DTO, 快照和展示模型 |
+| `CodexBar/Services` | app-server, Hook, 任务, 同步, 通知和系统服务 |
| `CodexBar/Views` | SwiftUI 界面 |
-| `CodexBar/Resources` | plist,entitlement,本地化和资源 |
+| `CodexBar/Resources` | plist, entitlement, 本地化和资源 |
| `CodexBarHelper` | root LaunchDaemon |
| `Shared` | XPC 共享接口 |
| `Config` | 版本配置 |
| `Scripts` | 发布和维护脚本 |
+## 第一次阅读代码的建议顺序
+
+不要从 View 反向猜业务状态. 推荐沿事实流阅读
+
+1. 从 [`CodexBarApp.swift`](../../CodexBar/App/CodexBarApp.swift) 确认 Hook 子进程分流
+2. 从 [`StatusItemController.swift`](../../CodexBar/Controllers/StatusItemController.swift) 查看普通模式 composition root
+3. 选择一条数据链路阅读 source, service, snapshot 和 ViewModel
+4. 再看通知或防睡眠如何订阅上游结果
+5. 最后查看 SwiftUI 如何展示状态和发出用户意图
+
+以实时任务为例
+
+```text
+WorkflowHookEventRecorder
+ -> HookEventTailReader
+ -> CodexActivityMonitor
+ -> CodexActivitySnapshot / CodexActivityTransition
+ -> StatusItemController 组装
+ -> UI
+ -> CodexNotificationService
+ -> KeepAliveController
+```
+
+先找到 authoritative state 能避免把 UI 缓存, 通知去重集合或 controller 中间态误认为业务事实
+
+## 修改前先写清楚 5 件事
+
+实现一个非纯视觉变化前, 至少在设计或开发笔记中回答
+
+| 问题 | 示例 |
+| --- | --- |
+| 目标事实 | "任务已经等待用户批准", 而不是"显示橙点" |
+| 权威来源 | reviewer 确认后的 Hook event |
+| 派生消费者 | 活动卡片, 通知, 防睡眠 |
+| 失败语义 | reader 不可用时暂停判定 |
+| 验收证据 | 转场一次, 不补发 bootstrap, 恢复后对账 |
+
+这一步的价值不是增加流程, 而是提前发现一个字段被 3 个副作用消费者赋予了不同含义
+
+## 常见改动应该落在哪一层
+
+| 改动 | 首选位置 | 避免放置 |
+| --- | --- | --- |
+| app-server 协议 method | `CodexStatus/` service 和 DTO | SwiftUI View |
+| Hook 原始字段 | recorder model 和 aggregation projection | CloudKit record 直接读取 stdin |
+| 实时任务转场 | `CodexActivityMonitor` | 通知服务从历史列表推断 |
+| 日统计展示 | `WorkflowViewModel` 投影 | View 重新合并 raw event |
+| 系统通知 | `CodexNotificationService` | 按钮 action 或 View lifecycle |
+| 防睡眠条件 | `KeepAliveController.sleepBlockReason` | 多个 UI computed property |
+| 窗口行为 | AppKit Controller | service 或 model |
+| 用户默认值 | 对应 Settings 类型 | 分散的 `UserDefaults.standard` 调用 |
+
+小改动优先延伸现有类型职责. 只有当新能力拥有独立生命周期, 状态所有权或故障边界时才值得新建 service
+
## 日常检查
### 构建
@@ -44,7 +98,7 @@ xcodebuild \
swiftformat .
```
-工程使用 Swift 6 和 4 空格缩进,配置位于 `.swiftformat`
+工程使用 Swift 6 和 4 空格缩进, 配置位于 `.swiftformat`
### 静态检查
@@ -54,11 +108,41 @@ swiftlint
规则位于 `.swiftlint.yml`
-仓库当前没有 XCTest target 或覆盖率门槛。构建,格式化和 lint 不能替代受影响流程的手动验证。
+仓库当前没有 XCTest target 或覆盖率门槛. 构建, 格式化和 lint 不能替代受影响流程的手动验证
+
+### 推荐检查顺序
+
+```text
+检查工作树范围
+ -> 完成最小实现
+ -> swiftformat
+ -> 审查格式化 diff
+ -> swiftlint
+ -> xcodebuild
+ -> 针对性手动验证
+ -> git diff --check
+```
+
+先格式化再构建可以让最终验证覆盖真正准备提交的代码. 但仓库已有用户未提交改动时, 不应无差别格式化整个仓库造成无关修改. 先用 `git status --short` 和 `git diff --name-only` 确认范围, 必要时只格式化本次触及的 Swift 文件
+
+`xcodebuild` 验证 Swift 6 并发检查, target membership, entitlement 和资源引用. `swiftlint` 验证风格与部分静态规则. 两者不能验证 AppKit focus, XPC crash recovery 或通知 relevance
+
+纯文档变更仍按仓库约定运行格式化, lint 和构建. 这些检查不验证文档内容, 因此还要额外检查 Markdown 相对链接, `git diff --check` 和仓库中文标点规则
+
+### 如何读构建失败
+
+优先找第一条实际 `error:` 而不是最后的 `BUILD FAILED`
+
+- actor isolation error 通常说明状态所有权不清, 不应先加 `nonisolated(unsafe)` 压掉
+- missing file 或 resource error 先检查 target membership 和 Xcode project 引用
+- helper protocol error 需要同时检查 App target, Helper target 和 `Shared` 接口
+- entitlement 或 signing error 要先确认当前是 Debug 还是 Release identity
+
+修复第一处根因后重新构建, 后续大量泛型或 module error 往往只是级联结果
## 日志
-查看 Release 系统日志:
+查看 Release 系统日志
```bash
/usr/bin/log stream \
@@ -66,59 +150,152 @@ swiftlint
--style compact
```
-Debug subsystem 带 `.debug` 后缀。
+Debug subsystem 带 `.debug` 后缀
+
+App 内日志窗口展示当前进程最近 500 条 app-server 交互日志, 适合排查 CLI 定位, handshake, method unsupported 和重试
+
+### 日志应回答什么
-App 内日志窗口展示当前进程最近 500 条 app-server 交互日志,适合排查 CLI 定位,handshake,method unsupported 和重试。
+一条有用状态机日志应至少能回答
+
+- 谁触发了本轮操作
+- 当前想达到什么状态
+- 哪个阶段失败
+- 采取了什么降级或重试动作
+- 操作耗时和处理规模
+
+仓库使用 `LogTrigger`, `LogDuration` 和 `LogFields.joined` 统一这些字段. 高频轮询只在状态翻转或结果变化时记录, 避免真正异常被空转日志覆盖
+
+推荐用稳定英文 key 加受控值, 例如
+
+```text
+trigger=wake want=0 reason=lowBattery elapsed=0.183s
+```
+
+不要记录通知正文, 完整路径, identity 或 token. 如果错误的 `localizedDescription` 可能包含敏感请求信息, 应先做错误分类再记录
+
+### 按 subsystem 和阶段排查
+
+| 症状 | 优先日志和状态 |
+| --- | --- |
+| 额度不刷新 | app-server handshake, method, retry, stale |
+| Hook 没有统计 | hooks 配置, recorder timeout, maintenance counts |
+| 实时任务卡住 | tail reader generation, rollout reconcile, data source availability |
+| 同步缺数据 | sync stage, local 和 confirmed 数量, replacement dates |
+| 通知不出现 | authorization, kind, duplicate 或 obsolete |
+| 防睡眠不生效 | block reason, helper registration, XPC generation, source |
## 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 或系统授权时不要混用两个配置。
+排查 CodexBarHelper 安装, LaunchDaemon 或系统授权时不要混用两个配置
+
+Hook handler 绑定当前 App 可执行文件路径. 在 Debug 和 Release 之间切换时, 先确认实际安装的 handler 指向目标版本
-Hook handler 绑定当前 App 可执行文件路径。在 Debug 和 Release 之间切换时,先确认实际安装的 handler 指向目标版本。
+### 为什么两个构建仍会共享部分状态
+
+Debug 和 Release bundle ID 分离是为了让 App, helper 注册和系统授权互不覆盖. 但 Hook 原始数据与 Activity Protection 需要观察同一个 Codex 工作事实, 因而按设计共享文件
+
+共享意味着
+
+- 文件写入必须使用 `flock`, actor 只保护单进程
+- schema 必须在两个版本共存时可解释
+- identity hash 算法变化会同时影响两个构建
+- 排查时要记录哪个 App 正在写, 哪个 helper 正在控制系统
+
+不要用修改目录名的方式临时隔离 Debug, 这会改变产品定义的数据来源并掩盖真实共存问题
## 架构规则
### 启动入口
-`WorkflowHookEventRecorder.handleIfRequested()` 必须是 App 初始化的第一项工作。
+`WorkflowHookEventRecorder.handleIfRequested()` 必须是 App 初始化的第一项工作
-`--hook-event` 模式只读取 stdin,加锁写入 JSONL 并立即退出。不初始化 UI,通知,CloudKit 或其他长期服务。
+`--hook-event` 模式只读取 stdin, 加锁写入 JSONL 并立即退出. 不初始化 UI, 通知, CloudKit 或其他长期服务
### MainActor
-UI,Controller,ViewModel 和 Settings 依赖默认隔离。阻塞文件,子进程和网络 I/O 放入 actor 或异步服务。
+UI, Controller, ViewModel 和 Settings 依赖默认隔离. 阻塞文件, 子进程和网络 I/O 放入 actor 或异步服务
+
+共享可变状态放入 actor. DTO 和跨 actor 值类型按需要补充并发声明, 不通过关闭检查绕过 Swift 6 诊断
-共享可变状态放入 actor。DTO 和跨 actor 值类型按需要补充并发声明,不通过关闭检查绕过 Swift 6 诊断。
+#### MainActor 不是 I/O 队列
+
+工程默认隔离让 UI 状态修改更清晰, 但不意味着文件和子进程工作可以同步执行在主线程
+
+合适的模式是
+
+```text
+MainActor 捕获不可变输入
+ -> actor 或 async API 执行 I/O
+ -> 返回 Sendable 结果
+ -> MainActor 校验 generation
+ -> 提交快照
+```
+
+不要把可变 controller 或 non-Sendable AppKit 对象传入后台 closure. 需要跨 actor 的 DTO 应尽量是小型 value type, 并让 `nonisolated` 表达类型本身不依赖 actor, 而不是绕开某个具体访问错误
+
+#### actor 与 `flock` 解决的问题不同
+
+- actor 串行化同一进程中的 task
+- `flock` 协调 App, Hook 子进程, Debug 和 Release 等多个进程
+
+一个 actor 内安全的 read-modify-write 仍可能被另一个进程打断. 反过来, 只有 `flock` 也不能自动保护 actor reentrancy 中 await 前后的内存状态
+
+#### `@Published` 的 `willSet` 语义
+
+Combine sink 收到新值时, 发布对象的属性可能仍是旧值. 需要基于变化后组合状态决策时
+
+- 使用 sink 参数作为正在变化的值
+- 其余未变化依赖可以从对象读取
+- 或把完整新状态封装成一个快照再发布
+
+仓库中的同步 activation 和低额度阈值重判都依赖这一规则. 将回调参数改成现场读取会产生一帧反向决策
### 数据链路
-保持以下链路独立:
+保持以下链路独立
-- app-server 账户,额度与用量
+- app-server 账户, 额度与用量
- Hook 历史聚合
- `CodexActivityMonitor` 实时任务
-新增 UI 可以组合 3 条链路的快照,但不能让一条链路成为另一条链路的隐式前置条件。
+新增 UI 可以组合 3 条链路的快照, 但不能让一条链路成为另一条链路的隐式前置条件
+
+组合只能发生在展示或显式业务策略层. 例如菜单栏可以同时展示额度条和活动点, 但 app-server 失败不能阻止 activity monitor 更新, Hook maintenance 也不能等待 CloudKit 才发布本机统计
+
+新增跨链路行为时应写出 truth table. 防睡眠就是一个合法例子: 它明确声明需要 Hook 可用和非匿名实时任务, 而不是因为两个对象恰好在同一 controller 中就形成依赖
### Hook
- handler 修改保留现有用户和第三方配置
- 启用与校验检查实际 app-server 版本不低于 `0.145.0`
- Hook 子进程失败不能阻断 Codex
-- `SessionEnd` 超时为 3 秒,其他事件为 5 秒
+- `SessionEnd` 超时为 3 秒, 其他事件为 5 秒
- `drainNow()` 必须维持读取屏障语义
- 数据源不可用时不能使用旧快照继续判定
+新增 Hook event 时要同时审查
+
+1. Codex 配置中的 handler group 和 timeout
+2. recorder 白名单字段与 fail-open 路径
+3. raw JSONL 解码的前后兼容
+4. aggregation 的计数和 missing 语义
+5. realtime monitor 是否消费该事件
+6. CloudKit 投影是否需要新字段
+7. 隐私文档和日志字段
+
+不是每个 event 都需要进入全部层. 明确写"不消费"比让下游依赖默认 decoder 行为更容易维护
+
### 聚合
-原始事件到聚合结果的算法,字段,含义或去重规则变化时:
+原始事件到聚合结果的算法, 字段, 含义或去重规则变化时
1. 递增 `WorkflowMaintenanceState.currentAggregationSchema`
2. 从保留期内原始 JSONL 完整重建
@@ -126,17 +303,25 @@ UI,Controller,ViewModel 和 Settings 依赖默认隔离。阻塞文件,子
4. 保留 missing 与 `0` 的区别
5. 标记 CloudKit 当前设备 replacement 日期
+schema 递增的判断标准是语义输出是否会因同一份 raw event 得到不同结果, 而不是 Codable 是否还能解码. 即使只修正去重规则, 也必须重建, 因为旧 daily 文件已经固化了错误结果
+
+完整重建优于字段级迁移, 因为 raw JSONL 才是事实来源. 字段级迁移必须猜测旧算法中丢失的信息, 长期会堆积不可组合的历史分支
+
### 防睡眠
- CodexBarHelper 只控制睡眠
- CodexBarHelper 不增加网络或任意命令能力
- 外部 `SleepDisabled=1` 不能被 CodexBar 声明或恢复
-- 租约,watchdog 和 owned 持久化必须共同成立
+- 租约, watchdog 和 owned 持久化必须共同成立
- App 退出前确认系统状态恢复
+修改防睡眠时先写出 acquire, release, timeout, crash 和 external-owner 5 条时序. 只验证正常开关无法证明全局系统状态可恢复
+
+任何新增 helper 方法都要先证明必须由 root 执行. 能在普通 App 完成的读取, 网络或文件操作不得因为"方便复用"放进 helper
+
### 兼容性
-以下变化属于兼容性问题:
+以下变化属于兼容性问题
- 持久化 key 改名或结构变化
- 本地 schema 变化
@@ -145,13 +330,59 @@ UI,Controller,ViewModel 和 Settings 依赖默认隔离。阻塞文件,子
- Debug 与 Release 共享身份计算变化
- 最低系统版本或 API 可用性变化
-这些变化会影响旧数据,旧 App 或 Debug 与 Release 共存,需要配套的迁移和降级设计。
+这些变化会影响旧数据, 旧 App 或 Debug 与 Release 共存, 需要配套的迁移和降级设计
+
+根据仓库约定, 任何兼容性问题都不能由实现者默默选择. 在修改前向用户说明
+
+- 受影响版本和数据范围
+- 保留旧格式, 一次迁移, 完整重建或明确丢弃的可选方案
+- 每种方案的失败模式和未来维护成本
+- 是否支持旧 App 与新 App 同时运行
+- 如何验证升级和必要时降级
+
+得到选择后再实现. 文档中记录最终不变量, 不只记录迁移步骤
+
+## 常见改动配方
+
+### 新增设置项
+
+1. 在对应 Settings 或 controller 中定义唯一 key 和缺失时默认值
+2. 明确旧用户升级后的值, 不依赖 Swift 属性默认值碰巧一致
+3. 把设置变化接入唯一 reconcile 入口
+4. 避免 View 自己写 `UserDefaults`
+5. 验证首次安装, 已有安装和切换后立即生效
+
+### 新增状态字段
+
+1. 确认字段是事实, 派生状态还是展示格式
+2. 放入最靠近权威来源的 model
+3. 定义 `nil`, empty, zero 和 stale
+4. 检查 Equatable snapshot 是否应因它变化
+5. 检查通知, 防睡眠和 UI 是否需要消费
+6. 如需持久化或同步, 先走兼容性与隐私审查
+
+### 新增异步刷新
+
+1. 确定触发来源和 freshness 规则
+2. 使用 single-flight 或 coordinator 合并同类请求
+3. 为连接或 source replacement 增加 generation
+4. 在 await 后重新验证当前资格
+5. 定义取消, 超时和最后可用快照策略
+6. 只在状态变化或最终结果记录日志
+
+### 新增窗口或侧边面板
+
+1. 决定它属于菜单交互表面还是独立辅助窗口
+2. 复用 `HostingWindowController` 或 `MenuSideDetailPanel`
+3. 加入互斥名册和 extra hit region
+4. 处理多屏 visible frame 和 Space
+5. 验证 key focus, activation 和关闭动画中间态
## 按改动类型验证
### 菜单和窗口
-- 左键,右键和 Control 点击行为
+- 左键, 右键和 Control 点击行为
- popover 外部点击关闭
- 侧边面板 hit region 和互斥
- 设置与日志窗口焦点
@@ -163,13 +394,13 @@ UI,Controller,ViewModel 和 Settings 依赖默认隔离。阻塞文件,子
- 保留已有 handler
- 版本不满足时拒绝启用
- 所有事件能在超时内落盘
-- 文件替换,截断和跨日读取
+- 文件替换, 截断和跨日读取
- schema 升级完整重建
- missing 字段不会显示为 `0`
### 实时任务
-- 运行,等待批准,完成和中断转场
+- 运行, 等待批准, 完成和中断转场
- auto review 不进入等待状态
- subagent 归属父任务
- bootstrap 不发送通知
@@ -181,7 +412,7 @@ UI,Controller,ViewModel 和 Settings 依赖默认隔离。阻塞文件,子
- 首次 backfill
- 多设备合并不重复本机贡献
- 重建只替换当前设备日期
-- iCloud 离线,账户切换和恢复
+- iCloud 离线, 账户切换和恢复
- 保留期清理
### 通知
@@ -203,9 +434,44 @@ UI,Controller,ViewModel 和 Settings 依赖默认隔离。阻塞文件,子
- 正常退出和异常退出恢复
- Debug 与 Release 分离
+## 手动验证如何留下可复查证据
+
+每个受影响流程至少记录
+
+- 使用的 Debug 或 Release 构建
+- 前置设置和数据状态
+- 操作序列
+- 预期 UI 与实际 UI
+- 对应日志关键字段
+- 是否检查重启, 失败和恢复路径
+
+例如 Hook 唤醒恢复可以记录
+
+```text
+前置: 1 个非匿名 running task, 防睡眠开启
+操作: 让 Mac 睡眠后唤醒, rollout 在睡眠期间写入 terminal
+预期: drainNow 新一轮成功后任务结束, 不发 bootstrap 通知, helper lease 释放
+日志: trigger=wake, reader generation 更新, rollout reconcile 完成
+```
+
+这种记录比"手测通过"更容易在未来回归时重现
+
+## 完成定义
+
+一项改动只有同时满足以下条件才算完成
+
+- 代码放在正确状态所有者中, 没有复制第二份规则
+- 正常, 缺失, stale, 失败和恢复语义明确
+- 并发请求有取消或 generation 边界
+- 兼容性和隐私影响已确认
+- 格式化, lint 和构建按变更范围通过
+- 受影响流程完成手动验证
+- DeveloperGuide 与实际常量, schema 和行为一致
+- `git diff` 中没有无关用户改动或意外格式化
+
## 发布脚本
-以下脚本需要 Developer ID,签名,公证或 appcast 凭据,不用于日常验证:
+以下脚本需要 Developer ID, 签名, 公证或 appcast 凭据, 不用于日常验证
- `Scripts/build.sh`
- `Scripts/dmg.sh`
diff --git a/Docs/DeveloperGuide/hook-and-aggregation.md b/Docs/DeveloperGuide/hook-and-aggregation.md
index 8804a6a..c077800 100644
--- a/Docs/DeveloperGuide/hook-and-aggregation.md
+++ b/Docs/DeveloperGuide/hook-and-aggregation.md
@@ -1,8 +1,19 @@
# Hook 采集与历史聚合
+## 设计出发点
+
+Hook 链路同时服务两个看似接近但要求相反的目标
+
+- 在 Codex 关键路径上尽快记录事实
+- 在主 App 中可靠地维护长期统计
+
+采集端必须短小, 有界和允许失败. 聚合端则可以异步运行, 需要检测文件变化, 修复损坏缓存并支持完整重建
+
+因此实现采用 append-only 原始 JSONL 加可重建日聚合, 而不是让 Hook 子进程直接更新一份复杂统计对象
+
## 链路职责
-Hook 链路把 Codex 生命周期事件转换为可重建的本地历史统计:
+Hook 链路把 Codex 生命周期事件转换为可重建的本地历史统计
```text
Codex Hook
@@ -13,13 +24,33 @@ Codex Hook
-> 活跃度 UI 和 CloudKit 同步
```
-原始事件是事实来源,日级聚合是可重建缓存。聚合算法或字段语义变化时,必须从保留期内的原始事件完整重建。
+原始事件是事实来源, 日级聚合是可重建缓存. 聚合算法或字段语义变化时, 必须从保留期内的原始事件完整重建
+
+### 为什么不在 Hook 子进程里直接聚合
+
+直接读改写 `daily.jsonl` 看起来少一层文件, 实际会带来 4 个问题
+
+- 每个 Hook 都要解码和重写历史数据, 事件越多延迟越高
+- 子进程在 Codex 的超时预算内, 聚合失败会放大成任务延迟
+- 算法升级后没有原始事实可重算
+- 多个并发 Codex session 更容易在读改写之间丢失更新
+
+当前方案把关键路径缩成一条 append. 主 App 可以在自己的节奏里批量聚合, 失败时保留原始事件等待下一轮修复
+
+### 原始事实和缓存的责任
+
+| 文件 | 是否权威 | 允许怎样恢复 |
+| --- | --- | --- |
+| `events/YYYY-MM-DD.jsonl` | 是 | 只追加, 超过保留期后清理 |
+| `daily.jsonl` | 否 | 可从原始事件完整重建 |
+| `maintenance.json` | 否 | 缺失或 schema 变化时重新对账 |
+| `stats.lock` | 不保存业务数据 | 只协调跨进程事务 |
## 安装与校验
-[`CodexHookSettings.swift`](../../CodexBar/Services/Settings/CodexHookSettings.swift) 通过 app-server 读取和修改 Hook 配置。
+[`CodexHookSettings.swift`](../../CodexBar/Services/Settings/CodexHookSettings.swift) 通过 app-server 读取和修改 Hook 配置
-启用前必须满足:
+启用前必须满足
- 当前可执行文件路径可解析
- 实际 app-server 版本不低于 `0.145.0`
@@ -27,9 +58,9 @@ Codex Hook
- `hooks/list` 返回可信来源
- 所需事件集合完整
-目标配置文件位于 `$CODEX_HOME/hooks.json`,未设置 `CODEX_HOME` 时位于 `~/.codex/hooks.json`
+目标配置文件位于 `$CODEX_HOME/hooks.json`, 未设置 `CODEX_HOME` 时位于 `~/.codex/hooks.json`
-安装逻辑把 CodexBar handler 作为独立命令加入现有配置。它不会用一份模板覆盖整个文件:
+安装逻辑把 CodexBar handler 作为独立命令加入现有配置. 它不会用一份模板覆盖整个文件
- 保留用户已有字段
- 保留其他应用已有 handler
@@ -37,11 +68,65 @@ Codex Hook
- 禁用时只移除精确匹配的 CodexBar handler
- 无法识别的配置保持原样
-`isEnabled` 只表示 handler 存在,`isVerified` 表示最近一次 app-server 校验通过。UI 只有在 `isOperable` 成立时把 Hook 当作可工作数据源。
+`isEnabled` 只表示 handler 存在, `isVerified` 表示最近一次 app-server 校验通过. UI 只有在 `isOperable` 成立时把 Hook 当作可工作数据源
+
+### 为什么安装和验证是两件事
+
+`hooks.json` 中存在命令只能证明配置写在磁盘上, 不能证明 Codex 会执行它
+
+实际执行还可能被以下条件阻止
+
+- 当前 app-server 版本过低
+- `features.hooks` 被全局关闭
+- handler 事件集合不完整
+- app-server 解析到其他来源文件
+- handler 处于 untrusted 或 modified
+
+因此 `isEnabled` 是本地配置事实, `isVerified` 是 Codex 对当前来源的最近明确结论. 防睡眠和任务通知只依赖两者合成的 `isOperable`
+
+临时 RPC 失败只代表本轮无法验证, 不能反推 handler 已失效. 此时保留上一次明确结论, 同时展示操作错误供用户排查
+
+### 启用事务的顺序
+
+```text
+确认运行中 app-server >= 0.145.0
+ -> 确认 features.hooks 没有全局关闭
+ -> 读取现有 hooks.json
+ -> 只移除当前 executable 的旧 CodexBar handler
+ -> 为全部事件追加独立 group
+ -> 原子写回 hooks.json
+ -> hooks/list 读取 app-server 实际解析结果
+ -> 仅信任 command + sourcePath + event 都匹配的条目
+ -> 再次 hooks/list 完整校验
+```
+
+前置检查发生在文件修改之前. 版本或全局开关不满足时, 用户文件一个字都不会改变
+
+信任匹配同时要求 command 和 `sourcePath`. 只按 executable 匹配可能误信任另一份配置中的相同命令, 只按 source 匹配则可能碰到用户自己的 handler
+
+### 禁用为什么先查询信任 key
+
+app-server 的 Hook key 来自它当前解析到的 handler. 如果先从 `hooks.json` 删除命令, 后续 `hooks/list` 已经无法反查对应 key
+
+因此禁用流程先保存精确匹配条目的 key, 再删 handler, 最后从 `hooks.state` 中清理这些 key. 清理时先读取完整 state 再 replace, 保留用户和其他工具的信任项
+
+信任清理失败不会把 handler 重新装回去. UI 会表达"Hook 已关闭, 但清理未完成", 因为停止采集的用户意图已经成功
+
+### 为什么每个事件使用独立 group
+
+CodexBar 不把命令塞进用户已有 group. 独立 group 让卸载时可以只删除自身 handler, 不需要理解用户 matcher 或其他 handler 之间的组合语义
+
+对于结构异常的同级条目, 移除逻辑选择跳过而不是让整个开关失败. CodexBar 只负责识别自己的命令, 不把自己变成用户 Hook 配置的全局校验器
+
+### 异步设置操作的代际
+
+用户可以快速开关 Hook, App 激活也会触发校验. `CodexHookSettings` 每次操作递增 `updateGeneration` 并取消旧 Task
+
+每个文件写入或 RPC await 之后都会再次检查 generation. 旧操作即使无法真正取消, 也不能把新的开关状态或错误信息覆盖回去
## 支持的事件
-CodexBar 订阅以下 Hook 事件:
+CodexBar 订阅以下 Hook 事件
| 事件 | 聚合或实时用途 |
| --- | --- |
@@ -57,11 +142,19 @@ CodexBar 订阅以下 Hook 事件:
| `SubagentStart` | 记录 subagent 启动 |
| `SubagentStop` | 记录 subagent 结束 |
+### 事件字段和用途并不完全相同
+
+历史计数需要事件名, 日期, project, model 和身份集合. 实时状态还需要 turn, reviewer, effort, tool 和 agent 关联
+
+把两类需求统一在一条最小原始记录中, 可以让 recorder 只写一次, 两个下游各自选择所需字段. 但新增字段前仍要证明至少有一个消费者需要它, 不能因为 Hook payload 中存在就全部持久化
+
+`PermissionRequest` 和 `UserPromptSubmit` 的 reviewer 或 effort 可能不在 Hook payload 中. recorder 只在这两个事件上按 turn 定向读取 rollout 尾部, 避免所有事件都承担额外文件 I/O
+
## Hook 子进程
[`WorkflowHookEventRecorder.swift`](../../CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift) 在 App 启动最早阶段检查 `--hook-event`
-命中后只执行以下工作:
+命中后只执行以下工作
1. 从 stdin 读取事件 JSON
2. 提取统计和状态机需要的最小字段
@@ -70,20 +163,56 @@ CodexBar 订阅以下 Hook 事件:
5. 在同一个锁事务中标记维护状态
6. 立即退出
-handler 超时由事件决定:
+handler 超时由事件决定
| 事件 | 超时 |
| --- | --- |
| `SessionEnd` | 3 秒 |
| 其他事件 | 5 秒 |
-锁等待预算为 handler 超时减 2 秒。获取锁时从 1 ms 开始指数退避,单次等待最多 20 ms。
+锁等待预算为 handler 超时减 2 秒. 获取锁时从 1 ms 开始指数退避, 单次等待最多 20 ms
+
+stdin 无效, 文件锁超时或写入失败都会被吞掉. Hook 子进程不能因为统计失败而阻断 Codex
+
+### 为什么仍然返回成功
+
+Hook 统计是 CodexBar 的辅助能力, 不是 Codex 完成任务的必要步骤. 如果 recorder 把解析或磁盘错误作为非零退出码返回, 一次统计故障就可能让用户的 Codex 流程失败
+
+因此显式进入 `--hook-event` 后, 无论输入是否有效都返回已处理并退出成功. 失败只意味着少一条统计, 不升级为上游任务故障
+
+### 锁内事务为什么同时写事件和维护状态
+
+一次采集在同一把 `stats.lock` 内完成
+
+```text
+检查当前文件身份
+ -> 必要时开始新 source generation
+ -> append 完整 JSONL 行
+ -> 标记该日期 pending
+ -> 原子保存 maintenance.json
+```
+
+如果 append 和 pending 分成两个锁事务, App 可能在中间完成一次维护并认为当天已经追平. 随后 recorder 只写事件却来不及标记 pending, 新行会静默等待到下一次全目录对账
+
+锁内联合提交让"文件已经增长"和"维护知道需要读取"保持一致
-stdin 无效,文件锁超时或写入失败都会被吞掉。Hook 子进程不能因为统计失败而阻断 Codex。
+### 为什么锁等待只使用超时预算的一部分
+
+Codex 对 `SessionEnd` 最多等待 3 秒, 其他事件最多 5 秒. recorder 把锁等待限制为总预算减 2 秒
+
+预留时间用于编码, append, 保存维护状态和进程退出. 如果把全部预算花在等锁上, Codex 可能正好在写入中途终止进程, 留下半行或未配对的维护状态
+
+等待从 1 ms 指数退避到最多 20 ms. 主 App 的正常持锁区很短, 小步起始能在锁刚释放时迅速继续, 上限则避免高竞争时 busy loop
+
+### 锁文件为什么用一次 `open(O_CREAT)` 创建并打开
+
+不能先判断文件不存在, 创建后再打开. 两个进程可能分别创建不同 inode, 后创建的一方替换目录项后, 双方会各自锁住不同文件并都认为自己独占
+
+单次 `open` 让创建和打开成为同一个原子入口, 所有参与者对同一路径上的同一 inode 使用 `flock`
## 采集字段
-原始记录只保留计算统计和实时状态所需的信息:
+原始记录只保留计算统计和实时状态所需的信息
- 时间戳和事件名
- 工作目录
@@ -93,23 +222,41 @@ stdin 无效,文件锁超时或写入失败都会被吞掉。Hook 子进程不
- session ID 和 turn ID
- agent 与 parent 关系
-对于 `UserPromptSubmit` 和 `PermissionRequest`,输入事件可能不包含 reviewer 或 effort。recorder 会在必要时从 rollout transcript 尾部回查匹配的 `turn_context`
+对于 `UserPromptSubmit` 和 `PermissionRequest`, 输入事件可能不包含 reviewer 或 effort. recorder 会在必要时从 rollout transcript 尾部回查匹配的 `turn_context`
-回查范围如下:
+回查范围如下
- 单次最多读取 512 KB
- 只提取 reviewer 和 effort 等结构字段
- 不把 prompt 或 response 内容写入 Hook 统计
+### 输入归一化
+
+Hook payload 在不同版本中可能把标识或时间表示为不同 JSON 类型. `WorkflowHookPayload` 集中做宽松归一化
+
+- string 会去掉首尾空白, 空串转为缺失
+- number 标识转换为字符串
+- 时间同时接受 ISO-8601, 本地 timestamp, Unix 秒和 Unix 毫秒
+- 缺失时间回退到 recorder 当前时间
+- 缺失 cwd 回退到子进程当前目录
+
+宽松只发生在外部输入边界. 一旦转成 `WorkflowHookEvent`, 下游使用统一类型, 不在聚合器和 monitor 中重复猜测协议差异
+
+### rollout 尾部回查的边界
+
+回查只读取 transcript 最后 512 KB, 丢弃可能被截断的第一行, 再从后向前寻找匹配 turn 的 `turn_context`
+
+从后向前是因为同一个 turn 的最新上下文更接近文件尾. 限制读取范围是为了守住 Hook 超时, 找不到时保留字段缺失而不是扩大成无界扫描
+
## 本地文件
-默认数据根目录是:
+默认数据根目录是
```text
~/Library/Application Support/CodexBar/HookEvents/
```
-目录结构如下:
+目录结构如下
```text
HookEvents/
@@ -132,22 +279,104 @@ HookEvents/
| `stats.lock` | 协调 Hook 子进程和 App 维护任务 |
| `Sync/*` | CloudKit 同步游标和缓存 |
-原始事件和日聚合最长保留 210 天。session ID 和 turn ID 的明细列表只保留 3 天,更早日期压缩为计数,降低本地文件体积和身份信息留存。
+原始事件和日聚合最长保留 210 天. session ID 和 turn ID 的明细列表只保留 3 天, 更早日期压缩为计数, 降低本地文件体积和身份信息留存
+
+### 为什么选择 JSONL
+
+JSONL 与这一链路的写入模式匹配
+
+- recorder 只需要在文件尾追加一条完整记录
+- 单行损坏可以被隔离, 不必让整个文件解码失败
+- 文件可以按日切分和保留期清理
+- 人工排查时仍可检查单条结构
+- 聚合缓存和远端缓存也能使用相同的逐行恢复策略
+
+普通 JSON 数组每次 append 都要改写尾部结构. 数据库会增加 schema, 锁和部署复杂度, 但当前查询只按日期顺序扫描, 没有足够收益
+
+### 完整行是提交单位
+
+reader 只推进到最后一个 newline 对应的 offset. 文件尾如果正在写入半行, 本轮保留旧 offset, 下一轮等完整行出现后再处理
+
+`JSONLines.decodeWithFailures` 按行解码. 一条坏行只增加 corrupt count, 不会连带丢掉同一读取块中的其他正确事件
+
+### 为什么身份明细只保留 3 天
+
+session 和 turn ID 用于近期精确去重, 但长期展示只需要计数
+
+3 天后把 identifiers 压缩为 count, 可以同时降低文件体积和身份信息保留. 聚合模型必须记录该字段当前是 retained 还是 compacted, 否则无法判断后续新事件能否继续用 ID 精确去重
+
+原始事件仍在 210 天保留期内, 所以算法升级时可以完整重建. CloudKit 从不上传这些原始身份
## 增量读取与来源代际
-聚合器记录每个原始文件的 inode,size,offset 和 source generation:
+聚合器记录每个原始文件的 inode, size, offset 和 source generation
- 正常追加时从上次 offset 继续读取
- inode 改变表示文件被替换
- size 小于 offset 表示文件被截断
- 替换或截断会创建新的 source generation
-source generation 让同一天的来源替换可被显式表达,避免把旧文件贡献和新文件贡献直接相加。
+source generation 让同一天的不同原始来源可被区分. 同源结果按替换处理, 明确独立的 generation 可以累加, 用户完整重建则通过同步层的 replacement 标记声明旧 generation 全部失效
+
+### `pending` 和 `dirty` 的区别
+
+`maintenance.json` 对每个日期维护两类待办
+
+| 状态 | 何时使用 | 下一步 |
+| --- | --- | --- |
+| `pending` | 已确认是同一来源上的正常追加 | 从旧 offset 增量聚合 |
+| `dirty` | 来源变化, schema 变化, 缓存缺失或上次处理失败 | 从文件起点完整重建 |
+
+`dirty` 优先于 `pending`. 同一天同时出现在两个集合时只生成重建任务, 避免先追加到旧聚合再完整覆盖
+
+这种显式状态比通过 `offset == 0` 猜测任务类型更安全. 全新空文件, 被截断文件和主动重建都可能具有 offset 0, 但它们的 source generation 和同步语义不同
+
+### 如何判断文件还是同一来源
+
+维护层综合 4 类证据
+
+- inode 标识是否变化
+- 当前 size 是否小于已处理 offset
+- 当前 size 是否与维护记录的上次 size 一致
+- offset 前 4 KB 的 boundary hash 是否仍匹配
+
+inode 与 size 能发现替换和截断, boundary hash 能发现保持相同长度的原地改写
+
+### boundary hash 为什么还配合 mtime
+
+每轮都给 210 天内所有文件重算 hash 会长时间持有 `stats.lock`, 直接增加 Hook recorder 的等待概率
+
+维护状态记录上次验证 boundary 时的 nanosecond mtime. inode, size 和 mtime 都没变化时直接跳过 hash. 文件变化后才重算 offset 前 4 KB
+
+正常 append 只修改 offset 之后的字节, 所以 boundary 仍匹配, maintenance 可以继续增量处理. boundary 改变则创建新 generation 并标脏
+
+### build 和 commit 为什么分开
+
+聚合器不能在读取整天文件时一直持有 `stats.lock`, 否则 Hook 子进程可能连续超时
+
+实际流程是
+
+```text
+锁内 prepare
+ -> 固定 sourceGeneration, inode, startOffset 和读取上界
+解锁后 build
+ -> 分块读取并生成候选 aggregate
+锁内 validate
+ -> generation 仍相同
+ -> inode 仍匹配
+ -> 候选上界仍存在
+ -> boundary hash 仍匹配
+提交 daily.jsonl
+锁内再次 validate 并推进 maintenance offset
+```
+
+读取期间允许 recorder 继续 append. 只要候选上界之前的字节没变, 本次结果仍然有效, 新增尾部会保留为下一轮 pending
+
+如果来源在 build 期间被替换, 候选结果不会提交, maintenance 会开始新 generation 并等待重建
## 聚合规则
-日级结果包括:
+日级结果包括
- Hook 事件总数和各事件计数
- session 数和 turn 数
@@ -157,24 +386,48 @@ source generation 让同一天的来源替换可被显式表达,避免把旧
- project 分布
- model 分布
-成对事件可能只有一侧成功落盘。因此计数使用能够避免重复且允许缺失的规则:
+成对事件可能只有一侧成功落盘. 因此计数使用能够避免重复且允许缺失的规则
- tool call 使用 `max(PreToolUse, PostToolUse)`
- compaction 使用 `max(PreCompact, PostCompact)`
- subagent 使用 `max(SubagentStart, SubagentStop)`
-字段缺失与数值 `0` 的含义不同:
+字段缺失与数值 `0` 的含义不同
- 缺失表示该日期的历史来源无法提供该指标
- `0` 表示来源可用且明确没有发生
-解码和 UI 展示必须保留这个区别。
+解码和 UI 展示必须保留这个区别
+
+### 为什么成对事件使用 `max`
+
+`PreToolUse` 和 `PostToolUse` 描述同一次工具调用的两侧. recorder 允许失败后, 任意一侧都可能缺失
+
+- 相加会把完整的一次调用统计为 2 次
+- 只看 pre 会漏掉 pre 写入失败而 post 成功的调用
+- 只看 post 会漏掉工具开始后进程中断的调用
+- `max(pre, post)` 在没有稳定 call ID 时给出最不容易重复的估计
+
+compaction 和 subagent 成对事件使用相同规则
+
+如果未来 Hook 协议提供稳定 operation ID, 去重算法可以升级为集合去重, 但这属于聚合语义变化, 必须递增 schema 并完整重建
+
+### 可用性如何穿过旧数据
+
+旧版本聚合可能没有某类 Hook count. 重建时不能因为当前代码认识该事件, 就假定旧来源也采集过
+
+`WorkflowHookCountAvailability` 保存每类计数是否有来源. 重建会继承现有日期对旧字段的可用性, 新鲜来源则可以声明当前字段全部可用
+
+这使 UI 能区分
+
+- 明确发生 0 次
+- 当前日期的历史采集没有这个指标
## Schema 演进与重建
-当前聚合 schema 为 `5`,由 `WorkflowMaintenanceState.currentAggregationSchema` 管理。
+当前聚合 schema 为 `5`, 由 `WorkflowMaintenanceState.currentAggregationSchema` 管理
-以下变化必须递增 schema:
+以下变化必须递增 schema
- 原始事件到聚合结果的算法变化
- 输出字段增删
@@ -182,15 +435,92 @@ source generation 让同一天的来源替换可被显式表达,避免把旧
- 去重规则变化
- 来源代际合并语义变化
-升级后统一从 210 天保留期内的原始 JSONL 完整重建,不做字段级历史迁移。这种策略让聚合缓存始终能够由同一套当前算法生成。
+升级后统一从 210 天保留期内的原始 JSONL 完整重建, 不做字段级历史迁移. 这种策略让聚合缓存始终能够由同一套当前算法生成
+
+用户手动重建时也走同一条完整重算路径, 并向同步层标记需要替换的日期
+
+### aggregation schema 与 source generation 不同
+
+| 标识 | 描述 | 何时变化 |
+| --- | --- | --- |
+| aggregation schema | 当前代码如何从原始事件计算聚合 | 算法, 字段或语义变化 |
+| source generation | 某一天的原始文件属于哪一代来源 | 替换, 截断, 主动重建或边界改写 |
+
+schema 变化通常把保留期内所有事件日期标脏. source generation 变化只影响具体日期
+
+两者都不能用 App 版本号替代. 一个 App 版本可能不改变聚合, 开发构建也可能在不变更版本号时多次迭代 schema
+
+### 为什么不做字段级迁移
+
+`daily.jsonl` 本来就是派生缓存, 原始 JSONL 又在保留期内. 为每个旧字段编写迁移会同时维护旧算法和新算法, 更容易产生混合语义
+
+完整重建的一次性成本可控, 换来以下保证
+
+- 同一 schema 下所有日期由同一套代码生成
+- 删除或改变字段语义时没有残留值
+- 损坏的聚合行也能一起修复
+- CloudKit replacement 可以统一跟随 source generation
-用户手动重建时也走同一条完整重算路径,并向同步层标记需要替换的日期。
+只有原始来源本身缺少字段时, 才通过 missing 保留历史能力差异
+
+### 用户手动重建的提交语义
+
+批量重建按日期独立处理. 单日失败不会阻断已经成功的日期, 失败日期会标脏交给常规维护继续尝试
+
+成功和失败日期都会先登记 CloudKit replacement. 原因是失败日期已经进入新 generation, 后续自动重建成功时会使用新 record identity. 如果没有提前标记, 旧 generation 可能留在云端与新值叠加
+
+只有所有日期都失败时, 操作整体返回失败. 部分成功会返回详细 summary, 包括成功日期, 损坏行和 replacement pending 状态
## 维护调度
-[`WorkflowService.swift`](../../CodexBar/Services/Workflow/WorkflowService.swift) 是 actor,串行执行读取,聚合,清理和重建。
+[`WorkflowService.swift`](../../CodexBar/Services/Workflow/WorkflowService.swift) 是 actor, 串行执行读取, 聚合, 清理和重建
+
+维护任务与额度刷新周期协调, 但两条数据链路没有数据依赖. Workflow ViewModel 对 UI 的最短刷新间隔为 5 秒, 避免频繁文件变更造成重复渲染
+
+### 为什么空转维护不写普通日志
+
+维护默认跟随 60 秒刷新. 空闲机器一天会执行上千次没有变化的检查
+
+`WorkflowService` 累计连续 idle 轮数, 只有真正写入, 跳过, 失败或清理时才输出一条摘要, 并附带之前空转次数. 这样日志既能证明维护一直在运行, 又不会淹没真正故障
+
+### scheduler 如何合并请求
+
+`WorkflowSyncScheduler` 串行处理 3 类请求
+
+1. 用户重建, 优先级最高
+2. 带同步的维护
+3. 仅本地维护
+
+同步完成后有 8 秒冷却. 冷却期间的多个请求合并成一次, 并保留最先到达的 trigger 作为真正起因
+
+UI 打开只读取当前本地快照, 不自动越过 scheduler 发起无条件 CloudKit 请求
+
+## 新增 Hook 事件或指标的步骤
+
+1. 在 `CodexHookEvent` 登记协议名, 配置名和 handler timeout
+2. 确认 recorder 只持久化计算所需的最小字段
+3. 更新 Hook 安装完整性校验
+4. 在 accumulator 中定义计数和去重语义
+5. 更新 aggregate 的 Codable 与 JSONL 编码, 保留旧字段 missing 语义
+6. 递增 `WorkflowMaintenanceState.currentAggregationSchema`
+7. 更新 CloudKit record schema, 上传和下载映射
+8. 确认旧 App 与新 record 共存策略后再修改兼容格式
+9. 补充 UI 展示和隐私边界
+10. 手动验证正常 append, 单侧事件缺失, 文件替换和完整重建
+
+## 建议验证的故障场景
-维护任务与额度刷新周期协调,但两条数据链路没有数据依赖。Workflow ViewModel 对 UI 的最短刷新间隔为 5 秒,避免频繁文件变更造成重复渲染。
+- 多个 Codex session 并发写入时每行完整且无覆盖
+- 主 App 持锁时 Hook recorder 能在预算内成功或安全放弃
+- stdin 非 JSON 或缺少 event name 时子进程仍立即成功退出
+- 文件尾半行不会推进 offset, 补全后下一轮能读取
+- 单条损坏 JSONL 只增加 corrupt count
+- inode 变化, 文件缩小和 boundary 改写都触发新 generation
+- build 期间继续 append 时只提交固定上界, 尾部保留 pending
+- schema 变化后保留期内日期全部用当前算法重建
+- 旧日期缺失字段仍显示 unavailable, 不变成 `0`
+- 禁用 CodexBar Hook 不删除用户 handler 和信任项
+- 快速开关 Hook 时旧 RPC 结果不能覆盖最后一次操作
## 故障边界
@@ -198,7 +528,7 @@ source generation 让同一天的来源替换可被显式表达,避免把旧
- 文件来源改变后不能继续使用旧 offset
- 重建失败时保留最后一份可用聚合
- 维护中断不能把部分结果当作完整日期提交
-- Hook 不可用时 UI 应表达来源不可用,而不是清空为 `0`
+- Hook 不可用时 UI 应表达来源不可用, 而不是清空为 `0`
- 配置写入失败不能破坏原有 handler
## 关键源码
diff --git a/Docs/DeveloperGuide/notifications.md b/Docs/DeveloperGuide/notifications.md
index 6ed7816..49feccb 100644
--- a/Docs/DeveloperGuide/notifications.md
+++ b/Docs/DeveloperGuide/notifications.md
@@ -2,60 +2,149 @@
## 职责
-[`CodexNotificationService.swift`](../../CodexBar/Services/Notifications/CodexNotificationService.swift) 是通知副作用的统一入口。
+[`CodexNotificationService.swift`](../../CodexBar/Services/Notifications/CodexNotificationService.swift) 是通知副作用的统一入口
-它观察两类状态:
+它观察两类状态
-- app-server 账户,额度和 Reset Credits 快照
+- app-server 账户, 额度和 Reset Credits 快照
- `CodexActivityMonitor` 任务转场和防睡眠恢复事件
-View 和其他服务不直接创建系统通知。它们发布状态变化,通知服务负责资格判断,去重,声音和点击行为。
+View 和其他服务不直接创建系统通知. 它们发布状态变化, 通知服务负责资格判断, 去重, 声音和点击行为
-## 通知开关
+## 设计原则
+
+通知不是状态本身, 而是状态变化触发的一次外部副作用. 一条可靠通知至少要同时满足 4 个条件
+
+```text
+事件真实发生
+ + 用户允许这一分类
+ + 事件仍然相关
+ + 本生命周期或持久化周期尚未发送
+```
+
+把这些条件集中到一个服务有两个目的
+
+- 上游只发布事实和转场, 不需要知道系统授权, 声音或去重存储
+- 所有提交都经过同一套 relevance 检查, retry 和隐私日志规则
+
+如果 View 直接发通知, SwiftUI 重建, 面板重复打开或快照重新发布都可能重复触发. 因此 View 只能修改设置或展示状态, 不能拥有通知副作用
+
+## 快照与转场不能混用
+
+不同通知需要不同类型的证据
-通知总开关默认关闭。各分类子开关默认开启,触觉反馈默认关闭。
+| 通知 | 输入类型 | 原因 |
+| --- | --- | --- |
+| 低额度 | 连续可信快照 | 需要比较阈值上下两帧 |
+| 额度重置 | 连续可信快照 | 需要先观察消费再观察归零 |
+| Reset Credits 到期 | 当前快照加时间调度 | 到期提醒由未来 deadline 触发 |
+| 任务完成 | monitor 转场 | 历史 terminal 快照不能补发 |
+| 等待批准 | monitor 转场加当前快照 | 先通知新等待, 再撤回过时等待 |
+| 异常会话保护 | 已提交保护结果 | 必须描述已经隐藏的任务 |
+| 防睡眠停止 | 已确认系统恢复结果 | 不能在恢复请求前预告成功 |
-总开关关闭时不会申请系统通知权限,也不会发送任何分类通知。子开关用于在总开关开启后选择具体类型:
+从当前快照推导任务完成看起来更简单, 但 App 每次启动都会把历史完成任务当作新事件. 相反, 对低额度只看单次转场又无法识别 App 在阈值穿越后才启动的场景
-| 分类 | 数据来源 |
+## 设置和系统授权是两层门槛
+
+`NotificationSettings` 分开保存 App 内意图与 macOS 授权
+
+| 状态 | 含义 |
| --- | --- |
-| 额度重置 | app-server 额度窗口 |
-| 低额度 | app-server 剩余额度 |
-| Reset Credits 到期 | Reset Credits endpoint |
-| 任务完成 | 实时任务 terminal 转场 |
-| 等待批准 | 实时任务 waiting 转场 |
-| 异常会话保护 | Activity Protection |
-| 防睡眠停止 | KeepAlive 恢复结果 |
+| `isEnabled` | 用户在 CodexBar 内打开总开关 |
+| `authorizationStatus` | 系统是否允许通知 |
+| `canDeliver` | 两者同时允许后的实际资格 |
+
+总开关默认关闭, 因此 App 首次运行不会无缘由弹出系统权限请求. 用户主动开启后才调用 authorization API
+
+App 激活时会重新读取系统状态, 因为用户可能在 System Settings 中改过权限. 如果 App 开关已开但系统仍为 `notDetermined`, 会补发一次请求, 覆盖用户在首次弹窗完成前退出的情况
+
+触觉反馈不依赖 `UNUserNotificationCenter` 授权, 但仍服从 App 内总开关. 这是能力边界的区别, 不是绕过用户意图
+
+## 通知开关
+
+通知总开关默认关闭. 7 个可配置分类的子开关默认开启, 触觉反馈默认关闭
+
+总开关关闭时不会申请系统通知权限, 也不会发送任何分类通知. 子开关用于在总开关开启后选择具体类型
+
+| 分类 | 数据来源 | 控制条件 |
+| --- | --- | --- |
+| 额度重置 | app-server 额度窗口 | 独立子开关 |
+| 低额度 | app-server 剩余额度 | 独立子开关和阈值 |
+| Reset Credits 到期 | Reset Credits endpoint | 独立子开关 |
+| 任务完成 | 实时任务 terminal 转场 | 独立子开关和最短时长 |
+| 等待批准 | 实时任务 waiting 转场 | 独立子开关 |
+| 异常会话保护 | Activity Protection | 防睡眠主开关和通知总开关 |
+| 低电量保护停止 | KeepAlive 恢复结果 | 独立子开关, 仅在保护可用时启用 |
+| 防睡眠达到上限 | KeepAlive 恢复结果 | 独立子开关, 仅在有限时长时启用 |
+
+异常会话保护没有独立通知子开关. 它本身跟随防睡眠主开关, 保护动作发生后再服从通知总开关. 低电量和时长上限的通知偏好会保留, 但对应保护条件不可用时 UI 显示为关闭并置灰, 不修改持久化偏好
## 额度重置
-额度重置通知需要先观察到窗口被消费,再观察到新窗口恢复为未消费状态。
+额度重置通知需要先观察到窗口被消费, 再观察到新窗口恢复为未消费状态
-这避免 App 第一次启动时仅因为当前额度是 100% 就发送重置通知。
+这避免 App 第一次启动时仅因为当前额度是 100% 就发送重置通知
-判断状态按账户和额度窗口隔离。账户变化时不把前一账户的消费状态延续到新账户。
+判断状态按账户和额度窗口隔离. 账户变化时不把前一账户的消费状态延续到新账户
+
+每个额度窗口还带一个会话内 lifecycle token. 窗口从可信快照消失后再出现会得到新 token. 如果旧窗口的通知提交失败回调迟到, 只有 token 仍相同时才把 `hasObservedConsumption` 恢复为 true
+
+这避免一个竞态: 旧窗口通知正在提交时 app-server 切换账户或窗口, 随后失败回调把新窗口错误标成"已经消费过"
+
+重置状态不持久化. App 启动时必须重新观察到消费后才通知重置, 这是主动接受漏掉离线期间重置, 以换取绝不在启动时对 0% 用量误报
## 低额度
-低额度阈值可选 5%, 10% 或 25%,默认 10%。
+低额度阈值可选 5%, 10% 或 25%, 默认 10%
+
+通知只在剩余额度从阈值上方跨到阈值或下方时发送. 持续停留在低额度区域不会每次刷新都重复通知
+
+首次可信快照已经低于阈值时也视为一次向下穿越, 用于覆盖 App 在穿越后才启动的情况
+
+持久化去重 key 保留 app-server 返回的秒级重置时间. 相同账户和额度窗口的重置时间与已记录值相差不超过 60 秒时视为同一周期, 只有差值超过 60 秒才视为新的重置周期
+
+额度恢复到阈值上方后会重新启用穿越判定, 但同一重置周期仍只通知一次. 进入新的重置周期后, 下一次向下跨越可以再次通知
+
+### 为什么使用剩余比例的向下穿越
+
+"当前低于 10%"是一个持续状态, "刚刚低于 10%"才是通知事件. 服务为每个 `account + limit + window` 保存上一帧剩余比例
+
+- 上一帧高于阈值且当前不高于阈值时发送
+- 会话内第一帧已经不高于阈值时发送一次
+- 一直停留在低区间时不发送
+- 阈值设置变化时清除当前观察并立即按新阈值重判
+
+设置订阅使用回调给出的新值. Combine 的 `@Published` 在 `willSet` 阶段发送, 此时重新读取 settings 属性仍会得到旧值. 这项实现细节是为了保证用户把阈值从 5% 改到 25% 时立即按 25% 判断
-通知只在剩余额度从阈值上方跨到阈值或下方时发送。持续停留在低额度区域不会每次刷新都重复通知。
+stale app-server 快照不会推进上一帧, 也不会触发低额度或重置. 旧缓存只能用于展示连续性, 不能成为一次新副作用的证据
-首次可信快照已经低于阈值时也视为一次向下穿越,用于覆盖 App 在穿越后才启动的情况。
+### 重置时间为何允许 60 秒漂移
-持久化去重 key 保留 app-server 返回的秒级重置时间。相同账户和额度窗口的重置时间与已记录值相差不超过 60 秒时视为同一周期,只有差值超过 60 秒才视为新的重置周期。
+app-server 连接重建后, 同一窗口的 `resetsAt` 可能出现秒级修正. 如果 dedup key 使用绝对相等, 同一周期会被当成新周期再次通知
-额度恢复到阈值上方后会重新启用穿越判定,但同一重置周期仍只通知一次。进入新的重置周期后,下一次向下跨越可以再次通知。
+服务在相同账户, limit 和 window 范围内寻找 60 秒容差内的已发送或正在提交 key, 并复用原 key. 容差只用于身份归一化, UI 仍展示服务返回的实际时间
## Reset Credits 到期
-当 Reset Credits 数量大于 `0` 且能够读取到期日时,通知服务在到期前 7 天到 1 天按天提醒。
+当 Reset Credits 数量大于 `0` 且能够读取到期日时, 通知服务在到期前 7 天到 1 天按天提醒
-去重 key 包含账户,到期日和剩余天数。同一天多次刷新不会重复发送。
+去重 key 包含账户, 到期日和剩余天数. 同一天多次刷新不会重复发送
+
+提醒不是建立 7 个长期系统 pending request. 服务只调度最近一个未来检查点, 到点后根据当前快照重新计算并安排下一次
+
+这样做可以处理
+
+- Reset Credits 数量或到期时间被 app-server 更新
+- 通知设置中途关闭
+- Mac 睡过 deadline 后通过 wake observer 补检
+- 多个相同到期秒的次数合并成一条通知
+
+日期判断基于距到期的剩余秒数, 7 天到 1 天分别有独立 dedup key. 调度器只负责唤醒检查, 最终资格仍由当前快照决定
## 任务完成
-任务通知只响应 monitor 发布的新 terminal 转场,不扫描历史列表推导:
+任务通知只响应 monitor 发布的新 terminal 转场, 不扫描历史列表推导
- bootstrap 建立的历史任务不发送通知
- terminal ID 在活动监控层保留 24 小时去重
@@ -64,36 +153,55 @@ View 和其他服务不直接创建系统通知。它们发布状态变化,通
匿名任务不会发布给任务通知消费者. 通知服务在 transition 入口再次过滤 `isAnonymous`, 因此匿名任务不发送完成或等待批准通知, 也不触发任务触觉反馈
-任务完成最短持续时间可选 30, 60, 120 或 300 秒,默认 60 秒。持续时间较短的完成任务不会通知,但仍可以在 UI 中短暂展示。
+任务完成最短持续时间可选 30, 60, 120 或 300 秒, 默认 60 秒. 持续时间较短的完成任务不会通知, 但仍可以在 UI 中短暂展示
+
+任务通知入口再次过滤匿名任务, 即使 monitor 已保证不发布匿名转场. 这是副作用边界的纵深保护: 上游未来重构或新增 transition 类型时, 缺少 session ID 的任务仍不会意外产生系统通知或触觉
+
+触觉在每个 task transition 到达时启动, 新 transition 会取消上一串 10 次脉冲并重新开始. 每次脉冲前重新检查设置, 用户关闭开关后不会继续完成旧序列
## 等待批准
-只有 `PermissionRequest` 的 reviewer 确认是用户时才发送等待批准通知:
+只有 `PermissionRequest` 的 reviewer 确认是用户时才发送等待批准通知
- 自动审批不通知
- 同一等待项只通知一次
- 任务离开等待状态后从相关集合移除
- bootstrap 中已存在的等待状态不补发历史通知
-等待状态是否维持防睡眠是独立设置,不影响是否可以发送等待批准通知。
+等待状态是否维持防睡眠是独立设置, 不影响是否可以发送等待批准通知
+
+等待通知使用稳定 task ID 作为系统通知 identifier. 服务同时观察活动快照
+
+- 提交前任务已经离开 waiting 时跳过
+- `UNUserNotificationCenter.add` 成功后状态又变化时立即撤回
+- 后续快照不再包含任务时同时移除 delivered 和 pending notification
+- 提交失败时从内存相关集合移除, 允许未来真实的新等待再次尝试
+
+前后两次 relevance 检查覆盖了异步提交窗口. 只在提交前检查仍可能让一个已经获批的任务在通知中心留下过时提醒
## 异常会话保护
非匿名任务静默达到阈值时, Activity Protection 先保存保护记录并隐藏任务, 然后请求通知. 匿名任务不进入保护候选, 也不会产生保护通知
-通知服务在提交前再次检查任务是否仍然被保护。如果 3 秒宽限内出现新进展,过时通知会被取消。
+通知服务在提交前再次检查任务是否仍然被保护. 如果 3 秒宽限内出现新进展, 过时通知会被取消
+
+保护通知使用固定默认声音, 不复用任务完成分类声音. 通知发送失败不撤销已经完成的保护动作
-保护通知使用固定默认声音,不复用任务完成分类声音。通知发送失败不撤销已经完成的保护动作。
+异常会话保护使用 `taskID + attemptID` 作为 identifier, relevance 还比较 progress generation 和静默时长. 任务在 3 秒通知宽限内出现进展时, monitor 让保护尝试失效并请求撤回
+
+这类通知的 `retryCount` 明确为 0. 保护结果对时间高度敏感, 立即提交失败后再重试可能已经不相关. 一般通知可以重试一次, 保护通知宁可漏发也不迟到误报
## 防睡眠停止
-低电量或最长时长导致防睡眠停止时,`KeepAliveController` 先释放 App assertion 和 CodexBarHelper 租约。
+低电量或最长时长导致防睡眠停止时, `KeepAliveController` 先撤销 CodexBarHelper 租约并等待 `SleepDisabled=0` 的回读确认
+
+确认后才提交通知. App idle assertion 会保留到通知提交结束, 避免合盖机器在通知交给系统前立即睡下. 随后 controller 释放 assertion 并按需补发合盖睡眠
-只有系统状态恢复得到确认后才发布通知事件。这保证通知文字描述的是已经完成的结果。
+这保证通知文字描述的是已经完成的系统级恢复, 同时让异步提交有机会收口
## 声音
-[`NotificationSoundOption.swift`](../../CodexBar/Services/Notifications/NotificationSoundOption.swift) 汇总 3 类选择:
+[`NotificationSoundOption.swift`](../../CodexBar/Services/Notifications/NotificationSoundOption.swift) 汇总 3 类选择
- 无声音
- macOS 可用系统声音
@@ -101,39 +209,98 @@ View 和其他服务不直接创建系统通知。它们发布状态变化,通
内置声音位于 [`NotificationSounds`](../../CodexBar/Resources/NotificationSounds)
-已保存的声音名称在新系统或新版 App 中不存在时,回退到默认声音,不阻断通知。
+已保存的声音名称在新系统或新版 App 中不存在时, 回退到默认声音, 不阻断通知
+
+不同通知分类可以保存各自的声音设置
+
+声音选项保存稳定 ID, 而不是绝对文件路径
+
+- 内置声音通过 bundle resource 解析
+- 系统声音首次访问时扫描用户, Local 和 System 声音目录
+- `/Network/Library/Sounds` 刻意不扫描, 自动挂载点探测可能阻塞 UI
+- 同名声音按系统查找顺序选择靠前目录
+- 内置 ID 预先保留, 防止本机同名文件在重启后改变已保存选项的含义
+- 已保存 ID 无法解析时回退 system default
-不同通知分类可以保存各自的声音设置。
+system default 和静音不可试听. 用系统 alert sound 冒充通知中心默认音会给用户错误预期, 因此预览只支持有明确文件的系统音和内置音
## 触觉反馈
-触觉反馈默认关闭。开启后使用 10 次脉冲,每次间隔约 100 ms。
+触觉反馈默认关闭. 开启后使用 10 次脉冲, 每次间隔约 100 ms
-触觉是系统通知之外的可选本地反馈。不应在没有对应有效通知事件时单独触发。
+触觉是系统通知之外的独立本地反馈. 它响应非匿名任务的完成或等待 transition, 服从通知总开关和触觉开关, 但不依赖系统通知授权, 分类通知开关或完成时长阈值
+
+这种分离让用户可以关闭 banner 仍保留统一的任务触觉. 上游 transition 仍必须真实有效, bootstrap 历史和匿名任务不会触发
## 提交与去重
-通知通过 `UNUserNotificationCenter` 提交:
+通知通过 `UNUserNotificationCenter` 提交
- 单次提交失败最多重试 1 次
- 已发送 dedup key 保存到 UserDefaults
- 最多保留 300 个 key
-- key 必须包含足够的账户或任务范围,避免不同对象相互压制
+- key 必须包含足够的账户或任务范围, 避免不同对象相互压制
- 过期或不再相关的 waiting key 会被移除
-持久化去重避免 App 重启后立即重复发送同一事件,但不能替代上游任务 terminal 去重。
+持久化去重避免 App 重启后立即重复发送同一事件, 但不能替代上游任务 terminal 去重
+
+### 两层去重解决不同问题
+
+`submittingDedupKeys` 和 `sentDedupKeys` 不能合并
+
+| 集合 | 生命周期 | 防止的问题 |
+| --- | --- | --- |
+| `submittingDedupKeys` | 当前异步提交期间 | 两个同步调用在第一个 `await` 前同时通过检查 |
+| `sentDedupKeys` | UserDefaults, 最多 300 条 | App 重启后重复发送同一业务周期 |
+
+dedup 检查和 `submitting` 插入在创建 Task 前同步完成, 因此正确性不依赖 Swift task 调度顺序
+
+只有 `UNUserNotificationCenter.add` 成功且事件在提交后仍相关时才写入 sent key. 如果提前记录, 一次系统提交失败会永久吃掉这条提醒
+
+300 条上限防止 UserDefaults 变成无界事件日志. 这里接受很久以前的事件在 key 淘汰后理论上可能重现, 因为上游周期身份和实时 transition 去重仍是第一道边界
+
+### 发送入口的统一语义
+
+所有通知内容最终经过同一个 `send` 和 `deliver`
+
+```text
+同步检查 dedup
+ -> 构造不可延迟的 notification request
+ -> 提交前检查 relevance
+ -> 调用系统中心
+ -> 提交后再次检查 relevance
+ -> 成功后持久化 dedup
+ -> 失败时最多重试一次并执行分类清理
+```
+
+日志只记录 `kind` 和失败原因, 不记录 title 或 body. 通知正文可能包含项目名和任务信息, 即使日志位于本机也不应复制这些内容
## 前台展示与点击
-App 是 `LSUIElement`,通知中心 delegate 明确允许 App 在前台时继续展示 banner 和声音。
+App 是 `LSUIElement`, 通知中心 delegate 明确允许 App 在前台时继续展示 banner 和声音
+
+用户点击通知后打开主面板. 打开动作通过状态栏控制器执行, 复用现有 popover 或 fallback panel 逻辑
+
+前台展示由 notification center delegate 显式返回 banner, list 和 sound. `LSUIElement` App 经常保持前台或处于特殊 activation 状态, 依赖系统默认前台策略会让用户感觉通知随机消失
+
+点击处理不直接创建新窗口, 而是调用 `openMenuSurface`. 这保证锚点有效时复用 popover, 锚点无效时使用 fallback panel, 并继续遵守同一套焦点和 dismiss 规则
+
+## 新增通知类型的实现清单
-用户点击通知后打开主面板。打开动作通过状态栏控制器执行,复用现有 popover 或 fallback panel 逻辑。
+1. 明确输入是快照, 转场还是已确认副作用结果
+2. 定义账户, 窗口, task 或 attempt 作用域的身份
+3. 决定是否需要会话去重, 持久化去重和 relevance 检查
+4. 明确 bootstrap, stale 数据和匿名任务是否允许触发
+5. 选择声音和失败重试语义
+6. 确认正文中的敏感字段不会进入日志
+7. 为设置默认值和旧 UserDefaults 缺失值定义行为
+8. 验证前台展示, 点击激活和事件失效后的撤回
## Codex TUI 通知
-设置页中的 Codex TUI 通知是 Codex 自身配置,通过 app-server 的 `config/batchWrite` 读写。
+设置页中的 Codex TUI 通知是 Codex 自身配置, 通过 app-server 的 `config/batchWrite` 读写
-它与 CodexBar 系统通知完全独立:
+它与 CodexBar 系统通知完全独立
- 关闭 CodexBar 通知不代表关闭 TUI 通知
- TUI 设置失败不影响 App 通知状态
diff --git a/Docs/DeveloperGuide/sleep-prevention.md b/Docs/DeveloperGuide/sleep-prevention.md
index 9d0246c..bbbe6b0 100644
--- a/Docs/DeveloperGuide/sleep-prevention.md
+++ b/Docs/DeveloperGuide/sleep-prevention.md
@@ -2,13 +2,13 @@
## 设计目标
-防睡眠功能需要同时满足 3 个目标:
+防睡眠功能需要同时满足 3 个目标
- 有符合条件的 Codex 任务时阻止 Mac 空闲睡眠
-- App 退出,崩溃或失联后可靠恢复系统设置
+- App 退出, 崩溃或失联后可靠恢复系统设置
- 不覆盖用户或其他应用已经设置的系统级防睡眠状态
-普通 App 进程负责策略和用户界面,CodexBarHelper 只执行受限的系统睡眠操作:
+普通 App 进程负责策略和用户界面, CodexBarHelper 只执行受限的系统睡眠操作
```text
CodexActivityMonitor
@@ -19,9 +19,99 @@ CodexActivityMonitor
-> /usr/bin/pmset
```
+## 为什么这不是一个 assertion 开关
+
+防睡眠表面上像一个布尔设置, 实际上同时跨越用户意图, 实时任务, 电源状态, App 生命周期和 root 系统状态. 任何一层都可能先于其他层变化, 因此实现不能把 `isEnabled` 直接等同于系统已经禁止睡眠
+
+系统把状态拆成 4 层
+
+| 层级 | 代表字段 | 回答的问题 |
+| --- | --- | --- |
+| 用户意图 | `isEnabled` | 用户是否希望使用功能 |
+| 决策条件 | `sleepBlockReason` | 当前是否满足生效条件 |
+| 请求状态 | `appliedSleepPreventionRequested` 和 `requestInFlight` | App 最近向 helper 请求了什么 |
+| 已确认效果 | `isPreventingSleep` 和 `sleepPreventionSource` | App 是否收到系统状态已经符合预期的证据 |
+
+这种区分解决了两个容易被 UI 掩盖的问题
+
+- helper 暂时不可用时保留用户开关, 修复依赖后可以自动恢复, 不需要用户重新开启
+- XPC 请求发出但尚未确认时不提前显示成功, 避免界面和系统实际状态相反
+
+`sleepBlockReason` 是所有条件的唯一决策出口. UI 派生状态, 条件日志和实际切换都读取同一个结果, 新增条件时必须在一个有穷的 `switch` 中说明设置入口是否仍应可用. 这是一处刻意的防遗漏设计
+
+## App assertion 与系统设置为什么并存
+
+两套机制的作用域不同
+
+| 机制 | 生命周期 | 作用 | 失效方式 |
+| --- | --- | --- | --- |
+| IOKit assertion | App 进程 | 阻止空闲系统睡眠, 可选阻止显示器睡眠 | App 退出后由系统自动回收 |
+| `pmset disablesleep` | 系统全局 | 覆盖 assertion 无法保证的系统睡眠路径 | 必须显式恢复, 因此需要 ownership 和 watchdog |
+
+只使用 assertion 的恢复成本低, 但能力不完整. 只使用 `pmset` 的能力更强, 但 App 崩溃后可能留下全局状态. CodexBar 同时使用两者, 并把高风险的全局状态交给最小权限 helper 管理
+
+App 侧 assertion 会在 XPC 获取流程开始前建立. 这样 helper 切换期间不会出现短暂的空闲睡眠窗口. 如果 helper 请求失败, 统一清理路径会释放 assertion, 避免形成只有 App 自己知道的半成功状态
+
+## 获取与释放是确认式事务
+
+获取流程不是先改 UI 再异步补系统操作, 而是一个带验证的事务
+
+```text
+条件求值为允许
+ -> 建立 App idle assertion
+ -> 标记 helper 可能已经收到租约
+ -> 发送带 generation 的 XPC 请求
+ -> helper 读取当前 SleepDisabled
+ -> 必要时写入并回读验证
+ -> App 校验来源和实测值
+ -> 发布已生效状态并开始累计时长
+```
+
+释放流程按相反方向收口
+
+```text
+条件求值为阻断
+ -> 请求 helper 撤销租约
+ -> helper 仅在 owned 且无其他租约时恢复系统值
+ -> App 收到实测结果
+ -> 发布未防睡眠状态并释放 display assertion
+ -> 停止时长累计
+ -> 提交低电量或时长上限通知
+ -> 释放 App idle assertion
+ -> 必要时补发合盖睡眠
+```
+
+通知放在 helper 确认 `SleepDisabled=0` 之后, 是为了保证用户看到的"已停止防睡眠"描述的是事实, 而不是尚未完成的意图
+
+App idle assertion 会多保留到通知提交结束. 合盖机器在全局设置恢复后可能立即睡下, 如果先释放最后一条 assertion, 通知请求可能来不及交给系统. 提交完成后立即释放 assertion 并执行合盖边沿补偿, 这段短暂顺序不会重新声明系统所有权
+
+## `mayHaveHelperLease` 为什么不能在超时时清除
+
+XPC 超时只证明 App 没收到回复, 不证明 helper 没执行请求. 请求可能已经把租约写入 helper, 只是回复在连接断开时丢失
+
+因此 `mayHaveHelperLease` 采用保守语义
+
+- 请求获取时立即设为 `true`
+- 超时或连接失效时保持 `true`
+- 只有一次已确认的释放结果才能清为 `false`
+
+这会让退出流程多做一次幂等释放, 但能避免 App 误以为没有租约而直接退出. 对全局系统状态而言, 多释放一次的成本远低于遗留 `SleepDisabled=1`
+
+## generation 解决什么竞态
+
+用户关闭开关, 任务结束和重试可能在前一条 XPC 回复返回前连续发生. 如果只按回复到达顺序更新状态, 旧的"获取成功"可能覆盖新的"释放成功"
+
+App 和 helper 都使用单调递增 generation
+
+- App 只接收当前 `requestGeneration` 的回调
+- helper 忽略比现有租约 generation 更旧的请求
+- 连接作废时 App 推进 generation, 让在途回调自然失效
+
+generation 不是用来给请求排序的日志编号, 而是异步状态提交的资格证明
+
## 生效条件
-[`KeepAliveController.swift`](../../CodexBar/Services/KeepAlive/KeepAliveController.swift) 只有在以下条件全部成立时才建立防睡眠:
+[`KeepAliveController.swift`](../../CodexBar/Services/KeepAlive/KeepAliveController.swift) 只有在以下条件全部成立时才建立防睡眠
- 防睡眠主开关已开启
- Hook 已启用且校验通过
@@ -31,11 +121,11 @@ CodexActivityMonitor
- 未达到单次最长防睡眠时长
- App 不在终止流程
-等待批准任务默认不计入有效任务,用户可以单独开启。异常会话保护抑制的任务也不再维持防睡眠。
+等待批准任务默认不计入有效任务, 用户可以单独开启. 异常会话保护抑制的任务也不再维持防睡眠
-`KeepAliveController` 会先从运行中和等待批准快照中排除 `isAnonymous` 任务。只有非匿名任务能够进入运行任务集合,启动新一轮最长时长计时或维持防睡眠
+`KeepAliveController` 会先从运行中和等待批准快照中排除 `isAnonymous` 任务. 只有非匿名任务能够进入运行任务集合, 启动新一轮最长时长计时或维持防睡眠
-控制器会发布明确的阻塞原因:
+控制器会发布明确的阻塞原因
| 原因 | 含义 |
| --- | --- |
@@ -51,23 +141,23 @@ CodexActivityMonitor
## App 侧 assertion
-[`SystemSleepService.swift`](../../CodexBar/Services/KeepAlive/SystemSleepService.swift) 使用 IOKit 建立 `PreventUserIdleSystemSleep` assertion。
+[`SystemSleepService.swift`](../../CodexBar/Services/KeepAlive/SystemSleepService.swift) 使用 IOKit 建立 `PreventUserIdleSystemSleep` assertion
-如果用户开启保持显示器唤醒,还会建立 `NoDisplaySleep` assertion,并每 30 秒调用一次用户活动声明,避免显示器空闲计时提前生效。
+如果用户开启保持显示器唤醒, 还会建立 `NoDisplaySleep` assertion, 并每 30 秒调用一次用户活动声明, 避免显示器空闲计时提前生效
-App 侧 assertion 只覆盖当前进程生命周期。系统级 `SleepDisabled` 由 CodexBarHelper 管理,用于覆盖 assertion 无法保证的系统睡眠路径。
+App 侧 assertion 只覆盖当前进程生命周期. 系统级 `SleepDisabled` 由 CodexBarHelper 管理, 用于覆盖 assertion 无法保证的系统睡眠路径
## CodexBarHelper 安装与通信
-CodexBarHelper 通过 `SMAppService` 注册为 LaunchDaemon。App 和 CodexBarHelper 使用 [`CodexBarHelperXPC.swift`](../../Shared/CodexBarHelperXPC.swift) 定义的 XPC 接口。
+CodexBarHelper 通过 `SMAppService` 注册为 LaunchDaemon. App 和 CodexBarHelper 使用 [`CodexBarHelperXPC.swift`](../../Shared/CodexBarHelperXPC.swift) 定义的 XPC 接口
-接口只提供 3 类能力:
+接口只提供 3 类能力
- 设置或撤销 App 租约
- 查询 CodexBarHelper 运行和拥有状态
- App 更新后重置 CodexBarHelper 状态
-每个 App 进程生成稳定的 `clientSessionID`,XPC 重连期间保持不变。每次租约变更带单调递增 generation,CodexBarHelper 只接受更新的请求,避免迟到消息覆盖新状态:
+每个 App 进程生成稳定的 `clientSessionID`, XPC 重连期间保持不变. 每次租约变更带单调递增 generation, CodexBarHelper 只接受更新的请求, 避免迟到消息覆盖新状态
- 单次 XPC 请求超时为 10 秒
- 连接丢失后 watchdog 宽限为 15 秒
@@ -76,68 +166,91 @@ CodexBarHelper 通过 `SMAppService` 注册为 LaunchDaemon。App 和 CodexBarHe
## CodexBarHelper 权限边界
-[`CodexBarHelper/main.swift`](../../CodexBarHelper/main.swift) 以 root 运行,但能力被刻意限制:
+[`CodexBarHelper/main.swift`](../../CodexBarHelper/main.swift) 以 root 运行, 但能力被刻意限制
- 只执行固定路径 `/usr/bin/pmset`
- 只使用固定参数读取或切换 `disablesleep`
- 不接受任意命令或参数
-- 不访问 Hook,rollout,账户或日志数据
+- 不访问 Hook, rollout, 账户或日志数据
- 不进行网络访问
- 不负责判断 Codex 任务状态
-CodexBarHelper 从自身签名派生客户端 code-signing requirement,并应用到 XPC listener。未通过签名要求的客户端不能建立控制连接。
+CodexBarHelper 从自身签名派生客户端 code-signing requirement, 并应用到 XPC listener. 未通过签名要求的客户端不能建立控制连接
## 系统状态所有权
-CodexBarHelper 先通过以下命令读取当前值:
+CodexBarHelper 先通过以下命令读取当前值
```bash
/usr/bin/pmset -g
```
-需要系统级防睡眠时只会执行固定操作:
+需要系统级防睡眠时只会执行固定操作
```bash
/usr/bin/pmset -a disablesleep 1
```
-释放时执行:
+释放时执行
```bash
/usr/bin/pmset -a disablesleep 0
```
-所有权规则是防止破坏外部状态的关键:
+所有权规则是防止破坏外部状态的关键
-- 如果 CodexBarHelper 观察到初始值已经是 `1`,它把状态标记为 external
+- 如果 CodexBarHelper 观察到初始值已经是 `1`, 它把状态标记为 external
- external 状态不会被 CodexBar 声明为自己拥有
- CodexBar 只在亲自完成 `0 -> 1` 切换后记录 owned
- 只有 owned 状态才允许在租约结束时恢复为 `0`
-因此,用户或其他工具预先开启的 `SleepDisabled=1` 不会在 CodexBar 退出时被关闭。
+因此, 用户或其他工具预先开启的 `SleepDisabled=1` 不会在 CodexBar 退出时被关闭
+
+### ownership 文件如何构成恢复事务
+
+helper 的持久化顺序刻意偏向可恢复
+
+```text
+获取: persist owned -> pmset 1 -> read back 1
+释放: persist restoring -> pmset 0 -> read back 0 -> persist idle
+```
+
+获取时先写 owned. 如果进程在写文件后, `pmset 1` 前崩溃, 下次启动多执行一次幂等 `pmset 0`, 不会留下全局禁止睡眠. 如果先写系统值再持久化, 两步之间崩溃就会失去恢复责任
+
+释放时先写 restoring. 如果在 `pmset 0` 或最终 idle 提交前崩溃, 下次启动仍知道这是一笔未完成恢复. 只有回读确认系统值为 `0` 后才允许持久化 idle
+
+### 外部来源消失后的接管
+
+`external` 不是永久判断. CodexBar 在仍有有效任务时周期性读取 helper 缓存的系统状态
+
+- 外部来源仍存在时继续借用现有 `SleepDisabled=1`, 不写系统设置
+- 外部来源消失而任务仍在时重新申请租约, 由 helper 完成新的 `0 -> 1`
+- helper 已经因为其他有效客户端转为 owned 时更新来源展示, 不重复创建计时周期
+
+这项观察避免一个隐蔽空窗: 用户先用其他工具开启防睡眠, CodexBar 因此判定为 external, 随后其他工具关闭设置. 如果 CodexBar 不重新观察, UI 会继续显示防睡眠, 系统却已经可以睡眠
## CodexBarHelper 状态持久化
-CodexBarHelper 把系统所有权记录保存在:
+CodexBarHelper 把系统所有权记录保存在
```text
/Library/Application Support/CodexBar/helper-state.json
```
-安全和可靠性要求如下:
+安全和可靠性要求如下
- 当前 schema 为 `1`
-- 目录由 root 拥有,权限为 `0755`
+- 目录由 root 拥有, 权限为 `0755`
- 目录不能被 group 或 world 写入
-- 文件由 root 拥有,权限为 `0600`
-- 使用临时文件,full sync 和原子 rename 提交
+- 文件由 root 拥有, 权限为 `0600`
+- 使用临时文件, full sync 和原子 rename 提交
- 启动时无法读取可信 owned 记录会执行恢复到 `disablesleep 0`
-该文件记录 CodexBar 对系统睡眠设置的所有权。
+该文件记录 CodexBar 对系统睡眠设置的所有权
## 租约与故障恢复
-App 持有有效任务时定期续租。CodexBarHelper 不把一次 XPC 请求解释为永久授权:
+App 持有有效任务时保持带身份的 XPC lease. CodexBarHelper 不把一次请求解释为脱离连接的永久授权
```text
租约有效 -> 保持 owned 状态
@@ -146,32 +259,131 @@ App 持有有效任务时定期续租。CodexBarHelper 不把一次 XPC 请求
宽限超时 -> 撤销租约并恢复 owned 状态
```
-异常退出后,CodexBarHelper 依靠连接失效,watchdog 和持久化所有权共同恢复系统设置。
+异常退出后, CodexBarHelper 依靠连接失效, watchdog 和持久化所有权共同恢复系统设置
+
+App 正常退出时先撤销租约和 IOKit assertion. 如果 CodexBarHelper 尚未确认恢复, App 终止流程会等待, 避免在不确定状态下直接离开
+
+### 正常退出为什么可以被取消
+
+`applicationShouldTerminate` 不能在未确认释放时直接返回允许. `prepareForTermination()` 会先停止新重试, 请求释放可能存在的租约, 然后等待 helper 回读结果
+
+- 释放成功时继续终止
+- 释放失败时取消本次终止, 恢复正常条件求值和重试
-App 正常退出时先撤销租约和 IOKit assertion。如果 CodexBarHelper 尚未确认恢复,App 终止流程会等待,避免在不确定状态下直接离开。
+取消退出看似比直接关闭更强硬, 但这是可恢复性的一部分. 正常退出是 App 唯一能主动确认 root 全局状态的机会, 不应主动放弃这次确认. 强制退出仍由 helper 的 15 秒 watchdog 兜底
+
+### helper 自检不是只看进程存活
+
+helper 会分别检查 lease, ownership 记录和实测 `SleepDisabled`
+
+- owned 且仍有租约时, 若系统值被外部改回 `0`, helper 会重新建立 `1`
+- owned 且已无租约时恢复 `0`
+- external 时只观察, 不把外部状态写成自己的 ownership
+- 持久化记录不可信时采取 fail-safe 恢复, 不把损坏记录当成继续持有权限的依据
+
+这里的周期检查不是替代事件驱动 XPC, 而是修复系统设置被其他进程改写, 回调丢失或进程重启造成的事实漂移
## 时长和电池策略
-单次时长只统计实际处于防睡眠的时间:
+单次时长只统计实际处于防睡眠的时间
- 没有任务时暂停或重置周期
- 新一轮任务可以开始新的周期
- 默认上限为 12 小时
- 可选 1, 2, 4, 8, 12, 24 小时或无限制
-低电量停止只在使用电池供电时生效:
+低电量停止只在使用电池供电时生效
- 可选阈值为 5%, 10%, 15%, 20%, 25%
- 默认关闭
-- 恢复使用 5 个百分点滞回,避免电量在阈值附近反复切换
+- 恢复使用 5 个百分点滞回, 避免电量在阈值附近反复切换
+
+防睡眠因低电量或时长上限结束时, 通知必须在睡眠状态已经恢复后发送
+
+### 时长周期如何定义
+
+"单次最长时长"不是从任务出现到任务消失的墙钟时间, 而是系统实际被 CodexBar 挡住睡眠的累计时间
+
+`KeepAliveDurationLimiter` 使用 `SuspendingClock`
+
+- 系统睡眠期间时钟暂停, 醒来后不会把睡眠时间误算为防睡眠时间
+- helper 不可用, 低电量或其他条件阻断期间暂停累计
+- 新运行任务出现时开始新周期
+- 等待任务恢复运行时开始新周期
+- 同一批任务只是在运行和观察之间刷新快照时不重复清零
+
+`hasReached` 是当前周期内的粘滞状态. 达到上限后不能因为一次普通快照刷新立即恢复, 只有明确的新任务周期或设置变化才能重新求值
+
+任务集合使用稳定 task ID 判断"新任务"和"等待后恢复", 而不是只比较数量. 如果一个任务结束同时另一个任务开始, 数量仍为 1, 但新的任务应得到完整时长预算
+
+### 电池读取为何是三态
+
+电池读取使用 `unavailable`, `unreadable` 和 `present` 三态, 不能压成一个可选值
+
+| 状态 | 含义 | 策略 |
+| --- | --- | --- |
+| `unavailable` | 已确认没有内置电池 | 隐藏低电量设置并清除阻断 |
+| `unreadable` | 本轮 IOKit 读取失败 | 保留上一次结论 |
+| `present` | 有可信电量和供电来源 | 正常执行阈值判断 |
+
+读取失败时维持上一次状态, 是为了避免一次 IOKit 枚举缺口让设置行闪烁, 也避免正在生效的低电量保护被瞬时解除. 一台机器只要曾经读到电池, 后续空列表就按 `unreadable` 处理, 因为硬件不会在运行中消失
+
+是否使用电池通过 power source state 判断, 不能通过 `isCharging` 推断. 接通电源但停止充电时 `isCharging` 也是 false, 此时电量并没有被任务持续消耗
+
+### 低电量锁存与滞回
+
+阈值为 `T` 时, 进入条件是电池供电且电量不高于 `T`, 退出条件是电量至少达到 `T + 5`
+
+这 5 个百分点不是展示层修饰, 而是状态机滞回. 没有它时, 电量在阈值附近的测量抖动会反复执行 root 写入, assertion 切换和通知判断
+
+低电量通知还保留单轮锁存
+
+- 只有此前确实由 CodexBar 防止睡眠时才排队通知
+- 只在恢复成功后记录已经通知
+- 接上电源会解除当前阻断, 但只有电量越过恢复门槛才结束这一轮锁存
+- 修改阈值会开启新一轮, 避免旧阈值的通知状态污染新设置
+
+## 显示器常亮是附加效果
+
+保持显示器唤醒只依赖"防睡眠已确认生效"和用户选项, 不独立维持系统睡眠
+
+`NoDisplaySleep` 只能阻止显示器休眠, 不能阻止屏保和闲置锁屏. 因此实现还每 30 秒声明一次用户活动. 声明会复用同一个 assertion ID, 否则 `pmset -g assertions` 中会持续堆积同名记录
+
+显示断言失败只记独立错误, 不覆盖主防睡眠结果. 这是有意区分核心效果和附加效果, 避免设置页把"屏幕没有保持常亮"误报成"系统防睡眠完全失败"
+
+assertion 名称使用 ASCII. 某些系统版本中带中文的名称会在 `pmset -g assertions` 中显示为空, 使诊断信息失去标识
+
+## 合盖恢复的边沿补偿
+
+合盖睡眠是一个边沿事件. 如果合盖时 `SleepDisabled=1`, 系统错过该边沿后不会仅因为稍后恢复为 `0` 就再次自动评估
+
+CodexBar 在确认自己拥有的系统设置已恢复后读取 clamshell 状态. 当盖子仍闭合且该硬件模式应因合盖睡眠时, 主动请求一次系统睡眠
+
+补偿只用于 `.codexBar` 来源
+
+- external 状态不是 CodexBar 改写的, 不能替外部所有者决定何时睡眠
+- `SleepDisabled` 仍为 `1` 时不能请求
+- 无法读取合盖状态时不猜测
+
+这是典型的边沿事件修复, 不能用"最终值已经正确"替代
+
+## 失败与重试策略
+
+防睡眠采用有界重试, 因为每次重试都会重新建立特权连接并可能启动 root 进程
+
+- 10 秒请求超时早于 15 秒 helper watchdog, App 先放弃不可信连接, helper 随后有机会清理租约
+- 每次重试前重新比较期望状态, 用户已经关闭功能时不会继续重试获取
+- 重试耗尽后保留明确错误, 不无限循环消耗系统资源
+- 连接失效会立即释放 App assertion, 避免 UI 已降级但进程仍永久阻止空闲睡眠
+- 旧请求通过 generation 失效, 不依赖每条取消路径都成功撤回底层消息
-防睡眠因低电量或时长上限结束时,通知必须在睡眠状态已经恢复后发送。
+诊断时应区分 registration error 和 operation error. 前者表示 helper 未安装, 待批准或更新失败, 后者表示已安装 helper 的某次切换没有得到可信结果
## CodexBarHelper 更新
-App 更新可能改变内嵌 CodexBarHelper 的签名或内容。App 会记录 CodexBarHelper fingerprint,检测变化后通过 `SMAppService` 和重置接口刷新安装状态。
+App 更新可能改变内嵌 CodexBarHelper 的签名或内容. App 会记录 CodexBarHelper fingerprint, 检测变化后通过 `SMAppService` 和重置接口刷新安装状态
-验证更新时需要同时检查:
+验证更新时需要同时检查
- CodexBarHelper 位于 App 包的正确位置
- LaunchDaemon plist 与 Debug 或 Release bundle ID 匹配
@@ -181,11 +393,11 @@ App 更新可能改变内嵌 CodexBarHelper 的签名或内容。App 会记录 C
## 手动验证矩阵
-- 运行任务开始和结束时,App assertion 与 CodexBarHelper 租约同步切换
-- 等待批准设置关闭和开启时,有效任务判断正确
-- 外部先设置 `disablesleep 1` 时,CodexBar 不声明所有权也不恢复为 `0`
+- 运行任务开始和结束时, App assertion 与 CodexBarHelper 租约同步切换
+- 等待批准设置关闭和开启时, 有效任务判断正确
+- 外部先设置 `disablesleep 1` 时, CodexBar 不声明所有权也不恢复为 `0`
- App 正常退出时恢复 owned 状态
-- App 强制退出或 XPC 断开后,watchdog 恢复 owned 状态
+- App 强制退出或 XPC 断开后, watchdog 恢复 owned 状态
- 达到时长上限后先恢复睡眠再通知
- 低电量触发和 5% 滞回恢复正确
- 异常会话保护隐藏任务后释放防睡眠
diff --git a/Docs/DeveloperGuide/sync.md b/Docs/DeveloperGuide/sync.md
index d5a9774..6177851 100644
--- a/Docs/DeveloperGuide/sync.md
+++ b/Docs/DeveloperGuide/sync.md
@@ -2,9 +2,9 @@
## 同步范围
-CloudKit 同步用于在同一 iCloud 账户的 Mac 之间合并 Hook 日级统计。
+CloudKit 同步用于在同一 iCloud 账户的 Mac 之间合并 Hook 日级统计
-同步对象是聚合结果,不是原始 Hook 事件:
+同步对象是聚合结果, 不是原始 Hook 事件
```text
本机原始 Hook JSONL
@@ -14,11 +14,46 @@ CloudKit 同步用于在同一 iCloud 账户的 Mac 之间合并 Hook 日级统
-> 按日期合并展示
```
-账户,额度,token 总量,实时任务和防睡眠状态不参与同步。
+账户, 额度, token 总量, 实时任务和防睡眠状态不参与同步
+
+## 设计目标和非目标
+
+同步的目标不是复制一台 Mac 的数据库, 而是让多台设备对同一天的独立贡献可以安全相加
+
+因此设计优先级是
+
+1. 不上传原始工作内容和可直接关联硬件的身份
+2. 本机统计永远不依赖 CloudKit 才能展示
+3. 重扫和文件替换不能制造重复计数
+4. 网络失败时保留最后一份可解释的远端快照
+5. 重试必须幂等, 不依赖请求恰好只执行一次
+
+以下内容明确不属于同步协议
+
+- 实时任务状态, 因为它变化快且需要本机低延迟判断
+- 账户额度, 因为它属于 Codex 账户而不是设备工作历史
+- 防睡眠状态, 因为它是当前 Mac 的系统副作用
+- 原始事件, 因为跨设备统计只需要可合并的日级事实
+
+把同步放在聚合层之后还有一个维护收益: 原始 Hook 格式可以独立演进, CloudKit 只面对稳定的日级投影
+
+## 权威来源如何划分
+
+同步展示同时使用 3 类值
+
+| 数据 | 权威来源 | 断网时行为 |
+| --- | --- | --- |
+| 当前设备当天和历史贡献 | 本机 `daily.jsonl` | 继续实时更新 |
+| 其他设备贡献 | `cache.jsonl` 中最近成功拉取的记录 | 保留最后快照 |
+| 上传确认和增量位置 | `state.json` 与 `cursor.data` | 下次继续或重建 |
+
+当前设备始终 local-first. CloudKit 中的本机副本是传给其他设备的复制品, 不是当前设备 UI 的真相来源. 这个规则避免网络往返期间出现先增加一次, 拉取后又重复增加一次的闪烁
+
+远端缓存是可重建投影, 游标只是加速状态. 任何游标错误都可以退化成全量读取 custom zone, 不要求用户清理本地文件
## CloudKit 结构
-[`WorkflowSyncService.swift`](../../CodexBar/Services/Workflow/WorkflowSyncService.swift) 使用 App 的 CloudKit private database:
+[`WorkflowSyncService.swift`](../../CodexBar/Services/Workflow/WorkflowSyncService.swift) 使用 App 的 CloudKit private database
| 项目 | 值 |
| --- | --- |
@@ -27,33 +62,43 @@ CloudKit 同步用于在同一 iCloud 账户的 Mac 之间合并 Hook 日级统
| 元数据 record type | `CodexBarSyncMetadata` |
| 日聚合 record type | `CodexBarDailyAggregate` |
-private database 中的数据只属于当前 iCloud 账户,不写入 public database。
+private database 中的数据只属于当前 iCloud 账户, 不写入 public database
+
+custom zone 的意义不只是命名空间. 它提供 zone change token 和删除事件, 使设备可以增量同步新增, 修改和删除, 而不需要每轮扫描整个 private database
+
+zone 已确认状态和账户 salt 会在 actor 内跨同步轮次缓存, 省去每轮两个固定网络往返. 任意同步失败会使这两项缓存失效, 因为 iCloud 账户切换也可能首先表现为一次请求失败. 下一轮重新确认比继续使用错误账户上下文更安全
## 启用条件
-同步只有在以下条件全部成立时运行:
+同步只有在以下条件全部成立时运行
- 用户打开 CloudKit 同步
- Hook 已启用并校验通过
- 当前 iCloud 账户可用
- 本地聚合服务可用
-首次启用会标记 backfill,上传本地保留期内需要同步的日期。同步调度有最短 8 秒冷却,合并短时间内的多次本地变化。
+首次启用会标记 backfill, 上传本地保留期内需要同步的日期. 同步调度有最短 8 秒冷却, 合并短时间内的多次本地变化
## 设备匿名化
-同步需要区分设备贡献,但不能直接上传硬件标识:
+同步需要区分设备贡献, 但不能直接上传硬件标识
1. 在 private database 创建 32 字节随机账户 salt
2. 读取本机 `IOPlatformUUID`
3. 使用账户 salt 对 UUID 执行 HMAC-SHA256
4. 把结果作为云端 `deviceId`
-原始 `IOPlatformUUID` 不会上传。同一设备在同一 iCloud 账户中得到稳定 pseudonym,不同账户得到不同结果。
+原始 `IOPlatformUUID` 不会上传. 同一设备在同一 iCloud 账户中得到稳定 pseudonym, 不同账户得到不同结果
+
+这里使用 HMAC 而不是普通 SHA-256. 硬件 UUID 的输入空间有固定格式, 单纯 hash 仍是跨账户稳定标识. 账户私有 salt 让同一硬件在不同 iCloud 账户中产生不可关联的 pseudonym
+
+salt 存在同一个 private custom zone 中. 多台设备先后创建时通过 CloudKit 冲突后回读现有记录收敛到同一份 salt, 而不是让每台设备各自产生不兼容身份
+
+本地状态记录最近解析出的 `deviceId`. 如果它变化, 同步会清除旧游标和远端缓存, 但保留待 replacement 日期. 设备身份变化意味着缓存的账户作用域已经不可信, 不能继续增量套用
## 日聚合字段
-每条日记录包含:
+每条日记录包含
- schema
- device ID pseudonym
@@ -65,7 +110,7 @@ private database 中的数据只属于当前 iCloud 账户,不写入 public da
- model 计数
- 更新时间
-不会上传:
+不会上传
- 原始 Hook JSONL
- session ID 或 turn ID 原文
@@ -92,40 +137,100 @@ private database 中的数据只属于当前 iCloud 账户,不写入 public da
-> 发布合并结果
```
+实际顺序刻意在上传前先拉取
+
+- 上传前知道远端是否已经有同设备同日记录, 才能选择更新, 新建 generation 记录或跳过
+- replacement 前必须先全量拉取, 才能找到增量缓存可能遗漏的旧 generation
+- 上传后再次拉取, 才能把本轮写入和其他设备并发写入统一进本地缓存
+- 最后清理过期记录, 避免清理失败阻断本轮有效数据上传
+
+每个阶段都写入日志中的 `stage`, 失败信息因此能回答问题发生在 zone, device, fetch, upload 还是 prune, 而不只得到一个笼统的 CloudKit error
+
- 上传每批最多 25 条记录
- 单批操作最长等待 20 秒
- 拉取单页最多 200 条变更
- 本地内容使用 SHA-256 hash 跳过未改变记录
+20 秒是整轮上传预算, 不是每条记录的超时. 达到预算后剩余日期保留为未确认状态, 后续调度继续处理. 这样一次历史 backfill 不会长时间占用 actor 和用户可见刷新链路
+
+每个日期的稳定 JSON 只编码并 hash 一次, 同一结果同时用于筛选和成功确认. 如果在不同阶段重新编码, 字典顺序或可选字段差异可能让"是否改变"判断自行漂移
+
+上传使用 `atomically: false`. 单批部分成功时, 每条 CloudKit 结果分别确认, 失败日期移除本地 hash 以便重试. 协议依赖单记录幂等身份, 不要求 25 条全部成功才前进
+
## 合并语义
-同一天可能有多个设备记录,也可能有当前设备尚未上传的最新本地结果。
+同一天可能有多个设备记录, 也可能有当前设备尚未上传的最新本地结果
-合并规则是:
+合并规则是
- 其他设备贡献按字段相加
-- 当前设备使用最新本地聚合替换云端同设备贡献
-- 同一设备同一天只取当前 source generation
+- 当前设备使用最新本地聚合替换云端的同源贡献
+- 同一 source generation 最多计算一份
+- 已确认属于不同来源的 generation 可以累加
- 当前设备本地数据缺失时才使用云端缓存贡献
-用本地值替换当前设备云端值可以避免同步刚上传但本地 UI 已更新时发生双重计数。
+用本地值替换当前设备云端值可以避免同步刚上传但本地 UI 已更新时发生双重计数
+
+### 同设备同日为什么可能有多条记录
+
+早期记录名只包含 `deviceId + date`. 新鲜来源可额外使用 `deviceId + date + sourceGeneration`
+
+generation 记录用于表达某一份原始来源的身份. 同源的本地和云端结果是替换关系, 明确不同的来源则可能是同一天先后产生的独立贡献
+
+读取层先寻找与本地 `sourceGeneration` 匹配的 record. 匹配项只取本地或远端中更完整的一份, 其他 generation 继续累加. 旧 legacy record 没有 generation 时, 内容完全相同也可视为同源, 用于兼容早期记录
+
+"所有旧 generation 都应失效"不是从 generation 本身推断, 而是由显式 `replacementDates` 事务表达. 这一区分避免正常文件换代丢掉独立贡献, 又让用户主动完整重建可以删除历史副本
+
+上传目标的选择遵循以下原则
+
+| 远端状态 | 本地来源 | 动作 |
+| --- | --- | --- |
+| 没有同日记录 | 任意 | 创建 legacy 或 generation record |
+| 有同源记录 | 本地不少于远端 | 更新该记录 |
+| 有同源且远端事件更多 | 本地带 generation | 保留远端, 避免较短的陈旧扫描覆盖较完整结果 |
+| 有其他来源记录 | 本地来源新鲜 | 创建当前 generation record |
+| 有其他来源记录 | 本地来源不新鲜 | 跳过, 等待权威重建 |
+
+`sourceIsFresh` 是一次读取对原始来源完整性的判断, 不是时间新旧. 文件被替换, 截断或仍在稳定边界确认中时, 较新的时间戳也不代表更权威
+
+### missing 为什么不能转成 0
+
+CloudKit record schema 演进时, 旧记录可能没有新计数字段. `nil` 表示该设备那天无法提供这项统计, `0` 表示明确观察到零次
+
+合并时保留可用性信息, UI 才能区分"所有设备合计为 0"和"部分历史来源不支持该指标". 把缺失解码成 0 会制造无法在以后修复的虚假事实
## 来源替换与重建
-Hook 原始文件被替换或完整重建时,聚合层会改变 source generation。同步层必须把这个变化解释为替换,不能把新旧代际相加。
+Hook 原始文件被替换或完整重建时, 聚合层会改变 source generation. 同步层必须把这个变化解释为替换, 不能把新旧代际相加
-用户执行重新扫描时:
+用户执行重新扫描时
1. 本地聚合从原始 JSONL 重建
2. 受影响日期标记为 replacement
3. 当前设备对应日期的云端记录被覆盖或删除后重建
4. 其他设备记录保持不变
-这种设计让重建只修正当前设备贡献。
+这种设计让重建只修正当前设备贡献
+
+### replacement 为什么是持久化事务
+
+重建和 CloudKit 同步不一定在同一进程生命周期完成. `replacementDates` 因此保存在 `state.json`, 不能只留在内存
+
+对每个 replacement 日期, 同步执行
+
+1. 全量重建远端缓存
+2. 枚举当前设备同日所有已知 legacy 和 generation record ID
+3. 删除这些旧贡献, `unknownItem` 按幂等成功处理
+4. 从本地 hash 表移除该日期, 强制重新上传
+5. 只有新内容得到确认后才清除 replacement 标记
+
+replacement 进行中时, 快照会临时过滤当前设备该日期的云端缓存, 同时展示本机最新聚合. 即使 App 在删除和重传之间退出, UI 也不会把旧云端贡献与新本地贡献相加
+
+先全量拉取是这一事务最关键的小细节. 增量 cursor 只保证从游标之后的变化完整, 不保证本地缓存从未因旧版本或手动删除丢过记录. 删除前全量枚举才能避免遗留幽灵 generation
## 增量游标与本地缓存
-同步状态位于:
+同步状态位于
```text
~/Library/Application Support/CodexBar/HookEvents/Sync/
@@ -133,15 +238,73 @@ Hook 原始文件被替换或完整重建时,聚合层会改变 source generat
| 文件 | 作用 |
| --- | --- |
-| `state.json` | 同步 schema,本地 hash,backfill 和替换状态 |
+| `state.json` | 同步 schema, 本地 hash, backfill 和替换状态 |
| `cache.jsonl` | 远端设备日聚合缓存 |
| `cursor.data` | CloudKit zone change token |
-当前 CloudKit record schema 为 `5`。本地同步状态 schema 为 `4`,能读取上一版 schema `3`
+当前 CloudKit record schema 为 `5`. 本地同步状态 schema 为 `4`, 能读取上一版 schema `3`
+
+3 个文件有不同的可恢复等级
+
+| 文件 | 丢失后代价 | 恢复方式 |
+| --- | --- | --- |
+| `state.json` | 失去上传 hash 和 replacement 进度 | 重新比较并上传, replacement 需依赖仍存在的标记 |
+| `cache.jsonl` | 暂时看不到其他设备贡献 | 全量拉取 custom zone |
+| `cursor.data` | 失去增量位置 | 全量拉取并重新建立 baseline |
+
+`cursor.data` 使用 secure coding 保存 CloudKit opaque token. 代码不解析其内部结构. 全量拉取后还要建立新的 cursor baseline, 否则下一轮可能从空游标重复消费刚拉取的全部变化
+
+本地 schema `3 -> 4` 的读取路径会先重建远端缓存再提交新状态. 未知 schema 则回到空同步状态, 因为错误解释上传确认信息比重新同步更危险
+
+任何 record 字段, identity 或 schema 的变化都是兼容性决策. 需要同时考虑旧 App 仍在写入, 新 App 如何读取旧字段, 以及降级后是否会覆盖新记录, 不能只递增一个常量
+
+## 调度器为什么独立存在
+
+本地维护和 CloudKit 同步共享聚合输入, 但触发频率不同. `WorkflowSyncScheduler` 把多处触发合并为单线程状态机
+
+优先级为
+
+```text
+用户请求重建 > 可立即执行的同步维护 > 纯本地维护 > 冷却中的同步
+```
+
+关键细节包括
+
+- 同步完成后 8 秒内的新请求合并到下一轮, 避免一次 Hook burst 触发多轮网络操作
+- 合并请求保留最早 trigger, 因为它才是这轮工作的真实起因
+- 重建会取消前一个尚未开始的重建 completion, 不让调用方永远等待
+- 同步在等待期间被关闭时清除 pending sync, 但仍允许必要的本地维护继续
+- `@Published` 订阅发生在 `willSet`, 从回调内读取属性仍是旧值, 因此 activation 由新回调参数显式计算后传入
+
+最后一点是 Combine 生命周期中很容易被"整理代码"破坏的小巧思. 现场重新读取 settings 看起来更简洁, 实际会用旧值决定是否同步
+
+## 失败和恢复语义
+
+同步失败不回滚已经确认的独立 record, 也不清空最后一份可用 cache. 下轮通过 hash, record ID 和 CloudKit 幂等 API 继续收敛
+
+| 失败点 | 已保留状态 | 下轮动作 |
+| --- | --- | --- |
+| zone 或账户确认 | 本地聚合和旧 cache | 重新确认 zone 和 salt |
+| 增量拉取 | 旧 cache | 退化为全量重建 |
+| 部分上传 | 已成功日期 hash | 仅重试未确认日期 |
+| replacement 删除 | replacement 标记 | 重新枚举并幂等删除 |
+| prune | 有效期内数据和上传结果 | 后续再清理 |
+
+账户级缓存会在失败后失效, 但磁盘 cache 不会立刻作为新账户事实发布. availability 和 device identity 重新确认后才恢复同步快照
+
+## 修改同步协议时的检查顺序
+
+1. 先定义字段语义, 尤其是 missing, 0 和空集合是否不同
+2. 决定 record identity 是否仍然幂等
+3. 评估旧 App 与新 App 并发写入的结果
+4. 明确本地 state, cache 和 cursor 的升级或重建路径
+5. 检查 replacement 是否能删除所有旧代际
+6. 检查隐私边界和用户 opt-in 是否仍成立
+7. 用两台设备和一次中途失败验证最终收敛
## 保留与清理
-CloudKit 记录保留期与本地 Hook 历史一致,最长 210 天:
+CloudKit 记录保留期与本地 Hook 历史一致, 最长 210 天
- 本地原始和日聚合过期后删除
- 当前设备过期云端记录进入清理
@@ -150,7 +313,7 @@ CloudKit 记录保留期与本地 Hook 历史一致,最长 210 天:
## 错误分类
-同步层区分以下状态,供设置页展示和通知:
+同步层区分以下状态, 供设置页展示和通知
- 网络不可用
- iCloud 账户不可用
@@ -159,15 +322,15 @@ CloudKit 记录保留期与本地 Hook 历史一致,最长 210 天:
- 本地数据或 schema 不兼容
- 同步成功或无需变化
-临时错误保留最后一份可用远端缓存。账户切换或身份失效时不能继续把旧账户缓存当作当前账户数据。
+临时错误保留最后一份可用远端缓存. 账户切换或身份失效时不能继续把旧账户缓存当作当前账户数据
## 手动验证矩阵
- 首次启用后上传保留期内本机聚合
-- 第二台设备能够合并显示,不重复当前设备贡献
+- 第二台设备能够合并显示, 不重复当前设备贡献
- 关闭同步后只显示本地统计
-- iCloud 未登录时显示明确状态,本地统计继续工作
-- 网络断开后使用最后缓存,恢复后完成增量同步
+- iCloud 未登录时显示明确状态, 本地统计继续工作
+- 网络断开后使用最后缓存, 恢复后完成增量同步
- 本机重建后只替换当前设备记录
- 超过 210 天的本地和远端缓存被清理
- iCloud 账户切换后不显示前一账户缓存
diff --git a/Docs/DeveloperGuide/ui-and-lifecycle.md b/Docs/DeveloperGuide/ui-and-lifecycle.md
index d1f764e..fd32430 100644
--- a/Docs/DeveloperGuide/ui-and-lifecycle.md
+++ b/Docs/DeveloperGuide/ui-and-lifecycle.md
@@ -4,70 +4,189 @@
CodexBar 在 [`Info.plist`](../../CodexBar/Resources/Info.plist) 中配置为 `LSUIElement`
-它没有 Dock 图标和普通主窗口生命周期。菜单栏,popover,浮动面板,设置窗口和通知点击都必须显式处理 App 激活与焦点。
+它没有 Dock 图标和普通主窗口生命周期. 菜单栏, popover, 浮动面板, 设置窗口和通知点击都必须显式处理 App 激活与焦点
-普通 SwiftUI Window 的默认行为不足以覆盖这些场景,因此 UI 采用 SwiftUI 内容加 AppKit Controller 的组合。
+普通 SwiftUI Window 的默认行为不足以覆盖这些场景, 因此 UI 采用 SwiftUI 内容加 AppKit Controller 的组合
+
+## UI 架构的分工
+
+SwiftUI 负责声明内容, AppKit 负责窗口和事件生命周期
+
+| 层 | 负责 | 不负责 |
+| --- | --- | --- |
+| SwiftUI View | 布局, 数据展示, 用户意图回调 | 创建长期服务, 决定 key window, 安装全局事件监听 |
+| ViewModel 和 Settings | 发布稳定快照, 保存用户设置 | 持有窗口或判断屏幕坐标 |
+| AppKit Controller | popover, panel, window, focus, event monitor | 重新实现业务状态机 |
+| AppDelegate | 组装和持有长期对象 | 承载具体视图布局 |
+
+这个边界让同一份菜单内容可以装入 `NSPopover` 或 fallback `NSPanel`, 同时避免 SwiftUI View 因 identity 变化而销毁 monitor, XPC 或通知服务
+
+## `LSUIElement` 下的 3 类焦点
+
+开发时需要区分
+
+- App 是否 active
+- 某个 window 是否 key
+- 菜单表面是否逻辑上 presented
+
+这 3 个状态不会自动同步. 例如 Command-Space 会让 App resign active, 但用户可能只是临时打开 Spotlight, 不希望菜单立即消失. 设置窗口可能已经可见, 但菜单关闭动画期间不应抢回 key 造成闪烁
+
+因此代码不使用 `NSApp.isActive` 作为菜单唯一真相, 而是维护显式的 menu surface 状态和当前容器, 再由事件监听器协调 activation
## 服务装配
-[`StatusItemController.swift`](../../CodexBar/Controllers/StatusItemController.swift) 同时包含 AppDelegate 和菜单栏主控制器。
+[`StatusItemController.swift`](../../CodexBar/Controllers/StatusItemController.swift) 同时包含 AppDelegate 和菜单栏主控制器
-AppDelegate 负责:
+AppDelegate 负责
-- 创建长期 service,ViewModel 和 settings
-- 建立 monitor 与通知,防睡眠的观察关系
+- 创建长期 service, ViewModel 和 settings
+- 建立 monitor 与通知, 防睡眠的观察关系
- 启动状态刷新和 Hook 活动读取
- 创建状态栏控制器
- 安装全局快捷键
- 配置 Sparkle 更新
- 在 App 终止时协调防睡眠释放
-对象由 composition root 显式持有,避免 SwiftUI View 生命周期意外销毁长期服务。
+对象由 composition root 显式持有, 避免 SwiftUI View 生命周期意外销毁长期服务
+
+### 启动顺序为什么重要
+
+普通模式的装配顺序体现依赖关系
+
+```text
+创建 settings 和数据服务
+ -> 建立 ViewModel
+ -> 启动 activity monitor
+ -> 连接 notification 与 keep-alive 副作用
+ -> 创建 status item 和窗口 controller
+ -> 启动周期刷新与更新服务
+```
+
+通知和防睡眠只消费 monitor 已发布的快照或转场, 不反向控制 reader. Controller 通过闭包连接这些服务, 从而避免服务层依赖 AppKit 容器
+
+终止时顺序反转, 但防睡眠是例外. AppDelegate 先异步确认 helper lease 已释放, 成功后才允许进程终止. 详细事务见 [防睡眠系统](sleep-prevention.md)
## 状态栏图标
-状态图标综合 app-server 加载状态,菜单栏额度设置和任务活动快照。
+状态图标综合 app-server 加载状态, 菜单栏额度设置和任务活动快照
-任务状态点的优先级是:
+任务状态点的优先级是
```text
等待批准 > 运行中 > 最近完成 > 最近中断 > 空闲
```
-图标生成结果按输入状态缓存,避免每次定时刷新重复绘制。非激活或不可用状态通过 alpha 表达。
+图标生成结果按输入状态缓存, 避免每次定时刷新重复绘制. 非激活或不可用状态通过 alpha 表达
+
+### 图像状态与 tooltip 状态分离
-左键打开主面板。右键或按住 Control 点击打开上下文菜单。
+`StatusIconState` 同时含图像输入和 tooltip 输入, 但 `renderState` 只保留真正影响像素的字段
+
+- 活跃任务持续时间每分钟变化, 只更新 tooltip
+- 额度过期但仍展示缓存时, 图标和进度使用降低后的 alpha
+- 指示点或额度条显隐变化时才启动约 0.18 秒的 10 帧动画
+- 新渲染状态到达时取消旧动画, 每帧再次确认目标状态仍是当前状态
+
+如果直接对完整状态做 `NSImage` 重绘, 每次计时文字变化都会打断动画并增加菜单栏绘制. 将 render identity 显式建模是一个小而重要的性能边界
+
+无状态点和额度条时图标保持 template image, 让系统根据浅色, 深色和菜单栏状态自动着色. 一旦加入自定义颜色或进度条就使用显式颜色绘制
+
+tooltip 只在存在实时任务持续时间时启动 60 秒计时器, 空闲时不保留永久 timer. App 还把 `NSInitialToolTipDelay` 调整为 500 ms, 让菜单栏这种小点击目标的状态解释更容易被发现
+
+左键打开主面板. 右键或按住 Control 点击打开上下文菜单
## 主面板
-主面板优先使用 `NSPopover`,`behavior` 设为 `applicationDefined`
+主面板优先使用 `NSPopover`, `behavior` 设为 `applicationDefined`
-CodexBar 自己管理 dismiss,原因包括:
+CodexBar 自己管理 dismiss, 原因包括
-- 主面板可以打开设置,日志和侧边详情面板
+- 主面板可以打开设置, 日志和侧边详情面板
- `LSUIElement` 激活切换会制造普通 transient popover 的误关闭
- 侧边面板需要被视为同一个交互表面
- 关闭动画需要统一淡出
-[`MenuSurfaceDismissMonitor.swift`](../../CodexBar/Controllers/MenuSurfaceDismissMonitor.swift) 监听全局和本地事件,[`MenuSurfaceFadeCoordinator.swift`](../../CodexBar/Controllers/MenuSurfaceFadeCoordinator.swift) 统一协调关闭动画。
+[`MenuSurfaceDismissMonitor.swift`](../../CodexBar/Controllers/MenuSurfaceDismissMonitor.swift) 监听全局和本地事件, [`MenuSurfaceFadeCoordinator.swift`](../../CodexBar/Controllers/MenuSurfaceFadeCoordinator.swift) 统一协调关闭动画
+
+### 为什么需要显式开合状态机
+
+`menuSurfaceState` 有 4 个状态
+
+```text
+hidden -> opening -> shown -> closing -> hidden
+```
+
+它解决快速重复点击产生的中间态
+
+- `opening` 或 `shown` 时再次 toggle 进入关闭
+- `closing` 时再次 toggle 先完成旧关闭, 再打开新表面
+- 关闭开始后取消延迟刷新和旧动画
+- 非动画关闭会直接完成状态收口, 不等待不会发生的 animation completion
+
+只检查 `popover.isShown` 不足以表示 opening 或 fade-out 中的逻辑状态, 也无法同时覆盖 fallback panel
+
+### dismiss 规则为什么由一个监听器管理
+
+主面板的允许点击区域是一个集合
+
+```text
+当前菜单窗口 + status item 按钮 + 所有已显示侧边面板
+```
+
+本地 monitor 处理 App 内鼠标和键盘, global monitor 处理其他 App 上的鼠标点击, workspace 和 window observer 处理激活变化. 任一入口最后都调用同一 `onDismiss`
+
+特殊规则包括
+
+- Escape 消费事件并关闭
+- Command-Tab 允许系统切换, 同时关闭面板
+- Command-Space 短暂抑制 activation dismiss, 避免打开 Spotlight 时误关
+- 点击后重新固定 `NSVisualEffectView` 为 inactive, 避免 AppKit 自动强调背景导致明暗跳变
+- 初次安装 observer 后 `Task.yield()` 再补一次窗口获取和聚焦, 覆盖 popover window 尚未挂载的时机
+
+这些规则应作为一个交互表面整体修改. 只给某个侧边 panel 单独添加 event monitor 会制造监听顺序和重复关闭问题
+
+### 淡入淡出作用在内容而不是窗口
+
+popover 的系统窗口由 AppKit 管理, 直接动画窗口 alpha 容易与系统显示状态冲突. `MenuSurfaceFadeCoordinator` 对活动容器的 content view 做动画, 完成后再调用统一 close
+
+关闭期间辅助窗口暂时拒绝 `makeKey()`. 否则原本已打开的设置或日志窗口可能在菜单 fade-out 的几帧里突然跳到前面
## Fallback panel
-全局快捷键触发时,状态栏按钮的屏幕位置可能不可用或不可信。此时 [`FallbackPanelController.swift`](../../CodexBar/Controllers/FallbackPanelController.swift) 在鼠标所在屏幕显示浮动面板。
+全局快捷键触发时, 状态栏按钮的屏幕位置可能不可用或不可信. 此时 [`FallbackPanelController.swift`](../../CodexBar/Controllers/FallbackPanelController.swift) 在鼠标所在屏幕显示浮动面板
+
+popover 和 fallback panel 承载同一份 SwiftUI 内容和状态. 业务逻辑不能依赖具体容器类型
-popover 和 fallback panel 承载同一份 SwiftUI 内容和状态。业务逻辑不能依赖具体容器类型。
+### 锚点为何需要可信度检查
+
+全局快捷键可能在 status item 尚未完成布局, 菜单栏位于另一块屏幕, 或系统暂时不给出 button window 时触发. 代码不会只检查 button 非 nil, 还验证
+
+- window 和 screen 存在
+- button 没有隐藏且 bounds 非空
+- 转换后的屏幕 rect 有效且至少为 1 point
+- rect 与目标屏幕 frame 在 1 point 容差内相交
+
+只有全部成立才使用 popover 箭头. 否则 fallback panel 放到鼠标所在屏幕. 这避免 popover 被 AppKit 放到错误显示器或完全不可见的位置
+
+fallback panel 在展示前根据 SwiftUI fitting size 和目标屏幕可见区域约束尺寸. 坐标计算集中在 `ScreenGeometry`, 因为 AppKit 使用左下角原点, SwiftUI 局部布局和多显示器 frame 很容易混用
## 侧边详情面板
-主面板可以打开:
+主面板可以打开
- 活跃度热力图详情
- Reset Credits 详情
- 活动中心
-这些面板互斥,打开一个时关闭其他侧边面板。它们会把自己的屏幕区域加入主表面的额外 hit region,用户在主面板和侧边面板之间移动或点击时不会触发误关闭。
+这些面板互斥, 打开一个时关闭其他侧边面板. 它们会把自己的屏幕区域加入主表面的额外 hit region, 用户在主面板和侧边面板之间移动或点击时不会触发误关闭
-相关控制器包括:
+所有详情面板实现 `MenuSideDetailPanel` 并登记在 `sideDetailPanels` 数组. 互斥关闭, 主表面关闭和 hit testing 都遍历同一份名册
+
+这比在每对面板之间写互相关闭更可扩展. 新增第 4 个面板时只需要加入名册, 不需要补齐 6 对互斥关系
+
+hover 类型的热力图面板在打开其他面板前可以渐隐, 点击类型的面板通常立即关闭旧面板. 这是为了避免同一屏幕位置出现两个反向滑动动画叠加
+
+相关控制器包括
- [`HeatmapDetailPanelController.swift`](../../CodexBar/Controllers/HeatmapDetailPanelController.swift)
- [`ResetCreditsPanelController.swift`](../../CodexBar/Controllers/ResetCreditsPanelController.swift)
@@ -76,19 +195,40 @@ popover 和 fallback panel 承载同一份 SwiftUI 内容和状态。业务逻
## 设置和日志窗口
-设置与日志使用独立 `NSWindowController`
+设置与日志由独立的 `HostingWindowController` 管理 `NSWindow`
+
+`LSUIElement` App 打开普通窗口时需要暂时允许窗口成为 key, 激活 App, 再把焦点交给目标控件. 关闭后恢复菜单栏 App 的非前台行为
-`LSUIElement` App 打开普通窗口时需要暂时允许窗口成为 key,激活 App,再把焦点交给目标控件。关闭后恢复菜单栏 App 的非前台行为。
+焦点恢复使用约 120 ms 延迟, 给 AppKit 完成窗口和 activation 状态切换. 这类延迟属于系统生命周期协调, 不能简单删除为同步调用
-焦点恢复使用约 120 ms 延迟,给 AppKit 完成窗口和 activation 状态切换。这类延迟属于系统生命周期协调,不能简单删除为同步调用。
+上下文菜单 action 会延迟到 menu tracking 结束后执行, 避免 AppKit 仍在菜单事件循环中时创建或激活窗口
-上下文菜单 action 会延迟到 menu tracking 结束后执行,避免 AppKit 仍在菜单事件循环中时创建或激活窗口。
+### 辅助窗口的持有和定位
+
+`HostingWindowController` 懒创建并长期复用单个 window
+
+- `isReleasedWhenClosed = false`, 关闭只隐藏, 下次保留窗口对象和 SwiftUI 状态
+- `.moveToActiveSpace`, 重开时跟随当前 Space, 不把用户切回旧桌面
+- 优先在 status item 所在屏幕居中, 再退到 window screen 或 main screen
+- miniaturized 窗口先 deminiaturize 再激活
+
+设置窗口的高度随当前 tab 内容变化, 但固定上边缘并限制到屏幕 visible frame. 固定上边缘可以减少切换 tab 时整窗上下漂移, 让标题栏保持稳定视觉锚点
+
+通知和防睡眠的二级设置面板按需创建. 控制器一旦创建就会长期订阅内容高度变化, 如果 App 启动时预建所有面板, 从未使用的 UI 也会一直参与更新
+
+### 120 ms 焦点恢复不是业务延迟
+
+菜单关闭时 `AuxiliaryHostingWindow` 暂时把 `allowsKeyFocus` 设为 false. 关闭完成后等待约 120 ms 再恢复
+
+这段时间给 AppKit 完成 popover order-out, activation 和 key window 重算. 删除延迟可能只在开发机上偶尔复现设置窗口闪前, 因此应把它视为系统事件排序约束, 而不是可以随意优化掉的等待
+
+右键菜单 action 也要等 `menuDidClose` 后通过主队列执行. menu tracking 是嵌套事件循环, 在其中同步创建窗口会得到不稳定的 activation 顺序
## 全局快捷键
-[`GlobalHotKeyController.swift`](../../CodexBar/Controllers/GlobalHotKeyController.swift) 使用 Carbon Hot Key API。
+[`GlobalHotKeyController.swift`](../../CodexBar/Controllers/GlobalHotKeyController.swift) 使用 Carbon Hot Key API
-快捷键约束:
+快捷键约束
- 至少包含 2 个修饰键
- 拒绝 `Command-Space`
@@ -96,41 +236,66 @@ popover 和 fallback panel 承载同一份 SwiftUI 内容和状态。业务逻
- 系统注册冲突时回滚到之前可用设置
- 设置变更立即重新注册
-Carbon API 适合无 Dock 菜单栏 App,不需要安装全局键盘事件 tap 或请求输入监控权限。
+Carbon API 适合无 Dock 菜单栏 App, 不需要安装全局键盘事件 tap 或请求输入监控权限
+
+注册新快捷键采用先试后换
+
+1. 为候选快捷键安装临时 handler 和 hot key
+2. 注册成功后才释放当前 registration
+3. 注册失败时清理候选资源并恢复设置中的旧值
+
+如果先注销旧快捷键, 一次冲突会让用户同时失去新旧两组按键. `GlobalHotKeyRegistration` 在显式 invalidate 和 deinit 中都清理 Carbon 引用, 避免重注册泄漏 handler
+
+至少两个修饰键降低误触概率. Command-Space 和 Command-Tab 被拒绝, 因为它们属于核心系统导航, 即使注册 API 某次允许也不应抢占
## 自动刷新与面板打开
-app-server 状态默认每 60 秒刷新。面板打开时会安排约 160 ms 的延迟刷新,先完成动画和焦点切换,再更新数据。
+app-server 状态默认每 60 秒刷新. 面板打开时会安排约 160 ms 的延迟刷新, 先完成动画和焦点切换, 再更新数据
+
+主面板显示倒计时. 手动刷新由双击触发, 避免单击状态栏本身与按钮动作产生歧义
+
+刷新协调器合并并发触发, 防止定时器, 面板打开和用户操作重复创建相同请求
+
+面板打开时 Hook 统计立即从本地缓存刷新, app-server 请求延后约 160 ms. 前者便宜且能快速填充内容, 后者可能启动进程或发协议请求, 放在开场动画之后可减少首帧卡顿
+
+`refreshIfNeeded` 仍会执行 freshness 合并, 160 ms 不是绕过协调器的第二套刷新路径. 面板在等待期间关闭时 task 被取消, 不再为不可见 UI 发请求
-主面板显示倒计时。手动刷新由双击触发,避免单击状态栏本身与按钮动作产生歧义。
+## 修改 UI 生命周期时的检查顺序
-刷新协调器合并并发触发,防止定时器,面板打开和用户操作重复创建相同请求。
+1. 确定变化属于 SwiftUI 内容还是 AppKit 容器生命周期
+2. 检查 popover 和 fallback panel 是否共用相同行为
+3. 检查 opening 和 closing 中间态, 不只验证稳定状态
+4. 检查点击区域是否需要加入 extra surface
+5. 检查 App active, key window 和逻辑 presented 是否可能分离
+6. 检查任务或 timer 在关闭和 uninstall 时是否取消
+7. 在多显示器, 多 Space 和无可信 status item anchor 下验证
+8. 从通知点击, 全局快捷键和右键菜单 3 个入口分别打开
## 本地化和格式化
简体中文和英文界面字符串位于 [`Localizable.xcstrings`](../../CodexBar/Resources/Localizable.xcstrings)
-日期,数字和百分比使用系统自动更新 locale。不在业务模型中固定中文格式,也不把本地化后的字符串作为状态机输入。
+日期, 数字和百分比使用系统自动更新 locale. 不在业务模型中固定中文格式, 也不把本地化后的字符串作为状态机输入
## 自动更新
-[`AppUpdater.swift`](../../CodexBar/Services/Updates/AppUpdater.swift) 封装 Sparkle:
+[`AppUpdater.swift`](../../CodexBar/Services/Updates/AppUpdater.swift) 封装 Sparkle
- appcast URL 来自 App 配置
- 自动检查间隔为 3600 秒
- 更新 UI 由设置页和上下文菜单触发
- CodexBarHelper 变化在更新后单独执行 fingerprint 和注册状态检查
-发布脚本需要 Developer ID,签名和公证凭据,不属于日常本地构建流程。
+发布脚本需要 Developer ID, 签名和公证凭据, 不属于日常本地构建流程
## 手动验证矩阵
-- 左键打开主面板,右键和 Control 点击打开上下文菜单
-- 点击主面板外部正确关闭,点击侧边面板不误关闭
-- 热力图,Reset Credits 和活动中心保持互斥
+- 左键打开主面板, 右键和 Control 点击打开上下文菜单
+- 点击主面板外部正确关闭, 点击侧边面板不误关闭
+- 热力图, Reset Credits 和活动中心保持互斥
- 全局快捷键在状态栏锚点有效和无效场景都能打开面板
- 从通知点击激活 App 并打开面板
-- 设置窗口首次打开,关闭和再次打开时焦点正确
+- 设置窗口首次打开, 关闭和再次打开时焦点正确
- 上下文菜单打开设置或日志时没有焦点丢失
- 多显示器和不同菜单栏位置下 fallback panel 位于鼠标屏幕
- 快捷键冲突后原快捷键仍可用