CodexBar 是一个 macOS 菜单栏应用,用于查看本机 Codex 账号状态、额度、Token 用量、详细统计信息
Swift appkitcodexcodex-clideveloper-toolsmacosmacos-appmenu-bar-appopenai-codexproductivityswiftswiftuiusage-tracker
docs: 统一项目文档写作规范
Bobd7281681a5d9
diff --git a/AGENTS.md b/AGENTS.mdindex 3a8d9f1..3342659 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -2,73 +2,91 @@## 项目结构与模块组织-CodexBar 是面向 macOS 15+ 的 `LSUIElement` 菜单栏应用, 使用 Swift 6, SwiftUI, AppKit 和 MVVM; 工程只有 `CodexBar` scheme, 包含主 App 与 `CodexBarHelper` 两个 target+CodexBar 是面向 macOS 15+ 的 `LSUIElement` 菜单栏应用,使用 Swift 6, SwiftUI, AppKit 和 MVVM。工程只有 `CodexBar` scheme,包含主 App 与 `CodexBarHelper` 两个 target。-`CodexBar/` 按 `App/` `Views/` `Controllers/` `Models/` `Services/` 和 `Resources/` 分层; root LaunchDaemon 位于 `CodexBarHelper/` 目录, 跨 target XPC 接口位于 `Shared/` 目录. `Scripts/` 提供发布和 helper 清理工具, `Images/` 存放 README 资源+`CodexBar/` 按 `App/` `Views/` `Controllers/` `Models/` `Services/` 和 `Resources/` 分层。root LaunchDaemon 位于 `CodexBarHelper/` 目录,跨 target XPC 接口位于 `Shared/` 目录。`Scripts/` 提供发布和 helper 清理工具,`Images/` 存放 README 资源。-## 构建, 测试与开发命令+## 构建、测试与开发命令- `xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/platform=macOS' build` 执行代码变更后的构建验证-- `swiftformat .` 按 `.swiftformat` 格式化全部 Swift, 使用 Swift 6 和 4 空格缩进+- `swiftformat .` 按 `.swiftformat` 格式化全部 Swift,使用 Swift 6 和 4 空格缩进- `swiftlint` 按 `.swiftlint.yml` 检查-- `/usr/bin/log stream --predicate 'subsystem == "app.zabrian.codexbar"' --style compact` 查看系统日志, Debug 版 subsystem 带 `.debug` 后缀+- `/usr/bin/log stream --predicate 'subsystem == "app.zabrian.codexbar"' --style compact` 查看系统日志,Debug 版 subsystem 带 `.debug` 后缀-`Scripts/build.sh` `dmg.sh` 和 `appcast.sh` 需要 Developer ID 与公证凭据, 不用于日常验证+`Scripts/build.sh` `dmg.sh` 和 `appcast.sh` 需要 Developer ID 与公证凭据,不用于日常验证。## 写作风格-本仓库的中文文本 (提交信息, 代码注释, 文档) 统一遵守+代码、代码注释和项目文档使用彼此独立的规则,不得把一类内容的标点约定直接套用到另一类内容。提交信息由 Git 规范单独约束。-- 禁止使用中文标点, 一律使用半角标点-- 句中停顿和并列项使用空格或者逗号, 顿号的位置也用空格或者逗号-- 分号只用来断开完整句子, 相当于句号; 拿不准就把它换成句号读一遍, 两边都能独立成句才保留+### 代码和注释++代码和注释统一遵守:++- 禁止使用中文标点,一律使用半角标点+- 句中停顿和并列项使用空格或者逗号,顿号的位置也用空格或者逗号+- 分号只用来断开完整句子,相当于句号;拿不准就把它换成句号读一遍,两边都能独立成句才保留- 行末禁止使用标点-- 行内标点后如果还有文字, 间隔一个英文空格-- 行内代码后尽量不要紧跟标点, 需要断句时补一个词或者使用空格再断-- 一条 bullet 只讲一件事, 需要两个以上完整句子时拆成多条+- 行内标点后如果还有文字,间隔一个英文空格+- 注释中引用类型、成员、参数或命令后尽量不要紧跟标点,需要断句时补一个词或者使用空格再断+- 一个注释段只解释一件事,需要说明多个独立主题时拆成多个注释段++### 项目文档++项目文档统一遵守:++- 代码标识符、命令、路径、配置键、原始字段值和需要精确复制的版本号使用行内代码+- 中文正文使用全角中文标点,包括 `,` `。` `;` `:` `!` `?` `“”` 和 `()`+- 中文短词或短语的并列使用 `、`;能独立表达语义的分句使用 `,`,两边都能独立成句时才考虑 `;`+- 中文标点前后不加空格;中文与英文、数字或行内代码之间按词语边界保留一个半角空格+- 不机械替换特殊内容中的英文标点。数字序列、行内代码序列或英文术语并列时,如果英文标点观感更好,使用英文标点并在其后保留一个半角空格+- 普通正文行末使用与语义匹配的中文标点;引出列表、表格或代码块的正文使用 `:`+- 标题、独立列表项、编号项和表格单元格行末不加标点+- 如果一行以 Markdown 格式的链接或行内代码结尾,后面不加任何标点;链接或行内代码位于句中时仍按句子结构使用中文标点+- Markdown 语法、代码块、命令、路径、URL、版本号和程序标识符内部的符号保持原样## 架构与编码约定-启动时必须先调用 `WorkflowHookEventRecorder.handleIfRequested()` 方法. `--hook-event` 模式只读取 stdin, 加锁写入 JSONL 并立即退出, 不初始化 UI, 失败也不能阻断 Codex. Handler 超时按事件从 `hookTimeoutSeconds(for:)` 取得, `SessionEnd` 为 3 秒, 其他事件为 5 秒. 普通模式由 `CodexBarAppDelegate` 统一装配长期服务+启动时必须先调用 `WorkflowHookEventRecorder.handleIfRequested()` 方法。`--hook-event` 模式只读取 `stdin`,加锁写入 JSONL 并立即退出,不初始化 UI,失败也不能阻断 Codex。Handler 超时按事件从 `hookTimeoutSeconds(for:)` 取得,`SessionEnd` 为 3 秒,其他事件为 5 秒。普通模式由 `CodexBarAppDelegate` 统一装配长期服务。-工程默认采用 `MainActor` 隔离. UI, Controller, ViewModel 和 Settings 依赖默认隔离, 共享可变状态放入 actor, DTO 和跨 actor 值类型按需添加 `nonisolated` 标记, 禁止在主 actor 执行阻塞 I/O. 类型命名使用 `UpperCamelCase` 风格, 成员命名使用 `lowerCamelCase` 风格. 注释只解释非显然的生命周期, 焦点, actor 或系统 API 约束+工程默认采用 `MainActor` 隔离。UI, Controller, ViewModel 和 Settings 依赖默认隔离,共享可变状态放入 actor,DTO 和跨 actor 值类型按需添加 `nonisolated` 标记,禁止在主 actor 执行阻塞 I/O。类型命名使用 `UpperCamelCase` 风格,成员命名使用 `lowerCamelCase` 风格。注释只解释非显然的生命周期、焦点、actor 或系统 API 约束。-保持三条数据链路独立: app-server 额度与用量, Hook 历史聚合, `CodexActivityMonitor` 实时任务; helper 只能控制睡眠, 不得增加网络, 任意命令执行或额外文件访问; 修改 Hook 配置时必须保留用户和其他应用已有的 handler; 启用和校验 Hook 必须检查当前 app-server 的实际版本不低于 `0.145.0`; 新增网络访问, 日志数据或 CloudKit 字段前先核对隐私边界+保持三条数据链路独立:app-server 额度与用量、Hook 历史聚合、`CodexActivityMonitor` 实时任务。helper 只能控制睡眠,不得增加网络、任意命令执行或额外文件访问。修改 Hook 配置时必须保留用户和其他应用已有的 handler。启用和校验 Hook 必须检查当前 app-server 的实际版本不低于 `0.145.0`。新增网络访问、日志数据或 CloudKit 字段前先核对隐私边界。-缺少 session ID 的 Hook 事件使用匿名 project key. 匿名任务保留在实时快照和 UI 中, 活动卡片与任务中心统一显示橙色 `person.crop.circle.dashed` 图标, help 为 `匿名任务不参与防睡眠`; 不发布任务通知或触觉反馈, 不参与防睡眠和异常会话保护, 不生成保护状态持久化标识. 活动卡片的 `+N` 只显示其他活跃任务总数+缺少 session ID 的 Hook 事件使用匿名 project key。匿名任务保留在实时快照和 UI 中,活动卡片与任务中心统一显示橙色 `person.crop.circle.dashed` 图标,`help` 为 `匿名任务不参与防睡眠`。匿名任务不发布任务通知或触觉反馈,不参与防睡眠和异常会话保护,不生成保护状态持久化标识。活动卡片的 `+N` 只显示其他活跃任务总数。-`CodexActivityMonitor` 的异常会话保护跟随防睡眠主开关, 只判定非匿名运行中任务, 等待批准任务不参与判定. 静默阈值可选 30 分钟, 1, 2 或 4 小时, 默认 1 小时. Hook bootstrap, 系统睡眠, 唤醒恢复或 Hook 数据源不可用期间必须暂停判定, 数据恢复后统一无通知对账+`CodexActivityMonitor` 的异常会话保护跟随防睡眠主开关,只判定非匿名运行中任务,等待批准任务不参与判定。静默阈值可选 30 分钟, 1, 2 或 4 小时,默认 1 小时。Hook bootstrap、系统睡眠、唤醒恢复或 Hook 数据源不可用期间必须暂停判定,数据恢复后统一无通知对账。-`HookEventTailReader.drainNow()` 是读取屏障, 每个调用方必须等待一轮在本次请求之后开始的读取. 系统唤醒只有在该轮读取成功后才执行 rollout 生命周期对账并恢复异常会话保护判定; reader 更换时丢弃旧结果, 数据源不可用或任务取消时不得使用旧快照继续判定+`HookEventTailReader.drainNow()` 是读取屏障,每个调用方必须等待一轮在本次请求之后开始的读取。系统唤醒只有在该轮读取成功后才执行 rollout 生命周期对账并恢复异常会话保护判定。reader 更换时丢弃旧结果,数据源不可用或任务取消时不得使用旧快照继续判定。-异常会话保护记录由 `ActivityProtectionStateStore` 保存在 `~/Library/Application Support/CodexBar/ActivityProtection/state.json`, 只包含哈希任务标识和时间戳, 最长保留到最后进展后的 24 小时. Debug 与 Release 通过 `flock` 共用该文件, 当前 schema 为 1; 修改格式或身份计算属于兼容性问题+异常会话保护记录由 `ActivityProtectionStateStore` 保存在 `~/Library/Application Support/CodexBar/ActivityProtection/state.json`,只包含哈希任务标识和时间戳,最长保留到最后进展后的 24 小时。Debug 与 Release 通过 `flock` 共用该文件,当前 schema 为 `1`。修改格式或身份计算属于兼容性问题。-需要从原始 Hook 事件重新计算的聚合算法, 输出字段, 字段含义或去重规则变化时必须递增 `WorkflowMaintenanceState.currentAggregationSchema`, 统一从保留期内的原始 JSONL 完整重建, 不新增字段级历史迁移. Hook 计数字段缺失表示历史来源不可用, 不能解码成明确的 0+需要从原始 Hook 事件重新计算的聚合算法、输出字段、字段含义或去重规则变化时,必须递增 `WorkflowMaintenanceState.currentAggregationSchema`,统一从保留期内的原始 JSONL 完整重建,不新增字段级历史迁移。Hook 计数字段缺失表示历史来源不可用,不能解码成明确的 `0`## 测试规范-仓库没有 XCTest target 或覆盖率门槛. 每次改动至少应完成构建, 运行 `swiftformat` 和 `swiftlint` 两项检查, 并手动验证受影响流程. 菜单, 窗口焦点, Hook, 同步, 通知和防睡眠改动必须说明手动验证场景. Debug 与 Release 使用不同 App 和 helper bundle ID, 排查时不要混用+仓库没有 XCTest target 或覆盖率门槛。每次改动至少应完成构建,运行 `swiftformat` 和 `swiftlint` 两项检查,并手动验证受影响流程。菜单、窗口焦点、Hook、同步、通知和防睡眠改动必须说明手动验证场景。Debug 与 Release 使用不同 App 和 helper bundle ID,排查时不要混用。## Git 规范-不要主动 push, 不要回滚, 覆盖或丢弃他人的未提交修改. 用户只要求提交时, 不要顺带格式化或修改文件+不要主动 push,不要回滚、覆盖或丢弃他人的未提交修改。用户只要求提交时,不要顺带格式化或修改文件。-提交标题使用 `<type>: <中文描述>` 格式+提交标题使用 `<type>: <中文描述>` 格式:- 常用 type 包括 `feat` `fix` `chore` `refactor` `docs`-- message 里不要出现版本号或发布字样, 只描述改动本身, 版本信息由 tag 承载+- message 里不要出现版本号或发布字样,只描述改动本身,版本信息由 tag 承载- 修复和发布提交需要 body- 标题与 body 之间空一行-- body 中的 bullet 连续排列, 每条缩进 4 个空格-- commit message 中不要出现版本号, Release 标记或其他发布版本相关内容+- body 中的 bullet 连续排列,每条缩进 4 个空格+- commit message 中不要出现版本号,Release 标记或其他发布版本相关内容-Tag 名 `v{MARKETING_VERSION}` 里的版本号从 `Config/Version.xcconfig` 读取, 使用附注 tag `git tag -a v3.x.y -m "Release v3.x.y"`+Tag 名 `v{MARKETING_VERSION}` 里的版本号从 `Config/Version.xcconfig` 读取,使用附注 tag `git tag -a v3.x.y -m "Release v3.x.y"`## 代码修改原则-- 优先结合现有文件结构和类型职责, 不为小改动新建抽象-- 改 shared controller, shared service, 模型解析或持久化 key 时, 要考虑旧数据和降级路径; 用户设置要保持默认值; 持久化 key 和旧版本迁移兼容-- **任何兼容性问题都必须主动询问用户, 不要自行决定**; 只要改动会影响新旧共存就适用, 不限于旧数据迁移或丢弃, 持久化 key 改名或改结构, 老版本升上来的降级路径, 最低系统版本与 API 可用性取舍, 云端记录格式变更; 先说清影响面和几种做法的代价, 等用户选定再动手-- 处理窗口, 菜单, 快捷键, App 激活或事件监听时, 特别注意 `LSUIElement` 应用特有的焦点行为-- 注释保持克制, 只解释非显然的生命周期, 焦点, actor 或系统 API 约束; 现有注释多为解释为什么的类型, 沿用同样风格-- 改动涉及菜单面板, 窗口焦点, Hook, 同步, 通知或防睡眠时, 构建通过之外还要说明应手动覆盖的交互场景; 防睡眠额外要验证 App 包内 helper 与 plist 位置, 签名, 首次系统授权, 运行/等待切换和异常退出后的恢复+- 优先结合现有文件结构和类型职责,不为小改动新建抽象+- 改 shared controller、shared service、模型解析或持久化 key 时,要考虑旧数据和降级路径;用户设置要保持默认值;持久化 key 和旧版本迁移兼容+- **任何兼容性问题都必须主动询问用户,不要自行决定**;只要改动会影响新旧共存就适用,不限于旧数据迁移或丢弃、持久化 key 改名或改结构、老版本升上来的降级路径、最低系统版本与 API 可用性取舍、云端记录格式变更;先说清影响面和几种做法的代价,等用户选定再动手+- 处理窗口、菜单、快捷键、App 激活或事件监听时,特别注意 `LSUIElement` 应用特有的焦点行为+- 注释保持克制,只解释非显然的生命周期、焦点、actor 或系统 API 约束;现有注释多为解释为什么的类型,沿用同样风格+- 改动涉及菜单面板、窗口焦点、Hook、同步、通知或防睡眠时,构建通过之外还要说明应手动覆盖的交互场景;防睡眠额外要验证 App 包内 helper 与 plist 位置、签名、首次系统授权、运行/等待切换和异常退出后的恢复diff --git a/CLAUDE.md b/CLAUDE.mdindex 1494fe4..1b083e8 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -4,23 +4,41 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co## 写作风格-本仓库的中文文本 (提交信息, 代码注释, 文档) 统一遵守+代码、代码注释和项目文档使用彼此独立的规则,不得把一类内容的标点约定直接套用到另一类内容。提交信息由 Git 规范单独约束。-- 禁止使用中文标点, 一律使用半角标点-- 句中停顿和并列项使用空格或者逗号, 顿号的位置也用空格或者逗号-- 分号只用来断开完整句子, 相当于句号; 拿不准就把它换成句号读一遍, 两边都能独立成句才保留+### 代码和注释++代码和注释统一遵守:++- 禁止使用中文标点,一律使用半角标点+- 句中停顿和并列项使用空格或者逗号,顿号的位置也用空格或者逗号+- 分号只用来断开完整句子,相当于句号;拿不准就把它换成句号读一遍,两边都能独立成句才保留- 行末禁止使用标点-- 行内标点后如果还有文字, 间隔一个英文空格-- 行内代码后尽量不要紧跟标点, 需要断句时补一个词或者使用空格再断-- 一条 bullet 只讲一件事, 需要两个以上完整句子时拆成多条+- 行内标点后如果还有文字,间隔一个英文空格+- 注释中引用类型、成员、参数或命令后尽量不要紧跟标点,需要断句时补一个词或者使用空格再断+- 一个注释段只解释一件事,需要说明多个独立主题时拆成多个注释段++### 项目文档++项目文档统一遵守:++- 代码标识符、命令、路径、配置键、原始字段值和需要精确复制的版本号使用行内代码+- 中文正文使用全角中文标点,包括 `,` `。` `;` `:` `!` `?` `“”` 和 `()`+- 中文短词或短语的并列使用 `、`;能独立表达语义的分句使用 `,`,两边都能独立成句时才考虑 `;`+- 中文标点前后不加空格;中文与英文、数字或行内代码之间按词语边界保留一个半角空格+- 不机械替换特殊内容中的英文标点。数字序列、行内代码序列或英文术语并列时,如果英文标点观感更好,使用英文标点并在其后保留一个半角空格+- 普通正文行末使用与语义匹配的中文标点;引出列表、表格或代码块的正文使用 `:`+- 标题、独立列表项、编号项和表格单元格行末不加标点+- 如果一行以 Markdown 格式的链接或行内代码结尾,后面不加任何标点;链接或行内代码位于句中时仍按句子结构使用中文标点+- Markdown 语法、代码块、命令、路径、URL、版本号和程序标识符内部的符号保持原样## 项目概述-CodexBar 是一个 macOS 菜单栏应用, 以 `LSUIElement` 方式运行, 没有 Dock 图标, 展示本机 Codex 的账号状态, 额度, Token 用量, 实时任务和工作流统计; 技术栈 Swift 6 + SwiftUI + AppKit + MVVM, 唯一外部依赖是 Sparkle 2.9.3+ (SwiftPM); 最低系统版本 macOS 15.0+CodexBar 是一个 macOS 菜单栏应用,以 `LSUIElement` 方式运行,没有 Dock 图标,展示本机 Codex 的账号状态、额度、Token 用量、实时任务和工作流统计。技术栈为 Swift 6 + SwiftUI + AppKit + MVVM,唯一外部依赖是 Sparkle `2.9.3+`(SwiftPM)。最低系统版本为 macOS `15.0`-Xcode 工程有两个 target: 主 App `CodexBar` 和随 App 嵌入的 root helper `CodexBarHelper` (command-line tool + LaunchDaemon); **没有测试 target**, 验证靠构建通过 + 实际运行+Xcode 工程有两个 target:主 App `CodexBar` 和随 App 嵌入的 root helper `CodexBarHelper`(command-line tool + LaunchDaemon)。**没有测试 target**,验证依靠构建通过和实际运行。-App Sandbox 未开启, entitlements 只声明 iCloud/CloudKit, 因为需要启动本机 `codex` 进程, 读取用户 Codex 登录状态, 写入用户级 Hook 配置+App Sandbox 未开启,entitlements 只声明 iCloud/CloudKit,因为需要启动本机 `codex` 进程、读取用户 Codex 登录状态、写入用户级 Hook 配置。## 常用命令@@ -53,26 +71,26 @@ Scripts/appcast.sh # sign_update 签名并写入 appcast.xmlScripts/cleanup.swift --help```-日常调试直接 `open CodexBar.xcodeproj` 用 Xcode 跑 Debug scheme; 注意 Debug 产物用的是 `app.zabrian.codexbar.debug` 这个 bundle ID, 与 Release 安装版可以共存, 排查防睡眠问题时要确认自己看的是哪一套 helper+日常调试直接用 `open CodexBar.xcodeproj` 在 Xcode 中运行 Debug scheme。Debug 产物使用 `app.zabrian.codexbar.debug` 这个 bundle ID,与 Release 安装版可以共存,排查防睡眠问题时要确认自己查看的是哪一套 helper。-`Scripts/build.sh` 会先清空 `Build/` 目录, 成功后只留最终产物 `.app` 文件; 凭据推荐用 keychain profile, 先跑一次 `xcrun notarytool store-credentials "codexbar-notary" --apple-id "<Apple ID>" --team-id "<Team ID>"` 存好, 之后构建加上 `--notary-profile codexbar-notary`+`Scripts/build.sh` 会先清空 `Build/` 目录,成功后只保留最终的 `.app` 文件。凭据推荐使用 keychain profile,先运行一次 `xcrun notarytool store-credentials "codexbar-notary" --apple-id "<Apple ID>" --team-id "<Team ID>"` 保存凭据,之后构建时加上 `--notary-profile codexbar-notary`-Debug 与 Release 使用不同 bundle ID, 分别是 `app.zabrian.codexbar.debug` 与 `app.zabrian.codexbar` 两个, helper 相应带 `.debug.helper` 与 `.helper` 后缀, 所以 `CodexBarHelper/` 下有两份 LaunchDaemon plist, `cleanup.swift` 也需要同时处理两套+Debug 与 Release 使用不同 bundle ID,分别是 `app.zabrian.codexbar.debug` 与 `app.zabrian.codexbar`。helper 相应带 `.debug.helper` 与 `.helper` 后缀,所以 `CodexBarHelper/` 下有两份 LaunchDaemon plist,`cleanup.swift` 也需要同时处理两套。## Git 规则-- 不要主动 push, 除非用户明确要求-- 不要回滚, 覆盖或丢弃不是你产生的未提交改动, 工作树可能是脏的-- 被要求提交时, **禁止**顺带修改任何文件内容: 不格式化, 不清理, 不补文档, 只把当前已有改动原样提交+- 不要主动 push,除非用户明确要求+- 不要回滚、覆盖或丢弃不是你产生的未提交改动,工作树可能是脏的+- 被要求提交时,**禁止**顺带修改任何文件内容:不格式化、不清理、不补文档,只把当前已有改动原样提交-Commit message: Conventional Commits 前缀 + 中文标题, 需要 body 时空一行后写 4 空格缩进 bullet+Commit message 使用 Conventional Commits 前缀和中文标题,需要 body 时空一行后写 4 空格缩进 bullet:-- 标题写成 `<type>: <中文描述>` 的形式, 不加句号; 常用 type 有 `feat` `fix` `chore` `refactor` `docs`-- message 里不要出现版本号或发布字样, 只描述改动本身, 版本信息由 tag 承载-- 功能 修复 发布类提交必须写 body; 简单文档或杂项可只写标题行-- body 中多条 bullet 连续排列, bullet 之间不空行-- 命令行提交时把完整 body 放进同一个 `-m` 参数或改用 `git commit -F` 传文件, 不要为每条 bullet 单独 `-m`-- message 中禁止使用中文标点, 行末禁止使用标点, 行内标点后如果有文字则间隔一个英文空格+- 标题写成 `<type>: <中文描述>` 的形式,不加句号;常用 type 有 `feat`、`fix`、`chore`、`refactor`、`docs`+- message 里不要出现版本号或发布字样,只描述改动本身,版本信息由 tag 承载+- 功能、修复、发布类提交必须写 body;简单文档或杂项可只写标题行+- body 中多条 bullet 连续排列,bullet 之间不空行+- 命令行提交时把完整 body 放进同一个 `-m` 参数或改用 `git commit -F` 传文件,不要为每条 bullet 单独 `-m`+- message 中禁止使用中文标点,行末禁止使用标点,行内标点后如果有文字则间隔一个英文空格```textfix: 修复 Codex 状态刷新@@ -81,245 +99,245 @@ fix: 修复 Codex 状态刷新- 保留当前运行版本与磁盘安装版本不一致时的更新提示```-Tag 名 `v{MARKETING_VERSION}` 里的版本号从 `Config/Version.xcconfig` 读取, 使用附注 tag `git tag -a v3.x.y -m "Release v3.x.y"`+Tag 名 `v{MARKETING_VERSION}` 里的版本号从 `Config/Version.xcconfig` 读取,使用附注 tag `git tag -a v3.x.y -m "Release v3.x.y"`## 架构-### 启动分流 (关键设计)+### 启动分流(关键设计)`CodexBar/App/CodexBarApp.swift` 的 `init()` 最先调用 `WorkflowHookEventRecorder.handleIfRequested()`-- 带 `--hook-event` 启动 -> **Hook 子进程模式**: 从 stdin 读 JSON payload, 在 `flock` 锁内追加一行 JSONL 后立即 `exit(EXIT_SUCCESS)` 退出, 绝不初始化菜单栏 UI; 写入失败静默吞掉, 不阻断 Codex-- Hook handler 超时统一由 `WorkflowHookEventRecorder.hookTimeoutSeconds(for:)` 提供, `SessionEnd` 是 3 秒, 其他事件是 5 秒; 等锁预算固定比对应事件超时少 2 秒, 当前分别是 1 秒和 3 秒-- 普通启动 -> `CodexBarAppDelegate` 创建全部长期对象, 它在 `Controllers/StatusItemController.swift` 内, 再由 `StatusItemController.install()` 装配菜单栏; AppDelegate 是唯一的装配点, 新增服务在这里注入+- 带 `--hook-event` 启动 -> **Hook 子进程模式**:从 `stdin` 读取 JSON payload,在 `flock` 锁内追加一行 JSONL 后立即调用 `exit(EXIT_SUCCESS)` 退出,绝不初始化菜单栏 UI;写入失败时静默吞掉,不阻断 Codex+- Hook handler 超时统一由 `WorkflowHookEventRecorder.hookTimeoutSeconds(for:)` 提供,`SessionEnd` 是 3 秒,其他事件是 5 秒;等锁预算固定比对应事件超时少 2 秒,当前分别是 1 秒和 3 秒+- 普通启动 -> `CodexBarAppDelegate` 创建全部长期对象,它在 `Controllers/StatusItemController.swift` 内,再由 `StatusItemController.install()` 装配菜单栏;AppDelegate 是唯一的装配点,新增服务在这里注入### 三条数据链路-**链路一: app-server (额度/用量)**+**链路一:app-server(额度/用量)**-`CodexStatusService` (actor) -> `CodexCLIResolver` 解析 `codex` 可执行文件, PATH 全局优先, 回退 `/Applications/ChatGPT.app` 或 `Codex.app` 内置 -> 启动 `codex app-server --listen stdio://` -> `AppServerSession` 做 stdio JSON-RPC -> 合成 `CodexQuotaSnapshot` -> `CodexStatusViewModel` 发布给 UI+`CodexStatusService`(actor) -> `CodexCLIResolver` 解析 `codex` 可执行文件,PATH 全局优先,回退 `/Applications/ChatGPT.app` 或 `Codex.app` 内置 -> 启动 `codex app-server --listen stdio://` -> `AppServerSession` 执行 stdio JSON-RPC -> 合成 `CodexQuotaSnapshot` -> `CodexStatusViewModel` 发布给 UI-- 刷新间隔 60 秒, 请求超时 20 秒, 连接最长复用 1 小时, 让后台升级的 codex 二进制有机会生效-- 主要方法有 `initialize` `account/read` `account/rateLimits/read` `account/usage/read` `config/read` `config/batchWrite` `hooks/list`-- `SIGPIPE` 被忽略, app-server 退出后写管道由 write 抛错走重建路径-- stdout 可能混有无关日志行, `AppServerSession` 先用轻量 `RPCIDEnvelope` 匹配 id 再完整解码+- 刷新间隔为 60 秒、请求超时为 20 秒,连接最长复用 1 小时,让后台升级的 `codex` 二进制有机会生效+- 主要方法有 `initialize`、`account/read`、`account/rateLimits/read`、`account/usage/read`、`config/read`、`config/batchWrite`、`hooks/list`+- `SIGPIPE` 被忽略,app-server 退出后写管道由 write 抛错走重建路径+- `stdout` 可能混有无关日志行,`AppServerSession` 先用轻量 `RPCIDEnvelope` 匹配 `id`,再完整解码-**链路二: Hook 统计 (历史聚合)**+**链路二:Hook 统计(历史聚合)**-Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/events/YYYY-MM-DD.jsonl` 这类文件, 主 App 的 `WorkflowService` (actor) 增量聚合出 `daily.jsonl` 与 `WorkflowSnapshot` 供热力图详情面板展示; 可选跨设备同步由 `WorkflowSyncScheduler` (唯一调度者) 与 `WorkflowSyncService` 负责, 走 `iCloud.app.zabrian.codexbar` 容器的 CloudKit private database, 只上传脱敏 daily 聚合+Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/events/YYYY-MM-DD.jsonl` 这类文件,主 App 的 `WorkflowService`(actor)增量聚合出 `daily.jsonl` 与 `WorkflowSnapshot`,供热力图详情面板展示。可选跨设备同步由 `WorkflowSyncScheduler`(唯一调度者)与 `WorkflowSyncService` 负责,使用 `iCloud.app.zabrian.codexbar` 容器的 CloudKit private database,只上传脱敏 daily 聚合。-- `WorkflowStorage` 管理的存储目录含 `events/` `daily.jsonl` `stats.lock` `maintenance.json` `Sync/` 五项-- 原始事件文件与 daily 聚合统一保留 210 天, 聚合里的会话与轮次标识只保留 3 天, 到期后只留下去重计数-- `WorkflowDailyAccumulator` 的全量与增量路径始终在内存收集完整 ID, 只有 `finalized(identifierStorage:)` 才决定保留或压缩; 已压缩的日期收到新事件时不能安全去重, 必须降级为从原始 JSONL 完整重建-- `WorkflowMaintenanceState.currentAggregationSchema` 是原始事件到 daily 聚合的算法版本; 缺少版本按 0 处理, 版本不一致时把仍有原始事件的日期全部标脏并走通用完整重建, 不写字段级历史迁移-- 需要从原始事件重新计算的聚合算法, 输出字段, 字段含义或去重规则变化时必须递增 `currentAggregationSchema`, 统一走相同的完整重建入口-- daily 与 CloudKit 中的 Hook 计数字段都是可选值; `nil` 表示来源版本没有提供或无法确认, 明确的 `0` 才表示已知没有对应事件, 解码和重建都不能把两者混为一谈+- `WorkflowStorage` 管理的存储目录含 `events/`、`daily.jsonl`、`stats.lock`、`maintenance.json`、`Sync/` 五项+- 原始事件文件与 daily 聚合统一保留 210 天,聚合里的会话与轮次标识只保留 3 天,到期后只留下去重计数+- `WorkflowDailyAccumulator` 的全量与增量路径始终在内存收集完整 ID,只有 `finalized(identifierStorage:)` 才决定保留或压缩;已压缩的日期收到新事件时不能安全去重,必须降级为从原始 JSONL 完整重建+- `WorkflowMaintenanceState.currentAggregationSchema` 是原始事件到 daily 聚合的算法版本;缺少版本按 0 处理,版本不一致时把仍有原始事件的日期全部标脏并走通用完整重建,不写字段级历史迁移+- 需要从原始事件重新计算的聚合算法、输出字段、字段含义或去重规则变化时,必须递增 `currentAggregationSchema`,统一走相同的完整重建入口+- daily 与 CloudKit 中的 Hook 计数字段都是可选值;`nil` 表示来源版本没有提供或无法确认,明确的 `0` 才表示已知没有对应事件,解码和重建都不能把两者混为一谈-**链路三: 实时任务, 由 `CodexActivityMonitor` 驱动**+**链路三:实时任务,由 `CodexActivityMonitor` 驱动**-`CodexActivityMonitor` 是菜单栏图标, 活动卡片, 通知, 触觉反馈和防睡眠的**唯一任务状态来源**, 由两个 reader 供料+`CodexActivityMonitor` 是菜单栏图标、活动卡片、通知、触觉反馈和防睡眠的**唯一任务状态来源**,由两个 reader 供料。-- `HookEventTailReader` (actor) 的 bootstrap 覆盖滚动 24 小时并作为单次事务发送, 之后按当日文件 offset 增量 tail, 同时向下游报告数据源健康状态-- `CodexSessionLifecycleReader` (actor) 增量读取 `~/.codex/sessions` 与 `archived_sessions` 下的 rollout JSONL, 只提取 turn 生命周期与最近进展时间, 不解码会话或工具内容-- 任务监控只在 `codexHookSettings.isOperable` 为 true 时运行, 即本地已安装且最近一次明确校验没有失败; 链路失效时立即停 reader 并清空实时状态-- `SessionEnd` 没有 `turn_id`, 收到后按 session 把对应任务立即移出活跃列表并放进 5 秒终态确认窗口; rollout 在窗口内补回准确的完成或终止分类, 超时后按终止处理-- `HookEventTailReader.drainNow()` 是读取屏障, 每个调用方等待一轮在本次请求之后开始的读取, 返回 `completed` `sourceUnavailable` 或 `cancelled`-- 缺少 session ID 的 Hook 事件使用匿名 project key, `isAnonymous` 会保留到活动快照, 完成记录和终止记录; 活动卡片和任务中心显示橙色 `person.crop.circle.dashed` 图标, help 为 `匿名任务不参与防睡眠`, `+N` 只显示其他活跃任务总数-- 匿名任务不向通知消费者发布等待或完成 transition, 不触发触觉反馈, 不参与 KeepAlive 或异常会话保护, `activityProtectionIdentifier` 为 nil+- `HookEventTailReader`(actor)的 bootstrap 覆盖滚动 24 小时并作为单次事务发送,之后按当日文件 offset 增量 tail,同时向下游报告数据源健康状态+- `CodexSessionLifecycleReader`(actor)增量读取 `~/.codex/sessions` 与 `archived_sessions` 下的 rollout JSONL,只提取 turn 生命周期与最近进展时间,不解码会话或工具内容+- 任务监控只在 `codexHookSettings.isOperable` 为 `true` 时运行,即本地已安装且最近一次明确校验没有失败;链路失效时立即停 reader 并清空实时状态+- `SessionEnd` 没有 `turn_id`,收到后按 session 把对应任务立即移出活跃列表并放进 5 秒终态确认窗口;rollout 在窗口内补回准确的完成或终止分类,超时后按终止处理+- `HookEventTailReader.drainNow()` 是读取屏障,每个调用方等待一轮在本次请求之后开始的读取,返回 `completed`、`sourceUnavailable` 或 `cancelled`+- 缺少 session ID 的 Hook 事件使用匿名 project key,`isAnonymous` 会保留到活动快照、完成记录和终止记录;活动卡片和任务中心显示橙色 `person.crop.circle.dashed` 图标,`help` 为 `匿名任务不参与防睡眠`,`+N` 只显示其他活跃任务总数+- 匿名任务不向通知消费者发布等待或完成 transition,不触发触觉反馈,不参与 KeepAlive 或异常会话保护,`activityProtectionIdentifier` 为 `nil`-系统唤醒时 `NSWorkspace.didWakeNotification` 先暂停异常会话保护. 读取屏障成功时重置生命周期解析回退并完成 rollout 对账后恢复判定; 数据源不可用时继续由 source health 门槛暂停, reader generation 变化时旧结果直接丢弃+系统唤醒时,`NSWorkspace.didWakeNotification` 先暂停异常会话保护。读取屏障成功时重置生命周期解析回退,并在完成 rollout 对账后恢复判定;数据源不可用时继续由 source health 门槛暂停,reader generation 变化时直接丢弃旧结果。#### 异常会话保护-- `CodexActivityProtection.swift` 管理异常会话保护状态机, `ActivityProtectionSettings` 只保存静默阈值; 保护开关跟随用户保存的 KeepAlive 主开关, 不依赖 helper 是否已获系统授权-- 静默阈值可选 30 分钟, 1, 2 或 4 小时, 默认 1 小时, UserDefaults key 固定为 `KeepAlive.abnormalTaskInactivitySeconds`-- 候选只包含非匿名 `.running` 任务, `.waitingApproval` 不参与异常判定; `lastProgressAt` 同时吸收 Hook 顶层事件, 子 Agent 事件与 rollout 行时间-- 达到阈值后先持久化候选记录并尝试提交本地通知, 通知使用系统默认声音且不重试; 最多等待 3 秒后无论通知是否提交成功都隐藏任务-- 通知以 task ID 与 attempt ID 共同标识, 候选失效或任务恢复, 终止, 完成, 过期时会撤回仍可识别的待处理和已送达通知; 迟到的提交结果不得影响新的 attempt-- 隐藏任务不进入 `CodexActivitySnapshot` 的运行中与等待批准列表, 因而不参与 UI 和 KeepAlive 的活跃任务计算; 后续进展会恢复任务并清除保护记录-- KeepAlive 关闭时恢复当前进程内所有隐藏任务并撤回通知, 已经隐藏任务的持久化记录保留; 再次开启后按当前阈值和最近进展时间无通知对账-- 判定要求监控已启动, KeepAlive 已开启, reader 存在, bootstrap 已结束, 不在睡眠或唤醒恢复阶段且 Hook 数据源健康; 进入不满足条件的阶段时会取消计时器和在途通知 attempt-- 静默定时器使用 `SuspendingClock`, 系统时间变化由 `NSSystemClockDidChange` 触发无通知重算; 系统睡眠期间暂停判定, 唤醒完成 Hook 读取和 rollout 对账后再恢复-- `ActivityProtectionStateStore` 把记录写入 `~/Library/Application Support/CodexBar/ActivityProtection/state.json`, 字段只有 SHA-256 任务标识与 `lastProgressAt` `markedAt` `expiresAt`, 最长保留到最后进展后的 24 小时-- Debug 与 Release 共用状态文件, actor 串行化进程内访问, `flock` 保护跨进程读写, 文件权限固定为 `0600`, 当前 schema 为 1; 状态在 task reader 启动前完成加载-- 持久化操作按 `activityProtectionPersistenceTask` 串行排队, 条件删除用 `markedAt` 防止旧 attempt 删除新记录, 终态与保留期清理执行无条件删除--### 防睡眠 (KeepAlive) 与 root helper--两套机制叠加, 职责不同--- `SystemSleepService` 用进程内 `IOPMAssertion` 建立 `PreventUserIdleSystemSleep` 断言, 只挡空闲睡眠, 不需要提权; 断言名必须是 ASCII, 否则 `pmset -g assertions` 显示不出标识-- `CodexBarHelper` 是 root LaunchDaemon, 通过 XPC 接受 `setSleepPreventionRequested` 请求, 执行 `/usr/bin/pmset -a disablesleep` 覆盖合盖睡眠--链路: `KeepAliveController` (MainActor) 订阅 `activityMonitor.$snapshot` 以及合成 `codexHookSettings.isOperable` 的两个发布值 -> `SMAppService.daemon(plistName:)` 注册 -> `NSXPCConnection` -> helper--关键约束--- `shouldDisableSleep` 是用户意图与依赖可用性的唯一汇合点, 要求 `isStarted && !isPreparingForTermination && isEnabled && isHookEnabled && hasRunningTasks && helperStatus == .enabled && !isRefreshingHelper && !isLowBatteryActive && !hasReachedMaximumDuration` 同时成立; **依赖不满足只让效果失效, 绝不回写用户保存的 `isEnabled`**-- `hasRunningTasks` 只消费 `CodexActivitySnapshot` 中非匿名且仍可见的运行中任务与按设置纳入的等待批准任务, 被异常会话保护隐藏的任务也不参与防睡眠-- Hook 状态在类内只认 `isHookEnabled` 这份镜像, 它跟的是 `codexHookSettings.isOperable`; 不要回读那个属性, 订阅回调跑在 `willSet`, 那一刻它的两个输入里正在变的那一项还是旧值, 只能认 `CombineLatest` 给的闭包参数-- 新增拦截条件一律加进 `sleepBlockReason` 的顺序判断里, 它和 `shouldDisableSleep` 同源, 顺带保证日志的 `reason=` 不会漏项-- UI 用的 `isLowBatteryBlocking` 与 `canShowOptions` 由 `reconcileSleepState` 从 `sleepBlockReason` 单点派生, 新增拦截条件时 `allowsOptions` 那个穷举 `switch` 会强制表态, 于是不会出现入口亮着却点不动-- `hasRunningTasks` 与 `isRefreshingHelper` 都不带 `@Published` 标注, 它们变得比结论频繁, 各自发信号会把整个设置页拖着一起重算-- helper 只做一件事; 不要给 root helper 增加网络, 任意命令执行或其他文件访问能力-- 调用方校验由 XPC 层强制; helper 启动时用 `SecCodeCopySelf` 读自身签名, 拼出形如 `anchor apple generic and certificate leaf[subject.OU] = "<team>" and identifier "<主 App identifier>"` 的 requirement 字符串, 交给 `NSXPCListener.setConnectionCodeSigningRequirement` 生效; 没有逐次连接的 audit token 检查, 改签名或改 bundle ID 会直接连不上-- 所有权记录固定放在 `/Library/Application Support/CodexBar/sleep-ownership.json`, 由 root 在同目录写临时文件, 完成 `F_FULLFSYNC` 后原子替换并同步目录, 权限固定为 `0600`; 只持久化 `idle` `owned` `restoring` 三态, `external` 只是任务期间的运行态, 不落盘也不承担恢复责任-- 当前值为 0 时必须先写 `owned` 再写 `pmset 1`; 释放时必须先写 `restoring` 再写 `pmset 0`; 两次 pmset 都要重新读取 `pmset -g` 确认实际值, 只有确认为 0 才能记回 `idle`-- 任务开始时实际值已为 1 就返回 `external`, 不写 pmset; helper 每 5 秒观察一次, 如果其他来源在任务期间改回 0, helper 立即按上一条顺序取得所有权-- helper 取得所有权后每 5 秒检查一次实际值与磁盘 transaction, 值被改成 0 时重新写回 1, 记录缺失, 损坏或 transaction 不一致时先修复记录; 修复失败也必须继续尝试恢复为 0-- 没有活跃租约时停止短轮询, 只保留 60 秒异常恢复检查; 所有短轮询使用 1 秒 leeway-- 每个 App 进程持有一个跨 XPC 重连不变的 client session ID, 请求再带单调递增的 generation; helper 只释放对应进程的租约并拒绝延迟到达的旧 generation, 不允许旧连接覆盖新状态-- 异常断连后租约宽限 15 秒; 同一 App 在宽限内重连会续上原租约, watchdog 只会释放仍处于断连状态的那一个 client session-- helper 以 `owned` 或 `restoring` 启动时先恢复为 0 再接受新接管; 以 `idle` 启动时不修改当前值, 因为那个值可能属于其他来源-- 更新 helper 前 App 先释放自己的租约, helper 原子确认全局没有活跃客户端且所有权为 `idle`, 再用短期更新准备锁拒绝新的接管; 注册新 helper 后必须收到状态查询回复才记录新指纹, 系统仍在等待首次批准时除外-- 切换失败按 2/4/8...256 秒重试, 列表耗尽即放弃 (延时累计约 8.5 分钟, 每轮再等一次超时约 10 分钟), 瞬时抖动能自愈, 权限类故障不该无限重试-- XPC 请求带超时并汇进同一条重试路径; launchd 拉不起 helper 时 XPC 方法既不回复也不触发 errorHandler, 没有它界面会显示防睡眠开着而实际没生效, 日志里只剩没有配对回复的 `Helper XPC 请求已发送`-- 超时取值放在 `CodexBarHelperIPC.requestTimeoutSeconds` 而不是控制器里, 它与 `watchdogGraceSeconds` 是一对: 必须更小, App 先放手 helper 才能靠 watchdog 兜底, 分处两个 module 会让人改了一边不知道另一边-- 开发期间用 `xcodebuild` 覆盖正在运行的 App bundle 会让 launchd 记的 daemon 与磁盘上的 helper 对不上, helper 从此拉不起来; 重启 App 会由 `helperRegistrationNeedsRefresh` 的指纹比对自愈, 排查时先看这一条-- helper 回传 `none` `external` `codexBar` 来源与操作后的实测值; App 只能在 `codexBar` 且实测为 0 时宣称系统睡眠已恢复或补发 `IOPMSleepSystem`, `external` 和 `none` 都只释放进程内断言-- App 退出由 `applicationShouldTerminate` 返回 `terminateLater`, 先冻结新接管并等 helper 释放回复再继续退出; helper 刷新同样先释放, 旧 helper 无响应时由新 helper 的启动恢复兜底-- `pmset` 是没有来源和引用计数的全局布尔值; CodexBar 取得所有权后如果另一个 App 也开始依赖这个 1, 释放时仍会恢复为 0, 系统层没有无歧义的方法判断另一个 App 的意图-- 低电量保护由 `PowerSourceMonitor` 供数, 它只报事实 (有没有内置电池, 电量, 是否靠电池供电), 不知道阈值; 读数保持 `unavailable` `unreadable` `present` 三态, 把读取失败折叠成"没有电池"会让设置项凭空消失且保护静默失效-- 见过一次内置电池就记住 `hasSeenBattery`, 之后读到空列表只能返回 `unreadable`; 硬件不会中途消失, 空列表只是 IOKit 重新枚举时的缺口, 当成台式机会当场撤掉保护-- `hasSeenBattery` 只活在进程内不持久化, 每次启动重新判定; 笔记本启动时撞上枚举缺口会短暂显示成没有电池, 由下一次电源通知自愈, 而持久化会让从笔记本备份恢复的台式机永远多出低电量设置项-- `IOPSNotificationCreateRunLoopSource` 注册失败时降级成 60 秒轮询并记 `action=poll`; 只靠 `didWakeNotification` 补读不够, 防睡眠生效的机器按定义就不会睡, 那条通知永远不来-- 首次读取在 `start()` 里单独判一次并记 `stage=start` 这条, 不能改走 `refresh()` 那条路: 后者按变化过滤, 而读数初始值就是 `unreadable` 本身, 首读失败会被静默吞掉, 之后只留下一条没有配对失败行的恢复日志-- 防睡眠上限累计的是**真正挡住睡眠**的那段时间, `begin` 起表 `pause` 收表, 收表之后机器睡着或被低电量拦下都不占用户的上限-- 上限计时用 `SuspendingClock` 而不是 `Date`, 后者受系统时间调整影响且系统睡眠期间照走; 排计时器的 `Task.sleep` 同样要传 `SuspendingClock`, 否则睡一夜醒来会当场判定到期-- 低电量是**纯条件**判定, 不设"低过电"的粘滞标志: 电量会回升, 充上电就该自动恢复防睡眠; `hasReachedMaximumDuration` 之所以是粘滞标志只因为累计只增不减, 两者不要照抄-- 低电量必须同时满足在用电池与电量低于阈值, 只看百分比会让"剩 5% 插上电再跑任务"当场被判低电量; 判定用 `Power Source State`, 不能用 `Is Charging` (接电停充时它也是 false)-- 电量读不到时维持上一次的判定, 从没读到过就是不触发: 误触发会当场断掉用户任务, 漏触发最坏也有系统强制睡眠兜底-- 已经在低电量保护中时读数失败不清零, 否则一次瞬时失败会绕过滞回, 让防睡眠反复开关并重发通知-- 低电量通知只在 `isActivelyPreventingSleep` 为真且来源是 `codexBar` 时排队, 外部来源不说"已恢复系统睡眠"; 日志无条件记并用 `action=release|none` 区分, 百分比只有那一条能看到-- 排队的通知要等 helper 恢复睡眠的 XPC 回复确认成功才发得出去, 恢复失败走重试直至放弃, 提前说"已恢复系统睡眠"会把用户骗去合盖然后把电耗干-- 补发 `IOPMSleepSystem` 之前还要 `await` 到通知真的提交完成, 只把提交排进下一个 MainActor job 的话同一个 job 里的补发会抢在它前面-- 那次 `await` 之后要重认一次 `generation` 再走 `finishSleepRestore` 这一步, 挂起期间可能已有新的禁用请求接管, 否则会释放掉刚建立的空闲断言-- 设置页那句低电量说明看 `isLowBatteryBlocking` 而不是 `isLowBatteryActive`, 后者在没有任务时也成立, 那时无话可说-- 触发与解除用 `阈值` 与 `阈值 + 5%` 两道门槛, 否则电量在阈值附近抖动会反复切 pmset, 合盖时还会反复补发 `IOPMSleepSystem`-- 一轮低电量通知的终点是电量回到 `阈值 + 5%` 或者用户改了阈值, 由 `hasNotifiedLowBattery` 记住; 只看是否接电会让适配器接触不良时每翻一次供电状态就重发一条-- `hasNotifiedLowBattery` 只在通知真的提交成功之后才置位, 打在入队处或提交前都会让没送达的那一条吃掉整轮配额, 使这一轮之后真正触发的低电量再也提醒不了-- `hasNotifiedLowBattery` 只管通知不管判定, 与上面"纯条件"不冲突: 电量回到解除门槛以下再跌破仍算同一轮, 不会重复提醒-- `SleepConditions` 里只放 `battery` 布尔, 放电量百分比会让每掉 1% 刷一条变化日志; 真实电量只在触发那一条单独记-- 状态只呈现在主面板活动卡片右侧的咖啡杯标记 (带 tooltip), 由 `KeepAliveController.isActivelyPreventingSleep` 驱动, `sleepPreventionSource` 区分外部来源与 CodexBar 所有权, 卡片折叠成"暂无数据"时标记要跟着一起收-- 设置页那一行说明只在异常, 外部来源, 低电量生效或达到上限时出现, CodexBar 自己正常持有所有权时整行收起, `keepAliveCaption` 返回 nil 即代表收起-- 最长防睡眠时间, 异常会话保护阈值与低电量阈值都在防睡眠子面板里, 台式机读不到电池时低电量那一行整行隐藏而不是置灰-- 保持屏幕常亮跟 `isActivelyPreventingSleep` 走, 由 `reconcileDisplayAwake` 单点切换, 于是低电量拦下, 达到上限, 任务结束时屏幕都跟着放开-- 显示断言只保证屏幕不睡, 屏保与闲置锁屏跟的是系统 idle 计时, 要靠 30 秒一次的 `IOPMAssertionDeclareUserActivity` 压住, 两者缺一不可-- 声明用户活动复用同一个 assertion ID, 每次传 null 会新建一条, `pmset -g assertions` 里会堆成一串同名断言-- 逐次声明不记日志, 建立与释放各一条就够还原状态; 两条断言都是进程级的, App 退出或崩溃时系统自动收回, 不经过 helper-- **菜单栏图标不承载防睡眠状态**, 它要保持模板渲染让系统按菜单栏外观着色, 自行着色在深浅和带染色的菜单栏下都会失控+- `CodexActivityProtection.swift` 管理异常会话保护状态机,`ActivityProtectionSettings` 只保存静默阈值;保护开关跟随用户保存的 KeepAlive 主开关,不依赖 helper 是否已获系统授权+- 静默阈值可选 30 分钟, 1, 2 或 4 小时,默认 1 小时,UserDefaults key 固定为 `KeepAlive.abnormalTaskInactivitySeconds`+- 候选只包含非匿名 `.running` 任务,`.waitingApproval` 不参与异常判定;`lastProgressAt` 同时吸收 Hook 顶层事件、子 Agent 事件与 rollout 行时间+- 达到阈值后先持久化候选记录并尝试提交本地通知,通知使用系统默认声音且不重试;最多等待 3 秒后无论通知是否提交成功都隐藏任务+- 通知以 task ID 与 attempt ID 共同标识,候选失效或任务恢复、终止、完成、过期时会撤回仍可识别的待处理和已送达通知;迟到的提交结果不得影响新的 attempt+- 隐藏任务不进入 `CodexActivitySnapshot` 的运行中与等待批准列表,因而不参与 UI 和 KeepAlive 的活跃任务计算;后续进展会恢复任务并清除保护记录+- KeepAlive 关闭时恢复当前进程内所有隐藏任务并撤回通知,已经隐藏任务的持久化记录保留;再次开启后按当前阈值和最近进展时间无通知对账+- 判定要求监控已启动、KeepAlive 已开启、reader 存在、bootstrap 已结束、不在睡眠或唤醒恢复阶段且 Hook 数据源健康;进入不满足条件的阶段时会取消计时器和在途通知 attempt+- 静默定时器使用 `SuspendingClock`,系统时间变化由 `NSSystemClockDidChange` 触发无通知重算;系统睡眠期间暂停判定,唤醒完成 Hook 读取和 rollout 对账后再恢复+- `ActivityProtectionStateStore` 把记录写入 `~/Library/Application Support/CodexBar/ActivityProtection/state.json`,字段只有 SHA-256 任务标识与 `lastProgressAt`、`markedAt`、`expiresAt`,最长保留到最后进展后的 24 小时+- Debug 与 Release 共用状态文件,actor 串行化进程内访问,`flock` 保护跨进程读写,文件权限固定为 `0600`,当前 schema 为 `1`;状态在 task reader 启动前完成加载+- 持久化操作按 `activityProtectionPersistenceTask` 串行排队,条件删除用 `markedAt` 防止旧 attempt 删除新记录,终态与保留期清理执行无条件删除++### 防睡眠(KeepAlive)与 root helper++两套机制叠加,职责不同:++- `SystemSleepService` 用进程内 `IOPMAssertion` 建立 `PreventUserIdleSystemSleep` 断言,只挡空闲睡眠,不需要提权;断言名必须是 ASCII,否则 `pmset -g assertions` 显示不出标识+- `CodexBarHelper` 是 root LaunchDaemon,通过 XPC 接受 `setSleepPreventionRequested` 请求,执行 `/usr/bin/pmset -a disablesleep` 覆盖合盖睡眠++链路:`KeepAliveController`(MainActor)订阅 `activityMonitor.$snapshot` 以及合成 `codexHookSettings.isOperable` 的两个发布值 -> `SMAppService.daemon(plistName:)` 注册 -> `NSXPCConnection` -> helper++关键约束:++- `shouldDisableSleep` 是用户意图与依赖可用性的唯一汇合点,要求 `isStarted && !isPreparingForTermination && isEnabled && isHookEnabled && hasRunningTasks && helperStatus == .enabled && !isRefreshingHelper && !isLowBatteryActive && !hasReachedMaximumDuration` 同时成立;**依赖不满足只让效果失效,绝不回写用户保存的 `isEnabled`**+- `hasRunningTasks` 只消费 `CodexActivitySnapshot` 中非匿名且仍可见的运行中任务与按设置纳入的等待批准任务,被异常会话保护隐藏的任务也不参与防睡眠+- Hook 状态在类内只认 `isHookEnabled` 这份镜像,它跟的是 `codexHookSettings.isOperable`;不要回读那个属性,订阅回调跑在 `willSet`,那一刻它的两个输入里正在变的那一项还是旧值,只能认 `CombineLatest` 给的闭包参数+- 新增拦截条件一律加进 `sleepBlockReason` 的顺序判断里,它和 `shouldDisableSleep` 同源,顺带保证日志的 `reason=` 不会漏项+- UI 用的 `isLowBatteryBlocking` 与 `canShowOptions` 由 `reconcileSleepState` 从 `sleepBlockReason` 单点派生,新增拦截条件时 `allowsOptions` 那个穷举 `switch` 会强制表态,于是不会出现入口亮着却点不动+- `hasRunningTasks` 与 `isRefreshingHelper` 都不带 `@Published` 标注,它们变得比结论频繁,各自发信号会把整个设置页拖着一起重算+- helper 只做一件事;不要给 root helper 增加网络、任意命令执行或其他文件访问能力+- 调用方校验由 XPC 层强制;helper 启动时用 `SecCodeCopySelf` 读自身签名,拼出形如 `anchor apple generic and certificate leaf[subject.OU] = "<team>" and identifier "<主 App identifier>"` 的 requirement 字符串,交给 `NSXPCListener.setConnectionCodeSigningRequirement` 生效;没有逐次连接的 audit token 检查,改签名或改 bundle ID 会直接连不上+- 所有权记录固定放在 `/Library/Application Support/CodexBar/sleep-ownership.json`,由 root 在同目录写临时文件,完成 `F_FULLFSYNC` 后原子替换并同步目录,权限固定为 `0600`;只持久化 `idle`、`owned`、`restoring` 三态,`external` 只是任务期间的运行态,不落盘也不承担恢复责任+- 当前值为 0 时必须先写 `owned` 再写 `pmset 1`;释放时必须先写 `restoring` 再写 `pmset 0`;两次 pmset 都要重新读取 `pmset -g` 确认实际值,只有确认为 0 才能记回 `idle`+- 任务开始时实际值已为 1 就返回 `external`,不写 `pmset`;helper 每 5 秒观察一次,如果其他来源在任务期间改回 0,helper 立即按上一条顺序取得所有权+- helper 取得所有权后每 5 秒检查一次实际值与磁盘 transaction,值被改成 0 时重新写回 1,记录缺失、损坏或 transaction 不一致时先修复记录;修复失败也必须继续尝试恢复为 0+- 没有活跃租约时停止短轮询,只保留 60 秒异常恢复检查;所有短轮询使用 1 秒 leeway+- 每个 App 进程持有一个跨 XPC 重连不变的 client session ID,请求再带单调递增的 `generation`;helper 只释放对应进程的租约并拒绝延迟到达的旧 `generation`,不允许旧连接覆盖新状态+- 异常断连后租约宽限 15 秒;同一 App 在宽限内重连会续上原租约,watchdog 只会释放仍处于断连状态的那一个 client session+- helper 以 `owned` 或 `restoring` 启动时先恢复为 0 再接受新接管;以 `idle` 启动时不修改当前值,因为那个值可能属于其他来源+- 更新 helper 前 App 先释放自己的租约,helper 原子确认全局没有活跃客户端且所有权为 `idle`,再用短期更新准备锁拒绝新的接管;注册新 helper 后必须收到状态查询回复才记录新指纹,系统仍在等待首次批准时除外+- 切换失败按 2/4/8...256 秒重试,列表耗尽即放弃(延时累计约 8.5 分钟,每轮再等一次超时约 10 分钟),瞬时抖动能自愈,权限类故障不该无限重试+- XPC 请求带超时并汇进同一条重试路径;launchd 拉不起 helper 时 XPC 方法既不回复也不触发 `errorHandler`,没有它界面会显示防睡眠开着而实际没生效,日志里只剩没有配对回复的 `Helper XPC 请求已发送`+- 超时取值放在 `CodexBarHelperIPC.requestTimeoutSeconds` 而不是控制器里,它与 `watchdogGraceSeconds` 是一对:必须更小,App 先放手 helper 才能靠 watchdog 兜底,分处两个 module 会让人改了一边不知道另一边+- 开发期间用 `xcodebuild` 覆盖正在运行的 App bundle 会让 launchd 记的 daemon 与磁盘上的 helper 对不上,helper 从此拉不起来;重启 App 会由 `helperRegistrationNeedsRefresh` 的指纹比对自愈,排查时先看这一条+- helper 回传 `none`、`external`、`codexBar` 来源与操作后的实测值;App 只能在 `codexBar` 且实测为 0 时宣称系统睡眠已恢复或补发 `IOPMSleepSystem`,`external` 和 `none` 都只释放进程内断言+- App 退出由 `applicationShouldTerminate` 返回 `terminateLater`,先冻结新接管并等 helper 释放回复再继续退出;helper 刷新同样先释放,旧 helper 无响应时由新 helper 的启动恢复兜底+- `pmset` 是没有来源和引用计数的全局布尔值;CodexBar 取得所有权后如果另一个 App 也开始依赖这个 1,释放时仍会恢复为 0,系统层没有无歧义的方法判断另一个 App 的意图+- 低电量保护由 `PowerSourceMonitor` 供数,它只报事实(有没有内置电池、电量、是否靠电池供电),不知道阈值;读数保持 `unavailable`、`unreadable`、`present` 三态,把读取失败折叠成“没有电池”会让设置项凭空消失且保护静默失效+- 见过一次内置电池就记住 `hasSeenBattery`,之后读到空列表只能返回 `unreadable`;硬件不会中途消失,空列表只是 IOKit 重新枚举时的缺口,当成台式机会当场撤掉保护+- `hasSeenBattery` 只活在进程内不持久化,每次启动重新判定;笔记本启动时撞上枚举缺口会短暂显示成没有电池,由下一次电源通知自愈,而持久化会让从笔记本备份恢复的台式机永远多出低电量设置项+- `IOPSNotificationCreateRunLoopSource` 注册失败时降级成 60 秒轮询并记 `action=poll`;只靠 `didWakeNotification` 补读不够,防睡眠生效的机器按定义就不会睡,那条通知永远不来+- 首次读取在 `start()` 里单独判一次并记 `stage=start` 这条,不能改走 `refresh()` 那条路:后者按变化过滤,而读数初始值就是 `unreadable` 本身,首读失败会被静默吞掉,之后只留下一条没有配对失败行的恢复日志+- 防睡眠上限累计的是**真正挡住睡眠**的那段时间,`begin` 起表 `pause` 收表,收表之后机器睡着或被低电量拦下都不占用户的上限+- 上限计时用 `SuspendingClock` 而不是 `Date`,后者受系统时间调整影响且系统睡眠期间照走;排计时器的 `Task.sleep` 同样要传 `SuspendingClock`,否则睡一夜醒来会当场判定到期+- 低电量是**纯条件**判定,不设“低过电”的粘滞标志:电量会回升,充上电就该自动恢复防睡眠;`hasReachedMaximumDuration` 之所以是粘滞标志只因为累计只增不减,两者不要照抄+- 低电量必须同时满足在用电池与电量低于阈值,只看百分比会让“剩 5% 插上电再跑任务”当场被判低电量;判定用 `Power Source State`,不能用 `Is Charging`(接电停充时它也是 `false`)+- 电量读不到时维持上一次的判定,从没读到过就是不触发:误触发会当场断掉用户任务,漏触发最坏也有系统强制睡眠兜底+- 已经在低电量保护中时读数失败不清零,否则一次瞬时失败会绕过滞回,让防睡眠反复开关并重发通知+- 低电量通知只在 `isActivelyPreventingSleep` 为真且来源是 `codexBar` 时排队,外部来源不说“已恢复系统睡眠”;日志无条件记并用 `action=release|none` 区分,百分比只有那一条能看到+- 排队的通知要等 helper 恢复睡眠的 XPC 回复确认成功才发得出去,恢复失败走重试直至放弃,提前说“已恢复系统睡眠”会把用户骗去合盖然后把电耗干+- 补发 `IOPMSleepSystem` 之前还要 `await` 到通知真的提交完成,只把提交排进下一个 MainActor job 的话同一个 job 里的补发会抢在它前面+- 那次 `await` 之后要重认一次 `generation` 再走 `finishSleepRestore` 这一步,挂起期间可能已有新的禁用请求接管,否则会释放掉刚建立的空闲断言+- 设置页那句低电量说明看 `isLowBatteryBlocking` 而不是 `isLowBatteryActive`,后者在没有任务时也成立,那时无话可说+- 触发与解除用 `阈值` 与 `阈值 + 5%` 两道门槛,否则电量在阈值附近抖动会反复切 pmset,合盖时还会反复补发 `IOPMSleepSystem`+- 一轮低电量通知的终点是电量回到 `阈值 + 5%` 或者用户改了阈值,由 `hasNotifiedLowBattery` 记住;只看是否接电会让适配器接触不良时每翻一次供电状态就重发一条+- `hasNotifiedLowBattery` 只在通知真的提交成功之后才置位,打在入队处或提交前都会让没送达的那一条吃掉整轮配额,使这一轮之后真正触发的低电量再也提醒不了+- `hasNotifiedLowBattery` 只管通知不管判定,与上面“纯条件”不冲突:电量回到解除门槛以下再跌破仍算同一轮,不会重复提醒+- `SleepConditions` 里只放 `battery` 布尔,放电量百分比会让每掉 1% 刷一条变化日志;真实电量只在触发那一条单独记+- 状态只呈现在主面板活动卡片右侧的咖啡杯标记(带 tooltip),由 `KeepAliveController.isActivelyPreventingSleep` 驱动,`sleepPreventionSource` 区分外部来源与 CodexBar 所有权,卡片折叠成“暂无数据”时标记要跟着一起收+- 设置页那一行说明只在异常、外部来源、低电量生效或达到上限时出现,CodexBar 自己正常持有所有权时整行收起,`keepAliveCaption` 返回 `nil` 即代表收起+- 最长防睡眠时间、异常会话保护阈值与低电量阈值都在防睡眠子面板里,台式机读不到电池时低电量那一行整行隐藏而不是置灰+- 保持屏幕常亮跟 `isActivelyPreventingSleep` 走,由 `reconcileDisplayAwake` 单点切换,于是低电量拦下、达到上限、任务结束时屏幕都跟着放开+- 显示断言只保证屏幕不睡,屏保与闲置锁屏跟的是系统 idle 计时,要靠 30 秒一次的 `IOPMAssertionDeclareUserActivity` 压住,两者缺一不可+- 声明用户活动复用同一个 assertion ID,每次传 `null` 会新建一条,`pmset -g assertions` 里会堆成一串同名断言+- 逐次声明不记日志,建立与释放各一条就够还原状态;两条断言都是进程级的,App 退出或崩溃时系统自动收回,不经过 helper+- **菜单栏图标不承载防睡眠状态**,它要保持模板渲染让系统按菜单栏外观着色,自行着色在深浅和带染色的菜单栏下都会失控### 通知-- `CodexNotificationService` 是集中式的 MainActor 服务, 订阅额度快照与实时活动, 负责阈值穿越判定, 去重, 额度重置识别, 触觉反馈和本地通知; dedup key 落 UserDefaults-- 匿名任务在 transition 入口被过滤, 不发送完成或等待批准通知, 也不触发任务触觉反馈-- `send` 是唯一的提交入口, 返回一个 `Task<Bool, Never>?` 值, 需要等通知真的发出去再做下一步的调用方 `await` 它的 `value` 即可; 不要另开一条 async 通道, 那会悄悄少掉去重 时效判定与提交失败回调三项能力-- 去重判定留在 `send` 的同步段而不是挪进 `Task` 内部, 这样连续两次调用的第二次一定被挡下, 不依赖任务调度顺序-- 异常会话保护通知只依赖通知总开关与系统授权, 使用系统默认声音, `retryCount` 为 0; 提交前后都调用 monitor 的 relevance 检查, 过期通知立即撤回-- `NotificationSettings` 管 CodexBar 自身通知; `CodexCLINotificationSettings` 是另一回事, 它通过 app-server `config/read` 与 `config/batchWrite` 读写 Codex 自己的用户级 `config.toml`-- 通知面板里带依赖的行一律显示为关闭并置灰而不是隐藏, 任务类看 `codexHookSettings.isOperable`, 低电量保护通知看 `KeepAliveController.isLowBatteryProtectionEnabled` (防睡眠可用, 阈值开着, 且这台机器确实有电池), 防睡眠上限通知看 `KeepAliveController.isMaximumDurationEnabled` (防睡眠可用且不是无限制); 都不回写用户保存的开关-- 两条防睡眠通知的依赖里都含"防睡眠可用"这一层, 即防睡眠开关与 Hook 都开着, 判定收在 `publishNotificationDependencies` 一处; 只判各自的子设置会让防睡眠关着时这两行还亮着-- 带依赖的行由 `KeepAliveController` 判定并派生成一个值, 视图只读结论, 不在各视图各写一遍 `!= .unlimited` 这类规则-- 防睡眠上限通知与低电量通知共用同一个发送时机; 达到上限是粘滞状态, 一个计时周期只发一次, 不需要低电量那种本轮已通知的锁存+- `CodexNotificationService` 是集中式的 `MainActor` 服务,订阅额度快照与实时活动,负责阈值穿越判定、去重、额度重置识别、触觉反馈和本地通知;dedup key 落 `UserDefaults`+- 匿名任务在 transition 入口被过滤,不发送完成或等待批准通知,也不触发任务触觉反馈+- `send` 是唯一的提交入口,返回一个 `Task<Bool, Never>?` 值,需要等通知真的发出去再做下一步的调用方 `await` 它的 `value` 即可;不要另开一条 async 通道,那会悄悄少掉去重、时效判定与提交失败回调三项能力+- 去重判定留在 `send` 的同步段而不是挪进 `Task` 内部,这样连续两次调用的第二次一定被挡下,不依赖任务调度顺序+- 异常会话保护通知只依赖通知总开关与系统授权,使用系统默认声音,`retryCount` 为 0;提交前后都调用 monitor 的 relevance 检查,过期通知立即撤回+- `NotificationSettings` 管 CodexBar 自身通知;`CodexCLINotificationSettings` 是另一回事,它通过 app-server `config/read` 与 `config/batchWrite` 读写 Codex 自己的用户级 `config.toml`+- 通知面板里带依赖的行一律显示为关闭并置灰而不是隐藏,任务类看 `codexHookSettings.isOperable`,低电量保护通知看 `KeepAliveController.isLowBatteryProtectionEnabled`(防睡眠可用、阈值开着,且这台机器确实有电池),防睡眠上限通知看 `KeepAliveController.isMaximumDurationEnabled`(防睡眠可用且不是无限制);都不回写用户保存的开关+- 两条防睡眠通知的依赖里都含“防睡眠可用”这一层,即防睡眠开关与 Hook 都开着,判定收在 `publishNotificationDependencies` 一处;只判各自的子设置会让防睡眠关着时这两行还亮着+- 带依赖的行由 `KeepAliveController` 判定并派生成一个值,视图只读结论,不在各视图各写一遍 `!= .unlimited` 这类规则+- 防睡眠上限通知与低电量通知共用同一个发送时机;达到上限是粘滞状态,一个计时周期只发一次,不需要低电量那种本轮已通知的锁存### 并发与隔离-工程开启 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor` 设置, 所有类型默认 MainActor 隔离+工程开启 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor` 设置,所有类型默认 `MainActor` 隔离。-- UI, 控制器, ViewModel, Settings, 更新类直接依赖默认隔离, 不需要额外标注-- 服务共享状态用 actor 管理, 包括 `CodexStatusService` `WorkflowService` `WorkflowSyncService` `CodexCLIVersionService` `HookEventTailReader` `CodexSessionLifecycleReader` `ActivityProtectionStateStore`-- DTO, 纯模型, 静态工具, 跨 actor 传递的类型必须显式标注 `nonisolated`-- 跨进程写统计文件用 `stats.lock` 加 `flock` 保护, Hook 子进程有等待上限, 主 App 无限等待; `RequestLogStorage` 用 `OSAllocatedUnfairLock`-- 非 Sendable 的管道 IO 集中在 `PipeReadBuffer` 里, `JSONLineReader` 与 `PipeDrain` 复用它-- 保留既有防重入与过期结果丢弃逻辑, 例如 `RefreshTaskCoordinator` 只让最新 generation 提交结果-- 不要用阻塞 I/O 或长耗时操作卡住 MainActor+- UI、控制器、ViewModel、Settings、更新类直接依赖默认隔离,不需要额外标注+- 服务共享状态用 actor 管理,包括 `CodexStatusService`、`WorkflowService`、`WorkflowSyncService`、`CodexCLIVersionService`、`HookEventTailReader`、`CodexSessionLifecycleReader`、`ActivityProtectionStateStore`+- DTO、纯模型、静态工具、跨 actor 传递的类型必须显式标注 `nonisolated`+- 跨进程写统计文件用 `stats.lock` 加 `flock` 保护,Hook 子进程有等待上限,主 App 无限等待;`RequestLogStorage` 用 `OSAllocatedUnfairLock`+- 非 Sendable 的管道 IO 集中在 `PipeReadBuffer` 里,`JSONLineReader` 与 `PipeDrain` 复用它+- 保留既有防重入与过期结果丢弃逻辑,例如 `RefreshTaskCoordinator` 只让最新 `generation` 提交结果+- 不要用阻塞 I/O 或长耗时操作卡住 `MainActor`### 错误处理原则-- 菜单面板的 `CodexFetchOutcome` 只暴露有数据, 未登录, 初始化失败三种结果, 而启动失败, 超时, 断连, 解析失败等细节全部只进日志窗口, 由 `RequestLogStorage` 保存, 上限 500 条-- app-server 之外的模块走 `Services/Support/AppLog.swift` 写系统日志, 用户可见文案只留步骤名, 错误码与 `localizedDescription` 这类细节进 os_log; 现有 category 为 `app` `keepalive` `activity` `workflow` `sync` `hooks` `codexcli` `settings` `notification`, helper 进程另用 `helper`-- 日志的目标是出问题时能从中重建当时的状态, 所以不只记失败, 状态转换, 关键操作与决策依据同样要记; 启动时由 `logLaunchState` 记一条含全部开关的基线, 后续变更日志都是相对它的增量-- 进程终止靠 `AppProcessDiagnostics` 补线索, 它和 `logLaunchState` 一样挂在 `app` category 下, ObjC 异常当场留痕, 其余终止方式靠下次启动补记一条 `App 上次非正常退出`-- 那条补记只能用 `.notice` 级别, 因为 kill 与强制退出和真崩溃无法区分, 用 `.error` 会让按级别筛的排查开局就追一个不存在的故障-- **级别只用 `.notice` 与 `.error`**, 状态转换和降级决策用 `.notice`, 失败用 `.error`; `.info` 与 `.debug` 只落在内存环形缓冲里, 事后 `log show` 捞不全, 一律不用-- 详细度靠**结果字段化**而不是多记几条: 一次操作只留开始与收尾两条, 每一步的成功结果压成收尾那条里的一个字段, 只有失败才单独发一条 `.error` 带 `stage=` 与 `detail=`; 逐事件与逐快照这类高频路径仍然一律不记, 例如两个 Reader 的 `try?` 文件 IO 失败是预期常态, 记了会刷屏-- 文案骨架是 `<主体><动作>: 字段=值; 字段=值`, 标题只说发生了什么, 理由进 `reason=`, 处置进 `action=`; 起止用 `开始` `完成` `失败`, 中间状态用 `已<动作>`-- 字段顺序固定为 标识 (`trigger` `generation` `date`) 输入 结果 `elapsed` `reason`/`detail`; 公共字段有 `trigger` `result` `reason` `action` `detail` `code` (系统返回码) `exit` (进程退出码) `elapsed`, 其中 `code` 与 `exit` 必须分开, 不要用一个 `error=` 同时装 OSStatus IOReturn 和退出码-- 文案只描述事实, 不写"用户做了什么"这类主语, 也不写推论; 字段值要可 grep, 用枚举 rawValue 而不是中文句子, App 与 helper 两侧保持同一套格式-- 词根固定, 一个词能 grep 出整条链路: 额度, 统计刷新 (调度层), 事件汇总 (计算层), 同步, KeepAlive (防睡眠决策层), 空闲断言 (进程内 `IOPMAssertion`), 显示断言 (屏幕常亮那条 `IOPMAssertion`), Helper 注册 (`SMAppService`), Helper XPC (`NSXPCConnection`), 系统睡眠 (helper 的 pmset 效果), 电源监听 (`PowerSourceMonitor`), 任务, Hook, codex, 通知-- 防睡眠日志按两套机制分组: `KeepAlive` 是两套共用的决策层, `空闲断言` 与 `显示断言` 是机制一, `Helper 注册` `Helper XPC` `系统睡眠` 是机制二的授权 传输 效果三层, 故障定位就是在这几层里找-- `trigger=` 由 `LogTrigger` 提供, 从 UI 入口透传到服务层, 用来区分同一条链路是被用户动作 定时轮询还是系统事件踢起来的; 统计维护挂在额度刷新完成事件上, 它的 trigger 继承那一次刷新-- 变化检测类日志只在值真的变了才记, 例如 `KeepAlive 条件已变化` 与 `Hook 配置已变化` 各自存一份上次的值, 否则每次开面板都会刷一条-- 设置项的变更日志照抄设置页那一行的标题, 例如 `菜单栏额度指示变更` `开机自动启动变更`, 用户说"我改了那个开关"时能直接对上; 只有本身带完整链路的才用链路词根, 例如 Hook 同步 通知 KeepAlive 快捷键-- 成对的操作要留成对的日志, 例如 XPC 的发送与回复各记一条并带同一个 `generation`, 缺一条就说明请求丢在途中-- 耗时用 `LogDuration` 取, 只加在收尾那一条上-- `Logger` 的插值是 autoclosure, 里面直接访问属性会被要求显式 `self`, 而 `.swiftformat` 配了 `--self remove`, 两边会打架; 把属性先取到局部常量再插值即可, 不需要 lint 豁免-- 账号有效时 rate limits 和 usage 允许单独失败, 复用同账号旧缓存并标记 stale, UI 显示为半透明, 无缓存则该区域不显示; 账号变化时整体丢弃缓存避免串号-- 各 Settings 类把读取类错误与操作类错误分开存储, 定时 refresh 不能抹掉用户操作或校验的结论, 参见 `CodexHookSettings` 与 `KeepAliveController`-- Hook 子进程任何失败都静默退出, 优先保证不拖慢 Codex+- 菜单面板的 `CodexFetchOutcome` 只暴露有数据、未登录、初始化失败三种结果,而启动失败、超时、断连、解析失败等细节全部只进日志窗口,由 `RequestLogStorage` 保存,上限 500 条+- app-server 之外的模块走 `Services/Support/AppLog.swift` 写系统日志,用户可见文案只留步骤名,错误码与 `localizedDescription` 这类细节进 `os_log`;现有 `category` 为 `app`、`keepalive`、`activity`、`workflow`、`sync`、`hooks`、`codexcli`、`settings`、`notification`,helper 进程另用 `helper`+- 日志的目标是出问题时能从中重建当时的状态,所以不只记失败,状态转换、关键操作与决策依据同样要记;启动时由 `logLaunchState` 记一条含全部开关的基线,后续变更日志都是相对它的增量+- 进程终止靠 `AppProcessDiagnostics` 补线索,它和 `logLaunchState` 一样挂在 `app` category 下,ObjC 异常当场留痕,其余终止方式靠下次启动补记一条 `App 上次非正常退出`+- 那条补记只能用 `.notice` 级别,因为 kill 与强制退出和真崩溃无法区分,用 `.error` 会让按级别筛的排查开局就追一个不存在的故障+- **级别只用 `.notice` 与 `.error`**,状态转换和降级决策用 `.notice`,失败用 `.error`;`.info` 与 `.debug` 只落在内存环形缓冲里,事后 `log show` 捞不全,一律不用+- 详细度靠**结果字段化**而不是多记几条:一次操作只留开始与收尾两条,每一步的成功结果压成收尾那条里的一个字段,只有失败才单独发一条 `.error` 带 `stage=` 与 `detail=`;逐事件与逐快照这类高频路径仍然一律不记,例如两个 Reader 的 `try?` 文件 IO 失败是预期常态,记了会刷屏+- 文案骨架是 `<主体><动作>: 字段=值; 字段=值`,标题只说发生了什么,理由进 `reason=`,处置进 `action=`;起止用 `开始` `完成` `失败`,中间状态用 `已<动作>`+- 字段顺序固定为标识(`trigger`、`generation`、`date`)、输入、结果、`elapsed`、`reason`/`detail`;公共字段有 `trigger`、`result`、`reason`、`action`、`detail`、`code`(系统返回码)、`exit`(进程退出码)、`elapsed`,其中 `code` 与 `exit` 必须分开,不要用一个 `error=` 同时装 OSStatus、IOReturn 和退出码+- 文案只描述事实,不写“用户做了什么”这类主语,也不写推论;字段值要可 `grep`,用枚举 `rawValue` 而不是中文句子,App 与 helper 两侧保持同一套格式+- 词根固定,一个词能 `grep` 出整条链路:额度、统计刷新(调度层)、事件汇总(计算层)、同步、KeepAlive(防睡眠决策层)、空闲断言(进程内 `IOPMAssertion`)、显示断言(屏幕常亮那条 `IOPMAssertion`)、Helper 注册(`SMAppService`)、Helper XPC(`NSXPCConnection`)、系统睡眠(helper 的 pmset 效果)、电源监听(`PowerSourceMonitor`)、任务、Hook、codex、通知+- 防睡眠日志按两套机制分组:`KeepAlive` 是两套共用的决策层,`空闲断言` 与 `显示断言` 是机制一,`Helper 注册`、`Helper XPC`、`系统睡眠` 是机制二的授权、传输、效果三层,故障定位就是在这几层里找+- `trigger=` 由 `LogTrigger` 提供,从 UI 入口透传到服务层,用来区分同一条链路是被用户动作、定时轮询还是系统事件踢起来的;统计维护挂在额度刷新完成事件上,它的 `trigger` 继承那一次刷新+- 变化检测类日志只在值真的变了才记,例如 `KeepAlive 条件已变化` 与 `Hook 配置已变化` 各自存一份上次的值,否则每次开面板都会刷一条+- 设置项的变更日志照抄设置页那一行的标题,例如 `菜单栏额度指示变更`、`开机自动启动变更`,用户说“我改了那个开关”时能直接对上;只有本身带完整链路的才用链路词根,例如 Hook、同步、通知、KeepAlive、快捷键+- 成对的操作要留成对的日志,例如 XPC 的发送与回复各记一条并带同一个 `generation`,缺一条就说明请求丢在途中+- 耗时用 `LogDuration` 取,只加在收尾那一条上+- `Logger` 的插值是 autoclosure,里面直接访问属性会被要求显式 `self`,而 `.swiftformat` 配了 `--self remove`,两边会打架;把属性先取到局部常量再插值即可,不需要 lint 豁免+- 账号有效时 `rate limits` 和 `usage` 允许单独失败,复用同账号旧缓存并标记 `stale`,UI 显示为半透明,无缓存则该区域不显示;账号变化时整体丢弃缓存避免串号+- 各 Settings 类把读取类错误与操作类错误分开存储,定时 `refresh` 不能抹掉用户操作或校验的结论,参见 `CodexHookSettings` 与 `KeepAliveController`+- Hook 子进程任何失败都静默退出,优先保证不拖慢 Codex## UI 与窗口约定-- 菜单栏按钮左键切换主面板; 右键或 Control+点击打开上下文菜单; `⌘,` 打开自定义设置窗口, 菜单面板打开时 `⌘L` 打开日志窗口; 默认全局快捷键 `⌘⇧W` 由 `GlobalHotKeySettings` 与 `GlobalHotKeyController` 管理-- 主面板是锚定 status item 的 `NSPopover` 弹窗, 锚点不可信时回退到 `FallbackPanelController` 提供的屏幕顶部居中 `NSPanel` 面板, 处理快捷键, 屏幕选择和焦点时要保留这两个分支-- 关闭逻辑统一由 `MenuSurfaceDismissMonitor` 管理, 淡出由 `MenuSurfaceFadeCoordinator` 负责-- 侧边面板都是 borderless nonactivating child panel, 热力图详情, 重置次数和任务中心挂在主面板上, 通知选项和防睡眠选项挂在设置窗口上-- 设置窗口的子面板占同一位置, 展开一个必须先 `hide(immediate: true)` 收掉其余的; 动作走 `SettingsOptionsPanelAction` 并带上目标 `SettingsOptionsPanel`, 互斥与 `closeAll` 都只写在 `SettingsWindowController.handleOptionsAction` 一处, 加第三个面板不会漏配对-- 面板控制器只在首次展开时构造, 收起动作走 `existingOptionsPanelController` 而不触发构造: 它一建就挂上内容变化订阅并常驻到 App 结束, 而用户可能一次子面板都没开过-- 两个子面板的顶边对齐各自主开关行, anchor 由设置页的 `ScreenFrameProvider` 随展开动作传出, 定位走 `SidePanelSupport.anchoredPosition` 而不是宿主底边-- 设置窗口的子面板要传 `clampsToSurfaceBottom: false` 让底边可以探出窗口, 否则放不下时会把整个面板上推而错开主开关行; 主面板那三个面板走默认的 true-- 两个子面板的高度都会变, 通知面板随音效行增删, 防睡眠面板随 `hasBattery` 增删低电量那一行; resize 时要固定顶边向下生长, 直接改 size 会保持底边不动而把顶边顶离主开关行-- 高度重算只订阅真正会改变行数的那几项, 通知面板订 `notificationSettings` 与 `codexHookSettings` 的 `objectWillChange` 再加 `KeepAliveController.$isLowBatteryProtectionEnabled` 与 `$isMaximumDurationEnabled` 两条, 防睡眠面板只订 `$hasBattery` 一条; 订整个防睡眠控制器会让任务每起停一次都白排一轮 resize-- 置灰也会改高度: 带音效的行置灰时音效子行跟着收起, 所以每个置灰依赖都要有一个对应的订阅源-- 增删行或改行的显示条件时要同步补上对应的订阅源, 漏一项会让面板裁掉底部或留下空白-- resize 的竖向夹紧走 `SidePanelSupport.clampedVertically`, 与初次展开的 `position` 同一条规则, 否则放不下时两边会把面板推向相反的边-- 子面板入口只在开关开着且依赖就绪时出现, 通知看 `NotificationSettings.canShowOptions` 那个值, 防睡眠看 `KeepAliveController.canShowOptions` 这个值; 两者都只控制入口显隐, 不回写用户保存的开关-- 两个子面板都只由滑杆按钮展开, 动作只有 toggle 与 close 两种, 开启主开关不自动弹出-- 侧边面板公共能力集中在 `Controllers/SidePanelSupport.swift` 里, 含 `SidePanelDrawerPresenter` `SidePanelContentHost` `SidePanelDrawerAnimator` panel 工厂和定位夹紧; 挂在主面板上的那三个面板优先复用 `SidePanelDrawerPresenter` 这一层, 不要另起一套-- 设置窗口的子面板直接复用 `Controllers/SettingsOptionsPanelController.swift`, 它在 presenter 之上补齐了装配, 两套关闭观察者, 顶边对齐定位和高度重算; 新增设置子面板只要给它内容工厂与内容变化来源, 不要再写一层壳-- 两个设置子面板的行高与间距从 `SettingsOptionsPanelMetrics` 取, 下拉控件共用 `SettingsOptionsPicker` 这一个, 只有面板宽度和 picker 宽度各自定义, 这样两个面板看起来才是同一套控件-- 设置子面板的内容工厂必须走 `SettingsOptionsPanelController.makeContentController(_:rebuiltBy:)`, 否则首次展开时原生 Switch 只剩一条空轨道; 重建信号由它接在内容外面, 内容视图不必知道 `SidePanelEntryCue`-- 原因是 thumb 由 `WindowPortal` 投射而不是画在开关上, 面板首次布局那一轮 portal 建不起来, 而且不会自愈, 只有一次内容重建才补得上; 第二次展开正常是因为 hosting controller 常驻, 复用了已经建好的那份-- 不要再用 `@_optimize(none)` 规避这个漏绘: 它当年在通知子面板管用只是因为逼着 body 重算时判定那些行变过, 与优化等级无关, 换个写法就失效; `SidePanelSupport` 里剩下那一处标注规避的是编译器崩溃, 与此无关-- 主面板任务中心的显隐由 `MainPanelSettings.showsTaskCenter` 与 `codexHookSettings.isEnabled` 共同决定, Hook 未开启时设置页那一行显示为关闭并置灰, 不回写用户保存的开关值-- 设置窗口 (通用/高级/关于三页) 和日志窗口复用 `HostingWindowController` 的行为, 可以成为 key window, 但不应成为 main window-- 视觉风格统一走 `Views/Shared/LiquidGlassStyle.swift` 这一套, 避免引入与系统菜单栏工具不一致的重装饰 UI+- 菜单栏按钮左键切换主面板;右键或 Control+点击打开上下文菜单;`⌘,` 打开自定义设置窗口,菜单面板打开时 `⌘L` 打开日志窗口;默认全局快捷键 `⌘⇧W` 由 `GlobalHotKeySettings` 与 `GlobalHotKeyController` 管理+- 主面板是锚定 status item 的 `NSPopover` 弹窗,锚点不可信时回退到 `FallbackPanelController` 提供的屏幕顶部居中 `NSPanel` 面板,处理快捷键、屏幕选择和焦点时要保留这两个分支+- 关闭逻辑统一由 `MenuSurfaceDismissMonitor` 管理,淡出由 `MenuSurfaceFadeCoordinator` 负责+- 侧边面板都是 borderless nonactivating child panel,热力图详情、重置次数和任务中心挂在主面板上,通知选项和防睡眠选项挂在设置窗口上+- 设置窗口的子面板占同一位置,展开一个必须先 `hide(immediate: true)` 收掉其余的;动作走 `SettingsOptionsPanelAction` 并带上目标 `SettingsOptionsPanel`,互斥与 `closeAll` 都只写在 `SettingsWindowController.handleOptionsAction` 一处,加第三个面板不会漏配对+- 面板控制器只在首次展开时构造,收起动作走 `existingOptionsPanelController` 而不触发构造:它一建就挂上内容变化订阅并常驻到 App 结束,而用户可能一次子面板都没开过+- 两个子面板的顶边对齐各自主开关行,anchor 由设置页的 `ScreenFrameProvider` 随展开动作传出,定位走 `SidePanelSupport.anchoredPosition` 而不是宿主底边+- 设置窗口的子面板要传 `clampsToSurfaceBottom: false` 让底边可以探出窗口,否则放不下时会把整个面板上推而错开主开关行;主面板那三个面板走默认的 `true`+- 两个子面板的高度都会变,通知面板随音效行增删,防睡眠面板随 `hasBattery` 增删低电量那一行;resize 时要固定顶边向下生长,直接改 size 会保持底边不动而把顶边顶离主开关行+- 高度重算只订阅真正会改变行数的那几项,通知面板订 `notificationSettings` 与 `codexHookSettings` 的 `objectWillChange` 再加 `KeepAliveController.$isLowBatteryProtectionEnabled` 与 `$isMaximumDurationEnabled` 两条,防睡眠面板只订 `$hasBattery` 一条;订整个防睡眠控制器会让任务每起停一次都白排一轮 resize+- 置灰也会改高度:带音效的行置灰时音效子行跟着收起,所以每个置灰依赖都要有一个对应的订阅源+- 增删行或改行的显示条件时要同步补上对应的订阅源,漏一项会让面板裁掉底部或留下空白+- resize 的竖向夹紧走 `SidePanelSupport.clampedVertically`,与初次展开的 `position` 同一条规则,否则放不下时两边会把面板推向相反的边+- 子面板入口只在开关开着且依赖就绪时出现,通知看 `NotificationSettings.canShowOptions` 那个值,防睡眠看 `KeepAliveController.canShowOptions` 这个值;两者都只控制入口显隐,不回写用户保存的开关+- 两个子面板都只由滑杆按钮展开,动作只有 `toggle` 与 `close` 两种,开启主开关不自动弹出+- 侧边面板公共能力集中在 `Controllers/SidePanelSupport.swift` 里,含 `SidePanelDrawerPresenter`、`SidePanelContentHost`、`SidePanelDrawerAnimator`、panel 工厂和定位夹紧;挂在主面板上的那三个面板优先复用 `SidePanelDrawerPresenter` 这一层,不要另起一套+- 设置窗口的子面板直接复用 `Controllers/SettingsOptionsPanelController.swift`,它在 presenter 之上补齐了装配、两套关闭观察者、顶边对齐定位和高度重算;新增设置子面板只要给它内容工厂与内容变化来源,不要再写一层壳+- 两个设置子面板的行高与间距从 `SettingsOptionsPanelMetrics` 取,下拉控件共用 `SettingsOptionsPicker` 这一个,只有面板宽度和 picker 宽度各自定义,这样两个面板看起来才是同一套控件+- 设置子面板的内容工厂必须走 `SettingsOptionsPanelController.makeContentController(_:rebuiltBy:)`,否则首次展开时原生 Switch 只剩一条空轨道;重建信号由它接在内容外面,内容视图不必知道 `SidePanelEntryCue`+- 原因是 thumb 由 `WindowPortal` 投射而不是画在开关上,面板首次布局那一轮 portal 建不起来,而且不会自愈,只有一次内容重建才补得上;第二次展开正常是因为 hosting controller 常驻,复用了已经建好的那份+- 不要再用 `@_optimize(none)` 规避这个漏绘:它当年在通知子面板管用只是因为逼着 body 重算时判定那些行变过,与优化等级无关,换个写法就失效;`SidePanelSupport` 里剩下那一处标注规避的是编译器崩溃,与此无关+- 主面板任务中心的显隐由 `MainPanelSettings.showsTaskCenter` 与 `codexHookSettings.isEnabled` 共同决定,Hook 未开启时设置页那一行显示为关闭并置灰,不回写用户保存的开关值+- 设置窗口(通用/高级/关于三页)和日志窗口复用 `HostingWindowController` 的行为,可以成为 key window,但不应成为 main window+- 视觉风格统一走 `Views/Shared/LiquidGlassStyle.swift` 这一套,避免引入与系统菜单栏工具不一致的重装饰 UI## Hook 配置改写约束-`~/.codex/hooks.json` 的读写全部在 `CodexHookSettings` 里完成, Codex 目录优先取 `CODEX_HOME` 环境变量, 找不到时回退真实用户 HOME 下的 `.codex` 目录+`~/.codex/hooks.json` 的读写全部在 `CodexHookSettings` 里完成,Codex 目录优先取 `CODEX_HOME` 环境变量,找不到时回退真实用户 HOME 下的 `.codex` 目录。-- 只识别并移除 command 同时包含当前 CodexBar 可执行路径与 `--hook-event` 的 handler, 必须保留用户已有 Hook 以及其他 App 的 Hook 和同事件下的其他 handler-- 每个 `CodexHookEvent.allCases` 事件追加一个独立 group, handler 超时从 `WorkflowHookEventRecorder.hookTimeoutSeconds(for:)` 取得; 新增事件时不得复制一份超时常量-- 启用和校验 Hook 前要求当前 app-server 握手版本至少为 `0.145.0`; 必须检查 `readyConnectionInfo()` 返回的实际连接版本, 不能用磁盘版本代替, 否则升级后尚未重连的旧进程会被误判为可用-- 写入前通过 app-server `config/read` 确认全局未禁用 Hook, 写入后用 `hooks/list` 验证; 两处读取共用 `readGlobalHookDisabled`, 开关流程与校验流程对"全局禁用"的判断不会分叉-- 读取失败 (I/O 或 JSON 格式错误) 不提供 Hook 装没装的信息, 必须保留上次已知值, 不能当成用户关闭了 Hook-- `isEnabled` 只表示 `hooks.json` 里至少装着一个当前 CodexBar handler, `isVerified` 是最近一次校验的明确结论, 两者合成的 `isOperable` 才表示事件链路可用-- 实时任务, 防睡眠和任务类通知必须看 `isOperable`; 历史聚合与同步仍可消费已落盘数据, 其调度只看 `isEnabled`, 不要把两类依赖混在一起-- `isVerified` 乐观默认为 true 且只由明确结论写入两个方向: 校验只在设置窗口打开与 App 激活时跑, 而 RPC 失败属于"验不了"不是"确认不通", 那时置灰会把好用的功能关掉-- 全局禁用要排在 `hooks/list` 之前判: 它一关列表里必然找不到我们的 handler, 那时报"已不完整"会把用户引去翻本来就完好的 `hooks.json`-- `refresh()` 只判断是否存在任一当前 CodexBar handler, `hooks/list` 校验才要求所有事件完整; 新增事件后旧配置不会自动补齐, 当前恢复方式是让用户关闭再开启 Hook-- 校验不通过时防睡眠那一行的说明写"CodexBar Hook 未生效"而不是"需要启用 CodexBar Hook", 后者会让用户去开一个已经开着的开关; 具体病因由 Hook 那一行自己的说明给出+- 只识别并移除 command 同时包含当前 CodexBar 可执行路径与 `--hook-event` 的 handler,必须保留用户已有 Hook 以及其他 App 的 Hook 和同事件下的其他 handler+- 每个 `CodexHookEvent.allCases` 事件追加一个独立 group,handler 超时从 `WorkflowHookEventRecorder.hookTimeoutSeconds(for:)` 取得;新增事件时不得复制一份超时常量+- 启用和校验 Hook 前要求当前 app-server 握手版本至少为 `0.145.0`;必须检查 `readyConnectionInfo()` 返回的实际连接版本,不能用磁盘版本代替,否则升级后尚未重连的旧进程会被误判为可用+- 写入前通过 app-server `config/read` 确认全局未禁用 Hook,写入后用 `hooks/list` 验证;两处读取共用 `readGlobalHookDisabled`,开关流程与校验流程对“全局禁用”的判断不会分叉+- 读取失败(I/O 或 JSON 格式错误)不提供 Hook 装没装的信息,必须保留上次已知值,不能当成用户关闭了 Hook+- `isEnabled` 只表示 `hooks.json` 里至少装着一个当前 CodexBar handler,`isVerified` 是最近一次校验的明确结论,两者合成的 `isOperable` 才表示事件链路可用+- 实时任务、防睡眠和任务类通知必须看 `isOperable`;历史聚合与同步仍可消费已落盘数据,其调度只看 `isEnabled`,不要把两类依赖混在一起+- `isVerified` 乐观默认为 `true` 且只由明确结论写入两个方向:校验只在设置窗口打开与 App 激活时跑,而 RPC 失败属于“验不了”不是“确认不通”,那时置灰会把好用的功能关掉+- 全局禁用要排在 `hooks/list` 之前判:它一关列表里必然找不到我们的 handler,那时报“已不完整”会把用户引去翻本来就完好的 `hooks.json`+- `refresh()` 只判断是否存在任一当前 CodexBar handler,`hooks/list` 校验才要求所有事件完整;新增事件后旧配置不会自动补齐,当前恢复方式是让用户关闭再开启 Hook+- 校验不通过时防睡眠那一行的说明写“CodexBar Hook 未生效”而不是“需要启用 CodexBar Hook”,后者会让用户去开一个已经开着的开关;具体病因由 Hook 那一行自己的说明给出## 隐私与数据边界-改动涉及网络, 日志或同步时必须遵守+改动涉及网络、日志或同步时必须遵守:-- App 只有四类出网行为, 分别是本机 app-server stdio 通信 (不算网络), 重置机会过期时间只读查询, Sparkle 更新, 用户显式开启后的 CloudKit 同步, 新增网络请求需要非常明确的理由-- 只读查询打到 `https://chatgpt.com/backend-api/wham/rate-limit-reset-credits` 这一个地址, 也是全仓库唯一的 `URLSession` 调用点, 位于 `CodexResetCreditsService` 内; Sparkle 更新走 `https://codexbar.zabrian.app/appcast.xml` 这个 feed-- 不展示 app-server stderr; 不展示或记录 Codex OAuth token 与 `auth.json` 内容; 不把原始敏感 RPC 响应写进文档-- CloudKit 只同步去掉 `sessionIds` 与 `turnIds` 的 daily 聚合, 不同步原始 Hook events, 账号, 额度或 Token 用量-- 异常会话保护状态只保存在本机, 不同步 CloudKit; 记录不含原始 session ID, turn ID, 项目名或任务内容-- CloudKit 的 `sessionEndCount` `userPromptSubmitCount` 与其他 Hook 计数字段保持可选, 远端缺失表示历史来源没有提供, 不能在读取时补成 0; 改变远端格式时同时评估并更新 `syncSchemaVersion`-- 系统日志不写用户数据: 额度与 Token 用量只记 `state=` 这类结果分类, 任务内容, 项目名, 会话与轮次标识一律不记; 可执行文件路径含用户名, 用 `source=global|bundled` 之类的标识代替-- 事件数, 任务数, 日期这类聚合数字可以记, 它们是判断重建是否正确和定位哪天出问题的依据, 不含任何内容+- App 只有四类出网行为,分别是本机 app-server stdio 通信(不算网络)、重置机会过期时间只读查询、Sparkle 更新、用户显式开启后的 CloudKit 同步;新增网络请求需要非常明确的理由+- 只读查询打到 `https://chatgpt.com/backend-api/wham/rate-limit-reset-credits` 这一个地址,也是全仓库唯一的 `URLSession` 调用点,位于 `CodexResetCreditsService` 内;Sparkle 更新走 `https://codexbar.zabrian.app/appcast.xml` 这个 feed+- 不展示 app-server stderr;不展示或记录 Codex OAuth token 与 `auth.json` 内容;不把原始敏感 RPC 响应写进文档+- CloudKit 只同步去掉 `sessionIds` 与 `turnIds` 的 daily 聚合,不同步原始 Hook events、账号、额度或 Token 用量+- 异常会话保护状态只保存在本机,不同步 CloudKit;记录不含原始 session ID、turn ID、项目名或任务内容+- CloudKit 的 `sessionEndCount`、`userPromptSubmitCount` 与其他 Hook 计数字段保持可选,远端缺失表示历史来源没有提供,不能在读取时补成 `0`;改变远端格式时同时评估并更新 `syncSchemaVersion`+- 系统日志不写用户数据:额度与 Token 用量只记 `state=` 这类结果分类,任务内容、项目名、会话与轮次标识一律不记;可执行文件路径含用户名,用 `source=global|bundled` 之类的标识代替+- 事件数、任务数、日期这类聚合数字可以记,它们是判断重建是否正确和定位哪天出问题的依据,不含任何内容## 代码修改原则-- 优先贴合现有文件结构和类型职责, 不为小改动新建抽象-- 改 shared controller, shared service, 模型解析或持久化 key 时, 要考虑旧数据和降级路径; 用户设置要保持默认值; 持久化 key 和旧版本迁移兼容-- **任何兼容性问题都必须主动询问用户, 不要自行决定**; 只要改动会影响新旧共存就适用, 不限于旧数据迁移或丢弃, 持久化 key 改名或改结构, 老版本升上来的降级路径, 最低系统版本与 API 可用性取舍, 云端记录格式变更; 先说清影响面和几种做法的代价, 等用户选定再动手-- 处理窗口, 菜单, 快捷键, App 激活或事件监听时, 特别注意 `LSUIElement` 应用特有的焦点行为-- 注释保持克制, 只解释非显然的生命周期, 焦点, actor 或系统 API 约束; 现有注释多为解释为什么的类型, 沿用同样风格-- 改动涉及菜单面板, 窗口焦点, Hook, 同步, 通知或防睡眠时, 构建通过之外还要说明应手动覆盖的交互场景; 防睡眠额外要验证 App 包内 helper 与 plist 位置, 签名, 首次系统授权, 运行/等待切换和异常退出后的恢复-- 不要把发布产物, DerivedData, 临时 DMG, 签名文件或个人凭据提交进仓库+- 优先贴合现有文件结构和类型职责,不为小改动新建抽象+- 改 shared controller、shared service、模型解析或持久化 key 时,要考虑旧数据和降级路径;用户设置要保持默认值;持久化 key 和旧版本迁移兼容+- **任何兼容性问题都必须主动询问用户,不要自行决定**;只要改动会影响新旧共存就适用,不限于旧数据迁移或丢弃、持久化 key 改名或改结构、老版本升上来的降级路径、最低系统版本与 API 可用性取舍、云端记录格式变更;先说清影响面和几种做法的代价,等用户选定再动手+- 处理窗口、菜单、快捷键、App 激活或事件监听时,特别注意 `LSUIElement` 应用特有的焦点行为+- 注释保持克制,只解释非显然的生命周期、焦点、actor 或系统 API 约束;现有注释多为解释为什么的类型,沿用同样风格+- 改动涉及菜单面板、窗口焦点、Hook、同步、通知或防睡眠时,构建通过之外还要说明应手动覆盖的交互场景;防睡眠额外要验证 App 包内 helper 与 plist 位置、签名、首次系统授权、运行/等待切换和异常退出后的恢复+- 不要把发布产物、DerivedData、临时 DMG、签名文件或个人凭据提交进仓库diff --git a/Docs/DeveloperGuide/README.md b/Docs/DeveloperGuide/README.mdindex 79be7f4..4aac3ae 100644--- a/Docs/DeveloperGuide/README.md+++ b/Docs/DeveloperGuide/README.md@@ -1,21 +1,21 @@# CodexBar 开发者指南-本指南面向希望理解 CodexBar 架构, 调试数据链路或参与开发的开发者+本指南面向希望理解 CodexBar 架构、调试数据链路或参与开发的开发者。-内容不仅描述模块做什么, 还解释为什么这样划分职责, 哪些失败路径是刻意保守处理, 以及修改实现时必须继续维持哪些不变量+内容不仅描述模块做什么,还解释为什么这样划分职责,哪些失败路径是刻意保守处理,以及修改实现时必须继续维持哪些不变量。产品功能和操作方式见 [用户指南](../UserGuide/README.md)## 文档目标-开发者指南需要帮助读者完成 4 类工作+开发者指南需要帮助读者完成 4 类工作:-- 建立系统模型, 理解数据从哪里来, 在哪里变成状态, 最终由谁消费-- 定位修改入口, 知道某个行为的唯一状态所有者和副作用边界-- 理解设计取舍, 避免把看似多余的 generation, stale 标记或恢复步骤简化掉-- 验证改动, 能从不变量和故障场景推导验收范围+- 建立系统模型,理解数据从哪里来,在哪里变成状态,最终由谁消费+- 定位修改入口,知道某个行为的唯一状态所有者和副作用边界+- 理解设计取舍,避免把看似多余的 generation, stale 标记或恢复步骤简化掉+- 验证改动,能从不变量和故障场景推导验收范围-每篇专题文档尽量按同一顺序组织+每篇专题文档尽量按同一顺序组织:```text目标与约束@@ -29,7 +29,7 @@## 阅读路线-第一次了解项目时, 建议按以下顺序阅读+第一次了解项目时,建议按以下顺序阅读:1. [整体架构](architecture.md)2. [设计原则与关键决策](design-decisions.md)@@ -47,17 +47,17 @@| 文档 | 内容 || --- | --- |-| [整体架构](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 对账, 状态机和异常会话保护 |+| [整体架构](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) | 工程结构, 构建检查, 调试和变更验收 |+| [CloudKit 同步](sync.md) | 私有数据库、设备匿名化、上传、合并和重建 |+| [通知系统](notifications.md) | 通知触发、去重、声音、触觉和点击行为 |+| [UI 与应用生命周期](ui-and-lifecycle.md) | 菜单栏、面板、焦点、全局快捷键和服务装配 |+| [数据与隐私边界](data-and-privacy.md) | 本地文件、网络访问、云端字段和日志边界 |+| [开发与验证](development.md) | 工程结构、构建检查、调试和变更验收 |## 按修改目标查找@@ -65,8 +65,8 @@| --- | --- | --- || 新增账户或用量字段 | [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) |+| 修改任务状态或 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) |@@ -74,35 +74,35 @@## 核心设计约束-- 启动时必须先处理 `--hook-event` 模式, 该模式不能初始化 UI-- app-server 额度与用量, Hook 历史聚合, 实时任务监控是 3 条独立数据链路+- 启动时必须先处理 `--hook-event` 模式,该模式不能初始化 UI+- app-server 额度与用量、Hook 历史聚合、实时任务监控是 3 条独立数据链路- `CodexActivityMonitor` 是任务状态的唯一来源- 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 不同 |+| snapshot | 可重复读取的当前状态,不代表刚刚发生了一次事件 |+| transition | 由可信 live 输入产生的一次性状态变化,可驱动通知等副作用 |+| bootstrap | 从现有本地数据恢复内存基线,不应补发历史副作用 |+| stale | 有可展示旧值,但本轮未能从来源确认 |+| unavailable | 当前无法得到可信来源,不能等价为空或 `0` |+| generation | 数据源或异步操作的代际,用于拒绝迟到结果 |+| source generation | 某日原始 Hook 文件的来源身份,与代码 schema 不同 || owned | 系统状态由 CodexBar 完成切换并有权恢复 || external | 系统状态已经由 CodexBar 之外的来源设置 |## 阅读源码的建议-先确认状态所有者, 再沿消费者反向阅读+先确认状态所有者,再沿消费者反向阅读。-例如修改等待批准行为时, 推荐顺序是+例如修改等待批准行为时,推荐顺序是:```textCodexActivityTask@@ -113,14 +113,14 @@ CodexActivityTask-> SwiftUI View```-从 View 开始搜索通常只能看到最终展示条件, 容易漏掉 bootstrap, 去重和恢复语义+从 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)-- CodexBarHelper: [`main.swift`](../../CodexBarHelper/main.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.mdindex 34c2054..1c437ff 100644--- a/Docs/DeveloperGuide/activity-monitor.md+++ b/Docs/DeveloperGuide/activity-monitor.md@@ -2,27 +2,27 @@## 设计出发点-实时任务不是 Hook 事件的直接映射+实时任务不是 Hook 事件的直接映射。-同一个 turn 可能出现事件缺失, 迟到, 重复, 只有 session ID, 新 prompt 覆盖旧 turn, `Stop` 与 rollout terminal 先后到达, 或 App 在任务已经运行一段时间后才启动+同一个 turn 可能出现事件缺失、迟到、重复、只有 session ID、新 prompt 覆盖旧 turn、`Stop` 与 rollout terminal 先后到达,或 App 在任务已经运行一段时间后才启动。-`CodexActivityMonitor` 的工作是把这些不完整观察合并成一个保守的任务状态机, 并同时提供两种不同输出+`CodexActivityMonitor` 的工作是把这些不完整观察合并成一个保守的任务状态机,并同时提供两种不同输出:- snapshot 表示现在可以展示什么-- transition 表示刚刚发生了什么, 可以驱动一次性副作用+- transition 表示刚刚发生了什么,可以驱动一次性副作用-如果消费者各自从 Hook 列表推断任务, 菜单栏, 通知和防睡眠会在边界场景下得出不同结论+如果消费者各自从 Hook 列表推断任务,菜单栏、通知和防睡眠会在边界场景下得出不同结论。## 目标-实时任务链路需要回答 4 个问题+实时任务链路需要回答 4 个问题:- 当前是否有任务正在运行- 当前是否在等待用户批准- 最近任务是完成还是中断- 哪些运行任务已经长时间没有进展-Hook 事件提供低延迟信号, rollout 文件提供权威生命周期补充. [`CodexActivityMonitor.swift`](../../CodexBar/Services/Workflow/CodexActivityMonitor.swift) 合并两者并发布唯一任务快照+Hook 事件提供低延迟信号,rollout 文件提供权威生命周期补充。[`CodexActivityMonitor.swift`](../../CodexBar/Services/Workflow/CodexActivityMonitor.swift) 合并两者并发布唯一任务快照:```textHook JSONL -> HookEventTailReader -----+@@ -41,40 +41,40 @@ rollout JSONL -> SessionLifecycleReader+| 完成与中断分类 | rollout terminal | grace 到期 fallback || effort | Hook recorder 回查 | rollout lifecycle backfill |-Hook 优先解决低延迟, rollout 优先解决语义准确性. 两者不是简单按时间戳覆盖, 每个字段都有自己的可信来源+Hook 优先解决低延迟,rollout 优先解决语义准确性。两者不是简单按时间戳覆盖,每个字段都有自己的可信来源。### snapshot 和 transition 为什么分开-snapshot 可以在 View 重建, 新消费者订阅或设置变化时反复读取. transition 只允许 live 数据产生一次+snapshot 可以在 View 重建、新消费者订阅或设置变化时反复读取。transition 只允许 live 数据产生一次。-例如 App 启动时 bootstrap 恢复出一个已经等待批准的任务+例如 App 启动时 bootstrap 恢复出一个已经等待批准的任务:- snapshot 应显示它正在等待- transition 不应发布等待事件- 通知服务因此不会补发一条历史通知-任务完成也一样. 通知服务消费 `.completed` transition, 不扫描 `recentCompletions`, 避免 App 重启或 UI 刷新重复提醒+任务完成也一样。通知服务消费 `.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 发送+24 小时窗口可能跨两个自然日文件,单个文件又会分成多个 512 KB batch 发送。-monitor 在 `.bootstrapStart` 时先清空上一次恢复态并暂停副作用, 接收所有 `.bootstrapEvents`, 最后在 `.bootstrapEnd` 才统一+monitor 在 `.bootstrapStart` 时先清空上一次恢复态并暂停副作用,接收所有 `.bootstrapEvents`,最后在 `.bootstrapEnd` 才统一:- 用 rollout 补齐生命周期- 应用持久化异常保护记录@@ -82,33 +82,33 @@ monitor 在 `.bootstrapStart` 时先清空上一次恢复态并暂停副作用,- 定向回查缺失 prompt 起点- 发布完整 snapshot-中间 batch 不应让 UI 或通知看到半恢复状态+中间 batch 不应让 UI 或通知看到半恢复状态。### 稳定边界为什么要重试 3 次-reader 在每次尝试开始时固定所有日期文件的 inode 和 size, 读取到这些上界后再次验证+reader 在每次尝试开始时固定所有日期文件的 inode 和 size,读取到这些上界后再次验证:- 历史日期必须 inode 和 size 都不变- 当前日期允许在固定上界之后继续 append- 当前自然日不能在读取期间跨过零点-任何条件不成立都从新的基线重试. 连续 3 次失败后跳到当前文件末尾, 是为了避免 App 永远卡在 bootstrap. 代价通过 degraded health 明确传给异常保护, 而不是假装成功+任何条件不成立都从新的基线重试。连续 3 次失败后跳到当前文件末尾,是为了避免 App 永远卡在 bootstrap。代价通过 degraded health 明确传给异常保护,而不是假装成功。### 为什么只推进完整行 offset-Hook recorder 可能正在写最后一行. reader 只把最后一个 newline 之前的字节计入 `completeOffset`+Hook recorder 可能正在写最后一行。reader 只把最后一个 newline 之前的字节计入 `completeOffset`-半行不会丢弃, 也不会被当作损坏事件. 下一轮从旧 offset 重新读取, 等行完整后再提交+半行不会丢弃,也不会被当作损坏事件。下一轮从旧 offset 重新读取,等行完整后再提交。### 跨日与文件替换-正常跨日时先排空旧日期文件, 再切换到新日期文件. inode 改变或文件缩小时重新 bootstrap, 不沿用旧游标+正常跨日时先排空旧日期文件,再切换到新日期文件。inode 改变或文件缩小时重新 bootstrap,不沿用旧游标。-当 `UserPromptSubmit` 早于当前增量窗口时, reader 可以向前回查最多 8 MB, 为现存任务补齐 prompt 起点+当 `UserPromptSubmit` 早于当前增量窗口时,reader 可以向前回查最多 8 MB,为现存任务补齐 prompt 起点。### drainNow 读取屏障-`drainNow()` 不是普通的立即刷新提示. 每个调用方必须等待一轮在本次请求之后开始的读取+`drainNow()` 不是普通的立即刷新提示。每个调用方必须等待一轮在本次请求之后开始的读取:```text调用 drainNow@@ -118,83 +118,83 @@ Hook recorder 可能正在写最后一行. reader 只把最后一个 newline 之-> 返回该轮结果```-调用发生前已经在执行的读取不能满足屏障. reader 被替换, 数据源不可用或任务取消时, 调用方不能使用旧快照继续判定+调用发生前已经在执行的读取不能满足屏障。reader 被替换、数据源不可用或任务取消时,调用方不能使用旧快照继续判定。### 屏障的具体代际语义-每次 `drainNow()` 都递增 `requestedDrainGeneration` 并注册独立 waiter+每次 `drainNow()` 都递增 `requestedDrainGeneration` 并注册独立 waiter。-如果读取已经在途, 新请求只把 `hasPendingDrain` 设为 true. 当前轮完成后 reader 必须再开始一轮, 这轮才会捕获该请求的 generation+如果读取已经在途,新请求只把 `hasPendingDrain` 设为 true。当前轮完成后 reader 必须再开始一轮,这轮才会捕获该请求的 generation。-一轮读取可以同时满足在它开始前排队的多个 waiter, 但不能满足读取开始后才加入的 waiter. 这正是唤醒恢复需要的 happens-after 保证+一轮读取可以同时满足在它开始前排队的多个 waiter,但不能满足读取开始后才加入的 waiter。这正是唤醒恢复需要的 happens-after 保证。-actor 在 `await` 期间可以重入, 因此 `isProcessingReads` 和 `hasPendingDrain` 共同把所有外部请求收敛成一个串行 drain loop, 避免两个读取同时推进 offset+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 先检查最可能的少量目录+reader 先检查最可能的少量目录:1. 任务开始日期对应的 `sessions/YYYY/MM/DD`2. 当前日期目录3. `archived_sessions`-resume 可能继续很早以前创建的 session. 快速路径找不到时, 每个活跃 session 生命周期最多执行一次递归兜底, 避免每秒 poll 都扫描整个 sessions 树+resume 可能继续很早以前创建的 session。快速路径找不到时,每个活跃 session 生命周期最多执行一次递归兜底,避免每秒 poll 都扫描整个 sessions 树。-文件被移到 archive 后, 已缓存 URL 不存在会清除 cursor 并允许重新完整定位+文件被移到 archive 后,已缓存 URL 不存在会清除 cursor 并允许重新完整定位。### rollout cursor 为什么从尾部 512 KB 开始-实时任务只需要活跃 turn 附近的 lifecycle, 全量读取一个长期 session 会增加常驻 I/O+实时任务只需要活跃 turn 附近的 lifecycle,全量读取一个长期 session 会增加常驻 I/O。-初始 cursor 从最后 512 KB 开始并丢弃第一条可能不完整的行. 如果 effort 仍缺失, 对具体 turn 再定向回查最多 8 MB+初始 cursor 从最后 512 KB 开始并丢弃第一条可能不完整的行。如果 effort 仍缺失,对具体 turn 再定向回查最多 8 MB。-effort backfill 只针对至少运行 2 秒, 尚未 terminal 且仍缺 effort 的任务, 同一 turn 重试间隔 10 秒. 这避免刚创建任务时立刻做大范围回查+effort backfill 只针对至少运行 2 秒,尚未 terminal 且仍缺 effort 的任务,同一 turn 重试间隔 10 秒。这避免刚创建任务时立刻做大范围回查。### 为什么只解析结构事件-共享的 `CodexRolloutLineEnvelope` 只提取 turn context, lifecycle 和 progress 所需字段. prompt, response 和 tool 内容不会进入活动模型+共享的 `CodexRolloutLineEnvelope` 只提取 turn context, lifecycle 和 progress 所需字段。prompt, response 和 tool 内容不会进入活动模型。-这既收紧隐私边界, 也降低大 rollout 的解码成本. 新增实时字段时应先扩展这份最小 envelope, 不应把完整 transcript 解码成通用 JSON 树+这既收紧隐私边界,也降低大 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 活动, 不创建独立顶层任务卡片+subagent 事件更新父任务的 subagent 活动,不创建独立顶层任务卡片。### 身份选择为什么按精度降级-`session ID + turn ID` 能精确区分同一 session 中顺序执行的 turn, 是首选身份+`session ID + turn ID` 能精确区分同一 session 中顺序执行的 turn,是首选身份。-某些事件只有 session ID. 此时 session key 允许事件仍然参与状态, 但终态匹配必须更保守. 如果同一 session 同时存在多个候选, monitor 返回 ambiguous 而不是猜一个任务结束+某些事件只有 session ID。此时 session key 允许事件仍然参与状态,但终态匹配必须更保守。如果同一 session 同时存在多个候选,monitor 返回 ambiguous 而不是猜一个任务结束。-完全没有 session ID 时只能使用 project key. 这个 key 可能把同项目并发匿名任务合并, 所以匿名任务只承担可撤销的 UI 展示, 不驱动通知, 防睡眠或持久化保护+完全没有 session ID 时只能使用 project key。这个 key 可能把同项目并发匿名任务合并,所以匿名任务只承担可撤销的 UI 展示,不驱动通知、防睡眠或持久化保护。### 为什么新 prompt 不直接把旧 turn 判为中断-同一 session 的 turn 顺序执行. 新 prompt 到来时旧 turn 必须立即离开活跃列表, 否则 UI 会短暂显示两个顶层任务+同一 session 的 turn 顺序执行。新 prompt 到来时旧 turn 必须立即离开活跃列表,否则 UI 会短暂显示两个顶层任务。-但新 prompt 可能早于旧 turn 的 rollout terminal 到达. 直接记录中断会误判一个正常完成的任务+但新 prompt 可能早于旧 turn 的 rollout terminal 到达。直接记录中断会误判一个正常完成的任务。因此旧 turn 被移到 `pendingTerminalTasks`@@ -204,55 +204,55 @@ subagent 事件更新父任务的 subagent 活动, 不创建独立顶层任务- terminal 到达时准确分类 completed 或 aborted- grace 到期仍无终态时按保守 fallback 收口-`SessionEnd` 使用同一个终态确认窗口, 只是按 session 一次移动所有不晚于该事件的任务+`SessionEnd` 使用同一个终态确认窗口,只是按 session 一次移动所有不晚于该事件的任务。### 迟到事件如何被拒绝-任务保存 `lastActivityAt`, terminal 记忆保存完成或中断时间+任务保存 `lastActivityAt`,terminal 记忆保存完成或中断时间:- 早于当前任务最后活动的事件不覆盖新状态- 不晚于已记录 terminal 的新 prompt 不会复活旧任务- `Stop` 命中多个候选时不猜测- 已进入 terminal 去重记忆的 key 会清除异常顺序留下的恢复任务-这种比较依赖事件自身时间, 而不是 batch 到达顺序, 因为跨进程文件写入和 rollout poll 都可能让旧事件晚到+这种比较依赖事件自身时间,而不是 batch 到达顺序,因为跨进程文件写入和 rollout poll 都可能让旧事件晚到。### 匿名任务-`WorkflowHookEvent.sessionId` 缺失时, task key 使用匿名 project key. `isAnonymous` 会保留到 `CodexActivityTaskSnapshot`, `CodexActivityCompletion` 和 `CodexActivityTermination`+`WorkflowHookEvent.sessionId` 缺失时,task key 使用匿名 project key。`isAnonymous` 会保留到 `CodexActivityTaskSnapshot`, `CodexActivityCompletion` 和 `CodexActivityTermination`-匿名任务仍进入活动快照和最近终态记录. 活动卡片与任务中心统一显示橙色 `person.crop.circle.dashed` 图标, help 为 `匿名任务不参与防睡眠`. 活动卡片的 `+N` 只表示其他活跃任务总数+匿名任务仍进入活动快照和最近终态记录。活动卡片与任务中心统一显示橙色 `person.crop.circle.dashed` 图标,help 为 `匿名任务不参与防睡眠`。活动卡片的 `+N` 只表示其他活跃任务总数。-匿名运行任务不展示精确运行时长, 匿名完成和终止记录也不包含精确耗时+匿名运行任务不展示精确运行时长,匿名完成和终止记录也不包含精确耗时。-匿名任务不向通知消费者发布等待批准或完成 transition, 不触发任务触觉反馈, 不进入 KeepAlive 的运行中或等待任务集合, 不参与异常会话保护. `activityProtectionIdentifier` 对匿名 key 返回 nil, 保护状态文件不会保存匿名任务记录+匿名任务不向通知消费者发布等待批准或完成 transition、不触发任务触觉反馈、不进入 KeepAlive 的运行中或等待任务集合、不参与异常会话保护。`activityProtectionIdentifier` 对匿名 key 返回 nil,保护状态文件不会保存匿名任务记录。### 为什么匿名任务仍保留在 UI-缺少 session ID 不等于任务不存在. 完全丢弃会让用户看到 Codex 正在工作, CodexBar 却显示空闲+缺少 session ID 不等于任务不存在。完全丢弃会让用户看到 Codex 正在工作,CodexBar 却显示空闲。-保留 UI 展示同时禁止高影响副作用, 是对不确定身份的分层处理+保留 UI 展示同时禁止高影响副作用,是对不确定身份的分层处理:- 可见性错误可以由后续事件自动修正- 错误通知会打扰用户- 错误防睡眠可能持续数小时- 持久化匿名 project key 可能压制未来另一个真实任务-因此匿名任务使用橙色虚线人物图标明确表达能力受限, 而不是伪装成普通精确任务+因此匿名任务使用橙色虚线人物图标明确表达能力受限,而不是伪装成普通精确任务。## 状态机-内部活动任务主要有以下状态+内部活动任务主要有以下状态:| 状态 | 含义 || --- | --- || `running` | Codex 正在处理当前 turn || `waitingApproval` | 当前 turn 明确等待用户批准 |-| `suppressed` | 任务被异常会话保护隐藏, 等待新进展恢复 |+| `suppressed` | 任务被异常会话保护隐藏,等待新进展恢复 |-`PermissionRequest` 只有在 reviewer 是用户时才进入 `waitingApproval`. 自动审批或策略审批不会被视为用户等待+`PermissionRequest` 只有在 reviewer 是用户时才进入 `waitingApproval`。自动审批或策略审批不会被视为用户等待。-终止信号按可靠性对账+终止信号按可靠性对账:- `SessionEnd` 结束 session- rollout terminal 区分完成和中断@@ -264,7 +264,7 @@ subagent 事件更新父任务的 subagent 活动, 不创建独立顶层任务| 当前状态 | 输入 | 新状态 | 额外动作 || --- | --- | --- | --- || 不存在 | `UserPromptSubmit` | running | 保存可信 startedAt |-| 不存在 | 顶层 tool 或 compact | 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 和保护记录 |@@ -275,37 +275,37 @@ subagent 事件更新父任务的 subagent 活动, 不创建独立顶层任务### waiting approval 为什么采用两阶段确认-`PermissionRequest` 说明进入审批流程, 但 reviewer 可能是 user, policy 或 auto review+`PermissionRequest` 说明进入审批流程,但 reviewer 可能是 user, policy 或 auto review。-Hook event 到达时如果已经带有 reviewer, task 可以立即确认. reviewer 缺失时先保存 `pendingApprovalRequestedAt`, rollout poll 补齐后再决定是否进入 `waitingApproval`+Hook event 到达时如果已经带有 reviewer,task 可以立即确认。reviewer 缺失时先保存 `pendingApprovalRequestedAt`,rollout poll 补齐后再决定是否进入 `waitingApproval`-只有 reviewer 明确为 user 才发布 waiting transition. 不确定时维持 running 比误报用户正在被等待更符合事实+只有 reviewer 明确为 user 才发布 waiting transition。不确定时维持 running 比误报用户正在被等待更符合事实。### effort 为什么可能变成 `mixed`-同一 turn 的多个上下文事件可能报告不同 reasoning effort. Task 不让最后一条静默覆盖前一条, 而是在观察到冲突后标记为 `mixed`+同一 turn 的多个上下文事件可能报告不同 reasoning effort。Task 不让最后一条静默覆盖前一条,而是在观察到冲突后标记为 `mixed`-这向 UI 表达任务生命周期内确实出现过多个值, 避免展示一个看似精确但只代表最后观察的 effort+这向 UI 表达任务生命周期内确实出现过多个值,避免展示一个看似精确但只代表最后观察的 effort。### subagent 数为什么允许 unknown-subagent 的 turn ID 属于 subagent 自己, 父任务只能通过共享 session 关联+subagent 的 turn ID 属于 subagent 自己,父任务只能通过共享 session 关联。-只有同 session 恰好有一个 active 父任务, 没有 pending terminal 歧义, 并且 start/stop 带稳定 agent ID 时, active subagent count 才可靠+只有同 session 恰好有一个 active 父任务、没有 pending terminal 歧义,并且 start/stop 带稳定 agent ID 时,active subagent count 才可靠。-缺少 ID, 先看到 stop 或同 session 有多个候选时, monitor 将可靠性降为 false, UI 不展示伪精确数字+缺少 ID、先看到 stop 或同 session 有多个候选时,monitor 将可靠性降为 false,UI 不展示伪精确数字。## 快照优先级-多个任务和短时状态同时存在时, 对外快照按以下优先级表达+多个任务和短时状态同时存在时,对外快照按以下优先级表达:```text等待批准 > 运行中 > 最近完成 > 最近中断 > 空闲```-完成状态在菜单栏保留 30 秒绿色提示. 活动中心保留最近 10 分钟任务, terminal 去重记忆保留 24 小时+完成状态在菜单栏保留 30 秒绿色提示。活动中心保留最近 10 分钟任务,terminal 去重记忆保留 24 小时。-快照由以下模块消费+快照由以下模块消费:- 菜单栏状态点- 主面板任务卡片@@ -315,33 +315,33 @@ subagent 的 turn ID 属于 subagent 自己, 父任务只能通过共享 session### 为什么最近完成和最近中断有不同展示权重-完成会在菜单栏保留 30 秒绿色高亮, 这是短时正反馈. 中断只进入最近记录, 不发布完成 transition, 也不显示绿色状态+完成会在菜单栏保留 30 秒绿色高亮,这是短时正反馈。中断只进入最近记录、不发布完成 transition,也不显示绿色状态。-任务中心保留 terminal 10 分钟, 但用于防止迟到事件重复完成的 key 会保留 24 小时. 展示期限和去重期限解决不同问题, 不能为了"统一缓存"合并+任务中心保留 terminal 10 分钟,但用于防止迟到事件重复完成的 key 会保留 24 小时。展示期限和去重期限解决不同问题,不能为了“统一缓存”合并。### 为什么只在快照变化时发布-monitor 每秒 poll rollout, 还会按多个 deadline 自行刷新. 如果每轮都给 `@Published` 赋相同值, SwiftUI 和所有 Combine 消费者会重复计算+monitor 每秒 poll rollout,还会按多个 deadline 自行刷新。如果每轮都给 `@Published` 赋相同值,SwiftUI 和所有 Combine 消费者会重复计算。-新快照先与当前值比较, 只有结构变化才发布. 运行时长文案由 View 使用当前时间格式化, 不要求每秒修改任务对象+新快照先与当前值比较,只有结构变化才发布。运行时长文案由 View 使用当前时间格式化,不要求每秒修改任务对象。### 排序为什么有稳定兜底-同一 batch 中多个任务可能具有相同时间戳, Swift sort 又不是稳定排序+同一 batch 中多个任务可能具有相同时间戳,Swift sort 又不是稳定排序。-所有列表先按最近时间降序, 时间相同再按 display UUID 字符串排序. 稳定顺序让 SwiftUI diff 不会因为等价任务随机交换位置而产生跳动+所有列表先按最近时间降序,时间相同再按 display UUID 字符串排序。稳定顺序让 SwiftUI diff 不会因为等价任务随机交换位置而产生跳动。### 清理采用最近 deadline-monitor 同时管理完成高亮, terminal grace, 活动保留, 历史保留, terminal 去重和保护记录过期+monitor 同时管理完成高亮、terminal grace、活动保留、历史保留、terminal 去重和保护记录过期。-它不使用固定高频 timer 扫描所有状态, 而是收集所有未来 deadline, 只为最近一项安排 Task. 到点刷新后再计算下一项+它不使用固定高频 timer 扫描所有状态,而是收集所有未来 deadline,只为最近一项安排 Task。到点刷新后再计算下一项。-这种实现减少常驻菜单栏 App 的无意义唤醒, 也保证每种保留期都能在没有新 Hook 事件时准时生效+这种实现减少常驻菜单栏 App 的无意义唤醒,也保证每种保留期都能在没有新 Hook 事件时准时生效。## 系统睡眠与唤醒-系统即将睡眠时暂停异常会话保护判断. 唤醒后执行严格恢复顺序+系统即将睡眠时暂停异常会话保护判断。唤醒后执行严格恢复顺序:1. 进入恢复状态并继续暂停保护2. 等待 `HookEventTailReader.drainNow()` 成功@@ -349,46 +349,46 @@ monitor 同时管理完成高亮, terminal grace, 活动保留, 历史保留, te4. 使用新 Hook 结果和 rollout 结果统一对账5. 恢复异常会话保护判断-如果新一轮读取失败, reader 被更换或数据源不可用, 不得使用睡眠前快照继续判断任务静默+如果新一轮读取失败、reader 被更换或数据源不可用,不得使用睡眠前快照继续判断任务静默。### 为什么系统睡眠期间必须暂停静默计时-系统睡眠时 Hook 与 rollout 都不会正常产生进展. 如果只比较墙上时间, 一次两小时睡眠会让所有运行任务在唤醒瞬间被判为异常静默+系统睡眠时 Hook 与 rollout 都不会正常产生进展。如果只比较墙上时间,一次两小时睡眠会让所有运行任务在唤醒瞬间被判为异常静默。-保护计时使用 `SuspendingClock` 安排下一次检查, 但系统时间变化和数据源恢复仍需要显式重算. will-sleep 先进入 recovery, did-wake 再通过新的数据读取屏障恢复判定+保护计时使用 `SuspendingClock` 安排下一次检查,但系统时间变化和数据源恢复仍需要显式重算。will-sleep 先进入 recovery,did-wake 再通过新的数据读取屏障恢复判定。### 唤醒顺序为何不能交换-rollout 对账必须发生在 Hook drain 成功之后+rollout 对账必须发生在 Hook drain 成功之后。-如果先读 rollout, 此时 monitor 中可能还没有睡眠期间刚追加的任务 key, lifecycle 结果无法关联. 如果先恢复保护判定, 则会基于睡前 last progress 误隐藏任务+如果先读 rollout,此时 monitor 中可能还没有睡眠期间刚追加的任务 key,lifecycle 结果无法关联。如果先恢复保护判定,则会基于睡前 last progress 误隐藏任务。-`readerGeneration` 防止唤醒 Task 返回时 reader 已因 Hook 设置变化被替换. `recoveryGeneration` 防止两次睡眠或设置变化交错后, 较早恢复流程提前解除暂停+`readerGeneration` 防止唤醒 Task 返回时 reader 已因 Hook 设置变化被替换。`recoveryGeneration` 防止两次睡眠或设置变化交错后,较早恢复流程提前解除暂停。## 异常会话保护-异常会话保护只在防睡眠主开关开启时工作, 只处理非匿名 `running` 任务+异常会话保护只在防睡眠主开关开启时工作,只处理非匿名 `running` 任务。-等待批准任务不参与静默阈值判断. 原因是等待批准本身就是一个合法的无进展状态+等待批准任务不参与静默阈值判断。原因是等待批准本身就是一个合法的无进展状态。-可选阈值为+可选阈值为:- 30 分钟-- 1 小时, 默认值+- 1 小时(默认值)- 2 小时- 4 小时-任务达到阈值后+任务达到阈值后:1. 先持久化保护记录2. 同时启动通知提交和 3 秒 grace3. 通知提交完成或 grace 到期后再次校验候选4. 候选仍有效时从活动快照隐藏任务-5. 如果期间或之后出现新进展, 清除保护并恢复展示+5. 如果期间或之后出现新进展,清除保护并恢复展示-隐藏任务不依赖通知成功. 3 秒只是等待解释性通知提交的最大时间, 到期后仍会释放防睡眠+隐藏任务不依赖通知成功。3 秒只是等待解释性通知提交的最大时间,到期后仍会释放防睡眠。-保护判断在以下阶段暂停+保护判断在以下阶段暂停:- Hook bootstrap- 系统睡眠@@ -398,53 +398,53 @@ rollout 对账必须发生在 Hook drain 成功之后### 保护针对的故障模型-Hook 或 Codex 异常退出后, 可能缺少 `Stop`, `SessionEnd` 和 rollout terminal. 任务会一直停在 running, 进而让防睡眠永久生效+Hook 或 Codex 异常退出后,可能缺少 `Stop`, `SessionEnd` 和 rollout terminal。任务会一直停在 running,进而让防睡眠永久生效。-异常会话保护不是判断 Codex 是否"真的卡住", 它只处理一个可观察事实: 非匿名 running 任务在可信数据源下超过阈值没有任何 Hook 或 rollout 进展+异常会话保护不是判断 Codex 是否“真的卡住”,它只处理一个可观察事实:非匿名 running 任务在可信数据源下超过阈值没有任何 Hook 或 rollout 进展。-等待批准被排除, 因为等待用户本来就是合法静默. 匿名任务被排除, 因为 project key 不足以证明保护记录属于哪一个具体任务+等待批准被排除,因为等待用户本来就是合法静默。匿名任务被排除,因为 project key 不足以证明保护记录属于哪一个具体任务。### progress generation 的作用-只比较时间戳不足以保护异步尝试. 两条进展可能具有相同秒级时间, 设置阈值也可能在通知提交期间变化+只比较时间戳不足以保护异步尝试。两条进展可能具有相同秒级时间,设置阈值也可能在通知提交期间变化。-每次有效进展都会递增 `progressGeneration`. 保护候选保存+每次有效进展都会递增 `progressGeneration`。保护候选保存:- task display ID- last progress timestamp- progress generation- 当时的阈值-通知返回或 3 秒 grace 到期时, 四项都必须仍匹配才允许 suppress. 任意新进展或阈值变化都会让旧尝试失效+通知返回或 3 秒 grace 到期时,四项都必须仍匹配才允许 suppress。任意新进展或阈值变化都会让旧尝试失效。### 为什么先持久化再隐藏-一旦任务从快照隐藏, App 可能随即退出或系统休眠. 如果保护记录还没有进入持久化队列, 重启 bootstrap 会再次展示并重新支撑防睡眠+一旦任务从快照隐藏,App 可能随即退出或系统休眠。如果保护记录还没有进入持久化队列,重启 bootstrap 会再次展示并重新支撑防睡眠。-因此候选开始时先写入记录, 再等待通知提交, 最后隐藏. 通知权限或系统服务失败不影响 suppress, 因为释放错误防睡眠才是保护的核心目标+因此候选开始时先写入记录、再等待通知提交、最后隐藏。通知权限或系统服务失败不影响 suppress,因为释放错误防睡眠才是保护的核心目标。### 3 秒通知宽限的含义-保护通知是有价值的解释, 但不能无限阻塞释放防睡眠+保护通知是有价值的解释,但不能无限阻塞释放防睡眠:- 通知先成功提交时立即完成 suppress- 3 秒内仍未完成时直接 suppress- 通知稍后成功返回但 attempt 已失效时立即撤回- grace 内出现新进展时取消 attempt 和持久化记录-这个窗口只约束通知副作用, 不改变静默阈值本身+这个窗口只约束通知副作用,不改变静默阈值本身。### 阈值改变如何对账-阈值变短时, 已经超过新阈值的 running 任务会立即重新判定+阈值变短时,已经超过新阈值的 running 任务会立即重新判定。-阈值变长时, 尚未超过新阈值的 suppressed 任务会静默恢复, 清除对应保护记录和通知. 已经仍超过新阈值的任务继续 suppressed, 不制造重复通知+阈值变长时,尚未超过新阈值的 suppressed 任务会静默恢复,清除对应保护记录和通知。已经仍超过新阈值的任务继续 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@@ -456,34 +456,34 @@ Hook 或 Codex 异常退出后, 可能缺少 `Stop`, `SessionEnd` 和 rollout te- Debug 与 Release 通过 `flock` 共用文件- 记录最长保留到最后进展后的 24 小时-任务身份使用 SHA-256 摘要, 不把 session ID 或 turn ID 原文写入该状态文件. 匿名任务没有保护标识, 不写入该文件+任务身份使用 SHA-256 摘要,不把 session ID 或 turn ID 原文写入该状态文件。匿名任务没有保护标识,不写入该文件。### 哈希身份的构造-turn 和 session key 先使用带类型前缀与 NUL 分隔的 canonical 字符串, 再加固定 domain separator `CodexBar.ActivityProtection.v1` 执行 SHA-256+turn 和 session key 先使用带类型前缀与 NUL 分隔的 canonical 字符串,再加固定 domain separator `CodexBar.ActivityProtection.v1` 执行 SHA-256。-类型和分隔符避免不同字段拼接后产生边界歧义. domain separator 避免同一原始 ID 在其他用途中的 hash 被直接关联+类型和分隔符避免不同字段拼接后产生边界歧义。domain separator 避免同一原始 ID 在其他用途中的 hash 被直接关联。-这不是用来抵抗已知 session ID 的穷举, 而是避免状态文件直接泄露可读身份并限制跨用途关联+这不是用来抵抗已知 session ID 的穷举,而是避免状态文件直接泄露可读身份并限制跨用途关联。### Debug 与 Release 为什么共享文件还要加锁-两个 App bundle ID 可以同时运行, 但都观察同一份 Codex Hook 数据. 如果各自保存独立保护状态, 一个版本隐藏的异常任务可能被另一个版本重新用于防睡眠+两个 App bundle ID 可以同时运行,但都观察同一份 Codex Hook 数据。如果各自保存独立保护状态,一个版本隐藏的异常任务可能被另一个版本重新用于防睡眠。-状态 store 使用 actor 串行单进程访问, 再用 `flock` 保护跨进程 read-modify-write. removal 还可以附带 `matchingMarkedAt`, 防止旧进程的迟到删除误删另一进程刚写入的新记录+状态 store 使用 actor 串行单进程访问,再用 `flock` 保护跨进程 read-modify-write。removal 还可以附带 `matchingMarkedAt`,防止旧进程的迟到删除误删另一进程刚写入的新记录。-写入按 task identifier 稳定排序并原子替换, 文件权限最终校正为 `0600`+写入按 task identifier 稳定排序并原子替换,文件权限最终校正为 `0600`## 代际和旧结果隔离-Monitor 为 reader 和异步恢复任务维护 generation+Monitor 为 reader 和异步恢复任务维护 generation:- reader 更换后丢弃旧 reader 的迟到结果- bootstrap 未完成时不发布转场副作用- 取消的 drain 不满足恢复屏障- 数据源显式不健康时不沿用最后健康快照做静默判断-这些约束避免系统唤醒, Hook 重装或 `CODEX_HOME` 变化时出现错误完成通知和错误释放+这些约束避免系统唤醒、Hook 重装或 `CODEX_HOME` 变化时出现错误完成通知和错误释放。### monitor 中的主要 generation@@ -491,39 +491,39 @@ Monitor 为 reader 和异步恢复任务维护 generation| --- | --- || `tailReaderGeneration` | reader batch, rollout poll 和 prompt backfill || `bootstrapCompletionGeneration` | 多次 bootstrap 重试后的异步 lifecycle 补齐 |-| `activityProtectionRecoveryGeneration` | 睡眠, 唤醒和数据源恢复 |+| `activityProtectionRecoveryGeneration` | 睡眠、唤醒和数据源恢复 || task `progressGeneration` | 通知宽限期间的保护候选 |-每一项都对应不同的"当前性"问题, 不能合并成一个全局计数. 例如 reader 没变但任务有新进展时, 只需要让 protection attempt 失效, 不应丢弃整个 reader+每一项都对应不同的“当前性”问题,不能合并成一个全局计数。例如 reader 没变但任务有新进展时,只需要让 protection attempt 失效,不应丢弃整个 reader。## 扩展任务状态机的步骤-1. 先确定新输入是事实, metadata, progress 还是 terminal-2. 定义 bootstrap 与 live 是否产生相同 snapshot, 是否允许 transition+1. 先确定新输入是事实、metadata、progress 还是 terminal+2. 定义 bootstrap 与 live 是否产生相同 snapshot,是否允许 transition3. 定义事件缺少 turn 或 session ID 时的降级行为4. 定义迟到和重复输入如何用 timestamp, terminal memory 或 generation 拒绝-5. 如果读取 rollout 新字段, 扩展最小 envelope 而不是读取正文-6. 在 `CodexActivityTask` 中维护领域状态, 在 monitor 中维护跨任务关联+5. 如果读取 rollout 新字段,扩展最小 envelope 而不是读取正文+6. 在 `CodexActivityTask` 中维护领域状态,在 monitor 中维护跨任务关联7. 更新 snapshot 前确认通知和防睡眠是否应该消费新状态-8. 为系统睡眠, reader 替换和数据源不健康定义恢复路径-9. 匿名任务默认不能获得新的高影响副作用, 除非身份可靠性发生根本变化+8. 为系统睡眠、reader 替换和数据源不健康定义恢复路径+9. 匿名任务默认不能获得新的高影响副作用,除非身份可靠性发生根本变化## 建议验证的故障场景-- App 在任务已运行时启动, bootstrap 展示任务但不补发通知+- App 在任务已运行时启动,bootstrap 展示任务但不补发通知- bootstrap 文件持续追加时能重试并最终获得稳定边界-- 连续 3 次不稳定后进入 degraded, 不启动异常静默判断-- 新 prompt 立即替换旧 turn, rollout terminal 在 5 秒内准确补分类+- 连续 3 次不稳定后进入 degraded,不启动异常静默判断+- 新 prompt 立即替换旧 turn,rollout terminal 在 5 秒内准确补分类- 同 session 多个 terminal 候选时不猜测 `Stop` 归属- reviewer 缺失后由 rollout 确认为 user 才进入等待- auto review 始终不发布等待 transition- subagent 关联不可靠时 UI 不展示伪精确数量- reader 进行中调用 `drainNow()` 必须再执行一轮新读取- 唤醒 drain 失败时保护继续暂停-- 静默候选在 3 秒窗口内出现进展后不隐藏, 迟到通知被撤回+- 静默候选在 3 秒窗口内出现进展后不隐藏,迟到通知被撤回- 阈值调长后未超新阈值的 suppressed 任务恢复- Debug 与 Release 并发更新保护记录时新记录不被旧 removal 删除-- 匿名任务始终不进入 transition, KeepAlive 和保护状态文件+- 匿名任务始终不进入 transition、KeepAlive 和保护状态文件## 关键源码diff --git a/Docs/DeveloperGuide/app-server.md b/Docs/DeveloperGuide/app-server.mdindex e34812f..8fd94e7 100644--- a/Docs/DeveloperGuide/app-server.md+++ b/Docs/DeveloperGuide/app-server.md@@ -2,28 +2,28 @@## 设计出发点-CodexBar 不重新实现 Codex 登录, token 刷新和账户协议, 而是把本机 `codex app-server` 作为账户能力边界+CodexBar 不重新实现 Codex 登录、token 刷新和账户协议,而是把本机 `codex app-server` 作为账户能力边界。-这样做的原因是+这样做的原因是:-- 认证和服务端协议由 Codex 自己维护, CodexBar 不复制一套容易漂移的客户端-- App 通过 stdio 与本机子进程通信, 账户主链路不需要直接暴露额外网络实现-- 当前真正运行的 Codex 版本可以从 handshake 获得, 能用于 Hook 能力判断+- 认证和服务端协议由 Codex 自己维护,CodexBar 不复制一套容易漂移的客户端+- App 通过 stdio 与本机子进程通信,账户主链路不需要直接暴露额外网络实现+- 当前真正运行的 Codex 版本可以从 handshake 获得,能用于 Hook 能力判断- 全局 CLI 与 App 内置 CLI 可以共享同一套上层数据模型-代价是菜单栏 App 必须自己解决 shell 环境缺失, 子进程生命周期, pipe 背压, 混杂 stdout, 超时和升级后的连接换代+代价是菜单栏 App 必须自己解决 shell 环境缺失、子进程生命周期、pipe 背压、混杂 stdout、超时和升级后的连接换代。## 职责-app-server 链路负责读取 Codex 账户和服务端状态+app-server 链路负责读取 Codex 账户和服务端状态:- 当前账户和套餐- 5 小时额度和周额度- token 用量与用量历史- Reset Credits 状态-- Hook 功能开关, handler 列表和配置写入能力+- Hook 功能开关、handler 列表和配置写入能力-这条链路不负责 Hook 历史统计, 也不负责实时任务状态+这条链路不负责 Hook 历史统计,也不负责实时任务状态。### 输入与输出边界@@ -38,20 +38,20 @@ CodexCLIResolver-> 菜单栏与主面板```-`CodexStatusService` 拥有连接和同账户缓存. `CodexStatusViewModel` 只拥有 UI 级加载状态, 自动刷新节奏和最后一次连接信息+`CodexStatusService` 拥有连接和同账户缓存。`CodexStatusViewModel` 只拥有 UI 级加载状态、自动刷新节奏和最后一次连接信息。-这个分工让设置页可以复用同一个 app-server session 读写 Hook 与 TUI 配置, 同时不让 View 直接持有 `Process` 或 pipe+这个分工让设置页可以复用同一个 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@@ -65,35 +65,35 @@ CodexCLIResolver/sbin```-数据目录优先使用 `CODEX_HOME`, 未设置时使用真实用户主目录下的 `~/.codex`+数据目录优先使用 `CODEX_HOME`,未设置时使用真实用户主目录下的 `~/.codex`### 为什么不能直接信任进程环境-从 Finder 或登录项启动的 `LSUIElement` App 通常没有用户交互式 shell 注入的完整 `PATH`. 如果只调用 `/usr/bin/env codex`, Homebrew, Volta 或 npm 全局安装会在 Terminal 中可用, 在 CodexBar 中却不可见+从 Finder 或登录项启动的 `LSUIElement` App 通常没有用户交互式 shell 注入的完整 `PATH`。如果只调用 `/usr/bin/env codex`,Homebrew, Volta 或 npm 全局安装会在 Terminal 中可用,在 CodexBar 中却不可见。-resolver 会做 3 层归一化+resolver 会做 3 层归一化:-1. 使用 `getpwuid(getuid())` 解析真实登录用户主目录, 避免继承 Xcode 或容器环境的错误 `HOME`-2. 保留现有 `PATH`, 再按顺序补充常见目录并去重-3. 对候选路径解析 symlink 和 standardized URL, 避免同一内置 binary 同时被识别成 global 与 bundled+1. 使用 `getpwuid(getuid())` 解析真实登录用户主目录,避免继承 Xcode 或容器环境的错误 `HOME`+2. 保留现有 `PATH`,再按顺序补充常见目录并去重+3. 对候选路径解析 symlink 和 standardized URL,避免同一内置 binary 同时被识别成 global 与 bundled-全局 CLI 优先是一个明确的产品选择. 开发者主动安装的 CLI 通常代表其期望版本, 内置 CLI 只是找不到全局版本时的可用回退+全局 CLI 优先是一个明确的产品选择。开发者主动安装的 CLI 通常代表其期望版本,内置 CLI 只是找不到全局版本时的可用回退。### 磁盘版本和运行版本为什么分开-设置页可以读取磁盘上两个候选 CLI 的版本, 但 Hook 能力检查只使用 `initialize` 返回的 app-server `userAgent`+设置页可以读取磁盘上两个候选 CLI 的版本,但 Hook 能力检查只使用 `initialize` 返回的 app-server `userAgent`-原因是连接最长复用 1 小时. 用户在连接存活期间升级磁盘 binary 后, 当前进程仍然是旧版本. 用磁盘版本判断会让 UI 声称 Hook 可用, 实际调用的旧 app-server 却不支持对应方法+原因是连接最长复用 1 小时。用户在连接存活期间升级磁盘 binary 后,当前进程仍然是旧版本。用磁盘版本判断会让 UI 声称 Hook 可用,实际调用的旧 app-server 却不支持对应方法。## 进程与协议-CodexBar 启动以下命令并通过 stdio 通信+CodexBar 启动以下命令并通过 stdio 通信:```bashcodex app-server --listen stdio://```-协议是逐行 JSON-RPC. 建立连接后先发送 `initialize`, 再发送 `initialized`, 然后读取账户+协议是逐行 JSON-RPC。建立连接后先发送 `initialize`,再发送 `initialized`,然后读取账户:```text启动子进程@@ -104,7 +104,7 @@ codex app-server --listen stdio://-> account/usage/read```-stdout 可能包含非 JSON 输出. pipe reader 会持续读取完整行, 只把能够解码且 response id 匹配的消息交给等待中的请求. stderr 独立排空, 防止子进程因管道写满而阻塞+stdout 可能包含非 JSON 输出。pipe reader 会持续读取完整行,只把能够解码且 response id 匹配的消息交给等待中的请求。stderr 独立排空,防止子进程因管道写满而阻塞。### 一次建连的完整事务@@ -120,76 +120,76 @@ stdout 可能包含非 JSON 输出. pipe reader 会持续读取完整行, 只把-> account 缺失: 关闭进程并返回 notLoggedIn```-只有 handshake 与首次账户读取都成功, connection 才进入 service 状态. 半初始化 session 不会被留给下一轮复用+只有 handshake 与首次账户读取都成功,connection 才进入 service 状态。半初始化 session 不会被留给下一轮复用。### 为什么 stdout reader 只暴露完整行-app-server 的 framing 是一行一个 JSON message. pipe 回调收到的 `Data` 块可能+app-server 的 framing 是一行一个 JSON message。pipe 回调收到的 `Data` 块可能:- 只包含半行- 同时包含多行- 在 JSON 行之间混有普通日志- 在进程结束时留下没有换行的最后一行-`PipeReadBuffer` 因而自己维护 byte buffer, 只在看到换行时发布完整非空行. 会话层先轻量解码 response id, 只有 id 匹配才完整解码 result 或 error+`PipeReadBuffer` 因而自己维护 byte buffer,只在看到换行时发布完整非空行。会话层先轻量解码 response id,只有 id 匹配才完整解码 result 或 error。-这既避免把日志误判成协议错误, 也让大响应只进行一次完整泛型解码+这既避免把日志误判成协议错误,也让大响应只进行一次完整泛型解码。### 为什么 stderr 也必须持续读取-即使 CodexBar 不展示 stderr 正文, 也必须 drain pipe. 子进程 pipe buffer 有上限, 如果父进程从不读取 stderr, app-server 写满后会阻塞, 随后的 stdout response 也不会到达+即使 CodexBar 不展示 stderr 正文,也必须 drain pipe。子进程 pipe buffer 有上限,如果父进程从不读取 stderr,app-server 写满后会阻塞,随后的 stdout response 也不会到达。-`PipeDrain` 不解析内容, 只消除背压. 这是进程正确性要求, 不是日志功能+`PipeDrain` 不解析内容,只消除背压。这是进程正确性要求,不是日志功能。### 关闭策略-session 关闭时按以下顺序收口+session 关闭时按以下顺序收口:1. 停止 stdout 和 stderr reader-2. 关闭 stdin 写端, 给 app-server 正常感知 EOF 的机会+2. 关闭 stdin 写端,给 app-server 正常感知 EOF 的机会3. 最多等待 1 秒优雅退出-4. 仍未退出时发送强制终止, 再等待 0.5 秒+4. 仍未退出时发送强制终止,再等待 0.5 秒5. 仍存活则记录诊断错误-进程提前退出后继续写 pipe 可能触发 `SIGPIPE`. service 在初始化时忽略该 signal, 让写入以 Swift error 返回并进入 transport failure 重建路径, 而不是杀死整个菜单栏 App+进程提前退出后继续写 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 版本缺少能力. 每分钟重复调用只会制造日志和延迟+method unsupported 通常代表当前 app-server 版本缺少能力。每分钟重复调用只会制造日志和延迟。-但这个结论不能永久保存到 UserDefaults. 新连接可能来自升级后的 binary, 因此 unsupported 集合只属于 `AppServerSession`, 连接重建后重新探测+但这个结论不能永久保存到 UserDefaults。新连接可能来自升级后的 binary,因此 unsupported 集合只属于 `AppServerSession`,连接重建后重新探测。### 为什么配置也复用这条连接-`config/read`, `hooks/list` 和 `config/batchWrite` 需要与账户刷新使用同一个实际 app-server 来源+`config/read`, `hooks/list` 和 `config/batchWrite` 需要与账户刷新使用同一个实际 app-server 来源。-如果设置页另起一套 resolver 或进程, 可能出现主面板连接全局 CLI, Hook 校验却连接内置 CLI 的分裂状态. 统一 service 保证能力检查, 配置来源和运行版本来自同一个进程选择+如果设置页另起一套 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 会话已经不可信。### 连接状态机@@ -207,7 +207,7 @@ ready-> account missing after refresh: close and notLoggedIn```-1 小时不是数据刷新周期, 而是连接最长寿命. 定期重建的主要价值是让后台升级后的 Codex binary 最迟在一个连接周期后生效+1 小时不是数据刷新周期,而是连接最长寿命。定期重建的主要价值是让后台升级后的 Codex binary 最迟在一个连接周期后生效。### 错误分类矩阵@@ -219,28 +219,28 @@ ready| authentication required | 本轮统一刷新 token 后再试 | 保留或转未登录 | 全程最多刷新 1 次 || timeout, pipe close, invalid transport | 失败 | 立即丢弃 | 仅复用连接时重建 1 次 |-限制重建次数是为了避免故障状态下反复拉起子进程. 一轮刷新结束后, 下一次正常定时刷新仍有新的尝试机会+限制重建次数是为了避免故障状态下反复拉起子进程。一轮刷新结束后,下一次正常定时刷新仍有新的尝试机会。### 为什么认证刷新全程只有一次-一次刷新会读取 account, rate limits, usage 和 Reset Credits. 多个接口可能同时发现 token 过期+一次刷新会读取 account, rate limits, usage 和 Reset Credits。多个接口可能同时发现 token 过期。-`fetchData` 内部用同一个 `didRefresh` 锁存本轮刷新资格. 第一个认证失败触发 `account/read(refreshToken: true)`, 后续接口复用刷新结果. 再次需要认证时直接归类为未登录+`fetchData` 内部用同一个 `didRefresh` 锁存本轮刷新资格。第一个认证失败触发 `account/read(refreshToken: true)`,后续接口复用刷新结果。再次需要认证时直接归类为未登录。-这避免一轮 UI 刷新对同一凭据连续触发多次 token refresh, 也让 Reset Credits 的 `401` 或 `403` 与 app-server 方法共享同一个认证预算+这避免一轮 UI 刷新对同一凭据连续触发多次 token refresh,也让 Reset Credits 的 `401` 或 `403` 与 app-server 方法共享同一个认证预算。## 刷新模型-状态 ViewModel 默认每 60 秒刷新. 用户也可以在主面板双击刷新按钮立即触发+状态 ViewModel 默认每 60 秒刷新。用户也可以在主面板双击刷新按钮立即触发。-一次刷新先解析账户, 再读取额度和用量. 补充数据缓存严格绑定到账户身份+一次刷新先解析账户,再读取额度和用量。补充数据缓存严格绑定到账户身份:- 账户不变且补充请求失败时可以继续展示缓存值- 账户变化时立即清空旧账户缓存- 服务端明确不支持的方法显示为来源缺失- 来源缺失不能转换为业务值 `0`-刷新任务通过协调器合并, 避免定时刷新, 面板打开和手动刷新并发创建重复请求+刷新任务通过协调器合并,避免定时刷新、面板打开和手动刷新并发创建重复请求。### 一次刷新如何组装快照@@ -255,9 +255,9 @@ ready-> MainActor 提交 loadState 与连接信息```-rate limits 与 usage 是补充数据. 只要账户有效, 即使两个接口都没有数据, 仍然生成快照让 UI 展示账户和明确的"暂无数据"+rate limits 与 usage 是补充数据。只要账户有效,即使两个接口都没有数据,仍然生成快照让 UI 展示账户和明确的“暂无数据”。-如果因为补充接口缺失就把整轮标成未登录, 用户会看到身份状态在真实登录和错误之间抖动, 也无法区分认证问题与单个新接口不支持+如果因为补充接口缺失就把整轮标成未登录,用户会看到身份状态在真实登录和错误之间抖动,也无法区分认证问题与单个新接口不支持。### 缓存决策表@@ -269,40 +269,40 @@ rate limits 与 usage 是补充数据. 只要账户有效, 即使两个接口都| method unsupported | 任意 | `nil` | 不适用 || 账户变化 | 旧账户缓存 | 先整体清空 | 不适用 |-method unsupported 不使用旧缓存, 因为它是明确能力结论. 普通请求失败使用缓存, 因为来源可能只是一轮暂时故障+method unsupported 不使用旧缓存,因为它是明确能力结论。普通请求失败使用缓存,因为来源可能只是一轮暂时故障。### stale 如何影响消费者-- UI 可以展示旧值, 但降低菜单栏和进度条透明度+- UI 可以展示旧值,但降低菜单栏和进度条透明度- `hasTrustedData` 只把非 stale 的额度或用量算作可信- 额度通知完全跳过 stale rate limits-- 系统日志只记录 step 为 `cached`, 不记录实际额度数值+- 系统日志只记录 step 为 `cached`,不记录实际额度数值-stale 是数据可信度的一部分, 新增展示时不能只复制数值而丢掉标记+stale 是数据可信度的一部分,新增展示时不能只复制数值而丢掉标记。### 刷新协调器为什么还需要 generation-`isRefreshing` guard 可以阻止普通重复触发, 但 cancellation 和对象生命周期仍可能让旧 Task 返回+`isRefreshing` guard 可以阻止普通重复触发,但 cancellation 和对象生命周期仍可能让旧 Task 返回。-`RefreshTaskCoordinator` 每次开始先推进 generation, 取消旧 Task, 最终只有 `canCommit(generation)` 成立的结果可以写回 UI. 这让"最后发起的刷新获胜"成为显式规则+`RefreshTaskCoordinator` 每次开始先推进 generation,取消旧 Task,最终只有 `canCommit(generation)` 成立的结果可以写回 UI。这让“最后发起的刷新获胜”成为显式规则。-自动刷新每轮按距离上次完成的剩余时间等待. 手动刷新完成后倒计时自然重新对齐, 不会在几秒后又被原来的 timer 立刻刷新一次+自动刷新每轮按距离上次完成的剩余时间等待。手动刷新完成后倒计时自然重新对齐,不会在几秒后又被原来的 timer 立刻刷新一次。### 模型层的小优化`CodexUsageSnapshot` 构造时把可能重复的 daily bucket 聚合成 `tokensByDate`-热力图在一次渲染中会反复查询日期. 提前构造索引避免每个方块都线性扫描原始 bucket, 同时保留原始数组用于快照相等比较+热力图在一次渲染中会反复查询日期。提前构造索引避免每个方块都线性扫描原始 bucket,同时保留原始数组用于快照相等比较。-额度 limit 的展示顺序也在模型层统一+额度 limit 的展示顺序也在模型层统一:- app-server 顶层 `rateLimits` 指向的主 limit 优先- 其余按本地化名称和 limit id 稳定排序-- primary 与 secondary 使用稳定枚举, View 不根据标签字符串猜测窗口类型+- 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 请求:```texthttps://chatgpt.com/backend-api/wham/rate-limit-reset-credits@@ -310,22 +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` 时补充查询+app-server 返回可用 Reset Credits 数量,但不返回每一批的过期时间。UI 和临期通知需要过期日,因此只在数量大于 `0` 时补充查询。-请求使用现有 `auth.json`, 不另建登录流程. 凭据只活在本次请求内, 返回模型只保留仍为 available 且晚于当前时间的日期并排序+请求使用现有 `auth.json`,不另建登录流程。凭据只活在本次请求内,返回模型只保留仍为 available 且晚于当前时间的日期并排序。-这个请求是增强信息, 不是账户快照的必要条件. 4 秒超时或任何解析错误只让过期日缺失, 不应让额度和用量一起失败+这个请求是增强信息,不是账户快照的必要条件。4 秒超时或任何解析错误只让过期日缺失,不应让额度和用量一起失败。## Hook 版本与配置校验-Hook 设置也复用 app-server 链路, 但采用独立的可用性状态+Hook 设置也复用 app-server 链路,但采用独立的可用性状态:- `isEnabled` 表示目标 handler 已安装- `isVerified` 表示最近一次 app-server 显式校验通过@@ -343,32 +343,32 @@ Hook 设置也复用 app-server 链路, 但采用独立的可用性状态- 没有连接时先建立连接- 有连接时复用当前真实进程- 从 handshake user agent 解析运行版本-- 无法解析版本时按不支持处理, 不乐观放行+- 无法解析版本时按不支持处理,不乐观放行-这是能力安全边界. 如果未来新增依赖某个 app-server 方法的功能, 应把最低版本判断放在实际连接能力入口, 不能只在"关于"页面展示磁盘版本+这是能力安全边界。如果未来新增依赖某个 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 内容+日志用于观察进程启动、JSON-RPC 方法、重试和错误分类。不应写入 access token 或 Hook prompt 内容。### 两套日志为什么分开-系统统一日志只保存控制流分类, 适合长期排查 App 是否在刷新, 失败在哪个阶段+系统统一日志只保存控制流分类,适合长期排查 App 是否在刷新,失败在哪个阶段。-App 内 `RequestLog` 保存最多 500 条请求交互预览, 只存在进程内存, 适合用户主动检查协议细节+App 内 `RequestLog` 保存最多 500 条请求交互预览,只存在进程内存,适合用户主动检查协议细节。-即使内存日志生命周期短, 也不能记录 Reset Credits Authorization header. 对新 RPC 增加日志时, 需要检查 payload 是否可能包含凭据或内容字段+即使内存日志生命周期短,也不能记录 Reset Credits Authorization header。对新 RPC 增加日志时,需要检查 payload 是否可能包含凭据或内容字段。## 扩展 app-server 字段的步骤-1. 在外部 DTO 中按协议可选性建模, 不先用展示默认值填充+1. 在外部 DTO 中按协议可选性建模,不先用展示默认值填充2. 在 `CodexStatusService` 决定该方法是账户核心还是补充数据-3. 明确普通失败, unsupported 和认证失败各自如何降级-4. 如果缓存该值, 必须绑定账户 identity 并携带 stale 语义-5. 在领域 snapshot 中转换时间戳, 百分比和排序等稳定规则-6. UI 只消费 snapshot, 不直接访问原始 response+3. 明确普通失败、unsupported 和认证失败各自如何降级+4. 如果缓存该值,必须绑定账户 identity 并携带 stale 语义+5. 在领域 snapshot 中转换时间戳、百分比和排序等稳定规则+6. UI 只消费 snapshot,不直接访问原始 response7. 通知等副作用只使用可信快照8. 核对请求和日志是否扩大隐私边界@@ -379,11 +379,11 @@ App 内 `RequestLog` 保存最多 500 条请求交互预览, 只存在进程内- stdout 混有普通文本时仍能匹配正确 response id- stderr 持续输出时请求不会因 pipe 背压卡住- 复用连接的 transport failure 只重建一次-- 磁盘 CLI 升级后, 当前连接版本与磁盘版本能被区分-- rate limits 失败但同账户有缓存时展示 stale, 通知不误触发+- 磁盘 CLI 升级后,当前连接版本与磁盘版本能被区分+- rate limits 失败但同账户有缓存时展示 stale,通知不误触发- 账户切换后旧额度和用量立即清空- unsupported method 不会每分钟重复请求-- Reset Credits `401` 后只共享一次认证刷新, 失败不影响主快照+- Reset Credits `401` 后只共享一次认证刷新,失败不影响主快照- 手动刷新后 60 秒倒计时重新对齐## 关键源码diff --git a/Docs/DeveloperGuide/architecture.md b/Docs/DeveloperGuide/architecture.mdindex 94429ea..7709efe 100644--- a/Docs/DeveloperGuide/architecture.md+++ b/Docs/DeveloperGuide/architecture.md@@ -2,14 +2,14 @@## 这套架构要解决什么-CodexBar 的核心挑战不是绘制菜单栏界面, 而是在一个长期运行的 `LSUIElement` App 中同时协调短命 Hook 子进程, 本机 app-server, 持续追加的文件, CloudKit, 系统通知和 root helper+CodexBar 的核心挑战不是绘制菜单栏界面,而是在一个长期运行的 `LSUIElement` App 中同时协调短命 Hook 子进程、本机 app-server、持续追加的文件、CloudKit、系统通知和 root helper。-架构需要持续满足以下目标+架构需要持续满足以下目标:-- 任意一条数据链路失败时, 不连带关闭其他功能-- 短命 Hook 模式和普通 App 模式共用可执行文件, 但生命周期完全隔离-- UI 只观察可解释的快照, 不直接承担 I/O, 去重或恢复逻辑-- 特权操作保持最小接口, 业务策略留在普通 App 进程+- 任意一条数据链路失败时,不连带关闭其他功能+- 短命 Hook 模式和普通 App 模式共用可执行文件,但生命周期完全隔离+- UI 只观察可解释的快照,不直接承担 I/O、去重或恢复逻辑+- 特权操作保持最小接口,业务策略留在普通 App 进程- 每个异步结果都能证明自己仍属于当前配置和数据源代际- 可重建数据与不可重放副作用分开处理@@ -17,18 +17,18 @@ CodexBar 的核心挑战不是绘制菜单栏界面, 而是在一个长期运行## 技术基线-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+App 使用 Sparkle 检查更新。工程默认启用 `MainActor` 隔离,Debug 和 Release 使用不同的 App 与 CodexBarHelper bundle ID。## 进程与信任边界@@ -47,19 +47,19 @@ CodexBar executable`-- signed XPC lease <-> root CodexBarHelper <-> fixed pmset commands```-边界设计有两个关键点+边界设计有两个关键点:-- 同一个可执行文件承载 Hook 模式可以让 handler 始终指向当前 App 版本, 不需要额外部署采集工具-- root helper 不知道 Codex 任务, 只知道经过签名校验的租约, 因而不会把业务输入直接带入特权边界+- 同一个可执行文件承载 Hook 模式可以让 handler 始终指向当前 App 版本,不需要额外部署采集工具+- root helper 不知道 Codex 任务,只知道经过签名校验的租约,因而不会把业务输入直接带入特权边界### 进程生命周期差异| 进程 | 生命周期 | 可以做什么 | 不能做什么 || --- | --- | --- | --- |-| Hook 子进程 | 单个事件, 最长几秒 | 读取 stdin, 提取最小字段, 追加本地 JSONL | 初始化 UI, 建立网络连接, 等待长期服务 |-| 主 App | 用户登录会话内长期运行 | 编排 UI, 数据链路和副作用 | 直接以 root 修改系统设置 |+| Hook 子进程 | 单个事件,最长几秒 | 读取 stdin、提取最小字段、追加本地 JSONL | 初始化 UI、建立网络连接、等待长期服务 |+| 主 App | 用户登录会话内长期运行 | 编排 UI、数据链路和副作用 | 直接以 root 修改系统设置 || app-server | 最长复用 1 小时 | 通过 JSON-RPC 提供账户和配置能力 | 成为 Hook 历史或实时任务的替代来源 |-| CodexBarHelper | LaunchDaemon | 执行固定 `pmset` 操作并恢复所有权 | 访问账户, Hook, rollout, 网络或任意命令 |+| CodexBarHelper | LaunchDaemon | 执行固定 `pmset` 操作并恢复所有权 | 访问账户、Hook、rollout、网络或任意命令 |## 目录职责@@ -79,7 +79,7 @@ Scripts/ 构建, DMG, appcast 和 CodexBarHelper 清理脚本## 启动顺序-[`CodexBarApp.swift`](../../CodexBar/App/CodexBarApp.swift) 的初始化顺序是架构约束, 不是实现细节+[`CodexBarApp.swift`](../../CodexBar/App/CodexBarApp.swift) 的初始化顺序是架构约束,不是实现细节:```text进程启动@@ -92,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@@ -103,55 +103,55 @@ Scripts/ 构建, DMG, appcast 和 CodexBarHelper 清理脚本- `KeepAliveController`- `WorkflowSyncSettings` 和同步调度器- `CodexNotificationService`-- 菜单栏, 快捷键, 设置窗口和更新服务+- 菜单栏、快捷键、设置窗口和更新服务-App 退出时需要先释放防睡眠状态. 如果 CodexBarHelper 尚未确认恢复, 终止流程会等待或取消退出, 避免遗留系统级睡眠状态+App 退出时需要先释放防睡眠状态。如果 CodexBarHelper 尚未确认恢复,终止流程会等待或取消退出,避免遗留系统级睡眠状态。### 为什么 Hook 判断必须放在 `App.init`-`@NSApplicationDelegateAdaptor` 会把 AppKit 生命周期接入 SwiftUI App. 一旦普通生命周期开始, 可能创建菜单栏对象, 注册通知 delegate 或访问 CloudKit+`@NSApplicationDelegateAdaptor` 会把 AppKit 生命周期接入 SwiftUI App。一旦普通生命周期开始,可能创建菜单栏对象、注册通知 delegate 或访问 CloudKit。-Hook handler 在 Codex 的关键路径上, 它需要的是接近命令行工具的行为. 因此 `WorkflowHookEventRecorder.handleIfRequested()` 必须在 `CodexBarApp.init()` 的第一段执行, 命中后直接 `exit(EXIT_SUCCESS)`+Hook handler 在 Codex 的关键路径上,它需要的是接近命令行工具的行为。因此 `WorkflowHookEventRecorder.handleIfRequested()` 必须在 `CodexBarApp.init()` 的第一段执行,命中后直接 `exit(EXIT_SUCCESS)`-这个顺序还保证 Hook 采集失败不会污染正常退出诊断. `AppProcessDiagnostics.install()` 只在 `applicationDidFinishLaunching` 中执行, Hook 子进程不会被误记为一次异常退出的完整 App+这个顺序还保证 Hook 采集失败不会污染正常退出诊断。`AppProcessDiagnostics.install()` 只在 `applicationDidFinishLaunching` 中执行,Hook 子进程不会被误记为一次异常退出的完整 App。### 为什么由 AppDelegate 持有长期对象-SwiftUI View 会因为布局, 条件分支和窗口重建而重复创建. 如果 service 的所有权落在 View 中, 一个看似普通的界面变化就可能终止 reader, app-server 或 XPC 连接+SwiftUI View 会因为布局、条件分支和窗口重建而重复创建。如果 service 的所有权落在 View 中,一个看似普通的界面变化就可能终止 reader, app-server 或 XPC 连接。-`CodexBarAppDelegate` 因而承担 composition root 职责+`CodexBarAppDelegate` 因而承担 composition root 职责:- 只在这里创建长期 service, settings 和 ViewModel- 在这里建立 monitor, notification 和 keep-alive 之间的回调- View 只接收已经创建好的引用- App 退出时从同一个所有者反向停止服务-这不是要求所有逻辑都堆进 AppDelegate. 它只负责装配和生命周期, 业务规则仍在各自 service 或 controller 中+这不是要求所有逻辑都堆进 AppDelegate。它只负责装配和生命周期,业务规则仍在各自 service 或 controller 中。### 退出为什么可以被取消`applicationShouldTerminate` 先调用 `KeepAliveController.prepareForTermination()` 并返回 `.terminateLater`-如果 helper 明确确认 release, App 再回复允许退出. 如果释放失败, 本次退出被取消, controller 回到正常协调状态并继续尝试维持正在运行的任务+如果 helper 明确确认 release,App 再回复允许退出。如果释放失败,本次退出被取消,controller 回到正常协调状态并继续尝试维持正在运行的任务。-直接在 `applicationWillTerminate` 中异步释放已经太晚, 因为该回调不能可靠延长进程寿命+直接在 `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 不提供完整的实时任务状态-- 历史聚合允许延迟和重建, 实时任务不能等待聚合完成+- 历史聚合允许延迟和重建,实时任务不能等待聚合完成- 实时任务快照不可作为历史统计的持久来源-- 某条链路不可用时, 其他链路仍应保持可用+- 某条链路不可用时,其他链路仍应保持可用### 依赖方向@@ -166,15 +166,15 @@ Hook + rollout --------> CodexActivityMonitor ----+`-------------> KeepAliveController --> helper```-箭头表示数据或只读状态的消费方向. 下游不能反向成为上游的事实来源+箭头表示数据或只读状态的消费方向。下游不能反向成为上游的事实来源。-例如, 菜单栏可以把额度进度和任务状态画在同一个图标上, 但图标是否存在不能决定任务 monitor 是否运行. 同步 scheduler 可以复用历史维护的触发时机, 但 CloudKit 是否可用不能决定本地聚合是否执行+例如,菜单栏可以把额度进度和任务状态画在同一个图标上,但图标是否存在不能决定任务 monitor 是否运行。同步 scheduler 可以复用历史维护的触发时机,但 CloudKit 是否可用不能决定本地聚合是否执行。### 共享触发不等于数据依赖-历史维护默认挂在 60 秒额度刷新完成事件上, 这是为了减少常驻 timer 和日志噪音. 两条链路共享调度时机, 但没有共享事实+历史维护默认挂在 60 秒额度刷新完成事件上,这是为了减少常驻 timer 和日志噪音。两条链路共享调度时机,但没有共享事实。-因此修改刷新节奏时需要区分+因此修改刷新节奏时需要区分:- 触发来源可以调整- 维护任务仍必须在 app-server 失败时具备独立执行能力@@ -182,7 +182,7 @@ Hook + rollout --------> CodexActivityMonitor ----+## 并发边界-工程启用 Swift 6 严格并发和默认 `MainActor` 隔离+工程启用 Swift 6 严格并发和默认 `MainActor` 隔离。### MainActor 对象@@ -192,7 +192,7 @@ Hook + rollout --------> CodexActivityMonitor ----+- `KeepAliveController`- `CodexNotificationService`-这些对象负责可观察状态和 UI 协调, 不应直接执行阻塞 I/O+这些对象负责可观察状态和 UI 协调,不应直接执行阻塞 I/O。### Actor 服务@@ -203,31 +203,31 @@ Hook + rollout --------> CodexActivityMonitor ----+- `WorkflowSyncService` 管理 CloudKit 状态- `ActivityProtectionStateStore` 管理跨进程保护记录-跨 actor 传递的 DTO 必须是不可变值类型, 并按需要声明 `Sendable` 或 `nonisolated`+跨 actor 传递的 DTO 必须是不可变值类型,并按需要声明 `Sendable` 或 `nonisolated`### 为什么 monitor 仍在 MainActor-`CodexActivityMonitor` 的输入读取在 actor 中完成, 但状态机本身与多个 Combine 消费者紧密相连+`CodexActivityMonitor` 的输入读取在 actor 中完成,但状态机本身与多个 Combine 消费者紧密相连。-把 monitor 放在 `MainActor` 有以下收益+把 monitor 放在 `MainActor` 有以下收益:- `@Published snapshot` 和 transition 发布顺序天然串行- 通知与防睡眠消费者看到相同的状态提交顺序-- App 睡眠, 唤醒和 Hook 设置变化可以与 UI 生命周期统一排序+- App 睡眠、唤醒和 Hook 设置变化可以与 UI 生命周期统一排序-前提是 monitor 不能直接执行阻塞文件读取. `HookEventTailReader`, `CodexSessionLifecycleReader` 和 `ActivityProtectionStateStore` 各自承担 I/O 边界+前提是 monitor 不能直接执行阻塞文件读取。`HookEventTailReader`, `CodexSessionLifecycleReader` 和 `ActivityProtectionStateStore` 各自承担 I/O 边界。### 非隔离 pipe reader 为什么使用锁-app-server 是 stdio 协议, 底层需要组合 `FileHandle`, `DispatchSourceRead` 和 semaphore. 这些类型不是天然 `Sendable`, 也不适合每读取一行都跨 Swift actor hop+app-server 是 stdio 协议,底层需要组合 `FileHandle`, `DispatchSourceRead` 和 semaphore。这些类型不是天然 `Sendable`,也不适合每读取一行都跨 Swift actor hop。-`PipeReadBuffer` 把不安全边界收口在一个 `@unchecked Sendable` 类型中, 所有可变状态由 `NSLock` 保护, 读事件固定在专用 queue 上. 上层只看到完整行和关闭状态+`PipeReadBuffer` 把不安全边界收口在一个 `@unchecked Sendable` 类型中,所有可变状态由 `NSLock` 保护,读事件固定在专用 queue 上。上层只看到完整行和关闭状态。-这里的 `@unchecked` 是经过封装的局部承诺, 不是关闭整个模块的并发检查+这里的 `@unchecked` 是经过封装的局部承诺,不是关闭整个模块的并发检查。### 跨进程文件不能只依赖 actor-Hook recorder 是另一个进程, 所以 `WorkflowService` actor 无法保护它. `stats.lock` 使用 `flock` 对事件文件和维护状态的联合修改提供进程级排他事务+Hook recorder 是另一个进程,所以 `WorkflowService` actor 无法保护它。`stats.lock` 使用 `flock` 对事件文件和维护状态的联合修改提供进程级排他事务。同一个流程中会同时出现 actor 和 `flock`@@ -236,41 +236,41 @@ Hook recorder 是另一个进程, 所以 `WorkflowService` actor 无法保护它## 模型分层-项目没有让 app-server DTO, 持久化模型和 View 直接共用同一个大对象+项目没有让 app-server DTO、持久化模型和 View 直接共用同一个大对象:| 模型类型 | 作用 | 设计要求 || --- | --- | --- |-| 外部 DTO | 解码 app-server, Hook, rollout 或 CloudKit | 宽容版本差异, 不承载 UI 副作用 |-| 持久化模型 | 保存可恢复状态和 schema | 兼容旧值, 明确 missing 语义 |-| 领域快照 | 向消费者表达当前可信状态 | 不可变, 可比较, 跨 actor 安全 |-| transition | 表达一次 live 状态变化 | 不从历史快照反推, 需要上游去重 |-| 展示格式 | 日期, 百分比, 文案和颜色 | 跟随 locale, 不反向参与业务判定 |+| 外部 DTO | 解码 app-server, Hook, rollout 或 CloudKit | 宽容版本差异,不承载 UI 副作用 |+| 持久化模型 | 保存可恢复状态和 schema | 兼容旧值,明确 missing 语义 |+| 领域快照 | 向消费者表达当前可信状态 | 不可变、可比较、跨 actor 安全 |+| transition | 表达一次 live 状态变化 | 不从历史快照反推,需要上游去重 |+| 展示格式 | 日期、百分比、文案和颜色 | 跟随 locale,不反向参与业务判定 |-例如 `CodexQuotaSnapshot` 可以同时携带当前值和 stale 标记. `CodexActivitySnapshot` 只保存展示需要的任务字段, 原始 session ID 不进入 View+例如 `CodexQuotaSnapshot` 可以同时携带当前值和 stale 标记。`CodexActivitySnapshot` 只保存展示需要的任务字段,原始 session ID 不进入 View。## 生命周期与保留时间-不同状态有不同的生命周期, 不能用一个统一缓存期限替代+不同状态有不同的生命周期,不能用一个统一缓存期限替代:| 状态 | 生命周期 | 原因 || --- | --- | --- |-| app-server connection | 最长 1 小时 | 复用降低启动成本, 定期重建让磁盘升级生效 |+| 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 小时 | 跨重启保持抑制, 同时限制身份留存 |+| 日聚合身份明细 | 3 天 | 近期精确去重与隐私、文件体积折中 |+| Activity Protection 记录 | 最后进展后 24 小时 | 跨重启保持抑制,同时限制身份留存 |-修改其中一个时间窗口时, 要先确认是否存在配对不变量. 例如 tail reader bootstrap 窗口必须和活动任务保留窗口一致+修改其中一个时间窗口时,要先确认是否存在配对不变量。例如 tail reader bootstrap 窗口必须和活动任务保留窗口一致。## 状态所有权-实时任务状态只有一个权威来源, 即 [`CodexActivityMonitor.swift`](../../CodexBar/Services/Workflow/CodexActivityMonitor.swift)+实时任务状态只有一个权威来源,即 [`CodexActivityMonitor.swift`](../../CodexBar/Services/Workflow/CodexActivityMonitor.swift)-它的快照被以下模块消费+它的快照被以下模块消费:- 菜单栏图标和主面板任务卡片- 活动中心@@ -278,7 +278,7 @@ Hook recorder 是另一个进程, 所以 `WorkflowService` actor 无法保护它- 防睡眠是否存在有效任务的判断- 异常会话保护-消费者只能基于快照展示或执行副作用, 不能各自重建一套任务状态机+消费者只能基于快照展示或执行副作用,不能各自重建一套任务状态机。### 状态所有权表@@ -294,55 +294,55 @@ Hook recorder 是另一个进程, 所以 `WorkflowService` actor 无法保护它| root 睡眠所有权 | `CodexBarHelper` | 通过 XPC 请求和查询 || 通知去重 | `CodexNotificationService` | 上游只发布候选事件 |-新增消费者时, 优先订阅已有快照. 如果现有快照缺字段, 应在状态所有者处扩展稳定值类型, 不应让消费者重新读取原始文件+新增消费者时,优先订阅已有快照。如果现有快照缺字段,应在状态所有者处扩展稳定值类型,不应让消费者重新读取原始文件。## 错误和降级原则- 短暂网络或 RPC 失败优先保留上一次可解释的状态-- 数据源不可用必须显式表达, 不能伪装为空数据-- bootstrap 阶段只建立基线, 不发送历史状态变化通知+- 数据源不可用必须显式表达,不能伪装为空数据+- bootstrap 阶段只建立基线,不发送历史状态变化通知- reader 更换或数据源代际变化时丢弃旧异步结果- 恢复流程必须完成新的读取屏障后才能继续判定-- 持久化文件写入需要原子替换或文件锁, 避免 Debug 与 Release 并发破坏+- 持久化文件写入需要原子替换或文件锁,避免 Debug 与 Release 并发破坏### 错误分类比统一重试更重要| 错误类别 | 典型处理 | 不应采取的处理 || --- | --- | --- |-| 明确业务不支持 | 缓存 method unsupported, 显示来源缺失 | 每分钟重复请求或展示 `0` |+| 明确业务不支持 | 缓存 method unsupported,显示来源缺失 | 每分钟重复请求或展示 `0` || 短暂业务失败 | 同账户范围内使用 stale 缓存 | 清空整个账户快照 |-| transport 失败 | 丢弃连接, 最多重建一次 | 在不可信 pipe 上继续请求 |-| 数据源身份变化 | 新 generation, 从原始来源重建 | 沿用旧 offset 继续追加 |+| transport 失败 | 丢弃连接,最多重建一次 | 在不可信 pipe 上继续请求 |+| 数据源身份变化 | 新 generation,从原始来源重建 | 沿用旧 offset 继续追加 || 迟到异步结果 | generation 不匹配时丢弃 | 覆盖新设置或新 reader 状态 || 特权状态不确定 | 保留可能租约并主动确认释放 | 假定 helper 没有执行 || Hook recorder 失败 | 吞掉本次采集并退出成功 | 阻断 Codex 或弹 UI |### 日志为什么记录阶段而不是用户数据-系统日志使用 `trigger`, `stage`, `reason`, `counts` 和 `elapsed` 解释流程, 避免记录额度数值, 项目路径或任务身份+系统日志使用 `trigger`, `stage`, `reason`, `counts` 和 `elapsed` 解释流程,避免记录额度数值、项目路径或任务身份。-这种日志结构允许区分+这种日志结构允许区分:- 同步是在 zone, device, fetch, upload 还是 prune 阶段失败- app-server 使用新连接还是复用连接-- 聚合是空转, 增量写入还是标脏重建+- 聚合是空转、增量写入还是标脏重建- 防睡眠被哪一个条件阻断-诊断需要的是控制流证据, 不需要复制用户数据+诊断需要的是控制流证据,不需要复制用户数据。## 变更一个核心流程时怎么落点### 新增数据来源1. 先确定它是否属于现有 3 条链路-2. 定义来源缺失, stale 和失败语义+2. 定义来源缺失、stale 和失败语义3. 在 actor service 内完成 I/O 和缓存4. 通过不可变快照进入 MainActor5. 单独审查网络和隐私边界### 新增一次性副作用-1. 找到能证明"刚刚发生"的 live transition+1. 找到能证明“刚刚发生”的 live transition2. 不从当前快照或历史列表反推3. 定义进程内和跨重启去重范围4. 提交前检查事件是否仍相关@@ -351,7 +351,7 @@ Hook recorder 是另一个进程, 所以 `WorkflowService` actor 无法保护它### 新增持久化状态1. 说明为什么内存状态不足-2. 定义 schema, 原子性和并发访问边界+2. 定义 schema、原子性和并发访问边界3. 定义旧版本读取新文件和新版本读取旧文件的行为4. 限制保存字段和保留时间5. 先确认兼容策略再修改格式diff --git a/Docs/DeveloperGuide/data-and-privacy.md b/Docs/DeveloperGuide/data-and-privacy.mdindex 30e2519..85ff1d2 100644--- a/Docs/DeveloperGuide/data-and-privacy.md+++ b/Docs/DeveloperGuide/data-and-privacy.md@@ -2,27 +2,27 @@## 原则-CodexBar 只读取实现账户展示, Hook 统计, 实时任务和防睡眠所需的数据+CodexBar 只读取实现账户展示、Hook 统计、实时任务和防睡眠所需的数据:- 原始数据能留在本机时不上传- 可以保存聚合时不保存正文- 可以保存哈希身份时不保存原始身份- 数据源不可用时显式标记缺失-隐私边界不是一份静态字段黑名单, 而是每条数据链路的架构约束. 新字段即使技术上容易读取, 也必须先回答"它是否是完成产品目标所必需的"+隐私边界不是一份静态字段黑名单,而是每条数据链路的架构约束。新字段即使技术上容易读取,也必须先回答“它是否是完成产品目标所必需的”。## 数据分类模型-开发时把数据分成 4 类有助于决定存储和传播范围+开发时把数据分成 4 类有助于决定存储和传播范围:| 分类 | 示例 | 默认处理 || --- | --- | --- |-| 凭据 | OAuth token, `auth.json` | 只在请求期间使用, 不复制, 不记录 |+| 凭据 | OAuth token、`auth.json` | 只在请求期间使用、不复制、不记录 || 内容 | prompt, response, tool 参数和输出 | 不采集 |-| 身份和上下文 | session ID, 完整路径, project 名 | 仅在必要链路最小化使用, 上传前脱敏或删除 |-| 聚合指标 | 每日事件数, model 计数 | 可本地持久化, 用户 opt-in 后上传规定字段 |+| 身份和上下文 | session ID、完整路径、project 名 | 仅在必要链路最小化使用,上传前脱敏或删除 |+| 聚合指标 | 每日事件数、model 计数 | 可本地持久化,用户 opt-in 后上传规定字段 |-"只保存在本机"不等于没有隐私成本. 本地日志, crash report, 备份和同机其他进程仍可能扩大暴露面, 所以不需要的数据应在解析入口就丢弃+“只保存在本机”不等于没有隐私成本。本地日志、crash report、备份和同机其他进程仍可能扩大暴露面,所以不需要的数据应在解析入口就丢弃。## 信任边界@@ -39,63 +39,63 @@ Codex hook stdin / rollout / auth.json / app-serverroot CodexBarHelper```-边界含义如下+边界含义如下:-- Codex 输入文件和协议数据都视为外部输入, 解码失败不能扩大成任意文件访问或命令执行-- CloudKit 是用户主动开启的远端边界, 即使使用 private database 也只允许规定聚合字段-- root helper 是权限提升边界, 接口能力必须比 App 业务能力更窄-- Debug 和 Release 是两个 App 身份, 但部分本地文件有意共享, 因此需要进程锁和兼容 schema+- Codex 输入文件和协议数据都视为外部输入,解码失败不能扩大成任意文件访问或命令执行+- CloudKit 是用户主动开启的远端边界,即使使用 private database 也只允许规定聚合字段+- root helper 是权限提升边界,接口能力必须比 App 业务能力更窄+- Debug 和 Release 是两个 App 身份,但部分本地文件有意共享,因此需要进程锁和兼容 schema## 最小化发生在采集入口-只在上传时删除敏感字段不够, 因为原始字段可能已经进入本地 JSONL, 内存日志或错误信息+只在上传时删除敏感字段不够,因为原始字段可能已经进入本地 JSONL、内存日志或错误信息。-CodexBar 的最小化顺序是+CodexBar 的最小化顺序是:1. Hook recorder 从 stdin 只提取白名单结构字段2. rollout reader 使用最小 Codable 结构跳过正文3. 聚合器把较老 identity 明细压成计数4. sync model 再投影成 CloudKit 允许字段-5. 日志层只记录阶段, 分类和非敏感计数+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 历史和实时活动读取不同事实,具有不同的新鲜度与失败模式:- 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+CodexBar 只通过 stdio 与本机进程通信,不从 app-server 响应中复制认证材料。request log 保存协议方法和结果摘要,不是原始 wire dump。### Hook 事件-Hook 子进程从 stdin 提取+Hook 子进程从 stdin 提取:- 时间和事件类型- 工作目录@@ -103,32 +103,32 @@ Hook 子进程从 stdin 提取- permission 和 reviewer- 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+工作目录只用于派生 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 从文件尾部按预算扫描,一方面减少 I/O,另一方面降低无关历史内容进入进程内存的范围。解析 DTO 只声明所需字段,JSONDecoder 自动忽略其余内容。-这不是对 rollout 文件的完整隐私隔离, 因为 reader 仍需打开原文件. 因此如果未来加入全文搜索或 prompt 展示, 应视为新的产品隐私能力, 不能当作现有 reader 的自然扩展+这不是对 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`+access token 只在 Reset Credits 数量大于 0 且需要到期信息时读取。这个条件把凭据读取限制到确有业务价值的路径,常规额度刷新不触碰 `auth.json`-网络错误中可能包含请求描述, 记录前必须确认不会把 Authorization header 拼进错误文本. 当前日志只记录错误分类和非敏感 detail+网络错误中可能包含请求描述,记录前必须确认不会把 Authorization header 拼进错误文本。当前日志只记录错误分类和非敏感 detail。## 本地持久化@@ -150,25 +150,25 @@ access token 只在 Reset Credits 数量大于 0 且需要到期信息时读取.| --- | --- | --- || `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 明细是精确去重与长期最小化之间的折中+3 天 identity 明细是精确去重与长期最小化之间的折中:-- 近期 Hook 文件仍可能补写或重复, 需要 identity 集合正确合并-- 远期数据变化概率低, 只保留总数可显著缩小长期身份暴露-- 压缩后不能从计数恢复 identity, 因此算法变化统一从仍在 210 天保留期内的原始 JSONL 重建+- 近期 Hook 文件仍可能补写或重复,需要 identity 集合正确合并+- 远期数据变化概率低,只保留总数可显著缩小长期身份暴露+- 压缩后不能从计数恢复 identity,因此算法变化统一从仍在 210 天保留期内的原始 JSONL 重建-原始事件和日聚合使用相同的 210 天上限, 避免派生数据已经清理但更敏感的原始数据仍无限保留+原始事件和日聚合使用相同的 210 天上限,避免派生数据已经清理但更敏感的原始数据仍无限保留。-匿名任务不生成异常会话保护标识, 因此不会写入 `ActivityProtection/state.json`+匿名任务不生成异常会话保护标识,因此不会写入 `ActivityProtection/state.json`### UserDefaults-UserDefaults 保存+UserDefaults 保存:- 功能开关和设置选项- 通知阈值和声音名称@@ -177,9 +177,9 @@ UserDefaults 保存- 有界的通知去重 key- CodexBarHelper fingerprint 等运行配置-持久化 key 改名, 结构变化或默认值变化需要考虑旧版本升级行为+持久化 key 改名、结构变化或默认值变化需要考虑旧版本升级行为。-UserDefaults 不是无 schema 存储. 对已有 key 改名, 枚举 raw value 变化或缺失默认值变化都会改变升级用户行为. 这类修改属于兼容性问题, 必须先确定迁移和降级策略+UserDefaults 不是无 schema 存储。对已有 key 改名、枚举 raw value 变化或缺失默认值变化都会改变升级用户行为。这类修改属于兼容性问题,必须先确定迁移和降级策略。### CodexBarHelper 目录@@ -187,28 +187,28 @@ UserDefaults 不是无 schema 存储. 对已有 key 改名, 枚举 raw value 变/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 内容。-ring buffer 的 500 条上限既控制内存, 也限制打开日志窗口时的渲染成本. 它不是审计日志, 不能承担跨启动问题追踪. 需要跨启动诊断时使用统一系统日志, 仍需遵守相同字段边界+ring buffer 的 500 条上限既控制内存,也限制打开日志窗口时的渲染成本。它不是审计日志,不能承担跨启动问题追踪。需要跨启动诊断时使用统一系统日志,仍需遵守相同字段边界。-统一系统日志 subsystem 为 `app.zabrian.codexbar`, Debug 版本带 `.debug` 后缀+统一系统日志 subsystem 为 `app.zabrian.codexbar`,Debug 版本带 `.debug` 后缀。-系统日志只应记录+系统日志只应记录:- 操作阶段和结果- 状态分类- 不敏感计数- 可定位模块的错误信息-系统日志不应记录+系统日志不应记录:- OAuth token- prompt, response 或 tool 内容@@ -224,13 +224,13 @@ ring buffer 的 500 条上限既控制内存, 也限制打开日志窗口时的| 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@@ -240,34 +240,34 @@ CloudKit 只上传日级聚合字段- model 计数- 更新时间-CloudKit 不上传+CloudKit 不上传:- 原始 Hook JSONL- session, turn 或 agent ID- 完整工作目录- prompt, response, tool 参数或输出-- Codex 账户, 额度和 token 用量+- Codex 账户、额度和 token 用量- access token- App 请求日志- Activity Protection 状态-project 显示名可能由目录名派生, 仍可能包含用户敏感信息. 同步开关必须保持用户主动选择+project 显示名可能由目录名派生,仍可能包含用户敏感信息。同步开关必须保持用户主动选择。-HMAC 设备 pseudonym 只降低硬件身份关联, 不会自动匿名化 project 名. private database 也不等于"数据不离开设备". 因此设置文案和开发文档都必须继续说明同步内容, 不能因为 CloudKit 属于用户账户就改成默认开启+HMAC 设备 pseudonym 只降低硬件身份关联,不会自动匿名化 project 名。private database 也不等于“数据不离开设备”。因此设置文案和开发文档都必须继续说明同步内容,不能因为 CloudKit 属于用户账户就改成默认开启。## root helper 的数据隔离-CodexBarHelper 只需要知道 3 类状态+CodexBarHelper 只需要知道 3 类状态:- 哪个已验证客户端持有哪一代 lease- `SleepDisabled` 当前实测值- CodexBar 是否拥有恢复责任-它不需要 task ID, project 名, Hook 路径, 账户状态或用户设置全文. XPC 只传布尔请求, client session ID, generation 和 update identifier+它不需要 task ID、project 名、Hook 路径、账户状态或用户设置全文。XPC 只传布尔请求、client session ID, generation 和 update identifier。-这种能力最小化意味着即使普通 App 层以后新增网络或数据功能, root 进程也不会自动获得这些能力. 不应为了复用文件读取或网络代码把业务 service 链接进 helper+这种能力最小化意味着即使普通 App 层以后新增网络或数据功能,root 进程也不会自动获得这些能力。不应为了复用文件读取或网络代码把业务 service 链接进 helper。-helper 的 ownership 文件不是用户偏好, 而是 crash recovery 事务记录. 它必须由 root 拥有, 拒绝 group 或 world 可写目录, 并通过 full sync 加原子 rename 确保重启后能判断是否需要恢复+helper 的 ownership 文件不是用户偏好,而是 crash recovery 事务记录。它必须由 root 拥有,拒绝 group 或 world 可写目录,并通过 full sync 加原子 rename 确保重启后能判断是否需要恢复。## 文件安全@@ -275,12 +275,12 @@ helper 的 ownership 文件不是用户偏好, 而是 crash recovery 事务记- JSONL 只追加完整行- 聚合和状态文件使用可恢复写入流程- Activity Protection 文件权限为 `0600`-- CodexBarHelper 状态通过 root owner, 权限检查, full sync 和原子 rename 提交+- CodexBarHelper 状态通过 root owner、权限检查、full sync 和原子 rename 提交- Debug 和 Release 共享的数据必须使用锁和兼容 schema-## 缺失, 陈旧和不可用的隐私含义+## 缺失、陈旧和不可用的隐私含义-数据不可用时不能用看似友好的默认值掩盖+数据不可用时不能用看似友好的默认值掩盖:| 状态 | 正确表达 | 错误做法 || --- | --- | --- |@@ -290,29 +290,29 @@ helper 的 ownership 文件不是用户偏好, 而是 crash recovery 事务记| CloudKit 离线 | 保留带来源的旧 cache | 当作当前账户新数据 || 电池读取失败 | 保留上次判定并标记 unreadable | 当作没有电池 |-显式降级不仅提升正确性, 也避免为了填满 UI 而读取更多备用来源或保存额外数据+显式降级不仅提升正确性,也避免为了填满 UI 而读取更多备用来源或保存额外数据。## 新增数据字段前的审查清单1. 写明产品目标以及没有该字段时无法完成的行为-2. 确认字段属于凭据, 内容, 身份上下文还是聚合指标+2. 确认字段属于凭据、内容、身份上下文还是聚合指标3. 定义采集入口和最早可以丢弃原文的层-4. 明确内存, UserDefaults, Application Support, system log 和 CloudKit 中的存在范围-5. 定义保留期, 删除触发和失败后的清理行为+4. 明确内存、UserDefaults, Application Support, system log 和 CloudKit 中的存在范围+5. 定义保留期、删除触发和失败后的清理行为6. 检查 Debug 与 Release 是否共享文件或 identity7. 检查字段缺失与明确空值的区别8. 检查日志和错误对象是否会间接复制原文-9. 如涉及 CloudKit, 网络或日志数据, 先更新隐私说明并取得明确产品决策-10. 如涉及 schema 或旧版本共存, 先确认兼容方案再改代码+9. 如涉及 CloudKit、网络或日志数据,先更新隐私说明并取得明确产品决策+10. 如涉及 schema 或旧版本共存,先确认兼容方案再改代码## 建议的隐私故障验证-- 用包含明显标记字符串的 prompt 和 tool 参数运行任务, 确认 Hook JSONL, App 日志和 CloudKit cache 均没有该字符串-- 让项目目录名包含敏感测试词, 确认它只出现在允许的本地展示和 opt-in 聚合字段-- 模拟 Reset Credits 请求失败, 确认 access token 不出现在内存日志和 unified log+- 用包含明显标记字符串的 prompt 和 tool 参数运行任务,确认 Hook JSONL、App 日志和 CloudKit cache 均没有该字符串+- 让项目目录名包含敏感测试词,确认它只出现在允许的本地展示和 opt-in 聚合字段+- 模拟 Reset Credits 请求失败,确认 access token 不出现在内存日志和 unified log- 检查 CloudKit record 不包含 session, turn, agent ID 或完整路径- 以非 root 用户验证 helper 状态目录不可写-- 损坏各类缓存文件, 确认系统降级或重建, 而不是扩大到备用数据采集+- 损坏各类缓存文件,确认系统降级或重建,而不是扩大到备用数据采集## 关键源码diff --git a/Docs/DeveloperGuide/design-decisions.md b/Docs/DeveloperGuide/design-decisions.mdindex c834499..2d1b18c 100644--- a/Docs/DeveloperGuide/design-decisions.md+++ b/Docs/DeveloperGuide/design-decisions.md@@ -1,138 +1,138 @@# 设计原则与关键决策-这篇文档解释 CodexBar 为什么采用现在的结构, 以及这些结构在解决什么问题+这篇文档解释 CodexBar 为什么采用现在的结构,以及这些结构在解决什么问题。-它不是源码目录索引, 也不是功能列表. 阅读目标是建立一套判断标准: 当实现需要变化时, 哪些只是可以替换的手段, 哪些是必须继续成立的系统不变量+它不是源码目录索引,也不是功能列表。阅读目标是建立一套判断标准:当实现需要变化时,哪些只是可以替换的手段,哪些是必须继续成立的系统不变量。## 从产品目标推导架构-CodexBar 看起来只是一个菜单栏 App, 但它同时横跨 4 个性质完全不同的边界+CodexBar 看起来只是一个菜单栏 App,但它同时横跨 4 个性质完全不同的边界:- Codex 自己的本机协议和配置- 持续变化的 Hook 与 rollout 文件-- macOS 窗口, 通知和电源管理+- macOS 窗口、通知和电源管理- 带 root 权限的系统级睡眠控制-这些边界不能用同一种失败策略处理+这些边界不能用同一种失败策略处理。-例如, 额度刷新失败时保留上一次数据通常比清空更有价值. Hook 采集失败时必须立即放弃, 因为统计不能阻塞 Codex. 防睡眠释放失败时则不能静默退出, 因为系统设置可能仍被 CodexBar 持有+例如,额度刷新失败时保留上一次数据通常比清空更有价值。Hook 采集失败时必须立即放弃,因为统计不能阻塞 Codex。防睡眠释放失败时则不能静默退出,因为系统设置可能仍被 CodexBar 持有。-因此项目没有追求一个包办所有工作的全局 service, 而是先按输入来源和失败语义拆开, 再在 UI 和副作用层组合只读快照+因此项目没有追求一个包办所有工作的全局 service,而是先按输入来源和失败语义拆开,再在 UI 和副作用层组合只读快照。## 决策优先级-遇到实现取舍时, 按以下顺序判断+遇到实现取舍时,按以下顺序判断:1. 不阻断用户正在执行的 Codex 任务2. 不遗留或误改系统级状态-3. 不把旧数据, 缺失数据或不确定状态伪装成当前事实+3. 不把旧数据、缺失数据或不确定状态伪装成当前事实4. 不让迟到的异步结果覆盖更新的用户意图-5. 不扩大特权进程, 网络和持久化数据的边界-6. 在上述条件成立后再优化延迟, 文件大小和 UI 动画+5. 不扩大特权进程、网络和持久化数据的边界+6. 在上述条件成立后再优化延迟、文件大小和 UI 动画-这个顺序解释了很多看起来不对称的处理+这个顺序解释了很多看起来不对称的处理:-- Hook recorder 获取锁超时后丢弃本次统计, 而不是继续等待-- App 退出时可以被延后, 直到 helper 确认释放由 CodexBar 拥有的睡眠状态-- app-server 补充接口失败时可以展示带陈旧标记的缓存, 但 method unsupported 必须展示来源缺失-- 唤醒恢复如果没有通过新的 Hook 读取屏障, 异常会话保护继续暂停+- Hook recorder 获取锁超时后丢弃本次统计,而不是继续等待+- App 退出时可以被延后,直到 helper 确认释放由 CodexBar 拥有的睡眠状态+- app-server 补充接口失败时可以展示带陈旧标记的缓存,但 method unsupported 必须展示来源缺失+- 唤醒恢复如果没有通过新的 Hook 读取屏障,异常会话保护继续暂停-## 事实, 快照与副作用+## 事实、快照与副作用-项目中的状态分为 3 层+项目中的状态分为 3 层:| 层级 | 含义 | 示例 || --- | --- | --- |-| 事实 | 外部系统或本地日志已经发生的输入 | Hook 事件, rollout terminal, app-server 响应 |+| 事实 | 外部系统或本地日志已经发生的输入 | Hook 事件、rollout terminal、app-server 响应 || 快照 | 对一组事实按当前规则得到的可展示状态 | `CodexQuotaSnapshot`, `WorkflowSnapshot`, `CodexActivitySnapshot` |-| 副作用 | 因可信状态变化而执行的一次性动作 | 通知, 触觉反馈, XPC 租约, CloudKit 上传 |+| 副作用 | 因可信状态变化而执行的一次性动作 | 通知、触觉反馈、XPC 租约、CloudKit 上传 |-设计上刻意不让 View 从原始事实直接执行副作用+设计上刻意不让 View 从原始事实直接执行副作用。-例如, 通知服务不扫描任务中心列表猜测哪个任务刚完成, 而是消费 monitor 发布的 transition. 防睡眠控制器也不解析 Hook, 它只消费活动快照中的运行和等待任务+例如,通知服务不扫描任务中心列表猜测哪个任务刚完成,而是消费 monitor 发布的 transition。防睡眠控制器也不解析 Hook,它只消费活动快照中的运行和等待任务。-这样做有两个原因+这样做有两个原因:-- 快照可以重复读取, transition 必须最多消费一次-- 同一个状态机可以统一处理 bootstrap, 去重, 迟到事件和 rollout 对账, 消费者不需要各自实现一套近似规则+- 快照可以重复读取,transition 必须最多消费一次+- 同一个状态机可以统一处理 bootstrap、去重、迟到事件和 rollout 对账,消费者不需要各自实现一套近似规则## 3 条数据链路为什么必须独立### app-server 链路-app-server 提供账户, 额度和 token 用量的周期性快照. 它适合按分钟刷新, 允许在短暂故障时展示同账户缓存+app-server 提供账户、额度和 token 用量的周期性快照。它适合按分钟刷新,允许在短暂故障时展示同账户缓存。### Hook 历史链路-历史链路把 append-only 原始事件转成日级聚合. 它允许延迟, 可以从原始 JSONL 重建, 主要目标是长期一致性+历史链路把 append-only 原始事件转成日级聚合。它允许延迟,可以从原始 JSONL 重建,主要目标是长期一致性。### 实时任务链路-实时链路关心秒级任务状态和一次性转场. 它需要组合 Hook 与 rollout, 不能等待日级聚合完成, 也不能把十分钟前的终态当成一条新通知+实时链路关心秒级任务状态和一次性转场。它需要组合 Hook 与 rollout,不能等待日级聚合完成,也不能把十分钟前的终态当成一条新通知。-如果把三者合并成一条链路, 会产生错误耦合+如果把三者合并成一条链路,会产生错误耦合:- app-server 暂时失败会让本来仍可读取的本地任务状态消失- 聚合重建会阻塞实时任务更新- 为通知设计的 terminal 去重会污染历史计数- CloudKit 或网络故障会反向影响本地 Hook 展示-允许它们在 UI 层组合, 但不允许互相充当事实来源, 是 CodexBar 最重要的架构边界之一+允许它们在 UI 层组合,但不允许互相充当事实来源,是 CodexBar 最重要的架构边界之一。-## 用户意图, 依赖可用性与实际效果+## 用户意图、依赖可用性与实际效果-设置类功能通常同时存在 3 种状态+设置类功能通常同时存在 3 种状态:```text用户意图 -> 依赖是否可用 -> 实际效果```-防睡眠是最完整的例子+防睡眠是最完整的例子:- `isEnabled` 表示用户愿意让 CodexBar 管理睡眠-- Hook, helper, 电量和时长共同决定当前是否具备执行条件+- Hook、helper、电量和时长共同决定当前是否具备执行条件- `isPreventingSleep` 表示 App 与 helper 已经确认实际效果-依赖暂时不可用时不能把 `isEnabled` 写回 `false`. 否则一次 RPC 故障就会永久修改用户偏好, 恢复后也无法自动继续+依赖暂时不可用时不能把 `isEnabled` 写回 `false`。否则一次 RPC 故障就会永久修改用户偏好,恢复后也无法自动继续。-Hook 设置同样区分+Hook 设置同样区分:- `isEnabled` 表示配置文件中安装了 handler- `isVerified` 表示 app-server 最近一次给出明确可用结论- `isOperable` 才是下游依赖应使用的状态-这个三层模型比一个布尔值多一些状态, 但避免了把配置, 诊断和效果混成不可解释的开关+这个三层模型比一个布尔值多一些状态,但避免了把配置、诊断和效果混成不可解释的开关。## 不确定性必须进入类型和 UI-项目中多处保留 `nil`, stale 或 degraded, 而不是统一回落为零或空数组+项目中多处保留 `nil`, stale 或 degraded,而不是统一回落为零或空数组。### 缺失不等于零-旧 Hook 数据没有某个计数字段时, `nil` 表示当时没有采集能力. `0` 才表示数据源明确确认没有发生+旧 Hook 数据没有某个计数字段时,`nil` 表示当时没有采集能力。`0` 才表示数据源明确确认没有发生。-如果把两者合并, 历史图表会把不可知数据画成真实零值, 后续无法再修复解释+如果把两者合并,历史图表会把不可知数据画成真实零值,后续无法再修复解释。### 陈旧不等于失败-同一账户的 app-server 补充接口暂时失败时, 旧额度或用量仍有参考价值. 快照用 `isRateLimitsStale` 和 `isUsageStale` 标记它们, UI 通过透明度表达可信度下降, 通知则完全跳过陈旧额度+同一账户的 app-server 补充接口暂时失败时,旧额度或用量仍有参考价值。快照用 `isRateLimitsStale` 和 `isUsageStale` 标记它们,UI 通过透明度表达可信度下降,通知则完全跳过陈旧额度。### 降级 bootstrap 不等于空闲-实时 reader 无法获得稳定文件边界时会跳到文件末尾, 但同时发布 degraded 和数据源不健康. 这不是"确认当前没有任务", 而是"无法可靠恢复现有任务"+实时 reader 无法获得稳定文件边界时会跳到文件末尾,但同时发布 degraded 和数据源不健康。这不是“确认当前没有任务”,而是“无法可靠恢复现有任务”。## 为什么大量使用 generation-CodexBar 的 I/O 大多具有以下共同风险+CodexBar 的 I/O 大多具有以下共同风险:1. 请求 A 开始2. 用户改变设置或 reader 被替换3. 请求 B 开始并先完成4. 请求 A 最后返回-只取消 Task 不足以解决这个问题. 某些系统 API 和同步桥接不能真正取消, 旧回调仍可能到达+只取消 Task 不足以解决这个问题。某些系统 API 和同步桥接不能真正取消,旧回调仍可能到达。-因此关键异步路径同时维护单调递增 generation+因此关键异步路径同时维护单调递增 generation:- 刷新协调器只允许当前 generation 提交- Hook 设置只允许最新操作更新 UI@@ -141,161 +141,161 @@ CodexBar 的 I/O 大多具有以下共同风险- XPC 租约请求用 generation 防止迟到的 acquire 覆盖 release- helper 状态请求和 CloudKit 可用性检查也按 generation 丢弃旧结果-generation 的价值不是"更容易取消", 而是让提交资格成为可以验证的显式条件+generation 的价值不是“更容易取消”,而是让提交资格成为可以验证的显式条件。-## 为什么使用 actor, MainActor 和锁三种并发手段+## 为什么使用 actor、MainActor 和锁三种并发手段-三者解决的问题不同+三者解决的问题不同:| 手段 | 解决范围 | 典型对象 || --- | --- | --- || `MainActor` | UI 可观察状态和 AppKit 生命周期 | Controller, ViewModel, Settings, Monitor |-| Swift actor | 单进程内异步可变状态 | app-server, 聚合, reader, CloudKit service |+| Swift actor | 单进程内异步可变状态 | app-server、聚合、reader、CloudKit service || `flock` | 多进程共享文件事务 | Hook recorder 与主 App 的统计文件 |-actor 不能保护另一个 CodexBar Hook 子进程. `flock` 也不适合承载 UI 状态. 选择并发工具时先确认竞争发生在哪个边界, 不要因为项目已经使用 actor 就把所有同步问题都塞进 actor+actor 不能保护另一个 CodexBar Hook 子进程。`flock` 也不适合承载 UI 状态。选择并发工具时先确认竞争发生在哪个边界,不要因为项目已经使用 actor 就把所有同步问题都塞进 actor。-默认 `MainActor` 让 UI 类型更安全, 代价是任何阻塞式文件或 pipe 等待都必须显式移出主 actor. `AppServerSession` 和底层 pipe reader 使用受锁保护的非隔离边界, 上层 `CodexStatusService` actor 再串行管理连接+默认 `MainActor` 让 UI 类型更安全,代价是任何阻塞式文件或 pipe 等待都必须显式移出主 actor。`AppServerSession` 和底层 pipe reader 使用受锁保护的非隔离边界,上层 `CodexStatusService` actor 再串行管理连接。## 为什么原始日志与派生缓存分开-Hook 原始 JSONL 是可审计事实, `daily.jsonl` 是当前算法生成的缓存+Hook 原始 JSONL 是可审计事实,`daily.jsonl` 是当前算法生成的缓存。-这种结构提供 3 个长期收益+这种结构提供 3 个长期收益:-- 聚合算法修正后可以重建历史, 不需要为每个旧字段设计迁移-- 写入关键路径只追加一行, 不需要在 Codex 等待的几秒内读改写整份统计-- CloudKit 同步可以只上传聚合, 保持原始身份和路径留在本机+- 聚合算法修正后可以重建历史,不需要为每个旧字段设计迁移+- 写入关键路径只追加一行,不需要在 Codex 等待的几秒内读改写整份统计+- CloudKit 同步可以只上传聚合,保持原始身份和路径留在本机-代价是必须明确管理 schema, offset 和来源替换. 因此维护状态保存 `sourceGeneration`, inode, size, boundary hash 和 dirty/pending 状态+代价是必须明确管理 schema、offset 和来源替换。因此维护状态保存 `sourceGeneration`, inode, size, boundary hash 和 dirty/pending 状态。## `sourceGeneration` 解决的不是版本号问题-同一天的事件文件可能被替换, 截断或由用户重建. 日期相同并不代表它还是同一份事实来源+同一天的事件文件可能被替换、截断或由用户重建。日期相同并不代表它还是同一份事实来源。-`sourceGeneration` 给"这份日期数据来自哪一代原始文件"一个稳定身份+`sourceGeneration` 给“这份日期数据来自哪一代原始文件”一个稳定身份:- 正常追加保持同一 generation-- inode 变化, 文件缩小或已消费边界被改写时创建新 generation+- inode 变化、文件缩小或已消费边界被改写时创建新 generation- CloudKit record name 可以区分不同 generation-- 展示层只把明确独立的贡献相加, 同源结果按替换处理+- 展示层只把明确独立的贡献相加,同源结果按替换处理-如果只用日期作为身份, 重建后的新值会和旧云端值叠加, 产生永久双重计数+如果只用日期作为身份,重建后的新值会和旧云端值叠加,产生永久双重计数。## 为什么实时任务同时读取 Hook 和 rollout-两种来源各自只解决一半问题+两种来源各自只解决一半问题:| 来源 | 优势 | 缺口 || --- | --- | --- |-| Hook | 延迟低, 事件类型清楚, 适合实时 UI | `Stop` 不能总是区分完成与中断, 部分上下文字段可能缺失 |-| rollout | terminal, effort 和 reviewer 更权威 | 文件定位和解析更慢, 不适合作为唯一低延迟信号 |+| Hook | 延迟低、事件类型清楚、适合实时 UI | `Stop` 不能总是区分完成与中断,部分上下文字段可能缺失 |+| rollout | terminal, effort 和 reviewer 更权威 | 文件定位和解析更慢,不适合作为唯一低延迟信号 |-monitor 先用 Hook 建立活动状态, 再用 rollout 补齐生命周期. `Stop` 形成完成候选, `SessionEnd` 或新 prompt 会把任务移入短暂终态确认窗口, rollout 在宽限期内给出准确分类+monitor 先用 Hook 建立活动状态,再用 rollout 补齐生命周期。`Stop` 形成完成候选,`SessionEnd` 或新 prompt 会把任务移入短暂终态确认窗口,rollout 在宽限期内给出准确分类。-这不是简单的"双源合并". 冲突时需要按语义决定谁更权威, 还要防止迟到事件复活已经完成的任务+这不是简单的“双源合并”。冲突时需要按语义决定谁更权威,还要防止迟到事件复活已经完成的任务。## 为什么特权 helper 只接受睡眠租约-App 需要 root 权限修改 `pmset disablesleep`, 但任务识别, 网络和文件解析不需要 root+App 需要 root 权限修改 `pmset disablesleep`,但任务识别、网络和文件解析不需要 root。-把策略放进 helper 会显著扩大攻击面和故障恢复范围. 当前边界把 helper 限制为一个小型执行器+把策略放进 helper 会显著扩大攻击面和故障恢复范围。当前边界把 helper 限制为一个小型执行器:-- 输入只有租约, generation, 状态查询和更新恢复标识+- 输入只有租约、generation、状态查询和更新恢复标识- 命令固定为 `/usr/bin/pmset` 的固定参数组合- 客户端通过 code-signing requirement 校验-- helper 不读取 Codex 文件, 不访问网络, 不接受任意路径或命令+- helper 不读取 Codex 文件、不访问网络、不接受任意路径或命令-App 决定"应该怎样", helper 只负责"以受限权限执行并验证"+App 决定“应该怎样”,helper 只负责“以受限权限执行并验证”。## 为什么租约还需要所有权记录-租约解决"还有没有活跃 App 请求", 所有权解决"当前系统值是不是 CodexBar 改的"+租约解决“还有没有活跃 App 请求”,所有权解决“当前系统值是不是 CodexBar 改的”。-两者不能互相替代+两者不能互相替代:- 没有租约时 helper 应撤销自己的效果-- 但如果 `SleepDisabled=1` 原本由用户或其他 App 设置, CodexBar 没有权恢复为 `0`-- 如果 CodexBar 完成了 `0 -> 1`, helper 必须先持久化 owned, 崩溃后才能恢复+- 但如果 `SleepDisabled=1` 原本由用户或其他 App 设置,CodexBar 没有权恢复为 `0`+- 如果 CodexBar 完成了 `0 -> 1`,helper 必须先持久化 owned,崩溃后才能恢复-因此释放条件是"最后一个租约结束并且 ownership 为 owned", 而不是简单看到没有客户端就写 `0`+因此释放条件是“最后一个租约结束并且 ownership 为 owned”,而不是简单看到没有客户端就写 `0`## 为什么 CloudKit 同步聚合而不是原始事件-跨设备展示只需要日级统计. 上传原始事件会带来额外身份信息, 更大的数据量和更复杂的去重, 却不增加当前产品能力+跨设备展示只需要日级统计。上传原始事件会带来额外身份信息、更大的数据量和更复杂的去重,却不增加当前产品能力。-同步聚合的收益包括+同步聚合的收益包括:- session, turn 和 agent ID 保留在本机- 网络和 CloudKit 操作量由事件数降为日期数-- 本机仍然可以独立重建, 云端只保存各设备贡献+- 本机仍然可以独立重建,云端只保存各设备贡献- 设备间合并规则可以围绕 `deviceId + date + sourceGeneration` 定义-project 显示名仍可能敏感, 所以同步必须由用户主动开启, 不能因为已经登录 iCloud 就默认上传+project 显示名仍可能敏感,所以同步必须由用户主动开启,不能因为已经登录 iCloud 就默认上传。## 容易忽略的小巧思### `@Published` 回调参数比现场回读更可靠-Combine 的发布发生在 `willSet`. 订阅闭包执行时, 属性本身可能仍是旧值+Combine 的发布发生在 `willSet`。订阅闭包执行时,属性本身可能仍是旧值。-因此 Hook 可用性, 同步 activation 和防睡眠依赖在订阅路径中使用闭包参数计算, 而不是立刻回读对象属性. 这是多个看似重复的状态镜像存在的原因+因此 Hook 可用性、同步 activation 和防睡眠依赖在订阅路径中使用闭包参数计算,而不是立刻回读对象属性。这是多个看似重复的状态镜像存在的原因。### 边界 hash 只覆盖已经消费的尾部-历史聚合不对每个文件每轮全量 hash. 它只保存 offset 前 4 KB 的 boundary hash, 再用 mtime 判断是否需要重算+历史聚合不对每个文件每轮全量 hash。它只保存 offset 前 4 KB 的 boundary hash,再用 mtime 判断是否需要重算。-正常追加只发生在 offset 之后, 不会改变这个边界. 这既能发现已消费内容被原地改写, 又避免长期持有 `stats.lock`, 让 Hook 子进程更快落盘+正常追加只发生在 offset 之后,不会改变这个边界。这既能发现已消费内容被原地改写,又避免长期持有 `stats.lock`,让 Hook 子进程更快落盘。### 状态排序有 UUID 兜底-多个任务时间戳可能相同, 而 Swift sort 不稳定. 快照在时间相等时再按 UUID 字符串排序, 避免 SwiftUI diff 因无意义的顺序抖动反复刷新+多个任务时间戳可能相同,而 Swift sort 不稳定。快照在时间相等时再按 UUID 字符串排序,避免 SwiftUI diff 因无意义的顺序抖动反复刷新。### 通知提交前再次检查相关性-等待批准和异常保护通知从判定到系统真正接收之间存在异步窗口. 任务可能已经恢复运行+等待批准和异常保护通知从判定到系统真正接收之间存在异步窗口。任务可能已经恢复运行。-通知服务在每次提交和重试前调用 `isStillRelevant`, 失效则撤回 pending 与 delivered notification. 这比只在状态变化时尝试删除更可靠+通知服务在每次提交和重试前调用 `isStillRelevant`,失效则撤回 pending 与 delivered notification。这比只在状态变化时尝试删除更可靠。-### XPC 请求超时不能清除"可能持有租约"+### XPC 请求超时不能清除“可能持有租约”-请求超时只能说明回复没有到达, 不能证明 helper 没有执行 acquire. `mayHaveHelperLease` 因此一直保留到一次明确成功的 release+请求超时只能说明回复没有到达,不能证明 helper 没有执行 acquire。`mayHaveHelperLease` 因此一直保留到一次明确成功的 release。-如果超时就直接清零, App 退出时可能跳过释放, 让 helper 等到 watchdog 才恢复系统状态+如果超时就直接清零,App 退出时可能跳过释放,让 helper 等到 watchdog 才恢复系统状态。### 外部睡眠来源需要持续观察-任务开始时如果系统已经 `SleepDisabled=1`, helper 将来源标记为 external. 但外部来源可能在任务仍运行时自行撤销+任务开始时如果系统已经 `SleepDisabled=1`,helper 将来源标记为 external。但外部来源可能在任务仍运行时自行撤销。-helper 定期读取实际值. 一旦 external 消失而租约仍有效, CodexBar 可以安全完成自己的 `0 -> 1` 并取得 owned, 防睡眠不会悄悄失效+helper 定期读取实际值。一旦 external 消失而租约仍有效,CodexBar 可以安全完成自己的 `0 -> 1` 并取得 owned,防睡眠不会悄悄失效。### 菜单栏锚点必须先验证-全局快捷键触发时, `NSStatusBarButton` 可能暂时没有可用 window 或位于另一块屏幕. 直接展示 popover 会出现位置错误或完全不显示+全局快捷键触发时,`NSStatusBarButton` 可能暂时没有可用 window 或位于另一块屏幕。直接展示 popover 会出现位置错误或完全不显示。-控制器先验证锚点尺寸和屏幕交集, 不可信时在鼠标所在屏幕使用 fallback panel. 两种容器共享同一个 SwiftUI 内容, 业务层不用知道当前是哪一种+控制器先验证锚点尺寸和屏幕交集,不可信时在鼠标所在屏幕使用 fallback panel。两种容器共享同一个 SwiftUI 内容,业务层不用知道当前是哪一种。### 只调度最近一个真实截止时间-任务过期, 完成高亮, terminal grace 和异常静默都不是靠高频 UI timer 扫描. monitor 收集所有截止时间, 只为最近一个建立 Task, 到点后重算并安排下一次+任务过期、完成高亮、terminal grace 和异常静默都不是靠高频 UI timer 扫描。monitor 收集所有截止时间,只为最近一个建立 Task,到点后重算并安排下一次。-这样能减少菜单栏 App 常驻时的无意义唤醒, 也让每个保留期在代码中有明确来源+这样能减少菜单栏 App 常驻时的无意义唤醒,也让每个保留期在代码中有明确来源。## 修改设计时的检查方法-新增功能或修改核心语义前, 依次回答以下问题+新增功能或修改核心语义前,依次回答以下问题:-1. 新数据来自哪条链路, 它的权威来源是什么-2. 数据缺失, 旧值, 明确零值和失败是否被区分-3. 这是可重复读取的状态, 还是最多执行一次的 transition+1. 新数据来自哪条链路,它的权威来源是什么+2. 数据缺失、旧值、明确零值和失败是否被区分+3. 这是可重复读取的状态,还是最多执行一次的 transition4. 异步结果返回时如何证明自己仍属于当前 generation-5. 是否扩大了网络, 持久化, CloudKit 或 root helper 的边界-6. 是否影响旧 UserDefaults, 本地 schema, CloudKit record 或 Debug 与 Release 共存-7. 崩溃, 强制退出, 系统睡眠和文件替换后如何恢复-8. 哪些日志足以区分正常降级和真实故障, 同时不泄露用户数据-9. 哪些手动场景能验证设计不变量, 而不只是验证理想路径+5. 是否扩大了网络、持久化、CloudKit 或 root helper 的边界+6. 是否影响旧 UserDefaults、本地 schema、CloudKit record 或 Debug 与 Release 共存+7. 崩溃、强制退出、系统睡眠和文件替换后如何恢复+8. 哪些日志足以区分正常降级和真实故障,同时不泄露用户数据+9. 哪些手动场景能验证设计不变量,而不只是验证理想路径-如果其中任何一项没有明确答案, 说明实现还没有形成完整的生命周期设计+如果其中任何一项没有明确答案,说明实现还没有形成完整的生命周期设计。## 不应轻易改变的不变量@@ -307,9 +307,8 @@ helper 定期读取实际值. 一旦 external 消失而租约仍有效, CodexBar- 缺失的计数字段不解释为 `0`- 原始事件是聚合缓存的重建来源- 聚合语义变化递增 schema 并完整重建-- root helper 不获得网络, 任意命令或额外文件读取能力+- root helper 不获得网络、任意命令或额外文件读取能力- 只有 CodexBar 自己取得的睡眠所有权可以由 CodexBar 恢复-- 通知描述系统效果时, 必须在效果已经确认后发送-- 匿名任务不进入通知, 防睡眠和异常会话保护+- 通知描述系统效果时,必须在效果已经确认后发送+- 匿名任务不进入通知、防睡眠和异常会话保护- 兼容性变化必须先确定迁移与降级策略-diff --git a/Docs/DeveloperGuide/development.md b/Docs/DeveloperGuide/development.mdindex 70f4d6c..9516a59 100644--- a/Docs/DeveloperGuide/development.md+++ b/Docs/DeveloperGuide/development.md@@ -9,18 +9,18 @@- `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` | 版本配置 |@@ -28,7 +28,7 @@## 第一次阅读代码的建议顺序-不要从 View 反向猜业务状态. 推荐沿事实流阅读+不要从 View 反向猜业务状态。推荐沿事实流阅读:1. 从 [`CodexBarApp.swift`](../../CodexBar/App/CodexBarApp.swift) 确认 Hook 子进程分流2. 从 [`StatusItemController.swift`](../../CodexBar/Controllers/StatusItemController.swift) 查看普通模式 composition root@@ -36,7 +36,7 @@4. 再看通知或防睡眠如何订阅上游结果5. 最后查看 SwiftUI 如何展示状态和发出用户意图-以实时任务为例+以实时任务为例:```textWorkflowHookEventRecorder@@ -49,21 +49,21 @@ WorkflowHookEventRecorder-> KeepAliveController```-先找到 authoritative state 能避免把 UI 缓存, 通知去重集合或 controller 中间态误认为业务事实+先找到 authoritative state 能避免把 UI 缓存、通知去重集合或 controller 中间态误认为业务事实。## 修改前先写清楚 5 件事-实现一个非纯视觉变化前, 至少在设计或开发笔记中回答+实现一个非纯视觉变化前,至少在设计或开发笔记中回答:| 问题 | 示例 || --- | --- |-| 目标事实 | "任务已经等待用户批准", 而不是"显示橙点" |+| 目标事实 | “任务已经等待用户批准”,而不是“显示橙点” || 权威来源 | reviewer 确认后的 Hook event |-| 派生消费者 | 活动卡片, 通知, 防睡眠 |+| 派生消费者 | 活动卡片、通知、防睡眠 || 失败语义 | reader 不可用时暂停判定 |-| 验收证据 | 转场一次, 不补发 bootstrap, 恢复后对账 |+| 验收证据 | 转场一次、不补发 bootstrap、恢复后对账 |-这一步的价值不是增加流程, 而是提前发现一个字段被 3 个副作用消费者赋予了不同含义+这一步的价值不是增加流程,而是提前发现一个字段被 3 个副作用消费者赋予了不同含义。## 常见改动应该落在哪一层@@ -78,7 +78,7 @@ WorkflowHookEventRecorder| 窗口行为 | AppKit Controller | service 或 model || 用户默认值 | 对应 Settings 类型 | 分散的 `UserDefaults.standard` 调用 |-小改动优先延伸现有类型职责. 只有当新能力拥有独立生命周期, 状态所有权或故障边界时才值得新建 service+小改动优先延伸现有类型职责。只有当新能力拥有独立生命周期、状态所有权或故障边界时才值得新建 service。## 日常检查@@ -98,7 +98,7 @@ xcodebuild \swiftformat .```-工程使用 Swift 6 和 4 空格缩进, 配置位于 `.swiftformat`+工程使用 Swift 6 和 4 空格缩进,配置位于 `.swiftformat`### 静态检查@@ -108,7 +108,7 @@ swiftlint规则位于 `.swiftlint.yml`-仓库当前没有 XCTest target 或覆盖率门槛. 构建, 格式化和 lint 不能替代受影响流程的手动验证+仓库当前没有 XCTest target 或覆盖率门槛。构建、格式化和 lint 不能替代受影响流程的手动验证。### 推荐检查顺序@@ -123,26 +123,26 @@ swiftlint-> git diff --check```-先格式化再构建可以让最终验证覆盖真正准备提交的代码. 但仓库已有用户未提交改动时, 不应无差别格式化整个仓库造成无关修改. 先用 `git status --short` 和 `git diff --name-only` 确认范围, 必要时只格式化本次触及的 Swift 文件+先格式化再构建可以让最终验证覆盖真正准备提交的代码。但仓库已有用户未提交改动时,不应无差别格式化整个仓库造成无关修改。先用 `git status --short` 和 `git diff --name-only` 确认范围,必要时只格式化本次触及的 Swift 文件。-`xcodebuild` 验证 Swift 6 并发检查, target membership, entitlement 和资源引用. `swiftlint` 验证风格与部分静态规则. 两者不能验证 AppKit focus, XPC crash recovery 或通知 relevance+`xcodebuild` 验证 Swift 6 并发检查、target membership、entitlement 和资源引用。`swiftlint` 验证风格与部分静态规则。两者不能验证 AppKit focus、XPC crash recovery 或通知 relevance。-纯文档变更仍按仓库约定运行格式化, lint 和构建. 这些检查不验证文档内容, 因此还要额外检查 Markdown 相对链接, `git diff --check` 和仓库中文标点规则+纯文档变更仍按仓库约定运行格式化、lint 和构建。这些检查不验证文档内容,因此还要额外检查 Markdown 相对链接、`git diff --check` 和仓库中文标点规则。### 如何读构建失败优先找第一条实际 `error:` 而不是最后的 `BUILD FAILED`-- actor isolation error 通常说明状态所有权不清, 不应先加 `nonisolated(unsafe)` 压掉+- actor isolation error 通常说明状态所有权不清,不应先加 `nonisolated(unsafe)` 压掉- missing file 或 resource error 先检查 target membership 和 Xcode project 引用-- helper protocol error 需要同时检查 App target, Helper target 和 `Shared` 接口+- helper protocol error 需要同时检查 App target、Helper target 和 `Shared` 接口- entitlement 或 signing error 要先确认当前是 Debug 还是 Release identity-修复第一处根因后重新构建, 后续大量泛型或 module error 往往只是级联结果+修复第一处根因后重新构建,后续大量泛型或 module error 往往只是级联结果。## 日志-查看 Release 系统日志+查看 Release 系统日志:```bash/usr/bin/log stream \@@ -150,13 +150,13 @@ 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 和重试。### 日志应回答什么-一条有用状态机日志应至少能回答+一条有用状态机日志应至少能回答:- 谁触发了本轮操作- 当前想达到什么状态@@ -164,72 +164,72 @@ App 内日志窗口展示当前进程最近 500 条 app-server 交互日志, 适- 采取了什么降级或重试动作- 操作耗时和处理规模-仓库使用 `LogTrigger`, `LogDuration` 和 `LogFields.joined` 统一这些字段. 高频轮询只在状态翻转或结果变化时记录, 避免真正异常被空转日志覆盖+仓库使用 `LogTrigger`, `LogDuration` 和 `LogFields.joined` 统一这些字段。高频轮询只在状态翻转或结果变化时记录,避免真正异常被空转日志覆盖。-推荐用稳定英文 key 加受控值, 例如+推荐用稳定英文 key 加受控值,例如:```texttrigger=wake want=0 reason=lowBattery elapsed=0.183s```-不要记录通知正文, 完整路径, identity 或 token. 如果错误的 `localizedDescription` 可能包含敏感请求信息, 应先做错误分类再记录+不要记录通知正文、完整路径、identity 或 token。如果错误的 `localizedDescription` 可能包含敏感请求信息,应先做错误分类再记录。### 按 subsystem 和阶段排查| 症状 | 优先日志和状态 || --- | --- || 额度不刷新 | app-server handshake, method, retry, stale |-| Hook 没有统计 | hooks 配置, recorder timeout, maintenance counts |+| Hook 没有统计 | hooks 配置、recorder timeout、maintenance counts || 实时任务卡住 | tail reader generation, rollout reconcile, data source availability |-| 同步缺数据 | sync stage, local 和 confirmed 数量, replacement dates |+| 同步缺数据 | 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 工作事实, 因而按设计共享文件+Debug 和 Release bundle ID 分离是为了让 App、helper 注册和系统授权互不覆盖。但 Hook 原始数据与 Activity Protection 需要观察同一个 Codex 工作事实,因而按设计共享文件。-共享意味着+共享意味着:-- 文件写入必须使用 `flock`, actor 只保护单进程+- 文件写入必须使用 `flock`,actor 只保护单进程- schema 必须在两个版本共存时可解释- identity hash 算法变化会同时影响两个构建-- 排查时要记录哪个 App 正在写, 哪个 helper 正在控制系统+- 排查时要记录哪个 App 正在写,哪个 helper 正在控制系统-不要用修改目录名的方式临时隔离 Debug, 这会改变产品定义的数据来源并掩盖真实共存问题+不要用修改目录名的方式临时隔离 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 状态修改更清晰, 但不意味着文件和子进程工作可以同步执行在主线程+工程默认隔离让 UI 状态修改更清晰,但不意味着文件和子进程工作可以同步执行在主线程。-合适的模式是+合适的模式是:```textMainActor 捕获不可变输入@@ -239,49 +239,49 @@ MainActor 捕获不可变输入-> 提交快照```-不要把可变 controller 或 non-Sendable AppKit 对象传入后台 closure. 需要跨 actor 的 DTO 应尽量是小型 value type, 并让 `nonisolated` 表达类型本身不依赖 actor, 而不是绕开某个具体访问错误+不要把可变 controller 或 non-Sendable AppKit 对象传入后台 closure。需要跨 actor 的 DTO 应尽量是小型 value type,并让 `nonisolated` 表达类型本身不依赖 actor,而不是绕开某个具体访问错误。#### actor 与 `flock` 解决的问题不同- actor 串行化同一进程中的 task-- `flock` 协调 App, Hook 子进程, Debug 和 Release 等多个进程+- `flock` 协调 App、Hook 子进程、Debug 和 Release 等多个进程-一个 actor 内安全的 read-modify-write 仍可能被另一个进程打断. 反过来, 只有 `flock` 也不能自动保护 actor reentrancy 中 await 前后的内存状态+一个 actor 内安全的 read-modify-write 仍可能被另一个进程打断。反过来,只有 `flock` 也不能自动保护 actor reentrancy 中 await 前后的内存状态。#### `@Published` 的 `willSet` 语义-Combine sink 收到新值时, 发布对象的属性可能仍是旧值. 需要基于变化后组合状态决策时+Combine sink 收到新值时,发布对象的属性可能仍是旧值。需要基于变化后组合状态决策时:- 使用 sink 参数作为正在变化的值- 其余未变化依赖可以从对象读取- 或把完整新状态封装成一个快照再发布-仓库中的同步 activation 和低额度阈值重判都依赖这一规则. 将回调参数改成现场读取会产生一帧反向决策+仓库中的同步 activation 和低额度阈值重判都依赖这一规则。将回调参数改成现场读取会产生一帧反向决策。### 数据链路-保持以下链路独立+保持以下链路独立:-- app-server 账户, 额度与用量+- app-server 账户、额度与用量- Hook 历史聚合- `CodexActivityMonitor` 实时任务-新增 UI 可以组合 3 条链路的快照, 但不能让一条链路成为另一条链路的隐式前置条件+新增 UI 可以组合 3 条链路的快照,但不能让一条链路成为另一条链路的隐式前置条件。-组合只能发生在展示或显式业务策略层. 例如菜单栏可以同时展示额度条和活动点, 但 app-server 失败不能阻止 activity monitor 更新, Hook maintenance 也不能等待 CloudKit 才发布本机统计+组合只能发生在展示或显式业务策略层。例如菜单栏可以同时展示额度条和活动点,但 app-server 失败不能阻止 activity monitor 更新,Hook maintenance 也不能等待 CloudKit 才发布本机统计。-新增跨链路行为时应写出 truth table. 防睡眠就是一个合法例子: 它明确声明需要 Hook 可用和非匿名实时任务, 而不是因为两个对象恰好在同一 controller 中就形成依赖+新增跨链路行为时应写出 truth table。防睡眠就是一个合法例子:它明确声明需要 Hook 可用和非匿名实时任务,而不是因为两个对象恰好在同一 controller 中就形成依赖。### Hook- handler 修改保留现有用户和第三方配置- 启用与校验检查实际 app-server 版本不低于 `0.145.0`- Hook 子进程失败不能阻断 Codex-- `SessionEnd` 超时为 3 秒, 其他事件为 5 秒+- `SessionEnd` 超时为 3 秒,其他事件为 5 秒- `drainNow()` 必须维持读取屏障语义- 数据源不可用时不能使用旧快照继续判定-新增 Hook event 时要同时审查+新增 Hook event 时要同时审查:1. Codex 配置中的 handler group 和 timeout2. recorder 白名单字段与 fail-open 路径@@ -291,11 +291,11 @@ Combine sink 收到新值时, 发布对象的属性可能仍是旧值. 需要基6. CloudKit 投影是否需要新字段7. 隐私文档和日志字段-不是每个 event 都需要进入全部层. 明确写"不消费"比让下游依赖默认 decoder 行为更容易维护+不是每个 event 都需要进入全部层。明确写“不消费”比让下游依赖默认 decoder 行为更容易维护。### 聚合-原始事件到聚合结果的算法, 字段, 含义或去重规则变化时+原始事件到聚合结果的算法、字段、含义或去重规则变化时:1. 递增 `WorkflowMaintenanceState.currentAggregationSchema`2. 从保留期内原始 JSONL 完整重建@@ -303,25 +303,25 @@ Combine sink 收到新值时, 发布对象的属性可能仍是旧值. 需要基4. 保留 missing 与 `0` 的区别5. 标记 CloudKit 当前设备 replacement 日期-schema 递增的判断标准是语义输出是否会因同一份 raw event 得到不同结果, 而不是 Codable 是否还能解码. 即使只修正去重规则, 也必须重建, 因为旧 daily 文件已经固化了错误结果+schema 递增的判断标准是语义输出是否会因同一份 raw event 得到不同结果,而不是 Codable 是否还能解码。即使只修正去重规则,也必须重建,因为旧 daily 文件已经固化了错误结果。-完整重建优于字段级迁移, 因为 raw JSONL 才是事实来源. 字段级迁移必须猜测旧算法中丢失的信息, 长期会堆积不可组合的历史分支+完整重建优于字段级迁移,因为 raw JSONL 才是事实来源。字段级迁移必须猜测旧算法中丢失的信息,长期会堆积不可组合的历史分支。### 防睡眠- CodexBarHelper 只控制睡眠- CodexBarHelper 不增加网络或任意命令能力- 外部 `SleepDisabled=1` 不能被 CodexBar 声明或恢复-- 租约, watchdog 和 owned 持久化必须共同成立+- 租约、watchdog 和 owned 持久化必须共同成立- App 退出前确认系统状态恢复-修改防睡眠时先写出 acquire, release, timeout, crash 和 external-owner 5 条时序. 只验证正常开关无法证明全局系统状态可恢复+修改防睡眠时先写出 acquire, release, timeout, crash 和 external-owner 5 条时序。只验证正常开关无法证明全局系统状态可恢复。-任何新增 helper 方法都要先证明必须由 root 执行. 能在普通 App 完成的读取, 网络或文件操作不得因为"方便复用"放进 helper+任何新增 helper 方法都要先证明必须由 root 执行。能在普通 App 完成的读取、网络或文件操作不得因为“方便复用”放进 helper。### 兼容性-以下变化属于兼容性问题+以下变化属于兼容性问题:- 持久化 key 改名或结构变化- 本地 schema 变化@@ -330,36 +330,36 @@ schema 递增的判断标准是语义输出是否会因同一份 raw event 得- Debug 与 Release 共享身份计算变化- 最低系统版本或 API 可用性变化-这些变化会影响旧数据, 旧 App 或 Debug 与 Release 共存, 需要配套的迁移和降级设计+这些变化会影响旧数据、旧 App 或 Debug 与 Release 共存,需要配套的迁移和降级设计。-根据仓库约定, 任何兼容性问题都不能由实现者默默选择. 在修改前向用户说明+根据仓库约定,任何兼容性问题都不能由实现者默默选择。在修改前向用户说明:- 受影响版本和数据范围-- 保留旧格式, 一次迁移, 完整重建或明确丢弃的可选方案+- 保留旧格式、一次迁移、完整重建或明确丢弃的可选方案- 每种方案的失败模式和未来维护成本- 是否支持旧 App 与新 App 同时运行- 如何验证升级和必要时降级-得到选择后再实现. 文档中记录最终不变量, 不只记录迁移步骤+得到选择后再实现。文档中记录最终不变量,不只记录迁移步骤。## 常见改动配方### 新增设置项1. 在对应 Settings 或 controller 中定义唯一 key 和缺失时默认值-2. 明确旧用户升级后的值, 不依赖 Swift 属性默认值碰巧一致+2. 明确旧用户升级后的值,不依赖 Swift 属性默认值碰巧一致3. 把设置变化接入唯一 reconcile 入口4. 避免 View 自己写 `UserDefaults`-5. 验证首次安装, 已有安装和切换后立即生效+5. 验证首次安装、已有安装和切换后立即生效### 新增状态字段-1. 确认字段是事实, 派生状态还是展示格式+1. 确认字段是事实、派生状态还是展示格式2. 放入最靠近权威来源的 model3. 定义 `nil`, empty, zero 和 stale4. 检查 Equatable snapshot 是否应因它变化-5. 检查通知, 防睡眠和 UI 是否需要消费-6. 如需持久化或同步, 先走兼容性与隐私审查+5. 检查通知、防睡眠和 UI 是否需要消费+6. 如需持久化或同步,先走兼容性与隐私审查### 新增异步刷新@@ -367,7 +367,7 @@ schema 递增的判断标准是语义输出是否会因同一份 raw event 得2. 使用 single-flight 或 coordinator 合并同类请求3. 为连接或 source replacement 增加 generation4. 在 await 后重新验证当前资格-5. 定义取消, 超时和最后可用快照策略+5. 定义取消、超时和最后可用快照策略6. 只在状态变化或最终结果记录日志### 新增窗口或侧边面板@@ -376,13 +376,13 @@ schema 递增的判断标准是语义输出是否会因同一份 raw event 得2. 复用 `HostingWindowController` 或 `MenuSideDetailPanel`3. 加入互斥名册和 extra hit region4. 处理多屏 visible frame 和 Space-5. 验证 key focus, activation 和关闭动画中间态+5. 验证 key focus、activation 和关闭动画中间态## 按改动类型验证### 菜单和窗口-- 左键, 右键和 Control 点击行为+- 左键、右键和 Control 点击行为- popover 外部点击关闭- 侧边面板 hit region 和互斥- 设置与日志窗口焦点@@ -394,13 +394,13 @@ schema 递增的判断标准是语义输出是否会因同一份 raw event 得- 保留已有 handler- 版本不满足时拒绝启用- 所有事件能在超时内落盘-- 文件替换, 截断和跨日读取+- 文件替换、截断和跨日读取- schema 升级完整重建- missing 字段不会显示为 `0`### 实时任务-- 运行, 等待批准, 完成和中断转场+- 运行、等待批准、完成和中断转场- auto review 不进入等待状态- subagent 归属父任务- bootstrap 不发送通知@@ -412,7 +412,7 @@ schema 递增的判断标准是语义输出是否会因同一份 raw event 得- 首次 backfill- 多设备合并不重复本机贡献- 重建只替换当前设备日期-- iCloud 离线, 账户切换和恢复+- iCloud 离线、账户切换和恢复- 保留期清理### 通知@@ -436,16 +436,16 @@ schema 递增的判断标准是语义输出是否会因同一份 raw event 得## 手动验证如何留下可复查证据-每个受影响流程至少记录+每个受影响流程至少记录:- 使用的 Debug 或 Release 构建- 前置设置和数据状态- 操作序列- 预期 UI 与实际 UI- 对应日志关键字段-- 是否检查重启, 失败和恢复路径+- 是否检查重启、失败和恢复路径-例如 Hook 唤醒恢复可以记录+例如 Hook 唤醒恢复可以记录:```text前置: 1 个非匿名 running task, 防睡眠开启@@ -454,27 +454,27 @@ schema 递增的判断标准是语义输出是否会因同一份 raw event 得日志: trigger=wake, reader generation 更新, rollout reconcile 完成```-这种记录比"手测通过"更容易在未来回归时重现+这种记录比“手测通过”更容易在未来回归时重现。## 完成定义-一项改动只有同时满足以下条件才算完成+一项改动只有同时满足以下条件才算完成:-- 代码放在正确状态所有者中, 没有复制第二份规则-- 正常, 缺失, stale, 失败和恢复语义明确+- 代码放在正确状态所有者中,没有复制第二份规则+- 正常、缺失、stale、失败和恢复语义明确- 并发请求有取消或 generation 边界- 兼容性和隐私影响已确认-- 格式化, lint 和构建按变更范围通过+- 格式化、lint 和构建按变更范围通过- 受影响流程完成手动验证-- DeveloperGuide 与实际常量, schema 和行为一致+- DeveloperGuide 与实际常量、schema 和行为一致- `git diff` 中没有无关用户改动或意外格式化## 发布脚本-以下脚本需要 Developer ID, 签名, 公证或 appcast 凭据, 不用于日常验证+以下脚本需要 Developer ID、签名、公证或 appcast 凭据,不用于日常验证:- `Scripts/build.sh`- `Scripts/dmg.sh`- `Scripts/appcast.sh`-版本号从 [`Version.xcconfig`](../../Config/Version.xcconfig) 读取+版本号从 [`Version.xcconfig`](../../Config/Version.xcconfig) 读取。diff --git a/Docs/DeveloperGuide/hook-and-aggregation.md b/Docs/DeveloperGuide/hook-and-aggregation.mdindex c077800..af871c2 100644--- a/Docs/DeveloperGuide/hook-and-aggregation.md+++ b/Docs/DeveloperGuide/hook-and-aggregation.md@@ -2,18 +2,18 @@## 设计出发点-Hook 链路同时服务两个看似接近但要求相反的目标+Hook 链路同时服务两个看似接近但要求相反的目标:- 在 Codex 关键路径上尽快记录事实- 在主 App 中可靠地维护长期统计-采集端必须短小, 有界和允许失败. 聚合端则可以异步运行, 需要检测文件变化, 修复损坏缓存并支持完整重建+采集端必须短小、有界和允许失败。聚合端则可以异步运行,需要检测文件变化、修复损坏缓存并支持完整重建。-因此实现采用 append-only 原始 JSONL 加可重建日聚合, 而不是让 Hook 子进程直接更新一份复杂统计对象+因此实现采用 append-only 原始 JSONL 加可重建日聚合,而不是让 Hook 子进程直接更新一份复杂统计对象。## 链路职责-Hook 链路把 Codex 生命周期事件转换为可重建的本地历史统计+Hook 链路把 Codex 生命周期事件转换为可重建的本地历史统计:```textCodex Hook@@ -24,33 +24,33 @@ Codex Hook-> 活跃度 UI 和 CloudKit 同步```-原始事件是事实来源, 日级聚合是可重建缓存. 聚合算法或字段语义变化时, 必须从保留期内的原始事件完整重建+原始事件是事实来源,日级聚合是可重建缓存。聚合算法或字段语义变化时,必须从保留期内的原始事件完整重建。### 为什么不在 Hook 子进程里直接聚合-直接读改写 `daily.jsonl` 看起来少一层文件, 实际会带来 4 个问题+直接读改写 `daily.jsonl` 看起来少一层文件,实际会带来 4 个问题:-- 每个 Hook 都要解码和重写历史数据, 事件越多延迟越高-- 子进程在 Codex 的超时预算内, 聚合失败会放大成任务延迟+- 每个 Hook 都要解码和重写历史数据,事件越多延迟越高+- 子进程在 Codex 的超时预算内,聚合失败会放大成任务延迟- 算法升级后没有原始事实可重算- 多个并发 Codex session 更容易在读改写之间丢失更新-当前方案把关键路径缩成一条 append. 主 App 可以在自己的节奏里批量聚合, 失败时保留原始事件等待下一轮修复+当前方案把关键路径缩成一条 append。主 App 可以在自己的节奏里批量聚合,失败时保留原始事件等待下一轮修复。### 原始事实和缓存的责任| 文件 | 是否权威 | 允许怎样恢复 || --- | --- | --- |-| `events/YYYY-MM-DD.jsonl` | 是 | 只追加, 超过保留期后清理 |+| `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`@@ -58,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@@ -68,13 +68,13 @@ Codex Hook- 禁用时只移除精确匹配的 CodexBar handler- 无法识别的配置保持原样-`isEnabled` 只表示 handler 存在, `isVerified` 表示最近一次 app-server 校验通过. UI 只有在 `isOperable` 成立时把 Hook 当作可工作数据源+`isEnabled` 只表示 handler 存在,`isVerified` 表示最近一次 app-server 校验通过。UI 只有在 `isOperable` 成立时把 Hook 当作可工作数据源。### 为什么安装和验证是两件事-`hooks.json` 中存在命令只能证明配置写在磁盘上, 不能证明 Codex 会执行它+`hooks.json` 中存在命令只能证明配置写在磁盘上,不能证明 Codex 会执行它。-实际执行还可能被以下条件阻止+实际执行还可能被以下条件阻止:- 当前 app-server 版本过低- `features.hooks` 被全局关闭@@ -82,9 +82,9 @@ Codex Hook- app-server 解析到其他来源文件- handler 处于 untrusted 或 modified-因此 `isEnabled` 是本地配置事实, `isVerified` 是 Codex 对当前来源的最近明确结论. 防睡眠和任务通知只依赖两者合成的 `isOperable`+因此 `isEnabled` 是本地配置事实,`isVerified` 是 Codex 对当前来源的最近明确结论。防睡眠和任务通知只依赖两者合成的 `isOperable`-临时 RPC 失败只代表本轮无法验证, 不能反推 handler 已失效. 此时保留上一次明确结论, 同时展示操作错误供用户排查+临时 RPC 失败只代表本轮无法验证,不能反推 handler 已失效。此时保留上一次明确结论,同时展示操作错误供用户排查。### 启用事务的顺序@@ -100,33 +100,33 @@ Codex Hook-> 再次 hooks/list 完整校验```-前置检查发生在文件修改之前. 版本或全局开关不满足时, 用户文件一个字都不会改变+前置检查发生在文件修改之前。版本或全局开关不满足时,用户文件一个字都不会改变。-信任匹配同时要求 command 和 `sourcePath`. 只按 executable 匹配可能误信任另一份配置中的相同命令, 只按 source 匹配则可能碰到用户自己的 handler+信任匹配同时要求 command 和 `sourcePath`。只按 executable 匹配可能误信任另一份配置中的相同命令,只按 source 匹配则可能碰到用户自己的 handler。### 禁用为什么先查询信任 key-app-server 的 Hook key 来自它当前解析到的 handler. 如果先从 `hooks.json` 删除命令, 后续 `hooks/list` 已经无法反查对应 key+app-server 的 Hook key 来自它当前解析到的 handler。如果先从 `hooks.json` 删除命令,后续 `hooks/list` 已经无法反查对应 key。-因此禁用流程先保存精确匹配条目的 key, 再删 handler, 最后从 `hooks.state` 中清理这些 key. 清理时先读取完整 state 再 replace, 保留用户和其他工具的信任项+因此禁用流程先保存精确匹配条目的 key、再删 handler、最后从 `hooks.state` 中清理这些 key。清理时先读取完整 state 再 replace,保留用户和其他工具的信任项。-信任清理失败不会把 handler 重新装回去. UI 会表达"Hook 已关闭, 但清理未完成", 因为停止采集的用户意图已经成功+信任清理失败不会把 handler 重新装回去。UI 会表达“Hook 已关闭,但清理未完成”,因为停止采集的用户意图已经成功。### 为什么每个事件使用独立 group-CodexBar 不把命令塞进用户已有 group. 独立 group 让卸载时可以只删除自身 handler, 不需要理解用户 matcher 或其他 handler 之间的组合语义+CodexBar 不把命令塞进用户已有 group。独立 group 让卸载时可以只删除自身 handler,不需要理解用户 matcher 或其他 handler 之间的组合语义。-对于结构异常的同级条目, 移除逻辑选择跳过而不是让整个开关失败. CodexBar 只负责识别自己的命令, 不把自己变成用户 Hook 配置的全局校验器+对于结构异常的同级条目,移除逻辑选择跳过而不是让整个开关失败。CodexBar 只负责识别自己的命令,不把自己变成用户 Hook 配置的全局校验器。### 异步设置操作的代际-用户可以快速开关 Hook, App 激活也会触发校验. `CodexHookSettings` 每次操作递增 `updateGeneration` 并取消旧 Task+用户可以快速开关 Hook,App 激活也会触发校验。`CodexHookSettings` 每次操作递增 `updateGeneration` 并取消旧 Task。-每个文件写入或 RPC await 之后都会再次检查 generation. 旧操作即使无法真正取消, 也不能把新的开关状态或错误信息覆盖回去+每个文件写入或 RPC await 之后都会再次检查 generation。旧操作即使无法真正取消,也不能把新的开关状态或错误信息覆盖回去。## 支持的事件-CodexBar 订阅以下 Hook 事件+CodexBar 订阅以下 Hook 事件:| 事件 | 聚合或实时用途 || --- | --- |@@ -144,17 +144,17 @@ CodexBar 订阅以下 Hook 事件### 事件字段和用途并不完全相同-历史计数需要事件名, 日期, project, model 和身份集合. 实时状态还需要 turn, reviewer, effort, tool 和 agent 关联+历史计数需要事件名、日期、project、model 和身份集合。实时状态还需要 turn, reviewer, effort, tool 和 agent 关联。-把两类需求统一在一条最小原始记录中, 可以让 recorder 只写一次, 两个下游各自选择所需字段. 但新增字段前仍要证明至少有一个消费者需要它, 不能因为 Hook payload 中存在就全部持久化+把两类需求统一在一条最小原始记录中,可以让 recorder 只写一次,两个下游各自选择所需字段。但新增字段前仍要证明至少有一个消费者需要它,不能因为 Hook payload 中存在就全部持久化。-`PermissionRequest` 和 `UserPromptSubmit` 的 reviewer 或 effort 可能不在 Hook payload 中. recorder 只在这两个事件上按 turn 定向读取 rollout 尾部, 避免所有事件都承担额外文件 I/O+`PermissionRequest` 和 `UserPromptSubmit` 的 reviewer 或 effort 可能不在 Hook payload 中。recorder 只在这两个事件上按 turn 定向读取 rollout 尾部,避免所有事件都承担额外文件 I/O。## Hook 子进程[`WorkflowHookEventRecorder.swift`](../../CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift) 在 App 启动最早阶段检查 `--hook-event`-命中后只执行以下工作+命中后只执行以下工作:1. 从 stdin 读取事件 JSON2. 提取统计和状态机需要的最小字段@@ -163,26 +163,26 @@ CodexBar 订阅以下 Hook 事件5. 在同一个锁事务中标记维护状态6. 立即退出-handler 超时由事件决定+handler 超时由事件决定:| 事件 | 超时 || --- | --- || `SessionEnd` | 3 秒 || 其他事件 | 5 秒 |-锁等待预算为 handler 超时减 2 秒. 获取锁时从 1 ms 开始指数退避, 单次等待最多 20 ms+锁等待预算为 handler 超时减 2 秒。获取锁时从 1 ms 开始指数退避,单次等待最多 20 ms。-stdin 无效, 文件锁超时或写入失败都会被吞掉. Hook 子进程不能因为统计失败而阻断 Codex+stdin 无效、文件锁超时或写入失败都会被吞掉。Hook 子进程不能因为统计失败而阻断 Codex。### 为什么仍然返回成功-Hook 统计是 CodexBar 的辅助能力, 不是 Codex 完成任务的必要步骤. 如果 recorder 把解析或磁盘错误作为非零退出码返回, 一次统计故障就可能让用户的 Codex 流程失败+Hook 统计是 CodexBar 的辅助能力,不是 Codex 完成任务的必要步骤。如果 recorder 把解析或磁盘错误作为非零退出码返回,一次统计故障就可能让用户的 Codex 流程失败。-因此显式进入 `--hook-event` 后, 无论输入是否有效都返回已处理并退出成功. 失败只意味着少一条统计, 不升级为上游任务故障+因此显式进入 `--hook-event` 后,无论输入是否有效都返回已处理并退出成功。失败只意味着少一条统计,不升级为上游任务故障。### 锁内事务为什么同时写事件和维护状态-一次采集在同一把 `stats.lock` 内完成+一次采集在同一把 `stats.lock` 内完成:```text检查当前文件身份@@ -192,27 +192,27 @@ Hook 统计是 CodexBar 的辅助能力, 不是 Codex 完成任务的必要步-> 原子保存 maintenance.json```-如果 append 和 pending 分成两个锁事务, App 可能在中间完成一次维护并认为当天已经追平. 随后 recorder 只写事件却来不及标记 pending, 新行会静默等待到下一次全目录对账+如果 append 和 pending 分成两个锁事务,App 可能在中间完成一次维护并认为当天已经追平。随后 recorder 只写事件却来不及标记 pending,新行会静默等待到下一次全目录对账。-锁内联合提交让"文件已经增长"和"维护知道需要读取"保持一致+锁内联合提交让“文件已经增长”和“维护知道需要读取”保持一致。### 为什么锁等待只使用超时预算的一部分-Codex 对 `SessionEnd` 最多等待 3 秒, 其他事件最多 5 秒. recorder 把锁等待限制为总预算减 2 秒+Codex 对 `SessionEnd` 最多等待 3 秒,其他事件最多 5 秒。recorder 把锁等待限制为总预算减 2 秒。-预留时间用于编码, append, 保存维护状态和进程退出. 如果把全部预算花在等锁上, Codex 可能正好在写入中途终止进程, 留下半行或未配对的维护状态+预留时间用于编码、append、保存维护状态和进程退出。如果把全部预算花在等锁上,Codex 可能正好在写入中途终止进程,留下半行或未配对的维护状态。-等待从 1 ms 指数退避到最多 20 ms. 主 App 的正常持锁区很短, 小步起始能在锁刚释放时迅速继续, 上限则避免高竞争时 busy loop+等待从 1 ms 指数退避到最多 20 ms。主 App 的正常持锁区很短,小步起始能在锁刚释放时迅速继续,上限则避免高竞争时 busy loop。### 锁文件为什么用一次 `open(O_CREAT)` 创建并打开-不能先判断文件不存在, 创建后再打开. 两个进程可能分别创建不同 inode, 后创建的一方替换目录项后, 双方会各自锁住不同文件并都认为自己独占+不能先判断文件不存在,创建后再打开。两个进程可能分别创建不同 inode,后创建的一方替换目录项后,双方会各自锁住不同文件并都认为自己独占。-单次 `open` 让创建和打开成为同一个原子入口, 所有参与者对同一路径上的同一 inode 使用 `flock`+单次 `open` 让创建和打开成为同一个原子入口,所有参与者对同一路径上的同一 inode 使用 `flock`## 采集字段-原始记录只保留计算统计和实时状态所需的信息+原始记录只保留计算统计和实时状态所需的信息:- 时间戳和事件名- 工作目录@@ -222,9 +222,9 @@ Codex 对 `SessionEnd` 最多等待 3 秒, 其他事件最多 5 秒. recorder- 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 等结构字段@@ -232,31 +232,31 @@ Codex 对 `SessionEnd` 最多等待 3 秒, 其他事件最多 5 秒. recorder### 输入归一化-Hook payload 在不同版本中可能把标识或时间表示为不同 JSON 类型. `WorkflowHookPayload` 集中做宽松归一化+Hook payload 在不同版本中可能把标识或时间表示为不同 JSON 类型。`WorkflowHookPayload` 集中做宽松归一化:-- string 会去掉首尾空白, 空串转为缺失+- string 会去掉首尾空白,空串转为缺失- number 标识转换为字符串-- 时间同时接受 ISO-8601, 本地 timestamp, Unix 秒和 Unix 毫秒+- 时间同时接受 ISO-8601、本地 timestamp、Unix 秒和 Unix 毫秒- 缺失时间回退到 recorder 当前时间- 缺失 cwd 回退到子进程当前目录-宽松只发生在外部输入边界. 一旦转成 `WorkflowHookEvent`, 下游使用统一类型, 不在聚合器和 monitor 中重复猜测协议差异+宽松只发生在外部输入边界。一旦转成 `WorkflowHookEvent`,下游使用统一类型,不在聚合器和 monitor 中重复猜测协议差异。### rollout 尾部回查的边界-回查只读取 transcript 最后 512 KB, 丢弃可能被截断的第一行, 再从后向前寻找匹配 turn 的 `turn_context`+回查只读取 transcript 最后 512 KB、丢弃可能被截断的第一行,再从后向前寻找匹配 turn 的 `turn_context`-从后向前是因为同一个 turn 的最新上下文更接近文件尾. 限制读取范围是为了守住 Hook 超时, 找不到时保留字段缺失而不是扩大成无界扫描+从后向前是因为同一个 turn 的最新上下文更接近文件尾。限制读取范围是为了守住 Hook 超时,找不到时保留字段缺失而不是扩大成无界扫描。## 本地文件-默认数据根目录是+默认数据根目录是:```text~/Library/Application Support/CodexBar/HookEvents/```-目录结构如下+目录结构如下:```textHookEvents/@@ -279,82 +279,82 @@ HookEvents/| `stats.lock` | 协调 Hook 子进程和 App 维护任务 || `Sync/*` | CloudKit 同步游标和缓存 |-原始事件和日聚合最长保留 210 天. session ID 和 turn ID 的明细列表只保留 3 天, 更早日期压缩为计数, 降低本地文件体积和身份信息留存+原始事件和日聚合最长保留 210 天。session ID 和 turn ID 的明细列表只保留 3 天,更早日期压缩为计数,降低本地文件体积和身份信息留存。### 为什么选择 JSONL-JSONL 与这一链路的写入模式匹配+JSONL 与这一链路的写入模式匹配:- recorder 只需要在文件尾追加一条完整记录-- 单行损坏可以被隔离, 不必让整个文件解码失败+- 单行损坏可以被隔离,不必让整个文件解码失败- 文件可以按日切分和保留期清理- 人工排查时仍可检查单条结构- 聚合缓存和远端缓存也能使用相同的逐行恢复策略-普通 JSON 数组每次 append 都要改写尾部结构. 数据库会增加 schema, 锁和部署复杂度, 但当前查询只按日期顺序扫描, 没有足够收益+普通 JSON 数组每次 append 都要改写尾部结构。数据库会增加 schema、锁和部署复杂度,但当前查询只按日期顺序扫描,没有足够收益。### 完整行是提交单位-reader 只推进到最后一个 newline 对应的 offset. 文件尾如果正在写入半行, 本轮保留旧 offset, 下一轮等完整行出现后再处理+reader 只推进到最后一个 newline 对应的 offset。文件尾如果正在写入半行,本轮保留旧 offset,下一轮等完整行出现后再处理。-`JSONLines.decodeWithFailures` 按行解码. 一条坏行只增加 corrupt count, 不会连带丢掉同一读取块中的其他正确事件+`JSONLines.decodeWithFailures` 按行解码。一条坏行只增加 corrupt count,不会连带丢掉同一读取块中的其他正确事件。### 为什么身份明细只保留 3 天-session 和 turn ID 用于近期精确去重, 但长期展示只需要计数+session 和 turn ID 用于近期精确去重,但长期展示只需要计数。-3 天后把 identifiers 压缩为 count, 可以同时降低文件体积和身份信息保留. 聚合模型必须记录该字段当前是 retained 还是 compacted, 否则无法判断后续新事件能否继续用 ID 精确去重+3 天后把 identifiers 压缩为 count,可以同时降低文件体积和身份信息保留。聚合模型必须记录该字段当前是 retained 还是 compacted,否则无法判断后续新事件能否继续用 ID 精确去重。-原始事件仍在 210 天保留期内, 所以算法升级时可以完整重建. CloudKit 从不上传这些原始身份+原始事件仍在 210 天保留期内,所以算法升级时可以完整重建。CloudKit 从不上传这些原始身份。## 增量读取与来源代际-聚合器记录每个原始文件的 inode, size, offset 和 source generation+聚合器记录每个原始文件的 inode, size, offset 和 source generation:- 正常追加时从上次 offset 继续读取- inode 改变表示文件被替换- size 小于 offset 表示文件被截断- 替换或截断会创建新的 source generation-source generation 让同一天的不同原始来源可被区分. 同源结果按替换处理, 明确独立的 generation 可以累加, 用户完整重建则通过同步层的 replacement 标记声明旧 generation 全部失效+source generation 让同一天的不同原始来源可被区分。同源结果按替换处理,明确独立的 generation 可以累加,用户完整重建则通过同步层的 replacement 标记声明旧 generation 全部失效。### `pending` 和 `dirty` 的区别-`maintenance.json` 对每个日期维护两类待办+`maintenance.json` 对每个日期维护两类待办:| 状态 | 何时使用 | 下一步 || --- | --- | --- || `pending` | 已确认是同一来源上的正常追加 | 从旧 offset 增量聚合 |-| `dirty` | 来源变化, schema 变化, 缓存缺失或上次处理失败 | 从文件起点完整重建 |+| `dirty` | 来源变化、schema 变化、缓存缺失或上次处理失败 | 从文件起点完整重建 |-`dirty` 优先于 `pending`. 同一天同时出现在两个集合时只生成重建任务, 避免先追加到旧聚合再完整覆盖+`dirty` 优先于 `pending`。同一天同时出现在两个集合时只生成重建任务,避免先追加到旧聚合再完整覆盖。-这种显式状态比通过 `offset == 0` 猜测任务类型更安全. 全新空文件, 被截断文件和主动重建都可能具有 offset 0, 但它们的 source generation 和同步语义不同+这种显式状态比通过 `offset == 0` 猜测任务类型更安全。全新空文件、被截断文件和主动重建都可能具有 offset 0,但它们的 source generation 和同步语义不同。### 如何判断文件还是同一来源-维护层综合 4 类证据+维护层综合 4 类证据:- inode 标识是否变化- 当前 size 是否小于已处理 offset- 当前 size 是否与维护记录的上次 size 一致- offset 前 4 KB 的 boundary hash 是否仍匹配-inode 与 size 能发现替换和截断, boundary hash 能发现保持相同长度的原地改写+inode 与 size 能发现替换和截断,boundary hash 能发现保持相同长度的原地改写。### boundary hash 为什么还配合 mtime-每轮都给 210 天内所有文件重算 hash 会长时间持有 `stats.lock`, 直接增加 Hook recorder 的等待概率+每轮都给 210 天内所有文件重算 hash 会长时间持有 `stats.lock`,直接增加 Hook recorder 的等待概率。-维护状态记录上次验证 boundary 时的 nanosecond mtime. inode, size 和 mtime 都没变化时直接跳过 hash. 文件变化后才重算 offset 前 4 KB+维护状态记录上次验证 boundary 时的 nanosecond mtime。inode, size 和 mtime 都没变化时直接跳过 hash。文件变化后才重算 offset 前 4 KB。-正常 append 只修改 offset 之后的字节, 所以 boundary 仍匹配, maintenance 可以继续增量处理. boundary 改变则创建新 generation 并标脏+正常 append 只修改 offset 之后的字节,所以 boundary 仍匹配,maintenance 可以继续增量处理。boundary 改变则创建新 generation 并标脏。### build 和 commit 为什么分开-聚合器不能在读取整天文件时一直持有 `stats.lock`, 否则 Hook 子进程可能连续超时+聚合器不能在读取整天文件时一直持有 `stats.lock`,否则 Hook 子进程可能连续超时。-实际流程是+实际流程是:```text锁内 prepare@@ -370,13 +370,13 @@ inode 与 size 能发现替换和截断, boundary hash 能发现保持相同长锁内再次 validate 并推进 maintenance offset```-读取期间允许 recorder 继续 append. 只要候选上界之前的字节没变, 本次结果仍然有效, 新增尾部会保留为下一轮 pending+读取期间允许 recorder 继续 append。只要候选上界之前的字节没变,本次结果仍然有效,新增尾部会保留为下一轮 pending。-如果来源在 build 期间被替换, 候选结果不会提交, maintenance 会开始新 generation 并等待重建+如果来源在 build 期间被替换,候选结果不会提交,maintenance 会开始新 generation 并等待重建。## 聚合规则-日级结果包括+日级结果包括:- Hook 事件总数和各事件计数- session 数和 turn 数@@ -386,48 +386,48 @@ inode 与 size 能发现替换和截断, boundary hash 能发现保持相同长- project 分布- model 分布-成对事件可能只有一侧成功落盘. 因此计数使用能够避免重复且允许缺失的规则+成对事件可能只有一侧成功落盘。因此计数使用能够避免重复且允许缺失的规则:- tool call 使用 `max(PreToolUse, PostToolUse)`- compaction 使用 `max(PreCompact, PostCompact)`- subagent 使用 `max(SubagentStart, SubagentStop)`-字段缺失与数值 `0` 的含义不同+字段缺失与数值 `0` 的含义不同:- 缺失表示该日期的历史来源无法提供该指标- `0` 表示来源可用且明确没有发生-解码和 UI 展示必须保留这个区别+解码和 UI 展示必须保留这个区别。### 为什么成对事件使用 `max`-`PreToolUse` 和 `PostToolUse` 描述同一次工具调用的两侧. recorder 允许失败后, 任意一侧都可能缺失+`PreToolUse` 和 `PostToolUse` 描述同一次工具调用的两侧。recorder 允许失败后,任意一侧都可能缺失:- 相加会把完整的一次调用统计为 2 次- 只看 pre 会漏掉 pre 写入失败而 post 成功的调用- 只看 post 会漏掉工具开始后进程中断的调用- `max(pre, post)` 在没有稳定 call ID 时给出最不容易重复的估计-compaction 和 subagent 成对事件使用相同规则+compaction 和 subagent 成对事件使用相同规则。-如果未来 Hook 协议提供稳定 operation ID, 去重算法可以升级为集合去重, 但这属于聚合语义变化, 必须递增 schema 并完整重建+如果未来 Hook 协议提供稳定 operation ID,去重算法可以升级为集合去重,但这属于聚合语义变化,必须递增 schema 并完整重建。### 可用性如何穿过旧数据-旧版本聚合可能没有某类 Hook count. 重建时不能因为当前代码认识该事件, 就假定旧来源也采集过+旧版本聚合可能没有某类 Hook count。重建时不能因为当前代码认识该事件,就假定旧来源也采集过。-`WorkflowHookCountAvailability` 保存每类计数是否有来源. 重建会继承现有日期对旧字段的可用性, 新鲜来源则可以声明当前字段全部可用+`WorkflowHookCountAvailability` 保存每类计数是否有来源。重建会继承现有日期对旧字段的可用性,新鲜来源则可以声明当前字段全部可用。-这使 UI 能区分+这使 UI 能区分:- 明确发生 0 次- 当前日期的历史采集没有这个指标## Schema 演进与重建-当前聚合 schema 为 `5`, 由 `WorkflowMaintenanceState.currentAggregationSchema` 管理+当前聚合 schema 为 `5`,由 `WorkflowMaintenanceState.currentAggregationSchema` 管理。-以下变化必须递增 schema+以下变化必须递增 schema:- 原始事件到聚合结果的算法变化- 输出字段增删@@ -435,90 +435,90 @@ compaction 和 subagent 成对事件使用相同规则- 去重规则变化- 来源代际合并语义变化-升级后统一从 210 天保留期内的原始 JSONL 完整重建, 不做字段级历史迁移. 这种策略让聚合缓存始终能够由同一套当前算法生成+升级后统一从 210 天保留期内的原始 JSONL 完整重建,不做字段级历史迁移。这种策略让聚合缓存始终能够由同一套当前算法生成。-用户手动重建时也走同一条完整重算路径, 并向同步层标记需要替换的日期+用户手动重建时也走同一条完整重算路径,并向同步层标记需要替换的日期。### aggregation schema 与 source generation 不同| 标识 | 描述 | 何时变化 || --- | --- | --- |-| aggregation schema | 当前代码如何从原始事件计算聚合 | 算法, 字段或语义变化 |-| source generation | 某一天的原始文件属于哪一代来源 | 替换, 截断, 主动重建或边界改写 |+| aggregation schema | 当前代码如何从原始事件计算聚合 | 算法、字段或语义变化 |+| source generation | 某一天的原始文件属于哪一代来源 | 替换、截断、主动重建或边界改写 |-schema 变化通常把保留期内所有事件日期标脏. source generation 变化只影响具体日期+schema 变化通常把保留期内所有事件日期标脏。source generation 变化只影响具体日期。-两者都不能用 App 版本号替代. 一个 App 版本可能不改变聚合, 开发构建也可能在不变更版本号时多次迭代 schema+两者都不能用 App 版本号替代。一个 App 版本可能不改变聚合,开发构建也可能在不变更版本号时多次迭代 schema。### 为什么不做字段级迁移-`daily.jsonl` 本来就是派生缓存, 原始 JSONL 又在保留期内. 为每个旧字段编写迁移会同时维护旧算法和新算法, 更容易产生混合语义+`daily.jsonl` 本来就是派生缓存,原始 JSONL 又在保留期内。为每个旧字段编写迁移会同时维护旧算法和新算法,更容易产生混合语义。-完整重建的一次性成本可控, 换来以下保证+完整重建的一次性成本可控,换来以下保证:- 同一 schema 下所有日期由同一套代码生成- 删除或改变字段语义时没有残留值- 损坏的聚合行也能一起修复- CloudKit replacement 可以统一跟随 source generation-只有原始来源本身缺少字段时, 才通过 missing 保留历史能力差异+只有原始来源本身缺少字段时,才通过 missing 保留历史能力差异。### 用户手动重建的提交语义-批量重建按日期独立处理. 单日失败不会阻断已经成功的日期, 失败日期会标脏交给常规维护继续尝试+批量重建按日期独立处理。单日失败不会阻断已经成功的日期,失败日期会标脏交给常规维护继续尝试。-成功和失败日期都会先登记 CloudKit replacement. 原因是失败日期已经进入新 generation, 后续自动重建成功时会使用新 record identity. 如果没有提前标记, 旧 generation 可能留在云端与新值叠加+成功和失败日期都会先登记 CloudKit replacement。原因是失败日期已经进入新 generation,后续自动重建成功时会使用新 record identity。如果没有提前标记,旧 generation 可能留在云端与新值叠加。-只有所有日期都失败时, 操作整体返回失败. 部分成功会返回详细 summary, 包括成功日期, 损坏行和 replacement pending 状态+只有所有日期都失败时,操作整体返回失败。部分成功会返回详细 summary,包括成功日期、损坏行和 replacement pending 状态。## 维护调度-[`WorkflowService.swift`](../../CodexBar/Services/Workflow/WorkflowService.swift) 是 actor, 串行执行读取, 聚合, 清理和重建+[`WorkflowService.swift`](../../CodexBar/Services/Workflow/WorkflowService.swift) 是 actor,串行执行读取、聚合、清理和重建。-维护任务与额度刷新周期协调, 但两条数据链路没有数据依赖. Workflow ViewModel 对 UI 的最短刷新间隔为 5 秒, 避免频繁文件变更造成重复渲染+维护任务与额度刷新周期协调,但两条数据链路没有数据依赖。Workflow ViewModel 对 UI 的最短刷新间隔为 5 秒,避免频繁文件变更造成重复渲染。### 为什么空转维护不写普通日志-维护默认跟随 60 秒刷新. 空闲机器一天会执行上千次没有变化的检查+维护默认跟随 60 秒刷新。空闲机器一天会执行上千次没有变化的检查。-`WorkflowService` 累计连续 idle 轮数, 只有真正写入, 跳过, 失败或清理时才输出一条摘要, 并附带之前空转次数. 这样日志既能证明维护一直在运行, 又不会淹没真正故障+`WorkflowService` 累计连续 idle 轮数,只有真正写入、跳过、失败或清理时才输出一条摘要,并附带之前空转次数。这样日志既能证明维护一直在运行,又不会淹没真正故障。### scheduler 如何合并请求-`WorkflowSyncScheduler` 串行处理 3 类请求+`WorkflowSyncScheduler` 串行处理 3 类请求:-1. 用户重建, 优先级最高+1. 用户重建,优先级最高2. 带同步的维护3. 仅本地维护-同步完成后有 8 秒冷却. 冷却期间的多个请求合并成一次, 并保留最先到达的 trigger 作为真正起因+同步完成后有 8 秒冷却。冷却期间的多个请求合并成一次,并保留最先到达的 trigger 作为真正起因。-UI 打开只读取当前本地快照, 不自动越过 scheduler 发起无条件 CloudKit 请求+UI 打开只读取当前本地快照,不自动越过 scheduler 发起无条件 CloudKit 请求。## 新增 Hook 事件或指标的步骤-1. 在 `CodexHookEvent` 登记协议名, 配置名和 handler timeout+1. 在 `CodexHookEvent` 登记协议名、配置名和 handler timeout2. 确认 recorder 只持久化计算所需的最小字段3. 更新 Hook 安装完整性校验4. 在 accumulator 中定义计数和去重语义-5. 更新 aggregate 的 Codable 与 JSONL 编码, 保留旧字段 missing 语义+5. 更新 aggregate 的 Codable 与 JSONL 编码,保留旧字段 missing 语义6. 递增 `WorkflowMaintenanceState.currentAggregationSchema`-7. 更新 CloudKit record schema, 上传和下载映射+7. 更新 CloudKit record schema、上传和下载映射8. 确认旧 App 与新 record 共存策略后再修改兼容格式9. 补充 UI 展示和隐私边界-10. 手动验证正常 append, 单侧事件缺失, 文件替换和完整重建+10. 手动验证正常 append、单侧事件缺失、文件替换和完整重建## 建议验证的故障场景- 多个 Codex session 并发写入时每行完整且无覆盖- 主 App 持锁时 Hook recorder 能在预算内成功或安全放弃- stdin 非 JSON 或缺少 event name 时子进程仍立即成功退出-- 文件尾半行不会推进 offset, 补全后下一轮能读取+- 文件尾半行不会推进 offset,补全后下一轮能读取- 单条损坏 JSONL 只增加 corrupt count-- inode 变化, 文件缩小和 boundary 改写都触发新 generation-- build 期间继续 append 时只提交固定上界, 尾部保留 pending+- inode 变化、文件缩小和 boundary 改写都触发新 generation+- build 期间继续 append 时只提交固定上界,尾部保留 pending- schema 变化后保留期内日期全部用当前算法重建-- 旧日期缺失字段仍显示 unavailable, 不变成 `0`+- 旧日期缺失字段仍显示 unavailable,不变成 `0`- 禁用 CodexBar Hook 不删除用户 handler 和信任项- 快速开关 Hook 时旧 RPC 结果不能覆盖最后一次操作@@ -528,7 +528,7 @@ UI 打开只读取当前本地快照, 不自动越过 scheduler 发起无条件- 文件来源改变后不能继续使用旧 offset- 重建失败时保留最后一份可用聚合- 维护中断不能把部分结果当作完整日期提交-- Hook 不可用时 UI 应表达来源不可用, 而不是清空为 `0`+- Hook 不可用时 UI 应表达来源不可用,而不是清空为 `0`- 配置写入失败不能破坏原有 handler## 关键源码diff --git a/Docs/DeveloperGuide/notifications.md b/Docs/DeveloperGuide/notifications.mdindex 49feccb..fff1f39 100644--- a/Docs/DeveloperGuide/notifications.md+++ b/Docs/DeveloperGuide/notifications.md@@ -2,18 +2,18 @@## 职责-[`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 个条件+通知不是状态本身,而是状态变化触发的一次外部副作用。一条可靠通知至少要同时满足 4 个条件:```text事件真实发生@@ -22,16 +22,16 @@ View 和其他服务不直接创建系统通知. 它们发布状态变化, 通+ 本生命周期或持久化周期尚未发送```-把这些条件集中到一个服务有两个目的+把这些条件集中到一个服务有两个目的:-- 上游只发布事实和转场, 不需要知道系统授权, 声音或去重存储-- 所有提交都经过同一套 relevance 检查, retry 和隐私日志规则+- 上游只发布事实和转场,不需要知道系统授权、声音或去重存储+- 所有提交都经过同一套 relevance 检查、retry 和隐私日志规则-如果 View 直接发通知, SwiftUI 重建, 面板重复打开或快照重新发布都可能重复触发. 因此 View 只能修改设置或展示状态, 不能拥有通知副作用+如果 View 直接发通知,SwiftUI 重建、面板重复打开或快照重新发布都可能重复触发。因此 View 只能修改设置或展示状态,不能拥有通知副作用。## 快照与转场不能混用-不同通知需要不同类型的证据+不同通知需要不同类型的证据:| 通知 | 输入类型 | 原因 || --- | --- | --- |@@ -39,15 +39,15 @@ View 和其他服务不直接创建系统通知. 它们发布状态变化, 通| 额度重置 | 连续可信快照 | 需要先观察消费再观察归零 || Reset Credits 到期 | 当前快照加时间调度 | 到期提醒由未来 deadline 触发 || 任务完成 | monitor 转场 | 历史 terminal 快照不能补发 |-| 等待批准 | monitor 转场加当前快照 | 先通知新等待, 再撤回过时等待 |+| 等待批准 | monitor 转场加当前快照 | 先通知新等待,再撤回过时等待 || 异常会话保护 | 已提交保护结果 | 必须描述已经隐藏的任务 || 防睡眠停止 | 已确认系统恢复结果 | 不能在恢复请求前预告成功 |-从当前快照推导任务完成看起来更简单, 但 App 每次启动都会把历史完成任务当作新事件. 相反, 对低额度只看单次转场又无法识别 App 在阈值穿越后才启动的场景+从当前快照推导任务完成看起来更简单,但 App 每次启动都会把历史完成任务当作新事件。相反,对低额度只看单次转场又无法识别 App 在阈值穿越后才启动的场景。## 设置和系统授权是两层门槛-`NotificationSettings` 分开保存 App 内意图与 macOS 授权+`NotificationSettings` 分开保存 App 内意图与 macOS 授权:| 状态 | 含义 || --- | --- |@@ -55,17 +55,17 @@ View 和其他服务不直接创建系统通知. 它们发布状态变化, 通| `authorizationStatus` | 系统是否允许通知 || `canDeliver` | 两者同时允许后的实际资格 |-总开关默认关闭, 因此 App 首次运行不会无缘由弹出系统权限请求. 用户主动开启后才调用 authorization API+总开关默认关闭,因此 App 首次运行不会无缘由弹出系统权限请求。用户主动开启后才调用 authorization API。-App 激活时会重新读取系统状态, 因为用户可能在 System Settings 中改过权限. 如果 App 开关已开但系统仍为 `notDetermined`, 会补发一次请求, 覆盖用户在首次弹窗完成前退出的情况+App 激活时会重新读取系统状态,因为用户可能在 System Settings 中改过权限。如果 App 开关已开但系统仍为 `notDetermined`,会补发一次请求,覆盖用户在首次弹窗完成前退出的情况。-触觉反馈不依赖 `UNUserNotificationCenter` 授权, 但仍服从 App 内总开关. 这是能力边界的区别, 不是绕过用户意图+触觉反馈不依赖 `UNUserNotificationCenter` 授权,但仍服从 App 内总开关。这是能力边界的区别,不是绕过用户意图。## 通知开关-通知总开关默认关闭. 7 个可配置分类的子开关默认开启, 触觉反馈默认关闭+通知总开关默认关闭。7 个可配置分类的子开关默认开启,触觉反馈默认关闭。-总开关关闭时不会申请系统通知权限, 也不会发送任何分类通知. 子开关用于在总开关开启后选择具体类型+总开关关闭时不会申请系统通知权限,也不会发送任何分类通知。子开关用于在总开关开启后选择具体类型:| 分类 | 数据来源 | 控制条件 || --- | --- | --- |@@ -75,133 +75,133 @@ App 激活时会重新读取系统状态, 因为用户可能在 System Settings| 任务完成 | 实时任务 terminal 转场 | 独立子开关和最短时长 || 等待批准 | 实时任务 waiting 转场 | 独立子开关 || 异常会话保护 | Activity Protection | 防睡眠主开关和通知总开关 |-| 低电量保护停止 | KeepAlive 恢复结果 | 独立子开关, 仅在保护可用时启用 |-| 防睡眠达到上限 | KeepAlive 恢复结果 | 独立子开关, 仅在有限时长时启用 |+| 低电量保护停止 | KeepAlive 恢复结果 | 独立子开关,仅在保护可用时启用 |+| 防睡眠达到上限 | KeepAlive 恢复结果 | 独立子开关,仅在有限时长时启用 |-异常会话保护没有独立通知子开关. 它本身跟随防睡眠主开关, 保护动作发生后再服从通知总开关. 低电量和时长上限的通知偏好会保留, 但对应保护条件不可用时 UI 显示为关闭并置灰, 不修改持久化偏好+异常会话保护没有独立通知子开关。它本身跟随防睡眠主开关,保护动作发生后再服从通知总开关。低电量和时长上限的通知偏好会保留,但对应保护条件不可用时 UI 显示为关闭并置灰,不修改持久化偏好。## 额度重置-额度重置通知需要先观察到窗口被消费, 再观察到新窗口恢复为未消费状态+额度重置通知需要先观察到窗口被消费,再观察到新窗口恢复为未消费状态。-这避免 App 第一次启动时仅因为当前额度是 100% 就发送重置通知+这避免 App 第一次启动时仅因为当前额度是 100% 就发送重置通知。-判断状态按账户和额度窗口隔离. 账户变化时不把前一账户的消费状态延续到新账户+判断状态按账户和额度窗口隔离。账户变化时不把前一账户的消费状态延续到新账户。-每个额度窗口还带一个会话内 lifecycle token. 窗口从可信快照消失后再出现会得到新 token. 如果旧窗口的通知提交失败回调迟到, 只有 token 仍相同时才把 `hasObservedConsumption` 恢复为 true+每个额度窗口还带一个会话内 lifecycle token。窗口从可信快照消失后再出现会得到新 token。如果旧窗口的通知提交失败回调迟到,只有 token 仍相同时才把 `hasObservedConsumption` 恢复为 true。-这避免一个竞态: 旧窗口通知正在提交时 app-server 切换账户或窗口, 随后失败回调把新窗口错误标成"已经消费过"+这避免一个竞态:旧窗口通知正在提交时 app-server 切换账户或窗口,随后失败回调把新窗口错误标成“已经消费过”。-重置状态不持久化. App 启动时必须重新观察到消费后才通知重置, 这是主动接受漏掉离线期间重置, 以换取绝不在启动时对 0% 用量误报+重置状态不持久化。App 启动时必须重新观察到消费后才通知重置,这是主动接受漏掉离线期间重置,以换取绝不在启动时对 0% 用量误报。## 低额度-低额度阈值可选 5%, 10% 或 25%, 默认 10%+低额度阈值可选 5%, 10% 或 25%,默认 10%。-通知只在剩余额度从阈值上方跨到阈值或下方时发送. 持续停留在低额度区域不会每次刷新都重复通知+通知只在剩余额度从阈值上方跨到阈值或下方时发送。持续停留在低额度区域不会每次刷新都重复通知。-首次可信快照已经低于阈值时也视为一次向下穿越, 用于覆盖 App 在穿越后才启动的情况+首次可信快照已经低于阈值时也视为一次向下穿越,用于覆盖 App 在穿越后才启动的情况。-持久化去重 key 保留 app-server 返回的秒级重置时间. 相同账户和额度窗口的重置时间与已记录值相差不超过 60 秒时视为同一周期, 只有差值超过 60 秒才视为新的重置周期+持久化去重 key 保留 app-server 返回的秒级重置时间。相同账户和额度窗口的重置时间与已记录值相差不超过 60 秒时视为同一周期,只有差值超过 60 秒才视为新的重置周期。-额度恢复到阈值上方后会重新启用穿越判定, 但同一重置周期仍只通知一次. 进入新的重置周期后, 下一次向下跨越可以再次通知+额度恢复到阈值上方后会重新启用穿越判定,但同一重置周期仍只通知一次。进入新的重置周期后,下一次向下跨越可以再次通知。### 为什么使用剩余比例的向下穿越-"当前低于 10%"是一个持续状态, "刚刚低于 10%"才是通知事件. 服务为每个 `account + limit + window` 保存上一帧剩余比例+“当前低于 10%”是一个持续状态,“刚刚低于 10%”才是通知事件。服务为每个 `account + limit + window` 保存上一帧剩余比例:- 上一帧高于阈值且当前不高于阈值时发送- 会话内第一帧已经不高于阈值时发送一次- 一直停留在低区间时不发送- 阈值设置变化时清除当前观察并立即按新阈值重判-设置订阅使用回调给出的新值. Combine 的 `@Published` 在 `willSet` 阶段发送, 此时重新读取 settings 属性仍会得到旧值. 这项实现细节是为了保证用户把阈值从 5% 改到 25% 时立即按 25% 判断+设置订阅使用回调给出的新值。Combine 的 `@Published` 在 `willSet` 阶段发送,此时重新读取 settings 属性仍会得到旧值。这项实现细节是为了保证用户把阈值从 5% 改到 25% 时立即按 25% 判断。-stale app-server 快照不会推进上一帧, 也不会触发低额度或重置. 旧缓存只能用于展示连续性, 不能成为一次新副作用的证据+stale app-server 快照不会推进上一帧,也不会触发低额度或重置。旧缓存只能用于展示连续性,不能成为一次新副作用的证据。### 重置时间为何允许 60 秒漂移-app-server 连接重建后, 同一窗口的 `resetsAt` 可能出现秒级修正. 如果 dedup key 使用绝对相等, 同一周期会被当成新周期再次通知+app-server 连接重建后,同一窗口的 `resetsAt` 可能出现秒级修正。如果 dedup key 使用绝对相等,同一周期会被当成新周期再次通知。-服务在相同账户, limit 和 window 范围内寻找 60 秒容差内的已发送或正在提交 key, 并复用原 key. 容差只用于身份归一化, UI 仍展示服务返回的实际时间+服务在相同账户、limit 和 window 范围内寻找 60 秒容差内的已发送或正在提交 key,并复用原 key。容差只用于身份归一化,UI 仍展示服务返回的实际时间。## Reset Credits 到期-当 Reset Credits 数量大于 `0` 且能够读取到期日时, 通知服务在到期前 7 天到 1 天按天提醒+当 Reset Credits 数量大于 `0` 且能够读取到期日时,通知服务在到期前 7 天到 1 天按天提醒。-去重 key 包含账户, 到期日和剩余天数. 同一天多次刷新不会重复发送+去重 key 包含账户、到期日和剩余天数。同一天多次刷新不会重复发送。-提醒不是建立 7 个长期系统 pending request. 服务只调度最近一个未来检查点, 到点后根据当前快照重新计算并安排下一次+提醒不是建立 7 个长期系统 pending request。服务只调度最近一个未来检查点,到点后根据当前快照重新计算并安排下一次。-这样做可以处理+这样做可以处理:- Reset Credits 数量或到期时间被 app-server 更新- 通知设置中途关闭- Mac 睡过 deadline 后通过 wake observer 补检- 多个相同到期秒的次数合并成一条通知-日期判断基于距到期的剩余秒数, 7 天到 1 天分别有独立 dedup key. 调度器只负责唤醒检查, 最终资格仍由当前快照决定+日期判断基于距到期的剩余秒数,7 天到 1 天分别有独立 dedup key。调度器只负责唤醒检查,最终资格仍由当前快照决定。## 任务完成-任务通知只响应 monitor 发布的新 terminal 转场, 不扫描历史列表推导+任务通知只响应 monitor 发布的新 terminal 转场,不扫描历史列表推导:- bootstrap 建立的历史任务不发送通知- terminal ID 在活动监控层保留 24 小时去重- 通知服务还维护自己的已发送 key- 同一 turn 的 `Stop` 和 rollout terminal 对账后只发送一次-匿名任务不会发布给任务通知消费者. 通知服务在 transition 入口再次过滤 `isAnonymous`, 因此匿名任务不发送完成或等待批准通知, 也不触发任务触觉反馈+匿名任务不会发布给任务通知消费者。通知服务在 transition 入口再次过滤 `isAnonymous`,因此匿名任务不发送完成或等待批准通知,也不触发任务触觉反馈。-任务完成最短持续时间可选 30, 60, 120 或 300 秒, 默认 60 秒. 持续时间较短的完成任务不会通知, 但仍可以在 UI 中短暂展示+任务完成最短持续时间可选 30, 60, 120 或 300 秒,默认 60 秒。持续时间较短的完成任务不会通知,但仍可以在 UI 中短暂展示。-任务通知入口再次过滤匿名任务, 即使 monitor 已保证不发布匿名转场. 这是副作用边界的纵深保护: 上游未来重构或新增 transition 类型时, 缺少 session ID 的任务仍不会意外产生系统通知或触觉+任务通知入口再次过滤匿名任务,即使 monitor 已保证不发布匿名转场。这是副作用边界的纵深保护:上游未来重构或新增 transition 类型时,缺少 session ID 的任务仍不会意外产生系统通知或触觉。-触觉在每个 task transition 到达时启动, 新 transition 会取消上一串 10 次脉冲并重新开始. 每次脉冲前重新检查设置, 用户关闭开关后不会继续完成旧序列+触觉在每个 task transition 到达时启动,新 transition 会取消上一串 10 次脉冲并重新开始。每次脉冲前重新检查设置,用户关闭开关后不会继续完成旧序列。## 等待批准-只有 `PermissionRequest` 的 reviewer 确认是用户时才发送等待批准通知+只有 `PermissionRequest` 的 reviewer 确认是用户时才发送等待批准通知:- 自动审批不通知- 同一等待项只通知一次- 任务离开等待状态后从相关集合移除- bootstrap 中已存在的等待状态不补发历史通知-等待状态是否维持防睡眠是独立设置, 不影响是否可以发送等待批准通知+等待状态是否维持防睡眠是独立设置,不影响是否可以发送等待批准通知。-等待通知使用稳定 task ID 作为系统通知 identifier. 服务同时观察活动快照+等待通知使用稳定 task ID 作为系统通知 identifier。服务同时观察活动快照:- 提交前任务已经离开 waiting 时跳过- `UNUserNotificationCenter.add` 成功后状态又变化时立即撤回- 后续快照不再包含任务时同时移除 delivered 和 pending notification-- 提交失败时从内存相关集合移除, 允许未来真实的新等待再次尝试+- 提交失败时从内存相关集合移除,允许未来真实的新等待再次尝试-前后两次 relevance 检查覆盖了异步提交窗口. 只在提交前检查仍可能让一个已经获批的任务在通知中心留下过时提醒+前后两次 relevance 检查覆盖了异步提交窗口。只在提交前检查仍可能让一个已经获批的任务在通知中心留下过时提醒。## 异常会话保护-非匿名任务静默达到阈值时, Activity Protection 先保存保护记录并隐藏任务, 然后请求通知. 匿名任务不进入保护候选, 也不会产生保护通知+非匿名任务静默达到阈值时,Activity Protection 先保存保护记录并隐藏任务,然后请求通知。匿名任务不进入保护候选,也不会产生保护通知。-通知服务在提交前再次检查任务是否仍然被保护. 如果 3 秒宽限内出现新进展, 过时通知会被取消+通知服务在提交前再次检查任务是否仍然被保护。如果 3 秒宽限内出现新进展,过时通知会被取消。-保护通知使用固定默认声音, 不复用任务完成分类声音. 通知发送失败不撤销已经完成的保护动作+保护通知使用固定默认声音,不复用任务完成分类声音。通知发送失败不撤销已经完成的保护动作。-异常会话保护使用 `taskID + attemptID` 作为 identifier, relevance 还比较 progress generation 和静默时长. 任务在 3 秒通知宽限内出现进展时, monitor 让保护尝试失效并请求撤回+异常会话保护使用 `taskID + attemptID` 作为 identifier,relevance 还比较 progress generation 和静默时长。任务在 3 秒通知宽限内出现进展时,monitor 让保护尝试失效并请求撤回。-这类通知的 `retryCount` 明确为 0. 保护结果对时间高度敏感, 立即提交失败后再重试可能已经不相关. 一般通知可以重试一次, 保护通知宁可漏发也不迟到误报+这类通知的 `retryCount` 明确为 0。保护结果对时间高度敏感,立即提交失败后再重试可能已经不相关。一般通知可以重试一次,保护通知宁可漏发也不迟到误报。## 防睡眠停止-低电量或最长时长导致防睡眠停止时, `KeepAliveController` 先撤销 CodexBarHelper 租约并等待 `SleepDisabled=0` 的回读确认+低电量或最长时长导致防睡眠停止时,`KeepAliveController` 先撤销 CodexBarHelper 租约并等待 `SleepDisabled=0` 的回读确认。-确认后才提交通知. App idle assertion 会保留到通知提交结束, 避免合盖机器在通知交给系统前立即睡下. 随后 controller 释放 assertion 并按需补发合盖睡眠+确认后才提交通知。App idle assertion 会保留到通知提交结束,避免合盖机器在通知交给系统前立即睡下。随后 controller 释放 assertion 并按需补发合盖睡眠。-这保证通知文字描述的是已经完成的系统级恢复, 同时让异步提交有机会收口+这保证通知文字描述的是已经完成的系统级恢复,同时让异步提交有机会收口。## 声音-[`NotificationSoundOption.swift`](../../CodexBar/Services/Notifications/NotificationSoundOption.swift) 汇总 3 类选择+[`NotificationSoundOption.swift`](../../CodexBar/Services/Notifications/NotificationSoundOption.swift) 汇总 3 类选择:- 无声音- macOS 可用系统声音@@ -209,55 +209,55 @@ app-server 连接重建后, 同一窗口的 `resetsAt` 可能出现秒级修正.内置声音位于 [`NotificationSounds`](../../CodexBar/Resources/NotificationSounds)-已保存的声音名称在新系统或新版 App 中不存在时, 回退到默认声音, 不阻断通知+已保存的声音名称在新系统或新版 App 中不存在时,回退到默认声音,不阻断通知。-不同通知分类可以保存各自的声音设置+不同通知分类可以保存各自的声音设置。-声音选项保存稳定 ID, 而不是绝对文件路径+声音选项保存稳定 ID,而不是绝对文件路径:- 内置声音通过 bundle resource 解析-- 系统声音首次访问时扫描用户, Local 和 System 声音目录-- `/Network/Library/Sounds` 刻意不扫描, 自动挂载点探测可能阻塞 UI+- 系统声音首次访问时扫描用户、Local 和 System 声音目录+- `/Network/Library/Sounds` 刻意不扫描,自动挂载点探测可能阻塞 UI- 同名声音按系统查找顺序选择靠前目录-- 内置 ID 预先保留, 防止本机同名文件在重启后改变已保存选项的含义+- 内置 ID 预先保留,防止本机同名文件在重启后改变已保存选项的含义- 已保存 ID 无法解析时回退 system default-system default 和静音不可试听. 用系统 alert sound 冒充通知中心默认音会给用户错误预期, 因此预览只支持有明确文件的系统音和内置音+system default 和静音不可试听。用系统 alert sound 冒充通知中心默认音会给用户错误预期,因此预览只支持有明确文件的系统音和内置音。## 触觉反馈-触觉反馈默认关闭. 开启后使用 10 次脉冲, 每次间隔约 100 ms+触觉反馈默认关闭。开启后使用 10 次脉冲,每次间隔约 100 ms。-触觉是系统通知之外的独立本地反馈. 它响应非匿名任务的完成或等待 transition, 服从通知总开关和触觉开关, 但不依赖系统通知授权, 分类通知开关或完成时长阈值+触觉是系统通知之外的独立本地反馈。它响应非匿名任务的完成或等待 transition,服从通知总开关和触觉开关,但不依赖系统通知授权、分类通知开关或完成时长阈值。-这种分离让用户可以关闭 banner 仍保留统一的任务触觉. 上游 transition 仍必须真实有效, bootstrap 历史和匿名任务不会触发+这种分离让用户可以关闭 banner 仍保留统一的任务触觉。上游 transition 仍必须真实有效,bootstrap 历史和匿名任务不会触发。## 提交与去重-通知通过 `UNUserNotificationCenter` 提交+通知通过 `UNUserNotificationCenter` 提交:- 单次提交失败最多重试 1 次- 已发送 dedup key 保存到 UserDefaults- 最多保留 300 个 key-- key 必须包含足够的账户或任务范围, 避免不同对象相互压制+- key 必须包含足够的账户或任务范围,避免不同对象相互压制- 过期或不再相关的 waiting key 会被移除-持久化去重避免 App 重启后立即重复发送同一事件, 但不能替代上游任务 terminal 去重+持久化去重避免 App 重启后立即重复发送同一事件,但不能替代上游任务 terminal 去重。### 两层去重解决不同问题-`submittingDedupKeys` 和 `sentDedupKeys` 不能合并+`submittingDedupKeys` 和 `sentDedupKeys` 不能合并:| 集合 | 生命周期 | 防止的问题 || --- | --- | --- || `submittingDedupKeys` | 当前异步提交期间 | 两个同步调用在第一个 `await` 前同时通过检查 |-| `sentDedupKeys` | UserDefaults, 最多 300 条 | App 重启后重复发送同一业务周期 |+| `sentDedupKeys` | UserDefaults,最多 300 条 | App 重启后重复发送同一业务周期 |-dedup 检查和 `submitting` 插入在创建 Task 前同步完成, 因此正确性不依赖 Swift task 调度顺序+dedup 检查和 `submitting` 插入在创建 Task 前同步完成,因此正确性不依赖 Swift task 调度顺序。-只有 `UNUserNotificationCenter.add` 成功且事件在提交后仍相关时才写入 sent key. 如果提前记录, 一次系统提交失败会永久吃掉这条提醒+只有 `UNUserNotificationCenter.add` 成功且事件在提交后仍相关时才写入 sent key。如果提前记录,一次系统提交失败会永久吃掉这条提醒。-300 条上限防止 UserDefaults 变成无界事件日志. 这里接受很久以前的事件在 key 淘汰后理论上可能重现, 因为上游周期身份和实时 transition 去重仍是第一道边界+300 条上限防止 UserDefaults 变成无界事件日志。这里接受很久以前的事件在 key 淘汰后理论上可能重现,因为上游周期身份和实时 transition 去重仍是第一道边界。### 发送入口的统一语义@@ -273,34 +273,34 @@ dedup 检查和 `submitting` 插入在创建 Task 前同步完成, 因此正确-> 失败时最多重试一次并执行分类清理```-日志只记录 `kind` 和失败原因, 不记录 title 或 body. 通知正文可能包含项目名和任务信息, 即使日志位于本机也不应复制这些内容+日志只记录 `kind` 和失败原因,不记录 title 或 body。通知正文可能包含项目名和任务信息,即使日志位于本机也不应复制这些内容。## 前台展示与点击-App 是 `LSUIElement`, 通知中心 delegate 明确允许 App 在前台时继续展示 banner 和声音+App 是 `LSUIElement`,通知中心 delegate 明确允许 App 在前台时继续展示 banner 和声音。-用户点击通知后打开主面板. 打开动作通过状态栏控制器执行, 复用现有 popover 或 fallback panel 逻辑+用户点击通知后打开主面板。打开动作通过状态栏控制器执行,复用现有 popover 或 fallback panel 逻辑。-前台展示由 notification center delegate 显式返回 banner, list 和 sound. `LSUIElement` App 经常保持前台或处于特殊 activation 状态, 依赖系统默认前台策略会让用户感觉通知随机消失+前台展示由 notification center delegate 显式返回 banner, list 和 sound。`LSUIElement` App 经常保持前台或处于特殊 activation 状态,依赖系统默认前台策略会让用户感觉通知随机消失。-点击处理不直接创建新窗口, 而是调用 `openMenuSurface`. 这保证锚点有效时复用 popover, 锚点无效时使用 fallback panel, 并继续遵守同一套焦点和 dismiss 规则+点击处理不直接创建新窗口,而是调用 `openMenuSurface`。这保证锚点有效时复用 popover,锚点无效时使用 fallback panel,并继续遵守同一套焦点和 dismiss 规则。## 新增通知类型的实现清单-1. 明确输入是快照, 转场还是已确认副作用结果-2. 定义账户, 窗口, task 或 attempt 作用域的身份-3. 决定是否需要会话去重, 持久化去重和 relevance 检查-4. 明确 bootstrap, stale 数据和匿名任务是否允许触发+1. 明确输入是快照、转场还是已确认副作用结果+2. 定义账户、窗口、task 或 attempt 作用域的身份+3. 决定是否需要会话去重、持久化去重和 relevance 检查+4. 明确 bootstrap、stale 数据和匿名任务是否允许触发5. 选择声音和失败重试语义6. 确认正文中的敏感字段不会进入日志7. 为设置默认值和旧 UserDefaults 缺失值定义行为-8. 验证前台展示, 点击激活和事件失效后的撤回+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.mdindex bbbe6b0..e48c3dd 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 只执行受限的系统睡眠操作:```textCodexActivityMonitor@@ -21,9 +21,9 @@ CodexActivityMonitor## 为什么这不是一个 assertion 开关-防睡眠表面上像一个布尔设置, 实际上同时跨越用户意图, 实时任务, 电源状态, App 生命周期和 root 系统状态. 任何一层都可能先于其他层变化, 因此实现不能把 `isEnabled` 直接等同于系统已经禁止睡眠+防睡眠表面上像一个布尔设置,实际上同时跨越用户意图、实时任务、电源状态、App 生命周期和 root 系统状态。任何一层都可能先于其他层变化,因此实现不能把 `isEnabled` 直接等同于系统已经禁止睡眠。-系统把状态拆成 4 层+系统把状态拆成 4 层:| 层级 | 代表字段 | 回答的问题 || --- | --- | --- |@@ -32,29 +32,29 @@ CodexActivityMonitor| 请求状态 | `appliedSleepPreventionRequested` 和 `requestInFlight` | App 最近向 helper 请求了什么 || 已确认效果 | `isPreventingSleep` 和 `sleepPreventionSource` | App 是否收到系统状态已经符合预期的证据 |-这种区分解决了两个容易被 UI 掩盖的问题+这种区分解决了两个容易被 UI 掩盖的问题:-- helper 暂时不可用时保留用户开关, 修复依赖后可以自动恢复, 不需要用户重新开启-- XPC 请求发出但尚未确认时不提前显示成功, 避免界面和系统实际状态相反+- helper 暂时不可用时保留用户开关,修复依赖后可以自动恢复,不需要用户重新开启+- XPC 请求发出但尚未确认时不提前显示成功,避免界面和系统实际状态相反-`sleepBlockReason` 是所有条件的唯一决策出口. UI 派生状态, 条件日志和实际切换都读取同一个结果, 新增条件时必须在一个有穷的 `switch` 中说明设置入口是否仍应可用. 这是一处刻意的防遗漏设计+`sleepBlockReason` 是所有条件的唯一决策出口。UI 派生状态、条件日志和实际切换都读取同一个结果,新增条件时必须在一个有穷的 `switch` 中说明设置入口是否仍应可用。这是一处刻意的防遗漏设计。## App assertion 与系统设置为什么并存-两套机制的作用域不同+两套机制的作用域不同:| 机制 | 生命周期 | 作用 | 失效方式 || --- | --- | --- | --- |-| IOKit assertion | App 进程 | 阻止空闲系统睡眠, 可选阻止显示器睡眠 | App 退出后由系统自动回收 |-| `pmset disablesleep` | 系统全局 | 覆盖 assertion 无法保证的系统睡眠路径 | 必须显式恢复, 因此需要 ownership 和 watchdog |+| IOKit assertion | App 进程 | 阻止空闲系统睡眠,可选阻止显示器睡眠 | App 退出后由系统自动回收 |+| `pmset disablesleep` | 系统全局 | 覆盖 assertion 无法保证的系统睡眠路径 | 必须显式恢复,因此需要 ownership 和 watchdog |-只使用 assertion 的恢复成本低, 但能力不完整. 只使用 `pmset` 的能力更强, 但 App 崩溃后可能留下全局状态. CodexBar 同时使用两者, 并把高风险的全局状态交给最小权限 helper 管理+只使用 assertion 的恢复成本低,但能力不完整。只使用 `pmset` 的能力更强,但 App 崩溃后可能留下全局状态。CodexBar 同时使用两者,并把高风险的全局状态交给最小权限 helper 管理。-App 侧 assertion 会在 XPC 获取流程开始前建立. 这样 helper 切换期间不会出现短暂的空闲睡眠窗口. 如果 helper 请求失败, 统一清理路径会释放 assertion, 避免形成只有 App 自己知道的半成功状态+App 侧 assertion 会在 XPC 获取流程开始前建立。这样 helper 切换期间不会出现短暂的空闲睡眠窗口。如果 helper 请求失败,统一清理路径会释放 assertion,避免形成只有 App 自己知道的半成功状态。## 获取与释放是确认式事务-获取流程不是先改 UI 再异步补系统操作, 而是一个带验证的事务+获取流程不是先改 UI 再异步补系统操作,而是一个带验证的事务:```text条件求值为允许@@ -67,7 +67,7 @@ App 侧 assertion 会在 XPC 获取流程开始前建立. 这样 helper 切换-> 发布已生效状态并开始累计时长```-释放流程按相反方向收口+释放流程按相反方向收口:```text条件求值为阻断@@ -81,37 +81,37 @@ App 侧 assertion 会在 XPC 获取流程开始前建立. 这样 helper 切换-> 必要时补发合盖睡眠```-通知放在 helper 确认 `SleepDisabled=0` 之后, 是为了保证用户看到的"已停止防睡眠"描述的是事实, 而不是尚未完成的意图+通知放在 helper 确认 `SleepDisabled=0` 之后,是为了保证用户看到的“已停止防睡眠”描述的是事实,而不是尚未完成的意图。-App idle assertion 会多保留到通知提交结束. 合盖机器在全局设置恢复后可能立即睡下, 如果先释放最后一条 assertion, 通知请求可能来不及交给系统. 提交完成后立即释放 assertion 并执行合盖边沿补偿, 这段短暂顺序不会重新声明系统所有权+App idle assertion 会多保留到通知提交结束。合盖机器在全局设置恢复后可能立即睡下,如果先释放最后一条 assertion,通知请求可能来不及交给系统。提交完成后立即释放 assertion 并执行合盖边沿补偿,这段短暂顺序不会重新声明系统所有权。## `mayHaveHelperLease` 为什么不能在超时时清除-XPC 超时只证明 App 没收到回复, 不证明 helper 没执行请求. 请求可能已经把租约写入 helper, 只是回复在连接断开时丢失+XPC 超时只证明 App 没收到回复,不证明 helper 没执行请求。请求可能已经把租约写入 helper,只是回复在连接断开时丢失。-因此 `mayHaveHelperLease` 采用保守语义+因此 `mayHaveHelperLease` 采用保守语义:- 请求获取时立即设为 `true`- 超时或连接失效时保持 `true`- 只有一次已确认的释放结果才能清为 `false`-这会让退出流程多做一次幂等释放, 但能避免 App 误以为没有租约而直接退出. 对全局系统状态而言, 多释放一次的成本远低于遗留 `SleepDisabled=1`+这会让退出流程多做一次幂等释放,但能避免 App 误以为没有租约而直接退出。对全局系统状态而言,多释放一次的成本远低于遗留 `SleepDisabled=1`## generation 解决什么竞态-用户关闭开关, 任务结束和重试可能在前一条 XPC 回复返回前连续发生. 如果只按回复到达顺序更新状态, 旧的"获取成功"可能覆盖新的"释放成功"+用户关闭开关、任务结束和重试可能在前一条 XPC 回复返回前连续发生。如果只按回复到达顺序更新状态,旧的“获取成功”可能覆盖新的“释放成功”。-App 和 helper 都使用单调递增 generation+App 和 helper 都使用单调递增 generation:- App 只接收当前 `requestGeneration` 的回调- helper 忽略比现有租约 generation 更旧的请求-- 连接作废时 App 推进 generation, 让在途回调自然失效+- 连接作废时 App 推进 generation,让在途回调自然失效-generation 不是用来给请求排序的日志编号, 而是异步状态提交的资格证明+generation 不是用来给请求排序的日志编号,而是异步状态提交的资格证明。## 生效条件-[`KeepAliveController.swift`](../../CodexBar/Services/KeepAlive/KeepAliveController.swift) 只有在以下条件全部成立时才建立防睡眠+[`KeepAliveController.swift`](../../CodexBar/Services/KeepAlive/KeepAliveController.swift) 只有在以下条件全部成立时才建立防睡眠:- 防睡眠主开关已开启- Hook 已启用且校验通过@@ -121,11 +121,11 @@ generation 不是用来给请求排序的日志编号, 而是异步状态提交- 未达到单次最长防睡眠时长- App 不在终止流程-等待批准任务默认不计入有效任务, 用户可以单独开启. 异常会话保护抑制的任务也不再维持防睡眠+等待批准任务默认不计入有效任务,用户可以单独开启。异常会话保护抑制的任务也不再维持防睡眠。-`KeepAliveController` 会先从运行中和等待批准快照中排除 `isAnonymous` 任务. 只有非匿名任务能够进入运行任务集合, 启动新一轮最长时长计时或维持防睡眠+`KeepAliveController` 会先从运行中和等待批准快照中排除 `isAnonymous` 任务。只有非匿名任务能够进入运行任务集合,启动新一轮最长时长计时或维持防睡眠。-控制器会发布明确的阻塞原因+控制器会发布明确的阻塞原因:| 原因 | 含义 || --- | --- |@@ -141,23 +141,23 @@ generation 不是用来给请求排序的日志编号, 而是异步状态提交## 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 秒@@ -166,91 +166,91 @@ CodexBarHelper 通过 `SMAppService` 注册为 LaunchDaemon. App 和 CodexBarHel## 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 的持久化顺序刻意偏向可恢复+helper 的持久化顺序刻意偏向可恢复:```text获取: persist owned -> pmset 1 -> read back 1释放: persist restoring -> pmset 0 -> read back 0 -> persist idle```-获取时先写 owned. 如果进程在写文件后, `pmset 1` 前崩溃, 下次启动多执行一次幂等 `pmset 0`, 不会留下全局禁止睡眠. 如果先写系统值再持久化, 两步之间崩溃就会失去恢复责任+获取时先写 owned。如果进程在写文件后,`pmset 1` 前崩溃,下次启动多执行一次幂等 `pmset 0`,不会留下全局禁止睡眠。如果先写系统值再持久化,两步之间崩溃就会失去恢复责任。-释放时先写 restoring. 如果在 `pmset 0` 或最终 idle 提交前崩溃, 下次启动仍知道这是一笔未完成恢复. 只有回读确认系统值为 `0` 后才允许持久化 idle+释放时先写 restoring。如果在 `pmset 0` 或最终 idle 提交前崩溃,下次启动仍知道这是一笔未完成恢复。只有回读确认系统值为 `0` 后才允许持久化 idle。### 外部来源消失后的接管-`external` 不是永久判断. CodexBar 在仍有有效任务时周期性读取 helper 缓存的系统状态+`external` 不是永久判断。CodexBar 在仍有有效任务时周期性读取 helper 缓存的系统状态:-- 外部来源仍存在时继续借用现有 `SleepDisabled=1`, 不写系统设置-- 外部来源消失而任务仍在时重新申请租约, 由 helper 完成新的 `0 -> 1`-- helper 已经因为其他有效客户端转为 owned 时更新来源展示, 不重复创建计时周期+- 外部来源仍存在时继续借用现有 `SleepDisabled=1`,不写系统设置+- 外部来源消失而任务仍在时重新申请租约,由 helper 完成新的 `0 -> 1`+- helper 已经因为其他有效客户端转为 owned 时更新来源展示,不重复创建计时周期-这项观察避免一个隐蔽空窗: 用户先用其他工具开启防睡眠, CodexBar 因此判定为 external, 随后其他工具关闭设置. 如果 CodexBar 不重新观察, UI 会继续显示防睡眠, 系统却已经可以睡眠+这项观察避免一个隐蔽空窗:用户先用其他工具开启防睡眠,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 持有有效任务时保持带身份的 XPC lease. CodexBarHelper 不把一次请求解释为脱离连接的永久授权+App 持有有效任务时保持带身份的 XPC lease。CodexBarHelper 不把一次请求解释为脱离连接的永久授权:```text租约有效 -> 保持 owned 状态@@ -259,66 +259,66 @@ App 持有有效任务时保持带身份的 XPC lease. CodexBarHelper 不把一宽限超时 -> 撤销租约并恢复 owned 状态```-异常退出后, CodexBarHelper 依靠连接失效, watchdog 和持久化所有权共同恢复系统设置+异常退出后,CodexBarHelper 依靠连接失效、watchdog 和持久化所有权共同恢复系统设置。-App 正常退出时先撤销租约和 IOKit assertion. 如果 CodexBarHelper 尚未确认恢复, App 终止流程会等待, 避免在不确定状态下直接离开+App 正常退出时先撤销租约和 IOKit assertion。如果 CodexBarHelper 尚未确认恢复,App 终止流程会等待,避免在不确定状态下直接离开。### 正常退出为什么可以被取消-`applicationShouldTerminate` 不能在未确认释放时直接返回允许. `prepareForTermination()` 会先停止新重试, 请求释放可能存在的租约, 然后等待 helper 回读结果+`applicationShouldTerminate` 不能在未确认释放时直接返回允许。`prepareForTermination()` 会先停止新重试、请求释放可能存在的租约,然后等待 helper 回读结果:- 释放成功时继续终止-- 释放失败时取消本次终止, 恢复正常条件求值和重试+- 释放失败时取消本次终止,恢复正常条件求值和重试-取消退出看似比直接关闭更强硬, 但这是可恢复性的一部分. 正常退出是 App 唯一能主动确认 root 全局状态的机会, 不应主动放弃这次确认. 强制退出仍由 helper 的 15 秒 watchdog 兜底+取消退出看似比直接关闭更强硬,但这是可恢复性的一部分。正常退出是 App 唯一能主动确认 root 全局状态的机会,不应主动放弃这次确认。强制退出仍由 helper 的 15 秒 watchdog 兜底。### helper 自检不是只看进程存活-helper 会分别检查 lease, ownership 记录和实测 `SleepDisabled`+helper 会分别检查 lease、ownership 记录和实测 `SleepDisabled`-- owned 且仍有租约时, 若系统值被外部改回 `0`, helper 会重新建立 `1`+- owned 且仍有租约时,若系统值被外部改回 `0`,helper 会重新建立 `1`- owned 且已无租约时恢复 `0`-- external 时只观察, 不把外部状态写成自己的 ownership-- 持久化记录不可信时采取 fail-safe 恢复, 不把损坏记录当成继续持有权限的依据+- external 时只观察,不把外部状态写成自己的 ownership+- 持久化记录不可信时采取 fail-safe 恢复,不把损坏记录当成继续持有权限的依据-这里的周期检查不是替代事件驱动 XPC, 而是修复系统设置被其他进程改写, 回调丢失或进程重启造成的事实漂移+这里的周期检查不是替代事件驱动 XPC,而是修复系统设置被其他进程改写、回调丢失或进程重启造成的事实漂移。## 时长和电池策略-单次时长只统计实际处于防睡眠的时间+单次时长只统计实际处于防睡眠的时间:- 没有任务时暂停或重置周期- 新一轮任务可以开始新的周期- 默认上限为 12 小时- 可选 1, 2, 4, 8, 12, 24 小时或无限制-低电量停止只在使用电池供电时生效+低电量停止只在使用电池供电时生效:- 可选阈值为 5%, 10%, 15%, 20%, 25%- 默认关闭-- 恢复使用 5 个百分点滞回, 避免电量在阈值附近反复切换+- 恢复使用 5 个百分点滞回,避免电量在阈值附近反复切换-防睡眠因低电量或时长上限结束时, 通知必须在睡眠状态已经恢复后发送+防睡眠因低电量或时长上限结束时,通知必须在睡眠状态已经恢复后发送。### 时长周期如何定义-"单次最长时长"不是从任务出现到任务消失的墙钟时间, 而是系统实际被 CodexBar 挡住睡眠的累计时间+“单次最长时长”不是从任务出现到任务消失的墙钟时间,而是系统实际被 CodexBar 挡住睡眠的累计时间。`KeepAliveDurationLimiter` 使用 `SuspendingClock`-- 系统睡眠期间时钟暂停, 醒来后不会把睡眠时间误算为防睡眠时间-- helper 不可用, 低电量或其他条件阻断期间暂停累计+- 系统睡眠期间时钟暂停,醒来后不会把睡眠时间误算为防睡眠时间+- helper 不可用、低电量或其他条件阻断期间暂停累计- 新运行任务出现时开始新周期- 等待任务恢复运行时开始新周期- 同一批任务只是在运行和观察之间刷新快照时不重复清零-`hasReached` 是当前周期内的粘滞状态. 达到上限后不能因为一次普通快照刷新立即恢复, 只有明确的新任务周期或设置变化才能重新求值+`hasReached` 是当前周期内的粘滞状态。达到上限后不能因为一次普通快照刷新立即恢复,只有明确的新任务周期或设置变化才能重新求值。-任务集合使用稳定 task ID 判断"新任务"和"等待后恢复", 而不是只比较数量. 如果一个任务结束同时另一个任务开始, 数量仍为 1, 但新的任务应得到完整时长预算+任务集合使用稳定 task ID 判断“新任务”和“等待后恢复”,而不是只比较数量。如果一个任务结束同时另一个任务开始,数量仍为 1,但新的任务应得到完整时长预算。### 电池读取为何是三态-电池读取使用 `unavailable`, `unreadable` 和 `present` 三态, 不能压成一个可选值+电池读取使用 `unavailable`, `unreadable` 和 `present` 三态,不能压成一个可选值:| 状态 | 含义 | 策略 || --- | --- | --- |@@ -326,64 +326,64 @@ helper 会分别检查 lease, ownership 记录和实测 `SleepDisabled`| `unreadable` | 本轮 IOKit 读取失败 | 保留上一次结论 || `present` | 有可信电量和供电来源 | 正常执行阈值判断 |-读取失败时维持上一次状态, 是为了避免一次 IOKit 枚举缺口让设置行闪烁, 也避免正在生效的低电量保护被瞬时解除. 一台机器只要曾经读到电池, 后续空列表就按 `unreadable` 处理, 因为硬件不会在运行中消失+读取失败时维持上一次状态,是为了避免一次 IOKit 枚举缺口让设置行闪烁,也避免正在生效的低电量保护被瞬时解除。一台机器只要曾经读到电池,后续空列表就按 `unreadable` 处理,因为硬件不会在运行中消失。-是否使用电池通过 power source state 判断, 不能通过 `isCharging` 推断. 接通电源但停止充电时 `isCharging` 也是 false, 此时电量并没有被任务持续消耗+是否使用电池通过 power source state 判断,不能通过 `isCharging` 推断。接通电源但停止充电时 `isCharging` 也是 false,此时电量并没有被任务持续消耗。### 低电量锁存与滞回-阈值为 `T` 时, 进入条件是电池供电且电量不高于 `T`, 退出条件是电量至少达到 `T + 5`+阈值为 `T` 时,进入条件是电池供电且电量不高于 `T`,退出条件是电量至少达到 `T + 5`-这 5 个百分点不是展示层修饰, 而是状态机滞回. 没有它时, 电量在阈值附近的测量抖动会反复执行 root 写入, assertion 切换和通知判断+这 5 个百分点不是展示层修饰,而是状态机滞回。没有它时,电量在阈值附近的测量抖动会反复执行 root 写入、assertion 切换和通知判断。-低电量通知还保留单轮锁存+低电量通知还保留单轮锁存:- 只有此前确实由 CodexBar 防止睡眠时才排队通知- 只在恢复成功后记录已经通知-- 接上电源会解除当前阻断, 但只有电量越过恢复门槛才结束这一轮锁存-- 修改阈值会开启新一轮, 避免旧阈值的通知状态污染新设置+- 接上电源会解除当前阻断,但只有电量越过恢复门槛才结束这一轮锁存+- 修改阈值会开启新一轮,避免旧阈值的通知状态污染新设置## 显示器常亮是附加效果-保持显示器唤醒只依赖"防睡眠已确认生效"和用户选项, 不独立维持系统睡眠+保持显示器唤醒只依赖“防睡眠已确认生效”和用户选项,不独立维持系统睡眠。-`NoDisplaySleep` 只能阻止显示器休眠, 不能阻止屏保和闲置锁屏. 因此实现还每 30 秒声明一次用户活动. 声明会复用同一个 assertion ID, 否则 `pmset -g assertions` 中会持续堆积同名记录+`NoDisplaySleep` 只能阻止显示器休眠,不能阻止屏保和闲置锁屏。因此实现还每 30 秒声明一次用户活动。声明会复用同一个 assertion ID,否则 `pmset -g assertions` 中会持续堆积同名记录。-显示断言失败只记独立错误, 不覆盖主防睡眠结果. 这是有意区分核心效果和附加效果, 避免设置页把"屏幕没有保持常亮"误报成"系统防睡眠完全失败"+显示断言失败只记独立错误,不覆盖主防睡眠结果。这是有意区分核心效果和附加效果,避免设置页把“屏幕没有保持常亮”误报成“系统防睡眠完全失败”。-assertion 名称使用 ASCII. 某些系统版本中带中文的名称会在 `pmset -g assertions` 中显示为空, 使诊断信息失去标识+assertion 名称使用 ASCII。某些系统版本中带中文的名称会在 `pmset -g assertions` 中显示为空,使诊断信息失去标识。## 合盖恢复的边沿补偿-合盖睡眠是一个边沿事件. 如果合盖时 `SleepDisabled=1`, 系统错过该边沿后不会仅因为稍后恢复为 `0` 就再次自动评估+合盖睡眠是一个边沿事件。如果合盖时 `SleepDisabled=1`,系统错过该边沿后不会仅因为稍后恢复为 `0` 就再次自动评估。-CodexBar 在确认自己拥有的系统设置已恢复后读取 clamshell 状态. 当盖子仍闭合且该硬件模式应因合盖睡眠时, 主动请求一次系统睡眠+CodexBar 在确认自己拥有的系统设置已恢复后读取 clamshell 状态。当盖子仍闭合且该硬件模式应因合盖睡眠时,主动请求一次系统睡眠。-补偿只用于 `.codexBar` 来源+补偿只用于 `.codexBar` 来源:-- external 状态不是 CodexBar 改写的, 不能替外部所有者决定何时睡眠+- external 状态不是 CodexBar 改写的,不能替外部所有者决定何时睡眠- `SleepDisabled` 仍为 `1` 时不能请求- 无法读取合盖状态时不猜测-这是典型的边沿事件修复, 不能用"最终值已经正确"替代+这是典型的边沿事件修复,不能用“最终值已经正确”替代。## 失败与重试策略-防睡眠采用有界重试, 因为每次重试都会重新建立特权连接并可能启动 root 进程+防睡眠采用有界重试,因为每次重试都会重新建立特权连接并可能启动 root 进程:-- 10 秒请求超时早于 15 秒 helper watchdog, App 先放弃不可信连接, helper 随后有机会清理租约-- 每次重试前重新比较期望状态, 用户已经关闭功能时不会继续重试获取-- 重试耗尽后保留明确错误, 不无限循环消耗系统资源-- 连接失效会立即释放 App assertion, 避免 UI 已降级但进程仍永久阻止空闲睡眠-- 旧请求通过 generation 失效, 不依赖每条取消路径都成功撤回底层消息+- 10 秒请求超时早于 15 秒 helper watchdog,App 先放弃不可信连接,helper 随后有机会清理租约+- 每次重试前重新比较期望状态,用户已经关闭功能时不会继续重试获取+- 重试耗尽后保留明确错误,不无限循环消耗系统资源+- 连接失效会立即释放 App assertion,避免 UI 已降级但进程仍永久阻止空闲睡眠+- 旧请求通过 generation 失效,不依赖每条取消路径都成功撤回底层消息-诊断时应区分 registration error 和 operation error. 前者表示 helper 未安装, 待批准或更新失败, 后者表示已安装 helper 的某次切换没有得到可信结果+诊断时应区分 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 匹配@@ -393,11 +393,11 @@ App 更新可能改变内嵌 CodexBarHelper 的签名或内容. App 会记录 Co## 手动验证矩阵-- 运行任务开始和结束时, 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.mdindex 6177851..8fbc582 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,32 +14,32 @@ CloudKit 同步用于在同一 iCloud 账户的 Mac 之间合并 Hook 日级统-> 按日期合并展示```-账户, 额度, token 总量, 实时任务和防睡眠状态不参与同步+账户、额度、token 总量、实时任务和防睡眠状态不参与同步。## 设计目标和非目标-同步的目标不是复制一台 Mac 的数据库, 而是让多台设备对同一天的独立贡献可以安全相加+同步的目标不是复制一台 Mac 的数据库,而是让多台设备对同一天的独立贡献可以安全相加。-因此设计优先级是+因此设计优先级是:1. 不上传原始工作内容和可直接关联硬件的身份2. 本机统计永远不依赖 CloudKit 才能展示3. 重扫和文件替换不能制造重复计数4. 网络失败时保留最后一份可解释的远端快照-5. 重试必须幂等, 不依赖请求恰好只执行一次+5. 重试必须幂等,不依赖请求恰好只执行一次-以下内容明确不属于同步协议+以下内容明确不属于同步协议:-- 实时任务状态, 因为它变化快且需要本机低延迟判断-- 账户额度, 因为它属于 Codex 账户而不是设备工作历史-- 防睡眠状态, 因为它是当前 Mac 的系统副作用-- 原始事件, 因为跨设备统计只需要可合并的日级事实+- 实时任务状态,因为它变化快且需要本机低延迟判断+- 账户额度,因为它属于 Codex 账户而不是设备工作历史+- 防睡眠状态,因为它是当前 Mac 的系统副作用+- 原始事件,因为跨设备统计只需要可合并的日级事实-把同步放在聚合层之后还有一个维护收益: 原始 Hook 格式可以独立演进, CloudKit 只面对稳定的日级投影+把同步放在聚合层之后还有一个维护收益:原始 Hook 格式可以独立演进,CloudKit 只面对稳定的日级投影。## 权威来源如何划分-同步展示同时使用 3 类值+同步展示同时使用 3 类值:| 数据 | 权威来源 | 断网时行为 || --- | --- | --- |@@ -47,13 +47,13 @@ CloudKit 同步用于在同一 iCloud 账户的 Mac 之间合并 Hook 日级统| 其他设备贡献 | `cache.jsonl` 中最近成功拉取的记录 | 保留最后快照 || 上传确认和增量位置 | `state.json` 与 `cursor.data` | 下次继续或重建 |-当前设备始终 local-first. CloudKit 中的本机副本是传给其他设备的复制品, 不是当前设备 UI 的真相来源. 这个规则避免网络往返期间出现先增加一次, 拉取后又重复增加一次的闪烁+当前设备始终 local-first。CloudKit 中的本机副本是传给其他设备的复制品,不是当前设备 UI 的真相来源。这个规则避免网络往返期间出现先增加一次,拉取后又重复增加一次的闪烁。-远端缓存是可重建投影, 游标只是加速状态. 任何游标错误都可以退化成全量读取 custom zone, 不要求用户清理本地文件+远端缓存是可重建投影,游标只是加速状态。任何游标错误都可以退化成全量读取 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:| 项目 | 值 || --- | --- |@@ -62,43 +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+custom zone 的意义不只是命名空间。它提供 zone change token 和删除事件,使设备可以增量同步新增、修改和删除,而不需要每轮扫描整个 private database。-zone 已确认状态和账户 salt 会在 actor 内跨同步轮次缓存, 省去每轮两个固定网络往返. 任意同步失败会使这两项缓存失效, 因为 iCloud 账户切换也可能首先表现为一次请求失败. 下一轮重新确认比继续使用错误账户上下文更安全+zone 已确认状态和账户 salt 会在 actor 内跨同步轮次缓存,省去每轮两个固定网络往返。任意同步失败会使这两项缓存失效,因为 iCloud 账户切换也可能首先表现为一次请求失败。下一轮重新确认比继续使用错误账户上下文更安全。## 启用条件-同步只有在以下条件全部成立时运行+同步只有在以下条件全部成立时运行:- 用户打开 CloudKit 同步- Hook 已启用并校验通过- 当前 iCloud 账户可用- 本地聚合服务可用-首次启用会标记 backfill, 上传本地保留期内需要同步的日期. 同步调度有最短 8 秒冷却, 合并短时间内的多次本地变化+首次启用会标记 backfill,上传本地保留期内需要同步的日期。同步调度有最短 8 秒冷却,合并短时间内的多次本地变化。## 设备匿名化-同步需要区分设备贡献, 但不能直接上传硬件标识+同步需要区分设备贡献,但不能直接上传硬件标识:1. 在 private database 创建 32 字节随机账户 salt2. 读取本机 `IOPlatformUUID`3. 使用账户 salt 对 UUID 执行 HMAC-SHA2564. 把结果作为云端 `deviceId`-原始 `IOPlatformUUID` 不会上传. 同一设备在同一 iCloud 账户中得到稳定 pseudonym, 不同账户得到不同结果+原始 `IOPlatformUUID` 不会上传。同一设备在同一 iCloud 账户中得到稳定 pseudonym,不同账户得到不同结果。-这里使用 HMAC 而不是普通 SHA-256. 硬件 UUID 的输入空间有固定格式, 单纯 hash 仍是跨账户稳定标识. 账户私有 salt 让同一硬件在不同 iCloud 账户中产生不可关联的 pseudonym+这里使用 HMAC 而不是普通 SHA-256。硬件 UUID 的输入空间有固定格式,单纯 hash 仍是跨账户稳定标识。账户私有 salt 让同一硬件在不同 iCloud 账户中产生不可关联的 pseudonym。-salt 存在同一个 private custom zone 中. 多台设备先后创建时通过 CloudKit 冲突后回读现有记录收敛到同一份 salt, 而不是让每台设备各自产生不兼容身份+salt 存在同一个 private custom zone 中。多台设备先后创建时通过 CloudKit 冲突后回读现有记录收敛到同一份 salt,而不是让每台设备各自产生不兼容身份。-本地状态记录最近解析出的 `deviceId`. 如果它变化, 同步会清除旧游标和远端缓存, 但保留待 replacement 日期. 设备身份变化意味着缓存的账户作用域已经不可信, 不能继续增量套用+本地状态记录最近解析出的 `deviceId`。如果它变化,同步会清除旧游标和远端缓存,但保留待 replacement 日期。设备身份变化意味着缓存的账户作用域已经不可信,不能继续增量套用。## 日聚合字段-每条日记录包含+每条日记录包含:- schema- device ID pseudonym@@ -110,7 +110,7 @@ salt 存在同一个 private custom zone 中. 多台设备先后创建时通过- model 计数- 更新时间-不会上传+不会上传:- 原始 Hook JSONL- session ID 或 turn ID 原文@@ -137,31 +137,31 @@ salt 存在同一个 private custom zone 中. 多台设备先后创建时通过-> 发布合并结果```-实际顺序刻意在上传前先拉取+实际顺序刻意在上传前先拉取:-- 上传前知道远端是否已经有同设备同日记录, 才能选择更新, 新建 generation 记录或跳过-- replacement 前必须先全量拉取, 才能找到增量缓存可能遗漏的旧 generation-- 上传后再次拉取, 才能把本轮写入和其他设备并发写入统一进本地缓存-- 最后清理过期记录, 避免清理失败阻断本轮有效数据上传+- 上传前知道远端是否已经有同设备同日记录,才能选择更新、新建 generation 记录或跳过+- replacement 前必须先全量拉取,才能找到增量缓存可能遗漏的旧 generation+- 上传后再次拉取,才能把本轮写入和其他设备并发写入统一进本地缓存+- 最后清理过期记录,避免清理失败阻断本轮有效数据上传-每个阶段都写入日志中的 `stage`, 失败信息因此能回答问题发生在 zone, device, fetch, upload 还是 prune, 而不只得到一个笼统的 CloudKit error+每个阶段都写入日志中的 `stage`,失败信息因此能回答问题发生在 zone, device, fetch, upload 还是 prune,而不只得到一个笼统的 CloudKit error:- 上传每批最多 25 条记录- 单批操作最长等待 20 秒- 拉取单页最多 200 条变更- 本地内容使用 SHA-256 hash 跳过未改变记录-20 秒是整轮上传预算, 不是每条记录的超时. 达到预算后剩余日期保留为未确认状态, 后续调度继续处理. 这样一次历史 backfill 不会长时间占用 actor 和用户可见刷新链路+20 秒是整轮上传预算,不是每条记录的超时。达到预算后剩余日期保留为未确认状态,后续调度继续处理。这样一次历史 backfill 不会长时间占用 actor 和用户可见刷新链路。-每个日期的稳定 JSON 只编码并 hash 一次, 同一结果同时用于筛选和成功确认. 如果在不同阶段重新编码, 字典顺序或可选字段差异可能让"是否改变"判断自行漂移+每个日期的稳定 JSON 只编码并 hash 一次,同一结果同时用于筛选和成功确认。如果在不同阶段重新编码,字典顺序或可选字段差异可能让“是否改变”判断自行漂移。-上传使用 `atomically: false`. 单批部分成功时, 每条 CloudKit 结果分别确认, 失败日期移除本地 hash 以便重试. 协议依赖单记录幂等身份, 不要求 25 条全部成功才前进+上传使用 `atomically: false`。单批部分成功时,每条 CloudKit 结果分别确认,失败日期移除本地 hash 以便重试。协议依赖单记录幂等身份,不要求 25 条全部成功才前进。## 合并语义-同一天可能有多个设备记录, 也可能有当前设备尚未上传的最新本地结果+同一天可能有多个设备记录,也可能有当前设备尚未上传的最新本地结果。-合并规则是+合并规则是:- 其他设备贡献按字段相加- 当前设备使用最新本地聚合替换云端的同源贡献@@ -169,68 +169,68 @@ salt 存在同一个 private custom zone 中. 多台设备先后创建时通过- 已确认属于不同来源的 generation 可以累加- 当前设备本地数据缺失时才使用云端缓存贡献-用本地值替换当前设备云端值可以避免同步刚上传但本地 UI 已更新时发生双重计数+用本地值替换当前设备云端值可以避免同步刚上传但本地 UI 已更新时发生双重计数。### 同设备同日为什么可能有多条记录-早期记录名只包含 `deviceId + date`. 新鲜来源可额外使用 `deviceId + date + sourceGeneration`+早期记录名只包含 `deviceId + date`。新鲜来源可额外使用 `deviceId + date + sourceGeneration`-generation 记录用于表达某一份原始来源的身份. 同源的本地和云端结果是替换关系, 明确不同的来源则可能是同一天先后产生的独立贡献+generation 记录用于表达某一份原始来源的身份。同源的本地和云端结果是替换关系,明确不同的来源则可能是同一天先后产生的独立贡献。-读取层先寻找与本地 `sourceGeneration` 匹配的 record. 匹配项只取本地或远端中更完整的一份, 其他 generation 继续累加. 旧 legacy record 没有 generation 时, 内容完全相同也可视为同源, 用于兼容早期记录+读取层先寻找与本地 `sourceGeneration` 匹配的 record。匹配项只取本地或远端中更完整的一份,其他 generation 继续累加。旧 legacy record 没有 generation 时,内容完全相同也可视为同源,用于兼容早期记录。-"所有旧 generation 都应失效"不是从 generation 本身推断, 而是由显式 `replacementDates` 事务表达. 这一区分避免正常文件换代丢掉独立贡献, 又让用户主动完整重建可以删除历史副本+“所有旧 generation 都应失效”不是从 generation 本身推断,而是由显式 `replacementDates` 事务表达。这一区分避免正常文件换代丢掉独立贡献,又让用户主动完整重建可以删除历史副本。-上传目标的选择遵循以下原则+上传目标的选择遵循以下原则:| 远端状态 | 本地来源 | 动作 || --- | --- | --- || 没有同日记录 | 任意 | 创建 legacy 或 generation record || 有同源记录 | 本地不少于远端 | 更新该记录 |-| 有同源且远端事件更多 | 本地带 generation | 保留远端, 避免较短的陈旧扫描覆盖较完整结果 |+| 有同源且远端事件更多 | 本地带 generation | 保留远端,避免较短的陈旧扫描覆盖较完整结果 || 有其他来源记录 | 本地来源新鲜 | 创建当前 generation record |-| 有其他来源记录 | 本地来源不新鲜 | 跳过, 等待权威重建 |+| 有其他来源记录 | 本地来源不新鲜 | 跳过,等待权威重建 |-`sourceIsFresh` 是一次读取对原始来源完整性的判断, 不是时间新旧. 文件被替换, 截断或仍在稳定边界确认中时, 较新的时间戳也不代表更权威+`sourceIsFresh` 是一次读取对原始来源完整性的判断,不是时间新旧。文件被替换、截断或仍在稳定边界确认中时,较新的时间戳也不代表更权威。### missing 为什么不能转成 0-CloudKit record schema 演进时, 旧记录可能没有新计数字段. `nil` 表示该设备那天无法提供这项统计, `0` 表示明确观察到零次+CloudKit record schema 演进时,旧记录可能没有新计数字段。`nil` 表示该设备那天无法提供这项统计,`0` 表示明确观察到零次。-合并时保留可用性信息, UI 才能区分"所有设备合计为 0"和"部分历史来源不支持该指标". 把缺失解码成 0 会制造无法在以后修复的虚假事实+合并时保留可用性信息,UI 才能区分“所有设备合计为 0”和“部分历史来源不支持该指标”。把缺失解码成 0 会制造无法在以后修复的虚假事实。## 来源替换与重建-Hook 原始文件被替换或完整重建时, 聚合层会改变 source generation. 同步层必须把这个变化解释为替换, 不能把新旧代际相加+Hook 原始文件被替换或完整重建时,聚合层会改变 source generation。同步层必须把这个变化解释为替换,不能把新旧代际相加。-用户执行重新扫描时+用户执行重新扫描时:1. 本地聚合从原始 JSONL 重建2. 受影响日期标记为 replacement3. 当前设备对应日期的云端记录被覆盖或删除后重建4. 其他设备记录保持不变-这种设计让重建只修正当前设备贡献+这种设计让重建只修正当前设备贡献。### replacement 为什么是持久化事务-重建和 CloudKit 同步不一定在同一进程生命周期完成. `replacementDates` 因此保存在 `state.json`, 不能只留在内存+重建和 CloudKit 同步不一定在同一进程生命周期完成。`replacementDates` 因此保存在 `state.json`,不能只留在内存。-对每个 replacement 日期, 同步执行+对每个 replacement 日期,同步执行:1. 全量重建远端缓存2. 枚举当前设备同日所有已知 legacy 和 generation record ID-3. 删除这些旧贡献, `unknownItem` 按幂等成功处理-4. 从本地 hash 表移除该日期, 强制重新上传+3. 删除这些旧贡献,`unknownItem` 按幂等成功处理+4. 从本地 hash 表移除该日期,强制重新上传5. 只有新内容得到确认后才清除 replacement 标记-replacement 进行中时, 快照会临时过滤当前设备该日期的云端缓存, 同时展示本机最新聚合. 即使 App 在删除和重传之间退出, UI 也不会把旧云端贡献与新本地贡献相加+replacement 进行中时,快照会临时过滤当前设备该日期的云端缓存,同时展示本机最新聚合。即使 App 在删除和重传之间退出,UI 也不会把旧云端贡献与新本地贡献相加。-先全量拉取是这一事务最关键的小细节. 增量 cursor 只保证从游标之后的变化完整, 不保证本地缓存从未因旧版本或手动删除丢过记录. 删除前全量枚举才能避免遗留幽灵 generation+先全量拉取是这一事务最关键的小细节。增量 cursor 只保证从游标之后的变化完整,不保证本地缓存从未因旧版本或手动删除丢过记录。删除前全量枚举才能避免遗留幽灵 generation。## 增量游标与本地缓存-同步状态位于+同步状态位于:```text~/Library/Application Support/CodexBar/HookEvents/Sync/@@ -238,49 +238,49 @@ replacement 进行中时, 快照会临时过滤当前设备该日期的云端缓| 文件 | 作用 || --- | --- |-| `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 个文件有不同的可恢复等级+3 个文件有不同的可恢复等级:| 文件 | 丢失后代价 | 恢复方式 || --- | --- | --- |-| `state.json` | 失去上传 hash 和 replacement 进度 | 重新比较并上传, replacement 需依赖仍存在的标记 |+| `state.json` | 失去上传 hash 和 replacement 进度 | 重新比较并上传,replacement 需依赖仍存在的标记 || `cache.jsonl` | 暂时看不到其他设备贡献 | 全量拉取 custom zone || `cursor.data` | 失去增量位置 | 全量拉取并重新建立 baseline |-`cursor.data` 使用 secure coding 保存 CloudKit opaque token. 代码不解析其内部结构. 全量拉取后还要建立新的 cursor baseline, 否则下一轮可能从空游标重复消费刚拉取的全部变化+`cursor.data` 使用 secure coding 保存 CloudKit opaque token。代码不解析其内部结构。全量拉取后还要建立新的 cursor baseline,否则下一轮可能从空游标重复消费刚拉取的全部变化。-本地 schema `3 -> 4` 的读取路径会先重建远端缓存再提交新状态. 未知 schema 则回到空同步状态, 因为错误解释上传确认信息比重新同步更危险+本地 schema `3 -> 4` 的读取路径会先重建远端缓存再提交新状态。未知 schema 则回到空同步状态,因为错误解释上传确认信息比重新同步更危险。-任何 record 字段, identity 或 schema 的变化都是兼容性决策. 需要同时考虑旧 App 仍在写入, 新 App 如何读取旧字段, 以及降级后是否会覆盖新记录, 不能只递增一个常量+任何 record 字段、identity 或 schema 的变化都是兼容性决策。需要同时考虑旧 App 仍在写入、新 App 如何读取旧字段,以及降级后是否会覆盖新记录,不能只递增一个常量。## 调度器为什么独立存在-本地维护和 CloudKit 同步共享聚合输入, 但触发频率不同. `WorkflowSyncScheduler` 把多处触发合并为单线程状态机+本地维护和 CloudKit 同步共享聚合输入,但触发频率不同。`WorkflowSyncScheduler` 把多处触发合并为单线程状态机。-优先级为+优先级为:```text用户请求重建 > 可立即执行的同步维护 > 纯本地维护 > 冷却中的同步```-关键细节包括+关键细节包括:-- 同步完成后 8 秒内的新请求合并到下一轮, 避免一次 Hook burst 触发多轮网络操作-- 合并请求保留最早 trigger, 因为它才是这轮工作的真实起因-- 重建会取消前一个尚未开始的重建 completion, 不让调用方永远等待-- 同步在等待期间被关闭时清除 pending sync, 但仍允许必要的本地维护继续-- `@Published` 订阅发生在 `willSet`, 从回调内读取属性仍是旧值, 因此 activation 由新回调参数显式计算后传入+- 同步完成后 8 秒内的新请求合并到下一轮,避免一次 Hook burst 触发多轮网络操作+- 合并请求保留最早 trigger,因为它才是这轮工作的真实起因+- 重建会取消前一个尚未开始的重建 completion,不让调用方永远等待+- 同步在等待期间被关闭时清除 pending sync,但仍允许必要的本地维护继续+- `@Published` 订阅发生在 `willSet`,从回调内读取属性仍是旧值,因此 activation 由新回调参数显式计算后传入-最后一点是 Combine 生命周期中很容易被"整理代码"破坏的小巧思. 现场重新读取 settings 看起来更简洁, 实际会用旧值决定是否同步+最后一点是 Combine 生命周期中很容易被“整理代码”破坏的小巧思。现场重新读取 settings 看起来更简洁,实际会用旧值决定是否同步。## 失败和恢复语义-同步失败不回滚已经确认的独立 record, 也不清空最后一份可用 cache. 下轮通过 hash, record ID 和 CloudKit 幂等 API 继续收敛+同步失败不回滚已经确认的独立 record,也不清空最后一份可用 cache。下轮通过 hash, record ID 和 CloudKit 幂等 API 继续收敛:| 失败点 | 已保留状态 | 下轮动作 || --- | --- | --- |@@ -290,11 +290,11 @@ replacement 进行中时, 快照会临时过滤当前设备该日期的云端缓| replacement 删除 | replacement 标记 | 重新枚举并幂等删除 || prune | 有效期内数据和上传结果 | 后续再清理 |-账户级缓存会在失败后失效, 但磁盘 cache 不会立刻作为新账户事实发布. availability 和 device identity 重新确认后才恢复同步快照+账户级缓存会在失败后失效,但磁盘 cache 不会立刻作为新账户事实发布。availability 和 device identity 重新确认后才恢复同步快照。## 修改同步协议时的检查顺序-1. 先定义字段语义, 尤其是 missing, 0 和空集合是否不同+1. 先定义字段语义,尤其是 missing、0 和空集合是否不同2. 决定 record identity 是否仍然幂等3. 评估旧 App 与新 App 并发写入的结果4. 明确本地 state, cache 和 cursor 的升级或重建路径@@ -304,7 +304,7 @@ replacement 进行中时, 快照会临时过滤当前设备该日期的云端缓## 保留与清理-CloudKit 记录保留期与本地 Hook 历史一致, 最长 210 天+CloudKit 记录保留期与本地 Hook 历史一致,最长 210 天:- 本地原始和日聚合过期后删除- 当前设备过期云端记录进入清理@@ -313,7 +313,7 @@ CloudKit 记录保留期与本地 Hook 历史一致, 最长 210 天## 错误分类-同步层区分以下状态, 供设置页展示和通知+同步层区分以下状态,供设置页展示和通知:- 网络不可用- iCloud 账户不可用@@ -322,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.mdindex fd32430..3c22072 100644--- a/Docs/DeveloperGuide/ui-and-lifecycle.md+++ b/Docs/DeveloperGuide/ui-and-lifecycle.md@@ -4,54 +4,54 @@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 负责声明内容,AppKit 负责窗口和事件生命周期:| 层 | 负责 | 不负责 || --- | --- | --- |-| SwiftUI View | 布局, 数据展示, 用户意图回调 | 创建长期服务, 决定 key window, 安装全局事件监听 |-| ViewModel 和 Settings | 发布稳定快照, 保存用户设置 | 持有窗口或判断屏幕坐标 |+| SwiftUI View | 布局、数据展示、用户意图回调 | 创建长期服务、决定 key window、安装全局事件监听 |+| ViewModel 和 Settings | 发布稳定快照、保存用户设置 | 持有窗口或判断屏幕坐标 || AppKit Controller | popover, panel, window, focus, event monitor | 重新实现业务状态机 || AppDelegate | 组装和持有长期对象 | 承载具体视图布局 |-这个边界让同一份菜单内容可以装入 `NSPopover` 或 fallback `NSPanel`, 同时避免 SwiftUI View 因 identity 变化而销毁 monitor, XPC 或通知服务+这个边界让同一份菜单内容可以装入 `NSPopover` 或 fallback `NSPanel`,同时避免 SwiftUI View 因 identity 变化而销毁 monitor、XPC 或通知服务。## `LSUIElement` 下的 3 类焦点-开发时需要区分+开发时需要区分:- App 是否 active- 某个 window 是否 key- 菜单表面是否逻辑上 presented-这 3 个状态不会自动同步. 例如 Command-Space 会让 App resign active, 但用户可能只是临时打开 Spotlight, 不希望菜单立即消失. 设置窗口可能已经可见, 但菜单关闭动画期间不应抢回 key 造成闪烁+这 3 个状态不会自动同步。例如 Command-Space 会让 App resign active,但用户可能只是临时打开 Spotlight,不希望菜单立即消失。设置窗口可能已经可见,但菜单关闭动画期间不应抢回 key 造成闪烁。-因此代码不使用 `NSApp.isActive` 作为菜单唯一真相, 而是维护显式的 menu surface 状态和当前容器, 再由事件监听器协调 activation+因此代码不使用 `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 与通知, 防睡眠的观察关系+- 建立 monitor 与通知、防睡眠的观察关系- 启动状态刷新和 Hook 活动读取- 创建状态栏控制器- 安装全局快捷键- 配置 Sparkle 更新- 在 App 终止时协调防睡眠释放-对象由 composition root 显式持有, 避免 SwiftUI View 生命周期意外销毁长期服务+对象由 composition root 显式持有,避免 SwiftUI View 生命周期意外销毁长期服务。### 启动顺序为什么重要-普通模式的装配顺序体现依赖关系+普通模式的装配顺序体现依赖关系:```text创建 settings 和数据服务@@ -62,131 +62,131 @@ AppDelegate 负责-> 启动周期刷新与更新服务```-通知和防睡眠只消费 monitor 已发布的快照或转场, 不反向控制 reader. Controller 通过闭包连接这些服务, 从而避免服务层依赖 AppKit 容器+通知和防睡眠只消费 monitor 已发布的快照或转场,不反向控制 reader。Controller 通过闭包连接这些服务,从而避免服务层依赖 AppKit 容器。-终止时顺序反转, 但防睡眠是例外. AppDelegate 先异步确认 helper lease 已释放, 成功后才允许进程终止. 详细事务见 [防睡眠系统](sleep-prevention.md)+终止时顺序反转,但防睡眠是例外。AppDelegate 先异步确认 helper lease 已释放,成功后才允许进程终止。详细事务见 [防睡眠系统](sleep-prevention.md)## 状态栏图标-状态图标综合 app-server 加载状态, 菜单栏额度设置和任务活动快照+状态图标综合 app-server 加载状态、菜单栏额度设置和任务活动快照。-任务状态点的优先级是+任务状态点的优先级是:```text等待批准 > 运行中 > 最近完成 > 最近中断 > 空闲```-图标生成结果按输入状态缓存, 避免每次定时刷新重复绘制. 非激活或不可用状态通过 alpha 表达+图标生成结果按输入状态缓存,避免每次定时刷新重复绘制。非激活或不可用状态通过 alpha 表达。### 图像状态与 tooltip 状态分离-`StatusIconState` 同时含图像输入和 tooltip 输入, 但 `renderState` 只保留真正影响像素的字段+`StatusIconState` 同时含图像输入和 tooltip 输入,但 `renderState` 只保留真正影响像素的字段:-- 活跃任务持续时间每分钟变化, 只更新 tooltip-- 额度过期但仍展示缓存时, 图标和进度使用降低后的 alpha+- 活跃任务持续时间每分钟变化,只更新 tooltip+- 额度过期但仍展示缓存时,图标和进度使用降低后的 alpha- 指示点或额度条显隐变化时才启动约 0.18 秒的 10 帧动画-- 新渲染状态到达时取消旧动画, 每帧再次确认目标状态仍是当前状态+- 新渲染状态到达时取消旧动画,每帧再次确认目标状态仍是当前状态-如果直接对完整状态做 `NSImage` 重绘, 每次计时文字变化都会打断动画并增加菜单栏绘制. 将 render identity 显式建模是一个小而重要的性能边界+如果直接对完整状态做 `NSImage` 重绘,每次计时文字变化都会打断动画并增加菜单栏绘制。将 render identity 显式建模是一个小而重要的性能边界。-无状态点和额度条时图标保持 template image, 让系统根据浅色, 深色和菜单栏状态自动着色. 一旦加入自定义颜色或进度条就使用显式颜色绘制+无状态点和额度条时图标保持 template image,让系统根据浅色、深色和菜单栏状态自动着色。一旦加入自定义颜色或进度条就使用显式颜色绘制。-tooltip 只在存在实时任务持续时间时启动 60 秒计时器, 空闲时不保留永久 timer. App 还把 `NSInitialToolTipDelay` 调整为 500 ms, 让菜单栏这种小点击目标的状态解释更容易被发现+tooltip 只在存在实时任务持续时间时启动 60 秒计时器,空闲时不保留永久 timer。App 还把 `NSInitialToolTipDelay` 调整为 500 ms,让菜单栏这种小点击目标的状态解释更容易被发现。-左键打开主面板. 右键或按住 Control 点击打开上下文菜单+左键打开主面板。右键或按住 Control 点击打开上下文菜单。## 主面板主面板优先使用 `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 个状态+`menuSurfaceState` 有 4 个状态:```texthidden -> opening -> shown -> closing -> hidden```-它解决快速重复点击产生的中间态+它解决快速重复点击产生的中间态:- `opening` 或 `shown` 时再次 toggle 进入关闭-- `closing` 时再次 toggle 先完成旧关闭, 再打开新表面+- `closing` 时再次 toggle 先完成旧关闭,再打开新表面- 关闭开始后取消延迟刷新和旧动画-- 非动画关闭会直接完成状态收口, 不等待不会发生的 animation completion+- 非动画关闭会直接完成状态收口,不等待不会发生的 animation completion-只检查 `popover.isShown` 不足以表示 opening 或 fade-out 中的逻辑状态, 也无法同时覆盖 fallback panel+只检查 `popover.isShown` 不足以表示 opening 或 fade-out 中的逻辑状态,也无法同时覆盖 fallback panel。### dismiss 规则为什么由一个监听器管理-主面板的允许点击区域是一个集合+主面板的允许点击区域是一个集合:```text当前菜单窗口 + status item 按钮 + 所有已显示侧边面板```-本地 monitor 处理 App 内鼠标和键盘, global monitor 处理其他 App 上的鼠标点击, workspace 和 window observer 处理激活变化. 任一入口最后都调用同一 `onDismiss`+本地 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 尚未挂载的时机+- Command-Tab 允许系统切换,同时关闭面板+- Command-Space 短暂抑制 activation dismiss,避免打开 Spotlight 时误关+- 点击后重新固定 `NSVisualEffectView` 为 inactive,避免 AppKit 自动强调背景导致明暗跳变+- 初次安装 observer 后 `Task.yield()` 再补一次窗口获取和聚焦,覆盖 popover window 尚未挂载的时机-这些规则应作为一个交互表面整体修改. 只给某个侧边 panel 单独添加 event monitor 会制造监听顺序和重复关闭问题+这些规则应作为一个交互表面整体修改。只给某个侧边 panel 单独添加 event monitor 会制造监听顺序和重复关闭问题。### 淡入淡出作用在内容而不是窗口-popover 的系统窗口由 AppKit 管理, 直接动画窗口 alpha 容易与系统显示状态冲突. `MenuSurfaceFadeCoordinator` 对活动容器的 content view 做动画, 完成后再调用统一 close+popover 的系统窗口由 AppKit 管理,直接动画窗口 alpha 容易与系统显示状态冲突。`MenuSurfaceFadeCoordinator` 对活动容器的 content view 做动画,完成后再调用统一 close。-关闭期间辅助窗口暂时拒绝 `makeKey()`. 否则原本已打开的设置或日志窗口可能在菜单 fade-out 的几帧里突然跳到前面+关闭期间辅助窗口暂时拒绝 `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, 还验证+全局快捷键可能在 status item 尚未完成布局、菜单栏位于另一块屏幕,或系统暂时不给出 button window 时触发。代码不会只检查 button 非 nil,还验证:- window 和 screen 存在- button 没有隐藏且 bounds 非空- 转换后的屏幕 rect 有效且至少为 1 point- rect 与目标屏幕 frame 在 1 point 容差内相交-只有全部成立才使用 popover 箭头. 否则 fallback panel 放到鼠标所在屏幕. 这避免 popover 被 AppKit 放到错误显示器或完全不可见的位置+只有全部成立才使用 popover 箭头。否则 fallback panel 放到鼠标所在屏幕。这避免 popover 被 AppKit 放到错误显示器或完全不可见的位置。-fallback panel 在展示前根据 SwiftUI fitting size 和目标屏幕可见区域约束尺寸. 坐标计算集中在 `ScreenGeometry`, 因为 AppKit 使用左下角原点, SwiftUI 局部布局和多显示器 frame 很容易混用+fallback panel 在展示前根据 SwiftUI fitting size 和目标屏幕可见区域约束尺寸。坐标计算集中在 `ScreenGeometry`,因为 AppKit 使用左下角原点,SwiftUI 局部布局和多显示器 frame 很容易混用。## 侧边详情面板-主面板可以打开+主面板可以打开:- 活跃度热力图详情- Reset Credits 详情- 活动中心-这些面板互斥, 打开一个时关闭其他侧边面板. 它们会把自己的屏幕区域加入主表面的额外 hit region, 用户在主面板和侧边面板之间移动或点击时不会触发误关闭+这些面板互斥,打开一个时关闭其他侧边面板。它们会把自己的屏幕区域加入主表面的额外 hit region,用户在主面板和侧边面板之间移动或点击时不会触发误关闭。-所有详情面板实现 `MenuSideDetailPanel` 并登记在 `sideDetailPanels` 数组. 互斥关闭, 主表面关闭和 hit testing 都遍历同一份名册+所有详情面板实现 `MenuSideDetailPanel` 并登记在 `sideDetailPanels` 数组。互斥关闭、主表面关闭和 hit testing 都遍历同一份名册。-这比在每对面板之间写互相关闭更可扩展. 新增第 4 个面板时只需要加入名册, 不需要补齐 6 对互斥关系+这比在每对面板之间写互相关闭更可扩展。新增第 4 个面板时只需要加入名册,不需要补齐 6 对互斥关系。-hover 类型的热力图面板在打开其他面板前可以渐隐, 点击类型的面板通常立即关闭旧面板. 这是为了避免同一屏幕位置出现两个反向滑动动画叠加+hover 类型的热力图面板在打开其他面板前可以渐隐,点击类型的面板通常立即关闭旧面板。这是为了避免同一屏幕位置出现两个反向滑动动画叠加。-相关控制器包括+相关控制器包括:- [`HeatmapDetailPanelController.swift`](../../CodexBar/Controllers/HeatmapDetailPanelController.swift)- [`ResetCreditsPanelController.swift`](../../CodexBar/Controllers/ResetCreditsPanelController.swift)@@ -197,38 +197,38 @@ hover 类型的热力图面板在打开其他面板前可以渐隐, 点击类型设置与日志由独立的 `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+`HostingWindowController` 懒创建并长期复用单个 window:-- `isReleasedWhenClosed = false`, 关闭只隐藏, 下次保留窗口对象和 SwiftUI 状态-- `.moveToActiveSpace`, 重开时跟随当前 Space, 不把用户切回旧桌面-- 优先在 status item 所在屏幕居中, 再退到 window screen 或 main screen+- `isReleasedWhenClosed = false`,关闭只隐藏,下次保留窗口对象和 SwiftUI 状态+- `.moveToActiveSpace`,重开时跟随当前 Space,不把用户切回旧桌面+- 优先在 status item 所在屏幕居中,再退到 window screen 或 main screen- miniaturized 窗口先 deminiaturize 再激活-设置窗口的高度随当前 tab 内容变化, 但固定上边缘并限制到屏幕 visible frame. 固定上边缘可以减少切换 tab 时整窗上下漂移, 让标题栏保持稳定视觉锚点+设置窗口的高度随当前 tab 内容变化,但固定上边缘并限制到屏幕 visible frame。固定上边缘可以减少切换 tab 时整窗上下漂移,让标题栏保持稳定视觉锚点。-通知和防睡眠的二级设置面板按需创建. 控制器一旦创建就会长期订阅内容高度变化, 如果 App 启动时预建所有面板, 从未使用的 UI 也会一直参与更新+通知和防睡眠的二级设置面板按需创建。控制器一旦创建就会长期订阅内容高度变化,如果 App 启动时预建所有面板,从未使用的 UI 也会一直参与更新。### 120 ms 焦点恢复不是业务延迟-菜单关闭时 `AuxiliaryHostingWindow` 暂时把 `allowsKeyFocus` 设为 false. 关闭完成后等待约 120 ms 再恢复+菜单关闭时 `AuxiliaryHostingWindow` 暂时把 `allowsKeyFocus` 设为 false。关闭完成后等待约 120 ms 再恢复。-这段时间给 AppKit 完成 popover order-out, activation 和 key window 重算. 删除延迟可能只在开发机上偶尔复现设置窗口闪前, 因此应把它视为系统事件排序约束, 而不是可以随意优化掉的等待+这段时间给 AppKit 完成 popover order-out, activation 和 key window 重算。删除延迟可能只在开发机上偶尔复现设置窗口闪前,因此应把它视为系统事件排序约束,而不是可以随意优化掉的等待。-右键菜单 action 也要等 `menuDidClose` 后通过主队列执行. menu tracking 是嵌套事件循环, 在其中同步创建窗口会得到不稳定的 activation 顺序+右键菜单 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`@@ -236,66 +236,66 @@ hover 类型的热力图面板在打开其他面板前可以渐隐, 点击类型- 系统注册冲突时回滚到之前可用设置- 设置变更立即重新注册-Carbon API 适合无 Dock 菜单栏 App, 不需要安装全局键盘事件 tap 或请求输入监控权限+Carbon API 适合无 Dock 菜单栏 App,不需要安装全局键盘事件 tap 或请求输入监控权限。-注册新快捷键采用先试后换+注册新快捷键采用先试后换:1. 为候选快捷键安装临时 handler 和 hot key2. 注册成功后才释放当前 registration3. 注册失败时清理候选资源并恢复设置中的旧值-如果先注销旧快捷键, 一次冲突会让用户同时失去新旧两组按键. `GlobalHotKeyRegistration` 在显式 invalidate 和 deinit 中都清理 Carbon 引用, 避免重注册泄漏 handler+如果先注销旧快捷键,一次冲突会让用户同时失去新旧两组按键。`GlobalHotKeyRegistration` 在显式 invalidate 和 deinit 中都清理 Carbon 引用,避免重注册泄漏 handler。-至少两个修饰键降低误触概率. Command-Space 和 Command-Tab 被拒绝, 因为它们属于核心系统导航, 即使注册 API 某次允许也不应抢占+至少两个修饰键降低误触概率。Command-Space 和 Command-Tab 被拒绝,因为它们属于核心系统导航,即使注册 API 某次允许也不应抢占。## 自动刷新与面板打开-app-server 状态默认每 60 秒刷新. 面板打开时会安排约 160 ms 的延迟刷新, 先完成动画和焦点切换, 再更新数据+app-server 状态默认每 60 秒刷新。面板打开时会安排约 160 ms 的延迟刷新,先完成动画和焦点切换,再更新数据。-主面板显示倒计时. 手动刷新由双击触发, 避免单击状态栏本身与按钮动作产生歧义+主面板显示倒计时。手动刷新由双击触发,避免单击状态栏本身与按钮动作产生歧义。-刷新协调器合并并发触发, 防止定时器, 面板打开和用户操作重复创建相同请求+刷新协调器合并并发触发,防止定时器、面板打开和用户操作重复创建相同请求。-面板打开时 Hook 统计立即从本地缓存刷新, app-server 请求延后约 160 ms. 前者便宜且能快速填充内容, 后者可能启动进程或发协议请求, 放在开场动画之后可减少首帧卡顿+面板打开时 Hook 统计立即从本地缓存刷新,app-server 请求延后约 160 ms。前者便宜且能快速填充内容,后者可能启动进程或发协议请求,放在开场动画之后可减少首帧卡顿。-`refreshIfNeeded` 仍会执行 freshness 合并, 160 ms 不是绕过协调器的第二套刷新路径. 面板在等待期间关闭时 task 被取消, 不再为不可见 UI 发请求+`refreshIfNeeded` 仍会执行 freshness 合并,160 ms 不是绕过协调器的第二套刷新路径。面板在等待期间关闭时 task 被取消,不再为不可见 UI 发请求。## 修改 UI 生命周期时的检查顺序1. 确定变化属于 SwiftUI 内容还是 AppKit 容器生命周期2. 检查 popover 和 fallback panel 是否共用相同行为-3. 检查 opening 和 closing 中间态, 不只验证稳定状态+3. 检查 opening 和 closing 中间态,不只验证稳定状态4. 检查点击区域是否需要加入 extra surface-5. 检查 App active, key window 和逻辑 presented 是否可能分离+5. 检查 App active、key window 和逻辑 presented 是否可能分离6. 检查任务或 timer 在关闭和 uninstall 时是否取消-7. 在多显示器, 多 Space 和无可信 status item anchor 下验证-8. 从通知点击, 全局快捷键和右键菜单 3 个入口分别打开+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 位于鼠标屏幕- 快捷键冲突后原快捷键仍可用diff --git a/Docs/UserGuide/README.md b/Docs/UserGuide/README.mdindex 6c6b5e6..d577069 100644--- a/Docs/UserGuide/README.md+++ b/Docs/UserGuide/README.md@@ -4,32 +4,32 @@| 文档 | 内容 || --- | --- |-| [安装与快速开始](getting-started.md) | 运行要求,安装方式,基本操作和功能依赖 |-| [主面板与菜单栏](main-panel.md) | 菜单栏状态,账户,额度,Token 热力图和任务中心 |-| [实时任务与 CodexBar Hook](activity-and-hook.md) | Hook 的作用,启用方式,任务状态和历史统计 |-| [通知与提醒](notifications.md) | 每类通知的触发条件,默认值,音效和触觉反馈 |-| [防止系统睡眠](sleep-prevention.md) | 生效条件,全部保护选项,CodexBarHelper 授权和外部来源共存 |-| [数据,同步与隐私](sync-data-privacy.md) | 本机数据,iCloud 同步,重建数据和网络边界 |-| [设置参考](settings.md) | 通用,高级和关于页面中每一个设置的作用 |-| [常见问题与排查](troubleshooting.md) | 登录,Hook,通知,防睡眠,同步和日志问题 |+| [安装与快速开始](getting-started.md) | 运行要求、安装方式、基本操作和功能依赖 |+| [主面板与菜单栏](main-panel.md) | 菜单栏状态、账户、额度、Token 热力图和任务中心 |+| [实时任务与 CodexBar Hook](activity-and-hook.md) | Hook 的作用、启用方式、任务状态和历史统计 |+| [通知与提醒](notifications.md) | 每类通知的触发条件、默认值、音效和触觉反馈 |+| [防止系统睡眠](sleep-prevention.md) | 生效条件、全部保护选项、CodexBarHelper 授权和外部来源共存 |+| [数据、同步与隐私](sync-data-privacy.md) | 本机数据、iCloud 同步、重建数据和网络边界 |+| [设置参考](settings.md) | 通用、高级和关于页面中每一个设置的作用 |+| [常见问题与排查](troubleshooting.md) | 登录、Hook、通知、防睡眠、同步和日志问题 |## 按目标快速查找- 只想查看账户和额度,从 [安装与快速开始](getting-started.md) 开始- 想看正在运行或等待批准的任务,阅读 [实时任务与 CodexBar Hook](activity-and-hook.md)- 想在长任务期间阻止 Mac 睡眠,阅读 [防止系统睡眠](sleep-prevention.md)-- 想知道某个开关是否会上传数据,阅读 [数据,同步与隐私](sync-data-privacy.md)+- 想知道某个开关是否会上传数据,阅读 [数据、同步与隐私](sync-data-privacy.md)- 已经遇到错误提示,直接进入 [常见问题与排查](troubleshooting.md)## 术语约定| 术语 | 含义 || --- | --- |-| Codex | Codex CLI,ChatGPT App 或 Codex App 中运行的 Codex 能力 |+| Codex | Codex CLI, ChatGPT App 或 Codex App 中运行的 Codex 能力 || app-server | CodexBar 在本机启动并连接的 Codex 数据接口进程 || CodexBar Hook | CodexBar 安装到 Codex 配置中的事件处理器 || 实时任务 | CodexBar 根据 Hook 事件和本机会话状态判断出的运行中或等待批准任务 |-| Hook 聚合 | 从本机 Hook 原始事件计算出的每日会话,轮次和工具等统计 |+| Hook 聚合 | 从本机 Hook 原始事件计算出的每日会话、轮次和工具等统计 || CodexBarHelper | 只负责系统级睡眠状态切换的 CodexBar 后台服务 |返回 [CodexBar README](../../README.md)diff --git a/Docs/UserGuide/activity-and-hook.md b/Docs/UserGuide/activity-and-hook.mdindex dc316d6..db2ae9b 100644--- a/Docs/UserGuide/activity-and-hook.md+++ b/Docs/UserGuide/activity-and-hook.md@@ -2,15 +2,15 @@## Hook 解决什么问题-账户,额度和 Token 用量是周期性快照,无法说明一轮 Codex 任务正在运行,等待批准还是已经结束。+账户、额度和 Token 用量是周期性快照,无法说明一轮 Codex 任务正在运行、等待批准还是已经结束。CodexBar Hook 会在 Codex 的关键事件发生时记录少量结构化字段,为 CodexBar 提供以下能力:- 菜单栏任务状态点和任务提示- 主面板活动卡片和并发任务中心-- 任务完成,等待批准和异常会话提醒+- 任务完成、等待批准和异常会话提醒- 任务触觉反馈-- 每日会话,轮次,工具调用,权限请求,上下文压缩和子 Agent 统计+- 每日会话、轮次、工具调用、权限请求、上下文压缩和子 Agent 统计- 按实时任务自动防止系统睡眠- 跨设备同步每日 Hook 聚合- 从原始事件重建历史聚合@@ -46,12 +46,12 @@ CodexBar 使用 `$CODEX_HOME/hooks.json`,未设置 `CODEX_HOME` 时使用 `~/.1. 读取并保留已有配置2. 为 CodexBar 追加独立的 command handler-3. 让 Codex 校验事件列表,来源和信任状态+3. 让 Codex 校验事件列表、来源和信任状态4. 只更新与当前 CodexBar handler 匹配的信任项关闭时只删除同时匹配当前 CodexBar 可执行路径和 `--hook-event` 参数的 handler。-用户自己的 handler,其他 App 的 handler,未识别字段和无关信任项都会保留。+用户自己的 handler、其他 App 的 handler、未识别字段和无关信任项都会保留。## 任务状态如何理解@@ -69,20 +69,20 @@ CodexBar 使用 `$CODEX_HOME/hooks.json`,未设置 `CODEX_HOME` 时使用 `~/.子 Agent 事件会更新所属顶层任务,不会独立显示为另一条并发任务。-Hook 事件缺少 session ID 时, CodexBar 会按项目显示匿名任务. 匿名任务仍可出现在运行中, 等待批准, 最近完成和最近终止列表中, 但不触发任务通知或触觉反馈, 不参与防睡眠和异常会话保护+Hook 事件缺少 session ID 时,CodexBar 会按项目显示匿名任务。匿名任务仍可出现在运行中、等待批准、最近完成和最近终止列表中,但不触发任务通知或触觉反馈,不参与防睡眠和异常会话保护。-活动卡片和任务中心使用橙色匿名图标标记这类任务, 悬停显示 `匿名任务不参与防睡眠`+活动卡片和任务中心使用橙色匿名图标标记这类任务,悬停时显示 `匿名任务不参与防睡眠`## Hook 事件与用途| 事件 | 主要用途 || --- | --- |-| `SessionStart` 和 `SessionEnd` | 会话生命周期,会话统计和任务收尾 |-| `UserPromptSubmit` 和 `Stop` | 对话轮次,任务开始和完成候选 |+| `SessionStart` 和 `SessionEnd` | 会话生命周期、会话统计和任务收尾 |+| `UserPromptSubmit` 和 `Stop` | 对话轮次、任务开始和完成候选 || `PreToolUse` 和 `PostToolUse` | 工具调用统计和任务进展 || `PermissionRequest` | 用户等待状态和权限请求统计 || `PreCompact` 和 `PostCompact` | 上下文压缩统计和任务进展 |-| `SubagentStart` 和 `SubagentStop` | 子 Agent 数量,状态和任务进展 |+| `SubagentStart` 和 `SubagentStop` | 子 Agent 数量、状态和任务进展 |## 每日统计如何计算@@ -109,14 +109,14 @@ Hook 事件缺少 session ID 时, CodexBar 会按项目显示匿名任务. 匿- 防止系统睡眠- 跨设备 Hook 聚合同步-账户,额度,Token 热力图,更新检查和日志窗口仍然可以使用。+账户、额度、Token 热力图、更新检查和日志窗口仍然可以使用。## 数据边界-Hook 原始事件只保存时间,事件名,模型,推理强度,权限模式,reviewer,session,turn,agent,工具名和工作目录等结构化字段。+Hook 原始事件只保存时间、事件名、模型、推理强度、权限模式、`reviewer`、`session`、`turn`、`agent`、工具名和工作目录等结构化字段。-CodexBar 不保存 prompt 文本,Codex 回复,工具参数或工具输出。+CodexBar 不保存 prompt 文本、Codex 回复、工具参数或工具输出。-完整存储和同步边界见 [数据,同步与隐私](sync-data-privacy.md)+完整存储和同步边界见 [数据、同步与隐私](sync-data-privacy.md)返回 [用户手册](README.md)diff --git a/Docs/UserGuide/getting-started.md b/Docs/UserGuide/getting-started.mdindex 49a41a1..34f66ae 100644--- a/Docs/UserGuide/getting-started.md+++ b/Docs/UserGuide/getting-started.md@@ -3,7 +3,7 @@## 运行要求- macOS 15.0 或更高版本-- 已安装并登录 [Codex CLI](https://github.com/openai/codex) 或安装了内置 Codex 的 ChatGPT App 或 Codex App+- 已安装并登录 [Codex CLI](https://github.com/openai/codex),或安装了内置 Codex 的 ChatGPT App 或 Codex App- 使用 Hook 相关功能时,当前运行的 Codex app-server 版本需要为 `0.145.0` 或更高版本- 使用跨设备同步时,Mac 需要登录可用的 iCloud 账户@@ -31,20 +31,20 @@ CodexBar 是菜单栏 App,启动后不会在 Dock 中显示图标:2. 左键点击图标打开主面板3. 等待首次账户和用量刷新完成4. 如果显示未登录,先在当前 Codex 中完成登录-5. 如果需要实时任务,通知或防睡眠,在 `设置 > 高级` 中开启 CodexBar Hook+5. 如果需要实时任务、通知或防睡眠,在 `设置 > 高级` 中开启 CodexBar Hook-CodexBar 每 60 秒自动刷新一次账户,额度和 Token 用量,双击主面板中的账户图标可以立即刷新。+CodexBar 每 60 秒自动刷新一次账户、额度和 Token 用量,双击主面板中的账户图标可以立即刷新。## 基本操作| 操作 | 结果 || --- | --- || 左键点击菜单栏图标 | 打开或关闭主面板 |-| 右键或 Control 点击菜单栏图标 | 打开设置,日志和退出菜单 |+| 右键或 Control 点击菜单栏图标 | 打开设置、日志和退出菜单 || `⌘⇧W` | 使用默认全局快捷键打开或关闭主面板 || `⌘,` | 打开设置窗口 || `⌘L` | 主面板打开时关闭面板并打开日志窗口 |-| 双击账户图标 | 立即刷新账户,额度和用量 |+| 双击账户图标 | 立即刷新账户、额度和用量 || 双击账户邮箱 | 切换邮箱模糊显示 || 悬停热力图方块 | 查看当天 Token 和 Hook 统计 || 点击活动卡片 | 打开并发任务中心 |@@ -56,7 +56,7 @@ CodexBar 每 60 秒自动刷新一次账户,额度和 Token 用量,双击主| 功能 | CodexBar Hook | 其他条件 || --- | --- | --- |-| 账户,套餐和额度 | 不需要 | Codex 已登录 |+| 账户、套餐和额度 | 不需要 | Codex 已登录 || Token 汇总和热力图 | 不需要 | 当前 Codex 支持用量接口 || 实时任务和任务中心 | 需要 | Hook 已通过校验 || 每日 Hook 统计 | 需要 | 本机存在 Hook 原始事件 |@@ -65,7 +65,7 @@ CodexBar 每 60 秒自动刷新一次账户,额度和 Token 用量,双击主| 防止系统睡眠 | 需要 | CodexBarHelper 已注册并获得系统批准 || 跨设备同步 | 需要 | iCloud 可用且用户主动开启同步 |-关闭 CodexBar Hook 不影响账户,额度,Token 热力图,更新检查或日志窗口。+关闭 CodexBar Hook 不影响账户、额度、Token 热力图、更新检查或日志窗口。## 语言与地区@@ -73,6 +73,6 @@ CodexBar 提供简体中文和英文界面,默认跟随 macOS 的 App 语言需要单独切换时,可在 macOS 系统设置的语言与地区页面为 CodexBar 指定 App 语言。-日期,时间,时长,百分比,月历和星期顺序始终跟随当前地区格式。+日期、时间、时长、百分比、月历和星期顺序始终跟随当前地区格式。下一步可以阅读 [主面板与菜单栏](main-panel.md) 或 [设置参考](settings.md)diff --git a/Docs/UserGuide/main-panel.md b/Docs/UserGuide/main-panel.mdindex d8133a4..9269a89 100644--- a/Docs/UserGuide/main-panel.md+++ b/Docs/UserGuide/main-panel.md@@ -2,12 +2,12 @@## 菜单栏图标-CodexBar 用图标,状态点和可选额度条同时表达账户,任务和额度状态:+CodexBar 用图标、状态点和可选额度条同时表达账户、任务和额度状态:| 外观 | 含义 || --- | --- || 正常账户图标 | 账户数据可用 |-| 错误账户图标 | 未登录,初始化失败或缺少可信额度与用量数据 |+| 错误账户图标 | 未登录、初始化失败或缺少可信额度与用量数据 || 蓝色状态点 | 至少有一个任务正在运行 || 橙色状态点 | 至少有一个任务正在等待用户批准 || 绿色状态点 | 任务刚刚完成,高亮持续 30 秒 |@@ -15,15 +15,15 @@ CodexBar 用图标,状态点和可选额度条同时表达账户,任务和多个状态同时存在时,等待批准优先于运行中,运行中优先于最近完成。-鼠标悬停在菜单栏图标上可以查看当前任务状态,项目名,持续时间,并发任务数量和额度窗口剩余比例。+鼠标悬停在菜单栏图标上可以查看当前任务状态、项目名、持续时间、并发任务数量和额度窗口剩余比例。额度数据来自缓存时,图标和进度条会降低透明度,表示当前看到的不是最新快照。## 账户区域- 展示当前登录账户或账户类型-- 展示 Enterprise,Team,Business,Pro,Plus,Edu 和 Free 等套餐标识-- 双击账户图标会立即刷新账户,额度和用量+- 展示 Enterprise, Team, Business, Pro, Plus, Edu 和 Free 等套餐标识+- 双击账户图标会立即刷新账户、额度和用量- 双击邮箱会切换模糊显示- 未登录时显示 `未登录`- app-server 无法初始化时显示 `初始化失败`@@ -61,7 +61,7 @@ CodexBar 会展示 Codex 返回的全部额度分组和窗口。热力图使用 30 列乘 7 行方块展示近 30 周每日 Token 用量,颜色强度相对于当前热力图中的峰值计算。-悬停日期方块时会显示日期,Token 数量和用量强度。+悬停日期方块时会显示日期、Token 数量和用量强度。CodexBar Hook 开启且当天有数据时,日期详情还会显示以下统计:@@ -75,7 +75,7 @@ CodexBar Hook 开启且当天有数据时,日期详情还会显示以下统计## 活动卡片-活动卡片的状态优先级为等待批准,运行中,最近完成,最近终止。+活动卡片的状态优先级为等待批准、运行中、最近完成、最近终止。卡片会按实际可用字段展示以下内容:@@ -89,9 +89,9 @@ CodexBar Hook 开启且当天有数据时,日期详情还会显示以下统计防睡眠实际生效时,活动卡片右侧会显示咖啡杯标记。-Hook 事件缺少 session ID 时, 任务仍会显示在活动卡片和任务中心, 并带有橙色匿名图标. 悬停图标会显示 `匿名任务不参与防睡眠`+Hook 事件缺少 session ID 时,任务仍会显示在活动卡片和任务中心,并带有橙色匿名图标。悬停图标会显示 `匿名任务不参与防睡眠`-活动卡片的 `+N` 只表示其他活跃任务总数, 不拆分匿名任务数量+活动卡片的 `+N` 只表示其他活跃任务总数,不拆分匿名任务数量。点击有内容的活动卡片可以打开任务中心。@@ -110,7 +110,7 @@ Hook 事件缺少 session ID 时, 任务仍会显示在活动卡片和任务中终止不会触发任务完成通知。-匿名任务的运行中, 等待批准, 最近完成和最近终止记录都会显示同一个匿名图标+匿名任务在运行中、等待批准、最近完成和最近终止状态下都会显示同一个匿名图标。## 底部状态@@ -118,7 +118,7 @@ Hook 事件缺少 session ID 时, 任务仍会显示在活动卡片和任务中- 数据更新时间- 距离下一次自动刷新的倒计时-- iCloud 同步关闭,同步中,已同步或失败状态+- iCloud 同步关闭、同步中、已同步或失败状态- 可用更新提示发现新版本时,双击更新提示可以开始更新。diff --git a/Docs/UserGuide/notifications.md b/Docs/UserGuide/notifications.mdindex e2bbd4b..8e46f04 100644--- a/Docs/UserGuide/notifications.md+++ b/Docs/UserGuide/notifications.md@@ -28,7 +28,7 @@即使系统通知没有发送成功,已确认超时的异常任务仍会被隐藏并停止参与防睡眠。-匿名任务不触发任务完成通知, 等待批准通知, 异常会话保护通知或任务触觉反馈, 但仍保留在活动卡片和任务中心中+匿名任务不触发任务完成通知、等待批准通知、异常会话保护通知或任务触觉反馈,但仍保留在活动卡片和任务中心中。## 可选阈值@@ -70,7 +70,7 @@## 通知交互-- CodexBar 位于前台时仍会显示通知横幅,通知列表项和声音+- CodexBar 位于前台时仍会显示通知横幅、通知列表项和声音- 点击任意 CodexBar 通知会打开主面板- 任务不再等待批准时,对应等待通知会从通知中心撤回- 异常任务恢复进展或候选失效时,对应保护通知会从通知中心撤回diff --git a/Docs/UserGuide/settings.md b/Docs/UserGuide/settings.mdindex b65b9c5..7a49d2b 100644--- a/Docs/UserGuide/settings.md+++ b/Docs/UserGuide/settings.md@@ -2,7 +2,7 @@右键或 Control 点击菜单栏图标并选择 `设置`,或按 `⌘,` 打开设置窗口。-设置窗口包含 `通用`,`高级` 和 `关于` 三个页面。+设置窗口包含 `通用`、`高级` 和 `关于` 三个页面。## 通用设置@@ -41,7 +41,7 @@### CodexBar Hook-开启后解锁实时任务,任务类通知,Hook 统计,防睡眠和跨设备同步。+开启后解锁实时任务、任务类通知、Hook 统计、防睡眠和跨设备同步。开启和校验要求当前 app-server 为 `0.145.0` 或更高版本。@@ -51,7 +51,7 @@关闭后,主面板不再显示活动卡片和任务中心入口。-这个设置不会关闭 Hook,不会停止 Hook 统计,通知或防睡眠。+这个设置不会关闭 Hook,不会停止 Hook 统计、通知或防睡眠。Hook 关闭时该选项会显示为关闭并置灰,保存的选择不会被覆盖。@@ -69,7 +69,7 @@ Hook 关闭时该选项会显示为关闭并置灰,保存的选择不会被覆| 任务触觉反馈 | 关闭 | 任务完成或等待批准时触发触摸板震动 || Codex TUI 通知 | 跟随 Codex 配置 | 独立于 CodexBar 通知 |-每类系统通知可以选择默认,静音,系统声音或 App 内置声音。+每类系统通知可以选择默认、静音、系统声音或 App 内置声音。完整说明见 [通知与提醒](notifications.md)@@ -94,7 +94,7 @@ Hook 关闭时该选项会显示为关闭并置灰,保存的选择不会被覆- 设置页显示同步状态和最近成功上传时间- 关闭后停止网络同步,本机 Hook 数据仍然保留-完整说明见 [数据,同步与隐私](sync-data-privacy.md)+完整说明见 [数据、同步与隐私](sync-data-privacy.md)### 重建数据@@ -102,7 +102,7 @@ Hook 关闭时该选项会显示为关闭并置灰,保存的选择不会被覆- 有原始事件的日期会显示数据标记- 选择完整范围后才可执行重建- 执行前会显示确认提示-- 完成后显示重建天数,事件数和跳过的无效行数+- 完成后显示重建天数、事件数和跳过的无效行数- 未完成的日期会在 Hook 可用时自动重试## 关于页面@@ -112,7 +112,7 @@ Hook 关闭时该选项会显示为关闭并置灰,保存的选择不会被覆| Codex CLI | 展示全局 Codex CLI 的磁盘版本和路径 || Codex APP | 展示 ChatGPT App 或 Codex App 内置 CLI 的磁盘版本和路径 || 当前使用 | 标记当前 app-server 实际使用的 Codex 来源和运行版本 |-| CodexBar 版本 | 展示当前版本,更新状态和可用更新 |+| CodexBar 版本 | 展示当前版本、更新状态和可用更新 || GitHub 项目 | 打开 CodexBar 项目页面 || 检查更新 | 手动触发 Sparkle 更新检查 || 退出 CodexBar | 先完成必要清理再退出 App |diff --git a/Docs/UserGuide/sleep-prevention.md b/Docs/UserGuide/sleep-prevention.mdindex b965699..48abf6d 100644--- a/Docs/UserGuide/sleep-prevention.md+++ b/Docs/UserGuide/sleep-prevention.md@@ -17,7 +17,7 @@ CodexBar 会根据实时任务状态自动管理系统睡眠,让长任务在1. CodexBar 正在运行且没有进入退出流程2. `防止系统睡眠` 主开关已打开3. CodexBar Hook 已安装并通过最近一次明确校验-4. 至少有一个非匿名运行中任务, 或已开启等待批准时保持且存在非匿名等待任务+4. 至少有一个非匿名运行中任务,或已开启等待批准时保持且存在非匿名等待任务5. CodexBarHelper 已注册并获得系统批准6. CodexBarHelper 当前不在更新过程中7. 低电量保护当前没有生效@@ -27,14 +27,14 @@ CodexBar 会根据实时任务状态自动管理系统睡眠,让长任务在条件恢复后,仍有符合条件任务时会自动重新生效。-匿名任务即使显示为运行中或等待批准, 也不会计入防睡眠的有效任务+匿名任务即使显示为运行中或等待批准,也不会计入防睡眠的有效任务。## 设置选项| 选项 | 作用 | 默认值 | 可选值 || --- | --- | --- | --- || 等待批准时保持 | 等待用户批准的任务也参与防睡眠 | 关闭 | 开启或关闭 |-| 保持屏幕常亮 | 同时阻止显示器睡眠,屏保和闲置锁屏 | 关闭 | 开启或关闭 |+| 保持屏幕常亮 | 同时阻止显示器睡眠、屏保和闲置锁屏 | 关闭 | 开启或关闭 || 最长防睡眠时间 | 限制一轮实际防睡眠的累计时长 | 12 小时 | 1, 2, 4, 8, 12, 24 小时或无限制 || 异常会话保护 | 长时间无进展时隐藏任务并停止其防睡眠贡献 | 1 小时 | 30 分钟, 1, 2, 4 小时 || 低电量保护 | 使用电池且电量过低时恢复系统睡眠 | 关闭 | 关闭或 5%, 10%, 15%, 20%, 25% |@@ -57,14 +57,14 @@ CodexBar 会根据实时任务状态自动管理系统睡眠,让长任务在CodexBar 会同时阻止显示器睡眠,并定期声明用户活动以压住屏保和闲置锁屏。-任务结束,低电量保护生效,达到时长上限或防睡眠失败时会同步释放。+任务结束、低电量保护生效、达到时长上限或防睡眠失败时会同步释放。开启后可能让你离开电脑时仍保持解锁界面,因此默认关闭。## 最长防睡眠时间- 只累计真正阻止系统睡眠的时间-- 因低电量,CodexBarHelper 不可用或其他条件暂停的时间不计入上限+- 因低电量、CodexBarHelper 不可用或其他条件暂停的时间不计入上限- 系统睡眠期间和系统时间调整不消耗上限- 没有活跃任务时会重置计时- 新运行任务出现或等待任务恢复运行时会开始新一轮计时@@ -76,15 +76,15 @@ CodexBar 会同时阻止显示器睡眠,并定期声明用户活动以压住- 跟随防睡眠主开关,没有独立开关- 只判断非匿名运行中任务-- 最近进展来自 Hook 事件,子 Agent 事件和本机会话生命周期+- 最近进展来自 Hook 事件、子 Agent 事件和本机会话生命周期- 达到阈值后保存保护记录,尝试通知并隐藏任务- 被隐藏任务不显示在活动卡片和任务中心,也不参与防睡眠- 后续出现新进展时自动恢复任务并撤回有效通知- 修改为更长阈值后,未超过新阈值的隐藏任务会恢复-- Hook 历史回放,系统睡眠,唤醒对账和 Hook 数据源不可用期间暂停判断+- Hook 历史回放、系统睡眠、唤醒对账和 Hook 数据源不可用期间暂停判断- 保护记录最长保留到最后进展后的 24 小时-保护记录只包含哈希任务标识和时间戳,不包含原始 session,turn,项目名或任务内容。+保护记录只包含哈希任务标识和时间戳,不包含原始 `session`、`turn`、项目名或任务内容。## 低电量保护diff --git a/Docs/UserGuide/sync-data-privacy.md b/Docs/UserGuide/sync-data-privacy.mdindex a741916..8ce363d 100644--- a/Docs/UserGuide/sync-data-privacy.md+++ b/Docs/UserGuide/sync-data-privacy.md@@ -1,8 +1,8 @@-# 数据,同步与隐私+# 数据、同步与隐私## 跨设备同步的内容-跨设备同步用于合并多台 Mac 的每日 Hook 聚合,不同步账户,额度或 Token 用量。+跨设备同步用于合并多台 Mac 的每日 Hook 聚合,不同步账户、额度或 Token 用量。启用条件如下:@@ -25,7 +25,7 @@| 同步未开启 | 用户没有开启同步或 CodexBar Hook 已关闭 || 正在同步 | 正在读取或写入 CloudKit || 已同步 | 最近一轮同步成功 |-| 同步失败 | 网络,iCloud 账户或服务暂时不可用 |+| 同步失败 | 网络、iCloud 账户或服务暂时不可用 |设置页还会显示最近一次成功上传时间。@@ -48,26 +48,26 @@4. 无法解析的行会跳过并计入结果5. 开启同步时,重建日期会在后续同步中替换当前设备对应日期的云端贡献-重建不会修改 Codex 账户,额度或 Token 用量。+重建不会修改 Codex 账户、额度或 Token 用量。## 本机保存的数据| 数据 | 内容 | 位置或生命周期 || --- | --- | --- || Hook 原始事件 | 选定的结构化事件字段 | `~/Library/Application Support/CodexBar/HookEvents/events`,保留 210 天 |-| Hook 每日聚合 | 事件计数,会话与轮次,项目名计数和模型计数 | `~/Library/Application Support/CodexBar/HookEvents/daily.jsonl`,保留 210 天 |-| Hook 维护状态 | 文件 offset,generation 和待处理日期 | `~/Library/Application Support/CodexBar/HookEvents/maintenance.json` |-| 同步缓存 | CloudKit 缓存,游标和上传状态 | `~/Library/Application Support/CodexBar/HookEvents/Sync` |+| Hook 每日聚合 | 事件计数、会话与轮次、项目名计数和模型计数 | `~/Library/Application Support/CodexBar/HookEvents/daily.jsonl`,保留 210 天 |+| Hook 维护状态 | 文件 `offset`、`generation` 和待处理日期 | `~/Library/Application Support/CodexBar/HookEvents/maintenance.json` |+| 同步缓存 | CloudKit 缓存、游标和上传状态 | `~/Library/Application Support/CodexBar/HookEvents/Sync` || 异常会话保护 | 哈希任务标识和时间戳 | `~/Library/Application Support/CodexBar/ActivityProtection/state.json`,最长 24 小时 || CodexBarHelper 所有权 | 睡眠所有权状态和恢复事务 | `/Library/Application Support/CodexBar/helper-state.json` |-| App 偏好 | 开关,阈值,快捷键和通知去重状态 | macOS UserDefaults |+| App 偏好 | 开关、阈值、快捷键和通知去重状态 | macOS UserDefaults || app-server 交互日志 | 最近 500 条请求和响应 | 只存在当前 App 进程内存 |每日聚合只在最近 3 天保留 session 和 turn ID 列表,更早日期转换为计数并删除列表。CodexBarHelper 所有权文件由 root 持有,用于 App 或 CodexBarHelper 异常退出后的睡眠状态恢复。-匿名任务不参与异常会话保护, 因此不会生成哈希任务标识或写入保护状态文件+匿名任务不参与异常会话保护,因此不会生成哈希任务标识或写入保护状态文件。## CloudKit 上传字段@@ -75,7 +75,7 @@ CodexBarHelper 所有权文件由 root 持有,用于 App 或 CodexBarHelper- iCloud 账户范围内的设备伪标识- 日期-- 本机 Hook 数据来源 generation+- 本机 Hook 数据来源 `generation`- 各类 Hook 事件计数- 会话数和对话轮次数- 项目显示名计数@@ -87,10 +87,10 @@ CodexBarHelper 所有权文件由 root 持有,用于 App 或 CodexBarHelper## CloudKit 不上传的内容- 原始 Hook 事件文件-- session ID,turn ID 和 agent ID+- session ID、turn ID 和 agent ID- 完整工作目录路径-- prompt,Codex 回复,工具参数或工具输出-- Codex 账户,额度和 Token 用量+- prompt、Codex 回复、工具参数或工具输出+- Codex 账户、额度和 Token 用量- app-server 交互日志- 异常会话保护记录- Codex 认证 token@@ -101,12 +101,12 @@ CodexBarHelper 所有权文件由 root 持有,用于 App 或 CodexBarHelperCodexBar 会读取以下本机数据:-- 通过本机 app-server 获取账户,额度,Token 用量和 Codex 配置+- 通过本机 app-server 获取账户、额度、Token 用量和 Codex 配置- 读取 Hook 原始事件以生成统计和实时任务- 读取本机 Codex rollout 的生命周期字段以区分完成与终止并补充进展时间- 在查询手动重置次数过期时间时读取 Codex `auth.json` 中的现有凭据-rollout 读取只提取生命周期,时间和推理强度等字段,不展示或保存会话正文和工具内容。+rollout 读取只提取生命周期、时间和推理强度等字段,不展示或保存会话正文和工具内容。CodexBar 不复制或持久化 Codex 认证 token。@@ -118,13 +118,13 @@ CodexBar 不复制或持久化 Codex 认证 token。| Sparkle 更新源 | 检查并安装 CodexBar 更新 | 自动检查开启或用户手动检查时 || CloudKit private database | 同步多设备每日 Hook 聚合 | 用户开启跨设备同步时 |-账户,额度和 Token 用量通过本机 app-server 的 stdio 通信获取,不是由 CodexBar 直接请求对应 OpenAI 接口。+账户、额度和 Token 用量通过本机 app-server 的 stdio 通信获取,不是由 CodexBar 直接请求对应 OpenAI 接口。## 日志隐私-系统日志只记录操作结果,状态分类,计数和错误阶段。+系统日志只记录操作结果、状态分类、计数和错误阶段。-系统日志不应记录账户额度数值,Token 用量,项目名,任务内容,session ID,turn ID 或 OAuth token。+系统日志不应记录账户额度数值、Token 用量、项目名、任务内容、session ID、turn ID 或 OAuth token。App 内 app-server 交互日志可能包含请求和响应内容,但只存在当前进程内存,只有用户主动打开日志窗口时才显示。diff --git a/Docs/UserGuide/troubleshooting.md b/Docs/UserGuide/troubleshooting.mdindex 03b1301..c8aae22 100644--- a/Docs/UserGuide/troubleshooting.md+++ b/Docs/UserGuide/troubleshooting.md@@ -9,7 +9,7 @@## 主面板显示未登录-1. 打开当前正在使用的 Codex CLI,ChatGPT App 或 Codex App+1. 打开当前正在使用的 Codex CLI, ChatGPT App 或 Codex App2. 完成 Codex 登录3. 双击 CodexBar 主面板中的账户图标刷新4. 仍然未登录时退出并重新打开 CodexBar@@ -44,7 +44,7 @@ CodexBar 优先使用全局 Codex CLI,关于页面的 `当前使用` 标记可| CodexBar Hook 已不完整 | 至少一个必要事件缺少当前 handler | 关闭后重新开启 CodexBar Hook || CodexBar Hook 未被信任 | Codex 仍把 handler 判定为未信任或已修改 | 重新开启 Hook 并检查 Codex 配置 || CodexBar Hook 意外来源 | app-server 返回的来源不是当前配置文件 | 检查 `CODEX_HOME` 和当前 Codex 来源 |-| hooks.json 文件格式错误 | 顶层或 `hooks` 结构不是有效 JSON | 修复 JSON 后重新操作 |+| `hooks.json` 文件格式错误 | 顶层或 `hooks` 结构不是有效 JSON | 修复 JSON 后重新操作 || 无法验证 Codex Hook | app-server 暂时不可用或校验失败 | 查看日志并在 Codex 可用后重新打开设置 |Hook 配置位于 `$CODEX_HOME/hooks.json`,未设置 `CODEX_HOME` 时位于 `~/.codex/hooks.json`@@ -121,7 +121,7 @@ Hook 配置位于 `$CODEX_HOME/hooks.json`,未设置 `CODEX_HOME` 时位于 `~日志窗口保留当前进程最近 500 条 app-server 请求。-每条记录包含请求时间,方法,状态和响应时间,展开后可以查看请求,响应或错误预览。+每条记录包含请求时间、方法、状态和响应时间,展开后可以查看请求、响应或错误预览。完整内容可以在独立窗口中查看或复制,清空或退出 App 后不会恢复。@@ -133,7 +133,7 @@ Hook 配置位于 `$CODEX_HOME/hooks.json`,未设置 `CODEX_HOME` 时位于 `~/usr/bin/log stream --predicate 'subsystem == "app.zabrian.codexbar"' --style compact```-Debug 版本的 subsystem 使用 `.debug` 后缀。+Debug 版本的 `subsystem` 使用 `.debug` 后缀。提交问题时请描述复现步骤和可见错误,分享日志前先检查 App 内交互日志是否包含不希望公开的请求内容。