本文迁移自 mindcarver/91ai · 原始位置 docs/ai-coding/cursor.md · 由 @阿新聊ai 整理。

Cursor 资料与项目索引

更新日期：2026-05-27
范围：Cursor IDE、Cursor Agent、Cursor CLI、Background Agent、BugBot、Cursor SDK、Rules、AGENTS.md、MCP、Hooks、学习资料、生态项目和评测研究。

Cursor 更适合被理解成一个 AI-first IDE，而不是单独的终端 coding agent。它的核心价值是把 AI 补全、项目级问答、inline edit、agent mode、rules 和 MCP 集成在同一个编辑器工作流里。

Cursor 当前有五个执行形态：

推荐阅读顺序

1. Cursor docs — 总入口
2. Cursor Rules — 上下文管理最核心的机制
3. Cursor Agent tools — Agent 能做什么、不能做什么
4. Background Agent — 异步执行模式
5. Cursor CLI — 终端 agent 形态
6. Cursor MCP — 外部工具接入

官方资料

核心机制深度解析

Rules 体系：四层规则叠加

Cursor 的规则系统有四个来源，按优先级从高到低：

Project Rules (.cursor/rules/)  >  AGENTS.md  >  User Rules  >  .cursorrules (legacy)

Project Rules 支持 globs 字段控制触发条件，只在编辑匹配文件时才加载，避免无关规则污染上下文：

---
description: React component conventions
globs: ["src/components/**/*.tsx", "src/components/**/*.ts"]
---
# React Component Rules

- Use functional components with hooks.
- Keep components under 200 lines.
- Colocate tests in __tests__/ directories.

最佳实践：

• Project Rules 按目录或文件类型拆分，每个规则控制在 50 行以内
• AGENTS.md 放跨工具通用规则（约 100 行）
• User Rules 只放个人偏好，不放入仓库
• .cursorrules 迁移到 Project Rules 后删除

Agent Mode：编辑器内的多步骤执行

Cursor Agent Mode 可以执行的工具：

Agent 的执行循环和 Codex/Claude Code 类似：用户给出任务 → Agent 规划步骤 → 调用工具 → 检查结果 → 继续或完成。但 Cursor Agent 的差异在于：

• 编辑器集成：Agent 修改的文件直接在编辑器中显示 diff，可以实时看到变更
• 自动模式：可以配置为自动执行不需要逐步确认（类似 Codex 的 full-auto）
• YOLO Mode：社区俗称，让 Agent 全自动执行所有操作包括 shell 命令，风险较高

Background Agent：云端异步执行

Background Agent 在独立的云端沙箱（Ubuntu VM）中运行，不阻塞编辑器：

• 触发方式：在 Chat 中选择 "Run in background"，或通过 Slack / Mobile app 分配任务
• 工作方式：克隆仓库 → 创建分支 → 实现变更 → 运行测试 → 打开 PR
• 多仓库支持（Cursor 3.3，2026-05）：可在单个任务中跨多个仓库操作
• 自定义环境：通过 .cursor/Dockerfile 配置云端 agent 的运行环境
• 治理控制：管理员可限制允许的仓库、分支和操作类型
• 并行处理：多个 Background Agent 可同时运行
• 移动端：iOS 和 Android app 可监控和分配任务
• 成本：约 $4.63/PR（简单任务），需要 Max Mode
• 注意：代码在 Cursor 云端运行，需评估 Privacy Mode 的数据安全影响

BugBot：自动 Code Review

BugBot 是 Cursor 的 GitHub 集成代码审查工具：

• 工作方式：监听 PR → 分析 diff → 发现真实 bug → 在 GitHub 上留 inline 评论
• 关键指标：70%+ 的标记在合并前被解决（Cursor 官方数据）
• Effort 级别：Default（标准审查）、High（更深度分析）、Custom（自定义行为）
• Security Review（Beta，2026-04）：专门的安全审查 agent，检查漏洞和不安全模式
• 计费：从按座位转向按次计费（约 $1-1.50/次审查）
• SOC 2 Type II 认证

Cursor Hooks：工作流拦截

Cursor 3.1+ 支持 Hooks，类似 Claude Code 的 hooks 但更轻量：

.cursor/hooks/
├── onPreEdit      # Agent 编辑文件前执行
├── onPostEdit     # Agent 编辑文件后执行
├── onPreCommit    # Git commit 前执行
└── onApprove      # 用户审批操作时执行

Hooks 可以做自动格式化、lint 检查、安全扫描等。目前不如 Claude Code 的 26 个 hook 点丰富，但覆盖了最常用的拦截场景。

Cursor SDK：编程式 Agent

2026-04-29 发布的 TypeScript SDK（@cursor/sdk），支持三种运行模式：

上下文管理

Cursor 的上下文由多个来源组合，新的 Context Usage Breakdown UI 可以看到每个来源的 token 消耗：

@ Mention 系统：@file（文件）、@folder（目录）、@docs（外部文档）、@code（代码符号）、@web（网络搜索）、@diff（未提交变更）、@terminal（终端输出）、@rules（规则文件）、@definitions（类型定义）。

Max Mode 扩大上下文窗口用于复杂任务，Background Agent 必须使用 Max Mode。

Cursor CLI：终端 agent

cursor-agent 是 Cursor 的终端形态，支持四种模式：

# Agent 模式（默认）：自主执行，运行命令，编辑文件
cursor-agent "给 auth 模块补充单元测试"

# Plan 模式：只返回计划不执行，适合审查
cursor-agent --plan "审查 PR #42 的安全性"

# Ask 模式：问答，不修改文件
cursor-agent --ask "这个项目用的是什么测试框架"

# Shell 模式：交互式终端会话
cursor-agent --shell

# Headless 模式：CI/CD 集成
cursor-agent --headless "运行 lint 并修复所有可自动修复的问题"

CLI 复用 IDE 的 Rules、MCP 配置和认证，支持与 IDE 相同的模型选择（GPT-5.5 Extra High、Composer 2.5、Opus 4.7、Gemini 3.1 Pro、Grok 4.3 等）。Pro+ 及以上订阅包含 CLI 访问。

学习资料

生态项目与能带来的东西

1. Rules / AGENTS.md 工作流

2. MCP 与外部工具

3. 研究与评测

Cursor 与其他 AI Coding 工具的定位差异

Cursor 核心机制对比

Rules 模板

通用项目规则

---
description: General project rules
globs:
alwaysApply: true
---

## Project Context

- Stack: TypeScript / React / Node.js
- Package manager: pnpm
- Main entry points: src/index.ts
- Important directories: src/, tests/, migrations/

## Commands

- Install: pnpm install
- Lint: pnpm lint
- Type check: pnpm typecheck
- Test: pnpm test
- Build: pnpm build

## Coding Rules

- Follow existing patterns.
- Keep changes scoped to the requested task.
- Add or update tests for public behavior changes.
- Do not introduce new dependencies without explanation.

## Safety

- Do not touch .env* files.
- Do not run destructive commands without explicit approval.
- Ask before changing database migrations.

目录级规则示例

---
description: API route conventions
globs: ["src/api/**/*.ts"]
---

## API Route Rules

- All routes must have input validation (zod schema).
- All routes must return typed responses.
- Error handling uses the centralized error middleware.
- Rate limiting is configured per route in route config.

使用场景分类

适合优先尝试

• 日常编辑器内代码补全（Tab）
• 项目级问答和代码导航
• 小到中型功能开发（Agent Mode）
• 局部重构、inline edit、测试生成
• 前端 UI 修改和快速反馈
• 团队规则沉淀到 .cursor/rules
• 用 Bug Finder 做代码质量检查

适合谨慎尝试

• 大规模自动重构（建议用 Background Agent + 人工审查）
• 没有测试覆盖的核心逻辑修改
• YOLO Mode 全自动执行
• 过度依赖 rules 替代代码审查
• 给 MCP server 过宽的外部工具权限

不建议直接交给 Cursor

• 生产数据库写操作
• 密钥、部署、权限相关高风险变更
• 无人工 review 的自动合并
• 没有回滚方案的核心架构迁移

评测维度建议

定价与模型支持

订阅方案

2025-06 起改为 Credit 计费制，每次模型调用按成本消耗 credit。Auto 模式在所有付费方案中无限使用。

支持模型

近期版本时间线

当前判断

Cursor 的核心优势是 把 AI 放进开发者最常用的编辑器工作流。它很适合日常开发提效和中小型功能实现，但评测时不能只看"能不能跑"，还要看长期可维护性、规则遵守和人工 review 成本。

Cursor 在 AI Coding 工具生态中的独特定位：最低上手门槛 + 最高日常使用频率。不需要切换到终端或学习新工具链，直接在编辑器里获得 AI 能力。这使它成为 AI Coding 的最佳入门工具，但在需要精细控制的复杂场景下，Claude Code 和 Codex 的深度配置能力更强。

核心评测问题：

Cursor 能否在不牺牲可维护性和审查质量的前提下，稳定提升日常开发效率？

Background Agent 和 Bug Finder 的加入，是否让 Cursor 从"编辑器提效工具"进化为"可靠的工程代理"？