JSON 与流式事件
解析最终结果和 NDJSON，区分增量与重复 flush，并正确处理失败退出。
This page has not been translated into English yet. The original Chinese version is shown below.
--output-format 只适用于打印模式，包括显式 --print，以及非 TTY stdout 或管道 stdin 推断出的打印模式。默认 text 只输出最后一条助手消息。
单个 JSON 结果
agent -p --output-format json "Explain the project structure"成功时输出一个 JSON 对象并换行；不包含逐条工具事件。主要字段如下：
| 字段 | 含义 |
|---|---|
| type、subtype | 成功结果分别为 result、success |
| is_error | 成功时为 false |
| result | 聚合的完整助手文本 |
| duration_ms | 总耗时（毫秒） |
| duration_api_ms | API 耗时，官方当前说明与总耗时相同 |
| session_id | 会话标识 |
| request_id | 可选请求标识 |
失败时进程返回非零退出码并向 stderr 写错误，不保证输出有效 JSON。脚本应先检查退出状态，再解析结果，不能假设每次都有 result 字段。
流式 NDJSON
agent -p --output-format stream-json "Explain the project structure"每行是一个事件。常见顺序为 system/init、user、assistant、tool_call/started、tool_call/completed，最后成功以 result 结束。默认 assistant 是两次工具调用之间的一整条消息；用 call_id 配对工具起止事件。
流可能因失败提前结束，没有终止 result。此时应结合退出码和 stderr 判断，不能把已收到文本当作任务成功。
字符增量去重
需要更细的实时显示时，增加 --stream-partial-output。同一文本还可能以 flush 再次出现，应按字段区分：
| timestamp_ms | model_call_id | 处理方式 |
|---|---|---|
| 有 | 无 | 新增量，追加 message.content 中的 text |
| 有 | 有 | 工具调用前的重复 flush，跳过 |
| 无 | 无 | 轮次末尾的重复 flush，跳过 |
只需要最终答案时可忽略所有 assistant 事件，读取终止 result 的 result 字段。打印模式不输出 thinking 事件；消费者应容忍新增字段，避免因向后兼容扩展而失败。