Token Usage（LLMDSHPlugin_token-usage）
DeepSeek Harness (DSH) 插件：在桌面端/Web 端侧边栏左下角增加 Token 统计，按天汇总当前 profile 下所有 Session 的 token 用量。
功能
- 左下角 footer 常驻入口，显示今日 token 总量。
- 点击展开统计面板：第一行是全部历史总量，下面是 GitHub 风格的每日日历热力图；颜色深浅表示当天用量，鼠标悬停/键盘聚焦可看当天总量、输入+输出、缓存读写和会话数。
- 按 provider 上报的 usage 统计，包含
inputTokens、outputTokens、cacheReadTokens、cacheWriteTokens。
- 中文界面下大数字用「万 / 百万 / 千万 / 亿 / 万亿」显示，悬停明细同时保留精确数字。
- 日历显示最近 365 天；顶部总量覆盖全部历史。
- 统计全部历史的轮次、步骤和平均生成速度（tok/s）。
- 面板打开优先使用本地缓存；自动刷新最快 1 小时一次，手动刷新立即重新扫描。
- Host 把每个 Session 的日汇总持久化到
~/.dsh/token-usage-ledger.json；Session 归档或删除后历史仍然保留。
- 只读扫描 Session 历史，不修改任何 Session 或配置；fork 继承的事件不会重复计数。
安装
要求 DSH Desktop / Web 已安装，且 profile 中已启用 @deepseek-ai/dsh-base。
从本地目录安装到 Desktop profile：
dsh plugin --profile desktop add D:\WORK\ai-v5\LLMDSHPlugin_token-usage
或直接从 GitHub 安装：
dsh plugin --profile desktop add github:ai-v5/LLMDSHPlugin_token-usage
安装后重启 DSH Desktop。插件会出现在左侧栏底部 Settings 上方（同一区域还有 Cordis 入口）。如果终端里没有 dsh 命令，可使用 DSH Desktop 安装目录下的 resources\runtime\cli\bin\dsh.cmd。
从旧的 LLMDSHPlugin monorepo 迁移：重新执行上面的 add 命令指向本仓库，旧的 plugins\token-usage 链接会失效。
卸载：
dsh plugin --profile desktop remove llm-dsh-token-usage
统计口径
- 数据来自 DSH 的
ctx.sessionQuery：先 listSessions()，再读取每个 Session 的完整事件日志。
- 每个
assistant/message 或 assistant/attempt 的 provider usage 都会计入；同一 turn/step 的后续样本会替换前一样本，llm/retry-started 之后的 attempt 单独累计。
compaction/summary 自带的 usage 也会计入（压缩调用不在 agent loop 的 step 内，日志里只有这一条记录）。- 日期按 Host 本地时区划分。
totalTokens = inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens，其中包含 prompt cache 命中读取；面板同时展示不含 cache read 的 inputOutputTokens。- 子 Session 与父 Session 都是独立 Session，会各自计入；fork 继承的前缀通过
inheritedEventCount 排除。
接口
Host 端注册只读路由：
GET /api/llm-token-usage/stats?range=all&refresh=1
也兼容 ?days=7|14|30|90 的有界范围。返回：
{
"generatedAt": 1760000000000,
"days": 366,
"rangeKind": "all",
"seriesTruncated": false,
"range": { "from": "2025-10-19", "to": "2026-10-18" },
"today": { "date": "2026-10-18", "inputTokens": 0, "outputTokens": 0, "cacheReadTokens": 0, "cacheWriteTokens": 0, "totalTokens": 0, "inputOutputTokens": 0, "sessions": 0 },
"totals": { "...": "same shape as today" },
"allTime": { "...": "same shape as today" },
"series": [{ "date": "2025-10-19", "...": "same shape as today" }],
"sessionCount": 0,
"skippedSessions": 0,
"incomplete": false,
"activity": {
"turns": 0,
"steps": 0,
"generationMs": 0,
"timedOutputTokens": 0,
"tokensPerSecond": 0
}
}
activity 为全部历史汇总：turns/steps 来自 turn/start/step/start；tokensPerSecond = timedOutputTokens / (generationMs / 1000)，只统计带流式时间戳的 Assistant 调用。
Host 结果缓存 1 小时；refresh=1 跳过缓存并重新扫描。浏览器端在 localStorage 缓存最近一次成功结果：面板打开时优先显示缓存，缓存不足 1 小时不发请求，超过 1 小时才后台刷新；手动刷新不受此限制。
已知限制
- AI 会话标题（session title）等辅助调用不写入 Session 日志，因此不会计入；如果部署把这些调用计费，面板总量会略低于账单。
- 读取失败的 Session 会被跳过，面板会显示
skippedSessions 提示。
- 统计是 provider 上报 usage 的汇总，不是计费账单；不同 provider 对缓存读/写的上报口径可能不同。
- 首次打开或手动刷新需要扫描全部 Session 日志，Session 很多时会有短暂延迟；之后 1 小时内优先使用浏览器和 Host 缓存。
- 插件首次成功扫描前就已经删除的 Session 无法追溯；删除
~/.dsh/token-usage-ledger.json 会重置历史汇总。
开发
node --test tests/stats.test.mjs
node --check lib/stats.js
node --check index.js
node --check client.js
项目本身不需要构建：index.js 是 Host 半部，client.js 是浏览器半部，locale/*.json 提供插件管理页显示名称。
参考
设计上参考了 MIT 许可的 HaoyueQin/dsh-usage-statistics-panel 的按天口径与 footer 面板布局；本仓库代码是独立实现，没有复制其源码。
License
MIT
