Concepts fondamentaux de Pi Agent

Avant d'utiliser officiellement Pi Agent, comprendre ses concepts clés et ses méthodes de travail peut vous aider à démarrer plus rapidement.


Comprendre Pi Agent en une phrase

Pi Agent est un assistant de programmation IA qui s'exécute dans le terminal.

Après le démarrage, vous verrez une interface semblable à un logiciel de chat. Saisissez des exigences en langage naturel, et l'IA peut lire votre code, exécuter des commandes et modifier des fichiers.


Quatre modes d'exécution

Pi Agent prend en charge quatre modes d'exécution pour s'adapter à différents scénarios :

ModeCommandeDescriptionCas d'utilisation
Mode interactifpi (par défaut)Interface TUI du terminal, conversation en temps réel, prend en charge toutes les fonctionnalitésDéveloppement quotidien, programmation interactive
Mode impressionpi -p "prompt"Questions-réponses ponctuelles, quitte après avoir affiché le résultatIntégration de scripts, requêtes rapides
Mode JSONpi --mode jsonTous les événements sont émis sous forme de lignes JSON, adaptées à l'analyse par programmeIntégration de la chaîne d'outils, analyse de données
Mode RPCpi --mode rpcIntégré via le protocole JSONL sur stdin/stdoutCommunication inter-processus, plugins d'éditeur

Le mode interactif démarre directement dans l'interface TUI :

$ pi
Pi Agent 0.1.x  |  ~/projects/example-demo
claude-sonnet-4  |  上下文 2%  |  $0.0000
>

Le mode Print quitte après avoir répondu, adapté pour être intégré dans des scripts :

$ pi -p "总结这个项目"
这是一个 TypeScript 命令行工具,核心逻辑位于 src/ 目录,包含会话管理、工具调度和扩展加载三个模块。
Tokens: 1.2k 输入 / 320 输出  |  费用 $0.0081

Le mode JSON produit chaque événement sous forme d'une ligne JSON, ce qui facilite l'analyse par les programmes :

$ pi --mode json -p "总结这个项目"
{"type":"session","id":"a1b2c3d4"}
{"type":"message_start","role":"assistant"}
{"type":"message_end","usage":{"input":1200,"output":320}}

Le mode RPC envoie et reçoit des messages JSONL via stdin/stdout pour les appels de plugins d'éditeur :

$ pi --mode rpc
{"id":1,"method":"prompt","params":{"message":"列出 src 目录"}}
{"id":1,"result":{"state":"idle","messages":2}}

En tant que débutant, vous passerez la plupart de votre temps à travailler en mode interactif.

Une fois que vous êtes expérimenté, le mode Print peut être utilisé pour l'automatisation de scripts.


Outils intégrés

Après le démarrage, Pi Agent fournit par défaut à l'IA les quatre outils intégrés suivants. De plus, trois outils en lecture seule — grep, find et ls — peuvent être activés en option :

Nom de l'outilFonctionExempleStatut par défaut
readLire le contenu du fichierL'IA lit src/main.ts pour comprendre la logique du codeActivé par défaut
writeCréer ou écraser des fichiersL'IA crée un nouveau fichier ou réécrit l'intégralité du fichierActivé par défaut
editRemplacer précisément le contenu d'un fichierL'IA modifie quelques lignes de code dans une fonctionActivé par défaut
bashExécuter des commandes shellL'IA exécute les tests, installe les dépendances et exécute lintActivé par défaut
grepRechercher du texte dans les fichiersL'IA recherche quels fichiers appellent une certaine fonctionOptional
trouverRechercher des fichiers par nomL'IA trouve tous les fichiers nommés *.test.tsOptional
lsLister le contenu d'un répertoireL'IA consulte la structure des répertoires pour localiser les modulesOptional

Les trois outils en lecture seule sont activés manuellement via le paramètre--tools, par exemplepi --tools read,grep,find,ls。


Système d'extension

Pi Agent étend ses fonctionnalités des cinq manières suivantes :

Méthode d'extensionFormat de fichierObjectifDifficulté
ExtensionsTypeScript(.ts)Enregistrer des outils personnalisés, des écouteurs d'événements, des commandes et des composants d'interface utilisateurNécessite de la programmation
CompétencesMarkdown(SKILL.md)Fournit des instructions de flux de travail et des scripts pour des domaines spécialisésSavoir écrire du Markdown suffit
Modèles de promptsMarkdown(.md)Invites réutilisables avec prise en charge des paramètresLe plus simple
ThèmesJSON(.json)Personnaliser le jeu de couleurs de l'interface du terminalSimple
Paquetsprojets npm/gitEmpaqueter et partager les quatre types de ressources ci-dessusSelon les besoins

En tant que débutant, vous n'avez pas besoin de comprendre immédiatement toutes les méthodes d'extension.

Commencez par l'utilisation de base, puis explorez progressivement le système d'extension à mesure que vos besoins augmentent.


Ordre de chargement des fichiers

Lorsque Pi Agent démarre, il charge automatiquement les fichiers d'instructions du projet, ce qui vous permet de définir le comportement attendu pour l'IA :

NiveauCheminPortéePriorité
Configuration globale~/.pi/agent/AGENTS.mdTous les projetsLe plus bas, sert de référence générale
Configuration du projetAGENTS.md ou CLAUDE.md dans le répertoire du projet et les répertoires parentsProjet actuelLe plus élevé, peut remplacer les instructions globales

La configuration au niveau du projet est chargée en remontant depuis le répertoire parent, puis fusionnée avec la configuration du répertoire courant.

Si vous avez déjà utilisé Claude Code, vous pouvez réutiliser directement les fichiers CLAUDE.md existants ; Pi Agent les reconnaîtra et les chargera automatiquement.


Sessions et branches

Le système de sessions de Pi Agent est l'une de ses fonctionnalités les plus distinctives.

Chaque conversation est automatiquement enregistrée en tant que fichier de session, stocké dans~/.pi/agent/sessions/le répertoire.

En interne, les sessions utilisent une structure arborescente : vous pouvez « créer des branches » vers de nouvelles directions d'exploration à partir de n'importe quel nœud historique sans perdre les conversations précédentes.

Pi Agent 会话树分叉结构示意

C'est très utile lorsque vous devez expérimenter différentes approches d'implémentation — chaque piste de réflexion peut être conservée indépendamment et revisitée à tout moment.

Autres extensions