实现篇第9章 在关键时刻插一句话——Hooks ​

小A引导工具胶囊沿主路径穿过决策闸门和变形滚轮,老Z在旁路记录时掉落一颗珠子,但主路径仍继续运行。

本章导读: 实现篇扩展第 1 章。mini-agent 目前只有 BeforeToolCall 这一条审批缝。这一章沿它推演一个完整的生命周期 hook 体系:不写进 src,而是讲清接口长什么样、失败语义怎么定、测试怎么设计。前提是先确认需求,再动手。

小A的 Agent 跑了一下午,他盯着日志,忽然问老Z:“我想在每次工具调用前记一笔账、每轮结束打一条状态,还要在 Agent 开始和结束时各做点清理。现在的 BeforeToolCall 只能拦工具,其他时刻我什么都干不了。”

“你想加的是生命周期 hooks。”老Z说,“但先别急着写。先回答三个问题:这些时刻谁需要可观察?失败时该中止还是忽略?要不要让某个 hook 改写主路径?”

小A:“这三个问题为什么要在写代码前答?”

“因为它们的答案决定接口的形状。”老Z说,“mini-agent 现在只有一条 BeforeToolCall(见 types.ts),签名是 (call: ToolCall) => Promise<{approved: boolean; reason?: string}>,它有返回值,因为它要决定主路径走不走。你想要的记账和打状态不决定走不走,只负责‘看见’。要是把记账塞进 BeforeToolCall,返回值 approved 就被两件事共用:一是审批决策,二是‘记账记完了吗’。两类需求挤一个返回值,迟早有人为了记账的副作用去改审批逻辑的返回值,接口就从这里开始被腐蚀。所以动手前先分清:哪些时刻要‘看见’,哪些时刻要‘决定’。”

先分清三类 Hook ​

概念篇 第11章 在动作发生前插一句话——Hooks 把 Hook 分成三类,实现时要先决定每一类落在哪:

  • 订阅者:只观察,不改主路径。日志、指标、审计属于这类。
  • 拦截器:能允许、拒绝或改写动作。BeforeToolCall 属于这类。
  • 转换器:改写输入但不决定是否继续。上下文转换属于这类。

“这三类的失败语义完全不同。”老Z说,“订阅者抛错的影响取决于投递策略,拦截器抛错可能让整个 turn 失败,转换器抛错会让请求带着错误上下文发出去。设计接口之前先分类,不然你会在一个接口里混进三种失败语义。”

把三类按几个维度并排:

类别 作用 返回什么 失败语义 放在哪 例
订阅者 观察,不改主路径 不返回结果 吞掉并记录 旁路 日志、指标、审计
拦截器 允许/拒绝/改写动作 决策结果 向上传播 主路径 BeforeToolCall
转换器 改写输入,不决定是否继续 改写后的输入 请求带错误上下文 主路径 上下文转换

“注意拦截器和转换器都在主路径上,返回值却不同:拦截器给出‘走不走’,转换器给出‘变成什么样’。订阅者唯一的产出是副作用,所以它的失败只能影响自己。这张表就是这一章的骨架,后面所有设计都在填这张表的格子。”

小A:“mini-agent 现在的这条缝,算三类里的哪一类?”

“只有一条,而且是拦截器。”老Z说,“BeforeToolCall 被 runAgent 在每个工具执行前调用(见 agent.ts 的 options.beforeToolCall?.(call)),返回值直接决定工具跑不跑:!approval.approved 就 continue 跳过执行。它的失败还会向上传播,测试里有个用例叫 approval hook failures close every persisted call before rethrowing(见 tool-failure-session.test.ts),hook 抛错时,当前 call 记成 'tool approval failed',后面的 call 记成 'not executed after an earlier failure',然后错误原样抛给调用方。出错就停,没跑完的 call 全部标成失败闭环,这就是拦截器的失败语义。你要的记账 hook 不能走这条路,记账失败不该让整个回合挂掉。”

设计一套最小生命周期 hooks ​

小A的需求(记账、打状态、清理)全是订阅者。老Z沿 BeforeToolCall 的模式推演了一套接口:

ts
// 设计草图:生命周期 hooks(未进 src,先确认需求)
export interface TurnHooks {
  onTurnStart?(context: { user: string }): Promise<void> | void;
  onBeforeToolCall?(call: { id: string; name: string; input: unknown }): Promise<void> | void;
  onAfterToolCall?(result: { callId: string; isError: boolean }): Promise<void> | void;
  onTurnEnd?(result: { stopReason: "complete" | "max_turns" | "aborted" }): Promise<void> | void;
}

“注意两点。”老Z说,“第一,每个方法都是可选的,不需要全部实现;第二,它们都接收最小上下文,不接收整个内部状态。订阅者拿到的信息越少,越不会动改主路径的念头。”

把这四个方法贴到 runAgent 的循环上,看它们在哪个时刻触发:

runAgent 一轮的执行顺序(mini-agent 现循环 + 推演 hook 触发点)

  onTurnStart({ user })                  ← 记录本轮开始
        │
        ▼
  client.stream(...) ──► 收集 text / tool_call
        │
        ▼
  for each call:
    BeforeToolCall(call) ──► approved? ──否──► 记 tool error,跳过
        │ 是
    onBeforeToolCall(call)               ← 记录"这次调用即将发生"
        │
        ▼
    tool.execute(...)
        │
    onAfterToolCall({ callId, isError }) ← 记录调用结果
        │
        ▼
  onTurnEnd({ stopReason })              ← complete / max_turns / aborted

“注意这个图里有一半是虚线。”老Z说,“mini-agent 的循环现在只调 options.beforeToolCall?.(call),四个新 hook 一个都没接,这张图是推演的接线图,不是已实现行为。画它的意义是让你看见:每个 hook 都钉在一个明确的时刻,onBeforeToolCall 必须落在拦截器决策之后、工具执行之前,onTurnEnd 在停止判定之后。时刻错了,订阅者记的就是假账。”

小A试着往大了要:“最小上下文怎么定?onTurnEnd 给它整个 messages 数组行不行?”

“能跑,但后患大。”老Z说,“整个 messages 是 runAgent 的内部状态,带着所有 user/assistant/tool 消息,包括还没 trim 的原始上下文。订阅者拿到它,就难免动‘我来改一条消息’或‘我根据历史做个决策’的心思。一旦订阅者开始改 messages,它就不再是订阅者,而是一个没定义失败语义的转换器。给订阅者的上下文,应该刚好够记账,不够干预。onTurnEnd 只给 { stopReason } 就够:它知道这轮是 complete 还是 max_turns,不需要知道之前调了哪些工具。这与 mini-agent 给 ToolResult 的设计一致:工具拿到的 input 是模型给的参数,不是整个循环状态(见 tools.ts 里 execute(input, signal))。接口收窄,挡的是未来的越界。”

小A:“onBeforeToolCall 和现有的 BeforeToolCall 什么关系?”

“分工不同。”老Z说,“BeforeToolCall 是拦截器,返回 { approved, reason } 决定是否放行;onBeforeToolCall 是订阅者,只记录,不返回结果。一个在主路径上,一个在旁路上。把日志逻辑塞进 BeforeToolCall,等于把旁路观察变成主路径阻塞点,就是概念篇讲过的‘带时序约束的观察者’陷阱,在实现里会拖慢整个循环。”

小A:“hook 要不要也接收 AbortSignal?Tool.execute 不是有一份吗?万一它跑一半,用户按了 Ctrl-C。”

“这是推演阶段最容易多给的一个参数。”老Z说,“runAgent 到处检查 signal,Tool.execute 也接收它,但那是为了中止一个可能跑很久的副作用。订阅者只记账的话,几毫秒就返回了,给它 signal 只是塞一个用不上的东西;它要做网络上报,超时重试是它自己的事,不该由循环替它解决。参数不是越多越稳,‘有调用方、有语义’才算数。真遇到‘订阅者可能卡住’的证据再回头加,那才是‘被证明需要的时刻’。”

小A:“同一个工具调用,onBeforeToolCall 和 BeforeToolCall 谁先跑?”

“BeforeToolCall 先跑,它决定放不放行;放行了才轮到工具执行。”老Z说,“看 agent.ts 的顺序:先 options.beforeToolCall?.(call) 拿到 approval,!approval.approved 就 continue 跳过;放行了才 tool.execute。要是 onBeforeToolCall 抢在前面,它会先记一笔‘即将调用 bash’,然后 bash 被 denyBashByDefault 拒绝,日志和实际就对不上。顺序要写进注释,别靠后人猜。”

本章其余小节为付费内容

登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。