Flujo de trabajo de descubrimiento de archivos
Guía técnica completa del flujo de trabajo de IA de 5 etapas que identifica y filtra archivos relevantes para la ejecución de tareas.
PlanToCode identifica los archivos correctos antes de planificar o ejecutar comandos. El flujo de trabajo de 5 etapas reduce el alcance y mantiene el contexto ajustado.
Arquitectura del flujo de trabajo
El flujo de trabajo opera como un sistema de trabajos en segundo plano orquestado con cinco etapas distintas que se ejecutan secuencialmente. Cada etapa se construye sobre la salida de la etapa anterior, refinando progresivamente la selección de archivos según los requisitos de la tarea.
El sistema utiliza una arquitectura de trabajos distribuidos donde cada etapa se ejecuta como un trabajo en segundo plano independiente, permitiendo cancelación, lógica de reintento y seguimiento detallado del progreso. Los eventos en tiempo real se publican durante toda la ejecución para proporcionar retroalimentación inmediata a la interfaz de usuario.
Características clave de la arquitectura:
- • Informes de progreso basados en eventos con actualizaciones tipo WebSocket
- • Manejo integral de errores con mecanismos de reintento automáticos
- • Seguimiento de costos y gestión de tiempos de espera para operaciones de IA
- • Almacenamiento en caché de resultados intermedios para optimización del rendimiento
- • Integración con Git con respaldo a recorrido de directorios
Proceso de flujo de trabajo de 5 etapas
Etapa 1: Selección de carpeta raíz
Determina el directorio raíz del proyecto y valida el estado del repositorio git. Esta etapa establece el directorio base para todas las operaciones de archivo subsiguientes y configura patrones de exclusión.
Etapa 2: Filtro de archivos por regex
Genera patrones regex inteligentes basados en la descripción de la tarea para realizar el filtrado inicial de archivos. Esta etapa combina la salida de git ls-files con detección de archivos binarios para crear una lista preliminar de archivos.
Etapa 3: Evaluación de relevancia de archivos con IA
Emplea modelos de IA para analizar el contenido del archivo y evaluar la relevancia para la descripción específica de la tarea. Esta etapa realiza un análisis de contenido profundo para identificar archivos que probablemente sean útiles para la tarea dada.
Etapa 4: Buscador de rutas extendidas
Descubre archivos relevantes adicionales a través del análisis de relaciones y seguimiento de dependencias. Esta etapa identifica archivos que podrían no coincidir con patrones iniciales pero son contextualmente importantes.
Opciones de configuración
Configuración del flujo de trabajo
Gestión de tiempos de espera
Configura el tiempo máximo de ejecución para todo el flujo de trabajo o etapas individuales para evitar bloqueos indefinidos.
timeoutMs: 300000 // 5 minutes defaultPatrones de exclusión
Define directorios y patrones de archivo para excluir del proceso de descubrimiento.
excludedPaths: ["node_modules", ".git", "dist", "build"]Configuración de reintentos
Establece intentos máximos de reintento para etapas fallidas con retroceso exponencial.
maxRetries: 3 // Per stage retry limitEjemplos de uso de API
Inicio de un flujo de trabajo
const tracker = await WorkflowTracker.startWorkflow(
sessionId,
"Add user authentication to the login page",
"/path/to/project",
["node_modules", "dist"],
{ timeoutMs: 300000 }
);Monitoreo del progreso
tracker.onProgress((state) => {
console.log(`Stage: ${state.currentStage}`);
console.log(`Progress: ${state.progressPercentage}%`);
});
tracker.onComplete((results) => {
console.log(`Selected ${results.selectedFiles.length} files`);
});Recuperación de resultados
const results = await tracker.getResults(); const selectedFiles = results.selectedFiles; const intermediateData = results.intermediateData; const totalCost = results.totalActualCost;
Consideraciones de rendimiento
Gestión de memoria
El flujo de trabajo implementa gestión inteligente de memoria con almacenamiento en caché de archivos (TTL de 30 segundos), procesamiento por lotes (100 archivos por lote) y limpieza automática de datos intermedios para evitar el agotamiento de la memoria.
Optimización de costos
Las etapas de IA rastrean los costos reales de las respuestas de API, implementan agrupación inteligente para minimizar el uso de tokens y proporcionan estimaciones de costos antes de la ejecución para ayudar a gestionar los gastos.
Monitoreo del rendimiento
El seguimiento de rendimiento integrado monitorea tiempos de ejecución, uso de memoria, métricas de rendimiento y proporciona recomendaciones para la optimización basadas en el análisis de datos históricos.
Patrones de integración
Aplicación de escritorio
El flujo de trabajo se integra perfectamente con la aplicación de escritorio a través de comandos Tauri, proporcionando acceso nativo al sistema de archivos y actualizaciones basadas en eventos a través de la clase WorkflowTracker.
Integración de planes de implementación
Los archivos seleccionados se alimentan automáticamente al panel de Planes de Implementación, asegurando que la generación del plan utilice el mismo contexto de archivo optimizado sin requerir la re-ejecución del flujo de trabajo de descubrimiento.
Gestión de sesiones
Los resultados del flujo de trabajo se almacenan en caché por sesión, permitiendo que múltiples operaciones dentro de la misma sesión reutilicen el contexto de archivo descubierto, mejorando significativamente el rendimiento para flujos de trabajo de desarrollo iterativo.
Manejo de errores y solución de problemas
Problemas comunes
- • Repositorio Git no encontrado: Recurre al recorrido de directorios con exclusiones estándar
- • Detección de archivos binarios: Usa detección basada en extensión y contenido
- • Límite de tokens excedido: Implementa agrupación inteligente y proporciona mensajes de error claros
- • Tiempos de espera de red: Reintento automático con retroceso exponencial para fallos transitorios
Categorías de error
- • Errores de validación: ID de sesión inválido, descripción de tarea faltante o directorio de proyecto inválido
- • Errores de flujo de trabajo: Fallos específicos de etapa con contexto detallado y sugerencias de reintento
- • Errores de facturación: Créditos insuficientes o fallos de pago con orientación accionable
- • Errores del sistema: Acceso al sistema de archivos, fallos de comandos git o restricciones de memoria
Herramientas de depuración
El flujo de trabajo proporciona registro completo, exportación de métricas de rendimiento y contexto de error detallado que incluye información de etapa, intentos de reintento y datos intermedios para solucionar problemas.
Gestión del estado del flujo de trabajo
Transiciones de estado
El flujo de trabajo progresa a través de estados claramente definidos: Creado → En ejecución → Pausado (opcional) → Completado/Fallido/Cancelado. Cada transición de estado publica eventos que se pueden monitorear para actualizaciones en tiempo real.
Almacenamiento de datos intermedios
Cada etapa almacena su salida en un formato de datos intermedios estructurado, que incluye contenido de árbol de directorios, patrones regex, listas de archivos filtradas y resultados de corrección de rutas. Estos datos son accesibles para depuración y se pueden usar para reanudar flujos de trabajo desde etapas específicas.
Actualizaciones basadas en eventos
El sistema publica eventos en tiempo real para cambios de estado del flujo de trabajo, finalizaciones de etapa y condiciones de error. Estos eventos permiten interfaces de usuario receptivas e integración con sistemas de monitoreo externos.
¿Necesitas la aplicación de escritorio?
El flujo de trabajo de descubrimiento de archivos se ejecuta dentro del cliente de escritorio junto con la planificación de implementación y las sesiones de terminal.