Drawio Diagram Builder

Research Draw.io 图表构建器（中文版）

前置条件

开始前请先确认以下条件已满足。如有缺失，立即告知用户并停止执行，不得继续。

本文档中的脚本路径均相对于技能目录（skill directory）。解析方式如 /scripts/serve_drawio_preview.py。若找不到技能目录，请检查 Agent 的已安装技能路径（如 ~/.claude// 或 ~/.codex//）。

如果 Playwright 提示缺少内置浏览器，可先尝试已安装的浏览器通道，例如 npx playwright screenshot --channel chrome ... 或 --channel msedge ...，再考虑放弃。

---

核心原则

优先产出可编辑的 draw.io 图表，尤其适用于科研和技术插图。当用户明确要求重绘、复刻、矢量图、可编辑或 100% 还原时，不得将嵌入的截图作为最终答案。 栅格图片仅可作为参考、临时叠加层或经明确批准的资产使用。

对于复杂或高保真图表，优先采用直接编写 .drawio XML + 浏览器截图反馈的方式。仅在能显著改善检查或用户交接体验时，才使用本地 draw.io UI 控制。

---

工具策略（优先级从高到低）

1. 直接生成 / 编辑 .drawio 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:/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 错误；不得依赖 .url 快捷方式加载大 XML。
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：用户要求计算机科学论文、顶会、相机就绪、方法图、ML 流水线、多模态架构、评测基准或精美科研插图，且样式参考薄弱或缺失时使用。
• references/xml-authoring.md：编写或修复 XML 形状、样式、边和文本布局时的必读。
• references/xml-preflight.md：渲染前静态 XML 质量检查清单，可无需截图发现箭头碰撞、文本溢出、间距异常、颜色混乱等问题。
• references/primitive-icons.md：参考图中包含模态、内存、警告、工具、时钟、文档等论文风格小图标时使用，确保图标保持可编辑性。
• assets/icons/ICON-MANIFEST.md：通用 SVG 图标资产清单，用于提升保真度。
• references/reference-replication-protocol.md：参考图复刻请求时必须首先加载。将高保真复刻视为证据管道：观察 → 规格定义 → 编写 XML → 渲染 → 对比 → 修补 → 重复。在未生成协议要求的中间产物前，不得开始绘图。

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

---

标准工作流

1. 验证前置条件

确认 Python 3 和浏览器自动化可用。否则立即停止并告知用户缺失项。

2. 收集输入上下文

• 阅读用户提示、参考图片、论文章节、代码库文件或领域说明。
• 识别任务类型：科研插图创作、论文方法绘图、视觉复刻、架构图、仓库结构图或迭代精修。
• 为每项输入标注角色：内容来源、结构来源、样式来源、布局来源或资产来源。样式参考不自动定义内容或连线语义。
• 对于顶会论文插图且样式输入薄弱的情况，使用 references/topconf-paper-style.md 及 assets/reference-images/ 下的图片作为样式/布局兜底，不得为填满布局而编造科学内容。
• 若需要精确资产，先在本地查找，必要时向用户索取。不得用无关图标静默替换必需 Logo/图标。
• 若用户提供参考图片作为样式指南，必须在绘图前进行视觉语言提取。 “看一眼”不等于提取。加载并严格遵循 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 /scripts/validate_visual_quality.py .drawio
  

  首次生成预览 HTML 前，FAIL 数量必须为 0。 逐条审查 WARN。若检查器返回非零退出码，修复后重新运行。不得跳过此步骤。详见 references/xml-preflight.md。

5. 预览（避免长 URL）

• 首选：scripts/serve_drawio_preview.py .drawio --port 8765。自动生成预览 HTML、启动服务并打开浏览器。
• 手动：scripts/make_drawio_preview.py .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 → 重新生成 → 逐一验证修复效果。
• 将截图与参考图或需求规格进行对比。
• 截图必须是仅包含画布的裁剪图，而非完整浏览器窗口。 完整浏览器截图包含侧边栏、工具栏等界面元素，导致图表占比过小，无法辨认文字、图标细节或间距问题。若图表占截图面积不足 80%，该截图无效。
• 裁剪方法：截取全页后，定位 draw.io 画布/页面矩形（通常为白色绘图区），按该区域裁剪。Playwright 示例：await page.screenshot({ clip: { x, y, width, height } })。裁剪坐标必须来自当前截图，而非记忆或 XML——先检查截图，找到画布边缘，再裁剪。
• 无法裁剪时，放大视口：导航至更大视口（如 1920×1400），缩小页面（Ctrl+-）直至完整画布可见，再截图。缩小后的全画布视图优于带浏览器边框的裁剪视图。
• 无效截图 → 不得进入审计环节。 若截图显示浏览器 UI 多于图表，重新截图。模糊到无法辨认文字的全浏览器截图不是证据，而是浪费迭代周期。
• 强制性：在修复任何问题前，必须创建覆盖全部 9 个区域的完整缺陷清单（文本、箭头、方框、间距、颜色、排版、布局、图标、样式一致性）。渐进最低要求：第 1 轮 ≥30 项，第 2 轮 ≥15 项，第 3 轮 ≥8 项（若 P0=0 且自评 ≥40 分可放宽至 ≥5 项）。不得在图表干净的情况下为了凑数而编造虚假缺陷。 分区扫描指南见 references/self-supervision-and-intake.md 第 4.1 节。
• 强制性：修复所有 P0 和 P1 缺陷（而非仅最重要几项），并在新截图中逐一验证。 若清单列出 40 个 P0/P1，则必须修复 40 个。标记每个缺陷状态：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 分打分：

• 总分 < 30 或任意维度 ≤ 4 → 阻断。 继续迭代，不得询问，直接修复。
• 总分 30–39（且无维度 ≤ 4）→ 临界。 列出至少 5 项具体待优化点。仅在用户明确要求快速交付时才可交付。
• 总分 ≥ 40 且各维度 ≥ 6 → 允许交付。 得分为 5 的维度属于临界状态，交付前必须复查改进。
• 每扣一分必须引用截图上可见的具体证据。
• 硬性门槛：红队审计已完成并记录。 红队环节必须发现至少 15 项问题（自评 ≥45/50 分时 ≥10 项）。若少于此数，要么是你不够认真，要么是图表确实已达标——结合自评卡判断。
• 硬性门槛：缺陷日志中至少记录 3 次完整截图→清单→修复→验证循环（每轮 = 截图 → 9 区清单 → 修复所有 P0/P1 → 重新生成 → 验证）。
• 运行 scripts/validate_drawio.py .drawio。
• 当需要 CI 友好的最终关卡，或警告（如跨页顶点、占位符式标签）应阻断交付时，使用 scripts/validate_drawio.py --strict --json .drawio。
• 参考图复刻时，还需在最新截图轮次后运行 scripts/validate_replication_artifacts.py --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 打开大型图表。改用本地预览 HTML + postMessage。
• 跳过预检：这是首张截图惨不忍睹的最常见原因。若未在渲染前运行 validate_visual_quality.py，后果自负。立即运行，修复所有 FAIL，再审阅 WARN，然后重新渲染。
• 首张截图质量极差：说明预检被跳过或其警告被忽略。回到第 4 步，运行 validate_visual_quality.py，修复所有 FAIL，审阅所有 WARN，再重新渲染。
• 完整浏览器截图（含侧边栏/工具栏）：图表过小无法辨认。裁剪至画布区域。在截图中定位白色 draw.io 页面区域，按 (x, y, w, h) 裁剪。无法裁剪时，将视口调整为 1920×1400，缩小页面（Ctrl+-）后重拍。图表占比不足截图 80% 的截图无效，不可用于质量检查。
• “我只找到 8 个缺陷”：未系统扫描全部 9 个区域。最低要求 30 项。从第 1 区开始，逐像素扫描。每个单元格、每条边、每个间隙都不能放过。
• 从预览保存：本地预览受浏览器沙箱限制，无法静默覆盖本地文件。蓝色“保存”按钮会触发 .drawio 下载。将下载的文件移回工作路径后再继续编辑。
• 文本重叠或溢出：将段落拆分为更小的文本单元格，减小字号，增大容器宽度，设置稳定几何属性，并通过截图验证。
• 高亮条错位：将高亮矩形置于单行文本后方，而非整个段落后方。
• 难看的循环箭头：使用可编辑的曲线连线或弧线，而非大型 Unicode 箭头符号，除非参考图明确使用符号。
• 图标保真度错误：用原语构建可编辑近似图形，或在精确度至关重要时索要/下载精确图标。
• 缺少通用图标：先检查 assets/icons/ICON-MANIFEST.md，再上网搜索。优先使用捆绑的 MIT 许可 Tabler SVG 作为文档、媒体、存储、路由、工具、指标和状态图标。
• 富文本或公式被字面渲染：使用 references/xml-authoring.md 中的安全辅助模式；转义普通文本，仅对 Agent 编写的标签（如 、）使用原始 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：构建本地短 URL 预览 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 数为 0 方可继续。支持 --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：混合输入需求收集、图表简报、强制性 5 维审计、红队角色切换、自评打分卡及交付前硬性门槛。
• 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、布局、样式、边、文本、图标及迭代模式指南。

---

是否需要我基于这个中文规范，帮你直接创建一个符合顶会风格的 draw.io 科研图表模板？