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

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

git clone https://github.com/lidge-jun/opencodex.git
cd opencodex
bun install
bun run setup:hooks  # удалить прежние управляемые pre-push и post-merge
bun run dev:proxy    # прокси-API в режиме разработки
bun run dev:gui      # dev-сервер дашборда (другой терминал)
bun run typecheck    # bun x tsc --noEmit
bun run test        # полный набор тестов (по умолчанию)

bun run setup:hooks удаляет прежние управляемые хуки pre-push и post-merge, если они не были изменены. Пользовательские хуки сохраняются. Хук pre-push больше не обязателен; bun run prepush остаётся необязательной ручной проверкой.

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:changed              # тесты графа импортов относительно найденного merge-base dev
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 run test. Если полный прогон несоразмерно затратен с учётом размера задачи, ресурсов машины или одновременно используемых рабочих деревьев, обязательно выполните хотя бы целевые регрессионные тесты, проверяющие изменённое поведение, например bun test tests/<domain>/<name>.test.ts. Объясните причину сокращения прогона и укажите точные команды, результаты и непроверенную область. bun run test:changed дополняет проверку, но не обнаруживает все косвенные зависимости. Нельзя устанавливать общее исключение, позволяющее полагаться только на CI или пропускать локальные тесты. Перед слиянием все обязательные проверки CI должны успешно завершиться для точного текущего коммита HEAD pull request.

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/, а заметки о планировании и расследованиях — в devlog/.
Сохраняйте экспорты — от них могут зависеть другие модули.

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

Все селекторы провайдеров и seed-данные выводятся из канонического реестра (src/providers/registry/entries-extended.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. Claim passthrough может ссылаться только на assertion equals по selector, привязанному к этой feature в manifest test, чей ожидаемый результат совпадает с собственным значением вызывающей стороны в том же месте. Поэтому удалённое, переписанное или не относящееся к делу поле нельзя пометить как lossless. Аспекты, которые маршрут может сохранить по отдельности, например custom tool и его grammar, оформляйте отдельными claim.

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

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

Следуйте политике тестирования выше и выполняйте bun run typecheck при изменении типов, а также проверки для затронутой области. Указывайте команды, результаты и непроверенную область; заявляйте только о реально выполненной проверке.