@lengduan/dsh-usage-stats 0.1.0 → 0.1.2

package/README.md

@@ -1,44 +1,57 @@
 # @lengduan/dsh-usage-stats
 
-DeepSeek Harness 的**用量统计**插件（只统计用量，不做费用计算）。
+DeepSeek Harness 的**用量统计**插件。每次模型调用的四类 token 落进本地 SQLite 账本，按 天 × 服务商 × 模型 分桶。只统计用量，不做费用计算。
 
-## 它统计什么
+## Overview
 
-每次模型调用的四类 token：**输入（未命中）/ 输出 / 缓存命中 / 缓存写入**，以及四者之和「总量」，
-按 **天 × 服务商 × 模型** 分桶，落在本地 SQLite 账本里。
+**解决什么：** DSH 本身不保留跨会话的用量视图，会话一删历史消耗就查不到。本插件把每次模型调用记进一个独立账本，删会话、清会话日志都不影响已记账的数据。
 
-## 数据来源（两路实时 + 一路回溯）
+**适合谁：** 想按天或按模型核对 token 消耗，并且需要把「主对话」与「DSH 内部调用（压缩、摘要、标题生成）」分开看的人。
 
-| 来源 | 覆盖 | 落库 kind |
-| --- | --- | --- |
-| `session/event` → `assistant/message.usage` | 主对话的每次模型调用（权威、幂等、带 seq） | `chat` |
-| `llm/stream`（仅 `purpose` 非空） | 压缩、摘要、标题生成等 **DSH 内部调用** | `internal` |
-| 启动回溯：`sessionPersistence` 逐个读历史会话 | 插件安装之前的全部对话调用 | `chat` |
+**不适合：** 要算钱（这里只有 token，不乘单价）；要跨机器汇总（账本是单机 `$DSH_HOME` 下的一个文件）；TUI / headless（没有 Web 的 slot 可挂）。
 
-- 内部调用不写进会话日志，**只能实时捕获**，所以 `internal` 自插件安装之日起才有数据。
-- 对话调用可用 `sessionPersistence` 服务回溯补齐历史（增量，按 `revision` + `next_seq` 水位）。
-- 两路使用同一主键 `(session_id, record_key)`，`INSERT OR IGNORE` 天然去重，不会双计。
+## Compatibility
 
-## 存储
+| 项 | 声明 |
+|---|---|
+| DSH 形态 | Web GUI profile（`dsh web` / `--profile web`） |
+| 运行环境 | Node.js ≥ 22.5（依赖内置 `node:sqlite`）；Web 端需要会话视图提供 `conversation.view` 扩展点 |
+| 宿主服务 | `sessionPersistence`、`webServer`，以及 `session/event`、`llm/stream` 事件 |
+| 最后本机验证 | 2026-09-12，Windows，DSH mainline 本机构建 + web profile：tab 正常渲染、账本落库、按天 / 按模型聚合正确 |
+| 未声称 | 未做跨平台与跨 DSH 版本矩阵；DSH mainline 的 DOM / class 漂移可能影响前端表格样式 |
 
-`$DSH_HOME/storages/usage-stats/usage.db`（默认 `~/.dsh/storages/usage-stats/usage.db`），`node:sqlite` 内置零依赖，WAL 模式。
+## Install / Uninstall
 
-**账本是权威事实源，不是会话日志的索引**——删除会话（或会话日志被清理）不会影响已记账的数据。
+从 npm 安装：
 
-## 界面
+```sh
+dsh plugin --profile web add @lengduan/dsh-usage-stats
+```
 
-在会话视图顶部新增「用量统计」tab：时间范围（今日 / 本周 / 上周 / 全部 / 指定日期）、
-口径切换（对话 / 内部 / 全部），表格按服务商分组列出各模型的输入 / 输出 / 缓存命中 / 缓存读写 / 总量。
+升级：
 
-## 安装
+```sh
+dsh plugin --profile web update @lengduan/dsh-usage-stats
+```
 
-从 npm 装（已发布包）：
+**禁用（不删依赖，账本保留）**：在 web profile 的 `cordis.patch.yml` 里把该行覆盖为 `disabled: true`：
+
+```yaml
+- id: usage-stats
+  disabled: true
+```
+
+**彻底移除**：
 
 ```sh
-dsh plugin --profile web add @lengduan/dsh-usage-stats
+dsh plugin --profile web remove @lengduan/dsh-usage-stats
 ```
 
-从源码装（本地开发调试）：
+移除不会删除账本。要清空历史，手动删 `$DSH_HOME/storages/usage-stats/`（默认 `~/.dsh/storages/usage-stats/`），该操作不可恢复。
+
+装完或改完 patch 都需要重启 `dsh web`。
+
+从源码安装（开发调试）：
 
 ```sh
 git clone https://github.com/lengduan/dsh-usage-stats
@@ -46,4 +59,83 @@ cd dsh-usage-stats
 dsh plugin --profile web add .
 ```
 
-装完需要重启 dsh web 服务。
+## Quick start
+
+1. 安装并重启 `dsh web`，打开任意一个已有对话的会话。
+2. 会话视图顶部出现「用量统计」tab，切过去；默认是「今日 · 全部口径」的表格。
+3. 用时间范围（今日 / 本周 / 上周 / 全部 / 指定日期）和口径（全部 / 对话 / 内部）筛选；点服务商行可折叠其下的模型明细，点「刷新」重新取数。
+
+最小验收：在任意会话发一句话触发一次模型调用，回到「用量统计」tab 点「刷新」，当天应出现该次调用的记录（输入 / 输出 / 缓存命中 / 缓存读写 / 总量）。
+
+## Configuration
+
+无配置项、无环境变量、无密钥。
+
+唯一的隐式输入是 `DSH_HOME`（决定账本目录），沿用 DSH 自身取值。外观与表结构写死在 `lib/client.js` 里。
+
+## Permissions & data
+
+| 面 | 行为 |
+|---|---|
+| 网络 | 无出网请求。前端只 POST 本机 `/usage/api` |
+| 文件系统 | 只读写 `$DSH_HOME/storages/usage-stats/usage.db`（含 WAL 伴生文件）；回溯历史时经 `sessionPersistence` 服务读会话日志 |
+| 凭据 / 会话内容 | 不读 token、密钥、消息正文；只取用量数字与 session id、provider、model、时间、purpose |
+| 宿主服务 | 订阅 `session/event` 与 `llm/stream`，注册 `/usage/api`，注入 `sessionPersistence` / `webServer` |
+| 数据去向 | 全部留在本机账本，不外发、不写第三方 |
+
+**统计口径**：输入（未命中）/ 输出 / 缓存命中 / 缓存写入 / 总量；provider 给出 `totalTokens` 时优先采用，否则四类相加。
+
+**三路数据来源**：
+
+| 来源 | 覆盖 | kind |
+|---|---|---|
+| `session/event` → `assistant/message.usage` | 主对话的每次模型调用（权威、幂等、带 seq） | `chat` |
+| `llm/stream`（仅 `purpose` 非空） | 压缩、摘要、标题生成等 DSH 内部调用 | `internal` |
+| 启动回溯：`sessionPersistence` 逐个读历史会话 | 插件安装之前的对话调用 | `chat` |
+
+内部调用不写进会话日志，**只能实时捕获**，所以 `internal` 自插件安装之日起才有数据。回溯是增量的，按 `revision` + `next_seq` 水位推进；两路共用主键 `(session_id, record_key)`，`INSERT OR IGNORE` 天然去重，不会双计。
+
+**账本是权威事实源，不是会话日志的索引** —— 删会话或清理会话日志都不会改变已记账的数据。
+
+## Troubleshooting
+
+| 现象 | 处理 |
+|---|---|
+| 会话顶部没有「用量统计」tab | 确认装的是 **web** profile 且已重启 `dsh web`；看浏览器控制台是否报 `client-modules: bundle … loaded without registering "<包名>"` —— 这类报错说明 client bundle 注册的 id 与包名不一致 |
+| tab 在，但一直「暂无记录」 | 先发一次消息触发调用；选「内部」口径时需要插件已运行过内部调用才有数据 |
+| 数字比预期少 | 检查口径是否停在「对话」；历史回溯只在插件启动时跑一次，装完请重启 |
+| 启动报 SQLite / 权限错误 | 确认 `$DSH_HOME/storages/usage-stats/` 可写；目录被占用或磁盘满会让账本打不开，此时接口返回 `账本不可用` |
+| 用量页里的按钮点不动 | 对话区两侧的宽度把手（40px 的 col-resize 条）会压在本页上抢走 pointerdown；本插件在用量页挂载期间会隐藏这两个把手，若仍复现请提 issue |
+| 卸载后 tab 还在 | 硬刷新页面；确认 profile 的 `dsh.profile.bundles` 已不再列出该包 |
+
+日志：`dsh web` 的终端输出（插件只经 `ctx.logger.warn` 输出告警）+ 浏览器控制台。插件不写独立日志文件。
+
+回滚：`dsh plugin --profile web remove @lengduan/dsh-usage-stats` 后重启；账本文件可先行备份。
+
+## Development
+
+```sh
+git clone https://github.com/lengduan/dsh-usage-stats
+cd dsh-usage-stats
+node scripts/verify.mjs          # 装载前自检
+dsh plugin --profile web add .   # 以本仓目录联调
+```
+
+无构建步骤，`lib/` 就是发布产物：
+
+| 文件 | 角色 |
+|---|---|
+| `lib/index.js` | host 半：账本、订阅、`/usage/api` |
+| `lib/client.js` | 浏览器 bundle：`conversation.view` 的「用量统计」tab |
+| `cordis.patch.yml` | bundle 层，按**包名**插入插件行 |
+| `scripts/verify.mjs` | 自检：host 半可 import 并导出 `inject`/`apply`；client 半的 `factory` 返回模块对象、bundle id 与 package.json 的 `name` 一致、确实注册到 `conversation.view` |
+
+改完 host 半需重启 `dsh web`，只改 client 半刷新页面即可。提交前请跑 `node scripts/verify.mjs`，它是 CI 之外唯一的门禁。
+
+贡献：最小 diff。Issue / PR 请写清 DSH 版本或 mainline commit、本插件 commit、操作系统。
+
+## License & security
+
+- 许可证：[MIT](LICENSE)
+- 安全问题：不要在公开 issue 里贴密钥或会话内容。请用 GitHub 的 Private vulnerability reporting（若已开启），或只描述复现步骤的私密渠道联系维护者。
+- 本插件不处理任何凭据；若发现发布产物里出现外链或凭证，视为供应链问题，按上面的私密渠道反馈。

package/lib/client.js

@@ -6,7 +6,7 @@
  * 列结构与 PI 的用量统计报表保持一致（总量 = 四类之和）。
  */
 window.__ModuleLoader__.load({
-  id: "dsh-usage-stats",
+  id: "@lengduan/dsh-usage-stats",
   factory: (require) => {
     const module = { exports: {} };
     const exports = module.exports;
@@ -27,6 +27,7 @@ window.__ModuleLoader__.load({
       "总 Token": "Total tokens",
       "内部调用自插件安装之日起统计，无法回溯历史": "Internal calls are counted from install time; history cannot be backfilled",
       "账本": "Ledger", "条记录": "records", "会话": "sessions",
+      "仅统计当前 DSH 实例（本 home）；同一账号在其他实例（独立 DSH_HOME）的消耗不在此列。": "Counts this DSH instance (current home) only; usage under the same account in other instances (separate DSH_HOME) is not included.",
     };
     let LANG = (() => {
       try { return String(navigator.language || "en").toLowerCase().startsWith("zh") ? "zh" : "en"; } catch (e) { return "zh"; }
@@ -67,11 +68,14 @@ window.__ModuleLoader__.load({
     // pointerdown。抬本页层级能盖住把手，但底部输入框只有 z-index 7，本页反
     // 而会压住输入框；因此改为在用量页挂载期间隐藏把手——切回对话 tab 时本页
     // 卸载，body:has 失配，把手自动恢复。
-    if (typeof document !== "undefined" && !document.getElementById("dsh-usage-stats-handle-fix")) {
+    /** 注入把手隐藏样式；随 ctx.effect 在插件卸载时撤回。 */
+    function avoidWidthHandles(ctx) {
+      if (typeof document === "undefined") return;
       const style = document.createElement("style");
-      style.id = "dsh-usage-stats-handle-fix";
+      style.dataset.usageStatsStyle = "width-handle-fix";
       style.textContent = "body:has([data-usage-stats]) [data-width-handle]{display:none}";
       document.head.append(style);
+      ctx.effect(() => () => { style.remove() });
     }
 
     // ── 工具 ──────────────────────────────────────────────────────────────
@@ -222,6 +226,8 @@ window.__ModuleLoader__.load({
           ? el("div", { style: st.hint }, t("内部调用自插件安装之日起统计，无法回溯历史"))
           : null,
 
+        el("div", { style: st.hint }, t("仅统计当前 DSH 实例（本 home）；同一账号在其他实例（独立 DSH_HOME）的消耗不在此列。")),
+
         state.error
           ? el("div", { style: st.err }, state.error)
           : null,
@@ -238,6 +244,8 @@ window.__ModuleLoader__.load({
     const inject = ["slots"];
 
     function apply(ctx) {
+      avoidWidthHandles(ctx);
+
       const slots = ctx.get("slots");
       if (slots === undefined) return;
 

package/lib/index.js

@@ -268,9 +268,9 @@ function resolveRange(range, dateArg) {
   return { from: today, to: today, label: `今日 ${today}` }
 }
 
-export default {
-  inject: ['sessionPersistence', 'webServer'],
-  apply(ctx) {
+export const inject = ['sessionPersistence', 'webServer']
+
+export function apply(ctx) {
     const warn = (message) => { try { ctx.logger?.warn?.(`[dsh-usage-stats] ${message}`) } catch (e) { /* 日志不可用则静默 */ } }
 
     let ledger = null
@@ -473,5 +473,4 @@ export default {
     }
 
     ctx.effect(() => () => { ledger?.close() }, 'dsh-usage-stats: 关闭账本')
-  },
 }

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@lengduan/dsh-usage-stats",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "DSH 用量统计插件：SQLite 本地账本，按天 / 按模型统计输入、输出、缓存命中、总计；区分对话调用与内部调用，只统计用量不做费用计算。",
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "dsh",
+    "usage-stats",
+    "token-usage",
+    "sqlite"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",

package/scripts/verify.mjs

@@ -24,13 +24,17 @@ function check(label, ok, detail = '') {
 
 // ── 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')
+const hostModule = await import(pathToFileURL(path.join(root, 'lib', 'index.js')).href)
+// 官方 bundle 用 named export（export const inject / export function apply），
+// default 对象形式也受支持；两种形状都接受，避免自检锁死其中一种。
+const host = hostModule.default ?? hostModule
+check('可 import 且导出插件', !!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 pkgName = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).name
 const code = fs.readFileSync(path.join(root, 'lib', 'client.js'), 'utf8')
 let definition = null
 const sandbox = {
@@ -44,7 +48,7 @@ try {
   check('脚本可执行', false, String(error?.message ?? error))
 }
 check('调用 __ModuleLoader__.load 注册了模块', !!definition)
-check('id 与包名一致', definition?.id === 'dsh-usage-stats', String(definition?.id))
+check('bundle id 与包名一致（宿主按包名校验注册）', definition?.id === pkgName, `${String(definition?.id)} vs ${pkgName}`)
 
 const React = {
   createElement: () => null,