Pi Agent 三层 Hook 系统架构

一、三层 Hook 定义

二、Agent Loop 层回调函数

三、Agent 事件层事件类型

export 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; ... }
  | { type: "message_end"; message: AgentMessage }  // → 触发 Session 写入
  | { type: "tool_execution_start/update/end"; ... }

四、Harness 层 Phantom Type 设计

declare const HookResult: unique symbol;

interface HookEvent<TType extends string, TResult = void> {
  type: TType;
  readonly [HookResult]?: TResult;  // 只在类型层面存在
}

type ResultOf<E> = E extends { readonly [HookResult]?: infer R } ? R : void;

五、完整 ReAct Loop 时间线

六、AppendOnlyLog 写入机制

6.1 写入时机：双重策略

6.2 三种消息的写入时机与数据结构

UserMessage {
  role: "user";
  content: string | (TextContent|ImageContent)[];
  timestamp: number;
}

AssistantMessage {
  role: "assistant";
  content: (TextContent|ThinkingContent|ToolCall)[];
  api: Api;
  provider: string;
  model: string;
  usage: Usage;
  stopReason: StopReason;
  timestamp: number;
}

ToolResultMessage {
  role: "toolResult";
  toolCallId: string;
  toolName: string;
  content: (TextContent|ImageContent)[];
  details?: any;
  isError: boolean;
  timestamp: number;
}

关键设计原则：消息不可变性

一旦 message_end 触发，消息内容即视为最终确定，立即写入 AppendOnlyLog，之后不再修改。三种消息的差异在于：

• Prompt 消息：几乎瞬间完成，无修改机会，写入原始输入
• Assistant 消息：流式构建，在 message_update 期间内容持续变化，只有 message_end 时才最终定型并写入
• ToolResult 消息：工具同步返回，内容确定后立刻写入（但可在写入前通过 tool_result hook 修改）

6.3 官方消息修改入口

Pi 提供以下官方修改入口，在消息写入前对其进行修改：

harness.on("before_agent_start", async (event) => {
  return {
    systemPrompt: event.systemPrompt + "\n请记住：简洁回答。",
    messages: [{ role: "system", content: "上下文..." }]
  };
});

harness.on("context", async (event) => {
  // 1. 裁剪过长历史
  const trimmed = event.messages.slice(-20);
  // 2. 注入系统提示
  const modified = [
    ...trimmed,
    { role: "user", content: "请记住：简洁回答。" }
  ];
  return { messages: modified };
});

harness.on("before_provider_request", async (event) => {
  return {
    model: cheaperModel,  // 降级模型
    streamOptions: { ... }
  };
});

harness.on("tool_result", async (event) => {
  if (event.toolName === "read_file") {
    return {
      content: "[截断] " + event.content.slice(0, 1000),
      details: { truncated: true }
    };
  }
});

agent.prepareNextTurn = async (ctx) => {
  // 修改最后一条消息
  const modified = [...ctx.newMessages];
  modified[modified.length - 1].content += "[补充]";
  return {
    context: { ...ctx.context, messages: modified },
    model: newModel
  };
};

关键限制

• Prompt 消息（已写入的）：无官方 API 修改，设计上就是原始用户输入
• Assistant 消息（LLM 输出）：无官方 API 修改，设计上保持 LLM 原始输出不可篡改
• 如需强制修改：只能通过 prepareNextTurn 替换整条 context.messages 数组

对 Append Only Log 的友好性分析

不同修改入口对 Session 持久化的影响：

6.4 Phase 管理与会话写入

type AgentHarnessPhase = "idle" | "turn" | "compaction" | "branch_summary" | "retry";

// "turn" 阶段：活跃操作期
if (this.phase === "turn") {
  // 变更进入 pending 队列，不立即写入
  this.pendingSessionWrites.push({ type: "model_change", ... });
}

// "idle" 阶段：可立即写入
if (this.phase === "idle") {
  await this.session.appendModelChange(model.provider, model.id);
}

6.5 Session Entry 类型

所有状态变更建模为不可变的 Entry，追加到 Session Tree：

type SessionTreeEntry =
  | MessageEntry              // 普通消息
  | ModelChangeEntry          // 模型切换
  | ThinkingLevelChangeEntry  // thinking 级别变更
  | ActiveToolsChangeEntry    // 工具集变更
  | CompactionEntry           // 压缩操作
  | BranchSummaryEntry        // 分支摘要
  | LabelEntry                // 标签
  | CustomEntry;              // 自定义数据

七、状态恢复机制

7.1 恢复流程：半持久化架构

7.2 核心归约函数

export function buildSessionContext(pathEntries: SessionTreeEntry[]): SessionContext {
  // 从 entries 提取配置状态
  for (const entry of pathEntries) {
    if (entry.type === "thinking_level_change") {
      thinkingLevel = entry.thinkingLevel;
    } else if (entry.type === "model_change") {
      model = { provider: entry.provider, modelId: entry.modelId };
    } else if (entry.type === "active_tools_change") {
      activeToolNames = [...entry.activeToolNames];
    } else if (entry.type === "compaction") {
      compaction = entry;  // 记录压缩点
    }
  }

  // 重建消息列表（处理 compaction 截断）
  if (compaction) {
    // 压缩点之前的消息被 summary 替代
    messages.push(createCompactionSummaryMessage(...));
    // 只保留 firstKeptEntryId 之后的 entries
    for (const entry of keptEntries) appendMessage(entry);
  } else {
    for (const entry of pathEntries) appendMessage(entry);
  }

  return { messages, thinkingLevel, model, activeToolNames };
}

7.3 恢复策略

7.4 设计哲学

半持久化架构：Session 存储可序列化的状态和配置（messages、model changes、tool changes），但工具实现、模型对象、钩子逻辑等运行时依赖必须由 Host App 重新注入。

// 未来的恢复 Builder（设计中）
const harness = await AgentHarness.builder()
  .env(env)
  .session(session)           // 提供持久化 session
  .model(defaultModel)        // 提供默认模型
  .tools(runtimeTools)        // 提供运行时工具（必须）
  .restore({ missingActiveTools: "fail" });  // 恢复策略

八、Pi Extension 扩展系统

8.1 Extension 与三层 Hook 的关系

Extension 是 Pi 的用户级扩展机制，与三层 Hook 的关系如下：

8.2 Extension 能操作的能力矩阵

8.3 Extension 的完整事件订阅

type ExtensionEvent =
  // Session 生命周期
  | ResourcesDiscoverEvent
  | SessionStartEvent | SessionBeforeSwitchEvent | SessionBeforeForkEvent
  | SessionBeforeCompactEvent | SessionCompactEvent | SessionShutdownEvent
  | SessionBeforeTreeEvent | SessionTreeEvent

  // Agent 执行（可修改的 HookEvent）
  | ContextEvent                    // 修改消息列表
  | BeforeProviderRequestEvent      // 修改请求 payload
  | BeforeAgentStartEvent           // 修改 systemPrompt
  | ToolCallEvent                   // 可 block，可 mutate input
  | ToolResultEvent                 // 可 patch result

  // Agent 执行（只读观察）
  | AgentStartEvent | AgentEndEvent
  | TurnStartEvent | TurnEndEvent
  | MessageStartEvent | MessageUpdateEvent | MessageEndEvent
  | ToolExecutionStartEvent | ToolExecutionUpdateEvent | ToolExecutionEndEvent
  | AfterProviderResponseEvent

  // 配置变更与用户输入
  | ModelSelectEvent | ThinkingLevelSelectEvent
  | UserBashEvent | InputEvent;

8.4 Extension 的限制

8.5 Extension 设计哲学

沙盒化扩展模型：Extension 只能通过类型安全的 Harness HookEvent 参与 Agent 生命周期，无法直接操作 Agent Loop 层的执行控制点。这种设计保证了：

• 稳定性：Extension 崩溃不会破坏核心 Agent 状态
• 可预测性：所有修改通过声明式的事件结果对象传递
• 可审计性：Extension 的所有操作可追踪、可回放

九、关键设计原则总结

Agent Loop 层 = "执行控制点" —— 同步调用，直接返回值影响执行，如 block 工具、修改消息格式、决定停止。

Agent 事件层 = "状态通知流" —— 异步事件，只读观察，如 UI 更新、日志、监控。message_end 触发 Session 写入，turn_end 触发 pending writes 批量刷新。

Harness/Extension 层 = "拦截与扩展系统" —— 类型安全的 HookEvent，支持 block/patch/cancel，与 Agent 事件并行但独立。

状态持久化 = "Append-Only Log" —— 每个消息和配置变更作为不可变 Entry 追加写入，通过归约（reduce）重建当前状态，实现崩溃恢复和会话重建。

一句话总结：Agent Loop 层控制"怎么执行"，Agent 事件层通知"发生了什么"并驱动"何时写入"，Harness 层决定"是否允许/如何修改"，Session 层保证"状态可恢复" —— 四层交织形成完整的可信 Agent 架构。