一份面向 AI Agent 开发初学者的 Pi Agent 架构学习文档，基于官方源码逐层拆解。
在线阅读 → https://albert-pzy.github.io/learn-pi-agent/
Pi 是 Mario Zechner（libGDX 作者）开源的 TypeScript AI Agent 框架，核心理念是 LLM + Tools + A Loop——用最少的代码实现最大的灵活性，agent-core 仅约 1500 行。
本文档从源码出发，用 15 个章节讲清 Pi 的完整架构，目标是两三天内建立完整心智模型：不只讲"怎么用"，更讲"为什么这么设计"。
| 章节 | 主题 | 核心内容 |
|---|---|---|
| 00 | 全景导读 | 设计哲学、Monorepo 结构、学习路线 |
| 01 | 三层架构 | pi-ai / agent-core / coding-agent 的垂直分离 |
| 02 | LLM 抽象层 | Provider 抽象、stream()、懒加载、跨厂商兼容 |
| 03 | Agent Loop | 双循环引擎、Steering、工具五步生命周期 |
| 04 | 工具系统 | Operations 接口、环境解耦、Result 类型 |
| 05 | 消息系统 | AgentMessage vs Message、最晚转换策略 |
| 06 | 事件流 | EventStream、事件类型全表、背压处理 |
| 07 | 上下文工程 | Compaction 压缩、分支摘要、动态 System Prompt |
| 08 | 会话管理 | Session Tree、JSONL 存储、Fork 分叉 |
| 09 | 扩展系统 | Skills / Extensions / Prompt Templates |
| 10 | Provider 与认证 | 认证优先级、CredentialStore、OAuth 刷新、跨厂商 handoff |
| 11 | Session 树与上下文构建 | Entry vs Message、buildContextEntries / buildSessionContext、分支操作 |
| 12 | Compaction 内部机制 | 切点规则、Split Turn、检查点、结构化摘要 |
| 13 | SDK 与嵌入集成 | createAgentSession、AgentSessionRuntime、三种 Run Mode |
| 14 | 术语表 | 60+ 术语按逻辑分组速查 |
每章包含源码示例、PlantUML 架构图、检查清单，章节之间环环相扣。
npx serve -l 3456 -C浏览器打开 http://localhost:3456/
- 暗 / 亮色主题切换，warm tone 配色，适合长时间阅读
- 侧边栏导航 + 底部上下章跳转 + 正文内链跳转
- 代码块语法高亮、PlantUML 图在线渲染
- 阅读进度指示、回到顶部
- 快捷键
Ctrl + ←/→切换章节
.
├── index.html # 文档阅读器（单文件，无构建步骤）
├── docs/ # 教学文档 Markdown 源文件
│ ├── 00-overview.md
│ └── ...
└── .github/workflows/
└── deploy.yml # 推送到 main 自动部署 Pages
pi-src/（Pi 官方源码克隆）不入库，需要对照源码时自行 clone：git clone https://github.com/earendil-works/pi.git pi-src
- earendil-works/pi — Pi 官方仓库
- pi.dev — 项目官网与文档
文档内容 CC BY 4.0，代码 MIT。