$ cat ~/map/pi-book.md

pi-book (pi 的设计艺术)

A free Chinese-language book dissecting the design decisions behind Pi's architecture.

tutorials

Facts

repository: zhanghandong.github.io/pi-book/ ↗
GitHub Stars: —
Forks: —
license: —
npm / mo: —
last push: —

## TL;DR

A free Chinese-language web book on pi's architecture — The Design Art of pi — that records the key design decisions of the pi agent runtime, with each chapter answering one design question rather than walking the source code.

## Key points

$Titled 《pi 的设计艺术：构建生产级 Coding Agent 的架构决策》 (The Design Art of pi: Architectural Decisions for Building a Production-Grade Coding Agent), it states up front that it is neither a source-code walkthrough nor an API document — source appears only to explain why a decision was made.
$Organized as a knowledge map in five layers — Foundation (pi-ai), Core (Agent Runtime), Product (productization, externalized capabilities, tool design), Shell (UI, product in practice), and Philosophy (design philosophy) — written in Chinese and freely readable as an mdBook site.
$Three recommended reading paths: architect (chapters 1, 8, 10, 30-32), developer/contributor (chapters 2-3, 8-10, 15-16, 19, appendix D), and a full read in order. Prerequisites are reading TypeScript (types, generics, async/await) and knowing LLM API basics — no prior pi or Node.js framework experience needed.
$Every chapter ends with a trade-off section — what a decision gained and what it gave up (得到了什么 / 放弃了什么) — plus version-evolution notes; Mermaid architecture, flow, and sequence diagrams are embedded, and source citations carry file paths with line ranges such as packages/agent/src/agent-loop.ts:155-232.
$Version baseline: the core analysis is based on pi-mono v0.66.0 (April 2026) and cross-checked against v0.82.1 (July 2026), with the notable repository changes between the two — including the new server, sqlite-node, and evals packages — covered in chapter 2.
$The book's source is hosted at github.com/ZhangHanDong/pi-book, and the rendered book is served from zhanghandong.github.io/pi-book.

## FAQ

Q What do I need to know before reading?

Enough TypeScript to read type definitions, generics, and async/await, plus LLM API basics (prompt, tool calling, streaming). The preface explicitly says you do not need to have used pi or have Node.js framework experience.

Q Will it go stale as pi evolves?

Each chapter ends with version-evolution notes stating which version the analysis is based on and what changed since; the whole book's core analysis was cross-checked against v0.82.1, and the preface documents how design decisions stayed stable across that window.

## References

## Related entries

Last updated: Aug 31, 2026