Cursor Hooks入门：5分钟掌握自动化工作流配置

什么是 Cursor Hooks？

如果你用过 Cursor（Cloud Code），可能会好奇：它是如何做到在需要权限时直接弹窗通知你，而不是傻傻地卡住等待？答案就是 Hooks 机制。

Hooks 可以简单理解为：当某个条件达成后，自动执行的一段命令、脚本或提示词。它让 Cursor 从一个被动的代码助手，变成了一个可以主动响应事件的自动化工作流引擎。

Hooks配置示例

这种设计背后采用的是软件工程中经典的事件驱动（Event-Driven）架构。在这种架构中，系统的执行流程不是线性的，而是由「事件」来驱动——当某个事件发生时，系统会查找并执行所有注册在该事件上的处理函数。这种模式在开发领域并不陌生：浏览器的 DOM 事件监听、React 的生命周期钩子、Git 的 pre-commit/post-commit 钩子，本质上都是同一种思想。Cursor 将这种模式引入 AI 编程助手，使得开发者可以在 AI 的工作流程中插入自定义逻辑，从而将 AI 从一个单向的问答工具升级为可编程的自动化平台。

Cursor 官方总共定义了 29 个触发事件，覆盖了从工具调用、文件操作到通知权限等各种场景。当对应条件满足时，预设的 Hook 就会被触发执行。

Hooks 的组成结构

一个完整的 Hooks 配置由以下四个部分组成：

触发事件（Event）：定义什么时候触发，比如 pre-tool-use（使用工具前）、post-tool-use（使用工具后）、permission_request（权限请求时）等
匹配条件（Matcher）：进一步缩小触发范围，每个事件都有对应的 Matcher 列表，可在官方文档查询
执行方式（Type）：触发后做什么类型的操作，可以是 command（运行命令）、输入一段提示词、或切换到某个 Agent
执行内容：具体要运行的命令或脚本内容

其中 pre-tool-use 和 post-tool-use 这种**「前置/后置钩子」的设计模式在软件工程中有着广泛的应用。Git 的 pre-commit 和 post-commit 钩子允许开发者在提交代码前后执行代码检查或自动部署；数据库的触发器（Trigger）可以在数据插入前后执行校验或级联更新；Web 框架中的中间件（Middleware）也遵循类似的请求前处理和响应后处理逻辑。这种模式的核心价值在于面向切面编程（AOP）**——它允许开发者在不修改核心逻辑的前提下，通过声明式的方式注入横切关注点，比如日志记录、权限校验、性能监控等。Cursor 的 Hooks 正是将这一思想应用到了 AI 编程助手的交互流程中。

以 notification 触发事件为例，它就有 6 个匹配条件可供选择。而 Matcher 设置为通配符时，表示所有匹配项都会触发 Hook。

配置文件放在哪里？

两个配置位置

Hooks 的配置文件是 .cursor/settings.json，可以放在两个位置：

位置	作用域	路径
项目目录内	仅当前项目生效	`项目根目录/.cursor/settings.json`
用户文件夹内	全局生效	`~/.cursor/settings.json`

Cursor 选择 JSON 作为 Hooks 的配置格式，延续了 VS Code 生态的一贯做法——settings.json、launch.json、tasks.json 等都采用 JSON 格式。相比 YAML 或 TOML，JSON 的优势在于解析器的普遍性和严格的语法规范，减少了因缩进或格式问题导致的配置错误。而项目级与全局级两层配置的设计，则借鉴了 Git 的配置优先级机制（.git/config 优先于 ~/.gitconfig）。项目级配置可以随代码仓库一起版本控制和分发，团队成员克隆项目后即可共享相同的 Hooks 设置；全局级配置则适合个人偏好和跨项目通用的自动化规则。

脚本文件存放

对应的脚本文件放在 .cursor/hooks/ 文件夹下，同样分为项目级和全局级两种。

脚本的工作原理

Hooks 脚本通过**标准输入/输出（stdin/stdout）**与 Cursor 通信：

脚本从标准输入中读取数据
将数据解析为 JSON 格式
根据解析出的 JSON 内容进行相应处理
处理完毕后通过标准输出将结果发送回 Cursor

标准输入/输出是 Unix/Linux 操作系统中最基础的**进程间通信（IPC）**方式之一。每个进程启动时都会自动获得三个文件描述符：标准输入（stdin，文件描述符 0）、标准输出（stdout，文件描述符 1）和标准错误（stderr，文件描述符 2）。Cursor 选择 stdin/stdout 作为与 Hook 脚本的通信协议，是一个非常巧妙的设计决策。相比 HTTP 接口、WebSocket 或共享内存等方式，stdin/stdout 几乎没有额外的依赖和配置成本，任何能读写文本流的编程语言都天然支持。这也是 Unix 哲学中强调「用管道连接小工具」的体现——通过标准 I/O，不同语言编写的程序可以无缝协作。

这种设计意味着你可以用任何支持标准 I/O 的编程语言来编写 Hook 脚本，Python 只是最常见的选择之一。Node.js、Bash、Go、Rust 甚至 Perl 都完全可以胜任，选择你最熟悉的语言即可。

手把手配置项目级 Hooks

前置条件

电脑已安装 Python 环境
已安装 VS Code 和 Cursor（Cloud Code）扩展

Cursor Cloud Code 是 Cursor 团队推出的 VS Code 扩展版本，它将 Cursor 的 AI 编程能力以插件形式集成到 VS Code 中。与独立的 Cursor 编辑器不同，Cloud Code 扩展让开发者无需切换编辑器即可使用 Cursor 的 Agent 模式、多模型切换和上下文感知等核心功能。值得注意的是，Hooks 功能目前主要在 Agent 模式下生效，因为只有 Agent 模式才涉及工具调用、文件操作和权限请求等需要钩子介入的场景。

第一步：创建目录结构

项目根目录/
└── .cursor/
    ├── settings.json
    └── hooks/
        └── notify.py

具体操作：

创建项目文件夹并进入
创建 .cursor 文件夹
在其中创建 settings.json 文件
创建 hooks 子文件夹
在 hooks 文件夹中创建 notify.py 脚本文件

第二步：编写配置和脚本

用 VS Code 打开项目根目录，分别编辑：

settings.json：写入 Hooks 配置，注意 command 字段中的脚本路径。如果是全局目录安装，路径前需要加上 ~/
notify.py：写入弹窗通知的脚本代码

小技巧：Hooks 的配置和脚本完全可以让 Cursor 自己生成，你只需要描述想要的功能即可。

第三步：测试验证

点击左侧的 Cursor 图标，点击 New Session 创建新对话
在输入框输入 /hooks，选择 continuing terminal 在终端打开
用上下键找到 permission_request，回车进入即可看到配置的 Hook
随便让 AI 写点代码，当需要权限时就会弹出弹窗

弹窗出现后，你可以直接在弹窗上选择操作，结果会同步回 Cursor。这样在需要权限确认时，你可以快速响应，而不是让 AI 傻等。

Hooks 的更多玩法

权限弹窗通知只是 Hooks 最基础的应用。通过不同事件和执行方式的组合搭配，你还可以实现：

自动跑测试脚本：代码修改后自动触发测试。例如配置 post-tool-use 事件并匹配 edit_file 工具，当 AI 修改完代码后自动运行 pytest 或 npm test，实时反馈测试结果，形成「编写-测试-修复」的闭环
拦截危险操作：在执行删除、覆盖等高风险命令前进行拦截确认。通过 pre-tool-use 钩子匹配 run_terminal_command，对包含 rm -rf、DROP TABLE 等危险关键词的命令进行二次确认，防止 AI 的误操作造成不可逆的损失
自动授权管理：根据规则自动处理权限请求。对于读取文件、列出目录等低风险操作自动批准，对于写入、删除等高风险操作则弹窗确认，实现分级授权策略
搭建完整的自动化工作流：将多个 Hooks 串联，实现复杂的自动化流程。比如代码修改后自动格式化 → 运行 lint 检查 → 执行单元测试 → 生成变更日志，整个流程无需人工干预

总结

Cursor Hooks 本质上是一套事件驱动的自动化框架。它的设计思路清晰：定义触发条件 → 设置匹配规则 → 指定执行方式 → 编写执行内容。29 个内置触发事件覆盖了 AI 编程助手的主要交互场景，配合自定义脚本，几乎可以实现任意自动化需求。

从更宏观的角度看，Hooks 机制代表了 AI 编程工具发展的一个重要方向：可编程性。早期的 AI 编程助手只能被动地响应用户的提问，而 Hooks 让开发者可以定义 AI 的行为边界和自动化规则，使人机协作从简单的「你问我答」进化为结构化的工作流协同。这与 DevOps 领域中 CI/CD 管道的理念一脉相承——通过预定义的自动化规则，减少重复性的人工操作，让开发者专注于真正需要创造力的工作。

对于日常使用 Cursor 的开发者来说，花 5 分钟配置几个常用的 Hooks，就能显著提升与 AI 协作的效率。建议从权限通知这个最实用的场景入手，逐步探索更复杂的自动化工作流。