OmniRoute/docs/i18n/hy/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 · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇮🇩 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-ի՝ հրամանները հաշվի առնող սեղմման շարժիչն է տերմինալի և գործիքների ելքի համար։ Այն նախատեսված է ծրագրավորման գործակալների աշխատաշրջանների համար, որտեղ համատեքստի աճի մեծ մասը պայմանավորված է թեստերի մատյաններով, կառուցման ելքով, փաթեթների կառավարիչների աղմուկով, shell-ի հրամանագրություններով, 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, ընդհանուր shell մատյաններ
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 schema 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 schema v1-ի հետ

OmniRoute-ը կարող է վերլուծել, վավերացնել, թեստավորել և տեղադրել հայտարարագրային զտիչների ֆայլեր՝ օգտագործելով RTK TOML schema 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 schema v1-ի հետ, այլ ոչ թե լիարժեք համատեղելիություն RTK գործարկելի ֆայլի, shell hook-երի, Rust հրամանների իրականացումների կամ դրա վստահության պահոցի կառուցվածքի հետ։

Վահանակի ընդլայնված RTK տեսքը ընդունում է տեղադրված կամ վերբեռնված TOML։ Վավերացումը միայն ընթերցման համար է։ Տեղադրումը սահմանափակ թույլտվություններով ատոմար կերպով գրում է DATA_DIR/rtk/filters.toml ֆայլը և առանց վերագործարկման թարմացնում է ակտիվ զտիչների կատալոգը։ Գոյություն ունեցող ֆայլը փոխարինելու համար պահանջվում է overwrite-ի բացահայտ հաստատում, և նախ ստեղծվում է DATA_DIR/rtk/filters.toml.bak ֆայլը։

Զտիչների DSL

Զտիչներն օգտագործում են Compression Rules Format-ում նկարագրված 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-ի կառուցվածքային համարժեքն է. կրկնօրինակների հեռացումը մշակում է ճշգրիտ կրկնությունները, իսկ խմբավորումը՝ «նույն կառուցվածքը փոքր տարբերություններով»։ Երկու դրոշներն էլ key_value աղյուսակում պահպանվող rtkConfig JSON-ի մասն են (տե՛ս վերևում՝ Կազմաձևում), ուստի կարգավորումը պահպանվում է վերագործարկումներից հետո։

Կոդի մեկնաբանությունների հեռացում (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) կատարվում է դատարկ տողերի և բացատների միավորում, բայց ոչ մեկնաբանությունների հեռացում։ Մշակված բլոկի գործարկումը rulesApplied-ում նշագրվում է rtk:code-strip պիտակով։

Նշում — GCF / աղյուսակային կոդավորումն առանձին շարժիչ է։ RTK-ն չի պարունակում «GCF» (Graph Compact Format) աղյուսակային/սյունակային JSON կոդավորիչը։ Այդ կոդավորիչը, որը փոխարինել է ավելի հին 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 schema 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/

Գաղտնի տվյալները հեռացվում են նախքան պահպանումը՝ ներառյալ տարածված bearer տոկենները, API բանալիները, Slack-ի տոկենները, AWS-ի հասանելիության բանալիները և վերագրման ձևաչափով token=..., secret=..., password=... արժեքները։ Վերլուծական տվյալներում պահվում են միայն ցուցիչի id-ն, չափը և հեշի մետատվյալները։

Ստուգման անցակետ

Նպատակային ստուգման անցակետը գործարկում է ներկառուցված ներկցված զտիչների թեստերը՝ առանց արտաքին հրամաններ կանչելու.

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-ի միջոցով։

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 մեթոդ։ Փոխարենը թարմացրեք շարժիչի կազմաձևը ռեեստրի օժանդակ ֆունկցիայի միջոցով.

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      # Նախագծի մակարդակ

Զտիչներն ավտոմատ բեռնվում են գործարկման ժամանակ՝ open-sse/services/compression/engines/rtk/filterLoader.ts-ում գտնվող loadRtkFilters()-ի միջոցով։ Բեռնիչը զտիչները հայտնաբերում է հետևյալ աղբյուրներից․

• Ներկառուցված կատալոգ՝ 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 թոքեն)     ──▶ պահվում է 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/օր	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[]-ի, և հավաստիանում, որ վարքագիծը ճիշտ է ինտենսիվության բոլոր 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)