DSH plugin 子代理:持久枚举、名称解析、后端句柄与消息中断到底该怎么对齐才不遗漏
“重启后子代理不见了”与“消息发了但状态没变”,本质是同一件事:把名称当成了身份。 DSH plugin 的子代理用 Session id 做唯一执行身份,名称只是面向模型的引用。把这两层分开,持久枚举与消息中断才有稳定语义。 DSH插件 派子代理时,名称只是引用,Session id 才是身份。
统一 activation,能力标记先校验
所有后端都走 startActivation,能力标记在创建前就把不合规选项挡掉。(来源)
统一的 activation API 管理本地对话与外部执行,创建祖先关系、运行归属和通信由 subagent 树管理。所有后端都使用 startActivation:能力标记校验请求选项,prepareContinuable 选择本地 Agent 创建,start 选择一次外部执行。
SubagentCapabilities 有四个标记:agentOptions、agentPreset、outputSchema 与 depthLimit。管理器会在准备本地子级或启动外部执行之前,逐项检查请求里用到的能力。depthLimit 控制 maxDepth,其余标记名与 SubagentStartRequest 字段一一对应。
cwd 的解析规则要留意:相对路径以父级当前有效目录为基准;省略时在准入阶段捕获该目录。本地子 Session 保留父级的原始项目,冷恢复保留其日志中的目录状态。
面向模型的工具采用 parent 回传;Workflow 与 code mode 消费者可以等待 caller 结果,不额外向父代理注入消息。历史子会话的 descriptor 不可用时,以 mode: 'unknown' 保持可发现性,但不授予继续执行能力。
spec 与句柄:释放只针对这一次
dispose() 释放的是这次 activation,不是之后的某次 resume。(来源)
SubagentActivationSpec 在启动请求之外多出五项:provider、label(保留在编目的子成员里)、name、可选 childId、signal 与 delivery。
name 的规则很具体:在父级子级中唯一,1 到 32 个小写字母、数字或连字符,以字母开头,且不能是 lead;省略时选第一个空闲的 agent-N。childId 是本地子级可预留的身份,外部后端自行分配 id。
delivery 决定投递语义:parent 会通知模型;caller 只把结果返回调用方。本地子级永远进入父级目录,与投递方式无关。
SubagentActivation 提供 childId、name、可选 messageId、result 与 dispose()。result 在拆卸落定且通知发出后兑现;dispose() 只停止并释放这一次 activation,拆卸失败以拒绝报告,不会覆盖已捕获的结果。
名称是引用,Session id 才是身份
resolveName 只做解析,不授予任何权限。(来源)
Session id 仍是路由、授权、持久化和任务归属使用的唯一执行身份;名称是面向模型的引用。SubagentActivation.name 是子级的完整名称:当从根开始的每一级都有名称时,listDescendants() 的行以 path 携带该名称。
namesOf(agent) 报告在线成员及其直接创建者的名称,根的名称为 lead。resolveName(caller, name, signal) 对 lead 或完整名称返回对应 Session id;树中不存在的其他文本会原样作为 Session id 返回,而指向无成员的斜杠路径以 AGENT_NAME_NOT_FOUND 失败。
最后一句很重要:调用方授权解析结果,解析本身不授予权限。也就是说“名字能解析到”不等于“你有权操作它”。
消息与中断需要确切在线身份
跨分支可以发,离线只能冷恢复,外部执行不接受后续输入。(来源)
sendMessage 要求确切在线发送方和同一根树中的目标 Session id。根与可继续成员可以跨分支发消息;接纳时会重新校验发送方和根。运行中目标接收 Steer;只冷恢复不在线的目标,其创建祖先可以保持离线。外部执行拒绝后续输入。
通知路径也有限定:本地和外部执行仅向仍在线的直接创建者报告最终文本、结构化输出、诊断和状态;caller 投递抑制这些通知。
释放范围要分清:drainDescendants 等待整棵树释放;activation 回执的 dispose() 仅释放那一次执行。
中断有明确的授权形态:user 是受信宿主操作;Remote 调用方需要对目标 Session 有权限才能调用;ancestor 携带目标创建祖先中的确切活 Agent。
持久枚举与后端句柄
目录记成员关系,不记执行状态。(来源)
父级拥有的 subagentCatalog 投影列出所有本地子级及 parent 投递的外部子级。caller 投递的外部执行由调用方负责成员关系与结果收集;本地工作流子级在完成后仍可被发现。
外部条目携带 mode: 'external',不能打开子 Session 或接受后续消息。目录在创建时记录成员关系,不携带执行状态。list_agents 展示根和可达的可继续后代,活跃状态为 running 或 inactive。
结果侧,SubagentResult 供程序消费方读取。activation 注册表保留外部后端句柄,直到释放完成。
清理失败的处理方式很克制:不覆盖已捕获的执行结果——activation 结果与父级通知保留该结果,dispose() 拒绝,而在线的 subagent/end 事件报告 error。所以你看到 dispose 失败时,不要顺手把结果也当成失败。
结果字段的读取顺序
output 与 structured 是两条独立通道,diagnostic 要单独展示。(来源)
output— 子级最终 assistant 输出,取自最后一条非空 assistant 消息的内容;空内容消息(含只有 usage 的)跳过。没有非空消息时,用它累计的 assistant 文本流,两者都没有则为[]。structured— 请求过outputSchema且成功满足后的结构化结果。请求不代表一定有:子级失败或结束时没有合法捕获,提供方可以以stopReason: 'error'结束。diagnostic— 提供方撰写的非 assistant 失败细节,必须不含工具输入、文件内容、环境值、凭证与原始协议载荷,且限制在 4096 个 UTF-8 字节内;消费方要把它与output分开呈现。stopReason— 可合并扩展的结束原因,已知取值为completed、aborted、error、max-tokens与refusal。
非 completed 的原因意味着 output 可能是部分内容。工具层据此把非 completed 结果映射为 isError 工具结果,而不是把半截输出当成功。
消息来源也做了区分:AgentMessageSource 的 kind 是 agent-message,表示另一个 agent 发来的内容;SubagentSettledMessageSource 的 kind 是 subagent-settled,是运行时的结算说明。把两者合并会让 transcript 把没写过的话算到子代理头上。
验证:创建、重启、再枚举
验证要覆盖名称解析、离线恢复与结果分区三处。(来源) 六步:
- 用
startActivation创建一个名为reviewer的子代理,断言activation.name与childId都可用。 - 调
resolveName(caller, 'reviewer'),断言返回 Session id;再用一个不存在的斜杠路径,断言报AGENT_NAME_NOT_FOUND。 - 重启后调
list_agents,断言仍能看到该子代理,状态为inactive。 - 向其发送一条消息,断言发生冷恢复;再次重启后发消息依然可用。
- 断开运行中的子代理,断言目标是接收 Steer 而不是新开一轮。
- 让子代理以
max-tokens结束,断言stopReason正确、output被视为部分内容,diagnostic单独呈现。
如果第 4 步失败,先确认外部执行是否被误用——外部后端拒绝后续输入,这与“子代理不存在”是两回事。
子代理的接入与委派,可以对照子代理提供方与子代理委派配置;持久化侧的恢复边界见持久化 seam。
一句话收束: 能力先校验、句柄只释放本次、名称不等于身份、离线靠冷恢复、目录不记状态、结果与清理失败要分开读。
常见问题
不能,DSH plugin 用 Session id 做唯一执行身份。DSH plugin 的 name 只是面向模型的引用,用于路由、授权、持久化和归属判断的始终是 Session id。
不能直接发,DSH plugin 只冷恢复不在线的目标。DSH plugin 的 sendMessage 要求确切在线发送方与同一根树中的目标 Session id,外部执行会拒绝后续输入。
不一定,DSH plugin 请求 schema 不保证产出。DSH plugin 在子代理失败或结束时没拿到合法捕获,提供方可以以 error 结束,此时 structured 缺失。
不会,DSH plugin 保留已捕获结果。DSH plugin 让 activation 结果与父级通知保留该结果、dispose 拒绝,而在线 subagent/end 事件报告 error。
相关术语
- SubagentCapabilities
- SubagentCapabilities 是后端支持的可选能力标记,含 agentOptions、agentPreset、outputSchema 与 depthLimit。— packages/subagent/subagent/src/types.ts
- SubagentActivation
- SubagentActivation 是一次受管子执行的回执,含 childId、name、可选 messageId、result 与 dispose。— packages/subagent/subagent/src/types.ts
- SubagentResult
- SubagentResult 是子代理运行的终态结果,含 output、可选 structured、可选 diagnostic 与 stopReason。— packages/subagent/subagent/src/types.ts
- subagentCatalog
- subagentCatalog 是父级拥有的投影,列出全部本地子级与 parent 投递的外部子级,创建时记录成员关系。— DeepSeek Harness 官方参考 - 子代理
来源
- DeepSeek Harness 官方参考 - 子代理· deepseek-ai
- packages/subagent/subagent/src/types.ts· deepseek-ai