前言¶

用 DSH（DeepSeek Harness）跑智能体，token 是最直接的成本信号：某段时间用了多少、缓存读写了多少、哪个 provider 和 model 消耗最大，都需要一本能持久保存、随时查询的账。DSH 内置了 usage accumulator 和对应的用量页面，满足基本查看没有问题；但如果你想把服务商上报的四类用量分开记账、按本地日统计活动，或者在自己的插件里读取这些数据，就需要一个独立的统计组件。

下面介绍的 Mu-scorpio/token-usage-counter 就是这样一个插件。

这是什么¶

它的定位一句话：为 DeepSeek Harness 提供持久化的、服务商上报的 token 用量统计，支持累计、每日、按会话和按模型查看。

• 维护者：Mu-scorpio
• npm 包名：dsh-token-usage-counter，当前版本 0.4.0
• 许可证：MIT（README 与 package.json 均为 MIT）
• 兼容环境：Node.js 22.13.0 或更新版本；DSH 0.1.2-alpha.3 至 0.1.2-alpha.5；Profile：web

核心功能¶

插件提供的能力如下：

• 分桶统计：将服务商上报的未缓存输入、缓存读取、缓存写入、输出四类用量分开保存；
• 持久化总量：数据存储在插件专有的 dsh-token-usage-counter 设置命名空间；
• 多视图：提供全局、会话、provider/model 三类汇总；
• 每日活动：按本地日统计 token 总量与调用次数；
• 内置设置页：自带 Web 设置视图和热力图；
• 安全计数：仅在成功完成锚点（completion anchor）之后才计入用量；
• 交互命令：命令服务挂载时注册 /tokens；
• API：提供 ctx.tokenUsageCounter（getSummary / getSession / getModel / formatSummary）。

计数规则¶

统计是否可信取决于计数规则。插件监听持久化的会话事件流，规则如下：

1、assistant/message.usage 只计一次；
2、compaction/summary.usage 计为一次 provider 调用；
3、仅有 usage 的 assistant/chunk 会先暂存，等到匹配的 assistant/message 到达再入账；
4、chunk 与最终消息描述同一轮次和步骤时，以最终值替换早先的采样；
5、失败请求、重试与 fork seed 历史不会重复计数。

前两条决定入账粒度，后三条避免流式采样和重试带来的重复计数；再配合「仅在成功完成锚点之后才计入用量」的策略，统计口径是比较克制的。

安装与启用¶

先确认运行环境满足上面的兼容性要求，再把已发布的 Bundle 安装进 web profile：

dsh plugin --profile web add -w --config.auto-install-peers=false dsh-token-usage-counter
dsh web

第一条命令把 dsh-token-usage-counter 安装到 web profile，第二条启动 dsh web。经过上面的步骤，插件即可随 dsh web 一起运行。

需要注意，这个 Bundle 是增量式的：它只挂载插件自己的 token-usage-counter 条目，DSH 内置的 usage accumulator 和用量页面保持启用，二者并存。

升级注意¶

0.4.0 把持久化从共享的 usage-stats 命名空间迁移到插件专有的 dsh-token-usage-counter 命名空间。由于共享命名空间属于内置插件，0.3.x 的既有总量不会被静默迁移，升级后新计数器从一份独立快照开始。如果你还在用 0.3.x 且在意旧累计数据，升级前先确认这一点。

本地开发¶

如果要在本地改这个插件，先在仓库 checkout 内完成构建：

npm install --ignore-scripts --legacy-peer-deps --no-package-lock
npm run build
npm run verify

构建生成的 host 与 client bundle 提交在 lib 目录下。

调试时用下面的命令把源码叠加进 dsh web，不替换内置组件：

dsh web --patch ./cordis.yml

也可以手动组合，只添加插件自己的条目：

- insert:
    - id: token-usage-counter
      name: './src/index.ts'

典型用法¶

交互命令¶

命令服务挂载时，插件会注册 /tokens 命令，在会话中调用即可查看统计。

API¶

其他插件可以通过 ctx.tokenUsageCounter 读取数据：

ctx.tokenUsageCounter.getSummary()
ctx.tokenUsageCounter.getSession(sessionId)
ctx.tokenUsageCounter.getModel(provider, model)
ctx.tokenUsageCounter.formatSummary()

四个方法分别对应全局汇总、按 sessionId 查会话用量、按 provider 和 model 查模型用量，以及格式化后的摘要文本。

适用场景与注意¶

适合的场景：

• 需要按四类口径（未缓存输入、缓存读取、缓存写入、输出）核算成本；
• 需要按本地日回看 token 总量与调用次数，或借助设置页的热力图观察活动分布；
• 想在自己的插件里通过 ctx.tokenUsageCounter 消费用量数据做进一步处理。

使用前注意：

• 插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。本项目源码公开在 GitHub，许可证为 MIT；
• 逐版本验证结果与一次性 profile 证据记录在 docs/VERIFICATION.md，选择版本前可先查阅；
• 从 0.3.x 升级到 0.4.0 后旧总量不会自动迁移，处理方式见上文。

小结¶

token-usage-counter 做的事很专注：把服务商上报的四类 token 用量分开、持久化地记下来，并提供全局、每日、会话、模型四个视角查询，还能通过 API 被其他插件复用。如果你的 DSH 工作流需要一份可信的用量账本，可以用上面的命令直接安装试用。

• GitHub：https://github.com/Mu-scorpio/token-usage-counter
• npm：https://www.npmjs.com/package/dsh-token-usage-counter
• 社区目录页：https://www.skillhub.cn/plugins/Mu-scorpio/token-usage-counter （该目录为社区独立维护，与 DeepSeek / 幻方无官方从属关系）