提到 Cursor，大部分人想到的是那個 AI-first 的程式碼編輯器——在 IDE 裡面跟 AI 對話、讓它幫你改 code、解釋 code。但其實 Cursor 還有一個很多人不知道（或知道但沒深入用過）的東西：Cursor Agent CLI，也就是 cursor-agent 這個命令列工具。它把 Cursor 的 AI 能力從 GUI 帶到了終端機，這意味著你可以在腳本裡呼叫它、在 CI/CD pipeline 裡用它、甚至讓另一個 AI 來呼叫它。
這件事聽起來好像只是「換個介面」，但它打開了一個全新的可能性：AI coding 不再綁定在「人坐在 IDE 前面」這個場景。它可以變成自動化流程的一環，被其他程式、其他 agent 來呼叫。這才是真正讓我興奮的地方。
為什麼要用 CLI？
直覺的問題是：IDE 裡面用得好好的，為什麼要搬到 CLI？
幾個原因：
- 自動化：IDE 需要人坐在前面操作，CLI 可以被腳本驅動
- 可組合：CLI 工具天生就能跟其他工具串接（shell pipe、程式呼叫）
- 輕量：不用開一整個 Electron app，在 server 上或 CI 環境就能跑
- 可控制：輸出格式可以指定為 JSON，方便程式解析
- 批量操作：可以同時開多個 cursor-agent process 處理不同任務
我自己最常用的場景是在另一個 AI 助理裡呼叫 cursor-agent 來做 codebase 分析和程式碼修改。比起自己寫 AST parser 或 grep 大法，讓一個理解 code 的 agent 來回答問題實在方便太多了。
基本用法
最簡單的用法就是一行指令：
1 | cursor-agent -p "幫我看一下 src/utils.js 有沒有未使用的 function" |
-p 就是 prompt，跟你在 IDE 裡打的 chat 一樣。執行後 cursor-agent 會分析你當前目錄的 codebase，然後回答你的問題或直接改 code。
這個指令看起來簡單，但背後 agent 做的事情不少：它會掃描當前目錄的檔案結構、讀取相關的程式碼、分析你的問題、然後決定要回答還是動手改。如果是改 code 的請求，它還會自己找到要改的檔案、做出修改、甚至跑 build 確認沒有壞掉。
指定模型
cursor-agent 支援多種 LLM 模型，可以用 --model 指定：
1 | cursor-agent -p "重構這個 function" --model sonnet-4.5-thinking |
目前支援超過 20 種模型，包括 GPT-5.2、Claude 4.5、Gemini 3 等主流模型。不同模型的特性不同，像是需要深度思考的問題我會用 thinking 系列的模型，簡單的格式調整就用比較快的模型。
模型的選擇其實對結果影響蠻大的。我的經驗是：
- 簡單的格式修改、rename 之類的 → 用快速模型，省時省錢
- 複雜的邏輯重構、架構分析 → 用 thinking 模型，品質差很多
- 不確定的時候 → 先用 ask mode + 快速模型看看回答品質，不夠好再換
Force 模式
預設情況下，cursor-agent 在執行有副作用的操作前會先問你確認。如果你確定要讓它放手去做，可以加 --force：
1 | cursor-agent -p "把所有 var 改成 const" --force |
這個很危險但很高效。建議只在你有 git 保護（可以隨時 revert）的情況下使用。我自己的習慣是：local 開發可以 force，production 相關的絕對不 force。
我有過一次慘痛經驗：在一個沒有 commit 的狀態下用了 --force，agent 改了一堆檔案，結果有幾個改壞了。因為沒有 commit point 可以 revert，只好手動一個一個檔案去比對修復。從此之後我養成了一個鐵律：force 之前先 commit，或至少 stash。
PTY 限制
有一個蠻重要的限制：cursor-agent 必須在 PTY（pseudo-terminal）環境下跑。你不能直接用 pipe 把 prompt 導進去，像這樣是不行的：
1 | # 這不會正常運作 |
原因是 cursor-agent 的互動介面需要 terminal 的控制能力（顏色、游標位置等）。如果你要在程式裡呼叫它，需要用 PTY library 來包裝，比如 Node.js 的 node-pty 或 Python 的 pexpect。
這一點在自動化整合的時候特別要注意，我一開始沒注意到這個限制，試了好幾種 spawn 方式都失敗，後來才發現要用 PTY。錯誤訊息也不是很直觀，它不會告訴你「需要 PTY」，而是直接 hang 住或輸出亂碼，讓你摸不著頭緒。
三種模式
cursor-agent 有三種操作模式，各有各的適用場景：
1. Code Mode（預設）
1 | cursor-agent -p "新增一個 retry mechanism 到 API client" --mode code |
這是最常用的模式。agent 會分析你的 codebase，然後直接寫 code 並執行修改。它會讀檔、改檔、甚至跑 build 和 test。
適合的場景：你已經知道要做什麼，讓 agent 去實作。
Code mode 的厲害之處在於它不只是生成 code 片段讓你貼上去——它會自己找到要修改的檔案、判斷修改位置、處理 import、甚至調整相關的 test。這跟在 IDE 裡用 AI 的體驗是不一樣的，因為 CLI 的 agent 有更大的自主權。
2. Plan Mode
1 | cursor-agent -p "怎麼把這個 monorepo 拆成 microservices" --mode plan |
Plan mode 只會產出計畫，不會實際動任何檔案。它會分析 codebase，然後告訴你「我打算做 A、B、C 這幾件事，改這些檔案」。
這個模式我超愛。尤其是面對比較大的重構，我會先讓 agent 出個 plan，自己 review 一遍確認方向對了，然後才切回 code mode 去執行。
它也很適合團隊協作：讓 agent 出 plan → 丟給團隊 review → 確認後再執行。這樣 AI 不是在「偷偷改 code」，而是先提案、再執行，人對結果有完全的掌控。
我在用的時候通常會先跑 plan，把產出的 plan 存起來，然後帶著 plan 再用 code mode 執行。有點像先畫設計圖再施工的感覺。
3. Ask Mode
1 | cursor-agent -p "這個 useEffect 的 dependency array 為什麼要放這些值？" --mode ask |
Ask mode 是唯讀的。agent 只回答問題，完全不動 code。適合用在：
- 理解不熟悉的 codebase
- 查某個 function 的邏輯
- 問架構相關的問題
- 讓另一個 AI 透過 cursor-agent 來了解 codebase
我最常在另一個 AI 助理裡用 ask mode 來做 codebase 查詢。比如「這個專案用了哪些 npm packages 跟 authentication 有關？」這類問題，ask mode 回答得又快又準。
對話管理
跟 IDE 裡面的 chat 一樣，cursor-agent 的對話也可以持續和恢復。
恢復之前的對話
1 | cursor-agent --resume abc123def |
對話歷史存在 ~/.cursor/chats/ 目錄下。你可以用 --resume 加上 chatId 來恢復之前的對話。這在多 session 工作時很有用——比如今天做了一半的重構，明天繼續。
繼續上一次對話
1 | cursor-agent --continue -p "上次那個 API client 的 retry 做好了嗎？" |
--continue 會自動接續最近一次的對話，不需要手動找 chatId。
這個功能讓 cursor-agent 可以在多個 session 間保持 context。agent 會記得之前的討論、改過的檔案、做過的決定。這比每次都重新給 context 省事多了。
不過要注意的是，如果你 resume 一個很長的對話，context window 可能已經很滿了，agent 的表現會開始下降。我的經驗是：如果對話超過十幾個 turn，不如開一個新的對話，把之前的結論帶過去就好。
輸出控制
如果你要在程式裡解析 cursor-agent 的輸出，可以控制它的輸出格式：
純文字
1 | cursor-agent -p "列出所有 TODO 註解" --print text |
就是乾淨的文字，沒有顏色碼和控制字元。
JSON
1 | cursor-agent -p "分析這個 function 的複雜度" --print json |
回傳結構化的 JSON，包含 agent 的回答、修改的檔案列表、執行的命令等。適合程式解析。
Stream JSON
1 | cursor-agent -p "重構所有 utils" --print stream-json |
即時串流 JSON，每一步操作都會即時輸出一個 JSON object。適合需要即時顯示進度的應用——比如在 web UI 裡顯示 agent 正在做什麼。
實際應用場景
聊完功能，來說說我實際怎麼用。
AI 助理 + cursor-agent 做 codebase 分析
我目前的設定是讓一個 AI 助理（不是 Cursor）在需要理解 codebase 的時候呼叫 cursor-agent 的 ask mode。流程大概是：
- 使用者問：「某專案的 API rate limiting 邏輯怎麼寫的？」
- AI 助理判斷這個問題需要看 code
- 呼叫
cursor-agent --mode ask -p "API rate limiting 邏輯在哪裡？怎麼實作的？" - 解析回傳結果，整理成使用者看得懂的回答
這比自己寫 code search 強太多了。而且因為 cursor-agent 理解程式碼的語意，它可以追蹤 function call chain、理解 import 關係，給出的答案比 grep 精確得多。
自動化開發流程
另一個我很常用的場景是用 cursor-agent 做自動化開發。搭配一個 PM 角色的 AI 來拆任務：
- PM agent 把一個 feature 拆成幾個小任務
- 每個任務都送給 cursor-agent 用 plan mode 先出方案
- Review 方案（人工或自動）
- 通過後用 code mode 執行
- 自動跑
npm run build和npm run lint - 如果 build 或 lint 失敗，把錯誤訊息回傳給 cursor-agent 讓它修
- 全部通過後自動 commit
這套流程我在幾個小專案上試過，效果蠻好的。但有個重要的前提：任務要拆得夠小。 如果你丟一個「幫我做一個完整的 CRUD API」給 cursor-agent，它有時候會迷路。但如果拆成「建立 model」「建立 route handler」「加上 validation」「寫 unit test」這樣的小任務，每一步的品質都高很多。
批量重構
有一次要把專案裡所有的 callback style 改成 async/await。手動改太累，直接：
1 | cursor-agent -p "把 src/ 下所有使用 callback 的非同步函式改成 async/await，一個檔案一個檔案處理" --force |
agent 自己找到所有需要改的檔案，逐一修改，還會自動調整相關的 error handling。整個過程大概十分鐘搞定，手動的話可能要花半天。
不過批量重構有個風險：agent 有時候會「過度修改」。比如你只想改 callback，但它順手把一些不相關的東西也改了。所以跑完之後一定要用 git diff 仔細 review。我的習慣是：跑完批量修改後，先整體看一遍 diff，確認改動範圍符合預期，再 commit。
Prompt 工程：寫好指令很重要
用 cursor-agent 跟用 IDE 裡的 AI chat 不太一樣。在 IDE 裡你可以用滑鼠選 code、用 @ 標記檔案，但 CLI 只有文字。所以 prompt 要寫得更精確。
幾個我學到的技巧：
- 指定檔案範圍：「只修改
src/api/目錄下的檔案」，不要讓 agent 亂改其他地方 - 說明預期行為：「修改後
npm test應該全部通過」，給 agent 一個驗證標準 - 分步驟指示：「先列出所有需要修改的檔案，然後一個一個處理」，這比一句「全部改好」效果好得多
- 指定不要做什麼：「不要修改 test 檔案」「不要改變函式的公開介面」
注意事項
最後提幾個使用前要知道的事：
- 需要 Cursor 帳號和訂閱：cursor-agent 不是免費的，它用的是你 Cursor 訂閱的額度
- CLI config：設定檔在
~/.cursor/cli-config.json，可以設定預設模型、預設模式等 - 雲端執行：加
--cloud可以把計算放到雲端跑，不佔本地資源。適合在輕量機器上使用 - 沙箱模式：加
--sandbox會在隔離環境中執行，agent 的所有操作都在沙箱裡，不會影響你本地的檔案。適合測試或不確定 agent 會做什麼的時候用 - 費用管理：每次 cursor-agent 呼叫都會消耗額度，如果你用在自動化流程裡，要注意控制呼叫頻率和 token 用量
結語
Cursor Agent CLI 把 AI coding 從「坐在 IDE 前面跟 AI 對話」延伸到了「在任何自動化流程裡呼叫 AI 來寫 code」。這個轉變聽起來微妙，但實際影響很大——它讓 AI coding 不再是一個「人機互動」的場景，而是可以變成「機器對機器」的自動化環節。
當然，目前還有一些限制（PTY 需求、需要訂閱、偶爾的 hallucination），但整體來說，cursor-agent 是我目前用過最實用的 coding agent CLI。如果你已經在用 Cursor IDE，強烈建議試試它的 CLI 版本——你會發現一個全新的工作流。
說真的，第一次看到一個 AI agent 呼叫另一個 AI agent 來寫 code，那個感覺很奇妙。有點像是看到未來的工作方式——人負責定方向和做決策，AI 之間自己協作把事情做完。雖然現在還沒完全到那個程度，但 cursor-agent 讓這個畫面變得越來越清晰了。