JSON 事件流模式

pi --mode json "Your prompt"

将所有会话事件以 JSON 行格式输出到 stdout。适用于将 pi 集成到其他工具或自定义 UI 中。

事件类型

Wire 事件使用 JsonAgentSessionEvent。它匹配 AgentSessionEvent 除了流式消息更新会省略累积快照：

type WithoutPartial<T> = T extends { partial: unknown } ? Omit<T, "partial"> : T;
 
type JsonAgentSessionEvent =
  | Exclude<AgentSessionEvent, { type: "message_update" }>
  | {
      type: "message_update";
      assistantMessageEvent: WithoutPartial<AssistantMessageEvent>;
    };

queue_update 会在待处理引导队列和后续队列发生变化时发出完整的队列。 compaction_start 和 compaction_end 涵盖了手动和自动压缩。

其他基础事件来自 AgentEvent:

type AgentEvent =
  // Agent lifecycle
  | { type: "agent_start" }
  | { type: "agent_end"; messages: AgentMessage[] }
  // Turn lifecycle
  | { type: "turn_start" }
  | { type: "turn_end"; message: AgentMessage; toolResults: ToolResultMessage[] }
  // Message lifecycle
  | { type: "message_start"; message: AgentMessage }
  | { type: "message_update"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }
  | { type: "message_end"; message: AgentMessage }
  // Tool execution
  | { type: "tool_execution_start"; toolCallId: string; toolName: string; args: any }
  | { type: "tool_execution_update"; toolCallId: string; toolName: string; args: any; partialResult: any }
  | { type: "tool_execution_end"; toolCallId: string; toolName: string; result: any; isError: boolean };

消息类型

基础消息来自 packages/ai/src/types.ts:

UserMessage（第 134 行）
AssistantMessage（第 140 行）
ToolResultMessage（第 152 行）

扩展消息来自 packages/coding-agent/src/core/messages.ts:

BashExecutionMessage（第 29 行）
CustomMessage（第 46 行）
BranchSummaryMessage（第 55 行）
CompactionSummaryMessage（第 62 行）

输出格式

每一行都是一个 JSON 对象。第一行是会话头：

{"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","assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
{"type":"message_end","message":{...}}
{"type":"turn_end","message":{...},"toolResults":[]}
{"type":"agent_end","messages":[...]}

message_update 记录仅包含增量。它们省略了累积的 message 字段和 assistantMessageEvent.partial 以保持流大小线性增长。使用 contentIndex 和 delta 在需要时组装实时文本、思考或工具调用参数。 message_end 包含最终权威消息。

示例

pi --mode json "List files" 2>/dev/null | jq -c 'select(.type == "message_end")'