# OmniRoute Architecture (Magyar)
🌐 **Languages:** 🇺🇸 [English](../../../../architecture/ARCHITECTURE.md) · 🇪🇹 [am](../../../am/docs/architecture/ARCHITECTURE.md) · 🇸🇦 [ar](../../../ar/docs/architecture/ARCHITECTURE.md) · 🇦🇿 [az](../../../az/docs/architecture/ARCHITECTURE.md) · 🇧🇬 [bg](../../../bg/docs/architecture/ARCHITECTURE.md) · 🇧🇩 [bn](../../../bn/docs/architecture/ARCHITECTURE.md) · 🇧🇦 [bs](../../../bs/docs/architecture/ARCHITECTURE.md) · 🇨🇿 [cs](../../../cs/docs/architecture/ARCHITECTURE.md) · 🇩🇰 [da](../../../da/docs/architecture/ARCHITECTURE.md) · 🇩🇪 [de](../../../de/docs/architecture/ARCHITECTURE.md) · 🇬🇷 [el](../../../el/docs/architecture/ARCHITECTURE.md) · 🇪🇸 [es](../../../es/docs/architecture/ARCHITECTURE.md) · 🇪🇪 [et](../../../et/docs/architecture/ARCHITECTURE.md) · 🇮🇷 [fa](../../../fa/docs/architecture/ARCHITECTURE.md) · 🇫🇮 [fi](../../../fi/docs/architecture/ARCHITECTURE.md) · 🇫🇷 [fr](../../../fr/docs/architecture/ARCHITECTURE.md) · 🇮🇪 [ga](../../../ga/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [gu](../../../gu/docs/architecture/ARCHITECTURE.md) · 🇳🇬 [ha](../../../ha/docs/architecture/ARCHITECTURE.md) · 🇮🇱 [he](../../../he/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [hi](../../../hi/docs/architecture/ARCHITECTURE.md) · 🇭🇷 [hr](../../../hr/docs/architecture/ARCHITECTURE.md) · 🇦🇲 [hy](../../../hy/docs/architecture/ARCHITECTURE.md) · 🇮🇩 [id](../../../id/docs/architecture/ARCHITECTURE.md) · 🇳🇬 [ig](../../../ig/docs/architecture/ARCHITECTURE.md) · 🇮🇹 [it](../../../it/docs/architecture/ARCHITECTURE.md) · 🇯🇵 [ja](../../../ja/docs/architecture/ARCHITECTURE.md) · 🇬🇪 [ka](../../../ka/docs/architecture/ARCHITECTURE.md) · 🇰🇭 [km](../../../km/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [kn](../../../kn/docs/architecture/ARCHITECTURE.md) · 🇰🇷 [ko](../../../ko/docs/architecture/ARCHITECTURE.md) · 🇱🇹 [lt](../../../lt/docs/architecture/ARCHITECTURE.md) · 🇱🇻 [lv](../../../lv/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [ml](../../../ml/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [mr](../../../mr/docs/architecture/ARCHITECTURE.md) · 🇲🇾 [ms](../../../ms/docs/architecture/ARCHITECTURE.md) · 🇲🇹 [mt](../../../mt/docs/architecture/ARCHITECTURE.md) · 🇲🇲 [my](../../../my/docs/architecture/ARCHITECTURE.md) · 🇳🇵 [ne](../../../ne/docs/architecture/ARCHITECTURE.md) · 🇳🇱 [nl](../../../nl/docs/architecture/ARCHITECTURE.md) · 🇳🇴 [no](../../../no/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [or](../../../or/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [pa](../../../pa/docs/architecture/ARCHITECTURE.md) · 🇵🇭 [phi](../../../phi/docs/architecture/ARCHITECTURE.md) · 🇵🇱 [pl](../../../pl/docs/architecture/ARCHITECTURE.md) · 🇵🇹 [pt](../../../pt/docs/architecture/ARCHITECTURE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/ARCHITECTURE.md) · 🇷🇴 [ro](../../../ro/docs/architecture/ARCHITECTURE.md) · 🇷🇺 [ru](../../../ru/docs/architecture/ARCHITECTURE.md) · 🇱🇰 [si](../../../si/docs/architecture/ARCHITECTURE.md) · 🇸🇰 [sk](../../../sk/docs/architecture/ARCHITECTURE.md) · 🇸🇮 [sl](../../../sl/docs/architecture/ARCHITECTURE.md) · 🇷🇸 [sr](../../../sr/docs/architecture/ARCHITECTURE.md) · 🇸🇪 [sv](../../../sv/docs/architecture/ARCHITECTURE.md) · 🇰🇪 [sw](../../../sw/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [ta](../../../ta/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [te](../../../te/docs/architecture/ARCHITECTURE.md) · 🇹🇭 [th](../../../th/docs/architecture/ARCHITECTURE.md) · 🇹🇷 [tr](../../../tr/docs/architecture/ARCHITECTURE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/ARCHITECTURE.md) · 🇵🇰 [ur](../../../ur/docs/architecture/ARCHITECTURE.md) · 🇺🇿 [uz](../../../uz/docs/architecture/ARCHITECTURE.md) · 🇻🇳 [vi](../../../vi/docs/architecture/ARCHITECTURE.md) · 🇳🇬 [yo](../../../yo/docs/architecture/ARCHITECTURE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/ARCHITECTURE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/ARCHITECTURE.md)
---
🌐 **Languages:** 🇺🇸 [English](../../../../architecture/ARCHITECTURE.md) · 🇪🇹 [am](../../../am/docs/architecture/ARCHITECTURE.md) · 🇸🇦 [ar](../../../ar/docs/architecture/ARCHITECTURE.md) · 🇦🇿 [az](../../../az/docs/architecture/ARCHITECTURE.md) · 🇧🇬 [bg](../../../bg/docs/architecture/ARCHITECTURE.md) · 🇧🇩 [bn](../../../bn/docs/architecture/ARCHITECTURE.md) · 🇧🇦 [bs](../../../bs/docs/architecture/ARCHITECTURE.md) · 🇨🇿 [cs](../../../cs/docs/architecture/ARCHITECTURE.md) · 🇩🇰 [da](../../../da/docs/architecture/ARCHITECTURE.md) · 🇩🇪 [de](../../../de/docs/architecture/ARCHITECTURE.md) · 🇬🇷 [el](../../../el/docs/architecture/ARCHITECTURE.md) · 🇪🇸 [es](../../../es/docs/architecture/ARCHITECTURE.md) · 🇪🇪 [et](../../../et/docs/architecture/ARCHITECTURE.md) · 🇮🇷 [fa](../../../fa/docs/architecture/ARCHITECTURE.md) · 🇫🇮 [fi](../../../fi/docs/architecture/ARCHITECTURE.md) · 🇫🇷 [fr](../../../fr/docs/architecture/ARCHITECTURE.md) · 🇮🇪 [ga](../../../ga/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [gu](../../../gu/docs/architecture/ARCHITECTURE.md) · 🇳🇬 [ha](../../../ha/docs/architecture/ARCHITECTURE.md) · 🇮🇱 [he](../../../he/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [hi](../../../hi/docs/architecture/ARCHITECTURE.md) · 🇭🇷 [hr](../../../hr/docs/architecture/ARCHITECTURE.md) · 🇦🇲 [hy](../../../hy/docs/architecture/ARCHITECTURE.md) · 🇮🇩 [id](../../../id/docs/architecture/ARCHITECTURE.md) · 🇳🇬 [ig](../../../ig/docs/architecture/ARCHITECTURE.md) · 🇮🇹 [it](../../../it/docs/architecture/ARCHITECTURE.md) · 🇯🇵 [ja](../../../ja/docs/architecture/ARCHITECTURE.md) · 🇬🇪 [ka](../../../ka/docs/architecture/ARCHITECTURE.md) · 🇰🇭 [km](../../../km/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [kn](../../../kn/docs/architecture/ARCHITECTURE.md) · 🇰🇷 [ko](../../../ko/docs/architecture/ARCHITECTURE.md) · 🇱🇹 [lt](../../../lt/docs/architecture/ARCHITECTURE.md) · 🇱🇻 [lv](../../../lv/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [ml](../../../ml/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [mr](../../../mr/docs/architecture/ARCHITECTURE.md) · 🇲🇾 [ms](../../../ms/docs/architecture/ARCHITECTURE.md) · 🇲🇹 [mt](../../../mt/docs/architecture/ARCHITECTURE.md) · 🇲🇲 [my](../../../my/docs/architecture/ARCHITECTURE.md) · 🇳🇵 [ne](../../../ne/docs/architecture/ARCHITECTURE.md) · 🇳🇱 [nl](../../../nl/docs/architecture/ARCHITECTURE.md) · 🇳🇴 [no](../../../no/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [or](../../../or/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [pa](../../../pa/docs/architecture/ARCHITECTURE.md) · 🇵🇭 [phi](../../../phi/docs/architecture/ARCHITECTURE.md) · 🇵🇱 [pl](../../../pl/docs/architecture/ARCHITECTURE.md) · 🇵🇹 [pt](../../../pt/docs/architecture/ARCHITECTURE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/ARCHITECTURE.md) · 🇷🇴 [ro](../../../ro/docs/architecture/ARCHITECTURE.md) · 🇷🇺 [ru](../../../ru/docs/architecture/ARCHITECTURE.md) · 🇱🇰 [si](../../../si/docs/architecture/ARCHITECTURE.md) · 🇸🇰 [sk](../../../sk/docs/architecture/ARCHITECTURE.md) · 🇸🇮 [sl](../../../sl/docs/architecture/ARCHITECTURE.md) · 🇷🇸 [sr](../../../sr/docs/architecture/ARCHITECTURE.md) · 🇸🇪 [sv](../../../sv/docs/architecture/ARCHITECTURE.md) · 🇰🇪 [sw](../../../sw/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [ta](../../../ta/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [te](../../../te/docs/architecture/ARCHITECTURE.md) · 🇹🇭 [th](../../../th/docs/architecture/ARCHITECTURE.md) · 🇹🇷 [tr](../../../tr/docs/architecture/ARCHITECTURE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/ARCHITECTURE.md) · 🇵🇰 [ur](../../../ur/docs/architecture/ARCHITECTURE.md) · 🇺🇿 [uz](../../../uz/docs/architecture/ARCHITECTURE.md) · 🇻🇳 [vi](../../../vi/docs/architecture/ARCHITECTURE.md) · 🇳🇬 [yo](../../../yo/docs/architecture/ARCHITECTURE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/ARCHITECTURE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/ARCHITECTURE.md)
_Utolsó frissítés: 2026-06-28_
## Vezetői összefoglaló
OmniRoute egy helyi AI útválasztási átjáró és műszerfal, amely Next.js re épül. Egyetlen OpenAI-kompatibilis végpontot (`/v1/*`) biztosít, és a forgalmat több upstream szolgáltató között irányítja át fordítással, tartalékkal, tokenfrissítéssel és használat követéssel.
Alapvető képességek:
- OpenAI-kompatibilis API felület CLI/tools (381 szolgáltató, 159 végrehajtó modul)
- Request/response fordítás a szolgáltatói formátumok között
- Modell kombinált tartalék (több modell sorozat)
- Strukturált kombinált lépések (`provider + model + connection`) `compositeTiers` futásidejű sorrendjével
- Fiókszintű tartalék (szolgáltatónként több fiók)
- Kvóta előzetes ellenőrzése és kvóta-tudatos P2C -fiók kiválasztása a fő csevegési útvonalon
- OAuth + API-kulcs szolgáltató kapcsolatkezelés (27 OAuth szolgáltató modul)
- Generáció beágyazása `/v1/embeddings` keresztül (18 szolgáltató)
- Képgenerálás `/v1/images/generations` keresztül (10 + szolgáltató, 20 + modell)
- Hang átírása `/v1/audio/transcriptions` keresztül (18 szolgáltató)
- Szövegfelolvasó `/v1/audio/speech` keresztül (24 beépített szolgáltató)
- Videó generálása `/v1/videos/generations` segítségével (ComfyUI + SD WebUI)
- Zenegenerálás `/v1/music/generations` keresztül (ComfyUI)
- Internetes keresés `/v1/search` keresztül (20 szolgáltató)
- Moderálás `/v1/moderations` keresztül
- Újrasorolás `/v1/rerank` keresztül
- Gondoljon a címkeelemzésre (`...`) az érvelési modellekhez
- Válasz fertőtlenítés a szigorú OpenAI SDK kompatibilitás érdekében
- Szerepkör normalizálás (fejlesztői → rendszer, rendszer → felhasználó) a szolgáltatók közötti kompatibilitás érdekében
- Strukturált kimenet átalakítás (json_schema → Gemini responseSchema)
- Helyi megmaradás a szolgáltatók, kulcsok, álnevek, kombinációk, beállítások, árképzés számára (122 DB modul)
- Usage/cost követés és kérésnaplózás
- Opcionális felhőszinkronizálás multi-device/state szinkronizáláshoz
- IP allowlist/blocklist API hozzáférés-vezérléshez
- Gondolkodó költségvetés-menedzsment (passthrough/auto/custom/adaptive)
- Globális rendszer azonnali befecskendezése
- Munkamenet-követés és ujjlenyomatvétel
- Fiókonként továbbfejlesztett díjkorlátozás szolgáltató-specifikus profilokkal
- Megszakító minta a szolgáltatói rugalmasság érdekében
- Mennydörgés elleni állományvédelem mutex zárral
- Aláírás-alapú kérés deduplikációs gyorsítótár
- Domain réteg: költségszabályok, tartalék házirend, kizárási szabályzat
- Context Relay: munkamenet-átadási összefoglalók a fiókrotáció folytonosságához
- Tartomány állapotának fennmaradása (SQLite átírási gyorsítótár tartalékok, költségvetések, zárolások, árammegszakítók számára)
- Házirend motor a kérelmek központosított kiértékeléséhez (lockout → budget → backback)
- Telemetria kérése p50/p95/p99 késleltetési összesítéssel
- Kombinált céltelemetria és történelmi kombinált célállapot `combo_execution_key` / `combo_step_id` segítségével
- Korreláció ID (X-Request-Id) a végpontok közötti nyomkövetéshez
- Megfelelőségi audit naplózás API kulcsonkénti leiratkozással
- Eval keretrendszer LLM minőségbiztosításhoz
- Egészségügyi műszerfal valós idejű szolgáltatói megszakító állapottal
- MCP szerver (110 eszköz) 3 átvitellel (stdio/SSE/Streamable HTTP)
- A2A szerver (JSON-RPC 2.0 + SSE) készségekkel és feladatok életciklusával
- Memóriarendszer (kivonás, injekció, előhívás, összegzés)
- Skills rendszer (nyilvántartó, végrehajtó, homokozó, beépített készségek)
- MITM proxy tanúsítványkezeléssel és DNS kezeléssel
- Azonnali befecskendezésvédő köztes szoftver
- Gyors tömörítési folyamat Cavemannel, RTK, halmozott folyamatokkal, tömörítési kombókkal, nyelvi csomagokkal és elemzésekkel
- ACP (Agent Communication Protocol) nyilvántartás
- Moduláris OAuth szolgáltatók (22 egyedi modul a `src/lib/oauth/providers/` alatt)
- Uninstall/full-uninstall szkriptek
- OAuth környezetvédelmi javítási akció
- WebSocket híd OpenAI-kompatibilis WS kliensekhez (`/v1/ws`)
- Szinkron tokenkezelés (issue/revoke, ETag-verziójú konfigurációs csomag letöltése)
- GLM Thinking (`glmt`) első osztályú szolgáltató előre beállított
- Hibrid token számlálás (szolgáltató oldali `/messages/count_tokens` becslési tartalékkal)
- Modellalias automatikus vetés (30 + proxy dialektusok közötti normalizálás indításkor)
- Biztonságos kimenő letöltés SSRF védelemmel, privát URL blokkolással és konfigurálható újrapróbálkozással
- Lehűlés-tudatos csevegési próbálkozások konfigurálható `requestRetry` és `maxRetryIntervalSec` segítségével
- Futási környezet ellenőrzése Zod val indításkor
- Megfelelőségi audit v2 oldalszámozással, szolgáltatói CRUD eseményekkel és SSRF által blokkolt érvényesítési naplózással
Elsődleges futásidejű modell:
- A Next.js alkalmazásútvonalai `src/app/api/*` alatt mind a műszerfali APIs, mind a kompatibilitási APIs megvalósítják
- A `src/sse/*` + `open-sse/*` megosztott SSE/routing magja kezeli a szolgáltató végrehajtását, fordítását, adatfolyamát, visszaállítását és használatát
## Referenciadiagramok
A v3.8.0 platform kanonikus, verziókövetett Mermaid-forrásai a
[`docs/diagrams/`](../diagrams/README.md) könyvtárban találhatók. A tájékozódás megkönnyítésére kettőt alább is bemutatunk;
a többi a saját szakterületéhez tartozó útmutatóból érhető el.
> Forrás: [diagrams/request-pipeline.mmd](../diagrams/request-pipeline.mmd)
> Forrás: [diagrams/resilience-3layers.mmd](../diagrams/resilience-3layers.mmd) — hivatkozás található rá továbbá a
> [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) fájlban és a `CLAUDE.md` rezilienciával kapcsolatos referenciájában.
## Hatókör és korlátok
### A hatókör része
- Helyi átjáró futtatókörnyezete
- Az irányítópult felügyeleti API-jai
- Szolgáltatói hitelesítés és tokenfrissítés
- Kérések átalakítása és SSE-adatfolyamok továbbítása
- Helyi állapot és használati adatok tartós tárolása
- Opcionális felhőszinkronizáció vezénylése
### Nem része a hatókörnek
- A `NEXT_PUBLIC_CLOUD_URL` mögötti felhőszolgáltatás megvalósítása
- A helyi folyamaton kívüli szolgáltatói SLA/vezérlősík
- Maguk a külső CLI-binárisok (Claude CLI, Codex CLI stb.)
## Irányítópult-felület (jelenlegi)
Fő oldalak a `src/app/(dashboard)/dashboard/` alatt:
- `/dashboard` — gyors kezdés és szolgáltatói áttekintés
- `/dashboard/endpoint` — végpontproxy, valamint MCP-, A2A- és API-végpontfülek
- `/dashboard/providers` — szolgáltatói kapcsolatok és hitelesítő adatok
- `/dashboard/combos` — kombinációs stratégiák, sablonok, lépésalapú összeállító, modellútválasztási szabályok és kézzel beállított, tartós sorrend
- `/dashboard/auto-combo` — Auto Combo Engine: pontozási súlyok, módcsomagok, virtuális gyári előbeállítások és telemetria
- `/dashboard/costs` — költségösszesítés és árképzési áttekinthetőség
- `/dashboard/analytics` — használati analitika, kiértékelések és a kombinációs célok állapota
- `/dashboard/limits` — kvóta- és sebességkorlátozási vezérlők
- `/dashboard/cli-tools` — CLI-bevezetés, futtatókörnyezet-észlelés és konfigurációgenerálás
- `/dashboard/agents` — észlelt ACP-ügynökök és egyéni ügynökök regisztrációja
- `/dashboard/cloud-agents` — felhőben futtatott ügynökfeladatok (Codex Cloud, Devin, Jules) és a feladatok életciklusa
- `/dashboard/skills` — A2A-képességjegyzék, homokozókörnyezetben történő végrehajtás és beépített képességkatalógus
- `/dashboard/memory` — tartós társalgási memória vizsgálata és visszakeresése
- `/dashboard/webhooks` — kimenő webhook-előfizetések, titokkulcs-rotáció és újrapróbálkozási statisztikák
- `/dashboard/batch` — kötegelt feladatok beküldése és előrehaladása
- `/dashboard/cache` — átengedéses és következtetési gyorsítótár statisztikái, valamint kiürítési vezérlők
- `/dashboard/playground` — interaktív csevegési tesztkörnyezet bármely konfigurált kombinációval vagy modellel
- `/dashboard/changelog` — alkalmazáson belüli változásnapló-megjelenítő (a `CHANGELOG.md` fájlt rendereli)
- `/dashboard/system` — futtatókörnyezeti diagnosztika, verzióinformációk és környezet-ellenőrzési felület
- `/dashboard/onboarding` — első futtatási beállítóvarázsló új telepítésekhez
- `/dashboard/media` — kép-, videó- és zenetesztkörnyezet
- `/dashboard/search-tools` — keresési szolgáltatók tesztelése és előzmények
- `/dashboard/health` — rendelkezésre állás, megszakítók, sebességkorlátok és kvótafigyelt munkamenetek
- `/dashboard/logs` — kérés-, proxy-, audit- és konzolnaplók
- `/dashboard/settings` — rendszerbeállítási fülek (általános, útválasztás, kombinációs alapértelmezések stb.)
- `/dashboard/context/caveman` — Caveman tömörítési szabályok, nyelvi csomagok, előnézet és kimeneti mód
- `/dashboard/context/rtk` — RTK parancskimeneti szűrők, előnézet és futásidejű biztonsági beállítások
- `/dashboard/context/combos` — útválasztási kombinációkhoz rendelt, elnevezett tömörítési folyamatláncok
- `/dashboard/translator` — fordítóvizsgálat és kérésformátum-konverziós előnézet
- `/dashboard/audit` — megfelelőségi auditnaplók lapozható böngészője strukturált metaadatokkal
- `/dashboard/usage` — kérésenkénti használati böngésző a `usage_history` adataihoz kapcsolva
- `/dashboard/compression` — tömörítési analitika, statisztikák és folyamatlánc-hozzárendelés
- `/dashboard/api-manager` — API-kulcsok életciklusa és modellengedélyek
Felhasználói felületi réteg: minden oldal egyetlen kereten belül jelenik meg — `src/app/(dashboard)/layout.tsx` →
`src/shared/components/layouts/DashboardLayout.tsx` → `DashboardShell.tsx` (a készlet
`SidebarProvider`/`SidebarInset` elemei, valamint az OmniRoute `Sidebar.tsx` és `Header.tsx` fájljai). Az oldalak az
építőelemeiket a `@/shared/components` modulból (a `packages/ui-kit` alatt szállított Keak CI UI Kit adapterei)
vagy a készlet komponens-alútvonalairól (`@omniroute/ui-kit/table`, `…/page-header`) importálják, az ikonokat pedig
az `` elemen keresztül (`ICON_MAP` → Lucide). A téma (alapértelmezés szerint `system`, világos/sötét) és a tokenek
a készletből származnak a `src/app/globals.css` fájlban található hídon keresztül. Részletek: `docs/architecture/DESIGN_SYSTEM.md`.
## Magas szintű rendszerkörnyezet
```mermaid
flowchart LR
subgraph Clients[Fejlesztői kliensek]
C1[Claude Code]
C2[Codex CLI]
C3[OpenClaw / Droid / Cline / Continue / Roo]
C4[Egyedi OpenAI-kompatibilis kliensek]
BROWSER[Böngészőalapú irányítópult]
end
subgraph Router[OmniRoute helyi folyamat]
API[V1 kompatibilitási API\n/v1/*]
DASH[Irányítópult + felügyeleti API\n/api/*]
CORE[SSE + fordítási mag\nopen-sse + src/sse]
DB[(storage.sqlite)]
UDB[(használati táblák + naplóösszetevők)]
end
subgraph Upstreams[Forrásoldali szolgáltatók]
P1[OAuth-szolgáltatók\nClaude/Codex/Gemini/Qoder/GitHub/Kiro/Cursor/Antigravity]
P2[API-kulcsos szolgáltatók\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA]
P3[Kompatibilis csomópontok\nOpenAI-kompatibilis / Anthropic-kompatibilis]
end
subgraph Cloud[Opcionális felhőszinkronizálás]
CLOUD[Felhőszinkronizálási végpont\nNEXT_PUBLIC_CLOUD_URL]
end
C1 --> API
C2 --> API
C3 --> API
C4 --> API
BROWSER --> DASH
API --> CORE
DASH --> DB
CORE --> DB
CORE --> UDB
CORE --> P1
CORE --> P2
CORE --> P3
DASH --> CLOUD
```
## Alapvető futásidejű összetevők
## 1) API- és útválasztási réteg (Next.js alkalmazásútvonalak)
Fő könyvtárak:
- `src/app/api/v1/*` és `src/app/api/v1beta/*` a kompatibilitási API-khoz
- `src/app/api/*` a felügyeleti és konfigurációs API-khoz
- A `next.config.mjs` fájlban található Next-átírások a `/v1/*` útvonalakat az `/api/v1/*` útvonalakra képezik le
Fontos kompatibilitási útvonalak:
- `src/app/api/v1/chat/completions/route.ts`
- `src/app/api/v1/messages/route.ts`
- `src/app/api/v1/responses/route.ts`
- `src/app/api/v1/models/route.ts` — tartalmazza a `custom: true` értékkel rendelkező egyedi modelleket
- `src/app/api/v1/embeddings/route.ts` — embeddingek generálása (6 szolgáltató)
- `src/app/api/v1/images/generations/route.ts` — képgenerálás (több mint 4 szolgáltató, beleértve az Antigravity/Nebius szolgáltatókat)
- `src/app/api/v1/messages/count_tokens/route.ts`
- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — szolgáltatónként elkülönített csevegési végpont
- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — szolgáltatónként elkülönített embeddingvégpont
- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — szolgáltatónként elkülönített képgenerálási végpont
- `src/app/api/v1beta/models/route.ts`
- `src/app/api/v1beta/models/[...path]/route.ts`
Felügyeleti területek:
- Hitelesítés/beállítások: `src/app/api/auth/*`, `src/app/api/settings/*`
- Szolgáltatók/kapcsolatok: `src/app/api/providers*`
- Szolgáltatói csomópontok: `src/app/api/provider-nodes*`
- Egyedi modellek: `src/app/api/provider-models` (GET/POST/DELETE)
- Modellkatalógus: `src/app/api/models/route.ts` (GET)
- Proxykonfiguráció: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
- OAuth: `src/app/api/oauth/*`
- Kulcsok/álnevek/kombinációk/árképzés: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
- Használat: `src/app/api/usage/*`
- Szinkronizálás/felhő: `src/app/api/sync/*`, `src/app/api/cloud/*`
- CLI-eszközök segédfunkciói: `src/app/api/cli-tools/*`
- IP-szűrő: `src/app/api/settings/ip-filter` (GET/PUT)
- Gondolkodási keret: `src/app/api/settings/thinking-budget` (GET/PUT)
- Rendszerüzenet: `src/app/api/settings/system-prompt` (GET/PUT)
- Tömörítés: `src/app/api/settings/compression`, `src/app/api/compression/*`, valamint
`src/app/api/context/*`
- Munkamenetek: `src/app/api/sessions` (GET)
- Sebességkorlátok: `src/app/api/rate-limits` (GET)
- Hibatűrés: `src/app/api/resilience` (GET/PATCH) — kérési várólista, kapcsolat-visszahűtés, szolgáltatói megszakító és visszahűtésre várási konfiguráció
- Hibatűrés alaphelyzetbe állítása: `src/app/api/resilience/reset` (POST) — a szolgáltatói megszakítók alaphelyzetbe állítása
- Gyorsítótár-statisztikák: `src/app/api/cache/stats` (GET/DELETE)
- Telemetria: `src/app/api/telemetry/summary` (GET)
- Költségkeret: `src/app/api/usage/budget` (GET/POST)
- Tartalék láncok: `src/app/api/fallback/chains` (GET/POST/DELETE)
- Megfelelőségi audit: `src/app/api/compliance/audit-log` (GET, lapozással + strukturált metaadatokkal)
- Kiértékelések: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
- Szabályzatok: `src/app/api/policies` (GET/POST)
- Szinkronizálási tokenek: `src/app/api/sync/tokens` (GET/POST), `src/app/api/sync/tokens/[id]` (GET/DELETE)
- Konfigurációs csomag: `src/app/api/sync/bundle` (GET, a beállításokról/szolgáltatókról/kombinációkról/kulcsokról készült, ETag-verziózott pillanatkép)
- WebSocket: `src/app/api/v1/ws/route.ts` — Upgrade-kezelő OpenAI-kompatibilis WS-kliensekhez
## 2) SSE + fordítási mag
A fő folyamat moduljai:
- Belépési pont: `src/sse/handlers/chat.ts`
- Alapvető vezérlés: `open-sse/handlers/chatCore.ts`
- Szolgáltatói végrehajtási adapterek: `open-sse/executors/*`
- Formátumfelismerés/szolgáltatói konfiguráció: `open-sse/services/provider.ts`
- Modell feldolgozása/feloldása: `src/sse/services/model.ts`, `open-sse/services/model.ts`
- Fiók-visszaállási logika: `open-sse/services/accountFallback.ts`
- Fordítási nyilvántartás: `open-sse/translator/index.ts`
- Adatfolyam-átalakítások: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
- Használati adatok kinyerése/normalizálása: `open-sse/utils/usageTracking.ts`
- Think-címke elemzője: `open-sse/utils/thinkTagParser.ts`
- Beágyazáskezelő: `open-sse/handlers/embeddings.ts`
- Beágyazási szolgáltatók nyilvántartása: `open-sse/config/embeddingRegistry.ts`
- Képgenerálási kezelő: `open-sse/handlers/imageGeneration.ts`
- Képszolgáltatók nyilvántartása: `open-sse/config/imageRegistry.ts`
- Válaszok megtisztítása: `open-sse/handlers/responseSanitizer.ts`
- Szerepkörök normalizálása: `open-sse/services/roleNormalizer.ts`
Szolgáltatások (üzleti logika):
- Fiókkiválasztás/pontozás: `open-sse/services/accountSelector.ts`
- A kontextus életciklusának kezelése: `open-sse/services/contextManager.ts`
- IP-szűrés kikényszerítése: `open-sse/services/ipFilter.ts`
- Munkamenetek követése: `open-sse/services/sessionManager.ts`
- Kérések deduplikációja: `open-sse/services/signatureCache.ts`
- Rendszerprompt beszúrása: `open-sse/services/systemPrompt.ts`
- Gondolkodási keret kezelése: `open-sse/services/thinkingBudget.ts`
- Helyettesítő karakteres modellútválasztás: `open-sse/services/wildcardRouter.ts`
- Sebességkorlátozás kezelése: `open-sse/services/rateLimitManager.ts`
- Megszakító: `src/shared/utils/circuitBreaker.ts`
- Kontextusátadás: `open-sse/services/contextHandoff.ts` — átadási összefoglaló létrehozása és beszúrása a kontextusközvetítési stratégiához
- Tömörítés: `open-sse/services/compression/*` — proaktív tömörítés a szolgáltatói fordítás előtt;
tartalmazza a Caveman-szabályokat, RTK-szűrőket, egymásra épülő feldolgozási láncokat, tömörítési kombinációkat, statisztikákat és ellenőrzést
- Codex-kvótalekérő: `open-sse/services/codexQuotaFetcher.ts` — lekéri a Codex-kvótát a kontextusközvetítési átadási döntésekhez
- Várakozási időt figyelembe vevő újrapróbálkozás: `src/sse/services/cooldownAwareRetry.ts` — modellenkénti, várakozási idővel működő újrapróbálkozások konfigurálható `requestRetry` / `maxRetryIntervalSec` értékekkel
- Biztonságos kimenő lekérés: `src/shared/network/safeOutboundFetch.ts` — védett szolgáltató-/modell-lekérés SSRF-védelemmel, privát URL-ek blokkolásával, újrapróbálkozással és időtúllépéssel
- Kimenő URL-ek védelme: `src/shared/network/outboundUrlGuard.ts` — gazdagép-ellenőrzések a szolgáltatói URL-eken; a `src/shared/network/outboundUrlGuardPolicy.ts` az `OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS`, az `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS` és a hozzájuk tartozó irányítópulti kapcsolók alapján választja ki a módot (lásd: `docs/reference/ENVIRONMENT.md`)
- Szolgáltatói kérések alapértelmezett értékei: `open-sse/services/providerRequestDefaults.ts` — szolgáltatói szintű `maxTokens`, `temperature`, `thinkingBudgetTokens` alapértékek
- GLM szolgáltatói konstansok: `open-sse/config/glmProvider.ts` — megosztott GLM-modellek, kvóta-URL-ek, GLMT-időtúllépési és alapértelmezett értékek
- Antigravity felsőbb réteg: `open-sse/config/antigravityUpstream.ts` — alap-URL és felderítési útvonal konstansai
- Codex-klienskonstansok: `open-sse/config/codexClient.ts` — verziózott felhasználóiügynök- és kliensverzió-értékek
- Modellaliasok kiinduló adatai: `src/lib/modelAliasSeed.ts` — indításkor több mint 30, proxy-dialektusok közötti aliast tölt be
A tartományi réteg moduljai:
- Költségszabályok/keretek: `src/domain/costRules.ts`
- Visszaállási szabályzat: `src/domain/fallbackPolicy.ts`
- Kombinációfeloldó: `src/domain/comboResolver.ts`
- Kizárási szabályzat: `src/domain/lockoutPolicy.ts`
- Szabályzatmotor: `src/domain/policyEngine.ts` — központosított kizárás → keret → visszaállás kiértékelés
- Hibakód-katalógus: `src/shared/constants/errorCodes.ts`
- Kérésazonosító: `src/shared/utils/requestId.ts`
- Lekérési időtúllépés: `src/shared/utils/fetchTimeout.ts`
- Kéréstelemetria: `src/shared/utils/requestTelemetry.ts`
- Megfelelőség/audit: `src/lib/compliance/index.ts`
- Kiértékelés-futtató: `src/lib/evals/evalRunner.ts`
- Tartományi állapot tartós tárolása: `src/lib/db/domainState.ts` — SQLite CRUD a visszaállási láncokhoz, keretekhez, költségelőzményekhez, kizárási állapothoz és megszakítókhoz
OAuth-szolgáltatói modulok (27 különálló fájl a `src/lib/oauth/providers/` alatt):
- Nyilvántartási index: `src/lib/oauth/providers/index.ts`
- Egyedi szolgáltatók: `agy.ts`, `antigravity.ts`, `claude.ts`, `cline.ts`, `codebuddy-cn.ts`, `codebuddy-intl.ts`, `codex.ts`, `cursor.ts`, `devin-desktop.ts`, `ghe-copilot.ts`, `github.ts`, `gitlab-duo.ts`, `grok-cli-oauth.ts`, `grok-cli.ts`, `kilocode.ts`, `kimi-coding.ts`, `kiro.ts`, `muse-code.ts`, `openference.ts`, `qoder.ts`, `trae.ts`, `workbuddy.ts`, `xai-oauth.ts`, `zed-hosted.ts`, `zed.ts`
- Megosztott segédfüggvények: `codebuddyDeviceAuth.ts` (CodeBuddy CN/nemzetközi eszközfolyamat), `museCodeDeviceResponse.ts`
- Vékony burkolómodul: `src/lib/oauth/providers.ts` — újraexportál az egyedi modulokból
## 5) Beágyazott szolgáltatások (v3.8.4)
Az OmniRoute képes telepíteni, felügyelni és útválasztási célként használni a helyben futó, **beágyazott szolgáltatásoknak** nevezett AI-eszközfolyamatokat. Öt ilyen szolgáltatást tartalmaz: 9Router, CLIProxyAPI, Bifrost, Mux és Dario.
Architekturális rétegek:
- **Felhasználói felület** (`/dashboard/providers/services`) — kétlapos oldal életciklus-vezérlőkkel,
élő naplóközvetítéssel, API-kulcsok kezelésével, valamint (a 9Router esetében) egy belső
fordított proxyn keresztül beágyazott natív felhasználói felülettel.
- **API** (`/api/services/{name}/*`) — 11 végpont a 9Routerhez, 10 a CLIProxyAPI-hoz, valamint egyenként 8 a Bifrost / Mux / Dario szolgáltatásokhoz,
valamennyi **LOCAL_ONLY** besorolással (17. szigorú szabály). Egy megosztott `GET /api/services/[name]/logs`
SSE-végpont szolgálja ki mindkét szolgáltatást.
- **Felügyelő** (`src/lib/services/`) — az általános `ServiceSupervisor` osztály a
`child_process.spawn` köré épül, egy 5 MB-os körkörös puffert tart fenn az SSE-naplóközvetítéshez, továbbá állapotellenőrzési
ciklust, atomi műveleti zárolást és SIGTERM→SIGKILL szabályos leállítást biztosít.
A `bootstrap.ts` a folyamat indításakor csatlakoztatja az összes konfigurált szolgáltatást.
- **Szolgáltató/végrehajtó** (`open-sse/executors/ninerouter.ts`) — a 9Router valódi
szolgáltatóként érhető el. A modellek `9router/{sub}/{model}` előtagot kapnak, és 5 percenként
szinkronizálódnak a 9Router `/v1/models` végpontjáról.
Részletes leírás: `docs/frameworks/EMBEDDED-SERVICES.md`
## Főbb alrendszerek (v3.8.0)
### A. Automatikus kombinált motor
Az Auto Combo dinamikusan pontozza és kiválasztja az útválasztási célokat a kérés időpontjában, ahelyett, hogy statikus kombináció-definícióra hagyatkozna. Ez hajtja a `auto/*` modell előtagcsaládot.
- Motorbemenet: `open-sse/services/autoCombo/` (`autoComboEngine.ts`, `scoringEngine.ts`, `virtualFactory.ts`, `modePacks.ts`)
- Feloldó: `src/domain/comboResolver.ts` ( `auto/` előtag automatikus felismerése)
- Műszerfal: `/dashboard/auto-combo`
- Telemetria: `auto_combo_decisions` SQLite asztal
Főbb képességek:
- **20 útválasztási stratégia** (prioritás, súlyozott, kitöltési sorrend, kör-robin, P2C, véletlenszerű, legkevésbé használt, költségoptimalizált, reset-aware, reset-window, headroom, kvótával súlyozott, szigorú véletlenszerű,** auto** , lkgp, kontextusra optimalizált, gyorsítótárra optimalizált, környezetrelé,** fúzió** , pipeline) — auto a 3.8.0-s v3.8.0 címsor kiegészítése; `fusion` (panel fan-out + bíró szintézis, `open-sse/services/fusion.ts`) új a v3.8.36-ban.
- **16 faktoros pontozás** : kvóta, egészség, fordított költség, fordított késleltetés, feladat-illesztés és még tíz. A faktorok kanonikus táblázata és alapértelmezett súlyaik [`docs/routing/AUTO-COMBO.md`](../routing/AUTO-COMBO.md) — -ben élnek, ha itt újra megismételjük, ez egy második helyet adna az elavulásnak.
- **Virtuális gyár** efemer kombinációkat valósít meg, ha nem létezik megfelelő nevű kombináció, így a jelölteket egészséges aktív szolgáltatói kapcsolatokból szerzi be.
- **Automatikus előtagok** : `auto/coding`, `auto/cheap`, `auto/fast`, `auto/offline`, `auto/smart`, `auto/lkgp` — mindegyiket hangolt súlyprofil támogatja.
- **6 mód csomag** : `ship-fast`, `cost-saver`, `quality-first`, `offline-friendly`, `reliability-first` és `chaos-mode` — előre beállított súlykonfigurációk, amelyek a műszerfalról hívhatók. (Nem tévesztendő össze a fenti `auto/*` előtagokkal, amelyek kérésidő-változatok.)
A teljes algoritmus részleteit (tényezőképletek, súlyhangolás) lásd: [`docs/routing/AUTO-COMBO.md`](../routing/AUTO-COMBO.md).
### B. Felhőügynökök
A Cloud Agents a harmadik féltől származó kódügynök-platformokat (Codex Cloud, Devin, Jules) egységes, adatbázis-támogatott feladatéletciklus mögé burkolja. Minden feladat creation/inspection végpontja felügyeleti hitelesítést igényel.
- Modul gyökér: `src/lib/cloudAgent/` (`baseAgent.ts`, `registry.ts`, `api.ts`, `types.ts`, `db.ts`, plusz ügynökönkénti alkönyvtárak `agents/` alatt)
- Ügynökönkénti megvalósítások: `agents/codex/`, `agents/devin/`, `agents/jules/`
- Nyilvános végpontok: `/api/v1/agents/tasks/*` (list/create/get/cancel)
- Felügyeleti végpontok: `/api/cloud/*` (kiépítés, állapot, köteg)
- Műszerfal: `/dashboard/cloud-agents`
- Tárolás: `cloud_agent_tasks` asztal
Az ügynökönkénti kiépítés és OAuth sajátosságaiért lásd: [`docs/frameworks/CLOUD_AGENT.md`](../frameworks/CLOUD_AGENT.md).
### C. Védőkorlátok
A védőkorlát modul egy üzem közben újratölthető köztes szoftverréteg, amely megvizsgálja a kéréseket és válaszokat PII, a gyors befecskendezés és a nem biztonságos látástartalom szempontjából. A szabálysértések rövidre zárják a kérést HTTP vel** 503** plusz egy strukturált hibakód, amely lehetővé teszi a későbbi hívók számára, hogy újra próbálkozzanak vagy elágazjanak.
- Modul gyökér: `src/lib/guardrails/` (`base.ts`, `registry.ts`, `piiMasker.ts`, `promptInjection.ts`, `visionBridge.ts`, `visionBridgeHelpers.ts`)
- Hot reload: a rendszerleíró adatbázis figyeli a konfigurációs változásokat, és a helyén újraépíti a láncot
- Bekötési pontok: chatkezelő belépés, képgeneráló kezelő, válaszfertőtlenítő
- HTTP szerződés: a jogsértések `503` ként jelennek meg `error.code = "GUARDRAIL_VIOLATION"` vel
A szabálykészlet létrehozásáról és a küszöbhangolásról lásd: [`docs/security/GUARDRAILS.md`](../security/GUARDRAILS.md).
### D. Domain réteg
A `src/domain/` névtér központosítja a politikai döntéseket, így az útvonalkezelőknek nem kell maguknak összeállítaniuk lockout/budget/fallback logikát.
- Irányelvmotor: `src/domain/policyEngine.ts` — egyetlen belépési pont a végrehajtás előtti értékeléshez (zárolási → költségvetési → tartalék rendelés)
- Költségszabályok: `src/domain/costRules.ts`
- Tartalék irányelv: `src/domain/fallbackPolicy.ts`
- Kizárási politika: `src/domain/lockoutPolicy.ts`
- Címke alapú útválasztás: `src/domain/tagRouter.ts`
- Kombinált feloldó: `src/domain/comboResolver.ts` — feloldja a kombinált neveket, az auto/\* előtagokat és a helyettesítő karakteres modellcélokat a konkrét végrehajtási tervekhez
- Connection/model szabálycsatlakozó: `src/domain/connectionModelRules.ts`
- Modell elérhetőségi pillanatképek: `src/domain/modelAvailability.ts`
- Szolgáltató lejáratának követése: `src/domain/providerExpiration.ts`
- Kvóta gyorsítótár: `src/domain/quotaCache.ts`. A szolgáltatók kvótaablakokat adnak hozzá és távolítanak el (OpenAI elvetette az 5 órás Codex ablakot egyes terveknél), így a szolgáltató adapterét leolvasó használat teljesnek igazolja (`quotasComplete`, lásd `src/lib/usage/usageReading.ts`) a fiók teljes ablakkészlete: a korábban ismert, de abból hiányzó ablak megszűnik, a gyorsítótárban, a rependedqrekordban, a restartqreffates. megmaradt a Codex kvóta állapota és Claude `quota_snapshots` sávjaiban. A részleges bizonyítékok (válaszfejlécek, elavult másolatok) csak az általuk hordozott ablakokat frissítik.
- Lebomlási állapot: `src/domain/degradation.ts`
- Konfiguráció audit: `src/domain/configAudit.ts`
- OmniRoute válasz metaadat-készítő: `src/domain/omnirouteResponseMeta.ts`
- Értékelési alrendszer: `src/domain/assessment/` — időszakos értékelési munkák
### E. Engedélyezési folyamat
Az engedélyezési folyamat minden bejövő kérelmet osztályoz, és a megfelelő házirend-láncot alkalmazza a feladás előtt.
- Csővezeték-bevezetés: `src/server/authz/pipeline.ts`
- Kérelem osztályozója: `src/server/authz/classify.ts` — megkülönbözteti a nyilvános kompatibilitási útvonalakat a kezelési útvonalaktól
- Közút leltár: `src/shared/constants/publicApiRoutes.ts`
- Irányelvek: `src/server/authz/policies/` — összeállítható predikátumok (`requireApiKey`, `requireManagement`, `requireFreshAuth` stb.)
- Fejléc segédprogramok: `src/server/authz/headers.ts`
- Állítási segéd: `src/server/authz/assertAuth.ts`
- A kérés szövegkörnyezete: `src/server/authz/context.ts`
A nyilvános és a felügyeleti útvonalak kemény határvonalat jelentenek: agent/cooldown APIs és a szolgáltatói mutációk kezelési hitelesítést igényelnek (HTTP 401, ha hiányzik).
A teljes útvonal-besorolási szabályokat lásd: [`docs/architecture/AUTHZ_GUIDE.md`](./AUTHZ_GUIDE.md).
### F. Workflow FSM és Task-Aware Router
Egy véges állapotú gép által vezérelt útválasztó, amely a kombinált kiválasztás fölé rétegezve irányítja a forgalmat az észlelt munkafolyamat szakasza (tervezés, végrehajtás, áttekintés) és a háttérfeladat-affinitás alapján.
- Munkafolyamat FSM: `open-sse/services/workflowFSM.ts`
- Feladat-tudatos útválasztó: `open-sse/services/taskAwareRouter.ts`
- Háttérfeladat detektor: `open-sse/services/backgroundTaskDetector.ts`
- Szándékos osztályozó: `open-sse/services/intentClassifier.ts`
A FSM átmenetek beépülnek az Auto Combo pontozásába, és az olcsóbb modellek felé hajlanak background/automation feladatokhoz, és az erősebb modellek felé az interaktív planning/review fordulatokhoz.
### G. Szolgáltató-specifikus rugalmasság
Számos szolgáltató dedikált rugalmassági és lopakodó modulokat szállít, amelyek visszatartják a globális megszakító / kapcsolat lehűlés / modellzár réteget:
- Antigravity 429 motor: `open-sse/services/antigravity429Engine.ts` (az identitás elforgatása, a válaszfejlécek tisztítása, credits/version nyomon követése `antigravityCredits.ts`, `antigravityHeaderScrub.ts`, `antigravityHeaders.ts`, `antigravityIdentity.ts`, `antigravityVersion.ts` segítségével)
- Antigravity 429 őr: `open-sse/services/antigravity429Guard.ts` (az upstream 429-ek kérésenkénti költségvetése az összes gazdagépen, `ANTIGRAVITY_MAX_429_ATTEMPTS`; a visszautasított test azonos újraküldésére helyileg válaszol; `src/sse/handlers/chat.ts` nem indítja újra az ilyen kérést a lehűlés-tudatos újrapróbálkozáson keresztül)
- ModelScope kvótapolitika: `open-sse/services/modelscopePolicy.ts`
- Claude kód CCH (kompatibilitási csatorna kézfogás): `open-sse/services/claudeCodeCCH.ts`, plusz `claudeCodeCompatible.ts`, `claudeCodeConstraints.ts`, `claudeCodeExtraRemap.ts`, `claudeCodeToolRemapper.ts`
- Claude Kód ujjlenyomat formázás: `open-sse/services/claudeCodeFingerprint.ts`
- Claude Kódzavarás: `open-sse/services/claudeCodeObfuscation.ts`
A teljes rejtett játékkönyvet és a működési útmutatást lásd `docs/security/STEALTH_GUIDE.md` (git; nincs `/docs`-be fordítva).
### H. Webhooks, érvelési gyorsítótár, olvasási gyorsítótár
- **Webhookok** — kimenő feladás provider/account/task eseményekhez.
- Diszpécser: `src/lib/webhookDispatcher.ts`
- Tárhely: `webhooks` SQLite asztal ( `src/lib/db/webhooks.ts` n keresztül)
- Irányítópult: `/dashboard/webhooks` (előfizetések, titkok, újrapróbálkozási előzmények)
- Az eseménytaxonómiával és az újrapróbálkozási szemantikával kapcsolatban lásd [`docs/frameworks/WEBHOOKS.md`](../frameworks/WEBHOOKS.md).
- **Érvelési gyorsítótár** — újrajátszható érvelési blokkok olyan szolgáltatók számára, amelyek gondolkodási tokeneket (Claude, GLMT stb.) bocsátanak ki, így az egymást követő fordulatok kihagyhatják az újragondolást.
- DB réteg: `src/lib/db/reasoningCache.ts`
- Szolgáltatási réteg: `open-sse/services/reasoningCache.ts`
- A visszajátszás szemantikáját lásd: [`docs/routing/REASONING_REPLAY.md`](../routing/REASONING_REPLAY.md).
- **Olvassa el a gyorsítótárat** — rövid élettartamú válaszgyorsítótár, amelyet aláírással kulcsolnak, és a törött upstream SDKs azonos újrapróbálkozásainak összecsukására használják.
- DB réteg: `src/lib/db/readCache.ts`
- Statisztikák végpontja: `GET /api/cache/stats`, műszerfal `/dashboard/cache` nél
## 3) Perzisztenciaréteg
Elsődleges állapot-adatbázis (SQLite):
- Alapinfrastruktúra: `src/lib/db/core.ts` (better-sqlite3, migrációk, WAL)
- Adatbázis-hozzáférés: közvetlenül az egyes `src/lib/db/*` modulokat importálja (a régi `localDb.ts` gyűjtőmodult eltávolították)
- fájl: `${DATA_DIR}/storage.sqlite` (vagy `$XDG_CONFIG_HOME/omniroute/storage.sqlite`, ha be van állítva, egyébként `~/.omniroute/storage.sqlite`)
- entitások (táblák + KV-névterek): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**
Használati adatok perzisztenciája:
- homlokzat: `src/lib/usageDb.ts` (felbontott modulok a `src/lib/usage/*` alatt)
- SQLite-táblák a `storage.sqlite` fájlban: `usage_history`, `call_logs`, `proxy_logs`
- az opcionális fájlartefaktumok kompatibilitási és hibakeresési célból megmaradnak (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`)
- a régi JSON-fájlokat az indítási migrációk SQLite-ba migrálják, ha jelen vannak
Tartományi állapotadatbázis (SQLite):
- `src/lib/db/domainState.ts` — CRUD-műveletek a tartományi állapothoz
- Táblák (létrehozásuk helye: `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
- Azonnali adatbázisba írást alkalmazó gyorsítótár-minta: futásidőben a memóriabeli Mapek a mérvadók; a módosítások szinkron módon íródnak az SQLite-ba; hidegindításkor az állapot visszaáll az adatbázisból
## 4) Hitelesítés + biztonsági felületek
- Vezérlőpult cookie-alapú hitelesítése: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
- API-kulcsok létrehozása/ellenőrzése: `src/shared/utils/apiKey.ts`
- A szolgáltatói titkos adatok a `providerConnections` bejegyzésekben vannak tartósan tárolva
- Kimenő proxy támogatása az `open-sse/utils/proxyFetch.ts` (környezeti változók) és az `open-sse/utils/networkProxy.ts` (szolgáltatónként vagy globálisan konfigurálható) révén
- SSRF-/kimenő URL-védelem: `src/shared/network/outboundUrlGuard.ts` — gazdagép-ellenőrzések a szolgáltatói hívásoknál és a webhook-célpontoknál; a módot a `src/shared/network/outboundUrlGuardPolicy.ts` határozza meg (jelzők: `docs/reference/ENVIRONMENT.md`)
- Futásidejű környezeti ellenőrzés: `src/lib/env/runtimeEnv.ts` — Zod-séma az összes környezeti változóhoz, amely az indítási hibákat/figyelmeztetéseket is megjeleníti
- Szinkronizálási tokenek: `src/lib/db/syncTokens.ts` — hatókörrel rendelkező tokenek a konfigurációscsomag-letöltési végpontokhoz; a `sync_tokens` SQLite-tábla tárolja őket (`024_create_sync_tokens.sql` migráció)
- WebSocket-kézfogás hitelesítése: `src/lib/ws/handshake.ts` — API-kulccsal vagy munkamenet-cookie-val ellenőrzi a WS-frissítési kéréseket
- Az élő vezérlőpult WebSocket-hitelesítése: `src/server/ws/liveServer.ts` — a segédfolyamat (a `LIVE_WS_PORT` porton) vezérlőpult-munkamenet-cookie-t vagy kezelési hatókörrel (`manage`/`admin`) rendelkező Bearer API-kulcsot fogad el; a csak következtetésre jogosító kulcsokat elutasítja. A belső `POST /__omniroute_event` közzétevő végpont csak akkor fogad el loopback társtól érkező kapcsolatot, ha nincs jelen proxyugrást jelző fejléc (`x-forwarded-*`, `x-real-ip`, `forwarded`, `via`)
## 5) Felhőalapú szinkronizálás
- Ütemező inicializálása: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts`
- Időszakos feladat: `src/shared/services/cloudSyncScheduler.ts`
- Időszakos feladat: `src/shared/services/modelSyncScheduler.ts`
- Vezérlési útvonal: `src/app/api/sync/cloud/route.ts`
## Kérés életciklusa (`/v1/chat/completions`)
```mermaid
sequenceDiagram
autonumber
participant Client as CLI/SDK-kliens
participant Route as /api/v1/chat/completions
participant Chat as src/sse/handlers/chat
participant Core as open-sse/handlers/chatCore
participant Model as Modellfeloldó
participant Auth as Hitelesítőadat-kiválasztó
participant Exec as Szolgáltatói végrehajtó
participant Prov as Felsőbb szintű szolgáltató
participant Stream as Adatfolyam-átalakító
participant Usage as usageDb
Client->>Route: POST /v1/chat/completions
Route->>Chat: handleChat(request)
Chat->>Model: modell vagy kombináció értelmezése/feloldása
alt Kombinált modell
Chat->>Chat: végighaladás a kombináció modelljein (handleComboChat)
end
Chat->>Auth: getProviderCredentials(provider)
Auth-->>Chat: aktív fiók + tokenek/API-kulcs
Chat->>Core: handleChatCore(body, modelInfo, credentials)
Core->>Core: forrásformátum észlelése
Core->>Core: kérés átalakítása a célformátumra
Core->>Exec: execute(provider, transformedBody)
Exec->>Prov: felsőbb szintű API-hívás
Prov-->>Exec: SSE-/JSON-válasz
Exec-->>Core: válasz + metaadatok
alt 401/403
Core->>Exec: refreshCredentials()
Exec-->>Core: frissített tokenek
Core->>Exec: kérés újbóli megkísérlése
end
Core->>Stream: adatfolyam átalakítása/normalizálása a kliensformátumra
Stream-->>Client: SSE-adatrészletek / JSON-válasz
Stream->>Usage: használati adatok kinyerése + előzmények/napló tárolása
```
## Kombinációs + fiók-visszalépési folyamat
```mermaid
flowchart TD
A[Beérkező modellkarakterlánc] --> B{Kombinációnév?}
B -- Igen --> C[Kombináció modelljeinek sorrendjének betöltése]
B -- Nem --> D[Egyetlen modell útvonala]
C --> E[N. modell kipróbálása]
E --> F[Szolgáltató/modell feloldása]
D --> F
F --> G[Fiók hitelesítő adatainak kiválasztása]
G --> H{Elérhetők a hitelesítő adatok?}
H -- Nem --> I[Szolgáltató nem érhető el eredmény visszaadása]
H -- Igen --> J[Kérés végrehajtása]
J --> K{Sikeres?}
K -- Igen --> L[Válasz visszaadása]
K -- Nem --> M{Visszalépésre jogosító hiba?}
M -- Nem --> N[Hiba visszaadása]
M -- Igen --> O[Fiók megjelölése átmenetileg nem elérhetőként]
O --> P{Van másik fiók a szolgáltatóhoz?}
P -- Igen --> G
P -- Nem --> Q{Kombinációban van következő modell?}
Q -- Igen --> E
Q -- Nem --> R[Mindegyik nem érhető el eredmény visszaadása]
```
A visszalépési döntéseket az `open-sse/services/accountFallback.ts` vezérli az állapotkódok és a hibaüzenetek heurisztikus elemzése alapján. A kombinációs útválasztás egy további védelmi feltételt ad hozzá: a szolgáltatóhoz kötődő 400-as hibákat, például a felsőbb szintű tartalomblokkolási és szerepkör-ellenőrzési hibákat, modellszintű helyi hibaként kezeli, így a kombináció későbbi célmodelljei továbbra is futtathatók.
## OAuth-bevezetés és tokenfrissítési életciklus
```mermaid
sequenceDiagram
autonumber
participant UI as Irányítópult felhasználói felülete
participant OAuth as /api/oauth/[provider]/[action]
participant ProvAuth as Szolgáltató hitelesítési kiszolgálója
participant DB as localDb
participant Test as /api/providers/[id]/test
participant Exec as Szolgáltató-végrehajtó
UI->>OAuth: GET engedélyezés vagy eszközkód
OAuth->>ProvAuth: hitelesítési/eszközfolyamat létrehozása
ProvAuth-->>OAuth: hitelesítési URL vagy eszközkód-adat
OAuth-->>UI: folyamatadatok
UI->>OAuth: POST csere vagy lekérdezés
OAuth->>ProvAuth: tokencsere/lekérdezés
ProvAuth-->>OAuth: hozzáférési/frissítési tokenek
OAuth->>DB: createProviderConnection(oauth adatok)
OAuth-->>UI: siker + kapcsolat azonosítója
UI->>Test: POST /api/providers/[id]/test
Test->>Exec: hitelesítő adatok ellenőrzése / opcionális frissítés
Exec-->>Test: érvényes vagy frissített tokeninformációk
Test->>DB: állapot/tokenek/hibák frissítése
Test-->>UI: ellenőrzési eredmény
```
Az élő forgalom közbeni frissítés az `open-sse/handlers/chatCore.ts` fájlban, a végrehajtó `refreshCredentials()` függvényén keresztül történik.
## Felhőszinkronizálási életciklus (engedélyezés / szinkronizálás / letiltás)
```mermaid
sequenceDiagram
autonumber
participant UI as Végpontoldal felhasználói felülete
participant Sync as /api/sync/cloud
participant DB as localDb
participant Cloud as Külső felhőszinkronizálás
participant Claude as ~/.claude/settings.json
UI->>Sync: POST action=enable
Sync->>DB: cloudEnabled=true beállítása
Sync->>DB: API-kulcs meglétének biztosítása
Sync->>Cloud: POST /sync/{machineId} (szolgáltatók/álnevek/kombinációk/kulcsok)
Cloud-->>Sync: szinkronizálási eredmény
Sync->>Cloud: GET /{machineId}/v1/verify
Sync-->>UI: engedélyezve + ellenőrzési állapot
UI->>Sync: POST action=sync
Sync->>Cloud: POST /sync/{machineId}
Cloud-->>Sync: távoli adatok
Sync->>DB: újabb helyi tokenek/állapot frissítése
Sync-->>UI: szinkronizálva
UI->>Sync: POST action=disable
Sync->>DB: cloudEnabled=false beállítása
Sync->>Cloud: DELETE /sync/{machineId}
Sync->>Claude: az ANTHROPIC_BASE_URL visszaállítása helyire (ha szükséges)
Sync-->>UI: letiltva
```
Az időszakos szinkronizálást a `CloudSyncScheduler` indítja el, amikor a felhő engedélyezve van.
## Adatmodell és tárolási térkép
```mermaid
erDiagram
SETTINGS ||--o{ PROVIDER_CONNECTION : controls
PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : backs_compatible_provider
PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emits_usage
SETTINGS {
boolean cloudEnabled
number stickyRoundRobinLimit
boolean requireLogin
string password_hash
string fallbackStrategy
json rateLimitDefaults
json providerProfiles
}
PROVIDER_CONNECTION {
string id
string provider
string authType
string name
number priority
boolean isActive
string apiKey
string accessToken
string refreshToken
string expiresAt
string testStatus
string lastError
string rateLimitedUntil
json providerSpecificData
}
PROVIDER_NODE {
string id
string type
string name
string prefix
string apiType
string baseUrl
}
MODEL_ALIAS {
string alias
string targetModel
}
COMBO {
string id
string name
string[] models
}
API_KEY {
string id
string name
string key
string machineId
}
USAGE_ENTRY {
string provider
string model
number prompt_tokens
number completion_tokens
string connectionId
string timestamp
}
CUSTOM_MODEL {
string id
string name
string providerId
}
PROXY_CONFIG {
string global
json providers
}
IP_FILTER {
string mode
string[] allowlist
string[] blocklist
}
THINKING_BUDGET {
string mode
number customBudget
string effortLevel
}
SYSTEM_PROMPT {
boolean enabled
string prompt
string position
}
```
Fizikai tárolófájlok:
- elsődleges futásidejű adatbázis: `${DATA_DIR}/storage.sqlite`
- kérésnapló sorai: `${DATA_DIR}/log.txt` (kompatibilitási/hibakeresési melléktermék)
- strukturált hívásiadat-archívumok: `${DATA_DIR}/call_logs/`
- opcionális fordítói/kérés-hibakeresési munkamenetek: `/logs/...`
## Telepítési topológia
```mermaid
flowchart LR
subgraph LocalHost[Fejlesztői gép]
CLI[CLI-eszközök]
Browser[Vezérlőpult böngészője]
end
subgraph ContainerOrProcess[OmniRoute futtatókörnyezet]
Next[Next.js-kiszolgáló\nPORT=20128]
Core[SSE-mag + végrehajtók]
MainDB[(storage.sqlite)]
UsageDB[(használati táblák + naplózási melléktermékek)]
end
subgraph External[Külső szolgáltatások]
Providers[MI-szolgáltatók]
SyncCloud[Felhőszinkronizálási szolgáltatás]
end
CLI --> Next
Browser --> Next
Next --> Core
Next --> MainDB
Core --> MainDB
Core --> UsageDB
Core --> Providers
Next --> SyncCloud
```
## Modulok leképezése (döntéskritikus)
### Útvonal- és API-modulok
- `src/app/api/v1/*`, `src/app/api/v1beta/*`: kompatibilitási API-k
- `src/app/api/v1/providers/[provider]/*`: szolgáltatónként elkülönített útvonalak (csevegés, beágyazások, képek)
- `src/app/api/providers*`: szolgáltatók CRUD-műveletei, ellenőrzése és tesztelése
- `src/app/api/provider-nodes*`: egyéni kompatibilis csomópontok kezelése
- `src/app/api/provider-models`: egyéni modellek kezelése (CRUD)
- `src/app/api/models/route.ts`: modellkatalógus API-ja (álnevek + egyéni modellek)
- `src/app/api/oauth/*`: OAuth-/eszközkód-folyamatok
- `src/app/api/keys*`: helyi API-kulcsok életciklusa
- `src/app/api/models/alias`: álnevek kezelése
- `src/app/api/combos*`: tartalék kombinációk kezelése
- `src/app/api/pricing`: árképzési felülbírálások a költségszámításhoz
- `src/app/api/settings/proxy`: proxykonfiguráció (GET/PUT/DELETE)
- `src/app/api/settings/proxy/test`: kimenő proxy kapcsolatának tesztelése (POST)
- `src/app/api/usage/*`: használati és naplózási API-k
- `src/app/api/sync/*` + `src/app/api/cloud/*`: felhőszinkronizálás és felhőorientált segédfunkciók
- `src/app/api/cli-tools/*`: helyi CLI-konfigurációk írói/ellenőrzői
- `src/app/api/settings/ip-filter`: IP-engedélyezési/tiltási lista (GET/PUT)
- `src/app/api/settings/thinking-budget`: gondolkodási tokenkeret konfigurációja (GET/PUT)
- `src/app/api/settings/system-prompt`: globális rendszerprompt (GET/PUT)
- `src/app/api/settings/compression`: globális tömörítési beállítások (GET/PUT)
- `src/app/api/compression/*`: tömörítési előnézet, szabálymetaadatok és nyelvi csomagok
- `src/app/api/context/caveman/config`: Caveman-beállítások álneve (GET/PUT)
- `src/app/api/context/rtk/*`: RTK-konfiguráció, szűrőkatalógus, tesztvégpont és nyers kimenet helyreállítása
- `src/app/api/context/combos*`: tömörítési kombinációk CRUD-műveletei és útválasztási kombinációk hozzárendelései
- `src/app/api/context/analytics`: tömörítéselemzési álnév
- `src/app/api/sessions`: aktív munkamenetek listázása (GET)
- `src/app/api/rate-limits`: fiókonkénti sebességkorlátozási állapot (GET)
- `src/app/api/sync/tokens`: szinkronizálási tokenek CRUD-műveletei (GET/POST)
- `src/app/api/sync/tokens/[id]`: szinkronizálási token lekérése/törlése (GET/DELETE)
- `src/app/api/sync/bundle`: konfigurációs csomag letöltése (GET, ETag-verziókezelés)
- `src/app/api/v1/ws`: WebSocket-frissítés kezelője OpenAI-kompatibilis WS-kliensekhez
### Útválasztási és végrehajtási mag
- `src/sse/handlers/chat.ts`: kérés feldolgozása, kombinációk kezelése, fiókkiválasztási ciklus
- `open-sse/handlers/chatCore.ts`: fordítás, végrehajtó kiválasztása, újrapróbálkozás/frissítés kezelése, adatfolyam beállítása
- `open-sse/executors/*`: szolgáltatóspecifikus hálózati és formátumkezelési viselkedés
### Fordítási nyilvántartás és formátumkonverterek
- `open-sse/translator/index.ts`: fordítóregiszter és vezérlés
- Kérésfordítók: `open-sse/translator/request/*` (9 modul — `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`)
- Válaszfordítók: `open-sse/translator/response/*` (11 modul — `claude-to-openai`, `cursor-to-openai`, `gemini-to-claude`, `gemini-to-openai`, `kiro-to-openai`, `openai-responses`, `openai-to-antigravity`, `openai-to-claude`, `openai-to-gemini`, `openai-to-gemini-sse`, `responsesToolItem`)
- Segédmodulok: `open-sse/translator/helpers/*` (12 modul — `claudeHelper`, `geminiHelper`, `geminiToolsSanitizer`, `jsonUtil`, `markdownBoundary`, `maxTokensHelper`, `openaiHelper`, `responsesApiHelper`, `schemaCoercion`, `strictSystemHoist`, `toolCallHelper`, `toolCallShim`)
- Formátumkonstansok: `open-sse/translator/formats.ts`
- Rendszerindítás és regiszter: `open-sse/translator/bootstrap.ts`, `open-sse/translator/registry.ts`
- Képformátum-segédmodulok: `open-sse/translator/image/`
### Perzisztencia
- `src/lib/db/*`: tartós konfiguráció-/állapottárolás és tartományi perzisztencia SQLite-on
- `src/lib/db/*`: az egyes modulokat közvetlenül importáld — nincs gyűjtőmodul (a régi `localDb.ts` újraexportáló réteget eltávolították)
- `src/lib/usageDb.ts`: használati előzmények és hívásnaplók homlokzata az SQLite-táblák felett
## Szolgáltatói végrehajtók lefedettsége (stratégiaminta)
Minden szolgáltató rendelkezik egy specializált, a `BaseExecutor` osztályt kiterjesztő végrehajtóval (az `open-sse/executors/base.ts` fájlban), amely biztosítja az URL-ek összeállítását, a fejlécek létrehozását, az exponenciális késleltetésű újrapróbálkozást, a hitelesítő adatok frissítéséhez szükséges hookokat, valamint az `execute()` vezénylési metódust.
| Végrehajtó | Szolgáltató(k) | Speciális kezelés |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA stb. | Dinamikus URL-/fejléc-konfiguráció szolgáltatónként |
| `AntigravityExecutor` | Google Antigravity | Egyéni projekt-/munkamenet-azonosítók, Retry-After feldolgozása, 429-es hibák elfedése |
| `AzureOpenAIExecutor` | Azure OpenAI | Telepítésalapú útválasztás, az api-version lekérdezési paraméter kikényszerítése |
| `BlackboxWebExecutor` | Blackbox AI (webes mód) | Webes munkamenet visszafejtése TLS-ujjlenyomat-emulációval |
| `ClaudeIdentityExecutor` | Claude.ai (CCH-útvonal) | Korlátozási és eszköz-újraleképezési folyamatok, ujjlenyomat-formálás |
| `CliProxyApiExecutor` | CLIProxyAPI-kompatibilis szolgáltatók | Egyéni hitelesítés- és protokollkezelés |
| `CloudflareAiExecutor` | Cloudflare Workers AI | Fiókazonosító beillesztése, Neurons-alapú használatkövetés |
| `CodexExecutor` | OpenAI Codex | Rendszerutasításokat illeszt be, kikényszeríti az érvelési erőfeszítés szintjét |
| `ChatGptWebCodexExecutor` | ChatGPT Web (Codex) | Böngésző-munkamenetes Responses API-híd szál-/fordulórögzítéssel |
| `CommandCodeExecutor` | Command Code | OAuth és munkamenetenkénti fejlécrotáció |
| `CursorExecutor` | Cursor IDE | ConnectRPC protokoll, Protobuf-kódolás, kérések aláírása ellenőrzőösszeggel |
| `DevinCliExecutor` | Devin CLI | A Devin-feladatok életciklusának összekapcsolása felhőügynök-modulon keresztül |
| `GithubExecutor` | GitHub Copilot | Copilot-token frissítése, VSCode-ot utánzó fejlécek |
| `GitlabExecutor` | GitLab Duo | GitLab OAuth és projekthatókörű útválasztás |
| `GlmExecutor` | Z.AI GLM (beleértve a `glmt` előbeállítást) | Gondolkodási keretet figyelembe vevő működés, GLMT előbeállítási állandók |
| `GrokWebExecutor` | xAI Grok web | Webes munkamenet visszafejtése, módválasztás (gondolkodó/normál) |
| `KieExecutor` | KIE | Egyéni tokenkibocsátás változó munkamenet-horgonyokkal |
| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream bináris formátum → SSE-konverzió |
| `MuseSparkWebExecutor` | Muse Spark (web) | Webes munkamenet visszafejtése képüzenetek áthidalásával |
| `NlpCloudExecutor` | NLP Cloud | Szolgáltatóspecifikus kérés-törzsstruktúra |
| `OpenCodeExecutor` | OpenCode | AI SDK-kompatibilis szolgáltató-beállítás |
| `PerplexityWebExecutor` | Perplexity web | Webes munkamenet visszafejtése a csevegés folytatásához |
| `PetalsExecutor` | Petals elosztott inferencia | Decentralizált rajalapú útválasztás |
| `PollinationsExecutor` | Pollinations AI | Nem igényel API-kulcsot, sebességkorlátozott kérések |
| `QoderExecutor` | Qoder AI | PAT- és OAuth-támogatás, többmodelles ingyenes csomag |
| `VertexExecutor` | Google Vertex AI | Szolgáltatásfiók-alapú hitelesítés, régióalapú végpontok |
| `DevinDesktopExecutor` | Devin Desktop | Importált API-kulcs és Connect-protobuf csevegésstreamelés |
Minden más szolgáltató (beleértve az egyéni kompatibilis csomópontokat is) a `DefaultExecutor` végrehajtót használja.
## Szolgáltatói kompatibilitási mátrix
> **Megjegyzés:** Az alábbi mátrix az OmniRoute v3.8.0 rendszerben regisztrált 351 szolgáltató reprezentatív mintája.
> A hiteles és folyamatosan frissített listát lásd az
> [`docs/reference/PROVIDER_REFERENCE.md`](../reference/PROVIDER_REFERENCE.md) (automatikusan generált) fájlban, vagy a mérvadó
> `src/shared/constants/providers.ts` forrásban (betöltéskor Zod által validálva).
| Szolgáltató | Formátum | Hitelesítés | Streamelés | Nem streamelt | Tokenfrissítés | Használati API |
| ------------------- | ---------------- | ------------------------- | ---------------- | ------------- | -------------- | --------------------------- |
| Claude | claude | API-kulcs / OAuth | ✅ | ✅ | ✅ | ⚠️ Csak adminisztrátoroknak |
| Gemini | gemini | API-kulcs / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Teljes kvóta-API |
| OpenAI | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| Codex | openai-responses | OAuth | ✅ kötelező | ❌ | ✅ | ✅ Sebességkorlátok |
| ChatGPT Web (Codex) | openai-responses | Böngésző-munkamenet | ✅ kötelező | ❌ | ❌ | ❌ |
| GitHub Copilot | openai | OAuth + Copilot-token | ✅ | ✅ | ✅ | ✅ Kvótapillanatképek |
| Cursor | cursor | Egyéni ellenőrzőösszeg | ✅ | ✅ | ❌ | ❌ |
| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Használati korlátok |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ Kérésenként |
| Kilo Code | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Cline | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Kimi Coding | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| OpenRouter | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| GLM/Kimi/MiniMax | claude | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| DeepSeek | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| Groq | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| xAI (Grok) | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| Mistral | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| Perplexity | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| Together AI | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| Fireworks AI | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| Cerebras | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| Cohere | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| NVIDIA NIM | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| Cloudflare AI | openai | API-token + fiókazonosító | ✅ | ✅ | ❌ | ❌ |
| Pollinations | openai | Nincs (nem kell kulcs) | ✅ | ✅ | ❌ | ❌ |
| Scaleway AI | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| LongCat | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| Ollama Cloud | openai | API-kulcs (opcionális) | ✅ | ✅ | ❌ | ❌ |
| HuggingFace | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| Nebius | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| SiliconFlow | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| Hyperbolic | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| Vertex AI | gemini | Szolgáltatásfiók | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
| Command Code | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Kérésenként |
| Z.AI / GLM | openai | API-kulcs / OAuth | ✅ | ✅ | ❌ | ❌ |
| GLMT (előbeállítás) | claude | API-kulcs | ✅ | ✅ | ❌ | ⚠️ Kérésenként |
| Kimi Coding | openai | OAuth / API-kulcs | ✅ | ✅ | ✅ | ❌ |
| KIE | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| Devin Desktop | openai | Importált API-kulcs | ✅ (Connect→SSE) | ✅ | ❌ | ⚠️ Kérésenként |
| GitLab Duo | openai | OAuth (GitLab) | ✅ | ✅ | ✅ | ❌ |
| Devin CLI | openai | Helyi CLI-bejelentkezés | ✅ | ✅ | ❌ | ✅ Feladat-API |
| Codex Cloud | openai-responses | OAuth | ✅ | ❌ | ✅ | ✅ Sebességkorlátok |
| Jules | openai | OAuth | ✅ | ✅ | ✅ | ✅ Feladat-API |
| AgentRouter | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| Grok-Web | openai | Munkamenetsüti | ✅ | ✅ | ❌ | ❌ |
| Perplexity-Web | openai | Munkamenetsüti | ✅ | ✅ | ❌ | ❌ |
| BlackBox-Web | openai | Munkamenetsüti + TLS | ✅ | ✅ | ❌ | ❌ |
| Muse-Spark-Web | openai | Munkamenetsüti | ✅ | ✅ | ❌ | ❌ |
| ModelScope | openai | API-kulcs | ✅ | ✅ | ❌ | ⚠️ Kvótaszabályzat |
| BazaarLink | openai | API-kulcs | ✅ | ✅ | ❌ | ❌ |
| Petals | openai | Nincs | ✅ | ✅ | ❌ | ❌ |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ Kérésenként |
| OpenCode (Go/Zen) | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| CLIProxyAPI | openai | Egyéni | ✅ | ✅ | ❌ | ❌ |
## Formátumfordítási lefedettség
Az észlelt forrásformátumok:
- `openai`
- `openai-responses`
- `claude`
- `gemini`
A célformátumok:
- OpenAI chat/Responses
- Claude
- Gemini/Antigravity-boríték
- Kiro
- Cursor
A fordítások **az OpenAI-t használják központi formátumként** — minden konverzió az OpenAI-on mint köztes formátumon keresztül történik:
```
Forrásformátum → OpenAI (központ) → Célformátum
```
A fordítások kiválasztása dinamikusan, a forrásadat-struktúra alakja és a célszolgáltató formátuma alapján történik.
További feldolgozási rétegek a fordítási folyamatban:
- **Válaszok tisztítása** — Eltávolítja a nem szabványos mezőket az OpenAI-formátumú válaszokból (streamelt és nem streamelt válaszokból egyaránt), így biztosítva az SDK-k szigorú követelményeinek való megfelelést
- **Szerepkörök normalizálása** — A nem OpenAI-célok esetén a `developer` szerepkört `system` szerepkörré alakítja; a rendszerszerepkört elutasító modelleknél (GLM, ERNIE) a `system` szerepkört a `user` szerepkörbe egyesíti
- **Think címkék kinyerése** — A tartalomban található `...` blokkokat feldolgozza, és a `reasoning_content` mezőbe helyezi
- **Strukturált kimenet** — Az OpenAI `response_format.json_schema` formátumát a Gemini `responseMimeType` + `responseSchema` formátumára alakítja
## Támogatott API-végpontok
| Végpont | Formátum | Kezelő |
| -------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------ |
| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` |
| `POST /v1/messages` | Claude Messages | Ugyanaz a kezelő (automatikusan észlelve) |
| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` |
| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` |
| `GET /v1/embeddings` | Modelllista | API-útvonal |
| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` |
| `GET /v1/images/generations` | Modelllista | API-útvonal |
| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedikált szolgáltatónkénti végpont modellvalidációval |
| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedikált szolgáltatónkénti végpont modellvalidációval |
| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedikált szolgáltatónkénti végpont modellvalidációval |
| `POST /v1/messages/count_tokens` | Claude tokenszámlálás | API-útvonal |
| `GET /v1/models` | OpenAI modelllista | API-útvonal (chat-, beágyazási, kép- és egyéni modellek) |
| `GET /api/models/catalog` | Katalógus | Az összes modell szolgáltató és típus szerint csoportosítva |
| `POST /v1beta/models/*:streamGenerateContent` | Natív Gemini | API-útvonal |
| `GET/PUT/DELETE /api/settings/proxy` | Proxykonfiguráció | Hálózati proxy konfigurációja |
| `POST /api/settings/proxy/test` | Proxykapcsolat | A proxy állapotát és kapcsolódását ellenőrző végpont |
| `GET/POST/DELETE /api/provider-models` | Szolgáltatói modellek | Az egyéni és felügyelt elérhető modellek mögötti szolgáltatói modellmetaadatok |
## Megkerülési kezelő
A megkerülési kezelő (`open-sse/utils/bypassHandler.ts`) elfogja a Claude CLI ismert „eldobható” kéréseit — a bemelegítő pingeket, a címkinyeréseket és a tokenszámlálásokat —, és egy **hamis választ** ad vissza anélkül, hogy felhasználná a felsőbb szintű szolgáltató tokenjeit. Ez csak akkor aktiválódik, ha a `User-Agent` tartalmazza a `claude-cli` értéket.
## Kérések naplózása és műtermékek
A régebbi, fájlalapú kérésnaplózó (`open-sse/utils/requestLogger.ts`) csak a visszamenőleges kompatibilitás érdekében maradt meg. A jelenlegi futásidejű szerződés a következőket használja:
- `APP_LOG_TO_FILE=true` az alkalmazás- és auditnaplókhoz, amelyek a `/logs/` alatt kerülnek tárolásra
- SQLite-alapú hívásnapló-rekordok a `call_logs` táblában
- `${DATA_DIR}/call_logs/YYYY-MM-DD/...` műtermékek, ha a hívásnaplózási folyamat engedélyezve van
## Hibamódok és ellenálló képesség
## 1) Fiók-/szolgáltató-elérhetőség
- kapcsolati várakozási idő az újrapróbálható felsőbb szintű hibák után
- tartalék fiók használata a kérés sikertelen lezárása előtt
- kombinált modellre való tartalék átváltás, amikor az aktuális modell-/szolgáltatói útvonal lehetőségei kimerültek
## 2) Token lejárata
- előzetes ellenőrzés és frissítés újrapróbálással a frissíthető szolgáltatóknál
- 401/403 esetén újrapróbálás a frissítési kísérlet után az alapvető feldolgozási útvonalon
## 3) Adatfolyam-biztonság
- kapcsolatbontást figyelembe vevő adatfolyam-vezérlő
- fordítási adatfolyam az adatfolyam végi pufferürítés és a `[DONE]` kezelésével
- tartalék használatbecslés, ha a szolgáltató használati metaadatai hiányoznak
## 4) Felhőszinkronizálás korlátozott működése
- a szinkronizálási hibák megjelennek, de a helyi futtatókörnyezet tovább működik
- az ütemező újrapróbálásra képes logikával rendelkezik, de az időszakos végrehajtás jelenleg alapértelmezés szerint egyszeri szinkronizálási kísérletet indít
## 5) Adatintegritás
- SQLite-sémamigrációk és automatikus frissítési horgok indításkor
- visszamenőleges kompatibilitási útvonal a régi JSON → SQLite migrációhoz
## 6) SSRF / kimenő URL-ek védelme
- a `src/shared/network/outboundUrlGuard.ts` blokkol minden privát, visszacsatolási és helyi kapcsolati cél-URL-t, mielőtt azok elérnék a szolgáltatói végrehajtókat
- a szolgáltatói modellek felderítési és ellenőrzési útvonalai a `src/shared/network/safeOutboundFetch.ts` fájlt használják, amely minden kimenő kérés előtt alkalmazza a védelmet
- a védelmi hibák `URL_GUARD_BLOCKED` hibakóddal és HTTP 422-es állapotkóddal jelennek meg, és a `providerAudit.ts` segítségével bekerülnek a megfelelőségi auditnaplóba
## Megfigyelhetőség és üzemeltetési jelzések
A futásidejű láthatóság forrásai:
- konzolnaplók a `src/sse/utils/logger.ts` fájlból
- kérésenkénti összesített használati adatok az SQLite-ban (`usage_history`, `call_logs`, `proxy_logs`)
- négyszakaszos, részletes adattartalom-rögzítés az SQLite-ban (`request_detail_logs`), ha `settings.detailed_logs_enabled=true`
- szöveges kérésállapot-napló a `log.txt` fájlban (opcionális/kompatibilitási)
- opcionális alkalmazásnapló-fájlok a `logs/` alatt, ha `APP_LOG_TO_FILE=true`
- opcionális kérésműtermékek a `${DATA_DIR}/call_logs/` alatt, ha a hívásnaplózási folyamat engedélyezve van
- irányítópulti használati végpontok (`/api/usage/*`) a felhasználói felület számára
A részletes kérés-adattartalom rögzítése irányított hívásonként legfeljebb négy JSON-adattartalmi szakaszt tárol:
- a klienstől fogadott nyers kérés
- a ténylegesen a felsőbb szintre küldött, átalakított kérés
- a szolgáltató JSON-ként rekonstruált válasza; az adatfolyamban továbbított válaszok a végső összefoglalóra és az adatfolyam metaadataira tömörítve kerülnek tárolásra
- az OmniRoute által visszaadott végső kliensválasz; az adatfolyamban továbbított válaszok ugyanebben a tömörített összefoglaló-formában kerülnek tárolásra
## Biztonsági szempontból érzékeny határok
- A JWT-titok (`JWT_SECRET`) biztosítja az irányítópult munkamenetsütijének ellenőrzését/aláírását
- A kezdeti jelszó rendszerindítási beállítását (`INITIAL_PASSWORD`) explicit módon kell konfigurálni az első futtatáskor történő kiépítéshez
- Az API-kulcs HMAC-titka (`API_KEY_SECRET`) biztosítja a generált helyi API-kulcs formátumát
- A szolgáltatói titkok (API-kulcsok/tokenek) a helyi adatbázisban vannak tárolva, és fájlrendszerszinten kell védeni őket
- A felhőszinkronizálási végpontok API-kulcsos hitelesítésre és gépazonosító-szemantikára támaszkodnak
## Környezeti és futtatási mátrix
A kód által aktívan használt környezeti változók:
- Alkalmazás/hitelesítés: `JWT_SECRET`, `INITIAL_PASSWORD`
- Tárolás: `DATA_DIR`
- Opcionális tárolásialap-felülbírálás (Linux/macOS rendszeren, ha a `DATA_DIR` nincs beállítva): `XDG_CONFIG_HOME`
- Biztonsági kivonatolás: `API_KEY_SECRET`, `MACHINE_ID_SALT`
- Naplózás: `APP_LOG_TO_FILE`, `APP_LOG_RETENTION_DAYS`, `CALL_LOG_RETENTION_DAYS`
- Szinkronizálási/felhőbeli URL-kezelés: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
- Kimenő proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` és kisbetűs változataik
- SOCKS5-funkciójelzők: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
- Platform-/futtatókörnyezet-segédváltozók (nem alkalmazásspecifikus konfiguráció): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
## Ismert architekturális megjegyzések
1. A `usageDb` és a `localDb` ugyanazt az alapkönyvtár-házirendet használja (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`), a régi fájlok migrációjával.
2. A `/api/v1/route.ts` ugyanarra az egységes katalóguskészítőre delegál, amelyet a `/api/v1/models` is használ (`src/app/api/v1/models/catalog.ts`), így elkerülhető a szemantikai eltérés.
3. A kérésnaplózó engedélyezés esetén a teljes fejlécet és törzset kiírja; a naplókönyvtárat érzékeny adatként kell kezelni.
4. A felhőbeli működés a `NEXT_PUBLIC_BASE_URL` helyes beállításától és a felhővégpont elérhetőségétől függ.
5. Az `open-sse/` könyvtár `@omniroute/open-sse` **npm workspace csomagként** van közzétéve. A forráskód a `@omniroute/open-sse/...` útvonalon importálja (a Next.js `transpilePackages` oldja fel). A dokumentumban szereplő fájlútvonalak a következetesség érdekében továbbra is az `open-sse/` könyvtárnevet használják.
6. Az irányítópult diagramjai **Recharts** (SVG-alapú) használatával biztosítanak akadálymentes, interaktív analitikai vizualizációkat (modellhasználati oszlopdiagramok, szolgáltatói bontást és sikerességi arányokat tartalmazó táblázatok).
7. Az E2E-tesztek **Playwright** használatával készülnek (`tests/e2e/`), és az `npm run test:e2e` paranccsal futtathatók. Az egységtesztek a **Node.js test runner** használatával készülnek (`tests/unit/`), és az `npm run test:unit` paranccsal futtathatók. A `src/` alatti forráskód **TypeScript** (`.ts`/`.tsx`); az `open-sse/` workspace továbbra is JavaScript (`.js`).
8. A beállítások oldala 7 lapra tagolódik: Általános, Megjelenés, MI, Biztonság, Útválasztás, Hibatűrés, Speciális. A Hibatűrés oldal kizárólag a kérési sort, a kapcsolat-várakoztatást, a szolgáltatói megszakítót és a lehűlés kivárásának viselkedését konfigurálja; a megszakító élő futásidejű állapota az Állapot oldalon jelenik meg.
9. A **Context Relay** stratégia (`context-relay`) két réteg között oszlik meg: a `combo.ts` dönti el, hogy kell-e átadást generálni, a `chat.ts` pedig a fiók feloldása után illeszti be az átadást. Az átadási adatok a `context_handoffs` SQLite-táblában találhatók. Ez a felosztás szándékos, mert csak a `chat.ts` tudja, hogy a tényleges fiók megváltozott-e.
10. A **proxykényszerítés** immár átfogó: a `tokenHealthCheck.ts` kapcsolatonként oldja fel a proxyt, az `/api/providers/validate` a `runWithProxyContext` használatával működik, a `proxyFetch.ts` pedig az `undici.fetch()` függvényt használja a diszpécser-kompatibilitás fenntartásához Node 22 alatt.
11. **Node.js futtatókörnyezet-házirend észlelése**: az `/api/settings/require-login` végpont `nodeVersion` és `nodeCompatible` mezőket ad vissza. A bejelentkezési oldal figyelmeztető sávot jelenít meg, ha a futtatókörnyezet kívül esik a támogatott, biztonságos Node.js-verzióvonalakon.
## Üzemeltetési ellenőrzőlista
- Fordítás forráskódból: `npm run build`
- Docker-kép létrehozása: `docker build -t omniroute .`
- Indítsa el a szolgáltatást, és ellenőrizze a következőket:
- `GET /api/settings`
- `GET /api/v1/models`
- A CLI céljának alap URL-je `http://:20128/v1` legyen, ha `PORT=20128`