动手学 Pi: ein TypeScript-Lehrgang entlang von 15 Checkpoints

Ein Lehrpfad statt einer Bibliothek

Das Projekt adressiert ein konkretes Verständnisproblem: Wer einen Coding-Agenten benutzt, sieht am Ende nur die fertige Antwort. Die Zwischenschritte (wie eine Nutzernachricht zu einer Modellanfrage wird, wie ein Werkzeugaufruf zurückgebunden wird, wann Kontext verdichtet wird) bleiben unsichtbar. Der Kurs setzt genau dort an und führt in 15 Checkpoints durch dieselbe Ausführungskette. Die Zielgruppe sind Entwickler, die TypeScript beherrschen und den Aufbau eines Pi-artigen Agenten nachvollziehen wollen, nicht Anwender, die eine fertige Lösung suchen. Der README formuliert den Anspruch so, dass der Kurs nicht aus Pseudocode-Demonstrationen besteht, sondern aus einer Git-Historie, die ausgecheckt, ausgeführt und geprüft werden kann. Diese Selbstbeschreibung ist der Kern des Projekts und zugleich die Grenze: Es ist Lehrmaterial, kein Paket für den Produktivbetrieb.

Die Kette vom Protokoll bis zur Auswertung

Die 15 Checkpoints sind in vier Teile gegliedert, und die Reihenfolge folgt einer Abhängigkeitskette statt einer Themenliste. Teil I baut Nachrichten- und Modellprotokoll auf: TypeScript-Grundlagen anhand von vier DemoEvent-Typen, dann ein EventStream, der sowohl den Fall abdeckt, dass ein Ereignis zuerst eintrifft, als auch den, dass der Konsument zuerst wartet. Danach folgt das Speichern eines vollständigen Werkzeug-Roundtrips als einheitliche Nachricht und ein ScriptedModel, das vorgegebene Runden reproduzierbar abspielt. Teil II verbindet das Protokoll mit der Außenwelt: ein Adapter zwischen Kursnachrichten und Provider-API inklusive Rückübersetzung von SSE-Antworten, dann ein Tool-Vertrag mit Schema, Registry und Executor, dann die zweistufige Agent Loop, in der das Modell erst read vorschlägt und nach dem Zurückschreiben des Ergebnisses die endgültige Antwort erzeugt. Teil III macht den Agenten zustandsbehaftet und speichert abgeschlossene Nachrichten als JSONL mit Elternzeigern, sodass sich der aktuelle Gesprächspfad ab einem Blatt wiederherstellen lässt. Teil IV schließt mit Ressourcen, Erweiterungen, einem Runtime als Composition Root und einer eigenständigen Eval-Stufe.

Die Rollen von pi-textbook und dem Kurszweig

Wer das Repository klont, bekommt zunächst nur die Webseite. Der README trennt ausdrücklich zwei Repositories: pi-textbook enthält die HTML-Lehrseite, der Zweig course/build-your-own-pi im Repository hahhforest/pi enthält den ausführbaren Code unter packages/pi-course/. Diese Trennung ist praktisch relevant, weil die Webseite allein keinen lauffähigen Agenten liefert. Der Kurszweig startet laut README von einem festen Upstream-Commit 8479bd84 und organisiert die Historie als course(00) bis course(14). Zusätzlich existieren Tags pi-course-v1 sowie course-v1/00 bis course-v1/14, die die erste Kursversion fixieren. Für Leser, die den Code selbst durcharbeiten wollen, heißt das: Die Commits sind Teil des Lehrmaterials, nicht nur Abfall der Entwicklung. Wer die Historie umschreibt, zerstört den didaktischen Aufbau, und der Hinweis auf die festen Tags deutet darauf hin, dass die Autoren das wissen.

Installation und die beiden Kursbefehle

Der README nennt für die Webseite vier Schritte: git clone https://github.com/hahhforest/pi-textbook.git, dann cd pi-textbook, npm install und npm run dev. Für die Arbeit am Agenten selbst ist ein anderer Klon nötig: git clone --branch course/build-your-own-pi https://github.com/hahhforest/pi.git, gefolgt von cd pi und npm install. Danach stehen zwei Workspace-Befehle bereit. npm run checkpoint -w @pi/course -- 05 lokalisiert für das jeweilige Kapitel Parent, Target und die fokussierten Tests. npm run practice -w @pi/course -- 05 ../pi-practice-05 erzeugt ein Übungsverzeichnis ohne Antworten und ohne Git-Historie. Der zweite Befehl ist der interessantere, weil er die Trennung zwischen Lesen und Selbermachen technisch erzwingt: Im Übungsverzeichnis liegt eine LEARNING.md, die zusammen mit der Webseite und der Konsolenausgabe an einen begleitenden Agenten übergeben werden kann. Ob die Befehle in einer bestimmten Node-Version laufen, sagt der README nicht, und ich habe sie nicht ausgeführt.

Wo der Kurs an seine Grenzen stößt

Die stärkste Einschränkung steht im README selbst: Die Webseite und die Kapiteltexte sind auf Chinesisch verfasst, die englische Fassung beschränkt sich auf README_EN.md. Wer die Sprache nicht liest, kann den Code lesen und ausführen, aber nicht die Begründungen nachvollziehen, und genau die Begründungen tragen den Kurs. Ein zweiter Punkt ist die Modellabhängigkeit: Checkpoint 04 führt ein ScriptedModel ein, das vorgegebene Runden reproduzierbar abspielt, und Checkpoint 14 prüft den Runtime mit einem frischen Fixture. Beide Mechanismen sind auf Determinismus ausgelegt. Wer den Kurs als Vorlage für einen Agenten gegen einen echten Provider nimmt, muss in Checkpoint 05 den Adapter auf die eigene SSE-Antwort anpassen, und dort endet die Führung durch das Material. Ein dritter Punkt betrifft die Eval-Stufe: Sie liefert laut Beschreibung stabile Kategorien und Zählungen, ist aber kein Ersatz für eine Bewertung der Antwortqualität gegen ein echtes Modell.

Abgrenzung zu SDKs wie dem Anthropic Agent SDK

Der naheliegende Vergleich ist ein fertiges Agent-SDK, etwa das Anthropic Agent SDK, das Agent Loop, Werkzeugausführung und Sitzungsverwaltung als Bibliothek bereitstellt. Der Unterschied liegt nicht im Funktionsumfang, sondern in der Richtung der Abstraktion. Ein SDK verbirgt die Loop hinter einer API; der Kurs baut sie in Checkpoint 07 explizit nach und macht sichtbar, dass zwei Modellaufrufe nötig sind, bevor eine README-Anfrage beantwortet ist. Ein SDK liefert Kontextverwaltung als Dienst; der Kurs behandelt sie in Checkpoint 11 als Budgetproblem, bei dem die Historie unangetastet bleibt und der Kontext aus einem Suffix plus strukturierter Zusammenfassung neu zusammengesetzt wird. Wer wissen will, warum ein Agent bei langen Sitzungen teurer wird, findet die Antwort im Kurs an einer konkreten Stelle. Wer dagegen in zwei Wochen einen Agenten ausliefern muss, verliert mit dem Kurs Zeit, weil jeder Checkpoint gelesen und nachgebaut werden will.

Wartung, Lizenzen und der Kurszweig als Abhängigkeit

Das Repository ist nicht archiviert, der letzte Push datiert auf den 23. Juli 2026. Veröffentlichte Releases wurden nicht abgerufen, der Kurs arbeitet stattdessen mit Tags und einer linearen Commit-Historie im Zweig course/build-your-own-pi. Für die Wartung bedeutet das: Der Kurszweig hängt an einem festen Upstream-Commit 8479bd84. Bewegt sich das Upstream-Repository weiter, entsteht Divergenz, und Aktualisierungen müssen als neue Kursversion über neue Tags erfolgen, nicht als stilles Nachziehen. Die Lizenzlage ist geteilt: Anwendung und eigener Code stehen unter MIT, die Lehrtexte und eigenen Medien unter CC BY 4.0, und der Pi-Upstream-Code behält seine ursprünglichen Lizenz- und Urheberangaben. Der README verweist dafür auf LICENSE und LICENSE-CONTENT. Wer Material übernimmt, muss diese drei Schichten auseinanderhalten. Das Projekt bezeichnet sich als unabhängigen Community-Kurs ohne Verbindung zu Pi oder Earendil Works. Eine rechtliche Bewertung der kombinierten Weitergabe kann dieser Text nicht leisten.

Redaktionelles Fazit

Wer einen Pi-artigen Agenten selbst nachbauen will und Chinesisch lesen kann, findet hier einen ungewöhnlich konkreten Pfad, weil jeder Checkpoint an einen echten Commit und fokussierte Tests gebunden ist. Wer eine Bibliothek sucht, die er in ein Produkt einbinden kann, sollte weiterziehen: das Repository liefert Lehrmaterial, keinen Runtime-Dienst. Vor dem Einstieg zuerst die Lizenzaufteilung in LICENSE und LICENSE-CONTENT prüfen und mit npm run checkpoint -w @pi/course -- 05 verifizieren, ob der Kurszweig aus dem eigenen Netzwerk überhaupt klonbar ist, denn ohne diesen Zweig bleibt nur die Webseite.

Offizielle Quellen

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