drawio-bpmn

Draw.io BPMN

在 draw.io 中生成正确的 BPMN（业务流程模型与标记法）泳道图。 此技能是一个轻量前端；确定性引擎、验证器和规则位于 drawio-ai-kit 软件包中，通过 drawio-ai CLI 调用。

0. 预检 — 必须已安装 CLI

command -v drawio-ai >/dev/null 2>&1 || echo "Install the Kit first:  npm i -g github:sparklabx/drawio-ai-kit"

如果 drawio-ai 不在 PATH 中，请停止并告知用户运行 npm i -g github:sparklabx/drawio-ai-kit。切勿自行运行 npm i -g — 未经用户同意，绝不更改用户的全局环境。

1. 委派构建（当你的运行环境支持时优先采用）

如果你的运行环境可以启动能够运行 shell 命令并读取图像的自主子 Agent（例如 Claude Code 的 Task 工具、通用 Agent），请在子 Agent 中运行整个构建循环 — 规则、图标搜索以及每次渲染／修复迭代都不会占用本次对话的资源。如果不支持（或子 Agent 无法读取图像），请跳转到下方的内联路径 — 循环和规则相同。

启动前，先确定子 Agent 无法询问的事项：图表范围、输出目录（位于用户项目下的绝对路径）和文件名。自行运行上述预检。对于多图表请求，请为每个图表并行启动一个子 Agent，并使用不同的文件名。

模型路由 — 如果你的运行环境允许选择子 Agent 的模型，请根据任务权重进行路由：当请求符合规则中 Templates 表的模板时（复现是机械化操作；验证器的建议字符串会指导每项修复），使用快速／低成本层级（Claude Haiku 级别 — 必须支持视觉）；对于自由绘制或新颖架构，使用你的默认强模型。如果低成本子 Agent 返回 VALIDATE not ok 或 ITERATIONS > 3，请在接管内联操作前，用强模型重新启动一次。多图表请求：分别为每个图表选择模型。

子 Agent 提示词（填写每个 <...>）：

Build a BPMN swimlane .drawio diagram with the drawio-ai CLI.
Request: <user's request + clarifications, verbatim>
Output: <ABS_PROJECT_DIR>/<NAME>.drawio — never write inside the Kit, never into cwd.
Follow exactly:
1. Set ROOT="$(drawio-ai root)". Read $ROOT/docs/api-cheatsheet.md — the full layout-engine
   API in one file; never read library source.
2. Run `drawio-ai workflow` and `drawio-ai principles --mode bpmn` — the source of
   truth. (Fallback if a command is blocked: read $ROOT/rules/*.md directly.)
3. Look up every icon with ONE batched `drawio-ai search "a, b, c"`; never recolor icons.
4. Scaffold, don't write: `drawio-ai scaffold --list`, pick the closest template, then
   `drawio-ai scaffold <name>.mjs -o <dir>/build.mjs` — the script arrives runnable
   (absolute imports, self-validating, self-rendering with an issues list). Edit only the
   deltas. If no template is close AND you'd change more than half of it, Write a new
   script instead (keep the scaffold's self-check tail). Layout engine only
   (group/frame/grid/icon/box + renderTree), NO hand-written coordinates.
5. Each `node build.mjs` run prints validate JSON AND the render's machine-readable
   `issues` list. Fix from THAT checklist — all issues in one Edit round — then re-run.
   Loop until issues is empty.
6. Only when issues is empty: Read the PNG once as final visual confirmation (list any
   remaining visual problems, fix ALL in one round). Target <= 2 PNG reads total. Then
   render once WITHOUT --check for the final deliverable PNG.
Do NOT invoke any drawio skill — this prompt already contains the full procedure.
Do not ask questions — make the standard choice and record it under ASSUMPTIONS.
Return EXACTLY this block, nothing else:
DRAWIO: <absolute path to .drawio>
PNG: <absolute path to .png>
VALIDATE: <verbatim final validate JSON>
ICONS: <comma-separated icon names used>
ITERATIONS: <number of render/fix cycles>
SUMMARY: <one sentence describing the diagram>
ASSUMPTIONS: <choices made without asking, or "none">

将 DRAWIO、PNG 和 SUMMARY 原样转交给用户；不要在本次对话中重新读取 .drawio 或 PNG — 子 Agent 已经完成视觉自检。如果 VALIDATE 不是 ok，请通过内联路径接手（build .mjs 和 .drawio 位于返回的路径中）。

内联路径（不支持子 Agent）

1. 共享工作流

drawio-ai workflow

输出每张图表都遵循的构建 → 验证 → 渲染 → 写入项目路径循环。请阅读；这是流程的权威说明。

2. 领域规则

drawio-ai principles --mode bpmn

返回 BPMN 规则 + 共享原则 + 目录中的形状分组。

3. 使用引擎构建，然后验证并渲染

确定 Kit 的安装目录，然后通过绝对路径 import 引擎（确切模式见共享工作流）：

ROOT="$(drawio-ai root)"     # absolute path to the installed Kit

使用声明式布局引擎构建（禁止手写坐标），使用 src/bpmn.mjs 创建器和 pool() 基元，然后： drawio-ai validate <file> → drawio-ai render <file> -o <file>.png（Read PNG 以进行视觉自检）→ 将 .drawio 写入用户项目下的绝对路径（绝不写入 Kit 或 cwd）。

领域说明

结构：pool → lanes (roles) × phases (milestones)。使用 src/bpmn.mjs 中的创建器 — start、intermediate、end、gateway（exclusive/parallel/ inclusive/event）、类型化任务（userTask、serviceTask、manualTask、 scriptTask、businessRuleTask）、普通 task、subProcess。每个节点都带有 { lane, col } 单元格标签；引擎会自动放置节点。

网关 MUST 分流（≥2 个出向流）或汇流（≥2 个入向流）— 不能两者都不是。仅阻塞型结束事件（error/cancel/terminate）使用红色强调；其他全部使用单色。顺序流：实线、圆角。仅有一个开始事件（无入向流）；结束事件位于右侧（无出向流）。默认采用水平布局；将 orientation: "vertical" 传给 pool() 可使用垂直泳道。

自检（交付前）

• 使用布局引擎构建——未手写坐标。
• drawio-ai validate → 通过，无警告，无建议。
• 每个图标均来自 drawio-ai search（类别颜色保持不变）。
• drawio-ai render 视觉自检通过。
• 输出写入用户的项目目录，而非 Kit。