前言¶
DeepSeek Harness（DSH）採用插件化架構，允許開發者通過擴展功能來定製工作流。在 Web profile 中，開發者需要實時監控 API Key 的賬戶消耗。傳統的命令行輸出方式不夠直觀，dsh-balance-view 插件通過在輸入框上方掛載常駐面板，解決了這一問題。
插件定位¶
dsh-balance-view 是一個 DeepSeek Harness 插件，由維護者 luhaifeng666 開發，屬於“聯網工具”分類。它旨在解決開發者需要頻繁查看賬戶餘額的問題，通過常駐面板和實時更新機制，提供直觀的餘額展示。
核心功能¶
該插件主要提供以下能力：
- 餘額查詢：查詢當前 DeepSeek API Key 對應賬號的賬戶餘額。
- 常駐面板：在輸入框上方展示餘額信息，不會遮擋對話內容。
- 實時更新：支持多種刷新觸發機制，確保數據儘可能貼近實時：
- 掛載時：面板首次出現時查詢一次。
- 回合結束：每輪對話結束後自動刷新。
- 定時輪詢：面板可見期間每 5 分鐘兜底刷新。
- 手動刷新：面板右側提供 ⟳ 按鈕供用戶隨時刷新。
- 命令支持：支持輸入
/balance命令查看餘額。
安裝與啓用¶
安裝該插件需要通過 DSH 的命令行工具進行。請確保你已安裝 DSH 並配置好 profile。
# 從 npm 安裝（推薦）
dsh plugin --profile web add dsh-balance-view
# 或從 GitHub 安裝
dsh plugin --profile web add github:luhaifeng666/dsh-balance-plugin
# 或從本地目錄安裝
dsh plugin --profile web add ./dsh-balance
安裝完成後，需要重啓 dsh 進程使插件生效。你也可以替換 --profile 參數爲其他 profile 名稱（如 desktop）。
使用方法¶
安裝並重啓後，插件會自動在輸入框上方加載面板。
- 查看餘額：輸入
/balance並回車，會在對話流中顯示當前的餘額信息。 - 手動刷新：點擊面板右側的 ⟳ 圖標，圖標旋轉時表示正在刷新，刷新完成後顯示最新余額。
- 關閉面板：點擊面板右側的 × 圖標可手動關閉面板。
實現與設計¶
該插件在實現上分爲 Host 側和 Client 側：
- Host 側 (
index.js)：註冊/balance命令，讀取憑據服務中的DEEPSEEK_API_KEY，請求https://api.deepseek.com/user/balance接口，並將結果作爲命令文本返回。Host 側不寫入會話日誌，也不註冊投影。 - Client 側 (
client.js)：向conversation.input.dock槽位注入面板組件，餘額數據存儲在組件本地 state 中。自動刷新和手動刷新均通過ctx.remote.commands.execute(sessionId, "/balance")觸發 Host 查詢。
設計說明：爲何不寫入會話日誌¶
原版插件曾嘗試將餘額變化寫入會話日誌（session.append("balance/change", ...)）。這會導致 DSH 默認啓用的 session-persistence-jsonl 持久化層在恢復會話時報錯，因爲 balance/change 是自定義事件，不在已知事件表中。此外，高頻的輪詢和刷新會嚴重污染會話日誌。
本插件改爲“命令返回文本 + 面板本地 state”的模式：餘額僅做一次性查詢，不進會話日誌。代價是自動刷新會以 /balance 命令節點的形式出現在對話流中，但這不會進入模型上下文，也不會影響 KV cache。
適用場景與注意事項¶
該插件適合所有使用 DeepSeek Harness 進行開發或對話的用戶，特別是需要精確控制 API 消耗的場景。
注意事項：
* 插件以當前 dsh 進程的權限運行，請確保安裝來源可信。
* 由於不寫入會話日誌，關閉面板後若不刷新，面板上的餘額可能不會反映最新的扣費情況（需依賴回合結束或輪詢機制）。
結語¶
dsh-balance-view 通過常駐面板和合理的刷新策略，爲 DSH 用戶提供了便捷的餘額監控手段。若需查看更多詳情或提交 Issue，請訪問 GitHub 倉庫。
