用自然语言驱动Excalidraw自动生成流程图（AI集成版）

用自然语言驱动Excalidraw自动生成流程图（AI集成版）

在一次远程架构评审会议前，产品经理甩出一句话：“画个图，前端调API网关，后面接用户服务和订单服务，都连到数据库。” 传统做法是有人默默打开 Figma 或 Draw.io，花十分钟拖拽连线。而现在，只需把这句话丢给系统——三秒后，一张布局合理、元素齐全的手绘风架构图已经出现在 Excalidraw 白板上，所有人直接开始讨论逻辑，而不是“这个框该放左边还是右边”。

这不是未来场景，而是今天就能实现的工作流革新。

Excalidraw 作为开发者圈子里广受欢迎的开源白板工具，凭借其极简界面、手绘风格和出色的协作能力，早已成为技术团队画草图的首选。但真正让它从“好用”迈向“智能”的，是与大语言模型（LLM）的深度融合：让用户用自然语言描述意图，自动输出可视化的流程图或架构图。这种“说一句，出一图”的能力，正在重新定义信息表达的效率边界。

要理解这套系统的运作机制，得先看清楚它的底层骨架。Excalidraw 本质上是一个运行在浏览器中的图形建模引擎。它用 TypeScript 编写，基于 React 构建 UI，所有图形以 SVG 形式渲染。每个元素——无论是矩形、箭头还是文本块——都被抽象为带有坐标的对象，包含type、x/y、width/height、strokeColor等属性。这些数据结构清晰且开放，使得外部程序可以精准地创建和操控图形。

更重要的是，Excalidraw 提供了完整的 JavaScript API，允许动态添加元素、绑定连接线、触发重绘。这意味着只要我们能生成符合其格式的数据，就能让画布“自己长出图形”。而这正是 AI 可以发力的地方。

当用户输入一段话，比如“画一个登录流程：用户名密码输入 → 验证 → 成功跳转主页，失败提示错误”，系统需要做的不是简单关键词匹配，而是进行语义级解析。这里的关键在于大语言模型的理解与结构化输出能力。GPT-3.5、Claude 或通义千问这类模型，并非天生就知道怎么生成 Excalidraw 兼容的 JSON，它们需要被明确引导。

这就引出了整个流程中最关键的一环：提示工程（Prompt Engineering）。你不能只说“帮我画个图”，而必须告诉模型：“请输出一个 JSON 数组，每个对象代表一个图形元素，字段包括 type、x、y、width、height 和 text；如果是箭头，请指定 startBoundElementId 和 endBoundElementId。” 加上示例格式后，模型才会学会按需输出结构化结果。

来看一个实际可用的 Python 函数：

import openai import json def generate_excalidraw_elements(prompt: str) -> list: system_msg = """ 你是一个Excalidraw图形生成助手。请根据用户的描述，输出一个JSON数组， 每个对象代表一个图形元素，包含以下字段： - type: 'rectangle' | 'arrow' | 'text' - x, y: 坐标位置（初始可设为0，后续由前端布局） - width, height: 宽高 - text: 显示的文字内容（仅text和rectangle使用） - startBoundElementId, endBoundElementId: 箭头连接的元素ID（用于arrow） 示例输出： [ {"type": "rectangle", "x": 0, "y": 0, "width": 100, "height": 50, "text": "用户服务"}, {"type": "rectangle", "x": 200, "y": 0, "width": 100, "height": 50, "text": "订单服务"}, {"type": "arrow", "startBoundElementId": "id1", "endBoundElementId": "id2"} ] 注意：使用简单布局逻辑，横向排列主要组件。 """ response = openai.ChatCompletion.create( model="gpt-3.5-turbo", messages=[ {"role": "system", "content": system_msg}, {"role": "user", "content": prompt} ], temperature=0.3, max_tokens=1024 ) try: raw_output = response.choices[0].message['content'].strip() if raw_output.startswith("```json"): raw_output = raw_output[7:-3] elements = json.loads(raw_output) return elements except Exception as e: print(f"解析失败: {e}") return []

这个函数的核心价值不在调用了 OpenAI API，而在于那个精心设计的system_msg。它像一份严格的接口契约，强制模型遵循特定输出规范。实践中你会发现，哪怕少了一句“不要自由发挥”，模型也可能返回 Markdown 段落甚至散文式描述。因此，控制输出格式比提升理解能力更重要。

拿到 JSON 后，下一步是注入 Excalidraw 画布。这一步依赖前端对 Excalidraw 实例的操作能力。虽然官方没有暴露完整的ExcalidrawElement构造器文档，但在社区实践中，可以通过获取场景实例并手动构造元素来实现自动化插入。

async function insertAIGeneratedDiagram(elements) { const { app } = await import("./excalidraw-app"); const scene = app.getScene(); let offsetX = 100; const gapX = 150; // 先处理矩形和文本，建立ID映射 const idMap = new Map(); elements.forEach((elem, index) => { if (elem.type === "rectangle") { const rect = new window.ExcalidrawElement("rectangle", { x: offsetX + index * gapX, y: 200, width: elem.width || 120, height: elem.height || 60, strokeColor: "#000", backgroundColor: "#fff", roughness: 2, text: elem.text, }); scene.addElement(rect); idMap.set(elem.id || `rect-${index}`, rect.id); // 保存真实ID elem.generatedId = rect.id; } }); // 再处理箭头，确保目标已存在 elements.forEach((elem) => { if (elem.type === "arrow" && elem.startBoundElementId && elem.endBoundElementId) { const startId = idMap.get(elem.startBoundElementId); const endId = idMap.get(elem.endBoundElementId); if (startId && endId) { const arrow = new window.ExcalidrawElement("arrow", { startBinding: { elementId: startId }, endBinding: { elementId: endId }, }); scene.addElement(arrow); } } }); scene.render(); }

这段代码看似简单，实则藏着不少坑。比如必须先创建节点再画连线，否则箭头会因找不到绑定目标而失效；又比如模型返回的 ID 是虚拟的，前端需维护一张映射表将逻辑 ID 转为实际生成的 UUID。这些都是工程落地时绕不开的细节。

整个系统的架构其实很清晰：

[用户输入] ↓ (HTTP POST /api/diagram) [Natural Language Interface] → [LLM Gateway] → [Prompt Engine + Parser] ↓ (Structured JSON) [Layout Planner] → [Coordinate Assignment] ↓ (Excalidraw Elements) [Frontend Renderer (Excalidraw)] ↓ [Browser Canvas Display]

其中最值得优化的是布局规划模块（Layout Planner）。目前示例中采用的是简单的横向等距排列，适用于线性流程。但对于树状结构（如组织架构）、网状拓扑（如微服务依赖），就需要引入更智能的算法。Dagre 是一个不错的选择，它是专门用于有向图自动布局的库，能自动计算层级、排序节点、避免交叉。将其集成进后处理阶段，可以让生成的图表真正达到“开箱即用”的质量。

当然，任何 AI 系统都不能假设 100% 可靠。模型可能输出非法 JSON、遗漏关键组件、误判关系方向。因此生产环境必须加入容错机制：

• 对 JSON 解析失败的情况，尝试清洗字符串（去除代码块标记）、启用备用提示词重试；
• 对缺失坐标的问题，设置默认值填充；
• 对复杂图表，提供“修正模式”：让用户标注哪里错了，系统据此调整 prompt 并重新生成。

安全性也不容忽视。很多企业架构涉及敏感信息，若通过公共 LLM 处理，存在数据泄露风险。解决方案有两个方向：一是私有化部署轻量级模型（如微软的 Phi-3、TinyLlama），在内网完成推理；二是构建本地规则引擎，在不依赖云端模型的前提下处理常见模板类请求（如“标准三层架构”、“Kubernetes 部署图”），仅将复杂需求转发给外部模型。

说到应用场景，这项技术的价值远超“省时间”本身。在敏捷开发中，PO 讲完用户故事，一句话就能生成流程初稿，极大加速 sprint planning；在教学培训中，讲师口述即可实时生成示意图，提升课堂互动效率；在远程协作中，不同背景成员通过自然语言达成视觉共识，减少沟通歧义。

更有意思的是，“图文同源”的潜力。如果我们将每一次生成所依据的原始语句存档，并与最终图表关联，就实现了可追溯的设计过程。几年后回头看，“为什么当时这么设计？” 的答案不再是模糊回忆，而是一段清晰的对话记录。

回头审视这项技术组合的本质，它并不是某个黑科技的突破，而是多个成熟模块的巧妙拼接：Excalidraw 提供了开放的图形载体，LLM 提供了语义理解能力，前端 API 实现了自动化渲染，再加上一点扎实的提示工程和容错设计，便构成了一个极具生产力的增强工具。

未来，随着小型化模型性能提升和插件生态完善，这类“AI+可视化”方案会越来越普及。也许很快，我们不再需要专门学绘图软件，而是像使用搜索引擎一样，用语言直接操作界面。对于追求高效协作的知识工作者而言，掌握这种“说话出图”的能力，将成为一项隐形但关键的竞争优势。

毕竟，真正的效率革命，往往始于一句“帮我画个图”。