前言¶
用 DSH 做日常會話時，切換模型或服務商之後，常常想知道賬戶裏還剩多少額度。已有做法是另開瀏覽器、登錄對應服務商的控制檯查看，一次切換就是一次中斷。dsh-balance 把這個動作收進輸入框：餘額以小段文本顯示在 composer 的模型席位旁，選中模型後即可看到。
DSH 的理念是「一切皆插件」，這個需求也正好由一個插件承擔。下面介紹它的實現、安裝方式和注意事項。
這是什麼¶
@kkbsgg/dsh-balance 是一個 DeepSeek Harness（DSH）插件，由 kkbsgg 維護，當前版本 0.2.0，許可證爲 MIT。它做的事情一句話可以說完：在選中模型及其 reasoning effort 之後，把當前所選模型服務商的賬戶餘額，以小文本形式顯示在輸入框模型席位旁。
實現方式¶
插件分爲 host 與 client 兩半，各管一段。
Host half：一條迴環路由¶
lib/index.js 是一個 Cordis 插件，負責在 webserver 上掛載一條迴環 HTTP 路由：
GET /dsh-balance/balance?provider=<route>
路由收到請求後，先通過標準 credentials service 解析所選 provider 自己的 API key：DeepSeek 官方路由使用 llm-deepseek 配置段，自定義或其他路由使用 llm-pi-ai 的 providers 表。密鑰只在 host 進程內解析和使用，不跨越線路邊界。
拿到密鑰後，先請求 DeepSeek 風格的 GET <baseURL>/user/balance，失敗時回退到 OpenAI 風格的 GET <baseURL>/v1/dashboard/billing/credit_grants。
Client half：輸入框右側的席位¶
client/client.js 是 web 客戶端插件，向 conversation.input.right 槽位註冊一個 seat，位置緊鄰模型選擇器。它訂閱活動會話的 modelDirectories，把選中的 provider 傳給上面的路由。
渲染有一條門檻：只有當選中具有非空 id 的模型後才顯示；選擇被清空時直接隱藏文本，而不是保留一份過期的餘額。刷新策略是每 60 秒輪詢一次，點擊餘額文本可立即刷新。
安裝與啓用¶
從源碼安裝（任意 DSH profile）¶
包聲明瞭 dsh.bundle manifest，倉庫可被解析後，用標準插件命令安裝：
dsh plugin add @kkbsgg/dsh-balance
手動安裝（打包版 DSH Desktop）¶
前提是包能從 profile 的 node_modules 解析。滿足後，在 profile patch（$DSH_HOME/profiles/
- insert:
- id: balance
name: 'dsh-balance'
然後重啓應用，讓 loader 把新行組合進去。之後對客戶端 bundle 的修改，可以通過 client HMR 通道熱更新。
打包版 DSH Desktop 中，包位於應用解包後的 node_modules，並以 junction 鏈接到 $DSH_HOME/profiles/node_modules，profile loader 因此能像解析內置插件一樣解析它。
有一個已知注意點：該包是手工安裝進 pnpm 管理的 hoisted store 的，未來 profile 內的 pnpm install 可能將其剪除。如果通過插件市場安裝後餘額文本消失，需要重建這條鏈接。
響應格式與自測¶
路由返回 JSON。成功時返回餘額信息：
{ "ok": true, "isAvailable": true, "balanceInfos": [{ "currency": "CNY", "totalBalance": "110.00", "grantedBalance": "10.00", "toppedUpBalance": "100.00" }], "fetchedAt": "2026-01-01T00:00:00.000Z" }
失敗時給出錯誤碼，例如未配置密鑰：
{ "ok": false, "code": "no-api-key", "message": "no credential configured for DEEPSEEK_API_KEY" }
倉庫自帶的 smoke 測試覆蓋 host half，運行方式：
node test/smoke.test.mjs
適用場景與注意¶
適合的使用者：在 DeepSeek 官方路由與自定義服務商之間切換、希望隨時掌握餘額、又不想爲此離開會話界面的 DSH 用戶。
幾點注意：
1、插件以當前 dsh 進程的權限運行。安裝前應先檢查源碼與許可證（MIT），確認可以接受再裝。
2、聲明瞭三個 peerDependencies：@deepseek-ai/cordis ^4.0.1、@deepseek-ai/dsh-credentials ^0.1.0-rc.7、@deepseek-ai/schemastery ^3.18.1。
3、倉庫是 source of truth：當前安裝在 DSH Desktop 應用 node_modules 裏的即時副本以它爲準，改代碼後需要重新同步到已安裝副本，或者從本倉庫安裝並重建 profile 鏈接。
小結¶
經過上面的步驟，dsh-balance 會在輸入框模型席位旁常駐一段小文本，把「查餘額」從一次瀏覽器登錄壓縮成一瞥。插件源碼與文檔見 GitHub：https://github.com/kkbsgg/dsh-balance
