前言¶

用 DSH 做日常任务时，token 花在哪里并不直观。会话日志里虽然带着每次模型调用 provider 上报的用量，但数据分散在所有持久化会话中——包括 subagent 会话。想知道「最近 7 天某个模型用了多少」，只能手工翻日志或临时写脚本聚合，插件安装之前的历史数据更是难以覆盖。

dsh-plugin-token-usage 把这件事做成了插件：按 (date, provider, model) 分桶聚合，一条 /usage 命令出报表，Web GUI 侧也有对应面板。下面介绍它的定位、设计与用法。

这是什么¶

dsh-plugin-token-usage 由 lovedheart 维护，定位是「QwenPaw 风格的 DSH 跨会话 token 用量统计」：把所有持久化会话（含 subagent 会话）中每次模型调用的 provider 上报用量，聚合到 (date, provider, model) 桶里，通过 /usage 命令与 Web GUI 的 Token 用量面板展示。当前版本 0.2.0，许可证为 MIT。

核心设计¶

会话日志即事实来源¶

插件直接读取 ~/.dsh/sessions 下的会话日志作为持久事实来源。这意味着两点：

1、插件安装之前的历史数据也能统计；
2、写入侧不需要任何额外记账，正常使用 DSH 即可，聚合由插件增量扫描完成。

防重复计数与幂等¶

统计口径的处理规则如下：

1、已落盘的 assistant/message.usage 优先采用；
2、没有产生消息的失败步骤，回退到最后一个 streaming usage chunk（在 turn/end 时落盘）；
3、每个会话文件维护一个持久化水位（{hiSeq, framesIngested}），保证增量扫描在跨重启、崩溃恢复重编码的场景下依然幂等，不会重复累计。

零运行时依赖¶

运行时只使用 Cordis 的 ctx API 与 Node 22 内置的 node:zlib（zstd）。@deepseek-ai/cordis ^4.0.1 以 optional peer dependency 的形式声明。

安装与启用¶

README 没有提供官方安装命令。插件是 out-of-tree 模块，通过 profile patch 挂载，与 telegram、thinking-mode 插件是同一模式。步骤如下：

1、将 GitHub 仓库克隆到本地；
2、编辑 ~/.dsh/profiles/web/cordis.patch.yml，添加一段 insert 行：

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

name 指向仓库内 lib/index.js 的绝对路径，config 四项来自 README 示例，可按需调整。

另外一个细节：commands 是可选依赖（通过 optional child fiber 消费），因此插件在没有命令注册的程序集中也能加载——只是不注册交互命令，存储照常工作。

用法：/usage 命令¶

查询入口是单一命令 /usage，支持时间范围与模型过滤：

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

时间范围不写时取 defaultDays；过滤参数对 provider/model 字符串做子串匹配。

README 给出的示例输出，按总量、按模型、按天三段展示：

📊 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

数字以缩写展示：达到百万级显示 M（如 1.2M），达到十亿级显示 B（如 1.5B），以下为普通整数；统一保留一位小数，末尾 .0 去掉。

配置项¶

Web GUI 面板¶

package.json 提供 ./client 导出，dsh.client 字段声明 platform 为 web，并注入 @deepseek-ai/dsh-client-runtime 与 @deepseek-ai/dsh-client-locale，对应 Web GUI 中的 Token 用量面板。

开发与测试¶

代码结构：

• 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）
• test/ — 单元与 harness 测试

仓库自带的开发命令：

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

npm run prepare 会把 src/*.js 复制到 lib/。由于挂载路径指向 lib/index.js，修改源码后需要同步一次。

适用场景与注意事项¶

适合的场景：DSH 会话多、常跑 subagent，想按天、按模型看用量分布；或者想在统计口径里包含插件安装之前的历史数据。

使用前注意：

1、插件以当前 dsh 进程权限运行，可读写 sessionsRoot 与 stateFile 指向的路径（默认 ~/.dsh/sessions 与 ~/.dsh/token-usage.json），启用前确认目录权限符合预期；
2、安装前建议自行检查源码与许可证（当前为 MIT）；
3、统计对象是 provider 上报的用量，来自会话日志本身，不需要改动任何写路径配置。

结尾¶

dsh-plugin-token-usage 的思路很克制：不引入新依赖、不改动写路径，把会话日志当作唯一事实来源，做好去重与幂等，然后用一条 /usage 命令交付结果。如果你在 DSH 上有多会话用量的统计需求，它值得一看。

• GitHub：https://github.com/lovedheart/dsh-plugin-token-usage
• 社区目录收录页：https://www.skillhub.cn/plugins/lovedheart/dsh-plugin-token-usage

其中社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。