Open-ClaudeCode Hooks 机制深度解析：7类事件钩子让你的 AI 工作流全自动化

Open-ClaudeCode Hooks 机制深度解析：7类事件钩子让你的 AI 工作流全自动化

【免费下载链接】Open-ClaudeCodeResearch archive of Claude Code source and runtime artifacts reconstructed from published npm source maps.项目地址: https://gitcode.com/gh_mirrors/op/Open-ClaudeCode

Open-ClaudeCode 是 Claude Code 源码与运行时产物的研究归档，其Hooks（事件钩子）机制是 AI 工作流自动化的核心能力：你只需编写简单的脚本或提示规则，就能在 AI 执行工具、提交提示、开始/结束会话等关键时刻自动介入——验证操作、拦截危险命令、注入上下文。本文将带你快速掌握 7 类事件钩子，从原理到实战，零门槛搭建全自动 AI 工作流。

一、Hooks 是什么：一句话看懂事件驱动自动化

可以把 Hooks 想象成"AI 工作流上的安检门"：每次 AI 要执行某个动作前或完成后，系统会自动触发你预设的钩子脚本，由你来决定——放行、拦截、还是补充信息。

它的核心特点：

• 🎯事件驱动：钩子只在特定事件发生时执行，平时零开销
• 🔌松耦合：钩子以独立脚本存在，不侵入 AI 主逻辑
• ⚙️两种实现方式：命令钩子（Command，跑确定性脚本）和提示钩子（Prompt，用 LLM 做上下文判断）

钩子事件的完整定义可以在src/entrypoints/sdk/coreTypes.ts的HOOK_EVENTS常量中找到，执行逻辑集中在src/utils/hooks.ts中。

二、7 类核心事件钩子一览表

💡 此外还有PreCompact（上下文压缩前）、SubagentStop（子代理停止时）等扩展事件，完整清单见src/entrypoints/sdk/coreTypes.ts。

三、两步写出你的第一个钩子

钩子配置写在.claude/settings.json中，结构非常直观：事件名 → 匹配规则（matcher）→ 钩子列表。

第 1 步：选择事件和匹配器。比如只监控文件写入类工具：

{ "PreToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "bash scripts/validate.sh" } ] } ] }

第 2 步：编写钩子脚本。脚本通过 stdin 收到 JSON 输入（含session_id、tool_name、tool_input等字段），通过退出码和 stdout 输出决策：

• 退出码0：放行，stdout 显示在会话中
• 退出码2：阻断，stderr 内容会反馈给 AI
• 还可以输出 JSON 决定permissionDecision: allow | deny | ask

对于需要"理解语义"的场景，推荐使用 Prompt 型钩子——直接用自然语言描述判断规则，无需写 bash：

{ "type": "prompt", "prompt": "Validate file write safety: system paths, credentials, path traversal. Return 'approve' or 'deny'." }

完整的事件用法与输入输出格式参考plugins/plugin-dev/skills/hook-development/SKILL.md。

四、零代码快捷方案：Hookify 插件

不想手写 JSON 配置？项目内置的Hookify 插件可以用对话方式创建钩子：

/hookify Warn me when I use rm -rf commands

它会自动分析你的需求，生成一个轻量的 markdown 规则文件（含 YAML frontmatter 和正则模式），无需重启，下一条工具调用立即生效。支持/hookify:list列出所有规则、随时启用/禁用。

⚠️ 同一图片仅引用一次，此处为强调说明：Hookify 位于plugins/hookify/，其命令入口见plugins/hookify/commands/hookify.md。

五、3 个实用自动化场景

1️⃣ PreToolUse 拦截危险命令在 Bash 工具执行前扫描输入，发现rm -rf /、误删生产库等高危操作立即阻断并告知 AI 原因——这是最经典的"AI 安全护栏"。

2️⃣ PostToolUse 自动质量检查每次代码编辑完成后自动触发 lint 或测试，结果反馈给 AI，让它立即修复问题，形成"改完即检"的闭环。

3️⃣ Stop 任务完整性验证AI 准备结束任务时，由钩子验证"测试跑过了吗？构建成功了吗？"，未达标则block并附理由，强制 AI 继续工作直到真正完成。

六、配置与部署要点

• 用户级钩子写在.claude/settings.json，事件名直接位于顶层（直接格式）
• 插件级钩子写在hooks/hooks.json，事件需包裹在"hooks": {...}中（包裹格式），并使用${CLAUDE_PLUGIN_ROOT}变量引用插件目录
• 企业部署可限制用户自定义钩子，示例配置见examples/settings/README.md及其中的settings-strict.json
• 钩子支持timeout字段防止脚本挂起拖慢会话

七、小结：从"提示 AI"到"规则驱动"

Hooks 机制的本质，是把你对 AI 的口头叮嘱变成确定性规则：危险操作永远被拦截、项目上下文永远被加载、任务完成永远有验证。掌握 7 类事件钩子后，你可以按需在 AI 工作流的每个关键节点埋下自动化节点——这正是 Open-ClaudeCode 从"聊天工具"进化为"可靠工程伙伴"的关键机制。

上手路径建议：先用/hookify创建一条拦截规则体验效果 → 再阅读plugins/plugin-dev/skills/hook-development/SKILL.md理解 Prompt 钩子 → 最后针对 PreToolUse / Stop 事件编写自己的命令钩子。

【免费下载链接】Open-ClaudeCodeResearch archive of Claude Code source and runtime artifacts reconstructed from published npm source maps.项目地址: https://gitcode.com/gh_mirrors/op/Open-ClaudeCode