Configuração
De onde aggrega lê as suas definições, e em que ficheiro colocar uma definição.
O caso simples
Dois ficheiros, e a maioria dos projetos não precisa de mais nada.
Um ficheiro no seu projeto, chamado .aggrega-config.yaml, na raiz do projeto. Contém a forma como este projeto é compilado: que diretórios contêm conteúdo de catálogo incorporado, que plugins renderizam que destinos, que regras de lint são relaxadas, para onde vai a cache local. É incluído no controlo de versões, para que um colega de equipa que clone o projeto o compile da mesma forma.
O seu bloco workspace: é o que marca o diretório como a raiz do projeto:
# <project>/.aggrega-config.yamlworkspace: catalog_dirs: - ./catalogauto_pull: trueO bloco transporta apenas os diretórios de catálogo que definem a raiz; todas as outras definições ficam no nível superior, ao lado dele. Um projeto que não incorpora conteúdo de catálogo escreve o bloco na mesma, vazio — workspace: {} —, porque é a presença do bloco que serve de marcador.
Um ficheiro global na sua máquina, em ~/.config/aggrega/config.yaml — no Windows, em aggrega\config.yaml, dentro do diretório que a variável de ambiente APPDATA nomeia. Todos os espaços de trabalho nessa máquina resolvem através dele, e contém definições que pertencem à máquina e não a um projeto em particular — os registos de onde faz pull e a política de confiança de assinaturas de cada um, até que tamanho pode crescer o armazenamento de módulos compilados e qualquer plugin de extensão de comandos que tenha instalado. Essas são as mesmas onde quer que esteja a trabalhar, pelo que declará-las uma vez é precisamente o objetivo. É carregado automaticamente quando existe, e nada falha quando não existe.
registries: - host: hub.aggrega.ai signing: required: trueaggrega config init escreve esse ficheiro global por si, registando um registo juntamente com a política de confiança de assinaturas que este anuncia, e indica onde está o ficheiro na sua máquina e onde são mantidas as caches de toda a máquina. aggrega config show imprime o que se aplica neste momento, e aggrega config show --origin indica que ficheiro — ou que variável de ambiente — decidiu cada definição.
Os segredos não são configuração. Uma palavra-passe de registo e um token de identidade de assinatura nunca são campos em nenhum dos ficheiros; são fornecidos por variável de ambiente ou flag no momento em que são necessários. Consulte environment-variables.md.
De onde são lidas as entidades locais
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 formas de dizer onde esse conteúdo está, e a primeira não precisa de qualquer configuração.
Um diretório catalog na raiz do projeto é lido quer algo o nomeie quer não. Coloque uma entidade em <project>/catalog/ e todos os comandos que carregam um catálogo a leem, incluindo num projeto cujo bloco workspace: está vazio. Um diretório de catálogo é lido recursivamente, pelo que a forma como organiza os subdiretórios dentro dele fica ao seu critério.
Os diretórios enumerados em workspace.catalog_dirs também são lidos, e são lidos primeiro. A lista é uma pilha de pesquisa ordenada: o primeiro diretório a declarar uma identidade é o seu dono, e a mesma identidade num diretório posterior fica sombreada. catalog é lido depois de tudo o que está enumerado — a menos que um diretório enumerado já o contenha, caso em que é lido como parte desse diretório —, pelo que enumerar um diretório acrescenta ao que já tinha em vez de o substituir. Um --catalog <dir> repetível na linha de comandos é lido à frente de ambos, e um caminho relativo dado aí resolve em relação ao diretório a partir do qual executou o comando, uma vez que nenhum ficheiro de configuração o declarou. Um diretório nomeado mais de uma vez — na linha de comandos e na lista, ou duas vezes na lista — é lido uma vez, no lugar onde foi nomeado primeiro, pelo que nada nele é reportado como sombreado por si próprio: uma sombra é sempre dois ficheiros diferentes que declaram uma identidade. Duas grafias de um diretório, um caminho para ele através de uma ligação e — num sistema de ficheiros que ignora maiúsculas e minúsculas — uma grafia com outra capitalização nomeiam todos esse mesmo diretório. Um diretório dentro de outro diretório enumerado continua a ser 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 os seus próprios diretórios de catálogo.
Enumerar um diretório é a forma de um projeto ler entidades mantidas fora dele. Um diretório enumerado pode estar em qualquer lugar — um checkout irmão, um diretório partilhado com outros projetos — e é lido onde está, mesmo quando é ele próprio uma ligação simbólica. Nada mais chega tão longe: uma ligação dentro do projeto que conduz para outro lugar não é seguida, e um documento que nomeia um ficheiro fora do projeto por um caminho é recusado, pelo que uma entidade mantida noutro lugar é alcançada enumerando o diretório que a contém e nomeando a entidade pelo seu nome. Um diretório enumerado fora do projeto é uma raiz própria, pelo que uma ligação sob ele que conduza para fora dele também não é lida. O limite do espaço de trabalho enuncia a regra completa.
Um diretório enumerado tem de ser um diretório. Um caminho enumerado onde nada existe, ou onde se encontra um ficheiro ou uma ligação que não leva a lado nenhum, é recusado antes de qualquer leitura ou escrita por todos os comandos que leem o catálogo — um pull, uma compilação, uma validação, uma inspeção, um lint, e as mesmas operações conduzidas a partir do editor através de aggrega serve ou de um assistente através de aggrega mcp —, pelo que uma compilação nunca corre com menos catálogos do que os enumerados. A recusa nomeia a entrada tal como está escrita, o caminho em que se resolveu, o ficheiro de configuração e a linha que a enumeram, e a lista em que se encontra:
<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 irmão que ele enumera remove essa entrada, e resolve a partir de um registo o que o checkout teria fornecido. O mesmo se aplica a um diretório que a entrada própria de uma Release enumera, a um que um ficheiro de configuração da sua pipeline ou o ficheiro global acrescenta, e a um que AGGREGA_CATALOG_DIRS contém, que a recusa nomeia em vez de um ficheiro. A configuração em si continua a ser carregada, pelo que um comando que não lê nenhum catálogo continua a correr. Um diretório --catalog que não existe foi escrito para um único comando, e aggrega build recusa-o, nomeando o diretório. Um diretório enumerado que existe e não pode ser lido é recusado pelos comandos que carregam o catálogo inteiro, que o nomeiam.
Escrever a lista como vazia diz que este projeto não tem nenhum catálogo local, e é a única grafia que impede que catalog também seja lido:
# <project>/.aggrega-config.yamlworkspace: catalog_dirs: []Omitir a chave é uma afirmação diferente: uma lista omitida é o caso normal, e catalog continua a ser lido.
Uma compilação, um pull, uma validação ou um aggrega inspect que não encontra nenhuma entidade com um nome que usou indica de onde este projeto lê as entidades locais e o que alterar para que aquela que nomeou seja lida. Não diz nada disso quando escreveu a lista vazia — não ler nenhum catálogo local é o que declarou aí, e uma sugestão para o alterar seria contrariá-lo. Também não o diz quando o documento que declara esse nome foi lido e recusado: esse documento já está onde o catálogo lê, pelo que o relatório nomeia antes aquilo que o documento viola, a linha e a restrição, e movê-lo não resolveria nada. Um documento demasiado malformado para que o nome que declara possa sequer ser lido não pode ser associado ao nome que usou, pelo que a explicação é dada na mesma — e, quando esse documento declara uma apiVersion do Aggrega, uma compilação, um pull ou uma validação de uma Release nomeia-o ao lado da explicação, com o motivo dado pelo próprio parser, já que pode ser o ficheiro a abrir. Uma falha que encontrou a entidade e não a pôde aceitar — um registo que agora serve outros bytes sob uma versão que o seu lockfile fixa, um ficheiro que a entidade transporta e que não pode ser lido — também não é uma entidade em falta, e reporta apenas a sua própria solução.
Se um pull ou um push fixa uma entidade
Uma Recipe ou FeatureRecipe transporta as fixações das entradas que lê — uma source: remota escrita por extenso, um ficheiro que uma entrada artifacts importa, os ficheiros de uma source: ao lado dela — no entity.lock ao lado dela, e registá-las é o passo do autor da entidade, aggrega pin. Por predefinição, nem pull nem push executam esse passo: um pull para numa entidade que o seu lock não fixa, e um push recusa-se a publicá-la. Duas chaves, uma por comando, tornam a execução desse passo a predefinição desse comando:
# <project>/.aggrega-config.yamlworkspace: {}pin_sources_at_pull: truepin_sources_at_push: trueCada chave rege o seu próprio comando e nada mais, e o --pin-sources de cada comando substitui a sua própria chave em ambos os sentidos — --pin-sources=false desativa o passo para uma execução num projeto configurado para fixar. Uma compilação que preenche o seu próprio lockfile é um pull e segue pin_sources_at_pull. Pertencem ao ficheiro do projeto e não ao global: se os pulls de um projeto registam fixações é política desse projeto, e um colega de equipa que o clone deve obter a mesma resposta. pin_sources_at_pull é também a forma de um projeto que consome o catálogo não fixado de outra pessoa registar essas fixações uma vez, em vez de parar em cada pull.
Que plugin renderiza uma capacidade
Uma Recipe nomeia a capacidade através da qual é renderizada — capability: helm — e um plugin que serve essa capacidade renderiza-a. Quando exatamente um plugin serve uma capacidade, nada precisa de ser configurado. Quando mais de um o faz, uma entrada plugins.providers indica qual, pela identidade do plugin:
# <project>/.aggrega-config.yamlworkspace: {}plugins: providers: - capability: helm uri: provider/helmUm pull resolve a entrada e regista o plugin que escolheu no lockfile da Release, e uma compilação renderiza através do que o lockfile regista, pelo que uma edição aqui produz efeito no pull seguinte.
O campo uri nomeia o plugin pela sua identidade, provider/<name>, nunca pelo local onde é publicado. aggrega plugin add provider <query> --capability <capability> escreve a entrada nessa forma, sem versão: a entrada seleciona qual plugin serve a capacidade, a versão é a que a Recipe fixa ou, caso contrário, a mais alta disponível, e o lockfile regista a que o pull escolheu. Um plugin que o compilador traz consigo é servido na própria versão do compilador, pelo que uma versão escrita numa entrada para um desses só se resolve quando é essa versão. Uma entrada cujo uri é uma localização de registo — oci://hub.aggrega.ai/plugin/provider/helm — não nomeia a identidade de nenhum plugin, e é recusada quando o ficheiro é carregado, nomeando a entrada e a forma a escrever.
As entradas são escritas uma vez para todo o projeto, enquanto uma compilação é de uma Release, pelo que uma entrada para uma capacidade que esta Release nunca pede é legal — outra Release do projeto lê-a — e é reportada como nada. O que cada compilação e cada aggrega validate --release efetivamente verifica é cada entrada, quer uma Recipe peça a sua capacidade quer não, por aquilo que a entrada nomeia:
- Uma entrada que nomeia um plugin que não serve a sua capacidade para a compilação e faz falhar a validação. Um pull resolve todas as entradas que nomeiam um plugin, e recusa uma que não consegue resolver, pelo que, assim que uma entrada passou por um pull, a compilação contém o seu plugin e sabe o que este serve; uma entrada que nomeia um plugin que a compilação ainda não contém é julgada assim que um pull o tiver obtido. A mensagem nomeia a entrada, o plugin, o que esse plugin efetivamente serve e uma grafia a uma edição de distância, quando existe — a forma que toma um erro de escrita como
hlemem vez dehelm. - Uma entrada que nomeia apenas uma capacidade que nenhum plugin que a compilação lê serve é um aviso, e a compilação prossegue. O plugin que a serve pode ser um que apenas outra Release lê, que esta compilação não consegue ver, e uma entrada que não nomeia nenhum plugin não seleciona nada que a resolução da capacidade não selecionasse sem ela.
Uma capacidade aqui nunca contém dois pontos, e uma que os contenha é recusada quando o ficheiro é carregado. O capability: de uma Recipe é lido como a capacidade até aos últimos dois pontos e uma fixação de versão a seguir, pelo que uma entrada com a chave helm:1.0.0 nunca poderia ser procurada. Em vez disso, fixe a versão no plugin — uri: provider/helm:1.0.0 — ou na Recipe.
Que importador transforma uma origem em rascunhos
aggrega import entrega uma origem ao importador que anuncia o formato da origem — um no seu catálogo ou um dos importadores principais do compilador, import:langflow para um fluxo Langflow. Quando exatamente um importador o anuncia, nada precisa de ser configurado. Uma entrada plugins.importer anexa um importador nomeando-o no seu uri, pela sua identidade e versão, e entrega-lhe o que transporta 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 outra: nesta lista, um uri sem dois pontos é lido como um caminho do sistema de ficheiros, como descreve Para onde aponta um caminho relativo, e não nomeia nenhum importador.
O que uma entrada faz depende de o importador que nomeia anunciar ou não o formato que uma importação pede:
- Anuncia: esse importador é o que corre, na versão que o
urinomeia, por muitos outros importadores do catálogo que também anunciem o formato, e recebe owith.sourcese owith.settingsda entrada. Uma entrada é a forma de um espaço de trabalho cujo catálogo federa os importadores de dois editores para um formato dizer qual deles usa. - Não anuncia — nomeia um importador de outro formato, um plugin de outro tipo, ou nada que o seu catálogo contenha ou que o compilador transporte: a entrada não tem qualquer papel nessa importação. Não escolhe nada, e o seu
withnão é entregue a nenhum importador. As definições de uma entrada só chegam ao importador que nomeia, pelo que um espaço de trabalho que anexa um importador por formato configura cada um sem que as definições de um cheguem ao outro.
Quando mais de um importador anuncia o formato e nenhum deles isoladamente está anexado — nenhum está, ou as 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, numa 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 suas versões cai — também é recusada, nomeando a versão, em vez de correr outra versão no seu lugar; uma versão que não é de todo uma versão, como :latest, é recusada como malformada. Uma entidade Plugin de um dos importadores core do compilador sem nenhum módulo ao seu lado na respetiva pasta do catálogo não é candidata: na versão própria do compilador, é o importador core que é executado no seu lugar, e em qualquer outra versão a entidade só continua a ser candidata quando uma entrada nomeia exatamente essa versão ou quando nenhum importador com o seu nome que possa ser executado anuncia o formato, como descreve Qual é executado ao lado dos importadores próprios.
Cada importador é anexado por uma entrada. Duas entradas que nomeiam um importador — a mesma identidade, numa 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 ficheiros onde foram escritas. A regra abrange todos os ficheiros que contribuem para a lista: uma entrada no ficheiro global, uma no ficheiro de um projeto, uma em importer_append e uma no .aggrega-config-append-ci.yaml de um pipeline contam todas, pelo que mudar um importador para uma nova versão significa alterar a versão na sua única entrada. aggrega plugin add importer faz exatamente isso quando a lista plugins.importer do ficheiro que escreve já nomeia o importador: muda essa entrada para a versão que resolveu, mantendo o lugar da entrada e o seu with, em vez de acrescentar uma segunda. Não lê nenhuma outra lista, pelo que um importador anexado em importer_append, ou no .aggrega-config-append-ci.yaml de um pipeline, é anexado uma segunda vez pelo comando e o par é recusado quando a configuração é carregada; altere a versão de uma entrada dessas onde está escrita. Uma entrada cujo uri é um caminho do sistema de ficheiros 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 anexado a elas mais de uma vez, de cada vez com o seu próprio with.
Os analisadores através dos quais uma importação lê não precisam de entrada. Um importador lê a sua origem — e uma importação que não nomeia nenhum formato reconhece-a — através de um analisador para a sintaxe da origem: o que o seu catálogo serve para essa sintaxe e, para uma sintaxe para a qual o seu catálogo não serve nenhum analisador, o que o próprio compilador transporta, entre os quais o de JSON. Assim, um espaço de trabalho cujo catálogo não contém nenhum analisador importa um fluxo Langflow ou Flowise sem nada configurado. Nenhuma lista anexa um analisador: um analisador que o seu catálogo serve para uma sintaxe é o que é usado, e dois com nomes diferentes que servem uma sintaxe são recusados, como descreve A parse or import format is advertised by more than one plugin (Um formato de análise ou de importação é anunciado por mais de um plugin).
Começar do zero
Um aggrega acabado de instalar não tem nenhum dos ficheiros, e esse é um estado funcional e não um estado avariado: todas as definições recorrem à sua predefinição incorporada e os comandos correm. O que falta é um registo de onde fazer pull de conteúdo de catálogo, juntamente com a política de confiança que diz que assinaturas aceitar — que é exatamente o que aggrega config init escreve.
Não é preciso saber isso de antemão. Um comando que lê a sua configuração e não encontra nenhum ficheiro em lado nenhum di-lo uma vez, no erro padrão, e nomeia aggrega config init como a forma de criar um. É um conselho e não uma falha: a saída padrão não é tocada, nada lhe é pedido, e o estado de saída é o que o comando teria reportado de qualquer forma. Só é escrito quando o erro padrão é um terminal, pelo que chega a si ao teclado e nunca se acumula no registo de um pipeline. Assim que qualquer um dos ficheiros existe — o do seu projeto ou o global —, deixa de aparecer.
Para inicializar o ficheiro global com o hub oficial e a política de confiança que esse hub anuncia:
aggrega config initPasse --registry <host> para inicializar um diferente, --workspace para escrever a entrada no ficheiro deste projeto em vez do global, e --dry-run para ver o conteúdo que escreveria sem criar nada. aggrega-config.md cobre o comando por completo.
Como se escreve um anfitrião de registo
Cada registries[].host nomeia um anfitrião de registo. O mesmo faz default_registry — seguido opcionalmente de um caminho de repositório —, a menos que nomeie antes uma dessas entradas (ver abaixo). Um anfitrião é escrito como o próprio anfitrião, na única grafia sob a qual a política de confiança do registo é mantida:
- um nome de anfitrião em minúsculas que contenha um ponto, como
registry.example.com; localhost, ou um nome simples seguido de uma porta, comoregistry:5000;- um endereço IPv4 como
127.0.0.1, ou um endereço IPv6 entre parênteses retos como[::1];
cada um com uma :port opcional, e nada mais — sem esquema, sem caminho, sem credenciais, sem espaços em branco e sem letras maiúsculas. Um nome simples sem porta não é um anfitrião de registo, 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 podem ser lidos um como 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 registries aplica-se ao anfitrião que o seu host: nomeia, e o requisito de assinatura incorporado do hub oficial aplica-se a hub.aggrega.ai, pelo que um anfitrião escrito de qualquer outra forma chegaria ao registo certo e falharia a política escrita para ele. Em vez disso, é 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, tal como registry.example.com/charts como registries[].host, que não transporta caminho. A porta 443 é a porta predefinida de um anfitrião acedido por HTTPS, pelo que hub.aggrega.ai:443 é recusado da mesma forma, nomeando hub.aggrega.ai. localhost e os outros endereços de loopback são acedidos por HTTP simples, onde 443 é uma porta comum, pelo que localhost:443 é aceite tal como está escrito. Um default_registry vazio não nomeia nenhum registo predefinido.
default_registry pode transportar um caminho de repositório. Muitos registos mantêm todos os repositórios sob um proprietário ou um projeto — ghcr.io/<owner>, <host>/<project> no Harbor — e um registo predefinido num deles é escrito como o anfitrião 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. Através desta predefinição, aggrega push publica core/api-server versão 1.0.0 em ghcr.io/acme/component/core/api-server:1.0.0, e um pull que resolve core/api-server obtém-no do mesmo local, pelo que uma assinatura anexada quando foi publicado também é encontrada aí. 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 hífenes, sem etiqueta, digest ou / final.
O caminho nunca faz parte da forma como o registo é considerado de confiança. A entrada registries cuja política se aplica, a credencial que aggrega login guarda, o requisito de assinatura e as identidades de confiança são todos encontrados apenas pelo anfitrião, pelo que a entrada para ghcr.io acima rege ghcr.io/acme e todos os outros caminhos nesse anfitrião, e nenhuma grafia de um caminho consegue ir além dela; o próprio host: de uma entrada não transporta caminho. Um anfitrião escrito noutra grafia antes de um caminho é recusado nomeando a localização a escrever — GHCR.io/acme e https://ghcr.io/acme nomeiam ghcr.io/acme — e o que segue o anfitrião, quando não é um caminho de repositório, é recusado nomeando o anfitrião que segue.
default_registry pode, em vez disso, nomear uma entrada. Escrito como o name: de uma entrada em registries, representa o host: dessa entrada. A publicação, o pull, a verificação de assinaturas e todas as definições de confiança por registo usam então esse anfitrião, e nenhum conteúdo é obtido de um anfitrião 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 anfitrião, tal como a flag --registry compara um, pelo que um valor que é o name: de uma entrada representa essa entrada mesmo quando também está escrito como um anfitrião. Um nome que duas entradas transportam é recusado como ambíguo, nomeando ambos os anfitriões. A entrada pode estar em qualquer um dos ficheiros — o default_registry de um projeto pode nomear uma entrada que o ficheiro global declara —, porque o nome é lido uma vez, em relação às entradas em vigor depois de todos os ficheiros e o ambiente terem sido lidos. Um valor que não é nem o nome de uma entrada nem um anfitrião de registo — isolado ou seguido de um caminho de repositório — é recusado, e a recusa diz que qualquer um deles o resolve. Um nome seguido de um caminho, como local/acme, também é recusado: um nome representa o anfitrião da sua entrada e não uma localização sob ele, pelo que a recusa nomeia as duas grafias a escrever em vez disso — local, ou o anfitrião da entrada seguido do caminho, 127.0.0.1:5000/acme. Remover uma entrada com aggrega registry remove deixa default_registry tal como está escrito, pelo que uma predefinição que nomeava a entrada removida deixa de nomear o que quer que seja e é recusada até ser reescrita.
Todas as camadas estão sujeitas à mesma grafia. Um valor é recusado com as mesmas palavras quer venha de um ficheiro de configuração, de AGGREGA_DEFAULT_REGISTRY ou da flag --registry que nomeia o destino de um aggrega push ou de um aggrega push-artifact. Essa flag nomeia um anfitrião, e a publicação que dirige chega a esse anfitrião sem caminho de repositório: um caminho pertence a default_registry. aggrega registry add e aggrega config init --registry também sujeitam a essa grafia o anfitrião que recebem; aceitam ainda uma referência no seu lugar, e associam a entrada ao anfitrião que a referência nomeia. Uma recusa vinda de um ficheiro nomeia o ficheiro e a chave; uma vinda do ambiente nomeia a variável. O esquema enuncia a forma do anfitrião como um padrão em registries[].host e não enuncia nenhuma em default_registry, cujo valor pode ser o nome de qualquer entrada — pelo que um editor que leia apenas o esquema não assinala uma predefinição mal escrita, e é o carregamento da configuração que a recusa.
Um anfitrião é julgado apenas pela sua grafia, tal como um caminho. Se o nome resolve, se um registo responde aí ou se o caminho existe nele não é verificado quando a configuração é carregada.
O que substitui o quê
CLI flag > environment variable > configuration file > built-in defaultUma flag é o sinal mais explícito que existe e prevalece sem mais. Uma variável de ambiente substitui o ficheiro incluído no controlo de versões, o que permite a um pipeline alterar uma definição sem editar um ficheiro rastreado. Uma variável que não está definida — ou que está definida como cadeia vazia — passa para a camada abaixo em vez de apagar um valor configurado. Entre os dois ficheiros, o ficheiro do seu projeto prevalece sobre o global.
Uma flag prevalece por ter sido escrita, não pelo valor que transporta, e, para uma definição de verdadeiro ou falso, essa é a diferença entre uma camada superior utilizável e nenhuma. --offline ativa a postura para uma execução; --offline=false desativa-a para uma execução em que um ficheiro incluído no controlo de versões ou uma variável exportada a tenha ativado. Uma camada que lesse apenas o valor não conseguiria distinguir «desativado» de «não mencionado», pelo que todos os comandos pareceriam ter pedido a predefinição da flag e não haveria forma alguma de anular uma definição configurada.
Este é o modelo completo para um único projeto numa única máquina. Tudo o que se segue existe para projetos que o ultrapassam.
Para além dos dois ficheiros
Estes mecanismos foram concebidos para estruturas maiores — um monorepo de projetos relacionados, um pipeline que contribui com definições próprias, um catálogo partilhado que vários projetos estendem. Recorra a um quando tiver o problema que ele resolve.
Mais de um ficheiro de configuração dentro de um projeto
Todos os .aggrega-config.yaml desde a raiz do projeto até ao diretório em que o comando corre contribuem, e um ficheiro mais próximo substitui um mais distante. Assim, um subprojeto pode ter o seu próprio ficheiro que ajusta o que a raiz declarou, sem o repetir.
Só um ficheiro que transporta um bloco workspace: marca uma raiz. Um ficheiro sem ele continua a contribuir com as suas definições — simplesmente não transforma o seu diretório numa raiz de projeto, que é o que impede o ficheiro de definições de um subprojeto de redefinir onde o projeto começa.
Passar --workspace-root altera isto, além de saltar a descoberta: o ficheiro de configuração da própria raiz nomeada é o único recolhido, pelo que os ficheiros em diretórios abaixo dela não contribuem. Isso mantém a configuração de uma raiz fixada igual, seja de onde for que o comando é executado.
Todos os ficheiros recolhidos desta forma são lidos a partir de dentro do projeto. Um que seja uma ligação simbólica que conduz para fora do projeto — ou que esteja num diretório alcançado através de uma ligação dessas — não é lido, e todos os comandos que leem a configuração param nele, nomeando a ligação, em vez de configurar o projeto a partir dos ficheiros restantes; o mesmo se aplica ao ficheiro 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 a ligação. O servidor de linguagem do editor e as ferramentas de um assistente leem a configuração da mesma forma, e arrancam mesmo assim sobre um projeto destes para que possa ser listado: as suas listagens de Releases e de entidades respondem, lidas sem nada configurado, e nomeiam o ficheiro entre as ligações não lidas, enquanto todos os outros pedidos que a configuração decide param nele, nomeando a ligação. Uma configuração mantida fora do projeto é lida nomeando-a como o ficheiro global, como descreve Nomear explicitamente o ficheiro global. Consulte O limite do espaço de trabalho.
Estender uma lista em vez de a substituir
Uma definição com valor de lista comporta-se como qualquer outra definição: o valor do ficheiro mais próximo substitui o do mais distante. Quando pretende acrescentar ao que um ficheiro exterior declarou em vez de o reescrever, use a companheira de acréscimo ao lado:
| definição de lista | a sua companheira de acréscimo |
|---|---|
workspace.catalog_dirs | catalog_dirs_append |
plugins.governance | governance_append |
plugins.linter | linter_append |
plugins.importer | importer_append |
plugins.providers | providers_append |
As entradas sob uma companheira são concatenadas à lista resolvida em cada camada em vez de a sombrearem, pelo que um subprojeto acrescenta um linter ao que a raiz já declarou:
# <project>/services/api/.aggrega-config.yamlplugins: linter_append: - uri: ./lint/api-rules.wasmQuando um ficheiro define tanto a lista base como a sua companheira, o valor desse ficheiro é a lista base seguida das entradas acrescentadas.
O bloco workspace: é a exceção quanto a onde uma companheira pode ser escrita. Um ficheiro que transporta esse bloco marca o seu próprio diretório como a raiz do projeto, pelo que o ficheiro de um subprojeto que escrevesse workspace.catalog_dirs_append iniciaria um projeto próprio em vez de acrescentar ao projeto envolvente. A companheira dos diretórios de catálogo compõe-se entre o seu ficheiro global e o ficheiro da raiz do projeto.
A lista plugins.cli compõe-se entre ficheiros por si só e não tem companheira: uma extensão de comando declarada no ficheiro global regista o seu comando em todos os projetos, uma declarada num projeto regista-o apenas aí, e ambas se registam em conjunto. Cada entrada fixa um plugin: o uri que 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 com qualquer outra grafia nunca poderia ser igual ao digest dos bytes resolvidos, pelo que é recusado quando o ficheiro é carregado, nomeando o ficheiro e a entrada.
Dar a uma Release os 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 fornecedor diferente — e compilar cada Release com uma delas. Nomeie cada Release em workspace.releases e dê-lhe os seus 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 ficheiro de Release, escrito em relação ao ficheiro de configuração que o nomeia. Uma chave — tal como build.authoring_release — pode nomear uma Release mantida fora do projeto, e nomeá-la aqui é a forma de um projeto chegar a ela: uma ligação dentro do projeto que conduz até ela é lida em vez de ignorada, como descreve O limite do espaço de trabalho. As duas chaves sob ela significam o que significam no bloco workspace:, restritas a essa Release:
catalog_dirssubstitui a lista do espaço de trabalho para essa Release. A ordem de pesquisa, o diretóriocataloglido depois dela e o que uma lista vazia diz são os mesmos que para a lista própria do espaço de trabalho.catalog_dirs_appendé lido depois da lista da Release. Uma entrada que escreve apenascatalog_dirs_appendmantém a lista do espaço de trabalho e acrescenta-lhe.
Uma Release que o mapa não nomeia lê o workspace.catalog_dirs próprio do espaço de trabalho. Uma Release que o mapa nomeia lê os seus próprios diretórios seja como for que é compilada — aggrega build ou aggrega pull num terminal, o editor através de aggrega serve, um assistente através de aggrega mcp —, pelo que nenhum deles precisa de uma flag para encontrar o seu catálogo. Um --catalog <dir> na linha de comandos continua a ser pesquisado à frente dos diretórios da Release, para essa invocação. E uma pesquisa que não encontra nenhuma entidade com um nome que usou nomeia a entrada dessa Release como o local onde enumerar o diretório que a contém.
Uma entrada que nomeia um ficheiro que não existe é recusada quando a configuração é carregada, nomeando a entrada e o ficheiro. Mudar o nome de uma Release para, portanto, todos os comandos até que a entrada seja renomeada com ela, em vez de deixar a Release compilar com a lista do espaço de trabalho sem nada que o indique. Um diretório que uma entrada liste tem de ser um diretório, tal como tem de o ser um que a lista do espaço de trabalho indique: um que não o seja é recusado por todos os comandos que leem o catálogo dessa Release, nomeando a entrada e a sua linha.
O que não diz respeito a nenhuma Release em particular continua a ler a lista do espaço de trabalho: um lint ou uma validação do catálogo inteiro, uma pesquisa de uma entidade pelo nome, um Aggregate inspecionado isoladamente e a listagem das entidades do espaço de trabalho de um editor. AGGREGA_CATALOG_DIRS define a lista do espaço de trabalho e não chega a nenhuma entrada aqui, e um ficheiro de configuração que pertence ao seu pipeline não lê de todo o mapa.
Um ficheiro de configuração que pertence ao seu pipeline
Um ficheiro chamado .aggrega-config-append-ci.yaml pode estar ao lado do ficheiro escrito à mão em qualquer diretório que o percurso visite. É um ficheiro separado para que um pipeline automatizado o possa possuir e substituir por inteiro sem nunca tocar no que uma pessoa escreveu.
É apenas aditivo. As suas entradas para as cinco definições de lista acima são concatenadas às listas resolvidas; não pode remover nada nem substituir um escalar. Uma chave escalar ou de mapa escrita nele não tem significado aditivo, pelo que é ignorada e nomeada num aviso em vez de ser aplicada discretamente. Também nunca marca uma raiz de projeto, pelo que colocar um num diretório acrescenta anexos sem mudar onde o projeto começa.
Para onde aponta um caminho relativo
Um caminho relativo do sistema de ficheiros é resolvido em relação ao diretório do ficheiro que o declarou — não em relação à raiz do projeto, nem em relação ao diretório a partir do qual executou o comando. Esta é a regra que vale a pena ler duas vezes, porque um caminho que parece relativo ao projeto resolve para outro lugar e a compilação tem êxito na mesma, com conteúdo que não pretendia.
Aplica-se a workspace.catalog_dirs, aos ficheiros de Release usados como chaves em workspace.releases e aos diretórios que cada entrada enumera, aos caminhos do sistema de ficheiros local num anexo plugins.governance ou plugins.linter — um uri que nomeia um ficheiro .wasm em disco, e cada entrada no with.sources desse anexo — e a cada entrada no with.sources de um anexo plugins.importer. Nas três listas, um uri sem dois pontos que não nomeia nenhum registo — tanto importer/agent-flows como ./lint/api-rules.wasm — é um caminho destes, enquanto um uri que nomeia um plugin pela sua identidade transporta a versão depois de dois pontos, importer/agent-flows:1.2.0, e é deixado exatamente como está escrito. O uri de um anexo de importador nomeia o importador que anexa, como descreve Que importador transforma uma origem em rascunhos; uma importação não lê nenhum módulo a partir de um caminho aí escrito. A regra aplica-se também às entradas sob as companheiras de acréscimo, e cada uma delas ancora no seu próprio ficheiro declarante e não no ficheiro em que a fusão por acaso termina. E aplica-se a mcp.tls.cert_file, mcp.tls.key_file e mcp.authorization.jwks_file, para que um ficheiro ao lado daquele que o nomeia seja encontrado seja de onde for que o servidor é lançado.
Assim, dada esta estrutura:
myproject/├── .aggrega-config.yaml└── services/ ├── .aggrega-config.yaml └── catalog/e ./catalog escrito no ficheiro da raiz, o caminho nomeia myproject/catalog. Escrito em services/.aggrega-config.yaml, o texto idêntico nomeia myproject/services/catalog. Um caminho absoluto é deixado exatamente como está escrito, tal como uma referência de registo como oci://hub.aggrega.ai/plugins/helm:1.0.0.
Estas definições não seguem deliberadamente esta regra, porque não têm nenhum ficheiro declarante em que ancorar ou porque todos os seus leitores as resolvem noutro lugar:
artifact_cache_diré interpretado em relação à raiz do projeto, seja de onde for que o comando corre, para que a cache seja um único diretório e não um por local de invocação. Um valor absoluto é recusado quando a configuração é carregada.AGGREGA_CATALOG_DIRSvem do ambiente e não tem de todo ficheiro declarante, pelo que deve fornecer caminhos absolutos nela.mcp.listené aceite exatamente como está escrito, e isso inclui o caminho do sistema de ficheiros na sua formaunix:<path>. O mesmo endereço também chega a partir deaggrega mcp --listen, que não tem ficheiro declarante, pelo que ancorar apenas a grafia configurada faria com que uma cadeia nomeasse dois lugares diferentes consoante a sua proveniência. Dê ao socket um caminho absoluto.
Uma definição cujo armazenamento é partilhado
Quase todas as definições regem algo que pertence ao projeto em que está a trabalhar — através de que diretórios resolve conteúdo de catálogo, que plugins renderizam os seus destinos, com que rigor o seu conteúdo é julgado, até que tamanho podem crescer as caches em memória do daemon. Um valor no ficheiro de um projeto rege aquilo que é desse projeto, e não há nada a vigiar.
compiled_module_cache.max_bytes é a única exceção, porque aquilo que limita não é por projeto. O código compilado dos plugins é mantido num único diretório que todos os projetos da sua máquina reutilizam, para que um dado plugin seja compilado uma vez e não uma vez por projeto. O próprio limite resolve como qualquer outra definição — escreva-o no ficheiro de um projeto e esse valor prevalece para esse projeto —, mas o armazenamento continua a ter um único tamanho, e o tamanho em vigor é o da compilação mais recente. Dois projetos que o limitem de forma diferente produzem ambos efeito à vez, e o limite mais baixo descarta código compilado pelo qual o outro projeto pagou.
Por isso, coloque-o no ficheiro global quando quiser uma resposta única para tudo o que compila, e mantenha-o acima do que uma única compilação compila. aggrega cache status reporta o que o armazenamento contém atualmente, e aggrega config show --origin indica de que ficheiro veio de facto o limite sob o qual está a correr.
Definições para um servidor a que outras pessoas acedem
aggrega mcp fala o Model Context Protocol. Na sua própria máquina, um cliente lança-o como subprocesso e comunica com ele através da entrada e da saída padrão, que é a predefinição, e as únicas definições que essa forma lê são mcp.transport, deixado nessa predefinição, e mcp.announce_tools. O resto do bloco mcp destina-se à outra forma, que mcp.transport: http escolhe: um processo de longa duração num anfitrião, acedido por HTTP por chamadores que não estão ao seu 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 é o que escolhe o transporte. http inicia um listener; stdio, a predefinição, fala através da entrada e da saída padrão, que é o que um cliente de subprocesso espera. Qualquer outro valor é recusado quando este ficheiro é carregado. aggrega mcp --transport <stdio|http> faz o mesmo para uma invocação e prevalece sobre a chave, da forma como todas as flags prevalecem sobre todos os ficheiros.
mcp.listen nomeia onde esse listener se associa, e não escolhe nada. Dê-lhe um endereço host:port ou um socket unix:<path>; aggrega mcp --listen <address> prevalece sobre ele para uma invocação. Com http escolhido e nenhum endereço de nenhum dos dois, o lançamento é recusado antes de qualquer associação. Com stdio escolhido, um --listen escrito é recusado, e um endereço que apenas esta chave nomeia fica por usar — o servidor di-lo numa linha no seu fluxo de erro, nomeando este ficheiro e mcp.transport: http. Assim, um servidor a que outras pessoas acedem define ambas as chaves, como acima, e um cliente lançado a partir de um diretório que esse ficheiro abrange continua a chegar ao servidor através dos seus próprios fluxos. Um caminho unix: é aceite tal 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 si. Omita ambos e serve texto simples, o que só é aceite em loopback ou num socket Unix — a forma que se usa quando um proxy à frente detém o certificado e reencaminha para o processo. Um listener de texto simples em qualquer outro endereço é recusado antes de qualquer associação, nomeando estas duas chaves, tal como um em que apenas uma das duas está definida. Ambos são caminhos do sistema de ficheiros e seguem a regra acima: um relativo resolve em relação ao diretório do ficheiro que o declarou, pelo que um certificado incluído no controlo de versões ao lado desse ficheiro é encontrado seja de onde for que o servidor é lançado. Escreva-os como absolutos quando o certificado é gerido fora do projeto.
mcp.authorization.issuer e mcp.authorization.resource dizem quem emite os tokens que os chamadores apresentam, e como se chama este servidor enquanto recurso para o qual são emitidos. Ambos são obrigatórios sempre que o transporte http é escolhido, e um listener é recusado antes de qualquer associação sem eles, porque todos os pedidos ao endpoint são respondidos com um desafio de bearer token, e um desafio que não nomeia para onde ir é um desafio sobre o qual um cliente não pode agir. Escreva endereços completos, incluindo esquema e anfitrião: o emissor exatamente como esse servidor de autorização indica o seu próprio identificador, e o recurso como o endereço a que os seus chamadores efetivamente acedem — o anfitrião que um proxy à frente apresenta, quando existe, e não o endereço a que este processo se associa. Ambos são publicados, sem que seja pedida qualquer credencial, no documento de metadados de recurso protegido OAuth que o listener serve, que é onde um cliente procura saber onde obter um token. Nenhum deles contém nada secreto: um token chega no pedido que o apresenta e nunca é escrito num ficheiro de configuração. O emissor é um endereço https, a menos que o servidor de autorização corra nesta máquina — localhost, 127.0.0.1 ou ::1 —, e um listener que nomeia um emissor http simples em qualquer outro anfitrião é recusado antes de qualquer associação, seja qual for a forma como lê as suas chaves e os seus chamadores: todos os clientes são enviados ao emissor para obter o seu token, pelo que, sobre http simples, o seu código de autorização e o seu token atravessariam a rede sem proteção, e, onde as chaves também são lidas a partir daí, quem estivesse nesse caminho poderia substituí-las.
mcp.authorization.jwks_file nomeia um ficheiro que contém as chaves com as quais os tokens são verificados, em vez de as ler do servidor de autorização. Omita-o e o servidor lê os metadados desse servidor no seu endereço well-known e segue o jwks_uri aí publicado, que é o que faz um espaço de trabalho com acesso à rede. Esse endereço das chaves está sujeito à mesma regra que o emissor, tal como qualquer endereço para o qual qualquer uma das leituras seja redirecionada: um que seja http simples noutro anfitrião nunca é consultado, e um token que precise dessas chaves é respondido com 503 até que o servidor de autorização publique os seus metadados e as suas chaves sobre https. Defina-o e o servidor de autorização nunca é contactado — que é do que precisa um espaço de trabalho que declara offline: true, e um espaço de trabalho desses é recusado antes de o seu listener se associar, a menos que isto nomeie um ficheiro. É um caminho e segue a regra acima: um relativo resolve em relação ao diretório do ficheiro que o declarou, pelo que um conjunto de chaves incluído no controlo de versões ao lado desse ficheiro é encontrado seja de onde for que o servidor é lançado. O ficheiro 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 um pedido transporta um cabeçalho Origin, o que, na prática, significa que foi um navegador a enviá-lo. Enumere aí as origens que serve; um pedido que nomeie uma que não esteja enumerada é recusado, e um pedido que não transporte esse cabeçalho é servido de qualquer forma. Um cliente que não seja um navegador não envia esse cabeçalho e não precisa de entrada. Uma entrada é comparada com o cabeçalho de forma exata, pelo que deve escrevê-la da forma como um navegador a envia: um esquema em minúsculas, ://, um anfitrião em minúsculas e : com a porta apenas quando a porta não é a predefinida 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 / final. Uma entrada com qualquer outra forma nunca poderia corresponder, e é recusada quando este ficheiro é carregado, nomeando a entrada.
mcp.limits limita o que um chamador pode pedir — que tamanho pode ter o corpo de um único pedido, quantos pedidos correm ao mesmo tempo e quantos um chamador pode enviar num minuto. Os três estão sempre em vigor; nenhum tem um valor que o levante. O terceiro, requests_per_minute, é contado separadamente para cada chamador, pelo que um chamador que envie muito não custa nada a outro.
mcp.authorization.trusted_proxy lê o chamador a partir 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 transporte os âmbitos desse chamador. Ambos são nomes de cabeçalhos HTTP, como X-Forwarded-User — letras, dígitos, hífenes e os poucos outros caracteres que um nome de cabeçalho pode ter, sem espaço nem dois pontos —, e um nome com qualquer outra forma é recusado quando este ficheiro é carregado, nomeando a chave, porque nenhum pedido o poderia transportar. Nesse modo nenhum token é lido, e um pedido sem o cabeçalho principal é recusado. Como o cabeçalho é então a credencial inteira, só é de confiança onde mais nada o pode definir: o processo é recusado antes de se associar, a menos que mcp.listen seja loopback ou um socket Unix. Omita o bloco e este servidor verifica os tokens por si, que é a predefinição; um bloco cujo principal_header esteja vazio é recusado em vez de ser lido como essa predefinição.
mcp.deny_reach retira um tipo de alcance a esta implantação. Cada operação que o servidor efetua declara até onde chegam os 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 espaço de trabalho que este processo serve, registry para uma que publica, assina ou retira, e machine para uma que altera o que todos os espaços de trabalho do anfitrião partilham. Nomear um tipo aqui retira todas as ferramentas que o alcançam: a ferramenta está ausente da lista de ferramentas de todos os chamadores, seja o que for que o token desse chamador transporte, e uma chamada a ela é recusada nomeando esta definição. Isso faz dela o limite da implantação e não do chamador, e nenhuma credencial o levanta — um servidor destinado a servir leituras e nada mais enumera aqui os três tipos de escrita e fica então sem poder publicar, mesmo para um chamador cujo token transporte todos os âmbitos. Omita-a, que é a predefinição, e esta implantação transporta tudo o que os âmbitos dos seus chamadores admitam. Um valor que não seja um dos quatro é recusado quando este ficheiro é carregado, em vez de ser ignorado. Nada do tipo machine é oferecido por HTTP, diga isto o que disser, pelo que nomeá-lo é aceite e nada altera; aggrega-mcp.md expõe os tipos e os âmbitos que os admitem.
mcp.announce_tools restringe o que o servidor anuncia, e é um limite diferente da chave acima. Nomeie as ferramentas que este servidor anuncia, escritas como a lista de ferramentas as reporta, e são anunciadas exatamente essas: uma deixada de fora está ausente da lista de ferramentas de todos os chamadores e é recusada se for chamada pelo nome mesmo assim, nomeando esta definição. Omita a chave — a predefinição — e todas as ferramentas que o servidor transporta são anunciadas; escreva uma lista vazia e nenhuma o é, pelo que essas duas grafias são afirmações diferentes e nenhuma predefinição é preenchida por si. O que a distingue de deny_reach é o que cada uma retira. deny_reach retira uma capacidade: as operações de um tipo retirado não são de todo transportadas aqui e nenhuma credencial as traz de volta. announce_tools retira apenas um anúncio — as ferramentas que deixa de fora são capacidades que o servidor continua a ter — e aquilo a que responde é um cliente que limita quantas ferramentas regista, por vezes em todos os servidores a que está ligado ao mesmo tempo. Quando ambas estão definidas, a retirada prevalece, pelo que uma ferramenta de um tipo retirado continua ausente por muito que esta chave a nomeie. Um nome ao qual nenhuma ferramenta responde para o servidor antes de este servir o que quer que seja, enumerando as ferramentas que tem, em vez de o deixar com uma superfície mais restrita do que a que pediu. Ao contrário das outras chaves aqui, que configuram o listener que o transporte http inicia, é lida seja qual for o transporte que o servidor fala, porque o cliente para o qual existe uma restrição é normalmente aquele que lançou o processo através da sua própria entrada e saída padrão; aggrega-mcp.md expõe o resto.
mcp.health.listen coloca as verificações de vivacidade e de prontidão num endereço próprio. Dê-lhe um endereço em qualquer uma das duas formas de mcp.listen e um segundo listener responde aí a GET /healthz — 200 a partir do momento em que o processo está a correr — e a GET /readyz — 503 até que o espaço de trabalho tenha sido resolvido e o endpoint se tenha associado, 200 a partir daí, que é o que permite a um balanceador reter o tráfego até que o processo consiga efetivamente responder a uma chamada. Omita-o e nenhuma das verificações é respondida em lado nenhum. Nunca são respondidas no endereço que mcp.listen nomeia, que lhes dá o 404 que dá a todos os caminhos que não serve: uma sonda aí seria uma leitura não autenticada de um listener que recusa tudo o resto. Ao contrário de mcp.listen, este endereço não está confinado 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 tenha em conta que tudo o que consiga alcançar o endereço que escolher pode ler essas duas respostas.
schema/other/aggrega-config.md enuncia cada uma destas chaves juntamente com a sua predefinição, quando tem uma.
As outras formas de reconhecer uma raiz de projeto
--workspace-root <path>, ou a sua contraparte AGGREGA_WORKSPACE_ROOT, nomeia a raiz diretamente e salta a descoberta. A pasta que nomeia tem de existir: um caminho que não nomeia nada, ou que nomeia um ficheiro, é recusado antes de o comando fazer qualquer outra coisa, e a recusa nomeia qual dos dois forneceu o valor e cita-o tal 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 pela proximidade:
- Um
.aggrega-config.yamlque transporta um blocoworkspace:prevalece sem mais, seja qual for a profundidade a que esteja. O percurso continua a subir à procura de um mesmo depois de ter passado por um marcador do tipo abaixo, pelo que uma raiz marcada explicitamente acima prevalece sempre sobre um marcador acidental abaixo dela. - Na falta disso, o mais próximo destes marcadores ancora a raiz, e, dentro de um diretório, são classificados por esta ordem: um diretório
.aggrega/, depois umaggregate*.yaml, depois umrelease*.yaml, depois ummanifest*.yaml. - Se tudo falhar, é usado o diretório de trabalho — os comandos são executados em vez de se recusarem a arrancar. Um comando cujo resultado depende do espaço de trabalho — um que lê ou escreve os documentos do espaço de trabalho, lê ou preenche a sua cache de artefactos, ou o serve — avisa uma vez no 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. Oaggrega config capture, cujo trabalho é escrever o próprio ficheiro de configuração do espaço de trabalho, não escreve nada numa pasta assim e termina com um erro que o indica.
Nada é escrito numa cache de artefactos numa pasta destas. Um diretório .aggrega/ é ele próprio um dos marcadores acima, pelo que uma cache escrita aí faria da pasta um espaço de trabalho só porque algo foi obtido nela uma vez. Um comando cujo trabalho preenche a cache — aggrega pull, uma compilação que resolve primeiro as suas dependências, aggrega registry update, a adição de um plugin de extensão de comandos a partir de um registo — é recusado antes de obter o que quer que seja, nomeando a pasta e as duas saídas possíveis: nomear o espaço de trabalho com --workspace-root ou AGGREGA_WORKSPACE_ROOT, ou dar à pasta um .aggrega-config.yaml que transporte um bloco workspace:. aggrega pin, e aggrega push de uma Recipe ou FeatureRecipe, que está sujeito às fixações que o entity.lock ao lado dela regista, só preenchem a cache com as origens remotas que a entidade escreve por extenso, que fixar uma delas ou comparar a sua fixação obtém: são recusados da mesma forma onde obteriam uma origem dessas, antes de a obterem. Uma entidade sem nenhuma origem dessas — nenhuma origem, uma local, ou uma cujas coordenadas cada Release preenche — é fixada ou publicada aí como em qualquer outro lugar. Uma compilação aí não é recusada, mas uma entrada externa que o seu lockfile fixa e que a cache já não contém não é obtida novamente para a reparar: a renderização recebe a mesma frase no lugar dessa entrada, da forma como recebe a da postura offline, e reporta-a. O local onde artifact_cache_dir coloca a cache não altera nada aqui, porque o diretório é juntado a qualquer raiz que tenha sido encontrada. Os comandos que apenas leem continuam a responder.
Esse último recurso tem uma exceção. Quando nada nomeou a raiz e o diretório de trabalho não ancora nada, um comando sobre uma Release ou um documento de entidade que nomeia esse ficheiro por um caminho absoluto volta a descobrir a raiz, subindo a partir da pasta onde o ficheiro está, e usa o que encontrar: o espaço de trabalho a que o ficheiro pertence ou, na falta de tudo, essa pasta. O ficheiro é aquele que --release nomeia em aggrega build e aggrega pull; a Release que aggrega validate, aggrega lint e aggrega inspect recebem, ou, caso contrário, o ficheiro que recebem; e o documento que aggrega pin, aggrega push e aggrega edit-document recebem. Assim, a Release de um projeto compilada a partir de fora do projeto lê a configuração do próprio projeto, tal como quando o comando corre dentro dele, e os avisos de configuração que o comando imprime são os desse espaço de trabalho. Quando a própria pasta do ficheiro também não ancora nada, essa pasta é a que o aviso do comando nomeia e aquela em que nenhuma cache é escrita. Um caminho relativo é lido em relação ao diretório onde executa o comando e não altera nada, e uma raiz nomeada, ou um diretório de trabalho que esteja ele próprio dentro de um espaço de trabalho, é usado tal como está. O servidor do assistente aplica a mesma regra a uma chamada que nomeia a sua Release ou o seu documento por um caminho absoluto.
Marcar a raiz com um bloco workspace: é a escolha explícita e a preferível; os marcadores de ficheiro e de diretório permitem que um projeto que não declarou um seja compilado na mesma.
Nomear explicitamente o ficheiro global
A camada global resolve por esta ordem:
--config <path>, a forma por invocação.- A variável de ambiente
AGGREGA_CONFIG. - A localização predefinida: no Windows,
aggrega\config.yamldentro do diretório que a variável de ambienteAPPDATAnomeia, e noutros sistemas,aggrega/config.yamldentro do diretório queXDG_CONFIG_HOMEnomeia, recorrendo a~/.config/aggrega/config.yaml.
As duas primeiras nomeiam um ficheiro explícito, pelo que um caminho que não existe é um erro ruidoso e não um recurso silencioso — pediu um ficheiro em particular. Um comando que lê a sua configuração para com uma frase que termina com o caminho, para que o possa copiar. aggrega config init é a exceção, porque criar esse ficheiro é a sua finalidade: cria o ficheiro nomeado e di-lo. A localização predefinida é carregada quando o ficheiro existe e é ignorada silenciosamente quando não existe. Seja qual for o ficheiro que resolva, os ficheiros do seu projeto continuam a sobrepor-se a ele.
Quando nenhuma destas resolve — nenhum ficheiro é nomeado, e as variáveis a partir das quais a localização predefinida é lida não estão definidas —, um comando que escreve o ficheiro global para e nomeia o que definir. Variáveis de ambiente enumera, por plataforma, as variáveis a partir das quais cada localização é lida.
Essa escolha também seleciona onde um comando que escreve configuração escreve. Um comando executado com --config <path> lê a sua configuração desse ficheiro e aplica a sua alteração a esse mesmo ficheiro, pelo que o que um comando escreve é o que o seguinte lê de volta.
O ficheiro em que um comando escreve por predefinição decorre da natureza da definição: as ferramentas de toda a máquina, como um registo, vão para o ficheiro global, enquanto as definições que participam na compilação, como uma associação de fornecedor ou um anexo de socket, vão para o ficheiro do projeto incluído no controlo de versões, para que acompanhem o projeto. Passe --global ou --workspace para substituir isto, e o comando imprime o ficheiro em que escreveu.
Ver também
- aggrega-config.md — os comandos
aggrega configque inicializam, inspecionam e congelam a configuração. - environment-variables.md — todas as variáveis com o prefixo
AGGREGA_, e onde são fornecidos os segredos. - global-flags.md —
--config,--workspace-roote as outras flags que todos os subcomandos aceitam. - schema/other/aggrega-config.md — todas as chaves de configuração, o seu tipo e a sua predefinição.
- aggrega-cache.md — o que
artifact_cache_dircontém efetivamente. - workspace-boundary.md — que caminhos ficam dentro do espaço de trabalho, e como os diretórios e ficheiros que esta configuração nomeia chegam para fora dele.
- aggrega-mcp.md — o servidor que o bloco
mcpconfigura.