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 :
| Mode | Commande | Description | Cas d'utilisation |
|---|---|---|---|
| Mode interactif | pi (par défaut) | Interface TUI du terminal, conversation en temps réel, prend en charge toutes les fonctionnalités | Développement quotidien, programmation interactive |
| Mode impression | pi -p "prompt" | Questions-réponses ponctuelles, quitte après avoir affiché le résultat | Intégration de scripts, requêtes rapides |
| Mode JSON | pi --mode json | Tous les événements sont émis sous forme de lignes JSON, adaptées à l'analyse par programme | Intégration de la chaîne d'outils, analyse de données |
| Mode RPC | pi --mode rpc | Intégré via le protocole JSONL sur stdin/stdout | Communication 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'outil | Fonction | Exemple | Statut par défaut |
|---|---|---|---|
| read | Lire le contenu du fichier | L'IA lit src/main.ts pour comprendre la logique du code | Activé par défaut |
| write | Créer ou écraser des fichiers | L'IA crée un nouveau fichier ou réécrit l'intégralité du fichier | Activé par défaut |
| edit | Remplacer précisément le contenu d'un fichier | L'IA modifie quelques lignes de code dans une fonction | Activé par défaut |
| bash | Exécuter des commandes shell | L'IA exécute les tests, installe les dépendances et exécute lint | Activé par défaut |
| grep | Rechercher du texte dans les fichiers | L'IA recherche quels fichiers appellent une certaine fonction | Optional |
| trouver | Rechercher des fichiers par nom | L'IA trouve tous les fichiers nommés *.test.ts | Optional |
| ls | Lister le contenu d'un répertoire | L'IA consulte la structure des répertoires pour localiser les modules | Optional |
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'extension | Format de fichier | Objectif | Difficulté |
|---|---|---|---|
| Extensions | TypeScript(.ts) | Enregistrer des outils personnalisés, des écouteurs d'événements, des commandes et des composants d'interface utilisateur | Nécessite de la programmation |
| Compétences | Markdown(SKILL.md) | Fournit des instructions de flux de travail et des scripts pour des domaines spécialisés | Savoir écrire du Markdown suffit |
| Modèles de prompts | Markdown(.md) | Invites réutilisables avec prise en charge des paramètres | Le plus simple |
| Thèmes | JSON(.json) | Personnaliser le jeu de couleurs de l'interface du terminal | Simple |
| Paquets | projets npm/git | Empaqueter et partager les quatre types de ressources ci-dessus | Selon 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 :
| Niveau | Chemin | Portée | Priorité |
|---|---|---|---|
| Configuration globale | ~/.pi/agent/AGENTS.md | Tous les projets | Le plus bas, sert de référence générale |
| Configuration du projet | AGENTS.md ou CLAUDE.md dans le répertoire du projet et les répertoires parents | Projet actuel | Le 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.
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