第16篇：事件钩子——关键时刻自动触发

各位小伙伴，欢迎回来！今天咱们聊一个特别实用的功能——事件钩子。简单说，就是让 Hermes 在“关键时刻”自动帮你干活，不用你手动盯着。

什么是事件钩子？

想象一下：你正在跟 Hermes 聊天，突然它卡在一个工具调用循环里出不来了。或者，你想在每次对话开始时自动加载某个记忆。这些场景，事件钩子都能派上用场。

事件钩子就是给 Hermes 装上的“小闹钟”——当特定事件发生时，自动触发预设的动作。就像你设置手机闹钟一样，到点就响，不用你操心。

Hermes 一共有四套钩子系统：Gateway hooks（放在 ~/.hermes/hooks/ 里的 HOOK.yaml + handler.py，只在网关里跑）、Plugin hooks（插件里用 ctx.register_hook() 注册，CLI 和网关都能跑）、Shell hooks（在 profile 的 config.yaml 里用 hooks: 块指向 shell 脚本，CLI、网关以及 Desktop/TUI/dashboard 聊天都能跑），以及 Outbound webhooks（在 ~/.hermes/config.yaml 的 hooks.outbound: 列表里配置，把签名的生命周期事件推送到外部 HTTP 端点）。钩子回调出错时会被隔离并记录日志，不会把 agent 弄崩。

顺带说一句，钩子可不全是“只读观察”的：指令类钩子能改变流程，转换类钩子能替换内容，shell 的 pre_tool_call 钩子甚至能直接拦截或失败关闭。

硬停止：防止“死循环”的保险丝

新版文档里特别提到了一个实用场景：工具循环硬停止（Tool-loop hard stops）。

默认情况下，tool_loop_guardrails.hard_stop_enabled 是 false。这在交互式 CLI 里没问题——你能看到警告，自己手动干预。但在无人值守的网关模式下（比如 Telegram 机器人），如果 Hermes 陷入重复调用工具的循环，光有警告可不够。

这时候，你需要主动打开“保险丝”：

tool_loop_guardrails:
  hard_stop_enabled: true
  hard_stop_after:
    exact_failure: 5
    idempotent_no_progress: 5

配置好之后，如果连续 5 次完全相同的失败，或者 5 次“看似在干活但毫无进展”的调用，Hermes 就会自动刹车，避免浪费你的 API 额度。

钩子用在哪？

除了硬停止，事件钩子还能用在：

会话开始时自动加载上下文
收到特定关键词时触发特定技能
工具调用失败时自动重试或切换方案

另外，新版文档里还新增了一个观察者事件 agent_loop_stopped：当一个真正在运行的 agent 被中断时（比如网关的 _interrupt_and_clear_session，或者 TUI/desktop 的 session.interrupt）会立即触发，回调里能拿到 session_key、platform、reason、invalidation_reason 这些信息，方便你记录或告警。

写插件钩子的时候有个小细节值得留意：如果某个回调每次都因为同样的原因失败（通常是签名里写了个钩子根本不发的字段，比如把 tool_name/args 写成了 tool_data），Hermes 只会在 WARNING 级别提醒你一次，消息里还会列出这个钩子实际提供的字段；之后重复的相同错误就降到 DEBUG 了，免得一个写错的插件把日志刷爆。

小贴士

如果你是跑在 Docker 里的网关模式，记得检查 docker logs 里的输出。新版镜像用 s6-overlay 做进程守护，网关崩了会自动重启，日志里会有一条面包屑提示，方便你确认钩子是否生效。

总结

事件钩子就是给 Hermes 装上的“条件反射”——在关键时刻自动响应，不用你时刻盯着。特别是硬停止功能，强烈建议网关用户开启，给无人值守的机器人上一道保险。

下期见！