本文为社区中文翻译（依据 MIT 协议），阅读英文原文 →。译文可能滞后于上游更新。

JSON 事件流模式

pi --mode json "你的提示词"

把全部会话事件以 JSON 行输出到 stdout。适合把 Pi 集成进其他工具或自定义 UI。

事件类型

线上事件使用 JsonAgentSessionEvent。它与 AgentSessionEvent 一致，只是流式消息更新省略了累积快照：

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：

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：

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

输出格式

每行一个 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","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 包含最终权威消息。

示例

pi --mode json "列出文件" 2>/dev/null | jq -c 'select(.type == "message_end")'
← RPC 模式 TUI 组件 →