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

这篇讲的是：给智能体装上“门铃”——在它启动、干活、结束等关键时刻，自动触发你预设的脚本动作。

钩子是什么？先打个比方

想象你家请了个管家（智能体）。你不想一直盯着他干活，于是装了几个“感应器”：他出门时响铃、做完饭时响铃、打扫完房间也响铃。每个铃响了，你都可以安排一个“自动反应”——比如他出门时自动锁门。

Hermes 的事件钩子（Event Hooks）就是干这个的。它分四种，但最常用、最好上手的是“Gateway 钩子”——我们今天就重点玩它。

所有钩子都是非阻塞的：就算脚本报错，也只是记个日志，绝不会把智能体搞崩溃。

第1步：认识钩子目录

每个钩子是一个文件夹，放在 ~/.hermes/hooks/ 下，里面必须有两个文件：

~/.hermes/hooks/
└── my-hook/
    ├── HOOK.yaml      # 声明监听哪些事件
    └── handler.py     # 事件触发后执行的Python代码

HOOK.yaml 长这样：

name: my-hook
description: 记录所有智能体活动
events:
  - agent:start
  - agent:end
  - agent:step

handler.py 长这样（核心是 handle 函数）：

import json
from datetime import datetime
from pathlib import Path

LOG_FILE = Path.home() / ".hermes" / "hooks" / "my-hook" / "activity.log"

async def handle(event_type: str, context: dict):
    entry = {
        "timestamp": datetime.now().isoformat(),
        "event": event_type,
        **context,
    }
    with open(LOG_FILE, "a") as f:
        f.write(json.dumps(entry) + "\n")

三条铁律：

函数必须叫 handle
接收两个参数：event_type（事件名）和 context（事件详情）
写成 async def 或普通 def 都行

第2步：挑你想监听的事件

常用事件一览（节选）：

事件	什么时候触发
`gateway:startup`	网关启动时
`session:start`	新会话创建时
`agent:start`	智能体开始处理消息
`agent:step`	智能体每执行一步工具调用
`agent:end`	智能体处理完毕
`command:*`	任何斜杠命令被使用（`*` 是通配符）

第3步：写一个“超时预警”钩子

假设你希望：智能体干活超过 10 步时，自动给你发 Telegram 消息。

HOOK.yaml：

name: long-task-alert
description: 智能体步骤过多时提醒我
events:
  - agent:step

handler.py：

import os
import httpx

THRESHOLD = 10
BOT_TOKEN = os.getenv("TELEGRAM_BOT_TOKEN")
CHAT_ID = os.getenv("TELEGRAM_HOME_CHANNEL")

async def handle(event_type: str, context: dict):
    iteration = context.get("iteration", 0)
    if iteration == THRESHOLD and BOT_TOKEN and CHAT_ID:
        tools = ", ".join(context.get("tool_names", []))
        text = f"⚠️ 智能体已运行 {iteration} 步。最近工具: {tools}"
        async with httpx.AsyncClient() as client:
            await client.post(
                f"https://api.telegram.org/bot{BOT_TOKEN}/sendMessage",
                json={"chat_id": CHAT_ID, "text": text},
            )

第4步：进阶玩法——BOOT.md 启动清单

社区很流行的一个套路：在 ~/.hermes/BOOT.md 写一份“开机检查清单”，让智能体每次网关启动时自动执行一遍。

BOOT.md 内容示例：

# 启动清单
1. 运行 `hermes cron list`，检查昨晚有没有定时任务失败。
2. 如果有失败，汇总发到 Discord #ops。
3. 检查 /opt/app/deploy.log 最近24小时有没有 ERROR。
4. 如果一切正常，只回复 `[SILENT]`（表示无需发消息）。

钩子配置：

# HOOK.yaml
name: boot-md
description: 网关启动时执行 BOOT.md 清单
events:
  - gateway:startup

handler.py 核心逻辑： 在 gateway:startup 事件触发时，启动一个一次性智能体，把 BOOT.md 内容作为指令喂给它，让它执行并汇报。

小结

事件钩子 = 给智能体装“感应器”，在关键时刻自动触发脚本。新手建议从 Gateway 钩子入手，先监听 agent:step 或 command:* 练手，再逐步尝试 BOOT.md 这类高级玩法。

下篇预告： 第17篇——插件系统：像装 App 一样扩展智能体能力。