《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
羽毛球分组比赛记分
小程序二维码

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

小夜