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 :

  1. ~/.pi/agent/AGENTS.md- Instructions globales, valables pour tous les projets
  2. Parcourir AGENTS.md ou CLAUDE.md dans les répertoires parents en remontant depuis le répertoire courant
  3. 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

# Instructions du projet

## 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 :

FichierNiveauEffet
~/.pi/agent/SYSTEM.mdGlobalRemplace le prompt système par défaut
Racine du projet/.pi/SYSTEM.mdProjetRemplace le prompt système par défaut
~/.pi/agent/APPEND_SYSTEM.mdGlobalAjoute après le prompt système par défaut
Racine du projet/.pi/APPEND_SYSTEM.mdProjetAjoute 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 configurationTypeValeur par défautDescription
compaction.enabledbooléenvraiIndique s'il faut activer le compactage automatique
compaction.reserveTokensnombre16384Nombre de jetons réservés aux réponses du LLM
compaction.keepRecentTokensnombre20000Nombre 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ètreTypeValeur par défautDescription
hideThinkingBlockbooléenfalseMasquer le processus de raisonnement et afficher uniquement la réponse finale
showCacheMissNoticesbooléenfalseAfficher 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)nonRechargez immédiatement après avoir exécuté /reload
ExtensionsnonRechargez immédiatement après avoir exécuté /reload
CompétencesnonRechargez immédiatement après avoir exécuté /reload
Modèles de promptnonRechargez immédiatement après avoir exécuté /reload
Fichiers de thèmenonRechargez immédiatement après avoir exécuté /reload
Configuration des raccourcis claviernonRechargez immédiatement après avoir exécuté /reload
Certains paramètres dans ~/.pi/agent/settings.jsonOuiCertaines configurations sont lues une seule fois au démarrage
Paquets d'extension nouvellement installésOuiLes dépendances des paquets sont résolues au démarrage
Identifiants auth.jsonOuiLes 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-20250514
Autres extensions