Configuração
De onde o aggrega lê suas configurações e em qual arquivo colocar uma configuração.
O caso simples
Dois arquivos, e a maioria dos projetos não precisa de mais nada.
Um arquivo no seu projeto, chamado .aggrega-config.yaml, localizado na raiz do projeto. Ele define como este projeto é compilado: quais diretórios contêm conteúdo de catálogo incluído no projeto, quais plugins renderizam quais destinos, quais regras de lint são relaxadas, para onde vai o cache local. Ele é commitado, de modo que um colega que clona o projeto o compila da mesma forma.
O bloco workspace: dele é o que marca o diretório como raiz do projeto:
# <project>/.aggrega-config.yamlworkspace: catalog_dirs: - ./catalogauto_pull: trueO bloco contém apenas os diretórios de catálogo que definem a raiz; todas as outras configurações ficam no nível superior, ao lado dele. Um projeto que não inclui conteúdo de catálogo ainda assim escreve o bloco, vazio — workspace: {} —, porque a presença do bloco é a marca.
Um arquivo global na sua máquina, em ~/.config/aggrega/config.yaml — no Windows, em aggrega\config.yaml dentro do diretório indicado pela variável de ambiente APPDATA. Todo workspace nessa máquina é resolvido por meio dele, e ele contém configurações que pertencem à máquina e não a um projeto específico — os registries de onde você faz pull e a política de confiança de assinaturas de cada um, quanto o armazenamento de módulos compilados pode crescer e qualquer plugin de extensão de comandos que você tenha instalado. Essas configurações são as mesmas onde quer que você esteja trabalhando, então declará-las uma vez é justamente o objetivo. Ele é carregado automaticamente quando existe, e nada quebra quando não existe.
registries: - host: hub.aggrega.ai signing: required: trueaggrega config init escreve esse arquivo global para você, registrando um registry junto com a política de confiança de assinaturas que ele anuncia, e informa onde o arquivo está na sua máquina e onde ficam os caches de toda a máquina. aggrega config show imprime o que se aplica neste momento, e aggrega config show --origin informa qual arquivo — ou qual variável de ambiente — decidiu cada configuração.
Segredos não são configuração. Uma senha de registry e um token de identidade de assinatura nunca são campos em nenhum dos dois arquivos; eles são fornecidos por variável de ambiente ou flag no momento em que são necessários. Consulte environment-variables.md.
De onde as entidades locais são lidas
Um projeto que mantém conteúdo de catálogo próprio — um Component, uma Feature, uma Recipe, um dos tipos de biblioteca — tem duas maneiras de dizer onde esse conteúdo fica, e a primeira não precisa de nenhuma configuração.
Um diretório catalog na raiz do projeto é lido, quer algo o nomeie ou não. Coloque uma entidade em <project>/catalog/ e todo comando que carrega um catálogo a lê, inclusive em um projeto cujo bloco workspace: está vazio. Um diretório de catálogo é lido recursivamente, então a forma como você organiza os subdiretórios dentro dele fica a seu critério.
Os diretórios listados em workspace.catalog_dirs também são lidos, e são lidos primeiro. A lista é uma pilha de busca ordenada: o primeiro diretório que declara uma identidade é o dono dela, e a mesma identidade em um diretório posterior fica sombreada. catalog é lido depois de tudo o que está listado — a menos que um diretório listado já o contenha, caso em que ele é lido como parte desse diretório —, então listar um diretório se soma ao que você tinha em vez de substituí-lo. Um --catalog <dir> repetível na linha de comando é lido antes de ambos, e um caminho relativo informado ali é resolvido em relação ao diretório a partir do qual você executou o comando, já que nenhum arquivo de configuração o declarou. Um diretório nomeado mais de uma vez — na linha de comando e na lista, ou duas vezes na lista — é lido uma vez, no lugar em que foi nomeado primeiro, de modo que nada dentro dele é relatado como sombreado por si mesmo: um sombreamento é sempre dois arquivos diferentes declarando uma mesma identidade. Duas grafias de um mesmo diretório, um caminho até ele através de um link e — em um sistema de arquivos que ignora maiúsculas e minúsculas — uma grafia com outra capitalização nomeiam todas esse único diretório. Um diretório dentro de outro diretório listado ainda é lido como uma entrada própria. Um projeto que mantém uma variante de catálogo por Release pode, em vez disso, dar a cada Release uma lista própria — consulte Dar a uma Release seus próprios diretórios de catálogo.
Listar um diretório é a forma como um projeto lê entidades mantidas fora dele. Um diretório listado pode estar em qualquer lugar — um checkout vizinho, um diretório compartilhado com outros projetos — e é lido onde está, mesmo quando ele próprio é um link simbólico. Nada mais vai tão longe: um link dentro do projeto que leva a outro lugar não é seguido, e um documento que nomeia um arquivo fora do projeto por um caminho é recusado, então uma entidade mantida em outro lugar é alcançada listando o diretório que a contém e nomeando a entidade pelo nome. Um diretório listado fora do projeto é uma raiz própria, então um link abaixo dele que sai dele também não é lido. O limite do workspace apresenta a regra completa.
Um diretório listado precisa ser um diretório. Um caminho listado onde nada existe, ou onde há um arquivo ou um link que não leva a lugar nenhum, é recusado antes que qualquer coisa seja lida ou gravada por todo comando que lê o catálogo — um pull, um build, uma validação, uma inspeção, um lint, e as mesmas operações acionadas a partir do editor por meio de aggrega serve ou de um assistente por meio de aggrega mcp —, de modo que um build nunca é executado com menos catálogos do que você listou. A recusa nomeia a entrada como foi escrita, o caminho em que ela se resolveu, o arquivo de configuração e a linha que a listam, e a lista em que ela 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 invalidCrie o diretório ou remova a entrada: uma cópia de um projeto feita sem um checkout vizinho que ele lista remove essa entrada, e resolve a partir de um registry o que o checkout teria fornecido. O mesmo vale para um diretório listado pela entrada própria de uma Release, para um que um arquivo de configuração da sua pipeline ou o arquivo global adiciona, e para um que AGGREGA_CATALOG_DIRS contém, que a recusa nomeia no lugar de um arquivo. A configuração em si continua sendo carregada, de modo que um comando que não lê nenhum catálogo continua sendo executado. Um diretório --catalog que não existe foi digitado para um único comando, e aggrega build o recusa, nomeando o diretório. Um diretório listado que existe e não pode ser lido é recusado pelos comandos que carregam o catálogo inteiro, que o nomeiam.
Escrever a lista vazia diz que este projeto não tem nenhum catálogo local, e é a única grafia que impede também que catalog seja lido:
# <project>/.aggrega-config.yamlworkspace: catalog_dirs: []Omitir a chave é uma afirmação diferente: uma lista omitida é o caso comum, e catalog continua sendo lido.
Um build, um pull, uma validação ou um aggrega inspect que não encontra nenhuma entidade com um nome que você usou diz de onde este projeto lê entidades locais e o que mudar para que aquela que você nomeou seja lida. Ele não diz nada do tipo onde você escreveu a lista vazia — não ler nenhum catálogo local é o que você declarou ali, e sugerir mudar isso seria contradizer você. Tampouco diz isso onde o documento que declara esse nome foi lido e recusado: esse documento já está onde o catálogo lê, então o relatório nomeia, em vez disso, o que o documento viola, a linha e a restrição, e movê-lo não resolveria nada. Um documento malformado demais para que o nome que declara possa sequer ser lido não pode ser associado ao nome que você usou, então a explicação é dada mesmo assim — e, quando esse documento declara uma apiVersion do Aggrega, um build, um pull ou uma validação de uma Release o nomeia ao lado da explicação, com o motivo dado pelo próprio parser, já que ele pode ser o arquivo a abrir. Uma falha que encontrou a entidade e não pôde aceitá-la — um registry que agora serve outros bytes sob uma versão que seu lockfile fixa, um arquivo que a entidade carrega e que não pode ser lido — também não é uma entidade ausente, e informa apenas a própria solução.
Se um pull ou um push fixa uma entidade
Uma Recipe ou FeatureRecipe carrega os pins das entradas que lê — um source: remoto escrito por completo, um arquivo que uma entrada de artifacts importa, os arquivos de um source: ao lado dela — no entity.lock ao lado dela, e registrá-los é o passo do autor da entidade, aggrega pin. Por padrão, nem pull nem push executa esse passo: um pull para em uma entidade que o lock dela não fixa, e um push se recusa a publicá-la. Duas chaves, uma por comando, tornam a execução desse passo o padrão daquele comando:
# <project>/.aggrega-config.yamlworkspace: {}pin_sources_at_pull: truepin_sources_at_push: trueCada chave governa o próprio comando e nada mais, e o --pin-sources de cada comando sobrepõe a própria chave nos dois sentidos — --pin-sources=false desativa o passo para uma execução em um projeto configurado para fixar. Um build que preenche o próprio lockfile é um pull e segue pin_sources_at_pull. Essas chaves pertencem ao arquivo do projeto e não ao global: se os pulls de um projeto registram pins é a política desse projeto, e um colega que o clona deve obter a mesma resposta. pin_sources_at_pull também é a forma como um projeto que consome o catálogo não fixado de outra pessoa registra esses pins uma vez, em vez de parar a cada pull.
Qual plugin renderiza uma capability
Uma Recipe nomeia a capability por meio da qual renderiza — capability: helm — e um plugin que serve essa capability a renderiza. Onde exatamente um plugin serve uma capability, nada precisa ser configurado. Onde mais de um a serve, uma entrada de plugins.providers diz qual, pela identidade do plugin:
# <project>/.aggrega-config.yamlworkspace: {}plugins: providers: - capability: helm uri: provider/helmUm pull resolve a entrada e registra o plugin escolhido no lockfile da Release, e um build renderiza por meio do que o lockfile registra, então uma alteração aqui entra em vigor no próximo pull.
O campo uri nomeia o plugin pela sua identidade, provider/<name>, nunca pelo lugar onde ele é publicado. aggrega plugin add provider <query> --capability <capability> grava a entrada nessa forma, sem versão: a entrada seleciona qual plugin atende à capacidade, a versão é a que a Recipe fixa ou, senão, a mais alta disponível, e o lockfile registra a que o pull escolheu. Um plugin que o compilador traz embutido é servido na própria versão do compilador, de modo que uma versão escrita em uma entrada para um deles só se resolve quando é essa versão. Uma entrada cujo uri é uma localização de registry — oci://hub.aggrega.ai/plugin/provider/helm — não nomeia a identidade de nenhum plugin, e é recusada quando o arquivo é carregado, nomeando a entrada e a forma a escrever.
As entradas são escritas uma vez para o projeto inteiro, enquanto um build é de uma única Release, então uma entrada para uma capability que esta Release nunca solicita é válida — outra Release do projeto a lê — e não é relatada de forma alguma. O que cada build e cada aggrega validate --release verificam é cada entrada, quer uma Recipe solicite a capability dela ou não, pelo que a entrada nomeia:
- Uma entrada que nomeia um plugin cujo plugin não serve a capability dela interrompe o build e faz a validação falhar. Um pull resolve toda entrada que nomeia um plugin, e recusa aquela que não consegue resolver; assim, depois que uma entrada passou por um pull, o build tem o plugin dela e sabe o que ele serve; uma entrada que nomeia um plugin que o build ainda não tem é avaliada assim que um pull o obtém. A mensagem nomeia a entrada, o plugin, o que esse plugin de fato serve, e uma grafia a uma edição de distância quando houver uma — a forma que um erro de digitação como
hlemem vez dehelmassume. - Uma entrada que nomeia apenas uma capability que nenhum plugin lido pelo build serve é um aviso, e o build continua. O plugin que a serve pode ser lido apenas por outra Release, que este build não consegue ver, e uma entrada que não nomeia nenhum plugin não seleciona nada que a resolução da capability não selecionaria sem ela.
Uma capability aqui nunca contém dois-pontos, e uma que contenha é recusada quando o arquivo é carregado. O capability: de uma Recipe é lido como a capability até os últimos dois-pontos e um pin de versão depois deles, então uma entrada com a chave helm:1.0.0 nunca poderia ser encontrada. Fixe a versão no plugin — uri: provider/helm:1.0.0 — ou na Recipe.
Qual importador transforma uma fonte em rascunhos
aggrega import entrega uma fonte ao importador que anuncia o formato da fonte — um no seu catálogo ou um dos importadores principais do compilador, import:langflow para um fluxo Langflow. Onde exatamente um importador o anuncia, nada precisa ser configurado. Uma entrada de plugins.importer vincula um importador nomeando-o no uri dela, pela identidade e versão, e entrega a ele o que ela carrega em with:
# <project>/.aggrega-config.yamlworkspace: {}plugins: importer: - uri: importer/agent-flows:1.2.0 with: settings: target_namespace: paymentsaggrega plugin add importer escreve o uri exatamente nessa forma. A versão é exata — :1.2.0 — ou um intervalo — :^1.2.0 para a versão mais alta igual ou superior a ela dentro da mesma versão principal. Escreva uma ou outro: nesta lista, um uri sem dois-pontos é lido como um caminho do sistema de arquivos, como descreve Para onde aponta um caminho relativo, e não nomeia nenhum importador.
O que uma entrada faz depende de o importador que ela nomeia anunciar ou não o formato que uma importação solicita:
- Ele anuncia: esse importador é o que é executado, na versão que o
urinomeia, não importa quantos outros importadores do catálogo também anunciem o formato, e ele recebewith.sourcesewith.settingsda entrada. Uma entrada é a forma como um workspace cujo catálogo federa os importadores de dois publicadores para um mesmo formato diz qual deles usa. - Ele não anuncia — a entrada nomeia um importador de outro formato, um plugin de outro tipo ou nada que seu catálogo contenha ou que o compilador inclua: a entrada não tem papel algum nessa importação. Ela não escolhe nada, e o
withdela não é entregue a nenhum importador. As configurações de uma entrada chegam apenas ao importador que ela nomeia, de modo que um workspace que vincula um importador por formato configura cada um sem que as configurações de um cheguem ao outro.
Onde mais de um importador anuncia o formato e nenhum deles está vinculado isoladamente — nenhum está, ou entradas nomeiam dois deles —, a importação é recusada, nomeando os importadores entre os quais não conseguiu escolher. Uma entrada que nomeia um importador que anuncia o formato, em uma versão que nenhuma versão dele no catálogo satisfaz — uma versão exata que o catálogo não contém, ou um intervalo em que nenhuma das versões dele se encaixa —, também é recusada, nomeando a versão, em vez de executar outra versão no lugar; uma versão que nem sequer é uma versão, como :latest, é recusada como malformada. Uma entidade Plugin de um dos importadores core do compilador sem nenhum módulo ao lado dela em sua pasta do catálogo não é candidata: na versão própria do compilador, o importador core é executado em seu lugar, e em qualquer outra versão a entidade continua candidata apenas onde uma entrada nomeia exatamente essa versão ou nenhum importador com o nome dela que possa ser executado anuncia o formato, como descreve Qual é executado ao lado dos seus próprios importadores.
Cada importador é vinculado por uma única entrada. Duas entradas que nomeiam um mesmo importador — a mesma identidade, em uma versão ou em duas — são recusadas quando a configuração é carregada, seja qual for o comando que a lê, nomeando ambas as entradas e os arquivos em que foram escritas. A regra abrange todo arquivo que contribui para a lista: uma entrada no arquivo global, uma no arquivo de um projeto, uma em importer_append e uma no .aggrega-config-append-ci.yaml de um pipeline contam todas, então mudar um importador para uma nova versão significa alterar a versão na única entrada dele. aggrega plugin add importer faz exatamente isso quando a lista plugins.importer do arquivo que ele escreve já nomeia o importador: ele move essa entrada para a versão que resolveu, mantendo a posição da entrada e o with dela, em vez de adicionar uma segunda. Ele não lê nenhuma outra lista, então um importador vinculado em importer_append, ou no .aggrega-config-append-ci.yaml de um pipeline, é vinculado uma segunda vez pelo comando, e o par é recusado quando a configuração é carregada; altere a versão de uma entrada assim onde ela está escrita. Uma entrada cujo uri é um caminho do sistema de arquivos não nomeia nenhum importador e não é comparada, e as listas plugins.governance e plugins.linter não estão sujeitas à regra: um plugin pode ser vinculado a elas mais de uma vez, cada vez com o próprio with.
Os parsers por meio dos quais uma importação lê não precisam de nenhuma entrada. Um importador lê sua fonte — e uma importação que não nomeia nenhum formato a reconhece — por meio de um parser para a sintaxe da fonte: aquele que seu catálogo serve para essa sintaxe e, para uma sintaxe para a qual seu catálogo não serve nenhum parser, aquele que o próprio compilador inclui, JSON entre eles. Assim, um workspace cujo catálogo não contém nenhum parser importa um fluxo Langflow ou Flowise sem nada configurado. Nenhuma lista vincula um parser: um parser que seu catálogo serve para uma sintaxe é o usado, e dois com nomes diferentes servindo uma mesma sintaxe são recusados, como descreve A parse or import format is advertised by more than one plugin (Um formato de parsing ou de importação é anunciado por mais de um plugin).
Começando do zero
Um aggrega recém-instalado não tem nenhum dos dois arquivos, e esse é um estado funcional, não quebrado: toda configuração recorre ao seu valor padrão embutido e os comandos são executados. O que falta é um registry de onde fazer pull de conteúdo de catálogo, junto com a política de confiança que diz quais assinaturas aceitar — que é exatamente o que aggrega config init escreve.
Você não precisa saber disso com antecedência. Um comando que lê sua configuração e não encontra nenhum arquivo em lugar algum diz isso uma vez, na saída de erro padrão, e indica aggrega config init como a forma de criar um. É uma orientação, não uma falha: a saída padrão não é tocada, nada é pedido a você, e o status de saída é o que o comando teria informado de qualquer forma. Ela só é escrita quando a saída de erro padrão é um terminal, de modo que chega até você no teclado e nunca se acumula no log de um pipeline. Assim que qualquer um dos arquivos existe — o do seu projeto ou o global —, ela deixa de aparecer.
Para inicializar o arquivo global com o hub oficial e a política de confiança que esse hub anuncia:
aggrega config initPasse --registry <host> para inicializar outro, --workspace para escrever a entrada no arquivo deste projeto em vez do global, e --dry-run para ver o conteúdo que seria escrito sem criar nada. aggrega-config.md cobre o comando por completo.
Como um host de registry é escrito
Cada registries[].host nomeia um host de registry. O mesmo faz default_registry — opcionalmente seguido de um caminho de repositório —, a menos que nomeie uma dessas entradas em vez disso (veja abaixo). Um host é escrito como o próprio host, na única grafia sob a qual a política de confiança do registry é mantida:
- um nome de host em minúsculas contendo um ponto, como
registry.example.com; localhost, ou um nome único seguido de uma porta, comoregistry:5000;- um endereço IPv4 como
127.0.0.1, ou um endereço IPv6 entre colchetes como[::1];
cada um com um :port opcional, e nada mais — sem esquema, sem caminho, sem credenciais, sem espaços em branco e sem letras maiúsculas. Um nome único sem porta não é um host de registry, porque essa é a forma do primeiro segmento do nome de uma entidade de catálogo — o core em core/web-api —, e os dois nunca devem ser confundidos um com o outro.
# <project>/.aggrega-config.yamlworkspace: {}default_registry: registry.example.comregistries: - host: registry.example.com signing: required: trueA grafia faz parte da política. Uma entrada de registries se aplica ao host que o host: dela nomeia, e o requisito de assinatura embutido do hub oficial se aplica a hub.aggrega.ai, então um host escrito de qualquer outra forma chegaria ao registry certo e perderia a política escrita para ele. Em vez disso, ele é recusado quando a configuração é carregada, e a recusa nomeia a grafia a escrever: HUB.AGGREGA.AI e https://registry.example.com são recusados nomeando hub.aggrega.ai e registry.example.com, assim como registry.example.com/charts como registries[].host, que não carrega caminho. A porta 443 é a porta padrão de um host acessado via HTTPS, então hub.aggrega.ai:443 é recusado da mesma forma, nomeando hub.aggrega.ai. localhost e os outros endereços de loopback são acessados via HTTP simples, em vez disso, onde 443 é uma porta comum, então localhost:443 é aceito como está escrito. Um default_registry vazio não nomeia nenhum registry padrão.
default_registry pode carregar um caminho de repositório. Muitos registries mantêm todo repositório sob um proprietário ou um projeto — ghcr.io/<owner>, <host>/<project> no Harbor —, e um registry padrão em um deles é escrito como o host seguido desse caminho:
# <project>/.aggrega-config.yamlworkspace: {}default_registry: ghcr.io/acmeregistries: - host: ghcr.io signing: required: trueO caminho é onde as coisas são publicadas e obtidas. Por meio desse padrão, aggrega push publica core/api-server na versão 1.0.0 em ghcr.io/acme/component/core/api-server:1.0.0, e um pull que resolve core/api-server o obtém do mesmo lugar, de modo que uma assinatura anexada quando ele foi publicado também é encontrada ali. O caminho é um caminho de repositório na gramática de distribuição OCI: um ou mais segmentos de letras minúsculas e dígitos unidos por /, que podem ser separados dentro de um segmento por ., _, __ ou hifens, sem tag, digest ou / final.
O caminho nunca faz parte de como se confia no registry. A entrada de registries cuja política se aplica, a credencial que aggrega login armazena, o requisito de assinatura e as identidades confiáveis são todos encontrados apenas pelo host, então a entrada para ghcr.io acima governa ghcr.io/acme e todos os outros caminhos nesse host, e nenhuma grafia de um caminho pode contorná-la; o próprio host: de uma entrada não carrega caminho. Um host escrito em outra grafia antes de um caminho é recusado nomeando o local a escrever — GHCR.io/acme e https://ghcr.io/acme nomeiam ghcr.io/acme —, e o que vem depois do host, quando não é um caminho de repositório, é recusado nomeando o host que o precede.
default_registry pode, em vez disso, nomear uma entrada. Escrito como o name: de uma entrada em registries, ele representa o host: dessa entrada. Publicação, pull, verificação de assinaturas e cada configuração de confiança por registry passam a usar esse host, e nenhum conteúdo é obtido de um host escrito como o nome:
# <project>/.aggrega-config.yamlworkspace: {}default_registry: localregistries: - name: local host: 127.0.0.1:5000Um nome é comparado antes de uma grafia de host, como o flag --registry faz, então um valor que é o name: de uma entrada representa essa entrada mesmo onde também está escrito como um host. Um nome que duas entradas carregam é recusado como ambíguo, nomeando ambos os hosts. A entrada pode estar em qualquer um dos dois arquivos — o default_registry de um projeto pode nomear uma entrada que o arquivo global declara —, porque o nome é lido uma vez, em relação às entradas em vigor depois que todos os arquivos e o ambiente foram lidos. Um valor que não é nem o nome de uma entrada nem um host de registry — sozinho ou seguido de um caminho de repositório — é recusado, e a recusa diz que qualquer um dos dois o corrige. Um nome seguido de um caminho, como local/acme, também é recusado: um nome representa o host da sua entrada e não um local sob ele, então a recusa nomeia, em vez disso, as duas grafias a escrever — local, ou o host da entrada seguido do caminho, 127.0.0.1:5000/acme. Remover uma entrada com aggrega registry remove deixa default_registry como está escrito, então um padrão que nomeava a entrada removida passa a não nomear nada e é recusado até ser reescrito.
Toda camada está sujeita à mesma grafia. Um valor é recusado com as mesmas palavras, venha ele de um arquivo de configuração, de AGGREGA_DEFAULT_REGISTRY ou do flag --registry que nomeia o destino de um aggrega push ou aggrega push-artifact. Esse flag nomeia um host, e a publicação que ele direciona chega a esse host sem caminho de repositório: um caminho pertence a default_registry. aggrega registry add e aggrega config init --registry também submetem a ela o host que recebem; eles também aceitam uma referência no lugar dele e registram a entrada sob o host que a referência nomeia. Uma recusa vinda de um arquivo nomeia o arquivo e a chave; uma vinda do ambiente nomeia a variável. O schema declara a forma do host como um pattern em registries[].host e não declara nenhuma em default_registry, cujo valor pode ser o nome de qualquer entrada — então um editor que lê apenas o schema não sinaliza um padrão digitado errado, e é o carregamento da configuração que o recusa.
Um host é julgado apenas pela grafia, e um caminho também. Se o nome é resolvido, se um registry responde ali ou se o caminho existe nele não é verificado quando a configuração é carregada.
O que sobrepõe o quê
CLI flag > environment variable > configuration file > built-in defaultUm flag é o sinal mais explícito que existe e vence sem ressalvas. Uma variável de ambiente sobrepõe o arquivo commitado, que é o que permite a um pipeline mudar uma configuração sem editar um arquivo versionado. Uma variável não definida — ou definida como string vazia — recai na camada abaixo em vez de apagar um valor configurado. Entre os dois arquivos, o arquivo do seu projeto vence o global.
Um flag vence por ter sido digitado, não pelo valor que carrega, e para uma configuração de verdadeiro ou falso essa é a diferença entre uma camada superior utilizável e nenhuma. --offline ativa o modo para uma execução; --offline=false o desativa para uma execução em que um arquivo commitado ou uma variável exportada o ativou. Uma camada que lesse apenas o valor não conseguiria distinguir “desativado” de “não mencionado”, de modo que todo comando pareceria ter pedido o padrão do flag e não haveria nenhuma forma de revogar uma configuração definida.
Esse é o modelo inteiro para um único projeto em uma única máquina. Tudo o que vem abaixo existe para projetos que o superam.
Além dos dois arquivos
Estes mecanismos são feitos para estruturas maiores — um monorepo de projetos relacionados, um pipeline que contribui com configurações próprias, um catálogo compartilhado que vários projetos estendem. Recorra a um deles quando tiver o problema que ele resolve.
Mais de um arquivo de configuração dentro de um projeto
Todo .aggrega-config.yaml da raiz do projeto até o diretório em que o comando é executado contribui, e um arquivo mais próximo sobrepõe um mais distante. Assim, um subprojeto pode ter um arquivo próprio que ajusta o que a raiz declarou, sem repeti-lo.
Apenas um arquivo que contém um bloco workspace: marca uma raiz. Um arquivo sem ele ainda contribui com suas configurações — ele simplesmente não transforma seu diretório em uma raiz de projeto, que é o que impede o arquivo de configurações de um subprojeto de redefinir onde o projeto começa.
Passar --workspace-root muda isso também, além de pular a descoberta: o próprio arquivo de configuração da raiz nomeada é o único coletado, então arquivos em diretórios abaixo dela não contribuem. Isso mantém a configuração de uma raiz fixada igual de onde quer que o comando seja executado.
Todo arquivo coletado dessa forma é lido de dentro do projeto. Um que seja um link simbólico que leva para fora do projeto — ou que esteja em um diretório alcançado por meio de um link assim — não é lido, e todo comando que lê a configuração para nele, nomeando o link, em vez de configurar o projeto a partir dos arquivos restantes; o mesmo vale para o arquivo de um pipeline, abaixo. Os poucos comandos que nunca a leem, como aggrega version e aggrega help, são executados com um aviso que nomeia o link. O servidor de linguagem do editor e as ferramentas de um assistente leem a configuração da mesma forma, e ainda assim iniciam sobre um projeto assim para que ele possa ser listado: as listagens de Releases e de entidades deles respondem, lidas sem nada configurado, e nomeiam o arquivo entre os links não lidos, enquanto toda outra solicitação que a configuração decide para nele, nomeando o link. Uma configuração mantida fora do projeto é lida nomeando-a como o arquivo global, como descreve Nomear o arquivo global explicitamente. Consulte O limite do workspace.
Estender uma lista em vez de substituí-la
Uma configuração com valor de lista se comporta como qualquer outra configuração: o valor do arquivo mais próximo substitui o do mais distante. Quando você quiser adicionar ao que um arquivo externo declarou em vez de declará-lo de novo, use o complemento de anexação ao lado dela:
| configuração de lista | seu complemento de anexação |
|---|---|
workspace.catalog_dirs | catalog_dirs_append |
plugins.governance | governance_append |
plugins.linter | linter_append |
plugins.importer | importer_append |
plugins.providers | providers_append |
As entradas em um complemento são concatenadas à lista resolvida em cada camada em vez de sombreá-la, de modo que um subprojeto adiciona um linter ao que a raiz já declarou:
# <project>/services/api/.aggrega-config.yamlplugins: linter_append: - uri: ./lint/api-rules.wasmOnde um arquivo define tanto a lista base quanto seu complemento, o valor desse arquivo é a lista base seguida das entradas anexadas.
O bloco workspace: é a exceção quanto a onde um complemento pode ser escrito. Um arquivo que contém esse bloco marca o próprio diretório como raiz do projeto, então o arquivo de um subprojeto que escrevesse workspace.catalog_dirs_append iniciaria um projeto próprio em vez de adicionar ao projeto que o envolve. O complemento de diretórios de catálogo se compõe entre o seu arquivo global e o arquivo raiz do projeto.
A lista plugins.cli se compõe entre arquivos por conta própria e não tem complemento: uma extensão de comando declarada no arquivo global registra seu comando em todo projeto, uma declarada em um projeto o registra apenas ali, e ambas se registram juntas. Cada entrada fixa um plugin: o uri que ela resolve e o digest dos bytes que aggrega plugin add cli verificou, escrito como sha256: seguido de 64 dígitos hexadecimais em minúsculas. Um digest em qualquer outra grafia nunca poderia ser igual ao digest resultante do hash dos bytes resolvidos, então ele é recusado quando o arquivo é carregado, nomeando o arquivo e a entrada.
Dar a uma Release seus próprios diretórios de catálogo
Um projeto pode manter várias variantes de catálogo lado a lado — uma por destino, cada uma contendo as Recipes que renderizam os mesmos Components para um provedor diferente — e compilar cada Release com uma delas. Nomeie cada Release em workspace.releases e dê a ela os próprios catalog_dirs:
# <project>/.aggrega-config.yamlworkspace: releases: release-compose.yaml: catalog_dirs: - ./catalog-compose release-helm.yaml: catalog_dirs: - ./catalog-helmCada chave é um arquivo de Release, escrito de forma relativa ao arquivo de configuração que o nomeia. Uma chave — como build.authoring_release — pode nomear uma Release mantida fora do projeto, e nomeá-la aqui é a forma como um projeto a alcança: um link dentro do projeto que leva até ela é lido em vez de ignorado, como descreve O limite do workspace. As duas chaves abaixo dela significam o que significam no bloco workspace:, restritas a essa única Release:
catalog_dirssubstitui a lista do workspace para essa Release. A ordem de busca, o diretóriocataloglido depois dela e o que uma lista vazia diz são os mesmos da lista própria do workspace.catalog_dirs_appendé lido depois da lista da Release. Uma entrada que escreve apenascatalog_dirs_appendmantém a lista do workspace e adiciona a ela.
Uma Release que o mapa não nomeia lê o workspace.catalog_dirs próprio do workspace. Uma Release que o mapa nomeia lê os próprios diretórios, seja como for compilada — aggrega build ou aggrega pull em um terminal, o editor por meio de aggrega serve, um assistente por meio de aggrega mcp —, então nenhum deles precisa de um flag para encontrar seu catálogo. Um --catalog <dir> na linha de comando continua sendo pesquisado antes dos diretórios da Release, para essa única invocação. E uma busca que não encontra nenhuma entidade com um nome que você usou indica a entrada dessa Release como o lugar onde listar o diretório que a contém.
Uma entrada que nomeia um arquivo que não existe é recusada quando a configuração é carregada, nomeando a entrada e o arquivo. Renomear uma Release, portanto, interrompe todo comando até que a entrada seja renomeada junto com ela, em vez de deixar a Release ser compilada com a lista do workspace sem que nada o indique. Um diretório que uma entrada lista deve ser um diretório, assim como deve ser um que a lista do workspace nomeia: um que não seja é recusado por todo comando que lê o catálogo dessa Release, nomeando a entrada e sua linha.
O que não diz respeito a nenhuma Release específica continua lendo a lista do workspace: um lint ou uma validação do catálogo inteiro, a busca de uma entidade pelo nome, um Aggregate inspecionado isoladamente e a listagem das entidades do workspace em um editor. AGGREGA_CATALOG_DIRS define a lista do workspace e não alcança nenhuma entrada aqui, e um arquivo de configuração de propriedade do seu pipeline não lê o mapa de forma alguma.
Um arquivo de configuração de propriedade do seu pipeline
Um arquivo chamado .aggrega-config-append-ci.yaml pode ficar ao lado do arquivo escrito à mão em qualquer diretório que a varredura visita. Ele é um arquivo separado para que um pipeline automatizado possa ser dono dele e sobrescrevê-lo por inteiro sem nunca tocar no que uma pessoa escreveu.
Ele é apenas aditivo. As entradas dele para as cinco configurações de lista acima são concatenadas às listas resolvidas; ele não pode remover nada nem sobrepor um escalar. Uma chave escalar ou de mapa escrita nele não tem significado aditivo, então é ignorada e nomeada em um aviso em vez de aplicada silenciosamente. Ele também nunca marca uma raiz de projeto, então colocar um em um diretório adiciona vínculos sem mover o lugar onde o projeto começa.
Para onde aponta um caminho relativo
Um caminho relativo do sistema de arquivos é resolvido em relação ao diretório do arquivo que o declarou — não em relação à raiz do projeto, nem em relação ao diretório a partir do qual você executou o comando. Esta é a regra que vale a pena ler duas vezes, porque um caminho que parece relativo ao projeto é resolvido em outro lugar e o build ainda assim é bem-sucedido, com um conteúdo que você não pretendia.
Ela se aplica a workspace.catalog_dirs, aos arquivos de Release usados como chaves em workspace.releases e aos diretórios que cada entrada lista, aos caminhos do sistema de arquivos local em um vínculo de plugins.governance ou plugins.linter — um uri que nomeia um arquivo .wasm em disco, e cada entrada no with.sources desse vínculo — e a cada entrada no with.sources de um vínculo de plugins.importer. Nas três listas, um uri sem dois-pontos que não nomeia nenhum registry — tanto importer/agent-flows quanto ./lint/api-rules.wasm — é um caminho assim, enquanto um uri que nomeia um plugin pela identidade carrega a versão depois de dois-pontos, importer/agent-flows:1.2.0, e é mantido exatamente como está escrito. O uri de um vínculo de importador nomeia o importador que ele vincula, como descreve Qual importador transforma uma fonte em rascunhos; uma importação não lê nenhum módulo de um caminho escrito ali. A regra se aplica também às entradas nos complementos de anexação, e cada uma delas se ancora ao próprio arquivo declarante, e não ao arquivo em que a mesclagem por acaso termina. E ela se aplica a mcp.tls.cert_file, mcp.tls.key_file e mcp.authorization.jwks_file, de modo que um arquivo ao lado daquele que o nomeia é encontrado de onde quer que o servidor seja iniciado.
Então, dada esta estrutura:
myproject/├── .aggrega-config.yaml└── services/ ├── .aggrega-config.yaml └── catalog/e ./catalog escrito no arquivo raiz, o caminho nomeia myproject/catalog. Escrito em services/.aggrega-config.yaml, o texto idêntico nomeia myproject/services/catalog. Um caminho absoluto é mantido exatamente como está escrito, assim como uma referência de registry como oci://hub.aggrega.ai/plugins/helm:1.0.0.
Estas configurações deliberadamente não seguem essa regra, porque não têm um arquivo declarante ao qual se ancorar ou porque todo leitor delas as resolve em outro lugar:
artifact_cache_diré interpretado em relação à raiz do projeto, de onde quer que o comando seja executado, de modo que o cache é um único diretório em vez de um por local de invocação. Um valor absoluto é recusado quando a configuração é carregada.AGGREGA_CATALOG_DIRSvem do ambiente e não tem nenhum arquivo declarante, então forneça caminhos absolutos nela.mcp.listené usado exatamente como está escrito, e isso inclui o caminho do sistema de arquivos na formaunix:<path>. O mesmo endereço também chega deaggrega mcp --listen, que não tem arquivo declarante, então ancorar apenas a grafia configurada faria uma mesma string nomear dois lugares diferentes dependendo de onde veio. Dê ao socket um caminho absoluto.
Uma configuração cujo armazenamento é compartilhado
Quase toda configuração governa algo que pertence ao projeto em que você está trabalhando — por meio de quais diretórios ele resolve conteúdo de catálogo, quais plugins renderizam seus destinos, com que rigor seu conteúdo é avaliado, quanto os caches em memória do daemon podem crescer. Um valor no arquivo de um projeto governa o que é próprio desse projeto, e não há nada com que se preocupar.
compiled_module_cache.max_bytes é a única exceção, porque o que ela limita não é por projeto. O código compilado de plugins é mantido em um único diretório que todo projeto na sua máquina reutiliza, de modo que um dado plugin é compilado uma vez, e não uma vez por projeto. O limite em si é resolvido como qualquer outra configuração — escreva-o no arquivo de um projeto e esse valor vence para esse projeto —, mas o armazenamento continua tendo um único tamanho, e o tamanho em vigor é o do build mais recente. Dois projetos que o limitam de forma diferente entram em vigor ambos, alternadamente, e o limite mais baixo descarta código compilado pelo qual o outro projeto pagou.
Então coloque-o no arquivo global quando quiser uma única resposta para tudo o que você compila, e mantenha-o acima do que um único build compila. aggrega cache status informa o que o armazenamento contém atualmente, e aggrega config show --origin informa de qual arquivo veio de fato o limite sob o qual você está executando.
Configurações para um servidor acessado por outras pessoas
aggrega mcp fala o Model Context Protocol. Na sua própria máquina, um cliente o inicia como subprocesso e se comunica com ele pela entrada e saída padrão, que é o padrão, e as únicas configurações que essa forma lê são mcp.transport, deixada nesse padrão, e mcp.announce_tools. O restante do bloco mcp é para a outra forma, que mcp.transport: http escolhe: um único processo de longa duração em um host, acessado via HTTP por chamadores que não estão diante do teclado dele.
# <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 é o que escolhe o transporte. http inicia um listener; stdio, o padrão, se comunica pela entrada e saída padrão, que é o que um cliente de subprocesso espera. Qualquer outro valor é recusado quando este arquivo é carregado. aggrega mcp --transport <stdio|http> faz o mesmo para uma única invocação e vence a chave, da mesma forma que todo flag vence todo arquivo.
mcp.listen nomeia onde esse listener faz bind, e não escolhe nada. Forneça a ele um endereço host:port ou um socket unix:<path>; aggrega mcp --listen <address> vence sobre ele para uma única invocação. Com http escolhido e nenhum endereço vindo de nenhum dos dois, a inicialização é recusada antes que qualquer coisa faça bind. Com stdio escolhido, um --listen digitado é recusado, e um endereço que apenas esta chave nomeia fica sem uso — o servidor diz isso em uma linha no seu fluxo de erro, nomeando este arquivo e mcp.transport: http. Assim, um servidor acessado por outras pessoas define as duas chaves, como acima, e um cliente iniciado a partir de um diretório coberto por esse arquivo ainda alcança o servidor pelos próprios fluxos. Um caminho unix: é usado como está escrito em vez de ancorado — consulte Para onde aponta um caminho relativo.
mcp.tls.cert_file e mcp.tls.key_file colocam TLS no processo. Defina ambos e o listener serve HTTPS por conta própria. Omita ambos e ele serve texto não criptografado, o que só é aceito em loopback ou em um socket Unix — a forma que você usa quando um proxy à frente detém o certificado e encaminha para o processo. Um listener não criptografado em qualquer outro endereço é recusado antes que qualquer coisa faça bind, nomeando essas duas chaves, assim como um dos dois definido sem o outro. Ambos são caminhos do sistema de arquivos e seguem a regra acima: um relativo é resolvido em relação ao diretório do arquivo que o declarou, de modo que um certificado commitado ao lado desse arquivo é encontrado de onde quer que o servidor seja iniciado. Escreva-os como absolutos onde o certificado é gerenciado fora do projeto.
mcp.authorization.issuer e mcp.authorization.resource dizem quem emite os tokens que os chamadores apresentam e como este servidor se chama enquanto recurso para o qual eles são emitidos. Ambos são obrigatórios sempre que o transporte http é escolhido, e sem eles um listener é recusado antes que qualquer coisa seja vinculada, porque toda requisição ao endpoint é respondida com um desafio bearer-token, e um desafio que não indica para onde ir é um desafio sobre o qual um cliente não consegue agir. Escreva endereços completos, com esquema e host incluídos: o issuer exatamente como esse servidor de autorização declara seu próprio identificador, e o recurso como o endereço que seus chamadores realmente alcançam — o host que um proxy à frente apresenta, onde houver um, em vez do endereço ao qual este processo se vincula. Ambos são publicados, sem que nenhuma credencial seja pedida, no documento de metadados OAuth do recurso protegido que o listener serve, que é onde um cliente procura onde obter um token. Nenhum dos dois contém nada secreto: um token chega na requisição que o apresenta e nunca é escrito em um arquivo de configuração. O issuer é um endereço https, a menos que o servidor de autorização rode nesta máquina — localhost, 127.0.0.1 ou ::1 —, e um listener que indica um issuer http sem criptografia em qualquer outro host é recusado antes que qualquer coisa seja vinculada, seja qual for a forma como ele lê suas chaves e seus chamadores: todo cliente é enviado ao issuer para obter seu token, então sobre http sem criptografia seu código de autorização e seu token atravessariam a rede sem proteção, e onde as chaves também são lidas de lá, qualquer um nesse caminho poderia substituí-las.
mcp.authorization.jwks_file indica um arquivo que contém as chaves com as quais os tokens são verificados, em vez de lê-las do servidor de autorização. Se você o omitir, o servidor lê os metadados desse servidor no endereço well-known dele e segue o jwks_uri publicado ali, que é o que faz um workspace com acesso à rede. Esse endereço de chaves está sujeito à mesma regra que o issuer, assim como qualquer endereço para o qual uma das duas leituras seja redirecionada: um que seja http sem criptografia em outro host nunca é consultado, e um token que precisa dessas chaves é respondido com 503 até que o servidor de autorização publique seus metadados e suas chaves sobre https. Se você o definir, o servidor de autorização nunca é contatado — que é do que precisa um workspace que declara offline: true, e esse workspace é recusado antes que seu listener se vincule, a menos que esta chave indique um arquivo. É um caminho e segue a regra acima: um caminho relativo é resolvido em relação ao diretório do arquivo que o declarou, então um conjunto de chaves commitado ao lado desse arquivo é encontrado de onde quer que o servidor seja iniciado. O arquivo contém chaves públicas de verificação, que são o que um servidor de autorização publica — nada que assine e nada secreto.
mcp.allowed_origins só é consultado quando uma requisição traz um cabeçalho Origin, o que na prática significa que um navegador a enviou. Liste ali as origens que você serve; uma requisição que indica uma não listada é recusada, e uma requisição sem esse cabeçalho é servida mesmo assim. Um cliente que não é um navegador não envia esse cabeçalho e não precisa de nenhuma entrada. Uma entrada é comparada exatamente com o cabeçalho, então escreva-a do jeito que um navegador a envia: um esquema em minúsculas, ://, um host em minúsculas e : com a porta somente onde a porta não é a padrão do esquema — https://studio.example.com, ou http://localhost:3000 para uma página servida na sua própria máquina —, sem caminho e sem / no final. Uma entrada em qualquer outro formato nunca poderia corresponder, e é recusada quando este arquivo é carregado, indicando a entrada.
mcp.limits limita o que um chamador pode pedir — o tamanho que o corpo de uma única requisição pode ter, quantas requisições rodam ao mesmo tempo e quantas um chamador pode enviar em um minuto. Os três estão sempre em vigor; nenhum tem um valor que o suspenda. O terceiro, requests_per_minute, é contado separadamente para cada chamador, então um chamador que envia muito não custa nada a outro.
mcp.authorization.trusted_proxy obtém o chamador de um proxy à frente em vez de verificar um token aqui. Defina principal_header como o cabeçalho que esse proxy usa para dizer quem é o chamador e, opcionalmente, scopes_header como um que traga os scopes desse chamador. Ambos são nomes de cabeçalho HTTP, como X-Forwarded-User — letras, dígitos, hifens e os poucos outros caracteres que um nome de cabeçalho pode conter, sem espaço nem dois-pontos —, e um nome em qualquer outro formato é recusado quando este arquivo é carregado, indicando a chave, porque nenhuma requisição poderia trazê-lo. Nesse modo, nenhum token é lido, e uma requisição sem o cabeçalho do principal é recusada. Como o cabeçalho passa a ser a credencial inteira, ele só é confiável onde nada mais pode defini-lo: o processo é recusado antes de se vincular, a menos que mcp.listen seja loopback ou um socket Unix. Se você omitir o bloco, este servidor verifica os tokens por conta própria, que é o padrão; um bloco cujo principal_header está vazio é recusado em vez de ser lido como esse padrão.
mcp.deny_reach retira um tipo de alcance desta implantação. Toda operação que o servidor executa declara até onde vão seus próprios efeitos — none para uma que lê ou renderiza e não deixa nada para trás, workspace para uma que escreve dentro do workspace que este processo serve, registry para uma que publica, assina ou retira, e machine para uma que altera o que todos os workspaces do host compartilham. Indicar um tipo aqui retira toda ferramenta que o alcança: a ferramenta fica ausente da lista de ferramentas de todo chamador, não importa o que o token desse chamador traga, e uma chamada a ela é recusada indicando esta configuração. Isso faz dela o limite da implantação, e não do chamador, e nenhuma credencial o suspende — um servidor destinado a servir leituras e nada mais lista aqui os três tipos que escrevem e então não consegue publicar nem mesmo para um chamador cujo token traga todos os scopes. Se você a omitir, que é o padrão, esta implantação oferece tudo o que os scopes de seus chamadores admitem. Um valor que não seja um dos quatro é recusado quando este arquivo é carregado, em vez de ser ignorado. Nada do tipo machine é oferecido via HTTP, diga o que disser esta configuração, então indicá-lo é aceito e não muda nada; aggrega-mcp.md descreve os tipos e os scopes que os admitem.
mcp.announce_tools restringe o que o servidor anuncia, e é um limite diferente da chave acima. Indique as ferramentas que este servidor anuncia, escritas como a lista de ferramentas as informa, e exatamente essas são anunciadas: uma omitida fica ausente da lista de ferramentas de todo chamador e é recusada se mesmo assim for chamada pelo nome, indicando esta configuração. Se você omitir a chave — o padrão —, toda ferramenta que o servidor oferece é anunciada; se escrever uma lista vazia, nenhuma é, então essas duas escritas são afirmações diferentes e nenhum padrão é preenchido por você. O que a distingue de deny_reach é o que cada uma tira. deny_reach tira uma capacidade: as operações de um tipo retirado não são oferecidas aqui de forma alguma e nenhuma credencial traz uma de volta. announce_tools tira apenas um anúncio — as ferramentas que ela omite são capacidades que o servidor ainda tem —, e ela atende a um cliente que limita quantas ferramentas vai registrar, às vezes somando todos os servidores aos quais está conectado ao mesmo tempo. Onde ambas estão definidas, a retirada prevalece, então uma ferramenta de um tipo retirado continua ausente, seja como for que esta chave a indique. Um nome ao qual nenhuma ferramenta responde para o servidor antes que ele sirva qualquer coisa, listando as ferramentas que ele tem, em vez de deixar você com uma superfície mais estreita do que a que pediu. Diferentemente das outras chaves aqui, que configuram o listener que o transporte http inicia, ela é lida qualquer que seja o transporte que o servidor fale, porque o cliente para o qual uma restrição existe costuma ser aquele que iniciou o processo pela sua própria entrada e saída padrão; aggrega-mcp.md descreve o restante.
mcp.health.listen coloca as verificações de liveness e readiness em um endereço próprio. Dê a ela um endereço em uma das duas formas de mcp.listen e um segundo listener responde ali a GET /healthz — 200 a partir do momento em que o processo está rodando — e a GET /readyz — 503 até que o workspace tenha sido resolvido e o endpoint vinculado, 200 daí em diante, que é o que permite a um balanceador segurar o tráfego até que o processo possa de fato responder a uma chamada. Se você a omitir, nenhuma das duas verificações é respondida em lugar nenhum. Elas nunca são respondidas no endereço que mcp.listen indica, que lhes dá o 404 que dá a todo caminho que não serve: uma sondagem ali seria uma leitura não autenticada de um listener que recusa todo o resto. Diferentemente de mcp.listen, este endereço não é restrito e nenhum endereço é recusado para ele — aponte-o para loopback ou para um socket Unix, que é o que um supervisor ao lado deste processo alcança, e observe que qualquer coisa que consiga alcançar o endereço que você escolher pode ler essas duas respostas.
schema/other/aggrega-config.md apresenta cada uma dessas chaves junto com seu valor padrão, onde houver um.
As outras formas de reconhecer a raiz de um projeto
--workspace-root <path>, ou seu equivalente AGGREGA_WORKSPACE_ROOT, indica a raiz diretamente e pula a descoberta. A pasta que ele indica precisa existir: um caminho que não indica nada, ou que indica um arquivo, é recusado antes que o comando faça qualquer outra coisa, e a recusa nomeia qual dos dois forneceu o valor e o cita como foi dado. Caso contrário, a descoberta sobe a partir do diretório de trabalho, e os tipos de âncora são classificados uns em relação aos outros, e não por proximidade:
- Um
.aggrega-config.yamlcom um blocoworkspace:prevalece de imediato, em qualquer profundidade em que esteja. A busca continua subindo para procurar um mesmo depois de passar por um marcador do tipo abaixo, então uma raiz marcada explicitamente mais acima sempre vence um marcador incidental abaixo dela. - Na falta disso, o mais próximo destes marcadores ancora a raiz, e dentro de um mesmo diretório eles são classificados nesta ordem: um diretório
.aggrega/, depois umaggregate*.yaml, depois umrelease*.yaml, depois ummanifest*.yaml. - Se tudo falhar, o diretório de trabalho é usado — os comandos são executados em vez de se recusarem a iniciar. Um comando cujo resultado depende do espaço de trabalho — um que lê ou grava os documentos do espaço de trabalho, lê ou preenche seu cache de artefatos, ou o serve — avisa uma vez na saída de erro padrão:
warning: <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace. Um comando cujo resultado não depende de qual pasta é a raiz não diz nada, mesmo quando lê a configuração: entre elesaggrega version,aggrega config show,aggrega plugin list,aggrega registry list,aggrega explaineaggrega login.aggrega config capture, cujo trabalho é gravar o próprio arquivo de configuração do espaço de trabalho, não grava nada em uma pasta assim e sai com um erro que informa isso.
Nada é gravado em um cache de artefatos em uma pasta assim. Um diretório .aggrega/ é ele próprio um dos marcadores acima, então um cache gravado ali tornaria a pasta um workspace só porque algo foi baixado nela uma vez. Um comando cujo trabalho preenche o cache — aggrega pull, um build que primeiro resolve suas dependências, aggrega registry update, a adição de um plugin de extensão de comandos a partir de um registro — é recusado antes de baixar qualquer coisa, indicando a pasta e as duas alternativas: indicar o workspace com --workspace-root ou AGGREGA_WORKSPACE_ROOT, ou dar à pasta um .aggrega-config.yaml com um bloco workspace:. aggrega pin, e aggrega push de uma Recipe ou de uma FeatureRecipe, que fica sujeito aos pins que o entity.lock ao lado registra, só preenchem o cache com as fontes remotas que a entidade escreve por completo, que o pin de uma delas ou a comparação do seu pin baixa: eles são recusados da mesma forma onde baixariam uma fonte assim, antes de baixá-la. Uma entidade sem uma fonte assim — sem nenhuma fonte, com uma local, ou com uma cujas coordenadas cada Release preenche — recebe pin ou é publicada ali como em qualquer outro lugar. Um build ali não é recusado, mas uma entrada externa que seu lockfile fixa e que o cache não contém mais não é baixada de novo para repará-la: a renderização recebe a mesma frase no lugar dessa entrada, do mesmo modo que recebe a da postura offline, e a relata. Onde artifact_cache_dir coloca o cache não muda nada aqui, porque o diretório é anexado a qualquer raiz que tenha sido encontrada. Comandos que apenas leem continuam respondendo.
Esse último recurso tem uma exceção. Quando nada indicou a raiz e o diretório de trabalho não ancora nada, um comando sobre uma Release ou um documento de entidade que indica esse arquivo por um caminho absoluto descobre a raiz de novo, subindo a partir da pasta em que o arquivo está, e usa o que encontrar: o workspace ao qual o arquivo pertence ou, na falta de tudo, essa pasta. O arquivo é aquele que --release indica em aggrega build e aggrega pull; a Release dada a aggrega validate, aggrega lint e aggrega inspect, ou então o arquivo dado a eles; e o documento dado a aggrega pin, aggrega push e aggrega edit-document. Assim, a Release de um projeto construída de fora do projeto lê a configuração do próprio projeto, como acontece quando o comando roda dentro dele, e os avisos de configuração que o comando imprime são os desse workspace. Onde a própria pasta do arquivo também não ancora nada, essa pasta é a que o aviso do comando indica e aquela em que nenhum cache é gravado. Um caminho relativo é lido em relação ao diretório em que você executa o comando e não muda nada, e uma raiz indicada, ou um diretório de trabalho que esteja ele próprio dentro de um workspace, é usado como está. O servidor do assistente aplica a mesma regra a uma chamada que indica sua Release ou seu documento por um caminho absoluto.
Marcar a raiz com um bloco workspace: é a escolha explícita e a preferível; os marcadores de arquivo e de diretório permitem que um projeto que não declarou nenhum ainda seja construído.
Indicar explicitamente o arquivo global
A camada global é resolvida nesta ordem:
--config <path>, a forma por invocação.- A variável de ambiente
AGGREGA_CONFIG. - O local padrão: no Windows,
aggrega\config.yamldentro do diretório que a variável de ambienteAPPDATAindica, e nos demais sistemasaggrega/config.yamldentro do diretório queXDG_CONFIG_HOMEindica, com~/.config/aggrega/config.yamlcomo alternativa.
Os dois primeiros indicam um arquivo explícito, então um caminho que não existe é um erro visível em vez de uma alternativa silenciosa — você pediu um arquivo específico. Um comando que lê sua configuração para com uma frase que termina com o caminho, para que você possa copiá-lo. aggrega config init é a exceção, porque criar esse arquivo é a sua finalidade: ele cria o arquivo indicado e avisa isso. O local padrão é carregado quando o arquivo está lá e é ignorado silenciosamente quando não está. Seja qual for o arquivo resolvido, os arquivos do seu projeto continuam se sobrepondo a ele.
Quando nenhum deles é resolvido — nenhum arquivo é indicado e as variáveis das quais o local padrão é lido não estão definidas —, um comando que grava o arquivo global para e indica o que definir. Variáveis de ambiente lista, por plataforma, as variáveis das quais cada local é lido.
Essa escolha também determina onde um comando que grava a configuração grava. Um comando executado com --config <path> lê sua configuração desse arquivo e aplica sua alteração a esse mesmo arquivo, então o que um comando grava é o que o próximo lê de volta.
Em qual dos dois arquivos um comando grava por padrão depende da natureza da configuração: ferramentas de toda a máquina, como um registro, vão para o arquivo global, enquanto configurações que participam do build, como um vínculo de provider ou uma conexão a um socket, vão para o arquivo commitado do projeto, para que acompanhem o projeto. Passe --global ou --workspace para mudar isso, e o comando imprime o arquivo em que gravou.
Veja também
- aggrega-config.md — os comandos
aggrega configque inicializam, inspecionam e congelam a configuração. - environment-variables.md — toda variável com o prefixo
AGGREGA_, e onde os segredos são fornecidos. - global-flags.md —
--config,--workspace-roote as outras flags que todo subcomando aceita. - schema/other/aggrega-config.md — toda chave de configuração, seu tipo e seu valor padrão.
- aggrega-cache.md — o que
artifact_cache_dirrealmente contém. - workspace-boundary.md — quais caminhos ficam dentro do workspace e como os diretórios e arquivos que esta configuração indica alcançam o que está fora dele.
- aggrega-mcp.md — o servidor que o bloco
mcpconfigura.