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

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:

  1. Wybierz encję należącą do Twojej roli.
  2. Poznaj jej kształt z JSON Schema i strony referencyjnej.
  3. Zacznij od szkieletu, a nie od pustego pliku.
  4. Wypełnij pola należące do Twojej roli, pozostawiając resztę ich właścicielom.
  5. 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 --list wymienia każdy rodzaj, o który można zapytać. Asystent odczytuje te same bajty z zasobu schema://<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 zasobu langref://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, a aggrega validate --release <release> sprawdza wszystko, do czego sięga encja Release, łącznie z jej encjami Aggregate i Manifest. aggrega lint uruchamia reguły dyscypliny publikacji na encji katalogu, a aggrega inspect rozwią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ępnie aggrega 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 oraz authoring://<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, oraz get-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