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”:“通过 Homebrew 安装 draw.io”,“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 文件并使用本地 draw.io 桌面应用 CLI 导出为 PNG/SVG/PDF/JPG。

支持的格式： 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 块（问题 #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
"E:\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 沙盒会拒绝服务器上的密钥环访问，导致崩溃）

工作流程

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

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

如果请求已明确指定这些细节或非常简单（如"画一个 X 的流程图"），则跳过澄清。

第 0 步——解析活跃预设。 判断本次生成适用哪个（如有）用户定义的样式预设。

  • 扫描用户消息中明确命名样式预设的短语：“使用我的 <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>）。” 参见下方的应用预设小节了解预设如何改变颜色/形状/连线/字体的决策。

  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 块会导致视觉 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 块（缺少 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 标志会生成一个 IEND 块被截断（缺少 8 字节类型+CRC）的 PNG，被 Anthropic 视觉 API 以 400 “Could not process image” 拒绝（问题 #8）。预览步骤最简单的修复是完全跳过 -e；步骤 7 的最终导出保留 -e 并运行修复脚本。如果在此处看到 400 错误，重新不加 -e 导出并重试一次；如果仍然失败（任何其他原因），跳过自检并继续执行步骤 6。

检查项 检查内容 自动修复操作
形状重叠 两个或多个形状堆叠在一起 将形状分开 ≥200px
标签裁剪 文本在形状边界处被截断 增加形状的宽度/高度以适应标签
连接缺失 箭头未在视觉上连接到形状 验证 source/target id 是否匹配现有单元格
画布外形状 形状在负坐标或远离主群组 移动到群组附近的正坐标
连线-形状重叠 连线/箭头视觉上穿过无关的形状 添加路径点（<Array as="points">）绕过形状，或增加形状间距
连线堆叠 多条连线在相同路径上重叠 在形状周边分散出入口点（使用不同的 exitX/entryX 值）
  • 最多 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 的最终导出。
  • 应用编辑后，重新导出并展示更新后的图片
  • 循环持续直到用户说批准/完成/OK
  • 安全阀： 经过 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" />
        <!-- 用户形状从 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="第一行&#xa;第二行"

形状类型（顶点）

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

必需属性

<!-- 矩形 / 圆角矩形 -->
<mxCell id="2" value="标签" 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="数据库" 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="判断?" 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" 并使用相对于容器的坐标
<!-- 泳道容器 -->
<mxCell id="svc1" value="用户服务" 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="数据库" 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" ... />）是无效的且不会渲染。始终使用展开形式。

<!-- 有向箭头——始终包含 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。如果太短，箭头会与弯折重叠并看起来异常。通过增加节点间距或添加显式路径点来修复

在形状上分散连接

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

位置 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 中保持可编辑。
# 预览 PNG（在步骤 4 中使用，自检前）——不用 -e
draw.io -x -f png -s 2 -o diagram.png input.drawio

# 最终 PNG（步骤 7，用户批准后）——用 -e，双扩展名
draw.io -x -f png -e -s 2 -o diagram.drawio.png input.drawio

# 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
"E:\Program Files\draw.io\draw.io.exe" -x -f png -e -s 2 -o diagram.drawio.png input.drawio

# 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
# 以 root 身份运行（CI/Docker）？在最后附加 --no-sandbox（放在前面会使 drawio 将其视为输入文件名）

# SVG 导出（最终——-e 是安全的；SVG 是文本）
draw.io -x -f svg -e -o diagram.svg input.drawio

# PDF 导出（最终）
draw.io -x -f pdf -e -o diagram.pdf input.drawio

# 自定义输出目录（如 CI 产物目录）——先创建目录，然后导出
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 块——文件以 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 块被截断，被视觉 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 中

# 先尝试短命令
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

常见错误

当某个环节出错时（导出失败、视觉拒绝 PNG、布局错乱、连线路由错误），请参阅 references/troubleshooting.md 查看逐行错误→修复表。

图表类型预设

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

用户说 references/diagram-types.md 中的章节
“ER图”、“模式图”、“数据模型” ERD
“UML类图”、“类图” UML 类图
“时序图”、“交互图”、“生命线” 时序图
“架构图”、“系统图”、“服务图” 架构图
“神经网络”、“模型架构”、“ML图”、“深度学习” ML/深度学习模型
“流程图”、“决策树”、“流程” 流程图

图表类型预设设置结构性的样式关键字。如果用户样式预设也已激活（参见 ## 样式预设），保留结构性关键字并将颜色/字体/连线/扩展等叠加在上面——阅读 references/style-presets.md → "与图表类型预设的交互"了解合并规则。

Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

OpenClaw + DeepSeek 大模型玩法：手把手教你玩转AI

OpenClaw（180k+ GitHub Star）是目前最火的开源自建 AI 助手框架，支持全平台部署、多模型切换、自定义技能节点，还能对接飞书、Telegram、Web 等渠道。DeepSeek则是国产大模型中的性价比之王——API 价格低至千 token 几分钱，推理能力（R1 系列）甚至可以对标顶级闭源模型。两者结合 =自建 AI 助手里最香的方案之一。而且！OpenClaw 本身已经内

avatar 龙虾开发者社区

企业缺的不是AI工具，是能把AI用起来的人

2026年了，大模型的参数量还在涨，AI Agent框架每个月都有新的出来。企业采购的AI工具越来越多，但真正能把这些工具跑出业务价值的团队，却少得可怜。这个现象很值得琢磨。

avatar 龙虾开发者社区

cursor自带skills-使用指南

《Cursor内置Skill使用指南》摘要（149字）： 本文介绍Cursor AI Agent内置Skill的功能与使用方法。Skill是预定义的流程化操作指南，存储在~/.cursor/skills-cursor/目录下，包含任务场景、执行步骤和模板。用户可通过斜杠命令、自然语言或Agent自动匹配触发，支持代码审查、PR管理、自动化等场景。与Rule不同，Skill是任务导向的临时工作流。文

avatar 龙虾开发者社区