前言¶
在基于 DeepSeek Harness（DSH）开发智能体、编排 Workflow 或处理长上下文时，每次模型调用的 Token 消耗与成本往往分散在日志和会话历史里，难以快速评估模型表现、缓存效率与预算。DSH 本身不提供全局用量聚合与成本核算能力，需要额外插件来统一统计与呈现。
插件定位¶
dsh-metrics 是专为 DeepSeek Harness 打造的轻量级插件，通过捕获宿主内部的所有模型调用事件，将 Token 消耗实时聚合并在 Web 侧边栏提供交互式看板。它按模型/供应商/项目/会话统计调用与缓存命中，并接入 OpenRouter 公开价目表进行成本估算。插件由 zdt3476 维护，分类为联网工具。
核心能力¶
- 全量调用追踪：通过双通路捕获覆盖所有
assistant/message会话事件，并通过 waterfall 补齐会话标题生成、记忆压缩等独立调用的 Token 消耗。 - 多维切片透视：在看板中按模型、供应商、工作区项目与会话自由切换与排序下钻，长列表支持容器内滚动与表头吸顶。
- 指标卡组：请求总数（含成功率/成功/失败）与 Token 总数（构成内联）两张主卡，配合 RPM、TPM、缓存率、成本四张卡，每张卡叠加迷你趋势线；支持今天/24 小时/3 天/7 天/30 天/全部六档时间范围。
- 成本核算（OpenRouter 单价）：自动拉取 OpenRouter 公开价目表并缓存 24 小时，按输入/输出/缓存读/缓存写/推理分别计价；缺价格的模型会显式提示而不是按 0 计算。
- 真实 RPM / TPM：账本内置最近 90 分钟的分钟级计数，RPM/TPM 为最近 60 分钟的实际墙钟速率。
- Token 活动热力图：以「星期 × 自然周」排布，顶部标注月份，直观展示每周使用规律。
- 供应商明细：按供应商列出请求数、Token、成本与占比条。
- 模型用量环形图：环形占比 + 右侧图例榜（模型、用量、占比），支持「按用量/按调用」两种口径切换。
- 多模型趋势图：单张折线图按模型分组，配图例与悬停明细，时间轴自动稀疏刻度避免拥挤。
- 缓存命中率审计：精准统计
cacheRead与新输入的配比，清晰呈现 Prompt 缓存命中效果。 - 离线日志自动回扫：首次安装或数据重建时，支持通过原生
zstd解压磁盘会话历史（.jsonl.zstd），即使离线或无持久化服务也能完整恢复历史统计。 - 账户余额实时展示：在面板顶部实时展示当前登录用户余额与代金券赠金，支持直达官方用量页面。
- 轻量安全与原子存储：本地存储采用写入防抖与临时文件原子重命名机制，避免 I/O 阻塞并防止半写入损坏；纯本地运行，不携带凭据，绝不向第三方上传任何数据。
安装与启用¶
方式一：命令行一键安装（推荐）¶
dsh plugin --profile web add @zdt3476/dsh-metrics
也可以直接装源码（无需 NPM）：
dsh plugin --profile web add github:zdt3476/dsh-metrics
方式二：通过 DSH 插件管理器¶
在 DSH 控制台中直接执行：
plugin_manager install_bundle @zdt3476/dsh-metrics
方式三：手动配置 Profile¶
在你的 DSH Profile（如 ~/.dsh/profiles/web/package.json）中添加依赖：
{
"dsh": {
"profile": {
"bundles": ["@zdt3476/dsh-metrics"]
}
},
"dependencies": {
"@zdt3476/dsh-metrics": "^1.0.3"
}
}
并在当前 Profile 的 cordis.patch.yml 中声明加载：
- insert:
- id: dsh-metrics
name: '@zdt3476/dsh-metrics'
重启 DSH 后，侧边栏左侧工具栏即会出现 用量监控 图标。首次载入看板会自动执行历史会话日志回扫，无感补齐过往全部调用数据。
统计口径与计算公式¶
| 指标字段 | 含义 | 说明 / 计算公式 |
|---|---|---|
| 调用次数 (Calls) | 模型请求总次数 | 按 (sessionId, turn, step) 严格去重累加 |
| 输入 (Input Tokens) | 未命中缓存的新输入量 | 模型消耗的新上下文 Token 数 |
| 缓存读 (Cache Read) | 命中缓存的输入量 | 上下文 Prompt 缓存成功复用的 Token 数 |
| 缓存写 (Cache Write) | 写入缓存的输入量 | 首次加载写入缓存的 Token 数 |
| 输出 (Output Tokens) | 模型最终生成的回复 Token | 包括代码、思考内容与最终文本 |
| 推理 (Reasoning) | 深度思考/推导 Token | 具备推理能力模型（如 R1）的思维链 Token 消耗 |
| 总量 (Total Tokens) | 单次调用涉及的所有 Token | 适配器上报值或各项 Token 之和 |
| 缓存命中率 (Hit Rate) | 输入层缓存复用效率 | CacheRead / (CacheRead + Input) |
配置说明¶
插件所有配置均开箱即用。若需自定义，可在 cordis.patch.yml 中覆盖：
- id: dsh-metrics
config:
flushDelayMs: 2000 # 磁盘写入防抖延迟（毫秒）
snapshotCacheMs: 3000 # 聚合快照缓存时间（毫秒）
retentionDays: 400 # 历史按天分桶保留天数（0 为不裁剪）
maxSessions: 500 # 会话明细最大保留记录数
maxTrendSeries: 6 # 趋势图展示的前 N 大模型曲线数
trackAccount: true # 是否读取登录账号余额（只读）
autoUpdate: true # 是否装配自更新检查
watchFiles: false # 开发环境文件变动热重载
HTTP 服务接口¶
插件在宿主 Web 服务中内置了只读接口与管理通道：
| 请求方法 | 接口路径 | 功能说明 |
|---|---|---|
GET |
/api/dsh-metrics/summary |
获取最新多维聚合快照（前端看板数据源） |
GET |
/api/dsh-metrics/flush |
立即强制执行防抖落盘，并返回最新快照 |
GET |
/api/dsh-metrics/version |
查看当前运行版本、构建标识与仓库信息 |
GET |
/api/dsh-metrics/update/check |
检查 GitHub Release 最新版本状态 |
POST |
/api/dsh-metrics/reload |
触发插件进程内热重载（重新加载磁盘代码） |
本地开发与测试¶
本项目采用现代 TypeScript 开发流程：
# 1. 安装依赖
pnpm install
# 2. 执行静态类型检查与全量单元测试
pnpm test
# 3. 运行构建（输出至 lib/）
pnpm run build
# 4. 监听测试
pnpm run test:watch
适用场景与注意¶
适合需要集中监控 DeepSeek Harness 模型调用成本与效率的开发者与团队，尤其是使用多模型、多供应商、多项目时，便于快速识别高消耗路径与优化缓存策略。
插件以当前 DSH 进程权限运行，安装前建议检查源码与许可证。插件依赖 Node.js ^22.19.0 || >=24.0.0 和 DSH >=0.2.0，可选依赖 @deepseek-ai/cordis: ^4.0.5。
结尾¶
dsh-metrics 为 DSH 提供了从单次调用到全局成本与缓存效率的完整透视能力，适合将 Token 用量与成本纳入日常开发与运营的闭环。插件目录页与源码仓库链接如下：
- 插件目录页：https://www.skillhub.cn/plugins/zdt3476/dsh-metrics
- GitHub：https://github.com/zdt3476/dsh-metrics
