跳转到主要内容
--output-format--print 搭配使用时,Cursor Agent CLI 提供多种输出格式。这些格式包括用于编程场景的结构化格式(jsonstream-json),以及用于人类可读进度跟踪的简化文本格式。
--output-format 的默认值是 stream-json。该选项仅在打印(--print)时有效,或在推断为打印模式(非 TTY 的 stdout 或通过管道的 stdin)时有效。

JSON 格式

当运行成功完成时,json 输出格式会输出单个 JSON 对象(后跟换行符)。不会输出增量数据或工具事件;文本会汇总到最终结果中。 发生失败时,进程会以非零退出码结束,并将错误消息写到 stderr。失败情况下不会输出任何格式正确的 JSON 对象。

成功响应

成功时,CLI 会输出一个具有以下结构的 JSON 对象:
{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 1234,
  "result": "<完整助手文本>",
  "session_id": "<uuid>",
  "request_id": "<可选请求ID>"
}
字段描述
type终端结果的取值始终为 "result"
subtype成功完成时的取值始终为 "success"
is_error成功响应时始终为 false
duration_ms总执行时长(毫秒)
duration_api_msAPI 请求时长(毫秒)(当前等同于 duration_ms
result助手完整响应文本(将所有文本增量拼接而成)
session_id唯一会话 ID
request_id可选的请求 ID(可能省略)

流式 JSON 格式

stream-json 输出格式会产生以换行分隔的 JSON(NDJSON)。每一行都是一个 JSON 对象,表示执行过程中的实时事件。 成功时,流以终止的 result 事件结束。失败时,进程以非零退出码退出,流可能在未产生终止事件的情况下提前结束;错误信息会写入 stderr。

事件类型

系统初始化

在每个会话开始时发出一次:
{
  "type": "system",
  "subtype": "init",
  "apiKeySource": "环境变量|标志位|登录",
  "cwd": "/绝对路径",
  "session_id": "<uuid>",
  "model": "<模型展示名称>",
  "permissionMode": "默认",
}
未来可能会为此事件新增 toolsmcp_servers 等字段。

用户消息

包含用户的输入提示词:
{
  "type": "user",
  "message": {
    "role": "user",
    "content": [{ "type": "text", "text": "<prompt>" }]
  },
  "session_id": "<uuid>"
}

助手文本增量

在助手生成回复的过程中会多次触发。这些事件包含逐步生成的文本片段:
{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "content": [{ "type": "text", "text": "<delta chunk>" }]
  },
  "session_id": "<uuid>"
}
按顺序串联所有 message.content[].text 的值,以重建完整的助手回复。

工具调用事件

工具调用通过开始和完成事件进行追踪: 工具调用开始:
{
  "type": "tool_call",
  "subtype": "started",
  "call_id": "<字符串ID>",
  "tool_call": {
    "readToolCall": {
      "args": { "path": "file.txt" }
    }
  },
  "session_id": "<uuid>"
}
工具调用完成:
{
  "type": "tool_call",
  "subtype": "completed",
  "call_id": "<string id>",
  "tool_call": {
    "readToolCall": {
      "args": { "path": "file.txt" },
      "result": {
        "success": {
          "content": "文件内容…",
          "isEmpty": false,
          "exceededLimit": false,
          "totalLines": 54,
          "totalChars": 1254
        }
      }
    }
  },
  "session_id": "<uuid>"
}

工具调用类型

读取文件工具:
  • 开始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": "..." }

终端结果

成功完成时发出的最后一个事件:
{
  "type": "result",
  "subtype": "success",
  "duration_ms": 1234,
  "duration_api_ms": 1234,
  "is_error": false,
  "result": "<完整助手文本>",
  "session_id": "<uuid>",
  "request_id": "<可选请求 ID>"
}

示例序列

下面展示了一个具有代表性的 NDJSON 序列,体现了事件的典型流转:
{"type":"system","subtype":"init","apiKeySource":"login","cwd":"/Users/user/project","session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff","model":"Claude 4 Sonnet","permissionMode":"default"}
{"type":"user","message":{"role":"user","content":[{"type":"text","text":"阅读 README.md 并创建摘要"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"我会"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"阅读 README.md 文件"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"tool_call","subtype":"started","call_id":"toolu_vrtx_01NnjaR886UcE8whekg2MGJd","tool_call":{"readToolCall":{"args":{"path":"README.md"}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"tool_call","subtype":"completed","call_id":"toolu_vrtx_01NnjaR886UcE8whekg2MGJd","tool_call":{"readToolCall":{"args":{"path":"README.md"},"result":{"success":{"content":"# Project\n\nThis is a sample project...","isEmpty":false,"exceededLimit":false,"totalLines":54,"totalChars":1254}}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"并创建摘要"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"tool_call","subtype":"started","call_id":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv","tool_call":{"writeToolCall":{"args":{"path":"summary.txt","fileText":"# README 概要\n\n该项目包含...","toolCallId":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv"}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"tool_call","subtype":"completed","call_id":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv","tool_call":{"writeToolCall":{"args":{"path":"summary.txt","fileText":"# README 概要\n\n该项目包含...","toolCallId":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv"},"result":{"success":{"path":"/Users/user/project/summary.txt","linesCreated":19,"fileSize":942}}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"result","subtype":"success","duration_ms":5234,"duration_api_ms":5234,"is_error":false,"result":"我会阅读 README.md 文件并创建摘要","session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff","request_id":"10e11780-df2f-45dc-a1ff-4540af32e9c0"}

文本格式

text 输出格式以简洁、易读的方式呈现代理的动作流。它不会输出详尽的 JSON 事件,而是实时给出代理正在执行的操作的简明文字描述。 这种格式适合在不需解析结构化数据的前提下监控代理进度,非常适用于日志记录、调试或简单的进度跟踪。

示例输出

读取了文件
编辑了文件
运行了终端命令
创建了新文件
随着代理执行操作,每个动作都会以新行显示,并即时反馈其任务进度。

实现说明

  • 每个事件以单行形式发出,并以\n结尾
  • 打印模式下会抑制thinking事件,它不会出现在任一输出格式中
  • 字段可能会随时间以向后兼容的方式增加(使用方应忽略未知字段)
  • 流式格式提供实时更新,而 JSON 格式会在完成后再输出结果
  • 将所有 assistant 消息增量拼接以重建完整响应
  • 工具调用 ID 可用于关联开始/完成事件
  • 会话 ID 在单次代理执行期间保持一致
I