pi-textbook

项目概述

《动手学 Pi》是一份面向开发者的中文技术实战教材，系统性讲解如何从零构建一个 Pi 风格的 AI Coding Agent。不同于纸上谈兵的伪代码演示，本教程沿一条真实的 Git 提交历史展开——每个章节对应一个可 checkout 的 checkpoint，配有完整可运行的代码、聚焦测试用例和故障实验。教程目前已在 GitHub 获得 509 颗星，31 个 Fork，广受中文开发者社区认可。

核心技术架构

项目主体为一套基于 Next.js 16 + React 19 + Tailwind CSS 4 构建的交互式 Web 教材网站。底层采用 vinext（Cloudflare Workers 开发框架） 提供 SSR 服务，数据库层使用 Drizzle ORM 对接 Cloudflare D1（SQLite 边缘数据库），文件存储则对接 Cloudflare R2。课程配套代码托管在独立仓库 hahhforest/pi（分支 course/build-your-own-pi），从固定上游 commit 8479bd84 开始，以 course(00) 到 course(14) 标签顺序承载 15 个渐进式 Checkpoint。

Pi-style Agent 的核心架构沿以下链路分层构建：

开发技术栈详解

前端框架

• Next.js 16.2.11（App Router + RSC）：服务端组件渲染，支持流式 HTML 输出
• React 19.2.7：最新 React 特性，支持 Server Actions
• Tailwind CSS 4.2.1 + @tailwindcss/postcss：原子化样式
• lucide-react 1.24.0：图标组件库

构建与工具链

• vite 8.1.5 + @cloudflare/vite-plugin：Vite 环境适配 Cloudflare Workers
• TypeScript 5.9.3：全项目强类型，Node.js >= 22.13.0
• wrangler 4.112.0：Cloudflare Workers 部署工具
• marked 18.0.6：Markdown 内容解析
• drizzle-kit 0.31.10：数据库 schema 迁移管理
• eslint 9.39.4：代码质量检查

课程验证体系

项目内置完整的质量保障机制：

• npm run learning:verify：验证学习合约 + 3 类测试（learning-contract、practice-sandbox、chinese-prose）
• npm run history:verify：校验 Checkpoint Manifest + 课程内容构建 + Git 历史一致性
• npm run test：端到端测试（学习验证 + 工作坊测试 + 构建 + 渲染 HTML 测试）

部署方式与硬件需求

本项目不提供 Docker 容器化，但部署流程极为简洁：

git clone https://github.com/hahhforest/pi-textbook.git
cd pi-textbook
npm install
npm run dev

硬件需求：仅需 CPU（推荐 4GB+ 内存），无需 GPU。依赖 Node.js >= 22.13.0。生产部署推荐使用 Cloudflare Pages 或 Workers。

配套课程代码部署：

git clone --branch course/build-your-own-pi https://github.com/hahhforest/pi.git
cd pi
npm install
npm run checkpoint -w @pi/course -- 05

适用人群与学习路径

目标受众

• LLM 应用开发者（60%）：想深入理解 Agent 系统内部工作原理
• AI 爱好者（40%）：对大模型如何控制工具、记忆对话感兴趣

学习前置要求

• 熟练 JavaScript/TypeScript
• 了解 Node.js 生态（npm、ESM 模块）
• 对 LLM/Agent 概念有基础认知

推荐学习路径

1. 打开在线教材通读序章，理解 Agent 完整闭环
2. Clone 课程仓库，checkout 到指定 Checkpoint，运行聚焦测试
3. 对照教材 + LEARNING.md + 命令输出，交给陪学 Agent 逐步完成练习

项目特色与亮点

1. 真实 Git 历史驱动：每个 Checkpoint 是一条可运行的 Git commit，保证代码与讲解完全同步
2. 四段式闭环结构：教材正文 + 真实 commit + 聚焦测试 + 故障实验，真正做到学练结合
3. 中文沉浸式教程：全中文教材，降低中文开发者理解 LLM/Agent 核心概念的门槛
4. 渐进式架构演进：从最简单的 TypeScript 类型定义开始，逐步引入流式事件、工具调用、状态管理、上下文压缩等核心概念
5. 可验证的学习合约：每个章节都有精确的完成条件定义，学习成果可量化

项目现状与社区

• GitHub：509 Stars，31 Forks，MIT License
• 官方在线站：https://build-your-own-pi-cn.enochzhang.chatgpt.site
• 协作平台：由 LINUX DO 社区提供中文技术交流空间
• 许可证：应用与原创代码采用 MIT License；教材正文与原创媒体采用 CC BY 4.0
• 活跃状态：最近更新 2026-07-23，仓库持续维护中