---
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="/docs/cursor/official/03-cli-automation/43-terminal-setup" />
  <Card title="Headless 模式" description="回到 scripts 和 CI 中如何使用输出格式。" href="/docs/cursor/official/03-cli-automation/35-headless" />
</Cards>
