前言¶
在 DeepSeek Harness（DSH）里跑智能体，token 会分散在多段会话、多种模型和缓存读写路径里。单靠印象或厂商账单，很难对照「哪几次调用花了多少、预算还剩多少」。社区维护者 xkzdwb 的 DSH-UsageStats-WhenNeedOverview（包名 dsh-usage-stats）在 DSH Web UI 侧边栏增加用量统计入口，把 harness 写入会话日志的 usage 折成 KPI、时间线和单会话明细，并按你在配置里填的单价重算费用。数字来自 ~/.dsh/sessions/**/session.v4.jsonl.zstd，不是面板内估算；Host 与 Client 分别只用 Node 内置模块和浏览器已有的 react，没有额外 npm 依赖。
这是什么¶
- 仓库与目录：GitHub，SkillHub 分类为客户端插件。
- 维护者：xkzdwb。
- 版本与许可（资料原文）：
1.0.0，MIT；要求 Node>=20。 - 定位：给 DSH Web UI 加用量统计面板；另提供只读 JSON 路由，便于 curl 或自建监控对接。
装好后侧边栏在「插件」「定时」之后多一个柱状图标，点开主栏即仪表盘。面板每 5 秒轮询（CPU 走势依赖此间隔）；点「刷新」会强制重读全部会话日志。
面板能力¶
下面按 README 中的区块说明（时间范围按钮：全部 / 24h / 7d / 30d 只影响面板显示；预算 KPI 始终按 budgetPeriod 计算，不受范围按钮影响）。
| 区块 | 内容 |
|---|---|
| 四个 KPI | 总 token（含输入/输出/缓存拆分）、会话数、模型调用次数、预估费用；第四格为预算进度 |
| Token 用量时间线 | 按小时堆叠柱（跨度超过 7 天按天）；缓存读取 / 输入 / 输出；绿线为每桶费用 |
| 按模型 | 每个 provider/model 的调用数、token、费用、相对花费条 |
| CPU 活动 | 进程与系统 CPU、进程内存、运行时长，约 90 个采样点的走势 |
| 会话明细 | 每会话调用数、token、费用、最后活动时间；可搜索、排序 |
面板右上角语言：自动 / 中文 / EN（默认跟随 Harness 或浏览器；选择写入 localStorage 的 dsh-usage-stats:lang，仅影响本面板渲染，不重新拉数）。
数据从哪来、怎么计费¶
Harness 每轮把 assistant/message 事件的 usage 写入会话日志。Host 侧通过 sessionQuery 列出并读取会话，从 data.usage 取 inputTokens、outputTokens 及可选的 cacheReadTokens、cacheWriteTokens 等，用 data.message.source 的 provider/model 分组。
两点实现上容易写错、README 也单独强调：
- 总 token 含缓存读写，计费必须四类 token 各乘各自单价，不能用
totalTokens乘单一价。 - 中间结果只存 token 计数、不存费用；改
pricing后历史会按新价立即重算，无需清缓存。非 live 会话在cacheTtlMs内可只折一次；live 会话刷新会重读。
对外只读路由：
GET /plugin-usage-stats/data?days=0&refresh=0
仅 GET/HEAD；响应 cache-control: no-store，不含消息正文。?refresh=1 强制重读日志；?days=7 限制最近天数（0 表示全部）。
安装与启用¶
插件以 bundle 包形态发布：package.json 的 dsh.bundle.patch 指向自带 cordis.patch.yml。要同时出现侧边栏与主栏面板，需把包列入 profile 的 bundles（方式 A）；仅插 Host 入口（方式 B）则只有 JSON 路由、没有 Web 界面。
方式 0：从 GitHub 安装（资料原文命令）¶
dsh plugin add github:xkzdwb/DSH-UsageStats-WhenNeedOverview
装完重启 DSH。Host 日志中应出现：
[usage-stats] serving GET /plugin-usage-stats/data
方式 A：作为 bundle 链进 profile（推荐，含 UI）¶
在 ~/.dsh/profiles/<profile>/package.json 增加依赖并把 dsh-usage-stats 放进 dsh.profile.bundles，且排在 @deepseek-ai/dsh-base、@deepseek-ai/dsh-web-app 之后（依赖其 webServer 与 sessionQuery）。本地开发可用 link: 指向仓库绝对路径。改配置后同样需重启 DSH。
验证路由¶
将 <DSH 的端口> 换成本机 Web 端口后执行：
curl -i http://127.0.0.1:<DSH 的端口>/plugin-usage-stats/data
期望：200、content-type: application/json、cache-control: no-store，正文为计数字段。
配置项¶
配置写在 patch 的 config: 下（完整字段见仓库 cordis.patch.yml）。价格单位为每 100 万 token。
| 字段 | 默认 | 说明 |
|---|---|---|
currency |
CNY |
币种符号或「数字 + 代码」 |
budget |
200 |
预算；0 只显示花费 |
budgetPeriod |
month |
month 本自然月；all 全部历史 |
cacheTtlMs |
30000 |
折叠缓存有效期 |
cpuSampleIntervalMs |
2000 |
CPU 采样间隔（500–60000） |
cpuHistoryLength |
90 |
走势采样点数（10–600） |
maxSessions |
2000 |
最多统计会话数 |
maxConversations |
300 |
明细条数上限，按花费降序 |
pricing.default / pricing.models |
见 README | 按 provider/model 覆盖单价 |
pricing.default 中的数值在文档中标明为占位，需按你的实付价或官方价表填写。不确定模型键名时，可先请求 GET /plugin-usage-stats/data?days=0，用返回里 byModel[].key 对照填写 pricing.models。
示例形状：
pricing:
default:
input: 2
output: 8
cacheRead: 0.5
cacheWrite: 2
models:
some-provider/some-model:
input: 1
output: 4
cacheRead: 0.25
cacheWrite: 1
典型用法¶
- 日常看板：重启 DSH 后从侧边栏打开面板，用 24h / 7d 等按钮切换视图，用「刷新」对齐最新日志。
- 脚本拉快照：用 curl 访问
/plugin-usage-stats/data，必要时加refresh=1或days参数。 - 改价后复盘：只改 patch 里
pricing，无需清缓存，历史费用按新价重算。 - 离线自测（不必安装 DSH）：在仓库目录执行
node test/run-tests.mjs（不读~/.dsh、不联网）；资产检查可执行node tools/check-assets.mjs。
适用场景与注意¶
适合：已在 DSH Web UI 里长期使用、需要对照真实会话日志看 token、费用、预算和 CPU 的开发者。
排错摘要（来自 README）：
- 侧边栏无图标：未按方式 A 装入
bundles（缺dsh.client则只有路由）；或未重启。 - 面板空转：确认 Host 日志有
serving GET /plugin-usage-stats/data，且 profile 包含提供webServer的官方 Web bundle。 - 费用异常：检查
pricing占位价与byModel[].key是否匹配。 - 数字滞后：点「刷新」或
?refresh=1；非 live 会话受cacheTtlMs影响。
边界：时间线按 UTC 整点分桶；预算周期仅「本自然月」与「全部」；会话数含子代理会话；金额宿主侧四舍五入到 4 位小数。
安全与信任：插件随当前 DSH 进程权限读取 ~/.dsh 下会话日志并注册 HTTP 路由。安装前请自行审阅 仓库源码 与 MIT 许可证。DSH 社区插件目录（如 SkillHub）为独立站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
DSH-UsageStats-WhenNeedOverview 把 harness 已落盘的 usage 转成可读的 Web 面板与一条只读 JSON API，费用由配置价驱动、改价即可重算历史。需要入口与细节时，可查阅 SkillHub 目录页 与 GitHub 仓库。
