OmniRoute/docs/i18n/ru/CLAUDE.md

# CLAUDE.md (Русский)

🌐 **Languages:** 🇺🇸 [English](../../../CLAUDE.md) · 🇸🇦 [ar](../ar/CLAUDE.md) · 🇦🇿 [az](../az/CLAUDE.md) · 🇧🇬 [bg](../bg/CLAUDE.md) · 🇧🇩 [bn](../bn/CLAUDE.md) · 🇨🇿 [cs](../cs/CLAUDE.md) · 🇩🇰 [da](../da/CLAUDE.md) · 🇩🇪 [de](../de/CLAUDE.md) · 🇪🇸 [es](../es/CLAUDE.md) · 🇮🇷 [fa](../fa/CLAUDE.md) · 🇫🇮 [fi](../fi/CLAUDE.md) · 🇫🇷 [fr](../fr/CLAUDE.md) · 🇮🇳 [gu](../gu/CLAUDE.md) · 🇮🇱 [he](../he/CLAUDE.md) · 🇮🇳 [hi](../hi/CLAUDE.md) · 🇭🇺 [hu](../hu/CLAUDE.md) · 🇮🇩 [id](../id/CLAUDE.md) · 🇮🇩 [in](../in/CLAUDE.md) · 🇮🇹 [it](../it/CLAUDE.md) · 🇯🇵 [ja](../ja/CLAUDE.md) · 🇰🇷 [ko](../ko/CLAUDE.md) · 🇮🇳 [mr](../mr/CLAUDE.md) · 🇲🇾 [ms](../ms/CLAUDE.md) · 🇳🇱 [nl](../nl/CLAUDE.md) · 🇳🇴 [no](../no/CLAUDE.md) · 🇵🇭 [phi](../phi/CLAUDE.md) · 🇵🇱 [pl](../pl/CLAUDE.md) · 🇵🇹 [pt](../pt/CLAUDE.md) · 🇧🇷 [pt-BR](../pt-BR/CLAUDE.md) · 🇷🇴 [ro](../ro/CLAUDE.md) · 🇸🇰 [sk](../sk/CLAUDE.md) · 🇸🇪 [sv](../sv/CLAUDE.md) · 🇰🇪 [sw](../sw/CLAUDE.md) · 🇮🇳 [ta](../ta/CLAUDE.md) · 🇮🇳 [te](../te/CLAUDE.md) · 🇹🇭 [th](../th/CLAUDE.md) · 🇹🇷 [tr](../tr/CLAUDE.md) · 🇺🇦 [uk-UA](../uk-UA/CLAUDE.md) · 🇵🇰 [ur](../ur/CLAUDE.md) · 🇻🇳 [vi](../vi/CLAUDE.md) · 🇨🇳 [zh-CN](../zh-CN/CLAUDE.md)

---

Этот файл предоставляет руководство для Claude Code (claude.ai/code) при работе с кодом в этом репозитории.

## Быстрый старт

```bash
npm install                    # Установка зависимостей (автоматически генерирует .env из .env.example)
npm run dev                    # Сервер разработки на http://localhost:20128
npm run build                  # Продакшн сборка (Next.js 16 standalone)
npm run lint                   # ESLint (ожидается 0 ошибок; предупреждения уже существуют)
npm run typecheck:core         # Проверка TypeScript (должна быть чистой)
npm run typecheck:noimplicit:core  # Строгая проверка (без неявного any)
npm run test:coverage          # Модульные тесты + контроль покрытия (75/75/75/70 — операторы/строки/функции/ветви)
npm run check                  # линт + тесты в одном
npm run check:cycles           # Обнаружение циклических зависимостей
```

### Запуск тестов

```bash
# Один файл теста (родной тестовый запускатель Node.js — большинство тестов)
node --import tsx/esm --test tests/unit/your-file.test.ts

# Vitest (MCP сервер, autoCombo, кэш)
npm run test:vitest

# Все наборы
npm run test:all
```

Для полной матрицы тестов смотрите `CONTRIBUTING.md` → "Запуск тестов". Для глубокой архитектуры смотрите `AGENTS.md`.

---

## Проект в общем

**OmniRoute** — унифицированный AI прокси/маршрутизатор. Один конечный пункт, более 160 поставщиков LLM, автоматическое резервирование.

| Уровень        | Местоположение          | Цель                                                                           |
| -------------- | ----------------------- | ------------------------------------------------------------------------------ |
| API маршруты   | `src/app/api/v1/`       | Next.js App Router — точки входа                                               |
| Обработчики    | `open-sse/handlers/`    | Обработка запросов (чат, встраивания и т.д.)                                   |
| Исполнители    | `open-sse/executors/`   | HTTP-диспетчер, специфичный для поставщика                                     |
| Переводчики    | `open-sse/translator/`  | Конверсия форматов (OpenAI↔Claude↔Gemini)                                      |
| Трансформер    | `open-sse/transformer/` | API ответов ↔ Завершения чата                                                  |
| Сервисы        | `open-sse/services/`    | Комбинированная маршрутизация, ограничения по скорости, кэширование и т.д.     |
| База данных    | `src/lib/db/`           | Модули домена SQLite (более 45 файлов, 55 миграций)                            |
| Домен/Политика | `src/domain/`           | Движок политик, правила затрат, логика резервирования                          |
| MCP сервер     | `open-sse/mcp-server/`  | 37 инструментов (30 базовых + 3 памяти + 4 навыка), 3 транспорта, ~13 областей |
| A2A сервер     | `src/lib/a2a/`          | Протокол агента JSON-RPC 2.0                                                   |
| Навыки         | `src/lib/skills/`       | Расширяемая структура навыков                                                  |
| Память         | `src/lib/memory/`       | Постоянная разговорная память                                                  |

Монорепозиторий: `src/` (приложение Next.js 16), `open-sse/` (рабочее пространство стримингового движка), `electron/` (десктопное приложение), `tests/`, `bin/` (точка входа CLI).

---

## Запросный Пайплайн

```
Клиент → /v1/chat/completions (маршрут Next.js)
  → CORS → валидация Zod → аутентификация? → проверка политики → защита от инъекций в запрос
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → проверка кэша → ограничение по частоте → комбинированная маршрутизация?
      → resolveComboTargets() → handleSingleModel() для каждой цели
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() вверх по потоку → повторная попытка с задержкой
    → перевод ответа → SSE поток или JSON
    → Если Responses API: responsesTransformer.ts TransformStream
```

API маршруты следуют последовательному шаблону: `Маршрут → предварительная проверка CORS → валидация тела Zod → необязательная аутентификация (extractApiKey/isValidApiKey) → соблюдение политики API ключа → делегирование обработчикам (open-sse)`. Нет глобального промежуточного ПО Next.js — перехват специфичен для маршрута.

**Комбинированная маршрутизация** (`open-sse/services/combo.ts`): 14 стратегий (приоритет, взвешенный, заполнение в первую очередь, круговая, P2C, случайный, наименее используемый, оптимизированный по стоимости, учитывающий сброс, строгий случайный, авто, lkgp, оптимизированный по контексту, контекстный реле). Каждая цель вызывает `handleSingleModel()`, который оборачивает `handleChatCore()` с обработкой ошибок для каждой цели и проверками автоматического отключения. См. `docs/routing/AUTO-COMBO.md` для 9-факторного оценивания Auto-Combo и `docs/architecture/RESILIENCE_GUIDE.md` для 3 слоев устойчивости.

---

## Состояние времени выполнения устойчивости

OmniRoute имеет три связанных, но различных механизма временных сбоев. Держите их
область применения отдельно при отладке поведения маршрутизации. См.
[диаграмму устойчивости в 3 слоя](./docs/diagrams/exported/resilience-3layers.svg)
(источник: [docs/diagrams/resilience-3layers.mmd](./docs/diagrams/resilience-3layers.mmd))
для быстрого обзора.

### Прерывание цепи поставщика

**Область применения**: весь поставщик, например, `glm`, `openai`, `anthropic`.

**Цель**: прекратить отправку трафика к поставщику, который постоянно терпит неудачу на
уровне upstream/service, чтобы один нездоровый поставщик не замедлял каждый запрос.

**Реализация**:

- Основной класс: `src/shared/utils/circuitBreaker.ts`
- Провода ворот/выполнения чата: `src/sse/handlers/chatHelpers.ts`, `src/sse/handlers/chat.ts`
- API состояния времени выполнения: `src/app/api/monitoring/health/route.ts`
- Общие обертки: `open-sse/services/accountFallback.ts`
- Таблица сохраненного состояния: `domain_circuit_breakers`

**Состояния**:

- `CLOSED`: нормальный трафик разрешен.
- `OPEN`: поставщик временно заблокирован; вызывающие получают ответ о том, что цепь поставщика открыта
  или комбинированная маршрутизация пропускает к другой цели.
- `HALF_OPEN`: время сброса истекло; разрешить пробный запрос. Успех закрывает
  прерывание, неудача снова открывает его.

**По умолчанию** (`open-sse/config/constants.ts`):

- OAuth поставщики: порог `3`, время сброса `60s`.
- Поставщики API-ключей: порог `5`, время сброса `30s`.
- Локальные поставщики: порог `2`, время сброса `15s`.

Только статусы сбоев на уровне поставщика должны срабатывать на прерывание цепи поставщика:

```ts
(408, 500, 502, 503, 504);
```

Не срабатывайте на прерывание всей цепи поставщика для нормальных ошибок аккаунта/ключа/модели, таких как большинство
`401`, `403` или `429`. Обычно они относятся к охлаждению соединения или блокировке модели. Общий ответ API-ключа `403` должен быть восстанавливаемым, если он не классифицируется как терминальная ошибка поставщика/аккаунта.

Прерывание использует ленивое восстановление, а не фоновый таймер. Когда `OPEN` истекает, такие
чтения, как `getStatus()`, `canExecute()`, и `getRetryAfterMs()` обновляют состояние на
`HALF_OPEN`, чтобы панели мониторинга и сборщики кандидатов на комбинирование не продолжали исключать
истекший поставщик навсегда.

### Охлаждение соединения

**Область применения**: одно соединение/аккаунт/ключ поставщика.

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

**Реализация**:

- Путь записи/обновления: `src/sse/services/auth.ts::markAccountUnavailable()`
- Выбор/фильтрация аккаунта: `src/sse/services/auth.ts::getProviderCredentials...`
- Расчет охлаждения: `open-sse/services/accountFallback.ts::checkFallbackError()`
- Настройки: `src/lib/resilience/settings.ts`

Важные поля на соединениях поставщика:

```ts
rateLimitedUntil;
testStatus: "unavailable";
lastError;
lastErrorType;
errorCode;
backoffLevel;
```

Во время выбора аккаунта соединение пропускается, пока:

```ts
new Date(rateLimitedUntil).getTime() > Date.now();
```

Охлаждения также ленивые: когда `rateLimitedUntil` в прошлом, соединение снова становится
доступным. При успешном использовании `clearAccountError()` очищает `testStatus`,
`rateLimitedUntil`, поля ошибок и `backoffLevel`.

Поведение охлаждения соединения по умолчанию:

- Базовое охлаждение OAuth: `5s`.
- Базовое охлаждение API-ключа: `3s`.
- API-ключ `429` должен предпочитать подсказки повторной попытки вверх по потоку (`Retry-After`, заголовки сброса или
  парсируемый текст сброса), когда это возможно.
- Повторяющиеся восстанавливаемые сбои используют экспоненциальное увеличение задержки:

```ts
baseCooldownMs * 2 ** failureIndex;
```

Защита от эффекта "громадного стада" предотвращает одновременные сбои на одном соединении от
повторного продления охлаждения или двойного увеличения `backoffLevel`.

Терминальные состояния не являются охлаждениями. `banned`, `expired`, и `credits_exhausted` должны оставаться недоступными до тех пор, пока учетные данные/настройки не изменятся или оператор не сбросит их. Не перезаписывайте терминальные состояния временным состоянием охлаждения.

### Блокировка модели

**Область применения**: поставщик + соединение + модель.

**Цель**: избежать отключения целого соединения, когда только одна модель недоступна или
ограничена по квоте для этого соединения.

Примеры:

- Поставщики с квотой на модель, возвращающие `429`.
- Локальные поставщики, возвращающие `404` для одной отсутствующей модели.
- Ошибки разрешения режима/модели, специфичные для поставщика, такие как выбранные режимы Grok.

Блокировка модели находится в `open-sse/services/accountFallback.ts` и позволяет тому же
соединению продолжать обслуживать другие модели.

### Рекомендации по отладке

- Если все ключи для поставщика пропущены, проверьте как состояние прерывания поставщика, так и `rateLimitedUntil`/`testStatus` каждого
  соединения.
- Если поставщик кажется постоянно исключенным после окна сброса, проверьте, читает ли код
  необработанное `state`, а не использует `getStatus()`/`canExecute()`.
- Если один ключ поставщика терпит неудачу, но другие должны работать, предпочтите охлаждение соединения перед
  прерыванием поставщика.
- Если только одна модель терпит неудачу, предпочтите блокировку модели перед охлаждением соединения.
- Если состояние должно восстанавливаться самостоятельно, оно должно иметь будущую метку времени/время сброса и
  путь чтения, который обновляет истекшее состояние. Постоянные статусы требуют ручных изменений учетных данных
  или конфигурации.

## Ключевые Конвенции

### Стиль Кода

- **2 пробела**, точки с запятой, двойные кавычки, ширина 100 символов, запятые в конце для es5 (обеспечивается lint-staged через Prettier)
- **Импорты**: внешние → внутренние (`@/`, `@omniroute/open-sse`) → относительные
- **Именование**: файлы=camelCase/kebab, компоненты=PascalCase, константы=UPPER_SNAKE
- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = ошибка везде; `no-explicit-any` = предупреждение в `open-sse/` и `tests/`
- **TypeScript**: `strict: false`, целевая версия ES2022, модуль esnext, разрешение bundler. Предпочитайте явные типы.

### База Данных

- **Всегда** используйте модули домена из `src/lib/db/` — **никогда** не пишите сырой SQL в маршрутах или обработчиках
- **Никогда** не добавляйте логику в `src/lib/localDb.ts` (только слой повторного экспорта)
- **Никогда** не используйте barrel-import из `localDb.ts` — вместо этого импортируйте конкретные модули `db/`
- Синглтон БД: `getDbInstance()` из `src/lib/db/core.ts` (журналирование WAL)
- Миграции: `src/lib/db/migrations/` — версионированные SQL файлы, идемпотентные, выполняются в транзакциях

### Обработка Ошибок

- try/catch с конкретными типами ошибок, логирование с контекстом pino
- Никогда не игнорируйте ошибки в потоках SSE — используйте сигналы прерывания для очистки
- Возвращайте правильные коды состояния HTTP (4xx/5xx)

### Безопасность

- **Никогда** не используйте `eval()`, `new Function()`, или подразумеваемый eval
- Проверяйте все входные данные с помощью схем Zod
- Шифруйте учетные данные в состоянии покоя (AES-256-GCM)
- Список заголовков для отказа: `src/shared/constants/upstreamHeaders.ts` — поддерживайте согласованность между очисткой, схемами Zod и юнит-тестами при редактировании
- **Публичные учетные данные для upstream** (OAuth client_id/secret в стиле Gemini/Antigravity/Windsurf + ключи Firebase Web, извлеченные из публичных CLI): **ДОЛЖНЫ** быть встроены через `resolvePublicCred()` из `open-sse/utils/publicCreds.ts` — **никогда** как строковые литералы. См. `docs/security/PUBLIC_CREDS.md` для обязательного шаблона.
- **Ответы на ошибки** (HTTP / SSE / обработчик executor / MCP): **ДОЛЖНЫ** проходить через `buildErrorBody()` или `sanitizeErrorMessage()` из `open-sse/utils/error.ts` — **никогда** не помещайте сырые `err.stack` или `err.message` в тело ответа. См. `docs/security/ERROR_SANITIZATION.md`.
- **Команды оболочки, построенные из переменных**: при вызове `exec()`/`spawn()` со скриптом, который требует значения времени выполнения, передавайте их через опцию `env` (автоматически экранируется для оболочки) — **никогда** не интерполируйте ненадежные/внешние пути в тело скрипта. Ссылка: `src/mitm/cert/install.ts::updateNssDatabases`.
- **Библиотеки с безопасными настройками по умолчанию** ([tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)): предпочитайте Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink перед пользовательскими реализациями при добавлении новых поверхностей, чувствительных к безопасности.

---

## Общие Сценарии Модификации

### Добавление Нового Провайдера

1. Зарегистрируйте в `src/shared/constants/providers.ts` (проверка Zod при загрузке)
2. Добавьте executor в `open-sse/executors/`, если нужна пользовательская логика (расширьте `BaseExecutor`)
3. Добавьте переводчик в `open-sse/translator/`, если формат не OpenAI
4. Добавьте конфигурацию OAuth в `src/lib/oauth/constants/oauth.ts`, если на основе OAuth — если upstream CLI поставляет публичный client_id/secret, встроите через `resolvePublicCred()` (см. `docs/security/PUBLIC_CREDS.md`), **никогда** как литерал
5. Зарегистрируйте модели в `open-sse/config/providerRegistry.ts`
6. Напишите тесты в `tests/unit/` (включите проверку формы publicCreds, если вы добавили новый встроенный по умолчанию)

### Добавление Нового API Маршрута

1. Создайте директорию в `src/app/api/v1/your-route/`
2. Создайте `route.ts` с обработчиками `GET`/`POST`
3. Следуйте шаблону: CORS → проверка тела Zod → необязательная аутентификация → делегирование обработчика
4. Обработчик помещается в `open-sse/handlers/` (импортируйте оттуда, а не инлайн)
5. Ответы на ошибки используют `buildErrorBody()` / `errorResponse()` из `open-sse/utils/error.ts` (автоматически очищены — никогда не помещайте `err.stack` или `err.message` сырыми в тело). См. `docs/security/ERROR_SANITIZATION.md`.
6. Добавьте тесты — включая как минимум одно утверждение, что ответы на ошибки не раскрывают трассировки стека (`!body.error.message.includes("at /")`)

### Добавление Нового Модуля БД

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

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

1. Добавьте определение инструмента в `open-sse/mcp-server/tools/` с схемой ввода Zod + асинхронным обработчиком
2. Зарегистрируйте в наборе инструментов (подключено через `createMcpServer()`)
3. Назначьте соответствующим областям
4. Напишите тесты (вызов инструмента записывается в таблицу `mcp_audit`)

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

1. Создайте навык в `src/lib/a2a/skills/` (уже существует 5: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
2. Навык получает контекст задачи (сообщения, метаданные) → возвращает структурированный результат
3. Зарегистрируйте в `A2A_SKILL_HANDLERS` в `src/lib/a2a/taskExecution.ts`
4. Экспонируйте в `src/app/.well-known/agent.json/route.ts` (Agent Card)
5. Напишите тесты в `tests/unit/`
6. Документируйте в `docs/frameworks/A2A-SERVER.md` таблицу навыков

### Добавление Нового Облачного Агента

1. Создайте класс агента в `src/lib/cloudAgent/agents/`, расширяющий `CloudAgentBase` (уже существует 3: codex-cloud, devin, jules)
2. Реализуйте `createTask`, `getStatus`, `approvePlan`, `sendMessage`, `listSources`
3. Зарегистрируйте в `src/lib/cloudAgent/registry.ts`
4. Добавьте обработку OAuth/учетных данных, если необходимо (`src/lib/oauth/providers/`)
5. Тесты + документируйте в `docs/frameworks/CLOUD_AGENT.md`

### Добавление Нового Ограничителя / Eval / Навыка / События Webhook

- Ограничитель: `src/lib/guardrails/` → документация: `docs/security/GUARDRAILS.md`
- Eval suite: `src/lib/evals/` → документация: `docs/frameworks/EVALS.md`
- Навык (песочница): `src/lib/skills/` → документация: `docs/frameworks/SKILLS.md`
- Событие Webhook: `src/lib/webhookDispatcher.ts` → документация: `docs/frameworks/WEBHOOKS.md`

## Справочная документация

Для любых нетривиальных изменений сначала прочитайте соответствующий углубленный материал:

| Область                                             | Документ                                                          |
| --------------------------------------------------- | ----------------------------------------------------------------- |
| Навигация по репозиторию                            | `docs/architecture/REPOSITORY_MAP.md`                             |
| Архитектура                                         | `docs/architecture/ARCHITECTURE.md`                               |
| Справочник по инженерии                             | `docs/architecture/CODEBASE_DOCUMENTATION.md`                     |
| Авто-комбо (9-факторная оценка, 14 стратегий)       | `docs/routing/AUTO-COMBO.md`                                      |
| Устойчивость (3 механизма)                          | `docs/architecture/RESILIENCE_GUIDE.md`                           |
| Воспроизведение рассуждений                         | `docs/routing/REASONING_REPLAY.md`                                |
| Каркас навыков                                      | `docs/frameworks/SKILLS.md`                                       |
| Система памяти (FTS5 + Qdrant)                      | `docs/frameworks/MEMORY.md`                                       |
| Облачные агенты                                     | `docs/frameworks/CLOUD_AGENT.md`                                  |
| Ограничения (PII / инъекция / видение)              | `docs/security/GUARDRAILS.md`                                     |
| Публичные учетные данные (Gemini и др.)             | `docs/security/PUBLIC_CREDS.md`                                   |
| Санитизация сообщений об ошибках                    | `docs/security/ERROR_SANITIZATION.md`                             |
| Оценки                                              | `docs/frameworks/EVALS.md`                                        |
| Соответствие / аудит                                | `docs/security/COMPLIANCE.md`                                     |
| Вебхуки                                             | `docs/frameworks/WEBHOOKS.md`                                     |
| Пайплайн авторизации                                | `docs/architecture/AUTHZ_GUIDE.md`                                |
| Скрытность (TLS / отпечаток)                        | `docs/security/STEALTH_GUIDE.md`                                  |
| Протоколы агентов (A2A / ACP / Cloud)               | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`                        |
| MCP сервер                                          | `docs/frameworks/MCP-SERVER.md`                                   |
| A2A сервер                                          | `docs/frameworks/A2A-SERVER.md`                                   |
| Справочник API + OpenAPI                            | `docs/reference/API_REFERENCE.md` + `docs/reference/openapi.yaml` |
| Каталог провайдеров (автоматически сгенерированный) | `docs/reference/PROVIDER_REFERENCE.md`                            |
| Процесс выпуска                                     | `docs/ops/RELEASE_CHECKLIST.md`                                   |

---

## Тестирование

| Что                     | Команда                                                                |
| ----------------------- | ---------------------------------------------------------------------- |
| Модульные тесты         | `npm run test:unit`                                                    |
| Один файл               | `node --import tsx/esm --test tests/unit/file.test.ts`                 |
| Vitest (MCP, autoCombo) | `npm run test:vitest`                                                  |
| E2E (Playwright)        | `npm run test:e2e`                                                     |
| Протокол E2E (MCP+A2A)  | `npm run test:protocols:e2e`                                           |
| Экосистема              | `npm run test:ecosystem`                                               |
| Порог покрытия          | `npm run test:coverage` (75/75/75/70 — операторы/строки/функции/ветви) |
| Отчет о покрытии        | `npm run coverage:report`                                              |

**Правило PR**: Если вы изменяете производственный код в `src/`, `open-sse/`, `electron/` или `bin/`, вы должны включить или обновить тесты в том же PR.

**Предпочтение уровня тестирования**: сначала модульные → интеграционные (мульти-модульные или состояние БД) → e2e (только UI/рабочий процесс). Кодируйте воспроизведения ошибок как автоматизированные тесты до или вместе с исправлением.

**Политика покрытия Copilot**: Когда PR изменяет производственный код и покрытие ниже 75% (операторы/строки/функции) или 70% (ветви), не просто сообщайте — добавьте или обновите тесты, повторно запустите порог покрытия, затем запросите подтверждение. Включите выполненные команды, измененные тестовые файлы и окончательный результат покрытия в отчет PR.

---

## Git Workflow

```bash
# Никогда не коммитьте напрямую в main
git checkout -b feat/your-feature
git commit -m "feat: опишите ваше изменение"
git push -u origin feat/your-feature
```

**Префиксы веток**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`

**Формат коммита** (Conventional Commits): `feat(db): добавить circuit breaker` — области: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`

**Хуки Husky**:

- **pre-commit**: lint-staged + `check-docs-sync` + `check:any-budget:t11`
- **pre-push**: `npm run test:unit`

---

## Среда

- **Время выполнения**: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES Модули
- **TypeScript**: 5.9+, целевой ES2022, модуль esnext, разрешение bundler
- **Псевдонимы путей**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*`
- **Порт по умолчанию**: 20128 (API + панель управления на одном порту)
- **Директория данных**: переменная окружения `DATA_DIR`, по умолчанию `~/.omniroute/`
- **Ключевые переменные окружения**: `PORT`, `JWT_SECRET`, `API_KEY_SECRET`, `INITIAL_PASSWORD`, `REQUIRE_API_KEY`, `APP_LOG_LEVEL`
- Настройка: `cp .env.example .env`, затем сгенерируйте `JWT_SECRET` (`openssl rand -base64 48`) и `API_KEY_SECRET` (`openssl rand -hex 32`)

---

## Жесткие правила

1. Никогда не коммитьте секреты или учетные данные
2. Никогда не добавляйте логику в `localDb.ts`
3. Никогда не используйте `eval()` / `new Function()` / подразумеваемый eval
4. Никогда не коммитьте напрямую в `main`
5. Никогда не пишите сырой SQL в маршрутах — используйте модули `src/lib/db/`
6. Никогда не игнорируйте ошибки в потоках SSE
7. Всегда проверяйте входные данные с помощью схем Zod
8. Всегда включайте тесты при изменении производственного кода
9. Покрытие должно оставаться ≥75% (операторы, строки, функции) / ≥70% (ветви). Текущая измеренная: ~82%.
10. Никогда не обходите хуки Husky (`--no-verify`, `--no-gpg-sign`) без явного одобрения оператора.
11. Никогда не встраивайте публичные upstream OAuth client_id/secret или ключи Firebase Web в виде строковых литералов — всегда используйте `resolvePublicCred()` (`open-sse/utils/publicCreds.ts`). См. `docs/security/PUBLIC_CREDS.md`.
12. Никогда не возвращайте сырой `err.stack` / `err.message` в HTTP / SSE / ответах исполнителя — всегда обрабатывайте через `buildErrorBody()` или `sanitizeErrorMessage()` (`open-sse/utils/error.ts`). См. `docs/security/ERROR_SANITIZATION.md`.
13. Никогда не интерполируйте внешние пути или значения времени выполнения в shell-скрипты, передаваемые в `exec()`/`spawn()` — передавайте через опцию `env`. Ссылка: `src/mitm/cert/install.ts::updateNssDatabases`.
14. Никогда не игнорируйте предупреждение CodeQL / Secret-Scanning без (a) предварительной проверки документации по шаблонам выше, чтобы увидеть, применим ли помощник, и (b) записи технического обоснования в комментарии об отклонении. Прецедент: `js/stack-trace-exposure`, поднятый на вызовах, которые уже обрабатываются через `sanitizeErrorMessage()`, является известным ограничением CodeQL (пользовательские санитайзеры не распознаются) — отклоняйте как `false positive`, ссылаясь на `docs/security/ERROR_SANITIZATION.md`.
15. Никогда не открывайте маршруты, которые запускают дочерние процессы (`/api/mcp/`, `/api/cli-tools/runtime/`), без классификации `isLocalOnlyPath()` в `src/server/authz/routeGuard.ts`. Принуждение к петле происходит без условий перед любой проверкой аутентификации — утечка JWT через туннель не может вызвать запуск процесса. См. `docs/security/ROUTE_GUARD_TIERS.md`.
16. Никогда не включайте трейлеры `Co-Authored-By`, которые приписывают авторство AI-ассистенту, LLM или автоматизированному аккаунту (например, имена, содержащие "Claude", "GPT", "Copilot", "Bot"; письма на `anthropic.com` / `openai.com` / адресах `noreply.github.com`, принадлежащих ботам). Такие трейлеры направляют атрибуцию коммитов к аккаунту бота на GitHub, скрывая реального автора (`diegosouzapw`) в истории PR. Человеческие соавторы — включая авторов upstream PR и репортёров issues, портируемых в OmniRoute — МОГУТ и ДОЛЖНЫ быть отмечены стандартными трейлерами `Co-authored-by: Name <email>`; рабочие процессы upstream-port (`/port-upstream-features`, `/port-upstream-issues`) зависят от этого.