Konfiguration
Woher aggrega seine Einstellungen liest und in welche Datei eine Einstellung gehört.
Der einfache Fall
Zwei Dateien, und die meisten Projekte brauchen nichts weiter.
Eine Datei in Ihrem Projekt, namens .aggrega-config.yaml, im Stammverzeichnis des Projekts. Sie legt fest, wie dieses Projekt gebaut wird: welche Verzeichnisse eingebundene Katalog-Inhalte enthalten, welche Plugins welche Ziele rendern, welche Lint-Regeln gelockert sind, wohin der lokale Cache kommt. Sie wird committet, sodass ein Teammitglied, das das Projekt klont, es auf dieselbe Weise baut.
Ihr workspace:-Block ist das, was das Verzeichnis als Projektstamm kennzeichnet:
# <project>/.aggrega-config.yamlworkspace: catalog_dirs: - ./catalogauto_pull: trueDer Block enthält nur die Katalogverzeichnisse, die den Stamm definieren; jede andere Einstellung steht daneben auf oberster Ebene. Ein Projekt, das keine Katalog-Inhalte einbindet, schreibt den Block trotzdem, leer — workspace: {} —, denn das Vorhandensein des Blocks ist die Kennzeichnung.
Eine globale Datei auf Ihrem Rechner, unter ~/.config/aggrega/config.yaml — unter Windows als aggrega\config.yaml in dem Verzeichnis, das die Umgebungsvariable APPDATA angibt. Jeder Workspace auf diesem Rechner wird über sie aufgelöst, und sie enthält Einstellungen, die zum Rechner gehören statt zu einem einzelnen Projekt — die Registries, aus denen Sie pullen, und die Vertrauensrichtlinie für Signaturen jeder einzelnen, wie groß der Speicher kompilierter Module werden darf, und jedes Befehlserweiterungs-Plugin, das Sie installiert haben. Diese sind gleich, wo immer Sie arbeiten, und genau darum geht es: sie einmal zu deklarieren. Sie wird automatisch geladen, wenn sie vorhanden ist, und nichts bricht, wenn sie fehlt.
registries: - host: hub.aggrega.ai signing: required: trueaggrega config init schreibt diese globale Datei für Sie, registriert eine Registry zusammen mit der Vertrauensrichtlinie für Signaturen, die sie ausweist, und gibt an, wo die Datei auf Ihrem Rechner liegt und wo die rechnerweiten Caches abgelegt sind. aggrega config show gibt aus, was gerade gilt, und aggrega config show --origin gibt an, welche Datei — oder welche Umgebungsvariable — jede Einstellung festgelegt hat.
Geheimnisse sind keine Konfiguration. Ein Registry-Passwort und ein Identitätstoken zum Signieren sind niemals Felder in einer der beiden Dateien; sie werden per Umgebungsvariable oder Flag in dem Moment geliefert, in dem sie gebraucht werden. Siehe environment-variables.md.
Woher lokale Entitäten gelesen werden
Ein Projekt, das eigene Katalog-Inhalte führt — eine Component, ein Feature, ein Recipe, eine der Bibliotheksarten —, hat zwei Möglichkeiten anzugeben, wo diese Inhalte liegen, und die erste erfordert überhaupt keine Konfiguration.
Ein catalog-Verzeichnis im Projektstamm wird gelesen, ob etwas es nennt oder nicht. Legen Sie eine Entität unter <project>/catalog/ ab, und jeder Befehl, der einen Katalog lädt, liest sie, auch in einem Projekt, dessen workspace:-Block leer ist. Ein Katalogverzeichnis wird rekursiv gelesen, wie Sie Unterverzeichnisse darin anordnen, bleibt also Ihnen überlassen.
Unter workspace.catalog_dirs aufgeführte Verzeichnisse werden ebenfalls gelesen, und zwar zuerst. Die Liste ist ein geordneter Suchstapel: Das erste Verzeichnis, das eine Identität deklariert, besitzt sie, und dieselbe Identität in einem späteren Verzeichnis wird verdeckt. catalog wird nach allem Aufgeführten gelesen — es sei denn, ein aufgeführtes Verzeichnis enthält es bereits; dann wird es als Teil dieses Verzeichnisses gelesen —, sodass das Aufführen eines Verzeichnisses das Bisherige ergänzt, statt es zu ersetzen. Ein wiederholbares --catalog <dir> auf der Befehlszeile wird vor beiden gelesen, und ein dort angegebener relativer Pfad wird relativ zu dem Verzeichnis aufgelöst, aus dem Sie den Befehl ausgeführt haben, da keine Konfigurationsdatei ihn deklariert hat. Ein mehrfach genanntes Verzeichnis — auf der Befehlszeile und in der Liste oder zweimal in der Liste — wird einmal gelesen, an der Stelle, an der es zuerst genannt wurde, sodass nichts darin als von sich selbst verdeckt gemeldet wird: Eine Verdeckung sind immer zwei verschiedene Dateien, die eine Identität deklarieren. Zwei Schreibweisen eines Verzeichnisses, ein Pfad dorthin über einen Link und — auf einem Dateisystem, das Groß- und Kleinschreibung ignoriert — eine Schreibweise in anderer Groß-/Kleinschreibung bezeichnen alle dieses eine Verzeichnis. Ein Verzeichnis innerhalb eines anderen aufgeführten Verzeichnisses wird dennoch als eigener Eintrag gelesen. Ein Projekt, das eine Katalogvariante pro Release führt, kann stattdessen jedem Release eine eigene Liste geben — siehe Einem Release eigene Katalogverzeichnisse geben.
Ein Verzeichnis aufzuführen ist die Art, wie ein Projekt Entitäten liest, die außerhalb davon liegen. Ein aufgeführtes Verzeichnis darf überall liegen — ein benachbarter Checkout, ein mit anderen Projekten geteiltes Verzeichnis — und wird dort gelesen, wo es liegt, selbst wenn es selbst ein symbolischer Link ist. Nichts anderes reicht so weit: Ein Link innerhalb des Projekts, der anderswohin führt, wird nicht verfolgt, und ein Dokument, das eine Datei außerhalb des Projekts über einen Pfad nennt, wird abgelehnt; eine anderswo geführte Entität wird also erreicht, indem man das Verzeichnis aufführt, das sie enthält, und die Entität bei ihrem Namen nennt. Ein aufgeführtes Verzeichnis außerhalb des Projekts ist ein eigener Stamm, daher wird auch ein Link darunter, der aus ihm herausführt, nicht gelesen. Die Workspace-Grenze legt die vollständige Regel dar.
Ein aufgeführtes Verzeichnis muss ein Verzeichnis sein. Ein aufgeführter Pfad, an dem nichts existiert oder an dem eine Datei oder ein ins Leere führender Link steht, wird von jedem Befehl, der den Katalog liest, abgelehnt, bevor irgendetwas gelesen oder geschrieben wird — von einem Pull, einem Build, einer Validierung, einer Inspektion, einem Lint und denselben Vorgängen, die aus dem Editor über aggrega serve oder von einem Assistenten über aggrega mcp ausgelöst werden —, sodass ein Build nie gegen weniger Kataloge läuft, als Sie aufgeführt haben. Die Ablehnung nennt den Eintrag, wie er geschrieben ist, den Pfad, zu dem er aufgelöst wurde, die Konfigurationsdatei und die Zeile, die ihn aufführen, sowie die Liste, in der er steht:
<project>/.aggrega-config.yaml:4: the `workspace.catalog_dirs` entry "../shared/aggrega-catalog" names <directory>, which does not exist; create that directory, or remove the entry: workspace configuration is invalidLegen Sie das Verzeichnis an oder entfernen Sie den Eintrag: Eine Kopie eines Projekts, die ohne einen von ihm aufgeführten benachbarten Checkout erstellt wurde, entfernt diesen Eintrag und löst aus einer Registry auf, was der Checkout geliefert hätte. Dasselbe gilt für ein Verzeichnis, das der eigene Eintrag eines Release aufführt, für eines, das eine Konfigurationsdatei Ihrer Pipeline oder die globale Datei hinzufügt, und für eines, das AGGREGA_CATALOG_DIRS enthält, das die Ablehnung anstelle einer Datei nennt. Die Konfiguration selbst wird weiterhin geladen, sodass ein Befehl, der keinen Katalog liest, weiterhin läuft. Ein --catalog-Verzeichnis, das nicht existiert, wurde für einen einzelnen Befehl eingegeben, und aggrega build lehnt es ab und nennt das Verzeichnis. Ein aufgeführtes Verzeichnis, das vorhanden ist und nicht gelesen werden kann, wird von den Befehlen, die den gesamten Katalog laden, unter Nennung des Verzeichnisses abgelehnt.
Die Liste leer zu schreiben besagt, dass dieses Projekt überhaupt keinen lokalen Katalog hat, und es ist die einzige Schreibweise, die auch das Lesen von catalog verhindert:
# <project>/.aggrega-config.yamlworkspace: catalog_dirs: []Den Schlüssel wegzulassen ist eine andere Aussage: Eine weggelassene Liste ist der Normalfall, und catalog wird weiterhin gelesen.
Ein Build, ein Pull, eine Validierung oder ein aggrega inspect, das unter einem von Ihnen verwendeten Namen keine Entität findet, sagt, woher dieses Projekt lokale Entitäten liest und was zu ändern ist, damit die genannte gelesen wird. Nichts dergleichen sagt es, wo Sie die leere Liste geschrieben haben — keinen lokalen Katalog zu lesen ist genau das, was Sie dort deklariert haben, und ein Vorschlag, das zu ändern, würde Ihnen widersprechen. Ebenso wenig sagt es dies, wo das Dokument, das diesen Namen deklariert, gelesen und abgelehnt wurde: Dieses Dokument liegt bereits dort, wo der Katalog liest, daher nennt der Bericht stattdessen, wogegen das Dokument verstößt, die Zeile und die Einschränkung, und es zu verschieben würde nichts beheben. Ein Dokument, das so fehlerhaft ist, dass der von ihm deklarierte Name gar nicht gelesen werden kann, lässt sich dem von Ihnen verwendeten Namen nicht zuordnen, daher wird die Auskunft trotzdem gegeben — und wo dieses Dokument eine Aggrega-apiVersion deklariert, nennt ein Build, ein Pull oder eine Validierung eines Release es neben der Auskunft, mit dem eigenen Grund des Parsers, da es die zu öffnende Datei sein kann. Ein Fehler, der die Entität gefunden hat und sie nicht akzeptieren konnte — eine Registry, die nun unter einer Version, die Ihre Lockfile pinnt, andere Bytes ausliefert, eine Datei, die die Entität mitführt und die nicht gelesen werden kann —, ist ebenfalls keine fehlende Entität und meldet allein seine eigene Abhilfe.
Ob ein Pull oder ein Push eine Entität pinnt
Ein Recipe oder FeatureRecipe führt die Pins für die Eingaben, die es liest — ein vollständig ausgeschriebenes entferntes source:, eine Datei, die ein artifacts-Eintrag importiert, die Dateien eines source: daneben — in der entity.lock daneben, und sie zu erfassen ist der Schritt des Entitätsautors, aggrega pin. Standardmäßig führt weder pull noch push diesen Schritt aus: Ein Pull hält bei einer Entität an, die ihr Lock nicht pinnt, und ein Push verweigert ihre Veröffentlichung. Zwei Schlüssel, einer pro Befehl, machen seine Ausführung zum Standard dieses Befehls:
# <project>/.aggrega-config.yamlworkspace: {}pin_sources_at_pull: truepin_sources_at_push: trueJeder Schlüssel steuert seinen eigenen Befehl und nichts anderes, und das --pin-sources jedes Befehls überschreibt dessen eigenen Schlüssel in beide Richtungen — --pin-sources=false schaltet den Schritt für einen Lauf in einem Projekt ab, das zum Pinnen konfiguriert ist. Ein Build, der seine eigene Lockfile befüllt, ist ein Pull und folgt pin_sources_at_pull. Die Schlüssel gehören in die Projektdatei statt in die globale: Ob die Pulls eines Projekts Pins erfassen, ist die Richtlinie dieses Projekts, und ein Teammitglied, das es klont, sollte dieselbe Antwort erhalten. pin_sources_at_pull ist zudem die Art, wie ein Projekt, das den ungepinnten Katalog eines anderen nutzt, diese Pins einmal erfasst, statt bei jedem Pull anzuhalten.
Welches Plugin eine Capability rendert
Ein Recipe nennt die Capability, über die es rendert — capability: helm —, und ein Plugin, das diese Capability bedient, rendert es. Wo genau ein Plugin eine Capability bedient, muss nichts konfiguriert werden. Wo mehr als eines sie bedient, gibt ein plugins.providers-Eintrag anhand der Identität des Plugins an, welches:
# <project>/.aggrega-config.yamlworkspace: {}plugins: providers: - capability: helm uri: provider/helmEin Pull löst den Eintrag auf und erfasst das gewählte Plugin in der Lockfile des Release, und ein Build rendert über das, was die Lockfile erfasst, daher wird eine Änderung hier beim nächsten Pull wirksam.
Die uri nennt das Plugin über seine Identität, provider/<name>, nie über den Ort, an dem es veröffentlicht ist. aggrega plugin add provider <query> --capability <capability> schreibt den Eintrag in dieser Form, ohne Version: Der Eintrag wählt aus, welches Plugin die Fähigkeit bedient, die Version ist die, die das Recipe pinnt, andernfalls die höchste verfügbare, und die Lockfile verzeichnet die, die der Pull gewählt hat. Ein Plugin, das der Compiler in sich mitführt, wird in der eigenen Version des Compilers bereitgestellt, sodass eine Version, die auf einem Eintrag für ein solches Plugin geschrieben ist, nur dann aufgelöst wird, wenn sie diese Version ist. Ein Eintrag, dessen uri ein Registry-Ort ist — oci://hub.aggrega.ai/plugin/provider/helm —, nennt keine Plugin-Identität und wird beim Laden der Datei abgelehnt, unter Nennung des Eintrags und der zu schreibenden Form.
Die Einträge werden einmal für das gesamte Projekt geschrieben, während ein Build ein einzelnes Release betrifft, daher ist ein Eintrag für eine Capability, die dieses Release nie anfordert, zulässig — ein anderes Release im Projekt liest ihn — und wird nicht gemeldet. Was jeder Build und jedes aggrega validate --release prüft, ist jeder Eintrag, ob ein Recipe seine Capability anfordert oder nicht, anhand dessen, was der Eintrag nennt:
- Ein Eintrag, der ein Plugin nennt, dessen Plugin seine Capability nicht bedient, stoppt den Build und lässt die Validierung fehlschlagen. Ein Pull löst jeden Eintrag auf, der ein Plugin nennt, und lehnt einen ab, den er nicht auflösen kann; sobald ein Eintrag einen Pull durchlaufen hat, hält der Build also dessen Plugin und weiß, was es bedient; ein Eintrag, der ein Plugin nennt, das der Build noch nicht hält, wird beurteilt, sobald ein Pull es abgerufen hat. Die Meldung nennt den Eintrag, das Plugin, was dieses Plugin tatsächlich bedient, und eine Schreibweise, die eine Änderung entfernt ist, sofern es eine gibt — die Form, die ein Tippfehler wie
hlemfürhelmannimmt. - Ein Eintrag, der nur eine Capability nennt, die kein vom Build gelesenes Plugin bedient, ist eine Warnung, und der Build läuft weiter. Das Plugin, das sie bedient, wird möglicherweise nur von einem anderen Release gelesen, das dieser Build nicht sehen kann, und ein Eintrag, der kein Plugin nennt, wählt nichts aus, was die Auflösung der Capability nicht auch ohne ihn auswählen würde.
Eine Capability enthält hier niemals einen Doppelpunkt, und eine, die einen enthält, wird beim Laden der Datei abgelehnt. Das capability: eines Recipe wird als die Capability bis zum letzten Doppelpunkt und ein Versions-Pin danach gelesen, daher könnte ein Eintrag mit dem Schlüssel helm:1.0.0 niemals nachgeschlagen werden. Pinnen Sie die Version stattdessen am Plugin — uri: provider/helm:1.0.0 — oder im Recipe.
Welcher Importer eine Quelle in Entwürfe umwandelt
aggrega import übergibt eine Quelle an den Importer, der das Format der Quelle ausweist — einen in Ihrem Katalog oder einen der Kern-Importer des Compilers, import:langflow für einen Langflow-Flow. Wo genau ein Importer es ausweist, muss nichts konfiguriert werden. Ein plugins.importer-Eintrag bindet einen Importer an, indem er ihn in seinem uri nennt, mit Identität und Version, und übergibt ihm, was er unter with mitführt:
# <project>/.aggrega-config.yamlworkspace: {}plugins: importer: - uri: importer/agent-flows:1.2.0 with: settings: target_namespace: paymentsaggrega plugin add importer schreibt den uri genau in dieser Form. Die Version ist exakt — :1.2.0 — oder ein Bereich — :^1.2.0 für die höchste Version, die gleich oder höher ist, innerhalb derselben Hauptversion. Schreiben Sie das eine oder das andere: In dieser Liste wird ein uri ohne Doppelpunkt als Dateisystempfad gelesen, wie Wohin ein relativer Pfad zeigt beschreibt, und nennt keinen Importer.
Was ein Eintrag bewirkt, hängt davon ab, ob der Importer, den er nennt, das Format ausweist, das ein Import anfordert:
- Er weist es aus: Dieser Importer ist derjenige, der ausgeführt wird, in der Version, die der
urinennt, ganz gleich, wie viele andere Importer im Katalog das Format ebenfalls ausweisen, und ihm werdenwith.sourcesundwith.settingsdes Eintrags übergeben. Ein Eintrag ist die Art, wie ein Workspace, dessen Katalog die Importer zweier Herausgeber für ein Format föderiert, angibt, welchen davon er verwendet. - Er weist es nicht aus — er nennt einen Importer eines anderen Formats, ein Plugin einer anderen Art oder nichts, was Ihr Katalog enthält oder der Compiler mitführt: Der Eintrag spielt bei diesem Import keine Rolle. Er wählt nichts aus, und sein
withwird keinem Importer übergeben. Die Einstellungen eines Eintrags erreichen nur den Importer, den er nennt, sodass ein Workspace, der einen Importer pro Format anbindet, jeden konfiguriert, ohne dass die Einstellungen des einen den anderen erreichen.
Wo mehr als ein Importer das Format ausweist und keiner davon allein angebunden ist — keiner ist es, oder Einträge nennen zwei davon —, wird der Import abgelehnt, mit Nennung der Importer, zwischen denen er nicht wählen konnte. Ein Eintrag, der einen Importer nennt, der das Format ausweist, in einer Version, die keine seiner Versionen im Katalog erfüllt — eine exakte Version, die der Katalog nicht enthält, oder ein Bereich, in den keine seiner Versionen fällt —, wird ebenfalls abgelehnt, mit Nennung der Version, statt an ihrer Stelle eine andere Version auszuführen; eine Version, die überhaupt keine ist, wie :latest, wird als fehlerhaft abgelehnt. Eine Plugin-Entität eines der Core-Importer des Compilers ohne Modul daneben in ihrem Katalogordner ist kein Kandidat: In der eigenen Version des Compilers läuft an ihrer Stelle der Core-Importer, und in jeder anderen Version bleibt die Entität nur dort ein Kandidat, wo ein Eintrag genau diese Version nennt oder kein lauffähiger Importer ihres Namens das Format ausweist, wie Welcher neben Ihren eigenen Importern läuft beschreibt.
Jeder Importer wird durch einen einzigen Eintrag angebunden. Zwei Einträge, die einen Importer nennen — dieselbe Identität, in einer Version oder in zwei —, werden beim Laden der Konfiguration abgelehnt, gleich welcher Befehl sie liest, mit Nennung beider Einträge und der Dateien, in denen sie geschrieben wurden. Die Regel erstreckt sich über jede Datei, die zur Liste beiträgt: Ein Eintrag in der globalen Datei, einer in der Datei eines Projekts, einer unter importer_append und einer in der .aggrega-config-append-ci.yaml einer Pipeline zählen alle, daher bedeutet das Umstellen eines Importers auf eine neue Version, die Version an seinem einen Eintrag zu ändern. aggrega plugin add importer tut genau das, wenn die plugins.importer-Liste der Datei, die es schreibt, den Importer bereits nennt: Es stellt diesen Eintrag auf die aufgelöste Version um und behält die Position des Eintrags und sein with, statt einen zweiten hinzuzufügen. Es liest keine andere Liste, daher wird ein Importer, der unter importer_append oder in der .aggrega-config-append-ci.yaml einer Pipeline angebunden ist, durch den Befehl ein zweites Mal angebunden, und das Paar wird beim Laden der Konfiguration abgelehnt; ändern Sie die Version eines solchen Eintrags dort, wo er geschrieben ist. Ein Eintrag, dessen uri ein Dateisystempfad ist, nennt keinen Importer und wird nicht verglichen, und die Listen plugins.governance und plugins.linter unterliegen der Regel nicht: Ein Plugin darf ihnen mehr als einmal angebunden werden, jedes Mal mit seinem eigenen with.
Die Parser, über die ein Import liest, benötigen keinen Eintrag. Ein Importer liest seine Quelle — und ein Import, der kein Format nennt, erkennt sie — über einen Parser für die Syntax der Quelle: den, den Ihr Katalog für diese Syntax bereitstellt, und für eine Syntax, für die Ihr Katalog keinen Parser bereitstellt, den, den der Compiler selbst mitführt, darunter JSON. So importiert ein Workspace, dessen Katalog keinen Parser enthält, einen Langflow- oder Flowise-Flow, ohne dass etwas konfiguriert ist. Keine Liste bindet einen Parser an: Ein Parser, den Ihr Katalog für eine Syntax bereitstellt, ist der verwendete, und zwei mit unterschiedlichen Namen, die eine Syntax bedienen, werden abgelehnt, wie A parse or import format is advertised by more than one plugin (Ein Parse- oder Importformat wird von mehr als einem Plugin ausgewiesen) beschreibt.
Bei null anfangen
Ein frisch installiertes aggrega hat keine der beiden Dateien, und das ist ein funktionierender Zustand, kein defekter: Jede Einstellung fällt auf ihren eingebauten Standardwert zurück, und Befehle laufen. Was fehlt, ist eine Registry, aus der Katalog-Inhalte gepullt werden, zusammen mit der Vertrauensrichtlinie, die angibt, welche Signaturen zu akzeptieren sind — und genau das schreibt aggrega config init.
Sie müssen das nicht im Voraus wissen. Ein Befehl, der seine Konfiguration liest und nirgends eine Datei findet, sagt dies einmal auf der Standardfehlerausgabe und nennt aggrega config init als Weg, eine zu erstellen. Es ist ein Hinweis, kein Fehler: Die Standardausgabe bleibt unberührt, nichts wird von Ihnen verlangt, und der Exit-Status ist der, den der Befehl ohnehin gemeldet hätte. Der Hinweis wird nur geschrieben, wenn die Standardfehlerausgabe ein Terminal ist, sodass er Sie an der Tastatur erreicht und sich nie im Log einer Pipeline ansammelt. Sobald eine der beiden Dateien existiert — die Ihres Projekts oder die globale —, erscheint er nicht mehr.
So befüllen Sie die globale Datei mit dem offiziellen Hub und der Vertrauensrichtlinie, die dieser Hub ausweist:
aggrega config initÜbergeben Sie --registry <host>, um eine andere einzutragen, --workspace, um den Eintrag in die Datei dieses Projekts statt in die globale zu schreiben, und --dry-run, um den Inhalt zu sehen, den der Befehl schreiben würde, ohne etwas zu erstellen. aggrega-config.md behandelt den Befehl vollständig.
Wie ein Registry-Host geschrieben wird
Jedes registries[].host nennt einen Registry-Host. Ebenso default_registry — optional gefolgt von einem Repository-Pfad —, sofern es nicht stattdessen einen dieser Einträge nennt (siehe unten). Ein Host wird als der Host selbst geschrieben, in der einen Schreibweise, unter der die Vertrauensrichtlinie der Registry geführt wird:
- ein kleingeschriebener Hostname, der einen Punkt enthält, etwa
registry.example.com; localhostoder ein einzelner Name gefolgt von einem Port, etwaregistry:5000;- eine IPv4-Adresse wie
127.0.0.1oder eine IPv6-Adresse in eckigen Klammern wie[::1];
jeweils mit einem optionalen :port und nichts anderem — kein Schema, kein Pfad, keine Anmeldedaten, kein Leerraum und keine Großbuchstaben. Ein einzelner Name ohne Port ist kein Registry-Host, denn das ist die Form des ersten Segments des Namens einer Katalog-Entität — das core in core/web-api —, und die beiden dürfen niemals miteinander verwechselt werden.
# <project>/.aggrega-config.yamlworkspace: {}default_registry: registry.example.comregistries: - host: registry.example.com signing: required: trueDie Schreibweise ist Teil der Richtlinie. Ein registries-Eintrag gilt für den Host, den sein host: nennt, und die eingebaute Signaturanforderung des offiziellen Hubs gilt für hub.aggrega.ai; ein anders geschriebener Host würde also die richtige Registry erreichen und die für sie geschriebene Richtlinie verfehlen. Er wird stattdessen beim Laden der Konfiguration abgelehnt, und die Ablehnung nennt die zu schreibende Schreibweise: HUB.AGGREGA.AI und https://registry.example.com werden mit Nennung von hub.aggrega.ai und registry.example.com abgelehnt, ebenso registry.example.com/charts als registries[].host, das keinen Pfad trägt. Port 443 ist der Standardport eines über HTTPS erreichten Hosts, daher wird hub.aggrega.ai:443 auf dieselbe Weise abgelehnt, mit Nennung von hub.aggrega.ai. localhost und die anderen Loopback-Adressen werden stattdessen über einfaches HTTP erreicht, wo 443 ein gewöhnlicher Port ist, daher wird localhost:443 wie geschrieben akzeptiert. Ein leeres default_registry nennt keine Standard-Registry.
default_registry darf einen Repository-Pfad tragen. Viele Registries führen jedes Repository unter einem Eigentümer oder einem Projekt — ghcr.io/<owner>, <host>/<project> bei Harbor —, und eine Standard-Registry auf einer davon wird als der Host gefolgt von diesem Pfad geschrieben:
# <project>/.aggrega-config.yamlworkspace: {}default_registry: ghcr.io/acmeregistries: - host: ghcr.io signing: required: trueDer Pfad ist der Ort, an dem veröffentlicht und abgerufen wird. Über diesen Standard veröffentlicht aggrega push core/api-server in Version 1.0.0 unter ghcr.io/acme/component/core/api-server:1.0.0, und ein Pull, der core/api-server auflöst, ruft es vom selben Ort ab, sodass eine bei der Veröffentlichung angehängte Signatur auch dort gefunden wird. Der Pfad ist ein Repository-Pfad in der OCI-Distributionsgrammatik: ein oder mehrere Segmente aus Kleinbuchstaben und Ziffern, verbunden durch /, die innerhalb eines Segments durch ., _, __ oder Bindestriche getrennt sein dürfen, ohne Tag, Digest oder abschließendes /.
Der Pfad ist niemals Teil davon, wie der Registry vertraut wird. Der registries-Eintrag, dessen Richtlinie gilt, die Anmeldedaten, die aggrega login speichert, die Signaturanforderung und die vertrauenswürdigen Identitäten werden alle allein über den Host gefunden, daher gilt der obige Eintrag für ghcr.io für ghcr.io/acme und jeden anderen Pfad auf diesem Host, und keine Schreibweise eines Pfades kann darüber hinausreichen; das host: eines Eintrags selbst trägt keinen Pfad. Ein Host, der vor einem Pfad in einer anderen Schreibweise geschrieben ist, wird mit Nennung des zu schreibenden Ortes abgelehnt — GHCR.io/acme und https://ghcr.io/acme nennen ghcr.io/acme —, und was auf den Host folgt, wenn es kein Repository-Pfad ist, wird mit Nennung des Hosts abgelehnt, auf den es folgt.
default_registry darf stattdessen einen Eintrag nennen. Als name: eines Eintrags unter registries geschrieben, steht es für das host: dieses Eintrags. Veröffentlichung, Pull, Signaturprüfung und jede Vertrauenseinstellung pro Registry verwenden dann diesen Host, und von einem Host, der wie der Name geschrieben wird, werden keine Inhalte abgerufen:
# <project>/.aggrega-config.yamlworkspace: {}default_registry: localregistries: - name: local host: 127.0.0.1:5000Ein Name wird vor einer Host-Schreibweise abgeglichen, so wie das Flag --registry einen abgleicht, daher steht ein Wert, der das name: eines Eintrags ist, für diesen Eintrag, auch wo er zugleich wie ein Host geschrieben ist. Ein Name, den zwei Einträge tragen, wird als mehrdeutig abgelehnt, mit Nennung beider Hosts. Der Eintrag darf in einer der beiden Dateien stehen — das default_registry eines Projekts kann einen Eintrag nennen, den die globale Datei deklariert —, denn der Name wird einmal gelesen, gegen die Einträge, die gelten, nachdem jede Datei und die Umgebung gelesen wurden. Ein Wert, der weder der Name eines Eintrags noch ein Registry-Host ist — allein oder gefolgt von einem Repository-Pfad —, wird abgelehnt, und die Ablehnung sagt, dass jedes von beidem ihn korrigiert. Ein Name gefolgt von einem Pfad, etwa local/acme, wird ebenfalls abgelehnt: Ein Name steht für den Host seines Eintrags und nicht für einen Ort darunter, daher nennt die Ablehnung stattdessen die beiden zu schreibenden Schreibweisen — local oder den Host des Eintrags gefolgt vom Pfad, 127.0.0.1:5000/acme. Das Entfernen eines Eintrags mit aggrega registry remove lässt default_registry so, wie es geschrieben ist, daher nennt ein Standard, der den entfernten Eintrag nannte, danach nichts mehr und wird abgelehnt, bis er neu geschrieben wird.
Jede Ebene unterliegt derselben Schreibweise. Ein Wert wird mit denselben Worten abgelehnt, ob er aus einer Konfigurationsdatei stammt, aus AGGREGA_DEFAULT_REGISTRY oder aus dem Flag --registry, das das Ziel eines aggrega push oder aggrega push-artifact nennt. Dieses Flag nennt einen Host, und die Veröffentlichung, die es lenkt, landet bei diesem Host ohne Repository-Pfad: Ein Pfad gehört zu default_registry. Auch aggrega registry add und aggrega config init --registry unterwerfen den ihnen übergebenen Host dieser Schreibweise; sie akzeptieren an seiner Stelle auch eine Referenz und führen den Eintrag unter dem Host, den die Referenz nennt. Eine Ablehnung aus einer Datei nennt die Datei und den Schlüssel; eine aus der Umgebung nennt die Variable. Das Schema gibt die Host-Form als Pattern auf registries[].host an und keine auf default_registry, dessen Wert der Name eines beliebigen Eintrags sein darf — ein Editor, der nur das Schema liest, markiert also einen falsch geschriebenen Standard nicht, und erst das Laden der Konfiguration lehnt ihn ab.
Ein Host wird allein nach seiner Schreibweise beurteilt, ebenso ein Pfad. Ob der Name aufgelöst wird, ob dort eine Registry antwortet oder ob der Pfad auf ihr existiert, wird beim Laden der Konfiguration nicht geprüft.
Was was überschreibt
CLI flag > environment variable > configuration file > built-in defaultEin Flag ist das expliziteste Signal, das es gibt, und gewinnt uneingeschränkt. Eine Umgebungsvariable überschreibt die committete Datei, was es einer Pipeline ermöglicht, eine Einstellung zu ändern, ohne eine versionierte Datei zu bearbeiten. Eine nicht gesetzte Variable — oder eine auf eine leere Zeichenkette gesetzte — fällt auf die Ebene darunter durch, statt einen konfigurierten Wert zu leeren. Zwischen den beiden Dateien gewinnt die Datei Ihres Projekts gegenüber der globalen.
Ein Flag gewinnt dadurch, dass es eingegeben wurde, nicht durch den Wert, den es trägt, und bei einer Wahr-oder-falsch-Einstellung ist das der Unterschied zwischen einer nutzbaren obersten Ebene und gar keiner. --offline schaltet den Modus für einen Lauf ein; --offline=false schaltet ihn für einen Lauf aus, wo eine committete Datei oder eine exportierte Variable ihn eingeschaltet hat. Eine Ebene, die nur den Wert läse, könnte „aus“ nicht von „nicht erwähnt“ unterscheiden, sodass jeder Befehl so aussähe, als hätte er den Standardwert des Flags angefordert, und es gäbe überhaupt keine Möglichkeit, eine konfigurierte Einstellung aufzuheben.
Das ist das gesamte Modell für ein einzelnes Projekt auf einem einzelnen Rechner. Alles Folgende existiert für Projekte, die ihm entwachsen.
Über die zwei Dateien hinaus
Diese Mechanismen sind für größere Strukturen gebaut — ein Monorepo verwandter Projekte, eine Pipeline, die eigene Einstellungen beisteuert, ein geteilter Katalog, den mehrere Projekte erweitern. Greifen Sie zu einem davon, wenn Sie das Problem haben, das er löst.
Mehr als eine Konfigurationsdatei innerhalb eines Projekts
Jede .aggrega-config.yaml vom Projektstamm bis hinunter zu dem Verzeichnis, in dem der Befehl läuft, trägt bei, und eine nähere Datei überschreibt eine fernere. So kann ein Teilprojekt eine eigene Datei führen, die anpasst, was der Stamm deklariert hat, ohne es zu wiederholen.
Nur eine Datei mit einem workspace:-Block kennzeichnet einen Stamm. Eine Datei ohne ihn trägt dennoch ihre Einstellungen bei — sie macht ihr Verzeichnis lediglich nicht zu einem Projektstamm, was verhindert, dass die Einstellungsdatei eines Teilprojekts neu festlegt, wo das Projekt beginnt.
Die Übergabe von --workspace-root ändert auch dies, zusätzlich dazu, dass die Erkennung übersprungen wird: Die eigene Konfigurationsdatei des genannten Stamms ist die einzige gesammelte, daher tragen Dateien in Verzeichnissen darunter nicht bei. So bleibt die Konfiguration eines festgelegten Stamms gleich, wo immer der Befehl ausgeführt wird.
Jede auf diese Weise gesammelte Datei wird von innerhalb des Projekts gelesen. Eine, die ein symbolischer Link ist, der aus dem Projekt herausführt — oder die in einem über einen solchen Link erreichten Verzeichnis liegt —, wird nicht gelesen, und jeder Befehl, der die Konfiguration liest, hält bei ihr an und nennt den Link, statt das Projekt aus den verbleibenden Dateien zu konfigurieren; dasselbe gilt für die Datei einer Pipeline, siehe unten. Die wenigen Befehle, die sie nie lesen, etwa aggrega version und aggrega help, laufen mit einer Warnung, die den Link nennt. Der Language Server des Editors und die Werkzeuge eines Assistenten lesen die Konfiguration auf dieselbe Weise und starten dennoch auf einem solchen Projekt, damit es aufgelistet werden kann: Ihre Release- und Entitätsauflistungen antworten, gelesen ohne jede Konfiguration, und nennen die Datei unter den nicht gelesenen Links, während jede andere Anfrage, über die die Konfiguration entscheidet, bei ihr anhält und den Link nennt. Eine außerhalb des Projekts geführte Konfiguration wird gelesen, indem man sie als globale Datei nennt, wie Die globale Datei explizit benennen beschreibt. Siehe Die Workspace-Grenze.
Eine Liste erweitern statt sie zu ersetzen
Eine listenwertige Einstellung verhält sich wie jede andere Einstellung: Der Wert der näheren Datei ersetzt den der ferneren. Wenn Sie zu dem, was eine äußere Datei deklariert hat, etwas hinzufügen möchten, statt es neu anzugeben, verwenden Sie das Append-Gegenstück daneben:
| Listeneinstellung | ihr Append-Gegenstück |
|---|---|
workspace.catalog_dirs | catalog_dirs_append |
plugins.governance | governance_append |
plugins.linter | linter_append |
plugins.importer | importer_append |
plugins.providers | providers_append |
Einträge unter einem Gegenstück werden auf jeder Ebene an die aufgelöste Liste angehängt, statt sie zu verdecken, sodass ein Teilprojekt einen Linter zu dem hinzufügt, was der Stamm bereits deklariert hat:
# <project>/services/api/.aggrega-config.yamlplugins: linter_append: - uri: ./lint/api-rules.wasmWo eine Datei sowohl die Basisliste als auch ihr Gegenstück setzt, ist der Wert dieser Datei die Basisliste, gefolgt von den angehängten Einträgen.
Der workspace:-Block ist die Ausnahme davon, wo ein Gegenstück geschrieben werden kann. Eine Datei mit diesem Block kennzeichnet ihr eigenes Verzeichnis als Projektstamm, daher würde die Datei eines Teilprojekts, die workspace.catalog_dirs_append schriebe, ein eigenes Projekt beginnen, statt das umschließende zu ergänzen. Das Gegenstück für Katalogverzeichnisse wirkt zwischen Ihrer globalen Datei und der Stammdatei des Projekts zusammen.
Die Liste plugins.cli setzt sich von selbst über Dateien hinweg zusammen und hat kein Gegenstück: Eine in der globalen Datei deklarierte Befehlserweiterung registriert ihren Befehl in jedem Projekt, eine in einem Projekt deklarierte registriert ihn nur dort, und beide registrieren sich gemeinsam. Jeder Eintrag pinnt ein Plugin: den uri, den er auflöst, und den digest der Bytes, die aggrega plugin add cli verifiziert hat, geschrieben als sha256: gefolgt von 64 kleingeschriebenen Hexadezimalziffern. Ein Digest in einer anderen Schreibweise könnte niemals dem Digest entsprechen, zu dem die aufgelösten Bytes gehasht werden, daher wird er beim Laden der Datei abgelehnt, mit Nennung der Datei und des Eintrags.
Einem Release eigene Katalogverzeichnisse geben
Ein Projekt kann mehrere Katalogvarianten nebeneinander führen — eine pro Ziel, jede mit den Recipes, die dieselben Components für einen anderen Provider rendern — und jedes Release gegen eine davon bauen. Nennen Sie jedes Release unter workspace.releases und geben Sie ihm eigene catalog_dirs:
# <project>/.aggrega-config.yamlworkspace: releases: release-compose.yaml: catalog_dirs: - ./catalog-compose release-helm.yaml: catalog_dirs: - ./catalog-helmJeder Schlüssel ist eine Release-Datei, relativ zu der Konfigurationsdatei geschrieben, die sie nennt. Ein Schlüssel — wie build.authoring_release — darf ein außerhalb des Projekts geführtes Release nennen, und es hier zu nennen ist die Art, wie ein Projekt es erreicht: Ein Link innerhalb des Projekts, der dorthin führt, wird gelesen statt übergangen, wie Die Workspace-Grenze beschreibt. Die beiden Schlüssel darunter bedeuten dasselbe wie im workspace:-Block, beschränkt auf dieses eine Release:
catalog_dirsersetzt die Liste des Workspace für dieses Release. Die Suchreihenfolge, das danach gelesenecatalog-Verzeichnis und das, was eine leere Liste besagt, sind dieselben wie bei der eigenen Liste des Workspace.catalog_dirs_appendwird nach der Liste des Release gelesen. Ein Eintrag, der nurcatalog_dirs_appendschreibt, behält die Liste des Workspace bei und ergänzt sie.
Ein Release, das die Zuordnung nicht nennt, liest das eigene workspace.catalog_dirs des Workspace. Ein Release, das die Zuordnung nennt, liest seine eigenen Verzeichnisse, wie auch immer es gebaut wird — aggrega build oder aggrega pull in einem Terminal, der Editor über aggrega serve, ein Assistent über aggrega mcp —, sodass keiner davon ein Flag braucht, um seinen Katalog zu finden. Ein --catalog <dir> auf der Befehlszeile wird für diesen einen Aufruf weiterhin vor den Verzeichnissen des Release durchsucht. Und eine Suche, die unter einem von Ihnen verwendeten Namen keine Entität findet, nennt den Eintrag dieses Release als die Stelle, an der das Verzeichnis aufzuführen ist, das sie enthält.
Ein Eintrag, der eine nicht existierende Datei nennt, wird beim Laden der Konfiguration abgelehnt, mit Nennung des Eintrags und der Datei. Das Umbenennen eines Release stoppt daher jeden Befehl, bis der Eintrag mit umbenannt wird, statt das Release gegen die Liste des Workspace bauen zu lassen, ohne dass etwas darauf hinweist. Ein Verzeichnis, das ein Eintrag auflistet, muss ein Verzeichnis sein, wie es auch eines sein muss, das die Liste des Workspace nennt: Eines, das keines ist, wird von jedem Befehl abgelehnt, der den Katalog dieses Release liest, mit Nennung des Eintrags und seiner Zeile.
Was kein einzelnes Release betrifft, liest weiterhin die Liste des Workspace: ein Lint oder eine Validierung des gesamten Katalogs, das Nachschlagen einer Entität nach Namen, ein für sich inspiziertes Aggregate und die Auflistung der Entitäten des Workspace in einem Editor. AGGREGA_CATALOG_DIRS setzt die Liste des Workspace und erreicht keinen Eintrag hier, und eine Konfigurationsdatei, die Ihrer Pipeline gehört, liest die Zuordnung überhaupt nicht.
Eine Konfigurationsdatei, die Ihrer Pipeline gehört
Eine Datei namens .aggrega-config-append-ci.yaml darf neben der von Hand geschriebenen Datei in jedem Verzeichnis liegen, das der Durchlauf besucht. Sie ist eine separate Datei, damit eine automatisierte Pipeline sie besitzen und vollständig überschreiben kann, ohne je anzutasten, was eine Person geschrieben hat.
Sie ist rein additiv. Ihre Einträge für die fünf obigen Listeneinstellungen werden an die aufgelösten Listen angehängt; sie kann nichts entfernen und keinen Skalar überschreiben. Ein darin geschriebener Skalar- oder Map-Schlüssel hat keine additive Bedeutung, daher wird er ignoriert und in einer Warnung genannt, statt stillschweigend angewendet zu werden. Sie kennzeichnet auch niemals einen Projektstamm, daher fügt das Ablegen einer solchen Datei in einem Verzeichnis Anbindungen hinzu, ohne zu verschieben, wo das Projekt beginnt.
Wohin ein relativer Pfad zeigt
Ein relativer Dateisystempfad wird relativ zum Verzeichnis der Datei aufgelöst, die ihn deklariert hat — nicht relativ zum Projektstamm und nicht relativ zu dem Verzeichnis, aus dem Sie den Befehl ausgeführt haben. Diese Regel lohnt es, zweimal zu lesen, denn ein Pfad, der projektrelativ aussieht, wird anderswo aufgelöst, und der Build gelingt trotzdem — gegen Inhalte, die Sie nicht beabsichtigt haben.
Sie gilt für workspace.catalog_dirs, für die Release-Dateien, die als Schlüssel unter workspace.releases stehen, und die Verzeichnisse, die jeder Eintrag aufführt, für die lokalen Dateisystempfade an einer plugins.governance- oder plugins.linter-Anbindung — ein uri, der eine .wasm-Datei auf der Festplatte nennt, und jeder Eintrag unter dem with.sources dieser Anbindung — und für jeden Eintrag unter dem with.sources einer plugins.importer-Anbindung. In allen drei Listen ist ein uri ohne Doppelpunkt, der keine Registry nennt — importer/agent-flows ebenso wie ./lint/api-rules.wasm —, ein solcher Pfad, während ein uri, der ein Plugin über seine Identität nennt, die Version nach einem Doppelpunkt trägt, importer/agent-flows:1.2.0, und genau wie geschrieben belassen wird. Der uri einer Importer-Anbindung nennt den Importer, den sie anbindet, wie Welcher Importer eine Quelle in Entwürfe umwandelt beschreibt; ein Import liest kein Modul aus einem dort geschriebenen Pfad. Die Regel gilt auch für die Einträge unter den Append-Gegenstücken, und jeder davon verankert sich an seiner eigenen deklarierenden Datei statt an der Datei, bei der die Zusammenführung zufällig endet. Und sie gilt für mcp.tls.cert_file, mcp.tls.key_file und mcp.authorization.jwks_file, sodass eine Datei neben derjenigen, die sie nennt, gefunden wird, wo immer der Server gestartet wird.
Bei diesem Layout also:
myproject/├── .aggrega-config.yaml└── services/ ├── .aggrega-config.yaml └── catalog/und ./catalog in der Stamm-Datei geschrieben, nennt der Pfad myproject/catalog. In services/.aggrega-config.yaml geschrieben, nennt der identische Text myproject/services/catalog. Ein absoluter Pfad wird genau wie geschrieben belassen, ebenso eine Registry-Referenz wie oci://hub.aggrega.ai/plugins/helm:1.0.0.
Diese Einstellungen folgen dieser Regel bewusst nicht, weil sie keine deklarierende Datei haben, an der sie sich verankern könnten, oder weil jeder, der sie liest, sie anderswo auflöst:
artifact_cache_dirwird relativ zum Projektstamm interpretiert, wo immer der Befehl ausgeführt wird, sodass der Cache ein einziges Verzeichnis ist statt eines pro Aufrufort. Ein absoluter Wert wird beim Laden der Konfiguration abgelehnt.AGGREGA_CATALOG_DIRSstammt aus der Umgebung und hat überhaupt keine deklarierende Datei, geben Sie darin also absolute Pfade an.mcp.listenwird genau wie geschrieben übernommen, und das schließt den Dateisystempfad in seinerunix:<path>-Form ein. Dieselbe Adresse kommt auch ausaggrega mcp --listen, das keine deklarierende Datei hat, daher würde das Verankern allein der konfigurierten Schreibweise dazu führen, dass eine Zeichenkette je nach Herkunft zwei verschiedene Orte bezeichnet. Geben Sie dem Socket einen absoluten Pfad.
Eine Einstellung, deren Speicher geteilt ist
Fast jede Einstellung steuert etwas, das zu dem Projekt gehört, in dem Sie arbeiten — über welche Verzeichnisse es Katalog-Inhalte auflöst, welche Plugins seine Ziele rendern, wie streng seine Inhalte beurteilt werden, wie groß die In-Memory-Caches des Daemons werden dürfen. Ein Wert in der Datei eines Projekts steuert das Eigene dieses Projekts, und es gibt nichts, worauf zu achten wäre.
compiled_module_cache.max_bytes ist die eine Ausnahme, denn was es begrenzt, ist nicht projektbezogen. Kompilierter Plugin-Code wird in einem einzigen Verzeichnis abgelegt, das jedes Projekt auf Ihrem Rechner wiederverwendet, sodass ein bestimmtes Plugin einmal kompiliert wird statt einmal pro Projekt. Die Obergrenze selbst wird wie jede andere Einstellung aufgelöst — schreiben Sie sie in die Datei eines Projekts, und dieser Wert gewinnt für dieses Projekt —, aber der Speicher hat dennoch nur eine Größe, und die geltende Größe ist die des jüngsten Builds. Zwei Projekte, die ihn unterschiedlich begrenzen, wirken beide abwechselnd, und die niedrigere Obergrenze verwirft kompilierten Code, für den das andere Projekt bezahlt hat.
Legen Sie sie also in die globale Datei, wenn Sie eine einzige Antwort für alles wollen, was Sie bauen, und halten Sie sie über dem, was ein einzelner Build kompiliert. aggrega cache status meldet, was der Speicher derzeit enthält, und aggrega config show --origin sagt Ihnen, aus welcher Datei die Obergrenze, unter der Sie laufen, tatsächlich stammt.
Einstellungen für einen Server, den andere erreichen
aggrega mcp spricht das Model Context Protocol. Auf Ihrem eigenen Rechner startet ein Client ihn als Unterprozess und kommuniziert mit ihm über Standardeingabe und -ausgabe, was der Standard ist, und die einzigen Einstellungen, die diese Form liest, sind mcp.transport, auf diesem Standard belassen, und mcp.announce_tools. Der Rest des mcp-Blocks ist für die andere Form, die mcp.transport: http wählt: ein einzelner langlebiger Prozess auf einem Host, über HTTP erreicht von Aufrufern, die nicht an seiner Tastatur sitzen.
# <project>/.aggrega-config.yamlmcp: transport: http listen: 127.0.0.1:7777 authorization: issuer: https://login.example.com resource: https://mcp.example.com/mcp allowed_origins: - https://studio.example.com limits: max_concurrent_requests: 32 deny_reach: - registry announce_tools: - list-entities - get-schema - validate - build health: listen: 127.0.0.1:7778mcp.transport wählt den Transport. http startet einen Listener; stdio, der Standard, kommuniziert über Standardeingabe und -ausgabe, was ein Unterprozess-Client erwartet. Jeder andere Wert wird beim Laden dieser Datei abgelehnt. aggrega mcp --transport <stdio|http> tut dasselbe für einen einzelnen Aufruf und gewinnt gegenüber dem Schlüssel, so wie jedes Flag gegenüber jeder Datei gewinnt.
mcp.listen nennt, woran dieser Listener bindet, und wählt nichts. Geben Sie ihm eine host:port-Adresse oder einen unix:<path>-Socket; aggrega mcp --listen <address> gewinnt für einen einzelnen Aufruf dagegen. Ist http gewählt und kommt von keinem der beiden eine Adresse, wird der Start abgelehnt, bevor etwas bindet. Ist stdio gewählt, wird ein eingegebenes --listen abgelehnt, und eine Adresse, die nur dieser Schlüssel nennt, bleibt ungenutzt — der Server sagt dies in einer Zeile auf seinem Fehlerstrom und nennt diese Datei und mcp.transport: http. Ein Server, den andere erreichen, setzt also beide Schlüssel, wie oben, und ein Client, der aus einem von dieser Datei abgedeckten Verzeichnis gestartet wird, erreicht den Server weiterhin über seine eigenen Ströme. Ein unix:-Pfad wird wie geschrieben übernommen statt verankert — siehe Wohin ein relativer Pfad zeigt.
mcp.tls.cert_file und mcp.tls.key_file bringen TLS in den Prozess. Setzen Sie beide, und der Listener liefert HTTPS selbst aus. Lassen Sie beide weg, und er liefert Klartext aus, was nur über Loopback oder einen Unix-Socket akzeptiert wird — die Form, die Sie verwenden, wenn ein vorgeschalteter Proxy das Zertifikat hält und an den Prozess weiterleitet. Ein Klartext-Listener an jeder anderen Adresse wird abgelehnt, bevor etwas bindet, mit Nennung dieser beiden Schlüssel, ebenso wenn einer der beiden ohne den anderen gesetzt ist. Beide sind Dateisystempfade und folgen der obigen Regel: Ein relativer wird relativ zum Verzeichnis der Datei aufgelöst, die ihn deklariert hat, sodass ein neben dieser Datei committetes Zertifikat gefunden wird, wo immer der Server gestartet wird. Schreiben Sie sie absolut, wo das Zertifikat außerhalb des Projekts verwaltet wird.
mcp.authorization.issuer und mcp.authorization.resource geben an, wer die Tokens ausstellt, die Aufrufer vorlegen, und wie dieser Server als die Ressource heißt, für die sie ausgestellt werden. Beide sind erforderlich, sobald der http-Transport gewählt ist, und ohne sie wird ein Listener abgewiesen, bevor irgendetwas gebunden wird, denn jede Anfrage an den Endpunkt wird mit einer Bearer-Token-Challenge beantwortet, und eine Challenge, die kein Ziel nennt, ist eine, auf die ein Client nicht reagieren kann. Schreiben Sie vollständige Adressen, einschließlich Schema und Host: den Issuer genau so, wie dieser Autorisierungsserver seinen eigenen Bezeichner angibt, und die Ressource als die Adresse, die Ihre Aufrufer tatsächlich erreichen — den Host, den ein vorgeschalteter Proxy präsentiert, sofern es einen gibt, statt der Adresse, an die dieser Prozess bindet. Beide werden, ohne dass eine Anmeldeinformation verlangt wird, im OAuth-Metadatendokument der geschützten Ressource veröffentlicht, das der Listener bereitstellt; dort sucht ein Client nach, wo er ein Token erhält. Keiner der beiden enthält etwas Geheimes: Ein Token kommt mit der Anfrage, die es vorlegt, und wird nie in eine Konfigurationsdatei geschrieben. Der Issuer ist eine https-Adresse, es sei denn, der Autorisierungsserver läuft auf diesem Rechner — localhost, 127.0.0.1 oder ::1 —, und ein Listener, der einen unverschlüsselten http-Issuer auf einem anderen Host nennt, wird abgewiesen, bevor irgendetwas gebunden wird, gleichgültig, wie er seine Schlüssel und seine Aufrufer liest: Jeder Client wird zum Issuer geschickt, um sein Token zu erhalten, sodass über unverschlüsseltes http sein Autorisierungscode und sein Token ungeschützt über das Netzwerk gingen, und wo auch die Schlüssel von dort gelesen werden, könnte jeder auf diesem Weg sie austauschen.
mcp.authorization.jwks_file nennt eine Datei mit den Schlüsseln, gegen die Tokens geprüft werden, statt sie vom Autorisierungsserver zu lesen. Lassen Sie den Schlüssel weg, liest der Server die Metadaten dieses Servers an dessen Well-known-Adresse und folgt der dort veröffentlichten jwks_uri; so verfährt ein Workspace mit Netzwerkzugang. Für diese Schlüsseladresse gilt dieselbe Regel wie für den Issuer, ebenso für jede Adresse, auf die einer der beiden Lesevorgänge umgeleitet wird: Eine, die unverschlüsseltes http auf einem anderen Host ist, wird nie abgefragt, und ein Token, das diese Schlüssel benötigt, wird mit 503 beantwortet, bis der Autorisierungsserver seine Metadaten und Schlüssel über https veröffentlicht. Setzen Sie ihn, wird der Autorisierungsserver nie kontaktiert — das braucht ein Workspace, der offline: true deklariert, und ein solcher Workspace wird abgewiesen, bevor sein Listener bindet, sofern dieser Schlüssel keine Datei nennt. Er ist ein Pfad und folgt der obigen Regel: Ein relativer wird gegen das Verzeichnis der Datei aufgelöst, die ihn deklariert hat, sodass ein neben dieser Datei committeter Schlüsselsatz gefunden wird, wo auch immer der Server gestartet wird. Die Datei enthält öffentliche Prüfschlüssel, also das, was ein Autorisierungsserver veröffentlicht — nichts, was signiert, und nichts Geheimes.
mcp.allowed_origins wird nur herangezogen, wenn eine Anfrage einen Origin-Header trägt, was in der Praxis bedeutet, dass ein Browser sie gesendet hat. Listen Sie dort die Origins auf, die Sie bedienen; eine Anfrage, die einen nicht aufgeführten nennt, wird abgewiesen, und eine Anfrage ohne diesen Header wird trotzdem bedient. Ein Client, der kein Browser ist, sendet keinen solchen Header und braucht keinen Eintrag. Ein Eintrag wird exakt mit dem Header verglichen, schreiben Sie ihn also so, wie ein Browser ihn sendet: ein kleingeschriebenes Schema, ://, ein kleingeschriebener Host und : mit dem Port nur dort, wo der Port nicht der Standardport des Schemas ist — https://studio.example.com oder http://localhost:3000 für eine auf Ihrem eigenen Rechner bereitgestellte Seite —, ohne Pfad und ohne abschließendes /. Ein Eintrag in jeder anderen Form könnte nie übereinstimmen und wird beim Laden dieser Datei unter Nennung des Eintrags abgewiesen.
mcp.limits begrenzt, was ein einzelner Aufrufer anfordern kann — wie groß ein einzelner Anfrage-Body sein darf, wie viele Anfragen gleichzeitig laufen und wie viele ein Aufrufer in einer Minute senden darf. Alle drei sind immer in Kraft; keiner hat einen Wert, der ihn aufhebt. Der dritte, requests_per_minute, wird für jeden Aufrufer getrennt gezählt, sodass ein Aufrufer, der viel sendet, einen anderen nichts kostet.
mcp.authorization.trusted_proxy liest den Aufrufer aus einem vorgeschalteten Proxy, statt hier ein Token zu prüfen. Setzen Sie principal_header auf den Header, mit dem dieser Proxy angibt, wer der Aufrufer ist, und optional scopes_header auf einen, der die Scopes dieses Aufrufers trägt. Beide sind HTTP-Header-Namen wie X-Forwarded-User — Buchstaben, Ziffern, Bindestriche und die wenigen anderen Zeichen, die ein Header-Name enthalten darf, ohne Leerzeichen oder Doppelpunkt —, und ein Name in jeder anderen Form wird beim Laden dieser Datei unter Nennung des Schlüssels abgewiesen, weil keine Anfrage ihn tragen könnte. In diesem Modus wird überhaupt kein Token gelesen, und eine Anfrage ohne den Principal-Header wird abgewiesen. Da der Header dann die gesamte Anmeldeinformation ist, ist er nur dort vertrauenswürdig, wo nichts anderes ihn setzen kann: Der Prozess wird abgewiesen, bevor er bindet, sofern mcp.listen nicht Loopback oder ein Unix-Socket ist. Lassen Sie den Block weg, prüft dieser Server Tokens selbst, was der Standard ist; ein Block, dessen principal_header leer ist, wird abgewiesen, statt als dieser Standard gelesen zu werden.
mcp.deny_reach entzieht diesem Deployment eine Art von Reichweite. Jede Operation, die der Server ausführt, deklariert, wie weit ihre eigenen Wirkungen reichen — none für eine, die liest oder rendert und nichts zurücklässt, workspace für eine, die innerhalb des Workspace schreibt, den dieser Prozess bedient, registry für eine, die veröffentlicht, signiert oder zurückzieht, und machine für eine, die ändert, was alle Workspaces auf dem Host gemeinsam nutzen. Eine hier genannte Art entzieht jedes Tool, das sie erreicht: Das Tool fehlt in der Tool-Liste jedes Aufrufers, was auch immer dessen Token trägt, und ein Aufruf des Tools wird unter Nennung dieser Einstellung abgewiesen. Damit ist es die Grenze des Deployments statt die des Aufrufers, und keine Anmeldeinformation hebt sie auf — ein Server, der nur Lesezugriffe bedienen soll, listet hier die drei schreibenden Arten auf und kann dann selbst für einen Aufrufer nicht veröffentlichen, dessen Token jeden Scope trägt. Lassen Sie sie weg, was der Standard ist, bietet dieses Deployment alles, was die Scopes seiner Aufrufer zulassen. Ein Wert, der keiner der vier ist, wird beim Laden dieser Datei abgewiesen, statt übergangen zu werden. Nichts von der Art machine wird über HTTP angeboten, was auch immer hier steht, sodass ihre Nennung akzeptiert wird und nichts ändert; aggrega-mcp.md beschreibt die Arten und die Scopes, die sie zulassen.
mcp.announce_tools schränkt ein, was der Server ankündigt, und ist eine andere Grenze als der Schlüssel oben. Nennen Sie die Tools, die dieser Server ankündigt, so geschrieben, wie die Tool-Liste sie meldet, und genau diese werden angekündigt: Ein weggelassenes fehlt in der Tool-Liste jedes Aufrufers und wird, wenn es dennoch beim Namen aufgerufen wird, unter Nennung dieser Einstellung abgewiesen. Lassen Sie den Schlüssel weg — der Standard —, wird jedes Tool angekündigt, das der Server bietet; schreiben Sie eine leere Liste, wird keines angekündigt, sodass diese beiden Schreibweisen unterschiedliche Aussagen sind und kein Standard für Sie eingesetzt wird. Was ihn von deny_reach unterscheidet, ist, was jeder der beiden wegnimmt. deny_reach nimmt eine Fähigkeit weg: Die Operationen einer entzogenen Art werden hier überhaupt nicht angeboten, und keine Anmeldeinformation bringt eine zurück. announce_tools nimmt nur eine Ankündigung weg — die Tools, die er weglässt, sind Fähigkeiten, die der Server weiterhin hat —, und er antwortet auf einen Client, der begrenzt, wie viele Tools er registriert, manchmal über alle Server hinweg, mit denen er zugleich verbunden ist. Wo beide gesetzt sind, gewinnt der Entzug, sodass ein Tool einer entzogenen Art fehlt, wie auch immer dieser Schlüssel es nennt. Ein Name, auf den kein Tool antwortet, hält den Server an, bevor er irgendetwas bedient, und listet die Tools auf, die er hat, statt Ihnen eine schmalere Oberfläche zu hinterlassen als die, die Sie verlangt haben. Anders als die übrigen Schlüssel hier, die den vom http-Transport gestarteten Listener konfigurieren, wird er gelesen, welchen Transport der Server auch spricht, weil der Client, für den eine Einschränkung existiert, meist derjenige ist, der den Prozess über seine eigene Standardein- und -ausgabe gestartet hat; aggrega-mcp.md beschreibt den Rest.
mcp.health.listen legt die Liveness- und Readiness-Prüfungen auf eine eigene Adresse. Geben Sie ihm eine Adresse in einer der beiden Formen von mcp.listen, und ein zweiter Listener beantwortet dort GET /healthz — 200 ab dem Moment, in dem der Prozess läuft — und GET /readyz — 503, bis der Workspace aufgelöst und der Endpunkt gebunden ist, ab dann 200; das erlaubt einem Load Balancer, Datenverkehr zurückzuhalten, bis der Prozess tatsächlich einen Aufruf beantworten kann. Lassen Sie ihn weg, wird keine der beiden Prüfungen irgendwo beantwortet. Sie werden nie auf der Adresse beantwortet, die mcp.listen nennt; diese gibt ihnen das 404, das sie jedem Pfad gibt, den sie nicht bedient: Eine Probe dort wäre ein nicht authentifiziertes Auslesen eines Listeners, der alles andere abweist. Anders als mcp.listen ist diese Adresse nicht eingeschränkt, und keine Adresse wird für sie abgewiesen — richten Sie sie auf Loopback oder einen Unix-Socket, was ein Supervisor neben diesem Prozess erreicht, und beachten Sie, dass alles, was die gewählte Adresse erreichen kann, diese beiden Antworten lesen kann.
schema/other/aggrega-config.md führt jeden dieser Schlüssel zusammen mit seinem Standardwert auf, sofern er einen hat.
Die anderen Arten, wie ein Projektstamm erkannt wird
--workspace-root <path> oder sein Gegenstück AGGREGA_WORKSPACE_ROOT nennt den Stamm direkt und überspringt die Erkennung. Der genannte Ordner muss existieren: Ein Pfad, der nichts oder eine Datei nennt, wird abgewiesen, bevor der Befehl irgendetwas anderes tut, und die Abweisung nennt, welcher der beiden den Wert geliefert hat, und zitiert ihn so, wie er angegeben wurde. Andernfalls wandert die Erkennung vom Arbeitsverzeichnis aufwärts, und die Arten von Ankern werden gegeneinander gewichtet statt nach Nähe:
- Eine
.aggrega-config.yamlmit einemworkspace:-Block gewinnt ohne Weiteres, in welcher Tiefe sie auch liegt. Die Suche steigt weiter auf, um eine solche zu finden, auch nachdem sie eine Markierung der unten genannten Art passiert hat, sodass ein explizit markierter Stamm weiter oben stets eine zufällige Markierung darunter schlägt. - Andernfalls verankert die nächstgelegene dieser Markierungen den Stamm, und innerhalb eines Verzeichnisses gilt diese Reihenfolge: ein
.aggrega/-Verzeichnis, dann eineaggregate*.yaml, dann einerelease*.yaml, dann einemanifest*.yaml. - Schlägt alles fehl, wird das Arbeitsverzeichnis verwendet – Befehle laufen, statt den Start zu verweigern. Ein Befehl, dessen Ergebnis vom Workspace abhängt – einer, der die Dokumente des Workspace liest oder schreibt, seinen Artefakt-Cache liest oder füllt oder ihn bereitstellt –, warnt einmal auf der Standardfehlerausgabe:
warning: <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace. Ein Befehl, dessen Ergebnis nicht davon abhängt, welcher Ordner die Wurzel ist, gibt nichts aus, auch wenn er die Konfiguration liest: darunteraggrega version,aggrega config show,aggrega plugin list,aggrega registry list,aggrega explainundaggrega login.aggrega config capture, dessen Aufgabe es ist, die eigene Konfigurationsdatei des Workspace zu schreiben, schreibt in einem solchen Ordner nichts und endet mit einem Fehler, der das besagt.
In einem solchen Ordner wird nichts in einen Artefakt-Cache geschrieben. Ein .aggrega/-Verzeichnis ist selbst eine der obigen Markierungen, sodass ein dort geschriebener Cache den Ordner zu einem Workspace machen würde, nur weil darin einmal etwas abgerufen wurde. Ein Befehl, dessen Arbeit den Cache füllt — aggrega pull, ein Build, der zuerst seine Abhängigkeiten auflöst, aggrega registry update, das Hinzufügen eines Befehlserweiterungs-Plugins aus einer Registry —, wird abgewiesen, bevor er irgendetwas abruft, wobei der Ordner und die zwei Möglichkeiten genannt werden: den Workspace mit --workspace-root oder AGGREGA_WORKSPACE_ROOT benennen oder dem Ordner eine .aggrega-config.yaml mit einem workspace:-Block geben. aggrega pin sowie aggrega push eines Recipe oder FeatureRecipe, das an die Pins gebunden ist, die das entity.lock daneben verzeichnet, füllen den Cache nur mit den entfernten Quellen, die die Entität vollständig ausschreibt und die das Pinnen einer Entität oder der Vergleich ihres Pins abruft: Sie werden auf dieselbe Weise abgewiesen, wo sie eine solche Quelle abrufen würden, bevor sie sie abrufen. Eine Entität ohne eine solche Quelle — gar keine Quelle, eine lokale oder eine, deren Koordinaten jedes Release ausfüllt — wird dort wie überall sonst gepinnt oder veröffentlicht. Ein Build dort wird nicht abgewiesen, aber eine externe Eingabe, die seine Lockdatei pinnt und die der Cache nicht mehr enthält, wird zur Reparatur nicht erneut abgerufen: Dem Rendering wird anstelle dieser Eingabe derselbe Satz mitgeteilt, so wie ihm der der Offline-Haltung mitgeteilt wird, und es meldet ihn. Wo artifact_cache_dir den Cache ablegt, ändert hier nichts, weil das Verzeichnis an den jeweils gefundenen Stamm angehängt wird. Befehle, die nur lesen, antworten weiterhin.
Dieser letzte Rückfall hat eine Ausnahme. Wenn nichts den Stamm benannt hat und das Arbeitsverzeichnis nichts verankert, ermittelt ein Befehl zu einem Release oder einem Entitätsdokument, der diese Datei mit einem absoluten Pfad nennt, den Stamm erneut, indem er vom Ordner der Datei aufwärts wandert, und verwendet, was er findet: den Workspace, zu dem die Datei gehört, oder, wenn alles fehlschlägt, diesen Ordner. Die Datei ist diejenige, die --release bei aggrega build und aggrega pull nennt; das Release, das aggrega validate, aggrega lint und aggrega inspect übergeben wird, oder andernfalls die ihnen übergebene Datei; und das Dokument, das aggrega pin, aggrega push und aggrega edit-document übergeben wird. So liest das Release eines Projekts, das von außerhalb des Projekts gebaut wird, die eigene Konfiguration des Projekts, wie es das tut, wenn der Befehl darin läuft, und die Konfigurationswarnungen, die der Befehl ausgibt, sind die dieses Workspace. Wo auch der eigene Ordner der Datei nichts verankert, ist dieser Ordner derjenige, den der Hinweis des Befehls nennt, und derjenige, in den kein Cache geschrieben wird. Ein relativer Pfad wird gegen das Verzeichnis gelesen, in dem Sie den Befehl ausführen, und ändert nichts, und ein benannter Stamm oder ein Arbeitsverzeichnis, das selbst in einem Workspace liegt, wird unverändert verwendet. Der Assistenten-Server wendet dieselbe Regel auf einen Aufruf an, der sein Release oder Dokument mit einem absoluten Pfad nennt.
Den Stamm mit einem workspace:-Block zu markieren ist die explizite Wahl und die vorzuziehende; die Datei- und Verzeichnismarkierungen ermöglichen es, ein Projekt, das keinen deklariert hat, dennoch zu bauen.
Die globale Datei explizit benennen
Die globale Ebene wird in dieser Reihenfolge aufgelöst:
--config <path>, die Form für einen einzelnen Aufruf.- Die Umgebungsvariable
AGGREGA_CONFIG. - Der Standardort: unter Windows
aggrega\config.yamlin dem Verzeichnis, das die UmgebungsvariableAPPDATAnennt, und anderswoaggrega/config.yamlin dem Verzeichnis, dasXDG_CONFIG_HOMEnennt, mit~/.config/aggrega/config.yamlals Rückfall.
Die ersten beiden nennen eine explizite Datei, sodass ein nicht existierender Pfad ein deutlicher Fehler ist statt eines stillen Rückfalls — Sie haben eine bestimmte Datei verlangt. Ein Befehl, der seine Konfiguration liest, bricht mit einem Satz ab, der mit dem Pfad endet, damit Sie ihn kopieren können. aggrega config init ist die Ausnahme, weil das Anlegen dieser Datei sein Zweck ist: Er legt die genannte Datei an und meldet dies. Der Standardort wird geladen, wenn die Datei vorhanden ist, und stillschweigend übergangen, wenn nicht. Welche Datei auch aufgelöst wird, die Dateien Ihres Projekts legen sich weiterhin darüber.
Wenn keine dieser Angaben aufgelöst wird — keine Datei genannt ist und die Variablen, aus denen der Standardort gelesen wird, nicht gesetzt sind —, bricht ein Befehl, der die globale Datei schreibt, ab und nennt, was zu setzen ist. Umgebungsvariablen führt pro Plattform die Variablen auf, aus denen jeder Ort gelesen wird.
Diese Wahl bestimmt auch, wohin ein konfigurationsschreibender Befehl schreibt. Ein mit --config <path> ausgeführter Befehl liest seine Konfiguration aus dieser Datei und wendet seine Änderung auf dieselbe Datei an, sodass das, was ein Befehl schreibt, das ist, was der nächste zurückliest.
In welche der beiden Dateien ein Befehl standardmäßig schreibt, ergibt sich aus der Art der Einstellung: rechnerweite Werkzeuge wie eine Registry gehen in die globale Datei, während am Build beteiligte Einstellungen wie eine Provider-Bindung oder eine Socket-Anbindung in die committete Datei des Projekts gehen, damit sie mit dem Projekt mitwandern. Übergeben Sie --global oder --workspace, um dies zu übersteuern, und der Befehl gibt die Datei aus, in die er geschrieben hat.
Siehe auch
- aggrega-config.md — die
aggrega config-Befehle, die Konfiguration anlegen, untersuchen und einfrieren. - environment-variables.md — jede Variable mit dem Präfix
AGGREGA_und wo Geheimnisse übergeben werden. - global-flags.md —
--config,--workspace-rootund die anderen Flags, die jeder Unterbefehl akzeptiert. - schema/other/aggrega-config.md — jeder Konfigurationsschlüssel, sein Typ und sein Standardwert.
- aggrega-cache.md — was
artifact_cache_dirtatsächlich enthält. - workspace-boundary.md — welche Pfade innerhalb des Workspace bleiben und wie die Verzeichnisse und Dateien, die diese Konfiguration nennt, über ihn hinausreichen.
- aggrega-mcp.md — der Server, den der
mcp-Block konfiguriert.