Обзор CLI
CLI aggrega — точка входа в компилятор. Любое взаимодействие с Aggrega — компиляция сущности Aggregate в развёртываемые артефакты, просмотр каталога или IR, разрешение и закрепление зависимостей, публикация сущностей каталога, проверка корректности с помощью validate, проверка соглашений о публикации с помощью lint и обслуживание IDE — выполняется через подкоманду aggrega. В этом наборе глав описаны флаги, входные и выходные данные каждой подкоманды.
aggrega validate и aggrega lint — взаимодополняющие средства проверки с тремя одинаковыми областями: весь каталог, замыкание зависимостей сущности Release или одна сущность. aggrega validate проверяет корректность (схему, опоры, разрешение ссылок, extends, поддержку провайдером вида входных данных, а для сущности, выполняющей рендеринг, — изолированный рендеринг); aggrega lint проверяет соглашения о публикации (именование, соответствие каталогу категории, префиксы аннотаций и размер повышения версии). Ни одна из них не создаёт артефактов; используйте validate, чтобы ответить на вопрос «корректно ли это?», и lint, чтобы ответить на вопрос «соответствует ли это дисциплине публикации каталога?».
aggrega build следует принципу единой точки входа: сущность Release — единственный вход компиляции. aggrega build --release release.yaml читает указатели aggregate: и manifest: сущности Release, чтобы найти остальную топологию, и формирует вывод по границам в dist/: именованная граница рендерится в объявленный ею directory: или, если она его не объявляет, в dist/boundaries/<boundary-name>/; сущность Release, которая объявляет components: верхнего уровня вместо именованных границ, рендерится без вложенности прямо в dist/. Каждый компонент топологии должен принадлежать одной из этих границ, а компонент, не входящий ни в одну из них, останавливает сборку: компонент попадает в границу либо будучи названным в components: этой границы — под тем идентификатором, который он получает после выравнивания вложенных Aggregates, — либо находясь внутри вложенного Aggregate, который граница подключает через aggregates:. Компонент, не попавший в границу ни тем, ни другим способом, рендерился бы вне всех границ, объявленных в Release, и ниоткуда не получил бы место вывода, волну синхронизации, аннотации и infra: для отдельного компонента, поэтому сборка останавливается и называет компонент, а не выпускает артефакты, к которым конфигурация границ Release так и не была применена. То же отношение проверяется и со стороны Release: запись границы, называющая компонент, которого нет в топологии, ничего не настраивает, поэтому она тоже останавливает сборку, и диагностика сообщает идентификатор, к которому обращалась запись. aggrega pull так же принимает Release на вход; aggrega inspect принимает любую сущность — имя в каталоге, файл сущности, ссылку на реестр или Release; aggrega push принимает сущность каталога; aggrega validate и aggrega lint принимают сущность каталога, Release (через --release) или весь каталог; aggrega serve работает как долгоживущий процесс. На странице глобальных флагов описаны флаги, общие для всех подкоманд.
Что выпуск может изменить в командах, флагах и инструментах ассистента — и чего патч-выпуск никогда не меняет, — описано в разделе Совместимость.
Справочник по командам
aggrega build— основная команда компиляции. Читает указатель на Release, разрешает Aggregate и Manifest, на которые он ссылается, и выдаёт скомпилированные артефакты для каждой границы.aggrega inspect— удобочитаемое представление любой сущности: сущности каталога по имени, файла сущности по пути, опубликованной сущности, прочитанной прямо из её реестра, или полностью разрешённой сущности Release, граф IR которой--ir-graphзаписывает в формате JSON, а замыкание зависимостей которой выводит--closure.aggrega pull— разрешает зависимости Release и записывает lock-файл для каждого Release, закрепляющий каждую зависимость; кэширует сущности каталога и исходные артефакты.aggrega push— публикует сущность каталога в реестр OCI, при необходимости подписывая её во время публикации.aggrega sign— подписывает один или несколько уже опубликованных артефактов и прикрепляет каждую подпись как OCI referrer.aggrega auth token— интерактивно получает токен идентификации OIDC и выводит его в stdout, чтобы выполнить одну аутентификацию для пакета бесключевых подписей.aggrega registry— управляет реестрами, известными рабочему пространству, и их политикой доверия к подписям: добавляет, перечисляет и удаляет записи, а также строит локальный индекс для поиска по метаданным опубликованного каталога с помощьюregistry update.aggrega search— ищет в локальном индексе настроенных реестров опубликованные сущности каталога и устанавливаемые плагины CLI по произвольному текстовому запросу и необязательным фасетным фильтрам.aggrega validate— проверяет корректность (схема, столпы, разрешение ссылок,extends, поддержка видов входных данных, изолированный рендеринг) по всему каталогу, замыканию зависимостей Release (--release) или одной сущности.aggrega lint— проверяет соглашения о публикации по всему каталогу, замыканию зависимостей Release (--release) или одной сущности;--pre-publishдобавляет учитывающую реестр проверку повышения версии.aggrega serve— долго работающий демон «компилятор как сервис» (JSON-RPC через stdin/stdout) для интеграции с IDE.aggrega version— выводит версию CLI;-o jsonвыдаёт машиночитаемый объект.aggrega get-schema— выводит каноническую JSON Schema для вида сущности или контракта;--listперечисляет все виды. Это авторитетная форма, по которой следует писать файл.aggrega scaffold— выводит начальный документ для вида сущности, построенный по схеме этого вида: обязательные поля, где фиксированные заполнены, а везде, где нужно значение, стоит заполнитель. При создании черновика файл не записывается; перенаправьте вывод туда, куда нужно. С--exampleкоманда вместо этого записывает один из готовых к запуску примеров документации в новый каталог, а--example --listперечисляет их.aggrega mcp— запускает сервер Model Context Protocol через стандартный ввод и вывод или через HTTP, чтобы клиент с поддержкой MCP стал помощником в написании, знающим Aggrega. См. Написание файлов Aggrega.aggrega skills— устанавливает навык, который учит AI-ассистента устанавливать и использовать Aggrega, в папку навыков этого ассистента — для одного проекта или, с--global, для всех ваших проектов.aggrega cache— просмотр и обслуживание кэшей на диске: вывод их содержимого, освобождение записей кэша артефактов, на которые не ссылается ни один lock-файл, сокращение кэша скомпилированных модулей до ограничения размера или полная очистка всех кэшей.aggrega config— просмотр и управление конфигурацией, которую читает Aggrega: показ действующих настроек и того, какой уровень определил каждую из них, создание рабочей конфигурации и закрепление критичных для сборки настроек в рабочем пространстве.aggrega deprecate— прикрепление подписанной отметки об устаревании к уже опубликованному артефакту.aggrega edit-document— применение к документу одной ограниченной структурированной правки с сохранением каждого байта, который она не затрагивает.aggrega explain— объяснение условия остановки, которое обозначает код.aggrega import— преобразование стороннего описания источника в черновые файлы для написания Aggrega.aggrega login— аутентификация в реестре OCI и сохранение учётных данных, которые предъявляютpush,pullиlint --pre-publish.aggrega logout— удаление сохранённых учётных данных реестра.aggrega pin— запись закреплений содержимого для внешних входных данных сущности вentity.lockрядом с ней.aggrega plugin— вывод списка плагинов Wasm, которые может разрешить CLI, добавление или удаление привязки рабочего пространства и проверка гостевого модуля перед его публикацией.aggrega push-artifact— публикация самостоятельного артефакта данных, например пакета документации, в реестр OCI в его пространство имёнdocs/.- Конфигурация — в каком файле должна находиться настройка и как объединяются слои. Начните отсюда: страница открывается двумя файлами, которые нужны большинству проектов, а механизмы, к которым прибегает более крупный проект, описывает после них.
- Глобальные флаги — флаги, общие для подкоманд (корень рабочего пространства, глобальный файл конфигурации, цветной и простой доступный вывод и автономный режим). Автономный режим также доступен как параметр конфигурации и как переменная окружения — см. Конфигурация, схему конфигурации и переменные окружения.
- Граница рабочего пространства — что находится внутри рабочего пространства, как символическая ссылка, ведущая за его пределы, влияет на каждый вид пути, какие пути намеренно выходят наружу и что делать, если путь отклонён.
| Команда | Описание |
|---|---|
aggrega auth | Управление идентичностью для подписи |
aggrega build | Компиляция Aggregate и Release в нативные для провайдера артефакты в dist/ в корне рабочего пространства |
aggrega cache | Инспекция и обслуживание кэшей на диске |
aggrega config | Инспекция и управление конфигурацией рабочего пространства |
aggrega deprecate | Прикрепление подписанной отметки об устаревании к уже опубликованному артефакту |
aggrega edit-document | Применение одной ограниченной структурной правки к документу с сохранением каждого байта, который она не затрагивает |
aggrega explain | Объяснение условия остановки, которое обозначает код |
aggrega get-schema | Вывод JSON Schema для вида сущности или контракта |
aggrega import | Преобразование стороннего описания источника в черновые файлы Aggrega |
aggrega inspect | Инспекция сущности каталога по имени, файла сущности по пути или опубликованной сущности по ссылке на реестр |
aggrega lint | Проверка соглашений о публикации каталога по всему каталогу, Release или одной сущности |
aggrega login | Аутентификация в реестре OCI и сохранение учётных данных |
aggrega logout | Удаление сохранённых учётных данных реестра |
aggrega mcp | Запуск сервера Model Context Protocol через стандартный ввод и вывод или через HTTP для интеграции с ИИ-помощником |
aggrega pin | Запись закреплений содержимого для внешних входных данных сущности в entity.lock рядом с ней |
aggrega plugin | Инспекция плагинов Wasm, которые может разрешить CLI |
aggrega pull | Разрешение зависимостей каталога и источников в кэш и запись lock-файла для Release |
aggrega push | Упаковка и публикация сущности каталога в реестр OCI |
aggrega push-artifact | Публикация отдельного артефакта данных (например, пакета документации) в реестр OCI |
aggrega registry | Управление реестрами и их политикой доверия к подписям |
aggrega scaffold | Создание начального документа для вида сущности или запись готового к запуску примера в новый каталог |
aggrega search | Поиск в локальном индексе настроенных реестров |
aggrega serve | Работа в качестве долго работающего «компилятора как сервиса» через JSON-RPC 2.0 на stdin/stdout |
aggrega sign | Подпись одного или нескольких уже опубликованных артефактов и прикрепление их подписей |
aggrega skills | Установить навык Aggrega в AI-ассистента |
aggrega validate | Проверка корректности по всему каталогу, Release или одной сущности |
aggrega version | Вывод версии CLI aggrega |
Позиционные аргументы и код завершения
Каждая команда отклоняет позиционный аргумент, который ей не нужен, и сообщает об этом ненулевым кодом завершения, а не завершается так, будто вызов был корректным. Это правило распространяется и на команды, которые существуют только для группировки подкоманд: в них опечатка в имени подкоманды приходит как нераспознанный позиционный аргумент, поэтому выводится справка команды, а код завершения ненулевой. Так опечатка в скрипте приводит к явной ошибке, а не выглядит как успешный запуск. aggrega, вызванный с нераспознанной командой, ведёт себя так же и дополнительно называет наиболее похожую команду, если такая достаточно близка.
Нераспознанная команда также подсказывает, как найти плагин CLI с таким именем. Ответ берётся из локального индекса реестра по умолчанию, который строит aggrega registry update и читает aggrega search, поэтому он возвращается сразу, а слово с опечаткой никогда не отправляется в реестр — ни в режиме онлайн, ни офлайн. Если в индексе есть плагин CLI с таким именем, сообщение называет команду aggrega plugin add cli <name>, которая его устанавливает. Если в индексе такого нет, оно называет поиск, который его ищет, aggrega search <name> --kind plugin --plugin-type cli. Если индекс ещё не построен, оно называет aggrega plugin add cli <name>, которая ищет плагин по этому имени в реестре и отказывает, если ни один не опубликован. Любая из этих команд содержит имя, при необходимости заключённое в кавычки для оболочки.
Там, где позиционные аргументы имеют смысл, справочная страница каждой команды описывает, что она принимает. Установленный плагин CLI — намеренное исключение: его команда сама разбирает аргументы, поэтому весь вектор аргументов передаётся плагину, который единолично разбирает свои аргументы, а вызов возвращает собственный код завершения плагина.
Ход выполнения и как долго команда ждёт реестр
Команда, которая ждёт, сообщает, чего она ждёт. Всякий раз, когда команда ждёт реестр, загрузку или первую компиляцию плагина, она показывает этот шаг в стандартном потоке ошибок, так же как aggrega build и aggrega pull показывают свои: в терминале — строка с названием шага, вращающимся индикатором и временем, которое шаг уже занял, отмеченная галочкой после завершения шага и оставленная без галочки, если шаг завершился неудачей; в терминале, который не может перерисовывать строку на месте, или с --plain — по одной строке на шаг в момент его завершения, с его временем. Если стандартный поток ошибок не является терминалом, ничего не показывается, и то, что команда выводит в стандартный поток вывода, ни в каком случае не меняется. Шаг показывается только пока команда действительно его ждёт, поэтому запуск, обслуженный из кэша, не показывает ничего, а компиляция плагина показывается только тогда, когда она длится достаточно долго, чтобы быть настоящей компиляцией, а не взятой из кэша.
Команды, которые показывают свои шаги таким образом, помимо команды каждого установленного плагина CLI:
aggrega config init, aggrega deprecate, aggrega explain, aggrega import, aggrega inspect, aggrega lint, aggrega plugin add, aggrega plugin gen-catalog, aggrega plugin run-local, aggrega plugin sync, aggrega push, aggrega push-artifact, aggrega registry add, aggrega scaffold, aggrega sign, aggrega validate
Ни один запрос не ждёт сервер бесконечно. Запрос ждёт не более 30 секунд, пока сервер начнёт ответ после того, как запрос отправлен полностью, и не более 30 секунд следующую часть ответа, который уже поступает. Сервер, заставляющий запрос ждать дольше, отклоняется с кодом E0376, который называет сервер и время ожидания. Ограничено только ожидание: загрузка или выгрузка, которая продолжает продвигаться, длится столько, сколько нужно. Helm-чарт, который source: сущности Recipe получает по HTTPS, подчиняется только первому из двух ожиданий, а об истечении его срока сообщается собственными словами сетевой библиотеки, а не под кодом E0376. Запрос, который команда и так повторяет по тайм-ауту, — чтение во время aggrega registry update, запись во время публикации — повторяется до того, как будет сообщено об отказе.
Обход полного списка репозиториев реестра завершается в течение пяти минут. Некоторые реестры собирают все хранящиеся в них репозитории ещё до того, как ответить на запрос списка, поэтому каждую страницу списка ждут столько, сколько может длиться обход, а не 30 секунд; список, который не завершился через пять минут, останавливается и отклоняется с кодом E0377. aggrega plugin add обходит список, только когда ни один плагин не носит в точности то имя, которое ему передано, чтобы найти плагин, имя которого его содержит, поэтому если указать точное имя плагина, ожидания обхода не возникает никогда.
Реестр, который просит замедлиться, команда пережидает, пока он не будет просить об этом пять минут без перерыва. Команда ждёт столько, сколько просит такой реестр, отправляет ему меньше запросов одновременно и показывает ожидание вместе с остальным ходом выполнения; реестр, который в течение пяти минут не отвечает ничем, кроме «помедленнее», отклоняется с кодом E0378. Как это происходит, описано в разделе Реестр, который просит замедлиться.
Все три ограничения фиксированы; нет настройки, которая бы их меняла.
Вводимые пути и граница рабочего пространства
Путь, который вы вводите в командной строке, — --release, --catalog, --output-dir, файл для проверки, линтинга, закрепления или публикации, --workspace-root — используется там, куда он ведёт, внутри рабочего пространства или вне его, через любую ссылку на пути. То, что команда затем читает и записывает по собственной инициативе, ограничено рабочим пространством, кто бы её ни запускал: она не читает файлы конфигурации рабочего пространства, документ каталога, документ рядом с сущностью Release или lock-файл сущности Release через ссылку, ведущую за пределы рабочего пространства, не следует по пути, который сущность Release или Manifest выводит за его пределы, и не записывает свой вывод, свой lock-файл или свой кеш через такую ссылку. Каталог, который вы указываете вне рабочего пространства, ограничивается так же в отношении того, что находится внутри него, а сущность Release, указанная вне рабочего пространства, достигает только файлов в собственном каталоге. aggrega edit-document — единственная команда, у которой ограничивается и вводимый путь: она редактирует только документ, содержащийся в рабочем пространстве. Граница рабочего пространства описывает это правило, пути, которые намеренно выходят за его пределы, и способ устранения каждого отказа.
Поиск по индексу каталога
aggrega search [query] ищет опубликованные сущности во всех реестрах, известных рабочему пространству. Необязательный [query] — это подстрока без учёта регистра, которая сопоставляется с именем и описанием каждой сущности. Фильтры по признакам сужают набор результатов:
--kindограничивает поиск одним или несколькими видами сущностей (component,feature,recipe,featurerecipe,workload,plugin); флаг можно повторять, регистр не учитывается, а виды объединяются по ИЛИ.-l/--selectorфильтрует по меткам каталога сущности. Категория — это метка, а не отдельный флаг:-l component.aggrega.ai/category=datastore.--capabilityи--plugin-typeфильтруют плагины по объявленной возможности или типу сокета;--capabilityможно повторять, значения объединяются по ИЛИ.--registryограничивает поиск одним реестром по хосту или понятному псевдониму; по умолчанию поиск идёт по всем настроенным реестрам.--limitограничивает число результатов.-o/--outputвыбирает формат вывода:table(по умолчанию, для чтения человеком),json(массив для машинной обработки) илиnames(только идентификаторы, по одному на строку).
Поиск всегда читает локальный индекс — офлайн-снимок, который строит и обновляет aggrega registry update. Команда не обращается к сети и ничего не загружает по запросу. Если индекса нет, команда завершается с ошибкой и предлагает сначала выполнить aggrega registry update. При каждом запуске в стандартный поток ошибок выводится строка о свежести «последнее обновление» для каждого реестра, поэтому вывод json и names в стандартный поток вывода остаётся чистым для использования в скриптах.
Автодополнение в оболочке
aggrega completion <shell> выводит в stdout скрипт автодополнения для bash, zsh, fish или powershell. Скрипт генерируется из актуального дерева команд CLI в момент запуска, поэтому он всегда отражает команды и флаги того бинарного файла, который его создал, — нет статического файла, который нужно было бы перегенерировать по мере развития CLI.
Чтобы попробовать автодополнение в текущем сеансе, ничего не устанавливая, загрузите скрипт напрямую:
source <(aggrega completion bash)Чтобы установить автодополнение постоянно, запишите скрипт в расположение, которое ваша оболочка читает при запуске.
bash
Автодополнение в Bash зависит от пакета bash-completion; установите его через менеджер пакетов вашей ОС, если он ещё не установлен.
# Linuxaggrega completion bash > /etc/bash_completion.d/aggrega
# macOS (Homebrew)aggrega completion bash > $(brew --prefix)/etc/bash_completion.d/aggregazsh
Если автодополнение в вашей оболочке ещё не включено, включите его один раз:
echo "autoload -U compinit; compinit" >> ~/.zshrcЗатем запишите скрипт автодополнения в каталог из вашего fpath:
# Linuxaggrega completion zsh > "${fpath[1]}/_aggrega"
# macOS (Homebrew)aggrega completion zsh > $(brew --prefix)/share/zsh/site-functions/_aggregafish
aggrega completion fish > ~/.config/fish/completions/aggrega.fishpowershell
Добавьте сгенерированный скрипт в конец вашего профиля PowerShell, чтобы он загружался в каждом сеансе:
aggrega completion powershell >> $PROFILEЗапустите новую оболочку, чтобы установленное автодополнение вступило в силу.