@lengduan/dsh-usage-stats 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 soon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @lengduan/dsh-usage-stats
+
+DeepSeek Harness 的**用量统计**插件（只统计用量，不做费用计算）。
+
+## 它统计什么
+
+每次模型调用的四类 token：**输入（未命中）/ 输出 / 缓存命中 / 缓存写入**，以及四者之和「总量」，
+按 **天 × 服务商 × 模型** 分桶，落在本地 SQLite 账本里。
+
+## 数据来源（两路实时 + 一路回溯）
+
+| 来源 | 覆盖 | 落库 kind |
+| --- | --- | --- |
+| `session/event` → `assistant/message.usage` | 主对话的每次模型调用（权威、幂等、带 seq） | `chat` |
+| `llm/stream`（仅 `purpose` 非空） | 压缩、摘要、标题生成等 **DSH 内部调用** | `internal` |
+| 启动回溯：`sessionPersistence` 逐个读历史会话 | 插件安装之前的全部对话调用 | `chat` |
+
+- 内部调用不写进会话日志，**只能实时捕获**，所以 `internal` 自插件安装之日起才有数据。
+- 对话调用可用 `sessionPersistence` 服务回溯补齐历史（增量，按 `revision` + `next_seq` 水位）。
+- 两路使用同一主键 `(session_id, record_key)`，`INSERT OR IGNORE` 天然去重，不会双计。
+
+## 存储
+
+`$DSH_HOME/storages/usage-stats/usage.db`（默认 `~/.dsh/storages/usage-stats/usage.db`），`node:sqlite` 内置零依赖，WAL 模式。
+
+**账本是权威事实源，不是会话日志的索引**——删除会话（或会话日志被清理）不会影响已记账的数据。
+
+## 界面
+
+在会话视图顶部新增「用量统计」tab：时间范围（今日 / 本周 / 上周 / 全部 / 指定日期）、
+口径切换（对话 / 内部 / 全部），表格按服务商分组列出各模型的输入 / 输出 / 缓存命中 / 缓存读写 / 总量。
+
+## 安装
+
+从 npm 装（已发布包）：
+
+```sh
+dsh plugin --profile web add @lengduan/dsh-usage-stats
+```
+
+从源码装（本地开发调试）：
+
+```sh
+git clone https://github.com/lengduan/dsh-usage-stats
+cd dsh-usage-stats
+dsh plugin --profile web add .
+```
+
+装完需要重启 dsh web 服务。

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# dsh-usage-stats — bundle patch layer.
+#
+# 安装到 DSH profile 后，loader 会把这一行挂到根 entry 列表上。
+# inject 必须声明：等到 sessionPersistence（回溯历史会话）与 webServer
+# （注册 /usage/api 与前端取数）就绪后再激活 apply。
+- insert:
+    - id: usage-stats
+      name: '@lengduan/dsh-usage-stats'
+      inject:
+        - sessionPersistence
+        - webServer

package/lib/client.js

@@ -0,0 +1,264 @@
+/**
+ * dsh-usage-stats — CLIENT half（浏览器端 bundle，由宿主 __ModuleLoader__ 加载）。
+ *
+ * 在会话视图顶部注册「用量统计」tab，渲染按服务商分组、按模型展开的用量表：
+ *   模型 | 输入 | 输出 | 缓存命中 | 缓存读写 | 总量
+ * 列结构与 PI 的用量统计报表保持一致（总量 = 四类之和）。
+ */
+window.__ModuleLoader__.load({
+  id: "dsh-usage-stats",
+  factory: (require) => {
+    const module = { exports: {} };
+    const exports = module.exports;
+    Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+
+    const React = require("react");
+    const el = React.createElement;
+
+    // ── 文案（中文为键，英文为值；跟随宿主语言） ──────────────────────────
+    const EN = {
+      "用量统计": "Usage Stats",
+      "记录每一次模型调用的 token 用量": "Token usage for every model call",
+      "今日": "Today", "本周": "This week", "上周": "Last week", "全部": "All", "指定日期": "Pick a date",
+      "口径": "Scope", "对话": "Chat", "内部": "Internal",
+      "刷新": "Refresh", "正在加载…": "Loading…", "暂无记录": "No records",
+      "模型": "Model", "输入": "Input", "输出": "Output",
+      "缓存命中": "Cache hit", "缓存读写": "Cache write", "总量": "Total",
+      "总 Token": "Total tokens",
+      "内部调用自插件安装之日起统计，无法回溯历史": "Internal calls are counted from install time; history cannot be backfilled",
+      "账本": "Ledger", "条记录": "records", "会话": "sessions",
+    };
+    let LANG = (() => {
+      try { return String(navigator.language || "en").toLowerCase().startsWith("zh") ? "zh" : "en"; } catch (e) { return "zh"; }
+    })();
+    const t = (s) => (LANG === "en" ? EN[s] || s : s);
+
+    // ── 样式 ──────────────────────────────────────────────────────────────
+    const st = {
+      root: { display: "flex", flexDirection: "column", gap: 12, padding: "16px 20px", width: "100%", boxSizing: "border-box", minWidth: 0 },
+      head: { display: "flex", alignItems: "center", justifyContent: "space-between", gap: 12, flexWrap: "wrap" },
+      title: { fontSize: "1.15em", fontWeight: 600 },
+      sub: { fontSize: "0.85em", opacity: 0.6, marginTop: 2 },
+      bar: { display: "flex", alignItems: "center", gap: 8, flexWrap: "wrap" },
+      seg: { display: "inline-flex", border: "1px solid rgba(128,128,128,.35)", borderRadius: 6, overflow: "hidden" },
+      segBtn: { border: 0, background: "transparent", padding: "4px 10px", fontSize: "0.88em", cursor: "pointer", color: "inherit" },
+      segOn: { border: 0, background: "rgba(90,140,255,.22)", padding: "4px 10px", fontSize: "0.88em", cursor: "pointer", color: "inherit", fontWeight: 600 },
+      btn: { border: "1px solid rgba(128,128,128,.35)", background: "transparent", borderRadius: 6, padding: "4px 10px", fontSize: "0.88em", cursor: "pointer", color: "inherit" },
+      date: { border: "1px solid rgba(128,128,128,.35)", background: "transparent", borderRadius: 6, padding: "3px 8px", fontSize: "0.88em", color: "inherit" },
+      hint: { fontSize: "0.82em", opacity: 0.6 },
+      // 宽表必须可横向滚动，窄屏下列不被挤压
+      tableWrap: { width: "100%", overflowX: "auto", border: "1px solid rgba(128,128,128,.25)", borderRadius: 8 },
+      table: { width: "100%", minWidth: 620, borderCollapse: "collapse", fontSize: "0.9em" },
+      thName: { textAlign: "left", padding: "8px 12px", fontWeight: 600, fontSize: "0.85em", opacity: 0.75, borderBottom: "1px solid rgba(128,128,128,.3)", whiteSpace: "nowrap" },
+      thNum: { textAlign: "right", padding: "8px 12px", fontWeight: 600, fontSize: "0.85em", opacity: 0.75, borderBottom: "1px solid rgba(128,128,128,.3)", whiteSpace: "nowrap" },
+      tdName: { padding: "7px 12px", borderBottom: "1px solid rgba(128,128,128,.15)" },
+      tdNum: { padding: "7px 12px", textAlign: "right", borderBottom: "1px solid rgba(128,128,128,.15)", fontVariantNumeric: "tabular-nums", whiteSpace: "nowrap" },
+      provRow: { background: "rgba(128,128,128,.08)", cursor: "pointer", fontWeight: 600 },
+      modelName: { paddingLeft: 28, opacity: 0.9 },
+      totalRow: { fontWeight: 700, borderTop: "2px solid rgba(128,128,128,.45)" },
+      empty: { padding: "24px 12px", textAlign: "center", opacity: 0.6, fontSize: "0.9em" },
+      err: { padding: "10px 12px", borderRadius: 6, background: "rgba(220,60,60,.12)", fontSize: "0.88em" },
+    };
+
+    // ── 避让宿主的对话宽度把手 ────────────────────────────────────────────
+    // 宿主在对话正文两侧各放一条 40px 的 col-resize 把手（ui-conversation
+    // ConversationRoot，z-index 8），只在对话视图下有意义，且仅对带 composer
+    // overlay 的视图自我隐藏。本页铺满对话列，把手会盖住页内按钮并抢走
+    // pointerdown。抬本页层级能盖住把手，但底部输入框只有 z-index 7，本页反
+    // 而会压住输入框；因此改为在用量页挂载期间隐藏把手——切回对话 tab 时本页
+    // 卸载，body:has 失配，把手自动恢复。
+    if (typeof document !== "undefined" && !document.getElementById("dsh-usage-stats-handle-fix")) {
+      const style = document.createElement("style");
+      style.id = "dsh-usage-stats-handle-fix";
+      style.textContent = "body:has([data-usage-stats]) [data-width-handle]{display:none}";
+      document.head.append(style);
+    }
+
+    // ── 工具 ──────────────────────────────────────────────────────────────
+    /** KM 格式化：>=1e6 用 M，>=1e3 用 K，两位小数（与 PI 报表一致）。 */
+    function kmb(n) {
+      const v = Number(n) || 0;
+      if (v >= 1e6) return (v / 1e6).toFixed(2) + "M";
+      if (v >= 1e3) return (v / 1e3).toFixed(2) + "K";
+      return String(v);
+    }
+    /** 精确值：千分位分隔，用于 hover 提示。 */
+    function exact(n) {
+      return String(Math.round(Number(n) || 0)).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+    }
+    function api(payload) {
+      return fetch("/usage/api", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+      }).then((r) => r.json());
+    }
+
+    // ── 用量表 ────────────────────────────────────────────────────────────
+    function StatsTable(props) {
+      const rows = props.rows || [];
+      const [collapsed, setCollapsed] = React.useState({});
+
+      const visible = React.useMemo(() => {
+        const out = [];
+        let hide = false;
+        for (const row of rows) {
+          if (row.level === "provider") {
+            hide = !!collapsed[row.name];
+            out.push(row);
+          } else if (row.level === "model") {
+            if (!hide) out.push(row);
+          } else {
+            out.push(row);
+          }
+        }
+        return out;
+      }, [rows, collapsed]);
+
+      const cells = (row) => [
+        el("td", { key: "n", style: Object.assign({}, st.tdName, row.level === "model" ? st.modelName : null) },
+          row.level === "model" ? "└─ " + row.name : row.name),
+        el("td", { key: "i", style: st.tdNum, title: exact(row.input) }, kmb(row.input)),
+        el("td", { key: "o", style: st.tdNum, title: exact(row.output) }, kmb(row.output)),
+        el("td", { key: "r", style: st.tdNum, title: exact(row.cacheRead) }, kmb(row.cacheRead)),
+        el("td", { key: "w", style: st.tdNum, title: exact(row.cacheWrite) }, kmb(row.cacheWrite)),
+        el("td", { key: "t", style: st.tdNum, title: exact(row.total) }, kmb(row.total)),
+      ];
+
+      return el("div", { style: st.tableWrap },
+        el("table", { style: st.table },
+          el("thead", null, el("tr", null,
+            el("th", { style: st.thName }, t("模型")),
+            el("th", { style: st.thNum }, t("输入")),
+            el("th", { style: st.thNum }, t("输出")),
+            el("th", { style: st.thNum }, t("缓存命中")),
+            el("th", { style: st.thNum }, t("缓存读写")),
+            el("th", { style: st.thNum }, t("总量")),
+          )),
+          el("tbody", null, visible.map((row, idx) => {
+            const style = row.level === "provider" ? st.provRow : row.level === "total" ? st.totalRow : null;
+            const onClick = row.level === "provider"
+              ? () => setCollapsed((prev) => Object.assign({}, prev, { [row.name]: !prev[row.name] }))
+              : undefined;
+            return el("tr", {
+              key: row.level + ":" + (row.provider || "") + ":" + row.name + ":" + idx,
+              style,
+              onClick,
+            },
+              row.level === "provider"
+                ? [
+                  el("td", { key: "n", style: st.tdName }, (collapsed[row.name] ? "▸ " : "▾ ") + row.name + "  ·  " + row.messages + " " + t("条记录")),
+                  el("td", { key: "i", style: st.tdNum, title: exact(row.input) }, kmb(row.input)),
+                  el("td", { key: "o", style: st.tdNum, title: exact(row.output) }, kmb(row.output)),
+                  el("td", { key: "r", style: st.tdNum, title: exact(row.cacheRead) }, kmb(row.cacheRead)),
+                  el("td", { key: "w", style: st.tdNum, title: exact(row.cacheWrite) }, kmb(row.cacheWrite)),
+                  el("td", { key: "t", style: st.tdNum, title: exact(row.total) }, kmb(row.total)),
+                ]
+                : cells(row));
+          })),
+        ));
+    }
+
+    // ── 主面板 ────────────────────────────────────────────────────────────
+    const RANGES = [
+      { k: "today", label: "今日" },
+      { k: "week", label: "本周" },
+      { k: "lastweek", label: "上周" },
+      { k: "all", label: "全部" },
+      { k: "date", label: "指定日期" },
+    ];
+    const KINDS = [
+      { k: "all", label: "全部" },
+      { k: "chat", label: "对话" },
+      { k: "internal", label: "内部" },
+    ];
+
+    function UsageStatsPanel() {
+      const [range, setRange] = React.useState("today");
+      const [kind, setKind] = React.useState("all");
+      const [date, setDate] = React.useState("");
+      const [state, setState] = React.useState({ status: "loading", data: null, error: "" });
+
+      const load = React.useCallback(() => {
+        setState((prev) => ({ status: "loading", data: prev.data, error: "" }));
+        api({ action: "summary", range, kind, date: range === "date" && date ? date : undefined })
+          .then((res) => {
+            if (res && res.ok) setState({ status: "done", data: res, error: "" });
+            else setState({ status: "error", data: null, error: (res && res.error) || t("暂无记录") });
+          })
+          .catch((e) => setState({ status: "error", data: null, error: String((e && e.message) || e) }));
+      }, [range, kind, date]);
+
+      React.useEffect(() => { load(); }, [load]);
+
+      const data = state.data || {};
+      const rows = data.rows || [];
+      const hasData = rows.length > 1 || (data.messages || 0) > 0;
+
+      return el("div", { style: st.root, "data-usage-stats": "" },
+        el("div", { style: st.head },
+          el("div", null,
+            el("div", { style: st.title }, t("用量统计")),
+            el("div", { style: st.sub }, data.label || t("记录每一次模型调用的 token 用量")),
+          ),
+          el("div", { style: st.bar },
+            el("button", { style: st.btn, onClick: load }, t("刷新")),
+          ),
+        ),
+
+        el("div", { style: st.bar },
+          el("span", { style: st.hint }, t("口径") + ":"),
+          el("div", { style: st.seg }, KINDS.map((item) =>
+            el("button", { key: item.k, style: kind === item.k ? st.segOn : st.segBtn, onClick: () => setKind(item.k) }, t(item.label)))),
+          el("span", { style: { width: 8 } }),
+          el("div", { style: st.seg }, RANGES.map((item) =>
+            el("button", { key: item.k, style: range === item.k ? st.segOn : st.segBtn, onClick: () => setRange(item.k) }, t(item.label)))),
+          range === "date"
+            ? el("input", { type: "date", style: st.date, value: date, onChange: (e) => setDate(e.target.value) })
+            : null,
+        ),
+
+        kind !== "chat"
+          ? el("div", { style: st.hint }, t("内部调用自插件安装之日起统计，无法回溯历史"))
+          : null,
+
+        state.error
+          ? el("div", { style: st.err }, state.error)
+          : null,
+
+        state.status === "loading" && !hasData
+          ? el("div", { style: st.empty }, t("正在加载…"))
+          : hasData
+            ? el(StatsTable, { rows })
+            : el("div", { style: st.empty }, t("暂无记录")),
+      );
+    }
+
+    // ── 插件注册 ──────────────────────────────────────────────────────────
+    const inject = ["slots"];
+
+    function apply(ctx) {
+      const slots = ctx.get("slots");
+      if (slots === undefined) return;
+
+      const locale = ctx.get("locale");
+      try {
+        if (locale && typeof locale.getLocale === "function") {
+          const snap = locale.getLocale();
+          LANG = snap && snap.active === "zh" ? "zh" : "en";
+        }
+      } catch (e) { /* 语言服务不可读时沿用浏览器语言 */ }
+
+      slots.inject("conversation.view", () => slots.register(
+        { name: "conversation.view", id: "usage-stats", order: 25, label: () => t("用量统计") },
+        UsageStatsPanel,
+      ));
+    }
+
+    exports.inject = inject;
+    exports.apply = apply;
+
+    // __ModuleLoader__ 用 factory 的返回值作为模块导出，漏掉它会拿到 undefined。
+    return module.exports;
+  },
+});

package/lib/index.js

@@ -0,0 +1,477 @@
+/**
+ * dsh-usage-stats — HOST half.
+ *
+ * 只做用量统计，不做费用计算。统计每次模型调用的四类 token
+ * （输入未命中 / 输出 / 缓存命中 / 缓存写入）与总量，按 天 × 服务商 × 模型 落库。
+ *
+ * 三条数据来源：
+ *   1. `session/event` → `assistant/message.usage`：主对话的权威事实，kind='chat'。
+ *      事件是 post-commit 广播且不重放，带 seq / messageId，天然幂等。
+ *   2. `llm/stream`（仅 purpose 非空）：压缩、摘要、标题生成等 DSH 内部调用，
+ *      kind='internal'。这类调用不写进会话日志，只能实时捕获。
+ *   3. 启动回溯：读 `sessionPersistence` 里的历史会话，补齐插件安装前的对话调用。
+ *
+ * 三路共用主键 (session_id, record_key)，靠 INSERT OR IGNORE 去重。
+ * 账本是权威事实源，不依赖会话文件；删除会话不影响已记账数据。
+ */
+import path from 'node:path'
+import os from 'node:os'
+import { mkdirSync } from 'node:fs'
+import { DatabaseSync } from 'node:sqlite'
+
+const pad2 = (n) => (n < 10 ? '0' : '') + n
+
+/** 本地日历日 YYYY-MM-DD（与 DSH / 官方账单的本地口径一致）。 */
+function dayKey(ts) {
+  const d = new Date(ts)
+  return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`
+}
+
+/** 本地时区当天 00:00 的毫秒时间戳。 */
+function startOfDay(d) {
+  const x = new Date(d.getTime())
+  x.setHours(0, 0, 0, 0)
+  return x
+}
+
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0)
+
+/**
+ * 把一条 provider usage 归一成账本的四类桶 + 总量。
+ * `totalTokens` 由 provider 给出时优先采用；缺失时四类相加。
+ */
+function buckets(u) {
+  const input = num(u?.inputTokens)
+  const output = num(u?.outputTokens)
+  const cacheRead = num(u?.cacheReadTokens)
+  const cacheWrite = num(u?.cacheWriteTokens)
+  const total = typeof u?.totalTokens === 'number' && Number.isFinite(u.totalTokens)
+    ? u.totalTokens
+    : input + output + cacheRead + cacheWrite
+  return { input, output, cacheRead, cacheWrite, total }
+}
+
+/** 账本文件：$DSH_HOME/storages/usage-stats/usage.db。 */
+function resolveDbPath() {
+  const home = process.env.DSH_HOME || path.join(os.homedir(), '.dsh')
+  return path.join(home, 'storages', 'usage-stats', 'usage.db')
+}
+
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS usage_calls (
+    session_id  TEXT    NOT NULL,
+    record_key  TEXT    NOT NULL,
+    kind        TEXT    NOT NULL,
+    time        INTEGER NOT NULL,
+    day         TEXT    NOT NULL,
+    provider    TEXT    NOT NULL DEFAULT '',
+    model       TEXT    NOT NULL DEFAULT '',
+    purpose     TEXT    NOT NULL DEFAULT '',
+    input       INTEGER NOT NULL DEFAULT 0,
+    output      INTEGER NOT NULL DEFAULT 0,
+    cache_read  INTEGER NOT NULL DEFAULT 0,
+    cache_write INTEGER NOT NULL DEFAULT 0,
+    total       INTEGER NOT NULL DEFAULT 0,
+    PRIMARY KEY (session_id, record_key)
+  );
+  CREATE INDEX IF NOT EXISTS idx_calls_day ON usage_calls (day);
+  CREATE INDEX IF NOT EXISTS idx_calls_day_kind ON usage_calls (day, kind);
+  CREATE INDEX IF NOT EXISTS idx_calls_group ON usage_calls (kind, provider, model);
+
+  CREATE TABLE IF NOT EXISTS scan_state (
+    session_id TEXT PRIMARY KEY,
+    revision   TEXT    NOT NULL DEFAULT '',
+    next_seq   INTEGER NOT NULL DEFAULT 0,
+    updated_at INTEGER NOT NULL DEFAULT 0
+  );
+`
+
+/** 用量账本：一个 SQLite 文件，WAL 模式，逐条 INSERT OR IGNORE。 */
+class Ledger {
+  constructor(dbPath) {
+    mkdirSync(path.dirname(dbPath), { recursive: true })
+    this.dbPath = dbPath
+    this.db = new DatabaseSync(dbPath)
+    this.db.exec('PRAGMA journal_mode = WAL')
+    this.db.exec('PRAGMA synchronous = NORMAL')
+    this.db.exec(SCHEMA)
+    this.insert = this.db.prepare(`
+      INSERT OR IGNORE INTO usage_calls
+        (session_id, record_key, kind, time, day, provider, model, purpose,
+         input, output, cache_read, cache_write, total)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `)
+    this.getState = this.db.prepare('SELECT revision, next_seq FROM scan_state WHERE session_id = ?')
+    this.putState = this.db.prepare(`
+      INSERT INTO scan_state (session_id, revision, next_seq, updated_at) VALUES (?, ?, ?, ?)
+      ON CONFLICT(session_id) DO UPDATE SET
+        revision = excluded.revision, next_seq = excluded.next_seq, updated_at = excluded.updated_at
+    `)
+  }
+
+  /** 记一笔；主键冲突（同一 session 的同一条消息）直接忽略。 */
+  add(rec) {
+    this.insert.run(
+      String(rec.sessionId || ''), String(rec.recordKey || ''), String(rec.kind || 'chat'),
+      Math.round(num(rec.time)), dayKey(num(rec.time)),
+      String(rec.provider || ''), String(rec.model || ''), String(rec.purpose || ''),
+      Math.round(num(rec.input)), Math.round(num(rec.output)),
+      Math.round(num(rec.cacheRead)), Math.round(num(rec.cacheWrite)), Math.round(num(rec.total)),
+    )
+  }
+
+  scanState(sessionId) {
+    const row = this.getState.get(String(sessionId))
+    if (!row) return null
+    return { revision: String(row.revision || ''), nextSeq: Number(row.next_seq) || 0 }
+  }
+
+  setScanState(sessionId, revision, nextSeq) {
+    this.putState.run(String(sessionId), String(revision || ''), Math.round(num(nextSeq)), Date.now())
+  }
+
+  /**
+   * 按范围聚合，返回扁平行数组（provider 汇总行 → 其下模型行 → 总计行），
+   * 结构与 PI 的用量统计报表一致，前端可直接映射成表格行。
+   */
+  summary({ from, to, kind }) {
+    const conds = []
+    const params = []
+    if (from) { conds.push('day >= ?'); params.push(from) }
+    if (to) { conds.push('day <= ?'); params.push(to) }
+    if (kind === 'chat' || kind === 'internal') { conds.push('kind = ?'); params.push(kind) }
+    const where = conds.length ? ' WHERE ' + conds.join(' AND ') : ''
+    const groups = this.db.prepare(`
+      SELECT provider, model,
+             SUM(input) AS input, SUM(output) AS output,
+             SUM(cache_read) AS cacheRead, SUM(cache_write) AS cacheWrite,
+             SUM(total) AS total, COUNT(*) AS messages
+      FROM usage_calls${where}
+      GROUP BY provider, model
+    `).all(...params)
+
+    const zero = () => ({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0, messages: 0 })
+    const addInto = (dst, src) => {
+      dst.input += src.input; dst.output += src.output
+      dst.cacheRead += src.cacheRead; dst.cacheWrite += src.cacheWrite
+      dst.total += src.total; dst.messages += src.messages
+    }
+
+    const byProvider = new Map()
+    const total = zero()
+    for (const g of groups) {
+      const provider = String(g.provider || '（未知服务商）')
+      const row = {
+        name: String(g.model || 'unknown'),
+        input: num(g.input), output: num(g.output),
+        cacheRead: num(g.cacheRead), cacheWrite: num(g.cacheWrite),
+        total: num(g.total), messages: num(g.messages),
+      }
+      let bucket = byProvider.get(provider)
+      if (!bucket) {
+        bucket = { name: provider, sum: zero(), models: [] }
+        byProvider.set(provider, bucket)
+      }
+      bucket.models.push(row)
+      addInto(bucket.sum, row)
+      addInto(total, row)
+    }
+
+    const providers = [...byProvider.values()].sort((a, b) => b.sum.total - a.sum.total)
+    const rows = []
+    for (const p of providers) {
+      rows.push({ level: 'provider', name: p.name, ...p.sum })
+      for (const m of p.models.sort((a, b) => b.total - a.total)) {
+        rows.push({ level: 'model', name: m.name, provider: p.name, ...m })
+      }
+    }
+    rows.push({ level: 'total', name: '总 Token', ...total })
+
+    return { rows, total, messages: total.messages, providers: providers.length }
+  }
+
+  /** 账本概况：给界面显示数据量与覆盖范围。 */
+  status() {
+    const row = this.db.prepare(`
+      SELECT COUNT(*) AS calls,
+             MIN(day) AS firstDay, MAX(day) AS lastDay,
+             SUM(CASE WHEN kind = 'chat' THEN 1 ELSE 0 END) AS chatCalls,
+             SUM(CASE WHEN kind = 'internal' THEN 1 ELSE 0 END) AS internalCalls
+      FROM usage_calls
+    `).get()
+    let sessions = 0
+    try { sessions = Number(this.db.prepare('SELECT COUNT(*) AS n FROM scan_state').get()?.n) || 0 } catch (e) { sessions = 0 }
+    return {
+      dbPath: this.dbPath,
+      calls: num(row?.calls),
+      chatCalls: num(row?.chatCalls),
+      internalCalls: num(row?.internalCalls),
+      firstDay: row?.firstDay || null,
+      lastDay: row?.lastDay || null,
+      sessionsTracked: sessions,
+    }
+  }
+
+  close() {
+    try { this.db.close() } catch (e) { /* 关闭失败不影响退出 */ }
+  }
+}
+
+/** 把请求体读成 JSON（解析失败按空对象处理）。 */
+function readBody(req) {
+  return new Promise((resolve) => {
+    let text = ''
+    req.on('data', (c) => { text += c })
+    req.on('end', () => { try { resolve(JSON.parse(text)) } catch (e) { resolve({}) } })
+    req.on('error', () => resolve({}))
+  })
+}
+
+function sendJson(res, obj) {
+  res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' })
+  res.end(JSON.stringify(obj))
+}
+
+/**
+ * 把请求的 range 参数换算成 [from, to] 的本地日历日闭区间。
+ * 周区间以周一为起点，与 PI 的用量报表口径保持一致。
+ */
+function resolveRange(range, dateArg) {
+  const today = dayKey(Date.now())
+  if (range === 'all') return { from: null, to: null, label: '全部' }
+
+  if (range === 'date') {
+    const d = String(dateArg || '')
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(d)) return { from: today, to: today, label: `今日 ${today}` }
+    return { from: d, to: d, label: d }
+  }
+
+  if (range === 'week') {
+    const base = startOfDay(new Date())
+    const weekday = (base.getDay() + 6) % 7 // 周一 = 0
+    const start = new Date(base.getTime() - weekday * 86400000)
+    const from = dayKey(start.getTime())
+    return { from, to: today, label: `本周（${from} 起）` }
+  }
+
+  if (range === 'lastweek') {
+    const base = startOfDay(new Date())
+    const weekday = (base.getDay() + 6) % 7
+    const thisStart = new Date(base.getTime() - weekday * 86400000)
+    const lastStart = new Date(thisStart.getTime() - 7 * 86400000)
+    const lastEnd = new Date(thisStart.getTime() - 1)
+    const from = dayKey(lastStart.getTime())
+    const to = dayKey(lastEnd.getTime())
+    return { from, to, label: `上周（${from} ~ ${to}）` }
+  }
+
+  return { from: today, to: today, label: `今日 ${today}` }
+}
+
+export default {
+  inject: ['sessionPersistence', 'webServer'],
+  apply(ctx) {
+    const warn = (message) => { try { ctx.logger?.warn?.(`[dsh-usage-stats] ${message}`) } catch (e) { /* 日志不可用则静默 */ } }
+
+    let ledger = null
+    try {
+      ledger = new Ledger(resolveDbPath())
+    } catch (error) {
+      warn(`账本打开失败：${error instanceof Error ? error.message : String(error)}`)
+    }
+
+    const currentAgent = () => {
+      try {
+        const agents = ctx.get('agents')
+        if (agents && typeof agents.currentInitiator === 'function') return agents.currentInitiator()
+      } catch (e) { /* agents 服务可选 */ }
+      return undefined
+    }
+
+    // 会话 → 最近一次请求头里的 provider/model；message.source 缺失时兜底。
+    const headers = new Map()
+    const rememberHeader = (sessionId, header) => {
+      if (!header || typeof header.provider !== 'string' || typeof header.model !== 'string') return
+      if (!headers.has(sessionId) && headers.size >= 500) {
+        const oldest = headers.keys().next().value
+        if (oldest !== undefined) headers.delete(oldest)
+      }
+      headers.set(sessionId, { provider: header.provider, model: header.model })
+    }
+
+    if (ledger) {
+      // ── 路 1：会话事件（主对话，权威事实） ─────────────────────────────
+      try {
+        ctx.on('session/event', (session, event) => {
+          try {
+            const sessionId = String(session?.id ?? '')
+            if (event?.type === 'request/header') {
+              rememberHeader(sessionId, event.data?.header?.config)
+              return
+            }
+            if (event?.type !== 'assistant/message') return
+            const usage = event.data?.usage
+            if (!usage) return
+            const source = event.data?.message?.source
+            const header = headers.get(sessionId)
+            ledger.add({
+              sessionId,
+              recordKey: String(event.data?.message?.id ?? `seq-${event.seq}`),
+              kind: 'chat',
+              time: num(event.time),
+              provider: (typeof source?.provider === 'string' && source.provider) || header?.provider || '',
+              model: (typeof source?.model === 'string' && source.model) || header?.model || 'unknown',
+              purpose: '',
+              ...buckets(usage),
+            })
+          } catch (error) {
+            warn(`记录会话事件失败：${error instanceof Error ? error.message : String(error)}`)
+          }
+        })
+      } catch (error) {
+        warn(`订阅 session/event 失败：${error instanceof Error ? error.message : String(error)}`)
+      }
+
+      // ── 路 2：LLM 流（只记 purpose 非空的内部调用） ─────────────────────
+      // 主对话不在这里记账，直接透传原始流，零额外开销。
+      try {
+        ctx.on('llm/stream', (options, next) => {
+          const source = next()
+          const purpose = options?.purpose ? String(options.purpose) : ''
+          if (!purpose) return source
+
+          const provider = String(options?.provider || '')
+          const model = String(options?.model || '')
+          const startedAt = Date.now()
+          let sessionId = options?.sessionId ? String(options.sessionId) : ''
+          let usage = null
+
+          async function* observe() {
+            try {
+              for await (const chunk of source) {
+                if (chunk?.type === 'usage' && chunk.usage) usage = chunk.usage
+                yield chunk
+              }
+            } finally {
+              try {
+                if (!sessionId) {
+                  const agent = currentAgent()
+                  if (agent?.session?.id) sessionId = String(agent.session.id)
+                }
+                if (usage) {
+                  ledger.add({
+                    sessionId: sessionId || '（内部）',
+                    recordKey: `internal:${purpose}:${startedAt}`,
+                    kind: 'internal',
+                    time: startedAt,
+                    provider, model, purpose,
+                    ...buckets(usage),
+                  })
+                }
+              } catch (error) {
+                warn(`记录内部调用失败：${error instanceof Error ? error.message : String(error)}`)
+              }
+            }
+          }
+
+          return observe()
+        })
+      } catch (error) {
+        warn(`订阅 llm/stream 失败：${error instanceof Error ? error.message : String(error)}`)
+      }
+
+      // ── 路 3：历史回溯（补齐插件安装前的对话调用） ──────────────────────
+      // 内部调用不在会话日志里，无法回溯，只能靠路 2 实时捕获。
+      const backfill = async () => {
+        const persistence = ctx.get('sessionPersistence')
+        if (!persistence || typeof persistence.list !== 'function') return
+        let snapshots = []
+        try {
+          snapshots = await persistence.list()
+        } catch (error) {
+          warn(`列出会话失败：${error instanceof Error ? error.message : String(error)}`)
+          return
+        }
+        let scanned = 0
+        let added = 0
+        for (const snapshot of snapshots) {
+          const sessionId = String(snapshot?.header?.id ?? '')
+          if (!sessionId) continue
+          const revision = String(snapshot?.revision ?? '')
+          const state = ledger.scanState(sessionId)
+          if (state && revision && state.revision === revision) continue
+
+          let handle = null
+          try {
+            handle = await persistence.open(sessionId, 'read')
+            const fromSeq = state ? state.nextSeq : 0
+            const { events } = await handle.read(fromSeq)
+            let maxSeq = fromSeq - 1
+            for (const event of events) {
+              if (typeof event?.seq === 'number' && event.seq > maxSeq) maxSeq = event.seq
+              if (event?.type !== 'assistant/message') continue
+              const usage = event.data?.usage
+              if (!usage) continue
+              const source = event.data?.message?.source
+              ledger.add({
+                sessionId,
+                recordKey: String(event.data?.message?.id ?? `seq-${event.seq}`),
+                kind: 'chat',
+                time: num(event.time),
+                provider: typeof source?.provider === 'string' ? source.provider : '',
+                model: typeof source?.model === 'string' ? source.model : 'unknown',
+                purpose: '',
+                ...buckets(usage),
+              })
+              added += 1
+            }
+            ledger.setScanState(sessionId, revision, maxSeq + 1)
+            scanned += 1
+          } catch (error) {
+            warn(`回溯会话 ${sessionId} 失败：${error instanceof Error ? error.message : String(error)}`)
+          } finally {
+            try { await handle?.close?.() } catch (e) { /* 句柄已关闭 */ }
+          }
+        }
+        if (scanned > 0) warn(`历史回溯完成：扫描 ${scanned} 个会话，补录 ${added} 条用量`)
+      }
+
+      // 异步跑，不阻塞插件激活与 web 服务启动。
+      Promise.resolve().then(backfill).catch((error) => {
+        warn(`历史回溯异常：${error instanceof Error ? error.message : String(error)}`)
+      })
+    }
+
+    // ── API ───────────────────────────────────────────────────────────────
+    const route = (body) => {
+      if (!ledger) return { ok: false, error: '账本不可用（SQLite 打开失败）' }
+      const action = body?.action ? String(body.action) : 'summary'
+      if (action === 'status') return { ok: true, ...ledger.status() }
+      if (action === 'summary') {
+        const kind = ['chat', 'internal', 'all'].includes(body?.kind) ? String(body.kind) : 'all'
+        const range = resolveRange(body?.range, body?.date)
+        return { ok: true, label: range.label, range: { from: range.from, to: range.to }, kind, ...ledger.summary({ ...range, kind }) }
+      }
+      return { ok: false, error: `未知操作：${action}` }
+    }
+
+    const webServer = ctx.get('webServer')
+    if (webServer && typeof webServer.register === 'function') {
+      ctx.effect(() => webServer.register({
+        kind: 'exact',
+        path: '/usage/api',
+        handler: async (req, res) => {
+          try {
+            sendJson(res, route(await readBody(req)))
+          } catch (error) {
+            sendJson(res, { ok: false, error: error instanceof Error ? error.message : String(error) })
+          }
+        },
+      }), 'dsh-usage-stats: /usage/api')
+    } else {
+      warn('webServer 不可用，/usage/api 未注册')
+    }
+
+    ctx.effect(() => () => { ledger?.close() }, 'dsh-usage-stats: 关闭账本')
+  },
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@lengduan/dsh-usage-stats",
+  "version": "0.1.0",
+  "description": "DSH 用量统计插件：SQLite 本地账本，按天 / 按模型统计输入、输出、缓存命中、总计；区分对话调用与内部调用，只统计用量不做费用计算。",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lengduan/dsh-usage-stats.git"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.5"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
+    }
+  },
+  "scripts": {
+    "verify": "node scripts/verify.mjs"
+  },
+  "files": [
+    "lib",
+    "scripts",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1"
+  }
+}

package/scripts/verify.mjs

@@ -0,0 +1,95 @@
+/**
+ * 插件自检：在装载进 profile 之前验证两半都能被宿主正常加载。
+ *
+ * 覆盖两类曾经真实翻车的问题：
+ *   1. host 半：ESM 能否 import、是否导出 inject / apply。
+ *   2. client 半：factory 是否 return module.exports（漏掉会让 boot 收到 undefined，
+ *      插件静默失效，而 dsh web 本身仍能正常启动）。
+ * 另外模拟一次 apply，确认 tab 真的注册到了 conversation.view。
+ *
+ * 用法：node scripts/verify.mjs
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import vm from 'node:vm'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+let failed = 0
+
+function check(label, ok, detail = '') {
+  console.log(`${ok ? '  [ok]' : '  [FAIL]'} ${label}${detail ? '  — ' + detail : ''}`)
+  if (!ok) failed += 1
+}
+
+// ── host 半 ───────────────────────────────────────────────────────────────
+console.log('host 半 lib/index.js')
+const host = (await import(pathToFileURL(path.join(root, 'lib', 'index.js')).href)).default
+check('可 import 且 default 导出对象', !!host && typeof host === 'object')
+check('apply 是函数', typeof host?.apply === 'function')
+check('inject 是数组', Array.isArray(host?.inject), JSON.stringify(host?.inject))
+
+// ── client 半 ─────────────────────────────────────────────────────────────
+console.log('client 半 lib/client.js')
+const code = fs.readFileSync(path.join(root, 'lib', 'client.js'), 'utf8')
+let definition = null
+const sandbox = {
+  window: { __ModuleLoader__: { load: (def) => { definition = def } } },
+  console,
+}
+vm.createContext(sandbox)
+try {
+  vm.runInContext(code, sandbox)
+} catch (error) {
+  check('脚本可执行', false, String(error?.message ?? error))
+}
+check('调用 __ModuleLoader__.load 注册了模块', !!definition)
+check('id 与包名一致', definition?.id === 'dsh-usage-stats', String(definition?.id))
+
+const React = {
+  createElement: () => null,
+  useState: () => [null, () => {}],
+  useEffect: () => {},
+  useMemo: (fn) => fn(),
+  useCallback: (fn) => fn,
+}
+const fakeRequire = (name) => {
+  if (name === 'react') return React
+  throw new Error(`未声明的外部模块：${name}`)
+}
+
+let exported = null
+try {
+  exported = definition.factory(fakeRequire)
+} catch (error) {
+  check('factory 可调用', false, String(error?.message ?? error))
+}
+// 这一条就是防"忘记 return module.exports"的回归
+check('factory 返回模块对象（不是 undefined）', exported !== null && typeof exported === 'object')
+check('导出 apply', typeof exported?.apply === 'function')
+check('导出 inject', Array.isArray(exported?.inject))
+
+// 模拟宿主 ctx，确认 apply 真的注册了 tab
+let registered = null
+const ctx = {
+  get(name) {
+    if (name === 'slots') {
+      return {
+        inject: (_slotName, fn) => fn(),
+        register: (options, Component) => { registered = { options, Component }; return () => {} },
+      }
+    }
+    return undefined
+  },
+}
+try {
+  exported?.apply?.(ctx)
+} catch (error) {
+  check('apply 可执行', false, String(error?.message ?? error))
+}
+check('注册到 conversation.view', registered?.options?.name === 'conversation.view')
+check('tab id 正确', registered?.options?.id === 'usage-stats', String(registered?.options?.id))
+check('tab label 可用', typeof registered?.options?.label === 'function' && !!registered.options.label())
+
+console.log(failed === 0 ? '\n自检通过。' : `\n自检失败：${failed} 项。`)
+process.exit(failed === 0 ? 0 : 1)