# RTK Compression (Hausa)

🌐 **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) · 🇮🇱 [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) · 🇰🇪 [sw](../../../sw/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)

---

Matsawar RTK ita ce injin matsewa na OmniRoute mai fahimtar umarni don fitarwar terminal da kayan aiki. An
ƙera ta ne don zaman wakilan coding inda mafi yawan ƙaruwar mahallin ke fitowa daga rajistan gwaji, fitarwar build,
hayaniyar package manager, rubutattun bayanan shell, fitarwar Docker, fitarwar git, da stack traces.

RTK na iya aiki kai tsaye da `defaultMode: "rtk"` ko a matsayin mataki na farko a cikin jerin matsewa, yawanci:

```txt
rtk -> caveman
```

Wannan tsari yana fara matse fitarwar na'ura mai hayaniya, sannan ya bar Caveman ya taƙaita sauran rubutun bayani.

RTK na asali yana bayar da rahoton adana `60-90%` na fitarwar umarni. Misalin zaman da ke cikin README ɗinsa ya sauka daga
daidaitattun tokens `~118,000` zuwa tokens na RTK `~23,900`, wanda ke nufin an adana `79.7%` (`~80%`). OmniRoute yana amfani da
wannan matsakaicin na asali don lissafin adanawar matsewa mai jerin matakai tare da matse shigarwar Caveman:

```txt
Matsakaicin RTK:  80% an adana
Shigarwar Caveman: 46% an adana
A jere:          1 - (1 - 0.80) * (1 - 0.46) = 89.2% an adana
Kewayo:          1 - (1 - 0.60..0.90) * (1 - 0.46) = 78.4-94.6%
```

## Abin da Take Matsewa

Kundin da aka gina a ciki a halin yanzu yana zuwa da filters 49 a waɗannan rukunan:

| Rukuni    | Misalai                                                               |
| --------- | --------------------------------------------------------------------- |
| `git`     | `git status`, `git branch`, `git diff`, `git log`                     |
| `test`    | Vitest, Jest, Pytest, Playwright, gwaje-gwajen Go, gwaje-gwajen Cargo |
| `build`   | TypeScript, ESLint, Biome, Prettier, Vite, Webpack, Turbo, Nx         |
| `package` | `npm install`, `npm audit`, `pip`, `uv sync`, Poetry, Bundler         |
| `shell`   | `ls`, `find`, `grep`, rajistan shell na gama-gari                     |
| `docker`  | `docker ps`, rajistan Docker                                          |
| `infra`   | Terraform, OpenTofu, `systemctl status`                               |
| `generic` | Fitarwar JSON, stack traces, madadin fitarwa na gama-gari             |

Mai gano nau'i da ke cikin `open-sse/services/compression/engines/rtk/commandDetector.ts` yana rarraba fitarwa
kafin zaɓin filter. Filters kuma za su iya daidaitawa bisa tsarin umarni ko regex na fitarwa idan rukunin umarni
bai wadatar ba.

## Tantance Filter

RTK tana loda filters a wannan tsari:

1. Filters na project daga `.rtk/filters.toml` da `.rtk/filters.json`, kawai idan an amince da su.
2. Filters na global daga `DATA_DIR/rtk/filters.toml` da `DATA_DIR/rtk/filters.json`.
3. Filters da aka gina a ciki daga `open-sse/services/compression/engines/rtk/filters/`.

A cikin scope ɗaya, filters na RTK TOML schema v1 suna da fifiko a kan filters na OmniRoute JSON. Ana duba
furucin TOML `match_command` kafin daidaitawa da nau'in umarni domin filter da aka shigo da shi na takamaiman umarni
ya iya maye gurbin filter mai faɗi a cikin wannan scope. Scope na project har yanzu yana da fifiko a kan scope na global,
ba tare da la'akari da tsarin fayil ba.

Da gangan an sanya filters na project ƙarƙashin sharadin amincewa saboda regex filters na iya sauya yadda ake
nuna fitarwar kayan aiki ga wakilai. Ana karɓar fayil ɗin filter na project idan ɗaya daga cikin waɗannan gaskiya ne:

- `rtkConfig.trustProjectFilters` yana `true`.
- An saita `OMNIROUTE_RTK_TRUST_PROJECT_FILTERS=1`.
- `.rtk/trust.json` yana ɗauke da hash na SHA-256 da ya dace da fayil ɗin filter na project.

Misalin fayil ɗin amincewa:

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

Hashes ɗin sun bambanta: `filtersSha256` yana amincewa da `.rtk/filters.json`, yayin da `filtersTomlSha256`
ke amincewa da `.rtk/filters.toml`. Gyara kowane fayil yana soke takardar amincewarsa kawai. Masu gudanarwa ne
ke girka fayilolin global kuma suna amfani da halin amincewa da global-filter da ake da shi.

Filters na musamman na iya zama object ɗin filter guda ɗaya ko array na objects na filter. Ana tsallake filters na musamman
marasa inganci kuma diagnostics na `/api/context/rtk/filters` yana bayar da rahotonsu. Filters da aka gina a ciki marasa inganci suna dakatar da aiki nan take.

## Daidaituwar RTK TOML schema v1

OmniRoute na iya tantancewa, ingantawa, gwadawa, da shigar da fayilolin tacewa na bayani ta amfani da RTK TOML schema v1.
Filayen da ake tallafawa su ne `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`, da gwaje-gwajen cikin layi na `[[tests.<filter>]]`.
Ana ƙin filayen da ba a sani ba, regular expressions marasa inganci ko haɗari, dokokin cirewa/riƙewa da aka yi amfani da su lokaci guda, fayilolin da suka wuce
1 MiB, da manazarta zuwa matatan da ba a sani ba. Ana iya inganta fayil ɗin da gwaje-gwajensa na cikin layi suka gaza domin dubawa, amma ba za a iya shigar ko loda shi ba. Gazawar loda fayil na musamman tana ci gaba da
barin tsarin a buɗe: ana tsallake fayil ɗin da ba shi da inganci, sannan sauran matatan su ci gaba da aiki.

OmniRoute yana karɓar fitarwar kayan aiki bayan abokin ciniki ya riga ya kama ta, don haka `filter_stderr = true`
ba zai iya canza yadda ake kama aikin ba. Ana karɓar filin a matsayin aikin da ba ya yin komai, kuma ingantawa tana dawo da gargadi.
Da gangan aka bayyana wannan a matsayin **daidaituwar RTK TOML schema v1**, ba cikakkiyar daidaituwa
da RTK executable, shell hooks, aiwatar da umarnin Rust, ko tsarin trust-store nasa ba.

Babban mahangar RTK ta dashboard tana karɓar TOML da aka liƙa ko aka ɗora. Ingantawa ta karatu kaɗai ce.
Shigarwa tana rubuta `DATA_DIR/rtk/filters.toml` ta atomatik tare da tsauraran izini, sannan ta sabunta
kundin matatan da ke aiki ba tare da sake farawa ba. Maye gurbin fayil da yake akwai yana buƙatar tabbatarwar `overwrite`
a sarari, kuma yana fara ƙirƙirar `DATA_DIR/rtk/filters.toml.bak`.

## DSL na Tacewa

Matata suna amfani da JSON schema da aka bayyana a [Tsarin Dokokin Matsewa](./COMPRESSION_RULES_FORMAT.md).
Lokacin aiki yana aiwatar da waɗannan matakai a jere:

```txt
stripAnsi -> filterStderr -> replace -> matchOutput -> sauke/haɗa layuka
  -> truncateLineAt -> head/tail/maxLines -> onEmpty
```

Muhimman filaye:

| Fili                         | Manufa                                                                       |
| ---------------------------- | ---------------------------------------------------------------------------- |
| `rules.stripAnsi`            | Cire jerin launi/sarrafa na terminal kafin daidaitawa                        |
| `rules.filterStderr`         | Daidaita gabatarwar stderr da aka saba amfani da ita kafin daidaitawa/tacewa |
| `rules.replace`              | Aiwatar da sauye-sauyen regex a jere                                         |
| `rules.matchOutput`          | Mayar da taƙaitaccen bayani idan fitarwa ta dace da sanannen yanayi          |
| `rules.matchOutput[].unless` | Tsallake gajeriyar hanyar idan akwai alamar kuskure/gazawa                   |
| `rules.dropPatterns`         | Cire layukan da ba su da amfani                                              |
| `rules.includePatterns`      | Fifita layukan da za a iya ɗaukar mataki a kansu                             |
| `rules.collapsePatterns`     | Haɗa layukan da suka dace masu maimaituwa                                    |
| `rules.deduplicate`          | Zaɓin shiga na kowace matata: haɗa layukan kwafi masu jere                   |
| `rules.truncateLineAt`       | Gajarta kowane layi cikin aminci ga Unicode                                  |
| `rules.onEmpty`              | Saƙon madadin idan an tace dukkan layuka                                     |
| `tests[]`                    | Samfuran cikin layi da ƙofar tabbatarwa ke amfani da su                      |

Ana sa ran matatan da aka gina a ciki su ƙunshi samfuran `tests[]` na cikin layi. Ya kamata matatan musamman su ma ƙunshi
su, musamman idan ana amfani da su tare a ayyuka daban-daban.

## Cire Maimaituwar Layi (matakai biyu)

RTK yana haɗa layukan da suka maimaitu a matakai biyu masu zaman kansu:

1. **`deduplicate` na kowane tacewa (sai an kunna, tsoho `false`).** Tacewa na iya saita `rules.deduplicate: true`
   don haɗa layuka masu maimaituwa da suke jere _a cikin sakamakon da wannan tacewar ta dace da shi_, kafin taƙaitawa.
   Wannan yana gudana a cikin `lineFilter.ts`. Ga tsofaffin matatu, ana kunna shi ta atomatik idan tacewar ta ayyana
   `collapsePatterns`. Tsari: `deduplicate: z.boolean().default(false)` a cikin
   `open-sse/services/compression/engines/rtk/filterSchema.ts`.
2. **`deduplicateThreshold` na gaba ɗaya injin (tsoho `3`).** Bayan duk matatu sun gama aiki, injin yana haɗa
   duk wani jerin layuka iri ɗaya masu jere guda `>= deduplicateThreshold` a faɗin dukkan sakamakon
   (`deduplicateRepeatedLines`, wanda ake amfani da shi a cikin `engines/rtk/index.ts`). Ana iyakance ƙimar zuwa 2–100 yayin
   daidaitawa.

Aikin kowane tacewa yana gudana da farko (a cikin tacewar), aikin gaba ɗaya injin kuma yana gudana a ƙarshe (a kan
sakamakon da aka haɗa), don haka su biyun suna aiki tare ba tare da ƙirga abu sau biyu ba.

## Rarraba Layuka Rukuni-rukuni (`enableGrouping`)

Lokacin da `rtkConfig.enableGrouping` yake `true` (tsoho `false`), RTK yana gudanar da wani ƙarin aikin `groupSimilarLines`
a kan sakamakon bayan cire maimaituwa, wanda ke haɗa jerin layuka masu _kusan daidaito_ (ba masu daidaito iri ɗaya ta kowane byte ba)
da suke jere. `rtkConfig.groupingThreshold` (tsoho `3`) shi ne mafi ƙarancin tsawon jeri da ke kunna
rarrabawa rukuni-rukuni. Wannan shi ne takwaran tsari na `deduplicateThreshold`: cire maimaituwa yana kula da ainihin maimaitawa,
rarrabawa rukuni-rukuni kuma yana kula da “siffa ɗaya mai ƙananan bambance-bambance”. Dukkan tutocin suna cikin JSON na `rtkConfig`
da aka adana a cikin teburin `key_value` (duba Kanfigareshan da ke sama), don haka saitin yana ci gaba da kasancewa bayan sake farawa.

## Cire Sharhin Lamba (`stripCodeComments` / `preserveDocstrings`)

Lokacin da aka kunna `rtkConfig.applyToCodeBlocks`, RTK zai iya cire sharhi daga tubalan lamba masu shinge:

- `stripCodeComments` (tsoho `false`) — sai an kunna. Lokacin da yake `true`, RTK yana cire sharhi daga tubalan JavaScript
  da TypeScript masu shinge. A tarihi ana karanta tutar amma ba a taɓa amfani da ita ba, saboda haka tsohon saitin ya ci gaba
  da kasancewa “adana” don guje wa canjin samarwa na shiru.
- `preserveDocstrings` (tsoho `true`) — yayin cire sharhi, ana adana sharhin tubalan JSDoc/`/** … */`
  (suna ɗauke da takardun API da darajarsu ta fi yawan bytes da suke ci). Saita shi zuwa `false` don cire
  su ma.

An aiwatar da cire sharhi a cikin `open-sse/services/compression/engines/rtk/codeStripper.ts`. Yana amfani da
**TypeScript parser** (ba regex ba), don kada a taɓa ɗaukar literals na string, template, da regex a matsayin
sharhi, kuma yana dakatar da aikin gaba ɗaya idan an gano JSX (don kada a taɓa lalata sharhin expression-container na JSX).
A halin yanzu cire sharhi yana aiki ne ga **JavaScript da TypeScript kawai** — sauran
harsunan da ke cikin saitin `CodeLanguage` na stripper (Python, Rust, Go, Ruby, Java) suna da haɗa layukan da babu komai da
fararen sarari, amma ba su da cire sharhi. Ana yi wa aikin tubalin da aka cire wa sharhi alamar `rtk:code-strip` a cikin
`rulesApplied`.

> **Lura — GCF / rufaffen bayanan tebur injin ne daban.** RTK **ba ya** ƙunshe da mai rufaffen bayanan JSON na “GCF”
> (Graph Compact Format) mai tsarin tebur/ginshiƙai. Wannan mai rufaffen bayanan — wanda ya maye gurbin tsohon
> mai rufaffen bayanan `omni-tabular` — yana cikin injin **headroom**
> (`open-sse/services/compression/engines/headroom/`, tare da codec ɗin da aka haɗa a ƙarƙashin
> `headroom/gcf/`). Ba shi da alaƙa da jerin ayyukan tacewa na RTK da aka rubuta a nan.

## Daidaitawa

Ana samun saitunan gaba ɗaya ta `/api/settings/compression`. Haka kuma ana samun saitunan da suka shafi RTK ta
`/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` da `disabledFilters` suna amfani da ID na matata, misali `test-vitest` ko `git-diff`.

An ayyana cikakken tsarin `rtkConfig` ta `RtkConfig` / `DEFAULT_RTK_CONFIG` a cikin
`open-sse/services/compression/types.ts`. Ana adana dukkan abin a matsayin ƙimar JSON guda ɗaya a
teburin SQLite na `key_value` ƙarƙashin `namespace = "compression"`, `key = "rtkConfig"`
(`src/lib/db/compression.ts`), sannan `normalizeRtkConfig` yana daidaita shi yayin karantawa. Don haka, kowane fili da ke ƙasa
— ciki har da `enableGrouping`, `groupingThreshold`, `stripCodeComments`, da `preserveDocstrings` —
yana bi ta ma'ajiyar guda ɗaya kuma yana nan bayan sake kunnawa.

| Maɓalli                | Tsoho   | Manufa                                                                                       |
| ---------------------- | ------- | -------------------------------------------------------------------------------------------- |
| `deduplicateThreshold` | `3`     | Ga injin gaba ɗaya: mafi ƙarancin layuka iri ɗaya a jere da za a dunƙule (iyaka 2–100)       |
| `enableGrouping`       | `false` | Zaɓin kunnawa: dunƙule jerin layuka masu kusan daidaito da ke biye da juna                   |
| `groupingThreshold`    | `3`     | Mafi ƙarancin adadin layuka makamanta a jere da ke jawo haɗawa rukuni                        |
| `stripCodeComments`    | `false` | Zaɓin kunnawa: cire sharhi daga tubalan lamba masu shinge (yana buƙatar `applyToCodeBlocks`) |
| `preserveDocstrings`   | `true`  | Lokacin cire sharhi, a bar tubalan JSDoc/`/** … */`                                          |

## API

| Hanya                              | Hanya ta HTTP | Manufa                                                      |
| ---------------------------------- | ------------- | ----------------------------------------------------------- |
| `/api/context/rtk/config`          | GET           | Karanta daidaitawar RTK                                     |
| `/api/context/rtk/config`          | PUT           | Sabunta daidaitawar RTK                                     |
| `/api/context/rtk/filters`         | GET           | Jera kundin matata da bayanan binciken lodawa               |
| `/api/context/rtk/import`          | POST          | Tabbatar ko shigar da fayilolin RTK TOML schema v1          |
| `/api/context/rtk/test`            | POST          | Samfoti na matsewar RTK don bayanan rubutu guda ɗaya        |
| `/api/context/rtk/raw-output/[id]` | GET           | Karanta ɗanyen fitarwa da aka ɓoye bayanansa kuma aka adana |
| `/api/compression/preview`         | POST          | Samfoti na kowane yanayin matsewa                           |

Bayanan gwajin RTK:

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

Bayanan samfurin matsewa:

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

Hanyoyin gudanarwa suna buƙatar izinin gudanar da dashboard ko manufar API-key da ta dace.

Bayanan tabbatar da RTK TOML:

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

Yi amfani da `"action": "install"` don shigar da fayil ɗin da aka tabbatar a matakin duniya. Ƙara `"overwrite": true` kawai
bayan dubawa da tabbatar da maye gurbin fayil ɗin duniya da yake akwai.

## Maido da Fitarwa Marar Sarrafawa

RTK yawanci yana dawo da rubutun da aka matse kawai. Don gyaran kurakurai, `rawOutputRetention` na iya riƙe
fitarwa marar sarrafawa da aka ɓoye bayananta:

| Ƙima       | Halayya                                                                       |
| ---------- | ----------------------------------------------------------------------------- |
| `never`    | Kada a riƙe fitarwa marar sarrafawa                                           |
| `failures` | A riƙe fitarwar da ake ganin wataƙila ta gaza kawai                           |
| `always`   | A riƙe kowace fitarwa marar sarrafawa ta RTK da aka matse, bayan ɓoye bayanai |

Ana rubuta fayilolin da aka riƙe a ƙarƙashin:

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

Ana ɓoye bayanan sirri kafin adanawa, ciki har da sanannun bearer tokens, API keys, Slack tokens,
AWS access keys, da ƙimomin salon sanyawa kamar `token=...`, `secret=...`, `password=...`. Nazari
yana adana id na manuni, girma, da metadata na hash kawai.

## Ƙofar Tabbatarwa

Ƙofar tabbatarwa mai mayar da hankali tana gudanar da ginannun gwaje-gwajen tacewa na inline ba tare da kiran umarnin waje ta shell ba:

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

Ƙofar RTK mafi faɗi ita ce:

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

Gudanar da ƙofar matsawa mai faɗi kafin fitarwa:

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

## Faɗaɗa RTK

1. Ƙara ko sabunta fayil ɗin JSON na mataci.
2. Haɗa aƙalla samfurin `tests[]` guda ɗaya da ke tabbatar da muhimmiyar halayyar.
3. Ƙara fixture a ƙarƙashin `tests/unit/compression/fixtures/rtk/` don sababbin rukunin umarni.
4. Ƙara ɗaukar gwajin gano umarni yayin gabatar da sabon nau'in fitarwa.
5. Gudanar da ƙofofin tabbatarwa da na RTK mai faɗi.
6. Idan matacin na cikin aikin ne kawai, yi commit na `.rtk/filters.json` sannan ka sabunta `.rtk/trust.json` bayan an yi bita kawai.

---

## Matakan Ƙarfi (v3.8.16+)

RTK yana goyon bayan **matakan ƙarfi 3** waɗanda ke yin daidaito tsakanin **tsananin matsawa** da **aminci**. Ana saita matakin ta `config.intensity` a cikin daidaitawar engine.

### Matakan 3

| Mataki             | Iyakar yankewa           | Rage tokens | Haɗari       | Ya fi dacewa da                                       |
| ------------------ | ------------------------ | ----------- | ------------ | ----------------------------------------------------- |
| `minimal`          | Layuka 24 a kowane sashe | ~20-40%     | Ƙarami sosai | Production mai mahallin da yake da matuƙar muhimmanci |
| `standard` (tsoho) | Layuka 24 a kowane sashe | ~50-70%     | Ƙarami       | Zaman rubuta lamba na yau da kullum                   |
| `aggressive`       | Layuka 16 a kowane sashe | ~70-90%     | Matsakaici   | Dogayen zama, mafi girman ragewa                      |

### Inda Yankewar Ke Faruwa

Iyakar yankewa tana shafar `lineFilter.ts`:

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

Ana kiyaye duka **farkon** da **ƙarshen** kowane sashe; ana cire abubuwan da ke tsakiya idan yankewa ta fara aiki.

### Abin da Ake Bari da Abin da Ake Yanke

| Abun ciki                            | minimal          | standard         | aggressive       |
| ------------------------------------ | ---------------- | ---------------- | ---------------- |
| Kurakurai / stack traces             | ✅ ana kiyayewa  | ✅ ana kiyayewa  | ✅ ana kiyayewa  |
| Gazawar gwaje-gwaje                  | ✅ ana kiyayewa  | ✅ ana kiyayewa  | ✅ ana kiyayewa  |
| Kurakuran build                      | ✅ ana kiyayewa  | ✅ ana kiyayewa  | ✅ ana kiyayewa  |
| Nasarar gwaje-gwaje (cikakke)        | ✅ ana kiyayewa  | 🟡 ana taƙaitawa | 🟡 ana taƙaitawa |
| Fitarwa ta yau da kullum (info logs) | 🟡 ana taƙaitawa | 🟡 ana taƙaitawa | ❌ ana cirewa    |
| Sandunan ci gaba                     | 🟡 ana taƙaitawa | ❌ ana cirewa    | ❌ ana cirewa    |
| Banner / fasahar ASCII               | 🟡 ana taƙaitawa | ❌ ana cirewa    | ❌ ana cirewa    |

### Zaɓar Ƙarfin da Ya Dace

```
                  Shin rasa mahalli zai zama bala'i?
                  │
      ┌───────────┼───────────┐
      │           │           │
     EH           A'A       BA A TABBATA BA
      │           │           │
      ▼           │           │
   minimal        │           │
      │           │           │
      │           ▼           ▼
      │      Yaya muhimmancin Fara gwada `standard`
      │      throughput yake? (yana aiki ga kashi 80%
      │           │          na lokuta)
      │      ┌────┴────┐
      │      │         │
      │    ƘASA      SAMA
      │      │         │
      │      ▼         ▼
      │   standard   aggressive
      │      │         │
      └──────┴─────────┘
```

### Daidaita Ƙarfi

**Ga kowane combo** (a cikin daidaitawar combo):

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

**Ta hanyar shirye-shirye**:

`rtkEngine` (`@omniroute/open-sse/services/compression/engines/rtk`) wani
`CompressionEngine` ne kuma ba shi da hanyar `updateConfig`. Sabunta daidaitawar engine
ta hanyar mataimakin registry maimakon haka:

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

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

### Tabbatar da Tasirin

Yi amfani da **Ƙofar Tabbatarwa** (duba ƙasa) don tabbatar da cewa matacinka yana da aminci a ƙarfin da ka zaɓa:

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

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

---

## Haɓaka Tace Na Musamman (v3.8.16+)

Kundin adireshi na `engines/rtk/filters/` yana ɗauke da **fayilolin JSON na matatu ginannu guda 49+**. Za ka iya ƙara naka don matse fitarwa daga kayan aiki na musamman waɗanda tsoffin matatun ba su rufe ba.

### Tsarin Tace (Zod)

```ts
{
  "id": "string",                      // Wajibi. Mai gano tace (kebab-case, misali, "python-traceback")
  "label": "string",                   // Wajibi. Sunan tace mai sauƙin karantawa
  "description": "string",             // Na zaɓi (tsoho: ""). Taƙaitaccen bayanin abin da tace ke yi
  "category": "git|test|build|shell|docker|package|infra|cloud|generic",
  "priority": number,                  // Na zaɓi (0-100, tsoho: 50). Jerin aiwatarwa (mafi girma = farko)
  "match": {
    "commands": ["string"],            // Sunayen umarni da za a daidaita (misali, "python", "pytest")
    "patterns": ["string"],            // Samfuran regex da za a daidaita da fitarwa
    "outputTypes": ["string"]          // Nau'ikan fitarwa da aka gano (misali, "test-failure")
  },
  "rules": {
    "stripAnsi": boolean,              // Na zaɓi (tsoho: false). Cire lambobin launin ANSI
    "replace": [                       // Dokokin nema-da-maye-gurbi (tsoho: [])
      { "pattern": "regex", "replacement": "..." }
    ],
    "matchOutput": [                   // Dakatar nan take idan samfur ya dace (tsoho: [])
      {
        "pattern": "regex",
        "message": "short summary",
        "unless": "regex"              // Tsallake idan wannan samfurin ya dace
      }
    ],
    "includePatterns": ["string"],     // Layukan da za a riƙe (samfuran regex, tsoho: [])
    "dropPatterns": ["string"],        // Layukan da za a cire (samfuran regex, tsoho: [])
    "collapsePatterns": ["string"],    // Layukan da za a taƙaita zuwa bayyanar guda ɗaya (tsoho: [])
    "deduplicate": boolean,            // Na zaɓi (tsoho: false). Cire layukan da suka maimaitu
    "truncateLineAt": number,          // Na zaɓi (tsoho: 0). Yanke layuka zuwa iyakar haruffa
    "maxLines": number,                // Na zaɓi (tsoho: 0). Ƙayyadadden iyaka ga jimillar layuka
    "headLines": number,               // Na zaɓi (tsoho: 20). Riƙe layuka N na farko daga fitarwar da ta dace
    "tailLines": number,               // Na zaɓi (tsoho: 20). Riƙe layuka N na ƙarshe daga fitarwar da ta dace
    "onEmpty": "string",               // Na zaɓi (tsoho: ""). Saƙon madadin idan an tace duk layuka
    "filterStderr": boolean            // Na zaɓi (tsoho: false). Haka kuma a tace fitarwar stderr
  },
  "preserve": {
    "errorPatterns": ["string"],       // Samfuran da dole ne a kiyaye koyaushe (tsoho: [])
    "summaryPatterns": ["string"]      // Samfuran layin taƙaitawa na ƙarshe (tsoho: [])
  },
  "tests": [                           // Gwaje-gwajen cikin layi don tabbatarwa (tsoho: [])
    {
      "name": "string",               // Wajibi. Sunan gwaji
      "input": "sample output",        // Wajibi. Samfurin rubutun shigarwa
      "expected": "expected output",   // Wajibi. Fitarwar da ake tsammani bayan matsawa
      "command": "optional command"    // Na zaɓi. Mahallin umarni
    }
  ]
}
```

### Misali: Tace Traceback na Python

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

### Loda Matatu Na Musamman

Sanya fayil ɗin a wurin da ake ganewa:

```
~/.omniroute/rtk/filters/my-filter.json     # Matakin mai amfani
<project>/.rtk/filters/my-filter.json      # Matakin aikin
```

Ana loda matatun kai tsaye lokacin farawa ta hanyar `loadRtkFilters()` a cikin `open-sse/services/compression/engines/rtk/filterLoader.ts`. Mai lodawar yana gano matatu daga:

- Kasidar ginannun matatu: `open-sse/services/compression/engines/rtk/filters/`
- Kundin adireshin mai amfani: `~/.omniroute/rtk/filters/`
- Kundin adireshin aikin: `<project>/.rtk/filters/`

Don loda matatu ta hanyar shirye-shirye:

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

// Zaɓuɓɓuka: customFiltersEnabled (loda matatun mai amfani/aiki, yana kunne ta tsohuwa),
// trustProjectFilters, refresh.
const filters = loadRtkFilters({ customFiltersEnabled: true });
```

### Tabbatarwa

Ana tabbatar da matatu bisa tsarin Zod lokacin lodawa. Tace mai tsari mara kyau ba zai samu loduwa ba kuma za a rubuta kuskure:

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

Don tabbatar da duk matatun da aka girka, kira `runRtkFilterTests()` wanda aka fitar daga `open-sse/services/compression/engines/rtk/verify.ts`.

### Mafi Kyawun Hanyoyin Aiki

1. **Koyaushe haɗa da `tests[]`** — suna tabbatar da cewa matatar ka tana aiki kuma suna hana sake bayyanar matsalolin da aka gyara
2. **Yi amfani da `matchOutput` don tsallake sauran matakai** — idan layi guda ya bayyana komai, maye gurbin dukkan toshe da shi
3. **Fi son `keep` maimakon `strip`** — ƙa’idojin “a kiyaye koyaushe” da aka bayyana sarai sun fi aminci fiye da “a cire koyaushe”
4. **Yi gwaji a dukkan matakan ƙarfi 3** — `minimal` bai kamata ya yi wani canji ba, yayin da `aggressive` ya kamata har yanzu ya kiyaye kurakurai
5. **Yi amfani da filin `unless`** — kare tsallake sauran matakai da sharadin “kada a kunna idan X yana nan”

---

## Maido da Fitowar Asali & Ƙofar Tabbatarwa

Lokacin da RTK ya matse fitowa sosai, za ka iya **maido da rubutun asali** domin gyara matsala, binciken tantancewa, ko sake kunnawa.

### Yadda Maido da Fitowar Asali ke Aiki

```
Fitowar asali (tokens 10K)
        │
        ▼
Matsewar RTK (tare da rawOutput.enabled=true)
        │
        ├─▶ Fitowar da aka matse (tokens 2K)  ──▶ zuwa LLM
        │
        └─▶ Fitowar asali (tokens 10K)        ──▶ an adana a DB
                                                     (an haɗa ta da request_id)
```

### Kunna Adana Fitowar Asali

**Ga kowace buƙata** (a cikin saitin combo):

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

**Tsoho**: `rawOutput.enabled: false` (yana rage amfani da ma'ajiyar bayanai).

### Kuɗin Ma'ajiya

| Ga kowace buƙata                 | Iyakar 1MB    | Iyakar 10MB    |
| -------------------------------- | ------------- | -------------- |
| Matsakaicin fitowar da aka matse | ~5KB          | ~5KB           |
| Fitowar asali da aka adana       | ~50-500KB     | ~500KB-5MB     |
| Tare da buƙatu 1000/rana         | 50-500MB/rana | 500MB-5GB/rana |

> **Shawara**: Ka kunna fitowar asali ne kawai yayin **zaman gyara matsala** ko **binciken tantancewa na samfurori**, ba a kullum ba.

### Maido da Asalin

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

const raw = readRtkRawOutput(pointerId); // pointerId daga ƙididdigar matsewa
if (raw) {
  console.log("Original output:", raw);
}
```

Ana mayar da `pointerId` a cikin `CompressionStats.rtkRawOutputPointers[]` bayan matsewa.
Duba `open-sse/services/compression/engines/rtk/rawOutput.ts:102` domin sigar aikin.

### Ƙofar Tabbatarwa

**Tabbatar da Tacewar RTK** (`open-sse/services/compression/engines/rtk/verify.ts`) yana tantance duk matatu ta amfani da `tests[]` nasu kuma yana tabbatar da cewa halayensu daidai ne a dukkan matakan ƙarfi guda 3.

**Kira `runRtkFilterTests()`** domin gudanar da tabbatarwa:

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

**Abubuwan da yake tantancewa**:

1. Kowace matata tana lodawa kuma tana wuce tantancewar schema
2. Kowace shigarwar `tests[]` tana samar da fitowar da ake tsammani
3. Ƙarfin `minimal` ba ya yin wani canji (yana kiyaye asali, yana amfani da matatun tsari kawai)
4. Ƙarfin `aggressive` yana kiyaye kurakurai, gazawar gwaje-gwaje, da bayanan sawun stack
5. Fitowar da aka matse ba ta taɓa fi girman shigarwar asali ba

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

- **Kafin haɗa canjin matata** — koyaushe ka tabbatar gwaje-gwajen sun yi nasara
- **Bayan sabunta engine na RTK** — mai yiwuwa schema ya canza
- **Lokaci-lokaci yayin sa ido** — yana kariya daga karkacewar kayan gwaji
- **Lokacin ƙara sabon dangin kayan aiki/umarni** — yana tabbatar da cewa sabuwar matatar tana aiki

---

## Duba Kuma

- [COMPRESSION_GUIDE.md](./COMPRESSION_GUIDE.md) — Cikakken bayani kan tsarin matakan matsewa
- [COMPRESSION_ENGINES.md](./COMPRESSION_ENGINES.md) — Rijistar injina da injinan da aka haɗa a ciki
- [EXTENDING_COMPRESSION.md](./EXTENDING_COMPRESSION.md) — Injina na musamman, fakitin harsuna, tsarin matakai masu jere
- Tushen lamba: `open-sse/services/compression/engines/rtk/` (fayiloli 63, ~70KB)