1. 项目概述一个能“读懂”你草图的AI技能最近在折腾一些AI应用开发发现一个挺有意思的项目叫coleam00/excalidraw-diagram-skill。乍一看名字你可能以为它就是个普通的Excalidraw一个开源的在线白板绘图工具插件或者集成。但深入琢磨一下这个“skill”后缀尤其是在AI Agent智能体的语境下就变得非常耐人寻味了。简单来说这个项目不是一个让你画图的工具而是一个让AI“看懂”你画的图并基于此执行任务的“技能”。想象一下你不需要学习复杂的UML语法或者流程图绘制规范只需要在Excalidraw的白板上用最直观的方式画几个框、连几条线标注几个箭头然后告诉AI“帮我把这个架构部署到云上”或者“根据这个流程图生成对应的Python代码”。这个技能就是连接你那充满创意但可能不够“规范”的草图与机器可理解、可执行的指令之间的桥梁。它解决的核心痛点非常明确降低技术沟通与任务执行的门槛。在软件开发、系统设计、流程规划中图表是沟通的基石。但绘制标准图表费时费力且不同工具如Draw.io, Lucidchart, Mermaid之间还存在格式壁垒。更关键的是这些静态图表本身没有“可操作性”。excalidraw-diagram-skill的出现意味着图表从“沟通文档”进化成了“可编程的交互界面”。它适合任何需要通过可视化方式驱动AI完成任务的人无论是想快速原型验证的产品经理还是想用草图描述需求然后自动生成代码或配置的开发者亦或是需要将复杂流程自动化落地的运维工程师。2. 核心设计思路从视觉元素到结构化指令的翻译器要理解这个技能的价值得先拆解它的核心工作原理。它本质上是一个多模态信息提取与转换管道。整个流程可以概括为图像草图 - 结构化数据 - 可执行指令。2.1 技能在AI智能体框架中的定位在诸如OpenAI的GPTs、LangChain的Agent、或是其他AI智能体框架中一个“Skill”技能或“Tool”工具是一个封装好的功能模块。智能体比如ChatGPT在理解用户自然语言指令后会判断是否需要调用某个技能来完成任务。excalidraw-diagram-skill就是这样一个专精于“理解草图”的技能。它的输入不是文本而是一个Excalidraw的图形文件通常是.excalidraw或.excalidraw.png格式。这个文件里不仅包含最终渲染出的图像更重要的是它包含了所有图形的原始矢量数据、位置、层级关系、文本标签等元信息。这比单纯从一张PNG图片去识别要精准和高效得多。2.2 核心转换逻辑解析技能的核心转换逻辑分几个层次元素识别与分类首先解析Excalidraw文件识别出基本元素矩形、圆形、菱形决策框、箭头、连接线、自由绘制笔迹、文本框等。这一步相对直接因为文件格式是结构化的。关系拓扑构建这是关键。技能需要分析箭头和连接线的起点与终点将它们关联到具体的图形元素上。例如箭头从“用户”矩形指向“登录”菱形再从“登录”菱形分出两条线分别指向“成功”矩形和“失败”矩形。通过这种分析构建出元素之间的连接关系图拓扑图。语义上下文理解结合文本框内的文字标签为图形元素赋予语义。例如识别出哪些矩形代表“组件”或“实体”哪些菱形代表“判断”哪些箭头代表“数据流”或“控制流”。这一步可能需要结合预定义的规则或轻量级的机器学习模型如对文本标签进行意图分类。结构化描述生成将上述信息综合生成一份机器可读的结构化描述。这份描述可能采用JSON、YAML或特定的领域特定语言DSL。例如对于流程图可能生成一个包含节点列表和边列表的JSON对于系统架构图可能生成一个描述组件、依赖关系和网络拓扑的配置清单。目标指令适配最后根据用户的具体请求如“生成代码”、“创建部署清单”将这个结构化描述“翻译”成目标系统能理解的指令或代码。这一步通常需要与后端的其他服务或模板引擎结合。注意这个技能本身可能不包含第5步的具体实现它更可能提供一个清晰、通用的结构化输出接口。真正的“代码生成”或“部署执行”会由调用该技能的上层AI智能体结合其他专门技能如代码生成技能、云API调用技能来完成。它的核心价值在于提供了那个关键的、高质量的“中间表示”。2.3 技术栈选型考量从项目命名和定位推断其技术栈很可能围绕以下几个方面构建Excalidraw 库集成直接使用excalidraw/excalidraw的API或数据模型来解析.excalidraw文件这是最准确的方式避免了从图像重建矢量的复杂过程。运行环境很可能是一个Node.js服务或Python服务因为这两种生态在AI应用开发中最为常见且有丰富的网络和数据处理库。AI智能体框架集成作为Skill它需要暴露标准的接口。这可能是一个遵循OpenAI Function Calling规范的函数一个符合LangChain Tool定义的类或者一个提供特定API端点的HTTP服务。输出标准化为了通用性其输出很可能采用如JSON Schema严格定义的结构确保下游技能能稳定解析。选择这样的设计优势在于精准和高效。直接解析源文件避免了计算机视觉CV识别可能带来的误差如箭头识别不准、文字OCR错误。劣势在于强耦合它深度依赖Excalidraw的数据格式如果用户用的是其他绘图工具导出的图片它就无能为力了。这体现了设计者的一种取舍为了在特定场景下达到最佳效果牺牲一部分通用性。3. 核心功能拆解与实现推演基于上述设计思路我们可以推演出这个技能应该具备的几个核心功能模块。虽然看不到源码但我们可以从“一个合格的开发者会如何实现”的角度来构建它。3.1 Excalidraw 文件解析器这是技能的基石。Excalidraw文件JSON格式包含了场景scene中的所有元素。// .excalidraw 文件结构示意简化版 { “type”: “excalidraw”, “version”: 2, “source”: “https://excalidraw.com”, “elements”: [ { “type”: “rectangle”, “id”: “element1”, “x”: 100, “y”: 50, “width”: 120, “height”: 60, “label”: { “text”: “用户”, “fontSize”: 20 } }, { “type”: “diamond”, “id”: “element2”, “x”: 300, “y”: 50, “width”: 100, “height”: 100, “label”: { “text”: “验证密码?”, “fontSize”: 16 } }, { “type”: “arrow”, “id”: “element3”, “startBinding”: { “elementId”: “element1”, “focus”: 0.5, “gap”: 10 }, “endBinding”: { “elementId”: “element2”, “focus”: 0, “gap”: 10 } } ] }解析器需要读取并验证文件格式。遍历elements数组按类型分类存储。特别处理arrow和line元素通过startBinding和endBinding属性建立起元素间的连接关系图。这里要注意处理gap间隙参数它表示箭头与元素边框的距离用于精确定位连接点。提取每个元素的文本标签label.text这是语义理解的关键。实操心得解析时元素的坐标和尺寸信息也很重要。通过计算元素的位置和连接关系可以推断出图表的大致布局从左到右的流程、自上而下的层级等这有助于后续理解图表的类型是流程图、时序图还是架构图。3.2 图表类型与语义推断引擎不是所有草图都需要被同等对待。一个方框在流程图中可能是“步骤”在架构图中可能是“服务”在实体关系图中可能是“表”。因此需要一个轻量级的推断引擎。基于规则的推断这是最直接的方式。可以定义一系列启发式规则。流程图特征存在大量菱形决策和箭头分支元素通常按线性或分支结构排列。架构图特征矩形框居多文本标签常为技术组件名如“API Gateway”、“User Service”、“Redis”箭头可能标注“调用”、“读写”、“发送”。时序图特征存在一条水平的“生命线”垂直方向表示时间流逝消息在生命线之间传递在Excalidraw中可能用带箭头的线和文本模拟。基于文本标签的推断对元素内的文本进行关键词匹配或简单的NLP分析。例如文本包含“if”、“check”、“decide”可能指向决策包含“service”、“database”、“queue”可能指向架构组件。混合推断结合图形拓扑和文本标签给出一个图表类型的置信度。例如检测到多个菱形和条件分支文本则高置信度判定为流程图。这个引擎的输出是为后续的结构化描述选择一个合适的“模板”或“模式Schema”。3.3 结构化描述生成器这是技能输出的核心。根据推断出的图表类型将解析出的元素和关系填充到一个预设的结构化模式中。以生成Mermaid流程图代码为例假设解析出一个简单的登录流程图用户 - 输入凭证 - 验证 - [是] - 主页 / [否] - 错误提示。 生成器的工作就是产出如下Mermaid代码graph TD A[用户] -- B[输入用户名密码] B -- C{验证通过?} C --|是| D[进入主页] C --|否| E[显示错误信息]它的内部逻辑是将每个非箭头的图形元素矩形、菱形映射为一个节点用其文本标签作为节点内容。将每个箭头映射为一条边。根据箭头起止点找到对应的起始节点和结束节点。如果箭头源自一个菱形决策则尝试从箭头路径上的文本标签或箭头本身的标签中提取分支条件如“是/否”、“成功/失败”作为边的标签。按照Mermaid语法组装节点和边。以生成系统组件列表为例对于架构图输出可能是一个JSON数组[ { “id”: “element1”, “type”: “service”, “name”: “API Gateway”, “dependencies”: [“element2”, “element3”] }, { “id”: “element2”, “type”: “service”, “name”: “User Service”, “dependencies”: [“element4”] }, { “id”: “element4”, “type”: “database”, “name”: “MySQL” } ]3.4 AI智能体接口适配层为了让上层AI智能体如GPT能方便地调用这个技能需要包装成标准格式。Function Calling 格式OpenAI需要定义这个技能的“函数”签名包括名称、描述、参数这里参数可能就是上传的Excalidraw文件数据或URL。# 伪代码示例 tools [ { “type”: “function”, “function”: { “name”: “parse_excalidraw_diagram”, “description”: “解析Excalidraw图表文件提取其中的图形、文本和关系并生成结构化描述。”, “parameters”: { “type”: “object”, “properties”: { “file_data”: { “type”: “string”, “description”: “Base64编码的.excalidraw文件内容或可公开访问的URL” } }, “required”: [“file_data”] } } } ]LangChain Tool 格式需要创建一个继承自BaseTool的类实现_run方法。REST API 端点提供一个HTTP POST接口接收文件返回结构化JSON。这一层的关键是提供清晰、准确的技能描述让AI能准确判断在什么场景下调用它。例如描述中应包含“当用户提及图表、流程图、架构图、设计草图并希望基于此生成代码、文档或执行操作时使用此技能。”4. 典型应用场景与实操串联理解了核心功能我们来看看它如何在实际工作流中发挥作用。这里串联几个从简单到复杂的场景。4.1 场景一草图转标准图表代码快速文档化用户诉求“我刚在白板上画了个系统架构草图帮我生成Mermaid代码我要放到Markdown文档里。”操作流程用户在Excalidraw中完成绘图。用户将.excalidraw文件或导出的.excalidraw.png需包含元数据提供给AI助手如ChatGPT。用户发出指令“请解析这个图表并生成对应的Mermaid架构图代码。”AI助手识别意图调用excalidraw-diagram-skill。技能解析文件识别出多个矩形代表服务、数据库、队列以及它们之间的箭头推断为架构图。技能生成Mermaid的graph LR左右流向或graph TD上下流向代码并返回给AI助手。AI助手将代码呈现给用户。用户一键复制粘贴到文档中。价值将非标准的草图瞬间转化为可版本管理、可嵌入文档的标准图表代码节省了重新绘制的时间保证了文档与设计草稿的一致性。4.2 场景二流程图转伪代码或测试用例用户诉求“这是我设计的业务审批流程能帮我写出大致的逻辑伪代码吗或者生成一些测试路径。”操作流程用户绘制流程图包含开始/结束节点、处理步骤矩形、判断条件菱形。用户提交文件并提问。AI调用技能解析流程图生成结构化的节点-边列表并识别出决策点和循环结构。基于这个结构AI可以结合其代码生成能力输出相应的伪代码# 伪代码示例 def approval_process(request): if not validate_request(request): return “Reject: Invalid request” if check_risk_level(request) HIGH_THRESHOLD: result senior_manager_approve(request) else: result manager_approve(request) if result “Approved”: trigger_next_phase(request) else: notify_reject(request) return result更进一步AI可以分析所有可能的路径从开始到结束的所有箭头组合为用户列出关键的测试场景例如“路径1验证失败 - 拒绝路径2高风险 - 高级经理批准 - 进入下一阶段路径3低风险 - 经理批准 - 进入下一阶段路径4... - 拒绝”。价值将视觉化的业务流程直接转化为可讨论、可评审的逻辑骨架甚至辅助测试设计加速了从设计到开发的过渡。4.3 场景三架构草图转基础设施即代码IaC这是更进阶、价值也更高的场景。用户诉求“这是我设想的新微服务架构能帮我生成一份Terraform或Kubernetes的部署清单草稿吗”操作流程用户绘制架构图。矩形代表不同的微服务如“订单服务”、“支付服务”、数据存储如“PostgreSQL”、“Redis”、中间件如“消息队列”。箭头代表网络访问关系或数据流。技能解析后不仅提取组件名还通过箭头方向推断出网络策略例如“订单服务”有箭头指向“PostgreSQL”意味着订单服务需要访问数据库。技能输出一个增强的结构化描述包含组件类型、名称、以及依赖关系。上层AI智能体或一个专门的“Terraform生成技能”接收到这个描述后结合最佳实践模板生成对应的IaC代码。每个“服务”矩形可能生成一个Kubernetes Deployment 和 Service YAML。每个“数据库”矩形可能生成一个Helm Chart引用或云数据库实例的Terraform资源。根据箭头依赖在Kubernetes中生成NetworkPolicy或在Terraform中设置安全组Security Group规则。# 示例根据“订单服务”访问“PostgreSQL”的推断生成的安全组规则片段 resource “aws_security_group_rule” “orders_to_db” { type “egress” from_port 5432 to_port 5432 protocol “tcp” security_group_id module.orders_service.security_group_id cidr_blocks [module.postgresql.db_subnet_cidr] }价值将高阶的架构设计思维与低层的运维部署代码连接起来极大地提升了基础设施定义的效率和一致性是“设计即代码”理念的延伸。实操心得在这个场景下草图的绘制需要一定的约定俗成。例如用特定的颜色或图标来表示组件类型数据库图标、服务器图标或者在文本标签中使用可识别的关键字如“svc:order”、“db:postgresql”。这需要技能的使用者或技能的配置有一些预先的约定或者技能本身具备一定的图标识别能力。最实用的方式是技能提供一种“标签映射”机制允许用户定义“矩形内文本包含‘mysql’则识别为数据库资源”。5. 开发与集成中的关键问题与解决方案在实际构建或使用此类技能时会遇到不少挑战。以下是一些预见性的问题及解决思路。5.1 问题一草图歧义性与不规范性这是最大的挑战。手绘草图是自由随意的可能存在图形不标准歪斜的矩形、不闭合的箭头。文本标签模糊缩写、笔误。逻辑关系不明确缺少箭头、箭头指向不明。解决方案预处理与规范化在解析前引入简单的图形规范化步骤。例如将接近矩形/菱形的自由绘制形状近似为标准形状对短文本进行拼写检查或同义词映射。置信度与交互式澄清技能输出应包含置信度分数。对于低置信度的识别结果如一个箭头同时指向三个目标技能可以返回一个“澄清请求”例如“检测到箭头A可能指向服务X、Y或Z请确认正确目标。”这可以通过AI智能体与用户进行多轮对话来完成。约定优于配置提倡用户遵循简单的绘图规范如“用箭头明确连接”、“在框内写明关键名称”。提供一份“最佳实践绘图指南”能极大提升识别成功率。5.2 问题二复杂图表的信息过载与焦点识别一张复杂的架构图可能包含数十个元素。当用户提出一个具体请求如“只为订单相关的服务生成配置”时技能需要能识别“焦点”。解决方案子图提取技能可以结合自然语言指令中的关键词如“订单”在解析后的元素图中进行搜索和子图提取。例如找到所有文本标签包含“订单”的节点以及这些节点直接相连的一度邻居节点构成一个子图进行后续处理。分层解析支持解析Excalidraw的图层layer或帧frame信息。如果用户将不同模块画在不同的“帧”里技能可以按帧分别处理这天然构成了模块划分。5.3 问题三与下游技能的衔接本技能产出的是“结构化描述”这个描述需要被下游技能如代码生成器、部署器理解。如何保证接口的通用性和可扩展性解决方案定义通用输出模式Schema设计一个核心的、图表类型无关的基础Schema包含nodes节点列表和edges边列表等通用字段。同时允许通过metadata或properties字段扩展图表类型特定的信息如流程图的决策逻辑、架构图的组件类型。{ “graph_type”: “architecture”, “nodes”: [ { “id”: “n1”, “label”: “API Gateway”, “type”: “gateway”, “position”: {…} } ], “edges”: [ { “source”: “n1”, “target”: “n2”, “label”: “forwards to” } ], “metadata”: { “inferred_tech_stack”: [“kubernetes”, “aws”] } }提供适配器Adapter开发一系列官方或社区的适配器将通用输出转换为特定下游工具所需的输入格式如Mermaid适配器、Terraform适配器、PlantUML适配器。开放插件体系允许开发者注册自定义的“后处理器”来消费技能输出的结构化数据完成特定领域的转换。5.4 性能与扩展性考量如果作为在线服务需要处理并发请求。解决方案无状态设计技能本身是无状态的解析和转换只依赖输入文件。这便于水平扩展。缓存解析结果对于相同的输入文件可通过哈希判断可以缓存其结构化描述避免重复计算。异步处理对于极其复杂的大型图表可以提供异步API快速返回一个任务ID后台处理完成后通过Webhook或轮询通知。6. 未来演进与生态想象excalidraw-diagram-skill的价值远不止于一个孤立的工具。它可以成为可视化编程和AI智能体协同工作的一个关键入口。1. 双向编辑与实时同步未来可以发展为“活图表”。当AI根据草图生成了部署代码后如果用户在代码中修改了某个服务的配置比如副本数这个变化能否反向同步回Excalidraw图表高亮显示被修改的组件这需要建立图表元素与生成资产之间的双向链接。2. 多模态融合技能可以与其他模态的技能结合。例如用户一边用语音描述“这里加一个缓存”AI一边在Excalidraw画布上添加一个Redis图标并同步更新结构化描述和生成的IaC代码。草图、语音、代码三者实时联动。3. 领域特定优化衍生出垂直领域的技能变体。比如excalidraw-aws-architecture-skill内置了AWS图标库和资源类型的映射规则能更精准地将草图转换为CloudFormation或AWS CDK代码。4. 成为智能体协作平台的标准输入在复杂的多智能体工作流中一个“设计智能体”负责绘制和修改草图excalidraw-diagram-skill负责解析将结构化描述传递给“开发智能体”生成代码再传递给“运维智能体”评估成本和性能。草图成为人机、机机协作的通用“蓝图”。从我个人的实践经验来看这类工具的成败关键在于在“理解用户意图”和“保持解析可靠性”之间找到平衡点。一开始不要追求理解天马行空的涂鸦而是先支持一种清晰、稍有限制但非常有用的绘图范式解决一个具体场景下的痛点比如“草图转Mermaid”。获得早期用户和反馈后再通过交互式澄清、机器学习微调等方式逐步扩大理解范围。它的核心魅力在于它承认并利用了人类最自然的表达方式——画画并将其无缝地整合到了数字化的创造流程中让思考到实现的路径变得更短、更流畅。