Skip to content

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

feat: 更新额度重置与同步状态

Bob7274bbc75beb
diff --git a/AGENTS.md b/AGENTS.md
index 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.pbxproj
index 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.xcscheme
index 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">
<BuildAction
parallelizeBuildables = "YES"
diff --git a/CodexBar/Controllers/HeatmapDetailPanelController.swift b/CodexBar/Controllers/HeatmapDetailPanelController.swift
index 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.left
private 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 = hostingController
self.hostingController = hostingController
- self.detailModel = detailModel
}
configurePanelLayers()
+ panel?.setContentSize(size)
}
private func configurePanelLayers() {
diff --git a/CodexBar/Models/CodexQuotaModels.swift b/CodexBar/Models/CodexQuotaModels.swift
index 7b2a6fe..58e587d 100644
--- a/CodexBar/Models/CodexQuotaModels.swift
+++ b/CodexBar/Models/CodexQuotaModels.swift
@@ -4,6 +4,7 @@ import Foundation
nonisolated struct CodexQuotaSnapshot: Equatable {
let account: CodexAccount
let planType: String?
+ let resetCreditsAvailableCount: Int?
let generatedAt: Date
let limits: [CodexQuotaLimitSnapshot]
let usage: CodexUsageSnapshot?
@@ -104,6 +105,12 @@ nonisolated struct QuotaWindow: Equatable, Identifiable {
nonisolated struct AccountRateLimitsResponse: Decodable {
let rateLimits: RateLimitSnapshot
let 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.swift
index 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: Bool
var 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.swift
index 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.swift
index 2279e7a..48df7d8 100644
--- a/CodexBar/Views/Menu/UsageHeatmap.swift
+++ b/CodexBar/Views/Menu/UsageHeatmap.swift
@@ -1,5 +1,4 @@
import AppKit
-import Combine
import 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.swift
index 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.lastUploadAtText
return 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.md
index 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.md
index 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.md
index 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 == .available
UI 状态:
-| 状态 | 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.md
index 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.xml
index 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>