Repository navigation
Contributing RU
Спасибо, что помогаете 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 installCLI запускается прямо из исходников, без сборки:
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. - Код на английском. Код, комментарии, идентификаторы и сообщения коммитов пишутся по-английски.
Коммиты следуют 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.
-
Id. Добавьте его в
HarnessIdвshared/contract/harness.ts. Схема конфига, lock-файл и публикуемые JSON Schema берут его оттуда. -
Профиль. Добавьте
HarnessProfileвPROFILESвentities/harness/profiles.ts: режимы и возможности, которые у харнесса действительно есть.profiles.test.tsпроверяет, например, что харнесс сcaptureещё иheadlessиproxyable. -
Обнаружение и разрешение. Создайте
entities/harness/<id>/сdiscover.ts, который находит все файлы, которые харнесс может загрузить, и возвращаетInventory, иresolve.ts, который предсказывает, что загрузится для рабочей папки и набора файлов. Зарегистрируйте оба вSTATIC_ADAPTERSвentities/harness/adapters.ts. -
Места файлов. Расскажите
entities/harness/locations.ts, какие расположения файлов читает харнесс, чтобы проверка охвата могла предупредить, когда харнессы получают разные инструкции. -
Статические тесты. Добавьте проект-фикстуру в
packages/ctxray/fixtures/static/и проверьте на нём обнаружение, активацию и находки lint таблицамиtest.each. Укажите в комментарии, какую версию харнесса эмулирует код. -
Запуск. Напишите
launch.ts: команду для headless-запуска, окружение, которое направляет харнесс на прокси ctxray с фиктивным ключом, и файлы конфигурации внутри домашней папки прогона, с выключенными телеметрией и обновлениями. MCP-серверы направьте черезcontext.shimиcontext.remote. Напишите иversion(). -
Сегменты. Напишите
segment.ts, который режет захваченный запрос наsystem,rules,skills,mcp,commands,toolsиmessages, иcapture.tsсCaptureAdapter, включаяcall(), который превращает намерение теста в вызов инструмента самого харнесса. Зарегистрируйте его вCAPTURE_ADAPTERS. Харнессу с протоколом, которого ctxray ещё не знает, нужен ещё и kit вentities/proxy/protocols/. -
Payload. Добавьте харнесс в
packages/ctxray/fixtures/capture/ctxray.config.ts, закрепите его черезctxray harness addв этой папке и запишите его настоящие запросы (ниже). Контрактные тесты сегментатора пишите на записанных payload. -
Установка. Добавьте
RecipeвRECIPESвentities/harness-cache/recipes.ts: npm-пакет, dist-tag по умолчанию, сборку под платформу и место исполняемого файла. Установочные скрипты пакетов не запускаются никогда. -
Пользовательская область. Научите
capture/user-scope.tsиcapture/user-mcp.ts, какие пользовательские правила, скиллы и MCP-серверы приноситuserScope: "inherit". - Тексты и документация. Новые сообщения lint — в оба каталога. Обновите страницу Harnesses и таблицу поддерживаемых агентов в README.
Контрактные тесты сегментаторов работают на настоящих запросах, которые отправил каждый харнесс. Они лежат в 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 покажет, что сдвинулось: если харнесс поменял маркеры, чините сегментатор.
| 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@nextStart
Use
Teams
Develop
По-русски
- Начало работы · Понятия · Loadout Stack · Режимы захвата
- Тесты · Конфигурация · Политики · Харнессы · Команды · Отчёты · Плагин Claude Code
- CI · Enterprise
- Архитектура · Локализация · Участие