OmniRoute/docs/i18n/hy/docs/architecture/CODEBASE_DOCUMENTATION.md

CODEBASE_DOCUMENTATION (Հայերեն)

🌐 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

---

---

title: "OmniRoute կոդային բազայի փաստաթղթեր" version: 3.8.40 lastUpdated: 2026-06-28

OmniRoute կոդային բազայի փաստաթղթեր

Տարբերակ՝ v3.8.51 Վերջին թարմացումը՝ 2026-06-28 Թիրախային լսարան՝ OmniRoute-ում ներդրում կատարող կամ դրա հիման վրա ինտեգրումներ կառուցող ինժեներներ։

Բարձր մակարդակի ճարտարապետական գծապատկերների և յուրաքանչյուր ենթահամակարգի հիմքում ընկած հիմնավորումների համար կարդացեք ARCHITECTURE.md։ Առանձին ենթահամակարգերի մանրամասն նկարագրությունների համար (Auto Combo, MCP սերվեր, A2A սերվեր, Skills, Memory, Cloud Agents, Resilience, Compression և այլն) տե՛ս այս docs/ գրացուցակի դրանց նվիրված ֆայլերը։

Այս ֆայլը նկարագրում է, թե ինչ կա պահոցում այսօր, որպեսզի նոր ինժեները կարողանա կողմնորոշվել ծառում, հասկանալ կատարման միջավայրի շերտավորումը և իմանալ, թե որտեղ ավելացնել կոդ՝ առանց նոր մոդուլներ հորինելու։

---

1. Տեխնոլոգիական փաթեթ

Բաղադրիչ	Ընտրություն
Վեբ-ֆրեյմվորք	Next.js 16 (App Router, ինքնուրույն ելքային կառուցվածք, առանց գլոբալ միջնաշերտի)
Լեզու	TypeScript 6.0+ — թիրախ՝ ES2022, module: esnext, moduleResolution: bundler, strict: false
Կատարման միջավայր	Node.js >=22.22.2 <23 կամ >=24.0.0 <27 (պարտադրվում է engines + SUPPORTED_NODE_RANGE-ի միջոցով)
Տվյալների բազա	SQLite՝ better-sqlite3-ի միջոցով (միակ օրինակ, WAL մատենավարում)
Սեղանադիր հավելված	Electron 41 + electron-builder 26.10 (առանձին աշխատանքային տարածք՝ electron/)
Թեստեր	Node-ի ներկառուցված թեստային գործարկիչ (մոդուլային/ինտեգրացիոն), Vitest (MCP, autoCombo, քեշ), Playwright (e2e + protocols-e2e)
Կառուցում	Next.js-ի ինքնուրույն կառուցվածք՝ scripts/build/build-next-isolated.mjs-ի միջոցով
Լինտինգ/ձևաչափում	ESLint-ի հարթ կազմաձև + Prettier (lint-staged՝ Husky pre-commit-ի միջոցով)
Մոդուլային համակարգ	Ամենուր ESM ("type": "module")
Աշխատանքային տարածքներ	npm աշխատանքային տարածք — open-sse-ն միակ ենթաաշխատանքային տարածքն է

Ուղիների կեղծանուններ (tsconfig.json)՝

• @/* → src/*
• @omniroute/open-sse → open-sse/index.ts
• @omniroute/open-sse/* → open-sse/*

Լռելյայն HTTP պորտը՝ 20128 (API-ն և կառավարման վահանակն օգտագործում են նույն գործընթացը)։ Տվյալների գրացուցակը սահմանվում է DATA_DIR միջավայրի փոփոխականով, իսկ լռելյայն արժեքը ~/.omniroute/ է։

---

2. Պահոցի կառուցվածքը

OmniRoute/
├── src/                  Next.js հավելված (App Router, գրադարաններ, տիրույթ, սերվեր, համօգտագործվող բաղադրիչներ)
├── open-sse/             Հոսքային մշակման շարժիչի աշխատանքային տարածք (@omniroute/open-sse)
├── electron/             Սեղանադիր պատյան (Electron 41-ի հիմնական գործընթաց + preload)
├── bin/                  CLI մուտքի կետեր (omniroute, reset-password)
├── tests/                Մոդուլային, ինտեգրացիոն, e2e, protocols-e2e, թարգմանիչի, անվտանգության թեստեր և ֆիքստուրաներ
├── scripts/              Կառուցման, համաժամացման, ստուգման, միգրացիայի և կատարման միջավայրի օժանդակ սկրիպտներ
├── docs/                 Հանրային փաստաթղթեր (այս գրացուցակը)
├── public/               Ստատիկ ռեսուրսներ, PWA մանիֆեստ, սպասարկող աշխատիչ
├── config/               Կատարման միջավայրի կազմաձևման օրինակներ
├── images/               Մարքեթինգային նյութեր/էկրանի պատկերներ
├── _ideia/, _references/, _mono_repo/, _tasks/   Ներքին սևագրեր / պլանավորում (չեն մատակարարվում)
├── CLAUDE.md             Պահոցի կանոններ Claude Code-ի համար
├── AGENTS.md             Գործակալների համար ավելի մանրամասն ճարտարապետական տեղեկատու
├── package.json          v3.8.51, աշխատանքային տարածքի արմատ
└── tsconfig.json         Ուղիների կեղծանուններ + կոմպիլյատորի հիմնական ընտրանքներ

---

3. src/ — Next.js հավելված

src/
├── app/                  App Router-ի էջեր + API երթուղիներ
├── lib/                  Հիմնական գրադարաններ (ՏԲ, նույնականացում, OAuth, հմտություններ, հիշողություն, …)
├── domain/               Մաքուր տիրույթային շերտ (քաղաքականություն, պահուստային անցում, ծախս, արգելափակում, …)
├── server/               Միայն սերվերի համար նախատեսված մոդուլներ (լիազորում, cors, նույնականացում)
├── shared/               Տիպեր, հաստատուններ, վավերացում, պայմանագրեր, օգտակար գործիքներ (անվտանգ՝ սահմանների միջև օգտագործման համար)
├── mitm/                 «Մարդը մեջտեղում» պրոքսիի օժանդակ գործիքներ՝ CLI ինտեգրման համար
├── models/               Տեղական մոդելների մետատվյալներ / այլանուններ
├── sse/                  Ժառանգական SSE մշակիչներ, որոնք դեռ գտնվում են src/-ում (ոչ թե open-sse/-ում)
├── store/                Հաճախորդային կողմի վիճակի պահոցներ
├── middleware/           Երթուղու մակարդակի middleware օգտակար գործիքներ (ոչ Next.js-ի գլոբալ middleware)
├── scripts/              Հավելվածի կոդից ներմուծելի՝ ծառի ներսում գտնվող սկրիպտներ
├── types/                Միջավայրային և համօգտագործվող TS տիպեր
├── i18n/                 Տեղայնացման փաթեթներ
├── instrumentation.ts    Next.js-ի գործիքավորման hook
├── instrumentation-node.ts
└── proxy.ts              Վերին մակարդակի պրոքսիի սկզբնագործման օժանդակ գործիք

3.1 src/app/ — App Router

App Router-ը տրամադրում է և՛ կառավարման վահանակի UI-ը, և՛ հանրային/կառավարման HTTP API-ն։ Գլոբալ middleware չկա․ հարցումների միջամտությունն իրականացվում է յուրաքանչյուր երթուղու համար առանձին։

src/app/-ի վերին մակարդակի հատվածները՝

Ուղի	Նպատակ
api/	Բոլոր HTTP API երթուղիները (տե՛ս ստորև ներկայացված բաժանումը)
a2a/	A2A JSON-RPC 2.0 վերջնակետ (POST /a2a)
.well-known/agent.json/	A2A Agent Card-ի հայտնաբերման փաստաթուղթ
(dashboard)/	Կառավարման վահանակի UI (երթուղիների խումբ, առանց URL նախածանցի)
auth/, login/, forgot-password/, callback/	Նույնականացման հոսքեր
landing/	Մարքեթինգային/մուտքային էջ
docs/	Ներկառուցված API փաստաթղթերի դիտիչ
status/, maintenance/, offline/	Շահագործման էջեր
privacy/, terms/	Իրավական էջեր
400/, 401/, 403/, 408/, 429/, 500/, 502/, 503/	Ստատիկ սխալի էջեր
error.tsx, global-error.tsx, not-found.tsx, forbidden/, loading.tsx	Ֆրեյմվորքի սխալների/բեռնման սահմաններ
layout.tsx, page.tsx, globals.css, manifest.ts	Արմատային պատյան

3.1.1 src/app/(dashboard)/dashboard/ — UI էջեր

agents, analytics, api-manager, audit, auto-combo, batch, cache, changelog, cli-tools, cloud-agents, combos, compression, context, costs, endpoint, health, limits, logs, memory, onboarding, playground, providers, search-tools, settings, skills, system, translator, usage, webhooks, ինչպես նաև արմատային page.tsx, HomePageClient.tsx, BootstrapBanner.tsx։

3.1.2 src/app/api/ — Վերին մակարդակի API խմբեր

src/app/api/
├── a2a/{status, tasks}
├── acp/
├── admin/
├── analytics/
├── assess/
├── auth/
├── batches/
├── cache/
├── cli-tools/
├── cloud/{codex-responses-ws}
├── combos/
├── compliance/
├── compression/
├── context/
├── db/, db-backups/
├── evals/
├── fallback/
├── files/
├── health/
├── init/
├── internal/{concurrency}
├── keys/
├── logs/
├── mcp/{audit, sse, status, stream, tools}
├── memory/{health, [id]/, route.ts}
├── model-combo-mappings/
├── models/
├── monitoring/
├── oauth/
├── openapi/
├── policies/
├── pricing/
├── provider-metrics/, provider-models/, provider-nodes/
├── providers/
├── rate-limit/, rate-limits/
├── resilience/
├── restart/, shutdown/
├── search/
├── sessions/
├── settings/
├── skills/{executions, [id], install, marketplace, route.ts, skillssh}
├── storage/
├── sync/, synced-available-models/
├── system/
├── tags/
├── telemetry/
├── token-health/
├── translator/
├── tunnels/
├── services/   Ներկառուցված ծառայությունների կառավարում (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         OpenAI-ի հետ համատեղելի հանրային API
├── v1beta/     Gemini ոճի համատեղելիություն
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — Ներկառուցված ծառայությունների կառավարում

9Router-ը և CLIProxyAPI-ն տեղադրելու, գործարկելու, կանգնեցնելու և վերահսկելու երթուղիներ։ Բոլոր ուղիները դասակարգված են որպես LOCAL_ONLY (միայն loopback, խիստ կանոն #17), քանի որ դրանք կարող են կանչել npm install և ստեղծել ենթապրոցեսներ։

src/app/api/services/
├── 9router/
│   ├── _lib.ts             getOrInitSupervisor() օժանդակ ֆունկցիա
│   ├── install/route.ts    POST — npm install՝ execFile-ի միջոցով
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — npm install՝ ավելի նոր տարբերակի համար
│   ├── rotate-key/route.ts POST — ստեղծել նոր API բանալի + վերագործարկել
│   ├── status/route.ts     GET  — ընթացիկ + DB կարգավիճակ + տարբերակի մետատվյալներ
│   └── auto-start/route.ts POST — փոխարկել auto_start դրոշակը
├── cliproxy/
│   ├── _lib.ts             getOrInitSupervisor() օժանդակ ֆունկցիա
│   ├── install/route.ts    POST — npm install
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — npm install՝ ավելի նոր տարբերակի համար
│   ├── status/route.ts     GET  — ընթացիկ + DB կարգավիճակ + տարբերակի մետատվյալներ
│   └── auto-start/route.ts POST — փոխարկել auto_start դրոշակը
└── [name]/
    └── logs/route.ts       GET  — SSE մատյանի վերջնամասը (ընդհանուր է բոլոր ծառայությունների համար)

Համապատասխան կառավարման վահանակի UI-ը՝ src/app/(dashboard)/dashboard/providers/services/ — երկու ներդիրով էջ (CLIProxyAPI + 9Router)։ Հակադարձ պրոքսի՝ 9Router-ի ներկառուցված UI-ի համար՝ src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

Մանրամասն նկարագրություն՝ docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — OpenAI-ի հետ համատեղելի հանրային API

v1/
├── accounts/[id]/                       հաշվի որոնում
├── agents/tasks/[id]/, agents/tasks/    A2A ոճով առաջադրանքների վերջնակետեր
├── api/                                 ներքին API-ի օժանդակ գործիքներ՝ հասանելի v1/api-ի ներքո
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    Chat Completions (հիմնական վերջնակետը)
├── completions/                         հնացած տեքստային լրացումներ
├── embeddings/                          վեկտորային ներկայացումներ
├── files/[id]/, files/                  Files API
├── _helpers/                            երթուղիների ընդհանուր օժանդակ գործիքներ (հանրային URL չկա)
├── images/{edits, generations}/         պատկերների ստեղծում + խմբագրում
├── issues/                              խնդիրների տեսակավորման օժանդակ վերջնակետեր
├── management/{proxies}/                կառավարման շրջանակով երթուղիներ v1-ի ներսում
├── messages/{count_tokens}/             Anthropic ոճի հաղորդագրությունների համատեղելիություն
├── models/                              մոդելների ցանկ (`route.ts`, `catalog.ts`)
├── moderations/                         բովանդակության ստուգում
├── music/                               երաժշտության ստեղծում
├── providers/[provider]/                յուրաքանչյուր մատակարարի գործողություններ
├── quotas/{check}                       քվոտաների ստուգումներ
├── registered-keys/                     գրանցված բանալիների կառավարում
├── rerank/                              վերադասակարգում
├── responses/[...path]/                 OpenAI Responses API (բոլոր երթուղիներն ընդգրկող)
├── search/                              վեբ որոնում
├── videos/                              տեսանյութերի ստեղծում
├── ws/                                  WebSocket կամուրջ
└── route.ts                             ինդեքսային մշակիչ

Յուրաքանչյուր երթուղու ֆայլ հետևում է նույն ձևանմուշին՝

Երթուղի → CORS նախնական հարցում → Zod-ով մարմնի վավերացում → ընտրովի նույնականացում
        → API բանալու քաղաքականության կիրառում → փոխանցում մշակիչին (open-sse)

v1beta/-ն Gemini ոճի համատեղելիության մակերեսն է (բարակ փաթեթիչ, որը փոխակերպում է հարցումները՝ նույն open-sse/handlers/ մշակման շղթան փոխանցելու համար)։

3.2 src/lib/ — Հիմնական գրադարաններ

Տվյալները, համաժամացումը, OAuth-ը, հմտությունները, հիշողությունը և այլն միշտ ներմուծեք այս մոդուլների միջոցով։ Ստորև բերված աղյուսակը խմբավորում է իրական գրացուցակները և վերին մակարդակի ուշագրավ ֆայլերը։

Մոդուլ	Նպատակ
a2a/	A2A արձանագրության սերվեր՝ taskManager.ts, streaming.ts, taskExecution.ts, routingLogger.ts, skills/ (6 հմտություն՝ ծախսերի վերլուծություն, վիճակի հաշվետվություն, մատակարարների հայտնաբերում, քվոտաների կառավարում, խելացի երթուղավորում, հնարավորությունների ցանկ)
acp/	Agent-Control-Protocol՝ index.ts, manager.ts, registry.ts
api/	Ներքին API-ի օժանդակ գործիքներ՝ requireManagementAuth.ts, requireCliToolsAuth.ts, errorResponse.ts
auth/	managementPassword.ts (գաղտնաբառի վերակայում / հեշավորում)
batches/	OpenAI Batches API ծառայություն (service.ts)
catalog/	OpenRouter կատալոգի համաժամացում (openrouterCatalog.ts)
cloudAgent/	Ամպային գործակալների ռեեստր՝ api.ts, baseAgent.ts, db.ts, index.ts, registry.ts, types.ts, agents/{codex, devin, jules}.ts
combos/	Համակցությունների որոշման օժանդակ գործիքներ
compliance/	Աուդիտ + մատակարարի աուդիտ՝ index.ts, providerAudit.ts
config/	Կատարման միջավայրի կազմաձևման կապակցող շերտ
db/	SQLite տիրույթային մոդուլներ (տե՛ս §3.2.1)
display/	API պատասխաններում օգտագործվող UI/արտապատկերման օժանդակ գործիքներ
embeddings/	Ներդրումների ծառայության ռեեստր
env/	Միջավայրի բեռնում + ինքնազննում
evals/	Գնահատումների կատարման միջավայր
guardrails/	piiMasker.ts, promptInjection.ts, visionBridge.ts, visionBridgeHelpers.ts, registry.ts, base.ts
jobs/	Ֆոնային առաջադրանքներ (autoUpdate.ts, …)
memory/	Մշտական հիշողություն՝ store.ts, cache.ts, retrieval.ts, summarization.ts, extraction.ts, injection.ts, qdrant.ts, settings.ts, verify.ts, schemas.ts, types.ts
monitoring/	observability.ts
oauth/	OAuth/մատակարարների ներմուծման մոդուլներ (22)՝ agy, antigravity, claude, cline, codebuddy-cn, codex, cursor, devin-desktop, ghe-copilot, github, gitlab-duo, grok-cli-oauth, grok-cli, kilocode, kimi-coding, kiro, openference, qoder, trae, xai-oauth, zed-hosted, zed, ինչպես նաև services/, utils/ և constants/oauth.ts
plugins/	Փլագինների բեռնիչ (index.ts)
promptCache/	prefixAnalyzer.ts, index.ts
providerModels/	Կառավարվող մոդելների կենսափուլ՝ modelDiscovery.ts, managedModelImport.ts, managedAvailableModels.ts, cursorAgent.ts
providers/	Մատակարարների օժանդակ գործիքներ՝ catalog.ts, validation.ts, imageValidation.ts, claudeExtraUsage.ts, codexConnectionDefaults.ts, codexFastTier.ts, webCookieAuth.ts, managedAvailableModels.ts, requestDefaults.ts
resilience/	settings.ts — շղթայի անջատիչի, սառեցման ժամանակահատվածի և արգելափակման կարգավորումներ
runtime/	Կատարման միջավայրի հնարավորությունների հայտնաբերում
search/	executeWebSearch.ts
services/	Ներկառուցված ծառայությունների ֆրեյմվորք՝ ServiceSupervisor.ts (ենթագործընթացների ընդհանրացված վերահսկիչ՝ գործողության կողպմամբ, օղակաձև բուֆերով և վիճակի ստուգիչով), bootstrap.ts (գործընթացի մակարդակի գրանցում և ինքնաշխատ մեկնարկ), registry.ts (գործիք → վերահսկիչ քարտեզ), apiKey.ts (AES-256-GCM բանալիների պահոց), modelSync.ts (մոդելների պարբերական համաժամացում), ringBuffer.ts (5 MB օղակաձև մատյանային բուֆեր), healthCheck.ts (HTTP վիճակի զոնդ), types.ts, embedWsProxy.ts (WebSocket պրոքսի), installers/{ninerouter,cliproxy}.ts։ Տե՛ս docs/frameworks/EMBEDDED-SERVICES.md
agentSkills/	Գործակալների հմտությունների կատալոգ + գեներատոր՝ catalog.ts (getCatalog/getSkillById/filterCatalog/computeCoverage), generator.ts (generateAgentSkills → գրում է skills/{id}/SKILL.md), openapiParser.ts (OpenAPI բնութագրից արդյունահանում է REST վերջնակետերը), cliRegistryParser.ts (bin/cli-registry-ից արդյունահանում է CLI ենթահրամանները), schemas.ts (Zod՝ AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), types.ts (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport)։ Օգտագործվում է REST երթուղիների (/api/agent-skills/*), MCP գործիքների (omniroute_agent_skills_*) և A2A list-capabilities հմտության կողմից։ Տե՛ս AGENT-SKILLS.md։
skills/	Հմտությունների ֆրեյմվորք՝ registry.ts, executor.ts, interception.ts, injection.ts, sandbox.ts, custom.ts, hybrid.ts, builtins.ts, a2a.ts, providerSettings.ts, schemas.ts, skillssh.ts, types.ts, ինչպես նաև builtin/browser.ts
spend/	batchWriter.ts (հետաձգված գրանցման բուֆեր)
sync/	bundle.ts, tokens.ts (Cloud Sync)
system/	Համակարգային մակարդակի օժանդակ գործիքներ
translator/	Վերին մակարդակի թարգմանիչի կապակցող շերտ (պատվիրակում է open-sse/translator/-ին)
usage/	Օգտագործման հաշվառում՝ costCalculator.ts, tokenAccounting.ts, usageHistory.ts, aggregateHistory.ts, usageStats.ts, callLogs.ts, callLogArtifacts.ts, fetcher.ts, providerLimits.ts, migrations.ts
versionManager/	Ինքնաշխատ թարմացում + տարբերակի մանիֆեստ
ws/	WebSocket կամուրջ
zed-oauth/	Zed խմբագրիչի OAuth հոսք

src/lib/-ի վերին մակարդակի ֆայլերը՝

• Հին localDb.ts barrel ֆայլը հեռացվել է. սպառողները ներմուծում են կոնկրետ src/lib/db/* մոդուլները՝ անմիջապես։
• proxyHealth.ts, proxyLogger.ts, tokenHealthCheck.ts, localHealthCheck.ts
• apiBridgeServer.ts, cacheLayer.ts, semanticCache.ts, settingsCache.ts
• cloudSync.ts, initCloudSync.ts
• cloudflaredTunnel.ts, ngrokTunnel.ts, tailscaleTunnel.ts
• consoleInterceptor.ts, container.ts, gracefulShutdown.ts, idempotencyLayer.ts
• ipUtils.ts, logEnv.ts, logPayloads.ts, logRotation.ts
• modelAliasSeed.ts, modelCapabilities.ts, modelMetadataRegistry.ts, modelsDevSync.ts
• piiSanitizer.ts, pricingSync.ts
• apiKeyExposure.ts, cacheControlSettings.ts, dataPaths.ts, toolPolicy.ts
• translatorEvents.ts, usageDb.ts, usageAnalytics.ts, webhookDispatcher.ts

3.2.1 src/lib/db/

SQLite տվյալների բազայի մեկ օրինակ (getDbInstance()՝ core.ts-ում, WAL գրանցամատյանային ռեժիմ)։ Երբեք մի գրեք չմշակված SQL երթուղիներում կամ մշակիչներում. օգտագործեք այս մոդուլները։

Աղբյուր՝ diagrams/db-schema-overview.mmd

Տիրույթային մոդուլներ (յուրաքանչյուրը կառավարում է մեկ կամ մի քանի աղյուսակ)՝ apiKeys.ts, backup.ts, batches.ts, cleanup.ts, cliToolState.ts, combos.ts, commandCodeAuth.ts, compression.ts, compressionAnalytics.ts, compressionCacheStats.ts, compressionCombos.ts, compressionScheduler.ts, contextHandoffs.ts, core.ts, creditBalance.ts, databaseSettings.ts, detailedLogs.ts, domainState.ts, encryption.ts, evals.ts, files.ts, healthCheck.ts, jsonMigration.ts, migrationRunner.ts, modelComboMappings.ts, models.ts, oneproxy.ts, prompts.ts, providers.ts, providerLimits.ts, proxies.ts, quotaSnapshots.ts, readCache.ts, reasoningCache.ts, registeredKeys.ts, secrets.ts, sessionAccountAffinity.ts, settings.ts, stateReset.ts, stats.ts, syncTokens.ts, tierConfig.ts, upstreamProxy.ts, versionManager.ts, webhooks.ts։

migrations/-ը պարունակում է տարբերակավորված 168 .sql ֆայլ (իդեմպոտենտ, տրանզակցիոն), և դրանք բեռնման պահին կատարվում են migrationRunner.ts-ի միջոցով։

Միգրացիաների ընթացքում ստեղծվող աղյուսակները (ընդհանուր՝ 123)՝

a, account_key_limits, api_keys, batches, call_logs, combo_adaptation_state, combos, command_code_auth_sessions, compression_analytics, compression_cache_stats, compression_combo_assignments, compression_combos, context_handoffs, daily_usage_summary, db_meta, domain_budgets, domain_circuit_breakers, domain_cost_history, domain_fallback_chains, domain_lockout_state, eval_cases, eval_runs, eval_suites, files, hourly_usage_summary, key_value, mcp_tool_audit, memories, model_combo_mappings, provider_connections, provider_key_limits, provider_nodes, proxy_assignments, proxy_logs, proxy_registry, quota_snapshots, reasoning_cache, registered_keys, request_detail_logs, routing_decisions, semantic_cache, session_account_affinity, skill_executions, skills, sync_tokens, tier_assignments, tier_config, upstream_proxy_config, usage_history, version_manager, webhooks (գումարած FTS5 վիրտուալ աղյուսակներ՝ հիշողության որոնման համար)։

3.3 src/domain/ — Տիրույթային շերտ

Մաքուր բիզնես տրամաբանություն՝ առանց I/O-ի։ Ներմուծվում է երթուղիների և մշակիչների կողմից։

Ֆայլ	Նպատակ
policyEngine.ts	Վերին մակարդակի քաղաքականության լուծիչ
fallbackPolicy.ts	Պահուստային տարբերակի որոշումների ծառ
costRules.ts	Արժեքի հաշվարկման կանոններ
lockoutPolicy.ts	Մոդելի արգելափակման որոշումներ
tagRouter.ts	Պիտակների վրա հիմնված երթուղավորում
comboResolver.ts	Համակցության որոշում՝ հարցումից → թիրախների ցանկ
connectionModelRules.ts	Յուրաքանչյուր կապի մոդելային զտիչներ
modelAvailability.ts	Մոդելի հասանելիության ստուգում
degradation.ts	Դեգրադացված ռեժիմի անցումներ
providerExpiration.ts	Ժամկետանց հաշիվների/բանալիների հայտնաբերում
quotaCache.ts	Քվոտայի քեշավորված որոշումներ
responses.ts, omnirouteResponseMeta.ts	Պատասխանի կառուցվածքի օժանդակ գործառույթներ
configAudit.ts	Կազմաձևի փոփոխությունների աուդիտ
assessment/	Մոդելի գնահատում (ըստ RFC-ի, մասամբ իրականացված)
types.ts	Համօգտագործվող տիրույթային տիպեր

3.4 src/server/ — Միայն սերվերի համար

Չի կարող ներմուծվել հաճախորդային բաղադրիչներից։

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Դասակարգում է երթուղիները որպես հանրային կամ կառավարման
│   ├── assertAuth.ts      Հաստատման օժանդակ գործառույթ
│   ├── context.ts         Յուրաքանչյուր հարցման authz համատեքստ
│   ├── headers.ts
│   ├── pipeline.ts        Authz մշակման շղթա
│   ├── policies/          Կոնկրետ քաղաքականություններ
│   └── types.ts
└── cors/origins.ts        CORS սկզբնաղբյուրների թույլատրելի ցանկ

3.5 src/shared/ — Անվտանգ համօգտագործման համար

Բաժանված է նեղ նպատակային ենթագրացուցակների՝

• constants/ — providers.ts (Zod-ով վավերացվող մատակարարների կատալոգ), models.ts, modelSpecs.ts, modelCompat.ts, pricing.ts, cliTools.ts, cliCompatProviders.ts, routingStrategies.ts, comboConfigMode.ts, headers.ts, upstreamHeaders.ts (արգելացուցակ), mcpScopes.ts, errorCodes.ts, publicApiRoutes.ts, batch.ts, batchEndpoints.ts, bodySize.ts, colors.ts, appConfig.ts, config.ts, sidebarVisibility.ts, visionBridgeDefaults.ts.
• validation/ — schemas.ts (~80 Zod սխեմա), compressionConfigSchemas.ts, providerSchema.ts, settingsSchemas.ts, helpers.ts.
• contracts/ — npm-ում հրապարակվող հանրային API պայմանագրեր։
• types/ — համօգտագործվող TS տիպեր։
• utils/ — circuitBreaker.ts, apiAuth.ts, apiKey.ts, apiKeyPolicy.ts, api.ts, classify429.ts, cliCompat.ts, clipboard.ts, cloud.ts, cn.ts, cors.ts, featureFlags.ts, fetchTimeout.ts, formatting.ts, inputSanitizer.ts, logger.ts, machine.ts, machineId.ts, maskEmail.ts, modelCatalogSearch.ts, nodeRuntimeSupport.ts, parseApiKeys.ts, providerHints.ts, providerModelAliases.ts, rateLimiter.ts, releaseNotes.ts, a11yAudit.ts, ինչպես նաև կառավարման վահանակի հուկեր/բաղադրիչներ՝ services/, network/, middleware/, schemas/, hooks/, components/ պանակներում։

---

4. open-sse/ — Հոսքային շարժիչի աշխատանքային տարածք

Առանձին npm աշխատանքային տարածք, որը հրապարակվում է որպես @omniroute/open-sse։ Պատասխանատու է հարցումների մշակման, կատարիչների, թարգմանիչների, ծառայությունների, փոխակերպիչի և MCP սերվերի համար։

open-sse/
├── index.ts                Հանրային արտահանումներ
├── package.json            Աշխատանքային տարածքի մանիֆեստ
├── tsconfig.json
├── types.d.ts
├── config/                 Մատակարարների ռեեստրներ, վերնագրերի պրոֆիլներ, ինքնություն, …
├── handlers/               Հարցումների մշակիչներ (զրույց, ներդրումներ, աուդիո, պատկեր, …)
├── executors/              Մատակարարներին հատուկ 108 HTTP կատարիչ
├── translator/             Ձևաչափերի փոխակերպում (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Responses API ↔ Chat Completions հոսքի փոխակերպիչ
├── services/               80+ ծառայության մոդուլներ (համակցություններ, պահուստային մշակում, քվոտաներ, ինքնություն, …)
├── utils/                  Հոսքային մշակման օժանդակ գործիքներ, TLS հաճախորդ, AWS SigV4, պրոքսի հարցումներ, …
└── mcp-server/             MCP սերվեր (3 տրանսպորտ, 33 տիրույթ, 110 գործիք)

4.1 open-sse/handlers/

Մշակիչ	Նպատակ
chatCore.ts	Զրույցի հիմնական հոսքաշար (քեշ, հաճախականության սահմանափակում, համակցված երթուղավորում, կատարիչի կանչ)
responsesHandler.ts	OpenAI Responses API-ի մուտքային կետ
embeddings.ts	Ներդրումներ
imageGeneration.ts	Պատկերների գեներացում
audioSpeech.ts	Տեքստից խոսքի փոխակերպում
audioTranscription.ts	Խոսքից տեքստի փոխակերպում
videoGeneration.ts	Տեսանյութերի գեներացում
musicGeneration.ts	Երաժշտության գեներացում
rerank.ts	Վերադասակարգում
moderations.ts	Բովանդակության վերահսկում
search.ts	Վեբ որոնում
sseParser.ts	SSE իրադարձությունների վերլուծիչ
usageExtractor.ts	Վերադաս հոսքերից տոկենների քանակների դուրսբերում
responseSanitizer.ts	Մատակարարին հատուկ ավելորդ տվյալների հեռացում
responseTranslator.ts	Մատակարարի պատասխանի և թարգմանիչ շերտի միջև կապակցող բաղադրիչ

4.2 open-sse/executors/

Մատակարարների 108 կատարիչ, որոնցից յուրաքանչյուրը ընդլայնում է BaseExecutor-ը (base.ts)՝

antigravity, azure-openai, blackbox-web, cliproxyapi, chatgpt-web-codex, cloudflare-ai, codex, commandCode, cursor, default, devin-cli, muse-spark-web, nlpcloud, opencode, perplexity-web, petals, pollinations, qoder, vertex, devin-desktop, ինչպես նաև claudeIdentity.ts (ինքնության համօգտագործվող օժանդակ գործիք) և index.ts (ռեեստր)։

Նշում․ այստեղ չթվարկված մատակարարները սպասարկվում են default.ts-ի կողմից՝ օգտագործելով ընդհանրական OpenAI-համատեղելի կատարիչը։ Մատակարարների ամբողջական կատալոգը (355 մատակարար) գտնվում է src/shared/constants/providers.ts-ում։

4.3 open-sse/translator/

Հանգույց-և-ճառագայթ թարգմանություն (OpenAI-ը հանգույցն է)։

• Հարցումների 9 թարգմանիչ (translator/request/)՝ antigravity-to-openai, claude-to-gemini, claude-to-openai, gemini-to-openai, openai-responses, openai-to-claude, openai-to-cursor, openai-to-gemini, openai-to-kiro։
• Պատասխանների 9 թարգմանիչ (translator/response/)՝ claude-to-openai, cursor-to-openai, gemini-to-claude, gemini-to-openai, kiro-to-openai, openai-responses, openai-to-antigravity, openai-to-claude։
• 9 օժանդակ գործիք (translator/helpers/)՝ claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper, ինչպես նաև օժանդակ գործիքների թեստեր։
• Պատկերների օժանդակ գործիքներ (translator/image/sizeMapper.ts)։
• Վերին մակարդակ՝ bootstrap.ts, formats.ts, registry.ts, index.ts։

4.4 open-sse/transformer/

• responsesTransformer.ts — TransformStream-ի վրա հիմնված Responses API ↔ Chat Completions փոխարկիչ (օգտագործվում է responses/ երթուղու համընդհանուր մշակիչի կողմից)։

4.5 open-sse/services/

Կարևոր բաղադրիչներ (ամբողջական ցանկը՝ open-sse/services/-ում)․

Մտահոգության ոլորտ	Ֆայլեր
Համակցված երթուղավորում	combo.ts (19 ռազմավարություն), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
Ավտոմատ համակցման շարժիչ	autoCombo/ — engine.ts, scoring.ts, taskFitness.ts, virtualFactory.ts, modePacks.ts, autoPrefix.ts, persistence.ts, providerDiversity.ts, providerRegistryAccessor.ts, routerStrategy.ts, selfHealing.ts, index.ts
Խափանումակայունություն	accountFallback.ts (սպասման ժամանակահատված + արգելափակում), errorClassifier.ts, emergencyFallback.ts, rateLimitManager.ts, rateLimitSemaphore.ts, accountSemaphore.ts, accountSelector.ts
Քվոտաներ	quotaMonitor.ts, quotaPreflight.ts, bailianQuotaFetcher.ts, codexQuotaFetcher.ts, deepseekQuotaFetcher.ts, openrouterQuotaFetcher.ts, openrouterFreeWindow.ts, crofUsageFetcher.ts, antigravityCredits.ts
Քեշավորում	reasoningCache.ts, searchCache.ts, signatureCache.ts, requestDedup.ts
Երթուղավորման բանականություն	intentClassifier.ts, taskAwareRouter.ts, backgroundTaskDetector.ts, volumeDetector.ts, wildcardRouter.ts, workflowFSM.ts, specificityDetector.ts, specificityRules.ts, specificityTypes.ts
Մոդելների մշակում	modelCapabilities.ts, modelDeprecation.ts, modelFamilyFallback.ts, modelStrip.ts, model.ts, provider.ts, providerRequestDefaults.ts, providerCostData.ts, payloadRules.ts
Սեղմում	compression/ — սեղմման շարժիչի ամբողջական կապակցում
Թոքեն + աշխատաշրջան	tokenRefresh.ts, sessionManager.ts, apiKeyRotator.ts, contextManager.ts, contextHandoff.ts, systemPrompt.ts, roleNormalizer.ts, responsesInputSanitizer.ts, toolSchemaSanitizer.ts, toolLimitDetector.ts, thinkingBudget.ts
Մակարդակ / մանիֆեստ	tierResolver.ts, tierConfig.ts, tierDefaults.json, tierTypes.ts, manifestAdapter.ts
IP / ցանց	ipFilter.ts, webSearchFallback.ts
Փաթեթներ	batchProcessor.ts
Օգտագործում	usage.ts

4.6 open-sse/mcp-server/

• 110 եզակի գործիք՝ կապակցված server.ts-ում (45 կանոնական՝ schemas/tools.ts-ում + հիշողության, հմտությունների, GitHub հմտությունների, պուլի, գեյմիֆիկացիայի, հավելումների, Notion-ի, Obsidian-ի, տեղային կորպուսի և սեղմման մոդուլներ. միավորումը հաշվարկվում է countUniqueMcpTools-ով)։
• 3 փոխադրամիջոց՝ stdio, HTTP Streamable, SSE։
• 33 շրջանակ՝ կիրառվող կատարման ընթացքում. բազային ցանկը գտնվում է src/shared/constants/mcpScopes.ts-ում, իսկ ամբողջական բազմությունը յուրաքանչյուր գործիքի մոդուլի կողմից հայտարարված շրջանակների միավորումն է։
• Աուդիտի աղյուսակ՝ mcp_tool_audit (լրացվում է audit.ts-ի միջոցով)։
• Ֆայլեր՝ server.ts, index.ts, httpTransport.ts, audit.ts, scopeEnforcement.ts, runtimeHeartbeat.ts, descriptionCompressor.ts, schemas/{tools, a2a, audit, index}.ts, tools/{advancedTools, compressionTools, memoryTools, skillTools}.ts, ինչպես նաև թեստերը՝ __tests__/-ի ներքո։
• Գործիքների ամբողջական կատալոգի համար տե՛ս MCP-SERVER.md։

4.7 open-sse/config/

Մատակարարների ռեեստրներ (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), ըստ ձևաչափի մոդելների ռեեստրներ (audioRegistry.ts, embeddingRegistry.ts, imageRegistry.ts, moderationRegistry.ts, musicRegistry.ts, rerankRegistry.ts, searchRegistry.ts, videoRegistry.ts), ինքնության օժանդակ գործիքներ (codexIdentity.ts, codexInstructions.ts, anthropicHeaders.ts, antigravityUpstream.ts, antigravityModelAliases.ts, cliFingerprints.ts, toolCloaking.ts, defaultThinkingSignature.ts), հավատարմագրերի օժանդակ գործիքներ (credentialLoader.ts, codexClient.ts) և ամպային ադապտերներ (azureAi.ts, bedrock.ts, datarobot.ts, glmProvider.ts, maritalk.ts, oci.ts, petals.ts, runway.ts, sap.ts, watsonx.ts, ollamaModels.ts, errorConfig.ts, constants.ts, registryUtils.ts)։

4.8 open-sse/utils/

Հոսքային մշակման պրիմիտիվներ և մատակարարների օժանդակ գործիքներ՝ stream.ts, streamHandler.ts, streamHelpers.ts, streamPayloadCollector.ts, streamReadiness.ts, sseHeartbeat.ts, proxyFetch.ts, proxyDispatcher.ts, tlsClient.ts, networkProxy.ts, awsSigV4.ts, cacheControlPolicy.ts, cursorChecksum.ts, cursorAgentProtobuf.ts, cursorVersionDetector.ts, comfyuiClient.ts, kieTask.ts, bypassHandler.ts, aiSdkCompat.ts, thinkTagParser.ts, urlSanitize.ts, usageTracking.ts, requestLogger.ts, progressTracker.ts, cors.ts, error.ts, logger.ts, sleep.ts, ollamaTransform.ts.

---

5. electron/ — Սեղանադիր հավելվածի փաթեթավորում

electron/
├── main.js                  Electron-ի հիմնական գործընթաց
├── preload.js               Նախաբեռնման կամուրջ (contextIsolation-ը միացված է)
├── types.d.ts
├── package.json             electron-builder-ի կազմաձևում, տարբերակ 3.8.51
├── README.md
├── assets/                  Կառուցման ռեսուրսներ (պատկերակներ, թույլտվություններ, …)
├── node_modules/            Առանձին node_modules (better-sqlite3, electron-updater)
└── dist-electron/           Կառուցման արդյունք (չի ներառվում պահոցում)

Աշխատանքային տարածքի արմատում առկա է հինգ npm սկրիպտ՝ electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged։ Ավտոմատ թարմացումն իրականացվում է electron-updater-ի միջոցով՝ հղվելով GitHub-ի թողարկումների հոսքին։

---

6. bin/ — Հրամանային տողի միջերես

bin/
├── omniroute.mjs           Հիմնական CLI մուտքային կետ (Node ESM)
├── reset-password.mjs      Կառավարման գաղտնաբառի վերակայում CLI-ից
├── mcp-server.mjs          MCP սերվերի գործարկիչ (stdio)
├── nodeRuntimeSupport.mjs  Node-ի տարբերակի ստուգիչ
└── cli/
    ├── program.mjs         Commander ծրագրի կառուցիչ
    ├── runtime.mjs         withRuntime օժանդակ գործառույթ (նախ՝ սերվեր, ապա՝ DB պահուստային տարբերակ)
    ├── output.mjs          Արտածման ձևաչափիչներ (json/jsonl/table/csv)
    ├── i18n.mjs            t() օժանդակ գործառույթ՝ տեղայնացումներով
    ├── api.mjs             API հարցումների օժանդակ գործառույթ
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Հրամանների գրանցում
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (մեկ ֆայլ՝ յուրաքանչյուր հրամանի/խմբի համար)

package.json → bin բաժնում հասանելի են երկու գործարկվող ֆայլեր՝

• omniroute → bin/omniroute.mjs
• omniroute-reset-password → bin/reset-password.mjs

---

7. tests/

Գրացուցակ	Տեսակ
tests/unit/	Միավորային թեստեր՝ Node-ի ներկառուցված թեստային գործարկիչով (1821 ֆայլ, ինչպես նաև api/, auth/, authz/ ենթագրացուցակներ)
tests/integration/	Միջմոդուլային և DB վիճակի թեստեր
tests/e2e/	Playwright UI թեստեր
tests/e2e/protocol-clients.test.ts	MCP/A2A արձանագրության e2e թեստ
tests/translator/	Թարգմանիչին հատուկ թեստեր
tests/security/	Անվտանգության հետընթացային սխալների թեստեր
tests/load/	Բեռնվածության / սթրես-թեստեր
tests/golden-set/	Էտալոնային արդյունքներ՝ թարգմանչի հետընթացային սխալների ստուգման համար
tests/helpers/, tests/fixtures/, tests/manual/	Օժանդակ նյութեր

Հաճախ օգտագործվող հրամաններ՝

Հրաման	Ինչ է գործարկում
npm run test:unit	Բոլոր tests/unit/*.test.ts ֆայլերը՝ Node-ի թեստային գործարկիչով (զուգահեռություն՝ 10)
npm run test:vitest	Vitest թեստային հավաքածուն (MCP, autoCombo, cache)
npm run test:e2e	Playwright UI թեստային հավաքածուն
npm run test:protocols:e2e	MCP + A2A արձանագրությունների e2e թեստերը
npm run test:coverage	Ծածկույթի շեմ (տողեր/արտահայտություններ/գործառույթներ/ճյուղեր՝ ≥60%)
node --import tsx/esm --test tests/unit/<file>.test.ts	Մեկ ֆայլի գործարկում

---

8. scripts/

Ըստ նշանակության կազմակերպված է 6 ենթապանակների մեջ։

• scripts/build/ — build-next-isolated.mjs, prepublish.ts, prepare-electron-standalone.mjs, pack-artifact-policy.ts, validate-pack-artifact.ts, postinstall.mjs, postinstallSupport.mjs, uninstall.mjs, bootstrap-env.mjs, runtime-env.mjs, native-binary-compat.mjs։
• scripts/dev/ — run-next.mjs, run-next-playwright.mjs, run-standalone.mjs, standalone-server-ws.mjs, responses-ws-proxy.mjs, v1-ws-bridge.mjs, smoke-electron-packaged.mjs, run-playwright-tests.mjs, run-ecosystem-tests.mjs, run-protocol-clients-tests.mjs, sync-env.mjs, healthcheck.mjs, system-info.mjs։
• scripts/check/ — check-cycles.mjs, check-docs-sync.mjs, check-docs-counts-sync.mjs, check-env-doc-sync.mjs, check-deprecated-versions.mjs, check-route-validation.mjs, check-t11-any-budget.mjs, check-pr-test-policy.mjs, check-supported-node-runtime.ts, test-report-summary.mjs։
• scripts/docs/ — generate-docs-index.mjs, gen-provider-reference.ts։
• scripts/i18n/ — generate-multilang.mjs, run-visual-qa.mjs, generate-qa-checklist.mjs, apply-priority-overrides.mjs, validate_translation.py, check_translations.py, i18n_autotranslate.py, untranslatable-keys.json։
• scripts/ad-hoc/ — cursor-tap.cjs, sync-cursor-models.mjs, migrate-env.mjs, dbsetup.js։

---

9. Հարցումների մշակման շղթա (ամփոփում)

Աղբյուր՝ diagrams/request-pipeline.mmd

Հաճախորդի հարցում
  → /v1/chat/completions (route.ts)
     CORS նախնական հարցման ստուգում
     Zod վավերացում (chatCompletionsSchema՝ shared/validation/schemas.ts-ում)
     Նույնականացում (extractApiKey + isValidApiKey ԿԱՄ requireManagementAuth)
     Քաղաքականությունների շարժիչ (src/server/authz/pipeline.ts)
     Պաշտպանիչ սահմանափակումներ (PII քողարկիչ, հրահանգների ներարկում, տեսողական կամուրջ)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Քեշի ստուգում (իմաստային + ընթերցման քեշ)
     Հաճախականության սահմանափակում (rateLimitManager, accountSemaphore)
     Համակցված երթուղավորում (եթե մոդելը վերածվում է համակցության)
       comboResolver → ցիկլ յուրաքանչյուր թիրախի համար → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       հարցում վերին հոսքին → կրկնափորձ/հետաձգում՝ accountFallback-ի միջոցով
     translateResponse() (open-sse/translator/response/*)
     SSE հոսք ԿԱՄ JSON պատասխան
     Եթե Responses API է՝ TransformStream՝ open-sse/transformer/responsesTransformer.ts-ի միջոցով
  → Համապատասխանության աուդիտ (src/lib/compliance/)
  → Պատասխան հաճախորդին

Խափանումակայունության կատարման վիճակ (երեք մեխանիզմ)

Մեխանիզմ	Գործողության շրջանակ	Որտեղ
Մատակարարի շղթայի անջատիչ	Ամբողջ մատակարարը	src/shared/utils/circuitBreaker.ts, պահպանվում է domain_circuit_breakers-ում
Կապի սառեցման ժամանակահատված	Մեկ հաշիվ/բանալի	markAccountUnavailable()՝ src/sse/services/auth.ts-ում․ օգտագործվում է accountFallback.checkFallbackError()-ի կողմից
Մոդելի արգելափակում	Մատակարար + կապ + մոդել	open-sse/services/accountFallback.ts, պահպանվում է domain_lockout_state-ում

Տե՛ս RESILIENCE_GUIDE.md և դրան նվիրված բաժինը CLAUDE.md-ում։

---

10. Ինչպես ներդրում կատարել

Ավելացնել նոր մատակարար

1. Գրանցեք src/shared/constants/providers.ts-ում (բեռնման ժամանակ ստուգվում է Zod-ի միջոցով)։
2. Եթե հատուկ տրամաբանություն է պահանջվում, ավելացրեք կատարիչ open-sse/executors/-ում (BaseExecutor-ի ընդլայնմամբ)։
3. Եթե այն չի աշխատում OpenAI ձևաչափով, ավելացրեք թարգմանիչ open-sse/translator/-ում։
4. Եթե հիմնված է OAuth-ի վրա, ավելացրեք կազմաձևում src/lib/oauth/providers/ և src/lib/oauth/services/ ուղիներում։
5. Գրանցեք մոդելները open-sse/config/providerRegistry.ts-ում (կամ ձևաչափին հատուկ գրանցամատյանում՝ open-sse/config/-ի ներքո)։
6. Գրեք թեստեր tests/unit/-ում։

Ավելացնել նոր API երթուղի

1. Ստեղծեք src/app/api/your-route/route.ts։
2. Հետևեք այս ձևանմուշին՝ CORS → հարցման մարմնի ստուգում Zod-ով → նույնականացում → մշակողին փոխանցում։
3. Եթե հարցման կառուցվածքը նոր է, ավելացրեք Zod սխեման src/shared/validation/schemas.ts-ում։
4. Եթե նախատեսված է միայն կառավարման համար, ավելացրեք ուղին src/shared/constants/publicApiRoutes.ts-ում (հանրային API մակերեսի արգելացանկ)։
5. Ավելացրեք թեստեր tests/unit/-ում։
6. Թարմացրեք docs/reference/API_REFERENCE.md-ը և docs/openapi.yaml-ը։

Ավելացնել նոր DB մոդուլ

1. Ստեղծեք src/lib/db/yourModule.ts և ներմուծեք getDbInstance()-ը ./core.ts-ից։
2. Արտահանեք CRUD ֆունկցիաներ ձեր տիրույթի համար։
3. Նոր աղյուսակների դեպքում ավելացրեք միգրացիա src/lib/db/migrations/-ում՝ հաջորդական համարակալմամբ, իդեմպոտենտ և տրանզակցիոն։
4. Ներմուծողներն օգտագործում են ուղիղ ներմուծումներ @/lib/db/yourModule-ից (առանց barrel-ի՝ հին localDb.ts վերաարտահանման շերտը հեռացվել է)։
5. Ավելացրեք թեստեր tests/unit/-ում։

Ավելացնել նոր MCP գործիք

1. Ավելացրեք գործիքի սահմանումը open-sse/mcp-server/tools/-ում (կամ ընդլայնեք open-sse/mcp-server/schemas/tools.ts-ը)։
2. Նշանակեք համապատասխան շրջանակը կամ շրջանակները src/shared/constants/mcpScopes.ts-ում։
3. Գրանցեք գործիքը open-sse/mcp-server/server.ts-ում։
4. Ավելացրեք թեստեր open-sse/mcp-server/__tests__/-ում։
5. Թարմացրեք MCP-SERVER.md-ը։

Ավելացնել նոր A2A հմտություն

Տե՛ս A2A-SERVER.md § Նոր հմտության ավելացում։ Հմտությունները գտնվում են src/lib/a2a/skills/-ում և գրանցվում են A2A առաջադրանքների կառավարչի միջոցով։

---

11. Պայմանավորվածություններ

• Կոդի ոճ: 2 բացատով նահանջ, կրկնակի չակերտներ, 100 նիշ լայնություն, կետ-ստորակետեր, es5 վերջնային ստորակետեր՝ կիրառվում է Prettier-ի կողմից՝ lint-staged-ի միջոցով։
• Ներմուծումներ: արտաքին → ներքին (@/, @omniroute/open-sse) → հարաբերական։
• Անվանումներ: ֆայլերը՝ camelCase կամ kebab-case, բաղադրիչները՝ PascalCase, հաստատունները՝ UPPER_SNAKE։
• ESLint: no-eval, no-implied-eval, no-new-func = error ամենուրեք, no-explicit-any = warn՝ open-sse/-ում և tests/-ում, իսկ այլուր՝ error։
• TypeScript: strict: false (ժառանգված մոտեցում)։ Մոդուլների սահմանների համար տիպերի ենթադրությունից գերադասեք բացահայտ տիպերը։
• Տվյալների բազա: երբեք մի գրեք անմշակ SQL երթուղիներում կամ մշակողներում՝ միշտ աշխատեք src/lib/db/ մոդուլների միջոցով։ Երբեք մի կատարեք barrel ներմուծում՝ ուղղակիորեն օգտագործեք հատուկ src/lib/db/* մոդուլները։
• DB էությունների տիպավորում (#3512): ֆունկցիան, որը գրում կամ կարդում է DB աղյուսակի տողի կառուցվածքը, պետք է ընդունի/վերադարձնի այդ աղյուսակի սյունակները 1:1 արտացոլող անվանված TS ինտերֆեյս, այլ ոչ թե any կամ կանչի վայրում սահմանված անանուն ներկառուցված տիպ։ Տեղադրեք ինտերֆեյսը ֆունկցիայի կողքին (օրինակ՝ export interface UsageEntry-ը src/lib/usage/usageHistory.ts-ում՝ saveRequestUsage-ից վերև), առանձին դաշտերը պահեք ոչ պարտադիր/nullable, երբ տարբեր գրողներ աստիճանաբար են լրացնում տողը, և any-ի փոխարեն նախընտրեք unknown, երբ դաշտի կառուցվածքը տարբեր է կանչողների միջև (փաստաթղթավորված դաշտում, օրինակ՝ UsageEntry.tokens-ն ընդունում է թե՛ մատակարարի սկզբնական կառուցվածքով օգտագործման տվյալները, թե՛ նորմալացված կառուցվածքը)։ Երբ ֆայլի any-ների քանակն այս եղանակով հասնի զրոյի, ավելացրեք այն check:any-budget:t11 թույլատրվածների ցանկում (scripts/check/check-t11-any-budget.mjs, maxAny: 0), որպեսզի հետընթաց հնարավոր չլինի։ Սա առաջին փուլի պայմանավորվածություն է՝ ավելի լայն «առանց անանուն any-ի» մաքրումը կրկնողականորեն իրականացվում է կոդային բազայի մնացած մասում։
• Սխալներ: օգտագործեք try/catch՝ սխալների կոնկրետ տիպերով, գրանցամատյանում գրեք pino համատեքստով։ Երբեք լուռ մի կլանեք SSE հոսքերի սխալները․ մաքրման համար օգտագործեք ընդհատման ազդանշաններ։
• Անվտանգություն: երբեք մի օգտագործեք eval() / new Function() / անուղղակի eval։ Ստուգեք բոլոր մուտքային տվյալները Zod-ով։ Պահպանման ընթացքում գաղտնագրեք հավատարմագրերը (AES-256-GCM)։ Պահեք src/shared/constants/upstreamHeaders.ts արգելացանկը համահունչ մաքրման/ստուգման շերտին։
• Commit-ներ: Conventional Commits՝ feat(scope): subject։ Թույլատրված շրջանակներն են՝ db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills։
• Ճյուղեր: նախածանցներ՝ feat/, fix/, refactor/, docs/, test/, chore/։ Երբեք commit մի կատարեք անմիջապես main-ում։
• Husky: pre-commit-ը գործարկում է lint-staged + check:docs-sync + check:any-budget:t11, իսկ pre-push-ը՝ check:any-budget:t11 + check:tracked-artifacts (արագ ստուգումներ՝ առանց test:unit-ի)։

---

12. Խիստ կանոններ (CLAUDE.md-ից)

1. Երբեք մի՛ commit արեք գաղտնիքներ կամ նույնականացման տվյալներ։
2. Երբեք մի՛ օգտագործեք barrel import. անմիջապես օգտագործեք համապատասխան src/lib/db/* մոդուլները։
3. Երբեք մի՛ օգտագործեք eval() / new Function() / անուղղակի eval։
4. Երբեք commit մի՛ արեք անմիջապես main ճյուղում։
5. Երբեք routes-ում մի՛ գրեք raw SQL. միշտ օգտագործեք src/lib/db/ մոդուլները։
6. Երբեք լուռ մի՛ անտեսեք SSE հոսքերի սխալները։
7. Միշտ վավերացրեք մուտքային տվյալները Zod սխեմաներով։
8. Production կոդը փոփոխելիս միշտ ներառեք թեստեր։
9. Ծածկույթը պետք է մնա ≥ 60% (հրահանգներ, տողեր, ֆունկցիաներ, ճյուղեր)։

---

13. Տես նաև

• ARCHITECTURE.md — բարձր մակարդակի ճարտարապետությունը և մոդուլների պատասխանատվությունները։
• API_REFERENCE.md — հանրային և կառավարման API-ի տեղեկատու։
• FEATURES.md — հնարավորությունների մատրիցը և տարբերակների կարևոր փոփոխությունները։
• RESILIENCE_GUIDE.md — circuit breaker-ի, cooldown-ի և lockout-ի մանրամասն նկարագրություն։
• AUTO-COMBO.md — Auto Combo-ի գնահատում և ռազմավարություններ։
• MCP-SERVER.md — MCP գործիքների ամբողջական կատալոգը և փոխանցման եղանակները։
• A2A-SERVER.md — A2A արձանագրության հմտությունները և հայտնաբերումը։
• COMPRESSION_GUIDE.md — RTK + Caveman սեղմում։
• CLI-TOOLS.md — CLI ինտեգրումներ։
• ELECTRON_GUIDE.md (եթե առկա է), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — տեղակայման թիրախներ։
• TROUBLESHOOTING.md — շահագործման տարածված խնդիրներ։
• CONTRIBUTING.md — ներդրողների աշխատանքային հոսքը։
• CLAUDE.md — Claude Code-ի համար պահոցի կանոնները (վերը նշված պայմանավորվածություններից շատերի ճշմարտության առաջնային աղբյուրը)։
• AGENTS.md — գործակալների կողմից օգտագործվող ճարտարապետության ավելի խորացված տեղեկատու։