ccus-cli 0.1.21 → 0.1.23

package/README.md

@@ -9,6 +9,7 @@
 - `ccus aggregate`：读取一个目录里的多人 export bundle（`.json.gz` 或 `.json`），输出明细、按天、按周三个 CSV。
 - `ccus aggregate serve`：同样以 bundle 目录为输入，启动本地多人 dashboard 页面，不落地任何文件。
 - `ccus sync`：定时把当前周数据包导出并复制到一个目标目录（如团队共享盘），目标目录下按周自动建子目录；日常由 statusline 兜底触发，也可挂系统计划任务做到严格每天定时。
+- `ccus api`：走第三方 API（如智谱 GLM Coding Plan）而非官方订阅时，主动拉取 5h/7d 额度填进 statusline 与导出；默认从环境变量读 token，带缓存，失败静默。
 - `ccus open`：用系统文件管理器打开 ccus 本地存储目录（事件日志、exports、dashboard 都在里面）；加 `--print` 只输出目录路径、不打开。
 - `ccus update`：主动检查 npm 上是否有新版本，有则提示手动升级命令；`ccus --version` 查看当前版本。
 
@@ -146,11 +147,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
 
@@ -230,6 +231,30 @@ ccus sync status                                 # 查看目标目录、周期
 
    > 记得先 `ccus sync config --target DIR` 配好目标目录，调度任务才有地方可同步。
 
+## API 模式（第三方额度）
+
+走第三方 API（如智谱 GLM Coding Plan）而非 Claude 官方订阅时，statusline payload 里没有 `rate_limits`，ccus 默认显示 `5h -- | 7d --`。开启 API 模式后，ccus 会在 `statusline emit` 时主动拉取第三方额度，填进 `rawPayload.rate_limits`，复用现有展示/落盘/导出/聚合管线（不改变 schemaVersion 与导出契约）。
+
+智谱 GLM 同样是「每 5 小时窗口 + 每周窗口」额度，语义与 5h/7d 对应，开箱即用：
+
+```bash
+# token 默认从环境变量 ANTHROPIC_AUTH_TOKEN 读（Claude Code 用第三方 API 时通常已注入）
+ccus api config --enable --provider zhipu --project <项目ID> --organization <组织ID>
+ccus api test      # 立即拉一次，验证配置是否生效、额度是否解析正确
+ccus api status    # 查看配置与缓存新鲜度
+ccus api config    # 不带参数：打印当前配置
+```
+
+要点：
+
+- **开启 / 关闭**：`ccus api config --enable` 开启、`--disable` 关闭（关闭后 statusline 回退成 `5h -- | 7d --` 或官方 `rate_limits`），不带参数只查看当前配置；配置（provider/url/token 等）保留，关了再开不用重填。另有 `--no-token` / `--no-header` / `--no-extractor` 清除对应单项。
+- **Token 来源**：默认读环境变量 `ANTHROPIC_AUTH_TOKEN`（可用 `--token-env NAME` 改）；读不到时可用 `--token VAL` 兜底（注意：兜底 token 会明文写入 `api-config.json`）。
+- **缓存**：statusline 高频调用，额度按 TTL 缓存（默认 5 分钟，`--ttl 5m` 改），拉取失败自动回退上次缓存；缓存文件 `api-quota-cache.json`。
+- **智谱请求头**：除 `Authorization` 外，`--project` / `--organization` 会作为 `bigmodel-project` / `bigmodel-organization` 头发出（团队版需要）。接口对请求来源敏感，若返回空响应疑似被拦，可用 `ccus api config --user-agent "<浏览器UA>"` 改 UA。
+- **自定义 provider**：`--provider custom` 配其它厂商。简单响应用 `--url` / `--method` / `--header "K: V; K2: V2"`（header 值支持 `{{token}}` 占位）/ `--five-hour-path` / `--seven-day-path`（点分路径，如 `data.limits.0.percentage`）映射字段；响应结构复杂（数组筛选/排序）时用 `--extractor-file script.js` 写一段 JS 函数，接收响应对象、返回 `{ fiveHour, sevenDay }` 或 cc-switch 风格的 `[{used}, {used}]`，配了 extractor 就优先于点分路径。脚本在 ccus 进程内执行，只放信任的来源。
+
+> API 模式填充的 5h/7d 会和官方 `rate_limits` 走同一条聚合管线（含 7d 累计去毛刺算法，该算法针对 Claude 官方锯齿波设计）；不同厂商的额度曲线语义可能不完全一致，混用聚合时注意。
+
 ## 调试
 
 出问题时（比如 statusline 不出数据、导出/聚合结果不对），可以打开详细日志：

package/dist/cli.js

@@ -54,6 +54,7 @@ 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 api_mode_1 = require("./lib/api-mode");
 const sync_1 = require("./lib/sync");
 const storage_1 = require("./lib/storage");
 const time_1 = require("./lib/time");
@@ -61,7 +62,7 @@ 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 sessions [RANGE] [--out FILE] [--data-dir PATH]   (把 ~/.claude/projects 本周活跃 session 打包成 zip，名如 projects_<dates>_<user>.zip)\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`);
+    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 sessions [RANGE] [--out FILE] [--data-dir PATH]   (把 ~/.claude/projects 本周活跃 session 打包成 zip，名如 projects_<dates>_<user>.zip)\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 api config [--enable|--disable] [--provider zhipu|custom] [--token-env NAME] [--token VAL] [--url URL] [--project P] [--organization O] [--ttl 5m] [--extractor-file FILE] [--data-dir PATH]\n  ccus api test [--data-dir PATH]   (立即拉取第三方额度并打印，验证配置是否生效)\n  ccus api 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) {
@@ -161,6 +162,15 @@ async function handleStatuslineEmit(options) {
         record.gitUserName = gitIdentity.userName;
         record.gitUserEmail = gitIdentity.userEmail;
         record.gitUserAccount = (0, time_1.extractGitEmailAccount)(gitIdentity.userEmail);
+        // API 模式：若启用，主动拉取第三方额度（智谱等），填进 rawPayload.rate_limits，
+        // 让落盘与 computeStatuslineEvent 都能算出 usage；失败静默回退缓存，绝不污染单行 statusline 契约。
+        const apiConfig = (0, api_mode_1.readApiConfig)(dataDir);
+        if (apiConfig.enabled) {
+            const quota = await (0, api_mode_1.resolveApiQuota)(dataDir, apiConfig, process.env);
+            if (quota) {
+                (0, api_mode_1.applyQuotaToPayload)(record.rawPayload, quota);
+            }
+        }
         if (noStore) {
             (0, debug_1.debugLog)("statusline", "no-store enabled, skipping appendEvent");
         }
@@ -826,6 +836,223 @@ async function handleBackgroundSync(options) {
         (0, debug_1.debugLog)("sync", "background sync failed", error instanceof Error ? (error.stack ?? error.message) : String(error));
     }
 }
+/** 解析时长字面量为毫秒：纯数字按 ms，支持 ms/s/m/h 后缀。非法返回 null。 */
+function parseDurationMs(raw) {
+    if (raw === undefined) {
+        return null;
+    }
+    const text = raw.trim().toLowerCase();
+    if (text === "") {
+        return null;
+    }
+    const match = text.match(/^(\d+(?:\.\d+)?)(ms|s|m|h)?$/);
+    if (!match) {
+        return null;
+    }
+    const n = Number(match[1]);
+    const unit = match[2] ?? "ms";
+    const mult = unit === "ms" ? 1 : unit === "s" ? 1000 : unit === "m" ? 60_000 : 3_600_000;
+    return Math.round(n * mult);
+}
+/** 把毫秒时长格式化成人类可读（整分钟显示成 m，否则 ms）。 */
+function formatDurationMs(ms) {
+    if (ms >= 60_000 && ms % 60_000 === 0) {
+        return `${ms / 60_000}m`;
+    }
+    return `${ms}ms`;
+}
+/** 解析 --header "K1: V1; K2: V2" 为 header map；按首个冒号拆 K/V，非法条目跳过。 */
+function parseHeaderFlag(raw) {
+    if (raw === undefined) {
+        return null;
+    }
+    const out = {};
+    for (const segment of raw.split(";")) {
+        const idx = segment.indexOf(":");
+        if (idx <= 0) {
+            continue;
+        }
+        const key = segment.slice(0, idx).trim();
+        const value = segment.slice(idx + 1).trim();
+        if (key !== "") {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/** 脱敏展示 token：只露首尾各 3 位。 */
+function maskSecret(value) {
+    if (!value) {
+        return "(未配置)";
+    }
+    if (value.length <= 8) {
+        return "***";
+    }
+    return `${value.slice(0, 3)}***${value.slice(-3)}`;
+}
+/**
+ * `ccus api config`：只读写 API 模式配置，不触发拉取。
+ *
+ * 带任意参数时合并并持久化到 api-config.json；不带参数仅打印当前配置。
+ * `--url` 按 `--provider` 落到 zhipu 或 custom 段；`--header "K: V; K2: V2"` 仅作用于 custom。
+ */
+async function handleApiConfig(options) {
+    const dataDir = getDataDir(options);
+    const current = (0, api_mode_1.readApiConfig)(dataDir);
+    const enable = getBooleanOption(options, "enable");
+    const disable = getBooleanOption(options, "disable");
+    const provider = getStringOption(options, "provider");
+    const tokenEnv = getStringOption(options, "token-env");
+    const token = getStringOption(options, "token");
+    const clearToken = getBooleanOption(options, "no-token");
+    const ttlMs = parseDurationMs(getStringOption(options, "ttl"));
+    const timeoutMs = parseDurationMs(getStringOption(options, "timeout"));
+    const userAgent = getStringOption(options, "user-agent");
+    const url = getStringOption(options, "url");
+    const project = getStringOption(options, "project");
+    const organization = getStringOption(options, "organization");
+    const method = getStringOption(options, "method");
+    const headers = parseHeaderFlag(getStringOption(options, "header"));
+    const clearHeaders = getBooleanOption(options, "no-header");
+    const fiveHourPath = getStringOption(options, "five-hour-path");
+    const sevenDayPath = getStringOption(options, "seven-day-path");
+    const extractorInline = getStringOption(options, "extractor");
+    const extractorFile = getStringOption(options, "extractor-file");
+    const clearExtractor = getBooleanOption(options, "no-extractor");
+    let extractorValue;
+    if (clearExtractor) {
+        extractorValue = "";
+    }
+    else if (extractorInline !== undefined) {
+        extractorValue = extractorInline;
+    }
+    else if (extractorFile !== undefined) {
+        const fsp = await Promise.resolve().then(() => __importStar(require("node:fs/promises")));
+        extractorValue = await fsp.readFile(node_path_1.default.resolve(extractorFile), "utf8");
+    }
+    const targetProvider = provider === "custom" || provider === "zhipu" ? provider : current.provider;
+    const next = {
+        ...current,
+        enabled: enable ? true : disable ? false : current.enabled,
+        provider: targetProvider,
+        tokenEnv: tokenEnv ?? current.tokenEnv,
+        token: clearToken ? null : token !== undefined ? token : current.token,
+        cacheTtlMs: ttlMs ?? current.cacheTtlMs,
+        timeoutMs: timeoutMs ?? current.timeoutMs,
+        userAgent: userAgent ?? current.userAgent,
+        zhipu: {
+            url: targetProvider === "zhipu" && url !== undefined ? url : current.zhipu.url,
+            project: project ?? current.zhipu.project,
+            organization: organization ?? current.zhipu.organization,
+        },
+        custom: {
+            url: targetProvider === "custom" && url !== undefined ? url : current.custom.url,
+            method: method ?? current.custom.method,
+            headers: clearHeaders ? {} : headers ?? current.custom.headers,
+            fiveHourPath: fiveHourPath ?? current.custom.fiveHourPath,
+            sevenDayPath: sevenDayPath ?? current.custom.sevenDayPath,
+            extractor: extractorValue !== undefined ? extractorValue : current.custom.extractor,
+        },
+    };
+    const changed = enable ||
+        disable ||
+        clearToken ||
+        clearHeaders ||
+        provider !== undefined ||
+        tokenEnv !== undefined ||
+        token !== undefined ||
+        ttlMs !== null ||
+        timeoutMs !== null ||
+        userAgent !== undefined ||
+        url !== undefined ||
+        project !== undefined ||
+        organization !== undefined ||
+        method !== undefined ||
+        headers !== null ||
+        fiveHourPath !== undefined ||
+        sevenDayPath !== undefined ||
+        extractorValue !== undefined;
+    if (changed) {
+        await (0, api_mode_1.writeApiConfig)(dataDir, next);
+        (0, debug_1.debugLog)("api-mode", "config updated", next);
+    }
+    const header = changed ? "API 模式配置已更新：" : "当前 API 模式配置：";
+    const lines = [
+        `  启用: ${next.enabled ? "是" : "否"}`,
+        `  provider: ${next.provider}`,
+        `  token 环境变量: ${next.tokenEnv}`,
+        `  token 兜底: ${maskSecret(next.token)}`,
+        `  当前生效 token: ${maskSecret((0, api_mode_1.resolveApiToken)(next))}`,
+        `  缓存 TTL: ${formatDurationMs(next.cacheTtlMs)}`,
+        `  请求超时: ${formatDurationMs(next.timeoutMs)}`,
+        `  User-Agent: ${next.userAgent}`,
+        `  [zhipu] url: ${next.zhipu.url}`,
+        `  [zhipu] project: ${next.zhipu.project || "(无)"}`,
+        `  [zhipu] organization: ${next.zhipu.organization || "(无)"}`,
+        `  [custom] url: ${next.custom.url || "(未配置)"}`,
+        `  [custom] method: ${next.custom.method}`,
+        `  [custom] headers: ${Object.keys(next.custom.headers).length > 0 ? JSON.stringify(next.custom.headers) : "(无)"}`,
+        `  [custom] fiveHourPath: ${next.custom.fiveHourPath}`,
+        `  [custom] sevenDayPath: ${next.custom.sevenDayPath}`,
+        `  [custom] extractor: ${next.custom.extractor.trim() !== "" ? `(已配置，${next.custom.extractor.length} 字符；优先于点分路径)` : "(无，用点分路径)"}`,
+    ];
+    process.stdout.write(`${header}\n${lines.join("\n")}\n`);
+}
+/**
+ * `ccus api test`：立即拉取一次第三方额度并打印，验证配置是否生效。
+ *
+ * 直接打真实接口（绕过缓存），成功打印 5h/7d/level，失败把原因打到 stderr 并返回非 0 退出码。
+ */
+async function handleApiTest(options) {
+    const dataDir = getDataDir(options);
+    const config = (0, api_mode_1.readApiConfig)(dataDir);
+    if (!config.enabled) {
+        process.stdout.write("API 模式未启用，先用 `ccus api config --enable` 开启。\n");
+        return;
+    }
+    process.stdout.write(`正在用 provider=${config.provider} 拉取额度（超时 ${formatDurationMs(config.timeoutMs)}）...\n`);
+    try {
+        const quota = await (0, api_mode_1.fetchQuota)(config, process.env);
+        const fiveHour = quota.fiveHour !== null ? `${quota.fiveHour.toFixed(1)}%` : "--";
+        const sevenDay = quota.sevenDay !== null ? `${quota.sevenDay.toFixed(1)}%` : "--";
+        process.stdout.write(`✅ 5h ${fiveHour} | 7d ${sevenDay}${quota.level ? ` | level ${quota.level}` : ""}\n`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`❌ 拉取失败：${message}\n`);
+        process.exitCode = 1;
+    }
+}
+/** `ccus api status`：打印当前 API 模式配置摘要与额度缓存新鲜度。 */
+async function handleApiStatus(options) {
+    const dataDir = getDataDir(options);
+    const config = (0, api_mode_1.readApiConfig)(dataDir);
+    const cache = (0, api_mode_1.readApiQuotaCacheSync)(dataDir);
+    const now = Date.now();
+    let fresh = false;
+    let ageLabel = "(无缓存)";
+    if (cache) {
+        const fetched = Date.parse(cache.fetchedAt);
+        if (Number.isFinite(fetched)) {
+            const ageMs = now - fetched;
+            fresh = ageMs < config.cacheTtlMs;
+            ageLabel = `${formatDurationMs(ageMs)} 前${fresh ? "" : "（已过期）"}`;
+        }
+    }
+    const lines = [
+        `  启用: ${config.enabled ? "是" : "否"}`,
+        `  provider: ${config.provider}`,
+        `  当前生效 token: ${maskSecret((0, api_mode_1.resolveApiToken)(config))}`,
+        `  缓存 TTL: ${formatDurationMs(config.cacheTtlMs)}`,
+        `  缓存状态: ${ageLabel}`,
+    ];
+    if (cache) {
+        const fiveHour = cache.fiveHour !== null ? `${cache.fiveHour.toFixed(1)}%` : "--";
+        const sevenDay = cache.sevenDay !== null ? `${cache.sevenDay.toFixed(1)}%` : "--";
+        lines.push(`  缓存额度: 5h ${fiveHour} | 7d ${sevenDay}${cache.level ? ` | level ${cache.level}` : ""}`);
+    }
+    process.stdout.write(`API 模式状态：\n${lines.join("\n")}\n`);
+}
 /** 顶层命令分发入口。 */
 async function main(args = process.argv.slice(2)) {
     (0, debug_1.setDebugEnabled)((0, debug_1.resolveDebugEnabled)(args));
@@ -875,6 +1102,25 @@ async function main(args = process.argv.slice(2)) {
         await handleSync(parseOptions(args.slice(1)));
         return;
     }
+    if (group === "api") {
+        if (action === "config") {
+            await handleApiConfig(parseOptions(rest));
+            return;
+        }
+        if (action === "test") {
+            await handleApiTest(parseOptions(rest));
+            return;
+        }
+        if (action === "status") {
+            await handleApiStatus(parseOptions(rest));
+            return;
+        }
+        if (action && !action.startsWith("--")) {
+            throw new Error(`Unsupported api argument: ${action}. Use \`ccus api config\`, \`ccus api test\` or \`ccus api status\`.`);
+        }
+        await handleApiStatus(parseOptions(args.slice(1)));
+        return;
+    }
     if (group === "__sync") {
         await handleBackgroundSync(parseOptions(args.slice(1)));
         return;

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/api-mode.js

@@ -0,0 +1,437 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZHIPU_EXTRACTOR = void 0;
+exports.defaultApiConfig = defaultApiConfig;
+exports.readApiConfig = readApiConfig;
+exports.writeApiConfig = writeApiConfig;
+exports.resolveApiToken = resolveApiToken;
+exports.extractCustomQuota = extractCustomQuota;
+exports.runExtractor = runExtractor;
+exports.normalizeExtractorResult = normalizeExtractorResult;
+exports.fetchQuota = fetchQuota;
+exports.readApiQuotaCacheSync = readApiQuotaCacheSync;
+exports.resolveApiQuota = resolveApiQuota;
+exports.applyQuotaToPayload = applyQuotaToPayload;
+const node_fs_1 = __importDefault(require("node:fs"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_http_1 = __importDefault(require("node:http"));
+const node_https_1 = __importDefault(require("node:https"));
+const debug_1 = require("./debug");
+const paths_1 = require("./paths");
+/** 默认智谱额度查询地址（团队视图 query）。 */
+const DEFAULT_ZHIPU_URL = "https://open.bigmodel.cn/api/monitor/usage/quota/limit?type=2";
+/** 默认从哪个环境变量读 token：Claude Code 用第三方 API 时通常注入它。 */
+const DEFAULT_TOKEN_ENV = "ANTHROPIC_AUTH_TOKEN";
+/** 额度缓存 TTL：statusline 高频调用，默认 5 分钟拉一次。 */
+const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000;
+/** 单次额度请求超时。 */
+const DEFAULT_TIMEOUT_MS = 4000;
+/** 默认请求 UA；遇反爬虫可在配置里改成浏览器 UA。 */
+const DEFAULT_USER_AGENT = "ccus/statusline";
+/** 构造一份带默认值的 API 模式配置。 */
+function defaultApiConfig() {
+    return {
+        enabled: false,
+        provider: "zhipu",
+        tokenEnv: DEFAULT_TOKEN_ENV,
+        token: null,
+        cacheTtlMs: DEFAULT_CACHE_TTL_MS,
+        timeoutMs: DEFAULT_TIMEOUT_MS,
+        userAgent: DEFAULT_USER_AGENT,
+        zhipu: { url: DEFAULT_ZHIPU_URL, project: "", organization: "" },
+        custom: {
+            url: "",
+            method: "GET",
+            headers: {},
+            fiveHourPath: "data.five_hour.used_percentage",
+            sevenDayPath: "data.seven_day.used_percentage",
+            extractor: "",
+        },
+    };
+}
+/** 仅把普通对象视作可继续读取字段的记录类型。 */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** 宽松读取数字，兼容 number 和可转成 number 的字符串。 */
+function toNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+/**
+ * 同步读取 API 模式配置；缺省补默认值，任何异常都回退到「未启用」的安全默认。
+ *
+ * statusline 兜底路径需要同步、极快、绝不抛错，所以这里用同步 IO（照搬 readSyncConfig）。
+ */
+function readApiConfig(dataDir) {
+    const base = defaultApiConfig();
+    try {
+        const raw = node_fs_1.default.readFileSync((0, paths_1.getApiConfigPath)(dataDir), "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            enabled: parsed.enabled === true,
+            provider: parsed.provider === "custom" ? "custom" : "zhipu",
+            tokenEnv: typeof parsed.tokenEnv === "string" && parsed.tokenEnv.trim() !== "" ? parsed.tokenEnv : base.tokenEnv,
+            token: typeof parsed.token === "string" && parsed.token.trim() !== "" ? parsed.token : null,
+            cacheTtlMs: typeof parsed.cacheTtlMs === "number" && Number.isFinite(parsed.cacheTtlMs) && parsed.cacheTtlMs >= 0 ? parsed.cacheTtlMs : base.cacheTtlMs,
+            timeoutMs: typeof parsed.timeoutMs === "number" && Number.isFinite(parsed.timeoutMs) && parsed.timeoutMs > 0 ? parsed.timeoutMs : base.timeoutMs,
+            userAgent: typeof parsed.userAgent === "string" && parsed.userAgent.trim() !== "" ? parsed.userAgent : base.userAgent,
+            zhipu: {
+                url: typeof parsed.zhipu?.url === "string" && parsed.zhipu.url.trim() !== "" ? parsed.zhipu.url : base.zhipu.url,
+                project: typeof parsed.zhipu?.project === "string" ? parsed.zhipu.project : "",
+                organization: typeof parsed.zhipu?.organization === "string" ? parsed.zhipu.organization : "",
+            },
+            custom: {
+                url: typeof parsed.custom?.url === "string" ? parsed.custom.url : base.custom.url,
+                method: typeof parsed.custom?.method === "string" && parsed.custom.method.trim() !== "" ? parsed.custom.method : base.custom.method,
+                headers: isRecord(parsed.custom?.headers) ? parsed.custom.headers : base.custom.headers,
+                fiveHourPath: typeof parsed.custom?.fiveHourPath === "string" && parsed.custom.fiveHourPath.trim() !== "" ? parsed.custom.fiveHourPath : base.custom.fiveHourPath,
+                sevenDayPath: typeof parsed.custom?.sevenDayPath === "string" && parsed.custom.sevenDayPath.trim() !== "" ? parsed.custom.sevenDayPath : base.custom.sevenDayPath,
+                extractor: typeof parsed.custom?.extractor === "string" ? parsed.custom.extractor : "",
+            },
+        };
+    }
+    catch {
+        return base;
+    }
+}
+/** 写入 API 模式配置；目录可能尚未创建，先 mkdir。 */
+async function writeApiConfig(dataDir, config) {
+    await promises_1.default.mkdir(dataDir, { recursive: true });
+    await promises_1.default.writeFile((0, paths_1.getApiConfigPath)(dataDir), `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+/** 解析实际 token：优先环境变量，读不到再用配置兜底。 */
+function resolveApiToken(config, env = process.env) {
+    const fromEnv = (env[config.tokenEnv] ?? "").trim();
+    if (fromEnv !== "") {
+        return fromEnv;
+    }
+    return typeof config.token === "string" && config.token.trim() !== "" ? config.token : null;
+}
+/** 把 header 值里的 {{token}} / {{apikey}} 占位符替换成实际 token；token 为空则替换为空串。 */
+function renderHeader(value, token) {
+    return value.replaceAll(/{{\s*(token|apikey)\s*}}/gi, token ?? "");
+}
+/**
+ * 智谱 GLM Coding Plan 的内置 extractor 脚本（zhipu provider 的预设）。
+ *
+ * data.limits 里筛 type==="TOKENS_LIMIT"，按 nextResetTime 升序，第 1 条 = 5h、第 2 条 = 每周；
+ * success !== true / code !== 200 / 缺 data.limits 时返回会让归一化判 null 的值。
+ * zhipu 不再单独维护提取函数，与 custom 走同一条 `runExtractor` 路径，只是 extractor 用这组内置脚本。
+ */
+exports.ZHIPU_EXTRACTOR = `function(response) {
+  if (!response || typeof response !== "object") return null;
+  if (response.success !== undefined && response.success !== true) return null;
+  if (response.code !== undefined && response.code !== 200) return null;
+  const data = response.data;
+  if (!data || typeof data !== "object") return null;
+  const limits = data.limits;
+  if (!Array.isArray(limits)) return null;
+  const tokenLimits = limits
+    .filter((l) => l && l.type === "TOKENS_LIMIT")
+    .map((l) => ({ p: l.percentage, r: l.nextResetTime }))
+    .sort((a, b) => (typeof a.r === "number" ? a.r : Infinity) - (typeof b.r === "number" ? b.r : Infinity));
+  return {
+    fiveHour: tokenLimits[0] ? tokenLimits[0].p : null,
+    sevenDay: tokenLimits[1] ? tokenLimits[1].p : null,
+    level: typeof data.level === "string" && data.level !== "" ? data.level : null,
+  };
+}`;
+/** 按点分路径取值，支持数组索引（如 data.limits.0.percentage）。 */
+function getByPath(value, path) {
+    const parts = path
+        .split(".")
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+    let current = value;
+    for (const part of parts) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        if (Array.isArray(current)) {
+            const idx = Number(part);
+            if (!Number.isInteger(idx)) {
+                return undefined;
+            }
+            current = current[idx];
+        }
+        else if (isRecord(current)) {
+            current = current[part];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return current;
+}
+/** 自定义 provider 响应提取：按点分路径取 5h / 7d 数字。 */
+function extractCustomQuota(json, fiveHourPath, sevenDayPath) {
+    const fiveHour = toNumber(getByPath(json, fiveHourPath));
+    const sevenDay = toNumber(getByPath(json, sevenDayPath));
+    if (fiveHour === null && sevenDay === null) {
+        return null;
+    }
+    return { fiveHour, sevenDay, level: null };
+}
+/**
+ * 用用户提供的 extractor 脚本从响应里提取额度。
+ *
+ * 脚本经 `new Function` 在受限作用域求值，求值结果应为函数，再以响应对象调用。
+ * 返回值兼容三种：`{ fiveHour, sevenDay }`、`[{used|percentage|number}, {used|percentage|number}]`（cc-switch 风格）、`[number, number]`。
+ * 任何异常或非法返回都静默返回 null（debugLog 到 stderr），不抛出、不影响 statusline。
+ *
+ * 注意：脚本在 ccus 进程内以当前权限执行，只配置信任的来源。
+ */
+function runExtractor(script, response) {
+    const trimmed = script.trim();
+    if (trimmed === "") {
+        return null;
+    }
+    try {
+        const factory = new Function(`"use strict"; return (${trimmed});`);
+        const extractor = factory();
+        if (typeof extractor !== "function") {
+            (0, debug_1.debugLog)("api-mode", "extractor script did not evaluate to a function");
+            return null;
+        }
+        return normalizeExtractorResult(extractor(response));
+    }
+    catch (error) {
+        (0, debug_1.debugLog)("api-mode", "extractor script failed", error instanceof Error ? error.message : String(error));
+        return null;
+    }
+}
+/** 把 extractor 返回值归一化成 ApiQuota，兼容对象 / cc-switch 数组 / 数字数组。 */
+function normalizeExtractorResult(result) {
+    if (result === null || result === undefined) {
+        return null;
+    }
+    if (isRecord(result)) {
+        const fiveHour = toNumber(result.fiveHour);
+        const sevenDay = toNumber(result.sevenDay);
+        if (fiveHour === null && sevenDay === null) {
+            return null;
+        }
+        const levelRaw = result.level;
+        const level = typeof levelRaw === "string" && levelRaw.trim() !== "" ? levelRaw : null;
+        return { fiveHour, sevenDay, level };
+    }
+    if (Array.isArray(result)) {
+        const fiveHour = extractArrayNumber(result[0]);
+        const sevenDay = extractArrayNumber(result[1]);
+        if (fiveHour === null && sevenDay === null) {
+            return null;
+        }
+        return { fiveHour, sevenDay, level: null };
+    }
+    return null;
+}
+/** 从 extractor 数组单项里取数字：number 自身，或 {used|percentage|used_percentage}。 */
+function extractArrayNumber(item) {
+    if (typeof item === "number") {
+        return Number.isFinite(item) ? item : null;
+    }
+    if (isRecord(item)) {
+        return toNumber(item.used) ?? toNumber(item.percentage) ?? toNumber(item.used_percentage);
+    }
+    return null;
+}
+/** 按 url 协议发起 HTTP(S) 请求，返回 {status, body}；超时或错误 reject（仿 fetchLatestVersion）。 */
+function httpRequest(url, opts) {
+    return new Promise((resolve, reject) => {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            reject(new Error(`invalid url: ${url}`));
+            return;
+        }
+        const transport = parsed.protocol === "http:" ? node_http_1.default : node_https_1.default;
+        const request = transport.request(url, { method: opts.method, headers: opts.headers }, (response) => {
+            const status = response.statusCode ?? 0;
+            let body = "";
+            response.setEncoding("utf8");
+            response.on("data", (chunk) => {
+                body += chunk;
+            });
+            response.on("end", () => resolve({ status, body }));
+        });
+        request.setTimeout(opts.timeoutMs, () => {
+            request.destroy(new Error("api quota request timed out"));
+        });
+        request.on("error", reject);
+        request.end();
+    });
+}
+/** 根据配置与 token 构造一次额度请求（含 extractor）；配置不完整返回 null。 */
+function prepareQuotaRequest(config, token) {
+    if (config.provider === "custom") {
+        const url = config.custom.url.trim();
+        if (url === "") {
+            return null;
+        }
+        const headers = { "User-Agent": config.userAgent };
+        for (const [key, value] of Object.entries(config.custom.headers)) {
+            headers[key] = renderHeader(value, token);
+        }
+        return {
+            url,
+            method: config.custom.method.toUpperCase() === "POST" ? "POST" : "GET",
+            headers,
+            extract: (json) => {
+                if (config.custom.extractor.trim() !== "") {
+                    return runExtractor(config.custom.extractor, json);
+                }
+                return extractCustomQuota(json, config.custom.fiveHourPath, config.custom.sevenDayPath);
+            },
+        };
+    }
+    // 智谱：Authorization 裸 token + 可选 project/organization 头。
+    const headers = {
+        Authorization: token ?? "",
+        "Content-Type": "application/json",
+        "User-Agent": config.userAgent,
+    };
+    if (config.zhipu.project.trim() !== "") {
+        headers["bigmodel-project"] = config.zhipu.project.trim();
+    }
+    if (config.zhipu.organization.trim() !== "") {
+        headers["bigmodel-organization"] = config.zhipu.organization.trim();
+    }
+    return {
+        url: config.zhipu.url,
+        method: "GET",
+        headers,
+        extract: (json) => runExtractor(exports.ZHIPU_EXTRACTOR, json),
+    };
+}
+/**
+ * 真正发起一次请求并解析额度。
+ *
+ * 任何失败都 reject（HTTP 非 2xx、空响应、解析失败、字段缺失），由调用方决定静默/回退；
+ * 错误信息尽量包含可排查原因（如反爬虫空响应提示改 UA）。
+ */
+async function fetchQuota(config, env = process.env) {
+    const token = resolveApiToken(config, env);
+    const prepared = prepareQuotaRequest(config, token);
+    if (!prepared) {
+        throw new Error(`API 模式 provider=${config.provider} 配置不完整（缺少 url）`);
+    }
+    const { status, body } = await httpRequest(prepared.url, {
+        method: prepared.method,
+        headers: prepared.headers,
+        timeoutMs: config.timeoutMs,
+    });
+    (0, debug_1.debugLog)("api-mode", "quota response", { status, bodyLength: body.length, preview: body.slice(0, 200) });
+    if (status < 200 || status >= 300) {
+        throw new Error(`额度接口返回 HTTP ${status}`);
+    }
+    if (body.trim() === "") {
+        throw new Error("额度接口返回空响应（可能被反爬虫拦截，尝试 `ccus api config --user-agent <浏览器UA>`）");
+    }
+    let json;
+    try {
+        json = JSON.parse(body);
+    }
+    catch (error) {
+        throw new Error(`额度响应不是合法 JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const quota = prepared.extract(json);
+    if (!quota) {
+        throw new Error("额度响应无法解析出 5h/7d（字段路径不对或接口未返回额度数据）");
+    }
+    return quota;
+}
+/** 同步读取额度缓存；损坏/缺失返回 null。 */
+function readApiQuotaCacheSync(dataDir) {
+    try {
+        const raw = node_fs_1.default.readFileSync((0, paths_1.getApiQuotaCachePath)(dataDir), "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.fetchedAt !== "string") {
+            return null;
+        }
+        return {
+            fetchedAt: parsed.fetchedAt,
+            fiveHour: typeof parsed.fiveHour === "number" ? parsed.fiveHour : null,
+            sevenDay: typeof parsed.sevenDay === "number" ? parsed.sevenDay : null,
+            level: typeof parsed.level === "string" && parsed.level.trim() !== "" ? parsed.level : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** 写入额度缓存；失败静默（不能因缓存写入失败影响 statusline 主流程）。 */
+async function writeApiQuotaCache(dataDir, cache) {
+    try {
+        await promises_1.default.mkdir(dataDir, { recursive: true });
+        await promises_1.default.writeFile((0, paths_1.getApiQuotaCachePath)(dataDir), `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+    }
+    catch (error) {
+        (0, debug_1.debugLog)("api-mode", "failed to write quota cache", error instanceof Error ? error.message : String(error));
+    }
+}
+function isCacheFresh(cache, ttlMs, now) {
+    if (!cache) {
+        return false;
+    }
+    const fetched = Date.parse(cache.fetchedAt);
+    if (!Number.isFinite(fetched)) {
+        return false;
+    }
+    return now.getTime() - fetched < ttlMs;
+}
+function quotaFromCache(cache) {
+    return { fiveHour: cache.fiveHour, sevenDay: cache.sevenDay, level: cache.level };
+}
+/**
+ * 缓存优先解析额度：新鲜直接返回；过期同步拉一次（带超时）；拉取失败回退旧缓存，全失败返回 null。
+ *
+ * statusline 路径用，全程不抛错、不写 stdout。`options.fetcher` 供测试注入。
+ */
+async function resolveApiQuota(dataDir, config, env = process.env, options = {}) {
+    const now = options.now ?? new Date();
+    const fetcher = options.fetcher ?? fetchQuota;
+    const cached = readApiQuotaCacheSync(dataDir);
+    if (isCacheFresh(cached, config.cacheTtlMs, now) && cached) {
+        return quotaFromCache(cached);
+    }
+    try {
+        const quota = await fetcher(config, env);
+        await writeApiQuotaCache(dataDir, { ...quota, fetchedAt: now.toISOString() });
+        return quota;
+    }
+    catch (error) {
+        (0, debug_1.debugLog)("api-mode", "quota fetch failed, fallback to cache", error instanceof Error ? error.message : String(error));
+        if (cached) {
+            return quotaFromCache(cached);
+        }
+        return null;
+    }
+}
+/**
+ * 把额度合并写进 rawPayload.rate_limits：保留已有官方字段，补 five_hour / seven_day 的 used_percentage。
+ *
+ * 之后 appendEvent 落盘即带 rate_limits，computeStatuslineEvent 自动算出 usage；raw-first，零契约改动。
+ */
+function applyQuotaToPayload(rawPayload, quota) {
+    const existing = isRecord(rawPayload.rate_limits) ? rawPayload.rate_limits : {};
+    const existingFiveHour = isRecord(existing.five_hour) ? existing.five_hour : {};
+    const existingSevenDay = isRecord(existing.seven_day) ? existing.seven_day : {};
+    rawPayload.rate_limits = {
+        ...existing,
+        five_hour: { ...existingFiveHour, used_percentage: quota.fiveHour },
+        seven_day: { ...existingSevenDay, used_percentage: quota.sevenDay },
+    };
+}
+//# sourceMappingURL=api-mode.js.map

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/dist/lib/paths.js

@@ -9,6 +9,8 @@ exports.getDashboardDir = getDashboardDir;
 exports.getUpdateCachePath = getUpdateCachePath;
 exports.getSyncConfigPath = getSyncConfigPath;
 exports.getSyncStatePath = getSyncStatePath;
+exports.getApiConfigPath = getApiConfigPath;
+exports.getApiQuotaCachePath = getApiQuotaCachePath;
 exports.getClaudeDataDir = getClaudeDataDir;
 exports.getClaudeSettingsPath = getClaudeSettingsPath;
 const node_os_1 = __importDefault(require("node:os"));
@@ -56,6 +58,14 @@ function getSyncConfigPath(dataDir) {
 function getSyncStatePath(dataDir) {
     return node_path_1.default.join(dataDir, "sync-state.json");
 }
+/** API 模式（第三方额度拉取）的用户配置文件，可手编。 */
+function getApiConfigPath(dataDir) {
+    return node_path_1.default.join(dataDir, "api-config.json");
+}
+/** API 模式的额度缓存文件，记录上次抓取的额度与时间。 */
+function getApiQuotaCachePath(dataDir) {
+    return node_path_1.default.join(dataDir, "api-quota-cache.json");
+}
 /** Claude Code 默认本地数据目录。 */
 function getClaudeDataDir() {
     const configured = process.env.CCUS_CLAUDE_DATA_DIR;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccus-cli",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Claude Code statusline usage logger and dashboard CLI",
   "type": "commonjs",
   "bin": {
@@ -16,7 +16,8 @@
     "build": "tsc -p tsconfig.json && node scripts/copy-vendor.js",
     "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 src/test/sync.test.ts src/test/scheduler.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 src/test/api-mode.test.ts",
+    "smoke:api": "node scripts/smoke-api.mjs"
   },
   "keywords": [
     "claude-code",