drawio-bpmn

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Draw.io BPMN

Produce correct BPMN (Business Process Model and Notation) swimlane diagrams in draw.io. This skill is a thin frontend; the deterministic engine, validator, and rules live in the

drawio-ai-kit

package, reached via the

drawio-ai

CLI.

在draw.io中生成符合规范的BPMN（Business Process Model and Notation，业务流程模型与符号）泳道图。该技能是一个轻量级前端；确定性引擎、验证器和规则都位于

drawio-ai-kit

包中，可通过

drawio-ai

CLI调用。

0. Preflight — the CLI must be installed

0. 预检 — 必须安装CLI

bash

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

drawio-ai

is not on PATH, stop and tell the user to run

npm i -g github:sparklabx/drawio-ai-kit

. Never run
npm i -g
yourself — nothing mutates the user's global environment without their say-so.

bash

command -v drawio-ai >/dev/null 2>&1 || echo "请先安装工具包：npm i -g github:sparklabx/drawio-ai-kit"

如果

drawio-ai

不在PATH中，请停止操作并告知用户运行

npm i -g github:sparklabx/drawio-ai-kit

。切勿自行运行
npm i -g
— 未经用户许可，不得修改用户的全局环境。

1. Delegate the build (preferred when your harness supports it)

1. 委托构建（当你的工具支持时优先选择）

If your harness can spawn autonomous subagents that run shell commands AND read images (e.g. Claude Code's Task tool, a general-purpose agent), run the whole build loop in a subagent — the rules, icon searches, and every render/fix iteration then cost this conversation nothing. If it can't (or the subagent can't read images), skip to Inline path below — same loop, same rules.

Before spawning, resolve what the subagent cannot ask about: diagram scope, output directory (absolute path under the user's project), filename. Run the preflight above yourself. For a multi-diagram request, spawn one subagent per diagram in parallel with distinct filenames.

Model routing — if your harness lets you choose the subagent's model, route by task weight: a fast/cheap tier (Claude Haiku-class — must support vision) when the request matches a template from the rules' Templates table (reproduction is mechanical; the validator's advice strings teach every fix), your default strong model for free-hand or novel architectures. If a cheap subagent returns VALIDATE not ok or ITERATIONS > 3, respawn ONCE on the strong model before taking over inline. Multi-diagram requests: route each diagram independently.

Subagent prompt (fill every

<...>

text

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">

Relay

DRAWIO

PNG

and

SUMMARY

to the user verbatim; do NOT re-read the .drawio or PNG in this conversation — the subagent already ran the vision self-check. If

VALIDATE

is not ok, take over via the Inline path (the build .mjs and .drawio are on disk at the returned paths).

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

生成子代理前，确定子代理无需询问的内容：图范围、输出目录（用户项目下的绝对路径）、文件名。自行执行上述预检步骤。对于多图请求，为每个图并行生成一个子代理，并使用不同的文件名。

模型路由 — 如果你的工具允许选择子代理的模型，请根据任务权重选择：当请求匹配规则模板表中的模板时（复制过程为机械操作；验证器的建议字符串会指导所有修复），使用快速/低成本层级（Claude Haiku级——必须支持视觉功能）；对于手绘或新型架构，使用默认的高性能模型。如果低成本子代理返回VALIDATE未通过或ITERATIONS>3，在切换到内联路径接管前，先在高性能模型上重新生成一次子代理。多图请求：为每个图独立选择模型。

子代理提示词（填充所有

<...>

）：

text

使用drawio-ai CLI构建BPMN泳道.drawio图。
请求：<用户的请求+澄清内容，原文照搬>
输出：<ABS_PROJECT_DIR>/<NAME>.drawio — 切勿写入工具包目录或当前工作目录。
严格遵循以下步骤：
1. 设置ROOT="$(drawio-ai root)". 阅读$ROOT/docs/api-cheatsheet.md — 该文件包含完整的布局引擎API；切勿读取库源代码。
2. 运行`drawio-ai workflow`和`drawio-ai principles --mode bpmn` — 这是事实来源。（如果命令被阻止， fallback方案：直接读取$ROOT/rules/*.md文件。）
3. 使用一次批量命令`drawio-ai search "a, b, c"`查找所有图标；切勿重新着色图标。
4. 搭建脚手架，而非从头编写：`drawio-ai scaffold --list`，选择最接近的模板，然后运行`drawio-ai scaffold <name>.mjs -o <dir>/build.mjs` — 生成的脚本可直接运行（绝对导入、自验证、自渲染并附带问题列表）。仅修改差异部分。如果没有接近的模板且需要修改超过一半内容，则编写新脚本（保留脚手架的自检尾部）。仅使用布局引擎（group/frame/grid/icon/box + renderTree），**禁止手写坐标**。
5. 每次运行`node build.mjs`都会输出验证JSON以及渲染后的机器可读`issues`列表。根据该清单修复——一次性修复所有问题——然后重新运行。循环直到issues为空。
6. 仅当issues为空时：读取一次PNG作为最终视觉确认（列出所有剩余视觉问题，一次性修复所有问题）。目标是总共读取PNG不超过2次。然后不带--check参数渲染一次，生成最终交付的PNG。
请勿调用任何drawio技能 — 本提示词已包含完整流程。
请勿提问 — 做出标准选择并记录在ASSUMPTIONS下。
仅返回以下内容块，别无其他：
DRAWIO: <.drawio文件的绝对路径>
PNG: <.png文件的绝对路径>
VALIDATE: <最终验证JSON原文>
ICONS: <使用的图标名称，逗号分隔>
ITERATIONS: <渲染/修复循环次数>
SUMMARY: <描述该图的一句话>
ASSUMPTIONS: <未询问用户做出的选择，或"无">

将

DRAWIO

、

PNG

和

SUMMARY

原文转发给用户；请勿在本次对话中重新读取.drawio或PNG — 子代理已执行视觉自检。如果

VALIDATE

未通过，请通过内联路径接管（build.mjs和.drawio文件位于返回路径的磁盘上）。

Inline path (no subagent support)

内联路径（不支持子代理时）

1. Shared Workflow

1. 共享工作流

bash

drawio-ai workflow

Prints the build → validate → render → write-to-project-path loop every diagram follows. Read it; it is the source of truth for the process.

bash

drawio-ai workflow

打印每个图都遵循的构建→验证→渲染→写入项目路径循环流程。请阅读该内容，它是流程的事实来源。

2. Domain rules

2. 领域规则

bash

drawio-ai principles --mode bpmn

Returns the BPMN rules + shared principles + catalog shape groups.

bash

drawio-ai principles --mode bpmn

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

3. Build with the engine, then validate + render

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

Resolve the Kit's install dir, then

import

the engine by absolute path (the Shared Workflow shows the exact pattern):

bash

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

Build with the declarative layout engine (NO hand-written coordinates) using the

src/bpmn.mjs

creators and the

pool()

primitive, then:

drawio-ai validate <file>

→

drawio-ai render <file> -o <file>.png

(

Read

the PNG for the vision self-check) → write the

.drawio

to an absolute path under the user's project (never the Kit, never

cwd

确定工具包的安装目录，然后通过绝对路径

import

引擎（共享工作流展示了确切模式）：

bash

ROOT="$(drawio-ai root)"     # 已安装工具包的绝对路径

使用声明式布局引擎（禁止手写坐标），通过

src/bpmn.mjs

中的创建器和

pool()

原语进行构建，然后执行：

drawio-ai validate <file>

→

drawio-ai render <file> -o <file>.png

（读取PNG进行视觉自检）→ 将

.drawio

文件写入用户项目下的绝对路径（切勿写入工具包目录或当前工作目录）。

Domain notes

领域说明

Structure:

pool → lanes (roles) × phases (milestones)

. Use the creators in

src/bpmn.mjs

—

start

intermediate

end

gateway

(exclusive/parallel/ inclusive/event), typed tasks (

userTask

serviceTask

manualTask

scriptTask

businessRuleTask

), plain

task

subProcess

. Each node carries

{ lane, col }

cell tags; the engine places them automatically.

A gateway MUST split (≥2 outgoing) or merge (≥2 incoming) — never neither. Red accent ONLY for blocker end events (error/cancel/terminate); everything else is monochrome. Sequence flow: solid lines, rounded corners. One start event (no incoming flow); end events on the right (no outgoing flow). Horizontal by default; pass

orientation: "vertical"

pool()

for vertical swimlanes.

结构：

pool → lanes（角色）× phases（里程碑）

。使用

src/bpmn.mjs

中的创建器——

start

、

intermediate

、

end

、

gateway

（排他/并行/包容/事件）、类型化任务（

userTask

、

serviceTask

、

manualTask

、

scriptTask

、

businessRuleTask

）、普通

task

、

subProcess

。每个节点都带有

{ lane, col }

单元格标签，引擎会自动放置它们。

网关必须拆分（≥2个输出流）或合并（≥2个输入流）——不能两者都不满足。仅阻塞结束事件（错误/取消/终止）使用红色强调；其他所有元素均为单色。序列流：实线、圆角。一个开始事件（无输入流）；结束事件位于右侧（无输出流）。默认水平布局；向

pool()

传递

orientation: "vertical"

可设置垂直泳道。

Self-check (before delivering)

自检（交付前）

Built with the layout engine — no hand-written coordinates.
```
drawio-ai validate
```
→ ok, no warnings, no advice.
Every icon came from
```
drawio-ai search
```
(category colors intact).
```
drawio-ai render
```
vision self-check passed.
Output written under the user's project, not the Kit.

使用布局引擎构建 — 无手写坐标。
```
drawio-ai validate
```
→ 通过，无警告，无建议。
所有图标均来自
```
drawio-ai search
```
（类别颜色保持不变）。
```
drawio-ai render
```
视觉自检通过。
输出文件写入用户项目目录，而非工具包目录。