用量仪表盘 noone89A/dsh-gauge

dsh-gauge

为 DeepSeek Harness Web UI 提供精确缓存命中率、token 用量与费用估算。

官方统计行把缓存命中率四舍五入成整数——Math.round 会把 99.8% 显示成误导性的 100%。
dsh-gauge 用一位小数（可配置）的精确数值顶替它，并补充分桶 token 明细、会话用量面板，以及自动跟随 DeepSeek 官方调价的会话费用估算（使用官方 API）。

功能

- 精确缓存命中率 — cacheRead / (cacheRead + uncached + cacheWrite)，小数位可配置（默认 1），99.8% 就是 99.8%。
- 分桶明细 — 命中 / 未命中输入 token 与输出 token。写入桶为 0 时自动隐藏（opencode-go/pi-ai 适配器从不报告 cache-write，实际恒为 0）。
- 费用估算 + 调价对比 — 按实际用量 × 模型单价估算（deepseek-v4-flash / deepseek-v4-pro，自动从会话推导）。官方新价生效前显示 当前费用 + 新价费用 + 预计涨幅；生效时刻自动切换到新价。
- 按请求时刻的峰谷计价 — 估算不是“当前时刻”快照：每条 assistant 消息按自己的时间戳计价，高峰时段消耗的 token 按高峰价、闲时按折扣价，最后求和。
- 高峰时段徽标 — 北京时间 09:00–12:00 / 14:00–18:00 为 DeepSeek 峰谷定价的高峰窗口。统计行尾按当前时段显示高峰/闲时状态（切换为新价后同样按当前时段显示）。
- 用量面板 — 会话页头 ⓘ 按钮弹出面板：模型、命中率、计费输入、各桶总数（默认完整数字）、上下文占用与费用估算（含调价后对比）。
- 两行统计（官方指标 + 精确用量） — 第一行保留官方会话指标（轮/步、LLM/工具调用时长、首 token 平均、tok/s），复刻官方样式（行距刻意收紧，两行视为一个整体）；第二行是插件的精确用量（命中率、分桶、输出、费用、高峰/闲时徽标）。replaceNativeStatsLine: false 时保留官方原生行（含原生用量段）。
- 双语 & 货币自适应 — UI 为英文时文案切英文、费用按国际价目表以 USD 估算。语言与货币实时跟随，无需重启。

截图

统计行用量面板

安装

一条命令（推荐）：dsh plugin 会 pnpm add，并自动把声明了 dsh.bundle 的包加进 dsh.profile.bundles
dsh plugin --profile web add dsh-gauge

手动方式：cd ~/.dsh/profiles/web && npm install dsh-gauge，
然后编辑 profiles/web/package.json，把 "dsh-gauge" 加进 dsh.profile.bundles

重启
dsh web

输入框下方应出现精确统计行，会话页头出现 ⓘ 用量入口。

本地开发/调试：用源码安装替代——pnpm add file:C:/Object/dsh-plugin/dsh-gauge（源码改动后 npm run build 即生效，适合改 src/config.ts 的价格/高峰窗口）。

开箱即用 & 配置卡片

装完重启后开箱即用，无需任何配置：

- 输入框下方两行统计：精确缓存命中率（99.8% 就是 99.8%）、分桶明细、输出、预估费用、高峰/闲时徽标；
- 会话页头 ⓘ 用量面板：完整 token 数字、上下文占用、模型、费用与调价对比；
- 中英文文案与费用货币自动跟随界面语言。

设置 → 插件 → 可配置插件里的 dsh-gauge 配置卡片：由于当前 DSH 版本把可暴露给网页端的插件设置写死在白名单（dsh-host-apiproxy 的 WEB_SETTINGS_NAMESPACES），第三方插件需一次性把 gauge 加入白名单后卡片才会显示（步骤见“故障排查”）。不加入白名单不影响任何核心功能——不想动白名单时，也可直接编辑 cordis.patch.yml（见“配置”）。

工作原理

- 统计行注册进 conversation.composer.dock 槽位。replaceNativeStatsLine: true（默认）时以 priority: -1 注册进官方 stats cell，影子顶替原生行；false 时以 order: 1 追加为第二行。
- token 总量来自 tokenUsage 投影（@deepseek-ai/dsh-token-meter）；上下文占用来自 contextPressure。
- 费用估算翻页拉取全会话历史（sessions.history）：每条已定稿的 assistant 消息自带完成时间与 usage，按消息自己的时间戳套高峰/闲时费率（新方案）或平价（当前旧价），再求和——窗口外（“加载更早”之前）的历史同样精确计价，不会出现“命中 2 亿 token 费用却只有几毛钱”。
- 当前模型从全量历史的最后一条 assistant 消息推导（source.model；无连接面时降级用 trajectory 视图的 requestConfig.model），或通过 model 配置固定。
- 上下文压缩（compaction）后旧事件被摘要替代：费用与官方 tokenUsage 投影基于相同的事件集合，两者保持一致（压缩丢弃的用量官方同样丢弃）。

配置

普通用户通常不需要做任何配置——插件开箱即用。以下键可通过官方设置 → 插件 → 可配置插件里的 dsh-gauge 卡片可视化开启/调整——保存后立即生效，无需重启（唯一例外：replaceNativeStatsLine 决定顶替注册，需重启），也可直接写进 ~/.dsh/profiles/web/cordis.patch.yml 的 gauge 行：

| 键 | 默认 | 含义 |
| showPrice | true | 显示费用估算（统计行 + 面板） |
| showPeakBadge | true | 统计行显示北京高峰时段徽标 |
| replaceNativeStatsLine | true | 顶替官方统计行（false 保留官方原生行） |
| hitRateDecimals | 1 | 缓存命中率小数位（0–2） |
| tokenDecimals | 1 | K/M 缩写小数位（0–2） |
| panelExactTokens | true | 面板显示完整 token 总数（false 用 K/M 缩写） |
| currency | auto | auto 跟随 UI 语言（English → $ + USD 价目，其余 → ¥ + CNY 价目）；可显式写 ¥ / $ |
| model | auto | auto 从会话推导模型；或显式写模型 id |

高级项（开发者）：高峰窗口 peakHours、CNY 价目 pricePlans、USD 价目 usdPricePlans、新价生效时刻 nextFrom、闲时系数 offPeakFactor 默认值内置在 src/config.ts，普通用户无需也不应在配置文件里改动；需要调整时直接改源码 src/config.ts 里的默认常量。

~/.dsh/profiles/web/cordis.patch.yml — 扁平 loader 补丁条目
- id: gauge
config:
showPrice: true
showPeakBadge: true
hitRateDecimals: 1
tokenDecimals: 1
panelExactTokens: true
currency: auto

内置价目 & 调价：当前价（8.17 前，平峰同价）与官方新价（2026-08-17 起，峰谷计价，闲时减半）已内置在 src/config.ts（CNY 用 pricePlans，USD 用 usdPricePlans），费用估算会按每条请求的时刻自动套用高峰/闲时价，并在 nextFrom 时刻自动切换到新价。官方价目如有调整，修改 src/config.ts 的默认常量即可；官方价目没有单独的"缓存写入"桶。

费用为估算值，以官方实际账单为准。补丁条目是扁平 {id, ...} loader 条目——没有 update:/disable: 包装层，写 - update: 会被报错拒绝。若配置卡片不显示，见"故障排查"的白名单说明。

与 dsh-usage 的对比

dsh-usage（v0.1.0）与本插件同一天出现，这里基于源码做客观对比。

| 维度 | dsh-usage | dsh-gauge |
| 缓存命中率（%） | — 完全没有命中率指标，只有原始缓存 token | 精确命中率，小数位可配置（99.8% 就是 99.8%） |
| 峰谷计价 | — 无峰谷处理；内置价目为 2026-04-24 的 USD 表，2026-08-16 调价后费用估算会失真 | 按消息时间戳的峰谷计价、新旧价对比、生效时刻自动切换 |
| 粒度 | 每条 assistant 消息下的 per-turn 读数 + 设置页 Usage 页（52 周热力图、provider/模型汇总、跨会话） | 会话级统计行（顶替原生行）+ 页头 ⓘ 面板（模型、分桶、上下文占用、费用） |
| 成本核算 | replay 派生的 modelCost 投影、按生效日期计价、unpriced/无 usage 覆盖说明 | tokenUsage 投影 × 内置价目表（CNY + USD） |
| 数据源 | 持久日志 replay（跨分页/压缩） | tokenUsage/contextPressure 投影 |
| 语言 | 仅英文 | 中英双语 |
| 原生行 | 追加自己的行 | 默认影子顶替官方行 |
| 写入桶 | 单独计价 | 为 0 时隐藏 |

总结： dsh-gauge 是精度/效率仪表——官方 UI 舍掉的精确命中率、高峰时段感知、以及免维护地跟随新峰谷价的实时费用检查。两者互补，可共存安装——槽位不同、id 不同、无冲突。

故障排查

- "写入"一直是 0 — 设计如此：一些适配器从不报告 cache-write token，为 0 时隐藏该桶。未来有提供方上报时自动恢复显示。
- 费用看起来不对 — 内置价目表（改 src/config.ts 的 pricePlans/usdPricePlans）或显式设置 currency/model；费用为估算值，以官方账单为准。
- 改动没反映 — 除 replaceNativeStatsLine（决定顶替注册）外，配置保存后立即生效；若改动的是 cordis.patch.yml，需重启 dsh web。
- 设置 → 插件 → 可配置插件 里没有 dsh-gauge 卡片 — 当前 DSH 版本把可暴露给网页端的插件设置写死在 dsh-host-apiproxy 的 WEB_SETTINGS_NAMESPACES 白名单里（官方注释标注"插件自行声明"为 deferred work），不在白名单的命名空间即使已注册，describe 也不会返回，卡片因此不显示。在宿主安装里把 gauge 加入白名单后重启 dsh web：

// /node_modules/@deepseek-ai/dsh-host-apiproxy/lib/index.js
const WEB_SETTINGS_NAMESPACES = [
"agent-loop", "shell", "locale", "permission",
"ui-conversation", "ui-theme", "web-search-deepseek",
"gauge", // ← 加这一行 ];

不加入白名单不影响统计行、面板等核心功能，只是配置卡片不显示（仍可用 cordis.patch.yml 配置）。等 DSH 开放插件自注册后此要求自动消失。
- 页面无法启动 — 确认 lib/client.js 是打包后的客户端产物（运行 npm run build，产出 __ModuleLoader__.load 格式；裸 tsc ESM 输出会导致页面白屏）。

开发
pnpm install
pnpm run typecheck
pnpm test
pnpm run build

npm run build 先用 tsc 编译，再用 scripts/build-client.mjs 把客户端入口打包成 DSH client-module loader 格式。

许可证

MIT