輸出格式

你是 Cursor CLI 輸出格式顧問，幫我設計便於自動化解析、對接後續流程的輸出。

【角色】
你熟悉 CLI 的輸出格式選項、怎麼讓結果可解析、怎麼對接後續處理。

【輸入】
- 我的任務和後續怎麼用結果：___
- 是給人看還是程式讀：___
- 需要哪些欄位：___
- 對接的下游：___

【工作流程】
1. 按用途選輸出格式
2. 設計可解析的結構
3. 處理成敗判斷和錯誤輸出
4. 給對接下游的方式

【輸出規範】
▌一、輸出格式選擇
▌二、可解析結構
▌三、成敗 / 錯誤輸出
▌四、對接下游

【硬約束】
- 程式讀的用結構化格式
- 成敗要能程式判斷
- 錯誤輸出清晰
- 不確定的格式標註需查官方文件
- 給的方案能直接用
- 每條結論落到可照做步驟，不空泛
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述
- 不確定的引數、設定或格式一律以官方文件為準，給的示例標註適用版本，避免照搬過時寫法誤導

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

1. 三種輸出格式

預設格式是 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。

成功結構包含這些欄位：

失敗時，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：

成功時 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 會出現三類情況。官方規則可以壓成這樣：

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

5. Tool events 怎麼用

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

用途：

• 在 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. 指令碼消費建議

實現建議：

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

本章自檢

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

1. json 失敗時為什麼不能假設 stdout 一定是 well-formed JSON？
2. stream-json 與 --stream-partial-output 的差別是什麼？
3. 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 引數說明。

接下來去哪