Gestion du contexte de Pi Agent
La gestion du contexte est une compétence essentielle pour utiliser Pi Agent efficacement.
Ce chapitre explique comment contrôler le comportement de l'IA à l'aide de fichiers d'environnement et comment gérer le contexte de conversation.
Aperçu des fichiers de contexte
Pi Agent charge automatiquement les fichiers d'instructions du projet au démarrage, ce qui permet à l'IA de comprendre les conventions, les commandes et les préférences de votre projet.
Ces fichiers indiquent à l'IA « comment travailler dans ce projet ».
AGENTS.md / CLAUDE.md
Voici les fichiers de contexte les plus importants pour Pi Agent, chargés dans l'ordre suivant :
- ~/.pi/agent/AGENTS.md- Instructions globales, valables pour tous les projets
- Parcourir AGENTS.md ou CLAUDE.md dans les répertoires parents en remontant depuis le répertoire courant
- AGENTS.md ou CLAUDE.md dans le répertoire courant
Ce qui suit estAGENTS.mdun exemple complet placé dans le répertoire racine du projet :
Exemple
## Normes de code
- Tout le code utilise le mode strict de TypeScript
- Les fonctions doivent avoir des annotations de type de retour
- Utilisez ESLint et Prettier pour garder un style de code cohérent
## Flux de travail
- Exécutez `npm run check` pour vérifier après des modifications de code
- Exécutez `npm test` avant de valider pour vous assurer que les tests passent
- Ne lancez pas les migrations de base de données de production directement sur votre machine locale
## Notes de sécurité
- N'écrivez pas les clés API ou les mots de passe dans le code
- Utilisez des variables d'environnement pour la configuration sensible
## Style de réponse
- Gardez des réponses concises et ne sur-expliquez pas le code évident
- Lorsque des problèmes surviennent, proposez d'abord une correction, puis expliquez la cause
Après avoir mis à jour AGENTS.md, utilisez la commande/reloadpour recharger à chaud, pas besoin de redémarrer Pi Agent.
Si vous avez à la fois AGENTS.md et CLAUDE.md, Pi Agent chargera AGENTS.md en premier.
Si vous utilisiez auparavant Claude Code, vous pouvez réutiliser directement votre fichier CLAUDE.md existant.
Si AGENTS.override.md existe dans un répertoire, il sera chargé à la place des fichiers AGENTS.md et CLAUDE.md de ce répertoire.
Pour désactiver le chargement des fichiers de contexte, utilisez l'argument de ligne de commande:
$ pi --no-context-files $ pi -nc # 短形式
SYSTEM.md
SYSTEM.md est utilisé pour remplacer complètement le prompt système par défaut de Pi Agent. Si vous souhaitez uniquement ajouter du contenu, utilisez plutôt APPEND_SYSTEM.md.
Les deux ont des niveaux global et projet, avec les chemins et effets suivants :
| Fichier | Niveau | Effet |
|---|---|---|
| ~/.pi/agent/SYSTEM.md | Global | Remplace le prompt système par défaut |
| Racine du projet/.pi/SYSTEM.md | Projet | Remplace le prompt système par défaut |
| ~/.pi/agent/APPEND_SYSTEM.md | Global | Ajoute après le prompt système par défaut |
| Racine du projet/.pi/APPEND_SYSTEM.md | Projet | Ajoute après le prompt système par défaut |
Dans la plupart des cas, vous n'avez pas besoin de modifier le prompt système.
AGENTS.md peut déjà couvrir la grande majorité des besoins de personnalisation.
SYSTEM.md convient aux scénarios qui nécessitent une personnalisation approfondie du comportement de l'IA ; des modifications inappropriées peuvent affecter les performances de l'IA.
Compactage du contexte
Lorsqu'une conversation devient très longue, la fenêtre de contexte de l'IA se remplira progressivement.
Pi Agent résout ce problème grâce au compactage du contexte — il résume automatiquement le contenu antérieur de la conversation en un bref condensé, libérant ainsi de l'espace de contexte.
Compactage automatique
Par défaut, Pi Agent déclenche automatiquement le compactage lorsque le contexte s'approche de la limite du modèle.
Le comportement de compactage est~/.pi/agent/settings.jsoncontrôlé par la configuration de compactage dans :
Exemple
"compaction": {
"enabled": true,
"reserveTokens": 16384,
"keepRecentTokens": 20000
}
}
| Élément de configuration | Type | Valeur par défaut | Description |
|---|---|---|---|
| compaction.enabled | booléen | vrai | Indique s'il faut activer le compactage automatique |
| compaction.reserveTokens | nombre | 16384 | Nombre de jetons réservés aux réponses du LLM |
| compaction.keepRecentTokens | nombre | 20000 | Nombre de jetons récents à conserver non compressés |
La condition de déclenchement est lorsque les jetons de contexte dépassent l'espace disponible après soustraction de reserveTokens de contextWindow.
La vérification a lieu après chaque exécution d'outil terminée et avant l'envoi de la prochaine invite utilisateur.
Compactage manuel
Vous pouvez également déclencher manuellement le compactage à tout moment :
/compact
Lors du compactage, vous pouvez ajouter des instructions personnalisées pour indiquer à l'IA sur quoi se concentrer lors de la synthèse :
/compact 重点关注错误修复和 API 变更
Le compactage n'est irréversible que pour le contexte de conversation actuel.
Les messages originaux compressés sont toujours entièrement conservés dans le fichier de session. Utilisez /tree pour revenir au nœud avant le compactage afin de récupérer les détails.
Si vous souhaitez conserver une sauvegarde complète avant le compactage, /clone est recommandé.
/clone copie entièrement la branche active actuelle vers un nouveau fichier de session, adapté pour une sauvegarde avant le compactage.
/fork ne démarre qu'à partir d'un certain message utilisateur historique, et le contenu qui suit ne sera pas reporté dans la nouvelle session.
Affichage du processus d'inférence
Les modèles qui prennent en charge la sortie de raisonnement réfléchiront avant de répondre.
Vous pouvez contrôler l'affichage du processus de raisonnement via les paramètres suivants :
| Paramètre | Type | Valeur par défaut | Description |
|---|---|---|---|
| hideThinkingBlock | booléen | false | Masquer le processus de raisonnement et afficher uniquement la réponse finale |
| showCacheMissNotices | booléen | false | Afficher les invites en cas d'échec de cache, et afficher aussi les invites d'utilisation des tokens générées par la compaction et les résumés de branche |
UtilisezCtrl+Tpour basculer l'affichage/le masquage du processus de raisonnement à tout moment pendant la conversation.
Rechargement à chaud (/reload)
Le besoin de redémarrer après avoir modifié la configuration dépend de ce que vous avez changé.
Le tableau ci-dessous résume comment les modifications courantes prennent effet. Pour les éléments marqués « Non », exécutez simplement /reload :
| Élément modifié | Redémarrage requis ? | Description |
|---|---|---|
| AGENTS.md ou CLAUDE.md (fichiers de contexte) | non | Rechargez immédiatement après avoir exécuté /reload |
| Extensions | non | Rechargez immédiatement après avoir exécuté /reload |
| Compétences | non | Rechargez immédiatement après avoir exécuté /reload |
| Modèles de prompt | non | Rechargez immédiatement après avoir exécuté /reload |
| Fichiers de thème | non | Rechargez immédiatement après avoir exécuté /reload |
| Configuration des raccourcis clavier | non | Rechargez immédiatement après avoir exécuté /reload |
| Certains paramètres dans ~/.pi/agent/settings.json | Oui | Certaines configurations sont lues une seule fois au démarrage |
| Paquets d'extension nouvellement installés | Oui | Les dépendances des paquets sont résolues au démarrage |
| Identifiants auth.json | Oui | Les identifiants sont chargés au démarrage |
Affichage de l'utilisation du contexte
La barre d'état inférieure affiche en temps réel l'utilisation des jetons et le coût du contexte actuel.
Utilisez la commande/sessionpour afficher des informations plus détaillées :
/session
Exemple de sortie :
Session file: ~/.pi/agent/sessions/--Users-example-projects-example-demo--/2026-08-30T09-15-04-000Z_019fbb5d-7a2e-7f31-b5c4-1a2b3c4d5e6f.jsonl Session ID: abc123-def456 Messages: 42 Tokens: 85,432 Cost: $0.52 Current model: claude-sonnet-4-20250514Autres extensions