RTK Compression (Português (Brasil))

Níveis de Intensidade (v3.8.16+)

O RTK oferece 3 níveis de intensidade que equilibram a agressividade da compactação e a segurança. O nível é definido por meio de config.intensity na configuração do mecanismo.

Os 3 Níveis

Nível	Limite de truncamento	Economia de tokens	Risco	Mais adequado para
minimal	24 linhas por seção	~20-40%	Muito baixo	Produção com contexto crítico
standard (padrão)	24 linhas por seção	~50-70%	Baixo	Sessões diárias de programação
aggressive	16 linhas por seção	~70-90%	Médio	Sessões longas, economia máxima

Onde Ocorre o Truncamento

O limite de truncamento afeta lineFilter.ts:

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

Tanto o início quanto o fim de cada seção são preservados; o conteúdo intermediário é descartado quando o truncamento entra em ação.

O Que Permanece e o Que É Cortado

Conteúdo	minimal	standard	aggressive
Erros / rastreamentos de pilha	✅ preservados	✅ preservados	✅ preservados
Falhas em testes	✅ preservadas	✅ preservadas	✅ preservadas
Erros de build	✅ preservados	✅ preservados	✅ preservados
Testes aprovados (detalhados)	✅ preservados	🟡 condensados	🟡 condensados
Saída rotineira (logs de info)	🟡 condensada	🟡 condensada	❌ descartada
Barras de progresso	🟡 condensadas	❌ descartadas	❌ descartadas
Banner / arte ASCII	🟡 condensados	❌ descartados	❌ descartados

Escolhendo a Intensidade Correta

                  Perder contexto seria catastrófico?
                  │
      ┌───────────┼───────────┐
      │           │           │
    SIM          NÃO       NÃO SEI
      │           │           │
      ▼           │           │
   minimal        │           │
      │           │           │
      │           ▼           ▼
      │      Quão crítico    Tente `standard` primeiro
      │      é o desempenho? (funciona em 80% dos
      │           │          casos)
      │      ┌────┴────┐
      │      │         │
      │    BAIXO      ALTO
      │      │         │
      │      ▼         ▼
      │   standard   aggressive
      │      │         │
      └──────┴─────────┘

Configurando a Intensidade

Por combo (na configuração do combo):

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

Programaticamente:

rtkEngine (@omniroute/open-sse/services/compression/engines/rtk) é um CompressionEngine e não possui um método updateConfig. Em vez disso, atualize a configuração de um mecanismo por meio do helper do registro:

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

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

Verificando o Efeito

Use o Gate de Verificação (veja abaixo) para confirmar que seu filtro é seguro na intensidade escolhida:

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

const result = runRtkFilterTests({ intensity: "aggressive" });
if (!result.passed) {
  console.error("Os filtros falharam na intensidade agressiva");
}

---

Desenvolvimento de filtros personalizados (v3.8.16+)

O diretório engines/rtk/filters/ contém mais de 49 arquivos JSON de filtros integrados. Você pode adicionar seus próprios filtros para compactar a saída de ferramentas personalizadas não abrangidas pelos padrões.

Esquema do filtro (Zod)

{
  "id": "string",                      // Obrigatório. Identificador do filtro (kebab-case, por exemplo, "python-traceback")
  "label": "string",                   // Obrigatório. Nome legível do filtro
  "description": "string",             // Opcional (padrão: ""). Breve descrição do que o filtro faz
  "category": "git|test|build|shell|docker|package|infra|cloud|generic",
  "priority": number,                  // Opcional (0-100, padrão: 50). Ordem de execução (maior = primeiro)
  "match": {
    "commands": ["string"],            // Nomes de comandos a serem correspondidos (por exemplo, "python", "pytest")
    "patterns": ["string"],            // Padrões de regex para correspondência com a saída
    "outputTypes": ["string"]          // Classes de saída detectadas (por exemplo, "test-failure")
  },
  "rules": {
    "stripAnsi": boolean,              // Opcional (padrão: false). Remove códigos de cores ANSI
    "replace": [                       // Regras de localização e substituição (padrão: [])
      { "pattern": "regex", "replacement": "..." }
    ],
    "matchOutput": [                   // Encerra antecipadamente ao encontrar correspondência com o padrão (padrão: [])
      {
        "pattern": "regex",
        "message": "short summary",
        "unless": "regex"              // Ignora se houver correspondência com este padrão
      }
    ],
    "includePatterns": ["string"],     // Linhas a serem mantidas (padrões de regex, padrão: [])
    "dropPatterns": ["string"],        // Linhas a serem descartadas (padrões de regex, padrão: [])
    "collapsePatterns": ["string"],    // Linhas a serem reduzidas a uma única ocorrência (padrão: [])
    "deduplicate": boolean,            // Opcional (padrão: false). Remove linhas duplicadas
    "truncateLineAt": number,          // Opcional (padrão: 0). Trunca as linhas no número máximo de caracteres
    "maxLines": number,                // Opcional (padrão: 0). Limite rígido para o total de linhas
    "headLines": number,               // Opcional (padrão: 20). Mantém as primeiras N linhas da saída correspondente
    "tailLines": number,               // Opcional (padrão: 20). Mantém as últimas N linhas da saída correspondente
    "onEmpty": "string",               // Opcional (padrão: ""). Mensagem alternativa se todas as linhas forem filtradas
    "filterStderr": boolean            // Opcional (padrão: false). Também filtra a saída de stderr
  },
  "preserve": {
    "errorPatterns": ["string"],       // Padrões que sempre devem ser preservados (padrão: [])
    "summaryPatterns": ["string"]      // Padrões para a linha de resumo final (padrão: [])
  },
  "tests": [                           // Testes embutidos para verificação (padrão: [])
    {
      "name": "string",               // Obrigatório. Nome do teste
      "input": "sample output",        // Obrigatório. Texto de entrada de exemplo
      "expected": "expected output",   // Obrigatório. Saída compactada esperada
      "command": "optional command"    // Opcional. Contexto do comando
    }
  ]
}

Exemplo: filtro de traceback do 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"
    }
  ]
}

Carregamento de filtros personalizados

Coloque o arquivo em um local reconhecido:

~/.omniroute/rtk/filters/my-filter.json     # Nível do usuário
<project>/.rtk/filters/my-filter.json      # Nível do projeto

Os filtros são carregados automaticamente na inicialização por meio de loadRtkFilters() em open-sse/services/compression/engines/rtk/filterLoader.ts. O carregador encontra filtros em:

• Catálogo integrado: open-sse/services/compression/engines/rtk/filters/
• Diretório do usuário: ~/.omniroute/rtk/filters/
• Diretório do projeto: <project>/.rtk/filters/

Para carregar filtros programaticamente:

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

// Opções: customFiltersEnabled (carrega filtros do usuário/projeto, ativado por padrão),
// trustProjectFilters, refresh.
const filters = loadRtkFilters({ customFiltersEnabled: true });

Validação

Os filtros são validados em relação ao esquema Zod durante o carregamento. Um filtro com uma estrutura inválida não será carregado e um erro será registrado:

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

Para validar todos os filtros instalados, chame runRtkFilterTests(), que é exportada de open-sse/services/compression/engines/rtk/verify.ts.

Práticas recomendadas

1. Sempre inclua tests[] — eles comprovam que seu filtro funciona e evitam regressões
2. Use matchOutput para curtos-circuitos — se uma única linha contar toda a história, substitua o bloco inteiro
3. Prefira keep a strip — regras explícitas de “sempre preservar” são mais seguras do que “sempre remover”
4. Teste em todos os 3 níveis de intensidade — minimal deve ser uma operação nula, e aggressive ainda deve preservar erros
5. Use o campo unless — proteja os curtos-circuitos com “não acione se X estiver presente”

---

Recuperação da saída bruta e etapa de verificação

Quando o RTK comprime a saída agressivamente, você pode recuperar o texto original para depuração, auditoria ou reprodução.

Como funciona a recuperação da saída bruta

Saída original (10 mil tokens)
        │
        ▼
Compressão do RTK (com rawOutput.enabled=true)
        │
        ├─▶ Saída comprimida (2 mil tokens)  ──▶ para o LLM
        │
        └─▶ Saída original (10 mil tokens)   ──▶ armazenada no banco de dados
                                                  (vinculada por request_id)

Habilitando o armazenamento da saída bruta

Por solicitação (na configuração do combo):

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

Padrão: rawOutput.enabled: false (economiza armazenamento).

Custo de armazenamento

Por solicitação	Limite de 1 MB	Limite de 10 MB
Média da saída comprimida	~5KB	~5KB
Saída bruta armazenada	~50-500KB	~500KB-5MB
Com 1000 solicitações/dia	50-500MB/dia	500MB-5GB/dia

Recomendação: habilite a saída bruta apenas para sessões de depuração ou auditoria por amostragem, não de forma permanente.

Recuperando o original

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

const raw = readRtkRawOutput(pointerId); // pointerId das estatísticas de compressão
if (raw) {
  console.log("Original output:", raw);
}

O pointerId é retornado em CompressionStats.rtkRawOutputPointers[] após a compressão. Consulte open-sse/services/compression/engines/rtk/rawOutput.ts:102 para ver a assinatura da função.

A etapa de verificação

A verificação dos filtros do RTK (open-sse/services/compression/engines/rtk/verify.ts) valida todos os filtros em relação aos respectivos tests[] e garante que o comportamento esteja correto nos três níveis de intensidade.

Chame runRtkFilterTests() para executar a verificação:

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}"`
      );
    });
}

O que é validado:

1. Todos os filtros são carregados e passam na validação do esquema
2. Cada entrada de tests[] produz a saída esperada
3. A intensidade minimal não realiza nenhuma operação (preserva o original e aplica apenas filtros estruturais)
4. A intensidade aggressive preserva erros, falhas de testes e rastreamentos de pilha
5. A saída comprimida nunca é maior que a entrada original

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

• Antes de mesclar uma alteração em um filtro — sempre garanta que os testes sejam aprovados

• Após atualizar o mecanismo RTK — o esquema pode ter mudado

• Periodicamente durante o monitoramento — protege contra divergências nos fixtures de teste

• Ao adicionar uma nova família de ferramentas/comandos — comprova que o novo filtro funciona

---

Veja também

• COMPRESSION_GUIDE.md — Visão geral completa do pipeline de compressão
• COMPRESSION_ENGINES.md — Registro de mecanismos e mecanismos integrados
• EXTENDING_COMPRESSION.md — Mecanismos personalizados, pacotes de idiomas e pipelines empilhados
• Código-fonte: open-sse/services/compression/engines/rtk/ (63 arquivos, ~70 KB)

---

Código-fonte do OmniRoute (a58000c7685f)