前言¶
用 DeepSeek Harness（dsh）跑智能體任務時，步數、輪次、吞吐、緩存命中、上下文佔用這些數字都擠在 web UI 原有的 stats 行裏。信息在，但都是平鋪文本，長任務跑到一半想快速回答「現在吞吐多少、上下文還剩多少、緩存效率如何」，得逐個讀數。
dsh-stats-hud 解決的就是這個讀數問題：它把會話統計渲染成一塊固定在頁面最右緣的豎排面板，用等級條、速度表和滾動計數器呈現，同時不動原有 stats 行。下面介紹它的功能、安裝方式和工作原理。
這是什麼¶
dsh-stats-hud 由 lauytgary 維護，MIT 許可證，分類爲客戶端（web 端）插件。一句話定位：把 DSH 會話統計行變成遊戲風格的等級條、速度表和滾動 token 計數器，豎排顯示在 dsh web UI 最右側。它是純瀏覽器側插件，不改宿主代碼，數據全部來自宿主已有的 projections。
面板上的儀表¶
- CLOCK 徽章：本地 24h 時間，附 DS API PEAK / OFF PEAK 峯谷標識。峯值爲北京時間週一至五 09:00-12:00 / 14:00-18:00，週末恆爲 OFF-PEAK。
- STEPS / TURN 滾動里程錶：數字鼓輪樣式，掛載時上卷，數值變化時滾動，進位按 9→0 處理。
- LLM / TOOLS 雙條形：兩列布局，標籤在值上方；條形分段按原始 LLM:TOOLS 時間比例劃分，無上限，時間比例直接映射爲條形比例。
- THROUGHPUT 儀表盤：tokens/s 讀數居中顯示，紅線初始 200，按 100 tok/s 步進自動擴展。
- CONTEXT USAGE 條：按 token 比例分三段——Sys Prompt（灰）/ Tools（藍）/ Messages（紫）；佔用 ≥80% 時整條變紅；懸停彈出 tooltip，顯示三類 token 明細。
- CACHE HIT 條：<50% 紅、<80% 黃、≥80% 綠。
- CONTEXT 滾動計數器：三行里程錶——CACHE HIT（綠）/ CACHE MISSED（橙）/ OUTPUT（粉）。
agent 運行期間，整個面板有呼吸效果，條形隨之脈動。
響應式佈局¶
面板按右側空閒空間分三檔，用 ResizeObserver 即時測量：
| 檔位 | 條件 | 顯示內容 |
|---|---|---|
| full | 窗口 ≥800px 且空閒 ≥180px | 全部儀表 |
| mini | 窗口 ≥800px 但空閒 <180px | 時鐘（短 PEAK / OFF PEAK 徽章）+ 緊湊滾動行 |
| hidden | 窗口 <800px | 不顯示（display:none） |
窗口寬度 <800px 是硬性下限；測量失敗時回退到 full。mini 檔在窄窗口下可能輕微遮擋聊天列，但面板可點擊穿透，不影響操作。
安裝與啓用¶
從 GitHub 安裝：
dsh plugin --profile web add https://github.com/lauytgary/dsh_hud_plugin
或從本地路徑安裝：
dsh plugin --profile web add /path/to/dsh-stats-hud
安裝後重啓 dsh web（loader 條目在啓動時掃描），再刷新頁面，插件會出現在 Settings → Plugins。依賴要求：DeepSeek Harness dsh（在 0.1.0-rc.6、macOS 上測試過）和 pnpm（用於插件管理）。
注意一個細節：倉庫地址是 lauytgary/dsh_hud_plugin，插件名是 dsh-stats-hud，兩者不一致，卸載時用插件名：
dsh plugin --profile web remove dsh-stats-hud
工作原理¶
1、插件註冊到 conversation.composer.dock 槽位（id dsh-stats-hud，order 1）；面板本身 position: fixed，不佔佈局空間，原 stats 行保持不變。
2、數據來自宿主既有 projections：sessionStats、tokenUsage、contextPressure、contextBreakdown，零宿主側改動。
3、exports.inject = ["slots"] 是必需項：DSH 的 ctx 是嚴格代理，訪問未聲明的服務會直接拋錯。
4、整個面板 pointer-events: none，可點擊穿透；僅 CONTEXT USAGE 條恢復指針事件，以支持懸停 tooltip。
開發與測試¶
lib/client.js 是手寫的 loader bundle（window.__ModuleLoader__.load），無需構建步驟。插件以 link: 依賴安裝，本地編輯 lib/client.js 後只需重啓，不用重裝。
運行測試：
npm test
測試基於 node:test，零依賴，要求 Node ≥ 18。測試專用的 __test 導出由 DSH_HUD_TEST 環境變量控制，瀏覽器包不受影響。
如果想發佈到 npm：移除 package.json 中的 private 後執行 npm publish，之後用戶可用 dsh plugin --profile web add dsh-stats-hud 安裝。當前默認未發佈到 npm，安裝走 GitHub 或本地路徑。
適用場景與注意¶
適合長期盯着 dsh web 跑任務、希望更快讀出吞吐、緩存和上下文狀態的人。如果你只想偶爾看一眼，原 stats 行仍在，裝了插件也不破壞任何原有佈局。
兩點提醒：mini 檔在窄窗口下可能輕微遮擋聊天列（點擊穿透所以安全）；插件以當前 dsh 進程權限運行，安裝任何第三方插件前都應檢查源碼與許可證，本插件採用 MIT。
結尾¶
dsh-stats-hud 展示了 DSH「一切皆插件」的一種典型做法：不動宿主一行代碼，把已有數據換成更易讀的呈現。源碼與文檔見 GitHub：https://github.com/lauytgary/dsh_hud_plugin；也可在社區目錄查看：https://www.skillhub.cn/plugins/lauytgary/dsh_hud_plugin（社區維護的獨立站點，與 DeepSeek、幻方無官方從屬關係）。
