drawio-diagram-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Research Draw.io Diagram Builder

科研Draw.io图表构建工具

Prerequisites

前置条件

Before starting, verify these are available. If anything is missing, tell the user immediately — do not proceed without them.

Requirement	Why
Python 3 (3.7+)	All preview/validation scripts are Python. Run `python --version` to check.
Browser automation	The iterative refinement loop depends on taking screenshots of a local preview. You need one of: Playwright MCP, Puppeteer MCP, browser-evaluate/screenshot tools, or equivalent.
Vision / image-reading tool (required when user provides reference images as style guides)	Style extraction (see `references/style-extraction.md` ) requires sampling pixel colors from reference images. You need one of: vision-capable model with image reading, a color-picker MCP/browser tool, or the ability to ask the user for hex codes. Without this, you CANNOT complete the style extraction table — do not fabricate hex codes. Fallback: ask the user for the palette.
Internet access	Preview loads `https://embed.diagrams.net/` in an iframe. Offline won't work.
File write access	You will create `.drawio` files.

Script paths in this document are relative to the skill directory. Resolve them like

<skill-dir>/scripts/serve_drawio_preview.py

. If you can't find the skill directory, look under the agent's installed skills path (e.g.,

~/.claude/skills/drawio-diagram-builder/

~/.codex/skills/drawio-diagram-builder/

If Playwright reports a missing bundled browser, first try an installed browser channel before giving up, for example

npx playwright screenshot --channel chrome ...

--channel msedge ...

开始前，请确认以下条件已满足。若有缺失，请立即告知用户——未满足条件不得继续操作。

要求	原因
Python 3（3.7及以上版本）	所有预览/验证脚本均基于Python开发。运行 `python --version` 检查版本。
浏览器自动化工具	迭代优化流程依赖于对本地预览内容截图。需具备以下工具之一：Playwright MCP、Puppeteer MCP、浏览器评估/截图工具或同类替代工具。
视觉/图像识别工具（当用户提供参考图片作为风格指南时必填）	风格提取（详见 `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 ...

。

Core Principle

核心原则

Produce an editable draw.io diagram first, especially for research and technical figures. Do not use an embedded screenshot as the final answer when the user asks for redraw, replica, vector, editable, or 100% reproduction. Raster images may be used only as references, temporary overlays, or explicitly approved assets.

Prefer direct

.drawio

XML authoring plus browser screenshot feedback for complex or high-fidelity diagrams. Use local draw.io UI control only when it materially improves inspection or user handoff.

优先生成可编辑的draw.io图表，尤其是科研和技术类图表。当用户要求重绘、复刻、矢量图、可编辑或100%复刻时，不得将嵌入截图作为最终成果。栅格图像仅可作为参考、临时叠加层或经明确批准的资源使用。

对于复杂或高保真图表，优先采用直接编写

.drawio

XML结合浏览器截图反馈的方式。仅当能显著提升检查或用户交接体验时，才使用本地draw.io UI控件。

Tool Strategy

工具策略

Use this priority order:

Direct
.drawio
XML generation/editing — reliable, reproducible. Write XML with explicit
```
mxGeometry
```
positions.
Local preview HTML + diagrams.net iframe postMessage — run
```
scripts/serve_drawio_preview.py
```
(one command, starts server + opens browser) or
```
scripts/make_drawio_preview.py
```
+
```
python -m http.server
```
. This keeps the browser URL short, avoiding the Windows long-URL crash.
Browser automation screenshots — navigate browser to
```
http://127.0.0.1:<port>/drawio-preview.html
```
, wait for the draw.io embed to load (2-5 seconds), take a full-page or viewport screenshot. This is the evidence you compare against the reference.
draw.io MCP /
@drawio/mcp
— only for small diagrams or quick opening. On Windows, large encoded URLs fail with
```
The data area passed to a system call is too small
```
; do not rely on
```
.url
```
shortcuts for large XML.
draw.io desktop/CLI export — if installed. Treat as optional; always have the local iframe preview fallback.

Load

references/drawio-workflow.md

for the detailed end-to-end process. Load

references/self-supervision-and-intake.md

for any non-trivial diagram, mixed prompt-plus-image input, project-context diagram, or iterative visual repair. Load

references/style-extraction.md

when the user provides reference images as style guides — mandatory before authoring XML; you must extract palette, typography, spacing, and arrow grammar before drawing. Load

references/topconf-paper-style.md

when the user asks for a computer-science paper, top-conference, camera-ready, method, ML pipeline, multimodal architecture, benchmark, or polished research figure, especially when the user gives weak or missing style references. Load

references/xml-authoring.md

when writing or repairing XML shapes, styles, edges, and text layout. Load

references/xml-preflight.md

before rendering any diagram — it documents static XML quality checks that catch computable defects (arrow-box collisions, text overflow, spacing variance, color chaos) without a screenshot. Load

references/primitive-icons.md

when a reference figure contains small modality, memory, warning, tool, clock, document, or other paper-style icons that should remain editable. Load

assets/icons/ICON-MANIFEST.md

when generic SVG icon assets would improve fidelity.

For any reference-image replication request, load

references/reference-replication-protocol.md

before creating XML. This is mandatory. Treat high-fidelity replication as an evidence pipeline: observe the reference, specify geometry, author XML, render, compare, patch, and repeat. Do not start drawing from a reference image until the protocol's required intermediate artifacts exist.

Resolve all references relative to the skill directory.

请按以下优先级使用工具：

直接生成/编辑
.drawio
XML——可靠、可复现。编写带有明确
```
mxGeometry
```
位置的XML。
本地预览HTML + diagrams.net iframe postMessage——运行
```
scripts/serve_drawio_preview.py
```
（单条命令，启动服务器并打开浏览器）或
```
scripts/make_drawio_preview.py
```
+
```
python -m http.server
```
。此方式可缩短浏览器URL，避免Windows长URL崩溃问题。
浏览器自动化截图——导航浏览器至
```
http://127.0.0.1:<port>/drawio-preview.html
```
，等待draw.io嵌入内容加载（2-5秒），截取全页或视口截图。此截图用于与参考内容对比验证。
draw.io MCP /
@drawio/mcp
——仅适用于小型图表或快速打开场景。在Windows系统中，大型编码URL会触发“传递给系统调用的数据区域太小”错误；请勿依赖
```
.url
```
快捷方式打开大型XML文件。
drawio桌面版/CLI导出——若已安装。视为可选工具；始终保留本地iframe预览作为备选方案。

加载

references/drawio-workflow.md

查看完整端到端流程。对于非 trivial 图表、混合提示+图像输入、项目上下文图表或迭代视觉修复任务，加载

references/self-supervision-and-intake.md

。当用户提供参考图片作为风格指南时，加载

references/style-extraction.md

——编写XML前必须执行此步骤；绘制前必须提取调色板、排版、间距和箭头规则。当用户要求生成计算机科学论文、顶级会议、终稿、方法图、机器学习 pipeline、多模态架构、基准测试或精细化科研图表，且风格参考较弱或缺失时，加载

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、渲染、对比、修补、重复。在完成协议要求的中间产物前，不得开始基于参考图片绘制。

所有参考路径均相对于技能目录解析。

Standard Workflow

标准工作流程

Verify prerequisites — confirm Python 3 and browser automation are available. If not, stop and tell the user what's missing.
Collect input context
- Read the user's prompt, reference images, paper sections, codebase files, or domain notes.
- Identify the task type: research figure creation, paper-method diagramming, visual replication, architecture diagramming, repository diagramming, or iterative polish.
- Classify every input by role: content source, structure source, style source, layout source, or asset source. A style reference does not automatically define content or connector semantics.
- For top-conference paper figures with weak or missing style input, use
```
references/topconf-paper-style.md
```
  and the bundled images under
```
assets/reference-images/
```
  as style/layout fallback only. Do not invent scientific content to fill the layout.
- If exact assets are needed, locate them locally or ask for them. Do not silently replace a required logo/icon with an unrelated one.
- If reference images were provided as style guides, extract their visual language BEFORE drawing. "Looking" at a reference is not extraction. Load and follow
```
references/style-extraction.md
```
  . Fill every row of the extraction table — palette hex codes, font sizes, corner radii, stroke widths, spacing rhythms. The extracted values become your mandatory style contract. Do not skip this. When your diagram looks nothing like the reference, the root cause is almost always: no style extraction was done.
Build the diagram brief and visual specification
- For mixed inputs, prompt-only diagrams, paper/code diagrams, or any complex task, create a brief with: user goal, source inventory, requirement traceability, semantic model, style contract, and open assumptions. Use
```
references/self-supervision-and-intake.md
```
  .
- Record canvas size, major regions, hierarchy, labels, colors, line styles, fonts, arrows, icons, captions, and spacing.
- Define the meaning of every connector before drawing it: source, target, direction, fan-in/fan-out, feedback, grouping, and arrowhead placement. Do not draw arrows whose semantics you cannot explain.
- For reference-image replication, create a coordinate-level inventory: bounding boxes, text lines, highlight bars, connectors, loops, and repeated blocks.
- For paper figures, preserve exact method terminology and distinguish data construction, training, evaluation, inference, and serving flows.
- Decide what must be exact and what can be approximated.
- For reference-image replication, write the required protocol artifacts before XML:
  - ```
  visual-spec.md
```
- ```
layout-grid.md
```
  - ```
  asset-ledger.md
```
- ```
defect-log.md
```
Author the
.drawio
file
- The
```
.drawio
```
  file is the primary artifact. Preview HTML is only a derived artifact.
- Use one
```
mxfile
```
  with one or more
```
diagram
```
  pages.
- Use explicit
```
mxGeometry
```
  positions and sizes for high-fidelity work.
- Split dense text into multiple cells when line-level alignment matters.
- Build important icons and arrows with editable draw.io primitives when possible. Use
```
references/primitive-icons.md
```
  for common research-figure icon recipes before inventing one-off symbols. Use bundled SVG icons from
```
assets/icons/
```
  when fidelity matters more than primitive editability, and record them in
```
asset-ledger.md
```
  .
- Keep colors, strokes, fonts, and rounded corners consistent with the reference or requested style.
- Before rendering, run the pre-flight checker. You cannot perceive visual quality from XML alone — arrow-box collisions, text overflow, font-box mismatches, spacing chaos, palette scatter, and meaningless decorative color blocks copied from references are all invisible to you but computable from geometry:
  powershell
```
python <skill-dir>/scripts/validate_visual_quality.py <file>.drawio
```
  Zero FAILs required before the first preview HTML is generated. Review every WARN. If the checker exits non-zero, fix and re-run. Do not skip this step. Load
```
references/xml-preflight.md
```
  for the full explanation of each rule.
Preview without long URLs
- Preferred: run
```
scripts/serve_drawio_preview.py <file>.drawio --port 8765
```
  . It generates the preview HTML, starts a server, and opens the browser.
- Manual: run
```
scripts/make_drawio_preview.py <file>.drawio --out drawio-preview.html
```
  , then
```
python -m http.server 8765 --bind 127.0.0.1
```
  in the output directory.
- Open
```
http://127.0.0.1:8765/drawio-preview.html?rev=1
```
  in the browser.
- Wait 2-5 seconds for the diagrams.net embed iframe to initialize.
- Take a screenshot of the rendered diagram.
Iterate from evidence
- HARD GATE: Minimum 3 screenshot→inventory→fix→verify cycles for any high-fidelity or user-critical diagram. A first draft is never acceptable. The only exception is if the user explicitly says "stop here." Record every cycle in the defect log.
- Each cycle follows: screenshot → complete defect inventory (all 9 zones) → fix ALL P0/P1 → regenerate → verify each fix.
- Compare the screenshot against the reference or requested spec.
- The screenshot MUST be a canvas-only crop, NOT the full browser window. A full browser screenshot includes the diagrams.net sidebar, toolbar, and chrome — this shrinks the diagram so much that you cannot read text, see icon details, or spot spacing defects. The screenshot is USELESS for quality inspection if the diagram occupies less than 80% of the image.
- How to crop: After taking a full-page screenshot, locate the draw.io canvas/page rectangle (the white area where your diagram renders). Crop to that rectangle. With Playwright:
```
await page.screenshot({ clip: { x, y, width, height } })
```
  . The crop coordinates must come from the CURRENT screenshot, not from memory or XML — inspect the screenshot, find the canvas edges, then crop.
- If you cannot crop, zoom the viewport: Navigate the browser to a larger viewport (e.g., 1920×1400 or higher) and zoom out (Ctrl+-) until the full canvas is visible, then screenshot. A zoomed-out full-canvas view is better than a clipped browser chrome view.
- Invalid screenshot → do not proceed to audit. If the screenshot shows more browser UI than diagram, retake it. A blurry full-browser shot where you cannot read text is not evidence — it is a waste of an iteration cycle.
- MANDATORY: Create a COMPLETE defect inventory scanning all 9 zones (text, arrows, boxes, spacing, color, typography, layout, icons, style coherence) BEFORE fixing anything. Graduated minimum per cycle: Cycle 1 ≥30, Cycle 2 ≥15, Cycle 3 ≥8 (or ≥5 if P0=0 and self-score≥40). Do NOT fabricate false defects to hit quotas on a clean diagram. Load
```
references/self-supervision-and-intake.md
```
  Section 4.1 for the zone-by-zone scanning guide.
- MANDATORY: Fix ALL P0 and P1 defects (not just the most important ones), then verify each fix against the new screenshot. If your inventory found 40 P0/P1 items, fix all 40. Mark each as FIXED/NOT FIXED/PARTIAL/REGRESSION. A defect marked NOT FIXED means you failed — fix it again.
- Run all 5 dimensions of the self-supervision audit to cross-check your inventory: requirement audit, semantic audit, visual hygiene audit, style audit, and regression audit.
- Regenerate the preview HTML, refresh the browser (add a cache-busting
```
?rev=N
```
  ), screenshot again, and repeat.
- Name the specific defects being fixed rather than claiming broad perfection.
- For reference-image replication, append every screenshot pass to
```
defect-log.md
```
  with: observed defect, reference evidence, XML cells to change, patch summary, and remaining risk. After the first screenshot row exists, treat
```
defect-log.md
```
  as append-only.
- Before claiming improvement, run a red-team role switch on the latest screenshot. You are no longer the author. You are a hostile reviewer. Re-scan all 9 zones with fresh eyes. Minimum findings: ≥15 (≥10 if self-score ≥45/50). After 3 fix cycles, a clean diagram has <15 residual issues — real auditing finds real problems, even if only 10 of them.
- If the user points out an obvious screenshot defect, treat it as a self-supervision failure: re-open the source/reference, correct the interpretation, patch the diagram, screenshot a focused crop plus the full canvas, and record the lesson in the defect log. Then re-run the red-team audit — a user-found defect proves you missed others.
- If the first screenshot is structurally wrong, go back to
```
visual-spec.md
```
  and
```
layout-grid.md
```
  before making XML patches. A structural miss means an observation, coordinate, asset, or draw.io-rendering assumption was wrong.
Validate before handoff
- HARD GATE: Self-score card (mandatory). Before handing off, score your own diagram on a 1-10 scale:
  Dimension Score (1-10)
  Text readability /10
  Arrow accuracy /10
  Color coherence /10
  Layout consistency /10
  Style match to reference/spec /10
  TOTAL /50
  - TOTAL < 30 or any dimension ≤ 4 → BLOCKED. Continue iterating. Do not ask — just fix it.
  - TOTAL 30–39 (and no dimension ≤ 4) → BORDERLINE. List 5+ specific things you'd fix next. Ship only if user explicitly asked for a quick result.
  - TOTAL ≥ 40 and every dimension ≥ 6 → ALLOWED. A dimension scored 5 is borderline, not allowed — review and improve it.
  - Each point deducted must cite concrete, screenshot-visible evidence.
- HARD GATE: Red-team audit completed and logged. The red-team pass must find at least 15 findings (≥10 if self-score ≥45/50). If it found fewer, you did not try hard enough or the diagram is ready for handoff — check the self-score card to determine which.
- HARD GATE: At least 3 screenshot→inventory→fix→verify cycles documented in defect log (each cycle = screenshot → 9-zone inventory → fix ALL P0/P1 → regenerate → verify).
- Run
```
scripts/validate_drawio.py <file>.drawio
```
  .
- Use
```
scripts/validate_drawio.py --strict --json <file>.drawio
```
  when a CI-friendly final gate is useful, or when warnings such as off-page vertices or placeholder-like labels should block handoff.
- For reference-image replication, also run
```
scripts/validate_replication_artifacts.py <workdir> --require-screenshot-review
```
  after the latest screenshot pass. Run validation after generation/preview writes finish; do not run validators in parallel with scripts that write the same artifact directory.
- Confirm: XML parses, page count is expected, ids and references are valid, required geometry exists, no unwanted embedded raster or external images are present, captions included/removed as requested, latest screenshot reviewed.
- Provide the
```
.drawio
```
  path, the latest screenshot path, the self-score card, and the defect log summary. Leave the local preview server running if the user wants to continue iterating.

Dimension	Score (1-10)
Text readability	/10
Arrow accuracy	/10
Color coherence	/10
Layout consistency	/10
Style match to reference/spec	/10
TOTAL	/50

验证前置条件——确认Python 3和浏览器自动化工具可用。若不可用，停止操作并告知用户缺失项。
收集输入上下文
- 读取用户提示、参考图片、论文章节、代码库文件或领域说明。
- 识别任务类型：科研图表创建、论文方法图绘制、视觉复刻、架构图绘制、代码库图表绘制或迭代优化。
- 按角色对所有输入分类：内容源、结构源、风格源、布局源或资源源。风格参考并不自动定义内容或连接器语义。
- 对于风格输入较弱或缺失的顶级会议论文图表，仅可将
```
references/topconf-paper-style.md
```
  和
```
assets/reference-images/
```
  下的捆绑图片作为风格/布局备选方案。不得编造科学内容填充布局。
- 若需要特定资源，先在本地查找或向用户索要。不得擅自将所需Logo/图标替换为无关资源。
- 若用户提供参考图片作为风格指南，绘制前必须提取其视觉语言。“查看”参考图片不等于提取。加载并遵循
```
references/style-extraction.md
```
  。填写提取表格的每一行——调色板十六进制代码、字体大小、圆角半径、描边宽度、间距规则。提取的值将成为必须遵守的风格约定。不得跳过此步骤。若最终图表与参考风格差异巨大，根源几乎都是未进行风格提取。
构建图表概要和视觉规范
- 对于混合输入、仅提示图表、论文/代码图表或任何复杂任务，创建包含以下内容的概要：用户目标、源清单、需求可追溯性、语义模型、风格约定和未明确假设。参考
```
references/self-supervision-and-intake.md
```
  。
- 记录画布尺寸、主要区域、层级、标签、颜色、线条样式、字体、箭头、图标、标题和间距。
- 绘制前定义每个连接器的含义：源、目标、方向、扇入/扇出、反馈、分组和箭头位置。不得绘制无法解释语义的箭头。
- 对于参考图片复刻任务，创建坐标级清单：边界框、文本行、高亮条、连接器、循环和重复块。
- 对于论文图表，保留精确的方法术语，区分数据构建、训练、评估、推理和服务流程。
- 确定必须精确还原和可近似处理的内容。
- 对于参考图片复刻任务，编写XML前需生成以下协议产物：
  - ```
  visual-spec.md
```
- ```
layout-grid.md
```
  - ```
  asset-ledger.md
```
- ```
defect-log.md
```
编写
.drawio
文件
- ```
.drawio
```
  文件是核心产物。预览HTML仅为衍生产物。
- 使用单个
```
mxfile
```
  ，包含一个或多个
```
diagram
```
  页面。
- 高保真任务需使用明确的
```
mxGeometry
```
  位置和尺寸。
- 当需要行级对齐时，将密集文本拆分为多个单元格。
- 尽可能使用可编辑的drawio基元构建重要图标和箭头。参考
```
references/primitive-icons.md
```
  获取常见科研图标制作方案，避免创建一次性符号。当保真度优先于基元可编辑性时，使用
```
assets/icons/
```
  下的捆绑SVG图标，并在
```
asset-ledger.md
```
  中记录。
- 保持颜色、描边、字体和圆角与参考或要求风格一致。
- **渲染前必须运行预检检查器。**仅通过XML无法感知视觉质量——箭头-框碰撞、文本溢出、字体-框不匹配、间距混乱、调色板分散以及“从参考复制的无意义装饰色块”等问题均无法通过XML发现，但可通过几何计算检测：
  powershell
```
python <skill-dir>/scripts/validate_visual_quality.py <file>.drawio
```
  **生成首个预览HTML前，必须确保检查结果无FAIL项。**查看所有WARN项。若检查器返回非零值，修复后重新运行。不得跳过此步骤。加载
```
references/xml-preflight.md
```
  了解每条规则的详细说明。
无长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初始化完成。
截取渲染后图表的截图。

基于证据迭代优化

**硬性要求：任何高保真或用户关键图表，至少完成3轮“截图→缺陷清单→修复→验证”循环。**初稿永远无法达标。唯一例外是用户明确要求“到此为止”。在缺陷日志中记录每一轮循环。
每轮循环流程：截图→完整缺陷清单（覆盖全部9个区域）→修复所有P0/P1级缺陷→重新生成→验证每项修复。
将截图与参考内容或要求规范对比。
**截图必须仅包含画布区域，不得包含完整浏览器窗口。**完整浏览器截图包含diagrams.net侧边栏、工具栏和边框——这会大幅缩小图表尺寸，导致无法读取文本、查看图标细节或发现间距缺陷。若图表占比不足图像的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级缺陷，需全部修复。标记每项缺陷为已修复/未修复/部分修复/回归。标记为未修复的缺陷意味着修复失败——需重新修复。
运行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渲染假设存在错误。

交接前验证

**硬性要求：自评卡（必填）。**交接前，按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→重新生成→验证）。

维度	得分（1-10）
文本可读性	/10
箭头准确性	/10
颜色一致性	/10
布局一致性	/10
与参考/规范的风格匹配度	/10
总分	/50

运行

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
```
文件路径、最新截图路径、自评卡和缺陷日志摘要。若用户希望继续迭代，保持本地预览服务器运行。

Editing Rules

编辑规则

Edit
```
.drawio
```
files by writing or patching XML directly. For small targeted fixes, use the file editing tool (e.g., Edit/Write in Claude Code).
Preserve user files and unrelated generated files.
Keep a working copy and a handoff copy only when useful; keep them synchronized.
Never claim the diagram is complete without visual verification (a screenshot).
Never claim the diagram is complete if the latest screenshot still has a visible P0/P1 blocker: wrong connector semantics, hidden text, clipped text, missing required content, accidental overlap, or a direct violation of the user's prompt/style reference.
Never claim the diagram is complete if any hard gate is unmet: style not extracted from references, fewer than 3 screenshot cycles, no complete defect inventory across 9 zones (graduated minimum: C1≥30, C2≥15, C3≥8), no fix verification, no red-team audit (≥15 findings, or ≥10 if self-score ≥45/50), self-score below 40, or self-score has any dimension ≤ 4 (≤5 is borderline and must be improved before handoff).
When the user asks for "100% reproduction", treat that as an iterative standard: keep finding and fixing visible differences until the user accepts or identifies next issues.
For reference-image replication, never skip the intermediate artifacts. A low-quality first draw usually means the observation inventory, coordinate plan, asset ledger, or rendering assumptions were underspecified.

通过直接编写或修补XML编辑
```
.drawio
```
文件。对于小型针对性修复，使用文件编辑工具（例如Claude Code中的Edit/Write）。
保留用户文件和无关生成文件。
仅在必要时保留工作副本和交接副本；保持两者同步。
无视觉验证（截图）不得声称图表已完成。
若最新截图仍存在可见的P0/P1级阻塞问题（错误的连接器语义、隐藏文本、裁剪文本、缺失所需内容、意外重叠、直接违反用户提示/风格参考），不得声称图表已完成。
若未满足任何硬性要求（未从参考提取风格、少于3轮截图循环、无覆盖9区域的完整缺陷清单（最低要求：C1≥30、C2≥15、C3≥8）、无修复验证、无红队审核（≥15项发现，或自评≥45/50分则≥10项）、自评低于40分、自评存在任意维度≤4分（≤5分为临界状态，需改进后交接）），不得声称图表已完成。
当用户要求“100%复刻”时，将其视为迭代标准：持续发现并修复可见差异，直至用户接受或指出下一问题。
对于参考图片复刻任务，不得跳过中间产物。低质量初稿通常意味着观察清单、坐标规划、资源台账或渲染假设未明确说明。

Common Failure Handling

常见故障处理

Windows long URL failure: Do not open large diagrams through
```
.url
```
files or huge
```
#create=
```
URLs. Use local preview HTML with postMessage.
Skipping pre-flight: The most common cause of a garbage first screenshot. If you did not run
```
validate_visual_quality.py
```
before rendering, you deserve the disaster you see. Run it now, fix the FAILs, regenerate.
First screenshot is terrible: This means the pre-flight was skipped or its warnings were ignored. Go back to step 4, run
```
validate_visual_quality.py
```
, fix every FAIL, review every WARN, then re-render.
Full browser screenshot (with sidebar/toolbar): The diagram is too small to read. CROP TO THE CANVAS. Locate the white draw.io page area in the screenshot, crop to its (x, y, w, h). If you cannot crop, resize viewport to 1920×1400, zoom out (Ctrl+-), and retake. A screenshot where the diagram is < 80% of the image is invalid for quality inspection.
"I only found 8 defects": You are not scanning all 9 zones systematically. Minimum 30. Start over from zone 1, pixel by pixel. Every cell, every edge, every gap.
Saving from preview: The local preview cannot silently overwrite local files (browser sandbox). The blue Save button triggers a
```
.drawio
```
download. Move the downloaded file back to your working path before further edits.
Text overlap or overflow: Split paragraphs into smaller text cells, reduce font size, increase container width, set stable geometry, and screenshot-check.
Misaligned highlight bars: Put highlight rectangles behind individual text lines, not behind the whole paragraph.
Ugly loop arrows: Use editable curved connectors or arcs, not large Unicode arrow glyphs, unless the reference explicitly uses glyphs.
Wrong icon fidelity: Build editable approximations from primitives, or ask for/download the exact icon when exactness matters.
Missing generic icons: Check
```
assets/icons/ICON-MANIFEST.md
```
before searching the web. Use the bundled MIT-licensed Tabler SVGs for generic document, media, storage, routing, tool, metric, and status icons.
Rich text or formulas render literally: Use the safe helper pattern in
```
references/xml-authoring.md
```
; escape normal text and use deliberate raw HTML only for agent-authored tags such as
```
<i>
```
or
```
<sub>
```
.
Stale preview: Add a query string such as
```
?rev=3
```
, regenerate preview HTML, or reopen the tab.
Editor chrome hiding details: Resize viewport, zoom inside draw.io, or export a PNG if draw.io CLI is available.
Partial screenshot false positives: If the screenshot clips any page edge, retake it with a larger viewport, a lower draw.io zoom, or a canvas-only crop before judging fidelity.
Research-label drift: Re-read the source paper or code when labels start becoming generic. Prefer exact names from the source material.
Preview iframe not loading: Wait a few more seconds — the
```
embed.diagrams.net
```
iframe can take 3-5 seconds on slow connections. If it still fails, verify internet access.

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重新开始，逐像素扫描。检查每个单元格、每条边、每个间隙。
从预览保存：本地预览无法静默覆盖本地文件（浏览器沙箱限制）。蓝色保存按钮会触发
```
.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秒加载。若仍失败，验证互联网访问权限。

Bundled Helpers

捆绑辅助工具

```
VERSION
```
: installed skill version marker. Use it through
```
scripts/check_skill_update.py
```
, not by checking for a specific feature string.
```
scripts/check_skill_update.py
```
: compare the installed skill version with the canonical GitHub version.
```
scripts/make_drawio_preview.py
```
: build a local short-URL preview HTML that loads
```
.drawio
```
XML into diagrams.net via
```
postMessage
```
.
```
scripts/serve_drawio_preview.py
```
: generate the preview HTML and serve it on
```
127.0.0.1
```
with an optional browser launch.
```
scripts/validate_drawio.py
```
: parse, structurally validate, count labels/assets, and sanity-check
```
.drawio
```
files before handoff. Supports
```
--strict
```
and
```
--json
```
.
```
scripts/validate_visual_quality.py
```
: pre-render static checker. Parses
```
.drawio
```
XML and computes visual defects without rendering — arrow-box collisions, text overflow risk, font proportionality, spacing variance, color incoherence, element overlap, orphan labels, font size anomalies, and edge density. Run before first preview. Zero FAILs required. Supports
```
--json
```
,
```
--strict
```
,
```
--rules
```
.
```
assets/icons/ICON-MANIFEST.md
```
: local MIT-licensed SVG icon inventory and usage rules.
```
assets/reference-images/REFERENCE-IMAGES.md
```
: bundled top-conference-style figure references for style fallback.
```
references/drawio-workflow.md
```
: full professional workflow for prompt/paper/code/reference-image to editable draw.io.
```
references/self-supervision-and-intake.md
```
: mixed-input intake, diagram brief, mandatory 5-dimension audit, red-team role switch, self-scoring card, and hard gates before handoff.
```
references/xml-preflight.md
```
: explains every pre-render static check — what it catches, why it matters, and why XML alone blinds the agent to these defects.
```
references/style-extraction.md
```
: mandatory style extraction protocol — how to sample palettes, measure typography, identify layout rhythm, and extract arrow grammar from reference images before drawing. Use whenever the user provides style reference images.
```
references/topconf-paper-style.md
```
: top-conference computer-science figure style, fallback reference selection, and paper-quality bar.
```
references/primitive-icons.md
```
: reusable editable primitive recipes for common research-figure icons.
```
references/reference-replication-protocol.md
```
: low-freedom protocol for high-fidelity reference-image replication.
```
references/xml-authoring.md
```
: XML, layout, style, edge, text, icon, and iteration patterns.

```
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项。支持
```
--json
```
、
```
--strict
```
、
```
--rules
```
参数。
```
assets/icons/ICON-MANIFEST.md
```
：本地MIT许可SVG图标清单和使用规则。
```
assets/reference-images/REFERENCE-IMAGES.md
```
：捆绑的顶级会议风格图表参考，作为风格备选方案。
```
references/drawio-workflow.md
```
：从提示/论文/代码/参考图片到可编辑drawio图表的完整专业流程。
```
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、布局、风格、边、文本、图标和迭代模式。