前言¶
在 DeepSeek Harness（DSH）里接入多个 LLM 服务商时，常见做法是分别配置渠道、在模型菜单里来回切换。会话一旦跨渠道，前缀 KV cache 往往无法复用；某条线路限流或鉴权失败后，又要手动改模型或改配置。若希望把多条真实渠道收成「一个虚拟服务商」，并在失败时自动换路、同时尽量让同一会话钉在同一条线路上，就需要在 Host 侧做统一路由与能力合并。dsh-llm-pool 是 lyingloong 维护的 DSH 插件（分类：模型推理），在当前资料中面向 DSH 0.2.1-rc.5，用会话粘性加全局负载均衡和自动切换来应对上述问题。
这是什么¶
dsh-llm-pool 为 DSH 增加「统一服务商 / 模型池」：把多个真实模型渠道组合成一个虚拟 provider，在模型选择器里像普通渠道一样选择。仓库与 npm 包名均为 dsh-llm-pool，许可证 MIT，运行时要求 Node.js ^22.19 || >=24，纯 JavaScript、无原生依赖；与 DSH 的版本约束为 >=0.2.1-0 <0.3.0-0（package.json 当前版本 0.1.1）。
插件不单独保存 provider 密钥，真实请求仍走用户已配置好的 provider route；只在 Host 内注册虚拟路由，并通过设置里的配置编辑器或 cordis.patch.yml 写入池配置。
核心功能¶
下面按资料中已写明的行为归纳，不超出 README 范围。
统一服务商与模型映射¶
- 可定义虚拟 provider（例如
pool-a），members列出有序的真实 provider（如provider-a、provider-b）。 - 在虚拟 provider 下定义统一模型 id（如
model-a），通过targets把「成员 → 实际模型 id」一一映射；省略映射时默认各成员使用与统一模型同名的实际 id。
会话粘性 + 全局均衡（默认 strategy: sticky）¶
- 新会话或子代理首次调用时，在候选成员中选当前绑定会话数最少者；相同时轮转。
- 之后该会话对同一统一模型尽量固定在同一成员，减少换渠道导致的前缀缓存失效。
- 调用失败且在尚未产生可见输出前，静默尝试下一个候选；若切换后成功，会话绑定会改到成功的成员。
分配粒度为「会话 + 统一服务商 + 统一模型」。进程重启后内存中的绑定会重置，但会话已选的 provider/model 不受影响。
失败切换与健康冷却¶
- 首 token 前失败（认证、配额、限流、5xx、超时等）：记录失败并进入冷却，尝试下一候选。
- 已有可见输出后再失败：不拼接两个渠道的回复，交给 DSH 自带的
dsh-llm-retry按 step 重试。 - 认证/配额/限流/服务端/超时等失败进入冷却；全部成员冷却时 fail-open，选最早恢复时间尝试。
strategy 还可设为 round-robin（每次调用轮询）或 failover（固定第一个可用）。
能力合并¶
对统一模型声明的能力会合并各成员：上下文窗口与最大输出默认取可用成员的最小值（可手动覆盖）；推理档位默认取交集，可用 effortMap 做统一档位到成员档位的映射；图片能力取并集。不支持当前请求能力的成员在调用时会被跳过。
配置界面与可观测¶
安装并在 设置 → 模型 页面底部打开「统一服务商池」面板后，可查看状态、编辑渠道与模型映射、测试模型；面板可显示会话分配、路由成功/失败、冷却与最近调用等信息。高级字段（推理档位映射、冷却毫秒等）可通过「高级 JSON」或 cordis.patch.yml 编辑。
安装与启用¶
推荐从 npm 安装（README 原文命令如下）。web 是 DSH 市场文档里的通用 profile 名；若 profile 名为 desktop，将 --profile web 换成 --profile desktop。
dsh plugin --profile web add dsh-llm-pool
安装后重启或刷新客户端，在 设置 → 模型 底部应出现「统一服务商池」。npm 包页：https://www.npmjs.com/package/dsh-llm-pool。
从 GitHub 安装源码时，资料给出的命令为：
dsh plugin --profile web add github:lyingloong/dsh-llm-pool
本地开发可将 --profile 与仓库绝对路径按 README 说明传入插件管理器。若环境中存在已从 npm 撤包的老插件导致 pnpm install 失败，README 建议可通过 registry 选项指定 https://registry.npmmirror.com 绕过，属安装环境问题而非本插件逻辑。
插件在带 llm、Web server、configEditor 的 profile（desktop / web 均可）上工作。安装前宜自行查看仓库源码与 MIT 许可证；插件以当前 DSH 进程权限运行，测试按钮会发起真实、可能计费的 provider 请求。
典型配置与用法¶
配置保存在当前 profile 的 cordis.patch.yml，也可通过面板保存。完整示例见仓库 examples/pool.yml。简例结构如下（字段含义见 README 字段表）：
- id: llm-pool
name: dsh-llm-pool
config:
retryPolicy:
mode: normal
maxRetries: 2
providers:
pool-a:
displayName: Example Pool
strategy: sticky
members: [provider-a, provider-b, provider-c]
models:
- id: model-a
name: Model A
targets:
provider-a: model-a
provider-b: model-a-alt
provider-c: model-a
使用步骤（与 README 一致）：
- 在真实渠道里配好各自的 endpoint、key 与模型；本插件复用这些配置，不要求在池里再配密钥。
- 在 设置 → 模型 底部面板点「新增统一服务商」，选择成员、聚合模型、调整映射后保存。
- 在会话
/model或输入框模型菜单中选择pool-a下统一模型；子代理、默认模型、AgentTeams 成员也可直接选该虚拟 provider。 - 在面板中对某模型行点「测试」，可做一次真实流式调用以确认映射与渠道可用。
可选 retryPolicy 将虚拟 provider 失败后的重试交给 dsh-llm-retry；providers.<id>.cooldown 可覆盖各类失败的冷却时长（毫秒）。
适用场景与注意¶
适合：已为 DSH 配置多条 LLM 渠道，希望在模型菜单里呈现一个逻辑上的「池」，在负载与故障之间做默认粘性均衡；需要按成员映射不同实际 model id，或合并多成员能力声明的场景。
资料中的限制与注意：
- 已输出内容后失败无法在同一流上无缝续接，依赖
dsh-llm-retry重试整个 step。 - 会话绑定、健康状态、最近调用在内存中，重启或保存配置后相关运行时状态会重置。
- 默认上下文取各成员最小值可能偏保守，可手动覆盖
contextWindow/maxTokens。 - 不支持嵌套统一服务商（成员不能是另一个池）。
- 卸载插件后真实 provider 配置保持不变；插件不修改 DSH 核心安装包。
CI 在 Node 22/24 上运行 npm run verify（27 个单元测试）；端到端与故障切换记录见仓库 docs/demo.md。
结尾¶
dsh-llm-pool 把多渠道路由、能力感知映射和失败前静默切换收到一个虚拟 provider 里，默认策略优先保住会话级 KV cache 并做全局会话数均衡。查阅市场条目与源码可分别访问 SkillHub 目录页与 GitHub 仓库：
