> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# Hook 扩展

> 将受治理的外部端点连接到文档摄取、文档推送和查询处理 Hook point。

Hook 扩展会把规定的 JSON payload POST 到管理员管理的端点，并在 pipeline 使用响应前验证返回的 JSON object。应将每个 Hook 视为出站数据边界和同步依赖。

Hooks 有三项后端硬边界：管理 router 和 HTTP executor 来自具备企业能力的 EE server、部署必须是 single-tenant，并且每个管理 endpoint 都要求完整 Admin Panel 权限。仅社区版执行会返回 no-op 结果，管理依赖会拒绝 multi-tenant 部署。当前 Web UI 还会检查 Enterprise tier 并读取 `hooks_enabled`，但服务端将该设置直接派生为 `not MULTI_TENANT`；当前 license 与 tier middleware 均为透传，并非独立的后端 gate。

## 端点与认证合同

| 设置           | 合同                                                           | 边界                                                                 |
| ------------ | ------------------------------------------------------------ | ------------------------------------------------------------------ |
| Endpoint URL | OpenCore 使用 `Content-Type: application/json` 发送 HTTP `POST`。 | 使用已批准端点，不要依赖 redirect；client 不会跟随 redirect。                        |
| API key      | 后端合同中可选；当前创建表单要求填写。                                          | 配置后，OpenCore 会发送 `Authorization: Bearer <HOOK_API_KEY>`。           |
| 响应           | 成功调用必须返回 2xx 状态，以及符合 Hook point 的 JSON object。               | 非 JSON、array、HTTP error、timeout 和 schema failure 都属于 Hook failure。 |
| 激活状态         | 每个 Hook point 只执行一个 active 且未删除的配置。                          | Hook 缺失、inactive 或没有 endpoint 时会被跳过。                               |

不要把最终用户 token 复用为 Hook API key。请通过 Admin Panel 轮换 key，再次验证 endpoint，并避免 request 或 response body 进入 error log。

## Document Ingestion

此 Hook 在内部验证之后、索引写入之前，对每份文档运行。所有顶层 input field 都是必填项；标为 nullable 的字段可以携带 `null`。

| 输入字段                  | 类型            | 含义                                                                        |
| --------------------- | ------------- | ------------------------------------------------------------------------- |
| `document_id`         | string        | 唯一只读文档标识符；response 中的修改会被忽略。                                              |
| `title`               | string 或 null | 文档标题。                                                                     |
| `semantic_identifier` | string        | 文件名或页面标题等人类可读标识符。                                                         |
| `source`              | string        | 只读连接器来源；response 中的修改会被忽略。                                                |
| `sections`            | array         | 有序文本或图片 section。每项包含 nullable 的 `text`、`link` 与 `image_file_id`；不会发送图片字节。 |
| `metadata`            | object        | string key 映射到 string array。                                              |
| `doc_updated_at`      | string 或 null | 已知时采用 ISO 8601 UTC 格式的来源更新时间。                                             |
| `primary_owners`      | array 或 null  | owner object，包含 nullable 的 `display_name` 与 `email`。                      |
| `secondary_owners`    | array 或 null  | 结构相同的 secondary owner object。                                             |

| 输出字段               | 是否必填       | 效果                                      |
| ------------------ | ---------- | --------------------------------------- |
| `sections`         | 是，但可为 null | 重排、删除或改写 section。`null` 或空 array 会丢弃文档。 |
| `rejection_reason` | 否          | 文档被丢弃时记录；省略后使用通用原因。                     |

默认 timeout 为 **30 秒**，默认 fail strategy 为 **hard**。端点或验证发生 hard failure 时，该文档不会被索引；soft failure 会忽略 Hook 结果，并使用原始文档继续。

## Document Push

此 Hook 仅在整个 batch 完成 vector database 写入和 `post_index` 后运行。随后 OpenCore 遍历成功索引的公开文档并逐一推送。它只在 single-tenant 部署中运行，且 `from_beginning=True` 会完全跳过 Document Push。配置了环境变量驱动的 document-push sink 时，该 sink 优先，受管理 Hook 不会被调用。

| 输入字段             | 类型            | 含义                            |
| ---------------- | ------------- | ----------------------------- |
| `document_id`    | string        | 唯一文档标识符。                      |
| `title`          | string 或 null | 文档标题。                         |
| `content`        | string        | 拼接全部文本 section 后的完整文本内容。      |
| `source`         | string        | 连接器来源。                        |
| `url`            | string 或 null | 可用时的规范来源 URL。                 |
| `doc_updated_at` | string 或 null | 已知时采用 ISO 8601 UTC 格式的来源更新时间。 |
| `metadata`       | object        | string key 映射到 string array。  |

返回 JSON object；`{}` 即可，因为 Document Push 不消费 response field。默认 timeout 为 **30 秒**，默认 strategy 为 **soft**，因此失败会被记录，遍历通常继续。如果管理员将 strategy 覆盖为 hard，失败可能在这个较晚阶段把 batch 标记为失败或抛出错误：成功文档已经完成写入，`post_index` 已结束，而且遍历中更早的 push 可能已经成功。

## Query Processing

此 Hook 在 chat message 保存前处理原始用户 query。其 input 不允许未知 field。

| 输入字段              | 类型            | 含义                            |
| ----------------- | ------------- | ----------------------------- |
| `query`           | string        | 用户输入的原始 query。                |
| `user_email`      | string 或 null | 提交用户的 email；未认证时为 `null`。     |
| `chat_session_id` | string        | 已存在 chat session 的小写连字符 UUID。 |

| 输出字段                | 是否必填 | 效果                                     |
| ------------------- | ---- | -------------------------------------- |
| `query`             | 否    | 替换 query。缺失、`null`、空值或只含空白字符时拒绝 query。 |
| `rejection_message` | 否    | 面向用户的拒绝文本；省略后使用通用消息。                   |

默认 timeout 为 **5 秒**，默认 strategy 为 **hard**，因为用户正在同步等待。hard failure 会阻止 query 并显示错误；soft failure 会忽略 Hook 结果，并使用原始 query 继续。

## 超时与失败策略

Admin Panel 接受大于 `0` 且不超过 `600` 秒的 timeout。除非端点有经过测量的差异理由，否则使用每个 Hook point 的默认值。

| Hook point         | 默认值       | Hard failure                                            | Soft failure              |
| ------------------ | --------- | ------------------------------------------------------- | ------------------------- |
| Document Ingestion | 30 秒，hard | 文档不进入索引。                                                | 使用原始文档继续。                 |
| Document Push      | 30 秒，soft | 成功文档写入和 `post_index` 完成后，batch 在较晚阶段失败；更早的 push 可能已经执行。 | 记录失败并继续 document-push 遍历。 |
| Query Processing   | 5 秒，hard  | Query 被阻止。                                              | 使用原始 query 继续。            |

Soft mode 不会让无效响应变成有效响应；它只决定失败后 pipeline 如何处理。失败执行会被记录，成功执行不会进入 failure log。

## 配置与运维

1. 确认具备企业能力的 server 以 single-tenant 模式运行，且操作者拥有完整 Admin Panel 权限。再确认当前 Web UI 开放 **Admin Panel → Hook Extensions**；其 Enterprise tier 与 `hooks_enabled` 检查属于 UI 条件，不是额外的后端 license enforcement。
2. 选择一个 Hook point，部署能接收其精确 input model 并返回精确 output model 的 endpoint。
3. 设置 display name、endpoint URL、API key、fail strategy 与 timeout。创建流程会验证 reachability 与认证。
4. 使用有代表性的非敏感 input 完成测试，再激活 Hook 并监控 endpoint latency 与失败执行记录。
5. 如需更改 endpoint、策略、timeout 或 key，请更新 Hook，并在依赖它之前重新验证。

## 验证

1. 让测试端点返回 `{}`，确认 Document Push 接受该响应，而转换型 Hook 会拒绝缺少所需有效内容的响应。
2. 对 Document Ingestion 重排 section，再返回空 section list，确认测试文档按预期 reason 被丢弃。
3. 对 Query Processing 改写测试 query，再返回空白内容，确认 query 在 message 保存前被拒绝。
4. 分别在 hard 与 soft strategy 下模拟 timeout、HTTP error、非 JSON response 和错误 JSON shape。
5. 停用 Hook，确认原始 pipeline 继续运行，并且没有出站调用。

## 相关页面

* [企业集成](/opencore/governance/enterprise-integrations)介绍整体条件式集成边界。
* [数据流](/opencore/governance/data-flows)介绍文档和 query 何时跨越处理边界。
* [连接器与索引](/opencore/knowledge/connectors)介绍连接器与索引生命周期。
* [用量、身份与安全](/opencore/governance/usage-and-security)介绍密钥与访问控制。