Skip to content

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

fix: 统一 Helper 功能开启确认流程

Bob2aa413d2e4a7
diff --git a/AGENTS.md b/AGENTS.md
index 2b8493d..e892aa7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -55,6 +55,8 @@ CodexBar 是面向 macOS 15+ 的 `LSUIElement` 菜单栏应用,使用 Swift 6,
自动重置默认关闭,提前量可选 15 分钟、30 分钟、1 小时、2 小时、4 小时或 6 小时,默认 30 分钟。状态机只处理新鲜响应明确列出的 `available + codexRateLimits + expiresAt` 凭证,每轮连续重试最多 5 分钟。CodexBarHelper 只接收有限时间戳,使用固定 owner 和固定 `wake` 类型维护一个系统事件;目标变化、功能关闭、App 退出、对应 XPC 连接断开或 helper 启动时必须收敛并清理该事件。修改 owner 或事件类型属于清理兼容性问题。
+自动重置和防睡眠从关闭切换为开启时必须先显示确认框。确认文案按 `HelperStatus` 展示:`.notRegistered` 和 `.notFound` 使用 `需要安装并授权 CodexBar Helper 后台运行`,`.requiresApproval` 使用 `已安装 CodexBar Helper 但需要授权允许后台运行`,`.enabled` 只显示对应功能说明。确认后写入用户意图并触发 helper 注册,Helper 授权系统设置仅由设置行的 `打开系统设置` 按钮显式打开。两个开关关闭时不显示状态说明。自动重置子面板入口仅在开关开启且 helper 状态为 `.enabled` 时显示,条件失效时关闭已展开面板。
+
缺少 session ID 的 Hook 事件使用匿名 project key。匿名任务保留在实时快照和 UI 中,活动卡片与任务中心统一显示橙色 `person.crop.circle.dashed` 图标,`help` 为 `匿名任务不参与防睡眠`。匿名任务不发布任务通知或触觉反馈,不参与防睡眠和异常会话保护,不生成保护状态持久化标识。活动卡片的 `+N` 只显示其他活跃任务总数。
`CodexActivityMonitor` 的异常会话保护跟随防睡眠主开关,只判定非匿名运行中任务,等待批准任务不参与判定。静默阈值可选 30 分钟, 1, 2 或 4 小时,默认 1 小时。Hook bootstrap、系统睡眠、唤醒恢复或 Hook 数据源不可用期间必须暂停判定,数据恢复后统一无通知对账。
diff --git a/CLAUDE.md b/CLAUDE.md
index 5bef465..cdf8dea 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -183,6 +183,8 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev
- `hasRunningTasks` 与 `isRefreshingHelper` 都不带 `@Published` 标注,它们变得比结论频繁,各自发信号会把整个设置页拖着一起重算
- helper 只做固定的系统电源操作;不要给 root helper 增加网络、任意命令执行或其他文件访问能力
- helper 注册需求由防睡眠主开关与自动重置请求共同决定;自动重置开启时即使防睡眠关闭也要完成 `SMAppService` 注册和系统批准,设置行复用注册错误并单独展示唤醒计划同步错误
+- 自动重置与防睡眠从关闭切换为开启时统一通过 `HelperFeatureConfirmation` 显示确认;`.notRegistered` 与 `.notFound` 提示需要安装并授权后台运行,`.requiresApproval` 提示已安装但仍需授权,`.enabled` 只显示功能说明
+- `ensureHelperRegistration()` 只负责注册与刷新 helper;Helper 授权系统设置仅由设置行的 `打开系统设置` 按钮调用 `openSystemSettings()` 打开,两个功能的开启动作不直接切换到系统设置
- `AutoResetWakeScheduler` 与防睡眠租约使用独立 XPC 连接,只同步下一次唤醒时间;距现在不超过 5 秒的时间不交给 helper,由 App 内定时任务直接进入到点执行路径
- helper 把自动重置事件 owner 固定为 `CodexBarHelperIPC.machServiceName + ".auto-reset"`,事件类型固定为 `kIOPMAutoWake`;替换时先取消这个 owner 的全部旧事件,设置后回读必须恰好得到一个 1 秒容差内的目标事件,取消后回读必须为空;修改 owner 或类型属于清理兼容性问题
- 唤醒连接关闭时 helper 立即取消该连接拥有的事件,取消失败后清除内存所有者并每 5 秒继续收敛;helper 启动时在开放 listener 前按立即、250 毫秒、1 秒清理遗留事件,`SIGTERM` 与 `SIGINT` 退出前也执行取消
@@ -311,7 +313,8 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev
- 置灰也会改高度:带音效的行置灰时音效子行跟着收起,所以每个置灰依赖都要有一个对应的订阅源
- 增删行或改行的显示条件时要同步补上对应的订阅源,漏一项会让面板裁掉底部或留下空白
- resize 的竖向夹紧走 `SidePanelSupport.clampedVertically`,与初次展开的 `position` 同一条规则,否则放不下时两边会把面板推向相反的边
-- 子面板入口只在开关开着且依赖就绪时出现,通知看 `NotificationSettings.canShowOptions`,自动重置看 `AutoResetSettings.isEnabled`,防睡眠看 `KeepAliveController.canShowOptions`;这些值只控制入口显隐,不回写用户保存的开关
+- 子面板入口只在开关开着且依赖就绪时出现,通知看 `NotificationSettings.canShowOptions`,自动重置要求 `AutoResetSettings.isEnabled` 且 `KeepAliveController.helperStatus == .enabled`,防睡眠看 `KeepAliveController.canShowOptions`;这些值只控制入口显隐,不回写用户保存的开关
+- 自动重置或防睡眠的子面板入口条件失效时,`AppSettingsView` 会发送对应的 `close` 动作收起已展开面板;关闭开关时对应设置行不显示状态说明
- 三个设置子面板都只由滑杆按钮展开,动作只有 `toggle` 与 `close` 两种,开启主开关不自动弹出
- 侧边面板公共能力集中在 `Controllers/SidePanelSupport.swift` 里,含 `SidePanelDrawerPresenter`、`SidePanelContentHost`、`SidePanelDrawerAnimator`、panel 工厂和定位夹紧;挂在主面板上的那三个面板优先复用 `SidePanelDrawerPresenter` 这一层,不要另起一套
- 设置窗口的子面板直接复用 `Controllers/SettingsOptionsPanelController.swift`,它在 presenter 之上补齐了装配、两套关闭观察者、顶边对齐定位和高度重算;新增设置子面板只要给它内容工厂与内容变化来源,不要再写一层壳
@@ -337,7 +340,7 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev
- `isVerified` 乐观默认为 `true` 且只由明确结论写入两个方向:校验只在设置窗口打开与 App 激活时跑,而 RPC 失败属于“验不了”不是“确认不通”,那时置灰会把好用的功能关掉
- 全局禁用要排在 `hooks/list` 之前判:它一关列表里必然找不到我们的 handler,那时报“已不完整”会把用户引去翻本来就完好的 `hooks.json`
- `refresh()` 只判断是否存在任一当前 CodexBar handler,`hooks/list` 校验才要求所有事件完整;新增事件后旧配置不会自动补齐,当前恢复方式是让用户关闭再开启 Hook
-- 校验不通过时防睡眠那一行的说明写“CodexBar Hook 未生效”而不是“需要启用 CodexBar Hook”,后者会让用户去开一个已经开着的开关;具体病因由 Hook 那一行自己的说明给出
+- 防睡眠开关关闭时说明行收起;开关开启且 Hook 校验不通过时显示“CodexBar Hook 未生效”,具体病因由 Hook 设置行说明
## 隐私与数据边界
diff --git a/CodexBar/Resources/Localizable.xcstrings b/CodexBar/Resources/Localizable.xcstrings
index 1b5c9b7..7d08aa3 100644
--- a/CodexBar/Resources/Localizable.xcstrings
+++ b/CodexBar/Resources/Localizable.xcstrings
@@ -273,18 +273,98 @@
}
}
},
- "APP 快捷键" : {
+ "1 小时" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "App Shortcut"
+ "value" : "1 Hour"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "APP 快捷键"
+ "value" : "1 小时"
+ }
+ }
+ }
+ },
+ "2 小时" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "2 Hours"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "2 小时"
+ }
+ }
+ }
+ },
+ "4 小时" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "4 Hours"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "4 小时"
+ }
+ }
+ }
+ },
+ "6 小时" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "6 Hours"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "6 小时"
+ }
+ }
+ }
+ },
+ "15 分钟" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "15 Minutes"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "15 分钟"
+ }
+ }
+ }
+ },
+ "30 分钟" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "30 Minutes"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "30 分钟"
}
}
}
@@ -321,6 +401,22 @@
}
}
},
+ "APP 快捷键" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "App Shortcut"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "APP 快捷键"
+ }
+ }
+ }
+ },
"app.command.settings" : {
"extractionState" : "manual",
"localizations" : {
@@ -946,50 +1042,50 @@
}
}
},
- "GitHub 项目" : {
+ "CodexBar 设置" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "GitHub Project"
+ "value" : "CodexBar Settings"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "GitHub 项目"
+ "value" : "CodexBar 设置"
}
}
}
},
- "CodexBar 设置" : {
+ "CodexBarHelper 尚未注册" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "CodexBar Settings"
+ "value" : "CodexBarHelper is not registered"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "CodexBar 设置"
+ "value" : "CodexBarHelper 尚未注册"
}
}
}
},
- "CodexBarHelper 尚未注册" : {
+ "GitHub 项目" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "CodexBarHelper is not registered"
+ "value" : "GitHub Project"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "CodexBarHelper 尚未注册"
+ "value" : "GitHub 项目"
}
}
}
@@ -1074,6 +1170,22 @@
}
}
},
+ "keep-alive.error.auto-reset-wake-schedule-failed" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Could not schedule a wake event for Automatic Reset"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "设置自动重置唤醒计划失败"
+ }
+ }
+ }
+ },
"keep-alive.error.connection-failed" : {
"localizations" : {
"en" : {
@@ -1202,22 +1314,6 @@
}
}
},
- "keep-alive.error.auto-reset-wake-schedule-failed" : {
- "localizations" : {
- "en" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "Could not schedule a wake event for Automatic Reset"
- }
- },
- "zh-Hans" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "设置自动重置唤醒计划失败"
- }
- }
- }
- },
"keep-alive.error.restore-idle-sleep-failed" : {
"localizations" : {
"en" : {
@@ -1394,242 +1490,242 @@
}
}
},
- "notification.credit-expiry.body" : {
+ "notification.auto-reset-failed.body.authentication" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "Reset credits expiring on %2$@: %1$lld"
+ "value" : "Codex sign-in has expired"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "有 %1$lld 个重置次数将于 %2$@ 过期"
+ "value" : "Codex 登录状态已失效"
}
}
}
},
- "notification.credit-expiry.title" : {
+ "notification.auto-reset-failed.body.expired" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "Reset Credits Expiring Soon"
+ "value" : "Expired before Automatic Reset could complete"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "重置即将过期"
+ "value" : "重置已过期, 自动重置未完成"
}
}
}
},
- "notification.keep-alive-ended.duration-limit" : {
+ "notification.auto-reset-failed.body.permanent" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "Keep-awake stopped after %@"
+ "value" : "The request could not be completed"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "已达防睡眠上限 %@, 已停止防睡眠"
+ "value" : "请求无法完成"
}
}
}
},
- "notification.keep-alive-ended.low-battery" : {
+ "notification.auto-reset-failed.title" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "Battery at %@; keep-awake stopped"
+ "value" : "Automatic Reset Failed"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "电量剩余 %@, 已停止防睡眠"
+ "value" : "自动重置失败"
}
}
}
},
- "notification.keep-alive-ended.title" : {
+ "notification.auto-reset.body.count" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "System Sleep Restored"
+ "value" : "Reset credits remaining: %lld"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "已恢复系统睡眠"
+ "value" : "剩余重置次数: %lld"
}
}
}
},
- "notification.low-quota.body" : {
+ "notification.auto-reset.title" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "%1$@ %2$@: less than %3$@ remaining"
+ "value" : "Automatic Reset"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "%1$@ %2$@ 剩余额度已低于 %3$@"
+ "value" : "自动重置"
}
}
}
},
- "notification.low-quota.title" : {
+ "notification.credit-expiry.body" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "Codex Quota Is Low"
+ "value" : "Reset credits expiring on %2$@: %1$lld"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "Codex 额度不足"
+ "value" : "有 %1$lld 个重置次数将于 %2$@ 过期"
}
}
}
},
- "notification.quota-reset.body" : {
+ "notification.credit-expiry.title" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "%1$@ %2$@"
+ "value" : "Reset Credits Expiring Soon"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "%1$@ %2$@"
+ "value" : "重置即将过期"
}
}
}
},
- "notification.quota-reset.title" : {
+ "notification.keep-alive-ended.duration-limit" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "Quota Reset"
+ "value" : "Keep-awake stopped after %@"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "额度已重置"
+ "value" : "已达防睡眠上限 %@, 已停止防睡眠"
}
}
}
},
- "notification.auto-reset-failed.body.authentication" : {
+ "notification.keep-alive-ended.low-battery" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "Codex sign-in has expired"
+ "value" : "Battery at %@; keep-awake stopped"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "Codex 登录状态已失效"
+ "value" : "电量剩余 %@, 已停止防睡眠"
}
}
}
},
- "notification.auto-reset-failed.body.expired" : {
+ "notification.keep-alive-ended.title" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "Expired before Automatic Reset could complete"
+ "value" : "System Sleep Restored"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "重置已过期, 自动重置未完成"
+ "value" : "已恢复系统睡眠"
}
}
}
},
- "notification.auto-reset-failed.body.permanent" : {
+ "notification.low-quota.body" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "The request could not be completed"
+ "value" : "%1$@ %2$@: less than %3$@ remaining"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "请求无法完成"
+ "value" : "%1$@ %2$@ 剩余额度已低于 %3$@"
}
}
}
},
- "notification.auto-reset-failed.title" : {
+ "notification.low-quota.title" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "Automatic Reset Failed"
+ "value" : "Codex Quota Is Low"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "自动重置失败"
+ "value" : "Codex 额度不足"
}
}
}
},
- "notification.auto-reset.body.count" : {
+ "notification.quota-reset.body" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "Reset credits remaining: %lld"
+ "value" : "%1$@ %2$@"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "剩余重置次数: %lld"
+ "value" : "%1$@ %2$@"
}
}
}
},
- "notification.auto-reset.title" : {
+ "notification.quota-reset.title" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "Automatic Reset"
+ "value" : "Quota Reset"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "自动重置"
+ "value" : "额度已重置"
}
}
}
@@ -2130,50 +2226,50 @@
}
}
},
- "主面板任务中心" : {
+ "临期时间" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "Show Task Center in Menu"
+ "value" : "Time Before Expiration"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "主面板任务中心"
+ "value" : "临期时间"
}
}
}
},
- "仅在使用电池供电时生效, 充电时自动恢复" : {
+ "主面板任务中心" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "Battery only; resumes when charging"
+ "value" : "Show Task Center in Menu"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "仅在使用电池供电时生效, 充电时自动恢复"
+ "value" : "主面板任务中心"
}
}
}
},
- "匿名任务不参与防睡眠" : {
+ "仅在使用电池供电时生效, 充电时自动恢复" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "Anonymous tasks do not prevent sleep"
+ "value" : "Battery only; resumes when charging"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "匿名任务不参与防睡眠"
+ "value" : "仅在使用电池供电时生效, 充电时自动恢复"
}
}
}
@@ -2530,38 +2626,6 @@
}
}
},
- "异常会话保护" : {
- "localizations" : {
- "en" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "Stalled Task Protection"
- }
- },
- "zh-Hans" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "异常会话保护"
- }
- }
- }
- },
- "长时间没有进展时隐藏任务并停止参与防睡眠" : {
- "localizations" : {
- "en" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "Hide inactive tasks and exclude them from keep-awake"
- }
- },
- "zh-Hans" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "长时间没有进展时隐藏任务并停止参与防睡眠"
- }
- }
- }
- },
"最长任务" : {
"localizations" : {
"en" : {
@@ -2658,6 +2722,22 @@
}
}
},
+ "匿名任务不参与防睡眠" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Anonymous tasks do not prevent sleep"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "匿名任务不参与防睡眠"
+ }
+ }
+ }
+ },
"单日峰值" : {
"localizations" : {
"en" : {
@@ -2994,6 +3074,22 @@
}
}
},
+ "已安装 CodexBar Helper 但需要授权允许后台运行" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "CodexBar Helper is installed but still needs authorization to run in the background"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "已安装 CodexBar Helper 但需要授权允许后台运行"
+ }
+ }
+ }
+ },
"已更新至 %@" : {
"localizations" : {
"en" : {
@@ -3106,6 +3202,86 @@
}
}
},
+ "开启" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Enable"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "开启"
+ }
+ }
+ }
+ },
+ "开启后, CodexBar 在手动重置临近过期时, 按设置的临期时间提前自动使用重置; 并可能短暂唤醒 Mac" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "When enabled, CodexBar automatically uses a manual reset credit at the configured time before it expires and may briefly wake your Mac."
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "开启后, CodexBar 在手动重置临近过期时, 按设置的临期时间提前自动使用重置; 并可能短暂唤醒 Mac"
+ }
+ }
+ }
+ },
+ "开启后, CodexBar 会在 Codex 任务运行时防止系统睡眠, 任务结束后自动恢复" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "When enabled, CodexBar prevents system sleep while Codex tasks are running and restores normal sleep afterward."
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "开启后, CodexBar 会在 Codex 任务运行时防止系统睡眠, 任务结束后自动恢复"
+ }
+ }
+ }
+ },
+ "开启自动重置?" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Enable Automatic Reset?"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "开启自动重置?"
+ }
+ }
+ }
+ },
+ "开启防止系统睡眠?" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Enable System Sleep Prevention?"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "开启防止系统睡眠?"
+ }
+ }
+ }
+ },
"开机自动启动" : {
"localizations" : {
"en" : {
@@ -3122,50 +3298,50 @@
}
}
},
- "当前使用" : {
+ "异常会话保护" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "In Use"
+ "value" : "Stalled Task Protection"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "当前使用"
+ "value" : "异常会话保护"
}
}
}
},
- "当前连胜" : {
+ "当前使用" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "Current Streak"
+ "value" : "In Use"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "当前连胜"
+ "value" : "当前使用"
}
}
}
},
- "当有 Codex 任务运行时防止系统睡眠, 任务结束后自动恢复" : {
+ "当前连胜" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "Prevent sleep while Codex tasks run; restore normal sleep afterward"
+ "value" : "Current Streak"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "当有 Codex 任务运行时防止系统睡眠, 任务结束后自动恢复"
+ "value" : "当前连胜"
}
}
}
@@ -3858,6 +4034,38 @@
}
}
},
+ "自动重置" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Automatic Reset"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "自动重置"
+ }
+ }
+ }
+ },
+ "自动重置通知" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Automatic Reset Notifications"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "自动重置通知"
+ }
+ }
+ }
+ },
"菜单栏额度指示" : {
"localizations" : {
"en" : {
@@ -4386,6 +4594,22 @@
}
}
},
+ "长时间没有进展时隐藏任务并停止参与防睡眠" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Hide inactive tasks and exclude them from keep-awake"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "长时间没有进展时隐藏任务并停止参与防睡眠"
+ }
+ }
+ }
+ },
"防止系统睡眠" : {
"localizations" : {
"en" : {
@@ -4450,18 +4674,18 @@
}
}
},
- "需要启用 CodexBar Hook" : {
+ "需要安装并授权 CodexBar Helper 后台运行" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "CodexBar Hook must be enabled"
+ "value" : "CodexBar Helper must be installed and authorized to run in the background"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "需要启用 CodexBar Hook"
+ "value" : "需要安装并授权 CodexBar Helper 后台运行"
}
}
}
@@ -4578,214 +4802,6 @@
}
}
},
- "1 小时" : {
- "localizations" : {
- "en" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "1 Hour"
- }
- },
- "zh-Hans" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "1 小时"
- }
- }
- }
- },
- "12 小时" : {
- "localizations" : {
- "en" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "12 Hours"
- }
- },
- "zh-Hans" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "12 小时"
- }
- }
- }
- },
- "15 分钟" : {
- "localizations" : {
- "en" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "15 Minutes"
- }
- },
- "zh-Hans" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "15 分钟"
- }
- }
- }
- },
- "2 小时" : {
- "localizations" : {
- "en" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "2 Hours"
- }
- },
- "zh-Hans" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "2 小时"
- }
- }
- }
- },
- "30 分钟" : {
- "localizations" : {
- "en" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "30 Minutes"
- }
- },
- "zh-Hans" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "30 分钟"
- }
- }
- }
- },
- "4 小时" : {
- "localizations" : {
- "en" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "4 Hours"
- }
- },
- "zh-Hans" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "4 小时"
- }
- }
- }
- },
- "6 小时" : {
- "localizations" : {
- "en" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "6 Hours"
- }
- },
- "zh-Hans" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "6 小时"
- }
- }
- }
- },
- "开启" : {
- "localizations" : {
- "en" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "Enable"
- }
- },
- "zh-Hans" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "开启"
- }
- }
- }
- },
- "开启自动重置?" : {
- "localizations" : {
- "en" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "Enable Automatic Reset?"
- }
- },
- "zh-Hans" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "开启自动重置?"
- }
- }
- }
- },
- "开启后, CodexBar 在手动重置临近过期时, 按设置的临期时间提前自动使用重置; 并可能短暂唤醒 Mac" : {
- "localizations" : {
- "en" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "When enabled, CodexBar automatically uses a manual reset credit at the configured time before it expires and may briefly wake your Mac."
- }
- },
- "zh-Hans" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "开启后, CodexBar 在手动重置临近过期时, 按设置的临期时间提前自动使用重置; 并可能短暂唤醒 Mac"
- }
- }
- }
- },
- "临期时间" : {
- "localizations" : {
- "en" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "Time Before Expiration"
- }
- },
- "zh-Hans" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "临期时间"
- }
- }
- }
- },
- "自动重置" : {
- "localizations" : {
- "en" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "Automatic Reset"
- }
- },
- "zh-Hans" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "自动重置"
- }
- }
- }
- },
- "自动重置通知" : {
- "localizations" : {
- "en" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "Automatic Reset Notifications"
- }
- },
- "zh-Hans" : {
- "stringUnit" : {
- "state" : "translated",
- "value" : "自动重置通知"
- }
- }
- }
- },
"默认快捷键 %@ 已被占用" : {
"localizations" : {
"en" : {
diff --git a/CodexBar/Services/CodexStatus/AutoResetController.swift b/CodexBar/Services/CodexStatus/AutoResetController.swift
index df00fa6..b4f6075 100644
--- a/CodexBar/Services/CodexStatus/AutoResetController.swift
+++ b/CodexBar/Services/CodexStatus/AutoResetController.swift
@@ -94,10 +94,7 @@ final class AutoResetController {
return
}
isStarted = true
- keepAliveController.setAutoResetRequested(
- settings.isEnabled,
- opensSystemSettings: false
- )
+ keepAliveController.setAutoResetRequested(settings.isEnabled)
statusViewModel.$snapshot
.sink { [weak self] snapshot in
@@ -137,20 +134,14 @@ final class AutoResetController {
return
}
isStarted = false
- keepAliveController.setAutoResetRequested(
- false,
- opensSystemSettings: false
- )
+ keepAliveController.setAutoResetRequested(false)
cancellables.removeAll()
cancelWork()
target = nil
}
private func handleEnabledChange(_ enabled: Bool) {
- keepAliveController.setAutoResetRequested(
- enabled,
- opensSystemSettings: enabled
- )
+ keepAliveController.setAutoResetRequested(enabled)
guard enabled else {
cancelWork()
target = nil
diff --git a/CodexBar/Services/KeepAlive/KeepAliveController.swift b/CodexBar/Services/KeepAlive/KeepAliveController.swift
index af26c32..5c7e38a 100644
--- a/CodexBar/Services/KeepAlive/KeepAliveController.swift
+++ b/CodexBar/Services/KeepAlive/KeepAliveController.swift
@@ -274,7 +274,7 @@ final class KeepAliveController: ObservableObject {
if isEnabled
|| isAutoResetRequested
|| helperStatus.isRegisteredOrAwaitingApproval {
- ensureHelperRegistration(opensSystemSettings: false)
+ ensureHelperRegistration()
}
reconcileSleepState(trigger: .statusRefresh)
reconcileAutoResetWakeSchedule()
@@ -299,7 +299,7 @@ final class KeepAliveController: ObservableObject {
operationErrorMessage = nil
if enabled {
- ensureHelperRegistration(opensSystemSettings: true)
+ ensureHelperRegistration()
} else {
durationLimiter.reset()
}
@@ -529,7 +529,7 @@ final class KeepAliveController: ObservableObject {
SMAppService.openSystemSettingsLoginItems()
}
- private func ensureHelperRegistration(opensSystemSettings: Bool) {
+ private func ensureHelperRegistration() {
guard helperRegistrationTask == nil else {
return
}
@@ -540,14 +540,12 @@ final class KeepAliveController: ObservableObject {
switch helperStatus {
case .enabled, .requiresApproval:
if KeepAliveHelperConfiguration.registrationNeedsRefresh(defaults: defaults) {
- refreshRegisteredHelper(opensSystemSettings: opensSystemSettings)
+ refreshRegisteredHelper()
} else if helperStatus == .enabled,
let updateIdentifier = KeepAliveHelperConfiguration.pendingUpdateIdentifier(
defaults: defaults
) {
completePendingHelperUpdate(updateIdentifier)
- } else if helperStatus == .requiresApproval, opensSystemSettings {
- openSystemSettings()
} else {
reconcileAutoResetWakeSchedule()
}
@@ -580,13 +578,10 @@ final class KeepAliveController: ObservableObject {
) {
completePendingHelperUpdate(updateIdentifier)
}
- if helperStatus == .requiresApproval, opensSystemSettings {
- openSystemSettings()
- }
reconcileAutoResetWakeSchedule()
}
- private func refreshRegisteredHelper(opensSystemSettings: Bool) {
+ private func refreshRegisteredHelper() {
let requiresSleepReset = helperStatus == .enabled
guard helperRegistrationTask == nil,
KeepAliveHelperConfiguration.assetsArePresent else {
@@ -655,9 +650,6 @@ final class KeepAliveController: ObservableObject {
assign(!helperWasUpdated && helperStatus == .enabled, to: \.isRefreshingHelper)
helperRegistrationTask = nil
- if helperStatus == .requiresApproval, opensSystemSettings {
- openSystemSettings()
- }
reconcileSleepState(trigger: .helperRegistered, force: true)
reconcileAutoResetWakeSchedule()
}
@@ -1526,10 +1518,7 @@ extension KeepAliveController {
}
}
- func setAutoResetRequested(
- _ requested: Bool,
- opensSystemSettings: Bool
- ) {
+ func setAutoResetRequested(_ requested: Bool) {
guard requested != isAutoResetRequested else {
if requested {
reconcileAutoResetWakeSchedule()
@@ -1540,7 +1529,7 @@ extension KeepAliveController {
isAutoResetRequested = requested
autoResetWakeScheduler.setRequested(requested)
if requested, isStarted {
- ensureHelperRegistration(opensSystemSettings: opensSystemSettings)
+ ensureHelperRegistration()
}
reconcileAutoResetWakeSchedule()
}
diff --git a/CodexBar/Views/Settings/AppSettingsView.swift b/CodexBar/Views/Settings/AppSettingsView.swift
index eadb7dd..9dc3d81 100644
--- a/CodexBar/Views/Settings/AppSettingsView.swift
+++ b/CodexBar/Views/Settings/AppSettingsView.swift
@@ -29,7 +29,7 @@ struct AppSettingsView: View {
@State private var isShowingRebuildConfirmation = false
@State private var isRebuildingWorkflowData = false
@State private var rebuildStatus: RebuildStatus?
- @State private var isShowingAutoResetConfirmation = false
+ @State private var helperFeatureConfirmation: HelperFeatureConfirmation?
var body: some View {
VStack(spacing: 0) {
@@ -92,7 +92,7 @@ struct AppSettingsView: View {
.onReceive(NotificationCenter.default.publisher(for: .settingsWindowDidOpen)) { _ in
selectedRebuildRange = nil
isShowingRebuildConfirmation = false
- isShowingAutoResetConfirmation = false
+ helperFeatureConfirmation = nil
clearRebuildStatus()
}
.onChange(of: selectedTab) { _, _ in
@@ -130,16 +130,13 @@ struct AppSettingsView: View {
} message: {
Text("将从本机原始 Hook 事件重新统计 \(selectedRebuildRange?.displayText ?? "")\n并在下次同步时替换当前设备对应日期的云端数据")
}
- .alert(
- "开启自动重置?",
- isPresented: $isShowingAutoResetConfirmation
- ) {
- Button("取消", role: .cancel) {}
- Button("开启", role: .destructive) {
- autoResetSettings.setEnabled(true)
+ .alert(item: $helperFeatureConfirmation) { feature in
+ feature.alert(helperStatus: keepAliveController.helperStatus) {
+ switch feature {
+ case .autoReset: autoResetSettings.setEnabled(true)
+ case .keepAlive: keepAliveController.setEnabled(true)
+ }
}
- } message: {
- Text("开启后, CodexBar 在手动重置临近过期时, 按设置的临期时间提前自动使用重置; 并可能短暂唤醒 Mac")
}
}
}
@@ -424,6 +421,7 @@ private extension AppSettingsView {
var autoResetRow: some View {
let isEnabled = autoResetSettings.isEnabled
+ let canShowOptions = isEnabled && keepAliveController.helperStatus == .enabled
let caption = autoResetCaption
return VStack(alignment: .leading, spacing: 4) {
@@ -434,14 +432,14 @@ private extension AppSettingsView {
get: { autoResetSettings.isEnabled },
set: { enabled in
if enabled {
- isShowingAutoResetConfirmation = true
+ helperFeatureConfirmation = .autoReset
} else {
autoResetSettings.setEnabled(enabled)
}
}
)
) {
- optionsButton(isAvailable: isEnabled) {
+ optionsButton(isAvailable: canShowOptions) {
onOptionsAction(
.toggle(
panel: .autoReset,
@@ -458,8 +456,8 @@ private extension AppSettingsView {
}
.animation(Metrics.statusAnimation, value: caption)
.animation(Metrics.statusAnimation, value: isEnabled)
- .onChange(of: isEnabled) { _, isEnabled in
- guard !isEnabled else {
+ .onChange(of: canShowOptions) { _, canShowOptions in
+ guard !canShowOptions else {
return
}
@@ -505,7 +503,13 @@ private extension AppSettingsView {
title: "防止系统睡眠",
isOn: Binding(
get: { keepAliveController.isEnabled },
- set: { keepAliveController.setEnabled($0) }
+ set: { enabled in
+ if enabled {
+ helperFeatureConfirmation = .keepAlive
+ } else {
+ keepAliveController.setEnabled(false)
+ }
+ }
),
isEnabled: codexHookSettings.isOperable && !codexHookSettings.isUpdating
) {
@@ -580,22 +584,15 @@ private extension AppSettingsView {
/// 返回 nil 表示这一行整个收起
/// 正常运行时不必占一行说"一切正常", 是否正在防睡眠由主面板的咖啡杯标记呈现
var keepAliveCaption: SettingsStatusCaption? {
+ guard keepAliveController.isEnabled else {
+ return nil
+ }
if let errorMessage = keepAliveController.errorMessage {
return SettingsStatusCaption(message: errorMessage, isError: true)
}
- guard codexHookSettings.isEnabled else {
- return SettingsStatusCaption(message: String(localized: "需要启用 CodexBar Hook"))
- }
- // 装着但校验不通过时不能说"需要启用", 那句会让用户去开一个已经开着的开关
- // 具体是全局禁用还是不被信任, 由上面 Hook 那一行的说明给出, 这里只说结果
guard codexHookSettings.isVerified else {
return SettingsStatusCaption(message: String(localized: "CodexBar Hook 未生效"))
}
- guard keepAliveController.isEnabled else {
- return SettingsStatusCaption(
- message: String(localized: "当有 Codex 任务运行时防止系统睡眠, 任务结束后自动恢复")
- )
- }
if keepAliveController.isActivelyPreventingSleep,
keepAliveController.sleepPreventionSource == .external {
diff --git a/CodexBar/Views/Settings/HelperFeatureConfirmation.swift b/CodexBar/Views/Settings/HelperFeatureConfirmation.swift
new file mode 100644
index 0000000..700cb2e
--- /dev/null
+++ b/CodexBar/Views/Settings/HelperFeatureConfirmation.swift
@@ -0,0 +1,55 @@
+import SwiftUI
+
+enum HelperFeatureConfirmation: Identifiable {
+ case autoReset
+ case keepAlive
+
+ var id: Self {
+ self
+ }
+
+ func alert(
+ helperStatus: KeepAliveController.HelperStatus,
+ onConfirm: @escaping () -> Void
+ ) -> Alert {
+ Alert(
+ title: title,
+ message: Text(verbatim: message(helperStatus: helperStatus)),
+ primaryButton: .destructive(Text("开启"), action: onConfirm),
+ secondaryButton: .cancel(Text("取消"))
+ )
+ }
+
+ private var title: Text {
+ switch self {
+ case .autoReset:
+ Text("开启自动重置?")
+ case .keepAlive:
+ Text("开启防止系统睡眠?")
+ }
+ }
+
+ private var details: String {
+ switch self {
+ case .autoReset:
+ String(
+ localized: "开启后, CodexBar 在手动重置临近过期时, 按设置的临期时间提前自动使用重置; 并可能短暂唤醒 Mac"
+ )
+ case .keepAlive:
+ String(
+ localized: "开启后, CodexBar 会在 Codex 任务运行时防止系统睡眠, 任务结束后自动恢复"
+ )
+ }
+ }
+
+ private func message(helperStatus: KeepAliveController.HelperStatus) -> String {
+ switch helperStatus {
+ case .notRegistered, .notFound:
+ "\(String(localized: "需要安装并授权 CodexBar Helper 后台运行"))\n\(details)"
+ case .requiresApproval:
+ "\(String(localized: "已安装 CodexBar Helper 但需要授权允许后台运行"))\n\(details)"
+ case .enabled:
+ details
+ }
+ }
+}
diff --git a/Config/Version.xcconfig b/Config/Version.xcconfig
index fa25ef1..158eca1 100644
--- a/Config/Version.xcconfig
+++ b/Config/Version.xcconfig
@@ -1,2 +1,2 @@
-MARKETING_VERSION = 3.6.3
-CURRENT_PROJECT_VERSION = 70
+MARKETING_VERSION = 3.6.4
+CURRENT_PROJECT_VERSION = 71
diff --git a/Docs/DeveloperGuide/development.md b/Docs/DeveloperGuide/development.md
index f039085..af5d052 100644
--- a/Docs/DeveloperGuide/development.md
+++ b/Docs/DeveloperGuide/development.md
@@ -438,6 +438,9 @@ schema 递增的判断标准是语义输出是否会因同一份 raw event 得
- 低电量和最长时长停止
- 外部 `SleepDisabled` 共存
- 正常退出和异常退出恢复
+- 自动重置与防睡眠每次开启时的确认框,以及取消后保持关闭
+- Helper 未注册、等待批准和已批准状态对应的确认文案
+- 自动重置选项入口只在开关开启且 Helper 已批准时显示
- 自动重置开启时的 helper 注册与系统批准
- 自动重置阈值和重试时间只保留最近一个固定 owner 的 `wake` 事件
- 自动重置关闭、目标变化、正常退出、连接中断和 helper 重启时清理唤醒事件
diff --git a/Docs/DeveloperGuide/sleep-prevention.md b/Docs/DeveloperGuide/sleep-prevention.md
index 5514e1c..c37f46f 100644
--- a/Docs/DeveloperGuide/sleep-prevention.md
+++ b/Docs/DeveloperGuide/sleep-prevention.md
@@ -166,6 +166,17 @@ CodexBarHelper 通过 `SMAppService` 注册为 LaunchDaemon。App 和 CodexBarHe
自动重置与防睡眠共用 helper 注册和系统批准状态,但使用独立 XPC 连接。开启自动重置时,即使防睡眠主开关关闭,也会尝试注册 helper;尚未批准时,自动重置设置行会提供相同的状态和“打开系统设置”入口。
+设置页把用户确认、helper 注册和 Helper 授权系统设置跳转分成独立职责:
+
+- `HelperFeatureConfirmation` 为自动重置和防睡眠提供统一确认框,每次从关闭切换为开启时显示
+- `.notRegistered` 与 `.notFound` 在确认框提示安装并授权后台运行,`.requiresApproval` 提示已安装但仍需授权,`.enabled` 只显示功能说明
+- 用户确认后才调用 `AutoResetSettings.setEnabled(true)` 或 `KeepAliveController.setEnabled(true)`,取消时不写入开关状态
+- `ensureHelperRegistration()` 只负责注册、刷新和后续协调,不负责打开 Helper 授权系统设置
+- `AppSettingsView` 只在已开启设置行的 `.requiresApproval` 状态显示 `打开系统设置`,按钮调用 `KeepAliveController.openSystemSettings()`
+- 自动重置选项入口要求开关已开启且 `helperStatus == .enabled`,条件失效时关闭已展开的自动重置面板
+- 防睡眠选项入口读取 `KeepAliveController.canShowOptions`,没有任务、低电量阻断、达到上限或 helper 刷新期间仍允许调整设置
+- 自动重置和防睡眠开关关闭时,设置行不显示状态说明
+
唤醒计划采用系统状态收敛而不是只依赖正常退出清理:
- helper 每次启动都在开放 XPC listener 前清除固定 owner 的遗留事件,App 重连后再按最新目标重新安排
@@ -428,6 +439,10 @@ App 更新可能改变内嵌 CodexBarHelper 的签名或内容。App 会记录 C
- 外部先设置 `disablesleep 1` 时,CodexBar 不声明所有权也不恢复为 `0`
- App 正常退出时恢复 owned 状态
- App 强制退出或 XPC 断开后,watchdog 恢复 owned 状态
+- 自动重置和防睡眠每次开启都显示确认,取消后保持关闭
+- 未注册、等待批准和已批准三种 helper 状态的确认文案与功能说明正确
+- 开启操作只触发 helper 注册,Helper 授权系统设置仅由设置行的 `打开系统设置` 按钮打开
+- 自动重置选项入口只在开关开启且 helper 已批准时显示,条件失效后已展开面板关闭
- 自动重置开启且防睡眠关闭时仍能完成 helper 注册与批准
- 未来阈值和重试只保留一个固定 owner 的 `wake` 事件,替换时不影响其他 owner
- 自动重置关闭、目标变化和正常退出时回读确认计划清零
diff --git a/Docs/DeveloperGuide/ui-and-lifecycle.md b/Docs/DeveloperGuide/ui-and-lifecycle.md
index daa2c6a..cade667 100644
--- a/Docs/DeveloperGuide/ui-and-lifecycle.md
+++ b/Docs/DeveloperGuide/ui-and-lifecycle.md
@@ -216,6 +216,16 @@ hover 类型的热力图面板在打开其他面板前可以渐隐,点击类
通知、自动重置和防睡眠的二级设置面板按需创建。控制器一旦创建就会长期订阅内容高度变化,如果 App 启动时预建所有面板,从未使用的 UI 也会一直参与更新。
+自动重置与防睡眠从关闭切换为开启时,`AppSettingsView` 使用 `HelperFeatureConfirmation` 显示统一确认框。确认框按 `KeepAliveController.HelperStatus` 组合 Helper 提示与对应功能说明,用户确认后才调用设置对象写入开启状态。已开启设置行在 `.requiresApproval` 状态显示 `打开系统设置` 按钮。
+
+二级设置入口使用各自的可用性结论:
+
+- 通知读取 `NotificationSettings.canShowOptions`
+- 自动重置要求 `AutoResetSettings.isEnabled` 且 `KeepAliveController.helperStatus == .enabled`
+- 防睡眠读取 `KeepAliveController.canShowOptions`
+
+入口条件失效时设置页发送对应的 `close` 动作,避免不可用的子面板继续显示。主开关关闭时,自动重置和防睡眠设置行不显示状态说明。
+
### 120 ms 焦点恢复不是业务延迟
菜单关闭时 `AuxiliaryHostingWindow` 暂时把 `allowsKeyFocus` 设为 false。关闭完成后等待约 120 ms 再恢复。
diff --git a/Docs/UserGuide/getting-started.md b/Docs/UserGuide/getting-started.md
index 1107d42..f97be7c 100644
--- a/Docs/UserGuide/getting-started.md
+++ b/Docs/UserGuide/getting-started.md
@@ -63,9 +63,9 @@ CodexBar 每 60 秒自动刷新一次账户、额度和 Token 用量,双击主
| 实时任务和任务中心 | 需要 | Hook 已通过校验 |
| 每日 Hook 统计 | 需要 | 本机存在 Hook 原始事件 |
| 额度类通知 | 不需要 | 系统通知总开关和权限已开启 |
-| 自动重置 | 不需要 | 用户主动开启;系统睡眠期间按计划唤醒需要 CodexBarHelper 获得批准;可选提前 15 分钟至 6 小时,默认提前 30 分钟 |
+| 自动重置 | 不需要 | 每次开启需确认;系统睡眠期间按计划唤醒和显示临期选项需要 CodexBarHelper 获得批准;可选提前 15 分钟至 6 小时,默认提前 30 分钟 |
| 任务类通知 | 需要 | Hook 已通过校验且通知已开启 |
-| 防止系统睡眠 | 需要 | CodexBarHelper 已注册并获得系统批准 |
+| 防止系统睡眠 | 需要 | 每次开启需确认;CodexBarHelper 已注册并获得系统批准 |
| 跨设备同步 | 需要 | iCloud 可用且用户主动开启同步 |
关闭 CodexBar Hook 不影响账户、额度、Token 热力图、更新检查或日志窗口。
diff --git a/Docs/UserGuide/settings.md b/Docs/UserGuide/settings.md
index 56bb93c..102638d 100644
--- a/Docs/UserGuide/settings.md
+++ b/Docs/UserGuide/settings.md
@@ -75,14 +75,33 @@ Hook 关闭时该选项会显示为关闭并置灰,保存的选择不会被覆
完整说明见 [通知与提醒](notifications.md)
+### 自动重置与防睡眠开启确认
+
+`自动重置` 和 `防止系统睡眠` 每次从关闭切换为开启时都会显示确认框。确认框先按 CodexBarHelper 当前状态显示提示,再显示对应功能说明:
+
+| CodexBarHelper 状态 | 确认提示 |
+| --- | --- |
+| 未注册或文件缺失 | `需要安装并授权 CodexBar Helper 后台运行` |
+| 已安装但等待系统批准 | `已安装 CodexBar Helper 但需要授权允许后台运行` |
+| 已安装并获得系统批准 | 只显示对应功能说明 |
+
+对应功能说明为:
+
+| 功能 | 确认标题 | 功能说明 |
+| --- | --- | --- |
+| 自动重置 | `开启自动重置?` | `开启后, CodexBar 在手动重置临近过期时, 按设置的临期时间提前自动使用重置; 并可能短暂唤醒 Mac` |
+| 防止系统睡眠 | `开启防止系统睡眠?` | `开启后, CodexBar 会在 Codex 任务运行时防止系统睡眠, 任务结束后自动恢复` |
+
+选择 `开启` 后保存开关状态并尝试注册 CodexBarHelper;选择 `取消` 时开关保持关闭。这两个功能的 Helper 授权系统设置只通过已开启设置行下方的 `打开系统设置` 按钮打开,该按钮在 CodexBarHelper 等待系统批准时显示。两个开关处于关闭状态时,设置行下方不显示状态说明。
+
### 自动重置
-每次开启都会显示操作确认。开启后点击主开关行右侧的选项按钮,在侧边面板的“临期时间”中选择到期前 `15 分钟`、`30 分钟`、`1 小时`、`2 小时`、`4 小时` 或 `6 小时` 开始尝试,默认是 `30 分钟`。
+自动重置开关已开启且 CodexBarHelper 已安装并获得系统批准时,主开关行右侧显示选项按钮。点击后可在侧边面板的“临期时间”中选择到期前 `15 分钟`、`30 分钟`、`1 小时`、`2 小时`、`4 小时` 或 `6 小时` 开始尝试,默认是 `30 分钟`。Helper 状态不满足条件时入口隐藏,已展开的自动重置面板会关闭。
- 只处理 app-server 最新响应明确列出的可用重置次数
- 每次使用前重新确认账号、凭证状态和过期时间
- 同一时间只处理最早到期的一次
-- 开启功能时会注册现有 CodexBarHelper;即使“防止系统睡眠”关闭,也可能需要在“登录项与扩展”中批准 CodexBar 后台运行
+- 确认开启后会尝试注册 CodexBarHelper;即使“防止系统睡眠”关闭,也可能需要在“登录项与扩展”中批准 CodexBar 后台运行
- 自动重置设置行会显示 CodexBarHelper 待批准、未注册、注册失败或唤醒计划同步失败状态
- 有未来任务时,CodexBarHelper 只为最近一次阈值或重试注册一个系统唤醒事件;任务变化、功能关闭或 App 退出时会取消,异常中断遗留的事件会在 helper 下次启动时清理
- 定时触发后仅在重新读取和使用期间短暂阻止空闲睡眠,不唤醒显示器,也不会开启“防止系统睡眠”
@@ -102,6 +121,8 @@ Hook 关闭时该选项会显示为关闭并置灰,保存的选择不会被覆
### 防止系统睡眠子选项
+防止系统睡眠开关已开启且 CodexBar Hook 可用时,主开关行右侧可显示子选项按钮。没有符合条件的任务、CodexBarHelper 正在刷新、低电量保护生效或达到最长时间上限时,入口仍然保留;存在符合条件的任务但 CodexBarHelper 不可用时,入口会隐藏。
+
| 选项 | 默认值 | 可选值 |
| --- | --- | --- |
| 等待批准时保持 | 关闭 | 开启或关闭 |
diff --git a/Docs/UserGuide/sleep-prevention.md b/Docs/UserGuide/sleep-prevention.md
index 16dc601..9c6c88f 100644
--- a/Docs/UserGuide/sleep-prevention.md
+++ b/Docs/UserGuide/sleep-prevention.md
@@ -101,8 +101,13 @@ CodexBar 会同时阻止显示器睡眠,并定期声明用户活动以压住
防睡眠需要随 App 安装的 CodexBarHelper 修改系统级睡眠状态。自动重置也复用同一个后台服务注册和批准状态,用于设置固定的系统唤醒计划:
-- 首次开启时由 macOS 注册后台服务
-- 系统要求批准后台项目时,设置页会显示 `打开系统设置`
+- 每次从关闭切换为开启时显示 `开启防止系统睡眠?` 确认框
+- CodexBarHelper 未注册或文件缺失时,确认框显示 `需要安装并授权 CodexBar Helper 后台运行`
+- CodexBarHelper 已安装但等待系统批准时,确认框显示 `已安装 CodexBar Helper 但需要授权允许后台运行`
+- CodexBarHelper 已获得系统批准时,确认框只显示 `开启后, CodexBar 会在 Codex 任务运行时防止系统睡眠, 任务结束后自动恢复`
+- 选择 `开启` 后保存主开关并尝试注册后台服务,选择 `取消` 时保持关闭
+- 系统要求批准后台项目时,已开启的设置行会显示 `打开系统设置`;点击该按钮进入 macOS 的“登录项与扩展”
+- 主开关关闭时不显示状态说明;主开关与 Hook 可用时由当前阻断原因决定是否显示防睡眠子选项入口
- CodexBarHelper 缺失或注册失败时不会执行防睡眠
- App 更新导致 CodexBarHelper 变化时会刷新注册并校验睡眠状态
- App 正常退出前会先取消自动重置唤醒计划、释放 CodexBarHelper 租约并恢复由 CodexBar 修改的状态
diff --git a/Docs/UserGuide/troubleshooting.md b/Docs/UserGuide/troubleshooting.md
index c9cf60a..4c500e1 100644
--- a/Docs/UserGuide/troubleshooting.md
+++ b/Docs/UserGuide/troubleshooting.md
@@ -91,7 +91,8 @@ Hook 配置位于 `$CODEX_HOME/hooks.json`,未设置 `CODEX_HOME` 时位于 `~
## CodexBarHelper 无法注册
-- 点击设置页中的 `打开系统设置` 并允许 CodexBar 后台运行
+- 确认 `自动重置` 或 `防止系统睡眠` 已开启;关闭状态不显示 Helper 状态说明
+- Helper 等待系统批准时,点击设置行下方的 `打开系统设置` 并允许 CodexBar 后台运行
- 确认 CodexBar 位于 Applications 中且 App 包完整
- 如果提示服务异常或 CodexBarHelper 文件缺失,重新安装完整 CodexBar App
- 更新后持续失败时退出 CodexBar,重新打开并再次检查授权
@@ -101,7 +102,7 @@ Hook 配置位于 `$CODEX_HOME/hooks.json`,未设置 `CODEX_HOME` 时位于 `~
按以下顺序检查:
1. `自动重置` 是否开启,提前量是否符合预期
-2. 自动重置设置行是否提示 CodexBarHelper 待批准、未注册或唤醒计划失败
+2. 自动重置设置行是否提示 CodexBarHelper 待批准、未注册或唤醒计划失败;临期选项按钮只在 Helper 已获得系统批准时显示
3. 当前 app-server 是否返回了具体的可用重置次数和过期时间
4. 计划时间到达后,网络与 Codex 登录状态是否可用
5. “自动重置通知”是否开启;通知关闭不会阻止自动重置本身执行
diff --git a/appcast.xml b/appcast.xml
index accde21..cb76f91 100644
--- a/appcast.xml
+++ b/appcast.xml
@@ -7,6 +7,15 @@
<link>https://codexbar.zabrian.app/appcast.xml</link>
<description>CodexBar appcast feed</description>
<language>zh-CN</language>
+ <item>
+ <title>CodexBar.app 3.6.4</title>
+ <sparkle:version>71</sparkle:version>
+ <sparkle:shortVersionString>3.6.4</sparkle:shortVersionString>
+ <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+ <sparkle:releaseNotesLink>https://codexbar.zabrian.app/notes#3.6.4</sparkle:releaseNotesLink>
+ <pubDate>Fri, 14 Aug 2026 11:31:25 +0800</pubDate>
+ <enclosure url="https://codexbar.zabrian.app/download/CodexBar-v3.6.4.dmg" sparkle:edSignature="xwLME1JE73pbUKMoB2gLQ9/TxCAdqFpmbcuwnfSQpMByw9W/srQD0RyZ0S1JPzr4jZtMqKXe/VoHLLuko2XIDw==" length="7110859" type="application/octet-stream"/>
+ </item>
<item>
<title>CodexBar.app 3.6.3</title>
<sparkle:version>70</sparkle:version>