---
title: "Prompting"
description: "基于 Cursor 官方 Prompting Agents 文档解释 @ mentions、图片、语音、context ring、上下文压缩和模型切换。"
verifiedAt: "2026-05-09"
---

Prompting 是 Cursor Agent 的入口。官方文档说明，你可以在 chat input 里用文本指挥 Agent，附加 context、images、voice，并且可以在任意时点切换 models。

> [!NOTE]
> **阅读目标**：读完本章，你应该能写出带目标、上下文、验收和模型选择的 Cursor Agent prompt，并知道什么时候用 `@`，什么时候让 Agent 自己搜索。

## 1. Prompt 的最小结构

官方页讲的是输入能力；落到工程使用，prompt 至少要包含四类信息。

| 信息 | 写什么 | 示例 |
| --- | --- | --- |
| 目标 | 这次要完成什么 | 修复登录页移动端按钮溢出 |
| 上下文 | 相关文件、报错、截图、终端输出 | `@src/app/login/page.tsx` 和截图 |
| 边界 | 允许和禁止做什么 | 只改登录页，不改认证逻辑 |
| 验收 | 怎么证明完成 | 跑 lint，390px 截图无横向滚动 |

```mermaid
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 是否占用过大。

<details>
<summary>深读：什么时候应该新开 chat，而不是继续追问</summary>

Cursor 会压缩旧对话，但压缩不等于完整保真。一个 chat 里任务太多时，Agent 可能同时背着旧目标、旧 diff、旧错误假设和新需求。

如果你已经换了任务、换了文件范围、换了验收标准，最好新开 chat。旧 chat 适合延续同一个任务，不适合把十几个互不相关的问题串成一条长链。
</details>

## 5. 切换模型

官方文档说明，可以用 chat input 顶部的 model picker dropdown 切换模型，也可以按 `Cmd+/` 循环切换。切换会影响当前 conversation 之后的内容。默认模型在 **Cursor Settings > Models** 设置。

| 任务类型 | 模型倾向 |
| --- | --- |
| 快速小改、常规编辑、机械调整 | Faster models |
| 复杂推理、多文件重构、架构判断 | More capable models |
| 先探索再实现 | 可以先用更快模型探索，再切更强模型做实现 |

模型列表和价格变化快，具体可用模型以官方 Models & Pricing 页面为准。

## 6. Prompt 模板

可以把下面这个结构作为商业项目的最小 prompt。

```text
目标：
修复 / 实现 / 分析什么。

上下文：
@相关文件、@Terminals、@Browser、截图或错误信息。

范围：
允许修改哪些文件；哪些文件或行为禁止改。

验收：
需要运行哪些命令、检查哪些页面、留下什么证据。

过程要求：
先说明计划；有风险先停下来；完成后列出 diff 和验证结果。
```

## 本章自检

完成本章后，用这 3 个问题检查自己是否真正理解：

1. 什么时候应该手动使用 `@` mentions，什么时候让 Agent 自己搜索？
2. Context ring 能帮助你发现哪些问题？
3. 为什么模型可以在同一个 conversation 中切换？

通过标准：你能把一个模糊需求改写成包含目标、上下文、边界、验收和模型选择的 Cursor prompt。

## 官方来源

- [Cursor Prompting Agents](https://cursor.com/docs/agent/prompting.md) —— 官方说明 chat input、`@` mentions、image input、voice input、context usage 和 changing models。
- [Cursor Models & Pricing](https://cursor.com/docs/models-and-pricing.md) —— 官方模型列表、模型能力和价格信息，以当前页面为准。

## 接下来去哪

<Cards>
  <Card title="Debug Mode" description="当 bug 需要运行时证据时，切到 Debug Mode。" href="/docs/cursor/official/01-agent-workflow/14-debug-mode" />
  <Card title="Rules 与上下文" description="继续理解项目规则如何进入 Cursor 上下文。" href="/docs/cursor/official/02-context-customization/20-rules" />
</Cards>
