前言¶
DeepSeek Harness (DSH) 是本地智能体测试工具。原生 Web 界面缺少对 Token 消耗和成本的直观展示。dsh-token-usage 插件为 DSH 的 Web 配置面板新增了“使用统计”页面，通过将原始 Token 消耗转换为官方的高峰/非高峰费率，帮助开发者量化实际支出。
插件介绍¶
dsh-token-usage 是一个用于 DeepSeek Harness 的插件。它不修改智能体运行逻辑，仅作为观察者读取持久化的会话日志，在本地计算并展示 Token 使用情况和估算成本。
核心功能¶
该插件提供以下核心能力：
- 摘要卡片：展示总 Token 数、日均、缓存命中率、估算支出。支持按“今天/本周/本月”切换。
- 热力图：提供 3 个月的 GitHub 风格水平热力图。悬停任意日期单元格可查看该日的详细 Token 统计和支出（CNY/USD）。
- 真实成本估算：使用官方的高峰/非高峰费率计算真实成本，并自动转换为 CNY 和 USD。
- 价格表管理：支持按模型编辑价格表，包含 CNY/USD 以及高峰/非高峰两个时段的价格配置。
- 精确计费：根据事件时间戳计费。北京高峰时段（09:00–12:00, 14:00–18:00）使用高峰费率，其余时段使用非高峰费率。
- 纯观察者模式：不修改 Agent 循环，不上传数据到外部服务，数据完全存储在本地。
安装与启用¶
插件安装到 DSH 的内置 Web 配置文件中。
使用 npm 安装（推荐）¶
dsh plugin --profile web add dsh-token-usage
使用本地路径安装¶
如果直接使用本地源码安装，需先构建：
pnpm build
dsh plugin --profile web add /path/to/dsh-token-usage
启动¶
安装后，从 DeepSeek Harness 检出目录运行即可：
pnpm dsh web
配置与使用¶
数据来源于持久化会话日志中的 usage 字段。
价格配置¶
插件支持通过 Web 配置文件或 --patch 覆盖层修改价格表。配置文件路径通常为 $DSH_HOME/profiles/web/cordis.patch.yml。
在配置中定义模型的价格，包含货币类型、高峰/非高峰费率以及输入/输出/缓存读写等各项指标。未配置的模型将使用内置的默认值。
索引位置¶
插件使用增量索引存储数据，索引文件位于 $DSH_HOME/dsh-token-usage/index.。系统会定期进行磁盘同步，确保重启后能快速恢复统计数据。
