《Cursor文档》-输出格式

Cursor文档 Cursor CLI 2026-08-26 35 阅读

Cursor Agent 命令行界面 与 --print 配合使用时，可通过 --output-format 选项指定多种输出格式，包括供程序使用的结构化格式 (json、stream-json) ，以及便于人类阅读的简化文本格式 (text) 。

--output-format 的默认值为 text。此选项仅在
打印 (--print) 或推断为 print 模式时有效 (stdout 不是 TTY，或 stdin 通过管道传入) 。

JSON 格式

运行成功完成后，json 输出格式会输出一个 JSON 对象 (后跟换行符) 。不会输出增量内容或工具事件；文本会汇总为最终结果。

运行失败时，进程会以非零退出码退出，并将错误消息写入 stderr。失败时不会输出格式良好的 JSON 对象。

成功响应

成功时，命令行界面会输出以下结构的 JSON 对象：

{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 1234,
  "result": "<full assistant text>",
  "session_id": "<uuid>",
  "request_id": "<optional request id>"
}
字段 描述
type 终端结果始终为 "result"
subtype 成功完成时始终为 "success"
is_error 成功响应时始终为 false
duration_ms 总执行时间，单位为毫秒
duration_api_ms API 请求耗时，单位为毫秒 (目前等于 duration_ms)
result 完整的助手响应文本 (串联所有文本增量)
session_id 唯一会话标识符
request_id 可选的请求标识符 (可省略)

流式 JSON 格式

stream-json 输出格式会输出以换行符分隔的 JSON (NDJSON) 。每行包含一个 JSON 对象，表示执行过程中的一个事件。该格式会聚合文本增量，每条助手消息输出一行 (即两次工具调用之间的完整消息) 。

成功时，流会以终结 result 事件结束。失败时，进程会以非零退出码退出，流可能在没有终结事件的情况下提前结束；错误消息会写入 stderr。

**流式部分输出：**如需实时字符级流式输出，请将 --stream-partial-output 与 --output-format stream-json 配合使用。生成文本时，会以小块形式输出，每条消息会产生多个 assistant 事件。

使用 --stream-partial-output 时，命令行界面会输出三类 assistant 事件。只有第一类包含新文本：

timestamp_ms model_call_id 含义 操作
存在 不存在 包含新文本的流式增量 使用 — 追加 message.content[].text
存在 存在 工具调用前的缓冲刷新 (重复) 跳过
不存在 不存在 轮次结束时的最终刷新 (重复) 跳过

如果不需要实时流式输出，只想获取最终回答，请跳过所有 assistant 事件，并从终结 result 事件中读取 result 字段。

事件类型

系统初始化

每个会话开始时发送一次：

{
  "type": "system",
  "subtype": "init",
  "apiKeySource": "env|flag|login",
  "cwd": "/absolute/path",
  "session_id": "<uuid>",
  "model": "<model display name>",
  "permissionMode": "default"
}

此事件未来可能会新增 tools 和 mcp_servers 等字段。

用户消息

包含用户输入的提示词：

{
  "type": "user",
  "message": {
    "role": "user",
    "content": [{ "type": "text", "text": "<prompt>" }]
  },
  "session_id": "<uuid>"
}

助手消息

每条完整的助手消息 (两次工具调用之间) 会发出一次。每个事件都包含该消息片段的完整文本：

{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "content": [{ "type": "text", "text": "<complete message text>" }]
  },
  "session_id": "<uuid>"
}

启用 --stream-partial-output 后，助手事件可能包含两个额外字段：

字段 描述
timestamp_ms 存在于流式增量和工具调用前的刷新事件中，轮次结束时的最终刷新事件中不存在。
model_call_id 仅存在于工具调用前发出的缓冲刷新事件中。可用于识别并跳过重复文本。

有关如何筛选这些事件，请参阅上方的流式部分输出说明。

工具调用事件

工具调用会通过开始和完成事件进行跟踪：

工具调用已开始：

{
  "type": "tool_call",
  "subtype": "started",
  "call_id": "<string 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": "file contents...",
          "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": "<full assistant text>",
  "session_id": "<uuid>",
  "request_id": "<optional request 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":"Read README.md and create a summary"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"I'll read the README.md file"}]},"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":"Based on the README, I'll create a summary"}]},"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 Summary\n\nThis project contains...","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 Summary\n\nThis project contains...","toolCallId":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv"},"result":{"success":{"path":"/Users/user/project/summary.txt","linesCreated":19,"fileSize":942}}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Done! I've created the summary in summary.txt"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"result","subtype":"success","duration_ms":5234,"duration_api_ms":5234,"is_error":false,"result":"I'll read the README.md fileBased on the README, I'll create a summaryDone! I've created the summary in summary.txt","session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff","request_id":"10e11780-df2f-45dc-a1ff-4540af32e9c0"}

文本格式

text 输出格式仅包含最终的助手消息，不含任何中间进度更新或工具调用摘要。对于只需智能体最终响应的脚本，这是最简洁的输出格式。

如果您只想获取智能体的答案或最终消息，而不需要进度提示或工具执行详情，此格式非常适合。

输出示例

The command to move this branch onto main is `git rebase --onto main HEAD~3`.

仅输出最后一次工具调用后的最终助手消息，不包含工具调用摘要或中间文本。

说明

  • 每个事件均以单行形式发出，并以 \n 结尾
  • thinking 事件在 print 模式下会被抑制，不会出现在任何输出格式中
  • 字段可能会以向后兼容的方式逐步新增 (使用方应忽略未知字段)
  • json 格式会等待完成后再输出结果
  • stream-json 格式会输出完整的智能体消息
  • --stream-partial-output 标志提供实时文本增量，支持字符级流式输出 (仅适用于 stream-json 格式)
  • 可使用工具调用 ID 关联开始和完成事件
  • 在单次智能体执行期间，会话 ID 保持一致

相关文章

Cursor 3 多 Agent 架构：Planner/Worker 分工最高降本 15 倍 2026-07-29 Cursor 多 Agent 蜂群用 1339 美元重建 SQLite：Planner/Worker 分层才是 Agent 经济学 2026-07-30 600 亿美元收购 Cursor：SpaceX/xAI 要重塑 AI 编程工具格局？ 2026-07-31 Cursor 3 多 Agent 架构：Planner/Worker 分层如何将编码成本降低 15 倍 2026-08-01 GitHub 爆火 Ponytail：让 AI Agent 像「最懒的高级工程师」一样写代码 2026-08-02
羽毛球分组比赛记分
小程序二维码

欢迎使用《羽毛球分组比赛记分》微信小程序

小夜