Skip to content

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

fix: 提升应用状态与工作流维护可靠性

Bob6f93fcedafd3
diff --git a/CodexBar.xcodeproj/project.pbxproj b/CodexBar.xcodeproj/project.pbxproj
index 86058b8..7e28770 100644
--- a/CodexBar.xcodeproj/project.pbxproj
+++ b/CodexBar.xcodeproj/project.pbxproj
@@ -424,7 +424,7 @@
"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";
CODE_SIGN_STYLE = Automatic;
COMBINE_HIDPI_IMAGES = YES;
- CURRENT_PROJECT_VERSION = 55;
+ CURRENT_PROJECT_VERSION = 56;
DEAD_CODE_STRIPPING = YES;
DEVELOPMENT_TEAM = 4KJ362VJW5;
ENABLE_APP_INTENTS_METADATA_GENERATION = NO;
@@ -441,7 +441,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
- MARKETING_VERSION = 3.5.1;
+ MARKETING_VERSION = 3.5.2;
PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar.debug;
PRODUCT_NAME = "$(TARGET_NAME)";
REGISTER_APP_GROUPS = YES;
@@ -464,7 +464,7 @@
"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";
CODE_SIGN_STYLE = Automatic;
COMBINE_HIDPI_IMAGES = YES;
- CURRENT_PROJECT_VERSION = 55;
+ CURRENT_PROJECT_VERSION = 56;
DEAD_CODE_STRIPPING = YES;
DEVELOPMENT_TEAM = 4KJ362VJW5;
ENABLE_APP_INTENTS_METADATA_GENERATION = NO;
@@ -481,7 +481,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
- MARKETING_VERSION = 3.5.1;
+ MARKETING_VERSION = 3.5.2;
PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar;
PRODUCT_NAME = "$(TARGET_NAME)";
PROVISIONING_PROFILE_SPECIFIER = "";
diff --git a/CodexBar/Controllers/StatusItemController.swift b/CodexBar/Controllers/StatusItemController.swift
index b5a25e2..768f7bf 100644
--- a/CodexBar/Controllers/StatusItemController.swift
+++ b/CodexBar/Controllers/StatusItemController.swift
@@ -688,7 +688,14 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
}
let message = hotKeyConflictMessage(for: shortcut)
- globalHotKeySettings.restoreShortcut(registeredHotKeyShortcut, message: message)
+ guard let previousShortcut = registeredHotKeyShortcut else {
+ // 启动阶段冲突时还没有成功注册过任何快捷键
+ // 此时 restoreShortcut(nil) 会清空用户保存的配置, 只能提示冲突
+ globalHotKeySettings.setRegistrationError(message)
+ return
+ }
+
+ globalHotKeySettings.restoreShortcut(previousShortcut, message: message)
}
private func hotKeyConflictMessage(for shortcut: GlobalHotKeyShortcut) -> String {
diff --git a/CodexBar/Models/DateFormatter.swift b/CodexBar/Models/DateFormatter.swift
index 28bc05f..aa590ba 100644
--- a/CodexBar/Models/DateFormatter.swift
+++ b/CodexBar/Models/DateFormatter.swift
@@ -63,7 +63,9 @@ nonisolated enum CodexDateFormat {
try? Date(string, strategy: .iso8601)
}
- private static let localGregorianCalendar: Calendar = {
+ /// 所有日期计算共用: Codex 落盘的日期键与目录名都是公历
+ /// 系统区域日历可能是和历/佛历等, 不能用 Calendar.current
+ static let localGregorianCalendar: Calendar = {
var calendar = Calendar(identifier: .gregorian)
calendar.locale = Locale(identifier: "en_US_POSIX")
calendar.timeZone = .autoupdatingCurrent
diff --git a/CodexBar/Services/KeepAlive/KeepAliveController.swift b/CodexBar/Services/KeepAlive/KeepAliveController.swift
index eb813cd..0aa35ca 100644
--- a/CodexBar/Services/KeepAlive/KeepAliveController.swift
+++ b/CodexBar/Services/KeepAlive/KeepAliveController.swift
@@ -12,7 +12,17 @@ final class KeepAliveController: ObservableObject {
@Published private(set) var helperStatus = HelperStatus.notRegistered
@Published private(set) var isPreventingSleep = false
@Published private(set) var hasReachedMaximumDuration = false
- @Published private(set) var errorMessage: String?
+
+ /// helper 安装与注册状态的错误, 注册恢复正常时才清除
+ @Published private var registrationErrorMessage: String?
+ /// 切换休眠状态过程中的错误, 只能由下一次操作结果或用户动作覆盖
+ /// 与注册类错误分开存储: refreshHelperStatus 每次 App 激活都会跑, 不能抹掉操作结果
+ @Published private var operationErrorMessage: String?
+
+ /// 注册不成功时操作类错误只是下游噪音, 优先展示注册问题
+ var errorMessage: String? {
+ registrationErrorMessage ?? operationErrorMessage
+ }
private let activityMonitor: CodexActivityMonitor
private let codexHookSettings: CodexHookSettings
@@ -28,6 +38,7 @@ final class KeepAliveController: ObservableObject {
private var requestInFlight = false
private var requestGeneration: UInt64 = 0
private var retryTask: Task<Void, Never>?
+ private var retryAttempt = 0
private var maximumDurationTask: Task<Void, Never>?
private var maximumDurationStartedAt: Date?
private var helperRegistrationTask: Task<Void, Never>?
@@ -54,13 +65,12 @@ final class KeepAliveController: ObservableObject {
}
isStarted = true
+ // Hook 是本功能的依赖, 不是用户意图
+ // 只重新求值当前该不该阻止休眠, 绝不改写用户保存的开关
codexHookSettings.$isEnabled
.removeDuplicates()
- .sink { [weak self] isHookEnabled in
- guard !isHookEnabled else {
- return
- }
- self?.setEnabled(false)
+ .sink { [weak self] _ in
+ self?.reconcileSleepState()
}
.store(in: &cancellables)
@@ -120,7 +130,8 @@ final class KeepAliveController: ObservableObject {
isEnabled = enabled
defaults.set(enabled, forKey: Self.enabledKey)
- errorMessage = nil
+ registrationErrorMessage = nil
+ operationErrorMessage = nil
if enabled {
ensureHelperRegistration(opensSystemSettings: true)
@@ -205,7 +216,7 @@ final class KeepAliveController: ObservableObject {
return
case .notRegistered, .notFound:
guard Self.helperAssetsArePresent else {
- errorMessage = "服务异常, 请重新安装 CodexBar"
+ registrationErrorMessage = "服务异常, 请重新安装 CodexBar"
return
}
}
@@ -215,7 +226,7 @@ final class KeepAliveController: ObservableObject {
} catch {
refreshHelperStatus()
if !helperStatus.isRegisteredOrAwaitingApproval {
- errorMessage = "注册服务失败: \(error.localizedDescription)"
+ registrationErrorMessage = "注册服务失败: \(error.localizedDescription)"
}
}
@@ -235,7 +246,9 @@ final class KeepAliveController: ObservableObject {
isRefreshingHelper = true
cancelRetryTask()
invalidateConnection()
- errorMessage = nil
+ // 连接已失效, 重试也取消了, 之前的操作类错误已经过期
+ registrationErrorMessage = nil
+ operationErrorMessage = nil
let service = Self.helperService
helperRegistrationTask = Task { @MainActor [weak self] in
@@ -263,7 +276,7 @@ final class KeepAliveController: ObservableObject {
if helperStatus.isRegisteredOrAwaitingApproval {
recordHelperRegistrationIfCurrent()
} else if let registrationError {
- errorMessage = "更新服务失败: \(registrationError.localizedDescription)"
+ registrationErrorMessage = "更新服务失败: \(registrationError.localizedDescription)"
}
isRefreshingHelper = false
@@ -302,7 +315,9 @@ final class KeepAliveController: ObservableObject {
private func refreshHelperStatus() {
helperStatus = HelperStatus(Self.helperService.status)
if helperStatus == .enabled {
- errorMessage = nil
+ // 注册已正常, 只撤回注册类抱怨
+ // 操作类结果 (例如重试耗尽) 必须留到下一次操作有结论为止
+ registrationErrorMessage = nil
} else if helperStatus != .requiresApproval {
_ = systemSleepService.endPreventingIdleSleep()
isPreventingSleep = false
@@ -337,7 +352,7 @@ final class KeepAliveController: ObservableObject {
if disabled {
let result = systemSleepService.beginPreventingIdleSleep()
guard result == kIOReturnSuccess else {
- errorMessage = "阻止空闲休眠失败 (\(result))"
+ operationErrorMessage = "阻止空闲休眠失败 (\(result))"
scheduleRetryIfNeeded(for: true)
return
}
@@ -374,14 +389,14 @@ final class KeepAliveController: ObservableObject {
_ = self.systemSleepService.endPreventingIdleSleep()
}
self.invalidateConnection()
- self.errorMessage = "切换休眠状态失败 (\(exitCode))"
+ self.operationErrorMessage = "切换休眠状态失败 (\(exitCode))"
self.scheduleRetryIfNeeded(for: disabled)
return
}
self.cancelRetryTask()
self.isPreventingSleep = disabled
- self.errorMessage = nil
+ self.operationErrorMessage = nil
if disabled {
self.beginMaximumDurationCountdownIfNeeded()
} else {
@@ -444,7 +459,7 @@ final class KeepAliveController: ObservableObject {
private func finishSleepRestore(sleepDisabledAfterOperation: Bool) {
let idleSleepResult = systemSleepService.endPreventingIdleSleep()
if idleSleepResult != kIOReturnSuccess {
- errorMessage = "恢复空闲休眠策略失败 (\(idleSleepResult))"
+ operationErrorMessage = "恢复空闲休眠策略失败 (\(idleSleepResult))"
}
let shouldRequestSystemSleep = !sleepDisabledAfterOperation
@@ -456,7 +471,7 @@ final class KeepAliveController: ObservableObject {
let result = SystemSleepService.requestSystemSleep()
if result != kIOReturnSuccess {
- errorMessage = "请求系统休眠失败 (\(result))"
+ operationErrorMessage = "请求系统休眠失败 (\(result))"
}
}
@@ -513,7 +528,7 @@ final class KeepAliveController: ObservableObject {
let shouldRetry = requestInFlight || isPreventingSleep
let desiredSleepDisabled = shouldDisableSleep
invalidateConnection()
- errorMessage = "连接服务失败: \(error.localizedDescription)"
+ operationErrorMessage = "连接服务失败: \(error.localizedDescription)"
if shouldRetry {
scheduleRetryIfNeeded(for: desiredSleepDisabled)
}
@@ -534,6 +549,8 @@ final class KeepAliveController: ObservableObject {
private func cancelRetryTask() {
retryTask?.cancel()
retryTask = nil
+ // 成功或任务结束都会走到这里, 重试预算随之重置
+ retryAttempt = 0
}
private func cancelHelperRegistrationTask() {
@@ -550,8 +567,18 @@ final class KeepAliveController: ObservableObject {
return
}
+ // 每次重试都会重建特权连接并以 root 拉起 pmset
+ // 固定 2 秒无上限重试会让持续失败的 helper 变成无限循环
+ guard retryAttempt < Self.sleepToggleRetryDelays.count else {
+ operationErrorMessage = "阻止休眠多次失败, 已停止重试"
+ return
+ }
+
+ let delay = Self.sleepToggleRetryDelays[retryAttempt]
+ retryAttempt += 1
+
retryTask = Task { @MainActor [weak self] in
- try? await Task.sleep(for: .seconds(2))
+ try? await Task.sleep(for: delay)
guard !Task.isCancelled, let self else {
return
}
@@ -565,9 +592,12 @@ final class KeepAliveController: ObservableObject {
}
}
+ /// 用户意图 (isEnabled) 与依赖可用性在这里汇合
+ /// 依赖不满足只让效果失效, 不回写 isEnabled
private var shouldDisableSleep: Bool {
isStarted
&& isEnabled
+ && codexHookSettings.isEnabled
&& hasRunningTasks
&& helperStatus == .enabled
&& !isRefreshingHelper
@@ -585,6 +615,19 @@ final class KeepAliveController: ObservableObject {
]
private static let operationNotPermittedErrorCode = 1
+ /// 切换休眠状态失败后的重试节奏, 逐次翻倍
+ /// 列表耗尽 (累计约 8.5 分钟) 即放弃: 瞬时抖动能自愈, 权限类故障不会无限重试
+ private static let sleepToggleRetryDelays: [Duration] = [
+ .seconds(2),
+ .seconds(4),
+ .seconds(8),
+ .seconds(16),
+ .seconds(32),
+ .seconds(64),
+ .seconds(128),
+ .seconds(256)
+ ]
+
private static var helperService: SMAppService {
SMAppService.daemon(plistName: CodexBarHelperIPC.daemonPlistName)
}
diff --git a/CodexBar/Services/Settings/CodexHookSettings.swift b/CodexBar/Services/Settings/CodexHookSettings.swift
index 9a5480d..f91dd70 100644
--- a/CodexBar/Services/Settings/CodexHookSettings.swift
+++ b/CodexBar/Services/Settings/CodexHookSettings.swift
@@ -6,7 +6,16 @@ import Foundation
final class CodexHookSettings: ObservableObject {
@Published private(set) var isEnabled = false
@Published private(set) var isUpdating = false
- @Published private(set) var errorMessage: String?
+
+ /// 读取 hooks.json 失败, 由 refresh() 独立维护
+ @Published private var readErrorMessage: String?
+ /// 开关操作与 Hook 校验的结果, 只能由下一次操作或校验覆盖
+ /// 与读取类错误分开存储: refresh() 每 60 秒被调用一次, 不能抹掉校验告警
+ @Published private var operationErrorMessage: String?
+
+ var errorMessage: String? {
+ operationErrorMessage ?? readErrorMessage
+ }
private let hooksURL: URL
private let fileManager: FileManager
@@ -35,10 +44,12 @@ final class CodexHookSettings: ObservableObject {
in: config,
executablePath: currentExecutablePath
)
- errorMessage = nil
+ readErrorMessage = nil
} catch {
- isEnabled = false
- errorMessage = "读取 Codex Hook 配置失败: \(error.localizedDescription)"
+ // 只有 I/O 失败和 JSON 格式错误会走到这里, 它们对「Hook 装没装」不提供信息
+ // 文件不存在或配置里没有 CodexBar 都由 readConfigIfPresent 正常返回
+ // 因此保留上次已知值, 不能把读取失败当成用户关闭了 Hook
+ readErrorMessage = "读取 Codex Hook 配置失败: \(error.localizedDescription)"
}
}
@@ -91,7 +102,7 @@ final class CodexHookSettings: ObservableObject {
do {
try await validateInstalledHooksWithAppServer()
try ensureCurrentUpdate(generation)
- errorMessage = nil
+ operationErrorMessage = nil
} catch is CancellationError {
return
} catch let error as HookConfigError {
@@ -99,13 +110,13 @@ final class CodexHookSettings: ObservableObject {
return
}
- errorMessage = error.localizedDescription
+ operationErrorMessage = error.localizedDescription
} catch {
guard isCurrentUpdate(generation) else {
return
}
- errorMessage = "无法验证 Codex Hook: \(error.localizedDescription)"
+ operationErrorMessage = "无法验证 Codex Hook: \(error.localizedDescription)"
}
}
@@ -119,7 +130,7 @@ final class CodexHookSettings: ObservableObject {
if showProgress {
isUpdating = true
- errorMessage = nil
+ operationErrorMessage = nil
}
updateTask = Task { [weak self] in
@@ -163,10 +174,10 @@ final class CodexHookSettings: ObservableObject {
if let hookError = error as? HookConfigError,
hookError.isPreflightFailure {
isEnabled = false
- errorMessage = hookError.localizedDescription
+ operationErrorMessage = hookError.localizedDescription
} else {
refresh()
- errorMessage = "设置 Codex Hook 失败: \(error.localizedDescription)"
+ operationErrorMessage = "设置 Codex Hook 失败: \(error.localizedDescription)"
}
}
}
@@ -180,7 +191,7 @@ private extension CodexHookSettings {
static let hookCommandKey = "command"
static let hookTimeoutKey = "timeout"
static let hookCommandType = "command"
- static let hookTimeout = 5
+ static let hookTimeout = WorkflowHookEventRecorder.hookTimeoutSeconds
static let configMergeStrategyReplace = "replace"
static let configMergeStrategyUpsert = "upsert"
static let hookTrustStateKeyPath = "hooks.state"
@@ -322,9 +333,9 @@ private extension CodexHookSettings {
}
if let discoveryError {
- errorMessage = "已关闭 Codex Hook, 清理信任状态失败: \(discoveryError.localizedDescription)"
+ operationErrorMessage = "已关闭 Codex Hook, 清理信任状态失败: \(discoveryError.localizedDescription)"
} else {
- errorMessage = nil
+ operationErrorMessage = nil
}
} catch is CancellationError {
return
@@ -333,7 +344,7 @@ private extension CodexHookSettings {
return
}
- errorMessage = "已关闭 Codex Hook, 清理信任状态失败: \(error.localizedDescription)"
+ operationErrorMessage = "已关闭 Codex Hook, 清理信任状态失败: \(error.localizedDescription)"
}
}
@@ -464,9 +475,11 @@ private extension CodexHookSettings {
var hooks = try hooksObject(from: config)
// 仅移除 command 同时匹配当前可执行路径与 --hook-event 的 handler
+ // 结构异常的同级条目一律跳过: 只负责移除自己的 handler, 不校验整个文件
+ // 在这里抛错会让开关既关不掉又被 refresh() 翻回打开, 用户无法从 UI 脱困
for (event, value) in hooks {
guard let groups = value as? JSONArray else {
- throw HookConfigError.invalidFormat
+ continue
}
let filteredGroups = groups.compactMap {
diff --git a/CodexBar/Services/Settings/GlobalHotKeySettings.swift b/CodexBar/Services/Settings/GlobalHotKeySettings.swift
index 2e12fa3..a642fd5 100644
--- a/CodexBar/Services/Settings/GlobalHotKeySettings.swift
+++ b/CodexBar/Services/Settings/GlobalHotKeySettings.swift
@@ -40,7 +40,9 @@ final class GlobalHotKeySettings: ObservableObject {
errorMessage = message
}
- func restoreShortcut(_ shortcut: GlobalHotKeyShortcut?, message: String) {
+ /// 参数不可为空: 传 nil 会经 saveShortcut 清空用户保存的配置
+ /// 没有可回退的快捷键时应改用 setRegistrationError
+ func restoreShortcut(_ shortcut: GlobalHotKeyShortcut, message: String) {
self.shortcut = shortcut
saveShortcut(shortcut)
errorMessage = message
diff --git a/CodexBar/Services/Updates/AppUpdater.swift b/CodexBar/Services/Updates/AppUpdater.swift
index c4a5595..5978be8 100644
--- a/CodexBar/Services/Updates/AppUpdater.swift
+++ b/CodexBar/Services/Updates/AppUpdater.swift
@@ -18,8 +18,12 @@ final class AppUpdater: NSObject, ObservableObject {
private var updaterController: SPUStandardUpdaterController?
private var clearSettingsStatusMessageTask: Task<Void, Never>?
private var isManualCheckInProgress = false
+ private var manualCheckTimeoutTask: Task<Void, Never>?
private static let missingUpdateConfigurationMessage = "未配置更新资源"
+ /// Sparkle 可能既不回调 didFindValidUpdate / didNotFindUpdate 也不回调 didAbortWithError
+ /// (后台检查已在进行, 或 feed 请求被放弃), 超时复位避免永久停留在手动检查态
+ private static let manualCheckTimeout = Duration.seconds(30)
init(bundle: Bundle = .main) {
super.init()
@@ -50,7 +54,7 @@ final class AppUpdater: NSObject, ObservableObject {
return
}
- isManualCheckInProgress = true
+ beginManualCheck()
showSettingsStatusMessage("正在检查更新")
updaterController.updater.checkForUpdateInformation()
}
@@ -80,6 +84,28 @@ final class AppUpdater: NSObject, ObservableObject {
automaticallyChecksForUpdates = updaterController?.updater.automaticallyChecksForUpdates ?? false
}
+ private func beginManualCheck() {
+ isManualCheckInProgress = true
+
+ manualCheckTimeoutTask?.cancel()
+ manualCheckTimeoutTask = Task { [weak self] in
+ try? await Task.sleep(for: Self.manualCheckTimeout)
+ guard !Task.isCancelled, let self else {
+ return
+ }
+
+ isManualCheckInProgress = false
+ manualCheckTimeoutTask = nil
+ }
+ }
+
+ /// 手动检查态只影响结果去向 (设置窗 vs 菜单面板), 复位失败会永久隐藏面板更新提示
+ private func finishManualCheck() {
+ manualCheckTimeoutTask?.cancel()
+ manualCheckTimeoutTask = nil
+ isManualCheckInProgress = false
+ }
+
private func showSettingsStatusMessage(_ message: String, autoDismissDelay: Duration? = .seconds(3)) {
clearSettingsStatusMessageTask?.cancel()
settingsStatusMessage = message
@@ -120,7 +146,7 @@ extension AppUpdater: SPUUpdaterDelegate {
panelUpdateMessage = message
}
- isManualCheckInProgress = false
+ finishManualCheck()
}
func updaterDidNotFindUpdate(_: SPUUpdater, error _: Error) {
@@ -131,7 +157,7 @@ extension AppUpdater: SPUUpdaterDelegate {
showSettingsStatusMessage("没有可用更新", autoDismissDelay: .milliseconds(1000))
}
- isManualCheckInProgress = false
+ finishManualCheck()
}
func updater(_: SPUUpdater, didAbortWithError _: Error) {
@@ -140,6 +166,6 @@ extension AppUpdater: SPUUpdaterDelegate {
}
showSettingsStatusMessage("检查更新失败")
- isManualCheckInProgress = false
+ finishManualCheck()
}
}
diff --git a/CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift b/CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift
index 6966348..c85125b 100644
--- a/CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift
+++ b/CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift
@@ -226,7 +226,9 @@ actor CodexSessionLifecycleReader {
}
private func sessionDirectory(for date: Date) -> URL {
- let components = Calendar.current.dateComponents([.year, .month, .day], from: date)
+ // Codex 的 sessions 目录名是公历, 必须固定公历日历
+ let components = CodexDateFormat.localGregorianCalendar
+ .dateComponents([.year, .month, .day], from: date)
return sessionsRootURL
.appendingPathComponent(String(format: "%04d", components.year ?? 0), isDirectory: true)
.appendingPathComponent(String(format: "%02d", components.month ?? 0), isDirectory: true)
diff --git a/CodexBar/Services/Workflow/HookEventTailReader.swift b/CodexBar/Services/Workflow/HookEventTailReader.swift
index 8c19dae..babda9a 100644
--- a/CodexBar/Services/Workflow/HookEventTailReader.swift
+++ b/CodexBar/Services/Workflow/HookEventTailReader.swift
@@ -362,8 +362,8 @@ actor HookEventTailReader {
}
private static func dateKeys(from start: Date, through end: Date) -> [String] {
- var calendar = Calendar(identifier: .gregorian)
- calendar.timeZone = .autoupdatingCurrent
+ // 产出的日期键要和 WorkflowStorage.dateKey 对齐, 必须固定公历
+ let calendar = CodexDateFormat.localGregorianCalendar
var date = calendar.startOfDay(for: start)
let endDate = calendar.startOfDay(for: end)
var keys: [String] = []
diff --git a/CodexBar/Services/Workflow/JSONLines.swift b/CodexBar/Services/Workflow/JSONLines.swift
index e09145e..55a6614 100644
--- a/CodexBar/Services/Workflow/JSONLines.swift
+++ b/CodexBar/Services/Workflow/JSONLines.swift
@@ -4,6 +4,9 @@ import Foundation
nonisolated enum JSONLines {
static let newlineByte: UInt8 = 0x0A
+ /// RFC 8259 允许出现在值前后的空白, 用于识别只含空白的空行
+ private static let jsonWhitespaceBytes: Set<UInt8> = [0x20, 0x09, 0x0A, 0x0D]
+
/// 落盘 JSON 统一的稳定输出配置, 保证文件可 diff 且格式一致
/// 配置后不再修改, encode 可重入, 可跨并发域缓存共享
static let stableEncoder: JSONEncoder = {
@@ -23,7 +26,7 @@ nonisolated enum JSONLines {
return firstCompleteIndex < data.endIndex ? Data(data[firstCompleteIndex...]) : Data()
}
- /// 按行解码 JSONL: 切分换行, trim, 跳过空行与解码失败的行
+ /// 按行解码 JSONL: 切分换行, 跳过空行与解码失败的行
static func decode<T: Decodable>(_ type: T.Type = T.self, from data: Data) -> [T] {
decodeWithFailures(type, from: data).values
}
@@ -32,29 +35,26 @@ nonisolated enum JSONLines {
_: T.Type = T.self,
from data: Data
) -> JSONLinesDecodeResult<T> {
- guard let text = String(bytes: data, encoding: .utf8) else {
- return JSONLinesDecodeResult(values: [], failedLineCount: data.isEmpty ? 0 : 1)
- }
-
let decoder = JSONDecoder()
+ var values = [T]()
var failedLineCount = 0
- let values = text
- .split(whereSeparator: \.isNewline)
- .compactMap { line -> T? in
- let trimmedLine = line.trimmingCharacters(in: .whitespacesAndNewlines)
- guard !trimmedLine.isEmpty, let lineData = trimmedLine.data(using: .utf8) else {
- return nil
- }
-
- if let value = try? decoder.decode(T.self, from: lineData) {
- return value
- }
-
+ // 逐行独立解码: 进程被杀或断电会留下截断的多字节序列
+ // 整块处理时一处损坏会连带丢掉同一次读取里的所有完好事件, 且调用方仍会推进 offset
+ // 直接把字节切片交给 JSONDecoder: 它自己跳过首尾空白并拒收非法 UTF-8,
+ // 省掉每行 String 转换 + trim + 再编码回 Data 的三次拷贝 (单次读取可达上万行)
+ for line in data.split(separator: newlineByte) {
+ guard line.contains(where: { !Self.jsonWhitespaceBytes.contains($0) }) else {
+ continue
+ }
+ guard let value = try? decoder.decode(T.self, from: Data(line)) else {
failedLineCount += 1
- return nil
+ continue
}
+ values.append(value)
+ }
+
return JSONLinesDecodeResult(values: values, failedLineCount: failedLineCount)
}
}
diff --git a/CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift b/CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift
index f868abf..b92fb11 100644
--- a/CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift
+++ b/CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift
@@ -5,6 +5,13 @@ import Foundation
nonisolated enum WorkflowHookEventRecorder {
static let hookArgument = "--hook-event"
+ /// 写进 hooks.json 的 handler 超时, 超时后 Codex 会杀掉本子进程
+ /// 定义在这里而不是 CodexHookSettings: 需要据此推算下面的等锁预算, 两者必须一起改
+ static let hookTimeoutSeconds = 5
+
+ /// 留出余量在被 Codex 杀掉之前主动收工: 被杀可能发生在写入中途并留下半截坏行
+ private static let lockWaitLimitSeconds = Double(hookTimeoutSeconds) - 2
+
static func handleIfRequested() -> Bool {
guard CommandLine.arguments.contains(hookArgument) else {
return false
@@ -72,7 +79,7 @@ nonisolated enum WorkflowHookEventRecorder {
}
private static func recordWorkflowTransaction(event: WorkflowHookEvent) throws {
- try WorkflowStorage.withExclusiveLock {
+ try WorkflowStorage.withExclusiveLock(waitLimitSeconds: lockWaitLimitSeconds) {
let dateKey = WorkflowStorage.dateKey(for: event.timestamp)
let eventLogURL = WorkflowStorage.eventLogURL(for: dateKey)
var maintenanceState = WorkflowStorage.loadMaintenanceState()
@@ -82,7 +89,6 @@ nonisolated enum WorkflowHookEventRecorder {
if let existingStat {
let day = maintenanceState.days[dateKey]
let identifierChanged = day?.fileIdentifier != nil
- && existingStat.identifier != nil
&& day?.fileIdentifier != existingStat.identifier
let fileShrank = day.map { existingStat.size < $0.offset } ?? false
diff --git a/CodexBar/Services/Workflow/WorkflowService.swift b/CodexBar/Services/Workflow/WorkflowService.swift
index d96565a..cbbce2b 100644
--- a/CodexBar/Services/Workflow/WorkflowService.swift
+++ b/CodexBar/Services/Workflow/WorkflowService.swift
@@ -67,16 +67,36 @@ actor WorkflowService {
throw WorkflowDataRebuildError.sourceUnavailable
}
+ // 单日失败不中止整批: 失败的日期已被 rebuildLocalData 标脏, 常规维护会自动重建
+ // 中止会让「前几天已改写、后几天没碰」这个事实完全不被上报
var rebuildResults = [WorkflowMaintenanceResult]()
- do {
- for dateKey in normalizedDateKeys {
+ var failedDateKeys = [String]()
+ var firstFailure: Error?
+ for dateKey in normalizedDateKeys {
+ do {
try rebuildResults.append(rebuildLocalData(for: dateKey))
+ } catch {
+ failedDateKeys.append(dateKey)
+ if firstFailure == nil {
+ firstFailure = error
+ }
}
+ }
+
+ // 成功与失败的日期都要登记: 失败的日期稍后会被自动重建并推进 sourceGeneration,
+ // 届时会上传到新的 record ID, 不清理旧记录会在云端留下同日重复的贡献
+ // 全部失败时同样要登记, 它们一样已被标脏
+ var didFailReplacementMarking = false
+ do {
+ try await syncService.markReplacementNeeded(for: normalizedDateKeys)
} catch {
- try? await syncService.markReplacementNeeded(for: rebuildResults.map(\.dateKey))
- throw error
+ didFailReplacementMarking = true
+ }
+
+ // 一天都没成功才算整体失败, 并保留首个真实原因而非笼统报「数据发生变化」
+ guard !rebuildResults.isEmpty else {
+ throw firstFailure ?? WorkflowDataRebuildError.sourceUnavailable
}
- try await syncService.markReplacementNeeded(for: normalizedDateKeys)
let snapshot = await makeSnapshot(
localAggregates: loadDailyAggregates() ?? [],
@@ -86,7 +106,9 @@ actor WorkflowService {
rebuiltDateCount: rebuildResults.count,
eventCount: rebuildResults.reduce(0) { $0 + $1.aggregate.eventCount },
corruptLineCount: rebuildResults.reduce(0) { $0 + $1.corrupt },
- isSyncReplacementPending: syncService.hasPendingReplacement(for: normalizedDateKeys)
+ isSyncReplacementPending: syncService.hasPendingReplacement(for: normalizedDateKeys),
+ failedDateKeys: failedDateKeys,
+ didFailSyncReplacementMarking: didFailReplacementMarking
)
return WorkflowDataRebuildOutcome(snapshot: snapshot, summary: summary)
}
@@ -277,13 +299,16 @@ actor WorkflowService {
}
let identifierChanged = day.fileIdentifier != nil
- && stat.identifier != nil
&& day.fileIdentifier != stat.identifier
- let boundaryChanged = day.boundaryHash.map {
- (try? eventLogBoundaryHash(for: dateKey, endingAt: day.offset)) != $0
- } ?? false
+ let boundary = boundaryStatus(dateKey: dateKey, day: day, stat: stat)
+ if let verifiedAt = boundary.verifiedAtNanoseconds {
+ changed = state.recordBoundaryVerification(
+ for: dateKey,
+ at: verifiedAt
+ ) || changed
+ }
- if identifierChanged || stat.size < day.offset || boundaryChanged {
+ if identifierChanged || stat.size < day.offset || boundary.isChanged {
state.startNewSourceGeneration(
for: dateKey,
isFresh: stat.size == 0,
@@ -304,6 +329,35 @@ actor WorkflowService {
return changed
}
+ /// boundaryHash 覆盖的是 [offset-4KB, offset), 而追加只写在 offset 之后,
+ /// 所以文件没被写过时那段字节不可能变化, 无需重算哈希.
+ /// 保留期内可能有上百个历史文件, 每轮全量重算会显著拉长持锁时间,
+ /// 而 Hook 子进程要等这把锁才能记录事件.
+ /// 返回边界是否变化, 以及重算确认无变化时应记下的 mtime (无需记录时为 nil)
+ private func boundaryStatus(
+ dateKey: String,
+ day: WorkflowDayMaintenanceState,
+ stat: WorkflowFileStat
+ ) -> (isChanged: Bool, verifiedAtNanoseconds: Int64?) {
+ guard let recordedHash = day.boundaryHash else {
+ return (false, nil)
+ }
+
+ // mtime 是主判据: 任何写入都会推进它, identifier 与 size 作为附加保险
+ if day.boundaryVerifiedAtNanoseconds == stat.modifiedAtNanoseconds,
+ day.fileIdentifier == stat.identifier,
+ day.size == stat.size {
+ return (false, nil)
+ }
+
+ guard (try? eventLogBoundaryHash(for: dateKey, endingAt: day.offset)) == recordedHash else {
+ return (true, nil)
+ }
+
+ // 记下本次校验时的 mtime, 文件保持不动的话下一轮即可跳过
+ return (false, stat.modifiedAtNanoseconds)
+ }
+
private func makeMaintenanceTasks(
state: inout WorkflowMaintenanceState,
dailyByDate: [String: WorkflowDailyAggregate],
@@ -568,7 +622,6 @@ actor WorkflowService {
let stat = WorkflowStorage.fileStat(at: eventLogURL(for: result.dateKey))
let identifierMatches = result.fileIdentifier == nil
- || stat?.identifier == nil
|| result.fileIdentifier == stat?.identifier
let boundaryMatches = (try? eventLogBoundaryHash(
for: result.dateKey,
@@ -771,34 +824,69 @@ nonisolated enum WorkflowStorage {
.appendingPathComponent("HookEvents", isDirectory: true)
}
- static func withExclusiveLock<T>(_ work: () throws -> T) throws -> T {
+ /// waitLimitSeconds 为 nil 时无限等待, 供不在 Codex 关键路径上的主 App 使用
+ static func withExclusiveLock<T>(
+ waitLimitSeconds: Double? = nil,
+ _ work: () throws -> T
+ ) throws -> T {
try FileManager.default.createDirectory(
at: directoryURL(),
withIntermediateDirectories: true
)
- let lockURL = lockURL()
- if !FileManager.default.fileExists(atPath: lockURL.path) {
- FileManager.default.createFile(atPath: lockURL.path, contents: nil)
+ // 创建与打开必须是同一次调用: 分开做时两个进程可能各自创建,
+ // 后创建的会 unlink 掉前者正在锁的 inode, 于是双方都以为自己独占
+ let fileDescriptor = open(lockURL().path, O_RDWR | O_CREAT, 0o644)
+ guard fileDescriptor >= 0 else {
+ throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)
}
-
- let lockHandle = try FileHandle(forUpdating: lockURL)
defer {
- try? lockHandle.close()
+ close(fileDescriptor)
}
// Hook 子进程和主 App 可能同时写统计文件, 必须使用进程级排他锁
- if flock(lockHandle.fileDescriptor, LOCK_EX) != 0 {
- throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)
- }
+ try acquireExclusiveLock(fileDescriptor, waitLimitSeconds: waitLimitSeconds)
defer {
- flock(lockHandle.fileDescriptor, LOCK_UN)
+ flock(fileDescriptor, LOCK_UN)
}
return try work()
}
+ /// 有等待上限时改用非阻塞重试: Hook 子进程不能无限期占着 Codex 的一轮
+ private static func acquireExclusiveLock(
+ _ fileDescriptor: Int32,
+ waitLimitSeconds: Double?
+ ) throws {
+ guard let waitLimitSeconds else {
+ guard flock(fileDescriptor, LOCK_EX) == 0 else {
+ throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)
+ }
+ return
+ }
+
+ let clock = ContinuousClock()
+ let deadline = clock.now.advanced(by: .seconds(waitLimitSeconds))
+ var retryInterval = lockMinimumRetryIntervalMicroseconds
+ while flock(fileDescriptor, LOCK_EX | LOCK_NB) != 0 {
+ let lockErrno = errno
+ guard lockErrno == EWOULDBLOCK else {
+ throw POSIXError(POSIXErrorCode(rawValue: lockErrno) ?? .EIO)
+ }
+ guard clock.now < deadline else {
+ throw POSIXError(.ETIMEDOUT)
+ }
+ usleep(retryInterval)
+ retryInterval = min(retryInterval * 2, lockMaximumRetryIntervalMicroseconds)
+ }
+ }
+
+ /// 轮询间隔从 1ms 起翻倍: 维护流程每次持锁都只有几毫秒,
+ /// 固定长间隔会让 Hook 子进程为一次已经释放的锁白等一整个间隔
+ private static let lockMinimumRetryIntervalMicroseconds: UInt32 = 1000
+ private static let lockMaximumRetryIntervalMicroseconds: UInt32 = 20000
+
static func loadMaintenanceState() -> WorkflowMaintenanceState {
let url = maintenanceURL()
guard let data = try? Data(contentsOf: url), !data.isEmpty,
@@ -824,14 +912,20 @@ nonisolated enum WorkflowStorage {
}
/// 单次 stat 同时返回大小与 inode 标识, 文件缺失或不可读时为 nil
- static func fileStat(at url: URL) -> (size: UInt64, identifier: UInt64?)? {
- guard let attributes = try? FileManager.default.attributesOfItem(atPath: url.path) else {
+ /// 维护流程每轮要 stat 上百个事件文件, 用裸 stat(2) 而非 attributesOfItem 避免逐个构造属性字典
+ /// mtime 记整数纳秒: 落盘状态用 JSON 编码, Date 会退化成浮点而无法精确比较
+ /// 沿用 attributesOfItem 的语义跟随符号链接, 因此用 stat 而非 lstat
+ static func fileStat(at url: URL) -> WorkflowFileStat? {
+ var info = Darwin.stat()
+ guard stat(url.path, &info) == 0 else {
return nil
}
- return (
- size: (attributes[.size] as? NSNumber)?.uint64Value ?? 0,
- identifier: (attributes[.systemFileNumber] as? NSNumber)?.uint64Value
+ return WorkflowFileStat(
+ size: UInt64(clamping: info.st_size),
+ identifier: UInt64(info.st_ino),
+ modifiedAtNanoseconds: Int64(info.st_mtimespec.tv_sec) * 1000000000
+ + Int64(info.st_mtimespec.tv_nsec)
)
}
@@ -892,6 +986,13 @@ nonisolated enum WorkflowStorage {
}
/// 记录单日事件文件已处理到的 offset, 支持后续增量维护
+/// stat(2) 里维护流程需要的三个字段
+nonisolated struct WorkflowFileStat {
+ let size: UInt64
+ let identifier: UInt64
+ let modifiedAtNanoseconds: Int64
+}
+
nonisolated struct WorkflowDayMaintenanceState: Codable, Equatable {
var offset: UInt64
var size: UInt64
@@ -900,6 +1001,8 @@ nonisolated struct WorkflowDayMaintenanceState: Codable, Equatable {
var sourceIsFresh: Bool
var fileIdentifier: UInt64?
var boundaryHash: String?
+ /// 上次校验 boundaryHash 时文件的 mtime; 未变即可跳过重算
+ var boundaryVerifiedAtNanoseconds: Int64?
init(
offset: UInt64 = 0,
@@ -908,7 +1011,8 @@ nonisolated struct WorkflowDayMaintenanceState: Codable, Equatable {
sourceGeneration: String? = nil,
sourceIsFresh: Bool = false,
fileIdentifier: UInt64? = nil,
- boundaryHash: String? = nil
+ boundaryHash: String? = nil,
+ boundaryVerifiedAtNanoseconds: Int64? = nil
) {
self.offset = offset
self.size = size
@@ -917,6 +1021,7 @@ nonisolated struct WorkflowDayMaintenanceState: Codable, Equatable {
self.sourceIsFresh = sourceIsFresh
self.fileIdentifier = fileIdentifier
self.boundaryHash = boundaryHash
+ self.boundaryVerifiedAtNanoseconds = boundaryVerifiedAtNanoseconds
}
init(from decoder: Decoder) throws {
@@ -928,6 +1033,10 @@ nonisolated struct WorkflowDayMaintenanceState: Codable, Equatable {
sourceIsFresh = try container.decodeIfPresent(Bool.self, forKey: .sourceIsFresh) ?? false
fileIdentifier = try container.decodeIfPresent(UInt64.self, forKey: .fileIdentifier)
boundaryHash = try container.decodeIfPresent(String.self, forKey: .boundaryHash)
+ boundaryVerifiedAtNanoseconds = try container.decodeIfPresent(
+ Int64.self,
+ forKey: .boundaryVerifiedAtNanoseconds
+ )
}
}
@@ -1030,6 +1139,18 @@ nonisolated struct WorkflowMaintenanceState: Codable, Equatable {
return changed
}
+ /// 记下 boundaryHash 重算通过时文件的 mtime, 供下一轮跳过重算
+ @discardableResult
+ mutating func recordBoundaryVerification(for dateKey: String, at nanoseconds: Int64) -> Bool {
+ guard var day = days[dateKey], day.boundaryVerifiedAtNanoseconds != nanoseconds else {
+ return false
+ }
+
+ day.boundaryVerifiedAtNanoseconds = nanoseconds
+ days[dateKey] = day
+ return true
+ }
+
mutating func startNewSourceGeneration(
for dateKey: String,
isFresh: Bool,
@@ -1108,6 +1229,9 @@ nonisolated struct WorkflowDataRebuildSummary: Equatable, Sendable {
let eventCount: Int
let corruptLineCount: Int
let isSyncReplacementPending: Bool
+ /// 未完成的日期, 已标脏并会由常规维护自动重建
+ let failedDateKeys: [String]
+ let didFailSyncReplacementMarking: Bool
}
private nonisolated struct WorkflowDataRebuildOutcome {
diff --git a/CodexBar/Views/Settings/AppSettingsView.swift b/CodexBar/Views/Settings/AppSettingsView.swift
index 3b42827..25bba0d 100644
--- a/CodexBar/Views/Settings/AppSettingsView.swift
+++ b/CodexBar/Views/Settings/AppSettingsView.swift
@@ -666,15 +666,20 @@ private extension AppSettingsView {
switch result {
case let .success(summary):
- var message = "共处理 \(summary.rebuiltDateCount) 天, 包含 \(summary.eventCount) 条数据"
- if summary.corruptLineCount > 0 {
- message += ", 跳过 \(summary.corruptLineCount) 条无效数据"
- }
- if summary.isSyncReplacementPending {
- message += "; 云端替换将在同步可用后继续"
- }
- rebuildStatus = RebuildStatus(message: message, isError: false)
+ rebuildStatus = RebuildStatus(
+ message: Self.rebuildSuccessMessage(
+ for: summary,
+ autoRetryAvailable: codexHookSettings.isEnabled
+ ),
+ isError: false
+ )
case let .failure(error):
+ // 请求被后续请求顶替时工作本身并没有失败, 不该报错
+ guard !(error is CancellationError) else {
+ clearRebuildStatus()
+ return
+ }
+
rebuildStatus = RebuildStatus(
message: "重建失败: \(error.localizedDescription)",
isError: true
@@ -683,6 +688,38 @@ private extension AppSettingsView {
}
}
+ static let rebuildFailedDateListLimit = 3
+
+ /// 未完成的日期只列前几个, 避免长范围重建时提示挤满整行
+ /// autoRetryAvailable: 常规维护只在 Hook 开启时运行, 关闭时不能承诺自动重试
+ static func rebuildSuccessMessage(
+ for summary: WorkflowDataRebuildSummary,
+ autoRetryAvailable: Bool
+ ) -> String {
+ var message = "已重建 \(summary.rebuiltDateCount) 天, 包含 \(summary.eventCount) 条数据"
+ if summary.corruptLineCount > 0 {
+ message += ", 跳过 \(summary.corruptLineCount) 条无效数据"
+ }
+
+ if !summary.failedDateKeys.isEmpty {
+ let listed = summary.failedDateKeys.prefix(rebuildFailedDateListLimit)
+ var dates = listed.joined(separator: ", ")
+ if summary.failedDateKeys.count > listed.count {
+ dates += " 等"
+ }
+ message += "; \(summary.failedDateKeys.count) 天未完成 (\(dates))"
+ message += autoRetryAvailable ? ", 稍后会自动重试" : ", 开启 CodexBar Hook 后会自动重试"
+ }
+
+ if summary.didFailSyncReplacementMarking {
+ message += "; 云端替换未能登记, 请稍后重新重建这些日期"
+ } else if summary.isSyncReplacementPending {
+ message += "; 云端替换将在同步可用后继续"
+ }
+
+ return message
+ }
+
func clearRebuildStatus() {
rebuildStatus = nil
}
@@ -1166,9 +1203,7 @@ private struct RebuildDateRange: Equatable {
return 0
}
- var calendar = Calendar(identifier: .gregorian)
- calendar.timeZone = .autoupdatingCurrent
- guard let dayDifference = calendar.dateComponents(
+ guard let dayDifference = CodexDateFormat.localGregorianCalendar.dateComponents(
[.day],
from: startDate,
to: endDate
diff --git a/CodexBarHelper/main.swift b/CodexBarHelper/main.swift
index 734da84..b78675f 100644
--- a/CodexBarHelper/main.swift
+++ b/CodexBarHelper/main.swift
@@ -32,6 +32,14 @@ private struct SleepRestoreResult {
let restoredSleepDisabled: Bool
}
+/// 哨兵必须区分三态: 「不存在」和「读不出来」的处理方式完全相反
+/// 把读取失败折叠成 nil 会让恢复流程认为无需恢复, 使 SleepDisabled=1 永久残留
+private enum SentinelState {
+ case absent
+ case present(previouslyDisabled: Bool)
+ case unreadable(Error)
+}
+
private enum SleepRestoreTrigger: String {
case appRequest = "CodexBar 主动请求"
case connectionWatchdog = "CodexBar 连接断开"
@@ -119,7 +127,7 @@ private final class CodexBarHelperRuntime: NSObject, NSXPCListenerDelegate, Code
exit(EXIT_FAILURE)
}
- if sentinelPreviousState() != nil {
+ if sentinelNeedsRestore() {
_ = restoreSleep(trigger: .helperStartup)
}
@@ -186,7 +194,7 @@ private final class CodexBarHelperRuntime: NSObject, NSXPCListenerDelegate, Code
queue.async { [self] in
guard connections.remove(identifier) != nil,
connections.isEmpty,
- sentinelPreviousState() != nil else {
+ sentinelNeedsRestore() else {
return
}
@@ -196,7 +204,7 @@ private final class CodexBarHelperRuntime: NSObject, NSXPCListenerDelegate, Code
return
}
watchdog = nil
- guard connections.isEmpty, sentinelPreviousState() != nil else {
+ guard connections.isEmpty, sentinelNeedsRestore() else {
return
}
_ = restoreSleep(trigger: .connectionWatchdog)
@@ -211,7 +219,18 @@ private final class CodexBarHelperRuntime: NSObject, NSXPCListenerDelegate, Code
private func disableSleep() -> Int32 {
var didCreateSentinel = false
- if sentinelPreviousState() == nil {
+ switch sentinelState() {
+ case .present:
+ break
+ case let .unreadable(error):
+ // 不能用当前的 SleepDisabled 覆写损坏的记录: 当前值可能正是我们自己禁用的结果
+ // 那会把「原本允许休眠」错记成「原本已禁用」, 让后续恢复永久跳过
+ let sentinelPath = sentinelURL.path
+ helperLog.error(
+ "休眠记录损坏, 拒绝覆写: path=\(sentinelPath, privacy: .public), detail=\(error.localizedDescription, privacy: .public)"
+ )
+ return -1
+ case .absent:
let current = PmsetRunner.currentSleepDisabled()
guard current.result.exitCode == 0, let wasDisabled = current.value else {
helperLog.error(
@@ -249,8 +268,19 @@ private final class CodexBarHelperRuntime: NSObject, NSXPCListenerDelegate, Code
@discardableResult
private func restoreSleep(trigger: SleepRestoreTrigger) -> SleepRestoreResult {
- guard let previouslyDisabled = sentinelPreviousState() else {
+ let previouslyDisabled: Bool
+ switch sentinelState() {
+ case .absent:
return SleepRestoreResult(exitCode: 0, restoredSleepDisabled: true)
+ case let .present(value):
+ previouslyDisabled = value
+ case let .unreadable(error):
+ // 读不出原值时按系统默认的「允许休眠」恢复
+ // 宁可多恢复一次(pmset 幂等), 也不能把 SleepDisabled=1 永久留给用户
+ helperLog.error(
+ "读取休眠记录失败, 按允许休眠恢复: reason=\(trigger.rawValue, privacy: .public), detail=\(error.localizedDescription, privacy: .public)"
+ )
+ previouslyDisabled = false
}
let previousValue = previouslyDisabled ? 1 : 0
@@ -286,7 +316,7 @@ private final class CodexBarHelperRuntime: NSObject, NSXPCListenerDelegate, Code
guard let self,
connections.isEmpty,
watchdog == nil,
- sentinelPreviousState() != nil else {
+ sentinelNeedsRestore() else {
return
}
_ = restoreSleep(trigger: .sentinelCheck)
@@ -364,8 +394,25 @@ private final class CodexBarHelperRuntime: NSObject, NSXPCListenerDelegate, Code
}
}
- private func sentinelPreviousState() -> Bool? {
- try? readSentinelPreviousState()
+ private func sentinelState() -> SentinelState {
+ do {
+ guard let previouslyDisabled = try readSentinelPreviousState() else {
+ return .absent
+ }
+ return .present(previouslyDisabled: previouslyDisabled)
+ } catch {
+ return .unreadable(error)
+ }
+ }
+
+ /// 读取失败也必须进入恢复流程: 记录损坏时无法排除「休眠正被我们禁用着」
+ private func sentinelNeedsRestore() -> Bool {
+ switch sentinelState() {
+ case .absent:
+ false
+ case .present, .unreadable:
+ true
+ }
}
private func readSentinelPreviousState() throws -> Bool? {
diff --git a/Docs/AppServer.md b/Docs/AppServer.md
index adf2d19..56ef333 100644
--- a/Docs/AppServer.md
+++ b/Docs/AppServer.md
@@ -1,130 +1,110 @@
-# app-server 通信合约
+# Codex app-server
-本文档记录 CodexBar 与本机 Codex app-server 的连接、请求、错误处理和日志规则。`AGENTS.md` 只保留开发时必须遵守的边界,具体实现细节以本文档为准。
+CodexBar 通过本机 Codex app-server 读取账号, 额度, Token 用量和部分用户配置; 通信使用子进程标准输入输出, 每条消息占一行 JSON
-## 启动命令
+## Codex 解析
-启动命令统一是:
+CodexBar 按以下顺序选择可执行文件
-```bash
+1. `PATH` 中的全局 `codex`
+2. `/Applications/ChatGPT.app/Contents/Resources/codex`
+3. `/Applications/Codex.app/Contents/Resources/codex`
+
+菜单栏 App 的环境会补充 Homebrew, npm, `~/.local`, Volta 和系统命令目录; `HOME` 使用当前真实用户目录; Codex 配置目录优先取 `CODEX_HOME`, 否则使用 `~/.codex`
+
+启动命令固定为
+
+```text
codex app-server --listen stdio://
```
-必须通过 `CodexCLIResolver.resolveAppServerCommand()` 解析:
-
-- 优先 PATH 中的全局 `codex`。
-- 如果 PATH 中的 `codex` 等价于 APP 内置路径,当作内置 CLI,不当作全局 CLI。
-- 全局 CLI 不存在时依次检查 `/Applications/ChatGPT.app/Contents/Resources/codex` 和 `/Applications/Codex.app/Contents/Resources/codex`。
-- 两者都不存在时返回 `CodexStatusError.executableNotFound`,UI 归为「初始化失败」,日志记录具体错误。
+设置窗口会同时探测全局 Codex 和 App 内置 Codex 的版本, 并根据当前 app-server 握手结果标记实际使用来源
-不要绕过 `CodexCLIResolver` 直接启动 app-server。
+## 会话生命周期
-## 启动环境
+新会话依次执行
-启动环境由 `CodexCLIResolver.environment` 构造:
+1. 发送 `initialize`
+2. 发送 `initialized` 通知
+3. 发送 `account/read`, 确认账号已登录
-- 保留当前环境。
-- `HOME` 必须来自 `getpwuid(getuid())` 的真实用户 home。
-- 同步设置 `USER`、`LOGNAME`。
-- 合并 Homebrew、npm global、`.local`、Volta 和系统路径。
-- 确保 `TERM` 有值。
-- 不要改回 Xcode sandbox/container 的 `HOME`,否则会读不到真实 `~/.codex/auth.json`。
+连接在刷新之间复用, 最长保留 1 小时; 进程退出, 写入失败, 响应超时或响应无法解析时, 连接会关闭; 复用连接发生传输故障时, 本轮读取最多重建并重试一次
-## 首次连接
+单次请求超时为 20 秒; stdout 读取器只向上层返回完整非空行, 并按响应 `id` 过滤; stderr 持续排空, 避免子进程因管道写满而阻塞
-首次连接流程:
+关闭会话时先结束管道并请求进程退出, 必要时再强制终止
-```json
-{"method":"initialize","id":1,"params":{"clientInfo":{"name":"codex_bar","title":"Codex Bar","version":"<Bundle MARKETING_VERSION 或 1.0.0>"}}}
-{"method":"initialized"}
-{"method":"account/read","id":2,"params":{"refreshToken":false}}
-```
+## 使用的接口
-`initialized` 是无 id 请求,不等待响应;日志中记录为空响应请求,不归为通知类型。
+| 方法 | 用途 |
+| --- | --- |
+| `initialize` | 建立客户端会话并读取运行版本 |
+| `initialized` | 完成初始化通知 |
+| `account/read` | 读取账号; 可请求刷新认证 |
+| `account/rateLimits/read` | 读取额度限制, 窗口和可用重置次数 |
+| `account/usage/read` | 读取 Token 摘要和每日用量 |
+| `config/read` | 读取 Hook, 信任状态和 Codex TUI 通知配置 |
+| `config/batchWrite` | 写入 Hook 信任状态和 TUI 通知配置 |
+| `hooks/list` | 验证 Codex 实际解析出的 Hook |
-`initialize` 响应的 `userAgent` 首个 token 形如 `codex_bar/0.139.0 (...)`;取 `/` 后版本号作为当前运行版本。
+`config/batchWrite` 始终设置 `reloadUserConfig: true`, 由 Codex 重新加载用户配置
-## 后续读取
+## 刷新与缓存
-同一会话后续读取:
+UI 默认每 60 秒触发一次读取; 一次刷新按以下顺序处理
-- `account/read` 每轮复用连接时用 `refreshToken: false` 更新账户状态。
-- `account/rateLimits/read` 读取额度, 包括可选的 `rateLimitResetCredits.availableCount`。当可用重置次数大于 0 时, 主 App 会通过 `CodexResetCreditsService` 额外读取本机 Codex OAuth token, 只读请求 `https://chatgpt.com/backend-api/wham/rate-limit-reset-credits` 获取各重置机会的 `expires_at`; 这条请求不走 app-server 日志, 失败时重置次数按钮仍可显示, 但侧边详情面板只展示未知过期时间。
-- `account/usage/read` 读取 `summary.lifetimeTokens`、`summary.peakDailyTokens`、`dailyUsageBuckets`。
-- `config/read` 在开启 Codex Hook 前读取有效配置,用于判断 `[features] hooks = false` 或兼容旧名 `codex_hooks = false` 是否禁用了 Hook;关闭清理时也读取 `hooks.state` 以保留其他 Hook 的信任状态。打开设置窗口或通知选项面板时还会读取 `[tui].notifications`,缺失时按 Codex 默认开启处理,布尔值 `false` 或空事件数组按关闭处理。
-- `hooks/list` 在写入 Hook 后或设置页刷新时验证 Codex 实际识别到的 Hook,检查 `command`、`eventName`、`enabled`、`sourcePath`、`trustStatus`、`key`、`currentHash`、`warnings` 和 `errors`。
-- `config/batchWrite` 用于写回 `hooks.state` 和 `tui.notifications`:Hook 开启后把 CodexBar Hook 的 `key/currentHash` upsert 成 `trusted_hash`,关闭时移除对应 key;通知选项面板切换「Codex TUI 通知」时只 upsert `tui.notifications` 的布尔值并要求 app-server reload 用户配置,不修改顶层 `notify` 外部回调。
+1. 复用连接时重新读取账号状态
+2. 读取额度
+3. 读取 Token 用量
+4. 组装菜单面板快照
-`account/rateLimits/read` 的额度模型约定:
+额度和用量是独立的补充数据
-- `rateLimitsByLimitId` 优先于顶层 `rateLimits`; 为空时回退顶层 `rateLimits`。
-- 顶层 `rateLimits.limitId` 指向主 limit, 缺省为 `codex`。
-- `rateLimitResetCredits.availableCount` 是可用额度重置次数; 字段缺失或值不大于 0 时 UI 不显示重置次数。
-- `rateLimitResetCredits.availableCount > 0` 时, `CodexResetCreditsService` 使用真实用户 `CODEX_HOME/auth.json` 或 `HOME/.codex/auth.json` 中的 access token 请求 ChatGPT backend, 超时为 4 秒。401/403 时复用本轮认证刷新预算调用一次 `account/read(refreshToken:true)` 后重试; 其他失败静默降级。成功响应只保留 `status == "available"` 且未过期 credit 的 `expires_at`, 点击 `重置次数: N` 后在侧边详情面板中按时间升序展示 `yyyy-MM-dd HH:mm:ss` 和 `可用: N`; 相同展示时间合并数量, 单个显示 `可用: 1`。
+- 成功读取时更新当前账号的内存缓存
+- 普通业务错误时可以回退到同一账号的缓存, 并标记为陈旧数据
+- 方法不支持, 认证失败或连接故障时不使用该项缓存
+- 账号变化时清空全部补充缓存
-认证失败时,同会话最多调用一次 `account/read(refreshToken:true)` 后重试原读取。
+app-server 返回认证错误时, 本轮最多执行一次 `account/read(refreshToken: true)`; 刷新后仍未认证则进入"未登录"状态
-## 错误处理
+app-server 明确表示方法不支持后, 当前会话会记住该方法, 后续不再重复请求; 可重试的服务端业务错误在会话层重试一次
-所有走 `AppServerSession.request` 的方法,收到方法不支持错误后都记录到当前会话的 `unsupportedMethods`,本连接后续不再请求该方法。
+## 手动重置机会
-方法不支持必须是 JSON-RPC error,且 message 包含:
+`account/rateLimits/read` 返回可用重置次数且数量大于 0 时, CodexBar 会读取当前 Codex 配置目录下的 `auth.json`, 向以下只读接口查询每次机会的过期时间
```text
-Invalid request: unknown variant
+https://chatgpt.com/backend-api/wham/rate-limit-reset-credits
```
-请求有 JSON-RPC error 响应,且不是认证失败、不是方法不支持、不是传输/解析故障时,先立即重试同一个请求一次。
+请求超时为 4 秒, 只保留状态为 `available` 且尚未过期的时间; 401 或 403 时, 如果本轮尚未刷新认证, 会先通过当前 app-server 刷新一次账号认证再重试; 查询失败不影响额度和可用次数展示, 只是不提供具体过期时间
-非认证业务错误重试后仍失败时,不阻断整轮刷新,详情只进日志。
+## 配置读写
-`account/rateLimits/read` 和 `account/usage/read` 重试后仍失败时:
+CodexBar 通过 app-server 管理两类用户配置
-- 若同账号有上次成功数据,则复用旧数据并标记为 stale。
-- 没有旧数据则不展示对应区域。
-- 方法不支持不复用旧数据,对应读取结果视为空。
+- `hooks.state`: 只新增, 更新或移除当前 CodexBar Hook 对应的信任项
+- `tui.notifications`: 写入布尔值控制 Codex TUI 通知
-传输/解析故障归为需要重建连接。
+Hook 事件注册本身保存在 `${CODEX_HOME}/hooks.json`, 由 CodexBar 直接按 JSON 文件读写; 注册后再通过 `hooks/list` 验证; 详见 [Codex Hook 与工作流统计](CodexHook.md)
-## 连接生命周期
+## 交互日志
-连接细节:
+日志窗口保存本次运行期间最近 500 条记录, 包括
-- `requestTimeout` 是 20 秒。
-- `connectionMaxAge` 是 1 小时。
-- `SIGPIPE` 已被忽略,写入断管后应由 `write` 抛错并走重建。
-- 复用连接出现传输故障时只重建重试一次。
-- 全新连接初始化失败直接返回「初始化失败」,不重复完整握手。
-- 关闭会话时先停止 stdout/stderr reader 并关闭 stdin,然后对 app-server 进程执行有界退出: 先 `terminate()` 等待 1 秒,仍未退出再 `SIGKILL` 并等待 0.5 秒;被强制结束或仍未退出时写入请求日志。
+- 请求方法和请求 JSON
+- 响应 JSON
+- 传输, 解析, 业务和进程错误
+- 无响应通知
-`CodexStatusService` 是 actor,app-server 连接、补充数据缓存和重建策略都在 actor 隔离内串行访问。stdout 的 `JSONLineReader` 和 stderr 的 `PipeDrain` 共用底层 `PipeReadBuffer`,把 `FileHandle`、`DispatchSourceRead` 和 semaphore 这些非 Sendable IO 细节集中在唯一的受控边界内;读事件运行在 `CodexBar.pipe-read` 的 `.userInitiated` 队列上。
+合法 JSON 会按稳定键序规范化; 日志只保存在进程内存中, 可以在窗口内清空, 不写入工作流文件, 也不参与跨设备同步
## UI 状态
-`CodexLoadState` 只有四种:
-
-- `loading`
-- `loaded`
-- `notLoggedIn`
-- `initializationFailed`
-
-UI 只展示「未登录」和「初始化失败」两类特殊状态;具体请求错误、启动错误、超时、断连、解析失败都进入日志。
-
-## 请求日志
-
-日志状态标签:
-
-- `.pending` ->「进行」
-- `.response` ->「完成」
-- `.failure` ->「错误」
-- `.emptyResponse` ->「请求」
+服务层向 UI 归并为三类结果
-日志规则:
+- 数据可用
+- 未登录
+- 初始化失败
-- 后台请求路径写入 `RequestLogStorage.shared`,日志窗口通过 `@MainActor RequestLogStore.shared` 订阅 storage 快照。
-- 带 id 的 JSON-RPC 请求先记录为进行,响应或错误到达后回填到同一条。
-- `initialized` 这类无 id 请求记录为空响应。
-- 日志容量上限 500 条,`RequestLogEntry` 完整保存 request/detail;日志窗口列表和行内展开只渲染单行短预览,非空请求/响应标题行提供完整预览和复制,预览视图对 JSON 做格式化和高亮。
-- `AppServerSession` 生成请求时已经通过 `JSONSerialization` 使用 `.sortedKeys` 和 `.withoutEscapingSlashes` 稳定序列化;`RequestLogStorage` 直接保存同一份 request 文本,不再二次解析。
-- 响应和 JSON 错误详情进入日志时仍通过 `JSONSerialization` 使用相同选项稳定化;非 JSON 错误消息保持原样。
-- 不要把子进程 stderr 直接展示给用户。
+更具体的请求错误保留在交互日志中; 陈旧的额度或用量仍可展示, 但会降低透明度, 且不会用于额度通知判断
diff --git a/Docs/CodexHook.md b/Docs/CodexHook.md
index cce793a..553c41f 100644
--- a/Docs/CodexHook.md
+++ b/Docs/CodexHook.md
@@ -1,397 +1,153 @@
-# Codex Hook 工作流统计
+# Codex Hook 与工作流统计
-本文档记录 CodexBar 接入 Codex Hook 后的配置、存储和统计口径。`AGENTS.md` 只保留开发时必须遵守的边界,具体实现细节以本文档为准。
+CodexBar Hook 是可选功能, 用于记录本机 Codex 工作流事件; 它为实时任务, 任务中心, 任务通知, 防休眠, 每日工作流统计和跨设备同步提供数据
-## 开关行为
+## 注册与关闭
-设置页「CodexBar Hook」由 `CodexHookSettings` 管理。开启后,CodexBar 会把当前 App 的可执行文件路径写入全局配置:
+Hook 配置文件位于
```text
-~/.codex/hooks.json
+${CODEX_HOME}/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 和同事件下的其他 Hook 必须保留。
-
-CodexBar Hook 的识别条件:
-
-- `type` 是 `command`
-- `command` 必须包含当前 App 可执行文件路径生成的 shell 命令和 `--hook-event` 参数, 例如 `'<当前 CodexBar 可执行文件路径>' --hook-event`
-
-也就是说,如果用户手写的 Hook 命令同样包含当前 CodexBar 可执行文件路径和 `--hook-event` 参数,也会被当作当前 CodexBar Hook 移除;不同时包含当前路径和 `--hook-event` 的用户 Hook 会保留。
-
-检测是否已开启时,只要任意 CodexBar 事件存在当前 App 路径对应的 Hook,开关就保持开启;如果缺少部分事件,`hooks/list` 验证会在 Hook 选项下方显示 `CodexBar Hook 已不完整`。
-
-关闭时会先通过 `hooks/list` 找出 `command` 属于当前 CodexBar 且来源为全局 `hooks.json` 的 Hook key;移除 `hooks.json` 中的 Hook 后,再通过 `config/read` + `config/batchWrite` 从 `hooks.state` 删除这些 key。清理失败不恢复已经关闭的 Hook,只在 Hook 选项下方提示清理信任状态失败。
-
-开启写入成功后会复用同一条 app-server 会话调用 `hooks/list` 做有效性检查:
-
-- `command`: 必须包含 CodexBar 当前可执行文件路径生成的命令和 `--hook-event` 参数。
-- `eventName`: 必须覆盖全部 CodexBar 事件;`hooks/list` 返回值使用 `sessionStart` 这类 lower camel 名称,CodexBar 会与写入的 `SessionStart` 配置名做映射。
-- `enabled`: 必须为 `true`,否则提示 Codex 已禁用这些 Hook。
-- `sourcePath`: 必须指向全局 `~/.codex/hooks.json`。
-- `trustStatus`: `untrusted` 或 `modified` 时,仅对 `sourcePath` 指向全局 `~/.codex/hooks.json` 且 command 属于当前 CodexBar 的 Hook 读取 `key` 和 `currentHash`,通过 `config/batchWrite` upsert 到 `hooks.state` 的 `trusted_hash`,再重新 `hooks/list` 验证。
-- `warnings` / `errors`: 参与验证优先级判断;设置页只显示最高优先级问题,完整返回内容进入日志窗口。
-
-`config/read`、`hooks/list` 和 `config/batchWrite` 都通过 `AppServerSession.request` 调用,请求和响应会进入 CodexBar 日志窗口。
-
-`config/read` 请求失败时,CodexBar 不写入 `hooks.json`,调用 `refresh()` 恢复本地实际状态,并在 Hook 选项下方显示 `设置 Codex Hook 失败: <错误>`。只有请求成功且明确读到全局禁用 Hook 时,才显示 `Codex 配置已禁用 Hook`。
-
-`hooks/list`、自动信任写入或二次验证失败时,CodexBar 不回滚已经写入的 Hook。请求失败时显示 `无法验证 Codex Hook: <错误>`;请求成功但验证未通过时只显示最高优先级的一条摘要。当前优先级为: 无返回结果、Codex 返回错误、Hook 被禁用、Hook 未被信任、事件不完整、来源异常、Codex 返回警告。
-
-Hook 事件定义集中在 `CodexHookEvent`。`configName` 用于写入 `hooks.json`, `appServerName` 用于匹配 `hooks/list` 返回的 lower camel 事件名, `init(eventName:)` 用于把 events 中的 `hook_event_name` 归一化到同一组事件。
-
-## Hook 事件
-
-当前安装的事件:
+未设置 `CODEX_HOME` 时使用
```text
-SessionStart
-UserPromptSubmit
-PreToolUse
-PostToolUse
-PermissionRequest
-PreCompact
-PostCompact
-Stop
-SubagentStart
-SubagentStop
-```
-
-命令格式:
-
-```bash
-'/Applications/CodexBar.app/Contents/MacOS/CodexBar' --hook-event
+~/.codex/hooks.json
```
-Hook timeout 为 5 秒。App 启动最早阶段会调用 `WorkflowHookEventRecorder.handleIfRequested()`,只有启动参数包含 `--hook-event` 时才读取 stdin;如果识别到 Hook 输入,只记录数据并立即退出正常 App 启动流程。
-
-Hook 子进程通过 `--hook-event` 参数进入记录模式, 再通过 stdin payload 顶层 `hook_event_name` 判断事件名。
-
-## Payload 解析
-
-Hook stdin 会尝试解析为 Codex 官方 JSON 对象,只读取顶层字段。`hook_event_name` 是记录事件的必需字段;其他字段缺失时尽量兜底,不阻断记录。
-
-读取字段:
+开启 Hook 时, CodexBar 会
-- 事件: `hook_event_name`
-- 目录: `cwd`
-- 工具: `tool_name`
-- 模型: `model`
-- 推理强度来源: `transcript_path`;只在 `UserPromptSubmit` / `PermissionRequest` 时从对应 rollout 尾部最多 512 KB 查找同 turn 的 `turn_context.effort`,写为 `effort`
-- 权限模式: `permission_mode`,写入 `events/YYYY-MM-DD.jsonl` 时保存为 `permission`
-- 审批路由来源: `transcript_path`;只在 `UserPromptSubmit` / `PermissionRequest` 时从对应 rollout 尾部最多 512 KB 查找同 turn 的 `turn_context.approvals_reviewer`,写为 `approval`
-- 会话: `session_id`
-- 轮次: `turn_id`
-- 子 Agent 标识: `agent_id`,字段存在时写为 `agent`,用于本机实时配对 `SubagentStart` / `SubagentStop`
+1. 通过 app-server 确认 Codex 没有全局禁用 Hook
+2. 保留现有配置, 只移除当前 CodexBar 可执行文件的旧条目
+3. 为全部受支持事件追加独立 command handler
+4. 原子写回 `hooks.json`
+5. 通过 `hooks/list` 验证事件, 命令, 来源和启用状态
+6. 必要时通过 `config/batchWrite` 更新 `hooks.state` 中对应的信任哈希
-事件名来自 payload 顶层 `hook_event_name`。没有 `--hook-event` 参数时按普通 App 启动;有 `--hook-event` 参数但 stdin 为空、不是 JSON 或事件名缺失时吞掉本次 Hook,避免 Hook 子进程继续启动完整菜单栏 App。事件时间优先读取 payload 顶层 `timestamp`,解析后按本机时区写成 `yyyy-MM-dd HH:mm:ss.SSS`;如果 `timestamp` 缺失或无法解析,记录当前时间作为兜底。同一个事件时间也会按本机时区格式化为 `yyyy-MM-dd` 的 date key,用于选择 `events/YYYY-MM-DD.jsonl` 文件。日期和时间解析统一走 `CodexDateFormat`,其中高频的 `yyyy-MM-dd` key 由本机 Gregorian 日历组件生成和校验,不暴露可变 `DateFormatter` 实例。每行按固定顺序写入 `timestamp`、`event`、`model`、`effort`、`permission`、`approval`、`session`、`turn`、`agent`、`tool`、`cwd`;缺少对应 Hook 字段或当前 rollout 无法读取时写为 `null`。事件行缺少可选字段时仍可正常解码。
-
-事件名统计时会去掉 `_` 和 `-` 并转小写,因此 `PreToolUse`、`pre_tool_use`、`pre-tool-use` 会归为同一个事件。
-
-常用项目名称只取目录最后一层;实时活动卡片会展示该名称,完整路径不会进入 UI。
-
-## 本机存储
-
-Hook 数据目录:
+handler 命令格式为
```text
-~/Library/Application Support/CodexBar/HookEvents/
-```
-
-文件职责:
-
-- `events/YYYY-MM-DD.jsonl`: 按本机日期拆分的原始 Hook 事件日志;Hook 开启期间主 App 会以只读方式 tail 当日文件,为菜单栏、活动卡片、任务通知和触觉反馈维护统一的进程内实时状态;该读取不修改文件、不参与统计维护,统计口径不变。
-- `daily.jsonl`: 每日聚合结果,UI 优先读取它
-- `stats.lock`: 并发写入锁文件,只用于 `flock`
-- `maintenance.json`: 记录待整理日期、需要重建日期和每个日期的处理进度
-
-`maintenance.json` 当前结构:
-
-```json
-{
- "schema": 4,
- "pending": ["2026-06-21"],
- "dirty": [],
- "days": {
- "2026-06-21": {
- "offset": 102400,
- "size": 122880,
- "corrupt": 0,
- "sourceGeneration": "<uuid>",
- "sourceIsFresh": true,
- "fileIdentifier": 123456,
- "boundaryHash": "<sha256>"
- }
- }
-}
+'<CodexBar 可执行文件>' --hook-event
```
-`pending` 表示有新增事件等待整理的日期;`dirty` 表示需要从头重建 `daily.jsonl` 对应日期的日期;`offset` 是当天 events 文件已经处理到的字节位置;`size` 是上次处理完成时当天 events 文件大小;`corrupt` 是当天解析失败的 JSONL 行数。`sourceGeneration` 标识这份日期文件从空文件开始后的连续追加阶段,`sourceIsFresh` 表示该阶段是否由 CodexBar 确认从空文件开始;`fileIdentifier` 和 `boundaryHash` 只在本机用于识别文件替换、截断或原位置内容变化,不进入 CloudKit。
-
-`WorkflowStorage` 定义这些路径和保留策略。UI 读取时优先加载 `daily.jsonl`;原始事件文件不再作为 UI 临时快照回退源。
+单个 handler 超时为 5 秒
-当前统计只读取按日期拆分的 `events/YYYY-MM-DD.jsonl`;`HookEvents/events.jsonl` 不参与统计或清理。
+关闭 Hook 时, CodexBar 只删除同时匹配当前可执行路径和 `--hook-event` 的 handler, 并只清理这些 Hook 的信任项; 其他应用或用户自行配置的 Hook 保持不变
-## 实时活动状态
+## 事件范围
-`CodexActivityMonitor` 是 `@MainActor ObservableObject` 长期对象。Hook 开启时它启动 `HookEventTailReader`,关闭时停止读取并清空状态;通知与触觉开关只控制是否发送对应提醒,不控制监测器生命周期。实时状态只保存在内存,不写入新的历史文件,也不增加 CloudKit 字段或网络请求。
+CodexBar 注册以下事件
-可选的 `KeepAliveController` 复用同一份实时快照,只在 `runningTasks` 非空且尚未达到用户选择的最长防休眠期限时请求关闭系统休眠并持有 `PreventUserIdleSystemSleep` assertion。已经确认进入 `waitingApproval` 的任务不计入运行数量;自动 reviewer 仍保持 `.running`,因此不会被误当成用户等待。控制器以稳定的任务 `id` 识别首次进入运行态的新任务,并记录上一份快照的等待任务;每个新运行任务以及同一任务从等待恢复运行都会把唯一共享起点更新为当前时间,即使旧任务仍在运行或上一周期已经到期也会开始新周期。普通 Hook 活动仍按实时状态机规则更新任务的 `lastActivityAt` 和过期时间,但不会更新防休眠期限的独立起点;App 激活和设置刷新同样不会续期。最后一个运行任务离开运行态或最近运行阶段对应的期限到期后恢复任务开始前的休眠设置,再释放 assertion,让 macOS 按当前空闲计时、其他 assertion 和电源策略重新评估是否应休眠;普通合盖且恢复结果为 `SleepDisabled=0` 时还会主动请求休眠。关闭 Hook 会同步关闭并持久化防休眠选项、请求恢复系统休眠,并使设置项置灰;重新开启 Hook 不会自动重新开启防休眠。该功能不改变 Hook 事件、原始文件或聚合口径,详细边界见 [KeepAlive.md](KeepAlive.md)。
+| 事件 | 用途 |
+| --- | --- |
+| `SessionStart` | 会话开始 |
+| `UserPromptSubmit` | 新任务或新轮次开始 |
+| `PreToolUse` | 工具调用开始 |
+| `PostToolUse` | 工具调用结束 |
+| `PermissionRequest` | 权限审批请求 |
+| `PreCompact` | 上下文压缩开始 |
+| `PostCompact` | 上下文压缩结束 |
+| `Stop` | 任务完成 |
+| `SubagentStart` | 子 Agent 开始 |
+| `SubagentStop` | 子 Agent 结束 |
-`HookEventTailReader` 是独立 actor,文件 I/O 和 JSON 解码不占用 MainActor。读取分为两类批次:
+事件名解析会忽略大小写, 下划线和连字符差异
-- `bootstrap`:App 启动、当前活动事件文件被截断或替换时,按 512 KB 分块流式读取滚动 24 小时涉及的日期文件,并按事件时间过滤窗口之外的数据。每次尝试开始时清空恢复态,成功后只发布一次最终快照,整个 bootstrap 不发布活动 transition。读取前记录各文件 inode 和 size;当前文件只读到当时最后一个完整换行,后续新增字节由 live 消费。文件边界变化时最多重试三次,连续失败则再次清空恢复态并跳过当前已有字节,避免把历史事件误当 live 通知。
-- bootstrap 结束后,monitor 对由工具或权限事件恢复、但缺少起点的精确 session + turn,向 reader 发起一次定向查找:在更早日期文件中按 session + turn 查找 `UserPromptSubmit`,最多额外读取 8 MB;找到后只回填 `startedAt`,不改变当前状态、最近事件或活动时间。达到上限仍找不到时保留任务,但不展示精确总耗时。
-- `live`:之后每 2 秒读取当天新增的完整行。末尾半行留到下次读取;跨零点时先读完旧文件尾部,再从新日期文件头开始。每个成功处理的分块都会推进到最后一个完整换行的 offset;后续分块读取失败时只重试尚未处理的部分。旧文件截断或替换触发 bootstrap 时,由 bootstrap 保留新日期的正确 offset,外层不会再从头按 live 重放;临时读取失败则保留旧日期并在下一轮重试。bootstrap、定时轮询和 Mac 唤醒补读共用串行入口;读取期间到达的请求只合并为一次待补读,并在当前读取结束后执行,避免 actor 在 `await` 处重入而重复消费同一 offset。monitor 为每一代 reader 分配 generation,快速开关 Hook 后迟到的旧批次会被丢弃。
+## Hook 子进程
-Codex Hook 事件可能缺少起点、结束或中断信号。`CodexSessionLifecycleReader` 会补充读取本机 Codex session rollout:
+应用启动入口最先检查 `--hook-event`; 处于 Hook 模式时不会创建菜单栏, 窗口或普通服务, 而是
-- 只检查 monitor 内仍在运行、等待批准或等待终态确认,并且同时具有 session ID 和 turn ID 的任务,不持续扫描所有历史会话。
-- 优先在 `~/.codex/sessions/YYYY/MM/DD/` 和 `~/.codex/archived_sessions/` 按 session ID 定位对应 rollout;这些便宜目录允许每 10 秒重试。resume 的旧 session 找不到时,每个活跃生命周期只递归 `sessions` 一次并保留负缓存;session 重新活跃、缓存文件消失或 Mac 唤醒时重置递归资格。
-- 初次从文件末尾最多读取 512 KB,之后每 1 秒按 byte offset 增量读取,保留半行并检测截断或替换。初始窗口未覆盖完整历史且活跃 turn 的 effort 仍缺失时,会在任务开始至少 2 秒后按精确 turn 从文件尾部最多 8 MB 一次性回查 `turn_context.effort`;每轮 lifecycle 查询最多回查一个 turn,读取失败至少间隔 10 秒重试,成功读取但未找到则不再回查。只解出顶层 `type`、`payload.type`、`payload.turn_id`、`started_at`、`completed_at`、`duration_ms`、`turn_context.approvals_reviewer` 和 `turn_context.effort`;不提取、保存或展示提示词、回复、推理内容、工具内容、审批内容或 token 数据。
-- `event_msg / task_started` 只为缺少 Hook Prompt 起点的精确 turn 回填开始时间;`task_complete` 补齐缺失的 Hook `Stop`,使用 `completed_at` 和 `duration_ms` 生成完成状态。初始恢复只更新状态而不回放通知或触觉反馈;运行期间新收到的 `task_complete` 可发布一次完成 transition,后到的 Hook `Stop` 会被去重。定时轮询和唤醒/恢复触发的即时查询都绑定启动时的 reader generation,并在跨 actor 等待前后校验,旧 generation 的迟到 rollout 结果不会写入新状态。
-- `PermissionRequest` 只表示操作进入审批流程,不等同于 UI 正在等待用户。monitor 先把它保存为当前 turn 的等待候选;只有同一 turn 的 `turn_context.approvals_reviewer` 明确为 `user` 时才切换到等待批准。`auto_review`、兼容值 `guardian_subagent` 或 reviewer 缺失时保持运行状态,不发布等待 transition、通知或触觉反馈。
-- 单次 lifecycle 查询同时包含 reviewer 和 `task_complete` / `turn_aborted` 时,monitor 先保留 `task_started` 的起点回填,再优先处理终态并跳过审批候选确认,不为已经结束的任务发布等待 transition。
-- lifecycle 查询读到 `turn_context.effort` 时会回填当前 turn 的推理强度;Hook 与 rollout 值一致时保持原值,缺失时沿用已有值,若同一 turn 出现冲突则标记为 `mixed`,不会静默覆盖。推理强度会随任务进入完成或终止记录。
-- `event_msg / turn_aborted` 移除对应任务,并在任务中心生成保留 10 分钟的灰色最近终止记录;优先使用 rollout 行时间,缺失时活跃任务使用检测时间、等待终态确认任务使用被新 Prompt 替代的时间,且都不猜测耗时。不生成完成记录、绿色状态、通知或触觉反馈。文件不存在、无法读取、格式变化或缺少精确 ID 时保留原 Hook 状态,最终仍由后续 prompt、Stop、Hook 关闭或 24 小时过期兜底。
+1. 从 stdin 读取一份 JSON payload
+2. 归一化事件字段
+3. 追加一行本地 JSONL
+4. 立即退出
-任务状态机规则:
-
-- 任务键优先使用 `session + turn`,缺少 turn 时使用 session;两者都缺少时按项目名归入匿名任务。匿名任务以及缺少起点的恢复任务不展示精确总耗时。
-- `UserPromptSubmit` 创建运行任务;同一 session 收到新 prompt 时,旧 turn 即使缺少 Stop 也视为已中断并从运行状态移除,但不生成完成记录、通知或触觉反馈。工具、上下文压缩和子智能体事件更新已有任务并解除等待,同时记录最近事件供活动卡片实时展示。工具和权限事件缺少起点时可以恢复顶层状态,子智能体事件不会单独创建顶层任务。
-- `SubagentStart` / `SubagentStop` 的 `turn_id` 属于子 Agent 自己,不等于父任务 turn;子 Agent 活跃数通过共享 `session_id` 归属到该 session 下唯一的当前顶层任务。关联成功后,早于顶层任务可信开始时间的事件会被视为上一 turn 的迟到事件并忽略。monitor 以 `agent_id` 保存每个子 Agent 最新的开始/结束状态,重复事件幂等,旧时间戳不会覆盖新状态;遇到缺失 `agent_id`、同 session 存在多个活动或等待终态确认的顶层任务、无法关联任务,或没有已知开始状态的结束事件后,将当前任务标记为不可可靠统计并隐藏数量。数量可靠且大于 0 时才显示在主面板当前活动卡片,任务中心不显示;任务结束或新 turn 替换旧 turn 时随内存任务状态一并清除。Hook 整体缺失结束事件无法被主动识别,因此该值仍是基于完整 Hook 序列的最佳努力实时状态。
-- `PermissionRequest` 先成为审批候选;只有 rollout 已确认该 turn 的 `approvals_reviewer == user` 才进入等待批准,自动 reviewer 产生的同名 Hook 不改变运行状态。重复的用户等待事件不重复发布等待 transition。live 读取一次可能包含多个事件,monitor 会在整批应用后按任务键合并等待候选:最终仍在等待时使用最终快照发布一次,已经恢复运行、完成或移除时不发布过期等待 transition;完成候选保持事件顺序,并按 completion ID 防止同批重复发布。
-- Hook `Stop` 或 rollout `task_complete` 结束任务并产生最近完成记录,两者在进程内按精确任务键和 session 回退键去重,保留第一次确认的完成及精确耗时且不重复发布 transition。后到的重复完成不会覆盖首次确认结果,也不会缩短 24 小时去重窗口。期间迟到的工具、压缩或权限事件不会恢复已完成任务,只有时间晚于完成记录的新 `UserPromptSubmit` 可以开始下一段生命周期。rollout `turn_aborted` 会直接进入最近终止列表;同 session 新 prompt 淘汰的旧 turn 则立即退出活动列表并进入 5 秒终态确认窗口,期间继续参与 rollout 查询并优先接受 `task_complete`、`turn_aborted` 或迟到 Hook `Stop`,到期仍无终态才进入最近终止列表。“完成”只表示该 turn 已结束,不表示任务成功。
-- 精确 turn 匹配失败时,回退同 session 最近活动任务,再回退同项目匿名任务。
-- UI 优先展示最近等待任务,其次最近运行任务、最近完成任务和最近终止任务,同时保留运行与等待数量。只有终止历史时,活动卡片使用灰色终止状态展示最近一项。活动卡片第一行按“模型 `•` 推理强度 `•` 项目”组合可用字段,第二行展示运行时间、可靠时的“`N 个子 Agent`”及最近的请求/工具/压缩/子智能体事件;其他任务数量以右侧 `+N` 徽标展示。任务中心在模型后使用 `•` 展示推理强度,但不展示子 Agent 数量。菜单栏完成绿色保留 30 秒,任务中心的最近完成和最近终止记录保留 10 分钟,24 小时没有新事件的活动自动过期。
-
-跨日时仍在内存中的运行任务会继续保留;重启 App 后由滚动 24 小时 bootstrap 恢复近期活动,并为更早开始的精确 turn 定向回填起点。任务会一直保留到收到 Hook `Stop` 或 rollout `task_complete`、检测到 `turn_aborted`、同 session 新 prompt 将其淘汰、Hook 被关闭或连续 24 小时没有新事件。完成高亮、最近完成、最近终止、完成去重键和活动过期共用按最近到期时刻创建的单次清理任务,不运行常驻清理计时器;读取完成键时还会惰性淘汰已经超过 24 小时的记录,避免系统休眠或计时任务稍晚唤醒时误拦第一条新事件。
-
-## 写入事务
-
-Hook 可能由多个 Codex 进程并发触发。`WorkflowHookEventRecorder` 会在同一个 `flock(LOCK_EX)` 中完成轻量写入事务:
-
-1. 解析事件时间并格式化为本机时间戳与 date key
-2. 检查当天事件文件是否不存在、已清空、缩小或更换 inode;确认从空文件开始时创建可独立累加的新 generation,非空替换则创建来源不明确的新 generation
-3. 追加当前事件到 `events/YYYY-MM-DD.jsonl`
-4. 将 date key 加入 `maintenance.json` 的 `pending`;如果来源状态和 pending 都没有变化,跳过 `maintenance.json` 重写
-
-Hook 写入路径不更新 `daily.jsonl`,也不执行重建或清理旧文件,避免在 Hook timeout 内持锁执行重活。
-
-`WorkflowService` 是 actor,只在现有自动刷新或手动刷新触发工作流统计刷新时检查 `maintenance.json`。打开菜单面板时只读取现有 `daily.jsonl`。如果没有 `pending` 或 `dirty`,服务不会执行维护。
-
-维护时优先处理 `dirty`,从对应日期文件第一行开始流式重建当天聚合;再处理 `pending`,从 `days[date].offset` 开始流式读取新增事件并合并到已有当天聚合。同一维护批次只读取一次现有 `daily.jsonl`,所有日期任务共享并逐步更新同一份内存聚合集合,每次落盘前仍对整份集合执行当前保留策略的归一化。每条坏行会被跳过并计入 `days[date].corrupt`。处理前后会同时校验文件大小、inode 和上次处理边界前最多 4 KB 的 SHA256;无法证明仍为连续追加时换 generation 并重新构建。处理完成后先在 `stats.lock` 外原子写回 `daily.jsonl`,再短暂持有 `stats.lock` 更新 `maintenance.json`,避免主 App 写 daily 时阻塞 Hook 追加事件。批次没有写入时,服务使用文件 size、identifier 和当天日期键组成的进程内 stamp 跳过未变化文件的重复全量归一化;日期跨天或文件变化后会重新检查并在需要时原子改写。
-
-维护只会根据当前仍存在的 events 文件发现和重建日期。直接删除某个历史 `events/YYYY-MM-DD.jsonl` 不会连带删除现有 `daily.jsonl` 行,也不会单独触发 generation 变化;历史日期不再写入新事件时,界面会继续使用已有 daily。若 daily 行也被删除,开启同步时可从本地同步缓存回退到云端贡献。把仍存在的 events 文件清空、截断或替换则不同:连续性校验会识别变化,并按来源是否可确认从空文件开始来切换 generation 和重建。
-
-## 保留策略
-
-CodexBar 最多保留最近 210 天数据。
-
-最近 3 个本地自然日的每日聚合只在实际收集到 ID 时保留非空 `sessionIds` 和 `turnIds`,用于继续去重。新建聚合以 `[]` 开始,一轮聚合结束后仍为空的数组会规范化为 `null`。早于最近 3 天窗口的日期会把有效 ID 数量或起止事件兜底值压缩成 `sessionCount` 和 `turnCount`,之后不再保存 ID。210 天外的 `events/YYYY-MM-DD.jsonl` 会在主 App 维护流程中删除。
-
-如果 `daily.jsonl` 缺失、为空、解析失败、缺少对应日期摘要,或者某天 events 文件状态和 `maintenance.json` 不一致,主 App 会把对应日期加入 `dirty` 并在刷新维护时按天重建。
-
-## 跨设备同步
-
-完整链路见 [CrossDeviceSync.md](CrossDeviceSync.md)。本节只保留和 Hook 统计直接相关的同步摘要。
-
-设置页「跨设备同步」由 `WorkflowSyncSettings` 管理。该开关只有在 Codex Hook 开启且 `WorkflowSyncCloudKit.makeContainer().accountStatus` 为 `available` 时可操作;`WorkflowSyncCloudKit` 固定使用 `iCloud.app.zabrian.codexbar` 容器。账号不可用时开关禁用,并在开关下方显示「同步不可用」。关闭 Hook 后不会继续触发工作流统计同步。同步使用 CloudKit private database,数据归属当前登录的 iCloud 账号,不跨 iCloud 账号迁移或合并。CodexBar 自己创建和维护的记录都保存在 custom zone `CodexBarZone`,不会写入 `_defaultZone`。
-
-CloudKit 中每个 iCloud 账号会保存一条账号级 salt:
-
-```text
-zoneName = CodexBarZone
-recordType = CodexBarSyncMetadata
-recordName = accountSalt
-schemaVersion = 4
-salt = 32 bytes
-```
-
-设备 ID 只用于区分同一 iCloud 账号下的不同设备:
+原始事件行包含
```text
-deviceId = HMAC_SHA256(accountSalt, IOPlatformUUID)
+timestamp, event, model, effort, permission, approval,
+session, turn, agent, tool, cwd
```
-CodexBar 不上传原始 `IOPlatformUUID`。同一台 Mac 在同一 iCloud 账号下重装 App 或系统后通常得到同一个 `deviceId`;切换 iCloud 账号后会进入另一个 CloudKit private database,并用该账号的 salt 派生另一个 `deviceId`。
-
-跨设备同步上传的是 `daily.jsonl` 单日聚合行的内存副本,去掉:
+除事件名外, 其余字段允许缺失; 时间戳缺失时使用当前时间, 工作目录缺失时使用子进程当前目录
-```text
-sourceIsFresh, sessionIds, turnIds
-```
+`PermissionRequest` 和 `UserPromptSubmit` 可以从 payload 中的 rollout 路径读取对应 `turn_context`, 补充审批路由和推理强度; 只有审批路由为 `user` 时, 实时任务才进入"等待批准"; `auto_review` 和 `guardian_subagent` 仍按运行状态处理
-`sourceGeneration` 会同步,用于区分同一设备、同一天的独立贡献;它只是随机 UUID。`sourceIsFresh` 只留在本机决定是否允许创建独立贡献,不上传。除 `sessionCount` / `turnCount` 按下述规则生成外,其余统计字段保持原值同步,包括 `projectCounts` 和 `modelCounts`。上传副本中的这两个 count 只接受已有正数压缩 count,或本地非空 `sessionIds` / `turnIds` 的去重数量;两者都没有时写为 `null`,不会把空数组或真实全零日上传成明确的 count。脱敏只发生在上传副本上,不会写回本地 `daily.jsonl`,因此最近 3 天本地仍保留非空 `sessionIds` / `turnIds` 用于本机精确去重。接收端读取同步记录时不恢复 ID;正数 count 优先,否则分别回退到 `sessionStartCount` / `stopCount`,所以明确的 `0` 和缺失字段都不会压过起止事件计数。
+## 本地文件
-正常情况下每台设备每天只有一个 generation、一条记录;确认事件文件从空文件重新开始后,会为同一天创建新的 generation 记录:
+工作流数据目录为
```text
-zoneName = CodexBarZone
-recordType = CodexBarDailyAggregate
-recordName = <deviceId>_<yyyy-MM-dd>[_<sourceGeneration>]
-schemaVersion = 4
-sourceGeneration = UUID?
+~/Library/Application Support/CodexBar/HookEvents/
```
-上传匹配只在当前 `deviceId`、当前待上传日期的云端记录内进行,其他设备同一天的贡献不会参与本机副本判断。云端记录没有 `sourceGeneration` 时,必须与本机脱敏聚合的全部同步业务字段完全一致才会被认作同一来源;即使两边 generation 都是 `nil` 也不会跳过内容比较。内容不一致时保留云端贡献,不覆盖、不相加,也不把来源不明确的本机聚合另建为独立贡献。
+| 文件 | 内容 |
+| --- | --- |
+| `events/YYYY-MM-DD.jsonl` | 按本地日期拆分的原始 Hook 事件 |
+| `daily.jsonl` | 每日聚合结果 |
+| `maintenance.json` | 维护 schema, 文件位置, 待增量和待重建状态 |
+| `stats.lock` | Hook 子进程与主 App 共用的进程级文件锁 |
+| `Sync/` | 开启跨设备同步后使用的本地同步状态和缓存 |
-Hook 子进程不访问网络。主 App 每次实际同步都会为保留窗口内的本机 daily 生成脱敏副本并计算稳定 hash,和本地同步状态相同的日期直接跳过,因此不会依赖某次维护刷新是否恰好与 CloudKit 同步同时发生。只有整批待写记录都返回成功才更新本地 hash。单条读取只有 `unknownItem` 会被视为记录不存在;其他读取错误、请求错误、结果缺失或任一单条保存失败都会清除失败批次日期的 hash,使整批在下次刷新继续重试。
+Hook 子进程在跨进程排他锁内完成文件追加和维护状态更新; 主 App 的聚合读取在锁外执行, 提交前后再检查源文件大小, inode 和边界哈希, 避免把截断, 替换或并发写入误认为连续追加
-上传按日期稳定排序并分批执行。每轮同步最多处理 20 秒,每批最多 25 天;每批全部确认后立即把对应日期的 hash 和 `lastUploadAt` 写入 `state.json`。如果时间预算用完、任务被取消或本批 CloudKit 请求失败,本轮停止,剩余日期留给后续每分钟刷新继续;部分成功、部分失败的批次会整体重试,重复 upsert 不改变聚合内容。首次开启同步时设置 `needsBackfill`,只有本地所有日期的 hash 都已与 state 匹配后才清除 backfill 请求。
+JSONL 中的坏行会被跳过并计数, 不会使整天数据失效
-本地同步状态保存在:
+## 每日聚合
-```text
-~/Library/Application Support/CodexBar/HookEvents/Sync/state.json
-~/Library/Application Support/CodexBar/HookEvents/Sync/cache.jsonl
-~/Library/Application Support/CodexBar/HookEvents/Sync/cursor.data
-```
+主 App 根据维护状态执行两类任务
-- `state.json`: 保存 `deviceId`、按日期记录的已上传或已按保护规则处理的 `hashByDate`、`lastUploadAt` 和 `lastPrunedDate`。
-- `cache.jsonl`: 保存从 iCloud 拉到的所有设备脱敏 daily 记录,一行一条;当前设备自己的云端副本用于本地数据缩减时回退。
-- `cursor.data`: 保存 CloudKit custom zone `CodexBarZone` 的 `CKServerChangeToken`,用于下次只拉取增量变化;没有游标时会 query 全量 `CodexBarDailyAggregate` 重建 `cache.jsonl`,随后建立新的游标基线;游标失效或增量拉取失败时会重新全量重建。
+- `pending`: 从已记录的文件 offset 增量读取新增事件
+- `dirty`: 从当天事件文件开头重新构建聚合
-CloudKit 返回删除变化时只会按 record name 从 `cache.jsonl` 移除记录,不会清除 `state.json` 已确认的日期 hash。因此外部删除云端记录后,如果本机该日聚合没有变化,不会在下一轮立即重新上传;本机内容变化或对应 hash 被清除后才会再次进入候选。
+以下情况会触发全量重建: 维护 schema 不匹配, 每日聚合缺失或损坏, 事件文件被截断或替换, 已处理边界发生变化
-接收云端变化时只更新 `cache.jsonl` 和 `cursor.data`,不直接发布新的 `WorkflowSnapshot`,也不让面板立即跳数。缓存和游标按「先写 `cache.jsonl`,再写 `cursor.data`」提交;如果缓存写入失败,游标不会提前推进,下一轮会重新拉取同一批变化或全量回填。面板仍只在现有每分钟自动刷新或用户手动刷新时重新读取本地 `daily.jsonl` 与同步缓存。
+每日聚合保存
-展示合并规则:
+- 事件总数
+- 各 Hook 事件计数
+- 会话数和轮次数
+- 项目计数
+- 模型计数
+- 来源 generation
-```text
-最终展示 = 各设备、各安全 generation 的 daily 贡献之和
-```
+统计口径
-同一 generation 的本机 daily 和本机云端副本不会重复相加:本机 `eventCount` 大于等于同 generation 云端副本时使用本机,否则回退云端。确认从空文件开始的新 generation 会作为同设备、同日期的独立贡献,与已有 generation 相加;来源不明确的非空替换不会自动加入已有云端贡献,避免重复统计。云端记录没有 generation 时,只有其全部同步业务字段与本机完全相同才会认作同一 generation;不一致则继续保护云端。其他设备记录照常累加;热力图详情的 6 个计数指标按每条安全贡献各自 daily 口径先生成展示值,再按日期相加,`projectCounts` 和 `modelCounts` 分别按项目名、模型名逐项相加,最后从合并后的模型计数中选出「最热模型」。
+| 展示指标 | 计算方式 |
+| --- | --- |
+| 会话总数 | 优先使用去重会话 ID 或压缩后的计数, 回退到 `SessionStart` 数量 |
+| 对话轮次 | 优先使用去重轮次 ID 或压缩后的计数, 回退到 `Stop` 数量 |
+| 工具调用 | `PreToolUse` 与 `PostToolUse` 的较大值 |
+| 上下文压缩 | `PreCompact` 与 `PostCompact` 的较大值 |
+| 子 Agent | `SubagentStart` 与 `SubagentStop` 的较大值 |
+| 权限请求 | `PermissionRequest` 数量 |
+| 最热模型 | 模型事件计数最高者; 并列时按名称排序 |
-CloudKit 也按最近 210 天保留。每天第一次工作流刷新时,当前设备会删除 `deviceId == 本机 deviceId` 且早于保留窗口的全部 generation 记录;其他设备记录不由本机清理。展示侧始终忽略最近 210 天外的缓存记录。
+会话 ID 和轮次 ID 只在最近 3 个本地自然日的聚合中保留, 用于持续去重; 更早日期只保存计数; 原始事件和每日聚合最多保留最近 210 天, 维护时删除过期的原始事件文件
-维护和同步请求由 `WorkflowSyncScheduler` 统一调度。菜单面板打开时只读取现有 `daily.jsonl` 和同步缓存;app-server 自动刷新倒计时重置、同步开关开启、Hook 重新开启或同步账号恢复可用时, 调度器合并维护/同步请求。同步中不会取消重启,冷却窗口内只保留一次待补跑请求,补跑前会重新校验 Hook、同步偏好和账号可用性。
+## 实时任务
-同步失败不会清空开启偏好,也不会把原始 CloudKit 错误直接展示给用户。`WorkflowSyncService` 会把错误归类为「网络不可用」「账号不可用」「服务暂时不可用」「同步失败,请稍后重试」,并通过同步结束通知交给 `WorkflowSyncSettings`。主面板更新时间行最右侧的同步图标先按 Codex Hook、跨设备同步偏好和同步账号可用性判断 active 同步态;非 active 同步统一显示 `icloud.slash` 和「同步未开启」。只有 active 同步态才继续区分空闲、同步中和失败;空闲态 tooltip 展示 `最近同步: yyyy-MM-dd HH:mm:ss`, 时间来源和设置页「最近同步」一致,没有成功上传记录时显示「暂无同步记录」;失败态使用 `exclamationmark.icloud`, tooltip 展示归类后的短错误。设置页只保留「同步不可用」、同步中和最近同步时间。
+`HookEventTailReader` 启动时读取最近 24 小时事件, 然后每 2 秒增量读取当天文件; 日期切换时会先读完旧文件, 再开始新文件
-## 从原始事件重建
+实时任务以 `session + turn` 为主要标识, 缺少字段时回退到 session 或项目; 状态由 Hook 事件和 Codex rollout 生命周期共同确定
-设置页「重建数据」使用两次点击选择最近 210 天内的开始和结束日期,选择期间可以跨月;连续点击同一天两次时形成单日范围。保留窗口内的日期均可选择,非空本机原始事件日期以圆点标记,未来日期和保留窗口外日期不可选。选择范围完成后,行内消息显示完整日历范围包含的天数;真正提交时只取范围内仍存在且文件非空的 `events/YYYY-MM-DD.jsonl` 日期批量重建,没有数据的日期不会生成空聚合。例如 1–15 号中只有 1、2、3、4、9、10 号有数据时,确认弹窗和重建任务均按 6 天处理。每次打开设置窗口都会清除上次选择和结果消息。
+- `UserPromptSubmit` 创建运行任务
+- 工具, 压缩和子 Agent 事件更新运行状态
+- `PermissionRequest` 在审批路由为用户时进入等待状态
+- `Stop` 记录完成
+- rollout 中的 `task_complete` 和 `turn_aborted` 补充可靠终态与时长
-用户确认后,`WorkflowSyncScheduler` 将整批重建与普通维护、CloudKit 同步串行调度;已有任务先完成,重建期间产生的自动维护或同步请求合并排队,并在重建结束后继续处理。`WorkflowService` 依次从每个待重建文件第一行开始重新聚合,为对应日期生成新的 `sourceGeneration`,并原子更新 `daily.jsonl`;原始事件文件不会被修改。重建期间允许 Hook 继续追加,每个任务只处理开始时捕获的稳定文件边界,随后新增内容仍由 pending 增量维护补齐;如果任一文件被截断、替换或原位置内容再次变化,本批重建失败并保留 dirty 状态供重试。已成功完成的前序日期仍会保留其本地结果和待云端替换状态。
+rollout reader 每秒检查活跃任务, 只读取任务开始, 上下文, 完成和终止字段, 不解析对话正文或工具内容
-重建表示用户明确选择「以本机这些日期现存原始事件为准」。因此它与自动检测到的来源不明替换不同:同步状态会持久化各日期的权威替换请求,展示时先忽略当前设备对应日期的旧云端缓存;同步可用后,全量确认并删除当前设备对应日期的所有旧 generation,再以本地新 generation 上传重建聚合。上传确认后,本机和远端使用同一个 generation。范围外日期、没有本机数据的日期、其他设备贡献以及原始事件不受影响;同步暂不可用或失败时替换请求保留,后续同步自动重试。
+任务中心保留最近 10 分钟的完成和终止记录; 菜单栏完成状态高亮约 30 秒; 实时恢复窗口为最近 24 小时
-## 统计口径
+## 手动重建
-`events/YYYY-MM-DD.jsonl` 是统计源。Hook 写入时已经按事件自身 `timestamp` 选择对应本地日期文件;重建或增量更新 `daily.jsonl` 时,维护流程按当前处理的文件日期生成当天聚合,再按每行的 `event` 名称归类。`event` 归类时会去掉 `_` 和 `-` 并转小写,例如 `PreToolUse`、`pre_tool_use`、`pre-tool-use` 都会归为 `pretooluse`。
+设置中的"重建数据"允许选择最近 210 天内的日期范围; CodexBar 只处理范围内存在非空原始事件文件的日期, 并逐日重建 `daily.jsonl`
-`daily.jsonl` 每一行 JSON 的字段顺序固定为:
+单日失败不会中止其他日期; 失败日期保持为待重建状态, 后续维护会继续处理; 跨设备同步开启时, 所选日期还会登记为当前设备的待替换数据; 详见 [跨设备同步](CrossDeviceSync.md)
-```text
-date, sourceGeneration, sourceIsFresh, eventCount, sessionStartCount, stopCount, preToolUseCount, postToolUseCount,
-permissionRequestCount, preCompactCount, postCompactCount, subagentStartCount,
-subagentStopCount, sessionCount, turnCount, projectCounts, modelCounts, sessionIds, turnIds
-```
+## 隐私
-其中 `sourceGeneration` 是本地日期事件源的随机 UUID,`sourceIsFresh` 只表示 CodexBar 是否确认该 generation 从空文件开始;两者不包含事件内容。`sessionIds` / `turnIds` / `sessionCount` / `turnCount` 没有值时写为 `null`,`projectCounts` 和 `modelCounts` 内部键按稳定顺序写出。
-
-能参与统计的事件行必须至少满足:
-
-- `timestamp` 能解析为 `yyyy-MM-dd HH:mm:ss.SSS` 本机时间
-- `event` 是非空字符串
-
-不满足这两个条件的坏行在重建时会被跳过。其他字段缺失不会阻断统计,只会影响依赖该字段的去重或项目统计。
-
-`effort` 用于本机实时任务展示,`agent` 用于子 Agent 关联;两者都不参与每日计数或 `daily.jsonl` schema,也不会进入 CloudKit 同步副本。`agent` 不直接展示给用户;原始值只随对应 Hook 行保存在本机事件文件中。
-
-从 `events/YYYY-MM-DD.jsonl` 到页面指标的判定规则如下:
-
-| 页面展示名 | 会被计入的 `events/YYYY-MM-DD.jsonl` 行 | 不会计入的典型情况 | 计数方式 |
-| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| 会话总数 | 最近 3 个本地自然日内,任意带非空 `session` 的事件行都会把该 `session` 加入当天去重集合;另外 `event` 归一化为 `sessionstart` 的行会增加 `sessionStartCount`。 | `session` 为 `null` 且 `event` 不是 `SessionStart`;坏行。 | 优先正数 `sessionCount`,其次非空 `sessionIds` 的去重数量,最后 `sessionStartCount` |
-| 对话轮次 | 最近 3 个本地自然日内,任意带非空 `turn` 的事件行都会把该 `turn` 加入当天去重集合;另外 `event` 归一化为 `stop` 的行会增加 `stopCount`。 | `turn` 为 `null` 且 `event` 不是 `Stop`;坏行。 | 优先正数 `turnCount`,其次非空 `turnIds` 的去重数量,最后 `stopCount` |
-| 子智能体 | `event` 归一化为 `subagentstart` 或 `subagentstop` 的行。 | 其他事件名;坏行。 | `max(subagentStartCount, subagentStopCount)` |
-| 调用工具 | `event` 归一化为 `pretooluse` 的行会增加 `preToolUseCount`;归一化为 `posttooluse` 的行会增加 `postToolUseCount`。`tool` 可以是具体工具名,也可以是 `null`。 | `SessionStart` 这类非工具事件,即使 `tool` 是 `null` 或存在也不会计入;坏行。 | `max(preToolUseCount, postToolUseCount)` |
-| 权限请求 | `event` 归一化为 `permissionrequest` 的行。 | `permission` 字段本身不会触发计数;只有事件名是 `PermissionRequest` 才计入。 | `permissionRequestCount` |
-| 上下文压缩 | `event` 归一化为 `precompact` 或 `postcompact` 的行。 | 其他事件名;坏行。 | `max(preCompactCount, postCompactCount)` |
-| 最热模型 | 任意带非空 `model` 的有效事件行。 | `model` 为 `null` 或空字符串;坏行。 | 按模型名累计事件数,取最高值;并列时按模型名升序取第一个 |
-
-逐字段统计口径如下:
-
-| `daily.jsonl` 字段 | 从 `events/YYYY-MM-DD.jsonl` 读取什么 | 写入 / 更新规则 | 页面关系 |
-| ------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
-| `date` | `timestamp` | Hook 写入时先把事件时间解析为绝对时间,再按当前本地时区格式化为 `yyyy-MM-dd` 选择日期文件。维护流程按当前处理的文件日期生成同名 `daily.jsonl` 行。早于最近 210 天保留窗口的日期不会进入聚合。 | 热力图日期键;详情面板日期。 |
-| `eventCount` | 每条成功解码并保留下来的事件行 | 每处理一条事件就 `+1`,发生在具体事件类型判断之前。因此 `UserPromptSubmit`、未知 `event`、`tool: null`、`session: null` 等行都会计入,只要 `timestamp` 和 `event` 可解析。 | 进入 `WorkflowDailyMetrics.eventCount`,当前页面不展示。 |
-| `sessionStartCount` | `event` | `event` 归一化后等于 `sessionstart` 时 `+1`。不要求 `session` 非空。 | 作为「会话总数」兜底来源。 |
-| `stopCount` | `event` | `event` 归一化后等于 `stop` 时 `+1`。不要求 `turn` 非空。 | 作为「对话轮次」兜底来源。 |
-| `preToolUseCount` | `event` | `event` 归一化后等于 `pretooluse` 时 `+1`。不读取 `tool` 做过滤,`tool` 为 `null` 也计入。 | 参与「调用工具」。 |
-| `postToolUseCount` | `event` | `event` 归一化后等于 `posttooluse` 时 `+1`。不读取 `tool` 做过滤,`tool` 为 `null` 也计入。 | 参与「调用工具」。 |
-| `permissionRequestCount` | `event` | `event` 归一化后等于 `permissionrequest` 时 `+1`。不读取 `permission` 字段做过滤,`permission` 只是记录当时的权限模式。 | 直接显示为「权限请求」。 |
-| `preCompactCount` | `event` | `event` 归一化后等于 `precompact` 时 `+1`。 | 参与「上下文压缩」。 |
-| `postCompactCount` | `event` | `event` 归一化后等于 `postcompact` 时 `+1`。 | 参与「上下文压缩」。 |
-| `subagentStartCount` | `event` | `event` 归一化后等于 `subagentstart` 时 `+1`。 | 参与「子智能体」。 |
-| `subagentStopCount` | `event` | `event` 归一化后等于 `subagentstop` 时 `+1`。 | 参与「子智能体」。 |
-| `sessionIds` | `session` | 新建聚合初始化为 `[]`。最近 3 个本地自然日内,任意事件行只要 `session` 是非空字符串,就插入当天集合并去重、排序;不要求事件类型是 `SessionStart`。聚合结束后仍为空或进入窗口外压缩时写成 `null`;只有非空数组会持久化。 | 参与「会话总数」去重。 |
-| `turnIds` | `turn` | 新建聚合初始化为 `[]`。最近 3 个本地自然日内,任意事件行只要 `turn` 是非空字符串,就插入当天集合并去重、排序;不要求事件类型是 `Stop`。聚合结束后仍为空或进入窗口外压缩时写成 `null`;只有非空数组会持久化。 | 参与「对话轮次」去重。 |
-| `sessionCount` | `sessionIds`、`sessionCount`、`sessionStartCount` | 最近 3 天通常为 `null`;日期进入 3 天外窗口后,归一化时优先沿用已有正数 `sessionCount`,否则使用非空 `sessionIds` 的去重数量,再否则使用 `sessionStartCount`,然后移除 `sessionIds`。空 ID 数组不表示权威的零;`sessionCount == 0` 但 `sessionStartCount > 0` 时会自动修复。 | 参与「会话总数」。 |
-| `turnCount` | `turnIds`、`turnCount`、`stopCount` | 最近 3 天通常为 `null`;日期进入 3 天外窗口后,归一化时优先沿用已有正数 `turnCount`,否则使用非空 `turnIds` 的去重数量,再否则使用 `stopCount`,然后移除 `turnIds`。空 ID 数组不表示权威的零;`turnCount == 0` 但 `stopCount > 0` 时会自动修复。 | 参与「对话轮次」。 |
-| `projectCounts` | `cwd` | 任意事件行只要 `cwd` 非空,就取标准化路径的最后一层目录名作为项目名并 `+1`;如果最后一层为空,回退使用完整路径字符串。统计的是事件数,不是会话数或调用工具数。未知事件也会计入。 | 用于计算 `mostActiveProject`,当前页面不展示。 |
-| `modelCounts` | `model` | 任意事件行只要 `model` 非空,就按原始模型名 `+1`。统计的是带模型字段的事件数,不是 token 数;未知事件也会计入。 | 合并后用于计算并展示「最热模型」。 |
-
-读取 `daily.jsonl` 时,缺失的数字字段按 `0` 处理,缺失的 `projectCounts` / `modelCounts` 按空字典处理,缺失的 `sessionIds` / `turnIds` / `sessionCount` / `turnCount` / `sourceGeneration` 保持为 `nil`,缺失的 `sourceIsFresh` 按 `false` 处理。仍有原始 events 文件的日期会在维护时确保存在来源 generation;已有非空事件文件默认视为来源不明确,只有 Hook 明确从不存在或空文件开始时才标记 fresh。只剩 daily、原始 events 已不存在的日期不会凭空生成 generation,原 daily 行会继续保留。后续归一化仍按当前保留策略补齐或压缩 ID 字段,并把由空 ID 数组产生的不一致零计数修复为起止事件兜底值。
-
-UI 不直接展示所有原始字段,而是先生成 `WorkflowDailyMetrics`:
-
-| 页面展示名 | 生成规则 |
-| ---------- | ------------------------------------------------------------------------------- |
-| 会话总数 | 正数 `sessionCount`,否则非空 `sessionIds` 的去重数量,否则 `sessionStartCount` |
-| 对话轮次 | 正数 `turnCount`,否则非空 `turnIds` 的去重数量,否则 `stopCount` |
-| 子智能体 | `max(subagentStartCount, subagentStopCount)` |
-| 调用工具 | `max(preToolUseCount, postToolUseCount)` |
-| 权限请求 | `permissionRequestCount` |
-| 上下文压缩 | `max(preCompactCount, postCompactCount)` |
-| 最热模型 | 合并 `modelCounts` 后取计数最高的模型;并列时按名称升序 |
-
-`eventCount` 和 `projectCounts` 保留在 daily 聚合中,但当前页面不展示。`UserPromptSubmit` 和未知事件不会增加上述 6 个计数指标,只会进入 `eventCount`;有 `cwd` 时进入 `projectCounts`,有 `model` 时进入 `modelCounts`。
-
-## UI 展示
-
-用量热力图固定为近 30 周、30 列 x 7 行、周日到周六排列。`account/usage/read` 返回当天 `dailyUsageBuckets` 时, 热力图展示今天的小方块和对应 token 数; 没有当天 bucket 时再按 Hook 开关决定是否包含今天。
-
-热力图 hover 时不在菜单面板内绘制旧式 tooltip, 而是通过 `UsageHeatmapHoverContext` 通知 `HeatmapDetailPanelController` 展示侧边详情面板。指针会吸附到最近方块, 离开热力图后 `UsageHeatmap` 延迟 160 ms 清除选中状态; 控制器收到空 hover context 后默认再延迟 220 ms 收起侧边详情面板, 菜单关闭或互斥面板切换时走立即隐藏。
-
-热力图详情面板和额度区的重置次数详情面板互斥。hover 热力图时会隐藏重置次数详情面板; 点击重置次数按钮时会立即隐藏热力图详情面板。
-
-详情面板是菜单面板的 borderless nonactivating child panel:
-
-- 不接收鼠标事件, 不抢走菜单面板 key window
-- 按悬停列优先显示在菜单面板左侧或右侧, 左右空间不足时尝试另一侧
-- 最终位置会被夹在当前屏幕可见区域内, 屏幕边缘保留 `8` px
-- 与菜单面板之间保留 `4` px gap
-- 侧边切换使用抽屉动画: 收起 `0.12` 秒, 展开 `0.18` 秒
-- 内容更新保留 `NSPanel` / `NSHostingController`, 但每次替换 `hostingController.rootView` 并同步 `setContentSize`; 不使用常驻 `ObservableObject` model 复用 SwiftUI 布局树, 避免 Hook 开关切换详情面板高度后触发 AppKit 递归布局
-- nonactivating panel、抽屉动画、child window 挂载、圆角 layer 和左右定位的共用实现位于 `SidePanelSupport.swift`, 同时服务热力图详情面板和重置次数详情面板
-
-Codex Hook 关闭时:
-
-- 默认不包含今天
-- 详情面板显示日期, token 数和「用量强度」分段条
-- 详情面板固定为 `212 x 84`
-- 详情面板横向 padding 为 `12`, 纵向 padding 为 `10`, 圆角为 `12`
-- 日期使用 `.caption2.monospacedDigit()`
-- token 数使用 `14pt` 等宽数字并加粗
-- token 数通过 `TokenCountText` 展示: `1K` 以下显示完整整数, `1K` 起显示 `K` / `M` / `B`, 不使用千位逗号; 文本自身允许缩小到 `0.8`
-
-Codex Hook 开启时:
-
-- 热力图包含今天
-- 没有当天 token bucket 时, 今天的 token 数显示为 `--`
-- 详情面板首行左侧显示日期、右侧显示 token 数
-- 第二行显示「用量强度」分段条
-- 后续逐行显示「最热模型」、「会话总数」、「对话轮次」、「子智能体」、「调用工具」、「权限请求」、「上下文压缩」
-- 详情面板固定为 `212 x 208`
-- 详情面板横向 padding 为 `12`, 纵向 padding 为 `10`, 圆角为 `12`
-- 日期使用 `.caption2.monospacedDigit()`, token 数使用 `14pt` 等宽数字并加粗
-- 工作流统计行整体使用 `11pt`; 左侧标签固定宽度 `72`, 标签和值之间 spacing 为 `6`
-- 工作流统计行右侧数字优先使用正常字号完整展示; 只有正常字号在横向剩余空间内放不下时, 才会启用自动缩小, 最小缩放比例为 `0.60`, 并允许字距收紧
+Hook 原始事件和本地聚合默认只保存在本机; CodexBar 不记录对话正文, 工具输入输出或认证内容; 跨设备同步仅使用每日脱敏聚合, 不上传原始事件, session ID, turn ID 或 agent ID
diff --git a/Docs/CrossDeviceSync.md b/Docs/CrossDeviceSync.md
index 2e4cabe..9bd7636 100644
--- a/Docs/CrossDeviceSync.md
+++ b/Docs/CrossDeviceSync.md
@@ -1,457 +1,147 @@
# 跨设备同步
-本文档记录设置页「跨设备同步」的完整链路。当前实现只同步 Codex Hook 产生的工作流统计每日聚合,不是整个 App 的通用云同步。
+CodexBar 使用 CloudKit 私有数据库同步每日工作流聚合; 同步是可选功能, 仅在 CodexBar Hook 已开启, 用户打开同步开关且当前 iCloud 账号可用时生效
## 同步范围
-会同步:
-
-- `daily.jsonl` 中每一天的工作流统计聚合副本
-- 会话总数、对话轮次、子智能体、调用工具、权限请求、上下文压缩等计数字段
-- `eventCount`、`projectCounts` 和 `modelCounts`
-- 用于区分同设备、同日期独立贡献的随机 `sourceGeneration`
-
-不会同步:
-
-- Codex 账号、额度、token 用量
+每台设备按日期上传一条或多条来源明确的聚合记录, 内容包括
+
+- 日期和来源 generation
+- Hook 事件总数
+- 会话开始和任务完成计数
+- 工具调用前后计数
+- 权限请求计数
+- 上下文压缩前后计数
+- 子 Agent 开始和结束计数
+- 已压缩的会话数和轮次数
+- 项目计数字典
+- 模型计数字典
+- 设备标识和更新时间
+
+以下内容不会同步
+
+- 原始 Hook 事件
+- session ID, turn ID, agent ID
+- 对话正文, 工具输入输出和 Codex rollout 文件
- app-server 请求日志
-- Codex auth 文件、refresh token、stderr 或原始 RPC 响应
-- 原始 Hook 事件 `events/YYYY-MM-DD.jsonl`
-- `sessionIds` 和 `turnIds`
-- CodexBar 设置项、快捷键、日志窗口内容
-
-同步目标是当前 macOS 登录的 iCloud 账号在 `iCloud.app.zabrian.codexbar` 容器中的 CloudKit private database。代码显式使用该容器标识,不通过 App bundle identifier 推导默认容器,因此独立 bundle identifier 的 Debug 构建不会误连到不存在的 `iCloud.app.zabrian.codexbar.debug`。数据不会跨 iCloud 账号迁移或合并;切换 iCloud 账号后会进入另一个 private database。
-
-## 代码入口
-
-| 文件 | 职责 |
-| -------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| `CodexBar/Services/Settings/WorkflowSyncSettings.swift` | 设置页状态、同步账号可用性检查、UserDefaults 开关、最近同步时间、同步中和失败通知 |
-| `CodexBar/Services/Workflow/WorkflowSyncScheduler.swift` | 维护、同步和显式重建的唯一调度者, 合并待执行请求、冷却窗口和最终状态校验 |
-| `CodexBar/Services/Workflow/WorkflowSyncService.swift` | CloudKit 设备标识、上传、拉取、缓存、游标、清理过期记录 |
-| `CodexBar/Services/Workflow/WorkflowService.swift` | 维护本机 daily,并在调度器允许时调用同步服务,把本机 daily 与同步缓存合并成快照 |
-| `CodexBar/Models/CodexWorkflowModels.swift` | 本机聚合、云端脱敏聚合、云端缓存记录、最终 UI 快照的模型和合并规则 |
-| `CodexBar/Views/Menu/CodexStatusMenuSections.swift` | 主面板更新时间行的同步状态图标、最近同步时间和失败 tooltip |
-| `CodexBar/Views/Settings/AppSettingsView.swift` | 设置页同步状态和日期范围批量重建界面 |
-| `CodexBar/Controllers/SettingsWindowController.swift` | 打开设置窗口前刷新 Hook 和同步状态 |
-| `CodexBar/Controllers/StatusItemController.swift` | 自动刷新时触发本机维护,并把同步开关、Hook 和同步可用性变化交给调度器 |
+- Codex `auth.json`, access token 或其他认证文件
+- 账号额度和 Token 用量
-## 本地状态
+## CloudKit 结构
-跨设备同步相关本地状态都在工作流统计目录下:
+容器
```text
-~/Library/Application Support/CodexBar/HookEvents/
+iCloud.app.zabrian.codexbar
```
-同步子目录:
+数据库和自定义 zone
```text
-Sync/state.json
-Sync/cache.jsonl
-Sync/cursor.data
+privateCloudDatabase / CodexBarZone
```
-各文件职责:
-
-| 文件 | 内容 |
-| ------------- | ------------------------------------------------------------------------------------------------------ |
-| `state.json` | 本机同步状态,包括 `deviceId`、每天已处理的本机 hash、待权威替换日期、`lastUploadAt`、`lastPrunedDate` |
-| `cache.jsonl` | 从 iCloud 拉取到的所有设备脱敏 daily 记录,一行一条;同一天可包含多个 generation |
-| `cursor.data` | CloudKit custom zone `CodexBarZone` 的 `CKServerChangeToken`,用于下次增量拉取 |
-
-`state.json` 的逻辑结构:
-
-```json
-{
- "schema": 4,
- "deviceId": "<当前设备在当前 iCloud 账号下的匿名设备 ID>",
- "hashByDate": {
- "2026-06-25": "<脱敏 daily 聚合的 SHA256>"
- },
- "replacementDates": ["2026-06-25"],
- "lastUploadAt": "2026-06-25T10:20:30Z",
- "lastPrunedDate": "2026-06-25"
-}
-```
-
-设置开关存在 `UserDefaults`:
-
-| Key | 含义 |
-| ---------------------------- | --------------------------------------- |
-| `WorkflowSync.isEnabled` | 用户是否开启过跨设备同步 |
-| `WorkflowSync.needsBackfill` | 是否需要对本机现有 daily 数据做一次补传 |
+记录类型
-关闭跨设备同步只会把 `WorkflowSync.isEnabled` 写成 `false`,不会删除本地 `state.json`、`cache.jsonl`、`cursor.data`,也不会删除 CloudKit 中已有记录。
+| 类型 | 内容 |
+| --- | --- |
+| `CodexBarSyncMetadata` | 账号级随机 salt 和同步 schema |
+| `CodexBarDailyAggregate` | 单台设备, 单个日期, 单个来源 generation 的每日聚合 |
-## CloudKit 数据结构
-
-CloudKit 使用显式标识为 `iCloud.app.zabrian.codexbar` 的 container private database。CodexBar 自己创建和维护的记录都保存在 custom zone `CodexBarZone`;不会向 CloudKit `_defaultZone` 写入同步数据。
-
-账号级 metadata 记录保存在 custom zone `CodexBarZone`:
-
-```text
-zoneName = CodexBarZone
-recordType = CodexBarSyncMetadata
-recordName = accountSalt
-fields:
- schemaVersion: 4
- salt: Data(32 bytes)
-```
-
-每天的工作流统计贡献记录保存在 custom zone `CodexBarZone`。正常情况下每台设备每天只有一个 generation;确认原始事件文件从空文件重新开始后,同一天会增加一条 generation 记录:
-
-```text
-recordType = CodexBarDailyAggregate
-recordName = <deviceId>_<yyyy-MM-dd>[_<sourceGeneration>]
-fields:
- schemaVersion: 4
- deviceId: String
- date: String
- sourceGeneration: String?
- eventCount: Int
- sessionStartCount: Int
- stopCount: Int
- preToolUseCount: Int
- postToolUseCount: Int
- permissionRequestCount: Int
- preCompactCount: Int
- postCompactCount: Int
- subagentStartCount: Int
- subagentStopCount: Int
- sessionCount: Int?
- turnCount: Int?
- projectCounts: Data(JSON object)
- modelCounts: Data(JSON object)
- updatedAt: Date
-```
-
-`projectCounts` 会保留本机聚合中的项目显示名。项目显示名通常是 `cwd` 的最后一层目录名;如果路径最后一层为空,代码会回退到完整路径字符串。
-
-`modelCounts` 会保留 Hook 事件中的模型名及其当天事件计数,用于跨设备合并后计算热力图详情的「最热模型」;不会包含 prompt、response 或原始事件内容。
-
-CloudKit Production schema 必须包含当前 schema `4` 使用的字段,包括 `CodexBarDailyAggregate.sourceGeneration`;`deviceId` 和 `date` 需要保持可查询,以便按设备清理过期记录。schema 变化需要通过 CloudKit Dashboard 从 Development 部署到 Production;App 只负责读写记录,不会自动部署 Production schema。开发签名通常访问 Development,发布签名访问 Production。
+当前写入的 CloudKit schema 版本为 `4`
## 设备标识
-设备标识不直接上传 `IOPlatformUUID`。同步服务会先在当前 iCloud private database 中读取或创建 32 字节账号级 salt,然后计算:
-
-```text
-deviceId = HMAC_SHA256(accountSalt, IOPlatformUUID)
-```
-
-这个设计的效果:
-
-- 同一台 Mac 在同一个 iCloud 账号下通常得到同一个 `deviceId`
-- 同一台 Mac 切换 iCloud 账号后会得到不同的 `deviceId`
-- CloudKit 中不会保存原始 `IOPlatformUUID`
-
-当前 iCloud sync state schema 为 `4`。服务会在实际同步前校验 `state.json`;状态无法按当前 schema 使用时,会重建同步状态并重新拉取 CloudKit 缓存。只读本地缓存用于展示时不会改写同步 state。
-
-如果本地 `state.json` 中的 `deviceId` 和当前解析出的 `deviceId` 不一致,说明 iCloud 账号或账号级 salt 已变化。此时同步服务会重置本地同步状态,清空 `cache.jsonl`,并删除 `cursor.data`,然后按新账号重新同步。
-
-## 设置页行为
-
-设置页打开时会刷新:
-
-- Codex Hook 本地配置状态
-- `hooks/list` 验证结果
-- CloudKit account status
-- 最近同步时间
-
-`AppSettingsView.onAppear` 和 App 再次变为 active 时也会刷新同步可用性。
-
-「跨设备同步」开关可操作的条件:
-
-```text
-Codex Hook 已开启
-Codex Hook 当前没有正在更新
-WorkflowSyncCloudKit.makeContainer().accountStatus == .available
-```
-
-UI 状态:
-
-| 状态 | UI 表现 |
-| ------------------------ | ------------------------------------------- |
-| 同步账号状态还在检查 | 开关不可操作,暂不显示错误 |
-| 同步账号可用但 Hook 关闭 | 开关不可操作 |
-| 同步账号不可用 | 开关不可操作,下方显示 `同步不可用` |
-| Hook 开启且同步账号可用 | 开关可操作 |
-| 同步中 | 开关下方显示 `最近同步` 和小型进度指示 |
-| 有成功上传记录 | 开关下方显示 `最近同步 yyyy-MM-dd HH:mm:ss` |
-
-跨设备同步开启时,设置页始终为「最近同步」状态子行保留固定 16 pt 高的单行布局;右侧状态区域固定宽度,同步时间与进度指示通过交叉淡入淡出平滑切换,不触发设置窗口高度或行内位置变化。关闭跨设备同步后移除整行及其占位,让设置窗口随内容缩回。
-
-主面板「数据更新时间」行最右侧始终显示同步状态图标:
-
-| 状态 | SF Symbol | tooltip |
-| ------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| 非 active 同步 | `icloud.slash` | `同步未开启`; 包括 Hook 关闭、同步偏好关闭、同步账号不可用或仍在检查 |
-| active 且空闲 | `icloud` | 有成功上传记录时为 `最近同步: yyyy-MM-dd HH:mm:ss`, 没有记录时为 `暂无同步记录`; 时间来源和设置页「最近同步」一致 |
-| active 且正在同步 | `arrow.trianglehead.clockwise.icloud` | `正在同步` |
-| active 且最近一次同步失败 | `exclamationmark.icloud` | 归类后的短错误, 例如 `网络不可用` |
-
-开启时:
-
-1. `WorkflowSyncSettings.setEnabled(true)` 先确认同步账号可用。
-2. 写入 `WorkflowSync.isEnabled = true`。
-3. 写入 `WorkflowSync.needsBackfill = true`,要求后续同步补传本机已有 daily 数据。
-4. `StatusItemController` 请求一次 CloudKit 同步;如果当前空闲且不在冷却窗口内会立即执行,否则由调度器合并为待补跑同步。
-
-关闭时:
-
-1. 写入 `WorkflowSync.isEnabled = false`。
-2. 清理调度器中的待同步请求,不新开 CloudKit 同步;已经开始的同步不取消,结束后按最终状态决定是否补跑。
-3. 本地同步状态、缓存和云端记录保留。
-
-关闭 Codex Hook 不会清空跨设备同步偏好;但因为工作流统计同步只在 Hook 开启时触发,所以 Hook 关闭期间不会继续同步。之后重新开启 Hook 时,如果跨设备同步偏好仍为 true 且同步账号可用,会通过调度器请求一次同步。
-
-## 刷新时机
-
-跨设备同步只在工作流统计的维护刷新中执行,但本机维护和 CloudKit 同步可以分开执行。核心入口是:
+CodexBar 不直接上传 Mac 的 `IOPlatformUUID`; 应用先在当前 iCloud 私有 zone 中创建或读取 32 字节随机 salt, 再计算
```text
-WorkflowService.loadSnapshot(performMaintenance: true, synchronize: true)
+HMAC-SHA256(IOPlatformUUID, account salt)
```
-两类刷新行为不同:
-
-| 刷新类型 | 是否维护 local daily | 是否访问 CloudKit | 用途 |
-| ---------------------------------------------- | -------------------- | ------------------------ | ------------------------------ |
-| `performMaintenance: false` | 否 | 否,只读取 `cache.jsonl` | 打开菜单面板时快速展示现有数据 |
-| `performMaintenance: true, synchronize: false` | 是 | 否,只读取 `cache.jsonl` | 每分钟自动刷新中的本机统计维护 |
-| `performMaintenance: true, synchronize: true` | 是 | 是 | 调度器允许后的 CloudKit 同步 |
-
-触发 CloudKit 同步请求:
-
-- 用户开启「跨设备同步」
-- Codex Hook 重新开启,且跨设备同步偏好仍为 true
-- 同步账号从不可用变为可用,且 Hook 与跨设备同步都已开启
-- app-server 自动刷新倒计时重置时,如果 Hook、跨设备同步和同步账号都可用
-- 用户从设置页批量重建日期范围内的本机数据,且 Hook、跨设备同步和同步账号都可用
-
-Hook 子进程不访问网络。它只检查事件文件是否从空文件重新开始、维护本地 generation 状态、把原始事件写入 `events/YYYY-MM-DD.jsonl` 并标记 `maintenance.json` 的 pending 日期。真正的 daily 重建和 CloudKit 同步都由主 App 的维护刷新完成。
-
-调度器规则:
-
-- 关闭同步、关闭 Hook 或同步账号不可用时,只清理待同步请求,不新开 CloudKit 同步
-- 同步正在执行时,新请求只标记为待补跑,不取消当前同步
-- 冷却窗口内的多次请求合并为一次待补跑同步
-- 补跑前重新校验 Hook 开启、`WorkflowSync.isEnabled == true` 且同步账号可用;最终状态不满足时丢弃待补跑请求
-- `WorkflowViewModel.refreshMaintenance(synchronize:)` 只执行一次明确的维护刷新;维护、同步和显式重建的运行、排队与同步冷却均由 `WorkflowSyncScheduler` 管理。
-- 用户发起的日期范围批量重建同样由 `WorkflowSyncScheduler` 串行执行;已有维护或同步完成后再开始,重建期间新增的自动维护或同步请求分别合并,并在整批重建完成后继续处理。
-
-## 同步主流程
-
-```mermaid
-flowchart TD
- A["工作流统计维护刷新"] --> B["整理 events 为 daily.jsonl"]
- B --> C["读取本机 daily 聚合"]
- C --> D{"跨设备同步已开启?"}
- D -- "否" --> E["只发布本机快照"]
- D -- "是" --> Z["确保 CodexBarZone 存在"]
- Z --> F["读取或创建 accountSalt 并解析 deviceId"]
- F --> G{"deviceId 是否变化?"}
- G -- "是" --> H["重置 state/cache/cursor"]
- G -- "否" --> I["沿用本地同步状态"]
- H --> Q["校验 sync state schema"]
- I --> Q
- Q --> P["先刷新 CloudKit 缓存"]
- P --> J["生成脱敏 daily 副本"]
- J --> K["按 generation 与 hash 判断待上传日期"]
- K --> L["分批上传到 CloudKit"]
- L --> M["再次拉取上传后的增量变化"]
- M --> N["清理本设备过期云端记录"]
- N --> O["保存 state 并合并快照"]
-```
+计算结果作为同步设备标识; 不同 iCloud 私有数据库使用不同 salt, 原始硬件 UUID 不写入 CloudKit
-「确保 CodexBarZone 存在」和「读取或创建 accountSalt」首次成功后会在 `WorkflowSyncService` actor 内跨轮缓存,后续每轮同步直接复用,不再重复往返 CloudKit。任何一轮同步失败都会作废这两项缓存:iCloud 账号切换必然伴随请求报错,因此下一轮会重新确认 zone、按新账号取 salt,并经 deviceId 变化检测重置本地同步状态。
+## 本地同步状态
-同步服务会在开始和结束时发出通知:
+同步目录位于
```text
-CodexBar.workflowSyncDidStart
-CodexBar.workflowSyncDidFinish
+~/Library/Application Support/CodexBar/HookEvents/Sync/
```
-设置页通过这两个通知更新 `isSyncing` 和 `lastUploadAt`。
-
-## 上传数据如何脱敏
-
-本机 `daily.jsonl` 每行是 `WorkflowDailyAggregate`。上传前会转换成 `WorkflowSyncedDailyAggregate`:
+| 文件 | 内容 |
+| --- | --- |
+| `state.json` | schema, 当前设备 ID, 各日期确认 hash, 待替换日期和最近上传时间 |
+| `cache.jsonl` | 保留范围内所有设备的 CloudKit 每日记录缓存 |
+| `cursor.data` | CloudKit zone 增量变化游标 |
-- 保留各类计数字段
-- 保留 `projectCounts`
-- 保留 `modelCounts`
-- 保留随机 UUID `sourceGeneration`
-- 不包含只用于本机判断来源是否从空文件开始的 `sourceIsFresh`
-- 不包含 `sessionIds`
-- 不包含 `turnIds`
-- 优先把本机已有的正数 `sessionCount` / `turnCount` 写入同步副本
-- 如果没有正数压缩 count,但本机还有非空 `sessionIds` / `turnIds`,会把去重数量写入对应 count
-- 如果两者都没有,对应同步 count 为 `null`,不会上传空数组得到的 `0`
+当前本地同步 state schema 为 `4`, 可读取上一版 schema `3` 并通过全量远端缓存重建迁移
-明确的 `sessionCount == 0` / `turnCount == 0` 如果分别与正数 `sessionStartCount` / `stopCount` 冲突,会被视为不一致值并在本地归一化时修复。接收端不恢复 ID,生成 `WorkflowDailyMetrics` 时使用「正数 `sessionCount`,否则 `sessionStartCount`」和「正数 `turnCount`,否则 `stopCount`」。真正没有会话或轮次的日期因为起止事件计数同样为 `0`,最终仍显示为 `0`。
+## 同步流程
-本机 `daily.jsonl` 不会因为上传而被改写。也就是说,最近 3 个本地自然日实际收集到的非空 `sessionIds` / `turnIds` 仍然只保存在本机,用于本机精确去重。
+一次同步按以下顺序执行
-## 待上传日期选择
+1. 确认自定义 zone 存在
+2. 创建或读取账号级 salt, 并计算当前设备 ID
+3. 设备 ID 变化时清理本地游标和远端缓存
+4. 使用 zone 游标拉取增量变化; 没有游标或增量失败时全量查询
+5. 将本机 `daily.jsonl` 转换为同步聚合并计算稳定 hash
+6. 上传尚未确认的日期
+7. 再次拉取 CloudKit 变化并更新本地缓存
+8. 每天清理当前设备超过 210 天的云端记录
-每次同步会检查保留窗口内的全部本机日期:
+单批最多处理 25 条上传, 每轮上传预算为 20 秒; 未处理完成的日期保留为待同步状态, 由后续刷新继续
-```text
-候选日期 = 本机 daily.jsonl 中的全部保留日期
-```
-
-最多只有 210 个日期;逐日稳定 hash 相同的记录会立即跳过。这样维护和 CloudKit 同步即使分两轮发生,也不会因为变化日期已经被维护流程消费而漏传。
+首次开启同步会请求补传保留范围内的本机聚合; 日常同步由工作流调度器合并, 主要触发来源包括
-对每个候选日期:
+- app-server 自动刷新后的工作流维护
+- 同步开关开启
+- Codex Hook 重新开启
+- iCloud 同步账号恢复可用
-1. 找到本机 daily 聚合。
-2. 转换成脱敏 cloud aggregate。
-3. 用固定字段顺序序列化为 JSON line。
-4. 计算 SHA256。
-5. 如果 hash 和 `state.hashByDate[date]` 相同,表示这份本机数据已经上传或已按保护规则处理,直接跳过。
-6. 否则加入待上传列表。
+连续同步之间使用 8 秒冷却窗口, 期间的新请求合并为一次后续同步
-待上传列表按日期升序排列,保证每次补传顺序稳定。
+## 合并规则
-## 上传节奏和时间预算
+界面展示会合并本机聚合和 `cache.jsonl` 中的远端记录
-为避免每分钟自动刷新被长时间上传拖住,上传有两个限制:
-
-```text
-每批最多 25 天
-每轮最多 20 秒
-```
+- 其他设备的记录按日期累加
+- 当前设备与本机相同 generation 的远端副本不会重复累加
+- 相同来源中 `eventCount` 更大的记录作为较完整版本
+- 没有 generation 的旧记录只有在全部同步字段一致时才视为本机副本
+- 明确从空文件开始的新 generation 可以作为独立来源累加
+- 来源不明确的替换优先保留已有远端记录, 避免把同一批数据重复计数
-上传流程:
+上传同样遵循来源连续性; 相同来源的远端记录事件数更大时, 本机不会用较小聚合覆盖它
-1. 以 25 天为一批切分待上传列表。
-2. 每批开始前检查 Task 是否取消,以及是否仍在 20 秒预算内。
-3. 先按当前设备、当前待上传日期的不带 generation record ID 和当前 generation record ID 批量读取已有 CloudKit 记录;只有单条结果明确为 `unknownItem` 才视为不存在,其他读取错误会终止本批。
-4. 同 generation 记录存在时复用更新;云端记录没有 generation 时,只有全部同步业务字段与本机完全一致才认作同一来源。即使本机 generation 也为空,仍必须比较完整内容。
-5. 当前 generation 不存在时,只有云端没有该日期记录,或本机明确标记为从空文件开始,才创建新的 generation 记录;来源不明确的非空替换不会自动加入云端已有贡献。
-6. 使用 `database.modifyRecords(saving:deleting:savePolicy:.changedKeys, atomically:false)` 保存。
-7. 只有本批所有待写记录都成功,或该日期已经明确按防倒退/来源保护规则保留云端,才更新对应的 `state.hashByDate[date]`。
-8. 如果读取、请求或任一单条保存失败,会删除本批日期在 `hashByDate` 中的确认值并立即保存,使整批日期稳定进入下轮候选。
-9. 本批全部确认后,如果至少有成功写入的日期,更新 `state.lastUploadAt`,并立刻写回 `state.json`。
-
-如果某批 CloudKit 请求整体抛错或返回单条失败,本轮上传停止。已经成功确认的前序批次不会回滚;失败批次即使已有部分记录实际写入,也会整批重试,重复 upsert 不改变聚合内容。
-
-`needsBackfill` 只有在本机所有 daily 日期的 hash 都已经和 `state.hashByDate` 匹配后才会清除。这样首次开启时即使 20 秒内没有补完,后续每分钟刷新也会继续补传。
-
-## 显式重建替换
-
-用户在设置页通过两次点击选择日期范围并确认重建后,`WorkflowService` 只处理范围内有非空本机原始事件文件的日期,为它们分别生成新的本地 generation,并批量加入 `state.replacementDates`,同时清除对应的 `hashByDate[date]`;两次点击同一天时只处理该日期。日期选择器允许选择最近 210 天保留窗口内的任意日期,非空本机原始事件日期以圆点标记,没有数据的日期只参与范围选择,不进入重建或云端替换。这个状态表示用户已经明确授权以当前本机原始事件替换「当前设备、实际重建日期」的云端贡献,不代表新的独立贡献。
-
-存在待替换日期时,同步流程会先全量查询 `CodexBarDailyAggregate`,再按批次删除当前 `deviceId` 对应日期的 legacy 记录和全部 generation 记录。只有删除结果全部成功或返回 `unknownItem` 后,才从本地 cache 移除这些旧记录并按正常上传流程创建本地新 generation 的记录。新记录确认后才从 `replacementDates` 移除日期;删除或上传中途失败时请求保留,下一轮会重新全量确认并幂等重试。
-
-待替换期间,`WorkflowSnapshot` 不使用当前设备对应日期的旧缓存,直接展示重建后的本机聚合;其他设备同日贡献仍照常合并。跨设备同步关闭、Hook 关闭或账号暂不可用时只完成本地重建,待替换状态保留到后续实际同步。超过 210 天保留窗口的待替换日期会随同步清理移除。
-
-## 拉取缓存和游标
-
-上传之后会更新本地同步缓存。`CodexBarDailyAggregate` 保存在 custom zone `CodexBarZone`, 因为 CloudKit 默认 zone 不支持 `getChanges`/zone change token。没有 `cursor.data` 时, App 会先 query 全量 `CodexBarDailyAggregate` 记录(包含当前设备自己的记录)回填 `cache.jsonl`, 然后从 `nil` 调用 CloudKit zone changes 补齐这段变化并保存新的 `cursor.data`; 有游标时优先拉取 custom zone 的增量变化:
-
-```text
-database.recordZoneChanges(
- inZoneWith: CodexBarZone,
- since: cursor,
- desiredKeys: nil,
- resultsLimit: 200
-)
-```
+## 数据重建与替换
-处理规则:
+用户在设置中重建日期范围后, CodexBar 将这些日期登记为当前设备的待替换数据; 下一次可用同步会
-- 修改记录: 只接受 `CodexBarDailyAggregate`,转换成 `WorkflowSyncedDailyRecord` 后按 CloudKit record name 写入内存 cache,因此同设备、同日期可以保留多个 generation
-- 删除记录: 如果删除的是 `CodexBarDailyAggregate`,按原 record name 从 cache 中移除对应 generation
-- `moreComing == true`: 继续用新的 change token 拉下一页
-- `changeTokenExpired` 或增量拉取失败: 不写入日志窗口,直接 query 全量 `CodexBarDailyAggregate` 重建 `cache.jsonl`
-- 全量重建后的游标基线建立失败: 保留已写入的 `cache.jsonl`, 不保存 `cursor.data`, 下轮刷新继续全量重建并再次尝试建立游标
+1. 全量刷新 CloudKit 本地缓存
+2. 删除当前设备在对应日期的旧记录, 包括 legacy 和 generation 记录
+3. 从本地缓存移除这些旧副本
+4. 上传重建后的新 generation
+5. 新记录确认后清除待替换标记
-删除变化只会从 `cache.jsonl` 移除对应 record,不会同时清除 `state.hashByDate`。因此,如果用户在 CloudKit Dashboard 或其他客户端删除某天的云端记录,而本机 daily 内容和上次确认的 hash 没有变化,下一轮同步不会立即把它重新上传;只有本机该日聚合之后发生变化,或同步 state 被重置、对应 hash 被清除时,它才会再次成为上传候选。
+替换只影响当前设备和所选日期, 不删除其他设备或范围外记录; 删除, 上传或网络请求中断时, 待替换标记会保留并在后续同步继续
-本地落盘顺序很重要:
-
-1. 先写 `cache.jsonl`
-2. 再写 `cursor.data`
-
-如果 `cache.jsonl` 写入失败,`cursor.data` 不会提前推进。下一轮会重新拉取同一批 CloudKit 变化,避免游标已经前进但缓存没有落盘导致记录丢失。
-
-## 展示合并规则
-
-UI 展示使用 `WorkflowSnapshot`。合并规则是:
-
-```text
-最终展示 = 各设备、各安全 generation 的 daily 贡献之和
-```
-
-`cache.jsonl` 会保留当前设备自己的全部 generation。当前本机 generation 与其云端副本不会重复相加:本机 `eventCount` 大于等于同 generation 云端副本时使用本机,否则回退云端。其他 generation 只有在 CodexBar 确认它们分别从空文件开始时才作为独立贡献相加。来源不明确的非空替换不会自动加入已有云端贡献,界面继续使用已有云端记录,避免重复统计。
-
-同一天多设备数据相加时,会先把每台设备的 daily aggregate 转成 `WorkflowDailyMetrics`,再按日期求和:
-
-- 本机 daily 的会话/轮次按「正数压缩 count → 非空 ID 去重数量 → 起止事件计数」解析
-- 同步 daily 不含 ID,按「正数压缩 count → 起止事件计数」解析
-
-```text
-sessionCount += other.sessionCount
-turnCount += other.turnCount
-toolCallCount += other.toolCallCount
-permissionRequestCount += other.permissionRequestCount
-contextCompactionCount += other.contextCompactionCount
-subagentCount += other.subagentCount
-```
-
-上传同样按 generation 防倒退:同 generation 云端 `eventCount` 更大时保留云端副本;本机追平后才继续写回。不同 generation 不再互相覆盖;确认从空文件开始的新 generation 使用独立 record,展示时与已有 contribution 相加。云端记录没有 generation 时,只有全部同步业务字段与本机一致才会认作同一来源;不一致则保留云端记录。
-
-CloudKit 拉取不会单独向 UI 推送新快照;只有当前这次 `WorkflowService` 刷新最终提交结果时,菜单面板和热力图才会看到更新。非维护刷新只读取已有 `cache.jsonl`,不会主动联网。
-
-## 保留和清理
-
-本机工作流统计最多保留最近 210 天。跨设备同步遵循同样窗口:
-
-- 读取缓存时会过滤掉 210 天窗口外的记录
-- 保存 `cache.jsonl` 前也会过滤 210 天窗口外的记录
-- 当前设备每天最多执行一次云端清理
-
-云端清理只删除当前设备自己的过期记录,包括同一天的全部 generation:
-
-```text
-deviceId == 当前 deviceId
-date < retentionCutoffDate
-```
+## 保留期
-其他设备的记录不会由本机删除。每台设备只负责清理自己上传的过期记录。
+本地工作流聚合和 CloudKit 缓存只参与最近 210 天的展示; CodexBar 每天清理当前设备超过保留期的 CloudKit 记录, 并从本地同步状态中移除对应确认 hash
-清理候选先通过 CloudKit 按 `deviceId == 当前设备` 分页查询,并通过 `desiredKeys` 只读取 `date` 字段,再在本地校验日期格式并按 `date < retentionCutoffDate` 过滤。CloudKit 的 `date` 是字符串字段,不在服务端使用范围比较;缺失 `date` 或不是合法 `yyyy-MM-dd` 的当前设备记录视为异常记录并一并删除。清理使用查询结果中的完整 `CKRecord.ID` 分批执行,不依赖已经过滤过期行的 `cache.jsonl`,legacy 名称和 `<device>_<date>_<generation>` 名称都会进入删除请求。只有全部删除成功或返回 `unknownItem` 后才更新 `lastPrunedDate`;中途失败会在下一轮继续查询和幂等重试。
+其他设备的过期记录由对应设备在同步时清理; 即使远端仍存在, 当前设备加载缓存时也会过滤保留期外的数据
-当前实现不会因为本机 `daily.jsonl` 删除了某个仍在 210 天窗口内的日期,就主动删除该日期对应的 CloudKit 记录。它会等到该记录超过 210 天保留窗口后再清理。
+## 状态与错误
-单独删除某天的本机 events 文件也不会删除已有 daily 行:历史日期不再产生事件时,界面仍使用保留下来的本机 daily,并与同 generation 云端副本择优。如果 daily 行也被删除,开启同步时界面会回退到 `cache.jsonl` 中的云端贡献;关闭同步或云端没有副本时,该日期才会从界面消失。相比之下,把仍存在的 events 文件清空或截断会被识别为文件连续性变化,并按维护规则重建或切换 generation。
+设置页显示最近一次实际上传时间; 主面板底部 iCloud 图标表示
-## 失败和重试
+- 同步未开启
+- 正在同步
+- 同步可用及最近上传时间
+- 网络, 账号, 服务或重试类错误
-失败处理以不中断工作流统计展示为目标。
+同步失败会保留本地数据和待处理状态; zone 与账号 salt 的进程内缓存会失效, 下一轮重新确认当前 iCloud 账号状态
-| 场景 | 当前行为 |
-| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| iCloud 未登录或不可用 | 设置页禁用「跨设备同步」,显示 `同步不可用`; 主面板同步图标走非 active 同步态, 显示 `icloud.slash` 和「同步未开启」 |
-| 用户尝试在同步账号不可用时开启 | `setEnabled(true)` 直接返回,不写入开启状态 |
-| `CodexBarZone` 不存在 | 同步开始时创建 custom zone |
-| CloudKit 上传读取失败 | 只有 `unknownItem` 视为记录不存在;其他单条读取错误终止本轮,整批日期持久化为待重试 |
-| CloudKit 上传保存失败 | 请求抛错、结果缺失或任一单条失败都会终止本轮;已确认的前序批次保留,失败批次清除 hash 后在下次刷新整批重试 |
-| 确认从空文件开始的新 generation | 为同设备、同日期创建独立记录,与旧 generation 一起展示和清理 |
-| 来源不明确的非空替换 | 不上传为新的独立贡献,继续使用已有云端记录,避免和可能重叠的事件重复相加 |
-| 用户确认从原始事件批量重建 | 对实际有本机数据的日期隐藏当前设备同日旧缓存,删除对应日期的全部旧 generation,再上传本地新 generation;失败时保留待替换日期并重试 |
-| CloudKit 增量拉取失败 | 不写入日志窗口,尝试全量重建缓存 |
-| 云端记录被外部删除 | 从本地 cache 移除;如果本机 daily hash 未变化则不会立即重新上传,等待本机内容变化,或 state 重置、对应 hash 被清除后重新进入候选 |
-| CloudKit 全量重建失败 | 本轮同步失败,保存已有 state,保留已有 cache,后续刷新重试 |
-| 账号 salt 创建冲突 | 重新读取 CloudKit 中已有 salt |
-| 本地 state schema 不兼容 | 丢弃旧 state,按当前 schema 重新同步 |
-| `deviceId` 变化 | 重置本地同步 state/cache/cursor,按当前 iCloud 账号重新同步 |
-| `changeTokenExpired` | 不写入日志窗口,尝试全量重建缓存并建立新的 cursor |
-| `cache.jsonl` 写入失败 | 不保存新 cursor,下一轮重新拉取同一批变化 |
-| 同步失败 | `WorkflowSyncService` 捕获错误并归类为 `网络不可用`、`账号不可用`、`服务暂时不可用` 或 `同步失败,请稍后重试`; 主面板显示 `exclamationmark.icloud` 和短 tooltip, 设置页停止同步中状态且 `最近同步` 不更新 |
+## 发布要求
-同步异常不会清空用户的开启偏好。只要 `WorkflowSync.isEnabled` 仍为 true、Codex Hook 开启且同步账号可用,后续调度器允许的同步会继续重试。
+CloudKit Production 环境必须包含当前 `CodexBarSyncMetadata` 和 `CodexBarDailyAggregate` 字段; 代码不会在运行时把 Development schema 部署到 Production
diff --git a/Docs/DevelopmentGuide.md b/Docs/DevelopmentGuide.md
index 7c614f3..4e98aca 100644
--- a/Docs/DevelopmentGuide.md
+++ b/Docs/DevelopmentGuide.md
@@ -1,1200 +1,382 @@
-# CodexBar 开发文档
+# CodexBar 开发指南
-本文面向继续开发 CodexBar 的维护者, 记录当前 App 的主要流程, 数据边界和模块协作方式
+CodexBar 是 macOS 15+ 菜单栏应用, 使用 Swift 6, SwiftUI, AppKit 和 MVVM; 工程包含主 App 与一个随 App 嵌入的 root helper
-更细的 app-server 协议见 [AppServer.md](AppServer.md), Codex Hook 统计口径见 [CodexHook.md](CodexHook.md), 跨设备同步链路见 [CrossDeviceSync.md](CrossDeviceSync.md), 防休眠边界见 [KeepAlive.md](KeepAlive.md)
+## 工程配置
-## 1. 应用定位与工程边界
+| 项目 | 配置 |
+| --- | --- |
+| Xcode 工程 | `CodexBar.xcodeproj` |
+| Scheme | `CodexBar` |
+| 最低系统 | macOS 15.0 |
+| Swift | 6.0 |
+| UI | SwiftUI + AppKit |
+| 默认 actor isolation | `MainActor` |
+| App Sandbox | 关闭 |
+| Hardened Runtime | 开启 |
+| 更新 | Sparkle |
+| 同步 | CloudKit private database |
-CodexBar 是一个 macOS 菜单栏应用, 使用 SwiftUI + AppKit + MVVM
+主 App 是 `LSUIElement`, 没有 Dock 图标和传统主窗口; App Sandbox 关闭, 以便启动本机 Codex, 读取用户 Codex 配置并管理 Hook; 应用启用 Hardened Runtime
-App 通过本机 Codex app-server 读取账号, 额度和 token 用量, 通过 Codex Hook 记录本机工作流事件, 并把这些数据展示在菜单面板, 设置窗口和日志窗口中
+## Targets
-关键边界:
+### CodexBar
-- 应用形态是 `LSUIElement`, 不显示 Dock 图标, 不依赖主窗口
-- 最低系统版本是 macOS 15.0
-- App Sandbox 保持关闭, 因为需要启动本机 `codex`, 读取真实用户 Codex 登录状态, 并写入用户级 Hook 配置
-- 除手动重置机会过期时间查询、Sparkle 检查/下载更新, 以及用户显式开启「跨设备同步」后的 CloudKit private database 同步外, App 自身不发起网络请求
-- 账号, 额度和 token 用量只在本机处理, 不发送给第三方;Hook 工作流统计默认只在本机处理, 仅在用户开启「跨设备同步」后把脱敏 daily 聚合行同步到当前 iCloud 账号
-- Swift 工程使用 Swift 6 并开启 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`, UI 默认 MainActor 隔离;服务共享状态优先用 actor 管理, DTO、模型、同步辅助类型和静态工具需要显式使用 `nonisolated`
+主菜单栏应用, 负责
-源码目录职责:
+- app-server 通信
+- 账号, 额度和 Token 用量展示
+- Hook 注册, 实时任务和工作流聚合
+- 通知, 设置, 日志和更新
+- CloudKit 同步
+- 防休眠状态控制和 helper 注册
-| 目录 | 职责 |
-| ----------------------- | --------------------------------------------------------------------- |
-| `CodexBar/App/` | SwiftUI 入口和 AppDelegate 启动分支 |
-| `CodexBar/Controllers/` | 菜单栏, 菜单面板, 侧边 child panel, 设置窗口, 日志窗口和窗口行为 |
-| `CodexBar/Models/` | account, quota, usage, workflow, activity, 日期网格、快捷键和错误模型 |
-| `CodexBar/Services/` | app-server, Codex CLI 解析, Hook、统计、防休眠、更新和登录项 |
-| `CodexBar/Views/` | 菜单面板, 设置窗口, 日志窗口和共享 Liquid Glass 样式 |
-| `Shared/` | 主 App 与 root helper 共用的最小 XPC 契约 |
-| `CodexBarHelper/` | 防休眠 root helper 与嵌入 App 的 LaunchDaemon plist |
-| `Docs/` | app-server, Hook 和开发文档 |
-| `Scripts/` | Release 构建、公证、DMG 和 appcast 发布脚本 |
+Bundle identifier
-## 2. 总体架构
-
-两条主数据链路:
-
-- Codex app-server 链路: `CodexStatusService` 启动或复用本机 app-server, 生成 `CodexQuotaSnapshot`, 由 `CodexStatusViewModel` 发布给菜单栏 UI
-- Codex Hook 链路: Codex 进程触发带 `--hook-event` 参数的 Hook 命令, CodexBar 从 stdin payload 读取 `hook_event_name` 并快速写入 JSONL; 主 App 一路维护聚合并生成 `WorkflowSnapshot`, 另一路通过 `CodexActivityMonitor` 只读 tail 原始事件并发布实时活动快照;活跃 turn 再由 `CodexSessionLifecycleReader` 从本机 rollout 补充起点、终态、审批路由和推理强度
-
-## 3. 启动流程
+```text
+Debug: app.zabrian.codexbar.debug
+Release: app.zabrian.codexbar
+```
-入口在 `CodexBar/App/CodexBarApp.swift`
+### CodexBarHelper
-`CodexBarApp.init()` 最先调用 `WorkflowHookEventRecorder.handleIfRequested()`, 用 `--hook-event` 参数区分普通 App 启动和 Hook 子进程启动
+随 App 嵌入的 root LaunchDaemon, 只接受签名匹配的 CodexBar XPC 客户端请求, 并使用 `pmset` 切换 `disablesleep`; 详细边界见 [阻止系统休眠](KeepAlive.md)
-```mermaid
-sequenceDiagram
- participant OS as macOS
- participant App as 启动分流
- participant Hook as Hook 记录器
- participant Delegate as App 启动协调
- participant Controller as 菜单栏控制器
- participant VM as 账号额度状态
+Bundle identifier
- OS->>App: 启动 CodexBar
- App->>Hook: 检查是否为 Hook 记录模式
- alt Hook 记录模式
- Hook->>Hook: 读取标准输入并写入本机事件
- App-->>OS: 正常退出
- else 普通菜单栏启动
- App->>Delegate: 进入 App 启动流程
- Delegate->>Controller: 创建菜单栏控制器
- Controller->>Controller: 安装菜单栏按钮和菜单面板
- Controller->>VM: 启动自动刷新
- end
+```text
+Debug: app.zabrian.codexbar.debug.helper
+Release: app.zabrian.codexbar.helper
```
-普通启动时, `CodexBarAppDelegate` 创建并持有这些长期对象:
-
-- `CodexStatusViewModel`: app-server 刷新状态
-- `WorkflowViewModel`: Hook 工作流统计快照
-- `CodexHookSettings`: Hook 配置状态和写入操作
-- `CodexActivityMonitor`: Hook 实时任务状态、UI 快照和 live transition
-- `KeepAliveController`: 订阅实时任务快照、维护用户偏好和 helper 授权/XPC 状态
-- `WorkflowSyncSettings`: 跨设备同步偏好、账号可用性、同步中和失败状态
-- `GlobalHotKeySettings`: 全局快捷键配置和错误状态
-- `MenuBarQuotaSettings`: 菜单栏额度指示偏好和窗口选择
-- `NotificationSettings`: 本地通知偏好和系统授权状态
-- `AppUpdater`: Sparkle 更新状态
+## 目录结构
-`StatusItemController.install()` 负责:
+```text
+.
+├── CodexBar/
+│ ├── App/
+│ │ └── CodexBarApp.swift SwiftUI 入口和 AppDelegate 启动装配
+│ ├── Controllers/
+│ │ ├── StatusItemController.swift 状态栏入口, 主面板和应用级 UI 装配
+│ │ ├── FallbackPanelController.swift 状态栏锚点不可用时的备用主面板
+│ │ ├── GlobalHotKeyController.swift 全局快捷键注册和事件处理
+│ │ ├── ActivityCenterPanelController.swift 任务中心侧边面板
+│ │ ├── HeatmapDetailPanelController.swift 热力图日期详情侧边面板
+│ │ ├── NotificationOptionsPanelController.swift 通知选项侧边面板
+│ │ ├── ResetCreditsPanelController.swift 手动重置机会侧边面板
+│ │ ├── SidePanelSupport.swift 侧边面板定位, 挂载, 动画和外观支持
+│ │ ├── HostingWindowController.swift SwiftUI 辅助窗口通用控制
+│ │ ├── SettingsWindowController.swift 设置窗口生命周期
+│ │ ├── LogWindowController.swift 日志窗口生命周期
+│ │ ├── MenuSurfaceDismissMonitor.swift 外部点击, 焦点和快捷键关闭处理
+│ │ ├── MenuSurfaceFadeCoordinator.swift 主面板与侧边面板淡入淡出协调
+│ │ └── ScreenGeometry.swift 屏幕选择, 锚点和可见区域计算
+│ ├── Models/
+│ │ ├── CodexAccountModels.swift 账号和订阅模型
+│ │ ├── CodexQuotaModels.swift 额度限制和时间窗口模型
+│ │ ├── CodexUsageModels.swift Token 用量模型
+│ │ ├── CodexActivityModels.swift 实时任务和任务快照模型
+│ │ ├── CodexHookEvent.swift Hook 原始事件模型
+│ │ ├── CodexWorkflowModels.swift 每日聚合和同步模型
+│ │ ├── CodexStatusError.swift 状态读取错误分类
+│ │ ├── CodexWeekGrid.swift 周视图和日期网格模型
+│ │ ├── UsageHeatmapDay.swift 热力图日期展示模型
+│ │ ├── GlobalHotKeyShortcut.swift 快捷键组合模型
+│ │ └── DateFormatter.swift 日期解析和显示格式
+│ ├── Services/
+│ │ ├── CodexCLI/
+│ │ │ ├── CodexCLIResolver.swift Codex 路径和配置目录解析
+│ │ │ └── CodexCLIVersionService.swift CLI 版本和实际使用来源探测
+│ │ ├── CodexStatus/
+│ │ │ ├── AppServerSession.swift app-server stdio 会话和 JSON 请求
+│ │ │ ├── AppServerPipeReaders.swift stdout 和 stderr 异步读取
+│ │ │ ├── CodexStatusService.swift 账号, 额度和用量读取与缓存
+│ │ │ ├── CodexStatusViewModel.swift 主面板状态和刷新协调
+│ │ │ ├── CodexResetCreditsService.swift 手动重置机会过期时间查询
+│ │ │ ├── CodexHookAppServerModels.swift Hook 和配置接口 DTO
+│ │ │ └── RequestLog.swift app-server 交互日志模型和内存存储
+│ │ ├── KeepAlive/
+│ │ │ ├── KeepAliveController.swift 任务驱动的防休眠和 helper 管理
+│ │ │ └── SystemSleepService.swift IOKit assertion 和系统休眠请求
+│ │ ├── Notifications/
+│ │ │ ├── CodexNotificationService.swift 额度, 任务和重置机会通知
+│ │ │ └── NotificationSoundOption.swift 通知声音选项和资源映射
+│ │ ├── Process/
+│ │ │ └── ProcessTermination.swift 子进程退出和强制终止支持
+│ │ ├── Settings/
+│ │ │ ├── CodexHookSettings.swift Hook 开关, 注册和验证状态
+│ │ │ ├── CodexCLINotificationSettings.swift Codex TUI 通知设置
+│ │ │ ├── GlobalHotKeySettings.swift 全局快捷键持久化
+│ │ │ ├── LoginItemSettings.swift 开机启动设置
+│ │ │ ├── MainPanelSettings.swift 主面板任务中心设置
+│ │ │ ├── MenuBarQuotaSettings.swift 菜单栏额度窗口设置
+│ │ │ ├── NotificationSettings.swift 系统通知, 阈值和声音设置
+│ │ │ └── WorkflowSyncSettings.swift 跨设备同步设置和状态
+│ │ ├── Support/
+│ │ │ └── RefreshTaskCoordinator.swift 刷新任务取消和过期结果丢弃
+│ │ ├── Updates/
+│ │ │ └── AppUpdater.swift Sparkle 更新状态和操作
+│ │ └── Workflow/
+│ │ ├── WorkflowHookEventRecorder.swift Hook 子进程入口和事件写入
+│ │ ├── HookEventTailReader.swift Hook JSONL 实时增量读取
+│ │ ├── CodexSessionLifecycleReader.swift rollout 任务生命周期读取
+│ │ ├── CodexActivityMonitor.swift Hook 与 rollout 实时任务合并
+│ │ ├── WorkflowService.swift 本地聚合, 维护和手动重建
+│ │ ├── WorkflowSyncService.swift CloudKit 上传, 拉取和合并
+│ │ ├── WorkflowSyncScheduler.swift 维护, 重建和同步串行调度
+│ │ └── JSONLines.swift JSONL 编解码和稳定序列化
+│ ├── Views/
+│ │ ├── Menu/
+│ │ │ ├── CodexStatusMenuView.swift 主面板根视图
+│ │ │ ├── CodexStatusMenuSections.swift 账号, 额度, 用量和底部区域
+│ │ │ ├── CodexActivityCard.swift 主面板任务卡片
+│ │ │ ├── CodexActivityCenterView.swift 任务中心列表
+│ │ │ ├── QuotaRow.swift 额度窗口行
+│ │ │ ├── ResetCreditsPanelView.swift 重置机会详情
+│ │ │ ├── UsageHeatmap.swift Token 热力图
+│ │ │ ├── AutoRefreshCountdownView.swift 自动刷新倒计时
+│ │ │ ├── TokenCountText.swift Token 数量格式化视图
+│ │ │ └── ScreenFrameReader.swift SwiftUI 屏幕坐标读取
+│ │ ├── Settings/
+│ │ │ ├── AppSettingsView.swift 通用, 高级和关于设置页
+│ │ │ ├── CodexVersionSection.swift Codex 路径和版本信息
+│ │ │ ├── HotKeyRecorderRow.swift 快捷键录制控件
+│ │ │ ├── NotificationOptionsView.swift 通知分类, 阈值和声音选项
+│ │ │ ├── SettingsToggleRow.swift 设置开关通用行
+│ │ │ └── SettingsIndentedRow.swift 设置缩进行布局
+│ │ ├── Log/
+│ │ │ └── LogView.swift app-server 交互日志窗口
+│ │ └── Shared/
+│ │ ├── LiquidGlassStyle.swift Liquid Glass 通用样式
+│ │ ├── QuotaPalette.swift 额度颜色映射
+│ │ └── PasteboardWriter.swift 剪贴板写入支持
+│ └── Resources/ 应用资源文件
+├── Shared/
+│ └── CodexBarHelperXPC.swift App 与 helper 共用的 XPC 契约
+├── CodexBarHelper/
+│ ├── main.swift root helper 入口, XPC 和恢复逻辑
+│ ├── app.zabrian.codexbar.helper.plist Release LaunchDaemon 配置
+│ └── app.zabrian.codexbar.debug.helper.plist Debug LaunchDaemon 配置
+├── Docs/
+│ ├── UserGuide.md 用户操作和设置说明
+│ ├── AppServer.md app-server 通信说明
+│ ├── CodexHook.md Hook 和工作流统计说明
+│ ├── CrossDeviceSync.md CloudKit 同步说明
+│ ├── KeepAlive.md 防休眠和 root helper 说明
+│ └── DevelopmentGuide.md 架构, 构建和发布说明
+├── Scripts/
+│ ├── build.sh Release 构建, 签名和公证
+│ ├── dmg.sh DMG 打包
+│ ├── appcast.sh Sparkle appcast 生成
+│ └── cleanup.swift KeepAlive helper 注销和检查
+├── README.md 项目入口文档
+├── AGENTS.md 编码代理项目约定
+├── CLAUDE.md 代理入口说明
+├── .swiftformat SwiftFormat 配置
+├── .swiftlint.yml SwiftLint 配置
+├── .gitignore Git 忽略规则
+├── appcast.xml Sparkle 更新源
+└── LICENSE GPL-3.0 许可证
+```
-- 配置菜单栏按钮图标、可选额度进度条和点击事件
-- 配置菜单面板的 SwiftUI 根视图
-- 订阅状态变化并切换菜单栏图标
-- 把统一活动快照注入菜单栏图标、tooltip 和菜单活动卡片
-- 订阅 Hook、同步开关和同步可用性变化, 把维护/同步请求交给 `WorkflowSyncScheduler`
-- 订阅全局快捷键配置并安装或移除 Carbon hot key
-- 开始每 60 秒自动刷新
+## 启动流程
-启动时还会把系统 tooltip 首次出现延迟 `NSInitialToolTipDelay` 设置为 200 ms, 让主面板同步图标等短提示更快出现。
+### Hook 模式
-App 退出时, `applicationWillTerminate` 调用 `StatusItemController.uninstall()`、`KeepAliveController.stop()` 和 `CodexActivityMonitor.stop()`, 关闭菜单面板与实时 tail, 注销全局快捷键, 释放防休眠连接, 移除订阅并从系统状态栏移除 status item。`KeepAliveController.stop()` 会先进入停止态,再取消 XPC 重试、最长时限任务和 Helper 注册任务;注册任务的迟到结果只有在控制器仍运行且任务未取消时才能提交状态或重新收敛防休眠
+`CodexBarApp.init()` 首先调用 `WorkflowHookEventRecorder.handleIfRequested()`; 命令行包含 `--hook-event` 时, 进程读取 stdin, 写入一条本地事件并直接退出, 不进入普通 App 生命周期
-### 3.1 任务运行期防休眠
+### 普通模式
-设置页「阻止系统休眠」持久化到 `KeepAlive.isEnabled`,依赖 Codex Hook。最长防休眠期限为 1、2、4、8、12、24 小时或无限制,缺失或无效值回退为 12 小时,持久化键为 `KeepAlive.maximumContinuousDurationSeconds`。`KeepAliveController` 订阅 Hook 开关;Hook 关闭时立即把防休眠选项设为关闭、清除开启偏好并请求恢复,设置页在 Hook 关闭期间将该选项置灰,Hook 重新开启后不会自动恢复开启。控制器只把 `CodexActivitySnapshot.runningTasks` 非空视为需要保活;`waitingTasks`、最近完成和最近终止都不计入。多个并发任务中只要仍有一个运行任务就继续保活,最后一个运行任务进入等待、完成、终止或从快照移除后立即请求恢复。
+1. `CodexBarApp` 安装自定义 `⌘,` 设置命令
+2. `CodexBarAppDelegate` 创建共享服务, 设置对象和 ViewModel
+3. `StatusItemController.install()` 创建状态栏入口, 主面板, 快捷键和刷新订阅
+4. `CodexNotificationService` 订阅额度和任务变化
+5. `CodexActivityMonitor` 启动 Hook 事件尾读和 rollout 生命周期读取
+6. `KeepAliveController` 订阅实时任务并刷新 helper 状态
-控制器用 `CodexActivityTaskSnapshot.id` 识别新运行任务,并记录上一份快照中的等待任务,只维护一个期限起点。第一个运行任务触发保活时建立起点;后续任何首次进入运行态的新任务,或同一任务从 `waitingApproval` 恢复为 `running`,都会把起点更新为当前时间并重排到期任务,因此旧任务仍在运行或本轮已经到期都不妨碍新的运行阶段开始完整周期。同一运行阶段内的工具事件、其他 Hook 更新、App 激活和设置刷新不会更新起点;无限制不创建计时任务。最后一个运行任务进入等待时会恢复系统休眠,获批恢复运行时从恢复时刻重新获得完整期限;多任务中即使还有其他任务一直运行,这次恢复也会更新全部运行任务共享的截止时间。到期后控制器设置上限锁存状态并请求恢复,直到新运行任务或等待任务恢复运行、所有运行和等待任务都消失、功能关闭或 helper 不再可用。用户把期限改大且按最近运行阶段起点仍有剩余时间,或改为无限制时,也可以继续当前周期。
+App 退出时依次卸载状态栏入口, 恢复防休眠状态并停止活动监控
-`SystemSleepService` 在进入保活前创建 `kIOPMAssertionTypePreventUserIdleSystemSleep` assertion,再由 helper 设置 `SleepDisabled=1`:前者明确阻止空闲休眠,后者覆盖普通 assertion 无法覆盖的合盖和手动休眠。每次 App 成功恢复时,先由 helper 还原任务开始前的 `SleepDisabled`,再释放 assertion,使 macOS 的空闲休眠策略在全局禁休眠已经解除后重新计算当前空闲时间、其他 assertion 和电源条件;因此已经达到空闲期限的开盖 Mac 可以由系统立即休眠,App 不自行猜测空闲期限或绕过系统条件强制休眠。随后只要 helper 确认结果为 `SleepDisabled=0`,且 `AppleClamshellState` 与 `AppleClamshellCausesSleep` 表明当前处于普通合盖应休眠状态,App 就调用 `IOPMSleepSystem` 补偿禁休眠期间被抑制的合盖休眠。该恢复流程统一覆盖任务等待、完成、终止、空闲、用户关闭功能和期限到达;App 已退出后的 helper 兜底恢复仍只负责还原原设置。
+## 主要数据流
-普通 power assertion 或 `caffeinate` 不能可靠阻止 MacBook 合盖休眠,因此工程使用 `SMAppService.daemon` 注册嵌入 App 的 `CodexBarHelper`,由 root helper 执行 `/usr/bin/pmset -a disablesleep 1/0`;空闲休眠 assertion 由无特权的主 App 持有,root helper 只负责固定的休眠设置切换和恢复哨兵。helper 只接受 Team ID 与当前构建配置 bundle identifier 都匹配的 CodexBar XPC 客户端。Debug 使用 `app.zabrian.codexbar.debug` 和独立的 helper 服务身份,Release 使用 `app.zabrian.codexbar`,避免开发授权影响正式版本。Mach service 名由当前进程的 bundle identifier 派生:App 添加 `.helper` 后缀,helper 直接使用自身 identifier;LaunchDaemon plist 名和 helper 私有哨兵文件名再由 service 名派生。首次开启可能进入 `requiresApproval`,设置页提供「打开系统设置」;批准后 App 再次 active 时刷新状态并按当前任务快照收敛。控制器按固定顺序计算嵌入的 helper 可执行文件与当前 LaunchDaemon plist 的内容 SHA-256,并把已注册服务对应的指纹保存在当前 App 身份的 `UserDefaults`。每次启动都会检查已注册或等待批准的服务,即使功能关闭;任一文件内容变化时会注销并重新注册,两个文件内容均未变化时不会因 App 本体更新重复注册。功能关闭且服务未注册时不主动注册。注册任务在注销前和注销完成后检查取消状态,停止后的结果不会提交状态、打开系统设置或触发防休眠。针对 macOS 在注销后立即重新注册可能返回的 `SMAppServiceErrorDomain Code=1` 竞态,只做 0.5、1、2 秒有限退避重试,其他错误不重试。
+| 数据 | 来源 | 处理 | 展示或输出 |
+| --- | --- | --- | --- |
+| 账号, 额度, Token | 本机 Codex app-server | `CodexStatusService` 读取并缓存 | 菜单栏图标, 主面板, 通知 |
+| Hook 事件 | Codex 调用当前 App 的 Hook 模式 | 追加本地 JSONL | 实时任务和每日聚合 |
+| rollout 生命周期 | `CODEX_HOME/sessions` 与 `archived_sessions` | 增量读取任务起点, 审批, 完成和终止 | 实时任务状态与时长 |
+| 每日工作流 | 本地 Hook 事件 | `WorkflowService` 增量维护 | 热力图详情和任务统计 |
+| 跨设备聚合 | CloudKit private database | `WorkflowSyncService` 缓存与合并 | 多设备工作流统计 |
+| 休眠状态 | 实时运行任务 | Main App assertion + root helper | 系统电源策略 |
-helper 在切换前把原始 `SleepDisabled` 值写入 root-owned `0600` 哨兵,恢复时写回原值而不是无条件写 `0`,避免覆盖用户或其他工具原有的禁休眠设置,并在 XPC reply 中把恢复后的值返回给 App。App 连接断开后有 15 秒看门狗,helper 每 60 秒自检残留哨兵;helper 启动、收到终止信号或 App 正常请求时也会尝试恢复。详细打包、安全边界与手动验收见 [KeepAlive.md](KeepAlive.md)。
+app-server 细节见 [Codex app-server](AppServer.md), Hook 与统计见 [Codex Hook 与工作流统计](CodexHook.md), 同步见 [跨设备同步](CrossDeviceSync.md)
-## 4. 菜单栏, 菜单面板与窗口流程
+## UI 与窗口
-菜单栏按钮由 `NSStatusBar.system.statusItem(withLength:)` 创建
+### 菜单栏入口
-正常图标是 `person.fill.checkmark`, 错误图标是 `person.fill.xmark`
+`StatusItemController` 是应用级装配点, 统一管理
-小人右下角的状态点只表达 Hook 任务状态,并以 `CodexQuotaSnapshot` 可用作为展示条件。快照可用时按 `等待批准 > 运行中 > 刚完成 > 暂无活动` 取最高优先级:等待批准使用系统橙色,运行中使用系统蓝色,确认 turn 完成后 30 秒内使用系统绿色,空闲时不显示;快照为 `nil` 时不绘制状态点。小人本体始终使用系统前景色,账号异常由 `person.fill.xmark` 表达;状态点与额度竖条分别绘制,颜色互不影响。空闲且没有额度竖条时使用 template 图像,存在状态点或额度竖条时使用非 template 合成图。
+- 状态栏图标与 tooltip
+- `NSPopover` 主面板
+- 无可信状态栏锚点时的 fallback `NSPanel`
+- 右键上下文菜单
+- 全局 Carbon hot key
+- 侧边详情面板
+- 设置和日志窗口
-设置页「菜单栏额度指示」默认开启, 使用独立开关控制启用状态; 缺失持久化选择时默认使用 `.primary`, 关闭时显式持久化 `.off`。开启后在同一行显示额度窗口菜单, 可选择当前账号 Codex limit 返回的额度窗口, 当前保留选择不在返回窗口中时用 fallback 标题追加到菜单。最后一次非关闭的窗口选择由 `MenuBarQuotaSettings` 以 `MenuBarQuota.lastWindowSelection` 键随偏好持久化: 关闭开关时它继续参与菜单淡出避免过渡期间回退, 重新开启时(含重开设置窗口或重启应用后)恢复该选择, 无记录时回退 `.primary`。开启后 `StatusItemController` 会把所选 Codex 窗口的剩余额度进度条绘制在图标左侧, 以竖条形式与 `person.fill.checkmark` / `person.fill.xmark` 合成为单个 `NSImage`, 并随 `CodexStatusViewModel` 自动刷新。合成图尺寸为 `27 x 17`, 图标本体保持原始 `24 x 17`, 左侧竖条轨道为 `2 x 15`, 状态点位于小人右下角。额度显隐或状态点变化时, `StatusItemController` 合并为同一个逐帧重绘任务,在 0.18 秒内同时插值竖条与状态点的透明度以及状态点颜色,避免两个动画任务竞争;过渡期间合成图宽度和绘制坐标保持固定。活动期间 tooltip 每分钟更新一次耗时并合并并发数量与额度,活动结束后取消刷新任务。
+左键切换主面板; 右键或 `Control` + 左键打开上下文菜单; 全局快捷键默认 `⌘⇧W`, 打开时优先使用鼠标所在屏幕
-Hook 开启且 `MainPanelSettings.showsTaskCenter` 为 `true` 时,账号卡片下方显示固定高度 `CodexActivityCard`;该偏好缺失时默认开启。`CodexQuotaSnapshot` 为 `nil` 时,卡片显示「暂无数据」且不开放任务中心;Monitor 继续维护实时状态。快照可用时,卡片按等待、运行、最近完成、最近终止、空闲的顺序展示项目最后一级名称、模型或工具、耗时及其他活动任务数量;只有终止历史时显示最近一项灰色终止状态。存在任务中心内容时,卡片可点击,其他活动任务数量使用右侧 `+N` 徽标,hover 和选中反馈作用于卡片描边。关闭展示偏好只移除活动卡片和任务中心入口,不影响 Monitor、菜单栏状态点、通知或触觉反馈。
+### 主面板
-`ActivityCenterPanelController` 展示 `CodexActivitySnapshot` 的完整等待、运行、最近完成和最近终止列表。等待和运行按最后活动时间倒序,完成和终止按各自结束时间倒序;列表身份使用进程内 opaque UUID,不向 UI 暴露 session/turn ID。最近完成和最近终止保留 10 分钟。活动 Monitor 和 `CodexActivityCenterPresentationState` 作为普通引用传入菜单根视图,再由活动卡片自身观察;这样共享逐秒时间只让卡片失效,不会带动整个菜单树每秒重算。卡片与任务中心观察同一个 Monitor,并在菜单可见、额度快照可用、`MainPanelSettings` 允许展示且存在任务中心内容时使用 presentation state 的共享逐秒时间。任务中心打开期间额度快照变为 `nil`、Hook 关闭或展示偏好关闭时立即关闭。
+主面板使用 SwiftUI, 固定宽度, 按顺序展示账号, 可选任务卡片, 额度, Token/热力图和底部状态; 数据不可用时保留账号状态和任务卡片位置, 并显示统一空状态
-错误图标触发条件:
+`MenuSurfaceDismissMonitor` 处理外部点击, `Esc`, `⌘L`, App 激活变化和 key window 变化; `⌘Space` 会短暂抑制失活关闭, `⌘Tab` 会关闭面板
-- `loadState` 是 `.notLoggedIn` 或 `.initializationFailed`
-- 当前 snapshot 没有可信额度和用量数据, 即 `snapshot?.hasTrustedData == false`
+### 侧边面板
-点击行为:
+热力图详情, 重置机会, 任务中心和通知选项复用 `SidePanelSupport` 的定位, 父子窗口挂载, 圆角和抽屉动画; 面板优先显示在请求侧, 空间不足时换边, 并限制在当前屏幕可见区域内
-| 操作 | 行为 |
-| ---------------- | ---------------- |
-| 左键点击 | 切换菜单面板 |
-| 右键点击 | 打开上下文菜单 |
-| Control + 点击 | 打开上下文菜单 |
-| 全局快捷键 | 切换菜单面板 |
-| 系统 `⌘,` | 打开独立设置窗口 |
-| 菜单面板内 `⌘L` | 打开独立日志窗口 |
-| 点击可见活动卡片 | 切换并发任务中心 |
-| 上下文菜单"设置" | 打开独立设置窗口 |
-| 上下文菜单"日志" | 打开独立日志窗口 |
-| 上下文菜单"退出" | 终止 App |
+### 辅助窗口
-上下文菜单由 `NSStatusBarButton.performClick(nil)` 触发。设置和日志菜单项的 action 可能在 `NSMenu` 仍处于 tracking 时被键盘等效键触发, 因此 `StatusItemController` 会先缓存打开请求, 等 `NSMenuDelegate.menuDidClose(_:)` 确认菜单结束、清空 `statusItem.menu` 后再真正打开辅助窗口, 确保鼠标点击和键盘等效键路径都能把目标窗口激活到最前面。
+设置和日志窗口继承 `HostingWindowController`; `AuxiliaryHostingWindow` 可以成为 key window, 但不会成为 main window; 重新打开时移动到当前 Space, 并按菜单栏所在屏幕或当前屏幕定位
-系统应用设置命令由 `CodexBarApp` 的 `CommandGroup(replacing: .appSettings)` 接管, `⌘,` 不打开空 Settings scene, 而是调用 `StatusItemController.openSettingsFromCommand()` 关闭菜单面板并打开自定义设置窗口。菜单面板打开时, `MenuSurfaceDismissMonitor` 只对精确 `⌘L` 调用日志快捷入口; 带 Shift、Option 或 Control 的组合键不触发该路径。
+设置窗口包含"通用""高级""关于"三页, 按当前内容高度调整窗口; 超过可用高度时由内部滚动视图承载
-全局快捷键由 `GlobalHotKeySettings` 和 `GlobalHotKeyController` 管理。没有用户设置时默认注册 `⌘⇧W`; 用户清除后不注册快捷键。注册冲突时恢复到上一个已注册快捷键, 并把错误显示在设置窗口的快捷键行内。
+## 服务边界
-通过全局快捷键打开菜单面板前, `StatusItemController` 会先用鼠标所在屏幕作为目标屏幕, 找不到时回退主屏幕, 再校验当前 `NSStatusBarButton` 锚点是否可信: 按钮必须有 window 和有效 screen、未隐藏且 bounds 非空, 换算后的屏幕矩形必须是有限尺寸, 宽高至少 1 px, 并且与目标屏幕范围相交。锚点可信时使用 `NSPopover` 挂在 status item 下方; 锚点不可信时使用无箭头 fallback `NSPanel`, 放在目标屏幕顶部居中位置。快捷键打开主面板时会短暂禁止设置窗口和日志窗口成为 key window, 避免 App 激活时把已有的设置/日志窗口一起带到前台。已打开时仍允许快捷键关闭当前面板。鼠标点击路径不做这层 fallback, 因为点击 sender 本身就是当前锚点。
+### CodexStatusService
-打开菜单面板的顺序:
+actor 持有一条 app-server stdio 会话, 负责连接复用, 认证刷新, 请求分类和同账号缓存; UI 只接收数据可用, 未登录和初始化失败三类状态
-- 取消正在等待的延迟刷新和淡入淡出任务
-- 如果来自全局快捷键且当前状态需要打开菜单面板, 先临时禁止设置窗口和日志窗口成为 key window, 再用目标屏幕确认 status item 锚点可信; 不可信时改用同一屏幕顶部居中的 fallback `NSPanel`
-- 设置状态为 `opening`, 准备透明度淡入
-- 显示 `NSPopover` 或 fallback `NSPanel`, 把 `MenuSurfaceVisibilityState.isVisible` 设为 `true`
-- 调用 `refreshWorkflowIfHookEnabled(performMaintenance: false)`, 只读取已有 `daily.jsonl`, 不做重维护
-- 安装 `MenuSurfaceDismissMonitor`, 监听当前菜单面板 window、面板内日志快捷键和已打开的侧边详情面板区域, 并只将当前菜单面板 window 置前和设为 key window
-- 执行 0.24 秒淡入
-- 延迟 160 ms 后调用 `viewModel.refreshIfNeeded()`
+### WorkflowService
-关闭菜单面板的顺序:
+actor 负责每日聚合维护, 文件连续性检查, 保留期清理, 手动重建和同步快照合并; Hook 子进程与主 App 通过 `flock` 保护共享状态
-- 立即隐藏热力图详情面板、重置次数详情面板和并发任务中心
-- 移除本地和全局事件监听
-- 将 `isVisible` 设为 `false`, 停止活动卡片与任务中心共享的逐秒时间任务
-- 临时禁止设置窗口和日志窗口成为 key window, 避免关闭菜单面板时 AppKit 把这些辅助窗口提到前面
-- 默认执行 0.18 秒淡出, 无法淡出时直接关闭
-- 菜单面板关闭后延迟 120 ms 恢复设置窗口和日志窗口的 key window 能力
-
-`MenuSurfaceDismissMonitor` 监听这些 dismiss 条件:
-
-- 菜单面板、状态栏按钮和已打开侧边详情面板外部的鼠标点击
-- Escape
-- Command-Tab
-- App 失去 active
-- 其他应用被激活
-- 菜单面板 window 失去 key
-
-Command-Space 不直接关闭菜单面板, 只短暂抑制 600 ms 内的 active 变化关闭逻辑, 避免 Spotlight 或系统搜索抢焦点时误关弹窗。
-
-热力图详情面板、重置次数详情面板和并发任务中心都会通过 `containsScreenPoint(_:)` 告诉关闭监听器自己的屏幕区域, 因此点击这些 child panel 内部不会触发主菜单面板关闭。重置次数详情面板和并发任务中心可接收鼠标事件用于滚动; 热力图详情面板不接收鼠标事件。并发任务中心是点击后保持打开的面板;出现有效的热力图方块 hover context 时会自动收回任务中心并展示当天详情,点击重置次数也会显式切换并关闭任务中心。
-
-侧边面板的共同行为集中在 `CodexBar/Controllers/SidePanelSupport.swift`。`NonactivatingSidePanel` 不能成为 key/main window;`KeyableBorderlessPanel` 用于需要键盘焦点的通知子选项面板和 fallback 面板;`SidePanelDrawerAnimator` 管理横向抽屉 transform;`SidePanelDrawerPresenter` 管理重置次数、并发任务中心和通知子选项面板的显隐状态、generation、入退场动画及 child window 挂载;`SidePanelContentHost` 统一三个侧边详情面板的内容宿主行为——懒建 panel + hostingController、每次更新替换 rootView、圆角 layer 重配、内容尺寸同步与屏幕点命中检测。`SidePanelSupport` 统一提供 panel 创建、左右侧选择、屏幕边界夹紧、锚点行校验与对齐、菜单面板 key window 恢复、圆角 layer 配置和屏幕坐标换算。侧边面板视图的玻璃底、背板、描边和圆角裁剪共用 `LiquidGlassStyle.swift` 的 `sidePanelChrome(cornerRadius:)`。
-
-通知子选项面板包含 SwiftUI 承载的原生 AppKit 控件,因此通过 `SidePanelDrawerPresenter.usesUntranslatedInitialLayout` 先以 identity transform 完成首次布局和显示提交,再在下一个 MainActor 调度点应用隐藏位移并执行入场动画;重置次数和任务中心仍直接从隐藏位移开始。`present` 的 completion 只在当前 generation 的入场动画完成后调用,供通知面板恢复 fitting-size 更新。设置窗口发出 `willClose` 时,控制器在同一主线程通知中立即隐藏并解除通知面板的 child window 挂载,避免复用设置窗口时残留面板重新出现或补播退出动画。
-
-`HeatmapDetailPanelController` 管理 hover 请求、Y 轴策略、侧边切换队列和 token/workflow 内容更新;`ResetCreditsPanelController` 管理重置次数内容、最大高度和点击切换;`ActivityCenterPanelController` 观察常驻 Monitor 快照并更新列表与窗口布局。任务中心宽度固定,高度由标题、分区、固定行高、间距和底部留白计算,并受屏幕可见高度及活动卡片顶边到主面板底边的范围限制。活动卡片把 `ScreenFrameProvider` 作为锚点交给控制器,控制器每次布局都只读取属于当前菜单窗口的实时 frame;首次读取失败时等待一个 MainActor 调度点重试,仍无有效锚点才回退主面板垂直居中。锚点有效时,面板顶边与卡片顶边对齐,底边最低与主面板底边齐平;达到高度上限后列表内部滚动。
-
-任务中心列表使用普通 `VStack` 和单层条目 transition。快照变化后,SwiftUI 提交列表布局,AppKit 在下一个 MainActor 调度点用 0.20 秒 ease-in-ease-out 曲线更新 panel frame;新的快照会取消尚未执行的布局更新。任务中心内容变空时等待 0.20 秒再执行抽屉收起,期间出现新内容会取消收起。
-
-设置窗口和日志窗口都继承 `HostingWindowController` 的行为: 懒创建, 关闭后不释放, 重新打开复用, 按当前屏幕居中, 重新打开对应入口时只移动和置前对应窗口。窗口 level 保持 `.normal`; 置前时先恢复 `AuxiliaryHostingWindow.allowsKeyFocus`, 再执行 `NSWindow.bringToFrontActivatingApp()` (`ScreenGeometry.swift`, 即 `orderFrontRegardless()` → `NSRunningApplication.current.activate(options: [])` → `makeKeyAndOrderFront(nil)` 的固定序列, fallback 面板和菜单面板聚焦共用), 只做一次性置前, 不持续置顶。CodexBar 是 `LSUIElement` 菜单栏 App, 首次懒创建辅助窗口时需要通过当前运行中应用激活, 避免设置或日志窗口第一次打开时没有稳定拉到最前。
-
-设置窗口和日志窗口使用 `AuxiliaryHostingWindow`; 窗口可以成为 key window, 但不能成为 main window。关闭菜单面板期间会临时禁止成为 key window, 避免菜单面板收起时抢焦点。通过快捷键打开或关闭菜单面板时, 只激活并置前当前面板, 不主动置前已有的设置窗口或日志窗口。
-
-## 5. Codex 状态刷新流程
-
-刷新入口在 `CodexStatusViewModel`:
-
-- `startAutoRefresh()` 先尝试一次 `refreshIfNeeded()`, 之后按 `autoRefreshDelay` 循环
-- 刷新间隔是 60 秒
-- `refreshIfNeeded()` 会比较 `autoRefreshCountdownStartedAt`, 避免菜单面板打开和自动刷新同时触发重复请求
-- `refresh()` 通过 `isRefreshing` 防重入
-- 刷新任务通过 `RefreshTaskCoordinator` 管理, 保证只有最后一次有效刷新能回写 UI 状态
-
-下面的时序图展示刷新, app-server 握手, 额度与用量读取, 以及常见错误后的重试或降级
-
-```mermaid
-sequenceDiagram
- participant UI as 刷新入口
- participant State as 后台状态服务
- participant Finder as Codex 命令解析
- participant Pipe as 标准输入输出会话
- participant Server as 本机 Codex 服务
- participant Cache as 同账号旧缓存
- participant Log as 请求日志
-
- UI->>State: 请求刷新账号, 额度和用量
- State->>State: 进入 actor 隔离区并检查连接是否可复用
-
- alt 没有可复用连接
- State->>Finder: 查找全局 Codex 或 App 内置 Codex
- alt 找不到可执行文件
- Finder-->>State: 返回无法启动
- State->>Log: 记录初始化失败原因
- State-->>UI: 显示初始化失败
- else 找到可执行文件
- Finder-->>State: 返回启动路径和来源
- State->>Server: 启动本机 app-server
- alt 进程启动失败
- State->>Log: 记录启动失败
- State-->>UI: 显示初始化失败
- else 进程启动成功
- State->>Pipe: 建立标准输入输出会话
- Pipe->>Log: 记录初始化请求
- Pipe->>Server: 初始化客户端
- alt 初始化失败或响应无法解析
- Pipe->>Log: 回填错误
- State->>Pipe: 关闭会话
- State-->>UI: 显示初始化失败
- else 初始化成功
- Server-->>Pipe: 返回运行版本
- Pipe->>Server: 发送初始化完成通知
- Pipe->>Log: 记录无响应通知
- Pipe->>Server: 读取当前账号
- alt 当前账号为空
- Server-->>Pipe: 返回未登录状态
- State->>Pipe: 关闭会话
- State-->>UI: 显示未登录
- else 当前账号有效
- Server-->>Pipe: 返回账号状态
- end
- end
- end
- end
- else 复用现有连接
- State->>Pipe: 读取当前账号确认登录状态
- alt 账号为空
- State->>Cache: 清空同账号旧缓存
- State->>Pipe: 关闭会话
- State-->>UI: 显示未登录
- else 账号有效
- Pipe-->>State: 继续读取补充数据
- end
- end
-
- opt 账号有效
- State->>Pipe: 请求额度数据
- alt 认证过期
- State->>Pipe: 刷新登录凭据一次
- alt 刷新后仍失败
- State->>Cache: 清空同账号旧缓存
- State->>Pipe: 关闭会话
- State-->>UI: 显示未登录
- else 刷新成功
- State->>Pipe: 重试额度读取
- end
- else 方法不支持
- State->>Log: 记录不支持的接口
- State->>State: 本连接后续跳过额度接口
- else 业务错误
- State->>Pipe: 立即重试一次
- alt 重试仍失败且有旧缓存
- State->>Cache: 复用旧额度并标记陈旧
- else 重试仍失败且没有旧缓存
- State->>Log: 只保留错误日志
- end
- else 传输错误或超时
- State->>Pipe: 关闭会话
- State->>Server: 重建连接并只重试一次
- else 读取成功
- State->>Cache: 更新额度缓存
- end
-
- State->>Pipe: 请求 token 用量
- alt 认证过期
- State->>Pipe: 刷新登录凭据一次
- alt 刷新后仍失败
- State->>Cache: 清空同账号旧缓存
- State->>Pipe: 关闭会话
- State-->>UI: 显示未登录
- else 刷新成功
- State->>Pipe: 重试用量读取
- end
- else 方法不支持
- State->>Log: 记录不支持的接口
- State->>State: 本连接后续跳过用量接口
- else 业务错误或临时失败
- State->>Pipe: 立即重试一次
- alt 重试仍失败且有旧缓存
- State->>Cache: 复用旧用量并标记陈旧
- else 重试仍失败且没有旧缓存
- State->>Log: 只保留错误日志
- end
- else 传输错误或超时
- State->>Pipe: 关闭会话
- State->>Server: 重建连接并只重试一次
- else 读取成功
- State->>Cache: 更新用量缓存
- end
-
- State->>State: 合成账号快照
- State-->>UI: 更新 loaded, 数据和倒计时
- end
-```
+### CodexActivityMonitor
-`CodexStatusService` 的连接策略:
+MainActor 对象, 合并 Hook JSONL 和 rollout 生命周期, 发布统一任务快照和等待/完成 transition; 通知, 防休眠, 菜单栏状态点和任务中心都消费这份状态
-- `CodexStatusService` 是 actor, app-server 连接、缓存和重建状态都在 actor 隔离内访问
-- 请求超时是 20 秒
-- 连接最大复用时间是 1 小时, 超过后重建, 便于后台升级后的 `codex` 二进制生效
-- 忽略 `SIGPIPE`, 断管由 `write` 抛错后走连接重建
-- 复用连接发生传输故障时只重建并重试一次, 避免故障状态下反复拉起进程
-- 新连接初始化失败直接返回 `.initializationFailed`
+### WorkflowSyncService
-`CodexFetchOutcome` 只向 UI 暴露三种结果:
+actor 使用 CloudKit 私有数据库, 维护设备 ID, zone 游标, 本地缓存, 上传确认 hash 和重建替换状态
-| outcome | UI 状态 |
-| ----------------------- | -------------------------------------- |
-| `.data(snapshot)` | `.loaded` 并展示数据 |
-| `.notLoggedIn` | `.notLoggedIn`, snapshot 清空 |
-| `.initializationFailed` | `.initializationFailed`, snapshot 清空 |
+### CodexNotificationService
-更细的启动失败, 请求失败, 超时, 断连, 解析失败, 业务错误都只进入请求日志
+MainActor 服务, 订阅额度快照和任务 transition, 负责通知权限, 阈值, 去重, 提示音, 触觉反馈和通知点击回调
-## 6. app-server 会话与日志
+### AppUpdater
-app-server 启动命令必须通过 `CodexCLIResolver.resolveAppServerCommand()` 解析, 最终参数是:
+封装 Sparkle 更新状态和设置; Feed URL, EdDSA 公钥和检查间隔来自 `Info.plist`; 自动检查间隔为 1 小时
-```bash
-codex app-server --listen stdio://
-```
-
-解析优先级:
-
-- PATH 中的全局 `codex`
-- 如果 PATH 中的 `codex` 等价于 APP 内置路径, 它被视为内置 CLI, 不算全局 CLI
-- 全局 CLI 不存在时依次检查 `/Applications/ChatGPT.app/Contents/Resources/codex` 和 `/Applications/Codex.app/Contents/Resources/codex`
-- 两者都不存在时抛出 `CodexStatusError.executableNotFound`
-
-环境变量由 `CodexCLIResolver.environment` 构造:
-
-- 保留当前环境
-- `HOME` 使用 `getpwuid(getuid())` 获取真实用户 home
-- 同步设置 `USER` 和 `LOGNAME`
-- 合并 Homebrew, npm global, `.local`, Volta 和系统路径
-- 确保 `TERM` 有值
-
-`AppServerSession` 负责 JSON-RPC 读写:
-
-- 每个带 id 的请求先写入 `RequestLogStorage.beginRequest`
-- 请求 JSON 使用 sorted keys 和不转义斜杠序列化,同一份稳定文本直接写入请求日志
-- 写入 stdin 时追加换行
-- `JSONLineReader` 从 stdout 读取按行 JSON, 只处理 id 匹配的响应, 其他行忽略
-- id 匹配后用同时包含 `error` 和 `result` 的统一响应信封完成一次完整解码,避免大响应行重复解析
-- 收到 JSON-RPC error 时转成 `CodexStatusError.serverError(message)`
-- 响应不能解析成期望类型时归为 `.invalidServerResponse`
-- `initialized` 是无 id 通知, 不等待响应, 但记录为"请求"
-- `PipeDrain` 只 drain stderr, 不把子进程 stderr 展示给用户
-- `JSONLineReader` 和 `PipeDrain` 底层都使用 `PipeReadBuffer`, 把 `FileHandle`、`DispatchSourceRead` 和 semaphore 的非 Sendable IO 边界集中管理
-
-请求错误分类:
-
-| 错误 | 处理 |
-| ---------------------------- | ----------------------------------------------------------------- |
-| 认证失败 | 同一轮最多 `account/read(refreshToken:true)` 一次, 然后重试原读取 |
-| unsupported method | 当前连接记住该 method, 后续跳过 |
-| 非认证业务错误 | `AppServerSession` 先重试同请求一次, 仍失败后不阻断整轮刷新 |
-| 连接断开, 超时, 响应解析失败 | 视为传输故障, 外层重建连接 |
-
-`RequestLogStorage` 是常驻全局日志存储:
-
-- 容量上限 500 条
-- `RequestLogEntry` 完整保存 request/detail
-- 列表摘要和行内展开只使用 `RequestLogEntry` 生成的单行短预览
-- 非空请求和响应标题行提供完整预览和复制; 预览视图对 JSON 做格式化和高亮
-- request 直接保存 `AppServerSession` 已稳定序列化的文本;响应和 JSON 错误详情由 storage 使用相同选项稳定化,非 JSON 错误消息保持原样
-- storage 用 `OSAllocatedUnfairLock` 保护, 后台请求路径可以同步写入并立即拿到请求 token
-- 写入后通过 `Task { @MainActor ... }` 刷新 `RequestLogStore.shared`
-- 日志窗口关闭不会清空日志
-
-`RequestLogStore` 是 `@MainActor ObservableObject` 外壳, 只负责把 storage 快照发布给 SwiftUI, 清空操作也委托给 `RequestLogStorage`
-
-日志状态标签:
-
-| Kind | UI 标签 |
-| ---------------- | ------- |
-| `.pending` | 进行 |
-| `.response` | 完成 |
-| `.failure` | 错误 |
-| `.emptyResponse` | 请求 |
-
-## 7. 错误处理总览
-
-错误处理的基本原则:
-
-- 菜单面板只展示"未登录"和"初始化失败"两类特殊状态
-- 具体启动失败, 请求失败, 超时, 断连, 解析失败和业务错误进入日志窗口
-- 账户有效时, rate limits 和 usage 可以单独失败, 失败区域按缓存或无数据处理
-- 登录项错误显示在设置组与底部按钮组之间的独立错误组; Hook 写入/验证错误显示在 Hook 开关下方; 同步账号不可用显示在「跨设备同步」开关下方; 同步运行失败显示在主面板更新时间行同步图标 tooltip 中
-- 全局快捷键录制, 校验和注册错误显示在快捷键行内
-- Hook 子进程尽量快速退出, 事件记录失败不会阻断 Codex 自身流程
-- 通知发送与 Hook 事件 tail 的失败全部静默降级, 不进入请求日志窗口, 详见第 19 节
-
-app-server 与状态刷新错误:
-
-| 错误来源 | 检测位置 | 用户可见状态 | 日志或存储 | 重试或降级 |
-| -------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------- | ----------------------------------------------------------------- |
-| 找不到全局 Codex CLI 和 Codex APP 内置 CLI | `CodexCLIResolver.resolveAppServerCommand()` | `初始化失败` | `RequestLogStorage.recordFailure` 记录可读错误 | 不启动 app-server, 下轮刷新重新解析 |
-| app-server 进程启动失败 | `Process.run()` | `初始化失败` | 记录"app-server 启动失败" | 不复用本次进程, 下轮刷新重试 |
-| `initialize` 或首次 `account/read` 失败 | `CodexStatusService.openConnection` | `初始化失败` | 对应 JSON-RPC 请求进入日志 | 关闭本次 session, 不重复完整握手 |
-| 首次 `account/read` 返回 `account == nil` | `CodexStatusService.openConnection` | `未登录` | 请求响应进入日志 | 关闭本次 session, 不生成 snapshot |
-| 复用连接刷新 account 后返回 `account == nil` | `CodexStatusService.fetchData` | `未登录` | 请求响应进入日志 | 清空 supplemental cache, teardown connection |
-| JSON-RPC 认证失败 | `CodexStatusError.isAuthenticationRequired` | 取决于刷新后结果 | 失败响应进入日志 | 同一轮最多 `account/read(refreshToken:true)` 一次, 然后重试原读取 |
-| refresh token 后仍认证失败 | `ReadResult.resultAfterAuthAttempt` | `未登录` | 失败响应进入日志 | 清空 cache, teardown connection |
-| unsupported method | `CodexStatusError.isUnsupportedMethod` | 对应区域可能显示无数据 | 失败响应进入日志 | 当前 session 记住 method, 后续跳过, 不复用旧缓存 |
-| 非认证业务错误 | `CodexStatusError.isRetriableServerError` | 通常不改变整体状态 | 失败响应进入日志 | 同请求立即重试一次, 仍失败则 supplemental 读取按失败处理 |
-| rate limits 读取失败 | `CodexStatusService.cachedRead` | 有旧缓存时区域半透明, 无旧缓存时无额度区 | 失败进入日志 | 同账号旧缓存复用并标记 `isRateLimitsStale` |
-| usage 读取失败 | `CodexStatusService.cachedRead` | 有旧缓存时区域半透明, 无旧缓存时无用量区 | 失败进入日志 | 同账号旧缓存复用并标记 `isUsageStale` |
-| 重置机会过期时间请求失败 | `CodexStatusService.fetchResetCreditExpirationDates` / `CodexResetCreditsService` | `重置次数: N` 保留, 侧边详情面板显示未知过期时间 | 不展示错误, 不保存原始响应 | 401/403 时复用本轮认证刷新预算重试, 其他失败静默降级为 `nil` |
-| 连接断开, 请求超时, 响应解析失败 | `CodexStatusError.isTransportFailure` | 复用连接重建失败后为 `初始化失败` | 请求标记为错误 | 复用连接只重建重试一次, 新连接失败不再重试 |
-| app-server 关闭超时 | `AppServerSession.close()` | 不直接改变 UI | 记录强制结束或仍在后台运行 | 先 terminate 等 1 秒, 再 SIGKILL 等 0.5 秒 |
-| snapshot 无可信 quota 和 usage | `CodexQuotaSnapshot.hasTrustedData` | 菜单栏切换错误图标 | 不新增日志 | 仍可展示 stale 数据或无数据面板 |
-
-日志错误处理:
-
-| 场景 | 行为 |
-| ------------------------ | ------------------------------------------------------- |
-| 请求发送后等待响应 | 日志先显示"进行" |
-| 收到正常响应 | 回填同一条日志为"完成" |
-| 请求失败或响应解析失败 | 回填同一条日志为"错误" |
-| `initialized` 无 id 通知 | 记录为"请求", 不等待响应 |
-| 进程级错误没有 method | 日志行直接预览错误文本 |
-| 响应或 JSON 错误详情 | 重新序列化为稳定顺序并保留未转义斜杠 |
-| 请求 payload | 直接保存已稳定序列化的完整内容, UI 行内只渲染单行短预览 |
-| 响应或错误详情 | 存完整内容, 通过预览视图查看或复制 |
-
-设置, Hook 和更新错误:
-
-| 错误来源 | 检测位置 | 用户可见状态 | 重试或降级 |
-| -------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------ |
-| 登录项注册或取消失败 | `LoginItemSettings.setEnabled` | 设置窗口中部错误组显示"设置开机启动失败" | 调用 `refresh()` 恢复实际状态 |
-| `config/read` 请求失败 | `CodexHookSettings.setEnabled` / app-server `config/read` | Hook 选项下方显示"设置 Codex Hook 失败" | 不写 `hooks.json`, 调用 `refresh()` 恢复实际状态 |
-| Codex 全局配置禁用 Hook | `CodexHookSettings.setEnabled` / app-server `config/read` | Hook 开关保持关闭, Hook 选项下方显示禁用说明 | 不写 `hooks.json` |
-| `hooks.json` 读取失败或结构非法 | `CodexHookSettings.refresh` | Hook 开关视为关闭, Hook 选项下方显示错误 | 不写配置 |
-| Hook 开关写入失败 | `CodexHookSettings.setEnabled` | Hook 选项下方显示"设置 Codex Hook 失败" | 调用 `refresh()` 恢复实际状态 |
-| `hooks/list` 请求失败 | `CodexHookSettings.verifyInstalledHooks` / app-server `hooks/list` | Hook 选项下方显示"无法验证 Codex Hook" | 保留已写入 Hook, 详细错误进入日志 |
-| Hook 自动信任写入失败 | `CodexHookSettings.trustCodexBarHooks` / app-server `config/batchWrite` | Hook 选项下方显示"无法验证 Codex Hook" | 保留已写入 Hook, 详细错误进入日志 |
-| Hook 写入后验证发现问题 | `CodexHookSettings.verifyInstalledHooks` / app-server `hooks/list` | Hook 选项下方显示最高优先级验证摘要 | 保留已写入 Hook, 详细响应进入日志 |
-| 同步账号不可用 | `WorkflowSyncSettings.refreshSyncAvailability` / CloudKit account status | 跨设备同步开关禁用, 下方显示"同步不可用"; 主面板同步图标显示 `icloud.slash` 和"同步未开启" | 不开启同步偏好写入 |
-| CloudKit 同步上传或拉取失败 | `WorkflowSyncService.synchronizeIfEnabled` | 主面板更新时间行显示 `exclamationmark.icloud`, tooltip 显示归类错误, 最近同步时间不更新 | 保存已有 state, 下次刷新继续重试 |
-| 快捷键无法识别或不符合规则 | `HotKeyRecorderRow` / `GlobalHotKeySettings.setShortcut` | 快捷键行内显示红色错误 | 用户清除后重新录制 |
-| 快捷键注册冲突 | `StatusItemController.applyGlobalHotKey` | 快捷键行内显示占用提示 | 恢复上一个已注册快捷键 |
-| Hook 子进程 payload 不是 JSON | `WorkflowHookEventRecorder.stdinPayload` | 无 UI 提示 | 吞掉本次 Hook, 避免启动完整菜单栏 App |
-| Hook 子进程写入失败 | `WorkflowHookEventRecorder.handleIfRequested` | 无 UI 提示 | `try? record` 吞掉错误并正常退出, 避免阻断 Codex |
-| `daily.jsonl` 缺失, 空文件或坏行 | `WorkflowService.prepareMaintenanceTasks` | 热力图详情面板可能暂时显示 0 | 标记 dirty, 后续从 events 文件重建 |
-| events 文件变小或 offset 不一致 | `WorkflowService.reconcileEventFiles` | 热力图详情面板可能暂时显示旧聚合 | 标记 dirty, 从头重建当天聚合 |
-| 单个维护任务失败 | `WorkflowService.performMaintenanceIfNeeded` | 使用已有 daily 或空 snapshot | 对应日期标记 dirty |
-| Sparkle 配置缺失 | `AppUpdater.init` | 更新开关禁用, 操作显示"未配置更新资源" | 不创建 updater controller |
-| 手动检查没有更新 | `updaterDidNotFindUpdate` | 显示"没有可用更新" | 1 秒后自动清理状态 |
-| 手动检查失败 | `didAbortWithError` | 显示"检查更新失败" | 不展示底层错误细节 |
-
-Codex 版本探测错误:
-
-| 错误来源 | 显示文本 | 处理 |
-| ------------------------------- | ---------------------------------------- | ----------------------------------------- |
-| 对应安装源不存在 | `未找到 Codex CLI` 或 `未找到 Codex APP` | 不启动探测进程 |
-| `codex --version` 启动失败 | `启动失败` | 该来源显示错误, 另一个来源继续 |
-| 版本探测超时 | `读取超时` | terminate 后 SIGKILL, 停止 pipe collector |
-| 进程退出码非 0 | `读取失败` | 不展示 stderr 细节 |
-| stdout 和 stderr 都没有可用版本 | `版本未知` | 保留路径, 版本列显示错误 |
-
-发布脚本错误:
-
-| 脚本 | 失败条件 | 行为 |
-| -------------------- | --------------------------------------------------------------- | -------------------------------------- |
-| `Scripts/build.sh` | 找不到 Xcode 工程、签名命令、notary 凭据或导出 App | `set -euo pipefail` 直接退出并打印错误 |
-| `Scripts/build.sh` | archive、Developer ID 导出、notary、staple 或签名校验失败 | 退出;默认不产出最终 App,保留中间产物 |
-| `Scripts/dmg.sh` | 找不到唯一 App, 版本号缺失, DMG 挂载失败, 缺少必要命令 | `set -euo pipefail` 直接退出并打印错误 |
-| `Scripts/appcast.sh` | 找不到 DMG, appcast, Xcode 工程, build setting 或 `sign_update` | 直接退出并打印错误 |
-| `Scripts/appcast.sh` | 无法解析 `sparkle:edSignature` | 打印 sign_update 原始输出并退出 |
-| `Scripts/appcast.sh` | appcast 缺少插入点或 XML 校验失败 | 退出, 不继续发布 |
-
-## 8. Snapshot 合成流程
-
-`CodexQuotaSnapshot` 是菜单面板展示 app-server 数据的唯一入口
-
-它由 `AccountReadResponse`, 可选的 `AccountRateLimitsResponse` 和可选的 `AccountUsageResponse` 合成
-
-账户规则:
-
-- `AccountReadResponse.account` 必须存在, 否则视为未登录
-- 账户存在时, 即使 rate limits 和 usage 都没有数据, 也生成 snapshot, 让 UI 展示"暂无数据"
-- `CodexAccount.displayName` 优先使用 email, 没有 email 时按 account type 映射为 `API Key`, `ChatGPT`, `Amazon Bedrock` 或原始 type
-
-额度规则:
-
-- 优先读取 `rateLimitsByLimitId`, 为空时回退顶层 `rateLimits`
-- 顶层 `rateLimits.limitId` 指向的主 limit 置顶, 缺省为 `codex`
-- `codexLimit` 返回 `limitId` 大小写不敏感等于 `codex` 的第一个 limit, 供菜单栏额度指示读取可选窗口
-- 其他 limit 按 `limitName ?? limitId` localized standard 排序, 再按 `limitId` 稳定排序
-- `rateLimitResetCredits.availableCount` 写入 `resetCreditsAvailableCount`, 缺失时不展示重置次数
-- 如果 `resetCreditsAvailableCount > 0`, `CodexResetCreditsService` 会用真实用户 `CODEX_HOME/auth.json` 或 `HOME/.codex/auth.json` 中的 access token, 只读请求 `https://chatgpt.com/backend-api/wham/rate-limit-reset-credits`; 401/403 时复用本轮认证刷新预算, 尚未刷新过时通过当前 app-server 会话刷新一次 token 后重试。成功时将可用且未过期的 `credits[].expires_at` 按升序写入 `resetCreditExpirationDates`; 请求失败时为 `nil`
-- 每个 limit 的 `primary` 和 `secondary` 合成 `[QuotaWindow]`
-- 没有窗口的 limit 被过滤
-- `remainingPercent = clamp(100 - usedPercent, 0...100)`
-- `windowDurationMins` 标签按 `ND`, `NH`, `NM` 格式化, 缺失或非正数显示"额度"
-- 本轮 rate limits 请求失败但同账号有旧缓存时复用旧值, 并把 `isRateLimitsStale` 设为 `true`
-
-用量规则:
-
-- `AccountUsageResponse.summary` 提供全时累计, 单日峰值, 当前连胜, 最长连胜, 最长任务
-- `dailyUsageBuckets` 按 `startDate` 汇总 token
-- `CodexUsageSnapshot.recentWeekGrid` 使用 `CodexWeekGrid` 生成周日到周六排列的日期网格
-- 本轮 usage 请求失败但同账号有旧缓存时复用旧值, 并把 `isUsageStale` 设为 `true`
-
-热力图日期规则由 `UsageHeatmapDay.grid` 合并 token 和 workflow:
-
-- 固定 30 列 x 7 行
-- Hook 开启时包含今天
-- Hook 关闭但 app-server 已返回当天 token bucket 时包含今天
-- Hook 关闭且没有当天 token bucket 时结束于昨天
-- `nil` 表示未来日期或无法生成日期, UI 不绘制方块, 也不参与峰值计算
-- 今天没有 token bucket 但 Hook 开启时, 今天 token 显示 `--`
-
-## 9. 菜单面板 UI 展示流程
-
-`CodexStatusMenuView.menuWidth` 由热力图宽度和 padding 推导:
-
-```swift
-Metrics.padding * 2 + MenuMetrics.panelPadding * 2 + UsageHeatmap.Metrics.totalWidth
-```
+## 并发约定
-UI 状态分支:
-
-```mermaid
-flowchart TD
- Start["渲染菜单面板"] --> HasSnapshot{"是否有账号快照"}
- HasSnapshot -- "否" --> StatusCard["显示未登录或初始化失败"]
- StatusCard --> Empty["显示暂无数据面板"]
- HasSnapshot -- "是" --> Account["显示账号和计划"]
- Account --> HasData{"是否有额度或用量数据"}
- HasData -- "否" --> Empty2["显示暂无数据面板"]
- HasData -- "是" --> Quota["按需显示额度区域"]
- HasData -- "是" --> Usage["按需显示用量区域"]
- Quota --> Updated["显示数据更新时间"]
- Usage --> Updated
- Empty2 --> Updated
-```
+- App target 使用 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`
+- UI, 窗口控制器, 设置对象和 ViewModel 在 MainActor 上运行
+- app-server, 聚合, CloudKit 等共享服务使用 actor 串行管理状态
+- DTO, 纯模型, 格式化工具和跨 actor 数据根据用途标注 `nonisolated` 或满足 `Sendable`
+- 管道读取器和锁封装自行保护非 Sendable 底层对象
+- `RefreshTaskCoordinator` 和各类 generation 标记用于取消旧任务并丢弃过期结果
+- 工作流维护, 同步和手动重建由 `WorkflowSyncScheduler` 串行调度
+- 长时间文件和进程操作不应阻塞 MainActor
-账号区:
+## 本地数据与设置
-- 正常状态显示账号, 计划和刷新进度
-- 账号图标双击触发刷新
-- 邮箱文本双击切换模糊显示
-- 计划名是右侧加粗纯文字, 颜色由 `planBadgeTint(for:)` 按 enterprise, team/business, pro, plus, edu, free, 默认 cyan 匹配
-- 没有 snapshot 时只展示"未登录"或"初始化失败"两种特殊状态
+主要文件位置
-额度区:
+| 路径 | 内容 |
+| --- | --- |
+| `${CODEX_HOME}/auth.json` | Codex 认证文件, 只用于本机手动重置机会查询 |
+| `${CODEX_HOME}/hooks.json` | Codex Hook 配置 |
+| `${CODEX_HOME}/sessions/` | Codex rollout 会话文件, 只增量读取生命周期字段 |
+| `~/Library/Application Support/CodexBar/HookEvents/` | Hook 原始事件, 每日聚合和同步缓存 |
+| `/Library/Application Support/CodexBar/` | root helper 恢复哨兵 |
-- 多个 limit 间用 `LiquidGlassDivider` 分隔
-- 如果 `resetCreditsAvailableCount > 0`, 只在置顶主 limit 标题右侧显示 `重置次数: N`; 该控件是 plain button, 点击后通过重置次数侧边详情面板展示过期时间。`resetCreditExpirationDates` 非空时按 `yyyy-MM-dd HH:mm:ss` 升序逐行展示, 相同展示时间合并数量, 单个显示 `可用: 1`; 剩余时间不超过 7 天时徽标为橙色, 少于 24 小时时为红色, 两个阈值均按精确秒数计算; 多行之间显示渐变分隔线; 没有过期时间时显示「未知过期时间」
-- 每个 quota window 展示标签, 50 个固定胶囊组成的电量条, 剩余百分比和重置时间
-- 胶囊宽度为 `3.5`, 间距为 `2`, 高度为 `12`
-- 额度行标签列宽 `34`, 居中显示, 标签允许最小缩放到 `0.75`, 标签到电量条间距 `12`, 电量条到百分比间距 `8`, 百分比列宽 `37`, 百分比到重置时间最小间距 `6`, 重置时间列宽 `75`
-- 重置时间格式为 `MM-dd HH:mm`, 使用等宽数字, 在额度行最右侧对齐
-- 无数据时百分比和重置时间显示 `--`, 电量条用占位色
-- stale 数据通过 `.markStale(true)` 降低透明度到 0.55
+用户设置通过 `UserDefaults`, `SMAppService`, Sparkle 和 Codex app-server 分别持久化; 修改设置 key 时需要保留缺省值和已有数据的兼容读取
-`QuotaLimitsSection` 通过 `ScreenFrameProvider` 持有额度区桥接 `NSView`, 点击「重置次数」时同步读取额度区在屏幕坐标系中的最新 frame, 作为重置次数详情面板顶部对齐锚点。`ScreenFrameReader` 是通用 `NSViewRepresentable`, 同时服务额度区、活动卡片和热力图;它接受父布局提出的尺寸,在 SwiftUI 布局稳定后上报 frame 并去重,视图拆除时解除与 provider 的绑定。`ScreenFrameProvider` 弱持有当前桥接视图,并同时记录最后有效 frame 及其所属 window。任务中心首次展示只接受当前菜单窗口中的实时 frame,失败时等待一个 MainActor 调度点后重试;后续布局也只允许同一窗口的缓存 frame 兜底,避免复用旧菜单窗口坐标导致顶部错位。额度区和热力图继续按各自控制器的锚点校验与降级策略读取坐标。
+主要缺省值
-重置次数详情面板由 `ResetCreditsPanelController` 管理:
+| 设置 | 默认值 |
+| --- | --- |
+| 全局快捷键 | `⌘⇧W` |
+| 菜单栏额度指示 | 开启, 主额度窗口 |
+| 主面板任务中心 | 开启 |
+| 防休眠最长时限 | 12 小时 |
+| 低额度阈值 | 10% |
+| 长任务通知阈值 | 60 秒 |
+| 跨设备同步 | 关闭 |
-- 面板是菜单面板的 borderless nonactivating child panel, 可接收鼠标事件但不能成为 key/main window
-- 默认显示在菜单面板右侧, 空间不足时尝试左侧, 最终夹紧到当前屏幕可见区域内并保留 `8` px 边距
-- 与菜单面板之间保留 `4` px gap; 纵向优先对齐额度区顶部, 锚点坐标异常或与当前菜单内容区域不相交时丢弃, 没有可用锚点时居中对齐菜单面板
-- 内容宽 `147`, 最小高度 `62`, 高度按过期时间行数和额度区顶部到菜单面板底部的可用空间夹紧; 没有可用锚点时最大高度回退为 `260`, 圆角为 `12`
-- 过期时间行高 `42`, 行间距 `7`; 有多行时行间使用 `1` px 渐变分隔线并通过上下 padding 保持 `7` px 总间距; 横向 padding `12`, 纵向 padding `10`
-- 展开使用 `0.18` 秒抽屉动画, 收起使用 `0.12` 秒抽屉动画
-- 与热力图详情面板互斥: 点击重置次数会隐藏热力图详情面板, hover 热力图会隐藏重置次数详情面板
+## 网络范围
-用量区:
+除本机 app-server 通信外, 主 App 只在以下场景访问网络
-- 指标行展示"全时累计", "单日峰值", "当前连胜", "最长连胜", "最长任务"
-- token 文本由 `TokenCountText` 格式化, 1K 以下完整显示, 1K 起显示 K/M/B
-- 热力图方块强度按当天 token 相对当前 30 周峰值计算, 并用 `pow(percent, 0.62)` 调整视觉强度
-- hover 时通过 `UsageHeatmapHoverContext` 通知 `HeatmapDetailPanelController` 展示侧边详情面板
-- 指针会吸附到最近方块, 吸附动画 0.12 秒; 离开热力图后 `UsageHeatmap` 延迟 160 ms 清除选中状态, 控制器收到空 hover context 后默认再延迟 220 ms 执行侧边面板收起动画
+- 查询手动重置机会过期时间
+- Sparkle 更新检查和下载
+- 用户开启跨设备同步后的 CloudKit private database 请求
-热力图详情面板是菜单面板的 borderless nonactivating child panel, 不接收鼠标事件, 按悬停列优先显示在菜单面板左侧或右侧; 左右空间不足时尝试另一侧, 最终在当前屏幕可见区域内保留 8 px 边距。侧边切换时先以 0.12 秒抽屉动画收起, 再以 0.18 秒展开。热力图详情面板和重置次数详情面板互斥, hover 热力图会立即隐藏重置次数详情面板。nonactivating panel、抽屉 transform、child window 挂载和圆角 layer 配置复用 `SidePanelSupport.swift`。
+root helper 不执行网络请求
-`HeatmapDetailPanelController` 会复用同一个 `NSPanel` 和 `NSHostingController`, 但每次 hover 内容变化时必须替换 `hostingController.rootView` 并同步 `setContentSize` (该更新序列由 `SidePanelContentHost` 统一执行)。不要用常驻 `ObservableObject` model 持续推送 `UsageHeatmapHoverContext`; Hook 开关会让详情面板在 `212 x 84` 和 `212 x 208` 两种布局之间切换, 复用同一棵 SwiftUI 布局树容易触发 AppKit constraint/layout 递归。相关回归路径是: 先 hover 出详情面板, 打开设置切换 Hook, 再回到主面板 hover 热力图。
+## 构建与检查
-详情面板分两种:
+日常编译
-| Hook 状态 | 内容 | 尺寸 |
-| --------- | -------------------------------------------------------------------------------------------------------- | ----------- |
-| 关闭 | 日期, token 数和"用量强度"分段条 | `212 x 84` |
-| 开启 | 日期, token 数, "用量强度"分段条, 最热模型, 会话总数, 对话轮次, 子智能体, 调用工具, 权限请求, 上下文压缩 | `212 x 208` |
+```bash
+xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/platform=macOS' build
+```
-Hook 开启且当天没有 token bucket 时, 今天的 token 数显示 `--`。日期使用 `AnimatedDateText` 做数字滚动, token 数使用 `TokenCountText` 并保留数字和单位宽度。
-「用量强度」前置圆点固定为蓝色, 不随用量强度变化。
+也可以直接用 Xcode 打开 `CodexBar.xcodeproj`
-更新时间行:
+当前工程没有独立测试 target; 修改后至少完成一次构建, 并按影响范围手动检查
-- 显示倒计时圆环, "数据更新时间"和 `HH:mm:ss`
-- 菜单面板可见时使用 `TimelineView(.periodic(..., by: 1))` 每秒 tick
-- 菜单面板不可见时只渲染一次静态圆环
-- 普通 tick 不做连续动画, 只有刷新起点变化时播放 0.5 秒恢复动画
-- 如果 Sparkle 自动发现新版, 右侧显示 `panelUpdateMessage`, 双击该文本调用 `startUpdate()`
-- 最右侧显示同步状态图标;只有 Codex Hook 开启、跨设备同步偏好开启且同步账号可用时, 主面板同步图标才进入 active 同步态
-- 非 active 同步态显示 `icloud.slash`, tooltip 为「同步未开启」
-- active 空闲态显示 `icloud`, tooltip 为 `最近同步: yyyy-MM-dd HH:mm:ss`, 使用 `WorkflowSyncSettings.lastUploadAtText`,和设置页「最近同步」时间口径一致;没有成功上传记录时显示「暂无同步记录」
-- active 同步中显示 `arrow.trianglehead.clockwise.icloud`, tooltip 为「正在同步」
-- active 同步失败显示 `exclamationmark.icloud`; tooltip 不展示原始 CloudKit error, 只展示「网络不可用」「账号不可用」「服务暂时不可用」「同步失败,请稍后重试」这类归类文案
+- 菜单栏左键, 右键和全局快捷键
+- popover 与 fallback panel 的屏幕和焦点行为
+- `⌘,`, `⌘L`, 设置和日志窗口
+- Hook 注册, 验证, 事件写入和任务状态
+- CloudKit 开关, 同步状态和多设备合并
+- 防休眠授权, 运行/等待切换, 上限和异常恢复
-## 10. Codex Hook 开启后完整流程
+SwiftLint 配置位于 `.swiftlint.yml`, 检查范围为 `CodexBar/`
-设置页「CodexBar Hook」由 `CodexHookSettings` 管理, Hook 写入文件是:
+## 发布脚本
-```text
-~/.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 command 保存当前可执行文件的绝对路径。移动或替换 App 后如果不同安装路径的 CodexBar Hook 同时生效,Codex 会让每个 command 都处理同一事件,造成重复追加;另一安装位置的二进制还可能改写共享的 maintenance state。配置维护只增删当前可执行文件对应的 Hook,不会自动清除其他安装路径留下的条目,因此移动 App 和排障时需要显式检查并移除原路径。
-
-下面的时序图展示开启 Hook, Codex 触发事件, 本机写入, 后台维护, 以及常见错误后的处理
-
-```mermaid
-sequenceDiagram
- participant User as 用户
- participant Settings as 设置界面
- participant Server as app-server
- participant Config as Hook 配置读写
- participant File as 全局 Hook 配置
- participant Codex as Codex 运行过程
- participant HookApp as Hook 记录进程
- participant Store as 本机事件存储
- participant Stats as 统计维护
- participant Detail as 热力图详情面板
-
- User->>Settings: 打开启用 Hook
- Settings->>Server: config/read 检查全局 Hook 开关
- alt config/read 请求失败
- Server-->>Settings: 不写配置, 刷新本地状态并显示设置失败
- else Codex 全局禁用 Hook
- Server-->>Settings: Hook 选项下方显示禁用说明
- else Hook 未被全局禁用
- Settings->>Config: 请求写入 Hook 配置
- Config->>File: 读取现有配置
-
- alt 配置结构非法或读取失败
- Config-->>Settings: 开关恢复实际状态并显示错误
- else 文件不存在或读取成功
- Config->>Config: 使用空配置或现有配置
- Config->>Config: 移除 command 包含当前 App 路径的旧 Hook
- Config->>Config: 保留用户已有 Hook 和其他 App Hook
- Config->>Config: 为 10 个事件追加命令 Hook
- Config->>File: 原子写回配置
- alt 写入失败
- Config-->>Settings: 刷新实际状态并显示设置失败
- else 写入成功
- Config-->>Settings: 开关显示已启用
- Settings->>Server: hooks/list 验证 Codex 实际识别结果
- alt hooks/list 请求失败
- Server-->>Settings: 保留已写入 Hook, 显示无法验证
- else Hook 未信任或已修改
- Settings->>Server: config/batchWrite upsert trusted_hash
- Settings->>Server: hooks/list 二次验证
- else command, eventName, enabled, sourcePath, trustStatus, warnings 或 errors 异常
- Server-->>Settings: Hook 选项下方显示验证说明
- else 验证通过
- Server-->>Settings: 清空 Hook 错误提示
- end
- end
- end
- end
-
- opt Hook 已启用且 Codex 触发事件
- Codex->>HookApp: 执行 Hook 命令并传入事件内容
- HookApp->>HookApp: 解析事件名, 时间, 目录, 工具和会话字段
- alt 标准输入为空, 不是 JSON 或缺少 hook_event_name
- HookApp-->>Codex: 吞掉本次 Hook 并正常退出
- else 事件内容可解析
- HookApp->>HookApp: 转成本机事件记录, 缺失 timestamp/cwd 时使用兜底值
- end
-
- HookApp->>Store: 获取写入锁
- alt 获取锁或写入失败
- HookApp-->>Codex: 吞掉记录错误并正常退出
- else 写入成功
- HookApp->>Store: 追加当天原始事件
- HookApp->>Store: 标记当天等待维护
- HookApp->>Store: 释放写入锁
- HookApp-->>Codex: 正常退出
- end
- end
-
- opt App 后台刷新触发维护
- Stats->>Store: 读取维护状态和每日聚合
- alt 每日聚合缺失, 坏行或事件文件状态不一致
- Stats->>Store: 标记当天需要重建
- else 只有新增事件
- Stats->>Store: 从上次位置增量读取
- end
-
- Stats->>Stats: 合并事件计数, 会话去重和工具统计
- alt 单日维护失败
- Stats->>Store: 标记当天下次重建
- Stats-->>Detail: 继续使用已有聚合或空数据
- else 维护成功
- Stats->>Store: 原子写回每日聚合
- Stats->>Store: 更新维护状态并清理过期事件
- Stats-->>Detail: 展示最新统计
- end
- end
+```bash
+Scripts/build.sh --notary-profile <profile>
```
-当前安装事件:
-
-- `SessionStart`
-- `UserPromptSubmit`
-- `PreToolUse`
-- `PostToolUse`
-- `PermissionRequest`
-- `PreCompact`
-- `PostCompact`
-- `Stop`
-- `SubagentStart`
-- `SubagentStop`
+脚本执行 Release archive, Developer ID 导出, 签名验证, 公证, staple 和 Gatekeeper 校验; 默认清理 `build/`, 成功后只保留最终 `.app`; 没有发布凭据时可用 `--skip-notarization`, 但产物不是完整发布包
-每个 Hook 形如:
+### DMG
```bash
-'<当前 CodexBar 可执行文件路径>' --hook-event
+Scripts/dmg.sh [App.app] [Output.dmg]
```
-Hook 事件定义集中在 `CodexHookEvent`:
-
-- `configName`: 写入 `hooks.json` 使用, 例如 `SessionStart`
-- `appServerName`: 验证 `hooks/list` 使用, 例如 `sessionStart`
-- `init(eventName:)`: 统计 events 使用, 会把 `PreToolUse`, `pre_tool_use`, `pre-tool-use` 归一化到同一事件
-
-识别和移除当前 CodexBar Hook 时必须同时满足:
-
-- handler 是 JSON 对象
-- `type == "command"`
-- `command` 同时包含当前 App 可执行路径生成的 shell 命令和 `--hook-event` 参数
-
-这意味着:
-
-- 用户已有 Hook 会被保留
-- 其他 App Hook 会被保留
-- 同一事件下其他 Hook 会被保留
-- 如果用户自定义 Hook 命令中也同时包含当前 CodexBar 可执行路径和 `--hook-event` 参数, 会被当作当前 CodexBar Hook 删除
-
-检测是否已开启时, 只要任意 CodexBar 事件存在当前 App 路径对应的 handler, 开关就保持开启。缺少部分事件时, `hooks/list` 验证会在 Hook 选项下方显示"CodexBar Hook 已不完整"。
-
-## 11. Hook 事件写入流程
+脚本复制 App, 创建 Applications 别名, 写入 Finder 布局, 并输出压缩 DMG; 默认文件名包含 `MARKETING_VERSION`
-Hook 子进程写入路径追求轻量, 避免超过 Codex Hook timeout
+### Sparkle appcast
-```mermaid
-sequenceDiagram
- participant Codex as Codex
- participant App as Hook 记录进程
- participant Recorder as 事件记录器
- participant Lock as 写入锁
- participant Events as 当天事件日志
- participant State as 维护状态文件
-
- Codex->>App: 执行 Hook 命令并传入事件内容
- App->>Recorder: 进入快速记录分支
- Recorder->>Recorder: 解析事件名和顶层字段
- opt Prompt 或权限请求
- Recorder->>Recorder: 从 transcript 尾部提取当前 turn reviewer
- end
- Recorder->>Lock: 获取独占锁
- Recorder->>Events: 追加一行事件 JSONL
- Recorder->>State: 标记当天等待维护
- Recorder->>Lock: 释放独占锁
- App-->>Codex: 正常退出
+```bash
+Scripts/appcast.sh [CodexBar-vX.Y.Z.dmg]
```
-读取字段:
-
-| Hook payload 字段 | 写入字段 |
-| ----------------- | ----------------------------------------------- |
-| `timestamp` | `timestamp`, 本机时间 `yyyy-MM-dd HH:mm:ss.SSS` |
-| `hook_event_name` | `event` |
-| `cwd` | `cwd` |
-| `tool_name` | `tool` |
-| `model` | `model` |
-| `permission_mode` | `permission` |
-| `transcript_path` | `approval`、`effort`;仅提取匹配 turn 的上下文 |
-| `session_id` | `session` |
-| `turn_id` | `turn` |
-| `agent_id` | `agent` |
-
-`hook_event_name` 是 Hook 事件来源。如果 stdin 有输入但缺失事件名, 记录器会吞掉本次 Hook, 避免 Hook 子进程启动完整菜单栏 App。
-
-除 `hook_event_name` 外, 缺失字段不阻断写入:
-
-- `timestamp` 缺失或无法解析时使用当前时间
-- `cwd` 缺失时使用当前工作目录
-- `transcript_path` 缺失、无法读取或 512 KB 内找不到匹配 `turn_context` 时,`approval` 和 `effort` 写为 `null`;reviewer 未知时 `approval` 写为 `null`。主 App 仍会通过 rollout reader 尝试补齐,未补齐 reviewer 前不判定为用户等待
-- 其他字段缺失写为 `null`
-
-Hook 数据目录:
+脚本读取 `MARKETING_VERSION` 和 `CURRENT_PROJECT_VERSION`, 调用 Sparkle `sign_update`, 在 `appcast.xml` 顶部写入当前版本条目, 并校验 XML; 默认下载地址和发布说明地址来自脚本环境变量
-```text
-~/Library/Application Support/CodexBar/HookEvents/
-```
+### Helper 清理
-文件职责:
-
-| 文件 | 职责 |
-| ------------------------- | ------------------------------------------------------------ |
-| `events/YYYY-MM-DD.jsonl` | 按本机日期拆分的原始 Hook 事件 |
-| `daily.jsonl` | 每日聚合结果, UI 优先读取 |
-| `stats.lock` | `flock` 锁文件 |
-| `maintenance.json` | pending、dirty、offset、来源 generation 和文件连续性校验状态 |
-
-## 12. Workflow 维护与聚合流程
-
-`WorkflowViewModel` 刷新规则:
-
-- `refreshIfNeeded()` 只负责普通 UI 读取, 至少间隔 5 秒
-- 打开菜单面板时如果 Hook 开启, 只读取现有 `daily.jsonl` 和同步缓存, 不维护, 不联网
-- app-server 自动刷新倒计时重置时, 如果 Hook 开启, 通过 `WorkflowSyncScheduler.requestMaintenance(allowsSync: true)` 请求一次维护
-- 同步开关开启、Hook 重新开启或同步账号恢复可用时, 通过 `WorkflowSyncScheduler.requestSync()` 请求一次同步维护
-- `WorkflowSyncScheduler` 是维护、同步和显式重建的唯一调度者, 负责运行中、待补跑、冷却窗口和最终状态校验
-- `WorkflowViewModel.refreshMaintenance(synchronize:)` 只取消普通读取并执行一次明确的 `WorkflowService.loadSnapshot(performMaintenance: true, synchronize: ...)`, 运行和排队状态由调度器管理
-- 设置页日期范围批量重建同样通过 `WorkflowSyncScheduler` 排队, 首次点击确定起点, 第二次点击确定终点且允许跨月, 两次点击同一天时形成单日范围; 保留窗口内的日期均可选择, 本机非空事件日期以圆点标记, 提交时只筛选范围内本机非空的分日事件文件, 逐日从头生成新的本地 generation, 并批量持久化当前设备对应日期的待云端替换状态
-- 已有维护或同步先完成再执行重建; 重建期间新增的本机维护和同步请求分别合并, 整批重建结束后由调度器继续处理, 不与重建并发读写工作流状态
-
-维护流程在 `WorkflowService` actor 内串行执行
-
-```mermaid
-flowchart TD
- Start["刷新工作流统计"] --> Maintenance{"是否执行维护"}
- Maintenance -- "否" --> LoadDaily["读取每日聚合"]
- Maintenance -- "是" --> Prepare["准备维护任务"]
- Prepare --> Lock1["短暂持锁读取并修正维护状态"]
- Lock1 --> Tasks{"有任务?"}
- Tasks -- "否" --> LoadDaily
- Tasks -- "是" --> Build["按待重建或待增量日期构建当天聚合"]
- Build --> ReadEvents["从原始事件增量读取"]
- ReadEvents --> Aggregate["记录事件计数, 去重 ID, 项目计数"]
- Aggregate --> WriteDaily["锁外原子写回每日聚合"]
- WriteDaily --> Lock2["短暂持锁提交维护状态"]
- Lock2 --> Prune["清理 210 天外原始事件"]
- Prune --> LoadDaily
- LoadDaily --> Snapshot["生成工作流统计快照"]
+```bash
+Scripts/cleanup.swift [options]
```
-任务类型:
-
-| 类型 | 触发条件 | 读取方式 |
-| ------- | ------------------------------------------------------------------------ | ------------------------------- |
-| dirty | schema 变化、daily 缺失或坏行、events 来源 generation 或文件连续性不一致 | 从当天 events 文件开头重建 |
-| pending | Hook 新增事件或 events 文件变大 | 从 `days[date].offset` 增量读取 |
-
-同一维护批次只读取一次现有 `daily.jsonl`,随后让所有 dirty/pending 日期任务共享并逐步更新同一份内存聚合集合;每次落盘前仍对整份集合执行当前保留策略的归一化。批次没有写入时,服务用文件 size、identifier 和当天日期键组成的进程内 stamp 跳过未变化文件的重复全量解码;日期跨天或文件发生变化后会重新检查并在需要时原子改写。
-
-事件文件发现以当前实际存在的 `events/YYYY-MM-DD.jsonl` 为准。物理删除历史 events 文件不会删除已有 daily 行,也不会单独切换 generation;如果 daily 行也不存在,开启同步时快照可回退到当前 cache 中的云端贡献。仍存在的文件被清空、截断、替换 inode 或边界内容变化时,维护才会按连续性校验切换 generation 并重建。
-
-聚合规则:
-
-- 事件名先去掉 `_` 和 `-`, 再转小写
-- `sessionStartCount`, `stopCount`, `preToolUseCount` 等按归一化事件名增加
-- 任意有效事件中的非空 `model` 按模型名累加到 `modelCounts`
-- 最近 3 个本地自然日只持久化非空 `sessionIds` 和 `turnIds`, 用于继续去重
-- 新建聚合的 ID 数组从 `[]` 开始;聚合结束后仍为空时规范化为 `nil`,只有非空 ID 数组会持久化
-- 3 天前把 ID 集合压缩为 `sessionCount` 和 `turnCount`, 随后移除 ID 列表
-- 压缩和展示时只有正数 count 或非空 ID 集合可以优先于起止事件计数;空 ID 数组以及与正数起止事件冲突的零 count 按缺失处理
-- 本机聚合和同步聚合共享 `WorkflowCountResolution`; 同步聚合不含 ID,因此直接按正数 count、起止事件计数的顺序解析
-- 最多保留最近 210 天数据
-- 210 天外的 `events/YYYY-MM-DD.jsonl` 在主 App 维护流程中删除
-- 坏 JSONL 行跳过并计入 `corrupt`, 不阻断整天聚合
-
-UI 展示指标来自 `WorkflowDailyAggregate.metrics`:
-
-| UI 字段 | 生成规则 |
-| ---------- | ------------------------------------------------------------------------------- |
-| 会话总数 | 正数 `sessionCount`,否则非空 `sessionIds` 的去重数量,否则 `sessionStartCount` |
-| 对话轮次 | 正数 `turnCount`,否则非空 `turnIds` 的去重数量,否则 `stopCount` |
-| 子智能体 | `max(subagentStartCount, subagentStopCount)` |
-| 调用工具 | `max(preToolUseCount, postToolUseCount)` |
-| 权限请求 | `permissionRequestCount` |
-| 上下文压缩 | `max(preCompactCount, postCompactCount)` |
-| 最热模型 | 合并 `modelCounts` 后取计数最高的模型, 并列时按名称升序 |
-
-跨设备同步只在 `performMaintenance: true, synchronize: true` 的刷新中执行。`WorkflowSyncScheduler` 会合并同步开关、Hook 重新开启、同步账号恢复可用和自动刷新产生的同步请求;同步中不取消重启, 冷却窗口内只保留一次待补跑请求, 补跑前重新校验 Hook 开启、跨设备同步偏好为 true 且同步账号可用。`WorkflowSyncService` 先用本机 daily 聚合生成脱敏 `WorkflowSyncedDailyAggregate`, 保留 `sourceGeneration`、`projectCounts` 和 `modelCounts`, 再为保留窗口内的全部本机日期计算稳定 hash、按日期稳定排序候选项, 每批最多上传 25 天, 每轮最多使用 20 秒。zone 存在性确认和 account salt 首次成功后在 actor 内跨轮缓存, 任一轮同步失败时作废, 下一轮重新确认(覆盖 iCloud 账号切换)。同步先刷新一次 CloudKit 缓存再决定上传:只在当前 `deviceId`、当前待上传日期内查找本机副本;同 generation 复用现有记录并按 `eventCount` 防倒退;没有 generation 的记录必须与本机全部同步业务字段完全一致才会被认作同一来源,即使两边 generation 都是 `nil` 也不能跳过内容比较;确认从空文件开始的新 generation 使用独立记录;来源不明确的非空替换在已有云端贡献时只确认保留云端,不自动上传为新贡献。每批处理后立即保存已经上传或确认保留的 `state.hashByDate`; 只有实际上传时更新 `lastUploadAt`, 未完成的 backfill 留给后续自动刷新继续。上传后再次拉取 CloudKit 变化。没有 `cursor.data` 时先 query 全量 `CodexBarDailyAggregate` 回填 `cache.jsonl`; 有游标时优先拉 CloudKit 增量, 游标失效或增量失败时不写入日志窗口, 直接全量重建缓存。删除变化只移除 cache 记录,不清除已确认 hash,所以外部删除不会在本机 daily 未变化时立即回传。每天清理当前设备过期记录时,CloudKit 只按 `deviceId` 等值查询并只返回 `date` 字段;合法日期的保留窗口比较在本地完成,缺失或格式非法的当前设备记录作为异常记录删除。`cache.jsonl` 按 record name 保存所有设备和 generation 的记录;展示时当前本机 generation 与同 generation 云端副本按 `eventCount` 择优,确认独立的其他 generation 与其他设备记录继续累加;来源不明确的替换继续使用已有云端记录。增量路径先写 `cache.jsonl`, 成功后再写 `cursor.data`, 避免游标提前推进导致未落盘记录被跳过。同步失败会通过 `CodexBar.workflowSyncDidFinish` 通知发送 `didSucceed=false` 和归类后的 `failureMessage`, 主面板同步图标进入失败态。
-
-显式日期重建完成后, `WorkflowSyncService` 把实际重建日期写入 `state.replacementDates`, 清除对应日期的确认 hash, 并在快照合并时忽略当前设备这些日期的旧缓存。同步可用时先全量重建 CloudKit 缓存, 再分批删除当前设备对应日期的 legacy 和全部 generation 记录; 删除成功或返回 `unknownItem` 后从本地 cache 移除旧记录, 随后按正常上传流程写入本机新 generation。日期只有在新记录确认后才从 `replacementDates` 移除; 删除、上传或同步中途失败时保留请求并在后续同步幂等重试。其他设备和范围外日期不参与替换。
-
-当前代码写入的 CloudKit `schemaVersion` 是 `4`, 本地同步 state schema 是 `4`,本地工作流维护 state schema 也是 `4`。同步 state 无法按当前 schema 使用时会重建并重新同步。daily 或 CloudKit 记录没有 `sourceGeneration` 时仍可读取;只有其全部同步业务字段与当前本机聚合一致时,才会认作同一 generation。
-
-CloudKit Production schema 必须包含当前 schema `4` 使用的字段;schema 变化需要通过 CloudKit Dashboard 从 Development 部署到 Production,运行时代码不会代替发布流程执行部署。
-
-## 13. 设置窗口流程
-
-设置窗口由 `SettingsWindowController` 打开, 内容是 `AppSettingsView`
-
-`SettingsWindowController.open()` 每次打开设置窗口时刷新:
-
-- `CodexHookSettings.refresh()`
-- `CodexHookSettings.verifyInstalledHooks()`
-- `CodexCLINotificationSettings.refresh()`
-- `WorkflowSyncSettings.refresh()`
-- `MenuBarQuotaSettings.refresh()`
-- `MainPanelSettings.refresh()`
-- `KeepAliveController.refresh()`
-
-设置窗口内容宽度固定为 430 pt, 外层四周以及分页栏与内容卡片之间统一使用 12 pt 间距。当前分页通过 `SettingsPageHeightPreferenceKey` 回报实际内容高度, 窗口按「顶部间距 + 分页栏 + 中间间距 + 页面内容 + 底部间距」计算目标高度, 不再为各分页维护容易产生不等留白的固定高度; 超过 500 pt 或屏幕安全上限时由共享纵向 `ScrollView` 承接。Hosting controller 关闭 `preferredContentSize` 自动联动, SwiftUI 根视图始终贴住窗口顶部, 由 `SettingsWindowController` 统一控制窗口高度和底边。初次打开时控制器按最大视口高度预留居中位置; 切换分页固定标题栏和左上角且不使用窗口缩放动画, 旧页面立即替换, 只让新内容区从轻微缩小和下移状态通过弹簧动画回到原位, 避免过渡期间保留两份页面造成内容重叠; 顶部分页栏不参与布局动画。同时保留可见区域约束作为异常屏幕尺寸的兜底。`MenuBarQuotaSettings.refresh()` 可能被设置页 `onAppear` 和 `didBecomeActive` 调用, 发布 `selection` 时需要延后到下一轮 MainActor, 避免在 SwiftUI view update 中同步发布造成未定义布局行为。
-
-`AppSettingsView.onAppear` 时刷新:
-
-- `LoginItemSettings.refresh()`
-- `WorkflowSyncSettings.refresh()`
-- `MenuBarQuotaSettings.refresh()`
-- `MainPanelSettings.refresh()`
-- `AppUpdater.refreshAutomaticCheckSetting()`
-- `CodexCLIVersionViewModel.refresh()`
-- `CodexStatusViewModel.refreshCodexConnectionInfo()`
-- `NotificationSettings.refreshAuthorizationStatus()`
-- `KeepAliveController.refresh()`
-- `WorkflowStorage.rebuildableEventDateKeys()`
-
-App 再次成为 active 时, 也会刷新 Hook、同步、菜单栏额度、主面板、Codex 版本、通知授权、防休眠 helper 状态和可重建日期, 并重新运行 `hooks/list` 验证。`SettingsWindowController.open()` 发布 `.settingsWindowDidOpen` 后, 日期重建范围、确认弹窗和上次结果消息恢复为未选择状态。窗口存活期间保留最后选择的分页; 切换分页时关闭通知选项侧面板。
-
-版本探测内部有 60 秒节流, 避免 `onAppear` 和 `didBecomeActive` 连续触发时重复启动子进程
-
-设置项通过与现有 Liquid Glass 卡片一致的顶部分页栏分为:
-
-- 「通用」: 开机自动启动、自动检查更新、菜单栏额度指示和设置快捷键
-- 「高级」: CodexBar Hook、主面板任务中心、系统通知、阻止系统休眠、跨设备同步和重建数据
-- 「关于」: Codex 版本、CodexBar 版本、检查更新和退出 CodexBar
-
-窗口首次创建时默认进入「通用」, 后续关闭再打开沿用本次 App 运行期间最后选择的分页。检查更新和退出操作只在「关于」底部操作卡片展示。
-
-跨设备同步开启时,状态子行始终保留固定 16 pt 高的单行布局;右侧固定宽度 `ZStack` 让同步时间和 `.mini` 进度指示以交叉淡入淡出切换,不对 AppKit 进度控件应用几何缩放,也不改变该行高度或控件位置。关闭同步后移除整行占位, 让工作流页面回收对应的行内空间。
-
-| 设置项 | 状态源 | 写入行为 |
-| -------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 开机自动启动 | `SMAppService.mainApp.status` | `register()` / `unregister()` |
-| 自动检查更新 | Sparkle updater | 设置 `automaticallyChecksForUpdates` |
-| 菜单栏额度指示 | `MenuBarQuotaSettings.selection` / `MenuBarQuota.lastWindowSelection` | 开关写入 `.off` 或恢复持久化的上次窗口选择, 窗口菜单写入所选窗口并同步记住; 标签优先来自当前账号 Codex limit 返回的额度窗口, 缺失时使用 fallback 标题 |
-| 设置快捷键 | `GlobalHotKeySettings.shortcut` | 写入 `UserDefaults` 并注册 hot key |
-| CodexBar Hook | app-server `config/read` / `hooks/list` / `config/batchWrite`, `~/.codex/hooks.json` | 检查全局 Hook 开关后追加或移除当前 CodexBar command hook, 并维护对应 `hooks.state` 信任状态 |
-| 主面板任务中心 | `MainPanelSettings.showsTaskCenter` + Codex Hook 状态 | 写入 `MainPanel.showsTaskCenter`; 缺失时默认开启。Hook 关闭时显示为关闭并置灰但保留偏好, 重新开启后恢复 |
-| 系统通知 | `NotificationSettings` + `UNUserNotificationCenter` | 总开关、五类通知子开关、任务触觉开关与阈值写入 `UserDefaults`; 首次开启时请求系统通知授权 |
-| Codex TUI 通知 | `CodexCLINotificationSettings` + app-server `config/read` / `config/batchWrite` | 读取用户级 `[tui].notifications`; 缺失时按开启处理,关闭/开启分别 upsert `false` / `true`,不修改顶层 `notify` |
-| 跨设备同步 | `WorkflowSyncSettings` + CloudKit account status + `WorkflowSyncScheduler` | Hook 开启且同步账号可用时写入 `UserDefaults`; 开启时标记 `needsBackfill` 并请求调度同步 |
-| 阻止系统休眠 | `KeepAliveController` + `CodexActivityMonitor` + `SMAppService` | Hook 开启时允许写入 `KeepAlive.isEnabled`; 运行任务出现后通过 helper 和 idle sleep assertion 阻止休眠,等待、结束、关闭或到期后恢复 |
-| 重建数据 | `WorkflowStorage.rebuildableEventDateKeys()` + `WorkflowSyncScheduler` | 选择最近 210 天内的日期范围, 将范围内非空本机事件日期交给调度器逐日重建, 并登记当前设备对应日期的待云端替换状态 |
-| Codex 版本 | `CodexCLIVersionSnapshot` + 当前 app-server 握手信息 | 路径点击复制到剪贴板 |
-| CodexBar 版本 | Bundle + AppUpdater 状态 | 有更新状态时优先显示动态消息 |
-
-错误显示:
-
-- 开机启动失败显示在设置组与底部按钮组之间的独立错误组
-- Hook 设置失败, 全局禁用, 自动信任写入失败或验证异常显示在 Hook 选项下方
-- 同步账号不可用时显示在跨设备同步开关下方
-- 防休眠依赖、helper 授权、注册状态、当前休眠状态和切换错误显示在阻止系统休眠开关下方
-- 同步运行失败不在设置页展示原始错误; 主面板同步图标 tooltip 显示归类后的短错误
-- 重建行始终保留一行消息位置: 未选择时显示「未选择重建日期范围」, 只选择起点时显示「选择结束日期」, 范围完成且存在数据时显示完整日历范围的「已选择 X 天」, 范围内没有非空事件文件时显示「没有可重建的本地数据」; 完成或失败后改为对应结果消息
-- 没有登录项错误时不渲染错误组
-- 快捷键无法识别, 规则不合法或注册冲突显示在快捷键行内
-- 更新检查状态显示在 CodexBar 版本行
-- Hook 开关下方只在必要时展示错误, 不展示辅助说明、启用或关闭状态文案
-
-## 14. Codex CLI 解析与版本探测
-
-`CodexCLIResolver` 同时服务于 app-server 启动和版本探测
-
-安装源模型:
-
-- `.global`: PATH 中真实全局 `codex`
-- `.bundled`: `/Applications/ChatGPT.app/Contents/Resources/codex`、`/Applications/Codex.app/Contents/Resources/codex` 或等价路径, ChatGPT.app 优先
-
-`CodexCLIInstallations.activeSource` 与启动优先级一致: 全局优先, 内置回退
-
-`CodexCLIVersionService` 的版本探测:
-
-- `CodexCLIVersionService` 是 actor, 对外提供 async 快照 API
-- 先解析安装源
-- 全局和内置版本探测用 `async let` 并发启动, 再收集结果, 避免两个 5 秒超时串行叠加
-- 每个探测运行 `codex --version`
-- stdout 和 stderr 都通过 `PipeReadBuffer` 收集, 最多各 64 KiB
-- 进程结束由 `ProcessExitWaiter` 用 continuation 异步等待, Task 取消或超时都会恢复等待方
-- 进程超时时先 terminate, 再 SIGKILL
-- 第一行中第一个以数字开头的 token 作为显示版本
-
-`CodexCLIVersionDisplay` 合并磁盘探测结果和当前 app-server 连接信息:
-
-- 当前运行来源优先显示 app-server `initialize` 握手里的版本
-- 非当前来源显示磁盘探测版本
-- 当前运行版本低于磁盘安装版本时, 显示"已更新至 <version>"
-- 路径点击复制到剪贴板, 1.5 秒后恢复路径显示
-
-## 15. Sparkle 更新流程
-
-`AppUpdater` 是 `@MainActor ObservableObject`
-
-初始化时先检查 Bundle 中的 Sparkle 配置:
-
-- `SUFeedURL` 必须是 http 或 https
-- `SUPublicEDKey` 必须非空
-
-配置不可用时:
-
-- 不创建 `SPUStandardUpdaterController`
-- `canConfigureAutomaticChecks == false`
-- 手动检查或启动更新显示"未配置更新资源"
-
-配置可用时:
-
-- 创建 `SPUStandardUpdaterController(startingUpdater: true, updaterDelegate: self, userDriverDelegate: nil)`
-- 从 updater 读取自动检查设置
-
-手动检查:
-
-- `checkForUpdates()` 设置 `isManualCheckInProgress = true`
-- 设置页显示"正在检查更新"
-- 调用 `checkForUpdateInformation()`
-- delegate 回调发现新版时设置 `availableUpdateMessage`, 手动检查时同时保持设置页消息
-- 没有新版时显示"没有可用更新"1 秒
-- 失败时显示"检查更新失败"
-
-被动发现新版:
-
-- 自动检查发现新版时设置 `panelUpdateMessage`
-- 菜单面板底部更新时间行显示该消息
-- 双击消息调用 `startUpdate()`, 激活 App 并打开 Sparkle 更新流程
-
-## 16. 日志窗口流程
-
-日志窗口由右键菜单"日志"打开, 内容是 `LogView(store: RequestLogStore.shared)`
-
-展示规则:
-
-- 顶部显示标题和当前日志条数
-- "清空"按钮调用 `RequestLogStore.clear()`
-- 空状态显示"暂无日志"
-- 有日志时使用 `ScrollView + LazyVStack`, 最新日志在前
-- 每行默认显示时间, 状态标签, method 或无 method 记录的详情预览
-- 点击行展开请求和响应或错误详情; 展开正文限制为单行预览, 非空内容通过标题行的预览和复制查看或复制完整内容
-- 预览视图使用可滚动代码视图, 对 JSON 做格式化和高亮
-- 详情文本开启 `.textSelection(.enabled)`
-
-日志窗口只记录 app-server 请求和 app-server 生命周期错误;`RequestLogStore` 只负责把这些记录发布给 SwiftUI。
-
-为了保护隐私, 不直接展示 app-server stderr 或 Codex auth 文件内容。app-server 请求、响应和错误详情会完整保留在 `RequestLogEntry` 中, UI 默认只渲染预览以避免大文本拖慢日志窗口。
-
-## 17. 发布脚本流程
-
-发布脚本位于 `Scripts/`, 修改后至少运行 shell 语法检查
-
-`Scripts/build.sh [options] [Output.app]`:
-
-- 使用 `xcodebuild archive` 生成 Release archive, 默认路径为 `build/CodexBar.xcarchive`
-- 构建参数统一使用命令行 options; 运行 `Scripts/build.sh --help` 查看完整参数
-- 每次运行前先清理 `build/` 目录, 只允许清理项目目录内的 build 路径或 `/private/tmp/` 下路径
-- 使用 `developer-id` export options 导出 App; 未传 `--export-options` 时临时生成
-- 默认通过 `-allowProvisioningUpdates` 允许自动签名补齐 provisioning, 可用 `--no-provisioning-updates` 关闭
-- notary 凭据优先使用 `--notary-profile`; 未设置时使用 `--apple-id`、`--notary-password` 和 `--team-id`; 如果两组参数同时提供, `--notary-profile` 生效, Apple ID 三件套会被忽略
-- 将导出的 App 压缩后提交 `xcrun notarytool submit --wait`, 成功后对 App 执行 `stapler staple` 和 `stapler validate`
-- 通过 `codesign --verify --deep --strict` 校验导出 App 和最终 App; 默认额外执行 `spctl --assess`
-- 成功后把最终 App 写入 `build/CodexBar.app` 或传入的 `Output.app`; 失败时默认不产出最终 App,自定义 build 外输出路径不替换既有 App
-- 最终 App 校验通过后清理 `build/` 下的 archive、DerivedData 等中间产物, 默认只保留 `build/CodexBar.app`; 如果构建或 notary 失败, 保留中间产物便于排查
-- 可用 `--skip-notarization` 只执行 archive/export/signature verify, 便于本地调试脚本
-
-`Scripts/dmg.sh [App.app] [Output.dmg]`:
-
-- 解析 App 路径, 未指定时从 `build/` 查找唯一 `.app`
-- 读取 `MARKETING_VERSION`, 优先从 Xcode build settings 读取, 失败后回退 `project.pbxproj` 和 App `Info.plist`
-- 准备临时 staging 目录, 复制 `.app`, 挂载后通过 Finder 创建 `/Applications` alias
-- 创建可写 DMG
-- 挂载 DMG 并用 AppleScript 写 Finder icon view 布局
-- 压缩为最终 UDZO DMG; 未指定输出路径时写入 `build/CodexBar-vX.Y.Z.dmg`
-
-`Scripts/appcast.sh [CodexBar-vX.Y.Z.dmg]`:
-
-- 解析 DMG, appcast, 下载地址, release notes 地址和 Xcode 工程; 未指定 DMG 时从 `build/` 查找唯一 `.dmg`
-- 读取 Release 配置中的 `MARKETING_VERSION`, `CURRENT_PROJECT_VERSION` 和 `PRODUCT_NAME`
-- 查找 Sparkle `sign_update`
-- 对 DMG 签名并解析 `sparkle:edSignature` 和长度
-- 生成新的 appcast `<item>`
-- 移除同 build version 旧 item, 再插入新 item
-- 如果存在 `xmllint`, 校验 appcast XML
-
-## 18. 并发, 隔离与文件安全
-
-主要并发边界:
-
-| 模块 | 并发策略 |
-| --------------------------------- | ------------------------------------------------------------------------ |
-| UI, 控制器, ViewModel, 设置, 更新 | `@MainActor` |
-| `CodexStatusService` | actor 隔离 app-server 连接、缓存和重建状态 |
-| `CodexCLIVersionService` | actor + `async let` 并发探测版本 |
-| `WorkflowService` | actor 串行维护 daily 聚合和快照读取 |
-| `RequestLogStorage` | `OSAllocatedUnfairLock` 保护后台同步写入 |
-| `RequestLogStore` | `@MainActor ObservableObject` 发布日志快照 |
-| Hook 写入 | `stats.lock` + `flock(LOCK_EX)` |
-| app-server stdout/stderr | `JSONLineReader` / `PipeDrain` 复用 `PipeReadBuffer` |
-| 版本探测输出 | `PipeReadBuffer` 收集 stdout/stderr, 进程退出由 `ProcessExitWaiter` 等待 |
-
-文件写入安全:
-
-- 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`
-- `CodexCLINotificationSettings` 通过同一 app-server 会话读取有效 `tui.notifications`,并用 `config/batchWrite` 只 upsert 该布尔值;不直接重写 `config.toml`,也不修改顶层 `notify`
-
-隐私和敏感信息边界:
-
-- 不展示 app-server stderr
-- 不展示 Codex OAuth token 或 `auth.json` 内容; 只用 access token 发起 `rate-limit-reset-credits` 只读请求, 丢弃原始响应, 只保留可用且未过期的过期时间数组
-- 不把原始敏感 RPC 响应写入文档或测试夹具
-- 日志完整保存 request/detail, UI 默认只渲染单行预览; 完整内容通过标题行预览或复制查看
-- Hook 统计默认只保存在用户 Application Support 的 CodexBar 目录;开启「跨设备同步」后, CloudKit 只保存去掉 `sourceIsFresh`、`sessionIds` 和 `turnIds` 的 daily 聚合副本,以及用于区分独立数据段的随机 `sourceGeneration`,不保存原始 Hook events、文件 inode 或边界 hash
-- 实时任务状态只保存在 `CodexActivityMonitor` 内存中,UI 只展示项目最后一级名称、模型、推理强度、工具名与最近 Hook 事件类型;活动卡片第一行以 `•` 组合模型、推理强度和项目,第二行组合运行时间、可靠且大于 0 的活跃子 Agent 数量与请求/工具/压缩/子智能体状态,其他任务数使用右侧 `+N` 徽标。并发任务中心消费同一快照中的完整等待、运行、最近完成和最近终止列表,在模型后以 `•` 展示推理强度,但不展示子 Agent 数量;列表身份使用进程内 UUID,不展示或持久化 session/turn/agent ID。不写历史文件、不上传 CloudKit,也不新增网络请求。`CodexSessionLifecycleReader` 只对活跃 session + turn 读取本机 rollout,提取事件类型、turn ID、起止时间、耗时、审批 reviewer 和推理强度;不提取、保存或展示提示词、回复、推理内容、工具内容、审批内容或 token 数据
-
-## 19. 通知与触觉提醒链路
-
-通知与触觉反馈判定在 `CodexBar/Services/Notifications/`, 偏好类随其他设置类放在 `CodexBar/Services/Settings/`:
-
-- `NotificationSettings` (`Services/Settings/`): 总开关、五类通知子开关及各自的声音、任务触觉开关、低额度阈值 (5%/10%/25%, 默认 10%) 和长任务时长 (30s/1m/2m/5m, 默认 1m), 持久化到 UserDefaults; 负责系统授权请求、被拒状态镜像和设置页选项面板可展示状态
-- `NotificationSoundOption`: 定义默认、静音、14 个经典提示音和 17 个现代提示音;非静音选项统一生成 `UNNotificationSound` 并为设置页提供同源 WAV 试听资源
-- `CodexCLINotificationSettings` (`Services/Settings/`): 通过 app-server 读取和写入用户级 `tui.notifications`; 支持解析布尔值与事件数组,缺失时按默认开启,写入后回读验证并把错误显示在通知选项行
-- `CodexNotificationService`: 集中判定、去重、调度与发送; 由 `CodexBarAppDelegate` 创建, 订阅 `CodexStatusViewModel.$snapshot`、`CodexActivityMonitor` live transition 与 `NSWorkspace.didWakeNotification`; 五类正式通知共用 `CodexNotificationContent` 文案工厂并按类型附加用户选择的声音,系统提交失败时重试一次,等待与完成 transition 还会按偏好请求 AppKit `.levelChange` 触觉反馈
-- `CodexActivityMonitor`: Hook 开启期间始终运行并维护并发任务;向 UI 发布快照,向提醒服务发布 live transition。`PermissionRequest` 先作为审批候选,只有同 turn 的 rollout reviewer 为 `user` 才确认等待;自动 reviewer 或未知 reviewer 保持运行。单个 live 批次先完整应用事件,再按任务键合并已确认的等待候选;只有批次结束后仍处于等待的任务会使用最终快照发布一次等待 transition,完成候选保持顺序并按 completion ID 做批内去重。通知与触觉开关不会停止活动监测
-- `HookEventTailReader` (`Services/Workflow/`): 后台 actor;bootstrap 以 512 KB 为单次分块流式读取滚动 24 小时事件,并用 start/events/end 三阶段恢复状态。当前文件用 inode + 完整行 offset 固定 bootstrap/live 边界;bootstrap 结束后 monitor 再发起一次定向回溯,为缺少起点的精确 turn 向旧日期文件最多回读 8 MB。之后每 2 秒 tail 当日增量,保留半行、跨日先读旧文件尾部;live 每成功处理一个分块就推进到最后完整行 offset,后续分块失败只重试未处理部分。旧文件异常触发 bootstrap 时保留 bootstrap 设置的新日期 offset,临时读取失败则保留旧日期等待下轮重试。bootstrap、定时轮询和 Mac 唤醒补读共用串行入口,读取期间到达的请求合并为当前读取结束后的一次补读;monitor generation 会丢弃停用 reader 的迟到批次
-- `CodexSessionLifecycleReader`: 后台 actor,只为 monitor 当前活动或等待终态确认的精确 session + turn 定位对应 rollout;便宜目录每 10 秒重试,每个活跃生命周期最多递归 `sessions` 一次并保留负缓存,缓存文件移动、session 重新活跃或 Mac 唤醒时重置。rollout 初次最多读取末尾 512 KB,之后每 1 秒按 offset 增量读取;活跃 turn 的 effort 仍缺失且初始窗口未覆盖完整历史时,在任务开始至少 2 秒后从文件尾部最多 8 MB 定向回查,每轮查询最多处理一个 turn,失败至少间隔 10 秒重试。`task_started` 回填缺失起点,`task_complete` 补齐结束和精确耗时,`turn_aborted` 由 monitor 移除任务并生成灰色最近终止记录,`turn_context.approvals_reviewer` 用于确认 `PermissionRequest` 是否真的路由给用户,`turn_context.effort` 用于回填推理强度。读取失败时不把审批候选误判为等待,也不猜测 effort。同次查询同时包含 reviewer 和终态时,monitor 保留起点回填后优先处理终态并跳过审批候选确认。轮询和即时 lifecycle 查询都绑定 reader generation,跨 actor 返回后仍会复核,旧查询不能落入新 reader 状态
+脚本只注销 CodexBar Debug 和 Release KeepAlive LaunchDaemon, 并关闭对应防休眠偏好; 运行前需要退出所有 CodexBar 实例
-活动并发以 session 为边界:不同 session 可以同时运行;同一 session 的 turn 按顺序执行。收到新的 `UserPromptSubmit` 时,monitor 会让该 session 中更早且缺少结束信号的 turn 立即退出活动列表,但保留为等待终态确认任务并触发一次即时 rollout 查询;5 秒内收到 Hook `Stop`、rollout `task_complete` 或 `turn_aborted` 时按真实终态归类,到期仍无终态才生成灰色最近终止记录。子 Agent 事件只能通过共享 session 关联父任务,早于当前顶层任务可信开始时间的事件会被当作上一 turn 的迟到事件忽略。已完成和已终止任务键分别保留 24 小时 tombstone,避免迟到事件恢复旧任务或误操作同 session 的新 turn。终止不会触发绿色完成状态、长任务通知或完成触觉反馈。Hook `Stop` 与 rollout `task_complete` 均视为完成信号,先到者生效,后到者按任务键和 session 回退键去重;重复完成不会覆盖首次确认结果,也不会缩短去重窗口或再次触发反馈。
-
-设置页交互: 「系统通知」主开关行保留在设置窗口内, 子选项 (五类通知子开关与声音、任务触觉开关、Codex TUI 通知开关及两个阈值 Picker) 在设置窗口右侧的子面板中展开 (`NotificationOptionsPanelController`, 复用 SidePanelSupport 抽屉机制挂在设置窗口上, 内容用常驻 hosting controller + ObservableObject 驱动)。子面板不再读取通知行作为纵向锚点, 初次展开时底边与设置窗口内容区底边对齐。五类通知按需使用双行布局:第一行展示通知名称、可选阈值和开关,阈值 Picker 位于开关前;通知开启且依赖可用时,第二行展示「通知音效」、加宽的声音菜单和独立播放按钮,关闭时整行从布局移除。控制器订阅五类通知开关和 Hook 状态;入场期间暂停 fitting-size 更新,动画完成后重新测量,后续内容变化在 SwiftUI 完成布局后按 fitting size 动画调整面板高度并保持面板底边位置, 只在超过屏幕顶部安全边界时修正位置。菜单顶层提供默认和静音,其他声音按「经典提示音」和「现代提示音」子菜单分组。选择任意声音时立即试听,播放按钮可重复试听当前非静音选项,新的试听会停止上一段自定义声音;默认使用 `NSSound.beep()`, 静音不播放预览且禁用播放按钮,其余声音优先播放 App 包内与正式通知同源的 WAV。选项依次排列为「任务完成通知」「任务等待通知」「额度预警通知」「额度重置通知」「重置临期通知」「任务触觉反馈」和「Codex TUI 通知」。主开关开启后仅在系统授权允许时展开, 首次授权场景会等待授权结果; 点击行内滑杆按钮可手动展开; 设置窗口 resign key/关闭、主开关关闭或授权变为被拒时自动收起。任务完成、任务等待与任务触觉子项在 Hook 未开启时显示为关闭并置灰, 不修改各自持久化偏好及声音, Hook 重新开启后恢复用户原选择。「Codex TUI 通知」与用户级 `[tui] notifications` 联动,面板打开时刷新,写入后回读验证;已有 CLI 会话需重启后生效。该项不服从 CodexBar 通知发送判定,也不修改顶层 `notify`。「主面板任务中心」沿用相同依赖语义;关闭只隐藏活动卡片和任务中心入口,不停止 Monitor、状态点、通知或触觉反馈。授权被拒的引导文案与"打开系统设置"按钮仍内联显示在主开关行下方, 插入提示时不触发设置项纵向动画。
-
-`NotificationOptionsView` 的两个实际行构建器保留 `@_optimize(none)`:Swift 6.3.3 在 `-O` 下优化这些包含原生 mini Switch 的动态布局时会漏绘开关 thumb。该约束只覆盖 `optionRow` 和带 accessory 的 `notificationOptionRow` 实现,其余通知视图与 Release target 继续使用正常优化;调整这两个构建器的编译属性后需要用 Release 产物人工检查开启状态的 thumb。
-
-五类通知的触发与去重:
-
-| 通知 | 触发 | 去重键 |
-| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| 额度低阈值 | 非 stale 快照中窗口剩余比例穿越到 ≤ 阈值; 阈值或子开关变化时用当前快照立即重评估 | `low\|账号\|limitId\|windowId\|resetsAt` |
-| 额度已重置 | 同一账号下每个 limit 的 primary/secondary 窗口独立观察;可信快照中消耗从大于 0% 变为 0% 时立即发送以 `limit.title` 和窗口周期命名的通知 | 进程内按 `账号\|limitId\|windowId` 观察状态转换;成功发送后使用 `quotaReset\|账号\|limitId\|windowId\|resetsAt` 持久化去重 |
-| 长任务完成 | monitor 的 live Hook `Stop` 或 rollout `task_complete` transition 具有精确耗时且耗时 ≥ 阈值 | 状态机按精确任务键对两种完成信号去重 |
-| 任务等待批准 | 同一 turn 的 rollout 明确 `approvals_reviewer == user`,且 monitor 的 live 批次结束后任务仍处于 `waitingApproval`;自动审批不触发;任务离开等待状态后移除对应通知 | 同批次按任务键合并,通知使用 `taskWaiting\|taskUUID` 任务级 identifier |
-| 重置机会临期 | 过期时间距今 ≤ 7 天, 并在过期前 7/6/5/4/3/2/1 天各提醒一次; 正文使用本地时间 `yyyy-MM-dd HH:mm:ss` | `credit\|账号\|过期时间\|提醒档位` |
+## 发布检查
-额度低阈值、额度重置和重置机会通知只在系统成功接收后把去重键写入 UserDefaults (`Notification.sentKeys`),最多保留 300 条。键包含账号维度;额度重置窗口提供 `resetsAt` 时,去重键还包含该时间,缺失时仍发送通知但不生成周期去重键。额度重置观察状态和等待通知跟踪集合保存在当前进程内;通知不按预测时间调度,也不补发已错过的状态转换。可信额度快照持续推进重置观察状态,stale 快照不参与判定;窗口消失时移除对应观察状态,快照为 `nil` 时清空全部观察状态。Hook bootstrap 只恢复任务状态,不发布 transition,因此不产生历史任务通知或触觉反馈。
-
-五类声音分别使用 `Notification.lowQuotaSound`、`Notification.quotaResetSound`、`Notification.longTaskSound`、`Notification.taskWaitingSound` 和 `Notification.creditExpirySound`。偏好缺失或保存值未知时回退到默认,兼容升级前的用户数据;默认提交 `.default`,静音提交 `nil`,其他选项提交 App 包根资源目录中的 `CodexBar-<Name>.wav`,由系统通知中心按系统授权、专注模式和通知设置决定是否实际播放。
-
-「任务触觉反馈」使用 `Notification.taskHapticEnabled` 持久化,缺失时默认开启。等待批准和任意任务完成 transition 都启动一段触觉反馈任务:每 100 ms 请求一次 `.levelChange`,连续 10 次;新 transition 会取消并重启当前序列,开关关闭后会在下一脉冲前停止。触觉反馈不受长任务阈值与系统通知授权影响;App 内「系统通知」总开关关闭时不触发。`NSHapticFeedbackManager.defaultPerformer` 会按当前输入设备、辅助功能与系统偏好决定是否实际反馈及震感强弱。
-
-通知错误处理 (延续"细节不打扰用户"原则, 不写入请求日志窗口):
-
-| 场景 | 行为 |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
-| 系统授权未决定或被拒 | 未决定时等待用户选择,被拒时静默不发并在设置页显示引导 |
-| 当日事件文件临时读取失败 | 提交已处理完整行的 offset,下轮只重试剩余部分 |
-| Hook 或 rollout 单行解码失败 | 跳过坏行并继续处理同批其他完整行,不写入请求日志 |
-| 跨日旧文件临时读取失败 | 暂不切换日期,下一轮继续读取旧尾部;bootstrap 接管时不重放 live |
-| rollout 文件不存在或读取失败 | 保留 Hook 推导的任务状态,不猜测任务已经中断 |
-| 额度快照为空、stale 或窗口消失 | 空快照清空全部待重置窗口;stale 快照不参与转换;可信快照移除已消失窗口 |
-| 系统通知提交失败 | 自动重试一次;最终失败不写去重键,额度通知在后续可信快照中重试;账号或窗口生命周期已变化时丢弃迟到的重置失败回调 |
-| Hook 关闭 | monitor 停止 tail 并清空实时状态 |
-| 通知总开关或任务通知关闭 | 阻止对应通知;额度重置状态仍继续推进但不补发,总开关关闭时也阻止触觉反馈 |
+发布包至少确认
-通知点击通过 `UNUserNotificationCenterDelegate` 回调 `StatusItemController.openMenuSurfaceFromNotification()`, 复用全局快捷键的打开路径 (含 fallback 面板兜底)。
+1. 主 App, helper 和 Sparkle framework 签名有效
+2. App 包内 helper 与 LaunchDaemon plist 路径正确
+3. `Info.plist` 的 Sparkle feed 和公钥有效
+4. CloudKit entitlement 使用 `iCloud.app.zabrian.codexbar`
+5. DMG 可挂载并可将 App 拖入 `/Applications`
+6. appcast 的版本, build, 下载地址, 文件长度和 EdDSA 签名匹配产物
diff --git a/Docs/KeepAlive.md b/Docs/KeepAlive.md
index 44570b1..bbee136 100644
--- a/Docs/KeepAlive.md
+++ b/Docs/KeepAlive.md
@@ -1,94 +1,149 @@
# 阻止系统休眠
-本文档记录设置页「阻止系统休眠」的状态口径、特权边界、恢复路径和打包要求。实现思路参考 [Nemuri](https://github.com/syfssb/nemuri) 的 `pmset disablesleep`、特权 helper 与哨兵/看门狗设计;CodexBar 直接复用自身 Hook 实时状态机,不引入第二套任务检测。
+"阻止系统休眠"根据 Codex Hook 的实时任务状态临时保持 Mac 唤醒; 功能关闭或没有运行任务时, CodexBar 不修改系统休眠策略
-## 用户行为
+## 生效条件
-- 开关默认关闭,偏好键为 `KeepAlive.isEnabled`。
-- 功能依赖 Codex Hook;Hook 关闭后开关会自动关闭、清除开启偏好并恢复休眠,且在 Hook 关闭期间置灰不可操作。重新开启 Hook 后仍保持关闭,由用户决定是否再次开启。
-- 首次开启通过 `SMAppService.daemon(plistName:)` 注册 LaunchDaemon。状态为 `requiresApproval` 时,设置页引导用户打开 macOS「登录项与扩展」。
-- 只有 `CodexActivitySnapshot.runningTasks` 非空时,才同时把 `SleepDisabled` 设为 `1` 并持有 `PreventUserIdleSystemSleep` assertion,覆盖空闲、合盖和手动系统休眠。`waitingTasks`、最近完成、最近终止和空闲都恢复休眠。
-- 并发任务采用 any-running 语义:只要还有一个运行任务就继续保活。
-- 用户可选择最长防休眠期限:1、2、4、8、12、24 小时或无限制,默认 12 小时,偏好键为 `KeepAlive.maximumContinuousDurationSeconds`。有限期限只维护一个计时起点,每个新运行任务第一次出现在实时快照中,或同一任务从 `waitingApproval` 恢复为 `running` 时,都把共享起点更新为当前时间;无限制不创建到期计时器。
-- 达到期限后立即恢复任务开始前的休眠设置;即使旧任务仍在运行,也不会因 App 激活、设置刷新或同一运行阶段内的普通 Hook 活动而重置期限。等待批准后恢复运行属于新的运行阶段,会清除到期状态并获得完整的新期限;多任务场景下,这次恢复也会更新所有运行任务共享的截止时间。到期后改为无限制,或改为按当前起点计算后仍未到期的更长期限,会清除到期状态并继续当前周期。每次 App 成功恢复时,先由 helper 还原 `SleepDisabled`,再释放空闲休眠 assertion,让 macOS 根据当前空闲计时、用户活动、其他 assertion 和电源策略立即重新评估是否应休眠。App 不自行推算空闲期限,也不在开盖时无条件强制休眠。如果 helper 确认恢复结果为 `SleepDisabled=0`,且系统同时确认已经合盖并且合盖应触发休眠,CodexBar 还会主动请求系统休眠。该流程统一覆盖进入等待批准、任务完成或终止、没有活动任务、关闭功能和达到期限等恢复路径,无需记录本轮是否出现过合盖休眠意图。外接显示器合盖模式或原始设置本来就是禁止休眠时不会强制休眠。所有运行和等待任务都从实时快照消失或用户关闭再开启功能也会重置计时状态。
+以下条件必须同时满足
-`PermissionRequest` 本身不是等待用户。`CodexActivityMonitor` 只有在 rollout 确认同 turn 的 `approvals_reviewer == user` 后才把任务移入 `waitingApproval`;`auto_review`、兼容的自动 reviewer 或尚未确认 reviewer 时仍保持运行。因此防休眠与 UI、通知使用同一份已经归一的状态,不直接解释 Hook 事件。
+- CodexBar 正在运行
+- CodexBar Hook 已开启
+- 用户已开启"阻止系统休眠"
+- 至少有一个 Codex 任务处于运行状态
+- CodexBarHelper 已注册并获得系统授权
+- 当前连续防休眠时限尚未到达
-## 为什么不用 caffeinate
+任务等待用户批准时不属于运行状态; 如果同时还有其他任务运行, 防休眠继续生效; 否则立即恢复系统休眠
-`ProcessInfo.beginActivity`、IOKit idle sleep assertion 和 `/usr/bin/caffeinate` 适合阻止空闲休眠,但不能可靠覆盖 MacBook 合盖触发的休眠。合盖继续运行需要系统级 `/usr/bin/pmset -a disablesleep 1`,写入该设置需要 root 权限。CodexBar 同时使用 idle sleep assertion,不是因为 `pmset` 无法禁止空闲休眠,而是为了在 helper 恢复全局设置后通过释放 assertion 触发 macOS 自己重新评估已累计的空闲状态。
+## 最长时限
-CodexBar 使用 macOS 15 可用的 ServiceManagement 新 API。LaunchDaemon plist 位于 App 包的 `Contents/Library/LaunchDaemons/`,helper 位于 `Contents/Resources/`;主 App 不执行 `sudo`,也不持有任意 root 命令能力。
+可选时限为
-## 组件边界
+- 1 小时
+- 2 小时
+- 4 小时
+- 8 小时
+- 12 小时
+- 24 小时
+- 无限制
-| 组件 | 职责 |
-| -------------------------------- | ------------------------------------------------------------------------------- |
-| `KeepAliveController` | MainActor 上订阅活动快照、保存偏好、刷新 `SMAppService.Status`、管理 XPC 和重试 |
-| `SystemSleepService` | 持有/释放空闲休眠 assertion;恢复后读取当前合盖状态,并在满足条件时请求系统休眠 |
-| `Shared/CodexBarHelperXPC.swift` | 从当前 bundle identifier 派生 Mach service 名,并声明恢复时限和唯一 XPC 方法 |
-| `CodexBarHelper` | root 下串行执行固定的 `pmset` 命令、维护哨兵、看门狗和信号恢复 |
-| LaunchDaemon plist | 声明 `BundleProgram`、Mach service、RunAtLoad 和 KeepAlive |
+默认值为 12 小时; 以下事件会重新开始计时
-helper 的 XPC listener 使用代码签名 requirement。它从自身签名动态取得 Team ID,并由 helper identifier 推导对应的 App identifier,只接受两者都匹配的 Apple 签名客户端。对外接口只有:
+- 新任务进入运行状态
+- 等待批准的任务恢复运行
+
+普通工具, 压缩和子 Agent 活动不会延长时限; 到达上限后, 即使任务仍在运行, 也会恢复系统休眠; 后续新任务或等待批准后恢复运行可以开始新的计时周期
+
+## 系统休眠控制
+
+功能生效时, 主 App 同时执行两项操作
+
+1. 创建 `PreventUserIdleSystemSleep` IOKit assertion, 阻止空闲系统休眠
+2. 通过 root helper 执行 `/usr/bin/pmset -a disablesleep 1`
+
+恢复时按相反顺序处理
+
+1. helper 将 `SleepDisabled` 恢复为功能生效前的值
+2. 主 App 释放 IOKit assertion
+3. 如果 MacBook 当前合盖, 系统配置认为合盖应休眠, 且原始 `SleepDisabled` 为关闭状态, 主 App 主动请求一次系统休眠
+
+如果系统在 CodexBar 介入前已经禁用休眠, 恢复时会保留该状态
+
+## Helper 注册
+
+CodexBar 使用 `SMAppService.daemon` 注册随 App 打包的 LaunchDaemon; 首次开启时, macOS 可能要求用户在"系统设置 → 通用 → 登录项与扩展"中允许 CodexBar 后台项目
+
+Release 标识
+
+```text
+App: app.zabrian.codexbar
+Helper: app.zabrian.codexbar.helper
+```
+
+Debug 标识
```text
-setSleepDisabled(Bool)
+App: app.zabrian.codexbar.debug
+Helper: app.zabrian.codexbar.debug.helper
```
-helper 不接受命令、路径或环境变量参数,不访问网络,不读取 Codex 配置、事件或会话内容。唯一写入目录是 root-owned `/Library/Application Support/CodexBar/`;哨兵文件名为当前 Mach service 名加 `.state`,因此 Release 使用 `app.zabrian.codexbar.helper.state`,Debug 使用 `app.zabrian.codexbar.debug.helper.state`。
+App 包内文件位置
-helper 在恢复请求的 XPC reply 中同时返回成功恢复后的 `SleepDisabled` 值。App 收到成功 reply 后释放 idle sleep assertion,无论开盖还是合盖,都由 macOS 先按当前状态重新评估空闲休眠。App 只有确认 `SleepDisabled` 为 `0`,并重新读取到 `AppleClamshellState=true` 与 `AppleClamshellCausesSleep=true` 时才额外主动请求系统休眠。没有哨兵、读取失败、恢复失败或系统状态无法确认都按保守结果处理,不会误触发主动休眠。
+```text
+Contents/Resources/CodexBarHelper
+Contents/Library/LaunchDaemons/<helper bundle id>.plist
+```
+
+CodexBar 会对 helper 可执行文件和 plist 计算指纹; App 更新后指纹变化时, 已注册服务会注销并重新注册, 确保 launchd 使用当前版本
+
+## XPC 边界
+
+主 App 通过 privileged XPC Mach service 调用唯一接口
+
+```swift
+setSleepDisabled(_ disabled: Bool, reply: (Int32, Bool) -> Void)
+```
-## 原始状态与恢复
+helper 只允许与自身相同 Team ID, 且 bundle identifier 为对应 CodexBar App 的已签名客户端连接
-第一次请求关闭休眠时,helper 先用 `pmset -g` 读取 `SleepDisabled`;macOS 未输出该字段时按默认值 `0` 处理。helper 把原始 `0/1` 写入权限为 `0600` 的哨兵,再执行 `pmset -a disablesleep 1`。恢复时写回哨兵保存的原值,成功后才删除哨兵;因此任务开始前已经由用户或其他工具关闭休眠时,CodexBar 不会擅自改成开启休眠。
+helper 的权限范围仅包括
-恢复路径:
+- 读取当前 `SleepDisabled`
+- 执行 `/usr/bin/pmset -a disablesleep 0|1`
+- 在固定目录维护一份恢复哨兵
+- 接受上述 XPC 开关请求
-1. 最后一个运行任务进入等待、完成、终止或消失时,App 立即请求恢复;等待任务恢复运行时把恢复时刻设为新的共享计时起点,并获得完整的新期限。
-2. 达到从最近任务启动起计算的最长防休眠期限时请求恢复。新的运行任务、等待任务恢复运行、所有运行和等待任务都消失后再次出现任务,或用户关闭再开启功能时会开始新一轮。用户改为无限制,或改为按当前起点计算后仍未到期的更长期限,也会继续当前周期。
-3. 关闭功能或正常退出 App 时在可用连接上请求恢复;连接已经断开时释放 App 持有的 assertion,并由下一条兜底恢复全局设置。
-4. 最后一个 XPC 连接断开且哨兵存在时,helper 等待 15 秒后恢复;App 快速重连会取消该次看门狗。
-5. helper 每 60 秒检查一次「没有连接、没有看门狗、仍有哨兵」,用于重试瞬时 `pmset` 失败。
-6. helper 启动发现哨兵,或收到 `SIGTERM` / `SIGINT` 时,立即尝试恢复。
+helper 不提供网络, 任意命令执行或任意文件访问接口
-helper 的所有连接状态、命令与 timer 都在同一串行队列上修改。App 侧为每次 XPC 请求分配 generation,迟到回调不能覆盖后续任务状态;连接中断且目标状态不变时会延迟重连。若功能在断线重连等待期间关闭,App 会取消重连并释放本地 idle sleep assertion,全局 `SleepDisabled` 由 helper 的 15 秒断线看门狗恢复。凡是 App 收到成功的恢复 reply,都会在 `SleepDisabled` 已经还原后释放 idle sleep assertion,由系统重新评估空闲休眠,再检查恢复值与当前合盖状态,并在确认当前合盖应休眠时调用 `IOPMSleepSystem`;helper 在 App 已退出时执行的看门狗或启动恢复仍只负责恢复原设置。App 进程退出时其 assertion 会由系统自动释放,但异常退出路径不保证与 helper 的延迟恢复形成和正常 reply 相同的顺序。
+## 恢复哨兵
-## 打包与发布
+helper 在修改系统设置前, 将原始 `SleepDisabled` 写入
-Xcode 工程包含 `CodexBar` 和 `CodexBarHelper` 两个 target。主 target 显式依赖 helper,并在构建阶段:
+```text
+/Library/Application Support/CodexBar/<helper bundle id>.state
+```
+
+文件内容只能是 `0` 或 `1`; 目录要求由 root 所有且不可由 group 或 other 写入; 哨兵文件权限设置为 `0600`
+
+恢复成功后删除哨兵; 以下路径都会尝试恢复
-- 把 helper 复制和签名到 `Contents/Resources/CodexBarHelper`。
-- Debug 使用 `app.zabrian.codexbar.debug`,并只嵌入 `app.zabrian.codexbar.debug.helper.plist`。
-- Release 使用 `app.zabrian.codexbar`,并只嵌入 `app.zabrian.codexbar.helper.plist`。
+- 主 App 主动请求
+- 最后一个 XPC 连接断开 15 秒后
+- helper 启动时发现遗留哨兵
+- 无连接时每 60 秒检查一次
+- helper 收到 `SIGTERM` 或 `SIGINT`
-Debug 与 Release 使用独立的 App bundle identifier、helper bundle identifier、Mach service、LaunchDaemon label 和哨兵文件,避免开发授权与注册状态相互影响。App 从自身 bundle identifier 加 `.helper` 得到 Mach service 名,helper 直接使用自身 bundle identifier,LaunchDaemon plist 名和哨兵文件名再由该 service 名派生;helper target 的生成式 Info.plist 嵌入可执行文件,保证独立运行时也能取得自身 identifier。helper 启动时从自身代码签名读取 Team ID,并从自身 identifier 的 `.helper` 后缀推导对应的 App identifier,以生成 XPC 客户端签名要求,不在 Swift 源码中硬编码开发团队或 App identifier。由于 `pmset` 修改的是整台 Mac 的全局状态,不要同时运行 Debug 与 Release App 的防休眠功能。
+哨兵损坏或不可读时, helper 按允许休眠恢复, 避免把 `SleepDisabled=1` 长期留在系统中; 哨兵损坏时不会继续执行新的禁用休眠操作
-Apple 要求包含 `SMAppService` LaunchDaemon 的分发 App 正确签名和公证。日常 `xcodebuild ... build` 可验证编译、bundle 结构和开发签名;完整 Developer ID 导出和公证仍走 `Scripts/build.sh`。
+## 故障处理
-App 按固定顺序计算嵌入的 helper 可执行文件与当前构建配置 LaunchDaemon plist 的内容 SHA-256,并记录已注册服务对应的指纹。每次启动都会检查已注册或等待批准的服务,即使「阻止系统休眠」当前关闭;任一文件内容与记录不一致时,App 会等待 `SMAppService.unregister` 完成后重新注册,使服务使用当前 App 包内的 helper 和 plist。功能关闭且服务从未注册时不会主动注册;只有 App 本体变化而这两个嵌入文件内容不变时也不会重复注册。macOS 可能在注销刚完成时短暂拒绝重新注册;App 会先让出一次主线程事件循环,并只对 `SMAppServiceErrorDomain Code=1` 的 `Operation not permitted` 做 0.5、1、2 秒有限退避重试,其他签名、授权或配置错误立即返回。
+主 App 在休眠切换失败后重新建立 XPC 连接并按递增间隔重试, 累计约 8.5 分钟后停止; 重新出现任务状态变化或用户操作后, 可以启动新的切换流程
-`KeepAliveController.stop()` 先把控制器标记为停止,再取消 Helper 注册任务、XPC 重试和最长时限任务。Helper 注册任务会在注销前和注销完成后检查取消状态;只有控制器仍在运行且任务未取消时,才提交 Helper 状态、打开系统设置或重新收敛防休眠。`shouldDisableSleep` 同时要求控制器处于运行状态,因此停止后的异步结果不能重新关闭系统休眠。如果停止发生在旧 Helper 已注销而新 Helper 尚未注册时,下次 App 启动会根据当前偏好和 `SMAppService.Status` 决定是否重新注册。
+设置页可能显示
-开发机需要注销 Debug 和 Release 遗留的 KeepAlive 服务时,先退出所有 CodexBar 实例,再运行 `Scripts/cleanup.swift`。该独立 Swift 脚本为两个构建身份分别创建临时签名 App,并通过 `SMAppService.unregister()` 定向注销 KeepAlive LaunchDaemon;它不会调用 `sfltool resetbtm`,也不会重置其他 App 的后台项目。每个清理目标优先使用对应 App 包内的 Helper;目标包缺少可执行 Helper 时,只回退到同一 Debug 或 Release 构建配置的 Xcode 产物,不跨配置复用 Helper。可先使用 `--dry-run` 检查目标,使用 `--check` 只验证临时 App 的编译与签名,或使用 `--debug-only` / `--release-only` 只处理一个构建身份。清理后对应的 `KeepAlive.isEnabled` 偏好会被设为关闭,避免下次启动立即重新注册。
+- 需要后台项目授权
+- helper 未注册或资源缺失
+- IOKit assertion 创建或释放失败
+- XPC 连接失败
+- `pmset` 执行失败
+- 已达到最长防休眠时限
-`SMAppService.unregister()` 只保证服务不再加载。macOS 的 Background Task Management 数据库可能继续保留已禁用的 App/Helper 历史记录,并在后续系统维护时清除,因此「App 后台活动」中可能暂时仍显示 CodexBar。系统没有公开的按 bundle identifier 立即删除单条 BTM 历史记录的接口;`sudo sfltool resetbtm` 会重置所有第三方 App 的后台项目与授权,不属于本脚本的定向清理范围。
+## 开发与验证
-## 手动验收
+日常构建会把 helper 和对应配置的 LaunchDaemon plist 嵌入 App; 修改相关代码后至少检查
-1. 把签名、公证后的 App 放入 `/Applications`,开启 Codex Hook。
-2. 开启「阻止系统休眠」,按提示允许 CodexBar 后台项目。
-3. 启动任务,确认设置行显示「当前禁止系统休眠」,`pmset -g` 显示 `SleepDisabled 1`。
-4. 让任务进入等待用户批准,确认恢复为任务开始前的值;开盖时将系统空闲休眠设为较短时间,等待空闲期限先在任务运行期间经过,再确认进入等待后释放 assertion、由 macOS 按当前策略休眠;有其他有效 assertion 或近期用户活动时不应被 CodexBar 强制休眠。批准后继续运行时再次关闭休眠,并确认最长防休眠期限从恢复时重新完整计算。
-5. 同时运行两个任务,确认其中一个等待或完成时不会提前恢复,最后一个停止运行后才恢复。
-6. 选择较短期限并保持任务运行至到期,确认设置页提示已达到上限、系统休眠恢复;激活 App、刷新设置或让同一任务产生新 Hook 活动后仍不重新关闭休眠。
-7. 分别验证等待、完成、终止、空闲、关闭功能和到期行为:开盖时由 macOS 按当前空闲计时、其他 assertion 与电源策略决定是否休眠;普通合盖且没有外接显示器时应在恢复后进入休眠;合盖连接外接显示器并处于正常外接屏工作模式时只恢复设置、不主动休眠。
-8. 在开始任务前手动设置 `SleepDisabled=1`,确认到期时恢复原值且不主动休眠;结束后自行恢复测试机原有设置。
-9. 在旧任务仍运行且已经到期时启动新任务,确认立即重新关闭系统休眠并从新任务启动时开始完整的新周期;另行确认到期前启动新任务,以及任一等待任务获批恢复运行,都会把共享截止时间更新为对应启动或恢复时刻加完整期限。
-10. 运行期间关闭 Codex Hook,确认防休眠开关自动关闭并置灰、系统休眠恢复;重新开启 Hook 后确认防休眠开关仍保持关闭。
-11. 保持服务已注册,分别替换 helper 可执行文件内容和当前构建配置的 LaunchDaemon plist 内容,确认下次启动都会刷新注册;关闭「阻止系统休眠」后重复验证,确认仍刷新已注册服务但不关闭系统休眠。仅替换 App 本体且保持这两个文件内容不变时,确认不会重复注册。
-12. 运行期间正常退出与强制终止 CodexBar,确认最多经过看门狗宽限后恢复;另在 helper 刷新注册期间退出,确认停止后不再回写注册状态或重新请求防休眠,并在下次启动时按当前偏好和 `SMAppService.Status` 收敛。
-13. 运行期间终止 helper,确认 launchd 重启后通过哨兵恢复,再由仍活跃的 App 按快照重新收敛。
+1. App 包内 helper 和 plist 路径正确
+2. App, helper 和 XPC 客户端签名匹配
+3. 首次开启可以完成后台项目授权
+4. 运行任务时 `pmset -g` 显示 `SleepDisabled 1`
+5. 等待批准, 任务完成, 关闭 Hook, 关闭功能和达到时限后恢复原值
+6. App 或 XPC 异常退出后, watchdog 或定时检查能够恢复
+7. Debug 和 Release helper 不互相注册
+
+只需要注销 CodexBar 的 KeepAlive LaunchDaemon 时, 可在退出所有 CodexBar 实例后运行
+
+```bash
+Scripts/cleanup.swift
+```
-不要在密闭包内执行合盖验收。该功能会增加耗电和发热,当前不包含低电量自动放行策略。
+使用 `--dry-run` 查看目标, 使用 `--check` 只验证临时清理 App 和签名, 不执行注销
diff --git a/Docs/UserGuide.md b/Docs/UserGuide.md
index b7b33e6..f34bdb1 100644
--- a/Docs/UserGuide.md
+++ b/Docs/UserGuide.md
@@ -1,791 +1,208 @@
# CodexBar 使用指南
-这份指南面向日常使用 CodexBar 的用户。你可以按功能查找需要开启的设置、具体操作、界面状态,以及遇到问题时的处理方法。
-
-## 目录
-
-- [1. 快速开始](#1-快速开始)
-- [2. 入口、快捷键与功能依赖](#2-入口快捷键与功能依赖)
-- [3. 看懂菜单栏图标](#3-看懂菜单栏图标)
-- [4. 账号状态与数据刷新](#4-账号状态与数据刷新)
-- [5. 额度、重置时间与手动重置机会](#5-额度重置时间与手动重置机会)
-- [6. Token 摘要与近 30 周热力图](#6-token-摘要与近-30-周热力图)
-- [7. Codex Hook、活动卡片与任务中心](#7-codex-hook活动卡片与任务中心)
-- [8. 重建工作流统计](#8-重建工作流统计)
-- [9. 跨设备同步](#9-跨设备同步)
-- [10. 系统通知、Codex TUI 通知与触觉反馈](#10-系统通知codex-tui-通知与触觉反馈)
-- [11. 其他设置与全局快捷键](#11-其他设置与全局快捷键)
-- [12. 日志、版本与更新](#12-日志版本与更新)
-- [13. 常见问题速查](#13-常见问题速查)
-- [14. 隐私与数据范围](#14-隐私与数据范围)
-
-## 1. 快速开始
-
-### 使用要求
-
-- macOS 15.0 或更高版本
-- 已安装 Codex CLI 或 Codex App
-- 已在 Codex 中完成登录
+CodexBar 常驻 macOS 菜单栏, 不显示 Dock 图标; 启动后, 菜单栏人物图标是应用的主要入口
-CodexBar 是纯菜单栏 App,不显示 Dock 图标,也没有传统主窗口。启动后请在屏幕顶部菜单栏寻找带对勾的人物图标。
+## 快速开始
-### 第一次使用
+1. 确认本机已安装并登录 Codex CLI, ChatGPT App 或 Codex App
+2. 启动 CodexBar, 左键点击菜单栏图标查看账号, 额度和 Token 用量
+3. 右键点击图标打开设置, 根据需要开启 Codex Hook, 通知, 阻止系统休眠和跨设备同步
-1. 左键点击菜单栏图标,确认账号、额度和 Token 用量能够显示。
-2. 右键点击菜单栏图标,选择「设置」。
-3. 根据需要开启「开机自动启动」和「自动检查更新」。
-4. 如果希望在菜单栏直接看到剩余额度,开启「菜单栏额度指示」并选择额度窗口。
-5. 如果希望查看工作流统计、实时任务或任务提醒,开启「CodexBar Hook」。
-6. 开启 Hook 后,可继续开启「主面板任务中心」「阻止系统休眠」和「跨设备同步」。
-7. 如果希望接收提醒,开启「系统通知」,允许 macOS 通知权限,再打开右侧的通知选项。
+应用要求 macOS 15.0 或更高版本
-如果第一步显示「未登录」或「初始化失败」,先阅读[账号状态与数据刷新](#4-账号状态与数据刷新)。
+## 常用操作
-## 2. 入口、快捷键与功能依赖
+| 操作 | 结果 |
+| --- | --- |
+| 左键点击菜单栏图标 | 打开或关闭主面板 |
+| 右键或 `Control` + 左键点击菜单栏图标 | 打开设置, 日志和退出菜单 |
+| 默认全局快捷键 `⌘⇧W` | 打开或关闭主面板 |
+| `⌘,` | 打开设置窗口 |
+| 主面板打开时按 `⌘L` | 打开 app-server 日志窗口 |
+| 双击账号图标 | 立即刷新数据 |
+| 双击账号邮箱 | 模糊或恢复邮箱显示 |
+| 点击任务卡片 | 打开或关闭任务中心 |
+| 点击"重置次数" | 查看手动重置机会的过期时间 |
+| 悬停热力图日期 | 查看当天详细数据 |
-### 所有常用入口
+点击主面板和侧边面板以外的区域, 或按 `Esc`, 会关闭主面板
-| 位置 | 操作 | 结果 |
-| -------------------------------- | ----------------------------------- | ------------------------------------ |
-| 菜单栏图标 | 左键点击 | 打开或关闭主菜单面板 |
-| 菜单栏图标 | 右键点击,或按住 `Control` 左键点击 | 打开设置、日志和退出菜单 |
-| 任意 App 中 | 按全局快捷键,默认 `⌘⇧W` | 打开或关闭主菜单面板 |
-| 任意位置 | 按 `⌘,` | 打开 CodexBar 设置窗口 |
-| 主菜单面板打开时 | 按 `⌘L` | 关闭菜单面板并打开日志窗口 |
-| 账号卡片人物图标 | 双击 | 立即刷新账号、额度和用量 |
-| 账号邮箱 | 双击 | 模糊或恢复邮箱显示 |
-| 活动卡片 | 单击 | 打开或关闭任务中心 |
-| `重置次数: N` | 单击 | 查看每批手动重置机会的过期时间和数量 |
-| Token 热力图日期方块 | 鼠标悬停 | 查看当天 Token 和工作流统计 |
-| 菜单面板底部 iCloud 图标 | 鼠标悬停 | 查看同步状态或最近同步时间 |
-| 菜单面板底部更新提示 | 双击 | 开始安装可用更新 |
-| 设置中的「系统通知」右侧滑杆图标 | 单击 | 打开通知和触觉选项 |
-| 设置中的 Codex 安装路径 | 单击 | 复制路径,短暂显示「已复制」 |
-| 日志列表中的一行 | 单击 | 展开请求结果或错误摘要 |
-| 日志展开内容 | 点击「预览」或「复制」 | 查看或复制完整内容 |
+## 菜单栏图标
-点击菜单面板和侧边详情面板以外的区域会关闭菜单,这是菜单栏 App 的正常交互。
+人物图标表示账号状态
-### 功能依赖一览
+- 带对勾: 账号数据可用
+- 带叉: 未登录, 初始化失败或当前数据不可用
-| 功能 | 需要开启或满足的条件 |
-| ---------------------- | ---------------------------------------------------- |
-| 账号、额度、Token 用量 | Codex 已安装并登录 |
-| 菜单栏额度指示 | 开启「菜单栏额度指示」,且所选额度窗口有数据 |
-| 工作流统计 | 开启「CodexBar Hook」 |
-| 活动卡片与任务中心 | 开启「CodexBar Hook」和「主面板任务中心」 |
-| 任务状态点 | 开启 Hook,且当前主数据可用 |
-| 阻止系统休眠 | 开启 Hook、对应开关,并允许 CodexBar 后台项目 |
-| 跨设备同步 | 开启 Hook 和「跨设备同步」,并登录可用的 iCloud 账号 |
-| 额度类通知 | 开启「系统通知」、macOS 通知权限和对应通知选项 |
-| 任务类通知 | 在通知条件基础上额外开启 Hook |
-| 任务触觉反馈 | 开启「系统通知」「任务触觉反馈」和 Hook |
-| Codex TUI 通知 | 开启「系统通知」后,从通知选项中配置 |
+开启"菜单栏额度指示"后, 图标左侧显示所选额度窗口的剩余比例; 颜色按剩余额度分档
-## 3. 看懂菜单栏图标
+| 剩余额度 | 颜色 |
+| --- | --- |
+| 80% 及以上 | 绿色 |
+| 60%–79% | 蓝色 |
+| 40%–59% | 黄色 |
+| 20%–39% | 橙色 |
+| 低于 20% | 红色 |
-菜单栏图标同时表达账号、额度和实时任务三类信息。将鼠标停在图标上,可以查看文字摘要。
+开启 Codex Hook 后, 图标右下角可显示任务状态: 橙色表示等待批准, 蓝色表示运行中, 绿色表示刚刚完成; 多个状态同时存在时, 等待批准优先于运行中, 运行中优先于刚完成
-### 人物图标
+将鼠标停在图标上, 可以查看账号异常, 任务状态, 任务时长和所选额度窗口的摘要
-| 图标 | 含义 | 建议操作 |
-| ------------ | ---------------------------------- | ------------------------------------------ |
-| 带对勾的人物 | Codex 账号数据可用 | 正常使用 |
-| 带叉的人物 | 未登录、初始化失败或当前数据不可用 | 打开菜单查看具体状态,再按账号排障步骤处理 |
+## 主面板
-### 左侧额度竖条
+### 账号与刷新
-开启「菜单栏额度指示」后,人物图标左侧会显示所选额度窗口的剩余比例。设置行右侧的下拉菜单可以切换额度窗口。
+账号卡片显示账号邮箱或名称, 订阅类型和刷新状态; CodexBar 默认每 60 秒刷新一次账号, 额度和 Token 用量; 底部圆环显示下一次刷新进度
-| 剩余额度 | 颜色 | 含义 |
-| ---------- | ---- | ---------- |
-| 80% 及以上 | 绿色 | 额度充足 |
-| 60%–79% | 蓝色 | 额度较充足 |
-| 40%–59% | 黄色 | 建议留意 |
-| 20%–39% | 橙色 | 额度较低 |
-| 低于 20% | 红色 | 额度紧张 |
+状态含义
-如果开关已经开启但没有竖条,通常是所选额度窗口暂时没有可用数据。打开设置切换到另一个窗口,或双击账号卡片人物图标刷新。
+- "未登录": 当前 Codex 没有可用登录账号
+- "初始化失败": 无法找到, 启动或连接本机 Codex app-server
+- "暂无数据": 账号有效, 但当前没有额度或用量数据
+- 内容变淡: 当前显示的是前一次成功读取的缓存数据
-### 右下角任务状态点
+### 额度与重置机会
-任务状态点需要开启 Codex Hook。
+每个额度窗口显示名称, 剩余比例和重置时间; 一个账号可以同时返回多个额度限制和多个时间窗口
-| 状态点 | 含义 |
-| -------- | -------------------------------- |
-| 橙色 | 至少有一个任务正在等待用户批准 |
-| 蓝色 | 至少有一个任务正在运行 |
-| 绿色 | 有任务刚刚完成,通常保留约 30 秒 |
-| 无状态点 | 当前空闲,或任务数据暂不可用 |
+账号存在可用的手动重置机会时, 额度区会显示"重置次数"; 侧边面板按过期时间汇总这些机会; 查询不到过期时间时仍保留可用次数; CodexBar 只展示信息, 不执行重置操作
-多个状态同时出现时,优先显示:等待批准 → 运行中 → 刚完成 → 空闲。
+### Token 用量
-如果活动卡片显示「暂无数据」,状态点也不会显示。此时先处理账号或主数据加载问题。
+用量区显示
-## 4. 账号状态与数据刷新
+- 全时累计 Token
+- 单日峰值
+- 当前连续使用天数
+- 最长连续使用天数
+- 最长任务时长
+- 近 30 周日历热力图
-### 需要什么
+热力图颜色深浅按当前可见范围内的 Token 峰值计算; 开启 Codex Hook 后, 日期详情还会显示会话, 轮次, 工具调用, 权限请求, 上下文压缩, 子 Agent 和常用模型等工作流统计
-账号卡片不需要额外开关,但需要本机已安装并登录 Codex CLI 或 Codex App。
+### 任务卡片与任务中心
-### 账号卡片显示什么
+任务卡片需要同时开启"CodexBar Hook"和"主面板任务中心"; 卡片显示当前最重要的任务状态, 以及项目, 模型, 推理强度, 工具, 时长和子 Agent 数量等可用信息
-- 当前账号邮箱或账号名称
-- 当前订阅类型
-- 数据刷新状态
+点击卡片打开任务中心, 可查看
-双击邮箱可以临时模糊显示,适合共享屏幕或截图;再次双击即可恢复。账号发生变化后,模糊状态会自动恢复为正常显示。
+- 等待确认的任务
+- 正在运行的任务
+- 最近 10 分钟内完成的任务
+- 最近 10 分钟内终止的任务
-### 刷新数据
+只有 Codex 将审批明确路由给用户时, 任务才显示为等待批准; 自动审核和 guardian subagent 审批不会进入用户等待状态
-CodexBar 默认每 60 秒刷新一次账号、额度和 Token 用量。菜单底部「数据更新时间」左侧的蓝色圆环表示距离下一次自动刷新还有多久。
+### 底部状态
-需要立即刷新时,双击账号卡片左侧的人物图标。刷新期间人物图标旁会出现小型进度指示,完成后倒计时重新开始。
+底部显示数据更新时间, 自动刷新倒计时, 同步状态和可用更新; 悬停 iCloud 图标可查看同步说明; 双击更新提示可开始安装更新
-### 状态与处理方法
+## 设置
-| 状态 | 含义 | 处理方法 |
-| ---------------------- | ---------------------------------------- | ---------------------------------------------------------------- |
-| 「未登录」橙色提示 | CodexBar 没有读取到已登录账号 | 在 Codex CLI 或 Codex App 中完成登录,再双击人物图标刷新 |
-| 「初始化失败」红色提示 | 没有成功启动或连接本机 Codex | 检查 Codex 是否仍安装,打开设置确认 Codex 版本与路径,再查看日志 |
-| 「暂无数据」 | 账号已识别,但当前没有可展示的额度或用量 | 等待自动刷新,或手动刷新;持续出现时查看日志 |
-| 额度或热力图变淡 | 本轮刷新失败,当前显示的是较早缓存 | 网络或本机 Codex 恢复后再次刷新 |
-| 长时间显示刷新中 | 本次读取可能超时或连接异常 | 等待状态结束后重试,并在日志中查看最新错误 |
+### 通用
-如果安装了多个 Codex,设置中的「Codex 版本」会标记「当前使用」的来源。确认它是否是你实际登录和使用的版本。
+- 开机自动启动
+- 自动检查更新
+- 菜单栏额度指示及额度窗口选择
+- 全局快捷键
-## 5. 额度、重置时间与手动重置机会
+全局快捷键默认是 `⌘⇧W`; 录制快捷键需要至少两个修饰键; `⌘Space` 和 `⌘Tab` 不可使用; 要更换已有快捷键, 先清除, 再录制新组合
-### 需要什么
+### 高级
-主面板额度不需要额外开关,只需要账号已登录并返回额度数据。「菜单栏额度指示」只控制菜单栏竖条,不会隐藏主面板额度。
+#### CodexBar Hook
-### 查看额度
+开启后, CodexBar 在当前 `CODEX_HOME` 的 `hooks.json` 中注册十类工作流事件, 并通过 app-server 验证和维护对应信任状态; 关闭时只移除属于当前 CodexBar 可执行文件的配置, 不修改其他 Hook
-每个额度窗口会显示:
+Hook 提供实时任务, 任务中心, 工作流统计, 任务通知, 阻止系统休眠和跨设备同步所需的数据; 详细说明见 [Codex Hook 与工作流统计](CodexHook.md)
-- 窗口名称
-- 分段额度条
-- 剩余百分比
-- 下一次重置时间
+#### 系统通知
-额度条和百分比使用与菜单栏竖条相同的绿色、蓝色、黄色、橙色和红色分档。某个窗口显示 `--`,表示当前没有该项数据或重置时间。
+首次开启时需要允许 macOS 通知权限; 通知选项包括
-### 在菜单栏持续显示额度
+- 任务完成: 任务达到 30 秒, 1 分钟, 2 分钟或 5 分钟后提醒
+- 任务等待: 任务等待用户批准时提醒
+- 额度预警: 剩余额度到达 5%, 10% 或 25% 时提醒
+- 额度重置: 已消耗的额度窗口恢复为 0% 使用量时提醒
+- 重置临期: 手动重置机会过期前 7 天至 1 天每天提醒一次
+- 任务触觉反馈
+- Codex TUI 通知开关
-1. 打开设置。
-2. 开启「菜单栏额度指示」。
-3. 在右侧下拉菜单选择希望关注的额度窗口。
+每类系统通知都可以单独选择默认声音, 静音或随应用提供的提示音; 点击通知会打开 CodexBar 主面板
-关闭后,CodexBar 会记住最后选择的窗口,下次开启时自动恢复。
+#### 阻止系统休眠
-### 查看手动重置机会
+该功能依赖 Codex Hook 和 macOS 后台项目授权; 只有存在运行中的任务时才阻止休眠; 任务等待批准, 全部结束, Hook 关闭, 功能关闭或达到最长时限后会恢复原系统设置
-如果账号存在可用的手动重置机会,主额度标题右侧会显示绿色的 `重置次数: N`。
+最长时限可选 1, 2, 4, 8, 12, 24 小时或无限制, 默认 12 小时; 新任务开始或等待批准后恢复运行时重新计时
-点击后,侧边面板会按过期时间从近到远列出每批机会:
+首次开启后如果显示"需要授权允许 CodexBar 后台运行", 点击"打开系统设置", 在"登录项与扩展"中允许 CodexBar; 详细说明见 [阻止系统休眠](KeepAlive.md)
-| 数量颜色 | 含义 |
-| -------- | ------------------ |
-| 绿色 | 距离过期超过 7 天 |
-| 橙色 | 将在 7 天内过期 |
-| 红色 | 将在 24 小时内过期 |
+#### 跨设备同步
-`重置次数: N` 用于查看机会和过期时间,不会直接执行额度重置。
+跨设备同步要求
-### 常见问题
+- CodexBar Hook 已开启
+- 已开启"跨设备同步"
+- 当前 iCloud 账号可用
-#### 为什么看不到 `重置次数: N`?
+同步使用应用的 CloudKit 私有数据库, 只上传每日聚合; 开启后会补传本机保留范围内尚未确认的聚合数据; 详细说明见 [跨设备同步](CrossDeviceSync.md)
-只有账号当前存在大于零的可用机会时才显示。手动刷新后仍没有,表示当前没有可展示的机会。
+#### 重建数据
-#### 为什么显示「未知过期时间」?
+"重建数据"从本机原始 Hook 事件重新生成所选日期的每日统计; 日期范围限制在最近 210 天, 实际只处理存在非空事件文件的日期
-CodexBar 已读取到可用次数,但暂时没有取得有效过期时间。次数仍会显示,可以稍后再次刷新。
+如果跨设备同步已开启, 重建后的当前设备聚合会在后续同步中替换对应日期的旧云端记录; 其他设备的数据不受影响
-#### 为什么额度突然变淡?
+### 关于
-当前显示的是较早缓存,不一定是最新结果。双击人物图标刷新;如果持续变淡,请查看日志中的额度读取错误。
+"关于"页显示
-#### 为什么菜单栏竖条和主面板不一致?
+- 全局 Codex CLI 与 App 内置 Codex 的版本和路径
+- 当前 app-server 实际使用的 Codex
+- CodexBar 版本和更新状态
+- 检查更新与退出操作
-先确认设置中选择的是哪个额度窗口。主面板可能同时展示多个窗口,而菜单栏只显示选中的一个。
+点击 Codex 路径可以复制完整路径
-## 6. Token 摘要与近 30 周热力图
+## 日志
-### 需要什么
+日志窗口记录本次运行期间最近 500 条 app-server 请求, 响应和错误; 列表可以展开, 完整内容支持 JSON 格式化预览和复制; 点击"清空"只清除内存中的交互日志
-- Token 摘要和热力图不需要额外开关。
-- 热力图中的工作流明细需要开启「CodexBar Hook」。
+日志不包含 Hook 原始事件, 也不会上传到 CloudKit
-### 摘要指标
+## 常见问题
-用量区域会根据可用数据展示:
+### 显示"未登录"
-| 指标 | 含义 |
-| -------------- | --------------------------------- |
-| 全时累计 Token | 当前可读取范围内的累计 Token 用量 |
-| 单日峰值 | 单日 Token 用量最高值 |
-| 当前连胜 | 最近连续有使用记录的天数 |
-| 最长连胜 | 历史最长连续使用天数 |
-| 最长任务 | 可识别到的最长任务耗时 |
+在 Codex CLI 或 Codex App 中完成登录, 然后双击账号图标刷新
-### 使用热力图
+### 显示"初始化失败"
-热力图以周为列、日为行展示近 30 周。蓝色越深,表示当天 Token 用量相对于当前 30 周峰值越高。
+打开设置的"关于"页, 确认至少存在一个可用 Codex 路径, 并在日志中查看 `initialize` 或 `account/read` 错误
-把鼠标移到任意日期方块上,侧边详情会自动出现。详情跟随鼠标悬停,不需要点击;如果消失,将鼠标重新移回日期即可。
+### Hook 开启失败
-### Hook 开启后的每日统计
+确认当前 `CODEX_HOME` 可写, `hooks.json` 是有效 JSON, 且 Codex 配置没有全局关闭 Hook; 设置页会显示验证结果
-| 指标 | 含义 |
-| ---------- | ------------------------------------- |
-| 用量强度 | 当天 Token 相对于当前热力图峰值的强度 |
-| 最热模型 | 当天出现次数最多的模型 |
-| 会话总数 | 当天识别到的 Codex 会话数量 |
-| 对话轮次 | 当天识别到的任务轮次数量 |
-| 子智能体 | 当天记录到的子 Agent 活动数量 |
-| 调用工具 | 当天记录到的工具调用数量 |
-| 权限请求 | 当天请求用户批准操作的次数 |
-| 上下文压缩 | 当天发生的上下文压缩次数 |
+### 同步不可用
-### 常见问题
+确认系统已登录 iCloud, CloudKit 账号可用且 CodexBar Hook 已开启; 同步错误会显示在主面板底部 iCloud 图标的说明中
-#### 为什么某天有 Token,却没有工作流明细?
+### 阻止系统休眠未生效
-Token 用量和 Hook 工作流统计来自不同功能。请确认当天使用 Codex 时 Hook 已开启,并检查设置中的 Hook 是否有错误提示。
+确认 Hook 已开启, 当前确实有运行中的任务, 最长时限未到, 并在系统设置中允许 CodexBar 后台项目
-#### 为什么今天显示 `--`?
+### 菜单栏没有额度条
-今天的工作流活动可能已经出现,但 Token 用量尚未更新。等待下一次自动刷新即可。
+确认"菜单栏额度指示"已开启, 且所选额度窗口当前有数据; 主面板可同时显示多个窗口, 菜单栏只显示选中的一个
-#### 为什么工作流次数和 Token 数对不上?
+## 数据范围
-工作流次数表示会话、轮次和事件数量,Token 表示用量,两者不是相同口径,不需要逐项对应。
+账号, 额度, Token 用量和认证文件只在本机处理; Hook 原始事件和每日聚合默认保存在
-#### 为什么悬停后看不到侧边详情?
+```text
+~/Library/Application Support/CodexBar/HookEvents/
+```
-将鼠标准确移动到有颜色的日期格上。如果菜单靠近屏幕边缘,详情会自动改到另一侧显示。
-
-## 7. Codex Hook、活动卡片与任务中心
-
-### Hook 提供什么
-
-开启 Codex Hook 后,CodexBar 可以:
-
-- 在热力图中显示每日工作流统计
-- 在活动卡片中显示当前任务
-- 在任务中心查看并发任务
-- 在菜单栏人物图标上显示实时状态点
-- 发送任务等待和任务完成通知
-- 提供任务触觉反馈
-- 使用跨设备同步合并每日工作流统计
-
-### 开启步骤
-
-1. 打开设置。
-2. 开启「CodexBar Hook」。
-3. 等待开关更新完成,确认下方没有错误提示。
-4. 开启「主面板任务中心」,让活动卡片显示在主面板中。
-
-「主面板任务中心」依赖 Hook。Hook 关闭时,该开关会显示为关闭并置灰;重新开启 Hook 后会恢复此前选择。
-
-### 防止任务因系统休眠中断
-
-长时间运行 Codex 任务时,即使任务本身没有结束,macOS 也可能因为长时间无人操作或 MacBook 合盖而进入休眠。开启「阻止系统休眠」后,CodexBar 会根据 Hook 提供的实时任务状态,只在确实还有任务运行时暂时阻止系统休眠;没有其他任务运行时,任务等待你处理、已经结束或超过保护时限后,会把休眠控制权交还给 macOS。
-
-这个功能适合编译、分析、批量修改等需要离开电脑继续运行的长任务。它不是一个让 Mac 永久保持唤醒的总开关,也不会改变每个任务本身的执行逻辑。
-
-#### 它能阻止什么
-
-功能生效时,CodexBar 会同时处理几种常见的系统休眠来源:
-
-| 使用场景 | CodexBar 的行为 |
-| ---------------------------------- | ---------------------------------------------------------- |
-| Mac 开盖,但长时间没有键盘鼠标操作 | 阻止系统因空闲而休眠 |
-| MacBook 合盖 | 阻止普通合盖休眠,让正在运行的任务继续 |
-| 从 Apple 菜单等位置手动请求休眠 | 正在保护任务时阻止这次系统休眠 |
-| 屏幕自动熄灭或系统锁屏 | 不阻止;屏幕熄灭和系统休眠是两件事,屏幕关闭时任务仍可继续 |
-| 关机、重启、断电或电量耗尽 | 无法阻止 |
-| 网络中断、Codex 报错或任务自身终止 | 无法阻止;这个功能只控制系统休眠,不保证任务一定成功 |
-
-如果你希望立即让 Mac 休眠,请先停止正在运行的任务,或直接关闭「阻止系统休眠」后再操作。开关仍然开启时,可以用设置行是否显示「当前允许系统休眠」确认任务已经不再受到保护。
-
-#### 开启与授权
-
-1. 打开设置并先开启「CodexBar Hook」。
-2. 开启「阻止系统休眠」,再从右侧菜单选择「最长阻止时间」。
-3. 首次开启时,如果设置行显示「需要授权允许 CodexBar 后台运行」,点击「打开系统设置」。
-4. 在 macOS「系统设置」→「通用」→「登录项与扩展」的 App 后台活动列表中允许 CodexBar,然后回到 CodexBar。设置行会在 App 再次激活时自动刷新。
-5. 启动一个 Codex 任务;设置行显示「当前禁止系统休眠」时,说明功能已经生效。没有任务运行时显示「当前允许系统休眠」是正常状态。
-
-这项功能必须依赖 Hook,因为 CodexBar 需要靠 Hook 分辨任务是在运行、等待批准还是已经结束。关闭 Hook 时,防休眠开关会自动关闭并置灰,系统休眠设置也会恢复;之后重新开启 Hook,不会自动重新开启防休眠,需要由你再次确认。
-
-「App 后台活动」授权和设置中的「开机自动启动」是两件事。前者允许随 App 安装的后台辅助服务切换和恢复系统休眠设置,后者决定登录后是否自动打开 CodexBar 主应用。
-
-#### 什么时候会真正阻止休眠
-
-设置开关保持开启只表示“允许 CodexBar 在需要时保护任务”,不表示系统此刻一定不能休眠。CodexBar 使用与活动卡片和任务中心相同的实时状态来决定是否生效:
-
-| 当前任务情况 | 是否阻止系统休眠 | 原因 |
-| ------------------------------------ | ---------------- | -------------------------------- |
-| 至少有一个任务正在运行 | 是 | 仍有实际工作需要继续 |
-| 一部分任务等待批准,另一部分仍在运行 | 是 | 只要还有一个任务运行,就继续保护 |
-| 所有任务都在等待用户批准 | 否 | Codex 已经暂停工作,等待你的操作 |
-| 任务全部完成、终止或不再活动 | 否 | 没有需要继续保护的任务 |
-| 已达到最长阻止时间 | 否 | 防止异常任务让电脑无限期保持唤醒 |
-| Hook 关闭或防休眠开关关闭 | 否 | CodexBar 不再接管系统休眠 |
-
-“等待用户批准”只指 Codex 已经确认需要你亲自处理的请求。某些权限请求会由自动审核流程继续处理,这时任务仍算运行中,CodexBar 也会继续阻止休眠。
-
-一个常见过程是:任务运行时阻止休眠;任务停下来等待你批准时恢复系统休眠;你批准后任务重新开始运行,CodexBar 再次阻止休眠。这样可以保护真正执行中的工作,又不会在任务整晚等待输入时持续耗电。
-
-#### 最长阻止时间
-
-可选时限为 1、2、4、8、12、24 小时或无限制,默认是 12 小时。这个时限不是任务超时时间:到期只会允许系统重新休眠,不会取消、终止或修改 Codex 任务。
-
-多个任务共享同一个防休眠周期,而不是每个任务各自倒计时。周期按下面的方式计算:
-
-- 第一个运行任务出现时开始计时。
-- 后来又启动一个新任务时,从新任务启动的时刻重新获得完整时限。
-- 等待批准的任务获批并恢复运行时,也从恢复时刻重新获得完整时限。
-- 同一任务只是继续输出内容、调用工具或产生普通 Hook 活动,不会延长时限。重新打开设置、激活 CodexBar 或刷新状态也不会延长。
-- 所有运行和等待任务都消失后,当前周期结束;下次出现任务时重新计时。
-- 关闭再开启防休眠后,如果此时仍有任务运行,会建立一个新的周期。
-
-例如,最长时间设为 12 小时:任务 A 在 10:00 启动,原本会保护到 22:00;任务 B 在 15:00 新启动后,共享截止时间会改为次日 03:00。A 或 B 的普通进度更新不会继续顺延。如果任务在 16:00 等待你批准,并在 16:30 获批恢复运行,则会从 16:30 再获得完整的 12 小时。
-
-达到上限后,即使原任务仍显示运行中,CodexBar 也会恢复系统休眠;该任务后续的普通活动不会自动重新开启保护。此后启动新任务,或让等待批准的任务恢复运行,才会开始新的完整周期。
-
-运行中修改时限会按当前周期的起点重新计算。改成更短时,如果新时限已经过去,会立即恢复休眠;改成更长时,只要按新时限计算还没有到期,就会继续保护。改成「无限制」会取消本周期的自动到期限制,但仍会在任务等待、结束、功能关闭或 CodexBar 退出时恢复系统休眠。无限制可能显著增加耗电,建议只在明确需要时使用。
-
-#### 任务停止运行后会发生什么
-
-开始保护任务前,CodexBar 会记住电脑原本的休眠设置;结束保护时恢复这个原始状态,而不是一律强制开启休眠。因此,如果你在任务开始前已经通过其他工具全局禁止休眠,CodexBar 结束后会保留那个选择。相反,也不建议在保护期间同时使用其他工具修改同一项全局休眠设置,因为结束时 CodexBar 会按任务开始前记录的状态恢复。休眠设置作用于整台 Mac,也应避免同时运行来自不同安装位置的多个 CodexBar。
-
-恢复设置不等于无条件让电脑立刻睡眠。CodexBar 会先交还休眠控制权,再让 macOS 根据已经累计的空闲时间、最近是否有人操作、其他 App 是否也在阻止休眠以及当前电源策略重新判断:
-
-- Mac 开盖时,如果早已达到系统设定的空闲时间,可能很快进入休眠;如果你刚操作过电脑,或其他 App 仍在保持唤醒,也可能继续运行。
-- MacBook 普通合盖、没有处于外接显示器合盖工作模式,并且任务开始前的设置允许休眠时,CodexBar 会在恢复设置后请求系统进入休眠。
-- MacBook 合盖连接外接显示器,并且 macOS 允许合盖工作时,只恢复原设置,不会强制休眠。
-
-正常退出 CodexBar 时会主动恢复休眠设置。如果 App 意外退出或与后台服务失去连接,后台服务会根据此前保存的恢复记录进行兜底,通常在约 15 秒的宽限时间后恢复。这个短暂等待是为了避免 CodexBar 更新或快速重连时来回切换系统状态。
-
-关闭防休眠后,CodexBar 的后台项目仍可能继续出现在「登录项与扩展」列表中,这不表示系统仍被禁止休眠。保留后台服务是为了下次启用以及在异常情况下完成恢复;是否正在阻止休眠,应以 CodexBar 设置行的当前状态为准。
-
-#### 后台权限与隐私
-
-之所以需要后台项目授权,是因为普通 App 只能可靠阻止空闲休眠,无法保证 MacBook 合盖后继续运行。CodexBar 使用随 App 一起签名的 CodexBarHelper 完成必要的系统级切换。
-
-这个辅助服务的能力受到严格限制:它只响应同一签名的 CodexBar,只能在“阻止休眠”和“恢复原设置”之间切换,并在本机保存一条用于异常恢复的状态记录。它不能接收任意命令或文件路径,不访问网络,也不读取 Codex 账号、提示词、回复、任务内容、会话信息或 Hook 原始记录。你不需要在终端运行 `sudo` 或手动修改系统休眠设置。
-
-#### 状态提示与排查
-
-| 设置行提示 | 表示什么 | 建议操作 |
-| ------------------------------ | ---------------------------------------- | ----------------------------------------------------------------- |
-| 需要启用 CodexBar Hook | CodexBar 无法取得可靠的实时任务状态 | 先开启 Hook;重新开启 Hook 后还要手动重新开启防休眠 |
-| 需要授权允许 CodexBar 后台运行 | 后台服务已经注册,但仍在等待 macOS 授权 | 点击「打开系统设置」,在「登录项与扩展」中允许 CodexBar |
-| CodexBarHelper 尚未注册 | 后台服务还没有准备好 | 短暂出现可等待刷新;持续显示时确认 App 位于「应用程序」并重新安装 |
-| 当前允许系统休眠 | 功能已就绪,但当前没有需要保护的运行任务 | 通常无需处理;查看活动卡片确认任务是否正在运行 |
-| 当前禁止系统休眠 | 至少一个任务正在运行,保护已经生效 | 可以继续使用或合盖运行,同时注意散热和电量 |
-| 已达到禁用休眠上限 | 当前周期已经到期,系统休眠设置已恢复 | 需要继续时启动新任务、恢复等待任务,或重新评估最长阻止时间 |
-| 红色错误信息 | 注册、连接或切换休眠状态失败 | 打开日志查看最新错误;持续失败时退出并重新打开或重新安装 CodexBar |
-
-如果设置显示「当前允许系统休眠」,但你认为任务仍在运行,先查看活动卡片和任务中心:任务可能已经进入等待批准,或者当前周期已经达到上限。如果活动卡片也无法正确显示状态,请先排查 Hook。
-
-如果合盖后任务仍然停止,请依次确认:Hook 和防休眠开关都已开启;后台项目已经授权;合盖前设置行显示「当前禁止系统休眠」;当前周期尚未达到上限;任务不是在等待批准。还应检查任务是否因为断网、Codex 错误或其他与休眠无关的原因停止。
-
-如果功能关闭后 Mac 没有立刻休眠,这通常不表示恢复失败。macOS 仍会考虑最近的用户操作、其他 App 的唤醒请求和系统电源策略。只有设置行出现红色错误,或长时间无法恢复正常状态时,才需要查看日志进一步处理。
-
-#### 使用安全
-
-合盖运行会持续耗电并产生热量,CodexBar 不会根据低电量自动结束防休眠。请确保 Mac 通风良好,接通合适的电源,不要把仍在运行任务的电脑放进背包、保护套或其他密闭空间。需要携带电脑前,请停止任务并确认设置行已经显示「当前允许系统休眠」,或直接关闭该功能后再合盖携带。
-
-系统更新、关机、断电和电池耗尽仍会中断任务。对于无法轻易重跑的重要任务,建议同时保存中间结果,不要把防休眠功能当作任务可靠性的唯一保障。
-
-### 活动卡片图标
-
-| 图标与颜色 | 状态 | 含义 |
-| ---------- | -------- | -------------------------- |
-| 橙色举手 | 等待批准 | Codex 正在等待用户确认操作 |
-| 蓝色闪电 | 运行中 | Codex 正在执行任务 |
-| 绿色对勾 | 最近完成 | 任务已经确认结束 |
-| 灰色叉号 | 最近终止 | 任务没有按正常完成状态结束 |
-| 灰色月亮 | 暂无活动 | 当前没有可展示任务 |
-
-活动卡片会优先显示等待批准,其次是运行中、最近完成、最近终止和空闲。标题可能包含模型、推理强度和项目名称,第二行可能显示工具、阶段、耗时和活跃子 Agent 数量。
-
-右侧 `+N` 表示还有其他正在运行或等待批准的任务。
-
-### 使用任务中心
-
-点击活动卡片即可打开任务中心。任务按以下分组展示:
-
-- 等待确认
-- 运行中
-- 最近完成
-- 最近终止
-
-最近完成和最近终止通常保留约 10 分钟。任务中心优先显示在主面板右侧,空间不足时会自动切换到左侧;任务较多时可以在面板内滚动。
-
-「完成」表示该轮任务已结束,不评价结果是否符合预期;「终止」表示没有收到正常完成状态,因此不会显示绿色菜单栏状态,也不会触发任务完成通知。
-
-### Hook 错误提示
-
-| 提示 | 含义 | 处理方法 |
-| ------------------------- | ------------------------------- | ---------------------------------------------- |
-| `Codex 配置已禁用 Hook` | 当前 Codex 不允许 Hook 工作 | 检查 Codex 的 Hook 设置,更新 Codex 后重新开启 |
-| `hooks.json 文件格式错误` | Codex 的 Hook 配置无法正常读取 | 修复 Hook 配置后回到 CodexBar 重新开启 |
-| `CodexBar Hook 已被禁用` | Hook 已存在但当前未生效 | 关闭再开启 Hook;仍失败时查看日志 |
-| `CodexBar Hook 未被信任` | Codex 尚未信任当前 CodexBar | 关闭再开启 Hook,并确认使用的是最终安装位置 |
-| `CodexBar Hook 已不完整` | 部分所需事件没有正确启用 | 关闭再开启 Hook,让 CodexBar 重新配置 |
-| `CodexBar Hook 意外来源` | 当前生效的 Hook 不是预期配置 | 检查是否装有多个 CodexBar,保留最终使用的版本 |
-| `无法验证 Codex Hook` | Hook 可能已设置,但验证没有完成 | 查看日志,确认 Codex 可正常使用后重试 |
-| `设置 Codex Hook 失败` | 开启、关闭或保存设置失败 | 根据提示检查权限、Codex 状态和 App 安装位置 |
-
-### 常见问题
-
-#### 为什么 Hook 已开启,活动卡片仍显示「暂无 Codex 活动」?
-
-这表示主数据正常,但当前没有运行、等待、最近完成或最近终止的任务。启动一个新的 Codex 任务后再观察。
-
-#### 为什么活动卡片显示「暂无数据」?
-
-主面板账号或用量数据还没有准备好。先解决「未登录」「初始化失败」或「暂无数据」,再检查任务状态。
-
-#### 为什么有任务在运行,但 CodexBar 没有显示?
-
-依次检查:
-
-1. 「CodexBar Hook」是否开启且没有错误。
-2. 「主面板任务中心」是否开启。
-3. 该任务是否在开启 Hook 后启动。
-4. 当前使用的 Codex 是否为设置中标记「当前使用」的版本。
-5. 日志中是否有 Hook 验证或读取错误。
-
-#### 为什么任务显示运行中但没有精确耗时?
-
-CodexBar 没有取得可信的任务开始时间时,只显示「正在运行」,不会显示可能不准确的时长。
-
-#### 为什么 Codex 已关闭,任务仍显示运行中?
-
-强制关闭、崩溃、终端直接退出或电脑断电时,任务可能没有留下结束状态。后续新任务通常会使旧任务转为最近终止;如果一直没有新活动,旧状态最多可能保留约 24 小时。
-
-#### 能否手动删除一条卡住的任务?
-
-当前没有单任务删除按钮。等待后续任务更新状态,或等待旧活动自动过期。
-
-#### 移动 CodexBar 后 Hook 不工作怎么办?
-
-Hook 与当前 App 位置相关。建议先在旧位置关闭 Hook,把 App 移到最终位置,再重新开启。不要同时运行多个不同位置的 CodexBar,否则可能重复记录同一活动。
-
-#### 关闭 Hook 会删除历史统计吗?
-
-不会。关闭后会停止记录新活动,并隐藏活动卡片和 Hook 统计;重新开启后,仍可继续使用保留的历史数据。
-
-## 8. 重建工作流统计
-
-### 什么时候使用
-
-当某段日期的工作流统计缺失、重复或与本机记录不一致时,可以使用设置中的「重建数据」。日常使用不需要定期重建。
-
-### 需要什么
-
-- 所选日期在本机仍有 Hook 原始记录。
-- 当前可选择最近 210 天内的日期。
-- 是否正在开启 Hook,不影响对已有本机记录执行重建。
-
-### 操作步骤
-
-1. 打开设置,找到「重建数据」。
-2. 点击「选择日期范围」。
-3. 第一次点击选择开始日期,第二次点击选择结束日期。
-4. 只重建一天时,连续点击同一天两次。
-5. 检查设置行下方显示的选择结果。
-6. 点击「重建」,在确认窗口中再次确认。
-
-日历中带圆点的日期表示本机存在可用于重建的数据。范围可以包含没有圆点的日期,但实际只处理有本机数据的日期。
-
-### 状态提示
-
-| 提示 | 含义 |
-| ------------------------------ | ---------------------------------------- |
-| 「未选择重建日期范围」 | 尚未开始选择 |
-| 「选择结束日期」 | 已选择开始日期,等待选择结束日期 |
-| 「已选择 X 天」 | 日期范围已完成,范围中有可重建数据 |
-| 「没有可重建的本地数据」 | 所选范围没有可用的本机 Hook 记录 |
-| 「共处理 X 天,包含 X 条数据」 | 本机重建完成 |
-| 「跳过 X 条无效数据」 | 有少量记录无法读取,其余内容已完成重建 |
-| 「云端替换将在同步可用后继续」 | 本机已完成,跨设备数据会在同步恢复后更新 |
-| 「重建失败」 | 本次没有完成,请根据后续错误信息处理 |
-
-如果跨设备同步已开启,重建结果会更新当前设备在所选日期的同步数据,不影响其他设备或范围外日期。
-
-## 9. 跨设备同步
-
-### 同步内容
-
-跨设备同步用于在多台 Mac 上合并 Hook 的每日工作流统计,例如会话、轮次、模型和工具使用次数。Token 用量与实时任务不会跨设备同步。
-
-### 开启条件
-
-- 「CodexBar Hook」已开启
-- 「跨设备同步」已开启
-- 当前 Mac 已登录可用的 iCloud 账号
-- 多台 Mac 使用同一个 iCloud 账号
-
-### 开启步骤
-
-1. 先开启「CodexBar Hook」。
-2. 确认 macOS 已登录 iCloud。
-3. 开启「跨设备同步」。
-4. 等待设置中出现「最近同步」时间,或在菜单底部查看 iCloud 图标。
-
-首次开启后,历史统计需要一些时间完成合并。保持 CodexBar 运行即可,无需反复开关。
-
-### 同步图标
-
-| 图标 | 含义 | 建议操作 |
-| ------------------- | ------------------------ | ---------------------------------------------------- |
-| 普通 iCloud | 同步已开启 | 悬停查看最近同步时间;显示「暂无同步记录」时继续等待 |
-| 带斜杠的 iCloud | 同步未开启或没有实际生效 | 检查 Hook、同步开关和 iCloud 登录状态 |
-| 带旋转箭头的 iCloud | 正在同步 | 等待完成 |
-| 带感叹号的 iCloud | 最近一次同步失败 | 悬停查看原因,按网络、账号或服务状态处理 |
-
-### 常见问题
-
-#### 为什么同步开关是灰色的?
-
-先开启 Hook,并确认当前 Mac 已登录 iCloud。Hook 正在更新或 iCloud 状态尚未确认时,也可能暂时不可操作。
-
-#### 为什么显示「同步不可用」?
-
-常见原因包括 iCloud 未登录、账号受限、网络不可用或服务暂时不可用。先打开 macOS 系统设置确认 iCloud,再稍后返回 CodexBar。
-
-#### 为什么另一台 Mac 没有马上出现数据?
-
-确认两台 Mac 使用同一 iCloud 账号,并且都开启 Hook 和跨设备同步。首次合并或历史数据较多时需要等待后续同步完成。
-
-#### 同步失败后需要重新开关吗?
-
-通常不需要。网络或服务恢复后,CodexBar 会在后续刷新中继续尝试。长期失败时再检查 iCloud 登录和系统网络。
-
-#### 为什么两台 Mac 的 Token 热力图不同?
-
-跨设备同步只合并 Hook 工作流统计,不同步 Token 用量,因此每台 Mac 的 Token 数据仍来自各自本机 Codex。
-
-## 10. 系统通知、Codex TUI 通知与触觉反馈
-
-### 开启步骤
-
-1. 打开设置。
-2. 开启「系统通知」。
-3. 在 macOS 弹窗中允许 CodexBar 发送通知。
-4. 点击「系统通知」右侧的滑杆图标。
-5. 分别开启需要的通知类型,选择阈值与通知声音。
-
-如果通知权限被拒绝,设置中会显示提示和「打开系统设置」按钮。允许通知后,返回 CodexBar 即可继续配置。
-
-### 通知选项
-
-| 选项 | 触发条件 | 依赖与设置 |
-| -------------- | ----------------------------- | ----------------------------------- |
-| 任务完成通知 | 任务确认完成且耗时达到阈值 | 需要 Hook;可选 30 秒、1、2、5 分钟 |
-| 任务等待通知 | 任务正在等待用户批准 | 需要 Hook |
-| 额度预警通知 | 剩余额度下降到所选阈值 | 可选 5%、10%、25%,默认 10% |
-| 额度重置通知 | 已使用过的额度恢复到 100% | 需要可用额度数据 |
-| 重置临期通知 | 手动重置机会将在 7 天内过期 | 需要读取到机会及过期时间 |
-| 任务触觉反馈 | 任务进入等待批准或确认结束 | 需要 Hook 和支持的输入设备 |
-| Codex TUI 通知 | 控制 Codex CLI 自身的终端通知 | 修改后重新启动正在运行的 Codex 会话 |
-
-任务完成、任务等待和任务触觉选项依赖 Hook。Hook 关闭时,它们会置灰,但会保留此前选择。
-
-CodexBar 系统通知都可以独立选择声音,默认使用 macOS 系统通知声;选择「静音」时只显示通知。声音菜单将选项分为 14 个经典提示音和 17 个现代提示音,包括 Basso、Glass、Sosumi、Antic、Droplet、Portal、Received Message 等。打开声音菜单并选择任意声音时会立即试听;也可以点击声音右侧的播放按钮重复试听当前选项,选择「静音」时该按钮不可用。声音偏好会在通知关闭或 Hook 暂停时保留;Codex TUI 通知由 Codex CLI 自己播放,不使用这里的声音设置。
-
-### 图标与状态
-
-| 图标或状态 | 含义 |
-| ---------------------------- | ------------------------------ |
-| 「系统通知」右侧滑杆 | 打开通知子选项 |
-| 通知声音菜单 | 选择声音并立即试听 |
-| 通知声音右侧播放按钮 | 重复试听当前声音;静音时不可用 |
-| Codex TUI 通知旁的小进度圈 | 正在读取或保存设置 |
-| Codex TUI 通知旁的橙色感叹号 | 读取或保存失败;悬停可查看原因 |
-| 「打开系统设置」按钮 | macOS 尚未授权 CodexBar 通知 |
-
-点击 CodexBar 发出的系统通知,会尝试打开主菜单面板,方便继续查看任务或额度状态。
-
-### 常见问题
-
-#### 为什么开启后仍收不到通知?
-
-依次确认:
-
-1. 「系统通知」总开关已开启。
-2. macOS 系统设置允许 CodexBar 通知。
-3. 对应通知子选项已开启。
-4. 额度数据正常,或任务类通知所需的 Hook 已开启。
-5. 任务耗时达到所选完成通知阈值。
-
-#### 为什么短任务没有完成通知?
-
-任务完成通知只提醒达到所选时长的任务。默认阈值为 1 分钟,可改为 30 秒、2 分钟或 5 分钟。
-
-#### 为什么短暂显示等待批准,却没有通知?
-
-只有确实需要用户处理、并且仍处于等待状态的任务才会通知。自动处理或很快恢复运行的请求不会产生过期提醒。
-
-#### 为什么等待通知从通知中心消失了?
-
-当任务恢复运行、完成或终止后,对应等待通知会自动撤回,避免留下已经失效的提示。
-
-#### 为什么没有触觉反馈?
-
-确认「系统通知」「任务触觉反馈」和 Hook 都已开启。触觉效果还取决于 Mac、触控板、辅助功能和系统偏好,部分设备不会产生明显反馈。
-
-#### 为什么 Codex TUI 通知旁有感叹号?
-
-把鼠标停在感叹号上查看原因。确认 Codex 可以正常使用后重试;保存成功后,重新启动已打开的 Codex 会话。
-
-## 11. 其他设置与全局快捷键
-
-### 设置项说明
-
-| 设置项 | 图标 | 作用 | 常见问题 |
-| -------------- | -------- | ---------------------------------- | ----------------------------------------------------------- |
-| 开机自动启动 | 电源 | 登录 macOS 后自动运行 CodexBar | 设置失败时下方会显示错误;移动 App 后建议关闭再开启一次 |
-| 自动检查更新 | 循环箭头 | 定期检查 CodexBar 新版本 | 关闭后仍可手动点击「检查更新」 |
-| 菜单栏额度指示 | 仪表 | 在菜单栏显示所选额度窗口 | 没有对应额度数据时自动隐藏 |
-| 设置快捷键 | 键盘 | 设置全局打开或关闭菜单面板的快捷键 | 至少需要两个修饰键 |
-| CodexBar Hook | 链接 | 开启工作流统计和实时任务能力 | 失败时根据该行下方提示处理 |
-| 主面板任务中心 | 列表 | 在主面板显示活动卡片和任务中心入口 | 需要 Hook;Hook 关闭时置灰 |
-| 系统通知 | 铃铛 | 控制 CodexBar 通知与任务触觉总开关 | 首次开启需要 macOS 授权 |
-| 跨设备同步 | iCloud | 合并多台 Mac 的每日工作流统计 | 需要 Hook 和可用 iCloud 账号 |
-| 阻止系统休眠 | 月亮 | 仅在任务真正运行时阻止系统休眠 | 需要 Hook 和 macOS 后台项目授权;关闭 Hook 时自动关闭并置灰 |
-| 重建数据 | 圆形箭头 | 重新生成所选日期的本机工作流统计 | 需要所选日期仍有本机记录 |
-| Codex 版本 | 数字圆圈 | 查看已安装 Codex 及当前使用来源 | 点击路径可以复制 |
-| CodexBar 版本 | 信息圆圈 | 查看当前版本与更新状态 | 有更新时显示下载按钮 |
-
-### 设置全局快捷键
-
-默认快捷键为 `⌘⇧W`。
-
-修改步骤:
-
-1. 点击叉号图标清除当前快捷键。
-2. 点击「未设置」。
-3. 按下新的按键组合。
-
-快捷键至少需要 `Control`、`Option`、`Shift`、`Command` 中的两个修饰键。
-
-| 图标或操作 | 作用 |
-| ---------- | -------------------- |
-| 回转箭头 | 恢复默认快捷键 `⌘⇧W` |
-| 叉号 | 清除当前快捷键 |
-| `Esc` | 取消本次录制 |
-
-如果提示「至少需要两个修饰键」,请增加修饰键后重试。如果提示「不可使用系统快捷键」,请选择未被 macOS 保留的组合。注册失败时,CodexBar 会恢复之前的可用设置并显示原因。
-
-### 开机自动启动失败
-
-确认 CodexBar 已放在最终安装位置,并检查 macOS 是否允许登录项。移动 App 后,关闭再开启「开机自动启动」,让系统记录新位置。
-
-### 退出 CodexBar
-
-可以右键菜单栏图标选择「退出」,也可以在设置底部点击红色的「退出 CodexBar」。
-
-## 12. 日志、版本与更新
-
-### 使用日志
-
-打开方式:
-
-- 右键菜单栏图标,选择「日志」
-- 主菜单面板打开时按 `⌘L`
-
-日志适合排查未登录、初始化失败、刷新超时、Hook 验证和设置失败。
-
-| 日志标签 | 颜色 | 含义 |
-| -------- | ---- | -------------------------- |
-| 进行 | 橙色 | 正在等待结果 |
-| 完成 | 绿色 | 已收到正常结果 |
-| 错误 | 红色 | 请求或操作失败 |
-| 请求 | 蓝色 | 已发出不需要等待结果的操作 |
-
-点击日志行可以展开摘要;点击「预览」查看完整内容,点击「复制」复制内容。顶部数字表示当前日志条数,「清空」会删除当前运行期间的日志列表。
-
-关闭日志窗口不会立即清空记录;退出 CodexBar 后,本次运行日志会消失。
-
-### 查看 Codex 版本
-
-设置中的「Codex 版本」会列出:
-
-| 图标 | 来源 |
-| -------- | -------------------- |
-| 终端 | 全局安装的 Codex CLI |
-| App 标记 | Codex App 内置的 CLI |
-
-绿色「当前使用」表示 CodexBar 当前连接的来源。橙色「已更新至」表示磁盘上已有更新版本,但当前运行中的 Codex 仍可能是较早版本;重新启动 Codex 后再刷新即可确认。
-
-点击路径可以复制,复制成功后会短暂显示「已复制」。
-
-### 更新 CodexBar
-
-- 开启「自动检查更新」后,CodexBar 会定期检查新版本。
-- 点击设置底部「检查更新」可以立即手动检查。
-- 发现更新后,「CodexBar 版本」右侧会出现向下箭头按钮。
-- 菜单面板底部也会显示新版本提示,双击即可开始更新。
-
-| 更新提示 | 含义 |
-| ------------------ | -------------------------------------------------------- |
-| 「正在检查更新」 | 正在查询新版本 |
-| 「没有可用更新」 | 当前已是最新版本 |
-| 「发现新版本」 | 可以点击更新按钮安装 |
-| 「检查更新失败」 | 本次检查没有完成,请稍后重试 |
-| 「未配置更新资源」 | 当前安装版本不支持内置更新,建议从 Releases 重新下载安装 |
-
-## 13. 常见问题速查
-
-| 现象 | 优先检查 |
-| ------------------------ | ---------------------------------------------------- |
-| 找不到 Dock 图标或主窗口 | CodexBar 只显示在菜单栏,这是正常设计 |
-| 菜单栏人物带叉 | 打开菜单查看「未登录」或「初始化失败」 |
-| 主面板显示「暂无数据」 | 确认 Codex 已登录,手动刷新并查看日志 |
-| 额度或热力图变淡 | 当前显示的是较早缓存,等待或手动刷新 |
-| 菜单栏没有额度竖条 | 开启「菜单栏额度指示」,并检查所选窗口是否有数据 |
-| 看不到手动重置次数 | 当前账号没有可用机会,或数据尚未刷新 |
-| 热力图没有工作流统计 | 开启 Hook,并确认该日期有 Hook 记录 |
-| 活动卡片没有出现 | 同时开启 Hook 和「主面板任务中心」 |
-| 点击活动卡片没有反应 | 当前没有可展示任务,或主数据尚未加载 |
-| 任务一直显示运行中 | 任务可能没有正常留下结束状态,等待后续活动或自动过期 |
-| 合盖后任务仍然停止 | 检查防休眠开关、Hook 状态和 CodexBar 后台项目授权 |
-| 跨设备同步开关置灰 | 先开启 Hook,并确认 iCloud 可用 |
-| iCloud 图标带感叹号 | 悬停查看网络、账号或服务错误 |
-| 收不到系统通知 | 检查总开关、macOS 权限、子选项和 Hook 依赖 |
-| 没有触觉反馈 | 检查三个开关,并确认设备支持触觉 |
-| 快捷键无法设置 | 先清除原快捷键,使用至少两个修饰键的新组合 |
-| 设置显示两个 Codex 版本 | 查看绿色「当前使用」标记确认实际来源 |
-| 更新检查失败 | 稍后重试,或从 Releases 手动下载安装 |
-
-如果速查表仍无法解决问题,请打开日志,找到最新红色「错误」记录,再结合对应功能章节处理。
-
-## 14. 隐私与数据范围
-
-CodexBar 以本机处理为主:
-
-- 账号、额度和 Token 用量在本机读取和展示。
-- Hook 原始记录保存在当前 Mac,默认保留最近 210 天。
-- 实时任务只在当前 App 运行期间用于状态展示。
-- 防休眠 helper 只在本机切换系统休眠设置并维护恢复哨兵,不访问网络或任务内容。
-- 菜单面板只显示项目名称,不显示完整工作目录、会话编号或轮次编号。
-- CodexBar 不展示提示词、回复、推理内容、工具内容或审批内容。
-
-跨设备同步完全可选。开启后,只通过当前 iCloud 账号的私有数据库同步每日工作流聚合;不会同步 Codex 账号、额度、Token 用量、原始 Hook 记录、实时任务、请求日志或认证信息。
-
-CodexBar 只有在以下用户可见功能中使用网络:
-
-- 查询手动重置机会的过期时间
-- 检查和下载 CodexBar 更新
-- 用户主动开启的跨设备同步
-
-关闭 Hook 会停止记录新的工作流活动;关闭跨设备同步会停止后续同步。更详细的数据说明见 [Codex Hook 文档](CodexHook.md) 和 [跨设备同步文档](CrossDeviceSync.md)
+跨设备同步只上传每日统计字段, 不上传原始事件, 会话 ID, 轮次 ID, 请求日志或认证文件
diff --git a/README.md b/README.md
index 0bb6156..f033fea 100644
--- a/README.md
+++ b/README.md
@@ -1,43 +1,84 @@
# CodexBar
-> 在 macOS 菜单栏,一眼查看 Codex 状态、额度与使用情况。
-
-CodexBar 是一款无 Dock 图标的 macOS 菜单栏应用。无需打开 Codex CLI 或 Codex App,即可快速了解账号状态、剩余额度、重置时间、Token 用量和正在进行的任务。
+CodexBar 是一款 macOS 菜单栏应用, 用于查看本机 Codex 账号, 额度, Token 用量和任务状态; 应用不显示 Dock 图标, 主要数据通过本机 Codex app-server 获取
<p align="center">
<img src="Images/preview.gif" width="600" alt="CodexBar 预览">
</p>
-## 主要功能
+## 功能
+
+- 查看账号, 订阅类型, 额度窗口, 剩余比例和重置时间
+- 查看手动重置机会及其过期时间
+- 查看 Token 摘要和近 30 周用量热力图
+- 通过可选 Codex Hook 展示运行中, 等待批准, 最近完成和最近终止的任务
+- 按天统计会话, 轮次, 工具调用, 权限请求, 上下文压缩, 子 Agent 和常用模型
+- 提供额度, 任务和重置机会通知, 可分别选择通知声音
+- 在 Codex 任务运行时按需阻止系统休眠
+- 通过 iCloud 私有数据库同步脱敏的每日工作流聚合
+- 支持菜单栏额度指示, 全局快捷键, 开机启动, 交互日志和 Sparkle 更新
+
+## 运行要求
+
+- macOS 15.0 或更高版本
+- 已安装并登录 [Codex CLI](https://github.com/openai/codex), ChatGPT App 或 Codex App
-- **额度状态**:查看各时间窗口的剩余额度、重置时间和手动重置机会
-- **Token 热力图**:用近 30 周日历热力图回顾每日 Token 用量
-- **实时任务**:开启 Codex Hook 后,查看运行中、等待批准、最近完成和终止的任务
-- **阻止系统休眠**:可选仅在任务真正运行时阻止 macOS 的空闲、合盖和手动休眠,可设置从最近任务启动或获批恢复起的最长期限,并在等待批准、任务结束或到期后自动恢复;恢复后会立即让系统重新评估是否已经满足休眠条件
-- **工作流统计**:按日期查看会话、对话轮次、工具调用、权限请求、上下文压缩和子 Agent 等数据
-- **及时提醒**:可选额度告急、额度恢复、等待批准、长任务完成通知与触觉反馈,各类通知声音可独立选择
-- **跨设备汇总**:通过可选的 iCloud 私有数据库同步每日聚合数据
-- **本地优先**:账号、额度、Token 用量和工作流事件均以本机处理为主
-- **原生体验**:支持全局快捷键、开机启动、系统日志和 Sparkle 自动更新
+CodexBar 优先使用 `PATH` 中的全局 `codex`, 找不到时依次检查 ChatGPT App 和 Codex App 内置的 Codex 可执行文件
## 安装
-### Homebrew
+使用 Homebrew
```bash
brew install --cask bob-zebedy/tap/codexbar
```
-也可以从 [Releases](https://github.com/bob-zebedy/CodexBar/releases) 下载最新 DMG,并将 `CodexBar.app` 拖入 `/Applications`
+也可以从 [Releases](https://github.com/bob-zebedy/CodexBar/releases) 下载 DMG, 并将 `CodexBar.app` 拖入 `/Applications`
-运行要求:
+## 基本使用
-- macOS 15.0 或更高版本
-- 已安装并登录 [Codex CLI](https://github.com/openai/codex) 或 Codex App
+- 左键点击菜单栏图标: 打开或关闭主面板
+- 右键或 `Control` + 左键点击: 打开设置, 日志和退出菜单
+- 全局快捷键: 默认 `⌘⇧W`
+- 打开设置: `⌘,`
+- 主面板打开时打开日志: `⌘L`
+
+完整说明见 [使用指南](Docs/UserGuide.md)
+
+## 数据与隐私
+
+账号, 额度和 Token 用量由本机 Codex app-server 返回; Hook 原始事件默认只保存在本机
+
+```text
+~/Library/Application Support/CodexBar/HookEvents/
+```
+
+跨设备同步关闭时, 工作流数据不会上传; 开启后只同步每日聚合, 不上传原始事件, 会话 ID, 轮次 ID, app-server 日志或 Codex 认证文件
+
+应用自身的网络访问仅用于
+
+- 查询手动重置机会的过期时间
+- Sparkle 更新检查与下载
+- 用户开启后的 CloudKit 私有数据库同步
+
+## 开发
+
+使用 Xcode 打开 `CodexBar.xcodeproj`, 或运行
+
+```bash
+xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/platform=macOS' build
+```
+
+工程结构, 构建和发布说明见 [开发指南](Docs/DevelopmentGuide.md)
-更多使用方法见[使用指南与常见问题](Docs/UserGuide.md)
+## 文档
-「阻止系统休眠」需要 Codex Hook,并在首次开启时要求 macOS 允许 CodexBar 后台项目;关闭 Hook 会自动关闭并置灰该选项。最长防休眠期限可选 1、2、4、8、12、24 小时或无限制,默认 12 小时;新任务启动以及同一任务等待用户批准后恢复运行都会重新计时,普通 Hook 活动不会续期。任务运行时,CodexBar 同时关闭系统休眠并持有阻止空闲休眠的系统 assertion。每次恢复时先还原任务开始前的系统设置,再释放 assertion,让 macOS 按当前空闲计时、其他 assertion 和电源策略立即重新判断是否应休眠;普通合盖且系统确认合盖应休眠时还会主动请求休眠。电脑原本就全局禁止休眠或处于外接显示器合盖工作模式时不会强制休眠。合盖运行会增加耗电和发热,请确保 Mac 通风良好,不要在密闭包内使用。
+- [使用指南](Docs/UserGuide.md)
+- [Codex app-server](Docs/AppServer.md)
+- [Codex Hook 与工作流统计](Docs/CodexHook.md)
+- [跨设备同步](Docs/CrossDeviceSync.md)
+- [阻止系统休眠](Docs/KeepAlive.md)
+- [开发指南](Docs/DevelopmentGuide.md)
## 许可证
diff --git a/Scripts/appcast.sh b/Scripts/appcast.sh
index 7bb97e6..f215e12 100755
--- a/Scripts/appcast.sh
+++ b/Scripts/appcast.sh
@@ -230,16 +230,28 @@ APPCAST_ITEM=" <item>
</item>"
echo "==> Updating appcast"
-APPCAST_ITEM="${APPCAST_ITEM}" APPCAST_VERSION="${BUILD_VERSION}" perl -0pi -e '
+# Write through a temp file so a perl die leaves appcast.xml untouched.
+APPCAST_TMP="$(mktemp)"
+trap 'rm -f "${APPCAST_TMP}"' EXIT
+APPCAST_ITEM="${APPCAST_ITEM}" APPCAST_VERSION="${BUILD_VERSION}" perl -0p -e '
my $item = $ENV{"APPCAST_ITEM"};
my $version = $ENV{"APPCAST_VERSION"};
+ my $before = () = /<item>/g;
- s/\n\s*<item>\s*.*?<sparkle:version>\Q$version\E<\/sparkle:version>.*?<\/item>//sg;
+ # Keep the (?!<\/item>) guards: a plain .*? spans item boundaries and would
+ # also delete every entry above the one being replaced.
+ s/\n\s*<item>(?:(?!<\/item>).)*?<sparkle:version>\Q$version\E<\/sparkle:version>(?:(?!<\/item>).)*?<\/item>//sg;
if (!s/(<language>.*?<\/language>)/$1\n$item/s) {
die "Unable to find <language>...</language> insertion point\n";
}
-' "${APPCAST_PATH}"
+
+ my $after = () = /<item>/g;
+ if ($after != $before && $after != $before + 1) {
+ die "Unexpected appcast item count: before=$before after=$after\n";
+ }
+' "${APPCAST_PATH}" > "${APPCAST_TMP}"
+cat "${APPCAST_TMP}" > "${APPCAST_PATH}"
if command -v xmllint >/dev/null 2>&1; then
xmllint --noout "${APPCAST_PATH}"
diff --git a/appcast.xml b/appcast.xml
index 56dbd56..67a51b7 100644
--- a/appcast.xml
+++ b/appcast.xml
@@ -7,6 +7,15 @@
<link>https://codexbar.zabrian.app/appcast.xml</link>
<description>CodexBar appcast feed</description>
<language>zh-CN</language>
+ <item>
+ <title>CodexBar.app 3.5.2</title>
+ <sparkle:version>56</sparkle:version>
+ <sparkle:shortVersionString>3.5.2</sparkle:shortVersionString>
+ <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+ <sparkle:releaseNotesLink>https://codexbar.zabrian.app/notes#3.5.2</sparkle:releaseNotesLink>
+ <pubDate>Sat, 25 Jul 2026 20:21:25 +0800</pubDate>
+ <enclosure url="https://codexbar.zabrian.app/download/CodexBar-v3.5.2.dmg" sparkle:edSignature="BM53jQdnyfrX5Qy4Ny4dVNcwannh4NWT+mdhSOVTXbZKu5FKMwUr22sC295hzbY5Fu2VgvqhN1OSCSmUPbosDg==" length="5861330" type="application/octet-stream"/>
+ </item>
<item>
<title>CodexBar.app 3.5.1</title>
<sparkle:version>55</sparkle:version>