Référence du système d'outils

file_read

Capacités :

• Lit le contenu complet d'un fichier ou des plages de lignes spécifiques
• Essentiel pour comprendre le code avant toute modification
• Gestion efficace des gros fichiers grâce à la spécification de plages

Cas d'usage :

• Lire des fichiers de configuration avant de les modifier
• Comprendre les schémas d'implémentation existants
• Examiner des fichiers de test pour comprendre la couverture

Exemple :

# Read entire file
file_read("src/components/Button.tsx")

# Read specific range for large files
file_read("package-lock.json", start_line=1, max_lines=50)

file_edit

Capacités :

• Remplacement précis de texte par correspondance exacte de chaîne
• Opérations de remplacement multiples avec l'indicateur multiple
• Préserve la structure et le formatage du fichier

Cas d'usage :

• Mettre à jour des implémentations de fonctions
• Modifier des valeurs de configuration
• Renommer des variables dans plusieurs fichiers

Bonne pratique : À utiliser pour des changements ciblés. Pour des réécritures complètes, utilisez plutôt file_write.

file_write

Capacités :

• Créer de nouveaux fichiers depuis zéro
• Remplacer entièrement le contenu de fichiers existants
• Gérer tout format basé sur du texte

Cas d'usage :

• Générer de nouveaux composants ou modules
• Créer des fichiers de configuration
• Écrire des fichiers de test

Avertissement : Remplace entièrement les fichiers existants. Utilisez file_edit pour des modifications partielles.

glob

Capacités :

• Trouve des fichiers correspondant à des motifs : **/*.ts, src/**/*.js
• Filtre par chemin de répertoire
• Motifs d'exclusion pour affiner les résultats
• Contrôle du nombre de résultats

Cas d'usage :

• Trouver tous les composants d'un projet
• Localiser des fichiers de test
• Identifier des fichiers de configuration dans plusieurs répertoires

Exemples de motifs :

**/*.tsx          # All TypeScript React files
src/**/*.test.js  # All test files in src
**/config.*       # All config files anywhere

grep_content

Capacités :

• Recherche dans le contenu des fichiers à l'aide de motifs regex
• Affiche des lignes de contexte avant/après les correspondances (indicateurs -B, -A)
• Recherche insensible à la casse
• Filtrage par type de fichier via des motifs glob

Cas d'usage :

• Trouver des définitions de fonctions
• Localiser des implémentations de points de terminaison API
• Rechercher des messages d'erreur spécifiques
• Identifier des schémas de sécurité

Exemple :

# Find authentication-related code
grep_content("auth.*login", glob="**/*.ts")

# Search with context
grep_content("TODO", glob="src/**", context_before=2, context_after=2)

grep_file

Capacités :

• Liste les fichiers contenant des correspondances de motif
• Plus rapide que grep_content lorsque vous avez seulement besoin de l'emplacement des fichiers
• Prise en charge des motifs regex
• Filtrage glob par type de fichier

Cas d'usage :

• Identifier les fichiers à refactoriser
• Trouver les fichiers qui importent des modules spécifiques
• Localiser les fichiers contenant des schémas obsolètes

Bonne pratique : Utilisez d'abord grep_file pour identifier les fichiers pertinents, puis file_read pour un examen détaillé.

list_dir

Capacités :

• Affiche la hiérarchie des répertoires
• Contrôle de la profondeur avec le paramètre max_depth
• Motifs d'exclusion pour filtrer la sortie

Cas d'usage :

• Comprendre la structure d'un projet
• Vérifier l'organisation des répertoires
• Trouver des sous-répertoires spécifiques

bash

Capacités :

• Exécute des commandes shell
• Délai d'expiration maximal : 120 secondes (2 minutes, limite stricte)
• Enchaîne les commandes avec && pour gérer les dépendances
• Fournit des résumés descriptifs pour plus de clarté

Cas d'usage :

• Exécuter des tests
• Construire des projets
• Installer des dépendances
• Opérations Git
• Migrations de base de données

Exemple :

# Run tests
bash("npm test", timeout=60000, summary="Run Jest test suite")

# Chain dependent commands
bash("npm install && npm run build", timeout=120000)

Sécurité : Les commandes s'exécutent avec les permissions de l'utilisateur. Vérifiez les commandes dans Manual Accept Mode.

spawn_subagent

Capacités :

• Lance des sous-agents spécialisés avec des contextes isolés
• Types : explorer, verifier, code-reviewer
• Délègue des tâches complexes sans polluer le contexte principal
• Exécution parallèle de sous-agents pour plus d'efficacité

Cas d'usage :

• explorer : Rechercher des motifs dans de grandes bases de code
• verifier : Valider la logique d'implémentation
• code-reviewer : Évaluation de la sécurité et de la qualité

Bonne pratique : Déléguez les recherches exploratoires au sous-agent Explorer pour préserver le contexte de la conversation principale.

todo_update

Capacités :

• Créer et gérer des listes de tâches
• Mettre à jour le statut des tâches (pending, in_progress, completed)
• Suivre la progression au fil d'implémentations complexes

Cas d'usage :

• Décomposer des fonctionnalités multi-étapes
• Suivre la progression d'une refactorisation
• Gérer des tâches de migration

web_search

Capacités :

• Interroge des moteurs de recherche internet
• Contrôle du nombre de résultats
• Filtrage par fraîcheur (jours récents)

Cas d'usage :

• Trouver la documentation de APIs peu familiers
• Rechercher des messages d'erreur
• Vérifier les bonnes pratiques actuelles

web_fetch

Capacités :

• Récupère le contenu de pages web
• Analyse le contenu à l'aide de requêtes spécifiques
• Extrait des informations structurées

Cas d'usage :

• Lire des pages de documentation
• Analyser la documentation API
• Extraire des exemples depuis des tutoriels

Formats de données

Fichiers de build et de package

Efficacité de file_read

Bonnes pratiques :

• Utilisez des plages de lignes pour les fichiers de plus de 500 lignes afin d'éviter une surcharge du contexte
• Ne lisez que les sections pertinentes nécessaires à la tâche
• Pour les gros fichiers, utilisez d'abord grep_content pour identifier les numéros de lignes pertinents

# Good: Read specific section
file_read("large-config.json", start_line=100, max_lines=50)

# Less efficient: Read entire large file
file_read("large-config.json")  # May consume excessive context

Précision de file_edit

Bonnes pratiques :

• Assurez des correspondances exactes de chaîne pour éviter les échecs de modification
• Pour des changements multiples similaires, utilisez l'indicateur multiple=true
• Vérifiez les chemins de fichiers avant de les modifier

Sécurité de file_write

Bonnes pratiques :

• Vérifiez soigneusement les chemins pour éviter des remplacements accidentels
• À utiliser uniquement pour de nouveaux fichiers ou des réécritures complètes
• Pour des modifications, privilégiez file_edit par sécurité

Spécificité des motifs glob

Bonnes pratiques :

• Utilisez des motifs spécifiques pour restreindre la portée : src/**/*.ts plutôt que **/*
• Excluez des répertoires avec des motifs d'exclusion : !**/node_modules/**
• Limitez les résultats pour éviter une sortie excessive

# Good: Specific scope
glob("src/components/**/*.tsx", max_results=50)

# Less efficient: Too broad
glob("**/*")  # Returns thousands of results

Stratégie grep

Flux de travail recommandé :

1. Utilisez grep_file pour identifier les fichiers pertinents
2. Lisez les fichiers spécifiques avec file_read
3. Utilisez grep_content lorsque vous avez besoin du contexte environnant

Conseils de performance :

• Les motifs regex peuvent être plus lents que les chaînes littérales
• Les recherches insensibles à la casse sont plus lentes
• Limitez les lignes de contexte (-A, -B) au nécessaire

Bonnes pratiques pour bash

Exécution sécurisée des commandes :

• Fournissez des résumés clairs pour décrire les commandes
• Définissez des délais d'expiration appropriés pour les opérations longues
• Enchaînez les commandes dépendantes avec &&
• Examinez attentivement les commandes destructrices (rm, drop, truncate)

# Good: Clear summary, reasonable timeout
bash("npm run build", timeout=120000, summary="Build production bundle")

# Good: Chained dependencies
bash("npm install && npm run test", timeout=180000)

Considérations de sécurité

Règles de sécurité critiques :

• Les commandes s'exécutent avec les permissions de l'utilisateur
• Ne jamais exécuter de commandes non fiables
• Utilisez Manual Accept Mode pour la revue dans des bases de code partagées
• Évitez les commandes qui exposent des identifiants ou des données sensibles

Efficacité de la délégation aux sous-agents

Quand utiliser des sous-agents :

• Explorer : Recherches dans la base de code, questions d'architecture (préserve le contexte principal)
• Verifier : Vérifications rapides (validation isolée)
• Code-reviewer : Revues de sécurité et de qualité (analyse détaillée)
• General : Tâches complexes multi-étapes (exécution parallèle)

Bonne pratique : Déléguez les tâches exploratoires et de recherche à des sous-agents pour préserver le contexte de la conversation principale pour le travail de développement actif.

Gestion du contexte

Utilisation stratégique des outils :

• Lisez les fichiers de manière stratégique - uniquement ce qui est nécessaire
• Utilisez des sous-agents pour la recherche en arrière-plan
• Surveillez la consommation de contexte lors de sessions longues
• Décomposez les opérations complexes en étapes avec todo_update

Flux de travail efficaces :

1. Planification : Utilisez glob/grep pour identifier la portée
2. Lecture : Lisez uniquement les fichiers/sections pertinents
3. Exécution : Déléguez à des sous-agents lorsque c'est pertinent
4. Vérification : Vérifications rapides avec le sous-agent Verifier

Limites de taille de fichier

Gestion des gros fichiers : Les fichiers très volumineux (>10 000 lignes) doivent être lus par sections pour éviter :

• L'épuisement de la fenêtre de contexte
• Des temps de réponse lents
• Des problèmes de mémoire

Délais d'expiration par défaut des outils

Limites des outils :

• Délai d'expiration de Bash : 120 secondes (2 minutes) maximum
• Opérations sur les fichiers : Aucune limite de taille (les gros fichiers sont automatiquement lus par lots)
• Gestion des gros fichiers : Les fichiers >256 Ko ne renvoient que les 256 premiers Ko de contenu
• Résultats de recherche : Aucune limite sur les résultats de glob ou grep_content
• Sous-agents concurrents : Aucune limite sur l'exécution parallèle

Configuration des délais d'expiration :

• Définissez des délais d'expiration explicites pour les opérations longues
• Surveillez les processus bloqués
• Les commandes dépassant le délai de 2 minutes seront interrompues

Opérations concurrentes

Exécution parallèle : Plusieurs sous-agents peuvent s'exécuter en parallèle pour accélérer les opérations complexes. L'agent principal gère automatiquement la coordination.

Avantages en performance :

• Réduction du temps d'exécution total pour les tâches multi-étapes
• Utilisation efficace des ressources
• Orchestration automatique des tâches
• Aucune limite sur le nombre de sous-agents concurrents