ccus-cli 0.1.3 → 0.1.5

package/dist/lib/dashboard.js

@@ -46,12 +46,13 @@ function summarizeEvents(events) {
  */
 function bucketizeEvents(events, start, end, bucketMinutes = 5) {
     const bucketMs = bucketMinutes * 60 * 1000;
+    // 5h 与 7d 在同一时间桶里各自独立收集：某条采样可能只带其中一项，不应互相牵连。
     const buckets = new Map();
     for (let cursor = start.getTime(); cursor <= end.getTime(); cursor += bucketMs) {
-        buckets.set(cursor, []);
+        buckets.set(cursor, { fiveHour: [], sevenDay: [] });
     }
     for (const event of events) {
-        if (event.usagePct === null) {
+        if (event.usagePct === null && event.sevenDayUsagePct === null) {
             continue;
         }
         const ts = new Date(event.timestamp).getTime();
@@ -59,17 +60,24 @@ function bucketizeEvents(events, start, end, bucketMinutes = 5) {
             continue;
         }
         const bucketStart = start.getTime() + Math.floor((ts - start.getTime()) / bucketMs) * bucketMs;
-        const values = buckets.get(bucketStart);
-        if (values) {
-            values.push(event.usagePct);
+        const slot = buckets.get(bucketStart);
+        if (!slot) {
+            continue;
+        }
+        if (event.usagePct !== null) {
+            slot.fiveHour.push(event.usagePct);
+        }
+        if (event.sevenDayUsagePct !== null) {
+            slot.sevenDay.push(event.sevenDayUsagePct);
         }
     }
-    return [...buckets.entries()].map(([bucketStart, values]) => ({
+    return [...buckets.entries()].map(([bucketStart, slot]) => ({
         bucketStart: new Date(bucketStart).toISOString(),
-        avgUsagePct: values.length > 0 ? (0, time_1.roundNumber)(average(values), 1) : null,
-        maxUsagePct: values.length > 0 ? (0, time_1.roundNumber)(Math.max(...values), 1) : null,
-        minUsagePct: values.length > 0 ? (0, time_1.roundNumber)(Math.min(...values), 1) : null,
-        sampleCount: values.length,
+        avgUsagePct: slot.fiveHour.length > 0 ? (0, time_1.roundNumber)(average(slot.fiveHour), 1) : null,
+        maxUsagePct: slot.fiveHour.length > 0 ? (0, time_1.roundNumber)(Math.max(...slot.fiveHour), 1) : null,
+        minUsagePct: slot.fiveHour.length > 0 ? (0, time_1.roundNumber)(Math.min(...slot.fiveHour), 1) : null,
+        avgSevenDayUsagePct: slot.sevenDay.length > 0 ? (0, time_1.roundNumber)(average(slot.sevenDay), 1) : null,
+        sampleCount: slot.fiveHour.length,
     }));
 }
 /** 直接输出内联 SVG 曲线图，避免额外引入前端框架或图表依赖。 */
@@ -80,46 +88,154 @@ function renderChart(buckets) {
     const paddingY = 28;
     const innerWidth = width - paddingX * 2;
     const innerHeight = height - paddingY * 2;
-    const values = buckets.map((bucket) => bucket.avgUsagePct ?? 0);
-    const points = buckets.map((bucket, index) => {
-        const x = paddingX + (index / Math.max(buckets.length - 1, 1)) * innerWidth;
-        const usage = bucket.avgUsagePct ?? 0;
-        const y = paddingY + ((100 - usage) / 100) * innerHeight;
-        return { x, y, usage, label: (0, time_1.formatLocalTimestamp)(new Date(bucket.bucketStart)) };
-    });
-    const linePath = points.map((point, index) => `${index === 0 ? "M" : "L"}${point.x.toFixed(2)} ${point.y.toFixed(2)}`).join(" ");
-    const areaPath = `${linePath} L${points.at(-1)?.x.toFixed(2) ?? paddingX} ${(height - paddingY).toFixed(2)} L${points[0]?.x.toFixed(2) ?? paddingX} ${(height - paddingY).toFixed(2)} Z`;
+    const xOf = (index) => paddingX + (index / Math.max(buckets.length - 1, 1)) * innerWidth;
+    const yOf = (usage) => paddingY + ((100 - usage) / 100) * innerHeight;
+    // 每条曲线只连有数据的桶，跨空桶直接相连，避免周视图里大量空桶把线拉回 0 变成锯齿。
+    const collectPoints = (accessor) => buckets
+        .map((bucket, index) => ({ index, value: accessor(bucket), bucket }))
+        .filter((entry) => entry.value !== null)
+        .map((entry) => ({
+        x: xOf(entry.index),
+        y: yOf(entry.value),
+        usage: entry.value,
+        label: (0, time_1.formatLocalTimestamp)(new Date(entry.bucket.bucketStart)),
+    }));
+    const fiveHourPoints = collectPoints((bucket) => bucket.avgUsagePct);
+    const sevenDayPoints = collectPoints((bucket) => bucket.avgSevenDayUsagePct);
+    const linePathOf = (points) => points.map((point, index) => `${index === 0 ? "M" : "L"}${point.x.toFixed(2)} ${point.y.toFixed(2)}`).join(" ");
+    const fiveHourLine = linePathOf(fiveHourPoints);
+    const fiveHourArea = fiveHourPoints.length > 0
+        ? `${fiveHourLine} L${fiveHourPoints.at(-1).x.toFixed(2)} ${(height - paddingY).toFixed(2)} L${fiveHourPoints[0].x.toFixed(2)} ${(height - paddingY).toFixed(2)} Z`
+        : "";
+    const sevenDayLine = linePathOf(sevenDayPoints);
     const ticks = [0, 25, 50, 75, 100].map((tick) => {
-        const y = paddingY + ((100 - tick) / 100) * innerHeight;
+        const y = yOf(tick);
         return `<g><line x1="${paddingX}" x2="${width - paddingX}" y1="${y}" y2="${y}" class="chart-grid" /><text x="8" y="${y + 4}" class="chart-axis">${tick}%</text></g>`;
     }).join("");
-    const markers = points
-        .filter((_, index) => index === points.length - 1 || index % Math.max(Math.floor(points.length / 6), 1) === 0)
-        .map((point) => `<g><line x1="${point.x}" x2="${point.x}" y1="${height - paddingY}" y2="${height - paddingY + 6}" class="chart-axis-line" /><text x="${point.x}" y="${height - 2}" text-anchor="middle" class="chart-axis">${escapeHtml(point.label)}</text></g>`)
+    // 跨多天的窗口（this-week / last-week）x 轴按自然日打刻度，每天一格、标签只显示月-日，
+    // 更像“周视图”；当天/短窗口仍按时间桶等距取约 6 个时:分刻度。
+    const firstTs = buckets.length > 0 ? new Date(buckets[0].bucketStart).getTime() : 0;
+    const lastTs = buckets.length > 0 ? new Date(buckets.at(-1).bucketStart).getTime() : 0;
+    const multiDay = lastTs - firstTs > 2 * 24 * 60 * 60 * 1000;
+    let markerEntries;
+    if (multiDay) {
+        const seenDays = new Set();
+        markerEntries = buckets
+            .map((bucket, index) => ({ index, day: (0, time_1.localDateKey)(new Date(bucket.bucketStart)) }))
+            .filter((entry) => {
+            if (seenDays.has(entry.day)) {
+                return false;
+            }
+            seenDays.add(entry.day);
+            return true;
+        })
+            .map((entry) => ({ index: entry.index, label: entry.day.slice(5) }));
+    }
+    else {
+        markerEntries = buckets
+            .map((bucket, index) => ({ index, label: (0, time_1.formatLocalTimestamp)(new Date(bucket.bucketStart)) }))
+            .filter((_, index) => index === buckets.length - 1 || index % Math.max(Math.floor(buckets.length / 6), 1) === 0);
+    }
+    const markers = markerEntries
+        .map((entry) => {
+        const x = xOf(entry.index);
+        return `<g><line x1="${x}" x2="${x}" y1="${height - paddingY}" y2="${height - paddingY + 6}" class="chart-axis-line" /><text x="${x}" y="${height - 2}" text-anchor="middle" class="chart-axis">${escapeHtml(entry.label)}</text></g>`;
+    })
         .join("");
-    const tooltips = points
-        .filter((point) => point.usage > 0)
-        .map((point) => `<circle cx="${point.x}" cy="${point.y}" r="3.5" class="chart-point"><title>${escapeHtml(point.label)} · ${point.usage.toFixed(1)}%</title></circle>`)
+    const dotsOf = (points, pointClass, seriesLabel) => points
+        .map((point) => `<circle cx="${point.x.toFixed(2)}" cy="${point.y.toFixed(2)}" r="3.5" class="${pointClass}"><title>${escapeHtml(point.label)} · ${seriesLabel} ${point.usage.toFixed(1)}%</title></circle>`)
         .join("");
-    const noData = values.every((value) => value === 0)
-        ? `<div class="empty-state">当前时间窗口里还没有可绘制的 Claude 5 小时使用率样本。</div>`
+    const noData = fiveHourPoints.length === 0 && sevenDayPoints.length === 0
+        ? `<div class="empty-state">当前时间窗口里还没有可绘制的 Claude 使用率样本。</div>`
         : "";
     return `
     <section class="panel chart-panel">
       <div class="panel-header">
         <div>
           <p class="eyebrow">Recent Trend</p>
-          <h2>Claude 5 小时使用率趋势</h2>
+          <h2>Claude 使用率趋势</h2>
         </div>
-        <p class="muted">按采样时间聚合，Y 轴为 rate_limits.five_hour.used_percentage</p>
+        <p class="muted">按采样时间聚合，5h 来自 rate_limits.five_hour，7d 来自 rate_limits.seven_day</p>
+      </div>
+      <div class="chart-legend">
+        <span class="legend-item"><span class="legend-swatch legend-5h"></span>5 小时使用率</span>
+        <span class="legend-item"><span class="legend-swatch legend-7d"></span>7 天使用率</span>
       </div>
       ${noData}
-      <svg viewBox="0 0 ${width} ${height}" class="chart" role="img" aria-label="Claude 5 小时使用率趋势">
+      <svg viewBox="0 0 ${width} ${height}" class="chart" role="img" aria-label="Claude 使用率趋势（5h 与 7d）">
         ${ticks}
-        <path d="${areaPath}" class="chart-area"></path>
-        <path d="${linePath}" class="chart-line"></path>
+        ${fiveHourArea ? `<path d="${fiveHourArea}" class="chart-area"></path>` : ""}
+        ${sevenDayLine ? `<path d="${sevenDayLine}" class="chart-line chart-line-7d"></path>` : ""}
+        ${fiveHourLine ? `<path d="${fiveHourLine}" class="chart-line"></path>` : ""}
         ${markers}
-        ${tooltips}
+        ${dotsOf(sevenDayPoints, "chart-point chart-point-7d", "7d")}
+        ${dotsOf(fiveHourPoints, "chart-point", "5h")}
+      </svg>
+    </section>
+  `;
+}
+/**
+ * 根据时间窗口跨度自适应选择曲线分桶粒度。
+ *
+ * today/5h 这类短窗口保持 5 分钟桶；this-week/last-week 这类跨多天窗口改用小时桶，
+ * 否则一周会产生上千个点，曲线既慢又糊。
+ */
+function pickBucketMinutes(start, end) {
+    const spanMs = end.getTime() - start.getTime();
+    const twoDaysMs = 2 * 24 * 60 * 60 * 1000;
+    return spanMs > twoDaysMs ? 60 : 5;
+}
+/**
+ * 每日用户消息数柱状图。
+ *
+ * 口径与导出契约的 `userMessageCount` 一致：来自 Claude 本地 transcript 的真实用户请求数，
+ * 不是 statusline 采样数，也不是 API 请求数。
+ */
+function renderDailyMessages(points) {
+    if (points.length === 0) {
+        return "";
+    }
+    const total = points.reduce((sum, point) => sum + point.userMessageCount, 0);
+    const maxCount = Math.max(...points.map((point) => point.userMessageCount), 1);
+    const width = 920;
+    const height = 280;
+    const paddingX = 36;
+    const paddingY = 28;
+    const innerWidth = width - paddingX * 2;
+    const innerHeight = height - paddingY * 2;
+    const slot = innerWidth / points.length;
+    const barWidth = Math.max(Math.min(slot * 0.62, 48), 2);
+    const bars = points
+        .map((point, index) => {
+        const cx = paddingX + slot * (index + 0.5);
+        const barHeight = (point.userMessageCount / maxCount) * innerHeight;
+        const y = paddingY + (innerHeight - barHeight);
+        const dayLabel = point.date.slice(5);
+        return `<g>
+        <rect x="${(cx - barWidth / 2).toFixed(2)}" y="${y.toFixed(2)}" width="${barWidth.toFixed(2)}" height="${Math.max(barHeight, 0).toFixed(2)}" rx="4" class="bar"><title>${escapeHtml(dayLabel)} · ${point.userMessageCount} 条</title></rect>
+        <text x="${cx.toFixed(2)}" y="${(y - 6).toFixed(2)}" text-anchor="middle" class="bar-value">${point.userMessageCount > 0 ? point.userMessageCount : ""}</text>
+        <text x="${cx.toFixed(2)}" y="${(height - 8).toFixed(2)}" text-anchor="middle" class="chart-axis">${escapeHtml(dayLabel)}</text>
+      </g>`;
+    })
+        .join("");
+    const baselineY = paddingY + innerHeight;
+    const baseline = `<line x1="${paddingX}" x2="${width - paddingX}" y1="${baselineY}" y2="${baselineY}" class="chart-axis-line" />`;
+    const noData = total === 0
+        ? `<div class="empty-state">当前时间窗口里还没有统计到 Claude 用户消息。</div>`
+        : "";
+    return `
+    <section class="panel chart-panel">
+      <div class="panel-header">
+        <div>
+          <p class="eyebrow">Daily Messages</p>
+          <h2>每日用户消息数</h2>
+        </div>
+        <p class="muted">按自然日统计的真实用户请求数（口径同导出 userMessageCount），共 ${total} 条</p>
+      </div>
+      ${noData}
+      <svg viewBox="0 0 ${width} ${height}" class="chart" role="img" aria-label="每日用户消息数">
+        ${baseline}
+        ${bars}
       </svg>
     </section>
   `;
@@ -175,9 +291,10 @@ function renderRecentEvents(events) {
  *
  * 整个 dashboard 保持“单文件可打开”，方便导出和直接分享本地结果。
  */
-function buildDashboardHtml(events, rangeLabel, start, end) {
+function buildDashboardHtml(events, rangeLabel, start, end, dailyUserMessages = []) {
     const summary = summarizeEvents(events);
-    const buckets = bucketizeEvents(events, start, end, 5);
+    const buckets = bucketizeEvents(events, start, end, pickBucketMinutes(start, end));
+    const totalUserMessages = dailyUserMessages.reduce((sum, point) => sum + point.userMessageCount, 0);
     return `<!doctype html>
 <html lang="zh-CN">
   <head>
@@ -310,6 +427,22 @@ function buildDashboardHtml(events, rangeLabel, start, end) {
       .chart-area { fill: rgba(94, 234, 212, 0.14); }
       .chart-line { fill: none; stroke: var(--accent); stroke-width: 3; stroke-linecap: round; stroke-linejoin: round; }
       .chart-point { fill: var(--accent); }
+      .chart-line-7d { stroke: var(--warning); stroke-dasharray: 6 4; }
+      .chart-point-7d { fill: var(--warning); }
+      .chart-legend {
+        display: flex;
+        gap: 18px;
+        padding: 10px 24px 0;
+        color: var(--muted);
+        font-size: 13px;
+      }
+      .legend-item { display: inline-flex; align-items: center; gap: 8px; }
+      .legend-swatch { width: 18px; height: 0; border-top-width: 3px; border-top-style: solid; }
+      .legend-5h { border-top-color: var(--accent); }
+      .legend-7d { border-top-color: var(--warning); border-top-style: dashed; }
+      .bar { fill: rgba(94, 234, 212, 0.55); }
+      .bar:hover { fill: var(--accent); }
+      .bar-value { fill: var(--muted); font-size: 11px; }
       .empty-state {
         margin: 18px 24px 0;
         padding: 16px 18px;
@@ -375,17 +508,18 @@ function buildDashboardHtml(events, rangeLabel, start, end) {
           <p class="stat-note">窗口内观测到的 5 小时使用率峰值</p>
         </article>
         <article class="panel stat-card">
-          <h2>Sessions</h2>
-          <p class="stat-value">${summary.uniqueSessions}</p>
-          <p class="stat-note">去重 session 数</p>
+          <h2>Latest 7d usage</h2>
+          <p class="stat-value">${escapeHtml(statValue(summary.sevenDayLatestUsagePct))}</p>
+          <p class="stat-note">最新 7 天 usage 样本，峰值 ${escapeHtml(statValue(summary.sevenDayPeakUsagePct))}</p>
         </article>
         <article class="panel stat-card">
-          <h2>Workspaces</h2>
-          <p class="stat-value">${summary.uniqueWorkspaces}</p>
-          <p class="stat-note">去重项目目录数</p>
+          <h2>用户消息数</h2>
+          <p class="stat-value">${totalUserMessages}</p>
+          <p class="stat-note">窗口内每日真实用户请求数合计</p>
         </article>
       </section>
       ${renderChart(buckets)}
+      ${renderDailyMessages(dailyUserMessages)}
       ${renderRecentEvents(events)}
     </main>
   </body>

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,35 +1,35 @@
-{
-  "name": "ccus-cli",
-  "version": "0.1.3",
-  "description": "Claude Code statusline usage logger and dashboard CLI",
-  "type": "commonjs",
-  "bin": {
-    "ccus": "dist/cli.js"
-  },
-  "files": [
-    "dist/cli.js",
-    "dist/lib/**/*.js",
-    "dist/types.js"
-  ],
-  "scripts": {
-    "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"
-  },
-  "keywords": [
-    "claude-code",
-    "statusline",
-    "cli",
-    "dashboard"
-  ],
-  "license": "MIT",
-  "engines": {
-    "node": ">=20"
-  },
-  "devDependencies": {
-    "@types/node": "^24.0.0",
-    "tsx": "^4.20.0",
-    "typescript": "^5.8.3"
-  }
-}
+{
+  "name": "ccus-cli",
+  "version": "0.1.5",
+  "description": "Claude Code statusline usage logger and dashboard CLI",
+  "type": "commonjs",
+  "bin": {
+    "ccus": "dist/cli.js"
+  },
+  "files": [
+    "dist/cli.js",
+    "dist/lib/**/*.js",
+    "dist/types.js"
+  ],
+  "scripts": {
+    "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"
+  },
+  "keywords": [
+    "claude-code",
+    "statusline",
+    "cli",
+    "dashboard"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.8.3"
+  }
+}