bpmn

BPMN 2.0：读取和编辑流程图

此技能的作用

帮助你用通俗语言理解现有的 .bpmn 文件，并生成新的或编辑后的文件，确保它们在任何建模器（Camunda Modeler、bpmn.io、Cawemo 等）中打开时都有效且布局清晰。

工作分工明确：

• 你负责语义推理：流程的含义，以及要添加或更改的内容。
• 内置脚本负责确定性的操作：解析、重新生成布局和验证。每次都依赖它来完成这些操作，而不是手动处理。

让 BPMN 易于处理的关键：两个层次

.bpmn 文件在一个 XML 文档中包含两个层次：

1. 语义——实际流程：包含任务、网关、事件及连接它们的 sequenceFlow 的 bpmn:process。这就是流程的含义。
2. 图表交换格式（DI）——包含每个图形 x/y 坐标和每条边路径点的 bpmndi:BPMNDiagram。这只是图示。

手动编辑 DI 是 BPMN 工作出错的根源：坐标偏移、图形重叠、边线交叉。**因此，我们绝不手动编写 DI。**你编辑语义；DI 由 layout 命令负责。正因如此，图表才会“清晰”——以确定性方式生成整洁的从左到右布局。

默认情况下，layout 不会破坏现有内容，这条规则能帮你避免麻烦：对于已有图表的文件，它会保留现有布局，并使其与编辑内容同步（删除已删除元素的图形，为新增元素放置图形）。对于没有 DI 的文件，它会生成全新布局。只有在传入 --rebuild 时，它才会丢弃整个图表并从头重建。因此，习惯很简单：编辑语义后，始终运行 layout；它绝不会破坏良好的图表。

设置（每台机器只需一次）

该脚本需要两个 npm 包。在技能所在目录中运行：

npm install --prefix "<SKILL_DIR>"

<SKILL_DIR> 是包含此 SKILL.md 的文件夹。完成后，即可使用以下四条命令。如果运行时出现“Cannot find package”错误，说明跳过了安装步骤——请运行安装命令后重试。

阅读／解释图表

1. 获取结构化大纲（不要尝试读取原始 DI 坐标）：

   node "<SKILL_DIR>/scripts/bpmn-tool.mjs" summarize path/to/file.bpmn
   

   此命令会列出池／泳道、开始／结束事件、活动（及其类型）、 网关（及其方向）、边界事件（宿主活动和是否中断），以及每条 顺序流的 source -> target [condition]。如果想以编程方式 处理，可添加 --json。

2. 用人们容易理解的方式解释流程：先讲正常路径，然后讲决策点 （每个网关根据什么条件分支）、并行工作以及异常／边界处理。 使用实际的业务步骤名称，不要使用元素 ID。 使用用户所用的语言。

summarize 输出是理解“此图表做什么”的事实依据——请根据它来解读，而不是凭肉眼查看 XML，尤其是遇到复杂图表时。

要在编辑前定位特定元素，请使用 find <file> <term>（匹配名称或类型）。要比较两个图表——例如现状与目标状态，或准确显示某次编辑改动的内容——请使用 diff <a> <b>；它会报告新增、删除、重命名或更改类型的元素，以及重新连接的所有顺序流。

当用户想要审查（“这样对吗？”，“找出 bug”，“为什么会卡住？”）时，也要运行 lint。它可以捕获通过 validate 且 XML 有效、但行为错误的控制流 bug——这类问题很容易被肉眼漏掉：

node "<SKILL_DIR>/scripts/bpmn-tool.mjs" lint path/to/file.bpmn

它会标记：由排他（XOR）拆分馈入的并行（AND）汇合（死锁）；由排他汇合合并的并行拆分（运行两次）；条件可能全部为假且没有默认分支的排他网关（令牌卡住）；不可达节点；死路（非结束节点且没有出流）；缺少开始／结束节点；隐式拆分（有多条出流的非网关节点）；方向错误的事件（开始事件有入流，结束事件有出流）；位于非活动上的边界事件；流程使用泳道时，不属于任何泳道的节点；以及留在同一个池内的消息流。阅读检查结果，对照模型确认，然后用通俗的语言解释。

创建或编辑图表

为新流程编写 XML 之前，请像业务分析师一样思考并明确结构——这正是清晰模型与一团箱线图之间的区别。如果请求中有任何一点不明确，请先询问：

• 触发条件 - 什么启动流程（是普通开始事件、消息事件还是定时器事件？）。
• 参与者 - 谁负责什么。多个参与者通常意味着使用泳道（一个池）或池和消息流（多个独立流程）。
• 正常路径 - 一切顺利时活动的主要顺序。
• 决策点 - 路径在哪里分叉、分叉条件是什么，以及适合使用哪种网关（排他 = 二选一，并行 = 全部执行，包容 = 一个或多个）。
• 异常 / 替代路径 - 超时、拒绝、错误；通常使用边界事件或额外分支。
• 结束状态 - 流程结束的各种不同方式。

如果用户要记录当前状态与未来状态，请将 As-Is 和 To-Be 视为单独的图表/文件，并分别标注。

可靠的工作循环是编辑语义 -> 重新生成布局 -> 验证 -> 检查：

1. 编写或更改语义。 对于新图表，手动编写仅包含语义的文档（不含 bpmndi: 块）——文档简洁，也容易写正确。对于编辑，先运行 summarize 了解当前模型，然后再更改 bpmn:process 正文。有关骨架、每种元素的 XML 结构，以及可复制粘贴的示例（排他 / 并行 / 包容网关、边界事件、池、泳道、消息流），请参阅 references/bpmn-reference.md。

2. 布局。 将图表与编辑内容同步：

   node "<SKILL_DIR>/scripts/bpmn-tool.mjs" layout in.bpmn out.bpmn
   

   省略 out.bpmn 可直接改写原文件。对于已有 DI 的文件，这会保留现有布局（手动调整的位置、Camunda 多图子流程页面），并且只会删减或放置形状以匹配你的更改。对于全新的纯语义文件，这会生成整洁的布局。只有当用户明确要求从头重新布局整个图表时，才添加 --rebuild（这会丢弃所有手动定位——请说明这一点）。

3. 验证。 确认文件可以解析、每个流程元素都有对应形状，且没有形状重叠：

   node "<SKILL_DIR>/scripts/bpmn-tool.mjs" validate out.bpmn
   

   修复所有标记的问题（悬空引用会作为解析警告显示；缺少形状通常意味着你跳过了 layout；重叠会按图表平面分别检查，因此真正的重叠意味着布局过于拥挤——请重新运行 layout --rebuild）。

4. 检查控制流——尤其是在添加或重新连接网关和分支时：

   node "<SKILL_DIR>/scripts/bpmn-tool.mjs" lint out.bpmn
   

   validate 可证明文件格式正确；lint 可证明逻辑合理。它能捕获一些不易察觉的错误：网关分叉 / 汇合不匹配（死锁、重复执行）、令牌卡住、节点不可达、死路、缺少开始 / 结束事件、隐式分叉、开始 / 结束事件方向错误、非活动上的边界事件、未分配泳道的节点，以及仍在同一个池内的消息流。

只有在 validate 和 lint 都通过后，才能声称图表已完成——它们运行迅速，还能捕获会导致文件显示异常或在真实引擎中卡住的错误（引用拼写错误、缺少布局、网关死锁）。

建模要清晰，而不只是有效

自动布局处理的是位置；清晰度还取决于建模方式。以下习惯有助于提升图表的可读性：

• 使用业务术语命名。 任务使用动词短语（“批准发票”），网关使用其要回答的问题（“金额 > 1000？”），并为输出流标注答案（“是” / “否”）。
• 保持一个开始事件，并明确结束事件。 对于不同结果，使用不同的结束事件，比使用一个包罗万象的结束事件更清晰。
• 成对设置网关。 分叉网关通常需要对应的汇合网关；为排他网关设置默认 / 兜底路径，以免令牌卡住。
• 不要让单个图表承载过多内容。 如果图表过于庞杂，就将细节放入子流程。

自动布局：涵盖范围

layout 适用于日常 BPMN 的各种场景，而不仅仅是单泳池流程：

• **协作：**布局会覆盖每个泳池，并按垂直方向堆叠，同时在泳池之间布置消息流（而不只是处理第一个参与者）。
• **泳道：**节点会放置在所属泳道的水平带内，并绘制泳道形状。
• 子流程会获得自己的下钻图表页面（单独的 BPMNDiagram 平面），与 Camunda 导出完全相同：子流程在主画布上显示为一个方框，打开后即可在独立页面上查看布局完成的内部步骤。子流程不会被平铺到主画布上，也不会被清空。summarize 会显示内部步骤；建模器会在打开子流程时显示这些步骤。
• 数据对象／存储、文本注释、关联会在其关联元素旁放置形状／边。

当请求涉及以下限制时，值得如实说明：

• 组不会自动放置（组只是一个纯视觉矩形，在模型中没有成员关系，因此无法据此确定其大小）。如有需要，请在建模器中添加。
• 泳池、泳道、数据对象和注释的自动放置只是近似布局——结果整洁且有效，但用户可能仍希望在建模器中微调间距。

详细信息和替代方案见 references/bpmn-reference.md。

捆绑工具

命令	用途
summarize <file> [--json]	以结构化大纲展示流程，便于讲解或在编辑前了解流程
layout <in> [out] [--rebuild]	将图表与语义同步：保留并更新现有 DI，或在 DI 不存在时生成。--rebuild 会从头重新布局
validate <file>	解析并报告警告，标记任何缺少形状的流程元素或平面内互相重叠的形状
lint <file>	查找控制流／结构错误：网关分流／合流不匹配、网关令牌卡住、不可达节点、死路、缺少开始／结束事件、隐式分流、事件方向错误、边界事件宿主错误、未分配泳道的节点、泳池内的消息流
diff <a> <b>	语义与结构差异对比：元素的新增／删除／重命名／类型更改，以及序列流的重新连接（例如比较现状与目标状态，或审查编辑）
find <file> <term>	列出名称或类型包含 term 的流程元素（不区分大小写）——编辑前快速查找

所有四个工具都位于 scripts/bpmn-tool.mjs。更深入的元素参考、操作指南和边缘情况见 references/bpmn-reference.md——需要了解某个元素或模式的确切 XML 时，请查阅该文件。