前言¶
DeepSeek Harness (DSH) 采用插件化架构。在智能体开发或长对话场景中，开发者需要持续追踪 token 消耗、缓存命中率以及供应商的余额情况。dsh-usage 插件通过在侧栏注入面板，将余额、用量曲线、成本估算与热力图集中展示，无需切换窗口即可查看数据。
核心功能¶
该插件在侧栏“设置”按钮上方注入一个“用量”按钮，点击后展开单页模态面板，包含以下五个部分：
- 供应商余额：支持 DeepSeek（
DEEPSEEK_API_KEY）与 OpenRouter（OPENROUTER_API_KEY）。凭据仅在 host 侧解析，不会传入浏览器。 - 用量与命中率：可切换查看“全部会话”或“单个会话”。命中率为输入侧缓存命中率。
- 折线图：展示当日按小时聚合的 Token 和成本曲线。悬浮鼠标可查看该小时的具体数据桶（未命中、命中、输出）。
- 热力图：GitHub 风格的贡献度展示。支持“时间模式”（最近 13 周每日）和“会话模式”（每个会话的每轮）。
- 历史明细：分页展示全量明细，支持导出 CSV（含 BOM，可直接用 Excel 打开）。
安装与启用¶
通过官方命令安装该插件，重启 DeepSeek Harness Web 后生效。
dsh plugin --profile web add @dshd/dsh-usage
安装完成后，侧栏“设置”按钮上方会出现“用量”按钮。
使用方式¶
- 查看余额：在面板顶部切换供应商（DeepSeek / OpenRouter）以刷新余额。
- 筛选会话：通过下拉菜单切换“全部会话”或特定会话，面板数据会随之更新。
- 分析趋势：观察折线图了解当日 Token 和成本分布，通过热力图定位高频交互时段。
- 导出数据：在历史明细页点击导出按钮，获取 CSV 文件进行离线分析。
数据与配置¶
- 数据来源：解析 DSH 会话日志（内存活跃 + 磁盘持久化），提取
assistant/chunk和assistant/message事件中的 usage 数据。 - 计算逻辑：
- 命中率 =
cacheRead / (uncachedInput + cacheRead + cacheWrite)。 - 成本 = 未命中输入×miss + 命中×hit + 输出×out。价格按请求时刻套用官方峰谷价目，并定期在线同步官方价格页（失败时回退内置价目）。
- 命中率 =
- 安全性：插件不保存凭据，不上传数据，全部计算在本机完成。
- 配置项：
cnyPerUsd：USD 换算汇率，默认为6.76。pricing：单价覆盖配置，支持定义峰谷时段。
适用场景与注意¶
- 适用场景：需要精细化控制 API 成本、监控缓存效果以及管理多供应商账户余额的开发者。
- 注意：成本为按官方刊例价与请求时刻计算的估算值，可能与实际账单存在差异。插件以当前 dsh 进程权限运行，安装前建议检查源码与许可证（MIT）。
结语¶
dsh-usage 提供了一套标准化的用量监控方案，适合追求成本透明与开发效率的 DSH 用户。
