Excalidraw草图AI技能：从图形解析到自动化代码生成实战

1. 项目概述一个能“读懂”你草图的AI技能如果你经常用Excalidraw画流程图、架构图或者UI草图那你一定遇到过这样的场景画完一张图想把它整理成文档或者想基于这张图生成一些代码又或者想让它自己动起来——比如把流程图里的步骤变成可执行的脚本。这个过程通常很繁琐你需要手动复制图形元素、整理逻辑、再翻译成另一种语言。现在有一个开源项目试图用AI的力量让这个过程变得像说话一样简单。这个项目就是coleam00/excalidraw-diagram-skill。简单来说它是一个为AI助手比如Claude、GPTs或者类似的开源Agent框架开发的“技能”或“工具”。它的核心功能是让AI能够理解Excalidraw绘制的图形内容并基于图形内容执行一系列复杂的自动化任务。你可以把它想象成给AI装上了一双“读图”的眼睛和一双“执行”的手。当AI接收到一张Excalidraw的图形数据通常是JSON格式时这个技能能帮它解析出图形里有什么元素矩形、箭头、文本、这些元素之间的关系连接、包含、顺序然后根据你的指令对这些信息进行深度加工。我最初接触这个项目是因为在尝试用AI自动化一些设计到开发的流程。我们团队内部用Excalidraw做快速原型讨论非常高效但每次讨论完把定稿的草图变成Confluence文档、React组件代码或者系统部署清单又是一个耗时的体力活。这个技能的出现直接瞄准了这个痛点。它不是另一个画图工具而是一个强大的“图形处理器”将视觉化的设计语言转化为结构化的、可操作的数据和代码。对于开发者、产品经理、系统架构师乃至技术写作者来说这意味着一扇新的大门草图不再仅仅是沟通的终点它可以直接成为自动化流程的起点。2. 核心设计思路如何让AI“看懂”草图要让AI处理Excalidraw图形首要问题是我们给AI“看”的到底是什么Excalidraw保存的文件.excalidraw本质上是一个JSON对象里面包含了画布上所有元素的定义。这个技能的设计核心就是围绕解析和利用这个JSON结构展开的。2.1 理解Excalidraw的数据结构Excalidraw的JSON数据非常详细。一个典型的元素比如一个矩形会包含以下关键信息type: 元素类型如rectangle,ellipse,arrow,text。id: 元素的唯一标识符。x,y: 元素在画布上的坐标。width,height: 元素的尺寸。label或text: 元素上附着的文本内容这是理解图形语义的关键。boundElements: 一个数组列出了哪些箭头Arrow连接到了这个元素上。这是解析关系的关键。startBinding/endBinding: 对于箭头元素这两个属性指明了它连接的是哪个元素的哪个“绑定点”通常是元素的某条边。这个技能的第一步就是编写一个稳健的解析器Parser将这些原始的、扁平的JSON数据重建为一个有逻辑的“图形模型”。这个模型需要能回答诸如“这个矩形和哪个菱形有箭头相连”、“箭头上的文字描述是什么”、“这几个元素在视觉上是否构成了一个分组”等问题。注意Excalidraw的JSON结构可能会随着版本更新而微调。一个健壮的技能实现不能对数据结构做死板的假设最好能处理一些版本差异或者至少清晰地定义其支持的数据格式版本。2.2 定义技能的“能力”边界解析出图形信息只是第一步。接下来要定义这个技能具体能“做”什么。coleam00/excalidraw-diagram-skill项目通常预设或允许扩展以下几类核心能力图形转文本描述这是最基础的能力。将图形自动转换为一段结构化的文字描述。例如输入一张简单的流程图输出“这是一个用户登录流程。开始于‘用户访问登录页’矩形通过‘输入凭证’箭头指向‘验证凭证’菱形决策节点。若验证成功则指向‘跳转至主页’矩形若失败则指向‘显示错误信息’矩形并返回登录页。”图形转代码/配置这是最具实用价值的能力之一。根据图形元素和关系生成对应的代码框架或配置文件。流程图/时序图 - 伪代码/脚本将业务流程自动转换为Python、Bash或特定DSL的脚本骨架。架构图 - 基础设施即代码将绘制的云架构图包含EC2、S3、RDS等图标转换为Terraform或AWS CDK的配置代码片段。UI草图 - 前端代码将线框图转换为HTML/CSS或React/Vue组件的框架代码。虽然无法生成完美像素的UI但能快速搭建出组件结构和基本样式。图形分析与校验利用AI的逻辑能力对图形本身进行分析。例如检查流程图是否存在无法到达的节点死循环检查架构图是否符合某些安全最佳实践如数据库是否直接暴露在公网或者估算一个系统架构的粗略成本。图形交互与更新更高级的能力是让AI不仅能读还能“写”回图形。例如根据你的文字描述修改图形中的某个元素标签或者根据生成的代码反向在图形上高亮出对应的部分。项目的设计思路就是将这些能力模块化。每个能力都是一个独立的“函数”或“工具”暴露给AI助手调用。AI在接收到用户指令如“帮我把这张图转成Python代码”和图形数据后会决定调用哪个“工具”并将解析后的图形模型作为参数传入。2.3 与AI助手的集成模式这个技能本身不是一个独立运行的应用它需要被“集成”到一个AI助手中。目前主流的集成方式有两种Function Calling / Tool Use这是最主流的方式。技能将上述能力包装成符合OpenAI Function Calling、Anthropic Claude Tool Use或类似规范的“工具定义”。AI助手在对话中识别出用户意图需要用到这个技能时就会调用对应的工具函数。项目需要提供清晰的工具定义名称、描述、参数schema和具体的实现函数。Agent框架插件对于LangChain、LlamaIndex、AutoGen等AI Agent框架这个技能可以被打包成一个“Tool”或“Plugin”。框架负责调度技能负责执行。项目的架构通常会清晰地区分“核心逻辑库”和“适配器层”。核心逻辑库包含图形解析器和各个能力模块的实现与具体的AI平台无关。适配器层则负责将核心能力包装成目标AI平台如OpenAI, Claude所能识别的工具格式。3. 核心模块拆解与实现要点要构建这样一个技能我们可以将其拆解为几个核心模块每个模块都有需要注意的实现细节。3.1 图形解析与语义提取模块这是整个技能的基石。它的任务是将Excalidraw的原始JSON转化为一个富含语义的中间表示Intermediate Representation, IR。实现要点元素分类与过滤不是所有图形元素都有逻辑意义。比如装饰性的线条、背景色块可能需要被过滤掉。解析器需要能识别出哪些是“逻辑元素”如代表步骤的矩形、决策的菱形哪些是“连接元素”箭头哪些是“注释元素”便签、自由绘制。关系重建这是最复杂的部分。不能仅仅依赖boundElements因为箭头可能没有正确绑定或者图形是手动对齐的。一个更健壮的方法是结合空间关系基于绑定的关系优先使用startBinding/endBinding和boundElements这是最精确的。基于空间接近度的关系对于没有绑定的箭头计算箭头起点和终点坐标寻找最近的可能目标元素。需要设定一个合理的距离阈值。基于文本引用的关系有时箭头上的文本会写明“指向‘XX模块’”可以通过文本匹配来建立关系。分组与层级推断在架构图中我们经常将几个元素框在一起表示一个模块。解析器可以尝试通过分析元素的包围盒Bounding Box是否被另一个大的矩形或没有填充的框所包含来推断分组关系。文本信息提取与清洗元素内的文本是语义的关键。需要提取所有text和label并处理可能的换行、特殊字符。同时要注意文本元素和图形元素可能是分开的即文字是独立的一个type: “text”元素覆盖在某个图形上方这就需要通过坐标重叠检测来关联文本和图形。一个简单的解析流程伪代码示例def parse_excalidraw(json_data): elements json_data[“elements”] logical_elements [] connections [] # 第一遍过滤和分类元素 for el in elements: if el[“type”] in [“rectangle”, “ellipse”, “diamond”]: logical_elements.append({ “id”: el[“id”], “type”: el[“type”], “text”: extract_text(el), # 提取关联文本 “bounds”: (el[“x”], el[“y”], el[“width”], el[“height”]) }) elif el[“type”] “arrow”: connections.append({ “id”: el[“id”], “start”: find_connected_element(el, “startBinding”), “end”: find_connected_element(el, “endBinding”), “label”: el.get(“label”, “”) }) # 第二遍重建关系图Graph graph build_graph(logical_elements, connections) return graph3.2 技能能力实现模块基于解析好的图形模型Graph我们来实现具体的技能。3.2.1 转文本描述能力这个能力的核心是“图形遍历”和“自然语言生成”。对于流程图你可能需要实现一个深度优先或广度优先算法从“开始”节点出发沿着箭头遍历所有路径并用自然语言描述每条路径。这里可以结合简单的模板也可以调用一个小型的、本地的文本生成模型如经过微调的T5来让描述更自然。关键在于准确传达分支if/else、循环loop和并行parallel关系。3.2.2 转代码能力这是最能体现价值的模块。实现起来需要建立一套“图形元素到代码结构”的映射规则。流程图转Python伪代码矩形映射为# 步骤: [文本]注释或函数调用菱形映射为if [条件]: … else: …箭头方向表示执行流。架构图转Terraform这需要预先定义一个“图标类型到资源类型”的映射表。例如一个画成圆柱体的元素如果文本是“MySQL”则映射为aws_db_instance资源一个云朵图标映射为aws_vpc。元素的文本标签可以作为资源的name或tags箭头可以映射为安全组规则Security Group Ingress/Egress或VPC对等连接。实操心得映射规则最好是可配置的。提供一个配置文件如YAML让用户自定义“当图形元素包含‘数据库’文本且形状为圆柱时生成何种资源代码”。这极大地提升了技能的灵活性。3.2.3 分析与校验能力这个能力更依赖于外部知识或规则引擎。例如安全检查可以内嵌一些简单规则“如果某个元素的类型被识别为‘数据库’通过文本或图标且它有一条箭头直接指向一个被识别为‘互联网’的元素则报告一个安全警告。” 成本估算则可以更简单统计特定类型的资源数量乘以一个平均单价常量需要用户配置或从云厂商API获取。3.3 AI工具封装与适配模块这个模块负责让核心能力被AI助手调用。以OpenAI的Function Calling为例定义工具Tool你需要为每个能力定义一个JSON Schema描述这个工具的用途、所需的参数。{ “type”: “function”, “function”: { “name”: “generate_code_from_diagram”, “description”: “根据Excalidraw架构图生成Terraform基础设施代码。”, “parameters”: { “type”: “object”, “properties”: { “diagram_data”: { “type”: “object”, “description”: “Excalidraw导出的JSON数据” }, “target_framework”: { “type”: “string”, “enum”: [“terraform_aws”, “terraform_azure”, “python_script”], “description”: “要生成的目标代码框架” } }, “required”: [“diagram_data”, “target_framework”] } } }实现函数Function编写一个实际的函数其参数与上述Schema匹配。函数内部调用前面实现的parse_excalidraw和具体的代码生成逻辑。def generate_code_from_diagram(diagram_data: dict, target_framework: str) - str: # 1. 解析图形 graph parse_excalidraw(diagram_data) # 2. 根据target_framework选择不同的代码生成器 if target_framework “terraform_aws”: return generate_terraform_aws(graph) elif …… # 3. 返回生成的代码字符串 return generated_code集成到AI对话流在你的AI应用可能是基于LangChain、直接调用OpenAI API等中将这个工具定义和函数实现注册进去。当用户提问时AI模型会判断是否需要调用这个工具如果需要它会返回一个包含参数的调用请求你的程序执行函数并将结果返回给AI由AI组织成最终的回答给用户。4. 实战从一张草图到可部署的代码让我们通过一个完整的、假设性的例子把整个过程串起来。假设我们画了一个简单的Web应用架构图。步骤1绘制与导出在Excalidraw中我们画了以下几个元素一个云朵形状内部文字“AWS”。一个矩形文字“用户浏览器”放在云朵外。一个矩形文字“Load Balancer (ALB)”在云朵内。一个矩形文字“Web Server (EC2)”在云朵内位于ALB下方用箭头从ALB指向它。一个圆柱体文字“Database (RDS)”在云朵内位于Web Server下方用箭头从Web Server指向它箭头上写着“读写”。从“用户浏览器”到“Load Balancer”有一个箭头。画完后我们将图形导出为.excalidraw文件本质是JSON。步骤2通过AI助手调用技能我们向集成了excalidraw-diagram-skill的AI助手比如一个自定义的GPT发起对话用户“这是我画的系统架构图 [附上JSON数据]。请帮我生成在AWS上部署这个架构所需的Terraform代码。”步骤3技能执行过程AI模型识别意图AI助手分析用户消息发现提到了“架构图”和“生成Terraform代码”匹配到generate_code_from_diagram这个工具。调用工具AI助手返回一个请求要求调用该工具参数为diagram_data用户上传的JSON和target_framework: “terraform_aws”。技能后台处理解析技能解析JSON。识别出“AWS”云朵作为一个分组容器。识别出“Load Balancer”矩形根据文本关键词和常见图标知识虽然Excalidraw图标不标准但文本是关键将其分类为“ALB”资源。映射根据预定义的映射规则“Load Balancer (ALB)”-aws_lb资源。“Web Server (EC2)”-aws_instance资源。“Database (RDS)”-aws_db_instance资源。箭头“用户浏览器”-“ALB” 意味着ALB需要对公网开放因此其安全组需要添加允许HTTP/HTTPS的入口规则。箭头“Web Server”-“Database” 并带标签“读写”意味着需要生成数据库的安全组允许Web Server的安全组访问数据库的3306端口。生成技能调用Terraform代码生成器按照最佳实践如使用变量、输出值生成代码框架。它会为每个资源生成基本的HCL代码并建立它们之间的依赖关系如EC2实例的安全组引用RDS安全组的ID。返回结果生成的Terraform代码可能是一个包含main.tf,variables.tf,outputs.tf的压缩包或一段长文本被返回给AI助手。AI组织回复AI助手将代码稍作整理加上一些说明如“这是根据您的架构图生成的基础Terraform代码您需要配置AWS凭证并运行terraform apply来部署”最终呈现给用户。步骤4用户获得成果用户拿到了一份结构清晰、可直接修改和使用的Terraform代码骨架节省了大量从设计图到IaC基础设施即代码的手动翻译时间。5. 常见问题、优化方向与避坑指南在实际开发和使用的过程中你肯定会遇到各种挑战。以下是一些常见问题和我总结的优化思路。5.1 解析准确性当图形“不标准”时问题用户画的图很随意箭头没精确连接图形大小不一文字描述含糊如“服务器”而不是“Web Server”。解决方案模糊匹配与分类器不要只依赖精确的关键词匹配。可以使用一个轻量级的文本分类模型或简单的正则表达式、关键词库将“服务器”、“后端”、“App”等词都归类到“计算实例”这个逻辑类别。空间关系容忍度在基于空间接近度建立连接时设置一个动态阈值比如相对于画布尺寸的比例而不是绝对的像素值。提供“图形规范”建议在技能文档中最好能给用户一些绘图建议比如“请为关键组件使用明确的文字标签”、“尽量使用箭头工具连接图形而不是画线”这能极大提升解析成功率。5.2 生成代码的实用性与安全性问题生成的代码过于模板化缺乏具体配置实例类型、磁盘大小甚至可能生成不安全配置如数据库公网可访问。解决方案分层生成不要试图一步生成完美代码。首先生成骨架代码包含资源定义和基本的网络关系。然后在代码中插入醒目的TODO注释提示用户必须填写的关键参数如instance_type “t3.micro” # TODO: 请根据需求调整实例类型。安全第一的默认值默认生成最安全的配置。例如数据库资源默认不分配公网IP安全组默认只开放最小必要端口。在注释中解释“出于安全考虑数据库未配置公网访问如需连接请通过SSH隧道或设置VPC对等连接。”支持“配方”允许用户定义或选择“配方”Recipe。例如一个“高可用Web应用”配方会在生成ALB和EC2时自动将EC2数量设置为2并分布在不同的可用区。5.3 性能与扩展性问题图形非常复杂数百个元素时解析和生成可能变慢。解决方案异步处理对于耗时的操作如生成大量代码技能应该设计为异步模式立即返回一个任务ID让用户稍后查询结果。缓存解析结果如果同一张图被多次处理比如先要描述再要代码可以缓存解析后的图形模型IR避免重复解析JSON。模块化设计确保图形解析器、各个代码生成器都是独立的模块。这样新增对Kubernetes YAML的支持只需要新增一个生成器模块而不影响其他部分。5.4 与AI助手的协同优化问题AI助手有时会“误判”在不需要的时候调用技能或者在调用时传递了不正确的参数。解决方案精细化的工具描述在工具的description和参数description字段下足功夫。用清晰、无歧义的语言描述这个工具的精确用途和适用场景。例如不只是说“处理图形”而是说“当用户想要将Excalidraw绘制的系统架构图、流程图转换为可执行的配置代码或详细文本描述时使用此工具”。提供示例对话在集成时如果AI平台支持提供一些高质量的示例对话Few-shot Learning展示用户如何正确提问以及技能如何被调用。这能极大地提升AI模型对工具使用场景的理解。错误处理与友好提示在技能函数内部做好健壮的错误处理。当解析失败或生成出错时返回结构化的错误信息而不仅仅是抛出异常。这样AI助手可以将错误信息转化为友好的用户提示比如“我无法识别图中的数据库组件请确认您是否使用了‘数据库’标签或圆柱体图标”这个项目的魅力在于它连接了人类最自然的视觉表达工具和AI最强大的逻辑与生成能力。它不是一个替代专业绘图或专业编码的工具而是一个极其高效的“翻译官”和“加速器”。随着多模态AI模型对图像理解能力的飞速发展未来这类技能甚至可能直接解析截图或手绘照片其想象空间和应用价值会越来越大。对于开发者而言参与或利用这样的项目不仅是构建一个工具更是在塑造一种全新的、更直观的人机协作界面。