dsh-token-hud：DSH Web 全局实时 Token 悬浮窗

前言¶

在 DSH（DeepSeek Harness）中，内置的统计行通常只在“提供方上报 usage 且步骤结束后”才显示 tok/s。对于免费网关模型，经常出现不报 usage 或中途挂起的情况。这时开发者难以判断模型是在缓慢生成，还是已经卡死。

本插件通过从流式 chunk 直接估算（不依赖提供方上报）来解决这个问题，提供实时、可视化的监控。

核心功能¶

该插件是一个 DSH Web 全局实时 Token HUD，核心能力包括：

实时显示：显示 DSH 所有会话的模型输出速度。
悬浮窗：可拖拽、可折叠的悬浮窗，位置与折叠状态自动记忆（localStorage）。
状态与累计：显示累计输出 token、运行状态，并自动校正估算误差。
状态颜色编码：用颜色区分运行状态（绿/黄/橙/蓝/灰）。
模型聚合：显示全 DSH 聚合数据，包括模型级累计输出与历史峰值速度。

安装与启用¶

通过官方插件目录安装：

dsh plugin --profile web add dsh-token-hud

重启 dsh web 后，页面右下角会出现悬浮窗。

本地开发安装：

dsh plugin --profile web add link:<无空格路径>/dsh-token-hud

注意：Windows 下路径含空格会被 dsh 的参数解析拆坏；可用 junction 提供无空格入口：
New-Item -ItemType Junction -Path C:\Users\Public\dsh-token-hud -Target <真实目录>

配置（可选）¶

若需调整参数，可编辑 cordis.patch.yml：

- insert:
    - id: token-hud
      name: dsh-token-hud
      inject: [webServer]
      config:
        apiPath: /token-hud/v1     # 只读 HTTP 端点前缀
        charsPerToken: 4           # 非 CJK 每 token 字符数
        cjkTokensPerChar: 1        # 每个 CJK 字符的 token 数
        windowMs: 5000             # 速度滚动窗口
        idleTtlMs: 180000          # 空闲会话多久的清理

工作原理¶

插件分为 Host 半边与 Client 半边。

Host 半边：
- 实时速度通过双通道自适应获取（新版宿主走 agent/assistant-stream，旧版走 session/event 的 assistant/chunk）。
- 根据字符估算（中文 ≈1 tok/字，英文 ≈4 字符/tok）进滚动窗口聚合 tok/s。
- 当 assistant/message 携带 usage 时自动校正误差。
- 按模型归集累计输出 token 与滚动窗口 tps 历史峰值（均为 host 纯内存，重启清零）。
- 通过 webServer 暴露只读端点 GET /token-hud/v1/stats。
Client 半边：
- 注册进 shell.overlay（官方全局悬浮层），每秒轮询渲染。
- 页面隐藏自动暂停。
- API 失联 5 次显示灰色“离线”胶囊。

已知限制¶

速度为估算值（~10% 级误差），usage 上报后逐步校正；缓存读写 token 不参与速度。
Host 重启后累计值清零（无持久化）。
悬浮窗显示的是全 DSH 聚合，当前打开哪个会话不影响显示内容。

测试¶

node test.mjs          # host 逻辑（估算/校正/状态机/HTTP）
node test.client.mjs   # 客户端 jsdom 冒烟（渲染/折叠/持久化/离线降级）

信息¶

作者：chy007-fun
许可证：MIT
GitHub：https://github.com/chy007-fun/dsh-token-hud
目录：https://www.skillhub.cn/plugins/chy007-fun/dsh-token-hud