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:

• 模型选择器自动出现:模型列表 = 池内所有条目探查到的模型并集,选中任何一个即走池路由(余额热切换自动接管);
• 模型设置页自动显示该 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": {
        "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。

卸载

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 发送模型请求。

开发与测试

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 半逐字一致(发布包已静态化转换并单独冒烟)。

License

MIT