CodexBar 是一个 macOS 菜单栏应用,用于查看本机 Codex 账号状态、额度、Token 用量、详细统计信息
Swift appkitcodexcodex-clideveloper-toolsmacosmacos-appmenu-bar-appopenai-codexproductivityswiftswiftuiusage-tracker
feat: 更新额度重置与同步状态
Bob7274bbc75beb
diff --git a/AGENTS.md b/AGENTS.mdindex b18dc77..1eb9ce0 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -131,6 +131,7 @@ Hook 统计的配置、存储、保留策略和统计口径见 [Docs/CodexHook.m- 优先读取 `rateLimitsByLimitId`; 为空时回退顶层 `rateLimits`。- 顶层 `rateLimits.limitId` 指向的主 limit 置顶, 缺省 `"codex"`。- 其余 limit 按 `limitName ?? limitId` 做 localized standard 排序, 再按 `limitId` 稳定排序。+- `rateLimitResetCredits.availableCount` 读入 `resetCreditsAvailableCount`; 缺失时为 `nil`。- `primary` / `secondary` 合成 `[QuotaWindow]`; 没有窗口的 limit 被过滤。- `QuotaWindow.remainingPercent = clamp(100 - usedPercent, 0...100)`; 无 `usedPercent` 视为无数据。- `windowDurationMins` 标签: 整天 `ND`, 整小时 `NH`, 否则 `NM`, 缺失或非正数为「额度」。@@ -177,18 +178,20 @@ Hook 统计的配置、存储、保留策略和统计口径见 [Docs/CodexHook.m- `LiquidGlassStyle.swift` 是自绘玻璃效果, 不是 macOS 原生 `.glassEffect`; 没有明确设计要求时不要切换。- 账号图标双击触发刷新。邮箱文本双击切换模糊。- 计划名是右侧加粗纯文字; `planBadgeTint(for:)` 优先级: enterprise -> team/business -> pro -> plus -> edu -> free -> 默认 cyan。+- `resetCreditsAvailableCount` 有值时, 只在置顶主 limit 标题右侧显示 `重置 xN`。- 额度条展示剩余百分比, 固定为 50 个胶囊, 每个胶囊宽 `3.5`, 间距 `2`, 高 `12`; 颜色按 20% 一档: 红、橙、黄、薄荷、绿。- 额度行标签列宽 `34`, 居中显示, 标签允许最小缩放到 `0.75`, 标签到额度条间距 `12`, 额度条到百分比间距 `8`, 百分比列宽 `37`, 百分比到重置时间最小间距 `6`, 重置时间列宽 `75`; 不通过加宽菜单面板解决额度行溢出。- 无 quota 数据时显示 `--` / `暂无数据`, 并使用占位色。- `rateLimits` 或 `usage` 使用旧缓存时, 对应区域通过 `.markStale(true)` 降低透明度到 0.55, 不降低饱和度; 下一轮对应接口成功后恢复正常透明度。- 重置时间格式是 `MM-dd HH:mm`, 使用等宽数字, 在额度行最右侧对齐。- 更新时间行显示倒计时圆环、「数据更新时间」和 `HH:mm:ss`。-- 更新时间行最右侧显示同步状态图标: 未开启为 `icloud.slash`, 已开启为空闲为 `icloud`, 正在同步为 `arrow.trianglehead.clockwise.icloud`, 同步失败为 `exclamationmark.icloud`; 失败态 tooltip 展示归类后的同步错误文案。+- 更新时间行最右侧显示同步状态图标: 只有 Codex Hook 开启、跨设备同步偏好开启且同步账号可用时才进入 active 同步态; 非 active 同步统一为 `icloud.slash`, tooltip 为「同步未开启」; active 空闲为 `icloud`, tooltip 显示 `最近同步: yyyy-MM-dd HH:mm:ss`, 时间来源和设置页「最近同步」一致, 没有成功上传记录时显示「暂无同步记录」; active 同步中为 `arrow.trianglehead.clockwise.icloud`; active 同步失败为 `exclamationmark.icloud`, tooltip 展示归类后的同步错误文案。- 倒计时只在菜单面板可见时用 `TimelineView` 每秒 tick; 普通 tick 不做连续动画, 仅刷新起点变化时播放恢复动画。- token 区域显示「单日峰值」和「全时累计」; `TokenCountText` 对 1K 以下显示完整整数, 1K 起显示 K/M/B。- token 区域还显示「当前连胜」、「最长连胜」和「最长任务」。- 热力图是近 30 周、30 列 x 7 行、周日到周六排列; Codex Hook 开启时包含今天, Hook 关闭时仅在 app-server 已返回当天 token bucket 时包含今天。- 热力图 hover 使用 `HeatmapDetailPanelController` 展示侧边详情面板, 不是菜单面板内 tooltip; 面板作为菜单面板 child window, 不接收鼠标事件, 左右贴边展示并在屏幕可见区域内夹紧。+- 详情面板内容更新时保留 `NSPanel` / `NSHostingController`, 但每次替换 `hostingController.rootView` 并同步 `setContentSize`; 不用常驻 `ObservableObject` model 推送 hover context, 避免 Hook 开关切换 token-only / workflow 布局后触发 AppKit 递归布局。- Hook 关闭时详情面板显示日期、token 数和「用量强度」分段条, 尺寸 `212 x 84`。- Hook 开启时详情面板首行左侧显示日期、右侧显示 token 数, 当天 token 数显示 `--`; 后续显示「用量强度」、「会话总数」、「对话轮次」、「子智能体」、「工具调用」、「权限请求」、「上下文压缩」, 尺寸 `212 x 189`。- 「用量强度」前置圆点固定为蓝色, 不随用量强度变化。diff --git a/CodexBar.xcodeproj/project.pbxproj b/CodexBar.xcodeproj/project.pbxprojindex b971098..1de4748 100644--- a/CodexBar.xcodeproj/project.pbxproj+++ b/CodexBar.xcodeproj/project.pbxproj@@ -97,7 +97,7 @@attributes = {BuildIndependentTargetsInParallel = 1;LastSwiftUpdateCheck = 2650;- LastUpgradeCheck = 2650;+ LastUpgradeCheck = 2660;TargetAttributes = {C4A0FD942FD9302E000263A7 = {CreatedOnToolsVersion = 26.5;@@ -181,6 +181,7 @@CLANG_WARN_UNREACHABLE_CODE = YES;CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;COPY_PHASE_STRIP = NO;+ DEAD_CODE_STRIPPING = YES;DEBUG_INFORMATION_FORMAT = dwarf;DEVELOPMENT_TEAM = 4KJ362VJW5;ENABLE_STRICT_OBJC_MSGSEND = YES;@@ -206,6 +207,7 @@MTL_FAST_MATH = YES;ONLY_ACTIVE_ARCH = YES;SDKROOT = macosx;+ STRING_CATALOG_GENERATE_SYMBOLS = YES;SWIFT_ACTIVE_COMPILATION_CONDITIONS = "DEBUG $(inherited)";SWIFT_OPTIMIZATION_LEVEL = "-Onone";SWIFT_VERSION = 6.0;@@ -246,6 +248,7 @@CLANG_WARN_UNREACHABLE_CODE = YES;CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;COPY_PHASE_STRIP = NO;+ DEAD_CODE_STRIPPING = YES;DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";DEVELOPMENT_TEAM = 4KJ362VJW5;ENABLE_NS_ASSERTIONS = NO;@@ -264,6 +267,7 @@MTL_ENABLE_DEBUG_INFO = NO;MTL_FAST_MATH = YES;SDKROOT = macosx;+ STRING_CATALOG_GENERATE_SYMBOLS = YES;SWIFT_COMPILATION_MODE = wholemodule;SWIFT_VERSION = 6.0;};@@ -278,7 +282,8 @@"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";CODE_SIGN_STYLE = Automatic;COMBINE_HIDPI_IMAGES = YES;- CURRENT_PROJECT_VERSION = 29;+ CURRENT_PROJECT_VERSION = 30;+ DEAD_CODE_STRIPPING = YES;DEVELOPMENT_TEAM = 4KJ362VJW5;ENABLE_APP_INTENTS_METADATA_GENERATION = NO;ENABLE_APP_SANDBOX = NO;@@ -293,7 +298,7 @@"$(inherited)","@executable_path/../Frameworks",);- MARKETING_VERSION = 3.2.1;+ MARKETING_VERSION = 3.2.2;PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar;PRODUCT_NAME = "$(TARGET_NAME)";REGISTER_APP_GROUPS = YES;@@ -316,7 +321,8 @@"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";CODE_SIGN_STYLE = Automatic;COMBINE_HIDPI_IMAGES = YES;- CURRENT_PROJECT_VERSION = 29;+ CURRENT_PROJECT_VERSION = 30;+ DEAD_CODE_STRIPPING = YES;DEVELOPMENT_TEAM = 4KJ362VJW5;ENABLE_APP_INTENTS_METADATA_GENERATION = NO;ENABLE_APP_SANDBOX = NO;@@ -331,7 +337,7 @@"$(inherited)","@executable_path/../Frameworks",);- MARKETING_VERSION = 3.2.1;+ MARKETING_VERSION = 3.2.2;PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar;PRODUCT_NAME = "$(TARGET_NAME)";PROVISIONING_PROFILE_SPECIFIER = "";diff --git a/CodexBar.xcodeproj/xcshareddata/xcschemes/CodexBar.xcscheme b/CodexBar.xcodeproj/xcshareddata/xcschemes/CodexBar.xcschemeindex 5e96fbb..7237ed6 100644--- a/CodexBar.xcodeproj/xcshareddata/xcschemes/CodexBar.xcscheme+++ b/CodexBar.xcodeproj/xcshareddata/xcschemes/CodexBar.xcscheme@@ -1,6 +1,6 @@<?xml version="1.0" encoding="UTF-8"?><Scheme- LastUpgradeVersion = "2650"+ LastUpgradeVersion = "2660"version = "1.7"><BuildActionparallelizeBuildables = "YES"diff --git a/CodexBar/Controllers/HeatmapDetailPanelController.swift b/CodexBar/Controllers/HeatmapDetailPanelController.swiftindex 62c4be4..9e6d23a 100644--- a/CodexBar/Controllers/HeatmapDetailPanelController.swift+++ b/CodexBar/Controllers/HeatmapDetailPanelController.swift@@ -18,7 +18,6 @@ private final class DetailPanel: NSPanel {final class HeatmapDetailPanelController {private var panel: NSPanel?private var hostingController: NSHostingController<UsageHeatmapDayDetailView>?- private var detailModel: UsageHeatmapDayDetailModel?private var hideTask: Task<Void, Never>?private var currentSide = UsageHeatmapDetailSide.leftprivate var visibilityGeneration = 0@@ -319,21 +318,20 @@ final class HeatmapDetailPanelController {}private func updateContent(_ context: UsageHeatmapHoverContext) {- if let detailModel {- withAnimation(Animation.codexStatus) {- detailModel.context = context- }+ let rootView = UsageHeatmapDayDetailView(context: context)+ let size = UsageHeatmapDayDetailView.panelSize(showsWorkflow: context.showsWorkflow)++ if let hostingController {+ hostingController.rootView = rootView} else {- let detailModel = UsageHeatmapDayDetailModel(context: context)- let rootView = UsageHeatmapDayDetailView(model: detailModel)let hostingController = NSHostingController(rootView: rootView)hostingController.sizingOptions = [.preferredContentSize]panel?.contentViewController = hostingControllerself.hostingController = hostingController- self.detailModel = detailModel}configurePanelLayers()+ panel?.setContentSize(size)}private func configurePanelLayers() {diff --git a/CodexBar/Models/CodexQuotaModels.swift b/CodexBar/Models/CodexQuotaModels.swiftindex 7b2a6fe..58e587d 100644--- a/CodexBar/Models/CodexQuotaModels.swift+++ b/CodexBar/Models/CodexQuotaModels.swift@@ -4,6 +4,7 @@ import Foundationnonisolated struct CodexQuotaSnapshot: Equatable {let account: CodexAccountlet planType: String?+ let resetCreditsAvailableCount: Int?let generatedAt: Datelet limits: [CodexQuotaLimitSnapshot]let usage: CodexUsageSnapshot?@@ -104,6 +105,12 @@ nonisolated struct QuotaWindow: Equatable, Identifiable {nonisolated struct AccountRateLimitsResponse: Decodable {let rateLimits: RateLimitSnapshotlet rateLimitsByLimitId: [String: RateLimitSnapshot]?+ let rateLimitResetCredits: RateLimitResetCreditsSummary?+}++/// app-server 返回的可用额度重置次数+nonisolated struct RateLimitResetCreditsSummary: Decodable {+ let availableCount: Int}/// app-server 返回的单个 limit, primary/secondary 可能独立缺失@@ -156,6 +163,7 @@ nonisolated extension CodexQuotaSnapshot {self.init(account: account,planType: rateLimitsResponse?.rateLimits.planType,+ resetCreditsAvailableCount: rateLimitsResponse?.rateLimitResetCredits?.availableCount,generatedAt: generatedAt,limits: limits,usage: usage,diff --git a/CodexBar/Views/Menu/CodexStatusMenuSections.swift b/CodexBar/Views/Menu/CodexStatusMenuSections.swiftindex a47b2d2..26092ce 100644--- a/CodexBar/Views/Menu/CodexStatusMenuSections.swift+++ b/CodexBar/Views/Menu/CodexStatusMenuSections.swift@@ -136,16 +136,17 @@ struct EmptyDataPanel: View {/// 多个 limit 的额度区, 使用 stale 透明度标记缓存回退数据struct QuotaLimitsSection: View {let limits: [CodexQuotaLimitSnapshot]+ let resetCreditsAvailableCount: Int?let isStale: Boolvar body: some View {VStack(alignment: .leading, spacing: 8) {ForEach(limits) { limit in- if limit.id != limits.first?.id {+ if !isPrimaryLimit(limit) {LiquidGlassDivider()}- quotaLimitSection(limit)+ quotaLimitSection(limit, showsResetCredits: isPrimaryLimit(limit))}}.markStale(isStale)@@ -153,13 +154,25 @@ struct QuotaLimitsSection: View {.liquidGlassSurface(cornerRadius: MenuMetrics.panelCornerRadius)}- private func quotaLimitSection(_ limit: CodexQuotaLimitSnapshot) -> some View {+ private func quotaLimitSection(_ limit: CodexQuotaLimitSnapshot, showsResetCredits: Bool) -> some View {VStack(alignment: .leading, spacing: 6) {- Text(limit.title)- .font(.caption.weight(.semibold))- .foregroundStyle(.primary)- .lineLimit(1)- .truncationMode(.middle)+ HStack(spacing: 8) {+ Text(limit.title)+ .font(.caption.weight(.semibold))+ .foregroundStyle(.primary)+ .lineLimit(1)+ .truncationMode(.middle)++ Spacer(minLength: 8)++ if showsResetCredits, let resetCreditsText {+ Text(resetCreditsText)+ .font(.caption2.weight(.semibold))+ .foregroundStyle(.secondary)+ .lineLimit(1)+ .fixedSize(horizontal: true, vertical: false)+ }+ }VStack(spacing: 8) {ForEach(limit.windows) { window in@@ -168,6 +181,18 @@ struct QuotaLimitsSection: View {}}}++ private var primaryLimitId: CodexQuotaLimitSnapshot.ID? {+ limits.first?.id+ }++ private var resetCreditsText: String? {+ resetCreditsAvailableCount.map { "重置 x\($0)" }+ }++ private func isPrimaryLimit(_ limit: CodexQuotaLimitSnapshot) -> Bool {+ limit.id == primaryLimitId+ }}/// 底部更新时间行, 同时承载 Sparkle 被动更新提示@@ -249,15 +274,18 @@ struct WorkflowSyncDisplayState: Equatable {lhs.symbolName == rhs.symbolName && lhs.helpText == rhs.helpText}- init(settings: WorkflowSyncSettings) {- if !settings.isEnabled {+ init(isHookEnabled: Bool, settings: WorkflowSyncSettings) {+ guard isHookEnabled, settings.isEnabled, settings.isSyncAvailable else {self = .disabled- } else if settings.isSyncing {+ return+ }++ if settings.isSyncing {self = .syncing} else if settings.hasSyncFailure {self = .failed(message: settings.syncFailureMessage)} else {- self = .enabled+ self = .enabled(settings.lastUploadAtText)}}@@ -267,11 +295,13 @@ struct WorkflowSyncDisplayState: Equatable {self.helpText = helpText}- private static let enabled = WorkflowSyncDisplayState(- symbolName: "icloud",- tint: .codexSecondaryLabel,- helpText: "同步已开启"- )+ private static func enabled(_ lastSyncText: String?) -> WorkflowSyncDisplayState {+ WorkflowSyncDisplayState(+ symbolName: "icloud",+ tint: .codexSecondaryLabel,+ helpText: lastSyncText.map { "最近同步: \($0)" } ?? "暂无同步记录"+ )+ }private static let disabled = WorkflowSyncDisplayState(symbolName: "icloud.slash",diff --git a/CodexBar/Views/Menu/CodexStatusMenuView.swift b/CodexBar/Views/Menu/CodexStatusMenuView.swiftindex a664f21..c1840d2 100644--- a/CodexBar/Views/Menu/CodexStatusMenuView.swift+++ b/CodexBar/Views/Menu/CodexStatusMenuView.swift@@ -72,7 +72,11 @@ private extension CodexStatusMenuView {EmptyDataPanel()} else {if !snapshot.limits.isEmpty {- QuotaLimitsSection(limits: snapshot.limits, isStale: snapshot.isRateLimitsStale)+ QuotaLimitsSection(+ limits: snapshot.limits,+ resetCreditsAvailableCount: snapshot.resetCreditsAvailableCount,+ isStale: snapshot.isRateLimitsStale+ )}if let usage = snapshot.usage {@@ -98,7 +102,10 @@ private extension CodexStatusMenuView {countdownStartedAt: viewModel.autoRefreshCountdownStartedAt ?? snapshot.generatedAt,countdownInterval: viewModel.autoRefreshInterval,isCountdownActive: menuSurfaceVisibility.isVisible,- syncDisplayState: WorkflowSyncDisplayState(settings: syncSettings),+ syncDisplayState: WorkflowSyncDisplayState(+ isHookEnabled: codexHookSettings.isEnabled,+ settings: syncSettings+ ),updateMessage: appUpdater.panelUpdateMessage,startUpdate: appUpdater.startUpdate)diff --git a/CodexBar/Views/Menu/UsageHeatmap.swift b/CodexBar/Views/Menu/UsageHeatmap.swiftindex 2279e7a..48df7d8 100644--- a/CodexBar/Views/Menu/UsageHeatmap.swift+++ b/CodexBar/Views/Menu/UsageHeatmap.swift@@ -1,5 +1,4 @@import AppKit-import Combineimport SwiftUI/// hover 详情面板需要的完整上下文, 包括屏幕坐标和峰值 token@@ -549,48 +548,32 @@ private final class HeatmapScreenFrameReportingView: NSView {}}-/// 热力图 hover 详情内容, Hook 开启时额外展示工作流统计-@MainActor-final class UsageHeatmapDayDetailModel: ObservableObject {- @Published var context: UsageHeatmapHoverContext-- init(context: UsageHeatmapHoverContext) {- self.context = context- }-}-struct UsageHeatmapDayDetailView: View {- @ObservedObject var model: UsageHeatmapDayDetailModel+ let context: UsageHeatmapHoverContext@Environment(\.colorScheme) private var colorScheme- private var context: UsageHeatmapHoverContext {- model.context- }-var body: some View {let panelSize = Self.panelSize(showsWorkflow: context.showsWorkflow)- VStack(alignment: .leading, spacing: Metrics.sectionSpacing) {- detailContent- }- .padding(.horizontal, Metrics.horizontalPadding)- .padding(.vertical, Metrics.verticalPadding)- .frame(- width: panelSize.width,- height: panelSize.height,- alignment: .topLeading- )- .liquidGlassSurface(cornerRadius: Metrics.cornerRadius, isOuterSurface: true)- .background {- RoundedRectangle(cornerRadius: Metrics.cornerRadius, style: .continuous)- .fill(panelBackingFill)- }- .overlay {- RoundedRectangle(cornerRadius: Metrics.cornerRadius, style: .continuous)- .strokeBorder(panelBoundaryColor, lineWidth: Metrics.boundaryLineWidth)- }- .clipShape(RoundedRectangle(cornerRadius: Metrics.cornerRadius, style: .continuous))- .animation(Metrics.statusAnimation, value: context)+ detailContent+ .padding(.horizontal, Metrics.horizontalPadding)+ .padding(.vertical, Metrics.verticalPadding)+ .frame(+ width: panelSize.width,+ height: panelSize.height,+ alignment: .topLeading+ )+ .liquidGlassSurface(cornerRadius: Metrics.cornerRadius, isOuterSurface: true)+ .background {+ RoundedRectangle(cornerRadius: Metrics.cornerRadius, style: .continuous)+ .fill(panelBackingFill)+ }+ .overlay {+ RoundedRectangle(cornerRadius: Metrics.cornerRadius, style: .continuous)+ .strokeBorder(panelBoundaryColor, lineWidth: Metrics.boundaryLineWidth)+ }+ .clipShape(RoundedRectangle(cornerRadius: Metrics.cornerRadius, style: .continuous))+ .animation(Metrics.statusAnimation, value: context)}static var panelCornerRadius: CGFloat {@@ -614,12 +597,10 @@ struct UsageHeatmapDayDetailView: View {private var header: some View {HStack(alignment: .center, spacing: Metrics.headerSpacing) {- VStack(alignment: .leading, spacing: 4) {- dateText- .padding(.horizontal, 7)- .padding(.vertical, 3)- .liquidGlassCapsule(tint: .accentColor)- }+ dateText+ .padding(.horizontal, 7)+ .padding(.vertical, 3)+ .liquidGlassCapsule(tint: .accentColor)Spacer(minLength: 8)diff --git a/CodexBar/Views/Settings/AppSettingsView.swift b/CodexBar/Views/Settings/AppSettingsView.swiftindex b505204..4fe1ea2 100644--- a/CodexBar/Views/Settings/AppSettingsView.swift+++ b/CodexBar/Views/Settings/AppSettingsView.swift@@ -128,7 +128,7 @@ private extension AppSettingsView {var syncRow: some View {let state = syncRowState- let lastUploadAtText = syncSettings.lastUploadAtText+ let lastSyncText = syncSettings.lastUploadAtTextreturn VStack(alignment: .leading, spacing: 4) {SettingsToggleRow(@@ -151,9 +151,9 @@ private extension AppSettingsView {if let message = syncSettings.unavailableMessage {SettingsCaptionMessageRow(message: message)- } else if state.shouldShowUploadStatus(lastUploadAtText: lastUploadAtText) {+ } else if state.shouldShowSyncStatus(lastSyncText: lastSyncText) {SettingsIndentedRow {- Text("最近上传")+ Text("最近同步").font(.caption).foregroundStyle(.secondary)@@ -165,8 +165,8 @@ private extension AppSettingsView {.scaleEffect(0.7).frame(width: 16, height: 16).help("正在同步")- } else if let lastUploadAtText {- Text(lastUploadAtText)+ } else if let lastSyncText {+ Text(lastSyncText).font(.caption.monospacedDigit()).foregroundStyle(.secondary).lineLimit(1)@@ -294,7 +294,7 @@ private struct SyncRowState {isHookEnabled && !isHookUpdating && isSyncAvailable}- func shouldShowUploadStatus(lastUploadAtText: String?) -> Bool {- isActive && (isSyncing || lastUploadAtText != nil)+ func shouldShowSyncStatus(lastSyncText: String?) -> Bool {+ isActive && (isSyncing || lastSyncText != nil)}}diff --git a/Docs/AppServer.md b/Docs/AppServer.mdindex 964b63e..ca9aea6 100644--- a/Docs/AppServer.md+++ b/Docs/AppServer.md@@ -49,12 +49,18 @@ codex app-server --listen stdio://同一会话后续读取:- `account/read` 每轮复用连接时用 `refreshToken: false` 更新账户状态。-- `account/rateLimits/read` 读取额度。+- `account/rateLimits/read` 读取额度, 包括可选的 `rateLimitResetCredits.availableCount`。- `account/usage/read` 读取 `summary.lifetimeTokens`、`summary.peakDailyTokens`、`dailyUsageBuckets`。- `config/read` 在开启 Codex Hook 前读取有效配置,用于判断 `[features] hooks = false` 或兼容旧名 `codex_hooks = false` 是否禁用了 Hook;关闭清理时也读取 `hooks.state` 以保留其他 Hook 的信任状态。- `hooks/list` 在写入 Hook 后或设置页刷新时验证 Codex 实际识别到的 Hook,检查 `command`、`eventName`、`enabled`、`sourcePath`、`trustStatus`、`key`、`currentHash`、`warnings` 和 `errors`。- `config/batchWrite` 只用于写回 `hooks.state`:开启后把 CodexBar Hook 的 `key/currentHash` upsert 成 `trusted_hash`,关闭时移除对应 key。+`account/rateLimits/read` 的额度模型约定:++- `rateLimitsByLimitId` 优先于顶层 `rateLimits`; 为空时回退顶层 `rateLimits`。+- 顶层 `rateLimits.limitId` 指向主 limit, 缺省为 `codex`。+- `rateLimitResetCredits.availableCount` 是可用额度重置次数; 字段缺失时 UI 不显示重置次数。+认证失败时,同会话最多调用一次 `account/read(refreshToken:true)` 后重试原读取。## 错误处理diff --git a/Docs/CodexHook.md b/Docs/CodexHook.mdindex dd3cff3..578141d 100644--- a/Docs/CodexHook.md+++ b/Docs/CodexHook.md@@ -218,7 +218,7 @@ CloudKit 也按最近 210 天保留。每天第一次工作流刷新时,当前维护和同步请求由 `WorkflowSyncScheduler` 统一调度。菜单面板打开时只读取现有 `daily.jsonl` 和同步缓存;app-server 自动刷新倒计时重置、同步开关开启、Hook 重新开启或同步账号恢复可用时, 调度器合并维护/同步请求。同步中不会取消重启,冷却窗口内只保留一次待补跑请求,补跑前会重新校验 Hook、同步偏好和账号可用性。-同步失败不会清空开启偏好,也不会把原始 CloudKit 错误直接展示给用户。`WorkflowSyncService` 会把错误归类为「网络不可用」「账号不可用」「服务暂时不可用」「同步失败,请稍后重试」,并通过同步结束通知交给 `WorkflowSyncSettings`。主面板更新时间行最右侧使用 `exclamationmark.icloud` 进入失败态,tooltip 展示归类后的短错误;设置页只保留「同步不可用」、同步中和最近上传时间。+同步失败不会清空开启偏好,也不会把原始 CloudKit 错误直接展示给用户。`WorkflowSyncService` 会把错误归类为「网络不可用」「账号不可用」「服务暂时不可用」「同步失败,请稍后重试」,并通过同步结束通知交给 `WorkflowSyncSettings`。主面板更新时间行最右侧的同步图标先按 Codex Hook、跨设备同步偏好和同步账号可用性判断 active 同步态;非 active 同步统一显示 `icloud.slash` 和「同步未开启」。只有 active 同步态才继续区分空闲、同步中和失败;空闲态 tooltip 展示 `最近同步: yyyy-MM-dd HH:mm:ss`, 时间来源和设置页「最近同步」一致,没有成功上传记录时显示「暂无同步记录」;失败态使用 `exclamationmark.icloud`, tooltip 展示归类后的短错误。设置页只保留「同步不可用」、同步中和最近同步时间。## 统计口径@@ -301,6 +301,7 @@ UI 不直接展示所有原始字段,而是先生成 `WorkflowDailyMetrics`:- 最终位置会被夹在当前屏幕可见区域内, 屏幕边缘保留 `8` px- 与菜单面板之间保留 `4` px gap- 侧边切换使用抽屉动画: 收起 `0.12` 秒, 展开 `0.18` 秒+- 内容更新保留 `NSPanel` / `NSHostingController`, 但每次替换 `hostingController.rootView` 并同步 `setContentSize`; 不使用常驻 `ObservableObject` model 复用 SwiftUI 布局树, 避免 Hook 开关切换详情面板高度后触发 AppKit 递归布局Codex Hook 关闭时:diff --git a/Docs/CrossDeviceSync.md b/Docs/CrossDeviceSync.mdindex 82c53e4..72cb9b1 100644--- a/Docs/CrossDeviceSync.md+++ b/Docs/CrossDeviceSync.md@@ -23,17 +23,17 @@## 代码入口-| 文件 | 职责 |-| --- | --- |-| `CodexBar/Services/Settings/WorkflowSyncSettings.swift` | 设置页状态、同步账号可用性检查、UserDefaults 开关、最近上传时间、同步中和失败通知 |+| 文件 | 职责 |+| -------------------------------------------------------- | ---------------------------------------------------------------------------------- |+| `CodexBar/Services/Settings/WorkflowSyncSettings.swift` | 设置页状态、同步账号可用性检查、UserDefaults 开关、最近同步时间、同步中和失败通知 || `CodexBar/Services/Workflow/WorkflowSyncScheduler.swift` | 维护/同步任务的唯一调度者, 合并本机维护、CloudKit 同步请求、冷却窗口和最终状态校验 |-| `CodexBar/Services/Workflow/WorkflowSyncService.swift` | CloudKit 设备标识、上传、拉取、缓存、游标、清理过期记录 |-| `CodexBar/Services/Workflow/WorkflowService.swift` | 维护本机 daily,并在调度器允许时调用同步服务,把本机 daily 与同步缓存合并成快照 |-| `CodexBar/Models/CodexWorkflowModels.swift` | 本机聚合、云端脱敏聚合、云端缓存记录、最终 UI 快照的模型和合并规则 |-| `CodexBar/Views/Menu/CodexStatusMenuSections.swift` | 主面板更新时间行的同步状态图标和失败 tooltip |-| `CodexBar/Views/Settings/AppSettingsView.swift` | 设置页「跨设备同步」开关、`同步不可用`、同步中和最近上传时间展示 |-| `CodexBar/Controllers/SettingsWindowController.swift` | 打开设置窗口前刷新 Hook 和同步状态 |-| `CodexBar/Controllers/StatusItemController.swift` | 自动刷新时触发本机维护,并把同步开关、Hook 和同步可用性变化交给调度器 |+| `CodexBar/Services/Workflow/WorkflowSyncService.swift` | CloudKit 设备标识、上传、拉取、缓存、游标、清理过期记录 |+| `CodexBar/Services/Workflow/WorkflowService.swift` | 维护本机 daily,并在调度器允许时调用同步服务,把本机 daily 与同步缓存合并成快照 |+| `CodexBar/Models/CodexWorkflowModels.swift` | 本机聚合、云端脱敏聚合、云端缓存记录、最终 UI 快照的模型和合并规则 |+| `CodexBar/Views/Menu/CodexStatusMenuSections.swift` | 主面板更新时间行的同步状态图标、最近同步时间和失败 tooltip |+| `CodexBar/Views/Settings/AppSettingsView.swift` | 设置页「跨设备同步」开关、`同步不可用`、同步中和最近同步时间展示 |+| `CodexBar/Controllers/SettingsWindowController.swift` | 打开设置窗口前刷新 Hook 和同步状态 |+| `CodexBar/Controllers/StatusItemController.swift` | 自动刷新时触发本机维护,并把同步开关、Hook 和同步可用性变化交给调度器 |## 本地状态@@ -55,11 +55,11 @@ Sync/cursor.data各文件职责:-| 文件 | 内容 |-| --- | --- |-| `state.json` | 本机同步状态,包括 `deviceId`、每天上传过的 hash、`lastUploadAt`、`lastPrunedDate` |-| `cache.jsonl` | 从 iCloud 拉取到的其他设备脱敏 daily 记录,一行一条;不保存当前设备自己的云端副本 |-| `cursor.data` | CloudKit custom zone `CodexBarZone` 的 `CKServerChangeToken`,用于下次增量拉取 |+| 文件 | 内容 |+| ------------- | ---------------------------------------------------------------------------------- |+| `state.json` | 本机同步状态,包括 `deviceId`、每天上传过的 hash、`lastUploadAt`、`lastPrunedDate` |+| `cache.jsonl` | 从 iCloud 拉取到的其他设备脱敏 daily 记录,一行一条;不保存当前设备自己的云端副本 |+| `cursor.data` | CloudKit custom zone `CodexBarZone` 的 `CKServerChangeToken`,用于下次增量拉取 |`state.json` 的逻辑结构:@@ -77,9 +77,9 @@ Sync/cursor.data设置开关存在 `UserDefaults`:-| Key | 含义 |-| --- | --- |-| `WorkflowSync.isEnabled` | 用户是否开启过跨设备同步 |+| Key | 含义 |+| ---------------------------- | --------------------------------------- |+| `WorkflowSync.isEnabled` | 用户是否开启过跨设备同步 || `WorkflowSync.needsBackfill` | 是否需要对本机现有 daily 数据做一次补传 |关闭跨设备同步只会把 `WorkflowSync.isEnabled` 写成 `false`,不会删除本地 `state.json`、`cache.jsonl`、`cursor.data`,也不会删除 CloudKit 中已有记录。@@ -151,7 +151,7 @@ deviceId = HMAC_SHA256(accountSalt, IOPlatformUUID)- Codex Hook 本地配置状态- `hooks/list` 验证结果- CloudKit account status-- 最近上传时间+- 最近同步时间`AppSettingsView.onAppear` 和 App 再次变为 active 时也会刷新同步可用性。@@ -165,23 +165,23 @@ CKContainer.default().accountStatus == .availableUI 状态:-| 状态 | UI 表现 |-| --- | --- |-| 同步账号状态还在检查 | 开关不可操作,暂不显示错误 |-| 同步账号可用但 Hook 关闭 | 开关不可操作 |-| 同步账号不可用 | 开关不可操作,下方显示 `同步不可用` |-| Hook 开启且同步账号可用 | 开关可操作 |-| 同步中 | 开关下方显示 `最近上传` 和小型进度指示 |-| 有成功上传记录 | 开关下方显示 `最近上传 yyyy-MM-dd HH:mm:ss` |+| 状态 | UI 表现 |+| ------------------------ | ------------------------------------------- |+| 同步账号状态还在检查 | 开关不可操作,暂不显示错误 |+| 同步账号可用但 Hook 关闭 | 开关不可操作 |+| 同步账号不可用 | 开关不可操作,下方显示 `同步不可用` |+| Hook 开启且同步账号可用 | 开关可操作 |+| 同步中 | 开关下方显示 `最近同步` 和小型进度指示 |+| 有成功上传记录 | 开关下方显示 `最近同步 yyyy-MM-dd HH:mm:ss` |主面板「数据更新时间」行最右侧始终显示同步状态图标:-| 状态 | SF Symbol | tooltip |-| --- | --- | --- |-| 未开启同步 | `icloud.slash` | `同步未开启` |-| 已开启且空闲 | `icloud` | `同步已开启` |-| 已开启且正在同步 | `arrow.trianglehead.clockwise.icloud` | `正在同步` |-| 已开启且最近一次同步失败 | `exclamationmark.icloud` | 归类后的短错误, 例如 `网络不可用` |+| 状态 | SF Symbol | tooltip |+| ------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |+| 非 active 同步 | `icloud.slash` | `同步未开启`; 包括 Hook 关闭、同步偏好关闭、同步账号不可用或仍在检查 |+| active 且空闲 | `icloud` | 有成功上传记录时为 `最近同步: yyyy-MM-dd HH:mm:ss`, 没有记录时为 `暂无同步记录`; 时间来源和设置页「最近同步」一致 |+| active 且正在同步 | `arrow.trianglehead.clockwise.icloud` | `正在同步` |+| active 且最近一次同步失败 | `exclamationmark.icloud` | 归类后的短错误, 例如 `网络不可用` |开启时:@@ -208,11 +208,11 @@ WorkflowService.loadSnapshot(performMaintenance: true, synchronize: true)两类刷新行为不同:-| 刷新类型 | 是否维护 local daily | 是否访问 CloudKit | 用途 |-| --- | --- | --- | --- |-| `performMaintenance: false` | 否 | 否,只读取 `cache.jsonl` | 打开菜单面板时快速展示现有数据 |-| `performMaintenance: true, synchronize: false` | 是 | 否,只读取 `cache.jsonl` | 每分钟自动刷新中的本机统计维护 |-| `performMaintenance: true, synchronize: true` | 是 | 是 | 调度器允许后的 CloudKit 同步 |+| 刷新类型 | 是否维护 local daily | 是否访问 CloudKit | 用途 |+| ---------------------------------------------- | -------------------- | ------------------------ | ------------------------------ |+| `performMaintenance: false` | 否 | 否,只读取 `cache.jsonl` | 打开菜单面板时快速展示现有数据 |+| `performMaintenance: true, synchronize: false` | 是 | 否,只读取 `cache.jsonl` | 每分钟自动刷新中的本机统计维护 |+| `performMaintenance: true, synchronize: true` | 是 | 是 | 调度器允许后的 CloudKit 同步 |触发 CloudKit 同步请求:@@ -396,19 +396,19 @@ date < retentionCutoffDate失败处理以不中断工作流统计展示为目标。-| 场景 | 当前行为 |-| --- | --- |-| iCloud 未登录或不可用 | 设置页禁用「跨设备同步」,显示 `同步不可用`; 如果用户已开启同步, 主面板失败 tooltip 显示 `账号不可用` 或兜底错误 |-| 用户尝试在同步账号不可用时开启 | `setEnabled(true)` 直接返回,不写入开启状态 |-| `CodexBarZone` 不存在 | 同步开始时创建 custom zone |-| CloudKit 上传失败 | 本轮上传停止,已成功批次保留,失败日期下次刷新继续 |-| CloudKit 增量拉取失败 | 不写入日志窗口,尝试全量重建缓存 |-| CloudKit 全量重建失败 | 本轮同步失败,保存已有 state,保留已有 cache,后续刷新重试 |-| 账号 salt 创建冲突 | 重新读取 CloudKit 中已有 salt |-| 本地 state schema 不匹配 | 丢弃旧 state,按当前 schema 重新同步 |-| `deviceId` 变化 | 重置本地同步 state/cache/cursor,按当前 iCloud 账号重新同步 |-| `changeTokenExpired` | 不写入日志窗口,尝试全量重建缓存并建立新的 cursor |-| `cache.jsonl` 写入失败 | 不保存新 cursor,下一轮重新拉取同一批变化 |-| 同步失败 | `WorkflowSyncService` 捕获错误并归类为 `网络不可用`、`账号不可用`、`服务暂时不可用` 或 `同步失败,请稍后重试`; 主面板显示 `exclamationmark.icloud` 和短 tooltip, 设置页停止同步中状态且 `最近上传` 不更新 |+| 场景 | 当前行为 |+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| iCloud 未登录或不可用 | 设置页禁用「跨设备同步」,显示 `同步不可用`; 主面板同步图标走非 active 同步态, 显示 `icloud.slash` 和「同步未开启」 |+| 用户尝试在同步账号不可用时开启 | `setEnabled(true)` 直接返回,不写入开启状态 |+| `CodexBarZone` 不存在 | 同步开始时创建 custom zone |+| CloudKit 上传失败 | 本轮上传停止,已成功批次保留,失败日期下次刷新继续 |+| CloudKit 增量拉取失败 | 不写入日志窗口,尝试全量重建缓存 |+| CloudKit 全量重建失败 | 本轮同步失败,保存已有 state,保留已有 cache,后续刷新重试 |+| 账号 salt 创建冲突 | 重新读取 CloudKit 中已有 salt |+| 本地 state schema 不匹配 | 丢弃旧 state,按当前 schema 重新同步 |+| `deviceId` 变化 | 重置本地同步 state/cache/cursor,按当前 iCloud 账号重新同步 |+| `changeTokenExpired` | 不写入日志窗口,尝试全量重建缓存并建立新的 cursor |+| `cache.jsonl` 写入失败 | 不保存新 cursor,下一轮重新拉取同一批变化 |+| 同步失败 | `WorkflowSyncService` 捕获错误并归类为 `网络不可用`、`账号不可用`、`服务暂时不可用` 或 `同步失败,请稍后重试`; 主面板显示 `exclamationmark.icloud` 和短 tooltip, 设置页停止同步中状态且 `最近同步` 不更新 |同步异常不会清空用户的开启偏好。只要 `WorkflowSync.isEnabled` 仍为 true、Codex Hook 开启且同步账号可用,后续调度器允许的同步会继续重试。diff --git a/Docs/DevelopmentGuide.md b/Docs/DevelopmentGuide.mdindex 0aacb2a..d6bca6d 100644--- a/Docs/DevelopmentGuide.md+++ b/Docs/DevelopmentGuide.md@@ -410,28 +410,28 @@ app-server 与状态刷新错误:设置, Hook 和更新错误:-| 错误来源 | 检测位置 | 用户可见状态 | 重试或降级 |-| -------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------ |-| 登录项注册或取消失败 | `LoginItemSettings.setEnabled` | 设置窗口中部错误组显示"设置开机启动失败" | 调用 `refresh()` 恢复实际状态 |-| `config/read` 请求失败 | `CodexHookSettings.setEnabled` / app-server `config/read` | Hook 选项下方显示"设置 Codex Hook 失败" | 不写 `hooks.json`, 调用 `refresh()` 恢复实际状态 |-| Codex 全局配置禁用 Hook | `CodexHookSettings.setEnabled` / app-server `config/read` | Hook 开关保持关闭, Hook 选项下方显示禁用说明 | 不写 `hooks.json` |-| `hooks.json` 读取失败或结构非法 | `CodexHookSettings.refresh` | Hook 开关视为关闭, Hook 选项下方显示错误 | 不写配置 |-| Hook 开关写入失败 | `CodexHookSettings.setEnabled` | Hook 选项下方显示"设置 Codex Hook 失败" | 调用 `refresh()` 恢复实际状态 |-| `hooks/list` 请求失败 | `CodexHookSettings.verifyInstalledHooks` / app-server `hooks/list` | Hook 选项下方显示"无法验证 Codex Hook" | 保留已写入 Hook, 详细错误进入日志 |-| Hook 自动信任写入失败 | `CodexHookSettings.trustCodexBarHooks` / app-server `config/batchWrite` | Hook 选项下方显示"无法验证 Codex Hook" | 保留已写入 Hook, 详细错误进入日志 |-| Hook 写入后验证发现问题 | `CodexHookSettings.verifyInstalledHooks` / app-server `hooks/list` | Hook 选项下方显示最高优先级验证摘要 | 保留已写入 Hook, 详细响应进入日志 |-| 同步账号不可用 | `WorkflowSyncSettings.refreshSyncAvailability` / CloudKit account status | 跨设备同步开关禁用, 下方显示"同步不可用"; 已开启同步时主面板 tooltip 显示归类错误 | 不开启同步偏好写入 |-| CloudKit 同步上传或拉取失败 | `WorkflowSyncService.synchronizeIfEnabled` | 主面板更新时间行显示 `exclamationmark.icloud`, tooltip 显示归类错误, 最近上传时间不更新 | 保存已有 state, 下次刷新继续重试 |-| 快捷键无法识别或不符合规则 | `HotKeyRecorderRow` / `GlobalHotKeySettings.setShortcut` | 快捷键行内显示红色错误 | 用户清除后重新录制 |-| 快捷键注册冲突 | `StatusItemController.applyGlobalHotKey` | 快捷键行内显示占用提示 | 恢复上一个已注册快捷键 |-| Hook 子进程 payload 不是 JSON | `WorkflowHookEventRecorder.stdinPayload` | 无 UI 提示 | 吞掉本次 Hook, 避免启动完整菜单栏 App |-| Hook 子进程写入失败 | `WorkflowHookEventRecorder.handleIfRequested` | 无 UI 提示 | `try? record` 吞掉错误并正常退出, 避免阻断 Codex |-| `daily.jsonl` 缺失, 空文件或坏行 | `WorkflowService.prepareMaintenanceTasks` | 热力图详情面板可能暂时显示 0 | 标记 dirty, 后续从 events 文件重建 |-| events 文件变小或 offset 不一致 | `WorkflowService.reconcileEventFiles` | 热力图详情面板可能暂时显示旧聚合 | 标记 dirty, 从头重建当天聚合 |-| 单个维护任务失败 | `WorkflowService.performMaintenanceIfNeeded` | 使用已有 daily 或空 snapshot | 对应日期标记 dirty |-| Sparkle 配置缺失 | `AppUpdater.init` | 更新开关禁用, 操作显示"未配置更新资源" | 不创建 updater controller |-| 手动检查没有更新 | `updaterDidNotFindUpdate` | 显示"没有可用更新" | 1 秒后自动清理状态 |-| 手动检查失败 | `didAbortWithError` | 显示"检查更新失败" | 不展示底层错误细节 |+| 错误来源 | 检测位置 | 用户可见状态 | 重试或降级 |+| -------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------ |+| 登录项注册或取消失败 | `LoginItemSettings.setEnabled` | 设置窗口中部错误组显示"设置开机启动失败" | 调用 `refresh()` 恢复实际状态 |+| `config/read` 请求失败 | `CodexHookSettings.setEnabled` / app-server `config/read` | Hook 选项下方显示"设置 Codex Hook 失败" | 不写 `hooks.json`, 调用 `refresh()` 恢复实际状态 |+| Codex 全局配置禁用 Hook | `CodexHookSettings.setEnabled` / app-server `config/read` | Hook 开关保持关闭, Hook 选项下方显示禁用说明 | 不写 `hooks.json` |+| `hooks.json` 读取失败或结构非法 | `CodexHookSettings.refresh` | Hook 开关视为关闭, Hook 选项下方显示错误 | 不写配置 |+| Hook 开关写入失败 | `CodexHookSettings.setEnabled` | Hook 选项下方显示"设置 Codex Hook 失败" | 调用 `refresh()` 恢复实际状态 |+| `hooks/list` 请求失败 | `CodexHookSettings.verifyInstalledHooks` / app-server `hooks/list` | Hook 选项下方显示"无法验证 Codex Hook" | 保留已写入 Hook, 详细错误进入日志 |+| Hook 自动信任写入失败 | `CodexHookSettings.trustCodexBarHooks` / app-server `config/batchWrite` | Hook 选项下方显示"无法验证 Codex Hook" | 保留已写入 Hook, 详细错误进入日志 |+| Hook 写入后验证发现问题 | `CodexHookSettings.verifyInstalledHooks` / app-server `hooks/list` | Hook 选项下方显示最高优先级验证摘要 | 保留已写入 Hook, 详细响应进入日志 |+| 同步账号不可用 | `WorkflowSyncSettings.refreshSyncAvailability` / CloudKit account status | 跨设备同步开关禁用, 下方显示"同步不可用"; 主面板同步图标显示 `icloud.slash` 和"同步未开启" | 不开启同步偏好写入 |+| CloudKit 同步上传或拉取失败 | `WorkflowSyncService.synchronizeIfEnabled` | 主面板更新时间行显示 `exclamationmark.icloud`, tooltip 显示归类错误, 最近同步时间不更新 | 保存已有 state, 下次刷新继续重试 |+| 快捷键无法识别或不符合规则 | `HotKeyRecorderRow` / `GlobalHotKeySettings.setShortcut` | 快捷键行内显示红色错误 | 用户清除后重新录制 |+| 快捷键注册冲突 | `StatusItemController.applyGlobalHotKey` | 快捷键行内显示占用提示 | 恢复上一个已注册快捷键 |+| Hook 子进程 payload 不是 JSON | `WorkflowHookEventRecorder.stdinPayload` | 无 UI 提示 | 吞掉本次 Hook, 避免启动完整菜单栏 App |+| Hook 子进程写入失败 | `WorkflowHookEventRecorder.handleIfRequested` | 无 UI 提示 | `try? record` 吞掉错误并正常退出, 避免阻断 Codex |+| `daily.jsonl` 缺失, 空文件或坏行 | `WorkflowService.prepareMaintenanceTasks` | 热力图详情面板可能暂时显示 0 | 标记 dirty, 后续从 events 文件重建 |+| events 文件变小或 offset 不一致 | `WorkflowService.reconcileEventFiles` | 热力图详情面板可能暂时显示旧聚合 | 标记 dirty, 从头重建当天聚合 |+| 单个维护任务失败 | `WorkflowService.performMaintenanceIfNeeded` | 使用已有 daily 或空 snapshot | 对应日期标记 dirty |+| Sparkle 配置缺失 | `AppUpdater.init` | 更新开关禁用, 操作显示"未配置更新资源" | 不创建 updater controller |+| 手动检查没有更新 | `updaterDidNotFindUpdate` | 显示"没有可用更新" | 1 秒后自动清理状态 |+| 手动检查失败 | `didAbortWithError` | 显示"检查更新失败" | 不展示底层错误细节 |Codex 版本探测错误:@@ -469,6 +469,7 @@ Codex 版本探测错误:- 优先读取 `rateLimitsByLimitId`, 为空时回退顶层 `rateLimits`- 顶层 `rateLimits.limitId` 指向的主 limit 置顶, 缺省为 `codex`- 其他 limit 按 `limitName ?? limitId` localized standard 排序, 再按 `limitId` 稳定排序+- `rateLimitResetCredits.availableCount` 写入 `resetCreditsAvailableCount`, 缺失时不展示重置次数- 每个 limit 的 `primary` 和 `secondary` 合成 `[QuotaWindow]`- 没有窗口的 limit 被过滤- `remainingPercent = clamp(100 - usedPercent, 0...100)`@@ -527,6 +528,7 @@ flowchart TD额度区:- 多个 limit 间用 `LiquidGlassDivider` 分隔+- 如果 `resetCreditsAvailableCount` 有值, 只在置顶主 limit 标题右侧显示 `重置 xN`- 每个 quota window 展示标签, 50 个固定胶囊组成的电量条, 剩余百分比和重置时间- 胶囊宽度为 `3.5`, 间距为 `2`, 高度为 `12`- 额度行标签列宽 `34`, 居中显示, 标签允许最小缩放到 `0.75`, 标签到电量条间距 `12`, 电量条到百分比间距 `8`, 百分比列宽 `37`, 百分比到重置时间最小间距 `6`, 重置时间列宽 `75`@@ -544,6 +546,8 @@ flowchart TD热力图详情面板是菜单面板的 borderless nonactivating child panel, 不接收鼠标事件, 按悬停列优先显示在菜单面板左侧或右侧; 左右空间不足时尝试另一侧, 最终在当前屏幕可见区域内保留 8 px 边距。侧边切换时先以 0.12 秒抽屉动画收起, 再以 0.18 秒展开。+`HeatmapDetailPanelController` 会复用同一个 `NSPanel` 和 `NSHostingController`, 但每次 hover 内容变化时必须替换 `hostingController.rootView` 并同步 `setContentSize`。不要用常驻 `ObservableObject` model 持续推送 `UsageHeatmapHoverContext`; Hook 开关会让详情面板在 `212 x 84` 和 `212 x 189` 两种布局之间切换, 复用同一棵 SwiftUI 布局树容易触发 AppKit constraint/layout 递归。相关回归路径是: 先 hover 出详情面板, 打开设置切换 Hook, 再回到主面板 hover 热力图。+详情面板分两种:| Hook 状态 | 内容 | 尺寸 |@@ -561,8 +565,11 @@ Hook 开启且当天没有 token bucket 时, 今天的 token 数显示 `--`。- 菜单面板不可见时只渲染一次静态圆环- 普通 tick 不做连续动画, 只有刷新起点变化时播放 0.5 秒恢复动画- 如果 Sparkle 自动发现新版, 右侧显示 `panelUpdateMessage`, 双击该文本调用 `startUpdate()`-- 最右侧显示同步状态图标: 未开启 `icloud.slash`, 已开启空闲 `icloud`, 正在同步 `arrow.trianglehead.clockwise.icloud`, 最近一次同步失败 `exclamationmark.icloud`-- 同步失败 tooltip 不展示原始 CloudKit error, 只展示「网络不可用」「账号不可用」「服务暂时不可用」「同步失败,请稍后重试」这类归类文案+- 最右侧显示同步状态图标;只有 Codex Hook 开启、跨设备同步偏好开启且同步账号可用时, 主面板同步图标才进入 active 同步态+- 非 active 同步态显示 `icloud.slash`, tooltip 为「同步未开启」+- active 空闲态显示 `icloud`, tooltip 为 `最近同步: yyyy-MM-dd HH:mm:ss`, 使用 `WorkflowSyncSettings.lastUploadAtText`,和设置页「最近同步」时间口径一致;没有成功上传记录时显示「暂无同步记录」+- active 同步中显示 `arrow.trianglehead.clockwise.icloud`, tooltip 为「正在同步」+- active 同步失败显示 `exclamationmark.icloud`; tooltip 不展示原始 CloudKit error, 只展示「网络不可用」「账号不可用」「服务暂时不可用」「同步失败,请稍后重试」这类归类文案## 10. Codex Hook 开启后完整流程@@ -856,7 +863,7 @@ App 再次成为 active 时, 也会刷新 Codex 版本区、同步可用性, 并| 自动检查更新 | Sparkle updater | 设置 `automaticallyChecksForUpdates` || 使用快捷键 | `GlobalHotKeySettings.shortcut` | 写入 `UserDefaults` 并注册 hot key || 启用 Codex Hook | app-server `config/read` / `hooks/list` / `config/batchWrite`, `~/.codex/hooks.json` | 检查全局 Hook 开关后追加或移除当前 CodexBar command hook, 并维护对应 `hooks.state` 信任状态 |-| 跨设备同步 | `WorkflowSyncSettings` + CloudKit account status + `WorkflowSyncScheduler` | Hook 开启且同步账号可用时写入 `UserDefaults`; 开启时标记 `needsBackfill` 并请求调度同步 |+| 跨设备同步 | `WorkflowSyncSettings` + CloudKit account status + `WorkflowSyncScheduler` | Hook 开启且同步账号可用时写入 `UserDefaults`; 开启时标记 `needsBackfill` 并请求调度同步 || Codex 版本 | `CodexCLIVersionSnapshot` + 当前 app-server 握手信息 | 路径点击复制到剪贴板 || CodexBar 版本 | Bundle + AppUpdater 状态 | 有更新状态时优先显示动态消息 |diff --git a/appcast.xml b/appcast.xmlindex ab30193..bce6a3d 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.2.2</title>+ <sparkle:version>30</sparkle:version>+ <sparkle:shortVersionString>3.2.2</sparkle:shortVersionString>+ <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>+ <sparkle:releaseNotesLink>https://codexbar.zabrian.app/notes#3.2.2</sparkle:releaseNotesLink>+ <pubDate>Sun, 28 Jun 2026 11:37:15 +0800</pubDate>+ <enclosure url="https://codexbar.zabrian.app/download/CodexBar-v3.2.2.dmg" sparkle:edSignature="dqOKvzZ1wgiB/n2Vvkuve7F3eDFOZ2WEbXJaLxm7AmauIY/a/O7vPG0Y0jfhFO0cIZ1eUmLNx2EUJq6ANNGgBw==" length="3350670" type="application/octet-stream"/>+ </item><item><title>CodexBar.app 3.2.1</title><sparkle:version>29</sparkle:version>