Pi 1.0：从源码到自己的 Agent¶
这是一门面向「想理解 Agent 是怎么运行，并把它变成自己工具」的中文课程。最终目标：你能解释一次请求的完整生命周期，知道在哪个边界定制行为，并运行一个有自己工具、规则、事件记录和测试的 Agent。
本课程研究的是 Mario Zechner 发起、现在由 earendil-works/pi 维护的 Pi coding agent / agent harness。不是 Inflection Pi、树莓派项目，也不是某个 Pi 扩展的 1.0。官方发布记录的 v1.0.0 日期为 2026-10-01。
从哪里开始¶
| 你的目标 | 阅读路线 | 最终产物 |
|---|---|---|
| 先让 Pi 帮自己工作 | 01 → 03 → 12 | 个人 Pi 配置与技能包 |
| 把 Pi 嵌进自己的程序 | 02 → 04 → 06 → 07 → 14 | SDK 驱动的代码研究助手 |
| 自己掌握 Agent 运行时 | 02 → 04 → 05 → 08 → 13 | 只暴露业务工具的 Agent Core 应用 |
| 做长期运行、多用户产品 | 前面三条 → 09 → 10 → 11 → 15 | 存储、权限、并发和评测方案 |
| 深入读源码 | 05–11 → 17 | 文件、函数、行号与完整调用链 |
不需要先读完仓库再开始写 Agent。先跑离线实验，看见一次工具调用，再对照第 05 章研究它为什么发生。
配套文件¶
upstream/：从 GitHub 下载的最新主分支，保留完整 Git 历史。pi-1.0/：官方v1.0.0独立工作树，课程的稳定研究基线。docs/：课程 Markdown 原稿；完整单文件课程 便于整体保存。examples/：固定依赖版本的 TypeScript 实验、离线验证和个人 Pi 包。research/：版本证据、源码文件清单与讲解覆盖索引。scripts/、deployment/：课程构建、审核与 Nginx 部署文件。
下载：完整课程 Markdown、分章 Markdown 与图表资源、可运行实验项目。
第一项实验¶
在服务器项目根目录运行：
demo 使用 Pi 官方 Faux Provider，按脚本返回工具调用和最终回答。它不访问真实模型、不需要 API Key，不验证真实模型的智能水平。它验证的是实际 Pi 1.0 运行时、工具参数校验、事件和结果回传。
阅读约定¶
「源码事实」有固定 commit 的来源；「设计解释」是依据行为作出的归纳；「产品建议」是本课程为你的 Agent 提出的实现方案。课程代码采用 Pi 1.0 的 API，历史教程中的 @mariozechner/* 导入不能直接替换进去。