前言¶

用 DeepSeek Harness（DSH）跑会话时，token 用量分散在各个会话日志里。想知道这个月每个模型各消耗了多少、哪几天用得最频繁，只能手动翻日志或自己写脚本统计，费时且容易算错。dsh-token-stats 是为 DSH Web UI 打造的 Token 消耗统计插件，它以会话日志为数据源，把用量聚合成按天、按模型的视图，直接显示在设置面板里。下面介绍它的功能、安装方式和工作原理。

这是什么¶

dsh-token-stats 由 MoonlitDropOfBlood 维护，遵循 MIT License。README 中声明：本项目是基于 DeepSeek Harness 构建的社区插件，并非 DeepSeek 官方产品。

它的定位很明确：不改会话流程，不解析请求头，直接把 DSH 会话日志作为唯一权威数据源，聚合出每个模型每天、每个统计区间的 token 用量。

核心功能¶

图表能力：

• 两个统计 Tab：近 7 天 / 近 30 天，两个区间都包含今天
• 堆叠柱状图：统计区间内每个模型每天的消耗，悬停查看具体数字
• 饼图：统计区间内每个模型的总消耗占比，图例带精确值和百分比
• GitHub 风格热力图：近一年每日活跃，天数随容器宽度自适应，最多显示 365 天（一年）
• 汇总卡片：区间总 Tokens / 输入(含缓存) / 输出

数据与体验：

• 本地持久化：聚合结果落盘 <DSH_HOME>/data/dsh-token-stats/stats.json，冷启动只扫描新会话、秒开
• 自动刷新：页面打开期间每 30s 刷新；历史回填期间每 2s 轮询进度
• 主题适配：全部使用 DSH 设计 token，明暗主题自动跟随
• 去重：按 session+seq 水位线去重，历史回填与实时监听合并后不重复计数

安装与启用¶

这是一个标准 DSH bundle：package.json 声明 dsh.bundle.patch，包内自带 cordis.patch.yml，用官方 dsh plugin 命令安装：

dsh plugin --profile web add https://github.com/MoonlitDropOfBlood/dsh-token-stats/releases/download/v1.2.0/dsh-token-stats-1.2.0.tgz

dsh plugin add 会把插件装成 profile 的 npm 依赖并追加到 dsh.profile.bundles，启动时 DSH 自动应用包内的 cordis.patch.yml 挂载插件。

本地开发时可以软链到本仓库，改代码即生效：

dsh plugin --profile web add /path/to/dsh-token-stats

重启 DSH 后，打开 Web UI 的设置（侧栏底部），左侧导航会出现 Token 统计页。

卸载：

dsh plugin --profile web remove dsh-token-stats

典型用法¶

1、打开 设置 → Token 统计。

2、在 近 7 天 / 近 30 天 两个 Tab 间切换：

• 柱状图展示区间内每天、每个模型的消耗（堆叠）
• 饼图展示区间内每个模型的总消耗占比
• 顶部卡片给出区间总 Tokens / 输入 / 输出

3、下方 每日活跃 热力图展示更长时间范围：格子越多 = 容器越宽，最多覆盖近一年。

如果想强制全量重扫历史数据，删除聚合文件即可，下次启动会重新扫描全部会话：

rm <DSH_HOME>/data/dsh-token-stats/stats.json

工作原理¶

数据采集分实时和历史两条路，合并后统一落盘：

• LIVE：插件启动后，监听 session/event 中的 assistant/message（usage）实时累计
• HISTORY：通过 sessionQuery.readSession() 回填历史，仅扫描从未回填过的会话
• DEDUP：按 session+seq 水位线去重，绝不重复计数
• PERSIST：聚合结果和水位线落盘 stats.json（防抖写盘 + 停止时 flush）

历史回填只统计插件启动前发生的调用，实时监听只统计启动后的，两者通过每个会话的事件序号水位线合并，不会重复。

聚合规则：

• 数据按本地日历天 × 模型（provider::model）聚合
• total = input + output + cacheRead + cacheWrite
• 模型信息来自 assistant/message 的 message.source（kind = ‘model’）

代码结构：

dsh-token-stats/
├── index.js            # Host 半：TokenStatsService（Remote 服务，采集 + 回填）
├── client.js           # Client 半：设置页「Token 统计」UI bundle
├── typert.host.js      # Typert Host manifest（tokenStats/getStats 描述）
├── cordis.patch.yml    # dsh bundle patch（挂载行）
├── AGENTS.md           # 面向 AI agent 的开发指南（含踩坑）
└── LICENSE             # MIT

依赖方面，peerDependencies 声明 @deepseek-ai/cordis ^4.0.1 和 @deepseek-ai/dsh-typert-protocol ^0.1.0-rc.7，运行时依赖 zod ^4.4.3。

适用场景与注意¶

适合两类人：

• 日常使用 DSH 的开发者，想了解每个模型的消耗分布和长期活跃趋势
• 想写 DSH 插件的开发者，AGENTS.md 记录了 DSH 正式插件（Host/Client/Typert 三件套）的完整机制和踩坑，可以作为参考

安装前注意：插件以当前 dsh 进程的权限运行，建议安装前检查源码与许可证。本项目为社区插件，并非 DeepSeek 官方产品。

小结¶

装好 dsh-token-stats 后，每个模型每天的 token 消耗、长期活跃趋势都能在 Web UI 里直接看到，不用再手动翻会话日志。仓库地址：https://github.com/MoonlitDropOfBlood/dsh-token-stats ，社区目录页：https://www.skillhub.cn/plugins/MoonlitDropOfBlood/dsh-token-stats 。