RTK Compression (Español)

Niveles de intensidad (v3.8.16+)

RTK admite 3 niveles de intensidad que ofrecen distintos equilibrios entre la agresividad de la compresión y la seguridad. El nivel se establece mediante config.intensity en la configuración del motor.

Los 3 niveles

Nivel	Umbral de truncamiento	Ahorro de tokens	Riesgo	Ideal para
minimal	24 líneas por sección	~20-40%	Muy bajo	Producción con contexto crítico
standard (predeterminado)	24 líneas por sección	~50-70%	Bajo	Sesiones diarias de programación
aggressive	16 líneas por sección	~70-90%	Medio	Sesiones largas, ahorro máximo

Dónde se produce el truncamiento

El umbral de truncamiento afecta a lineFilter.ts:

// De open-sse/services/compression/engines/rtk/index.ts:329-330
config.intensity === "aggressive" ? 16 : 24,
config.intensity === "aggressive" ? 16 : 24,

Se conservan tanto el inicio como el final de cada sección; el contenido intermedio se descarta cuando se activa el truncamiento.

Qué se conserva y qué se elimina

Contenido	minimal	standard	aggressive
Errores / trazas de pila	✅ conservado	✅ conservado	✅ conservado
Fallos de pruebas	✅ conservado	✅ conservado	✅ conservado
Errores de compilación	✅ conservado	✅ conservado	✅ conservado
Pruebas superadas (detalladas)	✅ conservado	🟡 contraído	🟡 contraído
Salida rutinaria (registros info)	🟡 contraído	🟡 contraído	❌ descartado
Barras de progreso	🟡 contraído	❌ descartado	❌ descartado
Banner / arte ASCII	🟡 contraído	❌ descartado	❌ descartado

Elección de la intensidad adecuada

                  ¿Perder contexto sería catastrófico?
                  │
      ┌───────────┼───────────┐
      │           │           │
     SÍ          NO         NO SEGURO
      │           │           │
      ▼           │           │
   minimal        │           │
      │           │           │
      │           ▼           ▼
      │      ¿Qué importancia  Pruebe primero `standard`
      │      tiene el          (funciona en el 80% de los
      │      rendimiento?      casos)
      │           │
      │      ┌────┴────┐
      │      │         │
      │     BAJA      ALTA
      │      │         │
      │      ▼         ▼
      │   standard   aggressive
      │      │         │
      └──────┴─────────┘

Configuración de la intensidad

Por combo (en la configuración del combo):

{
  "combo": "my-coding-combo",
  "routing": {/* ... */},
  "compression": {
    "engine": "rtk",
    "intensity": "aggressive"
  }
}

Mediante programación:

rtkEngine (@omniroute/open-sse/services/compression/engines/rtk) es un CompressionEngine y no tiene ningún método updateConfig. En su lugar, actualice la configuración de un motor mediante la función auxiliar del registro:

import { updateEngineConfig } from "@omniroute/open-sse/services/compression/engines/registry";

updateEngineConfig("rtk", { intensity: "aggressive" });

Verificación del efecto

Utilice la puerta de verificación (véase más abajo) para confirmar que su filtro es seguro con la intensidad elegida:

import { runRtkFilterTests } from "omniroute/compression/engines/rtk/verify";

const result = runRtkFilterTests({ intensity: "aggressive" });
if (!result.passed) {
  console.error("Los filtros fallaron con la intensidad aggressive");
}

---

Desarrollo de filtros personalizados (v3.8.16+)

El directorio engines/rtk/filters/ contiene más de 49 archivos JSON de filtros integrados. Puede añadir los suyos propios para comprimir la salida de herramientas personalizadas no cubiertas por los valores predeterminados.

Esquema del filtro (Zod)

{
  "id": "string",                      // Obligatorio. Identificador del filtro (kebab-case, p. ej., "python-traceback")
  "label": "string",                   // Obligatorio. Nombre legible del filtro
  "description": "string",             // Opcional (valor predeterminado: ""). Descripción breve de lo que hace el filtro
  "category": "git|test|build|shell|docker|package|infra|cloud|generic",
  "priority": number,                  // Opcional (0-100, valor predeterminado: 50). Orden de ejecución (un valor mayor se ejecuta primero)
  "match": {
    "commands": ["string"],            // Nombres de comandos que deben coincidir (p. ej., "python", "pytest")
    "patterns": ["string"],            // Patrones regex que deben coincidir con la salida
    "outputTypes": ["string"]          // Clases de salida detectadas (p. ej., "test-failure")
  },
  "rules": {
    "stripAnsi": boolean,              // Opcional (valor predeterminado: false). Elimina los códigos de color ANSI
    "replace": [                       // Reglas de búsqueda y reemplazo (valor predeterminado: [])
      { "pattern": "regex", "replacement": "..." }
    ],
    "matchOutput": [                   // Finaliza anticipadamente cuando coincide un patrón (valor predeterminado: [])
      {
        "pattern": "regex",
        "message": "short summary",
        "unless": "regex"              // Omite si este patrón coincide
      }
    ],
    "includePatterns": ["string"],     // Líneas que se conservarán (patrones regex, valor predeterminado: [])
    "dropPatterns": ["string"],        // Líneas que se eliminarán (patrones regex, valor predeterminado: [])
    "collapsePatterns": ["string"],    // Líneas que se reducirán a una única aparición (valor predeterminado: [])
    "deduplicate": boolean,            // Opcional (valor predeterminado: false). Elimina las líneas duplicadas
    "truncateLineAt": number,          // Opcional (valor predeterminado: 0). Trunca las líneas a un número máximo de caracteres
    "maxLines": number,                // Opcional (valor predeterminado: 0). Límite estricto del número total de líneas
    "headLines": number,               // Opcional (valor predeterminado: 20). Conserva las primeras N líneas de la salida coincidente
    "tailLines": number,               // Opcional (valor predeterminado: 20). Conserva las últimas N líneas de la salida coincidente
    "onEmpty": "string",               // Opcional (valor predeterminado: ""). Mensaje alternativo si se filtran todas las líneas
    "filterStderr": boolean            // Opcional (valor predeterminado: false). También filtra la salida stderr
  },
  "preserve": {
    "errorPatterns": ["string"],       // Patrones que siempre deben conservarse (valor predeterminado: [])
    "summaryPatterns": ["string"]      // Patrones para la línea de resumen final (valor predeterminado: [])
  },
  "tests": [                           // Pruebas integradas para verificación (valor predeterminado: [])
    {
      "name": "string",               // Obligatorio. Nombre de la prueba
      "input": "sample output",        // Obligatorio. Texto de entrada de ejemplo
      "expected": "expected output",   // Obligatorio. Salida comprimida esperada
      "command": "optional command"    // Opcional. Contexto del comando
    }
  ]
}

Ejemplo: filtro de rastreo de Python

{
  "id": "python-traceback",
  "label": "Python Traceback Filter",
  "description": "Compresses Python tracebacks to essential file/line locations and error type",
  "category": "test",
  "priority": 60,
  "match": {
    "commands": ["python", "python3", "pytest", "uv", "poetry"],
    "patterns": ["Traceback \\(most recent call last\\)", "Error", "Exception"],
    "outputTypes": ["error-traceback"]
  },
  "rules": {
    "stripAnsi": true,
    "includePatterns": [
      "Traceback \\(most recent call last\\)",
      "^\\s*File \".+\", line \\d+",
      "^\\s*[A-Z][a-zA-Z]+Error:",
      "^\\s*[A-Z][a-zA-Z]+Exception"
    ],
    "dropPatterns": ["site-packages/", "^\\s+[a-z_]+\\([^)]*\\)$"],
    "headLines": 5,
    "tailLines": 3,
    "maxLines": 25,
    "filterStderr": true
  },
  "preserve": {
    "errorPatterns": ["Error:", "Exception:", "Traceback"],
    "summaryPatterns": ["^[A-Z][a-zA-Z]+(?:Error|Exception):"]
  },
  "tests": [
    {
      "name": "preserves-error-type-and-location",
      "input": "Traceback (most recent call last):\n  File \"app.py\", line 42, in main\n    do_thing()\n  File \"lib/utils.py\", line 17, in helper\n    return 1 / 0\nZeroDivisionError: division by zero",
      "expected": "Traceback (most recent call last):\n  File \"app.py\", line 42, in main\n  File \"lib/utils.py\", line 17, in helper\nZeroDivisionError: division by zero",
      "command": "python app.py"
    }
  ]
}

Carga de filtros personalizados

Coloque el archivo en una ubicación reconocida:

~/.omniroute/rtk/filters/my-filter.json     # Nivel de usuario
<project>/.rtk/filters/my-filter.json      # Nivel de proyecto

Los filtros se cargan automáticamente al iniciar mediante loadRtkFilters() en open-sse/services/compression/engines/rtk/filterLoader.ts. El cargador detecta filtros en:

• Catálogo integrado: open-sse/services/compression/engines/rtk/filters/
• Directorio del usuario: ~/.omniroute/rtk/filters/
• Directorio del proyecto: <project>/.rtk/filters/

Para cargar filtros mediante programación:

import { loadRtkFilters } from "@omniroute/open-sse/services/compression/engines/rtk/filterLoader";

// Opciones: customFiltersEnabled (carga los filtros del usuario/proyecto; activado de forma predeterminada),
// trustProjectFilters, refresh.
const filters = loadRtkFilters({ customFiltersEnabled: true });

Validación

Los filtros se validan con el esquema de Zod durante la carga. Un filtro con una estructura incorrecta no se cargará y registrará un error:

RTK_FILTER_LOADER: filter "my-filter" failed validation:
  - rules.replace.0.pattern: Invalid regex
  - match.commands: must not be empty

Para validar todos los filtros instalados, llame a runRtkFilterTests(), que se exporta desde open-sse/services/compression/engines/rtk/verify.ts.

Prácticas recomendadas

1. Incluye siempre tests[] — demuestran que tu filtro funciona y evitan regresiones
2. Usa matchOutput para cortocircuitos — si una sola línea cuenta toda la historia, sustituye el bloque completo
3. Prefiere keep a strip — las reglas explícitas de «preservar siempre» son más seguras que las de «eliminar siempre»
4. Prueba los 3 niveles de intensidad — minimal no debería realizar cambios y aggressive debería seguir preservando los errores
5. Usa el campo unless — protege los cortocircuitos con «no activar si X está presente»

---

Recuperación de la salida sin procesar y puerta de verificación

Cuando RTK comprime la salida de forma agresiva, puedes recuperar el texto original para depuración, auditoría o reproducción.

Cómo funciona la recuperación de la salida sin procesar

Salida original (10K tokens)
        │
        ▼
Compresión de RTK (con rawOutput.enabled=true)
        │
        ├─▶ Salida comprimida (2K tokens)  ──▶ al LLM
        │
        └─▶ Salida original (10K tokens)   ──▶ almacenada en la BD
                                                  (vinculada mediante request_id)

Activación del almacenamiento de la salida sin procesar

Por solicitud (en la configuración combinada):

{
  "compression": {
    "engine": "rtk",
    "intensity": "aggressive",
    "rawOutput": {
      "enabled": true,
      "maxBytes": 1048576 // límite de 1MB
    }
  }
}

Valor predeterminado: rawOutput.enabled: false (ahorra almacenamiento).

Coste de almacenamiento

Por solicitud	Límite de 1MB	Límite de 10MB
Salida comprimida promedio	~5KB	~5KB
Salida sin procesar almacenada	~50-500KB	~500KB-5MB
Con 1000 solicitudes/día	50-500MB/día	500MB-5GB/día

Recomendación: Activa la salida sin procesar únicamente para sesiones de depuración o auditorías por muestreo, no de forma permanente.

Recuperación del original

import { readRtkRawOutput } from "omniroute/compression/engines/rtk/rawOutput";

const raw = readRtkRawOutput(pointerId); // pointerId de las estadísticas de compresión
if (raw) {
  console.log("Original output:", raw);
}

El pointerId se devuelve en CompressionStats.rtkRawOutputPointers[] después de la compresión. Consulta open-sse/services/compression/engines/rtk/rawOutput.ts:102 para ver la firma de la función.

La puerta de verificación

La verificación de filtros de RTK (open-sse/services/compression/engines/rtk/verify.ts) valida todos los filtros respecto a sus tests[] y garantiza que el comportamiento sea correcto en los 3 niveles de intensidad.

Llama a runRtkFilterTests() para ejecutar la verificación:

import { runRtkFilterTests } from "open-sse/services/compression/engines/rtk/verify";

const result = runRtkFilterTests();
console.log(`Passed: ${result.outcomes.filter((o) => o.passed).length}`);
console.log(`Failed: ${result.outcomes.filter((o) => !o.passed).length}`);
if (!result.passed) {
  console.error("Filters failed verification");
  result.outcomes
    .filter((o) => !o.passed)
    .forEach((o) => {
      console.error(
        `  - ${o.filterId} / ${o.testName}: expected "${o.expected}", got "${o.actual}"`
      );
    });
}

Qué valida:

1. Todos los filtros se cargan y superan la validación del esquema
2. Cada entrada de tests[] produce la salida esperada
3. La intensidad minimal no realiza ninguna operación (conserva el original y solo aplica filtros estructurales)
4. La intensidad aggressive conserva los errores, los fallos de las pruebas y los seguimientos de pila
5. La salida comprimida nunca es mayor que la entrada original

• Fuente: open-sse/services/compression/engines/rtk/ (63 archivos, ~70KB)

• Antes de fusionar un cambio en un filtro — asegúrate siempre de que las pruebas se superen

• Después de actualizar el motor RTK — el esquema puede haber cambiado

• Periódicamente durante la monitorización — protege contra desviaciones en los datos de prueba

• Al añadir una nueva familia de herramientas/comandos — demuestra que el nuevo filtro funciona

---

Véase también

• COMPRESSION_GUIDE.md — Descripción general completa del proceso de compresión
• COMPRESSION_ENGINES.md — Registro de motores y motores integrados
• EXTENDING_COMPRESSION.md — Motores personalizados, paquetes de idiomas y procesos apilados
• Código fuente: open-sse/services/compression/engines/rtk/ (63 archivos, ~70 KB)

---

Código fuente de OmniRoute (a58000c7685f)