Dokumentacja języka
„Co” i „jak używać” w Aggrega. Składnia, wywoływanie CLI, katalog błędów, opracowane przykłady.
Przy pierwszym zapoznawaniu się z językiem należy czytać poniższe rozdziały po kolei. Podkatalogi referencyjne są wymienione pod swoimi rozdziałami — można przejść do nich bezpośrednio, szukając konkretnej encji, słowa kluczowego, dostawcy, polecenia CLI lub błędu.
Przed lekturą kolejnych rozdziałów należy zajrzeć do Stanu języka, aby poznać bieżący stan gotowości — które elementy języka są dostępne już dziś, które są akceptowane, ale kompilator jeszcze na nie nie reaguje, a które są planowane w przyszłych iteracjach. Sekcja Zgodność określa, co wydanie obiecuje w zakresie schematów, wiersza poleceń, narzędzi asystenta, kodów błędów i zestawów narzędzi dla pluginów.
Model poziomów encji
Autorskie rodzaje encji w Aggrega są zorganizowane w trzy poziomy odzwierciedlające stopniowe wdrażanie (poniżej). Obok nich istnieje należąca do platformy encja Workload, która nie jest osobnym rodzajem autorskim — to kształt, jaki przyjmuje syntetyzowane wejście encji Recipe, wyrażający kształt obliczeń za pomocą słownika form: (stateless, stateful, daemon, scheduled, task, reference). Podział na poziomy jest mechanizmem dokumentacyjnym i wdrożeniowym, a nie ograniczeniem w czasie wykonania: każdy rodzaj encji jest pełnoprawnym elementem języka; kompilator traktuje je jednakowo; otwartoźródłowy Aggrega obsługuje wszystkie poziomy bez licencjonowania ani blokowania funkcji. Oznaczenia poziomów sygnalizują „zaawansowane; pomiń, jeśli niepotrzebne” na potrzeby nawigacji, a nie możliwości.
| Poziom | Rodzaje encji | Kiedy wdrożyć |
|---|---|---|
| Poziom 1 — minimalna użyteczna powierzchnia | Aggregate, Component, Recipe, Manifest, Release | Dzień 1 — samodzielni założyciele i małe zespoły dostarczają działające oprogramowanie, korzystając wyłącznie z poziomu 1. Model myślowy: „Mam aplikację; chcę ją wdrożyć; oto jak.” |
| Poziom 2 — rozdzielenie ról | Feature, FeatureRecipe, Plugin | Dzień 30 — małe zespoły, w których role się rozdzielają (programista + Ops + czasem Security). Poziom 2 pojawia się poprzez Plugins renderujące dla dostawców (Ops wybierają spośród Helm, helm-chart, Compose, Terraform i CloudFormation), Features (Security zarządza poświadczeniami oddzielnie od konfiguracji aplikacji) oraz FeatureRecipes (dostosowanie w czasie wiązania dla każdego dostawcy). |
| Poziom 3 — ponowne użycie między encjami Component | SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary | Dzień 365 — dojrzałe katalogi, w których wspólne kształty powtarzają się w wielu encjach. Próg jest nieformalny: gdy kształt (np. PodResources) występuje w ponad 5 encjach Components, a koordynowanie aktualizacji staje się uciążliwe, wpis w SchemaLibrary jest uzasadniony. |
Każdy krok jest opcjonalny. Samodzielny założyciel nigdy nie jest zmuszany do zaglądania do poziomu 3; katalog przedsiębiorstwa ma pełny dostęp do poziomu 3 w razie potrzeby. Poziom 1 jest kompletny dla przypadku samodzielnego założyciela — programista może dostarczać działające aplikacje, używając wyłącznie encji poziomu 1. To istotna właściwość projektu: poziom 1 nie jest „podzbiorem, który się kompiluje”; jest „podzbiorem, który dostarcza oprogramowanie”.
Pięcioencjowa powierzchnia poziomu 1 wiąże się z kosztem wejścia — Aggregate + Component + Recipe + Manifest + Release to więcej ceremonii niż „wrzuć plik YAML, otrzymaj działającą usługę”. Koszt ten jest ceną rozdzielenia autorstwa na cztery domeny (Developer Intent / Platform Catalog / Platform Ops / Routing), które odróżnia Aggrega od samego Helm czy samego Terraform. Samouczki poziomu 1 jawnie przeprowadzają przez konfigurację pięciu encji.
W ramach poziomu 3 mechanizm spec.templates / $instantiate: (parametryczne pomocniki w SchemaLibrary) jest opisany jako jeszcze bardziej zaawansowana funkcja podrzędna. Większość użytkowników poziomu 3 początkowo nie sięga po spec.templates; próg to „gdy biblioteka ma ponad 6 schematów współdzielących sparametryzowaną strukturę”.
Kolejność czytania
- Jak korzystać z tej dokumentacji referencyjnej
- Konwencje nazewnictwa
- Przegląd encji
- Poziom 1: aggregate, component, recipe, manifest, release
- Poziom 2: feature, featurerecipe, plugin
- Poziom 3: schemalibrary, mappinglibrary, workloadlibrary, artifactlibrary
- Przekrojowo: workload (rodzaj kompilatora należący do platformy, wykorzystywany w
workload:encji Recipe)
- Przegląd słownictwa
- Dokumentacja słownictwa: topology-triad (provides, inject, uses), data-pillars (values, infra, parameters, locals), inheritance-and-interface (extends, implements), modifier-system (appliesTo, selectors), compact-form-authoring, cross-document-ref, labels-and-annotations, publishing-surface, social-contracts, validation-surface, output-composition, uri-grammar, version-resolution
- Przegląd szablonów
- Dokumentacja szablonów: expansion-matrix, template-context-contract, sprig-functions, parameters-context, assertions-block, rendered-resource-names
- Providers — przegląd
- Providers — dokumentacja: architektura, well-known-annotations, reference-matrix, helm, helm-chart, compose, terraform, cloudformation
- Przegląd CLI
- Dokumentacja CLI: aggrega-build, aggrega-inspect, aggrega-pull, aggrega-lint, aggrega-auth, aggrega-cache, aggrega-config, aggrega-deprecate, aggrega-edit-document, aggrega-explain, aggrega-get-schema, aggrega-import i plik odpowiedzi importu, aggrega-login, aggrega-logout, aggrega-mcp, aggrega-pin, aggrega-plugin, aggrega-push, aggrega-push-artifact, aggrega-registry, aggrega-scaffold, aggrega-search, aggrega-serve, aggrega-sign, aggrega-skills, aggrega-validate, aggrega-version, global-flags, configuration, environment-variables, workspace-boundary
- Przegląd błędów
- Dokumentacja błędów: fatal-halts, warnings, sentinels, error-translation
- Przegląd przykładów
- Przykłady: 01-getting-started, 02-data-model, 03-features-and-policies, 04-secrets, 05-credential-features, 06-composition, 07-input-kinds, 08-advanced-patterns, 09-cross-boundary-routing; uruchamialne obszary robocze: Uruchamialne przykłady
Dokumentacja referencyjna tworzenia encji Plugin
Interfejs pluginów Wasm znajduje się obok sekwencji rozdziałów, a nie w jej obrębie: autor pluginu czyta go niezależnie od ścieżki tworzenia encji. Strona encji plugin opisuje interfejs tworzenia w katalogu; poniższe strony opisują gniazda, ładunki i przepływ pracy autora.
- plugin-contract — gniazda, do których podłącza się plugin, ich miejsce w potoku oraz kształty wejścia i wyjścia każdego gniazda.
- plugin-developer-guide — kompletny przepływ pracy autora:
describe(), deklaracje uprawnień, limity środowiska uruchomieniowego, cykl publish/pull/build, podpisywanie, wersjonowanie. - policy-socket — szczegółowy opis gniazda zarządzania: jego cztery role, poziomy ważności werdyktów, kanał wejściowy operatora oraz pisanie polityki dla każdego z silników dostarczanych w kompilatorze.
- governance-attachment-facts — fakty dotyczące poszczególnych powiązań, które polityka zarządzania odczytuje z grafu budowania, w tym trzy jednostki oznaczenia wrażliwości oraz powód, dla którego brak oznaczenia nie oznacza zezwolenia.
- when-to-use-a-pipeline-step — wybór między krokiem potoku a szablonową encją FeatureRecipe.
- embedded-plugins — pluginy dostarczane w pliku binarnym kompilatora.
- tagging-plugins — dwie wbudowane wtyczki ładu, które zapisują etykiety bez zasady,
governance/label-injectorigovernance/selector-tagger: ich ustawienia i to, co zapisuje każda z nich. - core-importers — dziesięć importerów kompilatora, od Langflow, Flowise i n8n po Compose, MCP i frameworki agentowe: co każdy z nich odczytuje i szkicuje, ich ustawienia oraz ich publikacja z każdym wydaniem kompilatora.
- authoring-a-provider-walkthrough — praktyczny przewodnik po tworzeniu modułu gościa providera, od pustego katalogu do kompilacji, która zapisuje pliki wyrenderowane przez providera.
- writing-a-governance-plugin — pisanie własnej wtyczki ładu na podstawie szkieletu adaptera z zestawu do tworzenia wtyczek: jedna reguła, ręczne uruchomienie eksportu każdej roli, encja
Pluginw katalogu obszaru roboczego i kompilacja, którą wtyczka odrzuca. - compatibility — jak wersjonowane są zestawy narzędzi dla pluginów: co może zmienić wydanie poprawkowe i wydanie podrzędne zestawu oraz co zapewnia, że zbudowany plugin nadal się ładuje.