跳转到主要内容
本文档由 AI 自动翻译。如有任何不准确之处，请参考 英文原版。
当工作流执行到人工介入节点时会暂停，并在流式响应中发出 human_input_required 事件。该事件携带 form_token，集成方可凭其驱动整个表单生命周期，直到工作流恢复执行。 各接口的字段参考，详见 人工介入 API。

​
流程

下方流程同时适用于 Workflow 和 Chatflow 应用。两者仅在第 1 步的入口接口与第 5 步的恢复接口上有所不同。
1

以流式模式启动应用

  1. Workflow 应用调用 执行工作流，Chatflow 应用调用 发送对话消息。
  2. 在 SSE 流中关注 human_input_required 事件，提取其中的 form_token。 每个流式数据块都带有 task_id；请保留它，以便在第 5 步需要时恢复监听。
2

获取表单定义

使用 form_token 调用 获取人工介入表单 接口。响应包含渲染后的 Markdown、输入字段定义、可用操作、已预填的默认值，以及一个 expiration_time，超过该时间后表单将无法再提交。将表单呈现给接收人。
3

（仅文件输入）上传本地文件

若接收人为 file 或 file-list 输入附加了本地文件，请先通过 上传文件 上传。该接口返回一个 id，提交时作为 upload_file_id 引用。执行、上传和提交各次调用请使用同一个 user。远程文件无需上传：在提交时以 {transfer_method: remote_url, url} 映射内联附加即可。
4

提交响应

调用 提交人工介入表单 接口，附上接收人输入的值、所选的 action 以及你的 user。action 必须是第 2 步表单定义中的某个操作。文件输入既可使用 {transfer_method: local_file, upload_file_id} 映射（来自第 3 步），也可在提交时直接使用 {transfer_method: remote_url, url} 映射。两种模式的权衡详见 先上传 vs 直接提交远程 URL。提交一旦成功即为最终结果：表单随之关闭，工作流沿匹配的操作分支恢复执行，同一个 form_token 无法再次提交。若提交被拒绝（操作无效、缺少必填输入，或远程文件抓取失败），表单保持不变，修正输入后可用同一个 form_token 重新提交。
5

继续监听工作流

若原 SSE 流已关闭，使用第 1 步中的 task_id 调用 Workflow 或 Chatflow 的订阅工作流事件接口重新连接。恢复后的运行会像从未暂停过一样，继续流式输出其余节点事件直至完成。

​
先上传 vs 直接提交远程 URL

文件输入支持两种提交模式：
  • 先上传，再使用 upload_file_id（推荐） 上传文件 在上传阶段即校验文件大小、类型和扩展名，接收人可立即看到错误并在提交前重试。
  • 使用 transfer_method: remote_url 直接提交 后端在提交阶段抓取文件。集成更快，但任何大小、类型或抓取失败都会拒绝整次提交，接收人可能需要重填其他字段。
对于需要接收人反馈的交互式表单，优先选择先上传模式。仅当流程完全程序化、无需任何人重新输入时，直接提交模式的代价才能被抵消。

​
提交方式要求

人工介入 API 仅支持通过人工介入节点的 WebApp 提交方式投递的表单。仅通过邮件投递的表单不会向 API 暴露 form_token。

​
示例：带文件的提交

本示例的表单包含一个 feedback 段落输入、一个 attachments 文件列表输入，以及 approve / revise 两个操作。
  1. 调用 获取人工介入表单 接口获取表单定义： 
    GET /form/human_input/<form_token>
Authorization: Bearer {api-key}
  2. 针对每个本地文件，调用 上传文件 接口： 
    POST /files/upload
Authorization: Bearer {api-key}
Content-Type: multipart/form-data

file=<binary>
user=abc-123
    返回 {"id": "1a77f0df-...", ...}。
  3. 调用 提交人工介入表单 接口，附上接收人输入与所选操作： 
    POST /form/human_input/<form_token>
Authorization: Bearer {api-key}
Content-Type: application/json

{
  "inputs": {
    "feedback": "可以发布",
    "attachments": [
      {"transfer_method": "local_file", "upload_file_id": "1a77f0df-..."}
    ]
  },
  "action": "approve",
  "user": "abc-123"
}
    返回 {}。工作流沿 approve 分支恢复执行。
最后修改于 2026年6月26日