Cursor Chat：对话式编程

Chat 的三种模式

Cursor Chat（Cmd+L 打开）是 Cursor 的核心交互界面。在 Cursor 1.x 中，Chat 面板集成了三种不同的对话模式：

• Ask 模式（默认） 纯对话模式，AI 回答问题、解释代码、提供建议，但不会主动修改文件。适合探索性提问、代码审查、学习理解。回答中的代码块可以通过 Apply 按钮一键插入编辑器。
• Agent 模式 AI 不只是回答，而是主动执行操作：搜索代码库、读写文件、运行命令、调用 MCP 工具。适合需要 AI 做事、而不只是提建议的场景。详见第4章。
• Edit 模式（Composer） 专为多文件编辑设计，AI 可以同时修改多个文件，展示所有变更的合并 diff，统一预览和接受。详见第7章。

@ 引用系统详解

@ 引用系统是 Cursor Chat 最核心的差异化能力。通过在对话中输入 @ 符号，你可以精准地将项目中的各类资源引入 AI 上下文，让 AI 真正"看到"相关内容，而不是凭空猜测。

所有 @ 引用类型

@文件 引用

最基础也最常用的引用方式。在 Chat 中输入 @ 后开始键入文件名，会弹出模糊搜索下拉，选择即可。

// 示例对话：
// 用户：@auth.service.ts @user.model.ts
// 请帮我检查 login 方法的安全漏洞，特别是密码比对逻辑

// Cursor 会将两个文件的完整内容加入上下文，
// 然后基于真实代码做安全审查，而不是泛泛而谈

@Codebase — 最强大的引用

@Codebase 触发 Cursor 对整个代码库做 向量语义搜索：将你的问题转换为向量，在索引库中找出语义最相关的代码片段，注入上下文。 这意味着你可以问"项目里哪里处理了用户权限验证"，Cursor 会自动找到相关代码，不需要你知道文件名。

// 有效的 @Codebase 问法：
"@Codebase 项目里所有的数据库查询方法在哪里？用的是什么 ORM？"
"@Codebase 找出所有没有错误处理的 async 函数"
"@Codebase 项目的路由是如何组织的？有没有中间件层？"

// 不推荐的问法（太宽泛）：
"@Codebase 帮我理解整个项目"

@网页 引用

当你需要参考最新文档时，直接在 Chat 中输入完整 URL。Cursor 会抓取该页面内容并解析为文本，加入上下文。 这对于参考 API 变更日志、Stack Overflow 答案、GitHub Issue 讨论等场景极其便利。

// 示例：
"@https://docs.anthropic.com/claude/reference/messages-post
帮我写一个调用 Claude API 的 Python 函数，支持流式输出"

// Cursor 会读取最新的 API 文档，
// 生成符合当前 API 版本的代码，而不是基于训练数据里的旧版本

@Docs — 预配置文档索引

对于常用的第三方库，可以在 Cursor Settings → Features → Docs 中添加文档 URL，Cursor 会定期爬取并建立索引。 之后在 Chat 中可以用 @库名 快速引用，比每次粘贴 URL 方便。

代码库索引与语义搜索

Cursor 的代码库索引（Codebase Indexing）是其超越普通 AI 工具的核心基础设施。理解其工作原理，有助于更有效地利用它。

索引工作原理

1. 文件扫描：Cursor 扫描项目目录（排除 .cursorignore 中的路径）
2. 代码分块（Chunking）：将代码按函数、类、逻辑块切割为适当大小的片段
3. 向量编码（Embedding）：用专用模型将每个代码片段转换为高维向量，捕获语义信息
4. 存储索引：向量存储在本地向量数据库（如 FAISS），支持快速相似度检索
5. 增量更新：文件修改时，只重新索引变更部分

索引质量的影响因素

• 代码注释质量：有良好注释的代码被索引后语义更准确
• 函数命名：语义化的函数名（如 validateUserEmail）比 func1 检索效果好得多
• 文件大小：过大的文件（>1000行）会被截断，影响准确性
• .cursorignore 配置：排除无关文件（node_modules、build 产物）可提升搜索精度

上下文管理策略

AI 模型有上下文长度限制（通常 128K-200K tokens）。虽然 Cursor 会自动管理，但理解如何优化上下文选择，能显著提升回答质量。

精准上下文 vs 宽泛上下文

上下文 Token 预算管理

Chat 输入框底部会显示当前上下文的 token 用量。当 token 接近上限时：

• 开新对话（Cmd+N），从干净上下文开始
• 减少 @ 引用的文件数量
• 切换到支持更长上下文的模型（如 Gemini 2.0 Pro，支持 1M tokens）

Notepads — 持久化长期上下文

Notepads 是 Cursor 1.x 的重要功能，用于保存需要跨会话持续使用的上下文信息，如： 项目架构说明、技术栈决策、编码规范、常用代码模板。 通过 @NotepadName 在任何对话中引用。

// Notepad 示例内容（存储在 Cursor 的 Notepads 管理器中）

## 项目架构说明
- 前端：Next.js 14 App Router + TypeScript
- 后端：Node.js + Fastify + Prisma + PostgreSQL
- 认证：NextAuth.js v5，使用 JWT + Refresh Token
- 部署：Vercel（前端）+ Railway（后端）
- 测试：Vitest + Testing Library + Playwright (E2E)

## 命名规范
- 组件：PascalCase，文件名同名
- 函数：camelCase，动词开头
- 常量：UPPER_SNAKE_CASE
- 类型：PascalCase，接口以 I 开头（如 IUserProfile）

Apply 代码到编辑器

当 Chat 中 AI 给出代码块时，代码块右上角会出现 Apply 按钮。点击后：

1. Cursor 分析代码块应该插入到哪个文件（基于上下文判断）
2. 在目标文件中以 diff 形式展示变更
3. 你可以逐块接受或拒绝，或全部接受（Cmd+Enter）

Apply 的智能定位

Cursor 不会简单地将代码追加到文件末尾，而是智能判断应该 替换哪个函数、插入到哪个位置。 这基于语义匹配：如果 AI 生成了 function handleLogin()，Cursor 会找到文件中现有的 handleLogin 函数并替换它， 而不是另起一份。

Chat 历史与会话管理

Cursor 保留完整的 Chat 历史，可以随时回顾之前的对话。使用技巧：

• 新建对话（Cmd+N）：在当前任务完成后，开新对话避免上下文污染
• 对话命名：重要的对话可以手动命名，便于后续查找
• 对话复用：发现某个对话中的上下文对新任务有用时，可以直接继续，而不是重新设置
• 对话导出：可以将对话内容复制为 Markdown，用于文档或知识库

实战工作流

工作流一：Bug 调查

// Step 1：引入相关文件 + 描述问题
"@api/orders.ts @types/order.ts
用户反馈：提交订单时偶现 500 错误，从日志看是 'Cannot read properties of undefined'。
请帮我分析 createOrder 函数，找出可能为 undefined 的地方"

// Step 2：AI 指出问题后，继续追问
"@database/schema.ts
你提到 items 字段可能为空，但数据库 schema 里 items 是 NOT NULL。
这是数据层面的问题还是代码层面的问题？"

// Step 3：确认方案后，切换 Agent 模式执行修复
// （切换到 Agent）"现在帮我实现这个修复方案，并添加对应的单元测试"

工作流二：新功能开发

// Step 1：用 @Codebase 了解现有模式
"@Codebase 项目里如何处理文件上传？用的是什么库？返回格式是什么？"

// Step 2：引用相关代码，要求生成新功能
"@upload.service.ts 参考现有的上传服务，帮我实现一个支持批量上传图片、
自动压缩到 1MB 以下、返回 CDN URL 数组的函数"

// Step 3：Apply 并继续完善
"现在帮我为这个函数写单元测试，mock 掉 CDN 上传部分"