等待点

等待点（waitpoint） 是表示工作流运行中已暂停步骤的持久化行记录。工作流运行行仅携带状态（PAUSED、RUNNING 等）；暂停的原因存在于等待点上。

stateDiagram-v2
    [*] --> PENDING: createWaitpoint
    PENDING --> COMPLETED: 恢复信号
    COMPLETED --> [*]: 工作流继续
    [*] --> COMPLETED: 预完成（恢复信号先到达）

模式

字段	含义
`flowRunId`, `stepName`	哪个运行/步骤被暂停。联合唯一：一个步骤最多只有一个等待点。
`type`	`DELAY` 或 `WEBHOOK`。
`status`	`PENDING` 直到恢复信号到达，然后变为 `COMPLETED`。
`resumeDateTime`	对于 `DELAY`：何时触发恢复。
`responseToSend`	对于 `WEBHOOK`：立即返回给原始 webhook 触发器的可选 HTTP 响应。
`resumePayload`	恢复调用中的 `{ body, headers, queryParams }`，通过 `ctx.resumePayload` 暴露给 Piece。

类型

DELAY：在 resumeDateTime 恢复。服务器为该时间戳调度一次性的作业。延迟受服务器端可配置的最大值限制。
WEBHOOK：通过对等待点的恢复 URL 进行的任何 HTTP 调用恢复。如果设置了 responseToSend，则会立即回复原始触发器，从而允许单个 webhook 实现先响应再暂停。

生命周期

创建。 Piece 调用 ctx.run.createWaitpoint({ type, ... }) + ctx.run.waitForWaitpoint(id)。引擎将步骤标记为 paused，并要求服务器插入一条 PENDING 记录。该插入在 (flow run, step) 对上具有幂等性。
检查点。 引擎序列化执行上下文，并将工作流运行转换为 PAUSED。
恢复信号。 对恢复 URL 的 HTTP 调用或调度的作业触发。两者都携带 { body, headers, queryParams }。
重新运行。 工作节点重建上下文，并使用 ctx.executionType === ExecutionType.RESUME 和填充的 ctx.resumePayload 重新调用同一动作。

sequenceDiagram
    participant Piece
    participant Engine as 引擎
    participant Server as 服务器
    participant Queue as 作业队列
    participant Caller as 恢复调用方

    Piece->>Engine: createWaitpoint + waitForWaitpoint
    Engine->>Server: 注册等待点
    Server-->>Engine: { id, resumeUrl }
    Engine->>Engine: 检查点上下文, status = PAUSED
    Note over Piece,Server: ...时间流逝...
    Caller->>Server: 对 resumeUrl 发起 HTTP 调用
    Server->>Queue: 入队恢复作业
    Queue->>Engine: 恢复
    Engine->>Piece: 携带 resumePayload 重新调用

恢复先于暂停的竞态

回调可能在工作流运行将 PAUSED 写入磁盘之前到达。协议吸收了这种竞态：

完成等待点会对 PENDING 行加写锁。如果存在，则翻转为 COMPLETED 并存储 resumePayload。如果不存在，则改为插入一条预完成行。
当工作流运行转换为 PAUSED 时，服务器检查是否存在匹配的 COMPLETED 等待点，并立即入队恢复作业。

重复的回调被唯一约束吸收；引擎永远不会处理两次恢复。

端点

方法	路径	说明
`POST`	`/v1/waitpoints`	仅引擎使用。创建 `PENDING` 等待点，返回其恢复 URL。
`ALL`	`/v1/flow-runs/:id/waitpoints/:waitpointId`	异步恢复。
`ALL`	`/v1/flow-runs/:id/waitpoints/:waitpointId/sync`	同步恢复。HTTP 响应是工作流恢复后产生的任何内容。

Piece API

Piece 作者使用 ctx.run.createWaitpoint / ctx.run.waitForWaitpoint 创建等待点。WEBHOOK、DELAY 和 responseToSend 的模式见流程控制。