dsh-subagent-default-model (plugin)

dsh-subagent-default-model

为 DeepSeek Harness 子代理选择默认模型，并支持多模型轮换。

English · 安装 · 配置 · 更新日志 · 问题反馈

一个独立的 DeepSeek Harness (DSH) bundle 插件。它只处理省略了 agentOptions 的子代理请求；显式指定的模型始终优先，DSH 核心包保持原样。

亮点

三个核心功能

1. 多模型分配策略（round-robin 顺序 / random 随机） —— 配置 ≥2 条路由后决定并行子代理如何分配：顺序轮换按列表依次取用、结果可预期（10 个子代理 / 2 条路由稳定 5/5）；随机则无固定规律。分配发生在派发时，同一个子代理内部不会因策略中途换模型。

2. 跨供应商故障转移 —— 子代理遇到连接类失败（限流/配额/服务端/超时/传输/空响应）或认证类失败（密钥无效/过期，AUTH/INVALID_CREDENTIAL）时，在本插件的 models 列表内换一条路由重试。候选来自整个列表，因此可以切到另一个供应商的模型。认证类也会切换（各家密钥独立时，一家密钥坏不该让任务死掉），但必打 warn 日志说明该供应商密钥可能无效，避免静默掩盖配置问题。耗尽即放行真实错误，主代理循环不受影响。

3. 当前路由可见（你 + 子代理都能看到） —— 两条独立通路：

   • 界面行（给你）：轨迹视图与对话视图显示「当前供应商/模型：provider/model」，故障转移切换时显示「已切换到」，会话恢复显示「继续使用」。
   • 提示词注入（给子代理）：向子代理自己的上下文注入一行真实提示词，写明当前 provider 与 model，因此它能如实回答自己跑在哪个模型上；路由因故障转移变化时，这一行会在下一步跟着更新。默认开启，可在设置中关闭。

   两者互不替代：界面行不进模型上下文，提示词注入也不显示在你的界面上。

其他特性

• 单模型默认路由：所有未显式选模型的子代理使用同一条配置路由。
• 逐路由推理强度：每个模型条目可独立配置 reasoningEffort。
• 完整覆盖派发入口：同时包装 start() 与 startContinuable()，覆盖 subagent、subagent_fork 以及其他调用 ctx.subagents 的发起方。
• 设置热更新：编辑设置后，下一次派发立即采用新配置。
• 干净卸载：Cordis 销毁插件时恢复原始服务方法。
• 原生设置卡片：可在 设置 → 插件配置 → 子代理默认模型 中完成配置。

工作原理

显式请求 agentOptions
  → subagent-default-model 设置
  → 继承父会话路由

• 显式提供的 agentOptions 对象不会被修改。
• 非空 models 列表优先于兼容用的单 model 字段。
• 无效或不完整条目会被忽略；没有有效配置时回退到父会话路由。
• 多模型策略支持顺序轮换与独立随机选择。

效果预览

设置面板

配置一个或多个模型路由、分配策略以及逐路由推理强度。

分配验证

10 个子代理在 deepseek-v4-flash 与 Kimi-k3 之间以 round-robin 策略实现 5/5 分配。

当前路由可见（功能三）

对话流里出现的「当前供应商/模型：workbuddy/deepseek-v4.1-flash」提示行 —— 这行渲染给你看，不进入模型上下文。

安装

推荐使用 DSH 插件命令安装 npm 已发布版本：

dsh plugin --profile desktop add dsh-subagent-default-model

若使用其他 profile，请把 desktop 替换成对应名称。也可以直接通过 npm 安装：

npm install dsh-subagent-default-model

安装、更新或卸载 bundle 后，需要重启对应的 DSH 进程；仅修改设置不需要重启。

宿主版本要求

本插件声明全部 8 个 @deepseek-ai/* peer 为 >=0.1.7-rc.1 <0.3.0-0：支持 0.1.7 线及其后的整个 0.2.x 线（含 prerelease 与正式版），0.3.0 起不再声明支持。

⚠️ 上界必须带 -0（<0.3.0-0 而非 <0.3.0）。DSH 用 semver.satisfies(runtime, range, { includePrerelease: true }) 校验 peer， 该选项会关闭 prerelease 元组规则，于是 <0.3.0 会放进 0.3.0-rc.1， 把支持范围悄悄扩到未经验证的一行。同理，上界写 <0.2.0 是危险的： 它会放进 0.2.0-rc.1 却拒绝正式的 0.2.0——正式版一发布，整个 bundle 会被宿主跳过（skipping profile bundle），插件本体与设置卡片一起消失。

平台支持

Windows / macOS / Linux 均受支持，且不需要任何平台专用配置或额外步骤。

平台	配置路径	状态
Windows	%USERPROFILE%\.dsh\profiles\<profile>\cordis.patch.yml	✅ 受支持，CI 覆盖
macOS	~/.dsh/profiles/<profile>/cordis.patch.yml	✅ 受支持，CI 覆盖
Linux	~/.dsh/profiles/<profile>/cordis.patch.yml	✅ 受支持，CI 覆盖

插件本体是纯 JavaScript——宿主半边与客户端半边都不读文件系统、不拼路径、不派生进程、也不判断 process.platform，只消费 DSH 宿主暴露的服务与事件，因此平台差异由宿主承担。已被检查并持续验证的平台面：

• 依赖树跨平台：package-lock.json 锁定了 Windows 三套可选原生构建（x64 / arm64 / ia32），npm 只装匹配当前平台的那个；插件直接依赖 @deepseek-ai/schemastery 为纯 JS。
• CRLF 安全：Windows 检出可能得到 CRLF 源码（仓库未固定 core.autocrlf），全套测试在该形态下已验证通过。
• 路径解析：仓库脚本统一用 fileURLToPath，避免 URL.pathname 在 Windows 上折成不存在的 \C:\...。
• 测试发现：npm test 走 node --test 由 Node 自行发现，不依赖 shell 展开 glob（cmd/PowerShell 下 glob 不展开）。

CI 在 ubuntu-latest / windows-latest / macos-latest 三个平台同时跑同一套测试，因此以上为持续验证而非一次性声明。细节见 plugin/README.md。

配置

可以在 Web 设置卡片中配置（设置 → 插件 → dsh-subagent-default-model），也可以编辑 profile 的 patch 文件 ~/.dsh/profiles/<profile>/cordis.patch.yml——DSH 0.1.7 起设置就存在那里，段名是本插件的 Loader 条目 id dsh-subagent-default-model（不再使用 ~/.dsh/settings.yaml，详见 plugin/README.md）。

固定一个默认模型

- id: dsh-subagent-default-model
  name: dsh-subagent-default-model
  config:
    provider: deepseek-official
    model: deepseek-v4-pro

多模型轮换

- id: dsh-subagent-default-model
  name: dsh-subagent-default-model
  config:
    provider: deepseek-official
    models:
      - deepseek-v4-pro
      - deepseek-v4-flash
      - provider: other-provider
        model: another-model
        reasoningEffort: high
    strategy: round-robin # round-robin | random

推理强度预检（设置面板即时警告）

设置面板会在你选择 provider / model / 推理强度时即时校验所配 reasoningEffort 是否被目标模型声明，不匹配时在该路由行内与保存区显示红字警告，指明具体缺失的档位。

• 为何需要：所配 effort 不被目标模型接受时，宿主在 prepareRequest() 阶段就拒绝本次请求——早于 system prompt 组装与上下文注入，也早于 failover 的错误派发。表现为子代理「什么都发不出去」：界面上看不到任何上下文，父会话只收到一句 failed before it finished / It left no closing message，真实错误码（UNSUPPORTED_REASONING_EFFORT）只落在会话日志里。
• 不阻止保存：供应商目录可能尚未刷新（模型的能力声明会晚于插件配置出现，也可能在时间窗口内暂时缺失）。警告只提示，不卡住保存——否则会把用户困在一个暂时性状态里。
• 未知不等于不支持：provider 或 model 尚未出现在目录里时不报警告。把「目录里没有」当作「不支持」会把一次目录延迟变成误报。
• 警告随目录刷新自动消失，无需重开面板。

子代理连接失败自动切换（默认开启）

当子代理（subagent）自身的循环遇到连接类失败时，插件会自动在 models 列表内切换模型并按 strategy 规则重试——仅对 subagent 生效，主代理循环不受影响。

• 触发码：命中以下任一错误码才切换——RATE_LIMIT、QUOTA、SERVER、TIMEOUT、TRANSPORT、EMPTY_RESPONSE。认证错误（如 AUTH）不会触发切换。
• 队列：round-robin 策略下按列表顺序切到下一个模型。
• 随机：random 策略下随机挑一个模型（不判断之前是否用过）。
• 需要 ≥ 2 个模型：models 少于 2 项时本功能不生效。
• 耗尽即放行：列表内全部模型轮试失败后放行真实错误，不做无限重试。
• 切换时丢弃继承的 reasoningEffort：换到新 provider/model 后按默认推理强度请求，避免把主模型强度强加给不支持它的 provider。
• Run 内粘性：同一子代理 run 的后续 step 保持在切换后的模型上。
• 轨迹视图可见：每次请求用的 provider/model 会显示在子代理的轨迹视图里——换模型（含 failover 切换）后自动多出一行「当前供应商/模型：provider/model」，方便确认重试/切换时用的到底是哪个模型。
• 该行为由 failoverEnabled 开关控制，默认 true：

- id: dsh-subagent-default-model
  name: dsh-subagent-default-model
  config:
    provider: deepseek-official
    models:
      - deepseek-v4-pro
      - deepseek-v4-flash
    failoverEnabled: true # 连接失败时按队列与策略切换模型

字段	类型	默认值	说明
provider	string	—	字符串模型条目共用的 provider。
model	string	—	单模型 ID，保留用于向后兼容。
models	array	[]	字符串或 { provider, model, reasoningEffort? } 条目列表。
strategy	string	round-robin	多模型分配策略。
failoverEnabled	boolean	true	连接失败时在 models 列表内按队列与策略切换模型（仅 subagent）。
reasoningEffort	string	—	可选的逐路由推理强度。设置面板会校验它是否被目标模型声明，不匹配时给出警告（不阻止保存）。

市场收录与展示

插件已经包含可安装的 dsh.bundle manifest，并发布到 npm。社区市场通常从 Awesome DSH Plugin 注册表同步条目；仓库内的提交草稿位于 awesome-dsh-plugin-submission/dingminhua__dsh-subagent-default-model--plugin.yml。

市场卡片中的截图与 GitHub README 徽章是两套机制：

• GitHub 徽章由本 README 顶部的 Shields/dshfind 图片链接生成。
• 市场截图由注册表 data/screenshots.json 控制；未配置时，市场会尝试从 README 提取图片。
• 市场图标/占位图由具体市场的展示规则决定，并不是 npm package.json 的通用字段，也不是 README 徽章。

开发

npm --prefix plugin install
npm --prefix plugin test

根目录还提供两条聚焦回归命令：

node integration.mjs
node prove.mjs

完整开发说明见 DEVELOPMENT.md，发布步骤见 RELEASING.md。

卸载

dsh plugin --profile desktop remove dsh-subagent-default-model

重启 DSH 后 bundle 不再加载。profile patch 中遗留的配置不会再生效，可按需手工删除。

许可证

本项目采用 MIT 许可证 开源发布，版权归属：Copyright (c) 2026 LaoDing。

MIT 许可证授予任何人免费处理本软件（包括使用、复制、修改、合并、发布、分发、再许可及出售副本）的权利，前提是所有副本或实质性部分均保留上述版权声明与本许可声明；软件按“原样”提供，不附带任何明示或暗示的担保。完整条款见 LICENSE。