Tworzenie plików Aggrega
Tworzenie w Aggrega to krótka, powtarzalna pętla. Niezależnie od tego, jaką encję się pisze — encję Aggregate programisty, encję Component architekta, encję Recipe zespołu operacyjnego czy encję Release operatora — te same pięć kroków prowadzi od pustego pliku do zwalidowanego:
- Wybierz encję należącą do Twojej roli.
- Poznaj jej kształt z JSON Schema i strony referencyjnej.
- Zacznij od szkieletu, a nie od pustego pliku.
- Wypełnij pola należące do Twojej roli, pozostawiając resztę ich właścicielom.
- Zwaliduj, a następnie skompiluj.
Ta strona przechodzi przez pętlę raz, zarówno dla osoby tworzącej ręcznie, jak i dla asystenta AI tworzącego przez serwer Model Context Protocol. Obie ścieżki to ta sama pętla na tych samych materiałach referencyjnych. Obie wymagają pliku binarnego aggrega: Instalacja pliku binarnego instaluje go jednym poleceniem.
1. Wybierz encję należącą do Twojej roli
Aggrega dzieli tworzenie na cztery współpracujące role — intencję programisty, katalog platformy, receptury infrastruktury i okablowanie wdrożenia. Każda rola zazwyczaj odpowiada za określony zestaw rodzajów encji. Jeśli rola jest już znana, można przejść od razu do potrzebnej encji; jeśli nie, należy przeczytać Persony, gdzie opisano cztery role, oraz Encje według ról, gdzie znajduje się pełne przypisanie rodzajów do ról.
Ten podział jest wskazówką, a nie regułą wymuszaną przez kompilator. Pojedynczy autor może pełnić wszystkie role i napisać wszystkie encje za jednym razem; kompilator akceptuje każdy sposób tworzenia, który przechodzi walidację schematu. Role służą przejrzystemu rozdzieleniu odpowiedzialności, a nie ograniczaniu tego, co wolno napisać.
2. Poznaj jej kształt
Każdy rodzaj encji ma kanoniczny JSON Schema i stronę referencyjną opisującą pole po polu. Przed pisaniem należy przeczytać oba:
- Schemat to dokładna struktura: pola wymagane, dozwolone wartości i zagnieżdżenie. W wierszu poleceń wyświetla go
aggrega get-schema <kind>;aggrega get-schema --listwymienia każdy rodzaj, o który można zapytać. Asystent odczytuje te same bajty z zasobuschema://<kind>. Zobacz dokumentacjęaggrega get-schema. - Strona referencyjna wyjaśnia, co każde pole oznacza i jak pola są ze sobą powiązane. Strony encji znajdują się w
language-reference/entities/— na przykład component lub aggregate. Asystent odczytuje tę samą stronę z zasobulangref://entities/<kind>.
Schemat mówi, co jest poprawne strukturalnie; dokumentacja referencyjna mówi, co jest sensowne. Schemat należy czytać, aby uniknąć odrzucenia podczas walidacji, a dokumentację referencyjną, aby napisać coś, co robi to, co zamierzono.
3. Zacznij od szkieletu
Rozpoczęcie od szkieletu jest szybsze i mniej podatne na błędy niż pusty plik. Asystent połączony z serwerem MCP wywołuje narzędzie scaffold z rodzajem i nazwą, aby otrzymać minimalny punkt wyjścia zawierający każde pole wymagane przez dany rodzaj, z symbolem zastępczym wszędzie tam, gdzie wartość jest jeszcze do uzupełnienia. Przy tworzeniu ręcznym aggrega scaffold <kind> <name> wypisuje ten sam punkt wyjścia na standardowe wyjście, więc należy przekierować go do pliku; można też skopiować najbliższy przykład i okroić go do tego, co potrzebne.
W obu przypadkach szkielet zawiera już wymagane pola najwyższego poziomu (apiVersion, kind, metadata.name) we właściwym kształcie, dzięki czemu uwagę można poświęcić polom należącym do swojej roli, a nie powtarzalnemu szablonowi.
4. Wypełnij pola należące do Twojej roli
Należy wypełniać tylko filary, za które odpowiada dana rola, a pozostałe zostawić ich właścicielom. Programista dostarcza intencję aplikacji i wartości; architekt deklaruje kontrakt — wartości, które programista może podać, wyjścia udostępniane przez komponent, gniazda, które on wystawia; zespół operacyjny odwzorowuje ten kontrakt na konkretnego dostawcę bez zmiany powierzchni widocznej dla programisty; operator okablowuje wdrożenie. Encje według ról wyszczególnia, które filary należą do której roli dla każdego rodzaju.
Trzymanie każdej wartości w filarze kontrolowanym przez jej właściciela pozwala tej samej intencji programisty celować w różną infrastrukturę w różnych środowiskach bez zmiany pliku programisty. To właśnie dlatego powierzchnia tworzenia jest w ogóle podzielona.
Opis należy ograniczyć do kilku krótkich akapitów. Pole metadata.description encji to tekst, który czytelnik widzi przed jej wybraniem: jest publikowany wraz z encją jako jej przeszukiwalny opis, a aggrega search dopasowuje do niego zapytanie. Należy pisać go z myślą o tej chwili, w krótkich akapitach — w zwiniętym bloku description: > pusty wiersz rozpoczyna nowy akapit — opisując, czym jest encja, jak czytelnik jej używa, gdzie jest realizowana i czego nie robi. Ograniczenie, które czytelnik musi znać przed wyborem encji, również należy tam umieścić, krótko. Wszystko inne — dlaczego wartość domyślna jest taka, a nie inna, jak ustawienie zachowuje się na jednym celu, co wartość oznacza w każdej realizacji — trafia do komentarzy YAML obok pola lub bloku, który wyjaśnia, gdzie przeczyta je osoba pracująca z tym polem. Nic w kompilatorze nie ogranicza długości opisu ani nie reaguje na jego treść, więc zwięzłość służy czytelnikowi.
5. Zwaliduj, a następnie skompiluj
Plik należy sprawdzić, zanim się na nim polega:
- Asystent wywołuje narzędzie
validate, które zgłasza błędy schematu i odwołań bezpośrednio, aby mógł poprawić szkic przed jego zwróceniem. - Ręcznie
aggrega validate <file>sprawdza pojedynczy plik encji Component, Feature, Recipe, FeatureRecipe, Workload lub Plugin, aaggrega validate --release <release>sprawdza wszystko, do czego sięga encja Release, łącznie z jej encjami Aggregate i Manifest.aggrega linturuchamia reguły dyscypliny publikacji na encji katalogu, aaggrega inspectrozwiązuje i pokazuje to, co widzi kompilator. Gdy cała topologia jest gotowa,aggrega pull --release <release>rozwiązuje jej zależności i zapisuje plik blokady, a następnieaggrega build --release <release>kompiluje encję Release do artefaktów dla poszczególnych granic — nieudana kompilacja wskazuje dokładnie, co należy poprawić.
Wczesna walidacja jest tańsza niż późna nieudana kompilacja. Należy pisać, walidować, poprawiać i dopiero wtedy kompilować.
Tworzenie z asystentem AI
Polecenie aggrega mcp uruchamia serwer Model Context Protocol, który zmienia dowolnego klienta obsługującego MCP w asystenta tworzenia znającego Aggrega. Po połączeniu asystent może:
- Przyjąć rolę za pomocą wbudowanych promptów tworzenia — po jednym na personę (programista, architekt, zespół operacyjny) oraz ukierunkowanego szablonu dla pojedynczej encji. Każdy prompt określa rolę i kieruje asystenta do schematu, strony referencyjnej i tego przewodnika, dzięki czemu jego sugestie pozostają w obrębie filarów należących do roli.
- Czytać dokumentację referencyjną przez zasoby:
schema://<kind>dla JSON Schema danego rodzaju,langref://<path>dla dowolnej strony referencyjnej orazauthoring://<topic>dla tego przewodnika. - Działać w przestrzeni roboczej przez narzędzia:
scaffold, aby utworzyć poprawny szkielet,validate, aby sprawdzić szkic,describe, aby obejrzeć encję katalogu, orazget-schema, aby pobrać schemat według rodzaju.
Wszystko, co czyta asystent, jest serwowane z lokalnej maszyny: schematy są wbudowane w plik binarny, a strony przewodnika i dokumentacji pochodzą z pakietu dokumentacji przechowywanego w pamięci podręcznej maszyny, który serwer pobiera z rejestru, gdy przy uruchomieniu nie znajdzie tam kopii. Czytanie strony, tworzenie szkieletu i walidacja nie łączą się z siecią; tam, gdzie pakietu nie można pobrać, schematy są nadal serwowane, a strony nie. Aby połączyć klienta, należy postępować zgodnie ze stroną Połączenie z serwerem MCP; pozostałe rzeczy, do których asystent ma dostęp, opisuje strona Co asystent może zrobić z Aggrega. Opis samego polecenia znajduje się w dokumentacji aggrega mcp.
Co dalej
- Persony — poznaj cztery role, zanim wybierzesz encję.
- Encje według ról — pełne przypisanie rodzajów do ról.
- Instalacja — zainstaluj plik binarny; połączenie asystenta opisuje Połączenie z serwerem MCP.
- Konfiguracja Aggrega za pomocą asystenta AI — jeden prompt, dzięki któremu asystent sam instaluje i podłącza Aggrega.
- Przegląd CLI — każde podpolecenie
aggrega.