dsh-deepseek-balance-badge

DeepSeek Harness (DSH) 的插件生態允許在客戶端側邊欄集成功能。對於需要頻繁調用 DeepSeek API 的開發者來說，實時監控賬戶餘額至關重要。dsh-deepseek-balance-badge 旨在解決這個問題，它將餘額信息嵌入 DSH 的 Web GUI 側邊欄底部。

該插件由 chenjingchun 維護，開源協議爲 MIT。其核心價值在於將餘額查詢集成到工作流中，同時保持安全性和可配置性。

核心功能¶

側邊欄常駐徽標：在 Web GUI 側邊欄底部顯示 DeepSeek 賬戶餘額。徽標支持收起態（36px 圓形）與展開態（顯示餘額數值）。
明細浮層：點擊徽標展開詳情浮層，展示總餘額、贈送餘額、充值餘額。浮層內含手動刷新按鈕。
自動刷新與設置：插件支持按固定週期自動刷新。刷新週期（pollSeconds）與宿主緩存窗口（cacheTtlSeconds）可通過“設置 → 插件 → 插件配置”裏的卡片進行調整。
安全機制：API Key 永不進入瀏覽器。瀏覽器僅訪問同源宿主路由，密鑰保留在宿主進程中。這避免了因 api.deepseek.com 不返回 CORS 頭導致的瀏覽器直連失敗問題。
多幣種支持：支持逐行展示不同幣種的餘額。

安裝與啓用¶

使用 DSH CLI 安裝該插件：

dsh plugin --profile web add dsh-deepseek-balance-badge

安裝完成後刷新頁面即可。宿主半（Host）在首次安裝後需要重啓一次應用才能生效。

配置說明¶

配置分爲兩層：

用戶層：位於 ~/.dsh/settings.yaml 的 dsh-deepseek-balance: 分節。用戶可在“設置 → 插件 → 插件配置”中直接修改，或編輯 YAML 文件。
組合層：位於 profile 的 cordis.patch.yml 裏本插件條目的 config:。這是部署者配置，包含 apiKeyRef、baseUrl 等不直接暴露給用戶的字段。

當兩層配置了同一個鍵時，用戶層生效。如果發現配置修改不生效，應先檢查是否在卡片中覆蓋了默認值。

# profile 的 cordis.patch.yml（組合層示例）
- id: dsh-deepseek-balance
  config:
    pollSeconds: 300      # 自動刷新週期（秒）
    apiKeyRef: DEEPSEEK_API_KEY
    baseUrl: https://api.deepseek.com
    cacheTtlSeconds: 10   # 宿主結果緩存窗口

卡片僅暴露 pollSeconds 與 cacheTtlSeconds。修改配置後無需重啓，宿主會即時重新解析。

使用方式¶

查看餘額：側邊欄底部會常駐餘額徽標。點擊可展開查看明細。
手動刷新：在浮層中點擊“刷新”按鈕。該操作會攜帶 ?force=1 參數，跳過宿主緩存，強制從上游拉取最新數據。
調整週期：在“設置 → 插件 → 插件配置”中修改輪詢週期。該設置會立即應用到下一次輪詢中。
後臺行爲：頁面不可見時插件會跳過輪詢以省電。頁面回到前臺且數據已過期時，會立即補拉。

行爲細節¶

單飛機制：宿主的併發輪詢會共享一次上游調用，避免刷新風暴。
錯誤處理：上游出錯時，插件會保留上次成功的數據，並在浮層內顯示錯誤碼與原因，不會清空界面。
UI 對齊：徽標採用左對齊設計，通過 CSS 技巧消除頁腳的 4px bleed，使其與下方設置行共用同一條左邊線。

開發與限制¶

宿主改動需重啓：DSH 不支持熱加載宿主半代碼，修改 src/host 相關文件必須重啓應用。
客戶端構建：客戶端 bundle 採用手寫代碼，不使用打包器。
依賴管理：node_modules/@deepseek-ai/* 等依賴指向 DSH 安裝的 junction，僅供本地測試，不會進入安裝副本。

目錄與源碼¶

該插件目前僅通過 awesome-dsh-plugin 精選列表分發。如需上架內置市場或商店，需向該列表倉庫提交 PR。

插件目錄: https://www.skillhub.cn/plugins/chenjingchun/dsh-deepseek-balance-badge
源碼倉庫: https://github.com/chenjingchun/dsh-deepseek-balance-badge