Skip to content

Contributing RU

Pavel Erokhin edited this page Nov 20, 2026 · 4 revisions

English version

Спасибо, что помогаете ctxray. Эта страница ведёт от свежего клона до pull request: подготовка, проверки, правила, которым следует код, и добавление харнесса. Как код складывается в целое, объясняет Architecture.

Подготовка

Нужны git и Bun. Корневой package.json закрепляет версию Bun в packageManager — поставьте именно её. Правила Feature-Action Architecture подключены git-подмодулем:

git clone https://github.com/MairwunNx/ctxray.git
cd ctxray
git submodule update --init
bun install

CLI запускается прямо из исходников, без сборки:

bun packages/ctxray/src/app/main.ts inspect
bun packages/ctxray/src/app/main.ts test --help

Пробуйте на копии фикстуры, а не в самом репозитории, и держите кеш харнессов в отдельной папке:

repo="$PWD"
dir="$(mktemp -d)"
cp -R packages/ctxray/fixtures/capture/. "$dir/project"
cd "$dir/project" && git init -q
CTXRAY_CACHE_DIR="$dir/cache" bun "$repo/packages/ctxray/src/app/main.ts" test --plain

Команды

Команда Что делает
bun run check Biome, проверка типов (CLI и скрипт страницы HTML-отчёта) и лимит размера файлов. CI запускает то же самое
bun test Модульные тесты
bun run fix Безопасные исправления и форматирование Biome, biome check --write .
bun run build Компилирует исполняемый файл под эту машину в dist/ctxray
bun run typecheck Только проверка типов
bun run schemas Пишет публикуемые JSON Schema в dist/schemas
bun run gitleaks Заново генерирует правила редактирования секретов из gitleaks

Запускайте bun run check и bun test перед каждым коммитом.

Правила

Эти правила действуют для каждого изменения. Изменение, которое нарушает одно из них, ревью вернёт.

  • Стек. Bun, TypeScript в строгом режиме и Elysia, больше ничего.
  • Архитектура. Строго Feature-Action Architecture. Прочитайте Feature-Action-Architecture/AI.md и Feature-Action-Architecture/examples/ts-bun.md. Импорты идут только вниз, через index.ts каждого слайса и его алиас с # (Architecture).
  • Внедрение зависимостей. typed-inject, фабрики принимают зависимости позиционными параметрами и называют их в .inject. Не форма (deps: Deps) => … из README FAA: typed-inject передаёт аргументы по позиции. Никаких классов-сервисов с состоянием там, где хватит функции, и никаких глобальных синглтонов.
  • Самый простой код. Никаких абстракций «на потом». Явное лучше магии.
  • Маленькие файлы. Целитесь примерно в 120 строк, никогда не больше 200. scripts/check-file-size.ts валит CI на файле кода длиннее. Каталоги i18n и фикстуры — исключение.
  • Только Biome. Он и линтер, и форматтер. Никаких ESLint и Prettier.
  • Модульные тесты на bun:test для логики: резолверы, нормализация, разбор конфигов харнессов, статистика, редактирование секретов, выбор локали, множественные формы, политики, строки отчёта, развёртка матрицы. Тривиальное не тестируйте. Где одно поведение встречает много входов, прежде всего харнессы и локали, пишите таблицу test.each.
  • Ни телеметрии, ни сети по умолчанию. ctxray обращается только к реестру и upstream, которые настроил пользователь.
  • Секреты не утекают. Секреты и персональные данные никогда не попадают в трейсы, логи, отчёты и снапшоты открытым текстом. Редактирование работает до того, как что-то запишется на диск.
  • Файлы пользователя не трогаем. Прогон тестов никогда не касается рабочего дерева пользователя: фикстуры и канарейки живут во временной копии. Запуски харнессов не трогают и настоящую домашнюю папку: ~/.claude, ~/.codex, ~/.gemini, ~/.config/opencode, ~/.cursor и связка ключей macOS остаются как были.
  • Каждая строка, которую видит пользователь, идёт через каталог i18n. Источник — английский в packages/ctxray/src/shared/i18n/locales/en/index.ts, русский в locales/ru/index.ts поставляется вместе с ним. Строка для пользователя, зашитая в код, — это баг. Добавляйте каждый новый ключ в оба каталога: проверка типов и catalogs.test.ts падают, если не хватает ключа, формы множественного числа или плейсхолдера. Подробности — на странице Localization.
  • Код на английском. Код, комментарии, идентификаторы и сообщения коммитов пишутся по-английски.

Коммиты и changelog

Коммиты следуют Conventional Commits на английском, одно логическое изменение на коммит, и каждый коммит собирается и проходит свои тесты:

feat(proxy): count Gemini's cached tokens
fix(i18n): Russian plural for “harnesses”
chore(ci): update actions/checkout to v8
docs(wiki): the GitLab merge request job

В CHANGELOG.md по разделу на версию: ## 0.2.0. Если изменение доходит до того, что поставляет ctxray (CLI, npm-пакет, образы, плагин), добавьте строку в самый верхний ещё не выпущенный раздел или откройте раздел для следующей версии. Заметки релиза берутся из этого раздела, поэтому пишите для тех, кто ставит ctxray, а не для его разработчиков. Изменениям CI и инструментов разработки запись не нужна.

Как добавить адаптер харнесса

Харнесс входит в ctxray по шагам, и каждый шаг работает сам по себе: сначала static, потом capture, потом установка. Перед началом прочитайте папку харнесса, похожего на ваш: codex — для CLI, который говорит на OpenAI Responses, gemini-cli — для того, что работает на Node.

  1. Id. Добавьте его в HarnessId в shared/contract/harness.ts. Схема конфига, lock-файл и публикуемые JSON Schema берут его оттуда.
  2. Профиль. Добавьте HarnessProfile в PROFILES в entities/harness/profiles.ts: режимы и возможности, которые у харнесса действительно есть. profiles.test.ts проверяет, например, что харнесс с capture ещё и headless и proxyable.
  3. Обнаружение и разрешение. Создайте entities/harness/<id>/ с discover.ts, который находит все файлы, которые харнесс может загрузить, и возвращает Inventory, и resolve.ts, который предсказывает, что загрузится для рабочей папки и набора файлов. Зарегистрируйте оба в STATIC_ADAPTERS в entities/harness/adapters.ts.
  4. Места файлов. Расскажите entities/harness/locations.ts, какие расположения файлов читает харнесс, чтобы проверка охвата могла предупредить, когда харнессы получают разные инструкции.
  5. Статические тесты. Добавьте проект-фикстуру в packages/ctxray/fixtures/static/ и проверьте на нём обнаружение, активацию и находки lint таблицами test.each. Укажите в комментарии, какую версию харнесса эмулирует код.
  6. Запуск. Напишите launch.ts: команду для headless-запуска, окружение, которое направляет харнесс на прокси ctxray с фиктивным ключом, и файлы конфигурации внутри домашней папки прогона, с выключенными телеметрией и обновлениями. MCP-серверы направьте через context.shim и context.remote. Напишите и version().
  7. Сегменты. Напишите segment.ts, который режет захваченный запрос на system, rules, skills, mcp, commands, tools и messages, и capture.ts с CaptureAdapter, включая call(), который превращает намерение теста в вызов инструмента самого харнесса. Зарегистрируйте его в CAPTURE_ADAPTERS. Харнессу с протоколом, которого ctxray ещё не знает, нужен ещё и kit в entities/proxy/protocols/.
  8. Payload. Добавьте харнесс в packages/ctxray/fixtures/capture/ctxray.config.ts, закрепите его через ctxray harness add в этой папке и запишите его настоящие запросы (ниже). Контрактные тесты сегментатора пишите на записанных payload.
  9. Установка. Добавьте Recipe в RECIPES в entities/harness-cache/recipes.ts: npm-пакет, dist-tag по умолчанию, сборку под платформу и место исполняемого файла. Установочные скрипты пакетов не запускаются никогда.
  10. Пользовательская область. Научите capture/user-scope.ts и capture/user-mcp.ts, какие пользовательские правила, скиллы и MCP-серверы приносит userScope: "inherit".
  11. Тексты и документация. Новые сообщения lint — в оба каталога. Обновите страницу Harnesses и таблицу поддерживаемых агентов в README.

Запись payload

Контрактные тесты сегментаторов работают на настоящих запросах, которые отправил каждый харнесс. Они лежат в packages/ctxray/fixtures/payloads/. После обновления харнесса запишите их заново:

(cd packages/ctxray/fixtures/capture && bun ../../src/app/main.ts harness install)
bun scripts/record-payloads.ts            # все харнессы
bun scripts/record-payloads.ts codex      # один

Скрипт запускает каждый харнесс на capture-фикстуре против mock-модели — из кеша, как его закрепляет ctxray.lock фикстуры, или из PATH, если в кеше его нет. Папку копии, домашнюю папку прогона и путь к кешу он заменяет стабильными заглушками, чтобы файлы не менялись от машины к машине. Потом bun test покажет, что сдвинулось: если харнесс поменял маркеры, чините сегментатор.

CI и автопилот

Workflow Что делает
ci.yml На каждый push и pull request: Biome, проверка типов, лимит размера файлов, тесты, сборка, smoke-тесты исполняемого файла, конфига, раннера тестов и захвата со всеми закреплёнными харнессами, проверка плагина Claude Code
autopilot-biome.yml Его вызывает CI, когда падает Biome: Claude исправляет то, о чём сообщил Biome, и коммитит в ту же ветку, один раз
autopilot.yml Каждый понедельник: Claude запускает скилл update-deps, обновляет все зависимости и запускает CI на результате
release.yml Запускается вручную: выпускает версию, введённую в его поле, с заметками из CHANGELOG.md
release-build.yml Его вызывают Release и Next: собирает все платформы и ставит каждую сборку так, как поставил бы пользователь
release-packages.yml Его вызывают Release и Next: публикует в npm и ghcr.io
next.yml На каждый push в master: выпускает в канал next, когда переменная репозитория NEXT_CHANNEL равна "true"

Скилл update-deps в .claude/skills/update-deps/SKILL.md описывает, что обновляется вместе: Bun с @types/bun, Biome с URL его схемы, правила gitleaks, подмодуль и харнессы, закреплённые в capture-фикстуре. Прочитайте его, прежде чем обновлять зависимость вручную.

Релизы

Выпускает релизы только владелец или агент по его просьбе. CHANGELOG.md получает раздел для новой версии, например ## 0.1.1. Затем владелец запускает Actions → Release → Run workflow и вводит версию в поле или запускает gh workflow run release.yml -f version=0.1.1 -f dry-run=false. Workflow записывает версию в package.json и plugin.json своей сборки и берёт заметки из этого раздела, если в поле changelog не введены другие. По умолчанию это пробный прогон: он собирает и проверяет всё, но ничего не публикует.

Настоящий релиз создаёт релиз на GitHub с подписанными контрольными суммами и аттестацией сборки, публикует npm-пакеты и образы и обновляет Homebrew tap, Scoop bucket и репозиторий action с тегами v<version> и v0.

Между релизами, когда переменная NEXT_CHANNEL включена, каждый push в master выходит в канал next: dist-tag next в npm и образы :edge и :edge-runtime. Версия — патч после самого нового тега релиза с номером запуска, например 0.1.1-next.42, так что она сортируется выше релиза, за которым идёт:

npm install -g @mairwunnx/ctxray@next

Clone this wiki locally