前言¶
DeepSeek Harness (DSH) 採用插件化架構，旨在擴展 Web UI 的功能。Headroom 是一個壓縮代理，用於減少 Token 消耗。本插件爲 DSH Web UI 提供了一個實時的令牌和成本節省儀表盤。它將 Headroom 的統計信息集成到設置頁面和聊天輸入區，幫助開發者直觀地監控壓縮效果和成本。
功能概覽¶
該插件主要包含以下能力：
- 設置儀表盤：位於 Settings → Headroom Stats。提供生命週期 KPI（節省的令牌、壓縮/緩存的成本、請求數），當前會話卡片，緩存與壓縮的成本分割條，以及 Top 10 項目表格。同時處理加載、錯誤和陳舊狀態。
- Composer 統計行：在聊天輸入框下方顯示一行數據，格式爲
Headroom: tokens saved · $ · %，刷新間隔爲 5 秒。 - 動態路徑檢測：不使用硬編碼路徑，支持跨機器使用。探測順序爲
HEADROOM_SAVINGS_PATH→HEADROOM_WORKSPACE_DIR→%USERPROFILE%\.headroom。 - 5 秒實時刷新：使用單一共享輪詢器從單個快照爲設置頁和統計行提供數據，避免重複讀取文件。
- 主題感知：使用
--dsw-alias-*設計令牌，自動適配 DSH 的淺色/深色主題。 - 存活重啓：作爲真實配置文件捆綁插件，通過
dsh.bundle配置，隨 DSH 啓動自動加載，無需每次會話重新定義。
安裝與啓用¶
安裝命令如下。該命令會將插件添加到指定 Web 配置文件中，並隨配置文件持久化。
dsh plugin --profile web add git+https://github.com/Zenjibad/headroom-stats-plugin.git
安裝後需要重啓 DSH（或進行硬刷新）以加載插件。訪問路徑爲 Settings → Headroom Stats。統計行會自動出現在聊天輸入框下方。
工作原理與配置¶
- 數據源：插件僅讀取 Headroom 代理生成的文件
~/.headroom/proxy_savings.，不進行任何寫入操作。 - 路徑解析：插件啓動時根據環境變量探測 Headroom 數據文件位置。如果未配置環境變量，則默認查找用戶目錄下的
.headroom文件夾。 - 刷新機制：使用固定的 5 秒輪詢間隔（
POLL_MS）從服務器拉取快照數據。 - 無配置文件：插件不包含配置文件，也不持久化用戶設置。所有邏輯基於當前環境變量和文件狀態運行。
注意事項¶
- 依賴運行環境：必須確保機器上運行着 Headroom 代理，且代理正在寫入
proxy_savings.文件。 - 文件缺失處理：如果找不到
proxy_savings.文件，設置頁面會顯示“unavailable + error”提示，統計行則會隱藏。 - 僅讀權限：出於安全考慮，插件僅具備讀取 Headroom 數據文件的權限，不會修改磁盤文件或進行網絡請求。
- 移除方法：若需卸載，可執行
dsh plugin --profile web rm headroom-stats-plugin並重啓 DSH。
結語¶
該插件通過將 Headroom 的統計信息可視化，填補了 DSH 在壓縮代理監控方面的空白。它不僅提供了詳細的設置頁儀表盤，還通過常駐統計行提供了即時的會話反饋，適合需要在開發過程中頻繁關注 Token 和成本節省的開發者。
