DSH（DeepSeek Harness）的核心理念是「一切皆插件」。在智能体开发与调试过程中，追踪跨会话的 Token 消耗是高频需求。dsh-usage-lite 是一个由开发者 ChrisLou-bioinfo 维护的插件，它无需构建步骤，直接在本地聚合所有会话的 Token 数据，并在设置面板新增「用量统计」页进行可视化展示。
核心功能¶
该插件提供以下统计与展示能力：
- 汇总卡片：展示总 Tokens、输入（未缓存）、缓存读（含命中率）、缓存写、输出（含推理）。
- 时间范围切换：支持 7 天、30 天或全部历史数据的查看。
- 多维度排行与图表：提供按天用量柱状图、按模型排行以及按工作区排行。
- 增量索引与持久化：首次全量扫描后，仅重读新增或变更的会话，并将索引快照持久化到
~/.dsh/usage-lite/index.json，避免重复计算。
安装与启用¶
通过官方插件命令安装。该插件适配 DSH 0.2.0-rc.2+（桌面端与 Web Profile 均可）。
dsh plugin add github:ChrisLou-bioinfo/dsh-usage-lite
安装完成后，打开 Settings → 用量统计 页面即可查看统计数据。
统计口径与数据流¶
插件的数据来源为本地会话日志，具体规则如下：
- 数据源：优先读取
ctx.sessionQuery（Live 数据），兜底使用readSession(id)读取持久化事件。 - 过滤规则：仅统计
assistant/message事件中data.usage且data.message.source.kind === "model"的样本，忽略流式assistant/attempt里的过程值。 - 去重处理：跳过
inheritedEventCount之前的事件，避免 fork 或 resume 会话时重复计算父会话的 Token。 - 计算公式：
total = input + output + cacheRead + cacheWrite；reasoning单独列出。 - 缓存命中率：
cacheRead / (cacheRead + input)，若 Provider 不上报缓存则显示 “—”。
技术维护注意¶
- 客户端约束：客户端 Bundle（
client.js）只能依赖平台种子模块（如react、dsh-client-store等），禁止引入外部依赖。 - 注入服务名：
client.js的exports.inject必须是服务名["slots"]（非包名）。若配置错误，Web 启动会判定 “entry did not activate” 并拒绝启动，桌面端连续失败会触发恢复流程。 - 升级排查：若升级 DSH 版本后设置页空白，请前往 Settings → Plugins → Plugin list 检查装载审计信息。
- 移除插件：
- 命令行：
dsh plugin remove dsh-usage-lite - 手动：删除对应 profile 的
cordis.patch.yml中的插入条目。 - 索引清理：
~/.dsh/usage-lite/目录可一并删除（建议）。
- 命令行：
总结¶
dsh-usage-lite 是一个轻量级的 Token 统计工具，它通过增量索引和本地快照技术，在无需网络请求的情况下实现了跨会话的数据聚合。对于需要精细化控制成本和监控模型调用的开发者，这是一个直接可用的工具。
