批量执行任务 `flow.batch`

批量任务节点一次声明多项可以独立推进的宿主任务，并按声明顺序汇总结果。它适合数量已知、成员边界清楚的小批处理，例如同时检查若干资料或调用一组固定工具。成员集合非常大或需要分页恢复时，应按稳定游标拆成多批，或使用遍历容器建立更清楚的成员作用域。

成员配置

steps 中每个成员都有 step_key、step_name、input_mapping、max_attempts、retry_delay_ms 和 on_exhausted。step_key 在节点内必须唯一，并与图节点 ID 共同形成持久步骤身份。成员完成顺序可能不同，但不能根据完成先后重新编号、排序或复用 key。编辑已有运行对应的成员列表时，要保留原成员身份和语义位置。

每个 input_mapping 独立构造参数，重试字段也按成员生效。只要有成员选择 continue_workflow，节点就会提供 recoverable_failure 与 errors，后续可以检查哪些成员失败。默认的 fail_run 会在相应成员耗尽尝试后结束运行。宿主任务仍需处理至少一次交付，并为每个成员生成包含运行、节点、成员和尝试身份的幂等键。

结果与容量

全部成员解析后，控制从 done 继续，results 按声明顺序提供结果。失败分支同样保持成员顺序，不能依靠数组位置推断完成时间。发布前应验证空列表、重复 key、部分失败、全部失败、进程恢复和大结果体积。每项输出较大时只保存对象引用。批量规模应服从宿主并发与队列容量，避免一个节点瞬间提交超过下游可以承受的任务数。

用它声明一组可以独立推进的宿主任务。成员按固定顺序保存，各自拥有名称、输入和重试策略。

运行方式

节点 ID 与成员 key 共同构成步骤身份。引擎先保存整批成员，再推进尚未完成的任务，结果数组按声明顺序汇总。

节点契约

类型: flow.batch
角色: 持久运行命令
运行绑定: schedule_steps
持久身份: 图节点 ID 与成员 key

配置属性

属性	类型与控件	默认值	规则
`steps`任务列表	`table`A3SFlowBatchInput	`[{"step_key":"member-1","step_name":"task.run","input_mapping":{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"field","path":"input"}},"max_attempts":3,"retry_delay_ms":0,"on_exhausted":"fail_run"}]`	任务会按当前顺序执行。每项任务都需要一个在批次内唯一的固定 ID。必填

任务列表

属性	类型与控件	默认值	规则
`step_key`任务 ID	`string`	`未设置`	在当前批次内保持唯一。已有运行后请勿修改。必填
`step_name`任务名称	`string`	`未设置`	填写执行端已经注册的任务标识。必填
`input_mapping`任务输入	`object`	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"field","path":"input"}}`	选择要传给这项任务的数据。必填
`max_attempts`最多尝试次数	`int`	`3`	包含首次执行。必填
`retry_delay_ms`重试间隔（毫秒）	`int`	`0`	两次尝试之间等待的时间。必填
`on_exhausted`尝试次数用完后	`string`	`fail_run`	结束工作流或进入失败分支。必填

steps 成员属性

属性	类型与控件	规则
`step_key`	`string`	批次内稳定且唯一的成员身份必填
`step_name`	`string`	宿主已经注册的任务名称必填
`input_mapping`	`FlowExpression`	为这项任务生成输入必填
`max_attempts`	`integer`	包含首次执行的总尝试次数必填
`retry_delay_ms`	`integer`	下一次尝试前等待的毫秒数必填
`on_exhausted`	`fail_run \| continue_workflow`	重试耗尽后的运行方式必填

端口

方向	端口 ID	种类	数据类型
输入	`in`进入	control	`FlowControl`
输入	`input`批量输入	data	`JsonValue`
输出	`done`全部完成	control	`FlowControl`
输出	`results`任务结果	data	`JsonValue[]`
输出	`recoverable_failure`失败	control	`FlowControl`
输出	`errors`错误信息	data	`String[]`

节点 JSON 示例

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

workflow.json

{
  "position": {
    "x": 320,
    "y": 160
  },
  "id": "example-flow-batch",
  "data": {
    "steps": [
      {
        "step_key": "member-1",
        "step_name": "task.run",
        "input_mapping": {
          "apiVersion": "a3s.dev/flow-expression/v1",
          "expression": {
            "op": "field",
            "path": "input"
          }
        },
        "max_attempts": 3,
        "retry_delay_ms": 0,
        "on_exhausted": "fail_run"
      }
    ],
    "type": "flow.batch"
  }
}

CLI 用法

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

Terminal

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

CLI 用法 · Skill 用法

使用注意

成员 key 必须非空且不能重复。
不要按完成先后为成员重新编号。
大批量任务应按输入中的稳定游标分窗。

#批量执行任务 flow.batch

#成员配置

#结果与容量