Back to Docs
Guide technique

Flux de travail de découverte de fichiers

Guide technique complet du flux de travail AI en 5 étapes qui identifie et filtre les fichiers pertinents pour l'exécution de tâches.

12 min read

PlanToCode identifie les bons fichiers avant de planifier ou d'exécuter des commandes. Le flux de travail en 5 étapes réduit la portée et maintient le contexte serré.

Architecture du flux de travail

Le flux de travail fonctionne comme un système de tâches en arrière-plan orchestré avec cinq étapes distinctes qui s'exécutent séquentiellement. Chaque étape s'appuie sur la sortie de l'étape précédente, affinant progressivement la sélection de fichiers en fonction des exigences de la tâche.

Le système utilise une architecture de tâche distribuée où chaque étape s'exécute comme une tâche en arrière-plan indépendante, permettant l'annulation, la logique de nouvelle tentative et le suivi détaillé de la progression. Des événements en temps réel sont publiés tout au long de l'exécution pour fournir un retour immédiat à l'interface utilisateur.

Fonctionnalités clés de l'architecture :

  • Rapports de progression basés sur les événements avec des mises à jour de type WebSocket
  • Gestion complète des erreurs avec mécanismes de nouvelle tentative automatique
  • Suivi des coûts et gestion du délai d'attente pour les opérations AI
  • Mise en cache des résultats intermédiaires pour l'optimisation des performances
  • Intégration Git avec repli sur le parcours de répertoire

Processus de flux de travail en 5 étapes

Étape 1 : Sélection du dossier racine

Détermine le répertoire racine du projet et valide l'état du référentiel git. Cette étape établit le répertoire de base pour toutes les opérations de fichiers ultérieures et configure les modèles d'exclusion.

Détails techniques : Utilise la détection git avec repli sur la validation de répertoire, applique des modèles d'exclusion définis par l'utilisateur et établit le contexte du répertoire de travail pour l'ensemble du flux de travail.

Étape 2 : Filtre de fichiers Regex

Génère des modèles regex intelligents basés sur la description de la tâche pour effectuer un filtrage initial des fichiers. Cette étape combine la sortie git ls-files avec la détection de fichiers binaires pour créer une liste préliminaire de fichiers.

Intégration Git : Exécute `git ls-files --cached --others --exclude-standard` pour respecter les règles .gitignore tout en incluant les fichiers suivis et non suivis.
Détection binaire : Filtre les fichiers avec des extensions binaires (.jpg, .png, .pdf, .exe, etc.) et utilise l'analyse de contenu pour détecter les fichiers binaires par des octets nuls et des ratios de caractères non imprimables.

Étape 3 : Évaluation de la pertinence des fichiers par AI

Utilise des modèles AI pour analyser le contenu des fichiers et évaluer la pertinence par rapport à la description de tâche spécifique. Cette étape effectue une analyse approfondie du contenu pour identifier les fichiers les plus susceptibles d'être utiles pour la tâche donnée.

Traitement AI : Utilise de grands modèles de langage pour évaluer le contenu des fichiers par rapport aux exigences de la tâche, avec un regroupement intelligent pour gérer les limites de jetons et l'optimisation des coûts.

Étape 4 : Recherche de chemin étendu

Découvre des fichiers pertinents supplémentaires grâce à l'analyse de relations et au suivi des dépendances. Cette étape identifie les fichiers qui peuvent ne pas correspondre aux modèles initiaux mais qui sont contextuellement importants.

Analyse de relations : Analyse les instructions d'importation, les fichiers de configuration et la structure du projet pour trouver des fichiers connexes qui améliorent le contexte pour la tâche spécifique.

Options de configuration

Configuration du flux de travail

Gestion du délai d'attente

Configurer le temps d'exécution maximum pour l'ensemble du flux de travail ou des étapes individuelles pour éviter un blocage indéfini.

timeoutMs: 300000 // 5 minutes default

Modèles d'exclusion

Définir les répertoires et les modèles de fichiers à exclure du processus de découverte.

excludedPaths: ["node_modules", ".git", "dist", "build"]

Configuration de nouvelle tentative

Définir le nombre maximum de tentatives pour les étapes échouées avec un recul exponentiel.

maxRetries: 3 // Per stage retry limit

Exemples d'utilisation de l'API

Démarrage d'un flux de travail

const tracker = await WorkflowTracker.startWorkflow(
  sessionId,
  "Add user authentication to the login page",
  "/path/to/project",
  ["node_modules", "dist"],
  { timeoutMs: 300000 }
);

Surveillance de la progression

tracker.onProgress((state) => {
  console.log(`Stage: ${state.currentStage}`);
  console.log(`Progress: ${state.progressPercentage}%`);
});
tracker.onComplete((results) => {
  console.log(`Selected ${results.selectedFiles.length} files`);
});

Récupération des résultats

const results = await tracker.getResults();
const selectedFiles = results.selectedFiles;
const intermediateData = results.intermediateData;
const totalCost = results.totalActualCost;

Considérations de performance

Gestion de la mémoire

Le flux de travail implémente une gestion intelligente de la mémoire avec mise en cache de fichiers (TTL de 30 secondes), traitement par lots (100 fichiers par lot) et nettoyage automatique des données intermédiaires pour éviter l'épuisement de la mémoire.

Optimisation des coûts

Les étapes AI suivent les coûts réels à partir des réponses API, implémentent un regroupement intelligent pour minimiser l'utilisation des jetons et fournissent des estimations de coûts avant l'exécution pour aider à gérer les dépenses.

Surveillance des performances

Le suivi des performances intégré surveille les temps d'exécution, l'utilisation de la mémoire, les métriques de débit et fournit des recommandations d'optimisation basées sur l'analyse des données historiques.

Modèles d'intégration

Application de bureau

Le flux de travail s'intègre de manière transparente à l'application de bureau via les commandes Tauri, fournissant un accès natif au système de fichiers et des mises à jour basées sur les événements via la classe WorkflowTracker.

Intégration des plans d'implémentation

Les fichiers sélectionnés sont automatiquement alimentés dans le panneau Plans d'implémentation, garantissant que la génération de plan utilise le même contexte de fichier optimisé sans nécessiter de réexécution du flux de travail de découverte.

Gestion de session

Les résultats du flux de travail sont mis en cache par session, permettant à plusieurs opérations au sein de la même session de réutiliser le contexte de fichier découvert, améliorant considérablement les performances pour les flux de travail de développement itératifs.

Gestion des erreurs et dépannage

Problèmes courants

  • Référentiel Git introuvable : Repli sur le parcours de répertoire avec exclusions standard
  • Détection de fichier binaire : Utilise une détection basée sur l'extension et le contenu
  • Limite de jetons dépassée : Implémente un regroupement intelligent et fournit des messages d'erreur clairs
  • Délais d'attente réseau : Nouvelle tentative automatique avec recul exponentiel pour les échecs transitoires

Catégories d'erreurs

  • Erreurs de validation : ID de session non valide, description de tâche manquante ou répertoire de projet non valide
  • Erreurs de flux de travail : Échecs spécifiques à l'étape avec contexte détaillé et suggestions de nouvelle tentative
  • Erreurs de facturation : Crédits insuffisants ou échecs de paiement avec des conseils exploitables
  • Erreurs système : Accès au système de fichiers, échecs de commande git ou contraintes de mémoire

Outils de débogage

Le flux de travail fournit une journalisation complète, une exportation de métriques de performance et un contexte d'erreur détaillé incluant les informations d'étape, les tentatives de nouvelle tentative et les données intermédiaires pour le dépannage.

Gestion de l'état du flux de travail

Transitions d'état

Le flux de travail progresse à travers des états clairement définis : Créé → En cours → En pause (optionnel) → Terminé/Échoué/Annulé. Chaque transition d'état publie des événements qui peuvent être surveillés pour des mises à jour en temps réel.

Stockage de données intermédiaires

Chaque étape stocke sa sortie dans un format de données intermédiaires structuré, incluant le contenu de l'arborescence de répertoires, les modèles regex, les listes de fichiers filtrées et les résultats de correction de chemin. Ces données sont accessibles pour le débogage et peuvent être utilisées pour reprendre les flux de travail à partir d'étapes spécifiques.

Mises à jour basées sur les événements

Le système publie des événements en temps réel pour les changements d'état du flux de travail, les achèvements d'étape et les conditions d'erreur. Ces événements permettent des interfaces utilisateur réactives et l'intégration avec des systèmes de surveillance externes.

Besoin de l'application de bureau ?

Le flux de travail de découverte de fichiers s'exécute dans le client de bureau aux côtés de la planification d'implémentation et des sessions de terminal.

Découverte de fichiers - PlanToCode