我帮你把这篇官方 Hooks 文档彻底拆解 + 重写成“小白能看懂版”，但不会丢任何关键点。你可以当成一份“实战入门指南”。

🧠 一句话先讲明白 Hooks 是啥

👉 Hooks 本质就是：

在 AI 做事的“关键时刻”，强制执行你写的脚本

不是建议，是强制执行。

🧩 为什么需要 Hooks？（核心理解）

你之前可能用过：

CLAUDE.md（规则提示）
Prompt（告诉 AI 怎么做）

👉 这些有个问题：

❗ AI可以不听

而 Hooks：

✅ 一定执行（强制）

比如：

不允许改 .env
自动格式化代码
自动记录日志

👉 Hooks = 规则 → 变成程序

⚙️ Hooks 能干嘛？（官方用途翻译）

官方说的几个场景，我给你翻译成人话：

1️⃣ 通知

👉 AI卡住时提醒你
（比如：需要你点确认）

2️⃣ 自动格式化代码

👉 写完代码自动执行：

prettier（前端）
php-cs-fixer（PHP）

3️⃣ 日志记录

👉 AI干了什么全记录

4️⃣ 代码规范检查

👉 AI写的代码不符合规范 → 自动提示

5️⃣ 权限控制（最重要）

👉 比如：

禁止改 .env
禁止操作生产目录

🧠 Hooks 的核心机制（一定要懂）

👉 Hooks = “在某个时间点触发”

官方定义了一堆“触发点”（事件） (Claude API Docs)

📍 最重要的 5 个事件（你先记这几个）

1. PreToolUse（最关键）

👉 在 AI 执行操作之前

✔ 可以：

拦截
阻止

👉 用途：

防止危险操作

2. PostToolUse

👉 操作执行完之后

✔ 用途：

自动格式化代码
记录日志

3. UserPromptSubmit

👉 你刚输入问题时

✔ 用途：

校验 prompt
加上下文

4. Notification

👉 AI需要你操作时

✔ 用途：

弹通知

5. Stop

👉 AI完成任务时

✔ 用途：

收尾操作

📌 官方完整事件还有：

SessionStart / End（会话开始结束）
SubagentStop（子任务结束）
PreCompact（压缩上下文前） (Claude API Docs)

👉 小白先不用全记

⚙️ Hooks 是怎么运行的？

👉 本质流程：

AI要做事
   ↓
触发 Hook
   ↓
执行你写的 shell / python 脚本
   ↓
决定：
   - 允许
   - 阻止
   - 修改行为

📦 Hooks 配置长什么样？

最核心结构是这个：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "你的脚本"
          }
        ]
      }
    ]
  }
}

🧠 三个关键字段（必须理解）

1️⃣ Event（什么时候触发）

比如：

PreToolUse
PostToolUse

2️⃣ matcher（匹配什么操作）

比如：

"matcher": "Write"

👉 只在“写文件”时触发

支持：

Edit|Write（多个）
*（全部）
正则

3️⃣ command（执行什么）

👉 本质就是：

执行一个 shell 命令

比如：

python check.py

🚨 Hooks 最重要能力：可以“阻止 AI”

这是最关键的点。

👉 通过 exit code 控制

返回值	意义
0	正常
2	❗阻止操作
其他	报错但继续

示例：禁止改 .env

if ".env" in path:
    exit(2)

👉 结果：

AI 想改 → 直接被拦住 ❌

🧠 更高级玩法（JSON 控制）

Hooks 可以返回 JSON 控制行为 (Claude API Docs)

比如：

{
  "continue": false,
  "stopReason": "禁止操作"
}

👉 作用：

直接让 AI 停下来

🔌 Hooks + MCP（重点）

MCP 工具名字长这样：

mcp__filesystem__read_file

👉 规则：

"matcher": "mcp__filesystem__.*"

👉 你可以做到：

监控所有文件操作
限制某些 MCP 工具

⚠️ 安全问题（官方重点强调）

👉 Hooks 非常危险（真的）

因为：

❗它会自动执行系统命令

可能风险：

删除文件
泄露数据
执行恶意脚本

官方建议：

不信任输入
用绝对路径
避免操作：
- .env
- .git
检查路径（防止 ../） (Claude API Docs)

⚙️ 运行机制（你要知道的细节）

1️⃣ Hooks 是并行执行的

👉 多个 hook 会同时跑 (Claude API Docs)

2️⃣ 有超时（默认60秒）

👉 超时会被杀掉 (Claude API Docs)

3️⃣ 输入输出

输入：JSON（stdin）
输出：
- stdout（正常）
- stderr（错误）

4️⃣ 环境变量

最重要：

$CLAUDE_PROJECT_DIR

👉 当前项目路径

🧪 一个完整小白案例（你能直接用）

👉 自动禁止改敏感文件

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python protect.py"
          }
        ]
      }
    ]
  }
}

protect.py：

import json, sys

data = json.load(sys.stdin)
path = data.get("tool_input", {}).get("file_path", "")

if ".env" in path:
    print("禁止修改.env", file=sys.stderr)
    sys.exit(2)

sys.exit(0)

🧠 最终理解（帮你建立模型）

你可以这样理解：

工具	本质
Prompt	建议
CLAUDE.md	规则
Hooks	❗强制执行

🚀 给你的建议（结合你）

你是：

PHP + 运维 + 自动化

👉 强烈建议你先做 3 个 Hook：

必做：

禁止改 .env
自动记录所有 shell 命令
自动格式化 PHP 代码

🧩 一句话总结

👉 Hooks 就是：

给 AI 加“刹车 + 自动化 + 权限系统”

如果你想，我可以帮你：

👉 给你一套 “PHP开发者 Hooks 模板（直接可用）”
包括：

Laravel 专用
生产环境保护
自动部署流程

这套东西会直接把你提升到“AI工程化”阶段。

On this page