> ## Documentation Index
> Fetch the complete documentation index at: https://dify-6c0370d8-docs-new-agent-experience.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 人工介入 API 集成流程

> 通过 API 处理暂停中的人工介入表单的端到端流程

> 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/api-reference/guides/human-input-flow)。

当工作流执行到 [人工介入](/zh/cloud/use-dify/nodes/human-input) 节点时会暂停，并在流式响应中发出 `human_input_required` 事件。该事件携带 `form_token`，集成方可凭其驱动整个表单生命周期，直到工作流恢复执行。

各接口的字段参考，详见 [人工介入 API](/zh/api-reference/human-input/get-human-input-form)。

## 流程

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

<Steps>
  <Step title="以流式模式启动应用">
    1. Workflow 应用调用 [执行工作流](/zh/api-reference/workflow-runs/run-workflow)，Chatflow 应用调用 [发送对话消息](/zh/api-reference/chat-messages/send-chat-message)，并传入终端用户的 `user` 标识。
    2. 在 SSE 流中关注 `human_input_required` 事件，提取其中的 `form_token`。

       若 `form_token` 为 `null`，说明表单使用邮件投递，无法通过 API 驱动（见 [提交方式要求](#提交方式要求)）。

       `human_input_required` 事件同时携带本次运行的 `workflow_run_id`；请保留它，以便在第 5 步需要时恢复监听。
  </Step>

  <Step title="获取表单定义">
    使用 `form_token` 调用 [获取人工介入表单](/zh/api-reference/human-input/get-human-input-form) 接口。响应包含渲染后的 Markdown、输入字段定义、可用操作、已预填的默认值，以及一个 `expiration_time`，超过该时间后表单将无法再提交。将表单呈现给接收者。

    若表单在提交前过期，暂停的运行会按节点配置的超时行为处理；恢复后的事件流中携带的是 `human_input_form_timeout`，而非 `human_input_form_filled`。
  </Step>

  <Step title="（仅文件输入）上传本地文件">
    若接收者为 `file` 或 `file-list` 输入附加了本地文件，请先通过 [上传文件](/zh/api-reference/files/upload-file) 上传。该接口返回一个 `id`，提交时作为 `upload_file_id` 引用。执行、上传和提交各次调用使用同一个 `user`（见 [终端用户身份](/zh/api-reference/guides/end-user-identity)）。

    远程文件无需上传：在提交时以 `{transfer_method: remote_url, url}` 映射内联附加即可。
  </Step>

  <Step title="提交响应">
    调用 [提交人工介入表单](/zh/api-reference/human-input/submit-human-input-form) 接口，附上接收者输入的值、所选的 `action` 以及你的 `user`。`action` 必须是第 2 步表单定义中的某个操作。

    文件输入既可使用 `{transfer_method: local_file, upload_file_id}` 映射（来自第 3 步），也可在提交时直接使用 `{transfer_method: remote_url, url}` 映射。两种模式的权衡详见 [先上传 vs 直接提交远程 URL](#先上传-vs-直接提交远程-url)。

    提交一旦成功即为最终结果：表单随之关闭，工作流沿匹配的操作分支恢复执行，同一个 `form_token` 无法再次提交。

    若提交被拒绝（操作无效、缺少必填输入，或远程文件抓取失败），表单保持不变，修正输入后可用同一个 `form_token` 重新提交。
  </Step>

  <Step title="继续监听工作流">
    若原 SSE 流已关闭，可调用 [流式获取工作流事件](/zh/api-reference/workflow-runs/stream-workflow-events) 重新连接：使用第 1 步中的 `workflow_run_id`，并携带启动运行时的同一个 `user`（`user` 不一致会返回 404）。

    恢复后的事件流会先携带确认提交的 `human_input_form_filled`（表单过期时则是 `human_input_form_timeout`），随后像从未暂停过一样，继续输出其余节点事件直至完成。

    如需先重放已执行节点的状态，可附带 `include_state_snapshot=true`。若工作流串联了多个人工介入节点，流默认会在每次暂停时关闭；传入 `continue_on_pause=true` 可让同一条流跨越所有暂停保持连接。
  </Step>
</Steps>

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

文件输入支持两种提交模式：

* **先上传，再使用 `upload_file_id`**（推荐）

  [上传文件](/zh/api-reference/files/upload-file) 在上传阶段即校验文件大小限制，接收者可立即看到错误并在提交前重试。

* **使用 `transfer_method: remote_url` 直接提交**

  后端在提交阶段抓取文件。集成更快，但任何大小、类型或抓取失败都会拒绝整次提交，接收者可能需要重填其他字段。

<Tip>
  对于需要接收者反馈的交互式表单，优先选择先上传模式。仅当流程完全程序化、无需任何人重新输入时，直接提交模式的代价才能被抵消。
</Tip>

## 提交方式要求

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

## 示例：带文件的提交

本示例的表单包含一个 `feedback` 段落输入、一个 `attachments` 文件列表输入，以及 `approve` / `reject` 两个操作。

1. 调用 [获取人工介入表单](/zh/api-reference/human-input/get-human-input-form) 接口获取表单定义：

   ```http theme={null}
   GET /form/human_input/<form_token>
   Authorization: Bearer {api-key}
   ```

   返回表单定义：

   ```json theme={null}
   {
     "form_content": "Please review the draft and confirm or request changes.",
     "inputs": [
       {
         "type": "paragraph",
         "output_variable_name": "feedback",
         "default": {
           "type": "constant",
           "selector": [],
           "value": ""
         }
       },
       {
         "type": "file-list",
         "output_variable_name": "attachments",
         "allowed_file_types": [
           "image",
           "document"
         ],
         "allowed_file_extensions": [],
         "allowed_file_upload_methods": [
           "local_file",
           "remote_url"
         ],
         "number_limits": 5
       }
     ],
     "resolved_default_values": {},
     "user_actions": [
       {
         "id": "approve",
         "title": "Approve",
         "button_style": "primary"
       },
       {
         "id": "reject",
         "title": "Request changes",
         "button_style": "default"
       }
     ],
     "expiration_time": 1745510400
   }
   ```

2. 针对每个本地文件，调用 [上传文件](/zh/api-reference/files/upload-file) 接口：

   ```http theme={null}
   POST /files/upload
   Authorization: Bearer {api-key}
   Content-Type: multipart/form-data

   file=<binary>
   user=abc-123
   ```

   返回 `{"id": "1a77f0df-...", ...}`。

3. 调用 [提交人工介入表单](/zh/api-reference/human-input/submit-human-input-form) 接口，附上接收者输入与所选操作：

   ```http theme={null}
   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` 分支恢复执行。

4. 调用 [流式获取工作流事件](/zh/api-reference/workflow-runs/stream-workflow-events) 重新连接运行的事件流，跟踪至运行完成，与上文流程的第 5 步相同。