前言¶
在 DSH（DeepSeek Harness）裏調用 DeepSeek、Moonshot、Kimi For Coding、OpenAI Codex（Codex Connect）、OpenCode Go 等 provider 時，餘額和套餐配額通常分散在不同接口中。手動查詢比較分散，也容易把 API Key 暴露到瀏覽器端。dsh-plugin-llm-balance 是一個 DSH 插件，在 Web GUI 頁面右上角提供一個可拖動的懸浮卡片，用於集中顯示最近使用 provider 的餘額/配額，並按閾值分檔變色。
這是什麼¶
下面介紹 FengHuoLinShan/dsh-plugin-llm-balance 的能力、安裝方式和需要注意的邊界。
- 維護者：
FengHuoLinShan - 定位：DSH Web GUI 插件
- 許可證：
MIT - 核心場景：在瀏覽器端查看 provider 餘額與配額，不向前端發送 API Key 和 OAuth token
核心功能¶
最近使用的 provider 卡片¶
插件在 Web GUI 中常駐顯示最近使用的最多 3 個 provider 的餘額/配額懸浮卡片。它只記錄插件啓用後成功完成的模型調用，顯示最近 3 個不同 provider。
餘額與配額¶
插件同時支持金額餘額與套餐配額展示，包括 5 小時、周等可用窗口及重置時間。狀態顏色按最緊張窗口計算。餘額與配額按閾值分檔變色；加載或查詢失敗時顯示灰色。
交互與刷新¶
- 卡片可拖動並記憶位置
- 點擊卡片即可刷新
- 默認每 60 秒自動刷新
- 頁面隱藏時暫停刷新，恢復可見時立即更新
DeepSeek 峯谷電價徽標¶
DeepSeek 行可顯示「低谷 / 高峯」徽標。該狀態爲純時鐘計算，不發送餘額查詢請求；tooltip 顯示時段表與距切換倒計時。
自動發現配置¶
插件合併內置 provider、llm-pi-ai.providers.* 和本插件配置，用於自動發現當前可展示的 provider。
憑據邊界¶
API Key 和 OAuth token 不會發送到瀏覽器，也不會出現在任何響應、日誌或頁面中。餘額查詢通過僅允許 loopback 權限的 Connection RPC 完成。
支持範圍¶
當前資料列出的 provider 包括：
- DeepSeek / DeepSeek Official
- Moonshot / Moonshot CN
- Kimi For Coding
- OpenAI Codex（Codex Connect）
- OpenCode Go
OpenAI Codex 依賴可選的 dsh-codex-connect，最低兼容版本爲 0.1.0-alpha.4.5。不安裝時，插件仍會運行，只是 openai-codex 如實顯示未配置。
安裝與啓用¶
先確認 DSH 版本滿足要求：0.1.0-rc.7 或更高版本。該版本引入了插件使用的 Connection RPC 獨立通道。
下面使用 GitHub 方式安裝：
dsh plugin --profile web add "github:FengHuoLinShan/dsh-plugin-llm-balance#main"
安裝完成後，需要重啓 dsh 服務，然後刷新頁面。插件集合變更需重啓 dsh 服務生效；client bundle 改動在 DSH checkout 的 pnpm run dev:web watcher 運行時可 HMR，否則需重新安裝/重啓服務並刷新頁面。
如需顯示 OpenAI Codex，另外安裝 dsh-codex-connect：
dsh plugin --profile web add dsh-codex-connect@alpha
安裝後，在其界面完成 ChatGPT OAuth 登錄。不安裝該可選依賴時，不影響其他 provider 的展示。
典型用法¶
查看卡片¶
重啓 dsh 服務並刷新頁面後，頁面右上角會出現懸浮卡片。卡片會顯示最近使用的最多 3 個 provider，並給出餘額、配額、重置時間等信息。
調整輪詢間隔¶
個性化配置在 ~/.dsh/profiles/web/cordis.patch.yml 中按行 id 覆蓋。例如覆蓋 refreshMs 爲 30000：
# 在 ~/.dsh/profiles/web/cordis.patch.yml 中按行 id 覆蓋
# 示例字段：refreshMs: 30000
# 注意：覆蓋時需完整重述該行需要的全部 config 鍵
默認輪詢間隔爲 60 秒。
自測¶
如果從源碼 checkout 獲取插件，可以運行自測腳本：
node test/balance.test.mjs
卸載¶
dsh plugin --profile web remove dsh-plugin-llm-balance
適用場景與注意¶
適合正在使用 DSH Web GUI，並希望集中查看 DeepSeek、Moonshot、Kimi For Coding、OpenAI Codex（Codex Connect）、OpenCode Go 等 provider 餘額/配額的使用者。
使用前注意：
- 插件會以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證。
- 許可證爲
MIT。 - 餘額/配額數據來自官方接口，可能略有延遲，僅供參考。
- OpenCode Go 端點目前無官方公開文檔，可能變化。
- API Key 和 OAuth token 不出服務端；不會發送到瀏覽器。
鏈接¶
- GitHub：https://github.com/FengHuoLinShan/dsh-plugin-llm-balance
- 社區目錄頁：當前資料未確認 URL，這裏不給出具體鏈接。
