# RTK Compression (Kiswahili)

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

---

Ukandamizaji wa RTK ni injini ya ukandamizaji ya OmniRoute inayotambua amri kwa ajili ya matokeo ya terminali na zana. Imeundwa kwa ajili ya vikao vya mawakala wa uandishi wa msimbo ambapo ukuaji mkubwa wa muktadha unatokana na kumbukumbu za majaribio, matokeo ya uundaji, taarifa zisizo muhimu za vidhibiti vya vifurushi, nakala za shell, matokeo ya Docker, matokeo ya git, na ufuatiliaji wa rundo.

RTK inaweza kuendeshwa moja kwa moja kwa `defaultMode: "rtk"` au kama hatua ya kwanza katika mtiririko uliopangwa kwa mfululizo, kwa kawaida:

```txt
rtk -> caveman
```

Mpangilio huo hukandamiza kwanza matokeo ya mashine yenye taarifa nyingi zisizo muhimu, kisha huruhusu Caveman kufupisha nathari iliyosalia.

RTK ya awali inaripoti uokoaji wa `60-90%` kwenye matokeo ya amri. Sampuli ya kikao katika README yake hupungua kutoka tokeni za kawaida `~118,000` hadi tokeni za RTK `~23,900`, ambayo ni uokoaji wa `79.7%` (`~80%`). OmniRoute hutumia wastani huo wa awali kwa hesabu ya uokoaji wa mtiririko uliopangwa pamoja na ukandamizaji wa ingizo wa Caveman:

```txt
Wastani wa RTK:  80% imeokolewa
Ingizo la Caveman: 46% imeokolewa
Zilizopangwa:    1 - (1 - 0.80) * (1 - 0.46) = 89.2% imeokolewa
Masafa:          1 - (1 - 0.60..0.90) * (1 - 0.46) = 78.4-94.6%
```

## Inachokandamiza

Katalogi iliyojengewa ndani kwa sasa ina vichujio 49 katika kategoria hizi:

| Kategoria | Mifano                                                                     |
| --------- | -------------------------------------------------------------------------- |
| `git`     | `git status`, `git branch`, `git diff`, `git log`                          |
| `test`    | Vitest, Jest, Pytest, Playwright, majaribio ya Go, majaribio ya Cargo      |
| `build`   | TypeScript, ESLint, Biome, Prettier, Vite, Webpack, Turbo, Nx              |
| `package` | `npm install`, `npm audit`, `pip`, `uv sync`, Poetry, Bundler              |
| `shell`   | `ls`, `find`, `grep`, kumbukumbu za kawaida za shell                       |
| `docker`  | `docker ps`, kumbukumbu za Docker                                          |
| `infra`   | Terraform, OpenTofu, `systemctl status`                                    |
| `generic` | Matokeo ya JSON, ufuatiliaji wa rundo, chaguo-msingi la matokeo ya kawaida |

Kitambuzi katika `open-sse/services/compression/engines/rtk/commandDetector.ts` huainisha matokeo kabla ya uteuzi wa kichujio. Vichujio vinaweza pia kulingana na muundo wa amri au regex ya matokeo wakati aina ya amri haitoshi.

## Utatuzi wa Vichujio

RTK hupakia vichujio kwa mpangilio huu:

1. Vichujio vya mradi kutoka `.rtk/filters.toml` na `.rtk/filters.json`, ikiwa tu vinaaminika.
2. Vichujio vya kimataifa kutoka `DATA_DIR/rtk/filters.toml` na `DATA_DIR/rtk/filters.json`.
3. Vichujio vilivyojengewa ndani kutoka `open-sse/services/compression/engines/rtk/filters/`.

Ndani ya upeo mmoja, vichujio vya RTK TOML schema v1 vina kipaumbele juu ya vichujio vya OmniRoute JSON. Misemo ya TOML `match_command` hukaguliwa kabla ya ulinganishaji wa aina ya amri ili kichujio mahususi cha amri kilichoingizwa kiweze kubatilisha kichujio kipana zaidi katika upeo huo. Upeo wa mradi bado una kipaumbele juu ya upeo wa kimataifa, bila kujali umbizo la faili.

Vichujio vya mradi huwekewa kwa makusudi sharti la uaminifu kwa sababu vichujio vya regex vinaweza kubadilisha jinsi matokeo ya zana yanavyoonyeshwa kwa mawakala. Faili ya kichujio cha mradi hukubaliwa wakati mojawapo ya masharti haya ni kweli:

- `rtkConfig.trustProjectFilters` ni `true`.
- `OMNIROUTE_RTK_TRUST_PROJECT_FILTERS=1` imewekwa.
- `.rtk/trust.json` ina hash inayolingana ya SHA-256 kwa faili ya kichujio cha mradi.

Mfano wa faili ya uaminifu:

```json
{
  "filtersSha256": "0123456789abcdef...",
  "filtersTomlSha256": "fedcba9876543210..."
}
```

Hash zimetenganishwa: `filtersSha256` huamini `.rtk/filters.json`, huku `filtersTomlSha256` ikiamini `.rtk/filters.toml`. Kuhariri faili yoyote kati ya hizo hubatilisha tu ingizo lake la uaminifu. Faili za kimataifa husakinishwa na msimamizi na hutumia mwenendo uliopo wa uaminifu wa vichujio vya kimataifa.

Vichujio maalum vinaweza kuwa kipengee kimoja cha kichujio au safu ya vipengee vya vichujio. Vichujio maalum visivyo halali hurukwa na kuripotiwa na uchunguzi wa `/api/context/rtk/filters`. Vichujio vilivyojengewa ndani visivyo halali husababisha hitilafu mara moja.

## Upatanifu wa schema ya RTK TOML v1

OmniRoute inaweza kuchanganua, kuthibitisha, kujaribu na kusakinisha faili tangazo za vichujio kwa kutumia schema ya RTK TOML v1.
Sehemu zinazotumika ni `description`, `match_command`, `strip_ansi`, `filter_stderr`,
`strip_lines_matching`, `keep_lines_matching`, `replace`, `match_output`, `truncate_lines_at`,
`head_lines`, `tail_lines`, `max_lines`, `on_empty`, na majaribio ya ndani ya `[[tests.<filter>]]`.
Sehemu zisizotambulika, semi za kawaida zisizo sahihi au zisizo salama, kanuni za kuondoa/kuhifadhi zinazotumika kwa wakati mmoja, faili zinazozidi
1 MiB, na marejeleo ya vichujio visivyojulikana hukataliwa. Faili ambayo majaribio yake ya ndani yameshindwa inaweza
kuthibitishwa kwa ajili ya ukaguzi lakini haiwezi kusakinishwa au kupakiwa. Hitilafu za upakiaji wa faili maalum hubaki
katika hali ya kuruhusu kuendelea: faili batili hurukwa na vichujio vilivyosalia huendelea kufanya kazi.

OmniRoute hupokea matokeo ya zana baada ya kiteja kuyakamata tayari, kwa hivyo `filter_stderr = true`
haiwezi kubadilisha unasa wa mchakato. Sehemu hii inakubaliwa bila kutekeleza kitendo chochote na uthibitishaji hurejesha onyo.
Hii inaelezewa kwa makusudi kama **upatanifu wa schema ya RTK TOML v1**, si upatanifu kamili
na faili tekelezi ya RTK, vianzio vya shell, utekelezaji wa amri za Rust, au mpangilio wake wa hifadhi ya uaminifu.

Mwonekano wa kina wa RTK kwenye dashibodi hukubali TOML iliyobandikwa au kupakiwa. Uthibitishaji ni wa kusoma pekee.
Usakinishaji huandika `DATA_DIR/rtk/filters.toml` kiatomiki kwa ruhusa zenye vizuizi na kuonyesha upya
orodha hai ya vichujio bila kuwasha upya. Kubadilisha faili iliyopo kunahitaji uthibitisho wa wazi wa `overwrite`
na huunda `DATA_DIR/rtk/filters.toml.bak` kwanza.

## DSL ya Vichujio

Vichujio hutumia schema ya JSON iliyofafanuliwa katika [Muundo wa Kanuni za Mfinyazo](./COMPRESSION_RULES_FORMAT.md).
Wakati wa utekelezaji, hatua hizi hutumika kwa mpangilio ufuatao:

```txt
stripAnsi -> filterStderr -> replace -> matchOutput -> ondoa/jumuisha mistari
  -> truncateLineAt -> head/tail/maxLines -> onEmpty
```

Sehemu muhimu:

| Sehemu                       | Madhumuni                                                                            |
| ---------------------------- | ------------------------------------------------------------------------------------ |
| `rules.stripAnsi`            | Kuondoa mifuatano ya rangi/udhibiti wa terminal kabla ya kulinganisha                |
| `rules.filterStderr`         | Kusawazisha viambishi awali vya kawaida vya stderr kabla ya kulinganisha/kuchuja     |
| `rules.replace`              | Kutumia vibadilisho vya semi za kawaida kwa mpangilio                                |
| `rules.matchOutput`          | Kurejesha muhtasari mfupi wakati matokeo yanalingana na hali inayojulikana           |
| `rules.matchOutput[].unless` | Kuruka njia ya mkato wakati muundo wa hitilafu/kushindwa upo                         |
| `rules.dropPatterns`         | Kuondoa mistari yenye kelele                                                         |
| `rules.includePatterns`      | Kupa kipaumbele mistari inayoweza kufanyiwa kazi                                     |
| `rules.collapsePatterns`     | Kukusanya mistari inayolingana na kujirudia                                          |
| `rules.deduplicate`          | Uwezeshaji wa hiari kwa kila kichujio: kukusanya mistari inayofuatana na inayofanana |
| `rules.truncateLineAt`       | Kufupisha kila mstari kwa usalama wa Unicode                                         |
| `rules.onEmpty`              | Ujumbe mbadala ikiwa mistari yote imechujwa                                          |
| `tests[]`                    | Sampuli za ndani zinazotumiwa na lango la uthibitishaji                              |

Vichujio vilivyojengewa ndani vinatarajiwa kujumuisha sampuli za ndani za `tests[]`. Vichujio maalum vinapaswa kuvijumuisha
pia, hasa vinaposhirikiwa katika miradi mbalimbali.

## Uondoaji wa Mistari Iliyojirudia (tabaka mbili)

RTK huunganisha mistari iliyojirudia katika tabaka mbili zinazojitegemea:

1. **`deduplicate` ya kila kichujio (ya kuchagua, chaguo-msingi `false`).** Kichujio kinaweza kuweka `rules.deduplicate: true`
   ili kuunganisha mistari inayofuatana iliyojirudia _ndani ya matokeo yaliyolingana ya kichujio hicho_, kabla ya ufupishaji.
   Hili hutekelezwa ndani ya `lineFilter.ts`. Kwa vichujio vya zamani, huwashwa kiotomatiki kichujio kinapofafanua
   `collapsePatterns`. Skema: `deduplicate: z.boolean().default(false)` katika
   `open-sse/services/compression/engines/rtk/filterSchema.ts`.
2. **`deduplicateThreshold` ya injini nzima (chaguo-msingi `3`).** Baada ya vichujio vyote kutekelezwa, injini huunganisha
   mfululizo wowote wa mistari inayofanana kabisa na inayofuatana wenye `>= deduplicateThreshold` katika matokeo yote
   (`deduplicateRepeatedLines`, inayotumika katika `engines/rtk/index.ts`). Thamani huwekewa mipaka ya 2–100 wakati wa
   usawazishaji.

Hatua ya kila kichujio hutekelezwa kwanza (ndani ya kichujio), na hatua ya injini nzima hutekelezwa mwisho (juu ya
matokeo yaliyounganishwa), kwa hivyo hatua hizo mbili huungana bila kuhesabu mara mbili.

## Upangaji wa Mistari katika Makundi (`enableGrouping`)

Wakati `rtkConfig.enableGrouping` ni `true` (chaguo-msingi `false`), RTK hutekeleza hatua ya ziada ya `groupSimilarLines`
juu ya matokeo baada ya uondoaji wa marudio, ambayo huunganisha mifuatano ya mistari inayofuatana iliyo _karibu kufanana_ (si inayofanana baiti kwa baiti).
`rtkConfig.groupingThreshold` (chaguo-msingi `3`) ni urefu wa chini kabisa wa mfululizo unaoanzisha
upangaji katika makundi. Hiki ni kilinganishi cha kimuundo cha `deduplicateThreshold`: uondoaji wa marudio hushughulikia marudio yanayofanana kabisa,
ilhali upangaji katika makundi hushughulikia "umbo lilelile lenye tofauti ndogo". Alama zote mbili ni sehemu ya JSON ya `rtkConfig`
inayohifadhiwa katika jedwali la `key_value` (angalia Usanidi hapo juu), kwa hivyo mpangilio hudumu baada ya kuanzisha upya.

## Uondoaji wa Maoni ya Msimbo (`stripCodeComments` / `preserveDocstrings`)

Wakati `rtkConfig.applyToCodeBlocks` imewashwa, RTK inaweza pia kuondoa maoni kutoka kwenye vizuizi vya msimbo vilivyowekewa uzio:

- `stripCodeComments` (chaguo-msingi `false`) — ya kuchagua. Ikiwa `true`, RTK huondoa maoni kutoka kwenye vizuizi vya JavaScript
  na TypeScript vilivyowekewa uzio. Kihistoria, alama hii ilisomwa lakini haikutumika kamwe, kwa hivyo chaguo-msingi linasalia
  kuwa "hifadhi" ili kuepuka mabadiliko yasiyoonekana katika mazingira ya uzalishaji.
- `preserveDocstrings` (chaguo-msingi `true`) — wakati wa kuondoa maoni, maoni ya vizuizi vya JSDoc/`/** … */`
  huhifadhiwa (yana nyaraka za API zenye thamani kubwa kuliko baiti yanazotumia). Weka `false` ili kuyaondoa
  pia.

Uondoaji wa maoni umetekelezwa katika `open-sse/services/compression/engines/rtk/codeStripper.ts`. Hutumia
**kichanganuzi cha TypeScript** (si regex) ili tungo za mifuatano, violezo na regex zisitambuliwe kimakosa
kuwa maoni, na husitisha kabisa inapogundua JSX (ili maoni ya kontena za vielezi vya JSX
yasiharibiwe kamwe). Kwa sasa, uondoaji wa maoni hutumika kwa **JavaScript na TypeScript pekee** — lugha nyingine
katika seti ya `CodeLanguage` ya kiondoaji (Python, Rust, Go, Ruby, Java) zina uunganishaji wa mistari mitupu na
nafasi tupu lakini hazina uondoaji wa maoni. Utekelezaji wa kizuizi kilichoondolewa maoni huwekewa lebo ya `rtk:code-strip` katika
`rulesApplied`.

> **Kumbuka — GCF / usimbaji wa kijedwali ni injini tofauti.** RTK **haina** kisimbaji cha JSON cha kijedwali/kisafu cha "GCF"
> (Graph Compact Format). Kisimbaji hicho — kilichochukua nafasi ya kisimbaji cha zamani cha
> `omni-tabular` — kinapatikana katika injini ya **headroom**
> (`open-sse/services/compression/engines/headroom/`, huku kodeki iliyojumuishwa ikiwa chini ya
> `headroom/gcf/`). Hakihusiani na mchakato wa vichujio vya RTK ulioandikwa hapa.

## Usanidi

Mipangilio ya jumla inapatikana kupitia `/api/settings/compression`. Mipangilio mahususi ya RTK pia
inapatikana kupitia `/api/context/rtk/config`.

```json
{
  "defaultMode": "stacked",
  "autoTriggerMode": "stacked",
  "autoTriggerTokens": 32000,
  "stackedPipeline": [
    { "engine": "rtk", "intensity": "standard" },
    { "engine": "caveman", "intensity": "full" }
  ],
  "rtkConfig": {
    "enabled": true,
    "intensity": "standard",
    "applyToToolResults": true,
    "applyToCodeBlocks": false,
    "applyToAssistantMessages": false,
    "enabledFilters": [],
    "disabledFilters": [],
    "maxLinesPerResult": 120,
    "maxCharsPerResult": 12000,
    "deduplicateThreshold": 3,
    "customFiltersEnabled": true,
    "trustProjectFilters": false,
    "rawOutputRetention": "never",
    "rawOutputMaxBytes": 1048576,
    "enableGrouping": false,
    "groupingThreshold": 3,
    "stripCodeComments": false,
    "preserveDocstrings": true
  }
}
```

`enabledFilters` na `disabledFilters` hutumia vitambulisho vya vichujio, kwa mfano `test-vitest` au `git-diff`.

Muundo kamili wa `rtkConfig` unafafanuliwa na `RtkConfig` / `DEFAULT_RTK_CONFIG` katika
`open-sse/services/compression/types.ts`. Kitu kizima huhifadhiwa kama thamani moja ya JSON katika
jedwali la SQLite `key_value` chini ya `namespace = "compression"`, `key = "rtkConfig"`
(`src/lib/db/compression.ts`), na husawazishwa wakati wa kusomwa na `normalizeRtkConfig`. Kwa hiyo, kila uga ulio hapa chini
— ikiwa ni pamoja na `enableGrouping`, `groupingThreshold`, `stripCodeComments`, na `preserveDocstrings` —
hupitia hifadhi hiyo hiyo kwenda na kurudi na hubaki baada ya kuwasha upya.

| Ufunguo                | Chaguo-msingi | Madhumuni                                                                                                  |
| ---------------------- | ------------- | ---------------------------------------------------------------------------------------------------------- |
| `deduplicateThreshold` | `3`           | Injini nzima: idadi ya chini ya mistari inayofanana mfululizo inayokunjwa (kati ya 2–100)                  |
| `enableGrouping`       | `false`       | Hiari: kunja mifuatano ya mistari inayokaribia kufanana iliyo mfululizo                                    |
| `groupingThreshold`    | `3`           | Idadi ya chini ya mistari inayofanana mfululizo inayosababisha upangaji katika kikundi                     |
| `stripCodeComments`    | `false`       | Hiari: ondoa maoni kutoka kwenye vizuizi vya msimbo vilivyozungushiwa uzio (inahitaji `applyToCodeBlocks`) |
| `preserveDocstrings`   | `true`        | Wakati wa kuondoa maoni, hifadhi vizuizi vya JSDoc/`/** … */`                                              |

## API

| Njia                               | Mbinu | Madhumuni                                                 |
| ---------------------------------- | ----- | --------------------------------------------------------- |
| `/api/context/rtk/config`          | GET   | Soma usanidi wa RTK                                       |
| `/api/context/rtk/config`          | PUT   | Sasisha usanidi wa RTK                                    |
| `/api/context/rtk/filters`         | GET   | Orodhesha katalogi ya vichujio na uchunguzi wa upakiaji   |
| `/api/context/rtk/import`          | POST  | Thibitisha au sakinisha faili za schema ya RTK TOML v1    |
| `/api/context/rtk/test`            | POST  | Hakiki mbano wa RTK kwa mzigo mmoja wa maandishi          |
| `/api/context/rtk/raw-output/[id]` | GET   | Soma towe ghafi lililohifadhiwa na kufichwa taarifa nyeti |
| `/api/compression/preview`         | POST  | Hakiki hali yoyote ya mbano                               |

Mzigo wa jaribio la RTK:

```json
{
  "command": "npm test",
  "text": "FAIL tests/example.test.ts\nAssertionError: expected true\nTest Files 1 failed",
  "config": {
    "intensity": "standard"
  }
}
```

Mzigo wa uhakiki wa mbano:

```json
{
  "mode": "stacked",
  "messages": [
    {
      "role": "tool",
      "content": "FAIL tests/example.test.ts\nAssertionError: expected true\nTest Files 1 failed"
    }
  ],
  "config": {
    "rtkConfig": {
      "rawOutputRetention": "failures"
    }
  }
}
```

Njia za usimamizi zinahitaji uthibitishaji wa usimamizi wa dashibodi au sera inayolingana ya ufunguo wa API.

Mzigo wa uthibitishaji wa RTK TOML:

```json
{
  "action": "validate",
  "content": "schema_version = 1\n\n[filters.my-tool]\nmatch_command = \"^my-tool\\\\b\"\nmax_lines = 20\n"
}
```

Tumia `"action": "install"` kusakinisha faili iliyothibitishwa kimataifa. Ongeza `"overwrite": true` tu
baada ya kukagua na kuthibitisha ubadilishaji wa faili iliyopo ya kimataifa.

## Urejeshaji wa Matokeo Ghafi

Kwa kawaida RTK hurejesha maandishi yaliyobanwa pekee. Kwa utatuzi, `rawOutputRetention` inaweza kuhifadhi matokeo ghafi yaliyofichwa taarifa nyeti:

| Thamani    | Tabia                                                               |
| ---------- | ------------------------------------------------------------------- |
| `never`    | Usihifadhi matokeo ghafi                                            |
| `failures` | Hifadhi tu matokeo ambayo huenda yanaonyesha hitilafu               |
| `always`   | Hifadhi kila tokeo ghafi la RTK lililobanwa, baada ya kuficha nyeti |

Faili zilizohifadhiwa huandikwa chini ya:

```txt
DATA_DIR/rtk/raw-output/
```

Siri hufichwa kabla ya kuhifadhiwa, ikijumuisha tokeni za kawaida za bearer, funguo za API, tokeni za Slack,
funguo za ufikiaji za AWS, na thamani za mtindo wa ugawaji kama `token=...`, `secret=...`, `password=...`. Takwimu za uchanganuzi
huhifadhi tu kitambulisho cha kielekezi, ukubwa, na metadata ya heshi.

## Lango la Uthibitishaji

Lango mahususi la uthibitishaji huendesha majaribio ya vichujio vilivyojengewa ndani moja kwa moja bila kuita amri za nje kupitia shell:

```bash
node --import tsx/esm --test tests/unit/compression/rtk-verify.test.ts
```

Lango pana zaidi la RTK ni:

```bash
node --import tsx/esm --test \
  tests/unit/compression/rtk-*.test.ts \
  tests/unit/compression/pipeline-integration.test.ts \
  tests/unit/compression/context-compression-api.test.ts
```

Endesha lango pana la ubanaji kabla ya kutoa toleo:

```bash
node --import tsx/esm --test \
  tests/unit/compression/*.test.ts \
  tests/golden-set/*.test.ts \
  tests/integration/compression-pipeline.test.ts \
  tests/unit/api/compression/compression-api.test.ts
```

## Kupanua RTK

1. Ongeza au sasisha faili ya JSON ya kichujio.
2. Jumuisha angalau sampuli moja ya `tests[]` inayothibitisha tabia muhimu.
3. Ongeza fixture chini ya `tests/unit/compression/fixtures/rtk/` kwa familia mpya za amri.
4. Ongeza ushughulikiaji wa utambuzi wa amri unapoanzisha aina mpya ya matokeo.
5. Endesha malango ya uthibitishaji na ya RTK yaliyo mapana.
6. Ikiwa kichujio ni mahususi kwa mradi, commit `.rtk/filters.json` na uonyeshe upya `.rtk/trust.json` baada tu ya ukaguzi.

---

## Viwango vya Ukali (v3.8.16+)

RTK hutumia **viwango 3 vya ukali** vinavyosawazisha **ukali wa ubanaji** na **usalama**. Kiwango huwekwa kupitia `config.intensity` katika usanidi wa injini.

### Viwango 3

| Kiwango                    | Kizingiti cha ufupishaji   | Uokoaji wa tokeni | Hatari     | Kinafaa zaidi kwa                            |
| -------------------------- | -------------------------- | ----------------- | ---------- | -------------------------------------------- |
| `minimal`                  | Mistari 24 kwa kila sehemu | ~20-40%           | Ndogo sana | Uzalishaji wenye muktadha muhimu             |
| `standard` (chaguo-msingi) | Mistari 24 kwa kila sehemu | ~50-70%           | Ndogo      | Vipindi vya kila siku vya uandishi wa msimbo |
| `aggressive`               | Mistari 16 kwa kila sehemu | ~70-90%           | Wastani    | Vipindi virefu, uokoaji wa juu zaidi         |

### Mahali Ufupishaji Unapotokea

Kizingiti cha ufupishaji huathiri `lineFilter.ts`:

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

Sehemu za **mwanzo** na **mwisho** za kila sehemu huhifadhiwa; maudhui ya katikati huondolewa ufupishaji unapoanza kutumika.

### Kinachobaki dhidi ya Kinachokatwa

| Maudhui                                     | minimal        | standard       | aggressive     |
| ------------------------------------------- | -------------- | -------------- | -------------- |
| Hitilafu / ufuatiliaji wa rafu              | ✅ huhifadhiwa | ✅ huhifadhiwa | ✅ huhifadhiwa |
| Majaribio yaliyoshindwa                     | ✅ huhifadhiwa | ✅ huhifadhiwa | ✅ huhifadhiwa |
| Hitilafu za uundaji                         | ✅ huhifadhiwa | ✅ huhifadhiwa | ✅ huhifadhiwa |
| Majaribio yaliyofaulu (yenye maelezo mengi) | ✅ huhifadhiwa | 🟡 hukunjwa    | 🟡 hukunjwa    |
| Matokeo ya kawaida (kumbukumbu za taarifa)  | 🟡 hukunjwa    | 🟡 hukunjwa    | ❌ huondolewa  |
| Pau za maendeleo                            | 🟡 hukunjwa    | ❌ huondolewa  | ❌ huondolewa  |
| Bango / sanaa ya ASCII                      | 🟡 hukunjwa    | ❌ huondolewa  | ❌ huondolewa  |

### Kuchagua Ukali Unaofaa

```
                  Je, kupoteza muktadha ni janga?
                  │
      ┌───────────┼───────────┐
      │           │           │
    NDIYO       HAPANA      HUNA UHAKIKA
      │           │           │
      ▼           │           │
   minimal        │           │
      │           │           │
      │           ▼           ▼
      │      Ufanisi ni      Jaribu `standard` kwanza
      │      muhimu kiasi    (hufaa kwa 80% ya
      │      gani?           hali)
      │      ┌────┴────┐
      │      │         │
      │    MDOGO      MKUBWA
      │      │         │
      │      ▼         ▼
      │   standard   aggressive
      │      │         │
      └──────┴─────────┘
```

### Kusanidi Ukali

**Kwa kila combo** (katika usanidi wa combo):

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

**Kwa njia ya kiprogramu**:

`rtkEngine` (`@omniroute/open-sse/services/compression/engines/rtk`) ni
`CompressionEngine` na haina mbinu ya `updateConfig`. Sasisha usanidi wa injini
kupitia kisaidizi cha sajili badala yake:

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

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

### Kuthibitisha Athari

Tumia **Lango la Uthibitishaji** (tazama hapa chini) ili kuthibitisha kuwa kichujio chako ni salama katika ukali uliochagua:

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

const result = runRtkFilterTests({ intensity: "aggressive" });
if (!result.passed) {
  console.error("Filters failed at aggressive intensity");
}
```

---

## Utengenezaji wa Kichujio Maalum (v3.8.16+)

Saraka ya `engines/rtk/filters/` ina **faili 49+ za JSON za vichujio vilivyojengewa ndani**. Unaweza kuongeza vichujio vyako mwenyewe ili kubana matokeo kutoka kwa zana maalum ambazo hazijashughulikiwa na chaguo chaguomsingi.

### Skima ya Kichujio (Zod)

```ts
{
  "id": "string",                      // Inahitajika. Kitambulishi cha kichujio (kebab-case, kwa mfano, "python-traceback")
  "label": "string",                   // Inahitajika. Jina la kichujio linalosomeka na binadamu
  "description": "string",             // Si lazima (chaguomsingi: ""). Maelezo mafupi kuhusu kile kichujio hufanya
  "category": "git|test|build|shell|docker|package|infra|cloud|generic",
  "priority": number,                  // Si lazima (0-100, chaguomsingi: 50). Mpangilio wa utekelezaji (ya juu = ya kwanza)
  "match": {
    "commands": ["string"],            // Majina ya amri ya kulinganisha (kwa mfano, "python", "pytest")
    "patterns": ["string"],            // Ruwaza za regex za kulinganisha matokeo
    "outputTypes": ["string"]          // Aina za matokeo zilizotambuliwa (kwa mfano, "test-failure")
  },
  "rules": {
    "stripAnsi": boolean,              // Si lazima (chaguomsingi: false). Ondoa misimbo ya rangi ya ANSI
    "replace": [                       // Kanuni za kutafuta-na-kubadilisha (chaguomsingi: [])
      { "pattern": "regex", "replacement": "..." }
    ],
    "matchOutput": [                   // Sitisha mapema ruwaza inapolingana (chaguomsingi: [])
      {
        "pattern": "regex",
        "message": "muhtasari mfupi",
        "unless": "regex"              // Ruka ikiwa ruwaza hii inalingana
      }
    ],
    "includePatterns": ["string"],     // Mistari ya kuhifadhi (ruwaza za regex, chaguomsingi: [])
    "dropPatterns": ["string"],        // Mistari ya kuondoa (ruwaza za regex, chaguomsingi: [])
    "collapsePatterns": ["string"],    // Mistari ya kukunja iwe tukio moja (chaguomsingi: [])
    "deduplicate": boolean,            // Si lazima (chaguomsingi: false). Ondoa mistari inayojirudia
    "truncateLineAt": number,          // Si lazima (chaguomsingi: 0). Kata mistari kufikia upeo wa herufi
    "maxLines": number,                // Si lazima (chaguomsingi: 0). Kikomo thabiti cha jumla ya mistari
    "headLines": number,               // Si lazima (chaguomsingi: 20). Hifadhi mistari N ya kwanza ya matokeo yaliyolingana
    "tailLines": number,               // Si lazima (chaguomsingi: 20). Hifadhi mistari N ya mwisho ya matokeo yaliyolingana
    "onEmpty": "string",               // Si lazima (chaguomsingi: ""). Ujumbe mbadala ikiwa mistari yote imechujwa
    "filterStderr": boolean            // Si lazima (chaguomsingi: false). Chuja pia matokeo ya stderr
  },
  "preserve": {
    "errorPatterns": ["string"],       // Ruwaza ambazo lazima zihifadhiwe daima (chaguomsingi: [])
    "summaryPatterns": ["string"]      // Ruwaza za mstari wa mwisho wa muhtasari (chaguomsingi: [])
  },
  "tests": [                           // Majaribio ya ndani kwa ajili ya uthibitishaji (chaguomsingi: [])
    {
      "name": "string",               // Inahitajika. Jina la jaribio
      "input": "sample output",        // Inahitajika. Maandishi ya mfano ya ingizo
      "expected": "expected output",   // Inahitajika. Matokeo yaliyobanwa yanayotarajiwa
      "command": "optional command"    // Si lazima. Muktadha wa amri
    }
  ]
}
```

### Mfano: Kichujio cha Python Traceback

```json
{
  "id": "python-traceback",
  "label": "Python Traceback Filter",
  "description": "Compresses Python tracebacks to essential file/line locations and error type",
  "category": "test",
  "priority": 60,
  "match": {
    "commands": ["python", "python3", "pytest", "uv", "poetry"],
    "patterns": ["Traceback \\(most recent call last\\)", "Error", "Exception"],
    "outputTypes": ["error-traceback"]
  },
  "rules": {
    "stripAnsi": true,
    "includePatterns": [
      "Traceback \\(most recent call last\\)",
      "^\\s*File \".+\", line \\d+",
      "^\\s*[A-Z][a-zA-Z]+Error:",
      "^\\s*[A-Z][a-zA-Z]+Exception"
    ],
    "dropPatterns": ["site-packages/", "^\\s+[a-z_]+\\([^)]*\\)$"],
    "headLines": 5,
    "tailLines": 3,
    "maxLines": 25,
    "filterStderr": true
  },
  "preserve": {
    "errorPatterns": ["Error:", "Exception:", "Traceback"],
    "summaryPatterns": ["^[A-Z][a-zA-Z]+(?:Error|Exception):"]
  },
  "tests": [
    {
      "name": "preserves-error-type-and-location",
      "input": "Traceback (most recent call last):\n  File \"app.py\", line 42, in main\n    do_thing()\n  File \"lib/utils.py\", line 17, in helper\n    return 1 / 0\nZeroDivisionError: division by zero",
      "expected": "Traceback (most recent call last):\n  File \"app.py\", line 42, in main\n  File \"lib/utils.py\", line 17, in helper\nZeroDivisionError: division by zero",
      "command": "python app.py"
    }
  ]
}
```

### Kupakia Vichujio Maalum

Weka faili katika eneo linalotambuliwa:

```
~/.omniroute/rtk/filters/my-filter.json     # Kiwango cha mtumiaji
<project>/.rtk/filters/my-filter.json      # Kiwango cha mradi
```

Vichujio hupakiwa kiotomatiki wakati wa kuanza kupitia `loadRtkFilters()` katika `open-sse/services/compression/engines/rtk/filterLoader.ts`. Kipakiaji hugundua vichujio kutoka:

- Katalogi iliyojengewa ndani: `open-sse/services/compression/engines/rtk/filters/`
- Saraka ya mtumiaji: `~/.omniroute/rtk/filters/`
- Saraka ya mradi: `<project>/.rtk/filters/`

Ili kupakia vichujio kwa njia ya programu:

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

// Chaguo: customFiltersEnabled (pakia vichujio vya mtumiaji/mradi, imewashwa kwa chaguomsingi),
// trustProjectFilters, refresh.
const filters = loadRtkFilters({ customFiltersEnabled: true });
```

### Uthibitishaji

Vichujio huthibitishwa dhidi ya skima ya Zod vinapopakiwa. Kichujio chenye muundo usio sahihi kitashindwa kupakiwa na hitilafu itaandikwa kwenye kumbukumbu:

```
RTK_FILTER_LOADER: kichujio "my-filter" kimeshindwa uthibitishaji:
  - rules.replace.0.pattern: Regex si halali
  - match.commands: lazima isiwe tupu
```

Ili kuthibitisha vichujio vyote vilivyosakinishwa, ita `runRtkFilterTests()` ambayo inahamishwa kutoka `open-sse/services/compression/engines/rtk/verify.ts`.

### Mbinu Bora

1. **Daima jumuisha `tests[]`** — zinathibitisha kuwa kichujio chako kinafanya kazi na kuzuia hitilafu kujirudia
2. **Tumia `matchOutput` kwa ukatishaji wa mapema** — ikiwa mstari mmoja unaeleza kila kitu, badilisha bloku nzima
3. **Pendelea `keep` kuliko `strip`** — kanuni za wazi za "hifadhi daima" ni salama zaidi kuliko "ondoa daima"
4. **Jaribu katika viwango vyote 3 vya ukali** — `minimal` haipaswi kufanya mabadiliko yoyote, na `aggressive` bado inapaswa kuhifadhi hitilafu
5. **Tumia sehemu ya `unless`** — linda ukatishaji wa mapema kwa sharti la "usianzishwe ikiwa X ipo"

---

## Urejeshaji wa Matokeo Ghafi na Lango la Uthibitishaji

RTK inapobana matokeo kwa kiwango kikubwa, unaweza **kurejesha maandishi ya awali** kwa ajili ya utatuzi, ukaguzi, au urudiaji.

### Jinsi Urejeshaji wa Matokeo Ghafi Unavyofanya Kazi

```
Matokeo ya awali (tokeni 10K)
        │
        ▼
RTK inabana (rawOutput.enabled=true)
        │
        ├─▶ Matokeo yaliyobanwa (tokeni 2K)  ──▶ kwenda kwa LLM
        │
        └─▶ Matokeo ya awali (tokeni 10K)     ──▶ yanahifadhiwa katika DB
                                                  (yameunganishwa kwa request_id)
```

### Kuwasha Hifadhi ya Matokeo Ghafi

**Kwa kila ombi** (katika usanidi wa mchanganyiko):

```json
{
  "compression": {
    "engine": "rtk",
    "intensity": "aggressive",
    "rawOutput": {
      "enabled": true,
      "maxBytes": 1048576 // Kikomo cha 1MB
    }
  }
}
```

**Chaguo-msingi**: `rawOutput.enabled: false` (huokoa nafasi ya hifadhi).

### Gharama ya Hifadhi

| Kwa kila ombi                  | Kikomo cha 1MB | Kikomo cha 10MB |
| ------------------------------ | -------------- | --------------- |
| Wastani wa matokeo yaliyobanwa | ~5KB           | ~5KB            |
| Matokeo ghafi yaliyohifadhiwa  | ~50-500KB      | ~500KB-5MB      |
| Kwa maombi 1000 kwa siku       | 50-500MB/siku  | 500MB-5GB/siku  |

> **Pendekezo**: Washa matokeo ghafi kwa **vipindi vya utatuzi** au **ukaguzi wa sampuli** pekee, si muda wote.

### Kurejesha Matokeo ya Awali

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

const raw = readRtkRawOutput(pointerId); // pointerId kutoka kwenye takwimu za ubanaji
if (raw) {
  console.log("Original output:", raw);
}
```

`pointerId` inarejeshwa katika `CompressionStats.rtkRawOutputPointers[]` baada ya ubanaji.
Angalia `open-sse/services/compression/engines/rtk/rawOutput.ts:102` kwa saini ya kitendakazi.

### Lango la Uthibitishaji

**Uthibitishaji wa Vichujio vya RTK** (`open-sse/services/compression/engines/rtk/verify.ts`) huhakiki vichujio vyote dhidi ya `tests[]` zake na kuhakikisha tabia ni sahihi katika viwango vyote 3 vya ukali.

**Ite `runRtkFilterTests()`** ili kuendesha uthibitishaji:

```ts
import { runRtkFilterTests } from "open-sse/services/compression/engines/rtk/verify";

const result = runRtkFilterTests();
console.log(`Passed: ${result.outcomes.filter((o) => o.passed).length}`);
console.log(`Failed: ${result.outcomes.filter((o) => !o.passed).length}`);
if (!result.passed) {
  console.error("Filters failed verification");
  result.outcomes
    .filter((o) => !o.passed)
    .forEach((o) => {
      console.error(
        `  - ${o.filterId} / ${o.testName}: expected "${o.expected}", got "${o.actual}"`
      );
    });
}
```

**Mambo inayohakiki**:

1. Kila kichujio hupakiwa na kufaulu uthibitishaji wa skima
2. Kila ingizo la `tests[]` hutoa matokeo yanayotarajiwa
3. Kiwango cha ukali cha `minimal` hakifanyi mabadiliko yoyote (huhifadhi matokeo ya awali na kutumia vichujio vya kimuundo pekee)
4. Kiwango cha ukali cha `aggressive` huhifadhi hitilafu, kushindwa kwa majaribio, na ufuatiliaji wa rundo
5. Matokeo yaliyobanwa kamwe hayawi makubwa kuliko ingizo la awali

- Chanzo: `open-sse/services/compression/engines/rtk/` (faili 63, ~70KB)

- **Kabla ya kuunganisha badiliko la kichujio** — hakikisha kila mara majaribio yanafaulu
- **Baada ya kusasisha injini ya RTK** — huenda skima imebadilika
- **Mara kwa mara katika ufuatiliaji** — hulinda dhidi ya mkengeuko katika data za majaribio
- **Unapoongeza familia mpya ya zana/amri** — huthibitisha kwamba kichujio kipya kinafanya kazi

---

## Tazama Pia

- [COMPRESSION_GUIDE.md](./COMPRESSION_GUIDE.md) — Muhtasari kamili wa mchakato wa ukandamizaji
- [COMPRESSION_ENGINES.md](./COMPRESSION_ENGINES.md) — Rejesta ya injini na injini zilizojengewa ndani
- [EXTENDING_COMPRESSION.md](./EXTENDING_COMPRESSION.md) — Injini maalum, vifurushi vya lugha, michakato iliyopangwa kwa tabaka
- Chanzo: `open-sse/services/compression/engines/rtk/` (faili 63, ~70KB)