Memory Import Processor

Le Memory Import Processor est une fonctionnalité qui vous permet de modulariser vos fichiers de contexte (par exemple, QWEN.md) en important du contenu depuis d’autres fichiers via la syntaxe @file.md.

Aperçu

Cette fonctionnalité vous permet de découper des fichiers de contexte volumineux (comme QWEN.md) en composants plus petits et plus faciles à gérer, qui peuvent être réutilisés dans différents contextes. Le processeur d’import prend en charge les chemins relatifs et absolus, avec des fonctionnalités de sécurité intégrées pour éviter les imports circulaires et garantir la sécurité d’accès aux fichiers.

Syntaxe

Utilisez le symbole @ suivi du chemin vers le fichier que vous souhaitez importer :

 
# Fichier principal QWEN.md
 
Ceci est le contenu principal.
 
@./components/instructions.md
 
Plus de contenu ici.
 
@./shared/configuration.md

Formats de Chemin Supportés

Chemins Relatifs

• @./file.md - Import depuis le même répertoire
• @../file.md - Import depuis le répertoire parent
• @./components/file.md - Import depuis un sous-répertoire

Chemins absolus

• @/absolute/path/to/file.md - Importer en utilisant un chemin absolu

Exemples

Import basique

 
# My QWEN.md
 
Bienvenue dans mon projet !
 
@./getting-started.md
 
## Fonctionnalités
 
@./features/overview.md

Imports imbriqués

Les fichiers importés peuvent eux-mêmes contenir des imports, créant ainsi une structure imbriquée :

 
# main.md
 
@./header.md
@./content.md
@./footer.md

 
# header.md
 
# En-tête du projet
 
@./shared/title.md

Fonctionnalités de sécurité

Détection des imports circulaires

Le processeur détecte automatiquement et empêche les imports circulaires :

 
# file-a.md
 
@./file-b.md
 
# file-b.md
 
@./file-a.md <!-- Ceci sera détecté et bloqué -->

Sécurité d’accès aux fichiers

La fonction validateImportPath garantit que les imports ne sont autorisés que depuis des répertoires spécifiés, empêchant l’accès à des fichiers sensibles en dehors de la portée autorisée.

Profondeur d’importation maximale

Pour éviter les récursions infinies, il existe une profondeur d’importation maximale configurable (par défaut : 5 niveaux).

Gestion des erreurs

Fichiers manquants

Si un fichier référencé n’existe pas, l’importation échouera proprement avec un commentaire d’erreur dans la sortie.

Erreurs d’accès aux fichiers

Les problèmes de permissions ou autres erreurs du système de fichiers sont gérés proprement avec des messages d’erreur appropriés.

Détection des régions de code

Le processeur d’importation utilise la bibliothèque marked pour détecter les blocs de code et les portions de code en ligne, garantissant que les imports @ à l’intérieur de ces régions sont correctement ignorés. Cela permet une gestion robuste des blocs de code imbriqués et des structures Markdown complexes.

Structure de l’Arbre d’Importation

Le processeur retourne un arbre d’importation qui montre la hiérarchie des fichiers importés. Cela aide les utilisateurs à déboguer les problèmes avec leurs fichiers de contexte en montrant quels fichiers ont été lus et leurs relations d’importation.

Exemple de structure d’arbre :

 Memory Files
 L project: QWEN.md
            L a.md
              L b.md
                L c.md
              L d.md
                L e.md
                  L f.md
            L included.md

L’arbre préserve l’ordre dans lequel les fichiers ont été importés et montre la chaîne d’importation complète à des fins de débogage.

Comparaison avec l’approche /memory de Claude Code (claude.md)

La fonctionnalité /memory de Claude Code (comme vu dans claude.md) produit un document plat et linéaire en concaténant tous les fichiers inclus, en marquant toujours les limites des fichiers avec des commentaires clairs et des noms de chemins. Elle ne présente pas explicitement la hiérarchie des imports, mais le LLM reçoit tous les contenus et chemins des fichiers, ce qui suffit pour reconstruire la hiérarchie si nécessaire.

Note : L’arbre des imports sert principalement à la clarté pendant le développement et a une pertinence limitée pour la consommation par le LLM.

Référence API

processImports(content, basePath, debugMode?, importState?)

Traite les instructions d’import dans le contenu d’un fichier de contexte.

Paramètres :

• content (string) : Le contenu à traiter pour les imports
• basePath (string) : Le chemin du répertoire où se trouve le fichier courant
• debugMode (boolean, optionnel) : Active ou non le logging de débogage (par défaut : false)
• importState (ImportState, optionnel) : État de suivi pour prévenir les imports circulaires

Retourne : Promise<ProcessImportsResult> - Objet contenant le contenu traité et l’arbre des imports

ProcessImportsResult

interface ProcessImportsResult {
  content: string; // Le contenu traité avec les imports résolus
  importTree: MemoryFile; // Structure arborescente représentant la hiérarchie des imports
}

MemoryFile

interface MemoryFile {
  path: string; // Le chemin du fichier
  imports?: MemoryFile[]; // Imports directs, dans l'ordre où ils ont été importés
}

validateImportPath(importPath, basePath, allowedDirectories)

Valide les chemins d’import pour s’assurer qu’ils sont sûrs et situés dans les répertoires autorisés.

Paramètres :

• importPath (string) : Le chemin d’import à valider
• basePath (string) : Le répertoire de base pour résoudre les chemins relatifs
• allowedDirectories (string[]) : Tableau des chemins de répertoires autorisés

Retourne : boolean - Indique si le chemin d’import est valide

findProjectRoot(startDir)

Recherche la racine du projet en cherchant un répertoire .git en remontant à partir du répertoire de départ donné. Implémentée comme une fonction async utilisant des APIs de système de fichiers non bloquantes pour éviter de bloquer la boucle d’événements de Node.js.

Paramètres :

• startDir (string) : Le répertoire à partir duquel commencer la recherche

Retourne : Promise<string> - Le répertoire racine du projet (ou le répertoire de départ si aucun .git n’est trouvé)

Bonnes pratiques

1. Utilise des noms de fichiers descriptifs pour les composants importés
2. Garde les imports peu profonds - évite les chaînes d’importation trop imbriquées
3. Documente ta structure - maintiens une hiérarchie claire des fichiers importés
4. Teste tes imports - assure-toi que tous les fichiers référencés existent et sont accessibles
5. Utilise des chemins relatifs quand c’est possible pour une meilleure portabilité

Dépannage

Problèmes courants

1. Import qui ne fonctionne pas : Vérifie que le fichier existe et que le chemin est correct
2. Avertissements d’import circulaire : Révise ta structure d’importation pour détecter les références circulaires
3. Erreurs de permission : Assure-toi que les fichiers sont lisibles et se trouvent dans des répertoires autorisés
4. Problèmes de résolution de chemin : Utilise des chemins absolus si les chemins relatifs ne se résolvent pas correctement

Mode débogage

Active le mode débogage pour voir les logs détaillés du processus d’import :

const result = await processImports(content, basePath, true);