drawio-skill：让 AI 画专业图表的瑞士军刀

你有没有过这样的经历：向 AI 描述一个微服务架构，它洋洋洒洒写了几百字，你看着脑子里一片浆糊——文字描述再详细，也不如一张图来得直观。但问题是，画一张专业的架构图，从拖拽图框到调整连线，往往要耗费 20 分钟，AI 生成的内容又很难"对齐"到现成的图表工具里。

drawio-skill 解决的就是这个问题：它让 AI agent（Claude Code、Cursor、Copilot、OpenClaw、Codex、Hermes……）直接用自然语言生成 .draw.io 格式的专业图表，并调用 draw.io 桌面版的原生 CLI 导出 PNG / SVG / PDF / JPG。整个过程不需要浏览器自动化，不需要服务器，一行命令搞定。

图1：drawio-skill 生成的微服务架构图。 输入一条自然语言描述，自动吐出精确到每个 AWS/GCP 图标、连线路由零交叉的可编辑 draw.io 文件。

项目背景：从"AI 不会看自己画的东西"说起

drawio-skill 的作者是 Agents365-ai，项目出生于 2026 年 3 月，核心洞察非常犀利：所有 AI 画图工具的通病，是模型从来看不见自己画了什么。 当 AI 写代码时，错了会报 stack trace；但当它生成 draw.io XML，循环在闭合标签处就结束了——你打开 draw.io，然后花 20 分钟手动调整。

draw.io 桌面版自带 CLI，能把 .draw.io XML 渲染成 PNG 图片。这个 skill 利用这一点：生成 XML → 调用 CLI 渲染 PNG → 把图片传回给 Claude（它是多模态的，看图是本职）→ Claude 用视觉自检修复重叠、截断标签、连线堆叠问题（最多 2 轮）。这才是一个真正闭合的反馈循环。

项目在 GitHub 上迅速走红，不到半年突破 5791 star、464 fork，入选了 SkillsMP、ClawHub、Claude Code Plugin 等多个 agent skills 市场。Topics 覆盖了 20 个关键词，从 agent-skills 到 sysml，说明它既面向 agent 开发者，也面向系统架构师。

图2：drawio-skill 功能全景图，一张脑图覆盖 11 种图表类型、36 种工具、4 种导入来源。 本脑图本身即由本 skill 生成。

核心功能：11 种图表预设 + 36 种工具

图表类型全覆盖

skill 内置 11 种预设模板，覆盖软件工程中最常见的图表类型：

类型	说明
UML 类图 / 时序图	标准软件设计文档，精确表达类继承和调用关系
SysML / MBSE	BDD / IBD / 需求图 / 参数图，面向系统工程
BPMN 流程图	业务流程建模，业务分析师的刚需
网络拓扑	AWS / Azure / GCP / K8s 官方图标，直出云架构图
C4 模型	System → Container → Component 多层下钻，父页面点击跳转子层
ER 图	解析 SQL DDL，自动生成带 PK/FK 标记的表节点和鸦爪连线
ML / 深度学习架构图	Transformer / CNN / LSTM 组件，学术论文配图神器
流程图 / 泳道图	跨职能流程，支持水平/垂直/环形拓扑
思维导图	Mermaid mindmap 转原生 draw.io，支持递增动画

Mermaid → 原生 draw.io（draw.io CLI ≥ v30）

28 种 Mermaid 标准类型（mindmap、gantt、timeline、journey、pie、sankey、kanban……）可以直接写 Mermaid 文本，然后由 draw.io CLI 转成已布局、可编辑的 .draw.io 文件。你只需要关心结构，布局白送。

图3：用 Mermaid kanban 生成的本项目路线图。 几行文本，直接生成带泳道的看板，拖入 draw.io 即可编辑。

四大导入来源：代码、基础设施、截图、API

导入类型	工具脚本	产出
代码库可视化	pyimports.py、jsimports.py、goimports.py、rustimports.py	按子包嵌套的容器图，Graphviz 自动布局
CI/CD → 架构图	ciimports.py、composeimports.py、dockerimports.py	GitHub Actions / docker-compose → 自动拓扑
IaC → 架构图	tfimports.py、k8simports.py	Terraform / K8s manifest → AWS/GCP/K8s 官方图标
截图 → 可编辑图	raster2drawio.py	照片/截图 → AI 识别 → 可编辑 draw.io
API 规范 → 交互图	openapiimports.py	OpenAPI spec → 架构图

这个组合非常实用：Terraform 配置写好了，tfimports.py 一跑，架构图自动更新；代码重构了，pyimports.py 跑一遍，依赖关系图同步刷新。文档和代码终于可以保持同步了。

特色能力：PR 差异机器人 & 操作手册

PR Diff Bot（prdiff.py）：输入 GitHub PR URL，自动生成变更影响范围图。哪些服务改了、哪些依赖被波及，一图看懂 code review。

点击式操作手册（runbook.py）：把 CI/CD 流水线或故障排查步骤转成交互式文档，每个步骤可点击跳转下一步。这比 confluence 里贴截图高级多了。

图4：skill 处理流程的 Tube-Map 风格渲染。 四条彩色线路（作图/导入/二次利用/分析）在换乘站交汇，像伦敦地铁图一样清晰。

形状库：10,000+ 官方图标 + 321 个 AI 品牌 logo

drawio-skill 附带了 shape-index.json.gz，收录了 AWS / Azure / GCP / Cisco / Kubernetes / UML / BPMN 的 10,000+ 官方图标精确 style 参数。用 shapesearch.py 脚本搜索：不再靠猜 shape=mxgraph.*，杜绝空白框。

对于 LLM/RAG 应用架构图，项目还收录了 321 个 AI 品牌图标（OpenAI、Claude、Gemini、Mistral、Llama、Ollama、LangChain……）以及 18 个数据存储品牌（Redis、Postgres、Qdrant、Milvus……），这些是 draw.io 官方图标库没有的。

图5：shape-search.py 搜索界面。 输入关键词，精确返回 draw.io 官方 style 参数。

图6：321 个 AI/LLM 品牌图标合集。 专为 LLM 应用架构图设计，Claude、OpenAI、Ollama 全覆盖。

技术架构：纯 Python + Shell 脚本的轻量设计

代码结构

项目是典型的 "主技能定义 + 工具脚本集" 架构：

• skills/drawio-skill/SKILL.md：Agent skill 规范定义（兼容 Agent Skills 标准），描述何时调用本 skill、输出格式、bundled resources。
• skills/drawio-skill/scripts/：37 个 Python 工具脚本，按功能分组（导入/导出/布局/自检/动画）
• skills/drawio-skill/styles/：样式预设，支持用户自定义风格
• skills/drawio-skill/data/：形状索引数据（JSON/GZ）
• skills/drawio-skill/references/：技术参考文档（XML 编写规范、Mermaid 规范、工具箱索引）
• docs/：完整用户文档，含安装指南、中英文使用手册、样式预设说明

主力语言：Python（37 个脚本 + 测试 + 工具链），少量 Shell / YAML。

工具链依赖

依赖	用途	是否必需
draw.io CLI	渲染 draw.io XML → PNG/SVG/PDF	必须
Graphviz (dot)	自动布局（scripts/autolayout.py）	可选
多模态 LLM	视觉自检（自动修复重叠/截断）	可选，无则跳过自检

测试覆盖

项目有完整的 pytest 测试套件（tests/ 目录），覆盖构建、压缩、去栅格化、PR diff、runbook、脚本验证、元数据等 8 个模块：test_buildup.py、test_compress.py、test_derasterize.py、test_prdiff.py、test_runbook.py、test_scripts.py、test_skill_metadata.py、test_tubemap.py。

CI/CD 流水线（.github/workflows/tests.yml）确保每次提交自动运行测试。

部署与安装

安装方式

方式一：Claude Code（推荐）

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

方式二：OpenClaw / AutoHand Code / Codex

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

方式三：直接引用 SKILL.md Hermes 等 agent 可以直接把 skills/drawio-skill/SKILL.md 内容注入 context。

前置依赖

安装 draw.io 桌面版 CLI（各平台不同）：

• macOS: brew install --cask drawio
• Windows: 下载安装包
• Linux: snap install drawio 或从 GitHub releases 下载 AppImage

部署难度评估

维度	评分
部署难度	简单（git clone 即用）
资源需求	极低（skill 包 50MB，无 GPU 需求）
前置依赖	只需 draw.io CLI
容器化	不适用（纯工具包，无服务进程）
Web UI	无（CLI 工具）

局限性与注意事项

1. 必须安装 draw.io CLI：skill 本身是纯文本/脚本组合，但 draw.io CLI 是不可替代的依赖。在 CI/CD 环境中需要先安装 draw.io。
2. 多模态 LLM 视觉自检依赖：如果运行的模型不支持视觉能力，自动修复功能会静默跳过（gracefully skipped）。
3. 导出格式限制：PNG/SVG/PDF/JPG 的 --embed-diagram（嵌入完整 XML）功能需要 draw.io CLI ≥ v30。
4. 图形自动化局限：不适合完全无头环境（无图形界面）——虽然 CLI 可以在无头模式运行，但布局预览需要 display 环境变量。

行业意义：文档即代码的新范式

drawio-skill 代表了一个重要趋势：文档和架构图不再是事后补充，而是和代码一起被 AI 生成。 当一个项目里的图表可以随代码一起更新，当 CI/CD 流水线的架构图可以随配置一起刷新，文档腐化（documentation rot）的问题终于有了技术解法。

项目目前已突破 5791 star、464 fork，star 增长曲线陡峭。它被 SkillsMP、ClawHub、Claude Code Plugin 三大市场同时收录，说明 Agent Skills 生态正在快速成熟——skill 不再是单个 agent 的私有资产，而是可以在不同 agent 间流通的可复用组件。

如果你在用 Claude Code、Cursor、Copilot、Codex 或任何兼容 Agent Skills 的 agent，给你的 toolbelt 里加上 drawio-skill，下次需要画架构图时，只需要说一句「给我画一个微服务架构图」，剩下的交给 AI。