ccus-cli 0.1.10 → 0.1.12

package/README.md

@@ -8,6 +8,7 @@
 - `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` 查看当前版本。
 
@@ -84,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                            # 查看同步配置与上次同步时间
 ```
 
 ### 一键安装（推荐）
@@ -175,6 +180,48 @@ ccus aggregate serve --input-dir ./team-exports
 - 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 --suffix laptop                 # 给目标文件名加机器后缀，区分多台电脑
+ccus sync config --no-suffix                     # 移除已配置的机器后缀
+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 --suffix laptop` 会在**目标目录副本**的文件名扩展名前加 `-laptop`（如 `…_to_2026-06-07-laptop.json.gz`），本地原文件名不变。同一个人多台电脑同步到同一目标目录时，靠后缀让各机器的文件互不覆盖、都保留下来，正好供 `ccus aggregate` 按 personKey 合并去重。用 `ccus sync config --no-suffix` 移除后缀。
+- **配置与同步分离**：`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 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`);
+    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] [--suffix NAME | --no-suffix] [--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`);
 }
 /**
@@ -619,6 +631,148 @@ 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");
+    const suffix = getStringOption(options, "suffix");
+    if (target !== undefined || interval !== undefined || range !== undefined || suffix !== 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,
+            suffix: suffix !== undefined ? (0, sync_1.sanitizeSuffix)(suffix) : current.suffix,
+        };
+        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}`,
+        `文件后缀: ${config.suffix ?? "(无)"}`,
+        `上次同步: ${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 suffix = getStringOption(options, "suffix");
+    const clearSuffix = getBooleanOption(options, "no-suffix");
+    const current = (0, sync_1.readSyncConfig)(dataDir);
+    const changed = target !== undefined || interval !== undefined || range !== undefined || suffix !== undefined || clearSuffix;
+    const next = {
+        targetDir: target !== undefined ? node_path_1.default.resolve(target) : current.targetDir,
+        intervalLabel: interval ?? current.intervalLabel,
+        range: range ?? current.range,
+        // --no-suffix 优先清除；否则有 --suffix 就更新，没有就保持原值。
+        suffix: clearSuffix ? null : suffix !== undefined ? (0, sync_1.sanitizeSuffix)(suffix) : current.suffix,
+    };
+    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  文件后缀: ${next.suffix ?? "(无)"}\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));
@@ -645,6 +799,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/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,249 @@
+"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.sanitizeSuffix = sanitizeSuffix;
+exports.applyFileSuffix = applyFileSuffix;
+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" };
+}
+/**
+ * 清洗用户传入的文件名后缀：去首尾分隔、把非法字符折叠成连字符。
+ *
+ * 只保留字母数字与 `._-`，避免生成非法/危险的文件名；清洗后为空则返回 null。
+ */
+function sanitizeSuffix(raw) {
+    if (raw === undefined) {
+        return null;
+    }
+    const cleaned = raw
+        .trim()
+        .replaceAll(/[^a-zA-Z0-9._-]+/g, "-")
+        .replaceAll(/-+/g, "-")
+        .replaceAll(/^[-_.]+|[-_.]+$/g, "");
+    return cleaned === "" ? null : cleaned;
+}
+/**
+ * 把后缀插到文件名的扩展名之前（`.json.gz` / `.json` 视为整体扩展名）。
+ *
+ * 例如 `alice_export_2026-06-01_to_2026-06-07.json.gz` + `laptop`
+ * → `alice_export_2026-06-01_to_2026-06-07-laptop.json.gz`。
+ */
+function applyFileSuffix(fileName, suffix) {
+    if (!suffix) {
+        return fileName;
+    }
+    const tag = `-${suffix}`;
+    for (const ext of [".json.gz", ".json"]) {
+        if (fileName.endsWith(ext)) {
+            return `${fileName.slice(0, fileName.length - ext.length)}${tag}${ext}`;
+        }
+    }
+    const ext = node_path_1.default.extname(fileName);
+    return `${fileName.slice(0, fileName.length - ext.length)}${tag}${ext}`;
+}
+/** 把同一本地日映射成稳定日键，用于 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, suffix: null };
+    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,
+            suffix: typeof parsed.suffix === "string" && parsed.suffix.trim() !== "" ? parsed.suffix : null,
+        };
+    }
+    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, suffix) {
+    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 });
+    // 后缀只加在目标目录的副本上，本地 exports 原文件名保持不变。
+    const destPath = node_path_1.default.join(targetWeekDir, applyFileSuffix(node_path_1.default.basename(outputPath), suffix));
+    await promises_1.default.copyFile(outputPath, destPath);
+    (0, debug_1.debugLog)("sync", "copied bundle", { range, outputPath, destPath, weekDir, suffix });
+    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, config.suffix);
+        // 周一（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", config.suffix);
+                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.10",
+  "version": "0.1.12",
   "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",