OpenCore治理集成指南

Hook 扩展

以 Markdown 格式查看

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 URLOpenCore 使用 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_idstring唯一只读文档标识符；response 中的修改会被忽略。
titlestring 或 null文档标题。
semantic_identifierstring文件名或页面标题等人类可读标识符。
sourcestring只读连接器来源；response 中的修改会被忽略。
sectionsarray有序文本或图片 section。每项包含 nullable 的 text、link 与 image_file_id；不会发送图片字节。
metadataobjectstring key 映射到 string array。
doc_updated_atstring 或 null已知时采用 ISO 8601 UTC 格式的来源更新时间。
primary_ownersarray 或 nullowner object，包含 nullable 的 display_name 与 email。
secondary_ownersarray 或 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_idstring唯一文档标识符。
titlestring 或 null文档标题。
contentstring拼接全部文本 section 后的完整文本内容。
sourcestring连接器来源。
urlstring 或 null可用时的规范来源 URL。
doc_updated_atstring 或 null已知时采用 ISO 8601 UTC 格式的来源更新时间。
metadataobjectstring 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。

输入字段类型含义
querystring用户输入的原始 query。
user_emailstring 或 null提交用户的 email；未认证时为 null。
chat_session_idstring已存在 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 failureSoft failure
Document Ingestion30 秒，hard文档不进入索引。使用原始文档继续。
Document Push30 秒，soft成功文档写入和 post_index 完成后，batch 在较晚阶段失败；更早的 push 可能已经执行。记录失败并继续 document-push 遍历。
Query Processing5 秒，hardQuery 被阻止。使用原始 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 继续运行，并且没有出站调用。

相关页面