9.7 KiB
description, kind
| description | kind |
|---|---|
| 子级作用域 report 工具，供用户与维护者组合或排查可继续 subagent 的子到父返回通道。 | package-reference |
@deepseek-ai/dsh-tool-subagent-report
English | 中文
概述
dsh-tool-subagent-report 为每个可继续的进程内子级提供一条返回通道，指向启动它的 agent（智能体）：它安装子级作用域的 report 工具，以及指示子级使用该工具的提示词指导。工具及其指导只存在于这些子级内部——根 agent、一次性 subagent、远程提供方与同级作用域永远看不到它们。被接受的报告会以普通父级消息到达父级，前缀为 Background subagent <child-id> reported:。可继续模式不依赖本包，也不依赖控制包；本包只负责子到父方向。
目录
使用本包
在包含可继续进程内子级、且父级应在子级结束前看到其发现的组合中挂载本包。工具及其指导会自动出现在每个可继续子级内部；无需任何按子级的配置。
最小配置
先加载 subagent 服务、一个后端、处于 continuable 模式的委派工具与本包：
- name: '@deepseek-ai/dsh-subagent'
- name: '@deepseek-ai/dsh-subagent-spawn-in-process'
- name: '@deepseek-ai/dsh-tool-subagent'
config:
provider: spawn
backgroundMode: continuable
- name: '@deepseek-ai/dsh-tool-subagent-report'
| 字段 | 默认值 | 含义 |
|---|---|---|
reportDelivery |
next-step |
已接受报告的父级调度：next-step 在最近 step 边界唤醒父级；quiet 添加相同上下文但不唤醒 |
生成的配置目录是每个受支持字段及其 JSDoc 的穷尽式真源。
子级获得什么
每个可继续子级都会获得一个 report 工具，其唯一参数是 output——给父级的自足答案——以及一段提示词 section，指示子级在结束前调用一次 report，并在部分发现会改变父级下一步动作时提前调用。该指令是引导而非强制：一个轮次内子级可以调用零次或多次，结束轮次也绝不会自动上报。调用成功既不会结束轮次，也不会结算子级的 Activation。
父级看到什么
被接受的报告会成为一条用户角色的父级消息，以 Background subagent <child-id> reported: 开头，后接子级未经改动的输出，并带有指明子级的持久化来源。next-step 投递会唤醒空闲父级，或加入运行中父级最近的 step 边界；quiet 投递添加相同上下文但不唤醒父级。工具不接受接收方参数：服务根据子级持久化的 parentSession 推导唯一接收方。
作用域与方向
report 工具有意不受子级全局 toolFilter 影响：委派允许列表无法移除唯一的返回通道。要求子级不具备返回通道的部署应省略本包。父到子方向仍由独立安装的控制包负责，可继续模式不依赖这两个包中的任一个。
理解实现
实现细节——点击展开
本节解释工具的安装与调度方式；可观察行为已在使用本包中说明。
设计理念
本包注册的是可继续子级设置贡献，而非全局工具，因此工具及其指导安装于每个子级未发布的作用域内部，并随其一同消失。这些注册都是普通的子级作用域贡献，因此专家级 system-prompt/assemble 监听器可以替换它们，替换后则由其负责为该子级保留上报协议。
投递调度
next-step 使用 parent.steer()：运行中的父级在最近的安全 step 边界接收报告，空闲父级启动一个轮次，按顺序接受的报告共享 next-step FIFO。quiet 使用 parent.inject()，添加相同的 next-step 上下文但不唤醒停驻的父级。两者都是部署策略：面向模型的 schema 不能在单次调用中选择或覆盖投递方式。
导出的贡献
installReportTool(childCtx, ctx, delivery) 把工具及其指导安装到新创建的子级作用域中，并返回同时撤销两者的唯一 disposer。生成工具目录使用这条路径，因为全局注册表无法公开作用域局部 schema；生产组合仍通过 apply() 进入。
源码地图
| 文件 | 职责 |
|---|---|
src/index.ts |
可继续子级设置：installReportTool、Config、投递解析 |
src/invariant.ts |
不变式伴生插件 |
进一步探索
当包级约定不够用时阅读以下页面；它们从上报通道进入其背后的继续执行服务与面向父级的工具。
- Subagent 子系统——可继续子级、Activation 与
reportFrom/reportDelivery约定。 - dsh-tool-subagent-control——父到子的控制工具。
- dsh-tool-subagent——启动可继续子级的委派工具。
- 生成工具目录——
report的 schema。 - 生成配置目录——每个受支持配置字段。
模型体验
工具 schema
模型看到什么
已生成的 report schema：一个必填 output 字符串。其描述说明子级必须在结束前上报一次，上报只会到达启动该子级的 Agent，并且不会结束轮次。它不包含接收方或投递模式参数。独立的 tool:report 提示词 section 在 schema 之外重申该义务。
Token 影响
每个可继续子级请求支付固定的 schema 与提示词 section 成本，其他任何 Agent 的请求均无此成本。
KV Cache 影响
子级中的前缀保持稳定；schema 与该 section 都不会在运行时改变。移除本包会从驻留子级中撤销两者，从而改变其下一次请求前缀。
上报结果
模型看到什么
接受时返回 report accepted by the agent that started you as message <messageId>；规范输出携带稳定的 messageId。发送方未授权、父级不可用或生命周期正在关闭时，会返回出错结果。描述中会说明，失败的调用仍可能已经送达，因为 reportFrom() 接受消息后，后续 tools/post-execute 失败可能替换工具结果。
Token 影响
每次调用都会在执行上报的子级中产生一条简短确认消息。父级还会为上报内容支付 token 成本：next-step 投递会加入父级已打开轮次的下一次请求，或为空闲父级启动一个轮次；静默投递则等待其他输入唤醒父级。
KV Cache 影响
在子级中仅追加。在父级中，带前缀的报告位于现有历史之后，并保留可复用前缀。
父级可见的报告
模型看到什么
一条用户角色的父级消息，以 Background subagent <child-id> reported: 开头，后接子级未经改动的 output，并带有指明该子级的持久化来源 { kind: 'subagent-report', senderSessionId: <child-id> }。
Token 影响
子级的完整 output 加上一行前缀；本包不设上限。
KV Cache 影响
仅追加；报告位于父级可复用请求前缀之后。next-step 投递会唤醒父级，并可能延长其已打开的轮次；静默投递则不会唤醒父级。
已知限制与延期工作
这些限制说明被接受的报告保证什么、不保证什么；它们是当前包约束。
- 父级可能在宿主启动 dispose 后继续接受报告——
AgentHandle.dispose()会先取消并等待完全停稳，然后才撤销作用域并离开注册表；它不公开「dispose 已开始」信号。在该窗口内接受的报告会追加到父级 transcript（文本记录），但该父级不会在本进程中处理它。对于由继续执行管理器拥有的父级，管理器的准入边界会在整片森林拆卸期间拒绝该上报。 - 接受弱于持久投递——没有持久化 mailbox、幂等键、投递回执、重试协议，也不保证恰好一次。任一侧记录接受后若进程失败，结果都不明确；外部重试可能产生重复上报。
- 暂存的静默报告无法立即重建——接受时会返回其稳定
MessageId，但只有当待处理上下文到达普通日志边界后，父级会话才能重建带前缀的内容。 - 授权须等到下一个 Activation，撤销则立即生效——子级驻留后再安装本包，只会在该子级的下一个 Activation 中授予
report及其指导；移除本包则会立即从驻留子级撤销两者。 - 嵌套上报只向上到达一条直接边——孙级只向作为其直接父级的子级上报，不会直接到达顶层协调器；该直接父级必须随后显式发出一条衍生更新。
- 没有速率限制——嵌套子级频繁上报时，默认的
next-step模式会放大模型工作量，但一起等待的报告会共享一个 step；宁可接受报告无人阅读也要避免这种放大的部署应选择quiet。
开发备注
维护者的工作上下文——点击展开
无。