Hooks系统完整指南：自动化工作流的终极武器

Hooks系统完整指南：自动化工作流的终极武器 Hooks系统完整指南：自动化工作流的终极武器 Modified June 10 Q15: 如何处理Windows/macOS/Linux兼容性？ ⠀ Code block Plain Text import platform system = platform.system() if system == 'Windows': Windows特定代码 elif system == 'Darwin': macOS macOS特定代码 else: Linux Linux特定代码 ⠀ 高级问题 ⠀ Q16: Hook可以修改Claude的输出吗？ ⠀ 不能直接修改。但可以： • PostToolUse后修改文件内容 • UserPromptSubmit修改用户输入 ⠀ Q17: 多个Hook的执行顺序是什么？ ⠀ 按配置文件中的顺序依次执行。 ⠀ Q18: Hook可以调用Claude API吗？ ⠀ 可以，但要注意： • 会消耗额外Token • 可能导致无限循环 • 建议设置调用限制 ⠀ Q19: 如何在团队中共享Hook配置？ ⠀ 将 .claude/ 目录加入Git版本控制： Code block Plain Text git add .claude/settings.json git add .claude/hooks/ git commit m "Add Claude Code hooks" ⠀ Q20: Hook有性能影响吗？ ⠀ 有一定影响： • 每次工具调用都会触发Hook • 复杂脚本会增加延迟 • 建议优化脚本性能，设置合理timeout 附录A：配置速查表 ⠀ Hook类型速查 ⠀ Hook类型 触发时机 输入格式 输出格式 可阻止 重要 UserPromptSubmit 用户输入后 JSON 文本（注入上下文） V PreToolUse 工具调用前 JSON JSON决策 V ⭐ PostToolUse 工具调用后 JSON 无 X ⭐ Notification 通知发送时 JSON 无 X SessionStart 会话开始 无 无 X SessionEnd 会话结束 无 无 X Stop AI停止 JSON 无 X SubagentStart 🆕 子代理启动 JSON 无 X SubagentStop 🆕 子代理停止 JSON 无 X PermissionRequest 🆕 权限请求 JSON JSON决策 V PreCompact 🆕 上下文压缩前 JSON 无 X ConfigChange 🆕 配置变更 JSON 无 X TeammateIdle 🆕 队友空闲 JSON 无 X WorktreeCreate 工作树创建 JSON 无 X WorktreeRemove 工作树删除 JSON 无 X StopFailure 🆕 API异常停止 JSON 无 X PostCompact 🆕 上下文压缩后 JSON 无 X InstructionsLoaded 🆕 指令文件加载 JSON 无 X Elicitation 🆕 MCP请求输入 JSON 无 X ElicitationResult 🆕 MCP输入完成 JSON 无 X ⠀ 常用工具名速查 ⠀ 工具名 功能 常用Hook 重要 Write 写入文件 PostToolUse格式化 ⭐ Edit 编辑文件 PostToolUse备份 Read 读取文件 PreToolUse权限控制 Bash 执行命令 PreToolUse危险命令拦截 ⭐ Glob 文件搜索 • Grep 内容搜索 • WebSearch 网络搜索 • ⠀ Decision值速查 ⠀ PreToolUse 新版API（hookSpecificOutput.permissionDecision，推荐）： ⠀ 值 含义 工具执行 重要 "allow" 允许，绕过权限系统 V ⭐ "deny" 拒绝，原因反馈给Claude X ⭐ "ask" 暂停，询问用户 ? 无输出 默认允许 V ⠀ PreToolUse 旧版API（decision，已废弃但仍支持）： ⠀ 旧版值 等同于新版 "approve" "allow" "block" "deny" ⠀ PostToolUse / UserPromptSubmit： ⠀ 值 含义 "block" 阻止/提供反馈 无输出 默认允许 附录B：完整脚本模板 ⠀ Python脚本模板 ⠀ Code block Plain Text !/usr/bin/env python3 """ Hook名称 功能描述 """ import sys import json def main(): 读取输入 try: input data = json.loads(sys.stdin.read()) except json.JSONDecodeError: sys.exit(0) tool name = input data.get('tool name', '') tool input = input data.get('tool input', {}) 你的逻辑 ... 输出到Claude Code界面 print("信息", file=sys.stderr) 如果是PreToolUse，输出决策 print(json.dumps({"decision": "allow"})) if name == ' main ': main() ⠀ Bash脚本模板 ⠀ Code block Plain Text !/bin/bash Hook名称 功能描述 读取stdin input json=$(cat) 使用Python解析JSON tool name=$(echo "$input json" | python3 c "import sys,json; print(json.load(sys.stdin).get('tool name',''))") 你的逻辑 ... 输出日志 echo "信息" &2 exit 0 附录C：参考资源 ⠀ Q15: 如何处理Windows/macOS/Linux兼容性？ ⠀ ⠀ 高级问题 ⠀ Q16: Hook可以修改Claude的输出吗？ ⠀ 不能直接修改。但可以： • PostToolUse后修改文件内容 • UserPromptSubmit修改用户输入 ⠀ Q17: 多个Hook的执行顺序是什么？ ⠀ 按配置文件中的顺序依次执行。 ⠀ Q18: Hook可以调用Claude API吗？ ⠀ 可以，但要注意： • 会消耗额外Token • 可能导致无限循环 • 建议设置调用限制 ⠀ Q19: 如何在团队中共享Hook配置？ ⠀ 将 .claude/ 目录加入Git版本控制： ⠀ Q20: Hook有性能影响吗？ ⠀ 有一定影响： • 每次工具调用都会触发Hook • 复杂脚本会增加延迟 • 建议优化脚本性能，设置合理timeout 附录A：配置速查表 ⠀ Hook类型速查 ⠀ Hook类型 触发时机 输入格式 输出格式 可阻止 重要 UserPromptSubmit 用户输入后 JSON 文本（注入上下文） V PreToolUse 工具调用前 JSON JSON决策 V ⭐ PostToolUse 工具调用后 JSON 无 X ⭐ Notification 通知发送时 JSON 无 X SessionStart 会话开始 无 无 X SessionEnd 会话结束 无 无 X Stop AI停止 JSON 无 X SubagentStart 🆕 子代理启动 JSON 无 X SubagentStop 🆕 子代理停止 JSON 无 X PermissionRequest 🆕 权限请求 JSON JSON决策 V PreCompact 🆕 上下文压缩前 JSON 无 X ConfigChange 🆕 配置变更 JSON 无 X TeammateIdle 🆕 队友空闲 JSON 无 X WorktreeCreate 工作树创建 JSON 无 X WorktreeRemove 工作树删除 JSON 无 X StopFailure 🆕 API异常停止 JSON 无 X PostCompact 🆕 上下文压缩后 JSON 无 X InstructionsLoaded 🆕 指令文件加载 JSON 无 X Elicitation 🆕 MCP请求输入 JSON 无 X ElicitationResult 🆕 MCP输入完成 JSON 无 X Hook类型 Hook类型 触发时机 触发时机 输入格式 输入格式 输出格式 输出格式 可阻止 可阻止 重要 重要 UserPromptSubmit UserPromptSubmit 用户输入后 用户输入后 JSON JSON 文本（注入上下文） 文本（注入上下文） V V PreToolUse PreToolUse 工具调用前 工具调用前 JSON JSON JSON决策 JSON决策 V V ⭐ ⭐ PostToolUse PostToolUse 工具调用后 工具调用后 JSON JSON 无 无 X X ⭐ ⭐ Notification Notification 通知发送时 通知发送时 JSON JSON 无 无 X X SessionStart SessionStart 会话开始 会话开始 无 无 无 无 X X SessionEnd SessionEnd 会话结束 会话结束 无 无 无 无 X X Stop Stop AI停止 AI停止 JSON JSON 无 无 X X SubagentStart 🆕 SubagentStart 🆕 子代理启动 子代理启动 JSON JSON 无 无 X X SubagentStop 🆕 SubagentStop 🆕 子代理停止 子代理停止 JSON JSON 无 无 X X PermissionRequest 🆕 PermissionRequest 🆕 权限请求 权限请求 JSON JSON JSON决策 JSON决策 V V PreCompact 🆕 PreCompact 🆕 上下文压缩前 上下文压缩前 JSON JSON 无 无 X X ConfigChange 🆕 ConfigChange 🆕 配置变更 配置变更 JSON JSON 无 无 X X TeammateIdle 🆕 TeammateIdle 🆕 队友空闲 队友空闲 JSON JSON 无 无 X X WorktreeCreate WorktreeCreate 工作树创建 工作树创建 JSON JSON 无 无 X X WorktreeRemove WorktreeRemove 工作树删除 工作树删除 JSON JSON 无 无 X X StopFailure 🆕 StopFailure 🆕 API异常停止 API异常停止 JSON JSON 无 无 X X PostCompact 🆕 PostCompact 🆕 上下文压缩后 上下文压缩后 JSON JSON 无 无 X X InstructionsLoaded 🆕 InstructionsLoaded 🆕 指令文件加载 指令文件加载 JSON JSON 无 无 X X Elicitation 🆕 Elicitation 🆕 MCP请求输入 MCP请求输入 JSON JSON 无 无 X X ElicitationResult 🆕 ElicitationResult 🆕 MCP输入完成 MCP输入完成 JSON JSON 无 无 X X ⠀ 常用工具名速查 ⠀ 工具名 功能 常用Hook 重要 Write 写入文件 PostToolUse格式化 ⭐ Edit 编辑文件 PostToolUse备份 Read 读取文件 PreToolUse权限控制 Bash 执行命令 PreToolUse危险命令拦截 ⭐ Glob 文件搜索 • Grep 内容搜索 • WebSearch 网络搜索 • 工具名 工具名 功能 功能 常用Hook 常用Hook 重要 重要 Write Write 写入文件 写入文件 PostToolUse格式化 PostToolUse格式化 ⭐ ⭐ Edit Edit 编辑文件 编辑文件 PostToolUse备份 PostToolUse备份 Read Read 读取文件 读取文件 PreToolUse权限控制 PreToolUse权限控制 Bash Bash 执行命令 执行命令 PreToolUse危险命令拦截 PreToolUse危险命令拦截 ⭐ ⭐ Glob Glob 文件搜索 文件搜索 • • Grep Grep 内容搜索 内容搜索 • • WebSearch WebSearch 网络搜索 网络搜索 • • ⠀ Decision值速查 ⠀ PreToolUse 新版API（hookSpecificOutput.permissionDecision，推荐）： ⠀ 值 含义 工具执行 重要 "allow" 允许，绕过权限系统 V ⭐ "deny" 拒绝，原因反馈给Claude X ⭐ "ask" 暂停，询问用户 ? 无输出 默认允许 V 值 值 含义 含义 工具执行 工具执行 重要 重要 "allow" "allow" 允许，绕过权限系统 允许，绕过权限系统 V V ⭐ ⭐ "deny" "deny" 拒绝，原因反馈给Claude 拒绝，原因反馈给Claude X X ⭐ ⭐ "ask" "ask" 暂停，询问用户 暂停，询问用户 ? ? 无输出 无输出 默认允许 默认允许 V V ⠀ PreToolUse 旧版API（decision，已废弃但仍支持）： ⠀ 旧版值 等同于新版 "approve" "allow" "block" "deny" 旧版值 旧版值 等同于新版 等同于新版 "approve" "approve" "allow" "allow" "block" "block" "deny" "deny" ⠀ PostToolUse / UserPromptSubmit： ⠀ 值 含义 "block" 阻止/提供反馈 无输出 默认允许 值 值 含义 含义 "block" "block" 阻止/提供反馈 阻止/提供反馈 无输出 无输出 默认允许 默认允许 附录B：完整脚本模板 ⠀ Python脚本模板 ⠀ ⠀ Bash脚本模板 ⠀ 附录C：参考资源 ⠀ 官方文档 ⠀ • Claude Code Hooks官方文档 Claude Code Hooks官方文档 • Claude Code官方指南 Claude Code官方指南 ⠀ 社区资源 ⠀ • ClaudeLog Hooks教程 ClaudeLog Hooks教程 • GitButler Claude Code Hooks集成 GitButler Claude Code Hooks集成 • Awesome Claude Code Awesome Claude Code ⠀ 相关课程 ⠀ • 第3部分：Commands系统 Slash命令开发 • 第4部分：MCP集成 外部工具连接 • 第6部分：Skills定制 技能包开发 学习总结 ⠀ 通过本课学习，你已经掌握： ⠀ 1. Hooks核心概念：理解Hook是什么、为什么需要、能做什么 2. 15种Hook类型：PreToolUse、PostToolUse、UserPromptSubmit、Notification、Stop、SessionStart、SessionEnd、SubagentStart、SubagentStop、PermissionRequest、PreCompact、ConfigChange、TeammateIdle、WorktreeCreate、WorktreeRemove全部类型 3. 配置方法：settings.json配置格式、Matcher语法、timeout设置 4. 实战场景：Git自动化、代码格式化、文件保护、质量检查 5. 故障排查：常见问题诊断和解决方法 6. 安全意识：Hook安全风险和最佳实践 ⠀ 下一步建议： ⠀ 1. 从第二部分的简单示例开始实践 2. 根据你的项目需求，选择合适的Hook类型 3. 参考第四部分的实战案例，逐步构建自己的自动化工作流 4. 遇到问题查阅第五部分和第六部分 ⠀ 记住：Hooks是自动化的终极武器，合理使用可以让你的开发效率翻倍！ 课程信息 ⠀ • 作者：老金 • GitHub：https://github.com/KimYx0207 • 公众号：老金带你玩AI • X（Twitter）：老金带你玩AI • 个人博客：https://aiking.dev • 预计学时：4 6小时 • 难度等级：⭐⭐ 入门级（有Claude Code基础即可） • 更新日期：2026年5月30日 • 适用版本：Claude Code v2.1.158（验证于 2026 05 30） • 前置要求：已完成Claude Code安装和基础使用 本课学习目标 ⠀ 完成本课学习后，你将能够： ⠀ 1. 理解Hooks的核心价值：掌握Hooks与传统提示词的本质区别 2. 配置第一个Hook：5分钟内完成最简单的Hook配置并看到效果 3. 按事件族理解Hooks：理解工具、会话、任务、失败、文件系统、压缩和 Elicitation 等事件面 4. 实现自动化工作流：Git提交检查、代码格式化、文件保护等实战场景 5. 排查Hook故障：独立解决90%的常见配置和执行问题 6. 安全使用Hooks：理解安全风险并正确配置权限 学习路径导航（先看这里！） ⠀ 根据你的情况选择学习路径：这是一篇3000+行的长教程，不用全看！根据你的目标选择路径。 根据你的情况选择学习路径：这是一篇3000+行的长教程，不用全看！根据你的目标选择路径。 ⠀ 路径A：快速上手（30分钟） ⠀ 适合人群：急着体验Hooks，想快速配一个看效果 ⠀ 只看这些章节（其他跳过）： ⠀ ⠀ 30分钟后你能达到：成功配置第一个Hook，Claude Code能自动执行你的脚本 路径B：完整学习（4 6小时） ⠀ 适合人群：想深入理解Hooks，掌握所有类型和高级用法 ⠀ 学习顺序：从头到尾所有章节 ⠀ 建议分段学习： • 第1天（2小时）：第1 3部分（理解+15种类型） • 第2天（2小时）：第4 5部分（实战场景+故障排查） • 第3天（1小时）：第6 7部分（FAQ+附录） 路径C：问题排查（10分钟） ⠀ 适合人群：Hook配置出问题，需要快速解决 ⠀ 直接跳到这些章节： ⠀ ⠀ 使用方法： 1. 按 Ctrl + F 搜索你的错误信息关键词 2. 找到对应的Q&A 3. 按步骤解决 路径D：专项学习（30 60分钟/主题） ⠀ 适合人群：已经会配置Hook，想学习特定功能 ⠀ 想学什么 看哪几节 预计时间 Git自动化 第四部分4.1节 45分钟 代码格式化 第四部分4.2节 30分钟 文件保护 第三部分3.1节 20分钟 提示词优化 第三部分3.3节 30分钟 安全最佳实践 第一部分1.4节 + 第五部分 40分钟 想学什么 想学什么 看哪几节 看哪几节 预计时间 预计时间 Git自动化 Git自动化 第四部分4.1节 第四部分4.1节 45分钟 45分钟 代码格式化 代码格式化 第四部分4.2节 第四部分4.2节 30分钟 30分钟 文件保护 文件保护 第三部分3.1节 第三部分3.1节 20分钟 20分钟 提示词优化 提示词优化 第三部分3.3节 第三部分3.3节 30分钟 30分钟 安全最佳实践 安全最佳实践 第一部分1.4节 + 第五部分 第一部分1.4节 + 第五部分 40分钟 40分钟 术语表（小白必读） ⠀ 在开始之前，先了解这些关键术语。用生活类比帮助理解： ⠀ 术语 英文全称 通俗解释 生活类比 Hook • 在特定事件发生时自动执行的脚本 汽车传感器（检测到碰撞自动弹安全气囊） PreToolUse Pre Tool Use 工具调用前触发的Hook 机场安检门（登机前检查） PostToolUse Post Tool Use 工具调用后触发的Hook 快递签收后的自动通知 UserPromptSubmit User Prompt Submit 用户输入提交时触发的Hook 邮件发送前的拼写检查 Notification • 通知事件触发的Hook 手机APP推送通知 SessionStart Session Start 会话开始时触发的Hook 开机自动启动程序 SessionEnd Session End 会话结束时触发的Hook 关机前自动保存 Stop • AI停止响应时触发的Hook 紧急刹车后的状态保存 WorktreeCreate 🆕 Worktree Create 工作树创建时触发的Hook 新开一个平行工作台时的初始化 WorktreeRemove 🆕 Worktree Remove 工作树删除时触发的Hook 关闭平行工作台时的清理 Matcher • 匹配规则，决定Hook对哪些工具生效 筛选器（只检查特定行李） Decision • PreToolUse Hook的返回决策 安检结果（放行/拦截/询问） stdin Standard Input 标准输入，Hook接收数据的方式 传送带送入检查口 stdout Standard Output 标准输出，Hook返回结果的方式 检查结果显示屏 stderr Standard Error 标准错误输出，仅用于调试日志（不会显示在Claude Code界面） 后台监控日志（用户看不到） timeout • 超时时间，Hook最长运行时间 限时检查（超时自动放行） JSON JavaScript Object Notation 一种通用的数据格式，用花括号{}组织数据，settings.json配置文件就是JSON格式 标准化的表格模板 （波浪号） Home Directory 用户的"家目录"，macOS是/Users/用户名，Linux是/home/用户名，Windows对应C:\Users\用户名 你电脑上"我的文档"的上级目录 术语 术语 英文全称 英文全称 通俗解释 通俗解释 生活类比 生活类比 Hook Hook • • 在特定事件发生时自动执行的脚本 在特定事件发生时自动执行的脚本 汽车传感器（检测到碰撞自动弹安全气囊） 汽车传感器（检测到碰撞自动弹安全气囊） PreToolUse PreToolUse Pre Tool Use Pre Tool Use 工具调用前触发的Hook 工具调用前触发的Hook 机场安检门（登机前检查） 机场安检门（登机前检查） PostToolUse PostToolUse Post Tool Use Post Tool Use 工具调用后触发的Hook 工具调用后触发的Hook 快递签收后的自动通知 快递签收后的自动通知 UserPromptSubmit UserPromptSubmit User Prompt Submit User Prompt Submit 用户输入提交时触发的Hook 用户输入提交时触发的Hook 邮件发送前的拼写检查 邮件发送前的拼写检查 Notification Notification • • 通知事件触发的Hook 通知事件触发的Hook 手机APP推送通知 手机APP推送通知 SessionStart SessionStart Session Start Session Start 会话开始时触发的Hook 会话开始时触发的Hook 开机自动启动程序 开机自动启动程序 SessionEnd SessionEnd Session End Session End 会话结束时触发的Hook 会话结束时触发的Hook 关机前自动保存 关机前自动保存 Stop Stop • • AI停止响应时触发的Hook AI停止响应时触发的Hook 紧急刹车后的状态保存 紧急刹车后的状态保存 WorktreeCreate 🆕 WorktreeCreate 🆕 Worktree Create Worktree Create 工作树创建时触发的Hook 工作树创建时触发的Hook 新开一个平行工作台时的初始化 新开一个平行工作台时的初始化 WorktreeRemove 🆕 WorktreeRemove 🆕 Worktree Remove Worktree Remove 工作树删除时触发的Hook 工作树删除时触发的Hook 关闭平行工作台时的清理 关闭平行工作台时的清理 Matcher Matcher • • 匹配规则，决定Hook对哪些工具生效 匹配规则，决定Hook对哪些工具生效 筛选器（只检查特定行李） 筛选器（只检查特定行李） Decision Decision • • PreToolUse Hook的返回决策 PreToolUse Hook的返回决策 安检结果（放行/拦截/询问） 安检结果（放行/拦截/询问） stdin stdin Standard Input Standard Input 标准输入，Hook接收数据的方式 标准输入，Hook接收数据的方式 传送带送入检查口 传送带送入检查口 stdout stdout Standard Output Standard Output 标准输出，Hook返回结果的方式 标准输出，Hook返回结果的方式 检查结果显示屏 检查结果显示屏 stderr stderr Standard Error Standard Error 标准错误输出，仅用于调试日志（不会显示在Claude Code界面） 标准错误输出，仅用于调试日志（不会显示在Claude Code界面） 后台监控日志（用户看不到） 后台监控日志（用户看不到） timeout timeout • • 超时时间，Hook最长运行时间 超时时间，Hook最长运行时间 限时检查（超时自动放行） 限时检查（超时自动放行） JSON JSON JavaScript Object Notation JavaScript Object Notation 一种通用的数据格式，用花括号{}组织数据，settings.json配置文件就是JSON格式 一种通用的数据格式，用花括号{}组织数据，settings.json配置文件就是JSON格式 标准化的表格模板 标准化的表格模板 （波浪号） （波浪号） Home Directory Home Directory 用户的"家目录"，macOS是/Users/用户名，Linux是/home/用户名，Windows对应C:\Users\用户名 用户的"家目录"，macOS是/Users/用户名，Linux是/home/用户名，Windows对应C:\Users\用户名 你电脑上"我的文档"的上级目录 你电脑上"我的文档"的上级目录 第一部分：Hooks简介（5分钟理解） ⠀ 1.1 Hooks是什么 ⠀ 一句话理解：Hooks是Claude Code的"自动化传感器"，在特定事件发生时自动执行你的脚本，实现100%可靠的自动化。 一句话理解：Hooks是Claude Code的"自动化传感器"，在特定事件发生时自动执行你的脚本，实现100%可靠的自动化。 ⠀ 为什么需要Hooks？ ⠀ 没有Hooks之前（靠AI"记住"）： ⠀ ⠀ 有了Hooks之后（100%自动执行）： ⠀ ⠀ 生活类比： • 没有Hooks：靠人记住每次开车前检查轮胎（经常忘） • 有Hooks后：汽车传感器自动检测胎压，异常自动报警（100%可靠） 生活类比： • 没有Hooks：靠人记住每次开车前检查轮胎（经常忘） • 有Hooks后：汽车传感器自动检测胎压，异常自动报警（100%可靠） ⠀ Hooks的核心价值 ⠀ 对比维度 提示词方式 Hooks方式 可靠性 不确定（AI可能忘记） 100%执行（确定性） 一致性 每次可能不同 每次完全相同 自动化 需要AI主动执行 事件触发自动执行 团队协作 每人都要提醒AI 配置一次，全员生效 适用场景 灵活建议 强制规则 对比维度 对比维度 提示词方式 提示词方式 Hooks方式 Hooks方式 可靠性 可靠性 不确定（AI可能忘记） 不确定（AI可能忘记） 100%执行（确定性） 100%执行（确定性） 一致性 一致性 每次可能不同 每次可能不同 每次完全相同 每次完全相同