把 Pi 看成契约网络

从公开接口、消息、事件和状态边界理解 Pi,追踪一次带工具的 prompt。

本章目录CONTENTS ↓

本章以 Pi 1.1.0 的 2026-10-11 源码快照 为基准;实验性接口不代表长期兼容承诺。

本章目标:看到一个 Pi 行为时,你能先判断它属于哪一层、跨过什么边界,而不是直接跳进最大的类里。

从外部可观察行为出发

复刻 mini_pi 时,先确定消费者依赖哪些行为,再决定内部实现。兼容性首先需要回答下面的问题:

外部观察者能看见什么? import 路径与导出、数据形状、事件顺序、状态变化、失败方式和持久格式,才构成兼容边界。

Pi 的根 README 公开区分 coding agent、agent core、统一 LLM API、TUI 等包;各包 manifest 又把依赖方向写死。这说明分包并非目录整理,而是把变化隔离在不同契约后面。源码证据:项目总览、workspace manifest。

按职责理解六组边界

pi-ai

让不同 provider 使用同一套Model、Message、Tool和 stream event。

pi-agent-core

拥有 assistant ↔ tool 的循环、状态、队列和生命周期事件。

pi-coding-agent

组合会话、内置工具、扩展、资源、压缩、CLI/SDK 和交互模式。

pi-tui

把事件变成终端组件和差分渲染;自身不依赖其他 Pi 包。

protocol/client/server

通过路由 envelope 和 framed CBOR 连接客户端与会话。当前快照用 serverId、sessionId、attachmentId 标识路由;服务调用与订阅状态由 Chord 和应用定义。

telemetry/durable

让观测和持久化可替换,避免基础循环绑定到单一运行时。

完整包图和后续路线见架构与课程地图;术语见词汇表;精确时序见Agent 事件顺序速查。

追踪一次带工具的 prompt

  1. 产品层接受输入 AgentSession.prompt()处理模板、扩展命令、图片与排队规则,再把规范化消息交给 core Agent。
  2. 运行时层开启 run/turn Agent建立 active run 和 abort signal;low-level loop 发出agent_start → turn_start。
  3. 模型层流式返回 公开入口接受 Model + Context;provider stream function 接收归一化的 TranscriptContext,用统一事件更新 partial AssistantMessage。
  4. 运行时层执行工具 识别toolCall,校验参数,经过 before/after hooks,执行并生成ToolResultMessage。
  5. 结果回到下一轮 tool result 追加进 context;若仍需继续,新的turn_start后再次调用模型。
  6. 产品与显示层收口 订阅者消费事件以持久化和渲染。正常路径没有更多 tool/steer/follow-up 时,运行时发出 agent_end;错误、取消或明确结束决策也会收口。

这条路径的第一手规范是agent README 的 event flow,实现入口是agent-loop.ts。推荐本课后只读后者顶部到runLoop()结束:先看两个嵌套循环,不必钻进每个 tool helper。

关键辨析 一个turn是“一次 assistant response + 它的工具批次”;一个run可以包含多轮 turn。把两者混淆,会写错事件顺序、队列时机和 compaction 边界。

mini_pi 哪些能简化?

必须先兼容 内部可以简化
公开包名、子路径、常用导出符号 文件组织、类的拆分数量、私有 helper
Message/Tool/Event 的 discriminated unions 先只实现一个 provider adapter
正常、toolUse、error、aborted 的可观察时序 先顺序执行工具,再补并行执行
AgentSession 常用方法与 session 文件语义 先用朴素数组/JSONL 算法,保留相同行为
扩展和工具的注册接缝 首版不实现完整选择器和视觉细节

这里的“先”很重要:最终兼容范围要由真实调用样本和 contract tests 决定,不能只凭源码文件大小。

检索练习

先不回看上文,完成三题。展开解析前,先说明选择的理由。

  1. 模型已返回toolCall,接下来由哪一层承担核心责任?

模型层 / 运行层 / 显示层 / 协议层

查看解析

答案:运行层。toolCall 的校验、执行和 ToolResultMessage 生成属于 Agent loop。

  1. Anthropic 与 OpenAI 的响应差异首先应被哪一层吸收?

模型层 / 运行层 / 产品层 / 显示层

查看解析

答案:模型层。不同 provider 的差异在 pi-ai adapter 后收敛为统一消息与流事件。

  1. 下列哪一项最先进入 mini_pi 的兼容测试?

私有类 / 目录树 / 事件序 / 函数体

查看解析

答案:事件序。事件顺序是消费者可观察行为;私有 helper 和内部拆分类通常可以替换。

离开页面前的 90 秒

  1. 合上本页,从记忆写出:coding-agent → agent → ai → provider。
  2. 在agent旁画出 tool 的往返环。
  3. 在箭头上标出至少两种兼容契约,例如 event order、message shape。

主参考:agent-loop.ts · 补充:Pi SDK 官方文档 · 课程地图

这一页,先记到这里。