Skip to content

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

feat: 菜单栏图标区分防休眠状态并发布 3.5.3

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