前言¶
在 DeepSeek Harness（DSH）里跑多模型、多会话时，宿主本身没有现成的「按模型、按天」Token 台账。若只靠肉眼翻会话日志，很难回答「这周哪个模型吃掉了多少 Token」「有没有连续高消耗日」这类问题。社区插件 @zhangyongshuai56-hub/dsh-token-usage（仓库 zhangyongshuai56-hub/dsh-token-usage）从本地会话文件聚合用量，在设置里提供趋势图与日历热力图，把统计留在本机完成。
这是什么¶
维护者为 zhangyongshuai56-hub，分类属于模型推理。插件一句话定位：统计 DSH 每天消耗的 Tokens，按模型分系列展示趋势与日历热力图。npm 包名为 @zhangyongshuai56-hub/dsh-token-usage（因 dsh-token-usage 已被他人占用而加了 scope）。当前 package.json 版本为 0.1.0，许可证 MIT；要求 DSH >=0.2.0-rc.1、Node >=22.19.0。
数据从哪来¶
DSH 在每条模型响应里，会把用量写入会话文件的 assistant/message 事件，例如：
{"type":"assistant/message","time":1791555004268,
"data":{"usage":{"inputTokens":7636,"outputTokens":505,
"cacheReadTokens":0,"cacheWriteTokens":0,"totalTokens":8141}}}
模型归属来自同一会话的 request/header（config.provider / config.model），日期按本地时区归日。宿主侧扫描路径为 ~/.dsh/sessions/**/session.v4.jsonl.zstd：文件为 zstd 多帧，每帧独立解压后拼接，再聚合出「天 × 模型」用量表。README 注明一次全量扫描约 0.7 秒（40 个会话文件 / 38 MB），因此不能压在用户点开面板的那一次请求上。
加载与性能¶
面板需要「点开即出数」，插件在服务端采用 stale-while-revalidate 与增量扫描两层策略。
先做后台预热：插件装载时预热快照，用户第一次打开设置里的面板时通常已有数据。快照 TTL 为 30 秒；过期时接口先返回旧数据，同时在后台重扫，响应头 x-token-usage-stale: 1 表示当前是旧快照。后台扫描异步进行，每处理几个文件就让出事件循环，避免卡住宿主。
会话文件追加写入，历史聚合结果不变。插件按文件记录「消费到第几个字节 + 截至该处的聚合」，再次扫描只解压新增帧。README 给出的对比（全量 vs 增量）如下：冷扫描约 735 ms；稳态文件未变时增量约 1–2 ms；当前会话又写几条时增量约 3 ms。扫描前用正则挑出 assistant/message、request/header、request/context 等相关行，其余约 85% 行不进入 JSON.parse；预筛一行都没命中时退回逐行全解析，降低日志格式变化导致漏统计的风险。
浏览器端若收到 x-token-usage-stale: 1，约 1.2 秒后会自动再请求一次，用刷新后的数据替换，用户无需手动等待。
界面与能力¶
安装并在设置中打开 Token 用量 面板后，可见：
- 顶部五格 KPI：累计、峰值、日均、调用次数、当前连续天数。
- Token 活动：整年日历热力图，支持每日 / 每周 / 累计三种口径；色深表示消耗，悬停或点按可看当日各模型明细；可与表格视图（日期 / Token / 调用 / 强度）一键切换。
- 每日 Token 趋势图：连续日历轴，无记录日记 0，线不断；每模型一条系列，用量前五名单独展示，其余合并为「其他」。
- 模型排行：展示范围内全部模型，含序号列。
配色使用宿主 token（--dsw-alias-*），跟随 DSH 深浅主题。2026-11-01 的 UI/UX 审计修复了对比度、骨架屏、空态与数字格式等问题（详见仓库 README）。
安装与启用¶
从 GitHub 仓库地址安装；DSH 插件市场里也可直接搜包名。官方 README 给出的安装来源为：
https://github.com/zhangyongshuai56-hub/dsh-token-usage
安装完成后，在 DSH 设置 中打开 Token 用量 面板即可使用。本地开发可用 link: 协议软链，改源码后重启 DSH 生效；提交前可运行：
node --check lib/index.js && node --check lib/aggregate.js && node --check lib/client.js
HTTP 接口¶
需要对接或调试时，可调用：
GET /dsh-token-usage/usage
响应体形状为：
{
"days": { "YYYY-MM-DD": { "provider/model": { "total", "input", "output", "calls" } } },
"models": [],
"totalTokens": 0,
"totalCalls": 0,
"scannedAt": "",
"sessions": 0
}
响应头 x-token-usage-stale 为 0 或 1：1 表示返回的是旧快照，服务端正在后台重扫。
适用场景与注意¶
适合长期在 DSH 本机跑会话、希望按模型观察 Token 趋势与日历分布的开发者。数据完全来自本机 ~/.dsh/sessions 下的会话文件，不涉及远端上报；会话越多、文件越大，首次或冷扫描成本越高，但稳态下增量扫描保持在毫秒级。
DSH 生态是「一切皆插件」；社区目录站点与 DeepSeek / 幻方无官方从属关系，本文介绍的插件来自社区维护者，安装前请自行阅读仓库源码与 MIT 许可证。插件以当前 DSH 进程权限运行，会读取用户目录下的会话文件，安装前应确认来源可信。
结尾¶
dsh-token-usage 把分散在会话日志里的 assistant/message 用量聚合成「天 × 模型」视图，并用 stale-while-revalidate 与增量扫描保证面板可即时打开。目录页：https://www.skillhub.cn/plugins/zhangyongshuai56-hub/dsh-token-usage；源码与完整说明：https://github.com/zhangyongshuai56-hub/dsh-token-usage。
