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

RTK Compression (العربية)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 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/.

ضمن النطاق نفسه، تكون لمرشحات مخطط RTK TOML بالإصدار v1 أسبقية على مرشحات OmniRoute بصيغة JSON. وتُفحص تعبيرات 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 الإصدار v1

يمكن لـ OmniRoute تحليل ملفات المرشحات التعريفية والتحقق منها واختبارها وتثبيتها باستخدام مخطط RTK TOML الإصدار v1. الحقول المدعومة هي 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، والإشارات إلى مرشحات غير معروفة. يمكن التحقق من ملف تفشل اختباراته المضمّنة بغرض فحصه، ولكن لا يمكن تثبيته أو تحميله. تظل حالات فشل تحميل الملفات المخصصة متسامحة مع الفشل: يُتخطى الملف غير الصالح وتستمر بقية المرشحات في العمل.

يتلقى OmniRoute مخرجات الأداة بعد أن يكون العميل قد التقطها بالفعل، لذلك لا يمكن لـ filter_stderr = true تغيير عملية الالتقاط. يُقبل الحقل دون تنفيذ أي إجراء، ويُرجع التحقق تحذيرًا. يوصف هذا عمدًا بأنه توافق مع مخطط RTK TOML الإصدار v1، وليس توافقًا كاملًا مع ملف RTK التنفيذي، أو خطافات الصدفة، أو تطبيقات أوامر Rust، أو تخطيط مخزن الثقة الخاص به.

تقبل طريقة عرض RTK المتقدمة في لوحة المعلومات محتوى TOML ملصقًا أو مرفوعًا. التحقق للقراءة فقط. تكتب عملية التثبيت الملف DATA_DIR/rtk/filters.toml بصورة ذرية مع أذونات مقيّدة، وتحدّث كتالوج المرشحات النشط دون إعادة تشغيل. يتطلب استبدال ملف موجود تأكيدًا صريحًا عبر overwrite وينشئ أولًا DATA_DIR/rtk/filters.toml.bak.

لغة المرشحات الخاصة بالمجال

تستخدم المرشحات مخطط 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 واحدة في جدول SQLite المسمى key_value ضمن namespace = "compression"، وkey = "rtkConfig" (src/lib/db/compression.ts)، وتُطبَّع قيمته عند القراءة بواسطة normalizeRtkConfig. لذلك، تخضع جميع الحقول أدناه — بما في ذلك enableGrouping، وgroupingThreshold، وstripCodeComments، وpreserveDocstrings — لدورة ذهاب وإياب عبر مخزن البيانات نفسه، وتبقى محفوظة بعد إعادة التشغيل.

المفتاح	القيمة الافتراضية	الغرض
deduplicateThreshold	3	على مستوى المحرك: الحد الأدنى للأسطر المتطابقة المتتالية لطيّها (بين 2 و100)
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	التحقق من ملفات مخطط RTK TOML بالإصدار v1 أو تثبيتها
/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 المطابقة.

حمولة التحقق من RTK TOML:

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

تُنقَّح الأسرار قبل حفظها، بما في ذلك رموز حامل المصادقة الشائعة، ومفاتيح 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. أضف عيّنة اختبار ضمن tests/unit/compression/fixtures/rtk/ لعائلات الأوامر الجديدة.
4. أضف تغطية لاكتشاف الأوامر عند تقديم فئة مخرجات جديدة.
5. شغّل بوابة التحقق وبوابات RTK الشاملة.
6. إذا كان المرشّح محليًا للمشروع، فأدرج .rtk/filters.json في الالتزام وحدّث .rtk/trust.json بعد المراجعة فقط.

---

مستويات الشدة (v3.8.16+)

يدعم RTK 3 مستويات للشدة تحقق توازنًا بين قوة الضغط والأمان. يُضبط المستوى عبر config.intensity في إعدادات المحرك.

المستويات الثلاثة

المستوى	حد الاقتطاع	توفير الرموز	المخاطر	الأنسب لـ
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": "my-coding-combo",
  "routing": {/* ... */},
  "compression": {
    "engine": "rtk",
    "intensity": "aggressive"
  }
}

برمجيًا:

إن rtkEngine ‏(@omniroute/open-sse/services/compression/engines/rtk) هو CompressionEngine ولا يملك دالة updateConfig. حدّث إعدادات المحرك عبر أداة السجل المساعدة بدلًا من ذلك:

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("فشلت المرشّحات عند مستوى الشدة aggressive");
}

---

تطوير عوامل تصفية مخصصة (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"],            // أنماط التعبيرات النمطية لمطابقة المخرجات
    "outputTypes": ["string"]          // فئات المخرجات المكتشفة (مثل "test-failure")
  },
  "rules": {
    "stripAnsi": boolean,              // اختياري (القيمة الافتراضية: false). إزالة رموز ألوان ANSI
    "replace": [                       // قواعد البحث والاستبدال (القيمة الافتراضية: [])
      { "pattern": "regex", "replacement": "..." }
    ],
    "matchOutput": [                   // إيقاف المعالجة عند مطابقة النمط (القيمة الافتراضية: [])
      {
        "pattern": "regex",
        "message": "short summary",
        "unless": "regex"              // التجاوز إذا تطابق هذا النمط
      }
    ],
    "includePatterns": ["string"],     // الأسطر التي يجب الاحتفاظ بها (أنماط تعبيرات نمطية، القيمة الافتراضية: [])
    "dropPatterns": ["string"],        // الأسطر التي يجب حذفها (أنماط تعبيرات نمطية، القيمة الافتراضية: [])
    "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"    // اختياري. سياق الأمر
    }
  ]
}

مثال: عامل تصفية Python 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)

تمكين تخزين المخرجات الأولية

لكل طلب (في إعدادات combo):

{
  "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/يوم	500MB-5GB/يوم

التوصية: فعّل المخرجات الأولية فقط أثناء جلسات تصحيح الأخطاء أو التدقيق بأخذ عينات، وليس بصورة دائمة.

استعادة النص الأصلي

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[] الخاصة بها، ويضمن صحة السلوك عند مستويات الشدة الثلاثة جميعها.

استدعِ 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/ (63 ملفًا، ~70KB)