首页 / 开源热榜 / drawio-skill / 使用教程

drawio-skill 中文教程：从可编辑小图开始

核对日期：2026-09-23 · 已读官方 README、SKILL.md 与 CHANGELOG，未安装或执行技能

drawio-skill 是给 coding agent 使用的 diagrams.net 工具包。它能把文字、代码、Terraform、Kubernetes、SQL 和 API schema 变成可编辑的 .drawio，也能同步源码变化、做架构规则检查、查询依赖和发布离线 HTML。它不是一个只负责“画得好看”的提示词文件：安装后，代理可以执行 Bash、读写文件和访问网页，所以应把它当作代码依赖审阅。

版本判断：main 分支的 SKILL.md 标记 3.4.0；GitHub Releases 最新可见包仍是 v1.28.2。请固定 commit，并以同一 commit 内的 SKILL.md 与 CHANGELOG 为准。

1. draw.io、Python 与 Graphviz 各做什么

Diagram IR、同步、查询、规则检查、review 和 Story HTML 只要求 Python 3。PNG、SVG、PDF 等原生渲染依赖 draw.io desktop CLI。Graphviz 只在某些自动布局和压缩流程使用；PyYAML、python-pptx、Pillow 也都是按功能加载。先确定要交付什么，再安装对应依赖。

draw.io CLI 30 以上还能把 Mermaid 转成可编辑 draw.io，并提供 ELK layout。29 或更早版本没有这些能力，不能照抄新版参数。

2. 用项目级目录安装

官方给出 npx skills add，但首次审阅更适合手工 clone 到当前项目。这样变更范围清楚，也能锁定 commit：

mkdir -p .agents/skills
git clone https://github.com/Agents365-ai/drawio-skill.git \
  .agents/skills/drawio-skill
cd .agents/skills/drawio-skill
git rev-parse HEAD
less skills/drawio-skill/SKILL.md

重点看 allowed-tools、会读取的来源目录、联网图标与导出命令。不要让 importer 指向 home 目录或包含密钥的配置树。

3. 先运行不启动 GUI 的检查

cd .agents/skills/drawio-skill/skills/drawio-skill
python3 scripts/diagramctl.py doctor

官方说明 doctor 只有加 --probe 才启动 GUI 工具。先看 Python、draw.io 与可选依赖状态；若当前任务只需要 IR、query 或 test，没有 draw.io CLI 也能继续。

4. 第一次只生成一个小型 IR

cat > /tmp/demo.ir.json <<'JSON'
{
  "schema": "drawio-skill/diagram-ir/v1",
  "nodes": [
    {"id": "web", "label": "Web", "kind": "service"},
    {"id": "db", "label": "DB", "kind": "database"}
  ],
  "edges": [
    {"id": "web-db", "source": "web", "target": "db", "label": "query"}
  ]
}
JSON
python3 scripts/diagramctl.py build /tmp/demo.ir.json --from ir -o /tmp/demo.drawio
python3 scripts/validate.py /tmp/demo.drawio --score

验证边界：本站没有执行上面的 schema 示例，字段仍应以你锁定 commit 内的 references/diagram-ir.md 为准。本文只确认官方 CLI 形状，不把示例输出写成实测结果。

5. 同步时写到新文件

sync 通过稳定语义 ID 对齐旧图和新来源，目标是保留人工几何与样式。删除的来源元素默认留作待审，显式 --prune 才移除。即使如此，第一次也应输出到新文件：

python3 scripts/diagramctl.py sync architecture.drawio ./infra \
  --from terraform -o architecture.next.drawio
git diff --no-index architecture.drawio architecture.next.drawio

6. 静态架构结论要标注来源

工具可以检测循环、孤立节点、Internet 到数据库路径、owner、observability 与 trust boundary，也能模拟节点故障后的下游影响。但代码 importer 看不到所有反射、动态服务发现和真实流量。规则失败应当变成复核问题，不能直接写成生产事故事实。

python3 scripts/diagramctl.py test architecture.drawio --rules policy.yml
python3 scripts/diagramctl.py review architecture.drawio -o review.md
python3 scripts/diagramctl.py query architecture.drawio \
  --from internet --to orders-db

7. 导出后必须看图

先导出不嵌入 XML 的草稿 PNG，检查遮挡、裁切、断线、穿过节点的边和难读标签。最终需要可编辑 PNG 时再加 -e，并运行官方 repair 脚本。Linux headless、WSL2 和 macOS sandbox 的 Electron 行为不同，CLI 出错要按官方 troubleshooting 处理。

drawio -x -f png --width 2000 -o draft.png architecture.drawio
python3 scripts/validate.py architecture.drawio --score

AI/LLM logo 默认可能引用 unpkg CDN；离线文档要用 --embed。图标可显示不代表获得商标授权，仍要按品牌规范使用。

8. 同类对比：drawio-skill 与官方 drawio-mcp

相比 diagrams.net 官方的 jgraph/drawio-mcp，drawio-skill 把代码/IaC/SQL/API importer、Diagram IR、增量同步、架构规则、diff 和发布工具放在一个仓库中；官方方案由 diagrams.net 项目维护，并提供 MCP server 与 Claude Code plugin。只需生成和编辑 draw.io 时先看官方方案；确实需要来源追踪、同步和 CI 架构检查时再增加 drawio-skill。

这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。

先判断这个项目是否适合你

近期变化与关注原因

项目在 2026-09 将简单画图技能扩展为带版本化 Diagram IR、增量同步、架构规则、MCP 和可访问 Story 输出的工具链；当前 SKILL.md 标记 3.4.0，仓库约 9.6k stars。

采用建议

drawio-skill 可保留。它的自愿赞助链接没有形成付费功能门槛，仓库关注度高，但本站暂无搜索记录。使用时应按可执行代理插件管理：项目级安装、固定 commit、先读 SKILL.md、限制扫描路径；先交付 .drawio 和校验报告，再在 draw.io CLI 可用时导出图片。

原教程未展开的系统信息

核心功能

可编辑 Diagram IR
diagramctl 可从多种源码生成带稳定语义 ID、provenance 与属性的 IR，再输出 draw.io；同步时尽量保留人工布局与样式。
架构查询与检查
可执行路径查询、循环与耦合检查、失败传播、架构规则和 PR 差异；这些结论来自静态模型，不等于运行时观测。
多种导入与导出
支持 Python/JS/Go/Rust、Terraform、K8s、Compose、SQL、OpenAPI、AsyncAPI、Protobuf、GraphQL 与 CI；可转 PNG、SVG、PDF、PPTX、Mermaid、Markdown、动画和离线 HTML。
Agent Skill 与可选 MCP
可安装进 Codex、Claude Code、Cursor、Copilot 等兼容环境；MCP stdio server 将 doctor、build、sync、views、test、review 等工作流暴露为本地工具，不需要后台网络服务。

常见问题

drawio-skill 一定要安装 draw.io 桌面版吗？

核心 IR、同步、查询、规则检查和 Story 流程只需要 Python 3；要原生导出 PNG、SVG 或 PDF 时才需要 draw.io CLI。部分自动布局还会用到可选 Graphviz。

安装后会自动读取整个代码库吗？

技能具备 Bash 和文件读写能力，只有代理调用相应 importer 或命令时才会读取路径。建议装在项目级 skills 目录，先审阅 SKILL.md，并把扫描范围限制到明确目录。

sync 会删除我手工调整的布局吗？

官方设计用稳定语义 ID 对齐元素，更新关系和标签时保留匹配单元的几何与样式；移除项默认留下供审阅，只有显式 prune 才删除。仍应输出到新文件并先看 diff。

为什么 GitHub Release 与 SKILL.md 版本不一致？

Releases 页面最新可见包是 v1.28.2，但 main 分支的 SKILL.md 已标 3.4.0，CHANGELOG 也记录 3.x 功能。复现时固定 commit，并以该 commit 内的 SKILL.md 和 CHANGELOG 为准。

drawio-skill 和 Mermaid 应该怎么选？

需要在 Markdown 中自动渲染、文本 diff 清楚的简单图时选 Mermaid；需要精确样式、官方云图标、可编辑布局、源代码同步或多格式交付时选 drawio-skill。