OmniRoute/docs/i18n/fa/docs/compression/RTK_COMPRESSION.md

RTK Compression (فارسی)

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

---

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

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

rtk -> caveman

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

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

میانگین 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%

چه چیزهایی را فشرده میکند

کاتالوگ داخلی در حال حاضر شامل 49 فیلتر در دستههای زیر است:

دسته	نمونهها
git	git status، git branch، git diff، git log
test	Vitest، Jest، Pytest، 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، ردگیریهای پشته، جایگزین عمومی خروجی

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

تفکیک فیلتر

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 منطبق با فایل فیلتر پروژه باشد.

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

{
  "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 شرحدادهشده در قالب قواعد فشردهسازی استفاده میکنند. محیط اجرا این مراحل را بهترتیب اعمال میکند:

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 در دسترس هستند.

{
  "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:

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

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

{
  "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:

{
  "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 را پس از سانسور نگه میدارد

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

DATA_DIR/rtk/raw-output/

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

دروازه تأیید

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

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

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

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

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

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 از 3 سطح شدت پشتیبانی میکند که میان تهاجمیبودن فشردهسازی و ایمنی موازنه برقرار میکنند. سطح از طریق config.intensity در پیکربندی موتور تنظیم میشود.

3 سطح

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

محل وقوع کوتاهسازی

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

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

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

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

محتوا	minimal	standard	aggressive
خطاها / ردگیریهای پشته	✅ حفظ میشود	✅ حفظ میشود	✅ حفظ میشود
شکست آزمونها	✅ حفظ میشود	✅ حفظ میشود	✅ حفظ میشود
خطاهای ساخت	✅ حفظ میشود	✅ حفظ میشود	✅ حفظ میشود
آزمونهای موفق (پرمحتوا)	✅ حفظ میشود	🟡 خلاصه میشود	🟡 خلاصه میشود
خروجی معمول (گزارشهای اطلاعاتی)	🟡 خلاصه میشود	🟡 خلاصه میشود	❌ حذف میشود
نوارهای پیشرفت	🟡 خلاصه میشود	❌ حذف میشود	❌ حذف میشود
بنر / هنر ASCII	🟡 خلاصه میشود	❌ حذف میشود	❌ حذف میشود

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

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

پیکربندی شدت

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

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

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

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

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

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

تأیید اثر

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

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)

{
  "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 پایتون

{
  "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/

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

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)

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

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

{
  "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

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

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

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() را فراخوانی کنید:

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_ENGINES.md — رجیستری موتور و موتورهای داخلی
• EXTENDING_COMPRESSION.md — موتورهای سفارشی، بستههای زبانی و خط لولههای انباشته
• منبع: open-sse/services/compression/engines/rtk/ (۶۳ فایل، حدود ۷۰ کیلوبایت)