ccus-cli 0.1.21 → 0.1.22

package/README.md

@@ -146,11 +146,11 @@ ccus aggregate serve --input-dir ./team-exports
 其中：
 
 - `5 小时使用量百分比` 是 **展示指标**，来自 Claude 自身字段 `rate_limits.five_hour.used_percentage`
-- 使用率趋势图会在同一张图上叠加两条线：实线为 5 小时使用率（`rate_limits.five_hour`），虚线为 7 天使用率（`rate_limits.seven_day`），两者各自独立按时间桶聚合
+- 使用率趋势图会在同一张图上叠加三条线：实线为 5 小时使用率（`rate_limits.five_hour`）、虚线为 7 天使用率（`rate_limits.seven_day`），两者各自独立按时间桶聚合、共用固定 0–100% 的左侧 Y 轴；紫色「7d 分区叠加累计」是把 7 天额度锯齿波还原成的累计真实使用量（口径同团队看板的 `sevenDayCumulativeUsagePct`），量纲可超 100%、单独走**右侧自适应 Y 轴**，按分段峰谷和单调非递减地累积上升，终点即顶部卡片的累计值
 - **折线与纵向柱状图均由 [uPlot](https://github.com/leeoniya/uPlot) 渲染**：鼠标在绘图区**任意位置**悬停即可通过十字线 + **跟随鼠标的 tooltip** 看到该处各条线的当前读数（不必精确落在采样点上；遇到几乎垂直的窄尖峰，把鼠标移到竖线顶端即可读到峰值）；纵向柱还会在每根柱顶标注数值。底部为**自绘图例**（实时读数集中在 tooltip 里）。uPlot 库与样式已**内联进生成的 HTML**，`dashboard build` 产物用 `file://` 离线打开也能完整渲染与交互，不依赖任何 CDN
 - 页面新增 **每日用户消息数** 纵向柱状图：按自然日统计的真实用户请求数，口径与导出契约的 `userMessageCount` 一致（来自 `~/.claude/projects/**/*.jsonl`），不是 statusline 采样数，也仅用于页面展示、不进任何导出/聚合契约
 - 跨多天的窗口（如 `this-week` / `last-week`）使用率曲线会自动改用小时桶聚合，避免一周生成上千个点；x 轴刻度由 uPlot 按时间跨度自适应（短窗口显示 `HH:mm` **24 小时制**、跨天的刻度再补一行日期），不用 am/pm
-- 顶部统计卡展示 `Latest 5h usage`、`Peak 5h usage`、`Latest 7d usage`（含峰值）、`用户消息数`（窗口内每日真实用户请求数合计）
+- 顶部统计卡展示 `Latest 5h usage`、`Peak 5h usage`、`7d 分区叠加累计`（主数值为 7 天额度分区叠加累计真实使用量，小字补充峰值与最新值）、`用户消息数`（窗口内每日真实用户请求数合计）
 - `--range today / this-week / last-week / 24h` 是 **你要查看的采样历史时间窗口**（`last-week` 指上一个完整周一到周日）
 - statusline 日志本身主要保存 `rawPayload` 与外部补充字段；默认导出时会同时保留原始事件，并额外汇总 `~/.claude/projects/**/*.jsonl` 中的会话 usage
 

package/dist/lib/aggregate.js

@@ -4,7 +4,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadWeeklyExportBundles = loadWeeklyExportBundles;
+exports.computeCumulativeSevenDayCurve = computeCumulativeSevenDayCurve;
 exports.computeCumulativeSevenDay = computeCumulativeSevenDay;
+exports.deburrSevenDayEvents = deburrSevenDayEvents;
+exports.buildSevenDayCurveFromEvents = buildSevenDayCurveFromEvents;
 exports.buildPersonSevenDayCurve = buildPersonSevenDayCurve;
 exports.buildAggregatedDetailRows = buildAggregatedDetailRows;
 exports.buildAggregatedDailyRows = buildAggregatedDailyRows;
@@ -265,7 +268,8 @@ function bundleEventsByDate(bundle) {
  */
 const SEVEN_DAY_RESET_RATIO = 0.5;
 /**
- * 7 天额度累计真实使用量：对一组事件取非 null `sevenDayUsagePct`、按时间升序，用**分段峰谷和**还原。
+ * 7 天额度累计真实使用量的**逐点曲线**：对一组事件取非 null `sevenDayUsagePct`、按时间升序，用**分段峰谷和**
+ * 还原，并在每个样本处输出「截至此刻的累计值」，得到一条单调非递减曲线。
  *
  * 把曲线按 reset（样本跌破当前段峰值的 {@link SEVEN_DAY_RESET_RATIO}）切成若干上升段，
  * 每段贡献「段内峰值 − 段内谷值」，累计 = 各段贡献之和。等价于「正增量累加，但忽略未跌破段峰一半的小回落」。
@@ -274,21 +278,23 @@ const SEVEN_DAY_RESET_RATIO = 0.5;
  * 朴素累加会把每次上抖都计成真实增长，导致严重高估（实测 gaoshang 102 vs 分段 50）。
  * 分段峰谷和对抖动 / aging 回落鲁棒，又能正确累计「涨到峰 → 归零 → 再涨」的多段真实使用。
  *
- * 无有效样本返回 null（区别于 0：0 表示有样本但无净增长）；单样本返回 0。
+ * 每个点的累计 = 已锁定的各完整段贡献 + 当前段 (segMax − segMin)；段内更新 / reset 都不会让它回落，
+ * 所以曲线单调非递减、终点恒等于 {@link computeCumulativeSevenDay} 的标量返回值。输入建议先经 deburr 去毛刺。
+ * 无有效样本返回空数组；单样本返回单点 0。
  */
-function computeCumulativeSevenDay(events) {
-    const values = [...events]
-        .sort((left, right) => new Date(left.timestamp).getTime() - new Date(right.timestamp).getTime())
-        .map((event) => event.sevenDayUsagePct)
-        .filter((value) => value !== null);
-    if (values.length === 0) {
-        return null;
+function computeCumulativeSevenDayCurve(events) {
+    const sorted = [...events]
+        .filter((event) => event.sevenDayUsagePct !== null)
+        .sort((left, right) => new Date(left.timestamp).getTime() - new Date(right.timestamp).getTime());
+    if (sorted.length === 0) {
+        return [];
     }
+    const points = [{ timestamp: sorted[0].timestamp, cumulative: 0 }];
     let cumulative = 0;
-    let segMin = values[0];
-    let segMax = values[0];
-    for (let index = 1; index < values.length; index += 1) {
-        const value = values[index];
+    let segMin = sorted[0].sevenDayUsagePct;
+    let segMax = sorted[0].sevenDayUsagePct;
+    for (let index = 1; index < sorted.length; index += 1) {
+        const value = sorted[index].sevenDayUsagePct;
         if (value > segMax) {
             segMax = value;
         }
@@ -302,9 +308,18 @@ function computeCumulativeSevenDay(events) {
             // 段内小回落（抖动 / aging）：只更新谷值，不分段、不重复计数。
             segMin = value;
         }
+        points.push({ timestamp: sorted[index].timestamp, cumulative: (0, time_1.roundNumber)(cumulative + (segMax - segMin), 1) ?? 0 });
     }
-    cumulative += segMax - segMin;
-    return (0, time_1.roundNumber)(cumulative, 1);
+    return points;
+}
+/**
+ * 7 天额度累计真实使用量（标量）：取 {@link computeCumulativeSevenDayCurve} 曲线终点。
+ *
+ * 无有效样本返回 null（区别于 0：0 表示有样本但无净增长）；单样本返回 0。
+ */
+function computeCumulativeSevenDay(events) {
+    const curve = computeCumulativeSevenDayCurve(events);
+    return curve.length === 0 ? null : curve[curve.length - 1].cumulative;
 }
 /** 7d 曲线读数去毛刺的最小持续时长：短于此的中间读数段视为 stale / 瞬时异常。 */
 const SEVEN_DAY_MIN_HOLD_MS = 2 * 60 * 1000;
@@ -312,10 +327,14 @@ const SEVEN_DAY_MIN_HOLD_MS = 2 * 60 * 1000;
  * 7d 曲线读数去毛刺：真实 7d 信号变化慢、每个档位会被高频采样连续覆盖几十上百个样本，
  * 而 stale 缓存读数 / 瞬时异常只会短暂出现（秒级，如 baseline 很低时偶发跳到 30 又落回）。
  *
- * 把**中间**持续短于 {@link SEVEN_DAY_MIN_HOLD_MS} 的读数段（下一段起始 − 本段起始）替换为最近的已保留前值，
- * 抹掉这些尖峰；首尾段无条件保留（端点缺上下文判断持续性）。这等价于人眼在曲线图上自动忽略短毛刺。
+ * 把**中间**持续短于 {@link SEVEN_DAY_MIN_HOLD_MS} 的读数段替换为最近的已保留前值，抹掉这些尖峰；
+ * 首尾段无条件保留（端点缺上下文判断持续性）。这等价于人眼在曲线图上自动忽略短毛刺。
  *
- * 仅对密集采样的真实曲线生效：稀疏数据（每个值只有一两个样本、间隔很大）的中间段持续时长通常远超阈值，
+ * 持续时长默认按「下一段起始 − 本段起始」度量（密集采样下约等于本段实际持续）；但当**多样本**段后面紧跟一段
+ * 比阈值还大的**采集间隙**时，该度量会把间隙也算进去、把只持续几十秒的短尖峰“撑”过阈值而漏抹，
+ * 此时改用**段内真实跨度（最后样本 − 第一样本）**判定。单样本段无段内跨度、无法据此判断，仍走原度量。
+ *
+ * 仅对密集采样的真实曲线生效：稀疏数据（每个值只有一两个样本、间隔很大）的单样本中间段仍按原度量保留，
  * 不会被误删，所以 spec 的稀疏示例与单样本段不受影响。输入须按 timestamp 升序。
  */
 function deburrSevenDayEvents(events, minHoldMs = SEVEN_DAY_MIN_HOLD_MS) {
@@ -329,14 +348,28 @@ function deburrSevenDayEvents(events, minHoldMs = SEVEN_DAY_MIN_HOLD_MS) {
         while (end + 1 < events.length && events[end + 1].sevenDayUsagePct === events[index].sevenDayUsagePct) {
             end += 1;
         }
-        runs.push({ value: events[index].sevenDayUsagePct, startIdx: index, endIdx: end, startTime: new Date(events[index].timestamp).getTime() });
+        runs.push({
+            value: events[index].sevenDayUsagePct,
+            startIdx: index,
+            endIdx: end,
+            startTime: new Date(events[index].timestamp).getTime(),
+            endTime: new Date(events[end].timestamp).getTime(),
+        });
         index = end + 1;
     }
     const result = [...events];
     let lastKept = runs[0].value;
     for (let k = 0; k < runs.length; k += 1) {
         const isEdge = k === 0 || k === runs.length - 1;
-        const holdMs = k + 1 < runs.length ? runs[k + 1].startTime - runs[k].startTime : Number.POSITIVE_INFINITY;
+        // 默认持续时长 = 下一段起始 − 本段起始（密集采样下约等于本段实际持续）。
+        const toNext = k + 1 < runs.length ? runs[k + 1].startTime - runs[k].startTime : Number.POSITIVE_INFINITY;
+        // 本段最后样本到下一段起始的采集间隙：密集采样下很小，遇到数据采集中断时会变大。
+        const gapAfter = k + 1 < runs.length ? runs[k + 1].startTime - runs[k].endTime : Number.POSITIVE_INFINITY;
+        // 多样本段（段内本身有跨度）后面若紧跟一段比阈值还大的采集间隙，说明 toNext 把间隙也算进了持续时长，
+        // 会把本只持续几十秒的短尖峰“撑”过阈值而漏抹；此时改用段内真实跨度判定，正确识别这类 stale 尖峰。
+        // 单样本段（无段内跨度）无法据此判断真实持续，仍走 toNext，避免误伤稀疏单样本数据。
+        const multiSample = runs[k].endIdx > runs[k].startIdx;
+        const holdMs = multiSample && gapAfter > minHoldMs ? runs[k].endTime - runs[k].startTime : toNext;
         if (isEdge || holdMs >= minHoldMs) {
             lastKept = runs[k].value;
             continue;
@@ -347,6 +380,28 @@ function deburrSevenDayEvents(events, minHoldMs = SEVEN_DAY_MIN_HOLD_MS) {
     }
     return result;
 }
+/**
+ * 把一组事件整理成一条可用于累计计算的 7d 曲线：取非 null `sevenDayUsagePct`、按时间升序、
+ * 对完全相同 timestamp 去重，再做读数去毛刺。
+ *
+ * 单台机器的本地日志（dashboard 个人看板）与多机合并（aggregate）都走这同一套整理逻辑，
+ * 保证两边的累计口径不会漂移。
+ */
+function buildSevenDayCurveFromEvents(events) {
+    const sorted = [...events]
+        .filter((event) => event.sevenDayUsagePct !== null)
+        .sort((left, right) => new Date(left.timestamp).getTime() - new Date(right.timestamp).getTime());
+    const seen = new Set();
+    const deduped = [];
+    for (const event of sorted) {
+        if (seen.has(event.timestamp)) {
+            continue;
+        }
+        seen.add(event.timestamp);
+        deduped.push(event);
+    }
+    return deburrSevenDayEvents(deduped);
+}
 /**
  * 同一 personKey 的 7d 累计曲线：把该人**所有 bundle**（非仅 winner）的 rawEvents 计算成事件、
  * 取非 null `sevenDayUsagePct`、按 timestamp 升序合并、对完全相同 timestamp 去重，再做读数去毛刺，
@@ -380,17 +435,7 @@ function buildPersonSevenDayCurve(bundles) {
     }
     const curves = new Map();
     for (const [personKey, events] of collected.entries()) {
-        const sorted = [...events].sort((left, right) => new Date(left.timestamp).getTime() - new Date(right.timestamp).getTime());
-        const seen = new Set();
-        const deduped = [];
-        for (const event of sorted) {
-            if (seen.has(event.timestamp)) {
-                continue;
-            }
-            seen.add(event.timestamp);
-            deduped.push(event);
-        }
-        curves.set(personKey, deburrSevenDayEvents(deduped));
+        curves.set(personKey, buildSevenDayCurveFromEvents(events));
     }
     personSevenDayCurveCache.set(bundles, curves);
     return curves;

package/dist/lib/chart-assets.js

@@ -324,6 +324,7 @@ function uplotBodyScripts() {
             };
             if (s.fill) ser.fill = s.fill;
             if (s.dash) ser.dash = s.dash;
+            if (s.scale) ser.scale = s.scale;
             if (spec.bars) {
               ser.paths = uPlot.paths.bars({ size: [0.62, 48], align: 0 });
               ser.points = { show: false };
@@ -379,12 +380,30 @@ function uplotBodyScripts() {
             };
           }
 
+          var axes = [xAxis, yAxis];
+          if (spec.y2) {
+            var y2unit = spec.y2.unit || "";
+            scales[spec.y2.scale] = spec.y2.range
+              ? { range: spec.y2.range }
+              : (spec.y2.min0
+                  ? { range: function (u, min, max) { var hi = max == null || max <= 0 ? 1 : max; return [0, hi]; } }
+                  : {});
+            axes.push({
+              scale: spec.y2.scale,
+              side: 1,
+              stroke: THEME.axis,
+              grid: { show: false },
+              ticks: { stroke: THEME.grid, width: 1 },
+              values: function (u, splits) { return splits.map(function (v) { return round1(v) + y2unit; }); },
+            });
+          }
+
           var opts = {
             width: el.clientWidth || 920,
             height: spec.height || 280,
             scales: scales,
             series: series,
-            axes: [xAxis, yAxis],
+            axes: axes,
             // 关掉 uPlot 原生底部 legend（每条 series 一行），改用 buildLegend 自绘「每人一项」图例。
             legend: { show: false },
             // dataIdx 2D 吸附：横向重合的尖峰按鼠标高度命中峰顶，稀疏区/缺失退回最近真实点。

package/dist/lib/dashboard.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.summarizeEvents = summarizeEvents;
 exports.bucketizeEvents = bucketizeEvents;
 exports.buildDashboardHtml = buildDashboardHtml;
+const aggregate_1 = require("./aggregate");
 const chart_assets_1 = require("./chart-assets");
 const time_1 = require("./time");
 /** 所有插入到 HTML/SVG 的动态文本都先转义，避免本地页面被注入内容。 */
@@ -32,11 +33,14 @@ function summarizeEvents(events) {
     const latestSevenDayUsagePct = [...events]
         .sort((left, right) => new Date(right.timestamp).getTime() - new Date(left.timestamp).getTime())
         .find((event) => event.sevenDayUsagePct !== null)?.sevenDayUsagePct ?? null;
+    // 7d 分区叠加累计：与 aggregate 同一套「去毛刺 + 分段峰谷和」，口径与团队看板一致。
+    const sevenDayCumulativeUsagePct = (0, aggregate_1.computeCumulativeSevenDay)((0, aggregate_1.buildSevenDayCurveFromEvents)(events));
     return {
         fiveHourLatestUsagePct: latestUsagePct,
         fiveHourPeakUsagePct: usages.length > 0 ? (0, time_1.roundNumber)(Math.max(...usages), 1) : null,
         sevenDayLatestUsagePct: sevenDayUsages.length > 0 ? latestSevenDayUsagePct : null,
         sevenDayPeakUsagePct: sevenDayUsages.length > 0 ? (0, time_1.roundNumber)(Math.max(...sevenDayUsages), 1) : null,
+        sevenDayCumulativeUsagePct,
         sampleCount: events.length,
         uniqueSessions: new Set(events.map((event) => event.sessionId).filter(Boolean)).size,
         uniqueWorkspaces: new Set(events.map((event) => event.workspaceDir).filter(Boolean)).size,
@@ -72,12 +76,24 @@ function bucketizeEvents(events, start, end, bucketMinutes = 5) {
             slot.sevenDay.push(event.sevenDayUsagePct);
         }
     }
+    // 7d 累计曲线（去毛刺 + 分段峰谷和的逐点版本）映射到时间桶：曲线已按时间升序，
+    // 同桶内后写覆盖前写，最终每个桶留下落在其区间内最后一个累计点的值（单调，等于桶内最大累计）。
+    const cumulativeByBucket = new Map();
+    for (const point of (0, aggregate_1.computeCumulativeSevenDayCurve)((0, aggregate_1.buildSevenDayCurveFromEvents)(events))) {
+        const ts = new Date(point.timestamp).getTime();
+        if (ts < start.getTime() || ts > end.getTime()) {
+            continue;
+        }
+        const bucketStart = start.getTime() + Math.floor((ts - start.getTime()) / bucketMs) * bucketMs;
+        cumulativeByBucket.set(bucketStart, point.cumulative);
+    }
     return [...buckets.entries()].map(([bucketStart, slot]) => ({
         bucketStart: new Date(bucketStart).toISOString(),
         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,
+        cumulativeSevenDayPct: cumulativeByBucket.has(bucketStart) ? cumulativeByBucket.get(bucketStart) : null,
         sampleCount: slot.fiveHour.length,
     }));
 }
@@ -90,29 +106,34 @@ function bucketizeEvents(events, start, end, bucketMinutes = 5) {
  * 提供十字线 + legend 跟随显示两条线当前值。
  */
 function renderChart(buckets) {
-    // 每条曲线只连有数据的桶：取「5h 或 7d 任一非空」的桶作为统一 x 轴，缺失填 null。
-    const valued = buckets.filter((bucket) => bucket.maxUsagePct !== null || bucket.avgSevenDayUsagePct !== null);
+    // 每条曲线只连有数据的桶：取「5h / 7d / 累计 任一非空」的桶作为统一 x 轴，缺失填 null。
+    const valued = buckets.filter((bucket) => bucket.maxUsagePct !== null || bucket.avgSevenDayUsagePct !== null || bucket.cumulativeSevenDayPct !== null);
     const noData = valued.length === 0
         ? `<div class="empty-state">当前时间窗口里还没有可绘制的 Claude 使用率样本。</div>`
         : "";
     const xs = valued.map((bucket) => Math.floor(new Date(bucket.bucketStart).getTime() / 1000));
     const fiveHour = valued.map((bucket) => bucket.maxUsagePct);
     const sevenDay = valued.map((bucket) => bucket.avgSevenDayUsagePct);
+    // 7d 分区叠加累计：量纲可远超 0–100%，单独走右侧 Y 轴（y2 自适应），避免压扁固定 0–100 的 5h/7d 主轴。
+    const cumulative = valued.map((bucket) => bucket.cumulativeSevenDayPct);
     const spec = {
         height: 280,
         xType: "time",
         yUnit: "%",
         yRange: [0, 100],
+        y2: { scale: "y2", unit: "%", min0: true },
         series: [
             { label: "5 小时使用率", stroke: "#5eead4", fill: "rgba(94, 234, 212, 0.14)", width: 3 },
             { label: "7 天使用率", stroke: "#f59e0b", dash: [6, 4], width: 2 },
+            { label: "7d 分区叠加累计", stroke: "#a855f7", width: 2, scale: "y2" },
         ],
         legendGroups: [
             { label: "5 小时使用率", color: "#5eead4", seriesIdx: [1] },
             { label: "7 天使用率", color: "#f59e0b", seriesIdx: [2] },
+            { label: "7d 分区叠加累计", color: "#a855f7", seriesIdx: [3] },
         ],
     };
-    const chart = valued.length > 0 ? (0, chart_assets_1.renderUplotChart)("chart-usage", spec, [xs, fiveHour, sevenDay]) : "";
+    const chart = valued.length > 0 ? (0, chart_assets_1.renderUplotChart)("chart-usage", spec, [xs, fiveHour, sevenDay, cumulative]) : "";
     return `
     <section class="panel chart-panel">
       <div class="panel-header">
@@ -120,7 +141,7 @@ function renderChart(buckets) {
           <p class="eyebrow">Recent Trend</p>
           <h2>Claude 使用率趋势</h2>
         </div>
-        <p class="muted">按采样时间聚合，5h 来自 rate_limits.five_hour，7d 来自 rate_limits.seven_day</p>
+        <p class="muted">按采样时间聚合：5h（实线）来自 rate_limits.five_hour，7d（虚线）来自 rate_limits.seven_day；紫色「7d 分区叠加累计」走右侧 Y 轴，是把 7d 锯齿波还原成的累计真实使用量（口径同团队看板）</p>
       </div>
       ${noData}
       ${chart}
@@ -422,9 +443,9 @@ function buildDashboardHtml(events, rangeLabel, start, end, dailyUserMessages =
           <p class="stat-note">窗口内观测到的 5 小时使用率峰值</p>
         </article>
         <article class="panel stat-card">
-          <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>
+          <h2>7d 分区叠加累计</h2>
+          <p class="stat-value">${escapeHtml(statValue(summary.sevenDayCumulativeUsagePct))}</p>
+          <p class="stat-note">7 天额度分区叠加累计真实使用量 · 峰值 ${escapeHtml(statValue(summary.sevenDayPeakUsagePct))} · 最新 ${escapeHtml(statValue(summary.sevenDayLatestUsagePct))}</p>
         </article>
         <article class="panel stat-card">
           <h2>用户消息数</h2>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccus-cli",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "Claude Code statusline usage logger and dashboard CLI",
   "type": "commonjs",
   "bin": {