pi-from-scratch是什么?600行TypeScript零依赖手撕Coding Agent,AI编程Agent完整入门指南

原创2026-10-14 06:31:291,643 阅读

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 可以调工具。

  1. 模型读到你的问题,判断需要先看看某个文件,发出一个 tool_call
  2. 程序帮它执行工具,把结果喂回 Context(对话上下文)
  3. 模型接着想,继续调工具或直接回复,直到任务完成

这个"思考 → 行动 → 反馈"的循环,就是大名鼎鼎的 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 胶水层:把上面四者粘起来,管理会话持久化

pi-from-scratch nano-pi 五模块依赖关系与 Coding Agent 架构

这张依赖图值得细看:llm 不知道 agent 的存在,agent 不知道 tui 长什么样,tools 不知道自己被谁调用——单向依赖让每个模块都能独立替换、独立测试。src/cli.ts 是唯一"认识所有人"的入口,这也是它被称为胶水层的原因。

Agent Loop 工作原理:一个 while 循环就是 Agent 的灵魂

Agent 与普通聊天程序的差别全部浓缩在这个循环里:

AI 编程 Agent 的 Agent Loop 循环流程:ask LLM、tool_call、执行工具并回写 Context

用伪代码表示,核心逻辑不到 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 出去,外层可以逐条消费。一轮循环的完整数据流长这样:

Coding Agent 单轮 Agent Loop 数据流:Context 经 stream 产生 StreamEvent,agent 回写 assistant message 与 tool_result

注意图中实线与虚线的分工:实线是更新 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 是它们之间的协议。

同一个 AgentEvent 事件流可被 TUI、Web 前端等不同界面消费

想把终端换成 Web 页面?不动 agent 的任何代码,写一个 HTTP server 接收同一条事件流、用 SSE 推给浏览器即可——教学文档里给了一段二十来行的示例(见 docs/ch02-loop.md 的"换个前端"一节)。

完整回合走查:从你敲下回车到会话落盘

把一次真实任务"把 hello.txt 改成大写"拆成时序,各角色如何接力一目了然:

Coding Agent 完整任务时序:用户输入经 tui/cli、stream、read_file、edit 工具调用直至 persistSession 落盘

用户输入从 tui 出发,cli 把它塞进 Context 交给 agent;模型回复(可能带 tool_call)经 agent 转发给 tui 流式显示;有工具就执行、把结果放回 Context 再问;没有工具就等用户下一轮输入;回合结束 cli 把新增消息持久化到 ~/.nanopi/session.jsonl。

边界情况处理:生产级 Coding Agent 的三个真实坑

教学项目最容易省略、但恰恰最有价值的部分,nano-pi 一个都没省:

  1. max_tokens 截断——模型输出撞上限时,tool_call 的参数 JSON 可能只剩半截。nano-pi 的处理很保守:不执行残缺参数,而是回一条错误消息让模型重发(src/agent.ts)
  2. 用户中断(abort)——Ctrl+C 触发 AbortSignal,一路传到 fetch 和子进程。被跳过的 tool_call 会补上 error: aborted 结果,保证 tool_call 与 tool_result 严格配对,否则恢复会话时 API 会直接报错
  3. 请求失败(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,它对你都不再神秘。

登录后查看全文
pi-from-scratch