第10章钩子与中间件管线

Tue, 09 Jun 2026 00:00:00 +0800

10.1 问题引入

当一个 AI Agent 系统从原型走向生产，最棘手的需求往往不是核心推理能力本身，而是外围的「可定制性」：

企业安全团队希望在每次工具调用前检查是否符合合规策略，且无需修改 Agent 内核代码；
开发者希望在 LLM 返回结果后、工具实际执行前，注入一段额外的上下文信息；
运维工程师需要在会话开始时自动配置环境变量，在会话结束时清理临时资源；
插件系统需要让第三方扩展在不触碰主流程代码的前提下参与到工具调用的决策链中。

这些需求的共同特征是：在不修改 Agent 核心代码的情况下，拦截、修改、扩展其行为。

这正是「钩子（Hook）」系统要解决的问题。Claude Code 的 Hook 系统是一套完整的中间件管线（Middleware Pipeline），它在 Agent 生命周期的 26 个关键节点上提供了拦截点，支持四种执行器类型（Shell 命令、LLM 提示、Agent 验证器、HTTP 回调），并通过精密的匹配、优先级、权限聚合算法将多个钩子的结果合并为一个确定性决策。

从算法角度看，这里蕴含了几个经典问题：

事件匹配算法：如何将运行时上下文高效地路由到正确的钩子集合？
并发聚合算法：多个钩子并行执行后，如何将冲突的结果（允许/拒绝/询问）合并为一个最终决策？
责任链与优先级排序：多来源（用户配置、项目配置、策略配置、插件、会话）的钩子如何确定执行优先级？
安全性约束：如何保证钩子系统本身不成为安全漏洞的入口？

10.2 算法思想

10.2.1 事件驱动的生命周期模型

Claude Code 定义了 26 种钩子事件，覆盖 Agent 运行的完整生命周期。这些事件并非随意设置，而是遵循一个严格的时序模型：

SessionStart → Setup → [UserPromptSubmit →
 PreToolUse → (PermissionRequest) → 工具执行 →
 PostToolUse / PostToolUseFailure → (PermissionDenied) →
 ... → Stop / StopFailure] → SessionEnd

其中嵌套着子 Agent 的生命周期（SubagentStart / SubagentStop）、压缩事件（PreCompact / PostCompact）、文件监控事件（FileChanged）、以及团队协作事件（TeammateIdle、TaskCreated、TaskCompleted）等。

钩子 on Last Stand

第10章 钩子与中间件管线

10.1 问题引入

10.2 算法思想

10.2.1 事件驱动的生命周期模型

第10章钩子与中间件管线