前言¶
用 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 。
