# 🗜️ Prompt Compression Guide — OmniRoute (Kiswahili)

🌐 **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) · 🇮🇪 [ga](../../../ga/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) · 🇮🇳 [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)

---

> Okoa 15-95% ya muktadha unaostahiki kiotomatiki. Kwa muhtasari wa haraka, angalia [sehemu ya Ukandamizaji katika README](../README.md#%EF%B8%8F-prompt-compression--save-15-95-eligible-tokens-automatically).

## Muhtasari

OmniRoute hutekeleza mtiririko wa kimoduli wa ukandamizaji wa prompt unaoendeshwa **mapema** kabla maombi hayajafika kwa watoa huduma wa juu. Hii inamaanisha kuwa uokoaji wako wa tokeni hufanyika bila kuonekana — hakuna mabadiliko yanayohitajika katika mtiririko wako wa kazi.

```
Ombi la Mteja
  → Kiteuzi cha Mkakati wa Ukandamizaji
    → Kuna ubatilishaji wa combo? → Tumia mpangilio wa combo
    → Kiwango cha kuanzisha kiotomatiki? → Tumia hali ya auto
    → Hali chaguo-msingi? → Tumia mpangilio wa jumla
    → Imezimwa? → Ruka ukandamizaji
  → Hali ya Ukandamizaji Iliyochaguliwa
    → Off: Hakuna ukandamizaji
    → Lite: Usafishaji salama wa nafasi tupu/uumbizaji (~15%)
    → Standard: Uondoaji wa maneno ya ziada kwa mtindo wa Caveman (~30%)
    → Aggressive: Uchakavu wa historia + ufupishaji (~50%)
    → Ultra: Upogoaji wa kiheuristiki + upunguzaji wa vizuizi vya msimbo (~75%)
    → RTK: Uchujaji unaotambua amri wa matokeo ya terminal/zana (kiwango cha 60-90% kwa mtoa huduma wa juu)
    → Stacked: Mtiririko uliopangwa wa injini nyingi, kwa kawaida RTK kisha Caveman (kiwango cha 78-95% ya inayostahiki)
  → Ombi Lililokandamizwa → Mtoa Huduma
```

---

## Hali za Ukandamizaji

### Off

Hakuna ukandamizaji unaotumika. Ujumbe wote hupitishwa bila kubadilishwa.

### Hali ya Lite (uokoaji wa ~15%, ucheleweshaji wa <1ms)

Hali salama zaidi — hakuna mabadiliko ya maana, ni usafishaji wa uumbizaji pekee:

| Mbinu                    | Maelezo                                                 |
| ------------------------ | ------------------------------------------------------- |
| `collapseWhitespace`     | Unganisha mistari tupu inayofuatana na nafasi za mwisho |
| `dedupSystemPrompt`      | Ondoa ujumbe wa mfumo unaojirudia                       |
| `compressToolResults`    | Kandamiza matokeo marefu ya zana/vitendakazi            |
| `removeRedundantContent` | Ondoa maagizo yanayorudiwa                              |
| `replaceImageUrls`       | Fupisha URI za data za picha za base64                  |

**Inafaa zaidi kwa:** Matumizi ya kudumu, mitiririko ya kazi inayozingatia sana usalama.

### Hali ya Standard (uokoaji wa ~30%)

Imechochewa na [Caveman](https://github.com/JuliusBrussee/caveman) — huondoa maneno ya ziada na vifungu virefu huku ikihifadhi maana:

- Huondoa maneno ya ziada ("tafadhali", "nadhani", "kimsingi", "kwa hakika")
- Hufupisha vifungu virefu ("ili kuweza" → "ili", "kutokana na ukweli kwamba" → "kwa sababu")
- Huondoa lugha ya tahadhari yenye adabu ("Je, ungejali...", "Ikiwa ungeweza tafadhali...")
- Zaidi ya kanuni 30 za regex zilizoboreshwa kwa prompt za uandishi wa msimbo

**Inafaa zaidi kwa:** Mitiririko ya kila siku ya uandishi wa msimbo, timu zinazozingatia gharama.

### Hali ya Aggressive (uokoaji wa ~50%)

Usimamizi mahiri wa historia kwa vipindi virefu:

- **Uchakavu wa Ujumbe** — ujumbe wa zamani hukandamizwa hatua kwa hatua
- **Ukandamizaji wa Matokeo ya Zana** — matokeo marefu ya zana hukatwa au kuachwa (mistari ya kwanza/mwisho,
  uchujaji wa mistari inayolingana, ufupishaji wa funguo za JSON)
- **Vilinzi vya Uadilifu wa Muundo** — huhakikisha jozi za `tool_use` + `tool_result` zinabaki thabiti
- **Uelewa wa Dirisha la Muktadha** — huzingatia vikomo vya tokeni vya kila modeli

**Inafaa zaidi kwa:** Vipindi virefu vya utatuzi, hazina kubwa za msimbo.

### Hali ya Ultra (uokoaji wa ~75%)

Ukandamizaji wa juu zaidi kwa hali ambazo tokeni ni muhimu sana:

- **Upogoaji wa Kiheuristiki** — upogoaji wa tokeni za nathari kulingana na alama
- **Uhifadhi wa Muundo** — vizuizi vya msimbo vilivyozungushiwa uzio, msimbo wa ndani, URL na vitambulishi
  huwekewa alama za muda na kuunganishwa upya kama zilivyo, bila kupogolewa kamwe
- **Kiwango cha hiari cha SLM** — modeli ndogo ya ndani inaweza kuboresha upogoaji inaposanidiwa
- Hujitegemea kutoka kwa hali ya Aggressive: haiendeshi uchakavu wa ujumbe, ukandamizaji wa matokeo ya zana
  au kifupishaji cha dharura (ni hitilafu ya kiwango cha SLM pekee inayoweza kuelekeza upitishaji wa dharura kupitia
  aggressive)

**Inafaa zaidi kwa:** Unapofikia vikomo vya muktadha mara kwa mara.

### Hali ya RTK (kiwango cha 60-90% kwa mtoa huduma wa juu)

Hali ya RTK imeboreshwa kwa matokeo marefu ya zana yanayotokea katika vipindi vya mawakala wa uandishi wa msimbo:

- Hutambua aina za amri/matokeo kama vile `git status`, `git diff`, `git log`, viendeshaji vya majaribio,
  miundo ya TypeScript/Vite/Webpack, ESLint/Biome/Prettier, ukaguzi/usakinishaji wa npm, kumbukumbu za Docker, matokeo ya infra
  na matokeo ya kawaida ya shell
- Hutumia vifurushi vya vichujio vya JSON kutoka `open-sse/services/compression/engines/rtk/filters/`
- Huleta vichujio vya RTK TOML schema v1 kutoka faili za mradi au za jumla za `filters.toml`, pamoja na uthibitishaji wa
  majaribio ya ndani na uzuiaji unaotegemea uaminifu kwa faili za mradi
- Huja na vichujio 55 vilivyojengewa ndani pamoja na sampuli za uthibitishaji za ndani
- Huondoa mifuatano ya udhibiti ya ANSI, pau za maendeleo, mistari inayojirudia na kelele zisizoweza kufanyiwa kazi
- Huhifadhi hitilafu, makosa, maonyo, faili zilizobadilishwa, mihtasari na mwisho wa matokeo marefu
- Husaidia vichujio vya mradi vinavyodhibitiwa kwa uaminifu, vichujio vya jumla na urejeshaji wa hiari wa matokeo ghafi yaliyofichwa

**Inafaa zaidi kwa:** Vipindi vya mawakala vyenye shell, build, test, git, grep na nakala za matokeo ya faili.

### Hali ya Stacked (kiwango cha 78-95% ya inayostahiki)

Hali ya Stacked huendesha injini nyingi za ukandamizaji kwa mpangilio thabiti. Mtiririko chaguo-msingi ni:

```txt
RTK -> Caveman
```

Mpangilio huo huweka matokeo ya terminal/zana yakiwa mafupi kwanza, kisha hutumia ufupishaji wa kimaana wa Caveman kwa
prompt iliyosalia ya lugha asilia. Mitiririko ya Stacked inaweza kusanidiwa kwa ujumla au kupitia
combo za ukandamizaji zilizogawiwa kwa combo za uelekezaji.

**Inafaa zaidi kwa:** Muktadha mchanganyiko wenye kumbukumbu nyingi za zana pamoja na maagizo ya binadamu au mihtasari ya msaidizi.

---

## Hesabu ya Uokoaji wa Upstream

OmniRoute huandika uokoaji wa mbano kutoka vyanzo viwili: vipimo vya utendaji vya miradi ya upstream na
muundo wa injini za OmniRoute yenyewe.

| Chanzo  | Nambari ya README ya upstream iliyotumika hapa                                                                                                                         |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Caveman | tokeni za matokeo zimepungua kwa `~75%`, uokoaji wa wastani wa matokeo wa `65%` katika vipimo vya utendaji, kiwango cha `22-87%`, na zana ya mbano wa ingizo ya `~46%` |
| RTK     | uokoaji wa `60-90%` kwenye matokeo ya amri; kipindi cha mfano `~118,000 -> ~23,900` tokeni, au uokoaji wa `79.7%` (`~80%`)                                             |

Kwa data za zana/muktadha zinazoingiliana, mchanganyiko chaguo-msingi wa OmniRoute hupanga injini kwa mfuatano:

```txt
RTK -> Caveman
```

Uokoaji wa pamoja ni wa kuzidishana, si wa kujumlisha:

```txt
pamoja   = 1 - (1 - uokoaji wa RTK) * (1 - uokoaji wa ingizo wa Caveman)
wastani  = 1 - (1 - 0.80) * (1 - 0.46) = 89.2%
kiwango  = 1 - (1 - 0.60..0.90) * (1 - 0.46) = 78.4-94.6%
```

Nambari hiyo ya `78-95%` hutumika wakati RTK na Caveman zote zinaweza kupunguza data ileile ya ingizo/muktadha.
Hali ya matokeo ya majibu ya Caveman ni tofauti: inapowezeshwa, tumia uokoaji wa matokeo wa Caveman yenyewe (wastani wa `65%`,
takwimu kuu ya `~75%`, kiwango cha `22-87%`). Jumla ya uokoaji wa gharama hutegemea mchanganyiko wako wa ingizo/matokeo.

### Maana halisi ya "yanayostahiki"

Kiwango kikuu cha 15-95% ni halisi, lakini kinatumika tu kwa maudhui **yanayojirudia au yenye maneno mengi** — mistari ya
hitilafu inayojirudia, logi ya uundaji inayorudia onyo lilelile kupita kiasi, au dump kubwa kupita kiasi ya `grep`/usomaji wa faili. Hii
**haimaanishi** kwamba kila ombi huokoa kiasi hicho.

Imethibitishwa kwa majaribio (`tests/unit/compression/stacked-compression-tool-result-savings.test.ts`): utekelezaji wa
`stacked` (RTK + Caveman) dhidi ya bloku ya `tool_result` yenye muundo wa Anthropic iliyo na mistari 300 ya hitilafu inayofanana
ulizalisha **uokoaji wa tokeni wa 95.93% / uokoaji wa herufi wa 96.26%** — ndani kabisa ya kiwango kilichotangazwa.
Lakini pipeline hiyo hiyo inapoendeshwa dhidi ya matokeo ya kawaida ya zana yasiyojirudia (orodha safi ya matokeo ya `grep`,
usomaji mfupi wa faili, maandishi ya kawaida ya mazungumzo), kwa usahihi huzalisha **uokoaji unaokaribia sifuri**, kwa sababu
hakuna kitu kinachojirudia cha kuondoa na `validateCompression()` (`validation.ts`) hukataa kutuma maandishi
yaliyoandikwa upya ambayo yangeondoa au kubadilisha bloku za msimbo, URL, vichwa, matoleo, au vitambulishi vya viambatisho vya HERUFI-KUBWA-TUPU.

Hii ni tabia salama inayotarajiwa, si hitilafu: kipindi cha uandishi wa msimbo ambacho mara nyingi husoma/hutumia `grep` kwenye faili safi
kitaona uokoaji mdogo wa jumla hata kama mbano umewashwa kikamilifu, huku kipindi kinachokumbana na
kitanzi kinachoshindwa au linter yenye matokeo mengi kitaona kiwango kamili cha 78-95% kwenye trafiki hiyo. Usitumie asilimia ndogo ya
uokoaji wa jumla wa kipindi kimoja kama ushahidi kwamba mbano umesanidiwa vibaya — kwanza hakikisha ikiwa
matokeo ya msingi ya zana yalikuwa yakijirudia.

---

## Mwonekano wa Uokoaji wa Tokeni

```
Bila mbano:               tokeni 47K zimetumwa kwa LLM
Kwa Lite:                 tokeni 40K zimetumwa          (15% zimeokolewa — salama, imewashwa kila wakati)
Kwa Standard:             tokeni 33K zimetumwa          (30% zimeokolewa — kanuni za mtindo wa Caveman)
Kwa Aggressive:           tokeni 24K zimetumwa          (50% zimeokolewa — kuzeeka + ufupishaji)
Kwa Ultra:                tokeni 12K zimetumwa          (75% zimeokolewa — upogoaji wa kiheuristiki)
Kwa RTK:                  tokeni 19K-5K zimetumwa       (60-90% zimeokolewa kwenye matokeo ya amri/zana)
Kwa Stacked:              tokeni 10K-2.5K zimetumwa     (kiwango cha RTK+Caveman kinachostahiki cha 78-95%)
```

---

## Usanidi

### Dashibodi

Nenda kwenye `Dashibodi → Muktadha na Akiba`:

- **Caveman** — uteuzi wa modi, vifurushi vya lugha, onyesho la kukagua, na chaguo-msingi za jumla
- **RTK** — onyesho la kukagua kichujio cha amri, mipangilio ya usalama ya RTK, na katalogi ya vichujio
- **Michanganyiko ya Mfinyazo** — mifuatano ya injini iliyopewa majina na kukabidhiwa michanganyiko ya uelekezaji
- **Kiwango cha Uanzishaji Kiotomatiki** — anzisha mfinyazo kiotomatiki idadi ya tokeni inapozidi kiwango kilichowekwa

### Ubatilishaji kwa Kila Mchanganyiko

Katika `Dashibodi → Muktadha na Akiba → Michanganyiko ya Mfinyazo`, kabidhi mchanganyiko wa mfinyazo kwa mchanganyiko wa
uelekezaji:

```txt
Mchanganyiko: "free-tier-fallback"
  Mchanganyiko wa Mfinyazo: "coding-agent-stack"
  Mfuatano: RTK -> Caveman
  Malengo:
    1. if/kimi-k2.7-code
    2. if/qwen3.8-max-preview
```

Hii hukuruhusu kutumia mfinyazo uliopangwa kwa safu kwa watoa huduma wa bila malipo/uwekaji msimbo huku ukidumisha modi nyepesi kwenye
usajili unaolipiwa.

Ukabidhi huu wa "Ubatilishaji kwa Kila Mchanganyiko" ni kidhibiti tofauti na ubatilishaji wa **modi ya mfinyazo ya mchanganyiko wa uelekezaji**
(Default/Off/Lite/Standard/Aggressive/Ultra/Codex Responses — skima ya sehemu hiyo
pia inakubali `rtk`, `stacked` na `omniglyph`) — ubatilishaji huo hauchagui mfuatano wa mchanganyiko wa mfinyazo
uliopewa jina; unaweka tu sehemu ya `compressionMode` inayotumiwa na
`resolveCompressionPlan`. Inaweza kuwekwa ama kwenye kadi ya mchanganyiko (`Dashibodi → Michanganyiko`) au, tangu
#6760, kwa kila mchanganyiko wa uelekezaji katika orodha ya "Kabidhi kwa uelekezaji" kwenye
`Dashibodi → Muktadha na Akiba → Michanganyiko ya Mfinyazo`, karibu kabisa na kisanduku tiki cha ukabidhi wa mfuatano
kilichoelezwa hapo juu. Sehemu zote mbili huhifadhi kupitia endpoint ileile ya `PUT /api/combos/{id}`.

### Ubatilishaji kwa kila ombi

Tuma kichwa cha ombi cha `x-omniroute-compression` ili kubatilisha mpango wa mfinyazo kwa ombi moja.
Kina kipaumbele cha juu zaidi — kinashinda ubatilishaji wa mchanganyiko wa uelekezaji, wasifu unaotumika,
uanzishaji kiotomatiki, na chaguo-msingi la paneli. Thamani zisizojulikana hupuuzwa (ombi halikataliwi kamwe), na
swichi kuu ya jumla bado hudhibiti kila kitu: mfinyazo unapozimwa kwa ujumla, kichwa hakiwezi
kuuwasha. Thamani:

| Thamani       | Athari                                                                                                           |
| ------------- | ---------------------------------------------------------------------------------------------------------------- |
| `off`         | Hakuna mfinyazo kwa ombi hili.                                                                                   |
| `default`     | Wasifu Chaguo-msingi unaotokana na paneli (hupuuza wasifu unaotumika). Injini zenye upotevu huachwa zimezimwa.   |
| `safe`        | Sawa na kutotuma kichwa: kuondoa nakala rudufu na kukunja nafasi tupu pekee.                                     |
| `allow-lossy` | Dumisha mpango wa opereta wa ombi hili, ikijumuisha muhtasari, vichujio vya umuhimu, na uandishi upya wa mtindo. |
| `engine:<id>` | Injini moja inapowezeshwa, k.m. `engine:rtk`. Hili ndilo chaguo la kujiunga la kila ombi kwa injini hiyo.        |
| `<combo>`     | Mchanganyiko uliopewa jina, unaolinganishwa kwanza kwa jina (bila kujali herufi kubwa au ndogo), kisha kwa id.   |

Bila `allow-lossy`, `engine:<id>`, au mchanganyiko uliopewa jina, injini zenye upotevu hazitumiki.
Ombi bado hupata uondoaji wa nakala rudufu wa kipindi na ukunja wa nafasi tupu wakati mfinyazo umewashwa.

Mpango uliotumika hurejeshwa katika kichwa cha jibu cha `X-OmniRoute-Compression: <mode>; source=<source>`,
ambapo `<source>` ni mojawapo ya `request-header`, `routing-override`, `active-profile`,
`auto-trigger`, `default`, au `off`.

### API

```bash
# Pata mipangilio ya mfinyazo
curl http://localhost:20128/api/settings/compression

# Sasisha mipangilio ya mfinyazo
curl -X PUT http://localhost:20128/api/settings/compression \
  -H "Content-Type: application/json" \
  -d '{"defaultMode":"stacked","autoTriggerMode":"stacked","autoTriggerTokens":32000}'

# Kagua payload mahususi ya RTK/stacked
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"}]}'

# Orodhesha vifurushi vya vichujio vya RTK
curl http://localhost:20128/api/context/rtk/filters

# Jaribu RTK moja kwa moja kwa metadata ya hiari ya amri
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"}'
```

---

## Kinacholindwa

Injini ya ubanaji **huhifadhi kila wakati:**

- ✅ Vitalu vya msimbo (vilivyozungushiwa uzio na vya ndani ya mstari)
- ✅ URL na njia za faili
- ✅ Miundo ya JSON na data iliyopangwa
- ✅ Vitambulishi na tokeni za kiufundi zilizolindwa
- ✅ Semi za kihisabati
- ✅ Ufafanuzi wa miito ya zana/vitendaji
- ✅ Maagizo ya mfumo (katika hali ya lite)

Urejeshaji wa matokeo ghafi wa RTK huficha funguo za kawaida za API, tokeni za bearer, tokeni za Slack, funguo za ufikiaji za AWS,
nywila, tokeni na siri kabla ya chochote kuhifadhiwa.

---

## Takwimu za Ubanaji

Kila ombi lililobanwa hujumuisha takwimu katika kumbukumbu za seva:

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

---

## Ramani ya Hatua

| Hatua       | Hali                                                                                                                                                                    | Hadhi        |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| Hatua ya 1  | Off, Lite                                                                                                                                                               | ✅ Imetolewa |
| Hatua ya 2  | Standard, Aggressive, Ultra                                                                                                                                             | ✅ Imetolewa |
| Hatua ya 3  | RTK, Stacked, Compression Combos                                                                                                                                        | ✅ Imetolewa |
| Hatua ya 4  | Output Styles, SLM-tier Ultra, mfumo wa tathmini                                                                                                                        | ✅ Imetolewa |
| Hatua ya 4C | Bajeti ya muktadha inayobadilika ("dial") — injini ya ukokotoaji + API (`contextBudget` kwenye `PUT /api/settings/compression`) + vidhibiti vya hali/sera vya dashibodi | ✅ Imetolewa |

---

## Shukrani

Kanuni za ubanaji za hali ya Standard zimehamasishwa na **[Caveman](https://github.com/JuliusBrussee/caveman)** ya **[JuliusBrussee](https://github.com/JuliusBrussee)** (⭐ 51K+) — mradi uliosambaa sana wa "kwa nini utumie tokeni nyingi wakati chache zinatosha". Caveman inaripoti tokeni za matokeo zilizopungua kwa `~75%`, wastani wa uokoaji wa matokeo wa `65%` katika vipimo vya utendaji, kiwango cha matokeo cha `22-87%`, na zana ya ubanaji wa ingizo ya `~46%`.

Hali ya RTK imehamasishwa na **[RTK - Rust Token Killer](https://github.com/rtk-ai/rtk)** ya **[RTK AI](https://github.com/rtk-ai)** — mradi wa ubanaji wenye utendaji wa juu wa matokeo ya amri kwa ajili ya uchujaji wa matokeo ya terminali, ujenzi, majaribio, git na zana. RTK inaripoti uokoaji wa `60-90%`, huku kipindi cha mfano katika README yake kikionyesha uokoaji wa `~80%`.

---

## Mifumo ya Kina ya Mfinyazo

Zaidi ya hali 7 zilizoelezwa hapo juu (chanzo pia kinakubali hali za `codex-responses` na
`omniglyph`, ambazo mwongozo huu haujumuishi), sehemu zilizo hapa chini zinajumuisha vipengele
vinavyofanya kazi ndani ya hali hizo au sambamba nazo: Mfinyazo wa Matokeo ya Zana na Uchakavu Endelevu
ni hatua ya 1 na ya 2 ya injini kali (hali ya Aggressive na hatua ya `aggressive` ya
bomba lililorundikwa), Bomba Lililorundikwa ndilo linaloendesha hali ya Stacked, Mfinyazo
Unaozingatia Akiba hushusha `aggressive` na `ultra` hadi `standard` kwa watoa huduma wenye uhifadhi
wa akiba wakati mfinyazo umewashwa, na Hali ya Matokeo ya Caveman pamoja na Mitindo ya Matokeo ni
maagizo ya hiari ya kidokezo cha mfumo, ambayo yamezimwa kwa chaguo-msingi, na huunda muundo wa
matokeo ya modeli badala ya kufinyaza ombi.

### Mfinyazo Unaozingatia Akiba

Baadhi ya watoa huduma (kama Anthropic yenye uhifadhi wa akiba wa vidokezo) wanaunga mkono
**uhifadhi wa akiba wa vidokezo**, unaowaruhusu kuhifadhi sehemu za kidokezo kwenye akiba ili
kupunguza gharama na muda wa kusubiri. Uhifadhi wa akiba unapowashwa, mfinyazo mkali unaweza kwa
hakika **kudhoofisha** utendaji kwa sababu hubadilisha tokeni zilizohifadhiwa kwenye akiba,
na hivyo kubatilisha akiba.

Moduli ya `cachingAware.ts` hutatua hili kwa **kutambua muktadha wa uhifadhi wa akiba** na
**kurekebisha mkakati wa mfinyazo** ipasavyo.

#### Jinsi inavyofanya kazi

1. **Tambua muktadha wa uhifadhi wa akiba** — Huchanganua mwili wa ombi ili kutafuta viashiria vya `cache_control`
2. **Tambua watoa huduma wenye uhifadhi wa akiba** — Hukagua ikiwa mtoa huduma lengwa anaunga mkono uhifadhi wa akiba
3. **Rekebisha mkakati** — Hushusha `aggressive`/`ultra` hadi `standard` kwa watoa huduma wenye uhifadhi wa akiba
4. **Ruka kidokezo cha mfumo** — Vidokezo vya mfumo kwa kawaida huhifadhiwa kwenye akiba, kwa hivyo usivifinyaze

Kisaidizi cha mkakati pia hurejesha alama ya `deterministicOnly`, lakini kiundaji cha mpango
hutumia mkakati pekee — kwa sasa hakuna sehemu yoyote ya baadaye inayosoma alama hiyo.

#### Mfano wa msimbo

```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" }, // ← Kiashiria cha akiba
};

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 }
```

#### Wakati wa kutumia

Mfinyazo unaozingatia akiba **umewashwa kila wakati** — hakuna usanidi unaohitajika. Huanza
kufanya kazi wakati wowote mfinyazo umewashwa na mtoa huduma lengwa anaunga mkono uhifadhi wa
akiba wa vidokezo (Anthropic, OpenAI, n.k.); viashiria dhahiri vya `cache_control` havihitajiki —
mtoa huduma mwenye uhifadhi wa akiba pekee anatosha kusababisha ushushaji, na viashiria pekee
havifanyi hivyo kamwe (utambuzi wa viashiria hutoa data kwa telemetria ya akiba, si uamuzi wa
mkakati).

### Uchakavu Endelevu

Mazungumzo marefu hukusanya zamu nyingi za ujumbe, lakini zamu za zamani hupungua umuhimu.
Moduli ya `progressiveAging.ts` **hupunguza ubora wa ujumbe kulingana na umbali wa zamu**
(umbali unaopimwa kutoka mwisho wa mazungumzo). Kwa chaguo-msingi zinazotolewa
(`verbatim: 2, light: 2, moderate: 3`):

- **Zamu 2 za mwisho (umbali ≤ 2)**: Huwekwa kama zilivyo
- **Umbali wa 3**: Mfinyazo wa Caveman (kuondoa maneno ya kujazia)
- **Umbali wa 4+**: Ujumbe wa msaidizi hufupishwa; ujumbe wa mtumiaji hupunguzwa hadi mstari wake
  wa kwanza, ukiwekewa kikomo cha herufi 120; majukumu mengine hayaguswi. Vidokezo vya mfumo,
  ujumbe ambao tayari umechakazwa na ujumbe wa hivi karibuni zaidi wa mtumiaji huwekwa kama ulivyo
  kila wakati bila kujali umbali. Hakuna chochote kinachoondolewa kabisa, na ukanda wa `light`
  hauwezi kufikiwa kwa chaguo-msingi zinazotolewa (`light` ni sawa na `verbatim`).

#### Mfano wa msimbo

```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" },
  // ... zamu 50 zaidi ...
];

const { messages: aged, saved } = applyAging(messages, {
  verbatim: 3, // zamu 3 za mwisho: kama zilivyo
  light: 8, // umbali <= 8: mfinyazo mwepesi
  moderate: 20, // umbali <= 20: mfinyazo wa caveman
  fullSummary: 5, // inahitajika na aina, haisomwi na msimbo wa kugawa katika mikanda
  // umbali > 20: hufupishwa (msaidizi) / mstari wa kwanza huwekwa (mtumiaji)
});

// saved = idadi ya tokeni zilizookolewa
```

#### Wakati wa kutumia

Uchakavu endelevu **umewashwa kila wakati** kwa hali ya `aggressive` — ni hatua ya 2 ya
`compressAggressive()`. Hali ya Ultra haiutekelezi. Unafaa hasa kwa:

- Vipindi vya muda mrefu vya uandishi wa msimbo
- Mazungumzo yanayoendelea kwa siku nyingi
- Mitiririko ya kazi ya mawakala yenye miito mingi ya zana

### Hali ya Matokeo ya Caveman

Hali ya matokeo ya Caveman huongeza **maagizo ya kidokezo cha mfumo** yanayoiomba modeli yenyewe
itoe matokeo mafupi — kiwango cha `lite` huomba majibu mafupi yanayohifadhi sentensi kamili, `full`
huiomba "ijibu kwa ufupi kama caveman mwerevu", na `ultra` huomba matokeo ya kitelegrafu;
maagizo huomba tu, hayawezi kuhakikisha hilo. Maombi huyapokea kupitia
`applyOutputStyles()` (`open-sse/services/compression/outputStyles/apply.ts`):
`open-sse/handlers/chatCore.ts` kwanza hutatua uteuzi kwa kutumia safu ya uoanifu wa nyuma
(`resolveOutputStyleSelection()` katika
`open-sse/services/compression/outputStyles/backCompat.ts`), ambayo, wakati `outputStyles`
ni tupu, huoanisha `cavemanOutputMode` iliyowashwa na mtindo wa matokeo wa `terse-prose` katika
kiwango cha `cavemanOutputMode.intensity` (angalia Uoanifu wa nyuma hapa chini); uteuzi wa
`outputStyles` usio tupu hutumiwa kama ulivyo, na kisha `cavemanOutputMode.enabled` pamoja na
`intensity` havina athari, huku kibadilishaji chake cha `autoClarity` kikiendelea kutumika.
`outputMode.ts` huhifadhi maandishi ya maagizo (`CAVEMAN_INSTRUCTION_BY_LANGUAGE`), upitaji wa
maudhui na kisaidizi cha uwekaji kinachotumiwa na uingizaji; kiingizaji chake chenyewe cha
`applyCavemanOutputMode()` hakina kiitishaji katika uzalishaji.

#### Jinsi inavyofanya kazi

Hali hii haibani ingizo. Inaongeza bloku ya maagizo kwenye kidokezo cha mfumo
(angalia Jinsi udungaji unavyofanya kazi hapa chini), na hali yoyote ya ubanaji wa ingizo iliyochaguliwa kwa ombi
bado huendeshwa baadaye, kwenye kiini ambacho sasa kina bloku hiyo. Kabla ya kifungu cha pamoja cha
mipaka ambacho kila kiwango huishia nacho, kiwango cha Kiingereza cha `full` kinasema:

> "Jibu kwa ufupi kama mtu wa pangoni mwenye akili. Ondoa vihusishi (a/an/the), maneno ya kujaza (just/really/basically/actually/simply), maneno ya adabu, lugha ya kusita. Vipande vya sentensi vinakubalika. Visawe vifupi (big badala ya extensive, fix badala ya implement). Hifadhi maudhui yote ya kiufundi, msimbo, hitilafu, URL, vitambulishi bila kubadilisha."

Hii hufanya kazi vizuri hasa kwa:

- Uzalishaji wa msimbo (tokeo fupi zaidi = tokeni chache)
- Maswali na majibu ya haraka (hakuna haja ya maelezo marefu)
- Uchakataji wa bechi (ongeza kiwango cha uchakataji)

#### Wakati wa kutumia

Hali ya matokeo ya mtindo wa mtu wa pangoni ni **ya kuchagua**. Ubanaji ukiwa umewashwa (`enabled: true`, swichi kuu
kwenye ukurasa wa Mipangilio ya Ubanaji), iwashe kwa `cavemanOutputMode.enabled`; `intensity`
huchagua `lite`, `full` au `ultra`:

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

Swichi ya **Hali ya Matokeo** ya mchanganyiko wa ubanaji (`outputMode`, kiwango katika `outputModeIntensity`)
huweka swichi hiyo hiyo kwa maombi ambayo mchanganyiko huo unatumika kwayo, na zana ya MCP ya
`omniroute_set_compression_engine` huiandika kupitia hoja yake ya boolean `outputMode`.
Chaguo la `outputStyles` lisilo tupu hupewa kipaumbele kuliko swichi hii. Kwenye
dashibodi, kuwezesha mtindo wa matokeo wa **Nathari fupi** hudunga bloku hiyo hiyo (angalia Mitindo ya
Matokeo hapa chini).

### Mitindo ya Matokeo (katalogi)

Hali ya matokeo ya mtindo wa mtu wa pangoni hapo juu ndiyo **njia ya zamani ya mtindo mmoja**. Awamu ya 4 iliipanua
kuwa katalogi ya mitindo ya matokeo inayoweza kuunganishwa: `OUTPUT_STYLE_CATALOG` katika
`open-sse/services/compression/outputStyles/catalog.ts`. Kila mtindo ni agizo la kidokezo cha mfumo
linaloitaka modeli yenyewe kutoa matokeo yenye gharama ndogo; mitindo inaweza kuwezeshwa
pamoja na hudungwa kwa mpangilio wa katalogi.

| Mtindo                                       | `id`            | Inachofanya                                                                                                                                                                                                                                                                                                | Lugha za maagizo                              |
| -------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| Nathari fupi                                 | `terse-prose`   | Ondoa maneno ya kujaza/vihusishi/lugha ya kusita; hifadhi maudhui ya kiufundi bila kubadilisha. Maandishi sawa na hali ya zamani ya matokeo ya mtindo wa mtu wa pangoni (yanarejelewa, hayaandikwi upya).                                                                                                  | en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi |
| Msimbo mchache                               | `less-code`     | Ngazi ya YAGNI: badiliko dogo zaidi linalofanya kazi, bila uondoaji wa mambo mahususi usioombwa.                                                                                                                                                                                                           | en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi |
| Ponytail (msanidi mkuu mvivu)                | `ponytail`      | "Msimbo bora zaidi ni msimbo ambao haukuwahi kuandikwa": tumia tena > andika upya, chanzo kikuu > dalili, diff fupi zaidi inayofanya kazi.                                                                                                                                                                 | en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi |
| Nina ADHD (kitendo kwanza)                   | `i-have-adhd`   | Kitendo kwanza (amri/njia/kijisehemu kabla ya nathari), hatua zenye nambari na mipaka, hatua MOJA mahususi inayofuata, bila utangulizi/muhtasari/maneno ya kufunga. Imetoholewa kutoka [ayghri/i-have-adhd](https://github.com/ayghri/i-have-adhd) (MIT).                                                  | en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi |
| Kichujio cha UI cha antislop                 | `antislop-ui`   | Kila mbinu ya kuona lazima ipite jaribio la kusudi (mpangilio wa umuhimu, utambulisho, usomaji); hakuna gradient/glass/glow za chaguo-msingi, paleti yenye kikomo, wala miundo ya violezo. Mitindo yote miwili ya antislop huongeza mpaka wa kutokuwa na vidhibiti visivyofanya kazi / madai yaliyobuniwa. | en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi |
| Kichujio cha antislop cha nakala na binadamu | `antislop-copy` | Nakala mahususi (bila em dash, CTA za jumla, misemo ya kibiashara, vifungio vya chatbot, ukweli uliobuniwa) pamoja na kanuni za watu: utofautishaji wa WCAG AA, fokasi inayoonekana, ufikiaji kwa kibodi, hali tupu/za kupakia/za hitilafu, mpangilio upya wa simu.                                        | en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi |
| CJK fupi (文言)                              | `terse-cjk`     | Jibu la `full`/`ultra` kwa Kichina cha Kale (文言); `lite` huomba tu majibu mafupi bila maneno ya kisarufi, maneno ya adabu au mapambo.                                                                                                                                                                    | zh (imezuiwa kwa locale, angalia hapa chini)  |

Kila mtindo huja na viwango vitatu vya ukubwa — `lite`, `full`, `ultra` — na kila kiwango
huishia kwa kifungu cha pamoja cha mipaka (`SHARED_BOUNDARIES` katika `outputMode.ts`), ambacho
huhifadhi bloku za msimbo, njia za faili, amri, hitilafu na URL bila kubadilisha. Maandishi ya viwango vya `terse-prose` na
`terse-cjk` huongeza vitambulishi kwenye orodha hiyo.

`terse-cjk` imezuiwa kwa locale ya `zh` katika sehemu mbili. Ukurasa wa Mipangilio ya Ubanaji huorodhesha
safu yake tu wakati lugha ya UI ya dashibodi ni Kichina (`zh-CN` au `zh-TW`), na
`applyOutputStyles()` huidunga tu wakati lugha iliyotambuliwa ya ombi (angalia Uteuzi wa Lugha
hapa chini) ni `zh`. Kuficha safu hakufuti chaguo la `terse-cjk` lililohifadhiwa:
API ya mipangilio hukubali id yoyote ya mtindo, na kuhifadhi mitindo mingine kwenye ukurasa huihifadhi. Wakati wa
ombi, ukaguzi wa lugha wa `applyOutputStyles()` ndio kizuizi pekee cha locale.

#### Jinsi udungaji unavyofanya kazi

`applyOutputStyles()` (`open-sse/services/compression/outputStyles/apply.ts`) hutatua
uteuzi dhidi ya katalogi (vitambulisho visivyojulikana na mitindo isiyolingana na lugha
huondolewa, bila kusababisha hitilafu kamwe; uteuzi ambao hautatui hadi mtindo wowote
huacha mwili bila kubadilishwa, ukirukwa kama `no_styles`), huunganisha maagizo
yaliyochaguliwa kwa mpangilio wa katalogi,
huongeza kifungu cha mipaka **mara moja** (pamoja na kifungu cha usalama,
`SAFETY_BOUNDARIES` au tafsiri yake, wakati `less-code` au `ponytail` imechaguliwa), na
huanzisha bloku kwa alama moja ya kutorudiwa (`[OmniRoute Output Styles]`), hivyo
kutekeleza tena hakufanyi chochote. Wakati lugha iliyotatuliwa (tazama Uteuzi wa lugha
hapa chini) ina tafsiri, agizo lililotafsiriwa huingizwa badala ya Kiingereza.

Kwenye mwili wenye safu ya `messages` isiyo tupu, ukaguzi wa kutorudiwa huendeshwa kabla
ya upitaji wa maudhui: wakati alama ya `[OmniRoute Output Styles]` tayari ipo katika uga
wa kiwango cha juu wa `system` (mfuatano au safu ya bloku za maudhui) au katika ujumbe wa
mfumo wenye maudhui ya mfuatano, mwili huachwa bila kubadilishwa kama
`already_applied` na hakuna ukaguzi wa maneno muhimu unaoendeshwa.
Vinginevyo, upitaji wa maudhui (`shouldBypassCavemanOutputMode()` katika
`open-sse/services/compression/outputMode.ts`) hukagua maandishi ya jumbe tatu za
mwisho, bila kujali jukumu lake, na huruka mitindo kwa zamu nzima wakati maandishi hayo
yanalingana na maneno yake muhimu ya usalama, kitendo kisichoweza kutenduliwa au
ufafanuzi, au mfuatano unaozingatia mpangilio: `first`, `then`, `after that`, `before`,
`rollback` au `backup` likifuatwa ndani ya herufi 240 na `delete`, `drop`, `migrate`,
`deploy` au `release`. Upitaji huo huendeshwa wakati kibadilishaji cha
**Auto-Clarity Bypass** (`cavemanOutputMode.autoClarity`, ambacho huwashwa kwa chaguo-msingi)
kimewashwa; kuzima kibadilishaji huruka ukaguzi wa maneno muhimu.

Wakati upitaji unaruhusu zamu iendelee, `placeSystemInstruction()` (faili hiyo hiyo),
ambayo haiundi kamwe `messages[0]` mpya, huweka bloku katika sehemu ya kwanza kati ya
hizi inayopata:

1. Ujumbe wa mfumo wa mwanzo wenye maudhui ya mfuatano: bloku huongezwa baada ya
   maandishi yake.
2. Uga wa kiwango cha juu wa `system`: bloku huongezwa baada ya maandishi ya mfuatano,
   au huongezwa kama bloku mpya ya maandishi kwenye safu ya bloku za maudhui.
3. Ujumbe wa kwanza wa mfumo unaofuata wenye maudhui ya mfuatano: bloku huongezwa baada
   ya maandishi yake.
4. Hakuna kati ya yaliyo hapo juu: bloku huwekwa katika ujumbe mpya wa mfumo mwishoni
   mwa `messages`.

Kwenye mwili usio na safu ya `messages` (au wenye safu tupu), hakuna upitaji wa maudhui
unaoendeshwa na uga wa kiwango cha juu wa `system` hauangaliwi. Bloku huongezwa baada ya
maandishi ya uga wa mfuatano wa `instructions`, isipokuwa uga huo tayari una alama ya
`[OmniRoute Output Styles]`, ambapo mwili huachwa bila kubadilishwa kama
`already_applied`. Wakati mwili hauna uga wa mfuatano wa `instructions` lakini una
`input` (mfuatano au safu), bloku huwa `instructions`, ikibadilisha thamani yoyote isiyo
mfuatano iliyokuwapo katika uga huo. Mwili usio na uga wa mfuatano wa `instructions`
wala `input` ya mfuatano au safu huachwa bila kubadilishwa na hurukwa kama
`no_messages`.

#### Jinsi ya kuwezesha

Katika dashibodi: **Compression Context → Compression Settings**
(`/dashboard/context/settings`), sehemu ya mitindo ya towe: safu mlalo moja kwa kila
mtindo, yenye kibadilishaji cha kuwasha/kuzima na kiteuzi cha kiwango. Mitindo huingizwa
wakati mbano wenyewe umewashwa (kibadilishaji kikuu cha ukurasa, `enabled`).
Kibadilishaji cha **Auto-Clarity Bypass** kiko kwenye ukurasa wa **Caveman**
(`/dashboard/context/caveman`), katika kadi yake ya **Output Mode**. Kiprogramu,
usanidi wa mbano huhifadhi uteuzi kama:

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

Utangamano wa nyuma: wakati `outputStyles` ni tupu, mpangilio wa zamani wa
`cavemanOutputMode.enabled` huwekewa `terse-prose` katika
`cavemanOutputMode.intensity`. Kisha bloku huanza kwa alama ya
`[OmniRoute Output Styles]`, ambapo kiingiza cha zamani cha
`applyCavemanOutputMode()` kiliandika `[OmniRoute Caveman Output Mode]`. Chini ya alama
hiyo, maandishi yanalingana na uingizaji wa zamani katika en, pt-BR, es, de, fr, it, ru,
id na vi; katika ja na zh yana nafasi moja ya ziada kabla ya kifungu cha mipaka.
`terse-prose` hutafsiriwa katika pt-BR, es, de, fr, it, ru, zh, ja, id na vi, kwa hivyo
ombi ambalo lugha yake iliyotatuliwa ni `hu` hupata maandishi ya Kiingereza pale ambapo
kiingiza cha zamani kilitumia maandishi yake ya Kihungaria.

Uteuzi wa lugha ya mtindo wa towe (`resolveOutputStyleLanguage()` katika
`outputStyles/apply.ts`): `languageConfig.enabled` ikiwa imewashwa, `autoDetect`
huchukua sampuli ya ujumbe wa hivi karibuni wa mtumiaji katika safu ya `messages` ya
ombi ulio na maandishi (maudhui ya mfuatano, au `text` ya sehemu zake za maudhui) na
kuendesha kitambuzi cha injini ya Caveman (`detectCompressionLanguage()`) juu yake.
Kitambuzi hurejesha `zh` kwa maandishi yenye herufi za Han bila kana; vinginevyo
hurejesha lugha yoyote kati ya `it`, `pt-BR`, `es`, `de`, `fr`, `ru`, `ja`, `hu` na
`id` yenye idadi kubwa zaidi ya vidokezo vinavyolingana, na `en` wakati hakuna
kinacholingana — maandishi ambayo hakiwezi kuyaainisha hupata Kiingereza, kamwe si
`defaultLanguage`, na `vi` haitambuliwi kamwe ingawa mitindo husafirishwa ikiwa na
maandishi ya `vi`. Mwili wa Responses API huhifadhi zamu zake katika `input`, ambayo
haichukuliwi sampuli, kwa hivyo hupata `defaultLanguage`, kisha Kiingereza. Wakati
hakuna ujumbe wa mtumiaji katika `messages` wenye maandishi, au `autoDetect` ikiwa
imezimwa, `defaultLanguage` hutumika, kisha Kiingereza. `languageConfig.enabled` ikiwa
imezimwa, lugha huwa Kiingereza — isipokuwa mchanganyiko wa mbano utumike kwa ombi
(mchanganyiko uliogawiwa kwa mchanganyiko wa uelekezaji wa ombi, au mchanganyiko
chaguo-msingi wa mbano ambao chatCore huutumia kama mbadala kwa bomba lililorundikwa
lililojengewa ndani): kutumia mchanganyiko huwasha `languageConfig.enabled` kwa ombi
hilo na kuweka `defaultLanguage` kutoka kwenye vifurushi vya lugha vya mchanganyiko
(thamani iliyohifadhiwa ikiwa ni mojawapo ya vifurushi vya mchanganyiko, vinginevyo
kifurushi cha kwanza cha mchanganyiko, ambacho chaguo-msingi lake ni `en`), huku
`autoDetect` iliyohifadhiwa (iliyowashwa kwa chaguo-msingi) ikiendelea kutumika. Injini
ya ingizo ya Caveman huchagua lugha ya kifurushi cha kanuni kwa njia tofauti — kwa kila
sehemu ya maandishi na, utambuzi wa kiotomatiki ukiwa umezimwa, kwa kutegemea
`enabledPacks`.

Matriki ya mtindo × lugha imebainishwa na
`tests/unit/compression/output-styles-i18n-matrix.test.ts`: kila mtindo wa katalogi unahitaji
ingizo katika `BASELINE_LANGUAGES` ya jaribio; mtindo ambao haujawekewa kikomo cha locale lazima utoe
tafsiri ya pt-BR (`terse-cjk` iliyowekewa kikomo cha locale imeondolewa katika sheria hii) isipokuwa
umeorodheshwa katika `KNOWN_ENGLISH_ONLY`, ambayo inaweza kuwa na mitindo isiyo na tafsiri zozote pekee —
mtindo ulioorodheshwa ambao una tafsiri yoyote husababisha jaribio kushindwa; na mtindo hushindwa katika jaribio
unapopoteza lugha iliyoorodheshwa na ingizo lake la `BASELINE_LANGUAGES`. Ili kuongeza mtindo, angalia
[EXTENDING_COMPRESSION.md](./EXTENDING_COMPRESSION.md#adding-an-output-style).

### Mfinyazo wa Matokeo ya Zana

`compressToolResult()` katika `open-sse/services/compression/toolResultCompressor.ts`
hufinyaza maandishi ya matokeo ya zana kwa kutumia **mikakati 5**. Huijaribu kwa mpangilio huu, na
mkakati wa kwanza uliowashwa ambao ukaguzi wake unalingana na maudhui ndio huamua matokeo:

1. **`fileContent`**: maudhui ya mistari 3 au zaidi ambapo angalau mstari mmoja, bila kuzingatia
   ujongezaji wa mwanzo, huanza na `import `, `export `, `function `, `class `,
   `const `, `let `, `var ` au `return ` (neno kuu pamoja na nafasi), au na `if`,
   `for` au `while` ikifuatiwa na `(` au ` (`, huhifadhi mistari yake 20 ya kwanza na 5 ya mwisho, huku
   sehemu ya katikati iliyoondolewa ikiwekewa alama.
2. **`grepSearch`**: maudhui yenye angalau mstari mmoja wa muundo `<path>:<digits>:`,
   ambapo maandishi kabla ya koloni ya kwanza hayana nafasi tupu, huhifadhi mistari hiyo pekee, hadi
   30, ikifuatiwa na idadi ya ulinganifu wowote zaidi na orodha ya faili zinazolingana;
   kila mstari mwingine huondolewa. Mstari mmoja kama huo unatosha kuanzisha mkakati, kwa hivyo
   mstari wa kumbukumbu unaoanza na muhuri wa muda kama `12:30:45` pia huhesabiwa.
3. **`shellOutput`**: matokeo yenye mfuatano wa ANSI CSI (`ESC[` kisha tarakimu au
   nuktamkato na kisha herufi, kama katika misimbo ya rangi) au `$` inayofuatwa na nafasi tupu
   mahali popote katika maandishi huondokewa na mifuatano hiyo (mifuatano mingine ya uepukaji, kama `ESC[?25l` au
   mfuatano wa kichwa cha dirisha cha OSC, huhifadhiwa) na huhifadhi mistari yake 50 ya mwisho, huku mistari
   inayofuatana na kujirudia ikiunganishwa. Kwa sababu ukaguzi huu huendeshwa kabla ya `json` na `errorMessage`,
   matokeo ya JSON au hitilafu yaliyo na `$` kama hiyo hayafikii mikakati hiyo wakati
   `shellOutput` imewashwa.
4. **`json`**: mzigo wa JSON wenye zaidi ya vibambo 2,000 unaoanza na `{` au `[` (baada ya
   nafasi tupu ya hiari) na unaoweza kuchanganuliwa hufupishwa: safu yenye zaidi ya vipengee 7 huhifadhi
   vipengee vyake 5 vya kwanza na 2 vya mwisho pamoja na jumla ya idadi yake, na kitu huhifadhi funguo zake 20 za
   kwanza, huku kila thamani ya kitu au safu iliyopachikwa ikibadilishwa na kishikilia nafasi cha `{…N keys}`
   (kwa safu, N ni urefu wake) na alama ya `_remaining_<N>_keys` inayohesabu funguo
   zilizoondolewa baada ya 20 za kwanza. Thamani skala hunakiliwa zikiwa nzima, kwa hivyo kitu chenye funguo 20
   au chache bila thamani zilizopachikwa hupangwa upya kwa ujongezaji pekee — kilichobanwa katika mstari mmoja huongezewa vibambo
   na hubaki bila kubadilishwa.
5. **`errorMessage`**: matokeo yaliyo na, mahali popote na bila kujali ukubwa wa herufi, `error:`,
   `error ` (neno likifuatiwa na nafasi, kama katika `no error found`), `[error]`,
   `exception:`, `exception `, `[exception]` au `traceback` huhifadhi mstari wake wa kwanza,
   mistari 10 inayofuata na 3 ya mwisho, huku alama ya `… [N frames elided] …` ikiwekwa badala ya
   mistari iliyo katikati. Alama hiyo huonekana tu wakati zaidi ya mistari 13 inafuata mstari wa kwanza,
   kwa hivyo matokeo ya hitilafu yenye mistari 14 au michache hayafupishwi (katika mistari 12 au 13,
   mistari 3 ya mwisho hurudia mistari ambayo tayari imehifadhiwa).

Baada ya mkakati kulingana, hata ule ambao hauokoi chochote, mikakati ya baadaye
haijaribiwi. Wakati mkakati unaolingana hauokoi tokeni zozote zilizokadiriwa (urefu ÷ 4, ukizungushwa juu) —
kwa mfano faili inayofanana na msimbo yenye mistari 25 au michache, au safu ya JSON yenye zaidi ya vibambo 2,000
na vipengee 7 au vichache — injini kali huhifadhi matokeo ya awali ya zana:
wapigaji wote wawili (`compressAggressive()` na `compressAnthropicToolResultBlock()`)
huhifadhi matokeo ya awali wakati `saved` ni 0 au chini, ilhali `compressToolResult()` yenyewe bado
hurudisha matokeo ya mkakati huo. Hatua ya matokeo ya zana si uamuzi wa mwisho:
kifupishaji cha akiba cha injini bado kinaweza kufupisha ujumbe wa `tool` au `function` wenye urefu
wa zaidi ya vibambo 8,192 (`maxTokensPerMessage`, 2,048, mara 4).

#### Wakati wa kutumia

Mfinyazo wa matokeo ya zana ni hatua ya 1 ya injini kali (`compressAggressive()` katika
`open-sse/services/compression/aggressive.ts`), kwa hivyo huendeshwa katika hali ya Aggressive na katika
hatua ya `aggressive` ya bomba lililorundikwa. Hufinyaza ujumbe wa `tool` na `function`
wenye muundo wa OpenAI na maandishi ndani ya vizuizi vya Anthropic `tool_result`. Kila mkakati una
swichi yake chini ya `aggressive.toolStrategies`, zote zikiwa zimewashwa kwa chaguo-msingi. Katika dashibodi,
swichi hizo ziko katika mwonekano wa **Advanced** wa ukurasa wa Caveman wakati mfinyazo umewashwa na
hali chaguo-msingi ni Aggressive.

### Bomba Lililorundikwa

Hali iliyorundikwa huendesha **injini nyingi kwa mfuatano** — kwa kawaida RTK kwanza
(akiba ya 60-90% kwenye matokeo ya zana), kisha Caveman kwenye maandishi yaliyobaki (~46% ya
akiba ya ingizo). Zikiunganishwa, hiyo ni **masafa yanayostahiki ya 78-95%** (angalia Hesabu ya Akiba ya Chanzo
hapo juu): `1 - (1 - 0.60..0.90) × (1 - 0.46)` huwa na wastani wa ≈89%.

#### Jinsi inavyofanya kazi

```
Ingizo (tokeni 1000)
  → RTK (kichujio kinachotambua amri) → tokeni 200
    → Caveman (uondoaji wa vijazaji) → tokeni 108
  → Tokeo (tokeni 108, akiba ya ~89%)
```

#### Wakati wa kutumia

Tumia hali iliyorundikwa kwa:

- Mitiririko ya kazi inayotumia zana kwa wingi (uandishi wa msimbo wa kiwakala, utafiti)
- Uchakataji wa makundi unaozingatia gharama
- Unapohitaji akiba ya juu zaidi ya tokeni

Mabomba yaliyorundikwa husanidiwa kupitia mpangilio wa mfinyazo wa kimataifa wa `stackedPipeline`,
au kupitia mchanganyiko wa mfinyazo uliopewa jina na kuhusishwa na mchanganyiko wa uelekezaji (angalia
Ubatilishaji kwa Kila Mchanganyiko hapo juu) — si kupitia `modePack` ya mchanganyiko otomatiki (sehemu hiyo
hubadilisha tu uzani wa uteuzi wa modeli wa mchanganyiko otomatiki, na `stacked` si jina halali la kifurushi).

---

## Ubatilishaji wa Mchanganyiko wa Mfinyazo

Unaweza kubatilisha hali ya jumla ya mfinyazo **kwa kila mchanganyiko** ili kuboresha tabia
kwa matumizi tofauti:

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

Hii ni muhimu kwa:

- **Michanganyiko ya uandishi wa msimbo**: Tumia hali ya `aggressive` kwa vipindi virefu
- **Michanganyiko ya maswali na majibu ya haraka**: Tumia hali ya `lite` kwa majibu ya haraka
- **Michanganyiko inayotumia zana nyingi**: Tumia hali ya `stacked` kwa uokoaji wa kiwango cha juu
- **Michanganyiko ya uzalishaji**: acha ubatilishaji umezimwa kwa watoa huduma wa uakibishaji — marekebisho yanayozingatia akiba na yanayotumika kila wakati hushusha `aggressive`/`ultra` hadi `standard` kiotomatiki
  (hakuna hali ya `cache-aware` inayoweza kuchaguliwa)

---

## Tazama Pia

- [Usanidi wa Mazingira](../reference/ENVIRONMENT.md) — Vigeu vya mazingira vya mfinyazo
- [Mwongozo wa Usanifu](../architecture/ARCHITECTURE.md) — Utendaji wa ndani wa mchakato wa mfinyazo
- [Mwongozo wa Mtumiaji](../guides/USER_GUIDE.md) — Kuanza kutumia mfinyazo
- [Mfinyazo wa RTK](./RTK_COMPRESSION.md) — Vichujio vya RTK, modeli ya uaminifu, lango la uthibitishaji, urejeshaji wa towe ghafi
- [Injini za Mfinyazo](./COMPRESSION_ENGINES.md) — Caveman, RTK, stacked, API, MCP, dashibodi
- [Muundo wa Kanuni za Mfinyazo](./COMPRESSION_RULES_FORMAT.md) — Muundo wa kifurushi cha kanuni cha JSON
- [Vifurushi vya Lugha vya Mfinyazo](./COMPRESSION_LANGUAGE_PACKS.md) — Kanuni za Caveman mahususi kwa lugha