前言¶

在 DeepSeek Harness（DSH）里，一个 provider 路由通常只能绑定一个 apiKeyEnv；dsh-llm-retry 会在同一路由、同一把 key 上重试，遇到额度类错误时往往直接失败。社区目录里也没有现成的「多 key + 多路由池」方案。下面介绍维护者 NethielChou 发布的 dsh-llm-keypool（GitHub：NethielChou/dsh-llm-keypool，SkillHub 分类：模型推理）：用侧边栏面板管理已配置的供应商/模型顺序，并在额度用尽时自动兜底切换，可选在同一供应商下轮换多把 key。

这是什么¶

dsh-llm-keypool 是 DSH 的一个 bundle 插件（npm 包名 @nethiel/dsh-llm-keypool，当前版本 0.1.3，MIT 许可证）。它在一个 Cordis 行 id llm-keypool 下同时提供：

• 图形化「轮换池」侧边栏（读写 $DSH_HOME/keypool/route-pool.json）；
• 路由池 fallback（跨供应商、跨模型按顺序切换）；
• 可选的凭据轮换（默认关闭）。

要求 DSH 内核 >= 0.2.1-rc.2，Node >= 22.12.0（见 package.json）。

核心功能¶

轮换池面板（llm-keypool）¶

从 DSH 已经配好的供应商和模型里勾选、排序，保存为轮换池；界面可查看当前路由、冷却中的供应商、最近切换记录。侧栏入口为「轮换池」（样式与「用量/余额」同类；侧栏收起时为圆形图标）。

路由池 fallback¶

池子按顺序兜底：第一条优先，当前路由额度用尽则冷却该路由并同一步自动改用下一条健康的 provider/model 重试；当前路由健康时不主动切换。保存后下一次请求即读取配置，无需重启 DSH（桌面客户端安装插件本身仍需按官方说明重启以加载客户端代码）。

只处理插件识别的额度类失败（及面板可选扩展的认证失败）；不写 session 事件、不改历史、不记录凭据值。

凭据轮换（可选）¶

同一供应商配置了多把 key 时，可在 cordis.patch.yml 中启用 keyRotate：额度用尽时把下一把 key 写入当前凭据引用（依赖 dsh-llm-pi-ai 每次请求重新解析 resolveApiKey()）。

单包单行设计¶

DSH 浏览器模块按包名识别 bundle；一个包挂多个 Loader 会触发 duplicate factory registration。因此本插件只注册一行 llm-keypool，面板与两种兜底逻辑由同一行加载。空池时面板与 route-pool 对请求无影响。

安装与启用¶

插件以当前 DSH 进程权限运行；安装前请自行查看仓库源码与 MIT 许可证。

从 GitHub 安装（README 推荐）¶

dsh plugin --profile web add github:NethielChou/dsh-llm-keypool

或在 DSH 桌面客户端「设置 → 插件」中用本地目录 / 仓库地址安装，然后重启 DSH。

从 npm 安装¶

dsh plugin --profile web add @nethiel/dsh-llm-keypool

本地 link 开发¶

git clone https://github.com/NethielChou/dsh-llm-keypool.git
dsh plugin --profile web add link:$(pwd)/dsh-llm-keypool

手动挂载等价于将目录链入 profiles/<name>/node_modules/，并在 profile 的 cordis.patch.yml 中启用 README 所述三行配置（面板与 route-pool 启用，key-rotate 默认 disabled）。

典型用法¶

先做基础安装并重启 DSH，再按下面步骤建池：

1. 点侧边栏「轮换池」；
2. 「从已配置的模型里添加」→ 选供应商、选模型 → 加入池子；
3. 用 ↑ ↓ 调整顺序（顺序即兜底顺序）；
4. 需要时勾选「认证失败（401/403）也切换」（默认仅对额度类错误切换）；
5. 点击「保存」；
6. 在「状态」中查看当前路由、冷却中的供应商、最近切换记录。

额度用尽时：当前路由进入冷却（默认 600000 ms，即 10 分钟），同一步自动切到下一条健康路由重试；maxSwitchesPerTurn 默认 3，全池冷却则本步正常失败，不会死循环。限流（429 / RATE_LIMIT）默认也会切换，但该供应商仅冷却 60 秒，避免一次瞬时限流冻结整条线路 10 分钟。

面板写入的 route-pool.json 示例：

{
  "pools": [
    {
      "name": "我的轮换池",
      "routes": [
        { "provider": "vendor-a", "model": "model-1" },
        { "provider": "vendor-b", "model": "model-2" }
      ]
    }
  ],
  "cooldownMs": 600000,
  "maxSwitchesPerTurn": 3,
  "codes": ["QUOTA", "ACCOUNT_QUOTA"]
}

codes 表示触发切换的失败类型；默认还包含 RATE_LIMIT。勾选认证失败切换会向 codes 加入 AUTH，也可在文件中写 ["QUOTA", "ACCOUNT_QUOTA", "AUTH"]。除 codes 外，插件会按中英文常见报错文案判断；特殊文案可在行配置中加 patterns。

也可不用面板，在 profile 的 cordis.patch.yml 中写 routePool（面板文件优先）。凭据轮换示例：

- id: llm-keypool
  config:
    keyRotate:
      enabled: true
      activeRef: PROVIDER_KEY_ACTIVE
      refs: [PROVIDER_KEY_ACTIVE, PROVIDER_KEY_B, PROVIDER_KEY_C]
      maxSwitchesPerTurn: 3

工作原理（简述）¶

1. 监听 agent/request-error，在配额等条件下返回 { kind: 'retry' }，agent loop 在同一步重跑并重新走 agent/request waterfall。
2. 在 agent/request 上以 { prepend: true } 注册监听器，在 next() 之后改写 provider/model，避免被会话默认模型覆盖。
3. 失败归因时 agent/request-error 仅带 provider，插件用「最近一次命中的池路由」或池中唯一 provider 匹配；只有 provider + model 同时命中池子才改写路由。

插件仅写 ctx.logger，不 append session 事件，不向 waterfall 抛异常。

适用场景与注意¶

适合：已在 DSH 中配置多条供应商/模型（或多把 key），希望在 agent 对话额度用尽或限流时自动切换，而不是手改配置或重启。

务必知晓：

1. 供应商报错需能被默认识别或配置 patterns；同一账号多 key 可能共享额度，轮换前请确认额度是否独立。
2. 换 key / 换模型会使供应商侧前缀缓存失效，切换后首轮输入 token 可能重新计费。
3. 冷却状态在内存中，重启 DSH 后清空（不影响逻辑正确性）。
4. 只覆盖 agent loop 的模型请求；ctx.llm.stream() 直连调用不受影响。
5. 面板依赖 sidebar.footer.action 与 webServer 回环端点（DSH Desktop / web profile 满足；README 列有 /api/keypool/catalog|config|status）。

卸载：dsh plugin --profile <name> remove @nethiel/dsh-llm-keypool 后重启；或行配置 disabled: true。池子文件在 $DSH_HOME/keypool/route-pool.json，可手动删除；卸载不修改凭据文件。

结尾¶

dsh-llm-keypool 补上了 DSH 在多路由、多 key 额度兜底上的空白：面板配置顺序，后台在同一步 fail over，保存即生效。DeepSeek Harness 生态强调「一切皆插件」；SkillHub（plugins/NethielChou/dsh-llm-keypool）是社区目录站点，与 DeepSeek / 幻方无官方从属关系。

• 目录页：https://www.skillhub.cn/plugins/NethielChou/dsh-llm-keypool
• 源码与完整配置说明：https://github.com/NethielChou/dsh-llm-keypool