pi-from-scratch是什么?600行TypeScript零依赖手撕Coding Agent,AI编程Agent完整入门指南
pi-from-scratch是什么?600行TypeScript零依赖手撕Coding Agent,AI编程Agent完整入门指南
pi-from-scratch 是一个从零开始的 AI 编程 Agent(Coding Agent)教学项目:用约 600 行 TypeScript、运行时零依赖,手写一个能读文件、改代码、执行命令的 Agent(项目里叫 nano-pi),并配套一个"文章 + 代码逐步浮现"的交互式教学网站。本文将带你从模块结构、Agent Loop 到工具调用与事件流设计,完整看懂如何从零构建 pi-agent,并在 3 分钟内在本地跑起来。
📌 一句话概括项目理念:删除 pi 的工程细节,留下 pi 的核心思想——沿着数据流走,需要什么就写什么。
为什么新手适合"手撕"一个 Coding Agent
普通的 LLM 聊天程序是"你问一句、它答一句"。而 Agent 多了一个关键能力:LLM 可以调工具。
- 模型读到你的问题,判断需要先看看某个文件,发出一个
tool_call - 程序帮它执行工具,把结果喂回 Context(对话上下文)
- 模型接着想,继续调工具或直接回复,直到任务完成
这个"思考 → 行动 → 反馈"的循环,就是大名鼎鼎的 Agent Loop。生产级项目 pi 有上万行代码,而 nano-pi 把它的核心思想压缩到了约 600 行——正如费曼所说:"What I cannot create, I do not understand."(不能创造,即不理解。)
快速上手:3 分钟跑通 nano-pi Coding Agent
运行前只需要两个条件:Node.js 22+ 和一个 OpenAI 兼容 API。
git clone https://gitcode.com/gh_mirrors/pi/pi-from-scratch
cd pi-from-scratch
npm install
export NANOPI_API_KEY=your-api-key
npm run dev
常用环境变量如下(读取逻辑见 src/cli.ts):
| 环境变量 | 是否必填 | 作用 |
|---|---|---|
NANOPI_API_KEY |
✅ 必填 | OpenAI 兼容 API 密钥 |
NANOPI_MODEL |
可选 | 模型名,默认 glm-5.2 |
NANOPI_BASE_URL |
可选 | 接口地址,默认 https://api.openai.com/v1 |
每轮对话结束后,新增消息会自动 append 到 ~/.nanopi/session.jsonl,下次启动自动恢复历史会话(src/cli.ts#L97)。
五文件项目结构:Coding Agent 的最小蓝图
整个 nano-pi 的 src/ 目录只有 5 个 TypeScript 文件,各自职责清晰:
| 文件 | 行数 | 职责 |
|---|---|---|
| src/llm.ts | 268 | LLM 翻译层:发 HTTP 请求、解析 SSE 流,输出统一的 StreamEvent |
| src/agent.ts | 174 | Agent Loop:整个项目的灵魂,一个 while 循环 |
| src/tools.ts | 125 | 四个内置工具:读、写、改、执行命令 |
| src/tui.ts | 88 | 终端界面:读输入、流式打印、拦截 Ctrl+C |
| src/cli.ts | 112 | 胶水层:把上面四者粘起来,管理会话持久化 |
这张依赖图值得细看:llm 不知道 agent 的存在,agent 不知道 tui 长什么样,tools 不知道自己被谁调用——单向依赖让每个模块都能独立替换、独立测试。src/cli.ts 是唯一"认识所有人"的入口,这也是它被称为胶水层的原因。
Agent Loop 工作原理:一个 while 循环就是 Agent 的灵魂
Agent 与普通聊天程序的差别全部浓缩在这个循环里:
用伪代码表示,核心逻辑不到 10 行:
while true:
reply = stream(model, context, tools) # 流式调用 LLM
若 reply 没有 tool_call → break # 模型说"我做完了"
对每个 tool_call → execute 执行工具
把 reply 和工具结果塞回 context # 反馈给模型,进入下一轮
真正的实现是 src/agent.ts#L80 里的 runAgent(),一个 async generator:每产生一个事件就 yield 出去,外层可以逐条消费。一轮循环的完整数据流长这样:
注意图中实线与虚线的分工:实线是更新 Context 的主循环(决定模型下一轮看到什么),虚线是发给 UI 的 AgentEvent(只负责展示,不影响输入)。数据闭环发生在 Context、stream、agent、tool 四个角色之间,UI 挂在循环之外。
四大工具:让 Agent 真正"动手干活"的最小集
src/tools.ts 里的 builtinTools() 返回四个工具,这也是 pi 的 agent-core 层使用的同一组最小集:
| 工具 | 作用 | 值得注意的细节 |
|---|---|---|
read_file |
读取文件内容 | 超过 200 行时只保留尾部(错误信息通常在末尾),全文存入临时文件并告知路径 |
write_file |
写入/覆盖文件 | 自动 mkdir -p 补齐父目录 |
edit |
替换文件中的一小段 | 不用行号而用 old_string/new_string,要求唯一匹配才执行,避免行号漂移 |
run_bash |
执行 shell 命令 | 命令失败不抛异常,而是把 exit code + stderr 拼成字符串返回——对 Agent 来说,错误也是可读的上下文 |
每个工具都是一个纯函数:async (args) => string,不碰 agent 状态、不知道 Context 的存在。加一个新工具,不需要改 agent 的任何代码。
前后端分离设计:AgentEvent 是 AI Agent 的"API 协议"
nano-pi 里存在两套事件,分层清晰:
StreamEvent(LLM 层):text_delta/tool_call/done/error,贴近 HTTP 流的原始形态AgentEvent(agent 层):assistant_text/tool_call/tool_result/turn_end,语义更高(定义见 src/agent.ts#L21)
UI 只需要认识 AgentEvent,完全不用关心 LLM 底层响应长什么样。这正是 Web 开发"前后端分离"的思路:agent 是后端,UI 是前端,AgentEvent 是它们之间的协议。
想把终端换成 Web 页面?不动 agent 的任何代码,写一个 HTTP server 接收同一条事件流、用 SSE 推给浏览器即可——教学文档里给了一段二十来行的示例(见 docs/ch02-loop.md 的"换个前端"一节)。
完整回合走查:从你敲下回车到会话落盘
把一次真实任务"把 hello.txt 改成大写"拆成时序,各角色如何接力一目了然:
用户输入从 tui 出发,cli 把它塞进 Context 交给 agent;模型回复(可能带 tool_call)经 agent 转发给 tui 流式显示;有工具就执行、把结果放回 Context 再问;没有工具就等用户下一轮输入;回合结束 cli 把新增消息持久化到 ~/.nanopi/session.jsonl。
边界情况处理:生产级 Coding Agent 的三个真实坑
教学项目最容易省略、但恰恰最有价值的部分,nano-pi 一个都没省:
max_tokens截断——模型输出撞上限时,tool_call的参数 JSON 可能只剩半截。nano-pi 的处理很保守:不执行残缺参数,而是回一条错误消息让模型重发(src/agent.ts)- 用户中断(abort)——Ctrl+C 触发
AbortSignal,一路传到fetch和子进程。被跳过的tool_call会补上error: aborted结果,保证tool_call与tool_result严格配对,否则恢复会话时 API 会直接报错 - 请求失败(error)——先保存已生成的文本再结束本轮,绝不原地重试,否则会陷入无限报错循环
还有一招"context 续命":compactContext() 在消息超过 50 条时,让 LLM 把旧消息总结成一条摘要、只保留最近 20 条(src/agent.ts#L37-L70)。pi 在这个问题上花了近千行做 token 精确估算,nano-pi 用消息条数一刀切——粗糙,但概念完整。
交互式教学网站:读完文章,源码就写完了
pi-from-scratch 最有意思的地方是它的 web/ 目录下的 Next.js 教学站:
- checkpoint 机制:文章推进到哪一节,右侧编辑器就逐步补全对应代码;读完文章,nano-pi 的完整源码全部浮现(站点数据装配见 web/app/lesson-data.ts)
- Trace 断点调试:可对代码执行流打断点逐行单步,静态 trace 由 scripts/generate-traces.ts 预先生成,浏览网站不会发起任何模型请求
- 本地跑起来:
cd web && npm install && npm run dev
配套的文字章节同样值得精读:docs/ch01-modules.md(模块地图)和 docs/ch02-loop.md(跟着数据流把五个文件填起来)。
适合谁读:一份学习路线清单
- 🧭 第一次接触 AI Agent:先读 docs/ch01-modules.md,建立"五个模块各管什么"的直觉
- 🔁 想搞懂 Agent Loop 和 Tool Calling:精读 docs/ch02-loop.md + src/agent.ts,重点看循环内的事件 yield 与 Context 管理
- 🧪 想验证自己的理解:跑一遍测试套件(
npm test),从 test/agent.test.ts 看循环行为是如何被断言的 - 🚀 想继续深入:教学文档预告了 nano-pi 未覆盖的方向——精确 token 估算与 compaction 切割、TypeScript 扩展系统、多 provider 路由等,这些正是从"能跑"走向"生产级"的必经之路
总结:pi-from-scratch 用 600 行零运行时依赖的 TypeScript,把"AI 编程 Agent 到底是怎么运转的"这个问题拆解到了最透明的程度。当你能自己手撕出一个读文件、改代码、跑命令的 nano-pi,再看任何生产级 Coding Agent,它对你都不再神秘。




