Prompting
基于 Cursor 官方 Prompting Agents 文档解释 @ mentions、图片、语音、context ring、上下文压缩和模型切换。
Prompting 是 Cursor Agent 的入口。官方文档说明，你可以在 chat input 里用文本指挥 Agent，附加 context、images、voice，并且可以在任意时点切换 models。
阅读目标：读完本章，你应该能写出带目标、上下文、验收和模型选择的 Cursor Agent prompt，并知道什么时候用 @，什么时候让 Agent 自己搜索。
1. Prompt 的最小结构
官方页讲的是输入能力；落到工程使用，prompt 至少要包含四类信息。
| 信息 | 写什么 | 示例 |
|---|---|---|
| 目标 | 这次要完成什么 | 修复登录页移动端按钮溢出 |
| 上下文 | 相关文件、报错、截图、终端输出 | @src/app/login/page.tsx 和截图 |
| 边界 | 允许和禁止做什么 | 只改登录页，不改认证逻辑 |
| 验收 | 怎么证明完成 | 跑 lint，390px 截图无横向滚动 |
flowchart TD
Prompt["Prompt"] --> Goal["目标"]
Prompt --> Context["@ mentions / images / terminals / browser"]
Prompt --> Constraints["边界和禁止项"]
Prompt --> Validation["验收方式"]
Context --> Agent["Cursor Agent"]
Validation --> Evidence["Diff / tests / screenshots / logs"]不建议写成“帮我优化一下”。这会让 Agent 同时猜目标、猜文件、猜验收标准。
2. @ mentions
官方文档说明：在 chat input 输入 @ 可以把特定 context 附加到 prompt。继续输入关键词后，Cursor 会显示匹配建议。
| Mention | 用途 |
|---|---|
@auth.ts | 附加具体文件 |
@src/components/ | 附加目录；选中目录后输入 / 可以继续深入 |
@Docs | 搜索 indexed documentation，也可以通过 @Docs > Add new doc 添加自己的文档 |
@Terminals | 把 terminal output 加入上下文 |
@Past Chats | 引用之前 conversation 的上下文 |
@Commit (Diff of Working State) | 附加未提交变更 diff |
@Branch (Diff with Main) | 附加当前 branch 相对 main 的 diff |
@Browser | 附加 built-in browser 的上下文 |
官方还给出一个重要边界：当你知道哪些文件相关时，用 @。如果不确定哪些文件重要，可以不手动附加，让 Agent 通过自己的搜索找相关文件。
3. 图片和语音输入
官方支持把 image attached 到 prompt，给 UI、debugging 和 design implementation 提供视觉上下文。
| 输入 | 操作 | 适合场景 |
|---|---|---|
| 图片拖拽 | 把图片文件拖到 chat input | 设计稿、UI 截图、视觉 bug |
| 剪贴板粘贴 | Cmd+V 粘贴截图 | 报错截图、浏览器状态、stack trace |
| 语音 | 点击 chat input 中的 microphone icon | 长任务口述、快速记录复杂现象 |
使用语音时，官方建议自然描述，并包含文件名、函数名等技术细节；发送前要检查 transcription。
4. Context ring 和上下文压缩
每个 chat 都有固定 context window（上下文窗口，模型一次能看到的总信息量）。随着文件、工具调用和对话变多，tokens（词元，模型读 / 写文本的最小单位）会逐渐填满窗口；接近满时，Cursor 会把旧对话压缩成 summary，为新对话腾出空间。
官方文档说明，prompt input 旁边的 context ring（上下文环，输入框旁的圆形进度条）可以快速看窗口占用。点击后会打开 breakdown tray，按类别展示 token 使用。
| 类别 | 代表内容 |
|---|---|
| System prompt | Cursor 内置模型指令 |
| Tools | Agent 可用工具定义 |
| Rules | project rules 和 user rules |
| Skills | 注入 system context 的 skill descriptions |
| MCP | 已连接 MCP servers 的说明和 catalog |
| Subagents | Agent 可启动的 subagent 类型文档 |
| Summarized conversation | 早期 turns 的压缩摘要 |
| Conversation | 用户消息、Agent 回复和工具结果 |
你可以 hover bar segment 或列表行，查看对应类别高亮。实际排障时，这个入口能帮助判断：是不是附加了太多无关文件、旧 conversation 是否挤占上下文、rules 或 MCP 是否占用过大。
深读：什么时候应该新开 chat，而不是继续追问
Cursor 会压缩旧对话，但压缩不等于完整保真。一个 chat 里任务太多时，Agent 可能同时背着旧目标、旧 diff、旧错误假设和新需求。
如果你已经换了任务、换了文件范围、换了验收标准，最好新开 chat。旧 chat 适合延续同一个任务，不适合把十几个互不相关的问题串成一条长链。
5. 切换模型
官方文档说明，可以用 chat input 顶部的 model picker dropdown 切换模型，也可以按 Cmd+/ 循环切换。切换会影响当前 conversation 之后的内容。默认模型在 Cursor Settings > Models 设置。
| 任务类型 | 模型倾向 |
|---|---|
| 快速小改、常规编辑、机械调整 | Faster models |
| 复杂推理、多文件重构、架构判断 | More capable models |
| 先探索再实现 | 可以先用更快模型探索，再切更强模型做实现 |
模型列表和价格变化快，具体可用模型以官方 Models & Pricing 页面为准。
6. Prompt 模板
可以把下面这个结构作为商业项目的最小 prompt。
目标：
修复 / 实现 / 分析什么。
上下文：
@相关文件、@Terminals、@Browser、截图或错误信息。
范围：
允许修改哪些文件；哪些文件或行为禁止改。
验收：
需要运行哪些命令、检查哪些页面、留下什么证据。
过程要求：
先说明计划；有风险先停下来；完成后列出 diff 和验证结果。本章自检
完成本章后，用这 3 个问题检查自己是否真正理解：
- 什么时候应该手动使用
@mentions，什么时候让 Agent 自己搜索？ - Context ring 能帮助你发现哪些问题？
- 为什么模型可以在同一个 conversation 中切换？
通过标准：你能把一个模糊需求改写成包含目标、上下文、边界、验收和模型选择的 Cursor prompt。
官方来源
- Cursor Prompting Agents —— 官方说明 chat input、
@mentions、image input、voice input、context usage 和 changing models。 - Cursor Models & Pricing —— 官方模型列表、模型能力和价格信息，以当前页面为准。