# JSON 事件流模式

> 以 JSON Lines 输出 pi 会话事件，便于将 pi 集成到其他工具或自定义界面。

---

LLMS 索引： [llms.txt](/llms.txt)

---

```bash
pi --mode json "Your prompt"
```

该模式将所有会话事件以 JSON 行的形式输出到 stdout。适合将 pi 集成到其他工具或自定义界面。

## 事件类型 {#event-types}

线上传输的事件使用 `JsonAgentSessionEvent`。它与
[`AgentSessionEvent`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/core/agent-session.ts)
一致，区别在于流式消息更新会省略累积快照：

```typescript
type WithoutPartial<T> = T extends { partial: unknown } ? Omit<T, "partial"> : T;

type JsonAssistantMessageEvent<T> = T extends { type: "toolcall_start"; partial: unknown }
  ? WithoutPartial<T> & { id: string; toolName: string }
  : WithoutPartial<T>;

type JsonAgentSessionEvent =
  | Exclude<AgentSessionEvent, { type: "message_update" }>
  | {
      type: "message_update";
      usage: Usage;
      assistantMessageEvent: JsonAssistantMessageEvent<AssistantMessageEvent>;
    };
```

`queue_update` 会在待处理的转向队列和后续任务队列发生变化时输出完整队列。`compaction_start` 和 `compaction_end` 同时覆盖手动和自动上下文压缩。

其他基础事件来自
[`AgentEvent`](https://github.com/earendil-works/pi/blob/main/packages/agent/src/types.ts)：

```typescript
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 };
```

## 消息类型 {#message-types}

基础消息定义于 [`packages/ai/src/types.ts`](https://github.com/earendil-works/pi/blob/main/packages/ai/src/types.ts#L134)：

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

扩展消息定义于 [`packages/coding-agent/src/core/messages.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/core/messages.ts#L29)：

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

## 输出格式 {#output-format}

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

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

随后是按发生顺序输出的事件：

```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":[...]}
```

`message_update` 记录仅包含增量。它们同时省略了累积的 `message` 字段和
`assistantMessageEvent.partial`，以保持流大小的线性增长。顶层的 `usage` 字段包含
提供商报告的最新累计用量；如果提供商只在完成时上报用量，该字段可能一直为零。如有需要，
可以使用 `contentIndex` 和 `delta` 拼装实时的文本、思考内容或工具调用参数。`toolcall_start`
事件还包含大小固定的 `id` 和 `toolName` 字段。`message_end` 包含最终权威的消息。

## 示例 {#example}

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

---

反链：

- [使用 Pi](/book/pi/usage/)