Token 用量看板 zhangyongshuai56-hub/dsh-token-usage

dsh-token-usage

统计 DSH 每天消耗的 token，按模型分系列展示趋势与日历热力图。

安装

从 GitHub 仓库地址安装（市场里也可直接搜包名）：

https://github.com/zhangyongshuai56-hub/dsh-token-usage

npm 包名是 @zhangyongshuai56-hub/dsh-token-usage（dsh-token-usage 已被他人占用，故加 scope）。

也可以本地软链开发（见文末「开发」）。安装后在设置里打开「Token 用量」面板即可。

数据从哪来

DSH 没有现成的按模型 token 台账。每条模型响应把用量写进会话文件的 assistant/message 事件：

{"type":"assistant/message","time":1791555004268,
"data":{"usage":{"inputTokens":7636,"outputTokens":505,
"cacheReadTokens":0,"cacheWriteTokens":0,"totalTokens":8141}}}

模型归属在同一会话的 request/header（config.provider / config.model）里，时间按本地时区归日。宿主侧扫描 ~/.dsh/sessions//session.v4.jsonl.zstd （zstd 多帧，每帧独立解压后拼接）聚合出「天 × 模型」的用量表。

一次全量扫描约 0.7 秒（40 个会话文件 / 38 MB），所以不能把它压在用户点开面板的那一次请求上。

加载性能

点击后面板要立刻出数字，做法是两层：

服务端 · stale-while-revalidate

- 插件装载时后台预热一次快照，用户第一次点开时通常已经就绪；
- 快照过期（30 秒 TTL）时，接口先返回旧数据（立刻出数字），同时在后台重扫，响应头 x-token-usage-stale: 1 标记「这是旧的」；
- 后台扫描走异步驱动，每处理几个文件就把事件循环让出去，不卡宿主进程。

服务端 · 增量扫描

会话文件是追加写的，所以历史部分的聚合结果永远不变。按文件记住「消费到第几个字节 + 截至该处的聚合结果」，再次扫描只解压新增的那几帧：

| 场景 | 全量 | 增量 |
| 冷扫描（首次 / 文件被改写） | 735 ms | 735 ms |
| 稳态（文件没变） | 735 ms | 1-2 ms |
| 当前会话又写了几条 | 735 ms | 3 ms |

另外扫描时先用正则挑出与统计相关的事件行（assistant/message、 request/header、request/context），其余 85% 的行不交给 JSON.parse；预筛没挑中任何一行时退回逐行全解析，避免日志格式变化导致统计漏数。

浏览器端

拿到 x-token-usage-stale: 1 时，页面会在 1.2 秒后自动补取一次，把刚刷新的数据换上——用户全程不用等。

界面

设置 → Token 用量：

- 顶部 5 格大数字：累计 / 峰值 / 日均 / 调用次数 / 当前连续天数
- Token 活动：整年日历热力图（每日 / 每周 / 累计三种口径），方块格、颜色深浅表示消耗量，悬停或点按出当日各模型明细
- 每日 Token 趋势图：连续日历轴（无记录的日期计 0，线不断、空档宽度是真实天数），每模型一条系列，只画用量前 5 名、其余合并为「其他」，悬停出明细
- 模型排行：范围内全部模型

配色走宿主 token（--dsw-alias-），跟随 DSH 深浅主题。

接口

GET /dsh-token-usage/usage
→ { days: { "YYYY-MM-DD": { "provider/model": { total, input, output, calls } } },
models: string[], totalTokens, totalCalls, scannedAt, sessions }

响应头 x-token-usage-stale: 0 | 1 # 1 = 这是旧快照，服务端正在后台重扫

开发

插件是本地软链安装的（link: 协议），改完源码重启 DSH 即可生效：

node --check lib/index.js && node --check lib/aggregate.js && node --check lib/client.js

lib/client.js 手写成 window.__ModuleLoader__ 工厂，没有构建步骤——图表是手写 DOM + SVG，不需要 JSX，也就不需要打包器。

2026-11-01 UI/UX 修复（审计后落地）

按 ui-ux-pro-max 的十条优先级审计后修掉的部分（未采纳的两条见末尾「已知未做」）：

| 项 | 问题 | 修法 |
| 配色可读性 | 黄金角色板在白底有 19/31 个系列色低于 4.5:1，最差 1.70:1（画了看不见） | 色相不动，明度按主题夹到 ≥4.5:1（readableColor）；兜底灰同步可读（5.98:1 / 7.28:1）。实测 31/31 达标 |
| 主按钮 | 白字压 #3b82f6 只有 3.68:1 | 底色换成按主题夹过的 --tu-accent，文字色 --tu-on-accent 随之反转 |
| 首帧 | 请求返回前是空白容器（CLS + 无反馈） | 等尺寸骨架 + aria-busy，数据到达不跳动；失败态给「重试」按钮 |
| 空态 | 只有一句话、没有出口 | 文案 + 副文案 + 「重新读取」按钮（事件委托，重绘无需重绑） |
| 空态对比 | --tu-t3 3.25:1 | 正文改 --tu-t2（7.73:1），--tu-t3 只留给装饰 |
| 数据只靠颜色 | 热力图只有色阶，读不到具体数值 | 新增表格视图（日期 / Token / 调用 / 强度），与热力图一键切换 |
| 排行名次 | 只靠颜色和条长 | 增加序号列（1…n） |
| 触摸目标 | 按钮 28px | 32px 起，@media (hover:none) 提到 44px |
| 语义/文案 | 页面标题与卡片标题同为 h3；头部用全数字、KPI 用万/亿；· anim v2 调试残留 | h2 / 统一 fmtCN / 删除残留 |
| 数字精度 | 2.96 亿被四舍五入成「3亿」 | 亿保留两位再去尾零 |

已知未做（按使用方决定不采纳）：图表键盘可达（tabindex + aria-label + 方向键）、热力图触摸后提示常驻。表格视图让数值可读，但没有键盘焦点路径。

顺带修掉的 harness 缺陷：harness/index.html 的深色预览只换了 body 背景、没换 --dsw-alias- 令牌，深色截图里文字全是黑的（误判为"插件深色不可用"）。