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

dsh-plugin-token-usage

QwenPaw 风格的 跨会话 token 用量统计，用于 DSH。

插件把每次模型调用上报的 token 用量汇总成 (date, provider, model) 分桶，覆盖所有已持久化的会话（包括子代理会话），并通过单个 /usage 命令对外提供。

- 零运行时依赖 —— 只用 Cordis ctx API 和 Node 22 内置的 node:zlib（zstd）。
- 可靠的真相来源 —— 读取 ~/.dsh/sessions 下的会话日志，因此对插件出现之前的历史同样有效，写入时也无需单独记账。
- 不重复计数 —— 已提交的 assistant/message.usage 优先；某一步从未产出消息（失败）时，回退到它最后一段流式 usage 分片，在 turn/end 时刷出。按文件持久化的水位线（{hiSeq, framesIngested}）让增量扫描在重启和崩溃恢复后的重新编码中保持幂等。

命令

/usage # last 30 days (configurable defaultDays)
/usage 7d # last 7 days
/usage 7d qwen3.8 # last 7 days, model filter (substring on provider/model)
/usage qwen3.6 # default range, model filter

输出示例：

📊 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 | 记录回填进度。 |

挂载

插件是树外模块，通过配置档补丁挂载（与 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 单元测试 + harness 测试。

开发

npm install # installs the cordis peer for the harness test
npm test # node --test test/.test.mjs
npm run prepare # sync lib/ from src/