【免费下载链接】learn-agent-architectureLearn AI agents from scratch.项目地址https://gitcode.com/gh_mirrors/aw/learn-agent-architecture点击查看免费下载learn-agent-architecture 是一个逐层拆解 AI Agent 外层架构Harness的开源教程项目本文重点讲它的第 4 章Hooks 钩子机制如何用 PreToolUse、PostToolUse 等生命周期事件在不改动 Agent 循环本体loop的前提下挂入日志、校验、通知和策略检查并附上可运行的测试与演示代码。整个仓库按八层、22 章组织每一章都建立在前一层之上。Hooks 处在最底层的Core Loop中回答的问题是扩展功能怎么挂进 loop 如果你只想看这一章sections/04-hooks/README.zh-CN.md 就是完整入口。为什么需要钩子别把扩展逻辑写进循环绝大多数 Agent 共享同一套控制流程调用模型 → 执行它要求的工具 → 把结果加回对话 → 再次调用模型。这个 loop 很小真正的工程量大都在它周围。如果没有扩展点每加入一种新行为比如命令里出现危险操作就拒绝、工具成功后记一条审计日志都得直接修改 loop甚至 fork 一份代码单独维护。loop 一改再改很快会变得又厚又难读。Hooks 的思路正好相反loop 保持精简只负责触发一组固定的命名事件生命周期事件新行为以 callback 的形式挂到事件上注册即用、移除即无loop 本身不知道也不关心具体挂了什么只调用统一的触发入口。这样扩展变成了接线而不是改心脏。核心机制PreToolUse 与 PostToolUse 拦截点一次工具调用在加了 Hooks 之后会经过这样的完整路径PreToolUse拦截点在权限门permission gate之前触发。钩子可以返回deny直接挡下调用也可以返回updated_args改写输入参数Permission gate权限门被钩子挡下的调用永远不会到达这里Run tool执行只有通过拦截和权限校验的调用才会真正执行PostToolUse观察点仅在工具调用成功之后触发适合做日志、通知、结果后处理。Hooks对象本质是一个事件名 → 回调列表的映射核心只有两个触发入口# sections/04-hooks/src/hooks.py def fire_pre(self, name, args): # PreToolUse可 block 或 rewrite def fire_post(self, name, args, result): # PostToolUse只观察而 sections/04-hooks/src/loop.py 中的_dispatch只多了两行调用——这就是最小侵入的具体含义blocked, args, msg hooks.fire_pre(name, args) # 4 · PreToolUse if blocked: return res(msg) # ... 权限门与工具执行 ... hooks.fire_post(name, args, out) # 4 · PostToolUse钩子能做什么、不能做什么这里有一条非常重要的设计原则也是新手最容易踩的坑钩子可以收紧权限结果但不应该放宽它。也就是说PreToolUse 钩子能挡下本该放行的调用deny、能改写参数但不能授予一次调用本不具备的权限。项目的实现里钩子只允许拒绝或修改绝不放行。在 Claude Code 等真实系统中还会用类似resolveHookPermissionDecision的机制把钩子的输出与规则型权限再对齐一次防止钩子意外绕过权限体系。项目的 demo 给了一个直观例子即使运行在bypassPermissions全放行模式下一个 PreToolUse 钩子依然能挡住rm -rf命令。权限门全开也没关系拦截点在它前面。Waterfall 模式另一种钩子扩展风格除了一个事件、一串回调的串行写法仓库还收录了另一种值得了解的风格——waterfall瀑布式钩子源码在 sections/04-hooks/src/waterfall.py多个钩子在同一个事件上排成一条链每个钩子拿到事件数据和一个next()回调不调用next()直接返回决策链到此为止决策归它所有调用next()把决定权交给下游拿到下游结果后再原样返回或做调整典型的包装器用法比如统一审计日志当多个钩子的结论不一致时按最严格者胜合并deny ask allow保证链上靠后的钩子无法把靠前的拒绝放宽掉。两种风格对比一下就很清楚维度标准 Hooks本项目主链路Waterfall 链运行位置进程内普通函数进程内普通函数多个钩子依次执行都可生效链式委托可中途接管决策返回形式结构化字典deny / updated_args类型化决策deny / ask / allow合并规则先拒绝者胜最严格者胜deny ask allow动手验证运行测试与演示第 4 章的代码在 sections/04-hooks/src/ 下承接第 3 章权限与沙箱并新增hooks.pyHooks对象与fire_pre/fire_post两个触发入口loop.py_dispatch在权限门前触发 PreToolUse、执行后触发 PostToolUsewaterfall.pywaterfall 钩子链与最严格者胜合并对照演示未接入_dispatchtest.py离线断言无需 API key、无网络即可运行demo.py真实模型演示需要配置ANTHROPIC_API_KEY。python sections/04-hooks/src/test.py # 离线检查无需 key uv run python sections/04-hooks/src/demo.py # 实时演示需要 key离线测试覆盖了三个关键行为钩子在bypassPermissions模式下依然挡下rm -rf被挡下的调用不会触发 PostToolUse放行的调用才会进入 PostToolUse。跑通这几条断言基本就理解了钩子的完整生命周期。常见坑钩子写错会怎样章节文档总结了六类典型故障模式这里挑新手最容易遇到的四个钩子绕过权限钩子试图放行一个已被规则拒绝的动作。对策把钩子输出与规则型权限对齐钩子只收紧不放宽Stop 类钩子无限循环停止钩子触发自我修正后又再次触发自己。对策追踪该钩子是否已在运行中慢速钩子拖死主循环钩子内部去执行很慢的外部任务。对策加超时诊断信息淹没结果比如写入文件后对整个项目跑 lint返回的文字比写入本身还多。对策只检查刚修改的那一个文件并对追加内容设上限。延伸阅读里还有一个很实用的模式写入后即时 lint。write 工具一返回钩子就对刚改的文件跑 linter把诊断信息直接塞进 tool result——模型下一轮就能顺手看到错误而不必等到下一次构建。因为诊断包在工具结果里不额外消耗一轮对话成本几乎为零。总结扩展 Agent 的正确姿势让 loop 暴露固定的生命周期事件把日志、校验、通知、策略检查挂到事件上而不是改 loopPreToolUse 在权限门前拦截或改写PostToolUse 在成功后观察结果钩子的权限边界是只收紧、不放宽需要多钩子协作决策时用 waterfall 链 最严格者胜deny ask allow。想继续往下学第 3 章 sections/03-permission-sandbox/README.zh-CN.md 讲权限门本身第 5 章 sections/05-planning-todos/README.zh-CN.md 则开始把可变状态挪上 Session两者都与本节的钩子机制紧密衔接。赞分享【免费下载链接】learn-agent-architectureLearn AI agents from scratch.项目地址https://gitcode.com/gh_mirrors/aw/learn-agent-architecture点击查看免费下载相关推荐learn-claude-code s04Hooks——如何把扩展逻辑挂在 Agent 循环上而不侵入循环learn claude code s04Hooks——如何把扩展逻辑挂在 Agent 循环上而不侵入循环 本篇技术文章基于 learn claude cod示例工程AI Agent人工智能Cline Hooks 系统实战指南文件钩子与运行时钩子拦截 Agent 全生命周期Cline Hooks 系统实战指南文件钩子与运行时钩子拦截 Agent 全生命周期 Cline 的钩子Hooks系统是拦截和增强自主编码代理行为的两大扩人工智能AI Agent代码智能体AI 应用开发工具MCP Clientslearn-claude-code s04 实战Hooks 机制——把扩展逻辑挂在 Agent 循环上而不是写进循环里learn claude code s04 实战Hooks 机制——把扩展逻辑挂在 Agent 循环上而不是写进循环里 在 learn claude cod示例工程AI Agent人工智能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考