五層 AI 開發體系:SPEC、Harness、Agent 到正道腦與 A2A

市面上的 AI（ChatGPT／Claude）本質上是一個很聰明、但會失憶、沒有紀律、也沒進過你公司廚房的實習生。這篇不從技術架構講起，而是照「一般人怎麼真的用起來」的順序，拆給不寫程式、但要做決策的主管聽：① 先從聊天框升級到會幫你做事的 agent、用起來就算得出 ROI；② 要認真做、要穩定，才需要那套鷹架（SPEC／Harness／Workflow）；③ 再讓 agent 接上你的知識（RAG／GraphRAG／CAG）與系統（A2A）；④ 最後是企業落地、治理、還有怎麼用一個請來的人。輕度用，你看前面就夠；重度才往下。

從聊天框到 agent：先用起來（一般人這步就夠）

大多數人第一次碰 AI 是「聊天框」——問一句、答一句，每一步還是你在驅動。真正改變工作的是 agent：你給它一個目標，它自己跑多步、用工具、把整件事做完。這一部先讓你「動起來、算得出帳」，不用先懂後面那一整套鷹架。

怎麼開始（就三步）：下載一個 co-working／agent 工具 → 挑你最煩、最多步、現在都手動的一件活 → 讓它做給你看。它幫你把 5 步做完，就是 agent 特有的「有感」（聊天框給不了）。

怕它「亂搞」？別跳，爬梯子——越爬越放手：

導入要花多少、多久回本？（成本與 ROI）

前面都在講「怎麼做」。老闆真正要三件事：花多少、多久回本、什麼時候該升級——三個都給你能對照的東西，而且都不用懂 AI。

步 1 怎麼點火：讓非 IT 人快速上手（這步最難）

六步裡步 1 最難——非 IT 人要先「有感」才會動。訣竅就三個字：降門檻（像問同事一樣打字）、挑真痛（他最煩的一件重複活）、帶做一次（在他自己的活上、當場做給他看）。

ROI 用他的單位算（一個月約 3000 元，三種他一聽就懂的講法）：

一、花多少：分級成本表

不是報價，是幫你抓量級、避免被「先做個 PoC」拖成無底洞：

二、多久回本、省多少：量這幾個你本來就會算的數

三、什麼時候該升級（不用你懂技術，看症狀就好）

你不用懂 CAG／RAG／GraphRAG／A2A 是什麼。你只要認得下面這些症狀——大多數主管本來就分得出來——看到了，把中間那句話丟給工程師，換什麼是他的事。

一張圖看懂：五層堆疊，把實習生變成一支團隊

AI 開發體系是什麼？它是把「一個天才但會失憶、沒有紀律的實習生」，改造成「一支有菜單規格、有廚房水電、有出菜 SOP、有記憶、還會被師傅當場糾正的團隊」的一整套設計。先看這張堆疊圖，五層由下往上疊，愈下面愈是地基、愈上面愈換得起：

同樣一張表，供你快速對照每一層「是什麼、為什麼要它」：

先用你熟悉的老架構，接上 AI 時代

如果你做過系統，這一段最快讓你「接上」——因為骨架其實沒變，只是多疊了一層腦，而且有個方向整個反過來了。先看我們都熟的傳統三層：

AI 時代，這條交易線一條都沒消失——前端還是前端、API 還是 API、DB 還是 DB。它只是多長出一條平行的「智能線」：

這條線的中樞是 Agent——它負責發起與 orchestrate（決定要查什麼、問模型什麼、答案怎麼用）。它做事時往兩邊接：一邊查 GraphRAG（新的「知識庫」，像 DB，但放的是判斷與關係）當根據，一邊透過後端 API（Ollama／vLLM）叫 Model（運算核心）幫它想跟生成。你原本的交易線沒被丟掉，只是多了這條「管理解與生成」的智能線。（Agent 到底怎麼透過 API 叫模型，下一段細講。）

講清楚定位：Agent ＋ Model，中間就是一層 API（Ollama）

這裡有個一定要講清楚、不然定位會很模糊的點：Agent 不是「直接」跟模型講話的。AI 的運作其實就三段——Agent → 模型伺服器（Ollama／vLLM）→ Model：

跟傳統架構一模一樣的道理：前端不直接碰 DB，要透過後端 API；AI 這邊，Agent 也不直接碰模型，要透過 Ollama／vLLM 這一層 API。三者定位對照如下：

Agent 是「身體」、模型是「腦」——兩邊要相襯

再往下看 Agent 到底在做什麼。過去，我們自己就是那顆「腦」：寫 crontab 排好固定時間跑、寫 bash 或程式把每一步寫死、甚至動態產生 Python 再執行——指令都是「人」事先寫好的。AI 時代換模型當腦：

所以Agent 的角色，是「聽」後面那顆模型（透過 API）吐回來的 JSON 指令，然後忠實執行。模型當場寫腳本、Agent 當場照做。模型是出主意的腦，Agent 是動手的身體。

關鍵：腦跟身體要相襯，才能相輔相成。配不好會出現兩種毛病：

AI 時代最重要的轉變：方向反過來了

這是整個 AI 時代最該搞懂的一件事。過去二十年，資料庫的世界從交易（OLTP）、分析（OLAP）一路走到機器學習（ML）。OLTP／OLAP 本來是給人看報表、做決策；ML 是後來（2010 年代）才疊上來、想「從自己的資料煉出一個模型」的野心——而模型一直是最難、最貴、最後才拿得到的東西。

第 1 層 SPEC：把「要什麼」蒸餾成機器能驗的規則

SPEC 就是需求規格，也是最常被跳過、最致命的一步。一般人給 AI 的需求是「幫我做個登入功能」——這對 AI 等於沒說，它會自己腦補。我們的做法是把模糊需求，一路蒸餾成「機器可以驗證對錯」的規則（我們叫 INV，invariant／不變量）：

判斷一條規格好不好，標準很簡單：

關鍵心法：規格的金礦不在「要做什麼」（happy path），而在「絕對不准發生什麼」（負空間）。安全問題幾乎都藏在沒寫出來的禁止事項裡。

第 2 層 Harness：廚房的水電，讓 AI 不失憶

這是最容易被外行忽略、但價值最高的一層。AI 的致命傷是每次對話都失憶。Harness 就是一組自動化機關（技術上是 hooks ＋把 hook 接到工具層的橋接腳本），幫 AI 顧三件事：

這層幾乎是一次性建好、之後所有專案共用。它不讓 AI 變聰明，它讓 AI 不會蠢。要把 Harness 換輕量一點、接本地模型的實戰細節，可以看 本地 Agent 踩坑實錄：Claude Code 接 Ollama 為何要換輕量 Harness。

Harness 裡面到底裝了什麼：hooks 與橋接程式

講白一點，hook（掛鉤）就是「在 AI 工作的某個時刻，自動幫你執行一段小程式」的機制。你不去改 AI 本身，只在它的生命週期上裝感應器和開關。設定寫在一個設定檔（settings.json）裡，AI 平台會在對的時刻自動觸發。AI 一次任務的生命週期，大概是這幾個時刻：

我們在每個時刻掛一段小程式，讓 AI「自動守規矩」：

hook 只是「時刻」，它本身不做事——真正動手的是它在那個時刻去呼叫的一段 shell 腳本。這段夾在「hook 事件」和「AI 真正要跑的 Bash 指令」中間的黏合腳本，就是橋接程式。它把 AI 想下的指令攔下來改寫（例如把 npm test 改寫成「輸出導到暫存檔、只回傳失敗那幾行、保留原本的結束代碼」），再讓工具去跑改寫後的那條指令——等於在 AI 和它的工具（終端機、Bash）之間插了一層可控的關卡。（技術上 Claude Code 的 hook 是用 updatedInput 改寫指令、讓工具只跑一次，不是 hook 自己跑一遍再把結果塞回去。）

最實用的例子就是「跑測試」。AI 想下 npm test，如果直接跑，上萬行輸出會一次灌進它的記憶、又貴又把腦塞爆。橋接腳本在指令真正執行前把它接管掉：

這一層要小心一條紀律：只對「會噴一大堆字」的窄名單指令（跑測試、編譯）動手，一般讀檔、撈資料的指令原封不動放行。不然把 AI 需要的完整內容也截掉，反而害它拿到殘缺資訊。同樣的橋接，也能拿來擋危險動作、或在指令跑完後記一筆帳。

{
  "hooks": {
    "SessionStart": [
      {"hooks":[{"type":"command","command":"cat ~/.claude/rules.md"}]}
    ],
    "PreToolUse": [
      {"matcher":"Bash","hooks":[{"type":"command","command":"~/.local/bin/trim-verbose.sh"}]}
    ]
  }
}

# PreToolUse hook（掛在 Bash）：不自己跑指令，只「改寫」AI 要下的那條，讓工具跑改寫後的版本一次。
# 只對 test/build 這種會噴大量輸出的動手；其餘原封放行。用 updatedInput 換掉指令：
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "updatedInput": { "command": "npm test 2>&1 | grep -E 'FAIL|ERROR' | tail -50" }
  }
}
# ← 工具實際只跑「改寫後」這條一次；成功/失敗由這條指令自己的結束碼決定（hook 不自己跑、不塞結果）

第 3 層 Workflow：出菜 SOP，用「對抗迴圈」保品質

一個廚師從頭做到尾，你不知道哪一步會出包。所以我們設一條「產出 → 找錯 → 打回重做」的對抗迴圈，外加兩道人工關卡：

• 動手的 AI 做完，另一個 AI 專門找它的錯，打回去重做（這叫 Generator-Verifier，產出者 vs 驗貨者）。
• 關鍵：驗貨的那個不能跟產出的那個共用同一套想法，不然等於自己改自己考卷，一定看不出錯。
• 要有明確的「什麼條件才算做完」（stop 條件），否則 AI 會無限迴圈——我們真的燒過一整天，就是 QA 沒有停止條件、找 bug 找了 21 輪停不下來。

那條迴圈為什麼不會空轉一整天？關鍵是有一個「PM 角色」把守兩道閘。少任何一道，迴圈就會發散、永遠收不完。完整流程長這樣：

幾條反直覺、但用血換來的規則：

還有一個關鍵：這套流程靠三份分開的文件撐著，混在一起就會亂——規格（要做什麼，改得慢）、紅線清單（絕不能違反的事，每修一個 bug 補一條）、SOP（誰在什麼時候做什麼，方法論成熟後鎖死）。

## INV 宣告
- INV-AUTH-001: 未登記手機號不可換到 session
- 驗證層: L3（resolver）
- 反例測試: TestOTP_UnregisteredPhone_Rejected

第 4 層 Agent：一張決策樹決定「這件事派給誰」

Agent 就是「動手的廚師」，差別在貴不貴、聰不聰明、資料外不外流。同樣一顆會用 GPT 的腦，差別只在有沒有手（工具）——這個觀念在 會用 GPT 就會用 Agent：同一顆腦，差在有沒有手 講得更白。到底一件事該派給誰？照這張決策樹走：

實測結論：在我們這台機器上，配本地小模型時 Pi 表現最好，CC 對小模型反而太重。

pi -p -a --thinking off --provider ollama --model qwen3:8b \
   "照 SPEC.md 產生 hash.ts；只准用 bcrypt，別改其他檔"

第 5 層 大腦：換腦袋能力天差地別，本地小腦會偷偷降級

同一個廚師（agent），換不同腦袋（模型），能力天差地別。雲端大腦（Claude 的 Opus／Sonnet／Haiku）聰明，但貴＋資料外流；本地大腦（Ollama 跑的 qwen3:8b 等）免費、資料留在公司內，但小、慢。要落地一台自己的私密 AI 分身，可以參考 DGX Spark 打造私密 AI 分身：選一台、跑哪個模型、Day 1 落地。

我們用 A2A 實驗驗過一件對企業很重要的事：把一份「production 等級的登入系統設計稿」丟給本地小模型做，它會分岔成兩種結果——

# 本地、單人用：Ollama（好裝、低併發，資料不出門）
export OLLAMA_KEEP_ALIVE=30m   # 關鍵：模型別一直被卸載
ollama serve                   # 開伺服器
ollama run qwen3:8b            # 載入一顆模型

# 很多人同時打、要高併發吞吐：改用 vLLM（重點是併發，不是模型大小）
vllm serve Qwen/Qwen3-32B --port 8000   # 有 GPU 就上更大顆的腦；8B 也能跑，看你要多大

進階：什麼時候該從「一個廚師」升級成「一支團隊」？

前面說 Agent 是動手的廚師。但有些菜一個廚師就做得完，有些要一整個團隊。「什麼時候開團隊、怎麼開」本身就是 SPEC 和 Workflow 的變種——決定「派幾個人、各做哪一小塊、做完怎麼算數」，就是在寫一份規格和流程。這件事我們做過非常多次，也失敗過非常多次：開了團隊反而越改越亂、改了一整天收不了尾，甚至為了收拾平行改檔的爛攤子動用到特殊的版本控制工具。這一段把踩過的坑講白。

先搞懂：「開很多代理」不等於「Agent Team」

先破一個超常見的誤會。很多人跟 AI 說「幫我開很多代理」，看到一堆代理在跑，就以為這是 Agent Team。其實不是。「一堆各做各的代理」跟「一支真正的團隊」，差在四件事：

這個差異，正好解釋一個很多人碰過、卻講不出所以然的怪現象——

先破迷思：多找幾個 AI，不是免費的

直覺會覺得「人多好辦事」，但這在 AI 身上常常反過來。幾個實測證據：

Agent Team：一個人，還是一支團隊？

不要預設「大專案就開團隊」。照這張閘一路問下來：

我們自己歸納出來的判準（不是論文結論）：只有三種情況真的值得拆團隊——① 有一堆髒資訊會污染主腦（派子代理去做髒活、只回幾十字摘要）；② 要同時探索多個獨立方向（目標是「蓋得廣」不是「跑得快」）；③ 工具太多或人設衝突。而且要按「資訊邊界」拆，不是按「工作類型」拆——寫功能的 AI 就該順手寫它自己的測試，因為它已經有完整脈絡；硬把功能和測試拆給兩個人，只會逼對方重新搞懂一次。

怎麼編團隊：看「視角」，不是看「頭銜」

• 不要問「我有 3 個位子，塞哪些角色」，要問「這件事需要哪些視角想過」。人數是算出來的結果，不是一開始就定的輸入。
• 每個視角打分（有多重要 × 涉及多廣）：高分給專人、中分兩個視角共用一人、低分塞進別人的任務說明裡順便戴帽子。
• 反直覺：越小的任務越需要資深視角。一個 3 行的「健康檢查」端點，寫程式的風險≈1，但「這個端點決定要不要重啟正式主機」的維運視角≈6——所以那 3 行該給一個維運腦來寫，不是隨手丟給打字快的。
• 受機器記憶體限制：一台 32GB 的機器，扣掉系統，大概同時跑十幾到二十幾個混合模型的 agent。超了就把最不重要的兩個併起來。

動態派工：用完即拋、小而專注的 agent（這是解藥）

「改一整天收不完」的解藥，是不要養一排常駐團隊，改成每個回合依當下任務臨時生出、範圍鎖死、做完即丟的 agent：

• 範圍鎖死是關鍵：每個 agent 只驗 1～3 條紅線、被明令「不要順便找任何其他 bug」。這樣每個 agent 有邊界、會收斂；不鎖範圍，就是「找到天荒地老」的無限迴圈。
• 現在的工具還能自動分層：主腦用最聰明的模型負責「想」跟統整，一堆掃描小工自動派便宜快速的模型負責「找」，不用手動配。
• 硬限制要知道：同時大約最多 16 個（8 核機器實測約 7 個）——注意這是平台本身的併發上限，跟前面「記憶體能撐十幾廿幾個」是兩件事、兩個都要滿足（取小的）；單次累計上限約 1000 個、而且中途不能停下來問你——需要你臨場拍板的題目，別丟進這種自動流程。

Agent Team：合併，以及為什麼會用上 jj

一支團隊平行改檔，最後要把成果合在一起。這一關最容易爆，也是 Tom 提到「甚至動用到 jj」的地方。問題的本質不是工具好不好，而是「衝突發生時，需不需要你人在現場」：

所以 jj 的價值不是「比較快」，是「讓系統在你睡覺時照跑」——你不可能盯著 3 個 agent 即時解衝突。但底層有兩件事要先做對：

• 每個 agent 一定要有自己的獨立工作區（各自的資料夾）。兩個 agent 同時寫同一個檔＝檔案層的搶位子，這是 VCS 救不了的，得先隔離。
• 日常還是用 git，只有團隊合併那一刻才切 jj（少數幾個指令），零綁定、隨時拆掉、git 專案照樣完整。判準很簡單：這些 agent 需要動手寫檔嗎？純稽核／review＝只讀＝用 git 就好；平行開發、debug 試假設＝要寫＝jj 才划算。
• 踩過的血雷：解完衝突別把一長串指令串一起跑。其中一步默默失敗（例如工具說「檔案已被改」你卻當沒事）會被後面成功的指令蓋掉，結果把「衝突標記」原封不動送上去。鐵則：解完衝突、`git add` 之前，先用 grep 確認檔案裡沒有 <<<<<<< 這種標記，才准往下走。

先搞懂三個詞：RAG、GraphRAG、CAG——以及為什麼要有它們

接下來會一直出現 RAG、GraphRAG、CAG。先用一頁把「各是什麼、為了補哪個洞」講清楚，後面幾節才好深入。

根源問題：光一顆模型不夠用。通用模型很會講，但它不知道你公司的事、會一本正經地編（幻覺）、而且知識凍結在訓練那一刻。所以你得想辦法「把你的知識餵給它」——這三個詞，全是在解這件事，差別只在「怎麼餵、餵什麼形狀的知識」。

正道腦 / BUG 腦 / GraphRAG：把知識結構化

前面五層是「怎麼做事」。這四個是「怎麼讓這套東西越用越聰明、而且不會被 AI 幻覺帶歪」。這才是跟一般「買個 AI 工具來用」最大的差別。

BUG 腦（防錯腦）vs 正道腦：兩種知識分開存

工業、醫療、長照這種錯了會出人命或賠錢的場域，必走正道腦。而最核心的一條設計哲學，是我們用血換來的判斷：把每塊知識切成「事實」和「判斷」兩半——

GraphRAG：真相在「圖」，不在「模型」

GraphRAG 是把知識存成一張關係網（圖），而不是塞進 AI 模型裡。最關鍵的一張概念圖：知識放在外面那張圖，模型只是「一張可替換的嘴巴」，嘴換了，腦子不變——

它有三個殺手級好處：

餵知識進圖的實務做法，是資深業界獨立驗證過、跟我們架構一致的兩階段加權：

前提是第一刀要挑「大方向八成像、只改細節」的領域下手，不然老手覺得「全錯不如重寫」，整個崩掉。想看 GraphRAG 跟一般 RAG 的差別、以及一個完整的實作案例，可讀 GraphRAG vs RAG + A2A：後端工程師的請假流程 AI 實作。

為什麼 LLM 需要 GraphRAG？它到底幫 LLM 補了什麼

LLM 本身已經很會講話了，為什麼還要接 GraphRAG？因為一顆「單獨的」LLM 有幾個天生的洞，GraphRAG 正好補這幾個。先打個比方：

具體來說，GraphRAG 幫 LLM 補這四個洞：

一個實例：有接、沒接 GraphRAG，答覆差多少

先看一小段「知識圖」長什麼樣——圓框是實體（節點），連線是關係（邊）。GraphRAG 回答時就是照著這些關係「走」，而不是找最像的一段文字：

現在拿同一個問題，比較「沒接圖」跟「接了圖」的答覆：

GraphRAG vs 普通 RAG，怎麼接

這裡也給一個「一定懂」的類比，因為很多人到現在還用舊的 RAG 認知去想 GraphRAG，結果就想歪了。先把兩個擺在你熟的東西旁邊：

那「以前用 RAG」和「現在該用 GraphRAG」的場景，差在哪？

怎麼把「腦」接到 AI 上：RAG 的三種接法

知識做好了，怎麼讓 AI 用到？答案是 RAG——讓 AI 開口回答之前，先去外面的知識查一遍，把查到的東西當根據再講。RAG 三個字就是這三步：Retrieval（檢索，去查）→ Augment（把查到的塞給 AI 當根據）→ Generate（AI 據此生成答案）。流程長這樣：

差別在「檢索器怎麼查」。我們實作過三種接法，對應不同需求：

接的時候有三個用血換來的紀律，不守就會踩雷：

• 關鍵路徑別讓小模型自己寫查詢語法。本地小模型常把關係方向寫反（該查「A 導致 B」寫成「B 導致 A」），語法對、卻查回 0 筆。正解是用「事先驗證過的固定查詢模板」，只讓它填空。
• 先把「確定性的事實」印出來，AI 只當潤飾層。這樣就算 AI 那張嘴當機了，核心答案照樣成立——因為真相在圖裡，不在 AI 的記憶裡。
• 查詢繞太多層就「攤平」。三段關係（A→B→C）小模型接不動，就把常查的答案直接掛在節點上，查詢從三段降成兩段，穩很多。

docker run -d --name neo4j -p 127.0.0.1:7687:7687 \
  -e NEO4J_PLUGINS='["apoc"]' \
  -e NEO4J_server_memory_heap_max__size=512m neo4j:5

MATCH (c:Channel {name:$ch})-[:SYNC_FAILED]->(e:ErrorType)
RETURN e.name, e.root_cause, e.action

CAG vs RAG：知識放模型「外面」還是「裡面」？

把公司知識餵給 AI 有兩條路，差別在知識住在哪——搞清楚這個，才知道什麼時候用哪個。

光講不夠——我真的在地端把兩個都跑了一遍，量速度也量對錯：

A2A：agent 之間怎麼互通

A2A（Agent-to-Agent）是「讓一顆腦去呼叫另一顆腦」的協定。要講清楚它，最快的方式是先跟大家比較熟的 MCP 對照——這兩個常被搞混，但方向不一樣：

兩者不衝突、是互補：MCP 讓一顆腦長出手去用工具，A2A 讓一顆腦去指揮另一顆腦。而 A2A 本身，又有兩種用法——差別在對面是「講完就散」還是「開一件任務跟你來回」。

A2A 的兩種用法：訊息模式 vs 任務模式

照 A2A 官方規格（Life of a Task），對面 agent 收到你的話之後，有兩種回應方式：

任務模式的「生命週期」長這樣——一件任務會在這些狀態間移動，一旦走到終點（完成／取消／失敗）就不能重啟，要改只能開一件新任務連回去：

官方的「follow-up 範例」最好懂：你先請它畫一艘帆船（任務 A 完成）→ 你說「幫我把它改個顏色」，這句帶著「參考任務 A」的標記（規格叫 referenceTaskIds）→ 它開一件新任務 B、掛在同一段對話（contextId）下、產出同一張圖的新版本。三個識別碼各司其職：

A2A：把舊系統「包成一顆腦」

這是 A2A 最實用、對企業最值錢的用法。一個跑了十年的舊系統是「死」的，它不會自己長出技能；A2A 就是補這個洞——把舊系統的能力包裝成幾個 Skill、掛上一張「Agent Card（名片）」，讓任何 AI agent 直接發現它會什麼、直接呼叫。這其實是歷史重演第三次：

關鍵推論：這一層可以省掉很多「做給人點的畫面」。系統的能力直接暴露成 Skill 給 agent 呼叫，很多時候就不必再做一套 UI。要看一張真實的 Agent Card 長怎樣、以及跟 MCP 的白話對照，可讀 會用 GPT 就會用 Agent：同一顆腦，差在有沒有手。

安全分層：名片公開 ≠ 大門敞開

不管是訊息模式還是任務模式，都會碰到一個最常被誤會、務必講清楚的授權分層：

GET /.well-known/agent-card.json
{
  "name": "請假規則查詢 Agent",
  "capabilities": { "streaming": false },  // 不推播，agent 自己 poll
  "skills": [
    { "id": "get_leave_policy",            // 查規則 → 立刻回答案
      "auth": "none" }                      // 唯讀 → 公開
  ]
}

GET /.well-known/agent-card.json
{
  "name": "請假申辦 Agent",
  "capabilities": { "streaming": true },   // 有 SSE 推播進度（可選）
  "skills": [
    { "id": "apply_leave",                 // 送審 → 開一件任務
      "auth": "invite-token" }              // 寫入 → 要憑證
  ]
}

A2A：會不會卡死你、正名、部署

這是接 A2A 時最該問的一句：「對我來說這就是一個 API 端，會不會被你的 AI agent 佔住、把我的 thread host 卡死？」答案：訊息型不會；任務型做對不會、做錯才會。

• 訊息型（message）：短連線、秒回、執行緒立刻釋放，跟一般 REST 一樣，不會卡。
• 任務型（task）：危險只發生在你把它做成「開著連線、一直等任務跑完才回」。正確做法是不要 hold 連線——

要打開／守住的幾個關鍵（就是防「被佔住」的護欄）：

• 立刻回 taskId、工作進 queue：背景 worker 去做，不佔請求執行緒——這正是 A2A「任務有 id ＋ 狀態」存在的理由。
• 每個請求都有逾時：慢 agent 不能永遠佔一條 thread。
• 每個 token 的併發上限 ＋ rate limit：一個 agent 不能狂開一萬個任務。
• queue 滿了回 429（限流），不是把人卡住：正好呼應前面那個 HTTP 429 的例子。
• 要用 SSE 推進度就限量 ＋ 心跳逾時，別讓連線無限開著。

A2A 正名：嚴格講，是「Agent → API」

你這句點得很準。我們一直說 A2A 是「Agent-to-Agent（腦對腦）」，但拆到底層，它的實體就是「Agent → API」：

你（agent）打的就是一個 HTTP API 端點，那個端點用一張 Agent Card「自我介紹」它會什麼。之所以叫「agent 對 agent」，只是因為 API 背後那端可能自己會思考、會跑多步驟任務——但從你這條線看，就是 agent 在打 API。

那為什麼還是叫 Agent-to-Agent，不是 to-API？「做完」又怎麼判定？

你這一問，正好把上面那句「就是 API」校準成兩層——這也是照 A2A 官方 Life of a Task 的重點：

差別的核心，就是你點的「對方 agent 有 life cycle」。普通 API：HTTP 回 200 ＝ 這次呼叫結束，它不記得你、也沒有「進行中」這回事。A2A 的 task 不一樣——你拿到 taskId 後，它會在自己的狀態機裡移動，走到「終點狀態」才算做完：

那「你」怎麼知道做完了？兩種：① 定時 GET /tasks/{id} 查狀態；② 訂閱串流（SSE）讓它把狀態變化推給你。一旦狀態是終點（completed／failed…）就是做完；終點不可重啟，要改就開一件新任務、用 referenceTaskIds 連回舊的。

POST /skills/get_leave_policy
  → 直接查、直接回答案（同一個 response）
  # 請求執行緒只佔一下下，跟一般 REST 一樣

POST /skills/apply_leave
  taskId = queue.enqueue(job)        # 丟進工作佇列
  return 202 { "taskId": taskId }    # 秒回、請求執行緒立刻釋放

# 另一組「worker 池」（不是 web 執行緒）在背景跑：
worker:
  job = queue.pop()
  存狀態到 DB： working →（input-required?）→ completed
  # ← 這裡才是「真的在做事的 thread」，但跟 web 請求池分開、有上限

GET /tasks/{taskId}
  → 從 DB 讀狀態回給 agent（submitted / working / completed…）

即時 vs 非同步，差異重點一張表看完：

A2A 部署：掛在系統前面的轉接層

這個理解完全正確，而且正是推薦做法：A2A 跟你本身的系統是解耦的。你不用改你的 ERP（SAP、鼎新 Digiwin、iDempiere… 都一樣），只要另外寫一層「轉接層（adapter）」掛上去——它一邊講 A2A、一邊去呼叫你的系統。這層可以放在另一支程式、甚至另一台機器／另一個 domain：

轉接層裡每個元件在幹嘛：

一條請求怎麼走完（對照前面 sync／async 兩種模式）：

所以你的 ERP 本體乾乾淨淨、根本不知道 A2A 存在——這正是前面「把舊系統「包成一顆腦」」的落地拓撲：系統不動，轉接層另外長。

共用知識服務（MCP）：別讓每個人重寫

知識做好了，agent 到底怎麼「用到」它？先分清楚走哪一層：「給 agent 一個知識來源」走的是 MCP（腦 → 工具），不是 A2A（腦 → 腦）。A2A 是「你的 agent 去呼叫另一個會思考的 agent」；而 RAG／知識比較像「一個工具、一個資料源」，這正是 MCP 的守備範圍。

你擔心的「難道每個 agent 都自己寫一套 RAG？那不是很怪？」——完全正確，那就是要避免的反模式。如果每個 agent 各自寫檢索碼（連向量庫、寫查詢、處理 auth、管更新），就是每一隊重造一次輪子。企業做法是把知識做成「一個大家共用的服務」，寫一次、所有 agent 連上去用：

檢索邏輯（連線、查詢模板、GraphRAG 走關係、auth、新鮮度）只寫在服務端一次；每個 agent 只是連上去用。知識更新也一次（charge 圖）→ 所有 agent 立刻看到新真相（呼應前面「真相在圖不在模型」）。（提醒：圖保證「事實不背叛」，但「照著講對」仍吃模型的對點與生成品質——弱模型撈對了也可能說錯。）三種做法一比就清楚：

# graph_service.py — 檢索寫一次（全唯讀 Cypher、回傳附 cypher 當出處）
def path(self, source, target, scope="esg", max_hops=6):
    cy = f"MATCH p=shortestPath((a:{lbl} {{id:$a}})-[:REL*..{max_hops}]-(b:{lbl} {{id:$b}})) RETURN [n IN nodes(p)|n.id]"
    rows = self._read(cy, a=source, b=target)     # 純 Cypher，跟 LLM 無關
    return self._wrap(scope, lbl, cy, rows, note) # 回 {cypher,rows,note}；cypher=出處

# mcp_server.py — FastMCP 薄包，一個 decorator 就開放給任何 agent
@mcp.tool()
def graph_path(source, target, scope="esg", max_hops=6):
    """兩實體之間怎麼連 — 最短路徑；vector RAG 做不到的『沿線走』。"""
    return svc.path(source, target, scope=scope, max_hops=max_hops)

# agent 一行連上（本機 stdio、用完即起）
claude mcp add hr-graph -- .venv/bin/python graph-demo/mcp_server.py
# 之後直接問「本公司到 CDP 怎麼連」，它自己會叫 graph_path/… — 零檢索碼

實戰：把知識圖包成 MCP（hr-graph）

# 位置：onboarding-system/graph-demo/（檢索層 graph_service.py＋薄包 mcp_server.py）
# 本機 agent：一行加進 Claude Code（stdio，用完即起、非常駐）
claude mcp add hr-graph -- .venv/bin/python graph-demo/mcp_server.py
#   之後對話直接問：「用 hr-graph 查 本公司 到 CDP 怎麼連」

# 別台／遠端 agent：走 HTTP（實測連法）
claude mcp add --transport http hr-graph https://neo4j.tomting.com/mcp \
  --header "Authorization: Bearer hrg_xxxxxxxx" -s user
#   MCP /mcp 併進 graph-demo/app.py、重用既有 tunnel、Bearer token、全唯讀（免 SSE）

補充：要「強制、不可繞過」——Enterprise Managed Settings

上面「description ＋ server instructions 隨連線發全公司」是寫一次、隨連線走的做法——但它本質是「盡力」：模型仍可能不照做，而且只管得到 MCP 工具怎麼用。要做到「必須遵守、使用者繞不過」，Claude Code 有原生的一層：Enterprise managed settings。

關鍵開關：allowManagedMcpServersOnly ＋ allowedMcpServers（MCP 白名單強制，把你上面 hr-graph 那套從「盡力」升級成「強制」）、claudeMd（全公司 CLAUDE.md，使用者刪不掉）、strictKnownMarketplaces（鎖 plugin 只能從核准來源裝）。檔案在系統層（/Library/Application Support/ClaudeCode/、/etc/claude-code/、C:\Program Files\ClaudeCode\），或直接用主控台推。

# 政策就寫在每個 tool 的 docstring（＝MCP description；mcp_server.py，寫一次）
@mcp.tool()
def list_scopes():
    """列出可查的知識領域…先叫這個看有哪些圖（esg / hr…）。"""      # ← 教它「先叫我」
@mcp.tool()
def graph_search(term, scope="esg"):
    """在圖裡模糊找實體 id…不確定實體正確名稱時先用它對點。"""       # ← 教它「先對點」

# 發給全公司的就這一行；連進來，上面的 docstring 自動成為該 agent 的工具說明
claude mcp add --transport http hr-graph https://neo4j.tomting.com/mcp \
  --header "Authorization: Bearer hrg_xxxxxxxx" -s user

導對之後的真實使用經驗（下面是真的從這張 43 節點的 ESG 圖撈出來的）——問「幫本公司做 ESG 報告要準備什麼」，agent（被規則導去 hr-graph）：

實戰復盤 · 某企業專利 GraphRAG：知識怎麼「塞」進圖，圖又怎麼「修」

前面講的都是「該怎麼做」，這章真的做了一次——把某企業的智財管理培訓投影片，變成一顆工程師與發明人都能問、主管能審的 GraphRAG。一顆圖能不能長期用，只看三件事、而且有先後順序：怎麼「塞」→ 怎麼「驗」→ 怎麼「修」。下面按順序拆，每一步用黃底標出「該怎麼做」的重點。

一句話收：塞得準（機器打樣板＋老手矯正）、驗得出（用問句不用查表）、修得動（charge ＋ Pending 人閘），圖才會活。這也正是整篇的主張——真相在圖、判斷可糾正、手有人閘。

企業 AI vs 玩票 AI：分水嶺

講到這裡，把整個知識這塊的價值收成一句：不是「知識越多越好」，是「相關的知識、被低門檻地取用／貢獻／信任」。

而真正的重點，是把三個門檻降下來——這才是 A2A ＋ GraphRAG 的價值所在：

企業藍圖：各單位自維護、agent 來組合

把前面全部串起來，一家公司該長成這樣——各單位把自己領域的知識榨出來、自己維護；agent 在上面組合、跨單位取知識＋辦事：

你的藍圖方向完全正確（這叫「聯邦式企業知識架構」）。落地時記住五點：

落地兩件事：知識放哪、不會用 agent 的員工怎麼用

前面的 claude mcp add 是給工程師的路。真到全公司，你會撞到兩個現實問題：①知識到底集中在哪個「一個地方」統一改？②多數員工連 agent 都不會用。兩個都有乾淨解。

知識有兩種，各有「一個中心」——別散進每個人的 prompt

Gateway 長這樣——前面各種 client 用 API 連進來，後面各種模型連出去，CAG（知識注入＋快取）就掛在中間那一個位，改一次全員生效：

多數員工連 agent 都不會用——那就別給 agent，給一個聊天框

誠實的反方：什麼時候你其實不需要（或別急）

只聽支持自己的聲音會翻車。這裡把最強的反方攤開——很多情況它們是對的。核心一句：RAG／GraphRAG／A2A 都是「門檻之上才回本」的工具，不是預設。

上線後怎麼監控與維護（生命週期）

導入不是終點。這套東西會腐化——而且腐化的圖比沒有圖更危險：agent 拿到過期的關係、還附「出處」，變成更可信的錯。所以上線那天起，要有人、有流程、有回滾。

治理與資安：給 agent 裝了「手」，就得管好

這套東西＝給 agent 一顆腦（知識）＋一雙手（A2A 動作技能）＋餵它外部語料。腦＋手＋外部輸入三合一，是傳統資安沒完全涵蓋的新攻擊面。裝手之前，先把這五條想清楚。

怎麼用一個「請來做 AI 導入」的人

多數老闆不是自己做，是請人做。那「怎麼用這個人」才是真問題：我怎麼信任他？有些資料他不能看，怎麼辦？解法只有一句：信任靠「結構」，不靠「賭人品」——把情境設計成「就算他不可信、就算 AI 出錯，也傷不到你」。

一張圖總結：從模糊需求到交付的完整流程

鐵律：順序不能亂——規則書還沒就位就先開工，就是災難。骨架可以一天搭好，但規則內容是一坑一坑累積出來的，不可能一天到位。

對「公司」的落地意義

第四部到這裡：市面上的 AI 是廚師和腦袋，但一家餐廳能不能穩定出好菜，靠的是菜單規格、廚房水電、出菜 SOP，還有那本傳給徒弟、可以當場糾正的食譜。把這五層加四顆腦搭起來，你買的就不再是「一個會失憶的實習生」，而是一支越用越強的團隊——但團隊一大，還缺最後一層：那張管住它們的控制台。這就是第五部。

一張 Cisco 海報，逼我問了一個問題

前面四部，把五層加四顆腦搭起來了。但東西一多，會冒出一個新問題：誰來管這些腦？我是在展場看到一張 Cisco 的 agentic AIOps 架構圖，才被逼著把這個問題講清楚。那張圖由上到下是：自然語言 → 多個 agent ↔ LLM（雲端或地端）→ 中間一層掛著四個 Manager：LLM Manager、Skill Manager、KB Manager、MCP Manager → 底下接 Splunk、ThousandEyes、一排網路設備。

那件事是：當腦、工具、模型都變多，你需要一層控制台——agent 不該自己到處亂抓模型、技能、知識、工具，中間要有一層管「誰能用什麼、怎麼路由、健不健康」。這層現在業界正在給它取名：Agent Gateway / AI Gateway / control plane（AI 的控制平面）。名稱已經在收斂（Kong、AWS、Cloudflare 到 Linux Foundation 的 agentgateway 專案都在用同一組詞），但多數產品還在早期預覽。換句話說：方向對，工具還在長。

四個 Manager：你如果照前四部做，其實已經散做了

把四個 Manager 拆開看，你會發現前面幾部其實已經各做了一塊雛形，只是散著、沒收成一層。每一塊都有現成的開源／標準可以抄：

看懂這張表，重點不是「Cisco 好厲害」，而是：控制平面不是要你從零建一個平台，是把你手上四塊散的東西，收成一層可管理的介面。模型選擇散在各支腳本裡→收進 LLM Manager 一份 config；工具散在各個 MCP→收進 MCP Manager 一張註冊＋健康表。收斂本身就是價值。

但這張圖有個高度，看漏了會做錯：它是「公司層級」的架構。四個 Manager 是一層集中維護的平台，由少數懂設定的人顧一次；其他所有人——尤其非工程師——看海報最上面那格「自然語言交流」，只是講話，不碰任何設定檔。

反過來看個人：如果你自己早就在管一堆 skill、知識庫、模型選擇、一排 MCP（很多重度使用者玩幾個月後其實都到了這步），那你已經在跑一個個人版的控制平面了——只是散在各處，而你自己就是那個「會設定的少數」。所以這不是「要不要建」的問題，是同一套 Manager、兩個高度：個人版的功課是把你已經在管的收乾淨；公司版的功課是把它集中、再用 MCP 讓多數人零設定消費。

同一件事，一個人做 vs 一間公司做

把這四個 Manager 換個角度看會更清楚：一個重度使用者，自己就管得動這四樣（散著管，反正自己人）；一間公司要給全體用，就得把每一樣「集中成一個服務」。差別不是規模大小，是前面那句——可不可收回。

看整張表，同一條線再出現一次：一個人不必跟自己撤銷權限，所以「散著、拷貝、手動配」都行；一間公司每一格都被「要能收回」這條，逼成「一個帶身分驗證的集中服務」。其中變化最大的是技能——一個人一個資料夾就夠，一間公司卻非得把它服務化不可，因為資料夾一旦拷貝出去就收不回來了。

連 Cisco 都把「人閘」當核心，不是選配

這張圖最讓我在意的，不是那四個 Manager，而是 Cisco 官方版四個核心元件裡的最後一個：human-in-the-loop gates（人在迴圈的閘門）。這跟本文一路在講的那句話，是同一件事——腦可以錯（可以糾正），手不能亂動（要人閘）。

所以如果你只從這一部帶走一句話：控制平面 = 讓能力可管、可換，再加上一道「動作前人要點頭」的閘。前者省你重工，後者保你不出大事。

落地：別建平台，先收成薄薄一層

最後講落地。個人跟公司兩個高度，功課不一樣：個人版——你若已經在手動管這些（很多人玩幾個月就到了），落地是把散的收乾淨、別急著上一整套治理產品（多半還在預覽，押身家太早）；公司版——落地的難點不是設定檔，是「誰集中維運這層、怎麼讓非工程師零設定消費」。兩邊共通的一點是：每個 Manager 的「最小可用」形態其實很輕——LLM Manager 可能就是一份「哪種任務用哪顆」的設定；MCP Manager 可能就是一張「有哪些工具、健不健康」的清單。

1. 先做最痛的那個——通常是 MCP Manager，因為工具一多最容易亂（誰在哪、還活著嗎、誰能連）。
2. 再把模型選擇收成一處——用 LiteLLM 之類把散在各腳本的「用哪顆模型」收進一份 config，馬上省重複。
3. 知識與技能通常已經比較成熟，後補——你若已有 GraphRAG 和一套 skill，這兩塊先維持，等前兩個穩了再收。

整篇一句話收尾：菜單規格、廚房水電、出菜 SOP、可糾正的食譜、四顆腦——那些是「能力」；控制平面是「讓這些能力可管、可換、可把關」的那張出菜口的桌子。先把能力搭起來、真的用出效益；等腦多到開始亂了，再收成薄薄一層控制台——別為了架構對稱，先蓋一個沒人坐的控制室。能力先行、治理隨後，順序不能反。這才是把「一個會失憶的實習生」，變成「一支越用越強、而且管得動的團隊」的完整那條路。