Pi JSON Event Stream 模式

pi --mode json "Your prompt"

将所有 session 事件输出为 JSON lines（stdout），是外部工具、自定义 UI、以及 OpenClaw 等 harness 集成 pi 的重要接入面。

输出格式

第一行是 session header：

{"type":"session","version":3,"id":"uuid","timestamp":"...","cwd":"/path"}

之后按事件发生顺序逐行输出：

{"type":"agent_start"}
{"type":"turn_start"}
{"type":"message_start","message":{"role":"assistant","content":[],...}}
{"type":"message_update","message":{...},"assistantMessageEvent":{"type":"text_delta","delta":"Hello"}}
{"type":"message_end","message":{...}}
{"type":"turn_end","message":{...},"toolResults":[]}
{"type":"agent_end","messages":[...]}

事件类型完整列表

Agent/Turn/Message 基础事件（继承自 AgentEvent）

事件	携带字段
agent_start	—
agent_end	messages
turn_start	—
turn_end	message, toolResults
message_start	message
message_update	message, assistantMessageEvent（含 delta）
message_end	message
tool_execution_start	toolCallId, toolName, args
tool_execution_update	toolCallId, toolName, args, partialResult
tool_execution_end	toolCallId, toolName, result, isError

JSON 模式专属扩展事件

事件	说明
queue_update	任何时刻队列变化时发出，携带完整的 steering 和 followUp 待处理消息列表
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?

消息类型

基础消息（来自 packages/ai/src/types.ts）：

• UserMessage
• AssistantMessage
• ToolResultMessage

编程 Agent 扩展消息（来自 packages/coding-agent/src/core/messages.ts）：

• BashExecutionMessage
• CustomMessage（Extension 自定义消息）
• BranchSummaryMessage
• CompactionSummaryMessage

常见用法

# 只提取最终 assistant 消息
pi --mode json "List files" 2>/dev/null | jq -c 'select(.type == "message_end")'
 
# 只提取 text_delta 输出
pi --mode json "Hello" 2>/dev/null \
  | jq -r 'select(.assistantMessageEvent.type == "text_delta") | .assistantMessageEvent.delta'
 
# 监听压缩事件
pi -c --mode json 2>/dev/null | jq 'select(.type | startswith("compaction"))'

与 RPC 模式的区别

维度	JSON 模式（--mode json）	RPC 模式（--mode rpc）
方向	单向输出（stdout）	双向（stdin/stdout JSONL 协议）
用途	观察/解析 pi 的输出	进程间集成，外部进程驱动 pi
接入复杂度	低，只需解析 stdout	高，需实现完整 RPC 协议

详见 rpc-sdk。

相关页面：pi-agent-core | pi-coding-agent