Agent 工程 / 源码阅读 / 动手实现

大话 Agent

从 Agent 的共同语言出发，沿真实项目的调用链读源码，再用 TypeScript 完成一个可运行、可验证的受限 Agent。

从引子开始读 →直接看第 1 章 ↗

1. 01概念篇

   第 1–17 章。不依赖任何产品，建立模型、工具、循环、上下文、扩展与安全的共同语言。

2. 02源码篇

   源码篇 01–13 章。沿 pi v1.0.0 的真实调用链，核对这些边界在工程里落在哪里。

3. 03实现篇

   实现篇 01–12。关掉源码，从空目录写出一个范围克制、可运行、可验证的 TypeScript Agent。

42 章正文 · 11 个附录 · 源码基线 pi v1.0.0 · 实现篇 40 个测试

序

致翻开这本书的你：

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

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

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

这本书是什么

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

全书的目标可以浓缩成一句话：把一个 Agent 系统从“听说过”读成“能自己造出来”。

三步走

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

为什么写这本书

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

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

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

写给谁

• 有基本 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/ v1.0.0 快照中定位一次请求的入口、模型流、循环、会话、工具、终端更新和协议边界，并说明每一步的证据来自哪个文件或符号。
• 实现篇：能在 examples/mini-agent 中运行测试和类型检查，说明每条控制流、错误路径、取消路径和审批边界由哪条断言覆盖。

这三条不是“读完的感受”，而是可以交给别人检查的结果。做过对应核验，才算达成对应目标。

关于 pi

本书的源码篇以 pi-mono（现名 earendil-works/pi）为阅读对象，统一使用标签 v1.0.0（提交 a13d35a742c6ef8462812a28fbe1d8c8b7431c32）的快照。该快照的根仓库版本是 0.0.3，本书选取的八个包版本是 1.0.0；两者不能混用。本书仓库根目录的 pi/ 是这个标签的源码快照，加了中文注释，路径和符号与上游一致，行号会因注释偏移。它提供了多 Provider 模型调用、Agent 运行时、编码 CLI、终端 UI、协议和远程会话等相互关联的工程边界，适合用于追踪一条完整请求。

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

与引子的关系

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

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

致谢

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

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