$ cat ~/map/pi-book.md

pi-book (pi 的设计艺术)

一本免费中文书，剖析 Pi 架构背后的关键设计决策。

tutorials

事实速查

## 速览

一本免费在线中文书《pi 的设计艺术：构建生产级 Coding Agent 的架构决策》——记录 pi 这个 agent 运行时的关键设计决策，每章回答一个设计问题，而不是带你通读源码。

$书名《pi 的设计艺术：构建生产级 Coding Agent 的架构决策》，前言开门见山：这本书不是源码导读，也不是 API 文档——源码只在需要解释「为什么这样做」时出场。
$全书按知识地图分五层组织——基石层（pi-ai）、内核层（Agent Runtime）、产品层（产品化、能力外置、工具设计）、宿主层（UI、产品实证）与哲学层（设计哲学）——以中文写就，mdBook 站点免费在线阅读。
$给出三条推荐阅读路径：架构师（第 1、8、10、30-32 章）、开发者/贡献者（第 2-3、8-10、15-16、19 章与附录 D）、完整阅读（按目录顺序）。前置知识只需读懂 TypeScript（类型、泛型、async/await）与 LLM API 基本概念——不需要用过 pi，也不需要 Node.js 框架经验。
$每章末尾都有取舍分析——「得到了什么 / 放弃了什么」——并标注版本演化说明；书中嵌入 Mermaid 架构图、流程图与时序图，源码引用带文件路径与行号范围，例如 packages/agent/src/agent-loop.ts:155-232。
$版本基线：核心分析基于 pi-mono v0.66.0（2026 年 4 月），并已对照 v0.82.1（2026 年 7 月）核实；两个版本之间最显著的仓库结构变化——包括新增 server、sqlite-node、evals 三个包——见第 2 章。
$书籍源码托管于 github.com/ZhangHanDong/pi-book，在线版发布在 zhanghandong.github.io/pi-book。

Q 读这本书需要什么基础？

能读懂 TypeScript 的类型定义、泛型与 async/await，了解 LLM API 的基本概念（prompt、tool calling、streaming）即可。前言明确说明：不需要用过 pi，也不需要 Node.js 框架经验。

Q pi 一直在更新，书会不会过时？

每章末尾的「版本演化说明」都会标注该章分析基于的版本与后续变化；全书核心分析已对照 v0.82.1 核实，前言也记录了这段时间内核心设计决策保持稳定的结论。

最后更新: 2026年8月31日