# 🗜️ Prompt Compression Guide — OmniRoute (فارسی)

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

---

> بهصورت خودکار 15-95٪ در زمینهٔ واجد شرایط صرفهجویی کنید. برای مروری سریع، بخش [فشردهسازی README](../README.md#%EF%B8%8F-prompt-compression--save-15-95-eligible-tokens-automatically) را ببینید.

## نمای کلی

OmniRoute یک خط لولهٔ ماژولار برای فشردهسازی پرامپت پیادهسازی میکند که **بهصورت پیشدستانه**، پیش از رسیدن درخواستها به ارائهدهندگان بالادستی اجرا میشود. این یعنی صرفهجویی در توکنها بهشکلی شفاف انجام میشود — نیازی به تغییر گردش کار شما نیست.

```
درخواست کلاینت
  → انتخابگر راهبرد فشردهسازی
    → بازنویسی با ترکیب؟ → استفاده از تنظیم ترکیب
    → آستانهٔ فعالسازی خودکار؟ → استفاده از حالت خودکار
    → حالت پیشفرض؟ → استفاده از تنظیم سراسری
    → خاموش؟ → رد شدن از فشردهسازی
  → حالت فشردهسازی انتخابشده
    → خاموش: بدون فشردهسازی
    → سبک: پاکسازی ایمن فاصلههای خالی/قالببندی (~15%)
    → استاندارد: حذف کلمات زائد به سبک Caveman (~30%)
    → تهاجمی: قدیمیسازی تاریخچه + خلاصهسازی (~50%)
    → فوقفشرده: هرس ابتکاری + تنکسازی بلوکهای کد (~75%)
    → RTK: پالایش آگاه از فرمان برای خروجی ترمینال/ابزار (بازهٔ بالادستی 60-90%)
    → پشتهای: خط لولهٔ مرتبشدهٔ چندموتوره، معمولاً ابتدا RTK و سپس Caveman (بازهٔ واجد شرایط 78-95%)
  → درخواست فشردهشده → ارائهدهنده
```

---

## حالتهای فشردهسازی

### خاموش

هیچ فشردهسازیای اعمال نمیشود. همهٔ پیامها بدون تغییر عبور میکنند.

### حالت سبک (~15% صرفهجویی، <1ms تأخیر)

ایمنترین حالت — بدون هیچ تغییر معنایی و تنها با پاکسازی قالببندی:

| روش                      | توضیحات                                       |
| ------------------------ | --------------------------------------------- |
| `collapseWhitespace`     | ادغام خطوط خالی متوالی و فاصلههای انتهای خطوط |
| `dedupSystemPrompt`      | حذف پیامهای سیستمی تکراری                     |
| `compressToolResults`    | فشردهسازی خروجیهای طولانی ابزار/تابع          |
| `removeRedundantContent` | حذف دستورالعملهای تکراری                      |
| `replaceImageUrls`       | کوتاهسازی URIهای دادهٔ base64 تصاویر          |

**مناسب برای:** استفادهٔ همیشگی و گردشهای کاری حساس به ایمنی.

### حالت استاندارد (~30% صرفهجویی)

با الهام از [Caveman](https://github.com/JuliusBrussee/caveman) — کلمات زائد و عبارتهای طولانی را با حفظ معنا حذف میکند:

- حذف کلمات زائد («لطفاً»، «فکر میکنم»، «اساساً»، «در واقع»)
- خلاصهسازی عبارتهای طولانی («بهمنظور» ← «برای»، «در نتیجهٔ» ← «زیرا»)
- حذف عبارات مؤدبانهٔ محتاطانه («ممکن است لطف کنید...»، «اگر امکان دارد...»)
- بیش از 30 قاعدهٔ regex تنظیمشده برای پرامپتهای کدنویسی

**مناسب برای:** گردشهای کاری روزمرهٔ کدنویسی و تیمهای حساس به هزینه.

### حالت تهاجمی (~50% صرفهجویی)

مدیریت هوشمند تاریخچه برای نشستهای طولانی:

- **قدیمیسازی پیامها** — پیامهای قدیمیتر بهصورت تدریجی بیشتر فشرده میشوند
- **خلاصهسازی نتایج ابزار** — خروجیهای طولانی ابزار با خلاصه جایگزین میشوند
- **محافظهای یکپارچگی ساختاری** — سازگاری جفتهای `tool_use` + `tool_result` را تضمین میکند
- **آگاهی از پنجرهٔ زمینه** — محدودیت توکن هر مدل را رعایت میکند

**مناسب برای:** نشستهای طولانی اشکالزدایی و کدبیسهای بزرگ.

### حالت فوقفشرده (~75% صرفهجویی)

حداکثر فشردهسازی برای سناریوهای حساس به تعداد توکن:

- **هرس ابتکاری** — پیامهای پایینتر از آستانهٔ مرتبطبودن را حذف میکند
- **تنکسازی بلوکهای کد** — نمونهکدهای تکراری را فشرده میکند
- **برش با جستوجوی دودویی** — نقطهٔ بهینهٔ برش را برای پنجرهٔ زمینه پیدا میکند
- شامل تمام قابلیتهای حالت تهاجمی

**مناسب برای:** زمانی که بهطور مکرر به محدودیتهای زمینه میرسید.

### حالت RTK (بازهٔ بالادستی 60-90%)

حالت RTK برای خروجیهای طولانی ابزار که در نشستهای عامل کدنویسی ظاهر میشوند، بهینه شده است:

- کلاسهای فرمان/خروجی مانند `git status`، `git diff`، `git log`، اجراکنندههای آزمون،
  ساختهای TypeScript/Vite/Webpack، ابزارهای ESLint/Biome/Prettier، ممیزیها/نصبهای npm، گزارشهای Docker، خروجی
  زیرساخت و خروجی عمومی پوسته را تشخیص میدهد
- بستههای پالایش JSON را از `open-sse/services/compression/engines/rtk/filters/` اعمال میکند
- پالایشهای RTK TOML schema v1 را از فایلهای پروژه یا سراسری `filters.toml` وارد میکند و برای فایلهای پروژه،
  اعتبارسنجی آزمون درونخطی و کنترل مبتنی بر اعتماد را بهکار میگیرد
- همراه با 49 پالایش داخلی و نمونههای تأیید درونخطی عرضه میشود
- دنبالههای کنترلی ANSI، نوارهای پیشرفت، خطوط تکراری و نویزهای غیرقابلاقدام را حذف میکند
- شکستها، خطاها، هشدارها، فایلهای تغییریافته، خلاصهها و بخش انتهایی خروجیهای طولانی را حفظ میکند
- از پالایشهای پروژه مبتنی بر اعتماد، پالایشهای سراسری و بازیابی اختیاری خروجی خامِ ویرایششده پشتیبانی میکند

**مناسب برای:** نشستهای عامل شامل رونوشتهای پوسته، ساخت، آزمون، git، grep و خروجی فایل.

### حالت پشتهای (بازهٔ واجد شرایط 78-95%)

حالت پشتهای چندین موتور فشردهسازی را با ترتیبی قطعی اجرا میکند. خط لولهٔ پیشفرض بهشکل زیر است:

```txt
RTK -> Caveman
```

این ترتیب ابتدا خروجی ترمینال/ابزار را فشرده نگه میدارد و سپس چگالش معنایی Caveman را روی
بخش باقیماندهٔ پرامپت زبان طبیعی اعمال میکند. خط لولههای پشتهای را میتوان بهصورت سراسری یا از طریق
ترکیبهای فشردهسازی تخصیصیافته به ترکیبهای مسیریابی پیکربندی کرد.

**مناسب برای:** زمینهٔ ترکیبی شامل گزارشهای حجیم ابزار همراه با دستورالعملهای انسانی یا خلاصههای دستیار.

---

## محاسبات صرفهجویی بالادستی

OmniRoute صرفهجویی ناشی از فشردهسازی را بر اساس دو منبع مستند میکند: بنچمارکهای پروژههای بالادستی و
ترکیب موتورهای خود OmniRoute.

| منبع    | عدد README بالادستی استفادهشده در اینجا                                                                       |
| ------- | ------------------------------------------------------------------------------------------------------------- |
| Caveman | `~75%` توکن خروجی کمتر، `65%` میانگین صرفهجویی خروجی در بنچمارک، بازه `22-87%` و ابزار فشردهسازی ورودی `~46%` |
| RTK     | صرفهجویی `60-90%` در خروجی فرمان؛ نشست نمونه با `~118,000 -> ~23,900` توکن، یا `79.7%` صرفهجویی (`~80%`)      |

برای بارهای همپوشان ابزار/زمینه، ترکیب پیشفرض OmniRoute موتورها را بهصورت پشتهای اجرا میکند:

```txt
RTK -> Caveman
```

صرفهجویی ترکیبی، ضربی است، نه جمعی:

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

عدد `78-95%` زمانی صدق میکند که هم RTK و هم Caveman بتوانند همان بار ورودی/زمینه را کاهش دهند.
حالت خروجی پاسخ Caveman جداگانه است: وقتی فعال باشد، از صرفهجویی خروجی خود Caveman استفاده کنید (میانگین `65%`،
عدد شاخص `~75%` و بازه `22-87%`). صرفهجویی کل در هزینه به ترکیب پرامپت/خروجی شما بستگی دارد.

### منظور واقعی از «واجد شرایط» چیست

بازه شاخص 15-95% واقعی است، اما فقط برای محتوای **تکراری یا پرحجم** کاربرد دارد — خطوط خطای تکراری،
گزارش ساختی که همان هشدار را پشتسرهم تکرار میکند، یا خروجی بیشازحد بزرگ `grep`/خواندن فایل. این
به این معنا **نیست** که هر درخواست همینقدر صرفهجویی دارد.

بهصورت تجربی تأیید شده است (`tests/unit/compression/stacked-compression-tool-result-savings.test.ts`): یک
اجرای `stacked` (RTK + Caveman) روی یک بلوک `tool_result` با ساختار Anthropic که شامل 300 خط خطای یکسان بود،
**95.93% صرفهجویی توکن / 96.26% صرفهجویی کاراکتر** ایجاد کرد — دقیقاً در محدوده اعلامشده.
اما اجرای همان خط لوله روی خروجی عادی و غیرتکراری ابزار (فهرست تطبیقهای تمیز `grep`،
خواندن یک فایل کوتاه، متن مکالمهای معمولی) بهدرستی **صرفهجویی نزدیک به صفر** ایجاد میکند، زیرا
هیچ محتوای تکراری برای حذف وجود ندارد و `validateCompression()` (`validation.ts`) اجازه ارسال
بازنویسیای را نمیدهد که بلوکهای کد، URLها، عنوانها، نسخهها یا شناسههای ثابت تماماً با حروف بزرگ را حذف یا تغییر دهد.

این رفتاری مورد انتظار و ایمن است، نه یک باگ: یک نشست کدنویسی که عمدتاً فایلهای تمیز را میخواند یا در آنها
`grep` اجرا میکند، حتی با فعالبودن کامل فشردهسازی نیز صرفهجویی کلی محدودی خواهد داشت؛ درحالیکه نشستی که با یک حلقه
ناموفق یا یک لینتر پرحرف مواجه میشود، روی آن ترافیک از بازه کامل 78-95% بهره میبرد. درصد پایین
صرفهجویی تجمیعی یک نشست را بهتنهایی نشانه پیکربندی نادرست فشردهسازی ندانید — ابتدا بررسی کنید که آیا
خروجی ابزار واقعاً تکراری بوده است یا نه.

---

## نمایش تصویری صرفهجویی توکن

```
بدون فشردهسازی: 47K توکن ارسالشده به LLM
با Lite:         40K توکن ارسالشده          (15% صرفهجویی — ایمن، همیشه فعال)
با Standard:     33K توکن ارسالشده          (30% صرفهجویی — قواعد caveman-speak)
با Aggressive:   24K توکن ارسالشده          (50% صرفهجویی — کهنهسازی + خلاصهسازی)
با Ultra:        12K توکن ارسالشده          (75% صرفهجویی — هرس اکتشافی)
با RTK:          19K-5K توکن ارسالشده       (60-90% صرفهجویی در خروجی فرمان/ابزار)
با Stacked:      10K-2.5K توکن ارسالشده     (بازه 78-95% برای محتوای واجد شرایط RTK+Caveman)
```

---

## پیکربندی

### داشبورد

به `Dashboard → Context & Cache` بروید:

- **Caveman** — انتخاب حالت، بستههای زبان، پیشنمایش و پیشفرضهای سراسری
- **RTK** — پیشنمایش فیلتر فرمان، تنظیمات ایمنی RTK و فهرست فیلترها
- **ترکیبهای فشردهسازی** — خطلولههای نامگذاریشدهٔ موتور که به ترکیبهای مسیریابی اختصاص داده شدهاند
- **آستانهٔ فعالسازی خودکار** — هنگامی که تعداد توکنها از آستانه عبور کند، فشردهسازی را بهصورت خودکار فعال میکند

### بازنویسی برای هر ترکیب

در `Dashboard → Context & Cache → Compression Combos`، یک ترکیب فشردهسازی را به یک ترکیب
مسیریابی اختصاص دهید:

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

این کار به شما اجازه میدهد از فشردهسازی پشتهای برای ارائهدهندگان رایگان/کدنویسی استفاده کنید، درحالیکه حالت سبک را برای
اشتراکهای پولی حفظ میکنید.

این تخصیص «بازنویسی برای هر ترکیب» کنترلی متفاوت از بازنویسی **حالت فشردهسازی ترکیب
مسیریابی** (Default/Off/Lite/Standard/Aggressive/Ultra) است — آن بازنویسی یک خطلولهٔ نامگذاریشدهٔ
ترکیب فشردهسازی را انتخاب نمیکند؛ بلکه فقط فیلد `compressionMode` را تنظیم میکند که
`resolveCompressionPlan` به آن رجوع میکند. این مقدار را میتوان روی کارت ترکیب (`Dashboard → Combos`) یا، از
#6760 به بعد، برای هر ترکیب مسیریابی در فهرست «Assign to routing» در
`Dashboard → Context & Cache → Compression Combos`، درست کنار کادر انتخاب تخصیص خطلوله که
در بالا مستند شده است، تنظیم کرد. هر دو رابط از طریق همان نقطهٔ پایانی `PUT /api/combos/{id}` ذخیره میشوند.

### بازنویسی برای هر درخواست

برای بازنویسی طرح فشردهسازی یک درخواست، هدر درخواست `x-omniroute-compression` را ارسال کنید.
این هدر بالاترین اولویت را دارد — بر بازنویسی ترکیب مسیریابی، پروفایل فعال،
فعالسازی خودکار و مقدار Default پنل مقدم است. مقادیر ناشناخته نادیده گرفته میشوند (درخواست هرگز رد نمیشود) و
کلید اصلی سراسری همچنان همهچیز را کنترل میکند: وقتی فشردهسازی بهصورت سراسری خاموش باشد، هدر نمیتواند
آن را روشن کند. مقادیر:

| مقدار         | اثر                                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------------------- |
| `off`         | برای این درخواست فشردهسازی انجام نمیشود.                                                                            |
| `default`     | پروفایل Default برگرفته از پنل (پروفایل فعال را نادیده میگیرد).                                                     |
| `engine:<id>` | در صورت فعال بودن، یک موتور منفرد؛ برای مثال `engine:rtk`.                                                          |
| `<combo>`     | یک ترکیب نامگذاریشده که ابتدا بر اساس نام (بدون حساسیت به بزرگی و کوچکی حروف) و سپس بر اساس شناسه تطبیق داده میشود. |

طرح اعمالشده در هدر پاسخ `X-OmniRoute-Compression: <mode>; source=<source>` بازتاب داده میشود،
که در آن `<source>` یکی از مقادیر `request-header`، `routing-override`، `active-profile`،
`auto-trigger`، `default` یا `off` است.

### API

```bash
# دریافت تنظیمات فشردهسازی
curl http://localhost:20128/api/settings/compression

# بهروزرسانی تنظیمات فشردهسازی
curl -X PUT http://localhost:20128/api/settings/compression \
  -H "Content-Type: application/json" \
  -d '{"defaultMode":"stacked","autoTriggerMode":"stacked","autoTriggerTokens":32000}'

# پیشنمایش یک بار RTK/پشتهای مشخص
curl -X POST http://localhost:20128/api/compression/preview \
  -H "Content-Type: application/json" \
  -d '{"mode":"rtk","messages":[{"role":"tool","content":"npm test output here"}]}'

# فهرستکردن بستههای فیلتر RTK
curl http://localhost:20128/api/context/rtk/filters

# آزمایش مستقیم RTK با فرادادهٔ اختیاری فرمان
curl -X POST http://localhost:20128/api/context/rtk/test \
  -H "Content-Type: application/json" \
  -d '{"command":"npm test","text":"FAIL tests/example.test.ts\nError: boom"}'
```

---

## چه چیزهایی محافظت میشوند

موتور فشردهسازی **همیشه موارد زیر را حفظ میکند:**

- ✅ بلوکهای کد (محصور و درونخطی)
- ✅ نشانیهای URL و مسیرهای فایل
- ✅ ساختارهای JSON و دادههای ساختیافته
- ✅ شناسهها و توکنهای فنی محافظتشده
- ✅ عبارتهای ریاضی
- ✅ تعریف فراخوانی ابزار/تابع
- ✅ پرامپتهای سیستمی (در حالت lite)

بازیابی خروجی خام RTK، کلیدهای API رایج، توکنهای bearer، توکنهای Slack، کلیدهای دسترسی AWS،
گذرواژهها، توکنها و اسرار را پیش از ذخیرهشدن هر چیزی حذف میکند.

---

## آمار فشردهسازی

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

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

---

## نقشه راه فازها

| فاز    | حالتها                                                                                                                                | وضعیت        |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| فاز 1  | Off, Lite                                                                                                                             | ✅ منتشر شده |
| فاز 2  | Standard, Aggressive, Ultra                                                                                                           | ✅ منتشر شده |
| فاز 3  | RTK, Stacked, Compression Combos                                                                                                      | ✅ منتشر شده |
| فاز 4  | Output Styles, SLM-tier Ultra, eval harness                                                                                           | ✅ منتشر شده |
| فاز 4C | بودجه تطبیقی زمینه ("dial") — موتور محاسباتی + API (`contextBudget` در `PUT /api/settings/compression`) + کنترلهای حالت/سیاست داشبورد | ✅ منتشر شده |

---

## قدردانیها

قواعد فشردهسازی حالت Standard از **[Caveman](https://github.com/JuliusBrussee/caveman)**، ساخته **[JuliusBrussee](https://github.com/JuliusBrussee)** (⭐ 51K+)، الهام گرفته شدهاند — پروژه فراگیر «چرا وقتی توکن کم کار را انجام میدهد، از توکن زیاد استفاده کنیم». Caveman کاهش `~75%` در توکنهای خروجی، میانگین `65%` صرفهجویی خروجی در بنچمارک، بازه `22-87%` برای خروجی و یک ابزار فشردهسازی ورودی با نرخ `~46%` را گزارش میکند.

حالت RTK از **[RTK - Rust Token Killer](https://github.com/rtk-ai/rtk)**، ساخته **[RTK AI](https://github.com/rtk-ai)**، الهام گرفته شده است — پروژهای با کارایی بالا برای فشردهسازی خروجی فرمانها در ترمینال، فرایند ساخت، آزمایش، git و پالایش خروجی ابزارها. RTK صرفهجویی `60-90%` را گزارش میکند و نشست نمونه در README آن، صرفهجویی `~80%` را نشان میدهد.

---

## سامانههای پیشرفته فشردهسازی

فراتر از 7 حالت استاندارد، OmniRoute شامل چندین سامانه پیشرفته فشردهسازی
است که بر اساس زمینه، بهطور خودکار عمل میکنند.

### فشردهسازی آگاه از کش

برخی ارائهدهندگان (مانند Anthropic با کشکردن پرامپت) از **کشکردن پرامپت**
پشتیبانی میکنند که به آنها اجازه میدهد بخشهایی از پرامپت را برای کاهش هزینه و تأخیر کش کنند. وقتی
کش فعال است، فشردهسازی تهاجمی در واقع میتواند به عملکرد **آسیب بزند**،
زیرا توکنهای کششده را تغییر میدهد و کش را نامعتبر میکند.

ماژول `cachingAware.ts` این مشکل را با **تشخیص زمینه کش** و
**تنظیم راهبرد فشردهسازی** بر همان اساس حل میکند.

#### نحوه عملکرد

1. **تشخیص زمینه کش** — بدنه درخواست را برای نشانگرهای `cache_control` اسکن میکند
2. **شناسایی ارائهدهندگان دارای کش** — بررسی میکند آیا ارائهدهنده مقصد از کش پشتیبانی میکند
3. **تنظیم راهبرد** — برای ارائهدهندگان دارای کش، `aggressive`/`ultra` را به `standard` تنزل میدهد
4. **نادیدهگرفتن پرامپت سیستم** — پرامپتهای سیستم معمولاً کش میشوند، بنابراین آنها را فشرده نمیکند
5. **استفاده از تبدیلهای قطعی** — فقط از تبدیلهایی استفاده میکند که خروجی سازگار تولید میکنند

#### نمونه کد

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

const body = {
  model: "anthropic/claude-sonnet-4.5",
  messages: [{ role: "user", content: "Hello" }],
  cache_control: { type: "ephemeral" }, // ← نشانگر کش
};

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

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

#### زمان استفاده

فشردهسازی آگاه از کش **همیشه فعال است** — به هیچ پیکربندیای نیاز نیست. این قابلیت فقط زمانی وارد عمل میشود
که:

- درخواست دارای نشانگرهای `cache_control` باشد
- ارائهدهنده مقصد از کشکردن پرامپت پشتیبانی کند (Anthropic، OpenAI و غیره)

### فرسودگی تدریجی

گفتوگوهای طولانی نوبتهای پیام زیادی انباشته میکنند، اما نوبتهای قدیمیتر بهتدریج
ارتباط کمتری پیدا میکنند. ماژول `progressiveAging.ts` **پیامها را بر اساس فاصله نوبت تنزل میدهد**:

- **نوبتهای اخیر (0-3)**: بدون تغییر نگه داشته میشوند (جزئیات کامل)
- **نوبتهای میانی (4-8)**: فشردهسازی Lite (پاکسازی فاصلههای خالی و قالببندی)
- **نوبتهای قدیمی (9+)**: فشردهسازی Caveman (حذف عبارتهای زائد و خلاصهسازی)
- **نوبتهای بسیار قدیمی (20+)**: بهشدت خلاصه یا حذف میشوند

#### نمونه کد

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

const messages = [
  { role: "system", content: "You are a helpful assistant" },
  { role: "user", content: "What is 2+2?" },
  { role: "assistant", content: "4" },
  // ... 50 نوبت دیگر ...
];

const { messages: aged, saved } = applyAging(messages, {
  verbatim: 3, // 3 نوبت اول: بدون تغییر
  light: 8, // نوبتهای 4 تا 8: فشردهسازی lite
  moderate: 20, // نوبتهای 9 تا 20: فشردهسازی caveman
  // نوبتهای 21 به بعد: خلاصهسازی شدید
});

// saved = تعداد توکنهای صرفهجوییشده
```

#### زمان استفاده

پیرسازی تدریجی برای حالتهای `aggressive` و `ultra` **همیشه فعال است**. این قابلیت
بهویژه برای موارد زیر مؤثر است:

- نشستهای طولانی کدنویسی
- گفتوگوهای چندروزه
- گردشکارهای عاملی با فراخوانیهای متعدد ابزار

### حالت خروجی غارنشینی

ماژول `outputMode.ts`، **دستورالعملهای اعلان سیستم** را تزریق میکند تا خود
مدل خروجی فشرده و مختصر تولید کند (سبک «غارنشینی»).

#### نحوه کار

این حالت بهجای فشردهسازی ورودی، یک اعلان سیستم مانند زیر اضافه میکند:

> «با حداقل کلمات پاسخ بده. تعارفات را حذف کن. از جملههای کوتاه استفاده کن.»

این روش بهویژه برای موارد زیر مناسب است:

- تولید کد (خروجی مختصرتر = توکنهای کمتر)
- پرسشوپاسخ سریع (نیازی به توضیحات مفصل نیست)
- پردازش دستهای (بیشینهسازی توان عملیاتی)

#### زمان استفاده

حالت خروجی غارنشینی **اختیاری** است — آن را از طریق پیکربندی ترکیبی تنظیم کنید:

```json
{
  "strategy": "auto",
  "config": {
    "auto": {
      "outputMode": "caveman"
    }
  }
}
```

### سبکهای خروجی (کاتالوگ)

حالت خروجی غارنشینی بالا، **مسیر تکسبکی قدیمی** است. فاز 4 آن را
به کاتالوگی از سبکهای خروجی قابلترکیب تعمیم داد: `OUTPUT_STYLE_CATALOG` در
`open-sse/services/compression/outputStyles/catalog.ts`. هر سبک یک دستورالعمل اعلان سیستم
است که باعث میشود خود مدل خروجی کمهزینهتری تولید کند؛ سبکها را میتوان همزمان فعال
کرد و آنها به ترتیب کاتالوگ تزریق میشوند.

| سبک                           | `id`          | عملکرد                                                                                                                                                                                                   | زبانهای دستورالعمل                                                  |
| ----------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| نثر مختصر                     | `terse-prose` | حذف حشو، حروف تعریف و دودلی؛ حفظ دقیق محتوای فنی. همان متن حالت خروجی غارنشینی قدیمی است (به آن ارجاع داده میشود، نه اینکه دوباره نوشته شود).                                                            | en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi                       |
| کد کمتر                       | `less-code`   | نردبان YAGNI: کوچکترین تغییر عملی، بدون انتزاعهای درخواستنشده.                                                                                                                                           | en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi                       |
| دماسبی (توسعهدهنده ارشد تنبل) | `ponytail`    | «بهترین کد، کدی است که هرگز نوشته نشود»: استفاده مجدد > بازنویسی، علت ریشهای > نشانه، کوتاهترین تفاوت عملی.                                                                                              | en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi                       |
| من ADHD دارم (اول عمل)        | `i-have-adhd` | ابتدا عمل (فرمان/مسیر/قطعهکد پیش از نثر)، گامهای شمارهدار و محدود، تنها یک گام بعدی مشخص، بدون مقدمه/جمعبندی/سخن پایانی. اقتباسشده از [ayghri/i-have-adhd](https://github.com/ayghri/i-have-adhd) (MIT). | en, pt-BR, es, de, fr, it, ru, zh, ja, id, vi                       |
| CJK مختصر (文言)              | `terse-cjk`   | سبک فوقمختصر چینی کلاسیک.                                                                                                                                                                                | zh (محدود به locale: فقط زمانی ارائه میشود که زبان حلشده `zh` باشد) |

هر سبک دارای سه سطح شدت است — `lite`، `full` و `ultra` — و هر سطح
با بند مرزهای مشترک پایان مییابد که بلوکهای کد، مسیرهای فایل، فرمانها،
رشتههای خطا، URLها و شناسهها را عیناً حفظ میکند.

#### نحوه تزریق

`applyOutputStyles()` (`open-sse/services/compression/outputStyles/apply.ts`)
انتخابها را با کاتالوگ تطبیق میدهد (شناسههای ناشناخته و سبکهای ناسازگار با locale
حذف میشوند و هرگز خطا ایجاد نمیکنند)، دستورالعملهای انتخابشده را به ترتیب کاتالوگ
به هم متصل میکند، بند مرزها را **یکبار** میافزاید و نتیجه را با یک نشانگر یکتای
ایدِمپوتنسی (`[OmniRoute Output Styles]`) در ابتدای اعلان سیستم قرار میدهد — اعمال
مجدد هیچ کاری انجام نمیدهد. وقتی زبان شناساییشده درخواست ترجمهای داشته باشد،
دستورالعمل بومیسازیشده بهجای انگلیسی تزریق میشود.

#### نحوه فعالسازی

در داشبورد: **زمینه → تنظیمات → فشردهسازی** — برای هر سبک یک ردیف با کلید
روشن/خاموش و انتخابگر سطح وجود دارد. از طریق برنامه، پیکربندی فشردهسازی
انتخابها را بهشکل زیر ذخیره میکند:

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

سازگاری با نسخههای قبلی: تنظیم ترکیبی قدیمی `outputMode: "caveman"` همچنان کار میکند و به
`terse-prose` نگاشت میشود؛ تزریق حاصل در همه زبانهای قدیمی، بایتبهبایت با نسخه قبلی یکسان است.

انتخاب زبان: وقتی `languageConfig.enabled` روشن باشد، `autoDetect` زبان
آخرین پیام کاربر را انتخاب میکند (با همان آشکارساز موتورهای ورودی)؛
خاموشکردن `autoDetect` زبان را روی `defaultLanguage` ثابت میکند. در حالت خاموش → انگلیسی.

ماتریس سبک × زبان توسط
`tests/unit/compression/output-styles-i18n-matrix.test.ts` تثبیت شده است: یک سبک جدید نمیتواند
بدون دستکم یک ترجمه pt-BR (یا یک استثنای صریح و رهگیریشده) منتشر شود و یک
سبک موجود نمیتواند بیسروصدا یک locale را از دست بدهد. برای افزودن سبک، به
[EXTENDING_COMPRESSION.md](./EXTENDING_COMPRESSION.md#adding-an-output-style) مراجعه کنید.

### فشردهسازی نتیجه ابزار

ماژول `toolResultCompressor.ts`، **5 راهبرد تخصصی فشردهسازی**
برای نتایج ابزار (فراخوانیهای تابع، خروجیهای عامل، نتایج جستوجو و غیره) فراهم میکند:

1. **فشردهسازی نتایج جستوجو** — نتایج تکراری را حذف میکند و N نتیجه برتر را نگه میدارد
2. **فشردهسازی خواندن فایل** — فایلهای بزرگ را کوتاه میکند و سرآیندها/واردسازیها را حفظ میکند
3. **فشردهسازی اجرای کد** — فقط stdout/stderr ضروری را نگه میدارد
4. **فشردهسازی کوئری پایگاه داده** — تعداد ردیفها را محدود و فرادادههای طولانی را حذف میکند
5. **فشردهسازی پاسخ API** — فیلدهای null را حذف و آرایهها را فشرده میکند

#### زمان استفاده

فشردهسازی نتیجه ابزار هنگام وجود فراخوانی ابزار **همیشه فعال است**.
به هیچ پیکربندیای نیاز نیست.

### خط لوله پشتهای

حالت پشتهای **چند موتور را بهترتیب** اجرا میکند — معمولاً ابتدا RTK
(صرفهجویی 60-90٪ در خروجی ابزار)، سپس غارنشینی (30٪ صرفهجویی بیشتر در
متن باقیمانده). این روش در مجموع **78-95٪ صرفهجویی** ایجاد میکند.

#### نحوه کار

```
ورودی (1000 توکن)
  → RTK (فیلتر آگاه از فرمان) → 200 توکن
    → غارنشینی (حذف حشو) → 140 توکن
  → خروجی (140 توکن، 86٪ صرفهجویی)
```

#### زمان استفاده

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

- گردشکارهای متکی بر ابزار (کدنویسی عاملی، پژوهش)
- پردازش دستهای حساس به هزینه
- زمانی که به بیشترین صرفهجویی در توکن نیاز دارید

از طریق پیکربندی ترکیبی تنظیم کنید:

```json
{
  "strategy": "auto",
  "config": {
    "auto": {
      "modePack": "stacked"
    }
  }
}
```

---

## بازنویسیهای ترکیبی فشردهسازی

میتوانید حالت سراسری فشردهسازی را **برای هر ترکیب** بازنویسی کنید تا رفتار آن را برای موارد استفاده مختلف بهدقت تنظیم کنید:

```json
{
  "id": "coding-combo",
  "strategy": "priority",
  "config": {
    "auto": {
      "weights": { "taskFit": 0.5 },
      "modePack": "quality-first"
    }
  },
  "compressionOverride": {
    "mode": "aggressive",
    "stackedPipelines": ["rtk", "caveman"],
    "preserveToolDefinitions": true
  }
}
```

این قابلیت برای موارد زیر مفید است:

- **ترکیبهای کدنویسی**: برای نشستهای طولانی از حالت `aggressive` استفاده کنید
- **ترکیبهای پرسشوپاسخ سریع**: برای پاسخهای سریع از حالت `lite` استفاده کنید
- **ترکیبهای متکی بر ابزار**: برای حداکثر صرفهجویی از حالت `stacked` استفاده کنید
- **ترکیبهای محیط عملیاتی**: برای ارائهدهندگان دارای قابلیت کش از حالت `cache-aware` استفاده کنید

---

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

- [پیکربندی محیط](../reference/ENVIRONMENT.md) — متغیرهای محیطی فشردهسازی
- [راهنمای معماری](../architecture/ARCHITECTURE.md) — جزئیات داخلی خط لوله فشردهسازی
- [راهنمای کاربر](../guides/USER_GUIDE.md) — شروع کار با فشردهسازی
- [فشردهسازی RTK](./RTK_COMPRESSION.md) — فیلترهای RTK، مدل اعتماد، دروازه تأیید و بازیابی خروجی خام
- [موتورهای فشردهسازی](./COMPRESSION_ENGINES.md) — Caveman، RTK، حالت انباشته، APIها، MCP و داشبورد
- [قالب قوانین فشردهسازی](./COMPRESSION_RULES_FORMAT.md) — قالب بسته قوانین JSON
- [بستههای زبانی فشردهسازی](./COMPRESSION_LANGUAGE_PACKS.md) — قوانین مختص زبان Caveman