Codex 流程图图片转Draw io流程图底稿

draw-io-illustrator Codex插件可以通过 draw.io 的图形 API ，将流程图片里的元素逐对象绘制复刻到draw io工程。

一、Codex 插件的最小结构

Codex 插件本质上是一个目录，包含：

• 声明文件 plugin.json
• 技能目录 skills/
• .mcp.json 和对应的服务端脚本（非必须）

my-plugin/├── .codex-plugin/│   └── plugin.json      # 声明插件的名字、能力、入口├── skills/│   └── my-skill/│       └── SKILL.md      # 技能描述，告诉 Codex 何时触发、怎么干└── .mcp.json             # （可选）注册 MCP 工具

plugin.json 是 Codex 识别插件的唯一入口。draw-io-illustrator 的声明文件摘录如下：

1{2  "name": "draw-io-illustrator",3  "version": "2.2.0",4  "description": "Design or recreate scientific figures in draw.io Desktop...",5  "skills": "./skills/",          // 技能目录的相对路径6  "mcpServers": "./.mcp.json"     // MCP 工具配置的相对路径7}

skills 字段指向技能目录，Codex 启动时扫描其中所有 SKILL.md 文件，把它们注入到 system prompt 中作为可用技能。mcpServers 指向 MCP 工具配置，告诉 Codex 有哪些外部工具可以调用。
plugin.json 里还有一个 interface 字段，控制插件在 Codex UI 中如何展示：

1{2  "interface": {3    "displayName": "draw.io Illustrator",4    "shortDescription": "Build editable figures in draw.io Desktop.",5    "category": "Productivity",6    "capabilities": ["Interactive", "Write"],7    "brandColor": "#F08705"8  }9}

displayName 是 Codex 插件菜单中显示的名字，shortDescription 是简短说明，category 决定在哪个分类下出现，capabilities 声明插件需要的权限类型。

安装方式有两种：

• Codex 自己装：把仓库地址和安装指令发给它，Codex会自动调用 codex plugin marketplace add 和 codex plugin add
• 手动在终端执行，适合开发调试

1git clone https://github.com/sanyinchen/draw-io-illustrator.git2cd draw-io-illustrator3codex plugin marketplace add "$(pwd)"4codex plugin add draw-io-illustrator@draw-io-illustrator-tools

注意 codex plugin add 会把插件复制到 ~/.codex/plugins/cache/ 下的版本目录，Codex 加载的是这份副本。改了源码之后必须重新运行 codex plugin add，并完全退出 Codex 再打开才能生效。

二、draw-io-illustrator 整体架构

draw-io-illustrator 注册了两个 MCP server 和五个技能，架构上分为三层：

通信层（MCP Server）：两个 Node.js 脚本，通过 MCP（Model Context Protocol）与 draw.io 通信。

调度层（Skills）：五个 SKILL.md 文件，每个对应一个角色。

执行层（draw.io Desktop）：draw.io 应用程序本身，插件通过CDP直接操作 draw.io 的图形模型（mxGraph），优先使每个形状、连接线、文字都保持可编辑，只有确实无法用形状还原的显微照片或复杂纹理元素，才作为图片插入。

这里有一层细节值得注意：MCP server 脚本和 draw.io 之间的通信用的不是 draw.io 的官方 API，而是 Chrome DevTools Protocol。draw.io 是基于 Electron 的桌面应用，内部有一个隐藏的调试端口。live-server.mjs 启动 draw.io 时带上 --remote-debugging-port 参数，然后通过 CDP 向页面注入 JavaScript，直接操作画布上的 mxGraph 实例。这意味着每个 drawio_live_add_shape 调用，底层链路：

Codex → MCP JSON-RPC → live-server.mjs → CDP WebSocket → draw.io 页面 → mxGraph API → 画布渲染

三、角色工作流：Designer → Drawer → Reviewer → Corrector

四角色的工作流把"画图"拆成四个可验证的步骤，每个步骤都生成可检查的中间产物。

3.1 整体流程

核心约束：每个区域审查通过之前，不开始下一个区域。全部区域通过后，再做一次全图审查。这是一个"局部循环 + 全局循环"的双层门控。

3.2 Designer：从参考图到布局规范

当用户上传了参考图，recreate-scientific-figure 充当 Designer。它的第一件事不是立即画图，而是从参考图中取样：提取画布背景色、每类元素的填充色、边框色、边框粗细与虚实、文字颜色和字号。

recreate-scientific-figure/SKILL.md 中对取样规则的英文原文及逐行翻译如下，中文译文以 // 标注：

// 对参考图取样，绝不要重新诠释它## Sample the reference; never reinterpret it // 复刻效果以参考图为衡量标准，而不是以审美偏好为标准。绘制前，请直接从图片中记录以下属性：Replication is measured against the reference, not against good taste. Before drawing, record from the image itself: // - 画布背景色；// - 每一种不同对象类型的填充色、边框色、边框宽度，以及边框是实线、虚线还是点线；// - 标签的颜色、字号和字重；// - 圆角半径和透明度。- the canvas background color;- for every distinct object class: fill color, border color, border width, and whether the border is solid, dashed, or dotted;- label color, size, and weight;- corner radius and any transparency. // 将这些属性记录为从参考图中采样得到的精确值。不要替换成“更干净”的调色板，不要为了提高可读性而调亮深色填充，也不要因为实线看起来更整洁就去掉虚线边框——在类图或流程图中，虚线边框通常具有特定含义。当无法可靠地采样某种颜色时，应将其记录为歧义，而不是编造一个相近的颜色值。Record these as exact values sampled from the reference. Do not substitute a "cleaner" palette, do not lighten a dark fill for legibility, and do not drop a dashed border because a solid one looks tidier — in a class or flow diagram a dashed border usually carries meaning. When a color cannot be sampled confidently, record it as an ambiguity rather than inventing a nearby one.

取样完成后，Designer 产出一个 reconstruction_spec，包含：区域 ID、边界框、标题、绘制顺序、每个对象的 cell ID、几何、样式、连接路径、分组关系。spec 是后续三个角色来回沟通的协议。

3.3 Drawer：逐区域、逐对象绘制

recreate-scientific-figure-in-drawio 是 Drawer。它接到 reconstruction_spec 后，按以下顺序工作：

1. 调用 drawio_live_get_capabilities 获取当前 draw.io 支持的所有图形名
2. 调用 drawio_live_set_page_style 还原画布背景、关闭网格
3. 逐区域从后往前（背景→前景）绘制
4. 每个图形显式指定 fill_color 和 stroke_color，不依赖主题默认值
5. 虚线边框同时指定 dashed=true 和 dash_pattern

3.4 Reviewer：双重证据审查

audit-scientific-figure 作为 Reviewer，不画画，只审图。每次审查必须同时采集两种证据：

结构证据：通过 drawio_live_audit_figure 和 drawio_live_inspect 分析画布上的对象模型——cell ID、几何、样式、连接关系、分组。这一步能发现"虽然看着对了，但某个边框其实是主题默认值而非显式指定的"这类问题。
渲染证据：通过 drawio_live_screenshot 截图，与参考图的对应区域进行像素级对比。

Reviewer 对每个缺陷输出标准格式：

region: 区域 IDcells: 精确的 cell ID 列表category: 缺陷类别severity: hard | warningevidence: 可度量的结构或渲染观察correction: 要求达到的结果，而非模糊建议acceptance: 下次审查可验证的条件confidence: 0..1 附带证据依据

严重性为 hard 的缺陷会阻止区域通过门控。包括：文字错误、方向错误、可重建内容被塞进了图片、裁剪/重叠、箭头侵入标签、颜色或边框与参考图不一致。

3.5 Corrector：从缺陷到修复指令

correct-scientific-figure 是 Corrector，负责接收 Review 发现的问题，产出精确到 cell 级别的 correction_plan。它对每条缺陷诊断根因——是几何错误、颜色错误、连接路径错误，还是图片不够原子——然后给出最小的修复操作序列。

修复操作不是"把区域重画一遍"，而是精确到具体原因：

$correctio{n}_{i}d:fix-dashed-border-3$$findin{g}_{i}d:region-2-hard-5$$cells:[tabl{e}_{h}eade{r}_{0}1]$$roo{t}_{c}ause:边框渲染为实线，但参考图为虚线$operations:$1.drawi{o}_{l}iv{e}_{u}pdat{e}_{c}ell(id="tabl{e}_{h}eade{r}_{0}1",dashed=true,das{h}_{p}attern="86")$$acceptance:截图对比确认边框为虚线，das{h}_{p}attern与参考图一致$

drawio_live_update_cell 只传需要改的属性字段，其他属性保持不变。

四、MCP 服务器：Live 与 File-Utils

MCP server 的配置文件 .mcp.json ：

1{2  "mcpServers": {3    "drawio-live": {4      "command": "node",5      "args": ["./scripts/live-server.mjs"],6      "cwd": "."7    },8    "drawio-file-utils": {9      "command": "node",10      "args": ["./scripts/server.mjs"],11      "cwd": "."12    }13  }14}

每个 server 是一个独立的 Node.js 进程，通过 stdin/stdout 的 JSON-RPC 接口与 Codex 通信。Codex 启动插件时 spawn 这两个进程，之后每个 drawio_live_* 开头的工具调用都被路由到 live-server.mjs。

4.1 Live Server：与画布对话

live-server.mjs负责把 Codex 的调用翻译成画布操作，server 启动 draw.io Desktop 时的命令行参数：

1// live-server.mjs 核心启动逻辑（简化）2const drawioArgs = [3  "--remote-debugging-port=" + live.port,  // 开启 CDP 调试端口4  "--user-data-dir=" + PROFILE_ROOT,        // 独立 profile，避免污染用户配置5];6 7// 通过 CDP 连接到 draw.io，注入 light_mode 样式覆盖8// 这样截图中显示的颜色就是图里实际存储的颜色

drawio_live_add_shape ：创建具体的绘图单元

1// 每个形状至少需要：id、位置、尺寸2// fill_color 和 stroke_color 都是有就传，不依赖 draw.io 主题默认值3const shapeProperties = {4  id: { type: "string" },5  shape: { type: "string", default: "rounded" },6  x: { type: "number" }, y: { type: "number" },7  width: { type: "number" }, height: { type: "number" },8  fill_color: { type: "string" },       // 空着就用 draw.io 主题默认填充9  stroke_color: { type: "string" },     // 空着就没有边框10  dashed: { type: "boolean" },          // 虚线开关11  dash_pattern: { type: "string" },     // 如 "8 6" 长虚线、"1 3" 点线12  // ...13};

每个形状的属性被转换成 mxGraph 的 style 字符串，然后通过 CDP 注入到 draw.io 页面的 JavaScript 上下文中执行。update 时走同样的路径——drawio_live_update_cell 只传要改的属性，server 端做属性合并而非字符串替换。

4.2 File-Utils Server：离线操作

server.mjs的核心能力是 drawio_create_diagram：按给定的顶点和边生成 .drawio XML

1// 每个图片顶点必须满足五个栅格声明条件2function validateRasterAudit(args, id) {3  // 1. 为什么这个区域必须用图片而非可编辑形状4  if (args.raster_reason.trim().length < 8) throw Error("raster_reason required");5 6  // 2. 图片来源是否已经精确裁剪7  if (typeof args.source_is_tightly_cropped !== "boolean") throw Error("...");8 9  // 3. 是否只包含一个不可分割的栅格区域（不是网格、蒙太奇）10  if (args.atomic_raster_unit !== true) throw Error("...");11 12  // 4. 是否已移除所有可重建的文字、边框、箭头等13  if (args.contains_reconstructable_content !== false) throw Error("...");14 15  // 5. 拆解说明：什么被重建为可编辑对象，什么确实无法拆分16  if (args.decomposition_note.trim().length < 8) throw Error("...");17}

这五个条件是强制的。如果任一不满足，工具直接报错，不会把图片塞进图里。

五、示例Demo

prompt:

[@draw-io-illustrator](plugin://draw-io-illustrator@draw-io-illustrator-tools)  使用 draw-io-illustrator，连接实时 draw.io 画布，100% 复刻我上传的流程图：  1、先从参考图取样：画布背景色、每类元素的填充色、边框色、边框粗细与虚实、文字颜色和字号，  $全部按取样值还原，不要为了好看或对比度改成别的颜色。2、先用drawi{o}_{l}iv{e}_{s}e{t}_{p}ag{e}_{s}tyle还原画布背景并关闭网格，再开始画。$$3、每个图形都显式给出fil{l}_{c}olor和strok{e}_{c}olor；参考图是虚线边框的，必须带dashed和das{h}_{p}attern。$4、优先使用可编辑的文字、图形、连接线、表格、图表和分组对象。  5、只有无法可靠绘制的最小区域，例如显微照片或复杂纹理，才裁剪为图片插入。  6、按区域逐步绘制，每完成一个区域就检查结构和画布截图，有问题先修正再继续。  7、完成后做全图对比检查，检查通过后恢复网格并保存可编辑 .drawio。  

Codex执行过程：
第一步：连接画布。 recreate-scientific-figure 技能被触发后，它调 recreate-scientific-figure-in-drawio，后者调用 drawio_live_launch 启动或连接到 draw.io Desktop。启动时传 exact_color_rendering=true 和 light_mode=true，避免深色模式的颜色偏差。

第二步：分析参考图。 读取用户上传的图片，提取布局结构和颜色取值。Designer 角色输出 reconstruction_spec 提供详尽的布局规范。

第三步：逐区域绘制。 Drawer 从背景开始：

• drawio_live_set_page_style 设置画布背景色和关闭网格
• drawio_live_add_shape 添加每个节点，带上精确的颜色
• drawio_live_add_edge 添加连接线
• drawio_live_align_cells 和 drawio_live_distribute_cells 做精确对齐

第四步：逐区域审查。 每个区域画完后，Reviewer 调 drawio_live_screenshot 截图，调 drawio_live_audit_figure 分析结构，与参考图对比。发现缺陷就交给 Corrector 出修复方案，Drawer 执行后重新审查，直到通过。

第五步：全图审查。 所有区域通过后，对整个画布做同样的双重审查，检查跨区域对齐、间距一致性、全局配色和连接清晰度。

第六步：保存。 通过所有门控后，drawio_live_save_snapshot 保存可编辑的 .drawio 文件，导出预览图。

原图：

转换为draw io工程：

本文由 AgentPlanFlow 生成