Skip to Content
三. 配置与定制16 · Hooks 钩子

16 · Hooks 钩子

在 AI 操作的关键时机自动触发你的脚本——把”请求”变成”保证”。

01 Hooks 是什么

Hooks 是 Cursor 中的事件驱动自动化机制。你可以在 AI 生命周期的特定时间点挂载脚本——当对应事件发生时，Cursor 自动执行你的脚本。

把 Hooks 理解为关卡：你可以在 AI 读文件之前、写文件之后、启动时、停止时等时机插入自定义逻辑。

02 Hooks 的事件类型

Cursor 支持的 Hook 事件：

事件触发时机能阻止操作？
SessionStart新会话开始时否
UserPromptSubmit用户提交提示词时否
PreToolUseAI 调用工具（读/写/执行）之前✅ 可以阻止
PostToolUseAI 调用工具之后否
StopAI 停止生成时否
SessionEnd会话结束时否

PreToolUse 是最关键的事件——你可以在这里拦截危险操作。

03 配置 Hooks

Hooks 在 .cursor/hooks.json 中配置：

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "Bash",
      "command": "node .cursor/hooks/check-dangerous-command.js",
      "timeout": 5000
    },
    {
      "event": "PostToolUse",
      "matcher": "Edit|Write",
      "command": "npx prettier --write ${FILE}",
      "timeout": 10000
    }
  ]
}

配置字段说明

字段说明
event事件类型（PreToolUse / PostToolUse / …）
matcher匹配的工具名（Bash / Edit / Write / Read / * 表示所有）
command要执行的命令
timeout超时时间（毫秒），默认 10000

通信协议

Cursor 通过以下方式和 Hook 脚本通信：

  • stdin：以 JSON 格式传入事件上下文（做了什么操作、涉及什么文件等）
  • stdout：脚本可以输出 JSON 来控制行为
  • 退出码：
    • 0 → 放行，操作继续
    • 2 → 阻止操作
    • 其他 → 非阻塞错误，操作继续但记录日志

⚠️ 关键：想阻拦操作，必须 exit 2，不是 exit 1。

04 实用 Hook 示例

示例 1：阻止危险终端命令

// .cursor/hooks/check-dangerous-command.js
const fs = require('fs');
const input = JSON.parse(fs.readFileSync(0, 'utf-8'));
const command = input.command || '';
 
const DANGEROUS_PATTERNS = [
  /rm\s+-rf\s+\//,
  /git\s+push\s+--force.*origin\s+main/,
  /DROP\s+(TABLE|DATABASE)/i,
  /DELETE\s+FROM.+WHERE\s*$/i,  // 没有 WHERE 的 DELETE
];
 
const isDangerous = DANGEROUS_PATTERNS.some(p => p.test(command));
 
if (isDangerous) {
  console.error(`🚫 危险命令被拦截: ${command}`);
  process.exit(2);  // 阻止操作
}
 
process.exit(0);  // 放行

示例 2：自动格式化 AI 修改的文件

{
  "event": "PostToolUse",
  "matcher": "Edit|Write",
  "command": "npx prettier --write \"$CURSOR_MODIFIED_FILE\" 2>/dev/null || true"
}

这样每次 AI 修改文件后，Prettier 自动格式化——你永远不会看到 AI 写出格式混乱的代码。

示例 3：会话启动时注入上下文

{
  "event": "SessionStart",
  "matcher": "*",
  "command": "cat .cursor/context/team-conventions.md"
}

脚本的 stdout 输出会自动注入到 AI 的上下文——相当于每次启动新会话时自动告诉 AI 你的团队规范。

05 Hooks 的安全原则

  • Hooks 只能收紧权限，不能放宽：你可以在 PreToolUse 中阻止操作，但不能在 Hook 中授权本来需要审批的操作
  • Hooks 脚本运行在本地：它们能访问你的文件系统和环境变量，所以只使用你信任的脚本
  • 测试 Hooks：先用 echo 或写入日志来测试 Hook 是否触发，确认后再加拦截逻辑

06 小结

要点说明
Hooks 本质事件驱动自动化——在 AI 操作前后执行你的脚本
最关键的事件PreToolUse——唯一能阻止操作的时机
阻止操作脚本 exit 2
最常见用途阻止危险命令、自动格式化、注入上下文、发送通知
配置位置.cursor/hooks.json

下一篇：17 并行 Agent —— 同时跑多个 Agent，用 git worktree 隔离环境。

15 · Skills 技能17 · 并行 Agent