# OmniRoute Architecture (Slovenčina)
🌐 **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) · 🇭🇺 [hu](../../../hu/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) · 🇸🇮 [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) · 🇭🇺 [hu](../../../hu/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) · 🇸🇮 [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)
_Naposledy aktualizované: 2026-06-28_
## Zhrnutie
OmniRoute je lokálna smerovacia brána AI a riadiaci panel postavený na Next.js. Poskytuje jeden koncový bod kompatibilný s OpenAI (`/v1/*`) a smeruje prevádzku medzi viacerých upstream poskytovateľov s prekladom, záložným, obnovovaním tokenov a sledovaním používania.
Základné schopnosti:
- Povrch API kompatibilný s OpenAI pre CLI/tools (381 poskytovateľov, 159 spúšťacích modulov)
- preklad Request/response naprieč formátmi poskytovateľov
- Záložná kombinácia modelov (sekvencia viacerých modelov)
- Štruktúrované kombinované kroky (`provider + model + connection`) s riadením runtime podľa `compositeTiers`
- Záložný režim na úrovni účtu (viac účtov na poskytovateľa)
- Predbežná kontrola kvóty a výber účtu P2C s ohľadom na kvóty v hlavnej ceste rozhovoru
- Správa pripojenia poskytovateľa kľúča API OAuth + (27 modulov poskytovateľa OAuth )
- Generovanie vkladania cez `/v1/embeddings` (18 poskytovateľov)
- Generovanie obrázkov prostredníctvom `/v1/images/generations` (10 poskytovateľov +, 20 + modely)
- Prepis zvuku cez `/v1/audio/transcriptions` (18 poskytovateľov)
- Prevod textu na reč cez `/v1/audio/speech` (24 vstavaných poskytovateľov)
- Generovanie videa cez `/v1/videos/generations` (ComfyUI + SD WebUI)
- Generovanie hudby cez `/v1/music/generations` (ComfyUI)
- Vyhľadávanie na webe cez `/v1/search` (20 poskytovateľov)
- Moderácie cez `/v1/moderations`
- Zmena poradia cez `/v1/rerank`
- Myslite na analýzu značiek (`...`) pre modely uvažovania
- Dezinfekcia odozvy pre prísnu kompatibilitu OpenAI SDK
- Normalizácia rolí (systém → vývojára, používateľ systému →) pre kompatibilitu medzi poskytovateľmi
- Konverzia štruktúrovaného výstupu (json_schema → Gemini responseSchema)
- Lokálna stálosť pre poskytovateľov, kľúče, aliasy, kombá, nastavenia, ceny (122 modulov DB )
- sledovanie Usage/cost a zaznamenávanie žiadostí
- Voliteľná cloudová synchronizácia pre multi-device/state synchronizáciu
- IP allowlist/blocklist pre riadenie prístupu API
- Myslenie na správu rozpočtu (passthrough/auto/custom/adaptive)
- Okamžitá injekcia globálneho systému
- Sledovanie relácií a snímanie odtlačkov prstov
- Rozšírené obmedzenie sadzieb na účet s profilmi špecifickými pre poskytovateľov
- Vzor ističa pre odolnosť poskytovateľa
- Ochrana stáda proti hromu s blokovaním mutex
- Cache deduplikácie požiadaviek na základe podpisu
- Vrstva domény: cenové pravidlá, záložná politika, politika blokovania
- Context Relay: súhrny odovzdania relácie pre kontinuitu rotácie účtov
- Trvalosť stavu domény (SQLite zapisovacia vyrovnávacia pamäť pre záložné zdroje, rozpočty, blokovania, ističe)
- Nástroj pravidiel pre centralizované hodnotenie žiadostí (uzamknutie → budget → záložný)
- Požiadajte o telemetriu s agregáciou latencie p50/p95/p99
- Kombinovaná cieľová telemetria a historické kombinované cieľové zdravie cez `combo_execution_key` / `combo_step_id`
- Korelácia ID (X-Request-Id) pre end-to-end sledovanie
- Protokolovanie auditu súladu s odhlásením podľa kľúča API
- Eval rámec pre zabezpečenie kvality LLM
- Panel zdravia so stavom ističa poskytovateľa v reálnom čase
- MCP Server (110 nástrojov) s 3 transportmi (stdio/SSE/Streamable HTTP)
- A2A Server (JSON-RPC 2.0 + SSE) so zručnosťami a životným cyklom úloh
- Pamäťový systém (extrakcia, vstrekovanie, vyhľadávanie, sumarizácia)
- Systém zručností (register, exekútor, sandbox, vstavané zručnosti)
- MITM proxy so správou certifikátov a spracovaním DNS
- Prompt vstrekovanie stráž middleware
- Okamžité kompresné potrubie s Caveman, RTK, skladané potrubia, kompresné kombinácie, jazykové balíky a analýzy
- register ACP (Agent Communication Protocol).
- Modulárni poskytovatelia OAuth (22 samostatných modulov pod `src/lib/oauth/providers/`)
- Uninstall/full-uninstall skripty
- akcia na opravu prostredia OAuth
- most WebSocket pre klientov WS kompatibilných s OpenAI (`/v1/ws`)
- Správa synchronizačných tokenov (issue/revoke, stiahnutie konfiguračného balíka verzie ETag)
- prednastavenie prvotriedneho poskytovateľa GLM Thinking (`glmt`).
- Počítanie hybridných tokenov ( `/messages/count_tokens` na strane poskytovateľa s záložným odhadom)
- Automatické nasadenie modelu alias (30 + krížových proxy dialektových normalizácií pri spustení)
- Bezpečné odchádzajúce načítanie s ochranou SSRF, súkromným blokovaním URL a konfigurovateľným opakovaním
- Opakujú sa pokusy o chat s konfigurovateľnými `requestRetry` a `maxRetryIntervalSec`
- Overenie runtime prostredia pomocou Zod pri spustení
- Audit súladu v2 so stránkovaním, udalosťami CRUD poskytovateľa a protokolovaním overenia blokovaným SSRF
Primárny runtime model:
- Trasy aplikácií Next.js pod `src/app/api/*` implementujú APIs dashboard aj kompatibilitu APIs
- Zdieľané jadro SSE/routing v `src/sse/*` + `open-sse/*` sa stará o vykonávanie poskytovateľa, preklad, streamovanie, záložné zdroje a používanie
## Referenčné diagramy
Kanonické, verzované zdroje Mermaid pre platformu v3.8.0 sa nachádzajú v
[`docs/diagrams/`](../diagrams/README.md). Dva z nich sú pre orientáciu uvedené nižšie;
ostatné sú prepojené z príručiek pre príslušné domény.
> Zdroj: [diagrams/request-pipeline.mmd](../diagrams/request-pipeline.mmd)
> Zdroj: [diagrams/resilience-3layers.mmd](../diagrams/resilience-3layers.mmd) — prepojené aj z
> [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) a referencie odolnosti v `CLAUDE.md`.
## Rozsah a hranice
### Zahrnuté v rozsahu
- Lokálne spustenie brány
- API na správu ovládacieho panela
- Autentifikácia poskytovateľov a obnovenie tokenov
- Preklad požiadaviek a streamovanie SSE
- Lokálny stav + perzistencia údajov o používaní
- Voliteľná orchestrácia cloudovej synchronizácie
### Mimo rozsahu
- Implementácia cloudovej služby za `NEXT_PUBLIC_CLOUD_URL`
- SLA/riadiaca rovina poskytovateľa mimo lokálneho procesu
- Samotné externé binárne súbory CLI (Claude CLI, Codex CLI atď.)
## Rozhranie ovládacieho panela (aktuálne)
Hlavné stránky v priečinku `src/app/(dashboard)/dashboard/`:
- `/dashboard` — rýchly štart + prehľad poskytovateľov
- `/dashboard/endpoint` — proxy koncového bodu + karty MCP + A2A + koncového bodu API
- `/dashboard/providers` — pripojenia k poskytovateľom a prihlasovacie údaje
- `/dashboard/combos` — combo stratégie, šablóny, zostavovač založený na krokoch, pravidlá smerovania modelov, manuálne trvalo uložené poradie
- `/dashboard/auto-combo` — Auto Combo Engine: váhy hodnotenia, balíky režimov, predvoľby virtuálnej továrne, telemetria
- `/dashboard/costs` — agregácia nákladov a prehľad cien
- `/dashboard/analytics` — analytika používania, vyhodnotenia, stav cieľov combo stratégií
- `/dashboard/limits` — riadenie kvót a frekvencie požiadaviek
- `/dashboard/cli-tools` — úvodné nastavenie CLI, detekcia runtime prostredia, generovanie konfigurácie
- `/dashboard/agents` — zistení agenti ACP + registrácia vlastných agentov
- `/dashboard/cloud-agents` — úlohy agentov hostovaných v cloude (Codex Cloud, Devin, Jules) a životný cyklus úloh
- `/dashboard/skills` — register zručností A2A, vykonávanie v sandboxe, katalóg vstavaných zručností
- `/dashboard/memory` — kontrola a načítavanie trvalej konverzačnej pamäte
- `/dashboard/webhooks` — odbery odchádzajúcich webhookov, rotácia tajných kľúčov, štatistiky opakovaných pokusov
- `/dashboard/batch` — odosielanie dávkových úloh a ich priebeh
- `/dashboard/cache` — štatistiky priebežne načítavanej vyrovnávacej pamäte a vyrovnávacej pamäte uvažovania, ovládacie prvky vysúvania z pamäte
- `/dashboard/playground` — interaktívne chatové prostredie pre ľubovoľnú nakonfigurovanú combo stratégiu alebo model
- `/dashboard/changelog` — zobrazovač zoznamu zmien v aplikácii (vykresľuje `CHANGELOG.md`)
- `/dashboard/system` — diagnostika runtime prostredia, informácie o verzii, rozhranie na overenie prostredia
- `/dashboard/onboarding` — sprievodca úvodným nastavením pre nové inštalácie
- `/dashboard/media` — experimentálne prostredie pre obrázky, videá a hudbu
- `/dashboard/search-tools` — testovanie poskytovateľov vyhľadávania a história
- `/dashboard/health` — dostupnosť, ističe, limity frekvencie požiadaviek, relácie monitorované z hľadiska kvót
- `/dashboard/logs` — protokoly požiadaviek, proxy, auditu a konzoly
- `/dashboard/settings` — karty systémových nastavení (všeobecné, smerovanie, predvolené nastavenia combo stratégií atď.)
- `/dashboard/context/caveman` — pravidlá kompresie Caveman, jazykové balíky, náhľad a výstupný režim
- `/dashboard/context/rtk` — filtre výstupu príkazov RTK, náhľad a nastavenia bezpečnosti runtime prostredia
- `/dashboard/context/combos` — pomenované kompresné kanály priradené ku combo stratégiám smerovania
- `/dashboard/translator` — kontrola prekladača a náhľad konverzie formátu požiadaviek
- `/dashboard/audit` — prehliadač protokolu auditu súladu so stránkovaním a štruktúrovanými metadátami
- `/dashboard/usage` — prehliadač používania podľa jednotlivých požiadaviek prepojený s `usage_history`
- `/dashboard/compression` — analytika kompresie, štatistiky a priradenie kanálov
- `/dashboard/api-manager` — životný cyklus kľúčov API a oprávnenia modelov
Vrstva používateľského rozhrania: každá stránka sa vykresľuje v rámci jedného shellu — `src/app/(dashboard)/layout.tsx` →
`src/shared/components/layouts/DashboardLayout.tsx` → `DashboardShell.tsx` (`SidebarProvider`/`SidebarInset` zo súpravy,
ako aj `Sidebar.tsx` a `Header.tsx` z OmniRoute). Stránky importujú svoje stavebné prvky
z `@/shared/components` (adaptéry nad vendorizovanou súpravou Keak CI UI Kit v
`packages/ui-kit`) alebo z podciest komponentov súpravy (`@omniroute/ui-kit/table`, `…/page-header`) a
ikony prostredníctvom `` (`ICON_MAP` → Lucide). Motív (predvolene `system`, svetlý/tmavý) a tokeny pochádzajú
zo súpravy prostredníctvom premostenia v `src/app/globals.css`. Podrobnosti: `docs/architecture/DESIGN_SYSTEM.md`.
## Kontext systému na vysokej úrovni
```mermaid
flowchart LR
subgraph Clients[Klienti pre vývojárov]
C1[Claude Code]
C2[Codex CLI]
C3[OpenClaw / Droid / Cline / Continue / Roo]
C4[Vlastné klienty kompatibilné s OpenAI]
BROWSER[Ovládací panel v prehliadači]
end
subgraph Router[Lokálny proces OmniRoute]
API[Kompatibilné API V1\n/v1/*]
DASH[Ovládací panel + API na správu\n/api/*]
CORE[Jadro SSE + prekladu\nopen-sse + src/sse]
DB[(storage.sqlite)]
UDB[(tabuľky používania + artefakty protokolov)]
end
subgraph Upstreams[Poskytovatelia vyššej úrovne]
P1[Poskytovatelia OAuth\nClaude/Codex/Gemini/Qoder/GitHub/Kiro/Cursor/Antigravity]
P2[Poskytovatelia s kľúčom API\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA]
P3[Kompatibilné uzly\nKompatibilné s OpenAI / kompatibilné s Anthropic]
end
subgraph Cloud[Voliteľná synchronizácia s cloudom]
CLOUD[Koncový bod synchronizácie s cloudom\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
```
## Základné komponenty behu systému
## 1) Vrstva API a smerovania (aplikačné trasy Next.js)
Hlavné adresáre:
- `src/app/api/v1/*` a `src/app/api/v1beta/*` pre kompatibilné API
- `src/app/api/*` pre API na správu a konfiguráciu
- Prepisy Next v `next.config.mjs` mapujú `/v1/*` na `/api/v1/*`
Dôležité trasy kompatibility:
- `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` — zahŕňa vlastné modely s `custom: true`
- `src/app/api/v1/embeddings/route.ts` — generovanie embeddingov (6 poskytovateľov)
- `src/app/api/v1/images/generations/route.ts` — generovanie obrázkov (viac než 4 poskytovatelia vrátane Antigravity/Nebius)
- `src/app/api/v1/messages/count_tokens/route.ts`
- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — vyhradený chat pre jednotlivých poskytovateľov
- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — vyhradené embeddingy pre jednotlivých poskytovateľov
- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — vyhradené obrázky pre jednotlivých poskytovateľov
- `src/app/api/v1beta/models/route.ts`
- `src/app/api/v1beta/models/[...path]/route.ts`
Oblasti správy:
- Overovanie/nastavenia: `src/app/api/auth/*`, `src/app/api/settings/*`
- Poskytovatelia/pripojenia: `src/app/api/providers*`
- Uzly poskytovateľov: `src/app/api/provider-nodes*`
- Vlastné modely: `src/app/api/provider-models` (GET/POST/DELETE)
- Katalóg modelov: `src/app/api/models/route.ts` (GET)
- Konfigurácia proxy: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
- OAuth: `src/app/api/oauth/*`
- Kľúče/aliasy/kombinácie/ceny: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
- Používanie: `src/app/api/usage/*`
- Synchronizácia/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*`
- Pomocné nástroje CLI: `src/app/api/cli-tools/*`
- Filter IP: `src/app/api/settings/ip-filter` (GET/PUT)
- Rozpočet na uvažovanie: `src/app/api/settings/thinking-budget` (GET/PUT)
- Systémová výzva: `src/app/api/settings/system-prompt` (GET/PUT)
- Kompresia: `src/app/api/settings/compression`, `src/app/api/compression/*` a
`src/app/api/context/*`
- Relácie: `src/app/api/sessions` (GET)
- Limity frekvencie: `src/app/api/rate-limits` (GET)
- Odolnosť: `src/app/api/resilience` (GET/PATCH) — front požiadaviek, obdobie čakania pripojenia, istič poskytovateľa, konfigurácia čakania na skončenie obdobia
- Resetovanie odolnosti: `src/app/api/resilience/reset` (POST) — resetovanie ističov poskytovateľov
- Štatistiky vyrovnávacej pamäte: `src/app/api/cache/stats` (GET/DELETE)
- Telemetria: `src/app/api/telemetry/summary` (GET)
- Rozpočet: `src/app/api/usage/budget` (GET/POST)
- Reťazce záložných možností: `src/app/api/fallback/chains` (GET/POST/DELETE)
- Audit súladu: `src/app/api/compliance/audit-log` (GET, so stránkovaním + štruktúrovanými metadátami)
- Vyhodnotenia: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
- Zásady: `src/app/api/policies` (GET/POST)
- Synchronizačné tokeny: `src/app/api/sync/tokens` (GET/POST), `src/app/api/sync/tokens/[id]` (GET/DELETE)
- Konfiguračný balík: `src/app/api/sync/bundle` (GET, snímka nastavení/poskytovateľov/kombinácií/kľúčov s verziami ETag)
- WebSocket: `src/app/api/v1/ws/route.ts` — obslužná rutina Upgrade pre klientov WS kompatibilných s OpenAI
## 2) SSE + jadro prekladu
Hlavné moduly toku:
- Vstup: `src/sse/handlers/chat.ts`
- Základná orchestrácia: `open-sse/handlers/chatCore.ts`
- Adaptéry vykonávania poskytovateľov: `open-sse/executors/*`
- Detekcia formátu/konfigurácia poskytovateľa: `open-sse/services/provider.ts`
- Parsovanie/rozlíšenie modelu: `src/sse/services/model.ts`, `open-sse/services/model.ts`
- Logika záložného účtu: `open-sse/services/accountFallback.ts`
- Register prekladov: `open-sse/translator/index.ts`
- Transformácie streamov: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
- Extrakcia/normalizácia využitia: `open-sse/utils/usageTracking.ts`
- Parser značiek premýšľania: `open-sse/utils/thinkTagParser.ts`
- Obsluha embeddingov: `open-sse/handlers/embeddings.ts`
- Register poskytovateľov embeddingov: `open-sse/config/embeddingRegistry.ts`
- Obsluha generovania obrázkov: `open-sse/handlers/imageGeneration.ts`
- Register poskytovateľov obrázkov: `open-sse/config/imageRegistry.ts`
- Sanitizácia odpovedí: `open-sse/handlers/responseSanitizer.ts`
- Normalizácia rolí: `open-sse/services/roleNormalizer.ts`
Služby (biznis logika):
- Výber/hodnotenie účtu: `open-sse/services/accountSelector.ts`
- Správa životného cyklu kontextu: `open-sse/services/contextManager.ts`
- Vynucovanie filtra IP adries: `open-sse/services/ipFilter.ts`
- Sledovanie relácií: `open-sse/services/sessionManager.ts`
- Deduplikácia požiadaviek: `open-sse/services/signatureCache.ts`
- Vkladanie systémového promptu: `open-sse/services/systemPrompt.ts`
- Správa rozpočtu premýšľania: `open-sse/services/thinkingBudget.ts`
- Smerovanie modelov pomocou zástupných znakov: `open-sse/services/wildcardRouter.ts`
- Správa limitov frekvencie: `open-sse/services/rateLimitManager.ts`
- Istič: `src/shared/utils/circuitBreaker.ts`
- Odovzdanie kontextu: `open-sse/services/contextHandoff.ts` — generovanie a vkladanie súhrnu odovzdania pre stratégiu prenosu kontextu
- Kompresia: `open-sse/services/compression/*` — proaktívna kompresia pred prekladom poskytovateľa;
zahŕňa pravidlá Caveman, filtre RTK, zreťazené pipeline, kombinácie kompresie, štatistiky a validáciu
- Načítavanie kvóty Codex: `open-sse/services/codexQuotaFetcher.ts` — načítava kvótu Codex na rozhodovanie o odovzdaní pri prenose kontextu
- Opakovanie zohľadňujúce čas čakania: `src/sse/services/cooldownAwareRetry.ts` — opakované pokusy podľa modelu s konfigurovateľnými `requestRetry` / `maxRetryIntervalSec`
- Bezpečné odchádzajúce načítanie: `src/shared/network/safeOutboundFetch.ts` — chránené načítanie poskytovateľa/modelu s ochranou proti SSRF, blokovaním súkromných URL, opakovaním a časovým limitom
- Ochrana odchádzajúcich URL: `src/shared/network/outboundUrlGuard.ts` — kontroly hostiteľov v URL poskytovateľov; `src/shared/network/outboundUrlGuardPolicy.ts` vyberá režim z `OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS`, `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS` a ich prepínačov na ovládacom paneli (pozri `docs/reference/ENVIRONMENT.md`)
- Predvolené hodnoty požiadaviek poskytovateľa: `open-sse/services/providerRequestDefaults.ts` — predvolené hodnoty `maxTokens`, `temperature`, `thinkingBudgetTokens` na úrovni poskytovateľa
- Konštanty poskytovateľa GLM: `open-sse/config/glmProvider.ts` — zdieľané modely GLM, URL kvót, časový limit a predvolené hodnoty GLMT
- Upstream Antigravity: `open-sse/config/antigravityUpstream.ts` — základná URL a konštanty cesty zisťovania
- Konštanty klienta Codex: `open-sse/config/codexClient.ts` — verziované hodnoty používateľského agenta a verzie klienta
- Počiatočné aliasy modelov: `src/lib/modelAliasSeed.ts` — pri spustení inicializuje viac než 30 aliasov dialektov medzi proxy servermi
Moduly doménovej vrstvy:
- Pravidlá nákladov/rozpočty: `src/domain/costRules.ts`
- Zásady záložného riešenia: `src/domain/fallbackPolicy.ts`
- Riešiteľ kombinácií: `src/domain/comboResolver.ts`
- Zásady uzamknutia: `src/domain/lockoutPolicy.ts`
- Nástroj na vyhodnocovanie zásad: `src/domain/policyEngine.ts` — centralizované vyhodnotenie uzamknutia → rozpočtu → záložného riešenia
- Katalóg chybových kódov: `src/shared/constants/errorCodes.ts`
- ID požiadavky: `src/shared/utils/requestId.ts`
- Časový limit načítania: `src/shared/utils/fetchTimeout.ts`
- Telemetria požiadaviek: `src/shared/utils/requestTelemetry.ts`
- Súlad/audit: `src/lib/compliance/index.ts`
- Spúšťač vyhodnotení: `src/lib/evals/evalRunner.ts`
- Perzistencia stavu domény: `src/lib/db/domainState.ts` — operácie CRUD v SQLite pre reťazce záložných riešení, rozpočty, históriu nákladov, stav uzamknutia a ističe
Moduly poskytovateľov OAuth (27 samostatných súborov v `src/lib/oauth/providers/`):
- Index registra: `src/lib/oauth/providers/index.ts`
- Jednotliví poskytovatelia: `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`
- Zdieľané pomocné moduly: `codebuddyDeviceAuth.ts` (tok zariadenia CodeBuddy CN/intl), `museCodeDeviceResponse.ts`
- Tenký wrapper: `src/lib/oauth/providers.ts` — opätovne exportuje z jednotlivých modulov
## 5) Vstavané služby (v3.8.4)
OmniRoute dokáže inštalovať, riadiť a smerovať požiadavky na lokálne spustené procesy nástrojov AI,
ktoré sa nazývajú **vstavané služby**. Dodáva sa ich päť: 9Router, CLIProxyAPI, Bifrost, Mux a Dario.
Vrstvy architektúry:
- **UI** (`/dashboard/providers/services`) — stránka s dvoma kartami a ovládacími prvkami životného cyklu,
živým streamovaním protokolov, správou kľúčov API a (pre 9Router) vstavaným natívnym používateľským rozhraním
prostredníctvom interného reverzného proxy servera.
- **API** (`/api/services/{name}/*`) — 11 koncových bodov pre 9Router, 10 pre CLIProxyAPI a po 8 pre Bifrost / Mux / Dario,
pričom všetky sú klasifikované ako **LOCAL_ONLY** (pevné pravidlo č. 17). Zdieľaný koncový bod SSE `GET /api/services/[name]/logs`
slúži obom službám.
- **Supervízor** (`src/lib/services/`) — všeobecná trieda `ServiceSupervisor` obaľuje
`child_process.spawn`, udržiava 5 MB kruhovú vyrovnávaciu pamäť na streamovanie protokolov cez SSE, slučku
kontroly stavu, zámok atómovej operácie a korektné ukončenie SIGTERM→SIGKILL.
`bootstrap.ts` prepája všetky nakonfigurované služby pri spustení procesu.
- **Poskytovateľ/exekútor** (`open-sse/executors/ninerouter.ts`) — 9Router je sprístupnený ako
skutočný poskytovateľ. Modely majú predponu `9router/{sub}/{model}` a každých 5 minút sa synchronizujú
z koncového bodu `/v1/models` služby 9Router.
Podrobný rozbor: `docs/frameworks/EMBEDDED-SERVICES.md`
## Hlavné subsystémy (v3.8.0)
### A. Auto Combo Engine
Automatické kombo dynamicky hodnotí a vyberá ciele smerovania v čase vyžiadania, namiesto toho, aby sa spoliehalo na definíciu statického komba. Poháňa rodinu predpon modelu `auto/*`.
- Vstup motora: `open-sse/services/autoCombo/` (`autoComboEngine.ts`, `scoringEngine.ts`, `virtualFactory.ts`, `modePacks.ts`)
- Resolver: `src/domain/comboResolver.ts` (automatická detekcia predpony `auto/` )
- Prístrojová doska: `/dashboard/auto-combo`
- Telemetria: tabuľka `auto_combo_decisions` SQLite
Kľúčové schopnosti:
- **20 stratégií smerovania** (priorita, vážené, vyplňte najskôr, cyklicky, P2C, náhodné, najmenej používané, optimalizované z hľadiska nákladov, s vedomím obnovenia, okno obnovenia, rezerva, vážené kvótami, prísne náhodné,** auto** , lkgp, kontextovo optimalizované, cache optimalizované, kontextové relé,** fúzie** , pipeline) — auto je pridaný nadpis vo verzii 3.8.0; `fusion` (syntéza sudcu + s rozvetveným panelom, `open-sse/services/fusion.ts`) je novinkou vo verzii 3.8.36.
- **16-faktorové bodovanie** : kvóta, zdravie, inverzná cena, inverzná latencia, prispôsobenie úloh a desať ďalších. Kanonická tabuľka faktorov a ich predvolené váhy žije v [`docs/routing/AUTO-COMBO.md`](../routing/AUTO-COMBO.md) — ak ju tu znova uvedieme, priradíme jej druhé miesto na zastaranie.
- **Virtuálna továreň** zhmotňuje efemérne kombá, keď neexistuje žiadne zodpovedajúce pomenované kombo, pričom kandidátov získava zo zdravých aktívnych pripojení poskytovateľov.
- **Automatické predpony** : `auto/coding`, `auto/cheap`, `auto/fast`, `auto/offline`, `auto/smart`, `auto/lkgp` — každý podporený vyladeným hmotnostným profilom.
- **6 balíkov režimov** : prednastavené konfigurácie hmotnosti `ship-fast`, `cost-saver`, `quality-first`, `offline-friendly`, `reliability-first` a `chaos-mode` — dostupné z prístrojovej dosky. (Nezamieňajte si s vyššie uvedenými predponami `auto/*`, ktoré predstavujú varianty v čase vyžiadania.)
Úplné podrobnosti o algoritme (faktorové vzorce, ladenie hmotnosti) nájdete [`docs/routing/AUTO-COMBO.md`](../routing/AUTO-COMBO.md).
### B. Cloud Agenti
Cloud Agents zahŕňa platformy kódových agentov hostené tretími stranami (Codex Cloud, Devin, Jules) do jednotného životného cyklu úloh podporovaných DB. Všetky koncové body creation/inspection úlohy vyžadujú autentifikáciu manažmentu.
- Koreň modulu: `src/lib/cloudAgent/` (`baseAgent.ts`, `registry.ts`, `api.ts`, `types.ts`, `db.ts`, plus podadresáre jednotlivých agentov pod `agents/`)
- Implementácie podľa agentov: `agents/codex/`, `agents/devin/`, `agents/jules/`
- Verejné koncové body: `/api/v1/agents/tasks/*` (list/create/get/cancel)
- Koncové body správy: `/api/cloud/*` (poskytovanie, stav, dávka)
- Prístrojová doska: `/dashboard/cloud-agents`
- Úložný priestor: `cloud_agent_tasks` stôl
Informácie o poskytovaní pre jednotlivých agentov a špecifikách OAuth nájdete [`docs/frameworks/CLOUD_AGENT.md`](../frameworks/CLOUD_AGENT.md).
### C. Zábradlia
Modul zábradlia je vrstva middlewaru, ktorú možno načítať za tepla, ktorá kontroluje požiadavky a odpovede na PII, rýchle vstrekovanie a nebezpečný obsah videnia. Porušenia skratujú požiadavku pomocou HTTP** 503** plus štruktúrovaný chybový kód, ktorý umožňuje následným volajúcim opakovať pokus alebo odbočiť.
- Koreň modulu: `src/lib/guardrails/` (`base.ts`, `registry.ts`, `piiMasker.ts`, `promptInjection.ts`, `visionBridge.ts`, `visionBridgeHelpers.ts`)
- Hot reload: Register sleduje zmeny konfigurácie a prestavuje reťazec na mieste
- Wire-in body: vstup obsluhy chatu, obsluha generovania obrázkov, dezinfekcia odozvy
- zmluva HTTP : porušenia sa objavujú ako `503` so `error.code = "GUARDRAIL_VIOLATION"`
Informácie o vytváraní sady pravidiel a ladení prahu nájdete [`docs/security/GUARDRAILS.md`](../security/GUARDRAILS.md).
### D. Doménová vrstva
Menný priestor `src/domain/` centralizuje rozhodnutia o politike, takže obslužné nástroje smerovania nemusia zostavovať logiku lockout/budget/fallback sami.
- Nástroj politiky: `src/domain/policyEngine.ts` — jediný vstupný bod na vyhodnotenie pred vykonaním (uzamknutie → budget → záložné objednávanie)
- Pravidlá pre náklady: `src/domain/costRules.ts`
- Záložná politika: `src/domain/fallbackPolicy.ts`
- Zásady blokovania: `src/domain/lockoutPolicy.ts`
- Smerovanie založené na značkách: `src/domain/tagRouter.ts`
- Rozkladač komb: `src/domain/comboResolver.ts` — rieši názvy komb, automatické/\* predpony a ciele modelu so zástupnými znakmi na konkrétne plány vykonávania
- Connection/model rule joiner: `src/domain/connectionModelRules.ts`
- Snímky dostupnosti modelu: `src/domain/modelAvailability.ts`
- Sledovanie uplynutia platnosti poskytovateľa: `src/domain/providerExpiration.ts`
- Vyrovnávacia pamäť kvóty: `src/domain/quotaCache.ts`. Poskytovatelia pridávajú a odstraňujú okná kvóty (OpenAI u niektorých plánov zrušilo 5-hodinové okno Codex ), takže používanie čítajúce adaptér poskytovateľa potvrdzuje ako dokončené (`quotasComplete`, pozri `src/lib/usage/usageReading.ts`) je úplným súborom okien účtu: okno známe skôr, ale chýba v ňom, je vyradené, vo vyrovnávacej pamäti, v `quota_snapshots` sa reštartuje (pridaný záznam Codex vyraďovania kvóty), v saturácii kvóty Claude vedierka. Čiastočné dôkazy (hlavičky odpovedí, zastarané kópie) aktualizujú iba okná, ktoré nesie.
- Stav degradácie: `src/domain/degradation.ts`
- Audit konfigurácie: `src/domain/configAudit.ts`
- Zostavovač metadát odpovede OmniRoute : `src/domain/omnirouteResponseMeta.ts`
- Hodnotiaci subsystém: `src/domain/assessment/` — úlohy periodického hodnotenia
### E. Autorizačný kanál
Autorizačný kanál pred odoslaním klasifikuje každú prichádzajúcu požiadavku a aplikuje príslušný reťazec politiky.
- Vstup potrubia: `src/server/authz/pipeline.ts`
- Klasifikátor požiadaviek: `src/server/authz/classify.ts` — rozlišuje verejné cesty kompatibility od ciest správy
- Súpis verejnej trasy: `src/shared/constants/publicApiRoutes.ts`
- Zásady: `src/server/authz/policies/` — skladateľné predikáty (`requireApiKey`, `requireManagement`, `requireFreshAuth` atď.)
- Nástroje hlavičky: `src/server/authz/headers.ts`
- Pomocník pri tvrdení: `src/server/authz/assertAuth.ts`
- Kontext požiadavky: `src/server/authz/context.ts`
Verejné a manažérske cesty sú tvrdou hranicou: agent/cooldown APIs a mutácie poskytovateľa vyžadujú autentizáciu správy (HTTP 401, ak chýba).
Úplné pravidlá klasifikácie ciest nájdete [`docs/architecture/AUTHZ_GUIDE.md`](./AUTHZ_GUIDE.md).
### F. Workflow FSM a Task-Aware Router
Router riadený strojom s konečným stavom vrstvený nad kombinovaným výberom na riadenie prevádzky na základe zistenej fázy pracovného toku (plánovanie, vykonávanie, kontrola) a afinity úlohy na pozadí.
- Pracovný postup FSM: `open-sse/services/workflowFSM.ts`
- Router orientovaný na úlohy: `open-sse/services/taskAwareRouter.ts`
- Detektor úloh na pozadí: `open-sse/services/backgroundTaskDetector.ts`
- Klasifikátor zámerov: `open-sse/services/intentClassifier.ts`
Prechody FSM sa zapájajú do bodovania Auto Combo a smerujú k lacnejším modelom pre úlohy background/automation a smerom k silnejším modelom pre interaktívne obraty planning/review.
### G. Odolnosť špecifická pre poskytovateľa
Niekoľko poskytovateľov dodáva vyhradené moduly odolnosti a utajenia, ktoré spájajú vrstvy globálneho ističa / ochladzovania pripojenia / blokovania modelu:
- motor Antigravity 429: `open-sse/services/antigravity429Engine.ts` (otáča identitu, čistí hlavičky odozvy, riadi sledovanie credits/version cez `antigravityCredits.ts`, `antigravityHeaderScrub.ts`, `antigravityHeaders.ts`, `antigravityIdentity.ts`, `antigravityVersion.ts`)
- Antigravity 429 guard: `open-sse/services/antigravity429Guard.ts` (rozpočet na požiadavku upstream 429 na všetkých hostiteľoch, `ANTIGRAVITY_MAX_429_ATTEMPTS`; identické opätovné odoslanie odmietnutého tela je zodpovedané lokálne; `src/sse/handlers/chat.ts` nereštartuje takúto požiadavku prostredníctvom opätovného pokusu s ohľadom na cooldown)
- politika kvót ModelScope : `open-sse/services/modelscopePolicy.ts`
- Claude kód CCH (kompatibilný kanál handshake): `open-sse/services/claudeCodeCCH.ts`, plus `claudeCodeCompatible.ts`, `claudeCodeConstraints.ts`, `claudeCodeExtraRemap.ts`, `claudeCodeToolRemapper.ts`
- Claude Tvarovanie odtlačkov prstov kódu: `open-sse/services/claudeCodeFingerprint.ts`
- Claude zahmlievanie kódu: `open-sse/services/claudeCodeObfuscation.ts`
Úplnú príručku utajenia a prevádzkové pokyny nájdete `docs/security/STEALTH_GUIDE.md` (git; nie je kompilované do `/docs`).
### H. Webhooks, Reasoning Cache, Read Cache
- **Webhooky** odchádzajúce odoslanie — pre udalosti provider/account/task.
- Dispečer: `src/lib/webhookDispatcher.ts`
- Úložisko: tabuľka `webhooks` SQLite (cez `src/lib/db/webhooks.ts`)
- Informačný panel: `/dashboard/webhooks` (predplatné, tajomstvá, história opakovaných pokusov)
- Taxonómiu udalostí a sémantiku opakovania nájdete [`docs/frameworks/WEBHOOKS.md`](../frameworks/WEBHOOKS.md).
- **Reasoning Cache** — prehrateľné bloky uvažovania pre poskytovateľov, ktorí vysielajú tokeny myslenia (Claude, GLMT atď.), takže po sebe idúce ťahy môžu preskočiť opätovné uvažovanie.
- vrstva DB : `src/lib/db/reasoningCache.ts`
- Servisná vrstva: `open-sse/services/reasoningCache.ts`
- Sémantiku opakovaného prehrávania nájdete [`docs/routing/REASONING_REPLAY.md`](../routing/REASONING_REPLAY.md).
- **Prečítajte si Cache** — krátkodobá vyrovnávacia pamäť odpovedí kľúčovaná podpisom a používaná na zbalenie rovnakých pokusov z nefunkčného upstream SDKs.
- vrstva DB : `src/lib/db/readCache.ts`
- Koncový bod štatistík: `GET /api/cache/stats`, informačný panel na `/dashboard/cache`
## 3) Vrstva perzistencie
Primárna databáza stavu (SQLite):
- Základná infraštruktúra: `src/lib/db/core.ts` (better-sqlite3, migrácie, WAL)
- Prístup k databáze: importujte priamo konkrétne moduly `src/lib/db/*` (pôvodný zlučovací modul `localDb.ts` bol odstránený)
- súbor: `${DATA_DIR}/storage.sqlite` (alebo `$XDG_CONFIG_HOME/omniroute/storage.sqlite`, ak je nastavená, inak `~/.omniroute/storage.sqlite`)
- entity (tabuľky + menné priestory KV): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**
Perzistencia údajov o používaní:
- fasáda: `src/lib/usageDb.ts` (dekomponované moduly v `src/lib/usage/*`)
- Tabuľky SQLite v `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs`
- voliteľné súborové artefakty zostávajú zachované pre kompatibilitu a ladenie (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`)
- staršie súbory JSON sa pri spustení migrujú do SQLite, ak sú prítomné
Databáza stavu domén (SQLite):
- `src/lib/db/domainState.ts` — operácie CRUD pre stav domén
- Tabuľky (vytvorené v `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
- Vzor vyrovnávacej pamäte s priebežným zápisom: mapy v pamäti sú počas behu autoritatívne; zmeny sa zapisujú synchrónne do SQLite; stav sa pri studenom štarte obnoví z databázy
## 4) Autentifikácia + bezpečnostné rozhrania
- Autentifikácia informačného panela pomocou súborov cookie: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
- Generovanie/overovanie kľúčov API: `src/shared/utils/apiKey.ts`
- Tajné údaje poskytovateľov uložené v položkách `providerConnections`
- Podpora odchádzajúceho proxy prostredníctvom `open-sse/utils/proxyFetch.ts` (premenné prostredia) a `open-sse/utils/networkProxy.ts` (konfigurovateľné pre jednotlivých poskytovateľov alebo globálne)
- Ochrana proti SSRF / kontrola odchádzajúcich URL: `src/shared/network/outboundUrlGuard.ts` — kontroly hostiteľov pri volaniach poskytovateľov a cieľoch webhookov; režim pochádza z `src/shared/network/outboundUrlGuardPolicy.ts` (príznaky v `docs/reference/ENVIRONMENT.md`)
- Overovanie premenných prostredia za behu: `src/lib/env/runtimeEnv.ts` — schéma Zod pre všetky premenné prostredia, pričom chyby a upozornenia sa zobrazujú pri spustení
- Synchronizačné tokeny: `src/lib/db/syncTokens.ts` — tokeny s obmedzeným rozsahom pre koncové body na sťahovanie konfiguračných balíkov; používa tabuľku SQLite `sync_tokens` (migrácia `024_create_sync_tokens.sql`)
- Autentifikácia pri nadviazaní spojenia WebSocket: `src/lib/ws/handshake.ts` — overuje požiadavky na prechod na WS pomocou kľúča API alebo súboru cookie relácie
- Autentifikácia živého pripojenia informačného panela cez WebSocket: `src/server/ws/liveServer.ts` — sprievodná služba (port `LIVE_WS_PORT`) prijíma súbor cookie relácie informačného panela alebo kľúč API typu Bearer s rozsahom oprávnení na správu (`manage`/`admin`); kľúče určené iba na inferenciu sú odmietnuté. Jej interný koncový bod publikovania `POST /__omniroute_event` prijíma partnerov z lokálnej slučky iba vtedy, keď nie je prítomná žiadna hlavička prechodu cez proxy (`x-forwarded-*`, `x-real-ip`, `forwarded`, `via`)
## 5) Cloudová synchronizácia
- Inicializácia plánovača: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts`
- Pravidelná úloha: `src/shared/services/cloudSyncScheduler.ts`
- Pravidelná úloha: `src/shared/services/modelSyncScheduler.ts`
- Riadiaca trasa: `src/app/api/sync/cloud/route.ts`
## Životný cyklus požiadavky (`/v1/chat/completions`)
```mermaid
sequenceDiagram
autonumber
participant Client as Klient CLI/SDK
participant Route as /api/v1/chat/completions
participant Chat as src/sse/handlers/chat
participant Core as open-sse/handlers/chatCore
participant Model as Prekladač modelov
participant Auth as Výber poverení
participant Exec as Vykonávateľ poskytovateľa
participant Prov as Nadradený poskytovateľ
participant Stream as Prekladač prúdu
participant Usage as usageDb
Client->>Route: POST /v1/chat/completions
Route->>Chat: handleChat(request)
Chat->>Model: analyzovať/vyriešiť model alebo kombináciu
alt Kombinovaný model
Chat->>Chat: iterovať cez modely kombinácie (handleComboChat)
end
Chat->>Auth: getProviderCredentials(provider)
Auth-->>Chat: aktívny účet + tokeny/kľúč API
Chat->>Core: handleChatCore(body, modelInfo, credentials)
Core->>Core: zistiť zdrojový formát
Core->>Core: preložiť požiadavku do cieľového formátu
Core->>Exec: execute(provider, transformedBody)
Exec->>Prov: volanie nadradeného API
Prov-->>Exec: odpoveď SSE/JSON
Exec-->>Core: odpoveď + metadáta
alt 401/403
Core->>Exec: refreshCredentials()
Exec-->>Core: aktualizované tokeny
Core->>Exec: zopakovať požiadavku
end
Core->>Stream: preložiť/normalizovať prúd do formátu klienta
Stream-->>Client: bloky SSE / odpoveď JSON
Stream->>Usage: extrahovať údaje o používaní + uložiť históriu/protokol
```
## Tok kombinácie + záložného účtu
```mermaid
flowchart TD
A[Prichádzajúci reťazec modelu] --> B{Je to názov kombinácie?}
B -- Áno --> C[Načítať postupnosť modelov kombinácie]
B -- Nie --> D[Cesta jedného modelu]
C --> E[Vyskúšať model N]
E --> F[Určiť poskytovateľa/model]
D --> F
F --> G[Vybrať prihlasovacie údaje účtu]
G --> H{Sú prihlasovacie údaje dostupné?}
H -- Nie --> I[Vrátiť nedostupnosť poskytovateľa]
H -- Áno --> J[Vykonať požiadavku]
J --> K{Úspešné?}
K -- Áno --> L[Vrátiť odpoveď]
K -- Nie --> M{Chyba vhodná na použitie záložnej možnosti?}
M -- Nie --> N[Vrátiť chybu]
M -- Áno --> O[Označiť účet ako dočasne nedostupný]
O --> P{Ďalší účet poskytovateľa?}
P -- Áno --> G
P -- Nie --> Q{Je v kombinácii ďalší model?}
Q -- Áno --> E
Q -- Nie --> R[Vrátiť, že všetky možnosti sú nedostupné]
```
Rozhodnutia o použití záložnej možnosti riadi `open-sse/services/accountFallback.ts` pomocou stavových kódov a heuristiky chybových hlásení. Smerovanie kombinácií pridáva jednu dodatočnú kontrolu: chyby 400 viazané na poskytovateľa, ako sú blokovanie obsahu nadradenou službou a zlyhania overenia rolí, sa považujú za zlyhania konkrétneho modelu, takže sa môžu naďalej spúšťať ďalšie ciele kombinácie.
## Životný cyklus úvodného nastavenia OAuth a obnovenia tokenu
```mermaid
sequenceDiagram
autonumber
participant UI as Používateľské rozhranie panela
participant OAuth as /api/oauth/[provider]/[action]
participant ProvAuth as Autorizačný server poskytovateľa
participant DB as localDb
participant Test as /api/providers/[id]/test
participant Exec as Vykonávací modul poskytovateľa
UI->>OAuth: GET authorize alebo device-code
OAuth->>ProvAuth: vytvoriť autorizačný tok/tok zariadenia
ProvAuth-->>OAuth: autorizačná URL alebo dáta kódu zariadenia
OAuth-->>UI: údaje toku
UI->>OAuth: POST exchange alebo poll
OAuth->>ProvAuth: výmena tokenu/dopytovanie
ProvAuth-->>OAuth: prístupové/obnovovacie tokeny
OAuth->>DB: createProviderConnection(oauth data)
OAuth-->>UI: úspech + ID pripojenia
UI->>Test: POST /api/providers/[id]/test
Test->>Exec: overiť prihlasovacie údaje / voliteľné obnovenie
Exec-->>Test: platné alebo obnovené údaje tokenu
Test->>DB: aktualizovať stav/tokeny/chyby
Test-->>UI: výsledok overenia
```
Obnovenie počas živej prevádzky sa vykonáva v `open-sse/handlers/chatCore.ts` prostredníctvom `refreshCredentials()` vykonávacieho modulu.
## Životný cyklus cloudovej synchronizácie (zapnutie / synchronizácia / vypnutie)
```mermaid
sequenceDiagram
autonumber
participant UI as Používateľské rozhranie stránky koncového bodu
participant Sync as /api/sync/cloud
participant DB as localDb
participant Cloud as Externá cloudová synchronizácia
participant Claude as ~/.claude/settings.json
UI->>Sync: POST action=enable
Sync->>DB: nastaviť cloudEnabled=true
Sync->>DB: zabezpečiť existenciu kľúča API
Sync->>Cloud: POST /sync/{machineId} (poskytovatelia/aliasy/kombinácie/kľúče)
Cloud-->>Sync: výsledok synchronizácie
Sync->>Cloud: GET /{machineId}/v1/verify
Sync-->>UI: zapnuté + stav overenia
UI->>Sync: POST action=sync
Sync->>Cloud: POST /sync/{machineId}
Cloud-->>Sync: vzdialené údaje
Sync->>DB: aktualizovať novšie lokálne tokeny/stav
Sync-->>UI: synchronizované
UI->>Sync: POST action=disable
Sync->>DB: nastaviť cloudEnabled=false
Sync->>Cloud: DELETE /sync/{machineId}
Sync->>Claude: prepnúť ANTHROPIC_BASE_URL späť na lokálnu adresu (ak je to potrebné)
Sync-->>UI: vypnuté
```
Pravidelnú synchronizáciu spúšťa `CloudSyncScheduler`, keď je cloud zapnutý.
## Dátový model a mapa úložiska
```mermaid
erDiagram
SETTINGS ||--o{ PROVIDER_CONNECTION : riadi
PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : podporuje_kompatibilného_poskytovateľa
PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : zaznamenáva_použitie
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
}
```
Súbory fyzického úložiska:
- primárna runtime databáza: `${DATA_DIR}/storage.sqlite`
- riadky protokolu požiadaviek: `${DATA_DIR}/log.txt` (artefakt kompatibility/ladenia)
- archívy štruktúrovaných dát volaní: `${DATA_DIR}/call_logs/`
- voliteľné ladiace relácie prekladača/požiadaviek: `/logs/...`
## Topológia nasadenia
```mermaid
flowchart LR
subgraph LocalHost[Hostiteľské prostredie vývojára]
CLI[Nástroje CLI]
Browser[Prehliadač ovládacieho panela]
end
subgraph ContainerOrProcess[Runtime OmniRoute]
Next[Server Next.js\nPORT=20128]
Core[Jadro SSE + vykonávacie moduly]
MainDB[(storage.sqlite)]
UsageDB[(tabuľky používania + artefakty protokolov)]
end
subgraph External[Externé služby]
Providers[Poskytovatelia AI]
SyncCloud[Služba cloudovej synchronizácie]
end
CLI --> Next
Browser --> Next
Next --> Core
Next --> MainDB
Core --> MainDB
Core --> UsageDB
Core --> Providers
Next --> SyncCloud
```
## Mapovanie modulov (rozhodujúce pre rozhodovanie)
### Moduly trás a API
- `src/app/api/v1/*`, `src/app/api/v1beta/*`: API kompatibility
- `src/app/api/v1/providers/[provider]/*`: vyhradené trasy pre jednotlivých poskytovateľov (chat, embeddings, obrázky)
- `src/app/api/providers*`: CRUD poskytovateľov, validácia, testovanie
- `src/app/api/provider-nodes*`: správa vlastných kompatibilných uzlov
- `src/app/api/provider-models`: správa vlastných modelov (CRUD)
- `src/app/api/models/route.ts`: API katalógu modelov (aliasy + vlastné modely)
- `src/app/api/oauth/*`: toky OAuth/kódu zariadenia
- `src/app/api/keys*`: životný cyklus lokálnych kľúčov API
- `src/app/api/models/alias`: správa aliasov
- `src/app/api/combos*`: správa záložných kombinácií
- `src/app/api/pricing`: prepísania cien na výpočet nákladov
- `src/app/api/settings/proxy`: konfigurácia proxy (GET/PUT/DELETE)
- `src/app/api/settings/proxy/test`: test konektivity odchádzajúceho proxy (POST)
- `src/app/api/usage/*`: API používania a protokolov
- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloudová synchronizácia a pomocné funkcie pre cloud
- `src/app/api/cli-tools/*`: lokálne zapisovače/kontrolné nástroje konfigurácie CLI
- `src/app/api/settings/ip-filter`: zoznam povolených/blokovaných IP adries (GET/PUT)
- `src/app/api/settings/thinking-budget`: konfigurácia rozpočtu tokenov na uvažovanie (GET/PUT)
- `src/app/api/settings/system-prompt`: globálna systémová výzva (GET/PUT)
- `src/app/api/settings/compression`: globálne nastavenia kompresie (GET/PUT)
- `src/app/api/compression/*`: náhľad kompresie, metadáta pravidiel a jazykové balíky
- `src/app/api/context/caveman/config`: alias nastavení Caveman (GET/PUT)
- `src/app/api/context/rtk/*`: konfigurácia RTK, katalóg filtrov, testovací koncový bod a obnova nespracovaného výstupu
- `src/app/api/context/combos*`: CRUD kombinácií kompresie a priradenia kombinácií smerovania
- `src/app/api/context/analytics`: alias analytiky kompresie
- `src/app/api/sessions`: výpis aktívnych relácií (GET)
- `src/app/api/rate-limits`: stav limitov požiadaviek pre jednotlivé účty (GET)
- `src/app/api/sync/tokens`: CRUD synchronizačných tokenov (GET/POST)
- `src/app/api/sync/tokens/[id]`: získanie/odstránenie synchronizačného tokenu (GET/DELETE)
- `src/app/api/sync/bundle`: stiahnutie balíka konfigurácie (GET, verzovanie pomocou ETag)
- `src/app/api/v1/ws`: obslužný modul upgradu WebSocket pre klientov WS kompatibilných s OpenAI
### Jadro smerovania a vykonávania
- `src/sse/handlers/chat.ts`: spracovanie požiadavky, obsluha kombinácií, cyklus výberu účtu
- `open-sse/handlers/chatCore.ts`: preklad, odovzdanie vykonávaciemu modulu, obsluha opakovaných pokusov/obnovenia, nastavenie streamu
- `open-sse/executors/*`: sieťové správanie a správanie formátu špecifické pre poskytovateľa
### Register prekladov a konvertory formátov
- `open-sse/translator/index.ts`: register a orchestrácia prekladačov
- Prekladače požiadaviek: `open-sse/translator/request/*` (9 modulov — `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`)
- Prekladače odpovedí: `open-sse/translator/response/*` (11 modulov — `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`)
- Pomocné nástroje: `open-sse/translator/helpers/*` (12 modulov — `claudeHelper`, `geminiHelper`, `geminiToolsSanitizer`, `jsonUtil`, `markdownBoundary`, `maxTokensHelper`, `openaiHelper`, `responsesApiHelper`, `schemaCoercion`, `strictSystemHoist`, `toolCallHelper`, `toolCallShim`)
- Konštanty formátov: `open-sse/translator/formats.ts`
- Inicializácia a register: `open-sse/translator/bootstrap.ts`, `open-sse/translator/registry.ts`
- Pomocné nástroje pre formáty obrázkov: `open-sse/translator/image/`
### Perzistencia
- `src/lib/db/*`: perzistentná konfigurácia/stav a doménová perzistencia v SQLite
- `src/lib/db/*`: importujte konkrétne moduly priamo — bez súhrnného exportu (stará vrstva opätovného exportu `localDb.ts` bola odstránená)
- `src/lib/usageDb.ts`: fasáda histórie používania/protokolov volaní nad tabuľkami SQLite
## Pokrytie vykonávačov poskytovateľov (návrhový vzor Strategy)
Každý poskytovateľ má špecializovaný vykonávač rozširujúci `BaseExecutor` (v súbore `open-sse/executors/base.ts`), ktorý poskytuje zostavovanie URL, vytváranie hlavičiek, opakovanie pokusov s exponenciálnym oneskorením, hooky na obnovenie prihlasovacích údajov a metódu orchestrácie `execute()`.
| Vykonávateľ | Poskytovateľ(-ia) | Špeciálne spracovanie |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA atď. | Dynamická konfigurácia URL/hlavičiek pre jednotlivých poskytovateľov |
| `AntigravityExecutor` | Google Antigravity | Vlastné ID projektov/relácií, spracovanie Retry-After, maskovanie 429 |
| `AzureOpenAIExecutor` | Azure OpenAI | Smerovanie podľa nasadenia, vynútenie parametra api-version v dotaze |
| `BlackboxWebExecutor` | Blackbox AI (webový režim) | Reverzné spracovanie webovej relácie s emuláciou odtlačku TLS |
| `ClaudeIdentityExecutor` | Claude.ai (cesta CCH) | Kanály obmedzení a premapovania nástrojov, tvarovanie odtlačku |
| `CliProxyApiExecutor` | Poskytovatelia kompatibilní s CLIProxyAPI | Vlastné spracovanie autentifikácie a protokolu |
| `CloudflareAiExecutor` | Cloudflare Workers AI | Vloženie ID účtu, sledovanie využitia založené na Neurons |
| `CodexExecutor` | OpenAI Codex | Vkladá systémové pokyny, vynucuje mieru úsilia pri uvažovaní |
| `ChatGptWebCodexExecutor` | ChatGPT Web (Codex) | Most rozhrania Responses API pre reláciu prehliadača s pripnutím vlákna/ťahu |
| `CommandCodeExecutor` | Command Code | OAuth + rotácia hlavičiek pre každú reláciu |
| `CursorExecutor` | Cursor IDE | Protokol ConnectRPC, kódovanie Protobuf, podpisovanie požiadaviek pomocou kontrolného súčtu |
| `DevinCliExecutor` | Devin CLI | Premostenie životného cyklu úloh Devin prostredníctvom modulu cloudového agenta |
| `GithubExecutor` | GitHub Copilot | Obnova tokenu Copilot, hlavičky napodobňujúce VSCode |
| `GitlabExecutor` | GitLab Duo | GitLab OAuth + smerovanie v rozsahu projektu |
| `GlmExecutor` | Z.AI GLM (vrátane predvoľby `glmt`) | Zohľadnenie rozpočtu na uvažovanie, konštanty predvoľby GLMT |
| `GrokWebExecutor` | Web xAI Grok | Reverzné spracovanie webovej relácie, výber režimu (uvažovanie/štandardný) |
| `KieExecutor` | KIE | Vlastné vydávanie tokenov s rotujúcimi kotvami relácie |
| `KiroExecutor` | AWS CodeWhisperer/Kiro | Binárny formát AWS EventStream → konverzia na SSE |
| `MuseSparkWebExecutor` | Muse Spark (web) | Reverzné spracovanie webovej relácie s premostením obrazových správ |
| `NlpCloudExecutor` | NLP Cloud | Tvar tela požiadavky špecifický pre poskytovateľa |
| `OpenCodeExecutor` | OpenCode | Nastavenie poskytovateľa kompatibilné s AI SDK |
| `PerplexityWebExecutor` | Web Perplexity | Reverzné spracovanie webovej relácie na pokračovanie konverzácie |
| `PetalsExecutor` | Distribuovaná inferencia Petals | Decentralizované smerovanie v roji |
| `PollinationsExecutor` | Pollinations AI | Nevyžaduje sa kľúč API, požiadavky s obmedzenou frekvenciou |
| `QoderExecutor` | Qoder AI | Podpora PAT a OAuth, bezplatná úroveň s viacerými modelmi |
| `VertexExecutor` | Google Vertex AI | Autentifikácia servisného účtu, koncové body podľa regiónu |
| `DevinDesktopExecutor` | Devin Desktop | Importovaný kľúč API + streamovanie chatu cez Connect-protobuf |
Všetci ostatní poskytovatelia (vrátane vlastných kompatibilných uzlov) používajú `DefaultExecutor`.
## Matica kompatibility poskytovateľov
> **Poznámka:** Nižšie uvedená matica predstavuje reprezentatívnu vzorku z 351 registrovaných poskytovateľov v
> OmniRoute v3.8.0. Kanonický a priebežne aktualizovaný zoznam nájdete v
> [`docs/reference/PROVIDER_REFERENCE.md`](../reference/PROVIDER_REFERENCE.md) (automaticky generovaný) alebo v zdroji
> pravdivých údajov `src/shared/constants/providers.ts` (validovanom pomocou Zod pri načítaní).
| Poskytovateľ | Formát | Autentifikácia | Stream | Bez streamu | Obnova tokenu | API používania |
| ------------------- | ---------------- | -------------------------- | ---------------- | ----------- | ------------- | --------------------- |
| Claude | claude | Kľúč API / OAuth | ✅ | ✅ | ✅ | ⚠️ Iba pre správcov |
| Gemini | gemini | Kľúč API / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Úplné API kvót |
| OpenAI | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| Codex | openai-responses | OAuth | ✅ vynútený | ❌ | ✅ | ✅ Limity požiadaviek |
| ChatGPT Web (Codex) | openai-responses | Relácia prehliadača | ✅ vynútený | ❌ | ❌ | ❌ |
| GitHub Copilot | openai | OAuth + token Copilot | ✅ | ✅ | ✅ | ✅ Snímky kvót |
| Cursor | cursor | Vlastný kontrolný súčet | ✅ | ✅ | ❌ | ❌ |
| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Limity používania |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ Na požiadavku |
| Kilo Code | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Cline | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Kimi Coding | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| OpenRouter | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| GLM/Kimi/MiniMax | claude | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| DeepSeek | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| Groq | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| xAI (Grok) | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| Mistral | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| Perplexity | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| Together AI | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| Fireworks AI | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| Cerebras | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| Cohere | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| NVIDIA NIM | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| Cloudflare AI | openai | Token API + ID účtu | ✅ | ✅ | ❌ | ❌ |
| Pollinations | openai | Žiadna (bez kľúča) | ✅ | ✅ | ❌ | ❌ |
| Scaleway AI | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| LongCat | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| Ollama Cloud | openai | Kľúč API (voliteľný) | ✅ | ✅ | ❌ | ❌ |
| HuggingFace | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| Nebius | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| SiliconFlow | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| Hyperbolic | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| Vertex AI | gemini | Servisný účet | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
| Command Code | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Na požiadavku |
| Z.AI / GLM | openai | Kľúč API / OAuth | ✅ | ✅ | ❌ | ❌ |
| GLMT (predvoľba) | claude | Kľúč API | ✅ | ✅ | ❌ | ⚠️ Na požiadavku |
| Kimi Coding | openai | OAuth / kľúč API | ✅ | ✅ | ✅ | ❌ |
| KIE | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| Devin Desktop | openai | Importovaný kľúč API | ✅ (Connect→SSE) | ✅ | ❌ | ⚠️ Na požiadavku |
| GitLab Duo | openai | OAuth (GitLab) | ✅ | ✅ | ✅ | ❌ |
| Devin CLI | openai | Lokálne prihlásenie CLI | ✅ | ✅ | ❌ | ✅ API úloh |
| Codex Cloud | openai-responses | OAuth | ✅ | ❌ | ✅ | ✅ Limity požiadaviek |
| Jules | openai | OAuth | ✅ | ✅ | ✅ | ✅ API úloh |
| AgentRouter | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| Grok-Web | openai | Súbor cookie relácie | ✅ | ✅ | ❌ | ❌ |
| Perplexity-Web | openai | Súbor cookie relácie | ✅ | ✅ | ❌ | ❌ |
| BlackBox-Web | openai | Súbor cookie relácie + TLS | ✅ | ✅ | ❌ | ❌ |
| Muse-Spark-Web | openai | Súbor cookie relácie | ✅ | ✅ | ❌ | ❌ |
| ModelScope | openai | Kľúč API | ✅ | ✅ | ❌ | ⚠️ Zásady kvót |
| BazaarLink | openai | Kľúč API | ✅ | ✅ | ❌ | ❌ |
| Petals | openai | Žiadna | ✅ | ✅ | ❌ | ❌ |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ Na požiadavku |
| OpenCode (Go/Zen) | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| CLIProxyAPI | openai | Vlastná | ✅ | ✅ | ❌ | ❌ |
## Pokrytie prekladu formátov
Medzi zistené zdrojové formáty patria:
- `openai`
- `openai-responses`
- `claude`
- `gemini`
Medzi cieľové formáty patria:
- OpenAI chat/Responses
- Claude
- Obálka Gemini/Antigravity
- Kiro
- Cursor
Preklady používajú **OpenAI ako centrálny formát** — všetky konverzie prechádzajú cez OpenAI ako medziformát:
```
Zdrojový formát → OpenAI (centrálny formát) → Cieľový formát
```
Preklady sa vyberajú dynamicky na základe štruktúry zdrojového payloadu a cieľového formátu poskytovateľa.
Ďalšie vrstvy spracovania v procese prekladu:
- **Sanitizácia odpovede** — Odstraňuje neštandardné polia z odpovedí vo formáte OpenAI (streamovaných aj nestreamovaných), aby sa zabezpečila striktná kompatibilita so súpravou SDK
- **Normalizácia rolí** — Konvertuje `developer` → `system` pre ciele iné než OpenAI; zlučuje `system` → `user` pre modely, ktoré odmietajú systémovú rolu (GLM, ERNIE)
- **Extrakcia značiek premýšľania** — Analyzuje bloky `...` z obsahu do poľa `reasoning_content`
- **Štruktúrovaný výstup** — Konvertuje OpenAI `response_format.json_schema` na `responseMimeType` + `responseSchema` platformy Gemini
## Podporované koncové body API
| Koncový bod | Formát | Obslužná rutina |
| -------------------------------------------------- | --------------------- | -------------------------------------------------------------------------------- |
| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` |
| `POST /v1/messages` | Claude Messages | Rovnaká obslužná rutina (automaticky rozpoznané) |
| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` |
| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` |
| `GET /v1/embeddings` | Zoznam modelov | Trasa API |
| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` |
| `GET /v1/images/generations` | Zoznam modelov | Trasa API |
| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Vyhradený koncový bod pre každého poskytovateľa s overením modelu |
| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Vyhradený koncový bod pre každého poskytovateľa s overením modelu |
| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Vyhradený koncový bod pre každého poskytovateľa s overením modelu |
| `POST /v1/messages/count_tokens` | Počet tokenov Claude | Trasa API |
| `GET /v1/models` | Zoznam modelov OpenAI | Trasa API (chatovacie + embeddingové + obrazové + vlastné modely) |
| `GET /api/models/catalog` | Katalóg | Všetky modely zoskupené podľa poskytovateľa + typu |
| `POST /v1beta/models/*:streamGenerateContent` | Natívny formát Gemini | Trasa API |
| `GET/PUT/DELETE /api/settings/proxy` | Konfigurácia proxy | Konfigurácia sieťového proxy |
| `POST /api/settings/proxy/test` | Pripojiteľnosť proxy | Koncový bod na test stavu/pripojiteľnosti proxy |
| `GET/POST/DELETE /api/provider-models` | Modely poskytovateľov | Metadáta modelov poskytovateľov podporujúce vlastné a spravované dostupné modely |
## Obsluha obchádzania
Obsluha obchádzania (`open-sse/utils/bypassHandler.ts`) zachytáva známe „jednorazové“ požiadavky z Claude CLI — zahrievacie pingy, extrakcie názvov a počty tokenov — a vracia **falošnú odpoveď** bez spotrebovania tokenov upstream poskytovateľa. Aktivuje sa iba vtedy, keď `User-Agent` obsahuje `claude-cli`.
## Protokolovanie požiadaviek a artefakty
Starší protokolovač požiadaviek založený na súboroch (`open-sse/utils/requestLogger.ts`) sa zachováva iba pre
kompatibilitu so staršími verziami. Aktuálny kontrakt runtime prostredia používa:
- `APP_LOG_TO_FILE=true` pre aplikačné a auditné protokoly zapisované do `/logs/`
- záznamy protokolu volaní v `call_logs` uložené v SQLite
- artefakty `${DATA_DIR}/call_logs/YYYY-MM-DD/...`, keď je zapnutý kanál protokolovania volaní
## Režimy zlyhania a odolnosť
## 1) Dostupnosť účtu/poskytovateľa
- čakacia lehota pripojenia pri opakovateľných zlyhaniach upstreamu
- prechod na záložný účet pred zlyhaním požiadavky
- prechod na záložný kombinovaný model po vyčerpaní aktuálnej cesty modelu/poskytovateľa
## 2) Vypršanie platnosti tokenu
- predbežná kontrola a obnovenie s opakovaním pri poskytovateľoch podporujúcich obnovenie
- opakovanie po pokuse o obnovenie pri stavoch 401/403 v hlavnej ceste
## 3) Bezpečnosť streamu
- ovládač streamu zohľadňujúci odpojenie
- transformačný stream s vyprázdnením na konci streamu a spracovaním `[DONE]`
- záložný odhad využitia, keď chýbajú metadáta poskytovateľa o využití
## 4) Zhoršenie cloudovej synchronizácie
- chyby synchronizácie sa zobrazia, ale lokálne runtime prostredie pokračuje
- plánovač obsahuje logiku podporujúcu opakovanie, ale pravidelné spúšťanie v predvolenom nastavení aktuálne vykonáva synchronizáciu iba na jeden pokus
## 5) Integrita údajov
- migrácie schémy SQLite a mechanizmy automatickej aktualizácie pri spustení
- cesta kompatibility migrácie zo staršieho formátu JSON → SQLite
## 6) Ochrana pred SSRF / odchádzajúcimi URL
- `src/shared/network/outboundUrlGuard.ts` blokuje všetky súkromné, loopbackové a link-local cieľové URL predtým, než sa dostanú k vykonávacím modulom poskytovateľov
- Trasy vyhľadávania a overovania modelov poskytovateľov používajú `src/shared/network/safeOutboundFetch.ts`, ktorý aplikuje ochranu pred každou odchádzajúcou požiadavkou
- Chyby ochrany sa zobrazujú ako `URL_GUARD_BLOCKED` so stavom HTTP 422 a zaznamenávajú sa do protokolu auditu súladu prostredníctvom `providerAudit.ts`
## Pozorovateľnosť a prevádzkové signály
Zdroje informácií o behu systému:
- konzolové protokoly zo `src/sse/utils/logger.ts`
- súhrny využitia pre jednotlivé požiadavky v SQLite (`usage_history`, `call_logs`, `proxy_logs`)
- podrobné zachytenia obsahu v štyroch fázach v SQLite (`request_detail_logs`), keď je `settings.detailed_logs_enabled=true`
- textový protokol stavu požiadaviek v `log.txt` (voliteľné/kompatibilita)
- voliteľné aplikačné protokolové súbory v `logs/`, keď je `APP_LOG_TO_FILE=true`
- voliteľné artefakty požiadaviek v `${DATA_DIR}/call_logs/`, keď je zapnutý kanál protokolovania volaní
- koncové body využitia prehľadu (`/api/usage/*`) určené na použitie v používateľskom rozhraní
Podrobné zachytávanie obsahu požiadaviek ukladá pre každé smerované volanie až štyri fázy obsahu JSON:
- nespracovanú požiadavku prijatú od klienta
- preloženú požiadavku skutočne odoslanú upstreamu
- odpoveď poskytovateľa rekonštruovanú vo formáte JSON; streamované odpovede sa zhusťujú na konečný súhrn spolu s metadátami streamu
- konečnú klientsku odpoveď vrátenú službou OmniRoute; streamované odpovede sa ukladajú v rovnakej zhusťenej forme súhrnu
## Hranice citlivé z hľadiska bezpečnosti
- Tajomstvo JWT (`JWT_SECRET`) zabezpečuje overovanie/podpisovanie súborov cookie relácie ovládacieho panela
- Počiatočné nastavenie hesla (`INITIAL_PASSWORD`) by malo byť explicitne nakonfigurované na prvotné sprevádzkovanie
- Tajomstvo HMAC pre kľúč API (`API_KEY_SECRET`) zabezpečuje formát generovaného lokálneho kľúča API
- Tajomstvá poskytovateľov (kľúče API/tokeny) sa uchovávajú v lokálnej databáze a mali by byť chránené na úrovni súborového systému
- Koncové body cloudovej synchronizácie sa spoliehajú na autentifikáciu pomocou kľúča API a sémantiku identifikátora zariadenia
## Matica prostredí a behového prostredia
Premenné prostredia aktívne používané kódom:
- Aplikácia/autentifikácia: `JWT_SECRET`, `INITIAL_PASSWORD`
- Úložisko: `DATA_DIR`
- Voliteľné prepísanie základného umiestnenia úložiska (Linux/macOS, keď `DATA_DIR` nie je nastavená): `XDG_CONFIG_HOME`
- Bezpečnostné hašovanie: `API_KEY_SECRET`, `MACHINE_ID_SALT`
- Protokolovanie: `APP_LOG_TO_FILE`, `APP_LOG_RETENTION_DAYS`, `CALL_LOG_RETENTION_DAYS`
- Adresy URL synchronizácie/cloudu: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
- Odchádzajúci proxy server: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` a varianty s malými písmenami
- Príznaky funkcií SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
- Pomocné premenné platformy/behového prostredia (nie konfigurácia špecifická pre aplikáciu): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
## Známe poznámky k architektúre
1. `usageDb` a `localDb` zdieľajú rovnakú politiku základného adresára (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) s migráciou starších súborov.
2. `/api/v1/route.ts` deleguje na rovnaký zjednotený nástroj na zostavenie katalógu, aký používa `/api/v1/models` (`src/app/api/v1/models/catalog.ts`), aby sa predišlo sémantickým rozdielom.
3. Záznamník požiadaviek zapisuje po povolení úplné hlavičky/telo; adresár protokolov považujte za citlivý.
4. Správanie cloudu závisí od správnej hodnoty `NEXT_PUBLIC_BASE_URL` a dostupnosti cloudového koncového bodu.
5. Adresár `open-sse/` je publikovaný ako **balík pracovného priestoru npm `@omniroute/open-sse`**. Zdrojový kód ho importuje prostredníctvom `@omniroute/open-sse/...` (rozpoznáva sa pomocou `transpilePackages` systému Next.js). Cesty k súborom v tomto dokumente naďalej používajú názov adresára `open-sse/`, aby sa zachovala konzistentnosť.
6. Grafy na ovládacom paneli používajú **Recharts** (založené na SVG) na prístupné interaktívne vizualizácie analytických údajov (stĺpcové grafy používania modelov, tabuľky rozdelenia podľa poskytovateľov s mierami úspešnosti).
7. Testy E2E používajú **Playwright** (`tests/e2e/`) a spúšťajú sa pomocou `npm run test:e2e`. Jednotkové testy používajú **testovací nástroj Node.js** (`tests/unit/`) a spúšťajú sa pomocou `npm run test:unit`. Zdrojový kód v `src/` je napísaný v jazyku **TypeScript** (`.ts`/`.tsx`); pracovný priestor `open-sse/` zostáva v jazyku JavaScript (`.js`).
8. Stránka nastavení je usporiadaná do 7 kariet: Všeobecné, Vzhľad, AI, Zabezpečenie, Smerovanie, Odolnosť, Rozšírené. Stránka Odolnosť konfiguruje iba front požiadaviek, čas na obnovenie pripojenia, istič poskytovateľa a správanie čakania na obnovenie; aktuálny stav ističa za behu sa zobrazuje na stránke Stav.
9. Stratégia **Context Relay** (`context-relay`) je rozdelená do dvoch vrstiev: `combo.ts` rozhoduje, či sa má vygenerovať odovzdanie kontextu, a `chat.ts` ho vloží po rozpoznaní účtu. Údaje odovzdania sa nachádzajú v tabuľke SQLite `context_handoffs`. Toto rozdelenie je zámerné, pretože iba `chat.ts` vie, či sa skutočný účet zmenil.
10. **Vynucovanie proxy servera** je teraz komplexné: `tokenHealthCheck.ts` určuje proxy server pre každé pripojenie, `/api/providers/validate` používa `runWithProxyContext` a `proxyFetch.ts` používa `undici.fetch()` na zachovanie kompatibility dispečera v Node 22.
11. **Detekcia zásad behového prostredia Node.js**: `/api/settings/require-login` vracia polia `nodeVersion` a `nodeCompatible`. Pri behu mimo podporovaných bezpečných verzií Node.js zobrazí prihlasovacia stránka varovný banner.
## Kontrolný zoznam prevádzkového overenia
- Zostavenie zo zdrojového kódu: `npm run build`
- Zostavenie obrazu Docker: `docker build -t omniroute .`
- Spustenie služby a overenie:
- `GET /api/settings`
- `GET /api/v1/models`
- Základná cieľová URL adresa CLI by mala byť `http://:20128/v1`, keď `PORT=20128`