drawio-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Draw.io Diagrams

Draw.io 图表

Overview

概述

Generate

.drawio

XML files and export to PNG/SVG/PDF/JPG locally using the native draw.io desktop app CLI.

Supported formats: PNG, SVG, PDF, JPG — no browser automation needed.

PNG, SVG, and PDF exports support

--embed-diagram

(

-e

) — the exported file contains the full diagram XML, so opening it in draw.io recovers the editable diagram. Use double extensions (

name.drawio.png

) to signal embedded XML.

借助原生draw.io桌面应用CLI生成

.drawio

XML文件，并在本地导出为PNG/SVG/PDF/JPG格式。

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

PNG、SVG和PDF导出支持

--embed-diagram

（

-e

）参数 — 导出文件包含完整的图表XML，因此在draw.io中打开时可恢复可编辑的图表。使用双重扩展名（如

name.drawio.png

）来标识嵌入了XML的文件。

Bundled resources

捆绑资源

When the workflow references one of these, read it on demand — none of them need to be in context up front.

File	Read it when
`references/diagram-types.md`	The user names a specific diagram type (ERD, UML class, sequence, architecture, ML/DL, flowchart)
`references/style-presets.md`	The user asks to learn / save / list / set-default / delete a style preset, or you've resolved an active preset and need the application rules
`references/style-extraction.md`	You're inside the Learn flow and need the extraction procedure (called from `style-presets.md` )
`references/troubleshooting.md`	An export fails, vision rejects a PNG, or a rendering looks wrong
`scripts/repair_png.py`	After every `-e` PNG export — fixes draw.io's truncated IEND chunk (issue #8)
`scripts/encode_drawio_url.py`	The CLI is unavailable and you need a browser-fallback diagrams.net URL

当工作流涉及以下资源时，按需读取即可 — 无需预先加载到上下文环境中。

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

Prerequisites

前置条件

The draw.io desktop app must be installed and the CLI accessible:

bash

undefined

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

bash

undefined

macOS (Homebrew — recommended)

macOS（Homebrew — 推荐方式）

brew install --cask drawio draw.io --version

macOS (full path if not in PATH)

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


Install draw.io desktop if missing:
- macOS: `brew install --cask drawio` or download from https://github.com/jgraph/drawio-desktop/releases
- Windows: download installer from https://github.com/jgraph/drawio-desktop/releases
- Linux: download `.deb`/`.rpm` from https://github.com/jgraph/drawio-desktop/releases — **do not use snap** (AppArmor sandbox denies secrets/keyring on servers, causes crash)

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沙箱会阻止服务器访问密钥/密钥环，导致崩溃）

Workflow

工作流

Before starting the workflow, assess whether the user's request is specific enough. If key details are missing, ask 1-3 focused questions:

Diagram type — which preset? (ERD, UML, Sequence, Architecture, ML/DL, Flowchart, or general)
Output format — PNG (default), SVG, PDF, or JPG?
Output location — default is the user's working dir; honor any explicit path the user gives (e.g. "put it in
```
./artifacts/
```
"). Don't ask if they didn't mention one.
Scope/fidelity — how many components? Any specific technologies or labels?

Skip clarification if the request already specifies these details or is clearly simple (e.g., "draw a flowchart of X").

Update check (notify, don't pull) — first use per conversation. Throttle to once per 24 h via
```
<this-skill-dir>/.last_update
```
; never mutate the skill directory without explicit user consent.
- If
```
.last_update
```
  exists and is <24 h old, skip this step entirely.
- Otherwise, fetch the latest tag from upstream:
  bash
```
git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null \
  | awk '{print $2}' | sed 's|refs/tags/||' | sort -V | tail -1
```
- Compare with this skill's
```
metadata.version
```
  from the frontmatter. If the upstream tag is strictly newer (semver), tell the user one line and ask:
  "A newer version of this skill is available: vX.Y.Z → vA.B.C. Want me to
  git pull
  ?"
  If they say yes, run
```
git -C <this-skill-dir> pull --ff-only
```
  . Refresh
```
.last_update
```
  either way so the prompt doesn't repeat for 24 hours.
- If upstream is the same or older, refresh
```
.last_update
```
  silently and continue.
- On any failure (offline, not a git checkout — e.g. ClawHub-installed copy, read-only path, no permission), swallow the error silently and continue with the user's task. Do not mention the failure.

Step 0.5 — Resolve active preset. Determine which (if any) user-defined style preset applies to this generation.

Scan the user's message for a phrase that clearly names a style preset: "use my
```
<name>
```
style", "with my
```
<name>
```
style", "in
```
<name>
```
mode", "in the style of
```
<name>
```
". A bare
```
with <name>
```
does not count — "draw a diagram with redis" names a component, not a style. If a clear match is found → active preset =
```
<name>
```
.
Else, check
```
~/.drawio-skill/styles/
```
for any file with
```
"default": true
```
. If found → active preset = that one.
Else → no preset active; fall through to the built-in color/shape/edge conventions for the rest of the workflow.

Load the preset JSON from

~/.drawio-skill/styles/<name>.json

, falling back to

<this-skill-dir>/styles/built-in/<name>.json

. If the named preset exists in neither location, tell the user the name is unknown, list the available presets (user dir + built-in), and stop — do not silently fall back to defaults.

When a preset loads successfully, mention it in the first line of the reply: "Using preset
<name>
(confidence:
<level>
)." See the Applying a preset subsection below for how the preset changes color/shape/edge/font decisions.

Check deps — verify
```
draw.io --version
```
succeeds; note platform for correct CLI path
Plan — identify shapes, relationships, layout (LR or TB), group by tier/layer
Generate — write
```
.drawio
```
XML file to disk. Default output dir is the user's working dir; if the user specified an output path or directory (e.g.
```
./artifacts/
```
,
```
docs/images/
```
), use that instead —
```
mkdir -p
```
the target dir first. Apply the same dir choice to PNG/SVG/PDF exports in steps 4 and 7.
Export draft — run CLI to produce a preview PNG. Do NOT pass
-e
at this step — the embedded
```
zTXt mxGraphModel
```
chunk it adds causes vision APIs (Claude included) to return 400 "Could not process image" in step 5. Save the clean preview as
```
<name>.png
```
(single extension). Embedding is for the final export only (step 7).
Self-check — use the agent's built-in vision capability to read the exported PNG, catch obvious issues, auto-fix before showing user (requires a vision-enabled model such as Claude Sonnet/Opus). If reading the PNG returns a 400 / "Could not process image" error, you almost certainly exported with
```
-e
```
by mistake — re-export without
```
-e
```
and retry once. If it still fails, skip self-check and continue to step 6.
Review loop — show image to user, collect feedback, apply targeted XML edits, re-export, repeat until approved
Final export — re-export the approved version to all requested formats. Use
```
-e
```
here (PNG/SVG/PDF) so the deliverable stays editable in draw.io; save as
```
<name>.drawio.png
```
to signal embedded XML. For PNG with
-e
, run
python3 <this-skill-dir>/scripts/repair_png.py <name>.drawio.png
immediately after — draw.io's CLI truncates the IEND chunk in
```
-e
```
PNG output (8 bytes missing), producing a corrupt file that vision APIs and strict PNG decoders reject (issue #8). Report file paths.

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

图表类型 — 使用哪个预设？（ERD、UML类图、序列图、架构图、机器学习/深度学习图、流程图或通用型）
输出格式 — PNG（默认）、SVG、PDF还是JPG？
输出位置 — 默认是用户的工作目录；若用户指定了明确路径（如“放到
```
./artifacts/
```
目录”），则遵循用户要求。若用户未提及，无需询问。
范围/保真度 — 包含多少个组件？是否有特定技术或标签？

如果请求已明确包含这些细节，或明显简单（如“绘制X的流程图”），则跳过澄清步骤。

版本更新检查（仅通知，不自动拉取） — 每次对话首次使用时执行。通过
```
<this-skill-dir>/.last_update
```
文件限制为每24小时一次；未经用户明确同意，不得修改技能目录。
- 若
```
.last_update
```
  文件存在且创建时间不足24小时，完全跳过此步骤。
- 否则，从上游获取最新标签：
  bash
```
git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null \
  | awk '{print $2}' | sed 's|refs/tags/||' | sort -V | tail -1
```
- 将其与技能前导内容中的
```
metadata.version
```
  进行比较。如果上游标签版本更新（语义化版本），告知用户并询问：
  "该技能有新版本可用：vX.Y.Z → vA.B.C。是否需要执行
  git pull
  更新？"
  如果用户同意，运行
```
git -C <this-skill-dir> pull --ff-only
```
  。无论用户是否同意，都刷新
```
.last_update
```
  文件，确保24小时内不再重复提示。
- 如果上游版本相同或更旧，静默刷新
```
.last_update
```
  文件并继续。
- 若出现任何失败（离线、非git检出版本 — 如ClawHub安装的副本、只读路径、无权限），静默忽略错误并继续执行用户任务，不得提及失败情况。

步骤0.5 — 解析激活的预设。确定是否有用户定义的样式预设适用于本次生成。

扫描用户消息中明确命名样式预设的短语：“使用我的
```
<name>
```
样式”、“采用我的
```
<name>
```
样式”、“以
```
<name>
```
模式”、“按照
```
<name>
```
的风格”。仅
```
with <name>
```
不构成匹配 — “绘制包含redis的图表”指的是组件，而非样式。若找到明确匹配项 → 激活预设 =
```
<name>
```
。
否则，检查
```
~/.drawio-skill/styles/
```
目录中是否存在包含
```
"default": true
```
的文件。若找到 → 激活预设 = 该文件对应的预设。
否则 → 无激活预设；后续工作流使用内置的颜色/形状/连接线规则。

从

~/.drawio-skill/styles/<name>.json

加载预设JSON，若不存在则回退到

<this-skill-dir>/styles/built-in/<name>.json

。若指定的预设在两个位置都不存在，告知用户该名称未知，列出可用预设（用户目录+内置）并停止 — 请勿静默回退到默认值。

预设加载成功后，在回复的第一行提及：“正在使用预设
<name>
（置信度：
<level>
）。” 请参阅下方的应用预设小节，了解预设如何改变颜色/形状/连接线/字体的决策。

检查依赖 — 验证
```
draw.io --version
```
命令执行成功；记录平台信息以使用正确的CLI路径
规划 — 确定形状、关系、布局（左右布局LR或上下布局TB），按层级/层分组
生成 — 将
```
.drawio
```
XML文件写入磁盘。默认输出目录为用户的工作目录；若用户指定了输出路径或目录（如
```
./artifacts/
```
、
```
docs/images/
```
），则使用该路径 — 先执行
```
mkdir -p
```
创建目标目录。步骤4和7中的PNG/SVG/PDF导出也使用相同的目录选择。
导出草稿 — 运行CLI生成预览PNG。此步骤请勿传递
-e
参数 — 它添加的嵌入式
```
zTXt mxGraphModel
```
块会导致步骤5中视觉API（包括Claude）返回400“无法处理图像”错误。将干净的预览保存为
```
<name>.png
```
（单一扩展名）。嵌入操作仅在最终导出（步骤7）中执行。
自我检查 — 使用Agent内置的视觉能力读取导出的PNG，发现明显问题并在展示给用户前自动修复（需要支持视觉的模型，如Claude Sonnet/Opus）。若读取PNG返回400/“无法处理图像”错误，几乎可以肯定是误加了
```
-e
```
参数 — 重新导出时不使用
```
-e
```
并重试一次。若仍失败，跳过自我检查并继续步骤6。
审核循环 — 向用户展示图像，收集反馈，针对性修改XML，重新导出，重复此过程直到用户批准
最终导出 — 将已批准的版本重新导出为所有请求的格式。此处使用
```
-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块（缺失8字节），生成的损坏文件会被视觉API和严格的PNG解码器拒绝（问题#8）。报告文件路径。

Step 5: Self-Check

步骤5：自我检查

After exporting the draft PNG, use the agent's vision capability (e.g., Claude's image input) to read the image and check for these issues before showing the user. If the agent does not support vision, skip self-check and show the PNG directly.

Important: the draft PNG read here must have been exported without

-e

. Draw.io's

-e

flag emits a PNG with a truncated IEND chunk (8 bytes of type+CRC missing) that the Anthropic vision API rejects with 400 "Could not process image" (issue #8). The simplest fix for the preview step is to skip

-e

entirely; the final export in step 7 keeps

-e

and runs the repair snippet. If you see the 400 error here, re-export without

-e

and retry once; if it still fails (any other reason), skip self-check and proceed to step 6.

Check	What to look for	Auto-fix action
Overlapping shapes	Two or more shapes stacked on top of each other	Shift shapes apart by ≥200px
Clipped labels	Text cut off at shape boundaries	Increase shape width/height to fit label
Missing connections	Arrows that don't visually connect to shapes	Verify `source` / `target` ids match existing cells
Off-canvas shapes	Shapes at negative coordinates or far from the main group	Move to positive coordinates near the cluster
Edge-shape overlap	An edge/arrow visually crosses through an unrelated shape	Add waypoints ( `<Array as="points">` ) to route around the shape, or increase spacing between shapes
Stacked edges	Multiple edges overlap each other on the same path	Distribute entry/exit points across the shape perimeter (use different exitX/entryX values)

Max 2 self-check rounds — if issues remain after 2 fixes, show the user anyway
Re-export after each fix and re-read the new PNG

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

重要提示： 此处读取的草稿PNG必须是未使用
-e
参数导出的。Draw.io的

-e

参数生成的PNG存在截断的IEND块（缺失8字节的类型+CRC），会导致Anthropic视觉API返回400“无法处理图像”错误（问题#8）。预览步骤的最简单修复方法是完全跳过

-e

参数；步骤7的最终导出保留

-e

参数并运行修复脚本。若在此处看到400错误，重新导出时不使用

-e

并重试一次；若仍失败（其他原因），跳过自我检查并继续步骤6。

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

最多执行2轮自我检查 — 若2次修复后仍存在问题，仍需展示给用户
每次修复后重新导出并读取新的PNG

Step 6: Review Loop

步骤6：审核循环

After self-check, show the exported image and ask the user for feedback.

Targeted edit rules — for each type of feedback, apply the minimal XML change:

User request	XML edit action
Change color of X	Find `mxCell` by `value` matching X, update `fillColor` / `strokeColor` in `style`
Add a new node	Append a new `mxCell` vertex with next available `id` , position near related nodes
Remove a node	Delete the `mxCell` vertex and any edges with matching `source` / `target`
Move shape X	Update `x` / `y` in the `mxGeometry` of the matching `mxCell`
Resize shape X	Update `width` / `height` in the `mxGeometry` of the matching `mxCell`
Add arrow from A to B	Append a new `mxCell` edge with `source` / `target` matching A and B ids
Change label text	Update the `value` attribute of the matching `mxCell`
Change layout direction	Full regeneration — rebuild XML with new orientation

Rules:

For single-element changes: edit existing XML in place — preserves layout tuning from prior iterations
For layout-wide changes (e.g., swap LR↔TB, "start over"): regenerate full XML
Overwrite the same
```
{name}.png
```
(no
```
-e
```
) each iteration — do not create
```
v1
```
,
```
v2
```
,
```
v3
```
files.
```
-e
```
is reserved for the final export in step 7.
After applying edits, re-export and show the updated image
Loop continues until user says approved / done / LGTM
Safety valve: after 5 iteration rounds, suggest the user open the
```
.drawio
```
file in draw.io desktop for fine-grained adjustments

自我检查完成后，向用户展示导出的图像并请求反馈。

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

用户请求	XML编辑操作
修改X的颜色	通过 `value` 匹配找到 `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
```
文件进行精细调整

Step 7: Final Export

步骤7：最终导出

Once the user approves:

Export to all requested formats (PNG, SVG, PDF, JPG) — default to PNG if not specified
Report file paths for both the
```
.drawio
```
source file and exported image(s)
Auto-launch: offer to open the
```
.drawio
```
file in draw.io desktop for fine-tuning —
```
open diagram.drawio
```
(macOS),
```
xdg-open
```
(Linux),
```
start
```
(Windows)
Confirm files are saved and ready to use

用户批准后：

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

Style Presets

样式预设

A style preset is a named JSON file capturing a user's visual preferences (palette, shapes, font, edges). When active, it fully replaces the built-in color/shape conventions in this skill.

Lookup order when SKILL.md's step 0.5 resolves a preset name:

~/.drawio-skill/styles/<name>.json

— user presets (survive

git pull

)

<this-skill-dir>/styles/built-in/<name>.json

— shipped built-ins (

default

corporate

handdrawn

)

Always lowercase the user-provided name before any file operation — the schema enforces lowercase.

For everything else — Learn flow (extracting a preset from a file), management ops (list/default/delete/rename), application rules (color lookup, shape keywords, edges, fonts, extras, interaction with diagram-type presets), and validation — read
references/style-presets.md
. It's only needed when the user invokes those flows or when an active preset must be applied to the current generation.

样式预设是一个记录用户视觉偏好（调色板、形状、字体、连接线）的命名JSON文件。启用后，它将完全替代本工具中的内置颜色/形状规则。

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

~/.drawio-skill/styles/<name>.json

— 用户预设（

git pull

后仍保留）

<this-skill-dir>/styles/built-in/<name>.json

— 内置预设（

default

、

corporate

、

handdrawn

）

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

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

Draw.io XML Structure

Draw.io XML结构

File skeleton

文件框架

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>

Rules:

```
id="0"
```
and
```
id="1"
```
are required root cells — never omit them
User shapes start at
```
id="2"
```
and increment sequentially
All shapes have
```
parent="1"
```
(unless inside a container — then use container's id)
All text uses
```
html=1
```
in style for proper rendering
Never use
--
inside XML comments — it's illegal per XML spec and causes parse errors
Escape special characters in attribute values:
```
&amp;
```
,
```
&lt;
```
,
```
&gt;
```
,
```
&quot;
```
Multi-line text in labels: use
```
&#xa;
```
for line breaks inside
```
value
```
attributes (not literal
```
\n
```
). Example:
```
value="Line 1&#xa;Line 2"
```

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" />
        <!-- 用户形状从id="2"开始 -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

规则：

```
id="0"
```
和
```
id="1"
```
是必需的根单元格 — 切勿省略
用户形状从
```
id="2"
```
开始，依次递增
所有形状的
```
parent="1"
```
（除非在容器内 — 此时使用容器的ID）
所有文本在样式中使用
```
html=1
```
以确保正确渲染
切勿在XML注释中使用
--
— 这违反XML规范，会导致解析错误
转义属性值中的特殊字符：
```
&amp;
```
、
```
&lt;
```
、
```
&gt;
```
、
```
&quot;
```
标签中的多行文本： 在
```
value
```
属性中使用
```
&#xa;
```
表示换行（不要使用字面量
```
\n
```
）。示例：
```
value="Line 1&#xa;Line 2"
```

Shape types (vertex)

形状类型（顶点）

Style keyword	Use for
`rounded=0`	plain rectangle (default)
`rounded=1`	rounded rectangle — services, modules
`ellipse;`	circles/ovals — start/end, databases
`rhombus;`	diamond — decision points
`shape=mxgraph.aws4.resourceIcon;`	AWS icons
`shape=cylinder3;`	cylinder — databases
`swimlane;`	group/container with title bar

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

Required properties

必填属性

xml

<!-- 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>

xml

<!-- 矩形 / 圆角框 -->
<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>

<!-- 圆柱体（数据库） -->
<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>

<!-- 菱形（决策） -->
<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>

Containers and groups

容器和群组

For architecture diagrams with nested elements, use draw.io's parent-child containment — do not just place shapes on top of larger shapes.

Type	Style	When to use
Group (invisible)	`group;pointerEvents=0;`	No visual border needed, container has no connections
Swimlane (titled)	`swimlane;startSize=30;`	Container needs a visible title bar, or container itself has connections
Custom container	Add `container=1;pointerEvents=0;` to any shape	Any shape acting as a container without its own connections

Key rules:

Add
```
pointerEvents=0;
```
to container styles that should not capture connections between children
Children set
```
parent="containerId"
```
and use coordinates relative to the container

xml

<!-- 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>

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

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

关键规则：

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

xml

<!-- 泳道容器 -->
<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>
<!-- 容器内的子元素 — 坐标相对于父容器 -->
<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>

Connector (edge)

连接线（边）

CRITICAL: Every edge

mxCell

must contain a

<mxGeometry relative="1" as="geometry" />

child element. Self-closing edge cells (

<mxCell ... edge="1" ... />

) are invalid and will not render. Always use the expanded form.

xml

<!-- 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>

Edge style rules:

Animated connectors: add
```
flowAnimation=1;
```
to any edge style to show a moving dot animation along the arrow. Works in SVG export and draw.io desktop — ideal for data-flow and pipeline diagrams. Example:
```
style="edgeStyle=orthogonalEdgeStyle;flowAnimation=1;rounded=1;..."
```
Always include
```
rounded=1;orthogonalLoop=1;jettySize=auto
```
— these enable smart routing that avoids overlaps
Pin
```
exitX/exitY/entryX/entryY
```
on every edge when a node has 2+ connections — distributes lines across the shape perimeter
Add
```
<Array as="points">
```
waypoints when an edge must detour around an intermediate shape
Leave room for arrowheads: the final straight segment between the last bend and the target shape must be ≥20px long. If too short, the arrowhead overlaps the bend and looks broken. Fix by increasing node spacing or adding explicit waypoints

关键提示： 每个连接线

mxCell

必须包含一个

<mxGeometry relative="1" as="geometry" />

子元素。自闭合的连接线单元格（

<mxCell ... edge="1" ... />

）无效，无法渲染。始终使用展开形式。

xml

<!-- 有向箭头 — 始终包含rounded、orthogonalLoop、jettySize以实现清晰路由 -->
<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>

<!-- 带标签的箭头 + 显式入口/出口点以控制方向 -->
<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>

<!-- 带路径点的箭头 — 当连接线必须绕开其他形状时使用 -->
<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长。如果太短，箭头会与弯曲处重叠，导致显示异常。通过增大节点间距或添加显式路径点修复。

Distributing connections on a shape

在形状上分布连接

When multiple edges connect to the same shape, assign different entry/exit points to prevent stacking:

Position	exitX/entryX	exitY/entryY	Use when
Top center	0.5	0	connecting to node above
Top-left	0.25	0	2nd connection from top
Top-right	0.75	0	3rd connection from top
Right center	1	0.5	connecting to node on right
Bottom center	0.5	1	connecting to node below
Left center	0	0.5	connecting to node on left

Rule: if a shape has N connections on one side, space them evenly (e.g., 3 connections on bottom → exitX = 0.25, 0.5, 0.75)

当多个连接线连接到同一个形状时，分配不同的入口/出口点以避免堆叠：

位置	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）

Color palette (fillColor / strokeColor)

调色板（fillColor / strokeColor）

Used only when no preset is active (see "Applying a preset" above).

Color name	fillColor	strokeColor	Use for
Blue	`#dae8fc`	`#6c8ebf`	services, clients
Green	`#d5e8d4`	`#82b366`	success, databases
Yellow	`#fff2cc`	`#d6b656`	queues, decisions
Orange	`#ffe6cc`	`#d79b00`	gateways, APIs
Red/Pink	`#f8cecc`	`#b85450`	errors, alerts
Grey	`#f5f5f5`	`#666666`	external/neutral
Purple	`#e1d5e7`	`#9673a6`	security, auth

仅当无激活预设时使用（请参阅上方的“应用预设”）。

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

Layout tips

布局技巧

Spacing — scale with complexity:

Diagram complexity	Nodes	Horizontal gap	Vertical gap
Simple	≤5	200px	150px
Medium	6–10	280px	200px
Complex	>10	350px	250px

Routing corridors: between shape rows/columns, leave an extra ~80px empty corridor where edges can route without crossing shapes. Never place a shape in a gap that edges need to traverse.

Grid alignment: snap all

width

height

values to multiples of 10 — this ensures shapes align cleanly on draw.io's default grid and makes manual editing easier.

General rules:

Plan a grid before assigning x/y coordinates — sketch node positions on paper/mentally first
Group related nodes in the same horizontal or vertical band
Use
```
swimlane
```
cells for logical grouping with visible borders
Place heavily-connected "hub" nodes centrally so edges radiate outward instead of crossing
To force straight vertical connections, pin entry/exit points explicitly on edges:
```
exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0
```
Always center-align a child node under its parent (same center x) to avoid diagonal routing
Event bus pattern: place Kafka/bus nodes in the center of the service row, not below — services on either side can reach it with short horizontal arrows (
```
exitX=1
```
left side,
```
exitX=0
```
right side), eliminating all line crossings
Horizontal connections (
```
exitX=1
```
or
```
exitX=0
```
) never cross vertical nodes in the same row; use them for peer-to-peer and publish connections

Avoiding edge-shape overlap:

Before finalizing coordinates, trace each edge path mentally — if it must cross an unrelated shape, either move the shape or add waypoints
For tree/hierarchical layouts: assign nodes to layers (rows), connect only between adjacent layers to minimize crossings
For star/hub layouts: place the hub center, satellites around it — edges stay short and radial
When an edge must span multiple rows/columns, route it along the outer corridor, not through the middle of the diagram

间距 — 随复杂度调整：

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

路由通道： 在形状行/列之间，留出额外约80px的空白通道，供连接线路由而不穿过形状。切勿在连接线需要经过的间隙中放置形状。

网格对齐： 将所有

、

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
```
）不会与同一行的垂直节点交叉；用于对等连接和发布连接

避免连接线与形状重叠：

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

Export

导出

Commands

命令

There are two export modes:

Preview / self-check (step 4 of the workflow) — no
```
-e
```
. Output
```
diagram.png
```
. Required for vision self-check; using
```
-e
```
here triggers a 400 "Could not process image" error from the vision API (issue #8).
Final / deliverable (step 7) — pass
```
-e
```
. Output
```
diagram.drawio.png
```
. The embedded XML keeps the file editable in draw.io.

bash

undefined

有两种导出模式：

预览/自我检查（工作流步骤4） — 不使用
```
-e
```
参数。输出
```
diagram.png
```
。视觉自我检查必需；在此步骤使用
```
-e
```
会触发视觉API返回400“无法处理图像”错误（问题#8）。
最终/交付物（步骤7） — 使用
```
-e
```
参数。输出
```
diagram.drawio.png
```
。嵌入的XML使文件在draw.io中保持可编辑。

bash

undefined

Preview PNG (use this in step 4, before self-check) — NO -e

预览PNG（步骤4使用，自我检查前） — 不使用-e

draw.io -x -f png -s 2 -o diagram.png input.drawio

Final PNG (step 7, after user approval) — WITH -e, double extension

最终PNG（步骤7，用户批准后） — 使用-e，双重扩展名

draw.io -x -f png -e -s 2 -o diagram.drawio.png input.drawio

macOS — full path (if not in PATH); preview / final variants

macOS — 完整路径（若不在PATH中）；预览/最终变体

/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)

Linux（无头模式 — 需要xvfb-run；服务器上添加HOME和--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)

以root身份运行（CI / Docker）？在末尾添加--no-sandbox（放在前面会被drawio视为输入文件名）

SVG export (final — -e is safe; SVG is text)

SVG导出（最终 — -e安全；SVG是文本格式）

draw.io -x -f svg -e -o diagram.svg input.drawio

PDF export (final)

PDF导出（最终）

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

自定义输出目录（如CI工件目录） — 先创建目录（若不存在），再导出

mkdir -p ./artifacts && draw.io -x -f png -e -s 2 -o ./artifacts/diagram.drawio.png input.drawio

undefined

mkdir -p ./artifacts && draw.io -x -f png -e -s 2 -o ./artifacts/diagram.drawio.png input.drawio

undefined

Post-export PNG repair (required after

-e

PNG export)

导出后PNG修复（使用-e参数导出PNG后必需）

draw.io CLI truncates the IEND chunk when emitting

-e

PNGs — the file ends with the 4-byte IEND length field but the

IEND

type + CRC (8 bytes) are missing. Result: vision APIs return 400 "Could not process image" and strict PNG decoders error out. SVG/PDF are unaffected.

Run this immediately after every

-e

PNG export:

bash

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

The script's

endswith(IEND)

guard makes it a no-op once draw.io fixes the bug upstream — safe to run unconditionally.

Key flags:

```
-x
```
— export mode (required)
```
-f
```
— format:
```
png
```
,
```
svg
```
,
```
pdf
```
,
```
jpg
```
```
-e
```
— embed diagram XML in output (PNG, SVG, PDF) — exported file remains editable in draw.io. Skip for the preview PNG used in step 5 self-check —
```
-e
```
PNGs have a truncated IEND chunk that vision APIs reject (issue #8). For final PNG export, keep
```
-e
```
and run
```
scripts/repair_png.py
```
(see Post-export PNG repair). SVG/PDF unaffected.
```
-s
```
— scale:
```
1
```
,
```
2
```
,
```
3
```
(2 recommended for PNG)
```
-o
```
— output file path; accepts any directory (e.g.
```
./artifacts/diagram.drawio.png
```
) —
```
mkdir -p
```
the target dir first. Use
```
.drawio.png
```
double extension when embedding.
```
-b
```
— border width around diagram (default: 0, recommend 10)
```
-t
```
— transparent background (PNG only)
```
--page-index 0
```
— export specific page (default: all)

draw.io CLI在生成

-e

参数的PNG时会截断IEND块 — 文件以4字节的IEND长度字段结尾，但缺失

IEND

类型+CRC（8字节）。结果：视觉API返回400“无法处理图像”，严格的PNG解码器报错。SVG/PDF不受影响。

每次使用

-e

参数导出PNG后立即运行：

bash

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块，会被视觉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
```
— 导出特定页面（默认：所有页面）

Browser fallback (no CLI needed)

浏览器备用方案（无需CLI）

When the draw.io desktop CLI is unavailable, generate a client-side viewer URL:

bash

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

Prints a

https://viewer.diagrams.net/...

URL with the diagram XML deflate-compressed and base64-encoded into the URL fragment. The fragment (after

) is never sent to the server, so nothing is uploaded — the diagram opens client-side for viewing and editing. Useful when the user cannot install the desktop app.

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

bash

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

输出一个

https://viewer.diagrams.net/...

URL，其中图表XML经过deflate压缩并base64编码到URL片段中。片段（

之后）不会发送到服务器，因此不会上传任何内容 — 图表在客户端打开，可查看和编辑。当用户无法安装桌面应用时非常有用。

Fallback chain

降级策略

When tools are unavailable, degrade gracefully:

Scenario	Behavior
draw.io CLI missing, Python available	Use browser fallback (diagrams.net URL)
draw.io CLI missing, Python missing	Generate `.drawio` XML only; instruct user to open in draw.io desktop or diagrams.net manually
Vision unavailable for self-check	Skip self-check (step 5); proceed directly to showing user the exported PNG
Export fails (Chromium/display issues)	On Linux, retry with `xvfb-run -a` ; if still failing, deliver `.drawio` XML and suggest manual export
Export fails on Linux server (headless)	Try in order: (1) `xvfb-run -a` , (2) append `--no-sandbox` at the very end if root, (3) add `--disable-gpu` , (4) `export HOME=/tmp` , (5) install apt deps ( `libgtk-3-0 libnotify4 libnss3 libgbm1 libasound2t64` etc.), (6) fall back to tomkludy/drawio-renderer Docker (REST API for headless export)

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

场景	行为
draw.io CLI缺失，Python可用	使用浏览器备用方案（diagrams.net URL）
draw.io CLI缺失，Python缺失	仅生成 `.drawio` XML；指导用户手动在draw.io桌面应用或diagrams.net中打开
自我检查无视觉能力	跳过自我检查（步骤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）

Checking if draw.io is in PATH

检查draw.io是否在PATH中

bash

undefined

bash

undefined

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

undefined

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 — 请从https://github.com/jgraph/drawio-desktop/releases安装" fi

undefined

Common Mistakes

常见错误

When something looks wrong (export fails, vision rejects a PNG, layout broken, edges misroute), see

references/troubleshooting.md

for a row-by-row mistake → fix table.

当出现异常情况（导出失败、视觉API拒绝PNG、布局损坏、连接线路由错误）时，请查看

references/troubleshooting.md

中的错误-修复对照表。

Diagram Type Presets

图表类型预设

When the user requests a specific diagram type, read

references/diagram-types.md

for the matching preset (shapes, edges, layout direction). Pick by user phrasing:

User says	Section in `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

The diagram-type preset sets structural style keywords. If a user style preset is also active (see

## Style Presets

), keep the structural keywords and layer color/font/edge/extras on top — read

references/style-presets.md

→ "Interaction with diagram-type presets" for the merge rules.

当用户请求特定类型的图表时，请查看

references/diagram-types.md

获取匹配的预设（形状、连接线、布局方向）。根据用户表述选择：

用户表述	`references/diagram-types.md` 中的章节
"ER图"、" schema图"、"数据模型"	ERD
"UML类图"、"类图"	UML Class
"序列图"、"交互图"、"生命线"	Sequence
"架构图"、"系统图"、"服务图"	Architecture
"神经网络"、"模型架构"、"ML图"、"深度学习"	ML / Deep Learning Model
"流程图"、"决策树"、"流程流"	Flowchart

图表类型预设设置结构样式关键词。如果同时激活了用户样式预设（请参阅

## 样式预设

），保留结构关键词并叠加颜色/字体/连接线/附加项 — 请阅读

references/style-presets.md

→ “与图表类型预设的交互”了解合并规则。