前言¶

用 DeepSeek Harness（DSH）跑智能體、寫代碼、調 API，最怕兩件事：餘額不知不覺見底，用量到底花了多少卻得切出去查平臺。DSH 的 Web 界面本身專注對話與工具編排，賬戶信息並不常駐眼前。社區裏 MeteorNOX 維護的 DeepSeek Balance Whale Widget（包名 dsh-whale-widget）把一隻會 Q 彈的小鯨魚娘掛在界面右下角：餘額、今日已用、每輪對話消耗都能就地看見，打開界面自動啓用。該插件在 GitHub 上已有約 884 星，是客戶端類 DSH 插件裏關注度較高的一款。

本文基於 SkillHub 插件目錄頁 與 GitHub 倉庫 README 覈實後整理，供你在 DSH 環境裏安裝試用。

這是什麼¶

DSH 小鯨魚餘額掛件 是標準 DSH bundle 插件：隨 DSH Web 界面每次打開，在右下角常駐顯示 DeepSeek API 餘額，並附帶今日用量與每輪對話消耗統計。維護者爲 MeteorNOX，開源協議爲 MIT，當前包版本 0.2.10。

它解決的核心痛點很直接：不用反覆打開 DeepSeek 平臺查餘額，也不用憑感覺估算今天燒了多少 token；信息嵌在 DSH 界面裏，和開發流程同屏可見。

需要說明的是：DSH 社區插件目錄（如 SkillHub）由社區維護，與 DeepSeek / 幻方無官方從屬關係；安裝前建議自行閱讀源碼與許可證，插件以當前 dsh 進程權限運行。

核心功能與亮點¶

根據官方 README，掛件主要能力如下：

1. 常駐自啓：標準 DSH bundle 插件，打開 Web 界面即出現，無需每次手動加載。
2. 餘額監控：每 60 秒自動刷新；點擊鯨魚可手動刷新；餘額變化時有數字滾動動畫；短時網絡抖動會沿用最近一次餘額，避免界面報錯刷屏。
3. 今日已用（兩種模式）：
   - 小鯨魚記賬（默認，推薦）：僅需 DEEPSEEK_API_KEY，通過觀測餘額差值本地記賬（.dshw-usage.json），跨天自動歸零歸檔，免平臺會話令牌。
   - 即時·令牌（可選）：配置 DEEPSEEK_PLATFORM_TOKEN 後，調用平臺用量接口，按峯谷定價換算今日已用（2026-08-23 起週末全天按谷價）。
4. 每輪對話消耗：監聽本機會話事件，每輪對話結束後彈出本輪消耗金額（基於真實 usage，非估算）；可在菜單中開關，並自定義自動關閉秒數。
5. 交互與視覺：支持拖拽與四邊四分之一吸附；左吸附時整體水平鏡像翻轉；按壓有 Q 彈玩偶效果；懸停右上角漢堡菜單可調大小（0.6–2.5 倍）、音效、音量、用量模式等。
6. 隨機臺詞與音效：點擊氣泡可切換隨機臺詞段（含峯谷提示、賣萌吐槽等），5 秒自動收起；按壓/鬆手可選小黃鴨或音效包（缺失 mp3 時靜默降級）。

安裝與啓用¶

方式 A：從 GitHub 安裝（推薦）¶

無需本地克隆，一條命令即可：

dsh plugin --profile web add github:MeteorNOX/DeepSeek-Balance-Whale-Widget

說明：

• 安裝成功後插件會出現在 DSH 插件管理頁面，之後可在頁面內更新，不必重複敲命令。
• 若網絡需代理，可先設置環境變量再執行安裝命令。
• 安裝完成後重啓 dsh web，瀏覽器 F5 刷新。

方式 B：本地鏈接安裝¶

在倉庫根目錄（package.json 所在目錄）執行：

dsh plugin --profile web add link:.

注意：倉庫根目錄本身就是插件包，不要寫成 link:.\dsh-whale-widget（該子目錄不存在，會導致裝成普通依賴而非插件）。

方式 C：npm 發佈後安裝¶

dsh plugin --profile web add dsh-whale-widget

卸載¶

dsh plugin --profile web remove dsh-whale-widget

配置與典型用法¶

必需憑據¶

在 DSH 憑據服務中配置 DEEPSEEK_API_KEY（拉取 api.deepseek.com/user/balance 必需）。未配置時餘額區域會提示未配置密鑰。

DEEPSEEK_PLATFORM_TOKEN 爲可選：不配置時「今日已用」自動使用默認的「小鯨魚記賬」模式，開箱即用。

用量模式選擇¶

在掛件漢堡菜單 → 用量 中切換：

• 小鯨魚記賬：零額外配置，賬本寫入 $DSH_HOME/.dshw-usage.json，保留約 30 天歸檔。若 DSH 關閉期間有消耗，可能漏記；追求精確可改用令牌模式。
• 即時·令牌：需在瀏覽器登錄 platform.deepseek.com，從開發者工具 Network 中複製 usage/by_api_key/amount 請求的 Authorization 值，配置爲 DEEPSEEK_PLATFORM_TOKEN，重啓 dsh web 後選用該模式。

驗證安裝是否成功¶

dsh --profile web --dump-config | Select-String -Pattern "whale"

curl http://127.0.0.1:3080/dsh-whale/balance.json
curl http://127.0.0.1:3080/dsh-whale/widget.js

預期：dump-config 輸出中可見 dsh-whale-widget；balance.json 返回 200 且含 totalBalance；瀏覽器刷新後右下角出現小鯨魚掛件。

每輪對話消耗¶

該功能直接監聽 DSH 本機會話事件，按模型真實 usage 與內置峯谷定價表換算金額，不需要 DEEPSEEK_PLATFORM_TOKEN。在菜單中勾選「每輪對話後自動顯示消耗金額」即可；一輪對話須完整結束（turn/end）纔會結算彈出。

適用場景與注意事項¶

適合誰：

• 日常用 DSH Web 界面開發、調試智能體的開發者；
• 需要隨時盯 DeepSeek API 餘額、避免突然斷服的用戶；
• 希望在同屏看到「今天花了多少」「這一輪對話花了多少」的用量敏感型團隊。

注意事項：

1. 權限與安全：插件與 DSH 同進程運行，會讀取你配置的 API Key；安裝前請閱讀 源碼 與 MIT 許可證，確認符合你的安全策略。
2. 平臺令牌時效：DEEPSEEK_PLATFORM_TOKEN 來自平臺網頁會話，重新登錄後可能需要重新獲取。
3. 定價表維護：峯谷定價寫在 lib/index.js 的 PRICING 常量中，DeepSeek 調價時需自行跟進更新。
4. 常見問題：掛件不出現 → 確認 dsh plugin add 成功、dump-config 含 dsh-whale-widget、已重啓 dsh web 並刷新；今日已用顯示 -- → 記賬模式需先完成一次餘額觀測（60 秒內自動）；無聲音 → 檢查 assets/*.mp3 是否在包內，或接受靜默降級。

結尾¶

如果你已經在 DSH 裏泡了很久，卻總要切出去看餘額，這隻右下角的小鯨魚娘值得一試：安裝命令簡單，默認記賬模式幾乎零配置，交互細節（拖拽吸附、Q 彈、數字滾動）也把「盯餘額」這件事做得不那麼枯燥。

• 插件目錄：SkillHub - DeepSeek Balance Whale Widget
• GitHub 倉庫：MeteorNOX/DeepSeek-Balance-Whale-Widget