这是一本面向中文开发者的在线实践教材《动手学 Pi》，目标是通过 15 个可运行 checkpoint，从零实现一个 Pi-style coding agent。仓库本身主要承载 HTML 教材与网站，配套课程代码位于 hahhforest/pi 的 course/build-your-own-pi 分支。课程覆盖 TypeScript 协议设计、流式模型事件、Provider 适配、工具调用、Agent Loop、状态管理、会话树、上下文压缩、扩展机制、Runtime 组合与独立评测等内容，强调“教材正文 + 真实 commit + 聚焦测试 + 故障实验”的闭环学习方式。
适用领域
AI Agent 工程 / LLM 应用开发 / Coding Agent / TypeScript 后端工程 / 模型 Provider 适配 / 工具调用与 Agent Loop / 上下文管理 / 会话状态与历史恢复 / 软件工程教学 / 自动化评测 Eval
配置难度
中高级。阅读教材本身难度中等，但完整跟做需要 TypeScript、Node.js、Git、测试、LLM API、工具调用和 Agent 架构基础。适合有一定工程经验的开发者系统学习，不太适合完全零基础编程学习者。
商业价值
该项目的商业价值主要体现在 AI Agent 工程能力培养和研发加速上。对于个人开发者，它可以帮助系统理解 Coding Agent 的核心实现路径，降低从概念到工程落地的学习成本。对于团队，它适合作为内部培训材料或技术预研参考，帮助成员统一对工具调用、会话状态、上下文压缩和 Eval 的理解。对于正在构建 AI IDE、研发助手、自动化代码工具或企业内部 Agent 平台的组织，课程中的架构拆解和测试驱动方法具有较高参考价值。不过它本身不是直接可商业化的 SaaS 产品，更适合作为教育资源、原型参考和工程培训基础。
01
技术亮点
- 中文原生教材，对国内开发者友好，学习路径清晰
- 15 个 checkpoint 逐步构建完整 Pi-style coding agent，知识组织系统
- 不是伪代码教程，而是基于真实 Git commit、可 checkout、可运行、可测试的课程历史
- 每章包含教材正文、真实 commit、聚焦测试和故障实验，适合动手实践
- 覆盖 Agent 工程关键链路：协议、事件流、Provider、工具、循环、状态、会话树、上下文压缩、扩展和 Eval
- 提供 practice 命令，可生成无答案练习目录，适合自学和教学
- MIT License 代码授权较友好，教材内容使用 CC BY 4.0
- 课程设计强调工程可验证性，包含独立评测章节
02
目标用户
- 希望系统学习 AI Agent 实现原理的中文开发者
- 具备一定 TypeScript 或 JavaScript 基础，想从工程角度理解 Coding Agent 的开发者
- 正在构建 LLM 应用、Agent Runtime 或开发者工具的工程师
- 想学习如何设计工具调用、事件流、会话树和上下文压缩机制的 AI 应用开发者
- 希望通过真实 Git 历史和测试驱动方式学习的学生、独立开发者或技术团队
- 需要给团队内部做 Agent 工程培训的技术负责人
03
配置要求
- 需要 Node.js 与 npm 环境，README 未明确指定 Node.js 版本，建议使用当前 LTS 版本
- 需要 Git，用于克隆仓库、切换课程分支和查看真实 commit 历史
- 本仓库为教材网站，真正的 15 个 checkpoint 可运行代码在 hahhforest/pi 的 course/build-your-own-pi 分支中
- 如果只阅读教材，可直接访问在线站点，无需本地配置
- 如果运行课程代码，需要在 pi 仓库内使用 npm workspace 命令，例如 -w @pi/course
- 涉及 Provider API 的章节可能需要理解 SSE、模型 API 请求与响应格式；README 未说明必须配置真实模型 API Key，早期章节可通过 ScriptedModel 和测试运行
- 需要一定 TypeScript、ESM、Promise、测试框架、CLI 操作基础
04
适用场景
- 作为 AI Agent 工程入门到进阶教材，按 checkpoint 分阶段学习
- 本地运行教材网站，用于离线阅读或团队培训
- 结合课程代码仓库，逐章 checkout、运行测试、完成练习
- 学习如何把模型流式输出、工具调用和 Agent Loop 组合成完整 Coding Agent
- 参考其项目结构设计自己的 Agent 教程、课程或内部培训材料
- 研究会话树、Context Compaction、Runtime 组合和 Eval 在 Agent 系统中的实现方式
- 让陪学 Agent 辅助完成每章 practice 练习
05
部署与配置
- 克隆教材仓库：git clone https://github.com/hahhforest/pi-textbook.git
- 进入目录：cd pi-textbook
- 安装依赖：npm install
- 启动本地开发服务器：npm run dev
- 也可以直接访问在线教材：https://build-your-own-pi-cn.enochzhang.chatgpt.site
- 如需运行课程 checkpoint，克隆课程代码仓库：git clone --branch course/build-your-own-pi https://github.com/hahhforest/pi.git
- 进入课程代码仓库：cd pi
- 安装课程代码依赖：npm install
- 运行某章 checkpoint，例如第 05 章：npm run checkpoint -w @pi/course -- 05
- 创建无答案练习目录，例如第 05 章：npm run practice -w @pi/course -- 05 ../pi-practice-05
06
风险与注意事项
- 本仓库主要是教材网站，不是完整 Agent 运行时代码；学习者需要同时使用另一个 pi 课程分支
- 课程依赖 Git 历史、checkpoint 和 npm workspace，新手可能在环境和分支操作上遇到门槛
- README 未明确列出 Node.js 版本、包管理器版本或完整环境矩阵，企业环境落地前需要自行验证
- 项目为社区原创非官方课程，不代表 Pi 或 Earendil Works，不能视为官方实现或官方培训材料
- 如果上游 pi 仓库、分支或在线站点发生变化，教材和课程代码之间可能存在同步风险
- Agent 工程涉及模型 API、工具执行、bash、文件写入等概念，迁移到生产环境时必须额外考虑安全沙箱、权限控制和审计
- 课程关注学习和实现原理，不应直接当作生产级 Coding Agent 产品使用
2026-07-28
第10名
新收录 · github_search
2026-07-27
第18名
新收录 · github_search
