前言¶
用 DeepSeek Harness（DSH）做智能体或日常对话时，Token 消耗分散在大量会话里，设置页本身也不会直接给出「按天汇总」的视图。若只靠印象或零散日志，很难判断某一天用量是否异常、缓存读取是否占了大头，更谈不上对照官方价目做粗略花费估算。
下面介绍的 dsh-token-heatmap 由维护者 Seren-715 发布，分类为客户端插件：在 DSH 设置中增加「Token 用量」一节，用热力图按日展示本机会话日志聚合结果，并在选中日期后给出按 DeepSeek 公布价目与峰谷时段计算的人民币估算金额。数据全部来自本机 <DSH_HOME>/sessions 下的会话日志，不发起外部网络请求，也不维护单独的用量账本。
这是什么¶
一句话定位：DSH 设置页内的每日 Token 用量热力图，含 CNY 估算消费；聚合完全基于本地 session 日志。
- 目录页：skillhub.cn/plugins/Seren-715/dsh-token-heatmap
- 源码与文档：github.com/Seren-715/dsh-token-heatmap
- 当前资料中的版本：v0.5.1（MIT 许可证）
- 实现方式：组件注册到
settings.section槽位，与内置设置项并列显示，而非覆盖全屏浮层
DSH 生态强调「一切皆插件」；SkillHub 等社区目录由社区维护，与 DeepSeek / 幻方无官方从属关系，安装来源以目录页与仓库 README 为准。
核心功能¶
热力图与统计口径¶
打开 设置 → Token 用量 后，默认展示近半年（26 周），可切换到近一年（上下两排，27 + 26 周）。支持 每天 / 每周 视图，以及四种灰阶指标：
- 总量
- 输入+输出（不含缓存读，便于看清「真实推理」占比）
- 缓存读
- 输出
色阶按本机数据的分位数（25/50/75 百分位）划分，而不是固定阈值，避免总量与「输入+输出」量级差过大时整图发灰或失真。无用量记录的日期固定在最低视觉层级，有记录的日期更易辨认。
悬停或聚焦格子时显示日期、当前口径的 Token 数与「点击查看详情」；选择日期后，详情在热力图下方就地展开，包含总量、输入、输出、缓存读、调用次数、非零时的缓存写入，以及 Token 构成条与各分项占比。
金额估算（非账单）¶
会话日志只记录 Token 数量，不含货币字段。插件在详情中按 DeepSeek 官方人民币价目 对每条记录的时间戳判定峰谷（工作日 09:00–12:00、14:00–18:00 为高峰等规则，见仓库 lib/pricing.js），再汇总为当日估算金额，并在界面标明为估算。未知模型回退到 Flash 价目并标注。英文界面金额前写 CNY，不做汇率换算。
数据来源与解析¶
日志路径形如：
<DSH_HOME>/sessions/<项目>/<会话>/session.v*.jsonl.zstd
插件读取带有效时间戳和 data.usage 的记录（含 inputTokens、outputTokens、cacheReadTokens、cacheWriteTokens、totalTokens 等），按配置的时区切日聚合。实现上显式处理：多帧 zstd 拼接、重复 seq 去重、写入中的截断尾帧跳过等，避免单次解压只读第一帧导致统计偏低。
隐私与集成¶
仓库说明：不发起任何外部请求；日志仅本机读取，聚合结果仅服务于本机 DSH 页面。颜色使用宿主主题 token（--dsw-alias-*），文案通过 ctx.locale.register 注册，切换宿主语言后本节会重渲染，数字单位随语言（中文 万/亿，英文 K/M/B）。
安装与启用¶
桌面应用的 profile 由应用独占管理，命令行 dsh plugin 无法修改该 profile，因此需在 DSH 应用内安装：
- 打开 DSH → 侧栏 插件 → 添加插件
- 填入本插件目录的绝对路径（命令行等价形式为
dsh plugin add "link:<路径>"，路径以你本机为准） - 安装后重启应用
- 进入 设置，导航中会出现 Token 用量
卸载：同一插件页面的组合包卡片 → 卸载。
插件以当前 DSH 进程权限运行，安装前应阅读仓库源码与 MIT 许可证，确认可接受其读取 sessions 目录的行为。
典型用法¶
日常查看用量可按下面步骤操作：
- 重启后打开 设置 → Token 用量，先确认默认近半年范围是否符合需要。
- 在顶部切换 总量 / 输入+输出 / 缓存读 / 输出，观察哪类 Token 主导色阶。
- 将视图切到 每周 时，可看自然周（周日–周六）的合并色阶与周计数标注。
- 点击某一天格子，在下方查看分项与构成条，并阅读当日 人民币估算金额（估算非账单）。
- 再次点击同一日期可收起详情正文但保留选中外圈；换日期时详情直接切换；焦点在格子上时
Esc先收起详情，再按一次取消选中。
可选配置写在 bundle 的 config 中（不填则用默认值）：
| 键 | 默认 | 说明 |
|---|---|---|
timeZone |
Asia/Shanghai |
按哪个时区切「一天」 |
sessionsRoot |
<DSH_HOME>/sessions |
会话日志根目录 |
maxDepth |
2 |
目录遍历深度（项目 / 会话两层） |
开发者自测（在克隆或下载的源码目录内，需 Node.js ≥ 24）：
npm ci
npm run check
npm test
npm run test:logs
npm run test:logs 会读取本机日志；可通过环境变量 DSH_SESSIONS_ROOT 指定路径。
适用场景与注意¶
适合谁：
- 长期在 DSH 上跑多项目、多会话，希望用日历视图回顾 Token 习惯的用户。
- 需要区分「缓存读主导」与「输入+输出」、并对照官方价目做粗算成本的人（仍以服务商账单为准）。
- 希望用量统计留在本机、不依赖第三方统计服务的场景。
需要注意：
- 金额为插件按价目表与峰谷规则计算的估算；DeepSeek 调价或节假日安排变化后，需关注仓库
lib/pricing.js是否更新。 - 热力图与截图示例中的具体数字仅作界面说明，你的数据完全来自本机日志。
- 安装即授予插件读取
sessionsRoot下日志的能力，请从 GitHub 核对版本与变更（如 CHANGELOG.md）。
结尾¶
dsh-token-heatmap 把 DSH 已有的会话日志变成设置页里的每日热力图，并在本地完成聚合与人民币估算，全程无外连。若你正在社区目录里挑选客户端侧的可视化插件，可从目录页了解简介，并在 GitHub 查看设计与数据来源细节：
- 目录页：https://www.skillhub.cn/plugins/Seren-715/dsh-token-heatmap
- GitHub：https://github.com/Seren-715/dsh-token-heatmap
