跳轉到主要內容
Cursor Agent CLI 在搭配 --print 使用時，可透過 --output-format 選項提供多種輸出格式。這些格式包含供程式化使用的結構化格式（json、stream-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唯一的工作階段識別碼
request_id選填的請求識別碼（可能省略）

​
Stream JSON 格式

stream-json 輸出格式會產生以換行分隔的 JSON（NDJSON）。每一行包含一個 JSON 物件，代表執行期間的即時事件。 成功時，串流會以終止的 result 事件結束。若失敗，程序會以非零代碼結束，且串流可能在沒有終止事件的情況下提前結束；錯誤訊息會寫入 stderr。

​
事件類型

​
系統初始化

在每個工作階段開始時觸發一次： 
{
  "type": "system",
  "subtype": "init",
  "apiKeySource": "環境變數|旗標|登入",
  "cwd": "/絕對/路徑",
  "session_id": "<uuid>",
  "model": "<模型顯示名稱>",
  "permissionMode": "預設"
}
未來可能會在此事件中新增 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": "<增量分塊>" }]
  },
  "session_id": "<uuid>"
}
依序串接所有 message.content[].text 的值，重建完整的助手回應。

​
工具呼叫事件

工具呼叫會透過開始與完成事件進行追蹤： 工具呼叫開始： 
{
  "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": "檔案內容…",
          "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": "<選填的 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":"讀取 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":"# 專案\n\n這是一個範例專案...","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 將開始／完成事件對應起來
  • Session ID 在單次代理執行期間保持一致