序

致翻开这本书的你：

第一次打开一个真实的 Agent 项目，常见的障碍不是 TypeScript 语法，而是不知道该沿哪条调用链读：输入从哪里进入，状态如何变化，工具和模型怎样交接，出错时又由谁收束。

这本书提供的是一张阅读地图：先建立不依赖任何产品的 Agent 心智模型，再以固定快照中的 pi-mono 为例沿控制流和数据流走查，最后把必要零件实现为同一个可运行的 TypeScript Agent。

小a是刚加入项目的新同事，老z是有经验的同事。两人以代码走查、设计讨论和结对排障推进问题；对话只服务于问题、证据与取舍，不替代技术解释。

这本书是什么

这是一本面向开发者的 Agent 工程书籍，共 41 章正文和 9 个附录。它假定你已经有基本的 TypeScript、命令行和 Git 经验，想理解 Agent 是怎么搭起来的，并且愿意把结论落到代码和验证上。它不面向尚无程序设计经验的读者，也不是某款产品的手册。

全书的目标可以浓缩成一句话：把一个 Agent 系统从"听说过"读成"能自己造出来"。 为此它走了三步——先建立概念，再读真实源码，最后自己实现。

三步走

1. 建立共同语言：模型、工具、循环、上下文、扩展与安全，各自的工程边界是什么
2. 沿真实源码核对：带着问题走一次 pi-mono 的调用链，看这些概念怎么落地
3. 关掉源码自己动手：实现一个范围受控、可运行、可验证的 TypeScript Agent

为什么写这本书

“懂概念”与“能读真实工程”之间有一段距离。概念如果脱离实现，容易变成术语清单；源码如果没有路径，也容易退化为目录漫游。本书把两者连接起来，但不承诺逐行讲完所有源码。

它要解决的问题很具体：一个 Agent 项目摆在面前，你应该从哪个文件开始读？模型请求从哪发出、流怎么穿过适配层、循环怎么推进状态、会话怎么活过进程重启、出错时由谁收束——这些问题的答案，概念篇给框架，源码篇给实例，实现篇给你亲手造一遍的机会。

• 概念篇（第1-17章）建立模型、工具、循环、上下文、扩展与安全的共同语言，不以 Pi 或任何具体项目替代通用概念。
• 源码篇（第18-29章）讲清核心入口、关键类型、主要调用链、状态变化、错误路径与设计代价；没有覆盖的边缘功能会明确说明。
• 实现篇（第30-41章）只实现需求证明必要的能力，并以可运行产物、测试和阶段验收验证它们能够协同工作。

写给谁

• 有基本 TypeScript、命令行和 Git 经验，想理解 Agent 工程的开发者；
• 想阅读 pi-mono 源码、但需要一条可靠走查路径的程序员；
• 想用 TypeScript 实现一个范围受控 Agent，并愿意执行验证命令的人。

如果你符合其中任何一条，这本书按顺序读会有最大的收益；如果你只对某一部分感兴趣，下面的"怎么读"给了可跳的路径。

怎么读

• 只需要共同语言：阅读 Part I 概念篇；
• 想建立源码阅读能力：按 Part I → Part II 的顺序；
• 想完成可运行产物：按 Part I → Part III 的顺序，Part II 能为架构取舍提供真实项目的对照。

概念篇以“动手核验”收束，源码篇以“源码走查”收束，实现篇以“阶段验收”收束。每部分的结构、基线与阅读纪律，在三个篇首页各有交代。

整本书的阅读纪律

• 先分清四种内容：已确认的事实、基于源码的推断、通用的工程观点、明确标注的示意
• 概念篇不出现具体产品；源码篇固定在 pi-mono 的一个提交上；实现篇只承诺 examples/mini-agent 这个产物
• 每章结尾都有核验（动手核验 / 源码走查 / 阶段验收），做过才算读过
• 遇到引用的源码符号，回到对应提交核对，不只看书里的行号

关于 pi

本书的源码篇以 pi-mono 为阅读对象，统一使用提交 583f153d502aa8e958eefdb9af0fbd3344e68f95 的快照。该快照的根仓库版本是 0.0.3，本书选取的九个核心／产品范围包版本是 0.83.0；两者不能混用。本书根目录的 pi-mono/ 是被 Git 忽略的本地参考 clone，并非本书仓库的受版本控制内容；仅克隆本书仓库不等于已获得这份源码基线。它提供了多 Provider 模型调用、Agent 运行时、编码 CLI、终端 UI、协议和远程会话等相互关联的工程边界，适合用于追踪一条完整请求。

源码展示的是可核对的事实；从调用关系得到的解释会标为推断；伪代码、删节与假设场景会标为示意或简化。书中的观点是工程取舍，不代表 Pi 作者或维护者的意图。

与引子的关系

这本《序》回答"这本书是什么、写给谁、怎么读"；引子则是一个具体的工作场景——新同事小a接手一份故障复盘，在"模型流中断、工具参数不合法、会话恢复失败"三条日志里看不出该往哪层查。引子把"为什么要先建立共同语言"落成一个可感知的问题，也是全书叙事的起点。

如果你刚翻开这本书，建议先读引子（约三分钟），再回到这里看结构，然后从概念篇第1章开始。

致谢

感谢开源社区提供可阅读、可验证的真实项目，也感谢愿意把结论落实到代码和验证中的读者。

从引子开始，和小a、老z一起把问题拆开，再走到你自己的可运行 Agent。