Cursor CLI 輸出格式與 CI 整合：text、json、stream-json 怎麼選

同一個 Agent 跑完，你想要的「結果格式」可能完全不同：有時只需要最後一段文字、有時要 CI 能解析的 JSON、有時要即時知道 AI 現在在做什麼。

--output-format 就是控制這件事的開關，三個選項，用途分很清楚。

三種輸出格式

不加 --output-format 時就是 text 模式——輸出只有最後回覆的內容，沒有工具呼叫、沒有中間步驟：

cursor agent -p "這個 repo 的入口點是哪個檔案？"

在 CI 裡若只要把 Agent 的結論寫進一個檔：

cursor agent -p "根據 CHANGELOG 產出本版 release notes" > release_notes.txt

簡單，適合直接貼到文件或作為說明文字。

cursor agent -p --output-format json "分析 src/ 的依賴關係，回傳 JSON：{ \"entry\": \"...\", \"deps\": [...] }"

輸出是結構化的 JSON，包含 result、duration_ms 等欄位，可能還有你 prompt 裡要求的自訂欄位。在 CI 裡可以用 jq 取欄位、判斷是否為空、或根據內容決定 job 是 pass 還是 fail：

cursor agent -p --output-format json "做簡短 code review，回傳 {\"ok\": true/false, \"summary\": \"...\"}" | jq -r '.result'

實際欄位以 Cursor 文件為準——json 格式的核心價值在於「讓程式讀」，不是讓人讀。

cursor agent -p --output-format stream-json --stream-partial-output "分析專案並產出 analysis.txt"

每一行是一筆 JSON，代表一個事件——system、assistant、tool_call、result 之類的。--stream-partial-output 會讓助理回覆以增量方式出現，方便做即時字數或進度顯示。

可以解析 tool_call 的 started/completed，知道 Agent 正在讀哪個檔、寫哪個檔、花了多久——適合長任務、想在前端或 CI log 裡顯示「正在處理第 N 個檔案」的場合。

需求	建議
只關心「跑完沒、結論是什麼」	`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，雙重保險，不讓假成功溜過去。

格式選對了，後面的腳本和 CI pipeline 才能順順地跑——不然就是在 stdout 裡用 grep 找關鍵字，那就有點尷尬了。

下一步：12-sessions-cloud — 用 --resume 接回上次對話、-c 把長任務丟雲端跑。