把 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
- 产品层接受输入
AgentSession.prompt()处理模板、扩展命令、图片与排队规则,再把规范化消息交给 core Agent。 - 运行时层开启 run/turn
Agent建立 active run 和 abort signal;low-level loop 发出agent_start → turn_start。 - 模型层流式返回 公开入口接受
Model + Context;provider stream function 接收归一化的TranscriptContext,用统一事件更新 partialAssistantMessage。 - 运行时层执行工具 识别
toolCall,校验参数,经过 before/after hooks,执行并生成ToolResultMessage。 - 结果回到下一轮 tool result 追加进 context;若仍需继续,新的
turn_start后再次调用模型。 - 产品与显示层收口 订阅者消费事件以持久化和渲染。正常路径没有更多 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 决定,不能只凭源码文件大小。
检索练习
先不回看上文,完成三题。展开解析前,先说明选择的理由。
- 模型已返回
toolCall,接下来由哪一层承担核心责任?
模型层 / 运行层 / 显示层 / 协议层
查看解析
答案:运行层。toolCall 的校验、执行和 ToolResultMessage 生成属于 Agent loop。
- Anthropic 与 OpenAI 的响应差异首先应被哪一层吸收?
模型层 / 运行层 / 产品层 / 显示层
查看解析
答案:模型层。不同 provider 的差异在 pi-ai adapter 后收敛为统一消息与流事件。
- 下列哪一项最先进入 mini_pi 的兼容测试?
私有类 / 目录树 / 事件序 / 函数体
查看解析
答案:事件序。事件顺序是消费者可观察行为;私有 helper 和内部拆分类通常可以替换。
离开页面前的 90 秒
- 合上本页,从记忆写出:
coding-agent → agent → ai → provider。 - 在
agent旁画出 tool 的往返环。 - 在箭头上标出至少两种兼容契约,例如 event order、message shape。
主参考:agent-loop.ts · 补充:Pi SDK 官方文档 · 课程地图
这一页,先记到这里。