动手学 Pi : reconstruire un agent de codage en 15 checkpoints, avec le commit comme correction
《动手学 Pi》：沿 15 个真实 checkpoint 从零构建 Pi-style Agent
En bref
- De quoi s’agit-il ?
- Un cours chinois non officiel qui fait suivre l'implémentation d'un agent de type Pi, du protocole de messages jusqu'à l'évaluation, à travers 15 checkpoints exécutables et un historique Git vérifiable.
- À qui s’adresse-t-il ?
- Ce cours s'adresse aux développeurs TypeScript qui veulent comprendre la mécanique interne d'un agent de codage en lisant et exécutant du code, pas en assemblant des bibliothèques. Il n'est pas fait pour qui cherche un framework prêt à l'emploi, ni pour qui ne lit pas le chinois, car le corps du texte est en chinois et rien n'indique une traduction anglaise.
- Puis-je l’utiliser commercialement ?
- Oui. MIT est une licence permissive : vous pouvez utiliser, modifier et vendre un logiciel qui en dépend, à condition de conserver les mentions de droit d’auteur et de licence.
- Est-il encore maintenu ?
- Oui. Les derniers commits datent d’il y a 55 jours.
- En quel langage est-il écrit ?
- Principalement TypeScript, d’après les statistiques de langage de GitHub.
Ces réponses reposent sur les données GitHub du projet (dernière synchronisation le 15 septembre 2026) et sur notre analyse. Elles ne constituent pas un avis juridique.
ANALYSE OPEN SOURCE APPROFONDIE
Un cours qui se corrige par le commit, pas par le texte
La plupart des tutoriels sur les agents montrent du pseudo-code. Ici, le README annonce l'inverse : le code du cours est présenté comme un historique Git que l'on peut extraire, exécuter et vérifier, et non comme une démonstration. Chaque chapitre se referme sur quatre éléments, à savoir le texte de la leçon, un commit réel, un test ciblé et une expérience de panne. Le dépôt pi-textbook ne contient que le site HTML et le texte ; le code exécutable vit dans une branche distincte du dépôt pi, sous packages/pi-course/. Cette séparation est le premier point à comprendre avant de cloner quoi que ce soit, parce que cloner pi-textbook ne vous donne pas l'agent, seulement la documentation qui le décrit. Le parcours est en chinois, avec un README_EN.md en anglais pour la page d'accueil, et le site est consultable en ligne.
La chaîne d'exécution découpée en quinze arrêts
Les checkpoints 00 à 14 suivent une seule chaîne, dans un ordre qui n'est pas négociable. Le checkpoint 00 part d'une requête de lecture de README et relie message utilisateur, deux appels au modèle, appel d'outil, résultat et réponse finale. Les checkpoints 01 à 05 construisent la couche modèle et protocole : types TypeScript et validation à l'exécution autour de quatre DemoEvent, un EventStream qui doit livrer l'élément de progression et le résultat final quel que soit l'ordre d'arrivée, la sauvegarde d'un aller-retour d'outil sous forme de message unifié, un ScriptedModel qui rejoue des tours prédéfinis et conserve un instantané de la requête, puis un adaptateur qui traduit les messages du cours en requête fournisseur et reconvertit le flux SSE en événements normalisés. Les checkpoints 06 à 08 passent aux outils et à la boucle : une requête echo traverse schéma, registre et exécuteur en conservant le call id d'origine, la boucle appelle le modèle deux fois pour un aller-retour de lecture, et quatre outils (read, write, edit, bash) opèrent dans un même workspace. Les checkpoints 09 à 11 traitent l'état : agent avec messages persistants et gestion de l'abonnement, de l'annulation et des instructions en cours d'exécution, arbre de session en JSONL avec pointeurs parents et restauration depuis une feuille, puis compaction du contexte. Les checkpoints 12 à 14 ferment la boucle : découverte de règles de projet, de Skills et de modèles chargés à la demande, composition d'un Runtime complet, et évaluation sur des fixtures neuves.
La compaction du contexte, seul chapitre qui touche à l'économie de tokens
Le checkpoint 11 mérite qu'on s'y arrête, car c'est là que le cours prend une position de conception plutôt que de décrire une API. Le principe annoncé : l'historique ne bouge pas, le contexte est reconstruit selon un budget. La découpe se fait par interaction d'outil complète, jamais au milieu d'un échange, la queue de l'historique est conservée tant qu'elle tient dans le budget, et les faits anciens sont réinjectés sous forme de résumé structuré. C'est un choix défendable, mais il déplace le problème : la qualité du résumé devient le facteur limitant de la mémoire longue, et le cours ne prétend pas fournir de métrique sur ce point. Le checkpoint 10 pose la même question de façon plus concrète, en stockant les messages terminés comme enregistrements JSONL avec pointeur parent, ce qui permet de restaurer le chemin courant depuis une feuille donnée. Un arbre de session suppose que vous acceptez de gérer vous-même la sélection de branche ; aucune interface graphique ne le fait à votre place ici.
Mettre le cours en route : deux dépôts, deux commandes
Pour lire le site en local, le README donne trois commandes : git clone https://github.com/hahhforest/pi-textbook.git, puis cd pi-textbook, npm install et npm run dev. Pour manipuler le code du cours, il faut l'autre dépôt, avec la branche dédiée : git clone --branch course/build-your-own-pi https://github.com/hahhforest/pi.git, puis cd pi et npm install. Deux scripts npm structurent ensuite le travail. npm run checkpoint -w @pi/course -- 05 localise pour la leçon 05 le parent, la cible et les tests ciblés. npm run practice -w @pi/course -- 05 ../pi-practice-05 crée un répertoire d'exercice sans réponses ni historique Git. Le README précise que le fichier LEARNING.md de ce répertoire, la page du chapitre et la sortie des commandes sont censés être remis ensemble à un agent tuteur. Le cours part d'un commit amont figé, 8479bd84, et l'historique est organisé de course(00) à course(14), avec les tags pi-course-v1 et course-v1/00 à course-v1/14 qui figent la première version.
Ce que le dépôt ne fournit pas
Le point faible est le coût d'entrée non documenté. Le README ne liste ni version de Node requise, ni durée estimée par chapitre, ni prérequis autres que TypeScript. Il n'y a aucune release publiée, donc pas de version étiquetée du site à épingler ; seul l'historique de commits fait office de référence. La progression dépend d'un commit amont précis du dépôt pi, ce qui signifie qu'une évolution de ce dépôt peut compliquer le checkout de la base annoncée. Le contenu pédagogique est en chinois, sans indication d'une traduction anglaise du corps du texte, ce qui exclut de fait une partie des lecteurs. Enfin, le projet se déclare explicitement comme un cours communautaire non officiel, sans lien avec Pi ni Earendil Works : les questions sur les choix d'implémentation du cours ne remontent pas à l'équipe amont. Si vous cherchez un agent à intégrer dans un produit, ce dépôt n'est pas l'outil : il n'expose pas d'API stable, seulement une suite de checkpoints.
Face à un tutoriel d'agent classique
L'alternative la plus proche est le tutoriel d'agent qui fait installer un framework et enchaîner des appels d'API. La différence d'approche est nette : dans ce dernier cas, la boucle, la gestion des messages et la persistance sont fournies par la bibliothèque, et vous apprenez surtout à configurer. Ici, l'EventStream, le ScriptedModel, le contrat d'outil, la boucle et l'arbre de session sont écrits à la main, chapitre par chapitre, avec un test ciblé par étape. L'avantage est que les modes de défaillance deviennent visibles, notamment l'ordre d'arrivée des événements et l'appariement des call id. Le prix à payer est le temps : quinze checkpoints à écrire soi-même, contre quelques heures pour brancher un framework existant. Le ScriptedModel illustre bien ce compromis : il rend les tests reproductibles sans appel réseau, mais il ne dit rien du comportement réel d'un fournisseur sous charge.
Licences et maintenance : deux régimes à ne pas confondre
Le dépôt applique deux licences distinctes. L'application et le code original sont sous MIT License, tandis que le texte du cours et les médias originaux sont sous CC BY 4.0. Le code amont de Pi conserve sa propre licence et son attribution d'origine, détaillées dans LICENSE et LICENSE-CONTENT. Concrètement, réutiliser les exemples de code dans un projet interne relève de MIT, mais republier ou adapter le texte des leçons vous oblige à respecter les conditions de CC BY 4.0, attribution comprise. Pour la maintenance, les tags pi-course-v1 et course-v1/00 à course-v1/14 indiquent que la première version du cours est figée, ce qui limite le risque de dérive silencieuse : un lecteur peut revenir à un état connu. Le fichier CONTRIBUTING.md couvre la construction, les tests et la vérification d'historique entre dépôts. Le dernier push enregistré date du 23 juillet 2026. Ces éléments sont des constats de dépôt, pas un avis juridique : pour un usage commercial du texte, lisez LICENSE-CONTENT vous-même.
Conclusion éditoriale
Ce cours s'adresse aux développeurs TypeScript qui veulent comprendre la mécanique interne d'un agent de codage en lisant et exécutant du code, pas en assemblant des bibliothèques. Il n'est pas fait pour qui cherche un framework prêt à l'emploi, ni pour qui ne lit pas le chinois, car le corps du texte est en chinois et rien n'indique une traduction anglaise. Avant de vous engager, vérifiez trois choses concrètes : que npm install puis npm run dev se terminent sur votre machine, que npm run checkpoint -w @pi/course -- 05 affiche bien le parent, la cible et les tests de la leçon, et que le commit de base 8479bd84 du dépôt pi est toujours accessible, car toute la progression du cours en dépend.
Notes de la communauté