1. 项目概述与核心价值最近在折腾AI编程助手发现一个挺有意思的痛点让AI画技术架构图。你肯定也遇到过让Claude Code或者Cursor这类工具画个系统流程图它要么给你整一堆规规矩矩的方框加箭头要么生成的Excalidraw JSON文件打开一看布局乱得没法看。这问题本质上是AI缺乏“视觉论证”的能力——它知道要表达什么概念但不知道如何用图形元素的空间关系、视觉权重、颜色编码来强化这个概念的传达。coleam00的这个excalidraw-diagram-skill项目就是专门解决这个问题的。它不是简单地把自然语言描述转成Excalidraw的JSON而是内置了一套完整的视觉设计方法论。简单说它让AI生成的图不再是“元素的堆砌”而是“观点的可视化”。比如你要画一个“事件从AI代理流向前端UI”的图这个技能会确保“流”这个概念用箭头序列、颜色渐变、元素间距等一系列视觉线索清晰地表达出来而不是给你画几个方框标上字就完事。这个技能包的核心用户就是那些日常需要和AI结对编程、快速生成技术文档、设计评审材料的开发者。如果你用过Claude Code、OpenCode或者任何支持.claude/skills/目录的AI编码代理把它丢进去就能直接用。它的价值在于你不再需要反复给AI提修改意见“这个箭头不对”、“这两个组件靠太近了”、“颜色区分不明显”。这个技能让AI具备了自我视觉校验的能力它能自己生成图、自己渲染预览、自己发现布局问题比如文字重叠、箭头指向模糊、布局不平衡然后迭代修正最后交给你一个几乎可以直接用的成品。2. 核心设计思路从“画图”到“论证”2.1 视觉隐喻与概念映射普通AI画图工具的思路是“翻译”把“数据库”这个词翻译成一个矩形框把“调用”翻译成一个箭头。这个技能的思路是“映射”它建立了一套从抽象概念到视觉特征的映射规则库。举个例子“一对多关系”这个概念常见的画法可能就是一个框引出几个箭头指向另外几个框。但这个技能会采用“扇形发散”Fan-out的视觉隐喻。主导元素那个“一”会被放在视觉中心或左侧起点从它引出的多个箭头会以一定的弧度均匀散开指向各个子元素那些“多”。子元素之间的间距会被自动计算确保视觉上的均衡感。箭头可能采用渐细或颜色渐变的样式来暗示数据流或控制流的分发。这种画法一眼就能让人看出“这是一个源头分散到多个终点”而不需要阅读任何文字标签。再比如“时间序列”或“工作流”。它不会画成一条直线上的几个等距方框而可能会采用时间轴Timeline的隐喻用一条有方向性的基线关键节点作为线上的标记并用不同的形状或颜色来区分不同阶段如“输入”、“处理”、“输出”。甚至可以用元素的垂直偏移来表示并行分支。这种映射关系被固化在技能的知识库SKILL.md和element-templates.md里。当AI接到“画一个用户登录流程”的指令时它会先拆解出核心概念“用户”起点、“前端”输入界面、“API网关”入口、“认证服务”处理核心、“数据库”存储、“成功/失败”分支结果。然后它会为每个概念匹配合适的视觉模板并按照“流程”这一总概念自动选择“从左到右的阶段性布局”并为“分支”设计一个清晰的决策菱形和分叉路径。2.2 证据构件集成这是另一个让我觉得非常实用的设计。很多技术架构图是“纸上谈兵”框图上写着“发送API请求”但具体请求体长什么样响应码是什么图上没有。这个技能鼓励或者说强制AI在图中集成“证据构件”Evidence Artifacts。比如在描述“服务A调用服务B的REST接口”的箭头旁边可以附带一个便签形状的容器里面直接贴上一段真实的cURL命令示例或简化的JSON请求体。在描述“数据库Schema”的方框内可以嵌入一个代码片段展示关键的字段定义。对于消息队列可以展示一个真实的Kafka消息格式样例。这样做的好处是巨大的。首先图的可信度和实用性直线上升它不仅仅是设计稿更是部分实现的参考。其次它迫使AI在生成图时进行更深入的思考要展示这个交互最有代表性的数据样本是什么这反过来会让生成的架构设计更加具体和可落地。最后对于看图的人来说他们能立刻理解接口契约和数据格式减少了再去翻看其他文档的成本。这个功能的实现依赖于技能对Excalidraw元素类型的扩展理解。它不只是会用矩形、圆形、箭头还会熟练使用“代码块”、“便签”、“手绘框”等元素类型并将它们作为概念的证据附属物进行布局。2.3 基于Playwright的视觉验证循环这是整个技能最“自动化”的一环也是确保输出质量的关键。传统的AI生成图是“一锤子买卖”AI输出JSON用户打开Excalidraw查看不满意再回去让AI改。这个过程效率很低。这个技能引入了一个本地渲染管道。它的工作流程是这样的AI生成初版Excalidraw JSON基于指令和设计规则。调用本地渲染脚本技能内部调用一个用Playwright封装的Python脚本render_excalidraw.py。无头浏览器渲染脚本启动一个无头Chromium浏览器将JSON数据加载到一个特制的HTML模板render_template.html中这个模板模拟了Excalidraw的核心渲染逻辑将图画出来。截图与视觉分析脚本对渲染出的画面进行截图并且可以进行简单的视觉分析目前主要是通过截图供AI“查看”未来潜力巨大。AI自我审查AI即调用本技能的编码代理会“看到”这张截图。它能识别出明显的视觉问题例如两个图形的文字标签重叠了箭头指到了图形的空白处而不是边界整个图偏在了画布的一侧颜色对比度太低导致看不清。迭代优化AI根据发现的问题调整JSON中的元素位置、大小、样式然后回到第2步开始新一轮渲染和检查。这个循环会进行多次直到AI认为布局达到了一个“视觉上平衡、清晰”的状态或者达到迭代次数上限。这个“生成-渲染-审查-优化”的闭环模拟了一个设计师的工作流程。它把原本需要人工反馈的环节自动化了使得AI能交付显著更高质量的图表。设置这个渲染器只需要简单的依赖安装Playwright是一次性的成本却换来了每次生成质量的巨大提升。2.4 品牌化与可定制性很多团队对图表有统一的视觉规范比如使用企业品牌色。这个技能把视觉样式抽象到了一个中心文件——references/color-palette.md。这个文件定义了一套颜色方案指明哪种概念用哪种颜色。例如--color-primary: #007ACC 用于核心主体、关键服务--color-secondary: #2E8540 用于辅助服务、数据库--color-accent: #D14836 用于错误、警告、关键节点--color-background: #F5F5F5 画布背景--color-text: #333333 主要文字--color-border: #CCCCCC 边框颜色当AI需要为一个“数据库”元素上色时它会查阅这个调色板找到--color-secondary对应的色值。如果你想将整个技能输出的图表风格换成你们公司的蓝金配色只需要修改这个color-palette.md文件将所有图表的颜色风格就会整体切换。这种设计保证了灵活性和一致性技能的核心布局逻辑和元素映射规则是完全通用的与颜色解耦。3. 技能安装与配置详解3.1 环境准备与技能部署这个技能的目标环境是支持“技能”功能的AI编码代理。目前最主流的就是Anthropic官方推荐的Claude Code工作流以及开源项目OpenCode。它们都约定将技能放置在项目根目录下的.claude/skills/文件夹中AI代理会自动发现并加载它们。第一步获取技能包你有两种方式。一是直接克隆Git仓库这是最方便获取更新后续更新的方式。# 在你的项目根目录下操作 git clone https://github.com/coleam00/excalidraw-diagram-skill.git或者你也可以直接在GitHub仓库页面下载ZIP包并解压。第二步部署到技能目录关键一步是将技能包放到正确的路径下并确保目录名称清晰。我建议使用excalidraw-diagram这样明确的名字避免歧义。# 确保你的项目根目录下有 .claude/skills/ 文件夹没有则创建 mkdir -p .claude/skills # 将克隆或解压的文件夹复制进去 cp -r excalidraw-diagram-skill .claude/skills/excalidraw-diagram完成以上操作后你的项目结构应该看起来像这样your-project/ ├── .claude/ │ └── skills/ │ └── excalidraw-diagram/ # 技能本体 │ ├── SKILL.md │ └── references/ ├── src/ └── ... (你的其他项目文件)注意.claude/目录通常是隐藏的。在终端中操作时注意前面的点号。有些AI代理可能支持其他路径但.claude/skills/是兼容性最广的约定。3.2 渲染管道设置核心步骤技能本身是纯文本的指导但“视觉验证”功能需要本地运行一个微服务来渲染图表。这就是references/目录下那些Python脚本的作用。设置它有两种方式我强烈推荐方式A。方式A让AI代理帮你设置最省心这是技能设计初衷。你只需要对你的AI编码代理如Claude Code说一句“请按照.claude/skills/excalidraw-diagram/SKILL.md文件中的说明帮我设置好Excalidraw图表技能的渲染器。”AI代理会读取SKILL.md里的指令自动执行所需的命令。它会定位到references/目录。检查并使用uv一个快速的Python包管理器和解析器来安装依赖主要是Playwright。运行playwright install chromium来下载无头浏览器。 整个过程完全自动化你只需要确认即可。方式B手动设置用于调试或理解背后原理如果你想自己控制或者AI代理执行失败时需要排查可以手动操作。# 1. 进入技能目录的references文件夹 cd .claude/skills/excalidraw-diagram/references # 2. 使用uv同步Python虚拟环境并安装依赖 # 确保你系统已安装uv (pipx install uv 或 curl -LsSf https://astral.sh/uv/install.sh | sh) uv sync # 这个命令会读取pyproject.toml创建虚拟环境安装playwright等包。 # 3. 安装Playwright所需的Chromium浏览器 uv run playwright install chromium # 这会在本地缓存一个Chromium二进制文件用于无头渲染。验证安装是否成功你可以手动运行一下渲染脚本的测试命令通常AI会做但自己可以验证# 仍在 references/ 目录下 uv run python render_excalidraw.py --help如果能看到帮助信息说明Python环境没问题。Playwright的安装通常需要一点时间下载浏览器确保网络通畅。实操心得第一次设置时playwright install可能会因为网络问题失败。可以尝试设置镜像源例如在运行前设置环境变量PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright。另外确保你的系统有必要的依赖比如在Ubuntu上可能需要libnss3、libatk-bridge2.0等库。3.3 品牌颜色自定义在投入正式使用前花几分钟定制颜色是值得的。打开.claude/skills/excalidraw-diagram/references/color-palette.md文件。 你会看到一个用CSS变量风格定义的调色板。例如## Primary Palette - --color-primary: #2563eb // 主色用于核心实体 - --color-secondary: #7c3aed // 辅助色用于重要支持组件 ...修改这些十六进制颜色码即可。建议至少定义6-8个颜色涵盖主色、辅助色、强调色、背景色、文字色和边框色。你可以从公司品牌指南中取色或者使用在线调色板工具如Coolors、Adobe Color生成一套和谐的颜色。修改后保存即可无需重启AI代理。下次AI生成图表时就会自动应用新的配色方案。4. 使用技能生成图表完整工作流解析安装配置好后你就可以像使用任何内置功能一样使用这个技能了。整个过程对用户来说非常简单但对AI内部来说却经历了一个复杂而精密的链条。4.1 发出自然语言指令你不需要学习任何特殊的语法或标记。就像平时让AI写代码一样用自然语言描述你想要什么样的图。指令越具体、上下文越丰富生成的图就越精准。基础指令示例“为我们的用户认证微服务创建一个架构图。”高质量指令示例推荐“创建一个Excalidraw图表展示用户登录流程的完整后端序列。包括前端SPA、API网关、认证微服务负责JWT生成与验证、用户数据库PostgreSQL、以及一个Redis缓存用于存储刷新令牌。请突出显示OAuth 2.0授权码流程的步骤并用不同的颜色区分公共服务、数据存储和网络边界。在关键交互旁附上示例HTTP请求/响应片段。”第二个指令之所以更好是因为它明确了范围“用户登录流程”、“后端序列”。列举了关键组件前端、网关、认证服务、PostgreSQL、Redis。这减少了AI的猜测。提出了视觉要求“突出显示OAuth 2.0步骤”、“用颜色区分”、“附上示例片段”。这直接激活了技能的“概念映射”和“证据构件”功能。使用了领域术语“JWT”、“OAuth 2.0授权码”、“刷新令牌”这有助于AI选择正确的视觉模板。4.2 AI内部处理流程分解当你发出指令后AI代理如Claude Code会协同这个技能执行以下步骤步骤1指令解析与概念提取AI首先理解你的自然语言指令。它会识别出实体前端SPA、API网关、认证微服务、PostgreSQL、Redis。关系调用、存储、验证、缓存。流程OAuth 2.0授权码流程这是一个已知模式技能库可能预置了其步骤分解。约束与风格架构图、不同颜色区分、附上示例片段。步骤2视觉映射与模板选择AI调用技能的知识库SKILL.md,element-templates.md。对于认证微服务它可能被映射为一个“处理核心”矩形使用主色--color-primary内部可能包含一个齿轮或闪电图标表示业务逻辑。对于PostgreSQL和Redis虽然都是数据存储但可能用不同形状区分PostgreSQL用圆柱体传统数据库符号Redis用一个闪电圆柱体表示内存缓存并使用辅助色--color-secondary。对于OAuth 2.0授权码流程技能库可能预定义了一个包含“用户代理”、“授权服务器”、“资源服务器”、“客户端”的序列模板。AI会实例化这个模板并将你的具体组件前端、认证服务填入相应角色。对于“网络边界”AI会添加一个虚线框或背景色块将内部服务与外部组件前端隔开。步骤3初始布局生成AI根据关系决定布局算法。对于序列流程可能采用从左到右的水平流。对于有层次关系的架构可能采用从上到下的分层布局。它会为每个元素计算一个初始位置和大小并生成连接线箭头。此时它也会插入“证据构件”比如在“前端调用API网关”的箭头旁添加一个便签里面写着POST /api/login和示例请求体。步骤4首次渲染与视觉验证关键循环AI不会直接输出JSON给你。它会将上一步生成的Excalidraw JSON数据传递给本地的render_excalidraw.py脚本。脚本在内存中启动无头Chromium加载一个包含Excalidraw渲染库的HTML页面并将JSON数据注入。浏览器渲染出图表脚本对其进行截图。AI“看到”这张截图实际上是通过分析截图文件的路径或者在某些实现中通过OCR或图像描述模型来理解图像内容。它会检查重叠检测是否有任何文本框与图形或其他文本框重叠布局平衡图表是否严重偏向画布一侧留白是否合理箭头清晰度箭头是否准确指向了图形的边缘而不是悬空或指向图形中心颜色对比度在灰度模式下模拟色盲视图文字和背景是否还能分辨如果发现问题AI会调整JSON。例如将重叠的元素移开重新平衡整体布局微调箭头锚点。然后回到步骤4.1进行下一次渲染和检查。这个循环可能进行2-5次直到达到满意的状态或迭代上限。步骤5交付最终结果当AI认为图表在视觉上合格后它会将最终的Excalidraw JSON文件提供给你并且很可能会附上它生成的PNG预览图。你可以直接复制JSON到Excalidraw官网excalidraw.com的编辑器中粘贴查看或者导入到支持该格式的任何工具中。4.3 与AI代理的交互技巧迭代优化如果对第一次生成的图不满意你可以直接说“把认证服务画得更大一些”或“把Redis移到数据库旁边”。AI会基于现有的JSON进行修改而不是从头开始效率很高。风格指定你可以要求特定的风格如“画成白板手绘风格”或“使用非常正式、干净的商业图表风格”。Excalidraw支持多种画笔粗糙度和样式技能可以控制这些参数。导出需求你可以直接要求“将图表导出为SVG格式背景透明”。AI会调用技能中可能存在的扩展功能或者指导你使用Excalidraw的导出功能。5. 文件结构深度解读与高级定制理解技能包的文件结构能让你更好地进行故障排查和高级自定义。excalidraw-diagram/ ├── SKILL.md # 【灵魂文件】设计方法论与完整工作流说明 ├── references/ # 【核心资源库】 │ ├── color-palette.md # 品牌颜色定义自定义入口 │ ├── element-templates.md # 元素JSON模板库高级定制点 │ ├── json-schema.md # Excalidraw JSON格式速查参考 │ ├── render_excalidraw.py # Python渲染脚本视觉验证引擎 │ ├── render_template.html # 浏览器渲染模板 │ └── pyproject.toml # Python依赖声明(Playwright)5.1 SKILL.md设计方法论圣经这个文件是技能的“大脑”。它不仅仅是一个使用说明更是一份详细的设计指南教育AI如何思考可视化。内容可能包括视觉修辞原则如何用位置、大小、颜色、形状来表达重要性、关系、流程。布局算法提示对于树状结构、网状结构、线性流程分别建议采用何种布局力导向图、分层布局、时间线。常见图表类型范式架构图、序列图、状态图、用户旅程图的固定画法建议。错误案例与纠正展示不好的布局例子如拥挤、歧义箭头并给出修正方案。当你要求AI生成复杂图表时它正是在反复查阅这个文件中的规则。如果你想让技能生成的图表更符合你团队的特定规范比如规定数据库必须画在右侧可以谨慎地修改这个文件加入你自己的规则。但请注意这是一个高级操作需要你对Markdown和AI提示工程有一定理解。5.2 element-templates.md可视化词汇表这个文件定义了“视觉单词”。它将概念映射为具体的Excalidraw JSON片段。例如// element-templates.md 中的一个片段 { “database_postgres”: { “description”: “PostgreSQL数据库图标”, “template”: { “type”: “ellipse”, “x”: 0, “y”: 0, “width”: 120, “height”: 80, “backgroundColor”: “{{color_secondary}}”, “strokeColor”: “#333”, “strokeWidth”: 2, “label”: { “text”: “{{label}}”, “fontSize”: 16 }, “内部附加一个小的圆柱体图形...” } } }当AI需要画一个PostgreSQL数据库时它就会调用这个database_postgres模板将动态的{{label}}如“User DB”和{{color_secondary}}从调色板读取填充进去然后放置到画布的特定坐标。高级定制你可以在这里添加自己团队特有的组件模板。比如你们公司有一个叫“Omega Gateway”的专有关网你可以为它创建一个独特的图标模板。这样以后AI画架构图时就会统一使用这个图标保证图表的一致性。5.3 render_excalidraw.py 与渲染管道这是技能的“手”和“眼”。让我们看看它的核心逻辑伪代码# render_excalidraw.py 核心逻辑示意 import asyncio from playwright.async_api import async_playwright import json async def render_diagram(excalidraw_json_str, output_png_path): # 1. 启动无头浏览器 async with async_playwright() as p: browser await p.chromium.launch(headlessTrue) page await browser.new_page() # 2. 加载本地HTML模板该模板包含了Excalidraw的渲染库 await page.goto(f“file://{path_to_render_template.html}”) # 3. 将AI生成的JSON注入到页面的JavaScript环境中 await page.evaluate(f“window.diagramData {excalidraw_json_str};”) # 4. 触发页面内的渲染函数 await page.evaluate(“renderDiagram(window.diagramData);”) # 5. 等待渲染完成对特定容器截图 diagram_element await page.query_selector(‘#excalidraw-container’) await diagram_element.screenshot(pathoutput_png_path) # 6. 关闭浏览器 await browser.close() # AI调用这个函数获取截图路径然后“查看”截图这个流程确保了渲染环境的一致性。render_template.html是一个本地文件它可能打包了一个简化版的Excalidraw渲染器或者直接引用了Excalidraw的官方UMD库从而避免网络依赖。5.4 自定义与扩展可能性这个技能的架构是高度可扩展的。添加新的元素类型在element-templates.md中定义新模板。修改布局规则在SKILL.md中补充新的布局逻辑描述AI会学习并应用。增强视觉验证可以修改render_excalidraw.py加入更复杂的图像分析。例如使用OpenCV-Python检测元素对齐线或者计算颜色对比度比率给AI提供更精确的反馈。集成其他输出格式可以修改脚本在渲染PNG的同时生成SVG、PDF甚至是一个可交互的HTML文件。6. 常见问题与排查技巧实录在实际使用中你可能会遇到一些问题。以下是我在测试和使用过程中遇到的一些典型情况及解决方法。6.1 技能未被AI代理识别症状向AI发出画图指令后AI回复“我不知道如何画图”或直接开始用文字描述而不是调用技能。排查步骤检查路径确认技能文件夹是否准确放置在.claude/skills/excalidraw-diagram。注意目录名拼写和大小写。检查AI代理确认你的AI编码代理如Claude Code插件、OpenCode是否支持技能功能。查阅其官方文档。重启AI会话有时AI代理需要重新加载技能目录。尝试关闭并重新打开你的编辑器或AI会话窗口。查看AI日志某些AI代理有调试模式或日志输出查看是否有加载技能时的错误信息。6.2 渲染失败或截图空白症状AI尝试生成图表但卡住很久最后报错或者生成的PNG图片是空白或纯色的。原因与解决Playwright浏览器未正确安装这是最常见的原因。手动验证进入references/目录运行uv run playwright install --dry-run chromium检查。如果失败尝试uv run playwright install chromium --force。网络问题如前所述设置国内镜像源环境变量。系统依赖缺失Linux常见Playwright需要一些系统库。例如在Ubuntu/Debian上可以运行sudo apt-get install libnss3 libatk-bridge2.0-0 libdrm2 libxkbcommon0 libgbm1 libasound2来安装常见依赖。Python环境问题确保在references/目录下运行命令uv sync已成功创建虚拟环境。可以手动激活环境检查source .venv/bin/activate(Linux/Mac) 或.venv\Scripts\activate(Windows)然后python -c “import playwright; print(‘OK’)”。HTML模板路径错误检查render_excalidraw.py中加载render_template.html的路径是否正确。通常使用相对路径‘./render_template.html’但取决于脚本执行时的当前工作目录。如果AI是从项目根目录调用脚本路径可能需要调整。一个稳健的方法是使用os.path.dirname(__file__)来构建绝对路径。6.3 生成的图表布局不理想症状图表虽然生成了但元素堆在一起或者箭头乱飞布局混乱。解决提供更详细的指令AI的初始布局基于你的描述。如果你说“画一个系统架构”它可能不知道哪些组件是核心。尝试“画一个架构图将API网关和认证服务放在中心突出位置数据库和缓存放在下方前端客户端放在左侧。”启用并信任视觉验证循环确保渲染管道设置成功。AI的自我修正需要几次迭代。如果第一次图不好你可以说“这个布局太挤了请重新调整一下布局利用视觉验证功能优化一下。” AI会重新进入渲染-修正循环。审查元素模板如果某个特定组件如你的自定义微服务总是画得不好可以去element-templates.md看看它的模板定义是否合理比如初始尺寸是否太大。6.4 颜色不按调色板显示症状修改了color-palette.md但生成的图还是旧颜色或默认颜色。排查缓存问题AI代理或技能可能会缓存调色板。尝试重启AI会话或者让AI“重新读取颜色调色板文件”。文件格式错误确保color-palette.md是有效的Markdown颜色变量定义格式正确没有语法错误。AI在解析时如果出错会回退到默认值。模板引用错误检查element-templates.md中的模板是否正确地引用了调色板变量如{{color_primary}}而不是硬编码的色值。6.5 性能问题生成速度慢症状生成一张图需要几十秒甚至更长时间。分析首次运行慢第一次运行需要启动Python虚拟环境、启动浏览器这是正常的。迭代循环耗时如果AI进行了多轮如5轮视觉验证每轮都要启动浏览器、渲染、截图累积时间就会较长。优化建议降低迭代次数你可以在指令中明确说“生成一版即可不需要多次视觉验证”。或者在技能配置中如果支持调整最大迭代次数。升级硬件Playwright无头浏览器对CPU和内存有一定要求。简化图表过于复杂的图表上百个元素自然会渲染更慢。尝试将大图拆分成几个逻辑清晰的小图。6.6 与现有Excalidraw文件的兼容与编辑场景你有一个已有的.excalidraw或.excalidraw.json文件想让AI帮你优化布局或添加元素。操作将现有文件的内容JSON部分提供给AI。给出明确的修改指令例如“这是当前的架构图JSON请将新增加的‘消息队列’服务集成进去并放在认证服务和数据库之间然后优化整体布局。”AI会读取现有JSON将其作为基础应用技能的布局规则和视觉验证进行修改和优化然后输出新的JSON。这个技能不仅是从零生成也是一个强大的图表重构和美化工具。通过结合AI的理解能力和内置的设计规则它能将杂乱的手绘图快速整理成专业、清晰的图表。