drawio-reconstruction

Draw.io 重建

使用此技能，可将图表图像高保真地重建为 .drawio 文件。

辅助脚本位置

运行任何捆绑的辅助脚本之前，将 SKILL_DIR 解析为包含此 SKILL.md 的绝对目录。使用运行时提供的已解析技能位置；切勿假设技能安装在 ~/.codex、~/.agents 或任何其他固定目录下。

以下所有命令中的 $SKILL_DIR 均表示该已解析的绝对目录。

保真度要求

首要目标是忠实还原参考图的视觉效果，可编辑性居次。

不要将语义等同视为成功。如果参考图采用了特定视觉风格，那么通用图标、通用曲线、通用字号、大致相似的面板或近似的背景都属于缺陷。

脚本检查只能证明技术有效性。图表并非仅仅因为 .drawio 可以打开、导出或通过 check_drawio.py / batch_verify.py 检查，就算完成。完成还需要在全尺寸下与参考图进行视觉比较。

仅在用户指定的目标目录或目标文件中操作。不要因为相邻图表看起来相关，就修复、覆盖或改进它们。如果请求的目标不明确，应先检查并报告歧义，再进行编辑。

切勿擅自改写用户的内容。如果用户要求增大字体或采用更专业的 PPT 风格，应先区分：

• 仅调整布局：增大字号、调整框的大小、改善间距、对齐元素、调整换行，但不更改文字。
• 压缩内容：缩短句子、删除细节、改写标签。进行此类操作前，请征求用户同意。

批量文件夹工作流

当用户提供图像目录或要求批量重建时，使用此工作流。

批量意图与调度

在打开图像进行详细视觉分析之前，先判断请求是否属于批量重建任务：

• 如果请求指定了文件夹、多个图像文件、glob／模式，或任何解析后对应 2 个或更多图像条目的目标，则将其视为批量重建任务。
• 在开始逐张图像的详细工作之前，先创建并审核清单。
• 如果子 Agent 工具可用且适用，请使用有界工作池，工作池规模不得超过可用并发数和待处理图像数量。为每个正在工作的 Agent 分配一张图像，并指定该图像对应的 .drawio、导出的 .png、审计文件和专属资产／裁剪目录作为其独占写入范围。空出工作槽后再分配下一张图像，不要试图一次启动所有 Agent。
• 如果子 Agent 工具不可用、已禁用、受容量限制，或对于小批量任务而言没有必要，则按照清单顺序逐项处理。保留相同的清点、重建、导出、检查和视觉审计要求。
• 只有调度限制会实质性影响时间或交付时，才告知用户。不要仅仅因为无法并行执行就阻止有效的批量任务。
• 协调 Agent 可以检查缩略图或文件元数据，以确认范围、命名、方向和共用样式约束，再决定调度方式。

1. 确定输入目录、输出目录、命名约定和覆盖策略。

2. 创建批次清单：

   python "$SKILL_DIR/scripts/batch_manifest.py" path/to/images --output-dir path/to/output --write
   

3. 编辑前审核清单。除非用户扩大范围，否则只处理清单中的条目。

4. 对每张图像，在目标输出目录中定义预期输出 <stem>.drawio、<stem>.png 和轻量级 <stem>.audit.md。

5. 选择有界并行调度或串行调度：

   • 为每个正在处理的条目分配独占输出文件。
   • 告知工作 Agent：代码库中还有其他工作 Agent，不得还原或编辑其他工作 Agent 的输出。
   • 要求每个条目遵循与单张图像任务相同的完整工作流。批量模式只是调度策略，不会降低保真度、清点、重建、导出、检查或视觉审计要求。
   • 对每个条目应用以下质量门槛：生成 .drawio、.png 和 <stem>.audit.md；创建完整的可见元素清单；对非文本视觉元素进行分类；根据常规媒介规则使用裁剪图／SVG／原生元素；运行所需的检查／导出；将导出预览与参考图像进行视觉比较；标记尚未解决的视觉缺陷，不得声称已完成。
   • 最终批次验证、视觉检查、审计审核和面向用户的完成报告由协调 Agent 负责。

6. 重建后，运行批次验证：

   python "$SKILL_DIR/scripts/batch_verify.py" path/to/output/drawio_batch_manifest.json
   

7. 打开每个导出的预览并与参考图像比较。不要只凭工作 Agent 的完成声明或脚本运行成功就认定任务完成。

8. 报告已完成、已跳过和失败的条目，以及需要审核的图像。

默认批次输出：

• drawio_batch_manifest.json
• <image-stem>.drawio
• <image-stem>.png
• <image-stem>.audit.md

除非用户明确要求，否则不要覆盖现有输出。如果某个输出已存在，则跳过该项，或创建名称清晰的修订版本，例如 <stem>-v2.drawio。

强制参考清单

重建每张图像前，请先创建可见元素清单。对于复杂任务或批量任务，将清单写入 <stem>.audit.md；对于非常简单的单张图像，在工作笔记中维护清单，并执行相同的检查。

清单必须涵盖每个可见区域和元素：

• 画布尺寸、背景、网格、纹理、渐变、阴影、页面边界
• 标题、副标题、章节标题、页脚、页码
• 面板、卡片、容器、分隔线、徽章、编号标记
• 每个文本块和标签
• 每个图标、插图、截图、徽标、图表、缩略图或装饰性视觉元素
• 每条箭头、曲线、连接线、环路、括号、虚线路径和箭头
• 界定布局的所有间距关系

清单中的每个条目都必须包含：

• id
• 大致区域或边界框
• 内容／视觉描述
• 选定的媒介：原生元素／SVG／裁剪图／生成后清理
• 样式备注：颜色、描边、字体、大小、阴影、曲线几何形状、内边距
• 状态：待处理／已完成／需要修复／已验收

在所有可见清单条目都已验收或明确报告为未解决之前，不要开始最终交付。

重建策略

选择最能还原视觉效果的媒介。不要默认将所有非文本视觉元素都处理为截图，也不要默认将所有视觉元素都重绘为 SVG。判断标准是：哪种方法在导出后最接近参考图？

以下内容优先使用 Draw.io 原生元素：

• 可编辑的文本、标题、标签、标记、说明框
• 方框、面板、分隔线、简单表格、简单图表、徽章
• 使用原生几何形状即可匹配参考图的结构箭头／连接线
• 便于编辑的重复布局结构

以下内容默认使用 PNG 裁剪图／截图：

• 复杂图标、精细符号、装饰性插图和混合对象视觉元素
• 通用 SVG 无法匹配的特定风格图标系列
• 视觉隐喻和场景类插图：冰山、人物、环境、仪表板、显示器、实验室场景、房间、风景、工作流场景
• 真实的 UI 截图、手机／仪表板条带、应用缩略图、证据截图、密集的微型示意图
• 人物、卡通角色、表情丰富的面孔、手、身体姿势或人机交互场景
• 精确还原视觉效果比可编辑性更重要的任何内容
• 需要大量路径、渐变、蒙版或手动近似才能重绘的任何非文本视觉元素
• 使用 SVG／原生元素尝试会简化、遗漏或明显扭曲重要细节的任何视觉元素

仅在以下情况下使用 SVG／原生元素：

• 简洁的图标，且参考图的形状和风格都能匹配，而不只是语义相符
• 轮廓／填充几何形状简单、主要颜色为 1–2 种、没有关键纹理、内部细节不密集，并且具有清晰可复现的参考风格的图标
• 可通过 SVG 保持相同描边宽度、比例、颜色和缩放效果的重复简单图标系列
• 裁剪图会模糊或带入背景干扰，而形状级 SVG 可以匹配的小型源图标
• 用户明确需要矢量可编辑性的元素

不要仅因通用标准图标在语义上相符，就直接使用它。数据库、图表、文档、靶心、大脑、机器人、手机、剪贴板、光标、灯泡、分子、烧杯、显示器及类似图标，仍须对照参考图检查其形状和风格。

中等复杂度的判定规则

重建之前，先对每个视觉元素进行分类。

1. 如果是文本或结构，请使用 Draw.io 原生元素。
2. 如果是具有独特参考风格、细节丰富、带渐变、阴影、多对象构图或场景／隐喻内容的视觉元素，请裁剪它，除非用户明确要求可编辑的矢量图。
3. 如果是简单、干净的图标，只有当 SVG 能匹配参考图的形状、描边、比例、填充和视觉风格时，才使用 SVG／原生元素。
4. 如果 SVG 在语义上正确，但视觉效果很普通，就不要使用。请裁剪参考图，或创建更贴近原图形状的 SVG。
5. 如果裁剪图模糊、有杂项干扰或带有可见矩形背景，请先修复裁剪图／背景。只有当视觉元素简单，且 SVG 比裁剪图更贴近参考图时，才改用 SVG。
6. 如果裁剪图的背景接缝可见，请尝试清理为透明 PNG，或让裁剪图背景与所在面板的背景相匹配。
7. 如果常规清理后仍有光晕、边缘参差、水印、JPEG 块状伪影或面板不匹配，请将裁剪图放在同色背景块上、收紧裁剪范围，或使用可用的图像编辑／生成工具，仅修复背景。
8. 如果裁剪图和 SVG／原生元素都无法接受，请在审核中将该项目标记为 needs-fix，而不是悄悄替换成质量不佳的图形。

会阻止交付的视觉缺陷：

• 参考图使用了特定风格的图标，却被普通替代图标取代
• 未经用户要求使图形可编辑的情况下，将复杂视觉内容重绘为简化的 SVG
• 简单图标的裁剪图模糊不清，而干净的形状级 SVG 明显更匹配
• 复杂图稿的裁剪图存在明显背景接缝、光晕、笔画缺失、阴影被裁切，或包含无关的相邻文本／边框
• 缺少醒目的图标、装饰性标记或细节图形

图标重建规范

在编写图标 SVG 或嵌入裁剪图之前，先根据参考图建立角色与符号的对应表。例如：

• 规划：大脑、清单、规划符号
• 工具使用：扳手、交叉工具、终端、工具符号
• 记忆：数据库圆柱体、存储、记忆符号
• 验证：盾牌、对勾、审核、验证符号
• 证据卡片：架构／表格、日志／文档、执行树／计划、指标／仪表盘

对于对应表中的每一项：

• 对于复杂、风格独特或细节丰富的符号，请使用源图裁剪图。
• 仅对能够匹配参考风格的简单、干净图标，使用独立的 SVG 或 Draw.io 原生符号。
• 描边宽度、颜色、比例和尺寸应与参考图一致，不要套用通用图标集的样式。
• 不要复制一个图标，只改它的位置或标签。
• 除非参考图本身重复使用同一个占位图标，否则不要使用通用占位图标。
• 如果符号不够简单、干净，请从参考图中裁剪该符号，而不是用无关的 SVG 替代。

创建或编辑图标后，运行 check_drawio.py。证据图标、核心条带图标、工作流步骤图标或结果行图标中存在重复的图像负载，属于阻断性错误，除非参考图有意重复使用相同符号。

截图裁剪规则

在以下情况下使用截图／PNG 裁剪图：

• 插图过于复杂，无法高效重绘
• 精确的视觉风格比可编辑性更重要
• 尝试使用 SVG 后效果仍然不佳或显得普通
• 用户提供或认可了优质裁剪图
• 视觉元素是复杂图标，手绘 SVG 会丢失其中的细节
• 视觉元素是真实的 UI 截图、手机画面条、仪表板缩略图、密集的证据图、人物、场景或视觉隐喻

使用截图时：

• 不要用截图呈现可编辑文本或结构布局。

• 围绕目标前景图稿裁剪，不要把周围整个区域都裁进去。

• 先从粗略的 ROI 开始，确定前景边界框，然后添加适度的安全留白。

• 尽可能使用裁剪辅助工具：

  python "$SKILL_DIR/scripts/crop_assist.py" reference.png --roi x,y,w,h --anchor x,y --exclude x,y,w,h --output-dir crops --name icon_name
  

• 在嵌入裁剪图之前，先检查生成的预览和候选图。脚本会建议边界，但仍由模型决定哪个候选图最符合参考图。

• crop_assist.py 需要 Pillow。如果 Pillow 不可用，应先请求批准再更改环境，然后使用 python -m pip install -r "$SKILL_DIR/requirements.txt" 安装捆绑的可选依赖。不要悄悄跳过裁剪检查。

• 对粗略 ROI 内不属于目标图稿的邻近元素使用 --exclude 框，尤其是项目符号、正文、标题线、编号徽标、面板边框和分隔线。

• 安全留白应保留完整的线条、箭头、阴影、抗锯齿效果以及紧邻图稿且有意保留的空白。不要扩展到一般性的空白区域。

• 除非为了避开邻近内容而必须紧贴裁剪，否则不要紧贴可见线条裁剪。线条被截断、箭头被切掉、阴影缺失，或图稿触及裁剪边缘，都是阻断性缺陷。

• 不要包含邻近的项目符号、标签、标题线、卡片边框、分隔线或其他无关的同色标记。如果增加留白会带入邻近元素，请使用较紧但有效的候选图，并通过透明背景或颜色匹配来处理背景。

• 如果周围面板／背景不统一，优先使用透明 PNG。

• 如果无法使用透明背景，或者清理后出现光晕，请将裁剪图置于同色背景块上。

• 如果裁剪图的背景颜色与 Draw.io 面板不匹配，请缩紧裁剪范围、移除背景、重新着色／匹配裁剪图背景，或将容器面板／背景设置为匹配的颜色。

• 如果裁剪图较复杂，常规清理后仍存在背景不匹配，请使用可用的图像编辑／生成工具，仅修复或中和背景；不要更改有语义的前景内容。

• 检查导出的 PNG 是否存在明显接缝、抗锯齿光晕、锯齿状透明边缘、模糊或背景不匹配。不要留下可见的矩形裁剪接缝。

曲线和箭头

对于每个箭头或曲线，先匹配参考图，再选择实现方式。

创建箭头清单：

• 源元素和目标元素
• 起点／终点锚点
• 方向
• 线条类型：实线、虚线、点线、曲线、垂直、水平、环形
• 线条粗细、颜色、箭头类型和大小
• 弯折点、圆角半径，以及路径经过面板前方还是后方
• 语义角色：工作流转换、反馈循环、证据支持、标注、装饰性提示

实现顺序：

1. 对于结构连接线，若原生 Draw.io 连接器能够匹配参考图，则使用该连接器。
2. 对于特殊大括号、曲线箭头、环形箭头、圆角返回路径或原生 Draw.io 无法匹配的装饰性箭头，使用 SVG 路径。
3. 仅对高度特定且不可编辑的装饰性标记使用 PNG 裁剪图。

大型环形箭头、虚线反馈曲线和圆角返回路径必须匹配参考图的路径几何形状。不要用近似的通用连接器替代。

字体排版与布局

在指定字号之前，先从参考图中提取字体排版信息：

• 主标题
• 副标题
• 分区标题
• 卡片标题
• 卡片正文
• 标签/标记
• 页脚/页码
• 图标-标签组合

对于每种文本角色，记录近似字号、字重、颜色、行高、对齐方式和可用框尺寸。除非参考图明确采用 SIGMOD 风格的运行示例，否则不要套用 SIGMOD 运行示例的字号基线。

将每处文本更改都视为框模型更改：

文本 -> 文本框 -> 卡片/行 -> 容器面板 -> 相邻布局。

严重缺陷：

• 文本视觉上变大，但背景卡片/面板未调整尺寸
• 文本框高度小于渲染后的文本高度
• 文本贴近边框、与图标重叠，或超出行/卡片
• 空间充足时仍出现参考图中没有的不自然换行
• 父级卡片能容纳文本，却无法完整放入面板
• 页脚或幻灯片边界挤入内容区域

默认工作流

1. 确认参考图和目标输出目录。
2. 处理文件夹或多张图片时，创建或更新批次清单。
3. 为每张图片创建参考图清单和样式令牌说明。
4. 尽可能使用 Draw.io 原生元素重建图示中的文本和结构。
5. 根据媒介选择规则对每个非文本视觉元素进行分类。
6. 复杂或风格特定的视觉元素使用源图裁剪或透明 PNG；仅对符合形状/风格匹配要求的简单清晰图标使用 SVG/原生元素。
7. 使用 Draw.io CLI 导出 PNG 预览。
8. 运行检查器。任何布局失败都应视为阻断缺陷，而非警告。
9. 以原尺寸逐项对照参考图进行完整视觉审查。
10. 反复调整布局、尺寸、对齐、字号、裁剪、图标和箭头，直到技术检查和视觉审查均通过。
11. 报告已更改的文件和仍存在的质量风险。

默认输出：

• <name>.drawio
• <name>.png
• 批量或复杂重建任务需提供 <name>.audit.md

强制视觉审查

最终回复前，必须以原尺寸对照参考图检查导出的 PNG，并明确核查清单中的每一项。

阻断缺陷：

• 缺少可见元素
• 使用通用替代图标
• 图标/插图的风格、描边、比例或内部细节错误
• 曲线、环路、虚线路径、箭头路线、箭头头部或连接线层叠顺序错误
• 标题/正文的字号、字重、换行、颜色或对齐方式错误
• 文本重叠、裁切、贴边，或参考图中没有的不自然换行
• 面板/卡片尺寸、圆角、阴影、边框或间距错误
• 背景不匹配、缺少渐变/网格/纹理，或页面边界错误
• 裁剪接缝、模糊、光晕、透明度不佳、裁剪边界错误，或裁剪中包含相邻内容
• 仅通过脚本检查，未与参考图进行对照
• 清单中仍有任何项目标记为 needs-fix

如果有任何项目不合格，请继续编辑。不得将该图示作为成品提交。

对于批量任务，父 Agent 必须在最终回复前打开每个导出的预览和每个工作 Agent 的审查文件。工作 Agent 完成任务并不代表交付验收通过。

使用用户认可的参考图示

如果用户提供了手动调整过的截图或 .drawio 文件作为质量参考，在修改其他图示前，应先将其用作样式来源。

如有 .drawio 文件，优先使用它，因为其中包含实际几何信息：

• 按语义角色提取字号。
• 提取几何比例：卡片宽/高、标题/正文文本框高度、图标尺寸、角色标签高度、证据面板高度、结果行高度和内边距。
• 在主观调整视觉效果前，将这些基于角色的数值应用到目标图示。
• 保留目标图示中的文字。仅使用参考图调整字体排版、间距、图标尺寸和布局密度。
• 如果参考 .drawio 的页面元数据已过时，但仍能正确导出，则使用内容边界框和导出的 PNG 进行验证。

红线反馈

如果用户提供了带有红框或注释的截图：

• 将每个标记区域视为阻断性缺陷。
• 除非用户要求，否则不要将请求重新理解为重新构建。
• 首先修复标记区域中的容纳、裁切、溢出、错误裁剪、图标样式错误、箭头路径错误和字体错误。
• 保留用户当前的文本和手动修改。
• 如果红框标记的是卡通／插画／视觉隐喻，可考虑用参考图裁剪替代 SVG 重绘。

验证

编辑后始终验证 .drawio：

python "$SKILL_DIR/scripts/check_drawio.py" path/to/file.drawio
python "$SKILL_DIR/scripts/export_drawio.py" path/to/file.drawio path/to/preview.png

对于批处理任务：

python "$SKILL_DIR/scripts/batch_manifest.py" path/to/images --output-dir path/to/output --write
python "$SKILL_DIR/scripts/batch_verify.py" path/to/output/drawio_batch_manifest.json

检查器会检测 XML 有效性和常见的容纳问题；但它不能替代视觉检查。导出后，请在最终回复前对照参考图检查渲染后的 PNG。

最终回复

最终回复保持简短：

• 提供 .drawio 文件链接。
• 提供渲染后的 .png 预览链接。
• 说明主要视觉元素使用了裁剪图还是 SVG／原生元素。
• 说明是否还有待人工检查的事项，尤其是尚未解决的视觉审核项。