CypherNaught-0x/DSH-Subagent-Model-Router

DSH 子代理模型路由器

为每个委派的任务自动分配合适的模型。

不要再对所有类型的工作都使用同一个模型。一次性配置好你偏好的快速、经济、专用和高推理模型；路由器会为你的代理提供所需的别名、标签和指引，以便为每个委派的任务智能地选择最佳路由。

这意味着日常工作效率更高、难题上结果更强、成本控制更好，并且减少对模型的微观管理。子代理可以并行运行，它们的结果会在父代理响应之前可靠地汇合，而且每个任务所选的模型在整个 UI 中都保持可见。

为什么要用它？

- 在关键之处获得更好的结果 —— 把最强的模型留给架构、安全、深度推理或关键审查。
- 更低的成本和延迟 —— 将日常搜索、编辑和聚焦的实现工作交给更快或更经济的路由。
- 自动的、任务感知的路由 —— 友好的别名、能力标签和通俗易懂的使用指引帮助编排器做出智能选择。
- 有把握的并行委派 —— 在后台启动多个专家，并在综合之前可靠地收集每一个结果。
- 清晰的模型可见性 —— 在子代理标题、目录行以及 Better Sidebar 的 Tasks 视图中看到实际处理任务的是哪个模型。
- 轻松设置 —— 通过 Web UI、引导式技能，或直接在 settings.yaml 中配置你的模型团队。

[!TIP]
已经在使用 Better Sidebar？路由器通过 Better Sidebar 的公共 registerTab API 添加了一个可选的 Sub-agents 标签页。

实际效果

从 Better Sidebar 跟踪每一位专家

Better Sidebar Tasks 视图，显示委派的子代理及其所选模型标签

在你已经使用的任务树中，同时查看并行的委派工作、当前状态和所选模型。

构建你理想的模型团队

子代理模型路由器设置，用于别名、提供方、标签、令牌限制和路由指引

定义友好的路由，并告诉编排器每个模型在何时大放异彩——从快速、经济的任务到你最苛刻的工作。

它新增了什么

- subagent_model：一个委派工具，其 model 参数被限制为用户配置的别名。
- wait-for-subagents：一个汇合工具，等待此代理尚未完成的、可继续的后台子代理（包括标准委派和模型路由委派），并返回它们的最终结果。
- 嵌入在工具 schema 和系统提示中的按模型标签和路由描述。
- model_subagent_catalog：已注册 LLM 提供方所公布模型的只读视图。
- configure_subagent_models：一个命名空间作用域、面向模型的工具，无需文件系统访问即可读取或更新此插件的设置。
- model-subagent-setup：一个引导式技能，用于选择路由、生成路由指导、获取确认，并通过受约束的配置工具进行保存。
- 设置 → 子代理模型：一个 Web 设置页面，用于手动添加、编辑和删除路由。
- 在 ~/.dsh/settings.yaml 中热重载的 subagent-model-router 命名空间。
- 前台执行和持久可继续的后台子代理。
- 可配置的过期子代理过滤，用于列出工具，默认在无联系的情况下经过 20 个父/用户消息轮次。
- 在打开的子代理标题中显示活动模型标签。
- 在父会话的子代理目录中健康行显示活动模型标签。
- 通过公共侧边栏服务注册的可选 Better Sidebar 子代理标签页（当已安装时）。

当 models 列表为空时，目录、配置和等待工具仍与设置页面和设置技能一起可用，但 subagent_model 不会被注册。这为初始设置提供了一个引导状态。

编排器行为

当可进行模型选择委派时，系统提示会告知编排器不要重复其已委派的工作。在发出所有预期的后台委派后，它必须在综合子结果或给出最终答案之前调用 wait-for-subagents。当同一会话的完成目标处于活动状态时，编排器不能仅仅报告另一个模型正在处理该任务，并在后台子代理仍未完成的情况下结束其轮次：结束轮次会触发立即的目标继续，并可能与子跟踪发生竞争。等待会加入未完成的工作，以便编排器可以综合结果并继续或完成目标。等待工具会加入该父级通过 subagent、subagent_fork、subagent_model 或 auto_agent_run 启动的每个可继续的后台子级；即使未配置模型路由，它仍然有用。它会在标准、分叉和项目专家委派调用能够发布子级之前预留它们，并且在插件重新加载后，当直接可继续子级的持久描述符确认其模式，并且活动 Agent 要么正在运行，要么因停放的输入而中断（单独报告为暂停）时，它会发现这些子级。它会保留每个终端内容块，并在父级被处置时丢弃保留的记录，而前台一次性运行和由作业支持、不可继续的委派仍在此加入之外，因为其所属工具已经返回或收集结果。
直接的人类引导不得让父级阻塞在旧的 join 中。当已提交的 agent/inbox/spliced 事件为该父级在 next-step 插入一条 source.kind: user 消息时，一个活跃的等待会返回 { kind: "interrupted", pending: [...] }，而不会取消或消费任何子级。每个 pending 条目在可用时都携带确切的子级和运行身份。DSH agent 循环不会在父级应答后自动调度第二次工具调用。相反，插件的系统提示、工具描述和中断结果明确要求父级先应答引导消息，然后在最终综合之前再次调用 wait-for-subagents。第二次调用会恢复保留的记录，并返回它们最终的终端输出；排队的 next-turn 输入、模型编写的上下文、取消以及其他会话的事件都不会触发此结果。同时发生的子级完成仍会为恢复的等待保留。

延续管理器的持久结算通知会在错过终端生命周期事件时触发立即对账。恢复要求在保留的子级 epoch 日志和父级通知中都有匹配的边界后证据，因此仅凭缺失的注册表条目或空闲/可恢复的子级本身绝不会被视为成功。对于普通的受跟踪启动，记录仍绑定到确切的子级和运行身份。在插件重新加载后，一个真正正在运行的子级可能会在没有发布 run id 的情况下被发现；其确切的保留 Agent 对象加上子级和父级日志边界可安全地标识该观察到的激活。十秒看门狗提供相同的对账作为后备，以防实时通知事件也被错过。取消仍会拒绝活跃的工具调用而不消费记录，父级处置仍会释放受跟踪的子级和活跃等待。如果另一个插件已经拥有或作用域遮蔽了 wait-for-subagents 名称，本插件会保持其不变，并对受影响的 agent 抑制其等待特定的指导和跟踪。

被中断的子级可能处于空闲状态，其排队输入在显式恢复之前不会运行。对于具有停放输入和中止激活后缀的确切活跃子级，等待会返回 { kind: "paused", pending: [...], paused: [...] }，包括在重新加载后发现的情况。它不会结算该子级、丢弃其队列或自动唤醒它。请显式处理暂停状态：如果工作应继续，使用 send_message 并附上适当指令，然后再次调用等待；否则报告暂停并请求指示。不要盲目重启被有意中断的工作或反复重新等待。所有 pending 记录仍可 join。没有停放输入的空闲子级，或仍在运行的子级，不会以这种方式分类。
作为针对受可继续所有权持有排序缺陷影响的 Harness 版本的纵深防御，路由器会拒绝使用 send_message 将目标指向其自身调用方 agent id 的模型工具调用。该拒绝发生在公共 tools/execute 瀑布流中，早于内置工具调用子代理服务，并且常驻子代理会在错误提示中收到其直接父代理 id。这一刻意收窄的防护并不能替代核心修复：它无法保护直接调用子代理服务的调用方，无法拒绝所有其他无效的常驻关系，也无法修复当前宿主进程中已损坏的所有权状态。部署此源码需要常规的插件重建/重载（或重启宿主）；对于已损坏的进程，仍然需要重启宿主。

listingInactivityTurns 可防止旧的可持续子代理挤占面向模型的发现列表。对于每个直接父代理，路由器会统计传入的人类消息（对于嵌套代理，则为父代理中继消息），并在某个子代理收到父代理/用户消息时重置该子代理的窗口。一旦经过配置的轮数且没有联系，list_agents 就会省略该子代理。这仅是展示层面的处理：持久化的子代理不会被删除、卸载或变得不可寻址，因此已知 id 仍可通过 send_message 使用，并可在联系后重新出现。将该选项设为 0 可禁用过滤。在路由器重载后，没有可靠进程本地联系历史的子代理会获得一个新的可见性窗口，而不是基于不完整证据被隐藏。

如果存在已提交的管理者结算通知，但确切保留的结果不可用、损坏或不一致，看门狗对账会报告诊断错误，而不是捏造输出或永远等待。即时通知路径为正常终止事件先行到达留出了空间。插件卸载会明确拒绝活动等待，并释放跟踪器状态和看门狗定时器。

模型身份标签

已打开的子代理头部及其父代理子代理目录中每个健康行，都会显示最新适配器解析请求所配置的友好显示名称；当该路由不在当前路由器设置中时，回退到模型 id。悬停文本和无障碍文本会暴露完整的 provider/model 路由。插件会在子代理自身的描述符处重置路由，因此分叉不会继承其祖先的模型；并且在子代理记录权威请求路由之前，插件会省略该标签。
安装 Better Sidebar 后，路由器会通过 betterSidebar.registerTab({ id, title, component, single, order }) 注册一个单实例的 Sub-agents 标签页。该标签页读取权威的 DSH 会话目录，渲染带有模型标识的嵌套子项，并且仅在可见时管理目录观察。注册通过 ctx.inject(['betterSidebar'], ...) 进行作用域限定，因此原生路由器永远不会等待这个可选服务；服务的延迟加载和卸载都会被自动处理。原生 Better Sidebar 控制选中哪个标签页，并且目前在刷新后会恢复其 Start 页面；使用 + 菜单重新打开 Sub-agents。（可选的底部工作台具有独立的持久化语义。）当该服务不存在时，此集成处于惰性状态。

要求

- DeepSeek Harness 0.1.0-rc.6 或兼容版本
- Web 配置文件以及内置的 subagent 对话 UI
- 一个暴露常规 skill 加载器/工具的预设
- Host spawn subagent 提供程序，包含在标准 DSH 配置文件中
- 可选：一个兼容的 dsh-better-sidebar 发行版，暴露公共 registerTab API（包括原生右侧边栏界面）

安装

From npm once published
dsh plugin --profile web add dsh-subagent-model-router

Or from inside this checkout
dsh plugin --profile web add .

安装后重启 dsh web 并刷新页面。打开 Settings → Subagent Models，或调用：

/model-subagent-setup

通过 Web UI 配置

Subagent Models 设置页面提供以下控制项：

- 模型别名、显示名称、LLM 提供程序路由以及确切的模型 id；
- 逗号分隔的路由标签以及“何时使用”描述；
- 可选的按模型输出 token 上限；
- subagent 后端、委托深度、后台执行以及过期列表轮次阈值。

在 DSH rc.6 上，内置的 Web 设置 API 仅暴露固定的命名空间允许列表。因此，此插件使用一个由包拥有、同源的 Host 端点，其后端由相同的 Settings 服务、schema 验证、持久化和修订冲突保护提供支持。成功的更改会实时生效：旧的委托工具会被移除，更新后的 schema 和提示指导会立即注册。

该端点默认拒绝非回环传输和跨源变更。受信任的回环反向代理可以通过逗号分隔的 DSH_SUBAGENT_MODEL_ROUTER_TRUSTED_ORIGINS 环境变量允许特定的浏览器源，例如 https://dsh.example.test。请求仍必须通过回环到达，并且每个变更 Origin 必须同时与请求 Host 和允许列表中的某个源完全匹配。

通过面向模型的工具配置

configure_subagent_models 是 agent 辅助设置的首选路径：

- action: "get" 读取当前规范化设置。
- action: "update" 替换完整的模型列表，并可选择更改后端、深度或后台策略。
- 该工具直接调用 Settings 服务，并且只能修改 subagent-model-router；它不接受任何文件系统路径，也无法读取或写入其他命名空间。
- 更新会通过与 Web UI 相同的 schema 和 provider 能力校验，持久化到 settings.yaml，并实时生效。

更新操作有意仅记录用于用户直接请求的更改。setup 技能必须先展示完整的建议列表，并在调用它之前获得明确确认。

通过 settings.yaml 配置

将以下命名空间合并到 ~/.dsh/settings.yaml：

subagent-model-router:
subagentProvider: spawn
maxDepth: 3
enableRunInBackground: true
listingInactivityTurns: 20
models:
- alias: fast
provider: acme
model: acme-fast
displayName: Acme Fast
tags: [fast, routine]
description: Use for quick, well-scoped tasks where low latency matters.
- alias: deep
provider: acme
model: acme-reasoner
displayName: Acme Reasoner
tags: [reasoning, review]
description: Use for difficult analysis, architecture decisions, and adversarial review.
maxTokens: 16384

可复制的文档片段见 examples/settings.yaml。设置文件会被监视；有效的编辑无需更改 Cordis patch 即可生效。

设置参考

| 字段 | 默认值 | 用途 |
| --- | --- | --- |
| models | [] | 暴露给 AI agents 的路由。空列表仅保留 setup/catalog。 |
| models[].alias | 必填 | 在工具的 model 枚举中显示的稳定选择器。 |
| models[].provider | 必填 | 已注册的精确 LLM provider 路由。 |
| models[].model | 必填 | 由该 provider 解释的精确 model id。 |
| models[].displayName | alias | 路由指引中的人类可读标签。 |
| models[].tags | [] | 小写 kebab-case 路由标签。 |
| models[].description | 必填 | 一句话描述何时使用此路由。 |
| models[].maxTokens | provider 默认值 | 初始创建或常驻子项的可选上限。DSH rc.6 在可继续的子项被冷恢复后不会恢复它。 |
| subagentProvider | spawn | Subagent 执行后端，而非 LLM provider。 |
| maxDepth | 3 | 由后端强制实施的最大委派深度。 |
| enableRunInBackground | true | 启用持久后台子项并默认使用它们。 |
| listingInactivityTurns | 20 | 在这么多父/用户消息轮次无联系后，从 list_agents 中省略子项。0 禁用过滤；直接寻址和可恢复性不变。 |

委派工具始终命名为 subagent_model。0.4 之前版本中的旧 toolName 值会被忽略，并在下次保存该命名空间时移除。

实时 catalog 仅供参考：某些适配器会接受它们未公布的 model ids。手动输入的 id 仍然允许，但应经用户确认。

已知限制
DSH rc.6 在子代理目录行内没有附加插槽，因此该插件占用现有的 subagent-catalog 表头单元格来渲染行标签。它通过以 priority: -1 注册来占用该单元格——列表单元格会渲染其最低的活跃优先级，而宿主自身的条目位于默认的 0。subagent-model 单元格也以相同方式注册，这样即使宿主构建也填充它，也会被遮蔽而不是发生冲突。DSH 中目录交互的变更必须在此处同步镜像，直到宿主暴露行扩展插槽或自行渲染 subagentModelRoute。

Better Sidebar 的公共标签页注册表是受支持的集成接缝。该路由器不会抓取外部 DOM、注入原生 Tasks 行，也不会修改 Better Sidebar 源代码。注册的标签页是可选的，并限定于服务生命周期；如果 Better Sidebar 不可用，原生表头、目录、设置和模型标签将继续保持不变。

开发

pnpm install
pnpm test

项目布局：

dsh-subagent-model-router/
├── lib/
│   ├── index.js
│   ├── client.js
│   └── model-catalog.js
├── skills/model-subagent-setup/SKILL.md
├── examples/settings.yaml
├── test/
│   ├── client.test.js
│   ├── model-catalog.test.js
│   └── plugin.test.js
├── cordis.patch.yml
└── package.json

Client 包是纯 window.__ModuleLoader__.load(...) JavaScript，无需构建步骤。

许可证

MIT