Skip to content

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

feat: 支持任务流光颜色预览并保留真实提示时长

Bobb306adcd54f4
diff --git a/AGENTS.md b/AGENTS.md
index 5444dc1..70b4239 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,5 +1,57 @@
# Repository Guidelines
+## 语言要求
+
+始终使用简体中文回答,代码、命令、专有名词和用户明确要求保留的原文除外。
+
+## 实现原则
+
+在目标和约束明确的前提下,优先选择全生命周期综合成本最低的方案,兼顾当前实现、后续维护、可扩展性和未来调整的自由度。
+
+- 评估技术债务、路径依赖、维护复杂度和未来重构成本,必要时承担合理的一次性结构调整成本
+- 保持实现简单、清晰、实用,以尽可能少的概念、状态、依赖和特殊规则解决问题
+- 保持核心逻辑易于理解和验证,模块边界明确、职责合理,优先复用已有能力
+- 处理必要的边界条件和异常场景,为可预见的变化保留空间
+- 对生命周期短、影响范围小或需求高度不确定的问题控制前期投入,不为假设中的需求设计复杂架构
+- 让实现和维护成本与业务价值相匹配;长期收益与当前简洁性发生冲突时,说明生命周期、变更概率、影响范围、可逆性和未来修正成本等权衡依据
+
+## 判断与行动原则
+
+### 从目标和事实出发
+
+运用第一性原理分析目标、约束和因果关系。经验、惯例和既有路径可以作为参考,不能替代事实和推理。
+
+- 识别用户真正的目标、问题的事实依据、已知约束、未知信息、隐含前提和验收标准,不默认用户已完整定义问题
+- 信息可以从现有代码、文档、工具或环境获得时,先自行验证,不把可自行解决的问题交还给用户
+- 区分已确认事实、基于事实的推断、尚待验证的假设和无法确定的部分,不把推测表达为事实
+- 关键前提不成立时,先指出事实依据及其对结论的影响,再给出可落地的替代方案
+- 证据不足时,明确缺失信息、不确定性及验证方式
+
+### 根据清晰度和影响决定行动
+
+| 情况 | 行动 |
+| --- | --- |
+| 目标清晰、路径合理 | 直接执行 |
+| 目标清晰、当前路径明显不是最优 | 完成合理范围内的任务,同时指出更简单、成本更低或风险更低的替代方案 |
+| 目标模糊,但可通过低风险、可逆的假设推进 | 明确假设后执行 |
+| 目标模糊,且不同选择会显著影响结果 | 暂停实施,确认关键问题 |
+
+涉及兼容性问题时,遵守下文代码修改原则中的确认要求。
+
+### 给出可验证的判断
+
+能量化时使用数字,能形成明确结论时直接表态,不用模糊措辞或表面中立代替判断。根据问题需要,说明结论及适用边界、事实依据与推导、关键风险与失败条件、实施步骤、验证方法和验收标准。
+
+## 沟通原则
+
+优先直接回答当前问题,给出结果、方案、代码、命令或操作步骤,再按需补充分析。简单、明确的问题直接处理,避免长篇铺垫,不重复确认已经明确的信息。
+
+- 仅在手段偏离目标、关键前提或约束缺失、存在隐藏的长期成本、有明显更优的替代方案,或涉及安全、合规、数据损失及不可逆后果时,审慎挑战原始需求
+- 挑战时说明事实依据、推导和实际影响,并给出可执行的替代方案;不机械质疑,不揣测用户动机
+- 忠于事实和可验证的推理,不迎合预期,不为表面中立回避判断,不把观点分歧升级为立场对抗
+- 保持尊重、直接和坚定;用户提供更可靠的事实或推导后,及时修正结论并说明依据,不作无意义的辩护
+- 以共同得到准确、低成本且能落地的结果为目标,不以证明谁正确为目标
+
## 项目结构与模块组织
CodexBar 是面向 macOS 15+ 的 `LSUIElement` 菜单栏应用,使用 Swift 6, SwiftUI, AppKit 和 MVVM。工程只有 `CodexBar` scheme,包含主 App、`CodexBarHelper` 和 `CodexBarTests` 三个 target。
@@ -50,25 +102,39 @@ CodexBar 是面向 macOS 15+ 的 `LSUIElement` 菜单栏应用,使用 Swift 6,
## 架构与编码约定
-启动时必须先调用 `WorkflowHookEventRecorder.handleIfRequested()` 方法。`--hook-event` 模式从 `stdin` 接收事件,按需有界读取 rollout 元数据,加锁写入 JSONL 并立即退出,不初始化 UI,失败也不能阻断 Codex。Handler 超时按事件从 `hookTimeoutSeconds(for:)` 取得,`SessionEnd` 和 `Interrupt` 为 3 秒,其他事件为 5 秒。普通模式由 `CodexBarAppDelegate` 统一装配长期服务。
-
-工程默认采用 `MainActor` 隔离。UI, Controller, ViewModel 和 Settings 依赖默认隔离,共享可变状态放入 actor,DTO 和跨 actor 值类型按需添加 `nonisolated` 标记,禁止在主 actor 执行阻塞 I/O。类型命名使用 `UpperCamelCase` 风格,成员命名使用 `lowerCamelCase` 风格。注释只解释非显然的生命周期、焦点、actor 或系统 API 约束。
-
-保持三条数据链路独立:app-server 额度与用量、Hook 历史聚合、`CodexActivityMonitor` 实时任务。helper 只能执行固定的睡眠控制和自动重置唤醒计划,不得增加网络、任意命令执行或额外文件访问。账户主链路必须检查当前 app-server 的实际版本不低于 `0.145.0`。修改 Hook 配置时必须保留用户和其他应用已有的 handler。启用和校验 Hook 必须额外检查当前 app-server 的实际版本不低于 `0.150.0`。新增网络访问、日志数据或 CloudKit 字段前先核对隐私边界。
+### 启动与并发边界
-自动重置默认关闭,提前量可选 15 分钟、30 分钟、1 小时、2 小时、4 小时或 6 小时,默认 30 分钟。状态机只处理新鲜响应明确列出的 `available + codexRateLimits + expiresAt` 凭证,每轮连续重试最多 5 分钟。CodexBarHelper 只接收有限时间戳,使用固定 owner 和固定 `wake` 类型维护一个系统事件;目标变化、功能关闭、App 退出、对应 XPC 连接断开或 helper 启动时必须收敛并清理该事件。修改 owner 或事件类型属于清理兼容性问题。
+- Hook 事件模式必须先于 UI 和长期服务初始化,处理完成后立即退出,失败不能阻断 Codex
+- Hook 处理必须限制读取量和执行时间,并发写入必须加锁
+- 普通模式由 App 的统一入口装配长期服务
+- 工程默认采用 `MainActor` 隔离,共享可变状态放入 actor,跨 actor 值类型按需声明 `nonisolated`,禁止在主 actor 执行阻塞 I/O
+- 类型命名使用 `UpperCamelCase`,成员命名使用 `lowerCamelCase`
-自动重置和防睡眠从关闭切换为开启时必须先显示确认框。确认文案按 `HelperStatus` 展示:`.notRegistered` 和 `.notFound` 使用 `需要安装并授权 CodexBar Helper 后台运行`,`.requiresApproval` 使用 `已安装 CodexBar Helper 但需要授权允许后台运行`,`.enabled` 只显示对应功能说明。确认后写入用户意图并触发 helper 注册,Helper 授权系统设置仅由设置行的 `打开系统设置` 按钮显式打开。两个开关关闭时不显示状态说明。自动重置子面板入口仅在开关开启且 helper 状态为 `.enabled` 时显示,条件失效时关闭已展开面板。
+### 数据链路与权限边界
-缺少 session ID 的 Hook 事件使用匿名 project key。匿名任务保留在实时快照和 UI 中,活动卡片与任务中心统一显示橙色 `person.crop.circle.dashed` 图标,`help` 为 `匿名任务不参与防睡眠`。匿名任务不发布任务通知或触觉反馈,不参与防睡眠和异常会话保护,不生成保护状态持久化标识。活动卡片的 `+N` 只显示其他活跃任务总数。
+- 保持 app-server 额度与用量、Hook 历史聚合、实时任务三条数据链路独立
+- 账户主链路、Hook 启用与校验必须分别检查当前 app-server 的实际版本是否满足各自最低要求
+- 修改 Hook 配置时必须保留用户和其他应用已有的 handler
+- helper 只能执行固定的睡眠控制和自动重置唤醒计划,不得增加网络、任意命令执行或额外文件访问
+- 新增网络访问、日志数据或 CloudKit 字段前先核对隐私边界
+- 开启自动重置或防睡眠前必须取得用户确认,打开 helper 授权系统设置必须由用户显式操作触发
-`CodexActivityMonitor` 的异常会话保护跟随防睡眠主开关,只判定非匿名运行中任务,等待批准任务不参与判定。静默阈值可选 30 分钟, 1, 2 或 4 小时,默认 1 小时。Hook bootstrap、系统睡眠、唤醒恢复或 Hook 数据源不可用期间必须暂停判定,数据恢复后统一无通知对账。
+### 生命周期与资源清理
-`HookEventTailReader.drainNow()` 是读取屏障,每个调用方必须等待一轮在本次请求之后开始的读取。系统唤醒只有在该轮读取成功后才执行 rollout 生命周期对账并恢复异常会话保护判定。reader 更换时丢弃旧结果,数据源不可用或任务取消时不得使用旧快照继续判定。
+- 自动重置只处理新鲜响应中明确可用且具备用量和有效期信息的凭证,重试必须有界
+- helper 只接受有限时间戳,维护单一的系统唤醒计划;目标变化、功能关闭、App 退出、对应连接断开或 helper 启动时必须收敛并清理计划
+- 修改唤醒事件的归属或类型时,必须考虑旧版本遗留事件的清理兼容性
+- 异常会话保护跟随防睡眠开关,只判定非匿名运行中任务,等待批准任务不参与判定
+- Hook 初始化、系统睡眠、唤醒恢复或数据源不可用期间暂停异常会话判定,数据恢复后执行无通知对账
+- 主动排空 Hook 读取是屏障,每个调用方必须等待一轮在本次请求之后开始的读取;唤醒后只有该轮读取成功,才能执行生命周期对账并恢复保护判定
+- reader 更换时丢弃旧结果,数据源不可用或任务取消时不得使用旧快照继续判定
-异常会话保护记录由 `ActivityProtectionStateStore` 保存在 `~/Library/Application Support/CodexBar/ActivityProtection/state.json`,只包含哈希任务标识和时间戳,最长保留到最后进展后的 24 小时。Debug 与 Release 通过 `flock` 共用该文件,当前 schema 为 `1`。修改格式或身份计算属于兼容性问题。
+### 数据语义与兼容性
-需要从原始 Hook 事件重新计算的聚合算法、输出字段、字段含义或去重规则变化时,必须递增 `WorkflowMaintenanceState.currentAggregationSchema`,统一从保留期内的原始 JSONL 完整重建,不新增字段级历史迁移。Hook 计数字段缺失表示历史来源不可用,不能解码成明确的 `0`
+- 缺少会话标识的任务按匿名任务处理,保留在实时快照和 UI 中,不发布任务通知或触觉反馈,不参与防睡眠和异常会话保护,不生成持久化保护标识
+- 异常会话保护记录只保存哈希任务标识和必要时间戳,保留时间必须有界;Debug 与 Release 共用的数据必须跨进程加锁,修改存储格式或身份计算属于兼容性问题
+- 聚合算法、输出字段、字段含义或去重规则变化,需要重新计算历史数据时,必须递增聚合 schema,从保留期内的原始事件完整重建,不新增字段级历史迁移
+- Hook 计数字段缺失表示历史来源不可用,不能解释为明确的零值
## 测试规范
@@ -103,5 +169,6 @@ Tag 名 `v{MARKETING_VERSION}` 里的版本号从 `Config/Version.xcconfig` 读
- 改 shared controller、shared service、模型解析或持久化 key 时,要考虑旧数据和降级路径;用户设置要保持默认值;持久化 key 和旧版本迁移兼容
- **任何兼容性问题都必须主动询问用户,不要自行决定**;只要改动会影响新旧共存就适用,不限于旧数据迁移或丢弃、持久化 key 改名或改结构、老版本升上来的降级路径、最低系统版本与 API 可用性取舍、云端记录格式变更;先说清影响面和几种做法的代价,等用户选定再动手
- 处理窗口、菜单、快捷键、App 激活或事件监听时,特别注意 `LSUIElement` 应用特有的焦点行为
+- 不做辅助功能(Accessibility)适配,不新增辅助功能标签、特征或操作
- 注释保持克制,只解释非显然的生命周期、焦点、actor 或系统 API 约束;现有注释多为解释为什么的类型,沿用同样风格
- 改动涉及菜单面板、窗口焦点、Hook、同步、通知、自动重置唤醒或防睡眠时,构建通过之外还要说明应手动覆盖的交互场景;helper 相关改动额外要验证 App 包内 helper 与 plist 位置、签名、首次系统授权、运行/等待切换、唤醒计划替换与清理和异常退出后的恢复
diff --git a/CLAUDE.md b/CLAUDE.md
deleted file mode 100644
index d96f701..0000000
--- a/CLAUDE.md
+++ /dev/null
@@ -1,334 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-写作、构建、Git 与兼容性规则遵循 [AGENTS.md](AGENTS.md)
-
-## 项目概述
-
-CodexBar 是一个 macOS 菜单栏应用,以 `LSUIElement` 方式运行,没有 Dock 图标,展示本机 Codex 的账号状态、额度、Token 用量、实时任务和工作流统计。技术栈为 Swift 6 + SwiftUI + AppKit + MVVM,唯一外部依赖是 Sparkle `2.10.0+`(SwiftPM)。最低系统版本为 macOS `15.0`
-
-Xcode 工程有三个 target:主 App `CodexBar`、随 App 嵌入的 root helper `CodexBarHelper`(command-line tool + LaunchDaemon),以及使用 Swift Testing 的无宿主单元测试 `CodexBarTests`。测试直接编译 App 与 `Shared/` 源码,通过测试 target 独有的 `CODEXBAR_TESTING` 条件移除可执行入口。
-
-App Sandbox 未开启,entitlements 只声明 iCloud/CloudKit,因为需要启动本机 `codex` 进程、读取用户 Codex 登录状态、写入用户级 Hook 配置。
-
-## 常用命令
-
-```bash
-# 日常编译验证 (唯一 scheme 是 CodexBar)
-xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/platform=macOS' build
-
-# 单元测试: 使用独立临时目录和 UserDefaults suite
-xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'platform=macOS' test
-
-# 格式化: 配置在 .swiftformat, 覆盖整个仓库 (Swift 6 语言模式, 4 空格缩进)
-swiftformat .
-
-# Lint: 配置在 .swiftlint.yml, included 包含 CodexBar/ 和 CodexBarTests/
-# 即 Shared/ CodexBarHelper/ Scripts/ 不在 lint 范围内
-swiftlint
-
-# 查看系统日志; zsh 里 log 会和 shell 冲突, 必须写完整路径
-# Debug 版把 subsystem 换成 app.zabrian.codexbar.debug, helper 进程另带 .helper 后缀
-# BEGINSWITH 会同时命中 Debug 与 Release, 要分版本得用 == 或 IN
-/usr/bin/log stream --predicate 'subsystem == "app.zabrian.codexbar"' --style compact
-/usr/bin/log show --predicate 'subsystem == "app.zabrian.codexbar"' --last 30m --style compact
-
-# 发布流程 (需要 Developer ID 凭据, 不要当普通本地验证跑)
-Scripts/build.sh # Release archive + Developer ID 导出 + notarize + staple + Gatekeeper 校验
-Scripts/dmg.sh # 打包 DMG
-Scripts/appcast.sh # sign_update 签名并写入 appcast.xml
-
-# 注销 KeepAlive LaunchDaemon; 清理前需先退出所有 CodexBar 实例
-# 不带参数时同时处理 Release 与 Debug 两套
-# 常用: --release / --debug 限定范围, --check 只验证目标不真的注销
-# 签名身份取环境变量 CODEXBAR_CLEANUP_SIGN_IDENTITY, 默认 Apple Development
-Scripts/cleanup.swift --help
-```
-
-日常调试直接用 `open CodexBar.xcodeproj` 在 Xcode 中运行 Debug scheme。Debug 产物使用 `app.zabrian.codexbar.debug` 这个 bundle ID,与 Release 安装版可以共存,排查防睡眠问题时要确认自己查看的是哪一套 helper。
-
-`Scripts/build.sh` 会先清空 `Build/` 目录,成功后只保留最终的 `.app` 文件。凭据推荐使用 keychain profile,先运行一次 `xcrun notarytool store-credentials "codexbar-notary" --apple-id "<Apple ID>" --team-id "<Team ID>"` 保存凭据,之后构建时加上 `--notary-profile codexbar-notary`
-
-Debug 与 Release 使用不同 bundle ID,分别是 `app.zabrian.codexbar.debug` 与 `app.zabrian.codexbar`。helper 相应带 `.debug.helper` 与 `.helper` 后缀,所以 `CodexBarHelper/` 下有两份 LaunchDaemon plist,`cleanup.swift` 也需要同时处理两套。
-
-## Git 补充规则
-
-- 功能、修复和发布类提交必须写 body;简单文档或杂项可以只写标题
-- commit message 使用半角标点,行末不加标点,行内标点后留一个英文空格
-- 多条 body bullet 连续排列,使用同一个 `-m` 参数或通过 `git commit -F` 传入文件
-
-## 架构
-
-### 启动分流(关键设计)
-
-`CodexBar/App/CodexBarApp.swift` 的 `init()` 最先调用 `WorkflowHookEventRecorder.handleIfRequested()`
-
-- 带 `--hook-event` 启动 -> **Hook 子进程模式**:从 `stdin` 读取 JSON payload,按需有界读取 rollout 元数据,在 `flock` 锁内追加一行 JSONL 后立即调用 `exit(EXIT_SUCCESS)` 退出,绝不初始化菜单栏 UI;写入失败时静默吞掉,不阻断 Codex
-- Hook handler 超时统一由 `WorkflowHookEventRecorder.hookTimeoutSeconds(for:)` 提供,`SessionEnd` 和 `Interrupt` 是 3 秒,其他事件是 5 秒;等锁预算固定比对应事件超时少 2 秒,当前分别是 1 秒和 3 秒
-- 普通启动 -> `Controllers/CodexBarAppDelegate.swift` 中的 `CodexBarAppDelegate` 创建全部长期对象,再由 `StatusItemController.install()` 装配菜单栏;AppDelegate 是唯一的装配点,新增服务在这里注入
-
-### 三条数据链路
-
-**链路一:app-server(额度/用量)**
-
-`CodexStatusService`(actor) -> `CodexCLIResolver` 解析 `codex` 可执行文件,PATH 全局优先,回退 `/Applications/ChatGPT.app` 或 `Codex.app` 内置 -> 启动 `codex app-server --listen stdio://` -> `AppServerSession` 执行 stdio JSON-RPC -> 合成 `CodexQuotaSnapshot` -> `CodexStatusViewModel` 发布给 UI
-
-- 刷新间隔为 60 秒、请求超时为 20 秒,连接最长复用 1 小时,让后台升级的 `codex` 二进制有机会生效
-- 主要方法有 `initialize`、`account/read`、`account/rateLimits/read`、`account/usage/read`、`config/read`、`config/batchWrite`、`hooks/list`
-- `SIGPIPE` 被忽略,app-server 退出后写管道由 write 抛错走重建路径
-- `stdout` 可能混有无关日志行,`AppServerSession` 先用轻量 `RPCIDEnvelope` 匹配 `id`,再完整解码
-
-代理配置由 AppDelegate 持有的 `CodexProxySettings` 管理,配置和密码保存在当前构建的 UserDefaults 中,key 为 `CodexProxy.configuration`。只支持 HTTP/HTTPS,可选 Basic 认证,不使用 Keychain。停用保留字段,无法读取的记录可从配置窗口清除。
-
-- 开关在异步提交前更新显示状态并禁用,重复操作被忽略,提交失败恢复原状态
-- `CodexStatusService.applyProxy` 保存后关闭旧连接并清空缓存,随后触发刷新
-- 手动和到期重连均先关闭旧连接,新连接失败后保持断开
-- 代理测试使用草稿启动独立进程,请求共享 8 秒截止时间,取消后旧结果不得提交
-- 配置错误写入 `AppLog.settings`,正式 RPC 响应中的代理 URL 认证信息脱敏后才进入内存交互日志
-
-**链路二:Hook 统计(历史聚合)**
-
-Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/events/YYYY-MM-DD.jsonl` 这类文件,主 App 的 `WorkflowService`(actor)增量聚合出 `daily.jsonl` 与 `WorkflowSnapshot`,供热力图详情面板展示。可选跨设备同步由 `WorkflowSyncScheduler`(唯一调度者)与 `WorkflowSyncService` 负责,使用 `iCloud.app.zabrian.codexbar` 容器的 CloudKit private database,只上传脱敏 daily 聚合。
-
-- `WorkflowStorage` 管理的存储目录含 `events/`、`daily.jsonl`、`stats.lock`、`maintenance.json`、`Sync/` 五项
-- 原始事件文件与 daily 聚合统一保留 210 天,聚合里的会话与轮次标识只保留 3 天,到期后只留下去重计数
-- `WorkflowDailyAccumulator` 的全量与增量路径始终在内存收集完整 ID,只有 `finalized(identifierStorage:)` 才决定保留或压缩;已压缩的日期收到新事件时不能安全去重,必须降级为从原始 JSONL 完整重建
-- `WorkflowMaintenanceState.currentAggregationSchema` 是原始事件到 daily 聚合的算法版本;缺少版本按 0 处理,版本不一致时把仍有原始事件的日期全部标脏并走通用完整重建,不写字段级历史迁移
-- 需要从原始事件重新计算的聚合算法、输出字段、字段含义或去重规则变化时,必须递增 `currentAggregationSchema`,统一走相同的完整重建入口
-- daily 与 CloudKit 中的 Hook 计数字段都是可选值;`nil` 表示来源版本没有提供或无法确认,明确的 `0` 才表示已知没有对应事件,解码和重建都不能把两者混为一谈
-
-**链路三:实时任务,由 `CodexActivityMonitor` 驱动**
-
-`CodexActivityMonitor` 为菜单栏、活动卡片、任务流光、通知、触觉反馈和防睡眠提供统一任务状态,由两个 reader 读取数据。
-
-- `HookEventTailReader`(actor)的 bootstrap 覆盖滚动 24 小时并作为单次事务发送,之后按窗口内各日期文件的 offset 增量 tail,同时向下游报告数据源健康状态
-- `CodexSessionLifecycleReader`(actor)增量读取 Codex 目录中 `sessions` 与 `archived_sessions` 下的 rollout JSONL,提取线程归属、turn 生命周期、执行进展和审批上下文,不解码会话或工具内容
-- 任务监控只在 `codexHookSettings.isOperable` 为 `true` 时运行,即本地已安装且最近一次明确校验没有失败;链路失效时立即停 reader 并清空实时状态
-- `Stop` 保留正在收尾的任务,其他 Agent 等待审批时优先展示等待;rollout 确认后才记录完成。`Interrupt` 结束匹配轮次;新 turn 或 `SessionEnd` 将旧任务移出活动列表,前 5 秒快速查询终态,之后每 30 秒补查,最长保留 24 小时。审批归属、来源过滤和恢复规则见 [实时任务监控](Docs/DeveloperGuide/activity-monitor.md)
-- `HookEventTailReader.drainNow()` 是读取屏障,每个调用方等待一轮在本次请求之后开始的读取,返回 `completed`、`sourceUnavailable` 或 `cancelled`
-- 缺少 session ID 的 Hook 事件使用匿名 project key,`isAnonymous` 会保留到活动快照、完成记录和终止记录;活动卡片和任务中心显示橙色 `person.crop.circle.dashed` 图标,`help` 为 `匿名任务不参与防睡眠`,`+N` 只显示其他活跃任务总数
-- 匿名任务不向通知消费者发布等待或完成 transition,不触发触觉反馈,不参与 KeepAlive 或异常会话保护,`activityProtectionIdentifier` 为 `nil`
-
-系统睡眠前暂停异常会话保护。`NSWorkspace.didWakeNotification` 触发新的读取屏障,成功后重置生命周期解析回退,完成 rollout 对账后恢复判定;数据源不可用时继续暂停,reader generation 变化时丢弃旧结果。
-
-#### 异常会话保护
-
-- `CodexActivityProtection.swift` 管理异常会话保护状态机,`ActivityProtectionSettings` 只保存静默阈值;保护开关跟随用户保存的 KeepAlive 主开关,不依赖 helper 是否已获系统授权
-- 静默阈值可选 30 分钟, 1, 2 或 4 小时,默认 1 小时,UserDefaults key 固定为 `KeepAlive.abnormalTaskInactivitySeconds`
-- 候选只包含非匿名 `.running` 任务,`.waitingApproval` 不参与异常判定;`lastProgressAt` 同时吸收 Hook 顶层事件、子 Agent 事件与 rollout 行时间
-- 达到阈值后先更新内存候选记录并加入串行持久化队列,再提交本地通知;通知使用系统默认声音且不重试。通知处理返回或 3 秒宽限到期后重新校验候选,仍有效时隐藏任务;隐藏不等待磁盘写入成功
-- 通知以 task ID 与 attempt ID 共同标识,候选失效或任务恢复、终止、完成、过期时会撤回仍可识别的待处理和已送达通知;迟到的提交结果不得影响新的 attempt
-- 隐藏任务不进入 `CodexActivitySnapshot` 的运行中与等待批准列表,因而不参与 UI 和 KeepAlive 的活跃任务计算;后续进展会恢复任务并清除保护记录
-- KeepAlive 关闭时恢复当前进程内所有隐藏任务并撤回通知,已经隐藏任务的持久化记录保留;再次开启后按当前阈值和最近进展时间无通知对账
-- 判定要求监控已启动、KeepAlive 已开启、reader 存在、bootstrap 已结束、不在睡眠或唤醒恢复阶段且 Hook 数据源健康;进入不满足条件的阶段时会取消计时器和在途通知 attempt
-- 静默定时器使用 `SuspendingClock`,系统时间变化由 `NSSystemClockDidChange` 触发无通知重算;系统睡眠期间暂停判定,唤醒完成 Hook 读取和 rollout 对账后再恢复
-- `ActivityProtectionStateStore` 把记录写入 `~/Library/Application Support/CodexBar/ActivityProtection/state.json`,字段只有 SHA-256 任务标识与 `lastProgressAt`、`markedAt`、`expiresAt`,最长保留到最后进展后的 24 小时
-- Debug 与 Release 共用状态文件,actor 串行化进程内访问,`flock` 保护跨进程读写,文件权限固定为 `0600`,当前 schema 为 `1`;状态在 task reader 启动前完成加载
-- 持久化操作按 `activityProtectionPersistenceTask` 串行排队,条件删除用 `markedAt` 防止旧 attempt 删除新记录,终态与保留期清理执行无条件删除
-
-### 系统电源控制与 root helper
-
-两套机制叠加,职责不同:
-
-- `SystemSleepService` 用进程内 `IOPMAssertion` 建立 `PreventUserIdleSystemSleep` 断言,只挡空闲睡眠,不需要提权;断言名必须是 ASCII,否则 `pmset -g assertions` 显示不出标识
-- `CodexBarHelper` 是 root LaunchDaemon,通过 XPC 接受 `setSleepPreventionRequested` 和 `setAutoResetWakeSchedule` 请求;前者执行 `/usr/bin/pmset -a disablesleep` 覆盖合盖睡眠,后者使用固定 owner 和 `wake` 类型维护自动重置系统唤醒事件
-
-防睡眠链路:`KeepAliveController`(MainActor)订阅 `activityMonitor.$snapshot` 以及合成 `codexHookSettings.isOperable` 的两个发布值 -> `SMAppService.daemon(plistName:)` 注册 -> `NSXPCConnection` -> helper
-
-自动重置唤醒链路:`AutoResetController` -> `KeepAliveController` -> `AutoResetWakeScheduler` -> 独立 `NSXPCConnection` -> helper
-
-关键约束:
-
-- `shouldDisableSleep` 由 `sleepBlockReason == nil` 派生,要求服务已启动、App 未退出、主开关与 Hook 可用、存在符合条件的任务、helper 已批准且未刷新、低电量与时长上限均未阻断;依赖变化保留用户保存的 `isEnabled`
-- `hasRunningTasks` 只表示非匿名且仍可见的运行中任务;`hasKeepAliveTasks` 在此基础上纳入 `keepsAwakeWhileWaiting` 开启时的非匿名等待任务,被异常会话保护隐藏的任务不参与防睡眠
-- Hook 状态在类内只认 `isHookEnabled` 这份镜像,它跟的是 `codexHookSettings.isOperable`;不要回读那个属性,订阅回调跑在 `willSet`,此时正在变更的属性仍是旧值,使用 `CombineLatest` 传入的新值
-- 新增拦截条件一律加进 `sleepBlockReason` 的顺序判断里,它和 `shouldDisableSleep` 同源,顺带保证日志的 `reason=` 不会漏项
-- UI 用的 `isLowBatteryBlocking` 与 `canShowOptions` 由 `reconcileSleepState` 从 `sleepBlockReason` 单点派生,`allowsOptions` 的穷尽 `switch` 定义各阻断条件下的选项入口状态
-- `hasRunningTasks` 与 `isRefreshingHelper` 都不带 `@Published` 标注,它们变得比结论频繁,各自发信号会把整个设置页拖着一起重算
-- helper 只做固定的系统电源操作;不要给 root helper 增加网络、任意命令执行或其他文件访问能力
-- helper 注册需求由防睡眠主开关与自动重置请求共同决定;自动重置开启时即使防睡眠关闭也要完成 `SMAppService` 注册和系统批准,设置行复用注册错误并单独展示唤醒计划同步错误
-- 关于页面和功能说明读取派生的 `helperInstallationStatus`;包完整且无注册错误时,`.notRegistered` 与 `.notFound` 均显示未安装;包校验异常优先于已授权状态,后续校验成功后清除,详见 [CodexBarHelper 安装与通信](Docs/DeveloperGuide/sleep-prevention.md#codexbarhelper-安装与通信)
-- 自动重置与防睡眠从关闭切换为开启时统一通过 `HelperFeatureConfirmation` 显示确认;`.notRegistered` 与 `.notFound` 提示需要安装并授权后台运行,`.requiresApproval` 提示已安装但仍需授权,`.enabled` 只显示功能说明
-- `ensureHelperRegistration()` 只负责注册与刷新 helper;Helper 授权系统设置仅由设置行的 `打开系统设置` 按钮调用 `openSystemSettings()` 打开,两个功能的开启动作不直接切换到系统设置
-- `AutoResetWakeScheduler` 与防睡眠租约使用独立 XPC 连接,只同步下一次唤醒时间;距现在不超过 5 秒的时间不交给 helper,由 App 内定时任务直接进入到点执行路径
-- helper 把自动重置事件 owner 固定为 `CodexBarHelperIPC.machServiceName + ".auto-reset"`,事件类型固定为 `kIOPMAutoWake`;替换时先取消这个 owner 的全部旧事件,设置后回读必须恰好得到一个 1 秒容差内的目标事件,取消后回读必须为空;修改 owner 或类型属于清理兼容性问题
-- 唤醒连接关闭时 helper 立即取消该连接拥有的事件,取消失败后清除内存所有者并每 5 秒继续收敛;helper 启动时在开放 listener 前按立即、250 毫秒、1 秒清理遗留事件,`SIGTERM` 与 `SIGINT` 退出前也执行取消
-- App 同步唤醒计划失败后按 2/4/8/16/32/64 秒重试;App 正常退出或 helper 更新前按立即、250 毫秒、1 秒取消,失败就保留错误并取消本次退出或更新
-- `Scripts/cleanup.swift` 注销 helper 前先通过 XPC 取消固定 owner 的事件并回读;事件仍存在时必须停止注销,不能让系统计划失去最后一个具备清理能力的进程
-- 调用方校验由 XPC 层强制;helper 启动时用 `SecCodeCopySelf` 读自身签名,拼出形如 `anchor apple generic and certificate leaf[subject.OU] = "<team>" and identifier "<主 App identifier>"` 的 requirement 字符串,交给 `NSXPCListener.setConnectionCodeSigningRequirement` 生效;没有逐次连接的 audit token 检查,改签名或改 bundle ID 会直接连不上
-- 所有权记录固定放在 `/Library/Application Support/CodexBar/helper-state.json`,由 root 在同目录写临时文件,完成 `F_FULLFSYNC` 后原子替换并同步目录,权限固定为 `0600`;只持久化 `idle`、`owned`、`restoring` 三态,`external` 只是任务期间的运行态,不落盘也不承担恢复责任
-- 当前值为 0 时必须先写 `owned` 再写 `pmset 1`;释放时必须先写 `restoring` 再写 `pmset 0`;两次 pmset 都要重新读取 `pmset -g` 确认实际值,只有确认为 0 才能记回 `idle`
-- 任务开始时实际值已为 1 就返回 `external`,不写 `pmset`;helper 每 5 秒观察一次,如果其他来源在任务期间改回 0,helper 立即按上一条顺序取得所有权
-- helper 取得所有权后每 5 秒检查一次实际值与磁盘 transaction,值被改成 0 时重新写回 1,记录缺失、损坏或 transaction 不一致时先修复记录;修复失败也必须继续尝试恢复为 0
-- 没有活跃租约时停止短轮询,只保留 60 秒异常恢复检查;所有短轮询使用 1 秒 leeway
-- 每个 App 进程持有一个跨 XPC 重连不变的 client session ID,请求再带单调递增的 `generation`;helper 只释放对应进程的租约并拒绝延迟到达的旧 `generation`,不允许旧连接覆盖新状态
-- 异常断连后租约宽限 15 秒;同一 App 在宽限内重连会续上原租约,watchdog 只会释放仍处于断连状态的那一个 client session
-- helper 以 `owned` 或 `restoring` 启动时先恢复为 0 再接受新接管;以 `idle` 启动时不修改当前值,因为那个值可能属于其他来源
-- 更新 helper 前 App 冻结新防睡眠请求和自动重置唤醒同步,确认固定唤醒事件已取消后执行 unregister/register;旧 helper 终止时负责恢复 owned 睡眠状态,新 helper 就绪后对当前指纹执行一次 `resetSleepAfterUpdate` 并收到状态回复才完成更新,系统仍在等待首次批准时除外
-- 切换失败按 2/4/8…256 秒重试,重试次数耗尽后保留错误状态
-- XPC 请求带超时并汇进同一条重试路径;launchd 拉不起 helper 时 XPC 方法既不回复也不触发 `errorHandler`,没有它界面会显示防睡眠开着而实际没生效,日志里只剩没有配对回复的 `Helper XPC 请求已发送`
-- 超时取值放在 `CodexBarHelperIPC.requestTimeoutSeconds` 而不是控制器里,它与 `watchdogGraceSeconds` 是一对:必须更小,App 先放手 helper 才能靠 watchdog 兜底,分处两个 module 会让人改了一边不知道另一边
-- 开发期间用 `xcodebuild` 覆盖正在运行的 App bundle 可能使 launchd 注册信息与磁盘上的 helper 不一致;重启 App 后通过 `KeepAliveHelperConfiguration.registrationNeedsRefresh(defaults:)` 检查指纹并刷新注册
-- helper 回传 `none`、`external`、`codexBar` 来源与操作后的实测值;App 只能在 `codexBar` 且实测为 0 时宣称系统睡眠已恢复或补发 `IOPMSleepSystem`,`external` 和 `none` 都只释放进程内断言
-- App 退出由 `applicationShouldTerminate` 返回 `terminateLater`,先取消自动重置唤醒计划,再释放防睡眠租约;两项都经 helper 回读确认后才继续退出,任一失败都会取消本次退出并恢复协调
-- `pmset` 是没有来源和引用计数的全局布尔值;CodexBar 取得所有权后如果另一个 App 也开始依赖这个 1,释放时仍会恢复为 0,系统层没有无歧义的方法判断另一个 App 的意图
-- 低电量保护由 `PowerSourceMonitor` 供数,它只报事实(有没有内置电池、电量、是否靠电池供电),不知道阈值;读数保持 `unavailable`、`unreadable`、`present` 三态,把读取失败折叠成“没有电池”会让设置项凭空消失且保护静默失效
-- 见过一次内置电池就记住 `hasSeenBattery`,之后读到空列表只能返回 `unreadable`;硬件不会中途消失,空列表只是 IOKit 重新枚举时的缺口,当成台式机会当场撤掉保护
-- `hasSeenBattery` 只活在进程内不持久化,每次启动重新判定;笔记本启动时撞上枚举缺口会短暂显示成没有电池,由下一次电源通知自愈,而持久化会让从笔记本备份恢复的台式机永远多出低电量设置项
-- `IOPSNotificationCreateRunLoopSource` 注册失败时降级成 60 秒轮询并记 `action=poll`;只靠 `didWakeNotification` 补读不够,防睡眠生效的机器按定义就不会睡,那条通知永远不来
-- 首次读取在 `start()` 里单独判一次并记 `stage=start` 这条,不能改走 `refresh()` 那条路:后者按变化过滤,而读数初始值就是 `unreadable` 本身,首读失败会被静默吞掉,之后只留下一条没有配对失败行的恢复日志
-- 防睡眠上限累计的是**真正挡住睡眠**的那段时间,`begin` 起表 `pause` 收表,收表之后机器睡着或被低电量拦下都不占用户的上限
-- 上限计时用 `SuspendingClock` 而不是 `Date`,后者受系统时间调整影响且系统睡眠期间照走;排计时器的 `Task.sleep` 同样要传 `SuspendingClock`,否则睡一夜醒来会当场判定到期
-- 低电量判断使用 `isLowBatteryActive` 记录滞回状态;电池供电且电量不高于阈值时进入,达到阈值加 5 个百分点或接通电源时解除。时长上限由 `hasReachedMaximumDuration` 保持到下一轮任务或设置变化
-- 供电来源读取 `Power Source State`;接电停充时 `Is Charging` 为 `false`,不能用于判断是否正在使用电池
-- 电量不可读时维持上一次判定,从未取得有效读数时不触发低电量保护
-- 已经在低电量保护中时读数失败不清零,否则一次瞬时失败会绕过滞回,让防睡眠反复开关并重发通知
-- 低电量通知只在 `isActivelyPreventingSleep` 为真且来源是 `codexBar` 时排队,外部来源不说“已恢复系统睡眠”;日志无条件记并用 `action=release|none` 区分,百分比只有那一条能看到
-- 恢复睡眠的通知在 helper 的 XPC 回复确认成功后提交;恢复失败时进入有界重试
-- 补发 `IOPMSleepSystem` 之前还要 `await` 到通知真的提交完成,只把提交排进下一个 MainActor job 的话同一个 job 里的补发会抢在它前面
-- 那次 `await` 之后要重认一次 `generation` 再走 `finishSleepRestore` 这一步,挂起期间可能已有新的禁用请求接管,否则会释放掉刚建立的空闲断言
-- 设置页那句低电量说明看 `isLowBatteryBlocking` 而不是 `isLowBatteryActive`,后者在没有任务时也成立,那时无话可说
-- 触发与解除用 `阈值` 与 `阈值 + 5%` 两道门槛,否则电量在阈值附近抖动会反复切 pmset,合盖时还会反复补发 `IOPMSleepSystem`
-- 一轮低电量通知的终点是电量回到 `阈值 + 5%` 或者用户改了阈值,由 `hasNotifiedLowBattery` 记住;只看是否接电会让适配器接触不良时每翻一次供电状态就重发一条
-- `hasNotifiedLowBattery` 只在通知真的提交成功之后才置位,打在入队处或提交前都会让没送达的那一条吃掉整轮配额,使这一轮之后真正触发的低电量再也提醒不了
-- `SleepConditions` 里只放 `battery` 布尔,放电量百分比会让每掉 1% 刷一条变化日志;真实电量只在触发那一条单独记
-- 防睡眠生效且活动卡片数据可用时,右侧显示青绿色 `sun.max.fill`;主面板可见且“动画效果”开启时每 2 秒匀速旋转一圈,关闭动画时显示静态图标。tooltip 按 `sleepPreventionSource` 显示来源
-- 设置页那一行说明只在异常、外部来源、低电量生效或达到上限时出现,CodexBar 自己正常持有所有权时整行收起,`keepAliveCaption` 返回 `nil` 即代表收起
-- 最长防睡眠时间、异常会话保护阈值与低电量阈值都在防睡眠子面板里,台式机读不到电池时低电量那一行整行隐藏而不是置灰
-- 保持屏幕常亮跟 `isActivelyPreventingSleep` 走,由 `reconcileDisplayAwake` 单点切换,于是低电量拦下、达到上限、任务结束时屏幕都跟着放开
-- 显示断言只保证屏幕不睡,屏保与闲置锁屏跟的是系统 idle 计时,要靠 30 秒一次的 `IOPMAssertionDeclareUserActivity` 压住,两者缺一不可
-- 声明用户活动复用同一个 assertion ID,每次传 `null` 会新建一条,`pmset -g assertions` 里会堆成一串同名断言
-- 逐次声明不记日志,建立与释放各一条就够还原状态;两条断言都是进程级的,App 退出或崩溃时系统自动收回,不经过 helper
-- 菜单栏由 `StatusItemIconView` 绘制人物符号和额度圆弧,并挂载在原生 `NSStatusBarButton` 中。人物使用系统前景色,圆弧使用 `QuotaPalette`;防睡眠状态只显示在活动卡片
-
-### 自动重置
-
-- `AutoResetSettings` 默认关闭,提前量可选 15 分钟、30 分钟、1 小时、2 小时、4 小时、6 小时,缺失或无效值回退 30 分钟
-- `AutoResetController` 只处理新鲜 `account/rateLimits/read` 明确列出的 `available + codexRateLimits + expiresAt` 凭证,按过期时间和 ID 排序后一次只处理最早目标;数量不能反推缺失明细
-- App 启动、用户开启、系统唤醒和计划到点都会执行新鲜读取;阈值尚未到时重新调度,已经进入窗口且尚未过期时立即尝试
-- `creditId` 决定跨设备幂等键和通知身份,`expiresAt` 只是可变调度数据;同一 ID 的时间变化要取消当前阈值或重试并按新时间重排,不能换幂等身份
-- 阈值触发后单轮重试窗口固定为 5 分钟;暂时错误按 15/30/60/120/300 秒计算下一次退避,但落在截止点及之后的重试不安排,`nothingToReset` 在过期前最后 10 分钟内按 60 秒间隔处理
-- 单轮结束只取消本地任务和系统唤醒,不把目标标记成永久失败;后续普通额度快照仍可为有效目标开启新一轮
-- `.auto`、`.retry` 和 `.wake` 评估期间建立独立的 `PreventUserIdleSystemSleep` assertion,读取与消费结束后立即释放;不建立显示断言,不修改 `SleepDisabled`
-- `reset` 与 `alreadyRedeemed` 都视为成功并通知;认证失败暂停当前目标,协议或参数错误停止当前目标,明确过期发送失败通知,目标从明细消失时静默停止
-- 原始 `creditId` 和确定性幂等键只在当前进程内存中存在;`UserDefaults` 只保存开关、提前量、通知选项和哈希去重 key,CloudKit 不同步自动重置状态
-
-### 通知
-
-- `CodexNotificationService` 是集中式的 `MainActor` 服务,订阅额度快照与实时活动,负责阈值穿越判定、去重、额度重置识别、触觉反馈和本地通知;dedup key 落 `UserDefaults`
-- 匿名任务在 transition 入口被过滤,不发送完成或等待批准通知,也不触发任务触觉反馈
-- `send` 是唯一的提交入口,返回一个 `Task<Bool, Never>?` 值,需要等通知真的发出去再做下一步的调用方 `await` 它的 `value` 即可;不要另开一条 async 通道,那会悄悄少掉去重、时效判定与提交失败回调三项能力
-- 去重判定留在 `send` 的同步段而不是挪进 `Task` 内部,这样连续两次调用的第二次一定被挡下,不依赖任务调度顺序
-- 异常会话保护通知只依赖通知总开关与系统授权,使用系统默认声音,`retryCount` 为 0;提交前后都调用 monitor 的 relevance 检查,过期通知立即撤回
-- `NotificationSettings` 管 CodexBar 自身通知;`CodexCLINotificationSettings` 是另一回事,它通过 app-server `config/read` 与 `config/batchWrite` 读写 Codex 自己的用户级 `config.toml`
-- 通知面板里带依赖的行一律显示为关闭并置灰而不是隐藏,任务类看 `codexHookSettings.isOperable`,低电量保护通知看 `KeepAliveController.isLowBatteryProtectionEnabled`(防睡眠可用、阈值开着,且这台机器确实有电池),防睡眠上限通知看 `KeepAliveController.isMaximumDurationEnabled`(防睡眠可用且不是无限制);都不回写用户保存的开关
-- 两条防睡眠通知的依赖里都含“防睡眠可用”这一层,即防睡眠开关与 Hook 都开着,判定收在 `publishNotificationDependencies` 一处;只判各自的子设置会让防睡眠关着时这两行还亮着
-- 带依赖的行由 `KeepAliveController` 判定并派生成一个值,视图只读结论,不在各视图各写一遍 `!= .unlimited` 这类规则
-- 防睡眠上限通知与低电量通知共用同一个发送时机;达到上限是粘滞状态,一个计时周期只发一次,不需要低电量那种本轮已通知的锁存
-
-### 并发与隔离
-
-工程开启 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor` 设置,所有类型默认 `MainActor` 隔离。
-
-- UI、控制器、ViewModel、Settings、更新类直接依赖默认隔离,不需要额外标注
-- 服务共享状态用 actor 管理,包括 `CodexStatusService`、`WorkflowService`、`WorkflowSyncService`、`CodexCLIVersionService`、`HookEventTailReader`、`CodexSessionLifecycleReader`、`ActivityProtectionStateStore`
-- DTO、纯模型、静态工具、跨 actor 传递的类型必须显式标注 `nonisolated`
-- 跨进程写统计文件用 `stats.lock` 加 `flock` 保护,Hook 子进程有等待上限,主 App 无限等待;`RequestLogStorage` 用 `OSAllocatedUnfairLock`
-- 非 Sendable 的管道 IO 集中在 `PipeReadBuffer` 里,`JSONLineReader` 与 `PipeDrain` 复用它
-- 保留既有防重入与过期结果丢弃逻辑,例如 `RefreshTaskCoordinator` 只让最新 `generation` 提交结果
-- 不要用阻塞 I/O 或长耗时操作卡住 `MainActor`
-
-### 错误处理原则
-
-- `CodexFetchOutcome` 包含有数据、未登录、版本不满足要求和初始化失败四种结果。主面板显示对应状态,关于页面显示连接失败原因;完整请求与响应由 `RequestLogStorage` 保存在内存日志中,上限 500 条
-- app-server 之外的模块走 `Services/Support/AppLog.swift` 写系统日志,用户可见文案只留步骤名,错误码与 `localizedDescription` 这类细节进 `os_log`;现有 `category` 为 `app`、`keepalive`、`activity`、`workflow`、`sync`、`hooks`、`codexcli`、`settings`、`notification`,helper 进程另用 `helper`
-- 日志的目标是出问题时能从中重建当时的状态,所以不只记失败,状态转换、关键操作与决策依据同样要记;启动时由 `logLaunchState` 记一条含全部开关的基线,后续变更日志都是相对它的增量
-- 进程终止靠 `AppProcessDiagnostics` 补线索,它和 `logLaunchState` 一样挂在 `app` category 下,ObjC 异常当场留痕,其余终止方式靠下次启动补记一条 `App 上次非正常退出`
-- 非正常退出补记使用 `.notice`,该记录无法区分强制退出与崩溃
-- **级别只用 `.notice` 与 `.error`**,状态转换和降级决策用 `.notice`,失败用 `.error`;`.info` 与 `.debug` 只落在内存环形缓冲里,事后 `log show` 捞不全,一律不用
-- 详细度靠**结果字段化**而不是多记几条:一次操作只留开始与收尾两条,每一步的成功结果压成收尾那条里的一个字段,只有失败才单独发一条 `.error` 带 `stage=` 与 `detail=`;逐事件与逐快照这类高频路径仍然一律不记,例如两个 Reader 的 `try?` 文件 IO 失败是预期常态,记了会刷屏
-- 文案骨架是 `<主体><动作>: 字段=值; 字段=值`,标题只说发生了什么,理由进 `reason=`,处置进 `action=`;起止用 `开始` `完成` `失败`,中间状态用 `已<动作>`
-- 字段顺序固定为标识(`trigger`、`generation`、`date`)、输入、结果、`elapsed`、`reason`/`detail`;公共字段有 `trigger`、`result`、`reason`、`action`、`detail`、`code`(系统返回码)、`exit`(进程退出码)、`elapsed`,其中 `code` 与 `exit` 必须分开,不要用一个 `error=` 同时装 OSStatus、IOReturn 和退出码
-- 文案只描述事实,不写“用户做了什么”这类主语,也不写推论;字段值要可 `grep`,用枚举 `rawValue` 而不是中文句子,App 与 helper 两侧保持同一套格式
-- 词根固定,一个词能 `grep` 出整条链路:额度、统计刷新(调度层)、事件汇总(计算层)、同步、KeepAlive(防睡眠决策层)、空闲断言(进程内 `IOPMAssertion`)、显示断言(屏幕常亮那条 `IOPMAssertion`)、Helper 注册(`SMAppService`)、Helper XPC(`NSXPCConnection`)、系统睡眠(helper 的 pmset 效果)、电源监听(`PowerSourceMonitor`)、任务、Hook、codex、通知
-- 防睡眠日志按两套机制分组:`KeepAlive` 是两套共用的决策层,`空闲断言` 与 `显示断言` 是机制一,`Helper 注册`、`Helper XPC`、`系统睡眠` 是机制二的授权、传输、效果三层,故障定位就是在这几层里找
-- `trigger=` 由 `LogTrigger` 提供,从 UI 入口透传到服务层,用来区分同一条链路是被用户动作、定时轮询还是系统事件踢起来的;统计维护挂在额度刷新完成事件上,它的 `trigger` 继承那一次刷新
-- 变化检测类日志只在值真的变了才记,例如 `KeepAlive 条件已变化` 与 `Hook 配置已变化` 各自存一份上次的值,否则每次开面板都会刷一条
-- 设置项的变更日志照抄设置页那一行的标题,例如 `菜单栏额度指示变更`、`开机自动启动变更`,用户说“我改了那个开关”时能直接对上;只有本身带完整链路的才用链路词根,例如 Hook、同步、通知、KeepAlive、快捷键
-- 成对的操作要留成对的日志,例如 XPC 的发送与回复各记一条并带同一个 `generation`,缺一条就说明请求丢在途中
-- 耗时用 `LogDuration` 取,只加在收尾那一条上
-- `Logger` 的插值是 autoclosure,里面直接访问属性会被要求显式 `self`,而 `.swiftformat` 配了 `--self remove`,两者要求冲突;先将属性保存为局部常量再插值
-- 账户有效时,额度和用量请求可以分别失败;同账户缓存标为 `stale` 并降低透明度。可见的数据区域均无数据时,在其中第一个区域显示“暂无数据”;Hook 开启时用量区域可保留本地统计。账户变化时清空补充缓存
-- 各 Settings 类把读取类错误与操作类错误分开存储,定时 `refresh` 不能抹掉用户操作或校验的结论,参见 `CodexHookSettings` 与 `KeepAliveController`
-- Hook 子进程任何失败都静默退出,优先保证不拖慢 Codex
-
-## UI 与窗口约定
-
-- 菜单栏按钮左键切换主面板;右键或 Control+点击打开上下文菜单;`⌘,` 打开自定义设置窗口,菜单面板打开时 `⌘L` 打开日志窗口;默认全局快捷键 `⌘⇧W` 由 `GlobalHotKeySettings` 与 `GlobalHotKeyController` 管理
-- 主面板是锚定 status item 的 `NSPopover` 弹窗,锚点不可信时回退到 `FallbackPanelController` 提供的屏幕顶部居中 `NSPanel` 面板,处理快捷键、屏幕选择和焦点时要保留这两个分支
-- `MenuSurfaceDismissMonitor` 将鼠标、键盘和激活事件汇总为关闭请求,`StatusItemController.popoverDidClose` 接收 AppKit 实际关闭回调;主动关闭容器前将 `activeMenuSurface` 设为 `none`,回调只对仍为当前容器的 popover 执行完整收尾
-- `MenuSurfaceFadeCoordinator` 同时调整内容视图和窗口透明度,淡入 0.24 秒、淡出 0.18 秒,只保留一个完成任务,新动画取消旧任务
-- popover 和备用面板分别持有 `MenuSurfaceAnimationState`,展示前允许动画,淡出期间保持开启,实际关闭后禁用;根视图在禁用时设置 `transaction.animation = nil` 和 `transaction.disablesAnimations = true`,后台刷新继续执行
-- 主面板淡入完成且仍可见时,检查 Hook 配置、本地统计和账户数据是否需要刷新;淡入完成前关闭面板会取消该回调
-- 任务流光消费独立展示更新,开关与主面板动画独立;多屏、焦点和终态时限见 [任务流光](Docs/DeveloperGuide/ui-and-lifecycle.md#任务流光)
-- 主面板的热力图详情、重置次数和任务中心使用 `borderless nonactivating child panel`;设置窗口的主面板布局、通知、自动重置和防睡眠选项使用可获得键盘焦点的 `borderless child panel`
-- 设置窗口的子面板占同一位置,展开一个必须先 `hide(immediate: true)` 收掉其余的;动作走 `SettingsOptionsPanelAction` 并带上目标 `SettingsOptionsPanel`,互斥与 `closeAll` 都只写在 `SettingsWindowController.handleOptionsAction` 一处,新增面板不会漏配对
-- 面板控制器只在首次展开时构造,收起动作走 `existingOptionsPanelController` 而不触发构造:`NSHostingController` 与动态面板订阅会常驻到 App 结束,而用户可能一次子面板都没开过
-- 四个设置子面板的顶边对齐各自设置行,anchor 由设置页的 `ScreenFrameProvider` 随展开动作传出,定位走 `SidePanelSupport.anchoredPosition` 而不是宿主底边
-- 设置窗口的子面板要传 `clampsToSurfaceBottom: false` 让底边可以探出窗口,否则放不下时会把整个面板上推而错开主开关行;主面板那三个面板走默认的 `true`
-- 通知和防睡眠面板的高度会动态变化,前者随音效行增删,后者随 `hasBattery` 增删低电量那一行;自动重置面板只有固定的一行;resize 时要固定顶边向下生长,直接改 size 会保持底边不动而把顶边顶离主开关行
-- 内容变化订阅要保持最小:主面板布局固定 5 行、自动重置面板固定 1 行,均不订高度变化;通知面板订 `notificationSettings` 与 `codexHookSettings` 的 `objectWillChange`,再加 `autoResetSettings.$isEnabled`、`KeepAliveController.$isLowBatteryProtectionEnabled` 与 `$isMaximumDurationEnabled`;防睡眠面板只订 `$hasBattery`;订整个防睡眠控制器会让任务每起停一次都白排一轮 resize
-- 置灰也会改高度:带音效的行置灰时音效子行跟着收起,所以每个置灰依赖都要有一个对应的订阅源
-- 增删行或改行的显示条件时要同步补上对应的订阅源,漏一项会让面板裁掉底部或留下空白
-- resize 的竖向夹紧走 `SidePanelSupport.clampedVertically`,与初次展开的 `position` 同一条规则,否则放不下时两边会把面板推向相反的边
-- 主面板布局入口始终可用;其他子面板入口只在开关开着且依赖就绪时出现,通知看 `NotificationSettings.canShowOptions`,自动重置要求 `AutoResetSettings.isEnabled` 且 `KeepAliveController.helperStatus == .enabled`,防睡眠看 `KeepAliveController.canShowOptions`;这些值只控制入口显隐,不回写用户保存的开关
-- 自动重置或防睡眠的子面板入口条件失效时,`AppSettingsView` 会发送对应的 `close` 动作收起已展开面板;关闭开关时对应设置行不显示状态说明
-- 四个设置子面板都只由滑杆按钮展开;单个面板的展开和条件失效收起分别使用 `toggle` 与 `close`,切换分页时使用 `closeAll`,开启主开关不自动弹出
-- 设置子面板收起时,`SidePanelSupport.orderOut` 只有在被关闭面板仍是 key window 时才把焦点还给父窗口;如果焦点已经转移到主面板或其他窗口,不得主动抢回
-- 侧边面板公共能力集中在 `Controllers/SidePanelSupport.swift`,重置次数、任务中心和设置子面板复用 `SidePanelDrawerPresenter`;热力图详情独立处理切边和延迟隐藏,复用 `SidePanelContentHost`、`SidePanelDrawerAnimator`、panel 工厂和定位夹紧
-- 热力图详情和共享抽屉在立即关闭或窗口已不可见时,重置动画并执行 `orderOut`、移除父子窗口关系;任务中心已结束逻辑展示时,立即关闭请求仍传递给 presenter
-- 设置窗口的子面板直接复用 `Controllers/SettingsOptionsPanelController.swift`,它在 presenter 之上补齐了装配、两套关闭观察者、顶边对齐定位和高度重算;新增设置子面板只要给它内容工厂,动态高度面板再提供内容变化来源,不要另写一层壳
-- 设置子面板的公共内边距、间距与外观度量从 `SettingsOptionsPanelMetrics` 取;通知、自动重置和防睡眠面板的下拉控件共用 `SettingsOptionsPicker`;主面板布局使用独立的 28 点拖拽行高且不使用下拉控件
-- 设置子面板的内容工厂必须走 `SettingsOptionsPanelController.makeContentController(_:rebuiltBy:)`,否则首次展开时原生 Switch 只剩一条空轨道;重建信号由它接在内容外面,内容视图不必知道 `SidePanelEntryCue`
-- 原因是 thumb 由 `WindowPortal` 投射而不是画在开关上,面板首次布局那一轮 portal 建不起来,而且不会自愈,只有一次内容重建才补得上;第二次展开正常是因为 hosting controller 常驻,复用了已经建好的那份
-- `MainPanelSettings.layout` 保存主面板区域顺序与显隐,至少保留一个区域。`updateHookEnabled(_:)` 在 Hook 关闭时隐藏任务区域,必要时开启账户;从关闭切换为开启时显示任务区域,启动恢复开启状态时保留用户布局。Hook 关闭时任务开关禁用,拖拽手柄可用
-- 主面板布局排序由手柄上的自定义 `DragGesture` 驱动,悬浮副本跟手移动,其他行按预览顺序实时让位,松手后才通过 `setSectionOrder(_:)` 保存最终顺序
-- 热力图详情面板跟随包含标题和方格矩阵的完整热力图区域定位,优先让两者顶边对齐;详情面板过高时通过 `SidePanelSupport.anchoredPosition` 上移到与主面板底边对齐,不能恢复为固定贴住主面板底边
-- `SettingsWindowController` 持有窗口组唯一的 `UndoManager`,设置主窗口和四个可聚焦子面板必须共享这一撤销栈,保证焦点切换后 `⌘Z` 与 `⌘⇧Z` 仍然有效;Hook 自动联动不注册为用户操作
-- 设置窗口高度跟随当前 tab 的完整内容,只在内容超过屏幕可见高度时允许滚动;首次构造时 SwiftUI 可能早于 `HostingWindowController.window` 赋值上报高度,`SettingsWindowController` 必须缓存最近测量并在窗口就绪后应用,不能用初始高度或延迟掩盖
-- 设置窗口(通用/高级/关于三页)和日志窗口复用 `HostingWindowController` 的行为,可以成为 key window,但不应成为 main window
-- 视觉风格统一走 `Views/Shared/LiquidGlassStyle.swift` 这一套,避免引入与系统菜单栏工具不一致的重装饰 UI
-
-## Hook 配置改写约束
-
-`~/.codex/hooks.json` 的读写全部在 `CodexHookSettings` 里完成,Codex 目录优先取 `CODEX_HOME` 环境变量,找不到时回退真实用户 HOME 下的 `.codex` 目录。
-
-- 只识别并移除 command 同时包含当前 CodexBar 可执行路径与 `--hook-event` 的 handler,必须保留用户已有 Hook 以及其他 App 的 Hook 和同事件下的其他 handler
-- 每个 `CodexHookEvent.allCases` 事件追加一个独立 group,handler 超时从 `WorkflowHookEventRecorder.hookTimeoutSeconds(for:)` 取得;新增事件时不得复制一份超时常量
-- 账户主链路要求当前 app-server 至少为 `0.145.0`,Hook 启用和校验要求至少为 `0.150.0`;版本依据为握手返回的实际连接信息
-- 写入前通过 app-server `config/read` 确认全局未禁用 Hook,写入后用 `hooks/list` 验证;两处读取共用 `readGlobalHookDisabled`,开关流程与校验流程对“全局禁用”的判断不会分叉
-- 读取失败(I/O 或 JSON 格式错误)不提供 Hook 装没装的信息,必须保留上次已知值,不能当成用户关闭了 Hook
-- `isEnabled` 表示当前进程中的 Hook 开启状态,首次从已有 handler 恢复;开启后配置缺失会触发自愈。`isVerified` 保存最近一次校验的明确结论,`isOperable` 为两者的合取
-- 实时任务、防睡眠和任务类通知必须看 `isOperable`;历史聚合与同步仍可消费已落盘数据,其调度只看 `isEnabled`,不要把两类依赖混在一起
-- `isVerified` 默认为 `true`,RPC 临时失败或取消时保留上次明确结论。启动、打开主面板、打开设置、App 激活和额度刷新完成时对账已开启 Hook
-- 全局禁用要排在 `hooks/list` 之前判:它一关列表里必然找不到我们的 handler,那时报“已不完整”会把用户引去翻本来就完好的 `hooks.json`
-- `refreshInstallationState()` 检查 handler 是否存在及事件是否完整;已开启配置缺少必要事件或信任项时,`reconcileInstalledHooks()` 自动补齐并重新校验。启动前已无可识别 handler 时保持关闭
-- 防睡眠开关关闭时说明行收起;开关开启且 Hook 校验不通过时显示“CodexBar Hook 未生效”,具体病因由 Hook 设置行说明
-
-## 隐私与数据边界
-
-改动涉及网络、日志或同步时必须遵守:
-
-- App 只有三类外部通信行为,分别是本机 app-server stdio 通信(不算网络)、Sparkle 更新、用户显式开启后的 CloudKit 同步;新增网络请求需要非常明确的理由
-- 账户、额度、Token 用量和 Reset Credits 明细统一通过本机 app-server 获取;Sparkle 更新走 `https://codexbar.zabrian.app/appcast.xml` 这个 feed
-- 不展示 app-server stderr;不展示或记录 Codex OAuth token;不把原始敏感 RPC 响应写进文档
-- CloudKit 只同步去掉 `sessionIds` 与 `turnIds` 的 daily 聚合,不同步原始 Hook events、账号、额度或 Token 用量
-- 异常会话保护状态只保存在本机,不同步 CloudKit;记录不含原始 session ID、turn ID、项目名或任务内容
-- CloudKit 的 `sessionEndCount`、`userPromptSubmitCount` 与其他 Hook 计数字段保持可选,远端缺失表示历史来源没有提供,不能在读取时补成 `0`;改变远端格式时同时评估并更新 `syncSchemaVersion`
-- 系统日志不写用户数据:额度与 Token 用量只记 `state=` 这类结果分类,任务内容、项目名、会话与轮次标识一律不记;可执行文件路径含用户名,用 `source=global|bundled` 之类的标识代替
-- 事件数、任务数、日期这类聚合数字可以记,它们是判断重建是否正确和定位哪天出问题的依据,不含任何内容
-
-## 验证与文档
-
-构建、日志和各功能验证入口见 [开发与验证](Docs/DeveloperGuide/development.md)。不要提交发布产物、DerivedData、临时 DMG、签名文件或个人凭据。
diff --git a/CodexBar/Controllers/SettingsOptionsPanelController.swift b/CodexBar/Controllers/SettingsOptionsPanelController.swift
index decb3f6..d8f7249 100644
--- a/CodexBar/Controllers/SettingsOptionsPanelController.swift
+++ b/CodexBar/Controllers/SettingsOptionsPanelController.swift
@@ -51,6 +51,7 @@ final class SettingsOptionsPanelController {
private let initialPanelSize: CGSize
/// 展开前的准备动作, 例如刷新只在这个面板里露面的设置项
private let willShow: (() -> Void)?
+ private let willHide: (() -> Void)?
private let contentControllerProvider: (SidePanelEntryCue) -> NSViewController
private let entryCue = SidePanelEntryCue()
@@ -72,12 +73,14 @@ final class SettingsOptionsPanelController {
animationKey: String,
initialPanelSize: CGSize,
willShow: (() -> Void)? = nil,
+ willHide: (() -> Void)? = nil,
contentProvider: @escaping () -> some View,
contentChanges: AnyPublisher<Void, Never>? = nil
) {
self.animationKey = animationKey
self.initialPanelSize = initialPanelSize
self.willShow = willShow
+ self.willHide = willHide
// 内容闭包在首次构造面板时才执行, 保留 SwiftUI 状态的创建时机
contentControllerProvider = { cue in
let controller = NSHostingController(
@@ -120,6 +123,9 @@ final class SettingsOptionsPanelController {
}
func hide(immediate: Bool = false) {
+ if isVisible {
+ willHide?()
+ }
panelResizeTask?.cancel()
panelResizeTask = nil
isEntryAnimationRunning = false
diff --git a/CodexBar/Controllers/SettingsWindowController.swift b/CodexBar/Controllers/SettingsWindowController.swift
index a743290..6fe133e 100644
--- a/CodexBar/Controllers/SettingsWindowController.swift
+++ b/CodexBar/Controllers/SettingsWindowController.swift
@@ -197,6 +197,7 @@ final class SettingsWindowController: HostingWindowController {
SettingsOptionsPanelController(
animationKey: "CodexBar.taskGlowOptionsDrawerTransform",
initialPanelSize: TaskGlowOptionsView.initialPanelSize,
+ willHide: { [taskGlowSettings] in taskGlowSettings.endColorPreview() },
contentProvider: { [taskGlowSettings] in
TaskGlowOptionsView(settings: taskGlowSettings)
}
diff --git a/CodexBar/Controllers/TaskGlowController.swift b/CodexBar/Controllers/TaskGlowController.swift
index e1cb563..255aed0 100644
--- a/CodexBar/Controllers/TaskGlowController.swift
+++ b/CodexBar/Controllers/TaskGlowController.swift
@@ -17,8 +17,8 @@ final class TaskGlowController {
private var expirationTask: Task<Void, Never>?
private var scheduledExpiration: Date?
private var hidePanelsTask: Task<Void, Never>?
- private var previewTask: Task<Void, Never>?
- private var isPreviewVisible = false
+ private var preview: TaskGlowPreviewPresentation?
+ private var playback: TaskGlowPlayback?
private var isSystemSleeping = false
private var isDisplaySleeping = false
private var isSessionActive = true
@@ -38,7 +38,6 @@ final class TaskGlowController {
deinit {
expirationTask?.cancel()
hidePanelsTask?.cancel()
- previewTask?.cancel()
}
func start() {
@@ -50,19 +49,16 @@ final class TaskGlowController {
)
.sink { [weak self] enabled, hookEnabled, hookVerified in
guard let self else { return }
- if !hookEnabled || !hookVerified {
+ if !enabled || !hookEnabled || !hookVerified {
cancelPreview()
}
- if !enabled {
- isPreviewVisible = false
- }
isEnabled = enabled && hookEnabled && hookVerified
consume(CodexActivityPresentationUpdate(snapshot: activityMonitor.snapshot, terminalEvents: []))
}
.store(in: &cancellables)
settings.previewRequests
- .sink { [weak self] in self?.previewEnabled() }
+ .sink { [weak self] in self?.handlePreviewRequest($0) }
.store(in: &cancellables)
settings.$appearance
@@ -71,8 +67,12 @@ final class TaskGlowController {
guard let self else { return }
self.appearance = appearance
motionClock.setAnimationSpeed(appearance.animationSpeed)
- if isPreviewVisible {
- schedulePreviewEnd()
+ if preview != nil {
+ preview?.setAnimationSpeed(appearance.animationSpeed, now: Date())
+ playback = preview?.playback
+ if preview?.state == .running, let playback {
+ motionClock.restart(at: playback.mediaStart)
+ }
}
refreshPresentation()
}
@@ -116,39 +116,55 @@ final class TaskGlowController {
removePanels()
}
- private func previewEnabled() {
- guard previewTask == nil, hidePanelsTask == nil, isEnabled, hookSettings.isOperable,
+ private func handlePreviewRequest(_ request: TaskGlowPreviewRequest) {
+ if request == .endColorPreview {
+ if preview?.isColorPreview == true {
+ finishPreview()
+ }
+ return
+ }
+ guard isEnabled, hookSettings.isOperable,
!isSystemSleeping, !isDisplaySleeping, isSessionActive else { return }
- // 播放和收尾期间不重播, 提前关闭时由实际收尾完成释放预览
- removePanels()
- isPreviewVisible = true
- motionClock.setRunning(true)
- schedulePreviewEnd()
- updatePanels()
+ let role: TaskGlowColorRole
+ switch request {
+ case .enabled:
+ guard preview == nil, hidePanelsTask == nil else { return }
+ role = .running
+ case let .color(selectedRole): role = selectedRole
+ case .endColorPreview: return
+ }
+ let now = Date()
+ presentation.refresh(now: now, terminalDuration: appearance.terminalDuration)
+ presentation.suspend(now: now)
+ let playback = makePlayback(now: now)
+ self.playback = playback
+ preview = TaskGlowPreviewPresentation(
+ role: role, isColorPreview: request != .enabled,
+ playback: playback, speed: appearance.animationSpeed
+ )
+ motionClock.restart(at: playback.mediaStart)
+ refreshPresentation()
}
- private func schedulePreviewEnd() {
- previewTask?.cancel()
- let startTime = motionClock.startTime()
- let cycleDuration = motionClock.cycleDuration
- previewTask = Task { @MainActor [weak self] in
- do {
- let remaining = max(0, startTime + cycleDuration - CACurrentMediaTime())
- try await Task.sleep(for: .seconds(remaining))
- } catch {
- return
- }
- guard let self, !Task.isCancelled else { return }
- previewTask = nil
- isPreviewVisible = false
- refreshPresentation()
- }
+ private func makePlayback(now: Date) -> TaskGlowPlayback {
+ let delay = panels.map(\.indicatorView.interruptionDelay).max() ?? 0
+ return TaskGlowPlayback(startsAt: now.addingTimeInterval(delay), mediaStart: CACurrentMediaTime() + delay)
+ }
+
+ private func finishPreview() {
+ guard preview != nil else { return }
+ preview = nil
+ let playback = makePlayback(now: Date())
+ self.playback = playback
+ presentation.resume(now: playback.startsAt)
+ motionClock.restart(at: playback.mediaStart)
+ refreshPresentation()
}
private func cancelPreview() {
- previewTask?.cancel()
- previewTask = nil
- isPreviewVisible = false
+ preview = nil
+ playback = nil
+ presentation.resume(now: Date())
}
private func consume(_ update: CodexActivityPresentationUpdate) {
@@ -164,8 +180,8 @@ final class TaskGlowController {
private func refreshPresentation() {
presentation.refresh(now: Date(), terminalDuration: appearance.terminalDuration)
- let expiration = presentation.terminal?.expiresAt
updatePanels()
+ let expiration = preview?.expiresAt ?? (presentation.isSuspended ? nil : presentation.terminal?.expiresAt)
guard expiration != scheduledExpiration else { return }
expirationTask?.cancel()
expirationTask = nil
@@ -181,7 +197,12 @@ final class TaskGlowController {
guard let self, !Task.isCancelled else { return }
scheduledExpiration = nil
expirationTask = nil
- refreshPresentation()
+ // 相同期限可能跨越预览和真实状态, 到期时按当前展示选择动作
+ if preview != nil {
+ finishPreview()
+ } else {
+ refreshPresentation()
+ }
}
}
@@ -195,6 +216,9 @@ final class TaskGlowController {
case NSWorkspace.sessionDidBecomeActiveNotification: isSessionActive = true
default: break
}
+ if isSystemSleeping || isDisplaySleeping || !isSessionActive {
+ cancelPreview()
+ }
// 唤醒时按墙上时间重算, 不恢复已经过期的终态光带
refreshPresentation()
}
@@ -205,7 +229,7 @@ final class TaskGlowController {
removePanels()
return
}
- let state: TaskGlowState = isPreviewVisible ? .running : presentation.state
+ let state = preview?.state ?? presentation.state
motionClock.setRunning(state == .running)
if state == .hidden {
guard !panels.isEmpty else {
@@ -220,7 +244,7 @@ final class TaskGlowController {
for panel in closingPanels {
guard await panel.indicatorView.waitForDismissal() else { return }
}
- guard let self, !Task.isCancelled, !isPreviewVisible, presentation.state == .hidden else { return }
+ guard let self, !Task.isCancelled, preview == nil, presentation.state == .hidden else { return }
cancelPreview()
removePanels()
}
@@ -235,8 +259,9 @@ final class TaskGlowController {
panel.indicatorView.update(
state: state,
appearance: appearance,
- terminalPresentation: isPreviewVisible ? nil : presentation.terminal,
- repeatsMotion: !isPreviewVisible
+ terminalPresentation: preview == nil ? presentation.terminal : preview?.terminal,
+ repeatsMotion: preview == nil,
+ playback: playback
)
if !panel.isVisible {
panel.orderFrontRegardless()
@@ -259,142 +284,9 @@ final class TaskGlowController {
}
}
-private extension CodexActivityTerminalEvent {
- var glowState: TaskGlowState {
- switch self {
- case .completed: .completed
- case .terminated: .terminated
- }
- }
-}
-
-/// 短提示只消费开启后新增的结束记录, 到期后按最新快照恢复等待或运行状态
-struct TaskGlowPresentationState {
- private var snapshot = CodexActivitySnapshot.empty
- private var enabledAt: Date?
- private var briefEvent: CodexActivityTerminalEvent?
- private var briefExpiration: Date?
- private(set) var state = TaskGlowState.hidden
- private(set) var terminal: TaskGlowTerminalPresentation?
-
- mutating func update(
- snapshot: CodexActivitySnapshot,
- terminalEvents: [CodexActivityTerminalEvent],
- isEnabled: Bool,
- acceptsBriefEvents: Bool,
- now: Date
- ) {
- let latestEvent = terminalEvents.max { lhs, rhs in
- if lhs.endedAt != rhs.endedAt {
- return lhs.endedAt < rhs.endedAt
- }
- if lhs.glowState != rhs.glowState {
- return rhs.glowState == .terminated
- }
- return lhs.id.uuidString < rhs.id.uuidString
- }
- if isEnabled, let enabledAt, acceptsBriefEvents,
- snapshot.hasActiveTasks,
- let latestEvent, latestEvent.endedAt >= enabledAt {
- briefEvent = latestEvent
- briefExpiration = now.addingTimeInterval(3)
- }
- if !isEnabled || !acceptsBriefEvents || !snapshot.hasActiveTasks {
- briefEvent = nil
- briefExpiration = nil
- }
- if !isEnabled {
- enabledAt = nil
- } else if enabledAt == nil {
- enabledAt = now
- }
- self.snapshot = snapshot
- }
-
- mutating func refresh(now: Date, terminalDuration: TimeInterval) {
- guard enabledAt != nil else {
- state = .hidden
- terminal = nil
- return
- }
- if let briefExpiration, now >= briefExpiration {
- briefEvent = nil
- self.briefExpiration = nil
- }
- if snapshot.hasActiveTasks, let briefEvent, let briefExpiration {
- show(briefEvent, until: briefExpiration, fadeDuration: 0.5, now: now)
- return
- }
- if snapshot.waitingCount > 0 {
- state = .waiting
- } else if snapshot.runningCount > 0 {
- state = .running
- } else if let event = snapshot.latestTerminalEvent,
- now < event.endedAt.addingTimeInterval(terminalDuration) {
- show(event, until: event.endedAt.addingTimeInterval(terminalDuration), fadeDuration: 1, now: now)
- return
- } else {
- state = .hidden
- }
- terminal = nil
- }
-
- private mutating func show(_ event: CodexActivityTerminalEvent, until expiration: Date, fadeDuration: TimeInterval, now: Date) {
- terminal = TaskGlowTerminalPresentation(
- eventID: event.id,
- startedAt: terminal.flatMap { $0.eventID == event.id ? $0.startedAt : nil } ?? now,
- expiresAt: expiration,
- fadeDuration: fadeDuration
- )
- state = event.glowState
- }
-}
-
-enum TaskGlowState {
- case hidden
- case running
- case waiting
- case completed
- case terminated
-
- func color(in appearance: TaskGlowAppearance) -> NSColor {
- switch self {
- case .hidden: .clear
- case .running: appearance.color(for: .running)
- case .waiting: appearance.color(for: .waiting)
- case .completed: appearance.color(for: .completed)
- case .terminated: appearance.color(for: .terminated)
- }
- }
-}
-
-/// 终态共用墙上时间, 屏幕重建和唤醒后接续淡出, 不重新提亮
-struct TaskGlowTerminalPresentation: Equatable {
- static let entranceDuration: TimeInterval = 1.2
- let eventID: UUID
- let startedAt: Date
- let expiresAt: Date
- let fadeDuration: TimeInterval
-
- var duration: TimeInterval {
- max(0, expiresAt.timeIntervalSince(startedAt))
- }
-
- var entranceDuration: TimeInterval {
- min(Self.entranceDuration, duration / 4)
- }
-
- var holdDuration: TimeInterval {
- max(0, duration - fadeDuration)
- }
-}
-
/// 所有屏幕共享同一运动周期, 新窗口直接加入当前进度
private final class TaskGlowMotionClock {
- static let travelDuration = 2.0
- static let offscreenDuration = 0.2
- static let centerRetractionDuration = 0.3
- private static let standardCycleDuration = travelDuration + offscreenDuration * 2 + centerRetractionDuration
+ private static let standardCycleDuration = TaskGlowAnimationTiming.cycleDuration
private(set) var cycleDuration = standardCycleDuration
private var isRunning = false
private var startedAt: CFTimeInterval?
@@ -416,6 +308,11 @@ private final class TaskGlowMotionClock {
startedAt = nil
}
+ func restart(at time: CFTimeInterval) {
+ isRunning = true
+ startedAt = time
+ }
+
func startTime() -> CFTimeInterval {
if let startedAt {
return startedAt
@@ -477,7 +374,6 @@ private final class TaskGlowView: NSView {
private let lightLayer = CALayer()
private var lightSegments: [CAShapeLayer] = []
static let visibilityDuration = 0.24
- private static let edgeTraversalDuration = 0.7
private static let segmentsPerSide = 32
private static let stationaryColorAlpha: CGFloat = 0.9
private let convergencePoint = 0.5
@@ -487,6 +383,7 @@ private final class TaskGlowView: NSView {
private var contentState: TaskGlowState?
private var transitionTask: Task<Void, Never>?
private var repeatsMotion = true
+ private var playback: TaskGlowPlayback?
private var glowAppearance = TaskGlowAppearance()
init(
@@ -530,26 +427,46 @@ private final class TaskGlowView: NSView {
fatalError("init(coder:) has not been implemented")
}
+ private var hasArtwork: Bool {
+ contentState != nil && (layer?.presentation()?.opacity ?? layer?.opacity ?? 0) > 0.001
+ }
+
+ var interruptionDelay: TimeInterval {
+ guard hasArtwork else { return 0 }
+ let distance: CGFloat = if !trackLayer.isHidden {
+ 0.5
+ } else {
+ lightSegments.map { segment in
+ let current = segment.presentation() ?? segment
+ return max(abs(current.strokeStart - convergencePoint), abs(current.strokeEnd - convergencePoint))
+ }.max() ?? 0
+ }
+ return max(0.001, Double(distance) * TaskGlowAnimationTiming.edgeTraversalDuration) + TaskGlowAnimationTiming.transitionGap
+ }
+
func update(
state: TaskGlowState,
appearance glowAppearance: TaskGlowAppearance,
terminalPresentation: TaskGlowTerminalPresentation? = nil,
- repeatsMotion: Bool = true
+ repeatsMotion: Bool = true,
+ playback: TaskGlowPlayback? = nil
) {
let previousAppearance = applyAppearance(glowAppearance, state: state)
- if presentationState == state, self.terminalPresentation == terminalPresentation, self.repeatsMotion == repeatsMotion {
+ let changesPlayback = self.playback?.id != playback?.id
+ self.playback = playback
+ if !changesPlayback, presentationState == state, self.terminalPresentation == terminalPresentation, self.repeatsMotion == repeatsMotion {
refreshStableAppearance(state, previous: previousAppearance)
return
}
- let continuesRunning = presentationState == .running && state == .running
- let continuesTerminal = presentationState == state && self.terminalPresentation != nil && terminalPresentation != nil
+ let continuesRunning = !changesPlayback && presentationState == .running && state == .running
+ let continuesTerminal = !changesPlayback && presentationState == state && self.terminalPresentation != nil && terminalPresentation != nil
// 同色提示延长时保留尚未完成的展开, 收尾会读取最新的淡出期限
if continuesTerminal, transitionTask != nil {
self.terminalPresentation = terminalPresentation
return
}
let terminalOpacity = continuesTerminal ? (trackLayer.presentation() ?? trackLayer).opacity : nil
- let hasArtwork = contentState != nil && (layer?.presentation()?.opacity ?? layer?.opacity ?? 0) > 0.001
+ let hasArtwork = hasArtwork
presentationState = state
self.terminalPresentation = terminalPresentation
self.repeatsMotion = repeatsMotion
@@ -580,32 +497,7 @@ private final class TaskGlowView: NSView {
transitionTask = Task { @MainActor [weak self] in
guard let self, !Task.isCancelled else { return }
do {
- if hasArtwork {
- let duration = animateExtent(expanded: false)
- try await Task.sleep(for: .seconds(duration))
- guard !Task.isCancelled else { return }
- }
- if state == .hidden {
- contentState = nil
- animateVisibility(to: 0)
- try await Task.sleep(for: .seconds(Self.visibilityDuration))
- try Task.checkCancellation()
- } else {
- if hasArtwork {
- try await Task.sleep(for: .seconds(0.06))
- guard !Task.isCancelled else { return }
- }
- if state == .running {
- showStable(.running)
- fadeInMovingLight()
- } else {
- setCollapsedColor(state.color(in: self.glowAppearance))
- let duration = animateExtent(expanded: true)
- try await Task.sleep(for: .seconds(duration))
- guard !Task.isCancelled else { return }
- showStable(state)
- }
- }
+ try await transition(to: state, hasArtwork: hasArtwork, playback: changesPlayback ? playback : nil)
transitionTask = nil
} catch {
return
@@ -613,6 +505,37 @@ private final class TaskGlowView: NSView {
}
}
+ private func transition(to state: TaskGlowState, hasArtwork: Bool, playback: TaskGlowPlayback?) async throws {
+ if hasArtwork {
+ let duration = animateExtent(expanded: false)
+ // 预览切换共享收回期限, 避免不同屏幕分别开始计时
+ let wait = playback.map { max(0, $0.mediaStart - CACurrentMediaTime()) } ?? duration
+ try await Task.sleep(for: .seconds(wait))
+ try Task.checkCancellation()
+ }
+ if state == .hidden {
+ contentState = nil
+ animateVisibility(to: 0)
+ try await Task.sleep(for: .seconds(Self.visibilityDuration))
+ try Task.checkCancellation()
+ return
+ }
+ let delay = playback.map { max(0, $0.mediaStart - CACurrentMediaTime()) }
+ ?? (hasArtwork ? TaskGlowAnimationTiming.transitionGap : 0)
+ try await Task.sleep(for: .seconds(delay))
+ try Task.checkCancellation()
+ if state == .running {
+ showStable(.running)
+ fadeInMovingLight()
+ } else {
+ setCollapsedColor(state.color(in: glowAppearance))
+ let duration = animateExtent(expanded: true)
+ try await Task.sleep(for: .seconds(duration))
+ try Task.checkCancellation()
+ showStable(state)
+ }
+ }
+
private func applyAppearance(_ appearance: TaskGlowAppearance, state: TaskGlowState) -> TaskGlowAppearance {
let previous = glowAppearance
glowAppearance = appearance
@@ -701,7 +624,10 @@ private final class TaskGlowView: NSView {
animation.values = [1, 0, 0, 1]
animation.keyTimes = [0, 0.45, 0.55, 1]
animation.duration = 1.5 * glowAppearance.animationSpeed.durationMultiplier
- animation.repeatCount = .infinity
+ if !repeatsMotion, let playback {
+ animation.beginTime = trackLayer.convertTime(playback.mediaStart + TaskGlowAnimationTiming.expansionDuration, from: nil)
+ }
+ animation.repeatCount = repeatsMotion ? .infinity : 2
animation.timingFunctions = [
CAMediaTimingFunction(name: .easeInEaseOut),
CAMediaTimingFunction(name: .linear),
@@ -778,7 +704,7 @@ private final class TaskGlowView: NSView {
let distance = zip(lightSegments, targets).map { segment, target in
max(abs(segment.strokeStart - target.start), abs(segment.strokeEnd - target.end))
}.max() ?? 0
- let duration = max(0.001, Double(distance) * Self.edgeTraversalDuration)
+ let duration = max(0.001, Double(distance) * TaskGlowAnimationTiming.edgeTraversalDuration)
CATransaction.begin()
CATransaction.setDisableActions(true)
for (segment, target) in zip(lightSegments, targets) {
@@ -846,10 +772,10 @@ private final class TaskGlowView: NSView {
/// 各屏幕共享出发和掉头时刻, 回程拖尾完全收进中心后才开始下一轮
private func animateEmission(_ segment: CAShapeLayer, tailLength: Double, span: Double, isLeft: Bool, startTime: CFTimeInterval) {
let multiplier = glowAppearance.animationSpeed.durationMultiplier
- let halfCrossing = TaskGlowMotionClock.travelDuration / 2 * multiplier
- let offscreen = TaskGlowMotionClock.offscreenDuration * multiplier
+ let halfCrossing = TaskGlowAnimationTiming.travelDuration / 2 * multiplier
+ let offscreen = TaskGlowAnimationTiming.offscreenDuration * multiplier
let outwardDuration = halfCrossing + offscreen
- let inwardDuration = halfCrossing + offscreen + TaskGlowMotionClock.centerRetractionDuration * multiplier
+ let inwardDuration = halfCrossing + offscreen + TaskGlowAnimationTiming.centerRetractionDuration * multiplier
let outward = emissionAnimation(
waypoints: [(0, convergencePoint), (halfCrossing, 1), (outwardDuration, 1 + span)],
tailLength: tailLength, isLeft: isLeft
diff --git a/CodexBar/Models/TaskGlowPresentationState.swift b/CodexBar/Models/TaskGlowPresentationState.swift
new file mode 100644
index 0000000..2007a16
--- /dev/null
+++ b/CodexBar/Models/TaskGlowPresentationState.swift
@@ -0,0 +1,227 @@
+import AppKit
+import QuartzCore
+
+private extension CodexActivityTerminalEvent {
+ var glowState: TaskGlowState {
+ switch self {
+ case .completed: .completed
+ case .terminated: .terminated
+ }
+ }
+}
+
+/// 短提示只消费开启后新增的结束记录, 到期后按最新快照恢复等待或运行状态
+struct TaskGlowPresentationState {
+ private var snapshot = CodexActivitySnapshot.empty
+ private var enabledAt: Date?
+ private var briefEvent: CodexActivityTerminalEvent?
+ private var briefExpiration: Date?
+ private var suspendedAt: Date?
+ private var resumesAt: Date?
+ private var terminalEventID: UUID?
+ private var terminalTimeOffset: TimeInterval = 0
+ private(set) var state = TaskGlowState.hidden
+ private(set) var terminal: TaskGlowTerminalPresentation?
+
+ var isSuspended: Bool {
+ suspendedAt != nil
+ }
+
+ mutating func suspend(now: Date) {
+ guard suspendedAt == nil else { return }
+ // 恢复过渡尚未结束就再次预览时, 撤销提前计入的收回时间
+ let pendingDelay = max(0, resumesAt?.timeIntervalSince(now) ?? 0)
+ terminalTimeOffset -= pendingDelay
+ briefExpiration = briefExpiration?.addingTimeInterval(-pendingDelay)
+ suspendedAt = now
+ resumesAt = nil
+ }
+
+ /// 只平移展示期限, 不修改任务事件时间; 新事件在暂停期间保留完整时长
+ mutating func resume(now: Date) {
+ guard let suspendedAt else { return }
+ let elapsed = max(0, now.timeIntervalSince(suspendedAt))
+ terminalTimeOffset += elapsed
+ briefExpiration = briefExpiration?.addingTimeInterval(elapsed)
+ self.suspendedAt = nil
+ resumesAt = now
+ terminal = nil
+ }
+
+ mutating func update(
+ snapshot: CodexActivitySnapshot,
+ terminalEvents: [CodexActivityTerminalEvent],
+ isEnabled: Bool,
+ acceptsBriefEvents: Bool,
+ now: Date
+ ) {
+ let latestEvent = terminalEvents.max { lhs, rhs in
+ if lhs.endedAt != rhs.endedAt {
+ return lhs.endedAt < rhs.endedAt
+ }
+ if lhs.glowState != rhs.glowState {
+ return rhs.glowState == .terminated
+ }
+ return lhs.id.uuidString < rhs.id.uuidString
+ }
+ if isEnabled, let enabledAt, acceptsBriefEvents,
+ snapshot.hasActiveTasks,
+ let latestEvent, latestEvent.endedAt >= enabledAt {
+ briefEvent = latestEvent
+ briefExpiration = (suspendedAt ?? now).addingTimeInterval(3)
+ }
+ if !isEnabled || !acceptsBriefEvents || !snapshot.hasActiveTasks {
+ briefEvent = nil
+ briefExpiration = nil
+ }
+ if !isEnabled {
+ enabledAt = nil
+ suspendedAt = nil
+ resumesAt = nil
+ terminalEventID = nil
+ terminalTimeOffset = 0
+ } else if enabledAt == nil {
+ enabledAt = now
+ }
+ self.snapshot = snapshot
+ if let event = snapshot.latestTerminalEvent, event.id != terminalEventID {
+ terminalEventID = event.id
+ terminalTimeOffset = suspendedAt.map { min(0, $0.timeIntervalSince(event.endedAt)) } ?? 0
+ }
+ }
+
+ mutating func refresh(now: Date, terminalDuration: TimeInterval) {
+ let now = suspendedAt ?? max(now, resumesAt ?? now)
+ guard enabledAt != nil else {
+ state = .hidden
+ terminal = nil
+ return
+ }
+ if let briefExpiration, now >= briefExpiration {
+ briefEvent = nil
+ self.briefExpiration = nil
+ }
+ if snapshot.hasActiveTasks, let briefEvent, let briefExpiration {
+ show(briefEvent, until: briefExpiration, fadeDuration: 0.5, now: now)
+ return
+ }
+ if snapshot.waitingCount > 0 {
+ state = .waiting
+ } else if snapshot.runningCount > 0 {
+ state = .running
+ } else if let event = snapshot.latestTerminalEvent,
+ now < event.endedAt.addingTimeInterval(terminalDuration + terminalTimeOffset) {
+ show(event, until: event.endedAt.addingTimeInterval(terminalDuration + terminalTimeOffset), fadeDuration: 1, now: now)
+ return
+ } else {
+ state = .hidden
+ }
+ terminal = nil
+ }
+
+ private mutating func show(_ event: CodexActivityTerminalEvent, until expiration: Date, fadeDuration: TimeInterval, now: Date) {
+ terminal = TaskGlowTerminalPresentation(
+ eventID: event.id,
+ startedAt: terminal.flatMap { $0.eventID == event.id ? $0.startedAt : nil } ?? now,
+ expiresAt: expiration,
+ fadeDuration: fadeDuration
+ )
+ state = event.glowState
+ }
+}
+
+/// 同一轮切换共用开始时刻, 收回旧光带的时间不占用目标效果的展示时长
+struct TaskGlowPlayback {
+ let id = UUID()
+ var startsAt: Date
+ var mediaStart: CFTimeInterval
+}
+
+struct TaskGlowPreviewPresentation {
+ let role: TaskGlowColorRole
+ let isColorPreview: Bool
+ var playback: TaskGlowPlayback
+ private(set) var speed: TaskGlowAnimationSpeed
+
+ var state: TaskGlowState {
+ switch role {
+ case .running: .running
+ case .waiting: .waiting
+ case .completed: .completed
+ case .terminated: .terminated
+ }
+ }
+
+ var expiresAt: Date {
+ let duration: TimeInterval = switch role {
+ case .running: TaskGlowAnimationTiming.cycleDuration * speed.durationMultiplier
+ case .waiting: TaskGlowAnimationTiming.expansionDuration + 3 * speed.durationMultiplier
+ case .completed, .terminated: 3
+ }
+ return playback.startsAt.addingTimeInterval(duration)
+ }
+
+ var terminal: TaskGlowTerminalPresentation? {
+ guard role == .completed || role == .terminated else { return nil }
+ return TaskGlowTerminalPresentation(eventID: playback.id, startedAt: playback.startsAt, expiresAt: expiresAt, fadeDuration: 0.5)
+ }
+
+ mutating func setAnimationSpeed(_ speed: TaskGlowAnimationSpeed, now: Date) {
+ defer { self.speed = speed }
+ guard speed != self.speed, role == .running || role == .waiting else { return }
+ let entrance = role == .waiting ? TaskGlowAnimationTiming.expansionDuration : 0
+ let elapsed = max(0, now.timeIntervalSince(playback.startsAt) - entrance)
+ let shift = elapsed * (1 - speed.durationMultiplier / self.speed.durationMultiplier)
+ playback.startsAt = playback.startsAt.addingTimeInterval(shift)
+ playback.mediaStart += shift
+ }
+}
+
+enum TaskGlowAnimationTiming {
+ static let travelDuration = 2.0
+ static let offscreenDuration = 0.2
+ static let centerRetractionDuration = 0.3
+ static let cycleDuration = travelDuration + offscreenDuration * 2 + centerRetractionDuration
+ static let edgeTraversalDuration = 0.7
+ static let expansionDuration = edgeTraversalDuration / 2
+ static let transitionGap = 0.06
+}
+
+enum TaskGlowState {
+ case hidden
+ case running
+ case waiting
+ case completed
+ case terminated
+
+ func color(in appearance: TaskGlowAppearance) -> NSColor {
+ switch self {
+ case .hidden: .clear
+ case .running: appearance.color(for: .running)
+ case .waiting: appearance.color(for: .waiting)
+ case .completed: appearance.color(for: .completed)
+ case .terminated: appearance.color(for: .terminated)
+ }
+ }
+}
+
+/// 终态共用墙上时间, 屏幕重建和唤醒后接续淡出, 不重新提亮
+struct TaskGlowTerminalPresentation: Equatable {
+ static let entranceDuration: TimeInterval = 1.2
+ let eventID: UUID
+ let startedAt: Date
+ let expiresAt: Date
+ let fadeDuration: TimeInterval
+
+ var duration: TimeInterval {
+ max(0, expiresAt.timeIntervalSince(startedAt))
+ }
+
+ var entranceDuration: TimeInterval {
+ min(Self.entranceDuration, duration / 4)
+ }
+
+ var holdDuration: TimeInterval {
+ max(0, duration - fadeDuration)
+ }
+}
diff --git a/CodexBar/Resources/Localizable.xcstrings b/CodexBar/Resources/Localizable.xcstrings
index 3902885..ff4b03a 100644
--- a/CodexBar/Resources/Localizable.xcstrings
+++ b/CodexBar/Resources/Localizable.xcstrings
@@ -4977,6 +4977,22 @@
}
}
},
+ "task-glow.color.preview-help" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Double-click to preview effect"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "双击预览效果"
+ }
+ }
+ }
+ },
"task-glow.color.running" : {
"localizations" : {
"en" : {
diff --git a/CodexBar/Services/Settings/TaskGlowSettings.swift b/CodexBar/Services/Settings/TaskGlowSettings.swift
index 19b4384..7dc5fa6 100644
--- a/CodexBar/Services/Settings/TaskGlowSettings.swift
+++ b/CodexBar/Services/Settings/TaskGlowSettings.swift
@@ -89,12 +89,12 @@ final class TaskGlowSettings: ObservableObject {
nonisolated static let terminalDurationOptions: [TimeInterval] = [3, 5, 10, 15, 30, 60]
static let brightnessRange = 0.2 ... 1.0
- var previewRequests: AnyPublisher<Void, Never> {
+ var previewRequests: AnyPublisher<TaskGlowPreviewRequest, Never> {
previewSubject.eraseToAnyPublisher()
}
private let defaults: UserDefaults
- private let previewSubject = PassthroughSubject<Void, Never>()
+ private let previewSubject = PassthroughSubject<TaskGlowPreviewRequest, Never>()
private static let enabledKey = "TaskGlow.isEnabled"
private static let speedKey = "TaskGlow.animationSpeed"
private static let durationKey = "TaskGlow.terminalDuration"
@@ -126,10 +126,19 @@ final class TaskGlowSettings: ObservableObject {
defaults.set(enabled, forKey: Self.enabledKey)
isEnabled = enabled
if enabled {
- previewSubject.send()
+ previewSubject.send(.enabled)
}
}
+ func previewColor(for role: TaskGlowColorRole) {
+ guard isEnabled else { return }
+ previewSubject.send(.color(role))
+ }
+
+ func endColorPreview() {
+ previewSubject.send(.endColorPreview)
+ }
+
func setColorHex(_ input: String, for role: TaskGlowColorRole) {
if input.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
defaults.removeObject(forKey: Self.colorKey(role))
@@ -184,3 +193,9 @@ final class TaskGlowSettings: ObservableObject {
return appearance
}
}
+
+enum TaskGlowPreviewRequest: Equatable {
+ case enabled
+ case color(TaskGlowColorRole)
+ case endColorPreview
+}
diff --git a/CodexBar/Views/Settings/TaskGlowOptionsView.swift b/CodexBar/Views/Settings/TaskGlowOptionsView.swift
index 9c02d3f..72211f1 100644
--- a/CodexBar/Views/Settings/TaskGlowOptionsView.swift
+++ b/CodexBar/Views/Settings/TaskGlowOptionsView.swift
@@ -188,6 +188,12 @@ private struct TaskGlowColorHexField: View {
.strokeBorder(.primary.opacity(0.15), lineWidth: 0.5)
}
.frame(width: 14, height: 14)
+ .frame(height: SettingsOptionsPanelMetrics.rowHeight)
+ .contentShape(Rectangle())
+ .onTapGesture(count: 2) {
+ settings.previewColor(for: role)
+ }
+ .help("task-glow.color.preview-help")
Text(verbatim: "#")
.font(.system(.caption, design: .monospaced))
diff --git a/CodexBarTests/TaskGlowPreviewTests.swift b/CodexBarTests/TaskGlowPreviewTests.swift
new file mode 100644
index 0000000..0f9b935
--- /dev/null
+++ b/CodexBarTests/TaskGlowPreviewTests.swift
@@ -0,0 +1,240 @@
+import Combine
+import Foundation
+import Testing
+
+struct TaskGlowPreviewTests {
+ private let now = TestFixtures.now
+
+ @Test func previewRequestsDoNotChangePreferences() throws {
+ let preferences = try TestPreferences()
+ defer { preferences.remove() }
+ let settings = TaskGlowSettings(defaults: preferences.defaults)
+ var requests: [TaskGlowPreviewRequest] = []
+ let subscription = settings.previewRequests.sink { requests.append($0) }
+ defer { subscription.cancel() }
+ settings.previewColor(for: .waiting)
+ #expect(requests.isEmpty)
+ settings.setEnabled(true)
+ let saved = preferences.defaults.dictionaryRepresentation() as NSDictionary
+ for role in TaskGlowColorRole.allCases {
+ settings.previewColor(for: role)
+ }
+ settings.endColorPreview()
+ #expect(requests == [.enabled, .color(.running), .color(.waiting), .color(.completed), .color(.terminated), .endColorPreview])
+ #expect(preferences.defaults.dictionaryRepresentation() as NSDictionary == saved)
+ }
+
+ @Test func completionDuringPreviewGetsFullDurationAfterReturnTransition() {
+ var state = enabledState()
+ state.suspend(now: now)
+ let completion = completed(at: 2)
+ update(&state, snapshot: completion, at: 2)
+ state.refresh(now: time(60), terminalDuration: 15)
+ #expect(state.state == .completed)
+ #expect(state.isSuspended)
+ state.resume(now: time(60.4))
+ state.refresh(now: time(60), terminalDuration: 15)
+ #expect(state.terminal?.startedAt == time(60.4))
+ #expect(state.terminal?.expiresAt == time(75.4))
+ #expect(completion.latestTerminalEvent?.endedAt == time(2))
+ state.refresh(now: time(75.4), terminalDuration: 15)
+ #expect(state.state == .hidden)
+ }
+
+ @Test func interruptedCompletionKeepsOnlyRemainingTimeAcrossRepeatedPreviews() {
+ var state = enabledState(snapshot: completed(at: 0))
+ state.suspend(now: time(5))
+ state.suspend(now: time(8))
+ state.refresh(now: time(20), terminalDuration: 15)
+ state.resume(now: time(20))
+ state.refresh(now: time(20), terminalDuration: 15)
+ #expect(state.terminal?.expiresAt == time(30))
+ state.suspend(now: time(22))
+ state.resume(now: time(40))
+ state.refresh(now: time(40), terminalDuration: 15)
+ #expect(state.terminal?.expiresAt == time(48))
+ state.refresh(now: time(48), terminalDuration: 15)
+ #expect(state.state == .hidden)
+ }
+
+ @Test func previewDuringReturnTransitionDoesNotAddUnshownTime() {
+ var state = enabledState(snapshot: completed(at: 0))
+ state.suspend(now: time(5))
+ state.resume(now: time(10.4))
+ state.refresh(now: time(10), terminalDuration: 15)
+ state.suspend(now: time(10.1))
+ state.resume(now: time(20))
+ state.refresh(now: time(20), terminalDuration: 15)
+ #expect(state.terminal?.expiresAt == time(30))
+ }
+
+ @Test func expiredCompletionDoesNotReviveAfterPreview() {
+ var state = enabledState(snapshot: completed(at: 0))
+ state.refresh(now: time(20), terminalDuration: 15)
+ state.suspend(now: time(20))
+ state.resume(now: time(60))
+ state.refresh(now: time(60), terminalDuration: 15)
+ #expect(state.state == .hidden)
+ }
+
+ @Test func newTerminationDuringInterruptedReturnGetsFullTime() {
+ var state = enabledState(snapshot: completed(at: 0))
+ state.suspend(now: time(5))
+ state.resume(now: time(10.4))
+ state.refresh(now: time(10), terminalDuration: 15)
+ state.suspend(now: time(10.1))
+ let termination = CodexActivityTermination(
+ id: UUID(), isAnonymous: false, projectName: nil, modelName: nil,
+ effort: nil, terminatedAt: time(10.2), duration: 60
+ )
+ let snapshot = CodexActivitySnapshot(
+ waitingTasks: [], runningTasks: [], recentCompletions: completed(at: 0).recentCompletions,
+ recentTerminations: [termination]
+ )
+ update(&state, snapshot: snapshot, at: 10.2)
+ state.resume(now: time(20))
+ state.refresh(now: time(20), terminalDuration: 15)
+ #expect(state.state == .terminated)
+ #expect(state.terminal?.eventID == termination.id)
+ #expect(state.terminal?.expiresAt == time(35))
+ state.refresh(now: time(35), terminalDuration: 15)
+ #expect(state.state == .hidden)
+ }
+
+ @Test func onlyLatestTerminalStateSurvivesPreview() {
+ var state = enabledState()
+ state.suspend(now: now)
+ update(&state, snapshot: completed(at: 2), at: 2)
+ let latest = completed(at: 5)
+ update(&state, snapshot: latest, at: 5)
+ state.resume(now: time(20))
+ state.refresh(now: time(20), terminalDuration: 15)
+ #expect(state.terminal?.eventID == latest.latestTerminalEvent?.id)
+ #expect(state.terminal?.expiresAt == time(35))
+ state.refresh(now: time(35), terminalDuration: 15)
+ #expect(state.state == .hidden)
+ }
+
+ @Test func latestWaitingTaskReplacesCompletionDuringPreview() {
+ var state = enabledState()
+ state.suspend(now: now)
+ update(&state, snapshot: completed(at: 2), at: 2)
+ update(&state, snapshot: active(waiting: true), at: 3)
+ state.resume(now: time(20))
+ state.refresh(now: time(20), terminalDuration: 15)
+ #expect(state.state == .waiting)
+ #expect(state.terminal == nil)
+ }
+
+ @Test func concurrentBriefCompletionGetsFullTimeAfterPreview() throws {
+ var state = enabledState(snapshot: active())
+ state.suspend(now: time(1))
+ let event = try #require(completed(at: 2).latestTerminalEvent)
+ state.update(snapshot: active(), terminalEvents: [event], isEnabled: true, acceptsBriefEvents: true, now: time(2))
+ state.refresh(now: time(20), terminalDuration: 15)
+ state.resume(now: time(20))
+ state.refresh(now: time(20), terminalDuration: 15)
+ #expect(state.state == .completed)
+ #expect(state.terminal?.expiresAt == time(23))
+ state.refresh(now: time(23), terminalDuration: 15)
+ #expect(state.state == .running)
+ }
+
+ @Test func interruptedBriefCompletionResumesRemainingTime() throws {
+ var state = enabledState(snapshot: active())
+ let event = try #require(completed(at: 1).latestTerminalEvent)
+ state.update(snapshot: active(), terminalEvents: [event], isEnabled: true, acceptsBriefEvents: true, now: time(1))
+ state.refresh(now: time(1), terminalDuration: 15)
+ state.suspend(now: time(2))
+ state.resume(now: time(20))
+ state.refresh(now: time(20), terminalDuration: 15)
+ #expect(state.terminal?.expiresAt == time(22))
+ state.refresh(now: time(22), terminalDuration: 15)
+ #expect(state.state == .running)
+ }
+
+ @Test func disablingDropsSuspensionAndSleepDoesNotExtendIt() {
+ var state = enabledState(snapshot: completed(at: 0))
+ state.suspend(now: time(5))
+ state.resume(now: time(10))
+ state.refresh(now: time(60), terminalDuration: 15)
+ #expect(state.state == .hidden)
+ state.suspend(now: time(60))
+ state.update(snapshot: .empty, terminalEvents: [], isEnabled: false, acceptsBriefEvents: false, now: time(60))
+ state.refresh(now: time(60), terminalDuration: 15)
+ #expect(!state.isSuspended)
+ #expect(state.state == .hidden)
+ }
+
+ @Test(arguments: TaskGlowColorRole.allCases)
+ func previewUsesStateAnimationAndIndependentPlaybackIdentity(_ role: TaskGlowColorRole) {
+ let playback = TaskGlowPlayback(startsAt: time(0.4), mediaStart: 100.4)
+ let preview = TaskGlowPreviewPresentation(role: role, isColorPreview: true, playback: playback, speed: .standard)
+ let next = TaskGlowPreviewPresentation(
+ role: role, isColorPreview: true,
+ playback: TaskGlowPlayback(startsAt: time(1), mediaStart: 101), speed: .standard
+ )
+ #expect(preview.playback.id != next.playback.id)
+ switch role {
+ case .running:
+ #expect(preview.state == .running)
+ #expect(preview.expiresAt == time(3.1))
+ case .waiting:
+ #expect(preview.state == .waiting)
+ #expect(preview.expiresAt == time(3.75))
+ case .completed, .terminated:
+ #expect(preview.state == (role == .completed ? .completed : .terminated))
+ #expect(preview.expiresAt == time(3.4))
+ #expect(preview.terminal?.startedAt == time(0.4))
+ #expect(preview.terminal?.eventID == playback.id)
+ }
+ }
+
+ @Test(arguments: [TaskGlowColorRole.running, .waiting])
+ func changingSpeedPreservesCycleProgress(_ role: TaskGlowColorRole) {
+ var preview = TaskGlowPreviewPresentation(
+ role: role, isColorPreview: true,
+ playback: TaskGlowPlayback(startsAt: now, mediaStart: 100), speed: .standard
+ )
+ let entrance = role == .waiting ? TaskGlowAnimationTiming.expansionDuration : 0
+ let duration = preview.expiresAt.timeIntervalSince(now) - entrance
+ let halfway = time(entrance + duration / 2)
+ preview.setAnimationSpeed(.slow, now: halfway)
+ #expect(abs(preview.expiresAt.timeIntervalSince(halfway) - duration * 0.75) < 0.00001)
+ #expect(abs(preview.playback.mediaStart - 100 - preview.playback.startsAt.timeIntervalSince(now)) < 0.00001)
+ }
+
+ private func enabledState(snapshot: CodexActivitySnapshot = .empty) -> TaskGlowPresentationState {
+ var state = TaskGlowPresentationState()
+ update(&state, snapshot: snapshot, at: 0)
+ state.refresh(now: now, terminalDuration: 15)
+ return state
+ }
+
+ private func update(_ state: inout TaskGlowPresentationState, snapshot: CodexActivitySnapshot, at seconds: TimeInterval) {
+ state.update(snapshot: snapshot, terminalEvents: [], isEnabled: true, acceptsBriefEvents: true, now: time(seconds))
+ }
+
+ private func time(_ seconds: TimeInterval) -> Date {
+ now.addingTimeInterval(seconds)
+ }
+
+ private func completed(at seconds: TimeInterval) -> CodexActivitySnapshot {
+ let completion = CodexActivityCompletion(
+ id: UUID(), isAnonymous: false, projectName: nil, modelName: nil,
+ effort: nil, completedAt: time(seconds), duration: 60
+ )
+ return CodexActivitySnapshot(waitingTasks: [], runningTasks: [], recentCompletions: [completion], recentTerminations: [])
+ }
+
+ private func active(waiting: Bool = false) -> CodexActivitySnapshot {
+ let task = CodexActivityTaskSnapshot(
+ id: UUID(), isAnonymous: false, latestEvent: .toolStarted, projectName: nil,
+ modelName: nil, effort: nil, toolName: nil, startedAt: now,
+ stateChangedAt: now, showsPreciseDuration: true, activeSubagentCount: nil
+ )
+ return CodexActivitySnapshot(
+ waitingTasks: waiting ? [task] : [], runningTasks: waiting ? [] : [task], recentCompletions: [], recentTerminations: []
+ )
+ }
+}
diff --git a/Config/Version.xcconfig b/Config/Version.xcconfig
index 788a3d1..8fff83b 100644
--- a/Config/Version.xcconfig
+++ b/Config/Version.xcconfig
@@ -1,2 +1,2 @@
-MARKETING_VERSION = 4.0.5
-CURRENT_PROJECT_VERSION = 105
+MARKETING_VERSION = 4.0.6
+CURRENT_PROJECT_VERSION = 106
diff --git a/Docs/DeveloperGuide/activity-monitor.md b/Docs/DeveloperGuide/activity-monitor.md
index a61d082..37c63d3 100644
--- a/Docs/DeveloperGuide/activity-monitor.md
+++ b/Docs/DeveloperGuide/activity-monitor.md
@@ -27,7 +27,7 @@ rollout JSONL -> CodexSessionLifecycleReader ----------------------------+
`WorkflowHookEventRecorder` 从 `stdin` 提取最小字段,按需有界回查 rollout 元数据,加锁追加事件后退出。历史聚合和实时任务分别读取同一份 Hook JSONL;app-server 额度与用量走独立链路。采集与聚合细节见 [Hook 采集与历史聚合](hook-and-aggregation.md)
-通知和触觉反馈消费 monitor 发布的实时转场。流光消费快照与终态展示事件:等待用户批准为橙色,运行中为青色,完成为绿色,终止为红色。存在等待任务时,活跃状态优先显示橙色;短暂终态提示可以覆盖活跃状态。
+通知和触觉反馈消费 monitor 发布的实时转场。流光消费快照与终态展示事件,颜色跟随流光设置:默认等待用户批准为橙色,运行中为青色,完成为绿色,终止为红色。存在等待任务时,活跃状态优先显示等待状态;短暂终态提示可以覆盖活跃状态。
### 两种来源的分工
diff --git a/Docs/DeveloperGuide/ui-and-lifecycle.md b/Docs/DeveloperGuide/ui-and-lifecycle.md
index 4d6e591..a4848ac 100644
--- a/Docs/DeveloperGuide/ui-and-lifecycle.md
+++ b/Docs/DeveloperGuide/ui-and-lifecycle.md
@@ -57,9 +57,13 @@ UI 使用 SwiftUI 声明内容,由 AppKit Controller 管理窗口。
颜色、速度、亮度和结束时长由 `TaskGlowSettings.appearance` 提供。默认运行使用青色,等待批准使用橙色,完成使用绿色,终止使用红色;结束时间相同优先终止。所有计时包含进场动画,到期后按最新快照恢复展示。
-设置从关闭切换为开启且 Hook 可用时,`TaskGlowSettings.previewRequests` 请求一次使用当前外观设置的运行预览,完成一个往返周期后恢复实际状态,标准速度下周期为 2.7 秒。启动和设置刷新只恢复开关值,不触发预览。预览覆盖期间继续接收真实任务更新,不产生任务事件。
+设置从关闭切换为开启且 Hook 可用时,`TaskGlowSettings.previewRequests` 请求一次使用当前外观设置的运行预览,完成一个往返周期后恢复实际状态,标准速度下周期为 2.7 秒。启动和设置刷新只恢复开关值,不触发预览。
-播放和收尾期间忽略新的预览请求。关闭开关通过光带已有的退场流程快速收回到中心并淡出;所有屏幕实际收尾完成后释放预览占用。Hook 不可用、系统睡眠、屏幕休眠或会话不活跃时取消预览。
+双击设置面板中的颜色块请求对应状态的预览:运行播放一个往返周期,等待批准展开后播放两次呼吸,完成和终止显示 3 秒,最后 0.5 秒淡出。颜色预览可以替换正在播放的预览;收起设置子面板只结束颜色预览。开启预览在已有预览或窗口收尾期间忽略重复请求。
+
+预览覆盖期间继续接收真实任务更新,不产生任务事件。真实结束提示暂停计时,恢复时按最新快照展示:已有提示继续剩余时长,暂停期间产生的提示保留完整时长。预览切换时各屏幕共用开始时刻,旧光带收回时间不占用目标效果的展示时长。
+
+关闭开关取消预览,光带快速收回到中心并淡出,所有屏幕实际收尾完成后移除窗口。Hook 不可用、系统睡眠、屏幕休眠或会话不活跃时取消预览;睡眠期间真实结束提示按墙上时间到期。
光带使用不激活、穿透鼠标的 `NSPanel`,跨 Space 和全屏显示。系统睡眠、屏幕休眠或用户会话不活跃时移除窗口,恢复后按当前时间接续有效状态。屏幕配置变化时重建窗口,各显示器共享运动时钟。运动时钟根据分段时长和速度计算周期,改速时保留当前进度。
@@ -307,7 +311,7 @@ app-server 状态默认每 60 秒检查刷新。主面板的 0.24 秒淡入完
- 左键打开主面板,右键和 Control 点击打开上下文菜单
- 多任务运行或等待批准期间,完成和终止触发 3 秒流光提示;颜色跟随配置,全部任务结束后按所选结束时长到期
-- 开启流光按当前颜色、速度和亮度播放一次预览,关闭时收回并淡出,收尾期间不重播,收尾后可再次开启预览;预览期间任务状态变化后正确接续实际状态
+- 开启流光按当前颜色、速度和亮度播放一次预览,关闭时收回并淡出,收尾期间不重播开启预览,收尾后可再次开启预览;双击颜色块可连续替换预览,收起子面板结束颜色预览;恢复时已有结束提示继续剩余时长,预览期间产生的提示按最新状态显示并保留完整时长
- 历史重读及唤醒对账不补播旧终态短提示,恢复后的真实结束仍有提示;多显示器和屏幕配置变化后运动与到期时间一致
- 菜单栏符号随任务状态切换,最新终态在结束 10 秒后恢复空闲,跨睡眠唤醒后按当前时间显示
- 普通人物与四种任务徽章之间切换时过渡完整,快速连续切换后显示最新状态;带徽章时反复切换额度显隐仍保持流畅,首次显示和唤醒重算不播放过渡
diff --git a/Docs/UserGuide/settings.md b/Docs/UserGuide/settings.md
index 9d689d1..a39e091 100644
--- a/Docs/UserGuide/settings.md
+++ b/Docs/UserGuide/settings.md
@@ -26,7 +26,9 @@ Hook 关闭时任务区域自动关闭,从关闭切换到开启时自动显示
在各显示器顶部显示任务状态,需要 CodexBar Hook 开启且校验通过。此开关默认关闭,与主面板的“动画效果”独立。开启后,点击右侧选项按钮可调整各状态颜色、动画速度、亮度和结束时长。
-开启时按当前运行颜色、速度和亮度播放一次往返预览,随后显示实际任务状态。关闭时光带快速收回到屏幕中心并淡出。预览播放或收尾期间反复开关不会重播;收尾完成后再次开启可以重新预览。
+开启时按当前运行颜色、速度和亮度播放一次往返预览,随后显示实际任务状态。关闭时光带快速收回到屏幕中心并淡出,收尾完成前再次开启不会重播开启预览。
+
+双击选项面板中的颜色块可预览对应状态:运行播放一个往返周期,等待批准播放两次呼吸,完成和终止显示 3 秒。再次双击会替换当前预览,收起选项面板会结束颜色预览并恢复实际任务状态。
| 默认颜色 | 含义 |
| --- | --- |
@@ -37,7 +39,7 @@ Hook 关闭时任务区域自动关闭,从关闭切换到开启时自动显示
颜色使用 Display P3 六位十六进制值,字母自动转为大写,空输入框显示默认颜色值。无效颜色以红框提示,按回车、移开焦点或收起面板时恢复默认颜色。动画速度可选较慢、标准和较快,默认标准;亮度可调范围为 20%–100%,默认 100%。
-并发任务中有任务结束时,显示 3 秒的完成或终止提示,再恢复当前任务状态。全部任务结束后,从最新记录的结束时间起,按所选“结束时长”显示提示;可选 3、5、10、15、30 或 60 秒,默认 10 秒。
+并发任务中有任务结束时,显示 3 秒的完成或终止提示,再恢复当前任务状态。全部任务结束后,从最新记录的结束时间起,按所选“结束时长”显示提示;可选 3、5、10、15、30 或 60 秒,默认 10 秒。预览期间继续接收任务更新,结束提示暂停计时。恢复时按最新任务状态展示,已有结束提示继续剩余时长,预览期间产生的结束提示按完整时长显示。
Hook 不可用时隐藏光带并保留开关选择。系统睡眠、屏幕休眠或用户会话不活跃时也会隐藏;恢复后显示当前状态,已过期的结束提示不会重播。
diff --git a/Docs/en/DeveloperGuide/activity-monitor.md b/Docs/en/DeveloperGuide/activity-monitor.md
index a9c415e..626ec8b 100644
--- a/Docs/en/DeveloperGuide/activity-monitor.md
+++ b/Docs/en/DeveloperGuide/activity-monitor.md
@@ -27,7 +27,7 @@ rollout JSONL -> CodexSessionLifecycleReader ----------------------------+
`WorkflowHookEventRecorder` extracts minimal fields from `stdin`, performs bounded rollout metadata lookup when needed, appends under a file lock, and exits. Historical aggregation and live monitoring independently read the same Hook JSONL. App-server quota and usage use a separate pipeline. See [Hook Collection and Aggregation](hook-and-aggregation.md) for collection details.
-Notifications and haptics consume live transitions from the monitor. Glow consumes snapshots and terminal presentation events: orange for user approval, cyan for running, green for completion, and red for termination. Waiting takes precedence among active tasks; a short terminal indication can temporarily override active state.
+Notifications and haptics consume live transitions from the monitor. Glow consumes snapshots and terminal presentation events, using the configured colors: by default, orange for user approval, cyan for running, green for completion, and red for termination. Waiting takes precedence among active tasks; a short terminal indication can temporarily override active state.
### Division Between Sources
diff --git a/Docs/en/DeveloperGuide/ui-and-lifecycle.md b/Docs/en/DeveloperGuide/ui-and-lifecycle.md
index 2ac740e..c03956a 100644
--- a/Docs/en/DeveloperGuide/ui-and-lifecycle.md
+++ b/Docs/en/DeveloperGuide/ui-and-lifecycle.md
@@ -57,9 +57,13 @@ Shutdown reverses the order, except for helper-owned system state. AppDelegate f
`TaskGlowSettings.appearance` supplies colors, speed, brightness, and end duration. The default colors are cyan for running, orange for approval waiting, green for completion, and red for termination. Termination takes priority on equal end times. Durations include entrance animations. The latest snapshot determines the state after expiration.
-Switching the setting from off to on while Hook is available sends a `TaskGlowSettings.previewRequests` event for one running preview using the current appearance settings. After one round trip, presentation returns to the actual state; the cycle lasts 2.7 seconds at Standard speed. Startup and settings refresh restore the switch value without requesting a preview. Real task updates continue during the preview, which produces no task events.
+Switching the setting from off to on while Hook is available sends a `TaskGlowSettings.previewRequests` event for one running preview using the current appearance settings. After one round trip, presentation returns to the actual state; the cycle lasts 2.7 seconds at Standard speed. Startup and settings refresh restore the switch value without requesting a preview.
-New preview requests are ignored during playback and dismissal. Turning the switch off uses the glow's existing dismissal path to retract quickly to the center and fade out. Preview occupancy clears once every display finishes dismissal. Hook unavailability, system sleep, display sleep, or an inactive session cancels the preview.
+Double-clicking a color swatch in the settings panel requests a preview of that state: running makes one round trip, approval waiting expands and pulses twice, and completion and termination appear for 3 seconds with a fade during the final 0.5 seconds. Color previews can replace a playing preview; closing the settings child panel ends only color previews. Requests for the preview triggered by enabling the feature are ignored while a preview or window dismissal is in progress.
+
+Real task updates continue during previews, which produce no task events. Real terminal indicator timers pause, and presentation resumes from the latest snapshot: existing indicators retain their remaining time, while indicators for tasks that ended during the pause receive their full duration. Preview transitions share a start time across displays; retraction of the previous glow does not consume the target effect's display duration.
+
+Turning the switch off cancels the preview, retracts the glow quickly to the center, and fades it out. Windows are removed once every display finishes dismissal. Hook unavailability, system sleep, display sleep, or an inactive session cancels the preview; real terminal indicators expire according to wall time during sleep.
The glow uses nonactivating, mouse-transparent `NSPanel` windows across Spaces and full-screen apps. System sleep, display sleep, or an inactive user session removes the windows. On return, valid state resumes according to the current time. Screen configuration changes rebuild the windows; all displays share a motion clock. The clock calculates the cycle from segment durations and speed, preserving progress when speed changes.
@@ -306,7 +310,7 @@ Release scripts require Developer ID, signing, and notarization credentials and
## Manual Validation Matrix
- Left-click opens the main panel; right-click and Control-click open the context menu
-- Enabling Task Glow plays one preview using the current color, speed, and brightness; disabling retracts and fades it out. Dismissal blocks replay, and enabling again after dismissal can preview again. Task changes during preview resume with the actual state
+- Enabling Task Glow plays one preview using the current color, speed, and brightness; disabling retracts and fades it out. Dismissal blocks the enabling preview, and enabling again after dismissal can preview again. Repeated color-swatch double-clicks replace previews, and closing the child panel ends color previews. On return, existing terminal indicators retain their remaining time, and indicators for tasks that ended during the preview follow the latest state and receive their full duration
- During concurrent running or approval waiting, completion and termination trigger a 3-second glow indicator; colors follow the settings, and the selected end duration applies once all tasks end
- History reloads and wake reconciliation do not replay old terminal hints; subsequent real task endings still produce hints, and motion and expiry stay aligned across displays and screen configuration changes
- Menu bar symbols follow task state; terminal feedback expires 10 seconds after the task ends and is recalculated on wake
diff --git a/Docs/en/UserGuide/settings.md b/Docs/en/UserGuide/settings.md
index 3882c8c..5ec0c87 100644
--- a/Docs/en/UserGuide/settings.md
+++ b/Docs/en/UserGuide/settings.md
@@ -26,7 +26,9 @@ Disabling Hook hides Tasks; switching Hook from off to on shows Tasks automatica
Shows task status along the top of each display. CodexBar Hook must be enabled and verified. The switch is off by default and independent of the main panel's Animation Effects setting. Once enabled, click the options button to adjust status colors, animation speed, brightness, and end duration.
-Turning it on plays one round-trip preview using the current running color, speed, and brightness, then shows actual task status. Turning it off quickly retracts the glow to the screen center and fades it out. Repeated toggles during preview playback or dismissal do not replay it; turning it on after dismissal finishes can start another preview.
+Turning it on plays one round-trip preview using the current running color, speed, and brightness, then shows actual task status. Turning it off quickly retracts the glow to the screen center and fades it out. Turning it back on before dismissal finishes does not trigger another preview.
+
+Double-click a color swatch in the options panel to preview that state: running makes one round trip, approval waiting pulses twice, and completion and termination appear for 3 seconds. Double-clicking again replaces the current preview. Closing the options panel ends the color preview and restores actual task status.
| Default color | Meaning |
| --- | --- |
@@ -37,7 +39,7 @@ Turning it on plays one round-trip preview using the current running color, spee
Colors use six-digit Display P3 hexadecimal values. Letters are converted to uppercase, and empty fields show the default color as a placeholder. Invalid colors have a red border and revert to the default on Return, focus loss, or panel dismissal. Animation Speed offers Slower, Standard, and Faster, with Standard as the default. Brightness ranges from 20% to 100%, defaulting to 100%.
-When a task ends while others remain active, its completion or termination appears for 3 seconds before returning to the current task state. Once all tasks end, the latest ending is shown for the selected End Duration, measured from its end time. Choices are 3, 5, 10, 15, 30, or 60 seconds; the default is 10 seconds.
+When a task ends while others remain active, its completion or termination appears for 3 seconds before returning to the current task state. Once all tasks end, the latest ending is shown for the selected End Duration, measured from its end time. Choices are 3, 5, 10, 15, 30, or 60 seconds; the default is 10 seconds. Task updates continue during previews while terminal indicator timers pause. Presentation resumes according to the latest task state: existing terminal indicators retain their remaining time, and indicators for tasks that ended during the preview receive their full duration.
The glow is hidden while Hook is unavailable, preserving your switch preference. System sleep, display sleep, or an inactive user session also hides it. On return, it shows the current state without replaying expired terminal indicators.
diff --git a/appcast.xml b/appcast.xml
index daa66b2..688d835 100644
--- a/appcast.xml
+++ b/appcast.xml
@@ -7,6 +7,15 @@
<link>https://codexbar.zabrian.app/appcast.xml</link>
<description>CodexBar appcast feed</description>
<language>zh-CN</language>
+ <item>
+ <title>CodexBar.app 4.0.6</title>
+ <sparkle:version>106</sparkle:version>
+ <sparkle:shortVersionString>4.0.6</sparkle:shortVersionString>
+ <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+ <sparkle:releaseNotesLink>https://codexbar.zabrian.app/notes#4.0.6</sparkle:releaseNotesLink>
+ <pubDate>Sat, 26 Sep 2026 12:28:32 +0800</pubDate>
+ <enclosure url="https://codexbar.zabrian.app/download/CodexBar-v4.0.6.dmg" sparkle:edSignature="1MY2NtnI1PC+p6MIB8ulR8bwBQt/1hQrnOtqfKATjn0wOpgtxKLB5VMpoLvslK9R45gv8Z1pWB5QQofrI/kECw==" length="8389120" type="application/octet-stream"/>
+ </item>
<item>
<title>CodexBar.app 4.0.5</title>
<sparkle:version>105</sparkle:version>