前言¶
用 DeepSeek Harness（下称 DSH）跑智能体的团队都会遇到同一个问题：每个会话都在产生 token 用量，但这些数字分散在各自的会话里。想知道这个月总共花了多少美元、哪几天是消耗高峰、deepseek-v4-flash 和其他 provider/model 各占多少，往往要逐个会话去看。
dsh-token-stats 把这件事做成一个设置面板：跨会话汇总 token 用量，按 provider 和模型拆分，画成月度堆叠成本图。它也是 DSH「一切皆插件」理念下的一个典型样本——整个功能以独立 bundle 提供，不需要改核心仓库一行代码。
下面介绍这个插件的定位、工作方式和安装步骤。
这是什么¶
dsh-token-stats 是 DeepSeek Harness 的一个插件，由 qiushui0901 维护，MIT 许可。一句话定位：为 DSH 提供跨会话的 token 用量统计面板，核心是一张按 provider 和模型拆分的月度堆叠成本图（USD）。
版本为 0.1.0，依赖 zod ^3.23.8，可选 peerDependency react ^18.2.0，devDependencies 含 esbuild ^0.24.0 与 @types/react ^18.3.0。
核心功能¶
Overview 概览。 显示有用量记录的会话数、四个 provider 上报的 token 分桶（uncached input、cache read、cache write、output）、总计，以及按匹配价格表估算的成本拆分。
月度成本图。 按天、按模型的堆叠柱状图（USD），支持 < / > 月份导航、provider 与模型筛选，网格线刻度固定两位小数，配彩色图例。
按模型计价。 用量按精确的 provider/model 价格表匹配计价，内置一行 deepseek / deepseek-v4-flash，其余回退到默认价格表。本版本中价格是固定常量。
Data honesty。 缓存投影早于 per-model 单元的会话（或部署本身就缺少这些单元）会被记为 “no model data”，按默认价格表计价，并在界面上给出明确提示，不会静默混进按模型的统计里。
工作原理¶
bundle 分两半。
Host 半部（src/host/）注册两个会话投影单元：modelUsage（按 provider/model 的会话总量）和 modelDailyUsage（按 provider/model/UTC 日的单元格），沿用了 @deepseek-ai/dsh-token-meter 的模式。注册是幂等的——registry 会共享相同 stateVersion 的键，因此对已内置相同单元的部署（release 构建或源码 checkout）都是安全的。
Client 半部（src/client/）通过 settings.section 贡献一个「Token 用量」面板，读取 session.list 投影列展示数据（零日志加载），日单元格从 UTC 平移到本地时区显示。
安装与启用¶
前置条件：已安装 DeepSeek Harness（dsh CLI 或源码 checkout 均可）。
方式一：npm 安装。 README 将此方式标注为 once published，撰写本文时无法确认该包是否已在 npm 上架，如命令不可用请改用方式二：
dsh plugin --profile <name> add dsh-token-stats
dsh --profile <name> web
方式二：从仓库安装。 先克隆、构建，再把本地目录加入对应 profile：
git clone https://github.com/qiushui0901/dsh-token-stats.git
cd dsh-token-stats
npm install && npm run build
dsh plugin --profile <name> add ./dsh-token-stats
dsh --profile <name> web
方式三：从 DSH 源码 checkout 使用。 用 patch 文件直接挂载：
pnpm dsh web --patch /path/to/dsh-token-stats/cordis.patch.yml
使用此方式前，需要将 dsh-token-stats 链接进 checkout 的 node_modules，或安装到 checkout 启动时对应的 profile。
构建产物是 lib/host.js（自包含 Node 入口）和 lib/client.js（经 window.__ModuleLoader__.load 注册的浏览器 bundle）。
经过上面的步骤，启动后在浏览器打开 http://127.0.0.1:3080，进入 Settings → Token 用量 即可看到面板。
适用场景与注意¶
适合长期使用 DSH、需要按月复盘 token 成本、关注各模型消耗占比的开发者和团队。
几个使用前值得知道的限制：
1、模型数据向前填充。在 modelUsage / modelDailyUsage 投影存在之前运行的会话，在投影缓存行重写之前无法归属到具体模型，这部分用量按默认价格表计价。
2、按天分桶基于 UTC。host 在 UTC 日下归拢单元格，客户端按整日时区偏移平移显示，因此时区边界附近的日单元格可能落在相邻的本地日。
3、价格是编译进 bundle 的固定常量，UI 中没有编辑器。如果内置费率不符合你的情况，需要修改 src/client/usage-aggregate.ts 中的 DEFAULT_PRICES / DEFAULT_PRICE_TABLES 并重新构建。
最后提醒一点：插件以当前 dsh 进程的权限运行，安装任何第三方插件前都应检查其源码与许可证。dsh-token-stats 采用 MIT 许可，仓库地址见文末，可以自行审阅。
结尾¶
如果你的 DSH 部署缺一个按月、按模型看 token 成本的入口，dsh-token-stats 用不到一百行的安装流程就能补上，且不侵入核心仓库。
- 社区目录页：https://www.skillhub.cn/plugins/qiushui0901/dsh-token-stats
- GitHub 仓库：https://github.com/qiushui0901/dsh-token-stats
社区目录为独立站点，与 DeepSeek、幻方无官方从属关系；插件本身基于 MIT 许可的 DeepSeek Harness 插件系统构建。
