API 密钥池 bainianlaoyao/dsh-llm-api-pool

dsh-llm-api-pool

为 opencode go 设计的 API 池：根据余额热管理切换不同 API key。

把多个 opencode go 订阅（每个 = 一个 {baseUrl, apiKey}）收进一个池，实时掌握每个 key 的官方用量/余额，并按「余量最大者优先」自动路由模型请求；一个 key 用满或失败时，自动热切换到下一个。

核心能力

- 多 API key 池：条目主键 = {baseUrl, apiKey}。同一个 key 重复添加 = 原地更新配置；不同 key = 新订阅。同时管理任意多个 opencode go 订阅，无需命名约定。
- 官方余额/用量查询（纯 API Key，无需 org token）：对每个 opencode 条目调用网关原生 GET https://opencode.ai/zen/go/v1/usage，返回官方 rolling（5h）/weekly（周）/monthly（月）三重限额的用量百分比与精确重置时刻。美元数值 = 百分比 × 限额 的换算供参考，不是 opcode 官方返回的原始金额。
- 余额驱动热切换：路由决策优先使用官方用量压力（remotePressure，usageRemote 缓存 5 分钟 TTL）；模型请求前若官方用量过期则非阻塞刷新，选出余量最大的订阅；失败（429/5xx/超时）冷却该 key 60 秒并自动尝试下一个。
- 设置页 UI：设置 →「LLM API 池」：添加/删除/启停条目、探查模型、每张卡片独立展示官方限额（进度条 + 换算美元 + 重置时刻）、路由预览。

安装

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

包声明了 dsh.bundle.patch + dsh.client，dsh plugin add 会：
1. 把包加入 profile 依赖；
2. 发现 dsh.bundle.patch → 自动把 dsh-llm-api-pool 追加进 dsh.profile.bundles；
3. 启动时合成 cordis.patch.yml：host 半（池管理 + /llm-pool/api JSON 路由 + /llm-pool/v1 OpenAI 兼容端点 + DSH 原生模型 provider 自动注册）挂进 host 组合；dsh.client 声明让 client 半（设置页）被 web shell 装载。

安装/挂载的机制引用自 dsh 官方 CLI 协调流程；发布包自身通过 test/smoke-static.mjs 守护 host 半的注册与路由回路，完整 Web 挂载与重启后的设置页渲染请在首次安装后核对。

使用

1. 打开 设置 → LLM API 池；
2. + 添加 API：预设选 OpenCode Go（自动填入 https://opencode.ai/zen/go/v1 与 5h $12 / 周 $30 / 月 $60 限额），粘贴 OPENCODE_API_KEY → 添加并自动探查模型列表；
3. 卡片上 「刷新限额 / 查询余额」 调用官方 /usage 端点，显示 [官方] $x.xx / $cap (p%) · 重置 HH:MM:SS（p% 为官方百分比，$ 为换算值）；
4. 添加第二个订阅（不同 key）→ 第二张卡片，各自独立余额；模型请求自动优先路由到余量最大的订阅，失败自动切换。

模型也可直接调用池工具：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。

作为 DSH 原生 provider 使用（0.1.6，零配置）

装载后插件自动向 DSH 注册一个名为 LLM API Pool（余额热切换） 的模型 provider：

- 模型选择器自动出现：模型列表 = 池内所有条目探查到的模型并集，选中任何一个即走池路由（余额热切换自动接管）；每个模型带 reasoning effort 选择器（low/medium/high/max），选择经池透传给 opencode go 网关（reasoning_effort；off 被网关拒绝故不提供，未选时用网关默认）；
- 模型设置页自动显示该 provider 行：显示为已就绪，没有任何需要填写的字段（baseUrl/apiKey 都来自池，不在模型设置里）；
- 池为空时 provider 的模型列表为空，添加第一个 key 后自动出现。

无需手动添加 provider、无需填 baseUrl/apiKey。

作为 OpenAI 兼容 provider 接入（0.1.5）

池本身暴露了 OpenAI 兼容端点，复用 DSH Web 服务端口（默认 127.0.0.1:3080），任何 OpenAI 客户端把 baseUrl 指过来即可透明享受余额热切换——apiKey 任意（路由由池内的条目决定）：

- GET http://127.0.0.1:3080/llm-pool/v1/models — 池内所有条目探查到的模型并集；
- POST http://127.0.0.1:3080/llm-pool/v1/chat/completions — OpenAI chat 输入 → 池路由 → OpenAI 输出；stream:true 时返回 SSE 流。

DSH 自身：模型设置中新增自定义 provider，baseUrl = http://127.0.0.1:3080/llm-pool/v1，apiKey 任意，模型名填池内已探查的模型（如 deepseek-chat）。

opencode CLI（官方做法：自定义 provider 覆写 baseURL，参考 opencode providers 文档）：

// opencode.json
{
"provider": {
"dsh-pool": {
"npm": "@ai-sdk/openai-compatible",
"name": "DSH LLM API Pool",
"options": {json
"baseURL": "http://127.0.0.1:3080/llm-pool/v1",
"apiKey": "any-value"
},
"models": {
"deepseek-chat": { "name": "DeepSeek Chat (pooled)" }
}
}
}
}

任意 OpenAI SDK：baseURL 指向 http://127.0.0.1:3080/llm-pool/v1，apiKey 填任意值，chat.completions.create({ model, messages }) 即走池路由。

端口跟随 DSH Web 服务（webStartup.port，默认 3080）；若改动过 Web 端口，请同步替换上文 URL。

卸载 bash
dsh plugin --profile web remove dsh-llm-api-pool

移除后池文件（见下）保留在磁盘，如不再需要可手动删除。

数据与安全

- 条目持久化在 sandboxPolicy.workspaceRoot/.dsh-llm-api-pool.json：含 API key 明文（本机文件权限保护）、官方用量缓存、本地账本。请勿将该文件提交到版本库。
- 插件在 host 进程内会向 opencode.ai / console.opencode.ai 发起只读的用量查询请求，并在你主动调用 llm_pool_chat 时向条目 baseUrl 发送模型请求。

开发与测试 bash
npm test # 静态包冒烟：mock ctx 下跑通 10 工具注册 + /llm-pool/api + /llm-pool/v1 OpenAI 端点 + DSH 原生 provider 注册/stream（20 项断言）
node ../llm-pool-test/e2e.test.mjs # 完整 E2E：39 项（T1 host / T1c provider 注册 / T1b 多订阅路由 / T2 client 渲染 / T3 live 端点 / T4 真实 key）
LLM_POOL_TEST_KEY=sk-... node ../llm-pool-test/e2e.test.mjs # 真实 key 全生命周期（增查改删 + 真实余额 + 真实 chat）

E2E 套件位于仓库外（../llm-pool-test/），守护的动态逻辑与发布包 host 半逐字一致（发布包已静态化转换并单独冒烟）。

相关插件

同一作者的其它 dsh 插件，均已收录于 dsh 插件市场：

- dsh-codex-mode —— 面向 GPT 系模型的 Codex 形状编码预设：exec_command / write_stdin / apply_patch / view_image、OpenAI Chat Completions 与 Responses 两条路由，外加图形化子代理类型。
- dsh-session-robustness —— 让长会话保持可恢复。
- dsh-bash-on-windows —— 让 Git Bash 成为 Windows 上唯一且名副其实的终端工具。
- dsh-easy-archive —— 工作区侧边栏行内两步归档会话。

License

MIT