---
title: "Cursor Agent 如何工作"
description: "理解 instructions、tools、model、checkpoints、queued messages 和模式選擇。"
verifiedAt: "2026-05-09"
---

Cursor Agent 的穩定性來自結構，不是來自"模型更聰明"這一句話。官方 Agent 文件把它拆成三部分：instructions、tools、model。你寫的任務、專案 rules、可用工具、模型選擇和驗證方式，會共同決定 Agent 的行為邊界。

> [!NOTE]
> **本章目標**：你會知道 Agent 為什麼能跨檔案完成任務，也會知道它什麼時候容易失控，以及如何用 Ask、Agent、Plan、Debug、checkpoints 和 diff review 把風險壓住。

## 1. Agent 的三件套

Agent 每次工作都在組合三類輸入：

- **Instructions**：system prompt（系統提示詞，模型每次推理前看到的隱性指令）、rules、使用者 prompt 和當前任務邊界。
- **Tools**：讀檔案、改檔案、搜尋程式碼庫、執行 terminal、使用 browser、web search、MCP 等能力。
- **Model**：承擔推理和生成的模型，不同任務適合不同複雜度和成本。

```mermaid
flowchart TD
  Task["User Task"] --> Agent["Cursor Agent"]
  Agent --> Instructions["Instructions / Rules"]
  Agent --> Tools["Tools"]
  Agent --> Model["Model"]
  Tools --> Read["Read Files"]
  Tools --> Edit["Edit Files"]
  Tools --> Terminal["Run Shell Commands"]
  Tools --> Browser["Browser"]
  Tools --> MCP["MCP Servers"]
  Edit --> Diff["Diff"]
  Terminal --> Logs["Command Output"]
  Browser --> Evidence["Visual Evidence"]
```

只要其中一項不清楚，Agent 就會不穩定。例如 prompt 沒有範圍，tools 許可權太寬，model 選得過輕，或者專案 rules 互相沖突，都會讓同一個任務出現完全不同的結果。

## 2. Tools 是能力，也是副作用入口

官方 Agent 文件列出多類 tools，包括 semantic search（語義搜尋，按含義而不是關鍵字找程式碼）、file search（按檔名 / 目錄結構搜尋）、web（生成搜尋查詢並搜網）、fetch rules（按需調取專案 rule）、read files（讀檔案，含圖片）、edit files（改檔案）、run shell commands（跑命令）、browser（控制瀏覽器截圖 / 點選 / 讀 console + network）、image generation（影像生成）和 ask questions（澄清問題）——單次任務裡工具呼叫次數不設上限。

這些 tools 讓 Agent 能完成真實開發任務，但也帶來副作用：

- **Read files** 會把原生代碼、圖片和配置送進上下文。
- **Edit files** 會改變 working tree（工作樹，git 裡你當前看到的檔案狀態，未提交的改動也算）。
- **Run shell commands** 可能啟動服務、安裝依賴、刪除檔案或觸發指令碼。
- **Browser** 可以訪問本地頁面和外部頁面。
- **MCP** 可以連線資料庫、GitHub、文件、任務系統或內部工具。

所以商業級用法不是“預設全開”，而是按任務授權。

安全 prompt 示例：

```text
目标：修复用户列表分页按钮在空数据时仍可点击的问题。
范围：只允许修改 src/components/UserTable.tsx 和相关测试。
工具：可以读取文件，可以运行 pnpm test -- UserTable；不要安装依赖，不要改配置。
流程：先给计划，等我确认后再修改。
验收：输出 diff 摘要、测试结果、未覆盖风险。
```

這類 prompt 不會讓 Agent 更慢，反而會減少誤操作和返工。

## 3. Checkpoints 是撤銷機制，不是版本管理

Cursor 會在重要改動前建立 checkpoints，儲存 modified files 的狀態。Agent 走錯時，你可以在 chat timeline 裡預覽並 restore。

但要記住邊界：

- Checkpoints 是本地回退點。
- 它們主要針對 Agent changes。
- 它們和 Git 分開。
- 它們不能替代 branch、commit、PR 和 code review。

實操建議：

1. 任務開始前看 Git status。
2. 小任務直接依賴 diff review。
3. Agent 改偏時先看 checkpoint preview。
4. 重要工作仍然用 Git branch 和 commit 固化。

> [!IMPORTANT]
> 不要因為有 checkpoint 就批准大範圍修改。checkpoint 適合撤錯方向，不適合管理長期版本歷史。

## 4. Queued messages 適合序列，不適合混亂指揮

官方文件說明，Agent 工作時可以把後續 messages 加入 queue；也可以用 `Cmd+Enter` 立即傳送，追加到最近 user message。

推薦用法：

- **Enter 排隊**：當前任務還在跑、下一步很明確、不需要打斷當前工作時用。
- **Cmd / Ctrl + Enter 立即傳送**：Agent 已經偏離方向、需要立即重定向時用——訊息會附在最近一條 user message 後立即進入推理。
- 不要連續 queue 多條互相矛盾的要求。
- 不要在 Agent 正改檔案時不斷追加"順便再改"。

佇列讓長任務更順，但它不是專案管理系統。範圍變大時，應停下來重新定義任務。

## 5. 四種模式怎麼選

Cursor Help Center 把常見 AI modes 分成 Agent、Ask、Plan、Debug。理解模式比記住快捷鍵更重要。

- **Ask**：只讀理解程式碼、解釋架構、找入口、評估風險。預設不改檔案。
- **Agent**：執行小到中等任務，適合有明確目標和驗證方式的改動。
- **Plan**：複雜任務先給方案，適合跨模組功能、重構、遷移。
- **Debug**：需要執行時證據的 bug，適合日誌、復現、斷點、瀏覽器和終端配合。

切換模式可以用 mode picker，也可以用 `Shift + Tab`。官方提醒不同 mode 有自己的 context，換任務時最好開新 chat。

## 6. 判斷 Agent 是否健康

健康的 Agent 通常有這些跡象：

- 先讀相關檔案，而不是立刻改。
- 能說明為什麼這些檔案是入口。
- 計劃裡寫清楚改動範圍和驗證方式。
- 每次修改範圍可審查。
- 會執行目標檢查，並報告失敗原因。
- 總結和真實 diff 一致。

不健康的跡象：

- 沒看程式碼就給大方案。
- 自動擴大範圍，修改無關檔案。
- 遇到測試失敗就跳過或改測試迎合實現。
- 用“應該沒問題”替代驗證。
- 總結說修好了，但 diff 和命令輸出對不上。

## 7. 推薦第一條 Agent 指令模板

可以把這個模板作為起點：

```text
你在一个已有 Git 项目里工作。先只读分析，不要修改文件。

任务：
[写清楚要解决的问题]

请先输出：
1. 你需要读取哪些文件
2. 初步根因或实现路径
3. 最小修改范围
4. 需要运行的验证命令
5. 风险和停止条件

等我确认计划后再执行。
```

這條模板的重點不是格式，而是許可權分離：先理解，再計劃，再批准，再寫入，再驗證。

## 官方來源

- [Cursor Agent Overview](https://cursor.com/docs/agent/overview.md)：官方說明 Agent 的 instructions、tools、model、checkpoints 和 queued messages。
- [Cursor Agent Help](https://cursor.com/help/ai-features/agent.md)：Help Center 對 Agent、Ask、Plan、Debug、Restore Checkpoint 和模式切換的說明。
- [Cursor Documentation Index](https://cursor.com/llms.txt)：官方 Agent、tools、Help Center 和 CLI 索引。

## 接下來去哪

<Cards>
  <Card title="上一篇" description="先完成安裝、遷移和第一個低風險專案閉環。" href="/zh-Hant/docs/cursor/understanding/02-install-migrate-first-project" />
  <Card title="下一篇" description="理解 Agent、Plan、Ask、Debug 和 Tab 的分工。" href="/zh-Hant/docs/cursor/understanding/04-agent-plan-ask-debug-tab" />
  <Card title="官方 Agent 總覽" description="回到官方重組頁檢視 Agent 元件、tools 和 checkpoints。" href="/zh-Hant/docs/cursor/official/01-agent-workflow/10-agent-overview" />
</Cards>
