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/authCODE 步骤可传sourceCode/packageJson循环步骤传loopItems迭代数组的表达式如{{step_1[output].items}}。步骤尚未配置时valid: false配置完成并校验通过后才为true。二、Router分支路由自上而下匹配首个命中即执行Router 会自上而下依次评估各条件分支执行第一个匹配的分支所有分支都不匹配时落入末位的Otherwise兜底分支。从 ap-add-step.ts 可以看到新建 ROUTER 时默认的骨架设置是executionType: EXECUTE_FIRST_MATCH即执行首个匹配。2.1 三个常见陷阱GotchaGotcha 1 —— 新 Router 天生带着两个分支。调用ap_add_stepstepType 为ROUTER时系统会自动创建两个分支Branch 1条件分支但条件为空conditions: [[]]此时整个 Router 处于空分支的非法状态无法通过校验Otherwise兜底回退分支branchType: FALLBACK。因此构建 Router 的标准动作序列是ap_add_stepstepTypeROUTER→ 得到Branch 1空Otherwise二选一用ap_update_branch填充Branch 1的条件或用ap_delete_branchbranchIndex: 0删掉它再用ap_add_branch添加真实条件分支继续用ap_add_branch添加更多条件分支用ap_add_stepstepLocationRelativeToParent: INSIDE_BRANCHbranchIndex: 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查看——它的输出为每个步骤标注了relationshipbranch、first_loop_action、on_success_branch、on_failure_branch等与branchIndex/branchNameap-flow-structure.ts是定位父步骤名和分支索引的首选工具。三、Loop循环LOOP_ON_ITEMS用ap_add_stepstepTypeLOOP_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.mdap_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.tsap_test_flow完整运行流程这是验证 Loop 循环体的唯一途径。小结Router 与 Loop 是 Activepieces 流程中最重要的两类控制流结构。用细分构建路径搭建它们时请牢记三件事stepLocationRelativeToParent决定挂载位置branchIndex从 0 开始且兜底分支不可删不可设条件循环的item只保留最后一项、完整结果要去iterations里取。配合ap_flow_structure查看结构、ap_validate_flow验证合法性、ap_test_flow端到端测试即可稳定地通过 MCP 工具构建出健壮的自动化流程。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考