dispatching-parallel-agents

用途

Dispatching Parallel Agents 用于把任务委派给具有隔离上下文的专用智能体。通过精确构造指令和上下文，确保每个智能体专注于自己的任务并成功完成。智能体不应继承当前会话的上下文或历史——你需要为它们精确构造所需内容，这同时也能保留你自己的上下文用于协调工作。

当存在多个不相关的失败（不同测试文件、不同子系统、不同缺陷）时，顺序调查会浪费时间。每次调查都是独立的，可以并行进行。

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

何时使用

决策流程（原文 digraph）：

存在多个失败？
- 是 → 它们是否相互独立？
  - 否（相关）→ 由单个智能体调查全部
  - 是 → 它们能否并行工作？
    - 是 → 并行分派
    - 否（共享状态）→ 顺序智能体

适用场景：

3 个及以上测试文件因不同根因失败
多个子系统独立损坏
每个问题无需其他问题的上下文即可理解
各调查之间没有共享状态

不适用场景：

失败相互关联（修复一个可能修复其他）
需要理解完整系统状态
智能体之间会相互干扰

模式

1. 识别独立域

按损坏内容对失败分组：

文件 A 测试：工具审批流程
文件 B 测试：批处理完成行为
文件 C 测试：中止功能

每个域相互独立——修复工具审批不会影响中止测试。

2. 创建聚焦的智能体任务

每个智能体获得：

具体范围：一个测试文件或子系统
明确目标：让这些测试通过
约束：不要修改其他代码
预期输出：你发现并修复内容的摘要

3. 并行分派

在同一个响应中发出全部三个子智能体分派——它们会并行运行：

Subagent (general-purpose): "Fix agent-tool-abort.test.ts failures"
Subagent (general-purpose): "Fix batch-completion-behavior.test.ts failures"
Subagent (general-purpose): "Fix tool-approval-race-conditions.test.ts failures"
# All three run concurrently.

一个响应中多个分派调用 = 并行执行。每个响应一个 = 顺序执行。

4. 审查与整合

智能体返回后：

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

智能体提示结构

好的智能体提示应当：

聚焦——一个清晰的问题域
自包含——包含理解问题所需的全部上下文
明确输出——智能体应返回什么？

示例：

Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:

1. "should abort tool with partial output capture" - expects 'interrupted at' in message
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
3. "should properly track pendingToolCount" - expects 3 results but gets 0

These are timing/race condition issues. Your task:

1. Read the test file and understand what each test verifies
2. Identify root cause - timing issues or actual bugs?
3. Fix by:
   - Replacing arbitrary timeouts with event-based waiting
   - Fixing bugs in abort implementation if found
   - Adjusting test expectations if testing changed behavior

Do NOT just increase timeouts - find the real issue.

Return: Summary of what you found and what you fixed.

常见错误

❌ 过于宽泛："Fix all the tests"——智能体会迷失
✅ 具体："Fix agent-tool-abort.test.ts"——范围聚焦
❌ 没有上下文："Fix the race condition"——智能体不知道在哪里
✅ 有上下文：粘贴错误信息和测试名称
❌ 没有约束：智能体可能重构一切
✅ 有约束："Do NOT change production code" 或 "Fix tests only"
❌ 输出模糊："Fix it"——你不知道改了什么
✅ 输出具体："Return summary of root cause and changes"

何时不使用

相关失败：修复一个可能修复其他——先一起调查
需要完整上下文：理解需要看到整个系统
探索性调试：你还不知道哪里坏了
共享状态：智能体会相互干扰（编辑相同文件、使用相同资源）

会话中的真实示例

场景：大型重构后 3 个文件共 6 个测试失败

失败情况：

agent-tool-abort.test.ts：3 个失败（时序问题）
batch-completion-behavior.test.ts：2 个失败（工具未执行）
tool-approval-race-conditions.test.ts：1 个失败（执行计数 = 0）

决策：独立域——中止逻辑、批处理完成、竞态条件彼此分离

分派：

Agent 1 → Fix agent-tool-abort.test.ts
Agent 2 → Fix batch-completion-behavior.test.ts
Agent 3 → Fix tool-approval-race-conditions.test.ts

结果：

Agent 1：用基于事件的等待替换超时
Agent 2：修复事件结构缺陷（threadId 位置错误）
Agent 3：增加等待异步工具执行完成

整合：所有修复相互独立、无冲突，完整套件通过

验证