1. 项目概述：用自然语言画图，让AI成为你的专属图表设计师

如果你和我一样，经常需要画各种系统架构图、流程图，但每次打开绘图工具，面对一堆图形拖拽、连线、调样式就头疼，那这个项目绝对能让你眼前一亮。Agents365-ai/excalidraw-skill 是一个为 Claude Code 设计的技能，它的核心就一句话： 用嘴画图 。你只需要用中文或英文描述你想要什么图，它就能自动生成一份专业、美观、可直接编辑的 Excalidraw 图表文件，还能一键导出成 PNG 或 SVG。

这听起来像是把大象装进冰箱那么简单，但背后其实是一套完整的、经过深思熟虑的设计体系。它不是一个简单的“翻译器”，把文字变成图形元素堆砌。它更像是一个内置于 Claude 大脑里的“图表设计师”，懂得如何配色、如何布局、如何避免图表中的常见“车祸现场”。我花了几天时间深度使用和拆解这个技能，发现它解决的不是“能不能画”的问题，而是“怎么能画得又快又好”的问题。对于开发者、产品经理、技术文档工程师，或者任何需要频繁进行技术沟通的人来说，这几乎是一个生产力倍增器。

2. 核心设计思路：为什么“教AI画画”比“给AI画笔”更聪明？

在深入细节之前，我们先聊聊这个项目最根本的设计哲学。市面上有很多工具试图让AI辅助绘图，但路径大致分为两种：一种是给AI一个“画笔”（比如通过 MCP 服务器暴露一个绘图API），另一种是“教AI怎么画”（就像这个技能所做的）。这个项目坚定地选择了后者，并且我认为这个选择非常高明。

2.1 Skill vs. MCP：理念之争

MCP（Model Context Protocol）的思路是，让Claude调用一个外部服务。比如，你运行一个绘图服务器，Claude把需求发过去，服务器生成图表返回。这听起来很合理，对吧？但这个技能的作者认为，对于生成Excalidraw JSON这种纯文本结构化的任务，这属于“杀鸡用牛刀”。

Excalidraw的底层文件格式就是一个JSON数组，里面定义了每个图形元素的类型、位置、大小、颜色和文字。 生成这个JSON，恰恰是大型语言模型最擅长的事情之一 。LLM天生就理解结构、关系和语义。问题不在于LLM“不会写JSON”，而在于它“不知道怎么写得好”。它可能把元素堆在一起，可能用随机的颜色，可能画出交叉混乱的箭头。

这个技能所做的，就是通过一套精心编写的提示词（Skill），将人类图表设计师的最佳实践“注入”到Claude的思考过程中。它教会Claude：

• 什么时候该画图 ：当对话中描述的系统包含3个或以上组件时，自动触发图表生成建议。
• 怎么布局好看 ：针对流程图、架构图等不同模式，有明确的间距、对齐规则。
• 怎么配色专业 ：使用一套基于“60-30-10”法则的语义化色彩系统。
• 怎么避免错误 ：内置了“反模式”清单，让AI提前规避文字重叠、箭头混乱等问题。

所以，这个技能的本质，是 将设计规范与约束转化为AI可理解和执行的规则 ，从而释放LLM在结构化生成方面的原生潜力，而不是用一个外部服务去限制它。

2.2 零安装与主动触发：无缝融入工作流

这个设计的另外两个精妙之处在于“零安装”和“主动触发”。

零安装（Kroki API方案） ：你不需要在本地安装Node.js、Docker或者启动一个浏览器。图表渲染通过一个公开的在线服务Kroki完成，你只需要系统里有 curl 这个几乎无处不在的命令行工具。这意味着，在任何能运行Claude Code的环境（包括一些受限的服务器环境），你都能立即使用SVG导出功能。

主动触发 ：这是提升体验的关键。你不需要在每次描述完一个复杂系统后，再补一句“请帮我画个图”。当Claude通过这个技能“学习”后，它会在对话中自动识别出“这是一个适合可视化的复杂结构”，然后主动询问：“是否需要我为您生成一个架构图来更清晰地展示？” 这种“预判需求”的能力，让工具从“需要你命令的仆人”变成了“理解你意图的助手”。

3. 专业图表设计体系深度解析

这个技能远不止是“生成图形”，它内置了一整套从平面设计、信息架构中借鉴来的专业体系。这才是它区别于“玩具”项目的核心。

3.1 语义色彩系统：告别“彩虹图”

很多自动生成的图表喜欢用鲜艳、随机的颜色，结果就是一张令人眼花的“彩虹图”，信息层次混乱。这个技能采用了经典的 60-30-10 色彩法则 ，这是一个在室内设计和UI设计中广泛使用的原则。

• 60% 的主色调（中性色） ：通常是浅灰色或白色的背景和大量留白，确保画面干净、呼吸感强。
• 30% 的辅助色 ：用于区分主要的功能区块或数据类型。技能预定义了8种语义颜色：
  • 主要 (蓝色) ：核心服务、关键流程。
  • 成功 (绿色) ：完成状态、存储层（如数据库）。
  • 警告 (黄色) ：缓存、中间状态。
  • 错误 (红色) ：错误处理、告警服务。
  • 外部 (紫色) ：第三方服务、API。
  • 流程 (天蓝色) ：数据流、消息。
  • 触发 (橙色) ：触发器、事件源。
  • 中性 (灰蓝色) ：基础设施、支撑组件。
• 10% 的重点色 ：用于高亮最关键的元素或箭头，比如核心数据流向、最重要的用户入口。

通过这套系统，生成的图表一眼望去就能区分出内部服务、外部依赖、数据存储和流动方向，信息传达效率极高。

3.2 智能尺寸与间距：像素级的严谨

自动布局最怕两件事：文字被截断、元素挤成一团。这个技能通过精确的计算规则解决了这两个痛点。

元素宽度计算 ：

• 西文字符： 宽度 = max(160, 字符数 * 9) px
• 中日韩字符： 宽度 = max(160, 字符数 * 18) px

这个规则保证了即使是一个单词的标签（如“API”），也有160px的最小宽度，看起来舒适；而对于较长的中文服务名，则按字符数动态扩展，确保文字完全显示，不会出现尴尬的“…”省略号。

精确间距体系 ： 这是让图表显得“专业”而非“业余”的关键。技能文档里明确规定了不同场景下的像素间距：

• 同一列内，元素间的垂直间距： 120px 。
• 不同列之间的水平间距（有箭头标签时）： 400px ；无标签时： 340px 。这个差值是为了给箭头标签留出空间。
• 箭头与连接的元素之间： 150-200px （有标签）， 100-120px （无标签）。
• 容器（如表示一个微服务组的方框）的内边距： 50-60px 。

这些数字不是拍脑袋想的，而是在Excalidraw的默认画布和字体大小下，经过多次测试得出的视觉舒适区。遵循这些规则，生成的图表会自然呈现出清晰的视觉层次和引导路径。

3.3 箭头语义与路由：让流程图“活”起来

箭头是流程图的灵魂，混乱的箭头会让整个图表难以阅读。技能定义了三种箭头样式和三种路由方式。

箭头样式语义 ：

• 实线箭头 ：表示主流程、强依赖、同步调用。这是最常用的箭头。
• 虚线箭头 ：表示响应、异步消息、回调或可选流程。比如一个服务发送消息到Kafka，就可以用虚线箭头。
• 点线箭头 ：表示弱依赖、参考关系或非必要的链接。

箭头路由模式 ：

1. 直线 ：默认方式，两点之间最短距离。
2. L形折线 ：当需要绕过其他元素，或者明确表示“向下一个环节”传递时使用。在Excalidraw JSON中通过 points 属性实现直角转折。
3. 曲线弯折 ：用于表示跨越多区域的连接，避免与大量其他箭头交叉。通过设置 roundness: { type: 2 } 实现平滑曲线。

更重要的是，技能生成的 .excalidraw 文件中的箭头是 双向绑定 的。这意味着当你把文件导入Excalidraw.com在线编辑器后，拖动矩形框，与之相连的箭头会自动跟随移动，保持了图表的可编辑性和整洁性。

4. 五种图表模式与反模式防护

技能不是生成一种通用的“框图”，而是针对五种常见图表类型进行了专门的布局优化。

4.1 专用布局模式

模式	核心布局逻辑	适用场景与技巧
流程图	采用严格的 从左到右 或 从上到下 的线性布局。每个处理步骤（矩形）或判断（菱形）间距200px，决策分支向下展开。	非常适合算法流程、审批流。 技巧 ：对于复杂判断，使用“L形折线”箭头清晰展示“是/否”分支的走向。
架构图	列式布局 的典范。通常将用户端放在最左列，网关/负载均衡在第二列，业务微服务在中间列，数据存储与外部服务在最右列。严格遵循列间距规则。	绘制微服务、系统部署图的不二之选。 技巧 ：用不同语义颜色区分服务类型（如蓝色业务服务、绿色数据库），用容器框将同一模块的服务分组。
时序图	参与者（如用户、服务、数据库）纵向排列，间距200px。生命线从上到下延伸，消息箭头在参与者之间水平穿梭，并标注调用方法和顺序。	用于厘清API调用顺序、协议交互。 技巧 ：虽然Excalidraw不是专业时序图工具，但通过矩形+垂直虚线+水平箭头可以很好地模拟。
思维导图	放射状布局 。中心主题在画布中央，一级分支呈环形展开，二级分支再向外辐射。字体和框体大小随层级递减。	用于头脑风暴、知识梳理、项目规划。 技巧 ：避免层级过深（超过4级），否则在单页上会显得拥挤。可以用“曲线弯折”箭头连接关联的不同分支。
泳道图	用长矩形划分水平“泳道”，代表不同部门、系统或角色。流程步骤放置在对应的泳道中，箭头可以跨泳道连接。	用于描述跨团队/系统的业务流程，如订单履约、故障排查SOP。 技巧 ：泳道的标题要醒目，跨泳道的箭头尽量保持水平段对齐，显得整齐。

4.2 反模式防护：把经验教训写成规则

这是该项目最体现“匠心”的地方。作者将自己或他人画图时容易犯的错误，总结成一份“避坑清单”，并写进了技能指令里。这相当于让Claude在动笔前，先看一遍《图表设计常见错误大全》。主要包括：

1. 文字重叠 ：禁止将文字标签放在图形元素的中心（Excalidraw默认居中对齐，会重叠）。必须将文字放在元素上方或下方足够间距的位置。
2. 箭头面条化 ：当两个区域之间有多条箭头时，避免所有箭头从同一点出发、同一点结束，变成一团“面条”。应该错开箭头的起点和终点，或者使用合并的“总线”式画法。
3. 标签碰撞 ：短距离的箭头上如果标注文字，很容易与两端的元素重叠。规则要求，短箭头要么不标文字，要么将文字放在箭头一侧并用引线指向箭头。
4. 容器透明度过高 ：用于分组的容器框（背景矩形），如果透明度过高（如 0.1 ），在浅色背景下几乎看不见，失去分组意义。技能规定容器填充透明度不低于 0.05 ，边框清晰。
5. 色彩滥用 ：严格限制使用预定义的8种语义色，禁止随意使用其他鲜艳颜色，防止图表变成调色板。

通过将这些规则内化，Claude生成的图表第一版完成度就非常高，省去了大量后期调整的时间。

5. 完整实操指南：从安装到出图

理论说了这么多，我们来实际操作一遍。我会以最常用的Claude Code环境为例，展示从零开始到生成第一张架构图的全过程。

5.1 技能安装

首先，你需要一个能运行Claude Code的环境。然后，将技能文件克隆到指定目录。

全局安装（推荐） ： 这样在任何项目里都能使用这个技能。

# 创建Claude Code的技能目录（如果不存在）
mkdir -p ~/.claude/skills

# 克隆技能仓库
git clone https://github.com/Agents365-ai/excalidraw-skill.git ~/.claude/skills/excalidraw

安装完成后，重启你的Claude Code会话。Claude会自动加载 ~/.claude/skills/ 目录下的所有技能。

项目级安装 ： 如果你只想在当前项目中使用，可以克隆到项目内的 .claude/skills/ 目录。

git clone https://github.com/Agents365-ai/excalidraw-skill.git .claude/skills/excalidraw

5.2 依赖准备：两种导出方式

技能生成的是 .excalidraw 文件，我们需要将其导出为图片（PNG/SVG）。有两种方式：

方式一：Kroki API（零安装，仅SVG） 这是最简单的方式，只需要 curl 。

# 检查curl是否可用
curl --version

如果系统已安装（macOS、Linux、WSL通常预装），就可以直接用了。技能生成的命令会通过 curl 将JSON数据POST到 https://kroki.io 服务，返回SVG图片。 优点 ：无需任何额外安装，随时随地可用。 缺点 ：1）需要网络；2）只支持SVG格式；3）复杂图表可能因Kroki服务超时而失败。

方式二：本地CLI（推荐，支持PNG/SVG） 这种方式在本地使用无头浏览器渲染，更稳定，支持PNG。

# 1. 全局安装导出CLI工具
npm install -g excalidraw-brute-export-cli

# 2. 安装Playwright的Firefox浏览器（用于无头渲染）
npx playwright install firefox

对于 macOS用户 ，由于快捷键差异，需要执行一个一次性补丁：

# 找到CLI的主文件路径
CLI_MAIN=$(npm root -g)/excalidraw-brute-export-cli/src/main.js

# 将快捷键从Control（Ctrl）替换为Meta（Command）
sed -i '' 's/keyboard.press("Control+O")/keyboard.press("Meta+O")/' "$CLI_MAIN"
sed -i '' 's/keyboard.press("Control+Shift+E")/keyboard.press("Meta+Shift+E")/' "$CLI_MAIN"

注意 ： sed -i '' 是macOS上的语法，Linux上通常用 sed -i 。如果命令执行失败，可以手动编辑 main.js 文件，进行上述替换。

5.3 实战：生成你的第一张架构图

现在，打开你的Claude Code，可以直接用中文描述需求。例如，输入：

“帮我画一个简单的博客系统架构图，包含用户浏览器、Nginx反向代理、Node.js应用服务器、MySQL数据库和Redis缓存。用箭头标明数据流向。”

Claude在加载技能后，会识别出这是一个包含多个组件的系统描述，很可能会主动回复：

“我检测到您描述了一个包含多个组件的系统架构。是否需要我为您生成一个可视化的架构图，以便更清晰地展示各组件关系？”

你回答“是”或者直接让它画图。接下来，Claude会开始工作：

1. 构思与生成JSON ：它会根据技能里的规则，决定使用“架构图”模式，将组件按列排列，为Nginx、Node.js、MySQL、Redis分配语义颜色（如外部、主要、成功、警告），计算合适的框体大小和间距。
2. 保存文件 ：它会在当前目录生成一个 .excalidraw 文件，例如 blog_system_architecture.excalidraw 。
3. 执行导出命令 ：它会根据你的环境，生成并执行导出命令。
   • 如果检测到有本地CLI，它会运行类似以下的命令：

     excalidraw-brute-export-cli blog_system_architecture.excalidraw -o blog_arch.png
     

   • 如果只有 curl ，它会生成一个复杂的curl命令，将JSON提交到Kroki并下载SVG。
4. 输出结果 ：最终，Claude会告诉你图片已生成，并可能直接将图片以Markdown格式嵌入回复中（ ![架构图](blog_arch.png) ），你可以直接点击查看或下载。

实操心得 ：第一次运行时，如果使用本地CLI方式，可能会因为Firefox启动稍慢而等待几秒，这是正常的。生成的PNG图片默认是带有Excalidraw手绘风格的，如果希望是纯色背景的“标准”图表，可以在技能描述中更早地告诉Claude你的偏好。

6. 高级技巧与自定义调优

掌握了基础用法后，你可以通过更精细的指令，来驾驭这个技能，生成更符合你心意的图表。

6.1 指令控制图表细节

技能支持通过自然语言指令来调整生成的图表。这些指令可以混合在最初的描述中。

• 指定图表模式 ：“画一个 流程图 ，展示用户登录的步骤。”
• 控制颜色 ：“将数据库全部用绿色表示，外部API用紫色。”
• 调整布局 ：“使用 横向布局 ，从左到右展示数据流水线。”
• 聚焦细节 ：“ 重点突出 支付服务与订单服务的交互关系，其他服务可以简化。”
• 导出格式 ：“请导出为 SVG 格式，我需要矢量图进行编辑。”

6.2 处理复杂大型图表

对于非常庞大的系统（例如包含几十个微服务的架构），一次性生成可能会超出Claude的上下文限制。技能内置了“分段构建”的策略。你可以这样操作：

1. 先让Claude生成核心主干架构图。
2. 然后基于生成的文件，要求Claude“在现有图表的基础上，在 数据层 区域添加Elasticsearch日志集群和MongoDB NoSQL数据库”。
3. Claude会读取现有的 .excalidraw 文件，在其基础上添加新元素，并保持整体的设计风格一致。

这相当于进行“增量绘图”，非常适合迭代式地构建复杂图表。

6.3 编辑与协作

生成的 .excalidraw 文件是纯JSON文本，同时也是Excalidraw的官方格式。你可以：

1. 直接上传到 excalidraw.com ，进行图形化编辑。所有箭头绑定、分组关系都完好无损。
2. 将其加入Git版本控制，像管理代码一样管理你的架构图变更。
3. 与团队成员分享 .excalidraw 文件，他们可以在Excalidraw中查看和修改，无需安装任何特殊工具或技能。

7. 常见问题与排查实录

在实际使用中，你可能会遇到一些问题。以下是我遇到和收集的一些典型情况及其解决方法。

问题现象	可能原因	解决方案
Claude没有主动提示画图	1. 技能未正确加载。 2. 描述中组件不够复杂（未达到3个）。	1. 检查技能文件是否在正确的 ~/.claude/skills/ 目录下，重启Claude Code。 2. 直接明确要求：“请使用excalidraw技能为我画一个图。”
导出PNG时失败，报浏览器错误	1. Playwright的Firefox未正确安装。 2. (macOS) 快捷键补丁未打。	1. 重新运行 npx playwright install firefox 。 2. 检查并确保已为macOS应用了快捷键补丁。
使用Kroki导出SVG失败，超时或返回错误	1. 网络问题无法访问Kroki.io。 2. 生成的JSON过于复杂，超出Kroki处理限制。	1. 检查网络连接，或尝试使用本地CLI方式。 2. 简化图表，或要求Claude将图表拆分成多个部分分别生成。
生成的图表布局混乱，元素重叠	1. 描述过于模糊，AI理解有偏差。 2. 在已有图表上增量添加时位置计算冲突。	1. 提供更清晰、结构化的描述。例如：“画一个三列的架构图，第一列是客户端，第二列是网关和服务，第三列是数据库。” 2. 尝试重新生成整个图表，或手动在excalidraw.com上调整。
中文标签显示不全，被截断	AI在计算宽度时可能偶尔失误。	技能规则已考虑CJK字符双倍宽度，但若仍出现，可在指令中强调：“确保所有文本框宽度足够，完整显示中文标签。”
箭头样式不符合预期（如该用虚线却用了实线）	AI对关系语义的理解与你不符。	在描述中明确箭头类型：“用户点击后， 异步调用 支付服务（用虚线箭头表示）。”

一个我踩过的坑 ：在团队内部共享使用流程时，有的同事使用Windows（WSL），有的用macOS。本地CLI方式在Windows上一切正常，但在某位同事的macOS上始终导出失败。排查了很久才发现，他全局安装的 excalidraw-brute-export-cli 版本较旧，与当前技能脚本中预期的API不兼容。 解决方案 是统一要求团队成员更新CLI工具到最新版本： npm update -g excalidraw-brute-export-cli 。这提醒我们，对于依赖本地工具链的工作流，版本一致性很重要。

8. 总结与适用场景思考

经过这段时间的深度使用，我认为 Agents365-ai/excalidraw-skill 这个项目成功地在一个非常具体的痛点（快速生成技术图表）上，找到了最优解。它没有追求大而全的“AI绘图”，而是精准地结合了LLM的结构化生成能力与专业的设计规范。

它最适合谁？

• 全栈开发者/架构师 ：快速绘制和迭代系统设计图，用于技术评审或文档。
• 技术布道师/讲师 ：制作演讲材料中的技术示意图，效率远超PPT手绘。
• DevOps/SRE工程师 ：绘制故障排查流程图、系统部署拓扑图。
• 产品经理 ：与技术团队沟通复杂业务逻辑时，快速画出流程草图对齐认知。
• 个人学习者 ：阅读开源项目或学习新技术时，用图表来梳理和巩固知识结构。

它的局限性 ：

• 本质上仍是 基于规则的生成 ，对于极度追求艺术感或特定公司设计规范的图表，可能仍需后期人工调整。
• 非常复杂的、非标准的图表类型（如地图拓扑、甘特图）可能不支持或效果不佳。
• 高度依赖Claude Code的运行环境和网络（如果使用Kroki API）。

我个人最欣赏的一点 是，它将“最佳实践”编码化了。我们每个人画图都会慢慢积累一些经验（比如别把字放框中间、箭头别画太乱），但这个技能把这些散落的、感性的经验变成了Claude可以严格执行的理性规则。这或许才是AI辅助工具的正确打开方式：不是替代人类，而是将人类积累的智慧，变成一种可规模复用的能力。