Pi Harness : architecture et frontières des extensions

Ce cas conserve la version de Pi et les dates d’observation indiquées ci-dessous. Le guide du harness présente les responsabilités communes ; cette page examine leur répartition dans une implémentation.

Pi : un harness minimal programmable

Pi se présente comme un harness minimal de code en terminal. Son noyau conserve les appels de modèles, la boucle d’agent, l’exécution des outils, les sessions arborescentes et l’interface terminal, puis confie les comportements propres à chaque workflow à des ressources composables. Par défaut, le modèle ne reçoit que read, write, edit et bash. grep, find et ls sont aussi intégrés, mais doivent être sélectionnés explicitement ou activés par la configuration.

Outre le TUI interactif, Pi offre la sortie ponctuelle -p, un flux d’événements JSON, un RPC sur stdin/stdout et un SDK pour intégrer l’agent à une application Node.js. Les fournisseurs de modèles peuvent être remplacés. Les sessions sont des arbres JSONL : /tree, /fork, /clone et /compact couvrent l’exploration dans un même fichier, les sessions séparées et la compression du contexte.

Les détails Pi ci-dessous ont été vérifiés le 2026-08-28 dans la documentation de Pi 0.84.3 installée localement. Ce sont des faits produit versionnés, pas une promesse de compatibilité permanente.

Rôle de chaque couche de personnalisation

Couche	Point d’entrée typique	Bon emplacement pour	À ne pas confondre avec
Contexte du projet	AGENTS.md, CLAUDE.md, .pi/SYSTEM.md	règles stables, périmètres de chemins, commandes d’acceptation	un plugin ou une sandbox
Prompt template	.pi/prompts/review.md → /review	une amorce répétable et paramétrée	un workflow exécuté automatiquement
Skill	.agents/skills/*/SKILL.md → /skill:name	procédures, scripts et références chargés à la demande	une frontière de permission ou un processus séparé
Extension	.pi/extensions/*.ts	outils, commandes, politiques d’événements, UI, providers et comportement de session	un « petit plugin » naturellement sûr
Package Pi	pi install ..., pi config	distribution d’extensions, skills, prompts et thèmes par npm, Git ou chemin local	isolation ou signature de confiance
SDK / RPC	createAgentSession(), pi --mode rpc	intégration, tests ou communication interprocessus entre langages	une couche obligatoire pour un dépôt ordinaire

Les ressources globales résident généralement sous ~/.pi/agent/, celles du projet sous .pi/ ou .agents/skills/. Un prompt développe du texte. Un skill applique la divulgation progressive : seuls son nom et sa description entrent par défaut dans le contexte. Une extension modifie directement le harness. Préférer un skill lorsqu’il manque une méthode, un prompt lorsqu’il manque une entrée réutilisable, et une extension seulement lorsqu’un nouvel outil, hook d’événement ou élément d’UI est réellement nécessaire.

Le déroulement vérifié des requêtes, du Steering, du Follow-up, de la compaction et des sessions de Pi est regroupé dans Boucles d’agent bornées. Une branche de session modifie la conversation vue par le modèle sans restaurer les fichiers sur disque ; les commandes ci-dessous restent ici comme référence pratique.

Extensions : la couche de plugins de Pi

Une extension est un module TypeScript chargé directement par Pi. Elle peut :

• enregistrer des outils appelables par le modèle et des commandes slash utilisateur ;
• intercepter tours du modèle, appels et résultats d’outils, changements de modèle et cycle de vie des sessions ;
• bloquer ou réécrire les appels dangereux et ajouter chemins protégés ou UI d’approbation ;
• personnaliser compaction, état de session, composants du terminal et rendu ;
• enregistrer des providers, ou implémenter MCP, sous-agents, plan mode et intégration sandbox.

Le dernier point est essentiel : des exemples ou packages tiers peuvent fournir ces fonctions, mais elles ne font pas partie des valeurs par défaut du noyau. Un petit noyau autorise plusieurs conceptions, tout en rendant l’installateur responsable de leurs politiques, de leur maintenance et de leur récupération après erreur.

Les extensions découvertes automatiquement vont dans ~/.pi/agent/extensions/ ou .pi/extensions/ d’un projet approuvé ; après modification, exécuter /reload. Pour un essai temporaire sans installation, utiliser pi -e ./extension.ts. Un package Pi peut distribuer ensemble extensions, skills, prompts et thèmes :

pi install npm:@scope/package@1.2.3  # fixer une version
pi install ./local-package -l        # portée projet
pi list
pi config                            # activer ou désactiver chaque ressource
pi update --extensions

Une extension exécute du code arbitraire avec les droits de l’utilisateur courant, et un skill peut demander au modèle d’exécuter des scripts inclus. Un package est donc une unité de distribution, pas une frontière de sécurité. Lire le code source et les dépendances avant installation, fixer les versions lorsque c’est utile et n’activer que les ressources nécessaires.

Usage quotidien

Un projet ordinaire n’a pas besoin d’un vaste plan de contrôle dès le premier jour :

Un petit projet peut n’utiliser que les fichiers nécessaires :

• AGENTS.md pour les règles et les commandes d’acceptation ;
• .pi/prompts/review.md pour un court prompt répété, si besoin ;
• .agents/skills/release/SKILL.md pour une procédure réutilisable facultative ;
• .pi/extensions/policy.ts uniquement lorsqu’une politique du host exige du code.

Modes de lancement courants :

cd my-project
pi --name "parser repair"             # session interactive
pi -c                                 # continuer la dernière session
pi --no-session -p "Summarize this repository"  # tâche ponctuelle éphémère

# Pour une revue, n’exposer que les outils en lecture seule
pi --no-session --tools read,grep,find,ls -p "Review the change"

# Ignorer la découverte et ne charger que la ressource testée
pi --no-extensions -e ./.pi/extensions/policy.ts
pi --no-skills --skill ./.agents/skills/release/SKILL.md

Premières commandes interactives à retenir :

Commande	Usage
/model	changer de modèle
/name, /session	nommer la session et inspecter fichier, tokens et coût
/tree	revenir à un nœud précédent et créer une branche dans le même JSONL
/fork, /clone	copier un point antérieur ou la branche active vers une nouvelle session
/compact	compresser avec perte l’ancien contexte ; l’historique complet reste dans le fichier de session
/reload	recharger extensions, skills, prompts, thèmes et fichiers de contexte
/skill:name, /template	charger explicitement un skill ou développer un prompt template

Socle de sécurité

La confiance accordée au projet décide si Pi charge les réglages .pi, les ressources et les extensions exécutables du projet. Ce n’est pas une sandbox réseau ou système de fichiers. Les modes non interactifs n’affichent pas la demande intégrée de confiance du projet ; l’automatisation doit donc prendre une décision --approve explicite plutôt que de faire confiance par défaut à tout dépôt.

Point de départ conservateur :

1. inspecter l’état Git, AGENTS.md et le périmètre d’écriture avant d’approuver les ressources du projet ;
2. utiliser --tools read,grep,find,ls pour une revue, puis élargir les outils seulement si l’écriture devient nécessaire ;
3. placer dépôts inconnus ou commandes dangereuses dans un conteneur ou une VM, en laissant identifiants, socket Docker et dossiers sans rapport à l’extérieur ;
4. construire un jeu minimal et reproductible avec --no-extensions, --no-skills et les options apparentées ;
5. auditer et fixer les packages tiers, en considérant toute extension comme du code disposant de tous les droits utilisateur ;
6. juger la réussite avec tests, lint, diff et état final des processus, pas avec l’affirmation du modèle qu’il a terminé.

C’est l’échange central entre Pi et les harnesses plus « produits » : son noyau est plus petit et plus malléable, mais politique de sécurité et qualité du workflow n’apparaissent pas automatiquement.

Pi et DeepSeek Harness : qui prend en charge la complexité ?

La vidéo de présentation de Pi et la vidéo sur DeepSeek Harness montrent des systèmes qui se ressemblent au premier abord. Tous deux peuvent changer de modèle, connecter des outils et ajouter des plugins. La distinction la plus utile ne concerne pas le nombre de fonctions, mais le moment où la complexité apparaît et la personne qui doit la gérer.

Pi part d’un petit noyau. Si l’utilisateur veut un mode plan, des sous-agents, MCP ou une interface spécialisée, il assemble cette capacité lorsqu’elle devient utile. Le système par défaut reste ainsi lisible, mais la compatibilité, les permissions et la maintenance incombent à l’utilisateur.

La vidéo sur DeepSeek Harness part au contraire de la formule « Everything is a plugin ». Modèles, outils, interfaces et workflows partagent une même surface de composition. Cette approche facilite la réutilisation des processus récurrents dans une équipe, tout en transférant la gestion des dépendances, des versions et du diagnostic à la plateforme de plugins.

Aucune approche ne supprime la complexité. Pi la retarde et la confie à la personne qui construit le workflow ; la conception montrée dans la vidéo sur DeepSeek Harness en concentre davantage dans la plateforme. Pour mon workflow actuel, Pi doit rester petit et compréhensible. Seules les capacités récurrentes et déjà stables méritent de devenir des composants communs. Un atelier de plugins devient utile lorsque ces composants sont trop nombreux pour être maintenus séparément.

Mes lectures · Les notes ouvertes sont mémorisées dans ce navigateur.