看完你能带走:7 个挂点的完整说明、2 个可以直接照抄的实战配置、6 个最高频的翻车点,以及把规范随仓库共享给全队的方法。建议先收藏。 Hook 是什么:把记得变成必然团队规范落实难,难在它总是靠记性:规范写在文档里,靠人记得;写进 AGENTS.md,靠 AI “自觉”。而只要靠记性,就一定有漏网的时候。Hook 是另一种思路:在 ZCode 工作流程的固定节点上,自动执行你写好的脚本。它不经过 AI 的判断,也不依赖谁的记性——节点一到,脚本必跑。规范从口头约定变成机制保证。一轮对话里有哪些节点?看这张图: 七个挂点:一张表看懂ZCode 只支持七类事件,不多不少:事件触发时机典型用途SessionStart会话启动打印项目提醒、加载环境说明UserPromptSubmit你提交消息时向对话注入团队规范提醒PreToolUse工具执行前拦截危险操作(可拒绝)PermissionRequest弹出权限请求时定制审批策略PostToolUse工具执行后自动格式化、自动检查PostToolUseFailure工具执行失败后收集失败日志Stop一轮回答结束触发测试、生成收尾小结两个关键概念,配置前必须懂:matcher(匹配器):大小写敏感的正则表达式,决定这条 Hook 对不对这次操作生效。比如工具事件匹配的是工具名(Bash、Edit、Write、Agent等),Edit|Write表示只对编辑和写入触发;省略 matcher 则对所有操作生效。两种脚本类型:command型走 shell 执行字符串命令(注意它的超时单位是秒);process型直接调用可执行文件、参数数组传参、不走 shell(超时单位是毫秒,跨平台最稳)。️ 实战一:改完代码,自动检查最常用的场景:AI 每次用编辑/写入工具改了文件,自动跑一遍你的检查脚本(格式化、规范扫描、提示跑测试,都行)。完整配置模板:{hooks:{enabled:true,events:{PostToolUse:[{matcher:Edit|Write,hooks:[{type:process,command:D:/tools/check.cmd,args:[],timeoutMs:10000}]}]}}}放在用户级~/.zcode/cli/config.json(全项目生效)或工作区级.zcode/config.json(仅当前项目、可随 Git 共享)的hooks字段里。逐个说清:enabled: true:必须设。配置文件里的 Hook 默认是关闭的,忘了它,后面全白搭;matcher: Edit|Write:只对编辑、写入两类工具触发(大小写敏感);type: processargs:不走 shell 直接调用可执行文件,跨平台最稳;示例里的脚本路径是示意,换成你自己的;timeoutMs: 10000:10 秒超时。检查类脚本务必快,别拖慢每一次修改。配置怎么生效?记住退出码三个数:0 放行,2 拦截,其他非零 脚本执行出错(会记入日志)。检查类脚本检查通过就返回 0即可。️ 实战二:拦截危险命令PreToolUse 的价值在事前拦截:工具还没执行,你的脚本先过一遍。经典用法——AI 要执行 Bash 命令时,先检查有没有危险模式:{type:command,command:bash ${ZCODE_PROJECT_DIR}/.zcode/hooks/guard.sh,timeout:5}注意两个细节:${ZCODE_PROJECT_DIR}是内置模板变量,会被展开成项目路径,这样脚本写一份、各项目通用;timeout: 5在 command 型里的单位是秒(不是毫秒——这是最经典的翻车点之一)。检查脚本长这样(伪代码示意,输入字段以官方文档为准):#!/usr/bin/env bash# 从标准输入读取本次工具调用的信息# 命中危险模式(如递归删除) - exit 2,ZCode 将拒绝这次操作# 其余情况 - exit 0,放行拦截后,ZCode 会收到这次操作被拒绝并另做安排。用好了是保命符,用不好(误报率高)会很烦——所以拦截规则要从严设计,只拦真正危险的。 团队共享:让规范随仓库走把 Hook 配置和检查脚本放进工作区级配置(项目.zcode/config.json),随 Git 提交:队友拉取代码后,打开项目,规范就已经在场。新人不再需要入职先背规范——机制替你盯着。三个注意事项:工作区配置里同样要设enabled: true;脚本也要一起提交,否则队友那边只会报错;Team 里如果有人用不同操作系统,优先用process型(不走 shell,Windows/macOS/Linux 表现一致)。 6 个高频坑(官方文档都点名的那种)Hook 完全不触发:配置文件里的 Hook 默认关闭,enabled: true忘了设,后面全白搭——这是第一名的高频坑;事件名写错:只有七类事件,网上老文章里的Notification、SubagentStop等并不在支持之列;matcher 从不命中:大小写敏感,bash匹配不到Bash;写错的正则会静默失效;报 permission denied:脚本没有可执行位,改用解释器调用(如bash 脚本路径);动不动超时:command 型超时单位是秒、process 型是毫秒,混了就会被秒杀;指望 async 后台跑:它目前没有运行时效果,Hook 是同步执行的——耗时任务让脚本自行后台化。进阶玩法还有不少:脚本可以输出 JSON 向对话注入上下文、返回允许/询问/拒绝的决策、让 Stop 请求继续工作,此处不展开,以官方文档为准。 安全与克制脚本以你的身份运行:Hook 等于把一段自动化交给自己,写清楚再挂;同步执行,保持轻快:Hook 会阻塞流程,默认超时 60 秒;PreToolUse 的拦截会直接挡住操作,误报率高了寸步难行;第三方插件的 Hook 同样会执行:安装任何插件前,在设置 → 插件管理 → 插件详情里看一眼它注册了哪些 Hook。❓ 快问快答Q:Hook 和 AGENTS.md 什么关系?会冲突吗?不冲突,是互补:AGENTS.md 是告诉 AI 规范,靠模型理解遵守;Hook 是机制强制执行,不经过模型。规范写进 AGENTS.md,底线用 Hook 兜底,是最稳的组合。Q:Windows 上能用吗?能。但 command 型走 shell,POSIX 语法的脚本在 Windows 会失败;跨平台场景推荐 process 型,或提供多平台的包装脚本。Q:怎么知道 Hook 到底执行了没有?执行记录(触发、结果、耗时、错误信息预览)都会写进 ZCode 的日志;配置型 Hook 也可以直接翻配置文件的 hooks 块核对。Q:能让 Hook 自动改我的代码吗?技术上脚本里做什么都行,但建议克制:Hook 只做检查、提醒、拦截,把修改留给 AI 与你的确认流程。权限越大,误伤越多。 写在最后好的协作规范,从来不靠自觉。CI 流水线、代码评审、单元测试,本质上都是用机制代替记性。Hook 是同一思路在 AI 编程里的延伸:你把规范写成脚本,ZCode 负责让它在每个该出现的时刻必然出现。从今天的三个动作开始:挑一条最常被违反的规范、为它写一个十秒钟就能跑完的检查脚本、挂到对应的节点上。第一个 Hook 跑通的那天,你就再也回不去了。️ 声明:本文为个人使用经验总结,属第三方独立教程,非 ZCode 官方文档;ZCode名称及相关商标归其权利人所有;Hook 的配置字段与行为以你所用版本的官方文档为准。 你的团队里哪条规范最常被忘?评论区聊聊,我们一起把它变成 Hook。系列下一篇,写「自己动手写一个 MCP 服务器」。