drawio-skill | 把文字和真实系统变成可维护的 .drawio 图表

drawio-skill 是一个把自然语言、代码、基础设施配置和数据模型转换为可编辑 .drawio 图表的 Agent Skill。它不只生成一张扁平图片，而是围绕 Diagram IR（图表中间表示）组织语义、来源和几何布局，再提供增量同步、多视图投影、架构规则检查、依赖查询、故障模拟和离线讲解页。换句话说，它解决的是“图表如何持续维护和审查”，而不只是“如何画出第一版”。

本文依据仓库 main 分支、中文 README、安装/使用文档和 Release 信息在 2026 年 9 月 3 日核对。当前最新 Release 为 v3.2.0（2026 年 9 月 1 日），仓库主要语言为 Python，许可为 MIT；GitHub 页面当时约有 8,971 个 stars 和 631 个 forks。stars、版本和示例文件会变化，统计只代表本次核对快照。

先理解 Diagram IR：图的语义、来源和坐标分开保存

很多自动生成的架构图一旦手工移动节点，下一次重新生成就会把布局覆盖。drawio-skill 用版本化 Diagram IR 保存节点、关系、来源和几何信息，再将它们渲染为可编辑的 .drawio。这使同一份模型可以投影成 executive、system、deployment、dataflow、security 等不同视图，而不必为每张图重复维护一套节点。

diagramctl sync 是这套模型的关键入口：源代码或 Terraform/Kubernetes 配置变化后，它只更新变化的节点和关系，尽量保留手动坐标、样式和注释；删除项默认保留为可审查状态，而不是静默消失。团队可以把“源事实”和“设计判断”放在同一份可追踪的图表变更中。

从真实来源构建图，而不是手动摆满方框

仓库提供多种 importer 和确定性布局脚本：

Python、JavaScript/TypeScript、Go、Rust 的导入关系图，以及 Python 类继承层级。
Terraform、Kubernetes manifest、docker-compose 和实时的 Terraform state、Docker inspect、kubectl JSON，生成带引用关系的基础设施图。
SQL DDL 生成带 PK/FK 标记的 ER 图，OpenAPI/Swagger 生成按 HTTP 方法着色的 API 与 schema 图，CI 配置生成带 needs: 依赖的流水线 DAG。
确定性时序图、C4 多页下钻、ML/深度学习图、SysML、BPMN、网络拓扑和跨职能泳道图。

这些入口的共同点是先提取结构，再自动布局，最后导出原生图表。它们不会替你判断业务关系是否正确：importer 只能对输入文件中能读出的节点和引用负责，架构含义、边界和 owner 仍应由团队复核。

从生成到自检：图表也可以像代码一样被测试

统一 CLI scripts/diagramctl.py 串起 doctor、build、sync、views、test、review、query、whatif、story、publish 和 transform。典型的语义流程可以写成：

python3 scripts/diagramctl.py build ./infra --from terraform --group --ir-output architecture.ir.json -o architecture.drawio
python3 scripts/diagramctl.py sync architecture.drawio ./infra --from terraform -o architecture.next.drawio
python3 scripts/diagramctl.py test architecture.drawio --rules policy.yml

Diagram-as-Test 用 YAML/JSON 规则检查直连数据库、循环依赖、孤立节点、owner、生产可观测性、外部超时、信任边界协议和颜色对比度等契约；review 生成 Markdown 审查报告，query 可以查询组件、边界和调用路径，whatif 则把某个节点失效后的影响范围输出为高亮图和 JSON。这里的“测试”是对图表模型和规则的确定性检查，不等于对线上系统执行压测或故障演练。

drawio-skill 从检查依赖到最终导出的工作流程图 — drawio-skill 官方仓库中的工作流程图：检查依赖、规划图表、生成 .drawio XML、导出草稿 PNG、自检与反馈，再完成最终导出。来源：https://github.com/Agents365-ai/drawio-skill/blob/main/assets/workflow-cn.png

MCP、Story Mode 与多种输出，让图进入协作环节

内置 scripts/diagramctl_mcp.py 可向 Claude Desktop、Cursor、VS Code、Codex 等 MCP host 暴露 9 个工具：doctor、build、sync、views、architecture_test、review、query、whatif 和 story。README 标注该服务使用 Python 标准库、默认离线，不要求额外安装 mcp 包；宿主仍需按各自 MCP 配置方式注册脚本。

story 会生成自包含的离线 HTML 讲解页，支持键盘操作、文本替代、来源信息和多语言切换；drawiohtml.py 可以把图表变成带页签、平移、缩放、搜索和 C4 下钻链接的单文件查看器。除此之外，仓库还提供 PNG、SVG、PDF、PowerPoint、Mermaid 文本和 SVG 流动动画等转换脚本，便于把同一模型放进 README、评审、汇报和培训材料。

布局、形状和样式：自动化不等于随机配色

自动布局主要依赖 Graphviz；内置样式预设包括 default、corporate、handdrawn、colorblind-safe 和 dark，也能从既有 .drawio 文件或图片提取配色、字体、形状和连线风格。仓库的 shapesearch.py 可在 10,000+ 个官方 draw.io 形状中检索精确 style，避免手写错误的 shape= 字符串；aiicons.py 还补充了 AI/LLM 与数据存储品牌图标。

依赖边界需要单独看待：核心语义命令只需要 Python 3 并默认离线；Graphviz 是自动布局的可选依赖；要进行原生 PNG/SVG/PDF 导出或使用 Mermaid → 原生 .drawio 转换，需要安装 draw.io 桌面版 CLI，README 推荐使用 30 或更高版本。没有安装这些可选组件时，不能把“能生成 XML”写成“已经完成桌面渲染”。

安装与一次典型工作流

技能本身可以通过 Agent Skills 目录安装：

npx skills add Agents365-ai/365-skills -g

也可以手动把仓库克隆到对应的 skills 目录，例如 Codex 常用的 ~/.agents/skills/drawio-skill。如果需要本地导出，按操作系统安装 draw.io 桌面版；macOS 可使用 Homebrew，Windows 和 Linux 则从 draw.io desktop 的官方 Release 获取对应安装包。安装后可先运行：

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

建议的实际顺序是：先检查 Python、draw.io 和 Graphviz 能力；根据自然语言、代码或 IaC 选择 importer；生成 Diagram IR 和 .drawio；运行 validate.py --score 或 diagramctl test；导出草稿 PNG 检查重叠、截断标签和连线；确认后再输出最终 PNG/SVG/PDF。本文没有在本机安装 draw.io 或执行上述命令，不把它们写成实测成功结果。

把架构规则放进 GitHub Actions

仓库内置的 drawio-architecture-test 是一个纯 Python 的 composite GitHub Action，可以在每个 Pull Request 上对 Diagram IR 执行架构契约检查，不需要安装 draw.io、Xvfb 或 Graphviz；另有 drawio-diff action，对 PR 中变更的 .drawio 渲染 base/head/diff PNG 并生成 Markdown 报告。典型引用形式为：

uses: Agents365-ai/drawio-skill/.github/actions/drawio-architecture-test@main

CI 中仍应把源文件、规则文件和生成结果的职责分开：Action 能发现图表契约或结构变化，但不能替团队决定某条依赖是否符合业务意图。对于 draw.io 桌面版无头渲染，README 还提醒要在 -e PNG 导出后运行 repair_png.py，以修复 CLI 可能截断的 IEND chunk。

许可、图标来源和适用边界

drawio-skill 仓库以 MIT License 发布，代码和在该许可范围内的内容可按许可证使用、修改和再分发。仓库还引用了 lobe-icons（MIT）和 simple-icons（CC0）等图标来源；这些来源的许可证与 draw.io 桌面版、你自己的业务素材和第三方品牌商标并不自动合并。将官方云厂商或 AI 品牌图标用于文档时，仍应遵守相应商标和再分发要求。

它适合需要可编辑架构图、代码/IaC 可追踪图表、CI 架构门禁、C4 下钻或离线讲解页的团队；如果只是想在 Markdown 中维护轻量 diagrams-as-code，Mermaid 或 PlantUML 可能更直接。如果目标是实时监控、线上拓扑发现或自动修复生产故障，drawio-skill 只能提供图表建模和审查辅助，不能代替监控、配置管理和运维系统。