文档这东西，就是你画好一张多智能体架构图，然后半年不管，等再翻出来时发现早就对不上了——系统悄悄改了、新加的代理没画、老逻辑也变了，而没人费劲去更新图片。swarm-test v0.3.3想解决的就是这个痛点：它从你实际运行的代理拓扑直接生成图表，文档永远和系统保持同步。我拿自己那套14代理系统跑了一下，问题像被放大镜照亮一样跳出来。
一眼过去，图里那颗红得扎眼的节点是OrchestratorAgent。它被标为单点故障，爆炸半径高达92%。什么叫爆炸半径？就是如果这个节点挂了，92%的其他代理会跟着遭殃。再看整体形状，几乎全部14个代理的箭头都汇向两个枢纽：一个叫OrchestratorAgent，另一个叫TrainerAgent。这两个家伙，任何一个倒下，整套系统就瘫了。这种结构性问题，你在控制台打出来的表格里根本看不到，可换成这张图，瞬间就懂了。
出图只需一条命令：swarm-test graph my_crew.py --format mermaid。跑完后你会得到一段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都能原生渲染，你提交之后自然就在文档中展现，该红的红、该绿的绿，还有中等风险的黄色，每一种颜色都对应着可靠性分析里那套风险分类。
看你准备把图用在哪儿，工具提供了三种输出格式。Mermaid最适合README和Wiki，因为它是纯文本，内联渲染、可版本控制，在PR里做diff时清楚明了，一行改动都藏不住。DOT格式给Graphviz流水线或者你自己搭的工具链留着。需要做PPT或者塞进外部分享文档，就直接指定PNG：swarm-test graph my_crew.py --format png --output topology.png。唯一要注意的是PNG依赖matplotlib，得先装好swarm-test[png]这个扩展。
这套思路真正厉害的地方在于它能随系统规模长大。3个代理的小团队，你在控制台打印个列表还能一眼看出结构；但当系统膨胀到14个代理、牵出40多条边的时候，光靠脑子或者表格就抓瞎了。只有图才能暴露出那些隐蔽的集群、卡脖子的瓶颈，还有那些谁都不联系谁的孤岛代理。问题有了形状，解法也跟着浮现——我自己那套系统，修起来方向特别明确：把Orchestrator单一路由拆开，让多个代理分担调度，瓶颈自然消失。
最关键的是，图不是凭空画的，它来自那个跑可靠性测试的同一套图分析模块。这就意味着，你的测试分析说啥，文档里的图就是啥，永远不会出现两张皮的情况。目前已经兼容了CrewAI、LangGraph、AutoGen这些多智能体框架，你用自定义编排器也一样能跑。
想试试的话，升级安装就行：pip install swarm-test --upgrade，代码和更多例子都放在github.com/surajkumar811/swarm-test。
热门跟贴