Участие в разработке

Настройка окружения

git clone https://github.com/lidge-jun/opencodex.git
cd opencodex
bun install
bun run dev:proxy    # прокси-API в режиме разработки
bun run dev:gui      # dev-сервер дашборда (другой терминал)
bun run typecheck    # bun x tsc --noEmit
bun run test:changed              # routine import-graph test selection
bun test tests/routing/router.test.ts     # routine focused test
bun run test                      # complete suite (PR-ready / explicit ask)

bun run dev остаётся псевдонимом для bun run dev:proxy. Dev-сервер дашборда — bun run dev:gui; упакованный дашборд, доступный по GET /, собирается командой bun run build:gui (gui/dist).

Команды сборки и тестирования

Корневой пакет — Bun-нативный TypeScript; отдельного шага компиляции сервера нет. Используйте скрипты из репозитория, чтобы локальные команды совпадали с CI:

bun run typecheck                 # строгая проверка TypeScript
bun run test                      # полный набор tests/
bun test tests/routing/router.test.ts     # отдельный тестовый файл
bun run build:gui                 # сборка GUI на Vite + подготовка пакета
bun run privacy:scan              # проверка учётных данных/приватности, используемая в CI
bun run prepare:package           # обновление лаунчеров/ресурсов пакета

Bun-тесты лежат в доменных каталогах, повторяющих src/ (tests/<domain>/); карта — scripts/test-layout/layout.json. В tests/helpers/ лежат общие fixtures, а в tests/e2e-style/ — более широкие сценарии нативного паритета. Добавляйте сфокусированный регрессионный тест рядом с существующими тестами изменяемой подсистемы; если затронуты общая маршрутизация, адаптеры, конфигурация или поведение сервера, запускайте полный набор.

Сайт документации, который вы сейчас читаете, находится в docs-site/ (Astro + Starlight):

cd docs-site && bun install && bun dev

Публикация документации

Публичная документация публикуется на GitHub Pages по адресу https://opencodex.me/ru/. Воркфлоу .github/workflows/deploy-docs.yml запускается на push в main, затрагивающих docs-site/** или сам воркфлоу, собирает docs-site и разворачивает сгенерированный сайт. Перед push изменений документации выполните:

cd docs-site
bun install --frozen-lockfile
bun run build

CI и релизы

GitHub Actions намеренно остаются компактными:

Cross-platform CI (.github/workflows/ci.yml) запускается на pull request и push в main, затрагивающих файлы рантайма, тестов, пакета, скриптов, TypeScript или воркфлоу. Его Bun-матрица покрывает Linux, Windows и macOS: install, typecheck, тесты, privacy scan, smoke-сборка release-helper, сборка GUI и ocx help. Отдельная линия на тех же трёх ОС подтверждает, что npm global install работает без отдельно установленного Bun — за счёт runtime, входящего в состав пакета.
Release (.github/workflows/release.yml) запускается вручную. Он не служит вторым полным CI-пайплайном; перед dry-run или publish он требует, чтобы для точного релизного коммита (GITHUB_SHA) уже был успешный запуск Cross-platform CI.

Для релизов используйте helper:

Перед запуском helper выберите версию релиза и запустите .github/workflows/dev-version-bump.yml из ветки по умолчанию с параметрами intended-version=<version> и mode=pre-move. Проверьте и влейте созданный PR в dev, затем перенесите изменения в main или preview и запустите helper. Если версия dev уже выше целевой, workflow вернёт changed=false и PR для смены версии не потребуется. Публикация по-прежнему требует успешного CI для точного коммита релиза.

bun run release <version>           # коммитит/пушит bump версии; publish workflow по умолчанию dry-run
bun run release --bump minor        # вычисляет следующую patch, minor или major версию по тегам и каналам npm
bun run release <version> --publish # publish после осознанного CI-gated dry-run
bun run release:watch               # наблюдение за последним запуском Release workflow

--bump patch|minor|major можно использовать вместо явной версии. После появления preview-тега для более высокого core команда --bump patch откажется продолжать старую stable patch-линию; включите исправление в уже открытую preview-версию.

Ветки

dev — единственная цель интеграции. Открывайте все PR сюда.
main — только релизы. Двигается лишь при продвижении из dev мейнтейнером; не открывайте сюда PR с функциональностью.
preview — ветка предрелизов.

Ветка dev2-go, которая несла нативный порт на Go, закрыта, и вместе с ней закончилась политика двух линий интеграции. Её история опубликована только для чтения в lidge-jun/opencodex-go-archive. Теперь единственная линия рантайма — Bun-нативный TypeScript в dev.

Pull request’ы с ребейзом приветствуются: ребейз устаревшей ветки на текущий head — это обычный вклад, а не шум. Укажите исходные коммиты в описании.

Конвенции

Только ES Modules (import/export), TypeScript, режим strict. Держите bun x tsc --noEmit без ошибок.
Не более ~500 строк на файл — разделяйте по ответственности (сайдкары web-search/ и vision/ — хорошие примеры небольших сфокусированных модулей за единым index.ts).
Обрабатывайте асинхронные ошибки на границах — сайдкары никогда не бросают исключения в путь запроса; они деградируют до корректного маркера.
Structure SOT — актуальные инварианты для мейнтейнеров живут в structure/. Публичные пользовательские сценарии держите в docs-site/, а исторические заметки расследований — в docs/.
Сохраняйте экспорты — от них могут зависеть другие модули.

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

Все селекторы провайдеров и seed-данные выводятся из канонического реестра (src/providers/registry.ts):

{
  id: "my-provider",
  label: "My Provider",
  baseUrl: "https://api.example.com/v1",
  adapter: "openai-chat",
  authKind: "key",
  dashboardUrl: "https://example.com/keys",
  models: ["model-a", "model-b"],
  defaultModel: "model-a",
  noVisionModels: ["model-a"],   // text-only models → vision sidecar describes images
},

src/providers/derive.ts передаёт эту запись в ocx init, ocx provider, пресеты дашборда, вход по API-ключу и seed-конфигурации OAuth. enrichProviderFromCatalog() копирует метаданные моделей и классификацию возможностей в сохранённую конфигурацию провайдера. Реализации OAuth-протоколов по-прежнему живут в src/oauth/; одни лишь метаданные реестра ещё не образуют OAuth-flow.

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

Реализуйте ProviderAdapter (см. Адаптеры) в src/adapters/, зарегистрируйте его имя в src/server/adapter-resolve.ts и приведите его вывод к внутренним событиям AdapterEvent. Переиспользуйте image.ts для работы с изображениями и ориентируйтесь на openai-chat.ts для обычной потоковой передачи и вызовов инструментов; используйте fetchResponse только когда адаптер сам управляет повторными попытками транспорта, а runTurn — для действительно двунаправленного транспорта вроде Cursor. Добавьте сфокусированные тесты в tests/ и экспортируйте фабрику из src/index.ts, если она входит в публичный API пакета.

Добавление заявления о совместимости

Заявления о совместимости находятся в src/compatibility/. Их область уже области адаптера: в заявлении указываются точный проверенный провайдер, нормализованный upstream base URL, режим аутентификации, входной и upstream-протоколы и model id. Не переносите заявление на другого провайдера или адрес только потому, что они используют тот же адаптер или wire format.

Используйте одну из версионированных категорий: passthrough, translated, degraded или unsupported. Для каждого заявления, кроме passthrough, опишите конкретное ограничение, а для заявления на основе fixture укажите точные assertion id, которые его доказывают. Добавьте request vector без секретов в tests/fixtures/compatibility/ и сфокусированный тест, выполняющий его через production adapter.

Манифесты совместимости являются пассивными данными. Обычные router, Responses handler и server startup path не должны импортировать каталог манифестов или активировать Compatibility Lab.

Проверяйте, прежде чем объявлять работу завершённой

Запускайте самую узкую команду, которая доказывает ваше изменение: bun run typecheck для типов, сфокусированный bun test tests/<name>.test.ts или runtime-проверку для поведения, а затем более широкие проверки, соответствующие затронутой области. opencodex предпочитает небольшие проверяемые коммиты крупным пачкам изменений.