前言¶
在 DeepSeek Harness（DSH）里跑主会话、子代理或 workflow 时，模型调用会不断发生。若只看各供应商后台或零散日志，很难回答：今天花了多少 token、钱主要花在哪个模型、缓存有没有帮上忙、中转站余额还剩多少。社区插件 dsh-token-metrics（维护者 hugoyee75-cmyk）把统计、估价和余额查询收进 DSH 侧边栏，数据来自 DSH 自己的会话日志，不额外发请求、不上传内容。下面介绍它做什么、怎么装、怎么用。
这是什么¶
dsh-token-metrics 是一个 DSH 插件（分类：模型推理）：记录每一次经过 Harness 的模型调用，在界面展示 Token 用量、按模型估算成本（含 DeepSeek 峰谷计价）、供应商余额与配额，并按模型、供应商、项目、来源、账号、日期等维度拆分。当前仓库版本为 0.3.0，许可证 MIT，Node 要求 ^22.19 || >=24（见 package.json）。
核心功能¶
用量统计¶
- 今日、近 7 天与全部的 token 总量及趋势涨跌。
- 各模型、各供应商用量排行；缓存命中率（是否重复输入在烧钱）。
- 各项目、各子代理的 token 消耗。
- 总计维度包括：input / output / cacheRead / cacheWrite / reasoning / total、调用次数、缓存命中率。
- 按来源区分：主会话、子代理、workflow；按项目以会话工作目录归组。
统计口径以 DSH 会话日志为准：完成的调用在日志中追加 assistant/message，携带 data.message.source.{provider, model} 与 data.usage 等字段；主会话、子代理、workflow、压缩与会话标题生成等场景会计入，失败重试的中间态 assistant/attempt 默认不计入（避免重复），可选开启失败请求统计。
成本估算¶
- 价格取自 LiteLLM 公开价目表（约 2800 个模型）。
- 峰谷计价：DeepSeek 谷时价为峰时一半，按调用时刻区分。
- 美元 / 人民币可切换，汇率实时拉取。
- 匹配不到价格的模型会标为「未定价」并提供补价入口，不会静默算成 0。
模型接入与余额¶
- 32 个服务预设（国内优先排序），选中即可填好地址与协议。
- 供应商余额与配额：覆盖 Sub2API / new-api / one-api 三类网关与 8 家官方平台。
- 从 pi-ai 模型目录（1241 个模型）识别上下文、输出上限、思考档位与附件能力。
- 可一键把供应商与模型写入 DSH 模型配置。
订阅制平台（如部分 Coding Plan）无「余额」概念时，界面显示各时间窗口剩余比例与重置倒计时。
提醒与界面¶
七类告警可推到右下角：余额不足、配额将尽、配额即将重置、查询失败、插件更新等；告警有服务端冷却、状态落盘、客户端记忆三层去重。
统计页支持时间范围与模型多选筛选，趋势图与占比环形图联动；明细表可按模型 / 来源 / 项目 / 供应商 / 账号 / 日期切换。占比图与趋势按模型名合并（跨供应商），明细表仍按供应商拆分，两套合计一致。界面跟随 DSH 语言设置（中文 / English），运行时切换即时生效。
HTTP 接口与自更新¶
插件在宿主进程内提供 API，端口随 DSH。统计页有对应入口，也可直接调用，例如聚合快照：
| 方法 | 路径 | 作用 |
|---|---|---|
GET |
/api/dsh-token-metrics/summary |
聚合快照 |
GET |
/api/dsh-token-metrics/flush |
立即落盘并返回最新快照 |
POST |
/api/dsh-token-metrics/rebuild |
从会话日志重算全部统计 |
手动重算示例（端口以你本机 DSH 为准）：
curl -X POST http://127.0.0.1:53414/api/dsh-token-metrics/rebuild
右上角版本号可点击检查更新；支持自更新、安装与热重载，失败可回滚。插件为零运行时依赖，无需 npm install 构建。
安装与启用¶
在 DSH 里执行（路径换成你本地的插件目录）：
plugin_manager install_bundle /path/to/dsh-token-metrics
或手动写入 profile 的 package.json：
{
"dsh": { "profile": { "bundles": ["dsh-token-metrics"] } },
"dependencies": { "dsh-token-metrics": "link:/path/to/dsh-token-metrics" }
}
重启 DSH 后，侧边栏会出现「Token 用量统计」图标。首次打开页面会自动回扫历史会话日志补算用量，需等待数秒到十几秒（视会话数量而定）。
典型用法¶
- 安装并重启后，从侧边栏打开「Token 用量统计」，等待首次回扫完成。
- 在顶部切换「今日 / 近 7 天 / 全部」，用模型下拉多选缩小范围，查看指标卡、趋势图与明细表是否联动。
- 切换到「模型接入」页签，配置中转站或官方平台，查看余额、配额与重置倒计时；需要时在
cordis.patch.yml中调整告警阈值等配置。 - 若与官方账单对不上，以官方账单为准；本地统计用于趋势与归因。切换账号后，历史用量无法从日志回溯账号，会归为「未知」。
常用配置 override 示例（注意：同 id 的 override 会整体替换 config，改几项需写全或只写要改的项）：
- id: token-metrics
config:
showSessions: true
snapshotCacheMs: 5000
更多项见仓库 README 配置表（如 retentionDays、trackAccount、alertThresholds.* 等）。
适用场景与注意¶
适合谁：长期在 DSH 里混用多模型、多供应商的开发者，需要本地汇总 token、粗算成本、盯余额与配额，且希望数据留在本机会话日志链路内。
权限与安全：插件以当前 DSH 进程权限运行，会读取会话日志与（默认开启的）当前登录账号只读信息；安装前请自行查看 GitHub 源码 与 MIT 许可证，确认符合你的合规要求。
平台：不调用 shell，路径用 node:path 拼接，文档标明 macOS、Windows、Linux 与 Web 端 DSH 可用。
生态说明：DSH 采用「一切皆插件」的扩展方式；SkillHub 目录页 为社区收录，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-token-metrics 把 Harness 侧每一次模型调用的 token、估价和供应商状态集中到一块面板，并支持多维度拆分与本地日志回扫。若要安装或查完整配置与 FAQ，可看目录页 skillhub.cn/plugins/hugoyee75-cmyk/dsh-token-metrics 与仓库 github.com/hugoyee75-cmyk/dsh-token-metrics。
