逐条读取 JSON 事件流
严格的 LF 分帧、最前面的会话头、只含增量的 message_update,以及结束于 message_end 的重建规则——全部由测试断言。
pi --mode json 不是一个单一的 JSON 结果:它是一条记录流,每条记录都是一个以 LF 结尾的 JSON 对象,而 stdout 不承载别的任何东西。下面那些记录是那个形状的示意画——调用约定本身是在 1.0.4 上已观察的,方法是在一个脚本化的模型下运行随附的二进制文件并检查这条流。
分帧规则
- 只在 LF 上拆分;剥去一个可选的前导回车,好让 CRLF 输入能解析。
- **字符串内部的 U+2028 是合法 JSON,不是记录边界。**一个
readline式读者会把一条记录劈成两半;测试在真实输出上演示了这一点。 - 第一条记录是会话头,版本 3,而它不是这棵树的一部分。
- 持续地读 stdout——一个停止消费记录的读者会在管道缓冲区满时让 Pi 卡住。stdout 只承载 JSONL;诊断信息去 stderr。
示意性记录
{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/project"}
{"type":"agent_start"}
{"type":"message_update","usage":{},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"the quick "}}
{"type":"tool_execution_start","toolCallId":"c1","toolName":"bash","args":{"command":"echo hi"}}
{"type":"tool_execution_end","toolCallId":"c1","toolName":"bash","result":{"content":[{"type":"text","text":"hi"}]},"isError":false}
{"type":"message_end","message":{"role":"assistant","content":[{"type":"text","text":"hi"}],"stopReason":"stop"}}这些是示意性的:id、时间戳和文本都是占位符;字段遵循被断言的契约,而不是一份捕获的转录记录。
生命周期与重建
一次基本运行的顺序:
agent_start -> turn_start -> ... -> turn_end -> agent_end -> agent_settledagent_end 结束一次低层运行——重试、溢出恢复、引导或排队的工作仍可能继续。agent_settled 是最后一条记录,意味着 Pi 不会自动继续:等它,而不是等 agent_end。
message_update 在线上只含增量:没有累积式 message 字段,也没有 partial 快照,所以这条流保持线性。按三个逐级升高的权威层级重建——把 text_delta / thinking_delta 字段按 contentIndex 缓存起来做实时显示,用 text_end / thinking_end / toolcall_end 里已完成的内容替换它们,然后用 message_end.message 替换整条消息。一个失败的响应作为一条带 stopReason: "error" 的 message_end 出现在流里,而这次运行仍然落定。
机制与局限
有文档记载:json.md 钉住严格的 JSONL 分帧、会话头、事件词汇表,以及只含增量的线上形式;rpc.md 为双向的情形重复分帧规则。已观察:json-stream.test.ts 对上面每一条规则对着随附的二进制文件在 --mode json 下于 1.0.4 上、配一个脚本化的模型做出断言——一个没有 parentId 的版本 3 头、只按 LF 分帧且 U+2028 在字符串内原样发出、不带 message / partial 的 message_update、贯穿始终的 contentIndex、携带调用 ID、名称、参数和结果的工具事件,以及即使在一次失败的响应之后仍然在最后的 agent_settled。
extension_error 和 bash_execution_update 仅限 RPC,从不出现在 JSON 模式里:一次一次性的 JSON 运行无法告诉你一个扩展抛出了异常。usage 是累积但惰性的,可能一直为零直到完成——不要从它在中途计费。模型是脚本化的,所以这展示的是进程的分帧,而不是一个活模型输出的形状。
完整源码与测试 。
Understand this example
Copy this prompt into your AI tool. No code runs here.
Apply this example
Copy this prompt into your AI tool. No code runs here.