Activepieces 流程控制深度指南：用 MCP 工具构建 Router 分支与 Loop 循环-平芜编程栈

Activepieces 流程控制深度指南：用 MCP 工具构建 Router 分支与 Loop 循环

【免费下载链接】activepiecesAI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces

本文聚焦 Activepieces 的「细分构建路径」（granular build path），完整讲解如何用 MCP 工具ap_create_flow/ap_add_step以编程方式搭建Router 分支与Loop 循环，包括分支定位参数stepLocationRelativeToParent的四种取值、BranchOperator全部条件运算符、循环体内的item/index引用与iterations输出语义，以及"深嵌套拍平"的架构建议。读完本文，你将能通过 API 精确控制流程结构，并避开空分支校验失败、分支索引越界、循环结果误读等常见陷阱。

Activepieces 的流程构建存在两条路径：快速路径ap_build_flow适合线性流程；而一旦涉及分支（Router）与循环（Loop）这类控制流结构，就必须改用细分构建路径——先用ap_create_flow创建流程，再逐个用ap_add_step添加步骤。控制流步骤的类型只有两种：ROUTER（路由/分支）与LOOP_ON_ITEMS（循环）。本文将围绕这两个类型，结合仓库内 MCP 工具的实际实现，给出完整可用的构建方法。

一、核心前提：`stepLocationRelativeToParent`决定步骤挂在哪

在细分构建路径中，每个新步骤通过ap_add_step插入，而它的位置由stepLocationRelativeToParent参数决定，可选值如下：

取值	含义	何时使用
`AFTER`	放在父步骤之后（顺序执行）	线性推进流程
`INSIDE_BRANCH`	放进某个 Router 分支内作为该分支的第一个动作	配合`branchIndex`指定分支
`INSIDE_LOOP`	放进循环体内作为第一个动作	构建循环体
`INSIDE_ON_SUCCESS_BRANCH`/`INSIDE_ON_FAILURE_BRANCH`	放进某个开启了 continue-on-failure 步骤的成功/失败分支	错误处理，详见 error_handling.md

从 ap-add-step.ts 的输入 schema 可以看到，stepLocationRelativeToParent是必填的枚举参数，branchIndex仅在INSIDE_BRANCH时必填——源码中明确做了校验：

if (stepLocationRelativeToParent === StepLocationRelativeToParent.INSIDE_BRANCH && branchIndex === undefined) { return { content: [{ type: 'text', text: '❌ branchIndex is required when stepLocationRelativeToParent is INSIDE_BRANCH...' }] } }

另外，ap_add_step支持一次调用即完成"添加 + 配置"：PIECE 步骤可传pieceName/actionName/input/auth，CODE 步骤可传sourceCode/packageJson，循环步骤传loopItems（迭代数组的表达式，如{{step_1['output'].items}}）。步骤尚未配置时valid: false，配置完成并校验通过后才为true。

二、Router（分支路由）：自上而下匹配，首个命中即执行

Router 会自上而下依次评估各条件分支，执行第一个匹配的分支；所有分支都不匹配时，落入末位的Otherwise（兜底）分支。从 ap-add-step.ts 可以看到，新建 ROUTER 时默认的骨架设置是executionType: EXECUTE_FIRST_MATCH，即"执行首个匹配"。

2.1 三个常见陷阱（Gotcha）

Gotcha 1 —— 新 Router 天生带着两个分支。调用ap_add_step（stepType 为ROUTER）时，系统会自动创建两个分支：

Branch 1：条件分支，但条件为空（conditions: [[]]），此时整个 Router 处于"空分支"的非法状态，无法通过校验；
Otherwise：兜底回退分支（branchType: FALLBACK）。

因此构建 Router 的标准动作序列是：

ap_add_step（stepTypeROUTER）→ 得到Branch 1（空）+Otherwise；
二选一：用ap_update_branch填充Branch 1的条件，或用ap_delete_branch（branchIndex: 0）删掉它，再用ap_add_branch添加真实条件分支；
继续用ap_add_branch添加更多条件分支；
用ap_add_step+stepLocationRelativeToParent: INSIDE_BRANCH+branchIndex: N向各分支填入步骤。

Gotcha 2 ——branchIndex从 0 开始。条件分支按顺序排在末尾的Otherwise之前，索引从 0 计数。这一点在 ap-delete-branch.ts 的越界校验中体现得很清楚：合法索引范围是0到branches.length - 2，而branches.length - 1是兜底分支，不可删除。ap_add_branch的实现（ap-add-branch.ts）也是取branches.length - 1作为插入位置，即永远插在兜底分支之前。

Gotcha 3 ——ap_delete_branch是级联删除。删除分支会连同分支内的所有步骤一并删除。删除前务必先保存/迁移需要保留的内容。该工具在 MCP 声明中也被标记为destructiveHint: true，属于破坏性操作，调用时需谨慎。

2.2 分支条件运算符（BranchOperator）

分支条件唯一合法的运算符如下（逐字引用，注意精确拼写）：

TEXT_CONTAINS TEXT_DOES_NOT_CONTAIN TEXT_EXACTLY_MATCHES TEXT_DOES_NOT_EXACTLY_MATCH TEXT_START_WITH TEXT_DOES_NOT_START_WITH TEXT_ENDS_WITH TEXT_DOES_NOT_END_WITH NUMBER_IS_GREATER_THAN NUMBER_IS_LESS_THAN NUMBER_IS_EQUAL_TO BOOLEAN_IS_TRUE BOOLEAN_IS_FALSE DATE_IS_BEFORE DATE_IS_EQUAL DATE_IS_AFTER LIST_CONTAINS LIST_DOES_NOT_CONTAIN LIST_IS_EMPTY LIST_IS_NOT_EMPTY EXISTS DOES_NOT_EXIST

需要注意两个易错点：

拼写是TEXT_START_WITH（不是..._STARTS_WITH）；
不存在NUMBER_IS_NOT_EQUAL_TO。需要"不等于"语义时，用NUMBER_IS_GREATER_THAN/NUMBER_IS_LESS_THAN组合表达，或借助兜底分支取反。

条件组合语义：条件数组采用「外层数组 = OR 组、内层数组 = AND 条件」的结构——同一组内多个条件是 AND，不同组之间是 OR。这在ap_add_branch/ap_update_branch的 schema 注释中写明（ap-add-branch.ts）。任何稍复杂的组合都建议用ap_validate_flow验证后再发布。分支排序遵循"最具体在前"原则，把命中范围小的分支放前面，用Otherwise兜底。

2.3 分支操作的其余细节

ap_update_branch可同时更新分支的branchName与conditions，但不能给兜底分支设置条件（ap-update-branch.ts 会直接拒绝），兜底分支只能改名；该操作不会影响分支内已有步骤。
想知道某个 Router 当前有哪些分支、分支索引是多少、每个分支内已有哪些步骤，可调用ap_flow_structure查看——它的输出为每个步骤标注了relationship（branch、first_loop_action、on_success_branch、on_failure_branch等）与branchIndex/branchName（ap-flow-structure.ts），是定位父步骤名和分支索引的首选工具。

三、Loop（循环）：`LOOP_ON_ITEMS`

用ap_add_step（stepTypeLOOP_ON_ITEMS）创建循环步骤，通过loopItems参数传入要遍历的数组表达式（如{{step_1['output'].items}}），循环体步骤用stepLocationRelativeToParent: INSIDE_LOOP挂入。

3.1 循环体内的可用引用

当前项：{{loopStep['output'].item}}，取字段用点号深入，如{{loopStep['output'].item.email}}；
当前索引：{{loopStep['output'].index}}。

3.2 循环结束后的输出：`{ item, index, iterations }`

循环跑完后，其输出是一个包含三个字段的对象，语义需要特别注意：

item：只保存最后一次迭代的项——它不是所有项的数组！不要在循环后指望{{loopStep['output'].item}}给出完整列表；
index：最后一次迭代的索引；
iterations：一个数组，每个元素对应一次迭代，内容是该次迭代中各步骤的输出记录。

因此，要在循环结束后拿到全部结果，正确做法是读{{loopStep['output'].iterations}}；或者采用常见的"累加器"模式：循环体内用store/add_to_list把每次结果写入 Store/Table，循环结束后用store/get读取（见 state.md 指南）。

3.3 循环的约束与陷阱

串行执行，非并行：N 个元素 × 单次迭代耗时，会计入 600 秒的运行时间预算。面对超大列表，建议拆分为多个子流程（sub-flow）分摊，参见 error_handling.md；
ap_test_step不会执行循环体：单步测试无法验证循环内部逻辑，请改用ap_test_flow跑完整流程来验证循环；
没有内置限流：高速循环直接打速率受限的 API，会迅速收获 429 状态码，需要自己在循环体内设计节流/退避逻辑。

四、架构建议：深嵌套 → 拍平（flatten）

嵌套超过约2 层的 Router 是明显的坏味道，可维护性急剧下降。推荐的替代方案是"一次决策、单路由分发"：

用内联公式表达式一次性计算出决策结果，返回单个标签字符串，例如：

ap-formula-v1::{switch({{step_1['output'].country}};"US";"NA";"DE";"EU")}::ap-formula-v1

该表达式把国家代码映射为NA/EU等区域标签；

只有当逻辑复杂到公式无法表达时，才考虑用CODE步骤承担决策；
最后用一个基于该标签做条件匹配的 Router 完成分发，替代原本层层嵌套的 Router 树。

这样既保持了条件逻辑的集中与清晰，也让后续的调试、测试和审计（ap_flow_structure/ap_validate_flow）都更容易进行。

五、验证与调试闭环

控制流结构的正确性最终要靠验证与测试闭环来保证：

ap_validate_flow：在保存/发布前校验整条流程，尤其是 Router 的空分支、无效条件组合等问题——文档明确建议"任何非平凡的条件组合都要用ap_validate_flow验证"；
ap_flow_structure：随时查看步骤树、分支索引与各步骤的valid/configStatus（未配置、无效、已跳过等状态一目了然，ap-flow-structure.ts）；
ap_test_flow：完整运行流程，这是验证 Loop 循环体的唯一途径。

小结

Router 与 Loop 是 Activepieces 流程中最重要的两类控制流结构。用细分构建路径搭建它们时，请牢记三件事：stepLocationRelativeToParent决定挂载位置，branchIndex从 0 开始且兜底分支不可删不可设条件，循环的item只保留最后一项、完整结果要去iterations里取。配合ap_flow_structure查看结构、ap_validate_flow验证合法性、ap_test_flow端到端测试，即可稳定地通过 MCP 工具构建出健壮的自动化流程。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Activepieces 流程控制深度指南：用 MCP 工具构建 Router 分支与 Loop 循环