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
GraphQL SDL 架构（.graphql/.gql）或 introspection JSON	使用 graphqlerd.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 草稿并进行视觉检查。修复明显的重叠、裁切、断开的边、穿过节点的边、堆叠的边和难以辨认的标签。自动视觉修复最多进行两轮。如果无法使用 drawio 二进制文件，或视觉检查无法得出结论，则直接检查渲染器自身的 DOM（在查看器 URL 上使用 --dump-dom，参见 references/troubleshooting.md）：直接读取每条边的 <path> 线段和标签锚点坐标——仅靠视觉检查既会漏掉几何缺陷，也会凭空臆造缺陷。

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；只加载当前请求所需的任务专用参考资料。