信息卡

一句话定位

一篇中文教学项目：带你从零手写"nano-pi"——一个能读文件、改代码、执行命令的 600 行 TypeScript coding agent，借鉴 earendil-works/pi 的数据流设计但剔除工程细节、保留核心思想。

走红原因分析

当 everyone 都在用 coding agent 时，"亲手拆解 agent 内部原理"成为新一轮学习刚需。这个项目的聪明之处在于形式：它自定位为"一篇易读的文章而非一本厚书"，配套网站把文章与源码绑在一起——随着阅读进度推进，右侧编辑器逐步补全代码，读完全文 nano-pi 全部代码即在眼前。中文原生内容 + Trace 断点调试 + 作者强调人工撰写避免 AI 味，这三点在教程赛道里都算稀缺体验。

核心功能拆解

• 文章即源码：阅读进度驱动右侧编辑器渐进式补全，最终呈现完整可运行的 nano-pi。
• Trace 调试：支持设断点并逐行执行代码，直观理解 agent 循环中每一步的数据流转。
• 忠实还原 pi 的设计思想：按需构建组件、保持数据流直觉清晰，砍掉工程性枝蔓。
• 完整 agent 能力闭环：读文件、改代码、执行命令一个不少，麻雀虽小五脏俱全。
• 本地可跑：clone 即得教学网站与 agent 源码两个独立 npm 工程。

架构与技术栈浅析

双工程结构：agent 本体（nano-pi）是纯 TypeScript 实现，通过 OpenAI 兼容 API 与模型交互；`web/` 目录是 Next/Vite 类教学站点。README 特别说明在线网站的 trace 是预先生成的静态数据，浏览网页本身不会触发任何模型请求——这也是它把成本控制做在产品形态里的细节。

安装与环境要求

需要 Node.js 22+ 和一个 OpenAI 兼容 API。

npm install
export NANOPI_API_KEY=your-api-key
npm run dev

可选环境变量：

• `NANOPI_MODEL` —— 指定模型名称；
• `NANOPI_BASE_URL` —— OpenAI 兼容接口地址，默认 `https://api.openai.com/v1`（国内读者可换任意兼容网关）。

运行教学网站：

cd web
npm install
npm run dev

快速上手示例

最省事的学习路径是直接打开 https://pi-from-scratch.vercel.app 边读边看代码补全；想动手跑通 agent 则按上面三条命令设置 key 后 `npm run dev`，即可在终端里对它下达诸如读文件/修改代码的任务指令。想深挖原版工程思想的读者，README 推荐进阶读物 pi-book。

进阶使用要点

• 想接第三方兼容端点时只需改 `NANOPI_BASE_URL`，配合中转服务可低成本试多种模型。
• 断点与单步建议对照文章章节使用：先在 trace 里看清一轮 tool call 的完整生命周期，再回读对应段落。
• 若想改造出私有变体（加新工具），顺着"按需构建组件"的脉络扩展即可，600 行的体量正适合魔改实验。
• 文末赞助商列有 OpenModel（50+ 主流模型测试）与 Cubence（OpenAI/Anthropic 双协议中转），可作为无海外卡用户的替代入口。

典型应用场景

• 系统入门 coding agent 内部机制的第一课；
• 团队内训前必读的原理铺垫材料；
• 基于nano-pi 快速魔改出自己的极简 agent 实验；
• 对比原版 pi 工程，体会教学裁剪与工业实现之间的取舍。

同类生态位对比

同类"从零写 agent"内容很多（如手写 GPT 系列、minibook 类项目），本项目的差异化在于锚定了 pi 这一真实生产级工程作为蓝本、且用"文章+同步编辑器+trace 断点"三件套把抽象讲解变成可视过程；相比 MiniMind 这类训练向课程，它是推理时 harness 机制的教学向短篇。

资源导航

• 在线阅读：https://pi-from-scratch.vercel.app
• 原版参考：https://github.com/earendil-works/pi
• 进阶：pi-book