Agent Teams：Mesh 拓撲與五種死法

知識漫畫系列 — 用最少的字，講最硬的技術。

被誤解的星型

Claude Code Agent Teams 的通訊系統是一條全開放的管道。

SendMessage 的 recipient 欄位接受任何 teammate name，路由邏輯只做一件事：

把 JSON append 進 ~/.claude/teams/{team}/inboxes/{recipient}.json

沒有白名單、沒有 ACL、沒有「只能跟 Lead 說話」的硬編碼。

但所有人都跑星型。為什麼？

因為 Lead spawn teammate 時寫的 prompt 結尾那句：

"When done, send a summary message to the team lead."

一句話鎖死了拓撲。

打開 Mesh

把 spawn prompt 改成：

"You can coordinate directly with 'backend-dev' via
SendMessage(recipient='backend-dev'). Agree on the API
contract before either of you starts coding. Send final
summary to team-lead when both sides are done."

系統會照常路由。frontend-dev 的訊息寫進 inboxes/backend-dev.json，backend-dev 下次 turn 自動收到。

不需要改設定、不需要改工具、不需要改任何程式碼。

Mesh 通訊圖

frontend-dev ←──SendMessage──→ backend-dev
      │                              │
      └──────SendMessage─────→ team-lead
                                     │
                          (只收最終結果，
                           中間協調看不到)

Lead 唯一的可見性來源是 idle notification，但裡面只有四個欄位：

{ "type": "idle", "from": "frontend-dev", "timestamp": "...", "idleReason": "..." }

Peer 之間聊了什麼、協調了什麼，Lead 一無所知 — 除非 teammates 主動回報。

五種死法

不管是星型還是 Mesh，teammate 的 process 都有五種終結方式。

死法一：正常關機 ✅

Lead 發送 shutdown_request，teammate 回覆 approve: true，系統回傳 teammate_terminated。

三行 log，乾淨利落。

這是唯一有完整協議的死法。

死法二：Rate Limit 靜默死亡 ☠️

API 額度用盡，最後一條 log 印出：

"You've hit your limit · resets 5am"

Process 直接結束。沒有任何通知送到 Lead 或 peer。

Inbox 裡可能還有未讀訊息。

這是最毒的死法。

在 Mesh 拓撲下更致命 — 如果 A 正在等 B 的 API 合約回覆，但 B 被 rate limit 殺掉了，A 會永遠等下去。Lead 只看到兩個 idle notification，以為他們都在正常工作。

死法三：做完事自然 Idle 😴

Teammate 完成工作，最後一條 assistant message 是純文字總結，沒有 tool call。

Runtime 判定「沒有下一步」，發出 idle notification。Process 不會結束，而是進入等待：有新訊息寫入 inbox 就喚醒，沒人理就一直掛著。

在 Mesh 下，這是正常的「等待 peer 回覆」狀態。

但 Lead 無法區分「在等 peer」和「真的做完了」。

死法四：Leader Session 結束 💀

Lead 關掉 terminal 或 session timeout。

所有 backendType: "in-process" 的 teammates 跟著死 — 它們跑在同一個 process tree 裡。

沒有 shutdown 協議、沒有通知、inbox 裡的未讀訊息成為孤兒檔案。

Mesh 下如果 A 和 B 正在對話，Leader 一退出，兩個人同時消失。

死法五：Max Turns 超時 ⏱️

Task(max_turns=N) 或模板設定的 30 分鐘上限。到了就強制停止。

在 Mesh 下，如果一方 timeout 而另一方還在等回覆，效果和 Rate Limit 靜默死亡一樣 — 等待方永遠收不到訊息。

Mesh 的真正風險

五種死法裡，只有第一種（正常關機）有完整的生命週期管理。

其餘四種都是「靜默消失」— 對方不知道你死了，你不知道對方在等你。

星型下不是大問題

所有訊息都經過 Lead，Lead 收不到回覆就知道出事了，可以 shutdown 然後改用 sub-agent 接手。

但 Mesh 下…

兩個 peer 互聊、Lead 看不到內容。其中一個靜默死亡後：

A → SendMessage(to=B, "你的 API schema 定好了嗎？")
    ↓
    寫入 inboxes/B.json ← 成功（系統不管 B 死活）
    ↓
    A 等待回覆... idle... idle... idle...
    ↓
    Lead 看到 A 一直 idle，以為 A 卡住了
    ↓
    Lead shutdown A
    ↓
    兩個人的工作全白做

結論

星型不是技術限制，是風險管理。

管道全開，但開了 Mesh 就得自己處理「沉默的死者」問題。

目前系統沒有心跳、沒有送達確認、沒有「對方已離線」的回傳。

SendMessage 永遠 success: true
即使對方的 process 早就不在了