DeepAgents Hook机制详解：六种Hook与两种范式保障Agent生产可控

1. 从一次 Agent 失控说起：为什么 Hook 机制值得单独写一篇

去年冬天我接了个私活，帮一家做跨境电商的朋友搭一套自动客服 Agent。需求听起来不复杂：用户提问，Agent 查订单、查物流、必要时转人工。我用了当时最顺手的一套编排框架，三天跑通 demo，一周上线灰度。结果上线第二天凌晨两点，朋友电话打过来，说 Agent 在群里疯狂刷屏，同一个订单状态被重复查询了四十多次，还把内部库存字段直接吐给了用户。

我爬起来看日志，发现根因特别朴素：模型在某一步判断失误，触发了一个本不该触发的工具调用，而整个链路里没有任何一个环节能拦住它。工具调用没有前置校验，输出没有后置过滤，循环没有步数上限，异常没有兜底分支。说白了，我把一个能自主决策的系统放进了生产环境，却没给它装刹车。

那次事故之后，我把这套框架的 Hook 机制从头到尾啃了一遍，也对比了另外几套主流方案的设计哲学。越看越觉得，Hook 这个东西在 Agent 领域被严重低估了。大家聊 Agent 都在聊模型能力、聊工具生态、聊记忆系统，但真正决定一个 Agent 能不能上生产的，往往是这些"卡在关键节点上的小钩子"。

这篇就围绕 DeepAgents 这套体系里的六种 Hook 和两种范式展开。我会先讲清楚 Hook 到底解决什么问题，再逐个拆解六种 Hook 的职责边界和实现要点，然后重点聊两种范式——也就是"拦截式"和"增强式"——它们的设计取舍。中间会穿插大量我在实际项目里踩过的坑，包括参数怎么算、顺序怎么排、异常怎么兜。如果你正在做 Agent 相关的开发，或者准备把 Agent 推向生产，这篇应该能帮你少走不少弯路。

需要先说明一点：DeepAgents 是构建在 LangGraph 之上的 Agent 编排层，所以它的 Hook 机制和 LangGraph 的图执行模型是深度耦合的。理解 Hook 之前，最好对 LangGraph 的节点、边、状态流转有个基本概念。如果你还不熟，可以先把 LangGraph 的官方教程过一遍，不然下面有些设计意图会看不透。

2. Hook 到底在解决什么问题：Agent Loop 的四个失控点

2.1 Agent Loop 的本质是一个带状态的循环

很多人第一次接触 Agent，会觉得它很神秘。但把外壳剥掉，Agent Loop 的本质就是一个 while 循环：模型思考，决定要不要调工具，调完工具把结果塞回上下文，再思考，直到模型认为任务完成或者触发终止条件。

用伪代码写出来大概是这样：

while not done: thought = model.think(context) if thought.is_final: done = True break action = thought.action result = execute_tool(action) context.append(result)

看起来很简单对吧？但问题就出在这个"简单"上。这个循环里有四个地方特别容易失控，而且每一个失控点，靠模型自己是兜不住的。

第一个是入口失控。用户输入可能包含注入攻击、超长文本、恶意指令。模型看到什么就处理什么，它没有"这个输入我不该接"的判断力。

第二个是决策失控。模型可能选错工具、传错参数、在错误的时机调用。它可能陷入死循环，反复调用同一个工具。它可能幻觉出一个根本不存在的工具名。

第三个是执行失控。工具本身可能超时、报错、返回超大数据。工具可能有副作用，比如写数据库、发消息、扣款。执行环节出问题，模型是感知不到的。

第四个是出口失控。模型生成的最终回复可能包含敏感信息、内部字段、不当措辞。它可能把中间过程的思考链直接暴露给用户。

2.2 Hook 是插在循环关键节点上的拦截器

Hook 机制的核心思想，就是在这四个失控点上各插一道关卡。每一道关卡都是一个函数，它能在数据流经时做检查、做修改、做拦截、做记录。

你可以把 Hook 想象成机场的安检流程。值机（入口）要查证件，安检（决策）要查行李，登机口（执行）要核对身份，到达（出口）要过海关。每一道关卡都有明确的职责，而且关卡之间是串联的，前一道没过，后一道根本不会触发。

DeepAgents 把这道关卡体系拆成了六种 Hook，分别对应 Agent Loop 里六个最关键的时机。这六种 Hook 不是随便定的，它们覆盖了从输入到输出的完整生命周期，而且每一种都有明确的触发条件和数据契约。

2.3 为什么不用中间件而用 Hook

这里要澄清一个概念。很多人会把 Hook 和 middleware 混着说，其实两者有细微但重要的区别。

Middleware 通常是"包裹式"的，它包住一个完整的处理单元，在前后各加一层逻辑。比如一个 HTTP middleware，它包住整个请求处理过程，在请求进来前和响应出去后各做一件事。

Hook 则是"事件式"的，它绑定在特定的时机点上，触发即执行，执行完就退出。它不包裹任何东西，它只是"在某个时刻被叫一下"。

这个区别带来的实际影响是：middleware 更适合做横切关注点，比如日志、鉴权、限流；Hook 更适合做精细化的时机控制，比如"在工具调用前校验参数"和"在工具调用后过滤结果"是两个独立的 Hook，可以分别配置、分别启停。

DeepAgents 选择 Hook 而不是 middleware，我理解是出于两点考虑。一是 Agent Loop 的时机点比 HTTP 请求复杂得多，用 middleware 包裹会导致嵌套过深；二是 Hook 的粒度更细，能实现更精准的控制。这个设计取舍在后面讲两种范式的时候还会展开。

3. 六种 Hook 逐个拆解：职责、时机与实现要点

3.1 输入 Hook：把住第一道门

输入 Hook 在用户输入进入 Agent Loop 之前触发。它的核心职责是清洗、校验、改写输入。

我在实际项目里用输入 Hook 做过几件事。第一是长度截断，用户有时候会粘贴一整篇文档进来，直接塞给模型会爆上下文，输入 Hook 里按 token 数截断，保留头部和尾部，中间用省略标记。第二是敏感词过滤，把明显的注入指令、越权请求拦掉。第三是意图预分类，在进入主循环之前先判断这是不是 Agent 该处理的任务，不是的话直接走兜底回复，省一次模型调用。

输入 Hook 的实现要点是幂等。因为它可能被重试，也可能在调试时被手动触发多次，所以它不能有副作用。你不能在输入 Hook 里写数据库、发消息、改全局状态。它应该是一个纯函数：输入什么，输出什么，中间不留下任何痕迹。

还有一个坑是改写要留痕。输入 Hook 如果改写了用户输入，一定要把原始输入和改写后的输入都记录下来。我踩过一次坑，输入 Hook 把用户的问题截断了，结果模型基于截断后的内容回答，用户觉得答非所问，我排查了半天才发现是 Hook 干的。后来我养成了习惯，所有 Hook 的输入输出都打日志，出问题直接看日志链路。

3.2 模型调用前 Hook：给模型递话之前先检查

模型调用前 Hook 在每次调用模型之前触发。注意是"每次"，不是"第一次"。Agent Loop 里模型会被调用很多次，每一次调用前这个 Hook 都会跑一遍。

这个 Hook 的典型用途是上下文管理。Agent 跑久了，上下文会越来越长，里面塞满了历史工具调用结果。模型调用前 Hook 可以在这里做上下文压缩、摘要、裁剪。比如把超过 N 轮的旧对话压缩成一段摘要，把重复的工具结果去重，把超大的工具返回值截断。

另一个用途是动态注入。根据当前状态，往 prompt 里动态塞一些信息。比如当前是第几轮、已经调用了哪些工具、还剩多少预算。这些信息模型自己是不知道的，得靠 Hook 注入。

这里有个参数计算的问题值得展开。上下文压缩的阈值怎么定？我的经验是：先算出模型的上下文窗口大小，留出 30% 给输出，再留出 20% 给系统 prompt 和工具定义，剩下的 50% 才是历史对话的预算。假设模型窗口是 128K，那历史对话预算大概是 64K。当历史对话超过 64K 的 80%，也就是 51K 左右，就该触发压缩了。留 20% 的缓冲是为了避免压缩本身产生的额外 token 把窗口撑爆。

注意：模型调用前 Hook 里不要做耗时的操作。它每次模型调用都会跑，如果里面有个 2 秒的数据库查询，跑 10 轮就是 20 秒的额外延迟。耗时操作应该放到异步任务里，Hook 里只读缓存结果。

3.3 工具调用前 Hook：最关键的拦截点

如果六种 Hook 里只能保留一种，我会保留工具调用前 Hook。因为工具调用是 Agent 唯一能产生真实副作用的环节，也是最容易出事的地方。

这个 Hook 的职责有三层。第一层是权限校验：这个工具当前该不该被调用？比如一个只读的 Agent，就不该调用写操作的工具。第二层是参数校验：参数类型对不对、范围合不合理、有没有必填项缺失。第三层是频率控制：同一个工具短时间内被调用太多次，要拦下来。

我在跨境电商那个项目里，事后加的就是这个 Hook。逻辑很简单：同一个工具在同一个会话里，连续调用超过 3 次就拦截，返回一个提示让模型换个思路。加上之后，刷屏问题再没出现过。

参数校验这块有个细节值得说。模型的参数是自然语言生成的，经常会出现类型不对的情况。比如工具定义要一个整数，模型给了个字符串 "5"。你可以在 Hook 里做类型转换，也可以直接拦截让模型重试。我的做法是：能安全转换的就转，转不了的就拦截。字符串 "5" 转整数 5 是安全的，但字符串 "abc" 转整数就没法转，这时候拦截比瞎猜好。

频率控制的计算也有讲究。简单的做法是滑动窗口计数：记录每次调用的时间戳，统计最近 60 秒内的调用次数，超过阈值就拦。但这样有个问题，如果阈值是 10 次/分钟，模型在第 59 秒调了 10 次，第 61 秒又能调 10 次，实际上 2 秒内调了 20 次。更稳的做法是令牌桶：桶容量 10，每秒补充 1 个令牌，调用消耗 1 个令牌，没令牌就拦。这样能平滑限流，避免突发。

3.4 工具调用后 Hook：结果进上下文之前先过一遍

工具调用后 Hook 在工具执行完、结果塞回上下文之前触发。它的职责是过滤、改写、补充工具结果。

过滤是最常见的用途。工具返回的结果可能包含不该给模型看的内容，比如内部 ID、调试信息、其他用户的数据。工具调用后 Hook 里把这些字段剥掉，只留模型需要的那部分。

改写也很重要。工具返回的原始格式可能对模型不友好。比如一个返回 JSON 的工具，模型读 JSON 不如读自然语言顺畅。Hook 里可以把 JSON 转成一段描述性文字，模型理解起来更准。

补充则是往结果里加一些元信息。比如告诉模型这个结果是缓存的、可能不是最新的，或者告诉模型这个结果被截断了、只显示了前 100 条。

这里有个坑我踩过：工具调用后 Hook 不要改变结果的结构。如果工具返回的是一个列表，Hook 处理后还应该是列表，不能变成字典。因为模型在后续推理里会依赖这个结构，结构一变，模型就懵了。我见过有人为了"美化"结果，把列表包了一层字典，结果模型后面所有引用都错了。

3.5 模型调用后 Hook：拿到模型输出先别急着用

模型调用后 Hook 在模型返回结果之后、Agent 决定下一步动作之前触发。它的职责是解析、校验、修正模型的输出。

模型输出最常见的问题是格式不对。你要求它返回 JSON，它给你返回一段带 markdown 代码块的 JSON。你要求它调用工具，它给你返回一段自然语言描述"我打算调用某某工具"。模型调用后 Hook 里要做格式解析和修正，把不规范输出转成规范结构。

另一个用途是幻觉检测。模型可能声称调用了某个工具，但实际上没有。或者模型引用了不存在的工具名。Hook 里可以校验模型提到的工具是否在注册表里，不在的话就拦截，让模型重新生成。

这里有个经验：模型调用后 Hook 的修正要保守。能自动修的自动修，修不了的就拦截重试，千万别硬猜。我见过有人写了个 Hook，模型输出格式不对时用正则硬提取，结果提取错了，把错误的数据传给了下游，比直接报错还糟糕。宁可让模型重试一次，也不要传错数据。

3.6 输出 Hook：最后一道防线

输出 Hook 在 Agent 生成最终回复、返回给用户之前触发。它是最后一道防线，也是合规审查最集中的地方。

输出 Hook 要做的事包括：敏感信息脱敏、内部字段剥离、措辞合规检查、格式统一。我在项目里用输出 Hook 做过一个"内部字段黑名单"，把所有内部字段名维护成一个列表，输出里出现这些字段就替换成占位符。这个列表是动态维护的，每次发现新的泄露就加进去。

输出 Hook 还有个容易被忽略的职责：兜底。如果 Agent Loop 因为异常提前终止，没有生成正常回复，输出 Hook 要负责生成一个体面的错误提示，而不是把堆栈信息直接吐给用户。

提示：输出 Hook 是唯一一个"必须执行"的 Hook。其他 Hook 在异常时可以被跳过，但输出 Hook 一定要保证执行，否则用户可能收到半成品或者错误信息。实现上可以用 try-finally 包住整个 Agent Loop，在 finally 里强制跑输出 Hook。

4. 两种范式：拦截式与增强式的设计取舍

4.1 拦截式范式：说不行就不行

拦截式范式的核心逻辑是"检查-通过/拒绝"。Hook 拿到数据，做判断，要么放行，要么拦截并返回一个错误或替代结果。

这种范式的优点是简单、可预测、易调试。每个 Hook 就是一个 if-else，逻辑清晰，出问题好定位。而且拦截式 Hook 通常是纯函数，没有副作用，测试起来也方便。

缺点是能力有限。它只能做"是/否"的判断，不能做"改造"。比如输入太长，拦截式只能拒绝，不能截断。工具参数错了，拦截式只能报错，不能修正。

拦截式范式适合什么场景？适合安全边界。权限校验、频率控制、敏感词过滤，这些场景要的就是明确的"行"或"不行"，不需要模糊地带。我在项目里把所有安全相关的 Hook 都用拦截式实现，因为安全问题上，宁可误拦，不可放过。

4.2 增强式范式：让数据变得更好用

增强式范式的核心逻辑是"接收-改造-输出"。Hook 拿到数据，做加工，输出一个更好的版本。

这种范式的优点是灵活、强大。它能做上下文压缩、格式转换、信息补充，这些都是拦截式做不到的。增强式 Hook 让 Agent 的整体能力上了一个台阶，因为它能在不改变模型的前提下，优化模型看到的一切。

缺点是复杂、难调试、有副作用风险。增强式 Hook 改了数据，一旦改错，问题会传导到下游，而且很难追溯。我踩过的最大的坑就是增强式 Hook 把工具结果改错了，模型基于错误结果推理，最后输出完全离谱，我排查了整整一天才定位到是 Hook 的问题。

增强式范式适合什么场景？适合体验优化。上下文压缩、结果改写、动态注入，这些场景要的是"让数据更好用"，而不是"拦住坏数据"。我在项目里把所有这些优化类的 Hook 都用增强式实现，但每一个都配了详细的日志和开关，出问题能快速关掉。

4.3 两种范式怎么选：一张决策表

实际项目里，两种范式往往是混用的。同一个 Agent 里，安全相关的 Hook 用拦截式，优化相关的 Hook 用增强式。关键是知道每个 Hook 该用哪种。

我的经验是：先拦截，后增强。项目初期只上拦截式 Hook，把安全边界守住。等系统稳定了，再逐步加增强式 Hook，而且每加一个都要有开关，能随时关掉。这样风险可控，出问题也能快速回滚。

4.4 范式混用时的顺序问题

两种范式混用时，Hook 的执行顺序很关键。总的原则是：拦截式在前，增强式在后。

为什么？因为拦截式是"守门"的，它要先把不合格的数据挡在外面。如果增强式先跑，它可能把一个本该被拦截的数据"改造"成了合格的样子，绕过了安全检查。这就好比安检之前先让你换衣服，换完衣服安检就查不出来了。

具体到六种 Hook 的顺序，我的建议是：

1. 输入 Hook：先拦截（敏感词、长度），后增强（意图预分类）
2. 模型调用前 Hook：先增强（上下文压缩、动态注入），因为这里没有拦截需求
3. 工具调用前 Hook：先拦截（权限、频率），后增强（参数修正）
4. 工具调用后 Hook：先增强（格式转换），后拦截（敏感字段过滤）
5. 模型调用后 Hook：先拦截（幻觉检测），后增强（格式修正）
6. 输出 Hook：先拦截（敏感信息），后增强（措辞优化）

注意工具调用后 Hook 和模型调用后 Hook 是"先增强后拦截"，这跟其他几个不一样。原因是这两个 Hook 的输入是模型或工具生成的原始数据，格式可能不规范，得先规整成标准格式，拦截逻辑才能正确判断。如果先拦截，可能因为格式问题误判。

5. 实操：从零搭一套 Hook 体系

5.1 环境准备与依赖安装

先把环境搭起来。DeepAgents 构建在 LangGraph 之上，所以核心依赖是这两个。

pip install deepagents langgraph

如果你要用到模型调用，还需要装对应的模型 SDK。这里以通用的方式演示，具体用哪家模型按你的实际情况来。

pip install langchain-core

装完之后验证一下版本，DeepAgents 和 LangGraph 的版本要匹配，不然 Hook 的接口可能对不上。

import deepagents import langgraph print(deepagents.__version__) print(langgraph.__version__)

注意：DeepAgents 迭代比较快，不同版本的 Hook 接口可能有差异。建议锁定版本，不要用 latest。我吃过一次亏，自动升级后 Hook 的签名变了，整个链路报错，排查了半天。

5.2 定义 Hook 的数据契约

在写 Hook 之前，先定义清楚数据契约。每个 Hook 接收什么、返回什么，要提前定好，不然写到后面会乱。

我一般用一个统一的 HookContext 对象来传递数据：

from dataclasses import dataclass, field from typing import Any, Optional @dataclass class HookContext: session_id: str turn: int user_input: str = "" model_input: list = field(default_factory=list) tool_name: str = "" tool_args: dict = field(default_factory=dict) tool_result: Any = None model_output: Any = None final_output: str = "" metadata: dict = field(default_factory=dict)

这个对象贯穿整个 Agent Loop，每个 Hook 从里面读自己需要的字段，写自己负责的字段。这样 Hook 之间解耦，加新 Hook 不用改老 Hook。

数据契约定好之后，还要定错误契约。Hook 执行失败时怎么办？我的做法是分两类：拦截式 Hook 失败时"失败即拦截"，也就是 Hook 本身报错，就当拦截处理，宁可拒绝不可放过；增强式 Hook 失败时"失败即跳过"，Hook 报错就跳过这个 Hook，用原始数据继续，保证主流程不中断。

5.3 实现拦截式 Hook：以工具调用前为例

工具调用前 Hook 是最典型的拦截式场景。下面是一个完整实现，包含权限校验、参数校验、频率控制三层。

import time from collections import defaultdict class ToolGuardHook: def __init__(self, allowed_tools, rate_limit=10, window=60): self.allowed_tools = set(allowed_tools) self.rate_limit = rate_limit self.window = window self.call_records = defaultdict(list) def __call__(self, ctx: HookContext) -> HookContext: # 第一层：权限校验 if ctx.tool_name not in self.allowed_tools: raise PermissionError( f"工具 {ctx.tool_name} 不在允许列表中" ) # 第二层：参数校验 required = self._get_required_args(ctx.tool_name) missing = required - set(ctx.tool_args.keys()) if missing: raise ValueError( f"工具 {ctx.tool_name} 缺少必填参数: {missing}" ) # 第三层：频率控制 now = time.time() records = self.call_records[ctx.tool_name] records = [t for t in records if now - t < self.window] if len(records) >= self.rate_limit: raise RuntimeError( f"工具 {ctx.tool_name} 调用过于频繁" ) records.append(now) self.call_records[ctx.tool_name] = records return ctx def _get_required_args(self, tool_name): # 从工具注册表里读必填参数，这里简化处理 return set()

这个 Hook 有三层校验，任何一层不过就抛异常。异常会被 Agent Loop 捕获，转成一个错误信息塞回上下文，让模型知道这次调用失败了，换个方式重试。

频率控制这里用的是滑动窗口，简单直接。如果你要更平滑的限流，可以换成令牌桶，前面讲过原理，这里不重复。

5.4 实现增强式 Hook：以上下文压缩为例

上下文压缩是典型的增强式场景。下面是一个基于轮数的压缩实现。

class ContextCompressHook: def __init__(self, max_turns=10, keep_recent=5): self.max_turns = max_turns self.keep_recent = keep_recent def __call__(self, ctx: HookContext) -> HookContext: messages = ctx.model_input if len(messages) <= self.max_turns: return ctx # 保留系统消息 system_msgs = [m for m in messages if m.get("role") == "system"] # 保留最近 N 轮 recent_msgs = messages[-self.keep_recent:] # 中间部分压缩成摘要 middle_msgs = messages[len(system_msgs):-self.keep_recent] summary = self._summarize(middle_msgs) ctx.model_input = system_msgs + [ {"role": "system", "content": f"历史摘要：{summary}"} ] + recent_msgs return ctx def _summarize(self, messages): # 实际项目里这里调模型做摘要，这里简化 return f"省略了 {len(messages)} 条历史消息"

这个 Hook 的逻辑是：系统消息永远保留，最近 5 轮永远保留，中间的部分压缩成一段摘要。这样既控制了上下文长度，又保住了最近的上下文和系统设定。

提示：摘要本身也要消耗 token，所以摘要不能太长。我的经验是摘要控制在原内容的 10% 以内。如果原内容 5000 token，摘要不超过 500 token。摘要太长就失去了压缩的意义。

5.5 把 Hook 挂到 Agent Loop 上

Hook 写好了，要挂到 Agent Loop 上。DeepAgents 的挂载方式是在创建 Agent 时传入 Hook 配置。

from deepagents import create_agent agent = create_agent( model="your-model", tools=[...], hooks={ "before_input": [InputSanitizeHook()], "before_model": [ContextCompressHook()], "before_tool": [ToolGuardHook(allowed_tools=[...])], "after_tool": [ToolResultFilterHook()], "after_model": [OutputValidateHook()], "before_output": [OutputSanitizeHook()], } )

挂载顺序就是列表里的顺序。同一个时机有多个 Hook 时，按列表顺序依次执行。前面讲过，拦截式在前，增强式在后，所以列表里拦截式 Hook 要排在前面。

挂载完之后，建议先跑一遍冒烟测试。构造几个典型场景：正常输入、超长输入、越权工具调用、工具报错，看每个 Hook 是否按预期触发。我一般会写一个测试脚本，把这几个场景跑一遍，确认 Hook 链路通了再上真实流量。

5.6 参数计算：几个关键阈值的确定方法

Hook 里有很多阈值参数，定得合不合理直接影响效果。这里把几个关键阈值的计算方法整理一下。

上下文压缩阈值：模型窗口 × 50%，再乘 80% 作为触发点。比如 128K 窗口，历史对话预算 64K，触发点 51K。

频率控制阈值：先统计正常情况下的调用频率，取 P99 值，再乘 1.5 作为阈值。比如正常 P99 是 6 次/分钟，阈值定 9 次/分钟。

工具结果截断长度：单个工具结果不超过上下文预算的 10%。比如 64K 预算，单个结果不超过 6.4K token。

重试次数上限：一般 3 次。超过 3 次还失败，说明不是偶发问题，继续重试没意义，直接走兜底。

这些阈值不是拍脑袋定的，都是基于实际数据算出来的。上线后还要持续观察，根据实际表现调整。我一般会在 Hook 里埋点，记录每次触发的阈值和实际值，跑一周后看分布，再决定要不要调。

6. 常见问题与排查技巧实录

6.1 Hook 不触发：先查挂载，再查条件

Hook 不触发是最常见的问题。排查顺序是：先确认 Hook 有没有挂上，再确认触发条件有没有满足。

挂载问题一般是配置写错了。比如时机名写错，before_tool写成before_tools，Hook 就挂不上。或者 Hook 列表传了个空列表，等于没挂。这些低级错误我犯过不止一次，后来养成了习惯，启动时打印一遍 Hook 配置，确认挂载正确。

条件问题一般是 Hook 内部的判断逻辑太严。比如频率控制 Hook，如果窗口设得太小，或者阈值设得太低，可能永远不触发。这时候要看 Hook 内部的日志，确认它有没有被执行到，执行到了有没有走到判断分支。

6.2 Hook 执行顺序错乱：检查列表顺序和异步

顺序错乱一般有两个原因。一是列表顺序写错了，拦截式排在了增强式后面。二是 Hook 里有异步操作，异步任务的完成顺序和启动顺序不一致。

第一个原因好解决，调整列表顺序就行。第二个原因要小心，如果 Hook 里有await，那它的执行顺序就不确定了。我的做法是：Hook 里尽量不用异步，必须用的话，用await串行执行，不要用asyncio.gather并发。

6.3 增强式 Hook 改坏数据：加开关、加日志、加回滚

增强式 Hook 改坏数据是最难排查的问题，因为问题会传导到下游，你看到的现象和根因隔了好几层。

我的应对策略是三条。第一，每个增强式 Hook 都有开关，出问题一键关掉，先恢复服务再排查。第二，Hook 的输入输出都打日志，出问题直接对比改前改后。第三，保留原始数据，Hook 改的是副本，原始数据不动，需要时可以回滚。

这三条里，我觉得最重要的是开关。线上出问题，第一优先级是恢复，不是排查。有开关就能快速恢复，没开关就只能回滚整个版本，代价大得多。

6.4 常见问题速查表

6.5 几个独家避坑技巧

第一个技巧：Hook 里不要做网络请求。网络请求慢且不稳定，放在 Hook 里会拖慢整个链路。需要外部数据的，提前查好放缓存，Hook 里只读缓存。

第二个技巧：Hook 的日志要带 session_id 和 turn。Agent Loop 是多轮次的，没有这两个字段，日志根本串不起来。我一开始没加，排查问题时对着一堆日志完全不知道哪条是哪轮的，后来加上之后清晰多了。

第三个技巧：新 Hook 先灰度。不要一上来就全量开，先对 1% 的流量开，观察一周，没问题再逐步放量。我见过有人新 Hook 直接全量，结果误拦截率 5%，影响了大量正常用户。

第四个技巧：Hook 的异常要分类。拦截式 Hook 抛的异常和增强式 Hook 抛的异常，处理方式不一样。拦截式的异常要转成用户可见的提示，增强式的异常要静默处理。建议定义两个异常基类，分别处理。

第五个技巧：定期 review Hook 列表。项目跑久了，Hook 会越加越多，有些可能已经没用了。定期 review 一遍，把没用的删掉，把能合并的合并。Hook 太多会拖慢链路，也会增加维护成本。

7. 关于 Hook 设计的一点个人体会

写了这么多，最后聊点设计层面的体会。

Hook 机制的本质，是在一个自主系统里嵌入人工控制点。Agent 越自主，控制点就越重要。很多人做 Agent 只关注怎么让它更聪明，却忽略了怎么让它更可控。但真正上生产的时候，可控性比聪明更重要。一个聪明但不可控的 Agent，没人敢用；一个不那么聪明但完全可控的 Agent，反而能落地。

六种 Hook 覆盖了 Agent Loop 的完整生命周期，两种范式提供了拦截和增强两种控制手段。这套体系的价值不在于它有多复杂，而在于它把"控制"这件事拆解成了可配置、可组合、可观测的模块。你可以按需启用，按需组合，出问题能定位，能回滚。

我在实际项目里的体会是：Hook 的设计要"克制"。不要为了 Hook 而 Hook，每个 Hook 都要有明确的职责和存在的理由。Hook 越多，链路越复杂，出问题的概率越大。我现在的习惯是，加 Hook 之前先问自己三个问题：这个问题能不能在别的地方解决？这个 Hook 的职责是不是单一的？这个 Hook 出问题了我能不能快速关掉？三个问题都过了，才动手写。

另外，Hook 的测试要跟主流程一样重视。我一般会给每个 Hook 写单元测试，覆盖正常、边界、异常三种情况。Hook 是控制点，控制点出问题，整个系统就失控了。这块的测试投入，怎么强调都不过分。

后续如果要做更细的控制，可以考虑把 Hook 和策略引擎结合。比如把拦截规则抽成配置，用策略引擎动态加载，这样改规则不用改代码，运营同学也能参与。这个方向我还在探索，有进展了再单独写一篇。