dsh-balance-guard：DeepSeek 賬戶餘額實時監控與預警插件

前言¶

在使用 DeepSeek Harness（DSH）開發智能體時，API 賬戶餘額是持續消耗的資源。手動查看餘額通常需要登錄網頁控制台，中斷開發流程。dsh-balance-guard 插件解決了這一問題，它通過 Host 端代理和 Client 端渲染，將餘額狀態直接嵌入到 Web 界面的會話頭部右上角。

插件簡介¶

本插件由 bunipai 維護，採用 MIT 許可證。它通過讀取與 llm-deepseek 相同的憑證（默認 DEEPSEEK_API_KEY），調用 DeepSeek 官方接口獲取餘額信息，並實時展示在界面中。

核心功能¶

• 界面集成：在 Web 界面會話頭部右上角顯示餘額膠囊。
• 自動刷新：客戶端默認每 30 秒輪詢一次；點擊膠囊立即刷新；頁面重新可見時也會刷新。
• 詳細信息：懸停顯示總額、贈送、充值明細與更新時間。
• 低餘額預警：餘額 ≤ 閾值（默認 ¥5）時，膠囊變橙並顯示 ⚠，頁面標題加「⚠ 餘額不足」前綴，並彈窗系統通知。
• 通知規則：低餘額事件只提醒一次，充值恢復到閾值以上後再次跌破會重新提醒。
• 首次授權：第一次點擊膠囊會請求系統通知授權。

安裝與啓用¶

使用官方安裝命令：

dsh plugin --profile web add dsh-balance-guard

安裝後，運行中的 web 進程會熱加載 patch 變更，刷新頁面即可看到餘額膠囊。

配置¶

在 profile cordis.patch.yml 中添加插件行配置，支持自定義參數：

- insert:
    - id: plugin-balance
      name: dsh-balance-guard
      config:
        apiKeyEnv: DEEPSEEK_API_KEY
        baseURL: https://api.deepseek.com
        pollIntervalMs: 30000
        cacheMs: 15000
        timeoutMs: 10000
        lowBalanceThreshold: 5
        lowBalanceCurrency: CNY

也可以在 $DSH_HOME/settings.yaml 中以 plugin-balance: 節覆蓋部分配置項（如 pollIntervalMs、lowBalanceThreshold 等）。

注意事項¶

• 插件以當前 dsh 進程權限運行，需確保服務端能讀取到正確的憑證。
• 錯誤碼包括：no-api-key、invalid-api-key、api-error、transport-error、bad-response。