夜雨聆风故事是这样的，我前两天刷 GitHub Trending，看到一个项目名字特别直白，pi-from-scratch，从零写一个 pi。
我第一反应是，又一个标题党。结果点进去一看，好家伙，真不是。作者用 600 行 TypeScript 写了一个能读文件、改代码、执行命令的迷你 AI 编程 agent，然后把它怎么一步步做出来的全过程，写成了一篇带交互的教学文章。项目上线才 4 天，已经攒了 835 个星，仓库在 [GitHub](https://github.com/SaladDay/pi-from-scratch) 上，MIT 协议，随便拿去玩。
你敢信，现在还有人愿意把最核心的东西掰开揉碎了教给你。
先说 pi 是什么。pi 是 [earendil-works](https://github.com/earendil-works/pi) 出的一个开源 AI agent 工具包，在 GitHub 上有 8.9 万个星，它包含统一的 LLM 接口、agent 运行循环、终端界面，还有一个能实际干活的 coding agent CLI。你可以把它理解成一个开源版的 Claude Code 或者 Codex，跑在终端里，你说需求，它自己读代码、改文件、跑命令。
很多人在用 pi，但没多少人真的搞懂它内部是怎么转起来的。模型请求怎么发，工具怎么调用，上下文怎么管理，状态怎么保存，这些听起来全是黑话。反正我一开始看 pi 的源码是懵的，几千个文件，根本不知道从哪下嘴。
pi-from-scratch 干的事，就是把这个黑盒拆了。
作者 SaladDay 沿着 pi 的数据流，把工程细节全部删掉，只留下核心思想，然后重新实现了一遍。项目描述里那句话我特别喜欢，删除 pi 的工程细节，留下 pi 的核心思想。放轻松，这是一篇文章，不是一本书，你会很容易看懂。
他说到做到了。
这个项目最妙的设计在它的网站上，网址是 pi-from-scratch.vercel.app。它不是一篇干巴巴的教程，而是把文章和源码放在一起，你往下读文章，右侧的编辑器就会逐步补全代码。等你把整篇文章读完，nano-pi 的全部代码也就完整呈现在编辑器里了。
怎么说呢，就像有人一边给你讲课，一边当着你的面把零件一个个装起来，讲完最后一个字，机器正好组装完毕，通电就能跑。我当时看到这个设计，真的就是一声叹息，这种交互式教学，比任何图文教程都直观。你想想看，传统的编程书讲 agent，你只能靠脑补，这个项目直接把代码在你眼前长出来。
它还配了一个 Trace 跟踪功能，可以打断点，逐行过代码，看每一步执行流。我自己是那种看代码容易走神的人，有了这个，相当于有人指着屏幕告诉你，看这里，这一步在干什么。这种教学方式，说真的，比我见过的绝大多数编程书都用心。
跑起来也简单。项目需要 Node.js 22 或更高版本，以及一个 OpenAI 兼容的 API。步骤就三行命令，先 npm install 装依赖，再 export NANOPI_API_KEY 设置你的密钥，最后 npm run dev 启动。可选的环境变量还有 NANOPI_MODEL 指定模型名，NANOPI_BASE_URL 指定接口地址，默认走 OpenAI 官方接口。
整个安装配置过程，我实测下来大概就是几分钟的事，不需要额外下载模型，也不需要折腾显卡，有个 API 密钥就能跑。对新手来说，这种上手门槛简直是友好得过分，你甚至可以在本地把 agent 循环打断点，一步步看着它怎么思考、怎么调用工具，体验一把当 AI 工程师的感觉。
线上那个教学网站本身不会发起模型请求，Trace 里看到的是预先生成的静态数据，所以你可以放心地反复研究，不用担心烧 token。
这事的价值在哪呢，我觉得得从两个层面看。
第一个层面，是对普通开发者的教学价值。现在 AI 编程 agent 满天飞，但大多数人只是把 Claude Code 当高级补全工具用，模型替你把活干了，你根本不知道它怎么干的。pi-from-scratch 用 600 行代码告诉你，一个 agent 的核心循环其实就那几件事，拿到任务，调用模型，模型返回要不要用工具，要用就执行工具，然后把结果喂回去，循环往复，直到任务完成。就这么简单。
第二个层面，是它背后那个更大的项目 pi。你跟着 nano-pi 走一遍，再回去看 pi 的源码，就不会晕了。因为你知道骨架长什么样了，剩下的只是血肉填充。用作者的话说，pi-book 也给了他不少启发，想深入的话还有配套的书可以读。
顺便说一句，作者本人也是个有意思的人。他 GitHub 主页的 bio 就俩字，writing bugs，写 bug 的。他最出名的项目是一个叫 cc-switch-cli 的工具，4.6 千星，用来在 Claude Code、Codex 和 Gemini CLI 之间一键切换的终端助手。你看，他是个天天跟 AI 编程 agent 打交道的人，然后回头自己写了个 600 行的教学版，教别人理解这玩意。
这种心态我是真佩服。大多数人会用工具就满足了，他非得把工具拆了看里面的齿轮怎么咬合。
再聊聊它的热度。这个项目 8 月 9 日创建，到今天 8 月 13 日也就 4 天，星数从 0 涨到 835，平均每天涨 200 多个星，还有 56 个 fork。这种增速放在 GitHub Trending 上都是很靠前的，说明戳中了很多人的需求。对比一下同类项目，像之前爆火的那些 from-scratch 教学仓库，有的教你怎么写编译器，有的教你怎么写数据库，但专门把 AI agent 拆开教学的，这个算是少数派。你想想看，agent 是这两年最热的概念，但真正敢把它拆到 600 行讲清楚的，还真不多。
它的定位也很聪明，不是让你读 pi 的源码，而是先带你写一个简化版，建立心智模型，再回去看真家伙。这跟学游泳先学换气、学开车先学打方向盘是一个道理，先把核心动作练熟，再上复杂场景。这个项目上线 4 天星数就冲到了 835，增长曲线是这样的。
我看完这个项目，最大的感受是，AI 编程 agent 的门槛正在从会用，变成理解。以前你只要会敲 prompt，现在越来越多的人在拆解这些 agent 是怎么思考的，怎么规划任务的，怎么决定调用哪个工具。这个东西一旦被理解，就不是黑魔法了。我跟你说，这感觉就像小时候拆闹钟，拆完了再装回去，从此闹钟在你眼里就是齿轮和弹簧，不是玄学。
而且你发现没有，这种项目天生适合传播。它不像那些刷 star 的仓库，挂着个唬人的名字，里面啥也没有。它是一篇好文章加一堆能跑的代码，你读完了，真的懂了，然后你会忍不住分享给朋友，说你看，600 行就能写一个 AI 编程助手。
我反正是收藏了，等哪天有空，打算把 nano-pi 自己跑一遍，再对照着 Trace 走两遍。这种从 0 到 1 的拆解，看一次顶自己瞎琢磨一个月。
最后我想说，2026 年这个节点，AI 圈最不缺的是新模型和新工具，最缺的恰恰是这种愿意慢下来、把一件小事讲透的人。pi-from-scratch 没什么惊天动地的技术，但它让我重新想起来，学编程最开始的那种快乐，就是把一个东西彻底搞明白的快乐。也许哪天我闲下来，也学他这样，把手头某个黑盒拆一遍，写出来给需要的人看。。。600 行代码，一场手术，一次解谜。这大概就是开源社区最性感的样子了。
