Hooks接入指南

本文介绍千问办公企业 Hook 的配置格式、HTTP 调用约定，以及各类事件的请求和响应。企业 Hook 由桌面客户端调用企业提供的 HTTP 服务。

当前支持的 Hooks 事件

当前千问办公对企业开放以下 6 个事件：

Hook 配置

Hook 配置格式

在企业管理后台【安全管控】→【Hooks 规则】中选择事件，填写该事件的 JSON 配置数组。数组中的每一项是一个 Hook 组，matcher 决定何时匹配，hooks 指定匹配后调用的服务。

下面的配置用于在 Bash 工具执行前调用检查服务，应填写在 PreToolUse 事件中：

[
  {
    "matcher": "^Bash$",
    "hooks": [
      {
        "type": "http",
        "url": "https://hooks.example.com/pre-tool-use",
        "timeout": 30,
        "headers": {
          "Authorization": "Bearer ..."
        }
      }
    ]
  }
]

将 URL 和凭据替换为实际值。不需要认证时可省略 headers。配置为空数组 [] 时，该事件不调用企业 Hook。

字段说明

Hook 组字段：

matcher 在 PreToolUse、PostToolUse 中用于匹配工具名了；在 SessionStart 中匹配 source；在 Notification 中匹配通知类型；UserPromptSubmit 和 Stop 不需要配置该字段。

matcher 匹配规则

HTTP Hook 字段:

同一事件命中多个 Hook 时，默认并行执行，相同 URL 会去重。不依赖数组顺序；需要按顺序处理时，在同一个服务端点内编排。

HTTP 调用约定

• 请求方法：POST，正文为当前事件的 JSON 对象。
• 请求头：默认包含 Content-Type: application/json 和 Accept: application/json，并附加配置中的 headers。
• 超时：超过 timeout 后结束该次调用，当前不自动重试。
• 推荐返回 HTTP 200 和 JSON 对象；不改变流程时返回 {}。

Hook 输入和输出

请求体通用字段

每个事件都包含以下通用信息：

{
  "event": "PreToolUse",
  "hook_event_name": "PreToolUse",
  "session_id": "session-xxxx",
  "transcript_path": "/path/to/transcript",
  "cwd": "/workspace"
}

响应体通用字段

1. 纯文本：仅适用于 SessionStart、UserPromptSubmit作为补充上下文。
2. JSON 对象：用于返回 decision、reason、hookSpecificOutput 等控制字段。

以下字段均可选，不需要改变流程时直接返回 {}。

{
  "decision": "block",
  "reason": "企业策略要求阻断本次处理。"
}

hookSpecificOutput 一旦出现，必须包含 hookEventName，并应填写当前事件名。顶层 decision 不接受 ask，工具确认应使用 permissionDecision。

continue: false 用于 UserPromptSubmit、PreToolUse、PostToolUse 和 Stop 的执行控制。SessionStart 用于补充上下文；Notification 不通过响应控制流程。不要用 async: true 表达企业 HTTP 回调的异步处理。

Hook 事件

以下请求示例展示事件名和专用字段；实际请求还包含上文列出的通用字段。各事件的 HTTP 调用失败行为统一按「HTTP 调用约定」处理。

SessionStart

会话开始或恢复时触发，用于提供业务背景、项目约束等上下文。

请求体：

{
  "hook_event_name": "SessionStart",
  "source": "startup"
}

响应体：

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "请在交付报告时注明数据来源和统计周期。"
  }
}

也可以直接返回纯文本作为上下文。没有附加内容时返回 {}；此事件不用于设置操作系统环境变量。

UserPromptSubmit

用户提交提示词后、模型处理前触发，用于检查输入或补充上下文。matcher 不筛选提示词内容。

请求体：

{
  "hook_event_name": "UserPromptSubmit",
  "prompt": "请汇总本季度客户反馈。"
}

拒绝本次输入时返回：

{
  "decision": "block",
  "reason": "请移除输入中的敏感凭据后重试。"
}

补充上下文时返回：

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "按产品线分类，使用本年度统一的反馈口径。"
  }
}

没有附加行为时返回 {}。本事件也支持纯文本上下文；不要通过返回 prompt 替换用户输入。

PreToolUse

工具实际执行前触发，用于校验或修改参数，以及允许、拒绝或请求用户确认。matcher 匹配 tool_name（如 Bash、Write、Edit、Read、Glob、Grep，MCP 工具名如 mcp__server__tool）

请求体：

{
  "hook_event_name": "PreToolUse",
  "tool_use_id": "tool-demo-001",
  "tool_name": "Bash",
  "tool_input": {...}
}

响应示例：将命令参数调整为只读检查，并请求用户确认。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "ask",
    "permissionDecisionReason": "请确认是否执行项目状态检查。",
    "updatedInput": {
      "command": "git status --short"
    },
    "additionalContext": "命令已调整为只读状态检查。"
  }
}

无权限决定时返回 {}，不要用 allow 代替「没有意见」。多个 Hook 的决定按 deny > ask > allow 聚合；允许仍受工具权限规则约束。

deny 只拒绝本次工具调用；需要停止当前执行时，使用 continue: false。

PostToolUse

工具成功执行后触发，用于检查结果、补充上下文或替换输出。matcher 匹配 tool_name。

请求体：

{
  "hook_event_name": "PostToolUse",
  "tool_use_id": "tool-demo-001",
  "tool_name": "Bash",
  "tool_input": {...},
  "tool_response": {
    }
}

工具相关字段与 PreToolUse 相同，另外包含：

阻断工具结果：

{
  "decision": "block",
  "reason": "工具输出包含不允许继续传递的内容。"
}

补充或替换工具结果：

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "updatedToolOutput": "xxxxxxx",
    "additionalContext": "请根据当前分支状态继续处理任务。"
  }
}

替换字段应返回非空字符串；两种替换字段同时出现时，updatedToolOutput 优先。多个 Hook 不应同时修改同一份输入或输出。

本事件发生时工具已经执行，拒绝或替换结果都不会撤销文件修改、命令执行或外部调用。 要阻止操作发生，应使用 PreToolUse。

Stop

智能体准备结束当前轮次时触发，用于检查是否满足交付条件。返回 block 的含义是「暂不结束，继续工作」。

请求体：

{
  "hook_event_name": "Stop",
  "stop_hook_active": false,
  "last_assistant_message": "季度报告已生成。"
}

要求继续补充时返回：

{
  "decision": "block",
  "reason": "请补充报告的数据来源和统计周期，再给出最终答复。"
}

continue: false 表示停止，不是要求继续。服务端应检查 stop_hook_active，设置终止条件。例如，已经要求继续过一次时返回 {}，避免反复触发。

Notification

出现权限确认、MCP 征询等通知时触发。matcher 匹配 notification_type，不是工具名。

请求体：

{
  "hook_event_name": "Notification",
  "notification_type": "permission_prompt",
  "message": "Tool requires confirmation",
  "details": {}
}

notification_type通知类型：

接收成功后返回 {}。此事件的响应不会批准、拒绝或改变原操作；部分路径仍会等待 HTTP 返回，服务应快速响应。具体客户端不一定产生全部通知类型，也不保证每次任务完成都发送 idle_prompt。