阅读指南与学习路线
本页解决什么问题：告诉你这本书怎么读——按什么顺序、每个阶段学什么、做哪些实验、可以跳过什么。
全书结构
本书共八个部分，按四个学习层次组织：
图加载中…
图 0-1 全书学习路径
阅读顺序自上而下：先打好语言基础（层次一），再建立 Agent 概念（层次二），然后进入 Pi 源码（层次三），最后动手实现（层次四）。箭头表示「建议先读」。
图中每个方框对应侧边栏的一个部分。四个层次的分工：
- 层次一（第一、二部分）：让你能读懂 TypeScript 代码、能运行 Node.js 程序。只讲理解 Pi 所需的语言概念，不是完整语法手册。
- 层次二（第三部分）：不碰 Pi、不需要 API Key，用 Fake Model 和小实验建立 LLM、消息、流式输出、Tool Calling、Agent Loop、Session、Compaction 的完整心智模型。
- 层次三（第四~七部分）：进入 Pi 源码。先看全貌（第四部分），再追踪一次真实请求的完整路径（第五部分），然后逐模块深入（第六部分）与扩展机制（第七部分）。所有结论都固定在同一个 commit 上，可点击跳转 GitHub。
- 层次四（第八部分）：不抄 Pi 源码，独立实现一个教学版 Mini Agent Harness，检验你是否真正理解了前面的一切。
按背景选择起点
| 你的背景 | 建议起点 | 可以跳过 |
|---|---|---|
| 有编程经验，但没写过 JS/TS | 1.1 JavaScript、TypeScript 与 Node.js | 无 |
| 会 JS，没系统学过 TS | 2.1 类型入门（第一部分快速翻过） | 第一部分 |
| 熟悉 TS/Node | 3.1 LLM 与模型 API | 第一、二部分 |
| 已了解 LLM API 与 Tool Calling | 3.5 Agent 与 Agent Loop 快速校准术语，然后进第四部分 | 3.1–3.4 |
| 只想读 Pi 源码分析 | 4.1 Pi 是什么 | 前三部分（术语不懂时回查术语表） |
| 只想动手写代码 | 实践任务索引 或 8.0 Mini Harness 总览 | 按需回读 |
跳读时的安全网：本书所有关键术语都收录在术语表，每个术语给出定义和详细讲解所在的章节。
章节依赖关系
多数章节只依赖它前面的章节，以下是几条需要注意的强依赖：
图加载中…
图 0-2 关键章节依赖
如果读到右侧章节感到吃力，先回读它左侧的前置章节。
特别说明：2.3（可辨识联合）和 2.6（异步迭代器）是全书最重要的两个前置概念——Pi 的消息、事件、流式输出全部建立在它们之上。如果你只打算精读两章 TypeScript，就读这两章。
实践任务路线
全书实验都在仓库的 labs/ 目录，全部无需 API Key（第八部分最后一步接真实模型除外，且为可选）。完整清单见实践任务索引。
| 阶段 | 实验目录 | 你会做出什么 |
|---|---|---|
| A. TypeScript 基础 | labs/typescript-basics/01–12 | 12 个语言概念小实验，每个 5–15 分钟 |
| B. Agent 概念 | labs/agent-concepts/01–04 | Fake Model → 流式输出 → Tool Call 数据结构 → 完整 Agent Loop |
| C. Pi 源码观察 | 第四~七部分各章内嵌任务 | 从源码启动 Pi、观察 Session 文件、写最小 Extension |
| D. Mini Harness | labs/mini-agent-harness/ | 独立实现的教学版 Agent Harness（最终综合项目） |
建议节奏：每读一章就做该章的实践任务，不要攒到最后。B 阶段的 04-agent-loop 是基础篇的压轴实验，做完它再进入 Pi 源码会顺利得多。
概念出现顺序
如果你想知道某个概念在哪一章第一次正式讲解：
TypeScript / Node.js 概念
| 概念 | 首次讲解 |
|---|---|
| npm、package.json、monorepo/workspaces | 1.3 |
| module/import/export/ESM | 1.4 |
| 类型、基本类型、对象类型、optional、readonly、any/unknown | 2.1 |
| interface、type、函数类型、结构化类型 | 2.2 |
| union、字面量类型、可辨识联合、never | 2.3 |
| 泛型、class、类型收窄、type guard | 2.4 |
| Promise、async/await、事件循环 | 2.5 |
| 异步迭代器、async function*、for await | 2.6 |
| 事件订阅、回调、AbortController/AbortSignal | 2.7 |
| node:fs、node:path、process | 2.8 |
| Error、try/catch、node:test | 2.9 |
Agent 概念
| 概念 | 首次讲解 | 源码深入 |
|---|---|---|
| LLM、模型 API、system/user/assistant、API Key | 3.1 | 6.1 |
| 上下文、token、上下文窗口 | 3.2 | 6.6 |
| 流式输出、事件流、SSE | 3.3 | 5.4 / 6.1 |
| Tool Calling、Tool Call、Tool Result、参数校验 | 3.4 | 5.3 / 6.4 |
| Agent、Agent Loop | 3.5 | 6.3 |
| Agent Harness、Session、状态 | 3.6 | 5.5 / 6.5 |
| Context Compaction | 3.7 | 6.6 |
| Extension、Skill | 3.7 | 7.1 / 7.2 |
| 取消、中断、超时 | 2.7 / 3.7 | 5.6 |
| Provider | 3.1 | 6.2 |
| RPC、SDK | 4.3 提及 | 6.10 / 6.11 |
版本说明
本书分析的 Pi 源码固定在 earendil-works/pi@c13ffe18（2026-07-30）。你在 GitHub 上看到的最新代码可能已有差异——所有源码链接都指向固定 commit，不会因上游更新而失效。详见仓库、版本与历史。
排版约定
- 📘 概念卡片：正式定义一个新概念。
- 🌱 初学者提示：为零基础读者补充背景，有经验者可跳过。
- ⚠️ 常见误解：初学者最容易踩的坑。
- 🛠 实践任务：可以实际动手执行的练习。
- 带左侧竖线的源码引用块：可点击跳转到 GitHub 固定版本的对应行。
- 命令行代码块可直接复制运行；
$提示符不会出现在可复制内容里。