Skip to content

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

feat: 添加工作流统计跨设备同步

Bob986160ca8515
diff --git a/AGENTS.md b/AGENTS.md
index a5cb545..b966206 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.1`, `CURRENT_PROJECT_VERSION = 25`, `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`, `SWIFT_VERSION = 6.0`。
+- 当前 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`。
- 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/` 根层。
@@ -84,6 +84,7 @@ Codex Hook
-> WorkflowHookEventRecorder(--hook-event stdin hook_event_name)
-> WorkflowStatsStorage(events/YYYY-MM-DD.jsonl / daily.jsonl)
-> WorkflowStatsService
+ -> WorkflowSyncService(可选 CloudKit private database 同步)
-> WorkflowStatsViewModel
-> UsageSummaryView / UsageHeatmap
```
@@ -96,7 +97,7 @@ Codex Hook
- `Services/`: app-server、Codex CLI、设置、Hook 统计、更新和日志服务。
- `Views/`: 菜单面板、设置、日志和共享 Liquid Glass 样式。
-Hook 统计的配置、存储、保留策略和统计口径见 [Docs/CodexHook.md](Docs/CodexHook.md)。
+Hook 统计的配置、存储、保留策略和统计口径见 [Docs/CodexHook.md](Docs/CodexHook.md), 跨设备同步见 [Docs/CrossDeviceSync.md](Docs/CrossDeviceSync.md)。
## app-server 合约
@@ -111,7 +112,7 @@ Hook 统计的配置、存储、保留策略和统计口径见 [Docs/CodexHook.m
- 详细设计见 [Docs/CodexHook.md](Docs/CodexHook.md)。
- 设置开关只能追加或移除 command 同时包含当前 CodexBar 可执行路径和 `--hook-event` 参数的 Hook 处理器, 不能破坏其他用户 Hook。
- Hook 命令写入当前 CodexBar 可执行文件路径和 `--hook-event` 参数; Hook 事件名来自 Codex 传入的 stdin payload 顶层 `hook_event_name`。
-- Hook 数据只保存在 `~/Library/Application Support/CodexBar/HookEvents/`。
+- Hook 原始事件和本机 daily 聚合保存在 `~/Library/Application Support/CodexBar/HookEvents/`; 用户开启「跨设备同步」后, 仅脱敏 daily 聚合副本会同步到当前 iCloud 账号的 CloudKit private database。
- Hook 写入可能并发触发, 追加 `events/YYYY-MM-DD.jsonl` 并更新 `maintenance.json` 时必须通过 `stats.lock` 加锁。
## UI 状态与日志
@@ -206,6 +207,8 @@ Hook 统计的配置、存储、保留策略和统计口径见 [Docs/CodexHook.m
- 开启 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 开关下方只在必要时显示 Hook 相关错误; 不展示固定说明文案、启用状态或关闭状态文案。
+- 设置页包含「跨设备同步」开关; 仅在 Codex Hook 开启且 iCloud account status 为 available 时可操作。iCloud 不可用时开关禁用, 并在开关下方显示「iCloud 不可用」。
+- 「跨设备同步」开启后, 主 App 在工作流统计维护刷新中把脱敏 daily 聚合按日期稳定排序、每批最多 25 天、每轮最多 20 秒上传到 CloudKit; 已成功上传的日期立即写入本地 `state.json`, 剩余日期留给后续刷新继续。
- 开机启动错误显示在设置组与底部按钮组之间的独立错误组; 无错误时不展示该组, 退出和检查更新按钮之间不展示错误文案。
日志窗口:
@@ -228,9 +231,9 @@ Hook 统计的配置、存储、保留策略和统计口径见 [Docs/CodexHook.m
## 认证、隐私与沙盒
-- CodexBar 只与本机 Codex app-server 通信; 账号、额度和 token 使用量不发往第三方服务。
-- Codex Hook 工作流统计只写入本机 `~/Library/Application Support/CodexBar/HookEvents/`, 不发往第三方服务。
-- 除 Sparkle appcast/DMG 下载外, 应用自身不做网络请求。
+- CodexBar 只通过本机 Codex app-server 读取账号、额度和 token 使用量; 这些数据不发往第三方服务。
+- Codex Hook 工作流统计默认只写入本机 `~/Library/Application Support/CodexBar/HookEvents/`; 用户开启「跨设备同步」后, CloudKit 只保存去掉 `sessionIds` / `turnIds` 的 daily 聚合副本, 不保存原始 Hook events。
+- 除 Sparkle appcast/DMG 下载, 以及用户显式开启「跨设备同步」后的 CloudKit private database 请求外, 应用自身不做网络请求。
- App Sandbox 必须保持关闭。
- app-server 和版本探测必须使用真实用户 home。
- 不要把 Codex auth 文件、stderr、原始敏感 RPC 响应或用户路径之外的敏感信息写入 UI、文档或测试夹具。
@@ -264,8 +267,8 @@ fix: 修复 Codex 状态刷新
Tag:
-- tag 名格式 `v{MARKETING_VERSION}`, 例如 `v3.1.1`。
-- 使用附注 tag: `git tag -a v3.1.1 -m "Release v3.1.1"`。
+- tag 名格式 `v{MARKETING_VERSION}`, 例如 `v3.1.3`。
+- 使用附注 tag: `git tag -a v3.1.3 -m "Release v3.1.3"`。
## 最终检查
diff --git a/CLAUDE.md b/CLAUDE.md
index 2e1d8a5..77334d5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,7 +2,7 @@
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-> 本仓库已有一份详尽的 `AGENTS.md`,它是 app-server / Codex Hook / UI / 数据模型 / 发布 / Git 等各项合约的**权威来源**。本文件只做精炼导航,遇到具体行为约束请优先查 `AGENTS.md`、`Docs/AppServer.md` 与 `Docs/CodexHook.md`,不要凭记忆推断。
+> 本仓库已有一份详尽的 `AGENTS.md`,它是 app-server / Codex Hook / UI / 数据模型 / 发布 / Git 等各项合约的**权威来源**。本文件只做精炼导航,遇到具体行为约束请优先查 `AGENTS.md`、`Docs/AppServer.md`、`Docs/CodexHook.md` 与 `Docs/CrossDeviceSync.md`,不要凭记忆推断。
## 构建与验证
@@ -44,12 +44,12 @@ CodexStatusService (JSON-RPC over `codex app-server --listen stdio://`)
- 握手与读取顺序、超时/重连、token 刷新、stale 缓存等约束见 `Docs/AppServer.md` 与 `AGENTS.md` 的「app-server 合约」。
- 错误处理哲学:UI 只暴露 `notLoggedIn` / `initializationFailed` 两类特殊状态;所有具体请求/启动/超时/解析错误进 `RequestLogStorage.shared`(容量 500,完整保存 request/detail),日志窗口通过 `@MainActor RequestLogStore.shared` 订阅快照,列表/行内只展示单行短预览,非空请求/响应标题行提供完整预览和复制,预览视图会格式化并高亮 JSON,不直接展示子进程 stderr。
-**2. Codex Hook 工作流统计流**(本机统计)
+**2. Codex Hook 工作流统计流**(本机统计,可选 iCloud 脱敏同步)
```
WorkflowHookEventRecorder (--hook-event stdin hook_event_name 子进程)
→ WorkflowStatsStorage (events/YYYY-MM-DD.jsonl / daily.jsonl,~/Library/Application Support/CodexBar/HookEvents/)
- → WorkflowStatsService → WorkflowStatsViewModel
+ → WorkflowStatsService → WorkflowSyncService(可选 CloudKit private database) → WorkflowStatsViewModel
→ UsageSummaryView / UsageHeatmap (统计只在热力图侧边详情面板中展示)
```
@@ -58,7 +58,8 @@ WorkflowHookEventRecorder (--hook-event stdin hook_event_name 子进程)
- 开启 Hook 写入后必须通过当前 app-server 会话调用 `hooks/list` 验证 `command`、`eventName`、`enabled`、`sourcePath`、`trustStatus`、`warnings` 和 `errors`;未信任时提示用户去 Codex `/hooks` 信任。
- 设置开关只能追加/移除 `command` 同时包含当前 CodexBar 可执行路径和 `--hook-event` 参数的 Hook 处理器,绝不破坏其他用户 Hook。若用户自定义 Hook 命令也同时包含当前可执行路径和 `--hook-event` 参数,会被视为当前 CodexBar 处理器。
- Hook 写入可能由多个 Codex 进程并发触发,追加 `events/YYYY-MM-DD.jsonl` 并更新 `maintenance.json` 必须经 `stats.lock` + `flock` 加锁;`daily.jsonl` 由主 App 刷新维护流程写回。
-- 字段兼容、保留策略、统计口径见 `Docs/CodexHook.md`。
+- iCloud 跨设备同步只上传去掉 `sessionIds` / `turnIds` 的 daily 聚合副本;iCloud 不可用时设置页禁用「跨设备同步」并显示「iCloud 不可用」。
+- 字段兼容、保留策略、统计口径见 `Docs/CodexHook.md`;跨设备同步完整链路见 `Docs/CrossDeviceSync.md`。
## 并发分工
diff --git a/CodexBar.xcodeproj/project.pbxproj b/CodexBar.xcodeproj/project.pbxproj
index 2e1567f..8ff64e7 100644
--- a/CodexBar.xcodeproj/project.pbxproj
+++ b/CodexBar.xcodeproj/project.pbxproj
@@ -274,10 +274,11 @@
buildSettings = {
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
+ CODE_SIGN_ENTITLEMENTS = CodexBar/Resources/CodexBar.entitlements;
"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";
CODE_SIGN_STYLE = Automatic;
COMBINE_HIDPI_IMAGES = YES;
- CURRENT_PROJECT_VERSION = 27;
+ CURRENT_PROJECT_VERSION = 28;
DEVELOPMENT_TEAM = 4KJ362VJW5;
ENABLE_APP_INTENTS_METADATA_GENERATION = NO;
ENABLE_APP_SANDBOX = NO;
@@ -292,7 +293,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
- MARKETING_VERSION = 3.1.3;
+ MARKETING_VERSION = 3.2.0;
PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar;
PRODUCT_NAME = "$(TARGET_NAME)";
REGISTER_APP_GROUPS = YES;
@@ -310,11 +311,12 @@
buildSettings = {
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
+ CODE_SIGN_ENTITLEMENTS = CodexBar/Resources/CodexBar.entitlements;
CODE_SIGN_IDENTITY = "Apple Development";
"CODE_SIGN_IDENTITY[sdk=macosx*]" = "Apple Development";
CODE_SIGN_STYLE = Automatic;
COMBINE_HIDPI_IMAGES = YES;
- CURRENT_PROJECT_VERSION = 27;
+ CURRENT_PROJECT_VERSION = 28;
DEVELOPMENT_TEAM = 4KJ362VJW5;
ENABLE_APP_INTENTS_METADATA_GENERATION = NO;
ENABLE_APP_SANDBOX = NO;
@@ -329,7 +331,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
- MARKETING_VERSION = 3.1.3;
+ MARKETING_VERSION = 3.2.0;
PRODUCT_BUNDLE_IDENTIFIER = app.zabrian.codexbar;
PRODUCT_NAME = "$(TARGET_NAME)";
PROVISIONING_PROFILE_SPECIFIER = "";
diff --git a/CodexBar/Controllers/HeatmapDetailPanelController.swift b/CodexBar/Controllers/HeatmapDetailPanelController.swift
index 514e9cb..11cb8e9 100644
--- a/CodexBar/Controllers/HeatmapDetailPanelController.swift
+++ b/CodexBar/Controllers/HeatmapDetailPanelController.swift
@@ -18,6 +18,7 @@ private final class DetailPanel: NSPanel {
final class HeatmapDetailPanelController {
private var panel: NSPanel?
private var hostingController: NSHostingController<UsageHeatmapDayDetailView>?
+ private var detailModel: UsageHeatmapDayDetailModel?
private var hideTask: Task<Void, Never>?
private var currentSide = UsageHeatmapDetailSide.left
private var visibilityGeneration = 0
@@ -318,16 +319,20 @@ final class HeatmapDetailPanelController {
}
private func updateContent(_ context: UsageHeatmapHoverContext) {
- let rootView = UsageHeatmapDayDetailView(context: context)
let size = UsageHeatmapDayDetailView.panelSize(showsWorkflowStats: context.showsWorkflowStats)
- if let hostingController {
- hostingController.rootView = rootView
+ if let detailModel {
+ withAnimation(Animation.codexStatus) {
+ detailModel.context = context
+ }
} else {
+ let detailModel = UsageHeatmapDayDetailModel(context: context)
+ let rootView = UsageHeatmapDayDetailView(model: detailModel)
let hostingController = NSHostingController(rootView: rootView)
hostingController.sizingOptions = [.preferredContentSize]
panel?.contentViewController = hostingController
self.hostingController = hostingController
+ self.detailModel = detailModel
}
configurePanelLayers()
diff --git a/CodexBar/Controllers/SettingsWindowController.swift b/CodexBar/Controllers/SettingsWindowController.swift
index e12efc8..ecae744 100644
--- a/CodexBar/Controllers/SettingsWindowController.swift
+++ b/CodexBar/Controllers/SettingsWindowController.swift
@@ -1,30 +1,36 @@
import AppKit
import SwiftUI
-/// 设置窗口控制器, 打开前刷新 Hook 状态并按内容自适应高度
+/// 设置窗口控制器, 打开前刷新设置状态并按内容自适应高度
@MainActor
final class SettingsWindowController: HostingWindowController {
private let viewModel: CodexStatusViewModel
private let appUpdater: AppUpdater
private let codexHookSettings: CodexHookSettings
+ private let cloudSyncSettings: WorkflowSyncSettings
private let globalHotKeySettings: GlobalHotKeySettings
+ private let onICloudSyncChanged: () -> Void
init(
viewModel: CodexStatusViewModel,
appUpdater: AppUpdater,
codexHookSettings: CodexHookSettings,
+ cloudSyncSettings: WorkflowSyncSettings,
globalHotKeySettings: GlobalHotKeySettings,
- screenProvider: @escaping () -> NSScreen?
+ screenProvider: @escaping () -> NSScreen?,
+ onICloudSyncChanged: @escaping () -> Void
) {
self.viewModel = viewModel
self.appUpdater = appUpdater
self.codexHookSettings = codexHookSettings
+ self.cloudSyncSettings = cloudSyncSettings
self.globalHotKeySettings = globalHotKeySettings
+ self.onICloudSyncChanged = onICloudSyncChanged
super.init(screenProvider: screenProvider)
}
override func open() {
- refreshHookStatus()
+ refreshSettingsState()
super.open()
}
@@ -32,7 +38,9 @@ final class SettingsWindowController: HostingWindowController {
let hostingController = NSHostingController(
rootView: AppSettingsView(
codexHookSettings: codexHookSettings,
- globalHotKeySettings: globalHotKeySettings
+ cloudSyncSettings: cloudSyncSettings,
+ globalHotKeySettings: globalHotKeySettings,
+ onICloudSyncChanged: onICloudSyncChanged
)
.environmentObject(viewModel)
.environmentObject(appUpdater)
@@ -67,8 +75,9 @@ final class SettingsWindowController: HostingWindowController {
static let minimumContentSize = NSSize(width: 420, height: 240)
}
- private func refreshHookStatus() {
+ private func refreshSettingsState() {
codexHookSettings.refresh()
codexHookSettings.verifyInstalledHooks()
+ cloudSyncSettings.refresh()
}
}
diff --git a/CodexBar/Controllers/StatusItemController.swift b/CodexBar/Controllers/StatusItemController.swift
index d55d45a..29fdf49 100644
--- a/CodexBar/Controllers/StatusItemController.swift
+++ b/CodexBar/Controllers/StatusItemController.swift
@@ -9,6 +9,7 @@ final class CodexBarAppDelegate: NSObject, NSApplicationDelegate {
lazy var viewModel = CodexStatusViewModel(service: codexStatusService)
let workflowStatsViewModel = WorkflowStatsViewModel()
lazy var codexHookSettings = CodexHookSettings(codexStatusService: codexStatusService)
+ let cloudSyncSettings = WorkflowSyncSettings()
let globalHotKeySettings = GlobalHotKeySettings()
let appUpdater = AppUpdater()
@@ -19,6 +20,7 @@ final class CodexBarAppDelegate: NSObject, NSApplicationDelegate {
viewModel: viewModel,
workflowStatsViewModel: workflowStatsViewModel,
codexHookSettings: codexHookSettings,
+ cloudSyncSettings: cloudSyncSettings,
globalHotKeySettings: globalHotKeySettings,
appUpdater: appUpdater
)
@@ -37,6 +39,7 @@ private final class StatusItemController: NSObject {
private let viewModel: CodexStatusViewModel
private let workflowStatsViewModel: WorkflowStatsViewModel
private let codexHookSettings: CodexHookSettings
+ private let cloudSyncSettings: WorkflowSyncSettings
private let globalHotKeySettings: GlobalHotKeySettings
private let appUpdater: AppUpdater
private let statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength)
@@ -56,9 +59,12 @@ private final class StatusItemController: NSObject {
viewModel: viewModel,
appUpdater: appUpdater,
codexHookSettings: codexHookSettings,
+ cloudSyncSettings: cloudSyncSettings,
globalHotKeySettings: globalHotKeySettings
) { [weak self] in
self?.statusItem.button?.window?.screen
+ } onICloudSyncChanged: { [weak self] in
+ self?.workflowStatsViewModel.refresh(performMaintenance: true)
}
private lazy var logWindowController = LogWindowController { [weak self] in
@@ -98,12 +104,14 @@ private final class StatusItemController: NSObject {
viewModel: CodexStatusViewModel,
workflowStatsViewModel: WorkflowStatsViewModel,
codexHookSettings: CodexHookSettings,
+ cloudSyncSettings: WorkflowSyncSettings,
globalHotKeySettings: GlobalHotKeySettings,
appUpdater: AppUpdater
) {
self.viewModel = viewModel
self.workflowStatsViewModel = workflowStatsViewModel
self.codexHookSettings = codexHookSettings
+ self.cloudSyncSettings = cloudSyncSettings
self.globalHotKeySettings = globalHotKeySettings
self.appUpdater = appUpdater
super.init()
diff --git a/CodexBar/Models/CodexWorkflowStatsModels.swift b/CodexBar/Models/CodexWorkflowStatsModels.swift
index 20a001c..20cf929 100644
--- a/CodexBar/Models/CodexWorkflowStatsModels.swift
+++ b/CodexBar/Models/CodexWorkflowStatsModels.swift
@@ -161,6 +161,24 @@ nonisolated struct WorkflowDailyStats: Equatable, Identifiable {
startDate
}
+ init(
+ startDate: String,
+ sessionCount: Int,
+ turnCount: Int,
+ toolCallCount: Int,
+ permissionRequestCount: Int,
+ contextCompactionCount: Int,
+ subagentCount: Int
+ ) {
+ self.startDate = startDate
+ self.sessionCount = sessionCount
+ self.turnCount = turnCount
+ self.toolCallCount = toolCallCount
+ self.permissionRequestCount = permissionRequestCount
+ self.contextCompactionCount = contextCompactionCount
+ self.subagentCount = subagentCount
+ }
+
static func empty(startDate: String) -> WorkflowDailyStats {
WorkflowDailyStats(
startDate: startDate,
@@ -172,6 +190,39 @@ nonisolated struct WorkflowDailyStats: Equatable, Identifiable {
subagentCount: 0
)
}
+
+ init(
+ startDate: String,
+ sessionCount: Int,
+ turnCount: Int,
+ preToolUseCount: Int,
+ postToolUseCount: Int,
+ permissionRequestCount: Int,
+ preCompactCount: Int,
+ postCompactCount: Int,
+ subagentStartCount: Int,
+ subagentStopCount: Int
+ ) {
+ self.startDate = startDate
+ self.sessionCount = sessionCount
+ self.turnCount = turnCount
+ toolCallCount = max(preToolUseCount, postToolUseCount)
+ self.permissionRequestCount = permissionRequestCount
+ contextCompactionCount = max(preCompactCount, postCompactCount)
+ subagentCount = max(subagentStartCount, subagentStopCount)
+ }
+
+ func adding(_ other: WorkflowDailyStats) -> WorkflowDailyStats {
+ WorkflowDailyStats(
+ startDate: startDate,
+ sessionCount: sessionCount + other.sessionCount,
+ turnCount: turnCount + other.turnCount,
+ toolCallCount: toolCallCount + other.toolCallCount,
+ permissionRequestCount: permissionRequestCount + other.permissionRequestCount,
+ contextCompactionCount: contextCompactionCount + other.contextCompactionCount,
+ subagentCount: subagentCount + other.subagentCount
+ )
+ }
}
/// WorkflowStatsService 发布给 UI 的近端快照
@@ -193,6 +244,27 @@ nonisolated struct WorkflowStatsSnapshot: Equatable {
.sorted { $0.startDate < $1.startDate }
}
+ init(
+ localAggregates: [WorkflowDailyAggregate],
+ cloudRecords: [WorkflowCloudDailyRecord],
+ currentDeviceId: String?,
+ generatedAt: Date = Date()
+ ) {
+ self.generatedAt = generatedAt
+
+ var statsByDate = [String: WorkflowDailyStats]()
+ localAggregates
+ .map(\.stats)
+ .forEach { Self.merge($0, into: &statsByDate) }
+
+ cloudRecords
+ .filter { $0.deviceId != currentDeviceId }
+ .map(\.daily.stats)
+ .forEach { Self.merge($0, into: &statsByDate) }
+
+ dailyStats = statsByDate.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
@@ -210,6 +282,17 @@ nonisolated struct WorkflowStatsSnapshot: Equatable {
}
}
}
+
+ private static func merge(
+ _ stats: WorkflowDailyStats,
+ into statsByDate: inout [String: WorkflowDailyStats]
+ ) {
+ if let existing = statsByDate[stats.startDate] {
+ statsByDate[stats.startDate] = existing.adding(stats)
+ } else {
+ statsByDate[stats.startDate] = stats
+ }
+ }
}
/// 聚合时保留 Set 缓存, 避免同一会话或轮次重复计数
@@ -346,20 +429,17 @@ nonisolated struct WorkflowDailyAggregate: Codable, Equatable, Identifiable {
}
var stats: WorkflowDailyStats {
- let sessionTotal = resolvedSessionCount
- let turnTotal = resolvedTurnCount
- let toolCallCount = max(preToolUseCount, postToolUseCount)
- let contextCompactionCount = max(preCompactCount, postCompactCount)
- let subagentCount = max(subagentStartCount, subagentStopCount)
-
- return WorkflowDailyStats(
+ WorkflowDailyStats(
startDate: date,
- sessionCount: sessionTotal,
- turnCount: turnTotal,
- toolCallCount: toolCallCount,
+ sessionCount: resolvedSessionCount,
+ turnCount: resolvedTurnCount,
+ preToolUseCount: preToolUseCount,
+ postToolUseCount: postToolUseCount,
permissionRequestCount: permissionRequestCount,
- contextCompactionCount: contextCompactionCount,
- subagentCount: subagentCount
+ preCompactCount: preCompactCount,
+ postCompactCount: postCompactCount,
+ subagentStartCount: subagentStartCount,
+ subagentStopCount: subagentStopCount
)
}
@@ -416,6 +496,41 @@ nonisolated struct WorkflowDailyAggregate: Codable, Equatable, Identifiable {
return WorkflowStatsJSON.lineData(fields)
}
+ var cloudAggregate: WorkflowCloudDailyAggregate {
+ WorkflowCloudDailyAggregate(
+ date: date,
+ eventCount: eventCount,
+ sessionStartCount: sessionStartCount,
+ stopCount: stopCount,
+ preToolUseCount: preToolUseCount,
+ postToolUseCount: postToolUseCount,
+ permissionRequestCount: permissionRequestCount,
+ preCompactCount: preCompactCount,
+ postCompactCount: postCompactCount,
+ subagentStartCount: subagentStartCount,
+ subagentStopCount: subagentStopCount,
+ sessionCount: cloudSessionCount,
+ turnCount: cloudTurnCount,
+ projectCounts: projectCounts
+ )
+ }
+
+ private var cloudSessionCount: Int? {
+ sessionCount ?? Self.nonEmptyIdentifierCount(sessionIds)
+ }
+
+ private var cloudTurnCount: Int? {
+ turnCount ?? Self.nonEmptyIdentifierCount(turnIds)
+ }
+
+ private static func nonEmptyIdentifierCount(_ identifiers: [String]?) -> Int? {
+ guard let identifiers, !identifiers.isEmpty else {
+ return nil
+ }
+
+ return Set(identifiers).count
+ }
+
private static func append(
_ identifier: String,
to identifiers: inout [String]?,
@@ -458,3 +573,79 @@ nonisolated struct WorkflowDailyAggregate: Codable, Equatable, Identifiable {
case turnIds
}
}
+
+/// iCloud 中保存的脱敏每日聚合行: 对应 daily.jsonl 但不包含 sessionIds / turnIds
+nonisolated struct WorkflowCloudDailyAggregate: Codable, Equatable, Identifiable {
+ let date: String
+ var eventCount: Int
+ var sessionStartCount: Int
+ var stopCount: Int
+ var preToolUseCount: Int
+ var postToolUseCount: Int
+ var permissionRequestCount: Int
+ var preCompactCount: Int
+ var postCompactCount: Int
+ var subagentStartCount: Int
+ var subagentStopCount: Int
+ var sessionCount: Int?
+ var turnCount: Int?
+ var projectCounts: [String: Int]
+
+ var id: String {
+ date
+ }
+
+ var stats: WorkflowDailyStats {
+ WorkflowDailyStats(
+ startDate: date,
+ sessionCount: sessionCount ?? sessionStartCount,
+ turnCount: turnCount ?? stopCount,
+ preToolUseCount: preToolUseCount,
+ postToolUseCount: postToolUseCount,
+ permissionRequestCount: permissionRequestCount,
+ preCompactCount: preCompactCount,
+ postCompactCount: postCompactCount,
+ subagentStartCount: subagentStartCount,
+ subagentStopCount: subagentStopCount
+ )
+ }
+
+ 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)
+ ]
+
+ return WorkflowStatsJSON.lineData(fields)
+ }
+}
+
+nonisolated struct WorkflowCloudDailyRecord: Codable, Equatable, Identifiable {
+ let deviceId: String
+ let daily: WorkflowCloudDailyAggregate
+ var updatedAt: Date?
+
+ var id: String {
+ Self.id(deviceId: deviceId, date: daily.date)
+ }
+
+ var date: String {
+ daily.date
+ }
+
+ static func id(deviceId: String, date: String) -> String {
+ "\(deviceId)|\(date)"
+ }
+}
diff --git a/CodexBar/Resources/CodexBar.entitlements b/CodexBar/Resources/CodexBar.entitlements
new file mode 100644
index 0000000..bd04f32
--- /dev/null
+++ b/CodexBar/Resources/CodexBar.entitlements
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+ <key>com.apple.developer.icloud-container-identifiers</key>
+ <array>
+ <string>iCloud.app.zabrian.codexbar</string>
+ </array>
+ <key>com.apple.developer.icloud-services</key>
+ <array>
+ <string>CloudKit</string>
+ </array>
+</dict>
+</plist>
diff --git a/CodexBar/Services/Settings/WorkflowSyncSettings.swift b/CodexBar/Services/Settings/WorkflowSyncSettings.swift
new file mode 100644
index 0000000..a2a98e4
--- /dev/null
+++ b/CodexBar/Services/Settings/WorkflowSyncSettings.swift
@@ -0,0 +1,165 @@
+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 lastUploadAt: Date?
+ @Published private(set) var iCloudAvailability = WorkflowSyncAvailability.unknown
+
+ private let defaults: UserDefaults
+ private var cancellables = Set<AnyCancellable>()
+ private var accountStatusTask: Task<Void, Never>?
+ private var accountStatusGeneration = 0
+
+ init(defaults: UserDefaults = .standard) {
+ self.defaults = defaults
+ isEnabled = defaults.bool(forKey: Self.enabledKey)
+ lastUploadAt = Self.loadLastUploadAt()
+ observeSyncNotifications()
+ refreshICloudAvailability()
+ }
+
+ deinit {
+ accountStatusTask?.cancel()
+ }
+
+ func refresh() {
+ isEnabled = defaults.bool(forKey: Self.enabledKey)
+ lastUploadAt = Self.loadLastUploadAt()
+ refreshICloudAvailability()
+ }
+
+ func setEnabled(_ enabled: Bool) {
+ guard !enabled || iCloudAvailability.isAvailable else {
+ return
+ }
+
+ defaults.set(enabled, forKey: Self.enabledKey)
+ if enabled {
+ defaults.set(true, forKey: Self.needsBackfillKey)
+ }
+ isEnabled = enabled
+ lastUploadAt = Self.loadLastUploadAt()
+ }
+
+ var isICloudAvailable: Bool {
+ iCloudAvailability.isAvailable
+ }
+
+ var unavailableMessage: String? {
+ iCloudAvailability.isUnavailable ? "iCloud 不可用" : nil
+ }
+
+ var lastUploadAtText: String? {
+ guard let lastUploadAt else {
+ return nil
+ }
+ return Self.lastUploadAtFormatter.string(from: lastUploadAt)
+ }
+
+ nonisolated static func isEnabled(defaults: UserDefaults = .standard) -> Bool {
+ defaults.bool(forKey: enabledKey)
+ }
+
+ nonisolated static func needsBackfill(defaults: UserDefaults = .standard) -> Bool {
+ defaults.bool(forKey: needsBackfillKey)
+ }
+
+ nonisolated static func clearBackfillRequest(defaults: UserDefaults = .standard) {
+ defaults.set(false, forKey: needsBackfillKey)
+ }
+
+ private func observeSyncNotifications() {
+ NotificationCenter.default.publisher(for: .workflowStatsICloudSyncDidStart)
+ .sink { [weak self] _ in
+ Task { @MainActor in
+ self?.isSyncing = true
+ }
+ }
+ .store(in: &cancellables)
+
+ NotificationCenter.default.publisher(for: .workflowStatsICloudSyncDidFinish)
+ .sink { [weak self] _ in
+ Task { @MainActor in
+ self?.isSyncing = false
+ self?.lastUploadAt = Self.loadLastUploadAt()
+ }
+ }
+ .store(in: &cancellables)
+ }
+
+ private func refreshICloudAvailability() {
+ accountStatusGeneration += 1
+ let generation = accountStatusGeneration
+
+ accountStatusTask?.cancel()
+ accountStatusTask = Task { @MainActor [weak self] in
+ let isAvailable = await Self.queryICloudAvailability()
+ guard let self,
+ !Task.isCancelled,
+ generation == accountStatusGeneration else {
+ return
+ }
+
+ iCloudAvailability = isAvailable ? .available : .unavailable
+ if !isAvailable {
+ isSyncing = false
+ }
+ }
+ }
+
+ private nonisolated static func queryICloudAvailability() async -> Bool {
+ await withCheckedContinuation { continuation in
+ CKContainer.default().accountStatus { status, _ in
+ continuation.resume(returning: status == .available)
+ }
+ }
+ }
+
+ private nonisolated static func loadLastUploadAt() -> Date? {
+ let stateURL = WorkflowStatsStorage.iCloudSyncDirectoryURL()
+ .appendingPathComponent("state.json", isDirectory: false)
+ guard let data = try? Data(contentsOf: stateURL), !data.isEmpty,
+ let state = try? JSONDecoder().decode(LocalSyncState.self, from: data) else {
+ return nil
+ }
+ return state.lastUploadAt
+ }
+
+ private static let lastUploadAtFormatter: DateFormatter = {
+ let formatter = DateFormatter()
+ formatter.locale = Locale(identifier: "en_US_POSIX")
+ formatter.dateFormat = "yyyy-MM-dd HH:mm:ss"
+ return formatter
+ }()
+
+ private nonisolated static let enabledKey = "WorkflowiCloudSync.isEnabled"
+ private nonisolated static let needsBackfillKey = "WorkflowiCloudSync.needsBackfill"
+
+ private nonisolated struct LocalSyncState: Decodable {
+ let lastUploadAt: Date?
+ }
+}
+
+nonisolated enum WorkflowSyncAvailability: Equatable {
+ case unknown
+ case available
+ case unavailable
+
+ var isAvailable: Bool {
+ self == .available
+ }
+
+ var isUnavailable: Bool {
+ self == .unavailable
+ }
+}
+
+extension Notification.Name {
+ nonisolated static let workflowStatsICloudSyncDidStart = Notification.Name("CodexBar.workflowStatsICloudSyncDidStart")
+ nonisolated static let workflowStatsICloudSyncDidFinish = Notification.Name("CodexBar.workflowStatsICloudSyncDidFinish")
+}
diff --git a/CodexBar/Services/WorkflowStats/WorkflowStatsService.swift b/CodexBar/Services/WorkflowStats/WorkflowStatsService.swift
index ac8e3bf..8a347e4 100644
--- a/CodexBar/Services/WorkflowStats/WorkflowStatsService.swift
+++ b/CodexBar/Services/WorkflowStats/WorkflowStatsService.swift
@@ -6,26 +6,44 @@ import Foundation
actor WorkflowStatsService {
private let eventsDirectoryURL: URL
private let dailyLogURL: URL
+ private let cloudSyncService: WorkflowSyncService
private static let eventReadChunkSize = 64 * 1024
init(
eventsDirectoryURL: URL = WorkflowStatsStorage.eventsDirectoryURL(),
- dailyLogURL: URL = WorkflowStatsStorage.dailyURL()
+ dailyLogURL: URL = WorkflowStatsStorage.dailyURL(),
+ cloudSyncService: WorkflowSyncService = WorkflowSyncService()
) {
self.eventsDirectoryURL = eventsDirectoryURL
self.dailyLogURL = dailyLogURL
+ self.cloudSyncService = cloudSyncService
}
- func loadSnapshot(performMaintenance: Bool = false) -> WorkflowStatsSnapshot {
+ func loadSnapshot(performMaintenance: Bool = false) async -> WorkflowStatsSnapshot {
+ var changedDates = Set<String>()
if performMaintenance {
- performMaintenanceIfNeeded()
+ changedDates = performMaintenanceIfNeeded()
}
- if let aggregates = loadDailyAggregates(), !aggregates.isEmpty {
- return WorkflowStatsSnapshot(dailyAggregates: aggregates)
+ let aggregates = loadDailyAggregates() ?? []
+ let cloudSnapshot: WorkflowSyncSnapshot = if performMaintenance {
+ await cloudSyncService.synchronizeIfEnabled(
+ localAggregates: aggregates,
+ changedDates: changedDates
+ )
+ } else {
+ await cloudSyncService.snapshotFromCacheIfEnabled()
+ }
+
+ guard !aggregates.isEmpty || !cloudSnapshot.records.isEmpty else {
+ return .empty
}
- return .empty
+ return WorkflowStatsSnapshot(
+ localAggregates: aggregates,
+ cloudRecords: cloudSnapshot.records,
+ currentDeviceId: cloudSnapshot.currentDeviceId
+ )
}
private func loadDailyAggregates() -> [WorkflowDailyAggregate]? {
@@ -41,25 +59,29 @@ actor WorkflowStatsService {
return WorkflowDailyAggregate.normalized(aggregates: aggregates)
}
- private func performMaintenanceIfNeeded() {
+ private func performMaintenanceIfNeeded() -> Set<String> {
+ let beforePayloads = cloudPayloadByDate()
+
do {
let tasks = try prepareMaintenanceTasks()
- guard !tasks.isEmpty else {
- return
- }
-
- for task in tasks {
- do {
- let result = try buildDailyAggregate(for: task)
- try commit(result)
- } catch {
- markDirty(task.dateKey)
- }
- }
-
+ perform(tasks)
+ try normalizeDailyAggregatesIfNeeded()
try pruneExpiredEventFiles()
} catch {
- return
+ return []
+ }
+
+ return changedCloudPayloadDates(before: beforePayloads, after: cloudPayloadByDate())
+ }
+
+ private func perform(_ tasks: [WorkflowStatsMaintenanceTask]) {
+ for task in tasks {
+ do {
+ let result = try buildDailyAggregate(for: task)
+ try commit(result)
+ } catch {
+ markDirty(task.dateKey)
+ }
}
}
@@ -389,6 +411,49 @@ actor WorkflowStatsService {
try data.write(to: dailyLogURL, options: .atomic)
}
+ private func normalizeDailyAggregatesIfNeeded() throws {
+ guard let data = try? Data(contentsOf: dailyLogURL), !data.isEmpty else {
+ return
+ }
+
+ let decodeResult = JSONLines.decodeWithFailures(WorkflowDailyAggregate.self, from: data)
+ guard decodeResult.failedLineCount == 0 else {
+ return
+ }
+
+ let normalizedAggregates = WorkflowDailyAggregate.normalized(aggregates: decodeResult.values)
+ let normalizedData = try WorkflowDailyAggregate.encodeJSONLines(normalizedAggregates)
+ guard normalizedData != data else {
+ return
+ }
+
+ try FileManager.default.createDirectory(
+ at: dailyLogURL.deletingLastPathComponent(),
+ withIntermediateDirectories: true
+ )
+ try normalizedData.write(to: dailyLogURL, options: .atomic)
+ }
+
+ private func cloudPayloadByDate() -> [String: String] {
+ loadDailyAggregatesWithFailures().values.reduce(into: [String: String]()) { result, aggregate in
+ guard let data = try? aggregate.cloudAggregate.jsonLineData() else {
+ return
+ }
+
+ result[aggregate.date] = data.base64EncodedString()
+ }
+ }
+
+ private func changedCloudPayloadDates(
+ before: [String: String],
+ after: [String: String]
+ ) -> Set<String> {
+ let allDates = Set(before.keys).union(after.keys)
+ return Set(allDates.filter {
+ before[$0] != after[$0]
+ })
+ }
+
private func commitMaintenanceState(_ result: WorkflowStatsMaintenanceResult) throws {
try WorkflowStatsStorage.withExclusiveLock {
let currentSize = WorkflowStatsStorage.fileSize(at: eventLogURL(for: result.dateKey))
@@ -497,6 +562,11 @@ nonisolated enum WorkflowStatsStorage {
.appendingPathComponent("maintenance.json", isDirectory: false)
}
+ static func iCloudSyncDirectoryURL() -> URL {
+ directoryURL()
+ .appendingPathComponent("iCloudSync", isDirectory: true)
+ }
+
static func directoryURL() -> URL {
let applicationSupportURL = FileManager.default.urls(
for: .applicationSupportDirectory,
diff --git a/CodexBar/Services/WorkflowStats/WorkflowSyncService.swift b/CodexBar/Services/WorkflowStats/WorkflowSyncService.swift
new file mode 100644
index 0000000..daa5f5c
--- /dev/null
+++ b/CodexBar/Services/WorkflowStats/WorkflowSyncService.swift
@@ -0,0 +1,922 @@
+import CloudKit
+import CryptoKit
+import Foundation
+import IOKit
+import Security
+
+/// 将本机 daily.jsonl 的脱敏聚合行同步到 CloudKit private database
+actor WorkflowSyncService {
+ private let database: CKDatabase
+ private let fileManager: FileManager
+ private let directoryURL: URL
+
+ init(
+ container: CKContainer = .default(),
+ fileManager: FileManager = .default,
+ directoryURL: URL = WorkflowStatsStorage.iCloudSyncDirectoryURL()
+ ) {
+ database = container.privateCloudDatabase
+ self.fileManager = fileManager
+ self.directoryURL = directoryURL
+ }
+
+ func snapshotFromCacheIfEnabled() -> WorkflowSyncSnapshot {
+ guard WorkflowSyncSettings.isEnabled() else {
+ return .disabled
+ }
+
+ let state = loadState()
+ return snapshot(from: state)
+ }
+
+ func synchronizeIfEnabled(
+ localAggregates: [WorkflowDailyAggregate],
+ changedDates: Set<String>
+ ) async -> WorkflowSyncSnapshot {
+ guard WorkflowSyncSettings.isEnabled() else {
+ return .disabled
+ }
+
+ Self.postSyncNotification(.workflowStatsICloudSyncDidStart)
+ defer {
+ Self.postSyncNotification(.workflowStatsICloudSyncDidFinish)
+ }
+
+ var state = loadState()
+
+ do {
+ try await ensureSyncZoneExists()
+ let deviceId = try await resolveCurrentDeviceId()
+ resetStateIfDeviceChanged(deviceId, state: &state)
+
+ let localByDate = Self.cloudAggregatesByDate(localAggregates)
+ let forceBackfill = WorkflowSyncSettings.needsBackfill()
+ try await uploadChangedAggregates(
+ localByDate: localByDate,
+ changedDates: changedDates,
+ forceBackfill: forceBackfill,
+ state: &state
+ )
+
+ if forceBackfill, backfillCompleted(localByDate: localByDate, state: state) {
+ WorkflowSyncSettings.clearBackfillRequest()
+ }
+
+ try await refreshCacheFromCloud(currentDeviceId: deviceId)
+ try await pruneCurrentDeviceRecordsIfNeeded(deviceId: deviceId, state: &state)
+ try saveState(state)
+ } catch {
+ try? saveState(state)
+ }
+
+ let latestState = loadState()
+ return snapshot(from: latestState)
+ }
+
+ private func resetStateIfDeviceChanged(
+ _ deviceId: String,
+ state: inout WorkflowSyncState
+ ) {
+ guard state.deviceId != deviceId else {
+ return
+ }
+
+ state = WorkflowSyncState(deviceId: deviceId)
+ try? saveCachedRecords([])
+ try? fileManager.removeItem(at: cursorURL)
+ }
+
+ private static func cloudAggregatesByDate(
+ _ aggregates: [WorkflowDailyAggregate]
+ ) -> [String: WorkflowCloudDailyAggregate] {
+ aggregates.reduce(into: [String: WorkflowCloudDailyAggregate]()) { result, aggregate in
+ result[aggregate.date] = aggregate.cloudAggregate
+ }
+ }
+
+ private func backfillCompleted(
+ localByDate: [String: WorkflowCloudDailyAggregate],
+ state: WorkflowSyncState
+ ) -> Bool {
+ localByDate.allSatisfy { date, aggregate in
+ (try? hash(for: aggregate)) == state.hashByDate[date]
+ }
+ }
+
+ private func snapshot(from state: WorkflowSyncState) -> WorkflowSyncSnapshot {
+ WorkflowSyncSnapshot(
+ currentDeviceId: state.deviceId,
+ records: state.deviceId == nil
+ ? []
+ : Self.filteredRetained(records: loadCachedRecords(), excluding: state.deviceId)
+ )
+ }
+}
+
+private extension WorkflowSyncService {
+ typealias PendingUpload = (date: String, aggregate: WorkflowCloudDailyAggregate, hash: String)
+ typealias PendingRecord = (upload: PendingUpload, recordID: CKRecord.ID)
+ typealias UploadedHash = (date: String, hash: String)
+
+ enum Metrics {
+ static let cloudSchemaVersion = 1
+ static let syncZoneName = "CodexBarZone"
+ static let saltByteCount = 32
+ static let recordFetchLimit = 200
+ static let queryFetchLimit = 200
+ static let uploadBatchSize = 25
+ static let uploadTimeBudget: TimeInterval = 20
+ }
+
+ enum RecordTypes {
+ static let metadata = "CodexBarSyncMetadata"
+ static let dailyAggregate = "CodexBarDailyAggregate"
+ }
+
+ enum FieldKeys {
+ static let salt = "salt"
+ static let schemaVersion = "schemaVersion"
+ static let deviceId = "deviceId"
+ static let date = "date"
+ static let eventCount = "eventCount"
+ static let sessionStartCount = "sessionStartCount"
+ static let stopCount = "stopCount"
+ static let preToolUseCount = "preToolUseCount"
+ static let postToolUseCount = "postToolUseCount"
+ static let permissionRequestCount = "permissionRequestCount"
+ static let preCompactCount = "preCompactCount"
+ static let postCompactCount = "postCompactCount"
+ static let subagentStartCount = "subagentStartCount"
+ static let subagentStopCount = "subagentStopCount"
+ static let sessionCount = "sessionCount"
+ static let turnCount = "turnCount"
+ static let projectCounts = "projectCounts"
+ static let updatedAt = "updatedAt"
+ }
+
+ static let accountSaltRecordName = "accountSalt"
+
+ var syncZoneID: CKRecordZone.ID {
+ CKRecordZone.ID(zoneName: Metrics.syncZoneName, ownerName: CKCurrentUserDefaultName)
+ }
+
+ var accountSaltRecordID: CKRecord.ID {
+ CKRecord.ID(recordName: Self.accountSaltRecordName, zoneID: syncZoneID)
+ }
+
+ var stateURL: URL {
+ directoryURL.appendingPathComponent("state.json", isDirectory: false)
+ }
+
+ var cacheURL: URL {
+ directoryURL.appendingPathComponent("cache.jsonl", isDirectory: false)
+ }
+
+ var cursorURL: URL {
+ directoryURL.appendingPathComponent("cursor.data", isDirectory: false)
+ }
+
+ func uploadChangedAggregates(
+ localByDate: [String: WorkflowCloudDailyAggregate],
+ changedDates: Set<String>,
+ forceBackfill: Bool,
+ state: inout WorkflowSyncState
+ ) async throws {
+ guard let deviceId = state.deviceId else {
+ return
+ }
+
+ let pendingUploads = try makePendingUploads(
+ for: uploadCandidateDates(
+ localByDate: localByDate,
+ changedDates: changedDates,
+ forceBackfill: forceBackfill,
+ state: state
+ ),
+ localByDate: localByDate,
+ state: state
+ )
+ guard !pendingUploads.isEmpty else {
+ return
+ }
+
+ let deadline = Date().addingTimeInterval(Metrics.uploadTimeBudget)
+
+ for batchStart in stride(from: 0, to: pendingUploads.count, by: Metrics.uploadBatchSize) {
+ guard !Task.isCancelled, Date() < deadline else {
+ break
+ }
+
+ 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
+ }
+
+ try applyUploadedHashes(uploadedBatch, to: &state)
+ }
+ }
+
+ func uploadCandidateDates(
+ localByDate: [String: WorkflowCloudDailyAggregate],
+ changedDates: Set<String>,
+ forceBackfill: Bool,
+ state: WorkflowSyncState
+ ) -> Set<String> {
+ var candidateDates = Set(changedDates)
+ candidateDates.formUnion(localByDate.keys.filter { state.hashByDate[$0] == nil })
+
+ if forceBackfill {
+ candidateDates.formUnion(localByDate.keys)
+ }
+
+ return candidateDates
+ }
+
+ func applyUploadedHashes(
+ _ uploadedBatch: [UploadedHash],
+ to state: inout WorkflowSyncState
+ ) throws {
+ guard !uploadedBatch.isEmpty else {
+ return
+ }
+
+ for uploaded in uploadedBatch {
+ state.hashByDate[uploaded.date] = uploaded.hash
+ }
+
+ state.lastUploadAt = Date()
+ try saveState(state)
+ }
+
+ func makePendingUploads(
+ for candidateDates: Set<String>,
+ localByDate: [String: WorkflowCloudDailyAggregate],
+ state: WorkflowSyncState
+ ) throws -> [PendingUpload] {
+ try candidateDates.compactMap { date in
+ guard let aggregate = localByDate[date] else {
+ return nil
+ }
+
+ let hash = try hash(for: aggregate)
+ guard state.hashByDate[date] != hash else {
+ return nil
+ }
+
+ return (date: date, aggregate: aggregate, hash: hash)
+ }
+ .sorted { $0.date < $1.date }
+ }
+
+ func uploadAggregateBatch(
+ _ pendingUploads: [PendingUpload],
+ deviceId: String
+ ) async throws -> [UploadedHash] {
+ let pendingRecords: [PendingRecord] = pendingUploads.map {
+ (upload: $0, recordID: recordID(deviceId: deviceId, date: $0.date))
+ }
+ let recordIDs = pendingRecords.map(\.recordID)
+ let existingRecords = try await database.records(for: recordIDs)
+ let records = pendingRecords.map { pendingRecord in
+ let (_, aggregate, _) = pendingRecord.upload
+ let existingRecord: CKRecord? = if case let .success(record) = existingRecords[pendingRecord.recordID] {
+ record
+ } else {
+ nil
+ }
+
+ let record = existingRecord ?? CKRecord(
+ recordType: RecordTypes.dailyAggregate,
+ recordID: pendingRecord.recordID
+ )
+ apply(aggregate, deviceId: deviceId, to: record)
+ return record
+ }
+
+ let result = try await database.modifyRecords(
+ saving: records,
+ deleting: [],
+ savePolicy: .changedKeys,
+ atomically: false
+ )
+
+ return pendingRecords.compactMap { pendingRecord in
+ let (date, _, hash) = pendingRecord.upload
+ if case .success = result.saveResults[pendingRecord.recordID] {
+ return (date: date, hash: hash)
+ }
+ return nil
+ }
+ }
+
+ func refreshCacheFromCloud(currentDeviceId: String) async throws {
+ guard let token = try loadCursor() else {
+ try await rebuildCacheFromCloud(currentDeviceId: currentDeviceId)
+ return
+ }
+
+ do {
+ try await applyZoneChangesToCache(
+ since: token,
+ cachedRecords: loadCachedRecords(),
+ currentDeviceId: currentDeviceId
+ )
+ } catch {
+ try await rebuildCacheFromCloud(currentDeviceId: currentDeviceId)
+ }
+ }
+
+ func applyZoneChangesToCache(
+ since initialToken: CKServerChangeToken?,
+ cachedRecords: [WorkflowCloudDailyRecord],
+ currentDeviceId: String
+ ) async throws {
+ var cacheByID = Self.recordsByID(
+ records: cachedRecords,
+ excluding: currentDeviceId
+ )
+ var token: CKServerChangeToken? = initialToken
+ var latestToken: CKServerChangeToken?
+ var moreComing = true
+
+ while moreComing {
+ let result = try await database.recordZoneChanges(
+ inZoneWith: syncZoneID,
+ since: token,
+ desiredKeys: nil,
+ resultsLimit: Metrics.recordFetchLimit
+ )
+
+ mergeChangedRecords(
+ result.modificationResultsByID.values,
+ currentDeviceId: currentDeviceId,
+ into: &cacheByID
+ )
+ removeDeletedRecords(result.deletions, from: &cacheByID)
+
+ token = result.changeToken
+ latestToken = result.changeToken
+ moreComing = result.moreComing
+ }
+
+ try saveCachedRecords(
+ Self.filteredRetained(
+ records: Array(cacheByID.values),
+ excluding: currentDeviceId
+ )
+ )
+ if let latestToken {
+ try saveCursor(latestToken)
+ }
+ }
+
+ func rebuildCacheFromCloud(currentDeviceId: String) async throws {
+ let cloudRecords = try await fetchAllCloudDailyRecords()
+ let retainedRecords = Self.filteredRetained(records: cloudRecords, excluding: currentDeviceId)
+ try saveCachedRecords(retainedRecords)
+ await establishCursorBaseline(cachedRecords: retainedRecords, currentDeviceId: currentDeviceId)
+ }
+
+ func fetchAllCloudDailyRecords() async throws -> [WorkflowCloudDailyRecord] {
+ var records = [WorkflowCloudDailyRecord]()
+ var queryCursor: CKQueryOperation.Cursor?
+
+ let query = CKQuery(
+ recordType: RecordTypes.dailyAggregate,
+ predicate: NSPredicate(format: "TRUEPREDICATE")
+ )
+ query.sortDescriptors = [
+ NSSortDescriptor(key: FieldKeys.deviceId, ascending: true),
+ NSSortDescriptor(key: FieldKeys.date, ascending: true)
+ ]
+
+ let firstPage = try await database.records(
+ matching: query,
+ inZoneWith: syncZoneID,
+ desiredKeys: nil,
+ resultsLimit: Metrics.queryFetchLimit
+ )
+ records.append(contentsOf: Self.cloudDailyRecords(from: firstPage.matchResults))
+ queryCursor = firstPage.queryCursor
+
+ while let cursor = queryCursor {
+ let page = try await database.records(
+ continuingMatchFrom: cursor,
+ desiredKeys: nil,
+ resultsLimit: Metrics.queryFetchLimit
+ )
+ records.append(contentsOf: Self.cloudDailyRecords(from: page.matchResults))
+ queryCursor = page.queryCursor
+ }
+
+ return records
+ }
+
+ func establishCursorBaseline(
+ cachedRecords: [WorkflowCloudDailyRecord],
+ currentDeviceId: String
+ ) async {
+ do {
+ try await applyZoneChangesToCache(
+ since: nil,
+ cachedRecords: cachedRecords,
+ currentDeviceId: currentDeviceId
+ )
+ } catch {
+ try? fileManager.removeItem(at: cursorURL)
+ }
+ }
+
+ func mergeChangedRecords(
+ _ modificationResults: Dictionary<CKRecord.ID, Result<CKDatabase.RecordZoneChange.Modification, Error>>.Values,
+ currentDeviceId: String,
+ into cacheByID: inout [String: WorkflowCloudDailyRecord]
+ ) {
+ for modificationResult in modificationResults {
+ guard case let .success(modification) = modificationResult,
+ let record = Self.cloudDailyRecord(from: modification.record) else {
+ continue
+ }
+
+ guard record.deviceId != currentDeviceId else {
+ cacheByID.removeValue(forKey: record.id)
+ continue
+ }
+
+ cacheByID[record.id] = record
+ }
+ }
+
+ func removeDeletedRecords(
+ _ deletions: [CKDatabase.RecordZoneChange.Deletion],
+ from cacheByID: inout [String: WorkflowCloudDailyRecord]
+ ) {
+ for deletion in deletions where deletion.recordType == RecordTypes.dailyAggregate {
+ if let cacheID = cacheID(fromRecordName: deletion.recordID.recordName) {
+ cacheByID.removeValue(forKey: cacheID)
+ }
+ }
+ }
+
+ func pruneCurrentDeviceRecordsIfNeeded(
+ deviceId: String,
+ state: inout WorkflowSyncState
+ ) async throws {
+ let today = WorkflowStatsStorage.dateKey(for: Date())
+ guard state.lastPrunedDate != today else {
+ return
+ }
+
+ let cutoffKey = WorkflowStatsStorage.dateKey(for: WorkflowStatsStorage.retentionCutoffDate())
+ let expiredDates = state.hashByDate.keys
+ .filter { $0 < cutoffKey }
+ .sorted()
+
+ guard !expiredDates.isEmpty else {
+ state.lastPrunedDate = today
+ return
+ }
+
+ let result = try await database.modifyRecords(
+ saving: [],
+ deleting: expiredDates.map { recordID(deviceId: deviceId, date: $0) },
+ savePolicy: .changedKeys,
+ atomically: false
+ )
+
+ let allDeleted = expiredDates.allSatisfy { date in
+ let recordID = recordID(deviceId: deviceId, date: date)
+ return Self.isSuccessfulDeleteResult(result.deleteResults[recordID])
+ }
+
+ if allDeleted {
+ for date in expiredDates {
+ state.hashByDate.removeValue(forKey: date)
+ }
+ state.lastPrunedDate = today
+ }
+ }
+
+ func resolveCurrentDeviceId() async throws -> String {
+ let salt = try await accountSalt()
+ let uuid = try Self.ioPlatformUUID()
+ let mac = HMAC<SHA256>.authenticationCode(
+ for: Data(uuid.utf8),
+ using: SymmetricKey(data: salt)
+ )
+ return Self.hexString(Data(mac))
+ }
+
+ func accountSalt() async throws -> Data {
+ let recordID = accountSaltRecordID
+ if let salt = try await fetchAccountSalt(recordID) {
+ return salt
+ }
+
+ return try await createAccountSalt(recordID)
+ }
+
+ func fetchAccountSalt(_ recordID: CKRecord.ID) async throws -> Data? {
+ let result = try await database.records(for: [recordID])
+ return Self.accountSalt(from: result[recordID])
+ }
+
+ func createAccountSalt(_ recordID: CKRecord.ID) async throws -> Data {
+ 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
+
+ do {
+ let saveResult = try await database.modifyRecords(
+ saving: [record],
+ deleting: [],
+ savePolicy: .ifServerRecordUnchanged,
+ atomically: true
+ )
+ if case .success = saveResult.saveResults[recordID] {
+ return salt
+ }
+ } catch let error as CKError where error.code == .serverRecordChanged || error.code == .constraintViolation {
+ if let salt = try await fetchAccountSalt(recordID) {
+ return salt
+ }
+ }
+
+ throw WorkflowSyncError.missingAccountSalt
+ }
+
+ func ensureSyncZoneExists() async throws {
+ guard try await syncZoneExists() == false else {
+ return
+ }
+
+ let zone = CKRecordZone(zoneID: syncZoneID)
+ let result = try await database.modifyRecordZones(saving: [zone], deleting: [])
+
+ if case let .failure(error) = result.saveResults[syncZoneID] {
+ throw error
+ }
+ }
+
+ func syncZoneExists() async throws -> Bool {
+ do {
+ _ = try await database.recordZone(for: syncZoneID)
+ return true
+ } catch let error as CKError where error.code == .zoneNotFound || error.code == .unknownItem {
+ return false
+ }
+ }
+
+ func apply(
+ _ aggregate: WorkflowCloudDailyAggregate,
+ deviceId: String,
+ to record: CKRecord
+ ) {
+ record[FieldKeys.schemaVersion] = Metrics.cloudSchemaVersion as CKRecordValue
+ record[FieldKeys.deviceId] = deviceId as CKRecordValue
+ record[FieldKeys.date] = aggregate.date as CKRecordValue
+ record[FieldKeys.eventCount] = aggregate.eventCount as CKRecordValue
+ record[FieldKeys.sessionStartCount] = aggregate.sessionStartCount as CKRecordValue
+ record[FieldKeys.stopCount] = aggregate.stopCount as CKRecordValue
+ record[FieldKeys.preToolUseCount] = aggregate.preToolUseCount as CKRecordValue
+ record[FieldKeys.postToolUseCount] = aggregate.postToolUseCount as CKRecordValue
+ record[FieldKeys.permissionRequestCount] = aggregate.permissionRequestCount as CKRecordValue
+ record[FieldKeys.preCompactCount] = aggregate.preCompactCount as CKRecordValue
+ record[FieldKeys.postCompactCount] = aggregate.postCompactCount as CKRecordValue
+ record[FieldKeys.subagentStartCount] = aggregate.subagentStartCount as CKRecordValue
+ record[FieldKeys.subagentStopCount] = aggregate.subagentStopCount as CKRecordValue
+ record[FieldKeys.sessionCount] = aggregate.sessionCount as CKRecordValue?
+ record[FieldKeys.turnCount] = aggregate.turnCount as CKRecordValue?
+ record[FieldKeys.projectCounts] = Self.projectCountsData(aggregate.projectCounts) as CKRecordValue
+ record[FieldKeys.updatedAt] = Date() as CKRecordValue
+ }
+
+ func recordID(deviceId: String, date: String) -> CKRecord.ID {
+ CKRecord.ID(recordName: recordName(deviceId: deviceId, date: date), zoneID: syncZoneID)
+ }
+
+ func recordName(deviceId: String, date: String) -> String {
+ "\(deviceId)_\(date)"
+ }
+
+ func cacheID(fromRecordName recordName: String) -> String? {
+ guard let separatorIndex = recordName.lastIndex(of: "_") else {
+ return nil
+ }
+
+ let deviceId = String(recordName[..<separatorIndex])
+ let date = String(recordName[recordName.index(after: separatorIndex)...])
+ guard WorkflowStatsStorage.isValidDateKey(date), !deviceId.isEmpty else {
+ return nil
+ }
+
+ return WorkflowCloudDailyRecord.id(deviceId: deviceId, date: date)
+ }
+
+ func hash(for aggregate: WorkflowCloudDailyAggregate) throws -> String {
+ let digest = try SHA256.hash(data: aggregate.jsonLineData())
+ return Self.hexString(Data(digest))
+ }
+
+ nonisolated static func postSyncNotification(_ name: Notification.Name) {
+ Task { @MainActor in
+ NotificationCenter.default.post(name: name, object: nil)
+ }
+ }
+}
+
+private extension WorkflowSyncService {
+ func loadState() -> WorkflowSyncState {
+ guard let data = try? Data(contentsOf: stateURL), !data.isEmpty,
+ let state = try? JSONDecoder().decode(WorkflowSyncState.self, from: data) else {
+ return WorkflowSyncState()
+ }
+ guard state.schema == WorkflowSyncState.currentSchema else {
+ return WorkflowSyncState()
+ }
+ return state
+ }
+
+ func saveState(_ state: WorkflowSyncState) throws {
+ try fileManager.createDirectory(at: directoryURL, withIntermediateDirectories: true)
+ let encoder = JSONEncoder()
+ encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]
+ let data = try encoder.encode(state)
+ try data.write(to: stateURL, options: .atomic)
+ }
+
+ func loadCachedRecords() -> [WorkflowCloudDailyRecord] {
+ guard let data = try? Data(contentsOf: cacheURL), !data.isEmpty else {
+ return []
+ }
+
+ return JSONLines.decode(from: data)
+ }
+
+ func saveCachedRecords(_ records: [WorkflowCloudDailyRecord]) throws {
+ try fileManager.createDirectory(at: directoryURL, withIntermediateDirectories: true)
+
+ let encoder = JSONEncoder()
+ encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]
+ let data = try records
+ .sorted { lhs, rhs in
+ if lhs.deviceId == rhs.deviceId {
+ return lhs.date < rhs.date
+ }
+ return lhs.deviceId < rhs.deviceId
+ }
+ .reduce(into: Data()) { result, record in
+ try result.append(encoder.encode(record))
+ result.append(0x0A)
+ }
+ try data.write(to: cacheURL, options: .atomic)
+ }
+
+ func loadCursor() throws -> CKServerChangeToken? {
+ guard let data = try? Data(contentsOf: cursorURL), !data.isEmpty else {
+ return nil
+ }
+
+ return try NSKeyedUnarchiver.unarchivedObject(
+ ofClass: CKServerChangeToken.self,
+ from: data
+ )
+ }
+
+ func saveCursor(_ token: CKServerChangeToken) throws {
+ try fileManager.createDirectory(at: directoryURL, withIntermediateDirectories: true)
+ let data = try NSKeyedArchiver.archivedData(
+ withRootObject: token,
+ requiringSecureCoding: true
+ )
+ try data.write(to: cursorURL, options: .atomic)
+ }
+}
+
+private extension WorkflowSyncService {
+ static func cloudDailyRecords(
+ from matchResults: [(CKRecord.ID, Result<CKRecord, Error>)]
+ ) -> [WorkflowCloudDailyRecord] {
+ matchResults.compactMap { _, result in
+ guard case let .success(record) = result else {
+ return nil
+ }
+
+ return cloudDailyRecord(from: record)
+ }
+ }
+
+ static func cloudDailyRecord(from record: CKRecord) -> WorkflowCloudDailyRecord? {
+ guard record.recordType == RecordTypes.dailyAggregate,
+ let deviceId = record[FieldKeys.deviceId] as? String,
+ let date = record[FieldKeys.date] as? String,
+ WorkflowStatsStorage.isValidDateKey(date) else {
+ return nil
+ }
+
+ let aggregate = WorkflowCloudDailyAggregate(
+ date: date,
+ eventCount: intValue(record[FieldKeys.eventCount]),
+ sessionStartCount: intValue(record[FieldKeys.sessionStartCount]),
+ stopCount: intValue(record[FieldKeys.stopCount]),
+ preToolUseCount: intValue(record[FieldKeys.preToolUseCount]),
+ postToolUseCount: intValue(record[FieldKeys.postToolUseCount]),
+ permissionRequestCount: intValue(record[FieldKeys.permissionRequestCount]),
+ preCompactCount: intValue(record[FieldKeys.preCompactCount]),
+ postCompactCount: intValue(record[FieldKeys.postCompactCount]),
+ subagentStartCount: intValue(record[FieldKeys.subagentStartCount]),
+ subagentStopCount: intValue(record[FieldKeys.subagentStopCount]),
+ sessionCount: optionalIntValue(record[FieldKeys.sessionCount]),
+ turnCount: optionalIntValue(record[FieldKeys.turnCount]),
+ projectCounts: projectCounts(from: record[FieldKeys.projectCounts])
+ )
+
+ return WorkflowCloudDailyRecord(
+ deviceId: deviceId,
+ daily: aggregate,
+ updatedAt: record[FieldKeys.updatedAt] as? Date ?? record.modificationDate
+ )
+ }
+
+ static func accountSalt(from result: Result<CKRecord, Error>?) -> Data? {
+ guard case let .success(record) = result,
+ let salt = record[FieldKeys.salt] as? Data,
+ salt.count == Metrics.saltByteCount else {
+ return nil
+ }
+
+ return salt
+ }
+
+ static func filteredRetained(
+ records: [WorkflowCloudDailyRecord],
+ excluding currentDeviceId: String? = nil
+ ) -> [WorkflowCloudDailyRecord] {
+ let cutoffKey = WorkflowStatsStorage.dateKey(for: WorkflowStatsStorage.retentionCutoffDate())
+ return records.filter { record in
+ guard record.date >= cutoffKey else {
+ return false
+ }
+
+ return currentDeviceId.map { record.deviceId != $0 } ?? true
+ }
+ }
+
+ static func recordsByID(
+ records: [WorkflowCloudDailyRecord],
+ excluding currentDeviceId: String? = nil
+ ) -> [String: WorkflowCloudDailyRecord] {
+ filteredRetained(records: records, excluding: currentDeviceId)
+ .reduce(into: [String: WorkflowCloudDailyRecord]()) { result, record in
+ result[record.id] = record
+ }
+ }
+
+ static func isSuccessfulDeleteResult(_ result: Result<Void, Error>?) -> Bool {
+ switch result {
+ case .success:
+ true
+ case let .failure(error as CKError) where error.code == .unknownItem:
+ true
+ case .failure, .none:
+ false
+ }
+ }
+
+ static func intValue(_ value: CKRecordValue?) -> Int {
+ optionalIntValue(value) ?? 0
+ }
+
+ static func optionalIntValue(_ value: CKRecordValue?) -> Int? {
+ if let number = value as? NSNumber {
+ return number.intValue
+ }
+ if let value = value as? Int {
+ return value
+ }
+ return nil
+ }
+
+ static func projectCounts(from value: CKRecordValue?) -> [String: Int] {
+ guard let data = value as? Data,
+ let counts = try? JSONDecoder().decode([String: Int].self, from: data) else {
+ return [:]
+ }
+ return counts
+ }
+
+ static func projectCountsData(_ counts: [String: Int]) -> Data {
+ let encoder = JSONEncoder()
+ encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]
+ return (try? encoder.encode(counts)) ?? Data("{}".utf8)
+ }
+
+ static func randomSalt() throws -> Data {
+ var bytes = [UInt8](repeating: 0, count: Metrics.saltByteCount)
+ let status = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)
+ guard status == errSecSuccess else {
+ throw WorkflowSyncError.randomSaltFailed
+ }
+ return Data(bytes)
+ }
+
+ static func ioPlatformUUID() throws -> String {
+ let service = IOServiceGetMatchingService(
+ kIOMainPortDefault,
+ IOServiceMatching("IOPlatformExpertDevice")
+ )
+ guard service != 0 else {
+ throw WorkflowSyncError.missingIOPlatformUUID
+ }
+ defer {
+ IOObjectRelease(service)
+ }
+
+ guard let value = IORegistryEntryCreateCFProperty(
+ service,
+ "IOPlatformUUID" as CFString,
+ kCFAllocatorDefault,
+ 0
+ )?.takeRetainedValue() as? String,
+ !value.isEmpty else {
+ throw WorkflowSyncError.missingIOPlatformUUID
+ }
+
+ return value
+ }
+
+ static func hexString(_ data: Data) -> String {
+ data.map { String(format: "%02x", $0) }.joined()
+ }
+}
+
+nonisolated struct WorkflowSyncSnapshot: Equatable {
+ let currentDeviceId: String?
+ let records: [WorkflowCloudDailyRecord]
+
+ static let disabled = WorkflowSyncSnapshot(currentDeviceId: nil, records: [])
+}
+
+private nonisolated struct WorkflowSyncState: Codable, Equatable {
+ static let currentSchema = 1
+
+ var schema: Int
+ var deviceId: String?
+ var hashByDate: [String: String]
+ var lastUploadAt: Date?
+ var lastPrunedDate: String?
+
+ init(
+ schema: Int = Self.currentSchema,
+ deviceId: String? = nil,
+ hashByDate: [String: String] = [:],
+ lastUploadAt: Date? = nil,
+ lastPrunedDate: String? = nil
+ ) {
+ self.schema = schema
+ self.deviceId = deviceId
+ self.hashByDate = hashByDate
+ self.lastUploadAt = lastUploadAt
+ self.lastPrunedDate = lastPrunedDate
+ }
+
+ init(from decoder: Decoder) throws {
+ let container = try decoder.container(keyedBy: CodingKeys.self)
+
+ schema = try container.decodeIfPresent(Int.self, forKey: .schema) ?? Self.currentSchema
+ deviceId = try container.decodeIfPresent(String.self, forKey: .deviceId)
+ hashByDate = try container.decodeIfPresent([String: String].self, forKey: .hashByDate)
+ ?? [:]
+ lastUploadAt = try container.decodeIfPresent(Date.self, forKey: .lastUploadAt)
+ lastPrunedDate = try container.decodeIfPresent(String.self, forKey: .lastPrunedDate)
+ }
+
+ func encode(to encoder: Encoder) throws {
+ var container = encoder.container(keyedBy: CodingKeys.self)
+ try container.encode(schema, forKey: .schema)
+ try container.encodeIfPresent(deviceId, forKey: .deviceId)
+ try container.encode(hashByDate, forKey: .hashByDate)
+ try container.encodeIfPresent(lastUploadAt, forKey: .lastUploadAt)
+ try container.encodeIfPresent(lastPrunedDate, forKey: .lastPrunedDate)
+ }
+
+ private enum CodingKeys: String, CodingKey {
+ case schema
+ case deviceId
+ case hashByDate
+ case lastUploadAt
+ case lastPrunedDate
+ }
+}
+
+private nonisolated enum WorkflowSyncError: Error {
+ case missingAccountSalt
+ case missingIOPlatformUUID
+ case randomSaltFailed
+}
diff --git a/CodexBar/Views/Menu/UsageHeatmap.swift b/CodexBar/Views/Menu/UsageHeatmap.swift
index 547f30c..126beb3 100644
--- a/CodexBar/Views/Menu/UsageHeatmap.swift
+++ b/CodexBar/Views/Menu/UsageHeatmap.swift
@@ -1,4 +1,5 @@
import AppKit
+import Combine
import SwiftUI
/// hover 详情面板需要的完整上下文, 包括屏幕坐标和峰值 token
@@ -549,10 +550,23 @@ private final class HeatmapScreenFrameReportingView: NSView {
}
/// 热力图 hover 详情内容, Hook 开启时额外展示工作流统计
+@MainActor
+final class UsageHeatmapDayDetailModel: ObservableObject {
+ @Published var context: UsageHeatmapHoverContext
+
+ init(context: UsageHeatmapHoverContext) {
+ self.context = context
+ }
+}
+
struct UsageHeatmapDayDetailView: View {
- let context: UsageHeatmapHoverContext
+ @ObservedObject var model: UsageHeatmapDayDetailModel
@Environment(\.colorScheme) private var colorScheme
+ private var context: UsageHeatmapHoverContext {
+ model.context
+ }
+
var body: some View {
let panelSize = Self.panelSize(showsWorkflowStats: context.showsWorkflowStats)
@@ -714,22 +728,29 @@ struct UsageHeatmapDayDetailView: View {
.layoutPriority(1)
}
- @ViewBuilder
private var tokenText: some View {
- if let tokenCount = context.day.tokenCount {
- TokenCountText(
- tokens: tokenCount,
- font: tokenFont,
- reservedNumericWidth: Metrics.tokenMinimumWidth,
- reservedUnitWidth: Metrics.tokenUnitWidth
- )
- .foregroundStyle(Color.codexLabel)
- } else {
- Text("--")
- .font(tokenFont)
+ ZStack(alignment: .trailing) {
+ if let tokenCount = context.day.tokenCount {
+ TokenCountText(
+ tokens: tokenCount,
+ font: tokenFont,
+ reservedNumericWidth: Metrics.tokenMinimumWidth,
+ reservedUnitWidth: Metrics.tokenUnitWidth
+ )
.foregroundStyle(Color.codexLabel)
- .contentTransition(.opacity)
+ .transition(.opacity)
+ } else {
+ Text("--")
+ .font(tokenFont)
+ .foregroundStyle(Color.codexLabel)
+ .transition(.opacity)
+ }
}
+ .frame(
+ width: Metrics.tokenMinimumWidth + Metrics.tokenUnitWidth,
+ alignment: .trailing
+ )
+ .animation(Metrics.statusAnimation, value: context.day.tokenCount == nil)
}
private var dateFont: Font {
diff --git a/CodexBar/Views/Settings/AppSettingsView.swift b/CodexBar/Views/Settings/AppSettingsView.swift
index b678f93..3f7fff7 100644
--- a/CodexBar/Views/Settings/AppSettingsView.swift
+++ b/CodexBar/Views/Settings/AppSettingsView.swift
@@ -1,14 +1,16 @@
import AppKit
import SwiftUI
-/// 设置窗口根视图, 汇总启动项, 更新, Hook, 快捷键和版本信息
+/// 设置窗口根视图, 汇总启动项、更新、Hook、跨设备同步、快捷键和版本信息
struct AppSettingsView: View {
@EnvironmentObject private var statusViewModel: CodexStatusViewModel
@EnvironmentObject private var appUpdater: AppUpdater
@StateObject private var loginItemSettings = LoginItemSettings()
@StateObject private var codexVersions = CodexCLIVersionViewModel()
@ObservedObject var codexHookSettings: CodexHookSettings
+ @ObservedObject var cloudSyncSettings: WorkflowSyncSettings
@ObservedObject var globalHotKeySettings: GlobalHotKeySettings
+ let onICloudSyncChanged: () -> Void
var body: some View {
VStack(alignment: .leading, spacing: Metrics.sectionSpacing) {
@@ -19,6 +21,8 @@ struct AppSettingsView: View {
LiquidGlassDivider()
codexHookRow
LiquidGlassDivider()
+ iCloudSyncRow
+ LiquidGlassDivider()
hotKeyRow
LiquidGlassDivider()
codexVersionSection
@@ -41,6 +45,11 @@ struct AppSettingsView: View {
.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(
@@ -54,11 +63,13 @@ struct AppSettingsView: View {
)
.onAppear {
loginItemSettings.refresh()
+ cloudSyncSettings.refresh()
appUpdater.refreshAutomaticCheckSetting()
refreshCodexVersionSection()
}
.onReceive(NotificationCenter.default.publisher(for: NSApplication.didBecomeActiveNotification)) { _ in
codexHookSettings.refresh()
+ cloudSyncSettings.refresh()
codexHookSettings.verifyInstalledHooks()
refreshCodexVersionSection()
}
@@ -118,20 +129,73 @@ private extension AppSettingsView {
)
if let message = codexHookSettings.errorMessage {
- HStack(alignment: .top, spacing: 10) {
- Color.clear
- .frame(width: Metrics.iconWidth)
+ SettingsCaptionMessageRow(message: message)
+ .transition(.opacity)
+ }
+ }
+ }
+
+ var iCloudSyncRow: some View {
+ let state = iCloudSyncRowState
+ let lastUploadAtText = cloudSyncSettings.lastUploadAtText
+
+ return VStack(alignment: .leading, spacing: 4) {
+ SettingsToggleRow(
+ icon: "icloud",
+ title: "跨设备同步",
+ isOn: Binding(
+ get: { state.isActive },
+ set: { enabled in
+ guard codexHookSettings.isEnabled, state.isICloudAvailable else {
+ return
+ }
+ cloudSyncSettings.setEnabled(enabled)
+ onICloudSyncChanged()
+ }
+ ),
+ isEnabled: state.canToggle
+ )
- Text(message)
+ if let message = cloudSyncSettings.unavailableMessage {
+ SettingsCaptionMessageRow(message: message)
+ .transition(.opacity)
+ } else if state.shouldShowUploadStatus(lastUploadAtText: lastUploadAtText) {
+ SettingsIndentedRow {
+ Text("最近上传")
.font(.caption)
- .foregroundStyle(.red)
- .fixedSize(horizontal: false, vertical: true)
+ .foregroundStyle(.secondary)
+
+ Spacer(minLength: 8)
+
+ if cloudSyncSettings.isSyncing {
+ ProgressView()
+ .controlSize(.small)
+ .scaleEffect(0.7)
+ .frame(width: 16, height: 16)
+ .help("正在同步")
+ } else if let lastUploadAtText {
+ Text(lastUploadAtText)
+ .font(.caption.monospacedDigit())
+ .foregroundStyle(.secondary)
+ .lineLimit(1)
+ .contentTransition(.opacity)
+ }
}
.transition(.opacity)
}
}
}
+ var iCloudSyncRowState: ICloudSyncRowState {
+ ICloudSyncRowState(
+ isHookEnabled: codexHookSettings.isEnabled,
+ isHookUpdating: codexHookSettings.isUpdating,
+ isSyncEnabled: cloudSyncSettings.isEnabled,
+ isICloudAvailable: cloudSyncSettings.isICloudAvailable,
+ isSyncing: cloudSyncSettings.isSyncing
+ )
+ }
+
var versionRow: some View {
let status = versionStatus
@@ -225,3 +289,23 @@ private extension AppSettingsView {
loginItemSettings.errorMessage
}
}
+
+private struct ICloudSyncRowState {
+ let isHookEnabled: Bool
+ let isHookUpdating: Bool
+ let isSyncEnabled: Bool
+ let isICloudAvailable: Bool
+ let isSyncing: Bool
+
+ var isActive: Bool {
+ isHookEnabled && isSyncEnabled && isICloudAvailable
+ }
+
+ var canToggle: Bool {
+ isHookEnabled && !isHookUpdating && isICloudAvailable
+ }
+
+ func shouldShowUploadStatus(lastUploadAtText: String?) -> Bool {
+ isActive && (isSyncing || lastUploadAtText != nil)
+ }
+}
diff --git a/CodexBar/Views/Settings/HotKeyRecorderRow.swift b/CodexBar/Views/Settings/HotKeyRecorderRow.swift
index 9ffcc26..64acbbb 100644
--- a/CodexBar/Views/Settings/HotKeyRecorderRow.swift
+++ b/CodexBar/Views/Settings/HotKeyRecorderRow.swift
@@ -63,7 +63,7 @@ struct HotKeyRecorderRow: View {
}
if let message = settings.errorMessage {
- errorMessageRow(message)
+ SettingsCaptionMessageRow(message: message)
}
}
.onDisappear {
@@ -128,18 +128,6 @@ struct HotKeyRecorderRow: View {
stopRecording()
}
- private func errorMessageRow(_ message: String) -> some View {
- HStack(alignment: .top, spacing: 10) {
- Color.clear
- .frame(width: Metrics.iconWidth)
-
- Text(message)
- .font(.caption)
- .foregroundStyle(.red)
- .fixedSize(horizontal: false, vertical: true)
- }
- }
-
private func iconButton(
systemName: String,
help: String,
diff --git a/CodexBar/Views/Settings/SettingsIndentedRow.swift b/CodexBar/Views/Settings/SettingsIndentedRow.swift
new file mode 100644
index 0000000..c356f0c
--- /dev/null
+++ b/CodexBar/Views/Settings/SettingsIndentedRow.swift
@@ -0,0 +1,32 @@
+import SwiftUI
+
+/// 设置页中与主行标题对齐的缩进辅助行
+struct SettingsIndentedRow<Content: View>: View {
+ var alignment: VerticalAlignment = .center
+ var iconWidth: CGFloat = 18
+ var spacing: CGFloat = 10
+ @ViewBuilder var content: () -> Content
+
+ var body: some View {
+ HStack(alignment: alignment, spacing: spacing) {
+ Color.clear
+ .frame(width: iconWidth)
+
+ content()
+ }
+ }
+}
+
+struct SettingsCaptionMessageRow: View {
+ let message: String
+ var color = Color.red
+
+ var body: some View {
+ SettingsIndentedRow(alignment: .top) {
+ Text(message)
+ .font(.caption)
+ .foregroundStyle(color)
+ .fixedSize(horizontal: false, vertical: true)
+ }
+ }
+}
diff --git a/CodexBar/Views/Shared/LiquidGlassStyle.swift b/CodexBar/Views/Shared/LiquidGlassStyle.swift
index 924ee99..280cfb7 100644
--- a/CodexBar/Views/Shared/LiquidGlassStyle.swift
+++ b/CodexBar/Views/Shared/LiquidGlassStyle.swift
@@ -264,47 +264,48 @@ private struct LiquidGlassCapsule: View {
var body: some View {
Capsule(style: .continuous)
- .fill(baseFill)
+ .fill(fillColor)
.overlay {
- Capsule(style: .continuous)
- .fill(
- LinearGradient(
- colors: [
- .white.opacity(colorScheme == .dark ? 0.18 : 0.36),
- tint.opacity(colorScheme == .dark ? 0.16 : 0.12),
- .clear
- ],
- startPoint: .topLeading,
- endPoint: .bottomTrailing
- )
- )
- .blendMode(.plusLighter)
+ LiquidGlassFrostedTexture(isOuterSurface: false)
+ .clipShape(Capsule(style: .continuous))
+ .opacity(0.55)
}
.overlay {
Capsule(style: .continuous)
- .strokeBorder(.white.opacity(colorScheme == .dark ? 0.22 : 0.34), lineWidth: 0.7)
+ .strokeBorder(borderColor, lineWidth: 0.8)
}
.overlay {
- LiquidGlassFrostedTexture(isOuterSurface: false)
- .clipShape(Capsule(style: .continuous))
+ Capsule(style: .continuous)
+ .strokeBorder(innerRimColor, lineWidth: 0.45)
+ .padding(0.8)
+ }
+ .overlay(alignment: .top) {
+ Capsule(style: .continuous)
+ .fill(topHighlightColor)
+ .frame(height: 1)
+ .padding(.horizontal, 7)
+ .padding(.top, 1.5)
}
}
- private var baseFill: LinearGradient {
- LinearGradient(
- colors: [
- baseColor.opacity(colorScheme == .dark ? 0.76 : 0.70),
- baseColor.opacity(colorScheme == .dark ? 0.58 : 0.52)
- ],
- startPoint: .topLeading,
- endPoint: .bottomTrailing
- )
+ private var fillColor: Color {
+ colorScheme == .dark
+ ? Color(red: 0.18, green: 0.20, blue: 0.22)
+ : Color(red: 0.94, green: 0.96, blue: 0.98)
}
- private var baseColor: Color {
+ private var borderColor: Color {
colorScheme == .dark
- ? Color(red: 0.16, green: 0.18, blue: 0.20)
- : Color.white
+ ? tint.opacity(0.34)
+ : tint.opacity(0.26)
+ }
+
+ private var innerRimColor: Color {
+ .white.opacity(colorScheme == .dark ? 0.12 : 0.42)
+ }
+
+ private var topHighlightColor: Color {
+ .white.opacity(colorScheme == .dark ? 0.10 : 0.30)
}
}
diff --git a/Docs/CodexHook.md b/Docs/CodexHook.md
index 39aae78..a8d9d0c 100644
--- a/Docs/CodexHook.md
+++ b/Docs/CodexHook.md
@@ -149,6 +149,73 @@ 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`。
+
+CloudKit 中每个 iCloud 账号会保存一条账号级 salt:
+
+```text
+zoneName = CodexBarZone
+recordType = CodexBarSyncMetadata
+recordName = accountSalt
+salt = 32 bytes
+```
+
+设备 ID 只用于区分同一 iCloud 账号下的不同设备:
+
+```text
+deviceId = HMAC_SHA256(accountSalt, IOPlatformUUID)
+```
+
+CodexBar 不上传原始 `IOPlatformUUID`。同一台 Mac 在同一 iCloud 账号下重装 App 或系统后通常得到同一个 `deviceId`;切换 iCloud 账号后会进入另一个 CloudKit private database,并用该账号的 salt 派生另一个 `deviceId`。
+
+iCloud 同步上传的是 `daily.jsonl` 单日聚合行的内存副本,去掉:
+
+```text
+sessionIds, turnIds
+```
+
+其余字段保持原值同步,包括 `projectCounts`。如果本地仍保留 `sessionIds` / `turnIds`,上传副本会把去重后的 `sessionIds.count` / `turnIds.count` 写入 `sessionCount` / `turnCount`,但不会上传 ID 本身;只有既没有压缩后的 count、也没有本地 ID 时,这两个字段才可能为 `null`。脱敏只发生在上传副本上,不会写回本地 `daily.jsonl`,因此最近 3 天本地仍保留 `sessionIds` / `turnIds` 用于本机精确去重。
+
+每台设备每天一条记录:
+
+```text
+zoneName = CodexBarZone
+recordType = CodexBarDailyAggregate
+recordName = <deviceId>_<yyyy-MM-dd>
+```
+
+Hook 子进程不访问网络。主 App 在工作流统计维护刷新后对本次可能变化的日期生成脱敏 daily 副本,计算稳定 hash,并和本地同步状态比较。只有 hash 变化的日期才 upsert 到 CloudKit;上传成功后才更新本地 hash,失败则下次刷新继续重试。
+
+上传按日期稳定排序并分批执行。每轮同步最多处理 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
+```
+
+- `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 缓存。
+
+展示合并规则:
+
+```text
+最终展示 = 本机 daily.jsonl + iCloud 缓存中的其他设备记录
+```
+
+`cache.jsonl` 写入前必须过滤本机自己的 CloudKit 记录,否则本机会把本地 daily 和自己上传的云端副本重复相加。本机数据永远以本地 `daily.jsonl` 为准;云端只补其他设备。热力图详情的 6 个工作流指标按每台设备各自 daily 口径先生成展示值,再按日期相加;`projectCounts` 按项目名逐项相加。
+
+iCloud 也按最近 210 天保留。每天第一次工作流刷新时,当前设备会删除 `deviceId == 本机 deviceId` 且早于保留窗口的 CloudKit 记录;其他设备记录不由本机清理。展示侧始终忽略最近 210 天外的缓存记录。
+
## 统计口径
`events/YYYY-MM-DD.jsonl` 是统计源。Hook 写入时已经按事件自身 `timestamp` 选择对应本地日期文件;重建或增量更新 `daily.jsonl` 时,维护流程按当前处理的文件日期生成当天聚合,再按每行的 `event` 名称归类。`event` 归类时会去掉 `_` 和 `-` 并转小写,例如 `PreToolUse`、`pre_tool_use`、`pre-tool-use` 都会归为 `pretooluse`。
diff --git a/Docs/CrossDeviceSync.md b/Docs/CrossDeviceSync.md
new file mode 100644
index 0000000..aad192b
--- /dev/null
+++ b/Docs/CrossDeviceSync.md
@@ -0,0 +1,390 @@
+# 跨设备同步
+
+本文档记录设置页「跨设备同步」的完整链路。当前实现只同步 Codex Hook 产生的工作流统计每日聚合,不是整个 App 的通用 iCloud 同步。
+
+## 同步范围
+
+会同步:
+
+- `daily.jsonl` 中每一天的工作流统计聚合副本
+- 会话总数、对话轮次、子智能体、工具调用、权限请求、上下文压缩等计数字段
+- `eventCount` 和 `projectCounts`
+
+不会同步:
+
+- Codex 账号、额度、token 用量
+- app-server 请求日志
+- Codex auth 文件、refresh token、stderr 或原始 RPC 响应
+- 原始 Hook 事件 `events/YYYY-MM-DD.jsonl`
+- `sessionIds` 和 `turnIds`
+- CodexBar 设置项、快捷键、日志窗口内容
+
+同步目标是当前 macOS 登录的 iCloud 账号的 CloudKit private database。数据不会跨 iCloud 账号迁移或合并;切换 iCloud 账号后会进入另一个 private database。
+
+## 代码入口
+
+| 文件 | 职责 |
+| --- | --- |
+| `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` | 自动刷新时触发维护同步;开关变化后立即触发一次维护刷新 |
+
+## 本地状态
+
+跨设备同步相关本地状态都在工作流统计目录下:
+
+```text
+~/Library/Application Support/CodexBar/HookEvents/
+```
+
+同步子目录:
+
+```text
+iCloudSync/state.json
+iCloudSync/cache.jsonl
+iCloudSync/cursor.data
+```
+
+各文件职责:
+
+| 文件 | 内容 |
+| --- | --- |
+| `state.json` | 本机同步状态,包括 `deviceId`、每天上传过的 hash、`lastUploadAt`、`lastPrunedDate` |
+| `cache.jsonl` | 从 iCloud 拉取到的其他设备脱敏 daily 记录,一行一条;不保存当前设备自己的云端副本 |
+| `cursor.data` | CloudKit custom zone `CodexBarZone` 的 `CKServerChangeToken`,用于下次增量拉取 |
+
+`state.json` 的逻辑结构:
+
+```json
+{
+ "schema": 1,
+ "deviceId": "<当前设备在当前 iCloud 账号下的匿名设备 ID>",
+ "hashByDate": {
+ "2026-06-25": "<脱敏 daily 聚合的 SHA256>"
+ },
+ "lastUploadAt": "2026-06-25T10:20:30Z",
+ "lastPrunedDate": "2026-06-25"
+}
+```
+
+设置开关存在 `UserDefaults`:
+
+| Key | 含义 |
+| --- | --- |
+| `WorkflowiCloudSync.isEnabled` | 用户是否开启过跨设备同步 |
+| `WorkflowiCloudSync.needsBackfill` | 是否需要对本机现有 daily 数据做一次补传 |
+
+关闭跨设备同步只会把 `WorkflowiCloudSync.isEnabled` 写成 `false`,不会删除本地 `state.json`、`cache.jsonl`、`cursor.data`,也不会删除 CloudKit 中已有记录。
+
+## CloudKit 数据结构
+
+CloudKit 使用默认 container 的 private database。CodexBar 自己创建和维护的记录都保存在 custom zone `CodexBarZone`;不会向 CloudKit `_defaultZone` 写入同步数据。
+
+账号级 metadata 记录保存在 custom zone `CodexBarZone`:
+
+```text
+zoneName = CodexBarZone
+recordType = CodexBarSyncMetadata
+recordName = accountSalt
+fields:
+ schemaVersion: Int
+ salt: Data(32 bytes)
+```
+
+每天的工作流统计记录保存在 custom zone `CodexBarZone`:
+
+```text
+recordType = CodexBarDailyAggregate
+recordName = <deviceId>_<yyyy-MM-dd>
+fields:
+ schemaVersion: Int
+ deviceId: String
+ date: String
+ eventCount: Int
+ sessionStartCount: Int
+ stopCount: Int
+ preToolUseCount: Int
+ postToolUseCount: Int
+ permissionRequestCount: Int
+ preCompactCount: Int
+ postCompactCount: Int
+ subagentStartCount: Int
+ subagentStopCount: Int
+ sessionCount: Int?
+ turnCount: Int?
+ projectCounts: Data(JSON object)
+ updatedAt: Date
+```
+
+`projectCounts` 会保留本机聚合中的项目显示名。项目显示名通常是 `cwd` 的最后一层目录名;如果路径最后一层为空,代码会回退到完整路径字符串。
+
+## 设备标识
+
+设备标识不直接上传 `IOPlatformUUID`。同步服务会先在当前 iCloud private database 中读取或创建 32 字节账号级 salt,然后计算:
+
+```text
+deviceId = HMAC_SHA256(accountSalt, IOPlatformUUID)
+```
+
+这个设计的效果:
+
+- 同一台 Mac 在同一个 iCloud 账号下通常得到同一个 `deviceId`
+- 同一台 Mac 切换 iCloud 账号后会得到不同的 `deviceId`
+- CloudKit 中不会保存原始 `IOPlatformUUID`
+
+如果本地 `state.json` 的 `schema` 和当前代码不一致,服务会丢弃旧同步状态。下一轮同步会按当前设备重新写入 `state.json`,清空旧 `cache.jsonl` / `cursor.data`,再从 `CodexBarZone` 重建缓存。当前调试阶段 iCloud sync state schema 保持为 `1`。
+
+如果本地 `state.json` 中的 `deviceId` 和当前解析出的 `deviceId` 不一致,说明 iCloud 账号或账号级 salt 已变化。此时同步服务会重置本地同步状态,清空 `cache.jsonl`,并删除 `cursor.data`,然后按新账号重新同步。
+
+## 设置页行为
+
+设置页打开时会刷新:
+
+- Codex Hook 本地配置状态
+- `hooks/list` 验证结果
+- iCloud account status
+- 最近上传时间
+
+`AppSettingsView.onAppear` 和 App 再次变为 active 时也会刷新 iCloud 可用性。
+
+「跨设备同步」开关可操作的条件:
+
+```text
+Codex Hook 已开启
+Codex Hook 当前没有正在更新
+CKContainer.default().accountStatus == .available
+```
+
+UI 状态:
+
+| 状态 | UI 表现 |
+| --- | --- |
+| iCloud 状态还在检查 | 开关不可操作,暂不显示错误 |
+| iCloud 可用但 Hook 关闭 | 开关不可操作 |
+| iCloud 不可用 | 开关不可操作,下方显示 `iCloud 不可用` |
+| Hook 开启且 iCloud 可用 | 开关可操作 |
+| 同步中 | 开关下方显示 `最近上传` 和小型进度指示 |
+| 有成功上传记录 | 开关下方显示 `最近上传 yyyy-MM-dd HH:mm:ss` |
+
+开启时:
+
+1. `WorkflowSyncSettings.setEnabled(true)` 先确认 iCloud 可用。
+2. 写入 `WorkflowiCloudSync.isEnabled = true`。
+3. 写入 `WorkflowiCloudSync.needsBackfill = true`,要求后续同步补传本机已有 daily 数据。
+4. `StatusItemController` 立即触发 `workflowStatsViewModel.refresh(performMaintenance: true)`。
+
+关闭时:
+
+1. 写入 `WorkflowiCloudSync.isEnabled = false`。
+2. 后续 `WorkflowSyncService` 直接返回 `.disabled`,不再访问 CloudKit。
+3. 本地同步状态、缓存和云端记录保留。
+
+关闭 Codex Hook 不会清空跨设备同步偏好;但因为工作流统计同步只在 Hook 开启时触发,所以 Hook 关闭期间不会继续同步。之后重新开启 Hook 时,如果跨设备同步偏好仍为 true 且 iCloud 可用,同步会恢复。
+
+## 刷新时机
+
+跨设备同步只在工作流统计的维护刷新中执行。核心入口是:
+
+```text
+WorkflowStatsService.loadSnapshot(performMaintenance: true)
+```
+
+两类刷新行为不同:
+
+| 刷新类型 | 是否维护 local daily | 是否访问 CloudKit | 用途 |
+| --- | --- | --- | --- |
+| `performMaintenance: false` | 否 | 否,只读取 `cache.jsonl` | 打开菜单面板时快速展示现有数据 |
+| `performMaintenance: true` | 是 | 是 | 每分钟自动刷新、开关变化后的立即刷新 |
+
+触发维护刷新:
+
+- app-server 自动刷新倒计时重置时,如果 Codex Hook 已开启
+- 用户开启或关闭「跨设备同步」后立即触发一次
+
+Hook 子进程不访问网络。它只把原始事件写入本机 `events/YYYY-MM-DD.jsonl` 并标记 `maintenance.json` 的 pending 日期。真正的 daily 重建和 CloudKit 同步都由主 App 的维护刷新完成。
+
+## 同步主流程
+
+```mermaid
+flowchart TD
+ A["工作流统计维护刷新"] --> B["整理 events 为 daily.jsonl"]
+ B --> C["读取本机 daily 聚合"]
+ C --> D{"跨设备同步已开启?"}
+ D -- "否" --> E["只发布本机快照"]
+ D -- "是" --> Z["确保 CodexBarZone 存在"]
+ Z --> F["读取或创建 accountSalt 并解析 deviceId"]
+ F --> G{"deviceId 是否变化?"}
+ G -- "是" --> H["重置 state/cache/cursor"]
+ G -- "否" --> I["沿用本地同步状态"]
+ H --> J["生成脱敏 daily 副本"]
+ I --> J
+ J --> K["按 hash 判断待上传日期"]
+ K --> L["分批上传到 CloudKit"]
+ L --> M["拉取 CloudKit 增量变化"]
+ M --> N["清理本设备过期云端记录"]
+ N --> O["保存 state 并合并快照"]
+```
+
+同步服务会在开始和结束时发出通知:
+
+```text
+CodexBar.workflowStatsICloudSyncDidStart
+CodexBar.workflowStatsICloudSyncDidFinish
+```
+
+设置页通过这两个通知更新 `isSyncing` 和 `lastUploadAt`。
+
+## 上传数据如何脱敏
+
+本机 `daily.jsonl` 每行是 `WorkflowDailyAggregate`。上传前会转换成 `WorkflowCloudDailyAggregate`:
+
+- 保留各类计数字段
+- 保留 `projectCounts`
+- 不包含 `sessionIds`
+- 不包含 `turnIds`
+- 如果本机还有 `sessionIds`,会把去重数量写入 `sessionCount`
+- 如果本机还有 `turnIds`,会把去重数量写入 `turnCount`
+
+本机 `daily.jsonl` 不会因为上传而被改写。也就是说,最近 3 个本地自然日的 `sessionIds` / `turnIds` 仍然只保存在本机,用于本机精确去重。
+
+## 待上传日期选择
+
+每次同步先构造候选日期:
+
+```text
+候选日期 =
+ 本轮维护后内容发生变化的日期
+ + state.hashByDate 中还没有记录的本机日期
+ + needsBackfill 为 true 时的全部本机日期
+```
+
+对每个候选日期:
+
+1. 找到本机 daily 聚合。
+2. 转换成脱敏 cloud aggregate。
+3. 用固定字段顺序序列化为 JSON line。
+4. 计算 SHA256。
+5. 如果 hash 和 `state.hashByDate[date]` 相同,则跳过。
+6. 否则加入待上传列表。
+
+待上传列表按日期升序排列,保证每次补传顺序稳定。
+
+## 上传节奏和时间预算
+
+为避免每分钟自动刷新被长时间上传拖住,上传有两个限制:
+
+```text
+每批最多 25 天
+每轮最多 20 秒
+```
+
+上传流程:
+
+1. 以 25 天为一批切分待上传列表。
+2. 每批开始前检查 Task 是否取消,以及是否仍在 20 秒预算内。
+3. 先按 record ID 批量读取已有 CloudKit 记录。
+4. 已存在的记录复用后改字段;不存在的记录创建新 `CKRecord`。
+5. 使用 `database.modifyRecords(saving:deleting:savePolicy:.changedKeys, atomically:false)` 保存。
+6. 对保存成功的日期,立即更新 `state.hashByDate[date]`。
+7. 如果本批至少有成功日期,更新 `state.lastUploadAt`,并立刻写回 `state.json`。
+
+如果某批 CloudKit 请求整体抛错,本轮上传停止。已经成功的批次不会回滚,剩余日期留给下一次刷新继续处理。
+
+`needsBackfill` 只有在本机所有 daily 日期的 hash 都已经和 `state.hashByDate` 匹配后才会清除。这样首次开启时即使 20 秒内没有补完,后续每分钟刷新也会继续补传。
+
+## 拉取缓存和游标
+
+上传之后会更新本地 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 的增量变化:
+
+```text
+database.recordZoneChanges(
+ inZoneWith: CodexBarZone,
+ since: cursor,
+ desiredKeys: nil,
+ resultsLimit: 200
+)
+```
+
+处理规则:
+
+- 修改记录: 只接受 `CodexBarDailyAggregate`,转换成 `WorkflowCloudDailyRecord` 后写入内存 cache;如果 `deviceId == 当前设备`, 从 cache 中移除并跳过
+- 删除记录: 如果删除的是 `CodexBarDailyAggregate`,按 record name 解析出 `deviceId` 和 `date`,从 cache 中移除
+- `moreComing == true`: 继续用新的 change token 拉下一页
+- `changeTokenExpired` 或增量拉取失败: 不写入日志窗口,直接 query 全量 `CodexBarDailyAggregate` 重建 `cache.jsonl`
+- 全量重建后的游标基线建立失败: 保留已写入的 `cache.jsonl`, 不保存 `cursor.data`, 下轮刷新继续全量重建并再次尝试建立游标
+
+本地落盘顺序很重要:
+
+1. 先写 `cache.jsonl`
+2. 再写 `cursor.data`
+
+如果 `cache.jsonl` 写入失败,`cursor.data` 不会提前推进。下一轮会重新拉取同一批 CloudKit 变化,避免游标已经前进但缓存没有落盘导致记录丢失。
+
+## 展示合并规则
+
+UI 展示使用 `WorkflowStatsSnapshot`。合并规则是:
+
+```text
+最终展示 = 本机 daily.jsonl + iCloud 缓存中的其他设备记录
+```
+
+`cache.jsonl` 写入前会过滤当前设备自己的 CloudKit 记录,否则本机 daily 和自己上传到云端的副本会重复相加。
+
+同一天多设备数据相加时,会先把每台设备的 daily aggregate 转成 `WorkflowDailyStats`,再按日期求和:
+
+```text
+sessionCount += other.sessionCount
+turnCount += other.turnCount
+toolCallCount += other.toolCallCount
+permissionRequestCount += other.permissionRequestCount
+contextCompactionCount += other.contextCompactionCount
+subagentCount += other.subagentCount
+```
+
+本机数据永远以本机 `daily.jsonl` 为准。iCloud 缓存只补其他设备的数据。
+
+CloudKit 拉取不会单独向 UI 推送新快照;只有当前这次 `WorkflowStatsService` 刷新最终提交结果时,菜单面板和热力图才会看到更新。非维护刷新只读取已有 `cache.jsonl`,不会主动联网。
+
+## 保留和清理
+
+本机工作流统计最多保留最近 210 天。跨设备同步遵循同样窗口:
+
+- 读取缓存时会过滤掉 210 天窗口外的记录
+- 保存 `cache.jsonl` 前也会过滤 210 天窗口外的记录
+- 当前设备每天最多执行一次云端清理
+
+云端清理只删除当前设备自己的过期记录:
+
+```text
+deviceId == 当前 deviceId
+date < retentionCutoffDate
+```
+
+其他设备的记录不会由本机删除。每台设备只负责清理自己上传的过期记录。
+
+当前实现不会因为本机 `daily.jsonl` 删除了某个仍在 210 天窗口内的日期,就主动删除该日期对应的 CloudKit 记录。它会等到该记录超过 210 天保留窗口后再清理。
+
+## 失败和重试
+
+失败处理以不中断工作流统计展示为目标。
+
+| 场景 | 当前行为 |
+| --- | --- |
+| iCloud 未登录或不可用 | 设置页禁用「跨设备同步」,显示 `iCloud 不可用` |
+| 用户尝试在 iCloud 不可用时开启 | `setEnabled(true)` 直接返回,不写入开启状态 |
+| `CodexBarZone` 不存在 | 同步开始时创建 custom zone |
+| CloudKit 上传失败 | 本轮上传停止,已成功批次保留,失败日期下次刷新继续 |
+| CloudKit 增量拉取失败 | 不写入日志窗口,尝试全量重建缓存 |
+| CloudKit 全量重建失败 | 本轮同步失败,保存已有 state,保留已有 cache,后续刷新重试 |
+| 账号 salt 创建冲突 | 重新读取 CloudKit 中已有 salt |
+| 本地 state schema 不匹配 | 丢弃旧 state,按当前 schema 重新同步 |
+| `deviceId` 变化 | 重置本地同步 state/cache/cursor,按当前 iCloud 账号重新同步 |
+| `changeTokenExpired` | 不写入日志窗口,尝试全量重建缓存并建立新的 cursor |
+| `cache.jsonl` 写入失败 | 不保存新 cursor,下一轮重新拉取同一批变化 |
+| 同步失败 | 设置页没有单独错误文案,`最近上传` 不更新 |
+
+同步异常不会清空用户的开启偏好。只要 `WorkflowiCloudSync.isEnabled` 仍为 true、Codex Hook 开启且 iCloud 可用,后续维护刷新会继续重试。
diff --git a/Docs/DevelopmentGuide.md b/Docs/DevelopmentGuide.md
index 4259b05..3f956e6 100644
--- a/Docs/DevelopmentGuide.md
+++ b/Docs/DevelopmentGuide.md
@@ -2,7 +2,7 @@
本文面向继续开发 CodexBar 的维护者, 记录当前 App 的主要流程, 数据边界和模块协作方式
-更细的 app-server 协议见 [AppServer.md](AppServer.md), Codex Hook 统计口径见 [CodexHook.md](CodexHook.md)
+更细的 app-server 协议见 [AppServer.md](AppServer.md), Codex Hook 统计口径见 [CodexHook.md](CodexHook.md), 跨设备同步链路见 [CrossDeviceSync.md](CrossDeviceSync.md)
## 1. 应用定位与工程边界
@@ -15,8 +15,8 @@ App 通过本机 Codex app-server 读取账号, 额度和 token 用量, 通过 C
- 应用形态是 `LSUIElement`, 不显示 Dock 图标, 不依赖主窗口
- 最低系统版本是 macOS 15.0
- App Sandbox 保持关闭, 因为需要启动本机 `codex`, 读取真实用户 Codex 登录状态, 并写入用户级 Hook 配置
-- 除 Sparkle 检查和下载更新外, App 自身不发起网络请求
-- 账号, 额度, token 用量和 Hook 工作流统计都只在本机处理, 不发送给第三方
+- 除 Sparkle 检查/下载更新, 以及用户显式开启「跨设备同步」后的 CloudKit private database 同步外, App 自身不发起网络请求
+- 账号, 额度和 token 用量只在本机处理, 不发送给第三方;Hook 工作流统计默认只在本机处理, 仅在用户开启「跨设备同步」后把脱敏 daily 聚合行同步到当前 iCloud 账号
- Swift 工程使用 Swift 6 并开启 `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`, UI 默认 MainActor 隔离;服务共享状态优先用 actor 管理, DTO、模型、同步辅助类型和静态工具需要显式使用 `nonisolated`
源码目录职责:
@@ -368,7 +368,7 @@ codex app-server --listen stdio://
- 菜单面板只展示"未登录"和"初始化失败"两类特殊状态
- 具体启动失败, 请求失败, 超时, 断连, 解析失败和业务错误进入日志窗口
- 账户有效时, rate limits 和 usage 可以单独失败, 失败区域按缓存或无数据处理
-- 登录项和 Hook 写入错误显示在设置窗口中部的独立错误组
+- 登录项和 Hook 写入错误显示在设置窗口中部的独立错误组, iCloud 账号不可用显示在「跨设备同步」开关下方
- 全局快捷键录制, 校验和注册错误显示在快捷键行内
- Hook 子进程尽量快速退出, 事件记录失败不会阻断 Codex 自身流程
@@ -406,26 +406,28 @@ app-server 与状态刷新错误:
设置, Hook 和更新错误:
-| 错误来源 | 检测位置 | 用户可见状态 | 重试或降级 |
-| -------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------ |
-| 登录项注册或取消失败 | `LoginItemSettings.setEnabled` | 设置窗口中部错误组显示"设置开机启动失败" | 调用 `refresh()` 恢复实际状态 |
-| `config/read` 请求失败 | `CodexHookSettings.setEnabled` / app-server `config/read` | Hook 选项下方显示"设置 Codex Hook 失败" | 不写 `hooks.json`, 调用 `refresh()` 恢复实际状态 |
-| Codex 全局配置禁用 Hook | `CodexHookSettings.setEnabled` / app-server `config/read` | Hook 开关保持关闭, Hook 选项下方显示禁用说明 | 不写 `hooks.json` |
-| `hooks.json` 读取失败或结构非法 | `CodexHookSettings.refresh` | Hook 开关视为关闭, Hook 选项下方显示错误 | 不写配置 |
-| Hook 开关写入失败 | `CodexHookSettings.setEnabled` | Hook 选项下方显示"设置 Codex Hook 失败" | 调用 `refresh()` 恢复实际状态 |
-| `hooks/list` 请求失败 | `CodexHookSettings.verifyInstalledHooks` / app-server `hooks/list` | Hook 选项下方显示"无法验证 Codex Hook" | 保留已写入 Hook, 详细错误进入日志 |
-| Hook 自动信任写入失败 | `CodexHookSettings.updateCodexHookTrust` / app-server `config/batchWrite` | Hook 选项下方显示"无法验证 Codex Hook" | 保留已写入 Hook, 详细错误进入日志 |
-| Hook 写入后验证发现问题 | `CodexHookSettings.verifyInstalledHooks` / app-server `hooks/list` | Hook 选项下方显示最高优先级验证摘要 | 保留已写入 Hook, 详细响应进入日志 |
-| 快捷键无法识别或不符合规则 | `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 |
-| Sparkle 配置缺失 | `AppUpdater.init` | 更新开关禁用, 操作显示"未配置更新资源" | 不创建 updater controller |
-| 手动检查没有更新 | `updaterDidNotFindUpdate` | 显示"没有可用更新" | 1 秒后自动清理状态 |
-| 手动检查失败 | `didAbortWithError` | 显示"检查更新失败" | 不展示底层错误细节 |
+| 错误来源 | 检测位置 | 用户可见状态 | 重试或降级 |
+| -------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------ |
+| 登录项注册或取消失败 | `LoginItemSettings.setEnabled` | 设置窗口中部错误组显示"设置开机启动失败" | 调用 `refresh()` 恢复实际状态 |
+| `config/read` 请求失败 | `CodexHookSettings.setEnabled` / app-server `config/read` | Hook 选项下方显示"设置 Codex Hook 失败" | 不写 `hooks.json`, 调用 `refresh()` 恢复实际状态 |
+| Codex 全局配置禁用 Hook | `CodexHookSettings.setEnabled` / app-server `config/read` | Hook 开关保持关闭, Hook 选项下方显示禁用说明 | 不写 `hooks.json` |
+| `hooks.json` 读取失败或结构非法 | `CodexHookSettings.refresh` | Hook 开关视为关闭, Hook 选项下方显示错误 | 不写配置 |
+| Hook 开关写入失败 | `CodexHookSettings.setEnabled` | Hook 选项下方显示"设置 Codex Hook 失败" | 调用 `refresh()` 恢复实际状态 |
+| `hooks/list` 请求失败 | `CodexHookSettings.verifyInstalledHooks` / app-server `hooks/list` | Hook 选项下方显示"无法验证 Codex Hook" | 保留已写入 Hook, 详细错误进入日志 |
+| Hook 自动信任写入失败 | `CodexHookSettings.updateCodexHookTrust` / 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, 下次刷新继续重试 |
+| 快捷键无法识别或不符合规则 | `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 |
+| Sparkle 配置缺失 | `AppUpdater.init` | 更新开关禁用, 操作显示"未配置更新资源" | 不创建 updater controller |
+| 手动检查没有更新 | `updaterDidNotFindUpdate` | 显示"没有可用更新" | 1 秒后自动清理状态 |
+| 手动检查失败 | `didAbortWithError` | 显示"检查更新失败" | 不展示底层错误细节 |
Codex 版本探测错误:
@@ -798,8 +800,8 @@ flowchart TD
- 事件名先去掉 `_` 和 `-`, 再转小写
- `sessionStartCount`, `stopCount`, `preToolUseCount` 等按归一化事件名增加
-- 最近 7 天保留 `sessionIds` 和 `turnIds`, 用于继续去重
-- 7 天前把 ID 集合压缩为 `sessionCount` 和 `turnCount`, 随后移除 ID 列表
+- 最近 3 个本地自然日保留 `sessionIds` 和 `turnIds`, 用于继续去重
+- 3 天前把 ID 集合压缩为 `sessionCount` 和 `turnCount`, 随后移除 ID 列表
- 最多保留最近 210 天数据
- 210 天外的 `events/YYYY-MM-DD.jsonl` 在主 App 维护流程中删除
- 坏 JSONL 行跳过并计入 `corrupt`, 不阻断整天聚合
@@ -815,6 +817,8 @@ 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`, 避免游标提前推进导致未落盘记录被跳过。
+
## 13. 设置窗口流程
设置窗口由 `SettingsWindowController` 打开, 内容是 `AppSettingsView`
@@ -823,15 +827,17 @@ UI 展示指标来自 `WorkflowDailyAggregate.stats`:
- `CodexHookSettings.refresh()`
- `CodexHookSettings.verifyInstalledHooks()`
+- `WorkflowSyncSettings.refresh()`
`AppSettingsView.onAppear` 时刷新:
- `LoginItemSettings.refresh()`
+- `WorkflowSyncSettings.refresh()`
- `AppUpdater.refreshAutomaticCheckSetting()`
- `CodexCLIVersionViewModel.refresh()`
- `CodexStatusViewModel.refreshCodexConnectionInfo()`
-App 再次成为 active 时, 也会刷新 Codex 版本区, 并在已安装 Hook 时重新运行 `hooks/list` 验证。
+App 再次成为 active 时, 也会刷新 Codex 版本区、iCloud 可用性, 并在已安装 Hook 时重新运行 `hooks/list` 验证。
版本探测内部有 60 秒节流, 避免 `onAppear` 和 `didBecomeActive` 连续触发时重复启动子进程
@@ -843,6 +849,7 @@ App 再次成为 active 时, 也会刷新 Codex 版本区, 并在已安装 Hook
| 自动检查更新 | 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` |
| Codex 版本 | `CodexCLIVersionSnapshot` + 当前 app-server 握手信息 | 路径点击复制到剪贴板 |
| CodexBar 版本 | Bundle + AppUpdater 状态 | 有更新状态时优先显示动态消息 |
@@ -850,6 +857,7 @@ App 再次成为 active 时, 也会刷新 Codex 版本区, 并在已安装 Hook
- 开机启动失败显示在设置组与底部按钮组之间的独立错误组
- Hook 设置失败, 全局禁用, 自动信任写入失败或验证异常显示在 Hook 选项下方
+- iCloud 不可用时显示在跨设备同步开关下方
- 没有登录项错误时不渲染错误组
- 快捷键无法识别, 规则不合法或注册冲突显示在快捷键行内
- 更新检查状态显示在 CodexBar 版本行
@@ -934,7 +942,7 @@ App 再次成为 active 时, 也会刷新 Codex 版本区, 并在已安装 Hook
- 预览视图使用可滚动代码视图, 对 JSON 做格式化和高亮
- 详情文本开启 `.textSelection(.enabled)`
-日志只记录经过 `RequestLogStorage` 的请求和错误;`RequestLogStore` 只负责把这些记录发布给 SwiftUI
+日志窗口只记录 app-server 请求和 app-server 生命周期错误;`RequestLogStore` 只负责把这些记录发布给 SwiftUI。
为了保护隐私, 不直接展示 app-server stderr 或 Codex auth 文件内容。app-server 请求、响应和错误详情会完整保留在 `RequestLogEntry` 中, UI 默认只渲染预览以避免大文本拖慢日志窗口。
@@ -990,4 +998,4 @@ App 再次成为 active 时, 也会刷新 Codex 版本区, 并在已安装 Hook
- 不读取或展示 Codex auth 文件内容
- 不把原始敏感 RPC 响应写入文档或测试夹具
- 日志完整保存 request/detail, UI 默认只渲染单行预览; 完整内容通过标题行预览或复制查看
-- Hook 统计只保存在用户 Application Support 的 CodexBar 目录
+- Hook 统计默认只保存在用户 Application Support 的 CodexBar 目录;开启「跨设备同步」后, CloudKit 只保存去掉 `sessionIds` / `turnIds` 的 daily 聚合副本, 不保存原始 Hook events
diff --git a/Images/telegram-group.jpg b/Images/telegram-group.jpg
deleted file mode 100644
index 45ff820..0000000
Binary files a/Images/telegram-group.jpg and /dev/null differ
diff --git a/README.md b/README.md
index 98fbf22..9af63d2 100644
--- a/README.md
+++ b/README.md
@@ -13,9 +13,10 @@ CodexBar 是一个轻量级 macOS 菜单栏应用。它直接连接本机 Codex
- **额度一目了然**: 分段电量条展示各时间窗口 (如 5 小时、7 天) 的剩余额度,附剩余百分比和重置时间
- **用量热力图**: 展示近 30 周的每日 token 用量,鼠标悬停可查看单日明细
- **详细统计**: 开启 Codex Hook 后,热力图会展示会话总数、对话轮次、子智能体调用次数、工具调用次数、权限请求次数和上下文压缩次数
+- **跨设备同步**: 开启 Codex Hook 后可选择把脱敏后的每日工作流聚合同步到当前 iCloud 账号
- **自动刷新**: 每分钟后台刷新一次,弹窗未打开也保持最新;双击账号图标可手动刷新
- **自动更新**: 内置 Sparkle 更新检查,新版本自动更新
-- **本地优先**: 只与本机 Codex app-server 进程通信,不向任何第三方服务发送账号、额度、token 或工作流统计数据
+- **本地优先**: 账号、额度和 token 用量只与本机 Codex app-server 通信;Hook 工作流统计默认只保存在本机,只有用户开启「跨设备同步」后才通过 CloudKit private database 同步脱敏每日聚合
## 安装
@@ -62,7 +63,7 @@ CodexBar 可以在设置中开启「启用 Codex Hook」
CodexBar 只会追加或移除 command 中包含当前 CodexBar 可执行路径的 Hook,不会删除其他 Codex Hook。
-统计数据只保存在本机 `~/Library/Application Support/CodexBar/HookEvents/`,不会发送给任何个人或第三方服务。
+统计数据默认只保存在本机 `~/Library/Application Support/CodexBar/HookEvents/`。开启「跨设备同步」后,CodexBar 会通过 CloudKit private database 把去掉 `sessionIds` / `turnIds` 的每日聚合副本同步到当前 iCloud 账号;iCloud 不可用时该开关不可操作,并在设置页显示「iCloud 不可用」。
## 从源码构建
@@ -86,22 +87,14 @@ Swift 源码按职责放在 `CodexBar/` 下的子目录中:
- `Services/`: actor 隔离的 app-server 会话、Codex CLI 解析、版本探测、Hook 设置、工作流统计、日志存储、开机自启和 Sparkle 更新
- `Views/`: 菜单面板、设置窗口、日志窗口和共享 Liquid Glass 样式
-更详细的启动、刷新、Hook 统计、设置、日志、更新和发布流程见 [开发文档](Docs/DevelopmentGuide.md)。
+更详细的启动、刷新、Hook 统计、跨设备同步、设置、日志、更新和发布流程见 [开发文档](Docs/DevelopmentGuide.md) 与 [跨设备同步文档](Docs/CrossDeviceSync.md)。
## 隐私
-CodexBar 只与本机 Codex app-server 进程通信。账号信息、额度数据、token 用量和 Hook 工作流数据不会被收集或发送给任何个人或服务。
+CodexBar 只通过本机 Codex app-server 读取账号信息、额度数据和 token 用量,这些数据不会发送给第三方服务。Hook 工作流数据默认只保存在本机;用户显式开启「跨设备同步」后,CloudKit 仅保存脱敏后的每日聚合副本,不保存原始 Hook events、`sessionIds` 或 `turnIds`。
-只有检查和下载 App 更新时会产生额外网络请求,请求范围仅包含 [appcast](https://codexbar.zabrian.app/appcast.xml) 和 appcast 中对应的 DMG 下载地址。
+除用户开启「跨设备同步」后的 CloudKit 请求外,只有检查和下载 App 更新时会产生额外网络请求,请求范围仅包含 [appcast](https://codexbar.zabrian.app/appcast.xml) 和 appcast 中对应的 DMG 下载地址。
## 许可证
本项目采用 [GNU General Public License v3.0](LICENSE)
-
-## 群组
-
-加入 Telegram 群组
-
-<p align="center">
- <img src="Images/telegram-group.jpg" width="532">
-</p>
diff --git a/appcast.xml b/appcast.xml
index 24b2da4..aabff43 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.0</title>
+ <sparkle:version>28</sparkle:version>
+ <sparkle:shortVersionString>3.2.0</sparkle:shortVersionString>
+ <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+ <sparkle:releaseNotesLink>https://codexbar.zabrian.app/notes#3.2.0</sparkle:releaseNotesLink>
+ <pubDate>Thu, 25 Jun 2026 21:08:27 +0800</pubDate>
+ <enclosure url="https://codexbar.zabrian.app/download/CodexBar-v3.2.0.dmg" sparkle:edSignature="wnmcvQEIyI4jBIDmAaAWOWP/sGLw9tT5KBDYdBhzOAB+jIz5hbALMFZzf40F5lW0dV0Hy9SJ8r0DO3ab9b12Bw==" length="3329866" type="application/octet-stream"/>
+ </item>
<item>
<title>CodexBar.app 3.1.3</title>
<sparkle:version>27</sparkle:version>