子代理管控 SpaceRelay/dsh-subagent-control

dsh-subagent-control

English · 简体中文

三个工具，让任何 DSH 智能体——包括团队成员——列出、引导并停止它启动的子代理。

list_subagents · send_subagent_message · interrupt_subagent

问题

Harness 自带 list_agents、send_message 和 interrupt_agent。启用 Agent Team 包后，它会在每个团队成员各自的 Agent 作用域里注册同样这三个名字的工具，而更具体的注册会胜出。在队友作用域内，团队版本接管：它们只在团队名册里解析 target，而且中断是仅限 Lead 的操作。

结果：队友可以用 subagent 启动子代理，却无法列出它、跟进它或停止它——尽管子代理服务（ctx.subagents）一直支持对任何活跃智能体做这三件事，其权限规则也早已允许祖先管理自己的后代。

这个包不去争抢已被占用的名字。它在全局注册三个新名字，让 Lead 和每个队友立刻都能用上。

工具

| 工具 | 参数 | 底层调用 |
| list_subagents | scope?："children" \| "descendants"（默认 children） | ctx.subagents.listChildren() / listDescendants() |
| send_subagent_message | subagent_id、message（均必填） | ctx.subagents.sendMessage() |
| interrupt_subagent | subagent_id（必填） | ctx.subagents.interrupt()，带祖先权限 |

用法

list_subagents
→ 3b0f9c1e running "review the patch" depth=1

list_subagents scope=descendants
→ 3b0f9c1e running "review the patch" depth=1
7d2a44b0 inactive "check the tests" depth=2

send_subagent_message subagent_id=3b0f9c1e message="also look at locale/zh.json"
→ messageId=...

interrupt_subagent subagent_id=3b0f9c1e
→ accepted=true

列表每行格式为 id status "label" depth=。status 取 running 或 inactive——inactive 表示当前没有回合在执行，不代表子代理已经消失。用 send_subagent_message 唤醒它。

团队成员也是可继续的子代理，所以同样会出现在这个列表里，标记为 team=teammate（或 team=lead）。只想看自己启动的普通子代理时，传 include_teammates: false。

行为与限制

- 一次性子代理会隐藏。 它们无法接受跟进消息，列出来只会诱使你发起一次注定失败的调用。
- 损坏记录只上报，不抛错。 状态读不出来的子项会作为诊断条目返回（corrupt / unsupported / unavailable），不会让整个列表变成错误。
- send_subagent_message 只能触达直接子级。 这是服务自身的规则，插件不会放宽。
- interrupt_subagent 能触达后代，所以团队 Lead 也能停止孙级子代理。
- 每次失败都会说明原因：没有调用方智能体、未知 id，或 id 不属于你。
- 无配置，无存储。 插件包不写入任何内容，也不读取三个服务之外的任何东西。

安装

通过插件面板 / 市场安装，或者让智能体执行：

plugin_manager install_bundle target "dsh-subagent-control@1.0.0"

从本地检出安装时，传目录路径，不要传 npm 包名。插件包立即生效，无需重启。装好后三个工具名可见，插件行处于启用状态。

兼容性

- DSH，需带 tools、subagents 和 agents 服务（0.2.x 及更高版本）。
- Node ^22.19.0 || >=24.0.0。
- 零依赖 —— 没有运行时依赖，没有 peer 依赖，连一个 import 都没有。这些工具就是普通的工具表对象，带显式 JSON Schema，所以从 npm 安装和从链接的检出安装，行为完全一致。

名称冲突

dsh-subagent-library 也注册了全局工具 list_subagents。同一个名字注册两次，不可能两个都生效：二者只装一个，或者记住另一个可能遮蔽这个。

三个新名字之所以这样取，正是因为它们不与内置的 list_agents / send_message / interrupt_agent 冲突。

卸载

在插件面板里移除或禁用插件包。不会留下任何残留。

可选组件（默认全部关闭）

四个额外工具以独立组件形式提供，每个在插件面板里都有自己的行和开关（Cross-layer relay、Wait for subagents、Release subagents、Delegation budget）。四个组件初始都是禁用状态；打开一个只注册一个工具，所以你可以只启用需要的。

| 组件 | 工具 | 作用 | 风险 |
| Cross-layer relay | relay_subagent_message | 尽力向更深层的后代发消息：投递给第一跳，并请求它继续往下转发 | 中间智能体可能做摘要；不保证送达 |
| Wait for subagents | wait_subagents | 等待后代（受 timeout_seconds 限制），而不是先结束自己的回合 | 最多阻塞到超时 |
| Release subagents | drain_subagents | 停止并释放直接子代理，不同于 interrupt_subagent，后者只停止当前回合 | 已释放的子代理无法再被消息唤醒 |
| Delegation budget | subagent_budget | 只读报告：深度上限、树有多深、运行中/非活跃数量 | 无 |

另有一个配套插件包 dsh-team-limits，用来提高 Agent Team 的各项上限（成员数、任务数、消息字节数）。它故意做成单独安装：它会覆盖内置的 agent-team 行，这种事绝不该隐式发生。

第二个配套插件包 dsh-human-wait，让 PTC run_code 的截止时间不再把你回答问题、审阅方案或批准请求所花的时间算进去。PTC 模式会包住整个程序 —— 嵌套的工具等待和审批等待一并算进 120 秒的实际耗时里，所以慢响应以前会报 Error: code run failed (timeout): execution deadline reached (120000ms)。装上这个包之后，这段等待不再消耗预算（默认上限 24 小时，-1 表示不限），而真正失控的程序仍会在正常预算处被拦下。

同系列的 UI 插件 dsh-find-session 增加了会话关键词搜索：Ctrl+F 搜索你当前所在的会话，Ctrl+Shift+F 搜索所有已存储的会话，并把命中结果列在右侧边栏。它需要单独安装——它是浏览器侧的面板，不属于子代理工具链，Host 那一半只读取会话日志。

许可证

MIT —— 见 LICENSE。问题反馈与源码在 github.com/SpaceRelay/dsh-subagent-control。

它解决什么问题

Harness 自带 list_agents、send_message、interrupt_agent。开启 Agent Team 后，团队插件会把同名的三个工具注册进每个团队成员的精确作用域，而更具体的作用域优先。于是在成员作用域里生效的是团队版：target 只认队友名，打断只有组长能做。

结果是：团队成员能用 subagent 派出子代理，却列不出、追问不了、也打断不了它。而底层的子代理服务（ctx.subagents）本来就支持这三件事，权限规则也允许祖先管理自己的后代。

本插件不去抢那三个被占用的名字，而是全局注册三个新名字，组长和每个组员立刻都能用。

工具

| 工具 | 参数 | 底层调用 |
| list_subagents | scope?："children" 或 "descendants"，默认 children | ctx.subagents.listChildren() / listDescendants() |
| send_subagent_message | subagent_id、message（均必填） | ctx.subagents.sendMessage() |
| interrupt_subagent | subagent_id（必填） | ctx.subagents.interrupt()（祖先权限） |

用法

list_subagents
→ 3b0f9c1e running "review the patch" depth=1

list_subagents scope=descendants
→ 3b0f9c1e running "review the patch" depth=1
7d2a44b0 inactive "check the tests" depth=2

send_subagent_message subagent_id=3b0f9c1e message="顺手看一下 locale/zh.json" → messageId=...

interrupt_subagent subagent_id=3b0f9c1e
→ accepted=true

每行格式是 id status "label" depth=。status 为 running 或 inactive——inactive 表示当前没有在跑，不代表子代理已经消失；用 send_subagent_message 可以把它叫醒。

团队成员本身也是可续子代理，所以同样会出现在列表里，并带 team=teammate（或 team=lead）标记；只想看自己派的普通子代理时，传 include_teammates: false。

行为与边界

- 一次性子代理不会被列出。 它们无法接收后续消息，列出来只会诱导一次注定失败的调用。
- 记录损坏时报告，而不是抛错。 某个子代理状态读不出来，会作为诊断条目（corrupt / unsupported / unavailable）返回，而不是让整个列表失败。
- send_subagent_message 只能发给直接子代理。 这是服务本身的规则，插件没有放宽。
- interrupt_subagent 覆盖所有后代，所以组长也能打断孙代。
- 任何失败都说明原因：没有调用者、id 不存在、或者不是你的子代理。
- 不写配置、不落存储。 除了这三个服务，插件不读写任何东西。

安装

在插件面板 / 市场中安装，或者让智能体执行：

plugin_manager install_bundle target "dsh-subagent-control@1.0.0"

从本地目录安装时，把 npm 规格换成目录路径。安装即时生效，无需重启；装完后三个工具名可见、插件行为已启用。

兼容性

- 具备 tools、subagents、agents 三个服务的 DSH（0.2.x 及以上）。
- Node ^22.19.0 || >=24.0.0。
- 零依赖：没有运行时依赖、没有 peer 依赖，模块里一行 import 都没有。工具是带显式 JSON Schema 的普通定义对象，所以 npm 安装与软链安装行为完全一致。

撞名

dsh-subagent-library 也注册了全局的 list_subagents。同一个名字的两个全局注册不可能同时生效——二选一安装，或记住其中一个可能被另一个覆盖。

这三个新名字是特意挑的，不会和内置的 list_agents / send_message / interrupt_agent 冲突。

卸载

在插件面板里移除或停用即可，不会留下任何残留。

可选组件（各自默认关闭）

另外四个工具是四个独立组件，在插件面板里各有自己的一行和一个开关（中文界面显示：跨层补话 / 等待子代理 / 释放子代理 / 委派预算）。四个都默认关闭，打开哪一个就只注册那一个工具——只开你需要的。

| 组件 | 工具 | 作用 | 风险 |
| 跨层补话 | relay_subagent_message | 把消息投给第一跳并请它继续向下转发 | 中间层可能改写，不保证送达 |
| 等待子代理 | wait_subagents | 等后代结束再收工（受 timeout_seconds 限制） | 会阻塞到超时 |
| 释放子代理 | drain_subagents | 停止并释放直接子级；interrupt_subagent 只停当前回合 | 被释放的子级不能再靠消息唤醒 |
| 委派预算 | subagent_budget | 只读报告：深度上限、树有多深、运行/空闲数量 | 无 |

另有一个独立的同伴包 dsh-team-limits，用来提高 Agent Team 的成员数、任务数与消息字节上限。它刻意做成单独安装：它覆盖的是宿主自带的 agent-team 行，这种事不该偷偷发生。

还有一个独立的同伴包 dsh-human-wait，用来让 PTC 模式 run_code 的执行预算在「等你回答提问 / 审议计划 / 审批」期间暂停。PTC 会把整个程序——包括嵌套的工具调用与审批等待——包在一个 120 秒墙钟里，所以回答慢一点就会看到 Error: code run failed (timeout): execution deadline reached (120000ms)；装上之后这段等待不再计入预算（默认上限 24 小时，-1 表示不限），而普通的死循环程序仍会在原预算处被终止。同样刻意做成单独安装：它拦截的是宿主 ptc-runtime 的执行预算。

另有一个独立的界面插件 dsh-find-session，给会话加上关键词查找：Ctrl+F 搜当前这个会话，Ctrl+Shift+F 搜全部已存会话、命中列在右侧栏。它同样是单独安装——它是浏览器侧的查找面板，不属于子代理工具；宿主半边只读会话日志，不写任何东西。

许可

MIT，见 LICENSE。源码与问题反馈： github.com/SpaceRelay/dsh-subagent-control。