跨会话用量统计lovedheart/dsh-plugin-token-usage

dsh-plugin-token-usage

面向 DSH 的 QwenPaw 风格跨会话 token 用量统计。

该插件将所有已持久化会话（包括子代理会话）中每次模型调用由提供商报告的 token 用量，聚合到 (date, provider, model) 分桶中，并通过单个 /usage 命令对外提供。

- 零运行时依赖 —— 仅使用 Cordis 的 ctx API 和 Node 22 内置的 node:zlib（zstd）。
- 持久可信的数据源 —— 它读取 ~/.dsh/sessions 下的会话日志，因此对早于该插件的历史记录同样有效，且写入时无需单独记账。
- 不重复计数 —— 已提交的 assistant/message.usage 优先；未产生消息的步骤（失败）回退到其最后一个流式 usage 块，并在 turn/end 时刷出。持久化的按文件水位线（{hiSeq, framesIngested}）使增量扫描在重启和崩溃恢复重编码后仍保持幂等。

命令

/usage                 # 最近 30 天（可通过 defaultDays 配置）
/usage 7d              # 最近 7 天
/usage 7d qwen3.8      # 最近 7 天，模型过滤（对 provider/model 做子串匹配）
/usage qwen3.6         # 默认范围，模型过滤

输出示例：

📊 Token Usage  2026-07-17 → 2026-08-16

Total: 906.9M tokens · 4954 calls
input 473.3M · output 3.4M · cache read 430.1M

By model:
sglang/Qwen3.8-27B  —  719.4M tokens · 3320 calls
in 337.7M · out 2.8M · cacheR 378.9M
sglang/Qwen3.6-27B  —  187.4M tokens · 1634 calls
in 135.6M · out 669900 · cacheR 51.2M

By day:
2026-08-13  42.6M tokens · 481 calls
2026-08-14  195.7M tokens · 1587 calls
2026-08-15  380.5M tokens · 1513 calls
2026-08-16  288.1M tokens · 1373 calls

Token 单位：>= 1,000,000（百万）显示为 1.2M，>= 1,000,000,000（十亿）显示为 1.5B，低于该值则为普通整数（保留一位小数，末尾 .0 省略）。

配置

| key | default | description |
|-----|---------|-------------|
| defaultDays | 30 | 裸 /usage 的回溯窗口。 |
| backfillIntervalSec | 30 | 增量回填各轮之间的秒数（保持状态文件热更新）。 |
| sessionsRoot | ~/.dsh/sessions | DSH 会话日志根目录（为空 = 从 DSH_HOME 自动推断）。 |
| stateFile | ~/.dsh/token-usage.json | 聚合状态 + 水位线。 |
| flushDelayMs | 5000 | 状态写入的防抖时间。 |
| enableCommand | true | 注册 /usage。 |
| verbose | false | 记录回填进度。 |

挂载

该插件是一个树外模块，通过 profile 补丁挂载（与 telegram / thinking-mode 插件相同的模式）。向 ~/.dsh/profiles/web/cordis.patch.yml 添加一行 insert：

- insert:
- id: token-usage
name: '/home/lovedheart/Documents/dsh-plugin-token-usage/lib/index.js'
config:
defaultDays: 30
backfillIntervalSec: 30
enableCommand: true
verbose: true

commands 是一个可选依赖（通过一个可选的子项使用
fiber），因此该插件也会在无命令的程序集中加载——它只是存储
而不注册交互式命令。

布局

- src/frames.js — zstd 帧扫描器（镜像 DSH 的 scanZstdFrames）。
- src/store.js  — 桶聚合、去重、持久化、summarize。
- src/backfill.js — 增量会话日志遍历 + listSessionFiles。
- src/render.js — fmtTokens、renderUsageReport、parseUsageArgs。
- src/index.js  — 插件入口（name/inject/Config/apply）。
- lib/          — 构建输出（npm run prepare 复制 src/.js）。
- test/         — node --test 单元测试 + 测试框架测试。

开发

npm install        # 为测试框架测试安装 cordis peer
npm test           # node --test test/.test.mjs
npm run prepare    # 从 src/ 同步 lib/