Introduction

In DSH (DeepSeek Harness), the built-in statistics line usually displays tok/s only after the provider reports usage and the step ends. For free gateway models, usage may not be reported, or the stream may hang midway. In these cases, developers may have difficulty determining whether the model is generating slowly or has frozen.

This plugin solves the problem by estimating directly from streaming chunks, without relying on provider-reported usage, and provides real-time, visual monitoring.

Core Features

The plugin is a DSH Web global real-time Token HUD. Core capabilities include:

  1. Real-time display: Displays model output speed for all DSH sessions.
  2. Floating window: A draggable, collapsible floating window, with position and collapsed state automatically remembered (localStorage).
  3. Status and totals: Displays cumulative output tokens and running state, and automatically corrects estimation errors.
  4. Color-coded statuses: Uses colors to distinguish running states (green/yellow/orange/blue/gray).
  5. Model aggregation: Displays DSH-wide aggregated data, including model-level cumulative output and historical peak speed.

Installation and Enablement

Install from the official plugin directory:

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

After restarting dsh web, a floating window will appear in the lower-right corner of the page.

Local development installation:

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

Note: On Windows, paths containing spaces may be mangled by dsh argument parsing; use a junction to provide a space-free entry point:
New-Item -ItemType Junction -Path C:\Users\Public\dsh-token-hud -Target <真实目录>

Configuration (Optional)

To adjust parameters, edit 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          # 空闲会话多久的清理

How It Works

The plugin consists of a Host side and a Client side.

  • Host side:
    • Real-time speed is obtained adaptively through dual channels: newer hosts use agent/assistant-stream, while older versions use assistant/chunk from session/event.
    • Tokens are estimated from characters (Chinese ≈ 1 tok/char, English ≈ 4 chars/tok) and aggregated in a rolling window to calculate tok/s.
    • Error is automatically corrected when assistant/message includes usage.
    • Cumulative output tokens and rolling-window tps historical peaks are aggregated by model (all host-side, in-memory, and reset on restart).
    • A read-only endpoint GET /token-hud/v1/stats is exposed via webServer.
  • Client side:
    • Registered in shell.overlay (official global overlay layer), polling and rendering every second.
    • Automatically pauses when the page is hidden.
    • After 5 API disconnections, displays a gray “offline” capsule.

Known Limitations

  1. Speed is an estimated value (~10% level error) and is gradually calibrated after usage reports; cache read/written tokens are not included in speed.
  2. Cumulative values are cleared after the host restarts (no persistence).
  3. The floating window displays DSH-wide aggregation; the currently open session does not affect the displayed content.

Testing

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

Information