前言¶
在管理多个 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 错误时，它会自动冷却并切换到下一个。
核心功能¶
该插件主要提供以下能力：
- 多 API Key 池：以
{baseUrl, apiKey}作为条目主键。同一个 Key 重复添加会原地更新配置，不同 Key 则作为新的订阅。你可以同时管理任意多个 OpenCode Go 订阅，无需遵循特定的命名约定。 - 官方余额/用量查询：插件会调用 OpenCode Go 网关原生的
GET https://opencode.ai/zen/go/v1/usage接口。这允许在无需 Org Token 的情况下，实时获取官方的 rolling (5h)、weekly (周) 和 monthly (月) 三重限额的用量百分比与精确重置时刻。美元数值为换算参考值（百分比 × 限额），并非官方原始金额。 - 余额驱动热切换：路由决策优先使用缓存的官方用量压力数据（
remotePressure、usageRemote，缓存 TTL 为 5 分钟）。在发起模型请求前，若官方用量数据过期，系统会非阻塞地刷新余额，选出余量最大的订阅。如果请求失败（429、5xx 或超时），该 Key 会被冷却 60 秒，并自动尝试列表中的下一个 Key。 - 设置页 UI：在 DSH 设置中进入「LLM API 池」页面，可以添加、删除、启用或停用条目，并探查模型列表。每张卡片独立展示官方限额（进度条 + 换算美元 + 重置时刻）以及当前的路由预览。
安装与启用¶
通过 DSH 的官方 CLI 进行安装。安装过程会自动处理依赖、挂载 Host 半和 Client 半。
dsh plugin --profile web add dsh-llm-api-pool
安装完成后，插件会自动注册相关的路由和 Provider。
使用方法¶
安装并启动插件后，可以通过以下方式使用：
-
通过设置页管理：
- 打开 设置 → 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），你会看到第二张卡片，各自独立管理余额。后续的模型请求会自动优先路由到余量最大的订阅，失败时自动切换。
-
通过 CLI 工具：
插件提供了丰富的命令行工具，可用于脚本化操作：llm_pool_list/llm_pool_add/llm_pool_remove/llm_pool_updatellm_pool_probe/llm_pool_usage/llm_pool_limits/llm_pool_route/llm_pool_chat/llm_pool_balance
工作模式¶
插件提供了两种接入方式，以适应不同的使用场景：
-
作为 DSH 原生 Provider 使用（零配置）：
插件装载后会自动向 DSH 注册一个名为 LLM API Pool (余额热切换) 的模型 Provider。- 模型选择器：模型列表为池内所有条目探查到的模型并集。选中任意模型即走池路由，余额热切换自动接管。
- 参数支持：模型选择器会自动出现
reasoning effort选项（low/medium/high/max），选择后会透传给 opencode go 网关（reasoning_effort）。 - 模型设置：在模型设置页，该 Provider 会显示为已就绪，无需手动填写 baseUrl 或 apiKey（均来自池）。
- 空池处理：池为空时，Provider 的模型列表为空；添加第一个 Key 后自动出现。
-
作为 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 用户。
