前言：从会使用，到看懂它怎样工作
这本书写给第一次接触 Pi、也可能第一次认真打开一个软件工程的人。你不必先掌握 TypeScript，不必知道模型接口怎样调用，也不必理解所有文件。我们从一个具体的问题开始：当你在终端里输入“请帮我修改这段代码”时，究竟是谁读取文件，谁生成修改方案，谁执行命令，又是谁保存这次对话？
Pi 把这些工作拆在几个可以配合、也可以分别使用的软件包里。本书的目标，是帮你在脑中建立一张能用的地图。读完以后，你应该能说明 Pi 的主要用途，知道常见目录的职责，跟着一次输入走过核心执行流程，并在遇到问题时找到合适的文档或源码入口。
全书采用同一个方法：先提出问题，再走一个短例子，最后解释工程怎样解决它。代码只在能帮助理解的时候出现。第一次遇到专业词语时，我们会先解释；附录还准备了一份中英术语表，方便回查。
本书依据哪个工程版本
本书依据 earendil-works/pi 源码仓库编写，代码基准为提交 16f5f0af4d85ca583d045ceb5ed6d646fcaf7761，整理日期为 2026 年 10 月 20 日。该快照中的主要公开包版本为 1.3.0；Pi 源码根目录 package.json 的版本字段有自己的用途，不能用它代替各个包的版本。
书中章末的“源码依据”链接都固定到这次提交，便于你对照阅读。链接需要联网打开，但正文、目录、插图和练习都已装入 EPUB，离线也能阅读。未来版本可能改变命令、文件位置和接口；实际操作时，以你安装版本的 pi --help、交互命令和随包文档为准。
这是基于源码整理的中文学习读物，由 AI 辅助编写，不是项目维护者发布的官方手册。架构说明来自本次代码与文档检查；示例中的任务、对话和输出用于解释流程，不代表已经替你运行了真实模型请求。本书制作过程没有调用付费模型接口来验证任务效果。
怎样选择阅读顺序
如果你完全没有编程经验，请按顺序阅读第一至第四章。第二章专门解释终端、目录、Node.js、npm、TypeScript 和 JSON。初次阅读时，能说清它们各自负责什么就够了。
如果你已经会使用命令行，可以先读第三章建立目录地图，再进入第五至第八章，了解输入、执行循环、模型接口和会话。第九至第十三章介绍扩展、终端、外部工具，以及持久化和远程执行。它们是逐步拓宽视野的章节，不需要一次掌握。
如果你准备自己修改 Pi，请重点读第十四、十五章：前者教你按问题阅读源码，后者解释本仓库的开发与测试规则。第十六章把常见问题和一周学习路线放在一起，适合边用边查。
| 阅读目标 | 建议章节 | 可以完成的事情 |
|---|---|---|
| 先知道 Pi 是什么 | 第一至第三章 | 解释模型、工具和 Agent 的关系，认识工程目录 |
| 第一次实际使用 | 第四章、第八章 | 启动 Pi，选择模型，理解保存和恢复会话 |
| 理解内部执行过程 | 第五至第七章 | 跟踪一条消息怎样变成模型请求和工具调用 |
| 定制和集成 | 第九至第十三章 | 选择合适的扩展方式，区分不同运行时 |
| 开始读码和开发 | 第十四至第十六章 | 找到入口，按仓库规则检查和测试 |
阅读和练习的约定
书里的代码块会注明用途。bash 代码块一般表示在终端输入的命令；text 表示目录、流程或示意输出。出现 /login 这样的斜杠命令时，它是在 Pi 的输入框里使用的，不是直接交给系统终端。出现 src/、packages/ 等路径时，若未说明，都是相对于 Pi 源码仓库根目录。当前存放书稿的网站仓库是独立的 pi-beginner-book-zh，其中没有 Pi 的 packages/ 或 pi-test.sh。第十五章的开发命令需要先进入 Pi 源码仓库，再执行；书籍网站的构建方式另见本书仓库的 README。
你可以先读练习题，再看参考答案。练习主要检验理解，不要求付费账户或真实远程服务器。涉及实际修改时，使用自己创建的练习目录，保留修改前的内容。Pi 可以调用文件和命令工具；在当前默认设计中，它继承启动进程的权限。给练习任务安排清楚的工作范围，也是理解工具能力的一部分。
EPUB 是可以随着屏幕宽度和字号重新排版的电子书格式，因此本书按章和小节导航，没有固定页码。手机上遇到较长路径时可以横屏查看；不需要为了跟上“第几页”而保持某一种字号。
先从第一章开始。你要认识的第一件事，是“生成一段回答”和“真正完成一次代码修改”之间，需要哪些具体步骤。