Skip to main content

Command Palette

Search for a command to run...

参考文档

输出格式

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

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_msAPI 请求耗时，单位为毫秒 (目前等于 duration_ms)
result完整的助手响应文本 (串联所有文本增量)
session_id唯一会话标识符
request_id可选的请求标识符 (可省略)

流式 JSON 格式

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

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

事件类型

系统初始化

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

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

用户消息

包含用户输入的提示词：

{  "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 保持一致