御舆 (Yùyú) : anatomie écrite d'un Agent Harness, pas un framework à installer
《御舆：解码 Agent Harness》42万字拆解 AI Agent 的Harness骨架与神经 —— Claude Code 架构深度剖析，15 章从对话循环到构建你自己的 Agent Harness。在线阅读网站：
En bref
- De quoi s’agit-il ?
- Le dépôt lintsinghua/claude-code-book est un livre technique chinois de 15 chapitres sur l'architecture de Claude Code, publié en Markdown et sous CC BY-NC-SA 4.0. Sa valeur est documentaire, pas opérationnelle : on y lit des mécanismes, pas un paquet à importer.
- À qui s’adresse-t-il ?
- À adopter si vous concevez un runtime d'agent et voulez une carte des sous-systèmes avant d'écrire la première ligne : lisez 01, 02, 04 puis 15, et gardez les annexes B et C comme tables de référence. À éviter si vous cherchez du code exécutable, un SDK ou une base de production : le dépôt ne contient pas d'implémentation réutilisable.
- Puis-je l’utiliser commercialement ?
- Pas sans autorisation. GitHub ne trouve aucun fichier de licence dans ce dépôt, et sans licence tous les droits sont réservés par défaut : vous pouvez lire le code, mais pas le réutiliser. Consultez le README ou demandez l’accord des auteurs avant de l’utiliser.
- Est-il encore maintenu ?
- Oui. Les derniers commits datent d’il y a 11 jours.
- En quel langage est-il écrit ?
- Principalement Python, 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 livre, pas une bibliothèque : ce que le dépôt contient réellement
Le README annonce 42万字 (420 000 caractères chinois), 15 chapitres et 4 annexes. La structure du dépôt le confirme : des dossiers nommés 第一部分-基础篇, 第二部分-核心系统篇, 第三部分-高级模式篇, 第四部分-工程实践篇, plus un dossier 附录. Le langage principal déclaré est Python, mais il faut être précis : Python sert ici à l'outillage du livre (scripts/check_book.py, tests unitaires), pas à un moteur d'agent. Il n'y a aucune release publiée dans les données fournies, donc aucun artefact versionné à installer.
Le public visé est celui qui écrit ou évalue un runtime d'agent : ingénieur plateforme, architecte outillage, développeur qui veut comprendre pourquoi une boucle d'agent se comporte mal en production. Le problème résolu est celui de l'opacité. Un harness d'agent est un empilement de sous-systèmes qui interagissent (boucle, outils, permissions, mémoire, contexte, hooks, MCP) et la documentation publique de ces systèmes est rare. Le livre propose une lecture organisée de cet empilement.
Le README prend une précaution méthodologique explicite : il demande de distinguer « 源码可确认的行为、架构推演和教学示例 », soit les comportements confirmables dans le code source, les déductions architecturales et les exemples pédagogiques. C'est une honnêteté rare dans ce genre d'ouvrage, et cela doit guider la lecture : tout ce qui est présenté comme inférence ne doit pas être traité comme un contrat d'API.
Le squelette décrit : boucle, outils, permissions, contexte
Le chapitre 02 décrit une boucle principale en générateur asynchrone `while(true)`, avec cinq types d'événements yield et dix raisons de terminaison. L'injection de dépendances passe par `QueryDeps`. Le chapitre 03 présente un protocole d'outil à cinq éléments, `Tool<I,O,P>`, une fabrique `buildTool` décrite comme tolérante aux pannes, plus de 45 outils répartis en 12 catégories, et un algorithme glouton de partitionnement pour la concurrence. Le chapitre 04 détaille un pipeline de permissions en quatre phases, cinq modes, un appariement de règles Bash et un classificateur spéculatif avec `Promise.race` sur 2 secondes.
Ces éléments dessinent une architecture où la boucle ne fait pas le travail : elle émet des événements, et ce sont les sous-systèmes qui décident. La permission est traitée comme une phase du flux, pas comme un filtre post-hoc. Le partitionnement glouton des outils indique que la concurrence est décidée par propriété déclarée (readOnly, destructive, concurrencySafe selon l'annexe B) et non par ordre d'appel.
Les chapitres 06 et 07 complètent le tableau avec quatre types de mémoire fermés et la règle « ne stocker que ce qui n'est pas dérivable », un index MEMORY.md, puis une formule de fenêtre effective et quatre niveaux de compaction progressive (Snip, MicroCompact, Collapse, AutoCompact) avec un mode disjoncteur. Le chapitre 08 recense cinq types de hooks, 26 événements de cycle de vie, un protocole de réponse JSON et six niveaux de priorité. Ce sont des choix de conception discutables : 26 événements, c'est une surface d'extension large qui devient difficile à tester exhaustivement.
Mise en route : lire, cloner, vérifier
Il n'y a rien à installer pour lire. Le README donne un ordre de lecture pour une première passe : 前言, puis 01 → 02 → 04 → 15. Pour une construction pratique, il renvoie d'abord aux parties 基础篇 et 工程实践篇, et aux parties 2 et 3 quand on ajoute mémoire et extensions. Une version web est disponible sur lintsinghua.github.io, et les liens de chapitres fonctionnent directement depuis le dépôt.
Si vous contribuez, l'outillage est explicite. Le README demande d'exécuter avant soumission :
python3 scripts/check_book.py python3 -m unittest discover -s tests
La vérification de la syntaxe Mermaid demande Node.js 22 ou supérieur, avec `npm ci` puis `npm run check:diagrams`. Les contributions passent par Issue ou PR, avec chapitre, section, modification proposée et source de référence ; pour un problème d'affichage, plateforme de lecture et étapes de reproduction. Le contenu bilingue impose de vérifier aussi la version anglaise (en/README.md).
Le README précise aussi que les fonctionnalités et la disponibilité des outils dépendent de la configuration de build et d'exécution, et que les exemples de volume ou de durée ne constituent pas un engagement de la version courante. Autrement dit : ne recopiez pas un chiffre du livre comme paramètre de production.
La limite structurelle : un livre sur un logiciel fermé
Le README est clair : Claude Code est un produit Anthropic, et le livre est une analyse technique indépendante, non une publication officielle. La licence du livre ne couvre pas le code source tiers. C'est la contrainte la plus lourde du projet. Un lecteur qui veut reproduire un comportement décrit au chapitre 04 doit le reconstruire à partir d'une description, pas d'un code de référence exécutable.
Deuxièmement, l'analyse est datée par construction. Le dépôt a reçu un push le 5 septembre 2026, mais un harness évolue : des outils apparaissent, des flags changent, des événements de hook se déplacent. L'annexe C recense 89 flags en 13 catégories, avec type compile-time ou runtime et graphe de dépendances. C'est utile comme photographie, dangereux comme spécification.
Troisièmement, le livre est en chinois. Le README signale une version anglaise, mais l'essentiel du contenu et de la terminologie (舆, 御舆, 护栏, 基因) est pensé en chinois. Un lecteur non sinophone perd une partie de la cohérence conceptuelle, même s'il peut suivre les schémas et le code cité.
Enfin, ce n'est pas l'outil adapté si vous cherchez à intégrer un agent dans une application existante. Aucun paquet, aucun point d'entrée, aucun exemple d'installation de dépendance n'apparaît dans le matériel fourni. Le chapitre 15 donne une feuille de route en six étapes pour construire son propre harness, pas un adaptateur.
Comparaison : lire une analyse contre lire un framework
L'alternative la plus directe n'est pas un concurrent nommé, c'est une catégorie : les frameworks d'agent open source qui fournissent du code exécutable et une documentation d'API. La différence d'approche est nette. Un framework vous donne une abstraction à appeler ; le livre vous donne une description de mécanismes à arbitrer. Avec un framework, vous héritez de ses choix (comment il compacte le contexte, comment il gère les permissions) sans les voir. Avec ce livre, vous voyez les choix décrits, mais vous devez les implémenter.
Le compromis est asymétrique. Si votre objectif est de livrer une fonctionnalité d'agent cette semaine, un framework est le bon choix et ce dépôt ne vous aidera pas directement. Si votre objectif est de décider comment structurer une boucle, où placer la vérification de permission, ou à quel moment compacter le contexte, la lecture est plus rentable qu'un framework dont vous ne contrôlez pas les décisions internes.
Un point de comparaison interne au livre : les chapitres 09 et 10 traitent des sous-agents et du modèle coordinateur-worker, avec une contrainte « n'orchestre pas, n'exécute pas » et quatre modes d'adressage. Ce sont des patterns d'architecture que peu de frameworks documentent explicitement, parce qu'ils sont souvent enfouis dans le code. Le livre les isole. C'est là son apport réel.
Licence, maintenance et coût de mise à jour
Le texte est sous CC BY-NC-SA 4.0 : attribution obligatoire, usage non commercial, partage des adaptations sous la même licence. Les ressources tierces conservent leurs droits et conditions d'origine. Concrètement, cela interdit de revendre le contenu ou de l'intégrer dans une formation payante sans accord, et impose de citer l'auteur et la source en cas de réutilisation. Ce n'est pas un avis juridique : si votre usage est commercial, lisez le texte de la licence et, le cas échéant, demandez une autorisation.
La maintenance repose sur des contributions bénévoles via Issue et PR. Le coût pour un contributeur est réel : il faut respecter le format bilingue, fournir chapitre, section, modification et source, et faire passer trois vérifications (check_book.py, unittest, Mermaid via Node.js 22). Le coût pour un lecteur est plus faible : suivre les mises à jour de chapitres précis, notamment ceux qui décrivent des flags et des listes d'outils, qui périment le plus vite.
Il n'y a pas de release dans les données fournies, donc pas de version sémantique à épingler. Si vous citez le livre dans un document interne, référencez le commit ou la date de consultation plutôt qu'un titre de chapitre seul. C'est la seule façon de rendre une affirmation traçable dans un dépôt sans tags.
Conclusion éditoriale
À adopter si vous concevez un runtime d'agent et voulez une carte des sous-systèmes avant d'écrire la première ligne : lisez 01, 02, 04 puis 15, et gardez les annexes B et C comme tables de référence. À éviter si vous cherchez du code exécutable, un SDK ou une base de production : le dépôt ne contient pas d'implémentation réutilisable. Vérifiez d'abord la licence exacte des fichiers que vous comptez réutiliser, puis exécutez python3 scripts/check_book.py et python3 -m unittest discover -s tests sur votre clone avant toute contribution.
Notes de la communauté