前言¶
做智能體開發時，DeepSeek 賬戶餘額是個繞不開的問題：餘額耗盡，調用直接失敗。常見的做法是離開當前工作環境，去平臺後臺看一眼，或者自己手動調一次 API。dsh-balance 把這件事做成了 DSH 插件：註冊一個可被代理調用的工具，同時在 Web UI 的會話輸入區常駐顯示餘額，查詢不再打斷工作流。
下面介紹這個插件的定位、功能、安裝配置和注意事項。
這是什麼¶
dsh-balance 由 qiuyongjin 維護，當前版本 0.2.0，採用 MIT 許可證。它調用 DeepSeek 的 /user/balance API 查詢賬戶餘額，同時覆蓋工具和界面兩側：headless 環境下作爲工具供代理調用，Web 環境下在會話輸入區常駐顯示。
實現上是 TypeScript 雙面開發（node half + client half），運行期零依賴——@deepseek-ai/* 依賴在構建時內聯，唯一的 peerDependencies 是 react ^18.2.0。
核心功能¶
dsh_balance 工具¶
節點側註冊名爲 dsh_balance 的工具，調用 DeepSeek GET /user/balance，返回賬戶可用狀態與各幣種餘額明細——每個幣種下分總餘額、贈送餘額、充值餘額三項。headless 和 web 兩種組合下都可用。
Web UI 餘額入口¶
Web 環境下，插件填充官方 conversation.input.right slot：一個按鈕常駐在會話輸入區，直接顯示當前總餘額；點擊展開明細卡片，內容包含可用狀態、各幣種明細和更新時間，支持手動刷新。
餘額端點¶
節點側經可選的 webServer 後端（通過 ctx.inject 等待就緒）暴露一個 JSON 端點，供瀏覽器拉取：
GET /plugins/dsh-balance/balance
瀏覽器只做同源 fetch，headless 組合下該端點不掛載。
憑據解析¶
API key 經 DSH 憑據服務解析，默認引用 DEEPSEEK_API_KEY，可以在 Web 的 Models 設置頁直接寫入；憑據服務缺席時回退到啓動環境變量。每次調用即時解析，改 key 不需要重啓，取值方式與官方 dsh-llm-deepseek 一致。
值得注意的設計：API key 只存在於節點側，瀏覽器不接觸憑據。
取消語義¶
工具執行時合併超時與調用方取消（AbortSignal.any），符合 dsh-tools 的協作取消契約。
安裝與啓用¶
先安裝插件：
dsh plugin --profile web add ./dsh-balance
bundle 層棧變更需要重啓才能生效：
dsh --profile web
啓動日誌出現下面這行即掛載成功：
[dsh-balance] plugin loaded（API key 引用：DEEPSEEK_API_KEY，基地址：https://api.deepseek.com）
重啓後，會話輸入區工具行右側（發送按鈕前）會出現 🔋 餘額入口。
配置¶
默認配置開箱即用。如需覆蓋，在 profile 的 cordis.patch.yml 按行 id 覆蓋。注意 patch 會整替換 config，覆蓋時需要重述全部鍵：
- id: dsh-balance
config:
apiKeyEnv: DEEPSEEK_API_KEY
baseURL: https://api.deepseek.com
timeoutMs: 10000
三個鍵的含義：
| 鍵 | 默認值 | 說明 |
|---|---|---|
apiKeyEnv |
DEEPSEEK_API_KEY |
讀取 API key 的憑據引用（POSIX 環境變量名） |
baseURL |
https://api.deepseek.com |
DeepSeek API 基地址 |
timeoutMs |
10000 |
請求超時（毫秒） |
典型用法¶
安裝並重啓後，有兩種用法：
- 看界面：餘額按鈕直接顯示當前總餘額，點擊展開明細卡片，需要最新數據時手動刷新。
- 問代理：在會話中向代理提問「查詢 DeepSeek 餘額」，代理會調用
dsh_balance工具返回結果。
驗證插件是否正常工作：
- 類型層面運行
pnpm run typecheck； - 在會話中提問「查詢我的 DeepSeek 餘額」，確認返回賬戶可用狀態與餘額明細。
開發與構建¶
如果需要二次開發，常用腳本如下：
pnpm install
pnpm run build # tsc 產出 lib/types + tsdown 產出 lib/index.js / lib/client.js
pnpm run typecheck # 嚴格類型檢查，單一 tsconfig 覆蓋 node + client 兩側
pnpm run watch # tsdown 增量重建 client half
lib/ 是構建產物，不要手改；改完源碼後需要重新構建。
適用場景與注意¶
適合長期使用 DeepSeek、想隨時掌握賬戶餘額的開發者，尤其是已經在用 DSH 插件機制組織工作流的人。幾點注意：
- 插件以當前 dsh 進程的權限運行，安裝前建議自行檢查源碼與許可證（本項目爲 MIT）。
- 改 API key 不用重啓（憑據每次調用即時解析），但安裝、卸載這類 bundle 層棧變更需要重啓
dsh --profile web才生效。 - headless 組合下沒有 webServer，餘額端點和 Web UI 入口不可用，只能通過工具查詢。
結尾¶
dsh-balance 解決的問題很小但很具體：讓餘額查詢變成常駐信息，不再打斷工作流。工具和界面兩側都能用，憑據留在節點側，裝一次即可。
- GitHub：https://github.com/qiuyongjin/dsh-balance
- 社區目錄：https://www.skillhub.cn/plugins/qiuyongjin/dsh-balance
社區目錄爲獨立站點，與 DeepSeek、幻方無官方從屬關係。
