SaladDay/pi-from-scratch 是一个面向学习的 TypeScript 教程项目，用约 600 行代码从零实现一个迷你版 coding agent「nano-pi」。它拆解了 pi 类编程智能体的核心数据流，覆盖文件读取、代码修改、命令执行、LLM tool calling、agent loop 等关键机制，并配套在线交互式文章、逐步补全源码编辑器和 Trace 执行流跟踪，适合想理解 AI 编程助手内部原理的开发者。
适用领域
AI Agent / Coding Agent / 大语言模型应用开发 / Tool Calling / TypeScript 教程 / 开发者教育 / LLM 工程实践
配置难度
中等。对熟悉 TypeScript、Node.js 和基础 LLM API 调用的开发者较容易上手；如果不了解 agent loop、tool calling 或命令执行安全模型，需要结合教程逐步学习。
商业价值
该项目的直接商业价值主要在教育和技术验证层面。它可以帮助团队快速理解 AI 编程助手的核心实现机制，降低研发自有 coding agent、内部代码助手或自动化开发工具的认知门槛。对于培训机构、技术团队和 AI 应用创业者，它可作为原型参考和教学素材。但若要进入生产环境，还需要补充权限控制、沙箱、安全策略、模型路由、日志观测、错误恢复、企业集成等工程能力。
01
技术亮点
- 代码规模小，约 600 行 TypeScript，适合完整阅读和手动复现
- 聚焦 coding agent 核心思想，去掉了大型工程项目中的复杂工程细节
- 教程、源码和在线编辑器结合，阅读过程中右侧代码会逐步补全
- 提供 Trace 跟踪能力，便于理解 agent 的执行路径和数据流
- 采用 OpenAI 兼容 API，便于接入不同模型服务商
- MIT 许可证，适合学习、修改和二次开发
- 中文内容友好，对中国开发者学习 AI Agent 更容易上手
- 主题明确，覆盖 agent-loop、tool-calling、llm-agent、coding-agent 等热门方向
02
目标用户
- 想从零理解 coding agent 工作原理的前端或全栈开发者
- 希望学习 agent loop、工具调用、上下文管理的 AI 应用开发者
- 正在研究 pi、Claude Code、Codex 等编程智能体实现方式的工程师
- 熟悉 JavaScript/TypeScript、希望进入 AI Agent 开发方向的学生或自学者
- 想构建内部代码助手或轻量级自动化编程工具的技术团队
03
配置要求
- Node.js 22 或更高版本
- npm 包管理器
- 一个 OpenAI 兼容 API Key
- 必需环境变量：NANOPI_API_KEY
- 可选环境变量：NANOPI_MODEL，用于指定模型名称
- 可选环境变量：NANOPI_BASE_URL，用于指定 OpenAI 兼容接口地址，默认值为 https://api.openai.com/v1
- 如果运行教学网站，需要进入 web 目录单独安装前端依赖
04
适用场景
- 学习如何用 TypeScript 实现一个能读文件、改代码、执行命令的 coding agent
- 理解 LLM 与本地工具之间的调用流程，包括 tool calling 和 agent loop
- 作为 AI Agent 教学材料，用于团队内部分享、课程或技术文章参考
- 基于 nano-pi 原型扩展自己的轻量级代码助手
- 通过 Trace 跟踪逐行理解 agent 执行流和状态变化
- 对比 pi、Claude Code、Codex 等工具的基础设计思想
05
部署与配置
- 确保本机安装 Node.js 22 或更高版本
- 克隆仓库：git clone https://github.com/SaladDay/pi-from-scratch.git
- 进入项目目录：cd pi-from-scratch
- 安装依赖：npm install
- 配置 API Key：export NANOPI_API_KEY=your-api-key
- 可选配置模型名：export NANOPI_MODEL=your-model-name
- 可选配置 OpenAI 兼容接口地址：export NANOPI_BASE_URL=https://your-openai-compatible-endpoint/v1
- 运行 nano-pi：npm run dev
- 如需本地运行教学网站：cd web && npm install && npm run dev
06
风险与注意事项
- 项目定位是教学和原理演示，不是生产级 coding agent 框架
- 功能相对精简，缺少完整权限隔离、沙箱执行、安全审计、任务队列等生产能力
- 可执行本地命令和修改文件，若扩展不当可能带来安全风险
- 依赖外部 LLM API，运行成本、稳定性和响应质量受模型服务商影响
- 需要 Node.js 22，对部分旧环境不兼容
- 当前 README 中没有展示复杂项目适配、长上下文处理、错误恢复等高级能力
- 如果用于企业内部代码库，需要额外处理密钥管理、网络代理、数据合规和代码泄露风险
2026-08-15
第12名
新收录 · github_search
2026-08-14
第11名
新收录 · github_search
2026-08-13
第12名
新收录 · github_search
2026-08-12
第13名
新收录 · github_search
