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

OmniRoute Codebase Documentation (Latviešu)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Versija: v3.8.51 Pēdējoreiz atjaunināts: 2026-06-28 Mērķauditorija: Inženieri, kuri sniedz ieguldījumu OmniRoute izstrādē vai veido uz tā balstītas integrācijas.

Augsta līmeņa arhitektūras diagrammas un katras apakšsistēmas pamatojumu skatiet ARCHITECTURE.md. Detalizētu informāciju par atsevišķām apakšsistēmām (Auto Combo, MCP serveri, A2A serveri, Skills, Memory, Cloud Agents, Resilience, Compression utt.) skatiet tām veltītajos failos šajā docs/ direktorijā.

Šajā failā ir aprakstīts, kas repozitorijā pastāv pašlaik, lai jaunais inženieris varētu orientēties direktoriju kokā, izprast izpildlaika slāņojumu un zinātu, kur pievienot kodu, neizgudrojot jaunus moduļus.

---

1. Tehnoloģiju steks

Aspekts	Izvēle
Tīmekļa ietvars	Next.js 16 (App Router, savrupa izvade, nav globālas starpprogrammatūras)
Valoda	TypeScript 6.0+ — mērķis ES2022, module: esnext, moduleResolution: bundler, strict: false
Izpildvide	Node.js >=22.22.2 <23 vai >=24.0.0 <27 (nodrošināts ar engines + SUPPORTED_NODE_RANGE)
Datubāze	SQLite, izmantojot better-sqlite3 (viena instance, WAL žurnalēšana)
Darbvirsma	Electron 41 + electron-builder 26.10 (atsevišķa darbvieta direktorijā electron/)
Testi	Node iebūvētais testu izpildītājs (vienību/integrācijas), Vitest (MCP, autoCombo, kešatmiņa), Playwright (e2e + protocols-e2e)
Būvēšana	Next.js savrupais režīms, izmantojot scripts/build/build-next-isolated.mjs
Lintēšana/formatēšana	ESLint vienotā konfigurācija + Prettier (lint-staged, izmantojot Husky pirmskomita āķi)
Moduļu sistēma	Visur ESM ("type": "module")
Darbvietas	npm darbvieta — open-sse ir vienīgā apakšdarbvieta

Ceļu aizstājvārdi (tsconfig.json):

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

Noklusējuma HTTP ports: 20128 (API un informācijas panelis izmanto vienu un to pašu procesu). Datu direktoriju nosaka vides mainīgais DATA_DIR; tā noklusējuma vērtība ir ~/.omniroute/.

---

2. Repozitorija izkārtojums

OmniRoute/
├── src/                  Next.js lietojumprogramma (App Router, bibliotēkas, domēns, serveris, koplietojamais kods)
├── open-sse/             Straumēšanas dzinēja darbvieta (@omniroute/open-sse)
├── electron/             Darbvirsmas ietvars (Electron 41 galvenais process + preload)
├── bin/                  CLI ieejas punkti (omniroute, reset-password)
├── tests/                Vienību, integrācijas, e2e, protocols-e2e, tulkotāja, drošības testi un testa dati
├── scripts/              Būvēšanas, sinhronizācijas, pārbaužu, migrācijas un izpildlaika palīgskripti
├── docs/                 Publiskā dokumentācija (šis direktorijs)
├── public/               Statiskie resursi, PWA manifests, servisa darbinieks
├── config/               Izpildlaika konfigurācijas paraugi
├── images/               Mārketinga/ekrānuzņēmumu resursi
├── _ideia/, _references/, _mono_repo/, _tasks/   Iekšējie melnraksti/plānošana (netiek izplatīti)
├── CLAUDE.md             Repozitorija noteikumi Claude Code vajadzībām
├── AGENTS.md             Padziļināta arhitektūras atsauce aģentiem
├── package.json          v3.8.51, darbvietas sakne
└── tsconfig.json         Ceļu aizstājvārdi + kompilatora pamatopcijas

---

3. src/ — Next.js lietotne

src/
├── app/                  App Router lapas + API maršruti
├── lib/                  Pamatbibliotēkas (DB, autentifikācija, OAuth, prasmes, atmiņa, …)
├── domain/               Tīrs domēna slānis (politika, atkāpšanās mehānisms, izmaksas, bloķēšana, …)
├── server/               Tikai serverim paredzēti moduļi (autorizācija, CORS, autentifikācija)
├── shared/               Tipi, konstantes, validācija, līgumi, utilītas (drošas lietošanai pāri robežām)
├── mitm/                 Starpniekservera palīgfunkcijas CLI integrācijai
├── models/               Lokālo modeļu metadati / aizstājvārdi
├── sse/                  Mantotie SSE apstrādātāji, kas joprojām atrodas zem src/ (nevis open-sse/)
├── store/                Klienta puses stāvokļa krātuves
├── middleware/           Maršruta līmeņa starpprogrammatūras utilītas (nevis Next.js globālā starpprogrammatūra)
├── scripts/              Kokā iekļauti skripti, kurus var importēt lietotnes kods
├── types/                Apkārtējie un koplietojamie TS tipi
├── i18n/                 Lokalizācijas pakotnes
├── instrumentation.ts    Next.js instrumentācijas āķis
├── instrumentation-node.ts
└── proxy.ts              Augstākā līmeņa starpniekservera sāknēšanas palīgfunkcija

3.1 src/app/ — App Router

App Router nodrošina gan informācijas paneļa lietotāja saskarni, gan publisko/pārvaldības HTTP API. Globālas starpprogrammatūras nav — pārtveršana tiek veikta katram maršrutam atsevišķi.

Augstākā līmeņa segmenti zem src/app/:

Ceļš	Nolūks
api/	Visi HTTP API maršruti (skatiet sadalījumu tālāk)
a2a/	A2A JSON-RPC 2.0 galapunkts (POST /a2a)
.well-known/agent.json/	A2A aģenta kartes atklāšanas dokuments
(dashboard)/	Informācijas paneļa lietotāja saskarne (maršrutu grupa bez URL prefiksa)
auth/, login/, forgot-password/, callback/	Autentifikācijas plūsmas
landing/	Mārketinga/sākumlapa
docs/	Iegultais API dokumentācijas skatītājs
status/, maintenance/, offline/	Darbības lapas
privacy/, terms/	Juridiskās lapas
400/, 401/, 403/, 408/, 429/, 500/, 502/, 503/	Statiskās kļūdu lapas
error.tsx, global-error.tsx, not-found.tsx, forbidden/, loading.tsx	Ietvara kļūdu/ielādes robežas
layout.tsx, page.tsx, globals.css, manifest.ts	Saknes ietvars

3.1.1 src/app/(dashboard)/dashboard/ — Lietotāja saskarnes lapas

agents, analytics, api-manager, audit, auto-combo, batch, cache, changelog, cli-tools, cloud-agents, combos, compression, context, costs, endpoint, health, limits, logs, memory, onboarding, playground, providers, search-tools, settings, skills, system, translator, usage, webhooks, kā arī saknes page.tsx, HomePageClient.tsx, BootstrapBanner.tsx.

3.1.2 src/app/api/ — Augstākā līmeņa API grupas

src/app/api/
├── a2a/{status, tasks}
├── acp/
├── admin/
├── analytics/
├── assess/
├── auth/
├── batches/
├── cache/
├── cli-tools/
├── cloud/{codex-responses-ws}
├── combos/
├── compliance/
├── compression/
├── context/
├── db/, db-backups/
├── evals/
├── fallback/
├── files/
├── health/
├── init/
├── internal/{concurrency}
├── keys/
├── logs/
├── mcp/{audit, sse, status, stream, tools}
├── memory/{health, [id]/, route.ts}
├── model-combo-mappings/
├── models/
├── monitoring/
├── oauth/
├── openapi/
├── policies/
├── pricing/
├── provider-metrics/, provider-models/, provider-nodes/
├── providers/
├── rate-limit/, rate-limits/
├── resilience/
├── restart/, shutdown/
├── search/
├── sessions/
├── settings/
├── skills/{executions, [id], install, marketplace, route.ts, skillssh}
├── storage/
├── sync/, synced-available-models/
├── system/
├── tags/
├── telemetry/
├── token-health/
├── translator/
├── tunnels/
├── services/   Iegulto pakalpojumu pārvaldība (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         Ar OpenAI saderīga publiskā API
├── v1beta/     Gemini stila saderība
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — Iegulto pakalpojumu pārvaldība

Maršruti 9Router un CLIProxyAPI instalēšanai, palaišanai, apturēšanai un uzraudzībai. Visi ceļi ir klasificēti kā LOCAL_ONLY (tikai atgriezeniskās cilpas saskarne, stingrais noteikums #17), jo tie var izsaukt npm install un palaist bērnprocesus.

src/app/api/services/
├── 9router/
│   ├── _lib.ts             getOrInitSupervisor() palīgfunkcija
│   ├── install/route.ts    POST — npm install, izmantojot execFile
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — npm install jaunākai versijai
│   ├── rotate-key/route.ts POST — jaunas API atslēgas ģenerēšana + restartēšana
│   ├── status/route.ts     GET  — reāllaika + DB statuss + versijas metadati
│   └── auto-start/route.ts POST — auto_start karoga pārslēgšana
├── cliproxy/
│   ├── _lib.ts             getOrInitSupervisor() palīgfunkcija
│   ├── install/route.ts    POST — npm install
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — npm install jaunākai versijai
│   ├── status/route.ts     GET  — reāllaika + DB statuss + versijas metadati
│   └── auto-start/route.ts POST — auto_start karoga pārslēgšana
└── [name]/
    └── logs/route.ts       GET  — SSE žurnāla beigu straume (koplietota visiem pakalpojumiem)

Atbilstošā informācijas paneļa lietotāja saskarne: src/app/(dashboard)/dashboard/providers/services/ — divu cilņu lapa (CLIProxyAPI + 9Router). Reversais starpniekserveris 9Router iegultajai lietotāja saskarnei: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

Padziļināts apraksts: docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — ar OpenAI saderīga publiskā API

v1/
├── accounts/[id]/                       konta uzmeklēšana
├── agents/tasks/[id]/, agents/tasks/    A2A stila uzdevumu galapunkti
├── api/                                 iekšējās API palīgfunkcijas, kas pieejamas zem v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    tērzēšanas pabeigšanas (galvenais galapunkts)
├── completions/                         mantotās teksta pabeigšanas
├── embeddings/                          iegulumi
├── files/[id]/, files/                  failu API
├── _helpers/                            koplietoti maršrutu palīgrīki (bez publiska URL)
├── images/{edits, generations}/         attēlu ģenerēšana + rediģēšana
├── issues/                              problēmu sākotnējās izvērtēšanas palīggalapunkti
├── management/{proxies}/                pārvaldības tvēruma maršruti v1 iekšienē
├── messages/{count_tokens}/             saderība ar Anthropic stila ziņojumiem
├── models/                              modeļu uzskaitījums (`route.ts`, `catalog.ts`)
├── moderations/                         moderācija
├── music/                               mūzikas ģenerēšana
├── providers/[provider]/                katram nodrošinātājam specifiskas darbības
├── quotas/{check}                       kvotu pārbaudes
├── registered-keys/                     reģistrēto atslēgu administrēšana
├── rerank/                              atkārtota ranžēšana
├── responses/[...path]/                 OpenAI Responses API (visaptverošs maršruts)
├── search/                              meklēšana tīmeklī
├── videos/                              video ģenerēšana
├── ws/                                  WebSocket tilts
└── route.ts                             indeksa apstrādātājs

Katrs maršruta fails izmanto vienu un to pašu shēmu:

Maršruts → CORS priekšpieprasījums → Zod pieprasījuma ķermeņa validācija → neobligāta autentifikācija
         → API atslēgas politikas piemērošana → deleģēšana apstrādātājam (open-sse)

v1beta/ ir ar Gemini stilu saderīga virsma (plāns ietvars, kas pārveido datus, lai izmantotu to pašu open-sse/handlers/ konveijeru).

3.2 src/lib/ — Pamatbibliotēkas

Vienmēr importējiet datus, sinhronizāciju, OAuth, prasmes, atmiņu utt., izmantojot šos moduļus. Tabulā ir grupēti faktiskie direktoriji un ievērojamākie augšējā līmeņa faili.

Modulis	Mērķis
a2a/	A2A protokola serveris: taskManager.ts, streaming.ts, taskExecution.ts, routingLogger.ts, skills/ (6 prasmes: izmaksu analīze, darbspējas pārskats, pakalpojumu sniedzēju atklāšana, kvotu pārvaldība, viedā maršrutēšana, iespēju uzskaitīšana)
acp/	Aģentu vadības protokols: index.ts, manager.ts, registry.ts
api/	Iekšējie API palīgrīki: requireManagementAuth.ts, requireCliToolsAuth.ts, errorResponse.ts
auth/	managementPassword.ts (paroles atiestatīšana / jaukšana)
batches/	OpenAI Batches API pakalpojums (service.ts)
catalog/	OpenRouter kataloga sinhronizācija (openrouterCatalog.ts)
cloudAgent/	Mākoņa aģentu reģistrs: api.ts, baseAgent.ts, db.ts, index.ts, registry.ts, types.ts, agents/{codex, devin, jules}.ts
combos/	Kombināciju atrisināšanas palīgfunkcijas
compliance/	Audits un pakalpojumu sniedzēju audits: index.ts, providerAudit.ts
config/	Izpildlaika konfigurācijas integrācijas kods
db/	SQLite domēna moduļi (skatiet §3.2.1)
display/	Lietotāja saskarnes/attēlošanas palīgfunkcijas, ko izmanto API atbildes
embeddings/	Ieguldījumu pakalpojumu reģistrs
env/	Vides mainīgo ielāde un introspekcija
evals/	Novērtēšanas izpildlaika vide
guardrails/	piiMasker.ts, promptInjection.ts, visionBridge.ts, visionBridgeHelpers.ts, registry.ts, base.ts
jobs/	Fona uzdevumi (autoUpdate.ts, …)
memory/	Pastāvīgā atmiņa: store.ts, cache.ts, retrieval.ts, summarization.ts, extraction.ts, injection.ts, qdrant.ts, settings.ts, verify.ts, schemas.ts, types.ts
monitoring/	observability.ts
oauth/	OAuth/importēšanas nodrošinātāju moduļi (22): agy, antigravity, claude, cline, codebuddy-cn, codex, cursor, devin-desktop, ghe-copilot, github, gitlab-duo, grok-cli-oauth, grok-cli, kilocode, kimi-coding, kiro, openference, qoder, trae, xai-oauth, zed-hosted, zed, kā arī services/, utils/ un constants/oauth.ts
plugins/	Spraudņu ielādētājs (index.ts)
promptCache/	prefixAnalyzer.ts, index.ts
providerModels/	Pārvaldīts modeļu dzīves cikls: modelDiscovery.ts, managedModelImport.ts, managedAvailableModels.ts, cursorAgent.ts
providers/	Pakalpojumu sniedzēju palīgfunkcijas: catalog.ts, validation.ts, imageValidation.ts, claudeExtraUsage.ts, codexConnectionDefaults.ts, codexFastTier.ts, webCookieAuth.ts, managedAvailableModels.ts, requestDefaults.ts
resilience/	settings.ts — ķēdes pārtraucēja, atdzišanas perioda un bloķēšanas iestatījumi
runtime/	Izpildlaika funkcionalitātes noteikšana
search/	executeWebSearch.ts
services/	Iegulto pakalpojumu ietvars: ServiceSupervisor.ts (vispārīgs bērnprocesu pārraugs ar operāciju bloķētāju, gredzenbuferi un darbspējas pārbaudītāju), bootstrap.ts (procesa līmeņa reģistrācija un automātiska palaišana), registry.ts (rīka → pārrauga kartējums), apiKey.ts (AES-256-GCM atslēgu krātuve), modelSync.ts (periodiska modeļu sinhronizācija), ringBuffer.ts (5 MB ciklisks žurnāla buferis), healthCheck.ts (HTTP darbspējas pārbaude), types.ts, embedWsProxy.ts (WebSocket starpniekserveris), installers/{ninerouter,cliproxy}.ts. Skatiet docs/frameworks/EMBEDDED-SERVICES.md
agentSkills/	Aģenta prasmju katalogs un ģenerators: catalog.ts (getCatalog/getSkillById/filterCatalog/computeCoverage), generator.ts (generateAgentSkills → ieraksta skills/{id}/SKILL.md), openapiParser.ts (izgūst REST galapunktus no OpenAPI specifikācijas), cliRegistryParser.ts (izgūst CLI apakškomandas no bin/cli-registry), schemas.ts (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), types.ts (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Izmanto REST maršruti (/api/agent-skills/*), MCP rīki (omniroute_agent_skills_*) un A2A prasme list-capabilities. Skatiet AGENT-SKILLS.md.
skills/	Prasmju ietvars: registry.ts, executor.ts, interception.ts, injection.ts, sandbox.ts, custom.ts, hybrid.ts, builtins.ts, a2a.ts, providerSettings.ts, schemas.ts, skillssh.ts, types.ts, kā arī builtin/browser.ts
spend/	batchWriter.ts (atliktās rakstīšanas buferis)
sync/	bundle.ts, tokens.ts (mākoņa sinhronizācija)
system/	Sistēmas līmeņa palīgfunkcijas
translator/	Augstākā līmeņa tulkotāja sasaistes kods (deleģē uz open-sse/translator/)
usage/	Lietojuma uzskaite: costCalculator.ts, tokenAccounting.ts, usageHistory.ts, aggregateHistory.ts, usageStats.ts, callLogs.ts, callLogArtifacts.ts, fetcher.ts, providerLimits.ts, migrations.ts
versionManager/	Automātiskā atjaunināšana un versiju manifests
ws/	WebSocket tilts
zed-oauth/	Zed redaktora OAuth plūsma

Augstākā līmeņa faili direktorijā src/lib/:

• Vecais localDb.ts apvienojošais modulis tika noņemts — patērētāji tieši importē konkrētus src/lib/db/* moduļus.
• proxyHealth.ts, proxyLogger.ts, tokenHealthCheck.ts, localHealthCheck.ts
• apiBridgeServer.ts, cacheLayer.ts, semanticCache.ts, settingsCache.ts
• cloudSync.ts, initCloudSync.ts
• cloudflaredTunnel.ts, ngrokTunnel.ts, tailscaleTunnel.ts
• consoleInterceptor.ts, container.ts, gracefulShutdown.ts, idempotencyLayer.ts
• ipUtils.ts, logEnv.ts, logPayloads.ts, logRotation.ts
• modelAliasSeed.ts, modelCapabilities.ts, modelMetadataRegistry.ts, modelsDevSync.ts
• piiSanitizer.ts, pricingSync.ts
• apiKeyExposure.ts, cacheControlSettings.ts, dataPaths.ts, toolPolicy.ts
• translatorEvents.ts, usageDb.ts, usageAnalytics.ts, webhookDispatcher.ts

3.2.1 src/lib/db/

Vieninstances SQLite datubāze (getDbInstance() failā core.ts, WAL žurnalēšana). Nekad nerakstiet neapstrādātu SQL maršrutos vai apstrādātājos — izmantojiet šos moduļus.

Avots: diagrams/db-schema-overview.mmd

Domēna moduļi (katrs pārvalda vienu vai vairākas tabulas): apiKeys.ts, backup.ts, batches.ts, cleanup.ts, cliToolState.ts, combos.ts, commandCodeAuth.ts, compression.ts, compressionAnalytics.ts, compressionCacheStats.ts, compressionCombos.ts, compressionScheduler.ts, contextHandoffs.ts, core.ts, creditBalance.ts, databaseSettings.ts, detailedLogs.ts, domainState.ts, encryption.ts, evals.ts, files.ts, healthCheck.ts, jsonMigration.ts, migrationRunner.ts, modelComboMappings.ts, models.ts, oneproxy.ts, prompts.ts, providers.ts, providerLimits.ts, proxies.ts, quotaSnapshots.ts, readCache.ts, reasoningCache.ts, registeredKeys.ts, secrets.ts, sessionAccountAffinity.ts, settings.ts, stateReset.ts, stats.ts, syncTokens.ts, tierConfig.ts, upstreamProxy.ts, versionManager.ts, webhooks.ts.

migrations/ satur 168 versijotus .sql failus (idempotentus un transakcionālus), un sistēmas palaišanas laikā tos izpilda migrationRunner.ts.

Migrāciju gaitā izveidotās tabulas (kopā 123):

a, account_key_limits, api_keys, batches, call_logs, combo_adaptation_state, combos, command_code_auth_sessions, compression_analytics, compression_cache_stats, compression_combo_assignments, compression_combos, context_handoffs, daily_usage_summary, db_meta, domain_budgets, domain_circuit_breakers, domain_cost_history, domain_fallback_chains, domain_lockout_state, eval_cases, eval_runs, eval_suites, files, hourly_usage_summary, key_value, mcp_tool_audit, memories, model_combo_mappings, provider_connections, provider_key_limits, provider_nodes, proxy_assignments, proxy_logs, proxy_registry, quota_snapshots, reasoning_cache, registered_keys, request_detail_logs, routing_decisions, semantic_cache, session_account_affinity, skill_executions, skills, sync_tokens, tier_assignments, tier_config, upstream_proxy_config, usage_history, version_manager, webhooks (kā arī FTS5 virtuālās tabulas atmiņas meklēšanai).

3.3 src/domain/ — Domēna slānis

Tīra biznesa loģika bez ievades/izvades operācijām. To importē maršruti un apstrādātāji.

Fails	Nolūks
policyEngine.ts	Augstākā līmeņa politiku atrisinātājs
fallbackPolicy.ts	Rezerves risinājuma lēmumu koks
costRules.ts	Izmaksu aprēķināšanas noteikumi
lockoutPolicy.ts	Lēmumi par modeļu bloķēšanu
tagRouter.ts	Uz tagiem balstīta maršrutēšana
comboResolver.ts	Kombinācijas noteikšana no pieprasījuma → mērķu saraksts
connectionModelRules.ts	Modeļu filtri katram savienojumam
modelAvailability.ts	Modeļa pieejamības pārbaude
degradation.ts	Pārejas uz degradētu režīmu
providerExpiration.ts	Kontu/atslēgu ar beigušos derīguma termiņu noteikšana
quotaCache.ts	Kešoti kvotu lēmumi
responses.ts, omnirouteResponseMeta.ts	Atbildes struktūras palīgfunkcijas
configAudit.ts	Konfigurācijas izmaiņu audits
assessment/	Modeļu novērtēšana (saskaņā ar RFC, daļēji ieviesta)
types.ts	Koplietojamie domēna tipi

3.4 src/server/ — Tikai serverim

Nevar importēt klienta komponentos.

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Klasificē maršrutus kā publiskus vai pārvaldības maršrutus
│   ├── assertAuth.ts      Apstiprinājuma palīgfunkcija
│   ├── context.ts         Katra pieprasījuma autorizācijas konteksts
│   ├── headers.ts
│   ├── pipeline.ts        Autorizācijas konveijers
│   ├── policies/          Konkrētas politikas
│   └── types.ts
└── cors/origins.ts        Atļauto CORS izcelsmes avotu saraksts

3.5 src/shared/ — Droši koplietojams

Sadalīts mērķorientētos apakšdirektorijos:

• constants/ — providers.ts (ar Zod validēts pakalpojumu sniedzēju katalogs), models.ts, modelSpecs.ts, modelCompat.ts, pricing.ts, cliTools.ts, cliCompatProviders.ts, routingStrategies.ts, comboConfigMode.ts, headers.ts, upstreamHeaders.ts (aizliegumu saraksts), mcpScopes.ts, errorCodes.ts, publicApiRoutes.ts, batch.ts, batchEndpoints.ts, bodySize.ts, colors.ts, appConfig.ts, config.ts, sidebarVisibility.ts, visionBridgeDefaults.ts.
• validation/ — schemas.ts (~80 Zod shēmas), compressionConfigSchemas.ts, providerSchema.ts, settingsSchemas.ts, helpers.ts.
• contracts/ — publiskās API līgumi, kas tiek publicēti npm.
• types/ — koplietojami TS tipi.
• utils/ — circuitBreaker.ts, apiAuth.ts, apiKey.ts, apiKeyPolicy.ts, api.ts, classify429.ts, cliCompat.ts, clipboard.ts, cloud.ts, cn.ts, cors.ts, featureFlags.ts, fetchTimeout.ts, formatting.ts, inputSanitizer.ts, logger.ts, machine.ts, machineId.ts, maskEmail.ts, modelCatalogSearch.ts, nodeRuntimeSupport.ts, parseApiKeys.ts, providerHints.ts, providerModelAliases.ts, rateLimiter.ts, releaseNotes.ts, a11yAudit.ts, kā arī informācijas paneļa āķi/komponenti mapēs services/, network/, middleware/, schemas/, hooks/, components/.

---

4. open-sse/ — Straumēšanas dzinēja darbvieta

Atsevišķa npm darbvieta, kas publicēta kā @omniroute/open-sse. Tā pārvalda pieprasījumu apstrādi, izpildītājus, tulkotājus, pakalpojumus, transformatoru un MCP serveri.

open-sse/
├── index.ts                Publiskie eksporti
├── package.json            Darbvietas manifests
├── tsconfig.json
├── types.d.ts
├── config/                 Nodrošinātāju reģistri, galveņu profili, identitāte, …
├── handlers/               Pieprasījumu apstrādātāji (tērzēšana, iegultnes, audio, attēli, …)
├── executors/              108 nodrošinātājiem specifiski HTTP izpildītāji
├── translator/             Formātu pārveidošana (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Responses API ↔ Chat Completions straumes transformators
├── services/               Vairāk nekā 80 pakalpojumu moduļu (kombinācijas, atkāpšanās, kvotas, identitāte, …)
├── utils/                  Straumēšanas palīgrīki, TLS klients, AWS SigV4, starpniekservera izgūšana, …
└── mcp-server/             MCP serveris (3 transporti, 33 tvērumi, 110 rīki)

4.1 open-sse/handlers/

Apstrādātājs	Nolūks
chatCore.ts	Galvenais tērzēšanas konveijers (kešatmiņa, ātruma ierobežošana, kombināciju maršrutēšana, izpildītāja izsaukšana)
responsesHandler.ts	OpenAI Responses API ieejas punkts
embeddings.ts	Iegultnes
imageGeneration.ts	Attēlu ģenerēšana
audioSpeech.ts	Teksta pārveidošana runā
audioTranscription.ts	Runas pārveidošana tekstā
videoGeneration.ts	Video ģenerēšana
musicGeneration.ts	Mūzikas ģenerēšana
rerank.ts	Atkārtota ranžēšana
moderations.ts	Moderēšana
search.ts	Meklēšana tīmeklī
sseParser.ts	SSE notikumu parsētājs
usageExtractor.ts	Tokenu skaita iegūšana no augšupējām straumēm
responseSanitizer.ts	Nodrošinātājam specifiskā trokšņa noņemšana
responseTranslator.ts	Savienojošais slānis starp nodrošinātāja atbildi un tulkošanas slāni

4.2 open-sse/executors/

108 nodrošinātāju izpildītāji, no kuriem katrs paplašina BaseExecutor (base.ts):

antigravity, azure-openai, blackbox-web, cliproxyapi, chatgpt-web-codex, cloudflare-ai, codex, commandCode, cursor, default, devin-cli, muse-spark-web, nlpcloud, opencode, perplexity-web, petals, pollinations, qoder, vertex, devin-desktop, kā arī claudeIdentity.ts (koplietots identitātes palīgrīks) un index.ts (reģistrs).

Piezīme: nodrošinātājus, kas šeit nav uzskaitīti, apkalpo default.ts, izmantojot vispārīgo ar OpenAI saderīgo izpildītāju. Pilnais nodrošinātāju katalogs (355 nodrošinātāji) atrodas src/shared/constants/providers.ts.

4.3 open-sse/translator/

Centrmezgla un atzaru tipa tulkošana (OpenAI ir centrmezgls).

• 9 pieprasījumu tulkotāji (translator/request/): antigravity-to-openai, claude-to-gemini, claude-to-openai, gemini-to-openai, openai-responses, openai-to-claude, openai-to-cursor, openai-to-gemini, openai-to-kiro.
• 9 atbilžu tulkotāji (translator/response/): claude-to-openai, cursor-to-openai, gemini-to-claude, gemini-to-openai, kiro-to-openai, openai-responses, openai-to-antigravity, openai-to-claude.
• 9 palīgrīki (translator/helpers/): claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper, kā arī palīgrīku testi.
• Attēlu palīgrīki (translator/image/sizeMapper.ts).
• Augšējais līmenis: bootstrap.ts, formats.ts, registry.ts, index.ts.

4.4 open-sse/transformer/

• responsesTransformer.ts — uz TransformStream balstīts Responses API ↔ Chat Completions pārveidotājs (to izmanto responses/ maršruta universālais apstrādātājs).

4.5 open-sse/services/

Svarīgākie moduļi (pilns saraksts atrodas sadaļā open-sse/services/):

Joma	Faili
Kombinētā maršrutēšana	combo.ts (19 stratēģijas), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
Auto Combo dzinis	autoCombo/ — engine.ts, scoring.ts, taskFitness.ts, virtualFactory.ts, modePacks.ts, autoPrefix.ts, persistence.ts, providerDiversity.ts, providerRegistryAccessor.ts, routerStrategy.ts, selfHealing.ts, index.ts
Noturība	accountFallback.ts (nogaidīšanas periods + bloķēšana), errorClassifier.ts, requestRejectedStreak.ts, emergencyFallback.ts, rateLimitManager.ts, rateLimitSemaphore.ts, accountSemaphore.ts, accountSelector.ts
Kvotas	quotaMonitor.ts, quotaPreflight.ts, bailianQuotaFetcher.ts, codexQuotaFetcher.ts, deepseekQuotaFetcher.ts, openrouterQuotaFetcher.ts, openrouterFreeWindow.ts, crofUsageFetcher.ts, antigravityCredits.ts
Kešatmiņa	reasoningCache.ts, searchCache.ts, signatureCache.ts, requestDedup.ts
Maršrutēšanas intelekts	intentClassifier.ts, taskAwareRouter.ts, backgroundTaskDetector.ts, volumeDetector.ts, wildcardRouter.ts, workflowFSM.ts, specificityDetector.ts, specificityRules.ts, specificityTypes.ts
Modeļu apstrāde	modelCapabilities.ts, modelDeprecation.ts, modelFamilyFallback.ts, modelStrip.ts, model.ts, provider.ts, providerRequestDefaults.ts, providerCostData.ts, payloadRules.ts
Saspiešana	compression/ — pilns saspiešanas dziņa savienojums
Pilnvara + sesija	tokenRefresh.ts, sessionManager.ts, apiKeyRotator.ts, contextManager.ts, contextHandoff.ts, systemPrompt.ts, roleNormalizer.ts, responsesInputSanitizer.ts, toolSchemaSanitizer.ts, toolLimitDetector.ts, thinkingBudget.ts
Līmenis / manifests	tierResolver.ts, tierConfig.ts, tierDefaults.json, tierTypes.ts, manifestAdapter.ts
IP / tīkls	ipFilter.ts, webSearchFallback.ts
Paketes	batchProcessor.ts
Lietojums	usage.ts

4.6 open-sse/mcp-server/

• 110 unikāli rīki, kas savienoti failā server.ts (45 kanoniskie rīki failā schemas/tools.ts + atmiņas, prasmju, GitHub prasmju, pūla, spēliskošanas, spraudņu, Notion, Obsidian, lokālā korpusa un saspiešanas moduļi — apvienojums saskaitīts ar countUniqueMcpTools).
• 3 transporti: stdio, HTTP Streamable, SSE.
• 33 tvērumi, kas tiek piemēroti izpildlaikā — pamata saraksts atrodas failā src/shared/constants/mcpScopes.ts, bet pilnā kopa ir katra rīku moduļa deklarēto tvērumu apvienojums.
• Audita tabula: mcp_tool_audit (aizpilda audit.ts).
• Faili: server.ts, index.ts, httpTransport.ts, audit.ts, scopeEnforcement.ts, runtimeHeartbeat.ts, descriptionCompressor.ts, schemas/{tools, a2a, audit, index}.ts, tools/{advancedTools, compressionTools, memoryTools, skillTools}.ts, kā arī testi direktorijā __tests__/.
• Pilnu rīku katalogu skatiet dokumentā MCP-SERVER.md.

4.7 open-sse/config/

Pakalpojumu sniedzēju reģistri (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), katra formāta modeļu reģistri (audioRegistry.ts, embeddingRegistry.ts, imageRegistry.ts, moderationRegistry.ts, musicRegistry.ts, rerankRegistry.ts, searchRegistry.ts, videoRegistry.ts), identitātes palīgfunkcijas (codexIdentity.ts, codexInstructions.ts, anthropicHeaders.ts, antigravityUpstream.ts, antigravityModelAliases.ts, cliFingerprints.ts, toolCloaking.ts, defaultThinkingSignature.ts), akreditācijas datu palīgfunkcijas (credentialLoader.ts, codexClient.ts) un mākoņa adapteri (azureAi.ts, bedrock.ts, datarobot.ts, glmProvider.ts, maritalk.ts, oci.ts, petals.ts, runway.ts, sap.ts, watsonx.ts, ollamaModels.ts, errorConfig.ts, constants.ts, registryUtils.ts).

4.8 open-sse/utils/

Straumēšanas primitīvi un pakalpojumu sniedzēju palīgmoduļi: stream.ts, streamHandler.ts, streamHelpers.ts, streamPayloadCollector.ts, streamReadiness.ts, sseHeartbeat.ts, proxyFetch.ts, proxyDispatcher.ts, tlsClient.ts, networkProxy.ts, awsSigV4.ts, cacheControlPolicy.ts, cursorChecksum.ts, cursorAgentProtobuf.ts, cursorVersionDetector.ts, comfyuiClient.ts, kieTask.ts, bypassHandler.ts, aiSdkCompat.ts, thinkTagParser.ts, urlSanitize.ts, usageTracking.ts, requestLogger.ts, progressTracker.ts, cors.ts, error.ts, logger.ts, sleep.ts, ollamaTransform.ts.

---

5. electron/ — Darbvirsmas ietvars

electron/
├── main.js                  Electron galvenais process
├── preload.js               Priekšielādes tilts (iespējots contextIsolation)
├── types.d.ts
├── package.json             electron-builder konfigurācija, versija 3.8.51
├── README.md
├── assets/                  Būvējuma resursi (ikonas, pilnvarojumi, …)
├── node_modules/            Atsevišķs node_modules (better-sqlite3, electron-updater)
└── dist-electron/           Būvējuma izvade (netiek iekļauta repozitorijā)

Darbvietas saknē ir pieci npm skripti: electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged. Automātiskā atjaunināšana tiek veikta, izmantojot electron-updater, kas norāda uz GitHub laidienu plūsmu.

---

6. bin/ — CLI

bin/
├── omniroute.mjs           Galvenais CLI ieejas punkts (Node ESM)
├── reset-password.mjs      Pārvaldības paroles atiestatīšana no CLI
├── mcp-server.mjs          MCP servera palaidējs (stdio)
├── nodeRuntimeSupport.mjs  Node versijas pārbaude
└── cli/
    ├── program.mjs         Commander programmas veidotājs
    ├── runtime.mjs         withRuntime palīgfunkcija (vispirms serveris / rezerves variants — DB)
    ├── output.mjs          Izvades formatētāji (json/jsonl/table/csv)
    ├── i18n.mjs            t() palīgfunkcija ar lokalizācijām
    ├── api.mjs             API fetch palīgfunkcija
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Komandu reģistrācija
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (viens fails katrai komandai/grupai)

Sadaļā package.json → bin ir pieejami divi izpildāmie faili:

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

---

7. tests/

Direktorijs	Veids
tests/unit/	Vienībtesti, izmantojot Node iebūvēto testu izpildītāju (1821 fails, kā arī api/, auth/, authz/ apakšdirektoriji)
tests/integration/	Starpmoduļu un DB stāvokļa testi
tests/e2e/	Playwright lietotāja saskarnes testi
tests/e2e/protocol-clients.test.ts	MCP/A2A protokolu e2e testi
tests/translator/	Tulkotājam specifiski testi
tests/security/	Drošības regresiju testi
tests/load/	Slodzes/stresa testi
tests/golden-set/	Atsauces izvades tulkotāja regresiju testiem
tests/helpers/, tests/fixtures/, tests/manual/	Atbalsta faili

Biežāk lietotās komandas:

Komanda	Ko tā izpilda
npm run test:unit	Visus tests/unit/*.test.ts testus, izmantojot Node testu izpildītāju (paralēlisms 10)
npm run test:vitest	Vitest testu komplektu (MCP, autoCombo, cache)
npm run test:e2e	Playwright lietotāja saskarnes testu komplektu
npm run test:protocols:e2e	MCP un A2A protokolu e2e testus
npm run test:coverage	Pārklājuma slieksni (≥60% rindu/priekšrakstu/funkciju/zaru)
node --import tsx/esm --test tests/unit/<file>.test.ts	Viena faila izpildi

---

8. scripts/

Sakārtota 6 apakšmapēs pēc nolūka.

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

---

9. Pieprasījumu konveijers (kopsavilkums)

Avots: diagrams/request-pipeline.mmd

Klienta pieprasījums
  → /v1/chat/completions (route.ts)
     CORS priekšpieprasījuma pārbaude
     Zod validācija (chatCompletionsSchema failā shared/validation/schemas.ts)
     Autentifikācija (extractApiKey + isValidApiKey VAI requireManagementAuth)
     Politiku dzinis (src/server/authz/pipeline.ts)
     Aizsargmehānismi (PII maskētājs, uzvednes injekcija, attēlu apstrādes tilts)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Kešatmiņas pārbaude (semantiskā + lasīšanas kešatmiņa)
     Ātruma ierobežojums (rateLimitManager, accountSemaphore)
     Kombinētā maršrutēšana (ja modelis tiek atrisināts kā kombinācija)
       comboResolver → cikls katram mērķim → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       pieprasījums augšupstraumes pakalpojumam → atkārtots mēģinājums/eksponenciāla aizture, izmantojot accountFallback
     translateResponse() (open-sse/translator/response/*)
     SSE straume VAI JSON atbilde
     Ja Responses API: TransformStream, izmantojot open-sse/transformer/responsesTransformer.ts
  → Atbilstības audits (src/lib/compliance/)
  → Atbilde klientam

Noturības izpildlaika stāvoklis (trīs mehānismi)

Mehānisms	Tvērums	Atrašanās vieta
Nodrošinātāja ķēdes pārtraucējs	Viss nodrošinātājs	src/shared/utils/circuitBreaker.ts, saglabāts domain_circuit_breakers
Savienojuma nogaidīšanas periods	Viens konts/atslēga	markAccountUnavailable() failā src/sse/services/auth.ts; izmanto accountFallback.checkFallbackError()
Modeļa bloķēšana	Nodrošinātājs + savienojums + modelis	open-sse/services/accountFallback.ts, saglabāts domain_lockout_state

Skatiet RESILIENCE_GUIDE.md un tam veltīto sadaļu CLAUDE.md.

---

10. Kā sniegt ieguldījumu

Jauna pakalpojumu sniedzēja pievienošana

1. Reģistrējiet to failā src/shared/constants/providers.ts (ielādes laikā tiek validēts ar Zod).
2. Ja nepieciešama pielāgota loģika, pievienojiet izpildītāju direktorijā open-sse/executors/ (paplašiniet BaseExecutor).
3. Ja pakalpojumu sniedzējs neizmanto OpenAI formātu, pievienojiet tulkotāju direktorijā open-sse/translator/.
4. Ja tas izmanto OAuth, pievienojiet konfigurāciju direktorijās src/lib/oauth/providers/ un src/lib/oauth/services/.
5. Reģistrējiet modeļus failā open-sse/config/providerRegistry.ts (vai konkrētajam formātam paredzētajā reģistrā direktorijā open-sse/config/).
6. Rakstiet testus direktorijā tests/unit/.

Jauna API maršruta pievienošana

1. Izveidojiet src/app/api/your-route/route.ts.
2. Ievērojiet šādu secību: CORS → pieprasījuma pamatteksta validācija ar Zod → autentifikācija → deleģēšana apstrādātājam.
3. Ja pieprasījumam ir jauna struktūra, pievienojiet Zod shēmu failā src/shared/validation/schemas.ts.
4. Ja maršruts paredzēts tikai pārvaldībai, pievienojiet ceļu failam src/shared/constants/publicApiRoutes.ts (publiskās API saskarnes aizliegumu saraksts).
5. Pievienojiet testus direktorijā tests/unit/.
6. Atjauniniet docs/reference/API_REFERENCE.md un docs/openapi.yaml.

Jauna DB moduļa pievienošana

1. Izveidojiet src/lib/db/yourModule.ts un importējiet getDbInstance() no ./core.ts.
2. Eksportējiet sava domēna CRUD funkcijas.
3. Ja nepieciešamas jaunas tabulas, pievienojiet migrāciju direktorijā src/lib/db/migrations/; tai jābūt secīgi numurētai, idempotentai un transakcionālai.
4. Importētāji izmanto tiešus importus no @/lib/db/yourModule (bez apkopotājmoduļa — vecais localDb.ts reeksportēšanas slānis tika noņemts).
5. Pievienojiet testus direktorijā tests/unit/.

Jauna MCP rīka pievienošana

1. Pievienojiet rīka definīciju direktorijā open-sse/mcp-server/tools/ (vai paplašiniet open-sse/mcp-server/schemas/tools.ts).
2. Piešķiriet atbilstošo tvērumu vai tvērumus failā src/shared/constants/mcpScopes.ts.
3. Reģistrējiet rīku failā open-sse/mcp-server/server.ts.
4. Pievienojiet testus direktorijā open-sse/mcp-server/__tests__/.
5. Atjauniniet MCP-SERVER.md.

Jaunas A2A prasmes pievienošana

Skatiet A2A-SERVER.md § Jaunas prasmes pievienošana. Prasmes atrodas direktorijā src/lib/a2a/skills/ un tiek reģistrētas, izmantojot A2A uzdevumu pārvaldnieku.

---

11. Konvencijas

• Koda stils: 2 atstarpju atkāpe, dubultpēdiņas, 100 rakstzīmju platums, semikoli, es5 beigu komati — to nodrošina Prettier, izmantojot lint-staged.
• Importi: ārējie → iekšējie (@/, @omniroute/open-sse) → relatīvie.
• Nosaukumu piešķiršana: faili — camelCase vai kebab-case, komponenti — PascalCase, konstantes — UPPER_SNAKE.
• ESLint: no-eval, no-implied-eval, no-new-func = error visur; no-explicit-any = warn direktorijās open-sse/ un tests/, bet citur — error.
• TypeScript: strict: false (mantotā pieeja). Starpmoduļu robežām dodiet priekšroku skaidri norādītiem tipiem, nevis tipu izsecināšanai.
• Datubāze: nekad nerakstiet neapstrādātu SQL maršrutos vai apstrādātājos — vienmēr izmantojiet src/lib/db/ moduļus. Nekad neimportējiet no apkopotājmoduļa — tieši izmantojiet konkrētos src/lib/db/* moduļus.
• DB entītiju tipizēšana (#3512): funkcijai, kas raksta vai lasa DB tabulas rindas struktūru, kā parametrs jāpieņem vai kā rezultāts jāatgriež nosaukts TS interfeiss, kas 1:1 atspoguļo šīs tabulas kolonnas, nevis any vai izsaukuma vietā definēts anonīms tips. Novietojiet interfeisu blakus funkcijai (piemēram, export interface UsageEntry failā src/lib/usage/usageHistory.ts virs saveRequestUsage), atsevišķiem laukiem saglabājiet neobligāta vai null vērtību pieļaujoša lauka statusu, ja dažādi rakstītāji aizpilda rindu pakāpeniski, un laukam, kura struktūra dažādiem izsaucējiem atšķiras, dodiet priekšroku unknown, nevis any (dokumentējiet to pie lauka, piemēram, UsageEntry.tokens pieņem gan neapstrādātus pakalpojumu sniedzēja struktūras lietojuma datus, gan normalizēto struktūru). Kad šādā veidā failā any gadījumu skaits sasniedz nulli, pievienojiet to check:any-budget:t11 atļauju sarakstam (scripts/check/check-t11-any-budget.mjs, maxAny: 0), lai novērstu regresiju. Šī ir pirmā posma konvencija — plašāka anonīmo any vērtību likvidēšana pārējā kodu bāzē tiek veikta iteratīvi.
• Kļūdas: izmantojiet try/catch ar konkrētiem kļūdu tipiem un reģistrējiet žurnālā, norādot pino kontekstu. Nekad klusējot neignorējiet kļūdas SSE straumēs; tīrīšanai izmantojiet pārtraukšanas signālus.
• Drošība: nekad neizmantojiet eval() / new Function() / netiešu eval izsaukšanu. Validējiet visu ievadi ar Zod. Glabāšanas laikā šifrējiet akreditācijas datus (AES-256-GCM). Uzturiet src/shared/constants/upstreamHeaders.ts aizliegumu sarakstu saskaņotu ar sanitizācijas/validācijas slāni.
• Komiti: Conventional Commits — feat(scope): subject. Atļautie tvērumi: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.
• Zari: prefiksi feat/, fix/, refactor/, docs/, test/, chore/. Nekad neveiciet komitu tieši zarā main.
• Husky: pirms komita tiek izpildīti lint-staged + check:docs-sync + check:any-budget:t11; pirms nosūtīšanas tiek izpildīti check:any-budget:t11 + check:tracked-artifacts (ātras pārbaudes; neietver test:unit).

---

12. Stingrie noteikumi (no CLAUDE.md)

1. Nekad neiekļaujiet komitā noslēpumus vai akreditācijas datus.
2. Nekad neveiciet apkopojošu importēšanu — tieši izmantojiet konkrētus src/lib/db/* moduļus.
3. Nekad neizmantojiet eval() / new Function() / netiešu eval izpildi.
4. Nekad neveiciet komitus tieši zarā main.
5. Nekad nerakstiet neapstrādātu SQL maršrutos — vienmēr izmantojiet src/lib/db/ moduļus.
6. Nekad klusi neignorējiet kļūdas SSE straumēs.
7. Vienmēr validējiet ievaddatus ar Zod shēmām.
8. Mainot produkcijas kodu, vienmēr iekļaujiet testus.
9. Pārklājumam jāsaglabājas ≥ 60% (priekšraksti, rindas, funkcijas, zari).

---

13. Skatiet arī

• ARCHITECTURE.md — augsta līmeņa arhitektūra un moduļu atbildības.
• API_REFERENCE.md — publiskās un pārvaldības API atsauce.
• FEATURES.md — funkciju matrica un versiju svarīgākās izmaiņas.
• RESILIENCE_GUIDE.md — padziļināts ieskats ķēdes pārtraucējā, nogaidīšanas periodā un bloķēšanā.
• AUTO-COMBO.md — Auto Combo vērtēšana un stratēģijas.
• MCP-SERVER.md — pilns MCP rīku katalogs un transporti.
• A2A-SERVER.md — A2A protokola prasmes un atklāšana.
• COMPRESSION_GUIDE.md — RTK un Caveman saspiešana.
• CLI-TOOLS.md — CLI integrācijas.
• ELECTRON_GUIDE.md (ja pieejams), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — izvietošanas mērķi.
• TROUBLESHOOTING.md — biežākās darbības problēmas.
• CONTRIBUTING.md — līdzstrādnieku darbplūsma.
• CLAUDE.md — repozitorija noteikumi Claude Code (patiesības avots daudzām iepriekš minētajām konvencijām).
• AGENTS.md — padziļināta arhitektūras atsauce, ko izmanto aģenti.