前言¶

在管理多個 OpenCode Go 訂閱時，手動監控每個 API Key 的餘額、處理用量超額或網關報錯，會顯著增加運維負擔。DSH 插件生態提倡「一切皆插件」，dsh-llm-api-pool 正是爲此場景設計的一個工具。它將多個 OpenCode Go 訂閱聚合爲一個池，通過官方接口實時查詢用量，並基於餘額自動路由請求，實現熱切換。

插件簡介¶

dsh-llm-api-pool 是一個爲 DeepSeek Harness (DSH) 設計的 API 池插件。它由用戶 bainianlaoyao 維護，遵循 MIT 許可證。該插件解決了多 API Key 管理分散、餘額狀態不透明的問題。通過將多個 {baseUrl, apiKey} 組合收進一個池，它能在本地維護官方用量數據，並按照「餘量最大者優先」的原則自動轉發模型請求；當某個 Key 出現 429 或 5xx 錯誤時，它會自動冷卻並切換到下一個。

核心功能¶

該插件主要提供以下能力：

1. 多 API Key 池：以 {baseUrl, apiKey} 作爲條目主鍵。同一個 Key 重複添加會原地更新配置，不同 Key 則作爲新的訂閱。你可以同時管理任意多個 OpenCode Go 訂閱，無需遵循特定的命名約定。
2. 官方餘額/用量查詢：插件會調用 OpenCode Go 網關原生的 GET https://opencode.ai/zen/go/v1/usage 接口。這允許在無需 Org Token 的情況下，實時獲取官方的 rolling (5h)、weekly (周) 和 monthly (月) 三重限額的用量百分比與精確重置時刻。美元數值爲換算參考值（百分比 × 限額），並非官方原始金額。
3. 餘額驅動熱切換：路由決策優先使用緩存的官方用量壓力數據（remotePressure、usageRemote，緩存 TTL 爲 5 分鐘）。在發起模型請求前，若官方用量數據過期，系統會非阻塞地刷新余額，選出餘量最大的訂閱。如果請求失敗（429、5xx 或超時），該 Key 會被冷卻 60 秒，並自動嘗試列表中的下一個 Key。
4. 設置頁 UI：在 DSH 設置中進入「LLM API 池」頁面，可以添加、刪除、啓用或停用條目，並探查模型列表。每張卡片獨立展示官方限額（進度條 + 換算美元 + 重置時刻）以及當前的路由預覽。

安裝與啓用¶

通過 DSH 的官方 CLI 進行安裝。安裝過程會自動處理依賴、掛載 Host 半和 Client 半。

dsh plugin --profile web add dsh-llm-api-pool

安裝完成後，插件會自動註冊相關的路由和 Provider。

使用方法¶

安裝並啓動插件後，可以通過以下方式使用：

1. 通過設置頁管理：

   • 打開 設置 → LLM API 池。
   • 點擊 + 添加 API。預設選擇 OpenCode Go，系統會自動填入 https://opencode.ai/zen/go/v1 以及默認的限額信息（5h $12 / 周 $30 / 月 $60）。粘貼你的 OPENCODE_API_KEY 並添加，系統會自動探查模型列表。
   • 在卡片上點擊 「刷新限額 / 查詢餘額」，系統會調用官方接口，顯示 [官方] $x.xx / $cap (p%) · 重置 HH:MM:SS。
   • 添加第二個訂閱（使用不同的 Key），你會看到第二張卡片，各自獨立管理餘額。後續的模型請求會自動優先路由到餘量最大的訂閱，失敗時自動切換。

2. 通過 CLI 工具：
   插件提供了豐富的命令行工具，可用於腳本化操作：

   • llm_pool_list / llm_pool_add / llm_pool_remove / llm_pool_update
   • llm_pool_probe / llm_pool_usage / llm_pool_limits / llm_pool_route / llm_pool_chat / llm_pool_balance

工作模式¶

插件提供了兩種接入方式，以適應不同的使用場景：

1. 作爲 DSH 原生 Provider 使用（零配置）：
   插件裝載後會自動向 DSH 註冊一個名爲 LLM API Pool (餘額熱切換) 的模型 Provider。

   • 模型選擇器：模型列表爲池內所有條目探查到的模型並集。選中任意模型即走池路由，餘額熱切換自動接管。
   • 參數支持：模型選擇器會自動出現 reasoning effort 選項（low/medium/high/max），選擇後會透傳給 opencode go 網關（reasoning_effort）。
   • 模型設置：在模型設置頁，該 Provider 會顯示爲已就緒，無需手動填寫 baseUrl 或 apiKey（均來自池）。
   • 空池處理：池爲空時，Provider 的模型列表爲空；添加第一個 Key 後自動出現。

2. 作爲 OpenAI 兼容 Provider 接入：
   池本身暴露了 OpenAI 兼容的 API 端點，複用 DSH Web 服務的端口（默認 127.0.0.1:3080）。

   • 模型列表：GET http://127.0.0.1:3080/llm-pool/v1/models 返回池內所有模型。
   • 聊天接口：POST http://127.0.0.1:3080/llm-pool/v1/chat/completions 接收 OpenAI 格式的輸入，由池內部路由到具體的 Key，並返回 OpenAI 格式的輸出。支持流式傳輸。
   • 任意客戶端接入：任何 OpenAI SDK 或客戶端，只需將 baseURL 指向 http://127.0.0.1:3080/llm-pool/v1，並填入任意 apiKey（路由由池內條目決定），即可透明使用餘額熱切換功能。

數據與安全¶

• 持久化存儲：條目配置持久化在 sandboxPolicy.workspaceRoot/.dsh-llm-api-pool.json 文件中。該文件包含 API Key 明文，但依賴本機文件權限進行保護。請勿將該文件提交到版本控制系統。
• 網絡請求：插件在 Host 進程內會向 opencode.ai 和 console.opencode.ai 發起只讀的用量查詢請求。僅在調用 llm_pool_chat 時，纔會向條目對應的 baseUrl 發送模型請求。

卸載¶

如需移除該插件，可以使用以下命令：

dsh plugin --profile web remove dsh-llm-api-pool

卸載後，磁盤上的配置文件（.dsh-llm-api-pool.json）會保留。如果不再需要，可手動刪除該文件。

總結¶

dsh-llm-api-pool 爲 OpenCode Go 用戶提供了一個集中管理 API Key、實時監控官方餘額並自動處理故障切換的解決方案。它通過官方接口保證了數據的準確性，並提供了 UI 和 CLI 雙向的操作入口，適合需要管理多個訂閱或追求高可用性的 DSH 用戶。

相關資源：
* GitHub 倉庫
* 插件目錄頁