aiox-core 5.0.0

package/docs/es/performance-tuning-guide.md

@@ -0,0 +1,707 @@
+<!--
+  Traducción: ES
+  Original: /docs/en/performance-tuning-guide.md
+  Última sincronización: 2026-01-26
+-->
+
+# Guía de Optimización de Rendimiento de Synkra AIOX
+
+> 🌐 [EN](../performance-tuning-guide.md) | [PT](../pt/performance-tuning-guide.md) | **ES**
+
+---
+
+## Descripción General
+
+Esta guía completa proporciona estrategias, herramientas y mejores prácticas para optimizar el rendimiento de Synkra AIOX en todos los componentes críticos.
+
+## Objetivos de Rendimiento
+
+### Objetivos de Producción
+- **Tiempo de respuesta del meta-agent**: < 500ms (p95)
+- **Consultas de capa de memoria**: < 200ms (p95)
+- **Generación de componentes**: < 2 segundos
+- **Asistente de instalación**: < 2 minutos en total
+- **Uso de memoria**: < 512MB bajo carga normal
+- **Uso de CPU**: < 60% carga sostenida
+
+### Objetivos de Desarrollo
+- **Inicio de desarrollo local**: < 30 segundos
+- **Hot reload**: < 3 segundos
+- **Ejecución de suite de pruebas**: < 2 minutos
+
+## Kit de Herramientas de Optimización de Rendimiento
+
+### 1. Perfilador de Rendimiento
+```javascript
+const { PerformanceProfiler } = require('./performance/profiler');
+
+const profiler = new PerformanceProfiler({
+  enabled: true,
+  reportPath: '.aiox/reports/performance.json'
+});
+
+// Perfilar cualquier operación
+const result = await profiler.profileFunction(
+  'operation-name',
+  async () => {
+    // Tu operación costosa
+    return await expensiveOperation();
+  },
+  { category: 'meta-agent' }
+);
+```
+
+### 2. Gestor de Caché
+```javascript
+const { getGlobalCacheManager } = require('./performance/cache-manager');
+
+const cache = getGlobalCacheManager();
+
+// Cachear resultados de funciones
+const result = await cache.cacheFunction(
+  'expensive-operation',
+  [arg1, arg2],
+  expensiveFunction,
+  'memory-queries',
+  { ttl: 30 * 60 * 1000 } // 30 minutos
+);
+```
+
+### 3. Optimizador de Consultas de Memoria
+```javascript
+const { getGlobalMemoryOptimizer } = require('./performance/memory-query-optimizer');
+
+const optimizer = getGlobalMemoryOptimizer();
+
+// Optimizar consultas vectoriales
+const results = await optimizer.optimizeQuery(
+  'vector-similarity',
+  vectorQuery,
+  { topK: 10, threshold: 0.7 },
+  originalQueryFunction
+);
+```
+
+### 4. Monitor de Rendimiento
+```javascript
+const { getGlobalPerformanceMonitor } = require('./performance/performance-monitor');
+
+const monitor = getGlobalPerformanceMonitor();
+
+// Monitorear operación
+const operationId = 'op-' + Date.now();
+monitor.startOperation(operationId, 'meta-agent-task');
+// ... ejecutar operación
+monitor.endOperation(operationId, true, { result: 'success' });
+```
+
+## Optimizaciones de Ruta Crítica
+
+### 1. Operaciones del Meta-Agent
+
+#### Creación de Componentes
+```javascript
+// ❌ Sin optimizar
+async function createComponent(template, context) {
+  const rendered = await renderTemplate(template, context);
+  const validated = await validateComponent(rendered);
+  const written = await writeFiles(validated);
+  return written;
+}
+
+// ✅ Optimizado
+async function createComponent(template, context) {
+  const cache = getGlobalCacheManager();
+
+  // Cachear renderizado de plantilla
+  const rendered = await cache.cacheComponentTemplate(
+    template.name,
+    context,
+    () => renderTemplate(template, context)
+  );
+
+  // Validación paralela y escritura de archivos
+  const [validated, _] = await Promise.all([
+    validateComponent(rendered),
+    cache.cacheFileOperation('template-stats', template.path,
+      () => analyzeTemplate(template))
+  ]);
+
+  return await writeFiles(validated);
+}
+```
+
+#### Ejecución de Tareas
+```javascript
+// ✅ Ejecución de tareas optimizada con monitoreo
+async function executeTask(task) {
+  const monitor = getGlobalPerformanceMonitor();
+  const operationId = `task-${task.id}-${Date.now()}`;
+
+  monitor.startOperation(operationId, 'task-execution', {
+    taskType: task.type,
+    complexity: task.complexity
+  });
+
+  try {
+    const result = await profiler.profileFunction(
+      `task.${task.type}`,
+      () => processTask(task),
+      { taskId: task.id }
+    );
+
+    monitor.endOperation(operationId, true, {
+      steps: result.steps,
+      outputSize: result.output?.length
+    });
+
+    return result;
+  } catch (error) {
+    monitor.endOperation(operationId, false, { error: error.message });
+    throw error;
+  }
+}
+```
+
+### 2. Optimizaciones de Capa de Memoria
+
+#### Optimización de Consultas Vectoriales
+```javascript
+// ✅ Consultas vectoriales optimizadas
+async function optimizedVectorQuery(query, options = {}) {
+  const optimizer = getGlobalMemoryOptimizer();
+
+  return await optimizer.optimizeQuery(
+    'vector-similarity',
+    query,
+    {
+      topK: Math.min(options.topK || 10, 100), // Limitar resultados
+      threshold: options.threshold || 0.7,     // Filtrar baja similitud
+      ...options
+    },
+    async (query, params) => {
+      // Pre-filtrar si es posible
+      if (params.filters) {
+        params.filters = optimizeFilters(params.filters);
+      }
+
+      // Ejecutar consulta optimizada
+      return await vectorIndex.query(query, params);
+    }
+  );
+}
+```
+
+#### Gestión de Índices
+```javascript
+// ✅ Construcción inteligente de índices
+class OptimizedMemoryIndex {
+  constructor() {
+    this.batchSize = 100;
+    this.rebuildThreshold = 10000;
+    this.operationCount = 0;
+  }
+
+  async addDocument(doc) {
+    // Agrupar adiciones de documentos en lotes
+    this.pendingDocs = this.pendingDocs || [];
+    this.pendingDocs.push(doc);
+
+    if (this.pendingDocs.length >= this.batchSize) {
+      await this.flushBatch();
+    }
+
+    this.operationCount++;
+
+    // Reconstruir índice si es necesario
+    if (this.operationCount >= this.rebuildThreshold) {
+      await this.scheduleRebuild();
+    }
+  }
+
+  async flushBatch() {
+    if (this.pendingDocs?.length > 0) {
+      await this.index.addDocuments(this.pendingDocs);
+      this.pendingDocs = [];
+    }
+  }
+
+  async scheduleRebuild() {
+    // Reconstruir en segundo plano
+    setImmediate(async () => {
+      await this.rebuildIndex();
+      this.operationCount = 0;
+    });
+  }
+}
+```
+
+### 3. Operaciones del Sistema de Archivos
+
+#### Operaciones de Archivos en Lote
+```javascript
+// ✅ Operaciones de archivos optimizadas
+const fs = require('fs-extra');
+const path = require('path');
+
+async function optimizedFileCopy(sourceDir, targetDir, options = {}) {
+  const cache = getGlobalCacheManager();
+  const profiler = new PerformanceProfiler();
+
+  return await profiler.profileFunction(
+    'file.bulk-copy',
+    async () => {
+      // Obtener lista de archivos con caché
+      const files = await cache.cacheFileOperation(
+        'directory-scan',
+        sourceDir,
+        () => getAllFiles(sourceDir)
+      );
+
+      // Procesar en lotes
+      const batchSize = options.batchSize || 50;
+      const batches = chunkArray(files, batchSize);
+
+      for (const batch of batches) {
+        await Promise.all(
+          batch.map(async (file) => {
+            const sourcePath = path.join(sourceDir, file);
+            const targetPath = path.join(targetDir, file);
+
+            // Omitir si el destino es más reciente
+            const shouldCopy = await cache.cacheFileOperation(
+              'should-copy',
+              `${sourcePath}:${targetPath}`,
+              () => shouldCopyFile(sourcePath, targetPath)
+            );
+
+            if (shouldCopy) {
+              await fs.copy(sourcePath, targetPath);
+            }
+          })
+        );
+      }
+    },
+    { sourceDir, targetDir, fileCount: files.length }
+  );
+}
+```
+
+### 4. Proceso de Instalación
+
+#### Instalación de Dependencias
+```javascript
+// ✅ Instalación de dependencias optimizada
+async function optimizedDependencyInstall(packages) {
+  const cache = getGlobalCacheManager();
+
+  // Verificar qué paquetes ya están instalados
+  const installedPackages = await cache.cacheFunction(
+    'check-installed-packages',
+    [packages],
+    () => checkInstalledPackages(packages),
+    'dependencies'
+  );
+
+  const packagesToInstall = packages.filter(pkg =>
+    !installedPackages.includes(pkg)
+  );
+
+  if (packagesToInstall.length === 0) {
+    return { skipped: packages.length, installed: 0 };
+  }
+
+  // Instalar en lotes paralelos
+  const batchSize = 5; // Evitar sobrecargar npm
+  const batches = chunkArray(packagesToInstall, batchSize);
+
+  for (const batch of batches) {
+    await Promise.all(
+      batch.map(pkg =>
+        cache.cacheDependencyInstall(pkg, () => installPackage(pkg))
+      )
+    );
+  }
+
+  return { skipped: packages.length - packagesToInstall.length,
+           installed: packagesToInstall.length };
+}
+```
+
+## Estrategias de Caché
+
+### 1. Caché de Capa de Memoria
+```javascript
+// Cachear resultados de consulta por tipo
+const cacheStrategies = {
+  'vector-queries': {
+    ttl: 30 * 60 * 1000,  // 30 minutos
+    maxSize: 100,         // 100 entradas
+    priority: 'high'
+  },
+  'semantic-search': {
+    ttl: 15 * 60 * 1000,  // 15 minutos
+    maxSize: 200,
+    priority: 'medium'
+  },
+  'document-retrieval': {
+    ttl: 60 * 60 * 1000,  // 1 hora
+    maxSize: 50,
+    priority: 'high'
+  }
+};
+```
+
+### 2. Caché de Plantillas
+```javascript
+// Cachear plantillas renderizadas
+async function getCachedTemplate(templateName, context) {
+  const cache = getGlobalCacheManager();
+  const contextHash = hashObject(context);
+
+  return await cache.get(
+    `template:${templateName}:${contextHash}`,
+    'component-templates'
+  );
+}
+```
+
+### 3. Caché de Operaciones de Archivos
+```javascript
+// Cachear metadatos y resultados de archivos
+async function getCachedFileStats(filePath) {
+  const cache = getGlobalCacheManager();
+  const stats = await fs.stat(filePath);
+
+  return await cache.cacheFileOperation(
+    'file-stats',
+    filePath,
+    () => analyzeFile(filePath)
+  );
+}
+```
+
+## Monitoreo y Alertas
+
+### 1. Métricas de Rendimiento
+```javascript
+// Configurar monitoreo con umbrales personalizados
+const monitor = new PerformanceMonitor({
+  enabled: true,
+  monitoringInterval: 5000, // 5 segundos
+  thresholds: {
+    cpuUsage: 70,           // 70% CPU
+    memoryUsage: 80,        // 80% memoria
+    responseTime: 500,      // 500ms respuesta
+    errorRate: 2            // 2% tasa de error
+  }
+});
+
+// Escuchar alertas
+monitor.on('alert', (alert) => {
+  console.warn(`Alerta de Rendimiento: ${alert.message}`);
+  // Enviar al sistema de monitoreo
+  sendToMonitoring(alert);
+});
+```
+
+### 2. Métricas Personalizadas
+```javascript
+// Registrar métricas de rendimiento personalizadas
+monitor.recordMetric('component.generation.time', duration);
+monitor.recordMetric('memory.query.latency', queryTime);
+monitor.recordMetric('cache.hit.rate', hitRate);
+```
+
+### 3. Informes de Rendimiento
+```javascript
+// Generar y guardar informes de rendimiento
+async function generatePerformanceReport() {
+  const report = monitor.getReport(24 * 60 * 60 * 1000); // Últimas 24 horas
+  await monitor.saveReport(report, 'daily-performance-report.json');
+
+  // Verificar regresiones de rendimiento
+  const recommendations = report.recommendations;
+  if (recommendations.length > 0) {
+    console.log('Recomendaciones de Rendimiento:');
+    recommendations.forEach(rec => {
+      console.log(`- [${rec.priority}] ${rec.recommendation}`);
+    });
+  }
+}
+```
+
+## Depuración de Problemas de Rendimiento
+
+### 1. Perfilado de Operaciones
+```javascript
+// Perfilar operaciones lentas
+const profiler = new PerformanceProfiler({ verbose: true });
+
+const results = await profiler.profileFunction(
+  'slow-operation',
+  async () => {
+    // Tu operación lenta aquí
+    return await slowOperation();
+  }
+);
+
+console.log(`La operación tomó ${results.duration}ms`);
+console.log(`Delta de memoria: ${results.memoryDelta.heapUsed} bytes`);
+```
+
+### 2. Análisis de Memoria
+```javascript
+// Analizar patrones de uso de memoria
+const memStats = process.memoryUsage();
+console.log('Uso de Memoria:');
+console.log(`RSS: ${(memStats.rss / 1024 / 1024).toFixed(2)} MB`);
+console.log(`Heap Usado: ${(memStats.heapUsed / 1024 / 1024).toFixed(2)} MB`);
+console.log(`Heap Total: ${(memStats.heapTotal / 1024 / 1024).toFixed(2)} MB`);
+```
+
+### 3. Perfilado de CPU
+```javascript
+// Perfilar operaciones intensivas de CPU
+const { performance } = require('perf_hooks');
+
+const start = performance.now();
+// Operación intensiva de CPU
+const result = await cpuIntensiveOperation();
+const end = performance.now();
+
+console.log(`Tiempo de CPU: ${end - start}ms`);
+```
+
+## Ajuste de Configuración
+
+### 1. Límites de Memoria
+```javascript
+// Optimizar límites de memoria basados en el sistema
+const totalMemory = os.totalmem();
+const recommendedLimits = {
+  cacheSize: Math.min(totalMemory * 0.1, 100 * 1024 * 1024), // 10% o 100MB
+  maxOperations: Math.floor(totalMemory / (50 * 1024 * 1024)), // 50MB por op
+  indexSize: Math.min(totalMemory * 0.05, 50 * 1024 * 1024)   // 5% o 50MB
+};
+```
+
+### 2. Límites de Concurrencia
+```javascript
+// Establecer concurrencia óptima basada en núcleos de CPU
+const cpuCount = os.cpus().length;
+const optimalConcurrency = {
+  fileOperations: Math.max(2, cpuCount / 2),
+  networkRequests: Math.max(4, cpuCount),
+  backgroundTasks: Math.max(1, cpuCount / 4)
+};
+```
+
+### 3. Configuración de Caché
+```javascript
+// Configurar caché basado en patrones de uso
+const cacheConfig = {
+  memory: {
+    maxSize: process.env.NODE_ENV === 'production'
+      ? 100 * 1024 * 1024   // 100MB en producción
+      : 50 * 1024 * 1024,   // 50MB en desarrollo
+    ttl: 30 * 60 * 1000     // 30 minutos
+  },
+  disk: {
+    maxSize: 500 * 1024 * 1024, // 500MB
+    ttl: 24 * 60 * 60 * 1000    // 24 horas
+  }
+};
+```
+
+## Lista de Verificación de Rendimiento
+
+### Pre-despliegue
+- [ ] Ejecutar análisis de ruta crítica
+- [ ] Ejecutar benchmarks de rendimiento
+- [ ] Verificar uso de memoria bajo carga
+- [ ] Verificar tasas de acierto de caché > 70%
+- [ ] Probar con volumen de datos de producción
+- [ ] Validar tasas de error < 1%
+
+### Post-despliegue
+- [ ] Monitorear tiempos de respuesta
+- [ ] Rastrear crecimiento de memoria
+- [ ] Observar efectividad del caché
+- [ ] Verificar tasas de error
+- [ ] Revisar alertas de rendimiento
+- [ ] Generar informes semanales
+
+### Prioridades de Optimización
+1. **Alto Impacto, Bajo Esfuerzo**
+   - Habilitar caché para operaciones frecuentes
+   - Optimizar consultas de base de datos
+   - Implementar pooling de conexiones
+
+2. **Alto Impacto, Alto Esfuerzo**
+   - Implementar estrategias avanzadas de caché
+   - Optimizar algoritmos críticos
+   - Agregar monitoreo de rendimiento
+
+3. **Bajo Impacto, Bajo Esfuerzo**
+   - Corregir fugas de memoria menores
+   - Optimizar registro
+   - Limpiar recursos no utilizados
+
+## Antipatrones Comunes de Rendimiento
+
+### ❌ Evitar Estos Patrones
+
+```javascript
+// NO HACER: Operaciones síncronas en bucles
+for (const file of files) {
+  await processFile(file); // Procesa uno a la vez
+}
+
+// NO HACER: Sin caché para operaciones costosas
+async function getExpensiveData() {
+  return await expensiveCalculation(); // Siempre recalcula
+}
+
+// NO HACER: Fugas de memoria con event listeners
+setInterval(() => {
+  // Operación pesada sin limpieza
+}, 1000);
+```
+
+### ✅ Usar Estos Patrones en Su Lugar
+
+```javascript
+// HACER: Procesamiento paralelo con límites
+const results = await Promise.all(
+  files.map(file => processFile(file))
+);
+
+// HACER: Cachear operaciones costosas
+const cache = getGlobalCacheManager();
+async function getExpensiveData() {
+  return await cache.cacheFunction(
+    'expensive-calculation',
+    [],
+    expensiveCalculation,
+    'computation',
+    { ttl: 60 * 60 * 1000 }
+  );
+}
+
+// HACER: Limpieza adecuada
+const intervalId = setInterval(() => {
+  // Operación con limpieza
+}, 1000);
+
+process.on('exit', () => {
+  clearInterval(intervalId);
+});
+```
+
+## Pruebas de Rendimiento
+
+### 1. Pruebas de Carga
+```javascript
+// Prueba de carga simple
+async function loadTest(operation, concurrency = 10, duration = 60000) {
+  const startTime = Date.now();
+  const results = [];
+
+  while (Date.now() - startTime < duration) {
+    const batch = Array(concurrency).fill().map(() =>
+      measureOperation(operation)
+    );
+
+    const batchResults = await Promise.all(batch);
+    results.push(...batchResults);
+  }
+
+  return analyzeResults(results);
+}
+```
+
+### 2. Comparaciones de Benchmark
+```javascript
+// Comparar impacto de optimización
+async function benchmarkOptimization(originalFn, optimizedFn, iterations = 100) {
+  const originalResults = [];
+  const optimizedResults = [];
+
+  for (let i = 0; i < iterations; i++) {
+    originalResults.push(await measureOperation(originalFn));
+    optimizedResults.push(await measureOperation(optimizedFn));
+  }
+
+  return {
+    original: analyzeResults(originalResults),
+    optimized: analyzeResults(optimizedResults),
+    improvement: calculateImprovement(originalResults, optimizedResults)
+  };
+}
+```
+
+## Herramientas y Scripts
+
+### Script de Análisis de Rendimiento
+```bash
+#!/bin/bash
+# performance-check.sh
+
+echo "Ejecutando Análisis de Rendimiento..."
+
+# Ejecutar análisis de ruta crítica
+node performance/run-critical-path-analysis.js
+
+# Generar informe de rendimiento
+node -e "
+const { getGlobalPerformanceMonitor } = require('./performance/performance-monitor');
+const monitor = getGlobalPerformanceMonitor();
+monitor.saveReport().then(path => console.log('Informe guardado en:', path));
+"
+
+# Verificar uso de memoria
+node -e "
+console.log('Uso de Memoria:', process.memoryUsage());
+console.log('Memoria del Sistema:', require('os').totalmem(), 'bytes');
+"
+
+echo "Análisis de rendimiento completado!"
+```
+
+### Script de Análisis de Caché
+```javascript
+// analyze-cache.js
+const { getGlobalCacheManager } = require('./performance/cache-manager');
+
+async function analyzeCachePerformance() {
+  const cache = getGlobalCacheManager();
+  const stats = cache.getStats();
+
+  console.log('Rendimiento del Caché:');
+  console.log(`Tasa de Acierto: ${stats.hitRate.toFixed(2)}%`);
+  console.log(`Uso de Memoria: ${stats.memoryUsageMB} MB`);
+  console.log(`Uso de Disco: ${stats.diskUsageMB} MB`);
+
+  if (stats.hitRate < 50) {
+    console.warn('Baja tasa de acierto de caché detectada!');
+  }
+
+  if (parseFloat(stats.memoryUsageMB) > 100) {
+    console.warn('Alto uso de caché de memoria!');
+  }
+}
+
+analyzeCachePerformance();
+```
+
+## Recursos Adicionales
+
+- [Mejores Prácticas de Rendimiento de Node.js](https://nodejs.org/en/docs/guides/simple-profiling/)
+- [Gestión de Memoria en Node.js](https://nodejs.org/en/docs/guides/diagnostics/memory/)
+- [Herramientas de Monitoreo de Rendimiento](https://nodejs.org/en/docs/guides/diagnostics/)
+- [Consejos de Rendimiento de V8](https://v8.dev/docs/memory)
+
+---
+
+**Recuerde**: La optimización de rendimiento es un proceso iterativo. Siempre mida antes y después de los cambios, y enfóquese en las operaciones que tienen el mayor impacto en la experiencia del usuario.