AI架构绘图副驾驶：用自然语言生成专业Excalidraw架构图

1. 项目概述与核心价值如果你和我一样每天都要面对陌生的、动辄几十个微服务的复杂代码库或者需要向团队解释一个新系统的设计那你一定理解那种“认知过载”的痛苦。在脑海里构建整个系统的架构图试图理清服务间的调用关系和数据流向这本身就是一项艰巨的脑力劳动。更别提当你需要把这一切画出来用视觉语言进行沟通时传统的绘图工具要么太笨重要么太简陋。这就是excalidraw-architect-mcp诞生的背景。它不是一个简单的绘图工具而是一个专为开发者设计的“AI架构绘图副驾驶”。它的核心思想非常巧妙将“画什么”架构逻辑和“怎么画”图形布局彻底解耦。你或者更准确地说你的AI助手比如Cursor或Windsurf内置的模型只需要用自然语言描述清楚系统的组件和它们之间的关系。剩下的脏活累活——计算每个框的位置、避免重叠、绘制箭头、应用符合技术栈的图标和颜色——全部交给这个MCP服务器来处理。想象一下你只需要对AI说“给我画一个包含API网关、用户服务、订单服务、PostgreSQL数据库和Redis缓存的电商系统架构图。”几秒钟后一个布局工整、样式专业、可以直接嵌入文档的Excalidraw文件就生成了。这背后是它集成了成熟的图布局算法Sugiyama算法以及一个包含50多种常见技术栈如Kafka、Kubernetes、S3等的视觉样式库。它彻底解决了LLM直接生成Excalidraw JSON时因“幻觉”坐标而导致图形重叠、连线混乱的顽疾。这个工具特别适合几类人正在接手新项目、急需理解全局的开发者正在进行系统设计、需要快速可视化方案的技术负责人以及任何厌倦了维护过期架构图、希望文档能“活”起来的工程师。它让你从繁琐的拖拽对齐中解放出来专注于真正的架构思考。2. 核心设计思路与工作原理拆解2.1 问题根源为什么LLM画不好图要理解这个工具的价值首先要明白它解决了什么根本问题。当前让大语言模型LLM直接生成可视化图表主要有两大痛点空间感知缺失LLM是序列文本处理器它没有“上下左右”的空间概念。当你让它生成一个Excalidraw的JSON时它只是在模仿它训练数据中见过的坐标模式。这导致它经常生成重叠的方框、交叉的箭头或者把所有元素堆在画布的一个角落。修复这些布局问题所花的时间可能比手动画一遍还多。样式知识匮乏一个专业的架构图不同组件应该有视觉区分。数据库通常用圆柱体消息队列用流式图标缓存用闪电符号。虽然LLM知道这些概念但让它精确地生成对应的Excalidraw图形元素包括正确的图标ID、填充色、边框样式是非常困难且容易出错的。excalidraw-architect-mcp的解决方案是“分而治之”。它定义了一个清晰的职责边界AILLM的职责理解你的需求解析代码或描述提取出结构化的拓扑信息。也就是回答“画什么”有哪些节点Node每个节点是什么类型如service,database,queue以及节点之间有哪些连接Edge连接上有什么标签。MCP引擎的职责接收这个结构化的拓扑描述利用专业的图论算法进行自动布局从内置的样式库中为每个节点类型匹配预定义的视觉样式最终渲染出符合Excalidraw格式的、美观的矢量图形文件。这种分工让AI和引擎各自做最擅长的事实现了“112”的效果。2.2 技术栈选型为什么是Excalidraw MCP Sugiyama这个项目的技术选型堪称“黄金组合”每一环都经过了深思熟虑。Excalidraw作为输出格式它是完美的选择。首先它是一个开源、手绘风格的绘图工具这种风格在技术文档中非常受欢迎显得随意而不失专业。其次它基于JSON的存储格式.excalidraw文件是结构化的便于程序生成和解析。最后它有强大的生态系统包括VS Code插件和在线编辑器生成的文件可以无缝进行二次手动编辑。MCPModel Context Protocol这是连接AI IDE和外部工具的核心桥梁。由Anthropic提出现已被Cursor、Windsurf等主流AI IDE支持。MCP允许AI安全、标准化地调用外部服务器提供的工具Tools。对于用户而言配置一次即可在IDE内通过自然语言无缝使用无需切换窗口或复制粘贴体验极其流畅。选择MCP意味着本工具能深度集成到开发者的核心工作流中。Sugiyama分层布局算法这是自动布局的灵魂。这是一种用于绘制有向无环图DAG的经典算法特别适合表现具有层次关系的架构图如请求从上到下流动。它的核心步骤是去环如果图中存在循环依赖微服务架构中常见算法会暂时移除少量边使其成为DAG。分层将所有节点分配到不同的水平层Layer尽可能让所有边的方向从上到下。排序在同一层内调整节点的左右顺序以减少边与边的交叉。坐标计算为每一层和每一层的节点计算最终的XY坐标。该MCP的实现还在此基础上做了大量优化比如根据边的标签长度自适应调整层间距、将负载均衡器这类“中心节点”拉伸以跨越其连接的服务、让连线智能地绕过中间的节点等。这些细节共同保证了输出结果既符合算法美学又具备工程实用性。2.3 样式库的设计哲学内置的50技术样式不是随意选择的。它的设计遵循了几个原则语义化映射用户说“Kafka”引擎就知道这是一个“消息队列”类型的节点并自动应用流式数据风格的图标和颜色比如一个动态的“脉冲”背景而不是一个普通的灰色方框。这大大提升了图形的可读性。类别化区分数据库、缓存、计算服务、网络设备……不同类别的组件在颜色色相、形状圆角矩形、圆柱体、服务器图标上有明显区分让人一眼就能抓住重点。可扩展性样式库是模块化和可配置的。如果你公司内部使用某个特定的自研组件你可以通过修改配置为其添加自定义的图标和样式使得生成的架构图与你的内部设计规范保持一致。3. 从零开始完整安装与配置指南3.1 环境准备与MCP服务器安装这个工具的核心是一个Python包安装非常简单。假设你的系统已经安装了Python3.8和pip。基础安装推荐直接在终端执行以下命令。这会从PyPI下载并安装最新的稳定版本。pip install excalidraw-architect-mcp安装完成后系统路径中会有一个名为excalidraw-architect-mcp的可执行命令。你可以通过excalidraw-architect-mcp --help来验证安装是否成功。使用uv运行免安装如果你不想污染全局环境或者想快速尝鲜可以使用 uv 这个快速的Python包运行器。首先确保安装了uv然后uvx excalidraw-architect-mcpuvx命令会自动从网络获取这个包并在一个隔离的环境中运行它非常适合临时使用。注意无论采用哪种方式请确保你的Python环境是正常的。如果在Windows上遇到路径问题可以尝试在PowerShell或WSL2中运行。对于团队使用建议将excalidraw-architect-mcp写入项目的开发依赖如requirements-dev.txt或pyproject.toml以便统一环境。3.2 在AI IDE中配置MCP服务器安装好MCP服务器后需要告诉你的AI IDE它的存在。这里以最流行的Cursor和Windsurf为例。Cursor 配置Cursor的MCP配置通常位于用户目录下的.cursor文件夹中。你需要创建或编辑~/.cursor/mcp.json文件在Windows上是C:\Users\你的用户名\.cursor\mcp.json。将以下配置添加到该文件中。如果文件已存在且有其他MCP服务器只需在mcpServers对象中添加一个新条目即可。{ mcpServers: { excalidraw-architect: { command: excalidraw-architect-mcp, transport: stdio } } }excalidraw-architect这是你给这个服务器起的名字可以自定义。command这里填写你安装的命令。如果你用pip全局安装直接写excalidraw-architect-mcp。如果安装在虚拟环境可能需要写绝对路径。transport: stdio表示通过标准输入输出与服务器通信这是MCP的典型方式。保存文件后必须完全重启Cursor关闭所有窗口再重新打开新的MCP配置才会生效。Windsurf / Claude Desktop 配置配置逻辑与Cursor完全一致。找到Windsurf的配置目录通常也是用户目录下的.windsurf或类似位置编辑其中的mcp.json文件添加相同的配置片段即可。Claude Desktop的配置通常在~/Library/Application Support/Claude/(macOS) 或%APPDATA%\Claude(Windows)。3.3 安装与配置“图表设计技能”关键一步这是很多用户会忽略但至关重要的一步。项目提供了一个Diagram Design Skill文件。这个文件本质上是一套给AI看的“绘图说明书”或“设计规范”。为什么需要它即使有了强大的布局引擎如果AI生成的拓扑结构本身就很糟糕比如节点太多、关系太密再好的算法也画不出清晰的图。这个Skill文件教导AI控制复杂度建议架构图节点数在6-15个详细流程图在10-25个。系统太大时应拆分成多个专题图。优化拓扑建议避免过多的交叉连接鼓励分层、模块化的结构。规范标签指导如何为边连接线编写简洁明了的标签如“调用API”、“写入数据”。应用最佳实践包含一些常见的架构模式示例帮助AI生成更合理的结构。安装方法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对于其他IDE你需要手动下载这个SKILL.md文件然后通过IDE的设置将其添加为“上下文文件”或“系统指令”的一部分。确保AI在生成图表前能读到这个文件的内容。安装并配置好技能后AI在响应你的绘图请求时会自觉遵循这些设计准则从而显著提高生成图表的质量和可读性。4. 实战演练核心使用场景与操作详解配置完成后你就可以在IDE里和AI自然对话来生成和编辑图表了。下面通过几个典型场景展示具体如何操作。4.1 场景一从零生成全新架构图这是最常用的功能。你有一个新的系统设计想法或者想可视化一个现有的项目。操作流程在Cursor或Windsurf的聊天框中用自然语言描述你的需求。描述越具体结果越好。基础版“创建一个微服务架构图包含API网关、认证服务、用户服务、订单服务、PostgreSQL数据库和Redis缓存。”进阶版“画一个电商平台的详细架构图。前端有Web和Mobile App通过CDN加速。后端有一个API Gateway将流量路由到各个微服务Product Service, Cart Service, Order Service, Payment Service。Order Service依赖MySQL数据库并且前面有一个Redis缓存。所有服务都通过Kafka进行事件通信。还有一个独立的Monitoring服务收集日志和指标数据存在Elasticsearch用Grafana展示。”AI会理解你的描述调用create_diagram工具并生成一个结构化的请求发送给MCP服务器。这个过程你通常看不到。几秒钟后AI会回复你并附上一个.excalidraw文件。在Cursor中这个文件通常会以可点击的链接或预览形式出现。点击生成的.excalidraw文件它会用VS Code的Excalidraw插件如果你已安装打开或者你可以下载后拖到 excalidraw.com 中查看和编辑。实操心得命名一致性在描述服务时尽量使用清晰、一致的名称如AuthService而不是有时叫“认证”有时叫“登录”。这有助于AI识别和复用节点。明确关系说清楚“谁连接谁”以及“为什么连接”。例如“用户服务读写用户数据到PostgreSQL数据库”比“用户服务和数据库相连”要好得多。利用技能如果你安装了Diagram Design SkillAI会自动建议将过于复杂的系统拆分成“高层架构图”和“数据流细节图”等听从这些建议往往能得到更好的结果。4.2 场景二基于现有图表进行迭代编辑这是本工具最强大的功能之一实现了“可对话的架构图”。你的架构图不是一次性的快照而是一个可以随着设计讨论不断演化的活文档。操作流程假设你已经有一个名为high-level-architecture.excalidraw的图表文件。在聊天中首先让AI“读取”或“了解”当前图表的状态。你可以说“请查看当前架构图high-level-architecture.excalidraw的内容。” AI会调用get_diagram_info工具来解析现有文件。然后基于当前状态提出修改意见。例如“在订单服务和数据库之间添加一个Redis缓存层。” 或者“把消息队列从RabbitMQ换成Kafka。” 再或者“移除监控服务它不属于这个高层视图。”AI会调用modify_diagram工具传入“添加一个类型为cache、标签为Redis的节点并建立它与OrderService和PostgreSQL的连接”这样的指令。MCP引擎会重新计算布局确保新加入的节点不会破坏整体美观并生成一个新的.excalidraw文件。你得到更新后的文件整个过程无需你手动拖动任何一个像素。注意事项文件路径确保AI能访问到你提到的.excalidraw文件。通常需要把文件放在当前项目目录下或者在聊天中通过附件上传。状态一致性复杂的多次修改最好基于同一个文件版本顺序进行。如果中间你手动编辑了文件可能需要重新让AI读取最新状态。自然语言描述修改指令可以非常自然。“把数据库复制一份做成读写分离的主从结构”这样的复杂操作AI也能很好地理解并尝试实现。4.3 场景三将现有Mermaid图表转换为Excalidraw很多团队已经用Mermaid语法在Markdown中维护了一些图表。这个工具可以帮你将它们升级为更美观、可交互的Excalidraw格式。操作流程在聊天框中直接粘贴你的Mermaid代码块并给出指令。例如请将下面的Mermaid流程图转换为Excalidraw图表。 mermaid graph TD A[客户端] -- B(负载均衡器) B -- C[Web服务器] B -- D[Web服务器] C -- E[应用服务] D -- E E -- F[(数据库)]AI会调用mermaid_to_excalidraw工具将Mermaid语法解析成内部的节点和边结构然后交由布局引擎渲染。转换完成后你会获得一个布局优化、样式美化后的Excalidraw文件。相比原始的Mermaid渲染Excalidraw版本支持手动微调视觉表现力也更强。踩坑提醒语法支持目前该工具主要支持Mermaid的graph流程图/关系图类型。对于时序图、类图等复杂类型支持可能有限或效果不佳。样式映射Mermaid中的[ ]、( )、{ }等形状会被映射到Excalidraw中对应的样式但可能不如直接使用本工具内置的技术栈标签那么精确和美观。5. 高级技巧与最佳实践5.1 如何描述以获得最佳图表与AI协作绘图是一门“提示工程”的小学问。经过大量实践我总结出几个能极大提升出图质量的描述技巧分层描述法不要一次性抛出所有组件。先描述核心层。第一层接入层 “系统最前方是CloudFlare CDN和Nginx负载均衡器。”第二层应用层 “负载均衡器后面是三个无状态的API服务实例运行在Docker容器中。”第三层数据层 “服务访问一个主从复制的PostgreSQL集群并有一个Redis缓存用于会话存储。”这种描述方式天然地形成了清晰的层次AI更容易构建出结构良好的拓扑。显式定义节点类型在描述中直接使用工具能识别的“关键词”。好的描述“使用Kafka作为事件总线”“数据存储在Amazon S3”“用Prometheus和Grafana做监控。”这些加粗的关键词能精准触发内置的样式库让生成的图形元素自带专业图标和配色。明确边的方向和含义连接关系是图的灵魂。模糊“服务和数据库有连接。”清晰“用户服务向PostgreSQL数据库写入用户资料数据。” “订单服务通过同步HTTP调用支付服务。” “所有服务将日志事件发布到Kafka主题。”5.2 管理复杂系统分而治之的策略再强大的自动布局也无法在一张图上清晰展示一个包含50个微服务的系统。这时必须采用“分而治之”的策略。层级分离L1 上下文图只画系统与外部用户、系统的交互不涉及内部组件。适合给非技术人员或高层看。L2 容器图/组件图展示系统内部的主要进程、容器、数据库等。这就是excalidraw-architect-mcp最擅长的领域聚焦于6-15个核心组件。L3 代码级图针对某个具体服务绘制其内部的模块或类关系。这个工具也能通过分析代码来生成但需要更具体的指令。关注点分离架构概览图包含所有核心服务、数据和主要的通信方式。数据流图专门描述一个特定业务请求如“用户下单”流经哪些服务如何改变数据状态。部署图关注服务是如何部署在Kubernetes、ECS等平台上的包含Namespace、Pod、Node等概念。 为每个关注点创建单独的图表文件并用清晰的命名管理它们如deployment-view.excalidraw,>问题现象可能原因解决方案运行excalidraw-architect-mcp命令提示“未找到”1. Pip安装后可执行文件路径未添加到系统PATH。2. 在虚拟环境中安装但未激活。1. 尝试使用完整路径如python -m excalidraw_architect_mcp.server。2. 激活你的虚拟环境或用uvx excalidraw-architect-mcp运行。Cursor/Windsurf重启后仍提示“工具不可用”1. MCP配置文件mcp.json格式错误。2. 配置文件路径不正确。3. MCP服务器命令启动失败。1. 使用JSON验证工具检查mcp.json语法。2. 确认配置文件在正确的用户目录下的.cursor或.windsurf文件夹内。3. 在终端手动运行excalidraw-architect-mcp看是否有Python依赖错误。可能需要安装pygraphviz的系统依赖如Graphviz。AI无法调用绘图工具1. MCP配置未生效。2. AI的对话上下文未包含相关技能或指令。1. 完全关闭IDE再重新打开。2. 在对话中明确要求AI使用“excalidraw architect”工具或确保Diagram Design Skill已正确加载。6.2 图表生成与布局问题问题现象可能原因解决方案生成的图形元素重叠1. 节点数量过多超过25个。2. AI生成的拓扑结构存在大量循环或全连接。1.遵循最佳实践将大图拆分为多个小图。2. 在指令中要求AI“生成一个分层清晰的架构图”或“避免节点间交叉连接”。3. 手动编辑Excalidraw文件进行微调这是Excalidraw的优势。技术图标显示为默认方框1. 描述中使用的技术名称不在内置样式库中。2. 描述不够精确如说“数据库”而不是“PostgreSQL”。1. 使用已知的技术关键词参考项目文档的组件库列表。2. 对于自定义组件生成后可以在Excalidraw编辑器中手动替换图标。未来可考虑向项目贡献新的样式映射。连线杂乱绕远路这是图布局算法的固有挑战尤其是对于非分层或带环的复杂网络。1. 尝试在指令中强调核心数据流方向帮助AI构建更有方向性的拓扑。2. 对于复杂的网状结构考虑使用“力导向”布局当前工具未使用或接受一定杂乱度在Excalidraw中手动优化关键连线。修改现有图时布局大变添加/删除节点后Sugiyama算法为了全局最优会重新计算所有节点位置。这是自动布局的特点。如果希望保留大部分原有布局只能在修改后于Excalidraw编辑器中进行手动位置调整。6.3 性能与扩展性考量响应速度对于包含15-20个节点的典型架构图生成时间通常在2-5秒。如果遇到非常复杂的图节点30计算时间可能会增加到10秒以上。这是因为布局算法的时间复杂度随着节点和边数量的增加而上升。内存占用作为一个本地运行的Python MCP服务器其内存占用很小通常不会超过100MB。主要开销在于加载布局计算库和渲染图形。离线运行这是该工具的一大优势。所有计算都在本地完成不依赖任何外部API因此没有网络延迟也无需担心数据隐私问题。你的架构图数据永远不会离开你的机器。扩展自定义样式如果你需要为公司内部技术栈添加自定义样式可以查阅项目的CONTRIBUTING.md文件。通常需要修改源代码中的样式映射字典并重新打包安装。对于团队使用建议维护一个内部 fork 版本。这个工具从根本上改变了我们创建和维护技术架构图的方式。它把我们从枯燥的拖拽对齐中解放出来让我们能专注于架构设计本身。通过自然语言与AI协作图表变成了一个可以随时讨论、迭代的活文档而不是一个一旦创建就开始过时的静态图片。虽然它在处理极端复杂的网状结构时仍有局限但对于日常开发中80%的架构可视化需求来说它已经是一个效率提升巨大的利器。我个人最欣赏的一点是它生成的图是“可编辑的起点”你总能在自动生成的基础上进行手动微调达到完美的效果。