JSON 事件流模式

pi --mode json "Your prompt"

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

事件类型

事件定义在 AgentSessionEvent 中：

type AgentSessionEvent =
  | AgentEvent
  | { type: 'queue_update'; steering: readonly string[]; followUp: readonly string[] }
  | { type: 'compaction_start'; reason: 'manual' | 'threshold' | 'overflow' }
  | {
      type: 'compaction_end'
      reason: 'manual' | 'threshold' | 'overflow'
      result: CompactionResult | undefined
      aborted: boolean
      willRetry: boolean
      errorMessage?: string
    }
  | {
      type: 'auto_retry_start'
      attempt: number
      maxAttempts: number
      delayMs: number
      errorMessage: string
    }
  | { type: 'auto_retry_end'; success: boolean; attempt: number; finalError?: string }

每当待处理的 steering 和 follow-up 队列发生变化时，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","message":{...},"assistantMessageEvent":{"type":"text_delta","delta":"Hello",...}}
{"type":"message_end","message":{...}}
{"type":"turn_end","message":{...},"toolResults":[]}
{"type":"agent_end","messages":[...]}

示例

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