前言¶
在 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，再按下面步骤建池：
- 点侧边栏「轮换池」；
- 「从已配置的模型里添加」→ 选供应商、选模型 → 加入池子；
- 用 ↑ ↓ 调整顺序（顺序即兜底顺序）；
- 需要时勾选「认证失败（401/403）也切换」（默认仅对额度类错误切换）；
- 点击「保存」；
- 在「状态」中查看当前路由、冷却中的供应商、最近切换记录。
额度用尽时：当前路由进入冷却（默认 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
工作原理（简述）¶
- 监听
agent/request-error，在配额等条件下返回{ kind: 'retry' }，agent loop 在同一步重跑并重新走agent/requestwaterfall。 - 在
agent/request上以{ prepend: true }注册监听器，在next()之后改写 provider/model，避免被会话默认模型覆盖。 - 失败归因时
agent/request-error仅带 provider，插件用「最近一次命中的池路由」或池中唯一 provider 匹配；只有provider + model同时命中池子才改写路由。
插件仅写 ctx.logger，不 append session 事件，不向 waterfall 抛异常。
适用场景与注意¶
适合：已在 DSH 中配置多条供应商/模型（或多把 key），希望在 agent 对话额度用尽或限流时自动切换，而不是手改配置或重启。
务必知晓：
- 供应商报错需能被默认识别或配置
patterns；同一账号多 key 可能共享额度，轮换前请确认额度是否独立。 - 换 key / 换模型会使供应商侧前缀缓存失效，切换后首轮输入 token 可能重新计费。
- 冷却状态在内存中，重启 DSH 后清空（不影响逻辑正确性）。
- 只覆盖 agent loop 的模型请求；
ctx.llm.stream()直连调用不受影响。 - 面板依赖
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 / 幻方无官方从属关系。
