aggrega scaffold
Создание начального документа для вида сущности или запись готового к запуску примера в новый каталог
Синтаксис
aggrega scaffold <kind> [name] | --example <name> [dir] | --example --list [flags]Описание
Draft a starter document for an entity kind from its schema, or write one of the documentation's runnable examples into a new directory.
Drafting a starter document
The kind is the lowercase-hyphenated schema token — for example component, aggregate, release, recipe, manifest, or feature. Run aggrega get-schema --list to print the whole set; a token no schema answers to is refused with that set in the message, so a typo is corrected without a second lookup.
The document is derived from that kind's own contract and from nothing else. It carries exactly the fields that kind's schema requires, with the fixed apiVersion and kind filled in and a placeholder everywhere a value is needed. It is not a worked example: there is no namespace, no category, no label set and no commented suggestion of what people usually write, because a catalog decides those for itself and a starter document that guessed at them would teach a requirement that does not exist.
The optional name seeds metadata.name for a kind whose schema requires one. Every other required value is left as a placeholder to fill in.
Nothing is written to disk. The document goes to standard output, so a redirect decides where it lands:
aggrega scaffold component my-service > my-service.yaml
The same starter document is served to an assistant by the scaffold tool that aggrega mcp exposes, which returns these bytes alongside a machine-readable payload; this command is the terminal route to the same drafting.
Writing a runnable example
With --example, the argument is the name of one of the runnable examples the documentation publishes, and the command writes that example's files into a new directory — the second argument, or a directory named after the example in the current directory when there is none — then prints the commands the example's own page gives for building it:
aggrega scaffold --example redis-cache
The directory must not exist yet, or must be empty; a directory holding anything is refused and left as it is. With --list, the command prints every example there is, each with its level and the first sentence of its page, and writes nothing:
aggrega scaffold --example --list
The examples are read from the documentation bundle published for this version of aggrega on the default registry — or, where none is published for it, the newest one published for an earlier version. It is kept in the cache every project on this machine shares, so a second example needs no second download. It is fetched through the same network settings as every other registry read, and verified against this workspace's signature policy before it is kept or read; a bundle that does not verify is refused, never used. Offline, an example is written only from a copy already cached on this machine.
An example's files are written only as files and directories inside the directory named: a bundle carrying an entry that would land outside it, or a link, is refused whole and nothing is written.
The scaffold tool that aggrega mcp exposes, and the editor's language server that aggrega serve runs, write and list the examples on the same terms, with the directory named relative to the workspace root, and answer with the files written and these same commands.Флаги
| Флаг | По умолчанию | Описание |
|---|---|---|
--example | false | записать запускаемый пример, названный аргументом, в новый каталог, прочитав его из подписанного пакета документации |
--list | false | с —example вывести все запускаемые примеры, которые публикует документация, и ничего не записывать |
Что делает команда
У команды две формы. aggrega scaffold <kind> создаёт черновик начального документа по схеме вида и выводит его — именно это описывают этот раздел и три следующих. aggrega scaffold --example <name> вместо этого записывает один из запускаемых примеров документации в новый каталог — см. Начало с запускаемого примера.
aggrega scaffold <kind> выводит в стандартный вывод начальный документ для одного вида сущности. Документ содержит ровно те поля, которые требует схема этого вида: apiVersion и kind заполнены, потому что схема их фиксирует, а все остальные обязательные значения оставлены как заполнители, которые вам нужно заменить.
Необязательный аргумент [name] задаёт metadata.name для вида, схема которого требует это поле:
aggrega scaffold component my-serviceapiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: my-service version: "" labels: component.aggrega.ai/type: ""spec: {}Вид — это токен схемы в нижнем регистре через дефис: component, aggregate, release, recipe, manifest, feature и остальные. aggrega get-schema --list выводит весь набор, а токен, которому не соответствует ни одна схема, отклоняется с этим набором в сообщении, так что опечатку можно исправить без повторного поиска.
Что команда возвращает и чего не возвращает
Документ строится только по собственному контракту вида и ни по чему больше. Это не готовый пример. В нём не заполнены за вас ни пространство имён, ни категория, ни значения меток, и нет закомментированных подсказок о том, что обычно пишут, — потому что ничего из этого компилятор не требует. Каталог сам выбирает именование, категории и структуру каталогов; поля определяет схема, и схема — единственное, что читает эта команда. Начальный документ, который угадывал бы остальное, научил бы вас правилу, которого не существует.
Создание черновика не записывает файл. Документ выводится в стандартный вывод, поэтому место назначения определяет перенаправление, и ничего на диске не заменяется без вашего запроса:
aggrega scaffold component my-service > my-service.yamlЭто не готовая сущность, и именно это означает заполнитель. Пустое обязательное значение — не значение, поэтому запуск aggrega validate для документа в том виде, в каком он был выведен, отклоняет его и сразу называет каждый ещё не заполненный заполнитель вместе с тем, что он принимает, — выше это версия и тип компонента:
Entity: my-service.yamlKind: Component[E0215] document envelope validation failed: 2 placeholders still owed in my-service.yaml; an empty required value is not a value, so each of these needs one before the document validates: 5:3: metadata.version takes a semantic version, such as 1.0.0 7:5: metadata.labels.component.aggrega.ai/type takes one of: server, worker, task, function, stateful-server, resourceТо, что принимает каждое значение, берётся из собственной схемы вида: допустимые значения, если схема их перечисляет, семантическая версия, если схема её требует, а в остальных случаях — собственное описание поля в схеме. Укажите эти значения, и та же команда примет документ. Его структуру менять не нужно, потому что она взята из схемы.
Значение нужно указать, даже если схема приняла бы его пустым. В созданной заготовке сущности Recipe или FeatureRecipe поля capability и implements пусты. Их схема допускает пустую строку, но пустая строка не называет ни провайдера, ни тип, поэтому aggrega validate называет оба поля ещё не заполненными, пока вы их не заполните. Такая проверка относится к валидации одного файла сущности: запуск по всему каталогу, aggrega validate --release и aggrega build её не применяют. Что она охватывает, см. в разделе незаполненные заполнители. Созданная заготовка сущности Recipe также не объявляет ни одного из видов входных данных, хотя бы один из которых требует её схема, — source, valuesMapping, workload или artifacts, — поскольку выбрать подходящий должны вы, поэтому aggrega validate отклоняет её spec, пока вы не добавите один из них.
Тот же документ из ассистента или редактора
Начальный документ состоит из одних и тех же байтов, через какой бы интерфейс его ни запросили. ИИ-ассистент, подключённый через aggrega mcp, получает его как инструмент scaffold, который возвращает документ в виде текста вместе с машиночитаемыми данными. Редактор, работающий с aggrega serve, получает его через aggrega/scaffoldEntity. Документ выводится из схемы единожды, поэтому документ, созданный вами в терминале, и документ, созданный для вас ассистентом, побайтно идентичны.
Запись и вывод списка готовых к запуску примеров доступны на тех же поверхностях, а именами полей служат слова самой команды. Чтобы записать пример, отправьте инструменту scaffold или aggrega/scaffoldEntity поле example вместо kind; dir — чтобы задать новый каталог относительно корня рабочего пространства (если его не отправить, это каталог с именем примера там же); а одно list: true — чтобы получить в ответ все примеры. Пример читается из того же пакета, проверяется по той же политике и записывается той же распаковкой, поэтому файлы и следующие команды такие же, как в терминале, и так же обстоит дело с отказами: каталог, содержащий что-либо, элемент, ведущий за пределы каталога, или ссылка, пакет, который не принимает ваша политика, офлайн-рабочее пространство, в кэше которого ничего нет. Ответ структурирован: для списка — examples, каждый с name, level и summary; для записи — example, dir, files (записанные файлы относительно dir), next (команды, которые приводит страница примера) и version (версия документации, из которой прочитан пример). Ответ инструмента scaffold на запись также содержит output_dir — расположение каталога: через стандартные ввод и вывод — полный путь, чтобы ассистент, указавший его относительно рабочего пространства, которого он не видит, прочитал, куда попал пример, а через HTTP — относительно корня рабочего пространства. Текст инструмента scaffold — это отчёт, который печатает эта команда, завершённый строкой с этим расположением, если оно отличается от dir. Поля двух форм, отправленные вместе, — скажем, kind вместе с example, — отклоняются одними и теми же словами на обеих поверхностях, прежде чем что-либо будет прочитано. Редактор для формы примера указывает рабочее пространство в поле workspaceRoot запроса, а dir должен быть относительным путём, который остаётся внутри него и не ведёт за его пределы через ссылку; через HTTP инструмент тоже ограничивает dir обслуживаемым рабочим пространством, а через стандартные ввод и вывод принимает dir так, как он указан, как и любой путь. Индекс возможностей сообщает об инструменте scaffold как о записывающем — из-за этой формы, — а о cli-scaffold, который запускает эту команду в отдельном процессе, тоже как о записывающем.
Начало работы с готового к запуску примера
Документация содержит готовые к запуску примеры — каждый представляет собой каталог с сущностью Aggregate, её сущностями Releases и всем остальным, из чего он собирается, а также страницей, описывающей, как его собрать. --example записывает один из них в новый каталог, так что можно начать с работающего проекта, а не с пустого:
aggrega scaffold --example redis-cacheWrote the example redis-cache into redis-cache (12 files).
Next:
cd redis-cache # Local development (Docker Compose), no authentication aggrega build --release release-compose.yaml --auto-pull ...
Its page, redis-cache/README.md, explains what it shows.Что записывается и куда. Файлы примера в том виде, в каком их содержит документация, записываются в каталог, указанный вторым аргументом, — или, если он не указан, в каталог с именем примера в папке, из которой запущена команда. Каталог должен ещё не существовать или быть пустым. Всё остальное отклоняется и остаётся в точности таким, каким было: каталог, содержащий файл, файл, находящийся по этому пути, или ссылка. Ещё не существующие каталоги выше него создаются. Ни один файл примера не остаётся где-либо ещё, и ни один не помещается на место до того, как будут записаны все: сначала они записываются в сторону и перемещаются, как только все они на месте.
Команды, которые она печатает следом, — это те, что приводит собственная страница примера: первый блок sh, bash или shell под заголовком ## Build страницы, в том виде, в каком его записала страница, включая комментарии, после cd в этот каталог. Для примера, на странице которого такого блока нет, вместо этого сообщается путь к его странице.
Какие примеры есть. --list печатает каждый пример по одному разу в том порядке, в котором их излагает документация, — его имя, уровень, объявленный его страницей, и первое предложение его страницы — и ничего не записывает:
aggrega scaffold --example --listEXAMPLE LEVEL DESCRIPTION...redis-cache start This lean example compiles a single **Redis** in-memory cache (Redis wire protocol) from one Developer-authored `Aggregate` to two realizations....Этот список — собственный список примеров документации, тот, что опубликован рядом с ними как Примеры по продуктам и возможностям. Имя, под которым в пакете нет примера, отклоняется с указанием на --list, и ничего не записывается.
Откуда берутся примеры. Они читаются из пакета документации — подписанного архива опубликованной документации, из которого aggrega explain читает свои пошаговые разборы, — опубликованного в реестре вашего рабочего пространства по умолчанию. Читается пакет, опубликованный для запущенной вами версии aggrega. Если для этой версии пакет не опубликован, читается самый новый пакет, опубликованный для более раннего выпуска, и команда сообщает об этом в стандартный поток ошибок:
note: no documentation is published for 0.9.1; the examples are read from the documentation published for 0.9.0, the newest before itСборка aggrega, сделанная из нескольких коммитов после выпуска, — та, у которой aggrega version выглядит как 0.9.0-12-g1a2b3c4d, — читает документацию выпуска, после которого она собрана, здесь 0.9.0, или более раннего, если та не опубликована. Сборка, сделанная из нескольких коммитов после предварительного выпуска, например кандидата в выпуски, — та, у которой aggrega version выглядит как 0.9.0-rc.6-4-gc9db2f597, — читает документацию этого предварительного выпуска, здесь 0.9.0-rc.6, или, если та не опубликована, самую новую, опубликованную до него, включая более ранний предварительный выпуск. Любая другая сборка читает документацию предварительного выпуска, только если она сама является этим предварительным выпуском. Сборка без номера выпуска читает документацию своей версии или никакую. aggrega explain таким же образом выбирает пакет, из которого читает свои пошаговые разборы.
Если для вашей версии ничего не опубликовано, а самый новый из более ранних пакетов имеет формат, который эта версия aggrega больше не читает, — например, у кандидата в выпуск, запущенного до публикации его собственной документации, — команда отказывает, сообщая об обоих обстоятельствах одним предложением, и ничего не записывается:
[E0137] hub.aggrega.ai/docs/aggrega-docs publishes no documentation bundle for 0.9.1-rc.1, and the newest earlier one, 0.8.11, is in a format this version of aggrega no longer reads, so the examples cannot be readПеред использованием он проверяется. Пакет загружается с теми же сетевыми настройками, что и любое другое чтение из реестра, а его подпись проверяется по политике подписей вашего рабочего пространства для этого реестра, прежде чем пакет будет сохранён, — и снова перед чтением копии, которая уже есть на машине, так что копия, впущенная более мягкой политикой другого проекта, не используется под вашей. Пакет, который ваша политика не принимает, отклоняется, и ничего не записывается.
Он загружается один раз на машину. Пакет хранится в кэше, общем для всех проектов Aggrega на машине, — см. aggrega cache, — поэтому второму примеру или второму проекту не нужна повторная загрузка, а aggrega explain читает ту же копию, когда оба читают одну и ту же версию.
В офлайне читается только то, что есть в кэше. В офлайн-рабочем пространстве ничего не загружается: пример записывается из копии, которая уже есть на машине и которую допускает ваша политика, — для этой версии или, иначе, самой новой из более ранних, имеющихся в кэше, — а если такой нет, команда отказывает тем же офлайн-отказом, что и любое сетевое чтение, с указанием, как разрешить доступ к сети.
Пакет, содержащий что-то неожиданное, отклоняется целиком. Пакет поступает из реестра, поэтому распаковка ничему не доверяет в его структуре: элемент, имя которого оказалось бы за пределами указанного вами каталога или за пределами пакета, и элемент, являющийся ссылкой или чем-либо, кроме файла или каталога, — каждый из них приводит к отказу от всего примера с указанием этого элемента, и ничего не записывается. Исполняемый файл в примере остаётся исполняемым.
Читается конфигурация рабочего пространства. Реестр по умолчанию и политика подписей берутся из неё, поэтому файл конфигурации, являющийся ссылкой, ведущей за пределы рабочего пространства, останавливает форму примера так же, как останавливает любую другую команду, читающую конфигурацию, — см. граница рабочего пространства.
Примеры
Создать безымянную заготовку сущности Release и просмотреть её в терминале:
aggrega scaffold releaseСоздать заготовку сущности Recipe сразу в файле:
aggrega scaffold recipe postgres-helm > postgres-helm.yamlПроверить, что ещё нужно заполнить, прежде чем что-либо заполнять:
aggrega scaffold component my-service > my-service.yamlaggrega validate my-service.yamlПосмотрите, какие готовые к запуску примеры есть, а затем запишите один из них в выбранный вами каталог:
aggrega scaffold --example --listaggrega scaffold --example redis-cache my-cacheО цикле разработки, который начинает эта команда, — создать структуру, заполнить заполнители, проверить, — см. Написание файлов Aggrega.