dispatching-parallel-agents

分派平行代理

概述

你將任務委派給具有隔離上下文的專業代理。透過精確設計它們的指令和上下文，確保它們專注並成功完成任務。它們不應繼承你工作階段的上下文或歷史記錄——你應精確建構它們所需的內容。這也保留了你的上下文以便進行協調工作。

當你遇到多個不相關的失敗（不同的測試檔案、不同的子系統、不同的錯誤）時，循序調查會浪費時間。每個調查都是獨立的，可以平行進行。

核心原則： 每個獨立問題領域分派一個代理。讓它們同時工作。

使用時機

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

在同一則回應中發出所有三個子代理分派——它們會平行執行：

子代理（通用）：「修復 agent-tool-abort.test.ts 的失敗」
子代理（通用）：「修復 batch-completion-behavior.test.ts 的失敗」
子代理（通用）：「修復 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. 識別根本原因 - 時序問題還是實際錯誤？
3. 透過以下方式修復：
   - 用基於事件的等待取代任意逾時
   - 如果發現中止實作中的錯誤則修正
   - 如果測試的是已變更的行為則調整測試預期

不要只是增加逾時 - 找出真正的問題。

回傳：你發現和修復的摘要。

常見錯誤

❌ 太廣泛： 「修復所有測試」 - 代理會迷失
✅ 具體： 「修復 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：修正事件結構錯誤（threadId 位置錯誤）
• 代理 3：新增等待非同步工具執行完成

整合： 所有修復獨立，無衝突，完整套件綠燈

節省時間： 3 個問題平行解決 vs 循序解決

主要優點

1. 平行化 - 多個調查同時進行
2. 聚焦 - 每個代理範圍狹窄，需追蹤的上下文較少
3. 獨立性 - 代理不會互相干擾
4. 速度 - 3 個問題在 1 個問題的時間內解決

驗證

代理回傳後：

1. 審查每個摘要 - 了解變更內容
2. 檢查衝突 - 代理是否編輯了相同程式碼？
3. 執行完整套件 - 驗證所有修復能共同運作
4. 抽樣檢查 - 代理可能犯系統性錯誤

實際影響

來自除錯工作階段（2025-10-03）：

• 3 個檔案共 6 個失敗
• 3 個代理平行分派
• 所有調查同時完成
• 所有修復成功整合
• 代理變更之間零衝突