---

name: drawio-skill
version: 1.5.2
description: 当用户请求绘制图表、流程图、架构图、ER图、UML/时序/类图、网络拓扑图、ML/DL模型图（Transformer/CNN/LSTM）、思维导图或任何可视化内容时使用。也可在解释包含3个以上组件、复杂数据流或受益于可视化展示的关系时主动使用。最适合需要自定义样式、丰富形状词汇、泳道或可导出图片(PNG/SVG/PDF/JPG)的图表场景。生成 .drawio XML 文件并通过本地 draw.io 桌面应用 CLI 导出。
license: MIT
homepage: https://github.com/Agents365-ai/drawio-skill
compatibility: 需要 draw.io 桌面应用 CLI 在 PATH 环境变量中（macOS/Linux/Windows）。自查步骤需要支持视觉能力的模型（如 Claude Sonnet/Opus）；若不可用则优雅跳过。
platforms: [macos, linux, windows]
metadata: {“openclaw”:{“requires”:{“anyBins”:[“draw.io”,“drawio”]},“emoji”:“📐”,“os”:[“darwin”,“linux”,“win32”],“install”:[{“id”:“brew-drawio”,“kind”:“brew”,“formula”:“drawio”,“bins”:[“draw.io”],“label”:“Install draw.io via Homebrew”,“os”:[“darwin”]}]},“hermes”:{“tags”:[“drawio”,“diagram”,“flowchart”,“architecture”,“visualization”,“uml”],“category”:“design”,“requires_tools”:[“draw.io”],“related_skills”:[“mermaid”,“excalidraw”,“plantuml”]},“author”:“Agents365-ai”,“version”:“1.5.2”}

Draw.io 图表

概述

生成 .drawio XML 文件并本地导出为 PNG/SVG/PDF/JPG，使用原生 draw.io 桌面应用 CLI。

支持的格式： PNG、SVG、PDF、JPG — 无需浏览器自动化。

PNG、SVG 和 PDF 导出支持 --embed-diagram（-e）—— 导出的文件包含完整的图表 XML，因此在 draw.io 中打开它可以恢复可编辑的图表。使用双扩展名（name.drawio.png）表示内嵌了 XML。

附带资源

当工作流引用以下文件时，按需读取——这些文件无需预先加载到上下文中。

文件	何时读取
references/diagram-types.md	用户指定了特定图表类型（ERD、UML 类图、时序图、架构图、ML/DL、流程图）
references/style-presets.md	用户要求学习/保存/列出/设为默认/删除样式预设，或您已解析出活动预设并需要应用规则
references/style-extraction.md	您在学习流程中，需要提取步骤（从 style-presets.md 调用）
references/troubleshooting.md	导出失败、视觉检查拒绝 PNG、或渲染效果异常
scripts/repair_png.py	每次 -e PNG 导出后——修复 draw.io 截断的 IEND chunk（问题 #8）
scripts/encode_drawio_url.py	CLI 不可用，需要浏览器回退的 diagrams.net URL

前提条件

必须安装 draw.io 桌面应用且 CLI 可访问：

macOS 沙盒/沙盒隔离说明（例如 codex.app）： 在某些沙盒化的 macOS 环境中，调用 draw.io 桌面 CLI（即使是 draw.io --version）可能导致 draw.io 进程崩溃或无输出。如果发生这种情况，请将 CLI 视为在此沙盒隔离中不可用——不要在沙盒内反复重试。对于任何 CLI 导出工作，优先使用非沙盒化的主机环境（沙盒隔离之外），或使用浏览器回退/仅 XML 输出。

# macOS (Homebrew — 推荐；CLI 二进制文件为 `drawio`，不是 `draw.io`)
brew install --cask drawio
drawio --version

# macOS (完整路径，如果不在 PATH 中)
/Applications/draw.io.app/Contents/MacOS/draw.io --version

# Windows
"C:\Program Files\draw.io\draw.io.exe" --version

# Linux
draw.io --version

如果缺少 draw.io 桌面版，请安装：

• macOS：brew install --cask drawio 或从 https://github.com/jgraph/drawio-desktop/releases 下载
• Windows：从 https://github.com/jgraph/drawio-desktop/releases 下载安装程序
• Linux：从 https://github.com/jgraph/drawio-desktop/releases 下载 .deb/.rpm — 不要使用 snap（AppArmor 沙盒会拒绝服务器上的 secrets/keyring，导致崩溃）

工作流

在开始工作流之前，评估用户的请求是否足够具体。如果缺少关键细节，请提出 1-3 个有针对性的问题：

• 图表类型 — 哪种预设？（ERD、UML、时序图、架构图、ML/DL、流程图或通用）
• 输出格式 — PNG（默认）、SVG、PDF 或 JPG？
• 输出位置 — 默认为用户的工作目录；遵守用户指定的任何显式路径（例如"放在 ./artifacts/"）。如果用户未提及，不要询问。
• 范围/精度 — 包含多少组件？是否有特定技术或标签？

如果请求已包含这些细节，或明显很简单（例如"画一个 X 的流程图"），则跳过澄清。

步骤 0 — 解析活动预设。 确定哪个（如果有的话）用户定义的样式预设适用于本次生成。

• 扫描用户的消息，查找明确命名样式预设的短语：“use my <name> style”、“with my <name> style”、“in <name> mode”、“in the style of <name>”。单独的 with <name> 不算——"draw a diagram with redis"指的是组件而非样式。如果找到明确匹配 → 活动预设 = <name>。
• 否则，检查 ~/.drawio-skill/styles/ 中是否有任何文件包含 "default": true。如果找到 → 活动预设 = 该文件。
• 否则 → 无活动预设；工作流其余部分回退到内置颜色/形状/边线约定。

从 ~/.drawio-skill/styles/<name>.json 加载预设 JSON，回退到 <this-skill-dir>/styles/built-in/<name>.json。如果命名的预设在这两个位置都不存在，告知用户名称未知，列出可用预设（用户目录 + 内置），然后停止——不要静默回退到默认值。

当预设加载成功时，在回复的第一行提及：“使用预设 <name>（置信度：<level>）。” 关于预设如何改变颜色/形状/边线/字体决策，请参见下面的 应用预设 小节。

1. 检查依赖 — 验证 draw.io --version 执行成功；记录平台以使用正确的 CLI 路径
2. 规划 — 确定形状、关系、布局（LR 或 TB），按层级/层分组
3. 生成 — 将 .drawio XML 文件写入磁盘。默认输出目录为用户的工作目录；如果用户指定了输出路径或目录（例如 ./artifacts/、docs/images/），则使用该路径——先 mkdir -p 创建目标目录。将相同的目录选择应用于步骤 4 和步骤 7 中的 PNG/SVG/PDF 导出。
4. 导出草稿 — 运行 CLI 生成预览 PNG。此步骤不要传递 -e——它添加的内嵌 zTXt mxGraphModel chunk 会导致视觉 API（包括 Claude）在步骤 5 中返回 400 “Could not process image”。将干净的预览保存为 <name>.png（单扩展名）。嵌入仅用于最终导出（步骤 7）。
5. 自查 — 使用代理的内置视觉能力读取导出的 PNG，捕捉明显问题，在展示给用户之前自动修复（需要支持视觉能力的模型，如 Claude Sonnet/Opus）。如果读取 PNG 返回 400 / “Could not process image” 错误，几乎肯定您错误地使用了 -e 导出——重新导出时不带 -e 并重试一次。如果仍然失败，跳过自查并继续执行步骤 6。
6. 审查循环 — 向用户展示图片，收集反馈，应用有针对性的 XML 编辑，重新导出，重复直到获得批准
7. 最终导出 — 将批准版本重新导出为所有请求的格式。在此使用 -e（PNG/SVG/PDF）以使交付物在 draw.io 中保持可编辑；保存为 <name>.drawio.png 以表示内嵌 XML。对于带 -e 的 PNG，立即运行 python3 <this-skill-dir>/scripts/repair_png.py <name>.drawio.png——draw.io 的 CLI 在 -e PNG 输出中截断了 IEND chunk（缺少 8 字节），生成的文件损坏，视觉 API 和严格的 PNG 解码器会拒绝（问题 #8）。报告文件路径。

如果 draw.io --version 崩溃或无输出（在受限的 macOS 沙盒隔离（如 codex.app）中常见）：

• 不要在沙盒内反复重试 CLI 调用。
• 跳过步骤 4、5、6 和 7（CLI 导出 + 基于 PNG 的审查），使用浏览器回退（scripts/encode_drawio_url.py）或仅交付 .drawio XML。
• 如果用户需要 PNG/SVG/PDF 输出，请要求他们在非沙盒化的主机环境（沙盒隔离之外）中运行导出命令，并分享生成的文件。

升级规则：

• 如果二进制文件存在于 PATH（或已知的应用路径存在）但执行失败，出现异常退出、空输出、Electron 启动失败、显示/会话错误或疑似沙盒限制，优先进行一次升级重试，然后再回退。
• 如果二进制文件完全缺失，不要升级以更激进地搜索；直接转到安装指南或回退方案。

步骤 5：自查

导出草稿 PNG 后，使用代理的视觉能力（例如 Claude 的图像输入）读取图像并在展示给用户之前检查以下问题。如果代理不支持视觉，跳过自查并直接展示 PNG。

重要： 此步骤读取的草稿 PNG 必须是在不带 -e 的情况下导出的。Draw.io 的 -e 标志会发出一个 PNG，其 IEND chunk 被截断（缺少 8 字节的类型+CRC），Anthropic 视觉 API 会以 400 “Could not process image” 拒绝（问题 #8）。预览步骤最简单的修复是完全跳过 -e；步骤 7 中的最终导出保留 -e 并运行修复脚本。如果您在此处看到 400 错误，重新导出时不带 -e 并重试一次；如果仍然失败（其他任何原因），跳过自查并继续执行步骤 6。

检查项	检查内容	自动修复操作
形状重叠	两个或多个形状堆叠在一起	将形状移开 ≥200px
标签被裁剪	文本在形状边界处被截断	增加形状宽度/高度以适应标签
连接缺失	箭头未视觉连接到形状	验证 source/target id 是否匹配现有单元格
画布外形状	形状位于负坐标或远离主群组	移动到群集附近的正坐标
边线-形状重叠	边线/箭头视觉上穿过不相关的形状	添加路径点（<Array as="points">）以绕开形状，或增加形状之间的间距
边线堆叠	多条边线在同一条路径上相互重叠	在形状周边分散入口/出口点（使用不同的 exitX/entryX 值）

• 最多 2 轮自查 — 如果 2 次修复后问题仍然存在，仍向用户展示
• 每次修复后重新导出并重新读取新的 PNG

步骤 6：审查循环

自查后，展示导出的图片并向用户征求反馈。

针对性编辑规则 — 针对每种反馈类型，应用最小化的 XML 更改：

用户请求	XML 编辑操作
更改 X 的颜色	通过 value 匹配 X 找到 mxCell，更新 style 中的 fillColor/strokeColor
添加新节点	追加一个新的 mxCell 顶点，使用下一个可用 id，放置在相关节点附近
删除节点	删除 mxCell 顶点以及所有 source/target 匹配的边线
移动形状 X	更新匹配 mxCell 的 mxGeometry 中的 x/y
调整形状 X 大小	更新匹配 mxCell 的 mxGeometry 中的 width/height
从 A 到 B 添加箭头	追加一个新的 mxCell 边线，其 source/target 匹配 A 和 B 的 id
更改标签文本	更新匹配 mxCell 的 value 属性
更改布局方向	完全重新生成 — 使用新方向重建 XML

规则：

• 对于单个元素的更改：原地编辑现有 XML — 保留先前迭代的布局调整
• 对于布局范围的更改（例如交换 LR↔TB、“重新开始”）：重新生成完整 XML
• 每次迭代覆盖同一个 {name}.png（不带 -e）——不要创建 v1、v2、v3 文件。-e 保留给步骤 7 中的最终导出。
• 应用编辑后，重新导出并展示更新后的图片
• 循环持续进行，直到用户表示已批准/完成/LGTM
• 安全阀： 经过 5 轮迭代后，建议用户在 draw.io 桌面版中打开 .drawio 文件进行精细调整

步骤 7：最终导出

用户批准后：

• 导出为所有请求的格式（PNG、SVG、PDF、JPG）— 如果未指定，默认为 PNG
• 报告 .drawio 源文件和导出的图片文件的路径
• 自动打开： 提供在 draw.io 桌面版中打开 .drawio 文件进行微调的选项 — open diagram.drawio（macOS）、xdg-open（Linux）、start（Windows）
• 确认文件已保存并可供使用

样式预设

样式预设是一个命名的 JSON 文件，捕获用户的视觉偏好（调色板、形状、字体、边线）。激活时，它完全替换本技能中的内置颜色/形状约定。

当 SKILL.md 的步骤 0.5 解析预设名称时的查找顺序：

1. ~/.drawio-skill/styles/<name>.json — 用户预设（git pull 后仍保留）
2. <this-skill-dir>/styles/built-in/<name>.json — 随附的内置预设（default、corporate、handdrawn）

在任何文件操作之前，始终将用户提供的名称转换为小写——模式强制要求小写。

关于其他所有内容——学习流程（从文件中提取预设）、管理操作（列出/设为默认/删除/重命名）、应用规则（颜色查找、形状关键词、边线、字体、附加项、与图表类型预设的交互）以及验证——请阅读 references/style-presets.md。 仅在用户调用这些流程或需要将活动预设应用于当前生成时才需要读取。

Draw.io XML 结构

文件骨架

<?xml version="1.0" encoding="UTF-8"?>
<mxfile host="drawio" version="26.0.0">
  <diagram name="Page-1">
    <mxGraphModel>
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <!-- user shapes start at id="2" -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

规则：

• id="0" 和 id="1" 是必需的根单元格——切勿省略
• 用户形状从 id="2" 开始并顺序递增
• 所有形状都有 parent="1"（除非在容器内部——此时使用容器的 id）
• 所有文本在 style 中使用 html=1 以确保正确渲染
• 切勿在 XML 注释中使用 --——这在 XML 规范中是不合法的，会导致解析错误
• 在属性值中转义特殊字符：&、<、>、"
• 标签中的多行文本： 在 value 属性中使用 
 表示换行（不要使用字面量 \n）。示例：value="Line 1
Line 2"

形状类型（顶点）

样式关键字	用途
rounded=0	普通矩形（默认）
rounded=1	圆角矩形 — 服务、模块
ellipse;	圆形/椭圆形 — 起点/终点、数据库
rhombus;	菱形 — 决策点
shape=mxgraph.aws4.resourceIcon;	AWS 图标
shape=cylinder3;	圆柱体 — 数据库
swimlane;	带标题栏的组/容器

必需属性

<!-- Rectangle / rounded box -->
<mxCell id="2" value="Label" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="160" height="60" as="geometry" />
</mxCell>

<!-- Cylinder (database) -->
<mxCell id="3" value="DB" style="shape=cylinder3;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;" vertex="1" parent="1">
  <mxGeometry x="350" y="100" width="120" height="80" as="geometry" />
</mxCell>

<!-- Diamond (decision) -->
<mxCell id="4" value="Check?" style="rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;" vertex="1" parent="1">
  <mxGeometry x="100" y="220" width="160" height="80" as="geometry" />
</mxCell>

容器和分组

对于包含嵌套元素的架构图，使用 draw.io 的父子包含关系——不要仅将形状放置在更大的形状之上。

类型	样式	何时使用
组（不可见）	group;pointerEvents=0;	不需要视觉边框，容器没有连接
泳道（带标题）	swimlane;startSize=30;	容器需要可见标题栏，或容器本身有连接
自定义容器	向任意形状添加 container=1;pointerEvents=0;	任何作为容器但没有自身连接的形状

关键规则：

• 向不应捕获子元素之间连接的容器样式添加 pointerEvents=0;
• 子元素设置 parent="containerId" 并使用相对于容器的坐标

<!-- Swimlane container -->
<mxCell id="svc1" value="User Service" style="swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="300" height="200" as="geometry"/>
</mxCell>
<!-- Child inside container — coordinates relative to parent -->
<mxCell id="api1" value="REST API" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="svc1">
  <mxGeometry x="20" y="40" width="120" height="60" as="geometry"/>
</mxCell>
<mxCell id="db1" value="Database" style="shape=cylinder3;whiteSpace=wrap;html=1;" vertex="1" parent="svc1">
  <mxGeometry x="160" y="40" width="120" height="60" as="geometry"/>
</mxCell>

连接器（边线）

关键： 每条边线 mxCell 必须包含一个 <mxGeometry relative="1" as="geometry" /> 子元素。自闭合的边线单元格（<mxCell ... edge="1" ... />）是无效的，不会渲染。始终使用展开形式。

<!-- Directed arrow — always include rounded, orthogonalLoop, jettySize for clean routing -->
<mxCell id="10" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="2" target="3">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

<!-- Arrow with label + explicit entry/exit points to control direction -->
<mxCell id="11" value="HTTP/REST" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="1" source="2" target="4">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

<!-- Arrow with waypoints — use when edge must route around other shapes -->
<mxCell id="12" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="3" target="5">
  <mxGeometry relative="1" as="geometry">
    <Array as="points">
      <mxPoint x="500" y="50" />
    </Array>
  </mxGeometry>
</mxCell>

边线样式规则：

• 动画连接器： 向任意边线样式添加 flowAnimation=1; 以显示沿箭头的移动圆点动画。适用于 SVG 导出和 draw.io 桌面版——非常适合数据流和管道图。示例：style="edgeStyle=orthogonalEdgeStyle;flowAnimation=1;rounded=1;..."
• 始终包含 rounded=1;orthogonalLoop=1;jettySize=auto——这些启用智能路由，避免重叠
• 当节点有 2 个以上连接时，在每条边线上固定 exitX/exitY/entryX/entryY——在形状周边分散线条
• 当边线必须绕过一个中间形状时，添加 <Array as="points"> 路径点
• 为箭头留出空间： 最后一个拐弯和目标形状之间的最终直线段必须 ≥20px 长。如果太短，箭头会与拐弯重叠，看起来不完整。通过增加节点间距或添加显式路径点来修复

在形状上分配连接

当多条边线连接到同一形状时，分配不同的入口/出口点以防止堆叠：

位置	exitX/entryX	exitY/entryY	何时使用
顶部居中	0.5	0	连接到上方的节点
顶部左侧	0.25	0	从顶部起的第 2 条连接
顶部右侧	0.75	0	从顶部起的第 3 条连接
右侧居中	1	0.5	连接到右侧的节点
底部居中	0.5	1	连接到下方的节点
左侧居中	0	0.5	连接到左侧的节点

规则： 如果一个形状在一侧有 N 条连接，请均匀分布（例如，底部有 3 条连接 → exitX = 0.25、0.5、0.75）

调色板（fillColor / strokeColor）

仅在没有活动预设时使用（请参见上面的"应用预设"）。

颜色名称	fillColor	strokeColor	用途
蓝色	#dae8fc	#6c8ebf	服务、客户端
绿色	#d5e8d4	#82b366	成功、数据库
黄色	#fff2cc	#d6b656	队列、决策
橙色	#ffe6cc	#d79b00	网关、API
红色/粉色	#f8cecc	#b85450	错误、告警
灰色	#f5f5f5	#666666	外部/中性
紫色	#e1d5e7	#9673a6	安全、认证

布局技巧

间距——随复杂度变化：

图表复杂度	节点数	水平间距	垂直间距
简单	≤5	200px	150px
中等	6–10	280px	200px
复杂	>10	350px	250px

路由通道： 在形状行/列之间，留出约 80px 的空通道，让边线可以在不穿过形状的情况下路由。切勿在边线需要穿过的间隙中放置形状。

网格对齐： 将所有 x、y、width、height 值对齐到 10 的倍数——这确保形状在 draw.io 的默认网格上整齐对齐，并使手动编辑更容易。

通用规则：

• 在分配 x/y 坐标之前先规划网格——先在纸上或脑海中草拟节点位置
• 将相关节点分组到同一水平或垂直带中
• 使用 swimlane 单元格进行带有可见边界的逻辑分组
• 将高度连接的"枢纽"节点放在中央，使边线向外辐射而非交叉
• 要强制直线垂直连接，在边线上显式固定入口/出口点：
  exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0
• 始终将子节点与其父节点中心对齐（相同的中心 x）以避免对角线路由
• 事件总线模式： 将 Kafka/总线节点放在服务行的中央，而不是下方——两侧的服务可以使用短的水平箭头（左侧 exitX=1，右侧 exitX=0）到达它，消除所有线条交叉
• 水平连接（exitX=1 或 exitX=0）永远不会穿过同一行的垂直节点；用于点对点和发布连接

避免边线-形状重叠：

• 在确定坐标之前，在脑海中追踪每条边线路径——如果它必须穿过不相关的形状，要么移动该形状，要么添加路径点
• 对于树形/层次化布局：将节点分配到层（行），仅连接相邻层以最小化交叉
• 对于星形/枢纽布局：将枢纽放在中心，卫星围绕它——边线保持短且呈放射状
• 当边线必须跨越多个行/列时，沿外部通道路由，而不是穿过图表中间

导出

命令

有两种导出模式：

• 预览/自查（工作流的步骤 4）— 不带 -e。输出 diagram.png。视觉自查必需；在此使用 -e 会触发视觉 API 返回 400 “Could not process image” 错误（问题 #8）。
• 最终/交付（步骤 7）— 传递 -e。输出 diagram.drawio.png。内嵌的 XML 使文件在 draw.io 中保持可编辑。

# Preview PNG (use this in step 4, before self-check) — NO -e
draw.io -x -f png -s 2 -o diagram.png input.drawio

# Final PNG (step 7, after user approval) — WITH -e, double extension
draw.io -x -f png -e -s 2 -o diagram.drawio.png input.drawio

# macOS — full path (if not in PATH); preview / final variants
/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png -s 2 -o diagram.png input.drawio
/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png -e -s 2 -o diagram.drawio.png input.drawio

# Windows
"C:\Program Files\draw.io\draw.io.exe" -x -f png -e -s 2 -o diagram.drawio.png input.drawio

# Linux (headless — requires xvfb-run; on servers add HOME and --disable-gpu)
export HOME=${HOME:-/tmp}
xvfb-run -a --server-args="-screen 0 1280x1024x24" \
  draw.io -x -f png -e -s 2 -o diagram.drawio.png input.drawio --disable-gpu
# Running as root (CI / Docker)? Append --no-sandbox AT THE END (placing it earlier makes drawio treat it as the input filename)

# SVG export (final — -e is safe; SVG is text)
draw.io -x -f svg -e -o diagram.svg input.drawio

# PDF export (final)
draw.io -x -f pdf -e -o diagram.pdf input.drawio

# Custom output directory (e.g. CI artifacts dir) — create if missing, then export there
mkdir -p ./artifacts && draw.io -x -f png -e -s 2 -o ./artifacts/diagram.drawio.png input.drawio

导出后 PNG 修复（在 -e PNG 导出后必需）

draw.io CLI 在生成 -e PNG 时截断 IEND chunk——文件以 4 字节的 IEND 长度字段结尾，但缺少 IEND 类型 + CRC（8 字节）。结果：视觉 API 返回 400 “Could not process image”，严格的 PNG 解码器也会报错。SVG/PDF 不受影响。

每次 -e PNG 导出后立即运行：

python3 <this-skill-dir>/scripts/repair_png.py diagram.drawio.png

该脚本的 endswith(IEND) 保护机制使其在 draw.io 上游修复该 bug 后变为空操作——可无条件安全运行。

关键标志：

• -x — 导出模式（必需）
• -f — 格式：png、svg、pdf、jpg
• -e — 在输出中嵌入图表 XML（PNG、SVG、PDF）——导出的文件在 draw.io 中保持可编辑。在步骤 5 自查中使用的预览 PNG 跳过此项——-e PNG 具有截断的 IEND chunk，视觉 API 会拒绝（问题 #8）。对于最终 PNG 导出，保留 -e 并运行 scripts/repair_png.py（参见导出后 PNG 修复）。SVG/PDF 不受影响。
• -s — 缩放比例：1、2、3（PNG 推荐 2）
• -o — 输出文件路径；接受任何目录（例如 ./artifacts/diagram.drawio.png）——先 mkdir -p 创建目标目录。嵌入时使用 .drawio.png 双扩展名。
• -b — 图表周围的边框宽度（默认：0，建议 10）
• -t — 透明背景（仅 PNG）
• --page-index 0 — 导出特定页面（默认：所有页面）

浏览器回退（无需 CLI）

当 draw.io 桌面 CLI 不可用时，生成客户端查看器 URL：

python3 <this-skill-dir>/scripts/encode_drawio_url.py input.drawio

输出一个 https://viewer.diagrams.net/... URL，图表 XML 经 deflate 压缩和 base64 编码后放入 URL 片段中。片段（# 之后的内容）永远不会发送到服务器，因此不会上传任何内容——图表在客户端打开以供查看和编辑。当用户无法安装桌面应用时非常有用。

回退链

当工具不可用时，优雅降级：

场景	行为
draw.io CLI 不可用，Python 可用	使用浏览器回退（diagrams.net URL）
draw.io CLI 不可用，Python 不可用	仅生成 .drawio XML；指导用户在 draw.io 桌面版或 diagrams.net 中手动打开
draw.io CLI 在 macOS 沙盒隔离中崩溃/无输出	在沙盒内将 CLI 视为不可用；使用浏览器回退/仅 XML；要求用户在非沙盒化的主机环境中运行 CLI 导出
视觉能力不可用于自查	跳过自查（步骤 5）；直接向用户展示导出的 PNG
导出失败（Chromium/显示问题）	在 Linux 上，使用 xvfb-run -a 重试；如果仍然失败，交付 .drawio XML 并建议手动导出
在 Linux 服务器（无图形界面）上导出失败	按顺序尝试：(1) xvfb-run -a，(2) 如果是 root 用户，在最后附加 --no-sandbox，(3) 添加 --disable-gpu，(4) export HOME=/tmp，(5) 安装 apt 依赖包（libgtk-3-0 libnotify4 libnss3 libgbm1 libasound2t64 等），(6) 回退到 tomkludy/drawio-renderer Docker（用于无图形界面导出的 REST API）

检查 draw.io 是否在 PATH 中

# Try short command first
if command -v draw.io &>/dev/null; then
  DRAWIO="draw.io"
elif [ -f "/Applications/draw.io.app/Contents/MacOS/draw.io" ]; then
  DRAWIO="/Applications/draw.io.app/Contents/MacOS/draw.io"
else
  echo "draw.io not found — install from https://github.com/jgraph/drawio-desktop/releases"
fi

常见错误

当某些内容看起来异常时（导出失败、视觉检查拒绝 PNG、布局损坏、边线路由错误），请参阅 references/troubleshooting.md 中的逐行错误→修复表。

图表类型预设

当用户请求特定的图表类型时，请阅读 references/diagram-types.md 以获取匹配的预设（形状、边线、布局方向）。根据用户的措辞选择：

用户说	references/diagram-types.md 中的章节
“ER diagram”、“schema diagram”、“data model”	ERD
“UML class diagram”、“class diagram”	UML Class
“sequence diagram”、“interaction diagram”、“lifeline”	Sequence
“architecture”、“system diagram”、“service diagram”	Architecture
“neural network”、“model architecture”、“ML diagram”、“deep learning”	ML / Deep Learning Model
“flowchart”、“decision tree”、“process flow”	Flowchart

图表类型预设设置结构性的样式关键字。如果用户样式预设也处于活动状态（请参见 ## 样式预设），保留结构性关键字并在其上叠加颜色/字体/边线/附加项——关于合并规则，请阅读 references/style-presets.md → “Interaction with diagram-type presets”。