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 如何被替换。

课程路线

  1. 把 Pi 看成契约网络 分层、两条主链、一次 prompt 的责任流。
  2. pi-ai 的公共语言 Model、Message、Context、Tool 与 AssistantMessageEventStream。
  3. 低层 Agent loop 双重循环、stopReason、tool result 回注和完整事件序列。
  4. 工具契约与执行策略 schema 校验、hooks、partial updates、并行顺序与 terminate。
  5. Agent 的状态与并发边界 active run、abort、steer、followUp、listener settlement。
  6. Provider adapter 架构 工厂、lazy API、认证、模型目录与跨 provider 转换。
  7. AgentSession 产品编排 factory/services/runtime 三层、资源绑定、retry 与模式共享。
  8. 会话是树,不是数组 JSONL entry、parentId、branch、fork、restore 和 migration。
  9. Context 与 compaction 投影、token 预算、cut point、summary entry 和 overflow retry。
  10. 自扩展系统 ExtensionAPI、事件、命令、工具、UI、resources 与 trust。
  11. 内置工具的 I/O 设计 操作接口、截断、文件修改串行化、跨平台 shell。
  12. TUI 的最小渲染内核 Component、layout、terminal buffer、diff rendering、输入与宽度。
  13. CLI 的多入口装配 interactive、print、JSON、RPC;参数只决定组合,不重写内核。
  14. 远程会话协议 protocol/client/server、attachment 路由、Chord 服务订阅与传输边界。
  15. Durable harness 与存储 Harness、Conversation、Entry、Task 与 Storage;辨认尚未稳定的接口。
  16. 观测、测试与兼容蓝图 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

开始第一课 · 词汇表

这一页,先记到这里。