pi 工具 JSON 行事件流输出模式详解

pi --mode json "Your prompt"

将所有会话事件以 JSON 行形式输出到标准输出。适用于将 pi 集成到其他工具或自定义界面中。

## 事件类型

事件定义在 [`AgentSessionEvent`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/agent-session.ts#L102) 中：

```typescript
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 }
  | { type: "summarization_retry_scheduled"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }
  | { type: "summarization_retry_attempt_start"; source: "branchSummary" }
  | { type: "summarization_retry_attempt_start"; source: "compaction"; reason: "manual" | "threshold" | "overflow" }
  | { type: "summarization_retry_finished" };

queue_update 在待处理的 steering 和 follow-up 队列发生变化时发出完整队列内容。compaction_start 和 compaction_end 涵盖手动和自动压缩。

基础事件来自 AgentEvent：

type AgentEvent =
  // 智能体生命周期
  | { type: "agent_start" }
  | { type: "agent_end"; messages: AgentMessage[] }
  // 轮次生命周期
  | { type: "turn_start" }
  | { type: "turn_end"; message: AgentMessage; toolResults: ToolResultMessage[] }
  // 消息生命周期
  | { type: "message_start"; message: AgentMessage }
  | { type: "message_update"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }
  | { type: "message_end"; message: AgentMessage }
  // 工具执行
  | { 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")'

• 原文链接： github.com/badlogic/pi-m...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～