uipath-maestro-bpmn

推理预算

• 根据步骤难度调整推理力度，并倾向于直接执行；对于机械性、输入输出或格式处理步骤，如果已有脚本可以完成任务，就运行脚本——不要重新推导。
• 将深入、扩展的推理留给脚本无法替你完成的那个真正困难的判断。

工作方式

• 先理解，再决定。 阅读此技能的 SKILL.md，并了解它附带的脚本，然后再采取行动。接着据此规划，例如：脚本适用时直接运行，接近适用时修改脚本，或编写补充脚本——判断依据应是脚本的实际功能，而非猜测。
• 预先规划完整流程，然后串联执行。 在运行任何操作之前，概述完整步骤，将相互独立的步骤合并到一轮中，并尽可能用少量轮次串联整个计划。不要逐轮执行本可串联完成的操作。
• 只检查一次输入。 要了解文件结构（工作表／列、页面、表单字段、键），只转储一次——最好输出到文件后再用 grep 检索——绝不要逐字段重新打开同一文件，也不要用多个库反复尝试。源图像例外：当图像不再显示在上下文中时，应再次查看（参见根据图像创作）。
• 不要重复工作。 当输入及相关状态未发生变化时，不要重新运行命令；不要重新读取已在上下文中的未变文件、脚本或 SKILL.md。工具或命令可能修改文件后，依赖其内容前先重新读取受影响的部分。
• 代码只写一次并复用。 如果某个步骤需要代码，就将其写成小型脚本（路径／参数通过命令行参数传入）并调用；不要在多轮中粘贴几乎相同的内联 Python。保持简洁——内联脚本中不要添加注释横幅或叙述。
• 保持输出精简。 不要将大量工具结果和输出放入上下文，而应写入文件并使用工具检查。如果没有可用工具，应自行编写脚本检查文件。要判断某行是否存在，应按字段筛选 CLI JSON（使用 jq select），绝不要截断输出（使用 head、sed -n）。
• 避免不必要的操作。 不要调用工具、读取文件或将结果放入上下文，除非它们能立即派上用场。

UiPath Maestro BPMN

在整个生命周期内处理 UiPath Maestro（流程编排）.bpmn 项目：创作、验证、打包、运行和诊断。已注册节点的创作由注册表驱动：其执行负载来自注册表提供的模板。用于衔接这些节点的 BPMN 结构及序列化器负责的脚手架元数据（流程脚手架、变量、绑定、入口点、顺序流、网关、事件、边界事件、容器、多实例标记和图表）则根据文档规范和画布约定创作。打包、运行（上传、发布、执行）和诊断通过 UiPath CLI 完成，详见下文的功能参考。

适用场景

• 根据描述或流程图像（草图、白板或便利贴照片、其他图表的屏幕截图）创建 Maestro .bpmn。
• 编辑 .bpmn 结构：网关、事件、边界事件、子流程、调用活动、多实例循环、顺序流条件、变量。
• 添加 UiPath 扩展节点（RPA 作业、Agent、HITL、队列、业务规则、API 工作流、Integration Service 连接器、内部消息、计时器）。
• 在导入前根据画布规则验证 .bpmn。
• 打包、上传、发布或运行项目，并管理其作业和实例。
• 诊断运行失败或异常的问题。

编辑现有 .bpmn 文件（保留非你创建的内容）

此技能可以编辑现有文件。如果编辑引入了 Patterns 中的一种形状，请遵循该指南——在运行中的流程中插入一种模式属于常规编辑，不应因此跳过该形状。进行精细编辑，并保留非你创建的内容：未知的 uipath:* 元素、uipath:migrationVersion、标签、导入的 Integration Service 负载，以及稳定的元素 ID。不要重新生成整个文件，也不要删除此技能无法识别的扩展数据——仅保留结构（参见 references/structural-bpmn.md 中的阻止列表）在往返过程中应保持原样。绝不要将现有节点规范化为此技能的规范模板：不要为编辑未涉及的元素补充缺失属性（例如，为现有 uipath:input 添加 type="json" target="bodyField"）；对于未改动的邻接节点，仅允许更改连线（bpmn:incoming/bpmn:outgoing）。 例外：如果 validate 报错指出负载含有 type 属性或位于 <bpmn:extensionElements> 之外，或者 Orchestrator.StartAgentJob 的类型版本不是 v2 且其 releaseKey 或 folderId 没有值，则按规则 6 重写这些负载，并在摘要中逐一列出。

对于现有的 ScriptTask，保留其映射判别符和 uipath:scriptVersion；不要仅仅因为新节点的创建约定不同，就规范化可正常工作的棕地节点。迁移必须获得明确确认——参见 references/structural-bpmn.md。

对于 .flow JSON，请使用 uipath-maestro-flow；对于 XAML/代码化工作流，请使用 uipath-rpa；对于 Python Agent，请使用 uipath-agents；对于 Case 计划，请使用 uipath-maestro-case。

关键规则

1. Registry 拥有其列出的节点负载。 根据 registry get 模板编写执行扩展；仅根据结构／画布契约编写序列化器拥有的脚手架元数据。切勿凭文字描述臆造任何一方。
2. 切勿伪造标识符。 连接 ID、进程／队列／连接器键、应用 ID、文件夹 ID／路径均来自发现结果或用户。对于 describe 条目带有 Reference 的连接器字段，必须使用实时查询返回的 LookupValue，而非用户写下的名称。请参阅 references/registry-workflow.md。
3. 结构性 BPMN 是编写出来的，不是臆造的。 遵循 references/structural-bpmn.md 中的规范／画布契约；如实标明 Registry 未公开的内容。
4. 只进行一轮澄清，然后编写。 仅当请求和 CLI 证据无法确定某项选择，且选错后无法恢复或会迫使你伪造标识符时，才通过 AskUserQuestion 提问；在编写前将这些问题合并为一轮，绝不再开启第二轮。其余事项自行决定并编写，在摘要中说明每项假设及其依据。若请求明确要求不要暂停以征求批准或确认，则什么也不问。若来源是图像，请确认完整清单，而非摘要——请参阅 从图像编写。在草稿模式下，结构问题须等到 3c 阶段再问。
5. 图表必不可少。 导入由图表驱动——每个节点都需要一个 BPMNShape，每条流都需要一个 BPMNEdge，否则不会显示在画布上。uip maestro bpmn format <file.bpmn> 会生成整个图表；应在对 .bpmn 的最后一次写入时运行，并且必须在 validate 或 refresh 之前运行，因为没有图形的节点会导致这两条命令报错。
6. 将节点类型声明为 <uipath:type> 子元素。 每个 uipath:activity／uipath:event／uipath:mapping 都必须位于 <bpmn:extensionElements> 内，并包含 <uipath:type value="<Type>" version="<version>" />。对于包装元素上带有 type 的模板，移除该属性，添加子元素，保留包装元素自身的 version；若没有 <bpmn:extensionElements>，则添加它来包裹负载。这条规则优先于 4b 和 4c 中的原样粘贴要求。<version> 取自模板的 uipath:type；若模板中没有，则取自 uip maestro bpmn registry get <Type>。Orchestrator.StartAgentJob 使用 v2，绑定 name／folderPath，并移除 releaseKey／folderId。事件扩展类型（Intsvc.WaitForEvent、Intsvc.EventTrigger、Maestro.ReceiveMessageEvent、Maestro.SendMessageEvent）必须使用 <uipath:event>，即使 BPMN 宿主是类似任务的元素，例如 <bpmn:receiveTask>。
7. XML 注释中不得包含 --。 XML 禁止在 `` 中出现 --（连续两个连字符），因此切勿将 CLI 命令或标志（如 --output、--connection-id、--object-name）粘贴到注释中，否则文件将无法解析。注释应尽量精简。
8. 对需要解析的 CLI 调用使用 --output json。
9. 始终确保内容可公开。 不得包含客户 XML、租户 URL、真实 ID 或私人名称——请参阅 references/public-safety.md。例外：在用户的本地项目（.bpmn 和 CLI 生成的 bindings_v2.json）中，连接绑定及其文件夹键应使用 4a 绑定时所用的真实 ID（适用占位符时使用 4a 中的名称）。说明以及添加到此技能仓库的示例或测试夹具仍须经过脱敏。
10. 任何云端更改前都必须确认。 发布、部署、运行、暂停、恢复、取消、重试和迁移都需要用户明确同意；先在本地验证。solution upload 是例外：除非请求明确禁止，否则用户要求构建流程即授权上传该流程的展示内容，因此无需询问即可上传。只有项目并非在本次运行中创建时才需确认——即在 2a 中采用现有项目，或原地编辑（棕地项目）；因为上传会覆盖云端与本地 .uipx SolutionId 相匹配的解决方案。应在选定解决方案时（2a）确认；若未执行 2a，则在 4g 上传前确认。
11. 重试属于节点配置，不属于画布。 使用活动上的 uipath:retry 处理瞬时故障。切勿用网关和定时器事件绘制重试循环。请参阅 references/structural-bpmn.md。
12. 任务 SLA 属于任务配置，不属于画布。 审批定时器、重新分配和超时升级都配置在用户任务上。不要将它们建模为任务周围的边界定时器。
13. 错误事件子流程是中断式且终止的。 触发后，正常路径将停止，实例记录为 Completed，而非 Faulted。子流程中的每条路径都必须以明确命名的结果结束，否则已处理的故障将与成功无法区分。若要恢复并继续，请改为附加错误边界事件。
14. 目标系统不同，本身并不意味着形状也不同。 将 Document Understanding 换成 UiPath Agent，或将 Outlook 换成 Gmail，只会改变绑定。只有流程本身确实不同才应调整形状——不能仅仅因为目标系统不同就调整。
15. 你编写流程，但绝不能成为流程的参与者。 若某个形状要求在运行时进行推理、分类或提取，应放置并绑定实际执行这些操作的节点——UiPath Agent、Document Understanding 或业务规则任务。切勿在编写时完成这些工作，也不要将其结果硬编码。任何流程描述中的“agent”若未作限定，均指 UiPath Agent，绝不是你。
16. 生成的包文件由 CLI 管理。 切勿手动编写 bindings_v2.json、entry-points.json、operate.json 或 package-descriptor.json。运行 uip maestro bpmn refresh <project-path> 生成这些文件——切勿使用已弃用的 update-metadata。若用户要求提供 Integration Service 草稿或边界交接（4c），则不需要这些文件——只输出 .bpmn 和一个 .md 说明文件，列出由 CLI 管理的阻碍项。
17. 整合委派给同级技能的资源（RPA 工作流、API 工作流、Agent、业务规则）时，必须按顺序完成以下五个步骤。所属技能交还资源后就停止，不算完成。（业务规则跳过第 4 步；第 3 步中的 release 和文件夹键不适用：它按 name 和 folderPath 绑定，键为 <folderPath>.<name>，详见 registry-workflow.md § 业务规则绑定。） (1) 首先创建或打开解决方案（uip solution init；如果出现 unknown command，则使用旧版命令 uip solution new），并在其中 编写资源的项目，这样它才能注册到 .uipx 中：在存放 .uipx 的 目录中运行资源的 init 和 uip maestro bpmn init，如 Assemble 所示。在任何解决方案之外创建的项目都无法部署。

(2) 将编写工作委派给资源所属的技能（例如 uipath-api-workflow、uipath-rpa），并明确参数契约： 声明输入和输出，而不是未经编写的脚手架。(3) 将资源部署 （打包、发布、solution deploy run）后，再将其绑定到 BPMN 节点； 只有部署后才会有其发布键和文件夹键。要重新部署，请遵循 uipath-solution 的升级路径。

(4) 根据 ProcessType 选择包装器，从 uip or processes list --folder-path <path> --all-fields --output json 读取（registry-workflow.md）； 低代码 Agent 使用 Orchestrator.StartAgentJob（类型 v2，规则 6）， 绑定的是 name 和 folderPath，而非规则 18。对于规则 18 包装器，从 同一响应中读取 Key 和 FolderKey（PascalCase，与默认列表相同； 不带 --all-fields 的默认列表会省略 ProcessType），并按规则 18 进行绑定，绝不能伪造或使用占位键。每次部署后都要重新读取两者： deploy run 会创建新文件夹，因此早先部署时的字面量 folderKey 会指向旧文件夹。(5) 除非任务禁止实时运行，或要求草稿或交接，否则运行流程 （uip maestro bpmn debug），并在 debug-instance variables-all 中读取节点输出。将 =result.<key> 映射到 输出所用的键；标量可能显示在通用键下，而非架构属性名称下。如果没有运行， 则使用架构名称，并报告映射尚未验证。业务规则将其整个结果作为一个 output 从 =result 映射，而不是每个决策或列各映射一个输出。 18. 作业包装器注册表模板（Orchestrator.StartJob、 ExecuteApiWorkflowAsync、StartAgenticProcess[Async]、 StartCaseMgmtProcess[Async]）会提供尚未解析的 releaseKey，该键 虽能通过验证，但在运行时会出错。这一规则优先于 4b 和 4c 中的原样粘贴要求。 对于所有这些模板，都要通过 =bindings.<id> 将 releaseKey 绑定到资源的 Key。仅对于 ExecuteApiWorkflowAsync，还要添加一个包含文件夹 FolderKey 的字面量 folderKey，并删除 folderId、folderPath 和 name。对于其他模板， 保留模板的其余字段，只有在实时运行因 key:FolderKey 出错后才进行此替换； 如果没有运行，则报告该节点尚未验证。详情见： references/registry-workflow.md。

模型

两个部分共同构成有效的 Maestro .bpmn：

1. 注册表列出的节点负载——由注册表管理。 每个列出节点的 执行 XML（uipath:activity / uipath:event / uipath:mapping、其 context、input、output 和 bindingInfo）都来自 uip maestro bpmn registry get <type> 的 xmlTemplate。绝不要根据 文字说明手动编写由注册表管理的节点负载。
2. BPMN 结构和脚手架元数据——由规范/画布管理。 注册表不会生成 <bpmn:definitions>/<bpmn:process>、顺序流、网关条件/默认值、 事件定义负载、边界事件属性、子流程/循环结构或图表。序列化器管理的 脚手架扩展，例如 uipath:variables、uipath:bindings、 uipath:entryPointId 和 uipath:migrationVersion，也来自此 契约，而非节点模板。请根据 references/structural-bpmn.md 编写这些内容； 该文档基于注册表规范、CLI 脚手架和画布序列化器。

模式

七种反复出现的流程形态，可用于构建新流程，也可用于扩展已有流程。每份指南都给出完整的拓扑结构——节点、连线、网关条件、变量——并说明背后的原因。对于同一请求，许多拓扑结构都能通过验证；这些是经过验证的可用形态，而非规范。请根据需要调整：添加步骤、删除分支，以及更改数量。每份指南中的“为何有效”会指出支撑该形态的部分——更改这些部分就意味着你正在构建其他东西，请明确说明。阅读流程实际采用的每种模式对应的指南：简单流程读一份，组合流程读多份；不构建的模式则无需阅读。

每份指南的形态表都会将每个节点标为 Entry（插入到已有流程时省略）、Mechanism（更改它会改变模式）或 Placeholder（绑定它；如果流程已实现相应功能，则可跳过）。请创建表中指定的元素。如果 Placeholder 的目标在 4a 阶段未能解析，它仍应是该元素，带有注册表负载，并将身份字段保留为公开占位符；绝不能用一个裸 bpmn:task 代替实际工作。这适用于阶段 4，此时节点都是真实节点。在阶段 2 骨架中，每个活动都刻意使用裸 bpmn:task——参见 references/phase-2-skeleton-guide.md。

模式	适用场景	指南
ai-decision-review	AI 进行一次调用；根据结果采取行动，或由人工审核	ai-decision-review-guide.md
approval-chain	请求需要多人签字批准	approval-chain-guide.md
smart-triage	将收到的工作分类，并分别交由其他地方处理	smart-triage-guide.md
external-wait	流程在 SLA 期限内等待外部参与方	external-wait-guide.md
high-volume-batch	在一次运行中处理大量独立项目	high-volume-batch-guide.md
failure-escalation	未处理的故障绝不能悄无声息地消失	failure-escalation-guide.md
queue-distribution	Orchestrator 队列在不同运行时之间分发工作	queue-distribution-guide.md

以下情况不要采用模式：需求是一个简短的线性流程、单个节点，或不会引入上述形态的改动。模式绝不是为不需要它的工作硬加上的包装层。

要在一个流程中使用多个模式？请先阅读 references/patterns/composing-guide.md，了解哪个模式保留其开始事件、其余部分接入的四种方式、变量如何跨越嵌套边界，以及引擎限制的两种放置方式。只使用一种模式时，只需阅读该模式自己的指南。

根据图片创作

如果流程来自图片，任务就是转录：图片中的每个项目都变成一个节点，每条可见连接线都变成一条流。根据图片“获得灵感”创作出看似合理的流程，不算转录。最常见的失败是总结时遗漏或合并项目，然后再根据总结来构建。

1. 先盘点，再解读。 在提出任何拓扑结构之前，先写下每个可见项目：其准确措辞、颜色／形状和大致位置。然后逐一列出每条可见连接线，格式为源节点 → 目标节点，并注明其标签以及确定或含糊。对于无法辨认或被划掉的项目，应标记出来，而不是猜测或跳过。将此列表保存在项目文件夹之外的笔记文件中。
2. 确认盘点清单，而不是摘要。 根据规则 4 确认的结构必须列出盘点清单中的每个节点和流。绝不要把精简版或“解读后”的拓扑结构作为推荐选项。针对每处含糊之处分别提问；对于图片中未显示但你打算添加的内容（开始／结束事件、画布要求的合并网关、对隐含连接的解读），也要分别提问。
3. 逐项转录。 图片中的每个项目对应一个节点，并保留图片中的措辞和“是／否”分支标签。仅在画布要求时添加技术性支架，并在最终报告中逐项列出每个新增内容。
4. 始终查看图片。 较早轮次中的图片可能会从你的上下文中消失：宿主可能会用文本占位符替换图片，尤其是在用户发送新消息之后。在进行任何保真度检查之前，包括用户表示结果不匹配时，都要确认你确实能看到图片。如果看不到，请从其文件路径（宿主提供的附件路径）重新读取。如果仍然失败，请让用户重新附加图片。绝不要根据对图片的记忆、你先前的摘要或子 Agent 的文字描述来重建。如果子 Agent 转录了图片，在编辑前要亲自对照图片检查其结果。
5. 完成前核验保真度。 validate 通过后，再次查看图片，并逐个节点、逐条流与 BPMN 对照。报告任何仍然存在的不匹配，而不要声称结果已经完成。验证只能证明文件在结构上有效，并不能证明它与图片相符。

工作流

创作按顺序分为五个阶段。模式决定运行哪些步骤；它不会改变任何步骤的作用。

阶段	步骤	执行内容	参考资料
0 — 检测	—	暂无操作；表面检测是未来的工作。	下文
1 — 预检	1a–1c	检查登录状态，扫描是否存在现有解决方案和项目，并从其云端副本开始。不会更改项目，因此在所有模式下都会运行。	下文
2 — 骨架	2a–2f	搭建项目框架，为空白框添加实际控制流，运行 format、validate，并展示结构。不会调用注册表。仅在草稿模式下运行，2a 除外。	references/phase-2-skeleton-guide.md
3 — 迭代	3a–3c	调整结构，重新运行 format，展示结构，并等待审批关卡。仅在草稿模式下运行。	references/phase-2-skeleton-guide.md
4 — 接入	4a–4g	发现工具，获取模板，将实际负载粘贴到现有框中，进行布局、验证、刷新并展示。	下文

创建骨架（2b–2f）和迭代（阶段 3），是为了在接入之前向用户展示结构。自动模式会跳过这两个阶段：它会运行 2a 来搭建项目框架，然后在阶段 4 直接创作实际节点。其他每个步骤都完全相同。

模式

按从上到下的顺序检查模式，并选择第一个符合条件的模式。Draft 和 auto 是内部名称：不要询问用户选择哪种模式，也不要因选择而停滞。

模式	适用条件	阶段
Brownfield	请求所针对的 .bpmn 文件已存在。不要运行 init；如果该文件是空壳（没有 project.uiproj），请按照 4c 中的双键 project.uiproj + refresh 流程为其引导配置。	0–1，然后 4
Discovery-only	请求要求先发现再编写、保存原始注册表 JSON/证据，或明确要求“暂时不要编写”，即便请求描述了最终要创建的 BPMN 也如此。立即创建 registry-evidence/，保存 registry pull --output json、registry list --output json 或 registry search ... --output json，并为每种请求的类型保存 registry get <type> --output json。不要搭建项目骨架，也不要阅读深入的编写参考资料。操作指南：references/registry-workflow.md。	0–1，然后终止
Draft	会话处于规划模式，或用户希望在构建前先查看或批准方案：先起草、制定计划、勾勒、设计、看起来会是什么样、先给我看看。判断用户意图，而非字面用词：“草稿项目”或“草稿交接”若要求仅提供源文件交付物（规则 16），则属于 auto 模式。	0–3，在关卡处停止
Auto	其他所有情况。这是默认模式。	0–1、2a、4，不停止

在最终报告中说明采用了哪种模式。

在规划模式下，须等计划获批后才能写入：先在计划中列出骨架大纲（方框、网关、条件），然后在计划获批后执行 2a–2f。

只有 3c 中的 Build it 才授权进入阶段 4。 用户保留大纲，或尚未回复时，应将骨架作为大纲报告，而不是作为已完成的流程。Draft 模式下，如果请求允许上传，应通过上传来展示方案（2f）；如果禁止上传，则展示整理好的本地 .bpmn 路径和简短的文字大纲。

尽早开始编写：不要在动笔前预读所有参考资料。只有到达相关结构时才阅读对应参考资料，并且只读涵盖该结构的部分——references/structural-bpmn.md 开头有一个章节索引，列出了每个锚点。获取所需模板后，先写出第一个完整版本，再继续深入查阅资料。

阶段 0 — 表层

暂时无需操作。表层检测属于后续工作。

阶段 1 — 预检

• 1a 检查登录状态。 在与 1b 扫描相同的 Bash 调用中串联运行 uip login status --output json——不要单独占用一轮。未登录时，registry pull 只会返回内置（OOTB）扩展类型，因此连接器和流程的发现结果会悄然不完整：应告知用户，而不是基于不完整的注册表进行发现。本地编写和 validate 仍可离线使用——参见 references/cli-conventions.md。

• 1b 扫描解决方案和项目。 使用主机提供的任意文件搜索方式，查找工作目录下两级以内的所有 *.uipx 文件，例如：

  find . -maxdepth 2 -type f -name '*.uipx' -print
  

  搜索结果决定 2a 是创建还是采用。记录结果；第 2 阶段不要再次扫描。

• 1c 从云端副本开始。 如果 1b 找到了一个解决方案（仅发现模式时跳过此步骤），则根据其 .uipx 中的 SolutionId 将其下载到单独的目录：

  uip solution download <SOLUTION_ID> --extract -d <DOWNLOAD_DIR> --output json
  

  init 会在任何上传之前写入 SolutionId，因此，如果失败时 Instructions 提示“Studio Web API returned 404”，就表示云端副本尚不存在：跳过 1c 的其余部分。如果下载因其他原因失败（离线、未登录），则跳过 1c，并在最终报告中说明。否则，比较下载内容中的每个项目 .bpmn 与本地文件；Studio Web 会重新格式化 .uipx 和 project.uiproj，并添加 SolutionStorage.json，因此只有 .bpmn 文件能反映实际编辑内容。如果两者相同，继续操作。如果不同，在编写之前询问用户要保留哪个副本，因为之后的 upload 会用本地副本替换云端副本，从而抹去在 Studio Web 中所做的编辑。

阶段 2 — 骨架

除 2a 外，仅限草稿模式。2b 至 2f——编写空框、format、validate、refresh、展示骨架——详见 references/phase-2-skeleton-guide.md。这里只列出 2a，因为这一步取决于阶段 1 的扫描结果。

• 2a 创建或采用项目（仅限全新项目）。仅发现模式、对 brownfield/裸 .bpmn 进行编辑，以及用户要求的 Integration Service 草稿或边界交接（规则 16）均跳过此步骤。否则，应在同一轮中将其接在 1b 之后。步骤 1b 已确定是否存在解决方案；采用找到的解决方案，不要再次扫描。如果用户指定了项目路径（A/B/B.bpmn 表示项目目录为 A/B），则对该目录的父目录运行 mkdir -p，进入该目录，并在其中运行 uip maestro bpmn init <B> --skip-solution-registration --output json；只有当该父目录已经是解决方案时，才省略此标志。否则，init 会额外创建路径中没有的 <B>Solution/ 层级。无论哪种情况，都只能编写返回的 Data.Path 所指向的 .bpmn 文件；绝不要在其他位置另写一个 .bpmn 文件。

  如果找到了任何解决方案，请停下来询问用户要使用哪个；如果主机支持选项列表，则以选项列表形式呈现：每个找到的解决方案各列一项，另加“创建新解决方案”。绝不要悄悄采用、初始化或修复现有解决方案。在询问时说明，采用现有解决方案意味着后续的 upload 会覆盖其云端副本，因为这是用户仍可做出选择的最后时机。如果没有找到任何解决方案，则现在按照 组装（4c）中的规则运行 init；2b（草稿模式）或 4c（自动模式）会将内容编写到它生成的 .bpmn 文件中。

阶段 3 — 迭代

调整结构，重新运行 format，展示更改，并在用户同意前保持审批关卡：参见 references/phase-2-skeleton-guide.md。 仅限草稿模式。

阶段 4 — 连接

• 4a 发现。 执行一次 uip maestro bpmn registry pull（在当前会话中缓存——不要重新拉取），然后用 list / search 将意图映射到扩展类型；用 uip is connections list --all-folders 查看实时连接（始终使用 --all-folders——按文件夹筛选的列表会悄悄漏掉连接）。绝不要捏造标识符；仅在规则 4 要求时询问，否则自行决定。将每个连接器节点绑定到该连接器的一个 Enabled 连接：优先选择任务指定文件夹中的连接，否则选择 IsDefault 为 Yes 的连接，否则选择第一个。使用 uip is connections ping <id> --output json 确认（Data.Status 必须为 Enabled；列表中的 State 是缓存值），如果不满足条件则尝试下一个候选项。连接的所有者是其他人，并非跳过它的理由；将每个绑定连接的 Name、Owner 和 Folder 作为规则 4 的假设列出（绝不列出其 Id）。仅当用户要求只包含源文件的草稿（规则 16）、交接，或占位符、合成、可公开安全或已脱敏的值时，或者没有候选连接通过 Enabled 检查时，才使用占位符。 参见 references/registry-workflow.md。

• 4b 获取模板。 仅对选定的、由注册表管理的节点执行 uip maestro bpmn registry get <type> --output json。在一次 Bash 调用中获取所有选定模板，而不是每轮执行一条命令——每次 Shell 往返都会占用一个模型轮次，几十次往返会在创作完成前耗尽本次运行的时间预算： for t in TypeA TypeB TypeC; do uip maestro bpmn registry get "$t" --output json; done。 使用 --connection-id/--object-name 补充 Intsvc.* 连接器节点；从 references/registry-workflow.md 中的表格获取 --object-name——一个连接器针对每项操作会公开多个对象，而 describe 不会对它们排序。不要对注册表从不管理的结构性缺项调用 registry get：顺序流、网关、事件、边界事件、多实例/循环标记、errorMapping/重试结构或图表。粘贴任何 bpmn: 标签时，无论开始标签还是结束标签，都要将 bpmn: 后的首字母小写：<bpmn:UserTask> → <bpmn:userTask>、<bpmn:ServiceTask> → <bpmn:serviceTask>。除规则 6 和 18 另有规定外，原样保留 uipath:* 负载。 BPMN.ScriptTask 是注册表查询键，但新节点序列化后会生成 <uipath:type value="BPMN.Variables" version="v1" />——绝不要使用查询键。本地验证接受旧版判别符，因此 validate 通过并不能证明映射正确。有关兼容性回退及其适用范围，参见 references/structural-bpmn.md#script-tasks--jint-authoring-contract。

• 4c 组装。 如果本次运行上传了该流程图形，先下载（如 1c 所述）；如果其 .bpmn 与本地文件不同，则基于下载的文件继续构建（4g 有此要求）。对于从零开始的项目，在 2a 的 init 生成的 .bpmn 文件中直接编辑；绝不要替换整个文件。直接编辑可以保留生成的四个 JSON 文件、初始化程序的 Event_start id，以及其 uipath:entryPointId。以 references/structural-bpmn.md 中的完整最小文件和每个节点的 xmlTemplate 为基础进行创作（仅填入占位符）。该骨架展示了一个稳定的手动入口点、一个结构性任务以及完整的 DI。不要从任务夹具、生成的包文件或 node_modules 下任何已安装的软件包中逆向推导创作模式——这类探索是创作运行超时的首要原因。 仅添加流程所需的结构元素（额外的网关、事件、边界事件、容器、多实例标记、表达式/错误映射、重试属性）。将图表留到 4d 处理；源文件尚在变动时，不要手动编写 bpmndi:*。对于新的本地项目，使用 uip maestro bpmn init <ProjectName> --output json 初始化受支持的脚手架，在返回的 Data.Path 处编辑，并保留其生成的元数据。对于用户未要求打包或运行的只包含源文件的草稿，传入 --skip-solution-registration，这样就不会创建 *Solution/ 封装或 .uipx。init 接受项目名称而非路径，并会写入当前目录：使用该标志时写入 ./<ProjectName>/；否则，如果位于现有解决方案中，则写入 ./<ProjectName>Solution/<ProjectName>/。 当用户指定解决方案名称时（“同名解决方案”指的是 <ProjectName>，而不是 <ProjectName>Solution），请创建该解决方案，并在其中运行 init：

  uip solution init <SolutionName> --output json
  cd <SolutionName> && uip maestro bpmn init <ProjectName> --output json
  

  如果响应中出现 Data.AutoCreatedSolution，说明 init 是在解决方案外部运行的：请在解决方案内部重新运行，并报告多余创建的目录。

  若要将项目创建在用户指定的路径下，请对其父目录运行 mkdir -p，然后在该目录中运行 init，并将叶目录名作为项目名称；同时，需传入 --skip-solution-registration，或者先将该父目录创建为解决方案，因为默认情况下，init 会插入一个 <ProjectName>Solution/ 层级，而指定路径中并没有这一层级。编辑前，请确认 Data.Path 与指定路径一致。较旧的 init 脚手架不会声明 xsi 命名空间：在写入任何 xsi:type 属性前，请将 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 添加到 bpmn:definitions。请参阅 references/shared/local-metadata-regeneration-guide.md。 可运行的 BPMN/启动事件路径必须放在小写的 operate.json.main 中， 绝不能放在 project.uiproj.main 中。 添加草稿版或仅保留的案例管理变体时，请将真实的、包含合成内容的 小写 <uipath:caseManagement version="v1">...</uipath:caseManagement> 载荷作为单独的仅保留扩展纳入其中。用户要求保留案例管理契约变体时，不要将 Orchestrator.StartCaseMgmtProcess* 类型化活动外壳视为该载荷的替代品。 用户要求保留通用的不受支持的 uipath:Activity 时，请写入实际的大写元素 <uipath:Activity version="v1">...</uipath:Activity>。 不要写入 <uipath:activity><uipath:type value="uipath:Activity" ... />； 这是小写的类型化外壳，并非仅保留的通用载荷。 在 XML 属性值中写入可公开使用的占位符时，请对尖括号进行 XML 转义：在属性中使用 <TENANT_URL>、<FOLDER_KEY> 和 <CONNECTION_NAME>。原始的 <PLACEHOLDER> 文本仅在元素文本或 CDATA 中安全； 在属性中使用未转义的尖括号会导致 BPMN 格式不正确。 根据 Actions.HITL 用户任务的结果进行路由时，独占网关中的顺序流条件必须引用 HITL 模板 <uipath:output ... var="..."> 绑定的确切变量（例如 =vars.Var_HitlResult == "approve"），不能只引用复制或派生的脚本变量。 所有新建的连接器节点在所有工作流中都必须是 V2，包括 HTTP 请求 （Intsvc.UnifiedHttpRequest）和外部 Agent；请使用 registry get --input-details 构建，并原样粘贴 Data.V2。对于不含 <uipath:intsvcActivityConfig version="v2" /> 的现有工作流，绝不要添加该标记；除非任务有要求，否则保留其 V1 节点不变（V1 触发器 或等待节点会在运行时出错，因此任务涉及这些节点时，请将其重新构建为 V2）。 如果 registry get 报错 unknown option '--input-details'，说明 CLI 版本早于 V2 节点： 遇到触发器、等待节点、HTTP 请求或外部 Agent 时请停止，并告知用户更新 uip； 只有普通活动才可回退使用 V1 模板。请参阅 references/v2-connector-nodes.md。

  执行 bpmn refresh 后，请运行 uip solution resources refresh，以便将连接转换为解决方案资源。 填写 V1 模板（较旧的 CLI，或读取现有 V1 节点）时，对于 inputTarget 为 body 的 Intsvc.* 活动 （Intsvc.ActivityExecution 及其异步、Agent 和工作流变体）， 以下规则优先于模板的 InputNotes、DiscoveryNotes 和 ContextFieldNotes：

  • 一个 body。 必须且只能有一个 <uipath:input name="body" type="json" target="body">，在 CDATA 中包含完整请求对象，绝不能每个字段对应一个 input，也不能是裸数组。带点号的名称会形成嵌套结构（fields.project.key → {"fields":{"project":{"key":…}}}）；users[*] 是 users 下的数组（{"users":["U1","U2"]}）。将其以及每个 Parameters input 都放在 <uipath:activity> 内，位于 </uipath:context> 之后、模板的 <uipath:output> 之前。放在 </uipath:activity> 之后的 input 不会发送，而且 validate 不会发现此问题。参见 Body shape。
  • 必需的 Parameters。 每个 Required: true 条目（Slack 的 send_as） 都必须是独立的 uipath:input，其 target 设为对应的 Type， 放在 </uipath:context> 之后且仍位于 <uipath:activity> 内；其值取自 请求，否则使用其 DefaultValue。参见 Parameters。
  • operation（仅适用于 Intsvc.ActivityExecution）是所述的 Operation.Name（Create、List、Retrieve、Update、Delete、 Replace），绝不能是活动的 Name。
  • Data Service 文件使用 UploadFileToRecordField、 DownloadFileFromRecordField 和 DeleteFileFromRecordField，绝不能使用 uip is resources list 显示的 V2 对象。参见 Picking the object。
  • folderKey（仅适用于 Intsvc.ActivityExecution）。保留模板的 folderKey 上下文 input，将其设为 =bindings.<folderBindingId>，并在每个绑定连接的节点上保留其文件夹绑定。缺少此项会导致运行失败，错误为 102010 Value cannot be null (Parameter 'Folder')。参见 Bindings。
  • 值。 Reference 字段接受查找得到的 ID（规则 2）。不以 = 开头的 body 值是字面值：写成 "=vars.<id>"；与变量混合的文本应写成一个 =js: 表达式（"=js:'Severity: ' + vars.Var_Severity"）。 对于用户要求的 Integration Service 草稿或边界交接（仅要求验证的请求不算），只输出 .bpmn 和说明文件——不要创建四个生成的包文件（规则 16）；创建这些文件会违反任务测试的边界。节点本身仍需编写：粘贴注册表中的 Intsvc.* 模板，并保留模板声明的外壳——活动使用 uipath:activity，Intsvc.WaitForEvent 和 Intsvc.EventTrigger 使用 uipath:event（规则 6）——以及其上下文和输出，同时用转义后的公开占位符填写资源标识槽位。事件上下文将连接引用为 connectionId，活动则引用为 connection。不带这两种外壳的宿主元素，例如不含 uipath:activity 的裸 bpmn:sendTask，属于缺失节点，不是草稿。只有已解析的值由 CLI 负责提供——参见 references/registry-workflow.md。 对于 Integration Service 草稿说明，必须逐字写出每个由 CLI 负责提供的阻塞项，包括确切短语 connection binding，以及动态架构、生成的输出、bindings_v2.json 和包元数据。避免使用“连接和流程绑定”这类较含糊的说法，因为它会掩盖 CLI 必须提供的具体产物。 每次编辑更改了开始事件 ID，或添加、移除了入口点后，都要运行 uip maestro bpmn refresh <project-path>——不只是打包或运行时；触发器开始草稿（见下文）是例外。先布置图表（4d）：refresh 会先验证再写入，因此刚添加的节点会导致验证失败，报错 MISSING_DI_SHAPE。operate.json 和 entry-points.json 只生成一次，不会跟随源文件编辑更新，因此 4e 的验证器会因不匹配而失败： entry-points.json references start event "Event_start" via filePath, but no <bpmn:startEvent id="Event_start"> exists。从上面的最小文件完整替换文件内容会重命名初始化程序的 Event_start，因此纯源文件草稿也需要执行此操作；原位编辑则可避免此问题。保留原样输出——这是 pack 使用的约定结构。 refresh 需要由初始化程序生成的项目：如果没有 project.uiproj，就会失败并报错 Required file is missing / RetryWillNotFix。 对于裸 .bpmn 文件（本仓库编辑用例的形式），先写入双键 project.uiproj——{ "Name": "<ProjectName>", "ProjectType": "ProcessOrchestration" }——然后运行 refresh，由它写入其余内容。只有在 CLI 不可用时，才使用 references/shared/local-metadata-regeneration-guide.md 中等效的手工编写结构。不要将 CLI 脚手架元数据结构复制到合成的本地项目中。每个根级手动开始事件都需要在其 extensionElements 中包含一个 <uipath:entryPointId value="<uuid>" /> 子元素；否则 refresh 会导致整个项目失败并报错 RetryWillNotFix，而不是写入空的入口点列表。当请求指定以触发器作为开始，且未要求可交付的成品包、上传、调试、发布或部署时，这就是触发器开始草稿。对于计时器或 V1 连接器开始事件，应原位将初始化程序的 Event_start 改为触发器，保留其 ID 和 uipath:entryPointId 子元素，不添加第二个开始事件，并跳过 refresh（仅有计时器或 V1 开始事件时没有入口点，因此会失败），即使已绑定连接也一样；entry-points.json 会保持有效。如果要求上述任何一种可交付内容，包括之后对这类草稿提出的要求，则保留手动的 Event_start，为触发器设置独立的开始 ID，按 Gateways 将两者连接起来，并运行 refresh。V2 连接器触发器开始事件是例外，也是通常情况，因为每个新触发器都是 V2：它带有自己的 uipath:entryPointId，并且是一个入口点。在草稿中，粘贴其 Data.V2 元素，并将 {{ID}} 设为 Event_start，替代手动开始事件；不要添加第二个开始事件，并运行 refresh；跳过此步骤会使 entry-points.json 保留旧 ID，导致 validate 失败。可交付内容也可以采用相同做法，或者保留手动的 Event_start，并按上述方式将它与触发器连接，以便从任一开始事件进行调试。 循环计时器应使用带 R/ 重复标记的 timeCycle（R/P1D），而不是模板的 timeDuration。通过编辑或删除 entry-points.json 来清除过期入口错误，而不运行 refresh，虽然能通过 validate 和 pack，但会导致交付的 bindings_v2.json 为空。 为公开输入和输出提供明确的运行时桥接，并将返回单个结果的分支汇聚到同一个完成 EndEvent——关于两层约定，请参见 references/structural-bpmn.md。

• 4d 布置图表。 在最后一次源文件编辑之后、任何 validate、refresh 或 pack 之前——包括用于以下内容的 4c refresh 调用：

  uip maestro bpmn format <file.bpmn>
  

  它会原位覆盖文件中的 bpmndi:BPMNDiagram，使画布呈现排布好的流程，而不是堆叠在原点的流程。每个交付物都会执行此操作，包括仅含源文件的草稿。这也是后续两个步骤的硬性前提，而非外观优化：没有 BPMNShape 的节点或没有 BPMNEdge 的流都会导致 validate 报错 MISSING_DI_SHAPE / MISSING_DI_EDGE；完全没有图表则会报错 BPMN_PARSE_ERROR；而 refresh 会先验证再写入，因此也会以相同方式失败。再次编辑源文件后，布局就会过时——重新验证前请重跑此步骤。如果 format 报告 unknown command，请更新 CLI（参见 references/cli-conventions.md）；如果无法升级，请在 references/structural-bpmn.md 中手动编写备用 DI 结构。

• 4e 验证。 首先检查格式是否正确。validate 使用容错解析器进行分词，对于带有未绑定命名空间前缀的 XML 也会报告 Valid，因此此处的 ParseError 表明源文件有缺陷，应先修复再处理其他问题。然后运行 CLI 验证器，它会离线运行完整的 PO.Frontend 画布规则集（结构规则，以及变量、方法调用、输入类型和事件对象检查），并执行部署就绪性检查：

  python3 -c "import sys, xml.etree.ElementTree as ET; ET.parse(sys.argv[1])" <file.bpmn> &&
    ! grep -nE '</?bpmn:[A-Z]' <file.bpmn> &&
    uip maestro bpmn validate <file.bpmn> --output json
  

  validate 不区分标签大小写；grep 打印出的行中，标签需要改为小写（4b）。

  退出码 0 = 有效。退出码 1 = 解析错误、grep 命中或 validate 失败。请根据每条问题中的 [error] / [warning] 标签判断严重级别，而不是看 Found N error(s) 标题；该标题统计错误，但其下的列表也会打印警告。只修复错误级别的问题，然后重新运行 4d 并再次验证；剩余问题全为警告或以下占位符问题对时，就停止重新验证。read but never assigned 是没有任何错误覆盖的一项缺陷：流程读取的值没有被写入，因此本应生成该值的步骤没有做到这一点。MISSING_RESOURCE（警告）和 MISSING_BINDING（错误）是同一个未解析节点的问题，而绑定部分会查询实时租户。请将该节点绑定到已部署的资源。如果用户要求使用占位符、仅含源文件的草稿（规则 16）或边界交接，或者 4a 未找到 Enabled 候选项，那么虚构标识符无法消除 MISSING_BINDING（规则 2）：退出码 1 / RetryWillNotFix 是预期结果。报告一次这对问题后继续；即使问题尚未解决，refresh（4f）也能成功。请修复每个 VARIABLE_DOES_NOT_EXIST 警告：它指向一个没有声明的引用。读取启动事件作用域调用方输入的节点上出现 VARIABLE_NOT_SET 警告是预期情况；参见 references/structural-bpmn.md#validation。

  [warning] [(xml)] unknown attribute <type> 是脚本任务模板中的 <uipath:inputSchema type="jsonSchema"> 所产生的预期噪声。请保留它。type 是 uipath:input、uipath:output 和 uipath:inputOutput 上的必需属性；在这些位置移除它会导致加载失败，并报错 BPMN_PARSE_ERROR ... to be a string。不要逐段二分文件，也不要为了查找该规则而读取 node_modules 下的包文件。

  验证是结构性预检，并非运行时证明——参见 references/cli-conventions.md。获得执行授权后，请检查运行时变量、元素执行情况和事件，再报告行为是否成功。

  如果 validate 报告 unknown command，或明显跳过了结构规则，则说明已安装的 CLI 版本太旧——请更新（参见 references/cli-conventions.md）。另见 references/structural-bpmn.md#validation。

• 4f 刷新派生元数据。 4e 没有留下可修复的错误后，重新生成由 CLI 管理的四个包文件：

  uip maestro bpmn refresh <project-path> --output json
  

  将非零结果视为源文件／前置条件失败：修复 BPMN 或 project.uiproj，重新运行 4d 和 4e，然后再次刷新——绝不要手动修复生成的 JSON。绑定连接（4a）后，以及准备就绪、上传、调试、发布或部署交付物时，都要刷新；仅源文件的 草稿只需在 4c 编辑开始事件后刷新，而触发器启动的 草稿（4c）则跳过刷新。完整约定（范围、幂等性、 绑定规则）请参阅 references/shared/local-metadata-regeneration-guide.md。

• 4g 展示完成的流程。 当请求允许上传，且项目包含解决方案（.uipx）时，运行 uip solution upload <SolutionDir> --output json 会返回 Data.DesignerUrl。如果项目不是在本次运行中创建的（棕地项目，或在 2a 中采用但未获确认），上传前请先确认（规则 10）。当请求禁止上传或 不存在解决方案时，跳过此步骤。然后按以下格式回复，删除不适用的行：

  <Name>: built, validated<, uploaded><, run>. <One sentence if you kept the user's online changes.>
  <DesignerUrl as a link on its own line, or the local .bpmn path>
  
  - <what changed, one line each, up to 5>
  
  Assumed: <...>  Unverified: <...>
  

操作与诊断

除了创作之外，此技能还可通过 UiPath CLI 打包、交付、运行和诊断 Maestro 项目。

• 打包与操作（打包项目、上传到 Studio Web、发布或部署、运行或调试实例，以及管理作业、实例、事件和生命周期操作）：请参阅 references/operate/CAPABILITY.md。
• 诊断（获取事件、变量和元素执行记录，并将失败的运行追溯到其 BPMN 元素）：请参阅 references/diagnose/CAPABILITY.md。 运行时证据——事件、变量、元素执行记录、游标、已部署资产——只能通过 uip maestro bpmn ... --output json 读取， 每次读取只能使用一条原样命令，绝不循环（该文档中的规则 9）； 本地 .bpmn 源文件和生成的程序包文件仍照常从磁盘读取。 绝不要用 CLI 所读取的底层文件代替 CLI 本身——请参阅该文档中的规则 3。

任何云端更改（发布、部署、运行、暂停、恢复、取消、重试、 迁移）都需要用户明确同意，并且应先通过本地验证。solution upload 是例外——请参阅规则 10。

结构覆盖范围

此技能介绍如何编写画布支持的全部结构。注册表提供模板的内容与需要手动编写的内容如下：

结构	来源
节点 uipath:* 载荷（RPA、Agent、HITL、队列、业务规则、API 工作流、IS 连接器、内部消息、计时器、脚本）	注册表 xmlTemplate
<uipath:variables> 声明（每个声明都有一个 elementId）	手动编写（注册表缺失项）
<bpmn:definitions>/<bpmn:process> 脚手架 + 命名空间	手动编写（注册表缺失项）
顺序流、conditionExpression、网关 default	手动编写（注册表缺失项）
网关：排他、并行、包容、事件驱动（复杂网关仅保留）	手动编写（注册表缺失项）
事件 + 事件定义矩阵：消息、计时器、错误、终止（仅限结束事件）。信号/升级/条件/链接/补偿/取消/多重事件仅保留	手动编写（注册表缺失项）；载荷依据画布序列化器
边界事件：attachedToRef、中断/非中断（cancelActivity）	手动编写（注册表缺失项）
子流程、事件子流程（triggeredByEvent）、调用活动	手动编写（注册表缺失项）；调用活动载荷来自注册表
多实例 / 循环特征	根据画布契约手动编写 — 注册表不提供模板（注册表缺失项）
bpmndi:BPMNDiagram（每个节点一个形状，每个流一个边）	通过 uip maestro bpmn format <file.bpmn> 生成 — 注册表不会生成（注册表缺失项）

已标记的注册表缺失项：注册表不提供结构性 BPMN、顺序流条件、事件定义载荷、边界事件属性、多实例标记或图表的模板。这些内容依据规范 + 画布契约编写，详见 references/structural-bpmn.md；用户询问时，应如实说明这些缺失项。

参考资料

主题	阅读
阶段 2 骨架 — 空白方框、真实控制流、不调用注册表	references/phase-2-skeleton-guide.md
发现 → 模板 → 绑定 → 组装循环	references/registry-workflow.md
结构性 BPMN、事件矩阵、边界事件、容器、多实例、图表、验证	references/structural-bpmn.md
常见流程形态的完整拓扑，以及形态的组合方式	上方模式表 → references/patterns/*-guide.md
运行时表达式、vars./bindings./iterator.、=js:（Jint）语法	references/expression-authoring.md
CLI 约定与副作用边界	references/cli-conventions.md
确保内容可公开展示且安全	references/public-safety.md
打包、上传、发布、运行或管理实例	references/operate/CAPABILITY.md
诊断运行失败或行为异常的问题	references/diagnose/CAPABILITY.md
项目布局与生成的包文件	references/shared/project-layout.md