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

OmniRoute Codebase Documentation (Русский)

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

---

Версия: v3.8.51 Последнее обновление: 2026-06-28 Аудитория: Инженеры, вносящие вклад в OmniRoute или создающие интеграции на его основе.

Высокоуровневые архитектурные диаграммы и обоснование каждого компонента приведены в ARCHITECTURE.md. Подробные сведения об отдельных компонентах (Auto Combo, MCP-сервер, A2A-сервер, Skills, Memory, Cloud Agents, Resilience, Compression и т. д.) см. в соответствующих файлах в этом каталоге docs/.

Этот файл описывает текущее содержимое репозитория, чтобы новый инженер мог ориентироваться в его структуре, понимать уровни среды выполнения и знать, куда добавлять код, не создавая новые модули без необходимости.

---

1. Технологический стек

Аспект	Выбор
Веб-фреймворк	Next.js 16 (App Router, автономный вывод, без глобального промежуточного ПО)
Язык	TypeScript 6.0+ — цель ES2022, module: esnext, moduleResolution: bundler, strict: false
Среда выполнения	Node.js >=22.22.2 <23 или >=24.0.0 <27 (ограничение применяется через engines + SUPPORTED_NODE_RANGE)
База данных	SQLite через better-sqlite3 (одиночный экземпляр, журналирование WAL)
Настольное приложение	Electron 41 + electron-builder 26.10 (отдельное рабочее пространство в electron/)
Тесты	Встроенный исполнитель тестов Node (модульные/интеграционные), Vitest (MCP, autoCombo, кеш), Playwright (e2e + protocols-e2e)
Сборка	Автономная сборка Next.js через scripts/build/build-next-isolated.mjs
Линтинг/форматирование	Плоская конфигурация ESLint + Prettier (lint-staged через предкоммитный хук Husky)
Система модулей	Везде ESM ("type": "module")
Рабочие пространства	Рабочее пространство npm — open-sse является единственным вложенным рабочим пространством

Псевдонимы путей (tsconfig.json):

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

HTTP-порт по умолчанию: 20128 (API и панель управления используют один процесс). Каталог данных задаётся переменной окружения DATA_DIR; значение по умолчанию — ~/.omniroute/.

---

2. Структура репозитория

OmniRoute/
├── src/                  Приложение Next.js (App Router, библиотеки, предметная область, сервер, общий код)
├── open-sse/             Рабочее пространство потокового движка (@omniroute/open-sse)
├── electron/             Обёртка настольного приложения (основной процесс Electron 41 + предварительная загрузка)
├── bin/                  Точки входа CLI (omniroute, reset-password)
├── tests/                Модульные, интеграционные, e2e, protocols-e2e, переводческие тесты, тесты безопасности, фикстуры
├── scripts/              Вспомогательные скрипты для сборки, синхронизации, проверок, миграций и среды выполнения
├── docs/                 Общедоступная документация (этот каталог)
├── public/               Статические ресурсы, манифест PWA, сервис-воркер
├── config/               Примеры конфигурации среды выполнения
├── images/               Маркетинговые материалы и снимки экрана
├── _ideia/, _references/, _mono_repo/, _tasks/   Внутренние черновики / планирование (не входят в поставку)
├── CLAUDE.md             Правила репозитория для Claude Code
├── AGENTS.md             Более подробное архитектурное руководство для агентов
├── package.json          v3.8.51, корень рабочего пространства
└── tsconfig.json         Псевдонимы путей + основные параметры компилятора

---

3. src/ — приложение Next.js

src/
├── app/                  Страницы App Router + маршруты API
├── lib/                  Основные библиотеки (БД, аутентификация, OAuth, навыки, память, …)
├── domain/               Чистый доменный слой (политики, резервирование, стоимость, блокировка, …)
├── server/               Только серверные модули (авторизация, CORS, аутентификация)
├── shared/               Типы, константы, валидация, контракты, утилиты (безопасны на границах)
├── mitm/                 Вспомогательные средства прокси-посредника для интеграции с CLI
├── models/               Метаданные и псевдонимы локальных моделей
├── sse/                  Устаревшие обработчики SSE, которые всё ещё находятся в src/ (не в open-sse/)
├── store/                Клиентские хранилища состояния
├── middleware/           Утилиты промежуточного ПО уровня маршрутов (не глобальное middleware Next.js)
├── scripts/              Внутрипроектные скрипты, импортируемые кодом приложения
├── types/                Глобальные и общие типы TS
├── i18n/                 Пакеты локализаций
├── instrumentation.ts    Хук инструментирования Next.js
├── instrumentation-node.ts
└── proxy.ts              Вспомогательный модуль верхнего уровня для инициализации прокси

3.1 src/app/ — App Router

App Router предоставляет как пользовательский интерфейс панели управления, так и публичный/административный HTTP API. Глобального middleware нет — перехват выполняется отдельно для каждого маршрута.

Сегменты верхнего уровня в src/app/:

Путь	Назначение
api/	Все маршруты HTTP API (см. структуру ниже)
a2a/	Конечная точка A2A JSON-RPC 2.0 (POST /a2a)
.well-known/agent.json/	Документ обнаружения Agent Card для A2A
(dashboard)/	Интерфейс панели управления (группа маршрутов, без префикса URL)
auth/, login/, forgot-password/, callback/	Потоки аутентификации
landing/	Маркетинговая/посадочная страница
docs/	Встроенный просмотрщик документации API
status/, maintenance/, offline/	Служебные страницы
privacy/, terms/	Юридические страницы
400/, 401/, 403/, 408/, 429/, 500/, 502/, 503/	Статические страницы ошибок
error.tsx, global-error.tsx, not-found.tsx, forbidden/, loading.tsx	Границы ошибок/загрузки фреймворка
layout.tsx, page.tsx, globals.css, manifest.ts	Корневая оболочка

3.1.1 src/app/(dashboard)/dashboard/ — страницы интерфейса

agents, analytics, api-manager, audit, auto-combo, batch, cache, changelog, cli-tools, cloud-agents, combos, compression, context, costs, endpoint, health, limits, logs, memory, onboarding, playground, providers, search-tools, settings, skills, system, translator, usage, webhooks, а также корневые page.tsx, HomePageClient.tsx, BootstrapBanner.tsx.

3.1.2 src/app/api/ — группы API верхнего уровня

src/app/api/
├── a2a/{status, tasks}
├── acp/
├── admin/
├── analytics/
├── assess/
├── auth/
├── batches/
├── cache/
├── cli-tools/
├── cloud/{codex-responses-ws}
├── combos/
├── compliance/
├── compression/
├── context/
├── db/, db-backups/
├── evals/
├── fallback/
├── files/
├── health/
├── init/
├── internal/{concurrency}
├── keys/
├── logs/
├── mcp/{audit, sse, status, stream, tools}
├── memory/{health, [id]/, route.ts}
├── model-combo-mappings/
├── models/
├── monitoring/
├── oauth/
├── openapi/
├── policies/
├── pricing/
├── provider-metrics/, provider-models/, provider-nodes/
├── providers/
├── rate-limit/, rate-limits/
├── resilience/
├── restart/, shutdown/
├── search/
├── sessions/
├── settings/
├── skills/{executions, [id], install, marketplace, route.ts, skillssh}
├── storage/
├── sync/, synced-available-models/
├── system/
├── tags/
├── telemetry/
├── token-health/
├── translator/
├── tunnels/
├── services/   Управление встроенными сервисами (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         Публичный API, совместимый с OpenAI
├── v1beta/     Совместимость в стиле Gemini
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — управление встроенными сервисами

Маршруты для установки, запуска, остановки и мониторинга 9Router и CLIProxyAPI. Все пути классифицируются как LOCAL_ONLY (только loopback, жёсткое правило #17), поскольку они могут выполнять npm install и порождать дочерние процессы.

src/app/api/services/
├── 9router/
│   ├── _lib.ts             вспомогательная функция getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install через execFile
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — npm install более новой версии
│   ├── rotate-key/route.ts POST — генерация нового API-ключа + перезапуск
│   ├── status/route.ts     GET  — текущее состояние + состояние БД + метаданные версии
│   └── auto-start/route.ts POST — переключение флага auto_start
├── cliproxy/
│   ├── _lib.ts             вспомогательная функция getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — npm install более новой версии
│   ├── status/route.ts     GET  — текущее состояние + состояние БД + метаданные версии
│   └── auto-start/route.ts POST — переключение флага auto_start
└── [name]/
    └── logs/route.ts       GET  — поток журналов через SSE (общий для всех сервисов)

Соответствующий пользовательский интерфейс панели мониторинга: src/app/(dashboard)/dashboard/providers/services/ — страница с двумя вкладками (CLIProxyAPI + 9Router). Обратный прокси для встроенного пользовательского интерфейса 9Router: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

Подробное описание: docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — OpenAI-совместимый публичный API

v1/
├── accounts/[id]/                       поиск учётной записи
├── agents/tasks/[id]/, agents/tasks/    конечные точки задач в стиле A2A
├── api/                                 внутренние вспомогательные API, доступные через v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    Chat Completions (основная конечная точка)
├── completions/                         устаревшие текстовые дополнения
├── embeddings/                          векторные представления
├── files/[id]/, files/                  Files API
├── _helpers/                            общие вспомогательные средства маршрутов (без публичного URL)
├── images/{edits, generations}/         генерация + редактирование изображений
├── issues/                              вспомогательные конечные точки сортировки проблем
├── management/{proxies}/                маршруты управления внутри v1
├── messages/{count_tokens}/             совместимость с сообщениями в стиле Anthropic
├── models/                              список моделей (`route.ts`, `catalog.ts`)
├── moderations/                         модерация
├── music/                               генерация музыки
├── providers/[provider]/                операции для отдельных провайдеров
├── quotas/{check}                       проверки квот
├── registered-keys/                     администрирование зарегистрированных ключей
├── rerank/                              повторное ранжирование
├── responses/[...path]/                 OpenAI Responses API (универсальный маршрут)
├── search/                              веб-поиск
├── videos/                              генерация видео
├── ws/                                  мост WebSocket
└── route.ts                             обработчик индекса

Каждый файл маршрута следует одному и тому же шаблону:

Маршрут → предварительный запрос CORS → валидация тела с помощью Zod → необязательная аутентификация
        → применение политик API-ключей → делегирование обработчику (open-sse)

v1beta/ — это поверхность совместимости в стиле Gemini (тонкая обёртка, преобразующая запросы для того же конвейера open-sse/handlers/).

3.2 src/lib/ — Основные библиотеки

Всегда импортируйте данные, синхронизацию, OAuth, навыки, память и т. д. через эти модули. В таблице сгруппированы фактические каталоги и важные файлы верхнего уровня.

Модуль	Назначение
a2a/	Сервер протокола A2A: taskManager.ts, streaming.ts, taskExecution.ts, routingLogger.ts, skills/ (6 навыков: анализ затрат, отчёт о состоянии, обнаружение провайдеров, управление квотами, интеллектуальная маршрутизация, список возможностей)
acp/	Agent-Control-Protocol: index.ts, manager.ts, registry.ts
api/	Вспомогательные средства внутреннего API: requireManagementAuth.ts, requireCliToolsAuth.ts, errorResponse.ts
auth/	managementPassword.ts (сброс пароля / хеширование)
batches/	Сервис OpenAI Batches API (service.ts)
catalog/	Синхронизация каталога OpenRouter (openrouterCatalog.ts)
cloudAgent/	Реестр облачных агентов: api.ts, baseAgent.ts, db.ts, index.ts, registry.ts, types.ts, agents/{codex, devin, jules}.ts
combos/	Вспомогательные средства разрешения комбинаций
compliance/	Аудит и аудит провайдеров: index.ts, providerAudit.ts
config/	Связующий код конфигурации среды выполнения
db/	Доменные модули SQLite (см. §3.2.1)
display/	Вспомогательные средства пользовательского интерфейса и отображения, используемые в ответах API
embeddings/	Реестр сервисов эмбеддингов
env/	Загрузка и инспектирование окружения
evals/	Среда выполнения оценок
guardrails/	piiMasker.ts, promptInjection.ts, visionBridge.ts, visionBridgeHelpers.ts, registry.ts, base.ts
jobs/	Фоновые задания (autoUpdate.ts, …)
memory/	Постоянная память: store.ts, cache.ts, retrieval.ts, summarization.ts, extraction.ts, injection.ts, qdrant.ts, settings.ts, verify.ts, schemas.ts, types.ts
monitoring/	observability.ts
oauth/	Модули OAuth/импорта провайдеров (22): agy, antigravity, claude, cline, codebuddy-cn, codex, cursor, devin-desktop, ghe-copilot, github, gitlab-duo, grok-cli-oauth, grok-cli, kilocode, kimi-coding, kiro, openference, qoder, trae, xai-oauth, zed-hosted, zed, а также services/, utils/ и constants/oauth.ts
plugins/	Загрузчик плагинов (index.ts)
promptCache/	prefixAnalyzer.ts, index.ts
providerModels/	Управление жизненным циклом моделей: modelDiscovery.ts, managedModelImport.ts, managedAvailableModels.ts, cursorAgent.ts
providers/	Вспомогательные средства провайдеров: catalog.ts, validation.ts, imageValidation.ts, claudeExtraUsage.ts, codexConnectionDefaults.ts, codexFastTier.ts, webCookieAuth.ts, managedAvailableModels.ts, requestDefaults.ts
resilience/	settings.ts — настройки автоматического выключателя, периода ожидания и блокировки
runtime/	Обнаружение возможностей среды выполнения
search/	executeWebSearch.ts
services/	Фреймворк встроенных сервисов: ServiceSupervisor.ts (универсальный супервизор дочерних процессов с блокировкой операций, кольцевым буфером и проверкой состояния), bootstrap.ts (регистрация на уровне процесса и автоматический запуск), registry.ts (сопоставление «инструмент → супервизор»), apiKey.ts (хранилище ключей AES-256-GCM), modelSync.ts (периодическая синхронизация моделей), ringBuffer.ts (кольцевой буфер журналов объёмом 5 МБ), healthCheck.ts (HTTP-проверка состояния), types.ts, embedWsProxy.ts (прокси WebSocket), installers/{ninerouter,cliproxy}.ts. См. docs/frameworks/EMBEDDED-SERVICES.md
agentSkills/	Каталог и генератор навыков агентов: catalog.ts (getCatalog/getSkillById/filterCatalog/computeCoverage), generator.ts (generateAgentSkills → записывает skills/{id}/SKILL.md), openapiParser.ts (извлекает конечные точки REST из спецификации OpenAPI), cliRegistryParser.ts (извлекает подкоманды CLI из bin/cli-registry), schemas.ts (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), types.ts (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Используется маршрутами REST (/api/agent-skills/*), инструментами MCP (omniroute_agent_skills_*) и навыком A2A list-capabilities. См. AGENT-SKILLS.md.
skills/	Фреймворк навыков: registry.ts, executor.ts, interception.ts, injection.ts, sandbox.ts, custom.ts, hybrid.ts, builtins.ts, a2a.ts, providerSettings.ts, schemas.ts, skillssh.ts, types.ts, а также builtin/browser.ts
spend/	batchWriter.ts (буфер отложенной записи)
sync/	bundle.ts, tokens.ts (облачная синхронизация)
system/	Вспомогательные средства системного уровня
translator/	Связующий код переводчика верхнего уровня (делегирует работу в open-sse/translator/)
usage/	Учёт использования: costCalculator.ts, tokenAccounting.ts, usageHistory.ts, aggregateHistory.ts, usageStats.ts, callLogs.ts, callLogArtifacts.ts, fetcher.ts, providerLimits.ts, migrations.ts
versionManager/	Автоматическое обновление и манифест версий
ws/	Мост WebSocket
zed-oauth/	Процесс OAuth для редактора Zed

Файлы верхнего уровня в src/lib/:

• Старый баррель-файл localDb.ts был удалён — потребители импортируют конкретные модули src/lib/db/* напрямую.
• proxyHealth.ts, proxyLogger.ts, tokenHealthCheck.ts, localHealthCheck.ts
• apiBridgeServer.ts, cacheLayer.ts, semanticCache.ts, settingsCache.ts
• cloudSync.ts, initCloudSync.ts
• cloudflaredTunnel.ts, ngrokTunnel.ts, tailscaleTunnel.ts
• consoleInterceptor.ts, container.ts, gracefulShutdown.ts, idempotencyLayer.ts
• ipUtils.ts, logEnv.ts, logPayloads.ts, logRotation.ts
• modelAliasSeed.ts, modelCapabilities.ts, modelMetadataRegistry.ts, modelsDevSync.ts
• piiSanitizer.ts, pricingSync.ts
• apiKeyExposure.ts, cacheControlSettings.ts, dataPaths.ts, toolPolicy.ts
• translatorEvents.ts, usageDb.ts, usageAnalytics.ts, webhookDispatcher.ts

3.2.1 src/lib/db/

Синглтон базы данных SQLite (getDbInstance() в core.ts, журналирование WAL). Никогда не пишите необработанный SQL в маршрутах или обработчиках — используйте эти модули.

Источник: diagrams/db-schema-overview.mmd

Доменные модули (каждый отвечает за одну или несколько таблиц): apiKeys.ts, backup.ts, batches.ts, cleanup.ts, cliToolState.ts, combos.ts, commandCodeAuth.ts, compression.ts, compressionAnalytics.ts, compressionCacheStats.ts, compressionCombos.ts, compressionScheduler.ts, contextHandoffs.ts, core.ts, creditBalance.ts, databaseSettings.ts, detailedLogs.ts, domainState.ts, encryption.ts, evals.ts, files.ts, healthCheck.ts, jsonMigration.ts, migrationRunner.ts, modelComboMappings.ts, models.ts, oneproxy.ts, prompts.ts, providers.ts, providerLimits.ts, proxies.ts, quotaSnapshots.ts, readCache.ts, reasoningCache.ts, registeredKeys.ts, secrets.ts, sessionAccountAffinity.ts, settings.ts, stateReset.ts, stats.ts, syncTokens.ts, tierConfig.ts, upstreamProxy.ts, versionManager.ts, webhooks.ts.

Каталог migrations/ содержит 168 версионированных файлов .sql (идемпотентных и транзакционных), которые выполняются модулем migrationRunner.ts при запуске.

Таблицы, создаваемые всеми миграциями (всего 123):

a, account_key_limits, api_keys, batches, call_logs, combo_adaptation_state, combos, command_code_auth_sessions, compression_analytics, compression_cache_stats, compression_combo_assignments, compression_combos, context_handoffs, daily_usage_summary, db_meta, domain_budgets, domain_circuit_breakers, domain_cost_history, domain_fallback_chains, domain_lockout_state, eval_cases, eval_runs, eval_suites, files, hourly_usage_summary, key_value, mcp_tool_audit, memories, model_combo_mappings, provider_connections, provider_key_limits, provider_nodes, proxy_assignments, proxy_logs, proxy_registry, quota_snapshots, reasoning_cache, registered_keys, request_detail_logs, routing_decisions, semantic_cache, session_account_affinity, skill_executions, skills, sync_tokens, tier_assignments, tier_config, upstream_proxy_config, usage_history, version_manager, webhooks (а также виртуальные таблицы FTS5 для поиска по памяти).

3.3 src/domain/ — Доменный слой

Чистая бизнес-логика без операций ввода-вывода. Импортируется маршрутами и обработчиками.

Файл	Назначение
policyEngine.ts	Высокоуровневый механизм разрешения политик
fallbackPolicy.ts	Дерево принятия решений о резервном варианте
costRules.ts	Правила расчёта стоимости
lockoutPolicy.ts	Решения о блокировке модели
tagRouter.ts	Маршрутизация на основе тегов
comboResolver.ts	Разрешение комбинации из запроса → список целей
connectionModelRules.ts	Фильтры моделей для каждого подключения
modelAvailability.ts	Проверка доступности модели
degradation.ts	Переходы в режим пониженной функциональности
providerExpiration.ts	Обнаружение аккаунтов/ключей с истёкшим сроком действия
quotaCache.ts	Кешированные решения о квотах
responses.ts, omnirouteResponseMeta.ts	Вспомогательные функции для структуры ответа
configAudit.ts	Аудит изменений конфигурации
assessment/	Оценка модели (согласно RFC, реализована частично)
types.ts	Общие доменные типы

3.4 src/server/ — Только для сервера

Не может импортироваться из клиентских компонентов.

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Классифицирует маршруты как общедоступные или административные
│   ├── assertAuth.ts      Вспомогательная функция проверки
│   ├── context.ts         Контекст авторизации для каждого запроса
│   ├── headers.ts
│   ├── pipeline.ts        Конвейер авторизации
│   ├── policies/          Конкретные политики
│   └── types.ts
└── cors/origins.ts        Список разрешённых источников CORS

3.5 src/shared/ — Безопасно для совместного использования

Разделён на специализированные подкаталоги:

• constants/ — providers.ts (каталог провайдеров, валидируемый с помощью Zod), models.ts, modelSpecs.ts, modelCompat.ts, pricing.ts, cliTools.ts, cliCompatProviders.ts, routingStrategies.ts, comboConfigMode.ts, headers.ts, upstreamHeaders.ts (список запретов), mcpScopes.ts, errorCodes.ts, publicApiRoutes.ts, batch.ts, batchEndpoints.ts, bodySize.ts, colors.ts, appConfig.ts, config.ts, sidebarVisibility.ts, visionBridgeDefaults.ts.
• validation/ — schemas.ts (~80 схем Zod), compressionConfigSchemas.ts, providerSchema.ts, settingsSchemas.ts, helpers.ts.
• contracts/ — контракты публичного API, публикуемые в npm.
• types/ — общие типы TS.
• utils/ — circuitBreaker.ts, apiAuth.ts, apiKey.ts, apiKeyPolicy.ts, api.ts, classify429.ts, cliCompat.ts, clipboard.ts, cloud.ts, cn.ts, cors.ts, featureFlags.ts, fetchTimeout.ts, formatting.ts, inputSanitizer.ts, logger.ts, machine.ts, machineId.ts, maskEmail.ts, modelCatalogSearch.ts, nodeRuntimeSupport.ts, parseApiKeys.ts, providerHints.ts, providerModelAliases.ts, rateLimiter.ts, releaseNotes.ts, a11yAudit.ts, а также хуки и компоненты панели управления в services/, network/, middleware/, schemas/, hooks/, components/.

---

4. open-sse/ — Рабочее пространство движка потоковой передачи

Отдельное рабочее пространство npm, публикуемое как @omniroute/open-sse. Отвечает за обработку запросов, исполнители, трансляторы, сервисы, преобразователь и сервер MCP.

open-sse/
├── index.ts                Публичные экспорты
├── package.json            Манифест рабочего пространства
├── tsconfig.json
├── types.d.ts
├── config/                 Реестры провайдеров, профили заголовков, идентификация, …
├── handlers/               Обработчики запросов (чат, эмбеддинги, аудио, изображения, …)
├── executors/              108 HTTP-исполнителей для конкретных провайдеров
├── translator/             Преобразование форматов (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Преобразователь потоков Responses API ↔ Chat Completions
├── services/               Более 80 сервисных модулей (комбинации, резервирование, квоты, идентификация, …)
├── utils/                  Вспомогательные средства для потоковой передачи, TLS-клиент, AWS SigV4, проксирование fetch, …
└── mcp-server/             Сервер MCP (3 транспорта, 33 области доступа, 110 инструментов)

4.1 open-sse/handlers/

Обработчик	Назначение
chatCore.ts	Основной конвейер чата (кэш, ограничение частоты, маршрутизация комбинаций, диспетчеризация исполнителей)
responsesHandler.ts	Точка входа OpenAI Responses API
embeddings.ts	Эмбеддинги
imageGeneration.ts	Генерация изображений
audioSpeech.ts	Преобразование текста в речь
audioTranscription.ts	Преобразование речи в текст
videoGeneration.ts	Генерация видео
musicGeneration.ts	Генерация музыки
rerank.ts	Повторное ранжирование
moderations.ts	Модерация
search.ts	Веб-поиск
sseParser.ts	Парсер событий SSE
usageExtractor.ts	Извлечение количества токенов из вышестоящих потоков
responseSanitizer.ts	Удаление специфичного для провайдера шума
responseTranslator.ts	Связующий слой между ответом провайдера и слоем трансляции

4.2 open-sse/executors/

108 исполнителей провайдеров, каждый из которых расширяет BaseExecutor (base.ts):

antigravity, azure-openai, blackbox-web, cliproxyapi, chatgpt-web-codex, cloudflare-ai, codex, commandCode, cursor, default, devin-cli, muse-spark-web, nlpcloud, opencode, perplexity-web, petals, pollinations, qoder, vertex, devin-desktop, а также claudeIdentity.ts (общий вспомогательный модуль идентификации) и index.ts (реестр).

Примечание: провайдеры, не перечисленные здесь, обслуживаются default.ts с помощью универсального исполнителя, совместимого с OpenAI. Полный каталог провайдеров (355 провайдеров) находится в src/shared/constants/providers.ts.

4.3 open-sse/translator/

Трансляция по схеме «центр и лучи» (OpenAI выступает центром).

• 9 трансляторов запросов (translator/request/): antigravity-to-openai, claude-to-gemini, claude-to-openai, gemini-to-openai, openai-responses, openai-to-claude, openai-to-cursor, openai-to-gemini, openai-to-kiro.
• 9 трансляторов ответов (translator/response/): claude-to-openai, cursor-to-openai, gemini-to-claude, gemini-to-openai, kiro-to-openai, openai-responses, openai-to-antigravity, openai-to-claude.
• 9 вспомогательных модулей (translator/helpers/): claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper, а также тесты вспомогательных модулей.
• Вспомогательные средства для изображений (translator/image/sizeMapper.ts).
• Верхний уровень: bootstrap.ts, formats.ts, registry.ts, index.ts.

4.4 open-sse/transformer/

• responsesTransformer.ts — преобразователь Responses API ↔ Chat Completions на основе TransformStream (используется универсальным маршрутом responses/).

4.5 open-sse/services/

Основные модули (полный список находится в open-sse/services/):

Аспект	Файлы
Маршрутизация Combo	combo.ts (19 стратегий), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
Движок Auto Combo	autoCombo/ — engine.ts, scoring.ts, taskFitness.ts, virtualFactory.ts, modePacks.ts, autoPrefix.ts, persistence.ts, providerDiversity.ts, providerRegistryAccessor.ts, routerStrategy.ts, selfHealing.ts, index.ts
Отказоустойчивость	accountFallback.ts (период ожидания + блокировка), errorClassifier.ts, requestRejectedStreak.ts, emergencyFallback.ts, rateLimitManager.ts, rateLimitSemaphore.ts, accountSemaphore.ts, accountSelector.ts
Квоты	quotaMonitor.ts, quotaPreflight.ts, bailianQuotaFetcher.ts, codexQuotaFetcher.ts, deepseekQuotaFetcher.ts, openrouterQuotaFetcher.ts, openrouterFreeWindow.ts, crofUsageFetcher.ts, antigravityCredits.ts
Кэширование	reasoningCache.ts, searchCache.ts, signatureCache.ts, requestDedup.ts
Интеллектуальная маршрутизация	intentClassifier.ts, taskAwareRouter.ts, backgroundTaskDetector.ts, volumeDetector.ts, wildcardRouter.ts, workflowFSM.ts, specificityDetector.ts, specificityRules.ts, specificityTypes.ts
Обработка моделей	modelCapabilities.ts, modelDeprecation.ts, modelFamilyFallback.ts, modelStrip.ts, model.ts, provider.ts, providerRequestDefaults.ts, providerCostData.ts, payloadRules.ts
Сжатие	compression/ — полная интеграция движка сжатия
Токены и сеансы	tokenRefresh.ts, sessionManager.ts, apiKeyRotator.ts, contextManager.ts, contextHandoff.ts, systemPrompt.ts, roleNormalizer.ts, responsesInputSanitizer.ts, toolSchemaSanitizer.ts, toolLimitDetector.ts, thinkingBudget.ts
Уровни / манифест	tierResolver.ts, tierConfig.ts, tierDefaults.json, tierTypes.ts, manifestAdapter.ts
IP / сеть	ipFilter.ts, webSearchFallback.ts
Пакетная обработка	batchProcessor.ts
Использование	usage.ts

4.6 open-sse/mcp-server/

• 110 уникальных инструментов, подключённых в server.ts (45 канонических в schemas/tools.ts + модули памяти, навыков, GitHub-навыков, пула, геймификации, плагинов, Notion, Obsidian, локального корпуса и сжатия — объединение подсчитывается функцией countUniqueMcpTools).
• 3 транспорта: stdio, HTTP Streamable, SSE.
• 33 области доступа, применяемые во время выполнения, — базовый список находится в src/shared/constants/mcpScopes.ts, а полный набор представляет собой объединение областей доступа, объявленных каждым модулем инструментов.
• Таблица аудита: mcp_tool_audit (заполняется модулем audit.ts).
• Файлы: server.ts, index.ts, httpTransport.ts, audit.ts, scopeEnforcement.ts, runtimeHeartbeat.ts, descriptionCompressor.ts, schemas/{tools, a2a, audit, index}.ts, tools/{advancedTools, compressionTools, memoryTools, skillTools}.ts, а также тесты в __tests__/.
• Полный каталог инструментов см. в MCP-SERVER.md.

4.7 open-sse/config/

Реестры провайдеров (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), реестры моделей по форматам (audioRegistry.ts, embeddingRegistry.ts, imageRegistry.ts, moderationRegistry.ts, musicRegistry.ts, rerankRegistry.ts, searchRegistry.ts, videoRegistry.ts), вспомогательные средства идентификации (codexIdentity.ts, codexInstructions.ts, anthropicHeaders.ts, antigravityUpstream.ts, antigravityModelAliases.ts, cliFingerprints.ts, toolCloaking.ts, defaultThinkingSignature.ts), вспомогательные средства для учётных данных (credentialLoader.ts, codexClient.ts) и облачные адаптеры (azureAi.ts, bedrock.ts, datarobot.ts, glmProvider.ts, maritalk.ts, oci.ts, petals.ts, runway.ts, sap.ts, watsonx.ts, ollamaModels.ts, errorConfig.ts, constants.ts, registryUtils.ts).

4.8 open-sse/utils/

Примитивы потоковой передачи и вспомогательные средства провайдеров: stream.ts, streamHandler.ts, streamHelpers.ts, streamPayloadCollector.ts, streamReadiness.ts, sseHeartbeat.ts, proxyFetch.ts, proxyDispatcher.ts, tlsClient.ts, networkProxy.ts, awsSigV4.ts, cacheControlPolicy.ts, cursorChecksum.ts, cursorAgentProtobuf.ts, cursorVersionDetector.ts, comfyuiClient.ts, kieTask.ts, bypassHandler.ts, aiSdkCompat.ts, thinkTagParser.ts, urlSanitize.ts, usageTracking.ts, requestLogger.ts, progressTracker.ts, cors.ts, error.ts, logger.ts, sleep.ts, ollamaTransform.ts.

---

5. electron/ — Обёртка для настольных систем

electron/
├── main.js                  Основной процесс Electron
├── preload.js               Мост предварительной загрузки (contextIsolation включён)
├── types.d.ts
├── package.json             Конфигурация electron-builder, версия 3.8.51
├── README.md
├── assets/                  Ресурсы сборки (значки, разрешения, …)
├── node_modules/            Выделенный каталог node_modules (better-sqlite3, electron-updater)
└── dist-electron/           Результаты сборки (не включены в репозиторий)

Пять npm-скриптов в корне рабочего пространства: electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged. Автоматическое обновление выполняется через electron-updater, настроенный на ленту релизов GitHub.

---

6. bin/ — CLI

bin/
├── omniroute.mjs           Основная точка входа CLI (Node ESM)
├── reset-password.mjs      Сброс пароля управления через CLI
├── mcp-server.mjs          Средство запуска сервера MCP (stdio)
├── nodeRuntimeSupport.mjs  Проверка версии Node
└── cli/
    ├── program.mjs         Построитель программы Commander
    ├── runtime.mjs         Вспомогательная функция withRuntime (сначала сервер, при недоступности — БД)
    ├── output.mjs          Форматтеры вывода (json/jsonl/table/csv)
    ├── i18n.mjs            Вспомогательная функция t() с локалями
    ├── api.mjs             Вспомогательная функция для запросов API
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Регистрация команд
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (по одному файлу на команду/группу)

В package.json → bin представлены два исполняемых файла:

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

---

7. tests/

Каталог	Тип
tests/unit/	Модульные тесты через встроенный тестовый раннер Node (1821 файл, а также подкаталоги api/, auth/, authz/)
tests/integration/	Межмодульные тесты и тесты состояния БД
tests/e2e/	UI-тесты Playwright
tests/e2e/protocol-clients.test.ts	Сквозные тесты протоколов MCP/A2A
tests/translator/	Тесты, относящиеся к транслятору
tests/security/	Регрессионные тесты безопасности
tests/load/	Нагрузочные тесты / стресс-тесты
tests/golden-set/	Эталонные результаты для регрессионных тестов транслятора
tests/helpers/, tests/fixtures/, tests/manual/	Вспомогательные материалы

Основные команды:

Команда	Что запускается
npm run test:unit	Все tests/unit/*.test.ts через тестовый раннер Node (параллельность 10)
npm run test:vitest	Набор тестов Vitest (MCP, autoCombo, кэш)
npm run test:e2e	Набор UI-тестов Playwright
npm run test:protocols:e2e	Сквозные тесты протоколов MCP + A2A
npm run test:coverage	Порог покрытия (≥60% строк/инструкций/функций/ветвей)
node --import tsx/esm --test tests/unit/<file>.test.ts	Запуск одного файла

---

8. scripts/

Организовано в 6 подпапок по назначению.

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

---

9. Конвейер обработки запросов (краткий обзор)

Источник: diagrams/request-pipeline.mmd

Запрос клиента
  → /v1/chat/completions (route.ts)
     Предварительная проверка CORS
     Валидация Zod (chatCompletionsSchema в shared/validation/schemas.ts)
     Аутентификация (extractApiKey + isValidApiKey ИЛИ requireManagementAuth)
     Механизм политик (src/server/authz/pipeline.ts)
     Защитные механизмы (маскирование PII, защита от внедрения промптов, мост для обработки изображений)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Проверка кеша (семантический кеш + кеш чтения)
     Ограничение частоты запросов (rateLimitManager, accountSemaphore)
     Комбинированная маршрутизация (если модель разрешается в комбинацию)
       comboResolver → цикл по каждой целевой модели → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       запрос к вышестоящему сервису → повторные попытки/экспоненциальная задержка через accountFallback
     translateResponse() (open-sse/translator/response/*)
     Поток SSE ИЛИ ответ JSON
     Для Responses API: TransformStream через open-sse/transformer/responsesTransformer.ts
  → Аудит соответствия требованиям (src/lib/compliance/)
  → Ответ клиенту

Состояние механизмов отказоустойчивости во время выполнения (три механизма)

Механизм	Область действия	Расположение
Автоматический выключатель провайдера	Весь провайдер	src/shared/utils/circuitBreaker.ts, сохраняется в domain_circuit_breakers
Период недоступности подключения	Одна учётная запись/ключ	markAccountUnavailable() в src/sse/services/auth.ts; используется accountFallback.checkFallbackError()
Блокировка модели	Провайдер + подключение + модель	open-sse/services/accountFallback.ts, сохраняется в domain_lockout_state

См. RESILIENCE_GUIDE.md и специальный раздел в CLAUDE.md.

---

10. Как внести вклад

Добавление нового провайдера

1. Зарегистрируйте его в src/shared/constants/providers.ts (валидация с помощью Zod при загрузке).
2. Добавьте исполнитель в open-sse/executors/, если требуется пользовательская логика (расширьте BaseExecutor).
3. Добавьте транслятор в open-sse/translator/, если провайдер не поддерживает формат OpenAI.
4. Если используется OAuth, добавьте конфигурацию в src/lib/oauth/providers/ и src/lib/oauth/services/.
5. Зарегистрируйте модели в open-sse/config/providerRegistry.ts (или в реестре соответствующего формата в open-sse/config/).
6. Напишите тесты в tests/unit/.

Добавление нового маршрута API

1. Создайте src/app/api/your-route/route.ts.
2. Следуйте шаблону: CORS → валидация тела с помощью Zod → аутентификация → делегирование обработчику.
3. Для новой структуры запроса добавьте схему Zod в src/shared/validation/schemas.ts.
4. Если маршрут предназначен только для управления, добавьте путь в src/shared/constants/publicApiRoutes.ts (список запретов для общедоступного API).
5. Добавьте тесты в tests/unit/.
6. Обновите docs/reference/API_REFERENCE.md и docs/openapi.yaml.

Добавление нового модуля БД

1. Создайте src/lib/db/yourModule.ts и импортируйте getDbInstance() из ./core.ts.
2. Экспортируйте CRUD-функции для своей предметной области.
3. При добавлении новых таблиц добавьте миграцию в src/lib/db/migrations/ с последовательным номером, идемпотентную и транзакционную.
4. Импортирующие модули должны использовать прямой импорт из @/lib/db/yourModule (без агрегирующего модуля — старый слой реэкспорта localDb.ts удалён).
5. Добавьте тесты в tests/unit/.

Добавление нового инструмента MCP

1. Добавьте определение инструмента в open-sse/mcp-server/tools/ (или расширьте open-sse/mcp-server/schemas/tools.ts).
2. Назначьте соответствующую область или области доступа в src/shared/constants/mcpScopes.ts.
3. Зарегистрируйте инструмент в open-sse/mcp-server/server.ts.
4. Добавьте тесты в open-sse/mcp-server/__tests__/.
5. Обновите MCP-SERVER.md.

Добавление нового навыка A2A

См. A2A-SERVER.md § Добавление нового навыка. Навыки находятся в src/lib/a2a/skills/ и регистрируются через диспетчер задач A2A.

---

11. Соглашения

• Стиль кода: отступ в 2 пробела, двойные кавычки, ширина 100 символов, точки с запятой, завершающие запятые в стиле es5 — обеспечивается Prettier через lint-staged.
• Импорты: внешние → внутренние (@/, @omniroute/open-sse) → относительные.
• Именование: файлы — camelCase или kebab-case, компоненты — PascalCase, константы — UPPER_SNAKE.
• ESLint: no-eval, no-implied-eval, no-new-func = error везде; no-explicit-any = warn в open-sse/ и tests/, в остальных местах — ошибка.
• TypeScript: strict: false (унаследованный подход). На границах между модулями предпочитайте явные типы выводу типов.
• База данных: никогда не пишите необработанный SQL в маршрутах или обработчиках — всегда используйте модули из src/lib/db/. Никогда не импортируйте через агрегирующий модуль — напрямую используйте конкретные модули src/lib/db/*.
• Типизация сущностей БД (#3512): функция, которая записывает или считывает форму строки таблицы БД, должна принимать или возвращать именованный интерфейс TS, отражающий столбцы этой таблицы в соотношении 1:1, а не any или встроенный анонимный тип в месте вызова. Размещайте интерфейс рядом с функцией (например, export interface UsageEntry в src/lib/usage/usageHistory.ts над saveRequestUsage), оставляйте отдельные поля необязательными или допускающими null, если разные функции записи заполняют строку постепенно, и предпочитайте unknown вместо any для поля, форма которого различается у разных вызывающих сторон (с пояснением в документации поля; например, UsageEntry.tokens принимает как необработанные данные об использовании в формате провайдера, так и нормализованную форму). Когда таким образом количество any в файле достигнет нуля, добавьте его в список разрешений check:any-budget:t11 (scripts/check/check-t11-any-budget.mjs, maxAny: 0), чтобы предотвратить регрессии. Это соглашение для первого этапа — более масштабное устранение анонимных any выполняется итеративно в остальной кодовой базе.
• Ошибки: используйте try/catch с конкретными типами ошибок, ведите журналирование с контекстом pino. Никогда не подавляйте ошибки без уведомления в потоках SSE; используйте сигналы прерывания для очистки.
• Безопасность: никогда не используйте eval() / new Function() / неявный eval. Проверяйте все входные данные с помощью Zod. Шифруйте учётные данные при хранении (AES-256-GCM). Поддерживайте список запретов src/shared/constants/upstreamHeaders.ts согласованным со слоем очистки и валидации.
• Коммиты: Conventional Commits — feat(scope): subject. Допустимые области: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.
• Ветки: префиксы feat/, fix/, refactor/, docs/, test/, chore/. Никогда не выполняйте коммиты напрямую в main.
• Husky: перед коммитом запускаются lint-staged + check:docs-sync + check:any-budget:t11; перед отправкой изменений запускаются check:any-budget:t11 + check:tracked-artifacts (быстрые проверки; test:unit исключён).

---

12. Жёсткие правила (из CLAUDE.md)

1. Никогда не добавляйте секреты или учётные данные в коммиты.
2. Никогда не используйте импорты через barrel-файлы — импортируйте напрямую из конкретных модулей src/lib/db/*.
3. Никогда не используйте eval() / new Function() / неявный eval.
4. Никогда не выполняйте коммиты непосредственно в main.
5. Никогда не пишите необработанный SQL в маршрутах — всегда используйте модули из src/lib/db/.
6. Никогда не подавляйте ошибки в SSE-потоках без уведомления.
7. Всегда проверяйте входные данные с помощью схем Zod.
8. При изменении производственного кода всегда добавляйте тесты.
9. Покрытие должно оставаться ≥ 60% (операторы, строки, функции, ветви).

---

13. См. также

• ARCHITECTURE.md — высокоуровневая архитектура и зоны ответственности модулей.
• API_REFERENCE.md — справочник по публичному API и API управления.
• FEATURES.md — матрица функций и ключевые изменения версий.
• RESILIENCE_GUIDE.md — подробное описание автоматического выключателя, периода восстановления и блокировки.
• AUTO-COMBO.md — оценка и стратегии Auto Combo.
• MCP-SERVER.md — полный каталог инструментов MCP и транспортов.
• A2A-SERVER.md — возможности и обнаружение протокола A2A.
• COMPRESSION_GUIDE.md — сжатие RTK и Caveman.
• CLI-TOOLS.md — интеграции CLI.
• ELECTRON_GUIDE.md (если имеется), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — целевые среды развёртывания.
• TROUBLESHOOTING.md — распространённые эксплуатационные проблемы.
• CONTRIBUTING.md — рабочий процесс участника проекта.
• CLAUDE.md — правила репозитория для Claude Code (основной источник многих приведённых выше соглашений).
• AGENTS.md — более подробный справочник по архитектуре для агентов.