前言¶
在 DeepSeek Harness（DSH）里跑智能体时，你往往会配多条渠道、几十个 provider/model。日常对话里真正烦人的不是「选哪个模型」，而是当前模型突然撞额度、密钥失效、被限流，或者网络抖一下——一轮回答还没出字就断了。手工换模型、重发一轮，既打断流程，也容易把错误当成「模型不行」而不是「这条渠道暂时不可用」。
社区插件 dsh-model-rotator（维护者 chimneyQ，分类：模型推理）针对的是另一类问题：在不改动你已有的 provider / 模型配置的前提下，自动发现本机可拨通的对话模型，按实测连通率与速度排序，并在 llm/stream 瀑布上接管——当当前尝试完全没有产出正文时，在同一轮内换到下一候选继续流式回答。用户侧默认仍是一条普通回复；切换记录落在独立的「模型切换」页签，不占用对话上下文。
下面按「它做什么 → 怎么装 → 怎么用 → 注意什么」说明，事实以 GitHub 仓库 与 SkillHub 目录页 为准。SkillHub 是社区维护的插件目录，与 DeepSeek / 幻方无官方从属关系。
这是什么¶
dsh-model-rotator 是 DSH 上的模型推理类插件（npm 包名 dsh-model-rotator，当前资料记载版本 0.2.14，MIT 许可证，要求 Node >= 18）。一句话定位：给 Harness 加上「按实测排名 + 同轮透明 failover」——发现本机 provider/model、过滤非对话与识图孪生路由、对存活候选排序，失败时在零内容窗口内重试或切换，并提供按渠道分组的模型列表与开关。
插件从不读、写或改写模型与 provider 配置；只在运行时观察并介入流式调用。
核心功能¶
发现、过滤与排序¶
- 调用
ctx.llm.listProviders()与各适配器的listModels()，枚举本机可拨通的provider/model。 - 剔除无法完成一轮对话的族：向量/重排、语音、OCR、图像/视频生成、审核与评判模型等，避免白占冷却位。
- 跳过 dsh-vision-router 生成的
*-vision识图孪生路由（同一模型的第二条通路，不作独立候选；仅名字里带 vision 的真对话模型仍保留）。 - 对剩余候选按拉普拉斯平滑的成功率、TTFT 中位数与吞吐排序，并结合失败冷却；默认
preferSameModel: true时，当前模型或其在他渠道的近亲会加权靠前。
重试与同轮故障转移¶
- 单次失败不立刻判死：同一模型在
retriesPerModel（默认 2，0–5）内、按retryBackoffMs（默认 300ms，递增）重试；重试不换模型、不弹确认。 - 在
llm/stream上：第一次走宿主原路径；若失败且无任何正文分片（reasoning-delta、标记块不算内容），关闭上游流后用新的ctx.llm.stream()派发下一候选。 - 一旦已有正文流出，不再重试或切换，避免重复可见文本。
- 用户取消、超时或客户端断开时，停止走链，不再浪费候选。
- 带
purpose: "compaction"或purpose: "session-title"的自动调用原样透传（含错误），不参与 failover，避免压缩/标题通道上的误切换。
切换确认、冷却与记录¶
- 默认
confirmSwitch: true：零内容失败时经ctx.userQuestions.askTimed()询问「切换」或「保持当前模型」；超时未答则继续切换。quota、unsupported两类确定性失败直接切换，不再多问。 - 失败会归类（如
quota、auth、rate-limit、unsupported、server、network），并影响冷却：quota可走quotaCooldownMs与次日quotaCooldownHour；其余多用指数退避（cooldownBaseMs/maxCooldownMs）。实测状态可持久化到%DSH_HOME%/model-rotator/stats.json（受statsPersistTtlMs约束）。 - 切换默认静默；记录在对话顶部 「模型切换」 页签（
GET /_dsh/model-rotator/switches?session=<id>）。可选noticeSwitch: true在轮次边界贴一行模型已切换：A → B类通知。 - 默认
adoptSwitchedModel: true时，把实际作答的模型写回当前会话显示，不动全局默认配置。
工具、列表与界面¶
| 工具 | 作用 |
|---|---|
model_rotator_status |
只读：启用状态、池规模、排名、生效配置来源、冷却与问句通道等 |
model_rotator_benchmark |
用最小真实请求探测候选，刷新延迟与冷却（有次数上限，会消耗额度） |
model_rotator_select |
固定或取消固定转移队首 |
设置页入口：设置 → 模型自动切换，以及插件面板中的 model-rotator 卡片；下方提供可搜索、按渠道分组的模型列表（GET /_dsh/model-rotator/models，POST {key, enabled} 切换行或渠道）。配置合并顺序：默认值 < %DSH_HOME%/model-rotator/config.json < 设置页（设置页未覆盖的键仍来自文件）。
安装与启用¶
推荐从 npm 安装到 desktop profile：
dsh plugin --profile desktop add dsh-model-rotator
也可从 GitHub 安装：
dsh plugin --profile desktop add github:chimneyQ/dsh-model-rotator
包内自带 cordis.patch.yml，无需额外构建。装完后需完整重启 DSH 应用才会加载。若怀疑未接入 bundle，可检查 <DSH_HOME>/profiles/desktop/package.json 的 dsh.profile.bundles 是否包含 dsh-model-rotator。
可选配置文件路径：%DSH_HOME%/model-rotator/config.json，支持热加载；不建文件也能用默认值运行。常用字段包括 enabled、maxCandidates（默认 4）、confirmSwitch、retriesPerModel、noticeSwitch、disabledModels / disabledProviders 等，完整示例见仓库 README.zh.md。
典型用法¶
1. 安装后确认池子与排名
在对话或工具调用里执行：
model_rotator_status
关注 discovered 与排名表；本机候选数量完全取决于已配置的 provider，不要照搬文档里的示例数字。
2. 需要时刷新实测指标
model_rotator_benchmark
注意会发起真实请求并可能消耗额度。
3. 固定 failover 队首（可选）
model_rotator_select
或在 config.json 里设置 pinned。
4. 在 UI 里关渠道或单模型
打开 设置 → 模型自动切换，在列表中对某行或渠道表头关闭；等价于写入 disabledModels / disabledProviders。
5. 想在正文里看到切换行
在设置页打开对应项，或配置 noticeSwitch: true。
适用场景与注意¶
适合谁
- 同一台机器上配置了多条 API 渠道、多个同名或近亲模型，希望「当前渠道挂了自动换到下一条」，且不想改 cordis / provider 配置的人。
- 需要按连通率与速度自动排序、并对额度/限流做区分冷却的长期挂机或无人值守场景（默认可限时确认，超时仍会切换）。
务必注意
- 插件以当前 DSH 进程权限运行，会拦截并重新发起
llm/stream；安装前请阅读 源码 与 MIT 许可证，自行评估信任边界。 allowImageFailover默认为false：含图的轮次默认不参与转移，避免纯文本备选给出错误答案。- 图像识图孪生默认不进候选；若 wrapper 命名不符合
*-vision约定，可通过enabledModels单独放回。 - 社区目录与 GitHub 星标（资料记载为 1）只反映曝光度，不代表官方背书；版本与行为以你安装的包为准。
结尾¶
dsh-model-rotator 把「多模型、多渠道」从手工救火变成运行时排序与同轮 failover：失败在零内容窗口内重试或切换，切换有记录、可选确认，列表与冷却策略可配置，且承诺不碰 provider 配置本身。若你在 DSH 里已经堆了不少渠道，值得把它当作模型推理层的弹性插件试一轮。
