Status der Sprache
Diese Seite ist die maßgebliche Referenz dafür, welche Oberflächen von Aggrega heute nutzbar sind, welche dokumentiert sind, aber vom Compiler noch nicht verarbeitet werden, und welche für eine künftige Iteration geplant sind. Sie ergänzt die Kapitel zu den einzelnen Domänen, indem sie den Reifegrad der gesamten Sprache an einer Stelle zeigt.
Zwei Lesergruppen ziehen diese Seite heran. Erstautoren prüfen die Seite, bevor sie gegen eine unbekannte Oberfläche schreiben, um sicherzustellen, dass die Oberfläche heute gerenderte Ausgabe erzeugt. Nachschlagende prüfen die Seite, wenn sich eine verwendete Oberfläche unerwartet verhält — wenn zum Beispiel YAML die Validierung besteht, aber keine Ausgabe entsteht, ist die Seite die erste Stelle, um den Status der Oberfläche nachzusehen. Wiederkehrende Leser nutzen die Seite außerdem, um Oberflächen zu erkennen, die seit dem letzten Lesen ihr Status-Label gewechselt haben. Die Kapitel zu den Domänen und die Entitätsreferenzen beschreiben, wie die Oberfläche funktionieren soll; diese Seite beschreibt, ob sie bereits funktioniert.
Status-Taxonomie
Jede Sprachoberfläche auf dieser Seite trägt eines von vier Status-Labels:
-
verfügbar. Das Schema akzeptiert die Oberfläche; der Compiler verarbeitet sie; das Verhalten entspricht dem dokumentierten Vertrag. Wer eine
available-Oberfläche verwendet, erhält den dokumentierten Vertrag. -
akzeptiert, aber wirkungslos. Das Schema akzeptiert die Oberfläche — wer gegen sie schreibt, besteht die Validierung —, aber der Compiler verarbeitet sie noch nicht. Eine
accepted but inert-Oberfläche zu verwenden, erzeugt einen syntaktisch gültigen Build ohne gerenderte Wirkung für diese Oberfläche; der Compiler kann eine Warnung ausgeben, die die wirkungslose Oberfläche nennt (das empfohlene Muster), oder einige aktuelle Oberflächen werden ohne Warnung stillschweigend übersprungen. Die Einträge pro Abschnitt unten nennen das jeweilige Verhalten. -
akzeptiert, aber blockiert. Das Schema akzeptiert die Oberfläche — wer gegen sie schreibt, besteht die Validierung —, aber der Compiler bricht den Build ab, statt sie zu rendern. Das Schreiben gegen eine
accepted but blocked-Oberfläche schlägt beim Rendern mit einem expliziten Fehler fehl, der nennt, was stattdessen zu schreiben ist. Eine Blockade kann dauerhaft sein, wenn das Geschriebene eine Mehrdeutigkeit ist, die der Compiler nicht für Sie auflöst, weil eine für Sie gewählte Lesart etwas ausliefern könnte, das Sie nicht verlangt haben; oder sie kann nur bestehen, bis das Verhalten hinter der Oberfläche ausgeliefert wird. Was das Label verspricht, ist in beiden Fällen dasselbe: Das Schema nimmt sie an, der Build lehnt sie ab, und der Fehler sagt Ihnen, wie Sie es beheben. -
geplant. Die Oberfläche ist als entworfen dokumentiert, aber weder das Schema noch der Compiler akzeptieren sie bisher. Das Schreiben gegen eine
planned-Oberfläche schlägt bei der Schemavalidierung fehl. Die Seite zeigt geplante Elemente, damit Autoren ihr Fehlen einplanen können, statt die Lücke erst beim Build zu entdecken.
Status-Labels werden gegen den aktuellen Compiler bewertet. Oberflächen in aktiver Entwicklung können zwischen Labels wechseln; die Einträge pro Abschnitt beschreiben den Übergangsplan, wo einer bekannt ist.
Recipe-Eingabearten
Ein Recipe setzt seine Ausgabe aus drei Eingabearten zusammen — aus Quelle, synthetisiert und Artefakte —, beschrieben in 16-recipe-input-composition.md. Status pro Eingabeart:
-
source:+valuesMapping:(aus Quelle) — verfügbar. Der Compiler löst diesource:-URI auf, wertet das TemplatevaluesMappingaus (inline, Datei-$import:oder Bibliotheks-$import:) und übergibt das Ergebnis zum Rendern an den Ziel-Provider. Verwendet von den Providern helm, helm-chart, compose, terraform und cloudformation. -
workload:(synthetisiert) — verfügbar. Das Recipe deklariertworkload:entweder inline (Block-Skalar mit dem Workload-YAML) oder über$import:(Dateipfad). Der Compiler parst die templatisierte Workload, validiert sie gegen das eingebettete Workload-Schema und leitet sie an den Workload-Synthesizer des Ziel-Providers weiter. Verwendet von den Providern helm und compose. Der Provider helm-chart verweist Autoren für synthetisierte K8s-Manifeste ausdrücklich an den Provider helm. Ein Recipe, dasworkload:gegen einen Provider deklariert, der keine Workload-Synthese implementiert, bricht beim Rendern mit einemCATALOG_ERRORab. -
artifacts:(Artefakte) — verfügbar. Das Feld ist eine Map benannter Einträge; jeder Eintrag wird inline verfasst oder über ein eigenes$import:pro Eintrag geladen. Die Einträge werden ausgewertet, nachdem die Workload geparst und die Quelle aufgelöst ist, sodass ihnen der vollständige Template-Kontext — einschließlich.workloadund.source— zur Verfügung steht; sie erhalten Herkunftsangaben, die inmetadata.labelsundmetadata.annotationszusammengeführt werden, bei Dokumenten, die Metadaten tragen (die für den Zeichensatz unsicheren Schlüssel — recipe-uri, boundary-path, sync-wave — als Annotationen, dieselbe Aufteilung, die die helm-Provider anwenden), und werden als separate Dateien neben der aus der Quelle gerenderten oder aus der Workload synthetisierten Ausgabe des Recipe ausgegeben. Provider-Dispatch — der flache helm-Provider gibt eigenständige Dateien in einem Verzeichnis aus, das nach der Komponente benannt ist, die sie deklariert hat, innerhalb des Boundary-Ausgabeverzeichnisses, denn der Schlüssel benennt die Datei und sagt nichts darüber, welche Komponente sie geschrieben hat; der compose-Provider leitet seine Ausgaben durch den Merger am Ende des Release; der helm-chart-Provider wertet jeden Eintrag mit den Aggrega-Begrenzern[[ ]]aus, sodass die Helm-Syntax{{ }}in derselben Datei bis zum nachgelagerten Rendern erhalten bleibt, und platziert dann jeden Eintrag nach seiner verfassten Form — einen per$import:geladenen Eintrag unterboundaries/<bp>/charts/<nodeID>/templates/<authored-key>(die Dateien eines Bundles unter diesem Schlüssel verschachtelt), neben den eigenen Templates des Charts aus der Quelle, und einen Eintrag mit Inline-Inhalt unterboundaries/<bp>/charts/<nodeID>/<authored-key>, dem Chart-Stamm, wo die eigenen Templates des Charts ihn über.Files.Get/.Files.Globlesen; der terraform-Provider schreibt jeden Eintrag unverändert in das eigene Verzeichnis der Komponente unter demmodules/-Baum der Boundary; der cloudformation-Provider führt jeden Eintrag, ein Stack-Fragment, in den einzigen Stack zusammen, der für dieses Ausgabeverzeichnis zusammengesetzt wird. Dateinamenkollisionen zwischen Ursprüngen verschiedener Eingabearten (aus der Quelle gerendert, aus der Workload synthetisiert oder als Artefakt ausgegeben) werden zur Renderzeit vom ursprungsübergreifenden Kollisionsdetektor erkannt und erzeugen einen CATALOG_ERROR, der jeden Beitragenden nennt.
Siehe entities/recipe.md für die Authoring-Oberfläche des Recipe und die Kompositionsregeln der Eingabearten; errors/fatal-halts.md für die Formregeln des Recipe; und den Abschnitt Providers unten für die Matrix pro Provider.
Mapping-Sprachen
Recipes (und FeatureRecipes) binden sich an ein einziges Mapping-Feld, um den Aggrega-Kontext in das Werte-Dictionary zu übersetzen, das der zugrunde liegende Provider verarbeitet. Das Feld valuesMapping: unterstützt drei Authoring-Modi, die nach der Form des Inhalts ausgewählt werden:
valuesMapping:— Modi 1–3 verfügbar. Modus 1: Inline-Go-Template (Block-Skalar). Modus 2: Datei-$import:(eine Map, die nur$import:mit einem lokalen Dateipfad enthält). Modus 3: Bibliotheks-$import:(eine Map, die nur$import:mit einer Identitätsreferenz per reinem Namen auf einen Eintrag einer MappingLibrary enthält,<Library>#/mappings/<entry>, optional mit einer Untergrenze:<version>). Der Compiler wählt nach der Form des Inhalts — Block-Skalar für Modus 1,$import:mit einem Dateipfad für Modus 2,$import:mit einer Bibliotheksreferenz per reinem Namen für Modus 3. Alle drei werten das aufgelöste Go-Template während des Werte-Mappings gegen den Template-Kontext des Recipe aus (die Sprig-Hilfsbibliothek ist vorregistriert); Modus 3 löst den Eintrag gegen den lokalen Katalog plus alle in der Lockdatei gepinnten Bibliotheken auf, und eine Referenz mit Host wird abgelehnt. Sieheentities/recipe.md„Das FeldvaluesMapping— drei Authoring-Modi“ für den Dispatch-Mechanismus und ausgearbeitete Beispiele.
Siehe entities/recipe.md für die Authoring-Oberfläche des Recipe und den Entwurf der Mapping-Sprache sowie entities/mappinglibrary.md für die Bibliotheksentität, auf der Modus 3 beruht.
Inject-Syntax
Der inject:-Block hat an jeder Stelle dieselbe Syntax — im eigenen inject einer Komponente, in dem einer uses-Verbindung und in dem eines Anhangs.
-
Eine Liste von Einträgen pro Mechanismus (
[{in: ..., from: ...}],[{in: ..., value: ...}]) — verfügbar. Jeder Bereitstellungsmechanismus ist eine Liste; jeder Eintrag nennt seinen lokalen Bezeichner (Name der Umgebungsvariablen, Dateipfad, Argument-Flag) mitin:und trägt genau eines vonfrom:(Referenz auf einen provides-Schlüssel) odervalue:(literaler String). Ein Mechanismus, der als Map statt als Liste geschrieben ist, oder ein Eintrag mit beiden Schlüsselwörtern bricht den Build am Dokument-Envelope des Aggregate ab und nennt den Pfad. -
value:nur im eigeneninjecteiner Komponente. Ein Literal gehört in das eigeneinjectder Komponente, das es zustellt. Auf eineruses-Verbindung bricht einvalue:den Build ab, wie Aninject:entry on a connection carries a literal (Ein Eintrag auf einer Verbindung trägt ein Literal) beschreibt, und im eigeneninjecteines Anhangs bricht es den Build ebenfalls ab, wie Aninject:entry on an attached Feature carries a literal (Ein Eintrag auf einem angehängten Feature trägt ein Literal) beschreibt: Beide liefern nur Schlüssel, die eine andere Entität veröffentlicht und die mitfrom:benannt werden.
Siehe vocabulary/topology-triad.md für die vollständige Spezifikation des Injection Contract, einschließlich der Semantik des Kontexts mit zwei Zuständen, der Regeln für Schlüsselkollisionen und ausgearbeiteter Beispiele.
Template-Engine
Die Go-Template-Engine von Aggrega wertet Recipe- und FeatureRecipe-Templates gegen den Template-Kontext in der Phase pro Stelle aus, die die Template-Expansionsmatrix dokumentiert. Die Sprig-Hilfsbibliothek ist neben den eigenen Helfern von Aggrega auf jeder Oberfläche vorregistriert, die der Renderer auswertet, mit einer Ausnahme: Das Auflösen einer strukturierten source:-Koordinate registriert nur die Helfer von Aggrega — optional und capitalizedWords sind dort verfügbar, die Funktionen von Sprig nicht, sodass ein Sprig-Aufruf in einem source:-Feld oder in einem locals:-Eintrag einer Entität mit strukturiertem source: beim Parsen abbricht. Siehe errors/fatal-halts.md, wo diese Oberfläche einen eigenen Abschnitt hat. Auswertung, Parsen und Sprig-Integration sind heute verfügbar.
Verhalten bei fehlenden Schlüsseln — toleriert in Wert-Templates; striktes missingkey=error in Pfad-Templates, in Assertions und in einer source:-Koordinate. Wert-Templates werden mit der Go-Option missingkey=zero ausgewertet, sodass ein Template, das einen nicht gebundenen Schlüssel referenziert (z. B. .values.unset_field), keinen Fehler auslöst und der Lesezugriff nichts rendert. Katalog-Idiome wie {{ .values.optional_field | default "fallback" }} funktionieren unter dieser Richtlinie weiterhin, weil ein nicht gesetzter Wert für default als leer gilt. Pfad-Templates (directory: / subDirectory: an Release-Boundaries) werden mit missingkey=error gegen eine geschlossene Allowlist ausgewertet — stille Pfadfehler erzeugen fehlerhafte Dateisystem-Layouts, die Betreiber erst nach dem Build entdecken, und die Strenge fängt den Fehler früher ab. Zwei weitere Oberflächen folgen aus demselben Grund derselben strengen Richtlinie: Ein leeres Rendering würde dort ein falsches Urteil oder einen falschen Pin erzeugen statt eines Felds, das der Autor zurücklesen kann. Es sind ein assertions:-Eintrag an einer Component, einem Feature, einem Recipe oder einem FeatureRecipe sowie die templatisierten Felder eines strukturierten source:-Blocks an einem Recipe oder FeatureRecipe. errors/fatal-halts.md führt die Richtlinie jeder Oberfläche einzeln auf und nennt die anwesenheitsbewussten Formen, die unter der strengen funktionieren.
Anwesenheitsbewusster Fallback über optional. Wenn ein Recipe-Autor „Schlüssel fehlt“ von „Schlüssel vorhanden mit einem Null-, leeren oder false-Wert“ unterscheiden muss — die Unterscheidung, die Sprigs default nicht treffen kann —, stellt der Renderer den Helfer optional bereit: {{ optional .infra "replicas" 1 }} gibt das verfasste infra.replicas zurück (einschließlich einer verfassten 0), wenn vorhanden, und fällt nur dann auf 1 zurück, wenn der Schlüssel fehlt. Siehe templates/sprig-functions.md für die vollständige Semantik.
Namensfaltung über capitalizedWords. Wo ein Ziel in den Namen, mit denen es Ressourcen adressiert, nur Buchstaben und Ziffern akzeptiert, liest {{ capitalizedWords .context.instance_id }} die ID als Wörter, die durch alles außerhalb dieses Alphabets getrennt sind, und schreibt den ersten Buchstaben jedes Worts groß, sodass aus payments-db PaymentsDb wird. Die Faltung entfernt jedes Trennzeichen, sodass zwei IDs, die sich nur in der Zeichensetzung unterscheiden, denselben Namen ergeben; ein Build, der zwei Ressourcen unter einem Namen ausgeben würde, bricht ab und nennt beide IDs. Siehe templates/sprig-functions.md für die vollständige Semantik.
Durchsetzung des Parametervertrags auf der Deklarationsebene. Erforderliche Parameter, die das Release nicht liefert, erzeugen explizite Fehler auf der Ebene des Parametervertrags, dem ersten, was die Auflösung prüft, mit einer Herkunftsangabe file:line, die den Parameter und den Vertrag nennt. Typ- und Constraint-Verletzungen werden auf dieselbe Weise gemeldet. Das ist die eigentliche Durchsetzung bei fehlenden Schlüsseln: Die Typisierung wird dort geprüft, wo die Absicht des Entwicklers liegt (in der parameters:-Deklaration des Aggregate), nicht erst zur Auswertungszeit nachgelagerter Templates. Siehe entities/aggregate.md §„Typisierte Parameterverträge“.
Eine einzige Deklarationsgrammatik für parameters: im Aggregate. Jeder Parameter-Slot wird als typisiertes Vertragsobjekt verfasst (key: { type: <type>, default: <value>, ... }). Die Kurzform mit reinem Skalar (key: <value>) wird am Dokument-Envelope des Aggregate abgelehnt, mit einem Fehler, der den Parameter nennt und besagt, dass ein Objekt erwartet wurde. Das Vokabular des typisierten Vertrags macht die Semantik von type:, required: und den Constraints auf der Deklarationsebene explizit; die Erfüllung durch das Release verwendet weiterhin skalare Werte gemäß dem im Vertrag deklarierten Typ.
Siehe templates/expansion-matrix.md für die Auswertungsmatrix pro Template-Stelle und 05-templates.md für den Überblick über Templates.
Phasen der Kompilierungs-Pipeline
Die Kompilierungs-Pipeline von Aggrega ist in ../architecture/10-compilation-pipeline.md dokumentiert. Status pro Phase:
- Auflösung, Aufbau der Topologie, Finalisierung des Graphen, statische Analyse und Rendering — verfügbar.
- Inject-Mapping (Abfangen vor dem Rendern über
injectMapping) und jede Teilphase des Basis-Renderings — Veröffentlichung der Locals, Werte-Mapping, Workload-Synthese, Auswertung der Artefakte, Provider-Rendering, Feature-Rendering und Ressourcenerzeugung für Credential-FeatureRecipes — verfügbar. - Die Plugin-Pipeline (Wasm-Ausführung von
pipeline:) — verfügbar. Bei einem Recipe oder FeatureRecipe, das nicht leerepipeline:-Schritte deklariert, wird jeder Schritt in der deklarierten Reihenfolge ausgeführt: Der Compiler ruft das benannte Wasm-Plugin des Schritts auf der gerenderten Ausgabe auf, wendet die zurückgegebenen JSON-Patch-Operationen auf die adressierten Dokumente an und gibt die Nebeneffekte des Schritts aus. Ein Schritt, dessenwhen:-Bedingung falsy rendert, wird als Durchreichung übersprungen und lässt die Dokumentmenge unverändert. Autoren, die Mutationen im JSONPatch-Stil anstreben (Envoy-Sidecar-Injektion, Secret-VolumeMount usw.), erreichen sie über diese Oberfläche.
Providers
Die Standardbibliothek von Aggrega liefert fünf Rendering-Provider — helm, helm-chart, compose, terraform und cloudformation. Status pro Provider:
helm— verfügbar. Sowohl der Quellmodus (Rendern von Helm-Charts über das Helm-SDK) als auch der synthetisierte Modus (Workload → ein Controller-Objekt, gewählt nach derformder Workload — Deployment, StatefulSet, DaemonSet, Job oder CronJob — plus Services und PVCs) werden ausgeliefert.helm-chart— verfügbar. Der Quellmodus (Komposition per Umbrella-Chart) wird ausgeliefert. Die synthetisierte Eingabeart ist auf diesen Provider nicht anwendbar; Autoren, die eine K8s-Manifest-Synthese benötigen, verwenden den Providerhelmmitworkload:.compose— verfügbar. Sowohl der Quellmodus (Overlay von Compose-Fragmenten) als auch der synthetisierte Modus (Workload → Compose-Dienst + Volumes + Netzwerke) werden ausgeliefert. Die Ausgabedocker-compose.yamlpro Boundary wird über den Composer auf Release-Ebene zusammengesetzt.terraform— verfügbar. Sowohl der Quellmodus als auch Artefakte werden ausgeliefert; jede Boundary erhält eine Root-Konfiguration,aggrega.modules.tf, die jede Komponente alsmodule-Block deklariert, dessen Dateien in einem eigenen Verzeichnis untermodules/liegen. Die synthetisierte Eingabeart ist für diesen Provider nicht anwendbar.cloudformation— verfügbar. Sowohl der Quellmodus als auch Artefakte (Stack-Fragmente) werden ausgeliefert; alle Komponenten, die in ein und dasselbe Ausgabeverzeichnis rendern, werden zu einem einzigen Stack-Template zusammengesetzt, das als reines JSON ausgegeben wird. Die synthetisierte Eingabeart ist für diesen Provider nicht anwendbar.
Provider-Rendering wird von einem Plugin mit pluginType: provider bereitgestellt; siehe entities/plugin.md für die Authoring-Oberfläche des Provider-Rendering-Plugin und 06-providers.md für die Referenzseiten der einzelnen Provider.
Annotationsgesteuerte Erweiterung
Manifests enthalten einen Binding-Abschnitt features.annotations:, der Annotationsschlüssel auf Feature-Typen abbildet, sowie eine nach Säulen gruppierte Routing-Tabelle (maps.infra / maps.values), die festlegt, welche Schema-Eigenschaften des Feature jedes Binding befüllen darf. Dokumentiert in entities/manifest.md und providers/well-known-annotations.md; die Einordnung in die Pipeline in ../architecture/10-compilation-pipeline.md; die Mechanik beim Laden des Katalogs und bei der Inspektion in ../architecture/13-catalog-and-registry.md §„Annotationsgesteuerte Feature-Erweiterung“.
- Manifest-Bindings
features.annotations— verfügbar. Die Teilphase der Auflösung für die Annotationserweiterung wird durchgängig ausgeliefert. Sie durchläuft die Release-Boundaries (von außen nach innen) und die Aggregate-Subsysteme (von außen nach innen), berechnet die effektive Annotationsmenge pro Komponente über Kaskade + Überschreibung mit null-Opt-out für den ganzen Wert und pro Unterschlüssel, parst jeden Annotationswert als Skalar, strukturierte Map oder explizitesnull, leitet pro Unterschlüssel über diemaps-Deklaration des Binding weiter, mit Durchsetzung von Seite gegen Säule (die Aggregate-Seite löstmaps.valuesaus; die Release-Seite löstmaps.infraaus), validiert die Typen jedes Blatts gegen dasspec.schemades Ziel-Feature und injiziert synthetische Feature-Anhänge, die der IR-Graph mitorigin: annotationkennzeichnet. Die seitenübergreifende Komposition führt beim IR-Aufbau pro Säule und pro Feld zusammen, wobei der explizite Wert pro Feld gewinnt;aggrega inspectzeigt die Herkunft pro Blatt in Klammern. Die Validierung der Binding-Ziele beim Laden des Katalogs, der Lint für Überschneidungen der Schema-Säulen und der Lint für Überschneidungen der Binding-Maps sichern den Pfad ab. Das reine Präfixaggrega.ai/wird beim Laden des Manifest abgelehnt, wenn es als Binding-Schlüssel verwendet wird — dieses Präfix ist für plattformeigene Annotationen reserviert; Bindings verwendenfeature.aggrega.ai/oder eine eigene Domain.
Versionsabgleich
Recipes und FeatureRecipes deklarieren die Component- oder Feature-Schnittstelle, die sie implementieren, über das Schlüsselwort implements:. implements: wählt nie eine Recipe aus: Das tut das Mapping des Manifest, und eine Instanz, deren Typ kein Mapping abdeckt, bricht mit einem Fehler ab, der die Recipes als Kandidaten auflistet, deren implements: diesen Typ implementieren kann. Was implements: steuert, ist die Prüfung, dass die Recipe jedes Mapping-Eintrags im Manifest den gemappten Typ implementiert oder eine Basis, die dieser Typ mit extends erweitert. Der gemappte Typ ist der Schlüssel des Eintrags und, bei einem components.type-Schlüssel, auch der Typ jeder Komponenteninstanz, die der Schlüssel in einer Version erreicht, die der Schlüssel nicht nennt — bei einem ohne Version geschriebenen Schlüssel jede Instanz, die er erreicht —, und zwar in der Version, in der der Build diese Instanz kompiliert: der Version, die die Instanz nennt, oder, bei einer Instanz, die keine nennt, der höchsten Version dieser Component, die der Katalog enthält. Status pro Form:
- Exakt (
core/api-server:1.0.0) — verfügbar. Der gemappte Typ muss genau diese Version haben. - Major-kompatibler Bereich (
core/api-server:^1.0.0) — verfügbar. Die Caret-Form ist eine SemVer-Constraint (>=1.0.0, <2.0.0im Beispiel); die Version des gemappten Typs muss sie erfüllen. - Unversioniert (
core/api-server) — verfügbar. Jede Version des Typs erfüllt sie.
Ein Mapping-Eintrag, dessen Recipe mit ihrem implements: weder dem gemappten Typ noch einer seiner Basen entspricht, bricht den Build mit einem OPS_ERROR ab, der den Eintrag, die Recipe und ihren implements:-Wert nennt. Eine Komponenteninstanz, die ein Schlüssel in einer anderen Version erreicht und deren Version das implements: der Recipe nicht erfüllt, bricht den Build mit demselben OPS_ERROR ab und nennt die Instanz, ihren Typ — und bei einer Instanz ohne Versionsangabe die Version, in der sie kompiliert wurde —, den Schlüssel, die Recipe und ihren implements:-Wert. Die Caret-Form ist die kanonische Authoring-Oberfläche für den Major-kompatiblen Abgleich.
Siehe vocabulary/inheritance-and-interface.md für die Entwurfsoberfläche von implements: und entities/manifest.md für die Form der Mapping-Ebene pro Manifest.
Metadaten-Envelope
Die Envelopes der Katalogentitäten tragen metadata.labels, metadata.annotations und (beim Release) metadata.environment. Status pro Oberfläche:
Verfügbarkeit von metadata.labels und metadata.annotations — bei sieben Arten. Die Entitäts-Envelopes, die diese Felder tragen, sind Component (Labels erforderlich, mit dem erforderlichen Schlüssel component.aggrega.ai/type, Annotationen optional), Feature (beide optional), die vier Bibliotheksarten SchemaLibrary, MappingLibrary, WorkloadLibrary und ArtifactLibrary (beide optional) und Aggregate (nur Labels, optional). Die übrigen Entitäten — Recipe, FeatureRecipe, Manifest, Release, Plugin — akzeptieren metadata.labels oder metadata.annotations nicht auf Envelope-Ebene.
metadata.environment beim Release — erforderlich. Das Release-Schema führt environment als erforderliches metadata-Feld; der Build stempelt seinen Wert als Label aggrega.ai/environment auf die gerenderte Ausgabe. Siehe entities/release.md für die fünf praktischen Anwendungsfälle des Abschnitts Environment Metadata (OTel/FinOps-Kostenzuordnung, OTel-Trace-/Log-Filterung, Ausrichtung von Kubernetes-Operatoren, Differenzierung von Produktionsumgebungen über mehrere Regionen, Abgrenzung für Compliance).
Siehe 02-naming-conventions.md für die Regeln zur Schreibweise von Feldern, die für metadata-Schlüssel gelten, und die Referenzseiten der einzelnen Entitäten für die Envelope-Formen, die jede Entität heute akzeptiert.
CLI-Befehle
Die Aggrega-CLI registriert die Build-Pipeline sowie Introspektion. Status pro Befehl:
aggrega build— verfügbar. Liest eine Release-Datei, löst das Aggregate + Manifest auf, führt die Kompilierungs-Pipeline aus und schreibt gerenderte Artefakte in die Boundary-Ausgabeverzeichnisse. Ist eine Lockdatei vorhanden, prüft der Befehl die Abhängigkeiten dagegen; fehlt sie, bricht er mit der Aufforderung zu einem Pull ab oder füllt sie zuerst, wo--auto-pulloderauto_pulldies verlangt.aggrega inspect— verfügbar. Inspiziert eine Katalogentität, eine Entitätsdatei, eine in einer Registry veröffentlichte Entität oder ein Release und gibt deren aufgelöste Form aus. Siehecli/aggrega-inspect.md.aggrega pull— verfügbar. Löst alle Abhängigkeiten eines Release auf und schreibt eine Lockdatei pro Release, die jede Katalogentität und jedes Quellartefakt auf eine Version und einen Inhalts-Digest pinnt und jede externe Eingabe, die das Rendern des Release anfordert, auf einen Inhalts-Digest; speichert die abgerufenen Inhalte unter.aggrega/cacheim Cache.--verifyprüft eine vorhandene Lockdatei gegen den aktuellen Zustand. Siehecli/aggrega-pull.md.aggrega push— verfügbar. Veröffentlicht eine Katalogentität in einer OCI-Registry;aggrega push --list-kindsgibt an, welche Arten akzeptiert werden. Siehecli/aggrega-push.md.aggrega lint— verfügbar. Wendet die Regeln zur Veröffentlichungsdisziplin mit dem Schweregradwarnauf den gesamten Katalog, den Abhängigkeitsabschluss eines Release oder eine einzelne Entität an; bei einer einzelnen Entität fügt--pre-publisheine Prüfung der Versionserhöhung gegenüber der aktuell veröffentlichten Version der Entität hinzu, und eine Abweichung führt zum Abbruch. Die Regeln werden als optional aktivierbares Wasm-Plugin ausgeliefert. Siehecli/aggrega-lint.md.aggrega serve— verfügbar. Ein langlaufender Compiler-as-a-Service-Daemon, der JSON-RPC 2.0 über stdin/stdout spricht, für die Integration in Editoren und IDEs. Siehecli/aggrega-serve.mdfür die bereitgestellten Methoden.aggrega version— verfügbar. Gibt die CLI-Version aus;-o jsongibt ein maschinenlesbares Versionsobjekt aus.aggrega validate— verfügbar. Prüft die Korrektheit für den gesamten Katalog, ein Release oder eine einzelne Entität und meldet Diagnosen, ohne Artefakte zu rendern.aggrega search— verfügbar. Durchsucht den lokalen Index der konfigurierten Registries nach veröffentlichten Entitäten; der Index wird vonaggrega registry updateerstellt und aktualisiert.aggrega registry— verfügbar. Verwaltet Registries und ihre Vertrauensrichtlinie für Signaturen;registry adderfasst eine Registry, undregistry updateerstellt den lokalen Index, denaggrega searchabfragt.aggrega push-artifact— verfügbar. Veröffentlicht ein eigenständiges Datenartefakt (etwa ein Dokumentationspaket) in einer OCI-Registry, neben dem Entitäten veröffentlichendenpush.aggrega sign— verfügbar. Signiert ein oder mehrere bereits veröffentlichte Artefakte und hängt deren Signaturen an.aggrega deprecate— verfügbar. Hängt eine signierte Deprecation-Markierung an ein bereits veröffentlichtes Artefakt an.aggrega loginundaggrega logout— verfügbar. Authentifizieren sich bei einer OCI-Registry und speichern die Anmeldeinformation oder entfernen eine gespeicherte Anmeldeinformation.aggrega auth— verfügbar. Verwaltet die lokale Signaturidentität, mit der Artefakte signiert werden.aggrega config— verfügbar. Inspiziert und verwaltet die Workspace-Konfiguration; Unterbefehle zeigen die effektive zusammengeführte Konfiguration und die Herkunft jeder Einstellung, legen eine funktionsfähige Konfiguration mit einer Registry und deren Vertrauensrichtlinie für Signaturen an und frieren die effektive, für den Build kritische Konfiguration im Workspace ein, sodass er identisch gebaut wird, ohne sich auf die globale Konfiguration des Rechners zu verlassen.aggrega get-schema— verfügbar. Gibt das JSON Schema für eine Entitäts- oder Vertragsart aus.aggrega plugin— verfügbar. Inspiziert die Wasm-Plugins, die die CLI auflösen kann; Unterbefehle listen sie auf, fügen konfigurierte Plugins hinzu und entfernen sie, synchronisieren die maschinenverwalteten Datensätze eines Plugins und erzeugen eine Katalogansicht davon.aggrega cache— verfügbar. Inspiziert und pflegt die Caches auf dem Datenträger; Unterbefehle melden den Status, bereinigen, entfernen Einträge und leeren die Caches.aggrega mcp— verfügbar. Startet einen Model-Context-Protocol-Server über stdio oder über HTTPS für einen Client auf einem anderen Rechner und stellt die Introspektion des Compilers für KI-Assistenten-Integrationen bereit.aggrega completion— verfügbar. Erzeugt das Shell-Autovervollständigungsskript für die CLI.- CLI-Erweiterungsunterbefehle — verfügbar. Ein Wasm-Plugin, das als Gast
pluginType: cliveröffentlicht ist, wird aufgelöst und als Unterbefehl vonaggregaregistriert, sodass eine installierte Erweiterung neben den eingebauten Befehlen alsaggrega <extension>läuft. aggrega import— verfügbar. Wandelt eine fremde deklarative Quelle für Agentendefinitionen (Langflow, Flowise, n8n) in Entwürfe von Aggregate- und Component-Authoring-Dateien um, mit einer deterministischen, nach Konfidenz bewerteten Entscheidung zur Katalogwiederverwendung, die pro Knoten festgehalten wird. Das formatspezifische Mapping liefert ein Importer-Plugin, das der Workspace für das Quellformat auflöst — eines aus seinem Katalog oder einer der Importer für Langflow, Flowise und n8n des Compilers, die mit jedem Compiler-Release gebaut und veröffentlicht werden. Das Binärprogramm enthält ihre Plugin-Entitäten, aber nicht ihre Module, sodass sie ihre Formate in jedem Workspace bedienen: Der erste Import, der einen benötigt, den der Rechner nicht hat, holt ihn aus der Standard-Registry des Workspace, prüft ihn und behält ihn für jeden späteren Import im Inhalts-Cache. Eine Quelle wird mit dem Parser geparst, den der Katalog des Workspace für ihre Syntax bereitstellt, oder, wo der Katalog keinen bereitstellt, mit dem, den der Compiler mitbringt, sodass ein Workspace, dessen Katalog keinen Parser enthält, über einen der beiden importiert.aggrega scaffold— verfügbar. Entwirft ein Startdokument für jede Entitätsart aus dem Schema dieser Art — jedes Feld, das sie verlangt, mit einem Platzhalter, wo ein Wert benötigt wird — und schreibt es auf die Standardausgabe; mit--exampleschreibt es eines der ausführbaren Beispiele der Dokumentation, gelesen aus dem signierten Dokumentations-Bundle, in ein neues Verzeichnis.aggrega explain— verfügbar. Erklärt die Abbruchbedingung, die ein Kurzcode (etwaE0007) oder ein beschreibender Code nennt.aggrega edit-document— verfügbar. Wendet eine begrenzte strukturierte Änderung auf ein Dokument an — eine Komponente hinzufügen, ein Feature anhängen, eine Verbindung verdrahten oder einen Wert setzen — und bewahrt jedes Byte, das sie nicht berührt.aggrega pin— verfügbar. Zeichnet in derentity.lockneben einer Recipe oder einem FeatureRecipe den Inhalts-Pin für jede Eingabe auf, die die Entität von außerhalb ihres eigenen Dokuments liest.aggrega skills— verfügbar. Installiert den Aggrega-Skill in einen KI-Assistenten.
Siehe 07-cli.md für den CLI-Überblick und den Index der Sprachreferenz für alle Referenzseiten der einzelnen Befehle.
Editoren und andere Frontends
Jedes Frontend zeigt, was das Binary aggrega kompiliert hat; keines bringt einen eigenen Compiler mit. Status je Oberfläche:
- IR-Graph-Vertrag — verfügbar. Das IR-Graph-Schema, der Vertrag, gegen den jedes Frontend den Graphen liest, wird als Teil der Aggrega-Schemadistribution ausgeliefert; siehe die IR-Schemareferenz.
- Den Graphen aus einem Befehl lesen — verfügbar.
aggrega buildakzeptiert--ir-graph, ebensoaggrega inspect, wenn ein Release angegeben ist, undaggrega validate --release; das Flag schreibt den in diesem Lauf aufgelösten Graphen zusätzlich zu dem, was der Befehl ohnehin erzeugt, als JSON auf stdout. Eine Daemon-Sitzung liest denselben Graphen unteraggrega/irGraph, und die Werkzeugecli-inspect,cli-buildundcli-validatedes MCP-Servers nehmen ihn als ihr Argumentir_graphentgegen. - Topologiegraph in Visual Studio Code — verfügbar. Die Aggrega-Erweiterung für Visual Studio Code zeichnet den IR-Graphen des ausgewählten Release als interaktiven Graphen und hängt von dort aus Features an; beides erfragt sie beim Daemon
aggrega serve. - Headless-Streaming-Modus der CLI — geplant. Der Headless-Modus gibt den IR-Graphen als zeilengetrenntes JSON auf stdout aus, damit ein Frontend ihn verarbeiten kann, während sich die Topologie ändert. Heute wird ein Dokument pro Aufruf ausgeliefert statt eines Streams: Kein Befehl gibt eine Folge von Graphen auf einem einzigen stdout aus, während sich eine Topologie ändert.
Siehe ../architecture/15-editors-assistants-and-frontends.md dazu, wie der Editor, der Assistent und der Daemon den Compiler erreichen.
Entwurfsrichtungen
Die Status-Taxonomie oben klassifiziert den Zustand pro Oberfläche für die gesamte Sprache; dieser Abschnitt hält den Status breiterer Entwurfsrichtungen fest, die in den Architekturkapiteln dokumentiert sind.
Compliance über den gesamten Bestand ist keine geplante Richtung: Eine Governance-Regel einmal so festzulegen, dass sie jeden Build im Workspace bindet, ist heute über den Governance-Socket verfügbar. Ein Plugin, das am Schlüssel plugins.governance der Workspace-Konfiguration angehängt ist, bewertet jeden Build in diesem Workspace — eine Urteilsrolle, die einen Graphen oder ein gerendertes Artefakt ablehnt, das die Regel verletzt, eine Transformationsrolle, die abgeleitete Metadaten liefert, die ein Entwickler nie eintippt. Siehe ../architecture/11-governance-and-compliance.md.
- Interface Parity & Auto-Implementation — verfügbar. Eine Recipe, die gegen eine Basis-Component geschrieben ist, bedient jede Component, die diese erweitert, in jeder Tiefe der Kette, ohne dass der Architect ein doppeltes Recipe verfassen muss. Die erweiternde Component schreibt
schema: inheritedund fügt dahervalues/infra/provideskeinen Wurzelschlüssel hinzu, den die Recipe der Basis nicht verarbeiten könnte; eine Component, dieextendsmit einem eigenen Schema deklariert, wird an ihrem Dokument-Envelope abgelehnt. Das Manifest mappt den erweiternden Typ weiterhin mit einem eigenen Eintrag, und die Mapping-Prüfung akzeptiert ihn, wenn dasimplementsder gemappten Recipe den Typ oder eine beliebige Basis nennt, die er erweitert. Dokumentiert in../architecture/02-ecosystem-philosophy.md. - Ghost Infrastructure Tracker — verfügbar. Eine Schutzvorrichtung in der Rendering-Phase gibt eine Warnung aus, wenn ein Schlüssel, den ein Autor deklariert hat, einen Knoten erreicht und kein Template, das die gebundene Recipe deklariert, ihn liest, sodass ein vom Autor deklarierter und vom Template stillschweigend verworfener Wert benannt wird, statt verloren zu gehen. Sie ist die Rendering-Phasen-Hälfte desselben Entwurfs zum Formabgleich. Siehe
errors/warnings.md.
Die Architekturkapitel beschreiben die Entwurfsoberflächen; diese Seite verfolgt den Implementierungsstatus.