CodexBar 是一个 macOS 菜单栏应用,用于查看本机 Codex 账号状态、额度、Token 用量、详细统计信息
Swift appkitcodexcodex-clideveloper-toolsmacosmacos-appmenu-bar-appopenai-codexproductivityswiftswiftuiusage-tracker
fix: 优化 Codex 来源选择与重连交互
Bob90f44230c955
diff --git a/CLAUDE.md b/CLAUDE.mdindex 66fdb2e..5e05c79 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -31,6 +31,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co- 标题、独立列表项、编号项和表格单元格行末不加标点- 如果一行以 Markdown 格式的链接或行内代码结尾,后面不加任何标点;链接或行内代码位于句中时仍按句子结构使用中文标点- Markdown 语法、代码块、命令、路径、URL、版本号和程序标识符内部的符号保持原样+- 如果某句话的作用只是防止被质疑,而不是推进论证,请删除## 项目概述@@ -175,8 +176,8 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev关键约束:-- `shouldDisableSleep` 是用户意图与依赖可用性的唯一汇合点,要求 `isStarted && !isPreparingForTermination && isEnabled && isHookEnabled && hasRunningTasks && helperStatus == .enabled && !isRefreshingHelper && !isLowBatteryActive && !hasReachedMaximumDuration` 同时成立;**依赖不满足只让效果失效,绝不回写用户保存的 `isEnabled`**-- `hasRunningTasks` 只消费 `CodexActivitySnapshot` 中非匿名且仍可见的运行中任务与按设置纳入的等待批准任务,被异常会话保护隐藏的任务也不参与防睡眠+- `shouldDisableSleep` 由 `sleepBlockReason == nil` 派生,要求服务已启动、App 未退出、主开关与 Hook 可用、存在符合条件的任务、helper 已批准且未刷新、低电量与时长上限均未阻断;依赖变化保留用户保存的 `isEnabled`+- `hasRunningTasks` 只表示非匿名且仍可见的运行中任务;`hasKeepAliveTasks` 在此基础上纳入 `keepsAwakeWhileWaiting` 开启时的非匿名等待任务,被异常会话保护隐藏的任务不参与防睡眠- Hook 状态在类内只认 `isHookEnabled` 这份镜像,它跟的是 `codexHookSettings.isOperable`;不要回读那个属性,订阅回调跑在 `willSet`,那一刻它的两个输入里正在变的那一项还是旧值,只能认 `CombineLatest` 给的闭包参数- 新增拦截条件一律加进 `sleepBlockReason` 的顺序判断里,它和 `shouldDisableSleep` 同源,顺带保证日志的 `reason=` 不会漏项- UI 用的 `isLowBatteryBlocking` 与 `canShowOptions` 由 `reconcileSleepState` 从 `sleepBlockReason` 单点派生,新增拦截条件时 `allowsOptions` 那个穷举 `switch` 会强制表态,于是不会出现入口亮着却点不动@@ -203,7 +204,7 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev- 切换失败按 2/4/8...256 秒重试,列表耗尽即放弃(延时累计约 8.5 分钟,每轮再等一次超时约 10 分钟),瞬时抖动能自愈,权限类故障不该无限重试- XPC 请求带超时并汇进同一条重试路径;launchd 拉不起 helper 时 XPC 方法既不回复也不触发 `errorHandler`,没有它界面会显示防睡眠开着而实际没生效,日志里只剩没有配对回复的 `Helper XPC 请求已发送`- 超时取值放在 `CodexBarHelperIPC.requestTimeoutSeconds` 而不是控制器里,它与 `watchdogGraceSeconds` 是一对:必须更小,App 先放手 helper 才能靠 watchdog 兜底,分处两个 module 会让人改了一边不知道另一边-- 开发期间用 `xcodebuild` 覆盖正在运行的 App bundle 会让 launchd 记的 daemon 与磁盘上的 helper 对不上,helper 从此拉不起来;重启 App 会由 `helperRegistrationNeedsRefresh` 的指纹比对自愈,排查时先看这一条+- 开发期间用 `xcodebuild` 覆盖正在运行的 App bundle 可能使 launchd 注册信息与磁盘上的 helper 不一致;重启 App 后通过 `KeepAliveHelperConfiguration.registrationNeedsRefresh(defaults:)` 检查指纹并刷新注册- helper 回传 `none`、`external`、`codexBar` 来源与操作后的实测值;App 只能在 `codexBar` 且实测为 0 时宣称系统睡眠已恢复或补发 `IOPMSleepSystem`,`external` 和 `none` 都只释放进程内断言- App 退出由 `applicationShouldTerminate` 返回 `terminateLater`,先取消自动重置唤醒计划,再释放防睡眠租约;两项都经 helper 回读确认后才继续退出,任一失败都会取消本次退出并恢复协调- `pmset` 是没有来源和引用计数的全局布尔值;CodexBar 取得所有权后如果另一个 App 也开始依赖这个 1,释放时仍会恢复为 0,系统层没有无歧义的方法判断另一个 App 的意图@@ -340,11 +341,11 @@ Hook 子进程按天写入 `~/Library/Application Support/CodexBar/HookEvents/ev- 启用和校验 Hook 前要求当前 app-server 握手版本至少为 `0.145.0`;必须检查 `readyConnectionInfo()` 返回的实际连接版本,不能用磁盘版本代替,否则升级后尚未重连的旧进程会被误判为可用- 写入前通过 app-server `config/read` 确认全局未禁用 Hook,写入后用 `hooks/list` 验证;两处读取共用 `readGlobalHookDisabled`,开关流程与校验流程对“全局禁用”的判断不会分叉- 读取失败(I/O 或 JSON 格式错误)不提供 Hook 装没装的信息,必须保留上次已知值,不能当成用户关闭了 Hook-- `isEnabled` 只表示 `hooks.json` 里至少装着一个当前 CodexBar handler,`isVerified` 是最近一次校验的明确结论,两者合成的 `isOperable` 才表示事件链路可用+- `isEnabled` 表示当前进程中的 Hook 开启状态,首次从已有 handler 恢复;开启后配置缺失会触发自愈。`isVerified` 保存最近一次校验的明确结论,`isOperable` 为两者的合取- 实时任务、防睡眠和任务类通知必须看 `isOperable`;历史聚合与同步仍可消费已落盘数据,其调度只看 `isEnabled`,不要把两类依赖混在一起-- `isVerified` 乐观默认为 `true` 且只由明确结论写入两个方向:校验只在设置窗口打开与 App 激活时跑,而 RPC 失败属于“验不了”不是“确认不通”,那时置灰会把好用的功能关掉+- `isVerified` 默认为 `true`,RPC 临时失败或取消时保留上次明确结论。启动、打开主面板、打开设置、App 激活和额度刷新完成时对账已开启 Hook- 全局禁用要排在 `hooks/list` 之前判:它一关列表里必然找不到我们的 handler,那时报“已不完整”会把用户引去翻本来就完好的 `hooks.json`-- `refresh()` 只判断是否存在任一当前 CodexBar handler,`hooks/list` 校验才要求所有事件完整;新增事件后旧配置不会自动补齐,当前恢复方式是让用户关闭再开启 Hook+- `refreshInstallationState()` 检查 handler 是否存在及事件是否完整;已开启配置缺少必要事件或信任项时,`reconcileInstalledHooks()` 自动补齐并重新校验。启动前已无可识别 handler 时保持关闭- 防睡眠开关关闭时说明行收起;开关开启且 Hook 校验不通过时显示“CodexBar Hook 未生效”,具体病因由 Hook 设置行说明## 隐私与数据边界diff --git a/CodexBar/Resources/Localizable.xcstrings b/CodexBar/Resources/Localizable.xcstringsindex 1e40b2e..7484002 100644--- a/CodexBar/Resources/Localizable.xcstrings+++ b/CodexBar/Resources/Localizable.xcstrings@@ -897,6 +897,70 @@}}},+ "banked-reset.available-count" : {+ "localizations" : {+ "en" : {+ "stringUnit" : {+ "state" : "translated",+ "value" : "%lld left"+ }+ },+ "zh-Hans" : {+ "stringUnit" : {+ "state" : "translated",+ "value" : "可用: %lld"+ }+ }+ }+ },+ "banked-reset.count" : {+ "localizations" : {+ "en" : {+ "stringUnit" : {+ "state" : "translated",+ "value" : "Banked Resets: %lld"+ }+ },+ "zh-Hans" : {+ "stringUnit" : {+ "state" : "translated",+ "value" : "留存重置: %lld"+ }+ }+ }+ },+ "banked-reset.expiration.label" : {+ "localizations" : {+ "en" : {+ "stringUnit" : {+ "state" : "translated",+ "value" : "Expires"+ }+ },+ "zh-Hans" : {+ "stringUnit" : {+ "state" : "translated",+ "value" : "过期时间"+ }+ }+ }+ },+ "banked-reset.expiration.unknown" : {+ "localizations" : {+ "en" : {+ "stringUnit" : {+ "state" : "translated",+ "value" : "Expiration time unknown"+ }+ },+ "zh-Hans" : {+ "stringUnit" : {+ "state" : "translated",+ "value" : "未知过期时间"+ }+ }+ }+ },"codex-cli.version.launch-failed" : {"localizations" : {"en" : {@@ -3345,70 +3409,6 @@}}},- "reset-credits.available-count" : {- "localizations" : {- "en" : {- "stringUnit" : {- "state" : "translated",- "value" : "%lld left"- }- },- "zh-Hans" : {- "stringUnit" : {- "state" : "translated",- "value" : "可用: %lld"- }- }- }- },- "reset-credits.count" : {- "localizations" : {- "en" : {- "stringUnit" : {- "state" : "translated",- "value" : "Reset: %lld"- }- },- "zh-Hans" : {- "stringUnit" : {- "state" : "translated",- "value" : "重置次数: %lld"- }- }- }- },- "reset-credits.expiration.label" : {- "localizations" : {- "en" : {- "stringUnit" : {- "state" : "translated",- "value" : "Expires"- }- },- "zh-Hans" : {- "stringUnit" : {- "state" : "translated",- "value" : "过期时间"- }- }- }- },- "reset-credits.expiration.unknown" : {- "localizations" : {- "en" : {- "stringUnit" : {- "state" : "translated",- "value" : "Expiration time unknown"- }- },- "zh-Hans" : {- "stringUnit" : {- "state" : "translated",- "value" : "未知过期时间"- }- }- }- },"settings.about.github-project" : {"localizations" : {"en" : {@@ -3478,13 +3478,13 @@"en" : {"stringUnit" : {"state" : "translated",- "value" : "Refresh Connection"+ "value" : "Reconnect"}},"zh-Hans" : {"stringUnit" : {"state" : "translated",- "value" : "刷新连接"+ "value" : "重新建立连接"}}}@@ -3494,13 +3494,13 @@"en" : {"stringUnit" : {"state" : "translated",- "value" : "Reconnecting…"+ "value" : "Reconnecting"}},"zh-Hans" : {"stringUnit" : {"state" : "translated",- "value" : "正在重新连接…"+ "value" : "正在重新连接"}}}@@ -3537,22 +3537,6 @@}}},- "settings.codex-version.source.title" : {- "localizations" : {- "en" : {- "stringUnit" : {- "state" : "translated",- "value" : "Source"- }- },- "zh-Hans" : {- "stringUnit" : {- "state" : "translated",- "value" : "来源"- }- }- }- },"settings.codex-version.title" : {"localizations" : {"en" : {diff --git a/CodexBar/Views/Menu/CodexStatusMenuSections.swift b/CodexBar/Views/Menu/CodexStatusMenuSections.swiftindex 62c2a0b..44ad424 100644--- a/CodexBar/Views/Menu/CodexStatusMenuSections.swift+++ b/CodexBar/Views/Menu/CodexStatusMenuSections.swift@@ -281,7 +281,7 @@ struct QuotaLimitsSection: View {))} label: {- metadataCapsule(String(localized: "reset-credits.count", defaultValue: "\(count, specifier: "%lld")"))+ metadataCapsule(String(localized: "banked-reset.count", defaultValue: "\(count, specifier: "%lld")"))}.buttonStyle(.plain)}diff --git a/CodexBar/Views/Menu/ResetCreditsPanelView.swift b/CodexBar/Views/Menu/ResetCreditsPanelView.swiftindex 7db44b2..485dcb9 100644--- a/CodexBar/Views/Menu/ResetCreditsPanelView.swift+++ b/CodexBar/Views/Menu/ResetCreditsPanelView.swift@@ -97,7 +97,7 @@ struct ResetCreditsPanelView: View {}private var emptyMessage: some View {- Text("reset-credits.expiration.unknown")+ Text("banked-reset.expiration.unknown").font(.caption2).foregroundStyle(.secondary).frame(maxWidth: .infinity, minHeight: Metrics.rowHeight, alignment: .leading)@@ -142,7 +142,7 @@ struct ResetCreditsPanelView: View {.hidden().overlay {HStack(alignment: .center, spacing: 0) {- Text("reset-credits.expiration.label")+ Text("banked-reset.expiration.label").font(.caption2.weight(.medium)).foregroundStyle(.secondary).lineLimit(1)@@ -172,7 +172,7 @@ struct ResetCreditsPanelView: View {.green}- return Text(LocalizedStringResource("reset-credits.available-count", defaultValue: "\(group.count, specifier: "%lld")"))+ return Text(LocalizedStringResource("banked-reset.available-count", defaultValue: "\(group.count, specifier: "%lld")")).font(.caption2.monospacedDigit().weight(.semibold)).foregroundStyle(tint).lineLimit(1)diff --git a/CodexBar/Views/Menu/UsageHeatmap.swift b/CodexBar/Views/Menu/UsageHeatmap.swiftindex e80e956..544eb08 100644--- a/CodexBar/Views/Menu/UsageHeatmap.swift+++ b/CodexBar/Views/Menu/UsageHeatmap.swift@@ -945,10 +945,9 @@ private struct HeatmapTokenText: View {.foregroundStyle(Color.codexLabel)case .pending:- Image(systemName: "hourglass")- .font(.system(size: 13, weight: .medium))- .foregroundStyle(Color.codexSecondaryLabel)- .symbolEffect(.rotate.byLayer, options: .repeat(.periodic(delay: 1.0)))+ Image(systemName: "questionmark")+ .font(font)+ .foregroundStyle(Color.codexLabel)case .unavailable:Text(verbatim: "--")diff --git a/CodexBar/Views/Settings/CodexSourcePicker.swift b/CodexBar/Views/Settings/CodexSourcePicker.swiftnew file mode 100644index 0000000..a45dfde--- /dev/null+++ b/CodexBar/Views/Settings/CodexSourcePicker.swift@@ -0,0 +1,425 @@+import AppKit+import QuartzCore+import SwiftUI++/// 开合和悬停状态留在选择器内部, 避免交互时重新计算整个版本区+struct CodexSourcePicker: View {+ let selection: CodexCLISourceSelection+ let options: [CodexCLISourceSelection]+ let isEnabled: Bool+ let onSelect: (CodexCLISourceSelection) -> Void+ @State private var isHovered = false+ @State private var isPresented = false+ @Environment(\.accessibilityReduceMotion) private var reduceMotion++ private var title: String {+ options.contains(selection) ? selection.title : String(localized: "settings.codex-version.source.select")+ }++ var body: some View {+ Button {+ isPresented.toggle()+ } label: {+ HStack(spacing: 6) {+ ZStack(alignment: .leading) {+ ForEach(options) { option in+ Text(option.title).hidden()+ }+ Text(title)+ .foregroundStyle(isEnabled ? .primary : .secondary)+ }+ .font(.caption.weight(.medium))+ .lineLimit(1)++ Image(systemName: "chevron.down")+ .font(.system(size: 9, weight: .semibold))+ .foregroundStyle(.secondary)+ .rotationEffect(.degrees(isPresented ? 180 : 0))+ .animation(reduceMotion ? nil : .codexStatus, value: isPresented)+ .accessibilityHidden(true)+ }+ .padding(.horizontal, 8)+ .frame(height: SettingsRowMetrics.optionsButtonSize)+ .background {+ Capsule(style: .continuous)+ .fill(.primary.opacity((isHovered || isPresented) && isEnabled ? 0.06 : 0))+ .animation(reduceMotion ? nil : .codexStatus, value: isHovered || isPresented)+ }+ .liquidGlassCapsule(tint: isEnabled ? .accentColor : .secondary)+ .contentShape(Capsule(style: .continuous))+ }+ .buttonStyle(.plain)+ .controlSize(.small)+ .fixedSize()+ .disabled(!isEnabled)+ .onHover { isHovered = $0 }+ .accessibilityValue(Text(title))+ .background {+ CodexSourceDropdown(+ isPresented: $isPresented,+ selection: selection,+ options: options,+ isEnabled: isEnabled,+ animates: !reduceMotion,+ onSelect: onSelect+ )+ }+ .onDisappear {+ isPresented = false+ }+ .onChange(of: isEnabled) { _, isEnabled in+ if !isEnabled {+ isPresented = false+ }+ }+ .onChange(of: options) { _, _ in+ isPresented = false+ }+ }+}++/// 浮层开合由同一处处理, 快速点击从当前呈现位置反向动画+private struct CodexSourceDropdown: NSViewRepresentable {+ @Binding var isPresented: Bool+ let selection: CodexCLISourceSelection+ let options: [CodexCLISourceSelection]+ let isEnabled: Bool+ let animates: Bool+ let onSelect: (CodexCLISourceSelection) -> Void++ func makeCoordinator() -> Coordinator {+ Coordinator(configuration: self)+ }++ func makeNSView(context: Context) -> AnchorView {+ let view = AnchorView()+ context.coordinator.anchorView = view+ view.onWindowChange = { [weak coordinator = context.coordinator] in+ coordinator?.scheduleReconcile()+ }+ return view+ }++ func updateNSView(_: AnchorView, context: Context) {+ context.coordinator.configuration = self+ context.coordinator.scheduleReconcile()+ }++ static func dismantleNSView(_ view: AnchorView, coordinator: Coordinator) {+ view.onWindowChange = nil+ coordinator.dispose()+ }++ final class AnchorView: NSView {+ var onWindowChange: (() -> Void)?++ override func hitTest(_: NSPoint) -> NSView? {+ nil+ }++ override func viewDidMoveToWindow() {+ super.viewDidMoveToWindow()+ onWindowChange?()+ }+ }++ final class Coordinator: NSObject, NSPopoverDelegate {+ var configuration: CodexSourceDropdown+ weak var anchorView: AnchorView?+ private let popover = NSPopover()+ private weak var observedWindow: NSWindow?+ private var targetIsVisible = false+ private var presentedOrigin = NSPoint.zero+ private var animationGeneration = 0+ private var reconcileTask: Task<Void, Never>?+ private var localMonitor: Any?+ private var observers: [NSObjectProtocol] = []+ private var isAnchorPressInProgress = false+ private var isDisposed = false++ init(configuration: CodexSourceDropdown) {+ self.configuration = configuration+ super.init()+ popover.delegate = self+ popover.behavior = .applicationDefined+ popover.animates = false+ }++ func scheduleReconcile() {+ guard reconcileTask == nil else { return }+ reconcileTask = Task { @MainActor [weak self] in+ await Task.yield()+ guard let self, !Task.isCancelled else { return }+ reconcileTask = nil+ reconcile()+ }+ }++ private func setPresented(_ isPresented: Bool) {+ configuration.isPresented = isPresented && configuration.isEnabled+ reconcile()+ }++ private func reconcile() {+ guard !isDisposed else { return }+ guard let anchorView, let window = anchorView.window, window.isVisible else {+ configuration.isPresented = false+ closeImmediately()+ removeMonitors()+ return+ }+ installMonitors(for: window)+ let wantsPresentation = configuration.isPresented && configuration.isEnabled+ guard wantsPresentation != targetIsVisible else { return }+ if wantsPresentation, !popover.isShown {+ guard !anchorView.visibleRect.isEmpty, show(relativeTo: anchorView) else {+ configuration.isPresented = false+ return+ }+ }+ targetIsVisible = wantsPresentation+ if wantsPresentation {+ popover.contentViewController?.view.window?.makeKey()+ }+ animateVisibility(wantsPresentation)+ }++ private func show(relativeTo anchor: NSView) -> Bool {+ let content = CodexSourceOptions(+ selection: configuration.selection,+ options: configuration.options,+ onSelect: { [weak self] selection in+ guard let self else { return }+ setPresented(false)+ configuration.onSelect(selection)+ }+ )+ let host = NSHostingController(rootView: content)+ host.sizingOptions = [.preferredContentSize]+ guard let size = host.view.validFittingSize else { return false }+ popover.contentViewController = host+ popover.contentSize = size+ popover.show(relativeTo: anchor.bounds, of: anchor, preferredEdge: .minY)+ guard popover.isShown, let window = popover.contentViewController?.view.window else {+ popover.close()+ return false+ }+ presentedOrigin = window.frame.origin+ window.alphaValue = 0+ window.setFrameOrigin(NSPoint(x: presentedOrigin.x, y: presentedOrigin.y + 8))+ return true+ }++ private func animateVisibility(_ isVisible: Bool) {+ guard let window = popover.contentViewController?.view.window else {+ closeImmediately()+ return+ }+ animationGeneration += 1+ let generation = animationGeneration+ let targetOpacity: CGFloat = isVisible ? 1 : 0+ let targetFrame = NSRect(+ origin: NSPoint(x: presentedOrigin.x, y: presentedOrigin.y + (isVisible ? 0 : 8)),+ size: window.frame.size+ )+ // 整个窗口一起移动和淡入淡出, 避免系统边框和材质与内部图层变换不同步+ // animator 会从当前值转向新目标, 连续点击无需等待上一次动画结束+ NSAnimationContext.runAnimationGroup { context in+ context.duration = configuration.animates ? 0.18 * abs(targetOpacity - window.alphaValue) : 0+ context.timingFunction = CAMediaTimingFunction(name: .easeInEaseOut)+ window.animator().alphaValue = targetOpacity+ window.animator().setFrame(targetFrame, display: true)+ } completionHandler: { [weak self] in+ Task { @MainActor [weak self] in+ self?.finishAnimation(generation: generation)+ }+ }+ }++ private func finishAnimation(generation: Int) {+ guard !isDisposed, animationGeneration == generation, !targetIsVisible else { return }+ popover.close()+ }++ private func closeImmediately() {+ animationGeneration += 1+ if let window = popover.contentViewController?.view.window {+ NSAnimationContext.runAnimationGroup { context in+ context.duration = 0+ window.animator().alphaValue = window.alphaValue+ window.animator().setFrame(window.frame, display: true)+ }+ }+ targetIsVisible = false+ popover.close()+ }++ func popoverWillClose(_: Notification) {+ animationGeneration += 1+ targetIsVisible = false+ configuration.isPresented = false+ }++ private func installMonitors(for window: NSWindow) {+ guard observedWindow !== window || localMonitor == nil else { return }+ removeMonitors()+ observedWindow = window+ // 锚点的按下和抬起始终走同一条路径, 不随浮层开关切换回 SwiftUI 按钮的鼠标追踪+ localMonitor = NSEvent.addLocalMonitorForEvents(matching: [+ .leftMouseDown, .leftMouseUp, .leftMouseDragged, .rightMouseDown, .otherMouseDown, .keyDown+ ]) { [weak self] event in+ guard let self else { return event }+ return handleEvent(event)+ }+ for (name, object) in [+ (NSApplication.didResignActiveNotification, NSApplication.shared as AnyObject),+ (NSWindow.willCloseNotification, window as AnyObject),+ (NSWindow.willMiniaturizeNotification, window as AnyObject)+ ] {+ observers.append(NotificationCenter.default.addObserver(forName: name, object: object, queue: .main) { [weak self] _ in+ MainActor.assumeIsolated {+ guard let self else { return }+ if name == NSWindow.willCloseNotification {+ self.configuration.isPresented = false+ self.closeImmediately()+ self.removeMonitors()+ } else {+ self.setPresented(false)+ }+ }+ })+ }+ }++ private func handleEvent(_ event: NSEvent) -> NSEvent? {+ if isAnchorPressInProgress, event.type == .leftMouseUp || event.type == .leftMouseDragged {+ if event.type == .leftMouseUp {+ isAnchorPressInProgress = false+ }+ return nil+ }+ if event.type == .leftMouseDown, configuration.isEnabled,+ let anchorView, !anchorView.isHiddenOrHasHiddenAncestor,+ event.window === anchorView.window,+ anchorView.bounds.intersection(anchorView.visibleRect).contains(anchorView.convert(event.locationInWindow, from: nil)) {+ isAnchorPressInProgress = true+ setPresented(!configuration.isPresented)+ return nil+ }+ guard popover.isShown else { return event }+ if event.type == .keyDown {+ guard event.keyCode == 53 else { return event }+ setPresented(false)+ return nil+ }+ if [.leftMouseDown, .rightMouseDown, .otherMouseDown].contains(event.type),+ event.window !== popover.contentViewController?.view.window {+ setPresented(false)+ }+ return event+ }++ private func removeMonitors() {+ if let localMonitor {+ NSEvent.removeMonitor(localMonitor)+ self.localMonitor = nil+ }+ observers.forEach(NotificationCenter.default.removeObserver)+ observers.removeAll()+ observedWindow = nil+ isAnchorPressInProgress = false+ }++ func dispose() {+ isDisposed = true+ reconcileTask?.cancel()+ popover.delegate = nil+ closeImmediately()+ removeMonitors()+ }+ }+}++private struct CodexSourceOptions: View {+ let selection: CodexCLISourceSelection+ let options: [CodexCLISourceSelection]+ let onSelect: (CodexCLISourceSelection) -> Void+ @State private var highlightedSelection: CodexCLISourceSelection?++ var body: some View {+ VStack(spacing: 3) {+ ForEach(options) { option in+ Button {+ onSelect(option)+ } label: {+ HStack(spacing: 8) {+ Image(systemName: "checkmark")+ .font(.system(size: 10, weight: .semibold))+ .foregroundStyle(.tint)+ .opacity(option == selection ? 1 : 0)+ .frame(width: 12)+ .accessibilityHidden(true)++ Text(option.title)+ .font(.caption.weight(.medium))+ .lineLimit(1)+ .frame(maxWidth: .infinity, alignment: .leading)++ Color.clear+ .frame(width: 12, height: 10)+ .accessibilityHidden(true)+ }+ .padding(.horizontal, 8)+ .frame(height: 28)+ .background {+ RoundedRectangle(cornerRadius: 14, style: .continuous)+ .fill(.primary.opacity(highlightedSelection == option ? 0.08 : 0))+ }+ .contentShape(Rectangle())+ }+ .buttonStyle(.plain)+ .focusable(false)+ .onHover { isHovered in+ if isHovered {+ highlightedSelection = option+ }+ }+ .accessibilityAddTraits(option == selection ? .isSelected : [])+ }+ }+ .padding(6)+ .fixedSize(horizontal: true, vertical: false)+ // 列表接收方向键, 展开时不自动聚焦或高亮某个选项+ .focusable()+ .focusEffectDisabled()+ // 经过行间空隙时保留高亮, 离开列表才清除, 避免闪回键盘焦点所在行+ .onHover { isHovered in+ if !isHovered {+ highlightedSelection = nil+ }+ }+ .onKeyPress(.upArrow) {+ moveFocus(by: -1)+ return .handled+ }+ .onKeyPress(.downArrow) {+ moveFocus(by: 1)+ return .handled+ }+ .onKeyPress(.return) {+ if let selected = highlightedSelection {+ onSelect(selected)+ }+ return .handled+ }+ }++ private func moveFocus(by offset: Int) {+ guard !options.isEmpty else { return }+ if let index = highlightedSelection.flatMap({ options.firstIndex(of: $0) }) {+ highlightedSelection = options[(index + offset + options.count) % options.count]+ } else {+ highlightedSelection = offset > 0 ? options.first : options.last+ }+ }+}diff --git a/CodexBar/Views/Settings/CodexVersionSection.swift b/CodexBar/Views/Settings/CodexVersionSection.swiftindex 577fca8..b60d29b 100644--- a/CodexBar/Views/Settings/CodexVersionSection.swift+++ b/CodexBar/Views/Settings/CodexVersionSection.swift@@ -54,32 +54,14 @@ struct CodexVersionSection: View {private var sourceSelectionControls: some View {HStack(spacing: SettingsRowMetrics.spacing) {- Picker(- "settings.codex-version.source.title",- selection: Binding(- get: { availableSelections.contains(sourceSelection) ? sourceSelection : nil },- set: { selection in- guard let selection, selection != sourceSelection else { return }- onReconnect(selection)- }- )- ) {- if !availableSelections.contains(sourceSelection) {- Text("settings.codex-version.source.select")- .tag(CodexCLISourceSelection?.none)- .disabled(true)- }-- ForEach(availableSelections) { selection in- Text(selection.title)- .tag(Optional(selection))- }+ CodexSourcePicker(+ selection: sourceSelection,+ options: availableSelections,+ isEnabled: !isBusy+ ) { selection in+ guard !isBusy, availableSelections.contains(selection), selection != sourceSelection else { return }+ onReconnect(selection)}- .labelsHidden()- .pickerStyle(.menu)- .controlSize(.small)- .frame(width: Metrics.sourcePickerWidth, alignment: .trailing)- .disabled(isBusy)reconnectButton}@@ -87,7 +69,8 @@ struct CodexVersionSection: View {}private var reconnectButton: some View {- let isEnabled = !isBusy && !isReconnecting && isSourceInstalled(sourceSelection)+ let isWorking = isBusy || isReconnecting+ let isEnabled = !isWorking && isSourceInstalled(sourceSelection)let label: LocalizedStringKey = isReconnecting? "settings.codex-version.reconnecting": "settings.codex-version.reconnect"@@ -95,10 +78,21 @@ struct CodexVersionSection: View {return Button {onReconnect(nil)} label: {- Image(systemName: "arrow.clockwise")- .symbolEffect(.rotate.byLayer, options: .repeat(.periodic(delay: 0.0)), isActive: isReconnecting)- .frame(width: SettingsRowMetrics.optionsButtonSize, height: SettingsRowMetrics.optionsButtonSize)- .contentShape(Rectangle())+ let icon = Image(systemName: "cable.coaxial")+ Group {+ if #available(macOS 26.0, *), isWorking {+ // DrawOn 保持激活会停在隐藏状态, 交替阶段才能持续重复绘制+ icon.phaseAnimator([true, false]) { content, isHidden in+ content.symbolEffect(.drawOn.byLayer, options: .repeat(.continuous), isActive: isHidden)+ } animation: { _ in+ .linear(duration: 0.5)+ }+ } else {+ icon.symbolEffect(.wiggle.clockwise.byLayer, options: .repeat(.continuous), isActive: isWorking)+ }+ }+ .frame(width: SettingsRowMetrics.optionsButtonSize, height: SettingsRowMetrics.optionsButtonSize)+ .contentShape(Rectangle())}.buttonStyle(.plain).controlSize(.small)@@ -212,7 +206,6 @@ struct CodexVersionSection: View {static let rowSpacing: CGFloat = 14static let iconWidth = SettingsRowMetrics.iconWidthstatic let childIndent: CGFloat = 28- static let sourcePickerWidth: CGFloat = 140static let versionColumnWidth: CGFloat = 270static let statusAnimation = Animation.codexStatus}diff --git a/Config/Version.xcconfig b/Config/Version.xcconfigindex 3048284..fcec4d9 100644--- a/Config/Version.xcconfig+++ b/Config/Version.xcconfig@@ -1,2 +1,2 @@-MARKETING_VERSION = 3.6.15-CURRENT_PROJECT_VERSION = 82+MARKETING_VERSION = 3.6.16+CURRENT_PROJECT_VERSION = 83diff --git a/Docs/DeveloperGuide/app-server.md b/Docs/DeveloperGuide/app-server.mdindex 865c2b5..0bbfa28 100644--- a/Docs/DeveloperGuide/app-server.md+++ b/Docs/DeveloperGuide/app-server.md@@ -79,7 +79,7 @@ resolver 会做 3 层归一化:2. 保留现有 `PATH`,再按顺序补充常见目录并去重3. 对候选路径解析 symlink 和 standardized URL,避免同一内置 binary 同时被识别成 global 与 bundled-全局 CLI 优先是一个明确的产品选择。开发者主动安装的 CLI 通常代表其期望版本,内置 CLI 只是找不到全局版本时的可用回退。+`CodexCLISourceSelection.automatic` 优先使用全局 CLI,找不到时使用 App 内置 CLI。手动选择 `global` 或 `bundled` 后只使用指定来源,缺失时返回 `sourceUnavailable`。来源选择由 `CodexStatusService` 保存,重建连接时沿用。### 磁盘版本和运行版本为什么分开@@ -308,6 +308,8 @@ stale 是数据可信度的一部分,新增展示时不能只复制数值而## Reset Credits+界面将可用数量显示为“留存重置”或“Banked Resets”,本地化键为 `banked-reset.count`。协议字段仍使用 `rateLimitResetCredits`+`account/rateLimits/read` 的 `rateLimitResetCredits` 同时返回可用数量和可选明细:- `availableCount` 是权威总数diff --git a/Docs/DeveloperGuide/data-and-privacy.md b/Docs/DeveloperGuide/data-and-privacy.mdindex 36724b4..61ef0d4 100644--- a/Docs/DeveloperGuide/data-and-privacy.md+++ b/Docs/DeveloperGuide/data-and-privacy.md@@ -15,7 +15,7 @@ CodexBar 只读取实现账户展示、自动重置、Hook 统计、实时任务## 数据分类模型-开发时把数据分成 4 类有助于决定存储和传播范围:+数据按以下类别确定存储和传播范围:| 分类 | 示例 | 默认处理 || --- | --- | --- |@@ -295,7 +295,7 @@ helper 的 ownership 文件不是用户偏好,而是 crash recovery 事务记| --- | --- | --- || 字段从旧来源缺失 | `nil` 或 unavailable | 解码成明确的 0 || app-server 缓存过期 | stale 快照 | 继续触发通知 |-| rollout reader 不可用 | 暂停实时判定 | 使用旧任务继续防睡眠 |+| rollout 补充读取不可用 | 保留已有 Hook 任务状态,后续轮询继续补充生命周期 | 把缺少 rollout 结果解释为任务已结束 || CloudKit 离线 | 保留带来源的旧 cache | 当作当前账户新数据 || 电池读取失败 | 保留上次判定并标记 unreadable | 当作没有电池 |diff --git a/Docs/DeveloperGuide/hook-and-aggregation.md b/Docs/DeveloperGuide/hook-and-aggregation.mdindex 658dc84..f2506c9 100644--- a/Docs/DeveloperGuide/hook-and-aggregation.md+++ b/Docs/DeveloperGuide/hook-and-aggregation.md@@ -135,7 +135,7 @@ CodexBar 不把命令塞进用户已有 group。独立 group 让卸载时可以### 异步设置操作的代际-用户可以快速开关 Hook,App 激活也会触发校验。`CodexHookSettings` 每次操作递增 `updateGeneration` 并取消旧 Task。+用户开关 Hook 或触发校验时,`CodexHookSettings` 通过 `updateCoordinator` 启动操作,由 `RefreshTaskCoordinator` 推进代际并取消旧 Task。每个文件写入或 RPC await 之后都会再次检查 generation。旧操作即使无法真正取消,也不能把新的开关状态或错误信息覆盖回去。diff --git a/Docs/DeveloperGuide/notifications.md b/Docs/DeveloperGuide/notifications.mdindex 20d4e07..f16c82c 100644--- a/Docs/DeveloperGuide/notifications.md+++ b/Docs/DeveloperGuide/notifications.md@@ -44,7 +44,7 @@ View 和其他服务不直接创建系统通知。它们发布状态变化,通| 自动重置 | app-server mutation 结果 | 只有明确结果才能说明本机自动操作发生过 || 任务完成 | monitor 转场 | 历史 terminal 快照不能补发 || 等待批准 | monitor 转场加当前快照 | 先通知新等待,再撤回过时等待 |-| 异常会话保护 | 已提交保护结果 | 必须描述已经隐藏的任务 |+| 异常会话保护 | 达到静默阈值且仍有效的保护候选 | 提交通知与隐藏前分别校验候选 || 防睡眠停止 | 已确认系统恢复结果 | 不能在恢复请求前预告成功 |从当前快照推导任务完成看起来更简单,但 App 每次启动都会把历史完成任务当作新事件。相反,对低额度只看单次转场又无法识别 App 在阈值穿越后才启动的场景。@@ -83,7 +83,7 @@ App 激活时会重新读取系统状态,因为用户可能在 System Settings| 低电量保护停止 | KeepAlive 恢复结果 | 独立子开关,仅在保护可用时启用 || 防睡眠达到上限 | KeepAlive 恢复结果 | 独立子开关,仅在有限时长时启用 |-异常会话保护没有独立通知子开关。它本身跟随防睡眠主开关,保护动作发生后再服从通知总开关。低电量和时长上限的通知偏好会保留,但对应保护条件不可用时 UI 显示为关闭并置灰,不修改持久化偏好。+异常会话保护跟随防睡眠主开关,通知服从总开关和系统授权,没有独立通知子开关。低电量和时长上限的通知偏好会保留,对应保护条件不可用时 UI 显示为关闭并置灰。## 额度重置@@ -209,15 +209,11 @@ app-server 连接重建后,同一窗口的 `resetsAt` 可能出现秒级修正## 异常会话保护-非匿名任务静默达到阈值时,Activity Protection 先保存保护记录并隐藏任务,然后请求通知。匿名任务不进入保护候选,也不会产生保护通知。+非匿名运行任务静默达到阈值时,Activity Protection 先登记保护记录,再并行启动通知提交和 3 秒宽限。通知处理返回或宽限到期后,monitor 重新校验候选,仍有效时才隐藏任务。通知失败也会继续完成保护。-通知服务在提交前再次检查任务是否仍然被保护。如果 3 秒宽限内出现新进展,过时通知会被取消。+通知使用 `taskID + attemptID` 作为 identifier,提交前后校验 progress generation 和静默时长。新进展会使保护尝试失效,并撤回对应通知。-保护通知使用固定默认声音,不复用任务完成分类声音。通知发送失败不撤销已经完成的保护动作。--异常会话保护使用 `taskID + attemptID` 作为 identifier,relevance 还比较 progress generation 和静默时长。任务在 3 秒通知宽限内出现进展时,monitor 让保护尝试失效并请求撤回。--这类通知的 `retryCount` 明确为 0。保护结果对时间高度敏感,立即提交失败后再重试可能已经不相关。一般通知可以重试一次,保护通知宁可漏发也不迟到误报。+保护通知使用系统默认声音,`retryCount` 为 `0`,避免重试已经失效的候选。## 防睡眠停止diff --git a/Docs/DeveloperGuide/sync.md b/Docs/DeveloperGuide/sync.mdindex fbbec6f..26bb4bc 100644--- a/Docs/DeveloperGuide/sync.md+++ b/Docs/DeveloperGuide/sync.md@@ -76,7 +76,7 @@ zone 已确认状态和账户 salt 会在 actor 内跨同步轮次缓存,省同步只有在以下条件全部成立时运行:- 用户打开 CloudKit 同步-- Hook 已启用并校验通过+- `CodexHookSettings.isEnabled` 为 `true`,历史同步可继续消费已落盘聚合- 当前 iCloud 账户可用- 本地聚合服务可用@@ -129,18 +129,18 @@ salt 存在同一个 private custom zone 中。多台设备先后创建时通过## 一次同步的阶段```text-确认 iCloud 账户+读取本地同步状态-> 创建或确认 custom zone-> 读取账户 salt 并解析设备 pseudonym- -> 读取本地同步状态和缓存+ -> 按设备身份和 schema 更新本地状态+ -> 拉取远端变更到缓存,处理待替换日期-> 上传当前设备变化日期- -> 拉取远端变更- -> 更新本地 CloudKit 缓存+ -> 再次拉取远端变更到缓存-> 清理超过保留期的记录- -> 发布合并结果+ -> 保存状态并发布合并结果```-实际顺序刻意在上传前先拉取:+上传前后的拉取各有用途:- 上传前知道远端是否已经有同设备同日记录,才能选择更新、新建 generation 记录或跳过- replacement 前必须先全量拉取,才能找到增量缓存可能遗漏的旧 generation@@ -150,11 +150,11 @@ salt 存在同一个 private custom zone 中。多台设备先后创建时通过每个阶段都写入日志中的 `stage`,失败信息因此能回答问题发生在 zone, device, fetch, upload 还是 prune,而不只得到一个笼统的 CloudKit error:- 上传每批最多 25 条记录-- 单批操作最长等待 20 秒+- 每轮上传按 20 秒预算决定是否启动下一批- 拉取单页最多 200 条变更- 本地内容使用 SHA-256 hash 跳过未改变记录-20 秒是整轮上传预算,不是每条记录的超时。达到预算后剩余日期保留为未确认状态,后续调度继续处理。这样一次历史 backfill 不会长时间占用 actor 和用户可见刷新链路。+上传循环在每批开始前检查 20 秒预算。已开始的批次继续等待结果;预算耗尽后,剩余日期留到后续同步处理。每个日期的稳定 JSON 只编码并 hash 一次,同一结果同时用于筛选和成功确认。如果在不同阶段重新编码,字典顺序或可选字段差异可能让“是否改变”判断自行漂移。@@ -204,8 +204,6 @@ CloudKit record schema 演进时,旧记录可能没有新计数字段。`nil`## 来源替换与重建-Hook 原始文件被替换或完整重建时,聚合层会改变 source generation。同步层必须把这个变化解释为替换,不能把新旧代际相加。-用户执行重新扫描时:1. 本地聚合从原始 JSONL 重建diff --git a/Docs/UserGuide/README.md b/Docs/UserGuide/README.mdindex 38edc0a..2fb4325 100644--- a/Docs/UserGuide/README.md+++ b/Docs/UserGuide/README.md@@ -19,7 +19,7 @@- 只想查看账户和额度,从 [安装与快速开始](getting-started.md) 开始- 想看正在运行或等待批准的任务,阅读 [实时任务与 CodexBar Hook](activity-and-hook.md)-- 想在重置次数到期前自动重置额度,阅读 [设置参考](settings.md#自动重置)+- 想在留存重置到期前自动重置额度,阅读 [设置参考](settings.md#自动重置)- 想在长任务期间阻止 Mac 睡眠,阅读 [防止系统睡眠](sleep-prevention.md)- 想知道某个开关是否会上传数据,阅读 [数据、同步与隐私](sync-data-privacy.md)- 已经遇到错误提示,直接进入 [常见问题与排查](troubleshooting.md)diff --git a/Docs/UserGuide/activity-and-hook.md b/Docs/UserGuide/activity-and-hook.mdindex 62a4043..0735cd0 100644--- a/Docs/UserGuide/activity-and-hook.md+++ b/Docs/UserGuide/activity-and-hook.md@@ -28,7 +28,7 @@ CodexBar Hook 会在 Codex 的关键事件发生时记录少量结构化字段版本检查以当前已连接 app-server 的握手版本为准,不是磁盘上刚安装的版本。-更新 Codex 后如果仍提示版本过低,在“设置 > 关于”中点击“刷新连接”。+更新 Codex 后如果仍提示版本过低,在“设置 > 关于”中点击“重新建立连接”。## 开启方法diff --git a/Docs/UserGuide/getting-started.md b/Docs/UserGuide/getting-started.mdindex 4cae031..b76bf48 100644--- a/Docs/UserGuide/getting-started.md+++ b/Docs/UserGuide/getting-started.md@@ -51,7 +51,7 @@ CodexBar 每 60 秒自动刷新一次账户、额度和 Token 用量,双击主| 双击账户邮箱 | 切换邮箱模糊显示 || 悬停热力图方块 | 查看当天 Token 和 Hook 统计 || 点击活动卡片 | 打开并发任务中心 |-| 点击手动重置次数 | 查看各批次过期时间 |+| 点击 `留存重置` | 查看各批次过期时间 || `设置 > 高级 > 自动重置` | 配置是否自动重置以及提前量 |全局快捷键优先在鼠标所在屏幕打开主面板,菜单栏锚点不可用时会使用独立浮动面板。diff --git a/Docs/UserGuide/main-panel.md b/Docs/UserGuide/main-panel.mdindex 7aef6a4..804567e 100644--- a/Docs/UserGuide/main-panel.md+++ b/Docs/UserGuide/main-panel.md@@ -54,10 +54,10 @@ CodexBar 会展示 Codex 返回的全部额度分组和窗口。主额度分组还可能展示以下信息:- 可用积分或无限积分状态-- 可用手动重置次数-- 每批重置次数的过期时间+- 可用留存重置+- 每批留存重置的过期时间-点击手动重置次数可以打开详情面板,只有 Codex 返回可用次数时才会显示这个入口。+点击 `留存重置` 可查看各批次的过期时间,入口只在可用次数大于 `0` 时显示。## Token 用量与热力图diff --git a/Docs/UserGuide/notifications.md b/Docs/UserGuide/notifications.mdindex a5752f0..c477a55 100644--- a/Docs/UserGuide/notifications.md+++ b/Docs/UserGuide/notifications.md@@ -21,7 +21,7 @@| 任务等待 | 任务进入等待用户批准状态 | 开启 | CodexBar Hook || 额度预警 | 可信额度首次跌到阈值或以下 | 开启,10% | 无 || 额度重置 | 已观察到消耗的额度窗口回到未消耗状态 | 开启 | 无 |-| 重置临期 | 手动重置次数进入过期前 7 天窗口 | 开启 | 存在可用重置次数 |+| 重置临期 | 留存重置进入过期前 7 天窗口 | 开启 | 存在可用留存重置 || 自动重置 | 自动重置明确返回成功或此前已成功 | 开启 | 自动重置开关、通知子开关和通知总开关 || 自动重置失败 | 认证失败导致暂停、协议错误导致停止,或本机明确观察到过期 | 与成功通知共用设置 | 自动重置开关、通知子开关和通知总开关 || 低电量保护 | 低电量保护成功恢复系统睡眠 | 开启 | 防睡眠和低电量保护 |@@ -45,7 +45,7 @@同一额度重置周期内,退出并重新启动 CodexBar 也不会重复发送额度预警。-手动重置次数会在过期前 7, 6, 5, 4, 3, 2 和 1 天分别判断是否需要提醒。+留存重置会在过期前 7, 6, 5, 4, 3, 2 和 1 天分别判断是否需要提醒。## 自动重置通知diff --git a/Docs/UserGuide/settings.md b/Docs/UserGuide/settings.mdindex 1da4486..6bf0011 100644--- a/Docs/UserGuide/settings.md+++ b/Docs/UserGuide/settings.md@@ -51,7 +51,7 @@| --- | --- | --- || CodexBar Hook | 安装并校验 Codex 事件 handler | 未安装时关闭 || 系统通知 | 控制 CodexBar 本地通知和任务触觉反馈 | 关闭 |-| 自动重置 | 按所选提前量在过期前使用尚未消费的重置次数重置 Codex 额度 | 关闭,提前 30 分钟 |+| 自动重置 | 按所选提前量使用即将过期的留存重置 | 关闭,提前 30 分钟 || 防止系统睡眠 | 根据实时 Codex 任务自动切换系统睡眠 | 关闭 || 跨设备同步 | 通过 iCloud 同步每日 Hook 聚合 | 关闭 || 重建数据 | 从所选日期的本机原始事件重新生成聚合 | 手动操作 |@@ -72,7 +72,7 @@| 任务等待通知 | 开启 | 需要 CodexBar Hook || 额度预警通知 | 开启,10% | 阈值可选 5%, 10%, 25% || 额度重置通知 | 开启 | 只在观察到消耗后识别重置 |-| 重置临期通知 | 开启 | 提醒 7 天内到期的手动重置次数 |+| 重置临期通知 | 开启 | 提醒 7 天内到期的留存重置 || 自动重置通知 | 开启 | 只有自动重置开启时可用,成功和失败共用音效 || 低电量保护通知 | 开启 | 只有低电量保护实际可用时生效 || 防睡眠上限通知 | 开启 | 只有最长时间不是无限制时生效 |@@ -106,7 +106,7 @@自动重置开关已开启且 CodexBarHelper 已安装并获得系统批准时,主开关行右侧显示选项按钮。点击后可在侧边面板的“临期时间”中选择到期前 `15 分钟`、`30 分钟`、`1 小时`、`2 小时`、`4 小时` 或 `6 小时` 开始尝试,默认是 `30 分钟`。Helper 状态不满足条件时入口隐藏,已展开的自动重置面板会关闭。-- 只处理 app-server 最新响应明确列出的可用重置次数+- 只处理 app-server 最新响应明确列出的可用留存重置- 每次使用前重新确认账号、凭证状态和过期时间- 同一时间只处理最早到期的一次- 确认开启后会尝试注册 CodexBarHelper;即使“防止系统睡眠”关闭,也可能需要在“登录项与扩展”中批准 CodexBar 后台运行@@ -116,7 +116,7 @@- 系统自然唤醒或 App 下次启动时仍会立即补检;已经进入临期窗口且尚未过期时补试,否则按临期时间重新安排- 只有已经读到具体凭证和过期时间时才会安排重试唤醒;每轮连续重试最多持续 5 分钟,后续普通额度刷新仍可重新尝试- 当前没有可重置额度时不会消费次数,并会在本轮 5 分钟窗口内继续使用同一幂等键重试-- 服务端更新同一重置次数的过期时间后,会保留其幂等身份并按新时间重新安排+- 服务端更新同一留存重置的过期时间后,会保留其幂等身份并按新时间重新安排- 认证失效或确定的协议错误会暂停或停止当前任务,并在通知设置允许时通过系统通知说明多台 Mac 同时开启时,每台设备独立调度,但会为相同 `creditId` 生成相同幂等键。最先成功的设备完成消费;其他设备收到已成功结果后停止,或者在刷新时发现凭证已经消失并静默停止。@@ -166,7 +166,7 @@| 项目 | 作用 || --- | --- || 来源 | 位于 Codex 版本标题右侧,保留自动选项,按检测结果展示已安装的 Codex CLI 或 Codex APP |-| 刷新连接 | 点击来源选择器右侧的圆形箭头,按所选来源重新建立连接,使用磁盘上已安装的版本 |+| 重新建立连接 | 点击来源选择器右侧的连接图标,按所选来源和磁盘上已安装的版本建立新连接 || Codex CLI | 展示全局 Codex CLI 的磁盘版本和路径 || Codex APP | 展示 ChatGPT App 或 Codex App 内置 CLI 的磁盘版本和路径 || 当前使用 | 标记当前 app-server 实际使用的 Codex 来源和运行版本 |@@ -182,9 +182,9 @@来源默认为自动,优先使用 CLI,未安装 CLI 时使用 App 内置 Codex。来源选项只展示检测到的安装来源。版本行通常只展示已安装来源;当前、已选或刷新失败的来源被卸载后,保留该行并以“不可用”替换“当前使用”,不再在底部重复显示来源不可用提示。此标记表示无法从该来源建立新连接,不代表旧连接已经停止。切换来源后立即建立新连接,成功后保存选择,失败时保留原连接和原选择。之前手动指定的来源被卸载后,选择器显示“选择来源”,不会自动改用其他来源。-自动重连仍然保留:连接使用满 1 小时后,在下一次请求时按所选来源重建。也可以点击“刷新连接”提前使用更新后的版本。旧版 CodexBar 会忽略来源选择,沿用原有自动规则。+自动重连仍然保留:连接使用满 1 小时后,在下一次请求时按所选来源重建。也可以点击“重新建立连接”提前使用更新后的版本。旧版 CodexBar 会忽略来源选择,沿用原有自动规则。-悬停圆形箭头可查看“刷新连接”提示。重连期间,箭头持续旋转,来源选择器和重连按钮暂时不可操作;成功后更新“当前使用”标记,来源缺失时显示“不可用”,其他失败在版本区域底部显示原因。+悬停连接图标可查看“重新建立连接”提示,重连时显示“正在重新连接”。重连及后续刷新期间,图标持续播放动画,来源选择器和重连按钮暂时不可操作。成功后更新“当前使用”标记,来源缺失时显示“不可用”,其他失败在版本区域底部显示原因。点击可执行文件路径可以复制完整路径。diff --git a/Docs/UserGuide/sync-data-privacy.md b/Docs/UserGuide/sync-data-privacy.mdindex adf874d..766b0e8 100644--- a/Docs/UserGuide/sync-data-privacy.md+++ b/Docs/UserGuide/sync-data-privacy.md@@ -4,7 +4,7 @@## 跨设备同步的内容-跨设备同步用于合并多台 Mac 的每日 Hook 聚合,不同步账户、额度、Token 用量、重置次数或自动重置设置。+跨设备同步用于合并多台 Mac 的每日 Hook 聚合,不同步账户、额度、Token 用量、留存重置或自动重置设置。启用条件如下:@@ -70,7 +70,7 @@CodexBarHelper 所有权文件由 root 持有,用于 App 或 CodexBarHelper 异常退出后的睡眠状态恢复。-自动重置唤醒计划不包含账户、重置次数、`creditId` 或幂等键。CodexBarHelper 启动时会清理同一构建身份遗留的计划,App 也会在任务变化、功能关闭和正常退出时取消计划。+自动重置唤醒计划不包含账户、留存重置、`creditId` 或幂等键。CodexBarHelper 启动时会清理同一构建身份遗留的计划,App 也会在任务变化、功能关闭和正常退出时取消计划。匿名任务不参与异常会话保护,因此不会生成哈希任务标识或写入保护状态文件。@@ -96,7 +96,7 @@ CodexBarHelper 所有权文件由 root 持有,用于 App 或 CodexBarHelper- 完整工作目录路径- prompt、Codex 回复、工具参数或工具输出- Codex 账户、额度和 Token 用量-- 重置次数明细、自动重置设置和消费状态+- 留存重置明细、自动重置设置和消费状态- app-server 交互日志- 异常会话保护记录- Codex 认证 token@@ -107,13 +107,13 @@ CodexBarHelper 所有权文件由 root 持有,用于 App 或 CodexBarHelperCodexBar 会读取以下本机数据:-- 通过本机 app-server 获取账户、额度、Token 用量、手动重置次数明细和 Codex 配置+- 通过本机 app-server 获取账户、额度、Token 用量、留存重置明细和 Codex 配置- 读取 Hook 原始事件以生成统计和实时任务- 读取 Hook model 字段和本机 Codex rollout 的首条来源及生命周期字段,以排除 Auto-review 实时任务、区分完成与终止并补充进展时间来源判定优先使用 rollout 元数据;rollout 来源为 `unknown` 时,只有精确匹配 `codex-auto-review` 的 Hook model 才归类为 `autoReview`。rollout 来源读取最多 256 KiB,只保存 `main`, `autoReview`, `auxiliary` 或 `unknown` 四种归一化结果。CodexBar 不保存 rollout 路径或原始来源值;其他 rollout 读取也只提取生命周期、时间和推理强度等字段,不展示或保存会话正文和工具内容。-用户主动开启自动重置后,CodexBar 通过同一个本机 app-server 使用明确列出的临期重置次数。原始 `creditId` 和幂等键不写入磁盘或 CloudKit;`UserDefaults` 只保存功能开关、提前量、自动重置通知开关、音效选择和哈希后的通知去重键。+用户主动开启自动重置后,CodexBar 通过同一个本机 app-server 使用明确列出的临期留存重置。原始 `creditId` 和幂等键不写入磁盘或 CloudKit;`UserDefaults` 只保存功能开关、提前量、自动重置通知开关、音效选择和哈希后的通知去重键。CodexBar 不复制或持久化 Codex 认证 token。@@ -124,7 +124,7 @@ CodexBar 不复制或持久化 Codex 认证 token。| Sparkle 更新源 | 检查并安装 CodexBar 更新 | 自动检查开启或用户手动检查时 || CloudKit private database | 同步多设备每日 Hook 聚合 | 用户开启跨设备同步时 |-账户、额度、Token 用量、手动重置次数明细和用户开启的自动重置操作通过本机 app-server 的 stdio 通信完成。自动重置不会增加 CloudKit 请求;自动重置只向 CodexBarHelper 提交固定系统唤醒计划的时间,不提交账户或重置次数数据。+账户、额度、Token 用量、留存重置明细和用户开启的自动重置操作通过本机 app-server 的 stdio 通信完成。自动重置不会增加 CloudKit 请求;自动重置只向 CodexBarHelper 提交固定系统唤醒计划的时间,不提交账户或留存重置数据。## 日志隐私diff --git a/Docs/UserGuide/troubleshooting.md b/Docs/UserGuide/troubleshooting.mdindex b6903c4..9dc55e5 100644--- a/Docs/UserGuide/troubleshooting.md+++ b/Docs/UserGuide/troubleshooting.md@@ -41,7 +41,7 @@| 提示 | 含义 | 建议处理 || --- | --- | --- |-| 需要更高 Codex 版本 | 当前 app-server 版本不足 | 更新 Codex 后在关于页面点击“刷新连接” |+| 需要更高 Codex 版本 | 当前 app-server 版本不足 | 更新 Codex 后在关于页面点击“重新建立连接” || Codex Hook 已全局关闭 | `features.hooks` 已禁用 | 在 Codex 配置中重新启用 Hooks || CodexBar Hook 已不完整 | 至少一个必要事件缺少当前 handler | 重新打开设置触发自动补齐,仍未恢复时关闭后重新开启 Hook || CodexBar Hook 未被信任 | Codex 仍把 handler 判定为未信任或已修改 | 重新开启 Hook 并检查 Codex 配置 |@@ -105,7 +105,7 @@ CodexBar 会在启动、打开菜单和每轮额度刷新完成后自动补齐1. `自动重置` 是否开启,提前量是否符合预期2. 自动重置设置行是否提示 CodexBarHelper 待批准、未注册或唤醒计划失败;临期选项按钮只在 Helper 已获得系统批准时显示-3. 当前 app-server 是否返回了具体的可用重置次数和过期时间+3. 当前 app-server 是否返回了具体的可用留存重置和过期时间4. 计划时间到达后,网络与 Codex 登录状态是否可用5. “自动重置通知”是否开启;通知关闭不会阻止自动重置本身执行@@ -131,7 +131,7 @@ pmset -g sched当前版本来自已经运行的 app-server 握手,磁盘版本来自重新执行 Codex `--version`-如果关于页面显示新安装版本但 `当前使用` 仍是旧版本,点击“刷新连接”。也可以等待当前连接满 1 小时后的下一次请求自动重建。+如果关于页面显示新安装版本但 `当前使用` 仍是旧版本,点击“重新建立连接”。也可以等待当前连接满 1 小时后的下一次请求自动重建。## 使用日志窗口diff --git a/Docs/en/DeveloperGuide/app-server.md b/Docs/en/DeveloperGuide/app-server.mdindex 62ef0ee..4efe9ab 100644--- a/Docs/en/DeveloperGuide/app-server.md+++ b/Docs/en/DeveloperGuide/app-server.md@@ -79,7 +79,7 @@ The resolver normalizes in three layers:2. Preserve the existing `PATH`, then append common directories in order and deduplicate3. Resolve symlinks and standardized URLs for candidates so one bundled binary is not identified as both global and bundled-Preferring the global CLI is an explicit product choice. A CLI deliberately installed by a developer generally represents the intended version; a bundled CLI is a fallback when no global version exists.+`CodexCLISourceSelection.automatic` prefers the global CLI and falls back to the bundled CLI when none is found. Selecting `global` or `bundled` uses only that source and returns `sourceUnavailable` if it is missing. `CodexStatusService` saves the selection and reuses it when rebuilding the connection.### Why On-Disk and Running Versions Are Separate@@ -308,6 +308,8 @@ Rate-limit ordering is also centralized in the model:## Reset Credits+The UI labels the available count “Banked Resets” or “留存重置”, using the localization key `banked-reset.count`. The protocol field remains `rateLimitResetCredits`.+`rateLimitResetCredits` from `account/rateLimits/read` provides both an available count and optional details:- `availableCount` is the authoritative totaldiff --git a/Docs/en/DeveloperGuide/data-and-privacy.md b/Docs/en/DeveloperGuide/data-and-privacy.mdindex 95ea947..2a62af0 100644--- a/Docs/en/DeveloperGuide/data-and-privacy.md+++ b/Docs/en/DeveloperGuide/data-and-privacy.md@@ -295,7 +295,7 @@ Do not hide unavailable data behind friendly-looking defaults:| --- | --- | --- || Field missing from an older source | `nil` or unavailable | Decode as an explicit zero || app-server cache expired | Stale snapshot | Continue triggering notifications |-| Rollout reader unavailable | Pause live evaluation | Use old tasks to continue sleep prevention |+| Rollout supplemental read unavailable | Retain existing Hook task state and continue polling for lifecycle updates | Treat a missing rollout result as a task ending || CloudKit offline | Preserve old cache with source attribution | Treat it as new data for the current account || Battery read failed | Preserve prior decision and mark unreadable | Treat as no battery |diff --git a/Docs/en/DeveloperGuide/hook-and-aggregation.md b/Docs/en/DeveloperGuide/hook-and-aggregation.mdindex 86e0908..bf65ee1 100644--- a/Docs/en/DeveloperGuide/hook-and-aggregation.md+++ b/Docs/en/DeveloperGuide/hook-and-aggregation.md@@ -135,7 +135,7 @@ Removal skips structurally malformed sibling entries instead of failing the enti### Generations for Asynchronous Settings Operations-The user may toggle Hook quickly, and app activation also triggers validation. `CodexHookSettings` increments `updateGeneration` and cancels the old task for every operation.+When the user toggles Hook or validation is triggered, `CodexHookSettings` starts the operation through `updateCoordinator`. Its `RefreshTaskCoordinator` advances the generation and cancels the previous task.After every file write or RPC `await`, it checks the generation again. Even if an old operation cannot truly be canceled, it cannot overwrite the latest switch state or error.diff --git a/Docs/en/DeveloperGuide/notifications.md b/Docs/en/DeveloperGuide/notifications.mdindex 0f6aa79..00e3aac 100644--- a/Docs/en/DeveloperGuide/notifications.md+++ b/Docs/en/DeveloperGuide/notifications.md@@ -44,7 +44,7 @@ Different notifications require different evidence:| Automatic Reset | app-server mutation result | Only an explicit result proves that this Mac performed the automatic action || Task completion | Monitor transition | Historical terminal snapshots must not replay || Waiting for approval | Monitor transition plus current snapshot | Notify on new waiting state, then withdraw stale notifications |-| Stalled Task Protection | Committed protection result | Must describe a task that has already been hidden |+| Stalled Task Protection | A relevant candidate that has reached the silence threshold | Revalidate before notification submission and before hiding || Sleep prevention stopped | Confirmed system-restoration result | Must not announce success before restoration |Inferring task completion from a current snapshot looks simpler, but every app launch would treat historical completed tasks as new events. Conversely, one transition alone cannot identify a low-rate-limit case when the app starts after the threshold was crossed.@@ -83,7 +83,7 @@ While the master switch is off, CodexBar neither requests system notification pe| Low-battery stop | KeepAlive restoration result | Independent category switch, enabled only when protection is available || Keep-awake limit | KeepAlive restoration result | Independent category switch, enabled only for a finite duration |-Stalled Task Protection has no independent notification switch. It follows Prevent System Sleep, then the notification master switch after protection occurs. Preferences for low-battery and duration-limit notifications are retained, but the UI displays them off and disabled when their protection conditions are unavailable, without changing persisted preferences.+Stalled Task Protection follows Prevent System Sleep. Its notifications require the master switch and system authorization, with no separate category switch. Low-battery and duration-limit notification preferences are retained while their controls appear off and disabled when the corresponding protection is unavailable.## Rate-Limit Reset@@ -209,15 +209,11 @@ Relevance checks both before and after submission cover the asynchronous window.## Stalled Task Protection-When a non-anonymous task reaches its silence threshold, Activity Protection first saves a protection record and hides the task, then requests a notification. Anonymous tasks never become protection candidates and cannot create protection notifications.+When a non-anonymous running task reaches its silence threshold, Activity Protection records the candidate and starts notification submission alongside a 3-second grace period. When notification handling returns or the grace period expires, the monitor revalidates the candidate and hides the task if it remains relevant. Protection proceeds even if notification submission fails.-The notification service checks again before submission that the task remains protected. New progress during the 3-second grace period cancels the stale notification.+The notification identifier uses `taskID + attemptID`. Checks before and after submission compare progress generation and silence duration. New progress invalidates the protection attempt and withdraws its notification.-Protection notifications always use the default sound rather than the task-completion category sound. A failed notification does not undo protection that already completed.--The notification identifier uses `taskID + attemptID`; relevance also compares progress generation and silence duration. When the task progresses during the 3-second grace period, the monitor invalidates the protection attempt and requests withdrawal.--These notifications have an explicit `retryCount` of 0. Protection results are time-sensitive, and a retry after immediate failure may no longer be relevant. General notifications may retry once; a protection notification prefers omission over a late false alert.+Protection notifications use the system default sound and a `retryCount` of `0` to avoid retrying an obsolete candidate.## Sleep Prevention Stoppeddiff --git a/Docs/en/DeveloperGuide/sync.md b/Docs/en/DeveloperGuide/sync.mdindex 5ff0773..74b3149 100644--- a/Docs/en/DeveloperGuide/sync.md+++ b/Docs/en/DeveloperGuide/sync.md@@ -76,7 +76,7 @@ Confirmed zone state and the account salt are cached in the actor across sync cySync runs only when all conditions hold:- The user enabled CloudKit sync-- Hook is enabled and validated+- `CodexHookSettings.isEnabled` is `true`; historical sync can consume aggregates already stored locally- The current iCloud account is available- The local aggregation service is available@@ -129,18 +129,18 @@ For complete boundaries, see [Data and Privacy Boundaries](data-and-privacy.md).## One Sync Cycle```text-Confirm iCloud account+Read local sync state-> Create or confirm custom zone-> Read account salt and resolve device pseudonym- -> Read local sync state and cache+ -> Update local state for the device identity and schema+ -> Fetch remote changes into the cache and process replacement dates-> Upload changed dates for this device- -> Fetch remote changes- -> Update the local CloudKit cache+ -> Fetch remote changes into the cache again-> Prune records outside retention- -> Publish merged results+ -> Save state and publish merged results```-The implementation intentionally performs a fetch before upload:+The fetches before and after upload serve different purposes:- Before uploading, it must know whether a same-device, same-day remote record exists so it can update, create a generation record, or skip- Before replacement, it must perform a full fetch to discover old generations that an incremental cache may have missed@@ -150,11 +150,11 @@ The implementation intentionally performs a fetch before upload:Every stage writes a `stage` field to logs, so an error identifies zone, device, fetch, upload, or prune instead of reporting only a generic CloudKit error:- Upload batches contain at most 25 records-- One batch waits at most 20 seconds+- Each upload cycle uses a 20-second budget to decide whether to start another batch- A fetch page contains at most 200 changes- SHA-256 hashes of local content skip unchanged records-The 20 seconds is a budget for the complete upload cycle, not a per-record timeout. After the budget is reached, remaining dates stay unconfirmed for a later schedule. A historical backfill therefore does not occupy the actor and user-visible refresh path indefinitely.+The upload loop checks its 20-second budget before each batch. A batch already in progress continues waiting for its result. Once the budget is exhausted, remaining dates wait for a later sync.Stable JSON for each date is encoded and hashed once, and the same result drives filtering and success confirmation. Re-encoding in different phases could let dictionary order or optional fields make change detection drift.@@ -204,8 +204,6 @@ Preserving availability during merge lets the UI distinguish “all devices tota## Source Replacement and Rebuild-When a raw Hook file is replaced or fully rebuilt, the aggregation layer changes its source generation. Sync must interpret this as replacement rather than adding old and new generations.-When the user requests a rescan:1. Local aggregation rebuilds from raw JSONLdiff --git a/Docs/en/UserGuide/README.md b/Docs/en/UserGuide/README.mdindex 80d7b2a..f613b93 100644--- a/Docs/en/UserGuide/README.md+++ b/Docs/en/UserGuide/README.md@@ -19,7 +19,7 @@- To view only your account and rate limits, start with [Installation and Quick Start](getting-started.md)- To follow running tasks or tasks waiting for approval, read [Live Tasks and CodexBar Hook](activity-and-hook.md)-- To reset your rate limit automatically before reset credits expire, see [Automatic Reset](settings.md#automatic-reset)+- To reset your rate limit automatically before banked resets expire, see [Automatic Reset](settings.md#automatic-reset)- To keep your Mac awake during long tasks, read [Preventing System Sleep](sleep-prevention.md)- To find out whether a setting uploads data, read [Data, Sync, and Privacy](sync-data-privacy.md)- If you already see an error, go directly to [Troubleshooting](troubleshooting.md)diff --git a/Docs/en/UserGuide/activity-and-hook.md b/Docs/en/UserGuide/activity-and-hook.mdindex 85c74c7..723d98f 100644--- a/Docs/en/UserGuide/activity-and-hook.md+++ b/Docs/en/UserGuide/activity-and-hook.md@@ -28,7 +28,7 @@ Before enabling CodexBar Hook, make sure that:The version check uses the handshake version from the connected app-server, not a newly installed version on disk.-If CodexBar still reports an older version after you update Codex, click Refresh Connection under Settings > About.+If CodexBar still reports an older version after you update Codex, click Reconnect under Settings > About.## Enabling the Hookdiff --git a/Docs/en/UserGuide/getting-started.md b/Docs/en/UserGuide/getting-started.mdindex da359b8..b21387c 100644--- a/Docs/en/UserGuide/getting-started.md+++ b/Docs/en/UserGuide/getting-started.md@@ -51,7 +51,7 @@ CodexBar refreshes account, rate-limit, and token usage data every 60 seconds. D| Double-click the account email | Toggle email blurring || Hover over a heatmap cell | View token and Hook metrics for that day || Click the activity card | Open Task Center for concurrent tasks |-| Click the reset-credit count | View the expiration time of each credit batch |+| Click `Banked Resets` | View the expiration time of each batch || `Settings > Advanced > Automatic Reset` | Configure automatic use and lead time |The global shortcut opens the main panel on the screen under the pointer when possible. If the menu bar anchor is unavailable, CodexBar uses a standalone floating panel.diff --git a/Docs/en/UserGuide/main-panel.md b/Docs/en/UserGuide/main-panel.mdindex c05d40a..2fc3839 100644--- a/Docs/en/UserGuide/main-panel.md+++ b/Docs/en/UserGuide/main-panel.md@@ -54,10 +54,10 @@ When `Animation Effects` is enabled, each segmented progress bar fills from zeroThe primary rate-limit group may also show:- Available credits or unlimited-credit status-- Available reset credits-- The expiration time for each batch of reset credits+- Available banked resets+- The expiration time for each batch of banked resets-Click the reset-credit count to open its details. This entry appears only when Codex reports available reset credits.+Click `Banked Resets` to view expiration times by batch. The entry appears when the available count is greater than `0`.## Token Usage and Heatmapdiff --git a/Docs/en/UserGuide/notifications.md b/Docs/en/UserGuide/notifications.mdindex 6b5a75f..3ec6efc 100644--- a/Docs/en/UserGuide/notifications.md+++ b/Docs/en/UserGuide/notifications.md@@ -21,7 +21,7 @@ System Notifications is off by default. Turning it off disables all CodexBar sys| Waiting for approval | A task starts waiting for user approval | On | CodexBar Hook || Low rate limit | A trusted rate limit reaches or crosses the threshold for the first time | On, 10% | None || Rate limit reset | A rate-limit window previously observed as consumed returns to an unconsumed state | On | None |-| Reset credits expiring | Reset credits enter the 7-day expiration window | On | Available reset credits |+| Banked resets expiring | Banked resets enter the 7-day expiration window | On | Available banked resets || Automatic Reset | An automatic reset explicitly returns success or reports that it already succeeded | On | Automatic Reset, its notification option, and System Notifications || Automatic Reset failed | Authentication failure pauses the task, a protocol error stops it, or this Mac explicitly observes expiration | Shares the success-notification setting | Automatic Reset, its notification option, and System Notifications || Low Battery Protection | Low Battery Protection successfully restores system sleep | On | Sleep prevention and Low Battery Protection |@@ -45,7 +45,7 @@ A low-rate-limit alert fires only when the remaining percentage moves from aboveRestarting CodexBar does not repeat the alert within the same rate-limit reset cycle.-Reset credits are checked for reminders at 7, 6, 5, 4, 3, 2, and 1 day before expiration.+Banked resets are checked for reminders at 7, 6, 5, 4, 3, 2, and 1 day before expiration.## Automatic Reset Notificationsdiff --git a/Docs/en/UserGuide/settings.md b/Docs/en/UserGuide/settings.mdindex f7a5320..a33f496 100644--- a/Docs/en/UserGuide/settings.md+++ b/Docs/en/UserGuide/settings.md@@ -51,7 +51,7 @@ Hiding a section affects only the main-panel presentation. It does not stop rate| --- | --- | --- || CodexBar Hook | Installs and validates the Codex event handler | Off when not installed || System Notifications | Controls CodexBar local notifications and task haptic feedback | Off |-| Automatic Reset | Uses unredeemed reset credits at the selected lead time before expiration | Off; 30 minutes early |+| Automatic Reset | Uses banked resets at the selected lead time before expiration | Off; 30 minutes early || Prevent System Sleep | Manages system sleep automatically based on live Codex tasks | Off || Sync Across Devices | Syncs daily Hook aggregations through iCloud | Off || Rebuild Data | Regenerates aggregations from local raw events for selected dates | Manual action |@@ -72,7 +72,7 @@ See [Live Tasks and CodexBar Hook](activity-and-hook.md) for details.| Approval Requests | On | Requires CodexBar Hook || Low Quota | On, 10% | Threshold: 5%, 10%, or 25% || Quota Reset | On | Recognized only after consumption has been observed |-| Reset Expiration | On | Alerts for reset credits expiring within 7 days |+| Reset Expiration | On | Alerts for banked resets expiring within 7 days || Automatic Reset Notifications | On | Available only while Automatic Reset is enabled; success and failure share one sound || Low Battery Alert | On | Applies only when Low Battery Protection is available || Keep-Awake Limit | On | Applies only when the maximum duration is not unlimited |@@ -106,7 +106,7 @@ Selecting `Enable` saves your intent and attempts to register CodexBarHelper. SeWhen Automatic Reset is enabled and CodexBarHelper is installed and approved, an options button appears on the right side of the main row. Open it to choose a `Time Before Expiration` of `15 Minutes`, `30 Minutes`, `1 Hour`, `2 Hours`, `4 Hours`, or `6 Hours`; the default is `30 Minutes`. The entry is hidden if the Helper state no longer qualifies, and any open Automatic Reset side panel closes.-- Processes only available reset credits explicitly listed in the latest app-server response+- Processes only available banked resets explicitly listed in the latest app-server response- Revalidates the account, credit state, and expiration time before every use- Processes only the earliest-expiring credit at a time- Attempts to register CodexBarHelper after confirmation; even if Prevent System Sleep is off, CodexBar may need approval to run in the background under Login Items & Extensions@@ -166,7 +166,7 @@ See [Data, Sync, and Privacy](sync-data-privacy.md) for details.| Item | Purpose || --- | --- || Source | Located beside the Codex Versions heading; Automatic is always available, while Codex CLI and Codex APP appear only when detected as installed |-| Refresh Connection | The circular arrow next to the source selector establishes a new connection using the selected source and its installed version |+| Reconnect | The connector icon next to the source selector establishes a new connection using the selected source and its installed version || Codex CLI | Shows the on-disk version and path of the global Codex CLI || Codex APP | Shows the on-disk version and path of the CLI bundled with ChatGPT App or Codex App || In Use | Identifies the Codex source and running app-server version currently in use |@@ -182,9 +182,9 @@ Update hints share the semantic version parser used by minimum-version checks: aThe default source is Automatic, which prefers CLI and uses the app's bundled Codex when CLI is not installed. Source options only show detected installations. Version rows normally show installed sources; if the current, selected, or failed refresh source is uninstalled, its row remains with Unavailable replacing In Use, without a duplicate source-unavailable message below. This badge means a new connection cannot be opened from that source, not that the old connection has stopped. Changing the source connects immediately and saves the choice only after success. Failure preserves the previous connection and choice. If a previously selected source is uninstalled, the picker shows “Select Source” without falling back to another source.-Automatic reconnection remains enabled: once a connection is one hour old, the next request rebuilds it using the selected source. Refresh Connection applies an installed update sooner. Older CodexBar versions ignore the source preference and retain their original automatic selection behavior.+Automatic reconnection remains enabled: once a connection is one hour old, the next request rebuilds it using the selected source. Reconnect applies an installed update sooner. Older CodexBar versions ignore the source preference and retain their original automatic selection behavior.-Hover over the circular arrow to see Refresh Connection. While reconnecting, the arrow rotates continuously, and both controls are temporarily disabled. Success updates In Use; a missing source shows Unavailable, while other failures display a reason below the version rows.+Hover over the connector icon to see “Reconnect”; the tooltip changes to “Reconnecting” while connecting. The icon keeps animating through reconnection and the following refresh, while both controls remain disabled. Success updates In Use; a missing source shows Unavailable, while other failures display a reason below the version rows.Click an executable path to copy the full path.diff --git a/Docs/en/UserGuide/sync-data-privacy.md b/Docs/en/UserGuide/sync-data-privacy.mdindex 3f4ca76..6f7629a 100644--- a/Docs/en/UserGuide/sync-data-privacy.md+++ b/Docs/en/UserGuide/sync-data-privacy.md@@ -4,7 +4,7 @@## What Cross-Device Sync Includes-Cross-device sync merges daily Hook aggregations from multiple Macs. It does not sync account data, rate limits, token usage, reset credits, or Automatic Reset settings.+Cross-device sync merges daily Hook aggregations from multiple Macs. It does not sync account data, rate limits, token usage, banked resets, or Automatic Reset settings.It requires:@@ -70,7 +70,7 @@ Daily aggregations retain lists of session and turn IDs only for the latest 3 daThe CodexBarHelper ownership file is owned by root and is used to recover sleep state after an unexpected CodexBar or CodexBarHelper exit.-The Automatic Reset wake schedule contains no account data, reset credits, `creditId`, or idempotency key. CodexBarHelper removes schedules left by the same build identity when it starts. The app also cancels schedules when tasks change, the feature is disabled, or the app exits normally.+The Automatic Reset wake schedule contains no account data, banked resets, `creditId`, or idempotency key. CodexBarHelper removes schedules left by the same build identity when it starts. The app also cancels schedules when tasks change, the feature is disabled, or the app exits normally.Anonymous tasks do not participate in Stalled Task Protection, so they do not create hashed task identifiers or write to the protection-state file.@@ -96,7 +96,7 @@ The pseudonymous device identifier is derived from the device UUID and a random- Full working-directory paths- Prompts, Codex responses, tool arguments, or tool output- Codex account, rate-limit, or token usage data-- Reset-credit details, Automatic Reset settings, or redemption state+- Banked reset details, Automatic Reset settings, or redemption state- app-server interaction logs- Stalled Task Protection records- Codex authentication tokens@@ -107,13 +107,13 @@ Project display names and model names are synced. Do not enable cross-device synCodexBar reads the following local data:-- Account, rate-limit, token usage, reset-credit details, and Codex configuration through the local app-server+- Account, rate-limit, token usage, banked reset details, and Codex configuration through the local app-server- Raw Hook events to generate metrics and live tasks- Hook model fields and the first origin and lifecycle fields from local Codex rollout files to exclude Auto-review live tasks, distinguish completion from termination, and supplement progress timestampsOrigin classification prefers rollout metadata. When rollout origin is `unknown`, only an exact `codex-auto-review` Hook model match classifies the event as `autoReview`. Origin reading is limited to 256 KiB and stores only the normalized result `main`, `autoReview`, `auxiliary`, or `unknown`. CodexBar does not store rollout paths or raw source values; other rollout reads likewise extract only lifecycle, time, reasoning-effort, and similar fields and never display or store conversation text or tool content.-After you explicitly enable Automatic Reset, CodexBar uses reset credits that the same local app-server explicitly reports as near expiration. Raw `creditId` and idempotency keys are not written to disk or CloudKit. `UserDefaults` stores only the feature switch, lead time, notification switch, sound choice, and hashed notification-deduplication keys.+After you explicitly enable Automatic Reset, CodexBar uses banked resets that the same local app-server explicitly reports as near expiration. Raw `creditId` and idempotency keys are not written to disk or CloudKit. `UserDefaults` stores only the feature switch, lead time, notification switch, sound choice, and hashed notification-deduplication keys.CodexBar does not copy or persist Codex authentication tokens.@@ -124,7 +124,7 @@ CodexBar does not copy or persist Codex authentication tokens.| Sparkle update feed | Check for and install CodexBar updates | Automatic checking is enabled or you check manually || CloudKit private database | Sync daily Hook aggregations across devices | You enable cross-device sync |-Account data, rate limits, token usage, reset-credit details, and user-enabled Automatic Reset actions all use stdio communication with the local app-server. Automatic Reset does not add CloudKit requests. It sends CodexBarHelper only the time for a fixed system wake schedule, never account or reset-credit data.+Account data, rate limits, token usage, banked reset details, and user-enabled Automatic Reset actions all use stdio communication with the local app-server. Automatic Reset does not add CloudKit requests. It sends CodexBarHelper only the time for a fixed system wake schedule, never account or banked reset data.## Log Privacydiff --git a/Docs/en/UserGuide/troubleshooting.md b/Docs/en/UserGuide/troubleshooting.mdindex 41adebd..d6dd37a 100644--- a/Docs/en/UserGuide/troubleshooting.md+++ b/Docs/en/UserGuide/troubleshooting.md@@ -41,7 +41,7 @@ Double-click the account icon to retry. If the values remain dimmed, check `acco| Message | Meaning | Recommended action || --- | --- | --- |-| A newer Codex version is required | The current app-server version is too old | Update Codex, then click Refresh Connection on the About page |+| A newer Codex version is required | The current app-server version is too old | Update Codex, then click Reconnect on the About page || Codex Hook is disabled globally | `features.hooks` is disabled | Re-enable Hooks in the Codex configuration || CodexBar Hook is incomplete | At least one required event is missing the current handler | Reopen Settings to trigger automatic repair; if it still fails, turn Hook off and on again || CodexBar Hook is not trusted | Codex still considers the handler untrusted or modified | Re-enable the Hook and inspect the Codex configuration |@@ -105,7 +105,7 @@ Check in this order:1. `Automatic Reset` is enabled and its lead time is what you expect2. The Automatic Reset row does not report pending CodexBarHelper approval, missing registration, or wake-schedule failure; the lead-time options appear only after the Helper is approved-3. The current app-server response includes a specific available reset credit and expiration time+3. The current app-server response includes a specific available banked reset and expiration time4. Network access and Codex sign-in were available at the scheduled time5. `Automatic Reset Notifications` is enabled if you expected a notification; disabling notifications does not stop Automatic Reset itself@@ -131,7 +131,7 @@ A sync failure does not delete local Hook data. A later maintenance run retriesThe current version comes from the running app-server handshake. The on-disk version comes from running Codex `--version` again.-If About shows the new installed version but `In Use` still shows the old one, click Refresh Connection. Alternatively, the next request after the connection is one hour old rebuilds it automatically.+If About shows the new installed version but `In Use` still shows the old one, click Reconnect. Alternatively, the next request after the connection is one hour old rebuilds it automatically.## Using the Logs Windowdiff --git a/README.en.md b/README.en.mdindex 563ba03..af52678 100644--- a/README.en.md+++ b/README.en.md@@ -31,8 +31,8 @@ It can notify you when a task finishes, needs approval, or when your rate limits- View your current Codex account and plan- See every rate-limit window, its remaining allowance, and reset time-- Check available credits and reset credits-- Automatically use reset credits from 15 minutes to 6 hours before they expire, with a default lead time of 30 minutes; CodexBar can wake your Mac at the scheduled time and revalidate availability before use+- Check available credits and banked resets+- Automatically use banked resets from 15 minutes to 6 hours before they expire, with a default lead time of 30 minutes; CodexBar can wake your Mac at the scheduled time and revalidate availability before use- Show a selected rate-limit window directly beside the menu bar icon### Understand your Codex usagediff --git a/README.md b/README.mdindex 74234bf..24087f7 100644--- a/README.md+++ b/README.md@@ -31,8 +31,8 @@ CodexBar 是面向 macOS 15 及更高版本的菜单栏 App, 用于集中展示- 展示当前 Codex 账户和套餐- 展示全部额度窗口, 剩余比例和重置时间-- 展示可用积分和手动重置次数-- 支持自动重置,可设置在手动重置次数过期前 15 分钟到 6 小时执行,默认提前 30 分钟;计划到点时可唤醒 Mac,并在执行前重新确认可用状态+- 展示可用积分和留存重置+- 支持自动重置,可设置在留存重置过期前 15 分钟到 6 小时执行,默认提前 30 分钟;计划到点时可唤醒 Mac,并在执行前重新确认可用状态- 可在菜单栏图标旁直接显示所选额度窗口### 看见自己的 Codex 使用节奏diff --git a/appcast.xml b/appcast.xmlindex eb61d06..54130ad 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.16</title>+ <sparkle:version>83</sparkle:version>+ <sparkle:shortVersionString>3.6.16</sparkle:shortVersionString>+ <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>+ <sparkle:releaseNotesLink>https://codexbar.zabrian.app/notes#3.6.16</sparkle:releaseNotesLink>+ <pubDate>Sat, 05 Sep 2026 16:42:13 +0800</pubDate>+ <enclosure url="https://codexbar.zabrian.app/download/CodexBar-v3.6.16.dmg" sparkle:edSignature="n0bUA1ZSWByBAo23Jv7eHCRcg2vX/lNIfIpwy1AkJD7Y2GBDljHTYWaJdcp7U03d0cNTXEdP9QYHJdGxjyRIDw==" length="7722960" type="application/octet-stream"/>+ </item><item><title>CodexBar.app 3.6.15</title><sparkle:version>82</sparkle:version>