前言¶
DeepSeek Harness（DSH）是一個插件化的智能體開發框架。在日常使用中，監控官方 API 餘額和 Token 消耗量是剛需。現有的方案往往需要額外的後臺進程或跨域調用，不夠輕量。這個插件通過原生側邊欄集成，直接讀取 DSH 的會話日誌來聚合 Token 使用數據，並實時查詢官方餘額。
這是什麼¶
這是一個輕量級的 DSH 側邊欄插件，由 lurejewel 維護，採用 MIT 許可證。它不依賴獨立的守護進程或數據庫，完全利用 DSH 現有的安裝環境和憑證服務。主要功能是展示官方 DeepSeek 餘額以及基於本地會話日誌的 Token 使用歷史。
核心功能¶
該插件包含以下核心能力：
- 官方餘額查詢：利用 DSH 已有的
DEEPSEEK_API_KEY直接向api.deepseek.com/user/balance發起請求。API 密鑰永遠不會存儲在瀏覽器中，所有調用均在服務器端完成。 - Token 使用歷史：掃描
$DSH_HOME/sessions目錄下的日誌文件，按天聚合輸入、輸出和緩存 Token 數據，支持展示今日總量、每日平均值和緩存命中率。 - 側邊欄集成：在左側邊欄底部註冊觸發器。展開時顯示標籤，收起時顯示圖標。點擊後通過模態框展示數據。
- 一鍵充值：在刷新按鈕旁提供“充值/Top up”按鈕，點擊後直接打開官方計費頁面。
- 零 footprint：無守護進程，無額外配置，無數據庫。所有數據均來源於當前的 DSH 安裝。
安裝與啓用¶
在安裝前，請確保環境滿足以下版本要求：
| 組件 | 最低版本 |
|---|---|
| DeepSeek Harness | >= 0.1.0-rc.7 (實測 0.1.5-rc.2) |
| Node.js | >= 20 |
| pnpm | >= 10 |
執行以下命令安裝插件：
dsh plugin --profile web add dsh-usage-plugin
安裝後需要重啓 dsh web 進程才能生效，隨後在瀏覽器中硬刷新（Cmd/Ctrl + Shift + R）即可在左側邊欄底部看到使用量圖標。
典型用法¶
插件通過側邊欄面板與後端 API 交互。
側邊欄操作¶
- 刷新：點擊圖標或刷新按鈕獲取最新數據。使用
fresh=1參數可繞過短時的結果緩存。 - 充值：點擊充值按鈕跳轉至官方充值頁面。
API 接口¶
插件暴露了兩個 HTTP 接口，與 DSH 的其他 /api 接口共享進程級 Token 鑑權：
- 查詢餘額：
GET /api/dsh-usage/balance
- 查詢統計：
GET /api/dsh-usage/stats?days=N
其中 `N` 爲查詢天數，默認 7，範圍限制在 1 到 90 之間。
適用場景與注意¶
該插件適合需要在開發或使用過程中頻繁查看餘額和 Token 消耗量的 DSH 用戶。
注意事項：
1. 數據源安全：餘額查詢發生在服務器端，密鑰不會暴露給前端；Token 歷史僅讀取本地日誌，不涉及第三方網絡調用。
2. 性能優化：會話日誌掃描在 Worker 線程中運行，不會阻塞 DSH Web 服務器的主事件循環，防止健康檢查誤判服務宕機。
3. 版本兼容：需要 DeepSeek Harness 版本 >= 0.1.0-rc.7。
結尾¶
該插件通過原生側邊欄的形式，解決了餘額查詢和歷史 Token 統計的痛點，且保持了零配置的輕量化特性。相關源碼與安裝詳情可訪問插件倉庫。
