---
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="/zh-Hant/docs/cursor/official/01-agent-workflow/14-debug-mode" />
  <Card title="Rules 與上下文" description="繼續理解專案規則如何進入 Cursor 上下文。" href="/zh-Hant/docs/cursor/official/02-context-customization/20-rules" />
</Cards>
