---
name: drawio-diagram-builder
description: 创建、编辑、复刻并迭代精修 diagrams.net/draw.io（.drawio XML）格式的可编辑科研与技术图表。
适用于以下场景：根据提示词、论文、代码仓库、截图或现有图表生成内容；被要求绘制科学插图、论文方法图、机器学习/系统架构图、draw.io 文件；复刻参考图；利用浏览器截图反馈循环进行优化；在 Windows 环境下安全预览 draw.io；以及修复文本重叠、箭头样式、配色、图标、字体和组件对齐等布局问题。
---

# 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 directory）。解析方式如 `<skill-dir>/scripts/serve_drawio_preview.py`。若找不到技能目录，请检查 Agent 的已安装技能路径（如 `~/.claude/<skill-dir>/` 或 `~/.codex/<skill-dir>/`）。

如果 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:<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` 错误；**不得依赖 `.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 <skill-dir>/scripts/validate_visual_quality.py <file>.drawio
  ```

  **首次生成预览 HTML 前，FAIL 数量必须为 0。** 逐条审查 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 → 重新生成 → 逐一验证修复效果。
- 将截图与参考图或需求规格进行对比。
- **截图必须是仅包含画布的裁剪图，而非完整浏览器窗口。** 完整浏览器截图包含侧边栏、工具栏等界面元素，导致图表占比过小，无法辨认文字、图标细节或间距问题。**若图表占截图面积不足 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 分打分：

| 维度                    | 得分 (1-10) |
| ----------------------- | ----------- |
| 文本可读性              | /10         |
| 箭头准确性              | /10         |
| 色彩协调性              | /10         |
| 布局一致性              | /10         |
| 样式匹配度（参考/规格） | /10         |
| **总分**                | **/50**     |

- **总分 < 30 或任意维度 ≤ 4 → 阻断。** 继续迭代，不得询问，直接修复。
- **总分 30–39（且无维度 ≤ 4）→ 临界。** 列出至少 5 项具体待优化点。仅在用户明确要求快速交付时才可交付。
- **总分 ≥ 40 且各维度 ≥ 6 → 允许交付。** 得分为 5 的维度属于临界状态，交付前必须复查改进。
- 每扣一分必须引用截图上可见的具体证据。
- **硬性门槛：红队审计已完成并记录。** 红队环节必须发现至少 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 打开大型图表。改用本地预览 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 编写的标签（如 `<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`：构建本地短 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 科研图表模板？
