Pi 的 JSON Event Stream 模式用pi --mode json消费结构化 Agent 事件流【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills导读本文围绕 Pi一个极简终端编码代理工具安装包为earendil-works/pi-coding-agent的JSON Event Stream 模式展开讲解如何通过pi --mode json prompt让 Pi 以一次性提示方式运行并将整个会话过程中产生的全部 Agent 事件以 JSON LinesJSONL形式输出到 stdout。读完本文你将掌握 JSON 模式的适用场景、完整的事件类型体系会话级事件与基础 Agent 事件、线性的增量式输出格式message_update的 delta-only 设计以及如何用jq等标准命令行工具过滤、消费这些事件流。对于需要双向控制的场景本文也会给出与 RPC 模式、SDK 的取舍建议。一、JSON 模式是什么一次性脚本管道的首选Pi 提供四种运行模式JSON 模式是其中专门为一次性、单向、脚本化场景设计的形态交互模式TUIpi面向日常对话打印模式pi -p prompt打印结果后退出JSON Event Stream 模式pi --mode json prompt所有会话事件以 JSONL 逐行输出到 stdoutRPC 模式pi --mode rpc通过 stdin/stdout 的 JSONL 协议实现双向控制。JSON 模式的定位在 SKILL.md 中有明确表述Prefer JSON mode for one-shot command-line pipelines that only need streamed events, not bidirectional control即只适合一次性提示、只需要读取流式事件、不需要反向控制的命令行管道。它不具备 RPC 模式的双向通信能力——RPC 模式可以接收prompt、steer、abort、bash等命令而 JSON 模式只能发一个提示收一串事件。基本用法pi --mode json Your prompt一行命令即可把 Agent 会话的所有事件推送到 stdout。配合2/dev/null丢弃日志、jq过滤事件类型就能快速构建无侵入的 Agent 观测管道pi --mode json List files 2/dev/null | jq -c select(.type message_end)这条命令是 json.md 中给出的典型示例仅提取每条消息的最终结果message_end屏蔽掉中间的text_delta增量噪音。二、输出格式首行会话头 逐行事件流JSON 模式的输出遵循严格的首行头 事件流结构。会话头session header输出流的第一行是会话元数据{type:session,version:3,id:uuid,timestamp:...,cwd:/path}该行对应会话文件的 header 条目见 session-format.mdversion为会话格式版本当前为 3id是会话 UUIDtimestamp为创建时间cwd为工作目录。注意 header 与后续事件不同——它没有id/parentId字段仅承载元数据。事件流示例随后事件按发生顺序逐行输出每行一个独立 JSON 对象{type:agent_start} {type:turn_start} {type:message_start,message:{role:assistant,content:[]}} {type:message_update,usage:{},assistantMessageEvent:{type:text_delta,contentIndex:0,delta:Hello}} {type:message_end,message:{}} {type:turn_end,message:{},toolResults:[]} {type:agent_end,messages:[]}一个典型的会话生命周期大致为agent_start→turn_start→message_start→若干message_update→message_end→turn_end→agent_end。若 Agent 调用了工具中间还会插入tool_execution_start/tool_execution_update/tool_execution_end事件。三、事件类型全景会话级事件 基础 Agent 事件JSON 模式下的事件使用JsonAgentSessionEvent类型它与 Pi 内部的AgentSessionEvent基本一致唯一区别是流式消息更新message_update省略了累积快照type WithoutPartialT T extends { partial: unknown } ? OmitT, partial : T; type JsonAgentSessionEvent | ExcludeAgentSessionEvent, { type: message_update } | { type: message_update; usage: Usage; assistantMessageEvent: WithoutPartialAssistantMessageEvent };AgentSessionEvent是基础AgentEvent与会话级事件的并集。会话级事件事件类型载荷queue_update{ steering: readonly string[], followUp: readonly string[] }只要任一队列发生变化即触发compaction_start{ reason: manual \| threshold \| overflow }compaction_end{ reason, result: CompactionResult \| undefined, aborted, willRetry, errorMessage? }auto_retry_start{ attempt, maxAttempts, delayMs, errorMessage }auto_retry_end{ success, attempt, finalError? }summarization_retry_scheduled{ attempt, maxAttempts, delayMs, errorMessage }summarization_retry_attempt_start{ source: branchSummary }或{ source: compaction, reason }summarization_retry_finished无额外载荷其中compaction_start的reason三值与 compaction.md 中的触发机制一一对应manual/compact手动触发、threshold上下文超阈值自动压缩、overflow溢出恢复。compaction_end中willRetry为 true 表示溢出压缩成功后会自动重试原提示词。基础 Agent 事件agent_start、agent_end后者携带messagesturn_start、turn_end后者携带message与toolResultsmessage_start携带message、message_update携带usage与assistantMessageEvent、message_end携带messagetool_execution_start携带toolCallId、toolName、args、tool_execution_update在前者基础上增加partialResult、tool_execution_end携带result、isError。需要说明RPC 模式下的完整事件清单还包含agent_settled、bash_execution_update、extension_error等见 rpc.md且 RPC 的message_update同样采用 delta-only 设计——这一设计在 JSON 模式下被严格化JSON 模式的JsonAgentSessionEvent直接通过类型层面剔除了partial字段。四、核心设计为什么message_update是 delta-onlyJSON 模式最值得理解的设计决策是message_update记录的增量delta性质省略累积message字段常规事件流中message_update会携带当前累积的完整消息对象JSON 模式将其省略省略assistantMessageEvent.partial增量事件本身不再包含累积的 partial 快照。这样做的直接收益是流大小保持线性——无论生成多长的回复每个增量记录只携带新增的一小段文本而不是反复传输越来越大的累积快照。组装实时文本的规则由于累积快照被省略消费方需要自己拼装实时内容通过assistantMessageEvent中的contentIndex定位内容块文本、思考内容或工具调用参数各有独立的内容块索引通过delta字段累积增量文本对于工具调用需要缓存toolcall_delta.delta因为只有toolcall_end.toolCall才持有完整调用RPC 文档对此有同样的说明见 rpc.md最终以message_end中携带的message作为权威的最终消息。usage 字段的语义message_update顶层的usage字段携带最新一次累积的、由供应商上报的用量。它有一个值得注意的边界当供应商只在生成完成时才上报用量时中间过程的usage可能一直是 0。因此不要依赖流式过程中的 usage 数值做实时统计应等待message_end或会话结束后的权威数据。Usage对象的结构在 session-format.md 中有精确定义包含input、output、cacheRead、cacheWrite、totalTokens以及同样含四字段加total的cost。五、与 RPC 模式的分工何时不用 JSON 模式json.md 文档结尾给出了明确的边界For bidirectional control, use RPC instead of JSON mode.二者的定位对比如下维度JSON 模式RPC 模式命令pi --mode json promptpi --mode rpc方向单向一次提示 → 事件流双向stdin 发命令stdout 收事件典型场景一次性脚本管道、日志观测IDE 集成、自定义 UI、跨语言客户端增量事件delta-only无partial同样 delta-only会话持久化默认与普通会话一致可用--no-session实现无状态子进程在 SKILL.md 的Build-On-Pi Defaults中给出了更细的三级选择建议Node/TypeScript 进程内应用需要类型安全、直接状态访问、自定义工具/扩展→ 首选SDKcreateAgentSession()/createAgentSessionRuntime()非 Node.js 客户端或需要进程隔离→ 首选RPCpi --mode rpc --no-session起步按需加会话标志一次性命令行管道、只需要流式事件→ 首选JSON 模式。此外JSON 模式与打印模式pi -p都适用于跑一次拿结果的场景但 JSON 模式额外提供完整的事件级可观测性——你可以看到思考增量、工具调用过程、token 用量与压缩事件而打印模式只给你最终文本。六、实战用 jq 消费 JSON 事件流结合上述事件结构可以构建若干高价值的消费管道。只取助手最终消息pi --mode json List files 2/dev/null | jq -c select(.type message_end)message_end的message字段是权威的最终消息含文本、思考与工具调用块适合作为结果抽取的入口。监控工具调用序列pi --mode json Refactor this file 2/dev/null \ | jq -c select(.type tool_execution_start) | {tool: .toolName, args: .args}tool_execution_start携带toolCallId、toolName与args可按toolCallId关联tool_execution_end的result与isError从而重建完整的工具调用闭环。观测压缩与重试pi --mode json Process a large codebase 2/dev/null \ | jq -c select(.type | startswith(compaction) or startswith(auto_retry) or startswith(summarization_retry))上下文超限触发压缩、溢出重试等生命周期事件compaction_start/end、auto_retry_start/end、summarization_retry_*均可在此过滤下可见便于评估长会话的上下文管理行为。实时输出流式文本利用 delta-only 设计可以用jq把流式增量拼成实时文本pi --mode json Write a haiku 2/dev/null \ | jq -r select(.type message_update and .assistantMessageEvent.type text_delta) | .assistantMessageEvent.delta按contentIndexdelta拼装即可工具调用参数与思考内容同理分别消费toolcall_delta与thinking_delta增量。七、补充事件与会话格式的一致性JSON 模式输出的事件结构与 Pi 的会话持久化格式同源。会话文件本身也是 JSONL存储于~/.pi/agent/sessions/--path--/timestamp_uuid.jsonl其中的消息类型与事件体系一一对应UserMessagerole: user、AssistantMessagecontent含 text/thinking/toolCall 块stopReason∈stop/length/toolUse/error/aborted、ToolResultMessage含isError、BashExecutionMessage、CustomMessage等七种消息共同构成AgentMessage联合类型会话条目类型session、message、model_change、compaction、custom等通过id/parentId构成树结构。理解这层同源性有两个实践价值事件语义即持久化语义JSON 模式里看到的compaction_end.reason、message_end.message.stopReason与落盘会话文件中对应条目的字段完全一致结果可跨模式续接JSON 模式跑完的事件流其最终message_end与agent_end.messages中携带的消息对象可直接对应到会话文件中的持久化消息方便后续用/resume或--session无缝续接。更完整的会话文件格式、SessionManagerAPI 与解析建议逐行读取、按entry.type分派、忽略未知类型以兼容未来版本参见 session-format.md。结语pi --mode json是 Pi 四种运行模式中最适合脚本化消费的一种它以首行会话头 逐行 JSONL 事件流的线性格式把 Agent 的思考、文本生成、工具调用、上下文压缩与重试等全生命周期暴露为标准事件并通过 delta-only 的message_update设计保证了流体积随生成长度线性增长。结合jq即可搭建轻量的 Agent 观测、结果抽取与自动化管道一旦需求升级为双向控制如流式打断、中途注入指令、执行 bash则应迁移到 RPC 模式见 rpc.md进程内 Node/TypeScript 应用则优先考虑 SDK。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pi 的 JSON Event Stream 模式：用 `pi --mode json` 消费结构化 Agent 事件流
Pi 的 JSON Event Stream 模式用pi --mode json消费结构化 Agent 事件流【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills导读本文围绕 Pi一个极简终端编码代理工具安装包为earendil-works/pi-coding-agent的JSON Event Stream 模式展开讲解如何通过pi --mode json prompt让 Pi 以一次性提示方式运行并将整个会话过程中产生的全部 Agent 事件以 JSON LinesJSONL形式输出到 stdout。读完本文你将掌握 JSON 模式的适用场景、完整的事件类型体系会话级事件与基础 Agent 事件、线性的增量式输出格式message_update的 delta-only 设计以及如何用jq等标准命令行工具过滤、消费这些事件流。对于需要双向控制的场景本文也会给出与 RPC 模式、SDK 的取舍建议。一、JSON 模式是什么一次性脚本管道的首选Pi 提供四种运行模式JSON 模式是其中专门为一次性、单向、脚本化场景设计的形态交互模式TUIpi面向日常对话打印模式pi -p prompt打印结果后退出JSON Event Stream 模式pi --mode json prompt所有会话事件以 JSONL 逐行输出到 stdoutRPC 模式pi --mode rpc通过 stdin/stdout 的 JSONL 协议实现双向控制。JSON 模式的定位在 SKILL.md 中有明确表述Prefer JSON mode for one-shot command-line pipelines that only need streamed events, not bidirectional control即只适合一次性提示、只需要读取流式事件、不需要反向控制的命令行管道。它不具备 RPC 模式的双向通信能力——RPC 模式可以接收prompt、steer、abort、bash等命令而 JSON 模式只能发一个提示收一串事件。基本用法pi --mode json Your prompt一行命令即可把 Agent 会话的所有事件推送到 stdout。配合2/dev/null丢弃日志、jq过滤事件类型就能快速构建无侵入的 Agent 观测管道pi --mode json List files 2/dev/null | jq -c select(.type message_end)这条命令是 json.md 中给出的典型示例仅提取每条消息的最终结果message_end屏蔽掉中间的text_delta增量噪音。二、输出格式首行会话头 逐行事件流JSON 模式的输出遵循严格的首行头 事件流结构。会话头session header输出流的第一行是会话元数据{type:session,version:3,id:uuid,timestamp:...,cwd:/path}该行对应会话文件的 header 条目见 session-format.mdversion为会话格式版本当前为 3id是会话 UUIDtimestamp为创建时间cwd为工作目录。注意 header 与后续事件不同——它没有id/parentId字段仅承载元数据。事件流示例随后事件按发生顺序逐行输出每行一个独立 JSON 对象{type:agent_start} {type:turn_start} {type:message_start,message:{role:assistant,content:[]}} {type:message_update,usage:{},assistantMessageEvent:{type:text_delta,contentIndex:0,delta:Hello}} {type:message_end,message:{}} {type:turn_end,message:{},toolResults:[]} {type:agent_end,messages:[]}一个典型的会话生命周期大致为agent_start→turn_start→message_start→若干message_update→message_end→turn_end→agent_end。若 Agent 调用了工具中间还会插入tool_execution_start/tool_execution_update/tool_execution_end事件。三、事件类型全景会话级事件 基础 Agent 事件JSON 模式下的事件使用JsonAgentSessionEvent类型它与 Pi 内部的AgentSessionEvent基本一致唯一区别是流式消息更新message_update省略了累积快照type WithoutPartialT T extends { partial: unknown } ? OmitT, partial : T; type JsonAgentSessionEvent | ExcludeAgentSessionEvent, { type: message_update } | { type: message_update; usage: Usage; assistantMessageEvent: WithoutPartialAssistantMessageEvent };AgentSessionEvent是基础AgentEvent与会话级事件的并集。会话级事件事件类型载荷queue_update{ steering: readonly string[], followUp: readonly string[] }只要任一队列发生变化即触发compaction_start{ reason: manual \| threshold \| overflow }compaction_end{ reason, result: CompactionResult \| undefined, aborted, willRetry, errorMessage? }auto_retry_start{ attempt, maxAttempts, delayMs, errorMessage }auto_retry_end{ success, attempt, finalError? }summarization_retry_scheduled{ attempt, maxAttempts, delayMs, errorMessage }summarization_retry_attempt_start{ source: branchSummary }或{ source: compaction, reason }summarization_retry_finished无额外载荷其中compaction_start的reason三值与 compaction.md 中的触发机制一一对应manual/compact手动触发、threshold上下文超阈值自动压缩、overflow溢出恢复。compaction_end中willRetry为 true 表示溢出压缩成功后会自动重试原提示词。基础 Agent 事件agent_start、agent_end后者携带messagesturn_start、turn_end后者携带message与toolResultsmessage_start携带message、message_update携带usage与assistantMessageEvent、message_end携带messagetool_execution_start携带toolCallId、toolName、args、tool_execution_update在前者基础上增加partialResult、tool_execution_end携带result、isError。需要说明RPC 模式下的完整事件清单还包含agent_settled、bash_execution_update、extension_error等见 rpc.md且 RPC 的message_update同样采用 delta-only 设计——这一设计在 JSON 模式下被严格化JSON 模式的JsonAgentSessionEvent直接通过类型层面剔除了partial字段。四、核心设计为什么message_update是 delta-onlyJSON 模式最值得理解的设计决策是message_update记录的增量delta性质省略累积message字段常规事件流中message_update会携带当前累积的完整消息对象JSON 模式将其省略省略assistantMessageEvent.partial增量事件本身不再包含累积的 partial 快照。这样做的直接收益是流大小保持线性——无论生成多长的回复每个增量记录只携带新增的一小段文本而不是反复传输越来越大的累积快照。组装实时文本的规则由于累积快照被省略消费方需要自己拼装实时内容通过assistantMessageEvent中的contentIndex定位内容块文本、思考内容或工具调用参数各有独立的内容块索引通过delta字段累积增量文本对于工具调用需要缓存toolcall_delta.delta因为只有toolcall_end.toolCall才持有完整调用RPC 文档对此有同样的说明见 rpc.md最终以message_end中携带的message作为权威的最终消息。usage 字段的语义message_update顶层的usage字段携带最新一次累积的、由供应商上报的用量。它有一个值得注意的边界当供应商只在生成完成时才上报用量时中间过程的usage可能一直是 0。因此不要依赖流式过程中的 usage 数值做实时统计应等待message_end或会话结束后的权威数据。Usage对象的结构在 session-format.md 中有精确定义包含input、output、cacheRead、cacheWrite、totalTokens以及同样含四字段加total的cost。五、与 RPC 模式的分工何时不用 JSON 模式json.md 文档结尾给出了明确的边界For bidirectional control, use RPC instead of JSON mode.二者的定位对比如下维度JSON 模式RPC 模式命令pi --mode json promptpi --mode rpc方向单向一次提示 → 事件流双向stdin 发命令stdout 收事件典型场景一次性脚本管道、日志观测IDE 集成、自定义 UI、跨语言客户端增量事件delta-only无partial同样 delta-only会话持久化默认与普通会话一致可用--no-session实现无状态子进程在 SKILL.md 的Build-On-Pi Defaults中给出了更细的三级选择建议Node/TypeScript 进程内应用需要类型安全、直接状态访问、自定义工具/扩展→ 首选SDKcreateAgentSession()/createAgentSessionRuntime()非 Node.js 客户端或需要进程隔离→ 首选RPCpi --mode rpc --no-session起步按需加会话标志一次性命令行管道、只需要流式事件→ 首选JSON 模式。此外JSON 模式与打印模式pi -p都适用于跑一次拿结果的场景但 JSON 模式额外提供完整的事件级可观测性——你可以看到思考增量、工具调用过程、token 用量与压缩事件而打印模式只给你最终文本。六、实战用 jq 消费 JSON 事件流结合上述事件结构可以构建若干高价值的消费管道。只取助手最终消息pi --mode json List files 2/dev/null | jq -c select(.type message_end)message_end的message字段是权威的最终消息含文本、思考与工具调用块适合作为结果抽取的入口。监控工具调用序列pi --mode json Refactor this file 2/dev/null \ | jq -c select(.type tool_execution_start) | {tool: .toolName, args: .args}tool_execution_start携带toolCallId、toolName与args可按toolCallId关联tool_execution_end的result与isError从而重建完整的工具调用闭环。观测压缩与重试pi --mode json Process a large codebase 2/dev/null \ | jq -c select(.type | startswith(compaction) or startswith(auto_retry) or startswith(summarization_retry))上下文超限触发压缩、溢出重试等生命周期事件compaction_start/end、auto_retry_start/end、summarization_retry_*均可在此过滤下可见便于评估长会话的上下文管理行为。实时输出流式文本利用 delta-only 设计可以用jq把流式增量拼成实时文本pi --mode json Write a haiku 2/dev/null \ | jq -r select(.type message_update and .assistantMessageEvent.type text_delta) | .assistantMessageEvent.delta按contentIndexdelta拼装即可工具调用参数与思考内容同理分别消费toolcall_delta与thinking_delta增量。七、补充事件与会话格式的一致性JSON 模式输出的事件结构与 Pi 的会话持久化格式同源。会话文件本身也是 JSONL存储于~/.pi/agent/sessions/--path--/timestamp_uuid.jsonl其中的消息类型与事件体系一一对应UserMessagerole: user、AssistantMessagecontent含 text/thinking/toolCall 块stopReason∈stop/length/toolUse/error/aborted、ToolResultMessage含isError、BashExecutionMessage、CustomMessage等七种消息共同构成AgentMessage联合类型会话条目类型session、message、model_change、compaction、custom等通过id/parentId构成树结构。理解这层同源性有两个实践价值事件语义即持久化语义JSON 模式里看到的compaction_end.reason、message_end.message.stopReason与落盘会话文件中对应条目的字段完全一致结果可跨模式续接JSON 模式跑完的事件流其最终message_end与agent_end.messages中携带的消息对象可直接对应到会话文件中的持久化消息方便后续用/resume或--session无缝续接。更完整的会话文件格式、SessionManagerAPI 与解析建议逐行读取、按entry.type分派、忽略未知类型以兼容未来版本参见 session-format.md。结语pi --mode json是 Pi 四种运行模式中最适合脚本化消费的一种它以首行会话头 逐行 JSONL 事件流的线性格式把 Agent 的思考、文本生成、工具调用、上下文压缩与重试等全生命周期暴露为标准事件并通过 delta-only 的message_update设计保证了流体积随生成长度线性增长。结合jq即可搭建轻量的 Agent 观测、结果抽取与自动化管道一旦需求升级为双向控制如流式打断、中途注入指令、执行 bash则应迁移到 RPC 模式见 rpc.md进程内 Node/TypeScript 应用则优先考虑 SDK。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考