PI from Scratch：从零手撕一个 Coding Agent

Fen9Pi2026/8/12大约 8 分钟

前言：最好的学习方式是自己造一个

2026-08-12 15:07 GMT+8

学习 Pi 的最好方式是什么？

读文档？看视频？分析源码？

都不如自己造一个。

今天介绍 PI from Scratch：

从零手写一个能读文件、改代码、执行命令的 TypeScript coding agent
沿着 pi 的数据流拆解，需要什么、造什么，所有组件都是符合直觉的

一、项目概览

PI from Scratch 是一个教学项目，教你从零开始实现一个极简的 coding agent。

一句话说清楚：

删除 pi 的工程细节，留下 pi 的核心思想，从零手写一个 nano-pi

项目地址：https://github.com/SaladDay/pi-from-scratch 在线阅读：https://pi-from-scratch.vercel.app 开源协议：MIT

核心特性

教学性质：

放轻松，这是一篇文章，不是一本书
你会很容易看懂
文章保留古法手敲，尽可能没有 AI 味

可视化学习：

网站把文章和源码放在一起
阅读推进时，右侧编辑器会逐步补全代码
当你看完的时候，nano-pi 的代码也会全部呈现在编辑器中

Trace 跟踪：

可以打断点逐行过代码
帮助理解代码执行流
线上 trace 是预先生成的静态数据

沿 pi 的数据流拆解：

需要什么、造什么
所有组件都是符合直觉的
删除 pi 的工程细节，留下 pi 的核心思想

二、为什么需要 PI from Scratch？

学习 Pi 的困境

Pi 是一个成熟的工程化项目：

✅ 功能强大
✅ 设计精良
✅ 工程细节完善

但也因此：

❌ 代码量大，难以全面理解
❌ 工程细节掩盖核心思想
❌ 初学者容易迷失在细节中

PI from Scratch 的解决方案

极简版本：

只保留核心思想
删除工程细节
符合直觉的实现

学习路径：

从零开始
需要什么、造什么
逐步构建完整系统

可视化学习：

文章 + 代码同步
逐步补全代码
Trace 跟踪执行流

三、nano-pi 的核心能力

能做什么？

从零手写一个能：

✅ 读文件
✅ 改代码
✅ 执行命令

的 TypeScript coding agent

核心思想

沿 pi 的数据流拆解：

用户输入 → 读取文件 → LLM 处理 → 修改代码 → 执行命令 → 输出结果

需要什么、造什么：

不需要完整的 pi 架构
只需要核心组件
每个组件都是符合直觉的

四、快速开始

运行 nano-pi

前置要求：

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

注意：

线上 trace 是预先生成的静态数据
浏览览网站不会发起模型请求

五、教学网站设计

文章 + 代码同步

设计理念：

左侧：文章内容
右侧：代码编辑器
阅读推进时，右侧编辑器会逐步补全代码

学习体验：

当你看完的时候，nano-pi 的代码也会全部呈现在编辑器中
看到哪里、代码到哪里
逐步构建完整系统

Trace 跟踪

功能：

可以打断点逐行过代码
帮助理解代码执行流
可视化代码执行过程

实现：

线上 trace 是预先生成的静态数据
浏览网站不会发起模型请求
安全、快速、无成本

六、沿 Pi 的数据流拆解

Pi 的数据流

简化流程：

用户输入
  ↓
读取文件
  ↓
LLM 处理
  ↓
修改代码
  ↓
执行命令
  ↓
输出结果

nano-pi 的实现

需要什么、造什么：

1. 读取文件

文件系统 API
路径解析
错误处理

2. LLM 处理

OpenAI API 调用
Prompt 构建
响应解析

3. 修改代码

代码解析
文本操作
写入文件

4. 执行命令

子进程执行
输出捕获
错误处理

七、核心组件

1. 文件系统操作

读取文件：

import fs from 'fs';

function readFile(path: string): string {
  return fs.readFileSync(path, 'utf-8');
}

写入文件：

function writeFile(path: string, content: string): void {
  fs.writeFileSync(path, content, 'utf-8');
}

2. LLM 调用

OpenAI API：

async function callLLM(prompt: string): Promise<string> {
  const response = await fetch('https://api.openai.com/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.NANOPI_API_KEY}`,
    },
    body: JSON.stringify({
      model: process.env.NANOPI_MODEL || 'gpt-4',
      messages: [{ role: 'user', content: prompt }],
    }),
  });
  
  const data = await response.json();
  return data.choices[0].message.content;
}

3. 代码操作

修改代码：

function modifyCode(code: string, instruction: string): string {
  // 使用 LLM 修改代码
  const prompt = `
请根据以下指令修改代码：

原始代码：
\`\`\`
${code}
\`\`\`

修改指令：
${instruction}

返回修改后的代码。
`;
  
  return callLLM(prompt);
}

4. 命令执行

执行命令：

import { exec } from 'child_process';

function executeCommand(command: string): Promise<string> {
  return new Promise((resolve, reject) => {
    exec(command, (error, stdout, stderr) => {
      if (error) {
        reject(error);
      } else {
        resolve(stdout);
      }
    });
  });
}

八、学习路径

第一步：理解数据流

从用户输入到输出结果：

用户输入是什么？
需要读取哪些文件？
如何调用 LLM？
如何修改代码？
如何执行命令？
如何输出结果？

第二步：实现核心组件

文件系统操作：

读取文件
写入文件
路径解析
错误处理

LLM 调用：

OpenAI API
Prompt 构建
响应解析
错误处理

代码操作：

代码解析
文本操作
文件写入
验证

命令执行：

子进程执行
输出捕获
错误处理
超时控制

第三步：组装完整系统

数据流串联：

用户输入 → 读取文件 → LLM 处理 → 修改代码 → 执行命令 → 输出结果

错误处理：

每个步骤的错误处理
优雅降级
用户友好提示

优化：

性能优化
用户体验优化
错误恢复

九、与 Pi 的关系

从 Pi 到 nano-pi

Pi 的核心思想：

Coding Agent 应该是极简的
需要什么、造什么
数据流驱动设计

nano-pi 的实现：

删除工程细节
保留核心思想
符合直觉的实现

从 nano-pi 到 Pi

理解 nano-pi 后：

可以更容易理解 Pi 的完整实现
可以理解 Pi 的工程细节
可以理解 Pi 的设计决策

十、适用人群

适合谁？

初学者：

想理解 coding agent 的基本原理
想从零开始构建一个完整的系统
想学习 TypeScript 和 Node.js

进阶者：

想深入理解 Pi 的设计思想
想学习如何拆解复杂系统
想学习教学项目的设计

教育者：

想了解如何设计可视化学习体验
想了解如何设计教学项目
想了解如何设计 Trace 跟踪

十一、核心价值

1. 从零实现

不是黑箱：

每个组件都是从头实现
每个决策都有解释
每个步骤都清晰可见

符合直觉：

需要什么、造什么
不需要预先理解复杂架构
逐步构建完整系统

2. 可视化学习

文章 + 代码同步：

左侧文章、右侧代码
阅读推进、代码补全
逐步呈现完整系统

Trace 跟踪：

打断点逐行过代码
理解代码执行流
可视化执行过程

3. 删繁就简

删除工程细节：

不追求完美的错误处理
不追求极致的性能优化
不追求完整的测试覆盖

保留核心思想：

数据流驱动设计
需要什么、造什么
符合直觉的实现

4. 教学优先

文章形式：

不是一本书，是一篇文章
容易看懂
保留古法手敲，尽可能没有 AI 味

学习体验：

逐步构建
可视化呈现
Trace 跟踪

十二、实际学习路径

学习目标

初学者：

理解 coding agent 的基本原理
学习 TypeScript 和 Node.js
学习如何从零构建系统

进阶者：

理解 Pi 的设计思想
学习如何拆解复杂系统
学习教学项目的设计

十三、总结

核心问题

学习 Pi 的困境：

❌ 代码量大，难以全面理解
❌ 工程细节掩盖核心思想
❌ 初学者容易迷失在细节中

PI from Scratch 的解决方案

极简版本：

✅ 只保留核心思想
✅ 删除工程细节
✅ 符合直觉的实现

可视化学习：

✅ 文章 + 代码同步
✅ 逐步补全代码
✅ Trace 跟踪执行流

为什么选择 PI from Scratch？

1. 从零实现

不是黑箱
符合直觉
逐步构建

2. 可视化学习

文章 + 代码同步
Trace 跟踪
逐步呈现

3. 删繁就简

删除工程细节
保留核心思想
容易理解

4. 教学优先

文章形式
容易看懂
没有 AI 味

记住

学习 Pi 的最好方式是自己造一个。
PI from Scratch 删除 pi 的工程细节，留下 pi 的核心思想，让你从零手写一个 nano-pi。
这不是一本书，这是一篇文章，你会很容易看懂。

附：资源链接

项目资源：

GitHub：https://github.com/SaladDay/pi-from-scratch
在线阅读：https://pi-from-scratch.vercel.app
License：MIT

相关资源：

OpenModel：提供 API 测试支持
Cubence：项目赞助
pi-book：深入理解 Pi 的书籍

安装速查：

# 安装依赖
npm install

# 设置 API Key
export NANOPI_API_KEY=your-api-key

# 运行 nano-pi
npm run dev

# 本地运行教学网站
cd web
npm install
npm run dev