PI from Scratch
600 行 TypeScript 打造超级迷你版 pi，带你从 0 手写一个能读文件、改代码、执行命令的 coding agent。
证据显示这是一个教学用 coding agent，内置工具可读写文件、执行命令（e2e 测试直接演示写文件）。运行时依赖为零，dependency_security 可给满分；数据流因文章+Trace 断点设计而相对透明。扣分点：未见任何用户确认机制（命令执行、文件写入无审批），无回滚/撤销设计，外部副作用（shell、文件系统）无防护或边界声明，API 密钥仅靠环境变量、无泄露防护说明，最小权限原则未体现（工具直接获得任意命令执行能力）。
测试覆盖了 agent loop 核心路径（纯文本、tool_call 执行回填、未知工具报错回填）及 session 持久化 round-trip，与 README 描述的架构自洽；e2e 脚本对缺失 API key 有明确中文报错并退出。扣分点：未知工具的错误是回填进 Context 的字符串而非面向用户的清晰失败报告，e2e 中引用的 'GLM-5.2' 模型名真实性存疑，无重试/限流处理证据。
受众和场景非常明确：想从零理解 pi 数据流的开发者，README 语气和结构都服务这一目标，可给满分。模型名与 Base URL 可配置（OpenAI 兼容接口），环境适配尚可。扣分点：触发精度不适用/未见证据；能力边界仅靠'教学项目'定位隐含表达，未明确说明生产使用限制；Node 22+ 要求有说明但无降级方案。
安装说明完整（Node 22+、npm install、环境变量、本地网站运行、e2e 用法），LICENSE 文件与 package. 元数据一致的 MIT 可给满分。信息架构（文章+逐步补全的编辑器+Trace）有特色。扣分点：无 CHANGELOG、无已知限制章节、无贡献/维护指引，发布者身份未验证且无维护承诺证据，示例只有 e2e 一个、无 FAQ，版本停留在 0.1.0。
输出采用结构化事件流（assistant_text/tool_call/tool_result/turn_end）并支持 session 持久化，可用性尚可；600 行实现 agent loop 的边际价值在于教学而非生产替代，README 也如实定位。扣分点：作为实际 Agent 产品输出可用性一般（无确认、无审计、无中断恢复），成本收益取决于学习目的，通用任务价值有限，且 '600 行' 等宣传数字无法从给定文件核实。
测试文件与声称的核心路径可对应，README 提供了上游 pi 仓库和 pi-book 链接便于溯源。扣分点：'600 行'、'所有组件符合直觉' 等宣称无行内证据支撑；赞助商推荐语（OpenModel、Cubence）带有推广性质，事实陈述与营销混合未分离；除上游链接外缺少独立佐证，且本次为静态审查无法执行验证。
- 该项目的工具可直接执行任意 shell 命令并读写文件，且未见确认或沙箱机制；请在隔离环境中运行，切勿用于处理不受信任的任务。
- 这是一个教学项目而非生产级 Agent：无回滚、无审计、无已知限制说明，不要将其用于真实代码库的自动化修改。
- README 中的赞助商推荐（OpenModel、Cubence）带有推广链接和推荐码，属营销内容，请独立评估。
- API 密钥通过环境变量传入，请避免在 shell 历史或日志中泄露；e2e 测试会写入并删除 /tmp 下文件。
- e2e 中引用的 'GLM-5.2' 模型名未经核实，使用前请确认你实际可用的模型。
- '600 行' 等数字为作者宣称，本次静态审查无法核实。
这个 Agent 能做什么，适合哪些场景？
PI from Scratch 是一个教学型项目（仓库 SaladDay/pi-from-scratch），通过约 600 行 TypeScript 从零实现一个名为 nano-pi 的迷你 coding agent。项目沿用了开源项目 pi 的数据流拆解方式，删除工程细节、保留核心思想，说明 agent loop 与 tool-calling 的基本原理。它能读文件、改代码、执行命令，运行时需要一个 OpenAI 兼容 API 和模型名配置。配套教学网站把文章与源码并置展示：阅读推进时右侧编辑器会逐步补全代码，并提供 Trace 跟踪功能，可以打断点逐行查看代码执行流。线上 trace 为预先生成的静态数据，浏览网站本身不会发起模型请求。适合想理解 pi 类 coding agent 内部机制的工程师，而非作为生产级 agent 直接采用。
nano-pi 用 TypeScript 实现了一个最小可运行的 coding agent 循环：通过 OpenAI 兼容接口（默认 https://api.openai.com/v1）调用大模型，让模型读文件、修改代码并执行命令。安装后通过 npm run dev 启动，用 NANOPI_API_KEY 提供凭证，可用 NANOPI_MODEL 指定模型、NANOPI_BASE_URL 指定兼容接口地址。教学网站（pi-from-scratch.vercel.app）将文章与 nano-pi 源码同步展示，编辑器随阅读进度逐步补全代码，并支持 Trace 断点逐行跟踪执行流；网站上的 trace 是预生成的静态数据，浏览不消耗模型调用。
- 想理解 agent loop 和 tool-calling 原理的工程师，希望用 600 行代码看清 pi 类 coding agent 的最小核心
- 计划基于 pi 构建自己 agent 的开发者，想先通过删繁就简的 nano-pi 掌握其数据流
- 教学或团队分享场景，用 Trace 断点逐行讲解 agent 代码执行流
- 已读过 pi-book 的读者，想动手从零实现一遍再深入原版 pi
- 想在教学网站上一边读文章一边看代码逐步补全的自学者
这个 Agent 有哪些优点和局限？
- 体积极小：约 600 行 TypeScript 即可实现完整 agent 循环，阅读成本极低
- 配套教学网站将文章、逐步补全的源码和 Trace 断点跟踪结合，代码执行流可视化
- 遵循 pi 的数据流拆解，保留核心思想、去除工程细节，学习路径清晰
- 通过 NANOPI_BASE_URL 兼容任意 OpenAI 兼容接口，不绑定单一模型提供商
- 定位是教学项目而非生产工具，不适合直接用作日常 coding agent
- 运行依赖 Node.js 22+ 和自备的 OpenAI 兼容 API，密钥与调用费用需用户自行承担
- API 默认基于 OpenAI 兼容协议，若目标服务协议不兼容需要额外适配
- 仓库未提供测试、发布版本等工程化证据，代码质量与长期维护无从评估
如何安装或部署这个 Agent？
需要 Node.js 22 或更高版本，以及一个 OpenAI 兼容 API 的密钥。克隆仓库后：
bash
npm install
export NANOPI_API_KEY=your-api-key
npm run dev可选环境变量：NANOPI_MODEL（模型名）、NANOPI_BASE_URL（OpenAI 兼容接口地址，默认 https://api.openai.com/v1）。
如需本地运行教学网站：
bash
cd web
npm install
npm run dev如何使用这个 Agent？
配置 NANOPI_API_KEY（以及可选的 NANOPI_MODEL 和 NANOPI_BASE_URL）后运行 npm run dev 启动 nano-pi，它会把请求发送到你指定的 OpenAI 兼容接口。要学习实现原理，可访问 pi-from-scratch.vercel.app 在线阅读：右侧编辑器随阅读进度补全 nano-pi 代码，Trace 功能支持打断点逐行跟踪执行流；线上 trace 是静态预生成数据，浏览网站不会发起模型请求。
这个 Agent 与同类方案有什么区别？
项目明确以开源项目 pi 为蓝本：pi 是完整的工程实现，而本项目删除 pi 的工程细节、保留核心思想，用约 600 行代码实现超级迷你版。README 还提到 pi-book 一书可作为完成 nano-pi 后继续深入 pi 的进阶参考。