camunda-bpmn

Camunda BPMN 建模

创建和编辑可执行的 BPMN 2.0 流程，适用于 Camunda 8.8+。生成包含 Zeebe 扩展和图表坐标的有效 XML。

前置条件

• Camunda 8.8+ 集群（通过 c8run 在本地运行、SaaS 或自托管）
• 已安装并配置 c8ctl CLI（c8ctl add profile）——提供 c8ctl bpmn lint
• c8ctl ≥ 3.2.0 才支持 bpmn format。如果该命令不可用，请提示用户升级：npm install -g @camunda8/cli

交叉引用

• camunda-feel：用于网关条件、输入/输出映射和定时器定义中的 FEEL 表达式
• camunda-dmn：用于编写业务规则任务背后的 DMN 决策——<zeebe:calledDecision decisionId="..." resultVariable="..."/>
• camunda-forms：用于创建与用户任务关联的 Camunda Form JSON 架构
• camunda-connectors：用于通过元素模板配置预构建的连接器（REST、Slack、Kafka 等）
• camunda-development：用于确定服务任务应由 OOTB 连接器、自定义连接器还是作业工作器来执行
• camunda-job-workers：用于实现服务任务的 zeebe:taskDefinition type 所激活的处理程序代码
• camunda-connectors-development：用于构建附加到服务任务或事件元素的自定义连接器（仅 JSON 的模板或 Java SDK）
• camunda-process-test：用于针对嵌入式 Zeebe 引擎测试流程
• camunda-process-mgmt：用于部署到集群并运行实例
• camunda-ai-agents：用于建模 AI Agent——由 AI Agent 连接器驱动、承载工具的临时子流程

说明

XML 结构

从头编写 BPMN 文件时，请遵循 bpmn-js 的规范样式——<bpmn:definitions> 写在单行、缩进两个空格、同级元素之间不留空行，并使用 <el /> 自闭合形式。否则，经 Camunda Modeler、Web Modeler 或 c8ctl element-template apply 往返处理后，文件都会被重新格式化，导致 Edit 匹配失效并产生大量 diff。规则和完整示例骨架见：references/canonical-style.md。

必须包含 zeebe 命名空间、isExecutable="true" 和 modeler:executionPlatform="Camunda Cloud"——缺少这些内容，Camunda 就无法正确识别流程。

<bpmndi:BPMNDiagram> 块同样是必需项，并非可有可无的美化内容：c8ctl bpmn lint 会将缺少 DI（no-bpmndi）标记为错误，而 Modeler 没有 DI 就无法渲染流程。每个 <bpmn:process> 流元素都需要匹配的 <bpmndi:BPMNShape>，每个 <bpmn:sequenceFlow> 都需要匹配的 <bpmndi:BPMNEdge>。坐标、尺寸和路径点规则见：references/layout-rules.md。注意，Zeebe 可以顺利部署不含 DI 的 BPMN——缺少 DI 只会在 lint 检查和 Modeler 中暴露，因此不要把部署成功当作文件格式正确的依据。

符号编码

始终对 XML 属性值中的特殊字符进行编码：

• < → <，> → >，& → &，" → "，' → '

核心建模规则

开始/结束事件：

• 每条路径都以开始事件（无传入流）开始，并到达结束事件（无传出流）
• 大多数流程使用 None 开始事件；外部触发使用 Message；定时执行使用 Timer

任务——每个任务执行一个原子操作：

• 用户任务：人工交互。使用 Camunda 用户任务实现：包含 <zeebe:userTask />，并通过 <zeebe:formDefinition formId="X" /> 关联表单。使用 <zeebe:assignmentDefinition candidateGroups="..." /> 分配任务。设置 formId="X" 后，X.form 就是必需交付物——需在同一步骤中通过 camunda-forms 编写，或在最终消息中明确标出缺失项。c8ctl bpmn lint 会检查该属性是否存在，但不会检查文件是否可解析。不要使用已弃用的 job-worker 变体（不含 <zeebe:userTask />，使用 formKey 而非 formId）——参见 references/zeebe-extensions.md § 表单定义。
• 服务任务：自动化工作。必须包含 <zeebe:taskDefinition type="..." retries="3" />。类型必须与工作线程注册的类型完全匹配（区分大小写）。如果由开箱即用的连接器支持，请通过 camunda-connectors 应用模板——不要手动编写连接器输入映射。
• 脚本任务：内联 FEEL 表达式。使用 <zeebe:script expression="=..." resultVariable="..." />。
• 业务规则任务：DMN 评估。使用 <zeebe:calledDecision decisionId="X" resultVariable="..." />。decisionId="X" 意味着对应的 X.dmn 是必需交付物——需通过 camunda-dmn 编写。
• 任务名称采用动词 + 宾语模式：“Review invoice”“Send notification”

网关：

• 排他网关（XOR）：只选择一条路径。设置 default 属性以提供安全的回退流，并为条件流添加标签。对于二元或枚举决策（例如，批准/拒绝或是/否），将一个分支设为默认分支，仅在明确选择的分支上设置条件。只有其他条件的计算结果为 false 时才会使用默认分支；它不能处理 FEEL 评估错误。如果输入可能缺失或类型错误，请保护或规范化比较，使其返回 false 而非失败（例如，=if number(string(amount)) != null then number(string(amount)) <= 1000 else false）。切勿生成每条传出流都有条件但没有默认流的 XOR：意外、缺失或类型错误的值可能导致所有条件均为 false，并引发 CONDITION_ERROR 事件。
• 并行网关（AND）：同时执行所有路径。始终使用匹配的汇聚网关进行同步。
• 包容网关（OR）：执行一条或多条路径。同样需要匹配的汇聚网关。
• 修复 c8ctl bpmn lint 报告的虚假汇聚警告——汇聚网关必须与分支网关类型匹配。

顺序流：

• 条件使用带 = 前缀的 FEEL 表达式：

  <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=amount &gt; 1000</bpmn:conditionExpression>
  

BPMN 中的 FEEL 表达式——所有 FEEL 表达式都必须以 = 为前缀：

• 网关条件：=riskLevel = "HIGH"
• 计时器时长：="PT7D"（不带前缀的 PT7D 会被拒绝）
• 输入/输出映射：=customer.name

任何超出简单变量引用的表达式（函数调用、运算符、上下文字面量、for / every / some）都必须先通过 camunda-feel 验证，再提交。

ID：使用描述性 PascalCase 命名——ReviewInvoice、AmountExceedsLimit、Flow_ToApproval

输入/输出映射

创建局部变量并控制变量传播：

<zeebe:ioMapping>
  
  <zeebe:input source="=customer.name" target="customerName" />
  
  <zeebe:output source="=result.status" target="paymentStatus" />
</zeebe:ioMapping>

有关变量作用域、传播规则和示例的详细信息，请参见 references/zeebe-extensions.md。

处理现有 BPMN 文件

BPMN 文件可能很大。请遵循以下规则：

1. 使用 Grep 查找元素——切勿无必要地读取整个文件
2. 使用 Edit 进行修改——先用 Grep 定位确切部分，再进行精确修改
3. 仅阅读特定部分——需要时使用 offset/limit

规范

• 遵循 bpmn-js 的规范样式——参见 references/canonical-style.md
• 空元素使用 <el /> 自闭合（在 /> 前留一个空格）
• 使用唯一且具有描述性的 ID
• 包含用于视觉布局的 BPMN DI 部分（参见 references/layout-rules.md）
• 在元素上包含 <bpmn:incoming> 和 <bpmn:outgoing> 流引用
• 子元素必须遵循 XSD 顺序——否则部署会被拒绝（cvc-complex-type.2.4.a … One of '{…eventDefinition…}' is expected）：documentation、extensionElements、incoming、outgoing，然后（对于事件）是 *EventDefinition。对于事件，流引用必须放在事件定义之前。c8ctl bpmn format -i <file> 会按架构顺序重写子元素——部署手写 XML 前请先运行

Lint 循环 — 结构性退出门槛

只有当 c8ctl bpmn lint 报告零错误且零警告时，BPMN 编辑才算在结构上完成。将此视为每项 BPMN 任务（生成、修改、重构或合并）的最后一个结构性步骤。

1. 对你修改的文件运行 linter：

   c8ctl bpmn lint <path-to-touched-file.bpmn>
   

   c8ctl bpmn lint 会自动检测 BPMN 文件中的 Camunda 执行平台版本，并应用合理的 Camunda 默认值。如果项目中存在 .bpmnlintrc，则会使用该配置。也支持 stdin：cat process.bpmn | c8ctl bpmn lint。

2. 如果输出不为空，请修复所有报告的问题并重新运行 linter。常见类别：

   • no-overlapping-elements — 根据 references/layout-rules.md 中的间距规则调整 DI 坐标
   • fake-join — 使合并网关与其分支网关类型匹配（XOR 分支 → XOR 合并，AND 分支 → AND 合并）
   • label-required — 为每个需要标签的元素命名
   • no-disconnected — 确保每个元素都位于完整的起点到终点路径上
   • no-implicit-split — 排他网关的流出流需要条件和默认流
   • gateway safety — 检查每个排他网关是否有 default 流。conditional-flows 不能取代此项检查：网关的每条流出流都可以有条件，但对于未匹配的值仍然可能没有回退路径。
   • superfluous-gateway — 删除只有一个输入、一个输出的直通网关

3. 重复此循环，直到 linter 检查通过。警告仍然存在时，不要宣称任务在结构上已完成——静默失败的 BPMN 会部署到集群，并以运行时故障的形式暴露。

如果某条警告确实是误报，请在项目级 .bpmnlintrc 中显式抑制，并在最终消息中注明该抑制——绝不要默默忽略。

对于仓库的确定性 smoke 合约，固定的 fixture 命令为：

c8ctl bpmn lint process.bpmn

批量 lint 和修复指南

当任务针对一个目录（而非单个文件）时，请使用 references/bpmn-lint.md 中的目录工作流：递归发现 BPMN 文件（跳过指定目录），逐个 lint 文件，应用针对性修复，然后重新 lint，直到检查通过。

行为验证

Lint 能捕获结构问题，但无法检查运行时行为（FEEL 错误、缺失的 worker、无法到达的结束事件）。Lint 检查通过后，请通过运行流程进行验证：优先使用 camunda-process-test，在无需集群的情况下获取嵌入式引擎反馈；否则可使用 camunda-process-mgmt 部署并运行一个实例。

运行时兼容性检查

在部署或测试 BPMN 更改之前，请使用 c8ctl bpmn lint 对计划部署的确切文件（单个文件或整个目录集）进行兼容性检查。这是必需的运行时兼容性检查，但单凭此项检查并不能保证部署成功。

如果 lint 标记出兼容性问题，请参考以下排查对应关系：

• implementation/task-definition 失败：任务缺少其 BPMN 类型所需的 Zeebe 扩展（<zeebe:taskDefinition>、<zeebe:calledDecision> 等）。
• feel / io-mapping 失败：表达式不符合 Camunda 8 的 FEEL 语法（例如旧版 ${...} 或非 FEEL 映射语法）。请对照 camunda-feel 检查。
• element-type / gateway 失败：模型使用了目标运行时配置文件不支持或不建议使用的构造。
• timer / event-definition 失败：计时器或事件配置在结构上存在，但无法在运行时执行。

完整的兼容性工作流（目标选择、目录运行和修复循环）请参阅 references/runtime-compatibility.md。

参考资料

详细参考资料请查看 references/：

• element-catalog.md — 完整的 BPMN 元素类型及 Camunda/Zeebe 属性（事件、任务、网关、子流程）
• zeebe-extensions.md — 输入/输出映射、变量作用域、任务定义、表单定义、密钥
• layout-rules.md — DI 坐标管理、元素尺寸、图表布局间距规则
• canonical-style.md — 规范的 bpmn-js XML 样式：标签布局、属性顺序、自闭合形式，以及手动格式化为何会产生偏差
• bpmn-lint.md — 单文件与目录 lint 工作流、输出解析及推荐规则的修复对应关系
• runtime-compatibility.md — 部署就绪兼容性 lint 工作流及修复类别