Gestion des fichiers

Description

Guide complet pour créer, lire, modifier, organiser, supprimer et déplacer des fichiers sur le système de l'utilisateur — couvrant les six outils de fichiers, l'intégration shell, les stratégies de sauvegarde et la sensibilité aux fichiers protégés.

Déclencheurs

• créer un fichier
• écrire un fichier
• modifier un fichier
• supprimer un fichier
• déplacer un fichier
• renommer
• organiser les fichiers
• sauvegarde
• copier
• trouver des fichiers
• rechercher des fichiers
• répertoire
• dossier
• nettoyage
• espace disque

Instructions

1. Sélection de l'outil

EloPhanto dispose de six outils de fichiers dédiés. Utilisez le bon :

Règle : Préférez toujours les outils de fichiers dédiés à shell_execute. N'utilisez shell_execute que pour les opérations qui nécessitent des fonctionnalités shell (pipes, globbing, find + exec, xargs, etc.).

2. Lire des fichiers

Lecture simple

file_read(path="/path/to/file.txt")
→ retourne : contenu, size_bytes, line_count

Lecture ciblée (fichiers volumineux)

file_read(path="/path/to/large.log", start_line=100, end_line=150)
→ retourne uniquement les lignes 100-150

Quand utiliser les plages de lignes :

• Le fichier fait plus de ~1000 lignes
• Vous connaissez la section dont vous avez besoin (par exemple, bloc de config, définition de fonction)
• Vous avez déjà lu le fichier une fois et devez relire une section spécifique

Quand utiliser la lecture complète :

• Le fichier est petit/moyen (moins de 1000 lignes)
• Vous devez comprendre le contexte complet
• C'est la première fois que vous lisez le fichier

3. Lister les répertoires

Listing basique

file_list(path="/home/user/projects")
→ retourne les entrées avec nom, chemin, type, taille, date de modification

Récursif avec motif

file_list(path="/home/user/project", recursive=true, pattern="*.py")
→ trouve tous les fichiers Python dans l'arborescence du projet

Inclure les fichiers cachés

file_list(path="/home/user", include_hidden=true)
→ inclut les .dotfiles et .répertoires

Stratégie pour trouver des fichiers :

1. Commencez par file_list dans le répertoire parent probable
2. Si non trouvé, élargissez avec recursive=true
3. Si vous connaissez l'extension, utilisez le filtrage par motif
4. Pour les recherches complexes (regex, basées sur le contenu), utilisez shell_execute avec find/grep

4. Écrire des fichiers

Nouveau fichier

file_write(path="/path/to/new_file.py", content="...")
→ Crée automatiquement les répertoires parents
→ Retourne : chemin, size_bytes

Remplacer (avec sauvegarde)

file_write(path="/path/to/existing.txt", content="nouveau contenu")
→ Crée automatiquement une sauvegarde .bak de l'original
→ Retourne : chemin, size_bytes, backed_up=true

Remplacer (sans sauvegarde)

file_write(path="/path/to/temp.txt", content="données", backup=false)
→ Remplace sans créer de .bak

Bonnes pratiques :

• Lisez toujours un fichier avant de le remplacer — comprenez ce que vous remplacez
• Pour les petites modifications de fichiers volumineux, lisez le fichier, modifiez le contenu dans votre raisonnement, puis écrivez le fichier complet
• Utilisez backup=true (par défaut) pour les fichiers importants, backup=false pour les fichiers temporaires/générés
• create_directories=true (par défaut) crée les répertoires parents — pas besoin de mkdir d'abord

5. Déplacer et renommer

Renommer un fichier

file_move(source="/path/to/old_name.txt", destination="/path/to/new_name.txt")

Déplacer vers un autre répertoire

file_move(source="/path/to/file.txt", destination="/new/location/file.txt")
→ Crée /new/location/ s'il n'existe pas

Remplacer la destination

file_move(source="/path/to/new.txt", destination="/path/to/existing.txt", overwrite=true)
→ Remplace la destination

Attention : Déplacer un fichier avec overwrite=true remplace définitivement la destination. Il n'y a pas de sauvegarde .bak pour les déplacements.

6. Supprimer des fichiers

Supprimer un seul fichier

file_delete(path="/path/to/file.txt")
→ Retourne : chemin supprimé, type, size_bytes

Supprimer un répertoire vide

file_delete(path="/path/to/empty_dir")
→ Échoue si le répertoire n'est pas vide

Supprimer un répertoire avec contenu

file_delete(path="/path/to/dir", recursive=true)
→ Supprime tout à l'intérieur, puis le répertoire lui-même
→ C'EST IRRÉVERSIBLE — confirmez d'abord avec l'utilisateur

Règles de sécurité :

• Ne supprimez jamais avec recursive=true sans confirmer avec l'utilisateur
• Vérifiez le contenu d'un répertoire (file_list) avant de le supprimer
• Les fichiers protégés (core/executor.py, core/vault.py, etc.) ne peuvent pas être supprimés

7. Fichiers protégés

Les fichiers suivants sont protégés et NE PEUVENT PAS être modifiés, déplacés ou supprimés par aucun outil :

• core/protected.py
• core/executor.py
• core/vault.py
• core/config.py
• core/registry.py
• core/log_setup.py
• permissions.yaml

Si une tâche nécessite de modifier ces fichiers, expliquez à l'utilisateur quel changement est nécessaire et laissez-le le faire manuellement.

8. Intégration shell pour les opérations complexes

Utilisez shell_execute quand les outils de fichiers dédiés ne suffisent pas :

Opérations en masse

shell_execute(command="find /path -name '*.log' -mtime +30 -delete")
→ Supprime tous les fichiers .log de plus de 30 jours

Recherche de contenu

shell_execute(command="grep -r 'TODO' /path/to/project --include='*.py'")
→ Trouve tous les commentaires TODO dans les fichiers Python

Utilisation du disque

shell_execute(command="du -sh /path/to/dir/*")
→ Taille de chaque sous-répertoire

Comparaison de fichiers

shell_execute(command="diff /path/to/file1 /path/to/file2")
→ Affiche les différences entre deux fichiers

Permissions

shell_execute(command="chmod 755 /path/to/script.sh")
→ Rend un script exécutable

9. Modèles courants

Mise à jour sécurisée d'un fichier

1. file_read de l'original
2. Modifiez le contenu dans votre raisonnement
3. file_write avec backup=true
4. file_read à nouveau pour vérifier que l'écriture a réussi

Organisation des répertoires

1. file_list(recursive=true) pour comprendre la structure actuelle
2. Planifiez la réorganisation
3. Créez les répertoires de destination (file_write crée automatiquement les parents)
4. file_move chaque fichier vers son nouvel emplacement
5. file_delete les répertoires sources vides
6. file_list pour vérifier le résultat

Nettoyage / libération d'espace disque

1. shell_execute(command="du -sh /path/*") pour trouver les grands répertoires
2. file_list avec motif pour identifier les fichiers supprimables (logs, caches, temp)
3. Confirmez le plan avec l'utilisateur
4. file_delete chaque cible (ou shell_execute pour les opérations en masse)
5. shell_execute(command="df -h") pour confirmer l'espace récupéré

Vérifier

• L'agent/l'outil/le canal destinataire a réellement reçu le message ; un accusé de réception, un ID de message ou une charge utile de réponse est capturé
• L'identité, les portées et les permissions utilisées par l'appel étaient le minimum requis ; les jetons surprivégiés sont signalés
• La gestion des défaillances a été exercée : au moins un chemin retry/timeout/permission-denied est montré pour se comporter comme prévu
• Le contexte transmis au prochain acteur est suffisamment complet pour que le récepteur puisse agir sans question de suivi
• Tout état muté (config, mémoire, queue, fichier) est listé avec les valeurs avant/après, pas juste « mis à jour »
• Les matériaux sensibles (clés, tokens, PII) ont été supprimés des logs/transcriptions partagés dans les preuves de vérification

Notes

Tous les chemins de fichiers peuvent être absolus ou relatifs à la racine du projet. Le caractère ~ est développé en le répertoire personnel de l'utilisateur. L'agent fonctionne avec les mêmes permissions du système de fichiers que l'utilisateur qui l'a lancé.