OmniRoute/docs/i18n/el/docs/compression/EXTENDING_COMPRESSION.md

Extending the Compression Pipeline (Ελληνικά)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Εν συντομία: Η μηχανή συμπίεσης του OmniRoute είναι επεκτάσιμη — μπορείτε να καταχωρίσετε προσαρμοσμένες μηχανές, να διαθέσετε πακέτα γλώσσας για νέες γλώσσες και να συνθέσετε διαδοχικές διοχετεύσεις. Αυτός ο οδηγός δείχνει πώς.

Σχετικοί οδηγοί:

• COMPRESSION_GUIDE.md — Πλήρης επισκόπηση της διοχέτευσης
• COMPRESSION_ENGINES.md — Μητρώο μηχανών και ενσωματωμένες μηχανές
• RTK_COMPRESSION.md — Μηχανή RTK και προσαρμοσμένα φίλτρα
• COMPRESSION_RULES_FORMAT.md — Αναφορά μορφής πακέτου κανόνων

---

Επισκόπηση

Το σύστημα συμπίεσης διαθέτει 3 σημεία επέκτασης:

Σημείο επέκτασης	Περίπτωση χρήσης	Δυσκολία
Προσαρμοσμένη μηχανή	Προσθήκη ενός εντελώς νέου αλγορίθμου συμπίεσης (π.χ. σύνοψη συγκεκριμένου τομέα)	Προχωρημένη
Πακέτο γλώσσας	Προσθήκη υποστήριξης για μια νέα φυσική γλώσσα (π.χ. Χίντι, Αραβικά)	Μέτρια
Διαδοχική διοχέτευση	Σύνθεση υπαρχουσών μηχανών με προσαρμοσμένη σειρά	Αρχάρια

┌─────────────────────────────────────────────────────────────┐
│                    Στρατηγική συμπίεσης                      │
│                                                              │
│   Μηνύματα εισόδου ──▶ getEffectiveMode() ──▶ λειτουργία     │
│                                              │               │
│                      ┌───────────────────────┼──────────┐    │
│                      │         │         │         │    │    │
│                      ▼         ▼         ▼         ▼    │    │
│                   "rtk"    "lite"   "standard" "stacked"    │
│                      │         │         │         │    │    │
│                      ▼         ▼         ▼         ▼    │    │
│                   Μηχανή    Μηχανή   Μηχανή   engines[]   │
│                   RTK       Lite     Caveman  σε αλυσίδα  │
│                      │         │         │         │    │    │
│                      └─────────┴─────────┴─────────┘    │    │
│                                      │                    │
│                                      ▼                    │
│                           Συμπιεσμένη έξοδος               │
└─────────────────────────────────────────────────────────────┘

Ο επιλογέας στρατηγικής ΒΑΣΙΖΕΤΑΙ ΣΤΗ ΛΕΙΤΟΥΡΓΙΑ: κάθε αίτημα επιλέγει ΜΙΑ λειτουργία
(rtk / lite / standard / aggressive / ultra / stacked / off).
Μόνο η λειτουργία "stacked" συνδέει διαδοχικά πολλές μηχανές.
Η προεπιλεγμένη λειτουργία αυτόματης ενεργοποίησης είναι η "lite" (όχι μια αλυσίδα
προτεραιότητας 3 επιπέδων).

---

Δημιουργία προσαρμοσμένης μηχανής συμπίεσης

Η διεπαφή μηχανής (open-sse/services/compression/engines/types.ts) αποτελεί τη σύμβαση που πρέπει να ικανοποιεί κάθε μηχανή. Διαθέτει 5 απαιτούμενες μεθόδους.

Η διεπαφή CompressionEngine

interface CompressionEngine {
  id: string; // Μοναδικό αναγνωριστικό μηχανής
  name: string; // Εμφανιζόμενο όνομα
  description: string; // Σύντομη περιγραφή
  icon: string; // Εικονίδιο (emoji ή URL)
  targets: CompressionEngineTarget[]; // ["messages", "tool_results", "code_blocks"]
  stackable: boolean; // Μπορεί να χρησιμοποιηθεί σε διαδοχική διοχέτευση
  stackPriority: number; // Σειρά στις διαδοχικές διοχετεύσεις (χαμηλότερο = νωρίτερα)
  metadata: CompressionEngineMetadata;

  apply(body, options?): CompressionResult;
  compress(body, config?): CompressionResult;
  getConfigSchema(): EngineConfigField[];
  validateConfig(config): EngineValidationResult;
}

Ελάχιστο παράδειγμα: Μηχανή κενών χαρακτήρων

Η απλούστερη δυνατή μηχανή — αφαιρεί τους επιπλέον κενούς χαρακτήρες από τα μηνύματα.

import type { CompressionEngine } from "omniroute/compression/engines/types";
import { registerCompressionEngine } from "omniroute/compression/engines/registry";

function preserveCodeBlocks(text: string): string {
  // Διαχωρισμός με βάση τους δείκτες μπλοκ κώδικα και διατήρηση των κενών χαρακτήρων μέσα σε αυτά
  const parts = text.split(/(```[\s\S]*?```)/);
  return parts
    .map((part) => {
      if (part.startsWith("```")) {
        return part; // Μην τροποποιείτε τα μπλοκ κώδικα
      }
      return part.replace(/\n{3,}/g, "\n\n"); // Εφαρμογή μόνο στο πεζό κείμενο
    })
    .join("");
}

const whitespaceEngine: CompressionEngine = {
  id: "whitespace",
  name: "Whitespace Stripper",
  description: "Removes extra whitespace and blank lines",
  icon: "📝",
  targets: ["messages", "tool_results"],
  stackable: true,
  stackPriority: 100, // Εκτέλεση ΜΕΤΑ τα caveman/rtk

  metadata: {
    id: "whitespace",
    name: "Whitespace Stripper",
    description: "Removes extra whitespace and blank lines",
    inputScope: "messages",
    targetLatencyMs: 5,
    supportsPreview: true,
    stable: true,
  },

  apply(body, options) {
    return this.compress(body, options?.config);
  },

  compress(body, config = {}) {
    let originalLength = 0;
    let compressedLength = 0;

    // Διάσχιση του πίνακα μηνυμάτων — χειρισμός τόσο περιεχομένου συμβολοσειράς όσο και πολυμερούς περιεχομένου
    const compressedBody = (body.messages || []).map((msg) => {
      if (typeof msg.content === "string") {
        originalLength += msg.content.length;
        let compressed = msg.content
          .replace(/[ \t]+/g, " ")
          .replace(/\n{3,}/g, "\n\n")
          .replace(/^\s+|\s+$/gm, "");
        compressedLength += compressed.length;
        return { ...msg, content: compressed };
      }
      // Πολυμερές περιεχόμενο: διάσχιση των τμημάτων, συμπίεση μόνο των τμημάτων κειμένου
      if (Array.isArray(msg.content)) {
        const newParts = msg.content.map((part) => {
          if (part.type === "text" && typeof part.text === "string") {
            originalLength += part.text.length;
            let compressed = part.text
              .replace(/[ \t]+/g, " ")
              .replace(/\n{3,}/g, "\n\n")
              .replace(/^\s+|\s+$/gm, "");
            compressedLength += compressed.length;
            return { ...part, text: compressed };
          }
          return part; // διατήρηση των image_url, tool_use κ.λπ.
        });
        return { ...msg, content: newParts };
      }
      return msg;
    });

    return {
      body: { ...body, messages: compressedBody },
      stats: {
        originalTokens: Math.ceil(originalLength / 4),
        compressedTokens: Math.ceil(compressedLength / 4),
        savingsPercent: originalLength > 0 ? 100 * (1 - compressedLength / originalLength) : 0,
        techniques: ["whitespace-collapse"],
        engineId: "whitespace",
      },
    };
  },

  getConfigSchema() {
    return [
      {
        key: "preserveCodeBlocks",
        type: "boolean",
        label: "Preserve code blocks",
        defaultValue: true,
        description: "Don't touch whitespace inside ```code``` blocks",
      },
    ];
  },

  validateConfig(config) {
    if (config.preserveCodeBlocks !== undefined && typeof config.preserveCodeBlocks !== "boolean") {
      return { valid: false, errors: ["preserveCodeBlocks must be a boolean"] };
    }
    return { valid: true, errors: [] };
  },
};

// Καθολική καταχώριση
registerCompressionEngine(whitespaceEngine);

Πού να τοποθετήσετε προσαρμοσμένες μηχανές

~/.omniroute/compression/engines/my-engine.ts    # Σε επίπεδο χρήστη
<project>/compression-engines/my-engine.ts        # Σε επίπεδο έργου (φορτώνεται κατά την εκκίνηση)

Ή φορτώστε τις μέσω προγραμματισμού από ένα πρόσθετο:

// Στο πρόσθετό σας
import {
  registerCompressionEngine,
  unregisterCompressionEngine,
} from "@omniroute/open-sse/services/compression/engines/registry";
import { myEngine } from "./engines/my-engine";

export default definePlugin({
  name: "my-compression-plugin",
  // Το SDK προσθέτων εκθέτει τα hooks onRequest / onResponse / onError. Καταχωρίστε τη
  // μηχανή όταν φορτώνεται η μονάδα του προσθέτου (ή κατά το πρώτο onRequest)· καταργήστε την καταχώρισή της
  // μέσω της δικής σας διαδρομής τερματισμού.
  onRequest: async (ctx) => {
    registerCompressionEngine(myEngine);
  },
});

// Κατά τον τερματισμό:
// unregisterCompressionEngine("my-engine");

Δοκιμή της μηχανής σας

Καταχωρίστε τη μηχανή σας σε ένα πρόσθετο ή σε μια συνάρτηση εκκίνησης. Αφού καταχωριστεί, η μηχανή θα είναι διαθέσιμη στον επιλογέα στρατηγικής μέσω του id της. Δοκιμάστε την ενσωμάτωση συνθέτοντάς τη σε μια στοιβαγμένη διοχέτευση:

---

Δημιουργία πακέτων γλώσσας

Η συμπίεση τύπου Caveman χρησιμοποιεί πακέτα κανόνων ειδικά για κάθε γλώσσα για τη διαχείριση γεμιστικών εκφράσεων, επιφυλακτικών διατυπώσεων και φλύαρων μοτίβων σε κάθε φυσική γλώσσα. Το OmniRoute παρέχεται με 6 πακέτα γλώσσας: en, es, fr, de, ja, pt-BR.

Δομή πακέτου

Ένα πακέτο γλώσσας είναι ένας κατάλογος με αρχεία JSON κάτω από το open-sse/services/compression/rules/<language>/:

open-sse/services/compression/rules/
├── en/
│   ├── filler.json          # Τυπικές ευγένειες, επιφυλακτικές διατυπώσεις, ευγένεια
│   ├── context.json         # Κανόνες μείωσης συμφραζομένων
│   ├── dedup.json           # Κανόνες αποδιπλοποίησης
│   ├── structural.json      # Στίξη, μορφοποίηση
│   └── ultra.json           # Κανόνες επιθετικής συμπίεσης
├── es/  (ίδια δομή)
├── fr/  (ίδια δομή)
├── de/  (ίδια δομή)
├── ja/  (ίδια δομή)
└── pt-BR/ (ίδια δομή)

Ανατομία κανόνα

Κάθε κανόνας έχει την ακόλουθη μορφή (από το open-sse/services/compression/ruleLoader.ts):

interface FileRule {
  name: string; // Όνομα αναγνώσιμο από τον άνθρωπο (kebab-case)
  pattern: string; // Μοτίβο κανονικής έκφρασης JavaScript
  replacement?: string; // Με τι θα αντικατασταθεί η αντιστοίχιση
  replacementMap?: Record<string, string>; // Ή ένας χάρτης κλειδιού→αντικατάστασης
  flags?: string; // Σημαίες κανονικής έκφρασης (συνήθως "gi")
  context?: "all" | "user" | "system" | "assistant";
  category?: "filler" | "context" | "structural" | "dedup" | "terse" | "ultra";
  minIntensity?: "lite" | "full" | "ultra"; // Παράλειψη κάτω από αυτή την ένταση
  description?: string; // Τεκμηρίωση
}

Παράδειγμα: Προσθήκη κανόνων γεμιστικών εκφράσεων για τα Χίντι

{
  "language": "hi",
  "category": "filler",
  "rules": [
    {
      "name": "polite_opener",
      "pattern": "\\b(?:नमस्ते|नमस्कार|आदरणीय)\\b[,!\\s]*",
      "replacement": "",
      "context": "all",
      "category": "filler",
      "minIntensity": "lite",
      "description": "Strip polite openers like 'नमस्ते'"
    },
    {
      "name": "filler_actually",
      "pattern": "\\b(?:असल में|वास्तव में|दरअसल)\\b\\s*",
      "replacement": "",
      "context": "all",
      "category": "filler",
      "minIntensity": "lite",
      "description": "Strip 'actually' fillers"
    },
    {
      "name": "verbose_plea",
      "pattern": "\\b(?:कृपया|कृपया आप|अनुरोध है कि आप)\\b\\s*",
      "replacement": "",
      "context": "all",
      "category": "filler",
      "minIntensity": "full",
      "description": "Strip 'please' in Hindi"
    }
  ]
}

Επικύρωση

Τα πακέτα κανόνων επικυρώνονται βάσει του _schema.json κατά τη φόρτωση. Ένα πακέτο με λανθασμένη δομή δεν θα φορτωθεί και θα καταγράψει ένα σφάλμα:

RULE_LOADER: pack "hi/filler.json" failed validation:
  - rules.0.pattern: Invalid regex
  - rules.1.context: must be one of [all, user, system, assistant]

Η επικύρωση εκτελείται αυτόματα όταν φορτώνεται ένα πακέτο (βάσει του _schema.json)· ένα μη έγκυρο πακέτο απορρίπτεται και καταγράφεται το παραπάνω σφάλμα. Δεν υπάρχει ξεχωριστό script npm run για την επικύρωση πακέτων — φορτώστε το πακέτο (π.χ. εκκινήστε τον διακομιστή ή εκτελέστε τη διαδρομή συμπίεσης) και παρακολουθήστε τα αρχεία καταγραφής.

Φόρτωση προσαρμοσμένου πακέτου γλώσσας

import { loadRulePack } from "omniroute/compression/ruleLoader";

await loadRulePack("./my-custom-rules/hi/filler.json");

Εναλλακτικά, τοποθετήστε το σε μια αναγνωρισμένη τοποθεσία:

~/.omniroute/compression/rules/hi/filler.json  # Σε επίπεδο χρήστη
<project>/.compression/rules/hi/filler.json   # Σε επίπεδο έργου

Βέλτιστες πρακτικές για πακέτα γλώσσας

1. Ξεκινήστε με το filler — αυτοί είναι οι κανόνες με τη μεγαλύτερη επίδραση
2. Χρησιμοποιήστε το minIntensity για να περιορίσετε τους επιθετικούς κανόνες — προστατεύει από την υπερβολική συμπίεση
3. Συμπεριλάβετε περιπτώσεις δοκιμών — προσθέστε έναν πίνακα tests[] στο JSON για να επαληθεύσετε τη συμπεριφορά
4. Η σειρά έχει σημασία — οι προηγούμενοι κανόνες εφαρμόζονται πρώτοι· τοποθετήστε πρώτους τους κανόνες με τη μεγαλύτερη επίδραση
5. Να είστε συντηρητικοί με το replacement — η κενή συμβολοσειρά είναι συνήθως η σωστή επιλογή· μην εισάγετε ποτέ νέο περιεχόμενο

Στρατηγική μετάφρασης

Κατά την προσαρμογή πακέτων κανόνων σε μια νέα γλώσσα:

1. Μεταφράστε τα ονόματα των κανόνων — εμφανίζονται στην έξοδο αποσφαλμάτωσης
2. Προσαρμόστε τα μοτίβα κανονικών εκφράσεων — η άμεση μετάφραση συχνά αποτυγχάνει (τα όρια λέξεων διαφέρουν)
3. Δοκιμάστε τα σε πραγματικές συνομιλίες — το πακέτο πρέπει να είναι ασφαλές με πραγματικά δεδομένα εισόδου
4. Ακολουθήστε τις πολιτισμικές συμβάσεις — τα ιαπωνικά πακέτα, για παράδειγμα, περιέχουν περισσότερες τιμητικές γεμιστικές εκφράσεις από τα αγγλικά

---

Στοιβαγμένες Διοχετεύσεις

Μια στοιβαγμένη διοχέτευση εκτελεί πολλαπλές μηχανές διαδοχικά, με την έξοδο κάθε μηχανής να τροφοδοτεί την επόμενη. Έτσι λειτουργεί εσωτερικά το mode: stacked.

Πώς Λειτουργεί η Στοίβαξη

Είσοδος (10.000 token)
        │
        ▼
   ┌──────────┐
   │  Μηχανή  │  προτεραιότητα 10
   │  A       │  ──▶ έξοδος: 6.000 token (-40%)
   └────┬─────┘
        ▼
   ┌──────────┐
   │  Μηχανή  │  προτεραιότητα 50
   │  B       │  ──▶ έξοδος: 2.400 token (-60%)
   └────┬─────┘
        ▼
   ┌──────────┐
   │  Μηχανή  │  προτεραιότητα 100
   │  C       │  ──▶ έξοδος: 1.200 token (-80%)
   └────┬─────┘
        │
        ▼
Τελική έξοδος (1.200 token, ~88% συνδυαστική εξοικονόμηση)

Όταν επιλέγεται το mode: "stacked", οι μηχανές εκτελούνται διαδοχικά με τη σειρά που καθορίζεται στον πίνακα pipeline. Η έξοδος της μηχανής N γίνεται η είσοδος της μηχανής N+1.

Λειτουργίες Συμπίεσης

Το OmniRoute επιλέγει ΜΙΑ λειτουργία ανά αίτημα με βάση τη διαμόρφωση, τα όρια αυτόματης ενεργοποίησης και τις παρακάμψεις συνδυασμών. Οι διαθέσιμες λειτουργίες ορίζονται στο open-sse/services/compression/types.ts (τύπος CompressionMode):

Λειτουργία	Μηχανές	Περίπτωση χρήσης
off	Καμία	Απενεργοποίηση κάθε συμπίεσης
rtk	Μόνο RTK	Συνεδρίες με μεγάλο όγκο εξόδου εντολών (80%+ εξοικονόμηση)
lite	Μόνο Lite	Συντηρητική συμπίεση (γρήγορη, ασφαλής)
standard	Caveman	Συμπίεση πεζού λόγου με πακέτα γλωσσών
aggressive	Caveman + Aggressive	Επιθετική συμπίεση πεζού λόγου + επιθετικό τελικό πέρασμα
ultra	Ultra	Μέγιστη συμπίεση (με απώλειες, έσχατη λύση). Προαιρετικά δρομολογείται μέσω της μηχανής SLM LLMLingua-2 όταν έχει οριστεί το ultra.modelPath (επιστρέφει στη βασισμένη σε κανόνες διαδρομή όταν το μοντέλο δεν είναι διαθέσιμο).
stacked	Προσαρμοσμένη διοχέτευση	Σύνθεση μηχανών με οποιαδήποτε σειρά (δείτε παρακάτω)

Πέρα από τις παραπάνω μηχανές λειτουργιών, το μητρώο περιλαμβάνει επίσης εξειδικευμένες μηχανές που μπορούν να στοιβαχθούν — CCR, headroom, ionizer και session-dedup — οι οποίες τεκμηριώνονται στο COMPRESSION_ENGINES.md.

Η επιλογή λειτουργίας καθορίζεται από τη getEffectiveMode() στο open-sse/services/compression/strategySelector.ts:

1. Αν η συμπίεση είναι απενεργοποιημένη: "off"
2. Αν υπάρχει παράκαμψη συνδυασμού: χρήση της παράκαμψης
3. Αν ξεπεραστεί το όριο αυτόματης ενεργοποίησης: χρήση του autoTriggerMode (προεπιλογή: "lite")
4. Διαφορετικά: χρήση του defaultMode

Η Προεπιλεγμένη Στοιβαγμένη Διοχέτευση

Όταν το mode: "stacked" έχει διαμορφωθεί ρητά, η προεπιλεγμένη διοχέτευση συνθέτει:

1. RTK — αφαιρεί τον θόρυβο από την έξοδο εντολών (~80% εξοικονόμηση στην έξοδο τερματικού)
2. Caveman — αφαιρεί περιττές λέξεις και κάνει τον πεζό λόγο πιο περιεκτικό (~46% στο κείμενο που απομένει)
3. Lite — τελικό πέρασμα για κενά διαστήματα + αποδιπλοποίηση

Αυτή η σύνθεση επιτυγχάνει 78-95% εξοικονόμηση σε συνεδρίες με εκτεταμένη χρήση εργαλείων.

Διαμόρφωση Στοιβαγμένων Διοχετεύσεων

Στη διαμόρφωση συνδυασμού:

{
  "compression": {
    "mode": "stacked",
    "pipeline": [
      { "engine": "rtk", "config": { "intensity": "aggressive" } },
      { "engine": "caveman", "config": { "intensity": "full" } },
      { "engine": "lite", "config": {} }
    ]
  }
}

Μπορείτε να παραλείψετε μηχανές, να προσθέσετε προσαρμοσμένες ή να αλλάξετε τη σειρά τους.

Μεταβίβαση Κατάστασης

Οι μηχανές μπορούν να διαβάζουν μεταδεδομένα από το περιβάλλον του αιτήματος (στο options):

compress(body, config) {
  // Ανάγνωση μεταδεδομένων από προηγούμενες μηχανές
  const original = options?.compressionComboId;  // "my-coding-combo"
  // ...
}

Τα μεταδεδομένα είναι μόνο για ανάγνωση — οι μηχανές δεν μπορούν να μεταβάλουν το περιβάλλον του αιτήματος, παρά μόνο τη δική τους έξοδο σώματος.

Παγίδες στη Σειρά Εκτέλεσης

Σειρά μηχανών	Αποτέλεσμα
RTK → Caveman → Lite	Συνιστάται (αφαιρεί πρώτα τον θόρυβο, μετά τη γλώσσα και τέλος τα κενά διαστήματα)
Lite → RTK → Caveman	Κακή — το Lite αφαιρεί τα κενά διαστήματα από την ανεπεξέργαστη έξοδο, προκαλώντας αποτυχία αντιστοίχισης μοτίβων από το RTK
Caveman → RTK	Κακή — το Caveman ενδέχεται να ξαναγράψει το κείμενο με τρόπους που δεν αναγνωρίζει το RTK
Οποιαδήποτε σειρά με πρώτο το tool_results	Καλύτερη — η έξοδος εργαλείων είναι το περιεχόμενο με τον περισσότερο θόρυβο

Πότε να ΜΗ Χρησιμοποιείτε Στοίβαξη

Η στοίβαξη δεν είναι πάντα καλύτερη:

• Απλά μηνύματα (χωρίς έξοδο εργαλείων) — αρκεί μόνο το Caveman ή το Lite
• Ευαισθησία στο κόστος — κάθε μηχανή προσθέτει καθυστέρηση ~5-50ms
• Συγκεκριμένα εργαλεία — το RTK από μόνο του είναι συνήθως επαρκές για έξοδο κελύφους

Δημιουργία Προσαρμοσμένης Διοχέτευσης

Δεν υπάρχει μητρώο επώνυμων pipeline. Ένα stacked pipeline είναι απλώς ένας ενσωματωμένος πίνακας βημάτων που μεταβιβάζεται στη applyStackedCompression() (η οποία εξάγεται από το @omniroute/open-sse/services/compression/strategySelector):

import { applyStackedCompression } from "@omniroute/open-sse/services/compression/strategySelector";

const result = applyStackedCompression(body, [
  { engine: "rtk", intensity: "aggressive" },
  { engine: "caveman", intensity: "full" },
]);

Όταν δεν μεταβιβάζετε κάποιο pipeline, χρησιμοποιείται από προεπιλογή το rtk(standard) → caveman(full).

Για να το ελέγχετε μέσω ρυθμίσεων, ορίστε mode: "stacked" και παρέχετε τον πίνακα βημάτων στο stackedPipeline (διαβάζεται από το config.stackedPipeline):

{
  "compression": {
    "mode": "stacked",
    "stackedPipeline": [
      { "engine": "rtk", "intensity": "aggressive" },
      { "engine": "caveman", "intensity": "full" }
    ]
  }
}

---

Πολιτική συγχρονισμού με τα upstream έργα

Οι μηχανές συμπίεσης του OmniRoute αναγνωρίζουν στο README τη συνεισφορά αρκετών upstream έργων ("inspired by RTK, Caveman, LLMLingua-2, Troglodita"). Μια συνηθισμένη ερώτηση από τους συνεισφέροντες είναι: όταν το upstream RTK προσθέτει ένα νέο φίλτρο εργαλείου ή το Caveman προσθέτει ένα πακέτο κανόνων, πώς ενσωματώνεται αυτό στο OmniRoute; Αυτή η ενότητα αποτελεί την επίσημη απάντηση.

Ενσωματωμένα αντίγραφα έναντι ανεξάρτητων υλοποιήσεων

Μηχανή	Σχέση με το upstream	Τοποθεσία
RTK	Ανεξάρτητη επανυλοποίηση (εμπνευσμένη από αυτό, όχι αντίγραφο)	open-sse/services/compression/engines/rtk/
Caveman	Ανεξάρτητη επανυλοποίηση (εμπνευσμένη από αυτό)	open-sse/services/compression/engines/cavemanAdapter.ts
Headroom	Κυρίως εσωτερική· μόνο ο κωδικοποιητής gcf/ είναι πραγματικά ενσωματωμένος από το gcf-typescript (MIT, με σήμανση SPDX, μόνο γενικό προφίλ)	open-sse/services/compression/engines/headroom/gcf/
LLMLingua-2 / Troglodita	Εμπνευσμένες από αυτά (τροφοδοτούν τις μηχανές llmlingua + session-dedup)	open-sse/services/compression/engines/llmlingua/, session-dedup

Βασικό σημείο: Τα RTK και Caveman είναι υλοποιήσεις TypeScript καθαρού σχεδιασμού των ιδεών (κανόνες φίλτρων, πακέτα κανόνων) και όχι ενσωματωμένα δέντρα πηγαίου κώδικα. Δεν υπάρχει upstream αντίγραφο από το οποίο να εκτελεστεί git pull — και αυτός ακριβώς είναι ο λόγος που το README αναφέρει "inspired by" αντί για "bundled".

Πώς συγχωνεύονται οι upstream βελτιώσεις

**Δεν υπάρχει αυτοματοποιημένη παρακολούθηση upstream εκδόσεων ούτε ετικέτα compression-sync ** — από σχεδιασμό. Επειδή οι μηχανές είναι επανυλοποιήσεις, ένα upstream φίλτρο του RTK ή ένα πακέτο κανόνων του Caveman δεν συγχωνεύεται ως κώδικας· εκφράζεται εκ νέου ως νέος κανόνας/φίλτρο στην ιδιόκτητη μορφή του OmniRoute (βλ. COMPRESSION_RULES_FORMAT.md) και ενσωματώνεται κατά περίπτωση μέσω ενός κανονικού PR. Τα παραπάνω σημεία επέκτασης (προσαρμοσμένη μηχανή, πακέτο γλώσσας, φίλτρο RTK) αποτελούν τον εγκεκριμένο τρόπο συνεισφοράς ενός τέτοιου στοιχείου.

Πρόσφατα παραδείγματα αυτής ακριβώς της ροής:

• Φίλτρα RTK για την έξοδο build των Gradle και dotnet (v3.8.42)
• Φίλτρα RTK για kubectl / docker-build / composer / gh (#2824)
• Πακέτο ινδονησιακής γλώσσας για το Caveman (#3975), καθώς και πακέτα γερμανικών / γαλλικών / ιαπωνικών / κινεζικών

Headroom (διαμεσολαβητής συμπίεσης εισόδου)

Το Headroom είναι πλήρως εσωτερικό — ένα καρφιτσωμένο, ενσωματωμένο στιγμιότυπο του κωδικοποιητή gcf μαζί με τα ιδιόκτητα επίπεδα smartcrusher / toon / tabular του OmniRoute. Δεν υπάρχει ενεργό upstream προς παρακολούθηση πέρα από το ενσωματωμένο αντίγραφο· οι ενημερώσεις του gcf εφαρμόζονται χειροκίνητα όταν αλλάζει ο κωδικοποιητής και επανεπικυρώνονται βάσει της πύλης προϋπολογισμού συμπίεσης (check:compression-budget).

Πρόταση βελτίωσης εμπνευσμένης από upstream έργο

1. Μην ενσωματώνετε αντίγραφο — εκφράστε εκ νέου τον upstream κανόνα/φίλτρο στη μορφή του OmniRoute.
2. Προσθέστε τον μέσω του αντίστοιχου σημείου επέκτασης παρακάτω (πακέτο γλώσσας, φίλτρο RTK ή προσαρμοσμένη μηχανή).
3. Αναφέρετε το upstream έργο στην περιγραφή του PR (απόδοση αναφοράς), όχι αντιγράφοντας τον πηγαίο κώδικά του που καλύπτεται από άδεια χρήσης.
4. Συμπεριλάβετε δοκιμές και επιβεβαιώστε ότι η πύλη check:compression-budget εξακολουθεί να περνά επιτυχώς.

---

Προσθήκη ενός Στυλ Εξόδου

Τα στυλ εξόδου (δείτε τον πίνακα καταλόγου του οδηγού) είναι το αντίστοιχο των μηχανών εισόδου στην πλευρά της απόκρισης: αντί να συμπιέζουν ό,τι στέλνετε, καθοδηγούν το μοντέλο ώστε να παράγει οικονομικότερη έξοδο. Το μητρώο είναι το OUTPUT_STYLE_CATALOG στο open-sse/services/compression/outputStyles/catalog.ts και μία καταχώριση καταλόγου αποτελεί ολόκληρη τη λειτουργία: ο εγχυτής, ο πίνακας ρυθμίσεων, η διατήρηση δεδομένων και η τηλεμετρία απαριθμούν όλα τον κατάλογο — δεν υπάρχει άλλη λίστα προς ενημέρωση.

1. Προσθέστε μία καταχώριση στο OUTPUT_STYLE_CATALOG με id, label, description και τα τρία αγγλικά levels (lite, full, ultra). Κάθε επίπεδο πρέπει να τελειώνει με ${SHARED_BOUNDARIES}, ώστε ο κώδικας, οι διαδρομές, οι εντολές, τα σφάλματα και τα URL να παραμένουν αυτούσια. Το κείμενο οδηγιών πρέπει να είναι στατικό και ντετερμινιστικό ανά (id, level, language) — το ${SHARED_BOUNDARIES} είναι η μόνη επιτρεπόμενη παρεμβολή.
2. Μεταφράστε το. Συμπεριλάβετε τουλάχιστον ένα μπλοκ pt-BR κάτω από το i18n. Τα ponytail και i-have-adhd (en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi) αποτελούν το πρότυπο αναφοράς. Ένα στυλ που σκοπίμως υποστηρίζει μία μόνο γλώσσα ορίζει αντ’ αυτού το locale (όπως terse-cjk → zh) και τότε προσφέρεται μόνο για αυτήν την τοπική ρύθμιση.
3. Ενημερώστε τον έλεγχο πίνακα — προσθέστε τις γλώσσες του στυλ στο BASELINE_LANGUAGES στο tests/unit/compression/output-styles-i18n-matrix.test.ts. Η πύλη αποτυγχάνει για κάθε νέο στυλ που δεν περιορίζεται βάσει τοπικής ρύθμισης και δεν διαθέτει τις απαιτούμενες μεταφράσεις, εκτός αν έχει ρητή καταχώριση KNOWN_ENGLISH_ONLY με σχετικό ζήτημα παρακολούθησης.
4. Προσθέστε μια δοκιμή ανά στυλ κατά το πρότυπο του tests/unit/compression/i-have-adhd-catalog.test.ts: σχήμα καταλόγου, ρήτρα ορίων ανά επίπεδο και μια επιβεβαίωση αναφοράς ότι κάθε μετάφραση είναι γραμμένη στη δική της γλώσσα και δεν αποτελεί αντιγραμμένο αγγλικό κείμενο.
5. Απόδοση προέλευσης: αν το στυλ είναι προσαρμοσμένο από κάποιο έργο upstream, αναφέρετέ το σε σχόλιο πηγής στην καταχώριση (π.χ. i-have-adhd → ayghri/i-have-adhd, MIT) — ισχύει ο ίδιος κανόνας όπως στην ενότητα «Πρόταση βελτίωσης εμπνευσμένης από upstream» παραπάνω.

Δεν απαιτείται καμία αλλαγή στο περιβάλλον χρήστη, στο σχήμα ή στην τηλεμετρία — αυτές οι επιφάνειες αποδίδονται από τον κατάλογο.

---

Βέλτιστες Πρακτικές

Ανάπτυξη Μηχανών

1. Υλοποιείτε πάντα το validateConfig — οι μηχανές χωρίς επικύρωση προκαλούν σιωπηρές αποτυχίες
2. Ορίστε ρεαλιστικό targetLatencyMs — χρησιμοποιείται από τον επιλογέα στρατηγικής για την επιλογή μηχανών
3. Χρησιμοποιήστε το getConfigSchema για τον πίνακα ελέγχου — μην αποκρύπτετε ποτέ ρυθμίσεις από τους χρήστες
4. Υποστηρίξτε stackable: true αν η μηχανή σας είναι αμιγής — οι μηχανές με παρενέργειες δεν πρέπει να συνδυάζονται σε στοίβα
5. Γράψτε ενσωματωμένες δοκιμές — οι μηχανές πρέπει να μπορούν να επαληθευτούν σε <1s

Ανάπτυξη Πακέτων Γλώσσας

1. Ξεκινήστε με ένταση lite — οι κανόνες σας πρέπει να είναι ασφαλείς στη χαμηλότερη ρύθμιση
2. Χρησιμοποιήστε το context για να περιορίσετε την εμβέλεια των κανόνων — οι κανόνες μόνο για user δεν μπορούν να επηρεάσουν κατά λάθος τις προτροπές συστήματος
3. Αποφύγετε την καταγραφή κλειδιών JSON — το \\bword\\b μπορεί να αντιστοιχηθεί μέσα σε JSON, αλλοιώνοντας τα δομημένα δεδομένα
4. Δοκιμάστε με οριακές περιπτώσεις — κενή είσοδος, unicode, κείμενο RTL, emoji
5. Χρησιμοποιήστε υπάρχοντα πακέτα ως πρότυπα — το en/filler.json είναι το πιο ανεπτυγμένο παράδειγμα

Σχεδιασμός Διοχέτευσης

1. Κάντε ανάλυση επιδόσεων πριν από τη βελτιστοποίηση — μετρήστε πρώτα με το compression_stats
2. Προτιμήστε τη σύνθεση αντί της επανυλοποίησης — επεκτείνετε τους κανόνες Caveman πριν γράψετε μια νέα μηχανή
3. Τεκμηριώστε το σκεπτικό της σειράς — σχολιάστε γιατί η μηχανή A προηγείται της μηχανής B
4. Δοκιμάστε και στα 3 επίπεδα έντασης — το lite είναι γρήγορο αλλά με απώλειες, το ultra είναι αργό αλλά ακριβές

---

Αναφορά: Ενσωματωμένες μηχανές

Αναγνωριστικό μηχανής	Στοιβάσιμη	Προεπιλεγμένο stackPriority	Στόχοι
lite	Ναι	5	μηνύματα, αποτελέσματα εργαλείων
rtk	Ναι	10	αποτελέσματα εργαλείων
standard (caveman)	Ναι	20	μηνύματα, αποτελέσματα εργαλείων, μπλοκ κώδικα
aggressive	Ναι	30	μηνύματα
ultra	Ναι	40	μηνύματα, μπλοκ κώδικα

Δείτε επίσης

• COMPRESSION_GUIDE.md — Επισκόπηση της διοχέτευσης
• COMPRESSION_ENGINES.md — Αναφορά μητρώου μηχανών
• COMPRESSION_RULES_FORMAT.md — Προδιαγραφή μορφής κανόνων
• COMPRESSION_LANGUAGE_PACKS.md — Λεπτομέρειες πακέτων γλωσσών
• RTK_COMPRESSION.md — Μηχανή RTK και προσαρμοσμένα φίλτρα
• Πηγή: open-sse/services/compression/ (117 αρχεία, ~250KB)