drawio-skill 快速入门

drawio-skill 快速入门

一句话卖点：用自然语言一句话描述系统架构，AI 自动生成可编辑的 draw.io 图表——带视觉自检、最多 5 轮精修、导出即用。

这是什么？适合谁？

drawio-skill 是 Agents365-ai 开源的 Agent Skill，能将自然语言描述直接转换为 draw.io 原生 XML，并导出为 PNG/SVG/PDF/JPG。它不是一个简单的文本→图形转换器，而是一个带有自我检查和迭代优化的专业图表生成引擎。
核心特色：

• 6 类预设风格：架构图、流程图、UML、ER 图、网络拓扑、产品说明图——每种都有成熟的排版模板；
  
• 视觉自检系统：生成 PNG 后 AI 读取图像，自动检测重叠形状、截断标签、堆叠连线等问题并修复（最多 2 轮自动修复）；
  
• 5 轮迭代精修：用户可以通过自然语言反馈让 AI 逐轮优化（“把数据库节点左移”、“统一用蓝色调”），最多 5 轮；
  
• 代码库→结构图：给你的代码仓库路径，AI 自动分析 Python/JS-TS/Go/Rust 项目结构并生成架构图；
  
• 10,000+ 官方图形 + 321 个 AI/LLM 品牌 logo：包括 AWS、GCP、Azure 官方图标库和主流 AI 公司品牌标识；
  
• 多格式导出：PNG、SVG、PDF、JPG——其中 PNG/SVG/PDF 支持 --embed-diagram，导出的文件内嵌完整 XML，用 draw.io 打开可继续编辑。
  适合谁？需要频繁绘制技术图表的开发者、架构师、技术写作者。特别适合画系统架构图、微服务拓扑、数据流图、UML 类图/时序图。也适合需要「从代码库反向生成文档图」的团队。
  不适合？追求像素级美学设计的设计师（AI 生成的布局虽专业但不如手绘精细）；需要实时协作编辑的白板场景（draw.io 文件更适合异步共享）。
  

准备工作

1. 安装 draw.io Desktop 应用并确保 CLI 可用：
   

• macOS: brew install --cask drawio 或从 draw.io releases 下载 .dmg
  
• Windows: winget install JGraph.Draw 或下载 .exe 安装包
  
• Linux: 下载 .deb/.rpm 或使用 AppImage
  

2. 确认 CLI 可执行：
   

drawio --version   # 应输出版本号<br>
# 如果找不到命令，可能需要添加别名：<br>
# macOS: alias drawio='/Applications/draw.io.app/Contents/MacOS/draw.io'<br>
# Windows: 将 draw.io 安装目录加入 PATH<br>
```<br>
3. 一个支持 Agent Skills 的 AI 编程助手（Claude Code / Cursor / Hermes Agent / OpenAI Codex）
> ⚠️ **macOS 沙盒注意**：部分沙盒化环境（如 Codex.app）中调用 draw.io CLI 可能导致崩溃或无输出。如遇到此问题，可尝试在非沙盒终端中运行。

## 3 步快速上手

### 第 1 步：安装 Skill

```bash

# 克隆仓库

git clone https://github.com/Agents365-ai/drawio-skill.git

cd drawio-skill

# Claude Code 用户 — 软链到 skills 目录

mkdir -p ~/.claude/skills

ln -s $(pwd)/skills/drawio-skill ~/.claude/skills/drawio-skill

# Hermes Agent 用户 — 复制到 profile 的 skills 目录

cp -r skills/drawio-skill ~/.hermes/profiles/default/skills/

# Cursor 用户 — 放到 rules 目录

cp skills/drawio-skill/SKILL.md ~/.cursor/rules/drawio-skill.md

Skill 的核心文件是 SKILL.md，包含完整的图表生成指令和 10,000+ 图形索引。安装后 AI 助手会自动发现并加载。

第 2 步：配置

Skill 开箱即用，无需额外配置文件。你只需确保 draw.io CLI 路径正确。如果需要自定义行为：

• 自定义导出路径：在提示中指定输出目录，如「导出到 ./diagrams/」

• 选择风格预设：在提示中指定图表类型，AI 会自动匹配对应模板

• 品牌图形：提到具体品牌名（如「AWS Lambda」「OpenAI Logo」），AI 会使用对应的官方图标

第 3 步：首次使用

在加载了 Skill 的 AI 助手中输入：

“画一个微服务架构图：API Gateway → 3 个后端服务（用户服务、订单服务、支付服务），都连接同一个 PostgreSQL 数据库和 Redis 缓存。用户服务调用外部短信网关。导出为 PNG。”

AI 会：

1. 生成 .drawio XML 文件

2. 调用 draw.io CLI 导出为 PNG

3. 自动视觉检查：读取 PNG，检测重叠、截断等问题

4. 如有问题自动修复并重新导出

5. 输出最终文件路径

# 查看生成的文件

ls -la output/

# architecture.png    ← 可编辑 PNG（内嵌 XML）

# architecture.drawio ← 源文件（可在 draw.io 中编辑）

用 draw.io Desktop 打开 .drawio 文件或直接拖拽 PNG 到 draw.io 窗口即可继续手动编辑。

常见踩坑

1. draw.io CLI 找不到：最常见的问题。确认安装后执行 drawio --version 验证。macOS 用户注意 /Applications/draw.io.app/Contents/MacOS/draw.io 路径。如果仍然失败，在 Skill 提示中明确告知 AI 你的 drawio 可执行文件完整路径。

2. 沙盒环境崩溃：macOS 的 Codex.app 等沙盒应用中 drawio CLI 可能无输出或崩溃。解决：在系统终端中运行，或将 Skill 用于非沙盒客户端。

3. 导出格式选择：PNG 适合嵌入文档，SVG 适合网页嵌入且无损缩放，PDF 适合打印分发，JPG 体积最小但不可嵌入 XML。推荐默认用 PNG（--embed-diagram 参数）。

4. 大型代码库生成超时：代码库→结构图功能对 100+ 文件的仓库可能需要较长时间。建议先用 tree 命令生成目录结构再输入给 AI。

5. 品牌 logo 识别：321 个 AI/LLM 品牌 logo 覆盖主流厂商。如果不确定是否包含某个品牌，先在提示中提及品牌名让 AI 查找；若不在内置库中，可以用通用图标替代。

初级用法

• 系统架构图：「画一个 AWS 上的三层 Web 架构：ALB → EC2 Auto Scaling → RDS，加 ElastiCache 缓存层」

• 数据流图：「用户上传文件 → S3 存储 → Lambda 处理 → DynamoDB 记录元数据 → CloudFront CDN 分发」

• UML 类图：「电商系统的类图：User、Order、Product、Payment 四个核心类及其关联关系」

• ER 图：「博客系统的 ER 图：users、posts、comments、tags、post_tags 五张表，标注主键和外键」

• 流程图：「用户注册流程：填写表单 → 邮箱验证 → 设置密码 → 完善资料 → 完成注册，加入异常分支」

• 网络拓扑：「办公室网络拓扑：防火墙 → 核心交换机 → 3 个部门交换机 → 终端设备，加 VPN 网关」

高级玩法

• 代码库反向生成：「分析当前项目 ./src/ 目录，生成模块依赖关系图」——AI 会读取代码结构自动绘制；

• 风格预设（v1.3 新功能）：用一个已有的 .drawio 文件或截图作为风格模板——「用这个文件的配色和字体风格，画一个新项目的架构图」；

• 多轮迭代精修：生成初版后逐轮优化——第 1 轮「把数据库图标换成 AWS RDS」、第 2 轮「箭头加粗到 2px」、第 3 轮「给所有服务节点加阴影」……每轮都是增量改进；

• 批量图表生成：一次生成多个相关图表——「画 3 张图：系统架构图、部署拓扑图、核心时序图，统一用蓝色调」；

• 多语言图表：「架构图用中英文双语标注节点名称和说明」。

小技巧

1. 先说图表类型：在提示开头明确图表类型（架构图/流程图/ER 图…），AI 会匹配最优模板；

2. 节点命名要具体：写「用户认证微服务」而不是「一个服务」，具体命名能让 AI 选对图标和布局；

3. 利用风格预设：先画一张满意的图，保存 .drawio，后续所有图都以它为风格模板——团队图表风格统一的神器；

4. SVG 用于网页：文档或网页嵌入选 SVG，缩放不失真且体积小；

5. PNG 内嵌 XML：导出 PNG 时确保 --embed-diagram 开启（默认开启），这样 PNG 既是预览图又是可编辑源文件——拖进 draw.io 就能继续编辑；

6. 结合 Mermaid：如果不确定布局，先用 Mermaid 语法描述结构让 AI 理解，再让 drawio-skill 生成正式的 draw.io 图表。

常见问题 FAQ

Q1: 和 Mermaid/D2 等文本绘图有什么区别？

A: Mermaid/D2 是「代码→图形」的声明式绘图语言，适合嵌入 Markdown 和开发者文档。drawio-skill 是「自然语言→专业图形」，用 AI 理解意图后生成 draw.io 原生 XML，拥有 10,000+ 官方图形库、品牌 logo、和完整的手动编辑能力。简单来说：Mermaid 适合轻量嵌入，drawio-skill 适合正式文档和演示级图表。来源：GitHub README 功能对比。

Q2: 需要付费吗？

A: Skill 本身 MIT 开源免费。draw.io Desktop 应用也完全免费开源。你只需要承担 AI 助手（Claude/ChatGPT 等）的 API 调用费用，单次图表生成约 $0.02-0.10。来源：GitHub LICENSE + draw.io 官网。

Q3: 生成的图表可以手动编辑吗？

A: 完全可以。导出的 PNG/SVG/PDF（使用 --embed-diagram 参数）内嵌了完整的 draw.io XML。直接把文件拖入 draw.io Desktop 或 draw.io 网页版即可继续编辑每一个节点、连线、样式。来源：SKILL.md 导出说明。

Q4: 支持哪些图表类型？

A: 架构图、流程图、UML 类图/时序图、ER 图、网络拓扑图、ML/DL 模型结构图（Transformer/CNN/LSTM）、思维导图、组织结构图、BPMN 流程图、泳道图、产品路线图等。详见 references/diagram-types.md。来源：GitHub 仓库 references 目录。

Q5: 代码库→结构图功能支持哪些语言？

A: 当前支持 Python、JavaScript/TypeScript、Go、Rust 四种语言的代码库自动分析。AI 会读取目录结构、import/依赖关系、模块组织来生成结构图。支持 mono-repo 和多模块项目。来源：SKILL.md 代码库分析说明。

Q6: 视觉自检能发现哪些问题？

A: 重叠的形状、被截断的文字标签、堆叠/交叉的连接线、节点超出画布边界、配色对比度不足等。自检系统读取导出 PNG 后通过 AI 视觉扫描发现这些问题，自动调整布局（最多 2 轮自动修复），然后加上用户驱动的 5 轮迭代精修。来源：GitHub README self-check 说明。

参考链接

• drawio-skill 仓库：https://github.com/Agents365-ai/drawio-skill

• drawio-skill 官方文档站：https://agents365-ai.github.io/drawio-skill/

• draw.io Desktop 下载：https://github.com/jgraph/drawio-desktop/releases

• draw.io 网页版：https://app.diagrams.net/

• Agent Skills 生态目录（SkillsMP）：https://skillsmp.com

• Hermes Atlas 项目页：https://hermesatlas.com/projects/Agents365-ai/drawio-skill