动手学 Pi: A 15-Checkpoint TypeScript Course for Building a Pi-Style Coding Agent

The gap pi-textbook targets: agent tutorials that stop at the diagram

Most material about coding agents explains the loop in prose and leaves the reader to reconstruct the state machine. pi-textbook takes the opposite position. Its README describes the course as a closed loop of four parts per chapter: textbook prose, a real commit, focused tests, and a failure experiment. The claim that matters is the third one. The course code is not a pseudocode demonstration; according to the README it is a Git history you can check out, run and verify. That is a different promise from a blog series, because a commit history can be inspected and a test suite can fail loudly. The audience is narrow and identifiable: a TypeScript developer who wants to understand how streaming model events, tool calls, session state and context compaction fit together, and who would rather type the code than import a framework. The course is written in Simplified Chinese, with an English README available at README_EN.md, but the chapter prose itself is the Chinese textbook. If you cannot read Chinese, the runnable checkpoints and tests are still inspectable, but the teaching layer is closed to you.

Following one README request through the whole execution chain

The checkpoint table is the clearest statement of the architecture. Checkpoint 00 follows a single README read request through the complete loop: a user message, two model calls, a tool call and its result, and a final answer. Everything after that takes one layer of that loop and makes it explicit. Checkpoints 01 through 05 build the model and protocol layer: a TypeScript union type with runtime validation, an EventStream that delivers both the next item and the final result regardless of whether events arrive before or after the consumer waits, a unified message representation that pairs a tool call with its result, a ScriptedModel that replays preset turns, and a provider adapter that converts course messages into provider requests and turns SSE responses back into unified model events. Checkpoints 06 through 08 move to tools and the loop: an echo call passing through schema, Registry and executor while preserving the original call id; a two-turn Agent Loop where the model proposes a read, the tool result is written back, and the model produces a final answer; and four tools (read, write, edit, bash) operating inside a single workspace. Checkpoints 09 through 11 handle state: a stateful agent that keeps messages across runs and manages subscription, cancellation, in-run instructions, follow-up and reentry; a session tree that appends completed messages as JSONL records with parent pointers and restores the current conversation path from a chosen leaf; and context compaction that splits history at complete tool interactions, keeps a suffix within a token budget, and uses a structured summary to restore earlier facts. Checkpoints 12 through 14 close the loop with resources, extensions, a composition root and an independent eval. The design decision worth noting is that history is never mutated during compaction. The README states the principle directly: history stays put, context is rebuilt against a budget. That is a deliberate trade-off, since rebuilding costs work on every turn but keeps the session tree as a stable record.

Reading pi-textbook locally with npm run dev

The textbook site is a Next.js-style application with a content build step. The README gives this sequence for running it locally, and the predev script runs content:build before the dev server starts, so you do not need to invoke it separately.

git clone https://github.com/hahhforest/pi-textbook.git
cd pi-textbook
npm install
npm run dev

The engines field requires Node >=22.13.0, and the dev script runs vinext dev with WRANGLER_LOG_PATH set to .wrangler/wrangler.log, which tells you the site is built on a Workers-oriented toolchain rather than plain next dev. The README also points at the hosted version at build-your-own-pi-cn.enochzhang.chatgpt.site if you would rather not run it. For the course code itself, the README gives a separate clone against the course branch of the pi repository, followed by two workspace scripts. The checkpoint command locates the chapter's parent, target and focused tests; the practice command creates an exercise directory with no answers and no Git history.

git clone --branch course/build-your-own-pi https://github.com/hahhforest/pi.git
cd pi
npm install
npm run checkpoint -w @pi/course -- 05
npm run practice -w @pi/course -- 05 ../pi-practice-05

After the practice command you get a directory containing a LEARNING.md file. The README's suggested workflow is to hand that file, the chapter page and the command output to a tutoring agent. Note the repository split: pi-textbook holds the HTML textbook and site, while the runnable checkpoints live in packages/pi-course on the course branch of hahhforest/pi, which starts from a fixed upstream commit 8479bd84 and organizes history as course(00) through course(14), with pi-course-v1 and course-v1/00 through course-v1/14 tags pinning the first version.

Where the course model breaks down: ScriptedModel is not a provider

The most important limitation is structural rather than a bug. Checkpoint 04 introduces ScriptedModel, which replays preset turns and records request snapshots. That is what makes the early chapters testable without network access, and it is why the course can assert on a stable event stream. It also means the first half of the course teaches an agent whose model behaviour is deterministic. Real provider responses are not. The provider adapter arrives at checkpoint 05 precisely because the scripted layer cannot cover SSE parsing, partial events or provider-specific request shapes. A reader who stops before 05 has a mental model that will not survive contact with a live API. The second limitation is scope. The toolset is four tools: read, write, edit and bash, all confined to one workspace. There is no MCP integration, no multi-agent orchestration, and no sandboxing story beyond the workspace boundary. If your goal is a production agent that talks to arbitrary external services, this course gives you the loop and the state model, not the integration surface. The third is language. The chapter prose is Chinese. The repository ships README_EN.md, but the checkpoint table, the learning contract tests and the chapter content are Chinese-first, and the tests directory includes chinese-prose.test.mjs, which suggests prose quality is enforced as a build constraint rather than an afterthought. Translating the course is not a configuration change.

pi-textbook versus reading the upstream pi source directly

The obvious alternative is to read the pi repository itself, since the course branch is derived from a fixed upstream commit 8479bd84. The difference in approach is sequencing. Upstream source presents the finished architecture: the pieces exist in their final arrangement, and the reader has to infer which decisions were load-bearing and which were incidental. pi-textbook inverts that by making each layer a checkpoint with a parent, a target and focused tests, so the reader meets EventStream before the Agent Loop and the Agent Loop before session persistence. The cost is that the course is a reconstruction. It starts from an offline trajectory and builds toward a Pi-style agent, and the README is explicit that this is a community original unofficial course, not affiliated with or representing Pi or Earendil Works. So the course is a teaching artifact about an architecture, not a mirror of the upstream codebase's current state. If you need to work on upstream pi itself, the course branch will not track it. If you need to understand why the architecture is shaped the way it is, the checkpoint ordering is the more efficient path. A third option, importing a ready-made agent framework, solves a different problem entirely: it gives you a working agent without the mechanism, which is the opposite of what this repository is for.

Licence split between code and textbook prose

The repository does not use a single licence. The README states that applications and original code are under the MIT License, while the textbook prose and original media are under CC BY 4.0, and that upstream Pi code retains its original licence and attribution. The package.json license field reads SEE LICENSE IN LICENSE, which points at the file rather than naming a single identifier, and LICENSE-CONTENT is a separate file for the content terms. This matters if you plan to reuse the chapters in your own teaching material: MIT on the code and CC BY 4.0 on the prose are different obligations, and the attribution requirement for the content sits alongside the upstream attribution for any Pi-derived code. The README directs readers to both files for details. This is a description of what the repository states, not legal advice; if you are republishing the prose commercially, read LICENSE-CONTENT yourself. On maintenance, the last push to the default branch was on 2026-07-23, and the repository is not archived.

Editorial conclusion

Adopt pi-textbook if you already write TypeScript, want to read Chinese technical prose, and prefer learning an agent architecture by checking out real commits rather than reading diagrams. Skip it if you need English-only material, want a drop-in agent library, or expect the textbook repository to contain the runnable course code, which actually lives in the course/build-your-own-pi branch of hahhforest/pi. Before committing time, verify that Node satisfies the engines field (>=22.13.0), run npm run learning:verify to confirm the learning contract and prose tests pass, and check the LICENSE-CONTENT file if you intend to reuse the textbook prose rather than the code.

Frequently asked questions

Official sources

1. hahhforest/pi-textbook on GitHub
2. Issues
3. License: MIT
4. Project website
5. README