dsh-token-heatmap

dsh-token-heatmap

DSH Web GUI 插件：在新会话（hero）屏幕的输入框下方显示一个 GitHub 风格的 token 用量热力图 —— 可在年视图（当前自然年 1月–12月）与月视图（单月日历，逐日数值）之间切换，颜色深浅表示用量多少；同一行展示今日 / 本月 / 累计 token 用量。所有设置都在卡片自己身上（⚙），不在 DSH 设置里。

A DeepSeek Harness web plugin: a GitHub-style daily token-usage heatmap rendered below the composer input card on the new-session screen only, switchable between a calendar-year grid (Jan–Dec) and a single-month calendar with per-day numbers, with today / this-month / all-time totals on the same line. The card configures itself (⚙) — nothing lives in DSH settings.

界面 / What you get

新会话屏幕输入框正下方出现一张统计卡（只在新会话显示；已对话的会话不显示）：

月视图 / Month view

单月日历：7 列（周一起，表头一~日）× 5–6 行，每格显示日号 + 当日 token 数（如 4 44m），底色沿用同一套绝对阈值配色，一眼看出这个月哪几天在烧 token；周末列有浅色底以便区分。标题行的 ‹ 2026年9月 › 按月步进（最新到本月，最早到有数据的第一天）。

年视图 / Year view

GitHub 风格自然年热力图：覆盖所选自然年 1月–12月（‹ 2026 › 按年步进，最多到当前年），列为周（周一起），行为星期（左侧标注一~日全部 7 天）；顶部月份标签按列跨度标注（左侧与格线对齐），今日之后的日期显示为空格。

共同特性 / Shared

• 🔀 年 / 月切换：标题行里的分段按钮即时切换视图（在 ‹ › 步进器右边，跟着它一起管当前视图）；刷新 与 ⚙ 在行的最右端。
• 🎨 六套配色：绿色（经典 GitHub 风格）、蓝色、橙色、红色、紫色、青色，点卡片上的 ⚙ 切换（见下）；颜色按绝对阈值分档（按天 token 数，非相对排名）：0 / <1M / 1M–10M / 10M–100M / ≥100M 共 5 级，卡片右下角图例悬停显示各档范围；61M/天 显示为第 3 级。悬停任意格子（年视图的 10px 格子或月视图的日期格）显示日期与精确 token 数。
• 🔢 统计行（与标题同一行）：今日 / 本月 / 累计，悬停显示完整数值；本月/累计与当前视图无关，始终是实时值。
• 🔄 自动每 5 分钟刷新，窗口重新可见时也会刷新；行尾可手动刷新。

卡片设置 / In-card settings

• ⚙️ 设置就在卡片上：点标题行最右端的 ⚙（刷新 [⚙]）弹出悬浮设置面板 —— 位置在 ⚙ 正上方 8px、水平居中对齐、贴边留 12px，超出视口会自动钳制；点面板外的任意位置、按 Esc、或再点一次 ⚙ 都会收起。插件不再往 DSH 设置（设置 → 插件 → 插件配置）里注册任何卡片，所以那里看不到本插件。
• 配色方案：六个色板按钮，点击即时生效（不需要"保存"）；默认视图：年 / 月，决定新会话页面首次打开时显示哪个视图（当次会话手动切换只影响当前页面）。面板底部是阈值图例（悬停看各档范围）与一行说明。
• 写入失败时面板底部会红字提示"保存失败，已回到服务端的值"（settings scope 复核后回滚乐观值）。
• 配置作为本插件的 profile 配置持久化：DSH 0.2.0 用插件导出的 Config schema 生成设置表单，表单以 profile entry id（token-heatmap）为键，值写进 profile patch（旧的 <DSH_HOME>/settings.yaml 段与 0.1.1 及更早的 <DSH_HOME>/storages/token-heatmap-config.json 都会在启动时一次性迁移/抢救回配置）。⚠️ 两个字段必须带 .volatile()：DSH 只从 schema 的 volatile 子树生成表单，全是普通字段的条目会被 settings.describe() 整个丢弃、settings.update() 则抛 Plugin entry "token-heatmap" has no volatile fields——两种情况下 ⚙ 面板都只会静默回落到默认值（即"设置不生效"）。

安装 / Install

需要 web profile 与 pnpm。DSH 兼容版本见下方「兼容性 / Compatibility」；运行于 @deepseek-ai/dsh ^0.2.0-rc.2（0.2.0 版本线；0.1.2 线请用 0.4.2）。

从 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"

安装完成后重启正在运行的 dsh web，并在浏览器中硬刷新（Ctrl+Shift+R）。侧边栏无新增入口——统计卡直接出现在新会话输入框下方。卸载：

dsh plugin --profile web remove @kidli1412/dsh-token-heatmap

工作原理 / How it works

• 服务端（lib/index.js + lib/usage.js + lib/config.js）：作为 profile bundle 挂载，实时折叠会话事件（监听官方 session/event，每个 assistant/chunk/assistant/message 的 usage 事件即时写入缓存，不依赖 hero 屏挂载）；启动时一次性补折叠已存在的 live 会话（如 resumed 会话）；请求时 collectUsage 再做一次增量同步兜底，并枚举 已归档（stored）会话补齐历史——两种 sessionPersistence 接口都支持：0.1.2 线的 listSnapshots() + readFrom()，以及 0.1.3 起取代它们的 list() + open()/handle.read()。同 (turn, step) 的重复样本按"替换"语义处理，归属后一天；fork（isSeeded）会话从它的继承切点开始折叠——日志开头那批属于父会话的事件在父会话侧已折叠，跳过它们才不会把同一批 token 计两次；按天、按模型聚合，缓存到 <DSH_HOME>/storages/token-heatmap-cache.json（跨进程复用：revision 证明"这份日志没变"就完全跳过、只有追加时才折新尾巴、重写才从切点重建，见 0.5.2 条目）。通过回环受限端点 GET /api/token-heatmap/usage 提供；显示配置（配色 + 默认视图）由导出的 Config schema 持有（0.2.0 的设置模型：以 entry id token-heatmap 为键的表单，值写进 profile patch），GET/POST /api/token-heatmap/config 作为回环兼容 API 读写同一份配置（读经 settings.describe()，写经 settings.update()；0.1.x 的 enabled 开关已废弃，该字段只作为常量 true 回给旧客户端），0.1.1 及更早的 token-heatmap-config.json 文档在启动时一次性迁移。
• 客户端（lib/client.js）：手写 __ModuleLoader__ bundle，注册进会话 conversation.input.dock 列表插槽，仅在 session.blank（新会话 hero 屏；旧宿主回退 composerPhase === "blank"）时渲染——卡片没有显示开关，hero 屏上始终显示。框架真正的"卡片下方"插槽 conversation.composer.dock 在 hero 屏被 !hero 门控禁用，因此本插件利用 input.dock 容器（flex 列）的 CSS order 把自己排到输入卡片之后。同一份数据由 buildGrid()（年，53 列 × 7 行）与 buildMonthGrid()（月，7 列 × 5–6 行，带日号）两个纯函数分别铺格，共用 levelOf() 的绝对阈值分档与 palette 配色；‹ › 按钮按当前视图步进年或月，边界取"当前年/月"与"数据里最早的月"，年/月分段按钮紧跟在步进器后面，⚙ 设置面板在卡片底部展开（内嵌面板，动作：⚙ 切换 / × / Esc / 焦点移出）。不注册 settings.plugin.item（官方"插件配置"页签只渲染"Host 实际 serve 的 namespace ∩ 客户端已注册 key"的卡片，本插件不再占这个位置），配置经 ctx.configForms.get("token-heatmap") 读写本插件配置（0.2.0 的设置模型，取代 0.1.x 的 settings scope）。
• 语义与 dsh-token-meter 的 tokenUsage 投影一致（参考插件 dsh-usage-stats，MIT）。

说明 / Notes

• 仅回环地址可访问数据端点，凭据不外发；插件只读，不修改任何会话数据。
• 无会话/无工作区时（input.dock 需要会话上下文）统计卡不渲染。
• 服务端与客户端都随 dsh web 启动加载，因此新增/更新插件后需要重启。

兼容性 / Compatibility

在 GitHub 阅读完整 README →