Pi 架构与课程地图
查阅模块职责、兼容审计维度和从模型层到持久化的学习路线。
本章目录CONTENTS ↓
本章以 Pi 1.1.0 的 2026-10-11 源码快照 为基准;实验性接口不代表长期兼容承诺。
目标不是记目录,而是知道每种变化应该由哪一层吸收,以及 mini_pi 必须在哪些边界表现得像 Pi。
模块职责
-
pi-coding-agent:产品装配层:CLI、AgentSession、SDK、内置工具、资源发现、扩展、会话、compaction、交互模式。 -
pi-agent-core:运行时层:Agent 状态机、tool loop、队列与事件。持久执行的 Harness 已分离到实验性的pi-durable包。 -
pi-ai:模型层:统一消息/模型/工具/事件类型,provider factories 与各 API adapter。 -
pi-tui:显示层:终端、布局、组件、输入、差分渲染;不依赖其他 Pi 包。 -
protocol · client · server:远程层:严格 wire schema + framed CBOR、transport-neutral 客户端、应用注入 service 的服务器。 -
telemetry · durable:横切层:telemetry 提供观测契约;实验性的 pi-durable 基于 Chord 管理持久状态和任务恢复。
不能画成一条直线 本地 CLI/SDK 主链与实验性远程主链共享概念,但入口、状态所有权和稳定性不同。课程会分别追踪,最后再合并成兼容矩阵。
兼容审计的六个面
静态形状
包名、exports 子路径、导出符号、函数参数、联合类型和 schema。
动态时序
stream event、Agent event、tool hooks、队列 drain point 与订阅结算。
状态语义
谁拥有 transcript、何时写 session、branch leaf 如何移动、断线后何者权威。
失败语义
throw、error event、Result union、abort、retry、validation error 的边界。
持久格式
JSONL header/entry tree、CBOR frame、协议版本和 migration。
扩展接缝
provider、tools、extensions、ResourceLoader、transport、storage 如何被替换。
课程路线
- 把 Pi 看成契约网络 分层、两条主链、一次 prompt 的责任流。
- pi-ai 的公共语言 Model、Message、Context、Tool 与 AssistantMessageEventStream。
- 低层 Agent loop 双重循环、stopReason、tool result 回注和完整事件序列。
- 工具契约与执行策略 schema 校验、hooks、partial updates、并行顺序与 terminate。
- Agent 的状态与并发边界 active run、abort、steer、followUp、listener settlement。
- Provider adapter 架构 工厂、lazy API、认证、模型目录与跨 provider 转换。
- AgentSession 产品编排 factory/services/runtime 三层、资源绑定、retry 与模式共享。
- 会话是树,不是数组 JSONL entry、parentId、branch、fork、restore 和 migration。
- Context 与 compaction 投影、token 预算、cut point、summary entry 和 overflow retry。
- 自扩展系统 ExtensionAPI、事件、命令、工具、UI、resources 与 trust。
- 内置工具的 I/O 设计 操作接口、截断、文件修改串行化、跨平台 shell。
- TUI 的最小渲染内核 Component、layout、terminal buffer、diff rendering、输入与宽度。
- CLI 的多入口装配 interactive、print、JSON、RPC;参数只决定组合,不重写内核。
- 远程会话协议 protocol/client/server、attachment 路由、Chord 服务订阅与传输边界。
- Durable harness 与存储 Harness、Conversation、Entry、Task 与 Storage;辨认尚未稳定的接口。
- 观测、测试与兼容蓝图 telemetry schema、conformance tests、mini_pi exports 清单和 contract test suite。
源码入口
| 问题 | 先读 |
|---|---|
| 模型和消息长什么样? | ai/src/types.ts |
| 一次 run 如何循环? | agent/src/agent-loop.ts |
| 状态和队列归谁? | agent/src/agent.ts |
| SDK 暴露了什么? | coding-agent/src/index.ts |
| 会话如何落盘? | session-manager.ts |
| 远程字节如何解释? | protocol/src/protocol.ts |
这一页,先记到这里。