Loop（循环）
标记循环区域的顶部。它与配对 Loop End 之间的一切都会重复。
用途
重复一块节点——固定次数、条件保持为真时、或直到条件变真。用来把任务刷 N 次、反复尝试直到某物出现，或处理列表。
你画一条普通的主体节点链。进入、重复与退出的接线为你生成——没有回边要画，画布上没有循环端口。
何时用
- 把任务重复已知次数。
- 资源还在时继续（
While）。 - 重试直到达到某状态（
Until）。 - 带计数变量迭代。
何时不用
- 简单的"做到配额满"，Variable 计数器加 If 更清楚、也更经得起分支。
- 重试一个不稳的节点——用该节点的重试策略。
- 轮询等某物出现——超时更长的 Find Image 本来就在轮询。
前提
- 一个配对的 Loop End。区域在保存时校验。
- 一个 Max iterations 值。
- While/Until 需要布尔条件。
- 计数变量（若用）须预先声明为数字。
如何运行
每种模式都在 Max iterations 停。 永不翻转的 While 条件照样终止。
设置
| 设置 | 类型 | 范围 | 备注 |
|---|---|---|---|
| Mode | 选择 | count、while、until | 必填 |
| Max iterations | integer | 1–1000 | 必填。 每种模式的安全上限。接受 {{变量}} |
| Condition | 表达式 | ≤ 1000 字符 | While/Until 必填；须为布尔 |
| Counter variable | 变量路径 | — | 可选；接收轮序号，从 0 起 |
While 与 Until
- While 在条件为真时重复——条件变假即停。
- Until 重复直到条件为真——条件变真即停。
它们相反。选错的循环要么跑一轮要么跑到上限。
Max iterations 接受变量
maxIterations 接受整串 {{变量}} 引用，所以重复次数可作为 Flow Input 按次提供：
Max iterations: {{items_per_trip}}
这就是一个已保存流程无需编辑就能处理"3 个"和"10 个"的方式。
Loop End 能聚合
配对的 Loop End 可选地把某主体节点的输出跨轮收集，并暴露在循环出口。模式有 last、first、collectAll、unique、successOnly、failureOnly、successCount、failureCount 和 iterationCount。
iterationCount 最简单也最常用——"实际跑了几轮"。
端口
Loop 是区域标记，不是分支节点。你从它接一条普通 success 链进主体；重复与退出路由在编译期生成。
| 端口 | 备注 |
|---|---|
| Success | 接到第一个主体节点。必接 |
| Fatal | 无效的模式、上限或非布尔条件。永不被走 |
基础示例
把收集步骤重复十次：
- Mode：Count
- Max iterations：
10
实际示例——有界、变量长度的循环
两个终止条件，都安全：循环在调用方给的次数停，或没东西可处理时经 Break 提前停。
高级示例——带旗标的有界重试
Loop 作为重试区域，用旗标变量记录成功：
需要重试一组节点时用这个形状——节点级重试只覆盖单个节点。
最佳实践
- 把 Max iterations 设为真实界限，不是最大值。它是防无限循环的保险。
- 在主体内更新 While/Until 条件所测的东西，否则总撞上限。
- "没事可做"用 Break，别让循环空转。
- 先声明计数变量，为数字。
- 把 Max iterations 绑到 Flow Input 让流程可复用。
- 盯住
maxNodeExecutions。 12 节点上 200 轮是 2400 次执行——相 应调高流程护栏。
性能笔记
- Loop 本身零成本；主体成本乘以轮数才是要紧的。
- 循环里的 Wait 是最常见的性能错误：1500 ms × 200 轮就是五分钟空等。
- 循环里的检测节点主导成本。给它们紧的搜索区域。
- 收集数据的聚合模式（
collectAll、unique）保留每轮的值；只要数字时用计数。
内存笔记
- 每轮把节点结果记进运行上下文，长循环让
nodeResults稳步增长。 collectAll聚合每轮保留一条——受 Max iterations 限制，但 1000 轮循环是真实内存。- 超长工作优先重复的计划运行，而非一个巨型循环。
常见错误
| 错误 | 后果 | 修复 |
|---|---|---|
| While 条件从不更新 | 每次跑到上限 | 在主体里更新所测变量 |
| While 与 Until 弄混 | 跑一轮，或跑到上限 | While = 为真时；Until = 直到为真 |
| 计数器未声明 | 循环出错 | 先声明为数字 |
| 缺 Loop End | 保存时校验错误 | 每个 Loop 要它 的配对 |
| 上限"保险起见"设 1000 | 掩盖真 bug、烧执行数 | 设现实界限 |
循环体超 maxNodeExecutions | 运行中途死 | 调高流程护栏 |
故障排查
循环恰好跑一轮。 Until 条件已然为真，或 While 条件已然为假。
循环总跑到 Max iterations。 条件从不变化——主体里没有东西更新它测的变量。
运行死于 MAX_NODE_EXECUTIONS_EXCEEDED。
轮数 × 主体大小超了流程上限。在流程设置里调高。
Break 不离开循环。 Break 属于最内层包围循环。查它在哪个区域。
FAQ
最大轮数？ 1000。
次数能取自变量吗？
能——maxIterations 接受整串 {{变量}}。
要画回边吗？ 不。从 Loop 到 Loop End 接普通链；路由自动生成。
能嵌套循环吗？ 能。Break 和 Continue 作用于最内层包围循环。