前言¶
长期用 DeepSeek Harness（DSH）跑对话时，Token 会分散在多份 session*.jsonl 里，界面本身未必给出「按天、按模型」的长期视图。若你想在本地 GUI 里看到一段时间内的用量趋势，而不把日志上传到外部服务，需要依赖 Host 侧从磁盘日志做汇总、再只供本机 loopback 访问的插件。
下面介绍维护者 savasana168 的 dsh-token-usage-heatmap（分类：模型推理）。它在 DSH 网页界面中增加 Token 总用量面板：26 周热力图、按模型柱状图，以及会话标题栏左侧的紧凑芯片；数据全部由本机 Host 从已有会话日志折叠计算，不向机器外发送。
这是什么¶
dsh-token-usage-heatmap 是面向 DSH Web GUI 的 bundle 插件（dsh.bundle + cordis.patch.yml），当前包版本为 0.2.1，许可证 MIT，要求 Node ≥ 22.15.0（或运行时 node:zlib 提供 zstdDecompressSync）。它不引入构建步骤和 npm 依赖，发布物为纯 JavaScript。
插件解决的问题：把 $DSH_HOME/sessions 下已有的明文 session*.jsonl 与多帧 session*.jsonl.zstd 读入，按日、按小时、按模型分桶，合并为 roll-up 后通过仅 loopback 可访问的 HTTP 路由提供给前端，用于热力图、柱状图和标题栏芯片展示。
核心功能¶
总览（Overview）页¶
- 26 周日历热力图：每天一格，四档蓝色深浅按当前范围内最忙的一天缩放；网格固定 26 列，仅在周日推进，避免随日期滚动而错位。
- 选定范围内的六个指标：总 Token、消息数、会话数、活跃天数、峰值小时、最常用模型。
- 与书籍 Token 量的对照文案：用知名书籍的 Token 数作参照，说明当前总用量相当于多少「本」。
模型（Models）页¶
- 按日堆叠柱状图，以及带会话数的 per-model 排名。
- 纵轴固定三档刻度（0、一半、峰值），峰值向上取整，柱形不会超出顶刻度。
时间范围¶
范围选项为 全部 / 30 天 / 7 天。「全部」指磁盘上所有有记录的天，不等于热力图绘制的 26 周窗口。柱状图在「全部」与「30 天」下使用 30 天窗口，「7 天」下使用 7 天窗口。
标题栏芯片与浮动面板¶
- Header chip：显示紧凑的 Token 总量，位于会话标题左侧；每分钟轮询一次，窗口聚焦时刷新，冷启动时会短暂重试，避免一直停在页面初次加载的值。
- 点击打开面板：芯片即入口；点击后在下方以浮动卡片展示完整面板。再次点击芯片、点面板 ×、点外部或按 Escape 可关闭。卡片经 React portal 挂在
document.body，不受 composer 的 flex 挤压；窗口较矮时仅卡片主体滚动。打开状态会在会话之间记住。
主题¶
浅色与深色各有一套不透明色阶；深色不是浅色加透明度，避免在深色卡片上读成黑块。
设置项¶
在 Settings → General 下增加三个开关（存于 Host 配置，对本配置档的所有窗口生效）：
| 开关 | 作用 |
|---|---|
| Show the usage chip in the header | 隐藏标题栏芯片（同时去掉面板唯一入口） |
| Open the panel from the chip on a new session | 关闭时，新会话页的芯片仍显示总量但不打开面板 |
| Open the panel from the chip inside a conversation | 关闭时，对话内芯片仍显示总量但不打开面板 |
安装与启用¶
DSH 桌面版由应用管理 profile，建议在应用内安装，不必用命令行。
应用内：Settings → Plugins，安装插件名 dsh-token-usage-heatmap。
从 GitHub 安装到指定 profile：
dsh plugin --profile <name> add github:savasana168/dsh-token-usage-heatmap
在未发布前从本地目录安装：
dsh plugin --profile <name> add "file:$PWD"
安装后需 重启 Host，新加载的 JavaScript bundle 才会生效。
插件以当前 DSH Host 进程权限读取会话目录与写缓存；安装前应自行查看仓库源码与 MIT 许可证，确认符合你的环境策略。
典型用法¶
- 安装并重启 Host 后打开 DSH Web GUI。
- 在会话标题栏左侧查看 Token 总量芯片；需要详情时点击芯片打开浮动面板。
- 在面板内切换 Overview / Models，并用 全部 / 30 天 / 7 天 切换统计范围。
- 若只想保留数字、不想误触打开面板，到 Settings → General 关闭对应「从新会话/对话内芯片打开面板」开关；若完全不需要入口，可关闭「Show the usage chip in the header」。
数据不会离开本机：汇总由 Host 从本地 session 日志计算，路由 /token-usage-heatmap/usage 要求 loopback 的 Host、拒绝 sec-fetch-site: cross-site，且 Origin 须与 Host 一致，外部网页无法读取完整 Token 历史。
工作原理（简要）¶
lib/fold.js：读取$DSH_HOME/sessions下的日志并折叠到按日、按小时、按模型桶。lib/usage.js：合并会话并缓存到$DSH_HOME/cache/token-usage-heatmap/usage.<pid>.json，热启动避免重读全部日志。lib/index.js：注册精确路由/token-usage-heatmap/usage，返回 JSON。lib/client.js：在conversation.header.leading渲染芯片与面板，在settings.general.item注册上述开关；面板使用 popper + portal 到document.body。
若 Node 版本低于 22.15 且不支持 zstdDecompressSync，插件仍可加载并提供路由，但会跳过 .jsonl.zstd，仅统计明文 .jsonl。
适用场景与注意¶
适合：经常在 DSH Web 界面里工作、希望用本地日志观察 Token 习惯（按天热力、按模型分布、峰值时段）的开发者；强调隐私、不希望用量统计依赖第三方云端时也可使用。
注意：
- 需要能提供 Web GUI 且向插件暴露
webServer的 DSH Host。 - 统计范围受磁盘上实际保留的 session 文件限制；压缩日志依赖较新的 Node/runtime。
- 社区目录 SkillHub 插件页 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系；DSH 生态一贯是「一切皆插件」，本插件是其中一类模型用量可视化扩展。
结尾¶
dsh-token-usage-heatmap 把已有会话日志收成面板里的 26 周热力图、模型柱状图和标题栏芯片，全程本地计算、loopback 服务。查阅说明与 issue 见仓库 GitHub：savasana168/dsh-token-usage-heatmap；目录索引见 SkillHub。
