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