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 官方源码/文档，非原教程内容），见表格下方"补全章节"一节。
| 方式 | 入口 | 适合场景 |
|---|---|---|
| 🌐 Web 在线版（推荐） | https://dg-ai-notes.pages.dev | PC 端沉浸式阅读，三栏布局 + 配图联动 |
| 📥 Markdown 下载版 | docs/typescript/ · docs/python/ | 下载到本地，配合 AI 边读边问、对照源码 |
| 📕 PDF 版 | GitHub Releases | 离线阅读、打印、长期存档 |
🧪 补充材料：notebooks/agent-loop.ipynb 是第 3 章 Agent Loop 的可执行实验场，可以单步运行、改参数、观察 loop 状态。
本教程基于 Pi v0.80.2 编写。源码链接指向 earendil-works/pi main 分支，可能与 v0.80.2 有微小差异。
| 章节 | 主题 | TS 版 | Python 版 |
|---|---|---|---|
| ch01 | 开篇 - Pi-Agent 框架总览 | 📖 | 🐍 |
| ch02 | 三层架构 - 项目骨骼 | 📖 | 🐍 |
| ch03 | Agent Loop - 模型转动起来的引擎 | 📖 | 🐍 |
| ch04 | 模型调用 - 一行代码驾驭多模型 | 📖 | 🐍 |
| ch05 | 工具系统 - Agent 的手脚如何被管住 | 📖 | 🐍 |
| ch06 | 消息系统 - Agent 的记忆组织与传递 | 📖 | 🐍 |
| ch07 | 事件驱动 - Agent 的神经系统 | 📖 | 🐍 |
| ch08 | 上下文工程 - 让有限窗口装下无限对话 | 📖 | 🐍 |
| ch09 | 上下文压缩 - 当对话太长怎么办 | 📖 | 🐍 |
| ch10 | 会话管理 - 对话的存储恢复与分叉 | 📖 | 🐍 |
| 章节 | 主题 | 链接 |
|---|---|---|
| ch11 | 扩展系统 - 不改源码给 Agent 加能力 | 📖 |
| ch12 | 测试模式 - 怎么测一个不确定的系统 | 📖 |
| ch13 | 设计精华总结 - 把 Pi 的设计智慧带走 | 📖 |
三章依据：原作者留存的第 11 章设计文档（_chapter-design/，仓库内附）、Pi v0.81.1 官方源码（extensions / 337 个测试文件）与官方文档（README「Philosophy」、docs/extensions.md、security.md 等）。撰写时区分了官方原话与教程提炼，行文风格对齐前 10 章。
详细说明见 web/README.md。
PDF 版本不进 git 仓库（避免仓库膨胀），通过 GitHub Releases 分发：