Claude Code、Cursor 这些 AI 编程工具，用起来像魔法：你说一句"帮我改这个 bug"，它就真的去读代码、改代码、跑测试。
但魔法的谜底，其实朴素得很。上周 GitHub 周榜上有个项目，把这个谜底彻底摊开了——pi-from-scratch：8月9日创建，3天 700+ Star，MIT 开源。
一句话介绍：用 600 行 TypeScript，从零手写一个能读文件、改代码、执行命令的 AI 编程助手。
灵魂只有一个 while 循环
我把它的核心源码翻了一遍，整个 Agent 的心脏（agent.ts，174行）就是一个死循环：
- 把你的话发给大模型
- 模型回复时如果要求"调用工具"，就去执行工具
- 把工具执行结果塞回对话上下文
- 再问模型，如此循环
- 直到模型不再调用工具，循环结束
没有玄学，没有魔法。所谓"AI 自主完成任务"，本质就是这五步的反复。
工具只要4个，就够干活了
一个能改代码的 Agent 需要多少工具？答案：4个（tools.ts，125行）：
- read_file —— 读文件
- write_file —— 写文件
- edit —— 精确替换某段文本（还做了唯一性校验，防止改错地方）
- run_bash —— 执行命令验证结果
读、写、改、验证，最小闭环。你看，强大的不是工具数量，是循环本身。
两个生产级细节，值得抄走
让我意外的是，这个教学项目还藏了两个真实产品才有的细节：
上下文压缩：对话超过 50 条消息时，让大模型把旧消息总结成一段摘要，只保留最近 20 条。这就是所有 AI 助手"聊久了还记得开头"的秘密——不是记性好，是做了笔记。
会话持久化：每轮对话追加写入本地文件，程序重启不丢历史。
这两个细节，正是"玩具 demo"和"能用的产品"的分界线。
怎么学：边读边补全代码
这个项目最用心的地方是配套的学习网站（pi-from-scratch.vercel.app）：
左边是文章，右边是代码编辑器——你每读一段讲解，右边的代码就自动补全一块。读完文章，整个 Agent 的代码也完整呈现出来了。还带 Trace 功能，可以打断点逐行看代码怎么执行。
作者特意说了一句：文章"保留古法手敲，尽可能没有 AI 味"。在 AI 生成教程泛滥的今天，这句话本身就值得尊敬。
想自己跑一遍？三条命令
需要 Node.js 22 以上版本和一个 OpenAI 兼容的 API（DeepSeek、GLM、Ollama 本地模型都行）：
npm install
export NANOPI_API_KEY=你的key
npm run dev
然后你就可以和自己手写的 Agent 对话了。
看懂这个，就看懂了所有AI编程助手
Claude Code 的架构比这复杂几十倍，但核心骨架就是这 600 行：循环 + 工具 + 上下文。
这也是我反复强调的：AI 落地不神秘，它是一层一层可以拆开理解的工程。看懂原理的人用工具，会比只会点按钮的人深一个层次——你知道它为什么行，也知道它什么时候会不行。
💬 评论