1. 项目概述一个为Excalidraw注入AI灵魂的绘图技能如果你经常用Excalidraw画流程图、架构图或者白板草图那你一定体会过那种“想法很丰满画笔很骨感”的尴尬。脑子里明明有一个清晰的系统架构但落到画布上光是调整矩形框的大小、对齐箭头、给不同组件上色就能耗掉大半个下午。更别提反复修改时的繁琐了。这个名为coleam00/excalidraw-diagram-skill的项目就是为了解决这个痛点而生的。它本质上是一个AI技能Skill能够让你用自然语言描述直接生成或修改Excalidraw图表。简单来说它把Excalidraw从一个需要你手动操作的绘图工具变成了一个能听懂你需求的“绘图助手”。你不需要关心矩形的坐标、箭头的曲率、文本的字体大小你只需要告诉它“画一个用户登录的时序图包含前端、网关、认证服务和用户数据库四个组件”它就能在几秒钟内生成一个结构清晰、元素规范的可编辑图表。这对于产品经理快速绘制原型、工程师文档配图、讲师制作教学素材来说效率提升是颠覆性的。这个项目并非Excalidraw官方功能而是一个基于AI智能体平台如GPTs、Dify等构建的第三方技能。它通过解析你的自然语言指令理解其中的实体、关系、布局等意图然后调用Excalidraw的API或生成符合其数据结构的JSON最终在画布上渲染出图形。接下来我将为你彻底拆解这个技能的实现原理、如何部署使用以及在实际操作中如何避开那些新手容易掉的“坑”。2. 核心原理拆解语言如何变成图形要让AI理解“画一个系统架构图”并输出正确的图形背后是一套复杂的转换链条。这个技能的核心原理可以分解为三个关键环节意图理解、图形抽象与布局计算、以及Excalidraw数据生成。2.1 意图理解从自然语言到结构化指令这是第一步也是最关键的一步。AI需要从你模糊的、非结构化的描述中提取出绘图所需的精确元素和关系。这个过程通常依赖于大语言模型LLM的语义理解能力。例如当你输入“为一个电商系统画一个简化的架构图包含客户端、负载均衡器、多个Web服务器、一个Redis缓存和一个MySQL数据库。Web服务器访问缓存和数据库。”技能背后的AI模型需要识别出实体客户端、负载均衡器、Web服务器、Redis缓存、MySQL数据库。这些将成为图中的节点通常是矩形或圆形。关系“访问”是一种关系通常用箭头表示。这里存在“Web服务器 - Redis缓存”和“Web服务器 - MySQL数据库”的关系。“包含”则定义了系统的边界。属性与修饰“电商系统”可能暗示需要一些相关的图标或颜色“简化的”意味着不需要过于复杂的细节“多个”意味着Web服务器这个实体可能需要被复制或用一个带“xN”标注的框表示。图形类型暗示“架构图”这个词提示了应该使用矩形框、箭头连接布局偏向于分层或左右流向。这个技能会通过精心设计的提示词Prompt引导LLM将上述信息输出为一个结构化的中间格式例如JSON。这个JSON可能长这样{ diagram_type: architecture, elements: [ {id: 1, type: rectangle, label: 客户端, layer: frontend}, {id: 2, type: rectangle, label: 负载均衡器, layer: gateway}, {id: 3, type: rectangle, label: Web服务器, layer: backend, count: 3}, {id: 4, type: cylinder, label: Redis缓存, layer: data}, {id: 5, type: cylinder, label: MySQL数据库, layer: data} ], connections: [ {from: 1, to: 2, label: 请求}, {from: 2, to: 3, label: 分发}, {from: 3, to: 4, label: 读写缓存}, {from: 3, to: 5, label: 持久化} ] }注意这个结构化JSON的格式并非固定标准而是技能开发者为了衔接“理解”和“绘图”两个阶段而自行定义的数据契约。提示词工程的质量直接决定了AI输出的结构化程度和准确性这是该技能的核心竞争力之一。2.2 图形抽象与自动布局拿到结构化指令后下一个挑战是将其转换为视觉元素并决定它们的位置。Excalidraw虽然能画任何图形但自动生成一个“美观”、“不重叠”、“逻辑清晰”的布局是个经典的算法问题。布局策略基于图层/分层的布局这是架构图最常用的方式。如上例中的layer字段。技能内部会定义一个布局引擎将frontend层的元素放在画布上方gateway放在中间backend和data层依次向下排列。同一层内的多个元素如3个Web服务器则水平均匀分布。力导向图布局对于关系复杂的网络拓扑图或思维导图技能可能会采用简化的力导向算法。将图形元素视为带电粒子连接关系视为弹簧通过模拟粒子间的斥力和弹簧的引力迭代计算出一个相对平衡、连线交叉较少的位置。树状布局对于明显的层级结构如组织架构图采用经典的树状排列算法根节点在上或左子节点依次展开。元素视觉化type: “rectangle”会被映射为Excalidraw的矩形元素并可能根据label内容关联一个预设的图标如“数据库”可能自动添加一个圆柱体图标在旁边。layer信息可能通过给元素分配不同的背景色来视觉区分。count: 3可能会被处理为画出一个服务器图标并在其右下角添加一个“x3”的文本标签或者直接画出三个并列的矩形。这个环节通常需要开发者编写一个转换器Transformer将自定的结构化JSON转换为包含初步坐标和样式的图形对象数组。2.3 生成Excalidraw数据Excalidraw的核心是一个基于JSON的图形数据格式。最终技能需要生成一个符合Excalidraw数据规范的JSON对象这个对象包含了画布上所有元素的精确描述。一个Excalidraw图形元素的简化JSON描述如下{ type: rectangle, id: element_001, x: 100, y: 50, width: 120, height: 60, backgroundColor: #e1f5fe, strokeColor: #0277bd, roundness: { type: 3 }, // 表示圆角矩形 boundElements: [{id: arrow_001, type: arrow}], // 绑定的箭头 text: 客户端 }技能中的布局引擎计算出的(x, y)坐标以及根据元素类型、层级赋予的backgroundColor、strokeColor等样式都会被填充到这样的数据结构中。箭头元素则需要更复杂地计算起点startBinding.elementId和终点endBinding.elementId以及控制点的坐标以形成优美的曲线。最终这个包含了所有elements和appState画布状态的完整JSON对象会被返回给前端。Excalidraw应用在接收到这个数据后就能瞬间渲染出整个图表。实操心得这个流程的瓶颈往往在“意图理解”环节。用户的描述可能歧义、不完整或过于天马行空。一个健壮的技能会在Prompt中加入大量示例Few-shot Learning并设置严格的输出格式要求甚至分多步进行追问和确认以提高生成结果的准确率和可用性。3. 技能部署与使用实战了解了原理我们来看看如何真正用上这个技能。coleam00/excalidraw-diagram-skill通常以两种形式提供一种是封装好的AI智能体如GPTs开箱即用另一种是开源代码允许你自行部署和定制。3.1 开箱即用在AI平台中直接调用这是最快捷的方式。开发者可能已经将技能部署在了如Dify、Coze、GPTs商店等平台。使用步骤找到技能在对应的AI智能体平台搜索“Excalidraw diagram”或项目名。对话式生成在聊天界面直接输入你的绘图需求。例如“帮我画一个描述TCP三次握手和四次挥手的时序图。”获取结果AI会理解你的指令并在回复中直接嵌入一个Excalidraw图形。通常以一个链接或可交互的嵌入式组件形式呈现。编辑与导出点击该图形通常会跳转到Excalidraw的编辑页面可能是excalidraw.com或集成的白板你可以在此进行微调、修改然后导出为PNG、SVG或保存为.excalidraw文件。优势零配置无需技术背景体验流畅。局限功能固定无法定制提示词、布局算法或视觉风格。3.2 自行部署基于开源代码搭建如果你需要更强大的控制力或者想将其集成到自己的产品中就需要走自行部署的路线。项目仓库通常会提供详细的部署指南。典型技术栈与部署流程环境准备你需要一个能运行Node.js/Python的环境。项目根目录下会有package.json或requirements.txt。安装依赖执行npm install或pip install -r requirements.txt。配置API密钥技能需要调用LLM API如OpenAI GPT、Claude、或开源的Llama。你需要在环境变量或配置文件中设置你的OPENAI_API_KEY等。启动服务运行npm start或python app.py一个后端服务就会在本地如localhost:3000启动。连接前端服务会提供一组API端点。你可以创建一个简单的前端页面将用户输入发送到你的后端然后将返回的Excalidraw JSON数据渲染到Excalidraw组件中。更常见的是项目本身可能已经包含了一个示例前端。核心配置文件解析 在自行部署时你会接触到几个关键文件prompt_template.md这是技能的“大脑”。里面定义了如何与LLM对话包含系统指令、示例、输出格式约束。修改这个文件是定制技能行为最有效的方式。你可以增加针对你所在领域如 UML、电路图的示例让AI画得更专业。layout_engine.js或diagram_generator.py这里包含了将结构化数据转换为坐标和样式的逻辑。如果你想改变布局风格比如把所有流程图改成从左到右的直线布局就需要修改这里的算法。config.yaml可能包含模型选择gpt-4-turbovsclaude-3-sonnet、默认颜色主题、元素尺寸等参数。一个简单的集成示例 假设你有一个自己的笔记应用想集成这个功能。你可以这样做!-- 前端页面 -- textarea iduserInput画一个简单的CI/CD流水线图/textarea button onclickgenerateDiagram()生成图表/button div idexcalidraw-container/div script async function generateDiagram() { const input document.getElementById(userInput).value; const response await fetch(http://localhost:3000/generate, { method: POST, headers: {Content-Type: application/json}, body: JSON.stringify({ description: input }) }); const excalidrawData await response.json(); // 假设你已经引入了Excalidraw的UMD脚本 const excalidrawAPI window.ExcalidrawLib; const { elements, appState } excalidrawData; excalidrawAPI.updateScene({ elements, appState }); } /script注意事项自行部署时最大的成本是LLM API的调用费用。每一张生成的图都会消耗Token。你需要权衡使用高性能但昂贵的模型如GPT-4还是成本更低但可能需要更多提示词工程的模型。此外网络延迟也会影响生成速度对于实时交互体验有要求的话需要考虑优化。4. 提示词工程与高级用法要让这个技能真正成为你的得力助手而不是一个时灵时不灵的玩具掌握如何与它“有效沟通”至关重要。这本质上就是提示词工程。4.1 基础指令清晰、具体、分步差的指令“画个系统图。” 好的指令“绘制一个微服务架构图。包含API网关、用户服务、订单服务和产品服务。使用数据库图标表示MySQL云朵图标表示Redis缓存。用户请求先到达API网关然后网关可以调用任何一个下游服务。服务之间用虚线箭头表示内部通信。使用蓝色系表示网关层绿色系表示业务服务灰色系表示数据存储。”拆解好的指令的要素明确主体列出了所有需要出现的组件。指定图形明确了“数据库图标”、“云朵图标”、“虚线箭头”。定义关系清晰描述了“请求到达”、“调用”等数据流向。约束样式规定了颜色方案这能极大提升生成图表的可读性和专业性。4.2 迭代与修正像和设计师沟通一样AI生成的第一版往往不尽完美。你可以像和设计师沟通一样基于现有成果提出修改意见这比重新描述一遍高效得多。局部修改“把‘用户服务’的矩形改成圆形。”“把连接网关和用户服务的箭头加粗并标上‘HTTP/REST’。”结构调整“把这三个服务在水平方向上对齐。”“将MySQL数据库移到所有服务的正下方。”风格统一“把所有箭头的颜色改成深灰色。”“给所有服务组件加上相同的阴影效果。”高级的技能版本可能会支持“指哪打哪”的交互你可以直接引用画面中某个元素的ID进行修改。即使不支持在提示词中详细描述要修改的元素如“那个标着‘Redis’的红色云朵图标”也通常有效。4.3 领域特定提示词模板对于高频使用的场景你可以为自己创建一套提示词模板直接复制粘贴使用。UML类图模板请生成一个Excalidraw格式的UML类图。 类名User, Order, Product。 属性 - User: -id: int, -username: string, getOrders(): ListOrder - Order: -orderId: string, -total: float, getUser(): User, getProducts(): ListProduct - Product: -productId: string, -price: float 关系 - User 和 Order 是 1对多 组合关系实心菱形箭头。 - Order 和 Product 是多对多 关联关系直线。 请使用标准UML矩形框分隔线清晰方法参数可省略细节。网络拓扑模板绘制一个办公室网络拓扑图。核心是一台主交换机下连三个子交换机研发部、市场部、行政部。每个子交换机下连接若干台电脑图标。主交换机上连防火墙图标防火墙连接互联网云图标。使用不同颜色区分不同部门的连线。设备用简笔画图标表示。通过积累这样的模板你可以在几秒钟内生成专业级别的图表草稿极大提升工作效率。5. 常见问题、局限性与排查技巧即使是最优秀的AI绘图技能目前也并非万能。了解它的局限性和常见问题能帮助你更好地使用它并在出问题时快速解决。5.1 生成结果不理想从这几个方面排查下表列出了常见问题现象、可能原因及解决方案问题现象可能原因解决方案与排查技巧AI完全理解错误指令过于模糊或存在歧义。1.拆解指令将“画一个复杂的系统”拆成“先画核心服务层再画数据层最后画接入层”。2.提供参照在指令中加入“类似AWS架构图那种风格”。3.使用更强大的模型在配置中切换到GPT-4等理解能力更强的模型。图形元素缺失或错位1. 布局算法有缺陷。2. AI在结构化输出时遗漏了某些实体或关系。1.检查结构化输出如果技能提供调试模式查看AI生成的中间JSON是否完整。2.简化场景先尝试生成一个只有3-4个元素的简单图测试布局是否正常。3.手动指定在指令中明确“请确保以下五个元素全部出现A, B, C, D, E”。布局拥挤或重叠画布尺寸默认太小或元素数量过多超出布局引擎处理能力。1.在指令中指定画布“请在一个宽2000像素、高1200像素的画布上布局”。2.分模块生成先让AI生成“用户认证模块”的图再生成“订单处理模块”最后你在Excalidraw中手动拼接。样式不符合预期AI对颜色、图标等样式指令不敏感或技能内置样式库有限。1.后处理优先接受AI生成的结构和布局在Excalidraw中利用其强大的样式工具格式刷、样式库快速统一美化。2.在指令中提供色值不要说“用蓝色”要说“用颜色代码 #2E86C1”。生成速度慢1. LLM API响应慢。2. 布局计算复杂。3. 网络延迟。1.使用流式输出如果技能支持可以先看到文字描述和布局框架图形逐步渲染。2.降低模型复杂度对于简单图表换用更快的模型如GPT-3.5-Turbo。3.本地部署模型如果对延迟要求极高可考虑使用本地部署的较小LLM如Llama 3.1 8B但需牺牲一些理解能力。5.2 当前技术局限性极度复杂的图表对于元素数量极多如超过50个、关系极其复杂的图表如超大规模集群拓扑AI可能难以生成清晰的布局人类设计师的全局观和审美目前仍不可替代。高度定制化的图形如果需求涉及非常规的图形元素如自定义的图标、特殊的连线样式AI可能无法生成需要事后大量手动调整。对“美感”的把握不稳定AI对“美观”、“整洁”的理解是数据驱动的可能偶尔产生违反设计基本原则如对齐、间距、对比的布局。逻辑一致性检查AI不会检查你描述的架构是否存在逻辑矛盾如循环依赖它只是忠实地将你的描述可视化。实操心得最有效的工作流是“AI草稿 人工精修”。让AI负责最耗时、最重复的结构搭建和元素摆放生成一个80分可用的草稿。然后你作为领域专家花20%的时间进行结构调整、样式美化、细节补充和逻辑校验。这能将你的绘图效率提升数倍同时保证最终产出的质量。6. 进阶自定义与集成开发如果你不满足于使用现成技能而是希望将其深度融入自己的工作流那么进行自定义开发是必经之路。coleam00/excalidraw-diagram-skill的开源版本通常提供了良好的扩展点。6.1 扩展图形元素库技能内置的图形元素矩形、圆、箭头、基础图标可能不够用。你可以扩展它。识别元素映射文件在代码中找到一个类似element_mapping.json或shape_library.js的文件。添加自定义元素你可以将新的关键字映射到更复杂的Excalidraw元素组合。例如将关键字“kubernetes_pod”映射为一组绘制成一个豆荚形容器内部带有三个小圆点的图形元素。使用SVG或自定义库更高级的方法是让技能支持引用外部SVG图标库。当AI识别到“服务器”时不是画一个矩形而是插入一个预设的服务器SVG图标。这需要修改图形生成逻辑使其能处理image类型的Excalidraw元素。6.2 集成到其他工具真正的威力在于无缝集成。你可以将这个技能的后端API封装成插件或脚本。VS Code插件在写设计文档时选中一段描述文字右键选择“生成Excalidraw图表”自动生成并插入图片链接或代码块。ChatGPT自定义指令将核心提示词设置为你的自定义指令这样你在任何与ChatGPT的对话中只要描述图表就可以要求它以Excalidraw JSON格式输出。与文档平台结合如果你公司使用Confluence、Notion或飞书可以开发一个机器人。在文档中机器人并描述图表机器人自动回复一个可交互的Excalidraw图表链接。一个简单的CLI工具示例 你可以写一个Python脚本读取一个文本文件中的描述调用技能API并将生成的图表保存为图片。import requests import json import sys def generate_diagram(description, output_path): api_url http://localhost:3000/generate payload {description: description} response requests.post(api_url, jsonpayload) if response.status_code 200: diagram_data response.json() # 这里需要调用Excalidraw的导出API或使用无头浏览器渲染 # 伪代码render_and_save(diagram_data, output_path) print(f图表已生成并保存至 {output_path}) else: print(生成失败:, response.text) if __name__ __main__: if len(sys.argv) 1: with open(sys.argv[1], r) as f: desc f.read() generate_diagram(desc, output.png)6.3 优化提示词与模型微调对于企业级应用你可能有非常固定的图表规范如公司统一的架构图图例、颜色标准。这时你可以构建高质量示例对收集几十到上百个“自然语言描述”和“对应的完美Excalidraw JSON”配对数据。提示词工程优化用这些数据反复测试和优化你的prompt_template.md使其输出更稳定地符合你的规范。考虑模型微调如果提示词优化达到瓶颈且预算充足可以对基础LLM如GPT-3.5进行微调Fine-tuning专门训练它理解你所在领域的术语和图表规范。微调后的模型在生成特定类型图表时准确率和一致性会有质的飞跃。我个人在实际使用和定制这类技能的过程中最大的体会是它不是一个取代思考的工具而是一个加速表达的工具。它将我从繁琐的绘图操作中解放出来让我能更专注于架构设计本身。最初的几版生成结果可能需要较多调整但随着你提示词技巧的熟练和对技能“脾气”的把握你会发现自己和AI的配合越来越默契最终达到“所想即所得”的流畅状态。最后一个小技巧是建立一个你自己的“提示词库”把那些能稳定产出优秀结果的指令片段保存下来这将是属于你的最高效的绘图模板。
AI绘图技能解析：用自然语言驱动Excalidraw自动生成图表
1. 项目概述一个为Excalidraw注入AI灵魂的绘图技能如果你经常用Excalidraw画流程图、架构图或者白板草图那你一定体会过那种“想法很丰满画笔很骨感”的尴尬。脑子里明明有一个清晰的系统架构但落到画布上光是调整矩形框的大小、对齐箭头、给不同组件上色就能耗掉大半个下午。更别提反复修改时的繁琐了。这个名为coleam00/excalidraw-diagram-skill的项目就是为了解决这个痛点而生的。它本质上是一个AI技能Skill能够让你用自然语言描述直接生成或修改Excalidraw图表。简单来说它把Excalidraw从一个需要你手动操作的绘图工具变成了一个能听懂你需求的“绘图助手”。你不需要关心矩形的坐标、箭头的曲率、文本的字体大小你只需要告诉它“画一个用户登录的时序图包含前端、网关、认证服务和用户数据库四个组件”它就能在几秒钟内生成一个结构清晰、元素规范的可编辑图表。这对于产品经理快速绘制原型、工程师文档配图、讲师制作教学素材来说效率提升是颠覆性的。这个项目并非Excalidraw官方功能而是一个基于AI智能体平台如GPTs、Dify等构建的第三方技能。它通过解析你的自然语言指令理解其中的实体、关系、布局等意图然后调用Excalidraw的API或生成符合其数据结构的JSON最终在画布上渲染出图形。接下来我将为你彻底拆解这个技能的实现原理、如何部署使用以及在实际操作中如何避开那些新手容易掉的“坑”。2. 核心原理拆解语言如何变成图形要让AI理解“画一个系统架构图”并输出正确的图形背后是一套复杂的转换链条。这个技能的核心原理可以分解为三个关键环节意图理解、图形抽象与布局计算、以及Excalidraw数据生成。2.1 意图理解从自然语言到结构化指令这是第一步也是最关键的一步。AI需要从你模糊的、非结构化的描述中提取出绘图所需的精确元素和关系。这个过程通常依赖于大语言模型LLM的语义理解能力。例如当你输入“为一个电商系统画一个简化的架构图包含客户端、负载均衡器、多个Web服务器、一个Redis缓存和一个MySQL数据库。Web服务器访问缓存和数据库。”技能背后的AI模型需要识别出实体客户端、负载均衡器、Web服务器、Redis缓存、MySQL数据库。这些将成为图中的节点通常是矩形或圆形。关系“访问”是一种关系通常用箭头表示。这里存在“Web服务器 - Redis缓存”和“Web服务器 - MySQL数据库”的关系。“包含”则定义了系统的边界。属性与修饰“电商系统”可能暗示需要一些相关的图标或颜色“简化的”意味着不需要过于复杂的细节“多个”意味着Web服务器这个实体可能需要被复制或用一个带“xN”标注的框表示。图形类型暗示“架构图”这个词提示了应该使用矩形框、箭头连接布局偏向于分层或左右流向。这个技能会通过精心设计的提示词Prompt引导LLM将上述信息输出为一个结构化的中间格式例如JSON。这个JSON可能长这样{ diagram_type: architecture, elements: [ {id: 1, type: rectangle, label: 客户端, layer: frontend}, {id: 2, type: rectangle, label: 负载均衡器, layer: gateway}, {id: 3, type: rectangle, label: Web服务器, layer: backend, count: 3}, {id: 4, type: cylinder, label: Redis缓存, layer: data}, {id: 5, type: cylinder, label: MySQL数据库, layer: data} ], connections: [ {from: 1, to: 2, label: 请求}, {from: 2, to: 3, label: 分发}, {from: 3, to: 4, label: 读写缓存}, {from: 3, to: 5, label: 持久化} ] }注意这个结构化JSON的格式并非固定标准而是技能开发者为了衔接“理解”和“绘图”两个阶段而自行定义的数据契约。提示词工程的质量直接决定了AI输出的结构化程度和准确性这是该技能的核心竞争力之一。2.2 图形抽象与自动布局拿到结构化指令后下一个挑战是将其转换为视觉元素并决定它们的位置。Excalidraw虽然能画任何图形但自动生成一个“美观”、“不重叠”、“逻辑清晰”的布局是个经典的算法问题。布局策略基于图层/分层的布局这是架构图最常用的方式。如上例中的layer字段。技能内部会定义一个布局引擎将frontend层的元素放在画布上方gateway放在中间backend和data层依次向下排列。同一层内的多个元素如3个Web服务器则水平均匀分布。力导向图布局对于关系复杂的网络拓扑图或思维导图技能可能会采用简化的力导向算法。将图形元素视为带电粒子连接关系视为弹簧通过模拟粒子间的斥力和弹簧的引力迭代计算出一个相对平衡、连线交叉较少的位置。树状布局对于明显的层级结构如组织架构图采用经典的树状排列算法根节点在上或左子节点依次展开。元素视觉化type: “rectangle”会被映射为Excalidraw的矩形元素并可能根据label内容关联一个预设的图标如“数据库”可能自动添加一个圆柱体图标在旁边。layer信息可能通过给元素分配不同的背景色来视觉区分。count: 3可能会被处理为画出一个服务器图标并在其右下角添加一个“x3”的文本标签或者直接画出三个并列的矩形。这个环节通常需要开发者编写一个转换器Transformer将自定的结构化JSON转换为包含初步坐标和样式的图形对象数组。2.3 生成Excalidraw数据Excalidraw的核心是一个基于JSON的图形数据格式。最终技能需要生成一个符合Excalidraw数据规范的JSON对象这个对象包含了画布上所有元素的精确描述。一个Excalidraw图形元素的简化JSON描述如下{ type: rectangle, id: element_001, x: 100, y: 50, width: 120, height: 60, backgroundColor: #e1f5fe, strokeColor: #0277bd, roundness: { type: 3 }, // 表示圆角矩形 boundElements: [{id: arrow_001, type: arrow}], // 绑定的箭头 text: 客户端 }技能中的布局引擎计算出的(x, y)坐标以及根据元素类型、层级赋予的backgroundColor、strokeColor等样式都会被填充到这样的数据结构中。箭头元素则需要更复杂地计算起点startBinding.elementId和终点endBinding.elementId以及控制点的坐标以形成优美的曲线。最终这个包含了所有elements和appState画布状态的完整JSON对象会被返回给前端。Excalidraw应用在接收到这个数据后就能瞬间渲染出整个图表。实操心得这个流程的瓶颈往往在“意图理解”环节。用户的描述可能歧义、不完整或过于天马行空。一个健壮的技能会在Prompt中加入大量示例Few-shot Learning并设置严格的输出格式要求甚至分多步进行追问和确认以提高生成结果的准确率和可用性。3. 技能部署与使用实战了解了原理我们来看看如何真正用上这个技能。coleam00/excalidraw-diagram-skill通常以两种形式提供一种是封装好的AI智能体如GPTs开箱即用另一种是开源代码允许你自行部署和定制。3.1 开箱即用在AI平台中直接调用这是最快捷的方式。开发者可能已经将技能部署在了如Dify、Coze、GPTs商店等平台。使用步骤找到技能在对应的AI智能体平台搜索“Excalidraw diagram”或项目名。对话式生成在聊天界面直接输入你的绘图需求。例如“帮我画一个描述TCP三次握手和四次挥手的时序图。”获取结果AI会理解你的指令并在回复中直接嵌入一个Excalidraw图形。通常以一个链接或可交互的嵌入式组件形式呈现。编辑与导出点击该图形通常会跳转到Excalidraw的编辑页面可能是excalidraw.com或集成的白板你可以在此进行微调、修改然后导出为PNG、SVG或保存为.excalidraw文件。优势零配置无需技术背景体验流畅。局限功能固定无法定制提示词、布局算法或视觉风格。3.2 自行部署基于开源代码搭建如果你需要更强大的控制力或者想将其集成到自己的产品中就需要走自行部署的路线。项目仓库通常会提供详细的部署指南。典型技术栈与部署流程环境准备你需要一个能运行Node.js/Python的环境。项目根目录下会有package.json或requirements.txt。安装依赖执行npm install或pip install -r requirements.txt。配置API密钥技能需要调用LLM API如OpenAI GPT、Claude、或开源的Llama。你需要在环境变量或配置文件中设置你的OPENAI_API_KEY等。启动服务运行npm start或python app.py一个后端服务就会在本地如localhost:3000启动。连接前端服务会提供一组API端点。你可以创建一个简单的前端页面将用户输入发送到你的后端然后将返回的Excalidraw JSON数据渲染到Excalidraw组件中。更常见的是项目本身可能已经包含了一个示例前端。核心配置文件解析 在自行部署时你会接触到几个关键文件prompt_template.md这是技能的“大脑”。里面定义了如何与LLM对话包含系统指令、示例、输出格式约束。修改这个文件是定制技能行为最有效的方式。你可以增加针对你所在领域如 UML、电路图的示例让AI画得更专业。layout_engine.js或diagram_generator.py这里包含了将结构化数据转换为坐标和样式的逻辑。如果你想改变布局风格比如把所有流程图改成从左到右的直线布局就需要修改这里的算法。config.yaml可能包含模型选择gpt-4-turbovsclaude-3-sonnet、默认颜色主题、元素尺寸等参数。一个简单的集成示例 假设你有一个自己的笔记应用想集成这个功能。你可以这样做!-- 前端页面 -- textarea iduserInput画一个简单的CI/CD流水线图/textarea button onclickgenerateDiagram()生成图表/button div idexcalidraw-container/div script async function generateDiagram() { const input document.getElementById(userInput).value; const response await fetch(http://localhost:3000/generate, { method: POST, headers: {Content-Type: application/json}, body: JSON.stringify({ description: input }) }); const excalidrawData await response.json(); // 假设你已经引入了Excalidraw的UMD脚本 const excalidrawAPI window.ExcalidrawLib; const { elements, appState } excalidrawData; excalidrawAPI.updateScene({ elements, appState }); } /script注意事项自行部署时最大的成本是LLM API的调用费用。每一张生成的图都会消耗Token。你需要权衡使用高性能但昂贵的模型如GPT-4还是成本更低但可能需要更多提示词工程的模型。此外网络延迟也会影响生成速度对于实时交互体验有要求的话需要考虑优化。4. 提示词工程与高级用法要让这个技能真正成为你的得力助手而不是一个时灵时不灵的玩具掌握如何与它“有效沟通”至关重要。这本质上就是提示词工程。4.1 基础指令清晰、具体、分步差的指令“画个系统图。” 好的指令“绘制一个微服务架构图。包含API网关、用户服务、订单服务和产品服务。使用数据库图标表示MySQL云朵图标表示Redis缓存。用户请求先到达API网关然后网关可以调用任何一个下游服务。服务之间用虚线箭头表示内部通信。使用蓝色系表示网关层绿色系表示业务服务灰色系表示数据存储。”拆解好的指令的要素明确主体列出了所有需要出现的组件。指定图形明确了“数据库图标”、“云朵图标”、“虚线箭头”。定义关系清晰描述了“请求到达”、“调用”等数据流向。约束样式规定了颜色方案这能极大提升生成图表的可读性和专业性。4.2 迭代与修正像和设计师沟通一样AI生成的第一版往往不尽完美。你可以像和设计师沟通一样基于现有成果提出修改意见这比重新描述一遍高效得多。局部修改“把‘用户服务’的矩形改成圆形。”“把连接网关和用户服务的箭头加粗并标上‘HTTP/REST’。”结构调整“把这三个服务在水平方向上对齐。”“将MySQL数据库移到所有服务的正下方。”风格统一“把所有箭头的颜色改成深灰色。”“给所有服务组件加上相同的阴影效果。”高级的技能版本可能会支持“指哪打哪”的交互你可以直接引用画面中某个元素的ID进行修改。即使不支持在提示词中详细描述要修改的元素如“那个标着‘Redis’的红色云朵图标”也通常有效。4.3 领域特定提示词模板对于高频使用的场景你可以为自己创建一套提示词模板直接复制粘贴使用。UML类图模板请生成一个Excalidraw格式的UML类图。 类名User, Order, Product。 属性 - User: -id: int, -username: string, getOrders(): ListOrder - Order: -orderId: string, -total: float, getUser(): User, getProducts(): ListProduct - Product: -productId: string, -price: float 关系 - User 和 Order 是 1对多 组合关系实心菱形箭头。 - Order 和 Product 是多对多 关联关系直线。 请使用标准UML矩形框分隔线清晰方法参数可省略细节。网络拓扑模板绘制一个办公室网络拓扑图。核心是一台主交换机下连三个子交换机研发部、市场部、行政部。每个子交换机下连接若干台电脑图标。主交换机上连防火墙图标防火墙连接互联网云图标。使用不同颜色区分不同部门的连线。设备用简笔画图标表示。通过积累这样的模板你可以在几秒钟内生成专业级别的图表草稿极大提升工作效率。5. 常见问题、局限性与排查技巧即使是最优秀的AI绘图技能目前也并非万能。了解它的局限性和常见问题能帮助你更好地使用它并在出问题时快速解决。5.1 生成结果不理想从这几个方面排查下表列出了常见问题现象、可能原因及解决方案问题现象可能原因解决方案与排查技巧AI完全理解错误指令过于模糊或存在歧义。1.拆解指令将“画一个复杂的系统”拆成“先画核心服务层再画数据层最后画接入层”。2.提供参照在指令中加入“类似AWS架构图那种风格”。3.使用更强大的模型在配置中切换到GPT-4等理解能力更强的模型。图形元素缺失或错位1. 布局算法有缺陷。2. AI在结构化输出时遗漏了某些实体或关系。1.检查结构化输出如果技能提供调试模式查看AI生成的中间JSON是否完整。2.简化场景先尝试生成一个只有3-4个元素的简单图测试布局是否正常。3.手动指定在指令中明确“请确保以下五个元素全部出现A, B, C, D, E”。布局拥挤或重叠画布尺寸默认太小或元素数量过多超出布局引擎处理能力。1.在指令中指定画布“请在一个宽2000像素、高1200像素的画布上布局”。2.分模块生成先让AI生成“用户认证模块”的图再生成“订单处理模块”最后你在Excalidraw中手动拼接。样式不符合预期AI对颜色、图标等样式指令不敏感或技能内置样式库有限。1.后处理优先接受AI生成的结构和布局在Excalidraw中利用其强大的样式工具格式刷、样式库快速统一美化。2.在指令中提供色值不要说“用蓝色”要说“用颜色代码 #2E86C1”。生成速度慢1. LLM API响应慢。2. 布局计算复杂。3. 网络延迟。1.使用流式输出如果技能支持可以先看到文字描述和布局框架图形逐步渲染。2.降低模型复杂度对于简单图表换用更快的模型如GPT-3.5-Turbo。3.本地部署模型如果对延迟要求极高可考虑使用本地部署的较小LLM如Llama 3.1 8B但需牺牲一些理解能力。5.2 当前技术局限性极度复杂的图表对于元素数量极多如超过50个、关系极其复杂的图表如超大规模集群拓扑AI可能难以生成清晰的布局人类设计师的全局观和审美目前仍不可替代。高度定制化的图形如果需求涉及非常规的图形元素如自定义的图标、特殊的连线样式AI可能无法生成需要事后大量手动调整。对“美感”的把握不稳定AI对“美观”、“整洁”的理解是数据驱动的可能偶尔产生违反设计基本原则如对齐、间距、对比的布局。逻辑一致性检查AI不会检查你描述的架构是否存在逻辑矛盾如循环依赖它只是忠实地将你的描述可视化。实操心得最有效的工作流是“AI草稿 人工精修”。让AI负责最耗时、最重复的结构搭建和元素摆放生成一个80分可用的草稿。然后你作为领域专家花20%的时间进行结构调整、样式美化、细节补充和逻辑校验。这能将你的绘图效率提升数倍同时保证最终产出的质量。6. 进阶自定义与集成开发如果你不满足于使用现成技能而是希望将其深度融入自己的工作流那么进行自定义开发是必经之路。coleam00/excalidraw-diagram-skill的开源版本通常提供了良好的扩展点。6.1 扩展图形元素库技能内置的图形元素矩形、圆、箭头、基础图标可能不够用。你可以扩展它。识别元素映射文件在代码中找到一个类似element_mapping.json或shape_library.js的文件。添加自定义元素你可以将新的关键字映射到更复杂的Excalidraw元素组合。例如将关键字“kubernetes_pod”映射为一组绘制成一个豆荚形容器内部带有三个小圆点的图形元素。使用SVG或自定义库更高级的方法是让技能支持引用外部SVG图标库。当AI识别到“服务器”时不是画一个矩形而是插入一个预设的服务器SVG图标。这需要修改图形生成逻辑使其能处理image类型的Excalidraw元素。6.2 集成到其他工具真正的威力在于无缝集成。你可以将这个技能的后端API封装成插件或脚本。VS Code插件在写设计文档时选中一段描述文字右键选择“生成Excalidraw图表”自动生成并插入图片链接或代码块。ChatGPT自定义指令将核心提示词设置为你的自定义指令这样你在任何与ChatGPT的对话中只要描述图表就可以要求它以Excalidraw JSON格式输出。与文档平台结合如果你公司使用Confluence、Notion或飞书可以开发一个机器人。在文档中机器人并描述图表机器人自动回复一个可交互的Excalidraw图表链接。一个简单的CLI工具示例 你可以写一个Python脚本读取一个文本文件中的描述调用技能API并将生成的图表保存为图片。import requests import json import sys def generate_diagram(description, output_path): api_url http://localhost:3000/generate payload {description: description} response requests.post(api_url, jsonpayload) if response.status_code 200: diagram_data response.json() # 这里需要调用Excalidraw的导出API或使用无头浏览器渲染 # 伪代码render_and_save(diagram_data, output_path) print(f图表已生成并保存至 {output_path}) else: print(生成失败:, response.text) if __name__ __main__: if len(sys.argv) 1: with open(sys.argv[1], r) as f: desc f.read() generate_diagram(desc, output.png)6.3 优化提示词与模型微调对于企业级应用你可能有非常固定的图表规范如公司统一的架构图图例、颜色标准。这时你可以构建高质量示例对收集几十到上百个“自然语言描述”和“对应的完美Excalidraw JSON”配对数据。提示词工程优化用这些数据反复测试和优化你的prompt_template.md使其输出更稳定地符合你的规范。考虑模型微调如果提示词优化达到瓶颈且预算充足可以对基础LLM如GPT-3.5进行微调Fine-tuning专门训练它理解你所在领域的术语和图表规范。微调后的模型在生成特定类型图表时准确率和一致性会有质的飞跃。我个人在实际使用和定制这类技能的过程中最大的体会是它不是一个取代思考的工具而是一个加速表达的工具。它将我从繁琐的绘图操作中解放出来让我能更专注于架构设计本身。最初的几版生成结果可能需要较多调整但随着你提示词技巧的熟练和对技能“脾气”的把握你会发现自己和AI的配合越来越默契最终达到“所想即所得”的流畅状态。最后一个小技巧是建立一个你自己的“提示词库”把那些能稳定产出优秀结果的指令片段保存下来这将是属于你的最高效的绘图模板。
