drawio-skill

Draw.io 架构工作室

生成可编辑的 .drawio 文件，而不是扁平化图片。首选入口是 scripts/diagramctl.py，它通过共享的 Diagram IR，统一支持生成、增量 同步、多视图投影、语义查询/测试/审查、故障分析以及无障碍发布。

选择工作流

请求	路径
具有精确样式的自然语言图表	阅读 references/diagram-types.md，然后阅读 references/xml-authoring.md 并编写 XML
无特殊样式要求的标准流程图/思维导图/甘特图/时间线等	如果 draw.io >=30，阅读 references/mermaid-authoring.md 并将 Mermaid 转换为原生 .drawio
需要自动布局的大型图（约 15 个以上节点）	使用 autolayout.py；传入任何 --layout 值前，请阅读 references/autolayout.md
代码、Terraform、K8s、compose、SQL、OpenAPI、AsyncAPI 或 CI 源码	使用 diagramctl.py build；阅读 references/diagram-ir.md
Protocol Buffers 架构（.proto）	使用 protoimports.py 或 diagramctl.py build；阅读 references/toolbox.md
正在运行的集群/堆栈/云环境（实际状态，而非声明的配置）	阅读 references/live-infra.md，然后使用 tfstate.py、dockerimports.py 或 k8simports.py -
更新生成的图表，同时保留手动布局	使用 diagramctl.py sync；阅读 references/diagram-ir.md
高管/系统/部署/数据流/安全视图	使用 diagramctl.py views；阅读 references/diagram-ir.md
查询、架构策略、审查、假设分析或引导式讲解	阅读 references/semantic-workflows.md
MCP 宿主（Claude Desktop、Cursor、VS Code、Codex）需要调用这些工作流	注册 scripts/diagramctl_mcp.py；阅读 references/mcp.md
图表类型或语义工作流的提示词措辞	阅读 references/cookbook.md
在 GitHub Actions CI 中强制执行架构规则或进行视觉差异比较	阅读 references/ci-gate.md
作为 PR 审查评论的渲染前后对比/差异图片	使用 prdiff.py；阅读 references/pr-bot.md
将现有 .drawio 转换为 HTML/PPTX/Mermaid/Markdown/动画/运行手册	阅读 references/toolbox.md；diagramctl.py transform 可调用现有工具
绘制为地铁图的流水线、旅程或子系统地图	使用 tubemap.py；阅读 references/tubemap.md
形状、云服务商/厂商、AI 或 Databricks 图标	阅读 references/shapes.md 或 references/databricks.md；切勿猜测形状名称
学习/应用/管理视觉样式	阅读 references/style-presets.md
从现有图表或主题中提取可复用样式	阅读 references/style-extraction.md
将现有图片转换为可编辑图表（屏幕截图、白板照片、旧版 PNG）	阅读 references/derasterize.md
导出/平台问题	阅读 references/troubleshooting.md；如有访问/网络问题，请阅读 references/security.md

统一 CLI

在此技能目录下运行，或将 scripts/ 替换为此技能脚本目录的 绝对路径：

python3 scripts/diagramctl.py doctor
python3 scripts/diagramctl.py build model.json --from ir -o architecture.drawio
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 views architecture.ir.json \
  --views executive,system,deployment,dataflow,security -o views.drawio
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
python3 scripts/diagramctl.py whatif architecture.ir.json --fail kafka \
  --drawio kafka-failure.drawio -o impact.json
python3 scripts/diagramctl.py story architecture.ir.json -o walkthrough.html

除非传入 --probe，否则 doctor 不会启动 GUI 工具。核心语义 命令可离线运行，且仅依赖标准库。

创建工作流

1. 根据请求推断图表类型、受众、范围、输出格式和位置。只有缺失的选项会实质性影响结果时才询问；默认在工作目录中生成 PNG 和 .drawio。

2. 从上表中选择创作方式。对于数据驱动的图表，优先使用 Diagram IR 并保留溯源信息。对于大型图结构，使用导入器或 autolayout.py；不要手动放置超过约 15 个节点。

3. 按照 references/style-presets.md 中的说明，解析明确指定的样式预设或用户的默认预设。结构图表规范与视觉预设可以组合使用，但不能相互替代。

4. 生成 .drawio，然后运行结构验证：

   python3 scripts/validate.py diagram.drawio --score
   

   如果涉及语义元数据或架构策略，还要运行 diagramctl.py test。不要将推断出的语义结论描述为已验证的运行时事实。

5. 导出不含嵌入式 XML 的 PNG 草稿，并进行目视检查。修复明显的重叠、裁切、未连接的边、穿过节点的边、堆叠的边以及难以辨认的标签。自动视觉修复最多进行两轮。

6. 展示草稿并进行有针对性的修改。局部修改时保留现有几何布局。对于源数据支持的修改，使用 sync 并生成便于审阅的输出；只有在用户要求删除时才使用 --prune。

7. 获得批准后，生成所需的最终格式，并报告可编辑源文件和导出文件的路径。

导出不变量

解析一次可用的二进制文件（drawio、draw.io、macOS 应用程序路径或 Windows 可执行文件），并在整个运行过程中使用该二进制文件。

# Draft for visual inspection: never use -e here
drawio -x -f png --width 2000 -o diagram.png diagram.drawio

# Final editable PNG
drawio -x -f png -e -s 2 -o diagram.drawio.png diagram.drawio
python3 scripts/repair_png.py diagram.drawio.png

# Final editable SVG/PDF
drawio -x -f svg -e --embed-svg-images -o diagram.svg diagram.drawio
drawio -x -f pdf -e -o diagram.pdf diagram.drawio

不要同时使用 --width 和 -s。嵌入式 PNG 导出需要使用 repair_png.py；供视觉检查使用的 PNG 草稿不得使用 -e。在 Linux 无头环境中，按照 references/troubleshooting.md 操作，不要自行尝试 Electron 标志。如果 CLI 在 macOS 沙盒中崩溃，可尝试一次获得许可的提权运行，然后使用 encode_drawio_url.py 或交付 XML；不要反复启动它。

编辑与标识

• 使用稳定的语义 ID，且绝不重复使用保留 ID 0 或 1。
• 每条边都需要 <mxGeometry relative="1" as="geometry"/>。
• 对于局部编辑，只修改对应的单元格；对于全局方向变更，重新生成或重新布局页面。
• 除非用户另有要求，否则保留溯源信息、data-model-id、语义属性、手动设置的几何布局和样式。
• 合并时，默认将已删除的元素保留为便于审阅的淡化元素。
• 对于在边界处堆叠的边，运行 edgeports.py；如果边仍穿过无关形状，则添加路径点。没有仅通过 CLI 重设边路径且同时保留节点位置的方法。

质量与可信度

图表美观并不代表内容正确。优先采用有来源支持的关系，在有帮助时展示溯源信息，区分精确提取与 AI 推断，并将架构审查结果表述为提示。故事 HTML 必须保持自包含、支持键盘操作，并包含文本替代内容。切勿将机密信息放入节点属性或溯源信息中，因为它们会嵌入到输出中。

如需了解所有专用脚本和组合模式，请阅读 references/toolbox.md；只加载当前请求所需的参考资料。