Pi-Agent 深度教程
Pi-Agent 深度教程
10 章拆解 pi-agent SDK 的源码设计与实现
本库收录说明（2026-07-24）
本目录收录自 buchidonggua/dg-ai-notes 的 TypeScript 版 1-10 章及全部配图（assets/），文档许可 CC-BY-SA-4.0。下方表格中的原仓库相对链接在本库内无效，请直接打开同目录下的同名章节文件。
另：第 11-13 章为本库补全章节（AI 辅助撰写，基于原作者章节设计文档 + Pi v0.81.1 官方源码/文档，非原教程内容），见表格下方"补全章节"一节。
📚 三种阅读方式
🧪 补充材料：notebooks/agent-loop.ipynb 是第 3 章 Agent Loop 的可执行实验场，可以单步运行、改参数、观察 loop 状态。
本教程基于 Pi v0.80.2 编写。源码链接指向 earendil-works/pi main 分支，可能与 v0.80.2 有微小差异。
🗺️ 章节结构
text
ch01 开篇总览 → ch02 三层架构 → ch03 Agent Loop → ch04 模型调用 → ch05 工具系统
↓
ch06 消息系统 → ch07 事件驱动 → ch08 上下文工程 → ch09 上下文压缩 → ch10 会话管理
| 章节 | 主题 | TS 版 | Python 版 |
|---|
| ch01 | 开篇 - Pi-Agent 框架总览 | 📖 | 🐍 |
| ch02 | 三层架构 - 项目骨骼 | 📖 | 🐍 |
| ch03 | Agent Loop - 模型转动起来的引擎 | 📖 | 🐍 |
| ch04 | 模型调用 - 一行代码驾驭多模型 | 📖 | 🐍 |
| ch05 | 工具系统 - Agent 的手脚如何被管住 | 📖 | 🐍 |
| ch06 | 消息系统 - Agent 的记忆组织与传递 | 📖 | 🐍 |
| ch07 |
补全章节（本库独有，基于 Pi v0.81.1）
| 章节 | 主题 | 链接 |
|---|
| ch11 | 扩展系统 - 不改源码给 Agent 加能力 | 📖 |
| ch12 | 测试模式 - 怎么测一个不确定的系统 | 📖 |
| ch13 | 设计精华总结 - 把 Pi 的设计智慧带走 | 📖 |
三章依据：原作者留存的第 11 章设计文档（_chapter-design/，仓库内附）、Pi v0.81.1 官方源码（extensions / 337 个测试文件）与官方文档（README「Philosophy」、docs/extensions.md、security.md 等）。撰写时区分了官方原话与教程提炼，行文风格对齐前 10 章。
🚀 本地运行 web 电子书
bash
cd web
npm install
npm run dev # http://localhost:4321
详细说明见 web/README.md。
📥 PDF 下载
PDF 版本不进 git 仓库（避免仓库膨胀），通过 GitHub Releases 分发：
- 进入 Releases 页面
- 下载对应版本：
- pi-agent-book-ts.pdf — TypeScript 版（约 14MB）
- pi-agent-book-python.pdf — Python 版（约 16MB）
📜 License
苏公网安备32011402012723号