遍历集合 `iteration`

遍历容器为集合中的每个成员建立相同的子画布作用域。items 表达式在进入容器前得到确定集合，宿主再把子图编译成稳定步骤或子工作流。它适合成员处理逻辑相同、每项都需要清楚输入与结果边界的场景。成员规模很大时应先分窗，避免一次运行保存过多任务。

子画布结构

每个容器只能有一个内部 iteration-start，其 ID 必须等于 start_node_id。内部入口与其他子节点都把 parentId 设为容器节点 ID。入口的 item 数据端口提供当前成员，next 控制端口连接第一项工作。容器内至少还要有一个可执行节点，所有边的两端都留在同一作用域。

普通 DAG 不能画回边。遍历行为由容器表达，外层控制从 in 进入，所有成员完成后从 done 继续。宿主负责成员变量、并发、结果聚合和失败策略，因此发布前应明确是串行、限流并行还是以子工作流执行，并确保顺序与摘要在相同输入下保持稳定。

成员身份与验证

集合成员需要可重复得到的业务身份，不能依赖随机排序或实时查询顺序。测试应覆盖空集合、单成员、重复业务键、部分失败、进程恢复、并发限制和结果顺序。校验提示跨作用域边时，检查每个子节点的 parentId 与边端点。需要按条件重复同一状态时使用循环容器，不要把不断变化的集合塞进一次遍历。

用它为集合中的每个成员建立一个子画布作用域。items 表达式提供集合，容器内部从唯一的 iteration-start 开始。

运行方式

容器只描述图结构，不直接生成运行命令。宿主把子画布编译成稳定步骤或子工作流，并负责成员变量、并发和结果聚合。

节点契约

类型: iteration
角色: 子画布容器
运行绑定: 宿主编译
持久身份: 由图结构决定

配置属性

属性	类型与控件	默认值	规则
`items`待遍历集合	`dict`A3SFlowExpressionInput	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"field","path":"input.items"}}`	选择一个数组。容器内节点会依次收到其中的每一项。必填
`start_node_id`起始节点 ID	`str`StrInput	`iteration-start`	由编辑器管理，用于定位容器内的第一个节点。通常无需修改。必填 · 高级设置

子画布结构

属性	类型与控件	规则
`iteration-start`	`internal node`	唯一的容器入口，parentId 指向 iteration必填
`parentId`	`node id`	每个容器内节点都使用同一个父节点 ID必填

端口

方向	端口 ID	种类	数据类型
输入	`in`进入	control	`FlowControl`
输出	`done`全部完成	control	`FlowControl`

节点 JSON 示例

CLI 会用 manifest 默认值生成同样的节点结构。画布位置、标题和选中状态属于展示数据。

workflow.json

{
  "position": {
    "x": 320,
    "y": 160
  },
  "id": "example-iteration",
  "data": {
    "items": {
      "apiVersion": "a3s.dev/flow-expression/v1",
      "expression": {
        "op": "field",
        "path": "input.items"
      }
    },
    "start_node_id": "iteration-start",
    "type": "iteration"
  }
}

CLI 用法

先查看当前安装版本的 manifest，再创建节点并验证完整工作流。所有命令输出 JSON。

Terminal

a3s-flow node iteration --pretty
a3s-flow new iteration --id example-iteration --pretty
a3s-flow validate workflow.json --pretty
a3s-flow compile workflow.json --pretty
a3s-flow digest workflow.json --pretty

Skill 用法

安装包内附带 a3s-flow Skill。它会先查询 CLI 的节点清单，再创建、校验、编译并计算语义摘要。

Prompt

Use $a3s-flow to add the "iteration" node to workflow.json, connect valid ports, and validate the result.

CLI 用法 · Skill 用法

使用注意

start_node_id 必须指向容器内的 iteration-start。
容器至少还要有一个可执行子节点。
连线不能跨越容器作用域。

#遍历集合 iteration

#子画布结构

#成员身份与验证

运行方式

节点契约

配置属性

子画布结构

端口

节点 JSON 示例

CLI 用法

Skill 用法

使用注意

遍历集合 `iteration`

子画布结构

成员身份与验证