ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 子代理:持久枚举、名称解析、后端句柄与消息中断到底该怎么对齐才不遗漏

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness子代理持久枚举SubagentResult
重启后找不到之前的子代理,或中断消息后句柄状态不一致。本文讲 activation 与能力标记的校验顺序、名称与 Session id 的分工、消息与中断的准入条件,以及持久枚举与结果字段的读取规则。

“重启后子代理不见了”与“消息发了但状态没变”,本质是同一件事:把名称当成了身份。 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 把没写过的话算到子代理头上。

验证:创建、重启、再枚举

验证要覆盖名称解析、离线恢复与结果分区三处。(来源) 六步:

  1. 用 startActivation 创建一个名为 reviewer 的子代理,断言 activation.name 与 childId 都可用。
  2. 调 resolveName(caller, 'reviewer'),断言返回 Session id;再用一个不存在的斜杠路径,断言报 AGENT_NAME_NOT_FOUND。
  3. 重启后调 list_agents,断言仍能看到该子代理,状态为 inactive。
  4. 向其发送一条消息,断言发生冷恢复;再次重启后发消息依然可用。
  5. 断开运行中的子代理,断言目标是接收 Steer 而不是新开一轮。
  6. 让子代理以 max-tokens 结束,断言 stopReason 正确、output 被视为部分内容,diagnostic 单独呈现。

如果第 4 步失败,先确认外部执行是否被误用——外部后端拒绝后续输入,这与“子代理不存在”是两回事。

子代理的接入与委派,可以对照子代理提供方与子代理委派配置;持久化侧的恢复边界见持久化 seam。

一句话收束: 能力先校验、句柄只释放本次、名称不等于身份、离线靠冷恢复、目录不记状态、结果与清理失败要分开读。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的子代理名称能当身份用吗,还是只能当引用?

不能,DSH plugin 用 Session id 做唯一执行身份。DSH plugin 的 name 只是面向模型的引用,用于路由、授权、持久化和归属判断的始终是 Session id。

DSH plugin 能向已经离线的子代理发消息吗,还是要冷恢复?

不能直接发,DSH plugin 只冷恢复不在线的目标。DSH plugin 的 sendMessage 要求确切在线发送方与同一根树中的目标 Session id,外部执行会拒绝后续输入。

DSH plugin 请求了结构化输出,就一定拿得到结构化结果吗?

不一定,DSH plugin 请求 schema 不保证产出。DSH plugin 在子代理失败或结束时没拿到合法捕获,提供方可以以 error 结束,此时 structured 缺失。

DSH plugin 拆卸失败的时候,会覆盖已经拿到的运行结果吗?

不会,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 官方参考 - 子代理

来源