在 DeepSeek Harness (DSH) 的開發或使用過程中，頻繁切換標籤頁或手動訪問控制台來查詢 API 餘額會增加操作成本。dsh-balance-whale 作爲一個客戶端插件，直接在 DSH 的 Web 界面右下角提供懸浮窗口，用於實時展示 DeepSeek API 的剩餘額度。
這是一個由 chenpengye 維護的輕量級組件。它不依賴任何外部圖片資源，通過手繪 SVG 渲染鯨魚娘圖標，並提供實時的餘額狀態反饋。插件的核心價值在於將餘額查詢集成到本地開發環境，同時通過架構設計確保 API Key 的安全性。
核心功能¶
- 懸浮展示與狀態反饋：右下角顯示鯨魚娘圖標及當前餘額。圖標旁有一個狀態點，綠色代表有餘額，橙色代表無餘額。
- 交互詳情卡片：點擊圖標可展開卡片，顯示可用狀態、各幣種總餘額、充值明細、贈送明細、最後更新時間以及手動刷新按鈕。
- 自動刷新與緩存：每 60 秒自動請求一次最新數據。Host 進程端設有 30 秒緩存，防止頻繁調用官方接口導致限流。
- 安全機制：API Key 僅在 Host 進程中從憑據庫讀取，絕不傳輸至瀏覽器。查詢接口僅監聽本機迴環請求，拒絕非本地訪問。錯誤信息經過分類處理，不透傳上游接口的原始響應體。
安裝與啓用¶
該插件是 Cordis bundle，未發佈至 npm，需從源碼安裝。
- 克隆倉庫並構建：
git clone https://github.com/chenpengye/dsh-balance-whale.git
cd dsh-balance-whale
pnpm install && pnpm build
- 將插件註冊到 Web 配置文件目錄：
cd ~/.dsh/profiles/web
pnpm add /absolute/path/to/dsh-balance-whale -w
- 在
cordis.patch.yml中添加插件 ID：
- insert:
- id: dsh-balance-whale
name: dsh-balance-whale
- 重啓
dsh web（或觸發 HMR 熱加載）並硬刷新瀏覽器頁面。
典型用法¶
無需額外配置。插件會自動複用 DSH 憑據庫中保存的 DEEPSEEK_API_KEY（即“設置 -> 模型”中配置的 Key）。安裝完成後，右下角即可看到鯨魚娘圖標。
適用場景與注意¶
適合需要在本地開發過程中快速監控 API 額度且注重隱私的開發者。插件以當前 DSH 進程的權限運行，Key 永遠不會離開本地機器。默認配置下，查詢路由拒絕非迴環請求。建議在安裝前檢查源碼與許可證。
該插件通過本地輪詢和安全的 Key 管理方式，爲 DSH 用戶提供了便捷且安全的餘額監控入口。項目代碼託管在 GitHub，遵循 MIT 協議。
