文檔這東西，就是你畫好一張多智能體架構(gòu)圖，然后半年不管，等再翻出來時(shí)發(fā)現(xiàn)早就對(duì)不上了——系統(tǒng)悄悄改了、新加的代理沒畫、老邏輯也變了，而沒人費(fèi)勁去更新圖片。swarm-test v0.3.3想解決的就是這個(gè)痛點(diǎn)：它從你實(shí)際運(yùn)行的代理拓?fù)渲苯由蓤D表，文檔永遠(yuǎn)和系統(tǒng)保持同步。我拿自己那套14代理系統(tǒng)跑了一下，問題像被放大鏡照亮一樣跳出來。

一眼過去，圖里那顆紅得扎眼的節(jié)點(diǎn)是OrchestratorAgent。它被標(biāo)為單點(diǎn)故障，爆炸半徑高達(dá)92%。什么叫爆炸半徑？就是如果這個(gè)節(jié)點(diǎn)掛了，92%的其他代理會(huì)跟著遭殃。再看整體形狀，幾乎全部14個(gè)代理的箭頭都匯向兩個(gè)樞紐：一個(gè)叫OrchestratorAgent，另一個(gè)叫TrainerAgent。這兩個(gè)家伙，任何一個(gè)倒下，整套系統(tǒng)就癱了。這種結(jié)構(gòu)性問題，你在控制臺(tái)打出來的表格里根本看不到，可換成這張圖，瞬間就懂了。

出圖只需一條命令：swarm-test graph my_crew.py --format mermaid。跑完后你會(huì)得到一段Mermaid語法，直接就能粘到GitHub的README里。比如這樣：graph TD；OrchestratorAgent[OrchestratorAgent ?? SPOF]:::spof；TrainerAgent[TrainerAgent]:::healthy；ImageValidatorAgent --> OrchestratorAgent；classDef spof fill:#ff4444,stroke:#cc0000,color:#fff；classDef healthy fill:#44cc44,stroke:#22aa22,color:#fff。GitHub、GitLab還有Notion都能原生渲染，你提交之后自然就在文檔中展現(xiàn)，該紅的紅、該綠的綠，還有中等風(fēng)險(xiǎn)的黃色，每一種顏色都對(duì)應(yīng)著可靠性分析里那套風(fēng)險(xiǎn)分類。

看你準(zhǔn)備把圖用在哪兒，工具提供了三種輸出格式。Mermaid最適合README和Wiki，因?yàn)樗羌兾谋荆瑑?nèi)聯(lián)渲染、可版本控制，在PR里做diff時(shí)清楚明了，一行改動(dòng)都藏不住。DOT格式給Graphviz流水線或者你自己搭的工具鏈留著。需要做PPT或者塞進(jìn)外部分享文檔，就直接指定PNG：swarm-test graph my_crew.py --format png --output topology.png。唯一要注意的是PNG依賴matplotlib，得先裝好swarm-test[png]這個(gè)擴(kuò)展。

這套思路真正厲害的地方在于它能隨系統(tǒng)規(guī)模長大。3個(gè)代理的小團(tuán)隊(duì)，你在控制臺(tái)打印個(gè)列表還能一眼看出結(jié)構(gòu)；但當(dāng)系統(tǒng)膨脹到14個(gè)代理、牽出40多條邊的時(shí)候，光靠腦子或者表格就抓瞎了。只有圖才能暴露出那些隱蔽的集群、卡脖子的瓶頸，還有那些誰都不聯(lián)系誰的孤島代理。問題有了形狀，解法也跟著浮現(xiàn)——我自己那套系統(tǒng)，修起來方向特別明確：把Orchestrator單一路由拆開，讓多個(gè)代理分擔(dān)調(diào)度，瓶頸自然消失。

最關(guān)鍵的是，圖不是憑空畫的，它來自那個(gè)跑可靠性測試的同一套圖分析模塊。這就意味著，你的測試分析說啥，文檔里的圖就是啥，永遠(yuǎn)不會(huì)出現(xiàn)兩張皮的情況。目前已經(jīng)兼容了CrewAI、LangGraph、AutoGen這些多智能體框架，你用自定義編排器也一樣能跑。

想試試的話，升級(jí)安裝就行：pip install swarm-test --upgrade，代碼和更多例子都放在github.com/surajkumar811/swarm-test。