dsh-plugin-token-heatmap
该插件为每日 Token 用量热力图插件，面向 DeepSeek Harness Web GUI（dsh web profile）。
截图
功能
- 双数据视图：「全局」（所有会话合计）与「当前会话」，悬浮窗内切换
- 历史回填：首次安装自动扫描全部会话日志，把过去的 token 消耗计入热力图
- 实时更新：窗口可见时每 3 秒轮询，数据带版本号，仅变化时更新
- 5 级蓝色色阶：12 个月窗口内非零天数按四分位分档，最深色
#396BE2
- 竖向网格：最新一周在顶部，向下滚动回看 12 个月，带「回到最新」浮层
- 悬浮窗交互：头部拖动、位置 clamp 在视口内、显隐/位置/视图记忆于 localStorage
- 汇总统计：今日 / 本周 / 本月 / 12 个月合计，tooltip 展示输入 / 输出 / 缓存读写分项
- 主题适配：深浅主题均正常显示（DSH 主题 token）
环境要求
- Node.js ≥ 20，pnpm
- DeepSeek Harness web profile（宿主需提供
@deepseek-ai/* 运行时，见 peerDependencies）
- 依赖
@deepseek-ai/* 为内部私有包，仅能在 DSH 环境内安装
构建
pnpm install
pnpm build # 产出 lib/index.js（宿主）+ lib/client.js（客户端 bundle）
验证
pnpm typecheck # tsc --noEmit
pnpm test # node --test，宿主端单元测试
pnpm test:ui # vitest，客户端组件测试
安装
dsh plugin --profile web add dsh-plugin-token-heatmap
重启dsh web，右下角出现方形图标即安装成功。首次启动后台执行回填，期间界面可用。
数据存储
宿主端持久化在 $DSH_HOME/token-heatmap/（即 ~/.dsh/token-heatmap/）：
| 文件 | 内容 |
|---|
global.json | 全局每日用量（近 13 个月） |
sessions.json | 按会话每日用量 |
meta.json | 回填状态（done / scanned / skipped） |
写入策略：内存合并 → 5 秒节流 → 原子写（临时文件 + rename）。文件损坏时从空状态启动并告警，不阻断插件。
localStorage 键（客户端）
| 键 | 说明 |
|---|
dsh.tokenHeatmap.visible | 悬浮窗显隐 |
dsh.tokenHeatmap.position | 悬浮窗位置 |
dsh.tokenHeatmap.iconPosition | 图标位置 |
dsh.tokenHeatmap.view | 视图（global / session） |
架构
一个 npm 包、双半区（宿主 + 客户端）：
src/
├── index.ts # 宿主端入口：实时累计 + 一次性回填
├── usage-store.ts # 每日聚合存储（节流原子写、13 个月裁剪）
├── backfill.ts # 会话日志扫描回填
├── service.ts # TypertRemoteService：tokenHeatmap Remote 服务
├── day.ts # 本地时区自然日工具
├── usage.ts # 聚合/合并/裁剪纯函数
└── client/
├── index.tsx # 客户端入口：挂载 Remote + shell.overlay
├── remote.ts # 手工 Typert Remote 描述符 + strict 校验器
├── TokenHeatmapOverlay.tsx # 悬浮窗 + 右下角图标
├── HeatmapGrid.tsx # 周×天网格（竖向滚动）
├── ToggleIcon.tsx # 右下角方形图标
└── palette.ts # 5 级色阶与四分位映射
- 数据通道：客户端 ↔ 宿主走 Typert Remote 机制（
@Remote 方法暴露为 <namespace>/<method> 端点）；方法有 getGlobalUsage / getSessionUsage / getBackfillStatus
- UI 注册：
ctx.slots.inject('shell.overlay', ...) 挂到根级浮动层
- 用量口径：input + output + cacheRead + cacheWrite 合并为每日 total 用于着色
License
MIT
