Skip to content

Architecture RU

Pavel Erokhin edited this page Nov 21, 2026 · 5 revisions

English version

Эта страница — для тех, кто правит код: как устроен код 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 для внедрения зависимостей и токенизаторы.

Feature-Action Architecture

Код в packages/ctxray/src строго следует Feature-Action Architecture (FAA). В FAA четыре слоя, и каждый импортирует только из слоёв ниже себя:

Четыре слоя сверху вниз: app, features, entities, shared. Каждый импортирует только из слоёв ниже. Фича никогда не импортирует другую фичу, сущность — другую сущность.

app/

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.

features/

Слайс Команда
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 — его публичная граница.

entities/

Слайс Что в нём
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 Загрузка, слияние и финализация конфига и сетевые настройки, выведенные из него

shared/

Слайс Что в нём
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:

ctxray копирует проект, ставит в каждый файл метку и даёт каждой сессии свою папку. Харнесс работает в песочнице: запросы к модели идут в прокси ctxray, MCP-серверы стоят за прослойкой ctxray, а любое другое соединение упирается в сторожа. Трейс без секретов режется на сегменты, из которых получается Loadout для вашего теста.

  1. Копия. createCopy делает на прогон одну закоммиченную копию проекта: git clone с общими объектами плюс ваши незакоммиченные изменения или копирование файл за файлом вне git. Она дописывает канарейку ⟦ctx:<path>⟧ в каждый файл, который может загрузить харнесс, так что по захваченному запросу видно, какой файл дошёл до модели.
  2. Изоляция. isolate клонирует копию для каждой сессии — copy-on-write, где файловая система это умеет — и даёт сессии свои home, tmp, bin и logs. startSession задаёт HOME, TMPDIR и папки XDG_*, направляет переменные прокси на сторожа исходящих соединений, а на macOS оборачивает команду в sandbox-exec.
  3. Прокси. Один локальный прокси обслуживает весь прогон, и каждая сессия получает свой префикс <url>/s/<id> как базовый URL модели. Прокси распознаёт протокол (Anthropic Messages, OpenAI Responses, Chat Completions, Gemini), пишет каждый обмен в отредактированный трейс и отвечает из mock-модели, кассеты или настоящего upstream. MCP-серверы работают за прослойкой ctxray, которая записывает объявленные ими схемы инструментов.
  4. Сегменты. 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 собирает несколько из них, чтобы быстро посмотреть.

Clone this wiki locally