并行分派智能体
用途
当面对 2 个以上可以独立进行、彼此之间没有共享状态或顺序依赖的任务时，可以将任务委派给具有隔离上下文的专用智能体。通过精心设计每个智能体的指令和上下文，让它们专注并成功完成任务。它们不继承主控会话的上下文或历史记录，主控需要精确构造它们所需的一切，这样也能为主控保留用于协调工作的上下文。
当遇到多个不相关的失败，例如不同的测试文件、不同的子系统、不同的 bug，逐一排查会浪费时间。每个排查都是独立的，可以并行进行。
核心原则：每个独立问题域分派一个智能体，让它们并发工作。
何时使用
适用场景包括：
3 个以上测试文件因不同根因失败。
多个子系统独立出现故障。
每个问题无需其他问题的上下文即可理解。
排查之间无共享状态。
不适用场景包括：
失败是相关的，修复一个可能修复其他问题。
需要理解完整的系统状态。
智能体之间会互相干扰。
使用前可以用判断流程辅助决策：如果存在多个失败，判断它们是否独立；若独立，再看能否并行工作；可以并行则并行分派，否则顺序执行智能体。如果失败之间有关联，则由单个智能体排查所有问题。
模式
- 识别独立的问题域
按故障分组，例如：
文件 A 测试：工具审批流程。
文件 B 测试：批量完成行为。
文件 C 测试：中止功能。
每个问题域是独立的，修复工具审批不会影响中止测试。
- 创建聚焦的智能体任务
每个智能体获得：
明确范围：一个测试文件或子系统。
清晰目标：让这些测试通过。
约束条件：不修改其他代码。
预期输出：你发现和修复内容的总结。
- 并行分派
在 Claude Code 或 AI 环境中，可以这样分派：
Task("修复 agent-tool-abort.test.ts 的失败") Task("修复 batch-completion-behavior.test.ts 的失败") Task("修复 tool-approval-race-conditions.test.ts 的失败") // 三个任务并发运行
- 审查与集成
当智能体返回时：
阅读每个总结。
验证修复之间没有冲突。
运行完整测试套件。
集成所有更改。
智能体提示词结构
好的智能体提示词应该是：
聚焦的：一个清晰的问题域。
自包含的：包含理解问题所需的所有上下文。
明确输出要求：智能体应该返回什么？
示例提示词：
修复 src/agents/agent-tool-abort.test.ts 中 3 个失败的测试：
- "should abort tool with partial output capture" - 期望消息中包含 'interrupted at'
- "should handle mixed completed and aborted tools" - 快速工具被中止而非完成
- "should properly track pendingToolCount" - 期望 3 个结果但得到 0 个
这些是时序/竞态条件问题。你的任务：
- 阅读测试文件，理解每个测试验证的内容
- 找到根因——是时序问题还是实际 bug？
- 修复方式：
- 用基于事件的等待替换任意超时
- 如果发现中止实现中的 bug 则修复
- 如果测试的是已变更的行为则调整测试期望
不要只是增加超时时间——找到真正的问题。
返回：你发现了什么以及修复了什么的总结。
常见错误
太宽泛：例如说“修复所有测试”，智能体会迷失方向；应具体明确，例如“修复 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：修复了事件结构 bug，threadId 位置不对。
智能体 3：添加了等待异步工具执行完成的逻辑。
集成：所有修复互相独立，无冲突，完整测试套件全部通过。
节省的时间：3 个问题并行解决，而不是顺序解决。
核心优势
并行化：多个排查同时进行。
聚焦：每个智能体范围窄，需要跟踪的上下文少。
独立性：智能体之间互不干扰。
速度：3 个问题在 1 个问题的时间内解决。
验证
智能体返回后：
审查每个总结，理解改了什么。
检查冲突，确认智能体是否编辑了同一段代码。
运行完整套件，验证所有修复协同工作。
抽查，智能体可能犯系统性错误。
实际效果
来自调试会话（2025-10-03）：
3 个文件中 6 个失败。
并行分派 3 个智能体。
所有排查并发完成。
所有修复成功集成。
智能体之间的更改零冲突。