> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Human in the loop

# Human in the Loop

暂停工作流,询问一位工作区成员从选项列表中进行选择、提供文本回复,或在工作流继续之前进行批准/拒绝。

当工作流可以自动收集或准备候选选项,但需要人来做最终选择时,请使用此功能。例如,RSS 步骤可以获取新文章,然后 Human in the Loop 步骤可以询问队友接下来应研究哪篇文章。

## 配置

| 字段                        | 说明                                                                         |
| ------------------------- | -------------------------------------------------------------------------- |
| Question / approval title | 在批准页面和通知中向接收者显示的主问题或标题。在 Approval 模式下,这是批准标题。                              |
| Response mode             | 选择 **Choices** 显示可选列表,**Text area** 要求必填的输入答案,或 **Approval** 显示固定的批准/拒绝操作。 |
| Options source            | 解析为数组的变量表达式,例如 `{{rss_step.output.items}}`。仅在 Choices 模式下使用。               |
| Label path                | 用作每个选项可见标签的可选相对路径,例如 `title` 或 `source.title`。                             |
| Value path                | 用作所选值的可选相对路径,例如 `url` 或 `metadata.slug`。                                   |
| Description path          | 用作每个选项支持文本的可选相对路径,例如 `summary` 或 `content.excerpt`。                        |
| Recipient                 | 当通知渠道为 Email 时,允许做出选择的工作区成员。                                               |
| Notification channel      | Email 或 Telegram。                                                          |
| Telegram destination      | 当通知渠道为 Telegram 时使用的已连接 Fetch Hive 机器人目的地。                                 |
| Link TTL                  | 批准链接令牌在接收者必须请求新链接之前保持有效的时长。                                                |
| Wait timeout              | 工作流在步骤失败或根据失败行为继续之前等待的时长。                                                  |

label、value 和 description 字段是相对于选项数组中每一项的路径。它们仅在 Choices 模式下适用。当选项源从现有步骤输出或起始输入示例中解析时,编辑器可以从第一个示例项建议路径。带有完整路径的嵌套同名字段可以消除歧义,例如 `source.title` 和 `author.title`。同一 JSON 对象中重复的键在 JSON 解析后无法区分。

## 输出

该步骤始终返回相同的顶层对象,以便在工作流运行之前接入后续步骤。

Choices 模式返回所选选项:

```json theme={null}
{
  "response_type": "choice",
  "choice": {
    "id": "option_1",
    "label": "Example article",
    "value": "https://example.com/article",
    "description": "Short summary",
    "raw": {}
  },
  "text": "",
  "files": [],
  "metadata": {}
}
```

在运行完成之前,下游步骤仍可以针对相同的空形状进行接入:

```json theme={null}
{
  "text": "",
  "files": [],
  "choice": {
    "id": "",
    "label": "",
    "value": "",
    "description": "",
    "raw": {}
  },
  "metadata": {},
  "response_type": "choice"
}
```

Text 模式返回输入的答案:

```json theme={null}
{
  "text": "Submitted answer",
  "files": [],
  "choice": {
    "id": "",
    "label": "",
    "value": "",
    "description": "",
    "raw": {}
  },
  "metadata": {},
  "response_type": "text"
}
```

Approval 模式返回所选决定。Approve 让工作流继续:

```json theme={null}
{
  "text": "",
  "files": [],
  "choice": {
    "id": "approved",
    "label": "Approved",
    "value": "approved",
    "description": "",
    "raw": { "approved": true }
  },
  "metadata": {
    "approved": true,
    "rejected": false
  },
  "response_type": "approval"
}
```

Reject 有意停止工作流并将该次运行标记为已完成:

```json theme={null}
{
  "text": "",
  "files": [],
  "choice": {
    "id": "rejected",
    "label": "Rejected",
    "value": "rejected",
    "description": "",
    "raw": { "approved": false }
  },
  "metadata": {
    "approved": false,
    "rejected": true
  },
  "response_type": "approval"
}
```

下游步骤引用工作流构建器中显示的实际步骤标识符。例如,如果此步骤为 `step_5`,使用:

| 变量                                     | 用途                                       |
| -------------------------------------- | ---------------------------------------- |
| `{{step_5.output.text}}`               | Text area 模式下提交的文本答案。Choices 模式下为空。      |
| `{{step_5.output.choice.value}}`       | Choices 模式下所选选项的值。                       |
| `{{step_5.output.choice.label}}`       | Choices 模式下所选选项的标签。                      |
| `{{step_5.output.choice.description}}` | Choices 模式下所选选项的描述。                      |
| `{{step_5.output.choice.raw.url}}`     | 原始所选选项对象中的字段(当该字段存在时)。                   |
| `{{step_5.output.metadata.approved}}`  | 当 Approval 模式获得批准时为 `true`。              |
| `{{step_5.output.metadata.rejected}}`  | 当 Approval 模式被拒绝时为 `true`。               |
| `{{step_5.output.response_type}}`      | `choice`、`text` 或 `approval`,取决于接收者如何响应。 |

## 运行时

在等待接收者期间,工作流会被暂停。Fetch Hive 通过配置的通知渠道发送短时有效的批准链接。Email 模式发送给所选接收者。Telegram 模式发送到所选 Telegram 目的地。如果链接过期,接收者可以从批准页面请求新链接。

只有配置的接收者才能查看并提交选择,并且他们仍必须属于工作流的工作区。

在 Approval 模式下,Approve 会正常恢复工作流。Reject 被视为有意停止:Fetch Hive 记录被拒绝的输出,跳过剩余的工作流步骤,并将工作流运行标记为已完成,而不是失败。

## API 行为

包含 Human in the Loop 的已部署工作流必须使用回调 URL 异步运行。同步 API 调用会返回验证错误,因为在提交人类响应之前工作流无法完成。

## 费用

Human in the Loop 使用固定的工作流步骤额度,且其本身不调用 LLM。

## 备注

* Human in the Loop 不支持步骤级并行。
* 在当前版本中,Human in the Loop 不能放置在迭代主体内。
* 如果等待超时到期,该步骤将遵循其配置的失败行为:终止或继续。
* 超时与 Reject 不同。超时遵循失败行为;Reject 有意完成该次运行。