Configuración
De dónde lee aggrega su configuración y en qué archivo poner cada ajuste.
El caso simple
Dos archivos, y la mayoría de los proyectos no necesitan nada más.
Un archivo en tu proyecto, llamado .aggrega-config.yaml, ubicado en la raíz del proyecto. Contiene cómo se compila este proyecto: qué directorios contienen contenido de catálogo incluido en el proyecto, qué plugins renderizan qué destinos, qué reglas de lint se relajan, dónde va la caché local. Se confirma en el repositorio, de modo que un compañero de equipo que clona el proyecto lo compila de la misma manera.
Su bloque workspace: es lo que marca el directorio como raíz del proyecto:
# <project>/.aggrega-config.yamlworkspace: catalog_dirs: - ./catalogauto_pull: trueEl bloque contiene solo los directorios de catálogo que definen la raíz; cualquier otra configuración se sitúa en el nivel superior junto a él. Un proyecto que no incluye contenido de catálogo escribe igualmente el bloque, vacío —workspace: {}—, porque la presencia del bloque es la marca.
Un archivo global en tu máquina, en ~/.config/aggrega/config.yaml —en Windows, en aggrega\config.yaml dentro del directorio que indica la variable de entorno APPDATA—. Cada workspace de esa máquina se resuelve a través de él, y contiene configuraciones que pertenecen a la máquina y no a un proyecto concreto: los registros de los que haces pull y la política de confianza de firmas de cada uno, cuánto puede crecer el almacén de módulos compilados y cualquier plugin de extensión de comandos que hayas instalado. Estas son las mismas dondequiera que trabajes, así que declararlas una sola vez es precisamente el objetivo. Se carga automáticamente cuando existe, y nada se rompe cuando no existe.
registries: - host: hub.aggrega.ai signing: required: trueaggrega config init escribe ese archivo global por ti, registrando un registro junto con la política de confianza de firmas que anuncia, e indica dónde está el archivo en tu máquina y dónde se guardan las cachés de toda la máquina. aggrega config show imprime lo que se aplica en este momento, y aggrega config show --origin indica qué archivo —o qué variable de entorno— decidió cada configuración.
Los secretos no son configuración. Una contraseña de registro y un token de identidad de firma nunca son campos de ninguno de los dos archivos; se suministran mediante variable de entorno o flag en el momento en que se necesitan. Consulta environment-variables.md.
De dónde se leen las entidades locales
Un proyecto que mantiene contenido de catálogo propio —un Component, una Feature, una Recipe, uno de los tipos de biblioteca— tiene dos maneras de indicar dónde vive ese contenido, y la primera no necesita ninguna configuración.
Un directorio catalog en la raíz del proyecto se lee tanto si algo lo nombra como si no. Coloca una entidad bajo <project>/catalog/ y cada comando que carga un catálogo la lee, incluso en un proyecto cuyo bloque workspace: está vacío. Un directorio de catálogo se lee de forma recursiva, así que cómo organices los subdirectorios dentro de él depende de ti.
Los directorios listados en workspace.catalog_dirs también se leen, y se leen primero. La lista es una pila de búsqueda ordenada: el primer directorio que declara una identidad es su dueño, y la misma identidad en un directorio posterior queda ocultada. catalog se lee después de todo lo listado —a menos que un directorio listado ya lo contenga, en cuyo caso se lee como parte de ese directorio—, de modo que listar un directorio se suma a lo que tenías en lugar de reemplazarlo. Un --catalog <dir> repetible en la línea de comandos se lee antes que ambos, y una ruta relativa dada allí se resuelve respecto al directorio desde el que ejecutaste el comando, ya que ningún archivo de configuración la declaró. Un directorio nombrado más de una vez —en la línea de comandos y en la lista, o dos veces en la lista— se lee una sola vez, en el lugar donde se nombró primero, de modo que nada de su interior se informa como ocultado por sí mismo: un ocultamiento son siempre dos archivos distintos que declaran una misma identidad. Dos grafías de un mismo directorio, una ruta hacia él a través de un enlace y —en un sistema de archivos que ignora mayúsculas y minúsculas— una grafía con otras mayúsculas nombran todas ese único directorio. Un directorio dentro de otro directorio listado se sigue leyendo como entrada propia. Un proyecto que mantiene una variante de catálogo por Release puede, en su lugar, dar a cada Release una lista propia; consulta Dar a una Release sus propios directorios de catálogo.
Listar un directorio es la forma en que un proyecto lee entidades que se mantienen fuera de él. Un directorio listado puede estar en cualquier lugar —un checkout contiguo, un directorio compartido con otros proyectos— y se lee donde está, incluso cuando es en sí mismo un enlace simbólico. Nada más llega tan lejos: un enlace dentro del proyecto que lleva a otro lugar no se sigue, y un documento que nombra un archivo fuera del proyecto mediante una ruta se rechaza, de modo que una entidad mantenida en otro lugar se alcanza listando el directorio que la contiene y nombrando la entidad por su nombre. Un directorio listado fuera del proyecto es una raíz propia, así que tampoco se lee un enlace debajo de él que salga de él. El límite del workspace expone la regla completa.
Un directorio listado debe ser un directorio. Una ruta listada donde no existe nada, o donde hay un archivo o un enlace que no lleva a ninguna parte, se rechaza antes de leer o escribir nada por cada comando que lee el catálogo —un pull, un build, una validación, una inspección, un lint, y las mismas operaciones lanzadas desde el editor a través de aggrega serve o desde un asistente a través de aggrega mcp—, de modo que un build nunca se ejecuta con menos catálogos de los que listaste. El rechazo nombra la entrada tal como está escrita, la ruta en la que se resolvió, el archivo de configuración y la línea que la listan, y la lista en la que está:
<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 invalidCrea el directorio o elimina la entrada: una copia de un proyecto tomada sin un checkout contiguo que este lista elimina esa entrada, y resuelve desde un registro lo que el checkout habría aportado. Lo mismo vale para un directorio que lista la entrada propia de una Release, para uno que añade un archivo de configuración propiedad de tu pipeline o el archivo global, y para uno que contiene AGGREGA_CATALOG_DIRS, que el rechazo nombra en lugar de un archivo. La configuración en sí se sigue cargando, así que un comando que no lee ningún catálogo se sigue ejecutando. Un directorio --catalog que no existe se escribió para un solo comando, y aggrega build lo rechaza, nombrando el directorio. Un directorio listado que existe y no se puede leer lo rechazan los comandos que cargan el catálogo completo, nombrándolo.
Escribir la lista vacía indica que este proyecto no tiene ningún catálogo local, y es la única grafía que también impide que se lea catalog:
# <project>/.aggrega-config.yamlworkspace: catalog_dirs: []Omitir la clave es una declaración distinta: una lista omitida es el caso habitual, y catalog se sigue leyendo.
Un build, un pull, una validación o un aggrega inspect que no encuentra ninguna entidad con un nombre que usaste indica de dónde lee este proyecto las entidades locales y qué cambiar para que se lea la que nombraste. No dice nada parecido donde escribiste la lista vacía: no leer ningún catálogo local es lo que declaraste allí, y sugerir cambiarlo sería contradecirte. Tampoco lo dice donde el documento que declara ese nombre se leyó y se rechazó: ese documento ya está donde lee el catálogo, así que el informe nombra en su lugar lo que el documento infringe, la línea y la restricción, y moverlo no arreglaría nada. Un documento tan mal formado que el nombre que declara ni siquiera se puede leer no se puede asociar al nombre que usaste, así que la explicación se da igualmente, y donde ese documento declara una apiVersion de Aggrega, un build, un pull o una validación de una Release lo nombra junto a la explicación, con el motivo que da el propio analizador, ya que puede ser el archivo que abrir. Un fallo que encontró la entidad y no pudo aceptarla —un registro que ahora sirve otros bytes bajo una versión que fija tu lockfile, un archivo que la entidad incluye y que no se puede leer— tampoco es una entidad ausente, y solo informa de su propio remedio.
Si un pull o un push fija una entidad
Una Recipe o una FeatureRecipe lleva las fijaciones de las entradas que lee —un source: remoto escrito completo, un archivo que importa una entrada de artifacts, los archivos de un source: junto a ella— en el entity.lock junto a ella, y registrarlas es el paso del autor de la entidad, aggrega pin. De forma predeterminada, ni pull ni push ejecuta ese paso: un pull se detiene ante una entidad que su lock no fija, y un push se niega a publicarla. Dos claves, una por comando, hacen que ejecutarlo sea el comportamiento predeterminado de ese comando:
# <project>/.aggrega-config.yamlworkspace: {}pin_sources_at_pull: truepin_sources_at_push: trueCada clave rige su propio comando y nada más, y el --pin-sources de cada comando prevalece sobre su propia clave en ambos sentidos: --pin-sources=false desactiva el paso para una ejecución en un proyecto configurado para fijar. Un build que rellena su propio lockfile es un pull y sigue pin_sources_at_pull. Estas claves pertenecen al archivo del proyecto y no al global: que los pulls de un proyecto registren fijaciones es la política de ese proyecto, y un compañero de equipo que lo clona debería obtener la misma respuesta. pin_sources_at_pull es también la forma en que un proyecto que consume el catálogo sin fijar de otra persona registra esas fijaciones una sola vez en lugar de detenerse en cada pull.
Qué plugin renderiza una capability
Una Recipe nombra la capability a través de la cual se renderiza —capability: helm— y un plugin que sirve esa capability la renderiza. Donde exactamente un plugin sirve una capability, no hace falta configurar nada. Donde la sirve más de uno, una entrada de plugins.providers indica cuál, por la identidad del plugin:
# <project>/.aggrega-config.yamlworkspace: {}plugins: providers: - capability: helm uri: provider/helmUn pull resuelve la entrada y registra el plugin que eligió en el lockfile de la Release, y un build renderiza a través de lo que registra el lockfile, así que un cambio aquí surte efecto en el siguiente pull.
El campo uri nombra el plugin por su identidad, provider/<name>, nunca por el lugar donde está publicado. aggrega plugin add provider <query> --capability <capability> escribe la entrada de esa forma, sin versión: la entrada selecciona qué plugin sirve la capacidad, la versión es la que fija la Recipe o, en su defecto, la más alta disponible, y el lockfile registra la que eligió el pull. Un plugin que el compilador lleva incorporado se sirve en la versión del propio compilador, así que una versión escrita en una entrada para uno de ellos solo se resuelve cuando es esa versión. Una entrada cuyo uri es una ubicación de registro —oci://hub.aggrega.ai/plugin/provider/helm— no nombra la identidad de ningún plugin, y se rechaza cuando se carga el archivo, nombrando la entrada y la forma que escribir.
Las entradas se escriben una vez para todo el proyecto, mientras que un build es de una sola Release, así que una entrada para una capability que esta Release nunca solicita es legal —otra Release del proyecto la lee— y no se informa de ninguna manera. Lo que sí comprueban cada build y cada aggrega validate --release es cada entrada, la solicite o no una Recipe para su capability, según lo que nombra la entrada:
- Una entrada que nombra un plugin cuyo plugin no sirve su capability detiene el build y hace fallar la validación. Un pull resuelve cada entrada que nombra un plugin y rechaza la que no puede resolver, así que, una vez que una entrada ha pasado por un pull, el build tiene su plugin y sabe qué sirve; una entrada que nombra un plugin que el build aún no tiene se evalúa una vez que un pull lo ha obtenido. El mensaje nombra la entrada, el plugin, lo que ese plugin sí sirve y una grafía a una edición de distancia cuando la hay: la forma que adopta un error tipográfico como
hlemporhelm. - Una entrada que nombra solo una capability que ningún plugin leído por el build sirve es una advertencia, y el build continúa. El plugin que la sirve puede ser uno que solo lee otra Release, que este build no puede ver, y una entrada que no nombra ningún plugin no selecciona nada que la resolución de la capability no seleccionaría sin ella.
Una capability aquí nunca contiene dos puntos, y una que los contiene se rechaza al cargar el archivo. El capability: de una Recipe se lee como la capability hasta sus últimos dos puntos y una fijación de versión después de ellos, así que una entrada con la clave helm:1.0.0 nunca podría encontrarse. Fija la versión en el plugin —uri: provider/helm:1.0.0— o en la Recipe.
Qué importador convierte una fuente en borradores
aggrega import entrega una fuente al importador que anuncia el formato de la fuente: uno de tu catálogo o uno de los importadores principales del compilador, import:langflow para un flujo de Langflow. Donde exactamente un importador lo anuncia, no hace falta configurar nada. Una entrada de plugins.importer vincula un importador nombrándolo en su uri, por su identidad y versión, y le entrega lo que lleva bajo with:
# <project>/.aggrega-config.yamlworkspace: {}plugins: importer: - uri: importer/agent-flows:1.2.0 with: settings: target_namespace: paymentsaggrega plugin add importer escribe el uri exactamente de esa forma. La versión es exacta —:1.2.0— o un rango —:^1.2.0 para la versión más alta igual o superior a ella dentro de la misma versión mayor—. Escribe una u otro: en esta lista, un uri sin dos puntos se lee como una ruta del sistema de archivos, como describe Adónde apunta una ruta relativa, y no nombra ningún importador.
Lo que hace una entrada depende de si el importador que nombra anuncia el formato que solicita una importación:
- Lo anuncia: ese importador es el que se ejecuta, en la versión que nombra el
uri, por muchos otros importadores del catálogo que también anuncien el formato, y recibe loswith.sourcesywith.settingsde la entrada. Una entrada es la forma en que un workspace cuyo catálogo federa los importadores de dos publicadores para un mismo formato indica cuál de ellos usa. - No lo anuncia —nombra un importador de otro formato, un plugin de otro tipo o nada que tu catálogo contenga o que el compilador incluya—: la entrada no participa en esa importación. No elige nada, y su
withno se entrega a ningún importador. La configuración de una entrada solo llega al importador que nombra, de modo que un workspace que vincula un importador por formato configura cada uno sin que la configuración de uno llegue al otro.
Donde más de un importador anuncia el formato y ninguno de ellos está vinculado de forma única —ninguno lo está, o las entradas nombran a dos de ellos—, la importación se rechaza, nombrando los importadores entre los que no pudo elegir. Una entrada que nombra un importador que anuncia el formato, en una versión que ninguna de sus versiones del catálogo satisface —una versión exacta que el catálogo no contiene, o un rango en el que no cae ninguna de sus versiones—, también se rechaza, nombrando la versión, en lugar de ejecutar otra versión en su lugar; una versión que no es una versión en absoluto, como :latest, se rechaza por estar mal formada. Una entidad Plugin de uno de los importadores core del compilador sin ningún módulo junto a ella en su carpeta del catálogo no es candidata: en la versión propia del compilador se ejecuta en su lugar el importador core, y en cualquier otra versión la entidad sigue siendo candidata solo donde una entrada nombra exactamente esa versión o ningún importador de su nombre que pueda ejecutarse anuncia el formato, como describe Cuál se ejecuta junto a tus propios importadores.
Cada importador se vincula mediante una sola entrada. Dos entradas que nombran un mismo importador —la misma identidad, en una versión o en dos— se rechazan al cargar la configuración, sea cual sea el comando que la lea, nombrando ambas entradas y los archivos en los que se escribieron. La regla abarca cada archivo que contribuye a la lista: una entrada en el archivo global, una en el archivo de un proyecto, una bajo importer_append y una en el .aggrega-config-append-ci.yaml de un pipeline cuentan todas, así que pasar un importador a una nueva versión significa cambiar la versión en su única entrada. aggrega plugin add importer hace exactamente eso cuando la lista plugins.importer del archivo que escribe ya nombra el importador: pasa esa entrada a la versión que resolvió, conservando la posición de la entrada y su with, en lugar de añadir una segunda. No lee ninguna otra lista, así que un importador vinculado bajo importer_append, o en el .aggrega-config-append-ci.yaml de un pipeline, el comando lo vincula una segunda vez y el par se rechaza al cargar la configuración; cambia la versión de esa entrada donde está escrita. Una entrada cuyo uri es una ruta del sistema de archivos no nombra ningún importador y no se compara, y las listas plugins.governance y plugins.linter no están sujetas a la regla: un plugin puede vincularse a ellas más de una vez, cada vez con su propio with.
Los analizadores a través de los que lee una importación no necesitan ninguna entrada. Un importador lee su fuente —y una importación que no nombra ningún formato la reconoce— a través de un analizador para la sintaxis de la fuente: el que tu catálogo sirve para esa sintaxis y, para una sintaxis para la que tu catálogo no sirve ningún analizador, el que incluye el propio compilador, JSON entre ellos. Así, un workspace cuyo catálogo no contiene ningún analizador importa un flujo de Langflow o Flowise sin nada configurado. Ninguna lista vincula un analizador: un analizador que tu catálogo sirve para una sintaxis es el que se usa, y dos con nombres distintos que sirven una misma sintaxis se rechazan, como describe A parse or import format is advertised by more than one plugin (Un formato de análisis o de importación lo anuncia más de un plugin).
Empezar desde cero
Un aggrega recién instalado no tiene ninguno de los dos archivos, y ese es un estado funcional, no uno roto: cada configuración recurre a su valor predeterminado integrado y los comandos se ejecutan. Lo que falta es un registro del que hacer pull del contenido de catálogo, junto con la política de confianza que indica qué firmas aceptar, que es exactamente lo que escribe aggrega config init.
No necesitas saberlo de antemano. Un comando que lee su configuración y no encuentra ningún archivo en ninguna parte lo dice una vez, en la salida de error estándar, y nombra aggrega config init como la forma de crear uno. Es un consejo, no un fallo: la salida estándar no se toca, no se te pide nada y el código de salida es el que el comando habría informado de todos modos. Solo se escribe cuando la salida de error estándar es un terminal, de modo que te llega al teclado y nunca se acumula en el registro de un pipeline. En cuanto existe cualquiera de los dos archivos —el de tu proyecto o el global—, deja de aparecer.
Para inicializar el archivo global con el hub oficial y la política de confianza que anuncia ese hub:
aggrega config initPasa --registry <host> para inicializar otro distinto, --workspace para escribir la entrada en el archivo de este proyecto en lugar del global, y --dry-run para ver el contenido que escribiría sin crear nada. aggrega-config.md cubre el comando por completo.
Cómo se escribe un host de registro
Cada registries[].host nombra un host de registro. También lo hace default_registry —seguido opcionalmente de una ruta de repositorio—, a menos que nombre en su lugar una de esas entradas (consulta más abajo). Un host se escribe como el propio host, en la única grafía bajo la que se guarda la política de confianza del registro:
- un nombre de host en minúsculas que contiene un punto, como
registry.example.com; localhost, o un nombre único seguido de un puerto, comoregistry:5000;- una dirección IPv4 como
127.0.0.1, o una dirección IPv6 entre corchetes como[::1];
cada uno con un :port opcional, y nada más: sin esquema, sin ruta, sin credenciales, sin espacios en blanco y sin mayúsculas. Un nombre único sin puerto no es un host de registro, porque esa es la forma del primer segmento del nombre de una entidad de catálogo —el core de core/web-api—, y los dos nunca deben confundirse entre sí.
# <project>/.aggrega-config.yamlworkspace: {}default_registry: registry.example.comregistries: - host: registry.example.com signing: required: trueLa grafía forma parte de la política. Una entrada de registries se aplica al host que nombra su host:, y el requisito de firma integrado del hub oficial se aplica a hub.aggrega.ai, así que un host escrito de cualquier otra forma llegaría al registro correcto y no alcanzaría la política escrita para él. En su lugar, se rechaza al cargar la configuración, y el rechazo nombra la grafía que hay que escribir: HUB.AGGREGA.AI y https://registry.example.com se rechazan nombrando hub.aggrega.ai y registry.example.com, y también registry.example.com/charts como registries[].host, que no lleva ruta. El puerto 443 es el puerto predeterminado de un host al que se llega por HTTPS, así que hub.aggrega.ai:443 se rechaza de la misma manera, nombrando hub.aggrega.ai. A localhost y las demás direcciones de loopback se llega, en cambio, por HTTP simple, donde 443 es un puerto ordinario, así que localhost:443 se acepta tal como está escrito. Un default_registry vacío no nombra ningún registro predeterminado.
default_registry puede llevar una ruta de repositorio. Muchos registros guardan cada repositorio bajo un propietario o un proyecto —ghcr.io/<owner>, <host>/<project> en Harbor—, y un registro predeterminado en uno de ellos se escribe como el host seguido de esa ruta:
# <project>/.aggrega-config.yamlworkspace: {}default_registry: ghcr.io/acmeregistries: - host: ghcr.io signing: required: trueLa ruta es donde se publican y se obtienen las cosas. A través de este valor predeterminado, aggrega push publica core/api-server en la versión 1.0.0 en ghcr.io/acme/component/core/api-server:1.0.0, y un pull que resuelve core/api-server lo obtiene del mismo lugar, de modo que una firma adjuntada al publicarlo también se encuentra allí. La ruta es una ruta de repositorio en la gramática de distribución de OCI: uno o más segmentos de letras minúsculas y dígitos unidos por /, que pueden separarse dentro de un segmento con ., _, __ o guiones, sin etiqueta, digest ni / final.
La ruta nunca forma parte de cómo se confía en el registro. La entrada de registries cuya política se aplica, la credencial que almacena aggrega login, el requisito de firma y las identidades de confianza se encuentran todos solo por el host, así que la entrada para ghcr.io de arriba rige ghcr.io/acme y cualquier otra ruta en ese host, y ninguna grafía de una ruta puede sortearla; el propio host: de una entrada no lleva ruta. Un host escrito con otra grafía antes de una ruta se rechaza nombrando la ubicación que hay que escribir —GHCR.io/acme y https://ghcr.io/acme nombran ghcr.io/acme—, y lo que sigue al host cuando no es una ruta de repositorio se rechaza nombrando el host al que sigue.
default_registry puede, en cambio, nombrar una entrada. Escrito como el name: de una entrada bajo registries, representa el host: de esa entrada. La publicación, el pull, la verificación de firmas y cada configuración de confianza por registro usan entonces ese host, y no se obtiene ningún contenido de un host escrito como el nombre:
# <project>/.aggrega-config.yamlworkspace: {}default_registry: localregistries: - name: local host: 127.0.0.1:5000Un nombre se compara antes que una grafía de host, como lo hace el flag --registry, así que un valor que es el name: de una entrada representa esa entrada aunque también esté escrito como un host. Un nombre que llevan dos entradas se rechaza por ambiguo, nombrando ambos hosts. La entrada puede estar en cualquiera de los dos archivos —el default_registry de un proyecto puede nombrar una entrada que declara el archivo global—, porque el nombre se lee una sola vez, frente a las entradas vigentes después de haber leído cada archivo y el entorno. Un valor que no es ni el nombre de una entrada ni un host de registro —solo o seguido de una ruta de repositorio— se rechaza, y el rechazo indica que cualquiera de los dos lo corrige. Un nombre seguido de una ruta, como local/acme, también se rechaza: un nombre representa el host de su entrada y no una ubicación bajo él, así que el rechazo nombra en su lugar las dos grafías que hay que escribir: local, o el host de la entrada seguido de la ruta, 127.0.0.1:5000/acme. Eliminar una entrada con aggrega registry remove deja default_registry tal como está escrito, así que un valor predeterminado que nombraba la entrada eliminada ya no nombra nada después y se rechaza hasta que se reescribe.
Cada capa está sujeta a la misma grafía. Un valor se rechaza con las mismas palabras tanto si viene de un archivo de configuración, de AGGREGA_DEFAULT_REGISTRY o del flag --registry que nombra el destino de un aggrega push o un aggrega push-artifact. Ese flag nombra un host, y la publicación que dirige llega a ese host sin ruta de repositorio: una ruta pertenece a default_registry. aggrega registry add y aggrega config init --registry también someten a ella el host que reciben; además, aceptan una referencia en su lugar y registran la entrada bajo el host que nombra la referencia. Un rechazo procedente de un archivo nombra el archivo y la clave; uno procedente del entorno nombra la variable. El esquema establece la forma del host como un patrón en registries[].host y no establece ninguna en default_registry, cuyo valor puede ser el nombre de cualquier entrada, así que un editor que lee solo el esquema no marca un valor predeterminado mal escrito, y es la carga de la configuración la que lo rechaza.
Un host se juzga solo por su grafía, y una ruta también. Si el nombre se resuelve, si un registro responde allí o si la ruta existe en él no se comprueba al cargar la configuración.
Qué prevalece sobre qué
CLI flag > environment variable > configuration file > built-in defaultUn flag es la señal más explícita que existe y prevalece sin más. Una variable de entorno prevalece sobre el archivo confirmado, que es lo que permite a un pipeline cambiar una configuración sin editar un archivo versionado. Una variable no definida —o definida como cadena vacía— recurre a la capa inferior en lugar de vaciar un valor configurado. Entre los dos archivos, el archivo de tu proyecto prevalece sobre el global.
Un flag prevalece por haberse escrito, no por el valor que lleva, y para una configuración de verdadero o falso esa es la diferencia entre una capa superior utilizable y ninguna. --offline activa el modo para una ejecución; --offline=false lo desactiva para una ejecución donde un archivo confirmado o una variable exportada lo ha activado. Una capa que leyera solo el valor no podría distinguir «desactivado» de «no mencionado», de modo que cada comando parecería haber pedido el valor predeterminado del flag y no habría forma alguna de anular una configuración establecida.
Ese es todo el modelo para un solo proyecto en una sola máquina. Todo lo que sigue existe para los proyectos que lo superan.
Más allá de los dos archivos
Estos mecanismos están pensados para estructuras más grandes: un monorepo de proyectos relacionados, un pipeline que aporta configuraciones propias, un catálogo compartido que varios proyectos amplían. Recurre a uno cuando tengas el problema que resuelve.
Más de un archivo de configuración dentro de un proyecto
Cada .aggrega-config.yaml desde la raíz del proyecto hasta el directorio en el que se ejecuta el comando contribuye, y un archivo más cercano prevalece sobre uno más lejano. Así, un subproyecto puede llevar su propio archivo que ajusta lo que declaró la raíz, sin repetirlo.
Solo un archivo que lleva un bloque workspace: marca una raíz. Un archivo sin él sigue aportando sus configuraciones; simplemente no convierte su directorio en una raíz de proyecto, que es lo que impide que el archivo de configuración de un subproyecto redefina dónde empieza el proyecto.
Pasar --workspace-root cambia esto además de omitir el descubrimiento: el propio archivo de configuración de la raíz nombrada es el único que se recoge, así que los archivos de los directorios inferiores no contribuyen. Eso mantiene igual la configuración de una raíz fijada dondequiera que se ejecute el comando.
Cada archivo recogido de esta forma se lee desde dentro del proyecto. Uno que es un enlace simbólico que lleva fuera del proyecto —o que está en un directorio al que se llega a través de un enlace así— no se lee, y cada comando que lee la configuración se detiene en él, nombrando el enlace, en lugar de configurar el proyecto a partir de los archivos restantes; lo mismo vale para el archivo de un pipeline, más abajo. Los pocos comandos que nunca la leen, como aggrega version y aggrega help, se ejecutan con una advertencia que nombra el enlace. El servidor de lenguaje del editor y las herramientas de un asistente leen la configuración de la misma manera, y aun así se inician sobre un proyecto así para que pueda listarse: sus listados de Releases y de entidades responden, leídos sin nada configurado, y nombran el archivo entre los enlaces no leídos, mientras que cualquier otra solicitud que decide la configuración se detiene en él, nombrando el enlace. Una configuración mantenida fuera del proyecto se lee nombrándola como archivo global, como describe Nombrar explícitamente el archivo global. Consulta El límite del workspace.
Ampliar una lista en lugar de reemplazarla
Una configuración con valor de lista se comporta como cualquier otra configuración: el valor del archivo más cercano reemplaza al del más lejano. Cuando quieras añadir a lo que declaró un archivo exterior en lugar de volver a declararlo, usa el complemento de anexión que está junto a ella:
| configuración de lista | su complemento de anexión |
|---|---|
workspace.catalog_dirs | catalog_dirs_append |
plugins.governance | governance_append |
plugins.linter | linter_append |
plugins.importer | importer_append |
plugins.providers | providers_append |
Las entradas bajo un complemento se concatenan a la lista resuelta en cada capa en lugar de ocultarla, de modo que un subproyecto añade un linter a lo que la raíz ya declaró:
# <project>/services/api/.aggrega-config.yamlplugins: linter_append: - uri: ./lint/api-rules.wasmDonde un archivo establece tanto la lista base como su complemento, el valor de ese archivo es la lista base seguida de las entradas anexadas.
El bloque workspace: es la excepción en cuanto a dónde puede escribirse un complemento. Un archivo que lleva ese bloque marca su propio directorio como raíz del proyecto, así que el archivo de un subproyecto que escribiera workspace.catalog_dirs_append iniciaría un proyecto propio en lugar de añadir al que lo contiene. El complemento de directorios de catálogo se compone entre tu archivo global y el archivo raíz del proyecto.
La lista plugins.cli se compone por sí sola entre archivos y no tiene complemento: una extensión de comandos declarada en el archivo global registra su comando en cada proyecto, una declarada en un proyecto lo registra solo allí, y ambas se registran juntas. Cada entrada fija un plugin: el uri que resuelve y el digest de los bytes que verificó aggrega plugin add cli, escrito como sha256: seguido de 64 dígitos hexadecimales en minúsculas. Un digest con cualquier otra grafía nunca podría ser igual al digest que resulta del hash de los bytes resueltos, así que se rechaza al cargar el archivo, nombrando el archivo y la entrada.
Dar a una Release sus propios directorios de catálogo
Un proyecto puede mantener varias variantes de catálogo una al lado de otra —una por destino, cada una con las Recipes que renderizan los mismos Components para un proveedor distinto— y compilar cada Release con una de ellas. Nombra cada Release bajo workspace.releases y dale sus propios catalog_dirs:
# <project>/.aggrega-config.yamlworkspace: releases: release-compose.yaml: catalog_dirs: - ./catalog-compose release-helm.yaml: catalog_dirs: - ./catalog-helmCada clave es un archivo de Release, escrito de forma relativa al archivo de configuración que lo nombra. Una clave —como build.authoring_release— puede nombrar una Release mantenida fuera del proyecto, y nombrarla aquí es la forma en que un proyecto llega a ella: un enlace dentro del proyecto que lleva a ella se lee en lugar de omitirse, como describe El límite del workspace. Las dos claves que hay debajo significan lo mismo que en el bloque workspace:, limitadas a esa única Release:
catalog_dirsreemplaza la lista del workspace para esa Release. El orden de búsqueda, el directoriocatalogque se lee después y lo que indica una lista vacía son los mismos que para la lista propia del workspace.catalog_dirs_appendse lee después de la lista de la Release. Una entrada que escribe solocatalog_dirs_appendconserva la lista del workspace y le añade elementos.
Una Release que el mapa no nombra lee el workspace.catalog_dirs propio del workspace. Una Release que el mapa sí nombra lee sus propios directorios sea cual sea la forma en que se compile —aggrega build o aggrega pull en un terminal, el editor a través de aggrega serve, un asistente a través de aggrega mcp—, así que ninguno de ellos necesita un flag para encontrar su catálogo. Un --catalog <dir> en la línea de comandos se sigue buscando antes que los directorios de la Release, para esa única invocación. Y una búsqueda que no encuentra ninguna entidad con un nombre que usaste nombra la entrada de esa Release como el lugar donde listar el directorio que la contiene.
Una entrada que nombra un archivo que no existe se rechaza al cargar la configuración, nombrando la entrada y el archivo. Por tanto, renombrar una Release detiene cada comando hasta que la entrada se renombra con ella, en lugar de dejar que la Release se compile con la lista del workspace sin que nada lo indique. Un directorio que enumera una entrada debe ser un directorio, como debe serlo uno que nombra la lista del workspace: uno que no lo es lo rechaza cada comando que lee el catálogo de esa Release, nombrando la entrada y su línea.
Lo que no concierne a ninguna Release concreta sigue leyendo la lista del workspace: un lint o una validación de todo el catálogo, una búsqueda de una entidad por nombre, un Aggregate inspeccionado por sí solo y el listado de las entidades del workspace en un editor. AGGREGA_CATALOG_DIRS establece la lista del workspace y no llega a ninguna entrada de aquí, y un archivo de configuración propiedad de tu pipeline no lee el mapa en absoluto.
Un archivo de configuración propiedad de tu pipeline
Un archivo llamado .aggrega-config-append-ci.yaml puede estar junto al archivo escrito a mano en cualquier directorio que visite el recorrido. Es un archivo aparte para que un pipeline automatizado pueda ser su dueño y sobrescribirlo por completo sin tocar nunca lo que escribió una persona.
Es solo aditivo. Sus entradas para las cinco configuraciones de lista anteriores se concatenan a las listas resueltas; no puede eliminar nada ni prevalecer sobre un escalar. Una clave escalar o de mapa escrita en él no tiene significado aditivo, así que se ignora y se nombra en una advertencia en lugar de aplicarse en silencio. Tampoco marca nunca una raíz de proyecto, así que colocar uno en un directorio añade vinculaciones sin mover el lugar donde empieza el proyecto.
Adónde apunta una ruta relativa
Una ruta relativa del sistema de archivos se resuelve respecto al directorio del archivo que la declaró, no respecto a la raíz del proyecto ni respecto al directorio desde el que ejecutaste el comando. Esta es la regla que vale la pena leer dos veces, porque una ruta que parece relativa al proyecto se resuelve en otro lugar y el build tiene éxito igualmente, con un contenido que no pretendías.
Se aplica a workspace.catalog_dirs, a los archivos de Release que figuran como claves bajo workspace.releases y a los directorios que lista cada entrada, a las rutas del sistema de archivos local de una vinculación de plugins.governance o plugins.linter —un uri que nombra un archivo .wasm en disco, y cada entrada bajo el with.sources de esa vinculación— y a cada entrada bajo el with.sources de una vinculación de plugins.importer. En las tres listas, un uri sin dos puntos que no nombra ningún registro —tanto importer/agent-flows como ./lint/api-rules.wasm— es una ruta así, mientras que un uri que nombra un plugin por su identidad lleva la versión después de dos puntos, importer/agent-flows:1.2.0, y se deja exactamente como está escrito. El uri de una vinculación de importador nombra el importador que vincula, como describe Qué importador convierte una fuente en borradores; una importación no lee ningún módulo desde una ruta escrita allí. La regla se aplica también a las entradas bajo los complementos de anexión, y cada una de ellas se ancla a su propio archivo declarante y no al archivo en el que termina la fusión. Y se aplica a mcp.tls.cert_file, mcp.tls.key_file y mcp.authorization.jwks_file, de modo que un archivo junto al que lo nombra se encuentra dondequiera que se inicie el servidor.
Así, dada esta estructura:
myproject/├── .aggrega-config.yaml└── services/ ├── .aggrega-config.yaml └── catalog/y ./catalog escrito en el archivo raíz, la ruta nombra myproject/catalog. Escrito en services/.aggrega-config.yaml, el texto idéntico nombra myproject/services/catalog. Una ruta absoluta se deja exactamente como está escrita, y también una referencia de registro como oci://hub.aggrega.ai/plugins/helm:1.0.0.
Estas configuraciones no siguen deliberadamente esta regla, porque no tienen un archivo declarante al que anclarse o porque cada uno de sus lectores las resuelve en otro lugar:
artifact_cache_dirse interpreta de forma relativa a la raíz del proyecto, dondequiera que se ejecute el comando, de modo que la caché es un único directorio y no uno por cada ubicación de invocación. Un valor absoluto se rechaza al cargar la configuración.AGGREGA_CATALOG_DIRSviene del entorno y no tiene ningún archivo declarante, así que proporciona rutas absolutas en ella.mcp.listense toma exactamente como está escrito, y eso incluye la ruta del sistema de archivos en su formaunix:<path>. La misma dirección llega también desdeaggrega mcp --listen, que no tiene archivo declarante, así que anclar solo la grafía configurada haría que una misma cadena nombrara dos lugares distintos según su procedencia. Da al socket una ruta absoluta.
Una configuración cuyo almacén es compartido
Casi cada configuración rige algo que pertenece al proyecto en el que trabajas: a través de qué directorios resuelve el contenido de catálogo, qué plugins renderizan sus destinos, con qué rigor se juzga su contenido, cuánto pueden crecer las cachés en memoria del daemon. Un valor en el archivo de un proyecto rige lo propio de ese proyecto, y no hay nada que vigilar.
compiled_module_cache.max_bytes es la única excepción, porque lo que limita no es por proyecto. El código compilado de los plugins se guarda en un único directorio que reutiliza cada proyecto de tu máquina, de modo que un plugin dado se compila una vez y no una vez por proyecto. El límite en sí se resuelve como cualquier otra configuración —escríbelo en el archivo de un proyecto y ese valor prevalece para ese proyecto—, pero el almacén sigue teniendo un solo tamaño, y el tamaño vigente es el del build más reciente. Dos proyectos que lo limitan de forma distinta surten efecto ambos por turnos, y el límite más bajo descarta código compilado que el otro proyecto pagó.
Así que ponlo en el archivo global cuando quieras una sola respuesta para todo lo que compilas, y mantenlo por encima de lo que compila un solo build. aggrega cache status informa de lo que contiene actualmente el almacén, y aggrega config show --origin te indica de qué archivo procede realmente el límite bajo el que te estás ejecutando.
Configuración para un servidor al que acceden otras personas
aggrega mcp habla el Model Context Protocol. En tu propia máquina, un cliente lo lanza como subproceso y se comunica con él a través de la entrada y la salida estándar, que es lo predeterminado, y las únicas configuraciones que lee esa forma son mcp.transport, dejada en ese valor predeterminado, y mcp.announce_tools. El resto del bloque mcp es para la otra forma, la que elige mcp.transport: http: un único proceso de larga duración en un host, al que acceden por HTTP llamantes que no están ante su teclado.
# <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 es lo que elige el transporte. http inicia un listener; stdio, el predeterminado, se comunica por la entrada y la salida estándar, que es lo que espera un cliente subproceso. Cualquier otro valor se rechaza al cargar este archivo. aggrega mcp --transport <stdio|http> hace lo mismo para una sola invocación y prevalece sobre la clave, del mismo modo que cada flag prevalece sobre cada archivo.
mcp.listen nombra dónde se enlaza ese listener, y no elige nada. Dale una dirección host:port o un socket unix:<path>; aggrega mcp --listen <address> prevalece sobre ella para una sola invocación. Con http elegido y ninguna dirección procedente de ninguno de los dos, el lanzamiento se rechaza antes de que nada se enlace. Con stdio elegido, un --listen escrito se rechaza, y una dirección que solo nombra esta clave queda sin usar: el servidor lo dice en una línea en su flujo de error, nombrando este archivo y mcp.transport: http. Así que un servidor al que acceden otras personas establece ambas claves, como arriba, y un cliente lanzado desde un directorio que cubre ese archivo sigue llegando al servidor por sus propios flujos. Una ruta unix: se toma tal como está escrita en lugar de anclarse; consulta Adónde apunta una ruta relativa.
mcp.tls.cert_file y mcp.tls.key_file ponen TLS en el proceso. Establece ambos y el listener sirve HTTPS por sí mismo. Omite ambos y sirve texto sin cifrar, que solo se acepta en loopback o en un socket Unix: la forma que usas cuando un proxy situado delante tiene el certificado y reenvía al proceso. Un listener sin cifrar en cualquier otra dirección se rechaza antes de que nada se enlace, nombrando estas dos claves, y lo mismo ocurre si uno de los dos se establece sin el otro. Ambos son rutas del sistema de archivos y siguen la regla anterior: una relativa se resuelve respecto al directorio del archivo que la declaró, de modo que un certificado confirmado junto a ese archivo se encuentra dondequiera que se inicie el servidor. Escríbelos como absolutos donde el certificado se gestione fuera del proyecto.
mcp.authorization.issuer y mcp.authorization.resource indican quién emite los tokens que presentan los llamadores y cómo se llama este servidor como el recurso para el que se emiten. Ambos son obligatorios siempre que se elige el transporte http, y sin ellos un listener se rechaza antes de que nada se enlace, porque a cada solicitud al endpoint se responde con un desafío bearer-token, y un desafío que no indica adónde ir es uno sobre el que un cliente no puede actuar. Escribe direcciones completas, con esquema y host incluidos: el issuer exactamente como ese servidor de autorización declara su propio identificador, y el recurso como la dirección que tus llamadores alcanzan realmente — el host que presenta un proxy situado delante, donde lo haya, en lugar de la dirección a la que se enlaza este proceso. Ambos se publican, sin pedir ninguna credencial, en el documento de metadatos OAuth del recurso protegido que sirve el listener, que es donde un cliente busca dónde obtener un token. Ninguno contiene nada secreto: un token llega con la solicitud que lo presenta y nunca se escribe en un archivo de configuración. El issuer es una dirección https a menos que el servidor de autorización se ejecute en esta máquina — localhost, 127.0.0.1 o ::1 —, y un listener que indica un issuer http sin cifrar en cualquier otro host se rechaza antes de que nada se enlace, sea cual sea la forma en que lee sus claves y sus llamadores: cada cliente se envía al issuer para obtener su token, así que sobre http sin cifrar su código de autorización y su token cruzarían la red sin protección, y donde las claves también se leen de allí, cualquiera que esté en esa ruta podría sustituirlas.
mcp.authorization.jwks_file indica un archivo que contiene las claves con las que se verifican los tokens, en lugar de leerlas del servidor de autorización. Si lo omites, el servidor lee los metadatos de ese servidor en su dirección well-known y sigue el jwks_uri publicado allí, que es lo que hace un workspace con acceso a la red. Esa dirección de claves está sujeta a la misma regla que el issuer, y también lo está cualquier dirección a la que se redirija cualquiera de las dos lecturas: una que sea http sin cifrar en otro host nunca se consulta, y a un token que necesita esas claves se le responde 503 hasta que el servidor de autorización publique sus metadatos y sus claves sobre https. Si lo estableces, el servidor de autorización nunca se contacta — que es lo que necesita un workspace que declara offline: true, y un workspace así se rechaza antes de que su listener se enlace a menos que esta clave indique un archivo. Es una ruta y sigue la regla anterior: una relativa se resuelve respecto al directorio del archivo que la declaró, así que un conjunto de claves confirmado junto a ese archivo se encuentra desde dondequiera que se inicie el servidor. El archivo contiene claves públicas de verificación, que son lo que publica un servidor de autorización — nada que firme y nada secreto.
mcp.allowed_origins solo se consulta cuando una solicitud lleva un encabezado Origin, lo que en la práctica significa que la envió un navegador. Enumera allí los orígenes que sirves; una solicitud que indica uno que no está en la lista se rechaza, y una solicitud sin ese encabezado se sirve de todos modos. Un cliente que no es un navegador no envía ese encabezado y no necesita ninguna entrada. Una entrada se compara exactamente con el encabezado, así que escríbela como la envía un navegador: un esquema en minúsculas, ://, un host en minúsculas y : con el puerto solo donde el puerto no es el predeterminado del esquema — https://studio.example.com, o http://localhost:3000 para una página servida en tu propia máquina —, sin ruta y sin / final. Una entrada con cualquier otra forma nunca podría coincidir, y se rechaza al cargar este archivo, indicando la entrada.
mcp.limits acota lo que un llamador puede pedir — qué tamaño puede tener el cuerpo de una sola solicitud, cuántas solicitudes se ejecutan a la vez y cuántas puede enviar un llamador en un minuto. Los tres están siempre en vigor; ninguno tiene un valor que lo elimine. El tercero, requests_per_minute, se cuenta por separado para cada llamador, así que un llamador que envía mucho no le cuesta nada a otro.
mcp.authorization.trusted_proxy toma el llamador de un proxy situado delante en lugar de verificar un token aquí. Establece principal_header en el encabezado que ese proxy usa para indicar quién es el llamador y, opcionalmente, scopes_header en uno que lleve los scopes de ese llamador. Ambos son nombres de encabezado HTTP, como X-Forwarded-User — letras, dígitos, guiones y los pocos caracteres más que puede contener un nombre de encabezado, sin espacios ni dos puntos —, y un nombre con cualquier otra forma se rechaza al cargar este archivo, indicando la clave, porque ninguna solicitud podría llevarlo. En ese modo no se lee ningún token, y una solicitud sin el encabezado del principal se rechaza. Como el encabezado es entonces toda la credencial, solo es fiable donde nada más puede establecerlo: el proceso se rechaza antes de enlazarse a menos que mcp.listen sea loopback o un socket Unix. Si omites el bloque, este servidor verifica los tokens por sí mismo, que es el comportamiento predeterminado; un bloque cuyo principal_header está vacío se rechaza en lugar de leerse como ese comportamiento predeterminado.
mcp.deny_reach retira un tipo de alcance de este despliegue. Cada operación que realiza el servidor declara hasta dónde llegan sus propios efectos — none para una que lee o renderiza y no deja nada atrás, workspace para una que escribe dentro del workspace que sirve este proceso, registry para una que publica, firma o retira, y machine para una que cambia lo que comparten todos los workspaces del host. Indicar aquí un tipo retira toda herramienta que lo alcance: la herramienta no aparece en la lista de herramientas de ningún llamador, lleve lo que lleve su token, y una llamada a ella se rechaza indicando este ajuste. Eso lo convierte en el límite del despliegue y no del llamador, y ninguna credencial lo elimina — un servidor pensado para servir lecturas y nada más enumera aquí los tres tipos que escriben y entonces no puede publicar ni siquiera para un llamador cuyo token lleve todos los scopes. Si lo omites, que es el comportamiento predeterminado, este despliegue ofrece todo lo que admiten los scopes de sus llamadores. Un valor que no sea uno de los cuatro se rechaza al cargar este archivo, en lugar de pasarse por alto. Nada del tipo machine se ofrece por HTTP, diga lo que diga este ajuste, así que indicarlo se acepta y no cambia nada; aggrega-mcp.md expone los tipos y los scopes que los admiten.
mcp.announce_tools restringe lo que anuncia el servidor, y es un límite distinto de la clave anterior. Indica las herramientas que anuncia este servidor, escritas como las informa la lista de herramientas, y se anuncian exactamente esas: una omitida no aparece en la lista de herramientas de ningún llamador y, si aun así se llama por su nombre, se rechaza indicando este ajuste. Si omites la clave — el comportamiento predeterminado —, se anuncia cada herramienta que ofrece el servidor; si escribes una lista vacía, no se anuncia ninguna, así que esas dos escrituras son afirmaciones distintas y no se rellena ningún valor predeterminado por ti. Lo que la distingue de deny_reach es lo que cada una quita. deny_reach quita una capacidad: las operaciones de un tipo retirado no se ofrecen aquí en absoluto y ninguna credencial devuelve ninguna. announce_tools solo quita un anuncio — las herramientas que omite son capacidades que el servidor sigue teniendo —, y responde a un cliente que limita cuántas herramientas registrará, a veces entre todos los servidores a los que está conectado a la vez. Donde ambas están establecidas, prevalece la retirada, así que una herramienta de un tipo retirado sigue ausente como sea que esta clave la indique. Un nombre al que no responde ninguna herramienta detiene el servidor antes de que sirva nada, enumerando las herramientas que sí tiene, en lugar de dejarte con una superficie más estrecha que la que pediste. A diferencia de las demás claves de aquí, que configuran el listener que inicia el transporte http, se lee sea cual sea el transporte que habla el servidor, porque el cliente para el que existe una restricción suele ser el que inició el proceso a través de su propia entrada y salida estándar; aggrega-mcp.md expone el resto.
mcp.health.listen coloca las comprobaciones de liveness y readiness en una dirección propia. Dale una dirección en cualquiera de las dos formas de mcp.listen y un segundo listener responde allí a GET /healthz — 200 desde el momento en que el proceso está en ejecución — y a GET /readyz — 503 hasta que el workspace se ha resuelto y el endpoint se ha enlazado, 200 a partir de entonces, que es lo que permite a un balanceador retener el tráfico hasta que el proceso pueda realmente responder a una llamada. Si la omites, ninguna de las dos comprobaciones se responde en ningún sitio. Nunca se responden en la dirección que indica mcp.listen, que les da el 404 que da a cada ruta que no sirve: una sonda allí sería una lectura no autenticada de un listener que rechaza todo lo demás. A diferencia de mcp.listen, esta dirección no está restringida y no se rechaza ninguna dirección para ella — apúntala a loopback o a un socket Unix, que es lo que alcanza un supervisor junto a este proceso, y ten en cuenta que cualquier cosa que pueda alcanzar la dirección que elijas puede leer esas dos respuestas.
schema/other/aggrega-config.md indica cada una de estas claves junto con su valor predeterminado, donde lo tiene.
Las otras formas en que se reconoce la raíz de un proyecto
--workspace-root <path>, o su equivalente AGGREGA_WORKSPACE_ROOT, indica la raíz directamente y omite el descubrimiento. La carpeta que indica debe existir: una ruta que no indica nada, o que indica un archivo, se rechaza antes de que el comando haga cualquier otra cosa, y el rechazo nombra cuál de los dos aportó el valor y lo cita tal como se dio. De lo contrario, el descubrimiento sube desde el directorio de trabajo, y los tipos de ancla se ordenan entre sí en lugar de por cercanía:
- Un
.aggrega-config.yamlque lleva un bloqueworkspace:prevalece sin más, a cualquier profundidad que esté. El recorrido sigue subiendo para buscar uno incluso después de haber pasado un marcador del tipo de abajo, así que una raíz marcada explícitamente más arriba siempre gana a un marcador fortuito situado debajo. - En su defecto, el más cercano de estos marcadores ancla la raíz, y dentro de un mismo directorio se ordenan así: un directorio
.aggrega/, luego unaggregate*.yaml, luego unrelease*.yaml, luego unmanifest*.yaml. - Si todo lo demás falla, se usa el directorio de trabajo — los comandos se ejecutan en lugar de negarse a arrancar. Un comando cuyo resultado depende del espacio de trabajo —uno que lee o escribe los documentos del espacio de trabajo, lee o llena su caché de artefactos, o lo sirve— avisa una vez por la salida de error estándar:
warning: <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace. Un comando cuyo resultado no depende de qué carpeta es la raíz no dice nada, aunque lea la configuración: entre ellosaggrega version,aggrega config show,aggrega plugin list,aggrega registry list,aggrega explainyaggrega login.aggrega config capture, cuyo trabajo es escribir el propio archivo de configuración del espacio de trabajo, no escribe nada en una carpeta así y termina con un error que lo indica.
En una carpeta así no se escribe nada en una caché de artefactos. Un directorio .aggrega/ es en sí mismo uno de los marcadores anteriores, así que una caché escrita allí convertiría la carpeta en un workspace solo porque alguna vez se obtuvo algo en ella. Un comando cuyo trabajo llena la caché — aggrega pull, una compilación que primero resuelve sus dependencias, aggrega registry update, añadir un plugin de extensión de comandos desde un registro — se rechaza antes de obtener nada, nombrando la carpeta y las dos alternativas: indicar el workspace con --workspace-root o AGGREGA_WORKSPACE_ROOT, o dar a la carpeta un .aggrega-config.yaml que lleve un bloque workspace:. aggrega pin, y aggrega push de una Recipe o una FeatureRecipe, sujeto a los pins que registra el entity.lock junto a ella, solo llenan la caché con las fuentes remotas que la entidad escribe por completo, que obtiene el fijado de una de ellas o la comparación de su pin: se rechazan de la misma forma donde obtendrían una fuente así, antes de obtenerla. Una entidad sin una fuente así — sin ninguna fuente, con una local, o con una cuyas coordenadas rellena cada Release — se fija o se publica allí como en cualquier otro sitio. Una compilación allí no se rechaza, pero una entrada externa que su lockfile fija y que la caché ya no contiene no se vuelve a obtener para repararla: al renderizado se le comunica la misma frase en lugar de esa entrada, del mismo modo en que se le comunica la de la postura sin conexión, y la notifica. Dónde coloque artifact_cache_dir la caché no cambia nada aquí, porque el directorio se une a la raíz que se haya encontrado. Los comandos que solo leen siguen respondiendo.
Ese último recurso tiene una excepción. Cuando nada ha indicado la raíz y el directorio de trabajo no ancla nada, un comando sobre una Release o un documento de entidad que indica ese archivo con una ruta absoluta vuelve a descubrir la raíz, subiendo desde la carpeta en la que está el archivo, y usa lo que encuentre: el workspace al que pertenece el archivo o, si todo falla, esa carpeta. El archivo es el que indica --release en aggrega build y aggrega pull; la Release que se da a aggrega validate, aggrega lint y aggrega inspect, o en su defecto el archivo que se les da; y el documento que se da a aggrega pin, aggrega push y aggrega edit-document. Así, la Release de un proyecto compilada desde fuera del proyecto lee la configuración propia del proyecto, como lo hace cuando el comando se ejecuta dentro de él, y las advertencias de configuración que imprime el comando son las de ese workspace. Donde la propia carpeta del archivo tampoco ancla nada, esa carpeta es la que nombra el aviso del comando y aquella en la que no se escribe ninguna caché. Una ruta relativa se lee respecto al directorio en el que ejecutas el comando y no cambia nada, y una raíz indicada, o un directorio de trabajo que está a su vez dentro de un workspace, se usa tal cual. El servidor del asistente aplica la misma regla a una llamada que indica su Release o su documento con una ruta absoluta.
Marcar la raíz con un bloque workspace: es la opción explícita y la que conviene preferir; los marcadores de archivo y de directorio permiten compilar igualmente un proyecto que no ha declarado ninguno.
Indicar explícitamente el archivo global
La capa global se resuelve en este orden:
--config <path>, la forma para una sola invocación.- La variable de entorno
AGGREGA_CONFIG. - La ubicación predeterminada: en Windows,
aggrega\config.yamldentro del directorio que indica la variable de entornoAPPDATA, y en otros sistemasaggrega/config.yamldentro del directorio que indicaXDG_CONFIG_HOME, con~/.config/aggrega/config.yamlcomo alternativa.
Las dos primeras indican un archivo explícito, así que una ruta que no existe es un error visible en lugar de una alternativa silenciosa — pediste un archivo concreto. Un comando que lee su configuración se detiene con una frase que termina con la ruta, para que puedas copiarla. aggrega config init es la excepción, porque crear ese archivo es su propósito: crea el archivo indicado y lo dice. La ubicación predeterminada se carga cuando el archivo está allí y se omite en silencio cuando no lo está. Sea cual sea el archivo que se resuelva, los archivos de tu proyecto siguen superponiéndose a él.
Cuando ninguna de estas se resuelve — no se indica ningún archivo y las variables de las que se lee la ubicación predeterminada no están establecidas —, un comando que escribe el archivo global se detiene e indica qué establecer. Variables de entorno enumera, por plataforma, las variables de las que se lee cada ubicación.
Esa elección también selecciona dónde escribe un comando que escribe la configuración. Un comando ejecutado con --config <path> lee su configuración de ese archivo y aplica su cambio a ese mismo archivo, así que lo que escribe un comando es lo que el siguiente vuelve a leer.
En cuál de los dos archivos escribe un comando de forma predeterminada depende de la naturaleza del ajuste: las herramientas de toda la máquina, como un registro, van al archivo global, mientras que los ajustes que participan en la compilación, como un enlace de provider o una conexión a un socket, van al archivo confirmado del proyecto, para que viajen con el proyecto. Pasa --global o --workspace para cambiarlo, y el comando imprime el archivo en el que escribió.
Véase también
- aggrega-config.md — los comandos
aggrega configque inicializan, inspeccionan y congelan la configuración. - environment-variables.md — cada variable con el prefijo
AGGREGA_, y dónde se suministran los secretos. - global-flags.md —
--config,--workspace-rooty los demás flags que acepta cada subcomando. - schema/other/aggrega-config.md — cada clave de configuración, su tipo y su valor predeterminado.
- aggrega-cache.md — lo que contiene realmente
artifact_cache_dir. - workspace-boundary.md — qué rutas quedan dentro del workspace y cómo los directorios y archivos que indica esta configuración llegan fuera de él.
- aggrega-mcp.md — el servidor que configura el bloque
mcp.