90 秒總覽
代理與擴充機制讓 Claude Code 能把工作委派給子代理（sub-agent），並透過 MCP 擴充工具載入外部能力。子代理的核心概念是「任務委派」：主流程定義任務範圍與 ownership，啟動子代理執行，最後整合結果。擴充機制則讓第三方可以在不修改核心程式碼的前提下增加新工具、新命令或新資源。兩者都必須在安全邊界內運作。
執行路徑（主骨架）
const task = createAgentTask({ prompt, ownership })
startTask(task)
const result = await waitTask(task.id)
integrateResult(result)判斷委派
→ 建立子任務
→ 執行與監看
→ 整合輸出flowchart TD A[判斷任務可否委派] --> B[定義任務範圍與 ownership] B --> C[createAgentTask] C --> D[startTask] D --> E[子代理執行（可能使用工具）] E --> F[waitTask] F --> G[結果驗證] G --> H[integrateResult] H --> I[更新主流程狀態]
路徑判讀重點
- 委派前必須先定義 ownership，確保子代理的操作範圍不與主流程或其他子代理重疊。
- waitTask 是阻塞式等待，主流程在子代理完成前不會繼續推進。
- integrateResult 負責驗證子代理輸出的一致性，通過後才更新主流程狀態。
關鍵決策（為什麼這樣設計）
決策 1：子代理有獨立的工具與權限範圍
原因：避免越權操作。子代理若共享主流程的完整權限，可能存取或修改超出任務範圍的資源，導致非預期的副作用。獨立範圍確保每個子代理只能操作被明確授權的部分。
代價：需要額外設定每個子代理的工具與權限範圍，增加任務建立的複雜度。
決策 2：任務委派前必須定義 ownership 邊界
原因：防止平行寫入衝突。多個子代理同時修改相同檔案或資源，會產生競爭條件與合併衝突。明確的 ownership 邊界確保每個子代理的責任區互不重疊。
代價：任務分割的粒度受 ownership 邊界限制，某些跨邊界的操作需要額外協調。
決策 3：擴充透過 MCP 標準協議而非內部 API
原因：維持核心穩定性。內部 API 會隨版本迭代變動，若第三方直接依賴內部介面，每次核心更新都可能破壞擴充。MCP 標準協議提供穩定的合約，讓核心可以自由演進而不影響擴充生態。
代價：標準協議的表達力可能不如內部 API 豐富，某些進階需求需等待協議擴展。
替代方案與取捨
| 方案 | 優點 | 缺點 | 為何未採用/何時可採用 |
|---|---|---|---|
| 主流程直接執行 | 無需任務分割，流程簡單 | 複雜任務阻塞主流程，無法平行化 | 僅適合簡單且快速完成的操作 |
| 子代理委派 | 可平行化、職責明確、可獨立失敗 | 需要 ownership 管理與結果整合邏輯 | 目前採用；複雜任務的可擴展性優先 |
| 共享工具集 | 設定簡單，所有代理能力相同 | 越權風險高，難以追蹤誰做了什麼 | 安全需求要求最小權限原則 |
| 獨立工具範圍 | 最小權限，操作可追溯 | 每個子代理需額外設定權限 | 目前採用；安全性優先於便利性 |
| 內部擴充 API | 表達力強，能存取核心完整能力 | 核心更新可能破壞第三方擴充 | 穩定性風險過高，不適合開放生態 |
| MCP 標準協議 | 穩定合約，核心可自由演進 | 表達力受限於協議規範 | 目前採用；長期生態健康優先 |
失敗路徑與防護
Failure 1：子代理任務超時
症狀：waitTask 長時間未返回，主流程被阻塞，後續操作全部停滯。在多子代理場景下，一個超時可能導致整體任務卡住。
防護：為每個子代理設定合理的超時上限，超時後自動中止任務並回報失敗狀態，主流程可決定重試或降級處理。
Failure 2：平行子代理寫入同一檔案衝突
症狀：兩個以上的子代理同時修改同一檔案，後寫入者覆蓋先寫入者的變更，導致結果不一致或資料遺失。
防護：在任務建立階段透過 ownership 邊界嚴格劃分檔案責任區，若偵測到重疊則拒絕啟動子代理，並要求重新劃分。
Failure 3：擴充工具的 schema 與核心不相容
症狀：透過 MCP 載入的第三方工具回傳格式不符預期，導致核心解析失敗、工具呼叫結果無法整合，甚至造成回合引擎中斷。
防護：在工具載入階段進行 schema 驗證，不相容的工具拒絕載入並記錄錯誤；執行期對工具回傳值做防禦性解析，異常時降級為錯誤回報而非崩潰。
實作驗證（你改完要怎麼確認）
- 確認子代理任務正確啟動與完成：建立一個簡單的委派任務，驗證 createAgentTask → startTask → waitTask → integrateResult 的完整流程能正常執行並回傳預期結果。
- 確認 ownership 邊界有效隔離：同時啟動兩個子代理並指定不同的 ownership 範圍，驗證任一子代理無法存取另一方的責任區。
- 確認擴充工具正確載入：透過 MCP 註冊一個測試用工具，驗證該工具出現在可用工具列表中且能正常呼叫執行。
- 確認失敗任務有回報機制：故意讓子代理任務失敗（例如超時），驗證主流程收到失敗狀態且能正確處理。
這四步對應「委派生命週期、隔離驗證、擴充載入、失敗回報」，是最低可接受驗證集。