Импорт
aggrega import читает проект, написанный в другом формате, — поток, экспортированный из Langflow, конфигурацию клиента MCP, файл Compose и другие форматы, перечисленные ниже, — и записывает из него файлы Aggrega: сущность Aggregate, сущность Release и, для цели, которую указывает --target, сущность Manifest. Вместе они образуют рабочее пространство, которое проходит валидацию и собирается в том виде, в каком записано, как только даны ответы на несколько значений, которые не может содержать ни один источник: импорт запрашивает каждое из них один раз и сохраняет ответы в файле ответов. Он ничего не развёртывает и не обращается ни к какому кластеру или облачной учётной записи. Черновики — это обычные файлы в вашем рабочем пространстве, и что с ними делать дальше, решаете вы.
- LangGraph
- CrewAI
- n8n
- Dify
- Langflow
- Flowise
- Google ADK
- Microsoft Agent Framework
- MCP client configurations
- Compose
aggrega importчерновики файлов Aggrega
чтобы вы их просмотрели и отредактировали
На входе — ваш существующий проект, на выходе — черновики файлов Aggrega. Ничего не развёртывается; сначала вы просматриваете черновики.
Что он вам даёт
- Ваш проект попадает в Aggrega без ручного переписывания. Черновики сущностей Aggregate, Release и Manifest — это файлы того же рода, которые вы написали бы сами. Они собираются в том виде, в каком записаны, для цели, которую указывает импорт, а каждая политика управления, которую подключает ваше рабочее пространство, оценивает эту сборку так же, как любую другую.
- То, что указано в источнике, переносится. Узел или сервис, для которого в каталоге есть сильное совпадение, ссылается на эту сущность Component каталога со значениями, которые задаёт ему источник, например моделью, которую указывает поток. Платформа, на которой работает источник, попадает в черновик с образом, который запускают для неё сущности Recipes каталога. Секрет записывается в черновик как ссылка на то, откуда он берётся, и никогда как его значение.
- У вас запрашивается только то, чего не может содержать ни один источник, и только один раз. Ответы хранятся в файле ответов рядом с источником, поэтому следующий импорт того же источника ничего не запрашивает.
- Черновики принадлежат вам. Это обычный YAML в вашем рабочем пространстве, после которого не остаётся ничего, от чего зависела бы сборка. Редактируйте их, переименовывайте, коммитьте.
- Черновик может следовать за своим источником.
aggrega import --syncприводит черновики предыдущего импорта в соответствие с изменённым источником, меняя только то, что записал импорт. Если источник изменил часть, которую вы редактировали, он останавливается и называет эту часть, вместо того чтобы перезаписать ваши правки.
Чего он не делает
Импорт создаёт черновик того, что указано в источнике, и того, что определяет ваш каталог, а остальное запрашивает. Каждый черновик в комментарии рядом со значением сообщает, откуда взялось записанное им значение.
- Он не угадывает то, чего ваш источник не может указать. Ни один источник не указывает среду, в которую развёртывается сущность Release, поэтому черновик сущности Release указывает
developmentс комментарием о том, что это значение по умолчанию, которое следует изменить. Значение, которое требует каталог и которого не содержит ни один источник, — адрес электронной почты учётной записи владельца, образ приложения, собранного из вашего собственного кода, имя Secret в Kubernetes, — записывается в черновик пустым и запрашивается, как описывает раздел Как выполняется импорт ниже. - Он не читает код. Собственная программа потока или проекта не читается: программа crew CrewAI, код графа приложения LangGraph, исходный код компонента Langflow, который лишь переносится внутри потока.
- Он не судит о том, что означает значение. Каждый узел или сервис сопоставляется с сущностями Components каталога вашего рабочего пространства — их именами, категориями, метками и именами объявленных ими значений. На совпадение из высокого уровня черновик ссылается; более слабое записывается как комментарий, указывающий сущность Component и её оценку, и выбор за вами.
- Он не меняет версию, которую запускает платформа, чтобы следовать за источником. Образ платформы записывается в черновик с версией, которую, как известно, запускают для неё сущности Recipes каталога, а там, где источник указывает другую версию, её указывает комментарий рядом с образом.
- Он не выносит учётные данные из вашего источника за вас. Значение, которое может содержать ключ, — значение окружения, заголовок, командная строка сервера MCP — по умолчанию переносится в черновик как есть, а импорт называет каждое из них в предупреждении
credential-carried, никогда не по его значению. Параметр импортераempty_credentialsвместо этого записывает их пустыми (Настройки). Прочитайте предупреждения, прежде чем делиться черновиком. - Он ничего не развёртывает и не запускает. Он читает источник и ваш каталог и записывает файлы. Сборка черновиков и запуск того, что записала сборка, — это отдельные шаги, которые выполняете вы.
Как выполняется импорт
Импорт можно выполнить командами ниже или поручить его вашему ИИ-ассистенту.
-
Начните с рабочего пространства. Импорт записывает свои черновики внутри корня рабочего пространства, в котором он запущен, — папки, содержащей
.aggrega-config.yamlс ключомworkspace, — или внутри директории, которую задаёт--output-dir. Он никогда не перезаписывает уже существующую там сущность Aggregate. -
Каталог для сопоставления. Импорт оценивает ваш источник относительно сущностей Components каталога рабочего пространства — и ничего другого. Если рабочее пространство не указывает собственной папки каталога, это каталог стандартной библиотеки, читаемый из реестра рабочего пространства по умолчанию: каждая публикация каталога публикует подписанный снимок всего каталога, а первый импорт получает этот снимок, проверяет его подпись, сохраняет в кеше содержимого рабочего пространства и называет по его дайджесту в записи, которую пишет рядом с черновиками, поэтому последующий импорт тех же черновиков читает тот же каталог, не обращаясь к реестру снова. Относительно него сервис PostgreSQL сопоставляется с
core/datastore/postgres, а--targetсоздаёт черновик сущности Manifest на основе сущностей Recipes каталога. Без каталога импорту не с чем сопоставлять, а--targetотклоняется, поскольку ни один Recipe не привязан к цели.Рабочее пространство, которое указывает собственные папки каталога, вместо этого импортирует относительно них и не получает никакого снимка: директорий, которые перечисляет
workspace.catalog_dirs, папкиcatalogв корне рабочего пространства или директорий, которые называетAGGREGA_CATALOG_DIRS. Собственные файлы каталога стандартной библиотеки — это папкаaggrega-catalogрепозиторияaggrega-hub, https://github.com/aggrega-ai/aggrega-hub, для рабочего пространства, которому они нужны в виде папки.--upgradeполучает самый новый снимок, публикуемый реестром, и с этого момента импортирует относительно него; при--offlineимпорт, которому пришлось бы получить снимок, останавливается и называет, что нужно запустить. -
Запустите импорт. Укажите файл или директорию:
Terminal window aggrega import compose.yaml --target composeФормат распознаётся по имени и содержимому файла; там, где это не так, его задаёт
--format.--targetзадаёт возможность провайдера, напримерcomposeилиhelm, и создаёт черновик сущности Manifest, сопоставляющий каждый тип компонента и каждый тип функции, нужный черновикам, с той сущностью Recipe этой возможности, которую ваш каталог предлагает для него: с единственной имеющейся или, среди нескольких, с той, что названа по типу. Черновик сущности Release называет эту сущность Manifest, а содержимое черновиков зависит от цели: дляcomposeсекрет — это ссылка на переменную, которую Docker Compose заполняет из вашей оболочки, дляhelm— имя Kubernetes Secret. В стандартный поток ошибок импорт выводит название прочитанного формата, каждое предупреждение и по одной строке на каждый сопоставленный узел; в стандартный вывод — список записанных файлов. -
Ответьте на то, чего не содержит ни один источник. На значение, которого требует каталог и которое не может содержать ни один источник, — адрес электронной почты учётной записи владельца, образ приложения, собранного из вашего собственного кода, имя Kubernetes Secret — отвечают один раз. Импорт читает ответы из
import-answers.yamlрядом с источником или из файла, который задаёт--answers; в терминале он запрашивает каждое ещё отсутствующее значение, по одному вопросу за раз, и записывает ваши ответы в этот файл. На секрет отвечают тем, откуда он берётся, — переменной или именем Secret, — и никогда его значением. Там, где ничего нельзя спросить, — в непрерывной интеграции, через конвейер, из ассистента или редактора — импорт записывает файл ответов с ключом каждого отсутствующего значения и пустым ответом, перечисляет их и завершается со статусом 1; заполните их и запустите импорт снова. Один файл ответов служит всем целям: ответ, который не нужен черновикам для какой-либо цели, сохраняется в файле и остаётся неиспользованным. Файл ответов импорта полностью описывает этот файл. -
Импорт загружает то, что нужно сборке. Как только ничего не отсутствует, импорт загружает зависимости черновика сущности Release, как это делает
aggrega pull, и записывает рядомrelease.lock. С--offlineон ничего не загружает и называет командуaggrega pull, которую следует выполнить. -
Проверьте и соберите. В папке с черновиками:
Terminal window aggrega validate --release release.yamlaggrega build --release release.yamlКогда обе команды проходят, сборка уже записала файлы цели в
dist/. Отказ называет, что изменить и где, в документе, который вы изменяете. -
Запустите то, что записала сборка. Сборка для Docker Compose записывает
dist/compose/docker-compose.yaml, и этот файл не задаёт имени проекта Compose, поэтому задайте его с помощью-p:Terminal window docker compose -p <name> -f dist/compose/docker-compose.yaml up -dБез
-pDocker Compose называет проект по папке, содержащей файл,compose, поэтому два рабочих пространства, запущенные таким образом, используют один общий проект. Сервисы находятся в одной сети, которую Docker Compose называет по проекту,<name>_compose. К сервису, для которого сборка не публикует ни одного порта, обращаются изнутри этой сети с помощьюdocker compose -p <name> -f dist/compose/docker-compose.yaml exec <service> …или из контейнера, который вы запускаете в этой сети, с помощьюdocker run --network <name>_compose …. Разделы «Запуск» и «Проверка» пошагового руководства показывают команды для его собственной сборки.Запуск отвечает без ключа OpenAI, как только его модель
core/ai-model/openaiнаправлена на небольшую модель, которую обслуживает Ollama в том же проекте, с тремя изменениями в созданных черновиках файлов, сборкой с--auto-pull, которая загружает то, что нужно добавленному компоненту, и одной командой после запуска стека:- в сущности Aggregate — ещё один компонент, ни с чем не связанный:
local-modelтипаcore/ai-model/ollamaсmodel: qwen2.5:0.5bв егоvalues; - в сущности Manifest — его Recipe для Compose:
core/ai-model/ollama: compose/ollama; - в сущности Release —
local-model: {}, а также ключendpointмодели OpenAI в еёinfra, установленный на OpenAI-совместимый адрес этого сервера,http://local-model:11434/v1; - после запуска стека загруженная модель копируется под именем модели, которое указывает модель OpenAI сборки,
<model>, напримерgpt-4o-miniилиgpt-4.1:docker compose -p <name> -f dist/compose/docker-compose.yaml exec local-model ollama cp qwen2.5:0.5b <model>.
После этого
OPENAI_API_KEYможет содержать любое ваше непустое значение: локальный сервер не проверяет ни одного. Рабочий процесс n8n читает адрес и ключ модели из учётных данных, которые выбирает его узел модели, а не из адреса, который передаётendpoint, поэтому передайте этим учётным данным также адрес сервера — какurlрядом сapiKeyв ихdata. Сервер Ollama, которыйcore/ai-model/ollamaзапускает по умолчанию, обслуживает не только Chat Completions, но и Responses API от OpenAI, поэтому декларативный агент Agent Framework, указывающийapiType: Responses, обращается к нему в том виде, в каком он написан.Сборка для Kubernetes, цель
helm, записывает обычные манифесты, а не чарт, как описывает провайдер helm: вdist/helm/или, для компонентов, которые сущность Release помещает в границу, вdist/boundaries/<boundary>/helm/, некоторые из них — в собственной папке ниже. Файлы, в которых не указано пространство имён, как файлы сборок MCP и Dify, попадают в то, которое указывает ваш контекстkubectl, или вdefault, если он не указывает никакого; сначала создайте там Secrets, которые они читают, а затем примените папку:Terminal window kubectl apply -R -f dist/helm/-Rохватывает файлы в этих папках. Service типаClusterIP— тип, который сборки MCP и Dify дают запускаемым ими серверам, — доступен только изнутри кластера: чтобы обратиться к нему со своей машины, перенаправьте на него локальный порт с помощьюkubectl port-forward svc/<service> <local port>:<port>; эта команда работает, пока вы её не остановите. - в сущности Aggregate — ещё один компонент, ни с чем не связанный:
Рядом со своими черновиками импорт записывает .aggrega-import.json — сведения о том, что он записал. Храните его, пока собираетесь запускать aggrega import --sync: эта команда читает его, чтобы отличить ваши правки от записанного самим импортом. Храните и файл ответов: он не содержит секретов, поэтому может находиться в системе контроля версий рядом с источником, и каждый последующий импорт этого источника его читает.
С ИИ-ассистентом
ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.
Используй только инструменты Aggrega и сам не создавай никаких папок. Вызови инструмент `import`, задав `source` равным `compose.yaml` и `target` равным `compose`: он записывает свои черновики в папку Workspace. Если он сообщит, что ещё не хватает значений, назови мне каждое и объясни, что это, и подожди, пока я впишу ответы рядом с их ключами в файле ответов, который он назовёт; затем снова вызови инструмент `import` тем же способом. Потом вызови инструмент `validate`, задав `release` равным `release.yaml`, и инструмент `build`, задав `release` равным `release.yaml` и `write` равным true. Скажи мне, какие файлы записала сборка; они находятся в `dist/` в папке Workspace.Открытие в VS Code
Когда установлено расширение Aggrega для Visual Studio Code, откройте в VS Code рабочую область, в которой выполнялся импорт, — папку с её .aggrega-config.yaml: черновики находятся в ней, в корне или в папке, указанной --output-dir. Если рабочая область содержит одну сущность Release, редактор выбирает её за вас; если несколько, Aggrega: Select Release… выбирает ту, с которой работает редактор. Редактор проверяет черновики относительно выбранной сущности Release по мере их редактирования, отмечая найденное в файле и на панели «Проблемы». Aggrega: Show topology graph в палитре команд рисует компоненты выбранной сущности Release и соединения между ними. Aggrega: Build, Aggrega: Preview build и Aggrega: Pull действуют на ту же сущность Release, и каждая из них также является кнопкой на панели Commands представления Aggrega на панели действий; Build записывает свои файлы в dist/ рабочей области. Остальное описано в разделе Использование Aggrega в Visual Studio Code.
Откуда берутся импортеры
Каждый формат читает плагин-импортер. Базовые импортеры компилятора, по одному для каждого формата из таблицы ниже, публикуются с каждым выпуском компилятора и обслуживают свои форматы в каждом рабочем пространстве без какой-либо записи в вашем каталоге. Первый импорт, которому нужен импортер, загружает его из реестра рабочего пространства по умолчанию в версии самого компилятора, проверяет его и сохраняет в кеше содержимого рабочего пространства, поэтому каждый следующий импорт читает его оттуда, не обращаясь ради него к сети. Если модуль вообще невозможно загрузить — скажем, рабочее пространство офлайн, — импорт останавливается и называет два способа поместить его на машину. Базовые импортеры полностью описывают каждый импортер, а также параметры, которые импортер получает через запись plugins.importer.
Форматы
| Формат | Что он читает | Пошаговый пример |
|---|---|---|
| Compose | файл Compose и его файл переопределений или директория, содержащая их | Импорт проекта Compose |
| Конфигурации клиентов MCP | .mcp.json, claude_desktop_config.json, .vscode/mcp.json, .cursor/mcp.json или server.json реестра MCP | Импорт конфигурации клиента MCP |
| Langflow | поток, экспортированный из Langflow, в формате JSON | Импорт потока Langflow |
| Flowise | chatflow или agentflow, экспортированный из Flowise, в формате JSON | Импорт chatflow Flowise |
| n8n | рабочий процесс, экспортированный из n8n, в формате JSON | Импорт рабочего процесса n8n |
| Dify | приложение, экспортированное из Dify на его DSL, в формате YAML | Импорт приложения Dify |
| CrewAI | объявления агентов и задач проекта CrewAI | Импорт проекта CrewAI |
| LangGraph | langgraph.json приложения LangGraph | Импорт приложения LangGraph |
| Google ADK | файлы Agent Config приложения, построенного на Google ADK, начиная с root_agent.yaml | Импорт агента Google ADK |
| Microsoft Agent Framework | декларативный агент — документ YAML вида Prompt | Импорт декларативного агента Microsoft Agent Framework |
aggrega import — полный справочник по команде: каждый флаг, как распознаётся источник, что меняет --sync и что он отклоняет. Файл ответов импорта описывает файл ответов: где он находится, что содержит и как отвечать на секрет.