Cursor Agent 如何工作

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

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

1. Agent 的三件套

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

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

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 互相沖突，都會讓同一個任務出現完全不同的結果。

官方 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 示例：

目标：修复用户列表分页按钮在空数据时仍可点击的问题。
范围：只允许修改 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。

實操建議：

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

不要因為有 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 指令模板

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

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

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

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

等我确认计划后再执行。

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

官方來源

Cursor Agent Overview：官方說明 Agent 的 instructions、tools、model、checkpoints 和 queued messages。
Cursor Agent Help：Help Center 對 Agent、Ask、Plan、Debug、Restore Checkpoint 和模式切換的說明。
Cursor Documentation Index：官方 Agent、tools、Help Center 和 CLI 索引。

接下來去哪

先完成安裝、遷移和第一個低風險專案閉環。

理解 Agent、Plan、Ask、Debug 和 Tab 的分工。

官方 Agent 總覽

回到官方重組頁檢視 Agent 元件、tools 和 checkpoints。