Agent 總覽
基於 Cursor 官方 Agent 文件解釋 instructions、tools、model、checkpoints、queue 和模式選擇。
Cursor Agent 是能獨立完成複雜編碼任務的助手。官方文件說明，它可以編輯程式碼、執行 terminal commands、搜尋程式碼庫和 web，並圍繞不同 frontier models 調整 instructions 和 tools。
學習 Agent 的關鍵不是“它能不能改程式碼”，而是理解三件事：它由 instructions、tools、model 組成；它會在任務中呼叫很多工具；它會用 checkpoints 和 queued messages 支撐更長的迭代。
閱讀目標：讀完本章，你應該能判斷什麼時候用 Agent、Ask、Plan、Debug，並知道 Agent 做任務時哪些證據必須審查。
1. Agent 的三個組成部分
官方 Agent 文件把 agent 拆成三部分。
| 元件 | 官方含義 | 你要控制什麼 |
|---|---|---|
| Instructions | system prompt（系統提示詞，模型每次推理前看到的隱性指令）和 rules，指導 agent 行為 | 專案 rules、團隊約束、任務邊界 |
| Tools | 檔案編輯、程式碼庫搜尋、terminal、browser 等 | 哪些工具可用，哪些要人工確認 |
| Model | 你為任務選擇的 agent model | 複雜度、成本、上下文和速度 |
Cursor 會為不同模型調整 instructions 和 tools。使用者不需要手工適配每個模型，但仍要定義任務邊界和驗收方式。
flowchart TD
Goal["使用者任務"] --> Agent["Cursor Agent"]
Agent --> Instructions["Instructions / Rules"]
Agent --> Tools["Tools"]
Agent --> Model["Model"]
Tools --> Search["Codebase / Web search"]
Tools --> Edit["Read / Edit files"]
Tools --> Terminal["Run shell commands"]
Tools --> Browser["Browser screenshots / tests"]
Edit --> Diff["Diff view"]
Terminal --> Output["Command output"]
Browser --> Evidence["Visual evidence"]2. Tools 是 Agent 的工作手
官方列出的 tools 包括：
| Tool | 用途 |
|---|---|
| Semantic search | 在 indexed codebase 中按含義搜尋 |
| Search files and folders | 找檔名、目錄結構、關鍵詞和 pattern |
| Web | 生成搜尋查詢並執行 web searches |
| Fetch Rules | 根據 type 和 description 獲取相關 rules |
| Read files | 讀取文本和圖片檔案，並把圖片加入視覺模型上下文 |
| Edit files | 建議並應用檔案編輯 |
| Run shell commands | 執行 terminal 命令並監控輸出 |
| Browser | 控制瀏覽器截圖、測試應用、驗證視覺變化 |
| Image generation | 生成 UI mockup、產品素材或架構圖 |
| Ask questions | 任務中提出澄清問題 |
官方還說明 Agent 一次任務中的 tool calls 沒有數量上限。對真實專案來說，這意味著你不能只看最終回覆，要看它到底讀了什麼、改了什麼、跑了什麼命令。
3. Checkpoints 是本地回退，不是 Git 替代
官方文件說明，Agent 會在重要改動前自動建立 checkpoints，儲存 modified files 的狀態。如果 Agent 走錯，可以在 chat timeline 中點選 checkpoint 預覽並 restore。
關鍵邊界：
- Checkpoints 存在本地。
- 它們和 Git 分開。
- 只適合撤銷 Agent changes。
- 永久版本管理仍然用 Git。
Checkpoint 能幫你撤回 Agent 的一次錯誤方向，但不能代替 commit、branch、PR 和 code review。
4. Queued messages 和立即訊息
官方文件說明，Agent 工作時可以排隊後續指令：
| 操作 | 行為 |
|---|---|
| 輸入下一條並按 Enter | 加入 queue，等當前任務完成後順序執行 |
| 拖動 queued messages | 調整執行順序 |
Cmd+Enter | 立即傳送，繞過 queue，追加到最近 user message |
實操上，排隊適合“等當前小步驟結束後繼續”。如果 Agent 已經走偏，用 Stop 或立即訊息重定向，不要連續塞多個互相沖突的 queued messages。
深讀：為什麼 Agent 工具越多，任務邊界越重要
Cursor Agent 可以搜尋、讀檔案、改檔案、跑命令、控瀏覽器、生成圖片和提問。工具越多，它越容易把一個模糊目標擴充套件成一串副作用動作。
所以商業級 prompt 必須寫目標、範圍、允許工具、禁止動作和驗收證據。比如“只讀解釋當前目錄，不要修改檔案”與“修復並執行測試”是完全不同的授權級別。
5. 模式選擇
官方 Help Center 給出四種模式判斷。
| Mode | Best for | Can edit files |
|---|---|---|
| Agent | 構建功能、重構、修 bug | Yes |
| Ask | 理解程式碼、探索架構 | No |
| Plan | 複雜功能，先審方案 | Yes，審批後 |
| Debug | 需要執行時證據的疑難 bug | Yes |
切換方式：
Shift + Tab迴圈模式。- Agent panel 的 mode picker dropdown。
官方提醒：每個 mode 使用自己的 context，切換模式會開啟新的 context window；換任務最好開新 chat。
本章自檢
完成本章後，用這 3 個問題檢查自己是否真正理解：
- Cursor Agent 的 instructions、tools、model 各自負責什麼？
- Checkpoints 和 Git 的邊界是什麼？
- Ask、Agent、Plan、Debug 分別適合什麼任務？
透過標準：你能給一個真實任務選擇模式，並寫清楚允許工具、回退方式和驗收證據。
官方來源
- Cursor Agent Overview —— 官方說明 Agent 三元件、tools、checkpoints 和 queued messages。
- Cursor Agent Help —— Help Center 說明 Agent mode、Ask / Plan / Debug、Restore Checkpoint 和模式切換。