Cursor CLI 輸出格式與 CI 整合
4 min read
上一篇 10-headless-scripts 用 -p --force 在腳本裡改檔案。這篇講 輸出格式：同一個 Agent 跑完，你可以選「只要最後一段文字」、「整份結構化 JSON」、或「邊跑邊串流 JSON」——在 CI 裡要解析結果、算時間、或顯示進度條，就靠這三種格式。
三種輸出格式
| 格式 | 參數 | 適合 |
|---|---|---|
| text | 預設，或 --output-format text |
人類閱讀、只要最終答案、丟進檔案 |
| json | --output-format json |
腳本解析、CI 判斷成功失敗、擷取欄位 |
| stream-json | --output-format stream-json |
即時進度、工具呼叫追蹤、長任務監控 |
text：乾淨的最終答案
cursor agent -p "這個 repo 的入口點是哪個檔案？"不加 --output-format 時就是 text：輸出只有最後回覆的內容，沒有工具呼叫、沒有中間步驟，適合直接貼到文件或當成一段說明。
在 CI 裡若只要「把 Agent 的結論寫進一個檔」：
cursor agent -p "根據 CHANGELOG 產出本版 release notes" > release_notes.txtjson：給腳本與 CI 解析
cursor agent -p --output-format json "分析 src/ 的依賴關係，回傳 JSON：{ \"entry\": \"...\", \"deps\": [...] }"輸出會是結構化的 JSON，可能包含 result、duration_ms、或你 prompt 裡要求的欄位。
在 CI 裡可以：
- 用
jq取欄位、判斷是否為空、或檢查關鍵字 - 根據 exit code 與內容決定 job 成功失敗
範例（概念）：
cursor agent -p --output-format json "做簡短 code review，回傳 {\"ok\": true/false, \"summary\": \"...\"}" | jq -r '.result'
# 再依 .ok 或 .summary 做後續步驟或 fail the build實際欄位以 Cursor 文件為準，這裡是說明「json 適合被程式解析」。
stream-json：即時進度與工具追蹤
cursor agent -p --output-format stream-json --stream-partial-output "分析專案並產出 analysis.txt"- 每一行是一筆 JSON，代表一個事件（例如
system、assistant、tool_call、result） --stream-partial-output會讓助理回覆以增量（delta） 方式出現，方便做「即時字數」、「進度 %」等- 可解析
tool_call的 started/completed，知道 Agent 正在讀哪個檔、寫哪個檔、花了多久
適合：長任務、想在前端或 CI log 顯示「正在處理第 N 個檔案」、或統計工具呼叫次數與耗時。
CI 整合要點
| 需求 | 建議 |
|---|---|
| 只關心「跑完沒、結論是什麼」 | text + 重導向到檔或變數；看 exit code |
| 要依內容決定 pass/fail | json + jq 解析 |
| 要即時 log 或進度 | stream-json + 逐行解析 type/subtype |
| 要 Agent 改檔 | 加上 --force（見 10-headless-scripts） |
| 在 CI 跑 | 設 CURSOR_API_KEY；必要時用 --model 固定模型 |
失敗時怎麼處理
- Agent 執行失敗時，CLI 通常會回傳非 0 的 exit code
- 腳本裡用
if [ $? -ne 0 ]; then exit 1; fi或set -e讓 CI 正確失敗 - 若用 json，可再檢查輸出裡是否有
error或自訂的ok: false欄位，雙重保險
小結
- text：預設，人類可讀、最簡輸出，適合寫檔或當說明
- json：結構化，給
jq或腳本解析，適合 CI 判斷與擷取 - stream-json + --stream-partial-output：即時事件流，適合進度顯示與工具追蹤
- CI 記得設好
CURSOR_API_KEY、看 exit code、必要時解析 JSON 做 pass/fail
下一步：12-sessions-cloud — 會話恢復
--resume與雲端執行-c。