Hooks接入指南

更新时间:
复制 MD 格式

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

当前支持的 Hooks 事件

当前千问办公企业旗舰版支持以下 12 个事件:

事件

触发时机

典型用途

可以阻止操作

SessionStart

会话启动、恢复、清空或压缩后重新进入会话时

记录会话、注入企业规范

不建议用于阻断

UserPromptSubmit

用户提交内容后、内容进入 Agent 前

敏感信息检查、提示词合规检查

可以

PreToolUse

Agent 调用工具前

命令管控、文件操作管控、权限审批

可以

PostToolUse

工具执行完成后

操作审计、结果检查

工具已经执行,无法撤销

Stop

Agent 准备结束当前响应时

完整性检查、要求 Agent 继续处理

可以阻止 Agent 停止

Notification

Agent 产生通知时

通知转发、安全审计

不建议用于阻断

PreUserPromptSubmit

每轮用户输入保存并进入 Agent 前,包含首轮和后续轮次

替换提示词、输入合规检查

可以

PreCompact

手动或自动压缩上下文前

压缩前检查

可以阻止本次压缩

PostCompact

上下文成功压缩后

记录压缩摘要

压缩已经完成,无法撤销

ConnectorAdded

连接器添加、启用或配置更新生效前

连接器配置安全审批

可以

ExpertSuiteAdded

专家套件安装生效前

套件完整文件安全审批

可以

SkillAdded

技能安装生效前

技能完整文件安全审批

可以

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 组数组结构,在控制台选择对应事件即可;不需要在数组外再包一层事件名或 hooks。

字段说明

Hook 组字段:

matcher 在 PreToolUse、PostToolUse中匹配工具名;在 SessionStart 中匹配 source;在 Notification 中匹配 notification_type;在 PreCompact、PostCompact 中匹配 trigger(manual 或 auto)。

UserPromptSubmit 和 Stop 不需要配置该字段。

字段

类型

必填

说明

matcher

string

否

JavaScript 正则表达式,大小写敏感;省略表示匹配全部

hooks

array

是

HTTP Hook 列表,至少包含 1 项

PreUserPromptSubmit、ConnectorAdded、ExpertSuiteAdded、SkillAdded 的 matcher 建议省略;省略、空字符串或 "*"均匹配全部,其他值按正则匹配事件名,不匹配提示词、文件名或连接器名。内容筛选在服务端读取请求体判断。

matcher 匹配规则

写法

含义

示例

不填

匹配所有

所有工具都触发

精确值

精确匹配

"Bash" 只匹配 Bash 工具

<code>|</code> 分隔

匹配多个值

<code>"Write|Edit"</code> 匹配 Write 或 Edit

正则表达式

正则匹配

"mcp__.*" 匹配所有 MCP 工具

HTTP Hook 字段:

字段

类型

必填

说明

type

string

是

固定为 http。其他类型会被客户端拒收,不会执行

url

string

是

接收事件的完整 HTTP 或 HTTPS 地址

timeout

number

否

超时时间,单位为秒,必须大于 0。PreUserPromptSubmit、ConnectorAdded、ExpertSuiteAdded、SkillAdded 默认 10 秒;其他事件默认 600 秒。建议显式配置。

headers

object<string, string>

否

自定义请求头,键和值均为字符串。显式配置 headers.Accept 会覆盖默认值。

同一事件命中多个 Hook 时:PreUserPromptSubmit、ConnectorAdded、ExpertSuiteAdded、SkillAdded 按配置顺序串行执行,遇到合法 block 立即停止,后续 allow 不能覆盖 block;不按 URL 去重。

其他事件默认并行执行,相同 URL 会去重,不应依赖数组顺序。

HTTP 调用约定

  • 请求方法:POST,正文为当前事件的 JSON 对象。

  • 请求头:默认包含 Content-Type: application/json 和 Accept: application/json,并附加配置中的 headers。

  • 超时:超过 timeout 后结束该次调用,当前不自动重试。

推荐返回 HTTP 200 和当前事件支持的 JSON 对象。PreUserPromptSubmit、ConnectorAdded、ExpertSuiteAdded、SkillAdded 使用下文的 allow / block 格式;其他事件不干预流程时返回 {}。

HTTP 状态码

响应体

客户端行为

2xx

空

不改变原流程

2xx

合法 JSON 对象

按当前事件支持的响应字段处理

2xx

纯文本

SessionStart、UserPromptSubmit 将文本作为上下文;PreToolUse 将其解释为允许,不建议使用

2xx

JSON 语法错误或字段校验失败

PreToolUse 拒绝本次工具调用;其他事件记录错误后继续

非 2xx

任意

记录调用错误,继续原流程

连接失败或超时

—

记录调用错误,继续原流程

PreUserPromptSubmit、ConnectorAdded、ExpertSuiteAdded、SkillAdded 的处理补充:

返回情况

处理方式

HTTP 2xx+ 合法 allow

继续执行后续 Hook;没有阻断时继续原操作。

HTTP 2xx + 合法 block

立即终止本次操作,不执行后续 Hook;技能、专家套件、连接器统一按普通文本展示 reason,不执行其中的 HTML。

服务不可达、连接失败、超时、HTTP 非 2xx(含 4xx、5xx)

记录错误并跳过当前 Hook,继续后续 Hook;没有合法 block 时继续原操作。

空响应、纯文本、非法 JSON、未知字段或字段校验失败

记录错误并跳过当前 Hook,继续原流程;不是一次成功审批。

用户取消、身份未就绪或请求期间身份变化、本地 URL 安全校验或文件校验失败

停止本次操作;这些不是服务不可用,不适用异常放行。

上述 4 个事件不跟随 HTTP 重定向。需要阻断时必须返回 HTTP 2xx 和合法 block 响应;HTTP 403、HTTP 500 或缺少必填字段的 block 均按异常跳过,不产生阻断。

Hook 输入和输出

请求头新增字段(后续支持)

Third-Party-User-Id: external-user-001
Turn-Id: turn-001
App-Version: 1.3.2

字段

类型

说明

Third-Party-User-Id

string

客户身份系统中的用户标识,由客户端根据当前已认证身份获取。与千问办公平台用户 ID 含义不同,未取得有效值时不传。

Turn-Id

string

当前用户请求对应的执行轮次标识,用于关联同一轮次内产生的多个 Hook 事件。无法明确归属执行轮次的事件不传。

App-Version

string

发起 Hook 请求的客户端应用版本,例如 1.3.2。

请求体通用字段

请求字段由客户端自动填入,不是客户配置项。SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop、Notification、PreCompact、PostCompact 包含以下通用信息:

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

字段

类型

说明

event

string

HTTP 事件名,与 hook_event_name 一致

hook_event_name

string

当前事件名称,可用于服务端分发

session_id

string

当前会话 ID

transcript_path

string

客户端会话记录的本地路径

cwd

string

客户端当前工作目录

permission_mode

string,可能缺省

当前权限模式

agent_id

string,可能缺省

智能体 ID

agent_type

string,可能缺省

智能体类型

model

string,可能缺省

模型标识,当前可在 SessionStart 中提供

PreCompact、PostCompact 仅包含以上示例中的基础字段及各自专用字段,不包含 permission_mode、agent_id、agent_type、model。

PreUserPromptSubmit、ConnectorAdded、ExpertSuiteAdded、SkillAdded 使用以下公共字段:

请求字段

类型

说明

hook_event_name

string

当前事件名;服务端可据此分发。

request_id

string

由用户身份、逻辑操作及内容生成的稳定标识;用于关联请求,不应当作永不重复的全局流水号,也不代表客户端会自动重试。

user_id

string

当前已登录且完成身份校准的用户 ID。

app_version

string

客户端版本。

这 4 个事件不包含 event、cwd、transcript_path 等引擎通用字段。仅 PreUserPromptSubmit 另含 session_id、turn_id。示例中的用户、请求、会话和版本均为示例值。

响应体通用字段

  1. 纯文本:仅适用于 SessionStart、UserPromptSubmit作为补充上下文。

  2. JSON 对象:用于返回 decision、reason、hookSpecificOutput 等控制字段。

以下响应字段适用于 SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop、Notification,并非每个事件都支持所有字段。请按各事件的示例组合;不改变流程时返回 {}。

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

字段

类型

说明

continue

boolean

false 请求停止当前执行;省略时不主动停止

stopReason

string

与 continue: false 配套的停止原因

decision

string

业务决定,阻断为block;具体含义见各事件

reason

string

业务决定的原因

hookSpecificOutput

object

当前事件的专用响应字段

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

continue: false 用于 UserPromptSubmit、PreToolUse、PostToolUse 和 Stop 的执行控制。

SessionStart 用于补充上下文;Notification 不通过响应控制流程。不要用 async: true 表达企业 HTTP 回调的异步处理。

PreUserPromptSubmit、ConnectorAdded、ExpertSuiteAdded、SkillAdded 只接受各事件列出的严格 JSON 响应,不使用上述通用响应字段。

未知字段、类型错误、非法组合、纯文本或 {} 均按无效响应处理。PreCompact、PostCompact 的响应单独见对应事件。

Hook 事件

以下请求示例展示事件名和专用字段,实际请求还包含「请求体通用字段」中对应事件的公共信息。HTTP 调用失败按「HTTP 调用约定」处理。

SessionStart

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

请求体:

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

字段

类型

说明

source

string

会话来源:startup(新建)、resume(恢复)、clear(清空后开始)、compact(压缩后恢复)等

响应体:

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

专用响应字段

类型

说明

additionalContext

string

附加给模型的会话上下文

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

PreUserPromptSubmit

每轮用户主动提交文本,在写入正式聊天记录、进入 Agent 前触发。它负责整体替换或阻断本轮输入;既有 UserPromptSubmit 后续接收处理后的文本,仍只按原协议阻断或补充上下文,不能承担整体替换。

请求体:

{
  "hook_event_name": "PreUserPromptSubmit",
  "session_id": "session-example-001",
  "turn_id": "turn-example-001",
  "isFirstTurn": true,
  "prompt": "请分析客户张三的反馈。"
}

事件字段

类型

说明

session_id

string

客户端会话标识;首轮可以预分配。

turn_id

string

客户端本次提交的逻辑操作标识,不等同于原生引擎内部 Turn ID。

isFirstTurn

boolean

请求中表示是否为实际首轮用户输入。首轮阻断后重新提交仍为 true;重启或重新打开会话不会重置。

prompt

string

本轮待提交的文本。

响应体:

允许并保留原文:

{
  "decision": "allow",
  "isFirstTurn": true
}

允许并完整替换本轮文本:

{
  "decision": "allow",
  "isFirstTurn": true,
  "updated_prompt": "请分析客户[姓名已脱敏]的反馈。"
}

阻断本轮提交:

{
  "decision": "block",
  "isFirstTurn": true,
  "reason": "输入包含敏感信息,请修改后重试。"
}

响应字段

类型

约束

decision

string

必填,仅 allow 或 block。

isFirstTurn

boolean

两种响应都必填,由服务端返回;控制首轮 / 后续轮次的替换标记及阻断提示。通常回传请求值;客户端不要求响应值与请求值一致。

updated_prompt

string

仅可与 allow 搭配,必须为非空白字符串;缺省时保留当前文本。

reason

string

仅与 block 搭配,必填且不能是空白字符串。

替换成功后,正式聊天记录、用户消息展示、后续会话历史和模型输入使用替换后的文本,并显示企业处理标记。阻断时不新增正式用户消息,保留可编辑输入。本事件只处理文本,不审核或替换附件文件内容、系统指令、工具参数或工具结果。

多个 Hook 串行处理同一轮输入,前一个 Hook 的替换结果作为后一个 Hook 的 prompt;后续服务异常不会恢复原文。最后一个合法 allow 响应的 isFirstTurn 用于展示轮次。

UserPromptSubmit

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

请求体:

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

字段

类型

说明

prompt

string

本次用户提示词

拒绝本次输入时返回:

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

补充上下文时返回:

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

响应字段

类型

说明

decision

string

block 阻断本次提示词进入模型;无决定时省略

reason

string

拒绝原因,界面不保证逐字展示

hookSpecificOutput.additionalContext

string

附加给本次请求的上下文

没有附加行为时返回 {}。本事件也支持纯文本上下文;不要通过返回 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": {...}
}

字段

类型

说明

tool_use_id

string

本次工具调用 ID

tool_name

string

工具名称

tool_input

object

工具输入参数

mcp_context

object,可选

MCP 服务信息,包括 server_name、tool_name,以及可选的 url、command、args、cwd、tcp

original_request_name

string,可选

工具名称解析或别名转换前的请求名

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

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

专用响应字段

类型

说明

permissionDecision

string

allow:明确允许;

deny:拒绝;

ask:请求确认;

permissionDecisionReason

string

权限决定的原因

updatedInput

object

完整替换工具参数,不是局部合并;替换后会重新校验参数

additionalContext

string

附加给模型的说明

无权限决定时返回 {},不要用 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 相同,另外包含:

字段

类型

说明

tool_response

object

工具执行结果,内部结构因工具而异;示例不代表固定返回结构

阻断工具结果:

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

补充或替换工具结果:

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

响应字段

类型

说明

decision

string

返回 decision: "block" 时,向后续处理提供 Hook 错误反馈;不保证屏蔽原始工具结果,也不会撤销已经执行的操作。

reason

string

阻断结果的原因

hookSpecificOutput.additionalContext

string

附加给模型的说明

hookSpecificOutput.updatedToolOutput

string

替换工具输出文本

hookSpecificOutput.updatedMCPToolOutput

string

仅用于 MCP 的兼容替换字段;优先使用 updatedToolOutput

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

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

Stop

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

请求体:

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

字段

类型

说明

stop_hook_active

boolean

是否已经因 Stop Hook 的要求继续过;再次准备结束时为 true

last_assistant_message

string,可选

本轮累计的智能体文本输出

要求继续补充时返回:

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

响应字段

类型

说明

decision

string

block 阻止正常结束,并要求智能体继续;返回 {} 允许结束

reason

string

需要智能体继续完成的具体工作

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

string

通知类型,具体枚举值见下表

message

string

通知正文

details

object

通知详情,结构随通知类型变化

notification_type通知类型:

值

含义

permission_prompt

请求权限确认

elicitation_dialog

MCP 征询开始

elicitation_response

收到 MCP 征询响应

elicitation_complete

MCP 征询完成

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

PreCompact

上下文实际执行手动或自动压缩前触发,不是每轮对话都会触发。matcher 匹配 trigger。

请求体:

{
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": "保留尚未完成的任务和关键约束。"
}

字段

类型

说明

trigger

string

manual:手动压缩;auto:自动压缩。

custom_instructions

string

本次压缩自定义要求,没有时为空字符串。

响应体:

不干预本次压缩:

{}

阻止本次压缩:

{
  "decision": "deny",
  "reason": "当前任务仍需保留完整上下文,暂不允许压缩。"
}

响应字段

类型

说明

decision

string

deny 阻止本次压缩;不干预时返回 {}。本事件不使用 allow / block 审批格式。

reason

string

阻止压缩的原因。

阻止压缩不等于终止会话,也不保证上下文超限后仍能继续请求模型。压缩控制效果需以交付版本联调结果为准。

PostCompact

上下文成功压缩后触发,用于接收压缩摘要。压缩失败或被阻止时不触发成功通知。matcher 匹配 trigger。

请求体:

{
  "hook_event_name": "PostCompact",
  "trigger": "auto",
  "compact_summary": "用户正在分析季度反馈,已完成分类,下一步生成报告。"
}

字段

类型

说明

trigger

string

manual:手动压缩;auto:自动压缩。

compact_summary

string

本次压缩摘要,可能为空字符串。

响应体:

{}

接收成功后返回 {}。此事件不能撤销压缩;本文不定义替换摘要或注入上下文的响应字段。实际触发需以交付版本联调结果为准。

ConnectorAdded

审批连接器待生效配置;覆盖受控的新建、导入、市场安装、启用及配置更新。合法 block 后不注册、不启用或不应用本次更新,不撤销此前已经生效的配置。

请求体:

{
  "hook_event_name": "ConnectorAdded",
  "source": "manual_config",
  "content_digest": "<SHA-256 十六进制摘要>",
  "connector": {
    "name": "enterprise-knowledge",
    "kind": "mcp",
    "config": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    },
    "redacted_fields": []
  }
}

字段

类型

说明

source

string

来源:marketplace(市场安装)、local_import(本地导入或对话创建后安装)、manual_config(手动配置等入口)、console(企业控制台下发)。由客户端填写。

content_digest

string

待生效内容的 SHA-256 十六进制摘要,用于关联送审快照,不是下载地址。

connector

object

待生效连接器配置,子字段见下表。

connector 字段

类型

说明

name

string

连接器名称。

kind

string

mcp 或 builtin。

config

object

实际待生效配置的脱敏副本;HTTP 连接器包含地址,本地命令型包含 command、args 等实际配置。具体结构随连接器类型变化。

redacted_fields

string[]

已隐藏的敏感字段路径;没有时为空数组。

客户端会处理显式 Token、密码、Cookie、Authorization 等凭据字段,以及 URL 凭据、敏感查询参数和显式命令参数。脱敏不是任意秘密识别器;不要把凭据藏在无法识别的自定义字段、文本或命令片段中。

响应体:

允许:

{
  "decision": "allow"
}

拒绝:

{
  "decision": "block",
  "reason": "该连接器的服务地址不在企业允许范围内。"
}

此事件审批添加配置,不替代后续工具调用的 PreToolUse 检查。

响应字段

类型

说明

decision

string

必填,仅 allow 或 block。allow 继续添加;block 阻止本次操作。

reason

string

仅与 block 搭配,必填且不能是空白字符串。客户端按普通文本展示该原因。

content_digest 基于脱敏前的实际配置计算,不能使用收到的脱敏 config 重算。通过客户端受控入口添加、启用或修改连接器时触发;直接修改磁盘配置文件不保证触发。

ExpertSuiteAdded

审批专家套件安装前的完整文件快照,包括包清单、技能、脚本及其他资源。读取送审内容不执行包内脚本。

请求体:

{
  "hook_event_name": "ExpertSuiteAdded",
  "source": "local_import",
  "content_digest": "<SHA-256 十六进制摘要>",
  "expert_suite": {
    "name": "feedback-suite",
    "version": "1.0.0",
    "manifest": {
      "name": "feedback-suite",
      "version": "1.0.0",
      "description": "Customer feedback review."
    },
    "files": [
      {
        "path": "plugin.json",
        "encoding": "base64",
        "content": "ewogICJuYW1lIjogImZlZWRiYWNrLXN1aXRlIiwKICAidmVyc2lvbiI6ICIxLjAuMCIsCiAgImRlc2NyaXB0aW9uIjogIkN1c3RvbWVyIGZlZWRiYWNrIHJldmlldy4iCn0="
      },
      {
        "path": "skills/feedback-summary/SKILL.md",
        "encoding": "base64",
        "content": "LS0tCm5hbWU6IGZlZWRiYWNrLXN1bW1hcnkKZGVzY3JpcHRpb246IFN1bW1hcml6ZSBjdXN0b21lciBmZWVkYmFjay4KLS0tCiMgRmVlZGJhY2sgc3VtbWFyeQpHcm91cCBmZWVkYmFjayBieSBwcm9kdWN0Lgo="
      }
    ]
  }
}

字段

类型

说明

source

string

来源:marketplace(市场安装)、local_import(本地导入或对话创建后安装)、manual_config(手动配置等入口)、console(企业控制台下发)。由客户端填写。

content_digest

string

待生效内容的 SHA-256 十六进制摘要,用于关联送审快照,不是下载地址。

expert_suite

object

待安装的专家套件,子字段见下表。

expert_suite 字段

类型

说明

name

string

套件名称。

version

string,可能缺省

包未声明版本时不传。

manifest

object

实际解析的包清单。

files

array

完整待生效文件快照,每项包含 path、encoding、content。示例仅示意文件结构。

文件字段

类型

说明

files[].path

string

包内相对路径,不是服务端可直接读取的本地路径或下载地址。

files[].encoding

string

固定为 base64。

files[].content

string

完整文件内容的 Base64 编码;服务端解码后检查。

响应体:

允许:

{
  "decision": "allow"
}

拒绝:

{
  "decision": "block",
  "reason": "专家套件包含未经允许的自动执行脚本。"
}

拒绝后本次套件不安装生效;客户端按普通文本展示 reason,不额外添加「导入套件失败」前缀。

响应字段

类型

说明

decision

string

必填,仅 allow 或 block。allow 继续添加;block 阻止本次操作。

reason

string

仅与 block 搭配,必填且不能是空白字符串。客户端按普通文本展示该原因。

通过市场、本地导入或对话调用受控安装入口时触发。送审后使用同一完整文件快照安装;单个快照最多 20 MiB 原始内容、5000 个文件。符号链接、特殊文件、超限或读取失败属于本地校验失败,会停止安装。直接修改磁盘目录不保证触发。

SkillAdded

审批技能安装前的完整文件快照,包括 SKILL.md、脚本、参考文件及其他资源,不仅是技能简介。

请求体:

{
  "hook_event_name": "SkillAdded",
  "source": "local_import",
  "content_digest": "<SHA-256 十六进制摘要>",
  "skill": {
    "name": "feedback-summary",
    "files": [
      {
        "path": "SKILL.md",
        "encoding": "base64",
        "content": "LS0tCm5hbWU6IGZlZWRiYWNrLXN1bW1hcnkKZGVzY3JpcHRpb246IFN1bW1hcml6ZSBjdXN0b21lciBmZWVkYmFjay4KLS0tCiMgRmVlZGJhY2sgc3VtbWFyeQpHcm91cCBmZWVkYmFjayBieSBwcm9kdWN0Lgo="
      }
    ]
  }
}

字段

类型

说明

source

string

来源:marketplace(市场安装)、local_import(本地导入或对话创建后安装)、manual_config(手动配置等入口)、console(企业控制台下发)。由客户端填写。

content_digest

string

待生效内容的 SHA-256 十六进制摘要,用于关联送审快照,不是下载地址。

skill

object

待安装的技能,子字段见下表。

skill 字段

类型

说明

name

string

技能名称。

version

string,可能缺省

技能元数据未声明版本时不传。

files

array

完整待生效文件快照,每项包含 path、encoding、content。

文件字段

类型

说明

files[].path

string

包内相对路径,不是服务端可直接读取的本地路径或下载地址。

files[].encoding

string

固定为 base64。

files[].content

string

完整文件内容的 Base64 编码;服务端解码后检查。

响应体:

允许:

{
  "decision": "allow"
}

拒绝:

{
  "decision": "block",
  "reason": "技能包含向未授权外部地址发送企业数据的指令。"
}

拒绝后本次技能不安装到生效目录;与连接器、专家套件保持一致,客户端直接展示 reason,不替换成通用上传失败提示。

响应字段

类型

说明

decision

string

必填,仅 allow 或 block。allow 继续添加;block 阻止本次操作。

reason

string

仅与 block 搭配,必填且不能是空白字符串。客户端按普通文本展示该原因。

通过市场、本地导入或对话调用受控安装入口时触发。送审后使用同一完整文件快照安装;单个快照最多 20 MiB 原始内容、5000 个文件。符号链接、特殊文件、超限或读取失败属于本地校验失败,会停止安装。直接修改磁盘目录不保证触发。