Create, edit, replicate, and iteratively refine editable research and technical diagrams in diagrams.net/draw.io (.drawio XML) from prompts, papers, repositories, screenshots, or existing diagrams. Use when asked to generate a scientific figure, paper method diagram, ML/system architecture diagram,
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 控制。
工具策略(优先级从高到低)
- 直接生成 / 编辑
.drawioXML —— 可靠、可复现。务必使用显式mxGeometry定位。 - 本地预览 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 会触发The data area passed to a system call is too small错误;不得依赖.url快捷方式加载大 XML。 - 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.mdlayout-grid.mdasset-ledger.mddefect-log.md
4. 编写 .drawio 文件
-
.drawio文件是首要产物,预览 HTML 仅为派生产物。 -
使用单个
mxfile,内含一个或多个diagram页面。 -
高保真工作务必使用显式
mxGeometry位置和尺寸。 -
当行级对齐重要时,将密集文本拆分为多个单元格。
-
重要图标和箭头优先使用可编辑的 draw.io 原语构建。参考
references/primitive-icons.md获取常见科研图标配方。保真度优先时可从assets/icons/使用捆绑 SVG,并在asset-ledger.md中记录。 -
保持颜色、描边、字体和圆角与参考或需求一致。
-
渲染前必须运行预检检查器。 仅凭 XML 无法感知视觉质量——箭头-方框碰撞、文本溢出、字体-框不匹配、间距混乱、调色板分散以及无意义照搬参考图的装饰色块等问题对你不可见,但可通过几何计算发现:
text 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.netiframe 在慢速网络下可能需要 3–5 秒。若仍失败,检查网络连接。
捆绑辅助工具
VERSION:已安装技能版本标记。通过scripts/check_skill_update.py使用,而非检查特定功能字符串。scripts/check_skill_update.py:比对已安装技能版本与 GitHub 官方版本。scripts/make_drawio_preview.py:构建本地短 URL 预览 HTML,通过postMessage将.drawioXML 加载进 diagrams.net。scripts/serve_drawio_preview.py:生成预览 HTML 并在127.0.0.1上提供服务,可选择自动打开浏览器。scripts/validate_drawio.py:解析、结构验证、统计标签/资产并对.drawio文件进行交付前完整性检查。支持--strict和--json。scripts/validate_visual_quality.py:渲染前静态检查器。解析.drawioXML,无需渲染即可计算视觉缺陷——箭头-方框碰撞、文本溢出风险、字体比例失调、间距方差、色彩不协调、元素重叠、孤儿标签、字号异常和边密度过高。首次预览前必须运行,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 科研图表模板?
Related skills
- Downloads
- 989All time
- Security audit
- Pass
- Last updated
- 4mo ago
- Current version
- v0.1.2
- License
- MIT-0
