一句话总结
「动手学 Pi」不是教你「怎么用」AI Agent，而是教你「怎么造」一个 AI Agent。沿 15 个 Git checkpoint，从消息协议到工具调用、从会话树到上下文压缩、从 Runtime 组合到独立评测——每一步都是可运行的代码、可验证的测试、可还原的故障实验。
为什么你需要「动手学 Pi」？
2026 年的 AI 开发者面临一个尴尬的现实：每天用 Claude Code、Codex 写代码，但绝大多数人并不真正理解 Agent 内部是怎么工作的。
- 你知道 Agent 怎么决定「该调工具了」还是「该回答了」吗？
- 你知道 Agent 的上下文窗口快满时，它是怎么「压缩记忆」的？
- 你知道一个完整的 Agent Runtime 需要哪些模块、模块之间怎么通信？
- 你知道怎么给 Agent 写评测，让它不再「看起来对了但其实错了」？
市面上有无数「AI Agent 入门」课程，但几乎都是教你怎么用 LangChain 或者怎么调 API。「动手学 Pi」完全不同——它是教你从零实现一个完整的 AI Coding Agent。
「动手学 Pi」是什么？
「动手学 Pi」是一套面向中文开发者的 AI Agent 实现教程，由 hahhforest 团队开源。核心思路是：
沿 15 个可 checkout、可运行的 Git checkpoint，遵循「教材正文 + 真实 commit + 聚焦测试 + 故障实验」的四部分闭环，从一条离线 Agent 轨迹出发，逐步构建完整的 Pi-style Agent。
你不需要任何 AI Agent 的前置知识——只需要会 TypeScript 就行。
15 个 Checkpoint 速览
教程沿一条完整的 Agent 执行链逐层推进：先建立消息与模型协议 → 再接入工具和循环 → 然后保存状态与历史 → 最后组合 Runtime 并用独立评测验收。
序章：感受一次完整的 Agent 闭环
| CP | 章节 | 学到什么 |
|---|---|---|
| 00 | 一次 README 读取请求怎样走完 Agent 闭环 | 跟随一次 README 请求，把用户消息、两次模型调用、工具调用与结果、最终回答连成完整闭环 |
第一部分 · 模型与协议
| CP | 章节 | 学到什么 |
|---|---|---|
| 01 | TypeScript 生存集 | 联合类型、运行时校验、Promise 与 ESM 测试 |
| 02 | EventStream | 实现事件流，让「先到」与「先等」两种时序都能交付过程项和最终结果 |
| 03 | 消息中间表示 | 把文本、工具调用和配对结果保存为统一消息格式 |
| 04 | ScriptedModel | 实现可重复播放预设回合的模型模拟器 |
| 05 | Provider 适配器 | 把课程消息写成 Provider 请求，再将 SSE 响应还原为统一模型事件 |
第二部分 · 工具与循环
| CP | 章节 | 学到什么 |
|---|---|---|
| 06 | 工具合约 | 让 echo 调用经过 schema、Registry 和 executor，返回配对结果 |
| 07 | Agent Loop | 实现两轮循环：模型提出 read，工具结果写回后再生成最终回答 |
| 08 | 编程工具 | 让 read/write/edit/bash 在同一 workspace 内完成受控的文件与进程操作 |
第三部分 · 状态与历史
| CP | 章节 | 学到什么 |
|---|---|---|
| 09 | 有状态 Agent | 保存跨运行消息，管理订阅、取消、运行中指令与重入 |
| 10 | 会话树 | 把消息追加为带父指针的 JSONL 记录，从指定叶子恢复当前对话 |
| 11 | 上下文压缩 | 在 token 预算内保留后缀，用结构化摘要补回早期事实 |
第四部分 · 扩展与验证
| CP | 章节 | 学到什么 |
|---|---|---|
| 12 | 资源与扩展 | 发现项目规则、Skill 与模板，按需送入上下文 |
| 13 | Runtime 组合 | 把 Agent、Session Store、上下文、资源与扩展接成可提交历史的 Runtime |
| 14 | 独立评测 | 用全新 fixture 运行 Runtime，核对活动路径与文件结果，输出稳定分类和计数 |
每个 checkpoint 都是一次 git checkout cp-NN，然后运行 npm test 验证。
安装指南
前置条件
- Node.js 18+
- Git
- 一个 TypeScript 编辑器（VS Code 推荐）
快速开始
# 克隆教程仓库
git clone https://github.com/hahhforest/pi-textbook.git
cd pi-textbook
# 安装依赖
npm install
# 启动在线教材（本地阅读）
npm run dev
# 从第一个 checkpoint 开始
git checkout cp-00
npm test
在线阅读
如果你不想在本地搭建环境，可以直接访问在线教材，所有章节都有完整的中文文档。
教程的四个独特设计
1. Git 历史就是学习路径
这可能是最巧妙的设计。每个 checkpoint 对应一个 Git commit，你可以：
git checkout cp-07跳到「Agent Loop」章节- 查看
git log cp-06..cp-07看这一步改了什么 - 运行
npm test验证是否通过
代码不是「给你看的演示代码」，而是一条可执行的、带测试的 Git 历史。这使得学习过程异常扎实——你是在一条真实的开发线上步步前进。
2. 故障实验：故意踩坑
每个章节不仅有「怎么做对」，还有「怎么做错」——教程设计了故障实验，让你亲手触发错误并理解为什么：
- 如果 Agent Loop 只调一次模型会怎样？
- 如果上下文压缩删错了消息会怎样？
- 如果工具 schema 校验失败会怎样？
这种「先踩坑再理解」的方式，比任何文档都更深刻。
3. 可复现的评测体系
教程的最后一个 checkpoint（cp-14）建立了一套独立评测：
- 用全新 fixture（不与训练数据重合）运行完整 Runtime
- 核对活动路径（Agent 走了哪些步骤）
- 核对文件结果（Agent 是否产生了正确的文件修改）
- 输出稳定分类和计数
这意味着你不仅学会了「怎么造 Agent」，还学会了「怎么验证 Agent 是否做对了」——这是 AI 工程中最容易被忽视但最关键的能力。
4. 模型无关，聚焦工程
整个教程不使用任何特定模型的 API——所有的模型交互都通过你自己实现的 Provider 适配器完成。这意味着：
- 你可以用任何模型（OpenAI、DeepSeek、Kimi、本地模型）来测试
- 学习的是 Agent 的工程结构，而不是某个 API 的调用方式
- 毕业后你可以给任何模型写 Provider 适配器
适合人群
✅ 适合你，如果你
- 每天用 Claude Code / Codex 但想理解底层原理
- 想做自己的 AI 编程工具或 Agent 框架
- 是 TypeScript 开发者，想进入 AI 工程领域
- 正在面试 AI 工程岗位，需要系统理解 Agent 架构
❌ 不太适合，如果你
- 只想「学会用 AI 工具提高效率」（这是另一个需求）
- 完全没写过 TypeScript（前置门槛）
- 想要「7 天速成 AI 工程师」（这套教程需要扎实投入）
同类资源对比
| 动手学 Pi | Andrej Karpathy 的 minbpe | LangChain 教程 | 吴恩达 AI Agent 课程 | |
|---|---|---|---|---|
| 语言 | 中文 | 英文 | 英文 | 英文 |
| 从零实现 | ✅ 15 步渐进 | ✅ 逐步实现 BPE | ❌ 高层封装 | ❌ 概念为主 |
| 可运行代码 | ✅ | ✅ | ✅ | ❌ |
| 评测体系 | ✅ 内置 | ❌ | △ 部分 | ❌ |
| Git 历史学习 | ✅ | ❌ | ❌ | ❌ |
总结
- 📚 中文 AI Agent 实现教程：15 个 checkpoint 从零构建完整 Agent
- 🧪 可运行 + 可验证：每个 checkpoint 有测试，最后有独立评测
- 🔧 模型无关：学的是工程结构，不是 API 调用
- 🎯 面向实践者：适合想深入理解 Agent 底层的 TypeScript 开发者
- 🐛 故障实验设计：故意踩坑，比只看正确代码更深刻
- 🌟 上线 3 天 157 星：社区正在快速关注这个项目
2026 年不缺「用 Agent」的人，缺的是「造 Agent」的人。「动手学 Pi」可能是目前最好的中文 AI Agent 实现教程——不是教你调包，而是带你走一遍真实的 Agent 工程全流程。
数据来源：GitHub API（hahhforest/pi-textbook），2026-07-24
