CodexBar 是一个 macOS 菜单栏应用,用于查看本机 Codex 账号状态、额度、Token 用量、详细统计信息
Swift appkitcodexcodex-clideveloper-toolsmacosmacos-appmenu-bar-appopenai-codexproductivityswiftswiftuiusage-tracker
fix: 完善防睡眠所有权与运行诊断
Bobb128e08a8613
diff --git a/CLAUDE.md b/CLAUDE.mdindex 2bf0d17..a77ac63 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -131,25 +131,35 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev两套机制叠加, 职责不同- `SystemSleepService` 用进程内 `IOPMAssertion` 建立 `PreventUserIdleSystemSleep` 断言, 只挡空闲睡眠, 不需要提权; 断言名必须是 ASCII, 否则 `pmset -g assertions` 显示不出标识-- `CodexBarHelper` 是 root LaunchDaemon, 通过 XPC 接受 `setSleepDisabled` 请求, 执行 `/usr/bin/pmset -a disablesleep` 覆盖合盖睡眠+- `CodexBarHelper` 是 root LaunchDaemon, 通过 XPC 接受 `setSleepPreventionRequested` 请求, 执行 `/usr/bin/pmset -a disablesleep` 覆盖合盖睡眠链路: `KeepAliveController` (MainActor) 订阅 `activityMonitor.$snapshot` 以及合成 `codexHookSettings.isOperable` 的两个发布值 -> `SMAppService.daemon(plistName:)` 注册 -> `NSXPCConnection` -> helper关键约束-- `shouldDisableSleep` 是用户意图与依赖可用性的唯一汇合点, 要求 `isStarted && isEnabled && isHookEnabled && hasRunningTasks && helperStatus == .enabled && !isRefreshingHelper && !isLowBatteryActive && !hasReachedMaximumDuration` 同时成立; **依赖不满足只让效果失效, 绝不回写用户保存的 `isEnabled`**+- `shouldDisableSleep` 是用户意图与依赖可用性的唯一汇合点, 要求 `isStarted && !isPreparingForTermination && isEnabled && isHookEnabled && hasRunningTasks && helperStatus == .enabled && !isRefreshingHelper && !isLowBatteryActive && !hasReachedMaximumDuration` 同时成立; **依赖不满足只让效果失效, 绝不回写用户保存的 `isEnabled`**- Hook 状态在类内只认 `isHookEnabled` 这份镜像, 它跟的是 `codexHookSettings.isOperable`; 不要回读那个属性, 订阅回调跑在 `willSet`, 那一刻它的两个输入里正在变的那一项还是旧值, 只能认 `CombineLatest` 给的闭包参数- 新增拦截条件一律加进 `sleepBlockReason` 的顺序判断里, 它和 `shouldDisableSleep` 同源, 顺带保证日志的 `reason=` 不会漏项- UI 用的 `isLowBatteryBlocking` 与 `canShowOptions` 由 `reconcileSleepState` 从 `sleepBlockReason` 单点派生, 新增拦截条件时 `allowsOptions` 那个穷举 `switch` 会强制表态, 于是不会出现入口亮着却点不动- `hasRunningTasks` 与 `isRefreshingHelper` 都不带 `@Published` 标注, 它们变得比结论频繁, 各自发信号会把整个设置页拖着一起重算- helper 只做一件事; 不要给 root helper 增加网络, 任意命令执行或其他文件访问能力- 调用方校验由 XPC 层强制; helper 启动时用 `SecCodeCopySelf` 读自身签名, 拼出形如 `anchor apple generic and certificate leaf[subject.OU] = "<team>" and identifier "<主 App identifier>"` 的 requirement 字符串, 交给 `NSXPCListener.setConnectionCodeSigningRequirement` 生效; 没有逐次连接的 audit token 检查, 改签名或改 bundle ID 会直接连不上-- 恢复哨兵放在 `/Library/Application Support/CodexBar/<machService>.state` 这个路径, **必须保持 `absent` `present` `unreadable` 三态**, 把读取失败折叠成 nil 会让恢复流程以为无需恢复, 使 `SleepDisabled=1` 永久残留; watchdog 宽限 15 秒, 哨兵自检 60 秒一次+- 所有权记录固定放在 `/Library/Application Support/CodexBar/sleep-ownership.json`, 由 root 在同目录写临时文件, 完成 `F_FULLFSYNC` 后原子替换并同步目录, 权限固定为 `0600`; 只持久化 `idle` `owned` `restoring` 三态, `external` 只是任务期间的运行态, 不落盘也不承担恢复责任+- 当前值为 0 时必须先写 `owned` 再写 `pmset 1`; 释放时必须先写 `restoring` 再写 `pmset 0`; 两次 pmset 都要重新读取 `pmset -g` 确认实际值, 只有确认为 0 才能记回 `idle`+- 任务开始时实际值已为 1 就返回 `external`, 不写 pmset; helper 每 5 秒观察一次, 如果其他来源在任务期间改回 0, helper 立即按上一条顺序取得所有权+- helper 取得所有权后每 5 秒检查一次实际值与磁盘 transaction, 值被改成 0 时重新写回 1, 记录缺失, 损坏或 transaction 不一致时先修复记录; 修复失败也必须继续尝试恢复为 0+- 没有活跃租约时停止短轮询, 只保留 60 秒异常恢复检查; 所有短轮询使用 1 秒 leeway+- 每个 App 进程持有一个跨 XPC 重连不变的 client session ID, 请求再带单调递增的 generation; helper 只释放对应进程的租约并拒绝延迟到达的旧 generation, 不允许旧连接覆盖新状态+- 异常断连后租约宽限 15 秒; 同一 App 在宽限内重连会续上原租约, watchdog 只会释放仍处于断连状态的那一个 client session+- helper 以 `owned` 或 `restoring` 启动时先恢复为 0 再接受新接管; 以 `idle` 启动时不修改当前值, 因为那个值可能属于其他来源+- 更新 helper 前 App 先释放自己的租约, helper 原子确认全局没有活跃客户端且所有权为 `idle`, 再用短期更新准备锁拒绝新的接管; 注册新 helper 后必须收到状态查询回复才记录新指纹, 系统仍在等待首次批准时除外- 切换失败按 2/4/8...256 秒重试, 列表耗尽即放弃 (延时累计约 8.5 分钟, 每轮再等一次超时约 10 分钟), 瞬时抖动能自愈, 权限类故障不该无限重试-- XPC 请求带超时并汇进同一条重试路径; launchd 拉不起 helper 时 `setSleepDisabled` 既不回复也不触发 errorHandler, 没有它界面会显示防睡眠开着而实际没生效, 日志里只剩没有配对回复的 `Helper XPC 请求已发送`+- XPC 请求带超时并汇进同一条重试路径; launchd 拉不起 helper 时 XPC 方法既不回复也不触发 errorHandler, 没有它界面会显示防睡眠开着而实际没生效, 日志里只剩没有配对回复的 `Helper XPC 请求已发送`- 超时取值放在 `CodexBarHelperIPC.requestTimeoutSeconds` 而不是控制器里, 它与 `watchdogGraceSeconds` 是一对: 必须更小, App 先放手 helper 才能靠 watchdog 兜底, 分处两个 module 会让人改了一边不知道另一边- 开发期间用 `xcodebuild` 覆盖正在运行的 App bundle 会让 launchd 记的 daemon 与磁盘上的 helper 对不上, helper 从此拉不起来; 重启 App 会由 `helperRegistrationNeedsRefresh` 的指纹比对自愈, 排查时先看这一条-- helper 回传的 `restoredSleepDisabled` 只有 `.present` 分支是实测值, `.absent` (本轮没接管过) 与 pmset 失败时都是占位的 `true`; App 侧靠 `canTrustRestoreResult` (接管到恢复之间连接未断) 判断可不可信, 这是从未接管的一轮里不误发 `IOPMSleepSystem` 的唯一屏障, 不要把 `.absent` 改成回实测值+- helper 回传 `none` `external` `codexBar` 来源与操作后的实测值; App 只能在 `codexBar` 且实测为 0 时宣称系统睡眠已恢复或补发 `IOPMSleepSystem`, `external` 和 `none` 都只释放进程内断言+- App 退出由 `applicationShouldTerminate` 返回 `terminateLater`, 先冻结新接管并等 helper 释放回复再继续退出; helper 刷新同样先释放, 旧 helper 无响应时由新 helper 的启动恢复兜底+- `pmset` 是没有来源和引用计数的全局布尔值; CodexBar 取得所有权后如果另一个 App 也开始依赖这个 1, 释放时仍会恢复为 0, 系统层没有无歧义的方法判断另一个 App 的意图- 低电量保护由 `PowerSourceMonitor` 供数, 它只报事实 (有没有内置电池, 电量, 是否靠电池供电), 不知道阈值; 读数保持 `unavailable` `unreadable` `present` 三态, 把读取失败折叠成"没有电池"会让设置项凭空消失且保护静默失效- 见过一次内置电池就记住 `hasSeenBattery`, 之后读到空列表只能返回 `unreadable`; 硬件不会中途消失, 空列表只是 IOKit 重新枚举时的缺口, 当成台式机会当场撤掉保护- `hasSeenBattery` 只活在进程内不持久化, 每次启动重新判定; 笔记本启动时撞上枚举缺口会短暂显示成没有电池, 由下一次电源通知自愈, 而持久化会让从笔记本备份恢复的台式机永远多出低电量设置项@@ -161,7 +171,7 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev- 低电量必须同时满足在用电池与电量低于阈值, 只看百分比会让"剩 5% 插上电再跑任务"当场被判低电量; 判定用 `Power Source State`, 不能用 `Is Charging` (接电停充时它也是 false)- 电量读不到时维持上一次的判定, 从没读到过就是不触发: 误触发会当场断掉用户任务, 漏触发最坏也有系统强制睡眠兜底- 已经在低电量保护中时读数失败不清零, 否则一次瞬时失败会绕过滞回, 让防睡眠反复开关并重发通知-- 低电量通知只在 `isActivelyPreventingSleep` 为真时排队, 没挡过就不说"已恢复系统睡眠"; 日志无条件记并用 `action=release|none` 区分, 百分比只有那一条能看到+- 低电量通知只在 `isActivelyPreventingSleep` 为真且来源是 `codexBar` 时排队, 外部来源不说"已恢复系统睡眠"; 日志无条件记并用 `action=release|none` 区分, 百分比只有那一条能看到- 排队的通知要等 helper 恢复睡眠的 XPC 回复确认成功才发得出去, 恢复失败走重试直至放弃, 提前说"已恢复系统睡眠"会把用户骗去合盖然后把电耗干- 补发 `IOPMSleepSystem` 之前还要 `await` 到通知真的提交完成, 只把提交排进下一个 MainActor job 的话同一个 job 里的补发会抢在它前面- 那次 `await` 之后要重认一次 `generation` 再走 `finishSleepRestore` 这一步, 挂起期间可能已有新的禁用请求接管, 否则会释放掉刚建立的空闲断言@@ -171,8 +181,8 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev- `hasNotifiedLowBattery` 只在通知真的提交成功之后才置位, 打在入队处或提交前都会让没送达的那一条吃掉整轮配额, 使这一轮之后真正触发的低电量再也提醒不了- `hasNotifiedLowBattery` 只管通知不管判定, 与上面"纯条件"不冲突: 电量回到解除门槛以下再跌破仍算同一轮, 不会重复提醒- `SleepConditions` 里只放 `battery` 布尔, 放电量百分比会让每掉 1% 刷一条变化日志; 真实电量只在触发那一条单独记-- 状态只呈现在主面板活动卡片右侧的咖啡杯标记 (带 tooltip), 由 `KeepAliveController.isActivelyPreventingSleep` 驱动, 卡片折叠成"暂无数据"时标记要跟着一起收-- 设置页那一行说明只在异常, 低电量生效或达到上限时出现, 正常运行时整行收起, `keepAliveCaption` 返回 nil 即代表收起+- 状态只呈现在主面板活动卡片右侧的咖啡杯标记 (带 tooltip), 由 `KeepAliveController.isActivelyPreventingSleep` 驱动, `sleepPreventionSource` 区分外部来源与 CodexBar 所有权, 卡片折叠成"暂无数据"时标记要跟着一起收+- 设置页那一行说明只在异常, 外部来源, 低电量生效或达到上限时出现, CodexBar 自己正常持有所有权时整行收起, `keepAliveCaption` 返回 nil 即代表收起- 最长防睡眠时间与低电量阈值都在防睡眠子面板里, 台式机读不到电池时低电量那一行整行隐藏而不是置灰- 保持屏幕常亮跟 `isActivelyPreventingSleep` 走, 由 `reconcileDisplayAwake` 单点切换, 于是低电量拦下, 达到上限, 任务结束时屏幕都跟着放开- 显示断言只保证屏幕不睡, 屏保与闲置锁屏跟的是系统 idle 计时, 要靠 30 秒一次的 `IOPMAssertionDeclareUserActivity` 压住, 两者缺一不可diff --git a/CodexBar/Controllers/GlobalHotKeyController.swift b/CodexBar/Controllers/GlobalHotKeyController.swiftindex 19a925c..0490119 100644--- a/CodexBar/Controllers/GlobalHotKeyController.swift+++ b/CodexBar/Controllers/GlobalHotKeyController.swift@@ -46,7 +46,11 @@ final class GlobalHotKeyController {guard status == noErr else {// 最常见的原因是快捷键已被其他 App 占用, 用户只会看到"按了没反应"- AppLog.settings.error("快捷键注册失败: stage=register; code=\(status)")+ let details = LogFields.joined(+ "stage=register",+ "code=\(status)"+ )+ AppLog.settings.error("快捷键注册失败: \(details, privacy: .public)")GlobalHotKeyRegistration.remove(hotKeyRef: nil, eventHandlerRef: installedHandlerRef)return false}diff --git a/CodexBar/Controllers/StatusItemController.swift b/CodexBar/Controllers/StatusItemController.swiftindex 330f055..1c775d0 100644--- a/CodexBar/Controllers/StatusItemController.swift+++ b/CodexBar/Controllers/StatusItemController.swift@@ -27,6 +27,8 @@ final class CodexBarAppDelegate: NSObject, NSApplicationDelegate {private var statusItemController: StatusItemController?private var notificationService: CodexNotificationService?+ private var terminationPreparationTask: Task<Void, Never>?+ private var hasPreparedForTermination = false// MARK: - App 生命周期@@ -73,12 +75,38 @@ final class CodexBarAppDelegate: NSObject, NSApplicationDelegate {func applicationWillTerminate(_: Notification) {AppLog.app.notice("App 即将退出: reason=userQuit")+ terminationPreparationTask?.cancel()+ terminationPreparationTask = nilAppProcessDiagnostics.recordCleanExit()statusItemController?.uninstall()keepAliveController.stop()activityMonitor.stop()}+ func applicationShouldTerminate(_: NSApplication) -> NSApplication.TerminateReply {+ if hasPreparedForTermination {+ return .terminateNow+ }+ if terminationPreparationTask != nil {+ return .terminateLater+ }++ terminationPreparationTask = Task { @MainActor [weak self] in+ guard let self else {+ NSApplication.shared.reply(toApplicationShouldTerminate: false)+ return+ }+ let success = await keepAliveController.prepareForTermination()+ guard !Task.isCancelled else {+ return+ }+ terminationPreparationTask = nil+ hasPreparedForTermination = success+ NSApplication.shared.reply(toApplicationShouldTerminate: success)+ }+ return .terminateLater+ }+/// 启动时把各开关的初始值记成一条基线, 之后的变更日志都是相对这条基线的增量/// 排查时先看这条就知道当时的配置, 不必让用户逐项回忆private func logLaunchState() {@@ -96,9 +124,22 @@ final class CodexBarAppDelegate: NSObject, NSApplicationDelegate {let menuBarQuota = menuBarQuotaSettings.selection.rawValuelet taskCenter = mainPanelSettings.showsTaskCenter ? 1 : 0let hotKey = globalHotKeySettings.shortcut == nil ? 0 : 1- AppLog.app.notice(- "App 已启动: version=\(version, privacy: .public); build=\(build, privacy: .public); hook=\(hook); keepAlive=\(keepAlive); keepAliveLimit=\(keepAliveLimit); keepAliveBattery=\(keepAliveBattery); keepAliveWaiting=\(keepAliveWaiting); keepAliveDisplay=\(keepAliveDisplay); sync=\(sync); notification=\(notification); menuBarQuota=\(menuBarQuota, privacy: .public); taskCenter=\(taskCenter); hotKey=\(hotKey)"+ let state = LogFields.joined(+ "version=\(version)",+ "build=\(build)",+ "hook=\(hook)",+ "keepAlive=\(keepAlive)",+ "keepAliveLimit=\(keepAliveLimit)",+ "keepAliveBattery=\(keepAliveBattery)",+ "keepAliveWaiting=\(keepAliveWaiting)",+ "keepAliveDisplay=\(keepAliveDisplay)",+ "sync=\(sync)",+ "notification=\(notification)",+ "menuBarQuota=\(menuBarQuota)",+ "taskCenter=\(taskCenter)",+ "hotKey=\(hotKey)")+ AppLog.app.notice("App 已启动: \(state, privacy: .public)")}func openSettingsFromCommand() {diff --git a/CodexBar/Resources/Info.plist b/CodexBar/Resources/Info.plistindex 2805f2e..6dd478b 100644--- a/CodexBar/Resources/Info.plist+++ b/CodexBar/Resources/Info.plist@@ -26,6 +26,8 @@<string>public.app-category.developer-tools</string><key>LSMinimumSystemVersion</key><string>$(MACOSX_DEPLOYMENT_TARGET)</string>+ <key>LSMultipleInstancesProhibited</key>+ <true/><key>LSUIElement</key><true/><key>NSHumanReadableCopyright</key>diff --git a/CodexBar/Resources/Localizable.xcstrings b/CodexBar/Resources/Localizable.xcstringsindex 5b821da..bfef094 100644--- a/CodexBar/Resources/Localizable.xcstrings+++ b/CodexBar/Resources/Localizable.xcstrings@@ -3522,6 +3522,22 @@}}},+ "系统睡眠已由其他来源关闭" : {+ "localizations" : {+ "en" : {+ "stringUnit" : {+ "state" : "translated",+ "value" : "System sleep is disabled by another source"+ }+ },+ "zh-Hans" : {+ "stringUnit" : {+ "state" : "translated",+ "value" : "系统睡眠已由其他来源关闭"+ }+ }+ }+ },"系统通知" : {"localizations" : {"en" : {diff --git a/CodexBar/Services/CodexCLI/CodexCLIVersionService.swift b/CodexBar/Services/CodexCLI/CodexCLIVersionService.swiftindex a86e473..34199f3 100644--- a/CodexBar/Services/CodexCLI/CodexCLIVersionService.swift+++ b/CodexBar/Services/CodexCLI/CodexCLIVersionService.swift@@ -188,8 +188,10 @@ actor CodexCLIVersionService {} catch {process.terminationHandler = nilstopCollectors(outputCollector: outputCollector, errorCollector: errorCollector)- AppLog.codexCLI.error(- "版本检测失败: source=\(source.rawValue, privacy: .public); stage=launch; detail=\(error.localizedDescription, privacy: .public)"+ logVersionDetectionFailure(+ source: source,+ stage: "launch",+ detail: error.localizedDescription)return failedVersionItem(source: source, path: path, failure: .launch)}@@ -203,7 +205,7 @@ actor CodexCLIVersionService {outputCollector: outputCollector,errorCollector: errorCollector)- AppLog.codexCLI.error("版本检测失败: source=\(source.rawValue, privacy: .public); stage=timeout")+ logVersionDetectionFailure(source: source, stage: "timeout")return failedVersionItem(source: source, path: path, failure: .timeout)}@@ -211,21 +213,21 @@ actor CodexCLIVersionService {let errorOutput = collectedText(from: errorCollector, deadline: deadline)guard process.terminationStatus == 0 else {- AppLog.codexCLI.error(- "版本检测失败: source=\(source.rawValue, privacy: .public); stage=exit; exit=\(process.terminationStatus)"+ logVersionDetectionFailure(+ source: source,+ stage: "exit",+ exitCode: process.terminationStatus)return failedVersionItem(source: source, path: path, failure: .read)}guard let version = firstLine(in: output) ?? firstLine(in: errorOutput) else {- AppLog.codexCLI.error("版本检测失败: source=\(source.rawValue, privacy: .public); stage=parse")+ logVersionDetectionFailure(source: source, stage: "parse")return failedVersionItem(source: source, path: path, failure: .parse)}let displayVersion = CodexCLIVersionReader.displayVersion(from: version)- AppLog.codexCLI.notice(- "版本检测完成: source=\(source.rawValue, privacy: .public); version=\(displayVersion, privacy: .public)"- )+ logVersionDetectionCompleted(source: source, version: displayVersion)return CodexCLIVersionItem(source: source,path: path,@@ -233,6 +235,37 @@ actor CodexCLIVersionService {)}+ private static func logVersionDetectionFailure(+ source: CodexCLIExecutableSource,+ stage: String,+ exitCode: Int32? = nil,+ detail: String? = nil+ ) {+ var fields = [+ "source=\(source.rawValue)",+ "stage=\(stage)"+ ]+ if let exitCode {+ fields.append("exit=\(exitCode)")+ }+ if let detail {+ fields.append("detail=\(detail)")+ }+ let details = LogFields.joined(fields)+ AppLog.codexCLI.error("版本检测失败: \(details, privacy: .public)")+ }++ private static func logVersionDetectionCompleted(+ source: CodexCLIExecutableSource,+ version: String+ ) {+ let details = LogFields.joined(+ "source=\(source.rawValue)",+ "version=\(version)"+ )+ AppLog.codexCLI.notice("版本检测完成: \(details, privacy: .public)")+ }+private static func terminateTimedOutProbe(process: Process,outputCollector: PipeReadBuffer,diff --git a/CodexBar/Services/CodexStatus/CodexStatusService.swift b/CodexBar/Services/CodexStatus/CodexStatusService.swiftindex 48bdc99..526a8f2 100644--- a/CodexBar/Services/CodexStatus/CodexStatusService.swift+++ b/CodexBar/Services/CodexStatus/CodexStatusService.swift@@ -268,9 +268,11 @@ actor CodexStatusService {do {command = try CodexCLIResolver.resolveAppServerCommand(environment: Self.environment)} catch {- AppLog.app.error(- "codex 连接失败: stage=resolveCLI; detail=\(error.localizedDescription, privacy: .public)"+ let details = LogFields.joined(+ "stage=resolveCLI",+ "detail=\(error.localizedDescription)")+ AppLog.app.error("codex 连接失败: \(details, privacy: .public)")RequestLogStorage.shared.recordFailure(message: error.localizedDescription)return .initializationFailed}@@ -433,17 +435,21 @@ actor CodexStatusService {do {try refreshTokenIfNeeded()} catch {- AppLog.app.error(- "重置次数查询失败: stage=refreshToken; detail=\(error.localizedDescription, privacy: .public)"+ let details = LogFields.joined(+ "stage=refreshToken",+ "detail=\(error.localizedDescription)")+ AppLog.app.error("重置次数查询失败: \(details, privacy: .public)")return nil}return try? await fetchExpirationDates()} catch {- AppLog.app.error(- "重置次数查询失败: stage=fetch; detail=\(error.localizedDescription, privacy: .public)"+ let details = LogFields.joined(+ "stage=fetch",+ "detail=\(error.localizedDescription)")+ AppLog.app.error("重置次数查询失败: \(details, privacy: .public)")return nil}}diff --git a/CodexBar/Services/CodexStatus/CodexStatusViewModel.swift b/CodexBar/Services/CodexStatus/CodexStatusViewModel.swiftindex 13f1fec..e8da400 100644--- a/CodexBar/Services/CodexStatus/CodexStatusViewModel.swift+++ b/CodexBar/Services/CodexStatus/CodexStatusViewModel.swift@@ -135,19 +135,34 @@ final class CodexStatusViewModel: ObservableObject {let rateLimits = trace.rateLimits?.rawValue ?? "-"let usage = trace.usage?.rawValue ?? "-"let resetCredits = trace.resetCredits?.rawValue ?? "-"- AppLog.app.notice(- "额度刷新完成: trigger=\(triggerName, privacy: .public); state=\(state, privacy: .public); conn=\(connection, privacy: .public); account=\(account, privacy: .public); rateLimits=\(rateLimits, privacy: .public); usage=\(usage, privacy: .public); reset=\(resetCredits, privacy: .public); elapsed=\(elapsed, privacy: .public)"+ let details = LogFields.joined(+ "trigger=\(triggerName)",+ "state=\(state)",+ "conn=\(connection)",+ "account=\(account)",+ "rateLimits=\(rateLimits)",+ "usage=\(usage)",+ "reset=\(resetCredits)",+ "elapsed=\(elapsed)")+ AppLog.app.notice("额度刷新完成: \(details, privacy: .public)")case .notLoggedIn:// 未登录是正常状态, 混进失败词根会让每分钟一条噪声盖掉真故障- AppLog.app.notice(- "额度刷新已跳过: trigger=\(triggerName, privacy: .public); reason=notLoggedIn; elapsed=\(elapsed, privacy: .public)"+ let details = LogFields.joined(+ "trigger=\(triggerName)",+ "reason=notLoggedIn",+ "elapsed=\(elapsed)")+ AppLog.app.notice("额度刷新已跳过: \(details, privacy: .public)")case .initializationFailed, .loading:let stage = trace.failureStage?.rawValue ?? "-"- AppLog.app.error(- "额度刷新失败: trigger=\(triggerName, privacy: .public); stage=\(stage, privacy: .public); state=\(state, privacy: .public); elapsed=\(elapsed, privacy: .public)"+ let details = LogFields.joined(+ "trigger=\(triggerName)",+ "stage=\(stage)",+ "state=\(state)",+ "elapsed=\(elapsed)")+ AppLog.app.error("额度刷新失败: \(details, privacy: .public)")}}diff --git a/CodexBar/Services/KeepAlive/HelperRuntimeStatusMonitor.swift b/CodexBar/Services/KeepAlive/HelperRuntimeStatusMonitor.swiftnew file mode 100644index 0000000..02bc268--- /dev/null+++ b/CodexBar/Services/KeepAlive/HelperRuntimeStatusMonitor.swift@@ -0,0 +1,266 @@+import Foundation+import os++struct HelperRuntimeStatus {+ let ownership: CodexBarSleepOwnershipState+ let activeClientCount: Int+ let sleepDisabled: Bool++ var externalObservationAction: ExternalObservationAction {+ if ownership == .owned, activeClientCount > 0, sleepDisabled {+ return .sourceBecameCodexBar+ }+ if !sleepDisabled, ownership != .restoring {+ return .reacquireLease+ }+ return .none+ }++ enum ExternalObservationAction {+ case none+ case sourceBecameCodexBar+ case reacquireLease+ }+}++@MainActor+final class HelperRuntimeStatusMonitor {+ private(set) var isRequestInFlight = false++ private var requestGeneration: UInt64 = 0+ private var requestContinuation: CheckedContinuation<RequestResult?, Never>?+ private var requestTimeoutTask: Task<Void, Never>?+ private var observationTask: Task<Void, Never>?+ private var observationToken: UUID?++ func fetch(+ connection: NSXPCConnection,+ timeout: Duration,+ onConnectionFailure: @escaping (Error) -> Void,+ onTimeout: @escaping () -> Void+ ) async -> HelperRuntimeStatus? {+ let result = await performRequest(+ connection: connection,+ operation: .status,+ timeout: timeout+ )+ switch result {+ case let .status(status):+ return status+ case let .connectionFailure(error):+ onConnectionFailure(error)+ case let .invalidResponse(exitCode, ownership, activeClientCount):+ let details = LogFields.joined(+ "exit=\(exitCode)",+ "ownership=\(ownership)",+ "clients=\(activeClientCount)"+ )+ AppLog.keepAlive.error(+ "Helper 运行状态无效: \(details, privacy: .public)"+ )+ case .timedOut:+ let wait = LogDuration.seconds(timeout)+ AppLog.keepAlive.error(+ "Helper 状态请求超时: timeout=\(wait, privacy: .public)"+ )+ onTimeout()+ case .updateReset:+ break+ case nil:+ break+ }+ return nil+ }++ func resetSleepAfterUpdate(+ connection: NSXPCConnection,+ updateIdentifier: String,+ timeout: Duration,+ onConnectionFailure: @escaping (Error) -> Void,+ onTimeout: @escaping () -> Void+ ) async -> Bool {+ let result = await performRequest(+ connection: connection,+ operation: .updateReset(updateIdentifier),+ timeout: timeout+ )+ switch result {+ case let .updateReset(exitCode):+ guard exitCode == 0 else {+ AppLog.keepAlive.error(+ "Helper 更新后的睡眠重置失败: exit=\(exitCode)"+ )+ return false+ }+ return true+ case let .connectionFailure(error):+ onConnectionFailure(error)+ case .timedOut:+ let wait = LogDuration.seconds(timeout)+ AppLog.keepAlive.error(+ "Helper 更新后的睡眠重置超时: timeout=\(wait, privacy: .public)"+ )+ onTimeout()+ case .status, .invalidResponse, nil:+ break+ }+ return false+ }++ func startObservation(+ interval: Duration,+ action: @escaping @MainActor () async -> Void+ ) {+ guard observationTask == nil else {+ return+ }++ let token = UUID()+ observationToken = token+ observationTask = Task { @MainActor [weak self] in+ while !Task.isCancelled {+ try? await Task.sleep(for: interval)+ guard !Task.isCancelled else {+ break+ }+ await action()+ }+ guard let self, observationToken == token else {+ return+ }+ observationTask = nil+ observationToken = nil+ }+ }++ func cancelObservation() {+ observationTask?.cancel()+ observationTask = nil+ observationToken = nil+ }++ func cancelRequest() {+ guard isRequestInFlight else {+ return+ }+ requestGeneration &+= 1+ finishRequest(nil, generation: requestGeneration)+ }++ private func performRequest(+ connection: NSXPCConnection,+ operation: RequestOperation,+ timeout: Duration+ ) async -> RequestResult? {+ guard !isRequestInFlight else {+ return nil+ }++ return await withCheckedContinuation { continuation in+ isRequestInFlight = true+ requestGeneration &+= 1+ let generation = requestGeneration+ requestContinuation = continuation++ requestTimeoutTask = Task { @MainActor [weak self] in+ try? await Task.sleep(for: timeout)+ guard !Task.isCancelled else {+ return+ }+ self?.finishRequest(.timedOut, generation: generation)+ }++ let errorHandler: (Error) -> Void = { [weak self] error in+ Task { @MainActor in+ self?.finishRequest(+ .connectionFailure(error),+ generation: generation+ )+ }+ }+ guard let helper = connection.remoteObjectProxyWithErrorHandler(errorHandler)+ as? CodexBarHelperProtocol else {+ finishRequest(.connectionFailure(RequestError.invalidProxy), generation: generation)+ return+ }++ switch operation {+ case .status:+ let reply: @Sendable (Int32, Int, Int, Bool) -> Void = { [weak self] exitCode, ownershipRawValue, activeClientCount, sleepDisabled in+ Task { @MainActor in+ guard exitCode == 0,+ let ownership = CodexBarSleepOwnershipState(+ rawValue: ownershipRawValue+ ),+ activeClientCount >= 0 else {+ self?.finishRequest(+ .invalidResponse(+ exitCode: exitCode,+ ownership: ownershipRawValue,+ activeClientCount: activeClientCount+ ),+ generation: generation+ )+ return+ }+ self?.finishRequest(+ .status(+ HelperRuntimeStatus(+ ownership: ownership,+ activeClientCount: activeClientCount,+ sleepDisabled: sleepDisabled+ )+ ),+ generation: generation+ )+ }+ }+ helper.getSleepPreventionStatus(reply: reply)+ case let .updateReset(updateIdentifier):+ let reply: @Sendable (Int32) -> Void = { [weak self] exitCode in+ Task { @MainActor in+ self?.finishRequest(+ .updateReset(exitCode: exitCode),+ generation: generation+ )+ }+ }+ helper.resetSleepAfterUpdate(updateIdentifier, reply: reply)+ }+ }+ }++ private func finishRequest(_ result: RequestResult?, generation: UInt64) {+ guard generation == requestGeneration, isRequestInFlight else {+ return+ }++ requestTimeoutTask?.cancel()+ requestTimeoutTask = nil+ isRequestInFlight = false+ let continuation = requestContinuation+ requestContinuation = nil+ continuation?.resume(returning: result)+ }++ private enum RequestResult {+ case status(HelperRuntimeStatus)+ case updateReset(exitCode: Int32)+ case connectionFailure(Error)+ case invalidResponse(exitCode: Int32, ownership: Int, activeClientCount: Int)+ case timedOut+ }++ private enum RequestOperation {+ case status+ case updateReset(String)+ }++ private enum RequestError: LocalizedError {+ case invalidProxy++ var errorDescription: String? {+ "服务接口无效"+ }+ }+}diff --git a/CodexBar/Services/KeepAlive/KeepAliveController.swift b/CodexBar/Services/KeepAlive/KeepAliveController.swiftindex 5d3ab45..afd0718 100644--- a/CodexBar/Services/KeepAlive/KeepAliveController.swift+++ b/CodexBar/Services/KeepAlive/KeepAliveController.swift@@ -1,6 +1,5 @@import AppKitimport Combine-import CryptoKitimport Foundationimport IOKitimport os@@ -11,6 +10,7 @@ final class KeepAliveController: ObservableObject {@Published private(set) var isEnabled: Bool@Published private(set) var helperStatus = HelperStatus.notRegistered@Published private(set) var isPreventingSleep = false+ @Published private(set) var sleepPreventionSource = CodexBarSleepPreventionSource.none@Published private(set) var lowBatteryThreshold: LowBatteryThreshold/// 等待批准的任务算不算"有任务", 决定审批期间要不要继续挡住睡眠@Published private(set) var keepsAwakeWhileWaiting: Bool@@ -91,16 +91,18 @@ final class KeepAliveController: ObservableObject {/// 最近一份快照中的等待任务, 用于识别等待批准后恢复运行的状态转换/// 开着 keepsAwakeWhileWaiting 时它同时是"有没有任务撑着防睡眠"的另一半输入private var waitingTaskIDs = Set<UUID>()+ /// 同一 App 进程内跨 XPC 重连保持不变, helper 据此把连接变化与租约所有权分开+ private let helperClientSessionID = UUID().uuidStringprivate var connection: NSXPCConnection?- /// 本轮接管以来连接没有断过, helper 那边的哨兵必然还在- /// 断过就可能是 helper 已经自行恢复并清掉哨兵, 那之后拿到的回复只是占位值, 不是实测状态- /// 能这样判断是因为哨兵只由 helper 侧的恢复删除, 而那些路径都要求连接已断- private var canTrustRestoreResult = false- private var appliedSleepDisabled: Bool?+ private var appliedSleepPreventionRequested: Bool?+ /// true 请求可能已被 helper 接收却丢了回复, 只有一次成功的 false 才能清除这个可能性+ private var mayHaveHelperLease = falseprivate var requestInFlight = falseprivate var requestGeneration: UInt64 = 0+ private var pendingRequestCompletion: ((Bool) -> Void)?private var retryTask: Task<Void, Never>?private var requestTimeoutTask: Task<Void, Never>?+ private let helperRuntimeStatusMonitor = HelperRuntimeStatusMonitor()private var retryAttempt = 0private var helperRegistrationTask: Task<Void, Never>?/// 与 hasRunningTasks 同理: 只经由派生状态影响 UI, 自己不发信号@@ -116,6 +118,7 @@ final class KeepAliveController: ObservableObject {private var pendingKeepAliveLimit: MaximumDuration?private var cancellables = Set<AnyCancellable>()private var isStarted = false+ private var isPreparingForTermination = falseprivate var lastLoggedSleepConditions: SleepConditions?/// codexHookSettings.isOperable 的最新值, 由订阅维护/// 不直接读那个属性: 订阅回调跑在 willSet, 那时它还是改动前的值@@ -129,6 +132,7 @@ final class KeepAliveController: ObservableObject {case noTaskscase helperUnavailablecase helperRefreshing+ case terminatingcase lowBatterycase limitReached}@@ -229,6 +233,7 @@ final class KeepAliveController: ObservableObject {cancellables.removeAll()cancelRetryTask()cancelHelperRegistrationTask()+ cancelExternalObservation()startedRunningTaskIDs.removeAll()waitingTaskIDs.removeAll()durationLimiter.stop()@@ -237,12 +242,34 @@ final class KeepAliveController: ObservableObject {clearPendingLowBatteryNotification()pendingKeepAliveLimit = nil- if connection != nil {- applySleepDisabled(false)- }invalidateConnection()}+ /// App 退出时先等 root 侧把已取得的所有权恢复为 0+ /// 如果本轮只是外部来源, helper 会成功回复但不写 pmset+ func prepareForTermination() async -> Bool {+ guard isStarted else {+ return true+ }+ guard !isPreparingForTermination else {+ return false+ }++ isPreparingForTermination = true+ cancelRetryTask()+ cancelHelperRegistrationTask()+ cancelExternalObservation()+ let success = await releaseHelperLeaseIfNeeded(trigger: .termination)+ guard !success else {+ return true+ }++ // 退出被取消时恢复正常状态, 不能让一次失败把运行中的任务永久放开+ isPreparingForTermination = false+ reconcileSleepState(trigger: .termination, force: true)+ return false+ }+func refresh() {// 电源监听注册失败并降级成轮询时, 这是唯一还会即时重读电量的路径powerSourceMonitor.refresh()@@ -250,6 +277,11 @@ final class KeepAliveController: ObservableObject {}private func refreshRegistrationAndSleepState() {+ guard helperRegistrationTask == nil else {+ reconcileSleepState(trigger: .statusRefresh)+ return+ }+refreshHelperStatus()if isEnabled || helperStatus.isRegisteredOrAwaitingApproval {ensureHelperRegistration(opensSystemSettings: false)@@ -402,9 +434,13 @@ final class KeepAliveController: ObservableObject {// 百分比只在这里记一次; 放进 SleepConditions 会让每掉 1% 刷一条// 本来就没在挡睡眠时这一跌不改变任何事, 但仍要记: 这是排查"为什么在这个电量断的"的唯一依据let wasPreventingSleep = isActivelyPreventingSleep- AppLog.keepAlive.notice(- "KeepAlive 电量已触及阈值: percent=\(status.percent); threshold=\(threshold); action=\(wasPreventingSleep ? "release" : "none", privacy: .public)"+ && sleepPreventionSource == .codexBar+ let details = LogFields.joined(+ "percent=\(status.percent)",+ "threshold=\(threshold)",+ "action=\(wasPreventingSleep ? "release" : "none")")+ AppLog.keepAlive.notice("KeepAlive 电量已触及阈值: \(details, privacy: .public)")// 没挡过就不通知: "已恢复系统睡眠"会变成一句空话, 启动时电量本就偏低的机器首当其冲guard wasPreventingSleep, !hasNotifiedLowBattery else {@@ -498,19 +534,28 @@ final class KeepAliveController: ObservableObject {}private func ensureHelperRegistration(opensSystemSettings: Bool) {- let service = Self.helperService+ guard helperRegistrationTask == nil else {+ return+ }++ let service = KeepAliveHelperConfiguration.servicerefreshHelperStatus()switch helperStatus {case .enabled, .requiresApproval:- if helperRegistrationNeedsRefresh {+ if KeepAliveHelperConfiguration.registrationNeedsRefresh(defaults: defaults) {refreshRegisteredHelper(opensSystemSettings: opensSystemSettings)+ } else if helperStatus == .enabled,+ let updateIdentifier = KeepAliveHelperConfiguration.pendingUpdateIdentifier(+ defaults: defaults+ ) {+ completePendingHelperUpdate(updateIdentifier)} else if helperStatus == .requiresApproval, opensSystemSettings {openSystemSettings()}returncase .notRegistered, .notFound:- guard Self.helperAssetsArePresent else {+ guard KeepAliveHelperConfiguration.assetsArePresent else {registrationErrorMessage = KeepAliveLocalizedMessage.helperAssetsMissingreturn}@@ -530,35 +575,50 @@ final class KeepAliveController: ObservableObject {}refreshHelperStatus()- recordHelperRegistrationIfCurrent()+ KeepAliveHelperConfiguration.recordRegistration(defaults: defaults, status: helperStatus)+ if helperStatus == .enabled,+ let updateIdentifier = KeepAliveHelperConfiguration.pendingUpdateIdentifier(+ defaults: defaults+ ) {+ completePendingHelperUpdate(updateIdentifier)+ }if helperStatus == .requiresApproval, opensSystemSettings {openSystemSettings()}}private func refreshRegisteredHelper(opensSystemSettings: Bool) {+ let requiresSleepReset = helperStatus == .enabledguard helperRegistrationTask == nil,- Self.helperAssetsArePresent else {+ KeepAliveHelperConfiguration.assetsArePresent,+ let updateIdentifier = KeepAliveHelperConfiguration.beginUpdate(+ defaults: defaults,+ requiresSleepReset: requiresSleepReset+ ) else {return}assign(true, to: \.isRefreshingHelper)cancelRetryTask()+ cancelExternalObservation()invalidateConnection()- // 连接已失效, 重试也取消了, 之前的操作类错误已经过期+ // 刷新期间已冻结新接管, 旧 helper 由 unregister 终止registrationErrorMessage = niloperationErrorMessage = nil- let service = Self.helperService+ let service = KeepAliveHelperConfiguration.servicehelperRegistrationTask = Task { @MainActor [weak self] inguard let self else {return}+ var didUnregisterHelper = falsevar registrationError: Error?do {try Task.checkCancellation()try await service.unregister()+ didUnregisterHelper = true+ mayHaveHelperLease = falsetry Task.checkCancellation()try await registerRefreshedHelper(service)} catch is CancellationError {@@ -572,16 +632,31 @@ final class KeepAliveController: ObservableObject {}refreshHelperStatus()- if helperStatus.isRegisteredOrAwaitingApproval {- recordHelperRegistrationIfCurrent()- } else if let registrationError {+ var helperWasUpdated = false+ if didUnregisterHelper, helperStatus.isRegisteredOrAwaitingApproval {+ KeepAliveHelperConfiguration.recordRegistration(+ defaults: defaults,+ status: helperStatus+ )+ if !requiresSleepReset {+ helperWasUpdated = true+ } else if helperStatus == .enabled {+ helperWasUpdated = await completeHelperUpdate(updateIdentifier)+ } else {+ // 从 enabled 更新后若需要系统批准, 一次性重置会在批准后继续+ helperWasUpdated = true+ }+ }++ if !helperWasUpdated {+ let detail = registrationError?.localizedDescription ?? "readinessFailed"AppLog.keepAlive.error(- "Helper 注册更新失败: detail=\(registrationError.localizedDescription, privacy: .public)"+ "Helper 注册更新失败: detail=\(detail, privacy: .public)")registrationErrorMessage = KeepAliveLocalizedMessage.updateFailed}- assign(false, to: \.isRefreshingHelper)+ assign(!helperWasUpdated && helperStatus == .enabled, to: \.isRefreshingHelper)helperRegistrationTask = nilif helperStatus == .requiresApproval, opensSystemSettings {openSystemSettings()@@ -593,13 +668,17 @@ final class KeepAliveController: ObservableObject {private func registerRefreshedHelper(_ service: SMAppService) async throws {await Task.yield()- var retryDelays = Self.helperRegistrationRetryDelays.makeIterator()+ var retryDelays = KeepAliveHelperConfiguration.registrationRetryDelays.makeIterator()while true {do {try service.register()return} catch {- guard Self.isTransientHelperRegistrationError(error),+ let status = HelperStatus(service.status)+ if status.isRegisteredOrAwaitingApproval {+ return+ }+ guard KeepAliveHelperConfiguration.isTransientRegistrationError(error),let retryDelay = retryDelays.next() else {throw error}@@ -622,22 +701,18 @@ final class KeepAliveController: ObservableObject {self[keyPath: keyPath] = value}- private static func isTransientHelperRegistrationError(_ error: Error) -> Bool {- let error = error as NSError- return error.domain == SMAppServiceErrorDomain- && error.code == operationNotPermittedErrorCode- }-private func refreshHelperStatus() {let previousStatus = helperStatus- assign(HelperStatus(Self.helperService.status), to: \.helperStatus)+ assign(HelperStatus(KeepAliveHelperConfiguration.service.status), to: \.helperStatus)// 每次 App 激活都会跑, 只记真正的迁移, 否则日志会被无变化的求值淹没// 取局部量再插值: Logger 的插值是 autoclosure, 直接写属性会被要求显式 self, 与 --self remove 冲突let currentStatus = helperStatusif currentStatus != previousStatus {- AppLog.keepAlive.notice(- "Helper 注册状态变化: from=\(String(describing: previousStatus), privacy: .public); to=\(String(describing: currentStatus), privacy: .public)"+ let details = LogFields.joined(+ "from=\(String(describing: previousStatus))",+ "to=\(String(describing: currentStatus))")+ AppLog.keepAlive.notice("Helper 注册状态变化: \(details, privacy: .public)")}if helperStatus == .enabled {// 注册已正常, 只撤回注册类抱怨@@ -660,10 +735,17 @@ final class KeepAliveController: ObservableObject {reconcileDisplayAwake()logSleepConditionsIfChanged(blockReason: blockReason, trigger: trigger)+ // Helper 刷新只允许 unregister/register, 普通租约请求必须等新 Helper 就绪后再恢复+ guard !isRefreshingHelper else {+ cancelRetryTask()+ releaseSleepPrevention()+ return+ }+guard wantsSleepDisabled else {cancelRetryTask()- if connection != nil, appliedSleepDisabled != false || isPreventingSleep {- applySleepDisabled(false)+ if mayHaveHelperLease || isPreventingSleep {+ applySleepPreventionRequested(false)} else {releaseSleepPrevention()}@@ -671,9 +753,9 @@ final class KeepAliveController: ObservableObject {}if force {- appliedSleepDisabled = nil+ appliedSleepPreventionRequested = nil}- applySleepDisabled(true)+ applySleepPreventionRequested(true)}/// 只有实际防睡眠正在生效时达到上限才排队@@ -684,7 +766,9 @@ final class KeepAliveController: ObservableObject {return}- guard pendingKeepAliveLimit == nil, isActivelyPreventingSleep else {+ guard pendingKeepAliveLimit == nil,+ isActivelyPreventingSleep,+ sleepPreventionSource == .codexBar else {return}@@ -719,7 +803,7 @@ final class KeepAliveController: ObservableObject {/// 缺依赖时收起入口, 只是没在防睡眠 (没任务, 低电量, 已达上限) 时仍然要能改设置private static func allowsOptions(_ blockReason: SleepBlockReason?) -> Bool {switch blockReason {- case .notStarted, .userOff, .hookDisabled, .helperUnavailable:+ case .notStarted, .userOff, .hookDisabled, .helperUnavailable, .terminating:falsecase nil, .noTasks, .helperRefreshing, .lowBattery, .limitReached:true@@ -751,9 +835,18 @@ final class KeepAliveController: ObservableObject {let triggerName = trigger.rawValuelet helperName = String(describing: conditions.helper)- AppLog.keepAlive.notice(- "KeepAlive 条件变化: trigger=\(triggerName, privacy: .public); want=\(blockReason == nil ? 1 : 0); enabled=\(conditions.enabled ? 1 : 0); hook=\(conditions.hook ? 1 : 0); tasks=\(conditions.tasks ? 1 : 0); helper=\(helperName, privacy: .public); refreshing=\(conditions.refreshing ? 1 : 0); battery=\(conditions.battery ? 1 : 0); limited=\(conditions.limited ? 1 : 0)"+ let details = LogFields.joined(+ "trigger=\(triggerName)",+ "want=\(blockReason == nil ? 1 : 0)",+ "enabled=\(conditions.enabled ? 1 : 0)",+ "hook=\(conditions.hook ? 1 : 0)",+ "tasks=\(conditions.tasks ? 1 : 0)",+ "helper=\(helperName)",+ "refreshing=\(conditions.refreshing ? 1 : 0)",+ "battery=\(conditions.battery ? 1 : 0)",+ "limited=\(conditions.limited ? 1 : 0)")+ AppLog.keepAlive.notice("KeepAlive 条件变化: \(details, privacy: .public)")guard let previous, previous.blockReason == nil, let blockReason else {return@@ -764,31 +857,48 @@ final class KeepAliveController: ObservableObject {// MARK: - 睡眠切换与恢复- private func applySleepDisabled(_ disabled: Bool) {- guard appliedSleepDisabled != disabled else {+ private func applySleepPreventionRequested(+ _ requested: Bool,+ force: Bool = false,+ isObservation: Bool = false,+ completion: ((Bool) -> Void)? = nil+ ) {+ guard force || appliedSleepPreventionRequested != requested else {+ completion?(true)return}- if disabled {+ if requested, !isPreventingSleep {let result = systemSleepService.beginPreventingIdleSleep()guard result == kIOReturnSuccess else {AppLog.keepAlive.error("空闲断言建立失败: code=\(result)")operationErrorMessage = KeepAliveLocalizedMessage.preventIdleSleepFailedscheduleRetryIfNeeded(for: true)+ completion?(false)return}}+ helperRuntimeStatusMonitor.cancelRequest()+ completePendingRequest(success: false)let connection = connection ?? makeConnection()- appliedSleepDisabled = disabled+ appliedSleepPreventionRequested = requested+ if requested {+ // 发出后就要按可能被 helper 接收处理, 不能等回复才记这笔租约+ mayHaveHelperLease = true+ }requestInFlight = truerequestGeneration &+= 1let generation = requestGeneration- // 与下面的回复日志配成一对, 缺回复即说明请求丢在 XPC 途中或 helper 无响应- AppLog.keepAlive.notice(- "Helper XPC 请求已发送: op=\(disabled ? "disable" : "restore", privacy: .public); generation=\(generation)"- )- scheduleRequestTimeout(for: disabled, generation: generation)+ pendingRequestCompletion = completion+ if !isObservation {+ let details = LogFields.joined(+ "op=\(requested ? "acquire" : "release")",+ "generation=\(generation)"+ )+ AppLog.keepAlive.notice("Helper XPC 请求已发送: \(details, privacy: .public)")+ }+ scheduleRequestTimeout(for: requested, generation: generation)let errorHandler: (Error) -> Void = { [weak self] error inTask { @MainActor in@@ -804,63 +914,168 @@ final class KeepAliveController: ObservableObject {return}- helper.setSleepDisabled(disabled) { [weak self] exitCode, sleepDisabledAfterOperation in- Task { @MainActor in- guard let self, generation == self.requestGeneration else {- return- }- self.requestInFlight = false- self.cancelRequestTimeout()- let replyResult = exitCode == 0 ? "ok" : "failed"- AppLog.keepAlive.notice(- "Helper XPC 回复已收到: generation=\(generation); result=\(replyResult, privacy: .public); exit=\(exitCode)"+ let reply: @Sendable (Int32, Int, Bool) -> Void = { [weak self] exitCode, sourceRawValue, sleepDisabledAfterOperation in+ Task { @MainActor [weak self] in+ await self?.handleSleepPreventionReply(+ exitCode: exitCode,+ sourceRawValue: sourceRawValue,+ sleepDisabledAfterOperation: sleepDisabledAfterOperation,+ requested: requested,+ generation: generation,+ isObservation: isObservation)- guard exitCode == 0 else {- // invalidateConnection 会连同 assertion 一起收- self.invalidateConnection()- AppLog.keepAlive.error("系统睡眠切换失败: generation=\(generation); exit=\(exitCode)")- self.operationErrorMessage = KeepAliveLocalizedMessage.toggleSleepFailed- self.scheduleRetryIfNeeded(for: disabled)- return- }-- self.cancelRetryTask()- self.isPreventingSleep = disabled- self.operationErrorMessage = nil- // 屏幕跟着实际效果走, 这里是它唯一的建立时机- self.reconcileDisplayAwake()- if disabled {- // lidCausesSleep=0 说明这一轮 pmset 是空转的, 真正在挡的只有空闲断言- // 排查「开了却还是睡了」时先看这个字段- let lidStatus = SystemSleepService.currentStatus()- let lidCausesSleep = lidStatus- .map { $0.lidClosureCausesSleep ? "1" : "0" } ?? "unknown"- AppLog.keepAlive.notice(- "系统睡眠已关闭: generation=\(generation); lidCausesSleep=\(lidCausesSleep, privacy: .public)"- )- self.canTrustRestoreResult = true- self.durationLimiter.begin()- } else {- // 先收表再走恢复: finishSleepRestore 可能直接把机器送去睡- self.durationLimiter.pause()- // 通知同样要赶在补发睡眠之前发出去, 理由与收表相同- // 走到这里 pmset 已经恢复成功, 那句"已恢复系统睡眠"才站得住- await self.flushPendingSleepRestoreNotification()- // 上面这一步会挂起, 期间可能已经有新的禁用请求接管- // 那时再走恢复会释放掉刚建立的空闲断言, 所以重新认一次代- guard generation == self.requestGeneration else {- return- }- self.finishSleepRestore(- sleepDisabledAfterOperation: sleepDisabledAfterOperation- )- }}}+ helper.setSleepPreventionRequested(+ requested,+ clientSessionID: helperClientSessionID,+ generation: generation,+ reply: reply+ )}- private func finishSleepRestore(sleepDisabledAfterOperation: Bool) {- // assertion 无论回复可不可信都要释放, 与下面的判断无关+ private func handleSleepPreventionReply(+ exitCode: Int32,+ sourceRawValue: Int,+ sleepDisabledAfterOperation: Bool,+ requested: Bool,+ generation: UInt64,+ isObservation: Bool+ ) async {+ guard generation == requestGeneration else {+ return+ }+ requestInFlight = false+ cancelRequestTimeout()+ let replyResult = exitCode == 0 ? "ok" : "failed"+ if !isObservation || exitCode != 0 {+ let details = LogFields.joined(+ "generation=\(generation)",+ "result=\(replyResult)",+ "exit=\(exitCode)"+ )+ AppLog.keepAlive.notice("Helper XPC 回复已收到: \(details, privacy: .public)")+ }+ guard exitCode == 0 else {+ handleSleepPreventionFailure(+ requested: requested,+ generation: generation,+ detail: "exit=\(exitCode)"+ )+ return+ }+ guard let source = CodexBarSleepPreventionSource(rawValue: sourceRawValue),+ !requested || (source != .none && sleepDisabledAfterOperation) else {+ let details = LogFields.joined(+ "source=\(sourceRawValue)",+ "sleepDisabled=\(sleepDisabledAfterOperation ? 1 : 0)"+ )+ handleSleepPreventionFailure(+ requested: requested,+ generation: generation,+ detail: details+ )+ return+ }++ cancelRetryTask()+ isPreventingSleep = requested+ operationErrorMessage = nil+ let previousSource = sleepPreventionSource+ updateSleepPreventionSource(source, requested: requested)+ reconcileDisplayAwake()++ if requested {+ finishSleepPreventionAcquire(+ source: source,+ previousSource: previousSource,+ generation: generation,+ isObservation: isObservation+ )+ } else {+ await finishSleepPreventionRelease(+ source: source,+ sleepDisabledAfterOperation: sleepDisabledAfterOperation,+ generation: generation+ )+ }+ }++ private func handleSleepPreventionFailure(+ requested: Bool,+ generation: UInt64,+ detail: String+ ) {+ invalidateConnection()+ let details = LogFields.joined(+ "generation=\(generation)",+ "detail=\(detail)"+ )+ AppLog.keepAlive.error("系统睡眠切换失败: \(details, privacy: .public)")+ operationErrorMessage = KeepAliveLocalizedMessage.toggleSleepFailed+ scheduleRetryIfNeeded(for: requested)+ }++ private func updateSleepPreventionSource(+ _ source: CodexBarSleepPreventionSource,+ requested: Bool+ ) {+ if requested {+ assign(source, to: \.sleepPreventionSource)+ reconcileExternalObservation()+ } else {+ mayHaveHelperLease = false+ cancelExternalObservation()+ assign(.none, to: \.sleepPreventionSource)+ }+ }++ private func finishSleepPreventionAcquire(+ source: CodexBarSleepPreventionSource,+ previousSource: CodexBarSleepPreventionSource,+ generation: UInt64,+ isObservation: Bool+ ) {+ let lidStatus = SystemSleepService.currentStatus()+ let lidCausesSleep = lidStatus.map { $0.lidClosureCausesSleep ? "1" : "0" } ?? "unknown"+ if !isObservation || source != previousSource {+ let details = LogFields.joined(+ "generation=\(generation)",+ "source=\(String(describing: source))",+ "lidCausesSleep=\(lidCausesSleep)"+ )+ AppLog.keepAlive.notice("系统睡眠已防止: \(details, privacy: .public)")+ }+ durationLimiter.begin()+ completePendingRequest(success: true)+ }++ private func finishSleepPreventionRelease(+ source: CodexBarSleepPreventionSource,+ sleepDisabledAfterOperation: Bool,+ generation: UInt64+ ) async {+ durationLimiter.pause()+ if source == .codexBar, !sleepDisabledAfterOperation {+ await flushPendingSleepRestoreNotification()+ } else {+ pendingLowBatteryPercent = nil+ pendingKeepAliveLimit = nil+ }+ guard generation == requestGeneration else {+ return+ }+ finishSleepRestore(+ source: source,+ sleepDisabledAfterOperation: sleepDisabledAfterOperation+ )+ completePendingRequest(success: true)+ }++ private func finishSleepRestore(+ source: CodexBarSleepPreventionSource,+ sleepDisabledAfterOperation: Bool+ ) {let idleSleepResult = systemSleepService.endPreventingIdleSleep()if idleSleepResult != kIOReturnSuccess {AppLog.keepAlive.error("空闲断言释放失败: code=\(idleSleepResult)")@@ -868,11 +1083,12 @@ final class KeepAliveController: ObservableObject {}let sleepDisabled = sleepDisabledAfterOperation ? 1 : 0- // 连接断过时 helper 可能已自行恢复并清掉哨兵, 这份回复不带实测状态- // 不能据此补发合盖睡眠: 本轮可能压根不是我们禁用的睡眠- guard canTrustRestoreResult else {- // 这条判断是防止误发强制睡眠的唯一屏障, 生效时必须留痕, 否则误判无从追查- AppLog.keepAlive.notice("系统睡眠恢复结果不可信: reason=connectionLost")+ guard source == .codexBar else {+ let details = LogFields.joined(+ "source=\(String(describing: source))",+ "sleepDisabled=\(sleepDisabled)"+ )+ AppLog.keepAlive.notice("系统睡眠未修改: \(details, privacy: .public)")return}@@ -883,7 +1099,7 @@ final class KeepAliveController: ObservableObject {&& lidStatus?.shouldSleepForLidClosure == true// 合盖是边沿事件, 错过那一刻系统不会再评估- // 我们挡过一次就得在恢复后补一脚, 否则盖着的机器会一直醒着+ // 只有 CodexBar 自己挡过并恢复为 0 才补发, 外部来源不属于我们的合盖边沿guard shouldRequestSystemSleep else {let reason: String = if sleepDisabledAfterOperation {"stillDisabled"@@ -906,6 +1122,75 @@ final class KeepAliveController: ObservableObject {}}+ private func completePendingRequest(success: Bool) {+ let completion = pendingRequestCompletion+ pendingRequestCompletion = nil+ completion?(success)+ }++ private func fetchHelperRuntimeStatus() async -> HelperRuntimeStatus? {+ guard !requestInFlight, !helperRuntimeStatusMonitor.isRequestInFlight else {+ return nil+ }+ let connection = connection ?? makeConnection()+ return await helperRuntimeStatusMonitor.fetch(+ connection: connection,+ timeout: KeepAliveHelperConfiguration.requestTimeout,+ onConnectionFailure: { [weak self] error in+ self?.handleConnectionFailure(error)+ },+ onTimeout: { [weak self] in+ self?.handleHelperStatusTimeout()+ }+ )+ }++ private func resetSleepAfterHelperUpdate(_ updateIdentifier: String) async -> Bool {+ guard !requestInFlight, !helperRuntimeStatusMonitor.isRequestInFlight else {+ return false+ }+ let connection = connection ?? makeConnection()+ return await helperRuntimeStatusMonitor.resetSleepAfterUpdate(+ connection: connection,+ updateIdentifier: updateIdentifier,+ timeout: KeepAliveHelperConfiguration.requestTimeout,+ onConnectionFailure: { [weak self] error in+ self?.handleConnectionFailure(error)+ },+ onTimeout: { [weak self] in+ self?.handleHelperStatusTimeout()+ }+ )+ }++ private func handleHelperStatusTimeout() {+ let shouldRetry = isPreventingSleep+ let desiredSleepPrevention = shouldDisableSleep+ invalidateConnection()+ operationErrorMessage = KeepAliveLocalizedMessage.noResponse+ if shouldRetry {+ scheduleRetryIfNeeded(for: desiredSleepPrevention)+ }+ }++ private func releaseHelperLeaseIfNeeded(trigger: LogTrigger) async -> Bool {+ let blockReason = sleepBlockReason+ publishDerivedState(blockReason: blockReason)+ reconcileDisplayAwake()+ logSleepConditionsIfChanged(blockReason: blockReason, trigger: trigger)++ guard mayHaveHelperLease || isPreventingSleep else {+ releaseSleepPrevention()+ return true+ }++ return await withCheckedContinuation { continuation in+ applySleepPreventionRequested(false, force: true) { success in+ continuation.resume(returning: success)+ }+ }+ }+// MARK: - XPC 连接与重试private func makeConnection() -> NSXPCConnection {@@ -922,11 +1207,11 @@ final class KeepAliveController: ObservableObject {return}let shouldRetry = self.requestInFlight || self.isPreventingSleep- let desiredSleepDisabled = self.shouldDisableSleep+ let desiredSleepPrevention = self.shouldDisableSleep// 复用统一清理: 连接失效同样要释放 assertion, 否则空闲睡眠会被永久阻止self.invalidateConnection()if shouldRetry {- self.scheduleRetryIfNeeded(for: desiredSleepDisabled)+ self.scheduleRetryIfNeeded(for: desiredSleepPrevention)}}}@@ -943,37 +1228,40 @@ final class KeepAliveController: ObservableObject {private func handleConnectionFailure(_ error: Error) {let shouldRetry = requestInFlight || isPreventingSleep- let desiredSleepDisabled = shouldDisableSleep+ let desiredSleepPrevention = shouldDisableSleepinvalidateConnection()AppLog.keepAlive.error("Helper XPC 连接失败: detail=\(error.localizedDescription, privacy: .public)")operationErrorMessage = KeepAliveLocalizedMessage.connectionFailedif shouldRetry {- scheduleRetryIfNeeded(for: desiredSleepDisabled)+ scheduleRetryIfNeeded(for: desiredSleepPrevention)}}- /// helper 起不来时 setSleepDisabled 既不回复也不触发 errorHandler, 请求就那么挂着+ /// helper 起不来时 XPC 方法既不回复也不触发 errorHandler, 请求就那么挂着/// 没有这道超时, 界面会显示防睡眠开着而实际没生效, 日志里只剩一条没有配对回复的请求已发送- private func scheduleRequestTimeout(for disabled: Bool, generation: UInt64) {+ private func scheduleRequestTimeout(for requested: Bool, generation: UInt64) {requestTimeoutTask?.cancel()requestTimeoutTask = Task { @MainActor [weak self] in- try? await Task.sleep(for: Self.helperRequestTimeout)+ try? await Task.sleep(for: KeepAliveHelperConfiguration.requestTimeout)// 认状态而不是认取消位: 每条取消路径都同时推进了 generation 或清了 in-flight,// 认状态就不必依赖将来每个新路径都记得 cancelguard let self, generation == requestGeneration, requestInFlight else {return}- let timeout = LogDuration.seconds(Self.helperRequestTimeout)- AppLog.keepAlive.error(- "Helper XPC 请求超时: op=\(disabled ? "disable" : "restore", privacy: .public); generation=\(generation); timeout=\(timeout, privacy: .public)"+ let timeout = LogDuration.seconds(KeepAliveHelperConfiguration.requestTimeout)+ let details = LogFields.joined(+ "op=\(requested ? "acquire" : "release")",+ "generation=\(generation)",+ "timeout=\(timeout)")+ AppLog.keepAlive.error("Helper XPC 请求超时: \(details, privacy: .public)")// 连接已经不可信, 收掉它再走既有的重试阶梯, 与切换失败同一条路径invalidateConnection()operationErrorMessage = KeepAliveLocalizedMessage.noResponse- scheduleRetryIfNeeded(for: disabled)+ scheduleRetryIfNeeded(for: requested)}}@@ -984,38 +1272,94 @@ final class KeepAliveController: ObservableObject {private func invalidateConnection() {cancelRequestTimeout()+ cancelExternalObservation()+ helperRuntimeStatusMonitor.cancelRequest()requestGeneration &+= 1let connection = connectionself.connection = nilconnection?.invalidationHandler = nilconnection?.interruptionHandler = nilconnection?.invalidate()+ completePendingRequest(success: false)// 无连接时也会走到这里, 只记真的断掉了一条, 避免空转刷屏if connection != nil {- // trusted 记的是断开这一刻的可信度: 它一断, 后面那轮恢复回复就不再可信- // 也就不会补发睡眠, 这是追查「任务结束了机器却没睡」的唯一线索- let trusted = canTrustRestoreResult ? 1 : 0- AppLog.keepAlive.notice("Helper XPC 已断开: trusted=\(trusted)")- }- // 所有能让我们在哨兵已删的情况下再发一次恢复请求的路径都汇到这里, 标志清在这里才严密- canTrustRestoreResult = false- appliedSleepDisabled = nil+ let mayHaveLease = mayHaveHelperLease ? 1 : 0+ AppLog.keepAlive.notice("Helper XPC 已断开: mayHaveLease=\(mayHaveLease)")+ }+ // 断连不能清 mayHaveHelperLease, 请求可能已在 helper 执行只是回复丢了+ appliedSleepPreventionRequested = nilrequestInFlight = falsereleaseSleepPrevention()}/// assertion 与 isPreventingSleep 同进同退的唯一出口/// 两者必须一起收: 只清标志会让菜单栏图标显示成未防睡眠, 而这条 assertion 仍在防止空闲睡眠,- /// 且没有任何后续路径会释放它; 仍需要防睡眠时由重试经 applySleepDisabled(true) 重建+ /// 且没有任何后续路径会释放它; 仍需要防睡眠时由重试重建private func releaseSleepPrevention() {_ = systemSleepService.endPreventingIdleSleep()+ cancelExternalObservation()assign(false, to: \.isPreventingSleep)+ assign(.none, to: \.sleepPreventionSource)// 空闲断言与屏幕成对: 这里之后睡眠不再被挡, 屏幕也没有留住的理由reconcileDisplayAwake()// 收表跟着实际效果走: 这里之后睡眠不再被挡, 那段时间不该占用户的上限durationLimiter.pause()}+ /// pmset 轮询统一由 helper 执行, App 这里只读取缓存状态来刷新来源显示+ private func reconcileExternalObservation() {+ guard sleepPreventionSource == .external,+ isPreventingSleep,+ shouldDisableSleep else {+ cancelExternalObservation()+ return+ }+ helperRuntimeStatusMonitor.startObservation(+ interval: KeepAliveHelperConfiguration.externalObservationInterval+ ) { [weak self] in+ guard let self,+ sleepPreventionSource == .external,+ isPreventingSleep,+ shouldDisableSleep else {+ self?.cancelExternalObservation()+ return+ }+ guard !requestInFlight,+ let status = await fetchHelperRuntimeStatus() else {+ return+ }+ handleExternalObservation(status)+ }+ }++ private func handleExternalObservation(_ status: HelperRuntimeStatus) {+ guard sleepPreventionSource == .external,+ isPreventingSleep,+ shouldDisableSleep else {+ return+ }++ switch status.externalObservationAction {+ case .sourceBecameCodexBar:+ let previousSource = sleepPreventionSource+ updateSleepPreventionSource(.codexBar, requested: true)+ finishSleepPreventionAcquire(+ source: .codexBar,+ previousSource: previousSource,+ generation: requestGeneration,+ isObservation: true+ )+ case .reacquireLease:+ applySleepPreventionRequested(true, force: true, isObservation: true)+ case .none:+ break+ }+ }++ private func cancelExternalObservation() {+ helperRuntimeStatusMonitor.cancelObservation()+ }+// MARK: - 屏幕常亮/// 用户开关与防睡眠实际效果的汇合点, 两边任意一个变了都要过这里@@ -1061,31 +1405,34 @@ final class KeepAliveController: ObservableObject {assign(false, to: \.isRefreshingHelper)}- private func scheduleRetryIfNeeded(for disabled: Bool) {+ private func scheduleRetryIfNeeded(for requested: Bool) {guard isStarted,helperStatus == .enabled,- disabled == shouldDisableSleep,+ requested == shouldDisableSleep,retryTask == nil else {return}// 每次重试都会重建特权连接并以 root 拉起 pmset// 固定 2 秒无上限重试会让持续失败的 helper 变成无限循环- guard retryAttempt < Self.sleepToggleRetryDelays.count else {+ guard retryAttempt < KeepAliveHelperConfiguration.sleepToggleRetryDelays.count else {AppLog.keepAlive.error(- "KeepAlive 切换重试已放弃: attempts=\(Self.sleepToggleRetryDelays.count)"+ "KeepAlive 切换重试已放弃: attempts=\(KeepAliveHelperConfiguration.sleepToggleRetryDelays.count)")operationErrorMessage = KeepAliveLocalizedMessage.retryLimitReachedreturn}- let delay = Self.sleepToggleRetryDelays[retryAttempt]+ let delay = KeepAliveHelperConfiguration.sleepToggleRetryDelays[retryAttempt]retryAttempt += 1let attempt = retryAttemptlet wait = LogDuration.seconds(delay)- AppLog.keepAlive.notice(- "睡眠切换重试: attempt=\(attempt); delay=\(wait, privacy: .public); disabled=\(disabled ? 1 : 0)"+ let details = LogFields.joined(+ "attempt=\(attempt)",+ "delay=\(wait)",+ "requested=\(requested ? 1 : 0)")+ AppLog.keepAlive.notice("睡眠切换重试: \(details, privacy: .public)")retryTask = Task { @MainActor [weak self] intry? await Task.sleep(for: delay)@@ -1093,12 +1440,12 @@ final class KeepAliveController: ObservableObject {return}retryTask = nil- guard disabled == shouldDisableSleep else {+ guard requested == shouldDisableSleep else {reconcileSleepState(trigger: .retry)return}- appliedSleepDisabled = nil- applySleepDisabled(disabled)+ appliedSleepPreventionRequested = nil+ applySleepPreventionRequested(requested)}}@@ -1121,6 +1468,9 @@ final class KeepAliveController: ObservableObject {if !isStarted {return .notStarted}+ if isPreparingForTermination {+ return .terminating+ }if !isEnabled {return .userOff}@@ -1153,153 +1503,63 @@ final class KeepAliveController: ObservableObject {private static let keepsDisplayAwakeKey = "KeepAlive.keepsDisplayAwake"/// 解除门槛比触发门槛高这么多个百分点, 避免电量在阈值附近抖动导致反复切换private static let lowBatteryHysteresis = 5- private static let helperRegistrationFingerprintKey = "KeepAlive.helperRegistrationFingerprint"- private static let helperRegistrationRetryDelays: [Duration] = [- .milliseconds(500),- .seconds(1),- .seconds(2)- ]- private static let operationNotPermittedErrorCode = 1-- /// 与 helper 的 watchdog 宽限是一对, 取值和理由都在 CodexBarHelperIPC 那边- private static let helperRequestTimeout = Duration.seconds(- CodexBarHelperIPC.requestTimeoutSeconds- )-- /// 切换睡眠状态失败后的重试节奏, 逐次翻倍- /// 列表耗尽即放弃 (延时累计约 8.5 分钟, 每轮再等一次超时约 10 分钟): 瞬时抖动能自愈, 权限类故障不会无限重试- private static let sleepToggleRetryDelays: [Duration] = [- .seconds(2),- .seconds(4),- .seconds(8),- .seconds(16),- .seconds(32),- .seconds(64),- .seconds(128),- .seconds(256)- ]-- // MARK: - helper 资源与指纹-- private static var helperService: SMAppService {- SMAppService.daemon(plistName: CodexBarHelperIPC.daemonPlistName)- }-- private static var helperAssetsArePresent: Bool {- FileManager.default.fileExists(atPath: daemonPlistURL.path)- && FileManager.default.isExecutableFile(atPath: helperExecutableURL.path)- }-- private var helperRegistrationNeedsRefresh: Bool {- guard let fingerprint = Self.helperRegistrationFingerprint else {- return false- }- return defaults.string(forKey: Self.helperRegistrationFingerprintKey) != fingerprint- }+}- private func recordHelperRegistrationIfCurrent() {- guard helperStatus.isRegisteredOrAwaitingApproval,- let fingerprint = Self.helperRegistrationFingerprint else {+private extension KeepAliveController {+ func completePendingHelperUpdate(_ updateIdentifier: String) {+ guard helperRegistrationTask == nil else {return}- defaults.set(fingerprint, forKey: Self.helperRegistrationFingerprintKey)- }-- private static var helperRegistrationFingerprint: String? {- guard let helperData = try? Data(contentsOf: helperExecutableURL, options: .mappedIfSafe),- let daemonPlistData = try? Data(contentsOf: daemonPlistURL, options: .mappedIfSafe) else {- return nil- }- var hasher = SHA256()- for (name, data) in [- (helperExecutableURL.lastPathComponent, helperData),- (daemonPlistURL.lastPathComponent, daemonPlistData)- ] {- hasher.update(data: Data("\(name)\n\(data.count)\n".utf8))- hasher.update(data: data)- }- return hasher.finalize().map { String(format: "%02x", $0) }.joined()- }+ assign(true, to: \.isRefreshingHelper)+ cancelRetryTask()+ cancelExternalObservation()+ registrationErrorMessage = nil+ operationErrorMessage = nil- private static var appContentsURL: URL {- Bundle.main.bundleURL.appending(path: "Contents", directoryHint: .isDirectory)- }+ helperRegistrationTask = Task { @MainActor [weak self] in+ guard let self else {+ return+ }- private static var helperExecutableURL: URL {- appContentsURL- .appending(path: "Resources", directoryHint: .isDirectory)- .appending(path: "CodexBarHelper")- }+ let succeeded = await completeHelperUpdate(updateIdentifier)+ guard isStarted, !Task.isCancelled else {+ return+ }+ if !succeeded {+ registrationErrorMessage = KeepAliveLocalizedMessage.updateFailed+ }- private static var daemonPlistURL: URL {- appContentsURL- .appending(path: "Library/LaunchDaemons", directoryHint: .isDirectory)- .appending(path: CodexBarHelperIPC.daemonPlistName)+ assign(!succeeded && helperStatus == .enabled, to: \.isRefreshingHelper)+ helperRegistrationTask = nil+ reconcileSleepState(trigger: .helperRegistered, force: true)+ }}-}--private nonisolated enum KeepAliveLocalizedMessage {- static let helperAssetsMissing = String(- localized: "keep-alive.error.helper-assets-missing",- defaultValue: "服务异常, 请重新安装 CodexBar"- )- static let registrationFailed = String(- localized: "keep-alive.error.registration-failed",- defaultValue: "注册服务失败"- )- static let updateFailed = String(- localized: "keep-alive.error.update-failed",- defaultValue: "更新服务失败"- )- static let preventIdleSleepFailed = String(- localized: "keep-alive.error.prevent-idle-sleep-failed",- defaultValue: "防止空闲睡眠失败"- )- static let toggleSleepFailed = String(- localized: "keep-alive.error.toggle-sleep-failed",- defaultValue: "切换睡眠状态失败"- )- static let restoreIdleSleepFailed = String(- localized: "keep-alive.error.restore-idle-sleep-failed",- defaultValue: "恢复空闲睡眠策略失败"- )- static let requestSystemSleepFailed = String(- localized: "keep-alive.error.request-system-sleep-failed",- defaultValue: "请求系统睡眠失败"- )- static let connectionFailed = String(- localized: "keep-alive.error.connection-failed",- defaultValue: "连接服务失败"- )- static let noResponse = String(- localized: "keep-alive.error.no-response",- defaultValue: "服务无响应"- )- static let retryLimitReached = String(- localized: "keep-alive.error.retry-limit-reached",- defaultValue: "防睡眠多次失败, 已停止重试"- )- static let invalidHelperInterface = String(- localized: "keep-alive.error.invalid-helper-interface",- defaultValue: "服务接口无效"- )- static let connectionInterrupted = String(- localized: "keep-alive.error.connection-interrupted",- defaultValue: "服务连接中断"- )-}-private nonisolated enum KeepAliveError: LocalizedError {- case invalidHelperProxy- case connectionInterrupted+ func completeHelperUpdate(_ updateIdentifier: String) async -> Bool {+ for delay in KeepAliveHelperConfiguration.updateCompletionRetryDelays {+ if delay > .zero {+ try? await Task.sleep(for: delay)+ }+ guard !Task.isCancelled else {+ return false+ }- var errorDescription: String? {- switch self {- case .invalidHelperProxy:- KeepAliveLocalizedMessage.invalidHelperInterface- case .connectionInterrupted:- KeepAliveLocalizedMessage.connectionInterrupted+ refreshHelperStatus()+ guard helperStatus == .enabled else {+ continue+ }+ if await resetSleepAfterHelperUpdate(updateIdentifier) {+ KeepAliveHelperConfiguration.completeUpdate(+ updateIdentifier,+ defaults: defaults+ )+ mayHaveHelperLease = false+ appliedSleepPreventionRequested = nil+ operationErrorMessage = nil+ return true+ }}+ return false}}diff --git a/CodexBar/Services/KeepAlive/KeepAliveHelperConfiguration.swift b/CodexBar/Services/KeepAlive/KeepAliveHelperConfiguration.swiftnew file mode 100644index 0000000..44dd1d4--- /dev/null+++ b/CodexBar/Services/KeepAlive/KeepAliveHelperConfiguration.swift@@ -0,0 +1,140 @@+import CryptoKit+import Foundation+import ServiceManagement++@MainActor+enum KeepAliveHelperConfiguration {+ static let registrationRetryDelays: [Duration] = [+ .milliseconds(500),+ .seconds(1),+ .seconds(2)+ ]+ static let updateCompletionRetryDelays: [Duration] = [+ .zero,+ .milliseconds(250),+ .milliseconds(500),+ .seconds(1),+ .seconds(2)+ ]+ static let requestTimeout = Duration.seconds(+ CodexBarHelperIPC.requestTimeoutSeconds+ )+ static let externalObservationInterval = Duration.seconds(+ CodexBarHelperIPC.externalCheckIntervalSeconds+ )+ static let sleepToggleRetryDelays: [Duration] = [+ .seconds(2),+ .seconds(4),+ .seconds(8),+ .seconds(16),+ .seconds(32),+ .seconds(64),+ .seconds(128),+ .seconds(256)+ ]++ static var service: SMAppService {+ SMAppService.daemon(plistName: CodexBarHelperIPC.daemonPlistName)+ }++ static var assetsArePresent: Bool {+ FileManager.default.fileExists(atPath: daemonPlistURL.path)+ && FileManager.default.isExecutableFile(atPath: helperExecutableURL.path)+ }++ static func registrationNeedsRefresh(defaults: UserDefaults) -> Bool {+ guard let fingerprint else {+ return false+ }+ return defaults.string(forKey: registrationFingerprintKey) != fingerprint+ }++ static func beginUpdate(+ defaults: UserDefaults,+ requiresSleepReset: Bool+ ) -> String? {+ guard let fingerprint else {+ return nil+ }+ // 待完成重置是跨 Helper 版本的欠账, 后续更新只能转交给新指纹, 不能清除+ let hasPendingSleepReset = defaults.string(forKey: pendingUpdateIdentifierKey) != nil+ if requiresSleepReset || hasPendingSleepReset {+ defaults.set(fingerprint, forKey: pendingUpdateIdentifierKey)+ } else {+ defaults.removeObject(forKey: pendingUpdateIdentifierKey)+ }+ return fingerprint+ }++ static func pendingUpdateIdentifier(defaults: UserDefaults) -> String? {+ guard let fingerprint,+ defaults.string(forKey: registrationFingerprintKey) == fingerprint,+ defaults.string(forKey: pendingUpdateIdentifierKey) == fingerprint else {+ return nil+ }+ return fingerprint+ }++ static func completeUpdate(+ _ updateIdentifier: String,+ defaults: UserDefaults+ ) {+ guard defaults.string(forKey: pendingUpdateIdentifierKey) == updateIdentifier else {+ return+ }+ defaults.removeObject(forKey: pendingUpdateIdentifierKey)+ }++ static func recordRegistration(+ defaults: UserDefaults,+ status: KeepAliveController.HelperStatus+ ) {+ guard status.isRegisteredOrAwaitingApproval, let fingerprint else {+ return+ }+ defaults.set(fingerprint, forKey: registrationFingerprintKey)+ }++ static func isTransientRegistrationError(_ error: Error) -> Bool {+ let error = error as NSError+ return error.domain == SMAppServiceErrorDomain+ && error.code == operationNotPermittedErrorCode+ }++ private static let registrationFingerprintKey = "KeepAlive.helperRegistrationFingerprint"+ private static let pendingUpdateIdentifierKey = "KeepAlive.pendingHelperUpdateIdentifier"+ private static let operationNotPermittedErrorCode = 1++ private static var fingerprint: String? {+ guard let helperData = try? Data(contentsOf: helperExecutableURL, options: .mappedIfSafe),+ let daemonPlistData = try? Data(contentsOf: daemonPlistURL, options: .mappedIfSafe) else {+ return nil+ }++ var hasher = SHA256()+ for (name, data) in [+ (helperExecutableURL.lastPathComponent, helperData),+ (daemonPlistURL.lastPathComponent, daemonPlistData)+ ] {+ hasher.update(data: Data("\(name)\n\(data.count)\n".utf8))+ hasher.update(data: data)+ }+ return hasher.finalize().map { String(format: "%02x", $0) }.joined()+ }++ private static var appContentsURL: URL {+ Bundle.main.bundleURL.appending(path: "Contents", directoryHint: .isDirectory)+ }++ private static var helperExecutableURL: URL {+ appContentsURL+ .appending(path: "Resources", directoryHint: .isDirectory)+ .appending(path: "CodexBarHelper")+ }++ private static var daemonPlistURL: URL {+ appContentsURL+ .appending(path: "Library/LaunchDaemons", directoryHint: .isDirectory)+ .appending(path: CodexBarHelperIPC.daemonPlistName)+ }+}diff --git a/CodexBar/Services/KeepAlive/KeepAliveModels.swift b/CodexBar/Services/KeepAlive/KeepAliveModels.swiftindex 0a7eca9..264c411 100644--- a/CodexBar/Services/KeepAlive/KeepAliveModels.swift+++ b/CodexBar/Services/KeepAlive/KeepAliveModels.swift@@ -92,3 +92,68 @@ extension KeepAliveController {}}}++nonisolated enum KeepAliveLocalizedMessage {+ static let helperAssetsMissing = String(+ localized: "keep-alive.error.helper-assets-missing",+ defaultValue: "服务异常, 请重新安装 CodexBar"+ )+ static let registrationFailed = String(+ localized: "keep-alive.error.registration-failed",+ defaultValue: "注册服务失败"+ )+ static let updateFailed = String(+ localized: "keep-alive.error.update-failed",+ defaultValue: "更新服务失败"+ )+ static let preventIdleSleepFailed = String(+ localized: "keep-alive.error.prevent-idle-sleep-failed",+ defaultValue: "防止空闲睡眠失败"+ )+ static let toggleSleepFailed = String(+ localized: "keep-alive.error.toggle-sleep-failed",+ defaultValue: "切换睡眠状态失败"+ )+ static let restoreIdleSleepFailed = String(+ localized: "keep-alive.error.restore-idle-sleep-failed",+ defaultValue: "恢复空闲睡眠策略失败"+ )+ static let requestSystemSleepFailed = String(+ localized: "keep-alive.error.request-system-sleep-failed",+ defaultValue: "请求系统睡眠失败"+ )+ static let connectionFailed = String(+ localized: "keep-alive.error.connection-failed",+ defaultValue: "连接服务失败"+ )+ static let noResponse = String(+ localized: "keep-alive.error.no-response",+ defaultValue: "服务无响应"+ )+ static let retryLimitReached = String(+ localized: "keep-alive.error.retry-limit-reached",+ defaultValue: "防睡眠多次失败, 已停止重试"+ )+ static let invalidHelperInterface = String(+ localized: "keep-alive.error.invalid-helper-interface",+ defaultValue: "服务接口无效"+ )+ static let connectionInterrupted = String(+ localized: "keep-alive.error.connection-interrupted",+ defaultValue: "服务连接中断"+ )+}++nonisolated enum KeepAliveError: LocalizedError {+ case invalidHelperProxy+ case connectionInterrupted++ var errorDescription: String? {+ switch self {+ case .invalidHelperProxy:+ KeepAliveLocalizedMessage.invalidHelperInterface+ case .connectionInterrupted:+ KeepAliveLocalizedMessage.connectionInterrupted+ }+ }+}diff --git a/CodexBar/Services/KeepAlive/PowerSourceMonitor.swift b/CodexBar/Services/KeepAlive/PowerSourceMonitor.swiftindex b146b3e..b44b26b 100644--- a/CodexBar/Services/KeepAlive/PowerSourceMonitor.swift+++ b/CodexBar/Services/KeepAlive/PowerSourceMonitor.swift@@ -113,9 +113,11 @@ final class PowerSourceMonitor {}}, context)?.takeRetainedValue() else {// action= 记的是降级后还剩什么, 否则只知道注册失败, 不知道保护是不是全没了- AppLog.keepAlive.error(- "电源监听注册失败: stage=createRunLoopSource; action=poll"+ let details = LogFields.joined(+ "stage=createRunLoopSource",+ "action=poll")+ AppLog.keepAlive.error("电源监听注册失败: \(details, privacy: .public)")startPolling()return}diff --git a/CodexBar/Services/Notifications/CodexNotificationService.swift b/CodexBar/Services/Notifications/CodexNotificationService.swiftindex 2511345..d2bce34 100644--- a/CodexBar/Services/Notifications/CodexNotificationService.swift+++ b/CodexBar/Services/Notifications/CodexNotificationService.swift@@ -142,14 +142,14 @@ final class CodexNotificationService: NSObject {})case let .completed(completion):- guard settings.isLongTaskEnabled,+ guard settings.isTaskCompletionEnabled,let duration = completion.duration,- duration >= TimeInterval(settings.longTaskThresholdSeconds) else {+ duration >= TimeInterval(settings.taskCompletionMinimumDurationSeconds) else {return}send(.taskCompleted(project: completion.projectName, duration: duration),- sound: settings.longTaskSound+ sound: settings.taskCompletionSound)}}@@ -324,9 +324,12 @@ final class CodexNotificationService: NSObject {// 阈值是用户设置值不是用量数据, 记它才能解释这条通知为什么会发出来let threshold = lowQuota.thresholdPercent- AppLog.notification.notice(- "阈值已穿越: kind=lowQuota; threshold=\(threshold); direction=down"+ let details = LogFields.joined(+ "kind=lowQuota",+ "threshold=\(threshold)",+ "direction=down")+ AppLog.notification.notice("阈值已穿越: \(details, privacy: .public)")let dedupKey = "low|\(stateKey)|\(Self.epoch(resetsAt))"send(@@ -502,7 +505,11 @@ final class CodexNotificationService: NSObject {if let dedupKey {guard !sentDedupKeys.contains(dedupKey),submittingDedupKeys.insert(dedupKey).inserted else {- AppLog.notification.notice("通知已跳过: kind=\(kind, privacy: .public); reason=duplicate")+ let details = LogFields.joined(+ "kind=\(kind)",+ "reason=duplicate"+ )+ AppLog.notification.notice("通知已跳过: \(details, privacy: .public)")return nil}}@@ -544,18 +551,22 @@ final class CodexNotificationService: NSObject {for _ in 0 ... Self.notificationSubmissionRetryCount {guard isStillRelevant?() != false else {- AppLog.notification.notice(- "通知已跳过: kind=\(kind, privacy: .public); reason=obsolete"+ let details = LogFields.joined(+ "kind=\(kind)",+ "reason=obsolete")+ AppLog.notification.notice("通知已跳过: \(details, privacy: .public)")return false}do {try await UNUserNotificationCenter.current().add(request)guard isStillRelevant?() != false else {// 投递后任务状态又变了, 撤回避免用户看到过期提醒- AppLog.notification.notice(- "通知已撤回: kind=\(kind, privacy: .public); reason=obsolete"+ let details = LogFields.joined(+ "kind=\(kind)",+ "reason=obsolete")+ AppLog.notification.notice("通知已撤回: \(details, privacy: .public)")removeNotifications(withIdentifiers: [request.identifier])return false}@@ -570,9 +581,11 @@ final class CodexNotificationService: NSObject {}// 重试全部用尽才记, 循环内的单次失败会重试- AppLog.notification.error(- "通知发送失败: kind=\(kind, privacy: .public); reason=retryExhausted"+ let details = LogFields.joined(+ "kind=\(kind)",+ "reason=retryExhausted")+ AppLog.notification.error("通知发送失败: \(details, privacy: .public)")onSubmissionFailure?()return false}@@ -701,7 +714,7 @@ nonisolated struct CodexNotificationContent: Equatable {}return CodexNotificationContent(- kind: "longTask",+ kind: "taskCompleted",title: String(localized: "notification.task-completed.title",defaultValue: "Codex 任务完成"diff --git a/CodexBar/Services/Notifications/NotificationSoundOption.swift b/CodexBar/Services/Notifications/NotificationSoundOption.swiftindex 9074f2f..2ee1c33 100644--- a/CodexBar/Services/Notifications/NotificationSoundOption.swift+++ b/CodexBar/Services/Notifications/NotificationSoundOption.swift@@ -76,9 +76,13 @@ struct NotificationSoundOption: Identifiable, Hashable {/// 降级本身没有用户可见的痕迹, 通知照常弹出只是换了个声音, 这条日志是事后唯一的线索/// 记 id 是定位所需, 它是选项标识而不是文件路径, 用户自定义音也只会暴露文件名本身private static func degraded(id: String, source: String) -> UNNotificationSound {- AppLog.notification.notice(- "通知音已降级: id=\(id, privacy: .public); source=\(source, privacy: .public); reason=missing; action=default"+ let details = LogFields.joined(+ "id=\(id)",+ "source=\(source)",+ "reason=missing",+ "action=default")+ AppLog.notification.notice("通知音已降级: \(details, privacy: .public)")return .default}diff --git a/CodexBar/Services/Settings/CodexCLINotificationSettings.swift b/CodexBar/Services/Settings/CodexCLINotificationSettings.swiftindex bdf3368..133c249 100644--- a/CodexBar/Services/Settings/CodexCLINotificationSettings.swift+++ b/CodexBar/Services/Settings/CodexCLINotificationSettings.swift@@ -109,9 +109,11 @@ final class CodexCLINotificationSettings: ObservableObject {return}let logStage = operation.logStage- AppLog.settings.error(- "Codex TUI 通知失败: stage=\(logStage, privacy: .public); detail=\(error.localizedDescription, privacy: .public)"+ let details = LogFields.joined(+ "stage=\(logStage)",+ "detail=\(error.localizedDescription)")+ AppLog.settings.error("Codex TUI 通知失败: \(details, privacy: .public)")errorMessage = operation.errorPrefix}diff --git a/CodexBar/Services/Settings/CodexHookSettings.swift b/CodexBar/Services/Settings/CodexHookSettings.swiftindex 44bbedc..f50202b 100644--- a/CodexBar/Services/Settings/CodexHookSettings.swift+++ b/CodexBar/Services/Settings/CodexHookSettings.swift@@ -77,9 +77,11 @@ final class CodexHookSettings: ObservableObject {// 只有 I/O 失败和 JSON 格式错误会走到这里, 它们对「Hook 装没装」不提供信息// 文件不存在或配置里没有 CodexBar 都由 readConfigIfPresent 正常返回// 因此保留上次已知值, 不能把读取失败当成用户关闭了 Hook- AppLog.hooks.error(- "Hook 读取失败: detail=\(error.localizedDescription, privacy: .public); action=keepLastKnown"+ let details = LogFields.joined(+ "detail=\(error.localizedDescription)",+ "action=keepLastKnown")+ AppLog.hooks.error("Hook 读取失败: \(details, privacy: .public)")readErrorMessage = String(localized: "读取 Codex Hook 配置失败")}}@@ -182,9 +184,11 @@ final class CodexHookSettings: ObservableObject {return}- AppLog.hooks.notice(- "Hook 链路校验结论变化: verified=\(verified ? 1 : 0); reason=\(reason.rawValue, privacy: .public)"+ let details = LogFields.joined(+ "verified=\(verified ? 1 : 0)",+ "reason=\(reason.rawValue)")+ AppLog.hooks.notice("Hook 链路校验结论变化: \(details, privacy: .public)")isVerified = verified}@@ -370,9 +374,11 @@ private extension CodexHookSettings {}guard isSupported else {- AppLog.hooks.notice(- "Hook 版本不支持: current=\(currentVersion, privacy: .public); minimum=\(minimumVersion, privacy: .public)"+ let details = LogFields.joined(+ "current=\(currentVersion)",+ "minimum=\(minimumVersion)")+ AppLog.hooks.notice("Hook 版本不支持: \(details, privacy: .public)")throw HookConfigError.unsupportedCodexVersion(minimum: minimumVersion)}}@@ -461,9 +467,11 @@ private extension CodexHookSettings {}if let discoveryError {- AppLog.hooks.error(- "Hook 信任清理失败: stage=discovery; detail=\(discoveryError.localizedDescription, privacy: .public)"+ let details = LogFields.joined(+ "stage=discovery",+ "detail=\(discoveryError.localizedDescription)")+ AppLog.hooks.error("Hook 信任清理失败: \(details, privacy: .public)")operationErrorMessage = String(localized: "已关闭 Codex Hook, 清理信任状态失败")} else {operationErrorMessage = nil@@ -475,9 +483,11 @@ private extension CodexHookSettings {return}- AppLog.hooks.error(- "Hook 信任清理失败: stage=remove; detail=\(error.localizedDescription, privacy: .public)"+ let details = LogFields.joined(+ "stage=remove",+ "detail=\(error.localizedDescription)")+ AppLog.hooks.error("Hook 信任清理失败: \(details, privacy: .public)")operationErrorMessage = String(localized: "已关闭 Codex Hook, 清理信任状态失败")}}diff --git a/CodexBar/Services/Settings/LoginItemSettings.swift b/CodexBar/Services/Settings/LoginItemSettings.swiftindex 9df1534..cb05a2e 100644--- a/CodexBar/Services/Settings/LoginItemSettings.swift+++ b/CodexBar/Services/Settings/LoginItemSettings.swift@@ -26,9 +26,11 @@ final class LoginItemSettings: ObservableObject {refresh()} catch {- AppLog.settings.error(- "开机自动启动失败: enabled=\(enabled ? 1 : 0); detail=\(error.localizedDescription, privacy: .public)"+ let details = LogFields.joined(+ "enabled=\(enabled ? 1 : 0)",+ "detail=\(error.localizedDescription)")+ AppLog.settings.error("开机自动启动失败: \(details, privacy: .public)")refresh()errorMessage = String(localized: "设置开机启动失败")}diff --git a/CodexBar/Services/Settings/NotificationSettings.swift b/CodexBar/Services/Settings/NotificationSettings.swiftindex 335b8e6..4ffa70d 100644--- a/CodexBar/Services/Settings/NotificationSettings.swift+++ b/CodexBar/Services/Settings/NotificationSettings.swift@@ -11,17 +11,17 @@ final class NotificationSettings: ObservableObject {@Published private(set) var isEnabled: Bool@Published private(set) var isLowQuotaEnabled: Bool@Published private(set) var isQuotaResetEnabled: Bool- @Published private(set) var isLongTaskEnabled: Bool+ @Published private(set) var isTaskCompletionEnabled: Bool@Published private(set) var isTaskWaitingEnabled: Bool@Published private(set) var isTaskHapticEnabled: Bool@Published private(set) var isCreditExpiryEnabled: Bool@Published private(set) var isLowBatteryEnabled: Bool@Published private(set) var isKeepAliveLimitEnabled: Bool@Published private(set) var lowQuotaThresholdPercent: Int- @Published private(set) var longTaskThresholdSeconds: Int+ @Published private(set) var taskCompletionMinimumDurationSeconds: Int@Published private(set) var lowQuotaSound: NotificationSoundOption@Published private(set) var quotaResetSound: NotificationSoundOption- @Published private(set) var longTaskSound: NotificationSoundOption+ @Published private(set) var taskCompletionSound: NotificationSoundOption@Published private(set) var taskWaitingSound: NotificationSoundOption@Published private(set) var creditExpirySound: NotificationSoundOption@Published private(set) var lowBatterySound: NotificationSoundOption@@ -60,7 +60,7 @@ final class NotificationSettings: ObservableObject {}static let lowQuotaThresholdOptions = [5, 10, 25]- static let longTaskThresholdOptions = [30, 60, 120, 300]+ static let taskCompletionDurationOptions = [30, 60, 120, 300]private let defaults: UserDefaultsprivate var authorizationTask: Task<Void, Never>?@@ -70,7 +70,11 @@ final class NotificationSettings: ObservableObject {isEnabled = defaults.bool(forKey: Self.enabledKey)isLowQuotaEnabled = Self.bool(from: defaults, key: Self.lowQuotaEnabledKey, defaultValue: true)isQuotaResetEnabled = Self.bool(from: defaults, key: Self.quotaResetEnabledKey, defaultValue: true)- isLongTaskEnabled = Self.bool(from: defaults, key: Self.longTaskEnabledKey, defaultValue: true)+ isTaskCompletionEnabled = Self.bool(+ from: defaults,+ key: Self.taskCompletionEnabledKey,+ defaultValue: true+ )isTaskWaitingEnabled = Self.bool(from: defaults, key: Self.taskWaitingEnabledKey, defaultValue: true)isTaskHapticEnabled = Self.bool(from: defaults, key: Self.taskHapticEnabledKey, defaultValue: false)isCreditExpiryEnabled = Self.bool(from: defaults, key: Self.creditExpiryEnabledKey, defaultValue: true)@@ -81,14 +85,14 @@ final class NotificationSettings: ObservableObject {in: Self.lowQuotaThresholdOptions,defaultValue: 10)- longTaskThresholdSeconds = Self.option(- defaults.object(forKey: Self.longTaskThresholdKey) as? Int,- in: Self.longTaskThresholdOptions,+ taskCompletionMinimumDurationSeconds = Self.option(+ defaults.object(forKey: Self.taskCompletionMinimumDurationKey) as? Int,+ in: Self.taskCompletionDurationOptions,defaultValue: 60)lowQuotaSound = Self.sound(from: defaults, key: Self.lowQuotaSoundKey)quotaResetSound = Self.sound(from: defaults, key: Self.quotaResetSoundKey)- longTaskSound = Self.sound(from: defaults, key: Self.longTaskSoundKey)+ taskCompletionSound = Self.sound(from: defaults, key: Self.taskCompletionSoundKey)taskWaitingSound = Self.sound(from: defaults, key: Self.taskWaitingSoundKey)creditExpirySound = Self.sound(from: defaults, key: Self.creditExpirySoundKey)lowBatterySound = Self.sound(from: defaults, key: Self.lowBatterySoundKey)@@ -120,8 +124,8 @@ final class NotificationSettings: ObservableObject {setBool(enabled, current: &isQuotaResetEnabled, key: Self.quotaResetEnabledKey)}- func setLongTaskEnabled(_ enabled: Bool) {- setBool(enabled, current: &isLongTaskEnabled, key: Self.longTaskEnabledKey)+ func setTaskCompletionEnabled(_ enabled: Bool) {+ setBool(enabled, current: &isTaskCompletionEnabled, key: Self.taskCompletionEnabledKey)}func setTaskWaitingEnabled(_ enabled: Bool) {@@ -154,14 +158,14 @@ final class NotificationSettings: ObservableObject {defaults.set(percent, forKey: Self.lowQuotaThresholdKey)}- func setLongTaskThresholdSeconds(_ seconds: Int) {- guard Self.longTaskThresholdOptions.contains(seconds),- seconds != longTaskThresholdSeconds else {+ func setTaskCompletionMinimumDurationSeconds(_ seconds: Int) {+ guard Self.taskCompletionDurationOptions.contains(seconds),+ seconds != taskCompletionMinimumDurationSeconds else {return}- longTaskThresholdSeconds = seconds- defaults.set(seconds, forKey: Self.longTaskThresholdKey)+ taskCompletionMinimumDurationSeconds = seconds+ defaults.set(seconds, forKey: Self.taskCompletionMinimumDurationKey)}func setLowQuotaSound(_ sound: NotificationSoundOption) {@@ -172,8 +176,8 @@ final class NotificationSettings: ObservableObject {setSound(sound, current: "aResetSound, key: Self.quotaResetSoundKey)}- func setLongTaskSound(_ sound: NotificationSoundOption) {- setSound(sound, current: &longTaskSound, key: Self.longTaskSoundKey)+ func setTaskCompletionSound(_ sound: NotificationSoundOption) {+ setSound(sound, current: &taskCompletionSound, key: Self.taskCompletionSoundKey)}func setTaskWaitingSound(_ sound: NotificationSoundOption) {@@ -210,9 +214,11 @@ final class NotificationSettings: ObservableObject {let previousStatus = authorizationStatusif status != previousStatus {- AppLog.notification.notice(- "通知授权变化: from=\(String(describing: previousStatus), privacy: .public); to=\(String(describing: status), privacy: .public)"+ let details = LogFields.joined(+ "from=\(String(describing: previousStatus))",+ "to=\(String(describing: status))")+ AppLog.notification.notice("通知授权变化: \(details, privacy: .public)")}authorizationStatus = status}@@ -256,9 +262,11 @@ final class NotificationSettings: ObservableObject {}// 七个通知细项都走这里, 用持久化 key 区分是哪一项, 不必逐个 setter 铺日志- AppLog.notification.notice(- "通知选项变更: key=\(key, privacy: .public); enabled=\(value ? 1 : 0)"+ let details = LogFields.joined(+ "key=\(key)",+ "enabled=\(value ? 1 : 0)")+ AppLog.notification.notice("通知选项变更: \(details, privacy: .public)")current = valuedefaults.set(value, forKey: key)}@@ -305,17 +313,17 @@ final class NotificationSettings: ObservableObject {private static let enabledKey = "Notification.enabled"private static let lowQuotaEnabledKey = "Notification.lowQuotaEnabled"private static let quotaResetEnabledKey = "Notification.quotaResetEnabled"- private static let longTaskEnabledKey = "Notification.longTaskEnabled"+ private static let taskCompletionEnabledKey = "Notification.taskCompletionEnabled"private static let taskWaitingEnabledKey = "Notification.taskWaitingEnabled"private static let taskHapticEnabledKey = "Notification.taskHapticEnabled"private static let creditExpiryEnabledKey = "Notification.creditExpiryEnabled"private static let lowBatteryEnabledKey = "Notification.lowBatteryEnabled"private static let keepAliveLimitEnabledKey = "Notification.keepAliveLimitEnabled"private static let lowQuotaThresholdKey = "Notification.lowQuotaThresholdPercent"- private static let longTaskThresholdKey = "Notification.longTaskThresholdSeconds"+ private static let taskCompletionMinimumDurationKey = "Notification.taskCompletionMinimumDurationSeconds"private static let lowQuotaSoundKey = "Notification.lowQuotaSound"private static let quotaResetSoundKey = "Notification.quotaResetSound"- private static let longTaskSoundKey = "Notification.longTaskSound"+ private static let taskCompletionSoundKey = "Notification.taskCompletionSound"private static let taskWaitingSoundKey = "Notification.taskWaitingSound"private static let creditExpirySoundKey = "Notification.creditExpirySound"private static let lowBatterySoundKey = "Notification.lowBatterySound"diff --git a/CodexBar/Services/Support/AppLog.swift b/CodexBar/Services/Support/AppLog.swiftindex e0bdd70..9ad10c7 100644--- a/CodexBar/Services/Support/AppLog.swift+++ b/CodexBar/Services/Support/AppLog.swift@@ -26,6 +26,16 @@ nonisolated enum AppLog {private static let subsystem = Bundle.main.bundleIdentifier ?? "app.zabrian.codexbar"}+nonisolated enum LogFields {+ static func joined(_ fields: String...) -> String {+ fields.joined(separator: "; ")+ }++ static func joined(_ fields: [String]) -> String {+ fields.joined(separator: "; ")+ }+}+/// 一次操作的触发来源, 作为日志里的 trigger 字段/// 同一条链路可能被用户动作 定时轮询 系统事件分别踢起来, 事后只有这个字段能区分nonisolated enum LogTrigger: String {@@ -41,6 +51,7 @@ nonisolated enum LogTrigger: String {case hookChangedcase taskChangedcase helperRegistered+ case terminationcase limitReached/// 电量或供电方式变化case batterydiff --git a/CodexBar/Services/Support/AppProcessDiagnostics.swift b/CodexBar/Services/Support/AppProcessDiagnostics.swiftindex d0879ef..d1cb1f8 100644--- a/CodexBar/Services/Support/AppProcessDiagnostics.swift+++ b/CodexBar/Services/Support/AppProcessDiagnostics.swift@@ -19,9 +19,11 @@ nonisolated enum AppProcessDiagnostics {NSSetUncaughtExceptionHandler { exception inlet name = exception.name.rawValuelet reason = exception.reason ?? "-"- AppLog.app.error(- "未捕获异常: name=\(name, privacy: .public); reason=\(reason, privacy: .public)"+ let details = LogFields.joined(+ "name=\(name)",+ "reason=\(reason)")+ AppLog.app.error("未捕获异常: \(details, privacy: .public)")}}diff --git a/CodexBar/Services/Updates/AppUpdater.swift b/CodexBar/Services/Updates/AppUpdater.swiftindex ed6e4e5..f3fd65b 100644--- a/CodexBar/Services/Updates/AppUpdater.swift+++ b/CodexBar/Services/Updates/AppUpdater.swift@@ -157,9 +157,12 @@ extension AppUpdater: SPUUpdaterDelegate {)availableUpdateMessage = messagelet trigger = checkTrigger.rawValue- AppLog.app.notice(- "更新检查完成: trigger=\(trigger, privacy: .public); result=available; version=\(version, privacy: .public)"+ let details = LogFields.joined(+ "trigger=\(trigger)",+ "result=available",+ "version=\(version)")+ AppLog.app.notice("更新检查完成: \(details, privacy: .public)")if isManualCheckInProgress {showSettingsStatusMessage(message, autoDismissDelay: nil)@@ -174,9 +177,11 @@ extension AppUpdater: SPUUpdaterDelegate {availableUpdateMessage = nilpanelUpdateMessage = nillet trigger = checkTrigger.rawValue- AppLog.app.notice(- "更新检查完成: trigger=\(trigger, privacy: .public); result=upToDate"+ let details = LogFields.joined(+ "trigger=\(trigger)",+ "result=upToDate")+ AppLog.app.notice("更新检查完成: \(details, privacy: .public)")if isManualCheckInProgress {showSettingsStatusMessage(@@ -193,9 +198,11 @@ extension AppUpdater: SPUUpdaterDelegate {// 这一轮的结果已由 updaterDidNotFindUpdate 记成 result=upToDateif (error as NSError).code != Int(SUError.noUpdateError.rawValue) {let trigger = checkTrigger.rawValue- AppLog.app.error(- "更新检查失败: trigger=\(trigger, privacy: .public); detail=\(error.localizedDescription, privacy: .public)"+ let details = LogFields.joined(+ "trigger=\(trigger)",+ "detail=\(error.localizedDescription)")+ AppLog.app.error("更新检查失败: \(details, privacy: .public)")}guard isManualCheckInProgress else {diff --git a/CodexBar/Services/Workflow/CodexActivityMonitor.swift b/CodexBar/Services/Workflow/CodexActivityMonitor.swiftindex d945608..5322f4e 100644--- a/CodexBar/Services/Workflow/CodexActivityMonitor.swift+++ b/CodexBar/Services/Workflow/CodexActivityMonitor.swift@@ -315,15 +315,25 @@ final class CodexActivityMonitor: ObservableObject {let eventCount = bootstrapEventCountlet elapsed = bootstrapDuration.elapsedguard !degraded else {- AppLog.activity.notice(- "历史回放已降级: attempts=\(attempts); events=\(eventCount); activeTasks=\(activeCount); elapsed=\(elapsed, privacy: .public); reason=unstableBoundary; action=skipHistory"+ let details = LogFields.joined(+ "attempts=\(attempts)",+ "events=\(eventCount)",+ "activeTasks=\(activeCount)",+ "elapsed=\(elapsed)",+ "reason=unstableBoundary",+ "action=skipHistory")+ AppLog.activity.notice("历史回放已降级: \(details, privacy: .public)")return}- AppLog.activity.notice(- "历史回放完成: attempts=\(attempts); events=\(eventCount); activeTasks=\(activeCount); elapsed=\(elapsed, privacy: .public)"+ let details = LogFields.joined(+ "attempts=\(attempts)",+ "events=\(eventCount)",+ "activeTasks=\(activeCount)",+ "elapsed=\(elapsed)")+ AppLog.activity.notice("历史回放完成: \(details, privacy: .public)")case let .live(events):let pendingKeysBefore = Set(pendingTerminalTasks.keys)let activeCountBefore = snapshot.activeCount@@ -339,9 +349,12 @@ final class CodexActivityMonitor: ObservableObject {// 只看活跃数会漏掉 running 转 waitingApproval, 那一进一出恒抵消为零let activeCountAfter = snapshot.activeCountif activeCountAfter != activeCountBefore || !transitions.isEmpty {- AppLog.activity.notice(- "任务数变化: from=\(activeCountBefore); to=\(activeCountAfter); transitions=\(transitions.count)"+ let details = LogFields.joined(+ "from=\(activeCountBefore)",+ "to=\(activeCountAfter)",+ "transitions=\(transitions.count)")+ AppLog.activity.notice("任务数变化: \(details, privacy: .public)")}publishLiveTransitions(transitions)if !pendingTerminalTasks.isEmpty {diff --git a/CodexBar/Services/Workflow/WorkflowService.swift b/CodexBar/Services/Workflow/WorkflowService.swiftindex d53fe3d..ef53b4c 100644--- a/CodexBar/Services/Workflow/WorkflowService.swift+++ b/CodexBar/Services/Workflow/WorkflowService.swift@@ -121,9 +121,12 @@ actor WorkflowService {try rebuildResults.append(rebuildLocalData(for: dateKey))} catch {// 整批成功时这个原因不会往上抛, 摘要只带得走日期- AppLog.workflow.error(- "数据重建失败: stage=date; date=\(dateKey, privacy: .public); detail=\(error.localizedDescription, privacy: .public)"+ let details = LogFields.joined(+ "stage=date",+ "date=\(dateKey)",+ "detail=\(error.localizedDescription)")+ AppLog.workflow.error("数据重建失败: \(details, privacy: .public)")failedDateKeys.append(dateKey)if firstFailure == nil {firstFailure = error@@ -138,9 +141,12 @@ actor WorkflowService {do {try await syncService.markReplacementNeeded(for: normalizedDateKeys)} catch {- AppLog.workflow.error(- "数据重建失败: stage=replacementMarking; dates=\(normalizedDateKeys.count); detail=\(error.localizedDescription, privacy: .public)"+ let details = LogFields.joined(+ "stage=replacementMarking",+ "dates=\(normalizedDateKeys.count)",+ "detail=\(error.localizedDescription)")+ AppLog.workflow.error("数据重建失败: \(details, privacy: .public)")didFailReplacementMarking = true}@@ -164,9 +170,14 @@ actor WorkflowService {didFailSyncReplacementMarking: didFailReplacementMarking)let elapsed = duration.elapsed- AppLog.workflow.notice(- "数据重建完成: dates=\(summary.rebuiltDateCount); events=\(summary.eventCount); corruptLines=\(summary.corruptLineCount); failedDates=\(failedDateKeys.count); elapsed=\(elapsed, privacy: .public)"+ let details = LogFields.joined(+ "dates=\(summary.rebuiltDateCount)",+ "events=\(summary.eventCount)",+ "corruptLines=\(summary.corruptLineCount)",+ "failedDates=\(failedDateKeys.count)",+ "elapsed=\(elapsed)")+ AppLog.workflow.notice("数据重建完成: \(details, privacy: .public)")return WorkflowDataRebuildOutcome(snapshot: snapshot, summary: summary)}@@ -279,9 +290,12 @@ actor WorkflowService {counts.pruned = try pruneExpiredEventFiles()} catch {let elapsed = duration.elapsed- AppLog.workflow.error(- "事件汇总失败: stage=\(stage.rawValue, privacy: .public); elapsed=\(elapsed, privacy: .public); detail=\(error.localizedDescription, privacy: .public)"+ let details = LogFields.joined(+ "stage=\(stage.rawValue)",+ "elapsed=\(elapsed)",+ "detail=\(error.localizedDescription)")+ AppLog.workflow.error("事件汇总失败: \(details, privacy: .public)")idleMaintenanceRounds = 0return nil}@@ -329,9 +343,13 @@ actor WorkflowService {}} catch {counts.failed += 1- AppLog.workflow.error(- "事件汇总失败: stage=daily; date=\(task.dateKey, privacy: .public); detail=\(error.localizedDescription, privacy: .public); action=markDirty"+ let details = LogFields.joined(+ "stage=daily",+ "date=\(task.dateKey)",+ "detail=\(error.localizedDescription)",+ "action=markDirty")+ AppLog.workflow.error("事件汇总失败: \(details, privacy: .public)")markDirty(task.dateKey)}}@@ -900,9 +918,12 @@ actor WorkflowService {}} catch {// 标记丢了下一轮就不会重建这天, 数据会静默缺一块- AppLog.workflow.error(- "事件汇总失败: stage=markDirty; date=\(dateKey, privacy: .public); detail=\(error.localizedDescription, privacy: .public)"+ let details = LogFields.joined(+ "stage=markDirty",+ "date=\(dateKey)",+ "detail=\(error.localizedDescription)")+ AppLog.workflow.error("事件汇总失败: \(details, privacy: .public)")}}@@ -933,9 +954,11 @@ actor WorkflowService {try WorkflowStorage.saveMaintenanceState(state)}// 保留期到点会真的删掉原始事件文件, 数据对不上时要能查到哪些日期被清掉了- AppLog.workflow.notice(- "过期事件已清理: dates=\(expiredDateKeys.count); oldest=\(expiredDateKeys.first ?? "-", privacy: .public)"+ let details = LogFields.joined(+ "dates=\(expiredDateKeys.count)",+ "oldest=\(expiredDateKeys.first ?? "-")")+ AppLog.workflow.notice("过期事件已清理: \(details, privacy: .public)")return expiredDateKeys.count}diff --git a/CodexBar/Services/Workflow/WorkflowSyncScheduler.swift b/CodexBar/Services/Workflow/WorkflowSyncScheduler.swiftindex 74b3e7a..244546f 100644--- a/CodexBar/Services/Workflow/WorkflowSyncScheduler.swift+++ b/CodexBar/Services/Workflow/WorkflowSyncScheduler.swift@@ -47,9 +47,11 @@ final class WorkflowSyncScheduler {func requestSync(trigger: LogTrigger, activation overrideActivation: WorkflowSyncActivation? = nil) {let activation = overrideActivation ?? syncActivation()guard activation.isActive else {- AppLog.sync.notice(- "同步已跳过: trigger=\(trigger.rawValue, privacy: .public); reason=\(activation.rawValue, privacy: .public)"+ let details = LogFields.joined(+ "trigger=\(trigger.rawValue)",+ "reason=\(activation.rawValue)")+ AppLog.sync.notice("同步已跳过: \(details, privacy: .public)")clearPendingSync()return}@@ -194,9 +196,12 @@ final class WorkflowSyncScheduler {))} catch {- AppLog.workflow.error(- "数据重建失败: stage=request; dates=\(request.dateKeys.count); detail=\(error.localizedDescription, privacy: .public)"+ let details = LogFields.joined(+ "stage=request",+ "dates=\(request.dateKeys.count)",+ "detail=\(error.localizedDescription)")+ AppLog.workflow.error("数据重建失败: \(details, privacy: .public)")result = .failure(error)}@@ -225,9 +230,20 @@ final class WorkflowSyncScheduler {let sync = synchronize ? 1 : 0let range = counts.dateRangelet elapsed = duration.elapsed- AppLog.workflow.notice(- "统计刷新完成: trigger=\(triggerName, privacy: .public); sync=\(sync); idle=\(counts.idle); dates=\(counts.dates); range=\(range, privacy: .public); events=\(counts.events); written=\(counts.written); skipped=\(counts.skipped); failed=\(counts.failed); pruned=\(counts.pruned); elapsed=\(elapsed, privacy: .public)"+ let details = LogFields.joined(+ "trigger=\(triggerName)",+ "sync=\(sync)",+ "idle=\(counts.idle)",+ "dates=\(counts.dates)",+ "range=\(range)",+ "events=\(counts.events)",+ "written=\(counts.written)",+ "skipped=\(counts.skipped)",+ "failed=\(counts.failed)",+ "pruned=\(counts.pruned)",+ "elapsed=\(elapsed)")+ AppLog.workflow.notice("统计刷新完成: \(details, privacy: .public)")}private func remainingSyncCooldown() -> TimeInterval {@@ -249,9 +265,12 @@ final class WorkflowSyncScheduler {let trigger = pendingSyncTrigger ?? .autolet remaining = LogDuration.seconds(delay)- AppLog.sync.notice(- "同步已延后: trigger=\(trigger.rawValue, privacy: .public); reason=cooldown; remaining=\(remaining, privacy: .public)"+ let details = LogFields.joined(+ "trigger=\(trigger.rawValue)",+ "reason=cooldown",+ "remaining=\(remaining)")+ AppLog.sync.notice("同步已延后: \(details, privacy: .public)")let milliseconds = max(1, Int((delay * 1000).rounded(.up)))cooldownTask = Task { @MainActor [weak self] indiff --git a/CodexBar/Services/Workflow/WorkflowSyncService.swift b/CodexBar/Services/Workflow/WorkflowSyncService.swiftindex 0004f4b..5310d05 100644--- a/CodexBar/Services/Workflow/WorkflowSyncService.swift+++ b/CodexBar/Services/Workflow/WorkflowSyncService.swift@@ -80,9 +80,7 @@ actor WorkflowSyncService {trigger: LogTrigger) async -> WorkflowSyncSnapshot {guard WorkflowSyncSettings.isEnabled() else {- AppLog.sync.notice(- "同步已跳过: trigger=\(trigger.rawValue, privacy: .public); reason=syncOff"- )+ logSyncSkipped(trigger: trigger)return .disabled}@@ -142,14 +140,22 @@ actor WorkflowSyncService {// confirmed 是本地与远端已对齐的日期数, 含哈希未变而无需上传的那些// 它小于 local 就说明这一轮还有日期没落到云上let elapsed = duration.elapsed- AppLog.sync.notice(- "同步完成: trigger=\(trigger.rawValue, privacy: .public); local=\(localByDate.count); confirmed=\(confirmedDates.count); deleted=\(deletedCount); elapsed=\(elapsed, privacy: .public)"+ logSyncCompleted(+ trigger: trigger,+ localCount: localByDate.count,+ confirmedCount: confirmedDates.count,+ deletedCount: deletedCount,+ elapsed: elapsed)} catch {let reason = WorkflowSyncFailureReason.classify(error)let elapsed = duration.elapsed- AppLog.sync.error(- "同步失败: trigger=\(trigger.rawValue, privacy: .public); stage=\(stage.rawValue, privacy: .public); elapsed=\(elapsed, privacy: .public); reason=\(reason.rawValue, privacy: .public); detail=\(error.localizedDescription, privacy: .public)"+ logSyncFailed(+ trigger: trigger,+ stage: stage,+ elapsed: elapsed,+ reason: reason,+ detail: error.localizedDescription)invalidateAccountScopedCaches()failureMessage = reason.message@@ -160,6 +166,48 @@ actor WorkflowSyncService {return snapshot(from: latestState)}+ private func logSyncSkipped(trigger: LogTrigger) {+ let details = LogFields.joined(+ "trigger=\(trigger.rawValue)",+ "reason=syncOff"+ )+ AppLog.sync.notice("同步已跳过: \(details, privacy: .public)")+ }++ private func logSyncCompleted(+ trigger: LogTrigger,+ localCount: Int,+ confirmedCount: Int,+ deletedCount: Int,+ elapsed: String+ ) {+ let details = LogFields.joined(+ "trigger=\(trigger.rawValue)",+ "local=\(localCount)",+ "confirmed=\(confirmedCount)",+ "deleted=\(deletedCount)",+ "elapsed=\(elapsed)"+ )+ AppLog.sync.notice("同步完成: \(details, privacy: .public)")+ }++ private func logSyncFailed(+ trigger: LogTrigger,+ stage: WorkflowSyncStage,+ elapsed: String,+ reason: WorkflowSyncFailureReason,+ detail: String+ ) {+ let details = LogFields.joined(+ "trigger=\(trigger.rawValue)",+ "stage=\(stage.rawValue)",+ "elapsed=\(elapsed)",+ "reason=\(reason.rawValue)",+ "detail=\(detail)"+ )+ AppLog.sync.error("同步失败: \(details, privacy: .public)")+ }+private func refreshCacheBeforeUpload(localByDate: [String: LocalSyncAggregate],deviceId: String,@@ -679,9 +727,11 @@ private extension WorkflowSyncService {)} catch {// 增量拉取退化成全量重建, 代价高得多, 反复出现说明游标或缓存有问题- AppLog.sync.notice(- "增量拉取已降级: detail=\(error.localizedDescription, privacy: .public); action=fullRebuild"+ let details = LogFields.joined(+ "detail=\(error.localizedDescription)",+ "action=fullRebuild")+ AppLog.sync.notice("增量拉取已降级: \(details, privacy: .public)")try await rebuildCacheFromRemote()}}@@ -805,9 +855,11 @@ private extension WorkflowSyncService {)} catch {// 丢掉游标, 下次同步会从头拉一遍- AppLog.sync.notice(- "游标基线已降级: detail=\(error.localizedDescription, privacy: .public); action=dropCursor"+ let details = LogFields.joined(+ "detail=\(error.localizedDescription)",+ "action=dropCursor")+ AppLog.sync.notice("游标基线已降级: \(details, privacy: .public)")try? fileManager.removeItem(at: cursorURL)}}diff --git a/CodexBar/Views/Menu/CodexActivityCard.swift b/CodexBar/Views/Menu/CodexActivityCard.swiftindex 543ee1c..2507f25 100644--- a/CodexBar/Views/Menu/CodexActivityCard.swift+++ b/CodexBar/Views/Menu/CodexActivityCard.swift@@ -30,6 +30,15 @@ struct CodexActivityCard: View {keepAliveController.isActivelyPreventingSleep && !showsUnavailableState}+ private var keepAliveHelp: String {+ switch keepAliveController.sleepPreventionSource {+ case .external:+ String(localized: "系统睡眠已由其他来源关闭")+ case .codexBar, .none:+ String(localized: "已防止系统睡眠")+ }+ }+var body: some View {Group {if snapshot.hasTaskCenterContent {@@ -82,7 +91,7 @@ struct CodexActivityCard: View {.font(.system(size: 11, weight: .semibold)).foregroundStyle(Color.teal).transition(.opacity)- .help("已防止系统睡眠")+ .help(keepAliveHelp)}if content.otherTaskCount > 0 {diff --git a/CodexBar/Views/Settings/AppSettingsView.swift b/CodexBar/Views/Settings/AppSettingsView.swiftindex aa7619a..2e15d2f 100644--- a/CodexBar/Views/Settings/AppSettingsView.swift+++ b/CodexBar/Views/Settings/AppSettingsView.swift@@ -501,6 +501,13 @@ private extension AppSettingsView {)}+ if keepAliveController.isActivelyPreventingSleep,+ keepAliveController.sleepPreventionSource == .external {+ return KeepAliveCaption(+ message: String(localized: "系统睡眠已由其他来源关闭")+ )+ }+// 低电量拦下时开关开着却不防睡眠, 不留一句无从解释// 判定用 isLowBatteryBlocking 而不是 isLowBatteryActive: 后者在没有任务时也成立, 那时无话可说// 它成立即意味着 helper 已就绪, 所以排在下面那个 switch 之前不影响 helper 类问题的呈现diff --git a/CodexBar/Views/Settings/NotificationOptionsView.swift b/CodexBar/Views/Settings/NotificationOptionsView.swiftindex 161a176..b344f3e 100644--- a/CodexBar/Views/Settings/NotificationOptionsView.swift+++ b/CodexBar/Views/Settings/NotificationOptionsView.swift@@ -12,7 +12,7 @@ struct NotificationOptionsView: View {var body: some View {VStack(alignment: .leading, spacing: Metrics.rowSpacing) {- longTaskRow+ taskCompletionRowtaskWaitingRowlowQuotaRowquotaResetRow@@ -79,30 +79,30 @@ struct NotificationOptionsView: View {)}- /// Hook 未开启或链路校验不通时显示为关闭并置灰, 不修改持久化的 isLongTaskEnabled- private var longTaskRow: some View {- let isDisplayedOn = codexHookSettings.isOperable && notificationSettings.isLongTaskEnabled+ /// Hook 未开启或链路校验不通时显示为关闭并置灰, 不修改持久化的 isTaskCompletionEnabled+ private var taskCompletionRow: some View {+ let isDisplayedOn = codexHookSettings.isOperable && notificationSettings.isTaskCompletionEnabledreturn notificationOptionRow(title: "任务完成通知",isOn: Binding(get: { isDisplayedOn },- set: { notificationSettings.setLongTaskEnabled($0) }+ set: { notificationSettings.setTaskCompletionEnabled($0) }),isEnabled: codexHookSettings.isOperable,sound: Binding(- get: { notificationSettings.longTaskSound },- set: { notificationSettings.setLongTaskSound($0) }+ get: { notificationSettings.taskCompletionSound },+ set: { notificationSettings.setTaskCompletionSound($0) })) {optionPicker(title: "任务时长",selection: Binding(- get: { notificationSettings.longTaskThresholdSeconds },- set: { notificationSettings.setLongTaskThresholdSeconds($0) }+ get: { notificationSettings.taskCompletionMinimumDurationSeconds },+ set: { notificationSettings.setTaskCompletionMinimumDurationSeconds($0) }),- options: NotificationSettings.longTaskThresholdOptions,- label: { Self.longTaskOptionLabel($0) }+ options: NotificationSettings.taskCompletionDurationOptions,+ label: { Self.taskCompletionDurationLabel($0) })}}@@ -424,7 +424,7 @@ struct NotificationOptionsView: View {previewSound = nil}- private static func longTaskOptionLabel(_ seconds: Int) -> String {+ private static func taskCompletionDurationLabel(_ seconds: Int) -> String {seconds < 60? String(localized: "\(seconds) 秒"): String(localized: "\(seconds / 60) 分钟")diff --git a/CodexBarHelper/main.swift b/CodexBarHelper/main.swiftindex be0f245..71e0a84 100644--- a/CodexBarHelper/main.swift+++ b/CodexBarHelper/main.swift@@ -8,19 +8,24 @@ private let helperLog = Logger(category: "helper")+private enum LogFields {+ static func joined(_ fields: String...) -> String {+ fields.joined(separator: "; ")+ }+}+private enum CodexBarHelperStorage {- static let sentinelURL: URL = {+ static let ownershipURL: URL = {guard let applicationSupportURL = FileManager.default.urls(for: .applicationSupportDirectory,in: .localDomainMask).first else {- // launchd 会立刻重新拉起来, 不留痕就成了查不出原因的崩溃循环helperLog.error("Helper 启动失败: reason=applicationSupportMissing")exit(EXIT_FAILURE)}return applicationSupportURL.appending(path: "CodexBar", directoryHint: .isDirectory)- .appending(path: CodexBarHelperIPC.machServiceName + ".state")+ .appending(path: "helper-state.json")}()}@@ -29,34 +34,58 @@ private struct PmsetResult {let output: String}-private struct SleepRestoreResult {+private struct SleepOperationResult {let exitCode: Int32- let restoredSleepDisabled: Bool+ let source: CodexBarSleepPreventionSource+ let sleepDisabled: Bool}-/// 哨兵必须区分三态: 「不存在」和「读不出来」的处理方式完全相反-/// 把读取失败折叠成 nil 会让恢复流程认为无需恢复, 使 SleepDisabled=1 永久残留-private enum SentinelState {- case absent- case present(previouslyDisabled: Bool)- case unreadable(Error)+private struct ClientLease {+ var generation: UInt64+ var isRequesting: Bool+ var connectionIdentifier: UUID?+}++private enum SleepOwnership: String, Codable {+ case idle+ case owned+ case restoring- /// 读取失败也必须进入恢复流程: 记录损坏时无法排除「睡眠正被我们禁用着」var needsRestore: Bool {+ self != .idle+ }++ var sharedState: CodexBarSleepOwnershipState {switch self {- case .absent:- false- case .present, .unreadable:- true+ case .idle:+ .idle+ case .owned:+ .owned+ case .restoring:+ .restoring}}}+private struct SleepOwnershipRecord: Codable {+ let schema: Int+ let state: SleepOwnership+ let transaction: UUID+ let identifier: String?+ let updated: Date+}++private enum OwnershipRecordState {+ case absent+ case present(SleepOwnershipRecord)+ case unreadable(Error)+}+private enum SleepRestoreTrigger: String {case appRequestcase connectionWatchdogcase helperStartup- case sentinelCheck+ case ownershipCheckcase helperTermination}@@ -110,18 +139,81 @@ private enum PmsetRunner {return nil}}- // pmset 只在 disablesleep=1 时输出 SleepDisabled; 字段缺失表示默认值 0+ // pmset 只在 disablesleep=1 时输出 SleepDisabled, 字段缺失表示默认值 0return false}}-private final class CodexBarHelperRuntime: NSObject, NSXPCListenerDelegate, CodexBarHelperProtocol,+private final class CodexBarHelperConnectionSession: NSObject, CodexBarHelperProtocol,@unchecked Sendable {+ let identifier = UUID()+ private weak var runtime: CodexBarHelperRuntime?++ init(runtime: CodexBarHelperRuntime) {+ self.runtime = runtime+ }++ func setSleepPreventionRequested(+ _ requested: Bool,+ clientSessionID: String,+ generation: UInt64,+ reply: @escaping @Sendable (Int32, Int, Bool) -> Void+ ) {+ guard let runtime else {+ reply(-1, CodexBarSleepPreventionSource.none.rawValue, false)+ return+ }+ runtime.setSleepPreventionRequested(+ requested,+ clientSessionID: clientSessionID,+ generation: generation,+ for: identifier,+ reply: reply+ )+ }++ func getSleepPreventionStatus(+ reply: @escaping @Sendable (Int32, Int, Int, Bool) -> Void+ ) {+ guard let runtime else {+ reply(-1, CodexBarSleepOwnershipState.idle.rawValue, 0, false)+ return+ }+ runtime.getSleepPreventionStatus(+ for: identifier,+ reply: reply+ )+ }++ func resetSleepAfterUpdate(+ _ updateIdentifier: String,+ reply: @escaping @Sendable (Int32) -> Void+ ) {+ guard let runtime else {+ reply(-1)+ return+ }+ runtime.resetSleepAfterUpdate(+ updateIdentifier,+ for: identifier,+ reply: reply+ )+ }+}++private final class CodexBarHelperRuntime: NSObject, NSXPCListenerDelegate, @unchecked Sendable {private let queue = DispatchQueue(label: CodexBarHelperIPC.machServiceName + ".state")- private let sentinelURL = CodexBarHelperStorage.sentinelURL- private var connections = Set<ObjectIdentifier>()- private var watchdog: DispatchWorkItem?- private var sentinelTimer: DispatchSourceTimer?+ private let ownershipURL = CodexBarHelperStorage.ownershipURL+ private var ownership = SleepOwnership.idle+ private var transactionID = UUID()+ private var lastCompletedUpdateIdentifier: String?+ private var connections = Set<UUID>()+ private var clients = [UUID: ClientLease]()+ private var watchdogs = [UUID: DispatchWorkItem]()+ private var watchdogTokens = [UUID: UUID]()+ private var lastKnownSleepDisabled: Bool?+ private var ownershipTimer: DispatchSourceTimer?+ private var scheduledOwnershipCheckInterval: TimeInterval?private var signalSources = [DispatchSourceSignal]()private var listener: NSXPCListener?@@ -132,40 +224,31 @@ private final class CodexBarHelperRuntime: NSObject, NSXPCListenerDelegate, Code}do {- try ensureSentinelDirectory()+ try ensureOwnershipDirectory()} catch {- let sentinelDirectoryPath = sentinelURL.deletingLastPathComponent().path- helperLog.error(- "Helper 启动失败: reason=sentinelDirectory; path=\(sentinelDirectoryPath, privacy: .public); detail=\(error.localizedDescription, privacy: .public)"+ let directoryPath = ownershipURL.deletingLastPathComponent().path+ let details = LogFields.joined(+ "reason=ownershipDirectory",+ "path=\(directoryPath)",+ "detail=\(error.localizedDescription)")+ helperLog.error("Helper 启动失败: \(details, privacy: .public)")exit(EXIT_FAILURE)}- // 启动时哨兵还在说明上次异常退出, 这条是判断有没有残留过的起点- // 读一次就够, 恢复判断也用这同一份结果- let startupSentinel = sentinelState()- let sentinelName = switch startupSentinel {- case .absent: "absent"- case .present: "present"- case .unreadable: "unreadable"- }- helperLog.notice("Helper 已启动: sentinel=\(sentinelName, privacy: .public)")-- // 读取失败也必须进入恢复流程: 记录损坏时无法排除「睡眠正被我们禁用着」- if startupSentinel.needsRestore {- _ = restoreSleep(trigger: .helperStartup)- }-- installSentinelTimer()+ recoverOwnershipAtStartup()+ installOwnershipTimer()installSignalHandlers()let clientCodeSigningRequirement: Stringdo {clientCodeSigningRequirement = try Self.makeClientCodeSigningRequirement()} catch {- helperLog.error(- "Helper 启动失败: reason=listener; detail=\(error.localizedDescription, privacy: .public)"+ let details = LogFields.joined(+ "reason=listener",+ "detail=\(error.localizedDescription)")+ helperLog.error("Helper 启动失败: \(details, privacy: .public)")exit(EXIT_FAILURE)}@@ -178,17 +261,107 @@ private final class CodexBarHelperRuntime: NSObject, NSXPCListenerDelegate, Code// MARK: - XPC 接口- func setSleepDisabled(- _ disabled: Bool,- reply: @escaping @Sendable (Int32, Bool) -> Void+ fileprivate func setSleepPreventionRequested(+ _ requested: Bool,+ clientSessionID: String,+ generation: UInt64,+ for identifier: UUID,+ reply: @escaping @Sendable (Int32, Int, Bool) -> Void) {queue.async { [self] in- if disabled {- reply(disableSleep(), true)+ guard connections.contains(identifier),+ let clientIdentifier = UUID(uuidString: clientSessionID) else {+ reply(-1, CodexBarSleepPreventionSource.none.rawValue, false)+ return+ }++ if let currentLease = clients[clientIdentifier] {+ guard generation >= currentLease.generation else {+ let result = currentOperationResult()+ reply(result.exitCode, result.source.rawValue, result.sleepDisabled)+ return+ }+ guard generation != currentLease.generation+ || requested == currentLease.isRequesting else {+ reply(-1, currentSource().rawValue, lastKnownSleepDisabled ?? false)+ return+ }+ }++ cancelWatchdog(for: clientIdentifier)+ let source = currentSource()+ clients[clientIdentifier] = ClientLease(+ generation: generation,+ isRequesting: requested,+ connectionIdentifier: identifier+ )++ let result: SleepOperationResult+ if requested {+ let isNewRequest = source == .none+ result = reconcileRequestedSleep(logsExternalState: isNewRequest)} else {- let result = restoreSleep(trigger: .appRequest)- reply(result.exitCode, result.restoredSleepDisabled)+ result = reconcileReleasedSleep(source: source, trigger: .appRequest)+ }+ scheduleOwnershipTimerIfNeeded()+ reply(result.exitCode, result.source.rawValue, result.sleepDisabled)+ }+ }++ fileprivate func getSleepPreventionStatus(+ for identifier: UUID,+ reply: @escaping @Sendable (Int32, Int, Int, Bool) -> Void+ ) {+ queue.async { [self] in+ guard connections.contains(identifier),+ let lastKnownSleepDisabled else {+ reply(-1, ownership.sharedState.rawValue, activeClientCount, false)+ return+ }+ reply(+ 0,+ ownership.sharedState.rawValue,+ activeClientCount,+ lastKnownSleepDisabled+ )+ }+ }++ fileprivate func resetSleepAfterUpdate(+ _ updateIdentifier: String,+ for identifier: UUID,+ reply: @escaping @Sendable (Int32) -> Void+ ) {+ queue.async { [self] in+ guard connections.contains(identifier),+ Self.isValidUpdateIdentifier(updateIdentifier) else {+ reply(-1)+ return}+ guard lastCompletedUpdateIdentifier != updateIdentifier else {+ reply(0)+ return+ }++ let result = setAndVerifySleepDisabled(false)+ guard result.exitCode == 0 else {+ reply(result.exitCode)+ return+ }++ let previousUpdateIdentifier = lastCompletedUpdateIdentifier+ lastCompletedUpdateIdentifier = updateIdentifier+ do {+ try persistOwnership(.idle)+ } catch {+ lastCompletedUpdateIdentifier = previousUpdateIdentifier+ logOwnershipWriteFailure(error)+ reply(-1)+ return+ }++ helperLog.notice("Helper 更新后睡眠状态已重置")+ reply(0)}}@@ -196,11 +369,12 @@ private final class CodexBarHelperRuntime: NSObject, NSXPCListenerDelegate, Code_: NSXPCListener,shouldAcceptNewConnection newConnection: NSXPCConnection) -> Bool {- let identifier = ObjectIdentifier(newConnection)+ let session = CodexBarHelperConnectionSession(runtime: self)+ let identifier = session.identifiernewConnection.exportedInterface = NSXPCInterface(with: CodexBarHelperProtocol.self)- newConnection.exportedObject = self+ newConnection.exportedObject = sessionlet connectionDropped: () -> Void = { [weak self] inself?.connectionDropped(identifier)@@ -209,154 +383,398 @@ private final class CodexBarHelperRuntime: NSObject, NSXPCListenerDelegate, CodenewConnection.interruptionHandler = connectionDroppedqueue.sync {- connections.insert(identifier)- watchdog?.cancel()- watchdog = nil+ _ = connections.insert(identifier)}newConnection.resume()return true}- private func connectionDropped(_ identifier: ObjectIdentifier) {+ private func connectionDropped(_ identifier: UUID) {queue.async { [self] in- guard connections.remove(identifier) != nil,- connections.isEmpty,- sentinelNeedsRestore() else {+ guard connections.remove(identifier) != nil else {return}- watchdog?.cancel()- let workItem = DispatchWorkItem { [weak self] in- guard let self else {- return+ let droppedClients = clients.compactMap { clientIdentifier, lease in+ lease.connectionIdentifier == identifier ? clientIdentifier : nil+ }+ for clientIdentifier in droppedClients {+ guard var lease = clients[clientIdentifier] else {+ continue}- watchdog = nil- guard connections.isEmpty, sentinelNeedsRestore() else {- return+ guard lease.isRequesting else {+ clients[clientIdentifier] = nil+ continue}- _ = restoreSleep(trigger: .connectionWatchdog)++ lease.connectionIdentifier = nil+ clients[clientIdentifier] = lease+ scheduleWatchdog(for: clientIdentifier, generation: lease.generation)}- watchdog = workItem- queue.asyncAfter(- deadline: .now() + CodexBarHelperIPC.watchdogGraceSeconds,- execute: workItem- )+ scheduleOwnershipTimerIfNeeded()}}- // MARK: - 睡眠切换与恢复+ private func scheduleWatchdog(for clientIdentifier: UUID, generation: UInt64) {+ guard watchdogs[clientIdentifier] == nil else {+ return+ }- private func disableSleep() -> Int32 {- var didCreateSentinel = false- // 哨兵记的是接管前系统原本的 SleepDisabled, 恢复要还原到它而不是无脑写 0- var sentinelValue = "-"- switch sentinelState() {- case let .present(previouslyDisabled):- sentinelValue = previouslyDisabled ? "1" : "0"- 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(- "pmset 读取失败: exit=\(current.result.exitCode); detail=\(current.result.output, privacy: .public)"- )- return current.result.exitCode == 0 ? -1 : current.result.exitCode+ let token = UUID()+ let workItem = DispatchWorkItem { [weak self] in+ guard let self, watchdogTokens[clientIdentifier] == token else {+ return+ }+ watchdogs[clientIdentifier] = nil+ watchdogTokens[clientIdentifier] = nil+ guard let lease = clients[clientIdentifier],+ lease.generation == generation,+ lease.isRequesting,+ lease.connectionIdentifier == nil else {+ return}- do {- try writeSentinel(previouslyDisabled: wasDisabled)- didCreateSentinel = true- sentinelValue = wasDisabled ? "1" : "0"- } catch {- let sentinelPath = sentinelURL.path- helperLog.error(- "睡眠哨兵写入失败: path=\(sentinelPath, privacy: .public); detail=\(error.localizedDescription, privacy: .public)"+ let source = currentSource()+ clients[clientIdentifier] = nil+ _ = reconcileReleasedSleep(source: source, trigger: .connectionWatchdog)+ scheduleOwnershipTimerIfNeeded()+ }+ watchdogs[clientIdentifier] = workItem+ watchdogTokens[clientIdentifier] = token+ queue.asyncAfter(+ deadline: .now() + CodexBarHelperIPC.watchdogGraceSeconds,+ execute: workItem+ )+ }++ private func cancelWatchdog(for clientIdentifier: UUID) {+ watchdogs.removeValue(forKey: clientIdentifier)?.cancel()+ watchdogTokens[clientIdentifier] = nil+ }++ // MARK: - 所有权与睡眠切换++ private func reconcileRequestedSleep(logsExternalState: Bool) -> SleepOperationResult {+ if ownership == .restoring {+ let recovery = restoreOwnedSleep(trigger: .appRequest)+ guard recovery.exitCode == 0 else {+ return recovery+ }+ }++ if ownership == .owned {+ guard validateOrRepairOwnedRecord() else {+ return recoverFromOwnedRecordFailure()+ }++ let current = readCurrentSleepDisabled()+ guard current.result.exitCode == 0, let sleepDisabled = current.value else {+ logPmsetReadFailure(current.result)+ return SleepOperationResult(+ exitCode: normalizedFailureCode(current.result.exitCode),+ source: .codexBar,+ sleepDisabled: false)- return -1}++ if !sleepDisabled {+ let result = setAndVerifySleepDisabled(true)+ guard result.exitCode == 0 else {+ return SleepOperationResult(+ exitCode: result.exitCode,+ source: .codexBar,+ sleepDisabled: result.value ?? false+ )+ }+ guard validateOrRepairOwnedRecord() else {+ return recoverFromOwnedRecordFailure()+ }+ }+ return SleepOperationResult(exitCode: 0, source: .codexBar, sleepDisabled: true)}- let result = PmsetRunner.setSleepDisabled(true)- guard result.exitCode == 0 else {- if didCreateSentinel {- try? FileManager.default.removeItem(at: sentinelURL)+ let current = readCurrentSleepDisabled()+ guard current.result.exitCode == 0, let sleepDisabled = current.value else {+ logPmsetReadFailure(current.result)+ return SleepOperationResult(+ exitCode: normalizedFailureCode(current.result.exitCode),+ source: .none,+ sleepDisabled: false+ )+ }++ guard !sleepDisabled else {+ if logsExternalState {+ helperLog.notice("系统睡眠已由其他来源关闭")}- helperLog.error(- "系统睡眠关闭失败: exit=\(result.exitCode); detail=\(result.output, privacy: .public)"+ return SleepOperationResult(exitCode: 0, source: .external, sleepDisabled: true)+ }++ do {+ try persistOwnership(.owned)+ } catch {+ logOwnershipWriteFailure(error)+ return SleepOperationResult(exitCode: -1, source: .none, sleepDisabled: false)+ }++ let result = setAndVerifySleepDisabled(true)+ guard result.exitCode == 0 else {+ return SleepOperationResult(+ exitCode: result.exitCode,+ source: .codexBar,+ sleepDisabled: result.value ?? false)- return result.exitCode+ }+ guard validateOrRepairOwnedRecord() else {+ return recoverFromOwnedRecordFailure()}- helperLog.notice("系统睡眠已关闭: sentinel=\(sentinelValue, privacy: .public)")- return 0+ helperLog.notice("系统睡眠已由 CodexBar 关闭")+ return SleepOperationResult(exitCode: 0, source: .codexBar, sleepDisabled: true)}- @discardableResult- private func restoreSleep(trigger: SleepRestoreTrigger) -> SleepRestoreResult {- let previouslyDisabled: Bool- switch sentinelState() {- case .absent:- // 没接管过就没有要恢复的东西, 这个值只是占位, 不代表系统真实状态- // 必须保持 true: App 用它抑制补发合盖睡眠, 换成实测值会让从未接管的这一轮把机器按睡- return SleepRestoreResult(exitCode: 0, restoredSleepDisabled: true)- case let .present(value):- previouslyDisabled = value- case let .unreadable(error):- // 读不出原值时按系统默认的「允许睡眠」恢复- // 宁可多恢复一次(pmset 幂等), 也不能把 SleepDisabled=1 永久留给用户- helperLog.error(- "睡眠哨兵读取失败: trigger=\(trigger.rawValue, privacy: .public); detail=\(error.localizedDescription, privacy: .public); action=forceRestore"+ private func reconcileReleasedSleep(+ source: CodexBarSleepPreventionSource,+ trigger: SleepRestoreTrigger+ ) -> SleepOperationResult {+ guard activeClientCount == 0 else {+ return reconcileRequestedSleep(logsExternalState: false)+ }++ guard ownership.needsRestore else {+ // 未取得所有权时不写 pmset, 保留最近一次实测值供 App 判断是否需要补发系统睡眠+ return SleepOperationResult(+ exitCode: 0,+ source: source,+ sleepDisabled: lastKnownSleepDisabled ?? (source == .external))- previouslyDisabled = false+ }+ return restoreOwnedSleep(trigger: trigger)+ }++ @discardableResult+ private func restoreOwnedSleep(trigger: SleepRestoreTrigger) -> SleepOperationResult {+ do {+ try persistOwnership(.restoring)+ } catch {+ // 写恢复中标记失败也必须继续尝试写回 0, 否则记录故障本身会把机器永久卡在 1+ logOwnershipWriteFailure(error)}- let previousValue = previouslyDisabled ? 1 : 0- let result = PmsetRunner.setSleepDisabled(previouslyDisabled)+ let result = setAndVerifySleepDisabled(false)guard result.exitCode == 0 else {- helperLog.error(- "系统睡眠恢复失败: trigger=\(trigger.rawValue, privacy: .public); sleepDisabled=\(previousValue); exit=\(result.exitCode); detail=\(result.output, privacy: .public)"+ let details = LogFields.joined(+ "trigger=\(trigger.rawValue)",+ "exit=\(result.exitCode)")- return SleepRestoreResult(+ helperLog.error("系统睡眠恢复失败: \(details, privacy: .public)")+ return SleepOperationResult(exitCode: result.exitCode,- restoredSleepDisabled: true+ source: .codexBar,+ sleepDisabled: result.value ?? true)}- try? FileManager.default.removeItem(at: sentinelURL)- helperLog.notice(- "系统睡眠已恢复: trigger=\(trigger.rawValue, privacy: .public); sleepDisabled=\(previousValue)"+ do {+ try persistOwnership(.idle)+ } catch {+ logOwnershipWriteFailure(error)+ return SleepOperationResult(exitCode: -1, source: .codexBar, sleepDisabled: false)+ }++ let details = LogFields.joined(+ "trigger=\(trigger.rawValue)",+ "sleepDisabled=0"+ )+ helperLog.notice("系统睡眠已恢复: \(details, privacy: .public)")+ return SleepOperationResult(exitCode: 0, source: .codexBar, sleepDisabled: false)+ }++ private func setAndVerifySleepDisabled(+ _ disabled: Bool+ ) -> (exitCode: Int32, value: Bool?) {+ let writeResult = PmsetRunner.setSleepDisabled(disabled)+ guard writeResult.exitCode == 0 else {+ let details = LogFields.joined(+ "target=\(disabled ? 1 : 0)",+ "exit=\(writeResult.exitCode)",+ "detail=\(writeResult.output)"+ )+ helperLog.error("pmset 写入失败: \(details, privacy: .public)")+ return (writeResult.exitCode, nil)+ }++ let readResult = readCurrentSleepDisabled()+ guard readResult.result.exitCode == 0, let value = readResult.value else {+ logPmsetReadFailure(readResult.result)+ return (normalizedFailureCode(readResult.result.exitCode), nil)+ }+ guard value == disabled else {+ let details = LogFields.joined(+ "target=\(disabled ? 1 : 0)",+ "actual=\(value ? 1 : 0)"+ )+ helperLog.error("pmset 写入校验失败: \(details, privacy: .public)")+ return (-1, value)+ }+ return (0, value)+ }++ private func readCurrentSleepDisabled() -> (result: PmsetResult, value: Bool?) {+ let current = PmsetRunner.currentSleepDisabled()+ if current.result.exitCode == 0, let value = current.value {+ lastKnownSleepDisabled = value+ }+ return current+ }++ private func validateOrRepairOwnedRecord() -> Bool {+ guard ownership == .owned else {+ return false+ }++ if case let .present(record) = ownershipRecordState(),+ record.state == .owned,+ record.transaction == transactionID {+ return true+ }++ helperLog.error("睡眠所有权记录与运行状态不一致: action=repair")+ do {+ try persistOwnership(.owned)+ helperLog.notice("睡眠所有权记录已修复")+ return true+ } catch {+ logOwnershipWriteFailure(error)+ return false+ }+ }++ private func recoverFromOwnedRecordFailure() -> SleepOperationResult {+ let recovery = restoreOwnedSleep(trigger: .ownershipCheck)+ return SleepOperationResult(+ exitCode: recovery.exitCode == 0 ? -1 : recovery.exitCode,+ source: .codexBar,+ sleepDisabled: recovery.sleepDisabled)- return SleepRestoreResult(+ }++ private func currentSource() -> CodexBarSleepPreventionSource {+ if ownership.needsRestore {+ return .codexBar+ }+ return activeClientCount == 0 ? .none : .external+ }++ private func currentOperationResult() -> SleepOperationResult {+ guard let lastKnownSleepDisabled else {+ return SleepOperationResult(exitCode: -1, source: currentSource(), sleepDisabled: false)+ }+ return SleepOperationResult(exitCode: 0,- restoredSleepDisabled: previouslyDisabled+ source: currentSource(),+ sleepDisabled: lastKnownSleepDisabled)}- private func installSentinelTimer() {- let timer = DispatchSource.makeTimerSource(queue: queue)- timer.schedule(- deadline: .now() + CodexBarHelperIPC.sentinelCheckIntervalSeconds,- repeating: CodexBarHelperIPC.sentinelCheckIntervalSeconds,- leeway: .seconds(5)+ private var activeClientCount: Int {+ clients.values.lazy.filter(\.isRequesting).count+ }++ private func normalizedFailureCode(_ exitCode: Int32) -> Int32 {+ exitCode == 0 ? -1 : exitCode+ }++ private func logPmsetReadFailure(_ result: PmsetResult) {+ let details = LogFields.joined(+ "exit=\(result.exitCode)",+ "detail=\(result.output)")+ helperLog.error("pmset 读取失败: \(details, privacy: .public)")+ }++ // MARK: - 异常恢复++ private func recoverOwnershipAtStartup() {+ let state = ownershipRecordState()+ switch state {+ case .absent:+ do {+ try persistOwnership(.idle)+ helperLog.notice("Helper 已启动: ownership=idle")+ } catch {+ logOwnershipWriteFailure(error)+ exit(EXIT_FAILURE)+ }+ case let .present(record):+ ownership = record.state+ transactionID = record.transaction+ lastCompletedUpdateIdentifier = record.identifier+ helperLog.notice(+ "Helper 已启动: ownership=\(record.state.rawValue, privacy: .public)"+ )+ if record.state.needsRestore {+ _ = restoreOwnedSleep(trigger: .helperStartup)+ }+ case let .unreadable(error):+ // 损坏记录无法证明所有权, 启动时按最安全的默认值 0 收敛+ let details = LogFields.joined(+ "detail=\(error.localizedDescription)",+ "action=forceRestore"+ )+ helperLog.error("睡眠所有权记录无效: \(details, privacy: .public)")+ ownership = .restoring+ _ = restoreOwnedSleep(trigger: .helperStartup)+ }++ if lastKnownSleepDisabled == nil {+ let current = readCurrentSleepDisabled()+ if current.result.exitCode != 0 || current.value == nil {+ logPmsetReadFailure(current.result)+ }+ }+ }++ private func installOwnershipTimer() {+ let timer = DispatchSource.makeTimerSource(queue: queue)timer.setEventHandler { [weak self] in- guard let self,- connections.isEmpty,- watchdog == nil,- sentinelNeedsRestore() else {+ guard let self else {return}- _ = restoreSleep(trigger: .sentinelCheck)+ if activeClientCount > 0 {+ _ = reconcileRequestedSleep(logsExternalState: false)+ } else if ownership.needsRestore, watchdogs.isEmpty {+ _ = restoreOwnedSleep(trigger: .ownershipCheck)+ }+ scheduleOwnershipTimerIfNeeded()}+ ownershipTimer = timer+ scheduleOwnershipTimerIfNeeded(force: true)timer.resume()- sentinelTimer = timer+ }++ private func scheduleOwnershipTimerIfNeeded(force: Bool = false) {+ guard let ownershipTimer else {+ return+ }++ let interval: TimeInterval = if activeClientCount == 0 {+ CodexBarHelperIPC.recoveryCheckIntervalSeconds+ } else if ownership.needsRestore {+ CodexBarHelperIPC.ownedCheckIntervalSeconds+ } else {+ CodexBarHelperIPC.externalCheckIntervalSeconds+ }+ guard force || interval != scheduledOwnershipCheckInterval else {+ return+ }++ scheduledOwnershipCheckInterval = interval+ ownershipTimer.schedule(+ deadline: .now() + interval,+ repeating: interval,+ leeway: .seconds(Int(CodexBarHelperIPC.checkLeewaySeconds))+ )}private func installSignalHandlers() {@@ -367,9 +785,8 @@ private final class CodexBarHelperRuntime: NSObject, NSXPCListenerDelegate, Codeguard let self else {exit(EXIT_SUCCESS)}- // 和另外三个触发源一样先判断: 空闲态退出没有东西要恢复, 不必再 fork 一次 pmset- if sentinelNeedsRestore() {- _ = restoreSleep(trigger: .helperTermination)+ if ownership.needsRestore {+ _ = restoreOwnedSleep(trigger: .helperTermination)}exit(EXIT_SUCCESS)}@@ -378,13 +795,13 @@ private final class CodexBarHelperRuntime: NSObject, NSXPCListenerDelegate, Code}}- // MARK: - 恢复哨兵+ // MARK: - 所有权记录- private func ensureSentinelDirectory() throws {- let directoryURL = sentinelURL.deletingLastPathComponent()+ private func ensureOwnershipDirectory() throws {+ let directoryURL = ownershipURL.deletingLastPathComponent()var info = stat()if lstat(directoryURL.path, &info) == 0 {- try validateSentinelDirectory(info)+ try validateOwnershipDirectory(info)return}@@ -401,103 +818,249 @@ private final class CodexBarHelperRuntime: NSObject, NSXPCListenerDelegate, Code)}- private func validateSentinelDirectory(_ info: stat) throws {+ private func validateOwnershipDirectory(_ info: stat) throws {guard info.st_mode & S_IFMT == S_IFDIR else {- throw CodexBarHelperError.insecureSentinelDirectory(- "目录类型错误: actual=\(fileTypeName(info.st_mode)); expected=directory"+ let details = LogFields.joined(+ "actual=\(fileTypeName(info.st_mode))",+ "expected=directory"+ )+ throw CodexBarHelperError.insecureOwnershipDirectory(+ "目录类型错误: \(details)")}guard info.st_uid == 0 else {- throw CodexBarHelperError.insecureSentinelDirectory(- "所有者错误: actual=\(info.st_uid); expected=0"+ let details = LogFields.joined(+ "actual=\(info.st_uid)",+ "expected=0"+ )+ throw CodexBarHelperError.insecureOwnershipDirectory(+ "所有者错误: \(details)")}guard info.st_mode & 0o022 == 0 else {- throw CodexBarHelperError.insecureSentinelDirectory(- "目录权限错误: actual=\(permissionString(info.st_mode)); forbidden=0022"+ let details = LogFields.joined(+ "actual=\(permissionString(info.st_mode))",+ "forbidden=0022"+ )+ throw CodexBarHelperError.insecureOwnershipDirectory(+ "目录权限错误: \(details)")}}- private func writeSentinel(previouslyDisabled: Bool) throws {- try Data(previouslyDisabled ? "1".utf8 : "0".utf8).write(- to: sentinelURL,- options: .atomic+ private func persistOwnership(_ state: SleepOwnership) throws {+ try ensureOwnershipDirectory()+ if state == .owned, ownership == .idle {+ transactionID = UUID()+ }+ let record = SleepOwnershipRecord(+ schema: 1,+ state: state,+ transaction: transactionID,+ identifier: lastCompletedUpdateIdentifier,+ updated: Date())- try FileManager.default.setAttributes(- [.ownerAccountID: 0, .groupOwnerAccountID: 0, .posixPermissions: 0o600],- ofItemAtPath: sentinelURL.path+ let encoder = JSONEncoder()+ encoder.dateEncodingStrategy = .iso8601+ let data = try encoder.encode(record)+ try writeOwnershipDataDurably(data)+ guard case let .present(savedRecord) = ownershipRecordState(),+ savedRecord.state == state,+ savedRecord.transaction == transactionID,+ savedRecord.identifier == lastCompletedUpdateIdentifier else {+ throw CodexBarHelperError.invalidOwnershipRecord("写入后校验失败")+ }+ ownership = state+ }++ private func writeOwnershipDataDurably(_ data: Data) throws {+ let directoryURL = ownershipURL.deletingLastPathComponent()+ let temporaryURL = directoryURL.appending(+ path: ".helper-state.\(UUID().uuidString).tmp")- guard try readSentinelPreviousState() != nil else {- throw CodexBarHelperError.invalidSentinel("记录不存在")+ var descriptor = open(+ temporaryURL.path,+ O_WRONLY | O_CREAT | O_EXCL | O_CLOEXEC,+ mode_t(0o600)+ )+ guard descriptor >= 0 else {+ throw ownershipWriteError(operation: "open")+ }++ var shouldRemoveTemporaryFile = true+ defer {+ if descriptor >= 0 {+ _ = Darwin.close(descriptor)+ }+ if shouldRemoveTemporaryFile {+ _ = unlink(temporaryURL.path)+ }+ }++ try data.withUnsafeBytes { bytes in+ guard let baseAddress = bytes.baseAddress else {+ return+ }++ var offset = 0+ while offset < bytes.count {+ let written = Darwin.write(+ descriptor,+ baseAddress.advanced(by: offset),+ bytes.count - offset+ )+ if written < 0, errno == EINTR {+ continue+ }+ guard written > 0 else {+ throw ownershipWriteError(operation: "write")+ }+ offset += written+ }+ }++ guard fchown(descriptor, 0, 0) == 0 else {+ throw ownershipWriteError(operation: "fchown")+ }+ guard fchmod(descriptor, mode_t(0o600)) == 0 else {+ throw ownershipWriteError(operation: "fchmod")+ }+ try synchronizeOwnershipFile(descriptor)++ let closeResult = Darwin.close(descriptor)+ descriptor = -1+ guard closeResult == 0 else {+ throw ownershipWriteError(operation: "close")+ }+ guard rename(temporaryURL.path, ownershipURL.path) == 0 else {+ throw ownershipWriteError(operation: "rename")+ }+ shouldRemoveTemporaryFile = false+ try synchronizeOwnershipDirectory(directoryURL)+ }++ private func synchronizeOwnershipFile(_ descriptor: Int32) throws {+ if fcntl(descriptor, F_FULLFSYNC) == 0 {+ return+ }+ guard fsync(descriptor) == 0 else {+ throw ownershipWriteError(operation: "fsync")}}- private func sentinelState() -> SentinelState {+ private func synchronizeOwnershipDirectory(_ directoryURL: URL) throws {+ let descriptor = open(directoryURL.path, O_RDONLY | O_CLOEXEC)+ guard descriptor >= 0 else {+ throw ownershipWriteError(operation: "openDirectory")+ }+ defer {+ _ = Darwin.close(descriptor)+ }++ guard fsync(descriptor) == 0 else {+ let errorCode = errno+ // 部分文件系统不支持对目录执行 fsync, 文件本身已经完成 F_FULLFSYNC+ if errorCode == EINVAL || errorCode == ENOTSUP {+ return+ }+ throw ownershipWriteError(operation: "fsyncDirectory", code: errorCode)+ }+ }++ private func ownershipWriteError(+ operation: String,+ code: Int32 = errno+ ) -> CodexBarHelperError {+ .ownershipWriteFailed(operation: operation, code: code)+ }++ private func ownershipRecordState() -> OwnershipRecordState {do {- guard let previouslyDisabled = try readSentinelPreviousState() else {+ guard let record = try readOwnershipRecord() else {return .absent}- return .present(previouslyDisabled: previouslyDisabled)+ return .present(record)} catch {return .unreadable(error)}}- private func sentinelNeedsRestore() -> Bool {- sentinelState().needsRestore- }-- private func readSentinelPreviousState() throws -> Bool? {+ private func readOwnershipRecord() throws -> SleepOwnershipRecord? {var info = stat()- guard lstat(sentinelURL.path, &info) == 0 else {+ guard lstat(ownershipURL.path, &info) == 0 else {if errno == ENOENT {return nil}- throw CodexBarHelperError.invalidSentinel(+ throw CodexBarHelperError.invalidOwnershipRecord("读取属性失败: errno=\(errno)")}guard info.st_mode & S_IFMT == S_IFREG else {- throw CodexBarHelperError.invalidSentinel(- "文件类型错误: actual=\(fileTypeName(info.st_mode)); expected=file"+ let details = LogFields.joined(+ "actual=\(fileTypeName(info.st_mode))",+ "expected=file"+ )+ throw CodexBarHelperError.invalidOwnershipRecord(+ "文件类型错误: \(details)")}guard info.st_uid == 0 else {- throw CodexBarHelperError.invalidSentinel(- "所有者错误: actual=\(info.st_uid); expected=0"+ let details = LogFields.joined(+ "actual=\(info.st_uid)",+ "expected=0"+ )+ throw CodexBarHelperError.invalidOwnershipRecord(+ "所有者错误: \(details)")}guard info.st_mode & 0o022 == 0 else {- throw CodexBarHelperError.invalidSentinel(- "文件权限错误: actual=\(permissionString(info.st_mode)); forbidden=0022"+ let details = LogFields.joined(+ "actual=\(permissionString(info.st_mode))",+ "forbidden=0022"+ )+ throw CodexBarHelperError.invalidOwnershipRecord(+ "文件权限错误: \(details)")}let data: Datado {- data = try Data(contentsOf: sentinelURL)+ data = try Data(contentsOf: ownershipURL)} catch {- throw CodexBarHelperError.invalidSentinel(+ throw CodexBarHelperError.invalidOwnershipRecord("读取内容失败: detail=\(error.localizedDescription)")}- guard let value = String(data: data, encoding: .utf8) else {- throw CodexBarHelperError.invalidSentinel(- "文件编码错误: actual=unknown; expected=UTF-8"++ let decoder = JSONDecoder()+ decoder.dateDecodingStrategy = .iso8601+ let record: SleepOwnershipRecord+ do {+ record = try decoder.decode(SleepOwnershipRecord.self, from: data)+ } catch {+ throw CodexBarHelperError.invalidOwnershipRecord(+ "解码失败: detail=\(error.localizedDescription)")}-- switch value {- case "0":- return false- case "1":- return true- default:- throw CodexBarHelperError.invalidSentinel(- "文件内容错误: actual=\(data.count); expected=0|1"+ guard record.schema == 1 else {+ let details = LogFields.joined(+ "actual=\(record.schema)",+ "expected=1"+ )+ throw CodexBarHelperError.invalidOwnershipRecord(+ "版本错误: \(details)")}+ return record+ }++ private func logOwnershipWriteFailure(_ error: Error) {+ let path = ownershipURL.path+ let details = LogFields.joined(+ "path=\(path)",+ "detail=\(error.localizedDescription)"+ )+ helperLog.error("睡眠所有权记录写入失败: \(details, privacy: .public)")}private func fileTypeName(_ mode: mode_t) -> String {@@ -518,20 +1081,35 @@ private final class CodexBarHelperRuntime: NSObject, NSXPCListenerDelegate, CodeString(format: "%04o", Int32(mode & 0o7777))}+ private static func isValidUpdateIdentifier(_ identifier: String) -> Bool {+ let bytes = identifier.utf8+ return bytes.count == 64 && bytes.allSatisfy { byte in+ (48 ... 57).contains(byte) || (97 ... 102).contains(byte)+ }+ }+private static func makeClientCodeSigningRequirement() throws -> String {var runningCode: SecCode?var status = SecCodeCopySelf(SecCSFlags(), &runningCode)guard status == errSecSuccess, let runningCode else {+ let details = LogFields.joined(+ "Operation=SecCodeCopySelf",+ "Status=\(status)"+ )throw CodexBarHelperError.codeSigningValidationFailed(- "读取运行签名失败: Operation=SecCodeCopySelf; Status=\(status)"+ "读取运行签名失败: \(details)")}var staticCode: SecStaticCode?status = SecCodeCopyStaticCode(runningCode, SecCSFlags(), &staticCode)guard status == errSecSuccess, let staticCode else {+ let details = LogFields.joined(+ "Operation=SecCodeCopyStaticCode",+ "Status=\(status)"+ )throw CodexBarHelperError.codeSigningValidationFailed(- "读取静态签名失败: Operation=SecCodeCopyStaticCode; Status=\(status)"+ "读取静态签名失败: \(details)")}@@ -542,8 +1120,12 @@ private final class CodexBarHelperRuntime: NSObject, NSXPCListenerDelegate, Code&signingInformation)guard status == errSecSuccess, let signingInformation else {+ let details = LogFields.joined(+ "Operation=SecCodeCopySigningInformation",+ "Status=\(status)"+ )throw CodexBarHelperError.codeSigningValidationFailed(- "读取签名信息失败: Operation=SecCodeCopySigningInformation; Status=\(status)"+ "读取签名信息失败: \(details)")}@@ -557,8 +1139,12 @@ private final class CodexBarHelperRuntime: NSObject, NSXPCListenerDelegate, Codelet helperSuffix = CodexBarHelperIPC.helperBundleIdentifierSuffixguard helperIdentifier.hasSuffix(helperSuffix) else {+ let details = LogFields.joined(+ "actual=\(helperIdentifier)",+ "expected=*\(helperSuffix)"+ )throw CodexBarHelperError.codeSigningValidationFailed(- "Helper 标识符错误: actual=\(helperIdentifier); expected=*\(helperSuffix)"+ "Helper 标识符错误: \(details)")}@@ -590,16 +1176,19 @@ private final class CodexBarHelperRuntime: NSObject, NSXPCListenerDelegate, Code}private enum CodexBarHelperError: LocalizedError {- case insecureSentinelDirectory(String)- case invalidSentinel(String)+ case insecureOwnershipDirectory(String)+ case invalidOwnershipRecord(String)+ case ownershipWriteFailed(operation: String, code: Int32)case codeSigningValidationFailed(String)var errorDescription: String? {switch self {- case let .insecureSentinelDirectory(detail):+ case let .insecureOwnershipDirectory(detail):"睡眠设置目录无效: \(detail)"- case let .invalidSentinel(detail):- "睡眠设置记录无效: \(detail)"+ case let .invalidOwnershipRecord(detail):+ "睡眠所有权记录无效: \(detail)"+ case let .ownershipWriteFailed(operation, code):+ "睡眠所有权记录写入失败: operation=\(operation); errno=\(code)"case let .codeSigningValidationFailed(reason):"签名校验失败: \(reason)"}diff --git a/README.md b/README.mdindex 1bcd90f..168f79a 100644--- a/README.md+++ b/README.md@@ -185,7 +185,9 @@ App 使用 `--hook-event` 参数启动时不初始化任何 UI, 只从 stdin 读**root helper 权限**-`CodexBarHelper` 是随 App 嵌入的 LaunchDaemon, 只暴露一个 XPC 方法, 只执行 `pmset -a disablesleep`+`CodexBarHelper` 是随 App 嵌入的 LaunchDaemon, 只暴露防睡眠租约与状态查询 XPC, 只执行 `pmset -a disablesleep`++helper 只在 CodexBar 自己将 `SleepDisabled` 从 0 改为 1 时取得所有权, 取得所有权后任务结束始终恢复为 0; 任务开始时已经为 1 则视为其他来源, 不修改它, 该值在任务期间恢复为 0 时再由 CodexBar 接管签名强制校验: helper 启动时读取自身签名拼出 requirement 交给 XPC listener, 修改签名或 bundle ID 都会导致连接被拒diff --git a/Shared/CodexBarHelperXPC.swift b/Shared/CodexBarHelperXPC.swiftindex 8058c7f..015bb46 100644--- a/Shared/CodexBarHelperXPC.swift+++ b/Shared/CodexBarHelperXPC.swift@@ -7,7 +7,10 @@ nonisolated enum CodexBarHelperIPC {: bundleIdentifier + helperBundleIdentifierSuffixstatic let daemonPlistName = machServiceName + ".plist"static let watchdogGraceSeconds: TimeInterval = 15- static let sentinelCheckIntervalSeconds: TimeInterval = 60+ static let externalCheckIntervalSeconds: TimeInterval = 5+ static let ownedCheckIntervalSeconds: TimeInterval = 5+ static let recoveryCheckIntervalSeconds: TimeInterval = 60+ static let checkLeewaySeconds: TimeInterval = 1/// App 侧等回复的上限, 与 watchdog 宽限是一对: 必须更小, 这样 App 先放手 helper 再自行兜底/// helper 冷启动加一次 pmset 通常一秒内完成, 留这么宽只为排除偶发的调度抖动static let requestTimeoutSeconds: TimeInterval = 10@@ -20,13 +23,35 @@ nonisolated enum CodexBarHelperIPC {}()}+nonisolated enum CodexBarSleepPreventionSource: Int, Sendable {+ case none+ case external+ case codexBar+}++nonisolated enum CodexBarSleepOwnershipState: Int, Sendable {+ case idle+ case owned+ case restoring+}+@objc nonisolated protocol CodexBarHelperProtocol: AnyObject {- /// reply 的两个参数是 pmset 退出码, 与恢复写回的 SleepDisabled 值- /// 写回的是接管前的原值, 所以第二个参数不等于请求值: 系统原本就禁用睡眠时恢复后仍是禁用- /// 但 helper 本轮没接管过或 pmset 操作失败时它只是占位的 true, 并非实测状态- /// 调用方要先确认退出码为 0, 且自己的接管过程没有被连接中断打断, 才能把它当成实测值- func setSleepDisabled(- _ disabled: Bool,- reply: @escaping @Sendable (Int32, Bool) -> Void+ /// reply 依次返回 pmset 退出码, 本轮防睡眠来源与操作后实测的 SleepDisabled+ func setSleepPreventionRequested(+ _ requested: Bool,+ clientSessionID: String,+ generation: UInt64,+ reply: @escaping @Sendable (Int32, Int, Bool) -> Void+ )++ /// reply 依次返回状态码, 所有权状态, 活跃客户端数与最近一次实测的 SleepDisabled+ func getSleepPreventionStatus(+ reply: @escaping @Sendable (Int32, Int, Int, Bool) -> Void+ )++ /// helper 更新完成后对同一指纹只执行一次 SleepDisabled 0+ func resetSleepAfterUpdate(+ _ updateIdentifier: String,+ reply: @escaping @Sendable (Int32) -> Void)}