条件循环 `loop`

循环容器在每一轮进入子画布前检查确定性条件，并用次数上限约束无法退出的流程。它适合分页拉取、状态轮询和有明确终止条件的重复处理。外部状态不能直接在条件表达式中读取，需要先由子画布任务把最新结果写入历史，再由下一轮条件读取。

条件与上限

condition 返回真时进入下一轮，返回假时从 done 继续。max_iterations 是宿主安全上限，范围为 1 到 10000。达到上限时的业务处理应在设计中明确，可以在子图记录进度或由外层进入失败、超时和人工处理路径。上限不能代替真实退出条件，也不能设置成没有容量评估的任意大值。

start_node_id 必须指向唯一的内部 loop-start。所有子节点使用容器 ID 作为 parentId，内部入口的 next 连接第一项工作。边不能跨出容器，也不能从子图画回外层节点。循环语义来自容器，普通 DAG 始终保持无环。

恢复与容量检查

每轮决定和任务结果都要可从历史恢复。需要携带轮次、游标或累计状态时，使用明确的持久数据，不依赖进程内变量。测试应覆盖条件初始为假、第一轮退出、达到上限、任务失败、进程重启和长历史。轮次数可能很大时可以在稳定边界使用续段节点缩短单段历史，并保留下一段所需游标。

用它建立带条件和次数上限的循环子画布。每次进入子作用域前都会检查 condition，并由 max_iterations 提供硬上限。

运行方式

容器本身不生成运行命令。宿主负责把每轮子图编译成持久决定，并在条件为假或达到次数上限时从 done 端口继续。

节点契约

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

配置属性

属性	类型与控件	默认值	规则
`condition`继续条件	`dict`A3SFlowExpressionInput	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"lt","left":{"op":"field","path":"loop.index"},"right":{"op":"literal","value":10}}}`	每轮结束后检查。条件成立时进入下一轮。必填
`max_iterations`最大循环次数	`int`IntInput	`100`	限制循环最多执行多少次，避免配置错误造成无限循环。必填 · 高级设置 · 范围 1 to 10000 / 1
`start_node_id`起始节点 ID	`str`StrInput	`loop-start`	由编辑器管理，用于定位容器内的第一个节点。通常无需修改。必填 · 高级设置

子画布结构

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

端口

方向	端口 ID	种类	数据类型
输入	`in`进入	control	`FlowControl`
输出	`done`循环结束	control	`FlowControl`

节点 JSON 示例

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

workflow.json

{
  "position": {
    "x": 320,
    "y": 160
  },
  "id": "example-loop",
  "data": {
    "condition": {
      "apiVersion": "a3s.dev/flow-expression/v1",
      "expression": {
        "op": "lt",
        "left": {
          "op": "field",
          "path": "loop.index"
        },
        "right": {
          "op": "literal",
          "value": 10
        }
      }
    },
    "max_iterations": 100,
    "start_node_id": "loop-start",
    "type": "loop"
  }
}

CLI 用法

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

Terminal

a3s-flow node loop --pretty
a3s-flow new loop --id example-loop --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 "loop" node to workflow.json, connect valid ports, and validate the result.

CLI 用法 · Skill 用法

使用注意

start_node_id 必须指向容器内的 loop-start。
使用 max_iterations 防止无法退出的流程。
循环由容器表达，不要画回边。

#条件循环 loop

#条件与上限

#恢复与容量检查