方式一（推荐）：直接使用 Release 附件（npm 包 tarball，含编译产物）

dsh plugin --profile web add file:dsh-gauge-0.1.0.tgz

开箱即用 & 配置卡片

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

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

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

配置

普通用户通常不需要做任何配置——插件开箱即用。以下键可通过官方设置 → 插件 → 可配置插件里的 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-usage 的对比

[`dsh-usage`](https://www.npmjs.com/package/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 不同、无冲突。