前言¶

在 DSH 里跑多后端、多 Session 时，账单和 provider 控制台往往对不上「今天到底用了多少」。字符数估算和真实 usage 也会差一截。若你只想在本机汇总各 Session 里 provider 上报的用量，又不想把日志发到外部服务，需要一个只读、本地的统计入口。下面介绍维护者 ai-v5 发布的客户端插件 LLMDSHPlugin_token-usage（npm 包名 llm-dsh-token-usage）：在 Desktop / Web 侧边栏左下角增加 Token 统计，数据全部来自本机 Session 日志。

这是什么¶

LLMDSHPlugin_token-usage 是 DeepSeek Harness（DSH）的客户端插件，分类为客户端。它在界面左下角（Settings 上方、与 Cordis 同区域）提供 Token 统计面板；Host 端读取 DSH Session 事件日志并汇总，浏览器端通过本机 Host 注册的 API 展示结果。统计口径以 provider 实际上报的 inputTokens、outputTokens、cacheReadTokens、cacheWriteTokens 为准，不绑定单一模型或供应商；DeepSeek、GLM、Kimi 等只要在 Session 中留下 usage，就会统一计入。

插件声明为仅本地、只读、不上传：除向本机 GET /api/llm-token-usage/stats 拉取统计外，不访问外部域名；Host 用 fs-read 读 Session 日志，fs-write 仅写入 ~/.dsh/token-usage-ledger.json 账本文件。当前版本 0.1.3，许可证 MIT，要求 Node >= 20、dsh >= 0.2.0，且 profile 中已启用 @deepseek-ai/dsh-base。

核心功能¶

汇总与展示¶

• 历史总量：面板第一行展示全部历史汇总；日历为最近 365 天 GitHub 风格热力图。
• 今日用量：左下角常驻今日统计；中文界面下大数可用「万 / 百万 / 千万 / 亿 / 万亿」显示，悬停仍保留精确数字。
• 明细字段：按日可看总量、输入+输出、缓存读取、缓存写入、会话数；totalTokens 含四类 token，面板同时展示不含 cache read 的 inputOutputTokens。
• 活动指标：全部历史汇总轮次（turns）、步骤（steps）及平均生成速度（tokensPerSecond，基于带流式时间戳的 Assistant 输出）。

持久化与刷新¶

• Session 归档或删除后，日汇总仍保留在 ~/.dsh/token-usage-ledger.json；账本采用临时文件 + 原子替换，损坏时保留 .corrupt-* 备份。
• Host 结果缓存 1 小时；refresh=1 可强制重扫。浏览器端用 localStorage 缓存最近一次成功结果，打开面板优先显示缓存；自动后台刷新最快 1 小时一次，手动刷新立即重扫。
• 增量扫描：已归档 Session 不重复读取，仅 live 或新增 Session 会再读；fork 继承的前缀通过 inheritedEventCount 排除，避免重复计数。

统计口径（摘要）¶

数据来自 ctx.sessionQuery：先 listSessions()，再读各 Session 完整事件日志。assistant/message 或 assistant/attempt 的 provider usage 计入；同 turn/step 的后续样本替换前一样本，llm/retry-started 之后的 attempt 单独累计；compaction/summary 自带 usage 也会计入。日期按 Host 本地时区划分。

安装与启用¶

要求已安装 DSH Desktop / Web，且 profile 启用 @deepseek-ai/dsh-base。

从 GitHub 安装到 Desktop profile：

dsh plugin --profile desktop add github:ai-v5/LLMDSHPlugin_token-usage

从 npm 安装：

dsh plugin --profile desktop add llm-dsh-token-usage

从本地目录安装（示例路径以 README 为准）：

dsh plugin --profile desktop add D:\WORK\ai-v5\LLMDSHPlugin_token-usage

安装后重启 DSH Desktop。若终端没有 dsh，可使用 Desktop 安装目录下 resources\runtime\cli\bin\dsh.cmd。

卸载：

dsh plugin --profile desktop remove llm-dsh-token-usage

从旧版 LLMDSHPlugin monorepo 迁移时，重新执行 add 指向本仓库即可；旧 plugins\token-usage 链接会失效。

典型用法¶

安装并重启后，在侧边栏左下角打开 Token 统计面板即可查看缓存或最新扫描结果。

需要立刻重算时，可请求 Host 只读接口（参数以 README 为准）：

GET /api/llm-token-usage/stats?range=all&refresh=1

也支持 ?days=7|14|30|90 等有界范围。返回 JSON 包含 today、totals、allTime、series（按日序列）、activity 及 skippedSessions、incomplete 等状态字段；面板据此渲染总量、热力图与明细。

适用场景与注意¶

适合谁：长期在 DSH 内切换多 provider、多 Session，希望在本机一眼看到 usage 趋势与输入/输出/缓存拆分的开发者。

权限与安全：插件以当前 DSH 进程权限运行，安装前建议阅读仓库源码与 MIT 许可证。市场可能因前端界面标注 network 能力；README 说明该请求仅为浏览器对本机 Host 的同源 GET /api/llm-token-usage/stats，不含遥测或外连。

已知限制（摘自 README）：

• 未写入 Session 日志的辅助调用（例如部分会话标题生成）不会计入，面板总量可能略低于某些账单。
• 读取失败的 Session 会跳过，界面可能提示 skippedSessions。
• 统计是 usage 汇总，不是计费账单；各 provider 对缓存读/写上报口径可能不同。
• 单 Session 读取超过 15 秒或整次扫描超过 45 秒会部分跳过并可能标记 incomplete。
• 插件首次成功扫描前已删除的 Session 无法追溯；删除 ~/.dsh/token-usage-ledger.json 会重置历史汇总。

设计上参考了 MIT 许可的 HaoyueQin/dsh-usage-statistics-panel 的按天口径与 footer 布局；本仓库为独立实现。

结尾¶

LLMDSHPlugin_token-usage 把 DSH 各 Session 的 provider usage 收拢到本机面板：历史总量、365 天热力图、缓存与轮次/步骤、tok/s，并在归档后仍靠账本保留历史。社区目录页与源码如下，安装命令以 README 为准。

• 目录页：https://www.skillhub.cn/plugins/ai-v5/LLMDSHPlugin_token-usage
• GitHub：https://github.com/ai-v5/LLMDSHPlugin_token-usage