# 🗜️ Prompt Compression Guide — OmniRoute (Gaeilge)

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

---

> Sábháil 15-95% den chomhthéacs incháilithe go huathoibríoch. Chun forléargas tapa a fháil, féach ar [rannán Comhbhrúite an README](../README.md#%EF%B8%8F-prompt-compression--save-15-95-eligible-tokens-automatically).

## Forléargas

Cuireann OmniRoute píblíne mhodúlach comhbhrúite leideanna i bhfeidhm a ritheann **go réamhghníomhach** sula sroicheann iarratais soláthraithe réamhtheachtacha. Ciallaíonn sé seo go sábhálfar comharthaí go trédhearcach — ní gá aon athrú a dhéanamh ar do shreabhadh oibre.

```
Iarratas ón gCliant
  → Roghnóir Straitéise Comhbhrúite
    → Sárú teaglama? → Úsáid socrú an teaglama
    → Tairseach uathspreagtha? → Úsáid mód uathoibríoch
    → Mód réamhshocraithe? → Úsáid an socrú domhanda
    → Múchta? → Scipeáil an comhbhrú
  → Mód Comhbhrúite Roghnaithe
    → Múchta: Gan chomhbhrú
    → Éadrom: Glanadh sábháilte spás bán/formáidithe (~15%)
    → Caighdeánach: Focail líonta ar nós caint uaimheora a bhaint (~30%)
    → Ionsaitheach: Aosú staire + achoimriú (~50%)
    → Fíorard: Bearradh heorastúil + tanú bloc cód (~75%)
    → RTK: Scagadh aschur teirminéil/uirlisí atá feasach ar orduithe (raon réamhtheachtach 60-90%)
    → Cruachta: Píblíne ilinnill ordaithe, RTK de ghnáth agus Caveman ina dhiaidh (raon incháilithe 78-95%)
  → Iarratas Comhbhrúite → Soláthraí
```

---

## Móid Chomhbhrúite

### Múchta

Ní chuirtear aon chomhbhrú i bhfeidhm. Gabhann gach teachtaireacht tríd gan athrú.

### Mód Éadrom (~15% de choigilteas, aga folaigh <1ms)

An mód is sábháilte — gan aon athrú séimeantach, glanadh formáidithe amháin:

| Teicníc                  | Cur Síos                                                |
| ------------------------ | ------------------------------------------------------- |
| `collapseWhitespace`     | Cumaisc línte bána comhleanúnacha agus spásanna deiridh |
| `dedupSystemPrompt`      | Bain teachtaireachtaí córais dúblacha                   |
| `compressToolResults`    | Comhbhrúigh aschuir fhoclacha uirlise/feidhme           |
| `removeRedundantContent` | Bain treoracha athráite                                 |
| `replaceImageUrls`       | Giorraigh URIanna sonraí íomhá base64                   |

**Is fearr le haghaidh:** Úsáid leanúnach, sreafaí oibre atá criticiúil ó thaobh sábháilteachta de.

### Mód Caighdeánach (~30% de choigilteas)

Bunaithe ar [Caveman](https://github.com/JuliusBrussee/caveman) — baintear focail líonta agus friotal foclach agus an bhrí á caomhnú:

- Baintear focail líonta ("le do thoil", "sílim", "go bunúsach", "i ndáiríre")
- Dlúthaítear frásaí foclacha ("chun críche" → "chun", "mar thoradh ar" → "toisc")
- Baintear maolú béasach ("Ar mhiste leat...", "Dá bhféadfá, b'fhéidir...")
- Breis agus 30 riail slonn ionadaíochta tiúnáilte le haghaidh leideanna códaithe

**Is fearr le haghaidh:** Sreafaí oibre códaithe laethúla, foirne atá feasach ar chostais.

### Mód Ionsaitheach (~50% de choigilteas)

Bainistiú cliste staire le haghaidh seisiúin fhada:

- **Aosú Teachtaireachtaí** — déantar teachtaireachtaí níos sine a chomhbhrú de réir a chéile
- **Comhbhrú Torthaí Uirlise** — gearrtar nó fágtar ar lár aschuir fhada uirlise (na chéad línte/na línte deiridh,
  scagadh línte meaitseála, dlúthú eochracha JSON)
- **Cosaintí Sláine Struchtúraí** — cinntítear go bhfanann péirí `tool_use` + `tool_result` comhsheasmhach
- **Feasacht ar Fhuinneog an Chomhthéacs** — urramaítear teorainneacha comharthaí gach samhla

**Is fearr le haghaidh:** Seisiúin fhada dífhabhtaithe, bunachair mhóra cód.

### Mód Fíorard (~75% de choigilteas)

Comhbhrú uasta le haghaidh cásanna ina bhfuil comharthaí ríthábhachtach:

- **Bearradh Heorastúil** — bearradh prós comhartha ar chomhartha bunaithe ar scór
- **Caomhnú Struchtúir** — cuirtear bloic chód fhálaithe, cód inlíne, URLanna agus aitheantóirí
  i leataobh agus fuaitear ar ais iad focal ar fhocal; ní bhearrtar riamh iad
- **Sraith roghnach SLM** — is féidir le samhail bheag áitiúil an bearradh a bheachtú nuair a chumraítear í
- Neamhspleách ar an mód Ionsaitheach: ní ritheann sé aosú teachtaireachtaí, comhbhrú torthaí uirlise
  ná an t-achoimreoir cúltaca (ní féidir ach le teip sa tsraith SLM pas cúltaca a sheoladh tríd an
  mód ionsaitheach)

**Is fearr le haghaidh:** Nuair a bhíonn teorainneacha comhthéacs á sárú agat arís agus arís eile.

### Mód RTK (raon réamhtheachtach 60-90%)

Tá mód RTK optamaithe le haghaidh aschuir fhoclacha uirlise a bhíonn le feiceáil i seisiúin gníomhairí códaithe:

- Aimsítear aicmí ordaithe/aschuir amhail `git status`, `git diff`, `git log`, riteoirí tástála,
  tiomsúcháin TypeScript/Vite/Webpack, ESLint/Biome/Prettier, iniúchtaí/suiteálacha npm, logaí Docker, aschur bonneagair
  agus aschur ginearálta blaoisce
- Cuirtear pacáistí scagairí JSON ó `open-sse/services/compression/engines/rtk/filters/` i bhfeidhm
- Iompórtáiltear scagairí RTK TOML schema v1 ó chomhaid tionscadail nó dhomhanda `filters.toml`, le bailíochtú
  tástálacha inlíne agus geatú iontaoibhe do chomhaid tionscadail
- Soláthraítear 55 scagaire ionsuite le samplaí fíoraithe inlíne
- Baintear seichimh rialaithe ANSI, barraí dul chun cinn, línte athráite agus torann nach féidir gníomhú ina leith
- Caomhnaítear teipeanna, earráidí, rabhaidh, comhaid athraithe, achoimrí agus deireadh aschuir fhada
- Tacaítear le scagairí tionscadail faoi gheata iontaoibhe, scagairí domhanda agus aisghabháil roghnach aschuir amh faoi cheilt

**Is fearr le haghaidh:** Seisiúin ghníomhairí ina bhfuil tras-scríbhinní blaoisce, tiomsúcháin, tástála, git, grep agus aschuir comhad.

### Mód Cruachta (raon incháilithe 78-95%)

Ritheann mód Cruachta innill chomhbhrúite iolracha in ord cinntitheach. Is í an phíblíne réamhshocraithe:

```txt
RTK -> Caveman
```

Coinníonn an t-ord sin aschur teirminéil/uirlisí dlúth ar dtús, ansin cuireann sé dlúthú séimeantach Caveman i bhfeidhm ar
an gcuid eile den leid teanga nádúrtha. Is féidir píblínte cruachta a chumrú go domhanda nó trí
theaglamaí comhbhrúite a shanntar do theaglamaí ródúcháin.

**Is fearr le haghaidh:** Comhthéacs measctha ina bhfuil logaí móra uirlise chomh maith le treoracha daonna nó achoimrí cúntóra.

---

## Matamaitic na gCoigilteas Réamhtheachtach

Déanann OmniRoute coigilteas comhbhrúite ó dhá fhoinse a dhoiciméadú: tagarmharcanna tionscadail réamhtheachtacha agus
comhdhéanamh innill OmniRoute féin.

| Foinse  | Uimhir ón README réamhtheachtach a úsáidtear anseo                                                                                                    |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Caveman | `~75%` níos lú comharthaí aschuir, `65%` de choigilteas aschuir ar an meán sna tagarmharcanna, raon `22-87%`, agus uirlis comhbhrúite ionchuir `~46%` |
| RTK     | Coigilteas `60-90%` ar aschur orduithe; seisiún samplach `~118,000 -> ~23,900` comhartha, nó `79.7%` sábháilte (`~80%`)                               |

I gcás ualaí uirlise/comhthéacs atá ag forluí, cruachann teaglaim réamhshocraithe OmniRoute na hinnill:

```txt
RTK -> Caveman
```

Tá an coigilteas comhcheangailte iolrach, ní suimitheach:

```txt
combined = 1 - (1 - RTK savings) * (1 - Caveman input savings)
average  = 1 - (1 - 0.80) * (1 - 0.46) = 89.2%
range    = 1 - (1 - 0.60..0.90) * (1 - 0.46) = 78.4-94.6%
```

Baineann an figiúr `78-95%` sin le cásanna inar féidir le RTK agus Caveman araon an t-ualach ionchuir/comhthéacs céanna a laghdú.
Tá mód aschuir freagartha Caveman ar leithligh: nuair atá sé cumasaithe, úsáid coigilteas aschuir Caveman féin (`65%`
ar an meán, `~75%` mar phríomhfhigiúr, raon `22-87%`). Braitheann an coigilteas iomlán billeála ar do mheascán leid/aschuir.

### Cad is brí le "incháilithe" i ndáiríre

Tá an raon ceannlíne 15-95% fíor, ach ní bhaineann sé ach le hábhar **iomarcach nó foclach** — línte earráide
athdhéanta, loga tógála a dhéanann turscar den rabhadh céanna, dumpa rómhór `grep`/léite comhaid. Ní chiallaíonn sé
go sábhálann gach iarratas an méid sin.

Deimhnithe go heimpíreach (`tests/unit/compression/stacked-compression-tool-result-savings.test.ts`): chruthaigh
rith `stacked` (RTK + Caveman) ar bhloc `tool_result` i gcruth Anthropic ina raibh 300 líne earráide chomhionanna
**coigilteas comharthaí 95.93% / coigilteas carachtar 96.26%** — go díreach laistigh den raon fógraithe.
Ach nuair a ritheann an phíblíne chéanna ar ghnáth-aschur uirlise nach bhfuil iomarcach (liosta glan meaitseálacha `grep`,
léamh gairid comhaid, gnáth-théacs comhrá), cruthaíonn sí **coigilteas gar do nialas** mar is ceart, toisc
nach bhfuil aon rud athráiteach le baint agus go ndiúltaíonn `validateCompression()` (`validation.ts`) athscríobh a sheoladh
a bhainfeadh nó a d’athródh bloic chóid, URLanna, ceannteidil, leaganacha, nó aitheantóirí tairisigh atá go hiomlán i gCEANNLITREACHA.

Is iompar sábháilte, ionchais é seo, ní fabht: i seisiún códúcháin ina léitear/cuardaítear comhaid ghlana den chuid is mó,
beidh an coigilteas iomlán measartha fiú agus comhbhrú lánchumasaithe, ach i seisiún a thagann ar lúb theipthe
nó ar linter cainteach, feicfear an raon iomlán 78-95% ar an trácht sin. Ná húsáid céatadán íseal
coigilteas comhiomlán ó sheisiún amháin mar fhianaise go bhfuil an comhbhrú míchumraithe — seiceáil ar dtús an raibh
an t-aschur uirlise bunúsach iomarcach i ndáiríre.

---

## Amharcléiriú ar Choigilteas Comharthaí

```
Gan chomhbhrú:        47K comhartha seolta chuig LLM
Le Lite:               40K comhartha seolta          (15% sábháilte — sábháilte, ar siúl i gcónaí)
Le Standard:           33K comhartha seolta          (30% sábháilte — rialacha cainte Caveman)
Le Aggressive:         24K comhartha seolta          (50% sábháilte — aosú + achoimriú)
Le Ultra:              12K comhartha seolta          (75% sábháilte — bearradh heorastúil)
Le RTK:                19K-5K comhartha seolta       (60-90% sábháilte ar aschur ordaithe/uirlise)
Le Stacked:            10K-2.5K comhartha seolta     (raon incháilithe RTK+Caveman 78-95%)
```

---

## Cumraíocht

### Painéal

Téigh chuig `Dashboard → Context & Cache`:

- **Caveman** — roghnú móid, pacáistí teanga, réamhamharc, agus réamhshocruithe domhanda
- **RTK** — réamhamharc ar scagadh orduithe, socruithe sábháilteachta RTK, agus catalóg scagairí
- **Teaglamaí Comhbhrúite** — píblínte innill ainmnithe a shanntar do theaglamaí ródaithe
- **Tairseach Uathspreagtha** — cuir comhbhrú i ngníomh go huathoibríoch nuair a sháraíonn líon na dticeáil an tairseach

### Sárú de réir Teaglama

In `Dashboard → Context & Cache → Compression Combos`, sann teaglama comhbhrúite do theaglama
ródaithe:

```txt
Combo: "free-tier-fallback"
  Compression Combo: "coding-agent-stack"
  Pipeline: RTK -> Caveman
  Targets:
    1. if/kimi-k2.7-code
    2. if/qwen3.8-max-preview
```

Ligeann sé seo duit comhbhrú cruachta a úsáid le soláthraithe saor in aisce/códúcháin agus mód éadrom
a choinneáil ar shíntiúis íoctha.

Is rialtán ar leith é an sannadh "Sárú de réir Teaglama" seo ón sárú **mód comhbhrúite an teaglama
ródaithe** (Default/Off/Lite/Standard/Aggressive/Ultra/Codex Responses — glacann scéimre an réimse
le `rtk`, `stacked` agus `omniglyph` freisin) — ní roghnaíonn an sárú sin píblíne ainmnithe
teaglama comhbhrúite; ní dhéanann sé ach an réimse `compressionMode` a shocrú, rud a úsáideann
`resolveCompressionPlan`. Is féidir é a shocrú ar chárta an teaglama (`Dashboard → Combos`) nó, ó
#6760 i leith, de réir teaglama ródaithe sa liosta "Assign to routing" ar
`Dashboard → Context & Cache → Compression Combos`, díreach in aice leis an ticbhosca sanntha píblíne
atá doiciméadaithe thuas. Déanann an dá chomhéadan na sonraí a bhuanú tríd an gcríochphointe céanna `PUT /api/combos/{id}`.

### Sárú de réir iarratais

Seol ceanntásc iarratais `x-omniroute-compression` chun an plean comhbhrúite a shárú d'iarratas
amháin. Tá an tosaíocht is airde aige — sáraíonn sé sárú an teaglama ródaithe, an phróifíl ghníomhach,
an t-uathspreagadh, agus socrú Default an phainéil. Déantar neamhaird de luachanna anaithnide (ní dhiúltaítear
don iarratas riamh) agus rialaíonn an máistirlasc domhanda gach rud fós: nuair atá comhbhrú múchta go
domhanda, ní féidir leis an gceanntásc é a chasadh air. Luachanna:

| Luach         | Éifeacht                                                                                                                    |
| ------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `off`         | Gan aon chomhbhrú don iarratas seo.                                                                                         |
| `default`     | Próifíl Default a dhíorthaítear ón bpainéal (déantar neamhaird den phróifíl ghníomhach). Fágtar innill chaillteacha múchta. |
| `safe`        | Mar a bheadh an ceanntásc fágtha ar lár: dídhúbláil agus fillte bánspáis amháin.                                            |
| `allow-lossy` | Coinnigh plean oibreora an iarratais seo, lena n-áirítear achoimrí, scagairí ábharthachta, agus athscríobh stíle.           |
| `engine:<id>` | Inneall aonair nuair atá sé cumasaithe, e.g. `engine:rtk`. Seo é an rogha isteach de réir iarratais don inneall sin.        |
| `<combo>`     | Teaglama ainmnithe, meaitseáilte de réir ainm (gan beann ar chás) ar dtús, agus ansin de réir aitheantais.                  |

Gan `allow-lossy`, `engine:<id>`, nó teaglama ainmnithe, ní chuirtear innill chaillteacha i bhfeidhm.
Faigheann an t-iarratas dídhúbláil seisiúin agus fillte bánspáis fós nuair atá comhbhrú ar siúl.

Seoltar an plean a cuireadh i bhfeidhm ar ais i gceanntásc freagartha `X-OmniRoute-Compression: <mode>; source=<source>`,
áit a bhfuil `<source>` ar cheann de `request-header`, `routing-override`, `active-profile`,
`auto-trigger`, `default`, nó `off`.

### API

```bash
# Faigh na socruithe comhbhrúite
curl http://localhost:20128/api/settings/compression

# Nuashonraigh na socruithe comhbhrúite
curl -X PUT http://localhost:20128/api/settings/compression \
  -H "Content-Type: application/json" \
  -d '{"defaultMode":"stacked","autoTriggerMode":"stacked","autoTriggerTokens":32000}'

# Réamhamharc ar phálasta sonrach RTK/cruachta
curl -X POST http://localhost:20128/api/compression/preview \
  -H "Content-Type: application/json" \
  -d '{"mode":"rtk","messages":[{"role":"tool","content":"npm test output here"}]}'

# Liostaigh pacáistí scagairí RTK
curl http://localhost:20128/api/context/rtk/filters

# Tástáil RTK go díreach le meiteashonraí roghnacha ordaithe
curl -X POST http://localhost:20128/api/context/rtk/test \
  -H "Content-Type: application/json" \
  -d '{"command":"npm test","text":"FAIL tests/example.test.ts\nError: boom"}'
```

---

## An Méid a Chosnaítear

Caomhnaíonn an t-inneall comhbhrúite **na nithe seo i gcónaí:**

- ✅ Bloic chóid (fálaithe agus inlíne)
- ✅ URLanna agus conairí comhaid
- ✅ Struchtúir JSON agus sonraí struchtúrtha
- ✅ Aitheantóirí agus comharthaí teicniúla cosanta
- ✅ Sloinn mhatamaiticiúla
- ✅ Sainmhínithe ar ghlaonna uirlisí/feidhmeanna
- ✅ Leideanna córais (sa mhód lite)

Folaíonn aisghabháil aschuir amh RTK eochracha coitianta API, comharthaí iompróra, comharthaí Slack, eochracha rochtana AWS,
pasfhocail, comharthaí, agus rúin sula ndéantar aon rud a bhuanú.

---

## Staitisticí Comhbhrúite

Bíonn staitisticí i logaí an fhreastalaí i ngach iarratas comhbhrúite:

```json
{
  "originalTokens": 47200,
  "compressedTokens": 40120,
  "savingsPercent": 15.0,
  "techniquesUsed": ["collapseWhitespace", "dedupSystemPrompt"],
  "mode": "lite",
  "engine": "caveman",
  "compressionComboId": "coding-agent-stack",
  "durationMs": 0.8,
  "rtkRawOutputPointers": []
}
```

---

## Treochlár na gCéimeanna

| Céim    | Móid                                                                                                                                                         | Stádas    |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- |
| Céim 1  | Off, Lite                                                                                                                                                    | ✅ Seolta |
| Céim 2  | Standard, Aggressive, Ultra                                                                                                                                  | ✅ Seolta |
| Céim 3  | RTK, Stacked, Compression Combos                                                                                                                             | ✅ Seolta |
| Céim 4  | Output Styles, SLM-tier Ultra, eval harness                                                                                                                  | ✅ Seolta |
| Céim 4C | Buiséad comhthéacs oiriúnaitheach ("dial") — inneall ríomha + API (`contextBudget` ar `PUT /api/settings/compression`) + rialuithe móid/beartais ar an deais | ✅ Seolta |

---

## Buíochas

Tá rialacha comhbhrúite an mhóid Standard spreagtha ag **[Caveman](https://github.com/JuliusBrussee/caveman)** le **[JuliusBrussee](https://github.com/JuliusBrussee)** (⭐ 51K+) — an tionscadal víreasach "cén fáth mórán comhartha a úsáid nuair a dhéanann beagán comhartha an gnó". Tuairiscíonn Caveman `~75%` níos lú comharthaí aschuir, meánchoigilteas aschuir `65%` i dtagarmharcanna, raon aschuir `22-87%`, agus uirlis comhbhrúite ionchuir `~46%`.

Tá mód RTK spreagtha ag **[RTK - Rust Token Killer](https://github.com/rtk-ai/rtk)** le **[RTK AI](https://github.com/rtk-ai)** — an tionscadal ardfheidhmíochta chun aschur orduithe a chomhbhrú le haghaidh teirminéil, tógála, tástála, git, agus scagadh aschuir uirlisí. Tuairiscíonn RTK coigilteas `60-90%`, agus léiríonn an seisiún samplach ina README gur sábháladh `~80%`.

---

## Ardchórais Chomhbhrúite

Taobh amuigh de na 7 mód a bhfuil cur síos orthu thuas (glacann an fhoinse leis na móid `codex-responses` agus
`omniglyph` freisin, nach gclúdaítear sa treoir seo), clúdaíonn na rannáin thíos gnéithe
a oibríonn laistigh de na móid sin nó taobh leo: is iad Comhbhrú Torthaí Uirlisí agus Aosú Forchéimnitheach
céimeanna 1 agus 2 den inneall ionsaitheach (mód Ionsaitheach agus céim `aggressive` de
phíblíne chruachta), is í an Phíblíne Chruachta an chaoi a ritheann an mód Cruachta, déanann Comhbhrú
Feasach ar an Taisce `aggressive` agus `ultra` a íosghrádú go `standard` do sholáthraithe taisceála fad a bhíonn comhbhrú
ar siúl, agus is treoracha roghnacha i leid an chórais iad Mód Aschuir Uaimheora agus Stíleanna Aschuir,
atá múchta de réir réamhshocraithe, agus a mhúnlaíonn aschur na samhla seachas an t-iarratas a chomhbhrú.

### Comhbhrú Feasach ar an Taisce

Tacaíonn roinnt soláthraithe (amhail Anthropic le taisceáil leid) le **taisceáil leid**,
rud a ligeann dóibh codanna den leid a chur i dtaisce chun costais agus aga folaigh a laghdú. Nuair a
bhíonn taisceáil cumasaithe, is féidir le comhbhrú ionsaitheach **dochar** a dhéanamh don fheidhmíocht
toisc go n-athraíonn sé na comharthaí atá i dtaisce, rud a dhéanann an taisce neamhbhailí.

Réitíonn an modúl `cachingAware.ts` é seo trí **chomhthéacs taisceála a bhrath** agus
**an straitéis chomhbhrúite a choigeartú** dá réir.

#### Conas a oibríonn sé

1. **Comhthéacs taisceála a bhrath** — Scanann sé corp an iarratais le haghaidh marcóirí `cache_control`
2. **Soláthraithe taisceála a aithint** — Seiceálann sé an dtacaíonn an spriocsholáthraí le taisceáil
3. **An straitéis a choigeartú** — Íosghrádaíonn sé `aggressive`/`ultra` go `standard` do sholáthraithe taisceála
4. **Leid an chórais a scipeáil** — Is gnách go mbíonn leideanna córais i dtaisce, mar sin ná comhbhrúigh iad

Tugann an cúntóir straitéise bratach `deterministicOnly` ar ais freisin, ach ní úsáideann an tógálaí plean
ach an straitéis — ní léann aon rud níos faide síos an slabhra an bhratach faoi láthair.

#### Sampla cóid

```ts
import {
  detectCachingContext,
  getCacheAwareStrategy,
} from "@omniroute/open-sse/services/compression/cachingAware";

const body = {
  model: "anthropic/claude-sonnet-4.5",
  messages: [{ role: "user", content: "Hello" }],
  cache_control: { type: "ephemeral" }, // ← Marcóir taisce
};

const ctx = detectCachingContext(body, { provider: "anthropic" });
// → { hasCacheControl: true, provider: "anthropic", targetFormat: null, isCachingProvider: true }

const strategy = getCacheAwareStrategy("aggressive", ctx);
// → { strategy: "standard", skipSystemPrompt: true, deterministicOnly: true }
```

#### Cathain is ceart é a úsáid

Bíonn comhbhrú feasach ar an taisce **ar siúl i gcónaí** — ní gá aon chumraíocht a dhéanamh. Cuirtear i ngníomh é aon uair
a bhíonn comhbhrú ar siúl agus a dtacaíonn an spriocsholáthraí le taisceáil leid (Anthropic, OpenAI,
srl.); ní theastaíonn marcóirí sainráite `cache_control` — is leor soláthraí taisceála leis féin
chun an t-íosghrádú a spreagadh, agus ní dhéanann marcóirí leo féin amhlaidh riamh (cuireann brath marcóirí sonraí ar fáil do theiliméadracht
taisce, ní don chinneadh straitéise).

### Aosú Forchéimnitheach

Carnann comhráite fada go leor sealanna teachtaireachta, ach éiríonn sealanna níos sine níos lú
ábhartha. Déanann an modúl `progressiveAging.ts` **teachtaireachtaí a dhíghrádú de réir fhaid an tseala**
(an fad arna thomhas ó dheireadh an chomhrá). Leis na réamhshocruithe a sheoltar
(`verbatim: 2, light: 2, moderate: 3`):

- **An 2 sheal deiridh (fad ≤ 2)**: Coinnítear focal ar fhocal iad
- **Fad 3**: Comhbhrú Uaimheora (focail líonta a bhaint)
- **Fad 4+**: Déantar achoimre ar theachtaireachtaí an chúntóra; laghdaítear teachtaireachtaí úsáideora go dtí a gcéad
  líne, le huasteorainn 120 carachtar; ní athraítear róil eile. Coinnítear leideanna córais, teachtaireachtaí
  atá aosaithe cheana agus an teachtaireacht úsáideora is déanaí focal ar fhocal i gcónaí, beag beann ar an bhfad.
  Ní chaitear aon rud amach go hiomlán, agus ní féidir an banda `light`
  a bhaint amach leis na réamhshocruithe a sheoltar (tá `light` cothrom le `verbatim`).

#### Sampla cóid

```ts
import { applyAging } from "@omniroute/open-sse/services/compression/progressiveAging";

const messages = [
  { role: "system", content: "You are a helpful assistant" },
  { role: "user", content: "What is 2+2?" },
  { role: "assistant", content: "4" },
  // ... 50 seal eile ...
];

const { messages: aged, saved } = applyAging(messages, {
  verbatim: 3, // na 3 sheal dheireanacha: focal ar fhocal
  light: 8, // fad <= 8: comhbhrú éadrom
  moderate: 20, // fad <= 20: comhbhrú uaimheora
  fullSummary: 5, // riachtanach de réir an chineáil, ní léann an cód bandála é
  // fad > 20: achoimrithe (cúntóir) / coinnítear an chéad líne (úsáideoir)
});

// saved = líon na gcomharthaí a sábháladh
```

#### Cathain is ceart é a úsáid

Bíonn aosú forchéimnitheach **ar siúl i gcónaí** don mhód `aggressive` — is é céim 2 de
`compressAggressive()` é. Ní ritheann an mód Ultra é. Tá sé
an-éifeachtach go háirithe le haghaidh:

- Seisiúin fhada códaithe
- Comhráite a mhaireann roinnt laethanta
- Sreafaí oibre gníomhairíocha ina mbíonn go leor glaonna uirlise

### Mód Aschuir Uaimheora

Cuireann mód aschuir uaimheora **treoracha i leid an chórais** leis a iarrann ar an tsamhail féin
aschur gonta a thabhairt — iarrann an leibhéal `lite` freagraí achomair a choinníonn abairtí iomlána, iarrann `full`
uirthi "freagairt go gonta mar uaimheoir cliste", agus iarrann `ultra` aschur teileagrafach;
ní dhéanann na treoracha ach é sin a iarraidh, ní féidir leo é a ráthú. Faigheann iarratais iad trí
`applyOutputStyles()` (`open-sse/services/compression/outputStyles/apply.ts`):
réitíonn `open-sse/handlers/chatCore.ts` an roghnú ar dtús leis an oiriúntóir comhoiriúnachta siarghabhálaí
(`resolveOutputStyleSelection()` in
`open-sse/services/compression/outputStyles/backCompat.ts`), a mhapálann, fad atá `outputStyles`
folamh, `cavemanOutputMode` cumasaithe chuig an stíl aschuir `terse-prose` ag
`cavemanOutputMode.intensity` (féach Comhoiriúnacht siarghabhálach thíos); úsáidtear roghnú
`outputStyles` nach bhfuil folamh mar atá, agus ní bhíonn aon éifeacht ag `cavemanOutputMode.enabled` ná
`intensity` ansin, cé go mbíonn feidhm fós ag a lasc `autoClarity`. Coinníonn `outputMode.ts`
téacsanna na dtreoracha (`CAVEMAN_INSTRUCTION_BY_LANGUAGE`), an seachbhóthar ábhair agus an
cúntóir suímh a úsáideann an t-instealladh; níl aon ghlaoiteoir táirgthe ag a insteallaire
`applyCavemanOutputMode()` féin.

#### Conas a oibríonn sé

Ní dhéanann an mód seo an t-ionchur a chomhbhrú. Cuireann sé bloc treoracha le leid an chórais
(féach Conas a oibríonn an t-instealladh thíos), agus ritheann aon mhód comhbhrúite ionchuir a roghnaítear don iarratas
ina dhiaidh sin fós, ar an gcorp a bhfuil an bloc ann anois. Roimh an gclásal comhroinnte
teorainneacha a chríochnaíonn gach leibhéal leis, deir an leibhéal Béarla `full`:

> "Freagair go gonta mar uaimhfhear cliste. Fág ailt (a/an/the), focail líonta (just/really/basically/actually/simply), cúirtéisí agus maolú cainte ar lár. Tá blúirí ceart go leor. Comhchiallaigh ghearra (big seachas extensive, fix seachas implement). Coinnigh an tsubstaint theicniúil ar fad, an cód, na hearráidí, na URLanna agus na haitheantóirí cruinn."

Oibríonn sé seo go han-mhaith do:

- Giniúint cóid (aschur níos gonta = níos lú comharthaí)
- Ceisteanna agus freagraí tapa (níl gá le mínithe mionsonraithe)
- Baiscphróiseáil (uasmhéadaigh an tréchur)

#### Cathain ba cheart é a úsáid

Is gné **roghnach** é mód aschuir an uaimhfhir. Agus an comhbhrú ar siúl (`enabled: true`, an príomhscorán
ar an leathanach Socruithe Comhbhrúite), cuir ar siúl é le `cavemanOutputMode.enabled`; roghnaíonn `intensity`
`lite`, `full` nó `ultra`:

```json
{
  "enabled": true,
  "cavemanOutputMode": {
    "enabled": true,
    "intensity": "full"
  }
}
```

Socraíonn scorán **Mód Aschuir** teaglama comhbhrúite (`outputMode`, leis an leibhéal in `outputModeIntensity`)
an lasc céanna do na hiarratais lena mbaineann an teaglama sin, agus scríobhann uirlis MCP
`omniroute_set_compression_engine` é trína hargóint Boole `outputMode`. Bíonn tosaíocht ag roghnúchán
`outputStyles` nach bhfuil folamh ar an lasc seo. Sa deais, insteallann cumasú stíl aschuir **Prós gonta**
an bloc céanna (féach Stíleanna Aschuir thíos).

### Stíleanna Aschuir (catalóg)

Is é mód aschuir an uaimhfhir thuas an **chonair oidhreachta aonstíle**. Ghinearáltaigh Céim 4 é
ina chatalóg de stíleanna aschuir inchumtha: `OUTPUT_STYLE_CATALOG` in
`open-sse/services/compression/outputStyles/catalog.ts`. Is treoir leid chórais gach stíl
a iarrann ar an tsamhail féin aschur níos saoire a thabhairt; is féidir stíleanna a chumasú
le chéile agus instealltar iad in ord na catalóige.

| Stíl                                              | `id`            | A ndéanann sé                                                                                                                                                                                                                                                                                           | Teangacha treoracha                           |
| ------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| Prós gonta                                        | `terse-prose`   | Fág focail líonta/ailt/maolú cainte ar lár; coinnigh an tsubstaint theicniúil cruinn. An téacs céanna le mód oidhreachta aschuir an uaimhfhir (déantar tagairt dó, ní athscríobhtar é).                                                                                                                 | en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi |
| Níos lú cóid                                      | `less-code`     | Dréimire YAGNI: an t-athrú oibre is lú, gan astarraingtí nár iarradh.                                                                                                                                                                                                                                   | en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi |
| Eireaball capaill (forbróir sinsearach leisciúil) | `ponytail`      | "Is é an cód is fearr an cód nach scríobhtar riamh": athúsáid > athscríobh, bunchúis > siomptóm, an difríocht oibre is giorra.                                                                                                                                                                          | en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi |
| Tá ADHD orm (gníomh ar dtús)                      | `i-have-adhd`   | Gníomh ar dtús (ordú/conair/blúire roimh phrós), céimeanna uimhrithe teoranta, AON chéad chéim nithiúil eile, gan bhrollach/achoimre/clabhsúr. Oiriúnaithe ó [ayghri/i-have-adhd](https://github.com/ayghri/i-have-adhd) (MIT).                                                                         | en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi |
| Scagaire comhéadain antislop                      | `antislop-ui`   | Caithfidh gach teicníc amhairc triail chuspóra a shárú (ordlathas, féiniúlacht, inléiteacht); gan grádáin/gloine/luisne réamhshocraithe, pailéad teoranta, ná leagan amach teimpléid. Cuireann an dá stíl antislop teorainn leis freisin a chuireann cosc ar rialtáin neamhfheidhmiúla / maímh chumtha. | en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi |
| Scagaire antislop do chóip agus do dhaoine        | `antislop-copy` | Cóip shonrach (gan eim-dais, CTAanna cineálacha, focail fhaiseanta, clabhsúir bota comhrá ná fíricí cumtha), chomh maith le rialacha do dhaoine: codarsnacht WCAG AA, fócas infheicthe, rochtain méarchláir, staideanna folmha/lódála/earráide, athshreabhadh móibíleach.                               | en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi |
| CJK gonta (文言)                                  | `terse-cjk`     | Freagra `full`/`ultra` i Sínis Chlasaiceach (文言); ní iarrann `lite` ach freagraí gairide gan focail fheidhme, cúirtéisí ná maisiú.                                                                                                                                                                    | zh (faoi réir logchaighdeáin, féach thíos)    |

Tagann trí leibhéal déine le gach stíl — `lite`, `full`, `ultra` — agus críochnaíonn gach leibhéal
leis an gclásal comhroinnte teorainneacha (`SHARED_BOUNDARIES` in `outputMode.ts`), a choinníonn
bloic chóid, conairí comhaid, orduithe, earráidí agus URLanna cruinn. Cuireann téacsanna leibhéil
`terse-prose` agus `terse-cjk` aitheantóirí leis an liosta sin.

Tá `terse-cjk` teoranta de réir logchaighdeáin do `zh` in dhá áit. Ní liostaíonn an leathanach Socruithe Comhbhrúite
a ró ach amháin nuair is Sínis teanga chomhéadain na deaise (`zh-CN` nó `zh-TW`), agus
ní insteallann `applyOutputStyles()` é ach amháin nuair is `zh` teanga réitithe an iarratais (féach Roghnú
Teanga thíos). Ní ghlanann cur an ró i bhfolach roghnúchán sábháilte `terse-cjk`:
glacann API na socruithe le haon id stíle, agus coinnítear é nuair a shábháiltear stíleanna eile ar an leathanach. Ag
am an iarratais, is é seiceáil teanga `applyOutputStyles()` an t-aon gheata logchaighdeáin.

#### Conas a oibríonn an t-instealladh

Réitíonn `applyOutputStyles()` (`open-sse/services/compression/outputStyles/apply.ts`)
an roghnúchán i gcoinne na catalóige (fágtar aitheantais anaithnide agus stíleanna nach
bhfuil ag teacht leis an logchaighdeán ar lár, gan earráid riamh; má réitítear roghnúchán
gan aon stíl, fágtar an corp gan athrú agus scipeáiltear é mar `no_styles`), comhcheanglaíonn
sé na treoracha roghnaithe in ord na catalóige,
iarcheanglaíonn sé an clásal teorainneacha **uair amháin** (mar aon leis an gclásal
sábháilteachta, `SAFETY_BOUNDARIES` nó a aistriúchán, nuair a roghnaítear `less-code` nó
`ponytail`), agus tosaíonn sé an bloc le marcóir idéimitheachta amháin
(`[OmniRoute Output Styles]`), ionas nach ndéanann athchur i bhfeidhm aon rud. Nuair a
bhíonn aistriúchán ar fáil don teanga réitithe (féach Roghnú teanga thíos), instealltar
an treoir logánaithe in ionad an Bhéarla.

Ar chorp a bhfuil eagar `messages` neamhfholamh aige, ritear an tseiceáil idéimitheachta
roimh an seachbhóthar inneachair: nuair atá an marcóir `[OmniRoute Output Styles]`
cheana féin sa réimse barrleibhéil `system` (teaghrán nó eagar bloic inneachair) nó i
dteachtaireacht chórais a bhfuil inneachar teaghráin aici, fágtar an corp gan athrú mar
`already_applied` agus ní ritear aon seiceáil eochairfhocal. Seachas sin, seiceálann
seachbhóthar inneachair (`shouldBypassCavemanOutputMode()` in
`open-sse/services/compression/outputMode.ts`) téacs na dtrí theachtaireacht dheireanacha,
is cuma cén ról atá acu, agus scipeálann sé na stíleanna don idirghníomh iomlán nuair a
mheaitseálann an téacs sin a chuid eochairfhocal slándála, gnímh dho-aisiompaithe nó
soiléirithe, nó seicheamh atá íogair d’ord: `first`, `then`, `after that`, `before`,
`rollback` nó `backup` agus `delete`, `drop`, `migrate`, `deploy` nó `release` ina
ndiaidh laistigh de 240 carachtar. Ritheann an seachbhóthar fad atá an scorán
**Auto-Clarity Bypass** (`cavemanOutputMode.autoClarity`, casta air de réir réamhshocraithe)
ar siúl; má chastar an scorán as, scipeáiltear an tseiceáil eochairfhocal.

Nuair a ligeann an seachbhóthar don idirghníomh dul ar aghaidh, cuireann
`placeSystemInstruction()` (sa chomhad céanna), nach gcruthaíonn `messages[0]` nua riamh,
an bloc sa chéad áit díobh seo a aimsíonn sé:

1. Teachtaireacht chórais tosaigh a bhfuil inneachar teaghráin aici: iarcheanglaítear an
   bloc i ndiaidh a téacs.
2. An réimse barrleibhéil `system`: iarcheanglaítear an bloc i ndiaidh théacs teaghráin,
   nó cuirtear leis mar bhloc téacs nua in eagar bloic inneachair é.
3. An chéad teachtaireacht chórais níos déanaí a bhfuil inneachar teaghráin aici:
   iarcheanglaítear an bloc i ndiaidh a téacs.
4. Mura mbaineann aon cheann díobh seo: cuirtear an bloc i dteachtaireacht chórais nua ag
   deireadh `messages`.

Ar chorp gan eagar `messages` (nó a bhfuil ceann folamh aige), ní ritear aon seachbhóthar
inneachair agus ní bhreathnaítear ar réimse barrleibhéil `system`. Iarcheanglaítear an
bloc i ndiaidh théacs réimse teaghráin `instructions`, ach amháin má tá an marcóir
`[OmniRoute Output Styles]` sa réimse sin cheana féin, agus sa chás sin fágtar an corp
gan athrú mar `already_applied`. Nuair nach bhfuil réimse teaghráin `instructions` ag
an gcorp ach go bhfuil `input` aige (teaghrán nó eagar), déantar `instructions` den
bhloc, agus cuirtear é in ionad aon luacha neamhtheaghráin a bhí sa réimse sin. Fágtar
corp nach bhfuil réimse teaghráin `instructions` ná `input` atá ina theaghrán nó ina
eagar aige gan athrú agus scipeáiltear é mar `no_messages`.

#### Conas é a chumasú

Sa deais: **Comhthéacs Comhbhrúite → Socruithe Comhbhrúite**
(`/dashboard/context/settings`), rannán na stíleanna aschuir: ró amháin in aghaidh na
stíle le scorán air/as agus roghnóir leibhéil. Instealltar stíleanna fad atá an comhbhrú
féin ar siúl (máistirscorán an leathanaigh, `enabled`). Tá an scorán
**Auto-Clarity Bypass** ar an leathanach **Caveman**
(`/dashboard/context/caveman`), ina chárta **Output Mode**. Go ríomhchláraitheach,
coinníonn an chumraíocht chomhbhrúite an roghnúchán mar:

```json
{
  "outputStyles": [
    { "id": "i-have-adhd", "level": "full" },
    { "id": "less-code", "level": "lite" }
  ]
}
```

Comhoiriúnacht siarghabhálach: fad atá `outputStyles` folamh, mapálann an socrú
oidhreachta `cavemanOutputMode.enabled` go `terse-prose` ag
`cavemanOutputMode.intensity`. Tosaíonn an bloc ansin leis an marcóir
`[OmniRoute Output Styles]`, san áit ar insteall an t-insteallaire oidhreachta
`applyCavemanOutputMode()` `[OmniRoute Caveman Output Mode]`. Faoin marcóir, meaitseálann
an téacs an t-instealladh oidhreachta in en, pt-BR, es, de, fr, it, ru, id agus vi; in
ja agus zh tá spás breise amháin ann roimh an gclásal teorainneacha. Aistrítear
`terse-prose` go pt-BR, es, de, fr, it, ru, zh, ja, id agus vi, mar sin faigheann iarratas
arb é `hu` a theanga réitithe an téacs Béarla san áit ar úsáid an t-insteallaire
oidhreachta a théacs Ungáirise.

Roghnú teanga na stíleanna aschuir (`resolveOutputStyleLanguage()` in
`outputStyles/apply.ts`): agus `languageConfig.enabled` ar siúl, samplálann `autoDetect`
an teachtaireacht úsáideora is déanaí in eagar `messages` an iarratais a bhfuil téacs
aici (inneachar teaghráin, nó `text` a codanna inneachair) agus ritheann sé brathadóir
inneall Caveman (`detectCompressionLanguage()`) uirthi. Filleann an brathadóir `zh` do
théacs a bhfuil carachtair Han ann ach gan kana; seachas sin, filleann sé cibé ceann de
`it`, `pt-BR`, `es`, `de`, `fr`, `ru`, `ja`, `hu` agus `id` a bhfuil an líon is mó
meaitseálacha leide aige, agus `en` nuair nach meaitseálann ceann ar bith — faigheann
téacs nach féidir leis a aicmiú Béarla, ní `defaultLanguage` riamh, agus ní bhraitear
`vi` riamh cé go gcuirtear téacs `vi` ar fáil leis na stíleanna. Coinníonn corp Responses
API a idirghníomhaíochtaí in `input`, rud nach sampláiltear, mar sin faigheann sé
`defaultLanguage`, agus ansin Béarla. Nuair nach bhfuil téacs in aon teachtaireacht
úsáideora in `messages`, nó nuair atá `autoDetect` as, cuirtear `defaultLanguage` i
bhfeidhm, agus ansin Béarla. Agus `languageConfig.enabled` as, is é Béarla an teanga —
ach amháin má chuirtear teaglaim chomhbhrúite i bhfeidhm ar an iarratas (teaglaim atá
sannta do theaglaim ródaithe an iarratais, nó an teaglaim chomhbhrúite réamhshocraithe a
úsáideann chatCore mar chúltaca don phíblíne chruachta ionsuite): trí theaglaim a chur i
bhfeidhm, castar `languageConfig.enabled` air don iarratas sin agus socraítear
`defaultLanguage` ó phacáistí teanga na teaglaime (an luach sábháilte más ceann de
phacáistí na teaglaime é, nó céad phacáiste na teaglaime murab ea, arb é `en` é de réir
réamhshocraithe), agus tá feidhm fós ag an `autoDetect` sábháilte (ar siúl de réir
réamhshocraithe). Roghnaíonn inneall ionchuir Caveman teanga a phacáiste rialacha ar
bhealach eile — de réir gach coda téacs agus, nuair atá uathbhrath as, faoi réir
`enabledPacks`.

Tá an mhaitrís stíle × teanga socraithe ag
`tests/unit/compression/output-styles-i18n-matrix.test.ts`: teastaíonn iontráil i
`BASELINE_LANGUAGES` na tástála ó gach stíl sa chatalóg; ní mór do stíl nach bhfuil
teoranta de réir logchaighdeáin aistriúchán pt-BR a sholáthar (tá an stíl
`terse-cjk`, atá teoranta de réir logchaighdeáin, díolmhaithe ón riail seo), mura bhfuil
sí liostaithe in `KNOWN_ENGLISH_ONLY`, nach bhféadfaidh ach stíleanna nach bhfuil aon
aistriúchán acu ar chor ar bith a bheith ann — má tá aon aistriúchán ag stíl liostaithe,
teipeann ar an tástáil; agus teipeann ar stíl sa tástáil má chailleann sí teanga atá
liostaithe ina hiontráil `BASELINE_LANGUAGES`. Chun stíl a chur leis, féach
[EXTENDING_COMPRESSION.md](./EXTENDING_COMPRESSION.md#adding-an-output-style).

### Comhbhrú Torthaí Uirlise

Comhbhrúnn `compressToolResult()` in
`open-sse/services/compression/toolResultCompressor.ts` téacs toraidh uirlise le **5
straitéis**. Baineann sé triail astu san ord seo, agus is í an chéad straitéis chumasaithe
a dtagann a seiceáil leis an ábhar a chinneann an toradh:

1. **`fileContent`**: maidir le hábhar ina bhfuil 3 líne nó níos mó agus ina dtosaíonn
   líne amháin ar a laghad, gan an eangú tosaigh a chur san áireamh, le `import `,
   `export `, `function `, `class `, `const `, `let `, `var ` nó `return ` (an
   eochairfhocal agus spás ina dhiaidh), nó le `if`, `for` nó `while` agus `(` nó ` (`
   ina ndiaidh, coimeádann sé an chéad 20 líne agus na 5 líne dheireanacha, agus
   marcáiltear an lár atá fágtha ar lár.
2. **`grepSearch`**: maidir le hábhar ina bhfuil líne amháin ar a laghad den fhoirm
   `<path>:<digits>:`, áit nach bhfuil aon spás bán sa téacs roimh an gcéad idirstad,
   ní choinníonn sé ach na línte sin, suas le 30, agus ina ndiaidh sin comhaireamh ar aon
   mheaitseálacha eile agus liosta na gcomhad meaitseáilte; caitear gach líne eile
   amach. Is leor líne amháin den sórt sin chun an straitéis a ghníomhachtú, mar sin
   áirítear freisin líne loga a thosaíonn le stampa ama amhail `12:30:45`.
3. **`shellOutput`**: maidir le haschur ina bhfuil seicheamh ANSI CSI (`ESC[` agus
   digití nó leathstadanna ansin agus litir ina ndiaidh, mar atá i gcóid datha) nó `$`
   agus spás bán ina dhiaidh áit ar bith sa téacs, baintear na seichimh sin de (coimeádtar
   éaluithe eile, amhail `ESC[?25l` nó seicheamh teidil fuinneoige OSC) agus coimeádtar
   na 50 líne dheireanacha, agus línte comhleanúnacha athfhillteacha cúngaithe ina líne
   amháin. Toisc go ritear an tseiceáil seo roimh `json` agus `errorMessage`, ní
   shroicheann aschur JSON ná aschur earráide ina bhfuil `$` den sórt sin iad choíche
   fad atá `shellOutput` ar siúl.
4. **`json`**: déantar achoimre ar phálasta JSON os cionn 2,000 carachtar a thosaíonn le
   `{` nó `[` (tar éis spás bán roghnach) agus a pharsálann: maidir le heagar ina bhfuil
   níos mó ná 7 mír, coimeádtar a chéad 5 mhír agus a 2 mhír dheireanacha agus a
   chomhaireamh iomlán; agus maidir le réad, coimeádtar a chéad 20 eochair, agus cuirtear
   ionadchoinneálaí `{…N keys}` in ionad gach luacha réada nó eagair neadaithe (i gcás
   eagair, is é N a fhad), chomh maith le marcóir `_remaining_<N>_keys` a chomhaireann
   na heochracha a fágadh ar lár tar éis an chéad 20. Cóipeáiltear luachanna scálacha ina
   n-iomláine, mar sin ní dhéantar ach réad ina bhfuil 20 eochair nó níos lú agus gan
   luachanna neadaithe a atheangú — gnóthaíonn réad íoslaghdaithe carachtair agus
   fanann sé gan athrú.
5. **`errorMessage`**: maidir le haschur ina bhfuil, áit ar bith agus i gcás litreacha ar
   bith, `error:`, `error ` (an focal agus spás ina dhiaidh, mar atá in `no error found`),
   `[error]`, `exception:`, `exception `, `[exception]` nó `traceback`, coimeádann sé a
   chéad líne, na chéad 10 líne eile agus na 3 líne dheireanacha, agus cuirtear marcóir
   `… [N frames elided] …` in ionad na línte eatarthu. Ní bhíonn an marcóir le feiceáil
   ach amháin nuair a leanann níos mó ná 13 líne an chéad líne, mar sin ní ghiorraítear
   aschur earráide ina bhfuil 14 líne nó níos lú (ag 12 nó 13 líne, déanann na 3 líne
   dheireanacha línte atá coinnithe cheana féin a athrá).

Tar éis do straitéis teacht le hábhar, fiú mura sábhálann sí tada, ní bhaintear triail as
na straitéisí níos déanaí. Nuair nach sábhálann an straitéis mheaitseála aon chomhartha
measta (fad ÷ 4, slánaithe suas) — mar shampla, comhad atá cosúil le cód agus ina bhfuil
25 líne nó níos lú, nó eagar JSON os cionn 2,000 carachtar ina bhfuil 7 mír nó níos lú —
coimeádann an t-inneall ionsaitheach an buntoradh uirlise: coimeádann an dá ghlaoiteoir
(`compressAggressive()` agus `compressAnthropicToolResultBlock()`) an bunleagan nuair
atá `saved` cothrom le 0 nó faoina bhun, cé go gcuireann `compressToolResult()` féin
aschur na straitéise sin ar ais fós. Ní hé céim an toraidh uirlise an focal deiridh: is
féidir le hachoimreoir cúltaca an innill teachtaireacht `tool` nó `function` atá níos
faide ná 8,192 carachtar (`maxTokensPerMessage`, 2,048, méadaithe faoi 4) a ghiorrú fós.

#### Cathain ba cheart é a úsáid

Is é comhbhrú torthaí uirlise céim 1 den inneall ionsaitheach
(`compressAggressive()` in `open-sse/services/compression/aggressive.ts`), mar sin
ritheann sé sa mhód Ionsaitheach agus i gcéim `aggressive` de phíblíne chruachta.
Comhbhrúnn sé teachtaireachtaí `tool` agus `function` ar chruth OpenAI agus an téacs
laistigh de bhloic `tool_result` Anthropic. Tá a lasc féin ag gach straitéis faoi
`aggressive.toolStrategies`, iad uile ar siúl de réir réamhshocraithe. Sa deais, tá na
lasca in amharc **Casta** leathanach Caveman fad atá an comhbhrú ar siúl agus gurb é
Ionsaitheach an mód réamhshocraithe.

### Píblíne Chruachta

Ritheann an mód cruachta **innill iolracha i seicheamh** — RTK ar dtús de ghnáth
(coigilteas 60-90% ar aschur uirlise), agus ansin Caveman ar an téacs atá fágtha
(coigilteas ionchuir ~46%). Nuair a chuirtear le chéile iad, sin é an **raon incháilithe
78-95%** (féach Matamaitic an Choigiltis Réamhtheachtaigh thuas):
`1 - (1 - 0.60..0.90) × (1 - 0.46)` ar meán ≈89%.

#### Conas a oibríonn sé

```
Ionchur (1000 comhartha)
  → RTK (scagaire a thuigeann orduithe) → 200 comhartha
    → Caveman (ábhar líonta a bhaint) → 108 comhartha
  → Aschur (108 comhartha, coigilteas ~89%)
```

#### Cathain ba cheart é a úsáid

Úsáid an mód cruachta le haghaidh:

- Sreafaí oibre atá trom ar uirlisí (códú gníomhaíoch, taighde)
- Baiscphróiseáil atá íogair ó thaobh costais de
- Nuair a theastaíonn an coigilteas comharthaí is mó uait

Cumraítear píblínte cruachta tríd an socrú comhbhrúcháin domhanda `stackedPipeline`,
nó trí theaglaim chomhbhrúcháin ainmnithe atá sannta do theaglaim ródúcháin (féach
Sárú de réir Teaglaim thuas) — ní trí `modePack` de theaglaim uathoibríoch (ní dhéanann
an réimse sin ach ualú roghnúchán samhla na teaglaime uathoibríche a athrú, agus ní ainm
bailí paca é `stacked`).

---

## Sáruithe Teaglaim Comhbhrúite

Is féidir leat an mód comhbhrúite domhanda a shárú **de réir teaglaim** chun an t-iompar a mhionchoigeartú
do chásanna úsáide éagsúla:

```json
{
  "id": "coding-combo",
  "strategy": "priority",
  "config": {
    "weights": { "taskFit": 0.5 },
    "modePack": "quality-first"
  },
  "compressionOverride": "aggressive"
}
```

Tá sé seo úsáideach do:

- **Teaglamaí códúcháin**: Úsáid an mód `aggressive` le haghaidh seisiúin fhada
- **Teaglamaí mearcheisteanna agus freagraí**: Úsáid an mód `lite` le haghaidh freagraí tapa
- **Teaglamaí ina n-úsáidtear go leor uirlisí**: Úsáid an mód `stacked` chun an choigilteas is mó a bhaint amach
- **Teaglamaí táirgthe**: fág an sárú múchta do sholáthraithe taisce — déanann an coigeartú
  feasach ar an taisce atá ar siúl i gcónaí `aggressive`/`ultra` a íosghrádú go `standard` go huathoibríoch
  (níl aon mhód `cache-aware` inroghnaithe ann)

---

## Féach Freisin

- [Cumraíocht Timpeallachta](../reference/ENVIRONMENT.md) — Athróga timpeallachta comhbhrúite
- [Treoir Ailtireachta](../architecture/ARCHITECTURE.md) — Oibriúchán inmheánach na píblíne comhbhrúite
- [Treoir Úsáideora](../guides/USER_GUIDE.md) — Tús a chur le comhbhrú
- [Comhbhrú RTK](./RTK_COMPRESSION.md) — Scagairí RTK, samhail iontaoibhe, geata fíoraithe, aisghabháil amh-aschuir
- [Innill Chomhbhrúite](./COMPRESSION_ENGINES.md) — Caveman, RTK, cruachta, APIanna, MCP, deais
- [Formáid Rialacha Comhbhrúite](./COMPRESSION_RULES_FORMAT.md) — Formáid pacáiste rialacha JSON
- [Pacáistí Teanga Comhbhrúite](./COMPRESSION_LANGUAGE_PACKS.md) — Rialacha Caveman a bhaineann go sonrach le teanga