Przegląd CLI
CLI aggrega jest punktem wejścia kompilatora. Każda interakcja z Aggrega — kompilowanie encji Aggregate do artefaktów gotowych do wdrożenia, inspekcja katalogu lub IR, rozwiązywanie i przypinanie zależności, publikowanie encji katalogu, sprawdzanie poprawności za pomocą validate, sprawdzanie konwencji publikowania za pomocą lint oraz obsługa IDE — odbywa się przez podpolecenie aggrega. Ten zestaw rozdziałów opisuje flagi, dane wejściowe i dane wyjściowe każdego podpolecenia.
aggrega validate i aggrega lint to uzupełniające się narzędzia sprawdzające, które odzwierciedlają nawzajem swoje trzy zakresy — cały katalog, domknięcie zależności encji Release lub jedną encję. aggrega validate sprawdza poprawność (schemat, filary, rozwiązywanie referencji, extends, obsługę rodzajów danych wejściowych przez dostawcę oraz — w przypadku encji renderującej — izolowane renderowanie); aggrega lint sprawdza konwencje publikowania (nazewnictwo, zgodność z katalogiem kategorii, prefiksy adnotacji i wielkość podbicia wersji). Żadne z nich nie emituje artefaktów; należy używać validate, aby odpowiedzieć na pytanie „czy to jest poprawne?”, a lint, aby odpowiedzieć na pytanie „czy to jest zgodne z dyscypliną publikowania katalogu?”.
aggrega build stosuje zasadę pojedynczego punktu wejścia (Single Entry Point Principle): Release jest jedynym wejściem kompilacji. aggrega build --release release.yaml odczytuje wskaźniki aggregate: i manifest: encji Release, aby zlokalizować resztę topologii, i generuje dane wyjściowe dla każdej granicy w dist/: nazwana granica jest renderowana w zadeklarowanym katalogu directory: lub w dist/boundaries/<boundary-name>/, gdy go nie deklaruje; encja Release, która zamiast nazwanych granic deklaruje na najwyższym poziomie components:, jest renderowana płasko w dist/. Każdy komponent, który obejmuje topologia, musi należeć do jednej z tych granic, a komponent nienależący do żadnej z nich zatrzymuje kompilację: komponent trafia do granicy albo przez wymienienie go w components: tej granicy, pod identyfikatorem, który nosi po spłaszczeniu encji sub-Aggregates, albo przez umieszczenie w encji sub-Aggregate, którą granica włącza przez aggregates:. Komponent, który nie trafia do granicy żadną z tych dróg, zostałby wyrenderowany poza każdą granicą zadeklarowaną przez encję Release i nie miałby skąd wziąć lokalizacji wyjściowej, fali synchronizacji, adnotacji ani infra: dla komponentu, dlatego kompilacja zatrzymuje się i wskazuje ten komponent, zamiast generować artefakty, do których nigdy nie zastosowano konfiguracji granic encji Release. Ta sama relacja jest sprawdzana od strony encji Release: wpis granicy wskazujący komponent, którego topologia nie obejmuje, niczego nie konfiguruje, więc również zatrzymuje kompilację, a komunikat diagnostyczny podaje identyfikator, do którego odnosił się wpis. aggrega pull również przyjmuje Release jako wejście; aggrega inspect przyjmuje dowolną encję — nazwę z katalogu, plik encji, odwołanie do rejestru lub encję Release; aggrega push przyjmuje encję katalogu; aggrega validate i aggrega lint przyjmują encję katalogu, encję Release (przez --release) lub cały katalog; aggrega serve działa jako długotrwały proces. Strona flag globalnych opisuje flagi wspólne dla wszystkich podpoleceń.
To, co wydanie może zmienić w poleceniach, flagach i narzędziach asystenta — oraz czego wydanie poprawkowe nigdy nie zmienia — opisano w sekcji Zgodność.
Opis poszczególnych poleceń
aggrega build— główne polecenie kompilacji. Odczytuje wskaźnik encji Release, rozwiązuje wskazane przez nią encje Aggregate i Manifest oraz emituje skompilowane artefakty dla poszczególnych granic.aggrega inspect— czytelny widok dowolnej encji: encji katalogu wskazanej nazwą, pliku encji wskazanego ścieżką, opublikowanej encji odczytanej bezpośrednio z jej rejestru albo w pełni rozwiązanej encji Release, której graf IR--ir-graphzapisuje jako JSON, a której domknięcie zależności raportuje--closure.aggrega pull— rozwiązuje zależności encji Release i zapisuje plik blokady dla danej encji Release, przypinający każdą zależność; buforuje encje katalogu i artefakty źródłowe.aggrega push— publikuje encję katalogu w rejestrze OCI, opcjonalnie podpisując ją w momencie publikacji.aggrega sign— podpisuje jeden lub więcej już opublikowanych artefaktów i dołącza każdy podpis jako referrer OCI.aggrega auth token— interaktywnie uzyskuje token tożsamości OIDC i wypisuje go na stdout, aby jedno uwierzytelnienie obsłużyło serię podpisów bezkluczowych.aggrega registry— zarządza rejestrami znanymi obszarowi roboczemu i ich polityką zaufania do podpisów: dodaje, wyświetla i usuwa wpisy oraz za pomocąregistry updatebuduje lokalny, przeszukiwalny indeks opublikowanych metadanych katalogu.aggrega search— przeszukuje lokalny indeks skonfigurowanych rejestrów w poszukiwaniu opublikowanych encji katalogu i instalowalnych wtyczek CLI, dopasowując zapytanie tekstowe i opcjonalne filtry faset.aggrega validate— sprawdza poprawność (schemat, filary, rozwiązywanie odwołań,extends, obsługa rodzajów wejścia, izolowane renderowanie) w całym katalogu, w domknięciu zależności encji Release (--release) lub w jednej encji.aggrega lint— sprawdza konwencje publikowania w całym katalogu, w domknięciu zależności encji Release (--release) lub w jednej encji;--pre-publishdodaje uwzględniającą rejestr bramkę podbicia wersji.aggrega serve— długo działający demon kompilatora jako usługi (JSON-RPC przez stdin/stdout) do integracji z IDE.aggrega version— wypisuje wersję CLI;-o jsonemituje obiekt do odczytu maszynowego.aggrega get-schema— wypisuje kanoniczny JSON Schema dla rodzaju encji lub kontraktu;--listwymienia wszystkie rodzaje. Wiążący kształt, według którego należy tworzyć plik.aggrega scaffold— wypisuje dokument startowy dla rodzaju encji, wyprowadzony ze schematu tego rodzaju: pola wymagane, z wypełnionymi polami stałymi i symbolem zastępczym wszędzie tam, gdzie potrzebna jest wartość. Tworzenie szkicu nie zapisuje żadnego pliku; wynik można przekierować w dowolne miejsce. Z opcją--examplezamiast tego zapisuje jeden z uruchamialnych przykładów z dokumentacji w nowym katalogu, a--example --listwymienia ich nazwy.aggrega mcp— uruchamia serwer Model Context Protocol przez standardowe wejście i wyjście lub przez HTTP, dzięki czemu klient obsługujący MCP staje się asystentem tworzenia znającym Aggrega. Zob. Tworzenie plików Aggrega.aggrega skills— instaluje umiejętność, która uczy asystenta AI instalowania i używania Aggrega, w folderze umiejętności tego asystenta — dla jednego projektu albo, z--global, dla wszystkich projektów użytkownika.aggrega cache— przeglądanie i utrzymanie pamięci podręcznych na dysku: wyświetlanie ich zawartości, odzyskiwanie wpisów pamięci podręcznej artefaktów, do których nie odwołuje się żaden plik blokady, przycinanie pamięci podręcznej skompilowanych modułów do limitu rozmiaru lub wyczyszczenie wszystkich pamięci podręcznych.aggrega config— przeglądanie konfiguracji, którą odczytuje Aggrega, i zarządzanie nią: wyświetlanie obowiązujących ustawień i warstwy, która rozstrzygnęła każde z nich, przygotowanie działającej konfiguracji oraz zamrożenie ustawień krytycznych dla kompilacji w obszarze roboczym.aggrega deprecate— dołączenie podpisanego znacznika wycofania do już opublikowanego artefaktu.aggrega edit-document— zastosowanie do dokumentu jednej ograniczonej, ustrukturyzowanej edycji z zachowaniem każdego bajtu, którego nie dotyka.aggrega explain— wyjaśnienie warunku zatrzymania wskazywanego przez kod.aggrega import— przekształcenie obcego opisu źródła w robocze pliki autorskie Aggrega.aggrega login— uwierzytelnienie w rejestrze OCI i zapisanie poświadczenia, które przedstawiająpush,pullilint --pre-publish.aggrega logout— usunięcie zapisanego poświadczenia rejestru.aggrega pin— zapisanie przypięć treści dla zewnętrznych danych wejściowych encji w plikuentity.lockobok niej.aggrega plugin— wyświetlanie wtyczek Wasm, które CLI potrafi rozwiązać, dodawanie lub usuwanie powiązania obszaru roboczego oraz sprawdzanie modułu gościa przed jego opublikowaniem.aggrega push-artifact— publikowanie samodzielnego artefaktu danych, takiego jak pakiet dokumentacji, w rejestrze OCI w jego przestrzeni nazwdocs/.- Konfiguracja — w którym pliku należy umieścić dane ustawienie i jak łączą się warstwy. Warto zacząć tutaj: strona otwiera się dwoma plikami potrzebnymi w większości projektów, a mechanizmy, po które sięgają większe projekty, omawia dalej.
- Flagi globalne — flagi wspólne dla podpoleceń (katalog główny obszaru roboczego, globalny plik konfiguracji, kolorowe oraz proste, dostępne wyjście i tryb offline). Tryb offline jest dostępny także jako ustawienie konfiguracji i zmienna środowiskowa — zob. Konfiguracja, schemat konfiguracji i zmienne środowiskowe.
- Granica obszaru roboczego — co znajduje się wewnątrz obszaru roboczego, jak dowiązanie symboliczne prowadzące poza niego wpływa na każdy rodzaj ścieżki, które ścieżki celowo sięgają na zewnątrz i co zrobić, gdy któraś zostanie odrzucona.
| Polecenie | Opis |
|---|---|
aggrega auth | Zarządza tożsamością podpisującą |
aggrega build | Kompiluje encje Aggregate i Release do natywnych artefaktów dostawcy w dist/ w katalogu głównym obszaru roboczego |
aggrega cache | Przegląda i utrzymuje pamięci podręczne na dysku |
aggrega config | Przegląda konfigurację obszaru roboczego i zarządza nią |
aggrega deprecate | Dołącza podpisany znacznik wycofania do już opublikowanego artefaktu |
aggrega edit-document | Stosuje do dokumentu jedną ograniczoną edycję strukturalną, zachowując każdy bajt, którego nie dotyka |
aggrega explain | Wyjaśnia warunek zatrzymania wskazany przez kod |
aggrega get-schema | Wypisuje JSON Schema dla rodzaju encji lub kontraktu |
aggrega import | Przekształca obcy opis źródłowy w szkice plików Aggrega |
aggrega inspect | Przegląda encję katalogu według nazwy, plik encji według ścieżki lub opublikowaną encję według odwołania do rejestru |
aggrega lint | Sprawdza konwencje publikowania katalogu w całym katalogu, w encji Release lub w jednej encji |
aggrega login | Uwierzytelnia w rejestrze OCI i zapisuje poświadczenie |
aggrega logout | Usuwa zapisane poświadczenie rejestru |
aggrega mcp | Uruchamia serwer Model Context Protocol przez standardowe wejście i wyjście lub przez HTTP do integracji z asystentami AI |
aggrega pin | Zapisuje przypięcia treści zewnętrznych wejść encji w pliku entity.lock obok niej |
aggrega plugin | Przegląda wtyczki Wasm, które CLI potrafi rozwiązać |
aggrega pull | Rozwiązuje zależności katalogu i źródeł do pamięci podręcznej i zapisuje plik blokady dla encji Release |
aggrega push | Pakuje i publikuje encję katalogu w rejestrze OCI |
aggrega push-artifact | Publikuje samodzielny artefakt danych (np. pakiet dokumentacji) w rejestrze OCI |
aggrega registry | Zarządza rejestrami i ich polityką zaufania do podpisów |
aggrega scaffold | Tworzy szkic dokumentu startowego dla rodzaju encji lub zapisuje uruchamialny przykład w nowym katalogu |
aggrega search | Przeszukuje lokalny indeks skonfigurowanych rejestrów |
aggrega serve | Działa jako długo działający kompilator jako usługa przez JSON-RPC 2.0 na stdin/stdout |
aggrega sign | Podpisuje jeden lub więcej już opublikowanych artefaktów i dołącza ich podpisy |
aggrega skills | Instalowanie umiejętności Aggrega w asystencie AI |
aggrega validate | Sprawdza poprawność w całym katalogu, w encji Release lub w jednej encji |
aggrega version | Wypisuje wersję CLI aggrega |
Argumenty pozycyjne i kod wyjścia
Każde polecenie odrzuca argument pozycyjny, którego nie wykorzystuje, i sygnalizuje to odrzucenie niezerowym kodem wyjścia, zamiast kończyć działanie tak, jakby wywołanie było poprawne. Zasada obejmuje polecenia, które istnieją wyłącznie po to, by grupować podpolecenia — w nich błędnie wpisana nazwa podpolecenia trafia jako nierozpoznany argument pozycyjny: wypisywana jest pomoc polecenia, a kod wyjścia jest niezerowy, dzięki czemu literówka w skrypcie kończy się wyraźnym błędem, a nie wygląda na udane uruchomienie. aggrega wywołane z nierozpoznanym poleceniem zachowuje się tak samo i dodatkowo podaje najbliższe pasujące polecenie, o ile któreś jest wystarczająco bliskie.
Nierozpoznane polecenie podaje też, jak znaleźć wtyczkę CLI o tej nazwie. Odpowiedź pochodzi z lokalnego indeksu domyślnego rejestru, który buduje aggrega registry update i odczytuje aggrega search, dlatego jest zwracana natychmiast, a błędnie wpisane słowo nigdy nie jest wysyłane do rejestru, ani w trybie online, ani offline. Jeśli indeks zawiera wtyczkę CLI o tej nazwie, komunikat podaje polecenie aggrega plugin add cli <name>, które ją instaluje. Jeśli indeks nie zawiera żadnej, podaje wyszukiwanie, które jej szuka, aggrega search <name> --kind plugin --plugin-type cli. Jeśli indeks nie został jeszcze zbudowany, podaje aggrega plugin add cli <name>, które wyszukuje wtyczkę o tej nazwie w rejestrze i odmawia, gdy żadna nie jest opublikowana. Każde z tych poleceń zawiera nazwę ujętą w cudzysłów dla powłoki tam, gdzie to konieczne.
Tam, gdzie argumenty pozycyjne mają znaczenie, strona referencyjna każdego polecenia opisuje, co ono przyjmuje. Zamierzonym wyjątkiem jest zainstalowana wtyczka CLI: jej polecenie samo zajmuje się parsowaniem argumentów, więc cały wektor argumentów jest przekazywany do wtyczki, która jako jedyna parsuje własne argumenty — a wywołanie zwraca kod wyjścia samej wtyczki.
Postęp i jak długo polecenie czeka na rejestr
Polecenie, które czeka, informuje, na co czeka. Wszędzie tam, gdzie polecenie czeka na rejestr, na pobieranie lub na pierwszą kompilację wtyczki, pokazuje ten krok na standardowym wyjściu błędów, tak jak aggrega build i aggrega pull pokazują swoje: w terminalu jest to wiersz z nazwą kroku, wskaźnikiem obrotowym i czasem, który krok dotąd zajął, oznaczony znacznikiem po zakończeniu kroku i pozostawiony bez znacznika, gdy krok się nie powiódł; w terminalu, który nie potrafi przerysować wiersza w miejscu, lub z --plain — jeden wiersz na krok w chwili jego zakończenia, z jego czasem. Gdy standardowe wyjście błędów nie jest terminalem, nic nie jest pokazywane, a to, co polecenie wypisuje na standardowe wyjście, w żadnym przypadku się nie zmienia. Krok jest pokazywany tylko wtedy, gdy polecenie faktycznie na niego czeka, więc uruchomienie obsłużone z pamięci podręcznej nie pokazuje niczego, a kompilacja wtyczki jest pokazywana tylko wtedy, gdy trwa na tyle długo, by była prawdziwą kompilacją, a nie wynikiem z pamięci podręcznej.
Polecenia, które pokazują swoje kroki w ten sposób, oprócz polecenia każdej zainstalowanej wtyczki CLI:
aggrega config init, aggrega deprecate, aggrega explain, aggrega import, aggrega inspect, aggrega lint, aggrega plugin add, aggrega plugin gen-catalog, aggrega plugin run-local, aggrega plugin sync, aggrega push, aggrega push-artifact, aggrega registry add, aggrega scaffold, aggrega sign, aggrega validate
Żadne żądanie nie czeka na serwer bez końca. Żądanie czeka najwyżej 30 sekund, aż serwer zacznie odpowiedź po pełnym wysłaniu żądania, i najwyżej 30 sekund na kolejną część odpowiedzi, która już napływa. Serwer, który każe żądaniu czekać dłużej, jest odrzucany z kodem E0376, z podaniem serwera i czasu oczekiwania. Ograniczone jest tylko czekanie: pobieranie lub wysyłanie, które wciąż postępuje, trwa tyle, ile trwa. Chart Helm, który source: encji Recipe pobiera przez HTTPS, podlega tylko pierwszemu z dwóch limitów oczekiwania, a jego upłynięcie jest zgłaszane własnymi słowami biblioteki sieciowej, a nie pod kodem E0376. Żądanie, które polecenie i tak ponawia po przekroczeniu limitu czasu — odczyt podczas aggrega registry update, zapis podczas publikacji — jest ponawiane przed zgłoszeniem odrzucenia.
Przeglądanie pełnej listy repozytoriów rejestru kończy się w ciągu pięciu minut. Niektóre rejestry zbierają wszystkie przechowywane repozytoria, zanim w ogóle odpowiedzą na żądanie listy, dlatego na każdą stronę listy czeka się tak długo, jak może trwać przeglądanie, a nie 30 sekund; lista, która nie zakończyła się po pięciu minutach, jest zatrzymywana i odrzucana z kodem E0377. aggrega plugin add przegląda listę tylko wtedy, gdy żadna wtyczka nie nosi dokładnie podanej mu nazwy, aby znaleźć taką, której nazwa ją zawiera, więc podanie dokładnej nazwy wtyczki nigdy nie wymaga czekania na przeglądanie.
Na rejestr, który prosi o zwolnienie, czeka się, dopóki nie będzie o to prosił przez pięć minut bez przerwy. Polecenie czeka tak długo, jak taki rejestr prosi, wysyła do niego mniej żądań naraz i pokazuje oczekiwanie razem z pozostałym postępem; rejestr, który przez pięć minut nie odpowiada niczym innym niż „zwolnij”, jest odrzucany z kodem E0378. Rejestr, który prosi o zwolnienie opisuje, jak to działa.
Wszystkie trzy limity są stałe; żadne ustawienie ich nie zmienia.
Ścieżki wpisywane ręcznie i granica obszaru roboczego
Ścieżka wpisana w wierszu poleceń — --release, --catalog, --output-dir, plik do walidacji, lintowania, przypięcia lub opublikowania, --workspace-root — jest używana tam, dokąd prowadzi, wewnątrz obszaru roboczego lub poza nim, przez dowolne dowiązanie po drodze. To, co polecenie następnie odczytuje i zapisuje z własnej inicjatywy, jest ograniczone do obszaru roboczego niezależnie od tego, kto je uruchamia: polecenie nie odczytuje plików konfiguracyjnych obszaru roboczego, dokumentu katalogu, dokumentu obok encji Release ani pliku blokady encji Release przez dowiązanie prowadzące poza obszar roboczy, nie podąża za ścieżką, którą encja Release lub Manifest wyprowadza poza niego, ani nie zapisuje swojego wyniku, pliku blokady ani pamięci podręcznej przez takie dowiązanie. Katalog wskazany poza obszarem roboczym jest ograniczony w ten sam sposób w odniesieniu do tego, co się w nim znajduje, a encja Release wskazana poza obszarem roboczym sięga wyłącznie do plików we własnym katalogu. aggrega edit-document jest jedynym poleceniem, którego wpisana ścieżka również podlega ograniczeniu: edytuje ono wyłącznie dokument zawarty w obszarze roboczym. Granica obszaru roboczego opisuje tę zasadę, ścieżki celowo sięgające poza obszar roboczy oraz sposób rozwiązania każdej odmowy.
Przeszukiwanie indeksu katalogu
aggrega search [query] wyszukuje opublikowane encje we wszystkich rejestrach znanych przestrzeni roboczej. Opcjonalny argument [query] to podciąg, dopasowywany bez rozróżniania wielkości liter do nazwy i opisu każdej encji. Filtry faset zawężają zbiór wyników:
--kindogranicza wyniki do jednego lub kilku rodzajów encji (component,feature,recipe,featurerecipe,workload,plugin); flagę można powtarzać, nie rozróżnia wielkości liter, a rodzaje łączą się jako OR.-l/--selectorfiltruje według etykiet katalogowych encji. Kategoria jest etykietą, a nie osobną flagą:-l component.aggrega.ai/category=datastore.--capabilityi--plugin-typefiltrują pluginy według zadeklarowanej możliwości lub typu gniazda;--capabilitymożna powtarzać, a wartości łączą się jako OR.--registryzawęża wyszukiwanie do jednego rejestru, wskazanego przez host lub przyjazny alias; domyślnie przeszukiwane są wszystkie skonfigurowane rejestry.--limitogranicza liczbę wyników.-o/--outputwybiera format wyjścia:table(domyślny, czytelny dla człowieka),json(tablica do przetwarzania maszynowego) lubnames(same identyfikatory, po jednym w wierszu).
Wyszukiwanie zawsze odczytuje lokalny indeks — migawkę offline, którą buduje i odświeża aggrega registry update. Nie łączy się z siecią i niczego nie pobiera na żądanie. Gdy indeksu brak, polecenie kończy się błędem i informuje, że najpierw należy uruchomić aggrega registry update. Każde uruchomienie wypisuje na standardowe wyjście błędów wiersz „ostatnia aktualizacja” dla każdego rejestru, dzięki czemu wyjście json i names na standardowym wyjściu pozostaje czyste na potrzeby skryptów.
Uzupełnianie w powłoce
aggrega completion <shell> wypisuje na stdout skrypt uzupełniania dla bash, zsh, fish lub powershell. Skrypt jest generowany z bieżącego drzewa poleceń CLI w momencie uruchomienia, więc zawsze odzwierciedla polecenia i flagi pliku binarnego, który go wygenerował — nie ma statycznego pliku, który trzeba by generować ponownie w miarę rozwoju CLI.
Aby wypróbować uzupełnianie w bieżącej sesji bez instalowania czegokolwiek, należy bezpośrednio wczytać skrypt poleceniem source:
source <(aggrega completion bash)Aby zainstalować uzupełnianie na stałe, należy zapisać skrypt w lokalizacji, którą powłoka odczytuje przy uruchomieniu.
bash
Uzupełnianie w Bash wymaga pakietu bash-completion; jeśli nie jest jeszcze obecny, należy go zainstalować za pomocą menedżera pakietów systemu operacyjnego.
# Linuxaggrega completion bash > /etc/bash_completion.d/aggrega
# macOS (Homebrew)aggrega completion bash > $(brew --prefix)/etc/bash_completion.d/aggregazsh
Jeśli uzupełnianie nie jest jeszcze włączone w powłoce, należy je jednorazowo włączyć:
echo "autoload -U compinit; compinit" >> ~/.zshrcNastępnie należy zapisać skrypt uzupełniania w katalogu znajdującym się w fpath:
# Linuxaggrega completion zsh > "${fpath[1]}/_aggrega"
# macOS (Homebrew)aggrega completion zsh > $(brew --prefix)/share/zsh/site-functions/_aggregafish
aggrega completion fish > ~/.config/fish/completions/aggrega.fishpowershell
Należy dołączyć wygenerowany skrypt do profilu PowerShell, aby był wczytywany w każdej sesji:
aggrega completion powershell >> $PROFILEAby zainstalowane uzupełnianie zaczęło działać, należy uruchomić nową powłokę.