等待回调 `flow.hook`

Hook 节点建立一个只能解析一次的外部等待边界，可用于人工审批、网页操作或 webhook 回调。节点先把 Hook 身份和接收规则写入历史，再释放 worker。有效输入到达后，运行重新投递，并从接收分支读取保存的载荷。取消或主动关闭会走废弃分支。

模式与公开边界

kind 决定人工审批或 webhook 模式。人工审批可通过 subject 和元数据说明待处理事项。webhook 模式还显示 callback_method 与 callback_path。token_expression 产生公开接收凭据时，应基于稳定数据并由宿主安全传递。令牌属于凭据，不能写入普通日志、错误消息、分析事件或截图。

一次有效接收会开放 received 控制端口和 payload 数据端口。Hook 被关闭、运行取消或接收窗口结束时，控制从 disposed 继续。图中应明确处理这两个出口。审批拒绝通常属于有效载荷中的业务结果，可以在 received 后接条件节点判断。废弃分支用于没有结果的关闭状态，不宜混成审批拒绝。

接收与安全检查

宿主接收端需要验证令牌、方法、内容类型、载荷大小和调用者权限，并保证同一个 Hook 只能从等待态转换一次。重复请求应返回已解析状态或原结果，不能再次追加不同载荷。测试还要覆盖过期令牌、错误方法、并发接收、取消与接收竞争、日志脱敏和进程恢复。需要同名消息排队并多次消费时，应改用信号节点。

用它等待一次人工审批或外部回调。人工模式保留主题和元数据，webhook 模式还会显示请求方法与回调路径。

运行方式

节点创建带稳定身份的 Hook 并暂停运行。一次有效接收会开放 received 和 payload，关闭或取消则进入 disposed。

节点契约

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

配置属性

属性	类型与控件	默认值	规则
`kind`等待方式	`tab`TabInput	`human_approval`	选择由人工审批、Webhook 或应用事件恢复当前运行。必填 · 可选值 human_approval, webhook, host_event
`subject`标题	`str`StrInput	`Review workflow request`	写清需要处理的事项。该标题会显示在审批队列和审计记录中。必填
`token_expression`回调标识	`dict`A3SFlowExpressionInput	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"field","path":"input.callbackToken"}}`	请选择每次运行都不同的字段，用来把回调匹配到正确的等待节点。必填
`callback_method`请求方法	`str`DropdownInput	`POST`	选择接收 Webhook 时使用的 HTTP 方法。可选 · 高级设置 · 可选值 POST, PUT, PATCH · 显示条件 kind = webhook
`callback_path`回调路径	`str`StrInput	`/callbacks/workflow`	填写接入应用提供的路由。这里不会自动创建或托管接口。可选 · 高级设置 · 显示条件 kind = webhook
`metadata`附加数据	`dict`JSONInput	`{"labels":{},"data":{}}`	随回调请求一同保存的标签或业务数据。可选 · 高级设置

端口

方向	端口 ID	种类	数据类型
输入	`in`进入	control	`FlowControl`
输入	`token`回调标识	data	`String`
输入	`metadata`附加数据	data	`JsonValue`
输出	`received`收到回调	control	`FlowControl`
输出	`payload`回调内容	data	`JsonValue`
输出	`disposed`已关闭	control	`FlowControl`

节点 JSON 示例

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

workflow.json

{
  "position": {
    "x": 320,
    "y": 160
  },
  "id": "example-flow-hook",
  "data": {
    "kind": "human_approval",
    "subject": "Review workflow request",
    "token_expression": {
      "apiVersion": "a3s.dev/flow-expression/v1",
      "expression": {
        "op": "field",
        "path": "input.callbackToken"
      }
    },
    "callback_method": "POST",
    "callback_path": "/callbacks/workflow",
    "metadata": {
      "labels": {},
      "data": {}
    },
    "type": "flow.hook"
  }
}

CLI 用法

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

Terminal

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

CLI 用法 · Skill 用法

使用注意

回调 token 属于凭据，日志中不要输出。
同一个 Hook 只能接收或关闭一次。
取消请求会关闭当前仍在等待的 Hook。

#等待回调 flow.hook

#模式与公开边界

#接收与安全检查