企业官网建设流程全解析

💡 看完你能带走:7 个挂点的完整说明、2 个可以直接照抄的实战配置、6 个最高频的翻车点,以及把规范随仓库共享给全队的方法。建议先收藏。

🪝 Hook 是什么:把"记得"变成"必然"

团队规范落实难,难在它总是靠记性:规范写在文档里,靠人记得;写进 AGENTS.md,靠 AI “自觉”。而只要靠记性,就一定有漏网的时候。

Hook 是另一种思路:在 ZCode 工作流程的固定节点上,自动执行你写好的脚本。它不经过 AI 的判断,也不依赖谁的记性——节点一到,脚本必跑。规范从"口头约定"变成"机制保证"。

一轮对话里有哪些节点?看这张图:

📍 七个挂点:一张表看懂

ZCode 只支持七类事件,不多不少:

两个关键概念,配置前必须懂:

• 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: "process"+args:不走 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 个高频坑(官方文档都点名的那种)

1. Hook 完全不触发:配置文件里的 Hook 默认关闭,enabled: true忘了设,后面全白搭——这是第一名的高频坑;
2. 事件名写错:只有七类事件,网上老文章里的Notification、SubagentStop等并不在支持之列;
3. matcher 从不命中:大小写敏感,"bash"匹配不到Bash;写错的正则会静默失效;
4. 报 permission denied:脚本没有可执行位,改用解释器调用(如bash 脚本路径);
5. 动不动超时:command 型超时单位是秒、process 型是毫秒,混了就会被秒杀;
6. 指望 async 后台跑:它目前没有运行时效果,Hook 是同步执行的——耗时任务让脚本自行后台化。

进阶玩法还有不少:脚本可以输出 JSON 向对话注入上下文、返回"允许/询问/拒绝"的决策、让 Stop 请求继续工作,此处不展开,以官方文档为准。

🔒 安全与克制

1. 脚本以你的身份运行:Hook 等于把一段自动化交给自己,写清楚再挂;
2. 同步执行,保持轻快:Hook 会阻塞流程,默认超时 60 秒;PreToolUse 的拦截会直接挡住操作,误报率高了寸步难行;
3. 第三方插件的 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 服务器」。