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

Импорт

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 вместо этого записывает их пустыми (Настройки). Прочитайте предупреждения, прежде чем делиться черновиком.
  • Он ничего не развёртывает и не запускает. Он читает источник и ваш каталог и записывает файлы. Сборка черновиков и запуск того, что записала сборка, — это отдельные шаги, которые выполняете вы.

Как выполняется импорт

Импорт можно выполнить командами ниже или поручить его вашему ИИ-ассистенту.

  1. Начните с рабочего пространства. Импорт записывает свои черновики внутри корня рабочего пространства, в котором он запущен, — папки, содержащей .aggrega-config.yaml с ключом workspace, — или внутри директории, которую задаёт --output-dir. Он никогда не перезаписывает уже существующую там сущность Aggregate.

  2. Каталог для сопоставления. Импорт оценивает ваш источник относительно сущностей 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 импорт, которому пришлось бы получить снимок, останавливается и называет, что нужно запустить.

  3. Запустите импорт. Укажите файл или директорию:

    Terminal window
    aggrega import compose.yaml --target compose

    Формат распознаётся по имени и содержимому файла; там, где это не так, его задаёт --format. --target задаёт возможность провайдера, например compose или helm, и создаёт черновик сущности Manifest, сопоставляющий каждый тип компонента и каждый тип функции, нужный черновикам, с той сущностью Recipe этой возможности, которую ваш каталог предлагает для него: с единственной имеющейся или, среди нескольких, с той, что названа по типу. Черновик сущности Release называет эту сущность Manifest, а содержимое черновиков зависит от цели: для compose секрет — это ссылка на переменную, которую Docker Compose заполняет из вашей оболочки, для helm — имя Kubernetes Secret. В стандартный поток ошибок импорт выводит название прочитанного формата, каждое предупреждение и по одной строке на каждый сопоставленный узел; в стандартный вывод — список записанных файлов.

  4. Ответьте на то, чего не содержит ни один источник. На значение, которого требует каталог и которое не может содержать ни один источник, — адрес электронной почты учётной записи владельца, образ приложения, собранного из вашего собственного кода, имя Kubernetes Secret — отвечают один раз. Импорт читает ответы из import-answers.yaml рядом с источником или из файла, который задаёт --answers; в терминале он запрашивает каждое ещё отсутствующее значение, по одному вопросу за раз, и записывает ваши ответы в этот файл. На секрет отвечают тем, откуда он берётся, — переменной или именем Secret, — и никогда его значением. Там, где ничего нельзя спросить, — в непрерывной интеграции, через конвейер, из ассистента или редактора — импорт записывает файл ответов с ключом каждого отсутствующего значения и пустым ответом, перечисляет их и завершается со статусом 1; заполните их и запустите импорт снова. Один файл ответов служит всем целям: ответ, который не нужен черновикам для какой-либо цели, сохраняется в файле и остаётся неиспользованным. Файл ответов импорта полностью описывает этот файл.

  5. Импорт загружает то, что нужно сборке. Как только ничего не отсутствует, импорт загружает зависимости черновика сущности Release, как это делает aggrega pull, и записывает рядом release.lock. С --offline он ничего не загружает и называет команду aggrega pull, которую следует выполнить.

  6. Проверьте и соберите. В папке с черновиками:

    Terminal window
    aggrega validate --release release.yaml
    aggrega build --release release.yaml

    Когда обе команды проходят, сборка уже записала файлы цели в dist/. Отказ называет, что изменить и где, в документе, который вы изменяете.

  7. Запустите то, что записала сборка. Сборка для Docker Compose записывает dist/compose/docker-compose.yaml, и этот файл не задаёт имени проекта Compose, поэтому задайте его с помощью -p:

    Terminal window
    docker compose -p <name> -f dist/compose/docker-compose.yaml up -d

    Без -p Docker 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>; эта команда работает, пока вы её не остановите.

Рядом со своими черновиками импорт записывает .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
Flowisechatflow или agentflow, экспортированный из Flowise, в формате JSONИмпорт chatflow Flowise
n8nрабочий процесс, экспортированный из n8n, в формате JSONИмпорт рабочего процесса n8n
Difyприложение, экспортированное из Dify на его DSL, в формате YAMLИмпорт приложения Dify
CrewAIобъявления агентов и задач проекта CrewAIИмпорт проекта CrewAI
LangGraphlanggraph.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 и что он отклоняет. Файл ответов импорта описывает файл ответов: где он находится, что содержит и как отвечать на секрет.