前言¶
DSH 的理念是「一切皆插件」，Web 界面的能力可以由插件按需补充。但对 dsh web 的日常使用者来说，token 用量数据散落在各个会话的事件日志里，想回答「今天用了多少」「这个月累计用了多少」，并没有现成的入口。
下面介绍 @kidli1412/dsh-token-heatmap，一个 DSH Web GUI 插件：它在新会话屏幕的输入框下方渲染一张 GitHub 风格的每日 token 用量热力图，同一行给出今日 / 本月 / 累计三项统计，装完即用。
这是什么¶
一句话定位：在新会话屏幕输入框下方显示当前自然年（可选年份）的每日 token 用量热力图与用量统计。
插件由 KIDLi1412 维护，许可证为 MIT，当前版本 0.1.5。运行于 @deepseek-ai/dsh >= 0.1.2-alpha.4（0.1.2 版本线）。它解决的问题是：把会话日志里的 token 用量样本按天聚合，变成一张一眼能读懂的热力图。
核心功能¶
热力图卡片¶
安装后，新会话（hero）屏幕的输入框正下方出现统计卡。注意它只在新会话屏幕显示，已对话的会话不显示。
- 自然年视图：覆盖所选年份 1 月–12 月，通过『‹ 年份 ›』选择器切换年份，最多到当前年。
- 布局对齐 GitHub：列为周（周一起），行为星期，左侧标注一~日全部 7 天；今日之后的日期显示为空格。
配色与分档¶
- 六套配色：绿色 / 蓝色 / 橙色 / 红色 / 紫色 / 青色，在 设置 → 插件 → 插件配置 中切换，六个色板按钮即时预览。
- 颜色按绝对阈值分档：0 / <1M / 1M–10M / 10M–100M / ≥100M 共 5 级。图例悬停显示各档范围，格子悬停显示日期与精确 token 数。
统计行与刷新¶
- 统计行与标题同一行，显示今日 / 本月 / 累计，悬停显示完整数值。
- 每 5 分钟自动刷新，窗口重新可见时也会刷新，行尾可手动刷新。
配置项¶
插件配置卡（设置 → 插件 → 插件配置）提供『显示热力图』开关与配色方案选择，修改后可保存或放弃。配置经 token-heatmap settings namespace 持久化到 <DSH_HOME>/settings.yaml；0.1.1 及更早版本的旧配置文件在启动时自动迁移。
数据是怎么来的¶
服务端增量折叠全部会话事件日志中的 token 用量样本，按天、按模型聚合，缓存到 <DSH_HOME>/storages/token-heatmap-cache.json，并通过回环受限端点 GET /api/token-heatmap/usage 提供。数据端点仅回环地址可访问，凭据不外发；插件只读，不修改任何会话数据。
聚合与回环端点的实现参考了 dsh-usage-stats（MIT © Ychris12138）。
安装与启用¶
前置条件：需要 web profile 与 pnpm。
1、从 npm 安装：
dsh plugin --profile web add @kidli1412/dsh-token-heatmap
也可以从 GitHub 安装：
dsh plugin --profile web add github:KIDLi1412/dsh-token-heatmap
本地开发用本地链接：
dsh plugin --profile web add "link:path/to/dsh-token-heatmap"
2、安装完成后重启正在运行的 dsh web，并在浏览器中硬刷新（Ctrl+Shift+R）。之所以要重启，是因为服务端与客户端都随 dsh web 启动加载。
3、侧边栏没有新增入口。打开新会话，统计卡直接出现在输入框下方。
卸载：
dsh plugin --profile web remove @kidli1412/dsh-token-heatmap
兼容性¶
- DSH：manifest 将 0.1.2-alpha.4 / 0.1.2-alpha.5 / 0.1.2-rc.1 逐项声明为 compatible；宿主要求
engines.dsh: ^0.1.2-rc.1。 - Node：
^22.19.0 || >=24.0.0。
适用场景与注意¶
适合日常使用 dsh web、想直观掌握每日 token 用量的用户：装完不改变任何交互流程，打开新会话就能看到用量分布。
使用前注意：
1、插件以当前 dsh 进程权限运行，安装前建议检查源码与许可证。
2、无会话或无工作区时统计卡不渲染（input.dock 需要会话上下文）。
3、修改配置后在设置页保存或放弃；配置持久化在 <DSH_HOME>/settings.yaml。
4、新增或更新插件后需要重启 dsh web。
结尾¶
dsh-token-heatmap 把散落在会话日志里的 token 用量聚合成了熟悉的 GitHub 热力图视图，配合今日 / 本月 / 累计统计和可切换配色，属于装完就能长期挂着的 Web 插件。
- 社区目录页：https://www.skillhub.cn/plugins/KIDLi1412/dsh-token-heatmap
- GitHub 仓库：https://github.com/KIDLi1412/dsh-token-heatmap
社区目录 skillhub.cn 为独立站点，与 DeepSeek、幻方无官方从属关系。
