Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Обзор 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.

Чтобы попробовать автодополнение в текущем сеансе, ничего не устанавливая, загрузите скрипт напрямую:

Terminal window
source <(aggrega completion bash)

Чтобы установить автодополнение постоянно, запишите скрипт в расположение, которое ваша оболочка читает при запуске.

bash

Автодополнение в Bash зависит от пакета bash-completion; установите его через менеджер пакетов вашей ОС, если он ещё не установлен.

Terminal window
# Linux
aggrega completion bash > /etc/bash_completion.d/aggrega
# macOS (Homebrew)
aggrega completion bash > $(brew --prefix)/etc/bash_completion.d/aggrega

zsh

Если автодополнение в вашей оболочке ещё не включено, включите его один раз:

Terminal window
echo "autoload -U compinit; compinit" >> ~/.zshrc

Затем запишите скрипт автодополнения в каталог из вашего fpath:

Terminal window
# Linux
aggrega completion zsh > "${fpath[1]}/_aggrega"
# macOS (Homebrew)
aggrega completion zsh > $(brew --prefix)/share/zsh/site-functions/_aggrega

fish

Terminal window
aggrega completion fish > ~/.config/fish/completions/aggrega.fish

powershell

Добавьте сгенерированный скрипт в конец вашего профиля PowerShell, чтобы он загружался в каждом сеансе:

Terminal window
aggrega completion powershell >> $PROFILE

Запустите новую оболочку, чтобы установленное автодополнение вступило в силу.