Agent 循环的钩子：在哪儿插手，怎么插手

?先猜：想让 Agent 知道现在几点

1Agent 循环在哪些时刻停下来

回到开头的问题：不改 Agent 循环，怎么让它多做一件事？答案分两半。前一半是：Agent 循环自己会在几个固定时刻停下来，问一句“有没有插件要插手”。

Agent 循环干活时，会在下面这几个时刻停下来，问一句“有没有插件要插手”。这些时刻就叫钩子（hook）。标了黄色小字的，只在特定情况下才会经过。右边绿色的，是真的挂在上面的插件。

“停下来问一句”在代码里是什么样？拿第 00 章那个循环来看，第 1 个钩子就是开头多出来的两行：

while (true) {
  const 决定 = await 发出钩子('agent/pre-step', 这一步的消息, 默认处理)
  // 决定只有两种：{ kind: 'reject' } 或 { kind: 'enter', messages }
  if (决定.kind === 'reject') break        // reject：有插件拦下，这一步不走
  const 回复 = await ctx.llm.stream({ …, messages: [...会话, ...决定.messages] })  // enter：带上它的 messages 问模型
  …                                        // 往下和第 00 章一样
}

循环只喊一个名字 agent/pre-step，带上这一步的消息，再附一个默认处理：没有插件插手时，就由它交回 { kind: 'enter', messages }，带上这一步的消息进入这一步。谁挂在这个名字上，它不知道，也不用知道。（真实代码里，“发出钩子”叫 dispatch.waterfall。）

超时、重试、压缩……这些听起来像 Agent 循环的本职工作，其实都是挂在钩子上的插件。不装它们，循环照样能跑。

2插件怎么插手

答案的后一半：插件在自己的启动函数里，把一个处理函数注册到钩子的名字上。Agent 循环每次喊这个名字，就调用这个函数，听它的决定。

先看一个完整的插件：报时插件。它的样子和第 01 章的 bash 工具一模一样，依赖加启动函数：

export const name = 'time-context'
export const inject = ['agents', …]                 // 依赖
export function apply(ctx) {                        // 启动函数
  ctx.on('agent/pre-step', async (这一步, next) => {  // 注册：处理函数挂到这个名字上
    const 决定 = await next()
    if (决定.kind === 'reject') return 决定
    if (离上次报时不到 10 分钟) return 决定     // 默认十分钟最多报一次
    return { ...决定, messages: [...决定.messages, 现在几点] }  // 还是 enter，只是多了一条消息
  })
}

bash 把工具注册给工具服务，报时插件把处理函数注册给一个钩子，都是在启动函数里注册。所以规矩也一样：卸载报时插件，这个处理函数自动摘掉，循环照样跑，只是不再报时。

注意两样东西跑的时机不一样：

所以“现在几点”这种每一步都要重新算的东西，要写在处理函数里，不能写在 apply 里。写在 apply 里，就只在装上时算了一次。

再看处理函数本身：它拿到什么、能交回什么？这些不是插件自己说了算，而是调用它的那段代码定的。下面是 agent/pre-step 的契约。蓝色几行由 DSH 定，绿色一行由你定：

还有一个容易看错的地方：报时插件加的那条“现在几点”，在模型看来和你的话一样，都是 user 角色。区分它们靠每条消息上标的来源：你的话来源是 user，报时那条来源是 time-context。想判断“是不是用户亲口说的”，要看来源，不能看角色。

按这份契约，处理函数能做的就三种。左边是另一个插件的处理函数，右边把三种做法放在一起对照：

ctx.on('agent/pre-step', (step, next) => {
  if (会话已归档) return { kind: 'reject' }
  return next()
})

代码都是简化过的真实代码（中文是为了好读）。这里有两个独立的决定，别混在一起：

• 调不调 next()，决定后面的插件和默认处理跑不跑。
• 最后 return 什么，决定这一步进不进。

把所有写法摆在一起（以 agent/pre-step 为例）：

写插件时，你不知道同一个钩子上还有没有别的插件，也不需要知道：next() 一定能调。后面没有插件时，它调的就是循环自己的默认处理，返回 { kind: 'enter', messages }。所以默认先调 next()，只有要拦下时才不调。

注意，reject 和 enter 只是 agent/pre-step 这一个钩子的约定。每个钩子能交回什么，由喊它的那段代码定，所以取值各不相同。同样写 ctx.on，挂在不同的钩子上，能做的事完全不同：

取值不用背，记两条规律就够：有 next 的钩子，没意见时都写 return next()；要插手时交回什么，查这个钩子的类型声明，也就是喊它的那段代码写下的契约。

所以判断一个钩子能做什么，不能看名字猜，要看三处：它的类型声明、发出它的那行代码、调用方拿返回值做了什么。

3好几个插件同时插手，怎么办

上面两个插件，其实挂在同一个钩子上（“这一步要不要走”）。它们是不同的人写的，互相不知道对方存在。那 Agent 循环停在这一刻时，先问谁？

答案藏在 next() 里：next 指的“后面”，就是同一个钩子上的下一个插件；最后一个插件之后，是 Agent 循环自己的默认处理（交回 enter，带上这一步的消息）。所以它们排成一串：前一个调用 next()，才轮到后一个。谁都不用认识谁，各管各的事，不归自己管就 next()。

这一串的先后是怎么排的？同一个钩子上，先注册的排在外面，先被调用；默认处理永远在最里面。插件谁先启动看依赖（第 01 章），所以别指望“我一定排在谁前面”。真要排到最前，注册时加一个选项：ctx.on('agent/pre-step', 处理函数, { prepend: true })，它会插到现有处理函数的最前面。

点“下一个画面”，看这一串怎么一个个往里调用、再一个个把结果交回来。勾上“会话已归档”，看拦下时会怎样。

这一串排好以后，Agent 循环拿到最终的决定，才真正去问模型。回到开头的问题：报时就是这样加进去的。Agent 循环的代码，一行没改。

!一条规矩：不能偷偷改模型看到的东西

报时插件明明可以在“发给模型之前”把时间直接塞进请求，为什么要在“这一步开始前”往消息里加一条？

“往消息里加一条”有唯一的正确姿势：把它放进交回去的决定里，由 Agent 循环去记进日志。下面两种看起来也在“加”，其实都不算数：

• 改你读出来的历史：从会话里读出整段历史，在这个数组上 push 一条。那只是读出来的一份，改它什么都不会发生：日志里没有，模型也看不到。钩子传进来的那个数组也别原地改：生不生效要看调用时机，靠不住。
• 自己直接写日志：绕过决定、抢先写一条。万一后面的插件拒绝了这一步，日志里就多了一条本不该有的消息。

还有一个边界：卸载报时插件，以后不再加时间；但以前已经记进日志的时间消息还在，卸载不会抹掉历史。

所以“发给模型之前”这个钩子只许换模型、换参数，不许改消息。DSH 把这条规矩叫“模型看到的，必须记下来”。会话日志是怎么回事，下一章讲。

✓四道小题