Appearance
引子 · 新同事的第一个问题
小a第一天到项目组报到。工位还没坐热，组长就把一份故障复盘丢给了他：一个 Agent 在凌晨跑了三个小时，中途模型流中断、工具参数不合法、会话恢复失败——三条记录，像三个孤立的小问题，却让整夜的任务白干了。
小a翻着日志，越看越心虚。他刚学完 TypeScript，会跑命令行，见过 Agent 的演示，但真让他说清“这个 Agent 到底由什么组成”，他发现自己说不出来。
他硬着头皮去找老z，指了指日志里那三行记录：“这三条，我该从哪个开始查？”
老z没接话，反问道：“先别急着改代码。你能从输入走到输出，说清模型、工具、循环、会话和人，各自负责什么吗？”
小a想了想：“我知道它会调用模型，也会执行工具。但一次失败发生在哪一层，我看不出来；更不知道这个 Agent 的源码，该从哪个文件开始读。”
“这不怪你。”老z说，“你缺的不是代码量，是一套共同语言。没有这套语言，看日志全是孤立的错误，看源码全是陌生的目录。”
他指了指日志里的三行：“你看，这三条恰好是三个不同的层面。模型流中断，是接入层的问题——请求怎么发出去、流怎么收回来、中断算不算正常结束；工具参数不合法，是工具层的问题——schema 怎么声明、参数怎么校验、不合法的请求该被谁拦下；会话恢复失败，是状态层的问题——历史存在哪、进程重启后怎么接回来。没有共同语言，你只能三行日志一起抓瞎；有了共同语言，你第一眼就能判断该往哪一层查。”
小a眼睛亮了一下：“所以这本书不是教我怎么调某个 Agent，而是先教我怎么把它们分清楚？”
“对，而且不止分清楚。”老z在纸上画了一条线，“从分清，到看懂，再到自己造。这本书分三步走：”
本书的路线
- 建立共同语言——模型、工具、循环、上下文、扩展与安全，各自的工程边界是什么
- 沿真实源码核对——带着问题走一次 pi-mono 的调用链，看这些概念怎么落地
- 关掉源码自己动手——实现一个范围受控、可运行、可验证的 TypeScript Agent
“每一步都保留两件事，”老z说，“它解决什么，以及它暂时不解决什么。等你走完这三步，再回头看这页日志，你会自己找到答案。”
“那我大概要多久才能走完？”小a问。
“这本书不按‘天’排，按‘依赖’排。”老z说，“概念是源码的前置，源码是实现的前置——你读完概念才能读懂源码，读完源码才知道自己造的时候哪些抽象值得保留、哪些是那个项目特有的。顺序不是章节编号的巧合，是知识点本身的依赖链。”
“那三部分各解决什么问题，又暂时不解决什么？”小a追问。
“看这张表就清楚了。”老z写下一张导览：
全书导览
全书分为三部分，各自承担不同职责：
| Part | 职责 | 本部分解决什么 | 暂时不解决什么 | 章数 |
|---|---|---|---|---|
| I 概念篇 | 建立共同语言 | 模型、工具、循环、上下文、扩展与安全的工程边界 | 不讨论 Pi 或任一具体项目 | 17 |
| II 源码篇 | 沿调用链阅读 pi-mono | 核心入口、类型、状态、错误路径和设计代价 | 不逐行讲完所有源码，也不覆盖全部边缘功能 | 12 |
| III 实现篇 | 实现受限的 TypeScript Agent | 将各章代码拼成同一份可运行、可验证的产物 | 不承诺生产级平台或未被需求证明的扩展 | 12 |
“我给你翻译一下这三行。”老z说，“概念篇回答‘这些东西各自是什么’——它不绑定任何具体产品，所以你看完不会学到一个会过时的目录结构；源码篇回答‘一个真实项目怎么把它们组织起来’——它只讲 pi-mono 这一个仓库，但讲的是能复用的组织思路；实现篇回答‘如果我只有 TypeScript，最少要写什么’——它范围刻意收窄，只做被需求证明必要的部分。”
“那概念篇为什么不直接讲 pi-mono？”小a问。
“因为概念不分家，产品会分家。”老z说，“如果一上来就讲 pi-mono 的目录，你会把‘目录名’当成‘概念边界’——换一个产品，目录名变了，你就不认识了。先建立不依赖产品的概念，再看具体实现，概念才不会跟着目录名走。这也是为什么概念篇是 17 章、占了全书近一半——它是后面两部分的共同底座。”
“那源码篇只讲 pi-mono，是不是读完就只会 pi-mono？”
“不是只会，是能对照。”老z说，“pi-mono 是一个完整的、可运行的 Agent 仓库——它有真实的 Provider 接入、循环、会话、协议、评测。跟着它的调用链走一遍，你学会的是‘一个 Agent 系统有哪些责任边界、每条边界怎么接’；这套边界放回任何项目都成立。源码篇给你一个可以核对的样本，不是给你一套只能照抄的模板。”
“实现篇呢？既然源码篇已经讲透了，为什么还要自己造一个？”
“因为读和造是两种理解。”老z说，“读的时候，你会接受很多‘理所当然’的抽象——为什么要有 Harness、为什么会话要持久化、为什么工具要审批。自己造的时候，每个抽象都要重新问一遍‘我的需求需不需要它’。实现篇的价值不是写出比 pi-mono 更好的 Agent，而是让你对每个抽象都做过一次取舍。”
章节索引： 完整章节清单见 Part I 篇首页、Part II 篇首页、Part III 篇首页、附录。
阅读路线： Part I 建立共同语言 → Part II 用真实项目核对这些概念 → Part III 将必要能力实现并验证。
“还有几个阅读上的提醒，你记住，走完全书都用得上。”老z补充道，
怎么读这本书
- 先分清楚四种内容：已确认的事实、基于源码的推断、通用的工程观点、明确标注的示意——它们证据强度不同，别混为一谈
- 概念篇不出现具体产品，源码篇固定在 pi-mono 的一个提交上，实现篇只承诺
examples/mini-agent这个产物——每一部分都有它的证据边界- 每章结尾都有核验：概念篇是动手核验，源码篇是源码走查，实现篇是阶段验收——不是读过就完，是做出证据才算
- 遇到引用的源码符号，回 pi-mono 对应提交核对，不要只信书里的行号——行号是该快照下的辅助定位
“证据边界？”小a有点疑惑。
“就是‘我这句话凭什么站得住’。”老z说，“书里说的每一类话，来源不同：有的能从源码里直接看到，有的是从结构推出来的，有的是作者的经验判断，有的是画给你看的示意。**能分清这四类，你读的时候就知道哪些结论可以信任、哪些要自己验证、哪些只是参考。**这是整本书反复强调的阅读纪律，从引子就立起来。”
读完导览，小a还是惦记着那页日志。他问老z：“那我从哪个最小的问题开始？”
老z指着日志第一行说：“就从它开始。模型生成的一段文本，为什么有时能变成一次受控的工程动作？”