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

RTK Compression (עברית)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇳 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 יש קדימות על פני מסנני 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 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 והפניות למסננים לא מוכרים נדחים. קובץ שהבדיקות המשובצות שלו נכשלות ניתן לאמת לצורך בדיקה, אך לא ניתן להתקין או לטעון אותו. כשלים בטעינת קבצים מותאמים אישית ממשיכים לפעול במצב fail-open: הקובץ הלא תקין מדולג, והמסננים הנותרים ממשיכים לפעול.

OmniRoute מקבל את פלט הכלי לאחר שהלקוח כבר לכד אותו, ולכן filter_stderr = true אינו יכול לשנות את לכידת התהליך. השדה מתקבל ללא השפעה, והאימות מחזיר אזהרה. תכונה זו מתוארת במכוון כתאימות לסכמת RTK TOML v1, ולא כתאימות מלאה לקובץ ההפעלה RTK, ל-shell hooks, למימושי פקודות Rust או למבנה מאגר האמון שלו.

התצוגה המתקדמת של RTK בלוח המחוונים מקבלת TOML שהודבק או הועלה. האימות מיועד לקריאה בלבד. ההתקנה כותבת את DATA_DIR/rtk/filters.toml באופן אטומי עם הרשאות מגבילות, ומרעננת את קטלוג המסננים הפעיל ללא הפעלה מחדש. החלפת קובץ קיים דורשת אישור overwrite מפורש, ויוצרת תחילה את DATA_DIR/rtk/filters.toml.bak.

DSL למסננים

המסננים משתמשים בסכמת JSON המתוארת ב-פורמט כללי דחיסה. סביבת הריצה מחילה את השלבים הבאים לפי הסדר:

stripAnsi -> filterStderr -> replace -> matchOutput -> drop/include lines
  -> 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/, כאשר ה-codec המצורף נמצא תחת 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-key תואמת.

מטען אימות 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/

סודות מושחרים לפני השמירה, לרבות אסימוני 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. הוסיפו קיבוע תחת tests/unit/compression/fixtures/rtk/ עבור משפחות פקודות חדשות.
4. הוסיפו כיסוי לזיהוי פקודות בעת הוספת מחלקת פלט חדשה.
5. הריצו את שערי האימות ואת שערי RTK הרחבים.
6. אם המסנן מקומי לפרויקט, בצעו commit ל-.rtk/filters.json ורעננו את .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": "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("המסננים נכשלו בעוצמה אגרסיבית");
}

---

פיתוח מסננים מותאמים אישית (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"    // אופציונלי. הקשר הפקודה
    }
  ]
}

דוגמה: מסנן Traceback של Python

{
  "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. בדקו בכל 3 רמות העוצמה — minimal אמורה לא לבצע שום שינוי, ו-aggressive אמורה עדיין לשמר שגיאות
5. השתמשו בשדה unless — הגנו על קיצורי דרך באמצעות "אל תפעילו אם X קיים"

---

שחזור פלט גולמי ושער אימות

כאשר RTK דוחס פלט באופן אגרסיבי, ניתן לשחזר את הטקסט המקורי לצורך ניפוי שגיאות, ביקורת או הפעלה חוזרת.

כיצד פועל שחזור פלט גולמי

פלט מקורי (10K טוקנים)
        │
        ▼
דחיסת RTK (עם rawOutput.enabled=true)
        │
        ├─▶ פלט דחוס (2K טוקנים)  ──▶ אל ה-LLM
        │
        └─▶ פלט מקורי (10K טוקנים)   ──▶ מאוחסן במסד הנתונים
                                                  (מקושר באמצעות 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/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/ (63 קבצים, כ־70KB)