ccus-cli 0.1.9 → 0.1.11

package/README.md

@@ -8,6 +8,8 @@
 - `ccus export`：默认导出当前周数据包（gzip 压缩的 `.json.gz`），里面同时包含原始事件和按天维度的周汇总。
 - `ccus aggregate`：读取一个目录里的多人 export bundle（`.json.gz` 或 `.json`），输出明细、按天、按周三个 CSV。
 - `ccus aggregate serve`：同样以 bundle 目录为输入，启动本地多人 dashboard 页面，不落地任何文件。
+- `ccus sync`：定时把当前周数据包导出并复制到一个目标目录（如团队共享盘），目标目录下按周自动建子目录；日常由 statusline 兜底触发，也可挂系统计划任务做到严格每天定时。
+- `ccus open`：用系统文件管理器打开 ccus 本地存储目录（事件日志、exports、dashboard 都在里面）；加 `--print` 只输出目录路径、不打开。
 - `ccus update`：主动检查 npm 上是否有新版本，有则提示手动升级命令；`ccus --version` 查看当前版本。
 
 > **支持范围**：`ccus statusline emit` 依赖 Claude Code 的 statusLine 机制（从 `stdin` 读 JSON、向 `stdout` 回一行文本），**只在命令行版 Claude Code（CLI / 终端）里生效**。
@@ -83,6 +85,10 @@ ccus dashboard serve            # 启动本地页面，默认看本周（this-we
 
 ccus aggregate --input-dir ./team-exports   # 多人的数据汇总，可以导出 detail.csv、daily.csv、weekly.csv 三个维度的文件
 ccus aggregate serve --input-dir ./team-exports #直接打开一个看板
+
+ccus sync config --target ./team-exports    # 配置同步目标目录（之后 statusline 会兜底定时同步）
+ccus sync                                   # 立即同步一次
+ccus sync status                            # 查看同步配置与上次同步时间
 ```
 
 ### 一键安装（推荐）
@@ -165,14 +171,54 @@ ccus aggregate serve --input-dir ./team-exports
 
 - 输入目录放很多通过 `ccus export` 导出的 bundle 文件，`.json.gz`（gzip 压缩）与明文 `.json` 都能识别，gzip 文件读取时自动解压
 - `aggregate` 目前只接受 `schemaVersion: 6` 的 bundle；旧导出请先用当前版本重新 `ccus export`
+- 同一个人在多台电脑上各自导出 bundle 时会自动合并去重：累加类指标（token、消息数、采样数等）按「同人同天 / 同人同周取 `generatedAt` 最新的那份导出」保留，不相加，避免同一台机器重复导出或周与周重叠造成翻倍；usage（5h / 7d）从选中那份的 `rawEvents` 按真实时间戳重算（peak 取 max、latest 取最新）
 - `ccus aggregate --input-dir DIR --out-dir DIR`
 - 输出三个文件：
-  - `detail.csv`：来自每个 bundle 的 `rawEvents`，`contextUsedM` / `contextMaxM` 为单条事件的 context window token；另附带 `inputTokensM` / `outputTokensM` / `cacheReadInputTokensM`（按 `date` 取自当天 `dailySummaries` 的日总量，同一天多行会重复，不能按行求和）
-  - `daily.csv`：直接来自每个 bundle 的 `dailySummaries`
-  - `weekly.csv`：直接来自每个 bundle 的 `weeklySummary`
+  - `detail.csv`：来自 winner bundle 的 `rawEvents`（同人同天只展开最新那份的事件），`contextUsedM` / `contextMaxM` 为单条事件的 context window token；另附带 `inputTokensM` / `outputTokensM` / `cacheReadInputTokensM`（按 `date` 取自当天 `dailySummaries` 的日总量，同一天多行会重复，不能按行求和）
+  - `daily.csv`：同人同天取最新导出 bundle 的 `dailySummaries`，usage 从该 bundle 当天事件重算
+  - `weekly.csv`：同人同周取最新导出 bundle 的 `weeklySummary`，usage 从该 bundle 全部事件重算
 - CSV 里所有以 token 计的列（context 与 in/out/cache）都以百万（M）为单位（原始值除以 1,000,000），列名统一带 `M` 后缀；`contextWindowPct` 仍是百分比
 - 想直接查看团队多人 dashboard，可以用 `ccus aggregate serve --input-dir DIR [--port 0] [--host 127.0.0.1]`：默认监听 `127.0.0.1` 上的随机端口，启动后会自动用系统默认浏览器打开，每次请求实时读取目录里的 bundle，不写入任何文件
 
+## 定时同步
+
+把每个人的 `ccus export` 攒到一个共享目录（团队网盘 / 共享盘）通常是手动的，容易漏。`ccus sync` 用来自动化这一步：周期到了就 `export` 一次，并把导出文件**复制**到目标目录下**按周命名的子目录**里。
+
+```bash
+ccus sync config --target ./team-exports         # 配置同步目标目录（默认周期 3h）
+ccus sync config --interval daily                # 改周期，可写 3h（默认）/ daily / 6h / 30m
+ccus sync config                                 # 不带参数：打印当前配置
+ccus sync                                        # 用已存配置立即同步一次
+ccus sync install                                # 注册系统调度器：每周五 18:00 自动同步（Windows 直接创建计划任务）
+ccus sync uninstall                              # 卸载系统调度器
+ccus sync status                                 # 查看目标目录、周期、上次同步时间、是否到期
+```
+
+行为：
+
+- **目标目录按周建子目录**：子目录名形如 `2026_06_01_2026_06_07`（该周周一~周日，全下划线），不存在时自动创建。
+- **周一归档上一周**：周一同步时会额外把刚结束的上一整周（`last-week`）导出并归档到对应的上一周子目录（周一是第一个能拿到完整上一周数据的日子）；同一天内多次同步用 `sync-state.lastArchivedWeek` 去重，不重复归档。
+- **复制语义**：本地 `data-dir/exports` 仍保留一份，目标目录再放一份，本地照旧可 `aggregate` / `dashboard`。导出产物与 `ccus export` 完全一致，目标目录可直接喂给 `ccus aggregate`。
+- **配置与同步分离**：`ccus sync config` 只读写配置（`--target` / `--interval` / `--range` 写进数据目录下的 `sync-config.json`，可手编；不带参数则打印当前配置）；`ccus sync` 只用已存配置执行一次同步。上次同步时间记录在 `sync-state.json`。
+- **周期**：默认 `3h`（每 3 小时最多同步一次的滚动周期）；也支持 `daily`（按**自然日**判断——同一天内不重复同步，跨到下一天才再同步）与 `<N>h` / `<N>m` 的滚动周期。
+
+### 两种触发方式
+
+1. **statusline 兜底（零配置）**：配置过目标目录后，每次 statusline 渲染都会检查是否到周期，到了就 spawn 一个 detached 后台进程静默执行同步，**不阻塞 statusline、不污染单行输出**（与更新检查同款机制）。
+   - 局限：statusline 只在你**使用 Claude Code** 时触发。某天完全不开 Claude Code，则当天不会自动同步——但那天也没有新数据，下次任意一次交互都会把整周最新 bundle 重新覆盖同步，不丢数据。
+2. **系统调度器（不依赖是否开 Claude Code）**：如果要做到「哪怕一整天不碰 Claude Code，也在固定时间准时跑一次」，用 `ccus sync install` 一键注册一个**每周五 18:00** 跑 `ccus sync` 的系统调度器：
+
+   ```bash
+   ccus sync install          # Windows 用 schtasks 创建计划任务（任务名 ccus-sync）
+   ccus sync install --print  # 只打印将执行的命令、不实际安装
+   ccus sync uninstall        # 卸载该调度器（--print 只打印不执行）
+   ```
+
+   - **Windows** 会真正创建/删除计划任务；也可手动 `schtasks /delete /tn ccus-sync /f`。
+   - **macOS / Linux** 不自动改系统，`ccus sync install` 会打印一条 cron 命令（`0 18 * * 5 …`）让你手动 `crontab` 安装，避免误改已有 crontab。
+
+   > 记得先 `ccus sync config --target DIR` 配好目标目录，调度任务才有地方可同步。
+
 ## 调试
 
 出问题时（比如 statusline 不出数据、导出/聚合结果不对），可以打开详细日志：

package/dist/cli.js

@@ -53,13 +53,15 @@ const io_1 = require("./lib/io");
 const open_1 = require("./lib/open");
 const payload_1 = require("./lib/payload");
 const paths_1 = require("./lib/paths");
+const scheduler_1 = require("./lib/scheduler");
+const sync_1 = require("./lib/sync");
 const storage_1 = require("./lib/storage");
 const time_1 = require("./lib/time");
 const update_check_1 = require("./lib/update-check");
 const version_1 = require("./lib/version");
 /** CLI 帮助信息保持简洁，方便直接挂到 README 或终端里查看。 */
 function printHelp() {
-    process.stdout.write(`ccus\n\nCommands:\n  ccus install [--settings PATH] [--command CMD] [--data-dir PATH]\n  ccus statusline emit [--data-dir PATH] [--input FILE] [--no-store]\n  ccus dashboard build [--range today|this-week|last-week|5h] [--out FILE] [--data-dir PATH]\n  ccus dashboard open [--range today|this-week|last-week|5h] [--out FILE] [--data-dir PATH]\n  ccus dashboard serve [--range today|this-week|last-week|5h] [--port 0] [--host 127.0.0.1] [--open] [--data-dir PATH]\n  ccus export [RANGE] [--out FILE] [--data-dir PATH]   (RANGE: this-week|tw, last-week|lw, today, 5h; e.g. ccus export lw)\n  ccus aggregate --input-dir DIR [--out-dir DIR]\n  ccus aggregate serve --input-dir DIR [--port 0] [--host 127.0.0.1]\n  ccus update [--data-dir PATH]\n  ccus --version\n\nGlobal flags:\n  --verbose | --debug | -v   输出详细调试日志到 stderr（等价于设置 CCUS_DEBUG=1），方便排查问题\n`);
+    process.stdout.write(`ccus\n\nCommands:\n  ccus install [--settings PATH] [--command CMD] [--data-dir PATH]\n  ccus statusline emit [--data-dir PATH] [--input FILE] [--no-store]\n  ccus dashboard build [--range today|this-week|last-week|5h] [--out FILE] [--data-dir PATH]\n  ccus dashboard open [--range today|this-week|last-week|5h] [--out FILE] [--data-dir PATH]\n  ccus dashboard serve [--range today|this-week|last-week|5h] [--port 0] [--host 127.0.0.1] [--open] [--data-dir PATH]\n  ccus export [RANGE] [--out FILE] [--data-dir PATH]   (RANGE: this-week|tw, last-week|lw, today, 5h; e.g. ccus export lw)\n  ccus aggregate --input-dir DIR [--out-dir DIR]\n  ccus aggregate serve --input-dir DIR [--port 0] [--host 127.0.0.1]\n  ccus sync [--data-dir PATH]\n  ccus sync config [--target DIR] [--interval 3h|daily|<N>h|<N>m] [--range this-week] [--data-dir PATH]\n  ccus sync install [--print] [--data-dir PATH]   (注册每周五 18:00 的系统调度器)\n  ccus sync uninstall [--print]   (卸载系统调度器)\n  ccus sync status [--data-dir PATH]\n  ccus open [--data-dir PATH] [--print]\n  ccus update [--data-dir PATH]\n  ccus --version\n\nGlobal flags:\n  --verbose | --debug | -v   输出详细调试日志到 stderr（等价于设置 CCUS_DEBUG=1），方便排查问题\n`);
 }
 /** 一个轻量的参数解析器，当前命令面不复杂，没必要引入额外依赖。 */
 function parseOptions(args) {
@@ -179,6 +181,8 @@ async function handleStatuslineEmit(options) {
         // 更新检查必须对 statusline 完全无侵入：同步读旧缓存决定是否在行尾追加小标记，
         // 把网络请求甩给 detached 后台进程，主进程不等待、失败静默。
         (0, update_check_1.maybeSpawnBackgroundCheck)(dataDir);
+        // 定时同步同样对 statusline 无侵入：到周期才 spawn detached 后台进程执行 export+复制，主进程不等待。
+        (0, sync_1.maybeSpawnBackgroundSync)(dataDir);
         const notice = (0, update_check_1.computeUpdateNotice)(dataDir);
         const statusLine = notice ? `${event.statusLine} | ${notice}` : event.statusLine;
         process.stdout.write(`${statusLine}\n`);
@@ -288,11 +292,12 @@ async function handleDashboardServe(options) {
     });
 }
 /**
- * 导出原始事件。
+ * 导出原始事件：生成 bundle 并写入本地 exports，返回输出路径与时间窗口。
  *
  * 当前默认导出一个 JSON 包，同时包含原始事件和按天周汇总。
+ * 抽成独立函数供 `ccus export` 与 `ccus sync` 复用，行为完全一致。
  */
-async function handleExport(options) {
+async function runExport(options) {
     const dataDir = getDataDir(options);
     const range = getStringOption(options, "range") ?? "this-week";
     const output = getStringOption(options, "out");
@@ -417,6 +422,13 @@ async function handleExport(options) {
         await (0, export_1.writeTextFile)(outputPath, content);
     }
     (0, debug_1.debugLog)("export", "bundle written", { outputPath, rawBytes: content.length, compressed });
+    return { outputPath, window };
+}
+/**
+ * `ccus export` 入口：执行 runExport 并把输出路径打到 stdout。
+ */
+async function handleExport(options) {
+    const { outputPath } = await runExport(options);
     process.stdout.write(`${outputPath}\n`);
 }
 /**
@@ -508,6 +520,25 @@ async function handleAggregateServe(options) {
         process.once("SIGTERM", shutdown);
     });
 }
+/**
+ * `ccus open`：用系统文件管理器打开 ccus 本地存储目录（事件日志、exports、dashboard 都在里面）。
+ *
+ * 默认目录由 `getDefaultDataDir` 推导，可用 `--data-dir` 覆盖。
+ * 加 `--print` 只把目录路径打到 stdout、不真正打开，方便在脚本里取路径。
+ */
+async function handleOpenDataDir(options) {
+    const dataDir = getDataDir(options);
+    (0, debug_1.debugLog)("open", "resolved data dir", { dataDir, print: getBooleanOption(options, "print") });
+    if (getBooleanOption(options, "print")) {
+        process.stdout.write(`${dataDir}\n`);
+        return;
+    }
+    // 目录可能还没被 statusline 创建过，先确保存在，否则系统打开会失败。
+    const fs = await Promise.resolve().then(() => __importStar(require("node:fs/promises")));
+    await fs.mkdir(dataDir, { recursive: true });
+    await (0, open_1.openPath)(dataDir);
+    process.stdout.write(`${dataDir}\n`);
+}
 /** 历史上被移除的导出格式 token，作为位置参数出现时要明确报错而不是当成 range。 */
 const REMOVED_EXPORT_FORMAT_TOKENS = new Set(["csv", "jsonl", "raw"]);
 /**
@@ -600,6 +631,141 @@ async function handleBackgroundCheckUpdate(options) {
     const dataDir = getDataDir(options);
     await (0, update_check_1.performUpdateCheck)(dataDir);
 }
+/**
+ * `ccus sync`：执行一次定时同步（导出当前周 bundle 并复制到目标目录的按周子目录）。
+ *
+ * 带 `--target` / `--interval` / `--range` 时先合并并持久化配置，再立即同步一次；
+ * 不带参数则用已存配置同步。最终仍无目标目录则报错引导用户先配置。
+ */
+async function handleSync(options) {
+    const dataDir = getDataDir(options);
+    const target = getStringOption(options, "target");
+    const interval = getStringOption(options, "interval");
+    const range = getStringOption(options, "range");
+    if (target !== undefined || interval !== undefined || range !== undefined) {
+        const current = (0, sync_1.readSyncConfig)(dataDir);
+        const next = {
+            targetDir: target !== undefined ? node_path_1.default.resolve(target) : current.targetDir,
+            intervalLabel: interval ?? current.intervalLabel,
+            range: range ?? current.range,
+        };
+        await (0, sync_1.writeSyncConfig)(dataDir, next);
+        (0, debug_1.debugLog)("sync", "config updated", next);
+    }
+    const config = (0, sync_1.readSyncConfig)(dataDir);
+    if (!config.targetDir) {
+        throw new Error("未配置同步目标目录。请先运行 `ccus sync config --target DIR`。");
+    }
+    const result = await (0, sync_1.performSync)(dataDir, runExport);
+    process.stdout.write(`已同步到 ${result.destPath}\n`);
+    if (result.archivedLastWeekDest) {
+        process.stdout.write(`已归档上一周到 ${result.archivedLastWeekDest}\n`);
+    }
+}
+/**
+ * `ccus sync status`：打印当前同步配置、上次同步时间与是否到期。
+ */
+async function handleSyncStatus(options) {
+    const dataDir = getDataDir(options);
+    const config = (0, sync_1.readSyncConfig)(dataDir);
+    const state = (0, sync_1.readSyncStateSync)(dataDir);
+    const due = (0, sync_1.isSyncDue)(config, state);
+    const lines = [
+        `目标目录: ${config.targetDir ?? "(未配置)"}`,
+        `同步周期: ${config.intervalLabel}`,
+        `导出范围: ${config.range}`,
+        `上次同步: ${state?.lastSyncedAt ?? "(从未)"}${state?.lastResult ? ` [${state.lastResult}]` : ""}`,
+        state?.lastArchivedWeek ? `已归档上一周: ${state.lastArchivedWeek}` : null,
+        state?.lastError ? `上次错误: ${state.lastError}` : null,
+        `现在是否到期: ${config.targetDir ? (due ? "是" : "否") : "(未配置目标目录)"}`,
+    ].filter((line) => line !== null);
+    process.stdout.write(`${lines.join("\n")}\n`);
+}
+/**
+ * `ccus sync config`：只读写同步配置，不触发同步。
+ *
+ * 带 `--target` / `--interval` / `--range` 时合并并持久化到 `sync-config.json`；
+ * 不带任何参数时仅打印当前配置，方便确认。
+ */
+async function handleSyncConfig(options) {
+    const dataDir = getDataDir(options);
+    const target = getStringOption(options, "target");
+    const interval = getStringOption(options, "interval");
+    const range = getStringOption(options, "range");
+    const current = (0, sync_1.readSyncConfig)(dataDir);
+    const changed = target !== undefined || interval !== undefined || range !== undefined;
+    const next = {
+        targetDir: target !== undefined ? node_path_1.default.resolve(target) : current.targetDir,
+        intervalLabel: interval ?? current.intervalLabel,
+        range: range ?? current.range,
+    };
+    if (changed) {
+        await (0, sync_1.writeSyncConfig)(dataDir, next);
+        (0, debug_1.debugLog)("sync", "config updated", next);
+    }
+    const header = changed ? "同步配置已更新：" : "当前同步配置：";
+    process.stdout.write(`${header}\n  目标目录: ${next.targetDir ?? "(未配置)"}\n  同步周期: ${next.intervalLabel}\n  导出范围: ${next.range}\n`);
+}
+/**
+ * `ccus sync install`：安装一个系统调度器，每周五 18:00 跑一次 `ccus sync`。
+ *
+ * Windows 用 schtasks 真正创建计划任务；macOS / Linux 打印 cron 命令交由用户手动安装。
+ * 加 `--print` 只打印将执行的调度器命令、不真正安装。
+ */
+async function handleSyncInstall(options) {
+    const dataDir = getDataDir(options);
+    const print = getBooleanOption(options, "print");
+    const scriptPath = process.argv[1];
+    const result = (0, scheduler_1.installScheduler)(process.execPath, scriptPath, dataDir, { print });
+    const { plan } = result;
+    if (print) {
+        process.stdout.write(`将安装的调度器命令（每周五 18:00 同步）：\n  ${plan.displayCommand}\n`);
+        return;
+    }
+    if (result.installed) {
+        process.stdout.write(`已安装系统调度器「ccus-sync」：每周五 18:00 运行一次 ccus sync。\n卸载：\n  ${plan.uninstallHint}\n`);
+        return;
+    }
+    // 非 Windows：不自动改系统，打印命令引导用户手动安装。
+    process.stdout.write(`当前平台（${plan.platform}）不自动安装，请手动运行以下命令注册每周五 18:00 的 cron 任务：\n  ${plan.displayCommand}\n卸载：\n  ${plan.uninstallHint}\n`);
+}
+/**
+ * `ccus sync uninstall`：卸载每周五同步的系统调度器。
+ *
+ * Windows 用 schtasks 删除计划任务；macOS / Linux 打印 crontab 提示。加 `--print` 只打印命令、不执行。
+ */
+async function handleSyncUninstall(options) {
+    const print = getBooleanOption(options, "print");
+    const result = (0, scheduler_1.uninstallScheduler)({ print });
+    if (print) {
+        process.stdout.write(`将执行的卸载命令：\n  ${result.displayCommand}\n`);
+        return;
+    }
+    if (result.autoUninstallable) {
+        if (result.uninstalled) {
+            process.stdout.write(`已卸载系统调度器「ccus-sync」。\n`);
+        }
+        else {
+            process.stdout.write(`未能删除调度任务（可能本就未安装）。如需手动卸载：\n  ${result.displayCommand}\n`);
+        }
+        return;
+    }
+    process.stdout.write(`当前平台（${result.platform}）请手动卸载：\n  ${result.displayCommand}\n`);
+}
+/**
+ * 隐藏命令 `__sync`：由 statusline 路径以 detached 后台进程触发。
+ *
+ * 静默执行一次同步：不写 stdout，失败一律吞掉，绝不影响触发它的 statusline 主进程。
+ */
+async function handleBackgroundSync(options) {
+    const dataDir = getDataDir(options);
+    try {
+        await (0, sync_1.performSync)(dataDir, runExport);
+    }
+    catch (error) {
+        (0, debug_1.debugLog)("sync", "background sync failed", error instanceof Error ? (error.stack ?? error.message) : String(error));
+    }
+}
 /** 顶层命令分发入口。 */
 async function main(args = process.argv.slice(2)) {
     (0, debug_1.setDebugEnabled)((0, debug_1.resolveDebugEnabled)(args));
@@ -614,6 +780,10 @@ async function main(args = process.argv.slice(2)) {
         process.stdout.write(`${(0, version_1.getCurrentVersion)()}\n`);
         return;
     }
+    if (group === "open") {
+        await handleOpenDataDir(parseOptions(args.slice(1)));
+        return;
+    }
     if (group === "update") {
         await handleUpdate(parseOptions(args.slice(1)));
         return;
@@ -622,6 +792,33 @@ async function main(args = process.argv.slice(2)) {
         await handleBackgroundCheckUpdate(parseOptions(args.slice(1)));
         return;
     }
+    if (group === "sync") {
+        if (action === "config") {
+            await handleSyncConfig(parseOptions(rest));
+            return;
+        }
+        if (action === "status") {
+            await handleSyncStatus(parseOptions(rest));
+            return;
+        }
+        if (action === "install") {
+            await handleSyncInstall(parseOptions(rest));
+            return;
+        }
+        if (action === "uninstall") {
+            await handleSyncUninstall(parseOptions(rest));
+            return;
+        }
+        if (action && !action.startsWith("--")) {
+            throw new Error(`Unsupported sync argument: ${action}. Use \`ccus sync\`, \`ccus sync config [--target DIR]\`, \`ccus sync install\`, \`ccus sync uninstall\` or \`ccus sync status\`.`);
+        }
+        await handleSync(parseOptions(args.slice(1)));
+        return;
+    }
+    if (group === "__sync") {
+        await handleBackgroundSync(parseOptions(args.slice(1)));
+        return;
+    }
     if (group === "install") {
         await handleInstall(parseOptions(args.slice(1)));
         return;

package/dist/lib/aggregate.js

@@ -110,75 +110,172 @@ async function loadWeeklyExportBundles(inputDir) {
     }
     return bundles;
 }
-/** 从 bundle.rawEvents 展开 detail.csv 明细。 */
+/**
+ * 同一个人在多台电脑导出多个 bundle 时的合并策略。
+ *
+ * 累加类字段（token / 消息数 / 采样数等）怕重复计数（同一台机器重复导出、周与周重叠），
+ * 所以按「同人同天 / 同人同周取 generatedAt 最新的那份导出 bundle」去重，不相加。
+ * usage 是百分比快照、不是累加量，从选中那份 winner bundle 的 rawEvents 按真实时间戳重算
+ * （peak 取 max，latest 取时间戳最新），某指标在 rawEvents 里缺失时回退到 daySummary/weeklySummary 自带值。
+ */
+/** bundle 的 personKey 解析结果做一次缓存，避免反复计算。 */
+function bundlePersonKey(bundle) {
+    return toPersonKey(bundle.identity.gitUserEmail, bundle.identity.gitUserName);
+}
+/** 某天 daySummary 是否承载真实数据（用于优先选中有数据的那份 bundle，而非占位空天）。 */
+function dayHasData(day) {
+    return day.sampleCount > 0 || day.userMessageCount > 0 || day.apiRequestCount > 0;
+}
+/** 整周 weeklySummary 是否承载真实数据。 */
+function weekHasData(bundle) {
+    const summary = bundle.weeklySummary;
+    return summary.statusline.sampleCount > 0 || summary.counts.userMessageCount > 0 || summary.counts.apiRequestCount > 0;
+}
+/** winner 比较：有数据优先，其次 generatedAt 较新，最后用 filePath 做稳定 tie-break。 */
+function isBetterCandidate(nextHasData, nextGeneratedAt, nextFilePath, currentHasData, currentGeneratedAt, currentFilePath) {
+    if (nextHasData !== currentHasData) {
+        return nextHasData;
+    }
+    if (nextGeneratedAt !== currentGeneratedAt) {
+        return nextGeneratedAt > currentGeneratedAt;
+    }
+    return nextFilePath > currentFilePath;
+}
+/** 对每个 (personKey, date) 选出 generatedAt 最新、且尽量有数据的那份 bundle 当天数据。 */
+function selectDailyWinners(bundles) {
+    const winners = new Map();
+    for (const { filePath, bundle } of bundles) {
+        const personKey = bundlePersonKey(bundle);
+        const generatedAt = bundle.generatedAt ?? "";
+        for (const day of bundle.dailySummaries) {
+            const key = `${personKey}|${day.date}`;
+            const current = winners.get(key);
+            if (!current || isBetterCandidate(dayHasData(day), generatedAt, filePath, dayHasData(current.day), current.generatedAt, current.filePath)) {
+                winners.set(key, { personKey, date: day.date, day, bundle, generatedAt, filePath });
+            }
+        }
+    }
+    return winners;
+}
+/** 对每个 (personKey, week) 选出 generatedAt 最新、且尽量有数据的那份 bundle。 */
+function selectWeeklyWinners(bundles) {
+    const winners = new Map();
+    for (const { filePath, bundle } of bundles) {
+        const personKey = bundlePersonKey(bundle);
+        const week = weekKey(new Date(bundle.range.start));
+        const key = `${personKey}|${week}`;
+        const generatedAt = bundle.generatedAt ?? "";
+        const current = winners.get(key);
+        if (!current || isBetterCandidate(weekHasData(bundle), generatedAt, filePath, weekHasData(current.bundle), current.generatedAt, current.filePath)) {
+            winners.set(key, { personKey, week, bundle, generatedAt, filePath });
+        }
+    }
+    return winners;
+}
+/** 把 bundle 的 rawEvents 计算成 StatuslineEvent 并按本地自然日分组，结果做缓存复用。 */
+const bundleEventsCache = new WeakMap();
+function bundleEventsByDate(bundle) {
+    const cached = bundleEventsCache.get(bundle);
+    if (cached) {
+        return cached;
+    }
+    const byDate = new Map();
+    for (const record of bundle.rawEvents.filter(isPersistedStatuslineEvent)) {
+        const event = (0, payload_1.computeStatuslineEvent)(record);
+        const dateKey = localDateKey(new Date(event.timestamp));
+        const list = byDate.get(dateKey);
+        if (list) {
+            list.push(event);
+        }
+        else {
+            byDate.set(dateKey, [event]);
+        }
+    }
+    bundleEventsCache.set(bundle, byDate);
+    return byDate;
+}
+/** 从一组事件按真实时间戳重算 5h / 7d 的 peak（max）与 latest（时间戳最新非空）。 */
+function recomputeUsage(events) {
+    const newestFirst = [...events].sort((left, right) => new Date(right.timestamp).getTime() - new Date(left.timestamp).getTime());
+    const fiveValues = events.map((event) => event.usagePct).filter((value) => value !== null);
+    const sevenValues = events.map((event) => event.sevenDayUsagePct).filter((value) => value !== null);
+    return {
+        fiveHourPeakUsagePct: fiveValues.length > 0 ? (0, time_1.roundNumber)(Math.max(...fiveValues), 1) : null,
+        fiveHourLatestUsagePct: newestFirst.find((event) => event.usagePct !== null)?.usagePct ?? null,
+        sevenDayPeakUsagePct: sevenValues.length > 0 ? (0, time_1.roundNumber)(Math.max(...sevenValues), 1) : null,
+        sevenDayLatestUsagePct: newestFirst.find((event) => event.sevenDayUsagePct !== null)?.sevenDayUsagePct ?? null,
+    };
+}
+/** 从 winner bundle 的事件展开 detail.csv，同人同天只保留 winner，那份的当天 token 总量随行附带。 */
 function buildAggregatedDetailRows(bundles) {
+    const winners = selectDailyWinners(bundles);
     const rows = [];
-    for (const { bundle } of bundles) {
-        const personKey = toPersonKey(bundle.identity.gitUserEmail, bundle.identity.gitUserName);
-        const tokensByDate = new Map(bundle.dailySummaries.map((day) => [day.date, day]));
-        for (const record of bundle.rawEvents.filter(isPersistedStatuslineEvent)) {
-            const event = (0, payload_1.computeStatuslineEvent)(record);
-            const ts = new Date(event.timestamp);
-            const dateKey = localDateKey(ts);
-            const dayTokens = tokensByDate.get(dateKey);
+    for (const winner of winners.values()) {
+        const events = bundleEventsByDate(winner.bundle).get(winner.date) ?? [];
+        for (const event of events) {
             rows.push({
                 ...event,
-                personKey,
-                weekKey: weekKey(ts),
-                dateKey,
-                inputTokens: dayTokens?.inputTokens ?? 0,
-                outputTokens: dayTokens?.outputTokens ?? 0,
-                cacheReadInputTokens: dayTokens?.cacheReadInputTokens ?? 0,
+                personKey: winner.personKey,
+                weekKey: weekKey(new Date(event.timestamp)),
+                dateKey: winner.date,
+                inputTokens: winner.day.inputTokens,
+                outputTokens: winner.day.outputTokens,
+                cacheReadInputTokens: winner.day.cacheReadInputTokens,
             });
         }
     }
     return rows.sort((left, right) => left.timestamp.localeCompare(right.timestamp));
 }
-/** 直接从 bundle.dailySummaries 展开 daily.csv。 */
+/** 展开 daily.csv：同人同天取 winner bundle 的累加值，usage 从该 bundle 当天事件重算。 */
 function buildAggregatedDailyRows(bundles) {
+    const winners = selectDailyWinners(bundles);
     const rows = [];
-    for (const { bundle } of bundles) {
-        const personKey = toPersonKey(bundle.identity.gitUserEmail, bundle.identity.gitUserName);
-        for (const item of bundle.dailySummaries) {
-            rows.push({
-                personKey,
-                date: item.date,
-                userMessageCount: item.userMessageCount,
-                apiRequestCount: item.apiRequestCount,
-                inputTokens: item.inputTokens,
-                outputTokens: item.outputTokens,
-                cacheReadInputTokens: item.cacheReadInputTokens,
-                sampleCount: item.sampleCount,
-                fiveHourPeakUsagePct: item.fiveHourPeakUsagePct,
-                fiveHourLatestUsagePct: item.fiveHourLatestUsagePct,
-                sevenDayPeakUsagePct: item.sevenDayPeakUsagePct,
-                sevenDayLatestUsagePct: item.sevenDayLatestUsagePct,
-                uniqueSessions: item.uniqueSessions,
-                uniqueWorkspaces: item.uniqueWorkspaces,
-            });
-        }
+    for (const winner of winners.values()) {
+        const day = winner.day;
+        const usage = recomputeUsage(bundleEventsByDate(winner.bundle).get(winner.date) ?? []);
+        rows.push({
+            personKey: winner.personKey,
+            date: day.date,
+            userMessageCount: day.userMessageCount,
+            apiRequestCount: day.apiRequestCount,
+            inputTokens: day.inputTokens,
+            outputTokens: day.outputTokens,
+            cacheReadInputTokens: day.cacheReadInputTokens,
+            sampleCount: day.sampleCount,
+            fiveHourPeakUsagePct: usage.fiveHourPeakUsagePct ?? day.fiveHourPeakUsagePct,
+            fiveHourLatestUsagePct: usage.fiveHourLatestUsagePct ?? day.fiveHourLatestUsagePct,
+            sevenDayPeakUsagePct: usage.sevenDayPeakUsagePct ?? day.sevenDayPeakUsagePct,
+            sevenDayLatestUsagePct: usage.sevenDayLatestUsagePct ?? day.sevenDayLatestUsagePct,
+            uniqueSessions: day.uniqueSessions,
+            uniqueWorkspaces: day.uniqueWorkspaces,
+        });
     }
     return rows.sort((left, right) => `${left.personKey}|${left.date}`.localeCompare(`${right.personKey}|${right.date}`));
 }
-/** 直接从 bundle.weeklySummary 展开 weekly.csv。 */
+/** 展开 weekly.csv：同人同周取 winner bundle 的累加值，usage 从该 bundle 全部事件重算。 */
 function buildAggregatedWeeklyRows(bundles) {
-    return bundles
-        .map(({ bundle }) => ({
-        personKey: toPersonKey(bundle.identity.gitUserEmail, bundle.identity.gitUserName),
-        week: weekKey(new Date(bundle.range.start)),
-        userMessageCount: bundle.weeklySummary.counts.userMessageCount,
-        apiRequestCount: bundle.weeklySummary.counts.apiRequestCount,
-        inputTokens: bundle.weeklySummary.tokens.inputTokens,
-        outputTokens: bundle.weeklySummary.tokens.outputTokens,
-        cacheReadInputTokens: bundle.weeklySummary.tokens.cacheReadInputTokens,
-        sampleCount: bundle.weeklySummary.statusline.sampleCount,
-        fiveHourPeakUsagePct: bundle.weeklySummary.statusline.fiveHourPeakUsagePct,
-        fiveHourLatestUsagePct: bundle.weeklySummary.statusline.fiveHourLatestUsagePct,
-        sevenDayPeakUsagePct: bundle.weeklySummary.statusline.sevenDayPeakUsagePct,
-        sevenDayLatestUsagePct: bundle.weeklySummary.statusline.sevenDayLatestUsagePct,
-        uniqueSessions: bundle.weeklySummary.statusline.uniqueSessions,
-        uniqueWorkspaces: bundle.weeklySummary.statusline.uniqueWorkspaces,
-    }))
-        .sort((left, right) => `${left.personKey}|${left.week}`.localeCompare(`${right.personKey}|${right.week}`));
+    const winners = selectWeeklyWinners(bundles);
+    const rows = [];
+    for (const winner of winners.values()) {
+        const summary = winner.bundle.weeklySummary;
+        const usage = recomputeUsage([...bundleEventsByDate(winner.bundle).values()].flat());
+        rows.push({
+            personKey: winner.personKey,
+            week: winner.week,
+            userMessageCount: summary.counts.userMessageCount,
+            apiRequestCount: summary.counts.apiRequestCount,
+            inputTokens: summary.tokens.inputTokens,
+            outputTokens: summary.tokens.outputTokens,
+            cacheReadInputTokens: summary.tokens.cacheReadInputTokens,
+            sampleCount: summary.statusline.sampleCount,
+            fiveHourPeakUsagePct: usage.fiveHourPeakUsagePct ?? summary.statusline.fiveHourPeakUsagePct,
+            fiveHourLatestUsagePct: usage.fiveHourLatestUsagePct ?? summary.statusline.fiveHourLatestUsagePct,
+            sevenDayPeakUsagePct: usage.sevenDayPeakUsagePct ?? summary.statusline.sevenDayPeakUsagePct,
+            sevenDayLatestUsagePct: usage.sevenDayLatestUsagePct ?? summary.statusline.sevenDayLatestUsagePct,
+            uniqueSessions: summary.statusline.uniqueSessions,
+            uniqueWorkspaces: summary.statusline.uniqueWorkspaces,
+        });
+    }
+    return rows.sort((left, right) => `${left.personKey}|${left.week}`.localeCompare(`${right.personKey}|${right.week}`));
 }
 //# sourceMappingURL=aggregate.js.map

package/dist/lib/open.js

@@ -1,18 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.openPath = openPath;
 exports.openInBrowser = openInBrowser;
 const node_child_process_1 = require("node:child_process");
 /**
- * 用系统默认浏览器打开生成好的 dashboard。
+ * 用系统默认程序打开一个文件或目录：HTML 走默认浏览器，目录走文件管理器。
  *
  * 这里不拼接 shell 字符串，而是显式传参数，降低路径注入风险。
  */
-async function openInBrowser(filePath) {
+async function openPath(target) {
     const command = process.platform === "win32"
-        ? { program: "cmd", args: ["/c", "start", "", filePath] }
+        ? { program: "cmd", args: ["/c", "start", "", target] }
         : process.platform === "darwin"
-            ? { program: "open", args: [filePath] }
-            : { program: "xdg-open", args: [filePath] };
+            ? { program: "open", args: [target] }
+            : { program: "xdg-open", args: [target] };
     await new Promise((resolve, reject) => {
         const child = (0, node_child_process_1.spawn)(command.program, command.args, {
             detached: true,
@@ -23,4 +24,8 @@ async function openInBrowser(filePath) {
         resolve();
     });
 }
+/** 用系统默认浏览器打开生成好的 dashboard。 */
+async function openInBrowser(filePath) {
+    await openPath(filePath);
+}
 //# sourceMappingURL=open.js.map

package/dist/lib/paths.js

@@ -7,6 +7,8 @@ exports.getDefaultDataDir = getDefaultDataDir;
 exports.getEventsDir = getEventsDir;
 exports.getDashboardDir = getDashboardDir;
 exports.getUpdateCachePath = getUpdateCachePath;
+exports.getSyncConfigPath = getSyncConfigPath;
+exports.getSyncStatePath = getSyncStatePath;
 exports.getClaudeDataDir = getClaudeDataDir;
 exports.getClaudeSettingsPath = getClaudeSettingsPath;
 const node_os_1 = __importDefault(require("node:os"));
@@ -46,6 +48,14 @@ function getDashboardDir(dataDir) {
 function getUpdateCachePath(dataDir) {
     return node_path_1.default.join(dataDir, "update-check.json");
 }
+/** 定时同步的用户配置文件（目标目录、周期、范围），可手编。 */
+function getSyncConfigPath(dataDir) {
+    return node_path_1.default.join(dataDir, "sync-config.json");
+}
+/** 定时同步的运行时状态文件（上次同步时间与结果），由 ccus sync 写入。 */
+function getSyncStatePath(dataDir) {
+    return node_path_1.default.join(dataDir, "sync-state.json");
+}
 /** Claude Code 默认本地数据目录。 */
 function getClaudeDataDir() {
     const configured = process.env.CCUS_CLAUDE_DATA_DIR;

package/dist/lib/scheduler.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCHEDULE_TIME = exports.SCHEDULE_CRON = exports.SCHEDULE_WEEKDAY_SHORT = exports.SCHEDULER_TASK_NAME = void 0;
+exports.buildCcusSyncInvocation = buildCcusSyncInvocation;
+exports.buildSchedulerPlan = buildSchedulerPlan;
+exports.installScheduler = installScheduler;
+exports.uninstallScheduler = uninstallScheduler;
+const node_child_process_1 = require("node:child_process");
+const debug_1 = require("./debug");
+/** 系统调度器里使用的任务名（Windows 计划任务 / cron 注释里都用它）。 */
+exports.SCHEDULER_TASK_NAME = "ccus-sync";
+/** 调度时间：每周五 18:00（下午 6 点）。 */
+exports.SCHEDULE_WEEKDAY_SHORT = "FRI"; // schtasks 用
+exports.SCHEDULE_CRON = "0 18 * * 5"; // cron 用（周五 = 5）
+exports.SCHEDULE_TIME = "18:00";
+/** 给路径/命令片段加双引号，避免空格被拆分。 */
+function quote(value) {
+    return `"${value}"`;
+}
+/**
+ * 构造 ccus sync 的调用串。
+ *
+ * 优先用绝对的 node + cli.js 路径（调度任务运行时 PATH 可能不含全局 npm bin）；
+ * 拿不到脚本路径时退回 `ccus`。始终带显式 `--data-dir`，与交互式同步用同一目录。
+ */
+function buildCcusSyncInvocation(execPath, scriptPath, dataDir) {
+    if (!scriptPath) {
+        return `ccus sync --data-dir ${quote(dataDir)}`;
+    }
+    return `${quote(execPath)} ${quote(scriptPath)} sync --data-dir ${quote(dataDir)}`;
+}
+/**
+ * 根据平台构造「每周五 18:00 跑 ccus sync」的调度器安装计划。
+ *
+ * Windows 用 `schtasks` 创建计划任务（ccus 可自动执行）；
+ * macOS / Linux 给出 cron 一行命令（由用户手动执行，避免自动改 crontab 的风险）。
+ */
+function buildSchedulerPlan(platform, execPath, scriptPath, dataDir) {
+    const invocation = buildCcusSyncInvocation(execPath, scriptPath, dataDir);
+    if (platform === "win32") {
+        const args = [
+            "/create",
+            "/tn",
+            exports.SCHEDULER_TASK_NAME,
+            "/tr",
+            invocation,
+            "/sc",
+            "weekly",
+            "/d",
+            exports.SCHEDULE_WEEKDAY_SHORT,
+            "/st",
+            exports.SCHEDULE_TIME,
+            "/f",
+        ];
+        return {
+            platform,
+            autoInstallable: true,
+            invocation,
+            command: "schtasks",
+            args,
+            displayCommand: `schtasks /create /tn ${exports.SCHEDULER_TASK_NAME} /tr ${quote(invocation)} /sc weekly /d ${exports.SCHEDULE_WEEKDAY_SHORT} /st ${exports.SCHEDULE_TIME} /f`,
+            uninstallHint: `schtasks /delete /tn ${exports.SCHEDULER_TASK_NAME} /f`,
+        };
+    }
+    // macOS / Linux：给出 cron 一行命令，由用户手动安装。
+    const cronLine = `${exports.SCHEDULE_CRON} ${invocation} # ${exports.SCHEDULER_TASK_NAME}`;
+    return {
+        platform,
+        autoInstallable: false,
+        invocation,
+        command: null,
+        args: null,
+        displayCommand: `(crontab -l 2>/dev/null; echo '${cronLine}') | crontab -`,
+        uninstallHint: `crontab -e  # 删除标注 ${exports.SCHEDULER_TASK_NAME} 的那一行`,
+    };
+}
+/**
+ * 执行调度器安装。
+ *
+ * `print` 为 true 时只返回计划、不执行。Windows 下调用 schtasks 真正创建任务；
+ * 其它平台不自动改系统，交由调用方打印 displayCommand 引导用户手动安装。
+ */
+function installScheduler(execPath, scriptPath, dataDir, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const plan = buildSchedulerPlan(platform, execPath, scriptPath, dataDir);
+    if (options.print || !plan.autoInstallable || !plan.command || !plan.args) {
+        return { plan, installed: false };
+    }
+    (0, debug_1.debugLog)("scheduler", "installing", { command: plan.command, args: plan.args });
+    const result = (0, node_child_process_1.spawnSync)(plan.command, plan.args, { stdio: "inherit" });
+    if (result.status !== 0) {
+        throw new Error(`调度器安装失败（${plan.command} 退出码 ${result.status ?? "未知"}）。可手动运行：\n  ${plan.displayCommand}`);
+    }
+    return { plan, installed: true };
+}
+/**
+ * 卸载「每周五同步」的系统调度器。
+ *
+ * `print` 为 true 时只返回命令、不执行。Windows 调用 `schtasks /delete` 删除任务
+ * （任务不存在时 schtasks 返回非 0，这里视为「未卸载」而非抛错）；其它平台只打印 crontab 提示。
+ */
+function uninstallScheduler(options = {}) {
+    const platform = options.platform ?? process.platform;
+    if (platform === "win32") {
+        const displayCommand = `schtasks /delete /tn ${exports.SCHEDULER_TASK_NAME} /f`;
+        if (options.print) {
+            return { platform, autoUninstallable: true, uninstalled: false, displayCommand };
+        }
+        (0, debug_1.debugLog)("scheduler", "uninstalling", { task: exports.SCHEDULER_TASK_NAME });
+        const result = (0, node_child_process_1.spawnSync)("schtasks", ["/delete", "/tn", exports.SCHEDULER_TASK_NAME, "/f"], { stdio: "inherit" });
+        return { platform, autoUninstallable: true, uninstalled: result.status === 0, displayCommand };
+    }
+    return {
+        platform,
+        autoUninstallable: false,
+        uninstalled: false,
+        displayCommand: `crontab -e  # 删除标注 ${exports.SCHEDULER_TASK_NAME} 的那一行`,
+    };
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/lib/sync.js

@@ -0,0 +1,210 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSyncInterval = parseSyncInterval;
+exports.readSyncConfig = readSyncConfig;
+exports.writeSyncConfig = writeSyncConfig;
+exports.readSyncStateSync = readSyncStateSync;
+exports.isSyncDue = isSyncDue;
+exports.performSync = performSync;
+exports.maybeSpawnBackgroundSync = maybeSpawnBackgroundSync;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const debug_1 = require("./debug");
+const paths_1 = require("./paths");
+const time_1 = require("./time");
+/** 默认同步周期标签：每 3 小时最多同步一次（滚动 TTL）。 */
+const DEFAULT_INTERVAL_LABEL = "3h";
+/** 默认导出范围：当前周 bundle。 */
+const DEFAULT_RANGE = "this-week";
+/**
+ * 解析周期标签。
+ *
+ * `daily`（或空/无法识别）→ 按自然日；`<N>h` / `<N>m` → 滚动 TTL。
+ */
+function parseSyncInterval(label) {
+    const raw = (label ?? "").trim().toLowerCase();
+    if (raw === "" || raw === "daily") {
+        return { kind: "daily" };
+    }
+    const match = raw.match(/^(\d+)([hm])$/);
+    if (match) {
+        const amount = Number.parseInt(match[1], 10);
+        const ms = match[2] === "h" ? amount * 60 * 60 * 1000 : amount * 60 * 1000;
+        return { kind: "ttl", ms };
+    }
+    // 无法识别的标签退回每天语义，保持「默认每天」的承诺。
+    return { kind: "daily" };
+}
+/** 把同一本地日映射成稳定日键，用于 daily 周期的「是否跨天」判断。 */
+function localDayKey(date) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const day = String(date.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+}
+/**
+ * 同步读取用户配置；缺省补齐默认值，任何异常都回退到「无目标目录」的安全默认。
+ *
+ * statusline 兜底路径需要同步、极快、绝不抛错，所以这里用同步 IO。
+ */
+function readSyncConfig(dataDir) {
+    const fallback = { targetDir: null, intervalLabel: DEFAULT_INTERVAL_LABEL, range: DEFAULT_RANGE };
+    try {
+        const raw = node_fs_1.default.readFileSync((0, paths_1.getSyncConfigPath)(dataDir), "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            targetDir: typeof parsed.targetDir === "string" && parsed.targetDir.trim() !== "" ? parsed.targetDir : null,
+            intervalLabel: typeof parsed.intervalLabel === "string" && parsed.intervalLabel.trim() !== "" ? parsed.intervalLabel : DEFAULT_INTERVAL_LABEL,
+            range: typeof parsed.range === "string" && parsed.range.trim() !== "" ? parsed.range : DEFAULT_RANGE,
+        };
+    }
+    catch {
+        return fallback;
+    }
+}
+/** 写入用户配置；目录可能尚未创建，先 mkdir。 */
+async function writeSyncConfig(dataDir, config) {
+    await promises_1.default.mkdir(dataDir, { recursive: true });
+    await promises_1.default.writeFile((0, paths_1.getSyncConfigPath)(dataDir), `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+/** 同步读取运行时状态；缺失或损坏一律返回 null。 */
+function readSyncStateSync(dataDir) {
+    try {
+        const raw = node_fs_1.default.readFileSync((0, paths_1.getSyncStatePath)(dataDir), "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            lastSyncedAt: typeof parsed.lastSyncedAt === "string" ? parsed.lastSyncedAt : null,
+            lastResult: parsed.lastResult === "ok" || parsed.lastResult === "error" ? parsed.lastResult : null,
+            lastError: typeof parsed.lastError === "string" ? parsed.lastError : undefined,
+            lastArchivedWeek: typeof parsed.lastArchivedWeek === "string" ? parsed.lastArchivedWeek : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** 写入运行时状态；失败静默（不能因状态写入失败影响主流程）。 */
+async function writeSyncState(dataDir, state) {
+    try {
+        await promises_1.default.mkdir(dataDir, { recursive: true });
+        await promises_1.default.writeFile((0, paths_1.getSyncStatePath)(dataDir), `${JSON.stringify(state, null, 2)}\n`, "utf8");
+    }
+    catch (error) {
+        (0, debug_1.debugLog)("sync", "failed to write state", error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * 判断当前是否到了该同步的时间点。
+ *
+ * 无目标目录永远返回 false；从未同步过返回 true；
+ * `daily` 用「上次同步与现在不在同一自然日」判断（最贴近「每天」），其它用滚动 TTL。
+ */
+function isSyncDue(config, state, now = new Date()) {
+    if (!config.targetDir) {
+        return false;
+    }
+    if (!state || !state.lastSyncedAt) {
+        return true;
+    }
+    const last = Date.parse(state.lastSyncedAt);
+    if (!Number.isFinite(last)) {
+        return true;
+    }
+    const interval = parseSyncInterval(config.intervalLabel);
+    if (interval.kind === "daily") {
+        return localDayKey(new Date(last)) !== localDayKey(now);
+    }
+    return now.getTime() - last >= interval.ms;
+}
+/**
+ * 导出某个 range 的 bundle，并复制到目标目录下对应的「按周」子目录。
+ *
+ * 复制语义：本地 exports 仍保留一份，目标目录再放一份。周目录名按导出窗口的周一~周日推导。
+ */
+async function exportAndCopy(dataDir, runExport, targetDir, range) {
+    const { outputPath, window } = await runExport({ "data-dir": dataDir, range });
+    const weekDir = (0, time_1.formatWeekDirName)(window.start, window.end);
+    const targetWeekDir = node_path_1.default.join(targetDir, weekDir);
+    await promises_1.default.mkdir(targetWeekDir, { recursive: true });
+    const destPath = node_path_1.default.join(targetWeekDir, node_path_1.default.basename(outputPath));
+    await promises_1.default.copyFile(outputPath, destPath);
+    (0, debug_1.debugLog)("sync", "copied bundle", { range, outputPath, destPath, weekDir });
+    return { outputPath, destPath, weekDir, targetWeekDir };
+}
+/**
+ * 执行一次同步：导出当前周 bundle，并复制到目标目录下的「按周」子目录。
+ *
+ * 复制语义：本地 exports 仍保留一份，目标目录再放一份，本地照旧可 aggregate / dashboard。
+ * 周一时额外把上一周（last-week，刚结束的完整周）导出并归档到对应子目录；
+ * 用 `sync-state.lastArchivedWeek` 去重，避免周一当天每次同步都重复归档。
+ * 失败时写 error 状态后向上抛，由调用方决定展示或静默。
+ */
+async function performSync(dataDir, runExport, now = new Date()) {
+    const config = readSyncConfig(dataDir);
+    if (!config.targetDir) {
+        throw new Error("未配置同步目标目录。请先运行 `ccus sync config --target DIR`。");
+    }
+    const state = readSyncStateSync(dataDir);
+    let lastArchivedWeek = state?.lastArchivedWeek;
+    try {
+        const primary = await exportAndCopy(dataDir, runExport, config.targetDir, config.range);
+        // 周一（getDay() === 1）是上一周结束后第一个能拿到完整数据的日子：顺带归档 last-week。
+        let archivedLastWeekDest = null;
+        if (now.getDay() === 1) {
+            const lastWeek = (0, time_1.resolveRange)("last-week", now);
+            const lastWeekDir = (0, time_1.formatWeekDirName)(lastWeek.start, lastWeek.end);
+            if (lastArchivedWeek !== lastWeekDir) {
+                const archived = await exportAndCopy(dataDir, runExport, config.targetDir, "last-week");
+                lastArchivedWeek = archived.weekDir;
+                archivedLastWeekDest = archived.destPath;
+                (0, debug_1.debugLog)("sync", "archived last week", { weekDir: archived.weekDir, destPath: archived.destPath });
+            }
+        }
+        await writeSyncState(dataDir, { lastSyncedAt: now.toISOString(), lastResult: "ok", lastArchivedWeek });
+        return { ...primary, archivedLastWeekDest };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        await writeSyncState(dataDir, { lastSyncedAt: now.toISOString(), lastResult: "error", lastError: message, lastArchivedWeek });
+        throw error;
+    }
+}
+/**
+ * 如到了同步周期，spawn 一个 detached 后台进程执行同步，主进程不等待。
+ *
+ * 这是 statusline 路径能用的唯一安全方式（照搬 update-check 的 maybeSpawnBackgroundCheck）：
+ * 同步读配置与状态决定是否触发，把 export + 复制甩给后台子进程，自己立刻返回。
+ * 未配置目标目录、或未到周期，都直接返回，对 statusline 单行 stdout 契约零侵入。
+ */
+function maybeSpawnBackgroundSync(dataDir, now = new Date()) {
+    try {
+        const config = readSyncConfig(dataDir);
+        if (!config.targetDir) {
+            return;
+        }
+        if (!isSyncDue(config, readSyncStateSync(dataDir), now)) {
+            return;
+        }
+        const scriptPath = process.argv[1];
+        if (!scriptPath) {
+            return;
+        }
+        const child = (0, node_child_process_1.spawn)(process.execPath, [scriptPath, "__sync", "--data-dir", dataDir], {
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        child.on("error", () => { });
+        child.unref();
+        (0, debug_1.debugLog)("sync", "spawned background sync");
+    }
+    catch (error) {
+        (0, debug_1.debugLog)("sync", "failed to spawn background sync", error instanceof Error ? error.message : String(error));
+    }
+}
+//# sourceMappingURL=sync.js.map

package/dist/lib/time.js

@@ -4,6 +4,7 @@ exports.resolveRange = resolveRange;
 exports.expandToFullWeekWindow = expandToFullWeekWindow;
 exports.localDateKey = localDateKey;
 exports.formatRangeFileLabel = formatRangeFileLabel;
+exports.formatWeekDirName = formatWeekDirName;
 exports.extractGitEmailAccount = extractGitEmailAccount;
 exports.formatGitEmailFilePrefix = formatGitEmailFilePrefix;
 exports.enumerateDateKeys = enumerateDateKeys;
@@ -104,6 +105,16 @@ function localDateKey(date) {
 function formatRangeFileLabel(start, end) {
     return `${localDateKey(start)}_to_${localDateKey(end)}`;
 }
+/**
+ * 生成定时同步目标目录下「按周」子目录名：年_月_日_年_月_日（全下划线）。
+ *
+ * 与 formatRangeFileLabel 同源（都基于 localDateKey 的周一~周日窗口），
+ * 但分隔符统一成下划线，例如 `2026_06_01_2026_06_07`。
+ */
+function formatWeekDirName(start, end) {
+    const normalize = (date) => localDateKey(date).replaceAll("-", "_");
+    return `${normalize(start)}_${normalize(end)}`;
+}
 /**
  * 从 git email 中提取规范化的帐号名（@ 之前的部分，小写并清洗特殊字符）。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccus-cli",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Claude Code statusline usage logger and dashboard CLI",
   "type": "commonjs",
   "bin": {
@@ -15,7 +15,7 @@
     "build": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build",
     "test": "node --test dist/test",
-    "test:src": "node --import tsx --test src/test/payload.test.ts src/test/dashboard.test.ts src/test/export.test.ts src/test/storage.test.ts src/test/claude.test.ts src/test/aggregate.test.ts src/test/aggregate-dashboard.test.ts src/test/install.test.ts src/test/debug.test.ts src/test/time.test.ts src/test/update-check.test.ts"
+    "test:src": "node --import tsx --test src/test/payload.test.ts src/test/dashboard.test.ts src/test/export.test.ts src/test/storage.test.ts src/test/claude.test.ts src/test/aggregate.test.ts src/test/aggregate-dashboard.test.ts src/test/install.test.ts src/test/debug.test.ts src/test/time.test.ts src/test/update-check.test.ts src/test/sync.test.ts src/test/scheduler.test.ts"
   },
   "keywords": [
     "claude-code",