ccus-cli 0.1.4 → 0.1.6

package/README.md

@@ -5,9 +5,10 @@
 - `ccus install`：自动把 statusLine 命令写进 Claude Code 的 `settings.json`，省去手动改配置。
 - `ccus statusline emit`：读取 Claude Code statusline 通过 `stdin` 传入的 JSON，输出 statusline 文本，并写入本地日志（加 `--no-store` / `--no-log` 则只输出、不落盘）。
 - `ccus dashboard serve`：直接启动本地 Web 页面，不用先手动生成 HTML 文件。
-- `ccus export`：默认导出当前周数据包，里面同时包含原始事件和按天维度的周汇总。
-- `ccus aggregate`：读取一个目录里的多人 export bundle json，输出明细、按天、按周三个 CSV。
+- `ccus export`：默认导出当前周数据包（gzip 压缩的 `.json.gz`），里面同时包含原始事件和按天维度的周汇总。
+- `ccus aggregate`：读取一个目录里的多人 export bundle（`.json.gz` 或 `.json`），输出明细、按天、按周三个 CSV。
 - `ccus aggregate serve`：同样以 bundle 目录为输入，启动本地多人 dashboard 页面，不落地任何文件。
+- `ccus update`：主动检查 npm 上是否有新版本，有则提示手动升级命令；`ccus --version` 查看当前版本。
 
 > **支持范围**：`ccus statusline emit` 依赖 Claude Code 的 statusLine 机制（从 `stdin` 读 JSON、向 `stdout` 回一行文本），**只在命令行版 Claude Code（CLI / 终端）里生效**。
 >
@@ -23,6 +24,27 @@ npm install -g ccus-cli
 
 要求 Node.js >= 20。
 
+## 更新检查
+
+ccus 通过 npm 全局安装，自带一个轻量的更新检查：
+
+- statusline 渲染时会**异步、节流（每天最多一次）**地向 npm registry 查询最新版本，结果缓存到数据目录下的 `update-check.json`。检查在 detached 后台进程里完成，**不阻塞 statusline、不污染单行输出**。
+- 一旦发现有更新，statusline 行尾会追加一个小标记，例如 `… | ⏱ 11:44 | ⬆ v0.1.5`。
+- 看到标记后手动升级即可：
+
+```bash
+npm i -g ccus-cli@latest
+```
+
+也可以随时主动检查：
+
+```bash
+ccus update        # 立即查 registry，有新版本则打印升级命令
+ccus --version     # 查看当前安装的版本
+```
+
+> 出于稳妥考虑，ccus **只提示、不自动替你执行全局安装**。如需走私服或镜像（如 npmmirror），设置环境变量 `CCUS_REGISTRY` 指向对应 registry 即可。
+
 ## 快速开始
 
 全局安装后，一条命令把 statusline 接进 Claude Code：
@@ -91,7 +113,7 @@ ccus export --range today
 ccus export --range last-week
 ccus export lw                 # 位置参数简写，等价于 --range last-week
 ccus export tw                 # 等价于 --range this-week
-ccus export --out ./alice_export_2026-05-26_to_2026-06-01.json
+ccus export --out ./alice_export_2026-05-26_to_2026-06-01.json   # --out 指定非 .gz 路径时写明文 JSON
 ccus aggregate --input-dir ./team-exports --out-dir ./team-report
 ccus aggregate serve --input-dir ./team-exports
 ```
@@ -113,8 +135,10 @@ ccus aggregate serve --input-dir ./team-exports
 - 默认导出 `this-week`；如需导出上一个完整周（周一到周日），用 `--range last-week`，或位置参数简写 `ccus export lw`（`tw` = 本周）
 - 周度导出固定覆盖**完整一周（周一到周日）**：`this-week` 即使本周还没过完、后面几天还没有任何数据，文件名的起止日期也会补齐到本周日，`dailySummaries` 同样按整周 7 天逐日输出
 - 默认输出一个 `json` 数据包，里面同时包含 `rawEvents`、`weeklySummary`、`dailySummaries`
+- 导出文件内容为**紧凑 JSON**（无缩进），并默认 **gzip 压缩**后写成 `.json.gz`；gzip 与紧凑化都只是存储/展示层变化，解压后的字段集合与 `schemaVersion` 不变
+- 默认写 `.json.gz`；若用 `--out` 指定一个非 `.gz` 结尾的路径，则按明文 JSON 写出（不压缩）
 - 当前导出 bundle / weeklySummary 的 `schemaVersion` 为 `6`，用于标识已使用 `fiveHourLatestUsagePct`、`fiveHourPeakUsagePct`、`sevenDayLatestUsagePct`、`sevenDayPeakUsagePct` 字段的新导出契约
-- 默认文件名会带 git email 的帐号名前缀和起止日期，例如：`alice_export_2026-05-26_to_2026-06-01.json`
+- 默认文件名会带 git email 的帐号名前缀和起止日期，例如：`alice_export_2026-05-26_to_2026-06-01.json.gz`
 - `userMessageCount` 来自 `~/.claude/projects/**/*.jsonl` 的非 meta `type:user` 事件
 - `apiRequestCount` 与 token 指标来自 `~/.claude/projects/**/*.jsonl` 中带 `message.usage` 的 `type:assistant` 事件
 - `dailySummaries` 会按每天输出消息数、请求数、token 和当天 statusline usage 摘要
@@ -122,7 +146,7 @@ ccus aggregate serve --input-dir ./team-exports
 
 ## 多人汇总
 
-- 输入目录放很多通过 `ccus export` 导出的 bundle `.json` 文件
+- 输入目录放很多通过 `ccus export` 导出的 bundle 文件，`.json.gz`（gzip 压缩）与明文 `.json` 都能识别，gzip 文件读取时自动解压
 - `aggregate` 目前只接受 `schemaVersion: 6` 的 bundle；旧导出请先用当前版本重新 `ccus export`
 - `ccus aggregate --input-dir DIR --out-dir DIR`
 - 输出三个文件：

package/dist/cli.js

@@ -55,9 +55,11 @@ const payload_1 = require("./lib/payload");
 const paths_1 = require("./lib/paths");
 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\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 update [--data-dir PATH]\n  ccus --version\n\nGlobal flags:\n  --verbose | --debug | -v   输出详细调试日志到 stderr（等价于设置 CCUS_DEBUG=1），方便排查问题\n`);
 }
 /** 一个轻量的参数解析器，当前命令面不复杂，没必要引入额外依赖。 */
 function parseOptions(args) {
@@ -174,7 +176,12 @@ async function handleStatuslineEmit(options) {
             gitUserAccount: event.gitUserAccount,
             gitBranch,
         });
-        process.stdout.write(`${event.statusLine}\n`);
+        // 更新检查必须对 statusline 完全无侵入：同步读旧缓存决定是否在行尾追加小标记，
+        // 把网络请求甩给 detached 后台进程，主进程不等待、失败静默。
+        (0, update_check_1.maybeSpawnBackgroundCheck)(dataDir);
+        const notice = (0, update_check_1.computeUpdateNotice)(dataDir);
+        const statusLine = notice ? `${event.statusLine} | ${notice}` : event.statusLine;
+        process.stdout.write(`${statusLine}\n`);
     }
     catch (error) {
         // 正常路径不能因为采样失败把 statusline 弄挂，所以这里仍然降级输出兜底文本；
@@ -399,10 +406,17 @@ async function handleExport(options) {
     const content = (0, export_1.buildWeeklyExportBundleJson)(bundle);
     const fileLabel = (0, time_1.formatRangeFileLabel)(window.start, window.end);
     const gitEmailPrefix = (0, time_1.formatGitEmailFilePrefix)(exportUserEmail);
-    const defaultFileName = gitEmailPrefix ? `${gitEmailPrefix}_export_${fileLabel}.json` : `export_${fileLabel}.json`;
+    // 默认导出 gzip 压缩的 bundle（.json.gz）以缩减体积；用户用 --out 指定非 .gz 路径时仍写明文 JSON。
+    const defaultFileName = gitEmailPrefix ? `${gitEmailPrefix}_export_${fileLabel}.json.gz` : `export_${fileLabel}.json.gz`;
     const outputPath = node_path_1.default.resolve(output ?? node_path_1.default.join(dataDir, "exports", defaultFileName));
-    await (0, export_1.writeTextFile)(outputPath, content);
-    (0, debug_1.debugLog)("export", "bundle written", { outputPath, bytes: content.length });
+    const compressed = outputPath.endsWith(".gz");
+    if (compressed) {
+        await (0, export_1.writeGzipFile)(outputPath, content);
+    }
+    else {
+        await (0, export_1.writeTextFile)(outputPath, content);
+    }
+    (0, debug_1.debugLog)("export", "bundle written", { outputPath, rawBytes: content.length, compressed });
     process.stdout.write(`${outputPath}\n`);
 }
 /**
@@ -518,6 +532,43 @@ function resolveExportOptions(action, args, rest) {
     }
     return options;
 }
+/**
+ * `ccus update`：用户主动检查更新（绕过 24h 节流）。
+ *
+ * 根据当前的产品选择，这里只做「检查 + 提示」，不替用户执行全局安装。
+ * 有新版本时打印应当手动运行的 `npm i -g` 命令。
+ */
+async function handleUpdate(options) {
+    const dataDir = getDataDir(options);
+    const current = (0, version_1.getCurrentVersion)();
+    let latest;
+    try {
+        latest = await (0, update_check_1.fetchLatestVersion)();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stdout.write(`无法检查更新：${message}\n当前版本 v${current}\n`);
+        return;
+    }
+    // 顺手刷新缓存，让 statusline 标记和这次检查结果保持一致。
+    await (0, update_check_1.performUpdateCheck)(dataDir);
+    if ((0, version_1.isNewerVersion)(latest, current)) {
+        process.stdout.write(`发现新版本：v${current} -> v${latest}\n运行以下命令升级：\n  npm i -g ccus-cli@latest\n`);
+    }
+    else {
+        process.stdout.write(`已是最新版本 v${current}\n`);
+    }
+}
+/**
+ * 隐藏命令 `__check-update`：由 statusline 路径以 detached 后台进程触发。
+ *
+ * 只做一件事：查 registry 并写缓存。不输出任何东西到 stdout（它不是被人看的），
+ * 失败也静默，绝不影响触发它的 statusline 主进程。
+ */
+async function handleBackgroundCheckUpdate(options) {
+    const dataDir = getDataDir(options);
+    await (0, update_check_1.performUpdateCheck)(dataDir);
+}
 /** 顶层命令分发入口。 */
 async function main(args = process.argv.slice(2)) {
     (0, debug_1.setDebugEnabled)((0, debug_1.resolveDebugEnabled)(args));
@@ -528,6 +579,18 @@ async function main(args = process.argv.slice(2)) {
         printHelp();
         return;
     }
+    if (group === "--version" || group === "-V" || group === "version") {
+        process.stdout.write(`${(0, version_1.getCurrentVersion)()}\n`);
+        return;
+    }
+    if (group === "update") {
+        await handleUpdate(parseOptions(args.slice(1)));
+        return;
+    }
+    if (group === "__check-update") {
+        await handleBackgroundCheckUpdate(parseOptions(args.slice(1)));
+        return;
+    }
     if (group === "install") {
         await handleInstall(parseOptions(args.slice(1)));
         return;

package/dist/lib/aggregate.js

@@ -9,8 +9,11 @@ exports.buildAggregatedDailyRows = buildAggregatedDailyRows;
 exports.buildAggregatedWeeklyRows = buildAggregatedWeeklyRows;
 const promises_1 = __importDefault(require("node:fs/promises"));
 const node_path_1 = __importDefault(require("node:path"));
+const node_util_1 = require("node:util");
+const node_zlib_1 = require("node:zlib");
 const payload_1 = require("./payload");
 const time_1 = require("./time");
+const gunzipAsync = (0, node_util_1.promisify)(node_zlib_1.gunzip);
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -59,6 +62,10 @@ function weekKey(date) {
 function toPersonKey(gitUserEmail, gitUserName) {
     return (0, time_1.extractGitEmailAccount)(gitUserEmail) ?? gitUserName ?? "unknown";
 }
+/** bundle 文件可以是明文 `.json`，也可以是 `ccus export` 默认输出的 gzip 压缩 `.json.gz`。 */
+function isBundleFileName(name) {
+    return name.endsWith(".json") || name.endsWith(".json.gz");
+}
 async function collectBundleJsonFiles(directoryPath) {
     const entries = await promises_1.default.readdir(directoryPath, { withFileTypes: true });
     const nested = await Promise.all(entries.map(async (entry) => {
@@ -66,10 +73,19 @@ async function collectBundleJsonFiles(directoryPath) {
         if (entry.isDirectory()) {
             return collectBundleJsonFiles(fullPath);
         }
-        return entry.isFile() && entry.name.endsWith(".json") ? [fullPath] : [];
+        return entry.isFile() && isBundleFileName(entry.name) ? [fullPath] : [];
     }));
     return nested.flat();
 }
+/** 读取 bundle 文件内容：`.gz` 结尾的先 gunzip 再按 UTF-8 解码，其它按明文读取。 */
+async function readBundleFileContent(filePath) {
+    if (filePath.endsWith(".gz")) {
+        const compressed = await promises_1.default.readFile(filePath);
+        const decompressed = await gunzipAsync(compressed);
+        return decompressed.toString("utf8");
+    }
+    return promises_1.default.readFile(filePath, "utf8");
+}
 /** 读取目录里的 export bundle json 文件。 */
 async function loadWeeklyExportBundles(inputDir) {
     const files = await collectBundleJsonFiles(inputDir);
@@ -77,7 +93,7 @@ async function loadWeeklyExportBundles(inputDir) {
     const invalidFiles = [];
     for (const filePath of files) {
         try {
-            const content = await promises_1.default.readFile(filePath, "utf8");
+            const content = await readBundleFileContent(filePath);
             const parsed = JSON.parse(content);
             if (isWeeklyExportBundle(parsed)) {
                 bundles.push({ filePath, bundle: parsed });

package/dist/lib/export.js

@@ -13,9 +13,13 @@ exports.buildSummaryCsv = buildSummaryCsv;
 exports.buildAggregatedDailyCsv = buildAggregatedDailyCsv;
 exports.buildAggregatedWeeklyCsv = buildAggregatedWeeklyCsv;
 exports.writeTextFile = writeTextFile;
+exports.writeGzipFile = writeGzipFile;
 const promises_1 = __importDefault(require("node:fs/promises"));
 const node_path_1 = __importDefault(require("node:path"));
+const node_util_1 = require("node:util");
+const node_zlib_1 = require("node:zlib");
 const time_1 = require("./time");
+const gzipAsync = (0, node_util_1.promisify)(node_zlib_1.gzip);
 /** CSV 字符串字段统一做转义，避免逗号和引号破坏列结构。 */
 function quoteCsv(value) {
     return `"${value.replaceAll("\"", "\"\"")}"`;
@@ -128,9 +132,9 @@ function buildRawJsonl(events) {
 function buildWeeklySummaryJson(summary) {
     return `${JSON.stringify(summary, null, 2)}\n`;
 }
-/** 默认导出把原始事件与周汇总一起打包成一个 JSON 文件。 */
+/** 默认导出把原始事件与周汇总一起打包成一个 JSON 文件，用紧凑序列化避免缩进空白撑大体积。 */
 function buildWeeklyExportBundleJson(bundle) {
-    return `${JSON.stringify(bundle, null, 2)}\n`;
+    return `${JSON.stringify(bundle)}\n`;
 }
 /** 按天汇总 usage 数据，生成 summary 模式的中间结果。 */
 function buildSummaryRows(events) {
@@ -272,4 +276,15 @@ async function writeTextFile(outputPath, content) {
     await promises_1.default.mkdir(node_path_1.default.dirname(outputPath), { recursive: true });
     await promises_1.default.writeFile(outputPath, content, "utf8");
 }
+/**
+ * 把内容 gzip 压缩后写文件，父目录不存在时自动创建。
+ *
+ * 仅压缩存储/传输层，写入的字节解压后与 `writeTextFile` 完全一致，
+ * 不改变 bundle 字段集合，也不影响 schemaVersion。
+ */
+async function writeGzipFile(outputPath, content) {
+    await promises_1.default.mkdir(node_path_1.default.dirname(outputPath), { recursive: true });
+    const compressed = await gzipAsync(content);
+    await promises_1.default.writeFile(outputPath, compressed);
+}
 //# sourceMappingURL=export.js.map

package/dist/lib/paths.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getDefaultDataDir = getDefaultDataDir;
 exports.getEventsDir = getEventsDir;
 exports.getDashboardDir = getDashboardDir;
+exports.getUpdateCachePath = getUpdateCachePath;
 exports.getClaudeDataDir = getClaudeDataDir;
 exports.getClaudeSettingsPath = getClaudeSettingsPath;
 const node_os_1 = __importDefault(require("node:os"));
@@ -41,6 +42,10 @@ function getEventsDir(dataDir) {
 function getDashboardDir(dataDir) {
     return node_path_1.default.join(dataDir, "dashboard");
 }
+/** 版本更新检查的本地缓存文件，记录上次检查时间与拿到的最新版本。 */
+function getUpdateCachePath(dataDir) {
+    return node_path_1.default.join(dataDir, "update-check.json");
+}
 /** Claude Code 默认本地数据目录。 */
 function getClaudeDataDir() {
     const configured = process.env.CCUS_CLAUDE_DATA_DIR;

package/dist/lib/update-check.js

@@ -0,0 +1,180 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readUpdateCacheSync = readUpdateCacheSync;
+exports.fetchLatestVersion = fetchLatestVersion;
+exports.performUpdateCheck = performUpdateCheck;
+exports.maybeSpawnBackgroundCheck = maybeSpawnBackgroundCheck;
+exports.computeUpdateNotice = computeUpdateNotice;
+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_https_1 = __importDefault(require("node:https"));
+const debug_1 = require("./debug");
+const paths_1 = require("./paths");
+const version_1 = require("./version");
+/** npm 包名，更新检查向 registry 查询它的最新版本。 */
+const PACKAGE_NAME = "ccus-cli";
+/** 后台检查节流窗口：同一数据目录每天最多向 registry 查一次。 */
+const CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+/** 网络请求超时，避免后台进程长时间挂着；statusline 主进程本身不等它。 */
+const FETCH_TIMEOUT_MS = 4000;
+/**
+ * 同步读取更新缓存。
+ *
+ * statusline 是高频短命进程，这里只读一个很小的 JSON，用同步 IO 换取最简单、最快的路径；
+ * 任何异常都静默返回 null，绝不影响状态行输出。
+ */
+function readUpdateCacheSync(dataDir) {
+    try {
+        const raw = node_fs_1.default.readFileSync((0, paths_1.getUpdateCachePath)(dataDir), "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.lastCheckedAt !== "string") {
+            return null;
+        }
+        return {
+            lastCheckedAt: parsed.lastCheckedAt,
+            latestVersion: typeof parsed.latestVersion === "string" ? parsed.latestVersion : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** 写入更新缓存；目录可能尚未创建，所以先 mkdir。失败静默。 */
+async function writeUpdateCache(dataDir, cache) {
+    try {
+        await promises_1.default.mkdir(dataDir, { recursive: true });
+        await promises_1.default.writeFile((0, paths_1.getUpdateCachePath)(dataDir), `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+    }
+    catch (error) {
+        (0, debug_1.debugLog)("update", "failed to write cache", error instanceof Error ? error.message : String(error));
+    }
+}
+/** registry 基地址，允许用 CCUS_REGISTRY 指向私服或镜像（如 npmmirror）。 */
+function getRegistryBase(env = process.env) {
+    const configured = (env.CCUS_REGISTRY ?? "").trim();
+    const base = configured || "https://registry.npmjs.org";
+    return base.replace(/\/+$/, "");
+}
+/**
+ * 向 npm registry 查询最新发布版本。
+ *
+ * 走 `/<pkg>/latest` 这个轻量端点，只取 `version` 字段；超时或任何错误都 reject，
+ * 由调用方决定是否静默。
+ */
+function fetchLatestVersion(env = process.env) {
+    const url = `${getRegistryBase(env)}/${PACKAGE_NAME}/latest`;
+    return new Promise((resolve, reject) => {
+        const request = node_https_1.default.get(url, { headers: { accept: "application/json" } }, (response) => {
+            const status = response.statusCode ?? 0;
+            if (status < 200 || status >= 300) {
+                response.resume();
+                reject(new Error(`registry responded ${status}`));
+                return;
+            }
+            let body = "";
+            response.setEncoding("utf8");
+            response.on("data", (chunk) => {
+                body += chunk;
+            });
+            response.on("end", () => {
+                try {
+                    const parsed = JSON.parse(body);
+                    if (typeof parsed.version === "string") {
+                        resolve(parsed.version);
+                    }
+                    else {
+                        reject(new Error("registry payload missing version"));
+                    }
+                }
+                catch (error) {
+                    reject(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+        });
+        request.setTimeout(FETCH_TIMEOUT_MS, () => {
+            request.destroy(new Error("registry request timed out"));
+        });
+        request.on("error", reject);
+    });
+}
+/**
+ * 真正执行一次检查并把结果写进缓存。
+ *
+ * 供隐藏命令 `__check-update`（statusline 后台触发）和 `ccus update`（用户主动）复用。
+ * 即使 registry 失败也会更新 lastCheckedAt，避免反复重试打爆 registry。
+ */
+async function performUpdateCheck(dataDir) {
+    let latestVersion = null;
+    try {
+        latestVersion = await fetchLatestVersion();
+        (0, debug_1.debugLog)("update", "fetched latest version", latestVersion);
+    }
+    catch (error) {
+        (0, debug_1.debugLog)("update", "fetch failed", error instanceof Error ? error.message : String(error));
+    }
+    const cache = {
+        lastCheckedAt: new Date().toISOString(),
+        latestVersion,
+    };
+    await writeUpdateCache(dataDir, cache);
+    return cache;
+}
+/** 缓存是否已过 TTL（或根本不存在），需要重新向 registry 查询。 */
+function isCacheStale(cache, now) {
+    if (!cache) {
+        return true;
+    }
+    const last = Date.parse(cache.lastCheckedAt);
+    if (!Number.isFinite(last)) {
+        return true;
+    }
+    return now.getTime() - last >= CHECK_TTL_MS;
+}
+/**
+ * 如缓存过期，spawn 一个 detached 后台进程刷新它，主进程不等待。
+ *
+ * 这是 statusline 路径能用的唯一安全方式：主进程同步读旧缓存决定是否提示，
+ * 把网络请求甩给后台子进程，自己立刻输出单行状态文本并退出，绝不阻塞。
+ */
+function maybeSpawnBackgroundCheck(dataDir, now = new Date()) {
+    try {
+        if (!isCacheStale(readUpdateCacheSync(dataDir), now)) {
+            return;
+        }
+        const scriptPath = process.argv[1];
+        if (!scriptPath) {
+            return;
+        }
+        const child = (0, node_child_process_1.spawn)(process.execPath, [scriptPath, "__check-update", "--data-dir", dataDir], {
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        child.on("error", () => { });
+        child.unref();
+        (0, debug_1.debugLog)("update", "spawned background check");
+    }
+    catch (error) {
+        (0, debug_1.debugLog)("update", "failed to spawn background check", error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * 根据缓存计算 statusline 末尾要追加的更新标记。
+ *
+ * 有严格新于当前版本的发布时返回形如 `⬆ v0.1.5` 的短标记，否则返回 null。
+ */
+function computeUpdateNotice(dataDir, currentVersion = (0, version_1.getCurrentVersion)()) {
+    const cache = readUpdateCacheSync(dataDir);
+    if (!cache || !cache.latestVersion) {
+        return null;
+    }
+    if (!(0, version_1.isNewerVersion)(cache.latestVersion, currentVersion)) {
+        return null;
+    }
+    return `⬆ v${cache.latestVersion}`;
+}
+//# sourceMappingURL=update-check.js.map

package/dist/lib/version.js

@@ -0,0 +1,62 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCurrentVersion = getCurrentVersion;
+exports.isNewerVersion = isNewerVersion;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * 读取 ccus 自身的版本号（package.json 的 version）。
+ *
+ * dist/lib/version.js 与 src/lib/version.ts 距离包根都是 `../..`，
+ * 所以编译产物和 tsx 直跑源码时都能定位到同一个 package.json。
+ * 读不到时回退 "0.0.0"，让上层逻辑（更新检查）安全降级而不是抛错。
+ */
+let cachedVersion = null;
+function getCurrentVersion() {
+    if (cachedVersion !== null) {
+        return cachedVersion;
+    }
+    try {
+        const packageJsonPath = node_path_1.default.join(__dirname, "..", "..", "package.json");
+        const raw = node_fs_1.default.readFileSync(packageJsonPath, "utf8");
+        const parsed = JSON.parse(raw);
+        cachedVersion = typeof parsed.version === "string" ? parsed.version : "0.0.0";
+    }
+    catch {
+        cachedVersion = "0.0.0";
+    }
+    return cachedVersion;
+}
+/**
+ * 语义化版本比较：判断 latest 是否严格新于 current。
+ *
+ * 只比较 `major.minor.patch` 三段数字，忽略预发布/构建元数据，
+ * 对当前发布节奏足够；任意一段解析失败按 0 处理，避免误报更新。
+ */
+function isNewerVersion(latest, current) {
+    const parse = (value) => value
+        .trim()
+        .replace(/^v/, "")
+        .split("-", 1)[0]
+        .split(".")
+        .map((part) => Number.parseInt(part, 10))
+        .map((part) => (Number.isFinite(part) ? part : 0));
+    const a = parse(latest);
+    const b = parse(current);
+    const length = Math.max(a.length, b.length);
+    for (let index = 0; index < length; index += 1) {
+        const left = a[index] ?? 0;
+        const right = b[index] ?? 0;
+        if (left > right) {
+            return true;
+        }
+        if (left < right) {
+            return false;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccus-cli",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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"
+    "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"
   },
   "keywords": [
     "claude-code",