@xmoon76/dsh-subagent-router

dsh plugin --profile web add @xmoon76/dsh-subagent-router

@xmoon76/dsh-subagent-router

[English](README.md) | 中文

一个面向模型的 DSH 插件,用于在模型选定的 LLM provider 与 model 上启动子 agent(subagent)。模型选择路由(provider/model);部署方拥有子 agent 后端(subagentProvider,默认 spawn)、默认调度策略(backgroundMode)与路由白名单(allowedProviders)。单次调度的调度方式可用可选参数 run_in_background 覆盖,与官方 @deepseek-ai/dsh-tool-subagent 工具完全一致。continuable 子 agent 的后续轮次复用 @deepseek-ai/dsh-tool-subagent-control 的官方 send_message / list_agents / interrupt_agent 工具;后台 one-shot 任务用 @deepseek-ai/dsh-tool-jobs 的官方 job_output / job_kill 工具收集。

安装(以 DSH profile bundle 方式)

本包以 DSH profile bundle 形式发布:其 cordis.patch.yml(dsh.bundle.patch)会在 profile 组合中自动插入两个 router 行——tool-subagent-router(spawn + continuable,subagent_route)与 tool-subagent-router-fork(fork + one-shot,subagent_fork_route)。前提是 profile 的 bundles 包含 @deepseek-ai/dsh-base(所有官方 web/headless 模板都满足)——subagents 注册表及其 spawn/fork 后端来自该 base 层。

dsh plugin --profile <name> add @xmoon76/dsh-subagent-router

该命令把包安装进 profile,并把它加入 profile 的 dsh.profile.bundles 层列表;下次启动时其 patch 按下方默认配置插入两个 router 行(tool-subagent-router 与 tool-subagent-router-fork)。若要覆盖默认值,在 profile 自己的 cordis.patch.yml 里 patch 对应行 id(patch 会替换该行整个 config):

- id: tool-subagent-router
  config:
    allowedProviders:
      - deepseek-official

使用指南(Usage walkthrough)

下面是一个面向模型的实际调用流程。派发前请确认 profile 已注册 router 工具(subagent_route / subagent_fork_route)，且所选 provider/model 路由已经配置。

启动可继续的子 agent(默认后台)

subagent_route 的 description / prompt / provider / model 全部必填。模型只选择 LLM 路由；部署配置仍拥有后端与默认调度策略：

{
  "description": "say hi",
  "prompt": "请简短地打个招呼，然后说明你正在使用哪个模型。",
  "provider": "codex",
  "model": "gpt-5.6-luna"
}
// continuable 结果：started subagent <id>

continuable 结果只确认 inbox 已接受请求并返回持久 id，不包含子 agent 回复。请等待 DSH settlement notice，或按 id 查看子 agent transcript。

同步等待全新子 agent

当下一步必须依赖子 agent 结果时，设置 run_in_background: false。该调用会以前台方式运行子 agent 并直接返回其最终输出，而不是返回 id：

{
  "description": "review implementation",
  "prompt": "Review the diff and report concrete risks.",
  "provider": "codex",
  "model": "gpt-5.6-luna",
  "run_in_background": false
}
// foreground 结果：子 agent 的最终输出

多轮继续对话

子 agent 被接受后，使用官方 send_message 控制工具排队下一轮 FIFO 消息：

{
  "subagent_id": "<id>",
  "message": "你最擅长哪些工程任务？"
}
// message queued as the next turn for subagent <id>

后续轮次及 cold resume 都保持创建时的 provider/model；不支持会话中途切换路由。

配套控制工具

以下控制工具不属于本包：继续控制必须从官方 @deepseek-ai/dsh-tool-subagent-control 插件单独挂载，后台任务控制来自官方 @deepseek-ai/dsh-tool-jobs 插件：

工具 · 用途

send_message · 向持久子 agent 排队下一轮(FIFO)。

list_agents · 列出或回忆已启动的子 agent。

interrupt_agent · 中断正在运行的子 agent 轮次。

job_output · 收集后台 one-shot 任务的输出。

job_kill · 停止后台 one-shot 任务。

官方委托工具(subagent、subagent_fork)是另一回事：它们是 @deepseek-ai/dsh-tool-subagent 的不同实例，绑定固定的部署路由。本 router 从不替换它们——参见下方[官方工具共存](#官方工具共存)。

启动动态 fork(one-shot)

subagent_fork_route 由 bundle 默认挂载(fork + one-shot),因此继承父会话已完成轮次的 fork 子 agent 开箱即用。实例使用不冲突的名字(绝不用官方 subagent_fork)：

# bundle 插入的默认值(可在 profile 里按 row id 覆盖)
- id: tool-subagent-router-fork
  config:
    subagentProvider: fork
    toolName: subagent_fork_route
    backgroundMode: one-shot
    enableRunInBackground: true
    maxDepth: 3

模型调用(默认等待结果)：

{
  "description": "review prior design",
  "prompt": "Review the design discussed above and identify correctness or maintainability risks.",
  "provider": "openai",
  "model": "gpt-5.6"
}
// foreground 结果：子 agent 的最终输出

Fork prompt 语义：子 agent 已经看到父会话的已完成轮次，prompt 只需写新增任务；当前 in-flight 父轮次不在 fork seed 中。

后台运行 fork

设置 run_in_background: true 注册一个后台 Task 并立即返回其 job id：

{
  "description": "deep review",
  "prompt": "Perform a deep review of the design.",
  "provider": "codex",
  "model": "gpt-5.6-luna",
  "run_in_background": true
}
// background 结果：started background subagent job <id>

用 job_output 收集结果，用 job_kill 停止工作。后台 fork 是一次性 Task，不是 continuable 子 agent：不能用 send_message 继续它。

最佳实践

• 全新(spawn)子 agent 的 prompt 要自包含：它看不到父会话。
• fork(fork)子 agent 的 prompt 只需写增量：子 agent 继承父会话已完成轮次，只写新任务即可；当前 in-flight 轮次不在 fork seed 中。
• 派发前确认 provider/model 可用。没有模型发现工具，路由错误可能直到子 agent 首次解析路由时才出现。
• 把 continuable 启动结果当作确认而非子 agent 答案；实际结果通过 settlement notice 和 transcript 获取。
• 独立委派优先使用后台默认：在同一个 assistant turn 里一起启动多个子 agent，并在它们运行期间继续做其他有用工作；只有下一步依赖结果时才用 run_in_background: false。
• 如果部署策略需要限制路由，用 allowedProviders 配置；不要依赖 prompt 文案强制执行。
• 不要把凭证、endpoint、headers 放进 prompt 或工具参数；多实例挂载时为每个实例使用唯一的 toolName。
• 记住 maxTokens 不会在 activation 之间持久化。

为什么需要这个包

官方 @deepseek-ai/dsh-tool-subagent 把一个实例绑定到一个固定的子 agent agentOptions(部署固定 provider/model)。本插件把 LLM 路由选择交给模型,同时让所有能力仍由 DSH seam 拥有:它只是 ctx.subagents.startContinuable() / ctx.subagents.start() 与 ctx.jobs 之上的薄 Consumer,不重新实现 continuation、session、持久化、权限、任务或队列。调度与生命周期语义其余部分与官方工具一致。

契约(Contract)

面向模型的工具 subagent_route / subagent_fork_route 接受相同的参数:

参数 · 必填 · 含义

description · 是 · 委托任务的简短(3-5 词)标签。

prompt · 是 · 完整独立任务(全新子 agent)或基于已完成轮次的增量(fork 子 agent)。

provider · 是 · 子 agent 使用的已配置 DSH LLM provider 路由。

model · 是 · 子 agent 对话使用的 model id。

run_in_background · 否 · 调度覆盖。continuable 实例默认 true(返回持久 id);one-shot 实例默认 false(返回最终输出)。enableRunInBackground: false 时该参数不存在。

成功时根据实例的 backgroundMode 与本次调用的 run_in_background 返回三种规范结果之一:

类型 · 何时 · 结构

continuable · continuable 模式 + 后台(默认) · { kind: 'continuable', subagentId } —— 持久 id,inbox 接受时解析

foreground · 任意模式 + run_in_background: false(或 one-shot 默认) · { kind: 'foreground', runId, output } —— 子 agent 最终输出

background · one-shot 模式 + run_in_background: true · { kind: 'background', jobId } —— 用 job_output 收集,job_kill 停止

凭证、endpoint、headers、maxTokens、outputSchema 与后端选择绝不暴露给模型。

配置(Config)

键 · 默认 · 含义

`

…(truncated)