输出格式

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 模式

本页目录