輸出格式

Cursor CLI 的 --output-format 只在 print mode 中使用，也就是結合 --print / -p，或 stdout 非 TTY、stdin 被 pipe 時推斷為 print mode。

閱讀目標：讀完本章，你應該能判斷什麼時候用 text、json、stream-json，並能避免把自然語言輸出當穩定 API 解析。

1. 三種輸出格式

Format	適合	不適合
`text`	人讀結果、PR comment、簡單日誌	機器強解析
`json`	指令碼讀取最終結果、需要 session/request 後設資料	需要即時進度
`stream-json`	即時進度、工具呼叫事件、長任務觀察	只要最終答案的簡單指令碼

預設格式是 text。

agent -p "Summarize this repo"
agent -p --output-format json "Return a concise risk report"
agent -p --output-format stream-json "Analyze this repo and report progress"

商業級預設：人看用 text，機器解析用 json，需要過程事件用 stream-json。

2. JSON format

json 格式在成功結束時輸出一個 JSON object，並以 newline 結尾。它不會輸出 delta 或 tool events，而是把文本聚合到最終 result。

成功結構包含這些欄位：

Field	含義
`type`	terminal result，通常是 `result`
`subtype`	成功時為 `success`
`is_error`	成功時為 `false`
`duration_ms`	總執行時間
`duration_api_ms`	API 請求時間
`result`	完整 assistant response text
`session_id`	當前 execution 的 session ID
`request_id`	optional request ID，可能不存在

失敗時，process 會用 non-zero exit code，並把錯誤寫到 stderr；失敗場景不會保證輸出 well-formed JSON object。

指令碼里要同時處理 stdout、stderr 和 exit code：

if output=$(agent -p --output-format json "Review this diff" 2>err.log); then
  printf '%s\n' "$output" | jq -r '.result'
else
  cat err.log
  exit 1
fi

3. Stream JSON format

stream-json 輸出 NDJSON：每一行是一個 JSON object，代表執行過程中的一個 event。

常見 event types：

Type	說明
`system` / `init`	session 開始，包含 cwd、model、permissionMode 等
`user`	使用者輸入 prompt
`assistant`	assistant message
`tool_call` / `started`	tool call 開始
`tool_call` / `completed`	tool call 完成
`result` / `success`	成功結束的 terminal event

成功時 stream 以 terminal result event 結束。失敗時，process non-zero exit，stream 可能提前結束，並把錯誤寫到 stderr。

讀取 stream 時，不要假設每次都有最終 result；必須處理異常退出。

4. Partial output 去重規則

如果需要 character-level streaming，使用：

agent -p --output-format stream-json --stream-partial-output \
  "Analyze this project and stream progress"

開啟後，assistant events 會出現三類情況。官方規則可以壓成這樣：

`timestamp_ms`	`model_call_id`	含義	動作
present	absent	新文本 delta	append
present	present	tool call 前的 buffered flush	skip
absent	absent	turn 結束時 final flush	skip

如果不需要即時字元流，只想要最終答案，不要解析 assistant events，直接讀 terminal result event 的 result 欄位。

5. Tool events 怎麼用

tool_call events 分 started 和 completed。它們可以幫助你記錄 Agent 做過什麼。

Tool	started 裡看什麼	completed 裡看什麼
Read file	path	content metadata、totalLines、totalChars
Write file	path、fileText、toolCallId	absolute path、linesCreated、fileSize
Other tools	function name、arguments	tool-specific result

用途：

在 CI 中生成審計日誌。
統計 Agent 是否寫了檔案。
追蹤讀取了哪些敏感路徑。
將 tool call ID 與 completion event 對齊。

不要把 tool event 當業務成功的唯一依據。最終仍要看 exit code、result event、git diff 和測試結果。

6. Text format

text 只輸出最終 assistant message，不包含中間 progress、tool call summaries 或事件流。

適合：

PR comment。
人讀摘要。
本地指令碼輸出到 markdown。
不需要機器解析欄位的報告。

不適合：

判斷是否寫檔案。
統計 tool calls。
需要 request/session metadata。
嚴格 JSON contract。

7. 指令碼消費建議

需求	推薦
人看一段總結	`--output-format text`
取最終結果	`--output-format json` 並讀 `.result`
需要即時進度	`--output-format stream-json`
需要逐字流	再加 `--stream-partial-output`
需要審計工具呼叫	解析 `tool_call` events
失敗處理	同時檢查 exit code 和 stderr

實現建議：

每行 JSON 用正式 parser，不用字串切割。
consumer 忽略未知欄位，因為官方說明未來可能加欄位。
session ID 在單次 execution 內保持一致，可用於日誌關聯。
print mode 中 thinking events 被 suppress，不要等待 thinking events。

深讀：為什麼 text 不是 API

text 是給人看的最終回答，天然可能因為模型、prompt、上下文和版本變化而改變措辭。

一旦指令碼依賴某個中文標題、冒號或 bullet，就會變脆。機器消費結果要麼用 json，要麼讓 prompt 明確生成 JSON，再結合 --output-format json 做雙層約束。

本章自檢

完成本章後，用這 3 個問題檢查自己是否真正理解：

json 失敗時為什麼不能假設 stdout 一定是 well-formed JSON？
stream-json 與 --stream-partial-output 的差別是什麼？
partial output 中哪類 assistant event 應該 append，哪兩類應該 skip？

透過標準：你能寫一個指令碼，正確處理 exit code、stderr、JSON 解析失敗和 terminal result。

官方來源

Cursor CLI Output Format —— 官方 text、json、stream-json、partial output、event types 和 implementation notes。
Cursor Headless CLI —— 官方 headless / print mode 使用場景。
Cursor CLI Parameters —— 官方 --output-format 引數說明。

1. 三種輸出格式

2. JSON format

3. Stream JSON format

4. Partial output 去重規則

5. Tool events 怎麼用

6. Text format

7. 指令碼消費建議

本章自檢

官方來源

接下來去哪

Terminal Setup

Headless 模式

本頁目錄