filesystem-context

Ingénierie de Contexte Basée sur le Système de Fichiers

Utilisez le système de fichiers comme couche de débordement principale pour le contexte de l'agent, car les fenêtres de contexte sont limitées alors que les tâches nécessitent souvent plus d'informations que ce qui tient dans une seule fenêtre. Les fichiers permettent aux agents de stocker, récupérer et mettre à jour une quantité effectivement illimitée de contexte via une seule interface.

Privilégiez la découverte dynamique du contexte — extraire le contexte pertinent à la demande — plutôt que l'inclusion statique, car le contexte statique consomme des tokens indépendamment de la pertinence et empiète sur l'espace réservé aux informations spécifiques à la tâche.

Quand Activer

Activez cette compétence lorsque :

• Les sorties des outils gonflent la fenêtre de contexte
• Les agents doivent persister l'état sur de longues trajectoires
• Des sous-agents doivent partager des informations sans échange direct de messages
• Les tâches nécessitent plus de contexte que ce qui tient dans la fenêtre
• Vous construisez des agents qui apprennent et mettent à jour leurs propres instructions
• Vous implémentez des blocs-notes pour les résultats intermédiaires
• Les sorties du terminal ou les journaux doivent être accessibles aux agents

N'activez pas cette compétence pour les travaux adjacents gérés par d'autres compétences :

• Mémoire sémantique inter-sessions, suivi d'entités ou graphes de connaissances temporelles : memory-systems.
• Résumé de conversation, compaction ou formulation de transfert durable : context-compression.
• Tactiques d'efficacité des tokens ne nécessitant pas de stockage via fichiers : context-optimization.
• Conception de topologie multi-agent ou de protocole de transfert : multi-agent-patterns.
• Modifications de modèle qui évacuent le contenu de la fenêtre active elle-même : self-managed-context.

Concepts Fondamentaux

Diagnostiquez les échecs de contexte par rapport à ces quatre modes, car chacun nécessite un remède différent basé sur le système de fichiers :

1. Contexte manquant — l'information nécessaire est absente du contexte total disponible. Corrigez en persistant les sorties des outils et les résultats intermédiaires dans des fichiers afin que rien ne soit perdu.
2. Contexte sous-récupéré — le contenu récupéré ne parvient pas à encapsuler ce dont l'agent a besoin. Corrigez en structurant les fichiers pour une récupération ciblée (formats compatibles avec grep, en-têtes de section clairs).
3. Contexte sur-récupéré — le contenu récupéré dépasse largement ce qui est nécessaire, gaspillant des tokens et dégradant l'attention. Corrigez en déchargeant le contenu volumineux dans des fichiers et en renvoyant des références compactes.
4. Contexte enfoui — des informations de niche sont cachées dans de nombreux fichiers. Corrigez en combinant glob et grep pour une recherche structurelle avec la recherche sémantique pour les requêtes conceptuelles.

Utilisez le système de fichiers comme couche persistante qui répond aux quatre modes : écrivez une fois, stockez durablement, récupérez sélectivement.

Sujets Détaillés

Le Compromis entre Contexte Statique et Dynamique

Traitez le contexte statique (instructions système, définitions d'outils, règles critiques) comme un espace coûteux — il consomme des tokens à chaque tour, indépendamment de la pertinence. À mesure que les agents accumulent des capacités, le contexte statique croît et empiète sur les informations dynamiques.

Utilisez plutôt la découverte dynamique du contexte : incluez uniquement des pointeurs statiques minimaux (noms, descriptions d'une ligne, chemins de fichiers) et chargez le contenu complet avec des outils de recherche lorsque cela est pertinent. Cela est plus efficace en termes de tokens et améliore souvent la qualité des réponses en réduisant les informations contradictoires ou non pertinentes dans la fenêtre.

Acceptez le compromis : la découverte dynamique nécessite que le modèle reconnaisse quand il a besoin de plus de contexte. Les modèles frontières actuels gèrent bien cela, mais des modèles moins performants peuvent ne pas déclencher les chargements. En cas de doute, incluez de manière statique les contraintes critiques de sécurité ou d'exactitude.

Modèle 1 : Système de Fichiers comme Bloc-Notes

Redirigez les sorties volumineuses des outils vers des fichiers au lieu de les renvoyer directement dans le contexte, car une seule recherche web ou requête de base de données peut déverser des milliers de tokens dans l'historique des messages où ils persistent pendant toute la conversation.

Écrivez la sortie dans un fichier bloc-notes, extrayez un résumé compact et renvoyez une référence de fichier. L'agent utilise ensuite une récupération ciblée (grep pour les motifs, lecture avec plages de lignes) pour accéder uniquement à ce dont il a besoin.

def handle_tool_output(output: str, threshold: int = 2000) -> str:
    if len(output) < threshold:
        return output

    file_path = f"scratch/{tool_name}_{timestamp}.txt"
    write_file(file_path, output)

    key_summary = extract_summary(output, max_tokens=200)
    return f"[Output written to {file_path}. Summary: {key_summary}]"

Utilisez grep pour rechercher dans le fichier déchargé et read_file avec des plages de lignes pour récupérer des sections ciblées, car cela préserve la sortie complète pour une référence ultérieure tout en ne gardant qu'environ 100 tokens dans le contexte actif.

Modèle 2 : Persistance des Plans

Écrivez les plans dans le système de fichiers car les tâches à long terme perdent en cohérence lorsque les plans sortent de l'attention ou sont résumés. L'agent relit son plan à tout moment, restaurant ainsi la conscience de l'objectif et de la progression.

Stockez les plans dans un format structuré afin qu'ils soient à la fois lisibles par l'homme et analysables par la machine :

# scratch/current_plan.yaml
objective: "Refactoriser le module d'authentification"
status: en_cours
steps:
  - id: 1
    description: "Auditer les points d'accès d'authentification actuels"
    status: terminee
  - id: 2
    description: "Concevoir le nouveau flux de validation des jetons"
    status: en_cours
  - id: 3
    description: "Implémenter et tester les modifications"
    status: en_attente

Relisez le plan au début de chaque tour ou après tout rafraîchissement du contexte pour vous réorienter, car cela agit comme une "manipulation de l'attention par la récitation."

Modèle 3 : Communication entre Sous-Agents via le Système de Fichiers

Acheminez les résultats des sous-agents via le système de fichiers plutôt que par échange de messages, car les chaînes de messages à plusieurs sauts dégradent l'information par le résumé à chaque saut ("jeu du téléphone").

Faites en sorte que chaque sous-agent écrive directement dans son propre répertoire de travail. Le coordinateur lit ces fichiers directement, préservant la fidélité complète :

workspace/
  agents/
    agent_recherche/
      resultats.md
      sources.jsonl
    agent_code/
      modifications.md
      resultats_tests.txt
  coordinateur/
    synthese.md

Appliquez l'isolation des répertoires par agent pour éviter les conflits d'écriture et maintenir une propriété claire de chaque artefact de sortie.

Modèle 4 : Chargement Dynamique des Compétences

Stockez les compétences sous forme de fichiers et incluez uniquement les noms des compétences avec des descriptions brèves dans le contexte statique, car insérer toutes les instructions dans le prompt système gaspille des tokens et peut perturber le modèle avec des instructions contradictoires.

Compétences disponibles (charger avec read_file si pertinent) :
- optimisation-base-de-donnees : Réglage des requêtes et stratégies d'indexation
- conception-api : Meilleures pratiques REST/GraphQL
- strategies-test : Modèles de tests unitaires, d'intégration et e2e

Chargez le fichier de compétence complet (par exemple, competences/optimisation-base-de-donnees/SKILL.md) uniquement lorsque la tâche en cours l'exige. Cela convertit un coût de token statique O(n) en O(1) par tâche.

Modèle 5 : Persistance du Terminal et des Journaux

Persistez automatiquement les sorties du terminal dans des fichiers et utilisez grep pour une récupération sélective, car les sorties du terminal de processus de longue durée s'accumulent rapidement et le copier-coller manuel est sujet aux erreurs.

terminaux/
  1.txt    # Sortie de la session terminal 1
  2.txt    # Sortie de la session terminal 2

Interrogez avec un grep ciblé (grep -A 5 "erreur" terminaux/1.txt) au lieu de charger l'historique complet du terminal dans le contexte.

Modèle 6 : Apprentissage par Auto-Modification

Faites en sorte que les agents écrivent les préférences et modèles appris dans leurs propres fichiers d'instructions afin que les sessions suivantes chargent automatiquement ce contexte, au lieu de nécessiter des mises à jour manuelles du prompt système.

def remember_preference(key: str, value: str):
    preferences_file = "agent/preferences_utilisateur.yaml"
    prefs = load_yaml(preferences_file)
    prefs[key] = value
    write_yaml(preferences_file, prefs)

Protégez ce modèle avec une validation car l'auto-modification peut accumuler des instructions incorrectes ou contradictoires au fil du temps. Traitez-le comme expérimental — révisez périodiquement les préférences persistées.

Techniques de Recherche dans le Système de Fichiers

Combinez ls/list_dir, glob, grep et read_file avec des plages de lignes pour la découverte du contexte, car les modèles sont spécifiquement entraînés sur la navigation dans le système de fichiers et cette combinaison surpasse souvent la recherche sémantique pour le contenu technique où les motifs structurels sont clairs.

• ls / list_dir : Découvrir la structure des répertoires
• glob : Trouver des fichiers correspondant à des motifs (par exemple, **/*.py)
• grep : Rechercher le contenu des fichiers, renvoie les lignes correspondantes avec contexte
• read_file avec plages : Lire des sections spécifiques sans charger les fichiers entiers

Utilisez la recherche dans le système de fichiers pour les requêtes structurelles et de correspondance exacte, et la recherche sémantique pour les requêtes conceptuelles. Combinez les deux pour une découverte complète.

Conseils Pratiques

Quand Utiliser le Contexte du Système de Fichiers

Appliquez les modèles basés sur le système de fichiers lorsque la situation correspond à ces critères, car ils ajoutent des frais généraux d'E/S qui ne sont justifiés que par des économies de tokens ou des besoins de persistance :

Utilisez quand :

• Les sorties des outils dépassent ~2000 tokens
• Les tâches s'étendent sur plusieurs tours de conversation
• Plusieurs agents ont besoin d'un état partagé
• Les compétences ou instructions dépassent la taille confortable du prompt système
• Les journaux ou sorties du terminal nécessitent une interrogation sélective

Évitez quand :

• Les tâches sont terminées en un seul tour (frais généraux non justifiés)
• Le contexte tient confortablement dans la fenêtre (aucun problème à résoudre)
• La latence est critique (les E/S de fichiers ajoutent un délai mesurable)
• Le modèle ne dispose pas de capacités d'outils de système de fichiers

Organisation des Fichiers

Structurez les fichiers pour la découvrabilité par l'agent, car les agents naviguent en listant et en lisant les noms de répertoires :

projet/
  scratch/           # Fichiers de travail temporaires
    sorties_outils/  # Résultats volumineux des outils
    plans/           # Plans actifs et listes de contrôle
  memoire/           # Informations persistantes apprises
    preferences.yaml # Préférences utilisateur
    modeles.md       # Modèles appris
  competences/       # Définitions des compétences chargeables
  agents/            # Espaces de travail des sous-agents

Utilisez des conventions de nommage cohérentes et incluez des horodatages ou des identifiants dans les fichiers scratch pour la désambiguïsation.

Pour les boucles de recherche autonomes, stockez les preuves brutes récupérées sous l'exécution qui les a consommées, par exemple chercheur/executions/<id-execution>/sources/preuves/brut/. Ne laissez pas de vidanges de recherche brutes dans la racine du dépôt ; les artefacts à la racine deviennent difficiles à auditer et faciles à citer sans provenance.

Comptabilité des Tokens

Mesurez d'où proviennent les tokens avant et après l'application des modèles de système de fichiers, car optimiser sans mesure conduit à un effort gaspillé :

• Suivez le rapport contexte statique vs dynamique
• Surveillez les tailles des sorties des outils avant et après déchargement
• Mesurez la fréquence à laquelle le contexte chargé dynamiquement est réellement utilisé

Exemples

Exemple 1 : Déchargement de Sortie d'Outil

Entrée : La recherche web renvoie 8000 tokens
Avant : 8000 tokens ajoutés à l'historique des messages
Après :
  - Écrire dans scratch/resultats_recherche_001.txt
  - Retourner : "[Résultats dans scratch/resultats_recherche_001.txt. Résultat clé : La limite de débit de l'API est de 1000 req/min]"
  - L'agent grep le fichier lorsqu'il a besoin de détails spécifiques
Résultat : ~100 tokens dans le contexte, 8000 tokens accessibles à la demande

Exemple 2 : Chargement Dynamique de Compétence

Entrée : L'utilisateur demande des informations sur l'indexation de base de données
Contexte statique : "optimisation-base-de-donnees : Réglage des requêtes et indexation"
Action de l'agent : read_file("competences/optimisation-base-de-donnees/SKILL.md")
Résultat : Compétence complète chargée uniquement lorsque pertinente

Exemple 3 : Historique de Chat comme Référence de Fichier

Déclencheur : Limite de la fenêtre de contexte atteinte, résumé nécessaire
Action :
  1. Écrire l'historique complet dans historique/session_001.txt
  2. Générer un résumé pour la nouvelle fenêtre de contexte
  3. Inclure la référence : "Historique complet dans historique/session_001.txt"
Résultat : L'agent peut rechercher le fichier d'historique pour récupérer les détails perdus lors du résumé

Directives

1. Écrivez les sorties volumineuses dans des fichiers ; renvoyez des résumés et des références vers le contexte
2. Stockez les plans et l'état dans des fichiers structurés pour une relecture
3. Utilisez des espaces de travail de fichiers pour sous-agents au lieu de chaînes de messages
4. Chargez les compétences dynamiquement plutôt que de les insérer toutes dans le prompt système
5. Persistez les sorties du terminal et des journaux comme fichiers consultables
6. Combinez grep/glob avec la recherche sémantique pour une découverte complète
7. Organisez les fichiers pour la découvrabilité par l'agent avec un nommage clair
8. Mesurez les économies de tokens pour valider l'efficacité des modèles de système de fichiers
9. Implémentez le nettoyage des fichiers scratch pour éviter une croissance illimitée
10. Protégez les modèles d'auto-modification avec validation
11. Gardez les preuves brutes à côté de l'exécution, de l'évaluation et de la proposition qui les a utilisées

Pièges

1. Croissance illimitée du répertoire scratch : Les agents créent des fichiers temporaires sans nettoyage, consommant finalement de l'espace disque et rendant les listes de répertoires bruyantes. Implémentez une politique de conservation (basée sur l'âge ou le nombre) et exécutez un nettoyage aux limites de session.
2. Conditions de concurrence dans l'accès aux fichiers multi-agents : Des écritures simultanées sur le même fichier corrompent silencieusement l'état. Appliquez l'isolation des répertoires par agent ou utilisez des fichiers en ajout seul avec des entrées préfixées par agent.
3. Références de fichiers obsolètes après des déplacements/renommages : Les agents conservent des chemins de tours précédents qui n'existent plus après des refontes ou réorganisations de fichiers. Vérifiez toujours l'existence du fichier avant de lire un chemin mis en cache ; redécouvrez avec glob si la vérification échoue.
4. Fausses correspondances de motifs glob : Des motifs trop larges (par exemple, **/*) attirent des fichiers non pertinents dans le contexte, gaspillant des tokens et perturbant le modèle. Limitez les globs à des répertoires et extensions spécifiques.
5. Hypothèses sur la taille des fichiers : Lire un fichier sans vérifier sa taille peut déverser 100 000+ tokens dans le contexte en un seul appel d'outil. Vérifiez la taille du fichier avant de lire ; utilisez des lectures par plage de lignes pour les fichiers volumineux.
6. Absence de vérification d'existence de fichier : Les agents supposent que les fichiers existent des tours précédents, mais ils peuvent avoir été supprimés ou déplacés. Protégez toujours les lectures avec des vérifications d'existence et gérez les erreurs de fichier manquant avec élégance.
7. Dérive du format du bloc-notes : Les blocs-notes non structurés deviennent impossibles à analyser après de nombreuses écritures car les conventions de format s'érodent au fil des ajouts successifs. Définissez et appliquez un schéma (YAML, JSON, ou markdown structuré) dès la première écriture.
8. Chemins absolus codés en dur : Ils cassent lorsque les dépôts sont extraits à différents emplacements ou lors de l'exécution dans des conteneurs. Utilisez des chemins relatifs à partir de la racine du projet ou résolvez les chemins dynamiquement.

Intégration

Cette compétence est propriétaire du stockage de contexte basé sur les fichiers

…

[tronqué pour la traduction]