前言¶
DeepSeek Harness (DSH) 的核心理念是「一切皆插件」。在使用 DSH 进行开发或调试时，追踪 token 消耗是常见的刚需。dsh-token-heatmap 提供了一种直观的监控方式，通过 GitHub 风格的贡献图展示用量。
插件简介¶
这是一个可拖动的浮动窗口，用于显示 DeepSeek Harness 的 token 用量。它基于本地会话日志进行统计，没有网络请求和遥测行为。由 cccchensy 开发，采用 MIT 许可证。
核心功能¶
- GitHub 风格热力图：顶部显示今日总量，下方显示最近 30 天的用量。
- 年度面板：悬停时会展开年度面板，包含总量、活跃天数、日均、当前与最长连续天数、最佳单日，以及每日的输入/缓存/输出拆分。
- 可拖动窗口：支持拖动到任意位置，位置会被记住。
- 运行状态指示：有会话在运行时，窗口会缓慢闪烁。
- 本地统计：直接读取会话日志，无网络请求，支持统计 subagent（可配置）。
安装与启用¶
在任意会话中，向 agent 发送以下命令即可安装：
github:cccchensy/dsh-token-heatmap
插件按 profile 生效，安装后重启 DSH 即可加载。卸载和更新插件需在 Plugins 页面操作，更新后必须重启 DSH。
使用说明¶
- 拖动：按住窗口任意位置可拖动到屏幕其他位置。
- 查看详情：鼠标悬停可展开年度面板，查看详细的输入、缓存和输出数据。
- 折叠：双击窗口可将其折叠成只剩标题行。
- 状态闪烁：当有会话在运行时，窗口会缓慢亮灭，表示有活动，而非此刻正在消耗 token。
局限与注意¶
由于插件基于日志读取，存在以下口径差异和限制：
* 统计口径：数字准确到最后一个已提交的 step，而不是最后一个生成的 token。
* 官方对齐：口径与官网用量页一致，但会低 0.25%。这源于重试失败的请求，官方计入服务端已处理的 prompt，而 Harness 不把失败尝试的用量写进日志。
* 数据范围：无法获取服务端已处理但失败的 prompt。
* 去重机制：同一份会话历史被复制进多个日志时（如 subagent 快照、fork）只算一次，按指纹去重。
* 压缩摘要：压缩摘要本身是一次计费调用，已计入统计。
* 闪烁含义：闪烁表示「有会话在运行」，而非「此刻正在消耗 token」。
* 权限与更新：插件以当前 dsh 进程权限运行。更新插件后必须重启 DSH。
结语¶
dsh-token-heatmap 是一个轻量级的本地监控工具，适合需要直观追踪 token 消耗的开发者。其 GitHub 风格的界面降低了认知负担，且完全本地化运行。更多详情请查看 插件目录 或 GitHub 仓库。
