Skip to content

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

refactor: 收敛共享逻辑并优化同步与 Hook 写入

Bob2189c6495114
diff --git a/AGENTS.md b/AGENTS.md
index 8b5b765..014e325 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,296 +1,126 @@
# AGENTS.md
-本文件是 Codex 在本仓库工作的持久指令。根目录范围内均适用;如果子目录未来出现更近的 `AGENTS.md`, 以更近文件为准。
+本文件面向在本仓库工作的编码代理。优先遵循这里的项目约定;需要更细背景时再阅读 `Docs/` 下的专题文档。
-本文件按 OpenAI GPT-5.5 prompt guidance 的思路组织: 结果优先、约束明确、上下文可追溯、验证轻量但必须执行。不要把它当成逐步脚本机械执行;遇到更直接、安全、可验证的路径时, 选择更高效的做法。
+## 项目概览
-## 目标
+CodexBar 是一个 macOS 15+ 菜单栏应用,使用 Swift 6、SwiftUI + AppKit + MVVM。应用通过本机 Codex app-server 读取账号、额度和 token 用量,通过可选 Codex Hook 记录本机 Codex 工作流事件,并在菜单栏面板、设置窗口和日志窗口中展示状态。
-CodexBar 是一个 macOS 菜单栏应用, 通过本机 Codex app-server 展示当前 Codex 账号、额度、token 用量、Codex CLI/APP 版本和交互日志, 并可通过 Codex Hook 统计本机工作流数据。你的目标是交付可验证、范围清晰、贴合现有 SwiftUI/AppKit/MVVM 架构的修改, 并保护本地认证、隐私、菜单栏体验、Hook 配置、Sparkle 更新和发布流程。
+工程只有一个 Xcode app target:`CodexBar`。当前没有独立测试 target 或 `*Tests*` 目录。
-## 成功标准
+## 重要边界
-- 先明确用户要的结果: 代码修改、文档、诊断结论、review、构建验证或发布操作。
-- 修改范围只覆盖完成目标所需文件; 不顺手重构无关模块, 不回滚他人未提交改动。
-- 行为改变必须能用代码事实、工具输出或用户确认支撑。
-- 涉及 Swift/Xcode 工程、资源、build setting、Info.plist、SwiftPM、脚本行为或 UI 行为的改动后运行构建命令。
-- 纯文档改动可以不构建, 但最终说明实际做过的检查。
-- 最终回复简洁说明改了什么、如何验证、剩余风险或未执行项。
+- 应用是 `LSUIElement` 菜单栏 App,不显示 Dock 图标,也不依赖主窗口。
+- 最低系统版本是 macOS 15.0。
+- App Sandbox 关闭,因为需要启动本机 `codex`、读取用户 Codex 登录状态,并写入用户级 Hook 配置。
+- 除手动重置机会过期时间查询、Sparkle 更新、用户显式开启跨设备同步后的 CloudKit private database 同步外,App 自身不应新增网络请求。
+- Codex 账号、额度、token 用量只在本机处理。Hook 工作流统计默认只写本机文件,跨设备同步只上传 daily 聚合数据,不上传原始事件、会话 ID、轮次 ID、请求日志或认证文件。
+- 不要回滚或清理与当前任务无关的未提交变更;仓库可能处于脏工作树状态。
-## 工作方式
+## Git 规则
-- 默认中文回复, 除非用户要求英文。
-- 先读局部上下文再行动。优先用 `rg` / `rg --files`、当前文件和相邻模块定位事实。
-- 简单、低风险、可逆的请求直接执行。删除、发布、推送、生产写入、覆盖用户选择或行为不确定时先取得明确同意。
-- 独立读取可以并行; 有依赖、会改变文件、或动作不可逆时顺序执行。
-- 工具调用前用一句话说明意图。长任务中持续同步进度, 不把中间状态当最终结果。
-- 需要外部事实时使用可检索来源; 不猜测当前版本、API、文档或政策。若上下文缺失且无法检索, 问最小问题。
-- 修改 prompt、文档或 agent 指令时, 保留仍然准确的项目事实和边界; 删除会改变执行行为的规则前确认它确实过期或冲突。
+- 不要主动 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;简单文档或杂项可只写标题行。
-## 行动安全
+示例:
-执行高影响动作前做轻量 pre-flight:
+```text
+fix: 修复 Codex 状态刷新
-- 说明将要做的动作和关键参数。
-- 通过工具执行。
-- post-flight 确认结果和验证。
+ - 合并设置页 onAppear 和 didBecomeActive 的重复版本探测
+ - 保留当前运行版本与磁盘安装版本不一致时的更新提示
+```
-高影响动作包括: `git push`、tag、release、DMG/appcast 更新、删除文件、改 Xcode build settings、改 Sparkle 配置、改 sandbox/signing、改认证/隐私相关逻辑。
+Tag:
-## 验证
+- tag 名格式 `v{MARKETING_VERSION}`。
+- 使用附注 tag:`git tag -a v{MARKETING_VERSION} -m "Release v{MARKETING_VERSION}"`。
-Swift/Xcode 相关改动后运行:
+## 目录结构
-```bash
-xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination generic/platform=macOS -derivedDataPath /tmp/CodexBarDerivedData build
-```
+- `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。
+- `Docs/`: app-server、Codex Hook、跨设备同步和开发文档。
+- `Scripts/`: Release 构建、公证、DMG 和 Sparkle appcast 发布脚本。
-要求无 error。当前 Xcode 可能输出 `Metadata extraction skipped. No AppIntents.framework dependency found.` 的 metadata warning, 不作为项目代码 warning 处理。SourceKit 对跨文件类型偶尔误报时, 以 `xcodebuild` 为准。
+## 构建与验证
-文档-only 修改至少运行:
+日常编译验证:
```bash
-git diff --check
+xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/platform=macOS' build
```
-提交或发布前再检查:
+也可以直接用 Xcode 打开 `CodexBar.xcodeproj` 运行。
+
+发布相关脚本:
```bash
-git status --short
+Scripts/build.sh
+Scripts/dmg.sh
+Scripts/appcast.sh
```
-## 项目事实
+`Scripts/build.sh` 默认执行 Release archive、导出 Developer ID app、公证、staple 和 Gatekeeper 校验。没有发布凭据或不需要完整发布流程时,不要把它当作普通本地验证命令。
-- 平台: SwiftUI + AppKit + MVVM, 最低 macOS 15.0。
-- 应用形态: `LSUIElement` 菜单栏应用, 无 Dock 图标、无主窗口。
-- 外部依赖: Sparkle(SwiftPM)。
-- 当前 build settings: `MACOSX_DEPLOYMENT_TARGET = 15.0`, `MARKETING_VERSION = 3.2.6`, `CURRENT_PROJECT_VERSION = 34`, `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`, `SWIFT_VERSION = 6.0`。
-- App Sandbox 必须保持关闭(`ENABLE_APP_SANDBOX = NO`), 因为应用要启动本机 Codex CLI/APP 内置 CLI, 并读取真实 macOS 用户的 Codex 登录状态。
-- 工程使用 `PBXFileSystemSynchronizedRootGroup`; 新增或删除 `CodexBar/` 下 Swift 文件通常无需改 `project.pbxproj`。只有依赖、target/build settings 或资源归属变更才改 Xcode 工程文件。
-- Swift 源码按目录组织: `App/`、`Controllers/`、`Models/`、`Services/`、`Views/`。不要把新 Swift 文件直接放回 `CodexBar/` 根层。
-- 不要为 macOS 15 以下添加 SF Symbols 或 SwiftUI API fallback。
+当前没有自动化测试套件。修改后至少跑一次 `xcodebuild ... build`;如果改动涉及菜单面板、窗口焦点、Hook 或同步逻辑,需要手动说明还应覆盖的交互场景。
-## 架构地图
+## Swift 与并发约定
-主要数据流:
+- 项目使用 Swift 6,`SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`。UI 和 ViewModel 默认按 MainActor 思考。
+- 服务共享状态优先使用 `actor` 管理。
+- DTO、纯模型、静态工具、日期/格式化辅助、跨 actor 传递类型应根据需要显式标注 `nonisolated` 或保证 `Sendable` 语义清晰。
+- 不要用阻塞式 I/O 或长耗时操作卡住 MainActor;从服务层异步返回后再回写 UI 状态。
+- 已有防重入和过期结果丢弃逻辑要保留,例如 `RefreshTaskCoordinator` 保护刷新结果只让最新 generation 提交。
+- 注释保持克制,只解释非显然的生命周期、焦点、actor 或系统 API 约束。
-```text
-CodexStatusService(JSON-RPC app-server)
- -> CodexStatusViewModel(@MainActor 状态发布)
- -> StatusItemController(菜单栏图标、菜单面板、窗口入口)
- -> CodexStatusMenuView / AppSettingsView / LogView
-
-Codex Hook
- -> WorkflowHookEventRecorder(--hook-event stdin hook_event_name)
- -> WorkflowStorage(events/YYYY-MM-DD.jsonl / daily.jsonl)
- -> WorkflowService
- -> WorkflowSyncService(可选 CloudKit private database 同步)
- -> WorkflowViewModel
- -> UsageSummaryView / UsageHeatmap
-```
+## UI 与窗口约定
-目录职责:
-
-- `App/`: 入口和全局启动分支。
-- `Controllers/`: 菜单栏、菜单面板、侧边 child panel、设置窗口和日志窗口控制。
-- `Models/`: account、quota、usage、workflow、共享日期网格和错误模型。
-- `Services/`: app-server、Codex CLI、设置、Hook 统计、更新和日志服务。
-- `Views/`: 菜单面板、设置、日志和共享 Liquid Glass 样式。
-
-Hook 统计的配置、存储、保留策略和统计口径见 [Docs/CodexHook.md](Docs/CodexHook.md), 跨设备同步见 [Docs/CrossDeviceSync.md](Docs/CrossDeviceSync.md)。
-
-## app-server 合约
-
-- 详细合约见 [Docs/AppServer.md](Docs/AppServer.md)。
-- 必须通过 `CodexCLIResolver.resolveAppServerCommand()` 解析, 不要绕过 resolver 直接启动。
-- app-server 环境必须使用真实用户 `HOME`、`USER`、`LOGNAME`; 不要改回 Xcode sandbox/container 的 `HOME`。
-- 保留认证失败 refresh token、unsupported method、业务错误重试、stale cache 和连接重建语义。
-- 不要把子进程 stderr、认证文件或原始敏感 RPC 响应展示给用户。
-
-## Codex Hook 合约
-
-- 详细设计见 [Docs/CodexHook.md](Docs/CodexHook.md)。
-- 设置开关只能追加或移除 command 同时包含当前 CodexBar 可执行路径和 `--hook-event` 参数的 Hook 处理器, 不能破坏其他用户 Hook。
-- Hook 命令写入当前 CodexBar 可执行文件路径和 `--hook-event` 参数; Hook 事件名来自 Codex 传入的 stdin payload 顶层 `hook_event_name`。
-- Hook 原始事件和本机 daily 聚合保存在 `~/Library/Application Support/CodexBar/HookEvents/`; 用户开启「跨设备同步」后, 仅脱敏 daily 聚合副本会同步到当前 iCloud 账号的 CloudKit private database。
-- Hook 写入可能并发触发, 追加 `events/YYYY-MM-DD.jsonl` 并更新 `maintenance.json` 时必须通过 `stats.lock` 加锁。
-
-## UI 状态与日志
-
-- app-server 状态和请求日志规则见 [Docs/AppServer.md](Docs/AppServer.md)。
-- UI 只展示「未登录」和「初始化失败」两类特殊状态; 具体请求错误、启动错误、超时、断连、解析失败都进入日志。
-- 日志窗口状态标签为「进行」「完成」「错误」「请求」。
-
-## 数据模型
-
-`CodexQuotaSnapshot`:
-
-- 必须有 `AccountReadResponse.account`, 否则视为未登录。
-- `rateLimitsResponse` 和 `usageResponse` 都可以为空; 账户有效时仍生成快照, UI 展示「暂无数据」。
-- `isRateLimitsStale` / `isUsageStale` 标记额度或 token 区域是否来自同账号旧缓存; 本轮对应接口成功后重新生成 snapshot 并恢复为 `false`。
-- 优先读取 `rateLimitsByLimitId`; 为空时回退顶层 `rateLimits`。
-- 顶层 `rateLimits.limitId` 指向的主 limit 置顶, 缺省 `"codex"`。
-- `codexLimit` 返回 `limitId` 大小写不敏感等于 `"codex"` 的第一个 limit, 供菜单栏额度指示选择窗口使用。
-- 其余 limit 按 `limitName ?? limitId` 做 localized standard 排序, 再按 `limitId` 稳定排序。
-- `rateLimitResetCredits.availableCount` 读入 `resetCreditsAvailableCount`; 缺失时为 `nil`。
-- `resetCreditsAvailableCount > 0` 时, 主 App 可使用本机 Codex OAuth token 请求 `https://chatgpt.com/backend-api/wham/rate-limit-reset-credits`; 401/403 时复用本轮认证刷新预算重试; 只保留可用且未过期的 `credits[].expires_at` 到 `resetCreditExpirationDates`, 请求失败时为 `nil`, 重置次数侧边详情面板显示未知过期时间。
-- `primary` / `secondary` 合成 `[QuotaWindow]`; 没有窗口的 limit 被过滤。
-- `QuotaWindow.remainingPercent = clamp(100 - usedPercent, 0...100)`; 无 `usedPercent` 视为无数据。
-- `windowDurationMins` 标签: 整天 `ND`, 整小时 `NH`, 否则 `NM`, 缺失或非正数为「额度」。
-
-`CodexUsageSnapshot`:
-
-- `recentWeekGrid(columnCount:endingDaysAgo:today:)` 基于本地当天零点生成按周排列的日期网格, 每列从周日开始。
-- UI 使用 30 列、7 行; Hook 开启或 app-server 已返回当天 token bucket 时包含今天, 否则不包含今天。
-- `nil` 表示未来日期或不可生成日期; 热力图不绘制方块也不参与峰值计算。
-
-工作流统计:
-
-- 统计口径、字段兼容和保留策略见 [Docs/CodexHook.md](Docs/CodexHook.md)。
-- UI 展示字段为「会话总数」、「对话轮次」、「子智能体」、「工具调用」、「权限请求」、「上下文压缩」。
-
-## 并发与隔离
-
-工程开启 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`; 未显式标注的类型会推断为 MainActor 隔离。
-
-- UI 层保持 `@MainActor`: app delegate、status item controller、window controllers、view models、settings/updater。
-- 服务层对外暴露 async API, 共享可变状态优先由 actor 隔离。
-- 非 UI 类型、DTO、模型、服务辅助类型和静态工具需要显式 `nonisolated`, 避免 main actor 隔离泄漏到同步服务代码。
-- `CodexStatusService` 是 actor, 负责 app-server 连接、缓存和重建。
-- `CodexCLIVersionService` 是 actor, 全局和内置版本探测用 `async let` 并发启动; 子进程输出通过 `PipeReadBuffer` 收集。
-- `WorkflowService` 是 actor, 串行维护和读取 workflow 快照。
-- `WorkflowSyncScheduler` 是维护/同步任务的唯一调度者, 合并自动维护、同步开关、Hook 重新开启和同步可用性恢复触发的请求; `WorkflowViewModel.refreshMaintenance(synchronize:)` 只执行一次明确的维护刷新并发布快照。
-- `RequestLogStorage` 可从后台同步写入, 用 `OSAllocatedUnfairLock` 保护; `@MainActor RequestLogStore` 只负责发布 SwiftUI 快照。
-- `PipeReadBuffer` 是底层 `FileHandle`、`DispatchSourceRead` 和 semaphore 的唯一 `@unchecked Sendable` 边界, 读队列 `CodexBar.pipe-read` 使用 `.userInitiated` QoS。
-- Hook 写入可能由多个 Codex 进程并发触发, 必须通过 `stats.lock` 和 `flock` 保护 `events/YYYY-MM-DD.jsonl` 和 `maintenance.json` 的一致性; `daily.jsonl` 由主 App 刷新维护流程写回。
-
-## UI 约束
-
-菜单栏:
-
-- 正常图标是 `person.fill.checkmark`, 错误图标是 `person.fill.xmark`。
-- 菜单栏不展示额度数字; 详情只在菜单面板中展示。
-- 设置页「菜单栏额度指示」默认开启, 使用独立开关控制启用状态; 缺失持久化选择时默认使用 `.primary`, 关闭时必须显式持久化 `.off`。开启后同一行显示额度窗口菜单, 选项来自当前账号 Codex limit 返回的窗口, 当前保留选择不在返回窗口中时用 fallback 标题追加到菜单。关闭开关时设置页保留最后一个非关闭窗口值参与菜单淡出, 避免过渡期间回退到默认窗口。关闭时菜单栏只展示原图标, 开启时将所选 Codex 窗口剩余额度进度条绘制在 `person.fill.checkmark` / `person.fill.xmark` 图标左侧, 以竖条形式作为单个菜单栏图像自动随状态刷新; 合成图尺寸为 `27 x 17`, 图标本体保持原始 `24 x 17`, 左侧竖条轨道为 `2 x 15`; 开启或关闭时竖条透明度做 0.18 秒过渡, 过渡期间合成图宽度和图标绘制坐标保持固定。
-- 左键或全局快捷键切换菜单面板; 右键或 Control 点击显示「设置 / 日志 / 退出」; 系统应用设置命令 `⌘,` 转交给自定义设置窗口。
-- 上下文菜单由 `NSStatusBarButton.performClick(nil)` 触发; 设置和日志菜单项 action 需要等 `NSMenuDelegate.menuDidClose(_:)` 确认菜单结束并清空 `statusItem.menu` 后再打开窗口, 避免键盘等效键在 `NSMenu` tracking 期间打开窗口导致无法激活到最前。
-- 菜单面板打开时按 `⌘L` 会立即关闭菜单面板并打开日志窗口; 只响应精确 Command-L, 不响应额外修饰键组合。
-- 全局快捷键打开菜单面板前必须短暂禁止设置窗口和日志窗口成为 key window, 避免已有设置/日志窗口被 App 激活一起带到前台; 随后校验当前 status item 锚点可信。锚点无 window、无有效 screen、按钮隐藏、bounds 为空、屏幕矩形异常, 或屏幕矩形没有落在目标屏幕范围内时, 使用无箭头 fallback `NSPanel` 在目标屏幕顶部居中打开。目标屏幕优先取鼠标所在屏幕, 找不到时取主屏幕。快捷键关闭已打开的菜单面板不受此校验影响。
-- 设置和日志辅助窗口为 `.normal` level, 打开时先恢复 key focus, 再 `orderFrontRegardless()`, `NSRunningApplication.current.activate(options: [])` 和 `makeKeyAndOrderFront(nil)` 一次性置前; 不改用 `NSApplication.shared.activate()`, 避免 LSUIElement App 首次懒创建窗口时无法稳定拉到最前。
-
-菜单面板:
-
-- `CodexStatusMenuView.menuWidth` 由热力图宽度和 padding 推导; 改热力图尺寸时同步检查弹窗宽度。
-- 外层和分区使用 `.liquidGlassSurface(...)`; 分隔线使用 `LiquidGlassDivider`; 小徽章可用 `.liquidGlassCapsule(...)`。
-- `LiquidGlassStyle.swift` 是自绘玻璃效果, 不是 macOS 原生 `.glassEffect`; 没有明确设计要求时不要切换。
-- 账号图标双击触发刷新。邮箱文本双击切换模糊。
-- 计划名是右侧加粗纯文字; `planBadgeTint(for:)` 优先级: enterprise -> team/business -> pro -> plus -> edu -> free -> 默认 cyan。
-- `resetCreditsAvailableCount > 0` 时, 只在置顶主 limit 标题右侧显示 `重置次数: N`; 该控件是 plain button, 点击后通过 `ResetCreditsPanelController` 切换重置次数侧边详情面板。面板按升序逐行展示 `yyyy-MM-dd HH:mm:ss` 和 `可用: N`, 相同展示时间合并数量, 单个显示 `可用: 1`; 多行之间显示渐变分隔线; 没有过期时间时显示「未知过期时间」。
-- 重置次数侧边详情面板是菜单面板的 borderless nonactivating child panel, 可接收鼠标事件但不能成为 key/main window; 与菜单面板 gap 为 `4`, 屏幕边缘保留 `8` px, 内容宽 `147`, 最小高 `62`, 无可用锚点时最大高回退为 `260`, 有可用锚点时按额度区顶部到菜单面板底部的可用空间夹紧, 圆角 `12`; 锚点坐标异常或与当前菜单内容区域不相交时丢弃并改为居中对齐菜单面板; 展开 `0.18` 秒、收起 `0.12` 秒。点击面板内部不关闭菜单面板, 点击外部关闭; 与热力图详情面板互斥, 任一面板显示时会立即隐藏另一面板。
-- 额度条展示剩余百分比, 固定为 50 个胶囊, 每个胶囊宽 `3.5`, 间距 `2`, 高 `12`; 颜色按 20% 一档: 红、橙、黄、薄荷、绿。
-- 额度行标签列宽 `34`, 居中显示, 标签允许最小缩放到 `0.75`, 标签到额度条间距 `12`, 额度条到百分比间距 `8`, 百分比列宽 `37`, 百分比到重置时间最小间距 `6`, 重置时间列宽 `75`; 不通过加宽菜单面板解决额度行溢出。
-- 无 quota 数据时显示 `--` / `暂无数据`, 并使用占位色。
-- `rateLimits` 或 `usage` 使用旧缓存时, 对应区域通过 `.markStale(true)` 降低透明度到 0.55, 不降低饱和度; 下一轮对应接口成功后恢复正常透明度。
-- 重置时间格式是 `MM-dd HH:mm`, 使用等宽数字, 在额度行最右侧对齐。
-- 更新时间行显示倒计时圆环、「数据更新时间」和 `HH:mm:ss`。
-- 更新时间行最右侧显示同步状态图标: 只有 Codex Hook 开启、跨设备同步偏好开启且同步账号可用时才进入 active 同步态; 非 active 同步统一为 `icloud.slash`, tooltip 为「同步未开启」; active 空闲为 `icloud`, tooltip 显示 `最近同步: yyyy-MM-dd HH:mm:ss`, 时间来源和设置页「最近同步」一致, 没有成功上传记录时显示「暂无同步记录」; active 同步中为 `arrow.trianglehead.clockwise.icloud`; active 同步失败为 `exclamationmark.icloud`, tooltip 展示归类后的同步错误文案。
-- 倒计时只在菜单面板可见时用 `TimelineView` 每秒 tick; 普通 tick 不做连续动画, 仅刷新起点变化时播放恢复动画。
-- token 区域显示「单日峰值」和「全时累计」; `TokenCountText` 对 1K 以下显示完整整数, 1K 起显示 K/M/B。
-- token 区域还显示「当前连胜」、「最长连胜」和「最长任务」。
-- 热力图是近 30 周、30 列 x 7 行、周日到周六排列; Codex Hook 开启时包含今天, Hook 关闭时仅在 app-server 已返回当天 token bucket 时包含今天。
-- 热力图 hover 使用 `HeatmapDetailPanelController` 展示侧边详情面板, 不是菜单面板内 tooltip; 面板作为菜单面板 child window, 不接收鼠标事件, 左右贴边展示并在屏幕可见区域内夹紧。热力图详情面板和重置次数详情面板都被 `MenuSurfaceDismissMonitor` 视为允许点击区域。
-- 热力图详情面板和重置次数详情面板共用 `SidePanelSupport.swift` 中的 `NonactivatingSidePanel`、`SidePanelDrawerAnimator` 和定位/挂载/layer 辅助逻辑; 修改 child panel attach/orderOut、抽屉动画、圆角 layer 或左右定位语义时必须同步检查两个控制器。
-- 详情面板内容更新时保留 `NSPanel` / `NSHostingController`, 但每次替换 `hostingController.rootView` 并同步 `setContentSize`; 不用常驻 `ObservableObject` model 推送 hover context, 避免 Hook 开关切换 token-only / workflow 布局后触发 AppKit 递归布局。
-- Hook 关闭时详情面板显示日期、token 数和「用量强度」分段条, 尺寸 `212 x 84`。
-- Hook 开启时详情面板首行左侧显示日期、右侧显示 token 数, 当天 token 数显示 `--`; 后续显示「用量强度」、「会话总数」、「对话轮次」、「子智能体」、「工具调用」、「权限请求」、「上下文压缩」, 尺寸 `212 x 189`。
-- 「用量强度」前置圆点固定为蓝色, 不随用量强度变化。
-- 工作流统计只展示在用量热力图详情面板中, 不再有单独的工作流统计区。
-
-设置窗口:
-
-- 通过右键菜单「设置」或系统应用设置命令 `⌘,` 打开独立 `AppSettingsView` 窗口。
-- 不要恢复为 Option 点击或菜单面板内设置区。
-- 设置页包含「菜单栏额度指示」、「使用快捷键」行、「CodexBar 版本」和「Codex 版本」区域。
-- 设置窗口按 SwiftUI 内容自适应高度时必须校验 `fittingSize` 有限并夹紧到安全上限; 设置页 `onAppear` / `didBecomeActive` 中触发的设置刷新不得同步发布 `@Published` 变化。
-- `Codex CLI` 行图标用 `terminal`; `Codex APP` 行图标用 `app.badge`。
-- 当前运行来源显示「当前使用」。
-- 当前行优先展示 app-server 握手自报版本; 非当前行展示磁盘安装版本。
-- 当前运行版本与磁盘安装版本不同时, 显示「已更新至 <version>」。
-- 路径点击复制到剪贴板, 对应来源显示「已复制」1.5 秒; 保留路径文本布局宽度避免跳动。
-- 默认全局快捷键是 `⌘⇧W`; 快捷键录制至少需要两个修饰键, 不允许 Command-Space 或 Command-Tab; 注册冲突、无法识别和校验错误显示在快捷键行内。
-- 设置页包含「启用 Codex Hook」开关; 开启后会写入全局 Codex Hook 配置, 用于近 30 周数据展示更多本机统计数据。
-- 开启 Codex Hook 前必须通过当前 `CodexStatusService` app-server 会话调用 `config/read`, 如果 Codex 全局配置禁用了 Hook, 则不写入 `hooks.json`, 开启失败并在 Hook 选项下方提示。
-- 开启 Codex Hook 写入 `hooks.json` 后必须通过当前 app-server 会话调用 `hooks/list` 验证 `command`、`eventName`、`enabled`、`sourcePath`、`trustStatus`、`warnings` 和 `errors`; 未信任或已修改时, 只对来源为全局 `hooks.json` 且 command 属于当前 CodexBar 的 Hook 通过 `config/batchWrite` 自动写入 `hooks.state` 的 `trusted_hash`, 再重新验证。
-- Codex Hook 开关下方只在必要时显示 Hook 相关错误; 不展示固定说明文案、启用状态或关闭状态文案。
-- 设置页包含「跨设备同步」开关; 仅在 Codex Hook 开启且 CloudKit account status 为 available 时可操作。同步账号不可用时开关禁用, 并在开关下方显示「同步不可用」。
-- 「跨设备同步」开启后, 主 App 在工作流统计维护刷新中把脱敏 daily 聚合按日期稳定排序、每批最多 25 天、每轮最多 20 秒上传到 CloudKit; 已成功上传的日期立即写入本地 `state.json`, 剩余日期留给后续刷新继续。
-- 开机启动错误显示在设置组与底部按钮组之间的独立错误组; 无错误时不展示该组, 退出和检查更新按钮之间不展示错误文案。
-
-日志窗口:
-
-- 通过右键菜单「日志」打开。
-- 日志窗口应持续显示全局 `RequestLogStorage.shared` 中的记录, 通过 `@MainActor RequestLogStore.shared` 发布到 SwiftUI, 不因窗口关闭丢失。
-- `RequestLogEntry` 保存完整 request/detail; 列表摘要和行内展开只显示单行短预览, 非空请求/响应标题行提供预览和复制完整内容; 预览视图对 JSON 做格式化和高亮。
-
-## Sparkle 更新
-
-- `AppUpdater` 是 `@MainActor ObservableObject`。
-- 初始化时先校验 `SUFeedURL`(http/https) 和 `SUPublicEDKey`(非空)。
-- 任一缺失时不创建 `SPUStandardUpdaterController`, 更新操作显示「未配置更新资源」。
-- `canConfigureAutomaticChecks` 是 `updaterController != nil`。
-- `settingsStatusMessage` 用于设置窗版本行, 默认 3 秒后清空。
-- `panelUpdateMessage` 用于菜单面板底栏被动提示, 双击触发 `startUpdate()`。
-- `availableUpdateMessage` 驱动设置窗版本行和「立即更新」按钮。
-- 手动检查结果进 `settingsStatusMessage`; 自动发现新版进 `panelUpdateMessage`。
-- 当前 `SUFeedURL = https://codexbar.zabrian.app/appcast.xml`, `SUScheduledCheckInterval = 3600`。
-
-## 认证、隐私与沙盒
-
-- CodexBar 主要通过本机 Codex app-server 读取账号、额度和 token 使用量; 为展示手动重置机会过期时间, 可使用本机 Codex OAuth token 向 `https://chatgpt.com/backend-api/wham/rate-limit-reset-credits` 发起只读请求, 只保留可展示的过期时间数组。
-- Codex Hook 工作流统计默认只写入本机 `~/Library/Application Support/CodexBar/HookEvents/`; 用户开启「跨设备同步」后, CloudKit 只保存去掉 `sessionIds` / `turnIds` 的 daily 聚合副本, 不保存原始 Hook events。
-- 除手动重置机会过期时间查询、Sparkle appcast/DMG 下载, 以及用户显式开启「跨设备同步」后的 CloudKit private database 请求外, 应用自身不做网络请求。
-- App Sandbox 必须保持关闭。
-- app-server 和版本探测必须使用真实用户 home。
-- 不要把 Codex auth 文件、stderr、原始敏感 RPC 响应或用户路径之外的敏感信息写入 UI、文档或测试夹具。
-
-## 发布脚本
-
-- `Scripts/build.sh [options] [Output.app]` 生成 Developer ID App, 默认输出 `build/CodexBar.app`; 成功校验最终 App 后清理 `build/` 下 archive、DerivedData 等中间产物, 默认只保留 `.app`; 构建、notary 或校验失败时保留中间产物便于排查。
-- `Scripts/dmg.sh [App.app] [Output.dmg]` 创建带 `/Applications` Finder alias 的 DMG, 会尝试写 Finder 布局。
-- `Scripts/appcast.sh [CodexBar-vX.Y.Z.dmg]` 更新 `appcast.xml`, 需要 Sparkle `sign_update`。
-- 改发布脚本后至少运行对应脚本的 `bash -n`; 改 DMG 或 appcast 脚本后还要运行 `bash -n Scripts/dmg.sh` 和 `bash -n Scripts/appcast.sh`。
-- 更新 appcast、tag、push、上传 DMG 都必须先得到用户明确同意。
+- 菜单栏按钮左键切换主面板;右键或 Control+点击打开上下文菜单。
+- `⌘,` 打开自定义设置窗口;菜单面板打开时 `⌘L` 打开日志窗口。
+- 默认全局快捷键是 `⌘⇧W`,由 `GlobalHotKeySettings` 和 `GlobalHotKeyController` 管理。
+- 主菜单面板可能通过 `NSPopover` 锚定 status item,也可能在锚点不可信时使用 fallback `NSPanel`。处理快捷键、屏幕选择和焦点时要保留这些分支。
+- 设置窗口和日志窗口复用 `HostingWindowController` / `AuxiliaryHostingWindow` 行为。它们可以成为 key window,但不应成为 main window。
+- 侧边详情面板共享 `SidePanelSupport.swift` 的定位、动画、挂载和 chrome 行为;新增侧边面板能力时优先复用共享支持代码。
+- 保持现有 Liquid Glass 视觉风格,避免引入与系统菜单栏工具不一致的重装饰 UI。
-## Git 规则
+## Hook、同步与数据文件
-- 不要主动 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; 简单文档或杂项可只写标题行。
-
-示例:
+- Hook 子进程入口在 `CodexBarApp.init()` 中最先调用 `WorkflowHookEventRecorder.handleIfRequested()`;Hook 模式要快速读取 stdin 并退出,不进入普通 App 启动流程。
+- CodexBar 只追加或移除属于当前 CodexBar 可执行文件的 Hook 处理器,不应删除用户已有的其他 Codex Hook。
+- 本机 Hook 事件默认写入:
```text
-fix: 修复 Codex 状态刷新
-
- - 合并设置页 onAppear 和 didBecomeActive 的重复版本探测
- - 保留当前运行版本与磁盘安装版本不一致时的更新提示
+~/Library/Application Support/CodexBar/HookEvents/
```
-Tag:
+- 跨设备同步依赖用户开启 Codex Hook 且 iCloud 可用;只同步脱敏 daily 聚合行。同步范围变更时必须同时更新 `Docs/CrossDeviceSync.md`。
+- Hook 事件口径、字段或聚合方式变更时必须同步更新 `Docs/CodexHook.md`。
+
+## 文档同步
-- tag 名格式 `v{MARKETING_VERSION}`
-- 使用附注 tag: `git tag -a v{MARKETING_VERSION} -m "Release v{MARKETING_VERSION}"`
+涉及这些行为时,需要更新对应文档:
-## 最终检查
+- 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 76d7fa8..9a38004 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,79 +2,121 @@
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-> 本仓库已有一份详尽的 `AGENTS.md`,它是 app-server / Codex Hook / UI / 数据模型 / 发布 / Git 等各项合约的**权威来源**。本文件只做精炼导航,遇到具体行为约束请优先查 `AGENTS.md`、`Docs/AppServer.md`、`Docs/CodexHook.md` 与 `Docs/CrossDeviceSync.md`,不要凭记忆推断。
+## 项目概述
-## 构建与验证
+CodexBar 是一个 macOS 菜单栏应用 (`LSUIElement`, 无 Dock 图标),用于展示本机 Codex 的账号状态、额度、Token 用量和工作流统计。技术栈: Swift 6 + SwiftUI + AppKit + MVVM,唯一外部依赖是 Sparkle (SwiftPM)。最低系统版本 macOS 15.0,App Sandbox 保持关闭(需要启动本机 `codex` 进程并写入用户级 Hook 配置)。
-涉及 Swift/Xcode 工程、资源、build setting、Info.plist、SwiftPM、脚本或 UI 行为的改动后必须运行构建,要求无 error 和 warning:
+## 常用命令
```bash
-xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination generic/platform=macOS -derivedDataPath /tmp/CodexBarDerivedData build
+# 构建(唯一 scheme 是 CodexBar,无测试 target)
+xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/platform=macOS' build
+
+# 格式化(配置在 .swiftformat,Swift 6 语言模式、4 空格缩进)
+swiftformat .
+
+# Lint(配置在 .swiftlint.yml,只检查 CodexBar/ 目录)
+swiftlint
+
+# 发布脚本
+Scripts/build.sh # archive + Developer ID 导出 + notarize
+Scripts/dmg.sh # 打包 DMG
+Scripts/appcast.sh # 签名并更新 Sparkle appcast
```
-- 没有测试 target;不存在单测可跑,验证以构建通过为准。
-- `Metadata extraction skipped. No AppIntents.framework dependency found.` 是预期 warning,不算项目代码 warning。
-- SourceKit 对跨文件类型偶有误报(新建文件时尤其明显),以 `xcodebuild` 结果为准,不要据此回退正确改动。
-- 纯文档改动只需 `git diff --check`。
-- 发布脚本改动后至少 `bash -n Scripts/dmg.sh` / `bash -n Scripts/appcast.sh`。
+本仓库没有测试 target;验证改动依靠构建通过 + 实际运行。
-## 工程约定(影响如何改代码,非显而易见)
+## Git 规则
-- **App Sandbox 必须保持关闭**(`ENABLE_APP_SANDBOX = NO`):应用要启动本机 Codex CLI 并读取真实用户的 Codex 登录状态。
-- app-server 与版本探测**必须使用真实用户 `HOME`/`USER`/`LOGNAME`**,不能回退到 Xcode sandbox/container 的 home。
-- 工程使用 `PBXFileSystemSynchronizedRootGroup`:新增/删除 `CodexBar/` 下的 Swift 文件**通常无需改 `project.pbxproj`**;只有依赖、target/build settings、资源归属变更才动工程文件。仅 `Resources/Info.plist` 在同步组里被排除。
-- 源码按目录分层:`App/` `Controllers/` `Models/` `Services/` `Views/`。新文件放入对应子目录,不要丢回 `CodexBar/` 根层。
-- `SWIFT_VERSION = 6.0`,并开启 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`:未标注的类型会被推断为 MainActor 隔离。UI 层保持 `@MainActor`;**DTO、模型、服务辅助类型、静态工具必须显式 `nonisolated`**,否则 main actor 隔离会泄漏进同步的服务代码。
-- 最低 macOS 15.0;不要为 15 以下添加 SF Symbols 或 SwiftUI API 的 fallback。
+基本约束:
-## 架构(两条独立数据流)
+- 不要主动 push,除非用户明确要求。
+- 不要回滚、覆盖或丢弃不是你产生的未提交改动。
+- 被要求提交时,**禁止**顺带修改任何文件内容:不做格式化、不做清理、不补文档,只把当前已有改动原样提交。
-应用是 `LSUIElement` 菜单栏程序(无 Dock 图标、无主窗口),入口 `CodexBarApp` 在启动时先分流:若启动参数包含 `--hook-event`,则走 `WorkflowHookEventRecorder` 尝试记录 Hook 事件并立即退出;否则正常起 UI。
+Commit message 格式: Conventional Commits 前缀 + 中文标题,需要 body 时空一行后写 4 空格缩进的 bullet。
-**1. 状态/额度流**(实时数据)
+- 标题格式 `<type>: <中文描述>`,不加句号;常用 type: `feat`、`fix`、`chore`、`refactor`、`docs`。
+- 功能、修复、发布类提交必须写 body;简单文档或杂项改动可只写标题行。
+- body 中多条 bullet 连续排列,bullet 之间不空行。
+- 用命令行提交时,完整 body 放在同一个 `-m` 参数里或用 `git commit -F` 传文件,不要为每条 bullet 单独 `-m`。
-```
-CodexStatusService (JSON-RPC over `codex app-server --listen stdio://`)
- → CodexStatusViewModel (@MainActor 发布 CodexLoadState / CodexQuotaSnapshot)
- → StatusItemController (菜单栏图标、popover、设置/日志窗口入口)
- → CodexStatusMenuView / AppSettingsView / LogView
+示例:
+
+```text
+fix: 修复 Codex 状态刷新
+
+ - 合并设置页 onAppear 和 didBecomeActive 的重复版本探测
+ - 保留当前运行版本与磁盘安装版本不一致时的更新提示
```
-- app-server 启动命令统一由 `CodexCLIResolver.resolveAppServerCommand()` 解析(优先全局 `codex`,否则回退 Codex.app 内置 CLI),**不要绕过 resolver**。
-- 握手与读取顺序、超时/重连、token 刷新、stale 缓存等约束见 `Docs/AppServer.md` 与 `AGENTS.md` 的「app-server 合约」。
-- 错误处理哲学:UI 只暴露 `notLoggedIn` / `initializationFailed` 两类特殊状态;所有具体请求/启动/超时/解析错误进 `RequestLogStorage.shared`(容量 500,完整保存 request/detail),日志窗口通过 `@MainActor RequestLogStore.shared` 订阅快照,列表/行内只展示单行短预览,非空请求/响应标题行提供完整预览和复制,预览视图会格式化并高亮 JSON,不直接展示子进程 stderr。
+Tag:
-**2. Codex Hook 工作流统计流**(本机统计,可选 iCloud 脱敏同步)
+- tag 名格式 `v{MARKETING_VERSION}`(版本号从 Xcode build settings 读取)。
+- 使用附注 tag: `git tag -a v{MARKETING_VERSION} -m "Release v{MARKETING_VERSION}"`。
-```
-WorkflowHookEventRecorder (--hook-event stdin hook_event_name 子进程)
- → WorkflowStorage (events/YYYY-MM-DD.jsonl / daily.jsonl,~/Library/Application Support/CodexBar/HookEvents/)
- → WorkflowService → WorkflowSyncService(可选 CloudKit private database) → WorkflowViewModel
- → UsageSummaryView / UsageHeatmap (统计只在热力图侧边详情面板中展示)
-```
+## 架构总览
+
+详细流程(含时序图、错误处理矩阵、UI 尺寸常量)见 `Docs/DevelopmentGuide.md`,这是最权威的参考。协议细节见 `Docs/AppServer.md`(app-server JSON-RPC 合约)、`Docs/CodexHook.md`(Hook 统计口径)、`Docs/CrossDeviceSync.md`(CloudKit 同步链路)。
+
+### 启动分流(关键设计)
+
+入口 `CodexBar/App/CodexBarApp.swift` 的 `init()` 最先调用 `WorkflowHookEventRecorder.handleIfRequested()`:
+
+- 带 `--hook-event` 参数启动 → Hook 子进程模式:从 stdin 读 JSON payload,在 `flock` 锁内追加一行 JSONL 后立即退出,绝不初始化菜单栏 UI。写入失败静默吞掉,不阻断 Codex。
+- 普通启动 → `CodexBarAppDelegate` 创建长期对象(`CodexStatusViewModel`、`WorkflowViewModel`、各 Settings、`AppUpdater`),由 `StatusItemController.install()` 装配菜单栏。
+
+### 两条主数据链路
+
+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 聚合。
+
+### 并发与隔离
+
+工程开启 `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` 复用它)
+
+### 错误处理原则
+
+- 菜单面板只暴露三种结果(`CodexFetchOutcome`):有数据、未登录、初始化失败;启动失败/超时/断连/解析失败等细节全部只进请求日志窗口(`RequestLogStorage`,上限 500 条)
+- 账号有效时 rate limits 和 usage 允许单独失败:复用同账号旧缓存并标记 stale(UI 半透明),无缓存则该区域不显示
+- Hook 子进程任何失败都静默退出,优先保证不拖慢 Codex
+
+### 菜单面板与侧边面板
+
+- 菜单面板是 `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 递归
+
+### 修改 Hook 配置的约束
-- Hook 命令写入当前 CodexBar 可执行文件路径和 `--hook-event` 参数,事件名来自 Codex 传入的 stdin payload 顶层 `hook_event_name`。
-- 开启 Hook 前必须通过当前 app-server 会话调用 `config/read`,如果全局配置禁用了 Hook,则不写入 `hooks.json`,并在 Hook 选项下方提示。
-- 开启 Hook 写入后必须通过当前 app-server 会话调用 `hooks/list` 验证 `command`、`eventName`、`enabled`、`sourcePath`、`trustStatus`、`warnings` 和 `errors`;未信任或已修改时, 只对来源为全局 `hooks.json` 且 command 属于当前 CodexBar 的 Hook 通过 `config/batchWrite` 自动写入 `hooks.state` 的 `trusted_hash`, 再重新验证。
-- 设置开关只能追加/移除 `command` 同时包含当前 CodexBar 可执行路径和 `--hook-event` 参数的 Hook 处理器,绝不破坏其他用户 Hook。若用户自定义 Hook 命令也同时包含当前可执行路径和 `--hook-event` 参数,会被视为当前 CodexBar 处理器。
-- Hook 写入可能由多个 Codex 进程并发触发,追加 `events/YYYY-MM-DD.jsonl` 并更新 `maintenance.json` 必须经 `stats.lock` + `flock` 加锁;`daily.jsonl` 由主 App 刷新维护流程写回。
-- iCloud 跨设备同步只上传去掉 `sessionIds` / `turnIds` 的 daily 聚合副本;同步账号不可用时设置页禁用「跨设备同步」并显示「同步不可用」。
-- 字段兼容、保留策略、统计口径见 `Docs/CodexHook.md`;跨设备同步完整链路见 `Docs/CrossDeviceSync.md`。
+`~/.codex/hooks.json` 的读写在 `CodexHookSettings`:只识别并移除 command 同时包含「当前 CodexBar 可执行路径 + `--hook-event`」的 handler,必须保留用户已有 Hook、其他 App 的 Hook 和同事件下的其他 handler。写入前需通过 app-server `config/read` 确认全局未禁用 Hook,写入后用 `hooks/list` 验证。
-## 并发分工
+## 隐私与数据边界
-服务层对外暴露 async API,主要共享状态由 actor 隔离:`CodexStatusService` 管理 app-server 连接和缓存,`CodexCLIVersionService` 用 `async let` 并发探测全局/内置版本,`WorkflowService`(actor)串行维护本机统计、`WorkflowStorage`(`nonisolated enum`,与服务同文件)封装 HookEvents 目录与 `stats.lock`。工作流维护/同步刷新的并发由 `WorkflowSyncScheduler`(MainActor,冷却合并 + `isRunning` 串行)单点裁判;`WorkflowViewModel` 不自判维护并发,只执行一次明确的维护刷新(quick-refresh 路径仍走自身 `isRefreshing` + `RefreshTaskCoordinator`,不经 scheduler)。`RequestLogStorage` 可后台同步写入并用 `OSAllocatedUnfairLock` 保护,`RequestLogStore` 只在 MainActor 发布 SwiftUI 快照。`PipeReadBuffer` 是底层 `FileHandle` / `DispatchSourceRead` / semaphore 的唯一 `@unchecked Sendable` 边界。
+改动涉及网络或日志时必须遵守:
-热力图详情和重置次数详情的 nonactivating child panel、抽屉动画、child window 挂载、圆角 layer 和左右定位共用 `CodexBar/Controllers/SidePanelSupport.swift`;两个具体 controller 主要保留各自的触发、内容尺寸、锚点校验、状态编排和互斥状态。
+- 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 用量
-## 外部依赖与更新
+## 目录职责
-- 唯一外部依赖:Sparkle(SwiftPM)。
-- `AppUpdater` 初始化先校验 `SUFeedURL` 与 `SUPublicEDKey`,缺失则不创建 updater 并提示「未配置更新资源」。当前 `SUFeedURL = https://codexbar.zabrian.app/appcast.xml`。
-- 发布:`Scripts/build.sh` 生成 Developer ID App, 成功后 `build/` 默认只保留最终 `.app`; `Scripts/dmg.sh` 打 DMG;`Scripts/appcast.sh` 更新 `appcast.xml`(需 Sparkle `sign_update`)。tag、push、上传 DMG、改 appcast **均需用户明确同意**。
+| 目录 | 职责 |
+| ----------------------- | -------------------------------------------------------------- |
+| `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 发布脚本 |
-## Git
+## 文档同步
-- 不主动 push;不回滚/覆盖非自己产生的未提交改动;提交时只提交当前代码、不附带额外改动。
-- 提交信息:Conventional Commits 前缀 + 中文标题(`<type>: <描述>`,无句号),功能/修复/发布类需写 body(空行后 4 空格缩进 bullet,bullet 间不空行,整段 body 放进同一个 `-m` 或用 `git commit -F`)。type 常用 `feat`/`fix`/`chore`/`refactor`/`docs`。
-- tag 格式 `v{MARKETING_VERSION}`,使用附注 tag。
+改动涉及流程、错误处理、UI 常量或数据边界时,同步更新 `Docs/DevelopmentGuide.md` 中对应章节;协议或统计口径变化时更新 `Docs/AppServer.md` / `Docs/CodexHook.md` / `Docs/CrossDeviceSync.md`。
diff --git a/CodexBar.xcodeproj/project.pbxproj b/CodexBar.xcodeproj/project.pbxproj
index cf759a8..2e4c12f 100644
--- a/CodexBar.xcodeproj/project.pbxproj
+++ b/CodexBar.xcodeproj/project.pbxproj
@@ -282,7 +282,7 @@
"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";
CODE_SIGN_STYLE = Automatic;
COMBINE_HIDPI_IMAGES = YES;
- CURRENT_PROJECT_VERSION = 37;
+ CURRENT_PROJECT_VERSION = 38;
DEAD_CODE_STRIPPING = YES;
DEVELOPMENT_TEAM = 4KJ362VJW5;
ENABLE_APP_INTENTS_METADATA_GENERATION = NO;
@@ -298,7 +298,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
- MARKETING_VERSION = 3.2.9;
+ MARKETING_VERSION = 3.2.10;
PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar;
PRODUCT_NAME = "$(TARGET_NAME)";
REGISTER_APP_GROUPS = YES;
@@ -321,7 +321,7 @@
"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";
CODE_SIGN_STYLE = Automatic;
COMBINE_HIDPI_IMAGES = YES;
- CURRENT_PROJECT_VERSION = 37;
+ CURRENT_PROJECT_VERSION = 38;
DEAD_CODE_STRIPPING = YES;
DEVELOPMENT_TEAM = 4KJ362VJW5;
ENABLE_APP_INTENTS_METADATA_GENERATION = NO;
@@ -337,7 +337,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
- MARKETING_VERSION = 3.2.9;
+ MARKETING_VERSION = 3.2.10;
PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar;
PRODUCT_NAME = "$(TARGET_NAME)";
PROVISIONING_PROFILE_SPECIFIER = "";
diff --git a/CodexBar/Controllers/FallbackPanelController.swift b/CodexBar/Controllers/FallbackPanelController.swift
index e07e2a8..11153c7 100644
--- a/CodexBar/Controllers/FallbackPanelController.swift
+++ b/CodexBar/Controllers/FallbackPanelController.swift
@@ -88,7 +88,7 @@ final class FallbackPanelController {
}
private func frame(for panelSize: NSSize, on preferredScreen: NSScreen?) -> NSRect {
- guard let screen = preferredScreen ?? mouseScreen() ?? NSScreen.main else {
+ guard let screen = preferredScreen ?? NSScreen.containingMouse() ?? NSScreen.main else {
return NSRect(origin: .zero, size: panelSize)
}
@@ -101,13 +101,6 @@ final class FallbackPanelController {
)
}
- private func mouseScreen() -> NSScreen? {
- let mouseLocation = NSEvent.mouseLocation
- return NSScreen.screens.first { screen in
- screen.frame.contains(mouseLocation)
- }
- }
-
private enum Metrics {
static let fallbackSize = NSSize(
width: CodexStatusMenuView.menuWidth,
diff --git a/CodexBar/Controllers/HeatmapDetailPanelController.swift b/CodexBar/Controllers/HeatmapDetailPanelController.swift
index f41676c..66087c9 100644
--- a/CodexBar/Controllers/HeatmapDetailPanelController.swift
+++ b/CodexBar/Controllers/HeatmapDetailPanelController.swift
@@ -12,7 +12,7 @@ final class HeatmapDetailPanelController {
self?.hostingController?.view
},
animationKey: Metrics.drawerTransformAnimationKey,
- overscan: Metrics.drawerOverscan
+ overscan: SidePanelSupport.Metrics.drawerOverscan
)
private var hideTask: Task<Void, Never>?
private var currentSide = UsageHeatmapDetailSide.left
@@ -47,7 +47,7 @@ final class HeatmapDetailPanelController {
show(context: context, relativeTo: menuSurfaceWindow, contentView: contentView)
}
- func hide(immediate: Bool = false, delayed: Bool = true) {
+ func hide(immediate: Bool = false) {
cancelHideTask()
visibilityGeneration += 1
drawerTransition = .idle
@@ -67,9 +67,7 @@ final class HeatmapDetailPanelController {
let generation = visibilityGeneration
let side = currentSide
hideTask = Task { @MainActor [weak self] in
- if delayed {
- try? await Task.sleep(for: .milliseconds(Metrics.hideDelayMilliseconds))
- }
+ try? await Task.sleep(for: .milliseconds(Metrics.hideDelayMilliseconds))
guard let self,
!Task.isCancelled,
@@ -83,7 +81,7 @@ final class HeatmapDetailPanelController {
let hidden = drawerAnimator.hiddenTranslation(for: side, panelWidth: panel.frame.width)
drawerAnimator.animateTranslation(
to: hidden,
- duration: Metrics.drawerExitDuration,
+ duration: SidePanelSupport.Metrics.drawerExitDuration,
timing: .easeIn
) {
Task { @MainActor [weak self] in
@@ -165,7 +163,7 @@ final class HeatmapDetailPanelController {
return
case .exiting:
drawerTransition = .idle
- drawerAnimator.animateTranslation(to: 0, duration: Metrics.drawerEnterDuration, timing: .easeOut)
+ drawerAnimator.animateTranslation(to: 0, duration: SidePanelSupport.Metrics.drawerEnterDuration, timing: .easeOut)
case .idle, .switchingSide:
drawerTransition = .idle
drawerAnimator.resetVisualState(for: panel)
@@ -183,7 +181,7 @@ final class HeatmapDetailPanelController {
drawerAnimator.animateEntryAfterInitialLayout(
from: hidden,
panel: panel,
- duration: Metrics.drawerEnterDuration,
+ duration: SidePanelSupport.Metrics.drawerEnterDuration,
isCurrent: { [weak self] in
self?.visibilityGeneration == generation
},
@@ -211,7 +209,7 @@ final class HeatmapDetailPanelController {
let hidden = drawerAnimator.hiddenTranslation(for: sourceSide, panelWidth: panel.frame.width)
drawerAnimator.animateTranslation(
to: hidden,
- duration: Metrics.drawerExitDuration,
+ duration: SidePanelSupport.Metrics.drawerExitDuration,
timing: .easeIn
) {
Task { @MainActor [weak self] in
@@ -241,7 +239,7 @@ final class HeatmapDetailPanelController {
drawerAnimator.animateTranslation(
from: hidden,
to: 0,
- duration: Metrics.drawerEnterDuration,
+ duration: SidePanelSupport.Metrics.drawerEnterDuration,
timing: .easeOut
) {
Task { @MainActor [weak self] in
@@ -288,21 +286,10 @@ final class HeatmapDetailPanelController {
return panel
}
- let panel = NonactivatingSidePanel(
- contentRect: NSRect(origin: .zero, size: UsageHeatmapDayDetailView.panelSize(showsWorkflow: true)),
- styleMask: [.borderless, .nonactivatingPanel],
- backing: .buffered,
- defer: false
+ let panel = SidePanelSupport.makePanel(
+ initialSize: UsageHeatmapDayDetailView.panelSize(showsWorkflow: true),
+ ignoresMouseEvents: true
)
- panel.backgroundColor = .clear
- panel.collectionBehavior = [.transient, .canJoinAllSpaces, .fullScreenAuxiliary]
- panel.hasShadow = true
- panel.hidesOnDeactivate = false
- panel.ignoresMouseEvents = true
- panel.isFloatingPanel = true
- panel.isOpaque = false
- panel.isReleasedWhenClosed = false
- panel.animationBehavior = .none
self.panel = panel
return panel
}
@@ -352,65 +339,33 @@ final class HeatmapDetailPanelController {
heatmapScreenFrame: CGRect?,
showsWorkflow: Bool,
preferredSide: UsageHeatmapDetailSide
- ) -> PanelPosition {
- // 优先贴在请求侧, 空间不足时换边, 最后仍夹紧到屏幕可见区域
+ ) -> SidePanelPosition {
let menuSurfaceFrame = SidePanelSupport.contentScreenFrame(for: contentView, in: menuSurfaceWindow) ?? menuSurfaceWindow.frame
let visibleFrame = (menuSurfaceWindow.screen ?? NSScreen.main)?.visibleFrame ?? menuSurfaceFrame
- let leftX = menuSurfaceFrame.minX - Metrics.panelGap - panelSize.width
- let rightX = menuSurfaceFrame.maxX + Metrics.panelGap
- let horizontal = SidePanelSupport.horizontalPlacement(
- preferredSide: preferredSide,
- left: SidePanelHorizontalPlacement(
- x: leftX,
- side: .left,
- isAvailable: leftX >= visibleFrame.minX + Metrics.screenPadding
- ),
- right: SidePanelHorizontalPlacement(
- x: rightX,
- side: .right,
- isAvailable: rightX + panelSize.width <= visibleFrame.maxX - Metrics.screenPadding
- )
- )
- let x = SidePanelSupport.clamped(
- horizontal.x,
- lower: visibleFrame.minX + Metrics.screenPadding,
- upper: visibleFrame.maxX - panelSize.width - Metrics.screenPadding
- )
- let frame = NSRect(
- x: x,
- y: panelY(
+ return SidePanelSupport.position(
+ panelSize: panelSize,
+ menuSurfaceFrame: menuSurfaceFrame,
+ visibleFrame: visibleFrame,
+ preferredSide: preferredSide,
+ proposedY: proposedY(
for: panelSize,
menuSurfaceFrame: menuSurfaceFrame,
- visibleFrame: visibleFrame,
anchorScreenFrame: anchorScreenFrame,
heatmapScreenFrame: heatmapScreenFrame,
showsWorkflow: showsWorkflow
- ),
- width: panelSize.width,
- height: panelSize.height
- )
-
- return PanelPosition(
- frame: frame,
- side: SidePanelSupport.actualSide(
- forX: x,
- panelWidth: panelSize.width,
- menuSurfaceFrame: menuSurfaceFrame,
- fallback: horizontal.side
)
)
}
- private func panelY(
+ private func proposedY(
for panelSize: CGSize,
menuSurfaceFrame: CGRect,
- visibleFrame: CGRect,
anchorScreenFrame: CGRect?,
heatmapScreenFrame: CGRect?,
showsWorkflow: Bool
) -> CGFloat {
- let proposedY: CGFloat = if showsWorkflow {
+ if showsWorkflow {
menuSurfaceFrame.minY
} else if let heatmapScreenFrame {
heatmapScreenFrame.maxY - panelSize.height
@@ -419,12 +374,6 @@ final class HeatmapDetailPanelController {
} else {
menuSurfaceFrame.midY - panelSize.height / 2
}
-
- return SidePanelSupport.clamped(
- proposedY,
- lower: max(visibleFrame.minY + Metrics.screenPadding, menuSurfaceFrame.minY),
- upper: visibleFrame.maxY - panelSize.height - Metrics.screenPadding
- )
}
private func cancelHideTask() {
@@ -433,12 +382,7 @@ final class HeatmapDetailPanelController {
}
private enum Metrics {
- static let panelGap: CGFloat = 4
- static let screenPadding: CGFloat = 8
static let hideDelayMilliseconds: UInt64 = 220
- static let drawerEnterDuration: TimeInterval = 0.18
- static let drawerExitDuration: TimeInterval = 0.12
- static let drawerOverscan: CGFloat = 1
static let drawerTransformAnimationKey = "CodexBar.heatmapDetailDrawerTransform"
}
@@ -449,13 +393,8 @@ final class HeatmapDetailPanelController {
case switchingSide
}
- private struct PanelPosition {
- let frame: NSRect
- let side: UsageHeatmapDetailSide
- }
-
private struct PanelRequest {
let context: UsageHeatmapHoverContext
- let position: PanelPosition
+ let position: SidePanelPosition
}
}
diff --git a/CodexBar/Controllers/ResetCreditsPanelController.swift b/CodexBar/Controllers/ResetCreditsPanelController.swift
index 572b032..603eb32 100644
--- a/CodexBar/Controllers/ResetCreditsPanelController.swift
+++ b/CodexBar/Controllers/ResetCreditsPanelController.swift
@@ -12,7 +12,7 @@ final class ResetCreditsPanelController {
self?.hostingController?.view
},
animationKey: Metrics.drawerTransformAnimationKey,
- overscan: Metrics.drawerOverscan
+ overscan: SidePanelSupport.Metrics.drawerOverscan
)
private var visibilityGeneration = 0
private var isExitAnimationRunning = false
@@ -80,7 +80,7 @@ final class ResetCreditsPanelController {
let hidden = drawerAnimator.hiddenTranslation(for: side, panelWidth: panel.frame.width)
drawerAnimator.animateTranslation(
to: hidden,
- duration: Metrics.drawerExitDuration,
+ duration: SidePanelSupport.Metrics.drawerExitDuration,
timing: .easeIn
) {
Task { @MainActor [weak self] in
@@ -144,24 +144,10 @@ final class ResetCreditsPanelController {
return panel
}
- let panel = NonactivatingSidePanel(
- contentRect: NSRect(
- origin: .zero,
- size: ResetCreditsPanelView.initialPanelSize
- ),
- styleMask: [.borderless, .nonactivatingPanel],
- backing: .buffered,
- defer: false
+ let panel = SidePanelSupport.makePanel(
+ initialSize: ResetCreditsPanelView.initialPanelSize,
+ ignoresMouseEvents: false
)
- panel.backgroundColor = .clear
- panel.collectionBehavior = [.transient, .canJoinAllSpaces, .fullScreenAuxiliary]
- panel.hasShadow = true
- panel.hidesOnDeactivate = false
- panel.ignoresMouseEvents = false
- panel.isFloatingPanel = true
- panel.isOpaque = false
- panel.isReleasedWhenClosed = false
- panel.animationBehavior = .none
self.panel = panel
return panel
}
@@ -189,7 +175,7 @@ final class ResetCreditsPanelController {
private func apply(
context: ResetCreditsPanelContext,
panelSize: CGSize,
- position: PanelPosition,
+ position: SidePanelPosition,
to panel: NSPanel
) {
updateContent(context, size: panelSize)
@@ -208,7 +194,7 @@ final class ResetCreditsPanelController {
drawerAnimator.animateEntryAfterInitialLayout(
from: hidden,
panel: panel,
- duration: Metrics.drawerEnterDuration,
+ duration: SidePanelSupport.Metrics.drawerEnterDuration,
isCurrent: { [weak self] in
self?.visibilityGeneration == generation
},
@@ -233,46 +219,16 @@ final class ResetCreditsPanelController {
visibleFrame: CGRect,
alignmentScreenFrame: CGRect?,
preferredSide: UsageHeatmapDetailSide
- ) -> PanelPosition {
- let leftX = menuSurfaceFrame.minX - Metrics.panelGap - panelSize.width
- let rightX = menuSurfaceFrame.maxX + Metrics.panelGap
- let horizontal = SidePanelSupport.horizontalPlacement(
+ ) -> SidePanelPosition {
+ SidePanelSupport.position(
+ panelSize: panelSize,
+ menuSurfaceFrame: menuSurfaceFrame,
+ visibleFrame: visibleFrame,
preferredSide: preferredSide,
- left: SidePanelHorizontalPlacement(
- x: leftX,
- side: .left,
- isAvailable: leftX >= visibleFrame.minX + Metrics.screenPadding
- ),
- right: SidePanelHorizontalPlacement(
- x: rightX,
- side: .right,
- isAvailable: rightX + panelSize.width <= visibleFrame.maxX - Metrics.screenPadding
- )
- )
-
- let x = SidePanelSupport.clamped(
- horizontal.x,
- lower: visibleFrame.minX + Metrics.screenPadding,
- upper: visibleFrame.maxX - panelSize.width - Metrics.screenPadding
- )
- let y = SidePanelSupport.clamped(
- proposedY(
+ proposedY: proposedY(
for: panelSize,
menuSurfaceFrame: menuSurfaceFrame,
alignmentScreenFrame: alignmentScreenFrame
- ),
- lower: max(visibleFrame.minY + Metrics.screenPadding, menuSurfaceFrame.minY),
- upper: visibleFrame.maxY - panelSize.height - Metrics.screenPadding
- )
- let frame = NSRect(x: x, y: y, width: panelSize.width, height: panelSize.height)
-
- return PanelPosition(
- frame: frame,
- side: SidePanelSupport.actualSide(
- forX: x,
- panelWidth: panelSize.width,
- menuSurfaceFrame: menuSurfaceFrame,
- fallback: horizontal.side
)
)
}
@@ -309,7 +265,7 @@ final class ResetCreditsPanelController {
menuSurfaceFrame: CGRect
) -> CGRect? {
guard let alignmentScreenFrame = alignmentScreenFrame?.standardized,
- isValidScreenFrame(alignmentScreenFrame) else {
+ alignmentScreenFrame.isValidScreenRect else {
return nil
}
@@ -326,27 +282,8 @@ final class ResetCreditsPanelController {
return alignmentScreenFrame
}
- private func isValidScreenFrame(_ frame: CGRect) -> Bool {
- frame.minX.isFinite
- && frame.minY.isFinite
- && frame.width.isFinite
- && frame.height.isFinite
- && frame.width > 0
- && frame.height > 0
- }
-
private enum Metrics {
- static let panelGap: CGFloat = 4
- static let screenPadding: CGFloat = 8
static let anchorValidationTolerance: CGFloat = 6
- static let drawerEnterDuration: TimeInterval = 0.18
- static let drawerExitDuration: TimeInterval = 0.12
- static let drawerOverscan: CGFloat = 1
static let drawerTransformAnimationKey = "CodexBar.resetCreditsDrawerTransform"
}
-
- private struct PanelPosition {
- let frame: NSRect
- let side: UsageHeatmapDetailSide
- }
}
diff --git a/CodexBar/Controllers/ScreenGeometry.swift b/CodexBar/Controllers/ScreenGeometry.swift
new file mode 100644
index 0000000..2b2b4ea
--- /dev/null
+++ b/CodexBar/Controllers/ScreenGeometry.swift
@@ -0,0 +1,25 @@
+import AppKit
+
+/// 屏幕坐标相关的共享几何工具
+extension NSScreen {
+ /// 鼠标当前所在屏幕
+ @MainActor
+ static func containingMouse() -> NSScreen? {
+ let mouseLocation = NSEvent.mouseLocation
+ return NSScreen.screens.first { screen in
+ screen.frame.contains(mouseLocation)
+ }
+ }
+}
+
+nonisolated extension CGRect {
+ /// 各分量有限且宽高为正, 才能作为可信的屏幕坐标参与定位
+ var isValidScreenRect: Bool {
+ minX.isFinite
+ && minY.isFinite
+ && width.isFinite
+ && height.isFinite
+ && width > 0
+ && height > 0
+ }
+}
diff --git a/CodexBar/Controllers/SidePanelSupport.swift b/CodexBar/Controllers/SidePanelSupport.swift
index 363951b..2dd1aef 100644
--- a/CodexBar/Controllers/SidePanelSupport.swift
+++ b/CodexBar/Controllers/SidePanelSupport.swift
@@ -131,6 +131,81 @@ final class SidePanelDrawerAnimator {
@MainActor
enum SidePanelSupport {
+ /// 两个侧边详情面板共用的几何与抽屉动画常量
+ enum Metrics {
+ static let panelGap: CGFloat = 4
+ static let screenPadding: CGFloat = 8
+ static let drawerEnterDuration: TimeInterval = 0.18
+ static let drawerExitDuration: TimeInterval = 0.12
+ static let drawerOverscan: CGFloat = 1
+ }
+
+ static func makePanel(initialSize: CGSize, ignoresMouseEvents: Bool) -> NSPanel {
+ let panel = NonactivatingSidePanel(
+ contentRect: NSRect(origin: .zero, size: initialSize),
+ styleMask: [.borderless, .nonactivatingPanel],
+ backing: .buffered,
+ defer: false
+ )
+ panel.backgroundColor = .clear
+ panel.collectionBehavior = [.transient, .canJoinAllSpaces, .fullScreenAuxiliary]
+ panel.hasShadow = true
+ panel.hidesOnDeactivate = false
+ panel.ignoresMouseEvents = ignoresMouseEvents
+ panel.isFloatingPanel = true
+ panel.isOpaque = false
+ panel.isReleasedWhenClosed = false
+ panel.animationBehavior = .none
+ return panel
+ }
+
+ /// 水平方向优先贴在请求侧, 空间不足时换边, 最后夹紧到屏幕可见区域
+ /// 纵向由调用方给出期望位置, 这里统一夹紧
+ static func position(
+ panelSize: CGSize,
+ menuSurfaceFrame: CGRect,
+ visibleFrame: CGRect,
+ preferredSide: UsageHeatmapDetailSide,
+ proposedY: CGFloat
+ ) -> SidePanelPosition {
+ let leftX = menuSurfaceFrame.minX - Metrics.panelGap - panelSize.width
+ let rightX = menuSurfaceFrame.maxX + Metrics.panelGap
+ let horizontal = horizontalPlacement(
+ preferredSide: preferredSide,
+ left: SidePanelHorizontalPlacement(
+ x: leftX,
+ side: .left,
+ isAvailable: leftX >= visibleFrame.minX + Metrics.screenPadding
+ ),
+ right: SidePanelHorizontalPlacement(
+ x: rightX,
+ side: .right,
+ isAvailable: rightX + panelSize.width <= visibleFrame.maxX - Metrics.screenPadding
+ )
+ )
+
+ let x = clamped(
+ horizontal.x,
+ lower: visibleFrame.minX + Metrics.screenPadding,
+ upper: visibleFrame.maxX - panelSize.width - Metrics.screenPadding
+ )
+ let y = clamped(
+ proposedY,
+ lower: max(visibleFrame.minY + Metrics.screenPadding, menuSurfaceFrame.minY),
+ upper: visibleFrame.maxY - panelSize.height - Metrics.screenPadding
+ )
+
+ return SidePanelPosition(
+ frame: NSRect(x: x, y: y, width: panelSize.width, height: panelSize.height),
+ side: actualSide(
+ forX: x,
+ panelWidth: panelSize.width,
+ menuSurfaceFrame: menuSurfaceFrame,
+ fallback: horizontal.side
+ )
+ )
+ }
+
static func attach(_ panel: NSPanel, to parentWindow: NSWindow) {
guard panel.parent !== parentWindow else {
return
@@ -187,7 +262,7 @@ enum SidePanelSupport {
return screenFrame
}
- static func clamped(_ value: CGFloat, lower: CGFloat, upper: CGFloat) -> CGFloat {
+ private static func clamped(_ value: CGFloat, lower: CGFloat, upper: CGFloat) -> CGFloat {
guard lower <= upper else {
return lower
}
@@ -195,7 +270,7 @@ enum SidePanelSupport {
return min(max(value, lower), upper)
}
- static func horizontalPlacement(
+ private static func horizontalPlacement(
preferredSide: UsageHeatmapDetailSide,
left: SidePanelHorizontalPlacement,
right: SidePanelHorizontalPlacement
@@ -209,7 +284,7 @@ enum SidePanelSupport {
return fallback.isAvailable ? fallback : primary
}
- static func actualSide(
+ private static func actualSide(
forX x: CGFloat,
panelWidth: CGFloat,
menuSurfaceFrame: CGRect,
@@ -238,3 +313,8 @@ nonisolated struct SidePanelHorizontalPlacement {
let side: UsageHeatmapDetailSide
let isAvailable: Bool
}
+
+nonisolated struct SidePanelPosition {
+ let frame: NSRect
+ let side: UsageHeatmapDetailSide
+}
diff --git a/CodexBar/Controllers/StatusItemController.swift b/CodexBar/Controllers/StatusItemController.swift
index 7fcbc00..9f3664c 100644
--- a/CodexBar/Controllers/StatusItemController.swift
+++ b/CodexBar/Controllers/StatusItemController.swift
@@ -239,7 +239,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
width: trackRect.width,
height: fillHeight
)
- quotaProgressColor(for: progress.percent)
+ QuotaPalette.nsColor(for: progress.percent)
.withAlphaComponent(progressAlpha)
.setFill()
NSBezierPath(
@@ -259,30 +259,6 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
return value * value * (3 - 2 * value)
}
- private static func quotaProgressColor(for percent: Int) -> NSColor {
- switch percent {
- case 80...:
- nsColor(hex: 0x16A085)
- case 60 ..< 80:
- nsColor(hex: 0x5DADE2)
- case 40 ..< 60:
- nsColor(hex: 0xF5B041)
- case 20 ..< 40:
- nsColor(hex: 0xFF7A59)
- default:
- nsColor(hex: 0xEE3F3F)
- }
- }
-
- private static func nsColor(hex: Int) -> NSColor {
- NSColor(
- red: CGFloat((hex >> 16) & 0xFF) / 255.0,
- green: CGFloat((hex >> 8) & 0xFF) / 255.0,
- blue: CGFloat(hex & 0xFF) / 255.0,
- alpha: 1
- )
- }
-
private struct StatusIconState: Equatable {
let usesErrorImage: Bool
let progress: StatusIconProgress?
@@ -325,10 +301,10 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
configureStatusButton()
configurePopover()
observeGlobalHotKeySettings()
+ // 订阅时 CombineLatest 会同步发出当前值, 初始图标由订阅路径统一渲染
observeViewModel()
observeWorkflowSyncState()
codexHookSettings.refresh()
- updateStatusImage()
viewModel.startAutoRefresh()
}
@@ -491,20 +467,6 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
return "快捷键已被占用"
}
- private func updateStatusImage() {
- updateStatusImage(currentStatusIconState)
- }
-
- private var currentStatusIconState: StatusIconState {
- StatusIconState(
- usesErrorImage: viewModel.usesErrorImage,
- progress: StatusIconProgress(
- snapshot: viewModel.snapshot,
- selection: menuBarQuotaSettings.selection
- )
- )
- }
-
private func updateStatusImage(_ state: StatusIconState) {
statusItem.button?.toolTip = state.toolTip
@@ -626,7 +588,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
}
private func toggleMenuSurfaceFromHotKey() {
- let targetScreen = screenContainingMouse() ?? NSScreen.main
+ let targetScreen = NSScreen.containingMouse() ?? NSScreen.main
let opensMenuSurface = menuSurfaceState == .hidden || menuSurfaceState == .closing
if opensMenuSurface {
suspendAuxiliaryWindowKeyFocus()
@@ -666,7 +628,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
let buttonRectInWindow = button.convert(button.bounds, to: nil)
let buttonScreenRect = window.convertToScreen(buttonRectInWindow)
- guard buttonScreenRect.hasFiniteGeometry,
+ guard buttonScreenRect.isValidScreenRect,
buttonScreenRect.width >= Metrics.minimumTrustedAnchorLength,
buttonScreenRect.height >= Metrics.minimumTrustedAnchorLength else {
return false
@@ -679,13 +641,6 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
return trustedScreenFrame.intersects(buttonScreenRect)
}
- private func screenContainingMouse() -> NSScreen? {
- let mouseLocation = NSEvent.mouseLocation
- return NSScreen.screens.first { screen in
- screen.frame.contains(mouseLocation)
- }
- }
-
private func cancelMenuSurfaceTasks() {
delayedStatusRefreshTask?.cancel()
delayedStatusRefreshTask = nil
@@ -912,7 +867,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
}
private func hideSideDetailPanels() {
- heatmapDetailPanelController.hide(immediate: true, delayed: false)
+ heatmapDetailPanelController.hide(immediate: true)
resetCreditsPanelController.hide(immediate: true)
}
@@ -981,9 +936,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
}
private var canSynchronizeWorkflow: Bool {
- codexHookSettings.isEnabled
- && WorkflowSyncSettings.isEnabled()
- && syncSettings.isSyncAvailable
+ syncSettings.isEffectivelyActive(isHookEnabled: codexHookSettings.isEnabled)
}
private func updateHeatmapDetailPanel(_ context: UsageHeatmapHoverContext?) {
@@ -1117,12 +1070,3 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
case fallbackPanel
}
}
-
-private extension CGRect {
- var hasFiniteGeometry: Bool {
- origin.x.isFinite &&
- origin.y.isFinite &&
- size.width.isFinite &&
- size.height.isFinite
- }
-}
diff --git a/CodexBar/Models/CodexWorkflowModels.swift b/CodexBar/Models/CodexWorkflowModels.swift
index c54b79d..c23efd1 100644
--- a/CodexBar/Models/CodexWorkflowModels.swift
+++ b/CodexBar/Models/CodexWorkflowModels.swift
@@ -20,9 +20,7 @@ private nonisolated enum WorkflowJSON {
}
static func value(_ value: some Encodable) throws -> String {
- let encoder = JSONEncoder()
- encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]
- let data = try encoder.encode(value)
+ let data = try JSONLines.stableEncoder.encode(value)
guard let text = String(bytes: data, encoding: .utf8) else {
throw EncodingError.invalidValue(
value,
@@ -227,31 +225,19 @@ nonisolated struct WorkflowDailyMetrics: Equatable, Identifiable {
/// WorkflowService 发布给 UI 的近端快照
nonisolated struct WorkflowSnapshot: Equatable {
- let generatedAt: Date
let dailyMetrics: [WorkflowDailyMetrics]
- static let empty = WorkflowSnapshot(generatedAt: Date(), dailyMetrics: [])
+ static let empty = WorkflowSnapshot(dailyMetrics: [])
- init(generatedAt: Date = Date(), dailyMetrics: [WorkflowDailyMetrics]) {
- self.generatedAt = generatedAt
+ init(dailyMetrics: [WorkflowDailyMetrics]) {
self.dailyMetrics = dailyMetrics
}
- init(dailyAggregates: [WorkflowDailyAggregate], generatedAt: Date = Date()) {
- self.generatedAt = generatedAt
- dailyMetrics = dailyAggregates
- .map(\.metrics)
- .sorted { $0.startDate < $1.startDate }
- }
-
init(
localAggregates: [WorkflowDailyAggregate],
syncedRecords: [WorkflowSyncedDailyRecord],
- currentDeviceId: String?,
- generatedAt: Date = Date()
+ currentDeviceId: String?
) {
- self.generatedAt = generatedAt
-
var metricsByDate = [String: WorkflowDailyMetrics]()
localAggregates
.map(\.metrics)
diff --git a/CodexBar/Models/DateFormatter.swift b/CodexBar/Models/DateFormatter.swift
index 3d8a7e2..749c690 100644
--- a/CodexBar/Models/DateFormatter.swift
+++ b/CodexBar/Models/DateFormatter.swift
@@ -46,49 +46,46 @@ nonisolated enum CodexDateFormat {
/// yyyy-MM-dd HH: mm: ss.SSS, Hook 原始事件写入本机时间字符串
static func localTimestampString(from date: Date) -> String {
- localTimestampFormatter().string(from: date)
+ localTimestampFormatter.string(from: date)
}
static func localTimestampDate(from string: String) -> Date? {
- localTimestampFormatter().date(from: string)
+ localTimestampFormatter.date(from: string)
}
- /// 带小数秒的 ISO8601, 用于读取 Hook payload 中的原始时间戳
- static func iso8601FractionalDate(from string: String) -> Date? {
- iso8601FractionalFormatter().date(from: string)
+ /// yyyy-MM-dd HH: mm: ss, 设置页与重置次数详情统一的本地时间展示
+ static func localDisplayString(from date: Date) -> String {
+ localDisplayFormatter.string(from: date)
}
- /// 不带小数秒的 ISO8601 兜底解析器
- static func iso8601InternetDateTimeDate(from string: String) -> Date? {
- iso8601InternetDateTimeFormatter().date(from: string)
+ /// ISO8601 internet date-time, 带或不带小数秒均可解析
+ static func iso8601Date(from string: String) -> Date? {
+ try? Date(string, strategy: .iso8601)
}
- private static var localGregorianCalendar: Calendar {
+ private static let localGregorianCalendar: Calendar = {
var calendar = Calendar(identifier: .gregorian)
calendar.locale = Locale(identifier: "en_US_POSIX")
calendar.timeZone = .autoupdatingCurrent
return calendar
- }
+ }()
- private static func localTimestampFormatter() -> DateFormatter {
+ /// 以下格式器配置后不再修改; DateFormatter/ISO8601DateFormatter
+ /// 在 macOS 10.9+ 线程安全, 可跨并发域缓存共享
+ private static let localTimestampFormatter: DateFormatter = {
let formatter = DateFormatter()
formatter.locale = Locale(identifier: "en_US_POSIX")
formatter.timeZone = .autoupdatingCurrent
formatter.dateFormat = "yyyy-MM-dd HH:mm:ss.SSS"
return formatter
- }
-
- private static func iso8601FractionalFormatter() -> ISO8601DateFormatter {
- let formatter = ISO8601DateFormatter()
- formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
- return formatter
- }
+ }()
- private static func iso8601InternetDateTimeFormatter() -> ISO8601DateFormatter {
- let formatter = ISO8601DateFormatter()
- formatter.formatOptions = [.withInternetDateTime]
+ private static let localDisplayFormatter: DateFormatter = {
+ let formatter = DateFormatter()
+ formatter.locale = Locale(identifier: "en_US_POSIX")
+ formatter.dateFormat = "yyyy-MM-dd HH:mm:ss"
return formatter
- }
+ }()
private static func padded(_ value: Int, toLength length: Int) -> String {
let text = String(value)
diff --git a/CodexBar/Services/CodexCLI/CodexCLIResolver.swift b/CodexBar/Services/CodexCLI/CodexCLIResolver.swift
index 4c53e63..00b83e5 100644
--- a/CodexBar/Services/CodexCLI/CodexCLIResolver.swift
+++ b/CodexBar/Services/CodexCLI/CodexCLIResolver.swift
@@ -38,8 +38,12 @@ nonisolated struct CodexCLIInstallations: Equatable {
// 与启动优先级一致: 全局优先, 回退内置
var activeSource: CodexCLIExecutableSource? {
- if globalPath != nil { return .global }
- if bundledPath != nil { return .bundled }
+ if globalPath != nil {
+ return .global
+ }
+ if bundledPath != nil {
+ return .bundled
+ }
return nil
}
@@ -70,6 +74,26 @@ nonisolated enum CodexCLIResolver {
return AppServerCommand(source: source, executablePath: path)
}
+ /// Codex 配置目录: 优先 CODEX_HOME, 回退真实用户 HOME 下的 .codex
+ /// auth.json / hooks.json 等配置文件统一从这里解析
+ static func codexHomeDirectory(environment: [String: String] = environment) -> URL {
+ if let codexHome = nonEmptyEnvironmentValue("CODEX_HOME", in: environment) {
+ return URL(fileURLWithPath: codexHome, isDirectory: true)
+ }
+
+ let home = nonEmptyEnvironmentValue("HOME", in: environment) ?? NSHomeDirectory()
+ return URL(fileURLWithPath: home, isDirectory: true)
+ .appendingPathComponent(".codex", isDirectory: true)
+ }
+
+ private static func nonEmptyEnvironmentValue(
+ _ key: String,
+ in environment: [String: String]
+ ) -> String? {
+ let value = environment[key]?.trimmingCharacters(in: .whitespacesAndNewlines)
+ return value?.isEmpty == false ? value : nil
+ }
+
static func resolveInstallations(environment: [String: String] = environment) -> CodexCLIInstallations {
let cliPath = findExecutable(named: "codex", environment: environment)
let cliIsBundled = cliPath.map { pathsAreEquivalent($0, bundledExecutablePath) } ?? false
diff --git a/CodexBar/Services/CodexStatus/CodexResetCreditsService.swift b/CodexBar/Services/CodexStatus/CodexResetCreditsService.swift
index a5965cf..4bb86d2 100644
--- a/CodexBar/Services/CodexStatus/CodexResetCreditsService.swift
+++ b/CodexBar/Services/CodexStatus/CodexResetCreditsService.swift
@@ -64,8 +64,7 @@ nonisolated enum CodexResetCreditsService {
private static func decodeISO8601Date(from decoder: Decoder) throws -> Date {
let container = try decoder.singleValueContainer()
let raw = try container.decode(String.self)
- if let date = CodexDateFormat.iso8601FractionalDate(from: raw)
- ?? CodexDateFormat.iso8601InternetDateTimeDate(from: raw) {
+ if let date = CodexDateFormat.iso8601Date(from: raw) {
return date
}
@@ -107,24 +106,9 @@ private nonisolated extension CodexResetCreditsService {
}
private static func authFileURL(environment: [String: String]) -> URL {
- if let codexHome = nonEmptyEnvironmentValue("CODEX_HOME", in: environment) {
- return URL(fileURLWithPath: codexHome).appendingPathComponent("auth.json")
- }
-
- let home = nonEmptyEnvironmentValue("HOME", in: environment) ?? NSHomeDirectory()
- let homeURL = URL(fileURLWithPath: home)
- return homeURL
- .appendingPathComponent(".codex")
+ CodexCLIResolver.codexHomeDirectory(environment: environment)
.appendingPathComponent("auth.json")
}
-
- private static func nonEmptyEnvironmentValue(
- _ key: String,
- in environment: [String: String]
- ) -> String? {
- let value = environment[key]?.trimmingCharacters(in: .whitespacesAndNewlines)
- return value?.isEmpty == false ? value : nil
- }
}
struct CodexAuthFile: Decodable {
diff --git a/CodexBar/Services/CodexStatus/CodexStatusViewModel.swift b/CodexBar/Services/CodexStatus/CodexStatusViewModel.swift
index 18ed99a..fd88a30 100644
--- a/CodexBar/Services/CodexStatus/CodexStatusViewModel.swift
+++ b/CodexBar/Services/CodexStatus/CodexStatusViewModel.swift
@@ -25,18 +25,6 @@ final class CodexStatusViewModel: ObservableObject {
@Published private(set) var codexConnectionInfo: CodexCLIConnectionInfo?
@Published private(set) var autoRefreshCountdownStartedAt: Date?
- var hasError: Bool {
- loadState.isError
- }
-
- var hasUntrustedData: Bool {
- snapshot?.hasTrustedData == false
- }
-
- var usesErrorImage: Bool {
- hasError || hasUntrustedData
- }
-
var autoRefreshInterval: TimeInterval {
Self.refreshInterval
}
diff --git a/CodexBar/Services/Settings/CodexHookSettings.swift b/CodexBar/Services/Settings/CodexHookSettings.swift
index 679de6c..c1a48d5 100644
--- a/CodexBar/Services/Settings/CodexHookSettings.swift
+++ b/CodexBar/Services/Settings/CodexHookSettings.swift
@@ -224,9 +224,7 @@ private extension CodexHookSettings {
}
nonisolated static func defaultHooksURL() -> URL {
- FileManager.default
- .homeDirectoryForCurrentUser
- .appendingPathComponent(".codex", isDirectory: true)
+ CodexCLIResolver.codexHomeDirectory()
.appendingPathComponent("hooks.json")
}
@@ -645,25 +643,13 @@ private extension CodexHookSettings {
}
static func hookTrustStateValue(from state: [String: String]) -> [String: [String: String]] {
- var value: [String: [String: String]] = [:]
- for key in state.keys.sorted() {
- guard let trustedHash = state[key] else {
- continue
- }
-
- value[key] = [trustedHashKey: trustedHash]
- }
-
- return value
+ state.mapValues { [trustedHashKey: $0] }
}
static func hookTrustStateValue(from entries: [CodexHookTrustEntry]) -> [String: [String: String]] {
- var state: [String: String] = [:]
- for entry in entries {
- state[entry.key] = entry.trustedHash
+ entries.reduce(into: [:]) { value, entry in
+ value[entry.key] = [trustedHashKey: entry.trustedHash]
}
-
- return hookTrustStateValue(from: state)
}
static func hooksObject(from config: JSONObject) throws -> JSONObject {
diff --git a/CodexBar/Services/Settings/MenuBarQuotaSettings.swift b/CodexBar/Services/Settings/MenuBarQuotaSettings.swift
index 35c64c2..f6508c1 100644
--- a/CodexBar/Services/Settings/MenuBarQuotaSettings.swift
+++ b/CodexBar/Services/Settings/MenuBarQuotaSettings.swift
@@ -6,13 +6,17 @@ import Foundation
final class MenuBarQuotaSettings: ObservableObject {
@Published private(set) var selection: MenuBarQuotaSelection
+ /// 关闭指示前最后一次选中的窗口, 重新开启时恢复; 随偏好持久化
+ private var lastWindowSelection: MenuBarQuotaSelection
private let defaults: UserDefaults
private var pendingSelection: MenuBarQuotaSelection?
private var publishSelectionTask: Task<Void, Never>?
init(defaults: UserDefaults = .standard) {
self.defaults = defaults
- selection = Self.loadSelection(from: defaults)
+ let selection = Self.loadSelection(from: defaults)
+ self.selection = selection
+ lastWindowSelection = Self.loadLastWindowSelection(from: defaults, current: selection)
}
deinit {
@@ -20,10 +24,13 @@ final class MenuBarQuotaSettings: ObservableObject {
}
func refresh() {
- publishSelection(Self.loadSelection(from: defaults))
+ let selection = Self.loadSelection(from: defaults)
+ rememberLastWindowSelection(selection)
+ publishSelection(selection)
}
func setSelection(_ selection: MenuBarQuotaSelection) {
+ rememberLastWindowSelection(selection)
guard selection != effectiveSelection else {
return
}
@@ -32,6 +39,24 @@ final class MenuBarQuotaSettings: ObservableObject {
publishSelection(selection)
}
+ func setEnabled(_ enabled: Bool) {
+ setSelection(enabled ? lastWindowSelection : .off)
+ }
+
+ /// 供设置页 Picker 展示的窗口选择: 关闭时回退到最后一次的非 off 选择
+ var activeWindowSelection: MenuBarQuotaSelection {
+ selection == .off ? lastWindowSelection : selection
+ }
+
+ private func rememberLastWindowSelection(_ selection: MenuBarQuotaSelection) {
+ guard selection != .off, selection != lastWindowSelection else {
+ return
+ }
+
+ lastWindowSelection = selection
+ defaults.set(selection.rawValue, forKey: Self.lastWindowSelectionKey)
+ }
+
private var effectiveSelection: MenuBarQuotaSelection {
pendingSelection ?? selection
}
@@ -71,7 +96,21 @@ final class MenuBarQuotaSettings: ObservableObject {
return selection
}
+ private static func loadLastWindowSelection(
+ from defaults: UserDefaults,
+ current: MenuBarQuotaSelection
+ ) -> MenuBarQuotaSelection {
+ if let rawValue = defaults.string(forKey: lastWindowSelectionKey),
+ let selection = MenuBarQuotaSelection(rawValue: rawValue),
+ selection != .off {
+ return selection
+ }
+
+ return current == .off ? .primary : current
+ }
+
private static let selectionKey = "MenuBarQuota.selection"
+ private static let lastWindowSelectionKey = "MenuBarQuota.lastWindowSelection"
}
nonisolated enum MenuBarQuotaSelection: String, CaseIterable, Identifiable {
diff --git a/CodexBar/Services/Settings/WorkflowSyncSettings.swift b/CodexBar/Services/Settings/WorkflowSyncSettings.swift
index 9ed4680..fc4cd32 100644
--- a/CodexBar/Services/Settings/WorkflowSyncSettings.swift
+++ b/CodexBar/Services/Settings/WorkflowSyncSettings.swift
@@ -60,6 +60,11 @@ final class WorkflowSyncSettings: ObservableObject {
syncAvailability.isAvailable
}
+ /// 「同步是否实际生效」的唯一判定: Hook 已启用且同步开关打开且 iCloud 可用
+ func isEffectivelyActive(isHookEnabled: Bool) -> Bool {
+ isHookEnabled && isEnabled && isSyncAvailable
+ }
+
var unavailableMessage: String? {
syncAvailability.isUnavailable ? "同步不可用" : nil
}
@@ -68,7 +73,7 @@ final class WorkflowSyncSettings: ObservableObject {
guard let lastUploadAt else {
return nil
}
- return Self.lastUploadAtFormatter.string(from: lastUploadAt)
+ return CodexDateFormat.localDisplayString(from: lastUploadAt)
}
nonisolated static func isEnabled(defaults: UserDefaults = .standard) -> Bool {
@@ -181,28 +186,11 @@ final class WorkflowSyncSettings: ObservableObject {
}
private nonisolated static func loadLastUploadAt() -> Date? {
- let stateURL = WorkflowStorage.syncDirectoryURL()
- .appendingPathComponent("state.json", isDirectory: false)
- guard let data = try? Data(contentsOf: stateURL), !data.isEmpty,
- let state = try? JSONDecoder().decode(LocalSyncState.self, from: data) else {
- return nil
- }
- return state.lastUploadAt
+ WorkflowSyncService.loadLastUploadAt()
}
- private static let lastUploadAtFormatter: DateFormatter = {
- let formatter = DateFormatter()
- formatter.locale = Locale(identifier: "en_US_POSIX")
- formatter.dateFormat = "yyyy-MM-dd HH:mm:ss"
- return formatter
- }()
-
private nonisolated static let enabledKey = "WorkflowSync.isEnabled"
private nonisolated static let needsBackfillKey = "WorkflowSync.needsBackfill"
-
- private nonisolated struct LocalSyncState: Decodable {
- let lastUploadAt: Date?
- }
}
nonisolated enum WorkflowSyncAvailability: Equatable {
diff --git a/CodexBar/Services/Workflow/JSONLines.swift b/CodexBar/Services/Workflow/JSONLines.swift
index aab1789..0ba9de6 100644
--- a/CodexBar/Services/Workflow/JSONLines.swift
+++ b/CodexBar/Services/Workflow/JSONLines.swift
@@ -2,6 +2,14 @@ import Foundation
/// 简单 JSONL 工具, 读取时跳过坏行以保护历史统计可用性
nonisolated enum JSONLines {
+ /// 落盘 JSON 统一的稳定输出配置, 保证文件可 diff 且格式一致
+ /// 配置后不再修改, encode 可重入, 可跨并发域缓存共享
+ static let stableEncoder: JSONEncoder = {
+ let encoder = JSONEncoder()
+ encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]
+ return encoder
+ }()
+
/// 按行解码 JSONL: 切分换行, trim, 跳过空行与解码失败的行
static func decode<T: Decodable>(_ type: T.Type = T.self, from data: Data) -> [T] {
decodeWithFailures(type, from: data).values
diff --git a/CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift b/CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift
index fcbe761..b6bf68e 100644
--- a/CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift
+++ b/CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift
@@ -52,8 +52,11 @@ nonisolated enum WorkflowHookEventRecorder {
var maintenanceState = WorkflowStorage.loadMaintenanceState()
try append(event.jsonLineData(), to: eventLogURL)
- maintenanceState.markPending(dateKey)
- try WorkflowStorage.saveMaintenanceState(maintenanceState)
+
+ // 稳态下当天早已 pending, 跳过无变化的全量重写以缩短持锁时间
+ if maintenanceState.markPending(dateKey) {
+ try WorkflowStorage.saveMaintenanceState(maintenanceState)
+ }
}
}
@@ -138,14 +141,10 @@ private nonisolated struct WorkflowHookPayload {
return nil
}
- if let date = CodexDateFormat.iso8601FractionalDate(from: trimmedString) {
- return date
- }
-
- if let date = CodexDateFormat.localTimestampDate(from: trimmedString) {
+ if let date = CodexDateFormat.iso8601Date(from: trimmedString) {
return date
}
- return CodexDateFormat.iso8601InternetDateTimeDate(from: trimmedString)
+ return CodexDateFormat.localTimestampDate(from: trimmedString)
}
}
diff --git a/CodexBar/Services/Workflow/WorkflowService.swift b/CodexBar/Services/Workflow/WorkflowService.swift
index fd32369..27551dc 100644
--- a/CodexBar/Services/Workflow/WorkflowService.swift
+++ b/CodexBar/Services/Workflow/WorkflowService.swift
@@ -25,7 +25,10 @@ actor WorkflowService {
) async -> WorkflowSnapshot {
var changedDates = Set<String>()
if performMaintenance {
- changedDates = performMaintenanceIfNeeded()
+ // changedDates 只在实际执行 iCloud 同步时被消费, 其余场景跳过 payload 比对
+ changedDates = performMaintenanceIfNeeded(
+ computesChangedDates: synchronize && WorkflowSyncSettings.isEnabled()
+ )
}
let aggregates = loadDailyAggregates() ?? []
@@ -62,8 +65,8 @@ actor WorkflowService {
return WorkflowDailyAggregate.normalized(aggregates: aggregates)
}
- private func performMaintenanceIfNeeded() -> Set<String> {
- let beforePayloads = syncPayloadByDate()
+ private func performMaintenanceIfNeeded(computesChangedDates: Bool) -> Set<String> {
+ let beforePayloads = computesChangedDates ? syncPayloadByDate() : [:]
do {
let tasks = try prepareMaintenanceTasks()
@@ -74,6 +77,10 @@ actor WorkflowService {
return []
}
+ guard computesChangedDates else {
+ return []
+ }
+
return changedSyncPayloadDates(before: beforePayloads, after: syncPayloadByDate())
}
@@ -131,17 +138,17 @@ actor WorkflowService {
var changed = false
if state.schema != WorkflowMaintenanceState.currentSchema {
- changed = markDirty(eventDateKeys, in: &state) || changed
+ changed = state.markDirty(contentsOf: eventDateKeys) || changed
state.schema = WorkflowMaintenanceState.currentSchema
changed = true
}
if dailyDecodeResult.failedLineCount > 0 || (dailyDecodeResult.values.isEmpty && !eventDateKeys.isEmpty) {
- changed = markDirty(eventDateKeys, in: &state) || changed
+ changed = state.markDirty(contentsOf: eventDateKeys) || changed
}
- changed = markDirty(eventDateKeys.filter { dailyByDate[$0] == nil }, in: &state) || changed
- changed = markDirty(state.pending.filter { dailyByDate[$0] == nil }, in: &state) || changed
+ changed = state.markDirty(contentsOf: eventDateKeys.filter { dailyByDate[$0] == nil }) || changed
+ changed = state.markDirty(contentsOf: state.pending.filter { dailyByDate[$0] == nil }) || changed
return changed
}
@@ -150,7 +157,7 @@ actor WorkflowService {
eventDateKeys: [String],
state: inout WorkflowMaintenanceState
) -> Bool {
- var changed = markDirty(eventDateKeys.filter { state.days[$0] == nil }, in: &state)
+ var changed = state.markDirty(contentsOf: eventDateKeys.filter { state.days[$0] == nil })
// 文件变小说明被外部截断, 必须全量重建
// 变大则从旧 offset 增量追上
@@ -207,20 +214,6 @@ actor WorkflowService {
return tasks
}
- private func markDirty(
- _ dateKeys: [String],
- in state: inout WorkflowMaintenanceState
- ) -> Bool {
- let previousDirty = state.dirty
- let previousDays = state.days
-
- for dateKey in dateKeys {
- state.markDirty(dateKey)
- }
-
- return previousDirty != state.dirty || previousDays != state.days
- }
-
private func dirtyTask(for dateKey: String, size: UInt64? = nil) -> WorkflowMaintenanceTask {
WorkflowMaintenanceTask(
dateKey: dateKey,
@@ -388,17 +381,24 @@ actor WorkflowService {
private func eventLogHasNotShrunk(for result: WorkflowMaintenanceResult) throws -> Bool {
try WorkflowStorage.withExclusiveLock {
- let currentSize = WorkflowStorage.fileSize(at: eventLogURL(for: result.dateKey))
var state = WorkflowStorage.loadMaintenanceState()
+ return try eventLogSizeIfNotShrunk(for: result, state: &state) != nil
+ }
+ }
- guard currentSize >= result.size else {
- state.markDirty(result.dateKey)
- try WorkflowStorage.saveMaintenanceState(state)
- return false
- }
-
- return true
+ /// 锁内校验事件文件未被外部截断; 已收缩时标脏并落盘, 返回 nil
+ private func eventLogSizeIfNotShrunk(
+ for result: WorkflowMaintenanceResult,
+ state: inout WorkflowMaintenanceState
+ ) throws -> UInt64? {
+ let currentSize = WorkflowStorage.fileSize(at: eventLogURL(for: result.dateKey))
+ guard currentSize >= result.size else {
+ state.markDirty(result.dateKey)
+ try WorkflowStorage.saveMaintenanceState(state)
+ return nil
}
+
+ return currentSize
}
private func writeDailyAggregate(_ aggregate: WorkflowDailyAggregate) throws {
@@ -459,12 +459,9 @@ actor WorkflowService {
private func commitMaintenanceState(_ result: WorkflowMaintenanceResult) throws {
try WorkflowStorage.withExclusiveLock {
- let currentSize = WorkflowStorage.fileSize(at: eventLogURL(for: result.dateKey))
var state = WorkflowStorage.loadMaintenanceState()
- guard currentSize >= result.size else {
- state.markDirty(result.dateKey)
- try WorkflowStorage.saveMaintenanceState(state)
+ guard let currentSize = try eventLogSizeIfNotShrunk(for: result, state: &state) else {
return
}
@@ -640,9 +637,7 @@ nonisolated enum WorkflowStorage {
withIntermediateDirectories: true
)
- let encoder = JSONEncoder()
- encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]
- let data = try encoder.encode(state)
+ let data = try JSONLines.stableEncoder.encode(state)
try data.write(to: maintenanceURL(), options: .atomic)
}
@@ -723,14 +718,38 @@ nonisolated struct WorkflowMaintenanceState: Codable, Equatable {
days = try container.decodeIfPresent([String: WorkflowDayMaintenanceState].self, forKey: .days) ?? [:]
}
- mutating func markPending(_ dateKey: String) {
- pending = Self.inserting(dateKey, into: pending)
+ /// 返回状态是否有实际变化, 便于调用方跳过无谓的落盘
+ @discardableResult
+ mutating func markPending(_ dateKey: String) -> Bool {
+ let newPending = Self.inserting(dateKey, into: pending)
+ let changed = newPending != pending || days[dateKey] == nil
+ pending = newPending
ensureDayState(for: dateKey)
+ return changed
}
- mutating func markDirty(_ dateKey: String) {
- dirty = Self.inserting(dateKey, into: dirty)
- ensureDayState(for: dateKey)
+ @discardableResult
+ mutating func markDirty(_ dateKey: String) -> Bool {
+ markDirty(contentsOf: [dateKey])
+ }
+
+ /// 批量标脏一次性归一化, 避免逐个插入的重复排序与校验
+ @discardableResult
+ mutating func markDirty(contentsOf dateKeys: [String]) -> Bool {
+ guard !dateKeys.isEmpty else {
+ return false
+ }
+
+ let newDirty = Self.normalizedDates(dirty + dateKeys)
+ var changed = newDirty != dirty
+ dirty = newDirty
+
+ for dateKey in dateKeys where days[dateKey] == nil {
+ days[dateKey] = WorkflowDayMaintenanceState()
+ changed = true
+ }
+
+ return changed
}
mutating func removePending(_ dateKey: String) {
diff --git a/CodexBar/Services/Workflow/WorkflowSyncService.swift b/CodexBar/Services/Workflow/WorkflowSyncService.swift
index 78ce889..ee526d0 100644
--- a/CodexBar/Services/Workflow/WorkflowSyncService.swift
+++ b/CodexBar/Services/Workflow/WorkflowSyncService.swift
@@ -10,6 +10,11 @@ actor WorkflowSyncService {
private let fileManager: FileManager
private let directoryURL: URL
+ // zone 存在性和 account salt 首次确认后跨轮缓存, 省掉每轮同步的两次固定往返
+ // 任一轮同步失败时作废: iCloud 账号切换必然伴随请求报错, 下一轮会重新确认
+ private var isSyncZoneConfirmed = false
+ private var cachedAccountSalt: Data?
+
init(
container: CKContainer = .default(),
fileManager: FileManager = .default,
@@ -39,9 +44,10 @@ actor WorkflowSyncService {
var didSucceed = false
var failureMessage: String?
- Self.postSyncDidStart()
+ Self.postSyncNotification(.workflowSyncDidStart)
defer {
- Self.postSyncDidFinish(
+ Self.postSyncNotification(
+ .workflowSyncDidFinish,
didSucceed: didSucceed,
failureMessage: failureMessage
)
@@ -72,6 +78,7 @@ actor WorkflowSyncService {
try saveState(state)
didSucceed = true
} catch {
+ invalidateAccountScopedCaches()
failureMessage = WorkflowSyncFailureReason.classify(error).message
try? saveState(state)
}
@@ -514,12 +521,19 @@ private extension WorkflowSyncService {
}
func accountSalt() async throws -> Data {
+ if let cachedAccountSalt {
+ return cachedAccountSalt
+ }
+
let recordID = accountSaltRecordID
- if let salt = try await fetchAccountSalt(recordID) {
- return salt
+ let salt: Data = if let fetched = try await fetchAccountSalt(recordID) {
+ fetched
+ } else {
+ try await createAccountSalt(recordID)
}
- return try await createAccountSalt(recordID)
+ cachedAccountSalt = salt
+ return salt
}
func fetchAccountSalt(_ recordID: CKRecord.ID) async throws -> Data? {
@@ -553,16 +567,25 @@ private extension WorkflowSyncService {
}
func ensureSyncZoneExists() async throws {
- guard try await syncZoneExists() == false else {
+ guard !isSyncZoneConfirmed else {
return
}
- let zone = CKRecordZone(zoneID: syncZoneID)
- let result = try await database.modifyRecordZones(saving: [zone], deleting: [])
+ if try await syncZoneExists() == false {
+ let zone = CKRecordZone(zoneID: syncZoneID)
+ let result = try await database.modifyRecordZones(saving: [zone], deleting: [])
- if case let .failure(error) = result.saveResults[syncZoneID] {
- throw error
+ if case let .failure(error) = result.saveResults[syncZoneID] {
+ throw error
+ }
}
+
+ isSyncZoneConfirmed = true
+ }
+
+ func invalidateAccountScopedCaches() {
+ isSyncZoneConfirmed = false
+ cachedAccountSalt = nil
}
func syncZoneExists() async throws -> Bool {
@@ -625,53 +648,45 @@ private extension WorkflowSyncService {
return Self.hexString(Data(digest))
}
- nonisolated static func postSyncDidStart() {
- postSyncNotification(.workflowSyncDidStart)
- }
-
- nonisolated static func postSyncDidFinish(
- didSucceed: Bool,
- failureMessage: String?
- ) {
- postSyncNotification(.workflowSyncDidFinish) {
- finishNotificationUserInfo(
- didSucceed: didSucceed,
- failureMessage: failureMessage
- )
- }
- }
-
- @MainActor
- static func finishNotificationUserInfo(
- didSucceed: Bool,
- failureMessage: String?
- ) -> [String: Any] {
- var userInfo: [String: Any] = [
- WorkflowSyncNotificationKey.didSucceed: didSucceed
- ]
- if let failureMessage {
- userInfo[WorkflowSyncNotificationKey.failureMessage] = failureMessage
- }
- return userInfo
- }
-
nonisolated static func postSyncNotification(
_ name: Notification.Name,
- userInfo: @escaping @MainActor () -> [String: Any]? = { nil }
+ didSucceed: Bool? = nil,
+ failureMessage: String? = nil
) {
Task { @MainActor in
+ var userInfo = [String: Any]()
+ if let didSucceed {
+ userInfo[WorkflowSyncNotificationKey.didSucceed] = didSucceed
+ }
+ if let failureMessage {
+ userInfo[WorkflowSyncNotificationKey.failureMessage] = failureMessage
+ }
+
NotificationCenter.default.post(
name: name,
object: nil,
- userInfo: userInfo()
+ userInfo: userInfo.isEmpty ? nil : userInfo
)
}
}
}
+extension WorkflowSyncService {
+ /// 设置页读取最近上传时间, 与内部 loadState 使用同一 schema 校验口径
+ nonisolated static func loadLastUploadAt() -> Date? {
+ let stateURL = WorkflowStorage.syncDirectoryURL()
+ .appendingPathComponent("state.json", isDirectory: false)
+ return loadState(at: stateURL).lastUploadAt
+ }
+}
+
private extension WorkflowSyncService {
func loadState() -> WorkflowSyncState {
- guard let data = try? Data(contentsOf: stateURL), !data.isEmpty,
+ Self.loadState(at: stateURL)
+ }
+
+ nonisolated static func loadState(at url: URL) -> WorkflowSyncState {
+ guard let data = try? Data(contentsOf: url), !data.isEmpty,
let state = try? JSONDecoder().decode(WorkflowSyncState.self, from: data) else {
return WorkflowSyncState()
}
@@ -683,9 +698,7 @@ private extension WorkflowSyncService {
func saveState(_ state: WorkflowSyncState) throws {
try fileManager.createDirectory(at: directoryURL, withIntermediateDirectories: true)
- let encoder = JSONEncoder()
- encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]
- let data = try encoder.encode(state)
+ let data = try JSONLines.stableEncoder.encode(state)
try data.write(to: stateURL, options: .atomic)
}
@@ -700,8 +713,7 @@ private extension WorkflowSyncService {
func saveCachedRecords(_ records: [WorkflowSyncedDailyRecord]) throws {
try fileManager.createDirectory(at: directoryURL, withIntermediateDirectories: true)
- let encoder = JSONEncoder()
- encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]
+ let encoder = JSONLines.stableEncoder
let data = try records
.sorted { lhs, rhs in
if lhs.deviceId == rhs.deviceId {
@@ -850,9 +862,7 @@ private extension WorkflowSyncService {
}
static func projectCountsData(_ counts: [String: Int]) -> Data {
- let encoder = JSONEncoder()
- encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]
- return (try? encoder.encode(counts)) ?? Data("{}".utf8)
+ (try? JSONLines.stableEncoder.encode(counts)) ?? Data("{}".utf8)
}
static func randomSalt() throws -> Data {
diff --git a/CodexBar/Views/Menu/CodexStatusMenuSections.swift b/CodexBar/Views/Menu/CodexStatusMenuSections.swift
index 605d9ab..1d0b478 100644
--- a/CodexBar/Views/Menu/CodexStatusMenuSections.swift
+++ b/CodexBar/Views/Menu/CodexStatusMenuSections.swift
@@ -295,7 +295,7 @@ struct WorkflowSyncDisplayState: Equatable {
}
init(isHookEnabled: Bool, settings: WorkflowSyncSettings) {
- guard isHookEnabled, settings.isEnabled, settings.isSyncAvailable else {
+ guard settings.isEffectivelyActive(isHookEnabled: isHookEnabled) else {
self = .disabled
return
}
diff --git a/CodexBar/Views/Menu/QuotaRow.swift b/CodexBar/Views/Menu/QuotaRow.swift
index 529659b..331f986 100644
--- a/CodexBar/Views/Menu/QuotaRow.swift
+++ b/CodexBar/Views/Menu/QuotaRow.swift
@@ -82,33 +82,17 @@ private extension QuotaRow {
}()
}
-/// 额度颜色按剩余百分比分档, 无数据时使用占位色
+/// 分档色值来自共享的 QuotaPalette, 无数据时使用占位色
private enum QuotaBarPalette {
static func filledColor(for percent: Int?) -> Color {
guard let percent else {
return placeholderColor
}
- switch percent {
- case 80...:
- return green
- case 60 ..< 80:
- return teal
- case 40 ..< 60:
- return yellow
- case 20 ..< 40:
- return orange
- default:
- return red
- }
+ return QuotaPalette.color(for: percent)
}
static let placeholderColor = Color(hex: 0xE5E7EB)
- private static let green = Color(hex: 0x16A085)
- private static let teal = Color(hex: 0x5DADE2)
- private static let yellow = Color(hex: 0xF5B041)
- private static let orange = Color(hex: 0xFF7A59)
- private static let red = Color(hex: 0xEE3F3F)
}
/// 胶囊条, 与菜单面板宽度联动
diff --git a/CodexBar/Views/Menu/ResetCreditsPanelView.swift b/CodexBar/Views/Menu/ResetCreditsPanelView.swift
index 0d41a74..25fbae2 100644
--- a/CodexBar/Views/Menu/ResetCreditsPanelView.swift
+++ b/CodexBar/Views/Menu/ResetCreditsPanelView.swift
@@ -64,16 +64,7 @@ struct ResetCreditsPanelView: View {
.padding(.horizontal, Metrics.horizontalPadding)
.padding(.vertical, Metrics.verticalPadding)
.frame(width: panelSize.width, height: panelSize.height, alignment: .topLeading)
- .liquidGlassSurface(cornerRadius: Metrics.cornerRadius, isOuterSurface: true)
- .background {
- RoundedRectangle(cornerRadius: Metrics.cornerRadius, style: .continuous)
- .fill(panelBackingFill)
- }
- .overlay {
- RoundedRectangle(cornerRadius: Metrics.cornerRadius, style: .continuous)
- .strokeBorder(panelBoundaryColor, lineWidth: Metrics.boundaryLineWidth)
- }
- .clipShape(RoundedRectangle(cornerRadius: Metrics.cornerRadius, style: .continuous))
+ .sidePanelChrome(cornerRadius: Metrics.cornerRadius)
.animation(Metrics.statusAnimation, value: context)
}
@@ -183,17 +174,6 @@ struct ResetCreditsPanelView: View {
.liquidGlassCapsule(tint: .green)
}
- private var panelBackingFill: Color {
- Color(nsColor: .windowBackgroundColor)
- .opacity(colorScheme == .dark ? 0.90 : 0.86)
- }
-
- private var panelBoundaryColor: Color {
- colorScheme == .dark
- ? .white.opacity(0.18)
- : .black.opacity(0.14)
- }
-
private enum Metrics {
static let expirationTextWidth: CGFloat = 123
static let horizontalPadding: CGFloat = 12
@@ -207,7 +187,6 @@ struct ResetCreditsPanelView: View {
static let dividerVerticalPadding: CGFloat = (rowSpacing - dividerHeight) / 2
static let verticalPadding: CGFloat = 10
static let cornerRadius: CGFloat = 12
- static let boundaryLineWidth: CGFloat = 0.8
static let statusAnimation = Animation.codexStatus
}
}
@@ -222,7 +201,7 @@ private struct ResetCreditExpirationGroup: Identifiable, Equatable {
static func grouped(from dates: [Date]) -> [Self] {
dates.sorted().reduce(into: [Self]()) { groups, date in
- let expirationText = expirationFormatter.string(from: date)
+ let expirationText = CodexDateFormat.localDisplayString(from: date)
if let lastIndex = groups.indices.last, groups[lastIndex].expirationText == expirationText {
groups[lastIndex].count += 1
@@ -231,11 +210,4 @@ private struct ResetCreditExpirationGroup: Identifiable, Equatable {
}
}
}
-
- private static let expirationFormatter: DateFormatter = {
- let formatter = DateFormatter()
- formatter.locale = Locale(identifier: "en_US_POSIX")
- formatter.dateFormat = "yyyy-MM-dd HH:mm:ss"
- return formatter
- }()
}
diff --git a/CodexBar/Views/Menu/ScreenFrameReader.swift b/CodexBar/Views/Menu/ScreenFrameReader.swift
index e57a262..bdd686a 100644
--- a/CodexBar/Views/Menu/ScreenFrameReader.swift
+++ b/CodexBar/Views/Menu/ScreenFrameReader.swift
@@ -63,20 +63,11 @@ final class ScreenFrameProvider {
view.layoutSubtreeIfNeeded()
let frameInWindow = view.convert(view.bounds, to: nil)
let screenFrame = window.convertToScreen(frameInWindow).standardized
- guard isValidScreenFrame(screenFrame) else {
+ guard screenFrame.isValidScreenRect else {
return nil
}
return screenFrame
}
-
- private static func isValidScreenFrame(_ frame: CGRect) -> Bool {
- frame.minX.isFinite
- && frame.minY.isFinite
- && frame.width.isFinite
- && frame.height.isFinite
- && frame.width > 0
- && frame.height > 0
- }
}
/// 只在 SwiftUI 布局稳定后上报 frame, 避免重渲染期间反复触发无效定位
diff --git a/CodexBar/Views/Menu/UsageHeatmap.swift b/CodexBar/Views/Menu/UsageHeatmap.swift
index 1760e0f..d7bb355 100644
--- a/CodexBar/Views/Menu/UsageHeatmap.swift
+++ b/CodexBar/Views/Menu/UsageHeatmap.swift
@@ -492,16 +492,7 @@ struct UsageHeatmapDayDetailView: View {
height: panelSize.height,
alignment: .topLeading
)
- .liquidGlassSurface(cornerRadius: Metrics.cornerRadius, isOuterSurface: true)
- .background {
- RoundedRectangle(cornerRadius: Metrics.cornerRadius, style: .continuous)
- .fill(panelBackingFill)
- }
- .overlay {
- RoundedRectangle(cornerRadius: Metrics.cornerRadius, style: .continuous)
- .strokeBorder(panelBoundaryColor, lineWidth: Metrics.boundaryLineWidth)
- }
- .clipShape(RoundedRectangle(cornerRadius: Metrics.cornerRadius, style: .continuous))
+ .sidePanelChrome(cornerRadius: Metrics.cornerRadius)
.animation(Metrics.statusAnimation, value: context)
}
@@ -717,17 +708,6 @@ struct UsageHeatmapDayDetailView: View {
.lineLimit(1)
}
- private var panelBackingFill: Color {
- Color(nsColor: .windowBackgroundColor)
- .opacity(colorScheme == .dark ? 0.90 : 0.86)
- }
-
- private var panelBoundaryColor: Color {
- colorScheme == .dark
- ? .white.opacity(0.18)
- : .black.opacity(0.14)
- }
-
private struct WorkflowMetricRow: Identifiable {
let label: String
let value: Int
@@ -748,7 +728,6 @@ struct UsageHeatmapDayDetailView: View {
static let horizontalPadding: CGFloat = 12
static let verticalPadding: CGFloat = 10
static let cornerRadius: CGFloat = 12
- static let boundaryLineWidth: CGFloat = 0.8
static let tokenMinimumWidth: CGFloat = 38
static let tokenUnitWidth: CGFloat = 14
static let metricSpacing: CGFloat = 5
diff --git a/CodexBar/Views/Settings/AppSettingsView.swift b/CodexBar/Views/Settings/AppSettingsView.swift
index f69bcb4..7567fd0 100644
--- a/CodexBar/Views/Settings/AppSettingsView.swift
+++ b/CodexBar/Views/Settings/AppSettingsView.swift
@@ -7,7 +7,6 @@ struct AppSettingsView: View {
@EnvironmentObject private var appUpdater: AppUpdater
@StateObject private var loginItemSettings = LoginItemSettings()
@StateObject private var codexVersions = CodexCLIVersionViewModel()
- @State private var lastMenuBarQuotaWindowSelection: MenuBarQuotaSelection = .primary
@ObservedObject var codexHookSettings: CodexHookSettings
@ObservedObject var syncSettings: WorkflowSyncSettings
@ObservedObject var globalHotKeySettings: GlobalHotKeySettings
@@ -60,20 +59,17 @@ struct AppSettingsView: View {
.onAppear {
loginItemSettings.refresh()
syncSettings.refresh()
- refreshMenuBarQuotaSettings()
+ menuBarQuotaSettings.refresh()
appUpdater.refreshAutomaticCheckSetting()
refreshCodexVersionSection()
}
.onReceive(NotificationCenter.default.publisher(for: NSApplication.didBecomeActiveNotification)) { _ in
codexHookSettings.refresh()
syncSettings.refresh()
- refreshMenuBarQuotaSettings()
+ menuBarQuotaSettings.refresh()
codexHookSettings.verifyInstalledHooks()
refreshCodexVersionSection()
}
- .onChange(of: menuBarQuotaSettings.selection) { _, selection in
- rememberMenuBarQuotaSelection(selection)
- }
}
}
@@ -134,8 +130,8 @@ private extension AppSettingsView {
Picker(
"额度窗口",
selection: Binding(
- get: { activeMenuBarQuotaSelection },
- set: { setMenuBarQuotaWindowSelection($0) }
+ get: { menuBarQuotaSettings.activeWindowSelection },
+ set: { menuBarQuotaSettings.setSelection($0) }
)
) {
ForEach(menuBarQuotaWindowOptions) { option in
@@ -153,7 +149,7 @@ private extension AppSettingsView {
"菜单栏额度指示",
isOn: Binding(
get: { isMenuBarQuotaEnabled },
- set: { setMenuBarQuotaEnabled($0) }
+ set: { menuBarQuotaSettings.setEnabled($0) }
)
)
.labelsHidden()
@@ -173,7 +169,7 @@ private extension AppSettingsView {
return MenuBarQuotaOption(selection: selection, title: window.label)
}
- let selectedWindow = activeMenuBarQuotaSelection
+ let selectedWindow = menuBarQuotaSettings.activeWindowSelection
if !options.contains(where: { $0.selection == selectedWindow }) {
options.append(
MenuBarQuotaOption(
@@ -186,46 +182,10 @@ private extension AppSettingsView {
return options
}
- var activeMenuBarQuotaSelection: MenuBarQuotaSelection {
- let selection = menuBarQuotaSettings.selection
- return selection == .off ? lastMenuBarQuotaWindowSelection : selection
- }
-
var isMenuBarQuotaEnabled: Bool {
menuBarQuotaSettings.selection != .off
}
- func setMenuBarQuotaWindowSelection(_ selection: MenuBarQuotaSelection) {
- rememberMenuBarQuotaSelection(selection)
- menuBarQuotaSettings.setSelection(selection)
- }
-
- func setMenuBarQuotaEnabled(_ enabled: Bool) {
- if !enabled {
- rememberMenuBarQuotaSelection(menuBarQuotaSettings.selection)
- menuBarQuotaSettings.setSelection(.off)
- return
- }
-
- setMenuBarQuotaWindowSelection(activeMenuBarQuotaSelection)
- }
-
- func refreshMenuBarQuotaSettings() {
- menuBarQuotaSettings.refresh()
- rememberMenuBarQuotaSelection()
- }
-
- func rememberMenuBarQuotaSelection(
- _ selection: MenuBarQuotaSelection? = nil
- ) {
- let selection = selection ?? menuBarQuotaSettings.selection
- guard selection != .off else {
- return
- }
-
- lastMenuBarQuotaWindowSelection = selection
- }
-
var codexHookRow: some View {
VStack(alignment: .leading, spacing: 4) {
SettingsToggleRow(
@@ -255,9 +215,6 @@ private extension AppSettingsView {
isOn: Binding(
get: { state.isActive },
set: { enabled in
- guard codexHookSettings.isEnabled, state.isSyncAvailable else {
- return
- }
guard syncSettings.setEnabled(enabled) else {
return
}
@@ -363,7 +320,7 @@ private extension AppSettingsView {
@ViewBuilder
var settingsErrorPanel: some View {
- if let message = settingsErrorMessage {
+ if let message = loginItemSettings.errorMessage {
Text(message)
.font(.caption)
.foregroundStyle(.red)
@@ -391,10 +348,6 @@ private extension AppSettingsView {
.foregroundStyle(.red)
.keyboardShortcut("q")
}
-
- var settingsErrorMessage: String? {
- loginItemSettings.errorMessage
- }
}
private struct SyncRowState {
diff --git a/CodexBar/Views/Shared/LiquidGlassStyle.swift b/CodexBar/Views/Shared/LiquidGlassStyle.swift
index 280cfb7..76fd636 100644
--- a/CodexBar/Views/Shared/LiquidGlassStyle.swift
+++ b/CodexBar/Views/Shared/LiquidGlassStyle.swift
@@ -12,7 +12,7 @@ extension Color {
static let codexLabel = Color(nsColor: .labelColor)
static let codexSecondaryLabel = Color(nsColor: .secondaryLabelColor)
- init(hex: Int) {
+ nonisolated init(hex: Int) {
self.init(
red: Double((hex >> 16) & 0xFF) / 255.0,
green: Double((hex >> 8) & 0xFF) / 255.0,
@@ -60,6 +60,41 @@ extension View {
func markStale(_ isStale: Bool) -> some View {
opacity(isStale ? 0.55 : 1)
}
+
+ /// 侧边详情面板统一的外观: 玻璃底 + 背板填充 + 边界描边 + 圆角裁剪
+ func sidePanelChrome(cornerRadius: CGFloat) -> some View {
+ modifier(SidePanelChrome(cornerRadius: cornerRadius))
+ }
+}
+
+private struct SidePanelChrome: ViewModifier {
+ let cornerRadius: CGFloat
+ @Environment(\.colorScheme) private var colorScheme
+
+ func body(content: Content) -> some View {
+ content
+ .liquidGlassSurface(cornerRadius: cornerRadius, isOuterSurface: true)
+ .background {
+ RoundedRectangle(cornerRadius: cornerRadius, style: .continuous)
+ .fill(backingFill)
+ }
+ .overlay {
+ RoundedRectangle(cornerRadius: cornerRadius, style: .continuous)
+ .strokeBorder(boundaryColor, lineWidth: 0.8)
+ }
+ .clipShape(RoundedRectangle(cornerRadius: cornerRadius, style: .continuous))
+ }
+
+ private var backingFill: Color {
+ Color(nsColor: .windowBackgroundColor)
+ .opacity(colorScheme == .dark ? 0.90 : 0.86)
+ }
+
+ private var boundaryColor: Color {
+ colorScheme == .dark
+ ? .white.opacity(0.18)
+ : .black.opacity(0.14)
+ }
}
/// 分区之间的细分隔线, 与玻璃背景保持低对比
diff --git a/CodexBar/Views/Shared/QuotaPalette.swift b/CodexBar/Views/Shared/QuotaPalette.swift
new file mode 100644
index 0000000..b7ff4b5
--- /dev/null
+++ b/CodexBar/Views/Shared/QuotaPalette.swift
@@ -0,0 +1,39 @@
+import AppKit
+import SwiftUI
+
+/// 额度颜色按剩余百分比分档, 菜单栏图标与面板额度条共用同一套阈值和色值
+nonisolated enum QuotaPalette {
+ static func hex(for percent: Int) -> Int {
+ switch percent {
+ case 80...:
+ 0x16A085
+ case 60 ..< 80:
+ 0x5DADE2
+ case 40 ..< 60:
+ 0xF5B041
+ case 20 ..< 40:
+ 0xFF7A59
+ default:
+ 0xEE3F3F
+ }
+ }
+
+ static func color(for percent: Int) -> Color {
+ Color(hex: hex(for: percent))
+ }
+
+ static func nsColor(for percent: Int) -> NSColor {
+ NSColor(hex: hex(for: percent))
+ }
+}
+
+nonisolated extension NSColor {
+ convenience init(hex: Int) {
+ self.init(
+ red: CGFloat((hex >> 16) & 0xFF) / 255.0,
+ green: CGFloat((hex >> 8) & 0xFF) / 255.0,
+ blue: CGFloat(hex & 0xFF) / 255.0,
+ alpha: 1
+ )
+ }
+}
diff --git a/Docs/CodexHook.md b/Docs/CodexHook.md
index a2c7029..72a3d3f 100644
--- a/Docs/CodexHook.md
+++ b/Docs/CodexHook.md
@@ -10,6 +10,8 @@
~/.codex/hooks.json
```
+Codex 配置目录统一由 `CodexCLIResolver.codexHomeDirectory()` 解析: 优先环境变量 `CODEX_HOME`,否则回退真实用户 `HOME` 下的 `.codex`。`hooks.json` 与 `CodexResetCreditsService` 读取的 `auth.json` 使用同一口径。
+
开启前会先复用 App 当前的 Codex app-server 会话调用 `config/read`。如果有效配置中 `[features] hooks = false`,或兼容旧名 `codex_hooks = false`,CodexBar 不写入 `hooks.json`,并在 Hook 选项下方显示全局禁用说明。
开启和关闭都会先移除 `command` 包含当前 App 可执行文件路径的 CodexBar hook。开启时随后按当前 App 路径安装 hook。用户自定义 Hook、其他 App Hook 和同事件下的其他处理器必须保留。
@@ -133,7 +135,7 @@ Hook 可能由多个 Codex 进程并发触发。`WorkflowHookEventRecorder` 会
1. 解析事件时间并格式化为本机时间戳与 date key
2. 追加当前事件到 `events/YYYY-MM-DD.jsonl`
-3. 将 date key 加入 `maintenance.json` 的 `pending`
+3. 将 date key 加入 `maintenance.json` 的 `pending`;如果当天已在 `pending` 且已有日期状态记录(稳态下的绝大多数事件),跳过 `maintenance.json` 重写
Hook 写入路径不更新 `daily.jsonl`,也不执行重建或清理旧文件,避免在 Hook timeout 内持锁执行重活。
diff --git a/Docs/CrossDeviceSync.md b/Docs/CrossDeviceSync.md
index 72cb9b1..4c546f7 100644
--- a/Docs/CrossDeviceSync.md
+++ b/Docs/CrossDeviceSync.md
@@ -221,7 +221,7 @@ WorkflowService.loadSnapshot(performMaintenance: true, synchronize: true)
- 同步账号从不可用变为可用,且 Hook 与跨设备同步都已开启
- app-server 自动刷新倒计时重置时,如果 Hook、跨设备同步和同步账号都可用
-Hook 子进程不访问网络。它只把原始事件写入本机 `events/YYYY-MM-DD.jsonl` 并标记 `maintenance.json` 的 pending 日期。真正的 daily 重建和 CloudKit 同步都由主 App 的维护刷新完成。
+Hook 子进程不访问网络。它只把原始事件写入本机 `events/YYYY-MM-DD.jsonl` 并标记 `maintenance.json` 的 pending 日期(当天已 pending 时跳过重写)。真正的 daily 重建和 CloudKit 同步都由主 App 的维护刷新完成。
调度器规则:
@@ -253,6 +253,8 @@ flowchart TD
N --> O["保存 state 并合并快照"]
```
+「确保 CodexBarZone 存在」和「读取或创建 accountSalt」首次成功后会在 `WorkflowSyncService` actor 内跨轮缓存,后续每轮同步直接复用,不再重复往返 CloudKit。任何一轮同步失败都会作废这两项缓存:iCloud 账号切换必然伴随请求报错,因此下一轮会重新确认 zone、按新账号取 salt,并经 deviceId 变化检测重置本地同步状态。
+
同步服务会在开始和结束时发出通知:
```text
@@ -286,6 +288,8 @@ CodexBar.workflowSyncDidFinish
+ needsBackfill 为 true 时的全部本机日期
```
+「本轮维护后内容发生变化的日期」通过对比维护前后的脱敏同步 payload 得出;只有本轮会实际执行同步(`synchronize: true` 且 `WorkflowSync.isEnabled == true`)时才会计算,其余维护刷新跳过这两次全量对比。
+
对每个候选日期:
1. 找到本机 daily 聚合。
diff --git a/Docs/DevelopmentGuide.md b/Docs/DevelopmentGuide.md
index 85b3c38..c0588f7 100644
--- a/Docs/DevelopmentGuide.md
+++ b/Docs/DevelopmentGuide.md
@@ -95,7 +95,7 @@ App 退出时, `applicationWillTerminate` 调用 `StatusItemController.uninstall
正常图标是 `person.fill.checkmark`, 错误图标是 `person.fill.xmark`
-设置页「菜单栏额度指示」默认开启, 使用独立开关控制启用状态; 缺失持久化选择时默认使用 `.primary`, 关闭时显式持久化 `.off`。开启后在同一行显示额度窗口菜单, 可选择当前账号 Codex limit 返回的额度窗口, 当前保留选择不在返回窗口中时用 fallback 标题追加到菜单。关闭开关时, 设置页保留最后一个非关闭窗口值参与菜单淡出, 避免过渡期间回退到默认窗口。关闭时菜单栏只使用系统 template 图标; 开启后 `StatusItemController` 会把所选 Codex 窗口的剩余额度进度条绘制在图标左侧, 以竖条形式与 `person.fill.checkmark` / `person.fill.xmark` 合成为单个 `NSImage`, 并随 `CodexStatusViewModel` 自动刷新。合成图尺寸为 `27 x 17`, 图标本体保持原始 `24 x 17`, 左侧竖条轨道为 `2 x 15`。开启或关闭进度条时, `StatusItemController` 用逐帧重绘的方式对左侧竖条透明度做 0.18 秒过渡; 过渡期间合成图宽度和图标绘制坐标保持固定。
+设置页「菜单栏额度指示」默认开启, 使用独立开关控制启用状态; 缺失持久化选择时默认使用 `.primary`, 关闭时显式持久化 `.off`。开启后在同一行显示额度窗口菜单, 可选择当前账号 Codex limit 返回的额度窗口, 当前保留选择不在返回窗口中时用 fallback 标题追加到菜单。最后一次非关闭的窗口选择由 `MenuBarQuotaSettings` 以 `MenuBarQuota.lastWindowSelection` 键随偏好持久化: 关闭开关时它继续参与菜单淡出避免过渡期间回退, 重新开启时(含重开设置窗口或重启应用后)恢复该选择, 无记录时回退 `.primary`。关闭时菜单栏只使用系统 template 图标; 开启后 `StatusItemController` 会把所选 Codex 窗口的剩余额度进度条绘制在图标左侧, 以竖条形式与 `person.fill.checkmark` / `person.fill.xmark` 合成为单个 `NSImage`, 并随 `CodexStatusViewModel` 自动刷新。合成图尺寸为 `27 x 17`, 图标本体保持原始 `24 x 17`, 左侧竖条轨道为 `2 x 15`。开启或关闭进度条时, `StatusItemController` 用逐帧重绘的方式对左侧竖条透明度做 0.18 秒过渡; 过渡期间合成图宽度和图标绘制坐标保持固定。
错误图标触发条件:
@@ -157,7 +157,7 @@ Command-Space 不直接关闭菜单面板, 只短暂抑制 600 ms 内的 active
热力图详情面板和重置次数详情面板都会通过 `containsScreenPoint(_:)` 告诉关闭监听器自己的屏幕区域, 因此点击这些 child panel 内部不会触发主菜单面板关闭。重置次数详情面板可接收鼠标事件用于滚动; 热力图详情面板不接收鼠标事件。
-两个侧边详情面板的共同行为集中在 `CodexBar/Controllers/SidePanelSupport.swift`: `NonactivatingSidePanel` 固定不能成为 key/main window, `SidePanelDrawerAnimator` 管理内容 view 的横向抽屉 transform, `SidePanelSupport` 管理 child window 挂载/移除、菜单面板 key window 恢复、圆角 layer 配置、屏幕 frame 换算、左右侧选择和坐标夹紧。`HeatmapDetailPanelController` 主要保留 hover 请求、侧边切换队列和 token/workflow 内容更新; `ResetCreditsPanelController` 主要保留重置次数内容、额度区锚点校验、最大高度和点击切换状态。
+两个侧边详情面板的共同行为集中在 `CodexBar/Controllers/SidePanelSupport.swift`: `NonactivatingSidePanel` 固定不能成为 key/main window, `SidePanelDrawerAnimator` 管理内容 view 的横向抽屉 transform, `SidePanelSupport` 提供 panel 工厂(`makePanel`, 仅 `ignoresMouseEvents` 与初始尺寸由调用方决定)、完整定位入口(`position`, 内含左右侧选择、坐标夹紧与 `SidePanelPosition` 组装, 纵向由调用方传入期望位置)、共享几何/抽屉动画常量(`SidePanelSupport.Metrics`), 以及 child window 挂载/移除、菜单面板 key window 恢复、圆角 layer 配置和屏幕 frame 换算。`HeatmapDetailPanelController` 主要保留 hover 请求、Y 轴策略、侧边切换队列和 token/workflow 内容更新; `ResetCreditsPanelController` 主要保留重置次数内容、额度区锚点校验、最大高度和点击切换状态。两个面板视图的玻璃底/背板/描边/圆角裁剪皮肤共用 `LiquidGlassStyle.swift` 的 `sidePanelChrome(cornerRadius:)`。
设置窗口和日志窗口都继承 `HostingWindowController` 的行为: 懒创建, 关闭后不释放, 重新打开复用, 按当前屏幕居中, 重新打开对应入口时只移动和置前对应窗口。窗口 level 保持 `.normal`; 置前时先恢复 `AuxiliaryHostingWindow.allowsKeyFocus`, 再 `orderFrontRegardless()`, `NSRunningApplication.current.activate(options: [])` 和 `makeKeyAndOrderFront(nil)`, 只做一次性置前, 不持续置顶。CodexBar 是 `LSUIElement` 菜单栏 App, 首次懒创建辅助窗口时需要通过当前运行中应用激活, 避免设置或日志窗口第一次打开时没有稳定拉到最前。
@@ -610,6 +610,8 @@ Hook 开启且当天没有 token bucket 时, 今天的 token 数显示 `--`。
~/.codex/hooks.json
```
+该路径由 `CodexCLIResolver.codexHomeDirectory()` 统一解析: 优先环境变量 `CODEX_HOME`, 否则回退真实用户 `HOME` 下的 `.codex`, 与 `CodexResetCreditsService` 读取 `auth.json` 的口径一致。
+
开启前会复用 App 当前的 `CodexStatusService` app-server 会话调用 `config/read`, 如果有效配置中 `[features] hooks = false` 或兼容旧名 `codex_hooks = false`, 则不写入 Hook, 并在 Hook 选项下方提示。`config/read` 请求失败时同样不写入 Hook, 并显示"设置 Codex Hook 失败"。开启写入后会继续调用 `hooks/list`, 检查 Codex 实际识别到的 `command`, `eventName`, `enabled`, `sourcePath`, `trustStatus`, `key`, `currentHash`, `warnings` 和 `errors`。如果 `trustStatus` 是 `untrusted` 或 `modified`, CodexBar 只对 `sourcePath` 指向全局 `~/.codex/hooks.json` 且 command 属于当前 CodexBar 的 Hook, 用 `config/batchWrite` 把对应 `trusted_hash` upsert 到 `hooks.state` 并重新 `hooks/list` 验证。`hooks/list`、自动信任写入或验证未通过不会回滚已写入 Hook, 只在 Hook 选项下方显示验证摘要。这些 app-server 请求和响应都会进入日志窗口。
下面的时序图展示开启 Hook, Codex 触发事件, 本机写入, 后台维护, 以及常见错误后的处理
@@ -862,7 +864,7 @@ UI 展示指标来自 `WorkflowDailyAggregate.metrics`:
| 权限请求 | `permissionRequestCount` |
| 上下文压缩 | `max(preCompactCount, postCompactCount)` |
-跨设备同步只在 `performMaintenance: true, synchronize: true` 的刷新中执行。`WorkflowSyncScheduler` 会合并同步开关、Hook 重新开启、同步账号恢复可用和自动刷新产生的同步请求;同步中不取消重启, 冷却窗口内只保留一次待补跑请求, 补跑前重新校验 Hook 开启、跨设备同步偏好为 true 且同步账号可用。`WorkflowSyncService` 先用本机 daily 聚合生成脱敏 `WorkflowSyncedDailyAggregate`, 再按日期稳定排序候选项, 每批最多上传 25 天, 每轮最多使用 20 秒。每批成功后立即保存 `state.hashByDate` 和 `lastUploadAt`, 未完成的 backfill 留给后续自动刷新继续。没有 `cursor.data` 时先 query 全量 `CodexBarDailyAggregate` 回填 `cache.jsonl`; 有游标时优先拉 CloudKit 增量, 游标失效或增量失败时不写入日志窗口, 直接全量重建缓存。写入 `cache.jsonl` 前会过滤当前设备自己的记录, 只保留其他设备记录。增量路径先写 `cache.jsonl`, 成功后再写 `cursor.data`, 避免游标提前推进导致未落盘记录被跳过。同步失败会通过 `CodexBar.workflowSyncDidFinish` 通知发送 `didSucceed=false` 和归类后的 `failureMessage`, 主面板同步图标进入失败态。
+跨设备同步只在 `performMaintenance: true, synchronize: true` 的刷新中执行。`WorkflowSyncScheduler` 会合并同步开关、Hook 重新开启、同步账号恢复可用和自动刷新产生的同步请求;同步中不取消重启, 冷却窗口内只保留一次待补跑请求, 补跑前重新校验 Hook 开启、跨设备同步偏好为 true 且同步账号可用。`WorkflowSyncService` 先用本机 daily 聚合生成脱敏 `WorkflowSyncedDailyAggregate`, 再按日期稳定排序候选项, 每批最多上传 25 天, 每轮最多使用 20 秒。zone 存在性确认和 account salt 首次成功后在 actor 内跨轮缓存, 任一轮同步失败时作废, 下一轮重新确认(覆盖 iCloud 账号切换)。每批成功后立即保存 `state.hashByDate` 和 `lastUploadAt`, 未完成的 backfill 留给后续自动刷新继续。没有 `cursor.data` 时先 query 全量 `CodexBarDailyAggregate` 回填 `cache.jsonl`; 有游标时优先拉 CloudKit 增量, 游标失效或增量失败时不写入日志窗口, 直接全量重建缓存。写入 `cache.jsonl` 前会过滤当前设备自己的记录, 只保留其他设备记录。增量路径先写 `cache.jsonl`, 成功后再写 `cursor.data`, 避免游标提前推进导致未落盘记录被跳过。同步失败会通过 `CodexBar.workflowSyncDidFinish` 通知发送 `didSucceed=false` 和归类后的 `failureMessage`, 主面板同步图标进入失败态。
## 13. 设置窗口流程
@@ -896,7 +898,7 @@ App 再次成为 active 时, 也会刷新 Codex 版本区、同步可用性, 并
| --------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| 开机自动启动 | `SMAppService.mainApp.status` | `register()` / `unregister()` |
| 自动检查更新 | Sparkle updater | 设置 `automaticallyChecksForUpdates` |
-| 菜单栏额度指示 | `MenuBarQuotaSettings.selection` | 开关写入 `.off` 或当前保留窗口, 窗口菜单写入所选窗口; 标签优先来自当前账号 Codex limit 返回的额度窗口, 缺失时使用 fallback 标题 |
+| 菜单栏额度指示 | `MenuBarQuotaSettings.selection` / `MenuBarQuota.lastWindowSelection` | 开关写入 `.off` 或恢复持久化的上次窗口选择, 窗口菜单写入所选窗口并同步记住; 标签优先来自当前账号 Codex limit 返回的额度窗口, 缺失时使用 fallback 标题 |
| 使用快捷键 | `GlobalHotKeySettings.shortcut` | 写入 `UserDefaults` 并注册 hot key |
| 启用 Codex Hook | app-server `config/read` / `hooks/list` / `config/batchWrite`, `~/.codex/hooks.json` | 检查全局 Hook 开关后追加或移除当前 CodexBar command hook, 并维护对应 `hooks.state` 信任状态 |
| 跨设备同步 | `WorkflowSyncSettings` + CloudKit account status + `WorkflowSyncScheduler` | Hook 开启且同步账号可用时写入 `UserDefaults`; 开启时标记 `needsBackfill` 并请求调度同步 |
@@ -1052,7 +1054,7 @@ App 再次成为 active 时, 也会刷新 Codex 版本区、同步可用性, 并
文件写入安全:
-- Hook 子进程只在锁内追加当天 `events/YYYY-MM-DD.jsonl` 并更新 `maintenance.json`
+- Hook 子进程只在锁内追加当天 `events/YYYY-MM-DD.jsonl` 并更新 `maintenance.json`, pending 状态无变化时跳过重写
- 主 App 维护 `daily.jsonl` 时, 先锁外原子写 daily, 再短暂持锁提交维护状态, 减少阻塞 Hook 写入
- `maintenance.json` 和 `daily.jsonl` 使用 atomic write
- 设置 Hook 时通过当前 app-server 会话先读 `config/read`, 未全局禁用时 pretty printed 写回 `~/.codex/hooks.json`, 只移除 command 同时包含当前 App 可执行路径和 `--hook-event` 参数的 handler, 写入后再用 `hooks/list` 验证有效状态;未信任或已修改时, 仅把当前 CodexBar command 且来源为全局 `hooks.json` 的 `key/currentHash` 通过 `config/batchWrite` 写入 `hooks.state`