AI+布局引擎：用excalidraw-architect-mcp智能生成专业架构图

1. 项目概述：用AI重构你的架构图绘制体验

作为一名在软件工程领域摸爬滚打了十多年的老兵，我深知一个清晰的架构图对于理解复杂系统、进行技术讨论和编写文档的价值。但我也同样清楚，画图这件事有多“反人类”——要么是手绘在白板上，拍完照就再也看不清；要么是用绘图工具一个个拖拽、对齐、连线，半天时间就耗进去了；再或者，用文本工具（比如Mermaid）生成，虽然快，但布局混乱、样式单一，想微调一下简直无从下手。

最近，我在尝试用AI辅助编程时，发现了一个能彻底解决这个痛点的项目：excalidraw-architect-mcp。这本质上是一个MCP（Model Context Protocol）服务器，它充当了你的AI助手（比如Cursor、Windsurf里的AI）和Excalidraw绘图工具之间的“翻译官”和“布局引擎”。简单来说，你不再需要告诉AI“在这里画一个方框，坐标是(100,200)”，你只需要告诉它“我需要一个包含API网关、用户服务和PostgreSQL的架构图”，AI负责理解你的意图并描述结构，而这个MCP服务器则负责把所有枯燥、易错的布局计算、样式应用工作全包了。

这个项目最吸引我的，是它精准地切中了“语义”与“像素”之间的鸿沟。大语言模型擅长理解关系和概念，但让它去精确计算每个图形的位置和大小，它很容易“幻觉”出重叠、错乱的布局。而这个MCP服务器，则把AI从“美工”的岗位上解放出来，让它专注于自己擅长的“架构师”角色。最终生成的.excalidraw文件，布局工整、样式专业，可以直接导入Excalidraw进行进一步的微调或分享。对于需要频繁进行系统设计、代码库梳理或技术文档编写的开发者来说，这无疑是一个生产力倍增器。

2. 核心设计思路：分离“是什么”与“在哪里”

要理解excalidraw-architect-mcp的价值，我们需要先拆解它背后的核心设计哲学。传统的AI画图流程是“端到端”的：你提出需求，AI直接生成一份包含所有坐标、尺寸信息的Excalidraw JSON。这个流程存在一个根本性缺陷：布局是硬编码的。AI并不真正理解“层次布局”、“避免交叉”、“均匀分布”这些视觉设计原则，它只是在模仿训练数据中的坐标模式，这必然导致输出不稳定。

2.1 问题拆解：为什么AI不擅长直接画图？

AI模型，尤其是基于Transformer架构的大语言模型，其强项在于序列预测和语义理解。当你让它“画一个架构图”时，它理解“API网关”、“数据库”、“微服务”这些概念，并能推断出它们之间的关系。但是，将这些关系映射到二维平面的具体坐标（x, y, width, height），是一个完全不同的优化问题。这涉及到：

1. 图布局算法：如何自动安排节点位置，使得连接线总长度最短、交叉最少、布局层次清晰？
2. 视觉样式：不同技术组件（如Kafka vs PostgreSQL）是否有约定俗成的图标或颜色表示？
3. 可编辑性：生成的图是否易于后续修改？如果我想“在数据库前加个缓存”，是局部调整还是需要推倒重来？

让AI直接输出坐标，相当于让一位建筑师既负责设计房屋结构，又亲自去砌每一块砖。结果就是“幻觉”频出：盒子重叠、连线穿盒而过、布局拥挤不堪。

2.2 解决方案：引入专用布局引擎

excalidraw-architect-mcp的聪明之处在于，它引入了一个专用的、确定性的布局引擎作为中间层。整个工作流被清晰地分为两步：

1. AI负责“语义建模”：AI将你的自然语言描述，转换成一个结构化的、与视觉无关的“关系图”。这个图只包含节点（组件）和边（连接），以及它们的类型和标签。例如：[节点: 类型=‘api_gateway’， 标签=‘Nginx’] --[边: 类型=‘http’]--> [节点: 类型=‘service’， 标签=‘User Service’]。
2. MCP服务器负责“视觉渲染”：MCP服务器接收这个关系图，调用内部的Sugiyama分层布局算法（一种经典的自动布局算法），计算出每个节点的最优位置和大小。同时，它内置了一个丰富的组件样式库，能根据节点类型（如‘kafka’， ‘postgresql’）自动应用对应的背景色、图标和边框样式。

这种“语义-视觉”分离的架构，带来了几个决定性优势：

• 布局质量稳定可靠：每次生成的图都遵循相同的布局规则，杜绝了随机重叠。
• 样式专业统一：技术栈可视化符合业界常见实践，看图一目了然。
• 支持自然语言迭代：因为MCP服务器可以读取已生成的.excalidraw文件，解析出现有结构，所以你可以在原图基础上用自然语言进行修改（“在数据库前加个Redis缓存”），服务器会重新计算布局，而不是在错误的位置上硬塞一个图形。

实操心得：这个设计模式非常值得借鉴。它本质上是一种“AI + 确定性工具”的混合智能系统。AI处理模糊、开放性的语义理解，而将那些有明确算法、需要精确计算的任务交给专用工具。我们在构建自己的AI应用时，也可以思考哪些环节可以拆解出来，用更可靠的传统代码实现。

3. 环境配置与快速上手

理论讲完了，我们来点实际的。下面是我在本地环境（macOS）从零开始配置并使用excalidraw-architect-mcp的完整过程，我会把每一步的意图和可能遇到的坑都讲清楚。

3.1 基础环境准备

首先，你需要一个支持MCP协议的AI IDE。目前最主流的选择是Cursor和Windsurf。我以Cursor为例，因为它对MCP的支持非常直接。确保你安装的是较新版本的Cursor。

其次，你需要Python环境。项目推荐使用uv（一个快速的Python包安装器和解析器），但用传统的pip也完全没问题。我两种方式都会演示。

3.2 安装MCP服务器

方法一：使用pip安装（最通用）打开你的终端，执行以下命令。这会将excalidraw-architect-mcp作为全局命令行工具安装。

pip install excalidraw-architect-mcp

安装完成后，可以通过运行excalidraw-architect-mcp --help来验证是否成功。如果看到帮助信息，说明安装正确。

方法二：使用uvx临时运行（无需安装）如果你不想污染全局环境，或者想快速尝鲜，可以使用uvx。首先确保安装了uv（curl -LsSf https://astral.sh/uv/install.sh | sh），然后：

uvx excalidraw-architect-mcp

这个命令会临时下载并运行该MCP服务器。当你关闭终端会话，它就不会留下痕迹。

注意事项：如果你的网络环境访问PyPI较慢，可以考虑配置pip的国内镜像源。对于uv，可以通过设置环境变量UV_INDEX_URL来加速。

3.3 配置Cursor IDE

这是关键一步，需要告诉Cursor，有一个新的“工具”（即MCP服务器）可供其内部的AI调用。

1. 在你的项目根目录，或者你的用户主目录下，找到或创建Cursor的MCP配置文件。路径通常是：~/.cursor/mcp.json（全局配置）或者你项目目录下的.cursor/mcp.json（项目级配置）。我推荐使用项目级配置，这样配置只对当前项目生效。
2. 编辑这个JSON文件。如果文件不存在，就新建一个。内容如下：

{ "mcpServers": { "excalidraw-architect": { "command": "excalidraw-architect-mcp", "transport": "stdio" } } }

• "excalidraw-architect"：这是你给这个服务器起的名字，可以自定义，但后续AI调用时会用到。
• "command": "excalidraw-architect-mcp"：告诉Cursor启动哪个命令。因为我们用pip全局安装了，所以直接写命令名即可。
• "transport": "stdio"：通信方式为标准输入输出，这是MCP服务器最常见的通信模式。

3. 保存文件。重要：你需要完全重启Cursor，包括关闭所有Cursor窗口，再重新打开。仅仅重启编辑器标签页是不够的，必须让Cursor主进程重新加载配置。

3.4 安装并理解“Diagram Design Skill”

项目作者提供了一个名为“Diagram Design Skill”的提示词文件。这不是必须的，但强烈推荐安装。你可以把它理解为教AI如何更好地使用excalidraw-architect-mcp这个工具的“说明书”或“最佳实践指南”。

这个Skill文件做了以下几件事：

• 设定边界：告诉AI单个架构图建议包含6-15个节点，详细流程图建议10-25个节点。避免生成过于复杂、无法阅读的巨图。
• 定义拓扑规则：建议数据流方向（如从左到右），定义常见的架构模式（如三层架构、事件驱动架构中各组件的相对位置）。
• 规范标签：指导AI如何为连线和节点编写清晰、简洁的标签。
• 映射技术栈：提醒AI可以利用MCP内建的50多种技术样式库。

安装方法（Cursor用户）： 在终端中一次性执行以下命令：

mkdir -p ~/.cursor/skills/excalidraw-diagram-design && \ curl -o ~/.cursor/skills/excalidraw-diagram-design/SKILL.md \ https://raw.githubusercontent.com/BV-Venky/excalidraw-architect-mcp/main/.skills/excalidraw-diagram-design/SKILL.md

这个命令会在你的Cursor技能目录下创建文件夹并下载Skill文件。之后，Cursor的AI在生成图表时，会自动参考这个文件中的指导原则。

我的体会：安装这个Skill后，AI生成的图表描述（即传给MCP的结构化数据）质量有明显提升。它会更自觉地控制图表规模，并使用更规范的技术名称，从而触发MCP的自动样式功能。这印证了一个好想法：对于复杂的AI工具，提供“使用指南”能极大提升最终输出效果和用户体验。

4. 核心功能实战：从指令到专业图表

配置妥当，现在让我们看看它到底能做什么。以下是我测试的几个核心场景，包含了具体的操作指令、AI的思考过程以及最终成果分析。

4.1 场景一：从零创建微服务架构图

这是最常用的场景。假设我正在设计一个简单的电商后端系统。

我的指令（在Cursor Chat中输入）：

“为我创建一个微服务架构图，包含以下组件：一个Nginx作为API网关，一个认证服务，一个用户服务，一个订单服务。数据存储使用PostgreSQL，用Redis作为缓存，服务间通过Kafka进行异步通信。另外，需要一个Prometheus和Grafana做监控。”

AI的思考与行动：

1. AI首先会识别出这是一个create_diagram工具的适用场景。
2. 接着，它会参考Diagram Design Skill，决定将组件数量控制在合理范围（本例约9个节点），并规划一个从左到右的数据流。
3. AI在脑海中（或者说在它的上下文里）构建一个结构化描述。它不会直接想坐标，而是想：“有一个‘api_gateway’类型的节点，标签是‘Nginx’。它连接到‘auth_service’和‘user_service’……”等等。
4. 最终，AI调用excalidraw-architect-mcp的create_diagram工具，传入类似下面的结构化数据（这是简化的示意）：

{ "nodes": [ {"id": "1", "type": "load_balancer", "label": "Nginx"}, {"id": "2", "type": "service", "label": "Auth Service"}, {"id": "3", "type": "service", "label": "User Service"}, {"id": "4", "type": "service", "label": "Order Service"}, {"id": "5", "type": "database", "label": "PostgreSQL"}, {"id": "6", "type": "cache", "label": "Redis"}, {"id": "7", "type": "message_queue", "label": "Kafka"}, {"id": "8", "type": "monitoring", "label": "Prometheus"}, {"id": "9", "type": "monitoring", "label": "Grafana"} ], "edges": [ {"source": "1", "target": "2", "label": "路由"}, {"source": "1", "target": "3", "label": "路由"}, {"source": "3", "target": "5", "label": "读写"}, {"source": "3", "target": "6", "label": "缓存"}, {"source": "4", "target": "7", "label": "发布订单事件"} // ... 更多连接 ] }

5. MCP服务器收到请求，启动它的布局引擎：
   • Sugiyama算法工作：首先，它会自动识别出“Nginx”是一个入口点，可能将其放在最左侧。“Auth Service”和“User Service”可能被放在同一层（垂直排列），因为它们都直接从网关接收流量。“PostgreSQL”和“Redis”可能被放在更右侧，作为数据层。监控组件（Prometheus, Grafana）可能被识别为与核心业务流关联较弱，被算法放置在底部，作为独立的“子图”。
   • 样式库应用：根据type字段，自动上色加图标。“load_balancer”类型的Nginx可能获得一个特定的绿色和负载均衡器图标，“database”类型的PostgreSQL是蓝色和数据库圆柱图标，“message_queue”类型的Kafka是橙色和流数据图标。
6. 几秒钟后，AI会在聊天中回复，告诉我图表已生成，并提供一个.excalidraw文件的下载链接或直接显示预览。我点击后，一个布局工整、颜色区分度高的专业架构图就展现在眼前。Nginx的框体会自动拉伸宽度，以清晰展示其连接多个下游服务的关系。

4.2 场景二：迭代修改现有图表

图表不是一次性的。随着设计深入，我需要修改。

我的指令：

“在刚才生成的架构图中，在PostgreSQL数据库前面添加一个Redis缓存层，用于缓存用户查询结果。”

AI的思考与行动：

1. AI需要先知道“刚才的图表”是什么。它可能会使用get_diagram_info工具（如果上下文保留了图表引用），或者直接依赖我上传的.excalidraw文件。
2. 理解我的意图是“添加一个‘缓存’类型的节点，并建立它与‘User Service’和‘PostgreSQL’的连接”。
3. 调用modify_diagram工具，传入现有图表的状态和我的修改指令。
4. MCP服务器执行修改操作。关键在这里：它不是简单地把新节点放在某个随机位置。它会：
   • 将新的Redis缓存节点插入到现有的图结构中。
   • 重新运行布局算法，根据新的拓扑结构，再次计算所有节点的最优位置。这意味着整个图表会进行一次优雅的重新排列，新加入的节点会自然地融入现有布局，所有重叠和交叉都会被重新优化。
   • 保持所有已有的样式。

最终，我得到的是一个更新后、布局依然完美的图表。这个过程模拟了真实设计讨论中，我们在白板上不断添加、移动便利贴的体验，但完全由自然语言驱动。

4.3 场景三：转换现有Mermaid图表

很多文档里已经用Mermaid写了流程图，但想要更美观、可交互的版本。

我的指令：

“帮我把下面的Mermaid流程图转换成Excalidraw图表。”
然后我粘贴一段Mermaid代码，例如：

graph TD A[客户端请求] --> B{Nginx网关} B --> C[用户服务] B --> D[订单服务] C --> E[(PostgreSQL)] D --> F[(Redis)]

AI的思考与行动：

1. AI识别出这是mermaid_to_excalidraw工具的适用场景。
2. 它解析我提供的Mermaid语法，提取出节点和边的信息。
3. 调用mermaid_to_excalidraw工具，将解析出的结构传递给MCP服务器。
4. MCP服务器进行转换。这里有一个细节：Mermaid中的[(PostgreSQL)]语法可能被映射为database类型，从而触发PostgreSQL的专属样式。而普通的[ ]方块可能被映射为默认的service类型。
5. 同样，经过布局引擎的计算，输出一个视觉效果远超原Mermaid文本的Excalidraw图表。

避坑技巧：在转换复杂的Mermaid图时，有时AI对Mermaid语法的解析可能不完美。一个更稳妥的做法是，先让AI用create_diagram工具，根据你对流程的文字描述重新生成。这样能更好地利用MCP的样式库和布局能力。

5. 深入原理：布局引擎与样式系统

要真正用好这个工具，有必要稍微深入了解下它的两大核心技术支柱：布局引擎和样式系统。这能帮助你在指令不理想时，知道如何调整。

5.1 Sugiyama分层布局算法浅析

MCP服务器使用的Sugiyama算法，是绘制有向无环图（DAG）的经典算法。它的目标就是产生“层次清晰、边交叉少、边长短”的布局。其工作流程可以简化为四步：

1. 环移除：如果图中存在循环（比如A->B, B->C, C->A），算法会暂时反转一些边的方向，将其变为无环图以便布局，最后再恢复。
2. 节点分层：算法将所有节点分配到不同的水平层（Layer）上。理想情况下，所有的边都从上一层指向下一层。它会通过一个称为“最长路径”或“网络单纯形”的方法来最小化边的跨度。
3. 同层节点排序：在每一层内部，调整节点的左右顺序，目标是减少边与边之间的交叉。这是一个NP难问题，算法会使用启发式方法（如重心法）来找到一个好的解。
4. 计算最终坐标：根据层序和同层排序，为每个节点分配具体的(x, y)坐标，并绘制边。边通常被绘制为带有“弯折点”的折线或曲线，以绕过中间的节点。

这解释了为什么生成的图总是“从左到右”或“从上到下”流向清晰，且盒子很少重叠。因为算法在底层就强制了这种层次结构。当你看到网关节点被自动拉宽，那是因为算法识别出它是一个连接了多个下层节点的“枢纽”，为了视觉清晰，将其尺寸进行了调整。

5.2 技术组件样式库

样式库是一个将技术关键词映射到视觉属性的查找表。在MCP服务器的代码中，可能有一个类似下面的Python字典：

TECH_STYLES = { “postgresql”: { “backgroundColor”: “#336791”, “icon”: “database”, “strokeColor”: “#1e4a6e” }, “kafka”: { “backgroundColor”: “#231f20”, “icon”: “message-square”, “strokeColor”: “#000000” }, “redis”: { “backgroundColor”: “#a41e11”, “icon”: “zap”, “strokeColor”: “#8a1a0f” }, “nginx”: { “backgroundColor”: “#009639”, “icon”: “layers”, “strokeColor”: “#006b2d” }, # ... 更多技术 }

当AI在节点描述中使用了“type”: “database”, “label”: “PostgreSQL”时，MCP服务器会匹配“postgresql”关键词，并应用对应的蓝色背景和数据库图标。如果标签是“MySQL”，它可能匹配到同一个“database”类型，但使用不同的颜色。

注意事项：样式匹配依赖于AI使用的标签名称。尽量使用标准的技术名称（如“Kafka”，而不是“消息队列”），以确保能触发正确的样式。你可以在Skill文件中自定义或扩展这个映射关系。

6. 高级技巧与最佳实践

经过一段时间的深度使用，我总结出一些能让excalidraw-architect-mcp发挥更大效能的技巧。

6.1 编写更有效的AI指令

模糊的指令导致模糊的结果。要让AI生成你想要的图，指令需要具体。

• 不佳指令：“画一个系统架构图。”
• 优秀指令：“创建一个三层Web应用架构图。前端是React SPA，通过CDN（CloudFront）分发。后端是一个REST API服务（用Node.js表示），连接一个PostgreSQL数据库和一个Redis缓存。后端部署在Docker容器中，由Kubernetes编排。请使用从左到右的数据流方向。”

关键要素：

1. 明确层级和边界：如“三层架构”。
2. 指定技术栈：使用具体的名称（React, PostgreSQL, Redis, Kubernetes）。
3. 指明数据流向：“从左到右”。
4. 定义范围：说明是“高层级概览”还是“详细数据流”。

6.2 管理复杂性与多图表策略

再强大的自动布局，也解决不了信息过载的问题。一个包含50个节点的图表，无论如何排列，都难以阅读。

策略：遵循Skill文件中的建议，进行分层分解。

• Level 1 - 上下文图：显示系统与外部用户、系统的交互。节点数<8。
• Level 2 - 容器图：显示系统内部的主要进程、容器、存储。节点数在6-15之间。
• Level 3 - 组件图：深入某个服务内部，显示其关键类和模块。节点数在10-25之间。

你可以这样指挥AI：

“为我们的‘订单处理系统’先创建一个容器级架构图，聚焦于微服务、数据库和消息队列。” （生成并保存后） “现在，为其中的‘支付服务’创建一个组件级详细图，展示其内部的控制器、业务逻辑层、数据访问层以及与外部支付网关的交互。”

6.3 与Excalidraw生态无缝集成

生成的.excalidraw文件是标准格式，这带来了巨大的灵活性。

1. 在VS Code中编辑：安装“Excalidraw Editor”扩展，可以直接在VS Code或Cursor中打开.excalidraw文件进行微调，比如移动一两个你觉得位置不够好的图标，或者添加一些手绘风格的注释。
2. 导入Excalidraw.com：将文件拖入 excalidraw.com 的网页，可以启动在线协作，邀请同事一起评审、修改。
3. 导出为图像：在Excalidraw中，可以轻松导出为PNG、SVG，嵌入到你的设计文档、Confluence或PPT中。
4. 版本控制：.excalidraw文件是JSON格式，可以很好地被Git管理。你可以看到架构图随着代码的演变历史。

6.4 自定义与扩展

如果你是Python开发者，这个项目是开源的，意味着你可以深度定制。

• 添加自定义样式：你可以fork项目，在样式库中添加你们公司内部特有的技术栈或组件样式。
• 调整布局参数：觉得默认的节点间距太大或太小？可以修改布局算法中的间距、层距等参数。
• 开发新工具：MCP协议是开放的。理论上，你可以让这个服务器做更多事，比如从Kubernetes清单文件自动生成部署拓扑图。

7. 常见问题与故障排查

在实际使用中，你可能会遇到一些问题。以下是我遇到和收集的一些典型情况及其解决方法。

一个典型的排查流程：

1. 从简单开始：先用一个非常简单的指令测试，如“画一个包含客户端、服务器和数据库的三节点图”，确认整个链路是通的。
2. 检查配置：如果简单指令也失败，回头检查安装和配置步骤，尤其是重启Cursor这一步。
3. 分步验证：观察AI的思考过程。它是否识别出了应该使用create_diagram工具？它构建的JSON结构是否合理？你可以要求AI“只输出你准备发送给MCP工具的结构化数据，先不要调用”，以此来检查中间产物。
4. 查阅源码与社区：项目是开源的，遇到复杂问题可以去GitHub仓库的Issue页面搜索或提问。

这个工具代表了一种高效的AI应用模式：让专业的人（或工具）做专业的事。AI负责理解和翻译你的意图，而专门的引擎负责执行精确、复杂的计算任务。它解决的远不止是“画图”这个表面问题，更深层次的是降低了系统设计思维的可视化门槛，让开发者能更流畅地将脑海中的架构转化为可协作、可迭代、可存档的视觉资产。无论是用于新人的入职引导、技术方案评审，还是单纯的个人学习笔记，它都能显著提升效率和质量。我个人的工作流已经深度整合了它，每当需要梳理思路或向他人解释一个复杂设计时，我的第一反应不再是打开绘图软件，而是对AI说：“来，帮我把这个画出来看看。”