一句话总结
pi-from-scratch 用 600 行 TypeScript 手撕了一个完整的 AI coding agent——包含 Agent 循环、文件读写、工具调用和命令执行。配合交互式教学网站和 Trace 调试器，让每一个人都能从零理解 AI Agent 的底层原理。
为什么你需要了解 AI Coding Agent 的内部原理？
如果你每天都在用 Claude Code、Codex 或 Cursor，你一定有过这种体验：AI 自动读代码、自动写文件、自动跑命令——看起来像魔法一样。但当你遇到 agent 卡住、幻觉、无限循环时，又完全不知道内部发生了什么。
黑盒体验的本质问题：不了解原理 = 无法排错 = 只能重试。
pi-from-scratch 正是为了解决这个问题而生。它不是让你”用”一个 agent，而是让你亲手造一个 agent。600 行代码，每一行都有解释，读完你就彻底理解了：
- Agent 循环是怎么工作的？
- LLM 怎么决定该调用哪个工具？
- 工具调用的结果怎么回传给模型？
- 文件读写和命令执行的完整流程是什么？
pi-from-scratch 是什么？
pi-from-scratch 是 SaladDay 于 2026 年 8 月 9 日发布的开源项目，上线首日即获 533+ GitHub Stars。作者的一句声明很打动我：
“删除 pi 的工程细节，留下 pi 的核心思想。放轻松，这是一篇文章，不是一本书，你会很容易看懂。”
项目的核心特色：
| 特性 | 说明 |
|---|---|
| 📄 600 行 TypeScript | 极致精简，只保留核心逻辑 |
| 🧠 完整 Agent 循环 | Think → Act → Observe → Repeat |
| 🛠️ 4 大工具能力 | 读文件、写文件、改代码、执行命令 |
| 🔗 OpenAI API 兼容 | 支持任何兼容接口（DeepSeek/Qwen/本地模型） |
| 🐛 Trace 调试器 | 断点逐行跟踪代码执行流 |
| 📖 交互式教学网站 | 阅读推进时代码逐步补全 |
| 🌐 在线体验 | pi-from-scratch.vercel.app |
项目的灵感来源于两个优秀作品：
pi-from-scratch 把 pi 的精华提炼成了 600 行——就像从一整本教材中提炼出了精华笔记。
核心架构：nano-pi 长什么样？
pi-from-scratch 实现的 nano-pi 包含以下核心模块：
nano-pi
├── Agent 循环 ← 大脑：Think → Act → Observe
├── 工具定义层 ← 手和脚：读文件、写文件、执行命令
├── LLM 接口层 ← 语言中枢：OpenAI 兼容 API 调用
├── 上下文管理器 ← 记忆：系统提示 + 对话历史 + 工具回传
└── Trace 跟踪器 ← 自我意识：记录每一步的执行详情
Agent 循环 —— nano-pi 的心跳
这是整个 agent 最核心的逻辑，伪代码大致如下：
while (未完成任务 且 未超过最大步数) {
1. 构建上下文（系统提示 + 工具定义 + 对话历史）
2. 调用 LLM，获取响应
3. 如果 LLM 返回了工具调用：
a. 执行工具（读文件/写文件/运行命令）
b. 将工具执行结果追加到对话历史
4. 如果 LLM 返回了文本回复：
a. 如果没有工具调用需求 → 任务完成，退出循环
b. 否则 → 继续下一轮
}
关键洞察：Agent 循环本质上是 LLM + 工具调用 + 反馈循环的组合。没有魔法，只有工程。
三步跑起来：从 0 到拥有你自己的 nano-pi
前置条件
- Node.js 22+
- 一个 OpenAI 兼容 API（支持 DeepSeek、Qwen、本地 Ollama 等）
第 1 步：克隆并安装
git clone https://github.com/SaladDay/pi-from-scratch.git
cd pi-from-scratch
npm install
第 2 步：配置 API
export NANOPI_API_KEY=your-api-key # 必填
export NANOPI_MODEL=gpt-4o # 可选，默认 gpt-4o
export NANOPI_BASE_URL=https://api.openai.com/v1 # 可选
对于国内开发者，推荐使用 DeepSeek：
export NANOPI_API_KEY=sk-your-deepseek-key
export NANOPI_MODEL=deepseek-chat
export NANOPI_BASE_URL=https://api.deepseek.com
第 3 步：启动
npm run dev
nano-pi 就上线了！现在你可以对它说：“帮我在 src 目录下创建一个 hello.ts 文件，写一个输出 Hello World 的函数。“
Trace 调试器：看清楚 agent 的”内心独白”
nano-pi 最酷的特性是 Trace 跟踪器——它可以让你逐行断点查看代码的执行流程：
- 每一步 agent 做了什么决策？
- LLM 返回了什么原始响应？
- 工具调用的参数和返回值是什么？
- 为什么选择了这个工具而不是那个？
这个特性对于学习和排错都极其宝贵。当你理解了一个 agent 的完整执行流，你就再也不会对它”卡住”感到困惑——你会知道问题出在哪个环节。
作者贴心地提供了预生成的静态 Trace 数据——浏览教学网站不需要真正调用模型，完全免费。
与完整版 pi 的对比
| 维度 | pi-from-scratch (nano-pi) | pi (完整版) |
|---|---|---|
| 代码量 | 600 行 | 数万行 |
| 目标 | 教学、理解原理 | 生产级 coding agent |
| 工具数量 | 4 个（读/写/执行/搜索） | 20+ 个 |
| 子 agent | 无 | 支持并行子 agent |
| 沙箱隔离 | 无 | Docker 沙箱 |
| 多模型路由 | 单一模型 | 多模型智能选择 |
| 适用场景 | 学习 AI Agent 原理 | 日常编程工作 |
完整版 pi 的仓库地址：github.com/earendil-works/pi
为什么这个项目值得你花时间？
1. 打破 AI 黑盒幻觉
大多数开发者把 AI coding agent 当成”神秘盒子”——输入需求，等待结果，不满意就重试。pi-from-scratch 用 600 行代码告诉你：agent 就是 LLM + 工具调用 + 循环，没有魔法。
2. 600 行 vs 数万行——抽象的力量
从 pi 的数万行代码压缩到 nano-pi 的 600 行，这个抽象过程本身就是一堂高级软件工程课。你需要理解：什么必须保留？什么可以舍弃？什么用简化版本替代？
3. 中文友好 + 古法手敲
作者的宣言：“文章保留古法手敲，尽可能没有 AI 味，希望大家读得开心。“这在 AI 生成文本泛滥的 2026 年是一种稀缺品质。
4. 学了就能用
理解 agent 原理后，你可以：
- 为自己的项目构建定制 agent
- 排错更高效（知道问题出在哪个环节）
- 理解 Claude Code / Codex 的行为模式
- 参与开源 agent 项目贡献
同类学习资源推荐
如果你在完成 nano-pi 之后还想深入学习：
- pi-book：完整的 pi 架构解析，一本深入理解 coding agent 的书
- LangChain 官方教程：另一条路——用框架抽象构建 agent
- Anthropic 的 Building Effective Agents：Anthropic 对于 agent 设计的最佳实践指南
总结
pi-from-scratch 是一个难得的”小而美”开源项目——它不是要替代你正在用的 Claude Code 或 Codex，而是让你真正理解这些工具的内部运作。600 行 TypeScript，一个下午的通读时间，换来的是一辈子受益的 AI Agent 底层知识。
如果你是一名中文开发者，对 AI coding agent 的原理感到好奇，但又不想啃数万行的代码仓库——pi-from-scratch 就是为你准备的。
“删除 pi 的工程细节，留下 pi 的核心思想。” —— SaladDay
项目地址：github.com/SaladDay/pi-from-scratch — MIT 协议，⭐533+ Stars
