dsh-opencode-go-key-broker

OpenCode Go 在 DSH 中通常只能配置一個 API Key。當該 Key 的配額窗口（rolling/weekly/monthly）耗盡，請求會報錯，需要手動更換。dsh-opencode-go-key-broker 插件通過維護一組 Key 並根據配額狀態自動切換，解決了這個問題。

插件由 Gdenich 維護，屬於模型推理類別，許可證爲 MIT。

核心功能¶

OpenCode Go API-key 池管理：支持多個 API Key 的存儲與輪換。
基於配額的自動切換：根據 rolling、weekly、monthly 配額使用率自動切換 Key。
預防性輪詢與反應式切換：主動定期查詢配額狀態，或在發生錯誤時響應式切換。
Settings 頁面管理：提供圖形界面查看 Key 狀態、手動切換及日誌。
Composer 配額徽章：在編輯器中顯示配額使用情況。
HTTP 路由：提供 snapshot、activate、refresh、diag 等管理接口。

安裝與啓用¶

從 npm 註冊表安裝：

dsh plugin --profile desktop add dsh-opencode-go-key-broker

安裝後需要重啓 DSH Desktop，以便正確加載插件列表和啓動 manifest。

工作原理¶

Key 池結構¶

Key 池通過環境變量管理，遵循以下約定（這也是插件讀取和存儲 Key 的方式）：

OPENCODE_GO_API_KEY: sk-…        # 路由實際讀取的值（當前激活的 Key）
OPENCODE_GO_KEY_ACTIVE: go2      # 標記當前激活的 Key（顯示 ★）
OPENCODE_GO_KEY_go1: sk-…
OPENCODE_GO_KEY_go2: sk-…
OPENCODE_GO_KEY_go3: sk-…

切換策略¶

插件包含兩種切換邏輯：

預防性輪詢：按照 refreshMs 配置的週期，主動查詢每個 Key 的 /v1/usage 狀態。如果當前激活 Key 的使用率超過閾值（默認 98%），會將其設爲非激活狀態，並切換到下一個狀態爲 “ok” 的 Key。
反應式切換：監聽 agent/request-error waterfall 事件。當收到 QUOTA 或 INVALID_CREDENTIAL 錯誤時，立即切換 Key 並返回 { kind: 'retry' }，Agent 會重新準備請求並使用新 Key。

限制條件¶

切換頻率：同一 Key 最多每分鐘切換 3 次，防止在所有 Key 配額均耗盡時產生無限循環。
錯誤過濾：網絡錯誤或超時錯誤不會觸發 Key 切換，避免因臨時網絡波動導致切換。
緩存丟失：更換 Key 會改變賬號上下文，OpenCode Go 的 prompt-cache 與 Key 綁定，切換 Key 後的首次請求將無法使用緩存。

配置說明¶

配置項位於 cordis.patch.yml（或 profile override）中：

配置項	默認值	說明
`enabled`	`true`	是否啓用插件
`dryRun`	`true`	僅記錄決策日誌，不實際切換 Key，建議初始使用
`refreshMs`	`60000`	預防性輪詢的間隔（毫秒）
`timeoutMs`	`15000`	查詢 usage 接口的超時時間
`thresholds.rolling`	`98`	觸發切換的配額閾值（百分比）
`thresholds.weekly`	`98`	同上，周配額
`thresholds.monthly`	`98`	同上，月配額
`warnPercent`	`80`	顯示“接近耗盡”的閾值
`sticky`	`true`	切換後保持新 Key 直到其變紅
`prefer`	`first`	切換時的選擇策略：`first` 或 `headroom`（剩餘空間最大）
`switchOnError`	`true`	是否在錯誤時觸發反應式切換
`keyNames`	auto	指定 Key 列表名稱，或自動掃描環境變量

建議在 dryRun: true 模式下觀察一段時間，確認日誌中的切換邏輯符合預期後，再設置爲 false。

HTTP 路由¶

插件提供以下 Host 接口供外部調用：

GET /plugins/dsh-opencode-go-key-broker/snapshot?force=1：獲取當前 Key 池狀態和日誌。
POST /plugins/dsh-opencode-go-key-broker/activate {name}：手動指定激活的 Key 名稱。
POST /plugins/dsh-opencode-go-key-broker/refresh：立即觸發一次配額查詢。
POST /plugins/dsh-opencode-go-key-broker/diag：輸出診斷信息到日誌文件。

注意事項¶

Key 必須有效。無效的 Key（如 401）會被視爲“紅色”狀態。
更換 Key 會丟失 prompt-cache。
安裝後必須重啓 DSH Desktop。

結語¶

該插件通過自動化 Key 輪換，降低了 OpenCode Go 在多 Key 場景下的運維成本。更多細節可參考 GitHub 倉庫。