Cursor 2026 新特性实战：使用 Agent Hooks 构建自动化代码工作流

编辑 .cursor/hooks/config.yaml，添加第一个 Hook：

version: "1.0"
hooks:
  - name: auto-format
    trigger: onSave
    pattern: "**/*.{ts,tsx,js,jsx}"
    command: bunx biome check --write {{file}}

配置解析：

• trigger: onSave - 文件保存时触发
• pattern - 使用 glob 匹配 TypeScript/JavaScript 文件
• {{file}} - 当前保存文件的路径变量

继续配置文件，添加 TypeScript 类型检查：

  - name: type-check
    trigger: onSave
    pattern: "**/*.ts"
    command: tsc --noEmit {{file}}
    async: true

async: true 让检查异步执行，不会阻塞保存操作。类型错误会在编辑器中以红色波浪线标出。

保存测试文件时自动运行相关测试：

  - name: run-tests
    trigger: onSave
    pattern: "**/*.test.ts"
    command: bun test {{file}}
    showOutput: always

showOutput: always 确保测试结果始终显示在输出面板中。运行结果示例：

 PASS  src/utils/parser.test.ts
  ✓ parseInput should handle valid JSON (15ms)
  ✓ parseInput should throw on invalid JSON (8ms)

Test Suites: 1 passed, 1 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        0.234s

创建脚本 .cursor/hooks/scripts/auto-doc.sh：

#!/bin/bash
FILE=$1

# 读取文件内容
CONTENT=$(cat "$FILE")

# 调用 Cursor AI 生成 JSDoc
cursor-ai generate-docs --file "$FILE" --inplace

echo "✓ JSDoc 文档已更新"

赋予执行权限并添加到配置：

chmod +x .cursor/hooks/scripts/auto-doc.sh

  - name: auto-docs
    trigger: onSave
    pattern: "**/src/**/*.ts"
    command: bash .cursor/hooks/scripts/auto-doc.sh {{file}}

创建提交前检查脚本 .cursor/hooks/scripts/commit-check.sh：

#!/bin/bash
set -e

echo "🔍 运行提交前检查..."

# 1. 运行测试
echo "├─ 运行测试套件..."
if ! bun test --dry-run 2>&1; then
  echo "❌ 测试失败，阻止提交"
  exit 1
fi

# 2. 代码规范检查
echo "├─ 检查代码规范..."
if ! bunx biome check src/ 2>&1; then
  echo "❌ 代码规范检查失败"
  exit 1
fi

# 3. 生成 commit message 建议
echo "└─ 生成提交建议..."
cursor-ai suggest-commit-message --context=staged

echo "✓ 所有检查通过"

切换分支时自动同步依赖和清理缓存：

  - name: branch-sync
    trigger: onBranchChange
    command: |
      echo "🔄 检测到分支切换..."
      # 检查 package.json 是否变化
      if git diff --name-only HEAD@{1} HEAD | grep -q package.json; then
        echo "├─ 依赖配置变化，重新安装..."
        bun install
      fi
      # 清理构建缓存
      echo "└─ 清理构建缓存..."
      rm -rf .turbo node_modules/.cache

这个 Hook 在切换分支后自动运行，确保依赖与目标分支一致。

对于复杂场景，可以使用链式执行。编辑配置文件：

  - name: frontend-pipeline
    trigger: onSave
    pattern: "**/src/**/*.ts"
    chain:
      - command: bunx biome check --write {{file}}
        onError: continue
      - command: tsc --noEmit {{file}}
        onError: stop
      - command: bun test --related {{file}}
        async: true
      - command: git add {{file}}

链式执行规则：

• onError: continue - 出错时继续执行下一步
• onError: stop - 出错时停止后续步骤
• async: true - 异步执行，不阻塞后续操作

某些 Hooks 只在特定条件下执行，例如只在 main 分支运行生产构建：

  - name: production-build
    trigger: onSave
    pattern: "**/src/**/*.tsx"
    condition:
      branch: main
      env: CI!=true
    command: bun run build

支持的条件类型：

condition:
  branch: main              # 仅特定分支
  branches: ["main", "dev"] # 多个分支
  env: CI!=true            # 环境变量条件
  time: "9:00-18:00"       # 时间段
  files: ["**/config/*"]   # 额外文件匹配