超时结束 `flow.timeout`

超时节点提交独立的超时终态，并保存触发该结论的 UTC 截止时间。它适合 SLA、审批窗口、支付期限和其他到期后不能继续的业务边界。节点本身不会等待时钟，也不会定期检查当前时间。通常先由等待节点持久化同一个截止时间，唤醒后再进入本节点。

截止时间与原因

deadline 是必填日期时间表达式，结果应带时区并且来自稳定输入或已保存结果。reason 是可选的简短业务说明，用来区分哪一个窗口到期。截止时间参与运行结论，不能在重放时重新读取当前时钟生成。需要相对时长时，先在开始或任务结果中固定基准时间，再计算并保存绝对时间。

节点接收 in，并可以从 deadline 数据端口取得时间，提交后没有出站控制。多个截止窗口存在时，可以使用不同等待和超时节点，让每个节点 ID 对应清楚的业务边界。若到期后仍允许补偿、通知或人工复核，应在提交超时终态前完成这些步骤，或把后续工作交给独立子工作流。

调度与观测

测试要覆盖时区偏移、已经到期、调度延迟、重复唤醒、进程恢复和取消竞争。监控应分别记录业务截止时间、实际唤醒时间与终态提交时间，方便判断延迟来自业务配置、调度器还是 worker 容量。错误信息和 reason 不要包含凭据或完整外部响应，详细诊断使用受控关联 ID。

用它记录一个已经超过的业务截止时间。deadline 保存原始 UTC 时间，reason 用来说明哪个等待窗口到期。

运行方式

超时会关闭运行段，并保留独立的超时终态。通常先用等待节点持久化同一个截止时间，到期后再进入本节点。

节点契约

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

配置属性

属性	类型与控件	默认值	规则
`deadline`截止时间（UTC）	`dict`A3SFlowExpressionInput	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"field","path":"input.deadline"}}`	填写触发本次超时的 UTC 时间。必填
`reason`超时原因	`str`StrInput	`""`	说明哪个环节未在期限内完成，便于后续排查。可选 · 高级设置

端口

方向	端口 ID	种类	数据类型
输入	`in`进入	control	`FlowControl`
输出	`deadline`截止时间	data	`DateTime`

节点 JSON 示例

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

workflow.json

{
  "position": {
    "x": 320,
    "y": 160
  },
  "id": "example-flow-timeout",
  "data": {
    "deadline": {
      "apiVersion": "a3s.dev/flow-expression/v1",
      "expression": {
        "op": "field",
        "path": "input.deadline"
      }
    },
    "reason": "",
    "type": "flow.timeout"
  }
}

CLI 用法

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

Terminal

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

CLI 用法 · Skill 用法

使用注意

不要在重放中临时读取当前时间决定超时。
deadline 必须是确定的绝对时间。
reason 只写简短业务说明。

#超时结束 flow.timeout

#截止时间与原因

#调度与观测