失败结束 `flow.fail`

失败节点在工作流已经确认无法继续时提交失败终态。error_expression 生成最终错误文本，可以引用输入和已保存结果。它适合业务规则拒绝、补偿失败或明确不可恢复的状态。暂时性网络错误和可以重试的任务错误应留在任务节点处理，不要过早把运行关闭。

错误内容

错误信息要给操作者足够的业务上下文，例如失败阶段、外部引用和可执行的下一步。令牌、凭据、完整请求头、敏感输入与未脱敏的外部响应不能写入错误文本。需要保留诊断细节时，可在受控遥测系统中记录关联 ID，并让终态只保存安全摘要。

error 数据端口可以从上游传入字符串，表达式也可以从字段组合文本。最终内容必须稳定可重放，不能加入新的当前时间、随机 ID 或实时远程状态。失败节点没有出站端口。需要走人工修复或降级分支时，应在进入本节点前完成判断和补偿，确认运行确实不能继续后再提交终态。

运行与告警

测试应覆盖缺失错误字段、敏感内容脱敏、重复终态提交、取消期间清理失败以及任务重试耗尽产生的失败。监控可以分别统计显式失败节点与任务直接失败，前者通常表达业务判断，后者更接近执行问题。告警规则应使用稳定错误码或关联字段，避免依赖经常变化的整段自然语言。

用它在工作流已经确认无法继续时提交失败终态。错误表达式应给操作者足够的业务上下文。

运行方式

失败事件会关闭当前运行段，并保留表达式得到的错误文本。它与步骤重试耗尽产生的失败结果可以分别统计。

节点契约

类型: flow.fail
角色: 持久运行命令
运行绑定: fail
持久身份: 由图结构决定

配置属性

属性	类型与控件	默认值	规则
`error_expression`错误信息	`dict`A3SFlowExpressionInput	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"concat","values":[{"op":"literal","value":"Workflow failed: "},{"op":"field","path":"input.reason"}]}}`	可以填写固定文本，也可以插入工作流字段说明失败原因。必填

端口

方向	端口 ID	种类	数据类型
输入	`in`进入	control	`FlowControl`
输入	`error`错误信息	data	`String`

节点 JSON 示例

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

workflow.json

{
  "position": {
    "x": 320,
    "y": 160
  },
  "id": "example-flow-fail",
  "data": {
    "error_expression": {
      "apiVersion": "a3s.dev/flow-expression/v1",
      "expression": {
        "op": "concat",
        "values": [
          {
            "op": "literal",
            "value": "Workflow failed: "
          },
          {
            "op": "field",
            "path": "input.reason"
          }
        ]
      }
    },
    "type": "flow.fail"
  }
}

CLI 用法

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

Terminal

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

CLI 用法 · Skill 用法

使用注意

错误文本不要包含 token 或完整外部响应。
清理失败可以在取消过程中使用此终态。
可恢复错误应先走步骤失败分支。

#失败结束 flow.fail

#错误内容

#运行与告警