600 行 TypeScript 手撕一个 Coding Agent？pi-from-scratch 把「造 Agent」拆给你看

这个项目能干嘛

pi-from-scratch 是一份「从零手写一个 Coding Agent」的交互式教程兼源码库。它直接用大约 600 行 TypeScript 写出一个能读文件、改代码、执行命令的迷你版编程 Agent（内部叫 nano-pi）。野心不是做生产工具，而是把知名的 pi 项目的数据流拆开，删掉繁复的工程细节，只留下核心思想：Agent 怎么接收任务、怎么调工具、怎么读文件改代码、怎么循环直到完成。最有意思的是，它把文章和源码放在一起——你往下读，右边编辑器会同步把代码一段段补全，读完时 nano-pi 的完整实现就躺在编辑器里。

为什么最近火了

它 8 月 9 日才创建，几天就拿 500 多 Star，踩中「人人都想搞懂 Agent 到底怎么造」这股风。现在 Agent 框架一个比一个重，新手一上来被 LangGraph、Tool Calling、Memory 劝退。pi-from-scratch 反其道而行：它说「放轻松，这是一篇文章，不是一本书」，用最朴素的方式把骨架讲透。这种「去魔法化」叙事在 AI 圈特别吃香——大家都厌倦黑盒，想亲手摸一遍轮子怎么转。作者还强调「古法手敲，尽可能没有 AI 味」，反而勾起好奇心。

技术亮点

它沿着 pi 的数据流组织：需要什么组件就现场造什么，所有模块都符合直觉、不堆抽象。nano-pi 麻雀虽小五脏俱全——能读文件、改代码、执行 shell 命令，具备 Coding Agent 的核心闭环。项目还专门做了 Trace 跟踪功能，可打断点、逐行单步过代码，把执行流（哪一步调了什么工具、返回什么）清清楚楚摊开，对手写 Agent 的学习者简直是显微镜级可视化。运行也极简：Node.js 22 以上配一个 OpenAI 兼容 Key（NANOPI_API_KEY），npm install 后 npm run dev 就能跑起来；换模型或接口改 NANOPI_MODEL 和 NANOPI_BASE_URL 两个环境变量即可，默认走标准 OpenAI 接口。

适合什么人

它非常适合前端开发者、TypeScript 爱好者，以及所有「用过一堆框架却始终没搞懂底层」的 AI 学习者。如果你懂点 TS、想真正理解 tool calling 和 agent loop 怎么落地，而不是只会调 SDK，这就是最好的现场教学。它不适合想直接拿去干活的人——明确是教学用途，线上 demo 的 trace 是预生成静态数据，不会真发请求。但作为「从使用者变成造轮子的人」的第一步，门槛低得感人。

快速试用

git clone https://github.com/SaladDay/pi-from-scratch
cd pi-from-scratch
npm install
export NANOPI_API_KEY=your-api-key
npm run dev

浏览器打开本地地址就能边读文章边看代码补全；想单独跑教学网站就进 web 目录再 npm install 然后 npm run dev。整个项目没有重型依赖，clone 下来几分钟就能跑起来。

与竞品对比

和「开箱即用」的 Agent 框架比，pi-from-scratch 定位完全不同。LangChain、LangGraph 给你一套庞大抽象和组件，省事但黑盒、学习曲线陡；CrewAI、AutoGen 强调多智能体协作，工程细节更多。pi-from-scratch 反过来：不追求功能全，只追求让你「看懂」。它更像一本会动的教科书，而非瑞士军刀。要生产力去用现成框架；要「我终于明白 Agent 怎么跑起来的」，这个 600 行迷你实现比任何文档都管用。