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 —— 官方模型列表、模型能力和價格資訊，以當前頁面為準。