| name | dispatching-parallel-agents |
| description | 当面临2个或更多可独立执行的、无共享状态或顺序依赖的任务时使用 |
调度并行代理
概述
你将任务委派给具有隔离上下文的专业代理。通过精心构建它们的指令和上下文,确保它们保持专注并成功完成任务。它们不应继承你当前会话的上下文或历史——你只需精确构建它们所需的内容。这也为你自己的协调工作保留了上下文空间。
当你遇到多个不相关的故障(不同的测试文件、不同的子系统、不同的缺陷)时,逐一排查是在浪费时间。每个排查任务是独立的,可以并行进行。
核心原则: 每个独立的问题域派遣一个代理。让它们并发工作。
何时使用
digraph when_to_use {
"多个故障?" [shape=diamond];
"它们是否独立?" [shape=diamond];
"单代理排查所有问题" [shape=box];
"每个问题域一个代理" [shape=box];
"它们能否并行工作?" [shape=diamond];
"顺序代理" [shape=box];
"并行调度" [shape=box];
"多个故障?" -> "它们是否独立?" [label="是"];
"它们是否独立?" -> "单代理排查所有问题" [label="否 - 相关联"];
"它们是否独立?" -> "它们能否并行工作?" [label="是"];
"它们能否并行工作?" -> "并行调度" [label="是"];
"它们能否并行工作?" -> "顺序代理" [label="否 - 共享状态"];
}
适用场景:
- 3个以上测试文件因不同根因而失败
- 多个子系统独立出现问题
- 每个问题可以独立理解,无需其他问题的上下文
- 各排查任务之间无共享状态
不适用场景:
- 故障相互关联(修复一个可能同时修复其他)
- 需要理解完整系统状态
- 代理之间会互相干扰
模式说明
1. 识别独立的问题域
按故障点分组:
- 文件 A 的测试:工具审批流程
- 文件 B 的测试:批量完成行为
- 文件 C 的测试:中止功能
每个问题域是独立的——修复工具审批不影响中止测试。
2. 创建聚焦的代理任务
每个代理获得:
- 明确范围: 一个测试文件或子系统
- 清晰目标: 让这些测试通过
- 约束条件: 不要修改其他代码
- 预期输出: 发现问题和修复内容的摘要
3. 并行调度
Task("修复 agent-tool-abort.test.ts 的故障")
Task("修复 batch-completion-behavior.test.ts 的故障")
Task("修复 tool-approval-race-conditions.test.ts 的故障")
4. 审查与集成
代理返回后:
- 阅读每个摘要
- 验证修复不冲突
- 运行完整测试套件
- 集成所有变更
代理提示词结构
好的代理提示词应具备:
- 聚焦 - 一个清晰的问题域
- 自包含 - 理解问题所需的全部上下文
- 输出明确 - 代理应返回什么?
修复 src/agents/agent-tool-abort.test.ts 中的 3 个失败测试:
1. "should abort tool with partial output capture" - 期望消息中包含 'interrupted at'
2. "should handle mixed completed and aborted tools" - 快速工具被中止而非完成
3. "should properly track pendingToolCount" - 期望 3 个结果但得到 0
这些是时序/竞态条件问题。你的任务:
1. 阅读测试文件,理解每个测试验证的内容
2. 确定根因 - 是时序问题还是实际缺陷?
3. 通过以下方式修复:
- 将任意超时替换为基于事件的等待
- 如发现中止实现中的缺陷则修复
- 如果测试了变更后的行为,调整测试期望
不要只是增加超时时间 - 找到真正的问题。
返回:你发现了什么以及修复了什么的摘要。
常见错误
❌ 范围过宽: "修复所有测试" - 代理会迷失方向
✅ 明确具体: "修复 agent-tool-abort.test.ts" - 聚焦的范围
❌ 缺少上下文: "修复竞态条件" - 代理不知道在哪里
✅ 提供上下文: 粘贴错误信息和测试名称
❌ 没有约束: 代理可能会重构所有内容
✅ 设定约束: "不要修改生产代码" 或 "仅修复测试"
❌ 输出模糊: "修复它" - 你不知道改了什么
✅ 明确输出: "返回根因和变更的摘要"
何时不适用
关联故障: 修复一个可能修复其他 - 先一起排查
需要完整上下文: 理解问题需要查看整个系统
探索性调试: 你还不知道什么坏了
共享状态: 代理会互相干扰(编辑相同文件、使用相同资源)
会话中的真实案例
场景: 重大重构后 3 个文件中出现 6 个测试失败
失败情况:
- agent-tool-abort.test.ts:3 个失败(时序问题)
- batch-completion-behavior.test.ts:2 个失败(工具未执行)
- tool-approval-race-conditions.test.ts:1 个失败(执行次数 = 0)
决策: 独立的问题域 - 中止逻辑与批量完成与竞态条件各自独立
调度:
代理 1 → 修复 agent-tool-abort.test.ts
代理 2 → 修复 batch-completion-behavior.test.ts
代理 3 → 修复 tool-approval-race-conditions.test.ts
结果:
- 代理 1:将超时替换为基于事件的等待
- 代理 2:修复了事件结构缺陷(threadId 位置错误)
- 代理 3:添加了对异步工具执行完成的等待
集成: 所有修复相互独立,无冲突,完整测试套件全部通过
节省时间: 3 个问题并行解决,而非串行
核心收益
- 并行化 - 多个排查任务同时进行
- 聚焦 - 每个代理范围狭窄,需跟踪的上下文更少
- 独立性 - 代理之间互不干扰
- 速度 - 3 个问题在 1 个问题的时间内解决
验证
代理返回后:
- 审查每个摘要 - 理解变更内容
- 检查冲突 - 代理是否编辑了相同代码?
- 运行完整测试套件 - 验证所有修复协同工作
- 抽查 - 代理可能犯系统性错误
实际效果
来自调试会话(2025-10-03):
- 3 个文件中共 6 个失败
- 并行调度 3 个代理
- 所有排查任务并发完成
- 所有修复成功集成
- 代理变更之间零冲突