Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Import

aggrega import odczytuje projekt zapisany w innym formacie — przepływ wyeksportowany z Langflow, konfigurację klienta MCP, plik Compose i pozostałe formaty wymienione poniżej — i zapisuje na jego podstawie pliki Aggrega: encję Aggregate, encję Release oraz, dla celu wskazanego przez --target, encję Manifest. Razem tworzą obszar roboczy, który przechodzi walidację i kompiluje się w zapisanej postaci, gdy tylko zostaną udzielone odpowiedzi na nieliczne wartości, których żadne źródło nie może zawierać: import pyta o każdą z nich raz i przechowuje odpowiedzi w pliku odpowiedzi. Niczego nie wdraża i nie łączy się z żadnym klastrem ani kontem w chmurze. Wersje robocze to zwykłe pliki w obszarze roboczym, a dalsze postępowanie z nimi należy do użytkownika.

  • LangGraph
  • CrewAI
  • n8n
  • Dify
  • Langflow
  • Flowise
  • Google ADK
  • Microsoft Agent Framework
  • MCP client configurations
  • Compose
aggrega import

robocze pliki Aggrega

do przejrzenia i edycji

Na wejściu istniejący projekt, na wyjściu robocze pliki Aggrega. Nic nie jest wdrażane; najpierw należy przejrzeć wersje robocze.

Co daje import

  • Projekt trafia do Aggrega bez ręcznego przepisywania. Wygenerowane encje Aggregate, Release i Manifest to ten sam rodzaj plików, który napisałoby się samodzielnie. Kompilują się w zapisanej postaci dla celu wskazanego przez import, a każda polityka zarządzania dołączona w obszarze roboczym ocenia tę kompilację tak jak każdą inną.
  • To, co określa źródło, zostaje przeniesione. Węzeł lub usługa, dla których katalog zawiera silne dopasowanie, odwołuje się do tej encji Component z katalogu, z wartościami nadanymi jej przez źródło, takimi jak model wskazany przez przepływ. Platforma, na której działa źródło, jest zapisywana w wersji roboczej z obrazem uruchamianym przez encje Recipes z katalogu dla tej platformy. Sekret jest zapisywany jako odwołanie do miejsca, z którego pochodzi, nigdy jako jego wartość.
  • Pytania dotyczą tylko tego, czego żadne źródło nie może zawierać, i padają jeden raz. Odpowiedzi są przechowywane w pliku odpowiedzi obok źródła, więc kolejny import tego samego źródła o nic nie pyta.
  • Wersje robocze należą do użytkownika. To zwykły YAML w obszarze roboczym i nie pozostaje po nich nic, od czego zależałaby kompilacja. Można je edytować, zmieniać ich nazwy i commitować.
  • Wersja robocza może podążać za źródłem. aggrega import --sync uaktualnia wersje robocze z wcześniejszego importu do stanu zmienionego źródła, zmieniając tylko to, co zapisał import. Jeśli źródło zmieniło część, która została zmodyfikowana ręcznie, polecenie zatrzymuje się i wskazuje tę część, zamiast nadpisać wprowadzoną zmianę.

Czego nie robi

Import zapisuje w wersji roboczej to, co określa źródło, i to, co wyznacza katalog, a o resztę pyta. Każda wersja robocza informuje w komentarzu obok wartości, skąd pochodzi zapisana przez nią wartość.

  • Nie zgaduje tego, czego źródło nie może określić. Żadne źródło nie wskazuje środowiska, w którym wdrażana jest encja Release, więc wygenerowana encja Release wskazuje development, z komentarzem informującym, że jest to wartość domyślna do zmiany. Wartość, której wymaga katalog, a której nie zawiera żadne źródło — adres e-mail konta właściciela, obraz aplikacji zbudowanej z własnego kodu, nazwa obiektu Secret w Kubernetes — jest zapisywana jako pusta i wymaga odpowiedzi, jak opisuje sekcja Jak przebiega import poniżej.
  • Nie odczytuje kodu. Własny program przepływu lub projektu nie jest odczytywany: program załogi CrewAI, kod grafu aplikacji LangGraph, kod źródłowy komponentu Langflow poza przeniesieniem go wewnątrz przepływu.
  • Nie ocenia, co oznacza wartość. Każdy węzeł lub usługa jest porównywany z encjami Components z katalogu obszaru roboczego — ich nazwami, kategoriami, etykietami i nazwami deklarowanych przez nie wartości. Dopasowanie z wysokiego progu jest wskazywane w wersji roboczej; słabsze jest zapisywane jako komentarz wskazujący encję Component i jej wynik punktowy, a wybór należy do użytkownika.
  • Nie zmienia wersji uruchamianej przez platformę, aby podążać za źródłem. Obraz platformy jest zapisywany w wersji, o której wiadomo, że uruchamiają ją encje Recipes z katalogu dla tej platformy, a gdy źródło wskazuje inną wersję, wskazuje ją komentarz obok obrazu.
  • Nie usuwa poświadczeń ze źródła za użytkownika. Wartość, która może zawierać klucz — wartość środowiskowa, nagłówek, wiersz polecenia serwera MCP — jest domyślnie przenoszona do wersji roboczej w postaci, w jakiej została zapisana, a import wskazuje każdą z nich w ostrzeżeniu credential-carried, nigdy przez jej wartość. Ustawienie empty_credentials importera zapisuje je zamiast tego jako puste (Ustawienia). Przed udostępnieniem wersji roboczej należy przeczytać ostrzeżenia.
  • Niczego nie wdraża ani nie uruchamia. Odczytuje źródło i katalog, a następnie zapisuje pliki. Kompilacja wersji roboczych i uruchomienie tego, co zapisze kompilacja, to osobne kroki wykonywane przez użytkownika.

Jak przebiega import

Import można uruchomić poleceniami poniżej albo zlecić to asystentowi AI.

  1. Punktem wyjścia jest obszar roboczy. Import zapisuje wersje robocze w obrębie folderu głównego obszaru roboczego, w którym jest uruchamiany — folderu zawierającego plik .aggrega-config.yaml z kluczem workspace — lub w obrębie folderu wskazanego przez --output-dir. Nigdy nie nadpisuje istniejącej już tam encji Aggregate.

  2. Katalog używany do porównania. Import ocenia źródło względem encji Components z katalogu obszaru roboczego i niczego innego. Jeśli obszar roboczy nie wskazuje własnego folderu katalogu, jest to katalog biblioteki standardowej, odczytywany z domyślnego rejestru obszaru roboczego: każda publikacja katalogu publikuje podpisaną migawkę całego katalogu, a pierwszy import pobiera tę migawkę, weryfikuje jej podpis, przechowuje ją w pamięci podręcznej treści obszaru roboczego i wskazuje ją przez jej skrót w zapisie, który umieszcza obok szkiców, dzięki czemu późniejszy import tych samych szkiców odczytuje ten sam katalog bez ponownego odpytywania rejestru. Względem niego usługa PostgreSQL jest dopasowywana do core/datastore/postgres, a --target tworzy roboczą encję Manifest na podstawie encji Recipes z katalogu. Bez katalogu import nie ma do czego dopasowywać, a --target jest odrzucane, ponieważ żadna encja Recipe nie jest powiązana z celem.

    Obszar roboczy, który wskazuje własne foldery katalogu, importuje zamiast tego względem nich i nie pobiera żadnej migawki: folderów wymienionych w workspace.catalog_dirs, folderu catalog w folderze głównym obszaru roboczego lub folderów wskazanych przez AGGREGA_CATALOG_DIRS. Pliki samego katalogu biblioteki standardowej to folder aggrega-catalog repozytorium aggrega-hub, https://github.com/aggrega-ai/aggrega-hub, dla obszaru roboczego, który chce mieć je jako folder. --upgrade pobiera najnowszą migawkę publikowaną przez rejestr i od tej pory importuje względem niej; przy --offline import, który musiałby pobrać migawkę, zatrzymuje się i wskazuje, co należy uruchomić.

  3. Uruchomienie importu. Należy wskazać plik lub folder:

    Terminal window
    aggrega import compose.yaml --target compose

    Format jest rozpoznawany na podstawie nazwy i zawartości pliku; --format wskazuje go tam, gdzie rozpoznanie się nie udaje. --target wskazuje możliwość dostawcy, taką jak compose lub helm, i tworzy roboczą encję Manifest, która przypisuje każdy typ komponentu i każdy typ funkcji potrzebny szkicom do encji Recipe o tej możliwości, oferowanej dla niego przez katalog: tej jedynej, która istnieje, lub, spośród kilku, tej nazwanej od typu. Robocza encja Release wskazuje tę encję Manifest, a zawartość szkiców zależy od celu: w compose sekret jest odwołaniem do zmiennej, które Docker Compose wypełnia z powłoki, w helm — nazwą obiektu Kubernetes Secret. Na standardowym wyjściu błędów import podaje odczytany format, każde ostrzeżenie i po jednym wierszu dla każdego zmapowanego węzła; na standardowym wyjściu wymienia zapisane pliki.

  4. Odpowiedź na to, czego nie zawiera żadne źródło. Na wartość wymaganą przez katalog, której żadne źródło nie może zawierać — adres e-mail konta właściciela, obraz aplikacji zbudowanej z własnego kodu, nazwę obiektu Kubernetes Secret — odpowiada się raz. Import odczytuje odpowiedzi z import-answers.yaml obok źródła lub z pliku wskazanego przez --answers; w terminalu pyta o każdą wciąż brakującą wartość, po jednym pytaniu naraz, i zapisuje odpowiedzi w tym pliku. Na sekret odpowiada się wskazaniem, skąd pochodzi — zmienną lub nazwą obiektu Secret — nigdy jego wartością. Tam, gdzie nie można o nic zapytać — w ciągłej integracji, przez potok, z asystenta lub edytora — import zapisuje plik odpowiedzi z kluczem każdej brakującej wartości i pustą odpowiedzią, wymienia je i kończy działanie ze statusem 1; należy je uzupełnić i ponownie uruchomić import. Jeden plik odpowiedzi służy każdemu celowi: odpowiedź, której szkice dla danego celu nie potrzebują, pozostaje w pliku i nie jest używana. Plik odpowiedzi importu opisuje ten plik w całości.

  5. Import pobiera to, czego potrzebuje kompilacja. Gdy niczego już nie brakuje, import pobiera zależności roboczej encji Release, tak jak robi to aggrega pull, i zapisuje obok niej release.lock. W trybie --offline niczego nie pobiera i wskazuje polecenie aggrega pull do uruchomienia.

  6. Walidacja i kompilacja. W folderze zawierającym wersje robocze:

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

    Gdy oba polecenia zakończą się powodzeniem, kompilacja ma już zapisane pliki celu w dist/. Odmowa wskazuje, co i gdzie należy zmienić, w dokumencie, który się zmienia.

  7. Należy uruchomić to, co zapisała kompilacja. Kompilacja dla Docker Compose zapisuje dist/compose/docker-compose.yaml, a plik nie wskazuje żadnego projektu Compose, więc nazwę projektu należy podać za pomocą -p:

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

    Bez -p Docker Compose nazywa projekt od folderu zawierającego plik, compose, więc dwa obszary robocze uruchomione w ten sposób współdzielą jeden projekt. Usługi znajdują się w jednej sieci, którą Docker Compose nazywa od projektu, <name>_compose. Do usługi, dla której build nie publikuje żadnego portu, można dotrzeć z wnętrza tej sieci, poleceniem docker compose -p <name> -f dist/compose/docker-compose.yaml exec <service> …, lub z kontenera uruchomionego w tej sieci poleceniem docker run --network <name>_compose …. Sekcje „Uruchomienie” i „Test” przewodnika pokazują polecenia dla jego własnego buildu.

    Uruchomienie odpowiada bez klucza OpenAI, gdy jego model core/ai-model/openai wskazuje na mały model serwowany przez Ollama w tym samym projekcie, przy trzech zmianach w utworzonych plikach roboczych, kompilacji z --auto-pull, która pobiera to, czego potrzebuje dodany komponent, i jednym poleceniu po uruchomieniu stacku:

    • w encji Aggregate jeszcze jeden komponent, niepołączony z niczym: local-model, typu core/ai-model/ollama, z model: qwen2.5:0.5b w jego values;
    • w encji Manifest jego Recipe dla Compose: core/ai-model/ollama: compose/ollama;
    • w encji Release local-model: {} oraz klucz endpoint modelu OpenAI, w jego infra, ustawiony na zgodny z OpenAI adres tego serwera, http://local-model:11434/v1;
    • po uruchomieniu stosu pobrany model skopiowany pod nazwą modelu, którą wskazuje model OpenAI buildu, <model>, na przykład gpt-4o-mini lub 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 może wtedy zawierać dowolną własną niepustą wartość: lokalny serwer żadnej nie sprawdza. Przepływ pracy n8n odczytuje adres i klucz modelu z poświadczenia wybranego przez jego węzeł modelu, a nie z adresu dostarczanego przez endpoint, dlatego należy przekazać temu poświadczeniu również adres serwera, jako url obok apiKey w jego data. Serwer Ollama uruchamiany domyślnie przez core/ai-model/ollama obsługuje oprócz Chat Completions również Responses API OpenAI, dlatego deklaratywny agent Agent Framework, który wskazuje apiType: Responses, dociera do niego w postaci, w jakiej został napisany.

    Build dla Kubernetes, cel helm, zapisuje zwykłe manifesty zamiast chartu, jak opisuje to dostawca helm: w dist/helm/ lub, w przypadku komponentów, które encja Release umieszcza w granicy, w dist/boundaries/<boundary>/helm/, niektóre z nich we własnym folderze poniżej. Pliki, które nie wskazują przestrzeni nazw, jak pliki buildów MCP i Dify, trafiają do tej, którą wskazuje kontekst kubectl, lub do default, jeśli nie wskazuje żadnej; najpierw należy tam utworzyć obiekty Secrets, które te pliki odczytują, a następnie zastosować folder:

    Terminal window
    kubectl apply -R -f dist/helm/

    -R obejmuje pliki w tych folderach. Obiekt Service typu ClusterIP, czyli typu, który buildy MCP i Dify nadają uruchamianym serwerom, jest osiągalny tylko z wnętrza klastra: aby dotrzeć do niego z własnej maszyny, należy przekierować do niego lokalny port za pomocą kubectl port-forward svc/<service> <local port>:<port>; to polecenie działa, dopóki się go nie zatrzyma.

Obok wersji roboczych import zapisuje .aggrega-import.json, zapis tego, co utworzył. Należy go zachować tak długo, jak zamierza się uruchamiać aggrega import --sync, które odczytuje go, aby odróżnić zmiany użytkownika od własnych. Należy też zachować plik odpowiedzi: nie zawiera żadnego sekretu, więc może znajdować się w systemie kontroli wersji obok źródła, a każdy późniejszy import tego źródła go odczytuje.

Z asystentem AI

Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić do niego ten prompt.

Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Wywołaj narzędzie `import` z `source` ustawionym na `compose.yaml` i `target` ustawionym na `compose`: zapisuje ono swoje wersje robocze w folderze Workspace. Jeśli poinformuje, że wciąż brakuje wartości, podaj mi każdą z nich i wyjaśnij, czym jest, i poczekaj, aż wpiszę odpowiedzi obok ich kluczy w pliku odpowiedzi, który wskaże; następnie wywołaj ponownie narzędzie `import` w ten sam sposób. Potem wywołaj narzędzie `validate` z `release` ustawionym na `release.yaml` oraz narzędzie `build` z `release` ustawionym na `release.yaml` i `write` ustawionym na true. Powiedz mi, które pliki zapisał build; znajdują się w `dist/` w folderze Workspace.

Otwieranie w VS Code

Po zainstalowaniu rozszerzenia Aggrega dla Visual Studio Code należy otworzyć w VS Code obszar roboczy, w którym uruchomiono import — folder zawierający jego .aggrega-config.yaml: wersje robocze są w nim, w katalogu głównym lub w folderze wskazanym przez --output-dir. Gdy obszar roboczy zawiera jedną encję Release, edytor sam ją wybiera; gdy zawiera ich więcej, Aggrega: Select Release… wybiera tę, na której pracuje edytor. Edytor sprawdza wersje robocze względem wybranej encji Release podczas edycji, oznaczając to, co znajdzie, w pliku i w panelu Problemy. Aggrega: Show topology graph w palecie poleceń rysuje komponenty wybranej encji Release i połączenia między nimi. Aggrega: Build, Aggrega: Preview build i Aggrega: Pull działają na tej samej encji Release, a każde z nich jest też przyciskiem w panelu Commands widoku Aggrega na pasku działań; Build zapisuje swoje pliki w katalogu dist/ obszaru roboczego. Resztę omawia Korzystanie z Aggrega w Visual Studio Code.

Skąd pochodzą importery

Każdy format jest odczytywany przez wtyczkę importera. Podstawowe importery kompilatora, po jednym dla każdego formatu z poniższej tabeli, są publikowane z każdym wydaniem kompilatora i obsługują swoje formaty w każdym obszarze roboczym, bez żadnego wpisu w katalogu. Pierwszy import, który potrzebuje któregoś z nich, pobiera go z domyślnego rejestru obszaru roboczego, w wersji samego kompilatora, weryfikuje go i przechowuje w pamięci podręcznej treści obszaru roboczego, dzięki czemu każdy kolejny import odczytuje go stamtąd, bez łączenia się w tym celu z siecią. Jeśli modułu w ogóle nie da się pobrać — na przykład gdy obszar roboczy jest offline — import zatrzymuje się i wskazuje dwa sposoby umieszczenia go na maszynie. Podstawowe importery opisują każdy importer w całości, a także ustawienia przekazywane importerowi przez wpis plugins.importer.

Formaty

FormatCo odczytujePrzewodnik
Composeplik Compose i jego plik nadpisań albo folder, który je zawieraImport projektu Compose
Konfiguracje klientów MCP.mcp.json, claude_desktop_config.json, .vscode/mcp.json, .cursor/mcp.json lub server.json z rejestru MCPImport konfiguracji klienta MCP
Langflowprzepływ wyeksportowany z Langflow, jako JSONImport przepływu Langflow
Flowisechatflow lub agentflow wyeksportowany z Flowise, jako JSONImport chatflow z Flowise
n8nprzepływ pracy wyeksportowany z n8n, jako JSONImport workflow z n8n
Difyaplikację wyeksportowaną z Dify w jej DSL, jako YAMLImport aplikacji Dify
CrewAIdeklaracje agentów i zadań projektu CrewAIImport projektu CrewAI
LangGraphplik langgraph.json aplikacji LangGraphImport aplikacji LangGraph
Google ADKpliki Agent Config aplikacji zbudowanej na Google ADK, począwszy od root_agent.yamlImport agenta Google ADK
Microsoft Agent Frameworkagent deklaratywny, dokument YAML rodzaju PromptImport agenta deklaratywnego Microsoft Agent Framework

aggrega import to pełna dokumentacja referencyjna polecenia: każda flaga, sposób rozpoznawania źródła, co zmienia --sync i czego odmawia. Plik odpowiedzi importu opisuje plik odpowiedzi: gdzie się znajduje, co zawiera i jak udziela się odpowiedzi na sekret.