前言¶
用 DSH（DeepSeek Harness）Web GUI 接多家模型服務商時，查餘額是個高頻但麻煩的動作：要麼登錄各家的控制檯，要麼手動調一遍餘額接口。賬戶一多，這個動作每天要重複好幾次。
下面介紹的 dsh-balance 把這件事收進了 Web GUI：在頁面右下角放一個可拖動的餘額懸浮卡片，每 60 秒自動刷新，支持 DeepSeek / 硅基流動 / Moonshot / OpenRouter 四家的餘額接口，並在插件設置頁提供總開關。
這是什麼¶
dsh-balance 是一個面向 DeepSeek Harness Web GUI（dsh-web-ui 插件生態）的客戶端插件，倉庫路徑爲 Mystery-God/dsh-balance，許可證爲 MIT。package.json 顯示包名爲 @linxin666/dsh-balance、版本 0.1.2（包名與倉庫所有者不一致，歸屬以倉庫路徑爲準），engines 要求 node ^22.19.0 || >=24.0.0，peerDependencies 爲 react ^18.2.0。
它解決的問題很單一：把模型賬戶餘額常駐顯示在 Web GUI 裏，並且不把 API key 暴露給瀏覽器。
核心功能¶
懸浮卡片¶
懸浮卡片出現在頁面右下角，可以拖動。內容分三塊：
- 總餘額，大字顯示；
- 充值 / 贈送明細和更新時間；
- 三個操作按鈕：
⟳手動刷新、–收起成小膠囊、×關閉。關閉後會留一枚¥膠囊，隨時可以喚回。
刷新與緩存¶
插件每 60 秒自動查詢一次餘額，查詢結果在 host 側緩存 30 秒，不會頻繁打服務商接口。需要立即看最新數值時，用卡片上的 ⟳ 手動刷新。
總開關¶
「設置 → 插件 → 模型餘額懸浮窗」裏有一個「顯示餘額懸浮窗」總開關，設置持久化到 ~/.dsh/balance/settings.json。設置頁與懸浮窗共享同一份內存 store，開關切換即時生效，不用重啓。
密鑰安全¶
餘額查詢全部在 host 端發 fetch，API key 有兩種提供方式：
- 在設置頁直接填寫，存於本地
~/.dsh/balance/settings.json，接口只回傳脫敏預覽； - 經 credentials 服務解析，查找順序爲：環境變量 →
~/.dsh/.credentials.yaml→.env。
兩種方式下，key 都不會下發到瀏覽器。
多服務商¶
插件按配置的 baseURL 域名自動識別服務商，各家的餘額接口如下：
| 服務商 | 接口路徑 |
|---|---|
| DeepSeek | /user/balance |
| 硅基流動 | /v1/user/info |
| Moonshot | /v1/users/me/balance |
| OpenRouter | /api/v1/credits |
其他域名的請求會明確提示不支持，不做猜測式的兼容。
實現與安全圍欄¶
插件零運行時依賴：host 半體純 Node，瀏覽器半體純 React，無需構建，lib/ 目錄就是發佈產物。API 路由帶 loopback + same-origin 圍欄，即使部署在 LAN 暴露的環境，這些接口也不會對外提供服務。
安裝與啓用¶
通過 dsh CLI 安裝到 web profile：
dsh plugin --profile web add github:Mystery-God/dsh-balance
也可以不走路由安裝，直接改 profile 的 package.json，往 deps 和 bundles 里加條目後執行 pnpm install。
安裝後重啓 dsh web，進入「設置 → 插件 → 模型餘額懸浮窗」完成配置：填 API key（或走 credentials 服務解析），打開「顯示餘額懸浮窗」總開關，右下角就會出現懸浮卡片。
工作原理¶
倉庫裏三個關鍵文件對應插件的三個部分：
lib/index.js — host 半體：讀寫 ~/.dsh/balance/settings.json，
提供 /api/dsh-balance/* 路由（設置讀寫、餘額查詢），並向 agent 公告
lib/client.js — 瀏覽器半體：設置頁（settings.plugins.tab，總開關 + 餘額預覽）、
懸浮卡片（shell.overlay）、60s 輪詢
cordis.patch.yml — bundle patch：把插件行注入 profile 組合
本倉庫沒有 TypeScript，也沒有打包器：src/ 是手寫源碼，lib/ 是發佈產物。lib/ 需要提交，因爲 dsh 插件市場校驗安裝包時要求入口文件存在。
開發與測試¶
改完源碼後，先做構建，再做測試：
node scripts/build.mjs # 把 src/ 複製爲 lib/，無編譯步驟
node scripts/test.mjs # host 路由冒煙測試：mock 餘額接口，使用臨時 DSH_HOME
適用場景與注意¶
適合的人：在 DSH Web GUI 裏同時接了 DeepSeek / 硅基流動 / Moonshot / OpenRouter 中一家或多家，想隨時看到餘額，又不想把 key 暴露在瀏覽器端的開發者。
幾點注意：
- 插件只支持上述四家的餘額接口，其他域名會明確提示不支持，接入前先確認自己的服務商在列表內。
- 插件以當前 dsh 進程的權限運行，可以讀寫
~/.dsh/下的文件、在 host 端發起網絡請求。安裝前建議先檢查源碼和許可證（本項目爲 MIT）。 - Node 版本需滿足
^22.19.0 || >=24.0.0。
結尾¶
dsh-balance 只做一件事，但做得完整：餘額常駐可見、刷新有節奏、密鑰不下發瀏覽器、設置即改即生效，是 DSH「一切皆插件」理念下一個典型的小而完整的客戶端插件。
- 社區插件目錄頁：https://www.skillhub.cn/plugins/Mystery-God/dsh-balance
- GitHub 倉庫：https://github.com/Mystery-God/dsh-balance
目錄頁爲社區獨立站點，與 DeepSeek / 幻方無官方從屬關係。
