--output-format
与 --print
搭配使用时,Cursor Agent CLI 提供多种输出格式。这些格式包括用于编程场景的结构化格式(json
、stream-json
),以及用于人类可读进度跟踪的简化文本格式。
--output-format
的默认值是 stream-json
。该选项仅在打印(--print
)时有效,或在推断为打印模式(非 TTY 的 stdout 或通过管道的 stdin)时有效。JSON 格式
json
输出格式会输出单个 JSON 对象(后跟换行符)。不会输出增量数据或工具事件;文本会汇总到最终结果中。
发生失败时,进程会以非零退出码结束,并将错误消息写到 stderr。失败情况下不会输出任何格式正确的 JSON 对象。
成功响应
字段 | 描述 |
---|---|
type | 终端结果的取值始终为 "result" |
subtype | 成功完成时的取值始终为 "success" |
is_error | 成功响应时始终为 false |
duration_ms | 总执行时长(毫秒) |
duration_api_ms | API 请求时长(毫秒)(当前等同于 duration_ms ) |
result | 助手完整响应文本(将所有文本增量拼接而成) |
session_id | 唯一会话 ID |
request_id | 可选的请求 ID(可能省略) |
流式 JSON 格式
stream-json
输出格式会产生以换行分隔的 JSON(NDJSON)。每一行都是一个 JSON 对象,表示执行过程中的实时事件。
成功时,流以终止的 result
事件结束。失败时,进程以非零退出码退出,流可能在未产生终止事件的情况下提前结束;错误信息会写入 stderr。
事件类型
系统初始化
未来可能会为此事件新增
tools
和 mcp_servers
等字段。用户消息
助手文本增量
按顺序串联所有
message.content[].text
的值,以重建完整的助手回复。工具调用事件
工具调用类型
- 开始:
tool_call.readToolCall.args
包含{ "path": "file.txt" }
- 完成:
tool_call.readToolCall.result.success
包含文件元数据和内容
- 开始:
tool_call.writeToolCall.args
包含{ "path": "file.txt", "fileText": "content...", "toolCallId": "id" }
- 完成:
tool_call.writeToolCall.result.success
包含{ "path": "/absolute/path", "linesCreated": 19, "fileSize": 942 }
- 可能使用
tool_call.function
结构,形如{ "name": "tool_name", "arguments": "..." }
终端结果
示例序列
文本格式
text
输出格式以简洁、易读的方式呈现代理的动作流。它不会输出详尽的 JSON 事件,而是实时给出代理正在执行的操作的简明文字描述。
这种格式适合在不需解析结构化数据的前提下监控代理进度,非常适用于日志记录、调试或简单的进度跟踪。
示例输出
实现说明
- 每个事件以单行形式发出,并以
\n
结尾 - 打印模式下会抑制
thinking
事件,它不会出现在任一输出格式中 - 字段可能会随时间以向后兼容的方式增加(使用方应忽略未知字段)
- 流式格式提供实时更新,而 JSON 格式会在完成后再输出结果
- 将所有
assistant
消息增量拼接以重建完整响应 - 工具调用 ID 可用于关联开始/完成事件
- 会话 ID 在单次代理执行期间保持一致