Configuration
D’où aggrega lit ses paramètres, et dans quel fichier placer un paramètre.
Le cas simple
Deux fichiers, et la plupart des projets n’ont besoin de rien d’autre.
Un fichier dans votre projet, nommé .aggrega-config.yaml, placé à la racine du projet. Il décrit comment ce projet est construit : quels répertoires contiennent le contenu de catalogue embarqué dans le projet, quels plugins effectuent le rendu de quelles cibles, quelles règles de lint sont assouplies, où va le cache local. Il est commité, de sorte qu’un coéquipier qui clone le projet le construit de la même manière.
Son bloc workspace: est ce qui marque le répertoire comme racine du projet :
# <project>/.aggrega-config.yamlworkspace: catalog_dirs: - ./catalogauto_pull: trueLe bloc ne contient que les répertoires de catalogue qui définissent la racine ; tout autre paramètre se trouve au niveau supérieur, à côté de lui. Un projet qui n’embarque aucun contenu de catalogue écrit tout de même le bloc, vide — workspace: {} — car c’est la présence du bloc qui sert de marqueur.
Un fichier global sur votre machine, à ~/.config/aggrega/config.yaml — sous Windows, à aggrega\config.yaml dans le répertoire que désigne la variable d’environnement APPDATA. Chaque workspace de cette machine est résolu à travers lui, et il contient les paramètres qui appartiennent à la machine plutôt qu’à un projet en particulier — les registres depuis lesquels vous effectuez des pulls et la politique de confiance des signatures de chacun, la taille que peut atteindre le stockage des modules compilés, et tout plugin d’extension de commande que vous avez installé. Ceux-ci sont les mêmes où que vous travailliez, et c’est tout l’intérêt de les déclarer une seule fois. Il est chargé automatiquement lorsqu’il est présent, et rien ne casse lorsqu’il est absent.
registries: - host: hub.aggrega.ai signing: required: trueaggrega config init écrit ce fichier global pour vous, en enregistrant un registre avec la politique de confiance des signatures qu’il annonce, et indique où se trouve le fichier sur votre machine et où sont conservés les caches à l’échelle de la machine. aggrega config show affiche ce qui s’applique en ce moment, et aggrega config show --origin indique quel fichier — ou quelle variable d’environnement — a déterminé chaque paramètre.
Les secrets ne sont pas de la configuration. Un mot de passe de registre et un jeton d’identité de signature ne sont jamais des champs de l’un ou l’autre fichier ; ils sont fournis par variable d’environnement ou par flag au moment où ils sont nécessaires. Voir environment-variables.md.
D’où les entités locales sont lues
Un projet qui conserve son propre contenu de catalogue — un Component, une Feature, une Recipe, l’un des types de bibliothèque — dispose de deux façons d’indiquer où se trouve ce contenu, et la première ne nécessite aucune configuration.
Un répertoire catalog à la racine du projet est lu, que quelque chose le nomme ou non. Placez une entité sous <project>/catalog/ et chaque commande qui charge un catalogue la lit, y compris dans un projet dont le bloc workspace: est vide. Un répertoire de catalogue est lu récursivement, la façon dont vous y organisez les sous-répertoires vous appartient donc.
Les répertoires listés sous workspace.catalog_dirs sont lus également, et ils sont lus en premier. La liste est une pile de recherche ordonnée : le premier répertoire qui déclare une identité la possède, et la même identité dans un répertoire ultérieur est masquée. catalog est lu après tout ce qui est listé — sauf si un répertoire listé le contient déjà, auquel cas il est lu comme faisant partie de ce répertoire — de sorte que lister un répertoire s’ajoute à ce que vous aviez au lieu de le remplacer. Un --catalog <dir> répétable sur la ligne de commande est lu avant les deux, et un chemin relatif donné à cet endroit est résolu par rapport au répertoire depuis lequel vous avez lancé la commande, puisqu’aucun fichier de configuration ne l’a déclaré. Un répertoire nommé plus d’une fois — sur la ligne de commande et dans la liste, ou deux fois dans la liste — est lu une seule fois, à l’endroit où il a été nommé en premier, de sorte que rien de ce qu’il contient n’est signalé comme masqué par lui-même : un masquage, ce sont toujours deux fichiers différents qui déclarent une même identité. Deux graphies d’un même répertoire, un chemin vers lui passant par un lien et — sur un système de fichiers qui ignore la casse — une graphie dans une autre casse désignent tous ce seul répertoire. Un répertoire situé dans un autre répertoire listé est tout de même lu comme une entrée à part entière. Un projet qui conserve une variante de catalogue par Release peut plutôt donner à chaque Release sa propre liste — voir Donner à une Release ses propres répertoires de catalogue.
Lister un répertoire est la façon dont un projet lit des entités conservées en dehors de lui. Un répertoire listé peut se trouver n’importe où — un checkout voisin, un répertoire partagé avec d’autres projets — et il est lu là où il se trouve, même lorsqu’il est lui-même un lien symbolique. Rien d’autre ne va aussi loin : un lien à l’intérieur du projet qui mène ailleurs n’est pas suivi, et un document qui nomme un fichier extérieur au projet par un chemin est refusé, de sorte qu’une entité conservée ailleurs s’atteint en listant le répertoire qui la contient et en nommant l’entité par son nom. Un répertoire listé extérieur au projet est une racine à part entière, donc un lien situé en dessous qui en sort n’est pas lu non plus. La frontière du workspace énonce la règle complète.
Un répertoire listé doit être un répertoire. Un chemin listé où rien n’existe, ou où se trouve un fichier ou un lien qui ne mène nulle part, est refusé avant toute lecture ou écriture par chaque commande qui lit le catalogue — un pull, un build, une validation, une inspection, un lint, et les mêmes opérations pilotées depuis l’éditeur via aggrega serve ou depuis un assistant via aggrega mcp —, de sorte qu’un build ne s’exécute jamais sur moins de catalogues que vous n’en avez listé. Le refus nomme l’entrée telle qu’elle est écrite, le chemin vers lequel elle s’est résolue, le fichier de configuration et la ligne qui la listent, et la liste dans laquelle elle se trouve :
<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 invalidCréez le répertoire, ou supprimez l’entrée : une copie d’un projet prise sans un checkout voisin qu’il liste supprime cette entrée, et résout depuis un registre ce que le checkout aurait fourni. Il en va de même pour un répertoire que liste l’entrée propre d’une Release, pour un répertoire qu’ajoute un fichier de configuration appartenant à votre pipeline ou le fichier global, et pour un répertoire que porte AGGREGA_CATALOG_DIRS, que le refus nomme à la place d’un fichier. La configuration elle-même se charge toujours, de sorte qu’une commande qui ne lit aucun catalogue s’exécute toujours. Un répertoire --catalog qui n’existe pas a été saisi pour une seule commande, et aggrega build le refuse en nommant le répertoire. Un répertoire listé qui existe et ne peut pas être lu est refusé par les commandes qui chargent le catalogue entier, qui le nomment.
Écrire la liste vide indique que ce projet n’a aucun catalogue local, et c’est la seule graphie qui empêche aussi la lecture de catalog :
# <project>/.aggrega-config.yamlworkspace: catalog_dirs: []Omettre la clé est une autre déclaration : une liste omise est le cas ordinaire, et catalog est toujours lu.
Un build, un pull, une validation ou un aggrega inspect qui ne trouve aucune entité sous un nom que vous avez utilisé indique d’où ce projet lit les entités locales et ce qu’il faut changer pour que celle que vous avez nommée soit lue. Il ne dit rien de tel là où vous avez écrit la liste vide — ne lire aucun catalogue local est ce que vous y avez déclaré, et suggérer de le changer reviendrait à vous contredire. Il ne le dit pas non plus là où le document qui déclare ce nom a été lu et refusé : ce document se trouve déjà là où le catalogue lit, le rapport nomme donc plutôt ce que le document enfreint, la ligne et la contrainte, et le déplacer ne corrigerait rien. Un document trop mal formé pour que le nom qu’il déclare puisse même être lu ne peut pas être rapproché du nom que vous avez utilisé, l’explication est donc tout de même donnée — et là où ce document déclare une apiVersion Aggrega, un build, un pull ou une validation d’une Release le nomme à côté de l’explication, avec la raison donnée par le parseur lui-même, puisqu’il peut s’agir du fichier à ouvrir. Un échec qui a trouvé l’entité et n’a pas pu l’accepter — un registre qui sert désormais d’autres octets sous une version que votre lockfile épingle, un fichier que l’entité transporte et qui ne peut pas être lu — n’est pas non plus une entité manquante, et il signale seulement son propre remède.
Si un pull ou un push épingle une entité
Une Recipe ou une FeatureRecipe porte les épinglages des entrées qu’elle lit — un source: distant écrit en entier, un fichier qu’une entrée artifacts importe, les fichiers d’un source: à côté d’elle — dans l’entity.lock à côté d’elle, et les enregistrer est l’étape de l’auteur de l’entité, aggrega pin. Par défaut, ni pull ni push n’exécute cette étape : un pull s’arrête sur une entité que son lock n’épingle pas, et un push refuse de la publier. Deux clés, une par commande, font de son exécution le comportement par défaut de cette commande :
# <project>/.aggrega-config.yamlworkspace: {}pin_sources_at_pull: truepin_sources_at_push: trueChaque clé régit sa propre commande et rien d’autre, et le --pin-sources de chaque commande remplace sa propre clé dans les deux sens — --pin-sources=false désactive l’étape pour une exécution dans un projet configuré pour épingler. Un build qui remplit son propre lockfile est un pull et suit pin_sources_at_pull. Ces clés ont leur place dans le fichier du projet plutôt que dans le fichier global : savoir si les pulls d’un projet enregistrent des épinglages relève de la politique de ce projet, et un coéquipier qui le clone devrait obtenir la même réponse. pin_sources_at_pull est aussi la façon dont un projet qui consomme le catalogue non épinglé de quelqu’un d’autre enregistre ces épinglages une seule fois au lieu de s’arrêter à chaque pull.
Quel plugin effectue le rendu d’une capability
Une Recipe nomme la capability à travers laquelle elle effectue son rendu — capability: helm — et un plugin qui sert cette capability en effectue le rendu. Là où exactement un plugin sert une capability, rien n’a besoin d’être configuré. Là où plusieurs la servent, une entrée plugins.providers indique lequel, par l’identité du plugin :
# <project>/.aggrega-config.yamlworkspace: {}plugins: providers: - capability: helm uri: provider/helmUn pull résout l’entrée et enregistre le plugin qu’il a choisi dans le lockfile de la Release, et un build effectue le rendu à travers ce que le lockfile enregistre, de sorte qu’une modification ici prend effet au pull suivant.
Le champ uri nomme le plugin par son identité, provider/<name>, jamais par l’endroit où il est publié. aggrega plugin add provider <query> --capability <capability> écrit l’entrée sous cette forme, sans version : l’entrée choisit quel plugin sert la capacité, la version est celle qu’épingle la Recipe ou, à défaut, la plus élevée disponible, et le lockfile enregistre celle que le pull a choisie. Un plugin que le compilateur embarque est servi à la version du compilateur lui-même, de sorte qu’une version écrite sur une entrée pour l’un d’eux ne se résout que si c’est cette version. Une entrée dont l’uri est un emplacement de registre — oci://hub.aggrega.ai/plugin/provider/helm — ne nomme l’identité d’aucun plugin, et elle est refusée au chargement du fichier, en nommant l’entrée et la forme à écrire.
Les entrées sont écrites une fois pour tout le projet, alors qu’un build porte sur une seule Release, de sorte qu’une entrée pour une capability que cette Release ne demande jamais est légale — une autre Release du projet la lit — et n’est signalée d’aucune façon. Ce que chaque build et chaque aggrega validate --release vérifient, c’est chaque entrée, qu’une Recipe demande ou non sa capability, selon ce que l’entrée nomme :
- Une entrée qui nomme un plugin dont le plugin ne sert pas sa capability arrête le build et fait échouer la validation. Un pull résout chaque entrée qui nomme un plugin, et refuse celle qu’il ne peut pas résoudre ; une fois qu’une entrée est passée par un pull, le build détient donc son plugin et sait ce qu’il sert ; une entrée qui nomme un plugin que le build ne détient pas encore est jugée une fois qu’un pull l’a récupéré. Le message nomme l’entrée, le plugin, ce que ce plugin sert réellement, et une graphie à une modification près lorsqu’il en existe une — la forme que prend une faute de frappe comme
hlempourhelm. - Une entrée qui ne nomme qu’une capability qu’aucun plugin lu par le build ne sert est un avertissement, et le build se poursuit. Le plugin qui la sert peut n’être lu que par une autre Release, que ce build ne peut pas voir, et une entrée qui ne nomme aucun plugin ne sélectionne rien que la résolution de la capability ne sélectionnerait sans elle.
Une capability ne contient jamais de deux-points ici, et une qui en contient est refusée au chargement du fichier. Le capability: d’une Recipe est lu comme la capability jusqu’à son dernier deux-points, suivie d’un épinglage de version, de sorte qu’une entrée de clé helm:1.0.0 ne pourrait jamais être trouvée. Épinglez plutôt la version sur le plugin — uri: provider/helm:1.0.0 — ou dans la Recipe.
Quel importeur transforme une source en brouillons
aggrega import confie une source à l’importeur qui annonce le format de la source — un importeur de votre catalogue ou l’un des importeurs de base du compilateur, import:langflow pour un flux Langflow. Là où exactement un importeur l’annonce, rien n’a besoin d’être configuré. Une entrée plugins.importer rattache un importeur en le nommant dans son uri, par son identité et sa version, et lui transmet ce qu’elle porte sous with :
# <project>/.aggrega-config.yamlworkspace: {}plugins: importer: - uri: importer/agent-flows:1.2.0 with: settings: target_namespace: paymentsaggrega plugin add importer écrit l’uri exactement sous cette forme. La version est exacte — :1.2.0 — ou une plage — :^1.2.0 pour la version la plus élevée égale ou supérieure à celle-ci au sein de la même version majeure. Écrivez l’une ou l’autre : dans cette liste, un uri sans deux-points est lu comme un chemin du système de fichiers, comme le décrit Où pointe un chemin relatif, et ne nomme aucun importeur.
Ce que fait une entrée dépend de ce que l’importeur qu’elle nomme annonce ou non le format qu’un import demande :
- Il l’annonce : cet importeur est celui qui s’exécute, à la version que nomme l’
uri, quel que soit le nombre d’autres importeurs du catalogue qui annoncent aussi le format, et il reçoit leswith.sourcesetwith.settingsde l’entrée. Une entrée est la façon dont un workspace dont le catalogue fédère les importeurs de deux éditeurs pour un même format indique lequel il utilise. - Il ne l’annonce pas — elle nomme un importeur d’un autre format, un plugin d’un autre type, ou rien que votre catalogue contienne ou que le compilateur embarque : l’entrée ne joue aucun rôle dans cet import. Elle ne choisit rien, et son
withn’est transmis à aucun importeur. Les paramètres d’une entrée n’atteignent que l’importeur qu’elle nomme, de sorte qu’un workspace qui rattache un importeur par format configure chacun sans que les paramètres de l’un atteignent l’autre.
Là où plusieurs importeurs annoncent le format et qu’aucun d’eux n’est rattaché seul — aucun ne l’est, ou des entrées en nomment deux — l’import est refusé, en nommant les importeurs entre lesquels il n’a pas pu choisir. Une entrée qui nomme un importeur annonçant le format, à une version qu’aucune de ses versions présentes dans le catalogue ne satisfait — une version exacte que le catalogue ne contient pas, ou une plage dans laquelle aucune de ses versions ne tombe — est refusée elle aussi, en nommant la version, plutôt que d’exécuter une autre version à sa place ; une version qui n’en est pas une du tout, comme :latest, est refusée comme mal formée. Une entité Plugin de l’un des importeurs core du compilateur sans module à côté d’elle dans son dossier de catalogue n’est pas candidate : à la version propre du compilateur, c’est l’importeur core qui s’exécute à sa place, et à toute autre version l’entité ne reste candidate que là où une entrée nomme exactement cette version ou là où aucun importeur de son nom capable de s’exécuter n’annonce le format, comme le décrit Lequel s’exécute à côté de vos propres importateurs.
Chaque importeur est rattaché par une seule entrée. Deux entrées qui nomment un même importeur — la même identité, à une version ou à deux — sont refusées au chargement de la configuration, quelle que soit la commande qui la lit, en nommant les deux entrées et les fichiers dans lesquels elles ont été écrites. La règle s’étend à chaque fichier qui contribue à la liste : une entrée dans le fichier global, une dans le fichier d’un projet, une sous importer_append et une dans le .aggrega-config-append-ci.yaml d’un pipeline comptent toutes, de sorte que faire passer un importeur à une nouvelle version signifie changer la version sur son unique entrée. aggrega plugin add importer fait exactement cela lorsque la liste plugins.importer du fichier qu’il écrit nomme déjà l’importeur : il fait passer cette entrée à la version qu’il a résolue, en conservant la place de l’entrée et son with, au lieu d’en ajouter une seconde. Il ne lit aucune autre liste, de sorte qu’un importeur rattaché sous importer_append, ou dans le .aggrega-config-append-ci.yaml d’un pipeline, est rattaché une seconde fois par la commande et la paire est refusée au chargement de la configuration ; changez la version d’une telle entrée là où elle est écrite. Une entrée dont l’uri est un chemin du système de fichiers ne nomme aucun importeur et n’est pas comparée, et les listes plugins.governance et plugins.linter ne sont pas soumises à la règle : un plugin peut y être rattaché plus d’une fois, chaque fois avec son propre with.
Les parseurs à travers lesquels un import lit n’ont besoin d’aucune entrée. Un importeur lit sa source — et un import qui ne nomme aucun format la reconnaît — à travers un parseur pour la syntaxe de la source : celui que votre catalogue sert pour cette syntaxe et, pour une syntaxe pour laquelle votre catalogue ne sert aucun parseur, celui que le compilateur embarque lui-même, JSON parmi eux. Ainsi, un workspace dont le catalogue ne contient aucun parseur importe un flux Langflow ou Flowise sans rien configurer. Aucune liste ne rattache un parseur : un parseur que votre catalogue sert pour une syntaxe est celui qui est utilisé, et deux parseurs de noms différents servant une même syntaxe sont refusés, comme le décrit A parse or import format is advertised by more than one plugin (Un format d’analyse ou d’import est annoncé par plus d’un plugin).
Partir de rien
Un aggrega fraîchement installé n’a aucun des deux fichiers, et c’est un état fonctionnel plutôt qu’un état cassé : chaque paramètre se rabat sur sa valeur par défaut intégrée et les commandes s’exécutent. Ce qui manque, c’est un registre depuis lequel récupérer le contenu de catalogue, avec la politique de confiance qui indique quelles signatures accepter — ce qui est exactement ce qu’écrit aggrega config init.
Vous n’avez pas besoin de le savoir à l’avance. Une commande qui lit sa configuration et ne trouve de fichier nulle part le signale une fois, sur la sortie d’erreur standard, et nomme aggrega config init comme moyen d’en créer un. C’est un conseil plutôt qu’un échec : la sortie standard n’est pas touchée, rien ne vous est demandé, et le code de sortie est celui que la commande aurait de toute façon renvoyé. Il n’est écrit que lorsque la sortie d’erreur standard est un terminal, de sorte qu’il vous atteint au clavier et ne s’accumule jamais dans le journal d’un pipeline. Dès que l’un des deux fichiers existe — celui de votre projet ou le fichier global — il cesse d’apparaître.
Pour initialiser le fichier global avec le hub officiel et la politique de confiance que ce hub annonce :
aggrega config initPassez --registry <host> pour en initialiser un autre, --workspace pour écrire l’entrée dans le fichier de ce projet au lieu du fichier global, et --dry-run pour voir le contenu qui serait écrit sans rien créer. aggrega-config.md couvre la commande en entier.
Comment s’écrit un hôte de registre
Chaque registries[].host nomme un hôte de registre. C’est aussi le cas de default_registry — éventuellement suivi d’un chemin de dépôt — sauf s’il nomme plutôt l’une de ces entrées (voir ci-dessous). Un hôte s’écrit comme l’hôte lui-même, dans l’unique graphie sous laquelle la politique de confiance du registre est conservée :
- un nom d’hôte en minuscules contenant un point, comme
registry.example.com; localhost, ou un nom simple suivi d’un port, commeregistry:5000;- une adresse IPv4 comme
127.0.0.1, ou une adresse IPv6 entre crochets comme[::1];
chacun avec un :port facultatif, et rien d’autre — pas de schéma, pas de chemin, pas d’identifiants, pas d’espace et pas de majuscules. Un nom simple sans port n’est pas un hôte de registre, car c’est la forme du premier segment du nom d’une entité de catalogue — le core de core/web-api — et les deux ne doivent jamais être pris l’un pour l’autre.
# <project>/.aggrega-config.yamlworkspace: {}default_registry: registry.example.comregistries: - host: registry.example.com signing: required: trueLa graphie fait partie de la politique. Une entrée registries s’applique à l’hôte que nomme son host:, et l’exigence de signature intégrée du hub officiel s’applique à hub.aggrega.ai, de sorte qu’un hôte écrit de toute autre façon atteindrait le bon registre et manquerait la politique écrite pour lui. Il est refusé au chargement de la configuration à la place, et le refus nomme la graphie à écrire : HUB.AGGREGA.AI et https://registry.example.com sont refusés en nommant hub.aggrega.ai et registry.example.com, tout comme registry.example.com/charts en tant que registries[].host, qui ne porte aucun chemin. Le port 443 est le port par défaut d’un hôte atteint via HTTPS, donc hub.aggrega.ai:443 est refusé de la même façon, en nommant hub.aggrega.ai. localhost et les autres adresses de loopback sont atteints via HTTP simple à la place, où 443 est un port ordinaire, donc localhost:443 est accepté tel qu’écrit. Un default_registry vide ne nomme aucun registre par défaut.
default_registry peut porter un chemin de dépôt. De nombreux registres conservent chaque dépôt sous un propriétaire ou un projet — ghcr.io/<owner>, <host>/<project> sur Harbor — et un registre par défaut sur l’un d’eux s’écrit comme l’hôte suivi de ce chemin :
# <project>/.aggrega-config.yamlworkspace: {}default_registry: ghcr.io/acmeregistries: - host: ghcr.io signing: required: trueLe chemin est l’endroit où les choses sont publiées et récupérées. Par ce défaut, aggrega push publie core/api-server en version 1.0.0 à ghcr.io/acme/component/core/api-server:1.0.0, et un pull qui résout core/api-server le récupère au même endroit, de sorte qu’une signature jointe lors de sa publication y est également trouvée. Le chemin est un chemin de dépôt selon la grammaire de distribution OCI : un ou plusieurs segments de lettres minuscules et de chiffres joints par /, qui peuvent être séparés à l’intérieur d’un segment par ., _, __ ou des tirets, sans tag, digest ni / final.
Le chemin ne fait jamais partie de la façon dont on fait confiance au registre. L’entrée registries dont la politique s’applique, l’identifiant que stocke aggrega login, l’exigence de signature et les identités de confiance sont tous trouvés par l’hôte seul, de sorte que l’entrée pour ghcr.io ci-dessus régit ghcr.io/acme et tout autre chemin sur cet hôte, et aucune graphie d’un chemin ne peut la contourner ; le host: d’une entrée ne porte lui-même aucun chemin. Un hôte écrit dans une autre graphie devant un chemin est refusé en nommant l’emplacement à écrire — GHCR.io/acme et https://ghcr.io/acme nomment ghcr.io/acme — et ce qui suit l’hôte, lorsque ce n’est pas un chemin de dépôt, est refusé en nommant l’hôte qu’il suit.
default_registry peut plutôt nommer une entrée. Écrit comme le name: d’une entrée sous registries, il représente le host: de cette entrée. La publication, le pull, la vérification des signatures et chaque paramètre de confiance par registre utilisent alors cet hôte, et aucun contenu n’est récupéré depuis un hôte écrit comme le nom :
# <project>/.aggrega-config.yamlworkspace: {}default_registry: localregistries: - name: local host: 127.0.0.1:5000Un nom est comparé avant une graphie d’hôte, comme le fait le flag --registry, de sorte qu’une valeur qui est le name: d’une entrée représente cette entrée même là où elle s’écrit aussi comme un hôte. Un nom que portent deux entrées est refusé comme ambigu, en nommant les deux hôtes. L’entrée peut se trouver dans l’un ou l’autre fichier — le default_registry d’un projet peut nommer une entrée que déclare le fichier global — car le nom est lu une seule fois, par rapport aux entrées en vigueur une fois que chaque fichier et l’environnement ont été lus. Une valeur qui n’est ni le nom d’une entrée ni un hôte de registre — seule ou suivie d’un chemin de dépôt — est refusée, et le refus indique que l’un ou l’autre la corrige. Un nom suivi d’un chemin, comme local/acme, est refusé lui aussi : un nom représente l’hôte de son entrée et non un emplacement sous celui-ci, le refus nomme donc plutôt les deux graphies à écrire — local, ou l’hôte de l’entrée suivi du chemin, 127.0.0.1:5000/acme. Supprimer une entrée avec aggrega registry remove laisse default_registry tel qu’il est écrit, de sorte qu’un défaut qui nommait l’entrée supprimée ne nomme plus rien ensuite et est refusé jusqu’à ce qu’il soit réécrit.
Chaque couche est soumise à la même graphie. Une valeur est refusée dans les mêmes termes, qu’elle provienne d’un fichier de configuration, de AGGREGA_DEFAULT_REGISTRY ou du flag --registry qui nomme la destination d’un aggrega push ou d’un aggrega push-artifact. Ce flag nomme un hôte, et la publication qu’il dirige aboutit à cet hôte sans chemin de dépôt : un chemin appartient à default_registry. aggrega registry add et aggrega config init --registry y soumettent aussi l’hôte qu’on leur donne ; ils acceptent également une référence à sa place, et enregistrent l’entrée sous l’hôte que nomme la référence. Un refus provenant d’un fichier nomme le fichier et la clé ; un refus provenant de l’environnement nomme la variable. Le schéma énonce la forme de l’hôte comme un pattern sur registries[].host et n’en énonce aucune sur default_registry, dont la valeur peut être le nom de n’importe quelle entrée — un éditeur qui ne lit que le schéma ne signale donc pas un défaut mal saisi, et c’est le chargement de la configuration qui le refuse.
Un hôte est jugé sur sa seule graphie, et un chemin aussi. Que le nom se résolve, qu’un registre réponde à cet endroit ou que le chemin y existe n’est pas vérifié au chargement de la configuration.
Qu’est-ce qui remplace quoi
CLI flag > environment variable > configuration file > built-in defaultUn flag est le signal le plus explicite qui soit et l’emporte sans condition. Une variable d’environnement remplace le fichier commité, ce qui permet à un pipeline de changer un paramètre sans modifier un fichier suivi. Une variable non définie — ou définie sur une chaîne vide — se rabat sur la couche inférieure au lieu d’effacer une valeur configurée. Entre les deux fichiers, le fichier de votre projet l’emporte sur le fichier global.
Un flag l’emporte parce qu’il a été saisi, et non par la valeur qu’il porte, et pour un paramètre vrai-ou-faux, c’est la différence entre une couche supérieure utilisable et aucune. --offline active le mode pour une exécution ; --offline=false le désactive pour une exécution là où un fichier commité ou une variable exportée l’a activé. Une couche qui ne lirait que la valeur ne pourrait pas distinguer « désactivé » de « non mentionné », de sorte que chaque commande semblerait avoir demandé la valeur par défaut du flag et il n’y aurait aucun moyen d’annuler un paramètre configuré.
C’est là tout le modèle pour un seul projet sur une seule machine. Tout ce qui suit existe pour les projets qui le dépassent.
Au-delà des deux fichiers
Ces mécanismes sont conçus pour des configurations plus vastes — un monorepo de projets liés, un pipeline qui apporte ses propres paramètres, un catalogue partagé que plusieurs projets étendent. Recourez à l’un d’eux lorsque vous avez le problème qu’il résout.
Plus d’un fichier de configuration dans un projet
Chaque .aggrega-config.yaml depuis la racine du projet jusqu’au répertoire dans lequel la commande s’exécute contribue, et un fichier plus proche remplace un fichier plus éloigné. Un sous-projet peut ainsi porter son propre fichier qui ajuste ce que la racine a déclaré, sans le répéter.
Seul un fichier portant un bloc workspace: marque une racine. Un fichier sans ce bloc apporte tout de même ses paramètres — il ne fait simplement pas de son répertoire une racine de projet, ce qui empêche le fichier de paramètres d’un sous-projet de redéfinir l’endroit où commence le projet.
Passer --workspace-root change aussi cela, en plus de sauter la découverte : le propre fichier de configuration de la racine nommée est le seul collecté, de sorte que les fichiers des répertoires situés en dessous ne contribuent pas. Cela garantit que la configuration d’une racine fixée reste la même, d’où que la commande soit lancée.
Chaque fichier collecté de cette façon est lu depuis l’intérieur du projet. Un fichier qui est un lien symbolique menant hors du projet — ou qui se trouve dans un répertoire atteint par un tel lien — n’est pas lu, et chaque commande qui lit la configuration s’arrête sur lui, en nommant le lien, au lieu de configurer le projet à partir des fichiers restants ; il en va de même pour le fichier d’un pipeline, ci-dessous. Les quelques commandes qui ne la lisent jamais, comme aggrega version et aggrega help, s’exécutent avec un avertissement qui nomme le lien. Le serveur de langage de l’éditeur et les outils d’un assistant lisent la configuration de la même façon, et démarrent tout de même sur un tel projet afin qu’il puisse être listé : leurs listes de Releases et d’entités répondent, lues sans rien de configuré, et nomment le fichier parmi les liens non lus, tandis que toute autre requête que la configuration détermine s’arrête sur lui, en nommant le lien. Une configuration conservée hors du projet est lue en la désignant comme fichier global, comme le décrit Désigner explicitement le fichier global. Voir La frontière du workspace.
Étendre une liste au lieu de la remplacer
Un paramètre à valeur de liste se comporte comme tout autre paramètre : la valeur du fichier le plus proche remplace celle du fichier le plus éloigné. Lorsque vous voulez ajouter à ce qu’un fichier extérieur a déclaré plutôt que de le reformuler, utilisez le compagnon d’ajout placé à côté :
| paramètre de liste | son compagnon d’ajout |
|---|---|
workspace.catalog_dirs | catalog_dirs_append |
plugins.governance | governance_append |
plugins.linter | linter_append |
plugins.importer | importer_append |
plugins.providers | providers_append |
Les entrées sous un compagnon sont concaténées à la liste résolue à chaque couche au lieu de la masquer, de sorte qu’un sous-projet ajoute un linter à tout ce que la racine a déjà déclaré :
# <project>/services/api/.aggrega-config.yamlplugins: linter_append: - uri: ./lint/api-rules.wasmLà où un même fichier définit à la fois la liste de base et son compagnon, la valeur de ce fichier est la liste de base suivie des entrées ajoutées.
Le bloc workspace: est l’exception quant à l’endroit où un compagnon peut être écrit. Un fichier portant ce bloc marque son propre répertoire comme racine du projet, de sorte que le fichier d’un sous-projet qui écrirait workspace.catalog_dirs_append démarrerait un projet à part au lieu d’ajouter au projet englobant. Le compagnon des répertoires de catalogue se compose entre votre fichier global et le fichier racine du projet.
La liste plugins.cli se compose d’elle-même entre les fichiers et n’a pas de compagnon : une extension de commande déclarée dans le fichier global enregistre sa commande dans chaque projet, une extension déclarée dans un projet ne l’enregistre que là, et les deux s’enregistrent ensemble. Chaque entrée épingle un plugin : l’uri qu’elle résout et le digest des octets que aggrega plugin add cli a vérifiés, écrit sha256: suivi de 64 chiffres hexadécimaux en minuscules. Un digest dans toute autre graphie ne pourrait jamais être égal au digest que donne le hachage des octets résolus, il est donc refusé au chargement du fichier, en nommant le fichier et l’entrée.
Donner à une Release ses propres répertoires de catalogue
Un projet peut conserver plusieurs variantes de catalogue côte à côte — une par cible, chacune contenant les Recipes qui effectuent le rendu des mêmes Components pour un autre fournisseur — et construire chaque Release à partir de l’une d’elles. Nommez chaque Release sous workspace.releases et donnez-lui ses propres catalog_dirs :
# <project>/.aggrega-config.yamlworkspace: releases: release-compose.yaml: catalog_dirs: - ./catalog-compose release-helm.yaml: catalog_dirs: - ./catalog-helmChaque clé est un fichier de Release, écrit relativement au fichier de configuration qui le nomme. Une clé — comme build.authoring_release — peut nommer une Release conservée hors du projet, et la nommer ici est la façon dont un projet l’atteint : un lien à l’intérieur du projet qui y mène est lu au lieu d’être ignoré, comme le décrit La frontière du workspace. Les deux clés situées en dessous signifient ce qu’elles signifient dans le bloc workspace:, limitées à cette seule Release :
catalog_dirsremplace la liste du workspace pour cette Release. L’ordre de recherche, le répertoirecataloglu après elle et ce qu’indique une liste vide sont les mêmes que pour la liste propre du workspace.catalog_dirs_appendest lu après la liste de la Release. Une entrée qui n’écrit quecatalog_dirs_appendconserve la liste du workspace et y ajoute.
Une Release que la table ne nomme pas lit le workspace.catalog_dirs propre au workspace. Une Release que la table nomme lit ses propres répertoires quelle que soit la façon dont elle est construite — aggrega build ou aggrega pull dans un terminal, l’éditeur via aggrega serve, un assistant via aggrega mcp — de sorte qu’aucun d’eux n’a besoin d’un flag pour trouver son catalogue. Un --catalog <dir> sur la ligne de commande est toujours parcouru avant les répertoires de la Release, pour cette seule invocation. Et une recherche qui ne trouve aucune entité sous un nom que vous avez utilisé désigne l’entrée de cette Release comme l’endroit où lister le répertoire qui la contient.
Une entrée qui nomme un fichier inexistant est refusée au chargement de la configuration, en nommant l’entrée et le fichier. Renommer une Release arrête donc chaque commande jusqu’à ce que l’entrée soit renommée avec elle, au lieu de laisser la Release se construire à partir de la liste du workspace sans que rien ne le signale. Un répertoire qu’une entrée liste doit être un répertoire, comme doit l’être celui que nomme la liste du workspace : un répertoire qui n’en est pas un est refusé par chaque commande qui lit le catalogue de cette Release, en nommant l’entrée et sa ligne.
Ce qui ne concerne aucune Release en particulier lit toujours la liste du workspace : un lint ou une validation de l’ensemble du catalogue, la recherche d’une entité par son nom, un Aggregate inspecté seul et la liste des entités du workspace dans un éditeur. AGGREGA_CATALOG_DIRS définit la liste du workspace et n’atteint aucune entrée ici, et un fichier de configuration appartenant à votre pipeline ne lit pas du tout la table.
Un fichier de configuration appartenant à votre pipeline
Un fichier nommé .aggrega-config-append-ci.yaml peut se trouver à côté du fichier écrit à la main dans n’importe quel répertoire que le parcours visite. C’est un fichier distinct, afin qu’un pipeline automatisé puisse le posséder et l’écraser en entier sans jamais toucher à ce qu’une personne a écrit.
Il est uniquement additif. Ses entrées pour les cinq paramètres de liste ci-dessus sont concaténées aux listes résolues ; il ne peut rien supprimer ni remplacer un scalaire. Une clé scalaire ou de map qui y est écrite n’a aucune signification additive, elle est donc ignorée et nommée dans un avertissement au lieu d’être appliquée en silence. Il ne marque jamais non plus une racine de projet, de sorte qu’en déposer un dans un répertoire ajoute des rattachements sans déplacer l’endroit où commence le projet.
Où pointe un chemin relatif
Un chemin relatif du système de fichiers est résolu par rapport au répertoire du fichier qui l’a déclaré — pas par rapport à la racine du projet, ni par rapport au répertoire depuis lequel vous avez lancé la commande. C’est la règle qui mérite d’être lue deux fois, car un chemin qui semble relatif au projet est résolu ailleurs et le build réussit quand même, sur un contenu que vous n’aviez pas prévu.
Elle s’applique à workspace.catalog_dirs, aux fichiers de Release servant de clés sous workspace.releases et aux répertoires que liste chaque entrée, aux chemins du système de fichiers local d’un rattachement plugins.governance ou plugins.linter — un uri qui nomme un fichier .wasm sur disque, et chaque entrée sous le with.sources de ce rattachement — et à chaque entrée sous le with.sources d’un rattachement plugins.importer. Dans les trois listes, un uri sans deux-points qui ne nomme aucun registre — importer/agent-flows tout comme ./lint/api-rules.wasm — est un tel chemin, tandis qu’un uri qui nomme un plugin par son identité porte la version après un deux-points, importer/agent-flows:1.2.0, et est laissé exactement tel qu’il est écrit. L’uri d’un rattachement d’importeur nomme l’importeur qu’il rattache, comme le décrit Quel importeur transforme une source en brouillons ; un import ne lit aucun module depuis un chemin écrit à cet endroit. La règle s’applique aussi aux entrées sous les compagnons d’ajout, et chacune d’elles s’ancre à son propre fichier déclarant plutôt qu’au fichier où la fusion se trouve aboutir. Et elle s’applique à mcp.tls.cert_file, mcp.tls.key_file et mcp.authorization.jwks_file, de sorte qu’un fichier placé à côté de celui qui le nomme est trouvé d’où que le serveur soit lancé.
Ainsi, avec cette disposition :
myproject/├── .aggrega-config.yaml└── services/ ├── .aggrega-config.yaml └── catalog/et ./catalog écrit dans le fichier racine, le chemin désigne myproject/catalog. Écrit dans services/.aggrega-config.yaml, le même texte désigne myproject/services/catalog. Un chemin absolu est laissé exactement tel qu’il est écrit, tout comme une référence de registre telle que oci://hub.aggrega.ai/plugins/helm:1.0.0.
Ces paramètres ne suivent délibérément pas cette règle, parce qu’ils n’ont aucun fichier déclarant auquel s’ancrer ou parce que chacun de leurs lecteurs les résout ailleurs :
artifact_cache_direst interprété relativement à la racine du projet, d’où que la commande soit lancée, de sorte que le cache est un seul répertoire plutôt qu’un par emplacement d’invocation. Une valeur absolue est refusée au chargement de la configuration.AGGREGA_CATALOG_DIRSprovient de l’environnement et n’a aucun fichier déclarant, fournissez-y donc des chemins absolus.mcp.listenest pris exactement tel qu’il est écrit, y compris le chemin du système de fichiers dans sa formeunix:<path>. La même adresse arrive aussi deaggrega mcp --listen, qui n’a aucun fichier déclarant, de sorte qu’ancrer la seule graphie configurée ferait qu’une même chaîne désignerait deux endroits différents selon sa provenance. Donnez au socket un chemin absolu.
Un paramètre dont le stockage est partagé
Presque tous les paramètres régissent quelque chose qui appartient au projet sur lequel vous travaillez — à travers quels répertoires il résout le contenu de catalogue, quels plugins effectuent le rendu de ses cibles, avec quelle rigueur son contenu est jugé, quelle taille peuvent atteindre les caches en mémoire du démon. Une valeur dans le fichier d’un projet régit ce qui est propre à ce projet, et il n’y a rien à surveiller.
compiled_module_cache.max_bytes est la seule exception, car ce qu’il plafonne n’est pas propre à un projet. Le code compilé des plugins est conservé dans un seul répertoire que chaque projet de votre machine réutilise, de sorte qu’un plugin donné est compilé une fois plutôt qu’une fois par projet. Le plafond lui-même se résout comme tout autre paramètre — écrivez-le dans le fichier d’un projet et cette valeur l’emporte pour ce projet — mais le stockage n’a toujours qu’une seule taille, et la taille en vigueur est celle du build le plus récent. Deux projets qui le plafonnent différemment prennent effet tous deux à tour de rôle, et le plafond le plus bas supprime du code compilé que l’autre projet a payé.
Placez-le donc dans le fichier global lorsque vous voulez une seule réponse pour tout ce que vous construisez, et maintenez-le au-dessus de ce qu’un seul build compile. aggrega cache status indique ce que le stockage contient actuellement, et aggrega config show --origin vous indique de quel fichier provient réellement le plafond sous lequel vous travaillez.
Paramètres pour un serveur que d’autres personnes atteignent
aggrega mcp parle le Model Context Protocol. Sur votre propre machine, un client le lance comme sous-processus et communique avec lui via l’entrée et la sortie standard, ce qui est le comportement par défaut, et les seuls paramètres que lit cette forme sont mcp.transport, laissé à cette valeur par défaut, et mcp.announce_tools. Le reste du bloc mcp est destiné à l’autre forme, que choisit mcp.transport: http : un seul processus de longue durée sur un hôte, atteint via HTTP par des appelants qui ne sont pas devant son clavier.
# <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 est ce qui choisit le transport. http démarre un listener ; stdio, la valeur par défaut, communique via l’entrée et la sortie standard, ce qu’attend un client sous-processus. Toute autre valeur est refusée au chargement de ce fichier. aggrega mcp --transport <stdio|http> fait de même pour une seule invocation et l’emporte sur la clé, comme tout flag l’emporte sur tout fichier.
mcp.listen nomme l’endroit où ce listener se lie, et ne choisit rien. Donnez-lui une adresse host:port ou un socket unix:<path> ; aggrega mcp --listen <address> l’emporte sur lui pour une seule invocation. Avec http choisi et aucune adresse provenant de l’un ou de l’autre, le lancement est refusé avant que quoi que ce soit ne se lie. Avec stdio choisi, un --listen saisi est refusé, et une adresse que seule cette clé nomme reste inutilisée — le serveur le signale en une ligne sur son flux d’erreur, en nommant ce fichier et mcp.transport: http. Un serveur que d’autres personnes atteignent définit donc les deux clés, comme ci-dessus, et un client lancé depuis un répertoire que couvre ce fichier atteint tout de même le serveur via ses propres flux. Un chemin unix: est pris tel qu’il est écrit au lieu d’être ancré — voir Où pointe un chemin relatif.
mcp.tls.cert_file et mcp.tls.key_file placent TLS dans le processus. Définissez les deux et le listener sert lui-même du HTTPS. Omettez les deux et il sert du texte en clair, ce qui n’est accepté que sur loopback ou sur un socket Unix — la forme que vous utilisez lorsqu’un proxy placé devant détient le certificat et relaie vers le processus. Un listener en clair sur toute autre adresse est refusé avant que quoi que ce soit ne se lie, en nommant ces deux clés, et il en va de même si l’une des deux est définie sans l’autre. Les deux sont des chemins du système de fichiers et suivent la règle ci-dessus : un chemin relatif est résolu par rapport au répertoire du fichier qui l’a déclaré, de sorte qu’un certificat commité à côté de ce fichier est trouvé d’où que le serveur soit lancé. Écrivez-les en absolu là où le certificat est géré hors du projet.
mcp.authorization.issuer et mcp.authorization.resource indiquent qui émet les jetons que présentent les appelants, et comment ce serveur s’appelle en tant que ressource pour laquelle ils sont émis. Les deux sont requis dès que le transport http est choisi, et sans eux un listener est refusé avant que quoi que ce soit ne soit lié, car chaque requête adressée au point de terminaison reçoit en réponse un challenge bearer-token, et un challenge qui n’indique aucune destination est un challenge auquel un client ne peut pas donner suite. Écrivez des adresses complètes, schéma et hôte compris : l’émetteur exactement tel que ce serveur d’autorisation déclare son propre identifiant, et la ressource comme l’adresse que vos appelants atteignent réellement — l’hôte que présente un proxy placé en amont, s’il y en a un, plutôt que l’adresse à laquelle ce processus se lie. Les deux sont publiés, sans qu’aucun identifiant ne soit demandé, dans le document de métadonnées OAuth de ressource protégée que sert le listener, et c’est là qu’un client cherche où obtenir un jeton. Aucun des deux ne contient quoi que ce soit de secret : un jeton arrive avec la requête qui le présente et n’est jamais écrit dans un fichier de configuration. L’émetteur est une adresse https, sauf si le serveur d’autorisation tourne sur cette machine — localhost, 127.0.0.1 ou ::1 —, et un listener qui indique un émetteur en http simple sur tout autre hôte est refusé avant que quoi que ce soit ne soit lié, quelle que soit la façon dont il lit ses clés et ses appelants : chaque client est envoyé vers l’émetteur pour obtenir son jeton, de sorte qu’en http simple son code d’autorisation et son jeton traverseraient le réseau sans protection, et lorsque les clés sont aussi lues à partir de là, quiconque se trouve sur ce chemin pourrait les substituer.
mcp.authorization.jwks_file désigne un fichier contenant les clés par rapport auxquelles les jetons sont vérifiés, au lieu de les lire depuis le serveur d’autorisation. Si vous l’omettez, le serveur lit les métadonnées de ce serveur à leur adresse well-known et suit le jwks_uri qui y est publié, ce que fait un workspace disposant d’un accès réseau. Cette adresse de clés est soumise à la même règle que l’émetteur, tout comme toute adresse vers laquelle l’une ou l’autre lecture est redirigée : une adresse en http simple sur un autre hôte n’est jamais interrogée, et un jeton qui a besoin de ces clés reçoit la réponse 503 jusqu’à ce que le serveur d’autorisation publie ses métadonnées et ses clés en https. Si vous la définissez, le serveur d’autorisation n’est jamais contacté — c’est ce dont a besoin un workspace qui déclare offline: true, et un tel workspace est refusé avant que son listener ne se lie, sauf si cette clé désigne un fichier. C’est un chemin, qui suit la règle ci-dessus : un chemin relatif est résolu par rapport au répertoire du fichier qui l’a déclaré, de sorte qu’un jeu de clés committé à côté de ce fichier est trouvé quel que soit l’endroit d’où le serveur est lancé. Le fichier contient des clés publiques de vérification, c’est-à-dire ce que publie un serveur d’autorisation — rien qui signe, et rien de secret.
mcp.allowed_origins n’est consulté que lorsqu’une requête porte un en-tête Origin, ce qui signifie en pratique qu’un navigateur l’a envoyée. Listez-y les origines que vous servez ; une requête qui en indique une non listée est refusée, et une requête sans cet en-tête est servie malgré tout. Un client qui n’est pas un navigateur n’envoie pas cet en-tête et n’a besoin d’aucune entrée. Une entrée est comparée exactement à l’en-tête ; écrivez-la donc comme un navigateur l’envoie : un schéma en minuscules, ://, un hôte en minuscules, et : suivi du port uniquement lorsque le port n’est pas celui par défaut du schéma — https://studio.example.com, ou http://localhost:3000 pour une page servie sur votre propre machine —, sans chemin et sans / final. Une entrée de toute autre forme ne pourrait jamais correspondre, et elle est refusée au chargement de ce fichier, avec le nom de l’entrée.
mcp.limits borne ce qu’un appelant peut demander — la taille que peut avoir le corps d’une seule requête, le nombre de requêtes exécutées simultanément et le nombre de requêtes qu’un appelant peut envoyer en une minute. Les trois sont toujours en vigueur ; aucune n’a de valeur qui la lève. La troisième, requests_per_minute, est comptée séparément pour chaque appelant, de sorte qu’un appelant qui envoie beaucoup ne coûte rien à un autre.
mcp.authorization.trusted_proxy lit l’appelant depuis un proxy placé en amont au lieu de vérifier un jeton ici. Définissez principal_header sur l’en-tête que ce proxy utilise pour dire qui est l’appelant et, facultativement, scopes_header sur un en-tête portant les scopes de cet appelant. Les deux sont des noms d’en-tête HTTP, comme X-Forwarded-User — lettres, chiffres, traits d’union et les quelques autres caractères qu’un nom d’en-tête peut contenir, sans espace ni deux-points —, et un nom de toute autre forme est refusé au chargement de ce fichier, avec le nom de la clé, car aucune requête ne pourrait le porter. Dans ce mode, aucun jeton n’est lu, et une requête sans l’en-tête du principal est refusée. Comme l’en-tête est alors l’intégralité de l’identifiant, il n’est digne de confiance que là où rien d’autre ne peut le définir : le processus est refusé avant de se lier, sauf si mcp.listen est une adresse de loopback ou un socket Unix. Si vous omettez le bloc, ce serveur vérifie lui-même les jetons, ce qui est le comportement par défaut ; un bloc dont le principal_header est vide est refusé plutôt que lu comme ce comportement par défaut.
mcp.deny_reach retire un type de portée à ce déploiement. Chaque opération qu’effectue le serveur déclare jusqu’où vont ses propres effets — none pour une opération qui lit ou effectue un rendu et ne laisse rien derrière elle, workspace pour une opération qui écrit à l’intérieur du workspace que sert ce processus, registry pour une opération qui publie, signe ou retire, et machine pour une opération qui modifie ce que partagent tous les workspaces de l’hôte. Nommer ici un type retire tout outil qui l’atteint : l’outil est absent de la liste d’outils de chaque appelant, quoi que porte le jeton de cet appelant, et un appel à cet outil est refusé avec le nom de ce paramètre. Cela en fait la limite du déploiement plutôt que celle de l’appelant, et aucun identifiant ne la lève — un serveur destiné à servir des lectures et rien d’autre liste ici les trois types qui écrivent et ne peut alors pas publier, même pour un appelant dont le jeton porte tous les scopes. Si vous l’omettez, ce qui est le comportement par défaut, ce déploiement offre tout ce qu’admettent les scopes de ses appelants. Une valeur qui n’est pas l’une des quatre est refusée au chargement de ce fichier, plutôt qu’ignorée. Rien du type machine n’est proposé sur HTTP, quoi qu’indique ce paramètre, de sorte que le nommer est accepté et ne change rien ; aggrega-mcp.md expose les types et les scopes qui les admettent.
mcp.announce_tools restreint ce que le serveur annonce, et c’est une limite différente de la clé précédente. Nommez les outils que ce serveur annonce, écrits tels que la liste d’outils les indique, et exactement ceux-là sont annoncés : un outil omis est absent de la liste d’outils de chaque appelant et refusé s’il est malgré tout appelé par son nom, avec le nom de ce paramètre. Si vous omettez la clé — le comportement par défaut —, chaque outil que propose le serveur est annoncé ; si vous écrivez une liste vide, aucun ne l’est, de sorte que ces deux écritures sont des déclarations différentes et qu’aucune valeur par défaut n’est ajoutée à votre place. Ce qui la distingue de deny_reach, c’est ce que chacune retire. deny_reach retire une capacité : les opérations d’un type retiré ne sont pas du tout proposées ici, et aucun identifiant n’en rétablit une. announce_tools ne retire qu’une annonce — les outils qu’elle omet sont des capacités que le serveur possède toujours —, et elle répond à un client qui plafonne le nombre d’outils qu’il enregistrera, parfois sur l’ensemble des serveurs auxquels il est connecté à la fois. Lorsque les deux sont définies, le retrait l’emporte, de sorte qu’un outil d’un type retiré reste absent quelle que soit la façon dont cette clé le nomme. Un nom auquel aucun outil ne répond arrête le serveur avant qu’il ne serve quoi que ce soit, en listant les outils dont il dispose, plutôt que de vous laisser une surface plus étroite que celle que vous avez demandée. Contrairement aux autres clés ici, qui configurent le listener que démarre le transport http, elle est lue quel que soit le transport que parle le serveur, car le client pour lequel une restriction existe est généralement celui qui a lancé le processus via sa propre entrée et sortie standard ; aggrega-mcp.md expose le reste.
mcp.health.listen place les vérifications de liveness et de readiness sur une adresse qui leur est propre. Donnez-lui une adresse sous l’une des deux formes de mcp.listen, et un second listener y répond à GET /healthz — 200 dès que le processus est en cours d’exécution — et à GET /readyz — 503 jusqu’à ce que le workspace soit résolu et le point de terminaison lié, 200 ensuite, ce qui permet à un répartiteur de charge de retenir le trafic jusqu’à ce que le processus puisse réellement répondre à un appel. Si vous l’omettez, aucune des deux vérifications ne reçoit de réponse nulle part. Elles ne reçoivent jamais de réponse sur l’adresse que désigne mcp.listen, qui leur renvoie le 404 qu’il renvoie à tout chemin qu’il ne sert pas : une sonde à cet endroit serait une lecture non authentifiée d’un listener qui refuse tout le reste. Contrairement à mcp.listen, cette adresse n’est pas restreinte et aucune adresse n’est refusée pour elle — pointez-la vers le loopback ou un socket Unix, ce qu’atteint un superviseur placé à côté de ce processus, et notez que tout ce qui peut atteindre l’adresse que vous choisissez peut lire ces deux réponses.
schema/other/aggrega-config.md indique chacune de ces clés avec sa valeur par défaut, lorsqu’elle en a une.
Les autres façons dont une racine de projet est reconnue
--workspace-root <path>, ou son équivalent AGGREGA_WORKSPACE_ROOT, désigne directement la racine et ignore la découverte. Le dossier qu’il désigne doit exister : un chemin qui ne désigne rien, ou qui désigne un fichier, est refusé avant que la commande ne fasse quoi que ce soit d’autre, et le refus nomme celui des deux qui a fourni la valeur et la cite telle qu’elle a été donnée. Sinon, la découverte remonte depuis le répertoire de travail, et les types d’ancre se classent les uns par rapport aux autres plutôt que par proximité :
- Un
.aggrega-config.yamlcontenant un blocworkspace:l’emporte d’office, quelle que soit la profondeur à laquelle il se trouve. La remontée continue d’en chercher un même après avoir dépassé un marqueur du type ci-dessous, de sorte qu’une racine explicitement marquée plus haut l’emporte toujours sur un marqueur fortuit situé en dessous. - À défaut, le plus proche de ces marqueurs ancre la racine, et au sein d’un même répertoire ils se classent dans cet ordre : un répertoire
.aggrega/, puis unaggregate*.yaml, puis unrelease*.yaml, puis unmanifest*.yaml. - À défaut de tout le reste, le répertoire de travail est utilisé — les commandes s’exécutent au lieu de refuser de démarrer. Une commande dont le résultat dépend de l’espace de travail — une commande qui lit ou écrit les documents de l’espace de travail, lit ou remplit son cache d’artefacts, ou le sert — avertit une fois sur la sortie d’erreur standard :
warning: <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace. Une commande dont le résultat ne dépend pas du dossier qui est la racine ne dit rien, même lorsqu’elle lit la configuration : parmi ellesaggrega version,aggrega config show,aggrega plugin list,aggrega registry list,aggrega explainetaggrega login.aggrega config capture, dont le travail consiste à écrire le fichier de configuration propre à l’espace de travail, n’écrit rien dans un tel dossier et se termine avec une erreur qui le signale.
Rien n’est écrit dans un cache d’artefacts dans un tel dossier. Un répertoire .aggrega/ est lui-même l’un des marqueurs ci-dessus, de sorte qu’un cache écrit à cet endroit ferait du dossier un workspace simplement parce que quelque chose y a été récupéré un jour. Une commande dont le travail remplit le cache — aggrega pull, un build qui résout d’abord ses dépendances, aggrega registry update, l’ajout d’un plugin d’extension de commandes depuis un registre — est refusée avant de récupérer quoi que ce soit, en nommant le dossier et les deux solutions : désigner le workspace avec --workspace-root ou AGGREGA_WORKSPACE_ROOT, ou donner au dossier un .aggrega-config.yaml contenant un bloc workspace:. aggrega pin, et aggrega push d’une Recipe ou d’une FeatureRecipe, qui est tenu aux pins qu’enregistre l’entity.lock placé à côté, ne remplissent le cache qu’avec les sources distantes que l’entité écrit en entier, que récupère le pinning de l’une d’elles ou la comparaison de son pin : ils sont refusés de la même façon là où ils récupéreraient une telle source, avant de la récupérer. Une entité sans une telle source — aucune source, une source locale, ou une source dont chaque Release renseigne les coordonnées — y est pinnée ou publiée comme partout ailleurs. Un build à cet endroit n’est pas refusé, mais une entrée externe que son lockfile pinne et que le cache ne contient plus n’est pas récupérée à nouveau pour le réparer : le rendu reçoit la même phrase à la place de cette entrée, de la façon dont il reçoit celle de la posture hors ligne, et la signale. L’endroit où artifact_cache_dir place le cache ne change rien ici, car le répertoire est joint à la racine trouvée, quelle qu’elle soit. Les commandes qui ne font que lire répondent toujours.
Ce dernier recours a une exception. Lorsque rien n’a désigné la racine et que le répertoire de travail n’ancre rien, une commande portant sur une Release ou sur un document d’entité qui désigne ce fichier par un chemin absolu découvre à nouveau la racine, en remontant depuis le dossier où se trouve le fichier, et utilise ce qu’elle trouve : le workspace auquel appartient le fichier ou, à défaut de tout, ce dossier. Le fichier est celui que désigne --release pour aggrega build et aggrega pull ; la Release donnée à aggrega validate, aggrega lint et aggrega inspect, ou sinon le fichier qui leur est donné ; et le document donné à aggrega pin, aggrega push et aggrega edit-document. Ainsi, la Release d’un projet buildée depuis l’extérieur du projet lit la configuration propre au projet, comme lorsque la commande s’exécute à l’intérieur, et les avertissements de configuration qu’affiche la commande sont ceux de ce workspace. Lorsque le propre dossier du fichier n’ancre rien non plus, ce dossier est celui que nomme l’avis de la commande et celui dans lequel aucun cache n’est écrit. Un chemin relatif est lu par rapport au répertoire dans lequel vous exécutez la commande et ne change rien, et une racine désignée, ou un répertoire de travail qui se trouve lui-même dans un workspace, est utilisé tel quel. Le serveur de l’assistant applique la même règle à un appel qui désigne sa Release ou son document par un chemin absolu.
Marquer la racine avec un bloc workspace: est le choix explicite et celui à privilégier ; les marqueurs de fichier et de répertoire permettent tout de même de builder un projet qui n’en a pas déclaré.
Désigner explicitement le fichier global
La couche globale se résout dans cet ordre :
--config <path>, la forme propre à une invocation.- La variable d’environnement
AGGREGA_CONFIG. - L’emplacement par défaut : sous Windows,
aggrega\config.yamldans le répertoire que désigne la variable d’environnementAPPDATA, et ailleursaggrega/config.yamldans le répertoire que désigneXDG_CONFIG_HOME, avec~/.config/aggrega/config.yamlcomme repli.
Les deux premiers désignent un fichier explicite, de sorte qu’un chemin qui n’existe pas est une erreur signalée clairement plutôt qu’un repli silencieux — vous avez demandé un fichier précis. Une commande qui lit sa configuration s’arrête sur une phrase qui se termine par le chemin, afin que vous puissiez le copier. aggrega config init est l’exception, car créer ce fichier est sa raison d’être : il crée le fichier désigné et le signale. L’emplacement par défaut est chargé lorsque le fichier s’y trouve et ignoré silencieusement lorsqu’il n’y est pas. Quel que soit le fichier résolu, les fichiers de votre projet continuent de se superposer à lui.
Lorsqu’aucun d’eux ne se résout — aucun fichier n’est désigné, et les variables à partir desquelles l’emplacement par défaut est lu ne sont pas définies —, une commande qui écrit le fichier global s’arrête et indique ce qu’il faut définir. Variables d’environnement liste, par plateforme, les variables à partir desquelles chaque emplacement est lu.
Ce choix détermine aussi où écrit une commande qui écrit la configuration. Une commande exécutée avec --config <path> lit sa configuration dans ce fichier et applique sa modification à ce même fichier, de sorte que ce qu’écrit une commande est ce que la suivante relit.
Le fichier dans lequel une commande écrit par défaut dépend de la nature du paramètre : l’outillage à l’échelle de la machine, comme un registre, va dans le fichier global, tandis que les paramètres qui participent au build, comme une liaison de provider ou un rattachement de socket, vont dans le fichier committé du projet, afin qu’ils accompagnent le projet. Passez --global ou --workspace pour changer de cible, et la commande affiche le fichier dans lequel elle a écrit.
Voir aussi
- aggrega-config.md — les commandes
aggrega configqui initialisent, inspectent et figent la configuration. - environment-variables.md — chaque variable préfixée par
AGGREGA_, et où les secrets sont fournis. - global-flags.md —
--config,--workspace-rootet les autres flags qu’accepte chaque sous-commande. - schema/other/aggrega-config.md — chaque clé de configuration, son type et sa valeur par défaut.
- aggrega-cache.md — ce que contient réellement
artifact_cache_dir. - workspace-boundary.md — quels chemins restent à l’intérieur du workspace, et comment les répertoires et fichiers que désigne cette configuration atteignent l’extérieur.
- aggrega-mcp.md — le serveur que configure le bloc
mcp.