JSON 事件流
Pi 的 JSONL 事件的线上参考——严格的 LF 分帧、事件词汇表,以及把增量变回权威消息的那条重建规则。
你把 pi --mode json 管进了一个日志,现在你有四千行和一个问题:其中哪些是答案?
事件流是 JSON 与 RPC 模式所共享的一切的规范参考,而 json.md 对一件事异乎寻常地诚实——它是一个 wire format(线上格式),刻意地从进程内的那一个缩减而来。如果你不读那处缩减就建立在它之上,你的重建会漂移。本章把这条流拆开:分帧、词汇表,以及支配重建的那一条规则。
分帧没有商量余地
json.md 在分帧那一节的第一段说了这一点,而它是那种看起来很学究、直到它毁掉一次运行的规则:
这条流使用严格的 JSONL 分帧。每条记录是一个以 LF(
\n)结尾的 JSON 对象。只在 LF 上拆分记录,并剥去一个可选的前导回车。Unicode 的行分隔符和段落分隔符在 JSON 字符串内部是有效的,而它们不是记录边界。
最后一个从句有一个点了名的受害者。文档说 Node.js 的 readline “不适合这条流,因为它也识别那些 Unicode 分隔符”——U+2028 和 U+2029 在 JSON 字符串内部是合法的,而一个面向行的读者会把一条记录劈成两半。用一个字节流或 UTF-8 流解码器,自己按 LF 拆分。
rpc.md 为双向的情形重复了同一条规则,并补充:“不要用把 Unicode 行分隔符或段落分隔符当作记录边界的通用行读取器。”
跟着来的是两条操作规则。剥去那个可选的前导回车,好让 CRLF 输入能解析,并持续地读 stdout——“一个停止消费记录的读者会在管道缓冲区满时让 Pi 卡住。“stdout 专留给 JSONL;诊断信息去 stderr。
会话头在最前面
JSON 模式里的第一条记录是会话头,而它的形状与被持久化的那个相同:
{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path"}
RPC 模式不发出它。json.md 说得很明确:“RPC 模式不发出这条记录。用 get_state 取它当前的会话 ID 和文件。“这是两个协议之间的第一处结构差别,而它存在是因为 RPC 是双向且长期存活的——没有唯一的起始时刻可用来挂一个头。
事件词汇表
json.md 把事件分组,而这个分组值得作为一个形状来学,而不是作为一个列表。
运行生命周期。agent_start(无字段)、agent_end(messages、willRetry)、agent_settled(无字段)、turn_start、turn_end(message、toolResults)。一轮是"一条助手响应,加上该响应产生的任何工具调用与工具结果。”
agent_end 和 agent_settled 之间的区别是最要紧的一件事,而文档把它重复了两遍。agent_end 结束一次低层智能体运行,而"自动重试、溢出恢复、压缩重试、引导或后续跟进工作仍可能继续。"agent_settled 意味着"Pi 不会通过重试、压缩恢复或排队的消息自动继续。“如果你等错了那一个,你要么挂住,要么被截断。
消息。message_start(message)、message_update(usage、assistantMessageEvent)、message_end(message)。message_end “是权威的最终消息。”
工具执行。tool_execution_start(toolCallId、toolName、args)、tool_execution_update(增加 partialResult)、tool_execution_end(toolCallId、toolName、result、isError)。json.md 警告说"它是替换还是扩展一次更早的更新,取决于那个工具的结果契约”——与扩展那一章里关于部分结果的同一条注意事项。
队列与状态。queue_update(steering、followUp,两者都是完整队列)、entry_appended(entry)、session_info_changed(name)、thinking_level_changed(level)。
压缩。compaction_start 的 reason 为 "manual"、"threshold" 或 "overflow",然后是 compaction_end。成功时,结果携带 summary、firstKeptEntryId、tokensBefore、estimatedTokensAfter、usage 和 details。中止时,result 缺席而 aborted 为 true;失败时,result 缺席,aborted 为 false,而 errorMessage 描述它。成功的溢出恢复把 willRetry 设为 true。
重试。auto_retry_start(attempt、maxAttempts、delayMs、errorMessage)和 auto_retry_end(success、attempt),外加一个给摘要的独立家族:summarization_retry_scheduled、summarization_retry_attempt_start(source、reason)、summarization_retry_finished。
下面是一次基本运行的序列,直接取自 json.md:
pi --mode json "List files" 2>/dev/null | jq -c 'select(.type == "message_end")'
那个单行命令是本章的实用载荷:过滤出权威消息,忽略其余一切。
重建:先是增量,然后是权威
这一部分会改变你写一个消费者的方式。json.md 说:
线上的
message_update记录只含增量。它们省略了 SDK 事件的累积式message字段,以及每一个assistantMessageEvent.partial快照,好让流的大小保持线性。
在进程内,SDK 的 AgentSessionEvent 携带累积式快照。在线上,它们不见了——“好让流的大小保持线性。“如果你把一个进程内订阅者移植成一个 JSON 消费者,并指望 partial 在那儿,它会是 undefined。
嵌套的 assistantMessageEvent 词汇表是:
| Type | type 之外的字段 |
|---|---|
start |
— |
text_start |
contentIndex |
text_delta |
contentIndex, delta |
text_end |
contentIndex, content |
thinking_start |
contentIndex |
thinking_delta |
contentIndex, delta |
thinking_end |
contentIndex, content |
toolcall_start |
contentIndex, id, toolName |
toolcall_delta |
contentIndex, delta |
toolcall_end |
contentIndex, toolCall |
done |
reason, message |
error |
reason, error |
按文档自己的话说,重建规则是:用 contentIndex 标识内容块;把 delta 字段缓存起来做一个实时显示;然后"用 text_end、thinking_end 或 toolcall_end 里已完成的内容替换重建出来的数据”;以及"在 message_end.message 到达时,用整个部分消息替换它。”
这条规则是先拼装、后替换,而这些层级是有序的。
flowchart TD
U["text_delta"] --> D["1 已缓存的增量"]
X["..._end"] --> C["2 权威的内容"]
M["message_end"] --> A["3 权威的消息"]
D -->|"被……替换"| C
C -->|"被……替换"| A
三种记录,三个权威层级,逐级升高。..._end 那一行是 text_end、thinking_end 或 toolcall_end,而第 1 级是一个显示上的便利,不是真相的来源。
有一个值得知道的微妙之处:start、done 和 error 仍然在类型联合里,但"常规的智能体循环会把 provider 层的 start、done 和 error 翻译成 message_start 和 message_end 会话事件,而不是把它们作为 message_update 发出。“一个处理它们的消费者是正确的;一个指望它们的消费者是错误的。
而 usage 是累积但惰性的:顶层 usage 是"针对该助手响应的、最新累积的、由 provider 报告的使用量”,它"在 provider 流式输出期间不报告使用量时,可能一直保持为零,直到完成。“不要从它在中途计费。
TypeScript 镜像
json.md 公布了那个确切的变换,它值得一读,因为它精确地说出了什么被移除了:
type JsonAgentSessionEvent =
| Exclude<AgentSessionEvent, { type: "message_update" }>
| {
type: "message_update";
usage: Usage;
assistantMessageEvent: JsonAssistantMessageEvent<AssistantMessageEvent>;
};
除 message_update 之外的一切都原样透传。只有 message_update 被变换,而且只是通过剥去 partial。导出的 JsonAgentSessionEvent 类型可以从 @earendil-works/pi-coding-agent 取得,供那些想把这份契约放进自己类型里的消费者使用。
JSON 流里没有什么
两处缺席,值得围着它们做规划。
扩展 UI 记录不是会话事件。json.md 说它们"是一个独立的 RPC 子协议,不是 AgentSessionEvent 值。“一个在 JSON 模式下调用 ctx.ui.confirm() 的扩展不会产生一条你能回答的记录——没有什么可用来回答它。
存在两个仅限 RPC 的事件。bash_execution_update 为一条直接的 RPC bash 命令按每个输出块流出一条记录,带一个匹配该命令的可选 id。而 extension_error 在一个扩展处理器抛出时出现:
{"type":"extension_error","extensionPath":"/path/to/extension.ts","event":"tool_call","error":"Error message"}
两者都不出现在 JSON 模式里。如果你的自动化依赖于知道一个扩展失败了,你需要 RPC 或进程内 API——一次一次性的 JSON 运行不会告诉你。
运行了什么
examples/ch33-json/ 用 --mode json 运行随附的二进制文件,配一个脚本化的模型,并检查这条流本身:
- 第一条记录是会话头,
version为 3,没有parentId; - 每条记录是一个以 LF 结尾的 JSON 对象,而 stdout 不承载别的任何东西;
- **字符串内部的 U+2028 被原样发出。**按 LF 拆分 stdout 得到完整的记录;而像
readline式读者那样也按 Unicode 行分隔符和段落分隔符拆分,则产生更多记录,其中至少有一个不再能解析。这不是 Pi 产生了坏的分帧。U+2028 在 JSON 字符串内部是合法的,而这条流的分帧是 LF,所以规则是只在 LF 上拆分,不在别的任何东西上拆分。一个按 Unicode 称为行分隔符的每一个字符拆分的读者,才是出错的那个。本章的警告是在真实输出上演示的,而不只是被引用; agent_end后面跟着agent_settled,而agent_settled是最后一条记录;message_update只含增量:没有任何累积式message,也没有任何一次更新里的partial快照;- 三个重建层级彼此一致:缓存起来的
text_delta、text_end的内容和最终的message_end文本完全相同; - 内部词汇表使用
contentIndex,而 provider 层的start、done和error不作为message_update出现; tool_execution_start和tool_execution_end携带调用 ID、名称、参数和结果,而turn_end携带助手消息及其工具结果;- 一个失败的响应是一条带
stopReason: "error"的message_end,而这次运行仍然落定; extension_error和bash_execution_update不出现在 JSON 模式里。
与前一章的对比
print 模式给你一个字符串和一个退出码,而对于答案是如何产生的一句不说。JSON 流给你一切:每一轮、每一次工具调用、每一个 token 增量、每一次重试。它的代价是,正确性现在归你所有了。print 模式的契约是"读到流尾,然后相信退出码”;这一个的契约是"按 LF 拆分,缓存增量,用权威的 content 替换,再用 message_end.message 替换一次,并且等 agent_settled 而不是 agent_end。”
下一章保留同一套事件词汇表,并彻底移除那道进程边界。
下一章:SDK 会话——同一个智能体,在你的进程里,用类型化方法代替被解析的字符串。