sinapse-ai 5.0.8 → 6.0.1

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

@@ -1,707 +0,0 @@
-<!--
-  Traducción: ES
-  Original: /docs/en/performance-tuning-guide.md
-  Última sincronización: 2026-01-26
--->
-
-# Guía de Optimización de Rendimiento de SINAPSE
-
-> 🌐 [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 SINAPSE 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: '.sinapse/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.