当你同时面对多个互相独立的问题——比如三个测试文件分别因为不同原因失败——顺序处理意味着后面的问题在等前面的问题结束，而它们其实可以同时开始。并行发射子代理的核心判断标准是：任务之间是否没有共享状态，是否没有顺序依赖。两个条件都满足，就可以并行；任意一个不满足，就不能并行。

dispatching-parallel-agents：当多个任务互相独立时，同时发射多个子代理

并行的核心判断：两个独立性条件

在决定是否并行发射子代理之前，需要回答两个问题：

问题一：这些任务之间有没有共享状态？ 如果两个子代理都需要修改同一个文件，或者都会读写同一个数据库表，那么它们的修改可能相互覆盖，产生冲突，这种情况不能并行。

问题二：这些任务之间有没有顺序依赖？ 如果任务 B 的输入依赖于任务 A 的输出，那么 B 必须等 A 完成之后才能开始，这种情况也不能并行。

只有当两个条件都满足——没有共享状态，没有顺序依赖——才适合并行发射。

合适的例子：三个测试文件，三个不同的根因

场景：一次重构之后，CI 报告有 6 个测试失败，分布在三个文件里：

• agent-tool-abort.test.ts：3 个失败，都是计时/竞态条件问题
• batch-completion-behavior.test.ts：2 个失败，事件结构里 threadId 放错了位置
• tool-approval-race-conditions.test.ts：1 个失败，异步工具执行完成前就断言了结果

这三组失败的根因完全不同，修复 abort 相关的问题不会影响 batch completion，也不会影响 race condition。三个子代理分别处理三个文件，不会读写同一段代码，也不存在"先修好 A 才能知道怎么修 B"的依赖关系。

这是典型的适合并行的场景。三个代理同时工作，原本需要串行完成三个调查的时间，现在变成了完成一个调查的时间。

不合适的例子：根因不明确时的系统性调查

场景：构建失败，错误信息是类型不匹配，但你不清楚是哪个模块引入的变化导致的。

这种情况下并行是错误的选择，因为：

1. 根因未知：在你弄清楚问题出在哪里之前，没有办法把"一个问题"拆分成多个独立的子任务
2. 可能相互关联：看起来像三个问题，实际上可能是同一个类型定义改动导致的连锁反应，修了一个，其余会自动消失
3. 需要全局上下文：每个子代理的调查范围都是局部的，而这个问题需要理解整个系统的状态才能做出正确判断

正确做法是先用一个代理完成系统性调查，确定根因和影响范围，然后再判断是否有可以并行处理的独立修复任务。

如何写出好的子代理指令

子代理应该有自己完整的、独立的上下文，而不是继承你当前会话的历史。你的任务是构建这个上下文，而不是把问题甩给它。

好的子代理指令有四个要素：

明确的范围：只处理这个文件/这个模块，不要改其他地方。

足够的背景：把相关的错误信息、测试名称、期望行为直接写进去，不要让代理自己去猜。

清晰的目标：你要它返回什么？修复后的代码？根因分析？还是可以执行的修复方案？

明确的约束：有什么不能改？比如"不要修改生产代码，只调整测试"，或者"不要增加超时时间，找真正的根因"。

一个好的指令示例：

修复 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

这些是计时/竞态条件问题。要求：

• 读完测试文件，理解每个测试在验证什么
• 找出根因——是计时问题还是 abort 实现本身的 bug？
• 用事件驱动的等待替换任意超时，不要只是加大超时值

不要修改其他测试文件。返回：根因摘要和你做的改动说明。

收到子代理结果后的整合步骤

子代理完成并不等于任务完成。你需要：

1. 读每个代理的摘要：理解它做了什么，而不是假设它做对了
2. 检查冲突：多个代理有没有修改了同一段代码？如果有，需要手动合并
3. 跑完整的测试套件：各自能通过不代表合并在一起也能通过
4. 抽查代理的修改：代理有时会做出系统性错误，比如把所有的断言都改弱了让测试通过，而不是真正修复了问题

常见错误

范围太宽："帮我修所有失败的测试"——代理会迷失在过多的上下文里，倾向于做出大范围的改动。

没有提供错误信息："修复 race condition 问题"——代理不知道你在哪里看到了什么错误，只能猜。

没有说约束：代理可能重构整个模块来让测试通过，但引入了你不想要的改动。

没有指定输出格式：代理返回了一大段分析，但你不知道它到底改了什么，在哪里改的。

FAQ

Q：并行发射多少个代理合适？有没有上限？ A：没有硬性上限，但实际上受两个因素约束：问题能拆成多少个真正独立的域，以及你有没有能力在结果回来后有效地整合所有修改。代理越多，整合成本越高。一般来说，3 到 5 个是比较容易管理的范围。

Q：子代理在执行过程中如果发现自己的任务范围其实和另一个代理有重叠，应该怎么处理？ A：子代理应该停下来报告冲突，而不是继续往前走。这正是在发射之前明确范围和约束的原因——让代理在有疑问时报告，而不是自行决定。

Q：并行代理的执行结果应该由谁来做最终验证？ A：由你，而不是由任何一个子代理。每个代理只能验证自己的改动，无法验证所有改动合并在一起的效果。最终的完整测试套件必须由协调者来跑。