stone100010/dsh-token-gauge

dsh-token-gauge

一个用于 DeepSeek Harness Web GUI 的实时 token 计量器：三个仪表盘，悬浮在应用之上，可拖拽到任意位置，并记住你放置的位置。

test
npm
license
DSH

它显示什么

| 仪表盘 | 刻度 | 读数的含义 |
|---|---|---|
| Token 用量（左） | 0 – 300M | 整个会话日志中的累计 token 数。指针爬入琥珀色区间意味着模型读取的上下文远超它产出的内容——通常表明会话已增长到超出模型良好处理的范围。 |
| tok/s（中央，最大） | 0 – 500 | 解码吞吐量，根据页面自身的观测（每秒新增的输出 token）测量，空闲时回退到会话记录的平均值。读数不稳定是后端不稳定的征兆。 |
| 总成本（右） | 0 – $12 | 基于参考 token 定价，对照预算估算的花费。 |

每个仪表盘都带有真实刻度，配有绿 / 琥珀 / 红警示区间、指针、表盘内的大号数字，以及下方印出的细节信息（In / Out 拆分、会话平均值、预算）——就像汽车仪表盘那样一目了然。

每个数字都来自 Web 客户端已经接收的会话投影（tokenUsage、contextPressure、contextBreakdown、sessionStats）。该插件不添加任何会话事件、工具或模型可见内容：它是一个只读视图，因此不会影响对话。

要求

- 运行 web 配置文件的 DSH（dsh web 或 npx @deepseek-ai/dsh web）。
- 本插件的开发和测试基于 DSH 0.1.5-rc.2。该插件使用 ctx.sessions、ctx.slots 以及四个投影键；如果某个 DSH 版本重命名了其中任何一项，则需要在此处进行相应更新。

安装

配置文件自带的插件管理器（需要 PATH 中有 pnpm）：
dsh plugin --profile web add @stone100010/dsh-token-gauge

如果 pnpm 不可用，或者 dsh 本身不在你的 PATH 中——这在通过 npx 启动 DSH 时很常见，因为其 bin 目录永远不会进入交互式 shell——请使用随附的辅助脚本，它们会自行定位 dsh，并手动完成同样的链接与注册工作：

git clone https://github.com/stone100010/dsh-token-gauge.git
cd dsh-token-gauge
./setup.sh install      # symlink into ~/.dsh/profiles/web + register the bundle row
./setup.sh verify       # 组装 profile 树并确认插件可解析
./restart-and-verify.sh # 重启 dsh web，捕获启动令牌，确认其已加载

是从 npm 安装的？setup.sh 随 tarball 一起发布，但如果你还想要 restart-and-verify.sh，请从克隆的仓库中运行它——npm 只安装运行时文件。

无论哪种方式，打开服务器打印的带令牌 URL，并强制刷新（Ctrl+Shift+R）一次：客户端 bundle 在页面加载时载入。

面板出现在右下角。拖动其标题栏可移动它，拖动右下角可调整大小，使用标题栏控件可将其折叠。位置、大小和折叠状态按浏览器持久保存。

如何挂载

面板注册到 shell.overlay —— 由 @deepseek-ai/dsh-client-ui-layout 声明的、横跨整个框架且可点击穿透的 list 座位。在那里贡献是追加式的（在已发布的条目旁新增一个 id），并且该层可点击穿透，因此面板绝不会阻挡下方的应用。

T0  panel root                                       .td-root
├─ A   header (drag handle)                          .td-header
│  ├─ A1 grip · A2 title · A3 feed indicator · A4 route+session readout · A5 collapse
├─ B   dial cluster                                  .td-gauges
│  ├─ B1 Token Usage (small)
│  ├─ B2 tok/s (large)
│  └─ B3 Total Cost (small)
├─ D   empty state (only while no projection has arrived)
└─ E   resize corner                                 .td-resize

A4 是诊断行：它标明解析路由（binding、scope 或 unresolved）、正在读取的会话 id，以及当前输出 token 计数。当某个数值看起来不对时，这一行会说明它来自哪个会话。

配置

刻度和参考价格是 lib/client.js 顶部的常量：

const SCALE_TOKENS = 300e6;   // left dial maximum
const SCALE_RATE   = 500;     // centre dial maximum
const SCALE_COST   = 12;      // right dial maximum, also the budget
const ZONES = { tokens: [0.5, 0.8], rate: [0.6, 0.84], cost: [0.5, 0.8] }; // amber, red
const PRICES = { uncachedInput: 0.14, cacheRead: 0.0028, cacheWrite: 0.14, output: 0.28 }; // USD / M

成本刻度盘是一个估算值。 deepseek-v4.1-flash 不在 DSH 已安装的模型目录中，因此 DSH 不会为它计算成本，也就没有可读取的成本投影；默认值镜像了目录中 deepseek 系列的条目。把你网关真实的每百万费率填入 PRICES——在 $12 的刻度下，定价准确性正是让刻度盘可信的关键。刻度盘标注为 est. 正是出于这个原因。

开发

lib/client.js 是一个手工编写的 ModuleLoader bundle，而非构建产物：它保留了 DSH 客户端加载器所期望的精确外壳，并在加载时用 require() 解析其外部依赖。没有构建步骤，也没有需要安装的东西。

node test/harness.mjs        # 61 checks
测试夹具会针对忠实的替身执行真实 bundle——ModuleLoader 门面、带有 Object.is 依赖比较的 React hook dispatcher、ctx.slots 以及 ctx.sessions——覆盖注册、投影订阅、wire 形状规范化、会话切换、路由回退与重试、拖拽、调整大小、钳制、持久化和销毁。

测试中编码了两条来之不易的规则：

- 夹具必须使用 wire 形状。 投影通过 wire.view 转换发布，而 tokenUsage 会扁平化为它的四个桶（view: state => state.totals）。一个使用宿主侧嵌套形状的夹具曾让一个零值 bug 溜进了发布版本。
- 损坏的路由不能看起来是活的。 通过 useSyncExternalStore 读取 face 会在重新订阅时保留最后一个快照，因此面板会以解析后的 face 作为门控，并报告 unresolved，而不是显示冻结的数字。

重命名包会涉及 manifest、bundle id、loader 行、存储前缀以及测试预期。请使用工具而不是手动编辑——它会重写所有这些内容，并在结果不一致时失败：

node tools/rename.mjs @you/dsh-token-gauge

卸载

./setup.sh uninstall     # or: dsh plugin --profile web remove @stone100010/dsh-token-gauge

之后重启 dsh web。

许可证

MIT——参见 LICENSE。