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

Статус языка

Эта страница — канонический справочник о том, какие возможности Aggrega можно использовать уже сегодня, какие задокументированы, но пока не обрабатываются компилятором, и какие запланированы на будущие итерации. Она дополняет главы по отдельным областям, собирая в одном месте сведения о готовности возможностей во всём языке.

К этой странице обращаются две группы читателей. Начинающие авторы сверяются со страницей, прежде чем писать с использованием незнакомой возможности, чтобы убедиться, что она уже сегодня даёт отрендеренный результат. Ищущие справку обращаются к странице, когда используемая ими возможность ведёт себя неожиданно: например, если YAML проходит валидацию, но никакого результата не создаётся, первым делом стоит проверить здесь статус этой возможности. Постоянные читатели также обращаются к странице, чтобы узнать, какие возможности сменили статус с момента последнего прочтения. Главы по отдельным областям и справочники по сущностям описывают, как возможность должна работать; эта страница описывает, работает ли она уже.

Классификация статусов

Каждый элемент языка на этой странице имеет одну из четырёх меток статуса:

  • available. Схема принимает элемент; компилятор его обрабатывает; поведение соответствует документированному контракту. Авторы, использующие элемент со статусом available, получают документированный контракт.

  • accepted but inert. Схема принимает элемент — написанное с его использованием проходит валидацию, — но компилятор пока на него не реагирует. Использование элемента со статусом accepted but inert даёт синтаксически корректную сборку без какого-либо эффекта этого элемента в отрендеренном результате; компилятор может выдать предупреждение с названием неактивного элемента (рекомендуемый подход), либо некоторые текущие элементы молча пропускаются без предупреждения. Конкретное поведение указано в записях разделов ниже.

  • accepted but blocked. Схема принимает элемент — написанное с его использованием проходит валидацию, — но компилятор останавливает сборку вместо рендеринга. Использование элемента со статусом accepted but blocked завершается ошибкой при рендеринге с явным сообщением о том, что следует написать вместо этого. Блокировка может быть постоянной, если написанное представляет собой неоднозначность, которую компилятор не будет разрешать за вас, поскольку выбор одного толкования за вас может привести к поставке того, о чём вы не просили; либо она может действовать лишь до тех пор, пока не будет реализовано поведение, стоящее за элементом. В обоих случаях метка обещает одно и то же: схема элемент принимает, сборка его отвергает, а ошибка сообщает, как это исправить.

  • planned. Элемент задокументирован в соответствии с проектом, но пока его не принимают ни схема, ни компилятор. Использование элемента со статусом planned завершается ошибкой при валидации схемы. Страница показывает запланированные элементы, чтобы авторы могли заранее учесть их отсутствие, а не обнаружить пробел во время сборки.

Метки статуса оцениваются относительно текущей версии компилятора. Элементы, находящиеся в активной разработке, могут переходить между метками; записи разделов описывают план перехода, если он известен.

Виды входных данных Recipe

Сущность Recipe составляет свой результат из трёх видов входных данных — получаемых из источника (sourced), синтезируемых (synthesized) и артефактов (artifacts), — описанных в 16-recipe-input-composition.md. Статус по видам входных данных:

  • source: + valuesMapping: (sourced) — available. Компилятор разрешает URI source:, вычисляет шаблон valuesMapping (встроенный, файловый $import: или библиотечный $import:) и передаёт результат целевому провайдеру для рендеринга. Используется провайдерами helm, helm-chart, compose, terraform и cloudformation.

  • workload: (synthesized) — available. Сущность Recipe объявляет workload: либо встроенно (блочный скаляр с YAML сущности Workload), либо через $import: (путь к файлу). Компилятор разбирает шаблонизированную сущность Workload, проверяет её по встроенной схеме Workload и передаёт её синтезатору рабочих нагрузок целевого провайдера. Используется провайдерами helm и compose. Провайдер helm-chart явно перенаправляет авторов к провайдеру helm для синтезируемых манифестов K8s. Сущность Recipe, объявляющая workload: для провайдера, который не реализует синтез рабочих нагрузок, останавливается при рендеринге с CATALOG_ERROR.

  • artifacts: (артефакты) — available. Это поле представляет собой карту именованных записей; каждая запись задаётся inline или загружается через $import: на уровне записи. Записи вычисляются после разбора сущности Workload и разрешения источника, поэтому им доступен полный контекст шаблонов, включая .workload и .source. В документы, содержащие метаданные, в них подмешивается информация о происхождении в metadata.labels и metadata.annotations (небезопасные по набору символов ключи — recipe-uri, boundary-path, sync-wave — в виде аннотаций, с тем же разделением, что применяют провайдеры helm), а сами записи выводятся отдельными файлами рядом с выходными данными сущности Recipe, полученными рендерингом источника или синтезом рабочей нагрузки. Provider dispatch (диспетчеризация по провайдерам): плоский провайдер helm выводит отдельные файлы в каталог, названный по компоненту, который их объявил, внутри выходного каталога границы, поскольку ключ задаёт имя файла, но ничего не говорит о том, какой компонент его записал; провайдер compose направляет свои выходные данные через слияние на уровне сущности Release; провайдер helm-chart вычисляет каждую запись с разделителями Aggrega [[ ]], чтобы синтаксис Helm {{ }} в том же файле сохранился для последующего рендеринга, а затем размещает каждую запись в зависимости от формы, в которой она задана: запись, загруженную через $import:, — в boundaries/<bp>/charts/<nodeID>/templates/<authored-key> (файлы пакета вкладываются под этот ключ) рядом с собственными шаблонами исходного чарта, а запись со встроенным содержимым — в boundaries/<bp>/charts/<nodeID>/<authored-key>, в корень чарта, где собственные шаблоны чарта читают её через .Files.Get / .Files.Glob; провайдер terraform записывает каждую запись дословно в собственный каталог компонента в дереве modules/ границы; провайдер cloudformation объединяет каждую запись — фрагмент стека — в единый стек, собираемый для этого выходного каталога. Коллизии имён файлов между источниками разных видов входных данных (вывод рендеринга источника, синтеза рабочей нагрузки или артефактов) обнаруживаются во время рендеринга детектором межисточниковых коллизий и приводят к ошибке CATALOG_ERROR с перечислением всех участников.

Поверхность написания сущности Recipe и правила композиции видов входных данных описаны в entities/recipe.md; правила формы сущности Recipe — в errors/fatal-halts.md; матрица по провайдерам — в разделе Providers ниже.

Языки сопоставления

Сущности Recipes (и FeatureRecipes) привязываются к единственному полю сопоставления, которое переводит контекст Aggrega в словарь значений, потребляемый нижележащим провайдером. Поле valuesMapping: поддерживает три режима написания, выбираемых по форме содержимого:

  • valuesMapping: — режимы 1–3 доступны. Режим 1: встроенный шаблон Go (блочный скаляр). Режим 2: файловый $import: (отображение, содержащее только $import: с путём к локальному файлу). Режим 3: библиотечный $import: (отображение, содержащее только $import: со ссылкой на идентичность по голому имени на запись MappingLibrary, <Library>#/mappings/<entry>, необязательно с нижней границей :<version>). Компилятор выбирает режим по форме содержимого: блочный скаляр — режим 1, $import: с путём к файлу — режим 2, $import: со ссылкой на библиотеку по голому имени — режим 3. Во всех трёх режимах разрешённый шаблон Go вычисляется относительно контекста шаблонов сущности Recipe во время сопоставления значений (библиотека вспомогательных функций Sprig зарегистрирована заранее); в режиме 3 запись разрешается по локальному каталогу и всем библиотекам, закреплённым в lock-файле, а ссылка, содержащая хост, отклоняется. Механизм выбора режима и разобранные примеры см. в entities/recipe.md, раздел «Поле valuesMapping — три режима написания».

Описание поверхности написания сущности Recipe и устройства языка сопоставления см. в entities/recipe.md, а описание библиотечной сущности, на которой основан режим 3, — в entities/mappinglibrary.md.

Синтаксис inject

Блок inject: имеет один синтаксис в любом месте размещения — в собственном inject компонента, в соединении uses и в присоединении.

  • Список записей для каждого механизма ([{in: ..., from: ...}], [{in: ..., value: ...}]) — доступно. Каждый механизм доставки — это список; каждая запись задаёт свой локальный идентификатор (имя переменной окружения, путь к файлу, флаг аргумента) через in: и содержит ровно одно из двух: from: (ссылку на ключ provides) или value: (литеральную строку). Механизм, записанный как отображение, а не как список, или запись, содержащая оба ключевых слова, останавливает сборку на оболочке документа Aggregate с указанием пути.

  • value: только в собственном inject компонента. Литерал относится к собственному inject компонента, который его доставляет. В соединении uses значение value: останавливает сборку, как описано в An inject: entry on a connection carries a literal (Запись в соединении содержит литерал), а в собственном inject присоединения оно тоже останавливает сборку, как описано в An inject: entry on an attached Feature carries a literal (Запись в присоединённой сущности Feature содержит литерал): оба доставляют только ключи, которые публикует другая сущность, указанные через from:.

Полную спецификацию контракта внедрения (Injection Contract), включая семантику двухсостоянийного контекста, правила коллизий ключей и разобранные примеры, см. в vocabulary/topology-triad.md.

Движок шаблонов

Движок шаблонов Go в Aggrega вычисляет шаблоны сущностей Recipe и FeatureRecipe относительно контекста шаблонов на той фазе для каждого места, которую документирует Матрица раскрытия шаблонов. Библиотека вспомогательных функций Sprig предварительно регистрируется вместе с собственными функциями Aggrega на каждой поверхности, которую вычисляет рендерер, за одним исключением: при разрешении структурированной координаты source: регистрируются только функции Aggrega — там доступны optional и capitalizedWords, а функции Sprig недоступны, поэтому вызов Sprig в поле source: или в записи locals: сущности, содержащей структурированный source:, приводит к остановке на этапе разбора. См. errors/fatal-halts.md, где этой поверхности отведён отдельный раздел. Вычисление, разбор и интеграция со Sprig доступны уже сейчас.

Поведение при отсутствующем ключе — допускается в шаблонах значений; строгий missingkey=error в шаблонах путей, в проверках и в координате source:. Шаблоны значений вычисляются с опцией Go missingkey=zero, поэтому шаблон, ссылающийся на несвязанный ключ (например, .values.unset_field), не вызывает ошибку, а чтение ничего не выводит. Идиомы каталогов вроде {{ .values.optional_field | default "fallback" }} продолжают работать при этой политике, поскольку незаданное значение считается пустым для default. Шаблоны путей (directory: / subDirectory: на границах сущностей Release) вычисляются с missingkey=error относительно закрытого списка разрешённых ключей: незаметные сбои путей порождают некорректную структуру файловой системы, которую операторы обнаруживают только после сборки, а строгость позволяет поймать ошибку раньше. Ещё две поверхности следуют той же строгой политике по той же причине: пустой результат там дал бы неверный вердикт или неверную фиксацию версии, а не поле, которое автор может перечитать. Это запись assertions: в сущности Component, Feature, Recipe или FeatureRecipe и шаблонизированные поля структурированного блока source: в сущности Recipe или FeatureRecipe. errors/fatal-halts.md описывает политику каждой поверхности по отдельности и приводит формы с учётом наличия ключа, которые работают при строгой политике.

Значение по умолчанию с учётом наличия ключа через optional. Когда автору сущности Recipe нужно отличить «ключ отсутствует» от «ключ присутствует с нулевым / пустым / ложным значением» — различие, которое default из Sprig провести не может, — рендерер предоставляет вспомогательную функцию optional: {{ optional .infra "replicas" 1 }} возвращает заданное автором infra.replicas (включая заданный 0), если оно есть, и возвращает 1 только при отсутствии ключа. Полную семантику см. в templates/sprig-functions.md.

Свёртка имён через capitalizedWords. Если цель допускает в именах, по которым она адресует ресурсы, только буквы и цифры, {{ capitalizedWords .context.instance_id }} читает идентификатор как слова, разделённые любыми символами вне этого алфавита, и делает заглавной первую букву каждого слова, так что payments-db даёт PaymentsDb. Свёртка удаляет все разделители, поэтому два идентификатора, различающиеся только пунктуацией, дают одно имя; сборка, которая создала бы два ресурса под одним именем, останавливается и называет оба идентификатора. Полную семантику см. в templates/sprig-functions.md.

Соблюдение контракта параметров на уровне объявлений. Обязательные параметры, которые сущность Release не предоставляет, вызывают явные ошибки на уровне контракта параметров — первого, что проверяет разрешение, — с указанием происхождения file:line, называющим параметр и контракт. Нарушения типов и ограничений проявляются так же. Это и есть основное соблюдение требований к отсутствующим ключам: типизация проверяется там, где выражено намерение разработчика (в объявлении parameters: сущности Aggregate), а не позже, при вычислении шаблонов. См. entities/aggregate.md §«Typed parameter contracts».

Единая грамматика объявления parameters: сущности Aggregate. Каждый слот параметра задаётся как объект типизированного контракта (key: { type: <type>, default: <value>, ... }). Сокращённая скалярная запись (key: <value>) отклоняется на оболочке документа Aggregate с ошибкой, которая называет параметр и сообщает, что ожидался объект. Словарь типизированного контракта делает семантику type:, required: и ограничений явной на уровне объявлений; заполнение в сущности Release по-прежнему использует скалярные значения согласно объявленному в контракте типу.

Матрицу вычисления для каждого места шаблона см. в templates/expansion-matrix.md, а обзор шаблонизации — в 05-templates.md.

Фазы конвейера компиляции

Конвейер компиляции Aggrega описан в ../architecture/10-compilation-pipeline.md. Статус по фазам:

  • Разрешение, построение топологии, финализация графа, статический анализ и рендеринг — доступны.
  • Inject-сопоставление (перехват перед рендерингом injectMapping) и все подэтапы базового рендеринга — публикация locals, сопоставление значений, синтез рабочей нагрузки, вычисление артефактов, рендеринг провайдером, рендеринг функций и генерация ресурсов для учётных данных через сущности FeatureRecipe — доступны.
  • Конвейер плагинов (выполнение Wasm через pipeline:) — доступен. Если сущность Recipe или FeatureRecipe объявляет непустые шаги pipeline:, каждый шаг выполняется в объявленном порядке: компилятор вызывает указанный в шаге Wasm-плагин для отрендеренного вывода, применяет возвращённые операции JSON Patch к адресуемым документам и порождает побочные эффекты шага. Шаг, у которого условие when: даёт ложное значение, пропускается как сквозной, и набор документов остаётся неизменным. Авторы, которым нужны мутации в стиле JSONPatch (внедрение sidecar Envoy, VolumeMount для секрета и т. п.), реализуют их через этот механизм.

Providers

Стандартная библиотека Aggrega поставляет пять провайдеров рендеринга — helm, helm-chart, compose, terraform и cloudformation. Статус по провайдерам:

  • helm — доступен. Поставляются оба режима: режим с источником (рендеринг Helm-чарта через Helm SDK) и синтезированный режим (Workload → объект контроллера, выбранный по form сущности Workload, — Deployment, StatefulSet, DaemonSet, Job или CronJob, — а также Services и PVC).
  • helm-chart — доступен. Поставляется режим с источником (композиция umbrella-чарта). Синтезированный вид входных данных к этому провайдеру неприменим; авторы, которым нужен синтез манифестов K8s, используют провайдер helm с workload:.
  • compose — доступен. Поставляются оба режима: режим с источником (наложение фрагментов compose) и синтезированный режим (Workload → сервис compose + тома + сети). Вывод docker-compose.yaml для каждой границы собирается компоновщиком уровня сущности Release.
  • terraform — доступен. Поставляются и режим с источником, и артефакты; каждая граница получает одну корневую конфигурацию aggrega.modules.tf, объявляющую каждый компонент блоком module, файлы которого лежат в собственном каталоге компонента в modules/. Синтезированный вид входных данных к этому провайдеру неприменим.
  • cloudformation — доступен. Поставляются и режим с источником, и артефакты (фрагменты стека); все компоненты, рендерящиеся в один выходной каталог, собираются в один шаблон стека, выводимый как чистый JSON. Синтезированный вид входных данных к этому провайдеру неприменим.

Рендеринг сущностей Provider выполняет сущность Plugin с pluginType: provider; описание разработки сущности Plugin для рендеринга провайдеров см. в entities/plugin.md, а справочные страницы по каждому провайдеру — в 06-providers.md.

Расширение на основе аннотаций

Сущности Manifests содержат раздел привязок features.annotations:, который сопоставляет ключи аннотаций с типами Feature, а также таблицу маршрутизации, сгруппированную по опорам (maps.infra / maps.values), где указано, какие свойства схемы Feature может заполнять каждая привязка. Описано в entities/manifest.md и providers/well-known-annotations.md; место в конвейере — в ../architecture/10-compilation-pipeline.md; механизмы на этапе загрузки каталога и на этапе inspect — в ../architecture/13-catalog-and-registry.md, §«Annotation-driven Feature expansion».

  • Привязки features.annotations в Manifest — доступно. Подэтап разрешения, отвечающий за расширение аннотаций, реализован полностью. Он обходит границы Release (снаружи внутрь) и подсистемы Aggregate (снаружи внутрь), вычисляет эффективный набор аннотаций для каждого компонента посредством каскада и переопределения с отказом через null как для значения целиком, так и для отдельного подключа, разбирает каждое значение аннотации как скаляр, структурированную карту или явный null, маршрутизирует каждый подключ через объявление maps привязки с контролем соответствия стороны и опоры (сторона Aggregate задействует maps.values; сторона Release задействует maps.infra), проверяет типы каждого листа по spec.schema целевой Feature и внедряет синтетические присоединения Feature, которые граф IR помечает как origin: annotation. Композиция между сторонами объединяет данные по опорам и по полям на этапе построения IR, причём явно заданное значение поля имеет приоритет; aggrega inspect выводит скобки происхождения для каждого листа. Этот путь защищают проверка целей привязок при загрузке каталога, линт пересечения опор схемы и линт пересечения карт привязок. Голый префикс aggrega.ai/ отклоняется при загрузке Manifest, если используется как ключ привязки, — этот префикс зарезервирован для собственных аннотаций платформы; привязки используют feature.aggrega.ai/ или собственный домен.

Сопоставление версий

Сущности Recipes и FeatureRecipes объявляют интерфейс Component или Feature, который они реализуют, с помощью ключевого слова implements:. implements: никогда не выбирает Recipe: выбор делает сопоставление в Manifest, а экземпляр, тип которого не покрыт ни одним сопоставлением, останавливает сборку с ошибкой, перечисляющей в качестве кандидатов сущности Recipes, чьё implements: может реализовать этот тип. implements: управляет проверкой того, что сущность Recipe каждой записи сопоставления в Manifest реализует сопоставленный тип или базовый тип, который этот тип расширяет через extends. Сопоставленный тип — это ключ записи, а для ключа components.type также тип каждого экземпляра компонента, которого ключ достигает в версии, не названной ключом (для ключа, записанного без версии, — каждого достигаемого экземпляра), причём в той версии, в которой сборка компилирует этот экземпляр: в версии, которую называет экземпляр, или, для экземпляра без версии, в наивысшей версии этой сущности Component, имеющейся в каталоге. Статус по формам:

  • Точная (core/api-server:1.0.0) — доступна. Сопоставленный тип должен иметь именно эту версию.
  • Диапазон, совместимый по мажорной версии (core/api-server:^1.0.0), — доступен. Форма с символом каретки — это ограничение SemVer (>=1.0.0, <2.0.0 для данного примера); версия сопоставленного типа должна ему удовлетворять.
  • Без версии (core/api-server) — доступна. Ей удовлетворяет любая версия типа.

Запись сопоставления, у сущности Recipe которой implements: не совпадает ни с сопоставленным типом, ни с каким-либо из его базовых типов, останавливает сборку с OPS_ERROR, называя запись, сущность Recipe и её значение implements:. Экземпляр компонента, которого ключ достигает в другой версии и версии которого не удовлетворяет implements: сущности Recipe, останавливает сборку с тем же OPS_ERROR, называя экземпляр, его тип — а для экземпляра без версии и версию, в которой он был скомпилирован, — ключ, сущность Recipe и её значение implements:. Форма с кареткой — каноническая форма написания для сопоставления, совместимого по мажорной версии.

См. vocabulary/inheritance-and-interface.md — об устройстве implements:, и entities/manifest.md — о структуре уровня сопоставления для каждой сущности Manifest.

Оболочка метаданных

Оболочки сущностей каталога содержат metadata.labels, metadata.annotations и (у сущности Release) metadata.environment. Статус по каждому полю:

Доступность metadata.labels и metadata.annotations — у семи видов. Эти поля содержат оболочки следующих сущностей: Component (метки обязательны, с обязательным ключом component.aggrega.ai/type, аннотации необязательны), Feature (оба поля необязательны), четыре вида библиотек SchemaLibrary, MappingLibrary, WorkloadLibrary и ArtifactLibrary (оба поля необязательны) и Aggregate (только метки, необязательны). Остальные сущности — Recipe, FeatureRecipe, Manifest, Release, Plugin — не принимают metadata.labels и metadata.annotations на уровне оболочки.

metadata.environment у сущности Release — обязательно. Схема сущности Release указывает environment как обязательное поле metadata; сборка проставляет его значение в выходных данных рендеринга как метку aggrega.ai/environment. Пять практических сценариев использования из раздела Environment Metadata (атрибуция затрат OTel/FinOps, фильтрация трассировок и журналов OTel, нацеливание операторов Kubernetes, разграничение многорегионального production-окружения, определение области соответствия требованиям) описаны в entities/release.md.

Порядок регистра имён полей, применяемый к ключам metadata, описан в 02-naming-conventions.md, а формы оболочек, которые каждая сущность принимает сегодня, — на справочных страницах отдельных сущностей.

Команды CLI

CLI Aggrega регистрирует конвейер сборки, а также средства интроспекции. Статус по командам:

  • aggrega build — доступна. Читает файл Release, разрешает Aggregate и Manifest, запускает конвейер компиляции и записывает отрендеренные артефакты в выходные каталоги границ. Если lock-файл присутствует, команда сверяет с ним зависимости; если он отсутствует, она останавливается с требованием выполнить pull либо сначала заполняет его, если это запрошено через --auto-pull или auto_pull.
  • aggrega inspect — доступна. Исследует сущность каталога, файл сущности, сущность, опубликованную в реестре, или Release и сообщает её разрешённую форму. См. cli/aggrega-inspect.md.
  • aggrega pull — доступна. Разрешает все зависимости сущности Release и записывает lock-файл для каждого Release, закрепляющий каждую сущность каталога и исходный артефакт за версией и дайджестом содержимого, а каждый внешний вход, запрашиваемый при рендеринге Release, — за дайджестом содержимого; кэширует загруженное содержимое в .aggrega/cache. --verify сверяет существующий lock-файл с текущим состоянием. См. cli/aggrega-pull.md.
  • aggrega push — доступна. Публикует сущность каталога в реестр OCI; aggrega push --list-kinds сообщает, какие виды сущностей она принимает. См. cli/aggrega-push.md.
  • aggrega lint — доступна. Применяет правила дисциплины публикации с уровнем серьёзности warn ко всему каталогу, к замыканию зависимостей сущности Release или к одной сущности; для одной сущности --pre-publish добавляет проверку повышения версии относительно текущей опубликованной версии сущности, а несоответствие останавливает выполнение. Правила поставляются в виде подключаемого по выбору плагина Wasm. См. cli/aggrega-lint.md.
  • aggrega serve — доступна. Долгоживущий демон «компилятор как сервис», работающий по JSON-RPC 2.0 через stdin/stdout, для интеграции с редакторами и IDE. Обслуживаемые им методы см. в cli/aggrega-serve.md.
  • aggrega version — доступна. Выводит версию CLI; -o json выдаёт машиночитаемый объект версии.
  • aggrega validate — доступна. Проверяет корректность всего каталога, Release или отдельной сущности и сообщает диагностику, не рендеря артефакты.
  • aggrega search — доступна. Ищет опубликованные сущности в локальном индексе настроенных реестров; индекс строится и обновляется командой aggrega registry update.
  • aggrega registry — доступна. Управляет реестрами и их политикой доверия к подписям; registry add регистрирует реестр, а registry update строит локальный индекс, по которому выполняет запросы aggrega search.
  • aggrega push-artifact — доступна. Публикует автономный артефакт данных (например, пакет документации) в реестр OCI, в дополнение к команде push, публикующей сущности.
  • aggrega sign — доступна. Подписывает один или несколько уже опубликованных артефактов и прикрепляет их подписи.
  • aggrega deprecate — доступна. Прикрепляет подписанную отметку об устаревании к уже опубликованному артефакту.
  • aggrega login и aggrega logout — доступны. Выполняют аутентификацию в реестре OCI и сохраняют учётные данные либо удаляют сохранённые учётные данные.
  • aggrega auth — доступна. Управляет локальной идентичностью подписи, используемой для подписания артефактов.
  • aggrega config — доступна. Исследует конфигурацию рабочего пространства и управляет ею; подкоманды показывают действующую объединённую конфигурацию и источник каждого параметра, создают рабочую конфигурацию с реестром и его политикой доверия к подписям, а также фиксируют действующую критичную для сборки конфигурацию в рабочем пространстве, чтобы оно собиралось одинаково, не завися от глобальной конфигурации машины.
  • aggrega get-schema — доступна. Выводит JSON Schema для вида сущности или контракта.
  • aggrega plugin — доступна. Исследует плагины Wasm, которые может разрешить CLI; подкоманды выводят их список, добавляют и удаляют настроенные плагины, синхронизируют управляемые машиной записи плагина и формируют их представление в виде каталога.
  • aggrega cache — доступна. Исследует и обслуживает кэши на диске; подкоманды сообщают статус, выполняют очистку от устаревшего, вытеснение и полную очистку.
  • aggrega mcp — доступна. Запускает сервер Model Context Protocol через stdio или через HTTPS для клиента на другой машине, предоставляя интроспекцию компилятора интеграциям с ИИ-ассистентами.
  • aggrega completion — доступна. Генерирует скрипт автодополнения оболочки для CLI.
  • Подкоманды-расширения CLI — доступны. Плагин Wasm, опубликованный как гость pluginType: cli, разрешается и регистрируется как подкоманда aggrega, так что установленное расширение запускается как aggrega <extension> наряду со встроенными командами.
  • aggrega import — доступна. Преобразует сторонний декларативный источник определений агентов (Langflow, Flowise, n8n) в черновые файлы описания Aggregate и Component, записывая для каждого узла детерминированное решение о повторном использовании каталога с оценкой уверенности. Специфичное для формата сопоставление предоставляет плагин-импортёр, который рабочее пространство разрешает для формата источника, — либо хранящийся в его каталоге, либо один из импортёров Langflow, Flowise и n8n компилятора, которые собираются и публикуются с каждым выпуском компилятора. Бинарный файл содержит их сущности Plugin, но не их модули, поэтому они обслуживают свои форматы в любом рабочем пространстве: первый импорт, которому нужен импортёр, отсутствующий на машине, загружает его из реестра рабочего пространства по умолчанию, проверяет и сохраняет в кэше содержимого для всех последующих импортов. Источник разбирается парсером, который каталог рабочего пространства предоставляет для его синтаксиса, либо, если каталог не предоставляет никакого, парсером, встроенным в компилятор, так что рабочее пространство, в каталоге которого нет парсера, выполняет импорт любым из них.
  • aggrega scaffold — доступна. Создаёт черновик начального документа для любого вида сущности по схеме этого вида — со всеми обязательными полями и заполнителем там, где нужно значение, — и записывает его в стандартный вывод; с --example записывает в новый каталог один из готовых к запуску примеров документации, прочитанный из подписанного пакета документации.
  • aggrega explain — доступна. Объясняет условие остановки, которое обозначает короткий код (например, E0007) или описательный код.
  • aggrega edit-document — доступна. Применяет к документу одну ограниченную структурированную правку — добавление компонента, присоединение сущности Feature, подключение соединения или установку одного значения, — сохраняя каждый байт, который она не затрагивает.
  • aggrega pin — доступна. Записывает в entity.lock рядом с сущностью Recipe или FeatureRecipe закрепление содержимого для каждого входа, который сущность читает за пределами собственного документа.
  • aggrega skills — доступна. Устанавливает навык Aggrega в AI-ассистента.

Обзор CLI см. в 07-cli.md, а справочные страницы по каждой команде — в указателе справочника по языку.

Редакторы и другие фронтенды

Каждый фронтенд показывает то, что скомпилировал исполняемый файл aggrega; ни один не содержит собственного компилятора. Статус по поверхностям:

  • Контракт графа IR — доступно. Схема графа IR, контракт, по которому каждый фронтенд читает граф, поставляется в составе дистрибутива схем Aggrega; см. справочник схемы IR.
  • Чтение графа из команды — доступно. aggrega build принимает --ir-graph, как и aggrega inspect с сущностью Release и aggrega validate --release; флаг записывает граф, разрешённый в ходе запуска, в stdout в формате JSON в дополнение к тому, что команда уже выводит. Сеанс демона читает тот же граф через aggrega/irGraph, а инструменты cli-inspect, cli-build и cli-validate MCP-сервера принимают его как свой аргумент ir_graph.
  • Граф топологии в Visual Studio Code — доступно. Расширение Aggrega для Visual Studio Code рисует граф IR выбранной сущности Release как интерактивный граф и присоединяет из него Features, обращаясь за тем и другим к демону aggrega serve.
  • Потоковый режим CLI без интерфейса — запланировано. Режим без интерфейса выводит граф IR в stdout в виде JSON с разделением по строкам, чтобы фронтенд потреблял его по мере изменения топологии. Сегодня поставляется один документ на вызов, а не поток: ни одна команда не выводит последовательность графов в один stdout по мере изменения топологии.

О том, как редактор, ассистент и демон обращаются к компилятору, см. ../architecture/15-editors-assistants-and-frontends.md.

Направления проектирования

Приведённая выше таксономия статусов классифицирует состояние каждой поверхности языка; в этом разделе фиксируется статус более широких направлений проектирования, описанных в главах об архитектуре.

Соответствие требованиям в масштабе всей инфраструктуры не является запланированным направлением: задать правило управления один раз так, чтобы оно распространялось на каждую сборку в рабочем пространстве, уже сейчас доступно через сокет управления. Plugin, подключённый по ключу plugins.governance конфигурации рабочего пространства, оценивает каждую сборку в этом рабочем пространстве: роль вердикта отклоняет граф или отрисованный артефакт, нарушающий правило, а роль преобразования предоставляет производные метаданные, которые разработчик никогда не вводит вручную. См. ../architecture/11-governance-and-compliance.md.

  • Паритет интерфейсов и автоматическая реализация — доступно. Recipe, написанный для базового Component, обслуживает каждый Component, который его расширяет, на любой глубине цепочки, и архитектору не нужно создавать дублирующий Recipe. Расширяющий Component указывает schema: inherited, поэтому он не добавляет в values / infra / provides корневых ключей, которые Recipe базового компонента не смог бы использовать; Component, объявляющий extends с собственной схемой, отклоняется на оболочке своего документа. Manifest по-прежнему сопоставляет расширяющий тип отдельной записью, и проверка сопоставления принимает её, если implements сопоставленного Recipe называет этот тип или любой базовый тип, который он расширяет. Описано в ../architecture/02-ecosystem-philosophy.md.
  • Ghost Infrastructure Tracker — доступно. Защитный механизм фазы рендеринга выдаёт предупреждение, когда ключ, объявленный автором, достигает узла, но ни один шаблон, объявленный привязанным Recipe, его не читает, так что значение, объявленное автором и молча отброшенное шаблоном, называется, а не теряется. Это половина того же механизма сопоставления форм, относящаяся к фазе рендеринга. См. errors/warnings.md.

Главы об архитектуре описывают поверхности проектирования; эта страница отслеживает статус реализации.