# ⚔️ 忍法多重影分身之術：解密 `agy` 子代理（Subagent）與軍團協作架構
> [!NOTE]
> **作者資訊 (Author Info)**
> 
> * **姓名 (Name)**: mingo 謝明翰
> * **電子信箱 (Email)**: mhhsei@mail.batol.net


在木葉忍者村的修練場上，漩渦鳴人面對著「修練螺旋丸」這個極度艱難的 S 級任務。

如果只靠本尊一個人苦練，要同時完成查克拉的形態變化與性質變化，恐怕耗費數年光陰也難以集大成。於是，鳴人結下忍者手印，大喊一聲：「多重影分身之術！」

瞬間，修練場上出現了成百上千個與本尊一模一樣的影分身。一號分身專心致志地用雙手切開水球，二號分身全力以赴地弄破橡皮球，三號分身則在一旁觀察查克拉的流動方向。每個影分身都在獨立的空間裡瘋狂試錯與修練，而本尊則站在陣中冷靜地進行全局指揮。當修練結束，影分身砰的一聲化作白煙消散，數百個分身累積的修練記憶與經驗，在一瞬間如潮水般全數匯回鳴人本尊的大腦中！

這不只是熱血動漫裡的經典情節，這更是現代頂尖 AI 開發架構中，最震撼人心、最核心的魔法——**Subagent（子代理）與 Agent Teams（代理人團隊）架構**！

---

## 🌀 忍者學校修練瓶頸：為什麼單一忍者無法獨自攻克 S 級任務？

在過去，很多開發者習慣只依賴一個「主 Agent（大副）」來包辦所有大小事。但當你的專案規模逐漸長大，從簡單的腳本升級為包含前端、後端、資料庫與資安架構的大型系統時，單一 AI 的瓶頸便會立刻暴露無遺：

*   **黑板（Context Window）的極限與雜訊污染**：
    大語言模型的臨時黑板空間是寶貴且有限的。如果讓主 Agent 一邊去搜尋幾十個網頁、一邊印出幾千行編譯日誌、一邊又要在檔案裡寫程式碼，它的黑板很快就會被龐雜的過程雜訊填滿。自注意力機制會被這些無關緊要的日誌干擾，導致 AI 開始丟三落四、產生注意力潰散，甚至忘記了使用者最初下達的核心目標！
*   **矽谷開發哲學的根本性變革**：
    在矽谷軟體工程師 **Kelly Tsai** 在分析前沿 AI 工具（如 Claude Code 與 modern AGY 系統）的演進時明確指出：**全球 AI 軟體工程的開發哲學，正在經歷一場從『提示詞工程（Prompt Engineering）』轉向『管理代理人協作（Agentic Workflow / Agent Teams）』的世紀大躍遷！**
    以前的工程師折騰半天，只為了寫出一段幾千字的「黃金提示詞」去逼迫單一 AI；而現在矽谷最頂尖的創業者與 Solopreneur（一人公司），都在學習如何擔任「數位軍團總司令」，調動專門的 AI 子代理小隊來分工完成任務！

---

## 忍術祕傳解析：Subagent 子代理 vs Agent Teams 影分身軍團三大維度對決

在閱讀技術文檔時，許多新手常把 **Subagent（子代理）** 與 **Agent Teams（代理人團隊）** 混為一談。事實上，在底層架構與溝通拓樸上，兩者有著極為鮮明的差別。

我們可以用兩句話來切中要害：
*   **Subagent（子代理）＝「任務外包專家（主從單向委派）」**。
*   **Agent Teams（代理人團隊）＝「圓桌戰術會議（網狀對等協作）」**。

> 不懂吧，subagent 你就把它看成 line 的單一聊天室，你跟他的對話不會被其他人看到。而 agent teams 就是群組聊天，各個 agent 能互相溝通。

我們從三個技術維度來做深度對比：

*   **維度一：溝通拓樸結構（星狀主從 Hub-and-Spoke vs 網狀對等 Mesh）**
    *   **Subagent（子代理）**：採用標準的星狀主從架構（Hub-and-Spoke）。子代理之間是**完全物理隔離、無法直接橫向對話的**！一號子代理寫完前端 HTML，它不能直接給二號子代理傳訊息；它必須把成果交還給主 Agent（父節點），再由主 Agent 來進行任務交接與派工。
    *   **Agent Teams（代理人團隊）**：採用網狀對等架構（Mesh Network）。團隊中的成員地位平起平坐！前端 Agent 可以直接在圓桌會議室裡對後端 Agent 提出質疑：「你的 API 介面 JSON 格式不符合規範，請重新修訂。」它們不需要主 Agent 層層轉達，就能直接進行橫向辯論與互相審查。
*   **維度二：控制權與自主性（受控專項委派 vs 多方自主協商）**
    *   **Subagent（子代理）**：自主性被嚴格限制在給定的 Task 範疇內。主 Agent 給它什麼指令，它在獨立黑板裡執行完畢後隨即交差並銷毀，行為高度可預測，極度節省 Token 燃料。
    *   **Agent Teams（代理人團隊）**：自主性極高，成員具備獨立思考與互相詰問的權限。適用於高度開放、不確定性極強的系統設計與架構攻防戰。
*   **維度三：適用開發場景（流水線專項任務 vs 開放式頭腦風暴）**
    *   **Subagent（子代理）**：最適合確定性高的流水線任務（例如：主 Agent 派工「你去把這段 C++ 翻譯成 Rust」或「你去抓取網頁 API 文檔」）。
    *   **Agent Teams（代理人團隊）**：最適合複雜的模組重構與資安審查（例如：前端工程師、後端工程師與資安大師三方即時開會討論系統漏洞）。

---

## 📜 影分身修練三大黃金階段：Split、Fan Out 與 Merge 之術

在大副（主 Agent）召喚子代理執行任務時，底層遵循著嚴謹的**三大黃金階段（Three Golden Stages）**：

*   **階段一：拆解與派工 (Split / Task Decomposition)**
    *   **技術原理**：當主 Agent 收到一個龐大任務（例如「開發一個點字翻譯網頁與後端 API」）時，它絕不會盲目直接撰寫程式碼。主 Agent 會扮演指揮官，將大任務拆解成數個互不干擾的獨立子任務（Sub-tasks）。
    *   **修練比喻**：鳴人本尊站在陣前，分析敵情後將任務切割為「切開水球」與「弄破橡皮球」兩張修練派工單。
*   **階段二：獨立並行與黑板隔離 (Fan Out / Isolated Parallel Execution)**
    *   **技術原理**：主 Agent 呼叫內建工具 `invoke_subagent`，在背景瞬間繁衍（Fan Out）出多個獨立子代理。每個子代理都被分配到了**全新、乾淨且徹底隔離的對話黑板（Context Window）**，並被鎖定在專屬工具箱中。子代理們在背景各自獨立並行運作，搜尋了幾十個網頁或印出了上千行測試日誌，這些過程雜訊全被鎖在各自的黑板中，完全不會弄髒主 Agent 的黑板！
    *   **修練比喻**：影分身們各自跑到獨立的森林空地裡修練，水球濺出的水花與橡皮球碎片完全不會弄髒鳴人本尊的衣服。
*   **階段三：結果匯合與報告整合 (Merge / Result Synthesis)**
    *   **技術原理**：當子代理完成專項任務後，會自動發送任務完成標記（Task Complete）並銷毀自己的臨時黑板。它只把最精華、最乾淨的「結論報告與代碼產出」傳回給主 Agent。主 Agent 將各路子代理傳回的成果進行匯合（Merge）與最終驗驗證，最後呈報給船長（你）！
    *   **修練比喻**：影分身修練完畢後「砰」的一聲化作煙霧解散，累積的寶貴經驗瞬間灌回鳴人本尊的大腦，別墅竣工驗收完美通過！


---

## ⚙️ 影分身結界四重印記：Context 隔離、技能卡、異步並行與分支沙箱

在 `agy` 與現代 Agent Teams 框架中，子代理軍團遵循著四個極度嚴謹的底層運作機制：

*   **印記一：獨立的上下文空間（Context Isolation）**
    *   主 Agent 在召喚子代理時，系統會為其開闢全新的記憶黑板。子代理在執行過程中產生的所有試錯紀錄、錯誤日誌與網頁 HTML 雜訊，都會在子代理結束時被自動抹除，只有最終結果會被壓縮並回傳給主 Agent。
*   **印記二：專屬技能卡與角色限定（Skill Cards & Persona）**
    *   每個子代理在啟動時都會被賦予特定的技能卡與權限邊界：
        *   `research` 子代理：擁有搜尋引擎與文件閱讀權限，專門擔任情報調查員。
        *   `coder` 子代理：擁有讀寫檔案與執行編譯器的權限，專門擔任程式碼撰寫工程師。
        *   `reviewer` 子代理：僅擁有唯讀（Read-Only）權限，專門擔任資安與代碼品質稽核員。
*   **印記三：異步並行與背景工作（Asynchronous Execution）**
    *   主 Agent 可以同時召喚多個子代理並行工作。主 Agent 無需在原地傻傻等待，它可以繼續與你對話或處理其他規劃。當子代理在背景完成任務時，系統會發送 High-Priority（高優先級）通知提醒主 Agent 收工回報。
*   **印記四：工作區隔離模式（Workspace Isolation Mode）**
    *   主 Agent 召喚子代理時，可以設定物理工作區模式：
        *   `inherit`（繼承模式）：子代理直接在主專案資料夾中進行修改。
        *   `branch` / `share`（分支/共享模式）：利用 Git 物理隔離機制，為子代理複製一份獨立的物理工作區。子代理在裡面進行破壞性測試，就算把程式碼寫爛了，也完全不會影響到主專案！

---

## 🎮 忍術指揮所：在 `agy` 終端機調動影分身大軍的四大實戰印術

在我們的 `agy` 終端機與 Antigravity 2.0 桌面應用中，你可以透過以下指令直接操控與觀察子代理軍團：

*   **印術一：查看背景所有影分身（`/agents` 指令）**
    *   在對話框中輸入 `/agents`，大副會立刻列出目前所有在背景運行的子代理名單、它們的專屬對話 ID（Conversation ID）以及當前的執行進度。
*   **印術二：與特定影分身跨時空對話（`send_message`）**
    *   如果你想查看某個子代理的具體進度，或是想給正在寫前端的子代理補充新需求，主 Agent 會透過 `send_message` 工具與該子代理做跨時空對話，指揮其調整方向。
*   **印術三：多代理人協作預覽（`/teamwork-preview` 指令）**
    *   輸入 `/teamwork-preview`，系統會以直觀的可視化介面，向你展示主 Agent 如何將龐大專案拆解並分發給前端、後端、QA 子代理，以及最後如何匯合報告的全過程。
*   **印術四：手動召喚專用子代理（命令行指定）**
    *   你可以在指令中明確要求：「請召喚一個 `reviewer` 子代理，幫我對 `auth.py` 進行資安稽核」，大副便會精準啟動具備特定技能卡的子代理為你服務。

> 必須說，使用這種多代理合作的方式，速度確實快了很多。但在我們小專案的開發，建議不要使用這種多代理合作，因為非常燒 token,一下就噴光了。

---

## 忍道修練總結與下一站預告

掌握了 Subagent 子代理與 Agent Teams 影分身軍團後，你已經正式從「單打獨鬥的個人 AI 使用者」，跨入了「掌控數位軍團的 AI 總司令」行列！

然而，當影分身軍團在你的電腦裡高效率奔跑、調用各種終端機指令時，我們該如何建立嚴密的搜查令制度與無塵沙箱，防止惡意指令或越獄攻擊破壞你的主作業系統？

下一堂課，我們將踏入安全特勤中心，解密授權引擎與防彈沙箱隔離防禦機制！

---

👉 **[下一堂課：Lecture 04.8 代理人的記憶寶庫與安全方向盤：解密 Agent 四維記憶、Human-in-the-Loop 護城河與思維可觀測性](Lecture_04_8_Agent_Memory_HITL_Observability.md)**
👉 **[下一堂課：Lecture 05 特工無塵室與保密協定：掌握 agy 權限授權與沙箱安全防禦](Lecture_05_Permissions_Sandbox.md)**
👉 **[回課程大綱：學習地圖](README.md)**