OpenCode Go 密钥池 Gdenich/dsh-opencode-go-key-broker

dsh-opencode-go-key-broker

DSH 插件：根据配额状态（滚动 / 每周 / 每月）自动切换 OpenCode Go 密钥 + 在 Settings 中提供单独的标签页用于管理密钥池。

为什么需要

在模型设置中，opencode-go 路由只能指定一个密钥（apiKeyEnv: OPENCODE_GO_API_KEY）。当密钥的配额窗口耗尽时，请求会因 QUOTA 失败，只能手动切换。

DSH 会在每次请求之前解析路由密钥（dsh-llm-pi-ai：prepareCall 内部的 credentials.resolve(profile.apiKeyEnv)），因此只需更改一个引用的值即可——无需改动路由、模型和适配器。

它做什么

密钥池以约定形式存储（dsh-opencode-go-usage 小部件也读取同一约定）：

OPENCODE_GO_API_KEY: sk-… # 路由实际读取的值（活动密钥） OPENCODE_GO_KEY_ACTIVE: go2 # 活动密钥的标记（小部件中的 ★） OPENCODE_GO_KEY_go1: sk-…
OPENCODE_GO_KEY_go2: sk-…
OPENCODE_GO_KEY_go3: sk-…

两条切换分支：

1. 预防性——每隔 refreshMs 通过密钥池中的每个密钥轮询 GET /v1/usage。如果活动密钥为“红色”（status !== "ok" 或 percent >= thresholds[window]），则取下一个绿色密钥并保持活动（sticky），直到它自己也变红。
2. 反应性——监听 waterfall agent/request-error。当出现 QUOTA / INVALID_CREDENTIAL 时更换密钥并返回 { kind: 'retry' }： agent 循环会重新准备请求并重新解析凭据，也就是说重试已经使用新密钥进行——在同一轮中，无需等待下一次。

写入通过 credentials.set/unset（dsh-credentials-local）进行——与 Models 页面使用相同的跨进程锁，因此手动编辑和 UI 不会互相覆盖。密钥值不会离开 Host：发送到浏览器的只有名称、掩码和百分比。

安装

从 npm 注册表：

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

从 GitHub（不使用注册表，仓库发布后即可安装）：

dsh plugin --profile desktop add github:Gdenich/dsh-opencode-go-key-broker

从源码本地安装（用于开发）：

dsh plugin --profile desktop add file:/path/to/dsh-opencode-go-key-broker

dsh plugin add 会自行将包写入 dsh.profile.bundles——依据
dsh.bundle.patch 字段。然后重启 DSH Desktop：插件列表和 boot manifest 在加载配置文件时读取。

两个值得了解的 pnpm 陷阱：

- 新发布的版本不会立即安装（发布最小年龄策略）——如果需要特定新版本，请指定精确版本：dsh-opencode-go-key-broker@0.1.1；
- desktop 配置文件中的 dsh.profile.bundles 只能手动或通过 CLI 修改：desktop 配置文件由应用程序管理，但如果 bundles 列表与交付模板不一致，应用程序会将其视为用户自定义，不会覆盖。

配置

策略位于 cordis.patch.yml（或配置文件的 override 中）：

| 键 | 默认值 | 含义 |
| enabled | true | 完全关闭代理 |
| dryRun | true | 只记录决策，不做任何更改 |
| refreshMs | 60000 | 轮询 /v1/usage 的周期 |
| timeoutMs | 15000 | usage 请求超时 |
| thresholds.{rolling,weekly,monthly} | 98 | 从百分之多少起窗口变为“红色” |
| warnPercent | 80 | 从百分之多少起显示“接近” |
| sticky | true | 留在当前密钥上，直到它变红 |
| prefer | first | 切换时选谁：first \| headroom |
| switchOnError | true | 响应式分支（同一轮内重试） |
| keyNames | 自动 | 显式指定池名称列表，而不是扫描文件 |

切换只能切换到“非红色”候选：如果其余所有密钥的窗口 ≥ 阈值、状态为 rate-limited，或者 usage 请求失败（网络/401），代理会留在当前密钥上，并在日志中写入 no-alternative。“接近”级别（warn，≥ warnPercent）不妨碍成为候选——它不是红色。

投产顺序： 保留 dryRun: true，先运行一段时间，查看 Settings → OpenCode Go Keys 选项卡中的“决策日志”（“本来会切换到 go2，因为 monthly: 96%”），然后再设置 dryRun: false。

限制器：每分钟不超过 3 次切换（防止所有密钥窗口耗尽时出现循环）。

Settings 选项卡

Settings → OpenCode Go Keys：活动密钥和状态、密钥表（掩码、★ 活动、rolling/weekly/monthly 窗口及百分比和重置剩余时间、ok/接近/限额/无数据级别）、“设为活动”和“删除”按钮、添加密钥表单和决策日志。

HTTP 路由（Host）

| 方法 | 路径 | 用途 |
| GET | /plugins/dsh-opencode-go-key-broker/snapshot?force=1 | 池状态和日志 |
| POST | /plugins/dsh-opencode-go-key-broker/activate {name} | 强制指定活动密钥 |
| POST | /plugins/dsh-opencode-go-key-broker/refresh | 立即查询 usage |
| POST | /plugins/dsh-opencode-go-key-broker/diag | 客户端诊断（写入 $DSH_HOME/opencode-go-key-broker-diag.ndjson） |

变更仅接受来自 loopback 且同源的请求。

开发

宿主测试：自给自足，但插件需要 DSH 的 peer 包，因此源码旁边必须有包含它们的 node_modules ln -sfn "$HOME/.dsh/profiles/desktop/node_modules" node_modules # 或应用 bundle 的路径
node test/host.test.mjs # 14 个代理场景
node test/client-render.test.mjs # 4 个客户端块（React 桩，无依赖）

源码修改不会自动生效：profile 将包作为 file: 依赖安装，pnpm 会把副本（硬链接）放到 node_modules/dsh-opencode-go-key-broker。修改文件后，需要要么把它们复制到该文件夹，要么重新执行 dsh plugin --profile desktop add file:。宿主代码和 cordis.patch.yml 在启动时读取——策略和宿主的更改需要重启应用；客户端 bundle 从磁盘提供，只需强制刷新页面。

限制

- 池中的密钥必须有效：无效（401）被视为“红色”。
- 轮询时的 network/timeout 不算作“红色”——否则一次网络故障就会导致从可用密钥上切走。
- 更换密钥会改变账户上下文：OpenCode Go 的 prompt-cache 绑定到密钥，因此在新密钥上的第一个请求将不会使用缓存。