分派并行智能体

概述

当你有多个不相关的失败（不同的测试文件、不同的子系统、不同的错误）时，按顺序调查它们会浪费时间。每个调查都是独立的，可以并行进行。

核心原则：每个独立问题域分派一个智能体。让它们并行工作。

何时使用

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. 并行分派

// 在 Claude Code / AI 环境中
Task("修复 agent-tool-abort.test.ts 的失败")
Task("修复 batch-completion-behavior.test.ts 的失败")
Task("修复 tool-approval-race-conditions.test.ts 的失败")
// 三个任务同时运行

4. 审查与整合

当智能体返回时：

• 阅读每份摘要
• 验证修复没有冲突
• 运行完整的测试套件
• 整合所有更改

智能体提示结构

好的智能体提示是：

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 个

这些是时序/竞态条件问题。你的任务：

1. 阅读测试文件，理解每个测试验证的内容
2. 识别根本原因 - 是时序问题还是实际 bug？
3. 通过以下方式修复：
   - 将任意的超时等待替换为基于事件的等待
   - 如果发现中止实现的 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 个问题并行解决，而非顺序解决

主要优势

1. 并行化 – 多个调查同时进行
2. 聚焦 – 每个智能体范围狭窄，需要跟踪的上下文更少
3. 独立性 – 智能体之间互不干扰
4. 速度 – 在解决 1 个问题的时间内解决了 3 个问题

验证

智能体返回后：

1. 审查每份摘要 – 了解更改了什么
2. 检查冲突 – 智能体编辑了同一代码吗？
3. 运行完整套件 – 验证所有修复能协同工作
4. 抽查 – 智能体可能会犯系统性错误

实际影响

来自调试会话（2025-10-03）：

• 3 个文件出现 6 个失败
• 3 个智能体并行分派
• 所有调查同时完成
• 所有修复成功整合
• 智能体更改之间零冲突