# RTK Compression (فارسی)

🌐 **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) · 🇫🇮 [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) · 🇰🇪 [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)

---

فشردهسازی RTK موتور فشردهسازی آگاه از فرمان OmniRoute برای خروجی ترمینال و ابزارها است. این موتور
برای نشستهای عامل کدنویسی طراحی شده است؛ نشستهایی که در آنها بیشتر رشد زمینه ناشی از گزارشهای تست، خروجی ساخت،
نویز مدیر بسته، رونوشتهای پوسته، خروجی Docker، خروجی git و ردگیریهای پشته است.

RTK میتواند مستقیماً با `defaultMode: "rtk"` یا بهعنوان نخستین مرحله در یک خط لوله پشتهای اجرا شود که معمولاً به این صورت است:

```txt
rtk -> caveman
```

این ترتیب ابتدا خروجی ماشینی پرنویز را فشرده میکند، سپس به Caveman اجازه میدهد نثر باقیمانده را خلاصه کند.

RTK بالادستی صرفهجویی `60-90%` در خروجی فرمان را گزارش میکند. نشست نمونه در README آن از
`~118,000` توکن استاندارد به `~23,900` توکن RTK کاهش مییابد که برابر با `79.7%` صرفهجویی (`~80%`) است. OmniRoute از
این میانگین بالادستی برای محاسبه صرفهجویی پشتهای همراه با فشردهسازی ورودی Caveman استفاده میکند:

```txt
میانگین RTK:        80% صرفهجویی
ورودی Caveman:      46% صرفهجویی
پشتهای:            1 - (1 - 0.80) * (1 - 0.46) = 89.2% صرفهجویی
بازه:               1 - (1 - 0.60..0.90) * (1 - 0.46) = 78.4-94.6%
```

## چه چیزی فشرده میشود

کاتالوگ داخلی در حال حاضر ۵۶ فیلتر را در این دستهبندیها ارائه میدهد:

| دستهبندی  | مثالها                                                        |
| --------- | ------------------------------------------------------------- |
| `git`     | `git status`، `git branch`، `git diff`، `git log`             |
| `test`    | Vitest، Jest، Pytest، PHPUnit، Playwright، Go، تستهای Cargo   |
| `build`   | TypeScript، ESLint، Biome، Prettier، Vite، Webpack، Turbo، Nx |
| `package` | `npm install`، `npm audit`، `pip`، `uv sync`، Poetry، Bundler |
| `shell`   | `ls`، `find`، `grep`، لاگهای عمومی شل                         |
| `docker`  | `docker ps`، لاگهای Docker                                    |
| `infra`   | Terraform، OpenTofu، `systemctl status`                       |
| `generic` | خروجی JSON، stack traceها، جایگزین خروجی عمومی                |

آشکارساز موجود در `open-sse/services/compression/engines/rtk/commandDetector.ts` خروجی را پیش از انتخاب فیلتر دستهبندی میکند. فیلترها همچنین میتوانند زمانی که کلاس دستور بهتنهایی کافی نیست، بر اساس الگوی دستور یا regex خروجی تطبیق داده شوند.

## تفکیک فیلتر

RTK فیلترها را به ترتیب زیر بارگذاری میکند:

1. فیلترهای پروژه از `.rtk/filters.toml` و `.rtk/filters.json`، فقط در صورت مورداعتماد بودن.
2. فیلترهای سراسری از `DATA_DIR/rtk/filters.toml` و `DATA_DIR/rtk/filters.json`.
3. فیلترهای داخلی از `open-sse/services/compression/engines/rtk/filters/`.

در یک دامنه یکسان، فیلترهای schema v1 مربوط به RTK TOML بر فیلترهای JSON مربوط به OmniRoute اولویت دارند. عبارتهای TOML
`match_command` پیش از تطبیق نوع فرمان بررسی میشوند تا یک فیلتر واردشده مختص فرمان بتواند فیلتر گستردهتری را در همان دامنه
بازنویسی کند. دامنه پروژه، صرفنظر از قالب فایل، همچنان بر دامنه سراسری اولویت دارد.

فیلترهای پروژه عمداً به اعتماد مشروط شدهاند، زیرا فیلترهای عبارت منظم میتوانند نحوه نمایش خروجی ابزار
به عاملها را تغییر دهند. فایل فیلتر پروژه زمانی پذیرفته میشود که یکی از شرایط زیر برقرار باشد:

- `rtkConfig.trustProjectFilters` برابر با `true` باشد.
- `OMNIROUTE_RTK_TRUST_PROJECT_FILTERS=1` تنظیم شده باشد.
- `.rtk/trust.json` شامل هش SHA-256 منطبق با فایل فیلتر پروژه باشد.

نمونه فایل اعتماد:

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

هشها مجزا هستند: `filtersSha256` به `.rtk/filters.json` اعتماد میکند، در حالی که `filtersTomlSha256`
به `.rtk/filters.toml` اعتماد میکند. ویرایش هر یک از فایلها فقط مدخل اعتماد مربوط به همان فایل را نامعتبر میکند. فایلهای سراسری
توسط مدیر نصب میشوند و از رفتار اعتماد موجود برای فیلترهای سراسری استفاده میکنند.

فیلترهای سفارشی میتوانند یک شیء فیلتر یا آرایهای از اشیای فیلتر باشند. فیلترهای سفارشی نامعتبر
نادیده گرفته میشوند و توسط بخش تشخیص `/api/context/rtk/filters` گزارش میشوند. فیلترهای داخلی نامعتبر بلافاصله باعث شکست میشوند.

## سازگاری با طرحواره RTK TOML نسخه 1

OmniRoute میتواند فایلهای فیلتر اعلانی را با استفاده از طرحواره RTK TOML نسخه 1 تجزیه، اعتبارسنجی، آزمایش و نصب کند.
فیلدهای پشتیبانیشده عبارتاند از `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` و تستهای درونخطی `[[tests.<filter>]]`.
فیلدهای ناشناخته، عبارتهای منظم نامعتبر یا ناامن، استفاده همزمان از قواعد حذف/نگهداری، فایلهای بزرگتر از
1 MiB و ارجاع به فیلترهای ناشناخته رد میشوند. فایلی که تستهای درونخطی آن ناموفق باشند، برای بررسی
قابل اعتبارسنجی است، اما نمیتوان آن را نصب یا بارگذاری کرد. شکست در بارگذاری فایل سفارشی همچنان
بهصورت fail-open مدیریت میشود: فایل نامعتبر نادیده گرفته میشود و سایر فیلترها به کار خود ادامه میدهند.

OmniRoute خروجی ابزار را پس از آن دریافت میکند که کلاینت آن را ثبت کرده است؛ بنابراین `filter_stderr = true`
نمیتواند نحوه ثبت خروجی فرایند را تغییر دهد. این فیلد بهعنوان یک عملیات بیاثر پذیرفته میشود و اعتبارسنجی یک هشدار برمیگرداند.
این قابلیت عمداً با عنوان **سازگاری با طرحواره RTK TOML نسخه 1** توصیف میشود، نه سازگاری کامل
با فایل اجرایی RTK، هوکهای پوسته، پیادهسازیهای فرمان Rust یا چیدمان trust-store آن.

نمای پیشرفته RTK در داشبورد، TOML جایگذاریشده یا بارگذاریشده را میپذیرد. اعتبارسنجی فقط خواندنی است.
نصب، فایل `DATA_DIR/rtk/filters.toml` را بهصورت اتمی و با مجوزهای محدودکننده مینویسد و
کاتالوگ فعال فیلترها را بدون راهاندازی مجدد تازهسازی میکند. جایگزینی فایل موجود به تأیید صریح `overwrite`
نیاز دارد و ابتدا `DATA_DIR/rtk/filters.toml.bak` را ایجاد میکند.

## DSL فیلتر

فیلترها از طرحواره JSON شرحدادهشده در [قالب قواعد فشردهسازی](./COMPRESSION_RULES_FORMAT.md) استفاده میکنند.
محیط اجرا این مراحل را بهترتیب اعمال میکند:

```txt
stripAnsi -> filterStderr -> replace -> matchOutput -> حذف/شاملکردن خطوط
  -> truncateLineAt -> head/tail/maxLines -> onEmpty
```

فیلدهای مهم:

| فیلد                         | هدف                                                                  |
| ---------------------------- | -------------------------------------------------------------------- |
| `rules.stripAnsi`            | حذف توالیهای رنگ/کنترل ترمینال پیش از تطبیق                          |
| `rules.filterStderr`         | نرمالسازی پیشوندهای رایج stderr پیش از تطبیق/فیلترکردن               |
| `rules.replace`              | اعمال جایگزینیهای مرتبشده مبتنی بر عبارت منظم                        |
| `rules.matchOutput`          | بازگرداندن خلاصهای فشرده وقتی خروجی با یک وضعیت شناختهشده تطبیق دارد |
| `rules.matchOutput[].unless` | صرفنظر از میانبُر هنگام وجود الگوی خطا/شکست                          |
| `rules.dropPatterns`         | حذف خطوط مزاحم                                                       |
| `rules.includePatterns`      | ترجیح خطوط قابلاقدام                                                 |
| `rules.collapsePatterns`     | ادغام خطوط تکراری منطبق                                              |
| `rules.deduplicate`          | فعالسازی اختیاری برای هر فیلتر: ادغام خطوط تکراری متوالی             |
| `rules.truncateLineAt`       | کوتاهسازی ایمن از نظر Unicode برای هر خط                             |
| `rules.onEmpty`              | پیام جایگزین در صورت فیلترشدن همه خطوط                               |
| `tests[]`                    | نمونههای درونخطی مورد استفاده در دروازه راستیآزمایی                  |

انتظار میرود فیلترهای داخلی شامل نمونههای درونخطی `tests[]` باشند. فیلترهای سفارشی نیز باید
آنها را شامل شوند، بهویژه هنگامی که میان چند پروژه به اشتراک گذاشته میشوند.

## حذف خطوط تکراری (دو لایه)

RTK خطوط تکراری را در دو لایهٔ مستقل ادغام میکند:

1. **گزینهٔ `deduplicate` برای هر فیلتر (اختیاری، پیشفرض `false`).** یک فیلتر میتواند
   `rules.deduplicate: true` را تنظیم کند تا خطوط تکراریِ متوالی را _در خروجی منطبقشدهٔ همان فیلتر_
   و پیش از کوتاهسازی ادغام کند. این عملیات درون `lineFilter.ts` اجرا میشود. برای فیلترهای قدیمی،
   زمانی که فیلتر `collapsePatterns` را تعریف کرده باشد، این گزینه بهطور خودکار فعال میشود.
   شِما: `deduplicate: z.boolean().default(false)` در
   `open-sse/services/compression/engines/rtk/filterSchema.ts`.
2. **گزینهٔ سراسری موتور `deduplicateThreshold` (پیشفرض `3`).** پس از اجرای همهٔ فیلترها،
   موتور هر دنباله از خطوط متوالیِ یکسان با طول `>= deduplicateThreshold` را در کل نتیجه ادغام
   میکند (`deduplicateRepeatedLines` که در `engines/rtk/index.ts` اعمال میشود). هنگام
   نرمالسازی، مقدار آن به بازهٔ 2 تا 100 محدود میشود.

مرحلهٔ مربوط به هر فیلتر ابتدا (درون فیلتر) اجرا میشود و مرحلهٔ سراسری موتور در پایان (روی خروجی
بههمپیوسته) اجرا میشود؛ بنابراین این دو بدون شمارش مضاعف با یکدیگر ترکیب میشوند.

## گروهبندی خطوط (`enableGrouping`)

وقتی `rtkConfig.enableGrouping` برابر با `true` باشد (پیشفرض `false`)، RTK یک مرحلهٔ اضافی
`groupSimilarLines` را روی نتیجهٔ پس از حذف تکرار اجرا میکند که دنبالههایی از خطوط متوالیِ
_تقریباً معادل_ (نه یکسان در سطح بایت) را ادغام میکند. `rtkConfig.groupingThreshold` (پیشفرض
`3`) حداقل طول دنبالهای است که گروهبندی را فعال میکند. این گزینه همتای ساختاری
`deduplicateThreshold` است: حذف تکرار، موارد کاملاً یکسان را مدیریت میکند و گروهبندی، «شکل یکسان
با تفاوتهای جزئی» را مدیریت میکند. هر دو پرچم بخشی از JSON مربوط به `rtkConfig` هستند که در جدول
`key_value` ذخیره میشود (بخش پیکربندی در بالا را ببینید)، بنابراین این تنظیم پس از راهاندازیهای
مجدد نیز حفظ میشود.

## حذف توضیحات کد (`stripCodeComments` / `preserveDocstrings`)

وقتی `rtkConfig.applyToCodeBlocks` فعال باشد، RTK میتواند توضیحات را نیز از بلوکهای کد حصاردار
حذف کند:

- `stripCodeComments` (پیشفرض `false`) — اختیاری است. وقتی `true` باشد، RTK توضیحات را از
  بلوکهای حصاردار JavaScript و TypeScript حذف میکند. از نظر تاریخی، این پرچم خوانده میشد اما
  هرگز اعمال نمیشد؛ بنابراین مقدار پیشفرض همچنان «حفظ کردن» است تا از ایجاد تغییری بیسروصدا در
  محیط عملیاتی جلوگیری شود.
- `preserveDocstrings` (پیشفرض `true`) — هنگام حذف توضیحات، توضیحات بلوکی JSDoc/`/** … */` حفظ
  میشوند (زیرا حاوی مستندات API هستند که ارزششان از بایتهایی که مصرف میکنند بیشتر است). برای
  حذف آنها نیز، این گزینه را روی `false` تنظیم کنید.

حذف توضیحات در `open-sse/services/compression/engines/rtk/codeStripper.ts` پیادهسازی شده است. این
پیادهسازی از **تجزیهگر TypeScript** (نه یک عبارت منظم) استفاده میکند تا رشتهها، قالبها و
لیترالهای عبارت منظم هرگز بهاشتباه توضیح در نظر گرفته نشوند؛ همچنین در صورت شناسایی JSX، عملیات
را کاملاً متوقف میکند (تا توضیحات موجود در محفظههای عبارت JSX هرگز خراب نشوند). در حال حاضر،
حذف توضیحات فقط برای **JavaScript و TypeScript** اعمال میشود — سایر زبانهای مجموعهٔ
`CodeLanguage` این حذفکننده (Python، Rust، Go، Ruby و Java) خطوط خالی و فاصلههای سفید را ادغام
میکنند، اما توضیحات را حذف نمیکنند. اجرای بلوک حذفشده با `rtk:code-strip` در `rulesApplied`
برچسبگذاری میشود.

> **نکته — کدگذاری GCF / جدولی، موتوری جداگانه است.** RTK شامل کدگذار JSON جدولی/ستونی «GCF»
> (Graph Compact Format) **نیست**. آن کدگذار — که جایگزین کدگذار قدیمیتر `omni-tabular` شده است —
> در موتور **headroom** قرار دارد
> (`open-sse/services/compression/engines/headroom/`، همراه با کُدک همراهشده در
> `headroom/gcf/`). این کدگذار ارتباطی با خط لولهٔ فیلتر RTK که در اینجا مستند شده است ندارد.

## پیکربندی

تنظیمات سراسری از طریق `/api/settings/compression` در دسترس هستند. تنظیمات اختصاصی RTK نیز از طریق
`/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` و `disabledFilters` از شناسههای فیلتر استفاده میکنند؛ برای مثال `test-vitest` یا `git-diff`.

ساختار کامل `rtkConfig` توسط `RtkConfig` / `DEFAULT_RTK_CONFIG` در
`open-sse/services/compression/types.ts` تعریف شده است. کل شیء بهصورت یک مقدار JSON واحد در
جدول `key_value` پایگاه داده SQLite، تحت `namespace = "compression"` و `key = "rtkConfig"`
(`src/lib/db/compression.ts`) ذخیره میشود و هنگام خواندن توسط `normalizeRtkConfig` نرمالسازی میشود. بنابراین تمام فیلدهای زیر
— از جمله `enableGrouping`، `groupingThreshold`، `stripCodeComments` و `preserveDocstrings` —
از همان محل ذخیرهسازی خوانده و در آن نوشته میشوند و پس از راهاندازی مجدد نیز باقی میمانند.

| کلید                   | پیشفرض  | هدف                                                                          |
| ---------------------- | ------- | ---------------------------------------------------------------------------- |
| `deduplicateThreshold` | `3`     | در سراسر موتور: حداقل تعداد خطوط یکسانِ متوالی برای ادغام (محدودهٔ ۲ تا ۱۰۰) |
| `enableGrouping`       | `false` | اختیاری: ادغام دنبالههایی از خطوط متوالیِ تقریباً معادل                      |
| `groupingThreshold`    | `3`     | حداقل تعداد خطوط مشابهِ متوالی که گروهبندی را فعال میکند                     |
| `stripCodeComments`    | `false` | اختیاری: حذف توضیحات از بلوکهای کد محصورشده (نیازمند `applyToCodeBlocks`)    |
| `preserveDocstrings`   | `true`  | هنگام حذف توضیحات، بلوکهای JSDoc/`/** … */` را حفظ میکند                     |

## API

| مسیر                               | روش  | هدف                                                          |
| ---------------------------------- | ---- | ------------------------------------------------------------ |
| `/api/context/rtk/config`          | GET  | خواندن پیکربندی RTK                                          |
| `/api/context/rtk/config`          | PUT  | بهروزرسانی پیکربندی RTK                                      |
| `/api/context/rtk/filters`         | GET  | فهرستکردن کاتالوگ فیلترها و اطلاعات تشخیصی بارگذاری          |
| `/api/context/rtk/import`          | POST | اعتبارسنجی یا نصب فایلهای طرحوارهٔ TOML نسخهٔ ۱ مربوط به RTK |
| `/api/context/rtk/test`            | POST | پیشنمایش فشردهسازی RTK برای یک محتوای متنی                   |
| `/api/context/rtk/raw-output/[id]` | GET  | خواندن خروجی خامِ نگهداریشده و ویرایششده                     |
| `/api/compression/preview`         | POST | پیشنمایش هر حالت فشردهسازی                                   |

محتوای درخواست آزمایش RTK:

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

محتوای درخواست پیشنمایش فشردهسازی:

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

مسیرهای مدیریتی به احراز هویت مدیریت داشبورد یا خطمشی منطبق با کلید API نیاز دارند.

محتوای درخواست اعتبارسنجی TOML مربوط به RTK:

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

برای نصب سراسری فایل اعتبارسنجیشده از `"action": "install"` استفاده کنید. فقط
پس از بررسی و تأیید جایگزینی فایل سراسری موجود، `"overwrite": true` را اضافه کنید.

## بازیابی خروجی خام

RTK معمولاً فقط متن فشردهشده را برمیگرداند. برای اشکالزدایی، `rawOutputRetention` میتواند خروجی خامِ سانسورشده را نگه دارد:

| مقدار      | رفتار                                                       |
| ---------- | ----------------------------------------------------------- |
| `never`    | خروجی خام را نگه نمیدارد                                    |
| `failures` | فقط خروجیهایی را نگه میدارد که احتمالاً مربوط به شکست هستند |
| `always`   | تمام خروجیهای خام فشردهشده RTK را پس از سانسور نگه میدارد   |

فایلهای نگهداریشده در مسیر زیر نوشته میشوند:

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

اطلاعات محرمانه پیش از ذخیرهسازی سانسور میشوند؛ از جمله توکنهای bearer متداول، کلیدهای API، توکنهای Slack،
کلیدهای دسترسی AWS و مقادیر انتسابی بهشکل `token=...`، `secret=...` و `password=...`. سامانه تحلیل
فقط شناسه اشارهگر، اندازه و فراداده هش را ذخیره میکند.

## دروازه تأیید

دروازه تأیید متمرکز، آزمونهای درونخطی داخلی فیلتر را بدون فراخوانی فرمانهای خارجی پوسته اجرا میکند:

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

دروازه گستردهتر RTK بهصورت زیر است:

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

پیش از انتشار، دروازه گسترده فشردهسازی را اجرا کنید:

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

## گسترش RTK

1. یک فایل JSON فیلتر اضافه یا بهروزرسانی کنید.
2. دستکم یک نمونه `tests[]` بگنجانید که رفتار مهم را اثبات کند.
3. برای خانوادههای فرمان جدید، یک fixture در `tests/unit/compression/fixtures/rtk/` اضافه کنید.
4. هنگام معرفی یک کلاس خروجی جدید، پوشش تشخیص فرمان را اضافه کنید.
5. دروازههای تأیید و گسترده RTK را اجرا کنید.
6. اگر فیلتر مختص پروژه است، `.rtk/filters.json` را commit کنید و `.rtk/trust.json` را فقط پس از بازبینی بهروزرسانی کنید.

---

## سطوح شدت (v3.8.16+)

RTK از **۳ سطح شدت** پشتیبانی میکند که بین **تهاجمی بودن فشردهسازی** و **ایمنی** تعادل برقرار میکنند. این سطح از طریق `config.intensity` در پیکربندی موتور تنظیم میشود.

### ۳ سطح

| سطح                 | آستانه کوتاهسازی | صرفهجویی توکن | ریسک     | مناسب برای                       |
| ------------------- | ---------------- | ------------- | -------- | -------------------------------- |
| `minimal`           | 24 خط در هر بخش  | ~20-40%       | بسیار کم | محیط production با context حیاتی |
| `standard` (پیشفرض) | 24 خط در هر بخش  | ~50-70%       | کم       | جلسات کدنویسی روزانه             |
| `aggressive`        | 16 خط در هر بخش  | ~70-90%       | متوسط    | جلسات طولانی، حداکثر صرفهجویی    |

### کوتاهسازی کجا اتفاق میافتد

آستانه کوتاهسازی روی `lineFilter.ts` اثر میگذارد:

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

هم **ابتدا** و هم **انتهای** هر بخش حفظ میشود؛ هنگامی که کوتاهسازی فعال شود، محتوای میانی حذف میشود.

### چه چیزی باقی میماند و چه چیزی حذف میشود

| محتوا                    | minimal        | standard       | aggressive     |
| ------------------------ | -------------- | -------------- | -------------- |
| خطاها / stack traceها    | ✅ حفظ میشود   | ✅ حفظ میشود   | ✅ حفظ میشود   |
| تستهای ناموفق            | ✅ حفظ میشود   | ✅ حفظ میشود   | ✅ حفظ میشود   |
| خطاهای build             | ✅ حفظ میشود   | ✅ حفظ میشود   | ✅ حفظ میشود   |
| تستهای موفق (پرجزئیات)   | ✅ حفظ میشود   | 🟡 خلاصه میشود | 🟡 خلاصه میشود |
| خروجی عادی (لاگهای info) | 🟡 خلاصه میشود | 🟡 خلاصه میشود | ❌ حذف میشود   |
| نوارهای پیشرفت           | 🟡 خلاصه میشود | ❌ حذف میشود   | ❌ حذف میشود   |
| بنر / ASCII art          | 🟡 خلاصه میشود | ❌ حذف میشود   | ❌ حذف میشود   |

### انتخاب شدت مناسب

```
                  آیا از دست دادن context فاجعهبار است؟
                  │
      ┌───────────┼───────────┐
      │           │           │
     بله        خیر      مطمئن نیستم
      │           │           │
      ▼           │           │
   minimal        │           │
      │           │           │
      │           ▼           ▼
      │     throughput       ابتدا `standard` را
      │    چقدر حیاتی است؟    امتحان کنید
      │           │          (در 80% موارد
      │      ┌────┴────┐      کار میکند)
      │      │         │
      │     کم       زیاد
      │      │         │
      │      ▼         ▼
      │   standard   aggressive
      │      │         │
      └──────┴─────────┘
```

### پیکربندی شدت

**برای هر combo** (در پیکربندی combo):

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

**بهصورت برنامهای**:

`rtkEngine` (`@omniroute/open-sse/services/compression/engines/rtk`) یک
`CompressionEngine` است و متد `updateConfig` ندارد. بهجای آن، پیکربندی موتور را
از طریق helper مربوط به registry بهروزرسانی کنید:

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

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

### بررسی اثر

از **Verify Gate** (به بخش بعد مراجعه کنید) استفاده کنید تا تأیید کنید فیلتر شما در شدت انتخابشده ایمن است:

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

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

---

## توسعهٔ فیلتر سفارشی (v3.8.16+)

دایرکتوری `engines/rtk/filters/` شامل **بیش از 49 فایل JSON فیلتر داخلی** است. میتوانید فیلترهای خود را برای فشردهسازی خروجی ابزارهای سفارشی که تحت پوشش پیشفرضها نیستند، اضافه کنید.

### شِمای فیلتر (Zod)

```ts
{
  "id": "string",                      // الزامی. شناسهٔ فیلتر (با قالب kebab-case، برای مثال "python-traceback")
  "label": "string",                   // الزامی. نام خوانای فیلتر
  "description": "string",             // اختیاری (پیشفرض: ""). توضیحی کوتاه دربارهٔ کاری که فیلتر انجام میدهد
  "category": "git|test|build|shell|docker|package|infra|cloud|generic",
  "priority": number,                  // اختیاری (0-100، پیشفرض: 50). ترتیب اجرا (مقدار بالاتر = اجرای زودتر)
  "match": {
    "commands": ["string"],            // نام فرمانهایی که باید مطابقت داده شوند (برای مثال "python"، "pytest")
    "patterns": ["string"],            // الگوهای Regex برای مطابقت با خروجی
    "outputTypes": ["string"]          // کلاسهای خروجی شناساییشده (برای مثال "test-failure")
  },
  "rules": {
    "stripAnsi": boolean,              // اختیاری (پیشفرض: false). حذف کدهای رنگ ANSI
    "replace": [                       // قواعد جستوجو و جایگزینی (پیشفرض: [])
      { "pattern": "regex", "replacement": "..." }
    ],
    "matchOutput": [                   // توقف زودهنگام هنگام مطابقت الگو (پیشفرض: [])
      {
        "pattern": "regex",
        "message": "short summary",
        "unless": "regex"              // اگر این الگو مطابقت داشت، رد شود
      }
    ],
    "includePatterns": ["string"],     // خطوطی که باید حفظ شوند (الگوهای Regex، پیشفرض: [])
    "dropPatterns": ["string"],        // خطوطی که باید حذف شوند (الگوهای Regex، پیشفرض: [])
    "collapsePatterns": ["string"],    // خطوطی که باید به یک رخداد واحد فروکاسته شوند (پیشفرض: [])
    "deduplicate": boolean,            // اختیاری (پیشفرض: false). حذف خطوط تکراری
    "truncateLineAt": number,          // اختیاری (پیشفرض: 0). کوتاهسازی خطوط تا حداکثر تعداد نویسه
    "maxLines": number,                // اختیاری (پیشفرض: 0). سقف قطعی تعداد کل خطوط
    "headLines": number,               // اختیاری (پیشفرض: 20). حفظ N خط نخست خروجی منطبق
    "tailLines": number,               // اختیاری (پیشفرض: 20). حفظ N خط پایانی خروجی منطبق
    "onEmpty": "string",               // اختیاری (پیشفرض: ""). پیام جایگزین در صورت فیلتر شدن همهٔ خطوط
    "filterStderr": boolean            // اختیاری (پیشفرض: false). فیلتر کردن خروجی stderr نیز
  },
  "preserve": {
    "errorPatterns": ["string"],       // الگوهایی که همیشه باید حفظ شوند (پیشفرض: [])
    "summaryPatterns": ["string"]      // الگوهای خط خلاصهٔ نهایی (پیشفرض: [])
  },
  "tests": [                           // آزمونهای درونخطی برای راستیآزمایی (پیشفرض: [])
    {
      "name": "string",               // الزامی. نام آزمون
      "input": "sample output",        // الزامی. متن ورودی نمونه
      "expected": "expected output",   // الزامی. خروجی فشردهشدهٔ مورد انتظار
      "command": "optional command"    // اختیاری. زمینهٔ فرمان
    }
  ]
}
```

### مثال: فیلتر 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"
    }
  ]
}
```

### بارگذاری فیلترهای سفارشی

فایل را در یکی از مکانهای شناختهشده قرار دهید:

```
~/.omniroute/rtk/filters/my-filter.json     # سطح کاربر
<project>/.rtk/filters/my-filter.json      # سطح پروژه
```

فیلترها هنگام راهاندازی، بهطور خودکار از طریق `loadRtkFilters()` در `open-sse/services/compression/engines/rtk/filterLoader.ts` بارگذاری میشوند. بارگذار، فیلترها را از مکانهای زیر پیدا میکند:

- کاتالوگ داخلی: `open-sse/services/compression/engines/rtk/filters/`
- دایرکتوری کاربر: `~/.omniroute/rtk/filters/`
- دایرکتوری پروژه: `<project>/.rtk/filters/`

برای بارگذاری برنامهنویسیشدهٔ فیلترها:

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

// گزینهها: customFiltersEnabled (بارگذاری فیلترهای کاربر/پروژه، بهصورت پیشفرض فعال)،
// trustProjectFilters، refresh.
const filters = loadRtkFilters({ customFiltersEnabled: true });
```

### اعتبارسنجی

فیلترها هنگام بارگذاری بر اساس شِمای Zod اعتبارسنجی میشوند. فیلتری با ساختار نامعتبر بارگذاری نمیشود و یک خطا ثبت میکند:

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

برای اعتبارسنجی همهٔ فیلترهای نصبشده، `runRtkFilterTests()` را فراخوانی کنید که از `open-sse/services/compression/engines/rtk/verify.ts` صادر میشود.

### بهترین شیوهها

1. **همیشه `tests[]` را لحاظ کنید** — آنها اثبات میکنند که فیلتر شما کار میکند و از پسرفتها جلوگیری میکنند
2. **برای خروج زودهنگام از `matchOutput` استفاده کنید** — اگر یک خط بهتنهایی گویای همهچیز است، کل بلوک را جایگزین کنید
3. **`keep` را به `strip` ترجیح دهید** — قواعد صریح «همیشه حفظ شود» از «همیشه حذف شود» ایمنتر هستند
4. **در هر ۳ سطح شدت آزمایش کنید** — `minimal` باید هیچ تغییری ایجاد نکند و `aggressive` همچنان باید خطاها را حفظ کند
5. **از فیلد `unless` استفاده کنید** — با شرط «اگر X وجود داشت، فعال نشود» از خروجهای زودهنگام محافظت کنید

---

## بازیابی خروجی خام و دروازهٔ تأیید

هنگامی که RTK خروجی را بهشدت فشرده میکند، میتوانید برای اشکالزدایی، ممیزی یا بازپخش، **متن اصلی را بازیابی کنید**.

### نحوهٔ عملکرد بازیابی خروجی خام

```
خروجی اصلی (10K توکن)
        │
        ▼
فشردهسازی RTK (با rawOutput.enabled=true)
        │
        ├─▶ خروجی فشردهشده (2K توکن)  ──▶ به LLM
        │
        └─▶ خروجی اصلی (10K توکن)       ──▶ ذخیرهشده در DB
                                                  (مرتبط از طریق request_id)
```

### فعالسازی ذخیرهسازی خروجی خام

**برای هر درخواست** (در پیکربندی ترکیبی):

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

**پیشفرض**: `rawOutput.enabled: false` (باعث صرفهجویی در فضای ذخیرهسازی میشود).

### هزینهٔ ذخیرهسازی

| بهازای هر درخواست      | سقف 1MB      | سقف 10MB      |
| ---------------------- | ------------ | ------------- |
| میانگین خروجی فشردهشده | ~5KB         | ~5KB          |
| خروجی خام ذخیرهشده     | ~50-500KB    | ~500KB-5MB    |
| با 1000 درخواست در روز | 50-500MB/day | 500MB-5GB/day |

> **توصیه**: خروجی خام را فقط برای **جلسات اشکالزدایی** یا **ممیزی نمونهبرداریشده** فعال کنید، نه بهصورت دائمی.

### بازیابی نسخهٔ اصلی

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

const raw = readRtkRawOutput(pointerId); // pointerId از آمار فشردهسازی
if (raw) {
  console.log("Original output:", raw);
}
```

مقدار `pointerId` پس از فشردهسازی در `CompressionStats.rtkRawOutputPointers[]` بازگردانده میشود.
برای مشاهدهٔ امضای تابع، به `open-sse/services/compression/engines/rtk/rawOutput.ts:102` مراجعه کنید.

### دروازهٔ تأیید

**تأیید فیلتر RTK** (`open-sse/services/compression/engines/rtk/verify.ts`) تمام فیلترها را در برابر `tests[]` آنها اعتبارسنجی میکند و از صحت رفتار در هر 3 سطح شدت اطمینان مییابد.

برای اجرای تأیید، **تابع `runRtkFilterTests()` را فراخوانی کنید**:

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

**مواردی که اعتبارسنجی میکند**:

1. هر فیلتر بارگذاری میشود و اعتبارسنجی طرحواره را با موفقیت پشت سر میگذارد
2. هر ورودی `tests[]` خروجی مورد انتظار را تولید میکند
3. شدت `minimal` هیچ تغییری ایجاد نمیکند (نسخهٔ اصلی را حفظ میکند و فقط فیلترهای ساختاری را اعمال میکند)
4. شدت `aggressive` خطاها، شکستهای آزمون و ردگیریهای پشته را حفظ میکند
5. خروجی فشردهشده هرگز از ورودی اصلی بزرگتر نیست

- منبع: `open-sse/services/compression/engines/rtk/` (63 فایل، ~70KB)

- **پیش از ادغام تغییر یک فیلتر** — همیشه از موفقیت آزمونها اطمینان حاصل کنید
- **پس از ارتقای موتور RTK** — ممکن است طرحواره تغییر کرده باشد
- **بهصورت دورهای در پایش** — از تغییر ناخواسته در فیکسچرهای آزمون جلوگیری میکند
- **هنگام افزودن یک خانوادهٔ ابزار/فرمان جدید** — اثبات میکند که فیلتر جدید کار میکند

---

## همچنین ببینید

- [COMPRESSION_GUIDE.md](./COMPRESSION_GUIDE.md) — نمای کلی خط لولهٔ فشردهسازی
- [COMPRESSION_ENGINES.md](./COMPRESSION_ENGINES.md) — رجیستری موتور و موتورهای داخلی
- [EXTENDING_COMPRESSION.md](./EXTENDING_COMPRESSION.md) — موتورهای سفارشی، بستههای زبانی و خط لولههای انباشته
- منبع: `open-sse/services/compression/engines/rtk/` (۶۳ فایل، حدود ۷۰ کیلوبایت)