Skip to content

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

feat: 重构工作流同步调度

Bob9cba5b8e8e09
diff --git a/AGENTS.md b/AGENTS.md
index b966206..6e632c1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -64,7 +64,7 @@ git status --short
- 平台: SwiftUI + AppKit + MVVM, 最低 macOS 15.0。
- 应用形态: `LSUIElement` 菜单栏应用, 无 Dock 图标、无主窗口。
- 外部依赖: Sparkle(SwiftPM)。
-- 当前 build settings: `MACOSX_DEPLOYMENT_TARGET = 15.0`, `MARKETING_VERSION = 3.1.3`, `CURRENT_PROJECT_VERSION = 27`, `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`, `SWIFT_VERSION = 6.0`。
+- 当前 build settings: `MACOSX_DEPLOYMENT_TARGET = 15.0`, `MARKETING_VERSION = 3.2.0`, `CURRENT_PROJECT_VERSION = 28`, `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`, `SWIFT_VERSION = 6.0`。
- App Sandbox 必须保持关闭(`ENABLE_APP_SANDBOX = NO`), 因为应用要启动本机 Codex CLI/APP 内置 CLI, 并读取真实 macOS 用户的 Codex 登录状态。
- 工程使用 `PBXFileSystemSynchronizedRootGroup`; 新增或删除 `CodexBar/` 下 Swift 文件通常无需改 `project.pbxproj`。只有依赖、target/build settings 或资源归属变更才改 Xcode 工程文件。
- Swift 源码按目录组织: `App/`、`Controllers/`、`Models/`、`Services/`、`Views/`。不要把新 Swift 文件直接放回 `CodexBar/` 根层。
@@ -82,10 +82,10 @@ CodexStatusService(JSON-RPC app-server)
Codex Hook
-> WorkflowHookEventRecorder(--hook-event stdin hook_event_name)
- -> WorkflowStatsStorage(events/YYYY-MM-DD.jsonl / daily.jsonl)
- -> WorkflowStatsService
+ -> WorkflowStorage(events/YYYY-MM-DD.jsonl / daily.jsonl)
+ -> WorkflowService
-> WorkflowSyncService(可选 CloudKit private database 同步)
- -> WorkflowStatsViewModel
+ -> WorkflowViewModel
-> UsageSummaryView / UsageHeatmap
```
@@ -93,7 +93,7 @@ Codex Hook
- `App/`: 入口和全局启动分支。
- `Controllers/`: 菜单栏、菜单面板、设置窗口和日志窗口控制。
-- `Models/`: account、quota、usage、workflow stats、共享日期网格和错误模型。
+- `Models/`: account、quota、usage、workflow、共享日期网格和错误模型。
- `Services/`: app-server、Codex CLI、设置、Hook 统计、更新和日志服务。
- `Views/`: 菜单面板、设置、日志和共享 Liquid Glass 样式。
@@ -155,7 +155,8 @@ Hook 统计的配置、存储、保留策略和统计口径见 [Docs/CodexHook.m
- 非 UI 类型、DTO、模型、服务辅助类型和静态工具需要显式 `nonisolated`, 避免 main actor 隔离泄漏到同步服务代码。
- `CodexStatusService` 是 actor, 负责 app-server 连接、缓存和重建。
- `CodexCLIVersionService` 是 actor, 全局和内置版本探测用 `async let` 并发启动; 子进程输出通过 `PipeReadBuffer` 收集。
-- `WorkflowStatsService` 是 actor, 串行维护和读取 workflow stats 快照。
+- `WorkflowService` 是 actor, 串行维护和读取 workflow 快照。
+- `WorkflowSyncScheduler` 是维护/同步任务的唯一调度者, 合并自动维护、同步开关、Hook 重新开启和同步可用性恢复触发的请求; `WorkflowViewModel.refreshMaintenance(synchronize:)` 只执行一次明确的维护刷新并发布快照。
- `RequestLogStorage` 可从后台同步写入, 用 `OSAllocatedUnfairLock` 保护; `@MainActor RequestLogStore` 只负责发布 SwiftUI 快照。
- `PipeReadBuffer` 是底层 `FileHandle`、`DispatchSourceRead` 和 semaphore 的唯一 `@unchecked Sendable` 边界, 读队列 `CodexBar.pipe-read` 使用 `.userInitiated` QoS。
- Hook 写入可能由多个 Codex 进程并发触发, 必须通过 `stats.lock` 和 `flock` 保护 `events/YYYY-MM-DD.jsonl` 和 `maintenance.json` 的一致性; `daily.jsonl` 由主 App 刷新维护流程写回。
@@ -182,6 +183,7 @@ Hook 统计的配置、存储、保留策略和统计口径见 [Docs/CodexHook.m
- `rateLimits` 或 `usage` 使用旧缓存时, 对应区域通过 `.markStale(true)` 降低透明度到 0.55, 不降低饱和度; 下一轮对应接口成功后恢复正常透明度。
- 重置时间格式是 `MM-dd HH:mm`, 使用等宽数字, 在额度行最右侧对齐。
- 更新时间行显示倒计时圆环、「数据更新时间」和 `HH:mm:ss`。
+- 更新时间行最右侧显示同步状态图标: 未开启为 `icloud.slash`, 已开启为空闲为 `icloud`, 正在同步为 `arrow.trianglehead.clockwise.icloud`, 同步失败为 `exclamationmark.icloud`; 失败态 tooltip 展示归类后的同步错误文案。
- 倒计时只在菜单面板可见时用 `TimelineView` 每秒 tick; 普通 tick 不做连续动画, 仅刷新起点变化时播放恢复动画。
- token 区域显示「单日峰值」和「全时累计」; `TokenCountText` 对 1K 以下显示完整整数, 1K 起显示 K/M/B。
- token 区域还显示「当前连胜」、「最长连胜」和「最长任务」。
@@ -205,9 +207,9 @@ Hook 统计的配置、存储、保留策略和统计口径见 [Docs/CodexHook.m
- 默认全局快捷键是 `⌘⇧W`; 快捷键录制至少需要两个修饰键, 不允许 Command-Space 或 Command-Tab; 注册冲突、无法识别和校验错误显示在快捷键行内。
- 设置页包含「启用 Codex Hook」开关; 开启后会写入全局 Codex Hook 配置, 用于近 30 周数据展示更多本机统计数据。
- 开启 Codex Hook 前必须通过当前 `CodexStatusService` app-server 会话调用 `config/read`, 如果 Codex 全局配置禁用了 Hook, 则不写入 `hooks.json`, 开启失败并在 Hook 选项下方提示。
-- 开启 Codex Hook 写入 `hooks.json` 后必须通过当前 app-server 会话调用 `hooks/list` 验证 `command`、`eventName`、`enabled`、`sourcePath`、`trustStatus`、`warnings` 和 `errors`; 未信任时提示用户去 Codex `/hooks` 信任。
+- 开启 Codex Hook 写入 `hooks.json` 后必须通过当前 app-server 会话调用 `hooks/list` 验证 `command`、`eventName`、`enabled`、`sourcePath`、`trustStatus`、`warnings` 和 `errors`; 未信任或已修改时, 只对来源为全局 `hooks.json` 且 command 属于当前 CodexBar 的 Hook 通过 `config/batchWrite` 自动写入 `hooks.state` 的 `trusted_hash`, 再重新验证。
- Codex Hook 开关下方只在必要时显示 Hook 相关错误; 不展示固定说明文案、启用状态或关闭状态文案。
-- 设置页包含「跨设备同步」开关; 仅在 Codex Hook 开启且 iCloud account status 为 available 时可操作。iCloud 不可用时开关禁用, 并在开关下方显示「iCloud 不可用」。
+- 设置页包含「跨设备同步」开关; 仅在 Codex Hook 开启且 CloudKit account status 为 available 时可操作。同步账号不可用时开关禁用, 并在开关下方显示「同步不可用」。
- 「跨设备同步」开启后, 主 App 在工作流统计维护刷新中把脱敏 daily 聚合按日期稳定排序、每批最多 25 天、每轮最多 20 秒上传到 CloudKit; 已成功上传的日期立即写入本地 `state.json`, 剩余日期留给后续刷新继续。
- 开机启动错误显示在设置组与底部按钮组之间的独立错误组; 无错误时不展示该组, 退出和检查更新按钮之间不展示错误文案。
@@ -267,8 +269,8 @@ fix: 修复 Codex 状态刷新
Tag:
-- tag 名格式 `v{MARKETING_VERSION}`, 例如 `v3.1.3`。
-- 使用附注 tag: `git tag -a v3.1.3 -m "Release v3.1.3"`。
+- tag 名格式 `v{MARKETING_VERSION}`, 例如 `v3.2.0`。
+- 使用附注 tag: `git tag -a v3.2.0 -m "Release v3.2.0"`。
## 最终检查
diff --git a/CLAUDE.md b/CLAUDE.md
index 77334d5..3535fcf 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -48,8 +48,8 @@ CodexStatusService (JSON-RPC over `codex app-server --listen stdio://`)
```
WorkflowHookEventRecorder (--hook-event stdin hook_event_name 子进程)
- → WorkflowStatsStorage (events/YYYY-MM-DD.jsonl / daily.jsonl,~/Library/Application Support/CodexBar/HookEvents/)
- → WorkflowStatsService → WorkflowSyncService(可选 CloudKit private database) → WorkflowStatsViewModel
+ → WorkflowStorage (events/YYYY-MM-DD.jsonl / daily.jsonl,~/Library/Application Support/CodexBar/HookEvents/)
+ → WorkflowService → WorkflowSyncService(可选 CloudKit private database) → WorkflowViewModel
→ UsageSummaryView / UsageHeatmap (统计只在热力图侧边详情面板中展示)
```
@@ -63,7 +63,7 @@ WorkflowHookEventRecorder (--hook-event stdin hook_event_name 子进程)
## 并发分工
-服务层对外暴露 async API,主要共享状态由 actor 隔离:`CodexStatusService` 管理 app-server 连接和缓存,`CodexCLIVersionService` 用 `async let` 并发探测全局/内置版本,`WorkflowStatsService` 串行维护本机统计。`RequestLogStorage` 可后台同步写入并用 `OSAllocatedUnfairLock` 保护,`RequestLogStore` 只在 MainActor 发布 SwiftUI 快照。`PipeReadBuffer` 是底层 `FileHandle` / `DispatchSourceRead` / semaphore 的唯一 `@unchecked Sendable` 边界。
+服务层对外暴露 async API,主要共享状态由 actor 隔离:`CodexStatusService` 管理 app-server 连接和缓存,`CodexCLIVersionService` 用 `async let` 并发探测全局/内置版本,`WorkflowService`(actor)串行维护本机统计、`WorkflowStorage`(`nonisolated enum`,与服务同文件)封装 HookEvents 目录与 `stats.lock`。工作流维护/同步刷新的并发由 `WorkflowSyncScheduler`(MainActor,冷却合并 + `isRunning` 串行)单点裁判;`WorkflowViewModel` 不自判维护并发,只执行一次明确的维护刷新(quick-refresh 路径仍走自身 `isRefreshing` + `RefreshTaskCoordinator`,不经 scheduler)。`RequestLogStorage` 可后台同步写入并用 `OSAllocatedUnfairLock` 保护,`RequestLogStore` 只在 MainActor 发布 SwiftUI 快照。`PipeReadBuffer` 是底层 `FileHandle` / `DispatchSourceRead` / semaphore 的唯一 `@unchecked Sendable` 边界。
## 外部依赖与更新
diff --git a/CodexBar.xcodeproj/project.pbxproj b/CodexBar.xcodeproj/project.pbxproj
index 8ff64e7..b971098 100644
--- a/CodexBar.xcodeproj/project.pbxproj
+++ b/CodexBar.xcodeproj/project.pbxproj
@@ -278,7 +278,7 @@
"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";
CODE_SIGN_STYLE = Automatic;
COMBINE_HIDPI_IMAGES = YES;
- CURRENT_PROJECT_VERSION = 28;
+ CURRENT_PROJECT_VERSION = 29;
DEVELOPMENT_TEAM = 4KJ362VJW5;
ENABLE_APP_INTENTS_METADATA_GENERATION = NO;
ENABLE_APP_SANDBOX = NO;
@@ -293,7 +293,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
- MARKETING_VERSION = 3.2.0;
+ MARKETING_VERSION = 3.2.1;
PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar;
PRODUCT_NAME = "$(TARGET_NAME)";
REGISTER_APP_GROUPS = YES;
@@ -316,7 +316,7 @@
"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";
CODE_SIGN_STYLE = Automatic;
COMBINE_HIDPI_IMAGES = YES;
- CURRENT_PROJECT_VERSION = 28;
+ CURRENT_PROJECT_VERSION = 29;
DEVELOPMENT_TEAM = 4KJ362VJW5;
ENABLE_APP_INTENTS_METADATA_GENERATION = NO;
ENABLE_APP_SANDBOX = NO;
@@ -331,7 +331,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
- MARKETING_VERSION = 3.2.0;
+ MARKETING_VERSION = 3.2.1;
PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar;
PRODUCT_NAME = "$(TARGET_NAME)";
PROVISIONING_PROFILE_SPECIFIER = "";
diff --git a/CodexBar/App/CodexBarApp.swift b/CodexBar/App/CodexBarApp.swift
index e4166b6..2b6676c 100644
--- a/CodexBar/App/CodexBarApp.swift
+++ b/CodexBar/App/CodexBarApp.swift
@@ -11,6 +11,9 @@ struct CodexBarApp: App {
if WorkflowHookEventRecorder.handleIfRequested() {
exit(EXIT_SUCCESS)
}
+
+ // 缩短系统工具提示首次出现的延迟 (毫秒)
+ UserDefaults.standard.set(200, forKey: "NSInitialToolTipDelay")
}
var body: some Scene {
diff --git a/CodexBar/Controllers/HeatmapDetailPanelController.swift b/CodexBar/Controllers/HeatmapDetailPanelController.swift
index 11cb8e9..62c4be4 100644
--- a/CodexBar/Controllers/HeatmapDetailPanelController.swift
+++ b/CodexBar/Controllers/HeatmapDetailPanelController.swift
@@ -111,14 +111,14 @@ final class HeatmapDetailPanelController {
attach(panel, to: menuSurfaceWindow)
}
- let panelSize = UsageHeatmapDayDetailView.panelSize(showsWorkflowStats: context.showsWorkflowStats)
+ let panelSize = UsageHeatmapDayDetailView.panelSize(showsWorkflow: context.showsWorkflow)
let position = panelPosition(
for: panelSize,
relativeTo: menuSurfaceWindow,
contentView: contentView,
anchorScreenFrame: context.anchorScreenFrame,
heatmapScreenFrame: context.heatmapScreenFrame,
- showsWorkflowStats: context.showsWorkflowStats,
+ showsWorkflow: context.showsWorkflow,
preferredSide: context.preferredSide
)
let request = PanelRequest(context: context, position: position)
@@ -275,7 +275,7 @@ final class HeatmapDetailPanelController {
}
let panel = DetailPanel(
- contentRect: NSRect(origin: .zero, size: UsageHeatmapDayDetailView.panelSize(showsWorkflowStats: true)),
+ contentRect: NSRect(origin: .zero, size: UsageHeatmapDayDetailView.panelSize(showsWorkflow: true)),
styleMask: [.borderless, .nonactivatingPanel],
backing: .buffered,
defer: false
@@ -319,8 +319,6 @@ final class HeatmapDetailPanelController {
}
private func updateContent(_ context: UsageHeatmapHoverContext) {
- let size = UsageHeatmapDayDetailView.panelSize(showsWorkflowStats: context.showsWorkflowStats)
-
if let detailModel {
withAnimation(Animation.codexStatus) {
detailModel.context = context
@@ -336,7 +334,6 @@ final class HeatmapDetailPanelController {
}
configurePanelLayers()
- panel?.setContentSize(size)
}
private func configurePanelLayers() {
@@ -373,7 +370,7 @@ final class HeatmapDetailPanelController {
contentView: NSView?,
anchorScreenFrame: CGRect?,
heatmapScreenFrame: CGRect?,
- showsWorkflowStats: Bool,
+ showsWorkflow: Bool,
preferredSide: UsageHeatmapDetailSide
) -> PanelPosition {
// 优先贴在请求侧, 空间不足时换边, 最后仍夹紧到屏幕可见区域
@@ -408,7 +405,7 @@ final class HeatmapDetailPanelController {
visibleFrame: visibleFrame,
anchorScreenFrame: anchorScreenFrame,
heatmapScreenFrame: heatmapScreenFrame,
- showsWorkflowStats: showsWorkflowStats
+ showsWorkflow: showsWorkflow
),
width: panelSize.width,
height: panelSize.height
@@ -431,9 +428,9 @@ final class HeatmapDetailPanelController {
visibleFrame: CGRect,
anchorScreenFrame: CGRect?,
heatmapScreenFrame: CGRect?,
- showsWorkflowStats: Bool
+ showsWorkflow: Bool
) -> CGFloat {
- let proposedY: CGFloat = if showsWorkflowStats {
+ let proposedY: CGFloat = if showsWorkflow {
menuSurfaceFrame.minY
} else if let heatmapScreenFrame {
heatmapScreenFrame.maxY - panelSize.height
diff --git a/CodexBar/Controllers/SettingsWindowController.swift b/CodexBar/Controllers/SettingsWindowController.swift
index ecae744..fe731ee 100644
--- a/CodexBar/Controllers/SettingsWindowController.swift
+++ b/CodexBar/Controllers/SettingsWindowController.swift
@@ -7,25 +7,25 @@ final class SettingsWindowController: HostingWindowController {
private let viewModel: CodexStatusViewModel
private let appUpdater: AppUpdater
private let codexHookSettings: CodexHookSettings
- private let cloudSyncSettings: WorkflowSyncSettings
+ private let syncSettings: WorkflowSyncSettings
private let globalHotKeySettings: GlobalHotKeySettings
- private let onICloudSyncChanged: () -> Void
+ private let onSyncChanged: (Bool) -> Void
init(
viewModel: CodexStatusViewModel,
appUpdater: AppUpdater,
codexHookSettings: CodexHookSettings,
- cloudSyncSettings: WorkflowSyncSettings,
+ syncSettings: WorkflowSyncSettings,
globalHotKeySettings: GlobalHotKeySettings,
screenProvider: @escaping () -> NSScreen?,
- onICloudSyncChanged: @escaping () -> Void
+ onSyncChanged: @escaping (Bool) -> Void
) {
self.viewModel = viewModel
self.appUpdater = appUpdater
self.codexHookSettings = codexHookSettings
- self.cloudSyncSettings = cloudSyncSettings
+ self.syncSettings = syncSettings
self.globalHotKeySettings = globalHotKeySettings
- self.onICloudSyncChanged = onICloudSyncChanged
+ self.onSyncChanged = onSyncChanged
super.init(screenProvider: screenProvider)
}
@@ -38,9 +38,9 @@ final class SettingsWindowController: HostingWindowController {
let hostingController = NSHostingController(
rootView: AppSettingsView(
codexHookSettings: codexHookSettings,
- cloudSyncSettings: cloudSyncSettings,
+ syncSettings: syncSettings,
globalHotKeySettings: globalHotKeySettings,
- onICloudSyncChanged: onICloudSyncChanged
+ onSyncChanged: onSyncChanged
)
.environmentObject(viewModel)
.environmentObject(appUpdater)
@@ -78,6 +78,6 @@ final class SettingsWindowController: HostingWindowController {
private func refreshSettingsState() {
codexHookSettings.refresh()
codexHookSettings.verifyInstalledHooks()
- cloudSyncSettings.refresh()
+ syncSettings.refresh()
}
}
diff --git a/CodexBar/Controllers/StatusItemController.swift b/CodexBar/Controllers/StatusItemController.swift
index 29fdf49..4266fab 100644
--- a/CodexBar/Controllers/StatusItemController.swift
+++ b/CodexBar/Controllers/StatusItemController.swift
@@ -7,9 +7,9 @@ import SwiftUI
final class CodexBarAppDelegate: NSObject, NSApplicationDelegate {
private let codexStatusService = CodexStatusService()
lazy var viewModel = CodexStatusViewModel(service: codexStatusService)
- let workflowStatsViewModel = WorkflowStatsViewModel()
+ let workflowViewModel = WorkflowViewModel()
lazy var codexHookSettings = CodexHookSettings(codexStatusService: codexStatusService)
- let cloudSyncSettings = WorkflowSyncSettings()
+ let syncSettings = WorkflowSyncSettings()
let globalHotKeySettings = GlobalHotKeySettings()
let appUpdater = AppUpdater()
@@ -18,9 +18,9 @@ final class CodexBarAppDelegate: NSObject, NSApplicationDelegate {
func applicationDidFinishLaunching(_: Notification) {
let controller = StatusItemController(
viewModel: viewModel,
- workflowStatsViewModel: workflowStatsViewModel,
+ workflowViewModel: workflowViewModel,
codexHookSettings: codexHookSettings,
- cloudSyncSettings: cloudSyncSettings,
+ syncSettings: syncSettings,
globalHotKeySettings: globalHotKeySettings,
appUpdater: appUpdater
)
@@ -37,9 +37,9 @@ final class CodexBarAppDelegate: NSObject, NSApplicationDelegate {
@MainActor
private final class StatusItemController: NSObject {
private let viewModel: CodexStatusViewModel
- private let workflowStatsViewModel: WorkflowStatsViewModel
+ private let workflowViewModel: WorkflowViewModel
private let codexHookSettings: CodexHookSettings
- private let cloudSyncSettings: WorkflowSyncSettings
+ private let syncSettings: WorkflowSyncSettings
private let globalHotKeySettings: GlobalHotKeySettings
private let appUpdater: AppUpdater
private let statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength)
@@ -59,18 +59,25 @@ private final class StatusItemController: NSObject {
viewModel: viewModel,
appUpdater: appUpdater,
codexHookSettings: codexHookSettings,
- cloudSyncSettings: cloudSyncSettings,
+ syncSettings: syncSettings,
globalHotKeySettings: globalHotKeySettings
) { [weak self] in
self?.statusItem.button?.window?.screen
- } onICloudSyncChanged: { [weak self] in
- self?.workflowStatsViewModel.refresh(performMaintenance: true)
+ } onSyncChanged: { [weak self] enabled in
+ self?.handleSyncChanged(enabled)
}
private lazy var logWindowController = LogWindowController { [weak self] in
self?.statusItem.button?.window?.screen
}
+ private lazy var workflowSyncScheduler = WorkflowSyncScheduler(
+ viewModel: workflowViewModel,
+ canSynchronize: { [weak self] in
+ self?.canSynchronizeWorkflow == true
+ }
+ )
+
private lazy var menuSurfaceFadeCoordinator = MenuSurfaceFadeCoordinator(
contentViewProvider: { [weak self] in
self?.activeMenuSurfaceContentView
@@ -102,16 +109,16 @@ private final class StatusItemController: NSObject {
init(
viewModel: CodexStatusViewModel,
- workflowStatsViewModel: WorkflowStatsViewModel,
+ workflowViewModel: WorkflowViewModel,
codexHookSettings: CodexHookSettings,
- cloudSyncSettings: WorkflowSyncSettings,
+ syncSettings: WorkflowSyncSettings,
globalHotKeySettings: GlobalHotKeySettings,
appUpdater: AppUpdater
) {
self.viewModel = viewModel
- self.workflowStatsViewModel = workflowStatsViewModel
+ self.workflowViewModel = workflowViewModel
self.codexHookSettings = codexHookSettings
- self.cloudSyncSettings = cloudSyncSettings
+ self.syncSettings = syncSettings
self.globalHotKeySettings = globalHotKeySettings
self.appUpdater = appUpdater
super.init()
@@ -134,6 +141,8 @@ private final class StatusItemController: NSObject {
configurePopover()
observeGlobalHotKeySettings()
observeViewModel()
+ observeWorkflowSyncState()
+ codexHookSettings.refresh()
updateStatusImage()
viewModel.startAutoRefresh()
}
@@ -141,6 +150,7 @@ private final class StatusItemController: NSObject {
func uninstall() {
closeMenuSurface(animated: false)
auxiliaryWindowFocusRestoreTask?.cancel()
+ workflowSyncScheduler.cancel()
setAuxiliaryWindowKeyFocus(true)
globalHotKeyController.uninstall()
cancellables.removeAll()
@@ -170,8 +180,9 @@ private final class StatusItemController: NSObject {
private func makeMenuHostingController(usesPreferredContentSize: Bool) -> NSHostingController<AnyView> {
let rootView = CodexStatusMenuView(
viewModel: viewModel,
- workflowStatsViewModel: workflowStatsViewModel,
+ workflowViewModel: workflowViewModel,
codexHookSettings: codexHookSettings,
+ syncSettings: syncSettings,
menuSurfaceVisibility: menuSurfaceVisibility,
onUsageHeatmapHoverChange: { [weak self] context in
self?.updateHeatmapDetailPanel(context)
@@ -204,7 +215,39 @@ private final class StatusItemController: NSObject {
guard let self else {
return
}
- refreshWorkflowStatsIfHookEnabled(performMaintenance: true)
+ refreshWorkflowIfHookEnabled(performMaintenance: true)
+ }
+ .store(in: &cancellables)
+ }
+
+ private func observeWorkflowSyncState() {
+ codexHookSettings.$isEnabled
+ .removeDuplicates()
+ .sink { [weak self] isEnabled in
+ guard let self else {
+ return
+ }
+
+ if isEnabled {
+ workflowSyncScheduler.requestSync()
+ } else {
+ workflowSyncScheduler.clearPendingMaintenance()
+ }
+ }
+ .store(in: &cancellables)
+
+ syncSettings.$syncAvailability
+ .removeDuplicates()
+ .sink { [weak self] availability in
+ guard let self else {
+ return
+ }
+
+ if availability.isAvailable {
+ workflowSyncScheduler.requestSync()
+ } else {
+ workflowSyncScheduler.clearPendingSync()
+ }
}
.store(in: &cancellables)
}
@@ -374,7 +417,7 @@ private final class StatusItemController: NSObject {
private func completeMenuSurfaceOpen() {
menuSurfaceVisibility.isVisible = true
- refreshWorkflowStatsIfHookEnabled(performMaintenance: false)
+ refreshWorkflowIfHookEnabled(performMaintenance: false)
menuSurfaceDismissMonitor.install { [weak self] in
self?.closeMenuSurface()
}
@@ -543,14 +586,35 @@ private final class StatusItemController: NSObject {
}
}
- private func refreshWorkflowStatsIfHookEnabled(performMaintenance: Bool) {
+ private func refreshWorkflowIfHookEnabled(performMaintenance: Bool) {
// Hook 开关可能被外部 Codex 配置改动, 每次需要统计前都先读 hooks.json
codexHookSettings.refresh()
- if codexHookSettings.isEnabled {
- workflowStatsViewModel.refreshIfNeeded(performMaintenance: performMaintenance)
+ guard codexHookSettings.isEnabled else {
+ workflowSyncScheduler.clearPendingMaintenance()
+ return
+ }
+
+ if performMaintenance {
+ workflowSyncScheduler.requestMaintenance(allowsSync: true)
+ } else {
+ workflowViewModel.refreshIfNeeded()
+ }
+ }
+
+ private func handleSyncChanged(_ isEnabled: Bool) {
+ if isEnabled {
+ workflowSyncScheduler.requestSync()
+ } else {
+ workflowSyncScheduler.clearPendingSync()
}
}
+ private var canSynchronizeWorkflow: Bool {
+ codexHookSettings.isEnabled
+ && WorkflowSyncSettings.isEnabled()
+ && syncSettings.isSyncAvailable
+ }
+
private func updateHeatmapDetailPanel(_ context: UsageHeatmapHoverContext?) {
guard isActiveMenuSurfaceVisible,
let menuSurfaceContentView = activeMenuSurfaceContentView,
diff --git a/CodexBar/Models/CodexWorkflowStatsModels.swift b/CodexBar/Models/CodexWorkflowModels.swift
similarity index 76%
rename from CodexBar/Models/CodexWorkflowStatsModels.swift
rename to CodexBar/Models/CodexWorkflowModels.swift
index 20cf929..c54b79d 100644
--- a/CodexBar/Models/CodexWorkflowStatsModels.swift
+++ b/CodexBar/Models/CodexWorkflowModels.swift
@@ -1,7 +1,7 @@
import Foundation
/// 写入 JSONL 时固定字段顺序, 便于人工排查和 diff
-private nonisolated enum WorkflowStatsJSON {
+private nonisolated enum WorkflowJSON {
static func lineData(_ fields: [String]) -> Data {
let json = "{\(fields.joined(separator: ","))}"
return Data(json.utf8) + Data([0x0A])
@@ -26,7 +26,7 @@ private nonisolated enum WorkflowStatsJSON {
guard let text = String(bytes: data, encoding: .utf8) else {
throw EncodingError.invalidValue(
value,
- .init(codingPath: [], debugDescription: "Encoded workflow stats JSON was not UTF-8")
+ .init(codingPath: [], debugDescription: "Encoded workflow JSON was not UTF-8")
)
}
return text
@@ -122,17 +122,17 @@ nonisolated struct WorkflowHookEvent: Decodable, Equatable {
func jsonLineData() throws -> Data {
let fields = try [
- WorkflowStatsJSON.field("timestamp", CodexDateFormat.localTimestampString(from: timestamp)),
- WorkflowStatsJSON.field("event", name),
- WorkflowStatsJSON.field("model", modelName),
- WorkflowStatsJSON.field("permission", permissionMode),
- WorkflowStatsJSON.field("session", sessionId),
- WorkflowStatsJSON.field("turn", turnId),
- WorkflowStatsJSON.field("tool", toolName),
- WorkflowStatsJSON.field("cwd", directoryPath)
+ WorkflowJSON.field("timestamp", CodexDateFormat.localTimestampString(from: timestamp)),
+ WorkflowJSON.field("event", name),
+ WorkflowJSON.field("model", modelName),
+ WorkflowJSON.field("permission", permissionMode),
+ WorkflowJSON.field("session", sessionId),
+ WorkflowJSON.field("turn", turnId),
+ WorkflowJSON.field("tool", toolName),
+ WorkflowJSON.field("cwd", directoryPath)
]
- return WorkflowStatsJSON.lineData(fields)
+ return WorkflowJSON.lineData(fields)
}
private enum CodingKeys: String, CodingKey {
@@ -148,7 +148,7 @@ nonisolated struct WorkflowHookEvent: Decodable, Equatable {
}
/// 热力图详情面板直接消费的每日统计
-nonisolated struct WorkflowDailyStats: Equatable, Identifiable {
+nonisolated struct WorkflowDailyMetrics: Equatable, Identifiable {
let startDate: String
let sessionCount: Int
let turnCount: Int
@@ -179,8 +179,8 @@ nonisolated struct WorkflowDailyStats: Equatable, Identifiable {
self.subagentCount = subagentCount
}
- static func empty(startDate: String) -> WorkflowDailyStats {
- WorkflowDailyStats(
+ static func empty(startDate: String) -> WorkflowDailyMetrics {
+ WorkflowDailyMetrics(
startDate: startDate,
sessionCount: 0,
turnCount: 0,
@@ -212,8 +212,8 @@ nonisolated struct WorkflowDailyStats: Equatable, Identifiable {
subagentCount = max(subagentStartCount, subagentStopCount)
}
- func adding(_ other: WorkflowDailyStats) -> WorkflowDailyStats {
- WorkflowDailyStats(
+ func adding(_ other: WorkflowDailyMetrics) -> WorkflowDailyMetrics {
+ WorkflowDailyMetrics(
startDate: startDate,
sessionCount: sessionCount + other.sessionCount,
turnCount: turnCount + other.turnCount,
@@ -225,49 +225,49 @@ nonisolated struct WorkflowDailyStats: Equatable, Identifiable {
}
}
-/// WorkflowStatsService 发布给 UI 的近端快照
-nonisolated struct WorkflowStatsSnapshot: Equatable {
+/// WorkflowService 发布给 UI 的近端快照
+nonisolated struct WorkflowSnapshot: Equatable {
let generatedAt: Date
- let dailyStats: [WorkflowDailyStats]
+ let dailyMetrics: [WorkflowDailyMetrics]
- static let empty = WorkflowStatsSnapshot(generatedAt: Date(), dailyStats: [])
+ static let empty = WorkflowSnapshot(generatedAt: Date(), dailyMetrics: [])
- init(generatedAt: Date = Date(), dailyStats: [WorkflowDailyStats]) {
+ init(generatedAt: Date = Date(), dailyMetrics: [WorkflowDailyMetrics]) {
self.generatedAt = generatedAt
- self.dailyStats = dailyStats
+ self.dailyMetrics = dailyMetrics
}
init(dailyAggregates: [WorkflowDailyAggregate], generatedAt: Date = Date()) {
self.generatedAt = generatedAt
- dailyStats = dailyAggregates
- .map(\.stats)
+ dailyMetrics = dailyAggregates
+ .map(\.metrics)
.sorted { $0.startDate < $1.startDate }
}
init(
localAggregates: [WorkflowDailyAggregate],
- cloudRecords: [WorkflowCloudDailyRecord],
+ syncedRecords: [WorkflowSyncedDailyRecord],
currentDeviceId: String?,
generatedAt: Date = Date()
) {
self.generatedAt = generatedAt
- var statsByDate = [String: WorkflowDailyStats]()
+ var metricsByDate = [String: WorkflowDailyMetrics]()
localAggregates
- .map(\.stats)
- .forEach { Self.merge($0, into: &statsByDate) }
+ .map(\.metrics)
+ .forEach { Self.merge($0, into: &metricsByDate) }
- cloudRecords
+ syncedRecords
.filter { $0.deviceId != currentDeviceId }
- .map(\.daily.stats)
- .forEach { Self.merge($0, into: &statsByDate) }
+ .map(\.daily.metrics)
+ .forEach { Self.merge($0, into: &metricsByDate) }
- dailyStats = statsByDate.values.sorted { $0.startDate < $1.startDate }
+ dailyMetrics = metricsByDate.values.sorted { $0.startDate < $1.startDate }
}
- func recentWeekGrid(columnCount: Int, endingDaysAgo: Int = 0, today: Date = Date()) -> [WorkflowDailyStats?] {
- let statsByDate = dailyStats.reduce(into: [String: WorkflowDailyStats]()) { result, stats in
- result[stats.startDate] = stats
+ func recentWeekGrid(columnCount: Int, endingDaysAgo: Int = 0, today: Date = Date()) -> [WorkflowDailyMetrics?] {
+ let metricsByDate = dailyMetrics.reduce(into: [String: WorkflowDailyMetrics]()) { result, metrics in
+ result[metrics.startDate] = metrics
}
return CodexWeekGrid.dates(
@@ -278,19 +278,19 @@ nonisolated struct WorkflowStatsSnapshot: Equatable {
.map { date in
date.map {
let startDate = CodexDateFormat.dayString(from: $0)
- return statsByDate[startDate] ?? WorkflowDailyStats.empty(startDate: startDate)
+ return metricsByDate[startDate] ?? WorkflowDailyMetrics.empty(startDate: startDate)
}
}
}
private static func merge(
- _ stats: WorkflowDailyStats,
- into statsByDate: inout [String: WorkflowDailyStats]
+ _ metrics: WorkflowDailyMetrics,
+ into metricsByDate: inout [String: WorkflowDailyMetrics]
) {
- if let existing = statsByDate[stats.startDate] {
- statsByDate[stats.startDate] = existing.adding(stats)
+ if let existing = metricsByDate[metrics.startDate] {
+ metricsByDate[metrics.startDate] = existing.adding(metrics)
} else {
- statsByDate[stats.startDate] = stats
+ metricsByDate[metrics.startDate] = metrics
}
}
}
@@ -428,8 +428,8 @@ nonisolated struct WorkflowDailyAggregate: Codable, Equatable, Identifiable {
turnCount ?? turnIds?.count ?? stopCount
}
- var stats: WorkflowDailyStats {
- WorkflowDailyStats(
+ var metrics: WorkflowDailyMetrics {
+ WorkflowDailyMetrics(
startDate: date,
sessionCount: resolvedSessionCount,
turnCount: resolvedTurnCount,
@@ -448,8 +448,8 @@ nonisolated struct WorkflowDailyAggregate: Codable, Equatable, Identifiable {
today: Date = Date(),
calendar: Calendar = .current
) -> [WorkflowDailyAggregate] {
- let retentionCutoffDate = WorkflowStatsStorage.retentionCutoffDate(today: today, calendar: calendar)
- let identifierCutoffDate = WorkflowStatsStorage.identifierRetentionCutoffDate(today: today, calendar: calendar)
+ let retentionCutoffDate = WorkflowStorage.retentionCutoffDate(today: today, calendar: calendar)
+ let identifierCutoffDate = WorkflowStorage.identifierRetentionCutoffDate(today: today, calendar: calendar)
return aggregates.compactMap { aggregate in
guard let date = Self.date(from: aggregate.date), date >= retentionCutoffDate else {
@@ -475,29 +475,29 @@ nonisolated struct WorkflowDailyAggregate: Codable, Equatable, Identifiable {
func jsonLineData() throws -> Data {
let fields = try [
- WorkflowStatsJSON.field("date", date),
- WorkflowStatsJSON.field("eventCount", eventCount),
- WorkflowStatsJSON.field("sessionStartCount", sessionStartCount),
- WorkflowStatsJSON.field("stopCount", stopCount),
- WorkflowStatsJSON.field("preToolUseCount", preToolUseCount),
- WorkflowStatsJSON.field("postToolUseCount", postToolUseCount),
- WorkflowStatsJSON.field("permissionRequestCount", permissionRequestCount),
- WorkflowStatsJSON.field("preCompactCount", preCompactCount),
- WorkflowStatsJSON.field("postCompactCount", postCompactCount),
- WorkflowStatsJSON.field("subagentStartCount", subagentStartCount),
- WorkflowStatsJSON.field("subagentStopCount", subagentStopCount),
- WorkflowStatsJSON.field("sessionCount", sessionCount),
- WorkflowStatsJSON.field("turnCount", turnCount),
- WorkflowStatsJSON.field("projectCounts", projectCounts),
- WorkflowStatsJSON.field("sessionIds", sessionIds),
- WorkflowStatsJSON.field("turnIds", turnIds)
+ WorkflowJSON.field("date", date),
+ WorkflowJSON.field("eventCount", eventCount),
+ WorkflowJSON.field("sessionStartCount", sessionStartCount),
+ WorkflowJSON.field("stopCount", stopCount),
+ WorkflowJSON.field("preToolUseCount", preToolUseCount),
+ WorkflowJSON.field("postToolUseCount", postToolUseCount),
+ WorkflowJSON.field("permissionRequestCount", permissionRequestCount),
+ WorkflowJSON.field("preCompactCount", preCompactCount),
+ WorkflowJSON.field("postCompactCount", postCompactCount),
+ WorkflowJSON.field("subagentStartCount", subagentStartCount),
+ WorkflowJSON.field("subagentStopCount", subagentStopCount),
+ WorkflowJSON.field("sessionCount", sessionCount),
+ WorkflowJSON.field("turnCount", turnCount),
+ WorkflowJSON.field("projectCounts", projectCounts),
+ WorkflowJSON.field("sessionIds", sessionIds),
+ WorkflowJSON.field("turnIds", turnIds)
]
- return WorkflowStatsJSON.lineData(fields)
+ return WorkflowJSON.lineData(fields)
}
- var cloudAggregate: WorkflowCloudDailyAggregate {
- WorkflowCloudDailyAggregate(
+ var syncedAggregate: WorkflowSyncedDailyAggregate {
+ WorkflowSyncedDailyAggregate(
date: date,
eventCount: eventCount,
sessionStartCount: sessionStartCount,
@@ -509,17 +509,17 @@ nonisolated struct WorkflowDailyAggregate: Codable, Equatable, Identifiable {
postCompactCount: postCompactCount,
subagentStartCount: subagentStartCount,
subagentStopCount: subagentStopCount,
- sessionCount: cloudSessionCount,
- turnCount: cloudTurnCount,
+ sessionCount: syncedSessionCount,
+ turnCount: syncedTurnCount,
projectCounts: projectCounts
)
}
- private var cloudSessionCount: Int? {
+ private var syncedSessionCount: Int? {
sessionCount ?? Self.nonEmptyIdentifierCount(sessionIds)
}
- private var cloudTurnCount: Int? {
+ private var syncedTurnCount: Int? {
turnCount ?? Self.nonEmptyIdentifierCount(turnIds)
}
@@ -574,8 +574,8 @@ nonisolated struct WorkflowDailyAggregate: Codable, Equatable, Identifiable {
}
}
-/// iCloud 中保存的脱敏每日聚合行: 对应 daily.jsonl 但不包含 sessionIds / turnIds
-nonisolated struct WorkflowCloudDailyAggregate: Codable, Equatable, Identifiable {
+/// 同步存储中保存的脱敏每日聚合行: 对应 daily.jsonl 但不包含 sessionIds / turnIds
+nonisolated struct WorkflowSyncedDailyAggregate: Codable, Equatable, Identifiable {
let date: String
var eventCount: Int
var sessionStartCount: Int
@@ -595,8 +595,8 @@ nonisolated struct WorkflowCloudDailyAggregate: Codable, Equatable, Identifiable
date
}
- var stats: WorkflowDailyStats {
- WorkflowDailyStats(
+ var metrics: WorkflowDailyMetrics {
+ WorkflowDailyMetrics(
startDate: date,
sessionCount: sessionCount ?? sessionStartCount,
turnCount: turnCount ?? stopCount,
@@ -612,29 +612,29 @@ nonisolated struct WorkflowCloudDailyAggregate: Codable, Equatable, Identifiable
func jsonLineData() throws -> Data {
let fields = try [
- WorkflowStatsJSON.field("date", date),
- WorkflowStatsJSON.field("eventCount", eventCount),
- WorkflowStatsJSON.field("sessionStartCount", sessionStartCount),
- WorkflowStatsJSON.field("stopCount", stopCount),
- WorkflowStatsJSON.field("preToolUseCount", preToolUseCount),
- WorkflowStatsJSON.field("postToolUseCount", postToolUseCount),
- WorkflowStatsJSON.field("permissionRequestCount", permissionRequestCount),
- WorkflowStatsJSON.field("preCompactCount", preCompactCount),
- WorkflowStatsJSON.field("postCompactCount", postCompactCount),
- WorkflowStatsJSON.field("subagentStartCount", subagentStartCount),
- WorkflowStatsJSON.field("subagentStopCount", subagentStopCount),
- WorkflowStatsJSON.field("sessionCount", sessionCount),
- WorkflowStatsJSON.field("turnCount", turnCount),
- WorkflowStatsJSON.field("projectCounts", projectCounts)
+ WorkflowJSON.field("date", date),
+ WorkflowJSON.field("eventCount", eventCount),
+ WorkflowJSON.field("sessionStartCount", sessionStartCount),
+ WorkflowJSON.field("stopCount", stopCount),
+ WorkflowJSON.field("preToolUseCount", preToolUseCount),
+ WorkflowJSON.field("postToolUseCount", postToolUseCount),
+ WorkflowJSON.field("permissionRequestCount", permissionRequestCount),
+ WorkflowJSON.field("preCompactCount", preCompactCount),
+ WorkflowJSON.field("postCompactCount", postCompactCount),
+ WorkflowJSON.field("subagentStartCount", subagentStartCount),
+ WorkflowJSON.field("subagentStopCount", subagentStopCount),
+ WorkflowJSON.field("sessionCount", sessionCount),
+ WorkflowJSON.field("turnCount", turnCount),
+ WorkflowJSON.field("projectCounts", projectCounts)
]
- return WorkflowStatsJSON.lineData(fields)
+ return WorkflowJSON.lineData(fields)
}
}
-nonisolated struct WorkflowCloudDailyRecord: Codable, Equatable, Identifiable {
+nonisolated struct WorkflowSyncedDailyRecord: Codable, Equatable, Identifiable {
let deviceId: String
- let daily: WorkflowCloudDailyAggregate
+ let daily: WorkflowSyncedDailyAggregate
var updatedAt: Date?
var id: String {
diff --git a/CodexBar/Models/UsageHeatmapDay.swift b/CodexBar/Models/UsageHeatmapDay.swift
index 4f543d8..9d8a4c8 100644
--- a/CodexBar/Models/UsageHeatmapDay.swift
+++ b/CodexBar/Models/UsageHeatmapDay.swift
@@ -4,7 +4,7 @@ import Foundation
nonisolated struct UsageHeatmapDay: Equatable, Identifiable {
let startDate: String
let tokenCount: Int?
- let workflowStats: WorkflowDailyStats
+ let workflow: WorkflowDailyMetrics
var id: String {
startDate
@@ -16,21 +16,21 @@ nonisolated struct UsageHeatmapDay: Equatable, Identifiable {
static func grid(
usage: CodexUsageSnapshot,
- workflowStats: WorkflowStatsSnapshot,
- showsWorkflowStats: Bool,
+ workflow: WorkflowSnapshot,
+ showsWorkflow: Bool,
columnCount: Int,
today: Date
) -> [UsageHeatmapDay?] {
let todayTokenCount = usage.tokenCount(on: today)
// Hook 开启时当天工作流统计可见
// Hook 关闭时只在 token bucket 已返回时展示今天
- let endingDaysAgo = showsWorkflowStats || todayTokenCount != nil ? 0 : 1
+ let endingDaysAgo = showsWorkflow || todayTokenCount != nil ? 0 : 1
let tokenDays = usage.recentWeekGrid(
columnCount: columnCount,
endingDaysAgo: endingDaysAgo,
today: today
)
- let workflowDays = workflowStats.recentWeekGrid(
+ let workflowDays = workflow.recentWeekGrid(
columnCount: columnCount,
endingDaysAgo: endingDaysAgo,
today: today
@@ -46,7 +46,7 @@ nonisolated struct UsageHeatmapDay: Equatable, Identifiable {
private static func merge(
tokenDays: [DailyUsageBucket?],
- workflowDays: [WorkflowDailyStats?],
+ workflowDays: [WorkflowDailyMetrics?],
todayString: String,
todayTokenCount: Int?
) -> [UsageHeatmapDay?] {
@@ -58,7 +58,7 @@ nonisolated struct UsageHeatmapDay: Equatable, Identifiable {
return UsageHeatmapDay(
startDate: startDate,
tokenCount: startDate == todayString ? todayTokenCount : tokenDay?.tokens ?? 0,
- workflowStats: workflowDay ?? .empty(startDate: startDate)
+ workflow: workflowDay ?? .empty(startDate: startDate)
)
}
}
diff --git a/CodexBar/Services/Settings/WorkflowSyncSettings.swift b/CodexBar/Services/Settings/WorkflowSyncSettings.swift
index a2a98e4..9ed4680 100644
--- a/CodexBar/Services/Settings/WorkflowSyncSettings.swift
+++ b/CodexBar/Services/Settings/WorkflowSyncSettings.swift
@@ -2,13 +2,15 @@ import CloudKit
import Combine
import Foundation
-/// 设置页的工作流统计 iCloud 同步状态
+/// 设置页的工作流同步状态
@MainActor
final class WorkflowSyncSettings: ObservableObject {
@Published private(set) var isEnabled: Bool
@Published private(set) var isSyncing = false
+ @Published private(set) var hasSyncFailure = false
+ @Published private(set) var syncFailureMessage: String?
@Published private(set) var lastUploadAt: Date?
- @Published private(set) var iCloudAvailability = WorkflowSyncAvailability.unknown
+ @Published private(set) var syncAvailability = WorkflowSyncAvailability.unknown
private let defaults: UserDefaults
private var cancellables = Set<AnyCancellable>()
@@ -17,10 +19,10 @@ final class WorkflowSyncSettings: ObservableObject {
init(defaults: UserDefaults = .standard) {
self.defaults = defaults
- isEnabled = defaults.bool(forKey: Self.enabledKey)
+ isEnabled = Self.isEnabled(defaults: defaults)
lastUploadAt = Self.loadLastUploadAt()
observeSyncNotifications()
- refreshICloudAvailability()
+ refreshSyncAvailability()
}
deinit {
@@ -28,30 +30,38 @@ final class WorkflowSyncSettings: ObservableObject {
}
func refresh() {
- isEnabled = defaults.bool(forKey: Self.enabledKey)
+ isEnabled = Self.isEnabled(defaults: defaults)
+ if !isEnabled {
+ clearSyncActivity()
+ }
lastUploadAt = Self.loadLastUploadAt()
- refreshICloudAvailability()
+ refreshSyncAvailability()
}
- func setEnabled(_ enabled: Bool) {
- guard !enabled || iCloudAvailability.isAvailable else {
- return
+ @discardableResult
+ func setEnabled(_ enabled: Bool) -> Bool {
+ guard !enabled || syncAvailability.isAvailable else {
+ return false
}
+ let previousValue = isEnabled
defaults.set(enabled, forKey: Self.enabledKey)
if enabled {
defaults.set(true, forKey: Self.needsBackfillKey)
+ } else {
+ clearSyncActivity()
}
isEnabled = enabled
lastUploadAt = Self.loadLastUploadAt()
+ return previousValue != enabled
}
- var isICloudAvailable: Bool {
- iCloudAvailability.isAvailable
+ var isSyncAvailable: Bool {
+ syncAvailability.isAvailable
}
var unavailableMessage: String? {
- iCloudAvailability.isUnavailable ? "iCloud 不可用" : nil
+ syncAvailability.isUnavailable ? "同步不可用" : nil
}
var lastUploadAtText: String? {
@@ -74,54 +84,104 @@ final class WorkflowSyncSettings: ObservableObject {
}
private func observeSyncNotifications() {
- NotificationCenter.default.publisher(for: .workflowStatsICloudSyncDidStart)
+ NotificationCenter.default.publisher(for: .workflowSyncDidStart)
.sink { [weak self] _ in
Task { @MainActor in
- self?.isSyncing = true
+ self?.handleSyncDidStart()
}
}
.store(in: &cancellables)
- NotificationCenter.default.publisher(for: .workflowStatsICloudSyncDidFinish)
- .sink { [weak self] _ in
+ NotificationCenter.default.publisher(for: .workflowSyncDidFinish)
+ .sink { [weak self] notification in
Task { @MainActor in
- self?.isSyncing = false
- self?.lastUploadAt = Self.loadLastUploadAt()
+ guard let self else {
+ return
+ }
+
+ self.handleSyncDidFinish(notification)
}
}
.store(in: &cancellables)
}
- private func refreshICloudAvailability() {
+ private func refreshSyncAvailability() {
accountStatusGeneration += 1
let generation = accountStatusGeneration
accountStatusTask?.cancel()
accountStatusTask = Task { @MainActor [weak self] in
- let isAvailable = await Self.queryICloudAvailability()
+ let result = await Self.querySyncAvailability()
guard let self,
!Task.isCancelled,
generation == accountStatusGeneration else {
return
}
- iCloudAvailability = isAvailable ? .available : .unavailable
- if !isAvailable {
- isSyncing = false
- }
+ applyAvailabilityResult(result)
+ }
+ }
+
+ private func handleSyncDidStart() {
+ isSyncing = true
+ clearSyncFailure()
+ }
+
+ private func handleSyncDidFinish(_ notification: Notification) {
+ let didSucceed = notification.userInfo?[WorkflowSyncNotificationKey.didSucceed] as? Bool ?? true
+ let failureMessage = notification.userInfo?[WorkflowSyncNotificationKey.failureMessage] as? String
+
+ isSyncing = false
+ if didSucceed {
+ clearSyncFailure()
+ } else {
+ applySyncFailure(failureMessage)
}
+ lastUploadAt = Self.loadLastUploadAt()
+ }
+
+ private func applyAvailabilityResult(_ result: WorkflowSyncAvailabilityResult) {
+ syncAvailability = result.availability
+ guard result.availability.isUnavailable else {
+ return
+ }
+
+ isSyncing = false
+ applySyncFailure(result.failureReason?.message)
+ }
+
+ private func clearSyncActivity() {
+ isSyncing = false
+ clearSyncFailure()
+ }
+
+ private func clearSyncFailure() {
+ hasSyncFailure = false
+ syncFailureMessage = nil
+ }
+
+ private func applySyncFailure(_ message: String?) {
+ hasSyncFailure = isEnabled
+ syncFailureMessage = isEnabled
+ ? message ?? WorkflowSyncFailureReason.retryLater.message
+ : nil
}
- private nonisolated static func queryICloudAvailability() async -> Bool {
+ private nonisolated static func querySyncAvailability() async -> WorkflowSyncAvailabilityResult {
await withCheckedContinuation { continuation in
- CKContainer.default().accountStatus { status, _ in
- continuation.resume(returning: status == .available)
+ CKContainer.default().accountStatus { status, error in
+ continuation.resume(
+ returning: WorkflowSyncFailureReason.availabilityResult(
+ status: status,
+ error: error
+ )
+ )
}
}
}
private nonisolated static func loadLastUploadAt() -> Date? {
- let stateURL = WorkflowStatsStorage.iCloudSyncDirectoryURL()
+ let stateURL = WorkflowStorage.syncDirectoryURL()
.appendingPathComponent("state.json", isDirectory: false)
guard let data = try? Data(contentsOf: stateURL), !data.isEmpty,
let state = try? JSONDecoder().decode(LocalSyncState.self, from: data) else {
@@ -137,8 +197,8 @@ final class WorkflowSyncSettings: ObservableObject {
return formatter
}()
- private nonisolated static let enabledKey = "WorkflowiCloudSync.isEnabled"
- private nonisolated static let needsBackfillKey = "WorkflowiCloudSync.needsBackfill"
+ private nonisolated static let enabledKey = "WorkflowSync.isEnabled"
+ private nonisolated static let needsBackfillKey = "WorkflowSync.needsBackfill"
private nonisolated struct LocalSyncState: Decodable {
let lastUploadAt: Date?
@@ -159,7 +219,92 @@ nonisolated enum WorkflowSyncAvailability: Equatable {
}
}
+nonisolated struct WorkflowSyncAvailabilityResult {
+ let availability: WorkflowSyncAvailability
+ let failureReason: WorkflowSyncFailureReason?
+
+ static let available = WorkflowSyncAvailabilityResult(
+ availability: .available,
+ failureReason: nil
+ )
+
+ static func unavailable(
+ _ failureReason: WorkflowSyncFailureReason
+ ) -> WorkflowSyncAvailabilityResult {
+ WorkflowSyncAvailabilityResult(
+ availability: .unavailable,
+ failureReason: failureReason
+ )
+ }
+}
+
extension Notification.Name {
- nonisolated static let workflowStatsICloudSyncDidStart = Notification.Name("CodexBar.workflowStatsICloudSyncDidStart")
- nonisolated static let workflowStatsICloudSyncDidFinish = Notification.Name("CodexBar.workflowStatsICloudSyncDidFinish")
+ nonisolated static let workflowSyncDidStart = Notification.Name("CodexBar.workflowSyncDidStart")
+ nonisolated static let workflowSyncDidFinish = Notification.Name("CodexBar.workflowSyncDidFinish")
+}
+
+nonisolated enum WorkflowSyncNotificationKey {
+ static let didSucceed = "didSucceed"
+ static let failureMessage = "failureMessage"
+}
+
+nonisolated enum WorkflowSyncFailureReason: String {
+ case networkUnavailable
+ case accountUnavailable
+ case serviceUnavailable
+ case retryLater
+
+ var message: String {
+ switch self {
+ case .networkUnavailable:
+ "网络不可用"
+ case .accountUnavailable:
+ "账号不可用"
+ case .serviceUnavailable:
+ "服务暂时不可用"
+ case .retryLater:
+ "同步失败, 请稍后重试"
+ }
+ }
+}
+
+nonisolated extension WorkflowSyncFailureReason {
+ static func classify(_ error: Error) -> WorkflowSyncFailureReason {
+ guard let error = error as? CKError else {
+ return .retryLater
+ }
+
+ switch error.code {
+ case .networkUnavailable, .networkFailure:
+ return .networkUnavailable
+ case .notAuthenticated, .permissionFailure:
+ return .accountUnavailable
+ case .serviceUnavailable, .requestRateLimited, .zoneBusy:
+ return .serviceUnavailable
+ default:
+ return .retryLater
+ }
+ }
+
+ static func availabilityResult(
+ status: CKAccountStatus,
+ error: Error?
+ ) -> WorkflowSyncAvailabilityResult {
+ if let error {
+ return .unavailable(classify(error))
+ }
+
+ switch status {
+ case .available:
+ return .available
+ case .noAccount, .restricted:
+ return .unavailable(.accountUnavailable)
+ case .temporarilyUnavailable:
+ return .unavailable(.serviceUnavailable)
+ case .couldNotDetermine:
+ return .unavailable(.retryLater)
+ @unknown default:
+ return .unavailable(.retryLater)
+ }
+ }
}
diff --git a/CodexBar/Services/WorkflowStats/JSONLines.swift b/CodexBar/Services/Workflow/JSONLines.swift
similarity index 100%
rename from CodexBar/Services/WorkflowStats/JSONLines.swift
rename to CodexBar/Services/Workflow/JSONLines.swift
diff --git a/CodexBar/Services/WorkflowStats/WorkflowHookEventRecorder.swift b/CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift
similarity index 90%
rename from CodexBar/Services/WorkflowStats/WorkflowHookEventRecorder.swift
rename to CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift
index 991b856..fcbe761 100644
--- a/CodexBar/Services/WorkflowStats/WorkflowHookEventRecorder.swift
+++ b/CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift
@@ -42,18 +42,18 @@ nonisolated enum WorkflowHookEventRecorder {
turnId: turnId
)
- try recordStatsTransaction(event: event)
+ try recordWorkflowTransaction(event: event)
}
- private static func recordStatsTransaction(event: WorkflowHookEvent) throws {
- try WorkflowStatsStorage.withExclusiveLock {
- let dateKey = WorkflowStatsStorage.dateKey(for: event.timestamp)
- let eventLogURL = WorkflowStatsStorage.eventLogURL(for: dateKey)
- var maintenanceState = WorkflowStatsStorage.loadMaintenanceState()
+ private static func recordWorkflowTransaction(event: WorkflowHookEvent) throws {
+ try WorkflowStorage.withExclusiveLock {
+ let dateKey = WorkflowStorage.dateKey(for: event.timestamp)
+ let eventLogURL = WorkflowStorage.eventLogURL(for: dateKey)
+ var maintenanceState = WorkflowStorage.loadMaintenanceState()
try append(event.jsonLineData(), to: eventLogURL)
maintenanceState.markPending(dateKey)
- try WorkflowStatsStorage.saveMaintenanceState(maintenanceState)
+ try WorkflowStorage.saveMaintenanceState(maintenanceState)
}
}
diff --git a/CodexBar/Services/WorkflowStats/WorkflowStatsService.swift b/CodexBar/Services/Workflow/WorkflowService.swift
similarity index 77%
rename from CodexBar/Services/WorkflowStats/WorkflowStatsService.swift
rename to CodexBar/Services/Workflow/WorkflowService.swift
index 8a347e4..fd32369 100644
--- a/CodexBar/Services/WorkflowStats/WorkflowStatsService.swift
+++ b/CodexBar/Services/Workflow/WorkflowService.swift
@@ -3,46 +3,49 @@ import Darwin
import Foundation
/// 从 Hook 原始事件维护每日聚合, 对外只发布 UI 需要的统计快照
-actor WorkflowStatsService {
+actor WorkflowService {
private let eventsDirectoryURL: URL
private let dailyLogURL: URL
- private let cloudSyncService: WorkflowSyncService
+ private let syncService: WorkflowSyncService
private static let eventReadChunkSize = 64 * 1024
init(
- eventsDirectoryURL: URL = WorkflowStatsStorage.eventsDirectoryURL(),
- dailyLogURL: URL = WorkflowStatsStorage.dailyURL(),
- cloudSyncService: WorkflowSyncService = WorkflowSyncService()
+ eventsDirectoryURL: URL = WorkflowStorage.eventsDirectoryURL(),
+ dailyLogURL: URL = WorkflowStorage.dailyURL(),
+ syncService: WorkflowSyncService = WorkflowSyncService()
) {
self.eventsDirectoryURL = eventsDirectoryURL
self.dailyLogURL = dailyLogURL
- self.cloudSyncService = cloudSyncService
+ self.syncService = syncService
}
- func loadSnapshot(performMaintenance: Bool = false) async -> WorkflowStatsSnapshot {
+ func loadSnapshot(
+ performMaintenance: Bool = false,
+ synchronize: Bool = false
+ ) async -> WorkflowSnapshot {
var changedDates = Set<String>()
if performMaintenance {
changedDates = performMaintenanceIfNeeded()
}
let aggregates = loadDailyAggregates() ?? []
- let cloudSnapshot: WorkflowSyncSnapshot = if performMaintenance {
- await cloudSyncService.synchronizeIfEnabled(
+ let syncSnapshot: WorkflowSyncSnapshot = if synchronize {
+ await syncService.synchronizeIfEnabled(
localAggregates: aggregates,
changedDates: changedDates
)
} else {
- await cloudSyncService.snapshotFromCacheIfEnabled()
+ await syncService.snapshotFromCacheIfEnabled()
}
- guard !aggregates.isEmpty || !cloudSnapshot.records.isEmpty else {
+ guard !aggregates.isEmpty || !syncSnapshot.records.isEmpty else {
return .empty
}
- return WorkflowStatsSnapshot(
+ return WorkflowSnapshot(
localAggregates: aggregates,
- cloudRecords: cloudSnapshot.records,
- currentDeviceId: cloudSnapshot.currentDeviceId
+ syncedRecords: syncSnapshot.records,
+ currentDeviceId: syncSnapshot.currentDeviceId
)
}
@@ -60,7 +63,7 @@ actor WorkflowStatsService {
}
private func performMaintenanceIfNeeded() -> Set<String> {
- let beforePayloads = cloudPayloadByDate()
+ let beforePayloads = syncPayloadByDate()
do {
let tasks = try prepareMaintenanceTasks()
@@ -71,10 +74,10 @@ actor WorkflowStatsService {
return []
}
- return changedCloudPayloadDates(before: beforePayloads, after: cloudPayloadByDate())
+ return changedSyncPayloadDates(before: beforePayloads, after: syncPayloadByDate())
}
- private func perform(_ tasks: [WorkflowStatsMaintenanceTask]) {
+ private func perform(_ tasks: [WorkflowMaintenanceTask]) {
for task in tasks {
do {
let result = try buildDailyAggregate(for: task)
@@ -85,12 +88,12 @@ actor WorkflowStatsService {
}
}
- private func prepareMaintenanceTasks() throws -> [WorkflowStatsMaintenanceTask] {
+ private func prepareMaintenanceTasks() throws -> [WorkflowMaintenanceTask] {
let eventDateKeys = eventDateKeys()
let dailyDecodeResult = loadDailyAggregatesWithFailures()
- return try WorkflowStatsStorage.withExclusiveLock {
- var state = WorkflowStatsStorage.loadMaintenanceState()
+ return try WorkflowStorage.withExclusiveLock {
+ var state = WorkflowStorage.loadMaintenanceState()
var changedState = state.normalize()
let dailyByDate = dailyDecodeResult.values.reduce(into: [String: WorkflowDailyAggregate]()) { result, aggregate in
result[aggregate.date] = aggregate
@@ -112,7 +115,7 @@ actor WorkflowStatsService {
)
if changedState {
- try WorkflowStatsStorage.saveMaintenanceState(state)
+ try WorkflowStorage.saveMaintenanceState(state)
}
return tasks
@@ -123,13 +126,13 @@ actor WorkflowStatsService {
eventDateKeys: [String],
dailyDecodeResult: JSONLinesDecodeResult<WorkflowDailyAggregate>,
dailyByDate: [String: WorkflowDailyAggregate],
- state: inout WorkflowStatsMaintenanceState
+ state: inout WorkflowMaintenanceState
) -> Bool {
var changed = false
- if state.schema != WorkflowStatsMaintenanceState.currentSchema {
+ if state.schema != WorkflowMaintenanceState.currentSchema {
changed = markDirty(eventDateKeys, in: &state) || changed
- state.schema = WorkflowStatsMaintenanceState.currentSchema
+ state.schema = WorkflowMaintenanceState.currentSchema
changed = true
}
@@ -145,7 +148,7 @@ actor WorkflowStatsService {
private func reconcileEventFiles(
eventDateKeys: [String],
- state: inout WorkflowStatsMaintenanceState
+ state: inout WorkflowMaintenanceState
) -> Bool {
var changed = markDirty(eventDateKeys.filter { state.days[$0] == nil }, in: &state)
@@ -168,15 +171,15 @@ actor WorkflowStatsService {
}
private func makeMaintenanceTasks(
- state: inout WorkflowStatsMaintenanceState,
+ state: inout WorkflowMaintenanceState,
dailyByDate: [String: WorkflowDailyAggregate],
changedState: inout Bool
- ) -> [WorkflowStatsMaintenanceTask] {
+ ) -> [WorkflowMaintenanceTask] {
let dirty = Set(state.dirty)
var tasks = state.dirty.map { dirtyTask(for: $0) }
for dateKey in state.pending where !dirty.contains(dateKey) {
- let day = state.days[dateKey] ?? WorkflowStatsDayMaintenanceState()
+ let day = state.days[dateKey] ?? WorkflowDayMaintenanceState()
let size = eventLogSize(for: dateKey)
guard size > day.offset else {
state.removePending(dateKey)
@@ -206,7 +209,7 @@ actor WorkflowStatsService {
private func markDirty(
_ dateKeys: [String],
- in state: inout WorkflowStatsMaintenanceState
+ in state: inout WorkflowMaintenanceState
) -> Bool {
let previousDirty = state.dirty
let previousDays = state.days
@@ -218,8 +221,8 @@ actor WorkflowStatsService {
return previousDirty != state.dirty || previousDays != state.days
}
- private func dirtyTask(for dateKey: String, size: UInt64? = nil) -> WorkflowStatsMaintenanceTask {
- WorkflowStatsMaintenanceTask(
+ private func dirtyTask(for dateKey: String, size: UInt64? = nil) -> WorkflowMaintenanceTask {
+ WorkflowMaintenanceTask(
dateKey: dateKey,
startOffset: 0,
size: size ?? eventLogSize(for: dateKey),
@@ -230,11 +233,11 @@ actor WorkflowStatsService {
private func pendingTask(
for dateKey: String,
- day: WorkflowStatsDayMaintenanceState,
+ day: WorkflowDayMaintenanceState,
size: UInt64,
baseAggregate: WorkflowDailyAggregate
- ) -> WorkflowStatsMaintenanceTask {
- WorkflowStatsMaintenanceTask(
+ ) -> WorkflowMaintenanceTask {
+ WorkflowMaintenanceTask(
dateKey: dateKey,
startOffset: day.offset,
size: size,
@@ -248,7 +251,7 @@ actor WorkflowStatsService {
}
private func eventLogSize(for dateKey: String) -> UInt64 {
- WorkflowStatsStorage.fileSize(at: eventLogURL(for: dateKey))
+ WorkflowStorage.fileSize(at: eventLogURL(for: dateKey))
}
private func loadDailyAggregatesWithFailures() -> JSONLinesDecodeResult<WorkflowDailyAggregate> {
@@ -270,13 +273,13 @@ actor WorkflowStatsService {
return contents
.filter { $0.pathExtension == "jsonl" }
.map { $0.deletingPathExtension().lastPathComponent }
- .filter { WorkflowStatsStorage.isValidDateKey($0) }
+ .filter { WorkflowStorage.isValidDateKey($0) }
.sorted()
}
private func buildDailyAggregate(
- for task: WorkflowStatsMaintenanceTask
- ) throws -> WorkflowStatsMaintenanceResult {
+ for task: WorkflowMaintenanceTask
+ ) throws -> WorkflowMaintenanceResult {
var aggregate = task.baseAggregate ?? WorkflowDailyAggregate(date: task.dateKey)
var corrupt = task.existingCorrupt
var identifierCache = WorkflowDailyIdentifierCache(aggregate: aggregate)
@@ -295,7 +298,7 @@ actor WorkflowStatsService {
}
aggregate.compactIdentifiersIfNeeded(keepsIdentifiers: keepsIdentifiers)
- return WorkflowStatsMaintenanceResult(
+ return WorkflowMaintenanceResult(
dateKey: task.dateKey,
aggregate: aggregate,
size: task.size,
@@ -372,7 +375,7 @@ actor WorkflowStatsService {
return 0
}
- private func commit(_ result: WorkflowStatsMaintenanceResult) throws {
+ private func commit(_ result: WorkflowMaintenanceResult) throws {
guard try eventLogHasNotShrunk(for: result) else {
return
}
@@ -383,14 +386,14 @@ actor WorkflowStatsService {
try commitMaintenanceState(result)
}
- private func eventLogHasNotShrunk(for result: WorkflowStatsMaintenanceResult) throws -> Bool {
- try WorkflowStatsStorage.withExclusiveLock {
- let currentSize = WorkflowStatsStorage.fileSize(at: eventLogURL(for: result.dateKey))
- var state = WorkflowStatsStorage.loadMaintenanceState()
+ private func eventLogHasNotShrunk(for result: WorkflowMaintenanceResult) throws -> Bool {
+ try WorkflowStorage.withExclusiveLock {
+ let currentSize = WorkflowStorage.fileSize(at: eventLogURL(for: result.dateKey))
+ var state = WorkflowStorage.loadMaintenanceState()
guard currentSize >= result.size else {
state.markDirty(result.dateKey)
- try WorkflowStatsStorage.saveMaintenanceState(state)
+ try WorkflowStorage.saveMaintenanceState(state)
return false
}
@@ -434,9 +437,9 @@ actor WorkflowStatsService {
try normalizedData.write(to: dailyLogURL, options: .atomic)
}
- private func cloudPayloadByDate() -> [String: String] {
+ private func syncPayloadByDate() -> [String: String] {
loadDailyAggregatesWithFailures().values.reduce(into: [String: String]()) { result, aggregate in
- guard let data = try? aggregate.cloudAggregate.jsonLineData() else {
+ guard let data = try? aggregate.syncedAggregate.jsonLineData() else {
return
}
@@ -444,7 +447,7 @@ actor WorkflowStatsService {
}
}
- private func changedCloudPayloadDates(
+ private func changedSyncPayloadDates(
before: [String: String],
after: [String: String]
) -> Set<String> {
@@ -454,18 +457,18 @@ actor WorkflowStatsService {
})
}
- private func commitMaintenanceState(_ result: WorkflowStatsMaintenanceResult) throws {
- try WorkflowStatsStorage.withExclusiveLock {
- let currentSize = WorkflowStatsStorage.fileSize(at: eventLogURL(for: result.dateKey))
- var state = WorkflowStatsStorage.loadMaintenanceState()
+ private func commitMaintenanceState(_ result: WorkflowMaintenanceResult) throws {
+ try WorkflowStorage.withExclusiveLock {
+ let currentSize = WorkflowStorage.fileSize(at: eventLogURL(for: result.dateKey))
+ var state = WorkflowStorage.loadMaintenanceState()
guard currentSize >= result.size else {
state.markDirty(result.dateKey)
- try WorkflowStatsStorage.saveMaintenanceState(state)
+ try WorkflowStorage.saveMaintenanceState(state)
return
}
- state.days[result.dateKey] = WorkflowStatsDayMaintenanceState(
+ state.days[result.dateKey] = WorkflowDayMaintenanceState(
offset: result.size,
size: result.size,
corrupt: result.corrupt
@@ -478,7 +481,7 @@ actor WorkflowStatsService {
state.markPending(result.dateKey)
}
- try WorkflowStatsStorage.saveMaintenanceState(state)
+ try WorkflowStorage.saveMaintenanceState(state)
}
}
@@ -491,15 +494,15 @@ actor WorkflowStatsService {
}
private func markDirty(_ dateKey: String) {
- try? WorkflowStatsStorage.withExclusiveLock {
- var state = WorkflowStatsStorage.loadMaintenanceState()
+ try? WorkflowStorage.withExclusiveLock {
+ var state = WorkflowStorage.loadMaintenanceState()
state.markDirty(dateKey)
- try WorkflowStatsStorage.saveMaintenanceState(state)
+ try WorkflowStorage.saveMaintenanceState(state)
}
}
private func pruneExpiredEventFiles() throws {
- let cutoffDate = WorkflowStatsStorage.retentionCutoffDate()
+ let cutoffDate = WorkflowStorage.retentionCutoffDate()
let expiredDateKeys = eventDateKeys().filter { dateKey in
guard let date = CodexDateFormat.dayDate(from: dateKey) else {
return false
@@ -512,14 +515,14 @@ actor WorkflowStatsService {
return
}
- try WorkflowStatsStorage.withExclusiveLock {
- var state = WorkflowStatsStorage.loadMaintenanceState()
+ try WorkflowStorage.withExclusiveLock {
+ var state = WorkflowStorage.loadMaintenanceState()
for dateKey in expiredDateKeys {
try? FileManager.default.removeItem(at: eventLogURL(for: dateKey))
state.remove(dateKey)
}
- try WorkflowStatsStorage.saveMaintenanceState(state)
+ try WorkflowStorage.saveMaintenanceState(state)
}
}
@@ -528,12 +531,12 @@ actor WorkflowStatsService {
return true
}
- return date >= WorkflowStatsStorage.identifierRetentionCutoffDate()
+ return date >= WorkflowStorage.identifierRetentionCutoffDate()
}
}
/// Hook 统计文件路径, 保留期和跨进程 flock 都集中在这里
-nonisolated enum WorkflowStatsStorage {
+nonisolated enum WorkflowStorage {
private static let retentionDayCount = 210
private static let identifierRetentionDayCount = 3
@@ -562,9 +565,22 @@ nonisolated enum WorkflowStatsStorage {
.appendingPathComponent("maintenance.json", isDirectory: false)
}
- static func iCloudSyncDirectoryURL() -> URL {
- directoryURL()
- .appendingPathComponent("iCloudSync", isDirectory: true)
+ static func syncDirectoryURL() -> URL {
+ let currentURL = directoryURL()
+ .appendingPathComponent("Sync", isDirectory: true)
+ let legacyURL = directoryURL()
+ .appendingPathComponent(legacySyncDirectoryName, isDirectory: true)
+
+ if FileManager.default.fileExists(atPath: legacyURL.path),
+ !FileManager.default.fileExists(atPath: currentURL.path) {
+ return legacyURL
+ }
+
+ return currentURL
+ }
+
+ private static var legacySyncDirectoryName: String {
+ ["i", "Cloud", "Sync"].joined()
}
static func directoryURL() -> URL {
@@ -608,17 +624,17 @@ nonisolated enum WorkflowStatsStorage {
return try work()
}
- static func loadMaintenanceState() -> WorkflowStatsMaintenanceState {
+ static func loadMaintenanceState() -> WorkflowMaintenanceState {
let url = maintenanceURL()
guard let data = try? Data(contentsOf: url), !data.isEmpty,
- let state = try? JSONDecoder().decode(WorkflowStatsMaintenanceState.self, from: data) else {
- return WorkflowStatsMaintenanceState()
+ let state = try? JSONDecoder().decode(WorkflowMaintenanceState.self, from: data) else {
+ return WorkflowMaintenanceState()
}
return state
}
- static func saveMaintenanceState(_ state: WorkflowStatsMaintenanceState) throws {
+ static func saveMaintenanceState(_ state: WorkflowMaintenanceState) throws {
try FileManager.default.createDirectory(
at: directoryURL(),
withIntermediateDirectories: true
@@ -666,7 +682,7 @@ nonisolated enum WorkflowStatsStorage {
}
/// 记录单日事件文件已处理到的 offset, 支持后续增量维护
-nonisolated struct WorkflowStatsDayMaintenanceState: Codable, Equatable {
+nonisolated struct WorkflowDayMaintenanceState: Codable, Equatable {
var offset: UInt64
var size: UInt64
var corrupt: Int
@@ -679,19 +695,19 @@ nonisolated struct WorkflowStatsDayMaintenanceState: Codable, Equatable {
}
/// maintenance.json 的全局状态, pending 表示可增量, dirty 表示需全量重建
-nonisolated struct WorkflowStatsMaintenanceState: Codable, Equatable {
+nonisolated struct WorkflowMaintenanceState: Codable, Equatable {
static let currentSchema = 2
var schema: Int
var pending: [String]
var dirty: [String]
- var days: [String: WorkflowStatsDayMaintenanceState]
+ var days: [String: WorkflowDayMaintenanceState]
init(
schema: Int = Self.currentSchema,
pending: [String] = [],
dirty: [String] = [],
- days: [String: WorkflowStatsDayMaintenanceState] = [:]
+ days: [String: WorkflowDayMaintenanceState] = [:]
) {
self.schema = schema
self.pending = Self.normalizedDates(pending)
@@ -704,7 +720,7 @@ nonisolated struct WorkflowStatsMaintenanceState: Codable, Equatable {
schema = try container.decodeIfPresent(Int.self, forKey: .schema) ?? Self.currentSchema
pending = try Self.normalizedDates(container.decodeIfPresent([String].self, forKey: .pending) ?? [])
dirty = try Self.normalizedDates(container.decodeIfPresent([String].self, forKey: .dirty) ?? [])
- days = try container.decodeIfPresent([String: WorkflowStatsDayMaintenanceState].self, forKey: .days) ?? [:]
+ days = try container.decodeIfPresent([String: WorkflowDayMaintenanceState].self, forKey: .days) ?? [:]
}
mutating func markPending(_ dateKey: String) {
@@ -738,14 +754,14 @@ nonisolated struct WorkflowStatsMaintenanceState: Codable, Equatable {
pending = Self.normalizedDates(pending)
dirty = Self.normalizedDates(dirty)
- days = days.filter { WorkflowStatsStorage.isValidDateKey($0.key) }
+ days = days.filter { WorkflowStorage.isValidDateKey($0.key) }
return previousPending != pending || previousDirty != dirty || previousDays != days
}
private mutating func ensureDayState(for dateKey: String) {
if days[dateKey] == nil {
- days[dateKey] = WorkflowStatsDayMaintenanceState()
+ days[dateKey] = WorkflowDayMaintenanceState()
}
}
@@ -754,12 +770,12 @@ nonisolated struct WorkflowStatsMaintenanceState: Codable, Equatable {
}
private static func normalizedDates(_ dates: [String]) -> [String] {
- Array(Set(dates.filter { WorkflowStatsStorage.isValidDateKey($0) })).sorted()
+ Array(Set(dates.filter { WorkflowStorage.isValidDateKey($0) })).sorted()
}
}
// 单次维护任务: 从 startOffset 读到 size, 可基于已有聚合继续追加
-private nonisolated struct WorkflowStatsMaintenanceTask {
+private nonisolated struct WorkflowMaintenanceTask {
let dateKey: String
let startOffset: UInt64
let size: UInt64
@@ -768,26 +784,26 @@ private nonisolated struct WorkflowStatsMaintenanceTask {
}
/// 维护任务的提交结果, corrupt 统计保留给后续诊断
-private nonisolated struct WorkflowStatsMaintenanceResult {
+private nonisolated struct WorkflowMaintenanceResult {
let dateKey: String
let aggregate: WorkflowDailyAggregate
let size: UInt64
let corrupt: Int
}
-/// UI 层的工作流统计状态, 节流普通刷新但允许维护刷新立即执行
+/// UI 层的工作流状态, 节流普通刷新, 维护刷新由上层调度器合并
@MainActor
-final class WorkflowStatsViewModel: ObservableObject {
- @Published private(set) var snapshot = WorkflowStatsSnapshot.empty
+final class WorkflowViewModel: ObservableObject {
+ @Published private(set) var snapshot = WorkflowSnapshot.empty
private static let minimumRefreshInterval: TimeInterval = 5
- private let service: WorkflowStatsService
+ private let service: WorkflowService
private var isRefreshing = false
private let refreshCoordinator = RefreshTaskCoordinator()
private var lastRefreshedAt: Date?
- init(service: WorkflowStatsService = WorkflowStatsService()) {
+ init(service: WorkflowService = WorkflowService()) {
self.service = service
}
@@ -795,16 +811,16 @@ final class WorkflowStatsViewModel: ObservableObject {
refreshCoordinator.cancel()
}
- func refreshIfNeeded(performMaintenance: Bool = false) {
- guard performMaintenance || Date().timeIntervalSince(lastRefreshedAt ?? .distantPast) > Self.minimumRefreshInterval else {
+ func refreshIfNeeded() {
+ guard Date().timeIntervalSince(lastRefreshedAt ?? .distantPast) > Self.minimumRefreshInterval else {
return
}
- refresh(performMaintenance: performMaintenance)
+ refresh()
}
- func refresh(performMaintenance: Bool = false) {
- if isRefreshing, !performMaintenance {
+ func refresh() {
+ if isRefreshing {
return
}
@@ -821,7 +837,7 @@ final class WorkflowStatsViewModel: ObservableObject {
}
}
- let snapshot = await service.loadSnapshot(performMaintenance: performMaintenance)
+ let snapshot = await service.loadSnapshot()
guard refreshCoordinator.canCommit(generation) else {
return
@@ -831,4 +847,21 @@ final class WorkflowStatsViewModel: ObservableObject {
lastRefreshedAt = Date()
}
}
+
+ /// 由 WorkflowSyncScheduler 串行调度, 无需自行判断并发, 只执行一次明确的维护刷新
+ func refreshMaintenance(synchronize: Bool) async {
+ refreshCoordinator.cancel()
+ isRefreshing = true
+ defer {
+ isRefreshing = false
+ }
+
+ let snapshot = await service.loadSnapshot(
+ performMaintenance: true,
+ synchronize: synchronize
+ )
+
+ self.snapshot = snapshot
+ lastRefreshedAt = Date()
+ }
}
diff --git a/CodexBar/Services/Workflow/WorkflowSyncScheduler.swift b/CodexBar/Services/Workflow/WorkflowSyncScheduler.swift
new file mode 100644
index 0000000..713ea7b
--- /dev/null
+++ b/CodexBar/Services/Workflow/WorkflowSyncScheduler.swift
@@ -0,0 +1,154 @@
+import Foundation
+
+/// 合并工作流维护刷新中的同步请求, 避免频繁开关产生重复同步
+@MainActor
+final class WorkflowSyncScheduler {
+ private static let syncCooldown: TimeInterval = 8
+
+ private let viewModel: WorkflowViewModel
+ private let canSynchronize: () -> Bool
+ private var isRunning = false
+ private var pendingSync = false
+ private var pendingLocalMaintenance = false
+ private var cooldownTask: Task<Void, Never>?
+ private var lastSyncFinishedAt: Date?
+
+ init(
+ viewModel: WorkflowViewModel,
+ canSynchronize: @escaping () -> Bool
+ ) {
+ self.viewModel = viewModel
+ self.canSynchronize = canSynchronize
+ }
+
+ deinit {
+ cooldownTask?.cancel()
+ }
+
+ func requestMaintenance(allowsSync: Bool) {
+ if allowsSync, canSynchronize() {
+ pendingSync = true
+ } else {
+ pendingLocalMaintenance = true
+ }
+
+ drain()
+ }
+
+ func requestSync() {
+ guard canSynchronize() else {
+ clearPendingSync()
+ return
+ }
+
+ pendingSync = true
+ drain()
+ }
+
+ func clearPendingSync() {
+ pendingSync = false
+ cancelCooldownTask()
+ drain()
+ }
+
+ func clearPendingMaintenance() {
+ pendingSync = false
+ pendingLocalMaintenance = false
+ cancelCooldownTask()
+ }
+
+ func cancel() {
+ clearPendingMaintenance()
+ }
+
+ private func drain() {
+ guard !isRunning else {
+ return
+ }
+
+ let canSync = pendingSync && canSynchronize()
+ if canSync {
+ if remainingSyncCooldown() <= 0 {
+ startMaintenance(synchronize: true)
+ return
+ }
+ } else {
+ pendingSync = false
+ cancelCooldownTask()
+ }
+
+ if pendingLocalMaintenance {
+ startMaintenance(synchronize: false)
+ return
+ }
+
+ if canSync {
+ scheduleCooldownDrain(after: remainingSyncCooldown())
+ }
+ }
+
+ private func startMaintenance(synchronize: Bool) {
+ isRunning = true
+ pendingLocalMaintenance = false
+
+ if synchronize {
+ pendingSync = false
+ cancelCooldownTask()
+ }
+
+ Task { @MainActor [weak self] in
+ guard let self else {
+ return
+ }
+
+ await viewModel.refreshMaintenance(synchronize: synchronize)
+ finishMaintenance(synchronize: synchronize)
+ }
+ }
+
+ private func finishMaintenance(synchronize: Bool) {
+ isRunning = false
+
+ if synchronize {
+ lastSyncFinishedAt = Date()
+ }
+
+ if !canSynchronize() {
+ pendingSync = false
+ cancelCooldownTask()
+ }
+
+ drain()
+ }
+
+ private func remainingSyncCooldown() -> TimeInterval {
+ guard let lastSyncFinishedAt else {
+ return 0
+ }
+
+ let elapsed = Date().timeIntervalSince(lastSyncFinishedAt)
+ return max(0, Self.syncCooldown - elapsed)
+ }
+
+ private func scheduleCooldownDrain(after delay: TimeInterval) {
+ guard cooldownTask == nil else {
+ return
+ }
+
+ let milliseconds = max(1, Int((delay * 1000).rounded(.up)))
+ cooldownTask = Task { @MainActor [weak self] in
+ try? await Task.sleep(for: .milliseconds(milliseconds))
+ guard let self, !Task.isCancelled else {
+ return
+ }
+
+ cooldownTask = nil
+ drain()
+ }
+ }
+
+ private func cancelCooldownTask() {
+ cooldownTask?.cancel()
+ cooldownTask = nil
+ }
+}
diff --git a/CodexBar/Services/WorkflowStats/WorkflowSyncService.swift b/CodexBar/Services/Workflow/WorkflowSyncService.swift
similarity index 85%
rename from CodexBar/Services/WorkflowStats/WorkflowSyncService.swift
rename to CodexBar/Services/Workflow/WorkflowSyncService.swift
index daa5f5c..78ce889 100644
--- a/CodexBar/Services/WorkflowStats/WorkflowSyncService.swift
+++ b/CodexBar/Services/Workflow/WorkflowSyncService.swift
@@ -13,7 +13,7 @@ actor WorkflowSyncService {
init(
container: CKContainer = .default(),
fileManager: FileManager = .default,
- directoryURL: URL = WorkflowStatsStorage.iCloudSyncDirectoryURL()
+ directoryURL: URL = WorkflowStorage.syncDirectoryURL()
) {
database = container.privateCloudDatabase
self.fileManager = fileManager
@@ -37,9 +37,14 @@ actor WorkflowSyncService {
return .disabled
}
- Self.postSyncNotification(.workflowStatsICloudSyncDidStart)
+ var didSucceed = false
+ var failureMessage: String?
+ Self.postSyncDidStart()
defer {
- Self.postSyncNotification(.workflowStatsICloudSyncDidFinish)
+ Self.postSyncDidFinish(
+ didSucceed: didSucceed,
+ failureMessage: failureMessage
+ )
}
var state = loadState()
@@ -49,7 +54,7 @@ actor WorkflowSyncService {
let deviceId = try await resolveCurrentDeviceId()
resetStateIfDeviceChanged(deviceId, state: &state)
- let localByDate = Self.cloudAggregatesByDate(localAggregates)
+ let localByDate = Self.syncedAggregatesByDate(localAggregates)
let forceBackfill = WorkflowSyncSettings.needsBackfill()
try await uploadChangedAggregates(
localByDate: localByDate,
@@ -62,10 +67,12 @@ actor WorkflowSyncService {
WorkflowSyncSettings.clearBackfillRequest()
}
- try await refreshCacheFromCloud(currentDeviceId: deviceId)
+ try await refreshCacheFromRemote(currentDeviceId: deviceId)
try await pruneCurrentDeviceRecordsIfNeeded(deviceId: deviceId, state: &state)
try saveState(state)
+ didSucceed = true
} catch {
+ failureMessage = WorkflowSyncFailureReason.classify(error).message
try? saveState(state)
}
@@ -86,16 +93,16 @@ actor WorkflowSyncService {
try? fileManager.removeItem(at: cursorURL)
}
- private static func cloudAggregatesByDate(
+ private static func syncedAggregatesByDate(
_ aggregates: [WorkflowDailyAggregate]
- ) -> [String: WorkflowCloudDailyAggregate] {
- aggregates.reduce(into: [String: WorkflowCloudDailyAggregate]()) { result, aggregate in
- result[aggregate.date] = aggregate.cloudAggregate
+ ) -> [String: WorkflowSyncedDailyAggregate] {
+ aggregates.reduce(into: [String: WorkflowSyncedDailyAggregate]()) { result, aggregate in
+ result[aggregate.date] = aggregate.syncedAggregate
}
}
private func backfillCompleted(
- localByDate: [String: WorkflowCloudDailyAggregate],
+ localByDate: [String: WorkflowSyncedDailyAggregate],
state: WorkflowSyncState
) -> Bool {
localByDate.allSatisfy { date, aggregate in
@@ -114,12 +121,12 @@ actor WorkflowSyncService {
}
private extension WorkflowSyncService {
- typealias PendingUpload = (date: String, aggregate: WorkflowCloudDailyAggregate, hash: String)
+ typealias PendingUpload = (date: String, aggregate: WorkflowSyncedDailyAggregate, hash: String)
typealias PendingRecord = (upload: PendingUpload, recordID: CKRecord.ID)
typealias UploadedHash = (date: String, hash: String)
enum Metrics {
- static let cloudSchemaVersion = 1
+ static let syncSchemaVersion = 1
static let syncZoneName = "CodexBarZone"
static let saltByteCount = 32
static let recordFetchLimit = 200
@@ -177,7 +184,7 @@ private extension WorkflowSyncService {
}
func uploadChangedAggregates(
- localByDate: [String: WorkflowCloudDailyAggregate],
+ localByDate: [String: WorkflowSyncedDailyAggregate],
changedDates: Set<String>,
forceBackfill: Bool,
state: inout WorkflowSyncState
@@ -209,20 +216,14 @@ private extension WorkflowSyncService {
let batchEnd = min(batchStart + Metrics.uploadBatchSize, pendingUploads.count)
let batch = Array(pendingUploads[batchStart ..< batchEnd])
- let uploadedBatch: [UploadedHash]
-
- do {
- uploadedBatch = try await uploadAggregateBatch(batch, deviceId: deviceId)
- } catch {
- break
- }
+ let uploadedBatch = try await uploadAggregateBatch(batch, deviceId: deviceId)
try applyUploadedHashes(uploadedBatch, to: &state)
}
}
func uploadCandidateDates(
- localByDate: [String: WorkflowCloudDailyAggregate],
+ localByDate: [String: WorkflowSyncedDailyAggregate],
changedDates: Set<String>,
forceBackfill: Bool,
state: WorkflowSyncState
@@ -255,7 +256,7 @@ private extension WorkflowSyncService {
func makePendingUploads(
for candidateDates: Set<String>,
- localByDate: [String: WorkflowCloudDailyAggregate],
+ localByDate: [String: WorkflowSyncedDailyAggregate],
state: WorkflowSyncState
) throws -> [PendingUpload] {
try candidateDates.compactMap { date in
@@ -314,9 +315,9 @@ private extension WorkflowSyncService {
}
}
- func refreshCacheFromCloud(currentDeviceId: String) async throws {
+ func refreshCacheFromRemote(currentDeviceId: String) async throws {
guard let token = try loadCursor() else {
- try await rebuildCacheFromCloud(currentDeviceId: currentDeviceId)
+ try await rebuildCacheFromRemote(currentDeviceId: currentDeviceId)
return
}
@@ -327,13 +328,13 @@ private extension WorkflowSyncService {
currentDeviceId: currentDeviceId
)
} catch {
- try await rebuildCacheFromCloud(currentDeviceId: currentDeviceId)
+ try await rebuildCacheFromRemote(currentDeviceId: currentDeviceId)
}
}
func applyZoneChangesToCache(
since initialToken: CKServerChangeToken?,
- cachedRecords: [WorkflowCloudDailyRecord],
+ cachedRecords: [WorkflowSyncedDailyRecord],
currentDeviceId: String
) async throws {
var cacheByID = Self.recordsByID(
@@ -375,15 +376,15 @@ private extension WorkflowSyncService {
}
}
- func rebuildCacheFromCloud(currentDeviceId: String) async throws {
- let cloudRecords = try await fetchAllCloudDailyRecords()
- let retainedRecords = Self.filteredRetained(records: cloudRecords, excluding: currentDeviceId)
+ func rebuildCacheFromRemote(currentDeviceId: String) async throws {
+ let syncedRecords = try await fetchAllRemoteDailyRecords()
+ let retainedRecords = Self.filteredRetained(records: syncedRecords, excluding: currentDeviceId)
try saveCachedRecords(retainedRecords)
await establishCursorBaseline(cachedRecords: retainedRecords, currentDeviceId: currentDeviceId)
}
- func fetchAllCloudDailyRecords() async throws -> [WorkflowCloudDailyRecord] {
- var records = [WorkflowCloudDailyRecord]()
+ func fetchAllRemoteDailyRecords() async throws -> [WorkflowSyncedDailyRecord] {
+ var records = [WorkflowSyncedDailyRecord]()
var queryCursor: CKQueryOperation.Cursor?
let query = CKQuery(
@@ -401,7 +402,7 @@ private extension WorkflowSyncService {
desiredKeys: nil,
resultsLimit: Metrics.queryFetchLimit
)
- records.append(contentsOf: Self.cloudDailyRecords(from: firstPage.matchResults))
+ records.append(contentsOf: Self.remoteDailyRecords(from: firstPage.matchResults))
queryCursor = firstPage.queryCursor
while let cursor = queryCursor {
@@ -410,7 +411,7 @@ private extension WorkflowSyncService {
desiredKeys: nil,
resultsLimit: Metrics.queryFetchLimit
)
- records.append(contentsOf: Self.cloudDailyRecords(from: page.matchResults))
+ records.append(contentsOf: Self.remoteDailyRecords(from: page.matchResults))
queryCursor = page.queryCursor
}
@@ -418,7 +419,7 @@ private extension WorkflowSyncService {
}
func establishCursorBaseline(
- cachedRecords: [WorkflowCloudDailyRecord],
+ cachedRecords: [WorkflowSyncedDailyRecord],
currentDeviceId: String
) async {
do {
@@ -435,11 +436,11 @@ private extension WorkflowSyncService {
func mergeChangedRecords(
_ modificationResults: Dictionary<CKRecord.ID, Result<CKDatabase.RecordZoneChange.Modification, Error>>.Values,
currentDeviceId: String,
- into cacheByID: inout [String: WorkflowCloudDailyRecord]
+ into cacheByID: inout [String: WorkflowSyncedDailyRecord]
) {
for modificationResult in modificationResults {
guard case let .success(modification) = modificationResult,
- let record = Self.cloudDailyRecord(from: modification.record) else {
+ let record = Self.remoteDailyRecord(from: modification.record) else {
continue
}
@@ -454,7 +455,7 @@ private extension WorkflowSyncService {
func removeDeletedRecords(
_ deletions: [CKDatabase.RecordZoneChange.Deletion],
- from cacheByID: inout [String: WorkflowCloudDailyRecord]
+ from cacheByID: inout [String: WorkflowSyncedDailyRecord]
) {
for deletion in deletions where deletion.recordType == RecordTypes.dailyAggregate {
if let cacheID = cacheID(fromRecordName: deletion.recordID.recordName) {
@@ -467,12 +468,12 @@ private extension WorkflowSyncService {
deviceId: String,
state: inout WorkflowSyncState
) async throws {
- let today = WorkflowStatsStorage.dateKey(for: Date())
+ let today = WorkflowStorage.dateKey(for: Date())
guard state.lastPrunedDate != today else {
return
}
- let cutoffKey = WorkflowStatsStorage.dateKey(for: WorkflowStatsStorage.retentionCutoffDate())
+ let cutoffKey = WorkflowStorage.dateKey(for: WorkflowStorage.retentionCutoffDate())
let expiredDates = state.hashByDate.keys
.filter { $0 < cutoffKey }
.sorted()
@@ -530,7 +531,7 @@ private extension WorkflowSyncService {
let salt = try Self.randomSalt()
let record = CKRecord(recordType: RecordTypes.metadata, recordID: recordID)
record[FieldKeys.salt] = salt as CKRecordValue
- record[FieldKeys.schemaVersion] = Metrics.cloudSchemaVersion as CKRecordValue
+ record[FieldKeys.schemaVersion] = Metrics.syncSchemaVersion as CKRecordValue
do {
let saveResult = try await database.modifyRecords(
@@ -574,11 +575,11 @@ private extension WorkflowSyncService {
}
func apply(
- _ aggregate: WorkflowCloudDailyAggregate,
+ _ aggregate: WorkflowSyncedDailyAggregate,
deviceId: String,
to record: CKRecord
) {
- record[FieldKeys.schemaVersion] = Metrics.cloudSchemaVersion as CKRecordValue
+ record[FieldKeys.schemaVersion] = Metrics.syncSchemaVersion as CKRecordValue
record[FieldKeys.deviceId] = deviceId as CKRecordValue
record[FieldKeys.date] = aggregate.date as CKRecordValue
record[FieldKeys.eventCount] = aggregate.eventCount as CKRecordValue
@@ -612,21 +613,58 @@ private extension WorkflowSyncService {
let deviceId = String(recordName[..<separatorIndex])
let date = String(recordName[recordName.index(after: separatorIndex)...])
- guard WorkflowStatsStorage.isValidDateKey(date), !deviceId.isEmpty else {
+ guard WorkflowStorage.isValidDateKey(date), !deviceId.isEmpty else {
return nil
}
- return WorkflowCloudDailyRecord.id(deviceId: deviceId, date: date)
+ return WorkflowSyncedDailyRecord.id(deviceId: deviceId, date: date)
}
- func hash(for aggregate: WorkflowCloudDailyAggregate) throws -> String {
+ func hash(for aggregate: WorkflowSyncedDailyAggregate) throws -> String {
let digest = try SHA256.hash(data: aggregate.jsonLineData())
return Self.hexString(Data(digest))
}
- nonisolated static func postSyncNotification(_ name: Notification.Name) {
+ nonisolated static func postSyncDidStart() {
+ postSyncNotification(.workflowSyncDidStart)
+ }
+
+ nonisolated static func postSyncDidFinish(
+ didSucceed: Bool,
+ failureMessage: String?
+ ) {
+ postSyncNotification(.workflowSyncDidFinish) {
+ finishNotificationUserInfo(
+ didSucceed: didSucceed,
+ failureMessage: failureMessage
+ )
+ }
+ }
+
+ @MainActor
+ static func finishNotificationUserInfo(
+ didSucceed: Bool,
+ failureMessage: String?
+ ) -> [String: Any] {
+ var userInfo: [String: Any] = [
+ WorkflowSyncNotificationKey.didSucceed: didSucceed
+ ]
+ if let failureMessage {
+ userInfo[WorkflowSyncNotificationKey.failureMessage] = failureMessage
+ }
+ return userInfo
+ }
+
+ nonisolated static func postSyncNotification(
+ _ name: Notification.Name,
+ userInfo: @escaping @MainActor () -> [String: Any]? = { nil }
+ ) {
Task { @MainActor in
- NotificationCenter.default.post(name: name, object: nil)
+ NotificationCenter.default.post(
+ name: name,
+ object: nil,
+ userInfo: userInfo()
+ )
}
}
}
@@ -651,7 +689,7 @@ private extension WorkflowSyncService {
try data.write(to: stateURL, options: .atomic)
}
- func loadCachedRecords() -> [WorkflowCloudDailyRecord] {
+ func loadCachedRecords() -> [WorkflowSyncedDailyRecord] {
guard let data = try? Data(contentsOf: cacheURL), !data.isEmpty else {
return []
}
@@ -659,7 +697,7 @@ private extension WorkflowSyncService {
return JSONLines.decode(from: data)
}
- func saveCachedRecords(_ records: [WorkflowCloudDailyRecord]) throws {
+ func saveCachedRecords(_ records: [WorkflowSyncedDailyRecord]) throws {
try fileManager.createDirectory(at: directoryURL, withIntermediateDirectories: true)
let encoder = JSONEncoder()
@@ -700,27 +738,27 @@ private extension WorkflowSyncService {
}
private extension WorkflowSyncService {
- static func cloudDailyRecords(
+ static func remoteDailyRecords(
from matchResults: [(CKRecord.ID, Result<CKRecord, Error>)]
- ) -> [WorkflowCloudDailyRecord] {
+ ) -> [WorkflowSyncedDailyRecord] {
matchResults.compactMap { _, result in
guard case let .success(record) = result else {
return nil
}
- return cloudDailyRecord(from: record)
+ return remoteDailyRecord(from: record)
}
}
- static func cloudDailyRecord(from record: CKRecord) -> WorkflowCloudDailyRecord? {
+ static func remoteDailyRecord(from record: CKRecord) -> WorkflowSyncedDailyRecord? {
guard record.recordType == RecordTypes.dailyAggregate,
let deviceId = record[FieldKeys.deviceId] as? String,
let date = record[FieldKeys.date] as? String,
- WorkflowStatsStorage.isValidDateKey(date) else {
+ WorkflowStorage.isValidDateKey(date) else {
return nil
}
- let aggregate = WorkflowCloudDailyAggregate(
+ let aggregate = WorkflowSyncedDailyAggregate(
date: date,
eventCount: intValue(record[FieldKeys.eventCount]),
sessionStartCount: intValue(record[FieldKeys.sessionStartCount]),
@@ -737,7 +775,7 @@ private extension WorkflowSyncService {
projectCounts: projectCounts(from: record[FieldKeys.projectCounts])
)
- return WorkflowCloudDailyRecord(
+ return WorkflowSyncedDailyRecord(
deviceId: deviceId,
daily: aggregate,
updatedAt: record[FieldKeys.updatedAt] as? Date ?? record.modificationDate
@@ -755,10 +793,10 @@ private extension WorkflowSyncService {
}
static func filteredRetained(
- records: [WorkflowCloudDailyRecord],
+ records: [WorkflowSyncedDailyRecord],
excluding currentDeviceId: String? = nil
- ) -> [WorkflowCloudDailyRecord] {
- let cutoffKey = WorkflowStatsStorage.dateKey(for: WorkflowStatsStorage.retentionCutoffDate())
+ ) -> [WorkflowSyncedDailyRecord] {
+ let cutoffKey = WorkflowStorage.dateKey(for: WorkflowStorage.retentionCutoffDate())
return records.filter { record in
guard record.date >= cutoffKey else {
return false
@@ -769,11 +807,11 @@ private extension WorkflowSyncService {
}
static func recordsByID(
- records: [WorkflowCloudDailyRecord],
+ records: [WorkflowSyncedDailyRecord],
excluding currentDeviceId: String? = nil
- ) -> [String: WorkflowCloudDailyRecord] {
+ ) -> [String: WorkflowSyncedDailyRecord] {
filteredRetained(records: records, excluding: currentDeviceId)
- .reduce(into: [String: WorkflowCloudDailyRecord]()) { result, record in
+ .reduce(into: [String: WorkflowSyncedDailyRecord]()) { result, record in
result[record.id] = record
}
}
@@ -858,7 +896,7 @@ private extension WorkflowSyncService {
nonisolated struct WorkflowSyncSnapshot: Equatable {
let currentDeviceId: String?
- let records: [WorkflowCloudDailyRecord]
+ let records: [WorkflowSyncedDailyRecord]
static let disabled = WorkflowSyncSnapshot(currentDeviceId: nil, records: [])
}
diff --git a/CodexBar/Views/Menu/CodexStatusMenuSections.swift b/CodexBar/Views/Menu/CodexStatusMenuSections.swift
index ea2461d..a47b2d2 100644
--- a/CodexBar/Views/Menu/CodexStatusMenuSections.swift
+++ b/CodexBar/Views/Menu/CodexStatusMenuSections.swift
@@ -176,6 +176,7 @@ struct UpdatedAtRow: View {
let countdownStartedAt: Date
let countdownInterval: TimeInterval
let isCountdownActive: Bool
+ let syncDisplayState: WorkflowSyncDisplayState
let updateMessage: String?
let startUpdate: () -> Void
@@ -211,8 +212,17 @@ struct UpdatedAtRow: View {
.transition(.opacity)
.onTapGesture(count: 2, perform: startUpdate)
}
+
+ Image(systemName: syncDisplayState.symbolName)
+ .font(.caption2)
+ .foregroundStyle(syncDisplayState.tint)
+ .frame(width: Metrics.syncIconWidth)
+ .contentTransition(.opacity)
+ .help(syncDisplayState.helpText)
+ .accessibilityLabel(Text(syncDisplayState.helpText))
}
.animation(Metrics.statusAnimation, value: updateMessage)
+ .animation(Metrics.statusAnimation, value: syncDisplayState)
}
private static let timeFormatter: DateFormatter = {
@@ -226,5 +236,60 @@ struct UpdatedAtRow: View {
private enum Metrics {
static let statusAnimation = Animation.codexStatus
+ static let syncIconWidth: CGFloat = 16
+ }
+}
+
+struct WorkflowSyncDisplayState: Equatable {
+ let symbolName: String
+ let tint: Color
+ let helpText: String
+
+ static func == (lhs: WorkflowSyncDisplayState, rhs: WorkflowSyncDisplayState) -> Bool {
+ lhs.symbolName == rhs.symbolName && lhs.helpText == rhs.helpText
+ }
+
+ init(settings: WorkflowSyncSettings) {
+ if !settings.isEnabled {
+ self = .disabled
+ } else if settings.isSyncing {
+ self = .syncing
+ } else if settings.hasSyncFailure {
+ self = .failed(message: settings.syncFailureMessage)
+ } else {
+ self = .enabled
+ }
+ }
+
+ private init(symbolName: String, tint: Color, helpText: String) {
+ self.symbolName = symbolName
+ self.tint = tint
+ self.helpText = helpText
+ }
+
+ private static let enabled = WorkflowSyncDisplayState(
+ symbolName: "icloud",
+ tint: .codexSecondaryLabel,
+ helpText: "同步已开启"
+ )
+
+ private static let disabled = WorkflowSyncDisplayState(
+ symbolName: "icloud.slash",
+ tint: .codexSecondaryLabel,
+ helpText: "同步未开启"
+ )
+
+ private static let syncing = WorkflowSyncDisplayState(
+ symbolName: "arrow.trianglehead.clockwise.icloud",
+ tint: .blue,
+ helpText: "正在同步"
+ )
+
+ private static func failed(message: String?) -> WorkflowSyncDisplayState {
+ WorkflowSyncDisplayState(
+ symbolName: "exclamationmark.icloud",
+ tint: .orange,
+ helpText: message ?? WorkflowSyncFailureReason.retryLater.message
+ )
}
}
diff --git a/CodexBar/Views/Menu/CodexStatusMenuView.swift b/CodexBar/Views/Menu/CodexStatusMenuView.swift
index 28542c0..a664f21 100644
--- a/CodexBar/Views/Menu/CodexStatusMenuView.swift
+++ b/CodexBar/Views/Menu/CodexStatusMenuView.swift
@@ -12,8 +12,9 @@ struct CodexStatusMenuView: View {
static let menuWidth: CGFloat = Metrics.padding * 2 + MenuMetrics.panelPadding * 2 + UsageHeatmap.Metrics.totalWidth
@ObservedObject var viewModel: CodexStatusViewModel
- @ObservedObject var workflowStatsViewModel: WorkflowStatsViewModel
+ @ObservedObject var workflowViewModel: WorkflowViewModel
@ObservedObject var codexHookSettings: CodexHookSettings
+ @ObservedObject var syncSettings: WorkflowSyncSettings
@ObservedObject var menuSurfaceVisibility: MenuSurfaceVisibilityState
let onUsageHeatmapHoverChange: (UsageHeatmapHoverContext?) -> Void
@EnvironmentObject private var appUpdater: AppUpdater
@@ -26,6 +27,9 @@ struct CodexStatusMenuView: View {
.liquidGlassSurface(cornerRadius: Metrics.surfaceCornerRadius, isOuterSurface: true)
.animation(Metrics.statusAnimation, value: viewModel.loadState)
.animation(Metrics.statusAnimation, value: codexHookSettings.isEnabled)
+ .animation(Metrics.statusAnimation, value: syncSettings.isEnabled)
+ .animation(Metrics.statusAnimation, value: syncSettings.isSyncing)
+ .animation(Metrics.statusAnimation, value: syncSettings.hasSyncFailure)
}
}
@@ -74,8 +78,8 @@ private extension CodexStatusMenuView {
if let usage = snapshot.usage {
UsageSummaryView(
usage: usage,
- workflowStats: workflowStatsViewModel.snapshot,
- showsWorkflowStats: codexHookSettings.isEnabled,
+ workflow: workflowViewModel.snapshot,
+ showsWorkflow: codexHookSettings.isEnabled,
isStale: snapshot.isUsageStale,
onHoverContextChange: onUsageHeatmapHoverChange
)
@@ -94,6 +98,7 @@ private extension CodexStatusMenuView {
countdownStartedAt: viewModel.autoRefreshCountdownStartedAt ?? snapshot.generatedAt,
countdownInterval: viewModel.autoRefreshInterval,
isCountdownActive: menuSurfaceVisibility.isVisible,
+ syncDisplayState: WorkflowSyncDisplayState(settings: syncSettings),
updateMessage: appUpdater.panelUpdateMessage,
startUpdate: appUpdater.startUpdate
)
diff --git a/CodexBar/Views/Menu/UsageHeatmap.swift b/CodexBar/Views/Menu/UsageHeatmap.swift
index 126beb3..2279e7a 100644
--- a/CodexBar/Views/Menu/UsageHeatmap.swift
+++ b/CodexBar/Views/Menu/UsageHeatmap.swift
@@ -5,7 +5,7 @@ import SwiftUI
/// hover 详情面板需要的完整上下文, 包括屏幕坐标和峰值 token
nonisolated struct UsageHeatmapHoverContext: Equatable {
let day: UsageHeatmapDay
- let showsWorkflowStats: Bool
+ let showsWorkflow: Bool
let anchorScreenFrame: CGRect?
let heatmapScreenFrame: CGRect?
let preferredSide: UsageHeatmapDetailSide
@@ -28,7 +28,7 @@ nonisolated struct UsageHeatmapSelection: Equatable {
struct UsageSummaryView: View {
let usage: CodexUsageSnapshot
let isStale: Bool
- let showsWorkflowStats: Bool
+ let showsWorkflow: Bool
let onHoverContextChange: (UsageHeatmapHoverContext?) -> Void
private let days: [UsageHeatmapDay?]
private let peakTokens: Int
@@ -37,20 +37,20 @@ struct UsageSummaryView: View {
init(
usage: CodexUsageSnapshot,
- workflowStats: WorkflowStatsSnapshot,
- showsWorkflowStats: Bool,
+ workflow: WorkflowSnapshot,
+ showsWorkflow: Bool,
isStale: Bool = false,
onHoverContextChange: @escaping (UsageHeatmapHoverContext?) -> Void = { _ in }
) {
self.usage = usage
self.isStale = isStale
- self.showsWorkflowStats = showsWorkflowStats
+ self.showsWorkflow = showsWorkflow
self.onHoverContextChange = onHoverContextChange
let days = UsageHeatmapDay.grid(
usage: usage,
- workflowStats: workflowStats,
- showsWorkflowStats: showsWorkflowStats,
+ workflow: workflow,
+ showsWorkflow: showsWorkflow,
columnCount: UsageHeatmap.Metrics.columnCount,
today: Date()
)
@@ -176,7 +176,7 @@ struct UsageSummaryView: View {
hoverSelection.map {
UsageHeatmapHoverContext(
day: $0.day,
- showsWorkflowStats: showsWorkflowStats,
+ showsWorkflow: showsWorkflow,
anchorScreenFrame: hoveredSquareScreenFrame(for: $0),
heatmapScreenFrame: heatmapGridScreenFrame,
preferredSide: UsageHeatmap.Metrics.preferredDetailSide(for: $0.column),
@@ -568,7 +568,7 @@ struct UsageHeatmapDayDetailView: View {
}
var body: some View {
- let panelSize = Self.panelSize(showsWorkflowStats: context.showsWorkflowStats)
+ let panelSize = Self.panelSize(showsWorkflow: context.showsWorkflow)
VStack(alignment: .leading, spacing: Metrics.sectionSpacing) {
detailContent
@@ -597,15 +597,15 @@ struct UsageHeatmapDayDetailView: View {
Metrics.cornerRadius
}
- static func panelSize(showsWorkflowStats: Bool) -> CGSize {
- showsWorkflowStats
+ static func panelSize(showsWorkflow: Bool) -> CGSize {
+ showsWorkflow
? CGSize(width: Metrics.workflowPanelWidth, height: Metrics.workflowPanelHeight)
: CGSize(width: Metrics.tokenPanelWidth, height: Metrics.tokenPanelHeight)
}
@ViewBuilder
private var detailContent: some View {
- if context.showsWorkflowStats {
+ if context.showsWorkflow {
workflowContent
} else {
tokenOnlyContent
@@ -711,12 +711,12 @@ struct UsageHeatmapDayDetailView: View {
private var workflowMetricRows: [WorkflowMetricRow] {
[
- WorkflowMetricRow(label: "会话总数", value: context.day.workflowStats.sessionCount, tint: .green),
- WorkflowMetricRow(label: "对话轮次", value: context.day.workflowStats.turnCount, tint: .teal),
- WorkflowMetricRow(label: "子智能体", value: context.day.workflowStats.subagentCount, tint: .indigo),
- WorkflowMetricRow(label: "工具调用", value: context.day.workflowStats.toolCallCount, tint: .orange),
- WorkflowMetricRow(label: "权限请求", value: context.day.workflowStats.permissionRequestCount, tint: .red),
- WorkflowMetricRow(label: "上下文压缩", value: context.day.workflowStats.contextCompactionCount, tint: .purple)
+ WorkflowMetricRow(label: "会话总数", value: context.day.workflow.sessionCount, tint: .green),
+ WorkflowMetricRow(label: "对话轮次", value: context.day.workflow.turnCount, tint: .teal),
+ WorkflowMetricRow(label: "子智能体", value: context.day.workflow.subagentCount, tint: .indigo),
+ WorkflowMetricRow(label: "工具调用", value: context.day.workflow.toolCallCount, tint: .orange),
+ WorkflowMetricRow(label: "权限请求", value: context.day.workflow.permissionRequestCount, tint: .red),
+ WorkflowMetricRow(label: "上下文压缩", value: context.day.workflow.contextCompactionCount, tint: .purple)
]
}
diff --git a/CodexBar/Views/Settings/AppSettingsView.swift b/CodexBar/Views/Settings/AppSettingsView.swift
index 3f7fff7..b505204 100644
--- a/CodexBar/Views/Settings/AppSettingsView.swift
+++ b/CodexBar/Views/Settings/AppSettingsView.swift
@@ -8,9 +8,9 @@ struct AppSettingsView: View {
@StateObject private var loginItemSettings = LoginItemSettings()
@StateObject private var codexVersions = CodexCLIVersionViewModel()
@ObservedObject var codexHookSettings: CodexHookSettings
- @ObservedObject var cloudSyncSettings: WorkflowSyncSettings
+ @ObservedObject var syncSettings: WorkflowSyncSettings
@ObservedObject var globalHotKeySettings: GlobalHotKeySettings
- let onICloudSyncChanged: () -> Void
+ let onSyncChanged: (Bool) -> Void
var body: some View {
VStack(alignment: .leading, spacing: Metrics.sectionSpacing) {
@@ -21,7 +21,7 @@ struct AppSettingsView: View {
LiquidGlassDivider()
codexHookRow
LiquidGlassDivider()
- iCloudSyncRow
+ syncRow
LiquidGlassDivider()
hotKeyRow
LiquidGlassDivider()
@@ -42,14 +42,6 @@ struct AppSettingsView: View {
.padding(Metrics.panelPadding)
.liquidGlassSurface(cornerRadius: Metrics.panelCornerRadius)
}
- .animation(Metrics.statusAnimation, value: loginItemSettings.errorMessage)
- .animation(Metrics.statusAnimation, value: codexHookSettings.errorMessage)
- .animation(Metrics.statusAnimation, value: codexHookSettings.isUpdating)
- .animation(Metrics.statusAnimation, value: codexHookSettings.isEnabled)
- .animation(Metrics.statusAnimation, value: cloudSyncSettings.isEnabled)
- .animation(Metrics.statusAnimation, value: cloudSyncSettings.isSyncing)
- .animation(Metrics.statusAnimation, value: cloudSyncSettings.iCloudAvailability)
- .animation(Metrics.statusAnimation, value: cloudSyncSettings.lastUploadAt)
.padding(Metrics.padding)
.frame(width: Metrics.windowWidth)
.liquidGlassSurface(
@@ -63,13 +55,13 @@ struct AppSettingsView: View {
)
.onAppear {
loginItemSettings.refresh()
- cloudSyncSettings.refresh()
+ syncSettings.refresh()
appUpdater.refreshAutomaticCheckSetting()
refreshCodexVersionSection()
}
.onReceive(NotificationCenter.default.publisher(for: NSApplication.didBecomeActiveNotification)) { _ in
codexHookSettings.refresh()
- cloudSyncSettings.refresh()
+ syncSettings.refresh()
codexHookSettings.verifyInstalledHooks()
refreshCodexVersionSection()
}
@@ -130,14 +122,13 @@ private extension AppSettingsView {
if let message = codexHookSettings.errorMessage {
SettingsCaptionMessageRow(message: message)
- .transition(.opacity)
}
}
}
- var iCloudSyncRow: some View {
- let state = iCloudSyncRowState
- let lastUploadAtText = cloudSyncSettings.lastUploadAtText
+ var syncRow: some View {
+ let state = syncRowState
+ let lastUploadAtText = syncSettings.lastUploadAtText
return VStack(alignment: .leading, spacing: 4) {
SettingsToggleRow(
@@ -146,19 +137,20 @@ private extension AppSettingsView {
isOn: Binding(
get: { state.isActive },
set: { enabled in
- guard codexHookSettings.isEnabled, state.isICloudAvailable else {
+ guard codexHookSettings.isEnabled, state.isSyncAvailable else {
return
}
- cloudSyncSettings.setEnabled(enabled)
- onICloudSyncChanged()
+ guard syncSettings.setEnabled(enabled) else {
+ return
+ }
+ onSyncChanged(enabled)
}
),
isEnabled: state.canToggle
)
- if let message = cloudSyncSettings.unavailableMessage {
+ if let message = syncSettings.unavailableMessage {
SettingsCaptionMessageRow(message: message)
- .transition(.opacity)
} else if state.shouldShowUploadStatus(lastUploadAtText: lastUploadAtText) {
SettingsIndentedRow {
Text("最近上传")
@@ -167,7 +159,7 @@ private extension AppSettingsView {
Spacer(minLength: 8)
- if cloudSyncSettings.isSyncing {
+ if syncSettings.isSyncing {
ProgressView()
.controlSize(.small)
.scaleEffect(0.7)
@@ -178,21 +170,19 @@ private extension AppSettingsView {
.font(.caption.monospacedDigit())
.foregroundStyle(.secondary)
.lineLimit(1)
- .contentTransition(.opacity)
}
}
- .transition(.opacity)
}
}
}
- var iCloudSyncRowState: ICloudSyncRowState {
- ICloudSyncRowState(
+ var syncRowState: SyncRowState {
+ SyncRowState(
isHookEnabled: codexHookSettings.isEnabled,
isHookUpdating: codexHookSettings.isUpdating,
- isSyncEnabled: cloudSyncSettings.isEnabled,
- isICloudAvailable: cloudSyncSettings.isICloudAvailable,
- isSyncing: cloudSyncSettings.isSyncing
+ isSyncEnabled: syncSettings.isEnabled,
+ isSyncAvailable: syncSettings.isSyncAvailable,
+ isSyncing: syncSettings.isSyncing
)
}
@@ -263,7 +253,6 @@ private extension AppSettingsView {
.frame(maxWidth: .infinity, alignment: .leading)
.padding(Metrics.panelPadding)
.liquidGlassSurface(cornerRadius: Metrics.panelCornerRadius)
- .transition(.opacity)
}
}
@@ -290,19 +279,19 @@ private extension AppSettingsView {
}
}
-private struct ICloudSyncRowState {
+private struct SyncRowState {
let isHookEnabled: Bool
let isHookUpdating: Bool
let isSyncEnabled: Bool
- let isICloudAvailable: Bool
+ let isSyncAvailable: Bool
let isSyncing: Bool
var isActive: Bool {
- isHookEnabled && isSyncEnabled && isICloudAvailable
+ isHookEnabled && isSyncEnabled && isSyncAvailable
}
var canToggle: Bool {
- isHookEnabled && !isHookUpdating && isICloudAvailable
+ isHookEnabled && !isHookUpdating && isSyncAvailable
}
func shouldShowUploadStatus(lastUploadAtText: String?) -> Bool {
diff --git a/Docs/CodexHook.md b/Docs/CodexHook.md
index a8d9d0c..dd3cff3 100644
--- a/Docs/CodexHook.md
+++ b/Docs/CodexHook.md
@@ -123,7 +123,7 @@ Hook 数据目录:
`pending` 表示有新增事件等待整理的日期;`dirty` 表示需要从头重建 `daily.jsonl` 对应日期的日期;`offset` 是当天 events 文件已经处理到的字节位置;`size` 是上次处理完成时当天 events 文件大小;`corrupt` 是当天解析失败的 JSONL 行数。
-`WorkflowStatsStorage` 定义这些路径和保留策略。UI 读取时优先加载 `daily.jsonl`;原始事件文件不再作为 UI 临时快照回退源。
+`WorkflowStorage` 定义这些路径和保留策略。UI 读取时优先加载 `daily.jsonl`;原始事件文件不再作为 UI 临时快照回退源。
旧版单文件 `HookEvents/events.jsonl` 不参与新版统计、迁移或清理。
@@ -137,7 +137,7 @@ Hook 可能由多个 Codex 进程并发触发。`WorkflowHookEventRecorder` 会
Hook 写入路径不更新 `daily.jsonl`,也不执行重建或清理旧文件,避免在 Hook timeout 内持锁执行重活。
-`WorkflowStatsService` 是 actor,只在现有自动刷新或手动刷新触发工作流统计刷新时检查 `maintenance.json`。打开菜单面板时只读取现有 `daily.jsonl`。如果没有 `pending` 或 `dirty`,服务不会执行维护。
+`WorkflowService` 是 actor,只在现有自动刷新或手动刷新触发工作流统计刷新时检查 `maintenance.json`。打开菜单面板时只读取现有 `daily.jsonl`。如果没有 `pending` 或 `dirty`,服务不会执行维护。
维护时优先处理 `dirty`,从对应日期文件第一行开始流式重建当天聚合;再处理 `pending`,从 `days[date].offset` 开始流式读取新增事件并合并到已有当天聚合。每条坏行会被跳过并计入 `days[date].corrupt`。处理完成后先在 `stats.lock` 外原子写回 `daily.jsonl`,再短暂持有 `stats.lock` 更新 `maintenance.json`,避免主 App 写 daily 时阻塞 Hook 追加事件。
@@ -149,11 +149,11 @@ CodexBar 最多保留最近 210 天数据。
如果 `daily.jsonl` 缺失、为空、解析失败、缺少对应日期摘要,或者某天 events 文件状态和 `maintenance.json` 不一致,主 App 会把对应日期加入 `dirty` 并在刷新维护时按天重建。
-## iCloud 同步
+## 跨设备同步
完整链路见 [CrossDeviceSync.md](CrossDeviceSync.md)。本节只保留和 Hook 统计直接相关的同步摘要。
-设置页「跨设备同步」由 `WorkflowSyncSettings` 管理。该开关只有在 Codex Hook 开启且 `CKContainer.default().accountStatus` 为 `available` 时可操作;iCloud 不可用时开关禁用,并在开关下方显示「iCloud 不可用」。关闭 Hook 后不会继续触发工作流统计同步。iCloud 同步使用 CloudKit private database,数据归属当前登录的 iCloud 账号,不跨 iCloud 账号迁移或合并。CodexBar 自己创建和维护的记录都保存在 custom zone `CodexBarZone`,不会写入 `_defaultZone`。
+设置页「跨设备同步」由 `WorkflowSyncSettings` 管理。该开关只有在 Codex Hook 开启且 `CKContainer.default().accountStatus` 为 `available` 时可操作;账号不可用时开关禁用,并在开关下方显示「同步不可用」。关闭 Hook 后不会继续触发工作流统计同步。同步使用 CloudKit private database,数据归属当前登录的 iCloud 账号,不跨 iCloud 账号迁移或合并。CodexBar 自己创建和维护的记录都保存在 custom zone `CodexBarZone`,不会写入 `_defaultZone`。
CloudKit 中每个 iCloud 账号会保存一条账号级 salt:
@@ -172,7 +172,7 @@ deviceId = HMAC_SHA256(accountSalt, IOPlatformUUID)
CodexBar 不上传原始 `IOPlatformUUID`。同一台 Mac 在同一 iCloud 账号下重装 App 或系统后通常得到同一个 `deviceId`;切换 iCloud 账号后会进入另一个 CloudKit private database,并用该账号的 salt 派生另一个 `deviceId`。
-iCloud 同步上传的是 `daily.jsonl` 单日聚合行的内存副本,去掉:
+跨设备同步上传的是 `daily.jsonl` 单日聚合行的内存副本,去掉:
```text
sessionIds, turnIds
@@ -192,29 +192,33 @@ Hook 子进程不访问网络。主 App 在工作流统计维护刷新后对本
上传按日期稳定排序并分批执行。每轮同步最多处理 20 秒,每批最多 25 天;每批成功后立即把对应日期的 hash 和 `lastUploadAt` 写入 `state.json`。如果时间预算用完、任务被取消或本批 CloudKit 请求失败,本轮停止,剩余日期留给后续每分钟刷新继续。首次开启同步时设置 `needsBackfill`,只有本地所有日期的 hash 都已与 state 匹配后才清除 backfill 请求。
-本地 iCloud 同步状态保存在:
+本地同步状态保存在:
```text
-~/Library/Application Support/CodexBar/HookEvents/iCloudSync/state.json
-~/Library/Application Support/CodexBar/HookEvents/iCloudSync/cache.jsonl
-~/Library/Application Support/CodexBar/HookEvents/iCloudSync/cursor.data
+~/Library/Application Support/CodexBar/HookEvents/Sync/state.json
+~/Library/Application Support/CodexBar/HookEvents/Sync/cache.jsonl
+~/Library/Application Support/CodexBar/HookEvents/Sync/cursor.data
```
- `state.json`: 保存 `deviceId`、按日期记录的 `hashByDate`、`lastUploadAt` 和 `lastPrunedDate`。
- `cache.jsonl`: 保存从 iCloud 拉到的其他设备脱敏 daily 记录,一行一条;不保存当前设备自己的云端副本。
- `cursor.data`: 保存 CloudKit custom zone `CodexBarZone` 的 `CKServerChangeToken`,用于下次只拉取增量变化;没有游标时会 query 全量 `CodexBarDailyAggregate` 重建 `cache.jsonl`,随后建立新的游标基线;游标失效或增量拉取失败时会重新全量重建。
-接收 iCloud 变化时只更新 `cache.jsonl` 和 `cursor.data`,不直接发布新的 `WorkflowStatsSnapshot`,也不让面板立即跳数。缓存和游标按「先写 `cache.jsonl`,再写 `cursor.data`」提交;如果缓存写入失败,游标不会提前推进,下一轮会重新拉取同一批变化或全量回填。面板仍只在现有每分钟自动刷新或用户手动刷新时重新读取本地 `daily.jsonl` 与 iCloud 缓存。
+接收云端变化时只更新 `cache.jsonl` 和 `cursor.data`,不直接发布新的 `WorkflowSnapshot`,也不让面板立即跳数。缓存和游标按「先写 `cache.jsonl`,再写 `cursor.data`」提交;如果缓存写入失败,游标不会提前推进,下一轮会重新拉取同一批变化或全量回填。面板仍只在现有每分钟自动刷新或用户手动刷新时重新读取本地 `daily.jsonl` 与同步缓存。
展示合并规则:
```text
-最终展示 = 本机 daily.jsonl + iCloud 缓存中的其他设备记录
+最终展示 = 本机 daily.jsonl + 同步缓存中的其他设备记录
```
-`cache.jsonl` 写入前必须过滤本机自己的 CloudKit 记录,否则本机会把本地 daily 和自己上传的云端副本重复相加。本机数据永远以本地 `daily.jsonl` 为准;云端只补其他设备。热力图详情的 6 个工作流指标按每台设备各自 daily 口径先生成展示值,再按日期相加;`projectCounts` 按项目名逐项相加。
+`cache.jsonl` 写入前必须过滤本机自己的 CloudKit 记录,否则本机会把本地 daily 和自己上传的云端副本重复相加。本机数据永远以本地 `daily.jsonl` 为准;同步缓存只补其他设备。热力图详情的 6 个工作流指标按每台设备各自 daily 口径先生成展示值,再按日期相加;`projectCounts` 按项目名逐项相加。
-iCloud 也按最近 210 天保留。每天第一次工作流刷新时,当前设备会删除 `deviceId == 本机 deviceId` 且早于保留窗口的 CloudKit 记录;其他设备记录不由本机清理。展示侧始终忽略最近 210 天外的缓存记录。
+CloudKit 也按最近 210 天保留。每天第一次工作流刷新时,当前设备会删除 `deviceId == 本机 deviceId` 且早于保留窗口的 CloudKit 记录;其他设备记录不由本机清理。展示侧始终忽略最近 210 天外的缓存记录。
+
+维护和同步请求由 `WorkflowSyncScheduler` 统一调度。菜单面板打开时只读取现有 `daily.jsonl` 和同步缓存;app-server 自动刷新倒计时重置、同步开关开启、Hook 重新开启或同步账号恢复可用时, 调度器合并维护/同步请求。同步中不会取消重启,冷却窗口内只保留一次待补跑请求,补跑前会重新校验 Hook、同步偏好和账号可用性。
+
+同步失败不会清空开启偏好,也不会把原始 CloudKit 错误直接展示给用户。`WorkflowSyncService` 会把错误归类为「网络不可用」「账号不可用」「服务暂时不可用」「同步失败,请稍后重试」,并通过同步结束通知交给 `WorkflowSyncSettings`。主面板更新时间行最右侧使用 `exclamationmark.icloud` 进入失败态,tooltip 展示归类后的短错误;设置页只保留「同步不可用」、同步中和最近上传时间。
## 统计口径
@@ -250,28 +254,28 @@ subagentStopCount, sessionCount, turnCount, projectCounts, sessionIds, turnIds
逐字段统计口径如下:
-| `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` 可解析。 | 进入 `WorkflowDailyStats.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`。窗口外日期会被压缩为 `sessionCount` 并写成 `null`。 | 参与「会话总数」去重。 |
-| `turnIds` | `turn` | 仅最近 3 个本地自然日保留。任意事件行只要 `turn` 是非空字符串,就插入当天集合并去重、排序;不要求事件类型是 `Stop`。窗口外日期会被压缩为 `turnCount` 并写成 `null`。 | 参与「对话轮次」去重。 |
-| `sessionCount` | `sessionIds`、旧 `sessionCount`、`sessionStartCount` | 最近 3 天通常为 `null`;日期进入 3 天外窗口后,归一化时优先沿用已有 `sessionCount`,否则使用 `sessionIds.count`,再否则使用 `sessionStartCount`,然后移除 `sessionIds`。这样旧日期不用继续保存完整 ID,也能保留会话总数。 | 参与「会话总数」。 |
-| `turnCount` | `turnIds`、旧 `turnCount`、`stopCount` | 最近 3 天通常为 `null`;日期进入 3 天外窗口后,归一化时优先沿用已有 `turnCount`,否则使用 `turnIds.count`,再否则使用 `stopCount`,然后移除 `turnIds`。这样旧日期不用继续保存完整 ID,也能保留轮次总数。 | 参与「对话轮次」。 |
-| `projectCounts` | `cwd` | 任意事件行只要 `cwd` 非空,就取标准化路径的最后一层目录名作为项目名并 `+1`;如果最后一层为空,回退使用完整路径字符串。统计的是事件数,不是会话数或工具调用数。未知事件也会计入。 | 用于计算 `mostActiveProject`,当前页面不展示。 |
+| `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`。窗口外日期会被压缩为 `sessionCount` 并写成 `null`。 | 参与「会话总数」去重。 |
+| `turnIds` | `turn` | 仅最近 3 个本地自然日保留。任意事件行只要 `turn` 是非空字符串,就插入当天集合并去重、排序;不要求事件类型是 `Stop`。窗口外日期会被压缩为 `turnCount` 并写成 `null`。 | 参与「对话轮次」去重。 |
+| `sessionCount` | `sessionIds`、旧 `sessionCount`、`sessionStartCount` | 最近 3 天通常为 `null`;日期进入 3 天外窗口后,归一化时优先沿用已有 `sessionCount`,否则使用 `sessionIds.count`,再否则使用 `sessionStartCount`,然后移除 `sessionIds`。这样旧日期不用继续保存完整 ID,也能保留会话总数。 | 参与「会话总数」。 |
+| `turnCount` | `turnIds`、旧 `turnCount`、`stopCount` | 最近 3 天通常为 `null`;日期进入 3 天外窗口后,归一化时优先沿用已有 `turnCount`,否则使用 `turnIds.count`,再否则使用 `stopCount`,然后移除 `turnIds`。这样旧日期不用继续保存完整 ID,也能保留轮次总数。 | 参与「对话轮次」。 |
+| `projectCounts` | `cwd` | 任意事件行只要 `cwd` 非空,就取标准化路径的最后一层目录名作为项目名并 `+1`;如果最后一层为空,回退使用完整路径字符串。统计的是事件数,不是会话数或工具调用数。未知事件也会计入。 | 用于计算 `mostActiveProject`,当前页面不展示。 |
读取旧 `daily.jsonl` 时,缺失的数字字段按 `0` 处理,缺失的 `projectCounts` 按空字典处理,缺失的 `sessionIds` / `turnIds` / `sessionCount` / `turnCount` 保持为 `nil`。后续归一化会按当前保留策略补齐或压缩这些字段。
-UI 不直接展示所有原始字段,而是先生成 `WorkflowDailyStats`:
+UI 不直接展示所有原始字段,而是先生成 `WorkflowDailyMetrics`:
| 页面展示名 | 生成规则 |
| ---------- | ------------------------------------------------------- |
@@ -282,7 +286,7 @@ UI 不直接展示所有原始字段,而是先生成 `WorkflowDailyStats`:
| 权限请求 | `permissionRequestCount` |
| 上下文压缩 | `max(preCompactCount, postCompactCount)` |
-`mostActiveProject` 和 `eventCount` 会进入 `WorkflowDailyStats`,但当前页面没有展示。`UserPromptSubmit` 和未知事件不会增加上述 6 个页面指标,只会进入 `eventCount`,有 `cwd` 时也会进入 `projectCounts`。
+`mostActiveProject` 和 `eventCount` 会进入 `WorkflowDailyMetrics`,但当前页面没有展示。`UserPromptSubmit` 和未知事件不会增加上述 6 个页面指标,只会进入 `eventCount`,有 `cwd` 时也会进入 `projectCounts`。
## UI 展示
diff --git a/Docs/CrossDeviceSync.md b/Docs/CrossDeviceSync.md
index aad192b..82c53e4 100644
--- a/Docs/CrossDeviceSync.md
+++ b/Docs/CrossDeviceSync.md
@@ -1,6 +1,6 @@
# 跨设备同步
-本文档记录设置页「跨设备同步」的完整链路。当前实现只同步 Codex Hook 产生的工作流统计每日聚合,不是整个 App 的通用 iCloud 同步。
+本文档记录设置页「跨设备同步」的完整链路。当前实现只同步 Codex Hook 产生的工作流统计每日聚合,不是整个 App 的通用云同步。
## 同步范围
@@ -25,13 +25,15 @@
| 文件 | 职责 |
| --- | --- |
-| `CodexBar/Services/Settings/WorkflowSyncSettings.swift` | 设置页状态、iCloud 可用性检查、UserDefaults 开关、最近上传时间、同步中通知 |
-| `CodexBar/Services/WorkflowStats/WorkflowSyncService.swift` | CloudKit 设备标识、上传、拉取、缓存、游标、清理过期记录 |
-| `CodexBar/Services/WorkflowStats/WorkflowStatsService.swift` | 在工作流统计维护刷新中调用同步服务,并把本机 daily 与 iCloud 缓存合并成快照 |
-| `CodexBar/Models/CodexWorkflowStatsModels.swift` | 本机聚合、云端脱敏聚合、云端缓存记录、最终 UI 快照的模型和合并规则 |
-| `CodexBar/Views/Settings/AppSettingsView.swift` | 设置页「跨设备同步」开关、`iCloud 不可用`、同步中和最近上传时间展示 |
-| `CodexBar/Controllers/SettingsWindowController.swift` | 打开设置窗口前刷新 Hook 和 iCloud 同步状态 |
-| `CodexBar/Controllers/StatusItemController.swift` | 自动刷新时触发维护同步;开关变化后立即触发一次维护刷新 |
+| `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 和同步可用性变化交给调度器 |
## 本地状态
@@ -44,11 +46,13 @@
同步子目录:
```text
-iCloudSync/state.json
-iCloudSync/cache.jsonl
-iCloudSync/cursor.data
+Sync/state.json
+Sync/cache.jsonl
+Sync/cursor.data
```
+如果旧版 `HookEvents/iCloudSync/` 已存在且新的 `HookEvents/Sync/` 不存在,`WorkflowStorage.syncDirectoryURL()` 会继续使用旧目录,避免已有同步状态丢失;新写入默认使用 `Sync/`。
+
各文件职责:
| 文件 | 内容 |
@@ -75,10 +79,10 @@ iCloudSync/cursor.data
| Key | 含义 |
| --- | --- |
-| `WorkflowiCloudSync.isEnabled` | 用户是否开启过跨设备同步 |
-| `WorkflowiCloudSync.needsBackfill` | 是否需要对本机现有 daily 数据做一次补传 |
+| `WorkflowSync.isEnabled` | 用户是否开启过跨设备同步 |
+| `WorkflowSync.needsBackfill` | 是否需要对本机现有 daily 数据做一次补传 |
-关闭跨设备同步只会把 `WorkflowiCloudSync.isEnabled` 写成 `false`,不会删除本地 `state.json`、`cache.jsonl`、`cursor.data`,也不会删除 CloudKit 中已有记录。
+关闭跨设备同步只会把 `WorkflowSync.isEnabled` 写成 `false`,不会删除本地 `state.json`、`cache.jsonl`、`cursor.data`,也不会删除 CloudKit 中已有记录。
## CloudKit 数据结构
@@ -146,10 +150,10 @@ deviceId = HMAC_SHA256(accountSalt, IOPlatformUUID)
- Codex Hook 本地配置状态
- `hooks/list` 验证结果
-- iCloud account status
+- CloudKit account status
- 最近上传时间
-`AppSettingsView.onAppear` 和 App 再次变为 active 时也会刷新 iCloud 可用性。
+`AppSettingsView.onAppear` 和 App 再次变为 active 时也会刷新同步可用性。
「跨设备同步」开关可操作的条件:
@@ -163,34 +167,43 @@ UI 状态:
| 状态 | UI 表现 |
| --- | --- |
-| iCloud 状态还在检查 | 开关不可操作,暂不显示错误 |
-| iCloud 可用但 Hook 关闭 | 开关不可操作 |
-| iCloud 不可用 | 开关不可操作,下方显示 `iCloud 不可用` |
-| Hook 开启且 iCloud 可用 | 开关可操作 |
+| 同步账号状态还在检查 | 开关不可操作,暂不显示错误 |
+| 同步账号可用但 Hook 关闭 | 开关不可操作 |
+| 同步账号不可用 | 开关不可操作,下方显示 `同步不可用` |
+| Hook 开启且同步账号可用 | 开关可操作 |
| 同步中 | 开关下方显示 `最近上传` 和小型进度指示 |
| 有成功上传记录 | 开关下方显示 `最近上传 yyyy-MM-dd HH:mm:ss` |
+主面板「数据更新时间」行最右侧始终显示同步状态图标:
+
+| 状态 | SF Symbol | tooltip |
+| --- | --- | --- |
+| 未开启同步 | `icloud.slash` | `同步未开启` |
+| 已开启且空闲 | `icloud` | `同步已开启` |
+| 已开启且正在同步 | `arrow.trianglehead.clockwise.icloud` | `正在同步` |
+| 已开启且最近一次同步失败 | `exclamationmark.icloud` | 归类后的短错误, 例如 `网络不可用` |
+
开启时:
-1. `WorkflowSyncSettings.setEnabled(true)` 先确认 iCloud 可用。
-2. 写入 `WorkflowiCloudSync.isEnabled = true`。
-3. 写入 `WorkflowiCloudSync.needsBackfill = true`,要求后续同步补传本机已有 daily 数据。
-4. `StatusItemController` 立即触发 `workflowStatsViewModel.refresh(performMaintenance: true)`。
+1. `WorkflowSyncSettings.setEnabled(true)` 先确认同步账号可用。
+2. 写入 `WorkflowSync.isEnabled = true`。
+3. 写入 `WorkflowSync.needsBackfill = true`,要求后续同步补传本机已有 daily 数据。
+4. `StatusItemController` 请求一次 CloudKit 同步;如果当前空闲且不在冷却窗口内会立即执行,否则由调度器合并为待补跑同步。
关闭时:
-1. 写入 `WorkflowiCloudSync.isEnabled = false`。
-2. 后续 `WorkflowSyncService` 直接返回 `.disabled`,不再访问 CloudKit。
+1. 写入 `WorkflowSync.isEnabled = false`。
+2. 清理调度器中的待同步请求,不新开 CloudKit 同步;已经开始的同步不取消,结束后按最终状态决定是否补跑。
3. 本地同步状态、缓存和云端记录保留。
-关闭 Codex Hook 不会清空跨设备同步偏好;但因为工作流统计同步只在 Hook 开启时触发,所以 Hook 关闭期间不会继续同步。之后重新开启 Hook 时,如果跨设备同步偏好仍为 true 且 iCloud 可用,同步会恢复。
+关闭 Codex Hook 不会清空跨设备同步偏好;但因为工作流统计同步只在 Hook 开启时触发,所以 Hook 关闭期间不会继续同步。之后重新开启 Hook 时,如果跨设备同步偏好仍为 true 且同步账号可用,会通过调度器请求一次同步。
## 刷新时机
-跨设备同步只在工作流统计的维护刷新中执行。核心入口是:
+跨设备同步只在工作流统计的维护刷新中执行,但本机维护和 CloudKit 同步可以分开执行。核心入口是:
```text
-WorkflowStatsService.loadSnapshot(performMaintenance: true)
+WorkflowService.loadSnapshot(performMaintenance: true, synchronize: true)
```
两类刷新行为不同:
@@ -198,15 +211,26 @@ WorkflowStatsService.loadSnapshot(performMaintenance: true)
| 刷新类型 | 是否维护 local daily | 是否访问 CloudKit | 用途 |
| --- | --- | --- | --- |
| `performMaintenance: false` | 否 | 否,只读取 `cache.jsonl` | 打开菜单面板时快速展示现有数据 |
-| `performMaintenance: true` | 是 | 是 | 每分钟自动刷新、开关变化后的立即刷新 |
+| `performMaintenance: true, synchronize: false` | 是 | 否,只读取 `cache.jsonl` | 每分钟自动刷新中的本机统计维护 |
+| `performMaintenance: true, synchronize: true` | 是 | 是 | 调度器允许后的 CloudKit 同步 |
-触发维护刷新:
+触发 CloudKit 同步请求:
-- app-server 自动刷新倒计时重置时,如果 Codex Hook 已开启
-- 用户开启或关闭「跨设备同步」后立即触发一次
+- 用户开启「跨设备同步」
+- Codex Hook 重新开启,且跨设备同步偏好仍为 true
+- 同步账号从不可用变为可用,且 Hook 与跨设备同步都已开启
+- app-server 自动刷新倒计时重置时,如果 Hook、跨设备同步和同步账号都可用
Hook 子进程不访问网络。它只把原始事件写入本机 `events/YYYY-MM-DD.jsonl` 并标记 `maintenance.json` 的 pending 日期。真正的 daily 重建和 CloudKit 同步都由主 App 的维护刷新完成。
+调度器规则:
+
+- 关闭同步、关闭 Hook 或同步账号不可用时,只清理待同步请求,不新开 CloudKit 同步
+- 同步正在执行时,新请求只标记为待补跑,不取消当前同步
+- 冷却窗口内的多次请求合并为一次待补跑同步
+- 补跑前重新校验 Hook 开启、`WorkflowSync.isEnabled == true` 且同步账号可用;最终状态不满足时丢弃待补跑请求
+- `WorkflowViewModel.refreshMaintenance(synchronize:)` 不再自行判断维护并发;维护/同步是否运行、是否排队和是否冷却只由 `WorkflowSyncScheduler` 管理。
+
## 同步主流程
```mermaid
@@ -232,15 +256,15 @@ flowchart TD
同步服务会在开始和结束时发出通知:
```text
-CodexBar.workflowStatsICloudSyncDidStart
-CodexBar.workflowStatsICloudSyncDidFinish
+CodexBar.workflowSyncDidStart
+CodexBar.workflowSyncDidFinish
```
设置页通过这两个通知更新 `isSyncing` 和 `lastUploadAt`。
## 上传数据如何脱敏
-本机 `daily.jsonl` 每行是 `WorkflowDailyAggregate`。上传前会转换成 `WorkflowCloudDailyAggregate`:
+本机 `daily.jsonl` 每行是 `WorkflowDailyAggregate`。上传前会转换成 `WorkflowSyncedDailyAggregate`:
- 保留各类计数字段
- 保留 `projectCounts`
@@ -298,7 +322,7 @@ CodexBar.workflowStatsICloudSyncDidFinish
## 拉取缓存和游标
-上传之后会更新本地 iCloud 缓存。`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 的增量变化:
+上传之后会更新本地同步缓存。`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 的增量变化:
```text
database.recordZoneChanges(
@@ -311,7 +335,7 @@ database.recordZoneChanges(
处理规则:
-- 修改记录: 只接受 `CodexBarDailyAggregate`,转换成 `WorkflowCloudDailyRecord` 后写入内存 cache;如果 `deviceId == 当前设备`, 从 cache 中移除并跳过
+- 修改记录: 只接受 `CodexBarDailyAggregate`,转换成 `WorkflowSyncedDailyRecord` 后写入内存 cache;如果 `deviceId == 当前设备`, 从 cache 中移除并跳过
- 删除记录: 如果删除的是 `CodexBarDailyAggregate`,按 record name 解析出 `deviceId` 和 `date`,从 cache 中移除
- `moreComing == true`: 继续用新的 change token 拉下一页
- `changeTokenExpired` 或增量拉取失败: 不写入日志窗口,直接 query 全量 `CodexBarDailyAggregate` 重建 `cache.jsonl`
@@ -326,15 +350,15 @@ database.recordZoneChanges(
## 展示合并规则
-UI 展示使用 `WorkflowStatsSnapshot`。合并规则是:
+UI 展示使用 `WorkflowSnapshot`。合并规则是:
```text
-最终展示 = 本机 daily.jsonl + iCloud 缓存中的其他设备记录
+最终展示 = 本机 daily.jsonl + 同步缓存中的其他设备记录
```
`cache.jsonl` 写入前会过滤当前设备自己的 CloudKit 记录,否则本机 daily 和自己上传到云端的副本会重复相加。
-同一天多设备数据相加时,会先把每台设备的 daily aggregate 转成 `WorkflowDailyStats`,再按日期求和:
+同一天多设备数据相加时,会先把每台设备的 daily aggregate 转成 `WorkflowDailyMetrics`,再按日期求和:
```text
sessionCount += other.sessionCount
@@ -345,9 +369,9 @@ contextCompactionCount += other.contextCompactionCount
subagentCount += other.subagentCount
```
-本机数据永远以本机 `daily.jsonl` 为准。iCloud 缓存只补其他设备的数据。
+本机数据永远以本机 `daily.jsonl` 为准。同步缓存只补其他设备的数据。
-CloudKit 拉取不会单独向 UI 推送新快照;只有当前这次 `WorkflowStatsService` 刷新最终提交结果时,菜单面板和热力图才会看到更新。非维护刷新只读取已有 `cache.jsonl`,不会主动联网。
+CloudKit 拉取不会单独向 UI 推送新快照;只有当前这次 `WorkflowService` 刷新最终提交结果时,菜单面板和热力图才会看到更新。非维护刷新只读取已有 `cache.jsonl`,不会主动联网。
## 保留和清理
@@ -374,8 +398,8 @@ date < retentionCutoffDate
| 场景 | 当前行为 |
| --- | --- |
-| iCloud 未登录或不可用 | 设置页禁用「跨设备同步」,显示 `iCloud 不可用` |
-| 用户尝试在 iCloud 不可用时开启 | `setEnabled(true)` 直接返回,不写入开启状态 |
+| iCloud 未登录或不可用 | 设置页禁用「跨设备同步」,显示 `同步不可用`; 如果用户已开启同步, 主面板失败 tooltip 显示 `账号不可用` 或兜底错误 |
+| 用户尝试在同步账号不可用时开启 | `setEnabled(true)` 直接返回,不写入开启状态 |
| `CodexBarZone` 不存在 | 同步开始时创建 custom zone |
| CloudKit 上传失败 | 本轮上传停止,已成功批次保留,失败日期下次刷新继续 |
| CloudKit 增量拉取失败 | 不写入日志窗口,尝试全量重建缓存 |
@@ -385,6 +409,6 @@ date < retentionCutoffDate
| `deviceId` 变化 | 重置本地同步 state/cache/cursor,按当前 iCloud 账号重新同步 |
| `changeTokenExpired` | 不写入日志窗口,尝试全量重建缓存并建立新的 cursor |
| `cache.jsonl` 写入失败 | 不保存新 cursor,下一轮重新拉取同一批变化 |
-| 同步失败 | 设置页没有单独错误文案,`最近上传` 不更新 |
+| 同步失败 | `WorkflowSyncService` 捕获错误并归类为 `网络不可用`、`账号不可用`、`服务暂时不可用` 或 `同步失败,请稍后重试`; 主面板显示 `exclamationmark.icloud` 和短 tooltip, 设置页停止同步中状态且 `最近上传` 不更新 |
-同步异常不会清空用户的开启偏好。只要 `WorkflowiCloudSync.isEnabled` 仍为 true、Codex Hook 开启且 iCloud 可用,后续维护刷新会继续重试。
+同步异常不会清空用户的开启偏好。只要 `WorkflowSync.isEnabled` 仍为 true、Codex Hook 开启且同步账号可用,后续调度器允许的同步会继续重试。
diff --git a/Docs/DevelopmentGuide.md b/Docs/DevelopmentGuide.md
index 3f956e6..0aacb2a 100644
--- a/Docs/DevelopmentGuide.md
+++ b/Docs/DevelopmentGuide.md
@@ -25,7 +25,7 @@ App 通过本机 Codex app-server 读取账号, 额度和 token 用量, 通过 C
| ----------------------- | ----------------------------------------------------------------------- |
| `CodexBar/App/` | SwiftUI 入口和 AppDelegate 启动分支 |
| `CodexBar/Controllers/` | 菜单栏, 菜单面板, 设置窗口, 日志窗口和窗口行为 |
-| `CodexBar/Models/` | account, quota, usage, workflow stats, 日期网格和错误模型 |
+| `CodexBar/Models/` | account, quota, usage, workflow, 日期网格和错误模型 |
| `CodexBar/Services/` | app-server, Codex CLI 解析, 版本探测, Hook 设置, 统计维护, 更新, 登录项 |
| `CodexBar/Views/` | 菜单面板, 设置窗口, 日志窗口和共享 Liquid Glass 样式 |
| `Docs/` | app-server, Hook 和开发文档 |
@@ -36,7 +36,7 @@ App 通过本机 Codex app-server 读取账号, 额度和 token 用量, 通过 C
两条主数据链路:
- Codex app-server 链路: `CodexStatusService` 启动或复用本机 app-server, 生成 `CodexQuotaSnapshot`, 由 `CodexStatusViewModel` 发布给菜单栏 UI
-- Codex Hook 链路: Codex 进程触发带 `--hook-event` 参数的 Hook 命令, CodexBar 从 stdin payload 读取 `hook_event_name` 并快速写入 JSONL; 主 App 后续维护聚合并生成 `WorkflowStatsSnapshot`
+- Codex Hook 链路: Codex 进程触发带 `--hook-event` 参数的 Hook 命令, CodexBar 从 stdin payload 读取 `hook_event_name` 并快速写入 JSONL; 主 App 后续维护聚合并生成 `WorkflowSnapshot`
## 3. 启动流程
@@ -66,11 +66,12 @@ sequenceDiagram
end
```
-普通启动时, `CodexBarAppDelegate` 创建五个长期对象:
+普通启动时, `CodexBarAppDelegate` 创建六个长期对象:
- `CodexStatusViewModel`: app-server 刷新状态
-- `WorkflowStatsViewModel`: Hook 工作流统计快照
+- `WorkflowViewModel`: Hook 工作流统计快照
- `CodexHookSettings`: Hook 配置状态和写入操作
+- `WorkflowSyncSettings`: 跨设备同步偏好、账号可用性、同步中和失败状态
- `GlobalHotKeySettings`: 全局快捷键配置和错误状态
- `AppUpdater`: Sparkle 更新状态
@@ -79,9 +80,12 @@ sequenceDiagram
- 配置菜单栏按钮图标, tooltip 和点击事件
- 配置菜单面板的 SwiftUI 根视图
- 订阅状态变化并切换菜单栏图标
+- 订阅 Hook、同步开关和同步可用性变化, 把维护/同步请求交给 `WorkflowSyncScheduler`
- 订阅全局快捷键配置并安装或移除 Carbon hot key
- 开始每 60 秒自动刷新
+启动时还会把系统 tooltip 首次出现延迟 `NSInitialToolTipDelay` 设置为 200 ms, 让主面板同步图标等短提示更快出现。
+
App 退出时, `applicationWillTerminate` 调用 `StatusItemController.uninstall()`, 关闭菜单面板, 注销全局快捷键, 移除订阅并从系统状态栏移除 status item
## 4. 菜单栏, 菜单面板与窗口流程
@@ -117,7 +121,7 @@ App 退出时, `applicationWillTerminate` 调用 `StatusItemController.uninstall
- 如果来自全局快捷键且当前状态需要打开菜单面板, 先用目标屏幕确认 status item 锚点可信; 不可信时改用同一屏幕顶部居中的 fallback `NSPanel`
- 设置状态为 `opening`, 准备透明度淡入
- 显示 `NSPopover` 或 fallback `NSPanel`, 把 `MenuSurfaceVisibilityState.isVisible` 设为 `true`
-- 调用 `refreshWorkflowStatsIfHookEnabled(performMaintenance: false)`, 只读取已有 `daily.jsonl`, 不做重维护
+- 调用 `refreshWorkflowIfHookEnabled(performMaintenance: false)`, 只读取已有 `daily.jsonl`, 不做重维护
- 安装 `MenuSurfaceDismissMonitor`, 监听当前菜单面板 window 并只将当前菜单面板 window 置前和设为 key window
- 执行 0.24 秒淡入
- 延迟 160 ms 后调用 `viewModel.refreshIfNeeded()`
@@ -368,7 +372,7 @@ codex app-server --listen stdio://
- 菜单面板只展示"未登录"和"初始化失败"两类特殊状态
- 具体启动失败, 请求失败, 超时, 断连, 解析失败和业务错误进入日志窗口
- 账户有效时, rate limits 和 usage 可以单独失败, 失败区域按缓存或无数据处理
-- 登录项和 Hook 写入错误显示在设置窗口中部的独立错误组, iCloud 账号不可用显示在「跨设备同步」开关下方
+- 登录项错误显示在设置窗口中部的独立错误组; Hook 写入/验证错误显示在 Hook 开关下方; 同步账号不可用显示在「跨设备同步」开关下方; 同步运行失败显示在主面板更新时间行同步图标 tooltip 中
- 全局快捷键录制, 校验和注册错误显示在快捷键行内
- Hook 子进程尽量快速退出, 事件记录失败不会阻断 Codex 自身流程
@@ -414,17 +418,17 @@ app-server 与状态刷新错误:
| `hooks.json` 读取失败或结构非法 | `CodexHookSettings.refresh` | Hook 开关视为关闭, Hook 选项下方显示错误 | 不写配置 |
| Hook 开关写入失败 | `CodexHookSettings.setEnabled` | Hook 选项下方显示"设置 Codex Hook 失败" | 调用 `refresh()` 恢复实际状态 |
| `hooks/list` 请求失败 | `CodexHookSettings.verifyInstalledHooks` / app-server `hooks/list` | Hook 选项下方显示"无法验证 Codex Hook" | 保留已写入 Hook, 详细错误进入日志 |
-| Hook 自动信任写入失败 | `CodexHookSettings.updateCodexHookTrust` / app-server `config/batchWrite` | Hook 选项下方显示"无法验证 Codex Hook" | 保留已写入 Hook, 详细错误进入日志 |
+| Hook 自动信任写入失败 | `CodexHookSettings.trustCodexBarHooks` / app-server `config/batchWrite` | Hook 选项下方显示"无法验证 Codex Hook" | 保留已写入 Hook, 详细错误进入日志 |
| Hook 写入后验证发现问题 | `CodexHookSettings.verifyInstalledHooks` / app-server `hooks/list` | Hook 选项下方显示最高优先级验证摘要 | 保留已写入 Hook, 详细响应进入日志 |
-| iCloud 账号不可用 | `WorkflowSyncSettings.refreshICloudAvailability` / CloudKit account status | 跨设备同步开关禁用, 下方显示"iCloud 不可用" | 不开启同步偏好写入 |
-| CloudKit 同步上传或拉取失败 | `WorkflowSyncService.synchronizeIfEnabled` | 暂无明确错误提示, 最近上传时间不更新 | 保存已有 state, 下次刷新继续重试 |
+| 同步账号不可用 | `WorkflowSyncSettings.refreshSyncAvailability` / CloudKit account status | 跨设备同步开关禁用, 下方显示"同步不可用"; 已开启同步时主面板 tooltip 显示归类错误 | 不开启同步偏好写入 |
+| CloudKit 同步上传或拉取失败 | `WorkflowSyncService.synchronizeIfEnabled` | 主面板更新时间行显示 `exclamationmark.icloud`, tooltip 显示归类错误, 最近上传时间不更新 | 保存已有 state, 下次刷新继续重试 |
| 快捷键无法识别或不符合规则 | `HotKeyRecorderRow` / `GlobalHotKeySettings.setShortcut` | 快捷键行内显示红色错误 | 用户清除后重新录制 |
| 快捷键注册冲突 | `StatusItemController.applyGlobalHotKey` | 快捷键行内显示占用提示 | 恢复上一个已注册快捷键 |
| Hook 子进程 payload 不是 JSON | `WorkflowHookEventRecorder.stdinPayload` | 无 UI 提示 | 吞掉本次 Hook, 避免启动完整菜单栏 App |
| Hook 子进程写入失败 | `WorkflowHookEventRecorder.handleIfRequested` | 无 UI 提示 | `try? record` 吞掉错误并正常退出, 避免阻断 Codex |
-| `daily.jsonl` 缺失, 空文件或坏行 | `WorkflowStatsService.prepareMaintenanceTasks` | 热力图详情面板可能暂时显示 0 | 标记 dirty, 后续从 events 文件重建 |
-| events 文件变小或 offset 不一致 | `WorkflowStatsService.reconcileEventFiles` | 热力图详情面板可能暂时显示旧聚合 | 标记 dirty, 从头重建当天聚合 |
-| 单个维护任务失败 | `WorkflowStatsService.performMaintenanceIfNeeded` | 使用已有 daily 或空 snapshot | 对应日期标记 dirty |
+| `daily.jsonl` 缺失, 空文件或坏行 | `WorkflowService.prepareMaintenanceTasks` | 热力图详情面板可能暂时显示 0 | 标记 dirty, 后续从 events 文件重建 |
+| events 文件变小或 offset 不一致 | `WorkflowService.reconcileEventFiles` | 热力图详情面板可能暂时显示旧聚合 | 标记 dirty, 从头重建当天聚合 |
+| 单个维护任务失败 | `WorkflowService.performMaintenanceIfNeeded` | 使用已有 daily 或空 snapshot | 对应日期标记 dirty |
| Sparkle 配置缺失 | `AppUpdater.init` | 更新开关禁用, 操作显示"未配置更新资源" | 不创建 updater controller |
| 手动检查没有更新 | `updaterDidNotFindUpdate` | 显示"没有可用更新" | 1 秒后自动清理状态 |
| 手动检查失败 | `didAbortWithError` | 显示"检查更新失败" | 不展示底层错误细节 |
@@ -478,7 +482,7 @@ Codex 版本探测错误:
- `CodexUsageSnapshot.recentWeekGrid` 使用 `CodexWeekGrid` 生成周日到周六排列的日期网格
- 本轮 usage 请求失败但同账号有旧缓存时复用旧值, 并把 `isUsageStale` 设为 `true`
-热力图日期规则由 `UsageHeatmapDay.grid` 合并 token 和 workflow stats:
+热力图日期规则由 `UsageHeatmapDay.grid` 合并 token 和 workflow:
- 固定 30 列 x 7 行
- Hook 开启时包含今天
@@ -557,6 +561,8 @@ Hook 开启且当天没有 token bucket 时, 今天的 token 数显示 `--`。
- 菜单面板不可见时只渲染一次静态圆环
- 普通 tick 不做连续动画, 只有刷新起点变化时播放 0.5 秒恢复动画
- 如果 Sparkle 自动发现新版, 右侧显示 `panelUpdateMessage`, 双击该文本调用 `startUpdate()`
+- 最右侧显示同步状态图标: 未开启 `icloud.slash`, 已开启空闲 `icloud`, 正在同步 `arrow.trianglehead.clockwise.icloud`, 最近一次同步失败 `exclamationmark.icloud`
+- 同步失败 tooltip 不展示原始 CloudKit error, 只展示「网络不可用」「账号不可用」「服务暂时不可用」「同步失败,请稍后重试」这类归类文案
## 10. Codex Hook 开启后完整流程
@@ -623,10 +629,10 @@ sequenceDiagram
opt Hook 已启用且 Codex 触发事件
Codex->>HookApp: 执行 Hook 命令并传入事件内容
HookApp->>HookApp: 解析事件名, 时间, 目录, 工具和会话字段
- alt 标准输入为空或不是 JSON
- HookApp->>HookApp: 使用当前时间和工作目录兜底
+ alt 标准输入为空, 不是 JSON 或缺少 hook_event_name
+ HookApp-->>Codex: 吞掉本次 Hook 并正常退出
else 事件内容可解析
- HookApp->>HookApp: 转成本机事件记录
+ HookApp->>HookApp: 转成本机事件记录, 缺失 timestamp/cwd 时使用兜底值
end
HookApp->>Store: 获取写入锁
@@ -759,17 +765,18 @@ Hook 数据目录:
| `stats.lock` | `flock` 锁文件 |
| `maintenance.json` | pending, dirty, offset, size, corrupt 等维护状态 |
-## 12. Workflow Stats 维护与聚合流程
+## 12. Workflow 维护与聚合流程
-`WorkflowStatsViewModel` 刷新规则:
+`WorkflowViewModel` 刷新规则:
-- `refreshIfNeeded(performMaintenance: false)` 至少间隔 5 秒
-- `performMaintenance: true` 时跳过 5 秒节流, 直接刷新
-- 如果普通读取尚未结束, 带维护的刷新会通过 `RefreshTaskCoordinator` 取消旧任务, 确保旧结果不会回写
-- 打开菜单面板时如果 Hook 开启, 只读取现有 `daily.jsonl`, 不维护
-- app-server 自动刷新倒计时重置时, 如果 Hook 开启, 触发一次带维护的 workflow stats 刷新
+- `refreshIfNeeded()` 只负责普通 UI 读取, 至少间隔 5 秒
+- 打开菜单面板时如果 Hook 开启, 只读取现有 `daily.jsonl` 和同步缓存, 不维护, 不联网
+- app-server 自动刷新倒计时重置时, 如果 Hook 开启, 通过 `WorkflowSyncScheduler.requestMaintenance(allowsSync: true)` 请求一次维护
+- 同步开关开启、Hook 重新开启或同步账号恢复可用时, 通过 `WorkflowSyncScheduler.requestSync()` 请求一次同步维护
+- `WorkflowSyncScheduler` 是维护/同步任务的唯一调度者, 负责运行中、待补跑、冷却窗口和最终状态校验
+- `WorkflowViewModel.refreshMaintenance(synchronize:)` 不自行判断维护并发, 只取消普通读取并执行一次明确的 `WorkflowService.loadSnapshot(performMaintenance: true, synchronize: ...)`
-维护流程在 `WorkflowStatsService` actor 内串行执行
+维护流程在 `WorkflowService` actor 内串行执行
```mermaid
flowchart TD
@@ -806,7 +813,7 @@ flowchart TD
- 210 天外的 `events/YYYY-MM-DD.jsonl` 在主 App 维护流程中删除
- 坏 JSONL 行跳过并计入 `corrupt`, 不阻断整天聚合
-UI 展示指标来自 `WorkflowDailyAggregate.stats`:
+UI 展示指标来自 `WorkflowDailyAggregate.metrics`:
| UI 字段 | 生成规则 |
| ---------- | ------------------------------------------------------- |
@@ -817,7 +824,7 @@ UI 展示指标来自 `WorkflowDailyAggregate.stats`:
| 权限请求 | `permissionRequestCount` |
| 上下文压缩 | `max(preCompactCount, postCompactCount)` |
-iCloud 同步只在 `performMaintenance: true` 的刷新中执行。`WorkflowSyncService` 先用本机 daily 聚合生成脱敏 `WorkflowCloudDailyAggregate`, 再按日期稳定排序候选项, 每批最多上传 25 天, 每轮最多使用 20 秒。每批成功后立即保存 `state.hashByDate` 和 `lastUploadAt`, 未完成的 backfill 留给后续自动刷新继续。没有 `cursor.data` 时先 query 全量 `CodexBarDailyAggregate` 回填 `cache.jsonl`; 有游标时优先拉 CloudKit 增量, 游标失效或增量失败时不写入日志窗口, 直接全量重建缓存。写入 `cache.jsonl` 前会过滤当前设备自己的记录, 只保留其他设备记录。增量路径先写 `cache.jsonl`, 成功后再写 `cursor.data`, 避免游标提前推进导致未落盘记录被跳过。
+跨设备同步只在 `performMaintenance: true, synchronize: true` 的刷新中执行。`WorkflowSyncScheduler` 会合并同步开关、Hook 重新开启、同步账号恢复可用和自动刷新产生的同步请求;同步中不取消重启, 冷却窗口内只保留一次待补跑请求, 补跑前重新校验 Hook 开启、跨设备同步偏好为 true 且同步账号可用。`WorkflowSyncService` 先用本机 daily 聚合生成脱敏 `WorkflowSyncedDailyAggregate`, 再按日期稳定排序候选项, 每批最多上传 25 天, 每轮最多使用 20 秒。每批成功后立即保存 `state.hashByDate` 和 `lastUploadAt`, 未完成的 backfill 留给后续自动刷新继续。没有 `cursor.data` 时先 query 全量 `CodexBarDailyAggregate` 回填 `cache.jsonl`; 有游标时优先拉 CloudKit 增量, 游标失效或增量失败时不写入日志窗口, 直接全量重建缓存。写入 `cache.jsonl` 前会过滤当前设备自己的记录, 只保留其他设备记录。增量路径先写 `cache.jsonl`, 成功后再写 `cursor.data`, 避免游标提前推进导致未落盘记录被跳过。同步失败会通过 `CodexBar.workflowSyncDidFinish` 通知发送 `didSucceed=false` 和归类后的 `failureMessage`, 主面板同步图标进入失败态。
## 13. 设置窗口流程
@@ -837,7 +844,7 @@ iCloud 同步只在 `performMaintenance: true` 的刷新中执行。`WorkflowSyn
- `CodexCLIVersionViewModel.refresh()`
- `CodexStatusViewModel.refreshCodexConnectionInfo()`
-App 再次成为 active 时, 也会刷新 Codex 版本区、iCloud 可用性, 并在已安装 Hook 时重新运行 `hooks/list` 验证。
+App 再次成为 active 时, 也会刷新 Codex 版本区、同步可用性, 并在已安装 Hook 时重新运行 `hooks/list` 验证。
版本探测内部有 60 秒节流, 避免 `onAppear` 和 `didBecomeActive` 连续触发时重复启动子进程
@@ -849,7 +856,7 @@ App 再次成为 active 时, 也会刷新 Codex 版本区、iCloud 可用性,
| 自动检查更新 | Sparkle updater | 设置 `automaticallyChecksForUpdates` |
| 使用快捷键 | `GlobalHotKeySettings.shortcut` | 写入 `UserDefaults` 并注册 hot key |
| 启用 Codex Hook | app-server `config/read` / `hooks/list` / `config/batchWrite`, `~/.codex/hooks.json` | 检查全局 Hook 开关后追加或移除当前 CodexBar command hook, 并维护对应 `hooks.state` 信任状态 |
-| 跨设备同步 | `WorkflowSyncSettings` + CloudKit account status | Hook 开启且 iCloud 可用时写入 `UserDefaults`; 开启时标记 `needsBackfill` |
+| 跨设备同步 | `WorkflowSyncSettings` + CloudKit account status + `WorkflowSyncScheduler` | Hook 开启且同步账号可用时写入 `UserDefaults`; 开启时标记 `needsBackfill` 并请求调度同步 |
| Codex 版本 | `CodexCLIVersionSnapshot` + 当前 app-server 握手信息 | 路径点击复制到剪贴板 |
| CodexBar 版本 | Bundle + AppUpdater 状态 | 有更新状态时优先显示动态消息 |
@@ -857,7 +864,8 @@ App 再次成为 active 时, 也会刷新 Codex 版本区、iCloud 可用性,
- 开机启动失败显示在设置组与底部按钮组之间的独立错误组
- Hook 设置失败, 全局禁用, 自动信任写入失败或验证异常显示在 Hook 选项下方
-- iCloud 不可用时显示在跨设备同步开关下方
+- 同步账号不可用时显示在跨设备同步开关下方
+- 同步运行失败不在设置页展示原始错误; 主面板同步图标 tooltip 显示归类后的短错误
- 没有登录项错误时不渲染错误组
- 快捷键无法识别, 规则不合法或注册冲突显示在快捷键行内
- 更新检查状态显示在 CodexBar 版本行
@@ -978,7 +986,7 @@ App 再次成为 active 时, 也会刷新 Codex 版本区、iCloud 可用性,
| UI, 控制器, ViewModel, 设置, 更新 | `@MainActor` |
| `CodexStatusService` | actor 隔离 app-server 连接、缓存和重建状态 |
| `CodexCLIVersionService` | actor + `async let` 并发探测版本 |
-| `WorkflowStatsService` | actor 串行维护 daily 聚合和快照读取 |
+| `WorkflowService` | actor 串行维护 daily 聚合和快照读取 |
| `RequestLogStorage` | `OSAllocatedUnfairLock` 保护后台同步写入 |
| `RequestLogStore` | `@MainActor ObservableObject` 发布日志快照 |
| Hook 写入 | `stats.lock` + `flock(LOCK_EX)` |
diff --git a/appcast.xml b/appcast.xml
index aabff43..ab30193 100644
--- a/appcast.xml
+++ b/appcast.xml
@@ -7,6 +7,15 @@
<link>https://codexbar.zabrian.app/appcast.xml</link>
<description>CodexBar appcast feed</description>
<language>zh-CN</language>
+ <item>
+ <title>CodexBar.app 3.2.1</title>
+ <sparkle:version>29</sparkle:version>
+ <sparkle:shortVersionString>3.2.1</sparkle:shortVersionString>
+ <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+ <sparkle:releaseNotesLink>https://codexbar.zabrian.app/notes#3.2.1</sparkle:releaseNotesLink>
+ <pubDate>Sat, 27 Jun 2026 20:16:03 +0800</pubDate>
+ <enclosure url="https://codexbar.zabrian.app/download/CodexBar-v3.2.1.dmg" sparkle:edSignature="c/Yt/6GzPzxK95iqBO8rdFgMs9drbLI0zeIOpeLwLW26KUnNTEKotMknRQvWaIy+9vj9iIcKGYj2O+3WCnvCBA==" length="3349526" type="application/octet-stream"/>
+ </item>
<item>
<title>CodexBar.app 3.2.0</title>
<sparkle:version>28</sparkle:version>