---
title: "輸出格式"
description: "基於 Cursor 官方 Output Format 文件解釋 text、json、stream-json、partial output、事件型別、失敗行為和指令碼消費邊界。"
verifiedAt: "2026-05-09"
---

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

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

## 1. 三種輸出格式

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

預設格式是 `text`。

```bash
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：

```bash
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，使用：

```bash
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。

<details>
<summary>深讀：為什麼 text 不是 API</summary>

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

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

## 本章自檢

完成本章後，用這 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](https://cursor.com/docs/cli/reference/output-format.md) —— 官方 text、json、stream-json、partial output、event types 和 implementation notes。
- [Cursor Headless CLI](https://cursor.com/docs/cli/headless.md) —— 官方 headless / print mode 使用場景。
- [Cursor CLI Parameters](https://cursor.com/docs/cli/reference/parameters.md) —— 官方 `--output-format` 引數說明。

## 接下來去哪

<Cards>
  <Card title="Terminal Setup" description="繼續學習終端 keybindings 和快捷鍵相容性。" href="/zh-Hant/docs/cursor/official/03-cli-automation/43-terminal-setup" />
  <Card title="Headless 模式" description="回到 scripts 和 CI 中如何使用輸出格式。" href="/zh-Hant/docs/cursor/official/03-cli-automation/35-headless" />
</Cards>
