dispatching-parallel-agents

用途

本技能用于在存在多个相互独立的问题时，通过并行调度多个子智能体来加速排查与修复。它适用于 2 个以上可以独立处理、没有共享状态或顺序依赖的任务。典型场景是多个不相关的失败同时出现，例如不同的测试文件、不同的子系统、不同的缺陷。顺序调查这些问题会浪费时间，而每个调查彼此独立，可以并行进行。

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

主要能力

将任务委派给具有隔离上下文的专用智能体。
通过精确构造指令和上下文，让每个智能体保持专注并完成任务。
智能体不继承主会话的上下文或历史，所需内容由调度者精确构造。
保留主会话自身的上下文，用于协调工作。

何时使用

技能给出了判断流程：

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

适用情形：

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.

常见错误

过于宽泛：“修复所有测试”——智能体会迷失。应具体：“修复 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）。

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

派发：

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：增加等待异步工具执行完成。

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

验证