Hook 系统

Hook 是 Agent 运行时的生命周期扩展点。通过注册 Hook，您可以在 Agent 执行的关键节点插入自定义逻辑，例如在每轮对话前注入知识、在对话结束后提取记忆、在工具调用前做权限检查等。

核心概念

事件驱动

Hook 基于事件模型运作。Agent 运行过程中会在关键节点发布事件，已注册的 Hook 监听到对应事件后执行自定义逻辑。

优先级排序

同一事件可以注册多个 Hook。执行顺序由 priority 决定，数值越小优先级越高（priority 5 先于 priority 10 执行）。

结果控制

每个 Hook 执行后返回结果，决定后续流程是继续、跳过还是中止。

事件类型

Agent 运行时支持 15 种事件，覆盖会话、对话轮次、工具调用、记忆处理和自动化运行的完整生命周期。

会话事件

事件	触发时机	典型用途
`session_start`	会话开始	初始化上下文、加载配置
`session_end`	会话结束	清理资源、保存状态

对话轮次事件

事件	触发时机	典型用途
`pre_turn`	每轮对话处理前	注入知识、准备上下文
`post_turn`	每轮对话处理后	日志记录、后处理
`turn_complete`	轮次完成（异步）	提取记忆、异步分析

工具调用事件

事件	触发时机	典型用途
`pre_tool_call`	工具调用前	权限检查、参数校验
`post_tool_call`	工具调用后	结果审计、指标采集

记忆处理事件

事件	触发时机	典型用途
`pre_memory_inject`	记忆注入到提示前	过滤或增强注入内容
`post_memory_extract`	记忆召回后	日志记录、内容过滤
`pre_memory_store`	存储新记忆前	敏感信息拦截、内容脱敏

演化与后台事件

事件	触发时机	典型用途
`evolution_detected`	检测到用户行为模式	自动调整策略
`dream_scheduled`	后台整理任务被调度	日志记录、资源管理

自动化运行事件

事件	触发时机	典型用途
`run_start`	自动化运行开始	初始化、通知
`run_success`	自动化运行成功	结果通知、触发后续
`run_failure`	自动化运行失败	告警、错误上报

执行模式

Hook 支持两种执行模式：

模式	行为	适用场景
`sequential`	按优先级串行执行，遇到 Abort 立即中断后续	需要严格顺序的场景
`parallel`	所有 Hook 并行执行，互不阻塞	可独立运行的场景

默认模式为 sequential。

执行结果

每个 Hook 处理函数返回以下四种结果之一：

结果	含义	对后续 Hook 的影响
`Continue`	正常继续	无影响
`ContinueWith`	正常继续，并携带数据传递给下游	无影响，数据可被后续环节读取
`Skip`	跳过当前事件的后续处理	不执行后续 Hook
`Abort`	中止执行，附带错误信息	串行模式下中断后续；并行模式下仅记录日志

Hook 定位与加载规则

Hook 的注册来源分为两类，加载顺序如下：

1. 内置 Hook（builtin）

应用启动时自动注册，不可删除，但可以通过 CLI 或 UI 禁用。

Hook ID	事件	优先级	模式	超时	说明
`builtin:knowledge_retrieval`	`pre_turn`	10	`parallel`	30 秒	对话前检索 Agent 知识库，将相关知识注入上下文
`builtin:process_turn_memories`	`turn_complete`	10	`sequential`	60 秒	对话后异步提取并存储学习记忆

2. 配置型 Hook（config）

在 Agent Profile 的 hooks 字段中声明，应用启动时按 Agent 逐一加载。

加载流程：

应用启动 → 调用 register_builtin_hooks()
遍历所有 Agent → 读取每个 Agent Profile 的 hooks 字段
解析每条 Hook 配置 → 创建对应的处理函数 → 注册到全局 Registry

定位规则：

同一事件下，Hook 按 priority 升序排列（数值小的先执行）
同一 id 的 Hook 会覆盖已有注册（后注册覆盖先注册）
禁用的 Hook 保留在 Registry 中但不参与执行

Hook ID 命名约定

前缀	来源	示例
`builtin:`	系统内置	`builtin:knowledge_retrieval`
`config:<id>`	Agent 配置来源	注册时标记为 `config:agent-123`
`custom:`	用户自定义	`custom:filter_sensitive`

配置型 Hook

配置格式

在 Agent Profile JSON 的 hooks 数组中定义：

json

{
  "hooks": [
    {
      "id": "custom:log_turns",
      "event": "post_memory_extract",
      "priority": 50,
      "enabled": true,
      "action": "log",
      "config": { "level": "info" }
    },
    {
      "id": "custom:filter_sensitive",
      "event": "pre_memory_store",
      "priority": 10,
      "enabled": true,
      "action": "filter",
      "config": { "patterns": ["password", "secret", "api_key"] }
    }
  ]
}

字段说明

字段	类型	必填	默认值	说明
`id`	文本	是	-	Hook 唯一标识
`event`	文本	是	-	监听的事件类型（snake_case）
`priority`	数字	否	50	执行优先级，越小越先执行
`enabled`	布尔	否	false	是否启用
`action`	文本	是	-	处理动作类型
`config`	对象	否	`{}`	动作的配置参数

支持的 Action 类型

log — 日志记录

记录 Hook 事件到系统日志。

json

{
  "action": "log",
  "config": { "level": "debug" }
}

level 可选值：debug（默认）、info、warn。

filter — 内容过滤

检查事件 payload 是否包含指定模式，匹配时跳过该事件的后续处理。

json

{
  "action": "filter",
  "config": { "patterns": ["password", "secret"] }
}

当 payload 中包含任一 pattern 字符串时，返回 Skip，阻止后续处理（例如阻止敏感信息被存入记忆）。

Hook 上下文

每个 Hook 执行时收到的上下文数据：

字段	类型	说明
`event`	文本	事件类型
`agent_id`	文本（可选）	当前 Agent ID
`conversation_id`	文本（可选）	当前对话 ID
`run_id`	文本（可选）	自动化运行 ID
`query`	文本（可选）	用户消息内容
`timestamp`	文本	ISO 8601 时间戳
`payload`	JSON 对象	事件携带的数据

INFO

安全敏感字段（auth_token、app_handle、cloud_api_base）不会序列化到 JSON 中，仅在 runtime 内部使用。

超时保护

所有 Hook 执行都有超时保护，超时后自动跳过并记录警告日志：

场景	默认超时
普通 Hook	30 秒
LLM 相关 Hook	120 秒

超时不会导致系统崩溃，Hook 超时后返回 Continue，后续流程正常继续。

发布模式

Hook 事件有两种发布方式：

方式	行为	使用场景
`publish`	阻塞等待所有 Hook 完成	需要 Hook 结果的场景（如 PreTurn 注入知识）
`publish_detached`	火力即忘，立即返回	不需要等待结果的场景（如 TurnComplete 异步提取记忆）

CLI 管理

通过 CLI 可以查看和管理已注册的 Hook：

bash

# 列出所有 Hook
workova hooks:list

# 按事件类型过滤
workova hooks:list --event pre_turn

# 启用指定 Hook
workova hooks:toggle --event pre_turn --hook-id builtin:knowledge_retrieval --enabled

# 禁用指定 Hook
workova hooks:toggle --event pre_turn --hook-id builtin:knowledge_retrieval --no-enabled

适用场景

场景	推荐事件	说明
知识增强	`pre_turn`	在对话前注入相关知识提升回答质量
记忆提取	`turn_complete`	对话后异步提取关键信息存入长期记忆
敏感信息拦截	`pre_memory_store`	在存储记忆前过滤密码、密钥等敏感内容
工具调用审计	`post_tool_call`	记录所有工具调用的参数和结果
权限控制	`pre_tool_call`	在工具执行前检查权限，不满足时中止
运行状态通知	`run_success` / `run_failure`	自动化运行结束后发送通知

下一步

了解 Agent 基本能力：AI 助理
自动化触发配置：自动化
CLI 完整命令：完整命令参考

Hook 系统 ​

核心概念 ​

事件驱动 ​

优先级排序 ​

结果控制 ​

事件类型 ​

会话事件 ​

对话轮次事件 ​

工具调用事件 ​

记忆处理事件 ​

演化与后台事件 ​

自动化运行事件 ​

执行模式 ​

执行结果 ​

Hook 定位与加载规则 ​

1. 内置 Hook（builtin） ​

2. 配置型 Hook（config） ​

Hook ID 命名约定 ​

配置型 Hook ​

配置格式 ​

字段说明 ​

支持的 Action 类型 ​

log — 日志记录 ​

filter — 内容过滤 ​

Hook 上下文 ​

超时保护 ​

发布模式 ​

CLI 管理 ​

适用场景 ​

下一步 ​

Hook 系统

核心概念

事件驱动

优先级排序

结果控制

事件类型

会话事件

对话轮次事件

工具调用事件

记忆处理事件

演化与后台事件

自动化运行事件

执行模式

执行结果

Hook 定位与加载规则

1. 内置 Hook（builtin）

2. 配置型 Hook（config）

Hook ID 命名约定

配置型 Hook

配置格式

字段说明

支持的 Action 类型

log — 日志记录

filter — 内容过滤

Hook 上下文

超时保护

发布模式

CLI 管理

适用场景

下一步