Cursor Agent 实战手册

根据 Cursor 官方文档独立整理。涵盖本地 Agent、精确上下文、Project Rules、终端、MCP、审查、CLI、Cloud Agents、隐私和排错。

Cursor 从只读分析、计划、编辑、运行到审查的流程 — 每个阶段使用权限最低但足够的模式，接受修改前检查真实差异和测试结果。

1. 按风险选择模式

模式	用途	能力
Ask	学习、诊断、计划	只读搜索
Agent	多文件功能和修复	搜索、编辑、终端和修错
Manual	准确的小范围编辑	仅选中的文件
Custom	可复用专业流程	自选工具和说明

陌生工作从 Ask 开始；目标、范围、测试和禁止动作清楚后再使用 Agent。用 Ctrl+. 切换模式，Ctrl+I 打开 Agent。

2. 准备并索引代码库

打开项目根目录并检查 Git 状态。
等待代码库索引完成，检索不完整时检查索引状态。
用 .gitignore 和 .cursorignore 排除依赖、生成文件、密钥和隐私数据。
修改前先要求只读项目地图。

在 Ask 模式梳理代码库：入口、架构边界、构建和测试命令、数据存储、
部署文件及高风险区域。不要修改或运行命令。

3. 用 @ 提供精确上下文

用 @code 指定符号、@file 指定文件、@folder 指定有限模块，并附上权威网页或文档。精确引用可以减少无关检索。

@file:src/auth/session.ts @file:src/api/login.ts @code:refreshSession
复现界面一直加载的原因并引用准确控制流程。
不要检查或修改账单与客户导出模块。

4. 编写可验收任务并先计划

目标：登录成功必须打开 /admin。
验收：错误密码显示行内提示；加载状态一定结束；刷新保留有效会话；测试通过。
限制：不得重置数据库、升级依赖或修改生产环境。
先列出涉及文件、测试、风险和回滚计划，批准前不要编辑。

大范围修改应把计划和实现分开；Cloud Agent 也应在详细计划确认后再执行。

5. 用 Project Rules 固化规范

版本控制规则存放在 .cursor/rules 的 MDC 文件内，可设为 Always、按 glob 自动附加、由 Agent 根据描述请求，或用 @ruleName 手动引用。嵌套规则可限定单仓库内不同模块；全局偏好使用 User Rules；.cursorrules 已弃用。

---
description: Authentication safety and testing
globs: ["src/auth/**", "tests/auth/**"]
alwaysApply: false
---
- 不记录令牌或密码。
- 保持公开会话结构不变。
- 运行认证单元测试和登录浏览器测试。
- 增加依赖或修改迁移前先询问。

可用 /Generate Cursor Rules 从成熟对话生成规则，再人工精简。

6. 控制工具、终端和 MCP

Agent 工具包括搜索、读写与删除文件、终端、网页、Rules 和 MCP。自定义模式应关闭无关工具；陌生或高风险项目关闭 Auto-run。

按已批准计划实现，只修改列出的文件并运行针对性测试。
删除、安装依赖、迁移、联网、Git 提交或项目外命令必须先询问。
不得读取 .env 或凭据文件。

MCP 应核对发布者和启动方式，密钥不进入版本控制，先测试只读工具，外部写入必须审批。

7. 审查修改并验证行为

打开 Review changes，检查每一处增加和删除。
拒绝无关格式化或大范围重写。
运行 lint、类型检查、针对性测试和构建。
打开真实界面，检查成功、错误、加载、空状态和刷新。
确认 Git 状态中没有敏感文件。

逐项对照验收条件，列出准确命令、结果、修改文件和未验证内容。
不得只凭 HTTP 状态或智能体摘要判断成功，必须操作真实界面。

8. 安全使用 Cursor CLI

curl https://cursor.com/install -fsS | bash
cursor-agent
cursor-agent "解释认证模块；不要编辑"
cursor-agent -p "审查当前修改的安全问题" --output-format text
cursor-agent ls
cursor-agent resume

自动化默认使用只读审查任务、明确输出格式、受限环境和有限提示；任何写入或发布流程都要固定版本并审计。

9. 委派给 Cloud Agents

Cloud Agents 可从 Cursor、网页／移动端或支持的集成启动。只连接目标代码库，准备云端环境，使用独立分支，合并前人工审查。当前版本支持可复用环境快照、本地／云端交接，以及用 /in-cloud 启动隔离子智能体；/babysit 可持续检查拉取请求。

在新分支只实现已批准计划并运行文档规定的测试。
不得合并、部署、修改仓库设置或访问生产密钥。
返回差异摘要、证据、剩余风险和待审查的拉取请求。

10. 隐私和安全边界

在设置中选择合适的 Privacy Mode。Cursor 表示 AI 请求会经过其后端；索引时上传代码块计算嵌入，明文保存方式取决于隐私设置，嵌入和混淆元数据可能保留。路径排除属于尽力防护，高敏感代码库必须先取得组织批准并核对当前政策。

密钥不得进入提示、Rules、终端历史、日志或 MCP 配置。
禁止进入 AI 上下文的内容应关闭索引或排除。
删除、外部写入、提交、推送、合并和部署保留审批。
审查 Cloud Agent 的仓库、分支、环境和集成权限。

11. 常见问题

问题	检查
遗漏相关代码	索引、`.cursorignore`、准确 @ 引用、工作区根目录
规则未生效	类型、描述、glob、嵌套范围、手动引用
终端 Shell 错误	Terminal: Select Default Profile
MCP 工具缺失	服务、配置、凭据、启用工具和日志
修改循环或越界	停止并回到 Ask／计划，缩小上下文和验收范围
云端无法测试	环境快照、设置脚本、密钥、网络和服务依赖

12. 官方资料

资料来自官方 Agent 模式、工具、Rules、上下文、CLI、网页与移动端 Agent、隐私和更新日志。

编辑复核日期：2026 年 8 月 11 日。本页为独立手册，使用前请核对当前模式、模型、套餐、限制、命令、安全控制和数据政策。