子代理模型路由 dat-lequoc/dsh-opinionated-subagent

dsh-subagent-model

一个极简、有主见的 subagent，专为 DeepSeek Harness 打造：子代理能跑哪些模型、用多高的推理强度，由你决定；纠偏会在子代理的下一步送达，而不是等它这一轮结束。

它做什么

- 强制每个子代理的模型。 subagent 接收必填的 model 参数；Agent Teams 的 spawn_teammate 没有 model 参数，因此它使用本白名单里第一条具体路由。只要配置了强制，这两条路径都不会悄悄继承对话的模型。
- 强制子代理的推理强度。 强度由你按路由设定，不由委派的智能体决定——它没有强度参数，也无法继承你的强度。
- 在花掉任何开销之前就拒绝错误的强度。 配置的强度会先对照该模型自己公布的集合校验，然后才发起服务商调用。
- 在运行中的子代理的下一步纠偏。 自带的 send_message 会排在整个当前轮次之后；针对进行中工作的纠偏可能晚几分钟才落地。这个版本则加入正在进行的轮次。
- 在记录里显示路由。 每次 subagent 调用都会渲染它实际运行的模型，你不用翻会话日志去核对。
- 可在 UI 中配置。 设置 → 插件，强度下拉框按每个模型实际支持的内容填充。
- 可编辑的委派提示词。 同一张卡片会显示注入系统提示词的确切文本，你可以改写、保存，或重置为自带默认值。
- 在你选择启用之前保持中立。 安装后，它的行为与自带工具完全一致；只有你编辑白名单，强制才会开始。

每一部分都是可选的，按行组合：只挂载委派前端、只挂载纠偏的 send_message，或两者都挂。

为什么

子代理启动时若没有 agentOptions，就会继承父级的路由。当前 DSH 可以选择在自带工具上暴露模型选择，但本插件提供的是另一套必填路由策略，以及按路由、归用户所有的强度。安装它的设置面板不会配置自带工具。

本插件替换那个前端。model 参数必填，它的 enum 就是你配置的白名单，选中的路由及其配置的强度会钉在子代理上。

安装后，在你发话之前什么都不变

白名单自带一条初始条目 inherit/current，它明确跟随调用轮次自己的模型和强度。所以全新安装的行为与自带工具完全一致，你改变主意也没有需要撤销的东西。

强制是选择启用的：添加你想要的路由，并移除 inherit/current，让继承不再可能。只要它还在，模型就仍可指名它，所以它是一项许可，不是兜底——无论哪种情况，工具调用都会清楚记录子代理跑在哪条路由上。

inherit/current 解析的是当前轮次记录的路由，而不是会话创建时的模型，因此会话中途切换模型也会被尊重。

它如何强制路由

harness 把这两件事拆开了，所以插件用两套机制：

| 事实 | 机制 | 持久？ |
| 服务商 + 模型 | SubagentStartRequest.agentOptions，优先级高于继承来的父级路由 | 是 —— 不需要桥接 |
| 推理强度 | agentOptions.reasoningEffort，外加在活动子代理上调用 installModelSelection | 当前 DSH 会在首次请求前把它写进续接描述符 |

当前 DSH 支持 agentOptions.reasoningEffort。插件显式传入它（包括传 undefined，用来清除 provider/default 的同路由继承）。lib/effort.js 还会调用 harness 的 installModelSelection 原语，让活动提示词插值与请求路由保持一致。

agent/created 是同步发布边界，所以选择会在子代理组装提示词或发出请求之前装好。

安装

dsh plugin --profile web add /path/to/dsh-subagent-model

这条命令只挂载宿主侧：拥有你允许列表的设置命名空间。它不注册任何工具。

运行中的 Host 会保留已挂载的模块，所以更新本包代码后要重启它 —— 新卡片和新的 prompt 字段都在那时生效。改设置本身从不需要重启。

工具行属于智能体预设，因为委派工具是按智能体组合的，必须替换出厂行，而不是与它并排 —— 两行注册同一个 subagent 名字会冲突，而让出厂行继续挂载，模型就有办法绕过这套策略。

在预设选择器里为你实际使用的预设（例如 ptc）建一份本地副本，然后编辑该副本在 ~/.dsh/.agent-presets/<your-id>/ 下的 agent.cordis.yml。不要改出厂预设：升级会替换它们。宿主 cordis.patch.yml 不会给常驻预设组合打补丁。

按下文替换该文件里的两行委派行。这个例子为 spawn 和 fork 强制指定路由，并禁止两类子代理再委派：

- id: tool-subagent
name: dsh-subagent-model/spawn
config:
provider: spawn
toolName: subagent
backgroundMode: continuable # or one-shot
maxDepth: 1
toolFilter:
deny: [subagent, subagent_fork]

- id: tool-subagent-fork
name: dsh-subagent-model/spawn
config:
provider: fork
toolName: subagent_fork
backgroundMode: continuable
maxDepth: 1
toolFilter:
deny: [subagent, subagent_fork]

为新会话选择你的本地预设（也可以把它设为默认）。已有会话保留原来的预设代次。确认两个工具 schema 现在都要求 model，并列出你配置的路由。如果 model 缺失，说明出厂前端还在运行；改允许列表影响不到它。删掉 inherit/current 即可禁止继承。

深度不是子代理权限

maxDepth 是每次启动的绝对上限：根深度为 0，其子节点为 1。0 连第一个子节点都不允许；1 允许直接子节点。默认值仍为 3，以保持兼容。这个上限不是可继承的天花板。 子节点可以通过另一个前端绕过某个工具的上限，只要那个前端的上限更大。

DSH 0.2.1： SubagentStartRequest 不再携带 toolFilter 或 persona（限制已移到 Agent Presets / agentPreset）。本插件仍接受这两个配置键，好让已有配置档继续加载，但在 0.2.1 上会忽略它们并记录一条警告。保留 maxDepth —— 它仍然执行委派深度上限 —— 并把工具面限制移入子节点的 Agent Preset。

用 toolFilter 在每个子节点内同时拒绝 subagent 和 subagent_fork。DSH 在执行时和 schema 可见性上都会强制执行，包括 PTC 绑定，并为可继续的冷恢复持久化该过滤器。保留自带的 send_message 用于汇报。名称必须存在于继承的工具面中；如果你的预设省略了 fork，也要从过滤器中省略该名称。加上你的预设暴露的任何自定义委派别名或其他智能体创建工具，或者改用显式的 allow 列表列出 worker 工具。这是工具面限制，不是防止受信任插件直接调用运行时服务的沙箱。

要强制父级的委派选择，还需要替换或禁用每一个备用委派前端；只过滤子节点并不能堵住父级中自带的 fork 绕过路径。

配置

Settings → Plugins → Subagent model。 卡片列出你允许的路由，每条路由带一个 effort 下拉框，选项来自该模型自己声明的值，还有一个「Add a route…」选择器，数据来自实时模型目录。编辑先在本地暂存，点 Save 时通过带修订栅栏的设置作用域提交，所以半途而废的编辑永远不会到达运行中的智能体。横幅会直白说明你当前是继承还是强制。

路由下方，卡片显示委派提示词：注入系统提示词的确切文本，放在编辑器里，并显示字符数和大致 token 数：

- Save 把它和路由一起写入，一次带修订栅栏的提交，且只在文本确实被编辑过时才写 —— 未改动的提示词永远不会被重述，所以编辑路由既不会把出厂默认值冻结进你的配置档补丁，也不会把它清空。
- Reset to default 把出厂文本放回框里；Save 才会应用。在 Save 之前不写入任何内容。
- 出厂默认值不会在浏览器 bundle 里重复一份 —— 卡片从本包自己的宿主路由读取它，所以改进默认值的升级能到达从未覆盖过它的卡片。
- 清空输入框是有意义的：空提示词不注入任何段落，这就是不卸载任何东西就关掉该指引的方式。
两部分都打包在同一个包里：安装后，设置页就会出现这张卡片。这些值属于 subagent-model-settings 补丁行的易变 Config，所以 Save 会把它们持久化到配置档的 cordis.patch.yml，运行中的智能体无需重启即可读到。

等价地，在 ~/.dsh/profiles/<profile>/cordis.patch.yml 中：

- id: subagent-model-settings
config:
routes:
- kiro/claude-opus-5
- deepseek/deepseek-chat
- inherit/current # remove to forbid inheriting the conversation's model
efforts:
kiro/claude-opus-5: high
deepseek/deepseek-chat: provider/default
prompt: | # omit for the shipped guidance; '' injects nothing
Leverage long-running subagents to delegate work. Explore and report.
Make detailed plans, run them, wait for them to finish, then check their
quality and the code diff to steer.

- routes —— 完整的允许列表，写法为 provider/model-id，外加可选的 inherit/current 条目。只有第一个 / 用来切分服务商路由，所以模型 id 本身可以含斜杠。默认值为 [inherit/current]。对 Agent Teams 的 spawn_teammate 来说，第一条具体路由（即除 inherit/current 外的第一个条目）就是强制给队友使用的路由。
- efforts —— 每条路由的 effort。路由不在映射里，或设为 provider/default，都不发送显式 effort —— 对 inherit/current 而言，这意味着沿用调用轮次自身的 effort。其他任何值都必须是该模型明确公布的 effort；未公布的 id 会在调用任何服务商之前被拒绝，而不是被截断。在 inherit/current 上显式设置 effort 会覆盖继承来的值，所以你可以沿用模型，同时固定 effort。
- prompt —— 注入系统提示词的委派指引。省略则使用随包提供的文本；设为 '' 则完全不注入该段落。它在组装提示词时读取，所以保存后下一个请求即可生效，无需重启。

这三项在每次工具调用或提示词组装时都会读取，所以改动会在下一次委派时生效，无需重启。

模型被告知的委派方式

替换随包提供的 tool-subagent 行，也会移除该行贡献的提示词段落 —— 它属于那一行，不属于 harness。所以本插件自带一份，注册在同一个 TOOL_SUBAGENT 位置。文本由你决定：Settings → Plugins → Subagent model 会原样显示注入的内容，并允许你替换。随包默认文本是：

Delegate bounded work instead of doing it here. Three cases pay off:
- Exploration: "where is X, how does Y work" — ask for the conclusion with file:line references, not file contents.
- Implementation: one piece of an agreed plan: decisions already made, the files it may touch, what "done" means.
- Verification: a child that did not write the code, checking it against the requirement; ask what it ran and what it observed.
说明要汇报什么、什么不在范围内。同时启动相互独立的委派，让它们在后台运行，你继续干活。把子代理的发现当作线索，而不是事实：你的答案依赖什么，就回到产物本身去确认。

改写之前，有三条性质值得了解：

- 它在组装时读取。 这个段落每个配置档只注册一次，但它的文本在每次组装提示词时都会重新解析，所以保存后下一个请求就生效，不用重启——和 allowlist 走的是同一条易变的 Config 路径。
- 在宣告的工具不可调用的地方，它渲染为空，每个被委派的子代理都是如此：子代理按构造就没有委派工具，叫它去委派，是它无法采纳的建议。这道门控针对的是工具，不是措辞，所以自定义提示词对子代理同样不生效。配置的提示词为空时，在哪里都不渲染任何内容。
- 它随每个系统提示词一起下发。 随附的文本约 160 token，有测试盯着它，一旦变长就失败；你自己写的提示词没有这样的预算，卡片会显示字符数和大致 token 数，让你编辑时看得见成本。

host 那一半拥有这个段落，每个工具行只宣告自己注册的工具名。这个分工不是做样子：一个提示词段落只存在于一个作用域层，同一层里同名注册两次会抛错，而这个插件在同一作用域里为每个委派工具挂一个工具行——每行一个段落，要么抛错，要么把同一件事说两遍。把它交给每个配置档只挂载一次的那一半，也意味着文本能扛住会话更替。

值得了解的行为

- allowlist 为空会注销工具。 它绝不会回退到父级的模型——悄悄继承正是这个插件要防止的行为。提示词段落仍会写明这条规则，好让模型能解释拒绝的原因。
- 不再能解析的路由会被跳过并给出警告，其余路由继续工作。如果全都解析不了，工具就被注销。
- 模型不能选择 effort。 没有 effort 参数，子代理也从不继承父级的。
- 设置在 execute 内部重新读取，所以一步之前捕获的 schema 无法授权你此后删掉的路由。
- 前台调用被标记为并发不安全，因为它们共用一个与父级匹配的 effort 预留槽。
- 每个具名服务商先列出，再解析它的路由。 resolveModelInfo 不要求自己发现能力：适配器可能用只有 listModels 才会填充的缓存来回答，缓存冷的时候则报告一份静态回退列表。不先列出，服务商真正接受的 effort 就会被当作未宣告而拒绝。只列出 allowlist 点名的服务商，所以委派永远不会唤醒无关的适配器。

配置参考

| 字段 | 默认值 | 含义 |
| provider | spawn | 用来启动子代理的 ctx.subagents 服务商 |
| toolName | subagent | 模型看到的工具名；在活跃工具中必须唯一 |
| backgroundMode | continuable | continuable 返回一个持久子代理 id，可用 send_message 触达；one-shot 默认等待 |
| persona | — | 可选的子级人格，覆盖部署人格 |
| maxDepth | 3 | 每次启动的绝对深度上限；0 禁止启动，1 允许直接子级，provider-managed 不发送任何值 |
| toolFilter | — | 子级 { allow?: string[], deny?: string[] }；用 deny: [subagent, subagent_fork] 阻止嵌套委派，适用于同时暴露这两个工具的预设 |

查看子代理运行在哪个模型上

transcript 里每次 subagent 调用渲染一行：状态点（running / done / failed）、Subagent 字样、子级运行的路由，以及这次调用的简短描述。

这一行只读，不添加任何逻辑。路由就是工具本来就要求的 model 参数，所以没有新增日志，也没有新增计算。参数读不出来的调用——仍在流式输出、被中断，或由随附前端发起（它没有 model 参数）——渲染普通摘要，不声称任何模型，也不去猜。

这一行占用 subagent 这个工具名。带键的工具视图会替换通用行，而不是在它上面装饰，所以这是对这一个名字的有意接管；其他工具都保留随附的渲染方式。在 spawn 行里设置不同的 toolName，调用就会回退到通用行。

引导运行中的子代理

在当前 DSH 上，保留自带的 send_message：它已支持下一步引导和冷恢复。 下面介绍的是可选的旧版 lib/control.js 替换，用于较老的运行时，不是模型/深度强制执行的必需部分：

- id: tool-subagent-control
name: dsh-subagent-model/control

随附工具把每次投递都交给 ctx.subagents.followup()，它调用 Agent.followup()，因此目标是 next-turn。对于正处于回合中的子级——每步运行一个工具——消息会被接受，然后等整个回合结束，所以针对进行中工作的纠正，要等那项工作做完才到。在一次真实会话中实测：一个子级数到十，每回合一个 bash 步骤，引导在 +7.4s 被接受，在 +54.9s 才被认领，卡了 47.5 秒。

这个版本对运行中的直接子级调用 Agent.steer()，目标是 next-step，在下一个步骤边界被消费。其他情况都原样交给原生服务：空闲、等待或不存在的子级（唤醒和冷恢复由它负责），以及任何权限不匹配（权威拒绝由它负责）。归属记账和结算不受影响。

结果会报告走了哪条路径，即 delivery: 'next-step' 或 'next-turn'，这样模型就能判断纠正是否加入了当前回合。
转向请求与结算同时发生时，不会静默丢失：清理会清空收件箱，所以如果子代理在同一 tick 内离开注册表，投递就回退到原生路径。

路由

| 路由 | 用途 |
| GET /subagent-model/catalog | 设置卡片读取的模型目录：每条路由及其原生输入模态和对外公布的推理强度，加上 inherit/current 条目，再加上委派提示词的实时文本（prompt.value）和随包默认值（prompt.default），这样卡片就不必再存一份默认值副本。通过嵌套插件注入 webServer 注册，因此即使配置档里没有 web server，包也照样能挂载。 |

测试

node --test tests/*.test.mjs 覆盖纯模块；DSH_REQUIRE_RUNTIME=1 会额外要求 harness 包存在，这样缺少这些包的检出会直接报错，而不是跳过真实组合的测试套件。tests/delegation.test.mjs 锁定引导文本的渲染规则——包括配置过的提示词会替换随包文本、在组装时重新读取，以及空提示词不渲染任何内容——tests/integration.test.mjs 挂载真实的 SystemPrompt，断言模型实际收到的段落，既覆盖随包默认值，也覆盖用户自定义的替换文本。

npm test
运行 npm run test:runtime，前提是当前 DSH 包可解析，能 require 到 runtime 测试套件（缺 import 会失败，不会跳过）。child-policy.test.mjs 跑的是真实的 DSH 子级组合、执行过滤和描述符快照，不是完整的冷恢复端到端测试。policy.test.mjs 和 reservations.test.mjs 不依赖任何包——路由、effort 和预留匹配规则都是纯逻辑，不需要 harness。integration.test.mjs 把工具挂到真实的 Cordis 上下文上，配上真实的 ToolRuntime/SubagentRuntime，再用一个 capture provider 断言：构建出的 SubagentStartRequest 带上了选定的路由，其中也包括预置的 inherit 路由能复现出厂行为。defaults.test.mjs 锁定行为中性的种子。client-card.test.mjs 不开浏览器就能测浏览器卡片——它提供一个模块加载器和一个 React stub，后者记录元素树，然后断言插槽注册、Save 之前不写任何东西、Save 先写 efforts 再写 routes、删掉一条路由时它的 effort 也一并删掉。它用同样的方式驱动提示词编辑器：输入框显示已保存的文本；未设置的输入框从宿主路由填充，而不是声称自己是空的；敲键只是暂存，不写入；只有文本被编辑过，Save 才加上 prompt op；出厂默认值到达之前，Reset to default 不起作用；Discard 丢弃暂存的编辑；catalog 拉取失败绝不会丢掉已保存的文本；比卡片更老的 Host（它的路由只应答 routes）仍能保存路由编辑，而不会发出它会被拒绝的 prompt op。有一条回归测试守着最尖锐的边角：在设置文档或 catalog 加载完成之前编辑路由，绝不能种下空的提示词草稿——那会在下一次 Save 时写入 prompt: ''，悄悄把引导静音。它还拿卡片里用到的每个主题 token 去对照 Theme provider 发布的那一组，因为编造出来的 token 不会大声报错——CSS 会落到字面 fallback，所以一个拼写错误会让卡片渲染得没法读，而不是报错。依赖 harness 的套件在这些包不可解析时会自动跳过。

历史 live 端到端检查（预设组合之前）

下面的 overlay 早于常驻预设。不要用它去 patch 当前的预设： 请按上面的本地预设安装来做。这些历史结果不能作为当前 live 部署的验证。

tests/live-headless.patch.yml 跑的是真东西：它禁用配置档里出厂的 tool-subagent 行，在原位挂上这个前端，并把 PARENT 钉到一条不在 allowlist 上的路由，这样只要子级到达了选定的模型，就证明路由是被强制指定的，而不是继承来的。

dsh plugin --profile headless add /path/to/dsh-subagent-model
dsh --profile headless --patch tests/live-headless.patch.yml \
"Use the subagent tool once with model antigravity/gemini-3.7-flash and prompt 'name your model'."
真实运行验证过：父级用 unlimited/claude-sonnet-5，允许列表在 high 档强制 antigravity/gemini-3.7-flash，子代理持久化的 request/header 记录下 provider: antigravity、model: gemini-3.7-flash、reasoningEffort: high —— 说明 effort 桥接确实落到了真实请求上，不只是工具标签 —— 子代理也把自己报告为 Gemini 3.7 Flash。指定用户已删除的路由，会在执行前被 schema 枚举拒绝。

父级路由固定在补丁层，但 ~/.dsh/settings.yaml 里的 agent-default-model 块优先级更高：把它设成同一条路由，或者删掉它，否则运行会按 settings 指定的服务商启动。

已设计，未实现

docs/refork-spec.md 定义了 refork_subagent：把卡住或模型选错的子代理的整段对话换到另一条路由上继续，做法是把已完成的轮次历史复制进新子代理，而不是在没产出这段历史的模型上恢复旧子代理。

这份规格已经完整到可以直接照着实现 —— 每个机制都在当前源码里有出处，关键假设在真实卡住的子代理上测过，两处未验证的风险也已标注。提需求前有两点约束值得知道：子代理在轮次中途被杀会丢掉那半轮，因为种子必须结束在 turn/end；把带种子的子代理和可续模式组合起来，是已发布的 fork 服务商刻意回避的组合，所以得先测。

已知限制

- 前端必须挂载在你选定的预设里。 只靠宿主设置面板永远无法强制执行模型或深度策略。新的预设组合只对新会话生效，不影响已有对话。
- 替代的委派工具是独立的策略路径。 也要替换或禁用它们。子代理过滤器只覆盖过滤器里点名的继承工具，不覆盖任意受信任的子代理本地插件注册。
- lib/client.js 是手写的懒加载 CJS 工厂。 仓库的 tsdown 客户端预设没有发布，所以树外包必须自己复现那个产物格式。因此卡片直接用 React.createElement，自己画外壳 —— 客户端打包纯净度检查会拒绝跨插件值导入，所以它没法复用已发布的卡片组件。
- 卡片需要目录路由才能提供选项。 没有 web 服务器时，设置命名空间仍可从 YAML 工作；只是选择器和 effort 下拉框是空的，提示词框显示设置文档里有什么就显示什么，Reset to default 保持禁用，因为已发布的文本走那条路由。
- 每个服务商一行工具。 两行共用同一个 toolName 会在注册时冲突，这是有意设计。