---
title: "Agent 總覽"
description: "基於 Cursor 官方 Agent 文件解釋 instructions、tools、model、checkpoints、queue 和模式選擇。"
verifiedAt: "2026-05-09"
---

Cursor Agent 是能獨立完成複雜編碼任務的助手。官方文件說明，它可以編輯程式碼、執行 terminal commands、搜尋程式碼庫和 web，並圍繞不同 frontier models 調整 instructions 和 tools。

學習 Agent 的關鍵不是“它能不能改程式碼”，而是理解三件事：它由 instructions、tools、model 組成；它會在任務中呼叫很多工具；它會用 checkpoints 和 queued messages 支撐更長的迭代。

> [!NOTE]
> **閱讀目標**：讀完本章，你應該能判斷什麼時候用 Agent、Ask、Plan、Debug，並知道 Agent 做任務時哪些證據必須審查。

## 1. Agent 的三個組成部分

官方 Agent 文件把 agent 拆成三部分。

| 元件 | 官方含義 | 你要控制什麼 |
| --- | --- | --- |
| Instructions | system prompt（系統提示詞，模型每次推理前看到的隱性指令）和 rules，指導 agent 行為 | 專案 rules、團隊約束、任務邊界 |
| Tools | 檔案編輯、程式碼庫搜尋、terminal、browser 等 | 哪些工具可用，哪些要人工確認 |
| Model | 你為任務選擇的 agent model | 複雜度、成本、上下文和速度 |

Cursor 會為不同模型調整 instructions 和 tools。使用者不需要手工適配每個模型，但仍要定義任務邊界和驗收方式。

```mermaid
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。

> [!IMPORTANT]
> Checkpoint 能幫你撤回 Agent 的一次錯誤方向，但不能代替 commit、branch、PR 和 code review。

## 4. Queued messages 和立即訊息

官方文件說明，Agent 工作時可以排隊後續指令：

| 操作 | 行為 |
| --- | --- |
| 輸入下一條並按 Enter | 加入 queue，等當前任務完成後順序執行 |
| 拖動 queued messages | 調整執行順序 |
| `Cmd+Enter` | 立即傳送，繞過 queue，追加到最近 user message |

實操上，排隊適合“等當前小步驟結束後繼續”。如果 Agent 已經走偏，用 Stop 或立即訊息重定向，不要連續塞多個互相沖突的 queued messages。

<details>
<summary>深讀：為什麼 Agent 工具越多，任務邊界越重要</summary>

Cursor Agent 可以搜尋、讀檔案、改檔案、跑命令、控瀏覽器、生成圖片和提問。工具越多，它越容易把一個模糊目標擴充套件成一串副作用動作。

所以商業級 prompt 必須寫目標、範圍、允許工具、禁止動作和驗收證據。比如“只讀解釋當前目錄，不要修改檔案”與“修復並執行測試”是完全不同的授權級別。
</details>

## 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 個問題檢查自己是否真正理解：

1. Cursor Agent 的 instructions、tools、model 各自負責什麼？
2. Checkpoints 和 Git 的邊界是什麼？
3. Ask、Agent、Plan、Debug 分別適合什麼任務？

透過標準：你能給一個真實任務選擇模式，並寫清楚允許工具、回退方式和驗收證據。

## 官方來源

- [Cursor Agent Overview](https://cursor.com/docs/agent/overview.md) —— 官方說明 Agent 三元件、tools、checkpoints 和 queued messages。
- [Cursor Agent Help](https://cursor.com/help/ai-features/agent.md) —— Help Center 說明 Agent mode、Ask / Plan / Debug、Restore Checkpoint 和模式切換。

## 接下來去哪

<Cards>
  <Card title="Plan Mode" description="較大任務先進入 Plan Mode，審查方案再構建。" href="/zh-Hant/docs/cursor/official/01-agent-workflow/12-plan-mode" />
  <Card title="Agent Review" description="改完以後用 Agent Review 審查本地變更。" href="/zh-Hant/docs/cursor/official/01-agent-workflow/15-agent-review" />
</Cards>
