Skip to content

Latest commit

 

History

History
781 lines (626 loc) · 40.1 KB

ARCHITECTURE.md

File metadata and controls

781 lines (626 loc) · 40.1 KB

Arhitectura OmniRoute

🌐 Languages: 🇺🇸 English | 🇧🇷 Português (Brasil) | 🇪🇸 Español | 🇫🇷 Français | 🇮🇹 Italiano | 🇷🇺 Русский | 🇨🇳 中文 (简体) | 🇩🇪 Deutsch | 🇮🇳 हिन्दी | 🇹🇭 ไทย | 🇺🇦 Українська | 🇸🇦 العربية | 🇯🇵 日本語 | 🇻🇳 Tiếng Việt | 🇧🇬 Български | 🇩🇰 Dansk | 🇫🇮 Suomi | 🇮🇱 עברית | 🇭🇺 Magyar | 🇮🇩 Bahasa Indonesia | 🇰🇷 한국어 | 🇲🇾 Bahasa Melayu | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇵🇹 Português (Portugal) | 🇷🇴 Română | 🇵🇱 Polski | 🇸🇰 Slovenčina | 🇸🇪 Svenska | 🇵🇭 Filipino

Ultima actualizare: 2026-02-18

Rezumat executiv

OmniRoute este un gateway local de rutare AI și un tablou de bord construit pe Next.js. Acesta oferă un singur punct final compatibil cu OpenAI (/v1/*) și direcționează traficul către mai mulți furnizori din amonte cu traducere, alternativă, reîmprospătare token și urmărire a utilizării.

Capacitățile de bază:

  • Suprafață API compatibilă cu OpenAI pentru CLI/instrumente (28 de furnizori)
  • Traducerea cererii/răspunsurilor între formatele furnizorilor
  • Alternativ combo de model (secvență cu mai multe modele)
  • Rezervă de rezervă la nivel de cont (cu mai multe conturi pentru fiecare furnizor)
  • Gestionarea conexiunii furnizorului OAuth + cheie API
  • Generare de încorporare prin /v1/embeddings (6 furnizori, 9 modele)
  • Generare de imagini prin /v1/images/generations (4 furnizori, 9 modele)
  • Gândiți-vă la analizarea etichetelor (<think>...</think>) pentru modele de raționament
  • Sanitizarea răspunsului pentru compatibilitate strictă cu OpenAI SDK
  • Normalizarea rolurilor (dezvoltator→sistem, sistem→utilizator) pentru compatibilitate între furnizori
  • Conversie de ieșire structurată (json_schema → Gemini responseSchema)
  • Persistență locală pentru furnizori, chei, aliasuri, combo-uri, setări, prețuri
  • Urmărirea utilizării/costurilor și înregistrarea cererilor
  • Sincronizare cloud opțională pentru sincronizare multi-dispozitiv/state
  • Lista permisă/lista blocată IP pentru controlul accesului API
  • Gândire la managementul bugetului (passthrough/auto/personalizat/adaptativ)
  • Sistem global de injectare promptă
  • Urmărirea sesiunii și amprentarea
  • Limitare îmbunătățită a ratei per cont cu profiluri specifice furnizorului
  • Model de întrerupător pentru rezistența furnizorului
  • Protectie anti-tunet cu blocare mutex
  • Cache de deduplicare a cererilor bazate pe semnătură
  • Nivelul domeniului: disponibilitatea modelului, regulile de cost, politica de rezervă, politica de blocare
  • Persistența stării domeniului (cache-ul de scriere SQLite pentru rezervări, bugete, blocări, întreruptoare de circuit)
  • Motor de politici pentru evaluarea centralizată a cererilor (blocare → buget → rezervă)
  • Solicitați telemetrie cu agregarea latenței p50/p95/p99
  • ID de corelare (X-Request-Id) pentru urmărirea de la capăt la capăt
  • Înregistrare de audit de conformitate cu renunțare pentru fiecare cheie API
  • Cadrul de evaluare pentru asigurarea calității LLM
  • Tabloul de bord Resilience UI cu starea întreruptorului în timp real
  • Furnizori OAuth modulari (12 module individuale sub src/lib/oauth/providers/)

Model de rulare principal:

  • Rutele aplicației Next.js sub src/app/api/* implementează atât API-uri de tablou de bord, cât și API-uri de compatibilitate
  • Un nucleu SSE/rutare partajat în src/sse/* + open-sse/* se ocupă de execuția furnizorului, traducerea, transmiterea în flux, alternativă și utilizare

Domeniul de aplicare și limitele

În domeniul de aplicare

  • Timp de rulare gateway local
  • API-uri de gestionare a tabloului de bord
  • Autentificarea furnizorului și reîmprospătarea simbolului
  • Solicitați traducere și streaming SSE
  • Stare locală + persistență de utilizare
  • Orchestrare opțională de sincronizare în cloud

În afara domeniului de aplicare

  • Implementarea serviciului cloud în spatele NEXT_PUBLIC_CLOUD_URL
  • Furnizor SLA/plan de control în afara procesului local
  • Binarele CLI externe în sine (Claude CLI, Codex CLI etc.)

Context de sistem la nivel înalt

flowchart LR
    subgraph Clients[Developer Clients]
        C1[Claude Code]
        C2[Codex CLI]
        C3[OpenClaw / Droid / Cline / Continue / Roo]
        C4[Custom OpenAI-compatible clients]
        BROWSER[Browser Dashboard]
    end

    subgraph Router[OmniRoute Local Process]
        API[V1 Compatibility API\n/v1/*]
        DASH[Dashboard + Management API\n/api/*]
        CORE[SSE + Translation Core\nopen-sse + src/sse]
        DB[(db.json)]
        UDB[(usage.json + log.txt)]
    end

    subgraph Upstreams[Upstream Providers]
        P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/iFlow/GitHub/Kiro/Cursor/Antigravity]
        P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA]
        P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible]
    end

    subgraph Cloud[Optional Cloud Sync]
        CLOUD[Cloud Sync Endpoint\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
Loading

Componente Core Runtime

1) API și stratul de rutare (Rute pentru aplicații Next.js)

Directoare principale:

  • src/app/api/v1/* și src/app/api/v1beta/* pentru API-uri de compatibilitate
  • src/app/api/* pentru API-uri de gestionare/configurare
  • Următoarea rescrie în harta next.config.mjs /v1/* în /api/v1/*

Rute importante de compatibilitate:

  • 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 — include modele personalizate cu custom: true
  • src/app/api/v1/embeddings/route.ts — generare de încorporare (6 furnizori)
  • src/app/api/v1/images/generations/route.ts — generare de imagini (4+ furnizori inclusiv Antigravity/Nebius)
  • src/app/api/v1/messages/count_tokens/route.ts
  • src/app/api/v1/providers/[provider]/chat/completions/route.ts — chat dedicat pentru fiecare furnizor
  • src/app/api/v1/providers/[provider]/embeddings/route.ts — încorporare dedicate pentru fiecare furnizor
  • src/app/api/v1/providers/[provider]/images/generations/route.ts — imagini dedicate pentru fiecare furnizor
  • src/app/api/v1beta/models/route.ts
  • src/app/api/v1beta/models/[...path]/route.ts

Domenii de management:

  • Autentificare/setări: src/app/api/auth/*, src/app/api/settings/*
  • Furnizori/conexiuni: src/app/api/providers*
  • Noduri furnizor: src/app/api/provider-nodes*
  • Modele personalizate: src/app/api/provider-models (GET/POST/DELETE)
  • Catalog de modele: src/app/api/models/catalog (GET)
  • Configurare proxy: src/app/api/settings/proxy (GET/PUT/DELETE) + src/app/api/settings/proxy/test (POST)
  • OAuth: src/app/api/oauth/*
  • Chei/alias-uri/combo/preț: src/app/api/keys*, src/app/api/models/alias, src/app/api/combos*, src/app/api/pricing
  • Utilizare: src/app/api/usage/*
  • Sincronizare/cloud: src/app/api/sync/*, src/app/api/cloud/*
  • Ajutor de instrumente CLI: src/app/api/cli-tools/*
  • Filtru IP: src/app/api/settings/ip-filter (GET/PUT)
  • Buget de gândire: src/app/api/settings/thinking-budget (GET/PUT)
  • prompt de sistem: src/app/api/settings/system-prompt (GET/PUT)
  • Sesiuni: src/app/api/sessions (GET)
  • Limite de rate: src/app/api/rate-limits (GET)
  • Reziliență: src/app/api/resilience (GET/PATCH) — profiluri furnizor, întrerupător, stare limită a ratei
  • Resetare rezistență: src/app/api/resilience/reset (POST) — resetare întrerupătoare + cooldowns
  • Statistici cache: src/app/api/cache/stats (GET/DELETE)
  • Disponibilitatea modelului: src/app/api/models/availability (GET/POST)
  • Telemetrie: src/app/api/telemetry/summary (GET)
  • Buget: src/app/api/usage/budget (GET/POST)
  • Lanțuri de rezervă: src/app/api/fallback/chains (GET/POST/DELETE)
  • Audit de conformitate: src/app/api/compliance/audit-log (GET)
  • Evaluări: src/app/api/evals (GET/POST), src/app/api/evals/[suiteId] (GET)
  • Politici: src/app/api/policies (GET/POST)

2) SSE + Translation Core

Module principale de flux:

  • Intrare: src/sse/handlers/chat.ts
  • Orchestrare de bază: open-sse/handlers/chatCore.ts
  • Adaptoare de execuție furnizor: open-sse/executors/*
  • Format de detectare/configurare furnizor: open-sse/services/provider.ts
  • Analiza/rezolvarea modelului: src/sse/services/model.ts, open-sse/services/model.ts
  • Logica de rezervă a contului: open-sse/services/accountFallback.ts
  • Registrul traducerilor: open-sse/translator/index.ts
  • Transformări de flux: open-sse/utils/stream.ts, open-sse/utils/streamHandler.ts
  • Extragerea/normalizarea utilizării: open-sse/utils/usageTracking.ts
  • Analizator de etichete de gândire: open-sse/utils/thinkTagParser.ts
  • Manager de încorporare: open-sse/handlers/embeddings.ts
  • Încorporarea registrului furnizorului: open-sse/config/embeddingRegistry.ts
  • Manager de generare a imaginii: open-sse/handlers/imageGeneration.ts
  • Registrul furnizorului de imagini: open-sse/config/imageRegistry.ts
  • igienizare răspuns: open-sse/handlers/responseSanitizer.ts
  • Normalizare rol: open-sse/services/roleNormalizer.ts

Servicii (logica de afaceri):

  • Selectarea/punctarea contului: open-sse/services/accountSelector.ts
  • Gestionarea ciclului de viață a contextului: open-sse/services/contextManager.ts
  • Aplicarea filtrului IP: open-sse/services/ipFilter.ts
  • Urmărirea sesiunii: open-sse/services/sessionManager.ts
  • Solicitați deduplicarea: open-sse/services/signatureCache.ts
  • Injectarea promptă a sistemului: open-sse/services/systemPrompt.ts
  • Gândirea bugetului: open-sse/services/thinkingBudget.ts
  • rutare model wildcard: open-sse/services/wildcardRouter.ts
  • Gestionarea limitei ratei: open-sse/services/rateLimitManager.ts
  • Întrerupător: open-sse/services/circuitBreaker.ts

Module de nivel de domeniu:

  • Disponibilitatea modelului: src/lib/domain/modelAvailability.ts
  • Reguli de cost/bugete: src/lib/domain/costRules.ts
  • Politica de rezervă: src/lib/domain/fallbackPolicy.ts
  • Soluție combinată: src/lib/domain/comboResolver.ts
  • Politica de blocare: src/lib/domain/lockoutPolicy.ts
  • Motor de politici: src/domain/policyEngine.ts — blocare centralizată → buget → evaluare alternativă
  • Catalog coduri de eroare: src/lib/domain/errorCodes.ts
  • ID cerere: src/lib/domain/requestId.ts
  • Timeout pentru preluare: src/lib/domain/fetchTimeout.ts
  • Solicitați telemetrie: src/lib/domain/requestTelemetry.ts
  • Conformitate/audit: src/lib/domain/compliance/index.ts
  • Runner de evaluare: src/lib/domain/evalRunner.ts
  • Persistența stării domeniului: src/lib/db/domainState.ts — SQLite CRUD pentru lanțuri de rezervă, bugete, istoricul costurilor, starea de blocare, întrerupătoarele de circuit

Module de furnizor OAuth (12 fișiere individuale sub src/lib/oauth/providers/):

  • Index de registru: src/lib/oauth/providers/index.ts
  • Furnizori individuali: claude.ts, codex.ts, gemini.ts, antigravity.ts, iflow.ts, , , , kimi-coding.ts, github.ts, kiro.ts, cursor.ts, kilocode.ts, cline.ts
  • Ambalaj subțire: src/lib/oauth/providers.ts — reexporturi din module individuale

3) Stratul de persistență

DB de stat primar:

  • src/lib/localDb.ts
  • fișier: ${DATA_DIR}/db.json (sau $XDG_CONFIG_HOME/omniroute/db.json când este setat, altfel ~/.omniroute/db.json)
  • entități: providerConnections, providerNodes, modelAliases, combo-uri, apiKeys, setări, prețuri, customModels, proxyConfig, ipFilter, thinkingBudget, systemPrompt

DB de utilizare:

  • src/lib/usageDb.ts
  • fișiere: ${DATA_DIR}/usage.json, ${DATA_DIR}/log.txt, ${DATA_DIR}/call_logs/
  • urmează aceeași politică de bază de director ca localDb (DATA_DIR, apoi XDG_CONFIG_HOME/omniroute când este setat)
  • descompus în sub-module focalizate: migrations.ts, usageHistory.ts, costCalculator.ts, usageStats.ts, callLogs.ts

DB Stare Domeniu (SQLite):

  • src/lib/db/domainState.ts — Operații CRUD pentru starea domeniului
  • Tabele (create în src/lib/db/core.ts): domain_fallback_chains, domain_budgets, domain_cost_history, domain_lockout_state, domain_circuit_breakers_
  • Model de cache de scriere: hărțile din memorie sunt autorizate în timpul execuției; mutațiile sunt scrise sincron cu SQLite; starea este restabilită din DB la pornirea la rece

4) Autentificare + Suprafețe de securitate

  • Autentificare cookie pentru tabloul de bord: src/proxy.ts, src/app/api/auth/login/route.ts
  • Generarea/verificarea cheii API: src/shared/utils/apiKey.ts
  • Secretele furnizorului au persistat în intrările providerConnections
  • Suport proxy de ieșire prin open-sse/utils/proxyFetch.ts (env vars) și open-sse/utils/networkProxy.ts (configurabil per furnizor sau global)

5) Cloud Sync

  • Inițierea planificatorului: src/lib/initCloudSync.ts, src/shared/services/initializeCloudSync.ts
  • Sarcină periodică: src/shared/services/cloudSyncScheduler.ts
  • Rută de control: src/app/api/sync/cloud/route.ts

Ciclul de viață al solicitării (/v1/chat/completions)

sequenceDiagram
    autonumber
    participant Client as CLI/SDK Client
    participant Route as /api/v1/chat/completions
    participant Chat as src/sse/handlers/chat
    participant Core as open-sse/handlers/chatCore
    participant Model as Model Resolver
    participant Auth as Credential Selector
    participant Exec as Provider Executor
    participant Prov as Upstream Provider
    participant Stream as Stream Translator
    participant Usage as usageDb

    Client->>Route: POST /v1/chat/completions
    Route->>Chat: handleChat(request)
    Chat->>Model: parse/resolve model or combo

    alt Combo model
        Chat->>Chat: iterate combo models (handleComboChat)
    end

    Chat->>Auth: getProviderCredentials(provider)
    Auth-->>Chat: active account + tokens/api key

    Chat->>Core: handleChatCore(body, modelInfo, credentials)
    Core->>Core: detect source format
    Core->>Core: translate request to target format
    Core->>Exec: execute(provider, transformedBody)
    Exec->>Prov: upstream API call
    Prov-->>Exec: SSE/JSON response
    Exec-->>Core: response + metadata

    alt 401/403
        Core->>Exec: refreshCredentials()
        Exec-->>Core: updated tokens
        Core->>Exec: retry request
    end

    Core->>Stream: translate/normalize stream to client format
    Stream-->>Client: SSE chunks / JSON response

    Stream->>Usage: extract usage + persist history/log
Loading

Combo + Flux de rezervă pentru cont

flowchart TD
    A[Incoming model string] --> B{Is combo name?}
    B -- Yes --> C[Load combo models sequence]
    B -- No --> D[Single model path]

    C --> E[Try model N]
    E --> F[Resolve provider/model]
    D --> F

    F --> G[Select account credentials]
    G --> H{Credentials available?}
    H -- No --> I[Return provider unavailable]
    H -- Yes --> J[Execute request]

    J --> K{Success?}
    K -- Yes --> L[Return response]
    K -- No --> M{Fallback-eligible error?}

    M -- No --> N[Return error]
    M -- Yes --> O[Mark account unavailable cooldown]
    O --> P{Another account for provider?}
    P -- Yes --> G
    P -- No --> Q{In combo with next model?}
    Q -- Yes --> E
    Q -- No --> R[Return all unavailable]
Loading

Deciziile de rezervă sunt conduse de open-sse/services/accountFallback.ts folosind coduri de stare și euristică mesaj de eroare.

Ciclul de viață OAuth Onboarding și Token Refresh

sequenceDiagram
    autonumber
    participant UI as Dashboard UI
    participant OAuth as /api/oauth/[provider]/[action]
    participant ProvAuth as Provider Auth Server
    participant DB as localDb
    participant Test as /api/providers/[id]/test
    participant Exec as Provider Executor

    UI->>OAuth: GET authorize or device-code
    OAuth->>ProvAuth: create auth/device flow
    ProvAuth-->>OAuth: auth URL or device code payload
    OAuth-->>UI: flow data

    UI->>OAuth: POST exchange or poll
    OAuth->>ProvAuth: token exchange/poll
    ProvAuth-->>OAuth: access/refresh tokens
    OAuth->>DB: createProviderConnection(oauth data)
    OAuth-->>UI: success + connection id

    UI->>Test: POST /api/providers/[id]/test
    Test->>Exec: validate credentials / optional refresh
    Exec-->>Test: valid or refreshed token info
    Test->>DB: update status/tokens/errors
    Test-->>UI: validation result
Loading

Reîmprospătarea în timpul traficului live este executată în interiorul open-sse/handlers/chatCore.ts prin intermediul executorului refreshCredentials().

Ciclul de viață Cloud Sync (Activare / Sincronizare / Dezactivare)

sequenceDiagram
    autonumber
    participant UI as Endpoint Page UI
    participant Sync as /api/sync/cloud
    participant DB as localDb
    participant Cloud as External Cloud Sync
    participant Claude as ~/.claude/settings.json

    UI->>Sync: POST action=enable
    Sync->>DB: set cloudEnabled=true
    Sync->>DB: ensure API key exists
    Sync->>Cloud: POST /sync/{machineId} (providers/aliases/combos/keys)
    Cloud-->>Sync: sync result
    Sync->>Cloud: GET /{machineId}/v1/verify
    Sync-->>UI: enabled + verification status

    UI->>Sync: POST action=sync
    Sync->>Cloud: POST /sync/{machineId}
    Cloud-->>Sync: remote data
    Sync->>DB: update newer local tokens/status
    Sync-->>UI: synced

    UI->>Sync: POST action=disable
    Sync->>DB: set cloudEnabled=false
    Sync->>Cloud: DELETE /sync/{machineId}
    Sync->>Claude: switch ANTHROPIC_BASE_URL back to local (if needed)
    Sync-->>UI: disabled
Loading

Sincronizarea periodică este declanșată de CloudSyncScheduler când cloud este activat.

Model de date și hartă de stocare

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
    }
Loading

Fișiere de stocare fizică:

  • starea principală: ${DATA_DIR}/db.json (sau $XDG_CONFIG_HOME/omniroute/db.json când este setat, altfel ~/.omniroute/db.json)
  • statistici de utilizare: ${DATA_DIR}/usage.json
  • linii de jurnal de solicitare: ${DATA_DIR}/log.txt
  • sesiuni opționale de traducător/cerere de depanare: <repo>/logs/...

Topologie de implementare

flowchart LR
    subgraph LocalHost[Developer Host]
        CLI[CLI Tools]
        Browser[Dashboard Browser]
    end

    subgraph ContainerOrProcess[OmniRoute Runtime]
        Next[Next.js Server\nPORT=20128]
        Core[SSE Core + Executors]
        MainDB[(db.json)]
        UsageDB[(usage.json/log.txt)]
    end

    subgraph External[External Services]
        Providers[AI Providers]
        SyncCloud[Cloud Sync Service]
    end

    CLI --> Next
    Browser --> Next
    Next --> Core
    Next --> MainDB
    Core --> MainDB
    Core --> UsageDB
    Core --> Providers
    Next --> SyncCloud
Loading

Maparea modulului (decizie critică)

Rută și module API

  • src/app/api/v1/*, src/app/api/v1beta/*: API-uri de compatibilitate
  • src/app/api/v1/providers/[provider]/*: rute dedicate pentru fiecare furnizor (chat, încorporare, imagini)
  • src/app/api/providers*: furnizor CRUD, validare, testare
  • src/app/api/provider-nodes*: gestionarea nodurilor compatibile personalizate
  • src/app/api/provider-models: management personalizat model (CRUD)
  • src/app/api/models/catalog: API de catalog de model complet (toate tipurile grupate după furnizor)
  • src/app/api/oauth/*: fluxuri OAuth/cod dispozitiv
  • src/app/api/keys*: ciclul de viață local al cheii API
  • src/app/api/models/alias: gestionare alias
  • src/app/api/combos*: gestionarea combo de rezervă
  • src/app/api/pricing: înlocuirea prețurilor pentru calcularea costurilor
  • src/app/api/settings/proxy: configurație proxy (GET/PUT/DELETE)
  • src/app/api/settings/proxy/test: test de conectivitate proxy de ieșire (POST)
  • src/app/api/usage/*: API-uri de utilizare și jurnal
  • src/app/api/sync/* + src/app/api/cloud/*: sincronizare în cloud și asistență orientată către nor
  • src/app/api/cli-tools/*: scriitori/verificatori de configurare CLI locale
  • src/app/api/settings/ip-filter: lista IP permisă/lista blocată (GET/PUT)
  • src/app/api/settings/thinking-budget: configurația bugetului simbolului de gândire (GET/PUT)
  • src/app/api/settings/system-prompt: prompt de sistem global (GET/PUT)
  • src/app/api/sessions: listarea sesiunii active (GET)
  • src/app/api/rate-limits: starea limită a ratei per cont (GET)

Core de rutare și execuție

  • src/sse/handlers/chat.ts: analizarea cererii, gestionarea combinațiilor, bucla de selecție a contului
  • open-sse/handlers/chatCore.ts: traducere, expediere executor, reîncercare/reîmprospătare manipulare, configurare flux
  • open-sse/executors/*: comportamentul de rețea și format specific furnizorului

Registrul de traduceri și convertoare de format

  • open-sse/translator/index.ts: registru și orchestrare a traducătorilor
  • Solicitați traducători: open-sse/translator/request/*
  • Traducători de răspuns: open-sse/translator/response/*
  • Formatare constante: open-sse/translator/formats.ts

Persistență

  • src/lib/localDb.ts: config/stare persistentă
  • src/lib/usageDb.ts: istoricul utilizării și jurnalele de solicitare continuă

Acoperire Executor Furnizor (Model de strategie)

Fiecare furnizor are un executor specializat care extinde BaseExecutor (în open-sse/executors/base.ts), care oferă crearea URL, construcția antetului, reîncercarea cu backoff exponențial, cârlige de reîmprospătare a acreditărilor și metoda de orchestrare execute().

Executant Furnizor(i) Manipulare specială
DefaultExecutor OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA Configurare URL dinamică/antet per furnizor
AntigravityExecutor Google Antigravity ID-uri personalizate de proiect/sesiune, Reîncercați-După analizare
CodexExecutor OpenAI Codex Injectează instrucțiuni de sistem, forțează efortul de raționament
CursorExecutor Cursor IDE Protocolul ConnectRPC, codificarea Protobuf, semnarea cererii prin suma de control
GithubExecutor GitHub Copilot Reîmprospătare jeton Copilot, anteturi care imită VSCode
KiroExecutor AWS CodeWhisperer/Kiro Format binar AWS EventStream → conversie SSE
GeminiCLIExecutor Gemeni CLI Ciclul de reîmprospătare a simbolului OAuth Google

Toți ceilalți furnizori (inclusiv noduri compatibile personalizate) folosesc DefaultExecutor.

Matricea de compatibilitate a furnizorilor

Furnizor Format Auth Flux Non-Stream Token Refresh Utilizare API
Claude claude Cheie API / OAuth ✅ ✅ ✅ ⚠️ Doar administrator
Gemeni gemeni Cheie API / OAuth ✅ ✅ ✅ ⚠️ Cloud Console
Gemeni CLI gemeni-cli OAuth ✅ ✅ ✅ ⚠️ Cloud Console
Antigravitație antigravitație OAuth ✅ ✅ ✅ ✅ Cota completă API
OpenAI deschis Cheie API ✅ ✅ ❌ ❌
Codex openai-responses OAuth ✅ forțat ❌ ✅ ✅ Limite de tarif
GitHub Copilot deschis OAuth + Token Copilot ✅ ✅ ✅ ✅ Instantanee de cotă
Cursor cursor Sumă de control personalizată ✅ ✅ ❌ ❌
Kiro kiro AWS SSO OIDC ✅ (EventStream) ❌ ✅ ✅ Limite de utilizare
Qwen deschis OAuth ✅ ✅ ✅ ⚠️ La cerere
iFlow deschis OAuth (de bază) ✅ ✅ ✅ ⚠️ La cerere
OpenRouter deschis Cheie API ✅ ✅ ❌ ❌
GLM/Kimi/MiniMax claude Cheie API ✅ ✅ ❌ ❌
DeepSeek deschis Cheie API ✅ ✅ ❌ ❌
Groq deschis Cheie API ✅ ✅ ❌ ❌
xAI (Grok) deschis Cheie API ✅ ✅ ❌ ❌
Mistral deschis Cheie API ✅ ✅ ❌ ❌
Nedumerire deschis Cheie API ✅ ✅ ❌ ❌
Împreună AI deschis Cheie API ✅ ✅ ❌ ❌
Artificii AI deschis Cheie API ✅ ✅ ❌ ❌
Cerebre deschis Cheie API ✅ ✅ ❌ ❌
Cohere deschis Cheie API ✅ ✅ ❌ ❌
NVIDIA NIM deschis Cheie API ✅ ✅ ❌ ❌

Format Acoperire traducere

Formatele sursă detectate includ:

  • openai
  • openai-responses
  • claude
  • gemini

Formatele țintă includ:

  • Chat/Răspunsuri OpenAI
  • Claude
  • Plic Gemeni/Gemeni-CLI/Antigravity
  • Kiro
  • Cursor

Traducerile folosesc OpenAI ca format hub — toate conversiile trec prin OpenAI ca intermediar:

Source Format → OpenAI (hub) → Target Format

Traducerile sunt selectate dinamic pe baza formei încărcăturii sursei și a formatului țintă al furnizorului.

Straturi de procesare suplimentare în conducta de traducere:

  • Sanitizarea răspunsurilor — Elimina câmpurile nestandard din răspunsurile în format OpenAI (atât în flux, cât și în non-streaming) pentru a asigura conformitatea strictă cu SDK
  • Normalizarea rolurilor — Convertește developer → system pentru ținte non-OpenAI; îmbină system → user pentru modelele care resping rolul de sistem (GLM, ERNIE)
  • Think tag extraction — Analizează blocurile <think>...</think> din conținut în câmpul reasoning_content
  • Ieșire structurată — Convertește OpenAI response_format.json_schema în responseMimeType al lui Gemini + responseSchema

Puncte finale API acceptate

Punct final Format Manipulator
POST /v1/chat/completions OpenAI Chat src/sse/handlers/chat.ts
POST /v1/messages Claude Mesaje Același handler (detectat automat)
POST /v1/responses Răspunsuri OpenAI open-sse/handlers/responsesHandler.ts
POST /v1/embeddings Încorporare OpenAI open-sse/handlers/embeddings.ts
GET /v1/embeddings Lista de modele Rută API
POST /v1/images/generations Imagini OpenAI open-sse/handlers/imageGeneration.ts
GET /v1/images/generations Lista de modele Rută API
POST /v1/providers/{provider}/chat/completions OpenAI Chat Dedicat pentru fiecare furnizor cu validare a modelului
POST /v1/providers/{provider}/embeddings Încorporare OpenAI Dedicat pentru fiecare furnizor cu validare a modelului
POST /v1/providers/{provider}/images/generations Imagini OpenAI Dedicat pentru fiecare furnizor cu validare a modelului
POST /v1/messages/count_tokens Claude Token Count Rută API
GET /v1/models Lista de modele OpenAI Rută API (chat + încorporare + imagine + modele personalizate)
GET /api/models/catalog Catalog Toate modelele grupate după furnizor + tip
POST /v1beta/models/*:streamGenerateContent nativ Gemeni Rută API
GET/PUT/DELETE /api/settings/proxy Configurare proxy Configurare proxy de rețea
POST /api/settings/proxy/test Conectivitate proxy Punct final de testare de sănătate/conectivitate proxy
GET/POST/DELETE /api/provider-models Modele personalizate Gestionare model personalizat per furnizor

Handler de ocolire

Managerul de ocolire (open-sse/utils/bypassHandler.ts) interceptează cererile cunoscute „de aruncat” de la Claude CLI — ping-uri de încălzire, extrageri de titluri și numărătoare de jetonuri — și returnează un răspuns fals fără a consuma jetoane de furnizor în amonte. Aceasta este declanșată numai atunci când User-Agent conține claude-cli.

Solicitați Conducta Logger

Loggerul de solicitare (open-sse/utils/requestLogger.ts) oferă o conductă de înregistrare a depanării în 7 etape, dezactivată implicit, activată prin ENABLE_REQUEST_LOGS=true:

1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json
→ 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt

Fișierele sunt scrise în <repo>/logs/<session>/ pentru fiecare sesiune de solicitare.

Moduri de eșec și rezistență

1) Disponibilitatea contului/furnizorului

  • cooldown contului furnizorului pentru erori tranzitorii/rate/auth
  • rezervă de cont înainte de cererea eșuată
  • alternativă model combo atunci când modelul curent/calea furnizorului este epuizată

2) Expirarea simbolului

  • preverificare și reîmprospătare cu reîncercare pentru furnizorii care pot fi reîmprospătați
  • 401/403 reîncercați după încercarea de reîmprospătare în calea de bază

3) Siguranța fluxului

  • controler de flux conștient de deconectare
  • flux de traducere cu spălare la sfârșitul fluxului și gestionarea [DONE]
  • estimarea utilizării de rezervă atunci când metadatele de utilizare ale furnizorului lipsesc

4) Degradarea Cloud Sync

  • apar erori de sincronizare, dar timpul de execuție local continuă
  • planificatorul are o logică capabilă să reîncerce, dar execuția periodică apelează în mod implicit sincronizarea cu o singură încercare

5) Integritatea datelor

  • Migrare/reparare forme DB pentru cheile lipsă
  • garanții de resetare JSON corupte pentru localDb și usageDb

Observabilitate și semnale operaționale

Surse de vizibilitate la runtime:

  • jurnalele consolei de la src/sse/utils/logger.ts
  • agregate de utilizare la cerere în usage.json
  • autentificarea stării cererii textuale log.txt
  • jurnalele opționale de solicitare profundă/traducere sub logs/ când ENABLE_REQUEST_LOGS=true
  • puncte finale de utilizare a tabloului de bord (/api/usage/*) pentru consumul UI

Limite sensibile la securitate

  • Secretul JWT (JWT_SECRET) securizează verificarea/semnarea cookie-urilor sesiunii de bord
  • Parola de rezervă inițială (INITIAL_PASSWORD, implicit 123456) trebuie să fie înlocuită în implementările reale
  • Secretul HMAC cheie API (API_KEY_SECRET) securizează formatul cheii API locale generate
  • Secretele furnizorului (chei/token-uri API) sunt păstrate în DB local și ar trebui protejate la nivel de sistem de fișiere
  • Punctele finale de sincronizare în cloud se bazează pe semantica de autentificare a cheii API + ID-ul mașinii

Mediu și matrice de rulare

Variabilele de mediu utilizate în mod activ de cod:

  • Aplicație/autentificare: JWT_SECRET, INITIAL_PASSWORD
  • Stocare: DATA_DIR
  • Comportamentul nodului compatibil: ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE
  • Suprascriere opțională a bazei de stocare (Linux/macOS când DATA_DIR dezactivat): XDG_CONFIG_HOME
  • Hashing de securitate: API_KEY_SECRET, MACHINE_ID_SALT
  • Înregistrare: ENABLE_REQUEST_LOGS
  • URL sincronizare/cloud: NEXT_PUBLIC_BASE_URL, NEXT_PUBLIC_CLOUD_URL
  • Proxy de ieșire: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY și variante cu litere mici
  • Indicatori de caracteristică SOCKS5: ENABLE_SOCKS5_PROXY, NEXT_PUBLIC_ENABLE_SOCKS5_PROXY
  • Ajutor platformă/execuție (configurație nu specifică aplicației): APPDATA, NODE_ENV, PORT, HOSTNAME

Note arhitecturale cunoscute

  1. usageDb și localDb au acum aceeași politică de bază de director (DATA_DIR -> XDG_CONFIG_HOME/omniroute -> ~/.omniroute) cu migrarea fișierelor moștenite.
  2. /api/v1/route.ts returnează o listă de modele statice și nu este sursa principală de modele utilizată de /v1/models.
  3. Loggerul solicitărilor scrie anteturi/corp complet atunci când este activat; tratați directorul de jurnal ca fiind sensibil.
  4. Comportamentul în cloud depinde de NEXT_PUBLIC_BASE_URL corect și de accesibilitatea punctului final din cloud.
  5. Directorul open-sse/ este publicat ca pachetul @omniroute/open-sse npm workspace. Codul sursă îl importă prin @omniroute/open-sse/... (rezolvat de Next.js transpilePackages). Căile fișierelor din acest document folosesc în continuare numele directorului open-sse/ pentru consecvență.
  6. Diagramele din tabloul de bord utilizează Recharts (bazate pe SVG) pentru vizualizări analitice accesibile, interactive (diagrame cu bare de utilizare a modelelor, tabele de defalcare a furnizorilor cu rate de succes).
  7. Testele E2E folosesc Playwright (tests/e2e/), rulat prin npm run test:e2e. Testele unitare folosesc Node.js test runner (tests/unit/), rulează prin npm run test:plan3. Codul sursă sub src/ este TypeScript (.ts/.tsx); spațiul de lucru open-sse/ rămâne JavaScript (.js).
  8. Pagina Setări este organizată în 5 file: Securitate, Rutare (6 strategii globale: fill-first, round-robin, p2c, aleatoriu, cel mai puțin utilizat, optimizat pentru cost), Reziliență (limite ale ratei editabile, întrerupător de circuit, politici), AI (buget de gândire, prompt de sistem, cache prompt), Avansat (proxy).

Lista de verificare a verificării operaționale

  • Construire din sursă: npm run build
  • Creați imaginea Docker: docker build -t omniroute .
  • Porniți serviciul și verificați:
  • GET /api/settings
  • GET /api/v1/models
  • Adresa URL de bază țintă CLI ar trebui să fie http://<host>:20128/v1 când PORT=20128