Skip to content

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

feat: 支持按日期范围批量重建工作流数据

Bob2e12bcb39332
diff --git a/CodexBar.xcodeproj/project.pbxproj b/CodexBar.xcodeproj/project.pbxproj
index 3ed7f0b..6896712 100644
--- a/CodexBar.xcodeproj/project.pbxproj
+++ b/CodexBar.xcodeproj/project.pbxproj
@@ -274,7 +274,7 @@
"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";
CODE_SIGN_STYLE = Automatic;
COMBINE_HIDPI_IMAGES = YES;
- CURRENT_PROJECT_VERSION = 48;
+ CURRENT_PROJECT_VERSION = 49;
DEAD_CODE_STRIPPING = YES;
DEVELOPMENT_TEAM = 4KJ362VJW5;
ENABLE_APP_INTENTS_METADATA_GENERATION = NO;
@@ -290,7 +290,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
- MARKETING_VERSION = 3.3.10;
+ MARKETING_VERSION = 3.3.11;
PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar;
PRODUCT_NAME = "$(TARGET_NAME)";
REGISTER_APP_GROUPS = YES;
@@ -313,7 +313,7 @@
"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";
CODE_SIGN_STYLE = Automatic;
COMBINE_HIDPI_IMAGES = YES;
- CURRENT_PROJECT_VERSION = 48;
+ CURRENT_PROJECT_VERSION = 49;
DEAD_CODE_STRIPPING = YES;
DEVELOPMENT_TEAM = 4KJ362VJW5;
ENABLE_APP_INTENTS_METADATA_GENERATION = NO;
@@ -329,7 +329,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
- MARKETING_VERSION = 3.3.10;
+ MARKETING_VERSION = 3.3.11;
PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar;
PRODUCT_NAME = "$(TARGET_NAME)";
PROVISIONING_PROFILE_SPECIFIER = "";
diff --git a/CodexBar/Controllers/ActivityCenterPanelController.swift b/CodexBar/Controllers/ActivityCenterPanelController.swift
index d927b9d..fc40c66 100644
--- a/CodexBar/Controllers/ActivityCenterPanelController.swift
+++ b/CodexBar/Controllers/ActivityCenterPanelController.swift
@@ -2,7 +2,7 @@ import AppKit
import Combine
import SwiftUI
-/// 点击活动卡片后展开的并发任务中心,复用菜单侧边抽屉定位和动画。
+/// 点击活动卡片后展开的并发任务中心, 复用菜单侧边抽屉定位和动画
@MainActor
final class ActivityCenterPanelController {
private let activityMonitor: CodexActivityMonitor
@@ -72,7 +72,7 @@ final class ActivityCenterPanelController {
func hide(immediate: Bool = false) {
cancelScheduledPresentation()
- // 热力图 hover 等高频路径会盲调 hide;已隐藏时跳过 @Published 写入,避免整个菜单重算。
+ // 热力图 hover 等高频路径会盲调 hide; 已隐藏时跳过 @Published 写入, 避免整个菜单重算
guard presentationState.isPresented || presenter.isVisible else {
return
}
diff --git a/CodexBar/Controllers/SettingsWindowController.swift b/CodexBar/Controllers/SettingsWindowController.swift
index b6da555..a1ff738 100644
--- a/CodexBar/Controllers/SettingsWindowController.swift
+++ b/CodexBar/Controllers/SettingsWindowController.swift
@@ -14,6 +14,7 @@ final class SettingsWindowController: HostingWindowController {
private let mainPanelSettings: MainPanelSettings
private let notificationSettings: NotificationSettings
private let onSyncChanged: (Bool) -> Void
+ private let onRebuildWorkflowData: WorkflowSyncScheduler.RebuildHandler
private lazy var notificationOptionsPanelController = NotificationOptionsPanelController(
notificationSettings: notificationSettings,
codexHookSettings: codexHookSettings,
@@ -31,7 +32,8 @@ final class SettingsWindowController: HostingWindowController {
mainPanelSettings: MainPanelSettings,
notificationSettings: NotificationSettings,
screenProvider: @escaping () -> NSScreen?,
- onSyncChanged: @escaping (Bool) -> Void
+ onSyncChanged: @escaping (Bool) -> Void,
+ onRebuildWorkflowData: @escaping WorkflowSyncScheduler.RebuildHandler
) {
self.viewModel = viewModel
self.appUpdater = appUpdater
@@ -43,12 +45,14 @@ final class SettingsWindowController: HostingWindowController {
self.mainPanelSettings = mainPanelSettings
self.notificationSettings = notificationSettings
self.onSyncChanged = onSyncChanged
+ self.onRebuildWorkflowData = onRebuildWorkflowData
super.init(screenProvider: screenProvider)
}
override func open() {
refreshSettingsState()
super.open()
+ NotificationCenter.default.post(name: .settingsWindowDidOpen, object: nil)
}
override func makeWindow() -> NSWindow {
@@ -61,6 +65,7 @@ final class SettingsWindowController: HostingWindowController {
mainPanelSettings: mainPanelSettings,
notificationSettings: notificationSettings,
onSyncChanged: onSyncChanged,
+ onRebuildWorkflowData: onRebuildWorkflowData,
onNotificationOptionsAction: { [weak self] action in
self?.handleNotificationOptionsAction(action)
}
@@ -162,3 +167,7 @@ final class SettingsWindowController: HostingWindowController {
min(maximum, max(minimum, value))
}
}
+
+nonisolated extension Notification.Name {
+ static let settingsWindowDidOpen = Notification.Name("CodexBar.settingsWindowDidOpen")
+}
diff --git a/CodexBar/Controllers/SidePanelSupport.swift b/CodexBar/Controllers/SidePanelSupport.swift
index fb6e691..512c78a 100644
--- a/CodexBar/Controllers/SidePanelSupport.swift
+++ b/CodexBar/Controllers/SidePanelSupport.swift
@@ -106,7 +106,7 @@ final class SidePanelDrawerAnimator {
Task { @MainActor [weak self, weak panel] in
await Task.yield()
- // 过期请求的隐藏和清理由调用方的 generation 流程负责。
+ // 过期请求的隐藏和清理由调用方的 generation 流程负责
guard let self,
let panel,
panel.isVisible,
@@ -142,8 +142,8 @@ final class SidePanelDrawerAnimator {
}
}
-/// 重置次数、通知子选项和并发任务中心三类「一次性展开」抽屉面板共用的显隐状态机:
-/// 负责 generation 竞态防护、入退场动画和 child window 挂载/卸载
+/// 重置次数; 通知子选项和并发任务中心三类"一次性展开"抽屉面板共用的显隐状态机
+/// 负责 generation 竞态防护; 入退场动画和 child window 挂载/卸载
/// (热力图详情面板因带切边与延迟隐藏, 状态机不同, 不走这里)
@MainActor
final class SidePanelDrawerPresenter {
@@ -248,8 +248,8 @@ final class SidePanelDrawerPresenter {
}
}
-/// 侧边面板的内容宿主: 懒建 panel + hostingController, 统一「替换 rootView →
-/// configureLayers → setContentSize」的更新序列
+/// 侧边面板的内容宿主: 懒建 panel + hostingController, 统一"替换 rootView →
+/// configureLayers → setContentSize"的更新序列
/// ⚠️ 每次更新都整树替换 rootView 是刻意行为 (见 CLAUDE.md 热力图详情面板的说明), 不要改成常驻状态推送
@MainActor
final class SidePanelContentHost<Root: View> {
@@ -272,7 +272,7 @@ final class SidePanelContentHost<Root: View> {
self.cornerRadius = cornerRadius
}
- /// Swift 6.3.3 的 EarlyPerfInliner 会在优化该泛型类型的合成析构函数时崩溃。
+ /// Swift 6.3.3 的 EarlyPerfInliner 会在优化该泛型类型的合成析构函数时崩溃
@_optimize(none)
deinit {}
@@ -465,7 +465,7 @@ enum SidePanelSupport {
return alignmentScreenFrame.maxY - panelSize.height
}
- /// 宿主菜单面板可能进入系统菜单栏保留区域; 面板定位只向上放宽到锚点行顶边,
+ /// 宿主菜单面板可能进入系统菜单栏保留区域; 面板定位只向上放宽到锚点行顶边
/// 让两者顶边对齐, 同时继续沿用 visibleFrame 的左右边界和 Dock 下边界
static func anchorAwareVisibleFrame(
visibleFrame: CGRect,
diff --git a/CodexBar/Controllers/StatusItemController.swift b/CodexBar/Controllers/StatusItemController.swift
index 630150c..91876e0 100644
--- a/CodexBar/Controllers/StatusItemController.swift
+++ b/CodexBar/Controllers/StatusItemController.swift
@@ -109,6 +109,12 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
self?.statusItem.button?.window?.screen
} onSyncChanged: { [weak self] enabled in
self?.handleSyncChanged(enabled)
+ } onRebuildWorkflowData: { [weak self] dateKeys, completion in
+ guard let self else {
+ completion(.failure(CancellationError()))
+ return
+ }
+ workflowSyncScheduler.requestRebuild(for: dateKeys, completion: completion)
}
private lazy var logWindowController = LogWindowController { [weak self] in
@@ -182,7 +188,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
super.init()
}
- /// 无状态点和额度条时使用模板渲染,由系统按菜单栏外观着色。
+ /// 无状态点和额度条时使用模板渲染, 由系统按菜单栏外观着色
private static func makeStatusImage(
_ symbolName: String,
indicatorTint: NSColor? = nil,
@@ -346,7 +352,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
}
}
- /// 只包含影响图像像素的字段;tooltip 文本变化不应触发重绘。
+ /// 只包含影响图像像素的字段; tooltip 文本变化不应触发重绘
var renderState: StatusIconRenderState {
StatusIconRenderState(symbolName: symbolName, indicator: indicator, progress: progress)
}
@@ -409,7 +415,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
}
}
- /// 状态图标中影响像素的渲染子状态,用于跳过 tooltip-only 变化引发的重绘。
+ /// 状态图标中影响像素的渲染子状态, 用于跳过 tooltip-only 变化引发的重绘
private struct StatusIconRenderState: Equatable {
let symbolName: String
let indicator: ActivityIndicator?
@@ -700,7 +706,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
renderStatusImage(state)
return
}
- // tooltip-only 变化不重绘,也不打断进行中的图标动画。
+ // tooltip-only 变化不重绘, 也不打断进行中的图标动画
guard previousState.renderState != state.renderState else {
return
}
@@ -843,7 +849,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
}
}
- /// toggle 将走「打开」分支的状态谓词, 与 toggleMenuSurface 的分支口径一致
+ /// toggle 将走"打开"分支的状态谓词, 与 toggleMenuSurface 的分支口径一致
private var menuSurfaceWillOpenOnToggle: Bool {
menuSurfaceState == .hidden || menuSurfaceState == .closing
}
@@ -1127,7 +1133,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
scheduleAuxiliaryWindowKeyFocusRestore()
}
- /// 侧边面板互斥名册:新增面板只需要加入这里,显隐与点击区域判定即可覆盖。
+ /// 侧边面板互斥名册: 新增面板只需要加入这里, 显隐与点击区域判定即可覆盖
private var sideDetailPanels: [MenuSideDetailPanel] {
[heatmapDetailPanelController, resetCreditsPanelController, activityCenterPanelController]
}
@@ -1357,7 +1363,7 @@ private final class StatusItemController: NSObject, NSMenuDelegate {
}
}
-/// 菜单侧边面板的互斥名册接口;面板间互斥和点击区域判定统一走名册遍历。
+/// 菜单侧边面板的互斥名册接口; 面板间互斥和点击区域判定统一走名册遍历
private protocol MenuSideDetailPanel: AnyObject {
func hide(immediate: Bool)
func containsScreenPoint(_ screenPoint: NSPoint) -> Bool
diff --git a/CodexBar/Models/CodexActivityModels.swift b/CodexBar/Models/CodexActivityModels.swift
index 21250f5..01f5cab 100644
--- a/CodexBar/Models/CodexActivityModels.swift
+++ b/CodexBar/Models/CodexActivityModels.swift
@@ -1,12 +1,12 @@
import Foundation
-/// 实时活动管道的共享保留窗口。
-/// tail reader 的 bootstrap 回放范围与任务中心的历史保留期是同一个不变量,必须相等。
+/// 实时活动管道的共享保留窗口
+/// tail reader 的 bootstrap 回放范围与任务中心的历史保留期是同一个不变量, 必须相等
nonisolated enum CodexActivityRetention {
static let window: TimeInterval = 24 * 60 * 60
}
-/// 活跃任务最近收到的 Hook 事件,供活动卡片展示当前执行阶段。
+/// 活跃任务最近收到的 Hook 事件, 供活动卡片展示当前执行阶段
nonisolated enum CodexActivityEvent: Equatable {
case promptSubmitted
case toolStarted
@@ -18,13 +18,13 @@ nonisolated enum CodexActivityEvent: Equatable {
case approvalRequested
}
-/// bootstrap 后需要向更早日期定向查找 Prompt 起点的精确任务引用。
+/// bootstrap 后需要向更早日期定向查找 Prompt 起点的精确任务引用
nonisolated struct CodexActivityPromptReference: Hashable {
let sessionId: String
let turnId: String
}
-/// 正在运行或等待批准的任务摘要,不对 UI 暴露原始会话 ID。
+/// 正在运行或等待批准的任务摘要, 不对 UI 暴露原始会话 ID
nonisolated struct CodexActivityTaskSnapshot: Equatable, Identifiable {
let id: UUID
let latestEvent: CodexActivityEvent
@@ -35,11 +35,11 @@ nonisolated struct CodexActivityTaskSnapshot: Equatable, Identifiable {
let startedAt: Date?
let stateChangedAt: Date
let showsPreciseDuration: Bool
- /// nil 表示 Hook 字段不足,无法可靠统计;0 表示已确认当前没有活跃子 Agent。
+ /// nil 表示 Hook 字段不足, 无法可靠统计; 0 表示已确认当前没有活跃子 Agent
let activeSubagentCount: Int?
}
-/// 最近确认结束的任务。完成只表示一轮任务结束,不代表执行成功。
+/// 最近确认结束的任务; 完成只表示一轮任务结束, 不代表执行成功
nonisolated struct CodexActivityCompletion: Equatable, Identifiable {
let id: UUID
let projectName: String?
@@ -49,7 +49,7 @@ nonisolated struct CodexActivityCompletion: Equatable, Identifiable {
let duration: TimeInterval?
}
-/// 最近确认终止的任务。终止不会被视为完成,也不会触发完成提醒。
+/// 最近确认终止的任务; 终止不会被视为完成, 也不会触发完成提醒
nonisolated struct CodexActivityTermination: Equatable, Identifiable {
let id: UUID
let projectName: String?
@@ -59,7 +59,7 @@ nonisolated struct CodexActivityTermination: Equatable, Identifiable {
let duration: TimeInterval?
}
-/// UI 只消费该快照,不直接读取或解释 Hook 事件。
+/// UI 只消费该快照, 不直接读取或解释 Hook 事件
nonisolated struct CodexActivitySnapshot: Equatable {
let waitingTasks: [CodexActivityTaskSnapshot]
let runningTasks: [CodexActivityTaskSnapshot]
@@ -111,7 +111,7 @@ nonisolated struct CodexActivitySnapshot: Equatable {
hasActiveTasks || !recentCompletions.isEmpty || !recentTerminations.isEmpty
}
- /// 等待批准 > 运行中 > 最近完成 > 最近终止 > 空闲;菜单栏图标、tooltip 和活动卡片共用同一判定。
+ /// 等待批准 > 运行中 > 最近完成 > 最近终止 > 空闲; 菜单栏图标, tooltip 和活动卡片共用同一判定
var primaryActivity: CodexPrimaryActivity {
if let task = primaryWaitingTask {
return .waiting(task)
@@ -129,7 +129,7 @@ nonisolated struct CodexActivitySnapshot: Equatable {
}
}
-/// 快照归一后的主活动状态,highlighted 表示完成仍处于高亮时间窗内。
+/// 快照归一后的主活动状态, highlighted 表示完成仍处于高亮时间窗内
nonisolated enum CodexPrimaryActivity: Equatable {
case waiting(CodexActivityTaskSnapshot)
case running(CodexActivityTaskSnapshot)
@@ -138,7 +138,7 @@ nonisolated enum CodexPrimaryActivity: Equatable {
case idle
}
-/// 只有 live Hook 或 session 生命周期会发布 transition,bootstrap 永远不会触发历史通知。
+/// 只有 live Hook 或 session 生命周期会发布 transition, bootstrap 永远不会触发历史通知
nonisolated enum CodexActivityTransition: Equatable {
case waitingApproval(CodexActivityTaskSnapshot)
case completed(CodexActivityCompletion)
@@ -194,7 +194,7 @@ nonisolated enum CodexActivityDisplayFormat {
relativeText(since: terminatedAt, now: now, action: "终止")
}
- /// 活动卡片、任务中心、菜单栏 tooltip 和系统通知共用的时长片段。
+ /// 活动卡片, 任务中心, 菜单栏 tooltip 和系统通知共用的时长片段
static func waitingDurationFragment(since stateChangedAt: Date, now: Date) -> String {
"已等待 \(CodexActivityDurationFormat.text(for: now.timeIntervalSince(stateChangedAt)))"
}
@@ -207,7 +207,7 @@ nonisolated enum CodexActivityDisplayFormat {
"耗时 \(CodexActivityDurationFormat.text(for: duration))"
}
- /// 活动卡片和任务中心共用同一份文案片段。
+ /// 活动卡片和任务中心共用同一份文案片段
static func waitingDetailComponents(
for task: CodexActivityTaskSnapshot,
now: Date
diff --git a/CodexBar/Models/CodexHookEvent.swift b/CodexBar/Models/CodexHookEvent.swift
index 0968904..7dd69c0 100644
--- a/CodexBar/Models/CodexHookEvent.swift
+++ b/CodexBar/Models/CodexHookEvent.swift
@@ -41,7 +41,7 @@ nonisolated enum CodexHookEvent: String, CaseIterable {
}
}
-/// Codex turn 的审批路由;只有 user 表示 PermissionRequest 会停在用户 UI。
+/// Codex turn 的审批路由; 只有 user 表示 PermissionRequest 会停在用户 UI
nonisolated enum CodexApprovalReviewer: String, Codable {
case user
case autoReview = "auto_review"
diff --git a/CodexBar/Models/CodexWorkflowModels.swift b/CodexBar/Models/CodexWorkflowModels.swift
index 9ff9b2d..a648523 100644
--- a/CodexBar/Models/CodexWorkflowModels.swift
+++ b/CodexBar/Models/CodexWorkflowModels.swift
@@ -301,7 +301,7 @@ nonisolated struct WorkflowSnapshot: Equatable {
self.dailyMetrics = dailyMetrics
}
- /// 同 generation 只采用一份数据;确认独立的新 generation 与历史贡献累加
+ /// 同 generation 只采用一份数据; 确认独立的新 generation 与历史贡献累加
init(
localAggregates: [WorkflowDailyAggregate],
syncedRecords: [WorkflowSyncedDailyRecord],
diff --git a/CodexBar/Services/CodexCLI/CodexCLIResolver.swift b/CodexBar/Services/CodexCLI/CodexCLIResolver.swift
index 3a8831f..9c5dc29 100644
--- a/CodexBar/Services/CodexCLI/CodexCLIResolver.swift
+++ b/CodexBar/Services/CodexCLI/CodexCLIResolver.swift
@@ -176,7 +176,7 @@ nonisolated enum CodexCLIResolver {
canonicalPath(lhs) == canonicalPath(rhs)
}
- /// 「两个路径是否指向同一文件」的统一口径, Hook 配置匹配也复用它
+ /// "两个路径是否指向同一文件"的统一口径, Hook 配置匹配也复用它
static func canonicalPath(_ path: String, expandingTilde: Bool = false) -> String {
let expandedPath = expandingTilde ? (path as NSString).expandingTildeInPath : path
return URL(fileURLWithPath: expandedPath)
diff --git a/CodexBar/Services/Notifications/CodexNotificationService.swift b/CodexBar/Services/Notifications/CodexNotificationService.swift
index d6ca366..fd80966 100644
--- a/CodexBar/Services/Notifications/CodexNotificationService.swift
+++ b/CodexBar/Services/Notifications/CodexNotificationService.swift
@@ -3,7 +3,7 @@ import Combine
import Foundation
import UserNotifications
-/// 集中式提醒服务: 订阅额度与实时活动,负责触觉反馈、阈值判定、去重、重置识别与本地通知发送。
+/// 集中式提醒服务: 订阅额度与实时活动, 负责触觉反馈; 阈值判定; 去重; 重置识别与本地通知发送
@MainActor
final class CodexNotificationService: NSObject {
private let settings: NotificationSettings
@@ -25,7 +25,7 @@ final class CodexNotificationService: NSObject {
/// 阈值穿越判定的会话内上一帧剩余比例, key 为 account|limitId|windowId
private var lastRemainingPercents: [String: Int] = [:]
- /// 可信快照中每个额度窗口的重置观察状态;窗口消失后重现会获得新的生命周期标记。
+ /// 可信快照中每个额度窗口的重置观察状态; 窗口消失后重现会获得新的生命周期标记
private var quotaWindowResetObservations: [String: QuotaWindowResetObservation] = [:]
init(
@@ -319,7 +319,7 @@ final class CodexNotificationService: NSObject {
quotaWindowResetObservations[stateKey]?.hasObservedConsumption = true
} else if usedPercent == 0,
quotaWindowResetObservations[stateKey]?.hasObservedConsumption == true {
- // 归零即消费待重置状态; 开关或授权此刻不可用时不保留补发。
+ // 归零即消费待重置状态; 开关或授权此刻不可用时不保留补发
quotaWindowResetObservations[stateKey]?.hasObservedConsumption = false
guard settings.canDeliver,
settings.isQuotaResetEnabled,
diff --git a/CodexBar/Services/Settings/NotificationSettings.swift b/CodexBar/Services/Settings/NotificationSettings.swift
index 5a4c2f3..954812c 100644
--- a/CodexBar/Services/Settings/NotificationSettings.swift
+++ b/CodexBar/Services/Settings/NotificationSettings.swift
@@ -3,7 +3,7 @@ import Combine
import Foundation
import UserNotifications
-/// 通知偏好: 总开关、五类通知子开关、任务触觉开关、两个阈值和系统授权状态镜像
+/// 通知偏好: 总开关; 五类通知子开关; 任务触觉开关; 两个阈值和系统授权状态镜像
/// 授权请求/查询集中在这里, 通知与触觉反馈判定在 CodexNotificationService
@MainActor
final class NotificationSettings: ObservableObject {
@@ -23,7 +23,7 @@ final class NotificationSettings: ObservableObject {
authorizationStatus == .denied
}
- /// 总开关开启且系统已明确允许时才发送, 未决定或未知状态都按不可发送处理。
+ /// 总开关开启且系统已明确允许时才发送, 未决定或未知状态都按不可发送处理
var canDeliver: Bool {
guard isEnabled else {
return false
@@ -39,7 +39,7 @@ final class NotificationSettings: ObservableObject {
}
}
- /// 触觉反馈不依赖系统通知授权,但服从 App 内通知总开关。
+ /// 触觉反馈不依赖系统通知授权, 但服从 App 内通知总开关
var canPerformTaskHapticFeedback: Bool {
isEnabled && isTaskHapticEnabled
}
diff --git a/CodexBar/Services/Settings/WorkflowSyncSettings.swift b/CodexBar/Services/Settings/WorkflowSyncSettings.swift
index fc4cd32..2034099 100644
--- a/CodexBar/Services/Settings/WorkflowSyncSettings.swift
+++ b/CodexBar/Services/Settings/WorkflowSyncSettings.swift
@@ -60,7 +60,7 @@ final class WorkflowSyncSettings: ObservableObject {
syncAvailability.isAvailable
}
- /// 「同步是否实际生效」的唯一判定: Hook 已启用且同步开关打开且 iCloud 可用
+ /// "同步是否实际生效"的唯一判定: Hook 已启用且同步开关打开且 iCloud 可用
func isEffectivelyActive(isHookEnabled: Bool) -> Bool {
isHookEnabled && isEnabled && isSyncAvailable
}
diff --git a/CodexBar/Services/Workflow/CodexActivityMonitor.swift b/CodexBar/Services/Workflow/CodexActivityMonitor.swift
index a4a3649..13d640a 100644
--- a/CodexBar/Services/Workflow/CodexActivityMonitor.swift
+++ b/CodexBar/Services/Workflow/CodexActivityMonitor.swift
@@ -2,7 +2,7 @@ import AppKit
import Combine
import Foundation
-/// 从本机 Hook JSONL 维护进程内实时任务状态,是菜单栏、活动卡片、通知和触觉反馈的唯一任务状态来源。
+/// 从本机 Hook JSONL 维护进程内实时任务状态, 是菜单栏; 活动卡片; 通知和触觉反馈的唯一任务状态来源
@MainActor
final class CodexActivityMonitor: ObservableObject {
@Published private(set) var snapshot = CodexActivitySnapshot.empty
@@ -225,7 +225,7 @@ final class CodexActivityMonitor: ObservableObject {
tasks.removeValue(forKey: key)
didChange = true
if case .completed = terminal, recentCompletionDate(for: key) != nil {
- // 迟到事件恢复出的任务不能被 rollout 再次完成。
+ // 迟到事件恢复出的任务不能被 rollout 再次完成
continue
}
resolveTerminal(
@@ -293,8 +293,8 @@ final class CodexActivityMonitor: ObservableObject {
refreshSnapshot(now: Date())
publishLiveTransitions(transitions)
if !pendingTerminalTasks.isEmpty {
- // 只有刚进入终态确认窗口的任务需要重置解析缓存重试定位 rollout;
- // 窗口期内的后续批次只做即时查询,避免反复递归扫描 sessions。
+ // 只有刚进入终态确认窗口的任务需要重置解析缓存重试定位 rollout
+ // 窗口期内的后续批次只做即时查询, 避免反复递归扫描 sessions
let hasNewPendingTasks = !Set(pendingTerminalTasks.keys)
.subtracting(pendingKeysBefore).isEmpty
refreshSessionLifecycleNow(resetsResolutionFallbacks: hasNewPendingTasks)
@@ -302,7 +302,7 @@ final class CodexActivityMonitor: ObservableObject {
}
}
- /// bootstrap 只覆盖 24 小时窗口;窗口内恢复出的无起点任务向更早日期回查 Prompt 起点。
+ /// bootstrap 只覆盖 24 小时窗口; 窗口内恢复出的无起点任务向更早日期回查 Prompt 起点
private func backfillPromptStartTimesFromHistory() {
let references = tasks.values.compactMap(\.promptReference)
guard !references.isEmpty, let reader = tailReader else {
@@ -353,7 +353,7 @@ final class CodexActivityMonitor: ObservableObject {
case .postCompact:
resumeTask(from: event, latestEvent: .compactionFinished, allowsRecovery: true)
case .subagentStart:
- // 子智能体只更新所属顶层任务,不自行创建一条并发任务。
+ // 子智能体只更新所属顶层任务, 不自行创建一条并发任务
updateSubagentActivity(from: event, isStarting: true)
case .subagentStop:
updateSubagentActivity(from: event, isStarting: false)
@@ -383,8 +383,8 @@ final class CodexActivityMonitor: ObservableObject {
}
if let sessionId = key.sessionId {
- // 同一 session 的 turn 按顺序执行。新 prompt 让旧 turn 立即退出活动列表,
- // 但保留短暂终态确认窗口,避免把迟到的正常完成误记为终止。
+ // 同一 session 的 turn 按顺序执行. 新 prompt 让旧 turn 立即退出活动列表
+ // 但保留短暂终态确认窗口, 避免把迟到的正常完成误记为终止
guard !tasks.values.contains(where: {
$0.key.sessionId == sessionId && $0.lastActivityAt > event.timestamp
}) else {
@@ -408,7 +408,7 @@ final class CodexActivityMonitor: ObservableObject {
recentlyCompletedTaskAt.removeValue(forKey: key)
recentlyTerminatedTaskAt.removeValue(forKey: key)
if let sessionId = key.sessionId {
- // 缺少 turn 的 Stop 会使用 session 键;新 turn 开始后允许该键再次完成。
+ // 缺少 turn 的 Stop 会使用 session 键; 新 turn 开始后允许该键再次完成
recentlyCompletedTaskAt.removeValue(forKey: .session(sessionId))
recentlyTerminatedTaskAt.removeValue(forKey: .session(sessionId))
}
@@ -479,7 +479,7 @@ final class CodexActivityMonitor: ObservableObject {
return
}
- // 子 Agent 只能按 session 关联父任务,忽略上一 turn 延迟到达的事件。
+ // 子 Agent 只能按 session 关联父任务, 忽略上一 turn 延迟到达的事件
if let startedAt = task.startedAt, event.timestamp < startedAt {
return
}
@@ -507,7 +507,7 @@ final class CodexActivityMonitor: ObservableObject {
tasks[key] = task
}
- /// Subagent Hook 的 turn 属于子 Agent 自己;父任务只能通过共享 session 关联。
+ /// Subagent Hook 的 turn 属于子 Agent 自己; 父任务只能通过共享 session 关联
private func hasReliableSubagentAssociation(
eventSessionId: String?,
matchedKey: CodexActivityTaskKey
@@ -542,7 +542,7 @@ final class CodexActivityMonitor: ObservableObject {
}
task.mergeMetadata(from: event)
- // 权限事件描述当前请求;缺失工具名时不能沿用上一条工具事件。
+ // 权限事件描述当前请求; 缺失工具名时不能沿用上一条工具事件
task.toolName = event.toolName
task.lastActivityAt = event.timestamp
let enteredWaiting = task.recordApprovalRequest(at: event.timestamp)
@@ -566,7 +566,7 @@ final class CodexActivityMonitor: ObservableObject {
private func completeTask(from event: WorkflowHookEvent) -> CodexActivityLiveTransition? {
let eventKey = CodexActivityTaskKey(event: event)
guard recentCompletionDate(for: eventKey) == nil else {
- // 清掉旧版本或异常顺序留下的同键恢复任务。
+ // 清掉旧版本或异常顺序留下的同键恢复任务
tasks.removeValue(forKey: eventKey)
return nil
}
@@ -623,7 +623,7 @@ final class CodexActivityMonitor: ObservableObject {
return .completed(completion)
}
- /// 精确 turn 失败后回退同 session 最近活动,再回退同项目匿名任务。
+ /// 精确 turn 失败后回退同 session 最近活动, 再回退同项目匿名任务
private func matchingTaskKey(for event: WorkflowHookEvent) -> CodexActivityTaskKey? {
let exactKey = CodexActivityTaskKey(event: event)
if tasks[exactKey] != nil {
@@ -674,7 +674,7 @@ final class CodexActivityMonitor: ObservableObject {
.sorted(by: Self.recentFirst(\.lastActivityAt, \.displayID))
}
- /// 时间相同再按 UUID 字符串排序(Swift sort 不稳定),保证快照对 SwiftUI diff 稳定。
+ /// 时间相同再按 UUID 字符串排序(Swift sort 不稳定), 保证快照对 SwiftUI diff 稳定
private static func recentFirst<Element>(
_ date: KeyPath<Element, Date>,
_ id: KeyPath<Element, UUID>
@@ -766,7 +766,7 @@ final class CodexActivityMonitor: ObservableObject {
}
private extension CodexActivityMonitor {
- /// PermissionRequest 表示进入审批流程;只有 rollout 明确把审批路由给 user 时才是 UI 等待。
+ /// PermissionRequest 表示进入审批流程; 只有 rollout 明确把审批路由给 user 时才是 UI 等待
func resolvePendingApprovalIfPossible(
for task: inout CodexActivityTask,
into transitions: inout [CodexActivityTransition]
@@ -791,8 +791,8 @@ private extension CodexActivityMonitor {
return true
}
- /// rollout 终态归类的唯一入口;活动任务和等待终态确认任务只有 abort 兜底时间不同。
- /// 终止记录只供任务中心展示,不发布 transition,也不产生绿色状态或通知。
+ /// rollout 终态归类的唯一入口; 活动任务和等待终态确认任务只有 abort 兜底时间不同
+ /// 终止记录只供任务中心展示, 不发布 transition, 也不产生绿色状态或通知
func resolveTerminal(
_ terminal: CodexSessionTaskTerminalState,
task: CodexActivityTask,
@@ -855,7 +855,7 @@ private extension CodexActivityMonitor {
modelName: String? = nil,
effort: String? = nil
) -> CodexActivityCompletion {
- // rollout 时间戳是整秒,避免因为同一秒内的 Hook 毫秒时间戳而把完成时间记在最后活动之前。
+ // rollout 时间戳是整秒, 避免因为同一秒内的 Hook 毫秒时间戳而把完成时间记在最后活动之前
let recordedCompletedAt = max(completedAt, task.lastActivityAt)
let completion = storeCompletion(
projectName: projectName ?? task.projectName,
@@ -1115,7 +1115,7 @@ private struct CodexActivityTask {
startedAt != nil && !key.isAnonymous
}
- /// 起点可信时返回到 end 的精确耗时,起点缺失或晚于 end 时为 nil。
+ /// 起点可信时返回到 end 的精确耗时, 起点缺失或晚于 end 时为 nil
func preciseDuration(until end: Date) -> TimeInterval? {
guard showsPreciseDuration, let startedAt, end >= startedAt else {
return nil
@@ -1224,7 +1224,7 @@ private struct CodexActivityTask {
return value.isEmpty ? nil : value
}
- /// 记录审批候选;返回值只表示任务是否刚刚进入用户等待状态。
+ /// 记录审批候选; 返回值只表示任务是否刚刚进入用户等待状态
mutating func recordApprovalRequest(at requestedAt: Date) -> Bool {
pendingApprovalRequestedAt = requestedAt
guard approvalReviewer == .user else {
diff --git a/CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift b/CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift
index 6a71f96..6966348 100644
--- a/CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift
+++ b/CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift
@@ -1,13 +1,13 @@
import Foundation
-/// 活跃 turn 的最小定位信息,只在进程内用于关联 Codex session 生命周期事件。
+/// 活跃 turn 的最小定位信息, 只在进程内用于关联 Codex session 生命周期事件
nonisolated struct CodexActivityTurnReference: Hashable {
let sessionId: String
let turnId: String
let startedAt: Date
}
-/// 增量读取活跃 Codex session 的 rollout JSONL,只提取 turn 生命周期字段。
+/// 增量读取活跃 Codex session 的 rollout JSONL, 只提取 turn 生命周期字段
actor CodexSessionLifecycleReader {
private let sessionsRootURL: URL
private let archivedSessionsRootURL: URL
@@ -28,7 +28,7 @@ actor CodexSessionLifecycleReader {
self.fileManager = fileManager
}
- /// 返回 rollout 中已知的起点和终态,不解码会话或工具内容。
+ /// 返回 rollout 中已知的起点和终态, 不解码会话或工具内容
func lifecycleStates(
for references: [CodexActivityTurnReference]
) -> [CodexSessionTaskLifecycleState] {
@@ -144,7 +144,7 @@ actor CodexSessionLifecycleReader {
.max(by: { $0.startedAt < $1.startedAt })
}
- /// 唤醒后允许仍未定位到文件的活跃 session 重新执行一次递归兜底。
+ /// 唤醒后允许仍未定位到文件的活跃 session 重新执行一次递归兜底
func resetResolutionFallbacks() {
lastResolutionAttemptBySession.removeAll()
recursiveFallbackSessionIds.removeAll()
@@ -156,7 +156,7 @@ actor CodexSessionLifecycleReader {
return cursor
}
if cursorsBySession.removeValue(forKey: reference.sessionId) != nil {
- // 缓存文件可能被移动到 archived_sessions,允许重新完整定位一次。
+ // 缓存文件可能被移动到 archived_sessions, 允许重新完整定位一次
recursiveFallbackSessionIds.remove(reference.sessionId)
}
@@ -199,7 +199,7 @@ actor CodexSessionLifecycleReader {
return nil
}
- // resume 可能继续很早以前创建的 session;每次活跃生命周期最多递归一次。
+ // resume 可能继续很早以前创建的 session; 每次活跃生命周期最多递归一次
let suffix = "-\(reference.sessionId).jsonl"
guard let enumerator = fileManager.enumerator(
at: sessionsRootURL,
diff --git a/CodexBar/Services/Workflow/HookEventTailReader.swift b/CodexBar/Services/Workflow/HookEventTailReader.swift
index 2b575e2..8c19dae 100644
--- a/CodexBar/Services/Workflow/HookEventTailReader.swift
+++ b/CodexBar/Services/Workflow/HookEventTailReader.swift
@@ -7,13 +7,13 @@ nonisolated enum HookEventBatch {
case live([WorkflowHookEvent])
}
-/// 在独立 actor 中按完整 JSONL 行读取 HookEvents/events。
-/// bootstrap 覆盖滚动 24 小时并作为单次事务发送,live 随后按当日文件 offset 增量读取。
+/// 在独立 actor 中按完整 JSONL 行读取 HookEvents/events
+/// bootstrap 覆盖滚动 24 小时并作为单次事务发送, live 随后按当日文件 offset 增量读取
actor HookEventTailReader {
private let onBatch: @MainActor @Sendable (HookEventBatch) -> Void
private var pollTask: Task<Void, Never>?
private var isRunning = false
- // actor 会在 await 期间重入;所有外部读取请求通过这两个标记合并为单一读取流程。
+ // actor 会在 await 期间重入; 所有外部读取请求通过这两个标记合并为单一读取流程
private var isProcessingReads = false
private var hasPendingDrain = false
private var activeDateKey = ""
@@ -99,7 +99,7 @@ actor HookEventTailReader {
}
}
- // 连续读取失败时清空恢复态并跳过当前已有字节,避免稍后误当 live 发送历史通知。
+ // 连续读取失败时清空恢复态并跳过当前已有字节, 避免稍后误当 live 发送历史通知
let dateKey = WorkflowStorage.dateKey(for: Date())
let stat = WorkflowStorage.fileStat(at: WorkflowStorage.eventLogURL(for: dateKey))
activeDateKey = dateKey
@@ -167,9 +167,9 @@ actor HookEventTailReader {
let todayKey = WorkflowStorage.dateKey(for: Date())
if todayKey != activeDateKey {
- // 跨零点先读完旧文件尾部,再切到新日期文件。
+ // 跨零点先读完旧文件尾部, 再切到新日期文件
guard await readAppendedLines() else {
- // bootstrap 已经完成切日;临时失败则保留旧日期,下一轮继续重试。
+ // bootstrap 已经完成切日; 临时失败则保留旧日期, 下一轮继续重试
return
}
activeDateKey = todayKey
@@ -180,7 +180,7 @@ actor HookEventTailReader {
_ = await readAppendedLines()
}
- /// 返回是否读到当前文件上界;触发重新 bootstrap 或读取中断时为 false。
+ /// 返回是否读到当前文件上界; 触发重新 bootstrap 或读取中断时为 false
private func readAppendedLines() async -> Bool {
let url = activeFileURL
let stat = WorkflowStorage.fileStat(at: url)
@@ -213,7 +213,7 @@ actor HookEventTailReader {
return streamResult.didReachUpperBound
}
- /// 返回已处理完整行的绝对 offset 和是否读完固定上界;后续失败时保留此前进度。
+ /// 返回已处理完整行的绝对 offset 和是否读完固定上界; 后续失败时保留此前进度
private func streamEvents(
at url: URL,
from startOffset: UInt64,
@@ -281,7 +281,7 @@ actor HookEventTailReader {
return .completed(at: completeOffset)
}
- /// 从 24 小时窗口之前的事件文件中定向查找 Prompt 起点,供 bootstrap 后回填恢复任务的开始时间。
+ /// 从 24 小时窗口之前的事件文件中定向查找 Prompt 起点, 供 bootstrap 后回填恢复任务的开始时间
func findPromptStartTimes(
for references: [CodexActivityPromptReference]
) -> [CodexActivityPromptReference: Date] {
diff --git a/CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift b/CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift
index 67ceb85..f868abf 100644
--- a/CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift
+++ b/CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift
@@ -163,7 +163,7 @@ nonisolated enum WorkflowHookEventRecorder {
}
}
-/// Hook payload 不直接提供 reviewer 和 effort;从当前 rollout 尾部只提取匹配 turn 的上下文。
+/// Hook payload 不直接提供 reviewer 和 effort; 从当前 rollout 尾部只提取匹配 turn 的上下文
private nonisolated enum WorkflowTurnContextReader {
static func context(
transcriptPath: String,
diff --git a/CodexBar/Services/Workflow/WorkflowService.swift b/CodexBar/Services/Workflow/WorkflowService.swift
index fccd4a7..d96565a 100644
--- a/CodexBar/Services/Workflow/WorkflowService.swift
+++ b/CodexBar/Services/Workflow/WorkflowService.swift
@@ -30,24 +30,67 @@ actor WorkflowService {
performMaintenanceIfNeeded()
}
- let aggregates = loadDailyAggregates() ?? []
+ return await makeSnapshot(
+ localAggregates: loadDailyAggregates() ?? [],
+ synchronize: synchronize
+ )
+ }
+
+ private func makeSnapshot(
+ localAggregates: [WorkflowDailyAggregate],
+ synchronize: Bool
+ ) async -> WorkflowSnapshot {
let syncSnapshot: WorkflowSyncSnapshot = if synchronize {
- await syncService.synchronizeIfEnabled(localAggregates: aggregates)
+ await syncService.synchronizeIfEnabled(localAggregates: localAggregates)
} else {
await syncService.snapshotFromCacheIfEnabled()
}
- guard !aggregates.isEmpty || !syncSnapshot.records.isEmpty else {
+ guard !localAggregates.isEmpty || !syncSnapshot.records.isEmpty else {
return .empty
}
return WorkflowSnapshot(
- localAggregates: aggregates,
+ localAggregates: localAggregates,
syncedRecords: syncSnapshot.records,
currentDeviceId: syncSnapshot.currentDeviceId
)
}
+ /// 以指定日期范围内的本机原始事件为权威来源重建, 并安排替换当前设备的同日云端贡献
+ fileprivate func rebuildData(
+ for dateKeys: [String],
+ synchronize: Bool
+ ) async throws -> WorkflowDataRebuildOutcome {
+ let normalizedDateKeys = Set(dateKeys).sorted()
+ guard !normalizedDateKeys.isEmpty else {
+ throw WorkflowDataRebuildError.sourceUnavailable
+ }
+
+ var rebuildResults = [WorkflowMaintenanceResult]()
+ do {
+ for dateKey in normalizedDateKeys {
+ try rebuildResults.append(rebuildLocalData(for: dateKey))
+ }
+ } catch {
+ try? await syncService.markReplacementNeeded(for: rebuildResults.map(\.dateKey))
+ throw error
+ }
+ try await syncService.markReplacementNeeded(for: normalizedDateKeys)
+
+ let snapshot = await makeSnapshot(
+ localAggregates: loadDailyAggregates() ?? [],
+ synchronize: synchronize
+ )
+ let summary = await WorkflowDataRebuildSummary(
+ rebuiltDateCount: rebuildResults.count,
+ eventCount: rebuildResults.reduce(0) { $0 + $1.aggregate.eventCount },
+ corruptLineCount: rebuildResults.reduce(0) { $0 + $1.corrupt },
+ isSyncReplacementPending: syncService.hasPendingReplacement(for: normalizedDateKeys)
+ )
+ return WorkflowDataRebuildOutcome(snapshot: snapshot, summary: summary)
+ }
+
private func loadDailyAggregates() -> [WorkflowDailyAggregate]? {
guard let data = try? Data(contentsOf: dailyLogURL), !data.isEmpty else {
return nil
@@ -61,6 +104,67 @@ actor WorkflowService {
return WorkflowDailyAggregate.normalized(aggregates: aggregates)
}
+ private func rebuildLocalData(for dateKey: String) throws -> WorkflowMaintenanceResult {
+ let task = try prepareRebuildTask(for: dateKey)
+ var aggregates = loadDailyAggregates() ?? []
+
+ do {
+ let result = try buildDailyAggregate(for: task)
+ guard try commit(result, aggregates: &aggregates),
+ rebuildWasCommitted(result) else {
+ throw WorkflowDataRebuildError.sourceChanged
+ }
+ return result
+ } catch {
+ markDirty(dateKey)
+ throw error
+ }
+ }
+
+ private func prepareRebuildTask(for dateKey: String) throws -> WorkflowMaintenanceTask {
+ let retentionCutoffKey = WorkflowStorage.dateKey(for: WorkflowStorage.retentionCutoffDate())
+ guard WorkflowStorage.isValidDateKey(dateKey), dateKey >= retentionCutoffKey else {
+ throw WorkflowDataRebuildError.sourceUnavailable
+ }
+
+ return try WorkflowStorage.withExclusiveLock {
+ guard let stat = WorkflowStorage.fileStat(at: eventLogURL(for: dateKey)),
+ stat.size > 0 else {
+ throw WorkflowDataRebuildError.sourceUnavailable
+ }
+
+ var state = WorkflowStorage.loadMaintenanceState()
+ state.startNewSourceGeneration(
+ for: dateKey,
+ isFresh: false,
+ fileIdentifier: stat.identifier
+ )
+ try WorkflowStorage.saveMaintenanceState(state)
+
+ guard let day = state.days[dateKey] else {
+ throw WorkflowDataRebuildError.sourceUnavailable
+ }
+ return dirtyTask(for: dateKey, day: day, size: stat.size)
+ }
+ }
+
+ private func rebuildWasCommitted(_ result: WorkflowMaintenanceResult) -> Bool {
+ let dailyGeneration = loadDailyAggregates()?
+ .first(where: { $0.date == result.dateKey })?
+ .sourceGeneration
+ guard dailyGeneration == result.aggregate.sourceGeneration else {
+ return false
+ }
+
+ return (try? WorkflowStorage.withExclusiveLock {
+ guard let day = WorkflowStorage.loadMaintenanceState().days[result.dateKey] else {
+ return false
+ }
+ return day.sourceGeneration == result.aggregate.sourceGeneration
+ && day.offset == result.size
+ }) ?? false
+ }
+
private func performMaintenanceIfNeeded() {
do {
let tasks = try prepareMaintenanceTasks()
@@ -453,7 +557,7 @@ actor WorkflowService {
}
}
- /// 锁内确认读取期间仍是同一份追加源;断代时换 generation 并等待重建
+ /// 锁内确认读取期间仍是同一份追加源; 断代时换 generation 并等待重建
private func validatedEventLogSize(
for result: WorkflowMaintenanceResult,
state: inout WorkflowMaintenanceState
@@ -748,6 +852,19 @@ nonisolated enum WorkflowStorage {
.sorted()
}
+ /// 返回保留窗口内且本机原始事件文件非空的日期, 供设置页标记和筛选实际重建项
+ static func rebuildableEventDateKeys(
+ in directoryURL: URL = eventsDirectoryURL()
+ ) -> [String] {
+ let cutoffKey = dateKey(for: retentionCutoffDate())
+ return eventLogDateKeys(in: directoryURL)
+ .filter { dateKey in
+ dateKey >= cutoffKey
+ && fileSize(at: eventLogURL(for: dateKey, in: directoryURL)) > 0
+ }
+ .sorted(by: >)
+ }
+
static func retentionCutoffDate(today: Date = Date(), calendar: Calendar = .current) -> Date {
cutoffDate(dayCount: retentionDayCount, today: today, calendar: calendar)
}
@@ -949,7 +1066,7 @@ nonisolated struct WorkflowMaintenanceState: Codable, Equatable {
}
private static func normalizedDates(_ dates: [String]) -> [String] {
- Array(Set(dates.filter { WorkflowStorage.isValidDateKey($0) })).sorted()
+ Set(dates.filter(WorkflowStorage.isValidDateKey)).sorted()
}
private static func newSourceGeneration() -> String {
@@ -986,6 +1103,32 @@ private nonisolated struct WorkflowMaintenanceResult {
let boundaryHash: String?
}
+nonisolated struct WorkflowDataRebuildSummary: Equatable, Sendable {
+ let rebuiltDateCount: Int
+ let eventCount: Int
+ let corruptLineCount: Int
+ let isSyncReplacementPending: Bool
+}
+
+private nonisolated struct WorkflowDataRebuildOutcome {
+ let snapshot: WorkflowSnapshot
+ let summary: WorkflowDataRebuildSummary
+}
+
+private nonisolated enum WorkflowDataRebuildError: LocalizedError {
+ case sourceUnavailable
+ case sourceChanged
+
+ var errorDescription: String? {
+ switch self {
+ case .sourceUnavailable:
+ "没有可重建的本地数据"
+ case .sourceChanged:
+ "本地数据发生变化, 请重试"
+ }
+ }
+}
+
/// UI 层的工作流状态, 节流普通刷新, 维护刷新由上层调度器合并
@MainActor
final class WorkflowViewModel: ObservableObject {
@@ -1045,4 +1188,23 @@ final class WorkflowViewModel: ObservableObject {
self.snapshot = snapshot
lastRefreshedAt = Date()
}
+
+ func rebuildData(
+ for dateKeys: [String],
+ synchronize: Bool
+ ) async throws -> WorkflowDataRebuildSummary {
+ refreshCoordinator.cancel()
+ isRefreshing = true
+ defer {
+ isRefreshing = false
+ }
+
+ let outcome = try await service.rebuildData(
+ for: dateKeys,
+ synchronize: synchronize
+ )
+ snapshot = outcome.snapshot
+ lastRefreshedAt = Date()
+ return outcome.summary
+ }
}
diff --git a/CodexBar/Services/Workflow/WorkflowSyncScheduler.swift b/CodexBar/Services/Workflow/WorkflowSyncScheduler.swift
index 713ea7b..6b5af17 100644
--- a/CodexBar/Services/Workflow/WorkflowSyncScheduler.swift
+++ b/CodexBar/Services/Workflow/WorkflowSyncScheduler.swift
@@ -3,6 +3,9 @@ import Foundation
/// 合并工作流维护刷新中的同步请求, 避免频繁开关产生重复同步
@MainActor
final class WorkflowSyncScheduler {
+ typealias RebuildCompletion = (Result<WorkflowDataRebuildSummary, Error>) -> Void
+ typealias RebuildHandler = ([String], @escaping RebuildCompletion) -> Void
+
private static let syncCooldown: TimeInterval = 8
private let viewModel: WorkflowViewModel
@@ -10,6 +13,7 @@ final class WorkflowSyncScheduler {
private var isRunning = false
private var pendingSync = false
private var pendingLocalMaintenance = false
+ private var pendingRebuild: RebuildRequest?
private var cooldownTask: Task<Void, Never>?
private var lastSyncFinishedAt: Date?
@@ -45,6 +49,16 @@ final class WorkflowSyncScheduler {
drain()
}
+ func requestRebuild(
+ for dateKeys: [String],
+ completion: @escaping RebuildCompletion
+ ) {
+ pendingRebuild?.completion(.failure(CancellationError()))
+ pendingRebuild = RebuildRequest(dateKeys: dateKeys, completion: completion)
+ cancelCooldownTask()
+ drain()
+ }
+
func clearPendingSync() {
pendingSync = false
cancelCooldownTask()
@@ -59,6 +73,8 @@ final class WorkflowSyncScheduler {
func cancel() {
clearPendingMaintenance()
+ pendingRebuild?.completion(.failure(CancellationError()))
+ pendingRebuild = nil
}
private func drain() {
@@ -66,6 +82,11 @@ final class WorkflowSyncScheduler {
return
}
+ if let pendingRebuild {
+ startRebuild(pendingRebuild)
+ return
+ }
+
let canSync = pendingSync && canSynchronize()
if canSync {
if remainingSyncCooldown() <= 0 {
@@ -121,6 +142,37 @@ final class WorkflowSyncScheduler {
drain()
}
+ private func startRebuild(_ request: RebuildRequest) {
+ isRunning = true
+ pendingRebuild = nil
+ let synchronize = canSynchronize()
+
+ Task { @MainActor [weak self] in
+ guard let self else {
+ return
+ }
+
+ let result: Result<WorkflowDataRebuildSummary, Error>
+ do {
+ result = try await .success(
+ viewModel.rebuildData(
+ for: request.dateKeys,
+ synchronize: synchronize
+ )
+ )
+ } catch {
+ result = .failure(error)
+ }
+
+ isRunning = false
+ if synchronize {
+ lastSyncFinishedAt = Date()
+ }
+ request.completion(result)
+ drain()
+ }
+ }
+
private func remainingSyncCooldown() -> TimeInterval {
guard let lastSyncFinishedAt else {
return 0
@@ -151,4 +203,9 @@ final class WorkflowSyncScheduler {
cooldownTask?.cancel()
cooldownTask = nil
}
+
+ private struct RebuildRequest {
+ let dateKeys: [String]
+ let completion: RebuildCompletion
+ }
}
diff --git a/CodexBar/Services/Workflow/WorkflowSyncService.swift b/CodexBar/Services/Workflow/WorkflowSyncService.swift
index 79c7fe4..c398c29 100644
--- a/CodexBar/Services/Workflow/WorkflowSyncService.swift
+++ b/CodexBar/Services/Workflow/WorkflowSyncService.swift
@@ -34,6 +34,27 @@ actor WorkflowSyncService {
return snapshot(from: state)
}
+ /// 显式重建后, 将所选日期标记为当前设备云端贡献的权威替换来源
+ func markReplacementNeeded(for dates: [String]) throws {
+ let validDates = Set(dates.filter(WorkflowStorage.isValidDateKey))
+ guard !validDates.isEmpty else {
+ return
+ }
+
+ var state = loadState()
+ state.replacementDates = Set(state.replacementDates)
+ .union(validDates)
+ .sorted()
+ for date in validDates {
+ state.hashByDate.removeValue(forKey: date)
+ }
+ try saveState(state)
+ }
+
+ func hasPendingReplacement(for dates: [String]) -> Bool {
+ !Set(loadState().replacementDates).isDisjoint(with: dates)
+ }
+
func synchronizeIfEnabled(
localAggregates: [WorkflowDailyAggregate]
) async -> WorkflowSyncSnapshot {
@@ -59,9 +80,20 @@ actor WorkflowSyncService {
let deviceId = try await resolveCurrentDeviceId()
try resetStateIfDeviceChanged(deviceId, state: &state)
try await migrateStateIfNeeded(&state)
- try await refreshCacheFromRemote()
let localByDate = Self.syncedAggregatesByDate(localAggregates)
+ if state.replacementDates.isEmpty {
+ try await refreshCacheFromRemote()
+ } else {
+ // 替换前全量拉取, 避免增量缓存遗漏同设备同日期的旧 generation
+ try await rebuildCacheFromRemote()
+ try await preparePendingReplacements(
+ localByDate: localByDate,
+ deviceId: deviceId,
+ state: &state
+ )
+ }
+
let forceBackfill = WorkflowSyncSettings.needsBackfill()
let confirmedDates = try await uploadChangedAggregates(
localByDate: localByDate,
@@ -69,6 +101,12 @@ actor WorkflowSyncService {
state: &state
)
+ let completedReplacementDates = Set(state.replacementDates).intersection(confirmedDates)
+ if !completedReplacementDates.isEmpty {
+ state.replacementDates.removeAll { completedReplacementDates.contains($0) }
+ try saveState(state)
+ }
+
if forceBackfill,
backfillCompleted(localByDate: localByDate, confirmedDates: confirmedDates) {
WorkflowSyncSettings.clearBackfillRequest()
@@ -99,7 +137,10 @@ actor WorkflowSyncService {
try removeCursorIfPresent()
try saveCachedRecords([])
- let resetState = WorkflowSyncState(deviceId: deviceId)
+ let resetState = WorkflowSyncState(
+ deviceId: deviceId,
+ replacementDates: state.replacementDates
+ )
try saveState(resetState)
state = resetState
}
@@ -123,11 +164,18 @@ actor WorkflowSyncService {
}
private func snapshot(from state: WorkflowSyncState) -> WorkflowSyncSnapshot {
- WorkflowSyncSnapshot(
- records: state.deviceId == nil
- ? []
- : Self.filteredRetained(records: loadCachedRecords()),
- currentDeviceId: state.deviceId
+ guard let deviceId = state.deviceId else {
+ return .disabled
+ }
+
+ let replacementDates = Set(state.replacementDates)
+ let records = Self.filteredRetained(records: loadCachedRecords()).filter { record in
+ record.deviceId != deviceId || !replacementDates.contains(record.date)
+ }
+
+ return WorkflowSyncSnapshot(
+ records: records,
+ currentDeviceId: deviceId
)
}
}
@@ -289,6 +337,68 @@ private extension WorkflowSyncService {
try saveState(state)
}
+ func preparePendingReplacements(
+ localByDate: [String: LocalSyncAggregate],
+ deviceId: String,
+ state: inout WorkflowSyncState
+ ) async throws {
+ let replacementDates = Set(state.replacementDates).intersection(localByDate.keys)
+ guard !replacementDates.isEmpty else {
+ return
+ }
+
+ let cachedRecords = loadCachedRecords()
+ let recordsToReplace = cachedRecords.filter {
+ $0.deviceId == deviceId && replacementDates.contains($0.date)
+ }
+ var recordIDs = Set(recordsToReplace.map {
+ CKRecord.ID(recordName: $0.id, zoneID: syncZoneID)
+ })
+
+ for date in replacementDates {
+ recordIDs.insert(recordID(deviceId: deviceId, date: date))
+ if let generation = localByDate[date]?.aggregate.sourceGeneration {
+ recordIDs.insert(recordID(deviceId: deviceId, date: date, generation: generation))
+ }
+ }
+
+ try await deleteRecords(Array(recordIDs))
+
+ try saveCachedRecords(cachedRecords.filter {
+ $0.deviceId != deviceId || !replacementDates.contains($0.date)
+ })
+ for date in replacementDates {
+ state.hashByDate.removeValue(forKey: date)
+ }
+ try saveState(state)
+ }
+
+ func deleteRecords(_ recordIDs: [CKRecord.ID]) async throws {
+ for batchStart in stride(from: 0, to: recordIDs.count, by: Metrics.uploadBatchSize) {
+ let batchEnd = min(batchStart + Metrics.uploadBatchSize, recordIDs.count)
+ let batch = Array(recordIDs[batchStart ..< batchEnd])
+ let result = try await database.modifyRecords(
+ saving: [],
+ deleting: batch,
+ savePolicy: .changedKeys,
+ atomically: false
+ )
+
+ for recordID in batch {
+ switch result.deleteResults[recordID] {
+ case .success:
+ continue
+ case let .failure(error as CKError) where error.code == .unknownItem:
+ continue
+ case let .failure(error):
+ throw error
+ case nil:
+ throw WorkflowSyncError.missingRecordResult
+ }
+ }
+ }
+ }
+
func applyConfirmedHashes(
_ confirmedBatch: [ConfirmedHash],
to state: inout WorkflowSyncState
@@ -525,26 +635,54 @@ private extension WorkflowSyncService {
NSSortDescriptor(key: FieldKeys.date, ascending: true)
]
+ let matches = try await fetchAllRecordMatches(matching: query)
+ return try Self.remoteDailyRecords(from: matches)
+ }
+
+ func fetchExpiredCurrentDeviceRecordIDs(
+ deviceId: String,
+ cutoffKey: String
+ ) async throws -> [CKRecord.ID] {
+ let query = CKQuery(
+ recordType: RecordTypes.dailyAggregate,
+ predicate: NSPredicate(
+ format: "%K == %@ AND %K < %@",
+ FieldKeys.deviceId,
+ deviceId,
+ FieldKeys.date,
+ cutoffKey
+ )
+ )
+
+ return try await fetchAllRecordMatches(matching: query).map { recordID, result in
+ _ = try result.get()
+ return recordID
+ }
+ }
+
+ func fetchAllRecordMatches(
+ matching query: CKQuery
+ ) async throws -> [(CKRecord.ID, Result<CKRecord, Error>)] {
let firstPage = try await database.records(
matching: query,
inZoneWith: syncZoneID,
desiredKeys: nil,
resultsLimit: Metrics.queryFetchLimit
)
- var records = try Self.remoteDailyRecords(from: firstPage.matchResults)
- var queryCursor = firstPage.queryCursor
+ var matches = firstPage.matchResults
+ var cursor = firstPage.queryCursor
- while let cursor = queryCursor {
+ while let currentCursor = cursor {
let page = try await database.records(
- continuingMatchFrom: cursor,
+ continuingMatchFrom: currentCursor,
desiredKeys: nil,
resultsLimit: Metrics.queryFetchLimit
)
- try records.append(contentsOf: Self.remoteDailyRecords(from: page.matchResults))
- queryCursor = page.queryCursor
+ matches.append(contentsOf: page.matchResults)
+ cursor = page.queryCursor
}
- return records
+ return matches
}
func establishCursorBaseline(cachedRecords: [WorkflowSyncedDailyRecord]) async {
@@ -595,45 +733,35 @@ private extension WorkflowSyncService {
let cutoffKey = WorkflowStorage.dateKey(for: WorkflowStorage.retentionCutoffDate())
let expiredDates = Set(state.hashByDate.keys.filter { $0 < cutoffKey })
- let expiredRecords = loadCachedRecords().filter {
- $0.deviceId == deviceId && $0.date < cutoffKey
- }
- var recordNames = Set(expiredRecords.map(\.id))
+ state.replacementDates.removeAll { $0 < cutoffKey }
+ var recordIDs = try await Set(
+ fetchExpiredCurrentDeviceRecordIDs(
+ deviceId: deviceId,
+ cutoffKey: cutoffKey
+ )
+ )
for date in expiredDates {
- recordNames.insert(
- WorkflowSyncedDailyRecord.legacyRecordName(deviceId: deviceId, date: date)
+ recordIDs.insert(
+ CKRecord.ID(
+ recordName: WorkflowSyncedDailyRecord.legacyRecordName(
+ deviceId: deviceId,
+ date: date
+ ),
+ zoneID: syncZoneID
+ )
)
}
- guard !recordNames.isEmpty else {
- for date in expiredDates {
- state.hashByDate.removeValue(forKey: date)
- }
- state.lastPrunedDate = today
- return
- }
-
- let recordIDs = recordNames.map {
- CKRecord.ID(recordName: $0, zoneID: syncZoneID)
- }
-
- let result = try await database.modifyRecords(
- saving: [],
- deleting: recordIDs,
- savePolicy: .changedKeys,
- atomically: false
- )
-
- let allDeleted = recordIDs.allSatisfy { recordID in
- Self.isSuccessfulDeleteResult(result.deleteResults[recordID])
+ if !recordIDs.isEmpty {
+ try await deleteRecords(
+ recordIDs.sorted { $0.recordName < $1.recordName }
+ )
}
- if allDeleted {
- for date in expiredDates {
- state.hashByDate.removeValue(forKey: date)
- }
- state.lastPrunedDate = today
+ for date in expiredDates {
+ state.hashByDate.removeValue(forKey: date)
}
+ state.lastPrunedDate = today
}
func resolveCurrentDeviceId() async throws -> String {
@@ -1003,17 +1131,6 @@ private extension WorkflowSyncService {
}
}
- static func isSuccessfulDeleteResult(_ result: Result<Void, Error>?) -> Bool {
- switch result {
- case .success:
- true
- case let .failure(error as CKError) where error.code == .unknownItem:
- true
- case .failure, .none:
- false
- }
- }
-
static func intValue(_ value: CKRecordValue?) -> Int {
optionalIntValue(value) ?? 0
}
@@ -1079,7 +1196,7 @@ private extension WorkflowSyncService {
}
}
-/// records 包含所有设备的脱敏聚合;currentDeviceId 用于展示时替换而不是叠加本机云端副本
+/// records 包含所有设备的脱敏聚合; currentDeviceId 用于展示时替换而不是叠加本机云端副本
nonisolated struct WorkflowSyncSnapshot: Equatable {
let records: [WorkflowSyncedDailyRecord]
let currentDeviceId: String?
@@ -1098,6 +1215,7 @@ private nonisolated struct WorkflowSyncState: Codable, Equatable {
var schema: Int
var deviceId: String?
var hashByDate: [String: String]
+ var replacementDates: [String]
var lastUploadAt: Date?
var lastPrunedDate: String?
@@ -1105,12 +1223,14 @@ private nonisolated struct WorkflowSyncState: Codable, Equatable {
schema: Int = Self.currentSchema,
deviceId: String? = nil,
hashByDate: [String: String] = [:],
+ replacementDates: [String] = [],
lastUploadAt: Date? = nil,
lastPrunedDate: String? = nil
) {
self.schema = schema
self.deviceId = deviceId
self.hashByDate = hashByDate
+ self.replacementDates = replacementDates
self.lastUploadAt = lastUploadAt
self.lastPrunedDate = lastPrunedDate
}
@@ -1122,6 +1242,13 @@ private nonisolated struct WorkflowSyncState: Codable, Equatable {
deviceId = try container.decodeIfPresent(String.self, forKey: .deviceId)
hashByDate = try container.decodeIfPresent([String: String].self, forKey: .hashByDate)
?? [:]
+ let decodedReplacementDates = try container.decodeIfPresent(
+ [String].self,
+ forKey: .replacementDates
+ ) ?? []
+ replacementDates = Set(
+ decodedReplacementDates.filter(WorkflowStorage.isValidDateKey)
+ ).sorted()
lastUploadAt = try container.decodeIfPresent(Date.self, forKey: .lastUploadAt)
lastPrunedDate = try container.decodeIfPresent(String.self, forKey: .lastPrunedDate)
}
@@ -1130,6 +1257,7 @@ private nonisolated struct WorkflowSyncState: Codable, Equatable {
case schema
case deviceId
case hashByDate
+ case replacementDates
case lastUploadAt
case lastPrunedDate
}
diff --git a/CodexBar/Views/Menu/CodexActivityCard.swift b/CodexBar/Views/Menu/CodexActivityCard.swift
index fbd3af8..ffe6f7a 100644
--- a/CodexBar/Views/Menu/CodexActivityCard.swift
+++ b/CodexBar/Views/Menu/CodexActivityCard.swift
@@ -1,7 +1,7 @@
import SwiftUI
-/// Hook 开启时常驻的固定高度活动摘要,使用菜单面板共享的逐秒时间。
-/// 在卡片内部观察 activityMonitor 与逐秒时间, 让 1Hz 失效范围只覆盖本卡片而不是整个菜单树。
+/// Hook 开启时常驻的固定高度活动摘要, 使用菜单面板共享的逐秒时间
+/// 在卡片内部观察 activityMonitor 与逐秒时间, 让 1Hz 失效范围只覆盖本卡片而不是整个菜单树
struct CodexActivityCard: View {
@ObservedObject var activityMonitor: CodexActivityMonitor
@ObservedObject var presentationState: CodexActivityCenterPresentationState
@@ -213,7 +213,7 @@ struct CodexActivityCard: View {
}
}
-/// 卡片自行处理 hover/选中描边,按钮样式不再修改 label 的前景色或透明度。
+/// 卡片自行处理 hover/选中描边, 按钮样式不再修改 label 的前景色或透明度
private struct ActivityCardButtonStyle: ButtonStyle {
func makeBody(configuration: Configuration) -> some View {
configuration.label
diff --git a/CodexBar/Views/Menu/CodexActivityCenterView.swift b/CodexBar/Views/Menu/CodexActivityCenterView.swift
index 5f586ad..15401be 100644
--- a/CodexBar/Views/Menu/CodexActivityCenterView.swift
+++ b/CodexBar/Views/Menu/CodexActivityCenterView.swift
@@ -1,7 +1,7 @@
import Combine
import SwiftUI
-/// 活动卡片与任务中心共享的显隐和逐秒时间状态。
+/// 活动卡片与任务中心共享的显隐和逐秒时间状态
@MainActor
final class CodexActivityCenterPresentationState: ObservableObject {
@Published var isPresented = false
@@ -34,14 +34,14 @@ final class CodexActivityCenterPresentationState: ObservableObject {
}
}
-/// 点击活动卡片时传给 AppKit 控制器的定位信息。
+/// 点击活动卡片时传给 AppKit 控制器的定位信息
@MainActor
struct CodexActivityCenterPanelContext {
let anchorProvider: ScreenFrameProvider
let preferredSide: UsageHeatmapDetailSide
}
-/// 并发任务中心,实时展示全部等待、运行、最近完成和最近终止任务。
+/// 并发任务中心, 实时展示全部等待; 运行; 最近完成和最近终止任务
struct CodexActivityCenterView: View {
@ObservedObject var activityMonitor: CodexActivityMonitor
@ObservedObject var presentationState: CodexActivityCenterPresentationState
diff --git a/CodexBar/Views/Menu/CodexStatusMenuView.swift b/CodexBar/Views/Menu/CodexStatusMenuView.swift
index f560b1d..651833b 100644
--- a/CodexBar/Views/Menu/CodexStatusMenuView.swift
+++ b/CodexBar/Views/Menu/CodexStatusMenuView.swift
@@ -1,13 +1,13 @@
import Combine
import SwiftUI
-/// 菜单面板可见状态,用于控制逐秒时间更新。
+/// 菜单面板可见状态, 用于控制逐秒时间更新
@MainActor
final class MenuSurfaceVisibilityState: ObservableObject {
@Published var isVisible = false
}
-/// 菜单栏弹出面板根视图, 汇总账号、实时活动、额度、token、同步状态和更新时间
+/// 菜单栏弹出面板根视图, 汇总账号; 实时活动; 额度; token; 同步状态和更新时间
struct CodexStatusMenuView: View {
static let menuWidth: CGFloat = Metrics.padding * 2 + MenuMetrics.panelPadding * 2 + UsageHeatmap.Metrics.totalWidth
@@ -63,7 +63,7 @@ private extension CodexStatusMenuView {
dataSection(snapshot)
} else {
- // 仅展示未登录 / 初始化失败两种特殊状态, 其余错误只进日志
+ // 仅展示未登录/初始化失败两种特殊状态, 其余错误只进日志
StatusAccountCard(
loadState: viewModel.loadState,
isRefreshing: viewModel.isRefreshing,
diff --git a/CodexBar/Views/Settings/AppSettingsView.swift b/CodexBar/Views/Settings/AppSettingsView.swift
index 1364db8..7769163 100644
--- a/CodexBar/Views/Settings/AppSettingsView.swift
+++ b/CodexBar/Views/Settings/AppSettingsView.swift
@@ -1,7 +1,7 @@
import AppKit
import SwiftUI
-/// 设置窗口根视图, 汇总启动项、显示、Hook、同步、通知、快捷键和版本信息
+/// 设置窗口根视图, 汇总启动项; 显示; Hook; 同步; 通知; 快捷键和版本信息
struct AppSettingsView: View {
@EnvironmentObject private var statusViewModel: CodexStatusViewModel
@EnvironmentObject private var appUpdater: AppUpdater
@@ -14,9 +14,15 @@ struct AppSettingsView: View {
@ObservedObject var mainPanelSettings: MainPanelSettings
@ObservedObject var notificationSettings: NotificationSettings
let onSyncChanged: (Bool) -> Void
+ let onRebuildWorkflowData: WorkflowSyncScheduler.RebuildHandler
let onNotificationOptionsAction: (NotificationOptionsPanelAction) -> Void
@State private var notificationRowFrame: CGRect?
@State private var shouldOpenNotificationOptionsAfterAuthorization = false
+ @State private var rebuildableDates = [String]()
+ @State private var selectedRebuildRange: RebuildDateRange?
+ @State private var isShowingRebuildConfirmation = false
+ @State private var isRebuildingWorkflowData = false
+ @State private var rebuildStatus: RebuildStatus?
var body: some View {
VStack(alignment: .leading, spacing: Metrics.sectionSpacing) {
@@ -33,6 +39,8 @@ struct AppSettingsView: View {
LiquidGlassDivider()
syncRow
LiquidGlassDivider()
+ rebuildWorkflowDataRow
+ LiquidGlassDivider()
notificationRow
LiquidGlassDivider()
hotKeyRow
@@ -73,6 +81,7 @@ struct AppSettingsView: View {
appUpdater.refreshAutomaticCheckSetting()
refreshCodexVersionSection()
notificationSettings.refreshAuthorizationStatus()
+ refreshRebuildableDates()
}
.onReceive(NotificationCenter.default.publisher(for: NSApplication.didBecomeActiveNotification)) { _ in
codexHookSettings.refresh()
@@ -82,6 +91,23 @@ struct AppSettingsView: View {
codexHookSettings.verifyInstalledHooks()
refreshCodexVersionSection()
notificationSettings.refreshAuthorizationStatus()
+ refreshRebuildableDates()
+ }
+ .onReceive(NotificationCenter.default.publisher(for: .settingsWindowDidOpen)) { _ in
+ selectedRebuildRange = nil
+ isShowingRebuildConfirmation = false
+ clearRebuildStatus()
+ }
+ .alert(
+ "批量重建 \(selectedRebuildDateKeys.count) 天的数据?",
+ isPresented: $isShowingRebuildConfirmation
+ ) {
+ Button("取消", role: .cancel) {}
+ Button("重建", role: .destructive) {
+ rebuildWorkflowData()
+ }
+ } message: {
+ Text("将从本机原始 Hook 事件重新统计 \(selectedRebuildRange?.displayText ?? "")\n并在下次同步时替换当前设备对应日期的云端聚合")
}
}
}
@@ -186,7 +212,7 @@ private extension AppSettingsView {
menuBarQuotaSettings.selection != .off
}
- /// Hook 未开启时显示为关闭并置灰, 不修改持久化的 showsTaskCenter。
+ /// Hook 未开启时显示为关闭并置灰, 不修改持久化的 showsTaskCenter
var taskCenterRow: some View {
let isDisplayedOn = codexHookSettings.isEnabled && mainPanelSettings.showsTaskCenter
@@ -276,6 +302,118 @@ private extension AppSettingsView {
)
}
+ var rebuildWorkflowDataRow: some View {
+ VStack(alignment: .leading, spacing: 4) {
+ HStack(spacing: SettingsRowMetrics.spacing) {
+ Image(systemName: "arrow.clockwise.circle")
+ .frame(width: SettingsRowMetrics.iconWidth)
+ .foregroundStyle(.tint)
+
+ Text("重建数据")
+ .lineLimit(1)
+ .fixedSize(horizontal: true, vertical: false)
+
+ Spacer(minLength: 4)
+
+ RebuildDatePicker(
+ selection: $selectedRebuildRange,
+ dataDateKeys: Set(rebuildableDates),
+ isEnabled: !isRebuildingWorkflowData
+ )
+ .frame(
+ width: RebuildLayoutMetrics.pickerWidth,
+ height: RebuildLayoutMetrics.controlHeight,
+ alignment: .leading
+ )
+
+ if isRebuildingWorkflowData {
+ ProgressView()
+ .controlSize(.small)
+ .frame(width: RebuildLayoutMetrics.actionWidth)
+ } else {
+ Button("重建") {
+ isShowingRebuildConfirmation = true
+ }
+ .controlSize(.small)
+ .frame(width: RebuildLayoutMetrics.actionWidth)
+ .disabled(selectedRebuildDateKeys.isEmpty)
+ }
+ }
+ .frame(height: RebuildLayoutMetrics.controlHeight)
+
+ let caption = rebuildCaption
+ SettingsCaptionMessageRow(
+ message: caption.message,
+ color: caption.isError ? .red : .secondary
+ )
+ }
+ }
+
+ var rebuildCaption: RebuildStatus {
+ if let rebuildStatus {
+ return rebuildStatus
+ }
+ guard let selectedRebuildRange else {
+ return RebuildStatus(message: "未选择重建日期范围", isError: false)
+ }
+ guard selectedRebuildRange.isComplete else {
+ return RebuildStatus(message: "选择结束日期", isError: false)
+ }
+ if selectedRebuildDateKeys.isEmpty {
+ return RebuildStatus(message: "没有可重建的本地数据", isError: true)
+ }
+ return RebuildStatus(
+ message: "已选择 \(selectedRebuildRange.dayCount) 天",
+ isError: false
+ )
+ }
+
+ var selectedRebuildDateKeys: [String] {
+ guard let selectedRebuildRange, selectedRebuildRange.isComplete else {
+ return []
+ }
+ return rebuildableDates.filter(selectedRebuildRange.contains)
+ }
+
+ func refreshRebuildableDates() {
+ rebuildableDates = WorkflowStorage.rebuildableEventDateKeys()
+ }
+
+ func rebuildWorkflowData() {
+ let dateKeys = selectedRebuildDateKeys
+ guard !dateKeys.isEmpty, !isRebuildingWorkflowData else {
+ return
+ }
+
+ isRebuildingWorkflowData = true
+ clearRebuildStatus()
+ onRebuildWorkflowData(dateKeys) { result in
+ isRebuildingWorkflowData = false
+ refreshRebuildableDates()
+
+ switch result {
+ case let .success(summary):
+ var message = "共处理 \(summary.rebuiltDateCount) 天, 包含 \(summary.eventCount) 条数据"
+ if summary.corruptLineCount > 0 {
+ message += ", 跳过 \(summary.corruptLineCount) 条无效数据"
+ }
+ if summary.isSyncReplacementPending {
+ message += "; 云端替换将在同步可用后继续"
+ }
+ rebuildStatus = RebuildStatus(message: message, isError: false)
+ case let .failure(error):
+ rebuildStatus = RebuildStatus(
+ message: "重建失败: \(error.localizedDescription)",
+ isError: true
+ )
+ }
+ }
+ }
+
+ func clearRebuildStatus() {
+ rebuildStatus = nil
+ }
+
/// 主开关行保留在设置窗口内, 子选项在右侧子面板中展开
var notificationRow: some View {
VStack(alignment: .leading, spacing: 4) {
@@ -450,6 +588,352 @@ private extension AppSettingsView {
}
}
+private enum RebuildLayoutMetrics {
+ static let pickerWidth: CGFloat = 190
+ static let controlHeight: CGFloat = 26
+ static let actionWidth: CGFloat = 42
+}
+
+private struct RebuildDatePicker: View {
+ @Binding var selection: RebuildDateRange?
+ let dataDateKeys: Set<String>
+ let isEnabled: Bool
+
+ @State private var isPresented = false
+ @State private var displayedMonth = Date()
+
+ private enum Metrics {
+ static let daySize: CGFloat = 28
+ static let columnSpacing: CGFloat = 6
+ static let visibleWeekCount = 6
+ static let popoverWidth: CGFloat = 260
+ static let popoverHeight: CGFloat = 296
+ }
+
+ private static let columns = Array(
+ repeating: GridItem(.fixed(Metrics.daySize), spacing: Metrics.columnSpacing),
+ count: 7
+ )
+ private static let weekdaySymbols = ["一", "二", "三", "四", "五", "六", "日"]
+
+ var body: some View {
+ Button {
+ let focusedDateKey = selection?.endDateKey ?? selection?.startDateKey
+ if let focusedDateKey,
+ let selectedDate = CodexDateFormat.dayDate(from: focusedDateKey) {
+ displayedMonth = startOfMonth(for: selectedDate)
+ }
+ isPresented.toggle()
+ } label: {
+ HStack(spacing: 5) {
+ Image(systemName: "calendar")
+ .font(.system(size: 11, weight: .medium))
+ .foregroundStyle(.tint)
+
+ Text(selection?.displayText ?? "选择日期范围")
+ .font(.caption.monospacedDigit().weight(.medium))
+ .foregroundStyle(.primary)
+ .lineLimit(1)
+ .minimumScaleFactor(0.9)
+
+ Spacer(minLength: 0)
+
+ Image(systemName: "chevron.down")
+ .font(.system(size: 8, weight: .semibold))
+ .foregroundStyle(.secondary)
+ }
+ .padding(.horizontal, 7)
+ .frame(maxWidth: .infinity, minHeight: RebuildLayoutMetrics.controlHeight)
+ .background {
+ RoundedRectangle(cornerRadius: 7, style: .continuous)
+ .fill(Color(nsColor: .controlBackgroundColor).opacity(0.72))
+ }
+ .overlay {
+ RoundedRectangle(cornerRadius: 7, style: .continuous)
+ .strokeBorder(
+ isPresented ? Color.accentColor.opacity(0.70) : Color.primary.opacity(0.12),
+ lineWidth: isPresented ? 1.2 : 0.8
+ )
+ }
+ .shadow(color: .black.opacity(0.06), radius: 2, y: 1)
+ }
+ .buttonStyle(.plain)
+ .disabled(!isEnabled)
+ .help("选择日期范围")
+ .popover(isPresented: $isPresented, arrowEdge: .bottom) {
+ calendarPopover
+ }
+ }
+
+ private var calendarPopover: some View {
+ VStack(spacing: 10) {
+ HStack(spacing: 8) {
+ monthNavigationButton(
+ systemImage: "chevron.left",
+ help: "上个月",
+ offset: -1
+ )
+
+ Spacer()
+
+ Text(monthTitle)
+ .font(.system(.body, design: .rounded).weight(.semibold))
+ .monospacedDigit()
+
+ Spacer()
+
+ monthNavigationButton(
+ systemImage: "chevron.right",
+ help: "下个月",
+ offset: 1
+ )
+ }
+
+ LazyVGrid(columns: Self.columns, spacing: 5) {
+ ForEach(Self.weekdaySymbols, id: \.self) { symbol in
+ Text(symbol)
+ .font(.system(size: 10, weight: .medium))
+ .foregroundStyle(.secondary)
+ .frame(width: Metrics.daySize, height: 18)
+ }
+
+ ForEach(monthDates, id: \.self) { date in
+ dayButton(for: date)
+ }
+ }
+
+ Text(selection?.isComplete == false ? "选择结束日期" : "选择开始日期")
+ .font(.caption2)
+ .foregroundStyle(.secondary)
+ .lineLimit(1)
+ .frame(height: 14)
+ }
+ .padding(12)
+ .frame(width: Metrics.popoverWidth, height: Metrics.popoverHeight)
+ }
+
+ private func monthNavigationButton(
+ systemImage: String,
+ help: String,
+ offset: Int
+ ) -> some View {
+ Button {
+ guard let nextMonth = calendar.date(byAdding: .month, value: offset, to: displayedMonth) else {
+ return
+ }
+ displayedMonth = nextMonth
+ } label: {
+ Image(systemName: systemImage)
+ .font(.system(size: 10, weight: .semibold))
+ .frame(width: 24, height: 22)
+ .background {
+ RoundedRectangle(cornerRadius: 6, style: .continuous)
+ .fill(Color.primary.opacity(0.055))
+ }
+ }
+ .buttonStyle(.plain)
+ .disabled(!canMoveMonth(by: offset))
+ .help(help)
+ }
+
+ private func dayButton(for date: Date) -> some View {
+ let dateKey = WorkflowStorage.dateKey(for: date)
+ let isSelectable = selectableDateRange.contains(calendar.startOfDay(for: date))
+ let hasData = dataDateKeys.contains(dateKey)
+ let isInDisplayedMonth = calendar.isDate(
+ date,
+ equalTo: displayedMonth,
+ toGranularity: .month
+ )
+ let isStart = selection?.startDateKey == dateKey
+ let isEnd = selection?.endDateKey == dateKey
+ let isEndpoint = isStart || isEnd
+ let isInCompletedRange = selection?.contains(dateKey) == true
+ let day = calendar.component(.day, from: date)
+
+ return Button {
+ select(dateKey)
+ } label: {
+ ZStack(alignment: .bottom) {
+ RoundedRectangle(cornerRadius: 7, style: .continuous)
+ .fill(dayBackgroundColor(
+ isEndpoint: isEndpoint,
+ isInCompletedRange: isInCompletedRange
+ ))
+
+ Text(String(day))
+ .font(.system(size: 11, weight: isEndpoint ? .semibold : .regular))
+ .foregroundStyle(dayTextColor(
+ isSelectable: isSelectable,
+ isEndpoint: isEndpoint,
+ isInDisplayedMonth: isInDisplayedMonth
+ ))
+ .frame(maxWidth: .infinity, maxHeight: .infinity)
+
+ if hasData, !isEndpoint {
+ Circle()
+ .fill(Color.accentColor.opacity(0.75))
+ .frame(width: 2.5, height: 2.5)
+ .padding(.bottom, 2)
+ }
+ }
+ .frame(width: Metrics.daySize, height: Metrics.daySize)
+ .contentShape(Rectangle())
+ }
+ .buttonStyle(.plain)
+ .disabled(!isSelectable)
+ }
+
+ private var monthTitle: String {
+ let components = calendar.dateComponents([.year, .month], from: displayedMonth)
+ guard let year = components.year, let month = components.month else {
+ return ""
+ }
+ return String(format: "%04d-%02d", year, month)
+ }
+
+ private var monthDates: [Date] {
+ let monthStart = startOfMonth(for: displayedMonth)
+ let leadingDayCount = (
+ calendar.component(.weekday, from: monthStart) - calendar.firstWeekday + 7
+ ) % 7
+ guard let gridStart = calendar.date(
+ byAdding: .day,
+ value: -leadingDayCount,
+ to: monthStart
+ ) else {
+ return []
+ }
+
+ let visibleDayCount = Self.weekdaySymbols.count * Metrics.visibleWeekCount
+ return (0 ..< visibleDayCount).compactMap { dayOffset in
+ calendar.date(byAdding: .day, value: dayOffset, to: gridStart)
+ }
+ }
+
+ private var calendar: Calendar {
+ var calendar = Calendar(identifier: .gregorian)
+ calendar.locale = Locale(identifier: "zh_CN")
+ calendar.timeZone = .autoupdatingCurrent
+ calendar.firstWeekday = 2
+ return calendar
+ }
+
+ private var selectableDateRange: ClosedRange<Date> {
+ let today = calendar.startOfDay(for: Date())
+ let cutoff = WorkflowStorage.retentionCutoffDate(today: today, calendar: calendar)
+ return cutoff ... today
+ }
+
+ private func startOfMonth(for date: Date) -> Date {
+ let components = calendar.dateComponents([.year, .month], from: date)
+ return calendar.date(from: components) ?? date
+ }
+
+ private func canMoveMonth(by offset: Int) -> Bool {
+ guard let candidate = calendar.date(byAdding: .month, value: offset, to: displayedMonth) else {
+ return false
+ }
+
+ let month = startOfMonth(for: candidate)
+ return month >= startOfMonth(for: selectableDateRange.lowerBound)
+ && month <= startOfMonth(for: selectableDateRange.upperBound)
+ }
+
+ private func select(_ dateKey: String) {
+ if let selection, !selection.isComplete {
+ self.selection = selection.completing(with: dateKey)
+ isPresented = false
+ } else {
+ selection = .starting(at: dateKey)
+ }
+ }
+
+ private func dayBackgroundColor(
+ isEndpoint: Bool,
+ isInCompletedRange: Bool
+ ) -> Color {
+ if isEndpoint {
+ return .accentColor
+ }
+ return isInCompletedRange ? Color.accentColor.opacity(0.16) : .clear
+ }
+
+ private func dayTextColor(
+ isSelectable: Bool,
+ isEndpoint: Bool,
+ isInDisplayedMonth: Bool
+ ) -> Color {
+ if isEndpoint {
+ return .white
+ }
+ if !isInDisplayedMonth {
+ return .codexSecondaryLabel.opacity(isSelectable ? 0.58 : 0.24)
+ }
+ return isSelectable ? .codexLabel : .codexSecondaryLabel.opacity(0.36)
+ }
+}
+
+private struct RebuildDateRange: Equatable {
+ let startDateKey: String
+ let endDateKey: String?
+
+ static func starting(at dateKey: String) -> RebuildDateRange {
+ RebuildDateRange(startDateKey: dateKey, endDateKey: nil)
+ }
+
+ var isComplete: Bool {
+ endDateKey != nil
+ }
+
+ var dayCount: Int {
+ guard let endDateKey,
+ let startDate = CodexDateFormat.dayDate(from: startDateKey),
+ let endDate = CodexDateFormat.dayDate(from: endDateKey) else {
+ return 0
+ }
+
+ var calendar = Calendar(identifier: .gregorian)
+ calendar.timeZone = .autoupdatingCurrent
+ guard let dayDifference = calendar.dateComponents(
+ [.day],
+ from: startDate,
+ to: endDate
+ ).day else {
+ return 0
+ }
+ return dayDifference + 1
+ }
+
+ var displayText: String {
+ guard let endDateKey else {
+ return "\(startDateKey) ~"
+ }
+ return startDateKey == endDateKey
+ ? startDateKey
+ : "\(startDateKey) ~ \(endDateKey)"
+ }
+
+ func completing(with dateKey: String) -> RebuildDateRange {
+ RebuildDateRange(
+ startDateKey: min(startDateKey, dateKey),
+ endDateKey: max(startDateKey, dateKey)
+ )
+ }
+
+ func contains(_ dateKey: String) -> Bool {
+ guard let endDateKey else {
+ return false
+ }
+ return dateKey >= startDateKey && dateKey <= endDateKey
+ }
+}
+
+private struct RebuildStatus {
+ let message: String
+ let isError: Bool
+}
+
private struct SyncRowState {
/// 由 WorkflowSyncSettings.isEffectivelyActive 统一判定, 视图层不再拼接业务谓词
let isActive: Bool
diff --git a/CodexBar/Views/Settings/NotificationOptionsView.swift b/CodexBar/Views/Settings/NotificationOptionsView.swift
index edeb55a..0951e8f 100644
--- a/CodexBar/Views/Settings/NotificationOptionsView.swift
+++ b/CodexBar/Views/Settings/NotificationOptionsView.swift
@@ -1,6 +1,6 @@
import SwiftUI
-/// 通知子选项面板, 挂在设置窗口「系统通知」行右侧展开
+/// 通知子选项面板, 挂在设置窗口"系统通知"行右侧展开
/// 面板尺寸在 Hook 开/关两种状态下保持不变: 行高固定, Picker 行内显隐不改行高
struct NotificationOptionsView: View {
@ObservedObject var notificationSettings: NotificationSettings
diff --git a/Docs/CodexHook.md b/Docs/CodexHook.md
index 7b43d8c..9a4968c 100644
--- a/Docs/CodexHook.md
+++ b/Docs/CodexHook.md
@@ -272,6 +272,14 @@ CloudKit 也按最近 210 天保留。每天第一次工作流刷新时,当前
同步失败不会清空开启偏好,也不会把原始 CloudKit 错误直接展示给用户。`WorkflowSyncService` 会把错误归类为「网络不可用」「账号不可用」「服务暂时不可用」「同步失败,请稍后重试」,并通过同步结束通知交给 `WorkflowSyncSettings`。主面板更新时间行最右侧的同步图标先按 Codex Hook、跨设备同步偏好和同步账号可用性判断 active 同步态;非 active 同步统一显示 `icloud.slash` 和「同步未开启」。只有 active 同步态才继续区分空闲、同步中和失败;空闲态 tooltip 展示 `最近同步: yyyy-MM-dd HH:mm:ss`, 时间来源和设置页「最近同步」一致,没有成功上传记录时显示「暂无同步记录」;失败态使用 `exclamationmark.icloud`, tooltip 展示归类后的短错误。设置页只保留「同步不可用」、同步中和最近同步时间。
+## 从原始事件重建
+
+设置页「重建数据」使用两次点击选择最近 210 天内的开始和结束日期,选择期间可以跨月;连续点击同一天两次时形成单日范围。保留窗口内的日期均可选择,非空本机原始事件日期以圆点标记,未来日期和保留窗口外日期不可选。选择范围完成后,行内消息显示完整日历范围包含的天数;真正提交时只取范围内仍存在且文件非空的 `events/YYYY-MM-DD.jsonl` 日期批量重建,没有数据的日期不会生成空聚合。例如 1–15 号中只有 1、2、3、4、9、10 号有数据时,确认弹窗和重建任务均按 6 天处理。每次打开设置窗口都会清除上次选择和结果消息。
+
+用户确认后,`WorkflowSyncScheduler` 将整批重建与普通维护、CloudKit 同步串行调度;已有任务先完成,重建期间产生的自动维护或同步请求合并排队,并在重建结束后继续处理。`WorkflowService` 依次从每个待重建文件第一行开始重新聚合,为对应日期生成新的 `sourceGeneration`,并原子更新 `daily.jsonl`;原始事件文件不会被修改。重建期间允许 Hook 继续追加,每个任务只处理开始时捕获的稳定文件边界,随后新增内容仍由 pending 增量维护补齐;如果任一文件被截断、替换或原位置内容再次变化,本批重建失败并保留 dirty 状态供重试。已成功完成的前序日期仍会保留其本地结果和待云端替换状态。
+
+重建表示用户明确选择「以本机这些日期现存原始事件为准」。因此它与自动检测到的来源不明替换不同:同步状态会持久化各日期的权威替换请求,展示时先忽略当前设备对应日期的旧云端缓存;同步可用后,全量确认并删除当前设备对应日期的所有旧 generation,再以本地新 generation 上传重建聚合。上传确认后,本机和远端使用同一个 generation。范围外日期、没有本机数据的日期、其他设备贡献以及原始事件不受影响;同步暂不可用或失败时替换请求保留,后续同步自动重试。
+
## 统计口径
`events/YYYY-MM-DD.jsonl` 是统计源。Hook 写入时已经按事件自身 `timestamp` 选择对应本地日期文件;重建或增量更新 `daily.jsonl` 时,维护流程按当前处理的文件日期生成当天聚合,再按每行的 `event` 名称归类。`event` 归类时会去掉 `_` 和 `-` 并转小写,例如 `PreToolUse`、`pre_tool_use`、`pre-tool-use` 都会归为 `pretooluse`。
@@ -309,25 +317,25 @@ subagentStopCount, sessionCount, turnCount, projectCounts, modelCounts, sessionI
逐字段统计口径如下:
-| `daily.jsonl` 字段 | 从 `events/YYYY-MM-DD.jsonl` 读取什么 | 写入 / 更新规则 | 页面关系 |
-| ------------------------ | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
-| `date` | `timestamp` | Hook 写入时先把事件时间解析为绝对时间,再按当前本地时区格式化为 `yyyy-MM-dd` 选择日期文件。维护流程按当前处理的文件日期生成同名 `daily.jsonl` 行。早于最近 210 天保留窗口的日期不会进入聚合。 | 热力图日期键;详情面板日期。 |
-| `eventCount` | 每条成功解码并保留下来的事件行 | 每处理一条事件就 `+1`,发生在具体事件类型判断之前。因此 `UserPromptSubmit`、未知 `event`、`tool: null`、`session: null` 等行都会计入,只要 `timestamp` 和 `event` 可解析。 | 进入 `WorkflowDailyMetrics.eventCount`,当前页面不展示。 |
-| `sessionStartCount` | `event` | `event` 归一化后等于 `sessionstart` 时 `+1`。不要求 `session` 非空。 | 作为「会话总数」兜底来源。 |
-| `stopCount` | `event` | `event` 归一化后等于 `stop` 时 `+1`。不要求 `turn` 非空。 | 作为「对话轮次」兜底来源。 |
-| `preToolUseCount` | `event` | `event` 归一化后等于 `pretooluse` 时 `+1`。不读取 `tool` 做过滤,`tool` 为 `null` 也计入。 | 参与「调用工具」。 |
-| `postToolUseCount` | `event` | `event` 归一化后等于 `posttooluse` 时 `+1`。不读取 `tool` 做过滤,`tool` 为 `null` 也计入。 | 参与「调用工具」。 |
-| `permissionRequestCount` | `event` | `event` 归一化后等于 `permissionrequest` 时 `+1`。不读取 `permission` 字段做过滤,`permission` 只是记录当时的权限模式。 | 直接显示为「权限请求」。 |
-| `preCompactCount` | `event` | `event` 归一化后等于 `precompact` 时 `+1`。 | 参与「上下文压缩」。 |
-| `postCompactCount` | `event` | `event` 归一化后等于 `postcompact` 时 `+1`。 | 参与「上下文压缩」。 |
-| `subagentStartCount` | `event` | `event` 归一化后等于 `subagentstart` 时 `+1`。 | 参与「子智能体」。 |
-| `subagentStopCount` | `event` | `event` 归一化后等于 `subagentstop` 时 `+1`。 | 参与「子智能体」。 |
-| `sessionIds` | `session` | 新建聚合初始化为 `[]`。最近 3 个本地自然日内,任意事件行只要 `session` 是非空字符串,就插入当天集合并去重、排序;不要求事件类型是 `SessionStart`。聚合结束后仍为空或进入窗口外压缩时写成 `null`;只有非空数组会持久化。 | 参与「会话总数」去重。 |
-| `turnIds` | `turn` | 新建聚合初始化为 `[]`。最近 3 个本地自然日内,任意事件行只要 `turn` 是非空字符串,就插入当天集合并去重、排序;不要求事件类型是 `Stop`。聚合结束后仍为空或进入窗口外压缩时写成 `null`;只有非空数组会持久化。 | 参与「对话轮次」去重。 |
+| `daily.jsonl` 字段 | 从 `events/YYYY-MM-DD.jsonl` 读取什么 | 写入 / 更新规则 | 页面关系 |
+| ------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| `date` | `timestamp` | Hook 写入时先把事件时间解析为绝对时间,再按当前本地时区格式化为 `yyyy-MM-dd` 选择日期文件。维护流程按当前处理的文件日期生成同名 `daily.jsonl` 行。早于最近 210 天保留窗口的日期不会进入聚合。 | 热力图日期键;详情面板日期。 |
+| `eventCount` | 每条成功解码并保留下来的事件行 | 每处理一条事件就 `+1`,发生在具体事件类型判断之前。因此 `UserPromptSubmit`、未知 `event`、`tool: null`、`session: null` 等行都会计入,只要 `timestamp` 和 `event` 可解析。 | 进入 `WorkflowDailyMetrics.eventCount`,当前页面不展示。 |
+| `sessionStartCount` | `event` | `event` 归一化后等于 `sessionstart` 时 `+1`。不要求 `session` 非空。 | 作为「会话总数」兜底来源。 |
+| `stopCount` | `event` | `event` 归一化后等于 `stop` 时 `+1`。不要求 `turn` 非空。 | 作为「对话轮次」兜底来源。 |
+| `preToolUseCount` | `event` | `event` 归一化后等于 `pretooluse` 时 `+1`。不读取 `tool` 做过滤,`tool` 为 `null` 也计入。 | 参与「调用工具」。 |
+| `postToolUseCount` | `event` | `event` 归一化后等于 `posttooluse` 时 `+1`。不读取 `tool` 做过滤,`tool` 为 `null` 也计入。 | 参与「调用工具」。 |
+| `permissionRequestCount` | `event` | `event` 归一化后等于 `permissionrequest` 时 `+1`。不读取 `permission` 字段做过滤,`permission` 只是记录当时的权限模式。 | 直接显示为「权限请求」。 |
+| `preCompactCount` | `event` | `event` 归一化后等于 `precompact` 时 `+1`。 | 参与「上下文压缩」。 |
+| `postCompactCount` | `event` | `event` 归一化后等于 `postcompact` 时 `+1`。 | 参与「上下文压缩」。 |
+| `subagentStartCount` | `event` | `event` 归一化后等于 `subagentstart` 时 `+1`。 | 参与「子智能体」。 |
+| `subagentStopCount` | `event` | `event` 归一化后等于 `subagentstop` 时 `+1`。 | 参与「子智能体」。 |
+| `sessionIds` | `session` | 新建聚合初始化为 `[]`。最近 3 个本地自然日内,任意事件行只要 `session` 是非空字符串,就插入当天集合并去重、排序;不要求事件类型是 `SessionStart`。聚合结束后仍为空或进入窗口外压缩时写成 `null`;只有非空数组会持久化。 | 参与「会话总数」去重。 |
+| `turnIds` | `turn` | 新建聚合初始化为 `[]`。最近 3 个本地自然日内,任意事件行只要 `turn` 是非空字符串,就插入当天集合并去重、排序;不要求事件类型是 `Stop`。聚合结束后仍为空或进入窗口外压缩时写成 `null`;只有非空数组会持久化。 | 参与「对话轮次」去重。 |
| `sessionCount` | `sessionIds`、`sessionCount`、`sessionStartCount` | 最近 3 天通常为 `null`;日期进入 3 天外窗口后,归一化时优先沿用已有正数 `sessionCount`,否则使用非空 `sessionIds` 的去重数量,再否则使用 `sessionStartCount`,然后移除 `sessionIds`。空 ID 数组不表示权威的零;`sessionCount == 0` 但 `sessionStartCount > 0` 时会自动修复。 | 参与「会话总数」。 |
| `turnCount` | `turnIds`、`turnCount`、`stopCount` | 最近 3 天通常为 `null`;日期进入 3 天外窗口后,归一化时优先沿用已有正数 `turnCount`,否则使用非空 `turnIds` 的去重数量,再否则使用 `stopCount`,然后移除 `turnIds`。空 ID 数组不表示权威的零;`turnCount == 0` 但 `stopCount > 0` 时会自动修复。 | 参与「对话轮次」。 |
-| `projectCounts` | `cwd` | 任意事件行只要 `cwd` 非空,就取标准化路径的最后一层目录名作为项目名并 `+1`;如果最后一层为空,回退使用完整路径字符串。统计的是事件数,不是会话数或调用工具数。未知事件也会计入。 | 用于计算 `mostActiveProject`,当前页面不展示。 |
-| `modelCounts` | `model` | 任意事件行只要 `model` 非空,就按原始模型名 `+1`。统计的是带模型字段的事件数,不是 token 数;未知事件也会计入。 | 合并后用于计算并展示「最热模型」。 |
+| `projectCounts` | `cwd` | 任意事件行只要 `cwd` 非空,就取标准化路径的最后一层目录名作为项目名并 `+1`;如果最后一层为空,回退使用完整路径字符串。统计的是事件数,不是会话数或调用工具数。未知事件也会计入。 | 用于计算 `mostActiveProject`,当前页面不展示。 |
+| `modelCounts` | `model` | 任意事件行只要 `model` 非空,就按原始模型名 `+1`。统计的是带模型字段的事件数,不是 token 数;未知事件也会计入。 | 合并后用于计算并展示「最热模型」。 |
读取 `daily.jsonl` 时,缺失的数字字段按 `0` 处理,缺失的 `projectCounts` / `modelCounts` 按空字典处理,缺失的 `sessionIds` / `turnIds` / `sessionCount` / `turnCount` / `sourceGeneration` 保持为 `nil`,缺失的 `sourceIsFresh` 按 `false` 处理。仍有原始 events 文件的日期会在维护时确保存在来源 generation;已有非空事件文件默认视为来源不明确,只有 Hook 明确从不存在或空文件开始时才标记 fresh。只剩 daily、原始 events 已不存在的日期不会凭空生成 generation,原 daily 行会继续保留。后续归一化仍按当前保留策略补齐或压缩 ID 字段,并把由空 ID 数组产生的不一致零计数修复为起止事件兜底值。
diff --git a/Docs/CrossDeviceSync.md b/Docs/CrossDeviceSync.md
index 854aaab..fe39576 100644
--- a/Docs/CrossDeviceSync.md
+++ b/Docs/CrossDeviceSync.md
@@ -24,17 +24,17 @@
## 代码入口
-| 文件 | 职责 |
-| -------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `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/Settings/WorkflowSyncSettings.swift` | 设置页状态、同步账号可用性检查、UserDefaults 开关、最近同步时间、同步中和失败通知 |
+| `CodexBar/Services/Workflow/WorkflowSyncScheduler.swift` | 维护、同步和显式重建的唯一调度者, 合并待执行请求、冷却窗口和最终状态校验 |
+| `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 和同步可用性变化交给调度器 |
## 本地状态
@@ -54,11 +54,11 @@ Sync/cursor.data
各文件职责:
-| 文件 | 内容 |
-| ------------- | --------------------------------------------------------------------------------------- |
-| `state.json` | 本机同步状态,包括 `deviceId`、每天已处理的本机 hash、`lastUploadAt`、`lastPrunedDate` |
-| `cache.jsonl` | 从 iCloud 拉取到的所有设备脱敏 daily 记录,一行一条;同一天可包含多个 generation |
-| `cursor.data` | CloudKit custom zone `CodexBarZone` 的 `CKServerChangeToken`,用于下次增量拉取 |
+| 文件 | 内容 |
+| ------------- | ------------------------------------------------------------------------------------------------------ |
+| `state.json` | 本机同步状态,包括 `deviceId`、每天已处理的本机 hash、待权威替换日期、`lastUploadAt`、`lastPrunedDate` |
+| `cache.jsonl` | 从 iCloud 拉取到的所有设备脱敏 daily 记录,一行一条;同一天可包含多个 generation |
+| `cursor.data` | CloudKit custom zone `CodexBarZone` 的 `CKServerChangeToken`,用于下次增量拉取 |
`state.json` 的逻辑结构:
@@ -69,6 +69,7 @@ Sync/cursor.data
"hashByDate": {
"2026-06-25": "<脱敏 daily 聚合的 SHA256>"
},
+ "replacementDates": ["2026-06-25"],
"lastUploadAt": "2026-06-25T10:20:30Z",
"lastPrunedDate": "2026-06-25"
}
@@ -129,7 +130,7 @@ fields:
`modelCounts` 会保留 Hook 事件中的模型名及其当天事件计数,用于跨设备合并后计算热力图详情的「最热模型」;不会包含 prompt、response 或原始事件内容。
-CloudKit Production schema 必须包含当前 schema `4` 使用的字段,包括 `CodexBarDailyAggregate.sourceGeneration`。schema 变化需要通过 CloudKit Dashboard 从 Development 部署到 Production;App 只负责读写记录,不会自动部署 Production schema。开发签名通常访问 Development,发布签名访问 Production。
+CloudKit Production schema 必须包含当前 schema `4` 使用的字段,包括 `CodexBarDailyAggregate.sourceGeneration`;`deviceId` 和 `date` 需要保持可查询,以便按设备清理过期记录。schema 变化需要通过 CloudKit Dashboard 从 Development 部署到 Production;App 只负责读写记录,不会自动部署 Production schema。开发签名通常访问 Development,发布签名访问 Production。
## 设备标识
@@ -225,6 +226,7 @@ WorkflowService.loadSnapshot(performMaintenance: true, synchronize: true)
- Codex Hook 重新开启,且跨设备同步偏好仍为 true
- 同步账号从不可用变为可用,且 Hook 与跨设备同步都已开启
- app-server 自动刷新倒计时重置时,如果 Hook、跨设备同步和同步账号都可用
+- 用户从设置页批量重建日期范围内的本机数据,且 Hook、跨设备同步和同步账号都可用
Hook 子进程不访问网络。它只检查事件文件是否从空文件重新开始、维护本地 generation 状态、把原始事件写入 `events/YYYY-MM-DD.jsonl` 并标记 `maintenance.json` 的 pending 日期。真正的 daily 重建和 CloudKit 同步都由主 App 的维护刷新完成。
@@ -234,7 +236,8 @@ Hook 子进程不访问网络。它只检查事件文件是否从空文件重新
- 同步正在执行时,新请求只标记为待补跑,不取消当前同步
- 冷却窗口内的多次请求合并为一次待补跑同步
- 补跑前重新校验 Hook 开启、`WorkflowSync.isEnabled == true` 且同步账号可用;最终状态不满足时丢弃待补跑请求
-- `WorkflowViewModel.refreshMaintenance(synchronize:)` 不再自行判断维护并发;维护/同步是否运行、是否排队和是否冷却只由 `WorkflowSyncScheduler` 管理。
+- `WorkflowViewModel.refreshMaintenance(synchronize:)` 只执行一次明确的维护刷新;维护、同步和显式重建的运行、排队与同步冷却均由 `WorkflowSyncScheduler` 管理。
+- 用户发起的日期范围批量重建同样由 `WorkflowSyncScheduler` 串行执行;已有维护或同步完成后再开始,重建期间新增的自动维护或同步请求分别合并,并在整批重建完成后继续处理。
## 同步主流程
@@ -336,6 +339,14 @@ CodexBar.workflowSyncDidFinish
`needsBackfill` 只有在本机所有 daily 日期的 hash 都已经和 `state.hashByDate` 匹配后才会清除。这样首次开启时即使 20 秒内没有补完,后续每分钟刷新也会继续补传。
+## 显式重建替换
+
+用户在设置页通过两次点击选择日期范围并确认重建后,`WorkflowService` 只处理范围内有非空本机原始事件文件的日期,为它们分别生成新的本地 generation,并批量加入 `state.replacementDates`,同时清除对应的 `hashByDate[date]`;两次点击同一天时只处理该日期。日期选择器允许选择最近 210 天保留窗口内的任意日期,非空本机原始事件日期以圆点标记,没有数据的日期只参与范围选择,不进入重建或云端替换。这个状态表示用户已经明确授权以当前本机原始事件替换「当前设备、实际重建日期」的云端贡献,不代表新的独立贡献。
+
+存在待替换日期时,同步流程会先全量查询 `CodexBarDailyAggregate`,再按批次删除当前 `deviceId` 对应日期的 legacy 记录和全部 generation 记录。只有删除结果全部成功或返回 `unknownItem` 后,才从本地 cache 移除这些旧记录并按正常上传流程创建本地新 generation 的记录。新记录确认后才从 `replacementDates` 移除日期;删除或上传中途失败时请求保留,下一轮会重新全量确认并幂等重试。
+
+待替换期间,`WorkflowSnapshot` 不使用当前设备对应日期的旧缓存,直接展示重建后的本机聚合;其他设备同日贡献仍照常合并。跨设备同步关闭、Hook 关闭或账号暂不可用时只完成本地重建,待替换状态保留到后续实际同步。超过 210 天保留窗口的待替换日期会随同步清理移除。
+
## 拉取缓存和游标
上传之后会更新本地同步缓存。`CodexBarDailyAggregate` 保存在 custom zone `CodexBarZone`, 因为 CloudKit 默认 zone 不支持 `getChanges`/zone change token。没有 `cursor.data` 时, App 会先 query 全量 `CodexBarDailyAggregate` 记录(包含当前设备自己的记录)回填 `cache.jsonl`, 然后从 `nil` 调用 CloudKit zone changes 补齐这段变化并保存新的 `cursor.data`; 有游标时优先拉取 custom zone 的增量变化:
@@ -411,6 +422,8 @@ date < retentionCutoffDate
其他设备的记录不会由本机删除。每台设备只负责清理自己上传的过期记录。
+清理候选直接通过 CloudKit 按 `deviceId == 当前设备 && date < retentionCutoffDate` 分页查询,并使用查询结果中的完整 `CKRecord.ID` 分批删除。因此清理不依赖已经过滤过期行的 `cache.jsonl`,legacy 名称和 `<device>_<date>_<generation>` 名称都会进入删除请求。只有全部删除成功或返回 `unknownItem` 后才更新 `lastPrunedDate`;中途失败会在下一轮继续查询和幂等重试。
+
当前实现不会因为本机 `daily.jsonl` 删除了某个仍在 210 天窗口内的日期,就主动删除该日期对应的 CloudKit 记录。它会等到该记录超过 210 天保留窗口后再清理。
单独删除某天的本机 events 文件也不会删除已有 daily 行:历史日期不再产生事件时,界面仍使用保留下来的本机 daily,并与同 generation 云端副本择优。如果 daily 行也被删除,开启同步时界面会回退到 `cache.jsonl` 中的云端贡献;关闭同步或云端没有副本时,该日期才会从界面消失。相比之下,把仍存在的 events 文件清空或截断会被识别为文件连续性变化,并按维护规则重建或切换 generation。
@@ -419,23 +432,24 @@ date < retentionCutoffDate
失败处理以不中断工作流统计展示为目标。
-| 场景 | 当前行为 |
-| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| iCloud 未登录或不可用 | 设置页禁用「跨设备同步」,显示 `同步不可用`; 主面板同步图标走非 active 同步态, 显示 `icloud.slash` 和「同步未开启」 |
-| 用户尝试在同步账号不可用时开启 | `setEnabled(true)` 直接返回,不写入开启状态 |
-| `CodexBarZone` 不存在 | 同步开始时创建 custom zone |
-| CloudKit 上传读取失败 | 只有 `unknownItem` 视为记录不存在;其他单条读取错误终止本轮,整批日期持久化为待重试 |
-| CloudKit 上传保存失败 | 请求抛错、结果缺失或任一单条失败都会终止本轮;已确认的前序批次保留,失败批次清除 hash 后在下次刷新整批重试 |
+| 场景 | 当前行为 |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| iCloud 未登录或不可用 | 设置页禁用「跨设备同步」,显示 `同步不可用`; 主面板同步图标走非 active 同步态, 显示 `icloud.slash` 和「同步未开启」 |
+| 用户尝试在同步账号不可用时开启 | `setEnabled(true)` 直接返回,不写入开启状态 |
+| `CodexBarZone` 不存在 | 同步开始时创建 custom zone |
+| CloudKit 上传读取失败 | 只有 `unknownItem` 视为记录不存在;其他单条读取错误终止本轮,整批日期持久化为待重试 |
+| CloudKit 上传保存失败 | 请求抛错、结果缺失或任一单条失败都会终止本轮;已确认的前序批次保留,失败批次清除 hash 后在下次刷新整批重试 |
| 确认从空文件开始的新 generation | 为同设备、同日期创建独立记录,与旧 generation 一起展示和清理 |
-| 来源不明确的非空替换 | 不上传为新的独立贡献,继续使用已有云端记录,避免和可能重叠的事件重复相加 |
-| CloudKit 增量拉取失败 | 不写入日志窗口,尝试全量重建缓存 |
-| 云端记录被外部删除 | 从本地 cache 移除;如果本机 daily hash 未变化则不会立即重新上传,等待本机内容变化,或 state 重置、对应 hash 被清除后重新进入候选 |
-| CloudKit 全量重建失败 | 本轮同步失败,保存已有 state,保留已有 cache,后续刷新重试 |
-| 账号 salt 创建冲突 | 重新读取 CloudKit 中已有 salt |
-| 本地 state schema 不兼容 | 丢弃旧 state,按当前 schema 重新同步 |
-| `deviceId` 变化 | 重置本地同步 state/cache/cursor,按当前 iCloud 账号重新同步 |
-| `changeTokenExpired` | 不写入日志窗口,尝试全量重建缓存并建立新的 cursor |
-| `cache.jsonl` 写入失败 | 不保存新 cursor,下一轮重新拉取同一批变化 |
-| 同步失败 | `WorkflowSyncService` 捕获错误并归类为 `网络不可用`、`账号不可用`、`服务暂时不可用` 或 `同步失败,请稍后重试`; 主面板显示 `exclamationmark.icloud` 和短 tooltip, 设置页停止同步中状态且 `最近同步` 不更新 |
+| 来源不明确的非空替换 | 不上传为新的独立贡献,继续使用已有云端记录,避免和可能重叠的事件重复相加 |
+| 用户确认从原始事件批量重建 | 对实际有本机数据的日期隐藏当前设备同日旧缓存,删除对应日期的全部旧 generation,再上传本地新 generation;失败时保留待替换日期并重试 |
+| CloudKit 增量拉取失败 | 不写入日志窗口,尝试全量重建缓存 |
+| 云端记录被外部删除 | 从本地 cache 移除;如果本机 daily hash 未变化则不会立即重新上传,等待本机内容变化,或 state 重置、对应 hash 被清除后重新进入候选 |
+| 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 e6972b1..62d2aa1 100644
--- a/Docs/DevelopmentGuide.md
+++ b/Docs/DevelopmentGuide.md
@@ -822,11 +822,11 @@ Hook 数据目录:
文件职责:
-| 文件 | 职责 |
-| ------------------------- | ------------------------------------------------ |
-| `events/YYYY-MM-DD.jsonl` | 按本机日期拆分的原始 Hook 事件 |
-| `daily.jsonl` | 每日聚合结果, UI 优先读取 |
-| `stats.lock` | `flock` 锁文件 |
+| 文件 | 职责 |
+| ------------------------- | ------------------------------------------------------------ |
+| `events/YYYY-MM-DD.jsonl` | 按本机日期拆分的原始 Hook 事件 |
+| `daily.jsonl` | 每日聚合结果, UI 优先读取 |
+| `stats.lock` | `flock` 锁文件 |
| `maintenance.json` | pending、dirty、offset、来源 generation 和文件连续性校验状态 |
## 12. Workflow 维护与聚合流程
@@ -837,8 +837,10 @@ Hook 数据目录:
- 打开菜单面板时如果 Hook 开启, 只读取现有 `daily.jsonl` 和同步缓存, 不维护, 不联网
- app-server 自动刷新倒计时重置时, 如果 Hook 开启, 通过 `WorkflowSyncScheduler.requestMaintenance(allowsSync: true)` 请求一次维护
- 同步开关开启、Hook 重新开启或同步账号恢复可用时, 通过 `WorkflowSyncScheduler.requestSync()` 请求一次同步维护
-- `WorkflowSyncScheduler` 是维护/同步任务的唯一调度者, 负责运行中、待补跑、冷却窗口和最终状态校验
-- `WorkflowViewModel.refreshMaintenance(synchronize:)` 不自行判断维护并发, 只取消普通读取并执行一次明确的 `WorkflowService.loadSnapshot(performMaintenance: true, synchronize: ...)`
+- `WorkflowSyncScheduler` 是维护、同步和显式重建的唯一调度者, 负责运行中、待补跑、冷却窗口和最终状态校验
+- `WorkflowViewModel.refreshMaintenance(synchronize:)` 只取消普通读取并执行一次明确的 `WorkflowService.loadSnapshot(performMaintenance: true, synchronize: ...)`, 运行和排队状态由调度器管理
+- 设置页日期范围批量重建同样通过 `WorkflowSyncScheduler` 排队, 首次点击确定起点, 第二次点击确定终点且允许跨月, 两次点击同一天时形成单日范围; 保留窗口内的日期均可选择, 本机非空事件日期以圆点标记, 提交时只筛选范围内本机非空的分日事件文件, 逐日从头生成新的本地 generation, 并批量持久化当前设备对应日期的待云端替换状态
+- 已有维护或同步先完成再执行重建; 重建期间新增的本机维护和同步请求分别合并, 整批重建结束后由调度器继续处理, 不与重建并发读写工作流状态
维护流程在 `WorkflowService` actor 内串行执行
@@ -899,6 +901,8 @@ UI 展示指标来自 `WorkflowDailyAggregate.metrics`:
跨设备同步只在 `performMaintenance: true, synchronize: true` 的刷新中执行。`WorkflowSyncScheduler` 会合并同步开关、Hook 重新开启、同步账号恢复可用和自动刷新产生的同步请求;同步中不取消重启, 冷却窗口内只保留一次待补跑请求, 补跑前重新校验 Hook 开启、跨设备同步偏好为 true 且同步账号可用。`WorkflowSyncService` 先用本机 daily 聚合生成脱敏 `WorkflowSyncedDailyAggregate`, 保留 `sourceGeneration`、`projectCounts` 和 `modelCounts`, 再为保留窗口内的全部本机日期计算稳定 hash、按日期稳定排序候选项, 每批最多上传 25 天, 每轮最多使用 20 秒。zone 存在性确认和 account salt 首次成功后在 actor 内跨轮缓存, 任一轮同步失败时作废, 下一轮重新确认(覆盖 iCloud 账号切换)。同步先刷新一次 CloudKit 缓存再决定上传:只在当前 `deviceId`、当前待上传日期内查找本机副本;同 generation 复用现有记录并按 `eventCount` 防倒退;没有 generation 的记录必须与本机全部同步业务字段完全一致才会被认作同一来源,即使两边 generation 都是 `nil` 也不能跳过内容比较;确认从空文件开始的新 generation 使用独立记录;来源不明确的非空替换在已有云端贡献时只确认保留云端,不自动上传为新贡献。每批处理后立即保存已经上传或确认保留的 `state.hashByDate`; 只有实际上传时更新 `lastUploadAt`, 未完成的 backfill 留给后续自动刷新继续。上传后再次拉取 CloudKit 变化。没有 `cursor.data` 时先 query 全量 `CodexBarDailyAggregate` 回填 `cache.jsonl`; 有游标时优先拉 CloudKit 增量, 游标失效或增量失败时不写入日志窗口, 直接全量重建缓存。删除变化只移除 cache 记录,不清除已确认 hash,所以外部删除不会在本机 daily 未变化时立即回传。`cache.jsonl` 按 record name 保存所有设备和 generation 的记录;展示时当前本机 generation 与同 generation 云端副本按 `eventCount` 择优,确认独立的其他 generation 与其他设备记录继续累加;来源不明确的替换继续使用已有云端记录。增量路径先写 `cache.jsonl`, 成功后再写 `cursor.data`, 避免游标提前推进导致未落盘记录被跳过。同步失败会通过 `CodexBar.workflowSyncDidFinish` 通知发送 `didSucceed=false` 和归类后的 `failureMessage`, 主面板同步图标进入失败态。
+显式日期重建完成后, `WorkflowSyncService` 把实际重建日期写入 `state.replacementDates`, 清除对应日期的确认 hash, 并在快照合并时忽略当前设备这些日期的旧缓存。同步可用时先全量重建 CloudKit 缓存, 再分批删除当前设备对应日期的 legacy 和全部 generation 记录; 删除成功或返回 `unknownItem` 后从本地 cache 移除旧记录, 随后按正常上传流程写入本机新 generation。日期只有在新记录确认后才从 `replacementDates` 移除; 删除、上传或同步中途失败时保留请求并在后续同步幂等重试。其他设备和范围外日期不参与替换。
+
当前代码写入的 CloudKit `schemaVersion` 是 `4`, 本地同步 state schema 是 `4`,本地工作流维护 state schema 也是 `4`。同步 state 无法按当前 schema 使用时会重建并重新同步。daily 或 CloudKit 记录没有 `sourceGeneration` 时仍可读取;只有其全部同步业务字段与当前本机聚合一致时,才会认作同一 generation。
CloudKit Production schema 必须包含当前 schema `4` 使用的字段;schema 变化需要通过 CloudKit Dashboard 从 Development 部署到 Production,运行时代码不会代替发布流程执行部署。
@@ -927,8 +931,10 @@ CloudKit Production schema 必须包含当前 schema `4` 使用的字段;schem
- `AppUpdater.refreshAutomaticCheckSetting()`
- `CodexCLIVersionViewModel.refresh()`
- `CodexStatusViewModel.refreshCodexConnectionInfo()`
+- `NotificationSettings.refreshAuthorizationStatus()`
+- `WorkflowStorage.rebuildableEventDateKeys()`
-App 再次成为 active 时, 也会刷新 Codex 版本区、同步可用性, 并在已安装 Hook 时重新运行 `hooks/list` 验证。
+App 再次成为 active 时, 也会刷新 Hook、同步、菜单栏额度、主面板、Codex 版本、通知授权和可重建日期, 并重新运行 `hooks/list` 验证。`SettingsWindowController.open()` 发布 `.settingsWindowDidOpen` 后, 日期重建范围、确认弹窗和上次结果消息恢复为未选择状态。
版本探测内部有 60 秒节流, 避免 `onAppear` 和 `didBecomeActive` 连续触发时重复启动子进程
@@ -945,6 +951,7 @@ App 再次成为 active 时, 也会刷新 Codex 版本区、同步可用性, 并
| 使用快捷键 | `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` 并请求调度同步 |
+| 重建数据 | `WorkflowStorage.rebuildableEventDateKeys()` + `WorkflowSyncScheduler` | 选择最近 210 天内的日期范围, 将范围内非空本机事件日期交给调度器逐日重建, 并登记当前设备对应日期的待云端替换状态 |
| Codex 版本 | `CodexCLIVersionSnapshot` + 当前 app-server 握手信息 | 路径点击复制到剪贴板 |
| CodexBar 版本 | Bundle + AppUpdater 状态 | 有更新状态时优先显示动态消息 |
@@ -954,6 +961,7 @@ App 再次成为 active 时, 也会刷新 Codex 版本区、同步可用性, 并
- Hook 设置失败, 全局禁用, 自动信任写入失败或验证异常显示在 Hook 选项下方
- 同步账号不可用时显示在跨设备同步开关下方
- 同步运行失败不在设置页展示原始错误; 主面板同步图标 tooltip 显示归类后的短错误
+- 重建行始终保留一行消息位置: 未选择时显示「未选择重建日期范围」, 只选择起点时显示「选择结束日期」, 范围完成且存在数据时显示完整日历范围的「已选择 X 天」, 范围内没有非空事件文件时显示「没有可重建的本地数据」; 完成或失败后改为对应结果消息
- 没有登录项错误时不渲染错误组
- 快捷键无法识别, 规则不合法或注册冲突显示在快捷键行内
- 更新检查状态显示在 CodexBar 版本行
diff --git a/Docs/UserGuide.md b/Docs/UserGuide.md
index 3465b5b..71fd908 100644
--- a/Docs/UserGuide.md
+++ b/Docs/UserGuide.md
@@ -197,6 +197,7 @@ Hook 统计只从开启后开始记录,不能补出开启前的工作流历史
| 菜单栏额度指示 | 在图标左侧显示所选额度窗口 | 没有可用数据时自动隐藏 |
| 启用 Codex Hook | 开启工作流统计、活动卡片和任务提醒 | 会修改当前用户的 `~/.codex/hooks.json` |
| 跨设备同步 | 通过 iCloud private database 合并 Hook 日聚合 | 需要 Hook 已开启且 iCloud 可用 |
+| 重建数据 | 选择日期范围并批量重新生成有原始事件的每日聚合 | 会替换当前设备对应日期的云端聚合 |
| 系统通知 | 控制 CodexBar 通知和任务触觉反馈总开关 | 首次开启需要系统授权 |
| 使用快捷键 | 设置全局打开/关闭菜单面板的快捷键 | 至少需要两个修饰键 |
| Codex 版本 | 查看全局 CLI、Codex.app 内置 CLI 和当前使用来源 | 点击路径可以复制 |
@@ -248,6 +249,14 @@ CodexBar Hook 记录事件类型、时间、模型、权限模式、会话和轮
CodexBar 只增删属于当前 CodexBar 可执行文件的 Hook,不会删除其他 App 或用户自己的 Hook。
+### 批量重建日期范围内的工作流数据
+
+如果手动修改过 `events/YYYY-MM-DD.jsonl`,或确认一段日期范围内的本机聚合需要重新计算,可以在设置页「重建数据」第一次点击开始日期,再翻月并点击结束日期;如果只处理一天,则连续点击同一天两次。日期固定使用 `yyyy-MM-dd` 格式,最近 210 天保留窗口内的日期均可选择,未来日期和更早日期不可选。本机原始事件非空的日期会显示圆点;没有圆点的日期可以参与范围选择和高亮,但不会进入实际重建。日历固定显示六周,月首和月末相邻月份的日期会以较淡颜色补齐。
+
+每次重新打开设置窗口时,日期范围和上次操作消息都会恢复为未选择状态。重建行下方固定显示一行状态:尚未选择时显示「未选择重建日期范围」,只选择开始日期后显示「选择结束日期」,范围完成且其中存在可重建数据时显示完整日历范围包含的「已选择 X 天」,范围内没有非空原始事件时显示「没有可重建的本地数据」。
+
+确认弹窗和「重建」按钮只按范围内实际有非空本机原始事件文件的日期处理。CodexBar 会逐日从对应文件第一行重新统计,分别生成新的本地 generation,但不会修改原始事件。例如选择 1–15 号而只有 1、2、3、4、9、10 号有数据时,只批量重建这 6 天。重建与自动维护、CloudKit 同步由同一调度器串行执行;重建期间到达的自动刷新请求会合并排队,完成后继续处理。日期较多时本机重建耗时会随实际数据量增加;CloudKit 每批最多处理 25 天、每轮最多使用 20 秒,未完成的替换会由后续同步继续。若跨设备同步正在生效,当前设备这 6 天的旧云端 generation 会被删除,再以对应的新 generation 上传重建结果;其他设备、范围外日期和范围内无数据日期不受影响。同步暂不可用时先显示本机重建结果,云端替换会在后续同步恢复后自动重试。无效 JSONL 行会被跳过并在完成提示中汇总数量。
+
### 关闭 Hook 或移动 App
关闭 Hook 会停止记录新事件、隐藏 Hook 统计和活动卡片,并清空当前进程中的实时任务状态,但不会删除已经保存在本机的历史文件。以后重新开启 Hook 时,已有聚合仍可继续使用。
@@ -286,6 +295,8 @@ Hook 命令包含 CodexBar 当前可执行文件的完整路径。如果准备
同一台 Mac 同一天、同一 generation 的本地聚合和 iCloud 副本不会重复相加,通常显示事件数更完整的一份。如果当天事件文件被完整删除或清空,CodexBar 能确认后续事件属于新的独立 generation,因此新统计会与已有云端贡献相加;如果文件被替换成一份非空且来源不明确的数据,CodexBar 会继续使用已有云端记录,不自动覆盖或叠加,避免重复统计。
+设置页的显式重建是上述自动保护的例外:只有用户确认后,CodexBar 才会把所选本机原始事件视为权威来源,删除当前设备同日旧 generation,并上传与本机一致的新 generation。
+
直接删除某个历史日期的本机 events 文件不会同步删除 daily 聚合或云端记录,因此页面通常仍会显示原来的统计。如果连对应 daily 行也删除,开启同步时页面会回退使用已缓存的云端贡献;关闭同步或云端没有副本时,该日期才会消失。
不会上传:
diff --git a/README.md b/README.md
index 32197c5..3ad8081 100644
--- a/README.md
+++ b/README.md
@@ -61,6 +61,8 @@ CodexBar 是一个无 Dock 图标的 macOS 菜单栏应用。
统计结果会汇总到热力图详情面板中,不打断正常的 Codex 使用流程。
+设置页「重建数据」第一次点击选择开始日期,第二次点击选择结束日期,并批量重新统计范围内仍存在且非空的分日原始事件;连续点击同一天两次即可只重建一天,选择范围允许跨月。最近 210 天保留窗口内的日期均可选择,本机原始事件非空的日期以圆点标记,没有数据的日期不会进入实际重建。确认后会为实际重建的每一天生成新的本机 generation;开启跨设备同步时,只替换当前设备对应日期的旧云端聚合,其他设备、范围外日期、无数据日期和原始事件不受影响。
+
主 App 还会在后台只读 Hook JSONL:启动时按块恢复最近 24 小时的活动,之后 tail 当天新增事件,并在内存中维护并发任务状态。跨日任务缺少起点时会按精确 session + turn 定向查找更早的 Prompt;对于仍处于运行、等待终态确认或等待批准状态的精确 turn,CodexBar 会每秒增量读取对应本机 Codex session rollout,用 `task_started` 回填缺失起点、用 `task_complete` 补齐缺失的结束、用 `turn_aborted` 清理中断任务并生成最近终止记录,用 `turn_context.approvals_reviewer` 区分用户审批和自动审批,并用 `turn_context.effort` 补齐当前 turn 的推理强度;初始 512 KB 未找到 effort 时,主 App 会按精确 turn 从文件尾部最多 8 MB 执行一次受限回查。只有 reviewer 明确为 `user` 且同时收到 `PermissionRequest` 时才显示等待批准;`auto_review` 不会触发等待状态或提醒。Subagent Hook 带有稳定 `agent_id` 时,CodexBar 会通过共享 session 将子 Agent 归属到唯一的当前顶层任务,并在内存中幂等配对开始和结束事件,统计当前活跃数量;早于当前顶层任务可信开始时间的事件会被视为上一 turn 的迟到事件并忽略,字段缺失、同 session 无法唯一关联顶层任务或事件序列不完整时则隐藏数量,避免展示不可靠结果。同 session 新 Prompt 会让旧 turn 立即退出活动列表,但先保留 5 秒终态确认窗口,优先接受 rollout 或迟到 Hook 的完成/终止信号,仍无终态才记为终止。不读取提示词、回复、推理内容、工具内容、审批内容或 token 数据。该实时状态用于菜单栏状态点、活动卡片、并发任务中心、可选任务通知和触觉反馈,不新增历史状态文件,也不参与跨设备同步。
CodexBar 只会追加或移除属于当前 CodexBar 可执行文件的 Hook,不会删除用户已有的其他 Codex Hook。
@@ -141,7 +143,7 @@ Codex Hook 工作流数据默认只保存在本机:
菜单栏实时任务状态只存在于当前 App 进程内。活动卡片和并发任务中心只展示工作目录最后一级项目名、模型、推理强度、工具、阶段与耗时;可可靠统计且存在活跃子 Agent 时,活动卡片还会显示其数量。不展示完整路径、会话 ID、轮次 ID 或 agent ID。这份状态不会上传到 CloudKit,也不会产生新的网络请求。为补齐 Hook 缺失的起点、结束、中断、审批路由或推理强度,CodexBar 只对当前活跃 turn 读取 `~/.codex/sessions/` 或 `~/.codex/archived_sessions/` 下对应 rollout JSONL:正常情况下只增量解析生命周期事件、turn ID、起止耗时、`turn_context.approvals_reviewer` 和 `turn_context.effort`,effort 缺失时最多额外读取文件尾部 8 MB;不会提取、保存或展示其中的提示词、回复、推理内容、工具内容或 token 数据。
-只有在用户开启「跨设备同步」后,CodexBar 才会通过 `CloudKit private database` 同步每日使用详情数据;同步的数据副本只包含各个事件数量、项目聚合、模型名使用次数,以及用于区分同一日期独立数据段的随机 generation,不包含原始事件、会话 ID 或轮次 ID。正常追加时,同一 generation 的本机数据和云端副本只取一份;确认事件文件从空文件重新开始时,新 generation 会与旧云端贡献相加;无法确认来源的非空替换不会自动覆盖或叠加旧云端数据。
+只有在用户开启「跨设备同步」后,CodexBar 才会通过 `CloudKit private database` 同步每日使用详情数据;同步的数据副本只包含各个事件数量、项目聚合、模型名使用次数,以及用于区分同一日期独立数据段的随机 generation,不包含原始事件、会话 ID 或轮次 ID。正常追加时,同一 generation 的本机数据和云端副本只取一份;确认事件文件从空文件重新开始时,新 generation 会与旧云端贡献相加;无法确认来源的非空替换不会自动覆盖或叠加旧云端数据。只有用户在设置页确认批量重建日期范围时,才会以范围内实际存在的本机原始事件为准,替换当前设备对应日期的云端 generation。
除上述重置机会过期时间查询、Sparkle appcast / DMG 下载,以及用户开启跨设备同步后的 CloudKit 请求外,CodexBar 自身不发起其他网络请求。
diff --git a/appcast.xml b/appcast.xml
index 7e0aba0..5f87c97 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.3.11</title>
+ <sparkle:version>49</sparkle:version>
+ <sparkle:shortVersionString>3.3.11</sparkle:shortVersionString>
+ <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+ <sparkle:releaseNotesLink>https://codexbar.zabrian.app/notes#3.3.11</sparkle:releaseNotesLink>
+ <pubDate>Tue, 21 Jul 2026 15:05:35 +0800</pubDate>
+ <enclosure url="https://codexbar.zabrian.app/download/CodexBar-v3.3.11.dmg" sparkle:edSignature="xTVz2I+N7uQUQj2UdapIM8Jj+4VRTcoSntuQqlL084JpY7/Pcr5L8lIRAWxD+1Xw0Frvuutz0xD1LyusXq63BA==" length="4204885" type="application/octet-stream"/>
+ </item>
<item>
<title>CodexBar.app 3.3.10</title>
<sparkle:version>48</sparkle:version>