执行任务 `flow.step`

任务节点把一次外部工作交给宿主注册的处理器，例如模型调用、MCP 工具、HTTP 请求、数据库写入或业务服务。Flow 保存调度请求、尝试次数和最终结果，宿主负责凭据、权限、网络访问与真实副作用。step_name 必须与宿主注册表中的稳定名称一致，发布流程应在启动运行前验证该处理器可用。

输入与重试

input 表达式从启动输入或上游结果构造任务参数。提交到历史的输入会在重试时保持一致，因此不要把当前时间、随机数或进程内可变状态直接放进表达式。需要这些值时，由宿主任务生成并把结果提交回来。大型文件、模型输出和二进制内容宜传递对象引用，避免让事件历史承担不必要的体积。

max_attempts 包含首次执行，retry_delay_ms 表示下一次尝试前的等待时间。on_exhausted 选择 fail_run 时，尝试耗尽会结束运行。选择 continue_workflow 时，节点开放 failed 控制端口和 error 数据端口，后续图可以补偿、降级或转人工处理。外部系统幂等键应由运行 ID、节点 ID 和尝试身份构成。

端口与运行检查

成功结果提交后，success 与 result 才可供下游使用。任务在外部操作完成后、结果写入历史前遇到进程退出时可能再次交付，所以测试需要覆盖重复调用。只有启用继续失败分支时才连接 failed 与 error。上线前还要检查超时策略、错误脱敏、处理器版本路由、补偿路径和重试上限，避免永久错误在队列中反复消耗资源。

用它调用一个已经在宿主注册的任务，例如工具、HTTP 请求、数据库写入或业务服务。每次任务有独立输入、结果和重试策略。

运行方式

节点 ID 绑定持久步骤身份。结果提交历史后才会进入成功端口，重试耗尽时根据策略结束运行或开放失败端口。

节点契约

类型: flow.step
角色: 持久运行命令
运行绑定: schedule_step
持久身份: 图节点 ID

配置属性

属性	类型与控件	默认值	规则
`step_name`任务名称	`str`StrInput	`task.run`	填写执行端已经注册的任务标识，例如 task.run。必填
`input`任务输入	`dict`A3SFlowExpressionInput	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"field","path":"input"}}`	选择要传给任务的数据。可选
`max_attempts`最多尝试次数	`int`IntInput	`3`	包含第一次执行。填 1 表示失败后不重试。必填 · 高级设置 · 范围 1 to 100 / 1
`retry_delay_ms`重试间隔（毫秒）	`int`IntInput	`0`	两次尝试之间等待多久。填 0 表示立即重试。必填 · 高级设置 · 范围 0 to 86400000 / 100
`on_exhausted`尝试次数用完后	`str`DropdownInput	`fail_run`	可以结束整个工作流，也可以进入失败分支继续处理。必填 · 高级设置 · 可选值 fail_run, continue_workflow

端口

方向	端口 ID	种类	数据类型
输入	`in`进入	control	`FlowControl`
输入	`input`任务输入	data	`JsonValue`
输出	`success`成功	control	`FlowControl`
输出	`result`任务结果	data	`JsonValue`
输出	`failed`失败	control	`FlowControl`
输出	`error`错误信息	data	`String`

节点 JSON 示例

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

workflow.json

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

CLI 用法

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

Terminal

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

CLI 用法 · Skill 用法

使用注意

宿主任务必须能处理至少一次交付。
外部幂等键应由运行 ID、节点 ID 和尝试次数构造。
只有选择继续失败分支时才连接 failed 端口。

#执行任务 flow.step

#输入与重试

#端口与运行检查