Repository navigation
Architecture RU
Эта страница — для тех, кто правит код: как устроен код ctxray, как команда доходит до своей логики и как ctxray запускает и измеряет харнесс. Подготовка окружения и правила, которым следуют изменения, — на странице Contributing.
ctxray — одно рабочее пространство Bun с двумя пакетами:
| Пакет | Что это |
|---|---|
packages/ctxray |
CLI, публикуется в npm как @mairwunnx/ctxray. TypeScript в строгом режиме, запускается Bun, для релизов компилируется в один исполняемый файл на платформу |
packages/claude-plugin |
Плагин для Claude Code: скиллы, хуки и конфиг MCP-сервера (Claude Code Plugin). Кода в нём нет, только файлы, которые вызывают ctxray
|
В корне лежат scripts/ (сборка, релиз и служебные скрипты), packaging/ (GitHub Action, шаблон GitLab, Dockerfile, установочные скрипты, npm-лаунчер) и подмодуль Feature-Action-Architecture. Зависимостей у CLI немного: Elysia для локальных серверов, Ink и React для живого вывода в терминале, zod для контрактов, typed-inject для внедрения зависимостей и токенизаторы.
Код в packages/ctxray/src строго следует Feature-Action Architecture (FAA). В FAA четыре слоя, и каждый импортирует только из слоёв ниже себя:
main.ts — точка входа. Сначала он обрабатывает две скрытые подкоманды: __mcp-shim, через которую ctxray вызывают харнессы, и __spectate-hook — пустышку для хуков, которые поставила версия 0.1.0, а всё остальное отдаёт runCli из cli.ts. Рядом лежат commands.ts (список команд), container.ts (DI-контейнер), settings.ts (язык, режим CI и способ вывода), help.ts, options.ts (глобальные флаги) и self.ts, который знает, как ctxray запускает сам себя. user-modules.ts регистрирует Bun.plugin до загрузки любого пользовательского файла, поэтому import … from "@mairwunnx/ctxray" в конфиге или тесте всегда получает API запущенного исполняемого файла из public-api.ts, что бы ни лежало в node_modules.
| Слайс | Команда |
|---|---|
inspect |
ctxray inspect |
test-run |
ctxray test и ctxray baseline
|
diff |
ctxray diff |
show-report |
ctxray show-report |
harness-install |
ctxray harness add, install, list, pack, remove, upgrade
|
cache |
ctxray cache dir, ls, prune, clear
|
session |
скрытая ctxray __session, на которой работает /ctxray плагина |
mcp-serve |
ctxray mcp |
doctor |
ctxray doctor |
gen-prompts |
ctxray gen-prompts |
calibrate |
ctxray calibrate |
init |
ctxray init |
show-config |
ctxray config |
В слайсе лежат <verb>.action.ts с логикой, api/command.ts со спецификацией команды и тонким обработчиком, lib/ для помощников, нужных только этому слайсу, и index.ts — его публичная граница.
| Слайс | Что в нём |
|---|---|
harness |
Контракт адаптера, профили, по папке на харнесс (claude-code, codex, gemini-cli, opencode, cursor), конвейер захвата в capture/ и проверки L1–L3 в layers/
|
harness-cache |
Рецепты установки харнессов, клиент реестра, разбор .npmrc, папки кеша, установки и архивы harness pack
|
lockfile |
Чтение и запись ctxray.lock и расхождения lock-файла с конфигом |
loadout |
Сравнение двух loadout для diff, --base и harness upgrade
|
proxy |
Локальный прокси модели, протоколы, mock-разговор, пересылка в настоящий upstream, кассеты, трейсы, сторож исходящих соединений, цены и точный подсчёт токенов |
report |
Отчёты HTML, JUnit, Allure и Markdown и скрипт страницы HTML-отчёта |
user-config |
Загрузка, слияние и финализация конфига и сетевые настройки, выведенные из него |
| Слайс | Что в нём |
|---|---|
contract |
Версионированные схемы, которые читают все слои: конфиг, loadout, отчёт, трейс, lock-файл, сессия, inspection, тесты. Ещё коды выхода и публикуемые JSON Schema |
cli |
Разбор флагов, CommandSpec и Handler
|
i18n |
Каталоги сообщений, выбор локали, множественные формы, форматы чисел |
render |
Живой вывод на Ink, простой вывод и выбор между ними |
redact |
Редактирование секретов и персональных данных вместе с правилами gitleaks |
tokens |
Токенизаторы o200k и Gemma и калибровка Anthropic |
infra |
Окружение, определение CI, ключи платформ, HTTP через прокси пользователя, файловые блокировки, параллельные помощники |
markdown, glob, codeowners
|
Frontmatter и импорты через @, сопоставление glob, CODEOWNERS |
stats |
Интервал Уилсона для тестов активации |
mcp-shim |
Stdio-прослойка, которую ctxray ставит перед MCP-серверами харнесса |
Импорты идут только вниз: app → features → entities → shared. Фича никогда не импортирует другую фичу, сущность — другую сущность. Другой слайс подключается через его index.ts по алиасу из карты imports в packages/ctxray/package.json:
import { type Config, resolveNetwork } from "#entities/user-config/index.ts";
import { ExitCode } from "#shared/contract/index.ts";Импорты сохраняют расширение .ts. Внутри слайса пишите ./ или один ../, но не ../../: Biome это отклоняет. Скрипты в корне обращаются к коду CLI через #ctxray/*. Глобальных barrel-файлов нет.
ctxray использует typed-inject в функциональном стиле. Фабрика — это функция, которая принимает зависимости позиционными параметрами и объявляет их токены в .inject в том же порядке:
export const createDiffAction =
(config: Config, cwd: string) =>
async ({ base, harnesses }: DiffRequest): Promise<DiffResult> => { … };
createDiffAction.inject = ["config", "cwd"] as const;typed-inject передаёт аргументы по позиции, поэтому форма (deps: Deps) => … не проходит проверку типов и падает при запуске. Никаких классов-сервисов с состоянием там, где хватит функции, и никаких глобальных синглтонов.
app/container.ts строит два уровня:
-
Корневой контейнер
createContainer(env, cwd)живёт весь процесс. Он даётenv,cwd,version,self, загрузчик конфига и действие init, которое работает до того, как появился конфиг. -
Дочерний инжектор прогона
createRunInjector(container, settings, t, renderer, config)хранит то, что решили флаги и конфиг: настройки, переводчик, способ вывода, загруженный конфиг и все остальные фабрики действий. Состояние, которое живёт один прогон, сидит в замыкании внутри него, а сам инжектор освобождается, когда команда закончилась.
Команда — это три части: CommandSpec, фабрика обработчика и запись в COMMANDS.
// features/diff/api/command.ts
export const diffSpec: CommandSpec = {
name: "diff",
summary: "command.diff",
options: {
base: { type: "string", summary: "option.base", value: "ref" },
harness: { type: "string", summary: "option.harness", value: "ids" },
json: { type: "boolean", summary: "option.json" },
config: CONFIG_OPTION,
},
usesConfig: true,
};
export const createDiffCommand =
(diff: DiffAction, t: Translate, renderer: Renderer): Handler =>
async (values) => { … return ExitCode.ok; };
createDiffCommand.inject = ["diffAction", "t", "renderer"] as const;Спецификация называет команду, её параметры и тексты справки — ключами каталога. usesConfig велит CLI сначала загрузить конфиг, а subcommands с defaultSubcommand нужны командам вроде harness и cache. Обработчик разбирает свои флаги, вызывает действие, передаёт результат в вывод и возвращает код выхода.
app/commands.ts перечисляет все команды:
{ spec: diffSpec, handler: (injector) => injector.injectFunction(createDiffCommand) },а createRunInjector даёт действие под тем токеном, который просит обработчик: .provideFactory("diffAction", createDiffAction).
Остальное делает runCli. Он разбирает глобальные флаги вместе с флагами команды, определяет язык и режим CI, загружает конфиг, если спецификация просит, открывает вывод, строит инжектор прогона и вызывает обработчик. Выброшенная ошибка превращается в код выхода 5 со ссылкой на трекер задач.
Каждый харнесс объявляет, что он такое, и подключается максимум в три таблицы в entities/harness плюс рецепт установки:
| Часть | Где | Что сообщает |
|---|---|---|
HarnessProfile |
profiles.ts |
Id, название, режимы (static, capture, observe), экспериментальные режимы и возможности |
StaticAdapter |
adapters.ts, STATIC_ADAPTERS
|
discover(project) находит все файлы, которые харнесс может загрузить, и возвращает Inventory. resolve(inventory, scope) предсказывает, что загрузится для рабочей папки и набора файлов. Это L1–L3 |
CaptureAdapter |
adapters.ts, CAPTURE_ADAPTERS
|
binary, defaultModel, version(), launch() (команда, окружение и файлы конфигурации для одной сессии), call() (как намерение теста превращается в вызов инструмента самого харнесса) и segment() (разрезание захваченного запроса на куски). Это L4 и выше |
Recipe |
entities/harness-cache/recipes.ts, RECIPES
|
npm-пакет, dist-tag по умолчанию, сборка под платформу и место исполняемого файла внутри неё. Для харнесса не из npm — где узнать последнюю версию и контрольную сумму |
Тест, который требует (requires) возможность, которой нет в профиле, пропускается как неподдерживаемый, а не падает. Это решает checkSupport в profile.ts.
Начиная с L4, тест запускает харнесс и читает, что тот отправил. Конвейер живёт в entities/harness/capture и features/test-run/lib/capture.ts:
-
Копия.
createCopyделает на прогон одну закоммиченную копию проекта:git cloneс общими объектами плюс ваши незакоммиченные изменения или копирование файл за файлом вне git. Она дописывает канарейку⟦ctx:<path>⟧в каждый файл, который может загрузить харнесс, так что по захваченному запросу видно, какой файл дошёл до модели. -
Изоляция.
isolateклонирует копию для каждой сессии — copy-on-write, где файловая система это умеет — и даёт сессии своиhome,tmp,binиlogs.startSessionзадаётHOME,TMPDIRи папкиXDG_*, направляет переменные прокси на сторожа исходящих соединений, а на macOS оборачивает команду вsandbox-exec. -
Прокси. Один локальный прокси обслуживает весь прогон, и каждая сессия получает свой префикс
<url>/s/<id>как базовый URL модели. Прокси распознаёт протокол (Anthropic Messages, OpenAI Responses, Chat Completions, Gemini), пишет каждый обмен в отредактированный трейс и отвечает из mock-модели, кассеты или настоящего upstream. MCP-серверы работают за прослойкой ctxray, которая записывает объявленные ими схемы инструментов. -
Сегменты.
segment()адаптера режет запрос на сегменты:system,rules,skills,mcp,commands,toolsиmessages. У каждого есть доказательство: маркер, отпечаток или канарейка.buildLoadoutпривязывает их к файлам проекта и считает токены — получается Loadout, который проверяет тест.
Те же шаги со стороны пользователя описаны на странице Harnesses.
scripts/lib/compile.ts компилирует исполняемый файл через Bun.build:
-
compileсautoloadDotenv: falseиautoloadBunfig: false, чтобы.envилиbunfig.tomlпользователя никогда не меняли поведение ctxray -
bytecode: trueиformat: "esm"для быстрого старта,minify: trueиsourcemap: "linked" -
defineзадаётprocess.env.NODE_ENVравным"production"и встраивает скрипт страницы HTML-отчёта какCTXRAY_REPORT_CLIENT - плагин заменяет заглушкой
react-devtools-core, который импортирует Ink
bun run build компилирует под эту машину в dist/ctxray. scripts/release.ts собирает все платформы в dist/release:
| Папка | Что в ней |
|---|---|
assets/ |
Релиз на GitHub: архив на каждую платформу, SHA256SUMS, install.sh, install.ps1, JSON Schema, ctxray.gitlab-ci.yml, harnesses.Dockerfile, ctxray-claude-plugin.zip и SBOM, если его передали |
bin/ |
Исполняемые файлы, по папке на платформу |
docker/ |
Контекст сборки образов с исполняемыми файлами для Linux |
npm/ |
npm-пакеты и их tarball-архивы в npm/packs
|
packaging/ |
То, что уходит в Homebrew tap, Scoop bucket и репозиторий action |
Платформы: Linux x64 и arm64 на glibc и на musl, сборка x64 на glibc для процессоров без AVX2, macOS arm64 и x64, Windows x64 и arm64. bun scripts/release.ts --only linux-x64,darwin-arm64 собирает несколько из них, чтобы быстро посмотреть.
Start
Use
Teams
Develop
По-русски
- Начало работы · Понятия · Loadout Stack · Режимы захвата
- Тесты · Конфигурация · Политики · Харнессы · Команды · Отчёты · Плагин Claude Code
- CI · Enterprise
- Архитектура · Локализация · Участие