Aggrega-Dateien verfassen
Das Verfassen in Aggrega ist ein kurzer, wiederholbarer Kreislauf. Welche Entität Sie auch schreiben — das Aggregate eines Entwicklers, die Component eines Architekten, ein Recipe des Betriebs oder das Release eines Operators —, dieselben fünf Schritte führen Sie von einer leeren Datei zu einer validierten:
- Wählen Sie die Entität, für die Ihre Rolle zuständig ist.
- Lernen Sie ihre Struktur aus dem JSON Schema und der Referenzseite kennen.
- Beginnen Sie mit einem Gerüst statt mit einer leeren Datei.
- Füllen Sie die Felder aus, für die Ihre Rolle zuständig ist, und überlassen Sie den Rest den jeweils Zuständigen.
- Validieren Sie, dann kompilieren Sie.
Diese Seite durchläuft den Kreislauf einmal, sowohl für eine Person, die von Hand schreibt, als auch für einen KI-Assistenten, der über den Model-Context-Protocol-Server schreibt. Beide Wege sind derselbe Kreislauf über dieselben Referenzquellen. Beide benötigen die Binärdatei aggrega: Die Binärdatei installieren installiert sie mit einem Befehl.
1. Die Entität wählen, für die Ihre Rolle zuständig ist
Aggrega teilt das Verfassen auf vier zusammenarbeitende Rollen auf — Entwicklerabsicht, Plattformkatalog, Infrastruktur-Rezepte und Deployment-Verdrahtung. Jede Rolle ist in der Regel für eine bestimmte Gruppe von Entitätsarten zuständig. Wenn Sie Ihre Rolle bereits kennen, springen Sie direkt zur benötigten Entität; andernfalls lesen Sie Personas zu den vier Rollen und Entitäten nach Rolle für die vollständige Zuordnung von Art zu Rolle.
Die Trennung ist eine Orientierungshilfe, keine Regel, die der Compiler durchsetzt. Wer allein arbeitet, kann jede Rolle übernehmen und alle Entitäten in einem Zug schreiben; der Compiler akzeptiert jedes Vorgehen beim Verfassen, das die Schemavalidierung besteht. Die Rollen dienen dazu, Zuständigkeiten klar zu halten, nicht dazu, einzuschränken, was Sie schreiben dürfen.
2. Die Struktur kennenlernen
Jede Entitätsart hat ein kanonisches JSON Schema und eine Referenzseite, die Feld für Feld beschreibt. Lesen Sie beide, bevor Sie schreiben:
- Das Schema ist die genaue Struktur: Pflichtfelder, zulässige Werte und Verschachtelung. Auf der Kommandozeile gibt
aggrega get-schema <kind>es aus;aggrega get-schema --listnennt jede Art, die Sie abfragen können. Ein Assistent liest dieselben Bytes aus der Ressourceschema://<kind>. Siehe die Referenz zuaggrega get-schema. - Die Referenzseite erklärt, was jedes Feld bedeutet und wie die Felder zusammenhängen. Die Entitätsseiten liegen unter
language-reference/entities/— zum Beispiel component oder aggregate. Ein Assistent liest dieselbe Seite aus der Ressourcelangref://entities/<kind>.
Das Schema sagt Ihnen, was strukturell gültig ist; die Referenz sagt Ihnen, was sinnvoll ist. Lesen Sie das Schema, um eine Ablehnung bei der Validierung zu vermeiden, und die Referenz, um etwas zu verfassen, das tut, was Sie beabsichtigen.
3. Mit einem Gerüst beginnen
Mit einem Gerüst zu beginnen ist schneller und weniger fehleranfällig als eine leere Datei. Ein mit dem MCP-Server verbundener Assistent ruft das Werkzeug scaffold mit einer Art und einem Namen auf und erhält einen minimalen Ausgangspunkt, der jedes von der Art verlangte Feld enthält, mit einem Platzhalter überall dort, wo noch ein Wert fehlt. Wenn Sie von Hand schreiben, gibt aggrega scaffold <kind> <name> denselben Ausgangspunkt auf der Standardausgabe aus, leiten Sie ihn also in eine Datei um; oder kopieren Sie das am besten passende ausgearbeitete Beispiel und kürzen es auf das, was Sie brauchen.
In beiden Fällen enthält das Gerüst bereits die erforderlichen Felder der obersten Ebene (apiVersion, kind, metadata.name) in der richtigen Form, sodass Sie Ihre Aufmerksamkeit auf die Felder Ihrer Rolle richten statt auf Boilerplate.
4. Die Felder ausfüllen, für die Ihre Rolle zuständig ist
Füllen Sie nur die Säulen aus, für die Ihre Rolle verantwortlich ist, und überlassen Sie die anderen den jeweils Zuständigen. Ein Entwickler liefert Anwendungsabsicht und Werte; ein Architekt deklariert den Vertrag — die Werte, die ein Entwickler liefern darf, die Ausgaben, die eine Komponente bereitstellt, die Sockets, die sie anbietet; der Betrieb bildet diesen Vertrag auf einen bestimmten Provider ab, ohne die entwicklerseitige Oberfläche zu ändern; ein Operator verdrahtet das Deployment. Entitäten nach Rolle legt für jede Art dar, welche Säulen zu welcher Rolle gehören.
Dass jeder Wert in der Säule bleibt, die sein Zuständiger kontrolliert, ermöglicht es derselben Entwicklerabsicht, in verschiedenen Umgebungen unterschiedliche Infrastruktur anzusteuern, ohne dass sich die Datei des Entwicklers ändert. Genau deshalb ist die Oberfläche zum Verfassen überhaupt aufgeteilt.
Halten Sie die Beschreibung auf wenige kurze Absätze beschränkt. Die metadata.description einer Entität ist der Text, den ein Leser sieht, bevor er sie auswählt: Sie wird mit der Entität als ihre durchsuchbare Beschreibung veröffentlicht, und aggrega search gleicht eine Suchanfrage mit ihr ab. Schreiben Sie sie für diesen Moment, in kurzen Absätzen — in einem gefalteten description: >-Block beginnt eine Leerzeile einen neuen —, und sagen Sie, was die Entität ist, wie ein Leser sie verwendet, wo sie realisiert wird und was sie nicht tut. Eine Einschränkung, die ein Leser vor der Auswahl der Entität kennen muss, gehört ebenfalls dorthin, kurz formuliert. Alles andere — warum ein Standardwert so ist, wie er ist, wie sich eine Einstellung auf einem Ziel verhält, was ein Wert unter jeder Realisierung bedeutet — gehört in YAML-Kommentare neben dem Feld oder Block, den es erklärt, wo die Person, die mit diesem Feld arbeitet, es liest. Nichts im Compiler begrenzt die Länge einer Beschreibung oder reagiert auf ihren Inhalt; sie kurz zu halten, geschieht also um des Lesers willen.
5. Validieren, dann kompilieren
Prüfen Sie die Datei, bevor Sie sich auf sie verlassen:
- Ein Assistent ruft das Werkzeug
validateauf, das Schema- und Referenzfehler direkt meldet, sodass er den Entwurf korrigieren kann, bevor er ihn zurückgibt. - Von Hand prüft
aggrega validate <file>eine einzelne Component-, Feature-, Recipe-, FeatureRecipe-, Workload- oder Plugin-Datei, undaggrega validate --release <release>prüft alles, was ein Release erreicht, einschließlich seines Aggregate und Manifest.aggrega lintwendet die Regeln der Veröffentlichungsdisziplin auf eine Katalogentität an, undaggrega inspectlöst auf und zeigt, was der Compiler sieht. Wenn die gesamte Topologie bereit ist, löstaggrega pull --release <release>ihre Abhängigkeiten auf und schreibt ihre Lockfile, undaggrega build --release <release>kompiliert dann das Release in Artefakte pro Grenze — ein fehlgeschlagener Build nennt genau, was zu beheben ist.
Frühe Validierung ist günstiger als ein später fehlgeschlagener Build. Verfassen, validieren, korrigieren und erst dann kompilieren.
Verfassen mit einem KI-Assistenten
Der Befehl aggrega mcp startet einen Model-Context-Protocol-Server, der jeden MCP-fähigen Client in einen Assistenten zum Verfassen macht, der Aggrega kennt. Nach der Verbindung kann der Assistent:
- Eine Rolle einnehmen über die integrierten Prompts zum Verfassen — einer pro Persona (Entwickler, Architekt, Betrieb) plus eine gezielte Vorlage pro Entität. Jeder Prompt umreißt die Rolle und verweist den Assistenten auf das Schema, die Referenzseite und diesen Leitfaden, sodass seine Vorschläge innerhalb der Säulen bleiben, für die die Rolle zuständig ist.
- Die Referenz lesen über Ressourcen:
schema://<kind>für das JSON Schema einer Art,langref://<path>für jede Referenzseite undauthoring://<topic>für diesen Leitfaden. - In Ihrem Workspace handeln über Werkzeuge:
scaffold, um ein korrektes Gerüst anzulegen,validate, um einen Entwurf zu prüfen,describe, um eine Katalogentität zu untersuchen, undget-schema, um ein Schema nach Art abzurufen.
Alles, was der Assistent liest, wird von Ihrem Rechner bereitgestellt: Die Schemas sind in die Binärdatei eingebaut, und die Seiten des Leitfadens und der Referenz stammen aus dem Dokumentationspaket im Cache Ihres Rechners, das der Server aus der Registry abruft, wenn er startet und dort keine Kopie findet. Das Lesen einer Seite, das Erzeugen eines Gerüsts und das Validieren greifen nicht auf das Netzwerk zu; wo das Paket nicht abgerufen werden kann, werden die Schemas weiterhin bereitgestellt und die Seiten nicht. Um einen Client zu verbinden, folgen Sie Den MCP-Server verbinden; Was Ihr Assistent mit Aggrega tun kann behandelt den Rest dessen, was er erreicht. Zum Befehl selbst siehe die Referenz zu aggrega mcp.
Wie es weitergeht
- Personas — verstehen Sie die vier Rollen, bevor Sie eine Entität wählen.
- Entitäten nach Rolle — die vollständige Zuordnung von Art zu Rolle.
- Installation — die Binärdatei installieren; Den MCP-Server verbinden verbindet Ihren Assistenten.
- Aggrega mit Ihrem KI-Assistenten einrichten — ein einziger Prompt, mit dem Ihr Assistent Aggrega selbst installiert und verbindet.
- CLI-Übersicht — jeder Unterbefehl von
aggrega.