致翻开这本书的你:

几个月前,我第一次打开 pi 的源码时,和大多数人一样懵——一个 monorepo,几十个包,几千个文件,满屏 TypeScript。它在解决什么问题?为什么长成这样?我该从哪读起?

后来我想明白了:读源码和学任何手艺一样,缺的不是耐心,是一张地图。 这张地图不该是冷冰冰的目录,而该是一个人带着你走——讲清楚每个设计背后"作者遇到了什么难题、为什么这么选、代价是什么"。

于是有了这本书。它用一个"小a拜师"的故事当线索,把 AI Agent 从概念到源码再到动手实践,一路讲下来。

为什么写这本书

AI Agent 这两年火得发烫,但大多数教程要么只讲概念(读完还是不会),要么直接甩源码(读者直接被吓跑)。这本书想站在中间:

• 概念要讲透,但用故事和比喻,零门槛;
• 源码要拆细,但只拆最该读的,每段代码讲"为什么";
• 更要动手——最后三分之一,带你从空目录造一个真能跑的 Agent。

写给谁

• 想搞懂 AI Agent 怎么运作的开发者;
• 想读 pi 源码但不知从何下手的程序员;
• 想用 TypeScript 亲手造一个 Agent 的人。

怎么读

• 只想懂概念 → 读 Part I;
• 想精读 pi 源码 → Part I → Part II;
• 想动手造 → Part I → Part III(Part II 强烈建议先读)。

每章末尾有"课后实验",看十遍不如做一遍。

关于 pi

本书以 pi-mono(现 earendil-works/pi)为解剖对象。它是一个 AI agent toolkit 的 TypeScript monorepo——统一多厂商 LLM 调用、Agent 运行时、编码 CLI、终端 UI 等九个包。选它,是因为它分层清晰、设计克制、代码质量高,是极好的学习标本。

🧙 一句话:pi 是"单兵作战"哲学的极致,读懂它,你就懂了 Agent 的基本盘。

致谢

感谢开源社区——没有 pi 这样的项目,就没有可解剖的标本。感谢每一个读到这里的人,你们的耐心是这本书存在的意义。

开始吧。 从序章开始,认识小a和老z,然后一路读到你自己造出第一个 Agent。

—— 作者