视频 08 来源笔记：Hooks 生命周期与质量门禁

来源元信息

• 讲者：小单说AI
• Bilibili：BV1acM567EES
• 本地字幕：从零实现自己的agent第八期：hooks.ai-zh.srt
• 字幕覆盖：00:00:00–00:07:30
• 对照材料：本期仓库无独立文本稿；已核对 ppt/第八期-hooks生命周期.html
• 对应代码：step12_hooks.py、tests/test_step12_hooks.py

按时间顺序的主题窗口

[00:00:00–00:00:45] 主流程之外的横切问题

文件能否写、命令是否危险、工具输出是否过长、日志是否记录，都很重要，却不属于 Agent 推理主干。Hooks 用统一扩展点承接这些问题。

[00:00:45–00:01:26] Hook 是流程挂点

Hook 不取代主流程，而是在关键边界挂规则或动作。它可以记录、改写、询问、拒绝或阻断。

[00:01:26–00:02:18] 为什么 Agent 更需要 Hook

聊天模型只输出文本，Agent 会产生副作用。视频用地铁安检说明：不能只相信模型承诺谨慎，动作必须通过独立检查。

[00:02:18–00:02:58] 三个结构角色

Hook 是规则卡，Registry 按事件管理和依序执行规则，Runner 在生命周期边界触发 Registry。规则与主循环解耦后更容易测试和组合。

[00:02:58–00:03:43] 五个常见事件

before_turn 注入或限流，after_turn 记录耗时和输出，before_tool_call 做权限检查，after_tool_call 审计和截断，on_stop 做最终质量门禁。

[00:03:43–00:04:25] Before 与 After 的差别

Before 在副作用前，能阻止危险动作；After 在动作后，只能观察、整理或为后续补偿提供信息。审计 Hook 不能当预防性权限控制。

[00:04:25–00:05:10] 一张 Hook 卡的四层

Event 决定何时触发，Matcher 决定是否适用，Handler 执行检查，Decision 返回允许、拒绝、询问或阻断。这个结构让决策可记录、可测试。

[00:05:10–00:06:03] 代码中的五个 Hook

固定代码实现模型日志、工具审计、调用前策略、过长输出截断和停止质量门禁，并统一注册到 HookRegistry。

[00:06:03–00:06:54] 写文件演示

Agent 生成天气 Skill 并写到桌面，控制台显示模型日志与工具审计，审计 JSONL 也保存调用记录。演示重点是同一主循环可以并行获得多种横切能力。

[00:06:54–00:07:30] 复盘

记住 Hook、Registry、Runner 三个角色，以及 Event、Matcher、Handler、Decision 四层结构。下一步是把 Hook 事件与运行轨迹、评估指标连接起来。

主教学论点

Hooks 把权限、安全、审计、输出整形和质量门禁从 Agent Loop 中分离，并放到副作用发生前后与结束边界。它让 Harness 的规则不依赖模型自觉。

生命周期轨道

before_turn
  → before_model / model / after_model
  → before_tool_call / tool / after_tool_call
  → ... repeat ...
  → on_stop
  → after_turn

每个事件都应带 run_id、turn_id、事件序号、时间、调用对象、脱敏输入输出和 Decision，才能在 Web SSE 与离线评估中重建轨迹。

Decision 语义

• allow：继续，不修改主流程。
• deny：拒绝该动作，并把原因返回给 Agent。
• ask：暂停，等待用户或管理员批准。
• block：阻止结束或当前阶段，要求继续修正。

Decision 要有明确的默认策略。权限与安全检查应失败关闭，非关键日志 Hook 可失败开放。

术语与纠正

• 自动字幕中的 “hook 鸡肋 / 户口规则卡” 均指 Hook 基类或 Hook 规则。
• 视频口述五个位置；固定 step12_hooks.py 的 Hook 基类还覆盖模型调用前后等更多事件。
• “after 不能拦截”是针对已经发生的副作用；After 仍可阻止后续流程或触发补偿。

需要工程限定的说法

• Hook 执行顺序会影响结果，Registry 必须有稳定顺序和短路语义。
• Hook 自身也会失败或超时，必须定义故障策略。
• 仅靠字符串匹配危险命令容易绕过，应结合结构化参数、路径解析和沙箱。
• 输出截断要保留长度、哈希或产物引用，否则会破坏可追溯性。
• Stop Hook 不能无限打回；固定代码只允许有限提醒，生产系统还需预算和人工升级。

与评估的连接

Hook 产生的事件是轨迹评估的原始材料：可比较工具选择、参数、错误恢复、成本、延迟与最终产物。Verifier 可以在 on_stop 或离线评估中检查证据，但不能与生成 Agent 共用未经隔离的判断。

来源映射

• CAE：step12_hooks.py、doc/step12_hooks.md、tests/test_step12_hooks.py。
• 《深入理解 AI Agent》：第 6 章自动评估、指标和 LLM-as-a-Judge；第 8 章运行轨迹与验证发布闭环。
• 必做实验：chapter8/trajectory-verifier、chapter6/agent-cost-analysis。
• Mini Emperor：AgentEvent 已提供运行事件；review.py 的 Verifier 与 skills.py 的能力策略可进入 Hook Pipeline，完整 Hook 接口是正文扩展。
• 进入正文：book/08-Hooks与评估.md。

内容差异与待核对

• 本期没有仓库 bilibili-transcripts/08-*.txt，专有名词采用 SRT、PPT、固定代码和测试交叉确认。
• PPT 另有“安全边界、三个误区”，比视频口述更明确：Hook 不是 Tool、不是系统提示，也不是越多越好。
• 固定代码注释声称与某产品结构“完全对齐”属于实现作者的说明；课程应以官方 Hook 文档核对具体事件名和返回 Schema。