RTK Compression (Deutsch)

Intensitätsstufen (v3.8.16+)

RTK unterstützt 3 Intensitätsstufen, die einen Kompromiss zwischen Komprimierungsaggressivität und Sicherheit darstellen. Die Stufe wird über config.intensity in der Engine-Konfiguration festgelegt.

Die 3 Stufen

Stufe	Kürzungsschwellenwert	Token-Einsparung	Risiko	Am besten geeignet für
minimal	24 Zeilen pro Abschnitt	~20-40%	Sehr gering	Produktion mit kritischem Kontext
standard (Standard)	24 Zeilen pro Abschnitt	~50-70%	Gering	Tägliche Coding-Sitzungen
aggressive	16 Zeilen pro Abschnitt	~70-90%	Mittel	Lange Sitzungen, maximale Einsparungen

Wo die Kürzung erfolgt

Der Kürzungsschwellenwert wirkt sich auf lineFilter.ts aus:

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

Sowohl der Anfang als auch das Ende jedes Abschnitts bleiben erhalten; Inhalte in der Mitte werden entfernt, sobald die Kürzung greift.

Was erhalten bleibt und was gekürzt wird

Inhalt	minimal	standard	aggressive
Fehler / Stacktraces	✅ beibehalten	✅ beibehalten	✅ beibehalten
Testfehlschläge	✅ beibehalten	✅ beibehalten	✅ beibehalten
Build-Fehler	✅ beibehalten	✅ beibehalten	✅ beibehalten
Erfolgreiche Tests (ausführlich)	✅ beibehalten	🟡 zusammengefasst	🟡 zusammengefasst
Routineausgabe (Info-Logs)	🟡 zusammengefasst	🟡 zusammengefasst	❌ entfernt
Fortschrittsbalken	🟡 zusammengefasst	❌ entfernt	❌ entfernt
Banner / ASCII-Art	🟡 zusammengefasst	❌ entfernt	❌ entfernt

Auswahl der richtigen Intensität

                  Wäre ein Kontextverlust katastrophal?
                  │
      ┌───────────┼───────────┐
      │           │           │
     JA          NEIN       UNSICHER
      │           │           │
      ▼           │           │
   minimal        │           │
      │           │           │
      │           ▼           ▼
      │      Wie wichtig     Zuerst `standard` testen
      │      ist der         (funktioniert in 80 %
      │      Durchsatz?      der Fälle)
      │           │
      │      ┌────┴────┐
      │      │         │
      │   GERING      HOCH
      │      │         │
      │      ▼         ▼
      │   standard   aggressive
      │      │         │
      └──────┴─────────┘

Intensität konfigurieren

Pro Combo (in der Combo-Konfiguration):

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

Programmatisch:

rtkEngine (@omniroute/open-sse/services/compression/engines/rtk) ist eine CompressionEngine und besitzt keine updateConfig-Methode. Aktualisieren Sie die Konfiguration einer Engine stattdessen über die Registry-Hilfsfunktion:

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

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

Wirkung überprüfen

Verwenden Sie das Verifizierungs-Gate (siehe unten), um zu bestätigen, dass Ihr Filter bei der gewählten Intensität sicher ist:

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

const result = runRtkFilterTests({ intensity: "aggressive" });
if (!result.passed) {
  console.error("Filter bei aggressiver Intensität fehlgeschlagen");
}

---

Entwicklung benutzerdefinierter Filter (v3.8.16+)

Das Verzeichnis engines/rtk/filters/ enthält 49+ integrierte Filter-JSON-Dateien. Sie können eigene Filter hinzufügen, um die Ausgabe benutzerdefinierter Tools zu komprimieren, die von den Standardfiltern nicht abgedeckt werden.

Filterschema (Zod)

{
  "id": "string",                      // Erforderlich. Filterkennung (Kebab-Case, z. B. "python-traceback")
  "label": "string",                   // Erforderlich. Benutzerfreundlicher Filtername
  "description": "string",             // Optional (Standard: ""). Kurzbeschreibung der Filterfunktion
  "category": "git|test|build|shell|docker|package|infra|cloud|generic",
  "priority": number,                  // Optional (0–100, Standard: 50). Ausführungsreihenfolge (höher = zuerst)
  "match": {
    "commands": ["string"],            // Abzugleichende Befehlsnamen (z. B. "python", "pytest")
    "patterns": ["string"],            // Reguläre Ausdrücke zum Abgleichen der Ausgabe
    "outputTypes": ["string"]          // Erkannte Ausgabeklassen (z. B. "test-failure")
  },
  "rules": {
    "stripAnsi": boolean,              // Optional (Standard: false). ANSI-Farbcodes entfernen
    "replace": [                       // Such-und-Ersetzungs-Regeln (Standard: [])
      { "pattern": "regex", "replacement": "..." }
    ],
    "matchOutput": [                   // Bei Musterübereinstimmung vorzeitig beenden (Standard: [])
      {
        "pattern": "regex",
        "message": "short summary",
        "unless": "regex"              // Überspringen, wenn dieses Muster übereinstimmt
      }
    ],
    "includePatterns": ["string"],     // Beizubehaltende Zeilen (reguläre Ausdrücke, Standard: [])
    "dropPatterns": ["string"],        // Zu verwerfende Zeilen (reguläre Ausdrücke, Standard: [])
    "collapsePatterns": ["string"],    // Auf ein einzelnes Vorkommen zu reduzierende Zeilen (Standard: [])
    "deduplicate": boolean,            // Optional (Standard: false). Doppelte Zeilen entfernen
    "truncateLineAt": number,          // Optional (Standard: 0). Zeilen auf die maximale Zeichenanzahl kürzen
    "maxLines": number,                // Optional (Standard: 0). Harte Obergrenze für die Gesamtzahl der Zeilen
    "headLines": number,               // Optional (Standard: 20). Die ersten N Zeilen der übereinstimmenden Ausgabe beibehalten
    "tailLines": number,               // Optional (Standard: 20). Die letzten N Zeilen der übereinstimmenden Ausgabe beibehalten
    "onEmpty": "string",               // Optional (Standard: ""). Ersatzmeldung, falls alle Zeilen herausgefiltert wurden
    "filterStderr": boolean            // Optional (Standard: false). Auch die stderr-Ausgabe filtern
  },
  "preserve": {
    "errorPatterns": ["string"],       // Muster, die immer beibehalten werden müssen (Standard: [])
    "summaryPatterns": ["string"]      // Muster für die abschließende Zusammenfassungszeile (Standard: [])
  },
  "tests": [                           // Inline-Tests zur Überprüfung (Standard: [])
    {
      "name": "string",               // Erforderlich. Testname
      "input": "sample output",        // Erforderlich. Beispiel-Eingabetext
      "expected": "expected output",   // Erforderlich. Erwartete komprimierte Ausgabe
      "command": "optional command"    // Optional. Befehlskontext
    }
  ]
}

Beispiel: Python-Traceback-Filter

{
  "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"
    }
  ]
}

Laden benutzerdefinierter Filter

Legen Sie die Datei an einem der erkannten Speicherorte ab:

~/.omniroute/rtk/filters/my-filter.json     # Benutzerebene
<project>/.rtk/filters/my-filter.json      # Projektebene

Filter werden beim Start automatisch über loadRtkFilters() in open-sse/services/compression/engines/rtk/filterLoader.ts geladen. Der Loader erkennt Filter aus folgenden Quellen:

• Integrierter Katalog: open-sse/services/compression/engines/rtk/filters/
• Benutzerverzeichnis: ~/.omniroute/rtk/filters/
• Projektverzeichnis: <project>/.rtk/filters/

So laden Sie Filter programmgesteuert:

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

// Optionen: customFiltersEnabled (Benutzer-/Projektfilter laden, standardmäßig aktiviert),
// trustProjectFilters, refresh.
const filters = loadRtkFilters({ customFiltersEnabled: true });

Validierung

Filter werden beim Laden anhand des Zod-Schemas validiert. Ein Filter mit einer ungültigen Struktur kann nicht geladen werden und erzeugt einen protokollierten Fehler:

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

Um alle installierten Filter zu validieren, rufen Sie runRtkFilterTests() auf, das aus open-sse/services/compression/engines/rtk/verify.ts exportiert wird.

Bewährte Verfahren

1. Immer tests[] einschließen — sie belegen, dass Ihr Filter funktioniert, und verhindern Regressionen
2. matchOutput für Kurzschlussauswertungen verwenden — wenn eine einzelne Zeile alles Wesentliche aussagt, ersetzen Sie den gesamten Block
3. keep gegenüber strip bevorzugen — explizite Regeln nach dem Prinzip „immer beibehalten“ sind sicherer als „immer entfernen“
4. Auf allen 3 Intensitätsstufen testen — minimal sollte keine Änderungen bewirken, aggressive sollte Fehler weiterhin beibehalten
5. Das Feld unless verwenden — sichern Sie Kurzschlussauswertungen mit „nicht auslösen, wenn X vorhanden ist“ ab

---

Wiederherstellung der Rohausgabe & Verifizierungs-Gate

Wenn RTK die Ausgabe aggressiv komprimiert, können Sie den ursprünglichen Text wiederherstellen, um ihn zu debuggen, zu prüfen oder erneut wiederzugeben.

Funktionsweise der Wiederherstellung der Rohausgabe

Ursprüngliche Ausgabe (10K Token)
        │
        ▼
RTK-Komprimierung (mit rawOutput.enabled=true)
        │
        ├─▶ Komprimierte Ausgabe (2K Token)  ──▶ an das LLM
        │
        └─▶ Ursprüngliche Ausgabe (10K Token) ──▶ in der DB gespeichert
                                                   (über request_id verknüpft)

Aktivieren der Speicherung von Rohausgaben

Pro Anfrage (in der Combo-Konfiguration):

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

Standard: rawOutput.enabled: false (spart Speicherplatz).

Speicherkosten

Pro Anfrage	Begrenzung auf 1 MB	Begrenzung auf 10 MB
Durchschnittlich komprimierte Ausgabe	~5KB	~5KB
Gespeicherte Rohausgabe	~50-500KB	~500KB-5MB
Bei 1000 Anfragen/Tag	50-500MB/Tag	500MB-5GB/Tag

Empfehlung: Aktivieren Sie Rohausgaben nur für Debugging-Sitzungen oder stichprobenartige Audits, nicht dauerhaft.

Wiederherstellen des Originals

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

const raw = readRtkRawOutput(pointerId); // pointerId aus den Komprimierungsstatistiken
if (raw) {
  console.log("Original output:", raw);
}

Die pointerId wird nach der Komprimierung in CompressionStats.rtkRawOutputPointers[] zurückgegeben. Die Funktionssignatur finden Sie unter open-sse/services/compression/engines/rtk/rawOutput.ts:102.

Das Verifizierungs-Gate

Die RTK-Filterverifizierung (open-sse/services/compression/engines/rtk/verify.ts) validiert alle Filter anhand ihrer tests[] und stellt sicher, dass sie bei allen 3 Intensitätsstufen korrekt funktionieren.

Rufen Sie runRtkFilterTests() auf, um die Verifizierung auszuführen:

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

Was validiert wird:

1. Jeder Filter wird geladen und besteht die Schemavalidierung
2. Jeder tests[]-Eintrag erzeugt die erwartete Ausgabe
3. Die Intensität minimal ist eine No-op-Operation (behält das Original bei und wendet nur strukturelle Filter an)
4. Die Intensität aggressive bewahrt Fehler, fehlgeschlagene Tests und Stacktraces
5. Die komprimierte Ausgabe ist niemals größer als die ursprüngliche Eingabe

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

• Vor dem Zusammenführen einer Filteränderung — stellen Sie stets sicher, dass die Tests erfolgreich sind

• Nach einem Upgrade der RTK-Engine — das Schema könnte sich geändert haben

• Regelmäßig im Monitoring — schützt vor Abweichungen in den Test-Fixtures

• Beim Hinzufügen einer neuen Tool-/Befehlsfamilie — belegt, dass der neue Filter funktioniert

---

Siehe auch

• COMPRESSION_GUIDE.md — Vollständiger Überblick über die Komprimierungspipeline
• COMPRESSION_ENGINES.md — Engine-Registry und integrierte Engines
• EXTENDING_COMPRESSION.md — Benutzerdefinierte Engines, Sprachpakete, gestapelte Pipelines
• Quelle: open-sse/services/compression/engines/rtk/ (63 Dateien, ~70 KB)

---

OmniRoute-Quellcode (a58000c7685f)