Loop Block

容器节点，支持按次数、列表遍历或条件判断重复执行内部 Block。

功能说明

Loop Block 是一个容器节点，可以包含其他 Block 并重复执行它们。它支持三种循环模式：

• count（计数循环）：固定执行 N 次。
• list（列表循环）：遍历数组中的每个元素，每轮将当前元素注入 item 变量。
• condition（条件循环）：持续执行直到条件为 true（类似 do...until）。

Loop Block 本身不产生输出，内部 Block 的执行结果直接写入全局上下文。循环体内的变量（index、count、item）仅在循环内部可用，退出循环后失效。

使用场景

1. 批量处理：对数组中的每个元素依次执行相同的 AI 生成或数据处理操作。
2. 重复生成：指定次数重复调用 AI 生成，收集多个结果。
3. 轮询等待：通过条件循环反复检查某个条件，直到满足后退出。

配置参数

属性名	类型	说明	默认值
id	string	节点唯一标识（自动生成）	—
name	string	节点名称（自动生成，可自定义）	—
loopType	'count' | 'list' | 'condition'	循环类型	'count'
count	number	计数循环的次数（仅 loopType: 'count'）	10
list	ValueSource	列表循环的数据源（仅 loopType: 'list'）	{ sourceType: 'array', sourceValue: [] }
condition	Condition	条件循环的退出条件（仅 loopType: 'condition'）	空条件
maxIterations	number | null	条件循环最大迭代次数（0=取消上限，1-100=显式限制）	null（默认 10）
maxItems	number | null	列表循环最大处理项数（0=不限制，1-100=显式限制）	null（不限制）

Condition 结构

条件由三部分组成：

字段	类型	说明
first	ValueSource	左值（支持变量引用或字面量）
compare	Compare	比较操作符
second	ValueSource	右值（支持变量引用或字面量）

可用比较操作符：

操作符	说明
Equals	等于
NotEquals	不等于
Contains	包含（文本）
NotContains	不包含（文本）
GreaterThan	大于
GreaterThanOrEqual	大于等于
LessThan	小于
LessThanOrEqual	小于等于

输出变量

Loop Block 的变量仅在循环内部可用（checkShow: 'inside'）：

变量名	类型	说明
count	number	当前迭代计数（从 1 开始）
item	any	当前遍历的元素（仅 list 模式）
index	number	当前迭代索引（从 0 开始）

这些变量在循环退出后自动失效，外部 Block 无法引用。

引用语法示例（仅限循环内部）：

当前是第 {{loop_1.count}} 次循环
当前元素：{{loop_1.item}}
当前索引：{{loop_1.index}}

使用示例

示例 1：计数循环 - 批量生成

[Loop Block] name: loop_1, loopType: count, count: 5

  第 {{loop_1.count}} 轮生成：

  [Generation Block] name: gen_1
    请生成一个随机的创意点子，编号 {{loop_1.count}}

循环 5 次，每次调用 AI 生成一个创意点子。

示例 2：列表循环 - 遍历处理

[Structure Block] name: struct_1
  Schema: items (array of string)

[Loop Block] name: loop_1, loopType: list, list: {{struct_1.items}}

  正在处理：{{loop_1.item}}

  [Generation Block] name: gen_1
    请对以下内容进行详细分析：{{loop_1.item}}

遍历 struct_1 输出的数组，对每个元素调用 AI 分析。

运行时约束

• 适用文档类型：普通文档（document）。不可用于 skill 文档。
• 可插入上下文：文档顶层。Loop Block 可以嵌套使用。
• 内部内容：必须包含至少一个子 Block（content: 'block+'）。
• 安全上限：条件循环存在系统级安全上限（120 次），防止死循环。

注意事项

• Loop Block 本身不产生输出变量。内部 Block 的输出直接写入全局上下文。
• index 从 0 开始，count 从 1 开始。
• list 模式下，如果数据源不是数组，循环不会执行。
• condition 模式的语义是"运行直到条件为 true"（do...until）。条件满足时退出循环。
• maxIterations 和 maxItems 的有效范围为 1-100。超过 100 会被截断为 100。设为 0 表示取消用户配置的上限（条件循环退化到系统安全上限 120）。
• 循环体内的变量（index、count、item）通过作用域机制管理，每轮迭代会更新值，退出循环后自动清除。
• 在 skill 文档中不可使用 Loop Block。
• 迭代间变量行为：循环体内 Block 的输出会写入全局上下文，后续迭代可引用前序迭代的变量。若多次迭代中存在相同 Block ID，后序迭代的输出会覆盖前序的值。
• 首次迭代注意：第一次迭代时，循环体内部的变量可能尚无值（取决于执行顺序），设计工作流时需注意处理空值情况。