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 仓库。