drawio-diagram-builder

Research Draw.io 图表构建器

前置条件

开始前，请确认以下条件均已满足。如果缺少任何一项，请立即告知用户，不要继续操作。

要求	原因
Python 3（3.7+）	所有预览和验证脚本均使用 Python。运行 python --version 进行检查。
浏览器自动化	迭代优化流程依赖于截取本地预览的屏幕截图。你需要以下工具之一：Playwright MCP、Puppeteer MCP、browser-evaluate/screenshot 工具或同类工具。
视觉 / 图像读取工具（用户提供参考图作为风格指南时必需）	风格提取（参见 references/style-extraction.md）需要从参考图中采样像素颜色。你需要以下工具之一：支持图像读取的视觉模型、取色器 MCP/浏览器工具，或向用户询问十六进制颜色代码的能力。没有这些工具，你就无法完成风格提取表格，不要编造十六进制颜色代码。备用方案：请用户提供配色方案。
互联网访问	预览会在 iframe 中加载 https://embed.diagrams.net/。离线时无法使用。
文件写入权限	你将创建 .drawio 文件。

本文档中的脚本路径均相对于技能目录。请将其解析为 <skill-dir>/scripts/serve_drawio_preview.py。如果找不到技能目录，请在 Agent 已安装的技能路径下查找，例如 ~/.claude/skills/drawio-diagram-builder/ 或 ~/.codex/skills/drawio-diagram-builder/。

如果 Playwright 报告缺少捆绑的浏览器，请先尝试已安装的浏览器通道，再放弃，例如 npx playwright screenshot --channel chrome ... 或 --channel msedge ...。

核心原则

首先生成可编辑的 draw.io 图表，尤其是研究和技术图表。用户要求重绘、复刻、矢量、可编辑或 100% 还原时，不要将嵌入式屏幕截图作为最终答案。栅格图像仅可用作参考、临时叠加图，或明确获批的素材。

对于复杂或需要高保真还原的图表，优先直接编写 .drawio XML，并通过浏览器截图获取反馈。仅在本地 draw.io UI 操作能显著改善检查效果或用户交接时，才使用该方式。

工具策略

按以下优先级使用：

1. 直接生成／编辑 .drawio XML——可靠且可复现。编写 XML 时使用明确的 mxGeometry 位置。
2. 本地预览 HTML + diagrams.net iframe postMessage——运行 scripts/serve_drawio_preview.py（一条命令即可启动服务器并打开浏览器），或运行 scripts/make_drawio_preview.py + python -m http.server。这样浏览器 URL 会保持较短，避免 Windows 长 URL 崩溃。
3. 浏览器自动化截图——将浏览器导航至 http://127.0.0.1:<port>/drawio-preview.html，等待 draw.io 嵌入内容加载（2-5 秒），然后截取整页或视口截图。这就是你用来与参考图比较的依据。
4. draw.io MCP / @drawio/mcp——仅用于小型图表或快速打开。在 Windows 上，较大的编码 URL 会因 The data area passed to a system call is too small 而失败；大型 XML 不要依赖 .url 快捷方式。
5. draw.io 桌面版／CLI 导出——如果已安装。将其视为可选方案；务必保留本地 iframe 预览作为备用方案。

加载 references/drawio-workflow.md 以了解详细的端到端流程。对于任何非简单图表、提示词与图像混合输入、项目上下文图表或迭代式视觉修复，加载 references/self-supervision-and-intake.md。当用户提供参考图作为样式指南时，加载 references/style-extraction.md——在编写 XML 之前必须执行；绘图前必须提取配色、字体、间距和箭头规范。当用户要求计算机科学论文、顶会、终稿、方法、机器学习流水线、多模态架构、基准测试或精致的研究图时，加载 references/topconf-paper-style.md，尤其是用户提供的样式参考较弱或缺失时。编写或修复 XML 形状、样式、边和文本布局时，加载 references/xml-authoring.md。渲染任何图表前，加载 references/xml-preflight.md；其中介绍了无需截图即可发现可计算缺陷（箭头与方框碰撞、文本溢出、间距差异、配色混乱）的静态 XML 质量检查。当参考图包含应保持可编辑的论文风格小图标（如模态、记忆、警告、工具、时钟、文档等图标）时，加载 references/primitive-icons.md。当通用 SVG 图标资源有助于提高还原度时，加载 assets/icons/ICON-MANIFEST.md。

对于任何参考图复刻请求，创建 XML 前必须加载 references/reference-replication-protocol.md。这是强制要求。将高保真复刻视为一个证据流程：观察参考图、明确几何布局、编写 XML、渲染、比较、修补，然后重复。除非协议要求的中间产物已准备就绪，否则不要根据参考图开始绘图。

所有引用均相对于技能目录解析。

标准工作流

1. 验证先决条件——确认 Python 3 和浏览器自动化可用。如果不可用，请停止并告知用户缺少什么。

2. 收集输入上下文

   • 阅读用户的提示词、参考图像、论文章节、代码库文件或领域说明。
   • 确定任务类型：研究图表制作、论文方法图绘制、视觉复刻、架构图绘制、代码库图绘制或迭代润色。
   • 按角色对每项输入分类：内容来源、结构来源、风格来源、布局来源或素材来源。风格参考不会自动定义内容或连接线语义。
   • 对于风格输入较弱或缺失的顶会论文图表，使用 references/topconf-paper-style.md 和 assets/reference-images/ 下的随附图像作为风格／布局备用参考。不要为了填充布局而编造科学内容。
   • 如果需要精确素材，请在本地查找或向用户索取。不要悄悄用无关素材替换必需的徽标／图标。
   • 如果提供了参考图像作为风格指南，请在绘图之前提取其视觉语言。“看过”参考图不等于完成提取。加载并遵循 references/style-extraction.md。填写提取表中的每一行——调色板十六进制代码、字号、圆角半径、描边宽度、间距节奏。提取的数值将成为必须遵守的风格契约。不要跳过这一步。如果你的图表看起来与参考图毫不相似，根本原因几乎总是没有进行风格提取。

3. 编写图表简报和视觉规范

   • 对于混合输入、仅提示词图表、论文／代码图表或任何复杂任务，创建一份简报，包含：用户目标、来源清单、需求可追溯性、语义模型、风格契约和待确认假设。使用 references/self-supervision-and-intake.md。
   • 记录画布尺寸、主要区域、层级、标签、颜色、线条样式、字体、箭头、图标、说明文字和间距。
   • 在绘制之前，先定义每个连接线的含义：源、目标、方向、汇入／分流、反馈、分组和箭头位置。不要绘制无法解释其语义的箭头。
   • 对于参考图复刻，创建坐标级清单：边界框、文本行、高亮条、连接线、回路和重复模块。
   • 对于论文图表，保留精确的方法术语，并区分数据构建、训练、评估、推理和服务流程。
   • 确定哪些内容必须精确还原，哪些可以近似处理。
   • 对于参考图复刻，在编写 XML 之前，先创建所需的协议文件：
     • visual-spec.md
     • layout-grid.md
     • asset-ledger.md
     • defect-log.md

4. 编写 .drawio 文件

   • .drawio 文件是主要交付成果。预览 HTML 只是衍生产物。
   • 使用一个 mxfile，其中包含一个或多个 diagram 页面。
   • 为需要高保真效果的内容设置明确的 mxGeometry 位置和尺寸。
   • 需要逐行对齐时，将密集文本拆分到多个单元格中。
   • 尽可能使用可编辑的 draw.io 基本图形来构建重要图标和箭头。创建独特符号前，先使用 references/primitive-icons.md 中适用于常见研究图示的图标构建方案。对保真度的要求高于基本图形的可编辑性时，使用 assets/icons/ 中附带的 SVG 图标，并将其记录在 asset-ledger.md 中。
   • 颜色、描边、字体和圆角应与参考图或所需样式保持一致。
   • 渲染前，运行预检工具。 仅凭 XML 无法感知视觉质量——箭头与方框碰撞、文本溢出、字体框不匹配、间距混乱、配色分散，以及从参考图复制的毫无意义的装饰性色块，这些问题你都无法直接看到，但可以通过几何信息计算出来：

     python <skill-dir>/scripts/validate_visual_quality.py <file>.drawio
     

     首次生成预览 HTML 前，FAIL 必须为零。 检查每一项 WARN。如果检查器以非零状态码退出，请修复问题并重新运行。不要跳过此步骤。加载 references/xml-preflight.md，查看每条规则的完整说明。

5. 预览时避免使用长 URL

   • 推荐方式：运行 scripts/serve_drawio_preview.py <file>.drawio --port 8765。该脚本会生成预览 HTML、启动服务器并打开浏览器。
   • 手动方式：运行 scripts/make_drawio_preview.py <file>.drawio --out drawio-preview.html，然后在输出目录中运行 python -m http.server 8765 --bind 127.0.0.1。
   • 在浏览器中打开 http://127.0.0.1:8765/drawio-preview.html?rev=1。
   • 等待 2-5 秒，让 diagrams.net 嵌入式 iframe 完成初始化。
   • 截取渲染后图表的屏幕截图。

6. 根据证据迭代

   • 硬性门槛：对于任何高保真或对用户至关重要的图表，至少完成 3 轮“截图 → 清单 → 修复 → 验证”循环。 初稿永远不能接受。唯一例外是用户明确说“到此为止”。在缺陷日志中记录每一轮循环。
   • 每轮循环均按以下步骤进行：截图 → 完整缺陷清单（全部 9 个区域）→ 修复所有 P0/P1 缺陷 → 重新生成 → 验证每项修复。
   • 将截图与参考图或指定规范进行比较。
   • 截图必须仅截取画布，不能截取整个浏览器窗口。 整个浏览器截图会包含 diagrams.net 侧边栏、工具栏和浏览器边框，导致图表缩得太小，无法阅读文字、查看图标细节或发现间距缺陷。如果图表占图像面积不到 80%，该截图就无法用于质量检查。
   • 裁剪方法： 截取整页后，找到 draw.io 画布/页面矩形（图表渲染所在的白色区域），裁剪至该矩形。使用 Playwright：await page.screenshot({ clip: { x, y, width, height } })。裁剪坐标必须取自当前截图，不能凭记忆或从 XML 获取——先检查截图、找到画布边缘，再进行裁剪。
   • 如果无法裁剪，请缩放视口： 将浏览器视口调大（例如 1920×1400 或更大），然后按 Ctrl+- 缩小页面，直到完整画布可见，再截图。缩小后显示完整画布的截图，优于被浏览器边框占满的截图。
   • 截图无效 → 不得开始审查。 如果截图中的浏览器界面比图表还多，就重新截图。无法阅读文字的模糊全浏览器截图不构成证据，只会浪费一次迭代。
   • 必须在修复前扫描全部 9 个区域（文字、箭头、框、间距、颜色、排版、布局、图标、风格一致性），并建立完整缺陷清单。 每轮最低缺陷数逐轮递减：第 1 轮 ≥30，第 2 轮 ≥15，第 3 轮 ≥8（如果 P0=0 且自评分 ≥40，则可为 ≥5）。不要为了达到配额，在整洁的图表中捏造缺陷。请查阅 references/self-supervision-and-intake.md 第 4.1 节，了解逐区域扫描指南。
   • 必须修复所有 P0 和 P1 缺陷（不能只修最重要的），然后对照新截图逐项验证。 如果清单中有 40 项 P0/P1 缺陷，就必须全部修复。每项均标记为 FIXED/NOT FIXED/PARTIAL/REGRESSION。标记为 NOT FIXED 意味着你未能修复——请再次修复。
   • 执行自我监督审查的全部 5 个维度，交叉核对缺陷清单：需求审查、语义审查、视觉整洁度审查、风格审查和回归审查。
   • 重新生成预览 HTML、刷新浏览器（添加缓存破坏参数 ?rev=N），再次截图并重复上述流程。
   • 指明具体修复了哪些缺陷，不要泛称图表已臻完美。
   • 对于参考图复刻，将每轮截图检查记录追加到 defect-log.md，包括：观察到的缺陷、参考图证据、需要修改的 XML 单元格、补丁摘要和剩余风险。添加第一条截图记录后，defect-log.md 必须只允许追加内容。
   • 在宣称有所改进之前，必须切换到红队角色审查最新截图。 此时你不再是作者，而是挑剔的审查者。重新审查全部 9 个区域，保持全新视角。最少发现数：≥15（如果自评分 ≥45/50，则 ≥10）。经过 3 轮修复后，整洁的图表残留问题应少于 15 项——真正的审查总能发现实际问题，即使只有 10 项也一样。
   • 如果用户指出了明显的截图缺陷，应视为自我监督失败：重新打开源文件/参考图，纠正理解，修补图表，截取局部重点区域和完整画布的截图，并在缺陷日志中记录经验。然后重新执行红队审查——用户发现一项缺陷，说明你还漏掉了其他问题。
   • 如果第一张截图在结构上有误，应先返回 visual-spec.md 和 layout-grid.md，再修改 XML。结构性错误意味着观察结果、坐标、素材或 draw.io 渲染方面的假设有误。

7. 交付前验证

   • 硬性门槛：自评分卡（必填）。 交付前，为自己的图表打分，范围为 1–10 分：

     维度	评分（1–10）
     文本可读性	/10
     箭头准确性	/10
     色彩协调性	/10
     布局一致性	/10
     与参考图／规范的风格匹配度	/10
     总分	/50

     • 总分 < 30 或任一维度 ≤ 4 → 阻止交付。 继续迭代。不要询问，直接修复。
     • 总分为 30–39（且没有维度 ≤ 4）→ 临界。 列出至少 5 项接下来要修复的具体问题。只有用户明确要求快速出结果时才交付。
     • 总分 ≥ 40 且每个维度 ≥ 6 → 允许交付。 某维度得分为 5 属于临界，不允许交付——检查并改进。
     • 每扣 1 分都必须指出截图中可见的具体证据。
   • 硬性门槛：已完成并记录红队审查。 红队审查必须发现至少 15 项问题（自评分 ≥45/50 时至少 10 项）。如果发现的问题更少，说明审查不够深入，或者图表已达到交付标准——查看自评分卡，判断属于哪种情况。
   • 硬性门槛：缺陷日志中至少记录 3 次“截图→清单→修复→验证”循环（每次循环 = 截图 → 9 区域清单 → 修复所有 P0/P1 问题 → 重新生成 → 验证）。
   • 运行 scripts/validate_drawio.py <file>.drawio。
   • 在需要适用于 CI 的最终门槛检查时，或在页外顶点、类似占位符的标签等警告必须阻止交付时，使用 scripts/validate_drawio.py --strict --json <file>.drawio。
   • 对于参考图复刻，在最新一轮截图审查后，还要运行 scripts/validate_replication_artifacts.py <workdir> --require-screenshot-review。等待生成／预览写入完成后再运行验证；不要与会写入同一产物目录的脚本并行运行验证器。
   • 确认：XML 可解析，页面数量符合预期，ID 和引用有效，所需几何图形存在，没有不需要的嵌入栅格图像或外部图像，按要求包含／移除了标题，且已审查最新截图。
   • 提供 .drawio 路径、最新截图路径、自评分卡和缺陷日志摘要。如果用户想继续迭代，请保持本地预览服务器运行。

编辑规则

• 直接编写或修补 XML 来编辑 .drawio 文件。对于小范围定向修复，请使用文件编辑工具（例如 Claude Code 中的 Edit/Write）。
• 保留用户文件和无关的生成文件。
• 仅在有用时保留工作副本和交付副本；确保两者保持同步。
• 未进行视觉验证（截图）时，绝不要声称图表已完成。
• 如果最新截图仍有明显的 P0/P1 阻断问题：连接线语义错误、文本被遮挡、文本被裁切、缺少必需内容、意外重叠，或直接违反用户的提示词／风格参考，绝不要声称图表已完成。
• 如果任何硬性门槛未达标，绝不要声称图表已完成：尚未从参考图中提取风格、截图循环少于 3 次、未完成覆盖 9 个区域的缺陷清单（分级最低要求：C1≥30，C2≥15，C3≥8）、未验证修复、未进行红队审查（≥15 项问题；自评分 ≥45/50 时 ≥10 项）、自评分低于 40，或任一维度 ≤ 4（≤5 属于临界，交付前必须改进）。
• 用户要求“100% 复刻”时，将其视为迭代标准：持续查找并修复可见差异，直到用户接受或指出下一处问题。
• 对于参考图复刻，绝不要跳过中间产物。初稿质量差通常意味着观察清单、坐标规划、素材台账或渲染假设定义不充分。

常见故障处理

• Windows 长 URL 故障：不要通过 .url 文件或超长的 #create= URL 打开大型图表。请使用带有 postMessage 的本地预览 HTML。
• 跳过预检：这是导致首张截图惨不忍睹的最常见原因。如果渲染前没有运行 validate_visual_quality.py，那你看到的灾难就是自找的。现在就运行它，修复所有 FAIL，然后重新生成。
• 首张截图很糟糕：这说明你跳过了预检，或忽略了预检警告。返回第 4 步，运行 validate_visual_quality.py，修复每个 FAIL，检查每个 WARN，然后重新渲染。
• 完整浏览器截图（含侧边栏/工具栏）：图表太小，无法阅读。请裁剪到画布范围。找到截图中的白色 draw.io 页面区域，并按其 (x, y, w, h) 裁剪。如果无法裁剪，请将视口调整为 1920×1400，缩小页面（Ctrl+-），然后重新截图。图表面积不足图像 80% 的截图，不适用于质量检查。
• “我只发现了 8 个缺陷”：你没有系统地扫描全部 9 个区域。至少要找出 30 个。从第 1 区重新开始，逐像素检查。每个单元格、每条边、每个间隙都要检查。
• 从预览中保存：本地预览无法静默覆盖本地文件（浏览器沙盒限制）。蓝色的 Save 按钮会触发 .drawio 文件下载。继续编辑前，请将下载的文件移回工作路径。
• 文本重叠或溢出：将段落拆分到更小的文本单元格中，减小字号，增加容器宽度，设置稳定的几何属性，并通过截图检查。
• 高亮条未对齐：将高亮矩形放在每一行文字后面，而不是整个段落后面。
• 循环箭头难看：使用可编辑的弯曲连接线或弧线，而不是大型 Unicode 箭头字符，除非参考图明确使用了字符。
• 图标还原度不佳：使用基本图形构建可编辑的近似图标；如果必须精确还原，请索要或下载准确图标。
• 缺少通用图标：搜索网络前先检查 assets/icons/ICON-MANIFEST.md。通用文档、媒体、存储、路由、工具、指标和状态图标，请使用捆绑的 MIT 许可证 Tabler SVG。
• 富文本或公式按字面显示：使用 references/xml-authoring.md 中的安全辅助模式；转义普通文本，并仅对 Agent 编写的 <i> 或 <sub> 等标签有意使用原始 HTML。
• 预览内容过时：添加 ?rev=3 这类查询字符串、重新生成预览 HTML，或重新打开标签页。
• 编辑器界面遮挡细节：调整视口大小，在 draw.io 中缩放，或在 draw.io CLI 可用时导出 PNG。
• 截图不完整导致误报：如果截图裁掉了页面的任何边缘，请使用更大的视口、较低的 draw.io 缩放比例，或仅裁剪画布后重新截图，再判断还原度。
• 研究标签偏移：标签开始变得笼统时，重新阅读源论文或代码。优先使用源材料中的准确名称。
• 预览 iframe 未加载：再等几秒——网络较慢时，embed.diagrams.net iframe 可能需要 3-5 秒。如果仍未加载，请确认网络连接正常。

内置辅助工具

• VERSION：已安装技能的版本标记。请通过 scripts/check_skill_update.py 使用它，而不是检查特定功能字符串。
• scripts/check_skill_update.py：将已安装技能的版本与 GitHub 上的规范版本进行比较。
• scripts/make_drawio_preview.py：构建本地短网址预览 HTML，通过 postMessage 将 .drawio XML 加载到 diagrams.net。
• scripts/serve_drawio_preview.py：生成预览 HTML，并在 127.0.0.1 上提供服务，可选择启动浏览器。
• scripts/validate_drawio.py：在交付前解析并进行结构验证，统计标签和素材数量，并对 .drawio 文件进行合理性检查。支持 --strict 和 --json。
• scripts/validate_visual_quality.py：**渲染前静态检查器。**解析 .drawio XML 并计算视觉缺陷，无需渲染，包括箭头与方框碰撞、文本溢出风险、字体比例、间距差异、颜色不协调、元素重叠、孤立标签、字号异常和边密度。请在首次预览前运行。必须确保 FAIL 数为零。支持 --json、--strict 和 --rules。
• assets/icons/ICON-MANIFEST.md：本地采用 MIT 许可证的 SVG 图标清单及使用规则。
• assets/reference-images/REFERENCE-IMAGES.md：内置顶级会议风格图示参考，用作风格回退方案。
• references/drawio-workflow.md：从提示词、论文、代码或参考图像生成可编辑 draw.io 图示的完整专业工作流。
• references/self-supervision-and-intake.md：混合输入接收、图示简报、强制五维审查、红队角色切换、自评卡，以及交付前的硬性门槛。
• references/xml-preflight.md：说明每项渲染前静态检查的内容、重要性，以及为何仅凭 XML 会让 Agent 无法察觉这些缺陷。
• references/style-extraction.md：强制风格提取流程，说明如何从参考图像采样调色板、测量字体、识别布局节奏并提取箭头语法。用户提供风格参考图像时务必使用。
• references/topconf-paper-style.md：顶级计算机科学会议的图示风格、回退参考选择方式及论文质量标准。
• references/primitive-icons.md：常见研究图示图标的可复用、可编辑基础图形制作方案。
• references/reference-replication-protocol.md：高保真复现参考图像的低自由度流程。
• references/xml-authoring.md：XML、布局、样式、边、文本、图标和迭代模式。