Esquema da configuração do espaço de trabalho do Aggrega
Referência gerada. Não editar à mão — gerar novamente a partir do JSON Schema publicado.
ID do esquema: https://aggrega.ai/schemas/aggrega-config-v1beta1.schema.json
Ficheiro de configuração por espaço de trabalho consumido pela CLI aggrega. Encontra-se em .aggrega-config.yaml. O bloco workspace é o marcador da raiz: a sua presença marca a raiz do espaço de trabalho, e contém apenas diretórios de catálogo. Todas as outras chaves são definições e encontram-se no nível superior, nestas classes — de onde o conteúdo é obtido, fixado e guardado em cache (seleção do registo, offline, comportamento de auto-pull e de fixação, localizações e limites máximos de tamanho das caches de artefactos e de módulos compilados), como se confia no conteúdo (assinatura e comportamento da verificação de assinaturas), com que rigor a autoria é avaliada (ajustes de lint por regra, rigor quanto a descontinuações e a indicação da release de autoria), que plugins Wasm estão anexados a todo o espaço de trabalho (governação, linter, importador e associações de renderização do fornecedor por destino) e como a CLI é executada (concorrência, serviço e limites máximos de remoção da cache de análise do daemon). As propriedades abaixo são a lista completa e oficial; este resumo nomeia as classes em vez das chaves, pelo que acrescentar uma chave não o pode tornar falso. Forma plana de nível superior, sem envelope apiVersion/kind, distinta do conteúdo do catálogo. Disciplina de evolução do esquema: acrescentar uma nova chave de nível superior é um incremento SemVer-MINOR (aditivo); remover ou deslocar uma chave, ou tornar uma restrição mais rígida, é uma rutura SemVer-MAJOR.
Tipo de nível superior: object
Propriedades
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
workspace | objeto | não | Marcador da raiz do espaço de trabalho. A sua presença, por si só, marca o diretório como raiz do espaço de trabalho; contém apenas os diretórios de catálogo que definem a raiz — os do próprio espaço de trabalho e os que uma Release recebe como seus. Todas as definições que não definem a raiz encontram-se no nível superior e não aqui. Para marcar uma raiz sem diretórios de catálogo incorporados no projeto, escreve-se workspace: {}. |
default_registry | string | não | Registo OCI predefinido no qual as entidades são publicadas e a partir do qual as dependências são resolvidas quando uma entidade não nomeia explicitamente um registo: aggrega push publica nele e aggrega pull obtém a partir dele. A predefinição é hub.aggrega.ai. Escreve-se o name de uma entrada sob registries, que passa então a representar o host dessa entrada; o próprio host; ou o host seguido de / e de um caminho de repositório, como ghcr.io/acme ou harbor.example.com/platform. Um nome é comparado primeiro: um valor que é o name de uma entrada é o host dessa entrada, mesmo quando também está escrito como um host, pelo que a publicação, o pull, a verificação de assinaturas e todas as definições de confiança por registo usam esse único host; um valor com o qual duas entradas são nomeadas é recusado por ambiguidade, e um nome seguido de um caminho é recusado, porque um nome representa o host de uma entrada e não uma localização sob ele. Qualquer outro valor tem de ser um host, escrito na grafia sob a qual a sua política de confiança é mantida: um nome de host em minúsculas que contém um ponto (registry.example.com), localhost, um único nome seguido de uma porta (registry:5000), um endereço IPv4 ou um endereço IPv6 entre parênteses retos ([::1]), cada um com um :port opcional e sem esquema, credenciais, espaços em branco nem maiúsculas — opcionalmente seguido de um caminho de repositório: um ou mais segmentos de letras minúsculas e algarismos unidos por /, que podem ser separados dentro de um segmento por ., _, __ ou hífenes, sem tag, digest nem / final. O caminho é onde as coisas são publicadas e obtidas: cada entidade publicada através do registo predefinido é publicada sob <host>/<path>/, e cada entidade resolvida através dele é obtida a partir daí, pelo que aquilo que um publica o outro encontra. Nunca faz parte da forma como se confia num registo: a entrada de registries cuja política se aplica, um início de sessão, um requisito de assinatura e as identidades de confiança são todos encontrados apenas pelo host. A porta 443 num host alcançado por HTTPS é a porta predefinida desse host, e escrevê-la é recusado, indicando a grafia a escrever sem ela; localhost e os restantes endereços de loopback são alcançados por HTTP simples, pelo que aí 443 é uma porta comum e é mantida. Um valor vazio não nomeia nenhum registo predefinido. O valor é avaliado quando a configuração é carregada e não por este esquema, porque a entrada a que um nome se refere pode estar declarada noutro ficheiro de configuração: é lido depois de todos os ficheiros de configuração e da variável de ambiente AGGREGA_DEFAULT_REGISTRY, e recusado com as mesmas palavras, seja qual for o que o definiu, nomeando esse ficheiro ou a variável. A flag --registry que nomeia o destino de uma publicação para uma única invocação é comparada com os nomes das entradas da mesma forma; qualquer outro valor que tenha pode ser uma referência, e o host que essa referência nomeia está sujeito à mesma grafia e é onde a publicação chega, sem caminho de repositório. O host é avaliado apenas pela sua grafia: não se verifica se o nome é resolvido nem se um registo responde aí. Predefinição: "hub.aggrega.ai" |
offline | booleana | não | Quando é true, a compilação não contacta nenhum registo; apenas são consultados os artefactos em cache e o conteúdo de catálogo incorporado no projeto. A predefinição é false. Predefinição: false |
auto_pull | booleana | não | Quando é false (predefinição), aggrega build é só de leitura: nunca escreve fixações de fontes, e um ficheiro de bloqueio por release em falta ou incompleto interrompe a compilação de forma bem visível com um diagnóstico para executar primeiro aggrega pull --release <release>. Quando é true, aggrega build executa um passo de pull dentro do próprio processo antes de compilar — resolvendo as dependências da Release para o ficheiro de bloqueio e a cache — pelo que uma primeira compilação com uma Release não exige um passo de pull explícito. A mesma adesão para uma única compilação está disponível na linha de comandos como aggrega build --auto-pull; pull continua a ser o único que escreve o ficheiro de bloqueio. offline: true não desativa o passo de pull: este é executado sobre aquilo que a máquina já contém — a cache e os diretórios de catálogo locais — sem alcançar um registo, e uma referência que nenhuma das duas contém interrompe a compilação com a própria recusa do pull, que nomeia essa referência. Predefinição: false |
pin_sources_at_pull | booleana | não | Quando é false (predefinição), um pull não regista nenhuma fixação junto a uma entidade: sobre uma Recipe ou uma FeatureRecipe de um dos diretórios de catálogo deste espaço de trabalho que a Release compila, é interrompido quando o entity.lock junto à entidade não regista uma fixação para cada elemento que a entidade lê — um source: remoto cujas coordenadas estão escritas por extenso, um ficheiro que uma entrada de artifacts importa, ou cada ficheiro de um source: local junto à entidade — nomeando a entidade, cada elemento e a sua classe, e aggrega pin como o passo que os regista. A fixação é o passo do autor da entidade, pelo que uma entidade que ninguém fixou ainda não está pronta a ser consumida. Quando é true, cada pull neste espaço de trabalho executa, em vez disso, esse passo, sobre as mesmas entidades, escrevendo os mesmos bytes de entity.lock que aggrega pin escreve; é assim que um espaço de trabalho que consome entidades que outra pessoa não fixou regista as respetivas fixações uma única vez, em vez de ser interrompido. Uma compilação que preenche o seu próprio ficheiro de bloqueio é um pull e segue esta definição. aggrega pull --pin-sources fixa para uma única invocação e --pin-sources=false interrompe para uma única invocação, independentemente do que esta definição diga. Uma entidade resolvida a partir da cache e não de um diretório de catálogo não tem onde escrever um bloqueio e nunca é fixada nem retida por um pull. Predefinição: false |
pin_sources_at_push | booleana | não | Quando é true, cada aggrega push neste espaço de trabalho executa o passo de fixação do autor da entidade sobre a entidade que publica antes de a empacotar, pelo que o entity.lock que o passo escreve junto à entidade faz parte daquilo que é publicado; quando é false (predefinição), o push não executa nenhum passo de fixação e recusa uma Recipe ou uma FeatureRecipe cujo entity.lock não regista todas as fixações que esse passo registaria, nomeando aggrega pin. O passo escreve junto à entidade, pelo que só é executado onde a entidade tem uma localização com permissão de escrita, que um push tem sempre: publica uma entidade nomeada pelo seu documento. aggrega push --pin-sources fixa para uma única invocação e --pin-sources=false não, independentemente do que esta definição diga. É o mesmo passo que aggrega pin executa, escrevendo os mesmos bytes. Predefinição: false |
artifact_cache_dir | string | não | Diretório local da cache de artefactos/conteúdo (pulls de registos, manifestos OCI, fixtures compiladas). A predefinição é .aggrega/cache. Por convenção, deve ser incluído no gitignore. O caminho é interpretado relativamente à raiz do espaço de trabalho, seja qual for o local a partir do qual o comando é executado; um valor absoluto é recusado quando a configuração é carregada, porque cada leitor desta definição o resolve face a essa raiz e um caminho absoluto nomearia uma localização que eles nunca alcançam. A cache pode ficar dentro de um diretório de catálogo — a predefinida fica, uma vez que um diretório de catálogo é frequentemente a raiz do espaço de trabalho — mas não pode SER um: um varrimento do catálogo passa por cima da cache, pelo que um valor que nomeia um diretório de catálogo deixa todo o conteúdo desse diretório fora do varrimento. Um valor que nomeia a própria raiz do espaço de trabalho (., ou qualquer grafia que se reduza a ela) é recusado quando a configuração é carregada, exatamente por esse motivo. Um valor que nomeia qualquer outro diretório de catálogo não é recusado: carrega sem erros e o varrimento não encontra depois nada nesse diretório, pelo que manter a cache fora dos diretórios listados em workspace.catalog_dirs é uma verificação que cabe ao utilizador. Distinto de parse_cache, que limita a cache de análise em memória do daemon, e de compiled_module_cache, que limita o armazenamento de módulos compilados de toda a máquina. Predefinição: ".aggrega/cache" |
skip_signature_verification | booleana | não | Desativação global e bem visível da verificação de assinaturas. Quando é true, a verificação de assinaturas fica desativada em todos os registos, incluindo a linha de base obrigatória do hub. Destina-se a cenários de emergência (break-glass) e de desenvolvimento; nunca é silenciosa — onde quer que um pull tivesse verificado uma assinatura, avisa que a verificação foi desativada globalmente. A predefinição é false. Predefinição: false |
build | objeto | não | Ajustes de rigor em tempo de compilação e indicações de autoria. authoring_release fornece ao LSP uma indicação current Release para os diagnósticos inline; halt_on_deprecated_severity controla a forma como a compilação reage ao consumo de entidades descontinuadas; yaml_indent define a largura da indentação de cada artefacto YAML renderizado. |
plugins | objeto | não | Anexos de plugins Wasm ao nível do espaço de trabalho. Cada socket (governação, linter, importador) recebe um array de referências a plugins; a compilação invoca a função de entrada documentada de cada plugin segundo o contrato do respetivo socket. A lista providers associa as capacidades aos plugins de renderização do fornecedor que as servem. |
lint | objeto | não | Ajustes de rigor por regra. |
parse_cache | objeto | não | Limites máximos de remoção da cache de análise do daemon. Ambos os limites máximos se aplicam em simultâneo — o ciclo de remoção LRU é executado após cada inserção na cache e remove as entradas usadas menos recentemente até que tanto o número de entradas como o total de bytes estejam dentro dos limites. Zero em qualquer um dos dois significa unbounded on that axis, útil em cenários de CI em que a cache existe apenas durante uma invocação. Distinto de artifact_cache_dir, que é a cache de conteúdo em disco. |
compiled_module_cache | objeto | não | Limite máximo de tamanho para a cache em disco de módulos compilados, o armazenamento de código máquina que o compilador reutiliza para que um plugin Wasm seja compilado uma vez por máquina em vez de uma vez por compilação. É partilhada por todos os espaços de trabalho da máquina, pelo que esta chave pertence ao ficheiro de configuração global quando se pretende uma única resposta para toda a máquina. O limite máximo é aplicado uma vez por invocação, antes de qualquer plugin ser carregado, removendo entradas inteiras a começar pelas compiladas há mais tempo até que o restante caiba — nunca enquanto uma compilação está a decorrer. Remover uma entrada custa uma recompilação posterior e nada mais, pelo que é seguro baixar o limite máximo. aggrega cache status indica o tamanho atual do armazenamento, e aggrega cache evict --max-size reduz-o a pedido para um limite máximo indicado na linha de comandos. Distinto de artifact_cache_dir (conteúdo obtido dos registos) e de parse_cache (a cache de análise em memória do daemon). |
concurrency | objeto | não | Definições de concorrência do despacho de pedidos do daemon. O daemon lê os pedidos a partir de um único fluxo stdin e executa cada um através de um conjunto de workers que esvazia uma fila de pedidos limitada; as respostas são emitidas pela ordem de chegada dos pedidos, independentemente da ordem de conclusão. |
serve | objeto | não | Definições de comportamento do daemon (aggrega serve) para o compilador como serviço consumido pelas integrações com IDE. |
mcp | objeto | não | Definições do servidor Model Context Protocol (aggrega mcp). transport escolhe a forma como o servidor é alcançado — através da entrada e da saída padrão do processo, ou através de HTTP — e é lido seja qual for a escolha. announce_tools também é lido em ambos os transportes, porque as ferramentas oferecidas a um cliente são uma propriedade do servidor e não da forma como um cliente o alcançou. Todas as outras chaves configuram o listener que o transporte HTTP inicia e não são usadas enquanto o servidor comunica através da entrada e da saída padrão — listen incluída, que aí só é lida para que o servidor possa dizer, numa linha no seu fluxo de erros, que o endereço não é usado. Cada chave abaixo indica qual é o seu caso. Distinto de serve, que configura o daemon de backend do editor. |
registries | RegistryConfig[] | não | Definições por registo e política de confiança de assinaturas, indexadas pelo host do registo. Um registo que não esteja listado aqui usa as predefinições: uma assinatura presente é verificada e uma assinatura ausente é tolerada, exceto para hub.aggrega.ai, cuja linha de base incorporada exige uma assinatura verificada mesmo sem nenhuma entrada explícita. Uma entrada explícita para um host substitui a linha de base desse host. Predefinição: [] |
signing | SigningConfig | não | Bloco de assinatura de nível superior, aplicável a todos os registos: os URL dos serviços keyless, um caminho opcional de chave para assinatura com chave e a posição de confiança comum a todos os registos (required e kinds). Um bloco signing por registo substitui as predefinições dos endpoints para esse host e tem a mesma posição required/kinds com âmbito restrito a esse host — um nome, uma função, o âmbito dado pela colocação. A política required/kinds de nível superior compõe-se de forma monótona ao longo da cascata de configurações. Segurança: este bloco não contém nenhum material secreto — o token de identidade OIDC nunca é um campo de configuração (é fornecido em tempo de execução através de uma flag ou do ambiente OIDC envolvente) e key_path é um caminho para um ficheiro de chave, nunca bytes de chave inline. |
Não são permitidas propriedades adicionais.
aggrega-config.workspace
Marcador da raiz do espaço de trabalho. A sua presença, por si só, marca o diretório como raiz do espaço de trabalho; contém apenas os diretórios de catálogo que definem a raiz — os do próprio espaço de trabalho e os que uma Release recebe como seus. Todas as definições que não definem a raiz encontram-se no nível superior e não aqui. Para marcar uma raiz sem diretórios de catálogo incorporados no projeto, escreve-se workspace: {}.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
catalog_dirs | string[] | não | Diretórios de catálogo opcionais a partir dos quais este espaço de trabalho lê entidades locais, consultados antes de recorrer ao registo. Cada entrada é um caminho do sistema de ficheiros, resolvido relativamente ao ficheiro que a declara. A lista é uma pilha de pesquisa ordenada em que vence o primeiro: o diretório listado em primeiro lugar que declara uma identidade é o seu proprietário, e a mesma identidade num diretório posterior fica ocultada. O diretório catalog na raiz do espaço de trabalho também é lido, depois de todas as entradas listadas e apenas quando existe — a menos que uma entrada listada já o contenha, caso em que é lido como parte dessa entrada — pelo que listar um diretório acrescenta àquilo que o espaço de trabalho já lia em vez de o substituir. Omitir esta chave e escrevê-la como uma lista vazia são declarações diferentes: quando é omitida, o espaço de trabalho continua a ler catalog; quando é escrita como [], não lê nenhum catálogo local, que é a forma de um espaço de trabalho dizer que não tem nenhum. Uma Release que recebe diretórios de catálogo próprios sob releases lê esses em vez desta lista. Com âmbito de raiz: os diretórios de catálogo locais pertencem a esta raiz do espaço de trabalho, pelo que se encontram no marcador da raiz e não no nível superior. |
catalog_dirs_append | string[] | não | Acréscimo opcional, apenas no fim, à lista catalog_dirs efetiva. Em cada camada de precedência, as entradas indicadas aqui são concatenadas à lista de base resolvida, permitindo que as configurações do espaço de trabalho e globais componham os diretórios de catálogo em vez de os ocultar. Interação na mesma camada: quando catalog_dirs e catalog_dirs_append são especificados numa mesma camada, o valor resolvido nessa camada é a lista de base seguida da lista acrescentada. Predefinição: [] |
releases | mapa de ReleaseCatalogConfig | não | Diretórios de catálogo opcionais próprios de uma Release, para um espaço de trabalho que mantém várias variantes de catálogo lado a lado e compila cada Release com uma delas. Cada chave é um ficheiro de Release, escrito como um caminho relativo ao ficheiro que a declara; cada valor tem catalog_dirs e catalog_dirs_append com o significado que têm neste bloco, com âmbito restrito a essa única Release. Uma Release nomeada aqui lê o seu próprio catalog_dirs em vez da lista deste bloco, seguido do seu próprio catalog_dirs_append; uma entrada que omite catalog_dirs mantém a lista deste bloco e acrescenta-lhe depois o seu catalog_dirs_append. A ordem de pesquisa, o diretório catalog na raiz do espaço de trabalho e aquilo que uma lista vazia significa são os mesmos que para a própria lista deste bloco, e uma Release que este mapa não nomeia lê a lista deste bloco exatamente como antes. A Release lê estes diretórios seja qual for a forma como é compilada — num terminal, a partir de um editor através de aggrega serve, ou através de aggrega mcp — e um diretório --catalog continua a ser pesquisado antes deles para uma única invocação. Uma entrada que nomeia um ficheiro inexistente é recusada quando a configuração é carregada, nomeando a entrada e o ficheiro, pelo que mudar o nome de uma Release não pode alterar discretamente o catálogo com o qual é compilada. Entre ficheiros de configuração, a entrada de cada Release compõe-se da mesma forma que as próprias chaves deste bloco: o catalog_dirs de um ficheiro mais próximo para essa Release substitui o de um ficheiro mais distante, e o catalog_dirs_append de cada ficheiro para ela é acrescentado pela ordem da cascata. AGGREGA_CATALOG_DIRS define a lista deste bloco e não alcança nenhuma entrada daqui. Uma operação que não diz respeito a nenhuma Release em particular — um lint ou uma validação de todo o catálogo, a pesquisa de uma entidade pelo nome ou a listagem das entidades do espaço de trabalho num editor — lê a lista deste bloco e não estas. |
Não são permitidas propriedades adicionais.
aggrega-config.build
Ajustes de rigor em tempo de compilação e indicações de autoria. authoring_release fornece ao LSP uma indicação current Release para os diagnósticos inline; halt_on_deprecated_severity controla a forma como a compilação reage ao consumo de entidades descontinuadas; yaml_indent define a largura da indentação de cada artefacto YAML renderizado.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
authoring_release | string | não | Caminho para um ficheiro YAML de Release que o LSP trata como o contexto current Release para os diagnósticos inline. Opcional. |
yaml_indent | integer | não | Largura da indentação (em espaços) de cada artefacto YAML renderizado — ficheiros docker-compose, modelos e valores de charts Helm, e manifestos do Kubernetes. A predefinição é 2, a largura convencional para esses formatos. Mínimo: 2. Máximo: 9. Predefinição: 2 |
halt_on_deprecated_severity | string (enum) | não | Severidade, no conjunto ordenado warning < error < retracted, a partir da qual um marcador de descontinuação registado interrompe a compilação. Rege os dois locais em que um marcador é registado: o ficheiro de bloqueio, para tudo o que uma compilação reproduz byte a byte, e o registo de confiança dos plugins ao lado dele, para um plugin anexado num papel que devolve um veredicto de aceitação ou rejeição — um anexo plugins.governance em ir-verdict ou render-verdict, e todos os anexos plugins.linter. Um ajuste, uma regra, ambos os armazenamentos. Não definida por predefinição, e não definida significa que nenhum marcador registado interrompe nada: um marcador é registado face a uma versão que já foi fixada, pelo que uma compilação que foi bem-sucedida uma vez continua a sê-lo. Notificação e resolução são dois eixos separados e nenhum deles é este ajuste. Todas as superfícies que leem qualquer um dos dois registos indicam cada referência descontinuada que fixam e cada plugin de confiança que tenha um marcador — em qualquer severidade — nomeando-o, com a sua severidade e a sua mensagem: aggrega build, aggrega validate --release, aggrega lint --release, o daemon voltado para o editor e as ferramentas build, describe e validate nativas de IA. Assim, elevar este limiar nunca reduz aquilo que é comunicado. Este ajuste rege apenas a compilação: interrompe aggrega build (e a ferramenta build nativa de IA, que é a mesma operação), enquanto as superfícies que reportam nomeiam o marcador e prosseguem. Apenas um marcador retracted afeta a versão para a qual uma referência é resolvida, e fá-lo quando aggrega pull escolhe uma versão, não na compilação. Valores permitidos: "warning", "error", "retracted" |
Não são permitidas propriedades adicionais.
aggrega-config.plugins
Anexos de plugins Wasm ao nível do espaço de trabalho. Cada socket (governação, linter, importador) recebe um array de referências a plugins; a compilação invoca a função de entrada documentada de cada plugin segundo o contrato do respetivo socket. A lista providers associa as capacidades aos plugins de renderização do fornecedor que as servem.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
governance | PluginRef[] | não | Os plugins do socket de governação. Cada entrada nomeia o role do pipeline em que está anexada (annotation-transform, label-transform, ir-verdict ou render-verdict); o papel define tanto aquilo que o plugin pode emitir como a sua função de entrada predefinida (annotation-transform → transform_annotations; label-transform → mutate; ir-verdict → verdict_ir; render-verdict → verdict_render). Predefinição: [] |
governance_append | PluginRef[] | não | Acréscimo, apenas no fim, à lista governance efetiva. As entradas indicadas aqui são concatenadas à lista de base resolvida em cada camada de precedência, permitindo que as configurações do espaço de trabalho e globais componham os anexos de governação em vez de os ocultar. Predefinição: [] |
linter | PluginRef[] | não | Os plugins do socket linter. Função de entrada predefinida: lint_rules. As exportações de um plugin linter têm de começar por lint_, pelo que function: numa destas entradas nomeia uma exportação com esse prefixo. Predefinição: [] |
linter_append | PluginRef[] | não | Acréscimo, apenas no fim, à lista linter efetiva. A mesma semântica de compor sem ocultar que governance_append. Predefinição: [] |
importer | FixedEntryPluginRef[] | não | Os plugins do socket importador. O socket chama a função de entrada import; um anexo não nomeia nenhuma. Predefinição: [] |
importer_append | FixedEntryPluginRef[] | não | Acréscimo, apenas no fim, à lista importer efetiva. A mesma semântica de compor sem ocultar que governance_append. Predefinição: [] |
providers | FixedEntryPluginRef[] | não | Seleções do fornecedor por capacidade. Cada entrada associa uma capacidade do fornecedor (o nome simples da capacidade que uma Recipe associa através de spec.capability, por exemplo helm ou compose) à identidade simples do plugin de renderização do fornecedor que a serve (a identidade da entidade Plugin, os seus metadata.pluginType e metadata.name unidos por uma barra, por exemplo provider/helm), com um :version final opcional nas mesmas três formas de uma fixação de versão (simples, exata :1.0.0 ou intervalo compatível com a versão principal :^1.0.0). Esta é a superfície de desambiguação e de substituição para um catálogo federado em que mais de um plugin de fornecedor serve a mesma capacidade: a associação seleciona o plugin de qual publicador renderiza essa capacidade. Quando uma capacidade é servida por exatamente um plugin de fornecedor, não é necessária nenhuma entrada. Em toda a lista composta é permitida exatamente uma entrada por capacidade; uma capacidade duplicada interrompe a resolução de forma bem visível. A resolução ocorre no pull: o pull regista a associação resolvida no ficheiro de bloqueio por Release, e a compilação lê o ficheiro de bloqueio — uma alteração aqui depois de um pull só é adotada no pull seguinte, pelo que a saída da compilação é invariante face a ela (saída determinística). Cada compilação e cada validação de uma Release verifica também cada entrada daqui, quer uma Recipe peça ou não a sua capacidade: uma entrada que nomeia um plugin que a compilação contém e que não serve a capacidade da entrada provoca uma interrupção, nomeando aquilo que esse plugin serve e uma grafia a uma edição de distância, quando existe uma; uma entrada que nomeia uma capacidade e nenhum plugin, quando nenhum plugin de fornecedor que a compilação lê serve essa capacidade, é reportada como um aviso em vez de interromper, porque o plugin que a serve pode ser um que apenas outra Release lê; e uma entrada para uma capacidade que um plugin serve mas que esta Release nunca pede é permitida e não é reportada de todo, uma vez que as entradas são escritas para todo o espaço de trabalho e uma compilação é de uma única Release. Uma capability que contém dois pontos é recusada quando a configuração é carregada: o spec.capability de uma Recipe é lido como a capacidade até aos seus últimos dois pontos e uma fixação de versão depois deles, pelo que nenhuma Recipe poderia alcançar uma entrada assim. Uma entrada em falta para uma capacidade servida sem ambiguidade não é um erro; uma entrada em falta para uma capacidade servida de forma ambígua interrompe o pull de forma bem visível, listando os plugins candidatos. A coexistência de versões é preservada: a associação seleciona o repositório do plugin por capacidade, e a própria fixação de versão em spec.capability de cada Recipe seleciona a versão dentro desse repositório, pelo que duas Recipes que fixam versões diferentes de um mesmo fornecedor continuam a coexistir. Predefinição: [] |
providers_append | FixedEntryPluginRef[] | não | Acréscimo, apenas no fim, à lista providers efetiva. As entradas indicadas aqui são concatenadas à lista de base resolvida em cada camada de precedência, permitindo que as configurações do espaço de trabalho e globais componham as associações do fornecedor em vez de as ocultar. A mesma semântica de compor sem ocultar que governance_append. A regra de uma entrada por capacidade aplica-se à lista composta, pelo que uma entrada acrescentada que nomeia uma capacidade já associada por uma camada inferior interrompe a resolução de forma bem visível. Predefinição: [] |
cli | CLIPluginRef[] | não | Os plugins de extensão da CLI instalados como comandos aggrega de nível superior. Cada entrada fixa um plugin de CLI pela sua referência de artefacto resolvida e fixada numa versão e pelo digest de conteúdo dos bytes do guest para os quais essa referência foi resolvida no momento da instalação. Ao contrário das quatro listas de sockets transversais, cuja lista de base é substituída na íntegra ao longo da cascata de configurações, a lista da CLI compõe-se: um plugin de CLI na configuração global regista os seus comandos em todos os espaços de trabalho, um numa configuração do espaço de trabalho regista-se apenas nesse projeto, e ambos se registam em conjunto — pelo que não precisa de um complemento _append. Os nomes de comando e a ajuda com que cada plugin contribui provêm da autodescrição do próprio plugin, lida a partir da cache de describe em disco indexada por digest (carregar o guest é o recurso alternativo com a cache fria); a lista tem apenas a fixação. Na invocação do comando, os bytes resolvidos voltam a passar por hash e são comparados com digest; uma divergência interrompe o comando de forma bem visível e indica que se refaça a fixação, pelo que um plugin cujos bytes mudaram desde que foi fixado nunca é executado sem ser notado. Predefinição: [] |
Não são permitidas propriedades adicionais.
aggrega-config.lint
Ajustes de rigor por regra.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
publishing_discipline | objeto | não | Interruptores para todo o espaço de trabalho sobre o conjunto de regras do linter de publicação. As flags allow_* flexibilizam verificações dissuasoras individuais. A imutabilidade dos artefactos não é configurável aqui: aggrega push recusa-se incondicionalmente a substituir uma versão publicada. |
Não são permitidas propriedades adicionais.
aggrega-config.lint.publishing_discipline
Interruptores para todo o espaço de trabalho sobre o conjunto de regras do linter de publicação. As flags allow_* flexibilizam verificações dissuasoras individuais. A imutabilidade dos artefactos não é configurável aqui: aggrega push recusa-se incondicionalmente a substituir uma versão publicada.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
allow_dynamic_refs | booleana | não | Quando é true, o linter de publicação aceita as construções de JSON Schema $dynamicRef / $dynamicAnchor no conteúdo do catálogo. A predefinição é false; estas construções são desaconselhadas porque tornam não local a composição de esquemas em tempo de compilação. Predefinição: false |
allow_id_overrides | booleana | não | Quando é true, o linter de publicação aceita substituições de $id em subesquemas dentro do conteúdo de esquema de uma entidade. A predefinição é false; as substituições de $id quebram a convenção de um identificador canónico por esquema da qual dependem tanto o resolvedor como o validador de JSON Schema. Predefinição: false |
allow_direct_x_aggrega_extensions | booleana | não | Quando é true, a verificação dissuasora em tempo de compilação aceita as palavras-chave x-aggrega-selector e x-aggrega-inject escritas diretamente no conteúdo do esquema. A predefinição é false; o caminho de autoria recomendado é usesSchema (para sockets de dependência) ou featuresSchema (para associações de credenciais), que o compilador compõe nessas palavras-chave. Predefinição: false |
allow_aggrega_ai_prefix | booleana | não | Quando é true, o linter de publicação aceita chaves de anotação que usam os espaços de nomes reservados aggrega.ai/ e feature.aggrega.ai/ fora dos seus contextos canónicos. A regra de prefixos reservados controla os metadata.annotations das entidades de catálogo: o prefixo simples aggrega.ai/ é nativo da plataforma (as chaves de anotação bem conhecidas estão isentas independentemente desta flag); o prefixo feature.aggrega.ai/ só é canónico no tipo Feature. A predefinição é false. Os operadores definem-na quando as ferramentas empresariais precisam legitimamente de usar um prefixo reservado; flexibiliza ambos os prefixos em conjunto. Predefinição: false |
allow_nonstandard_names | booleana | não | Quando é true, o linter de publicação aceita nomes de entidades de catálogo que não seguem as convenções de nomenclatura documentadas do projeto. A predefinição é false; uma nomenclatura coerente é fundamental para o resolvedor, a seleção por etiquetas e a ergonomia dos revisores. Predefinição: false |
allow_category_mismatches | booleana | não | Quando é true, o linter de publicação suprime a regra category-matches-directory. A convenção do catálogo padrão exige que os Components sob core/false |
allow_undeclared_recipe_provides | booleana | não | Quando é true, o linter de publicação suprime a regra provides-declared-by-component. Essa regra reporta cada chave que uma Recipe publica em spec.provides e que o Component nomeado pelo seu spec.implements não declara no pilar provides do seu spec.schema. As duas são superfícies separadas: aquilo que uma Recipe publica é o valor que um consumidor recebe, enquanto aquilo que o Component declara é o contrato de saída face ao qual uma referência inject from: é verificada — pelo que uma chave publicada sem ser declarada faz com que uma referência assim seja interrompida. De resto, uma Recipe que publica mais do que o seu Component declara é aceite em tempo de compilação, razão pela qual a constatação é consultiva e não uma recusa de publicação. A predefinição é false. Predefinição: false |
allow_connection_credential_mismatches | booleana | não | Quando é true, o linter de publicação suprime a regra connection-credential-matches-target-key, que aggrega lint --release executa sobre a Release que nomeia: a Release, o Aggregate que ela implementa e os Components que as instâncias desse Aggregate usam. Para cada ligação cujo destino declara a chave que exige aos seus chamadores, a regra compara aquilo a que as duas extremidades fazem referência: a credencial que a ligação apresenta e a chave que o destino mantém no seu próprio slot. Reporta duas extremidades que nomeiam segredos diferentes e uma chave declarada apenas numa extremidade, e nunca cita nenhum dos dois. Nenhuma das extremidades consegue ver os anexos da outra, pelo que as duas só coincidem por disciplina de autoria — normalmente um único parâmetro que alimenta ambas — e uma compilação aceita-as de qualquer forma, razão pela qual a constatação é consultiva. Um espaço de trabalho cujas duas extremidades diferem deliberadamente opta por sair aqui. A predefinição é false. Predefinição: false |
Não são permitidas propriedades adicionais.
aggrega-config.parse_cache
Limites máximos de remoção da cache de análise do daemon. Ambos os limites máximos se aplicam em simultâneo — o ciclo de remoção LRU é executado após cada inserção na cache e remove as entradas usadas menos recentemente até que tanto o número de entradas como o total de bytes estejam dentro dos limites. Zero em qualquer um dos dois significa unbounded on that axis, útil em cenários de CI em que a cache existe apenas durante uma invocação. Distinto de artifact_cache_dir, que é a cache de conteúdo em disco.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
max_entries | integer | não | Limite máximo do número de análises em cache. A predefinição é 1000. 0 desativa o eixo do número de entradas (nenhuma remoção desencadeada pelo número de entradas). Mínimo: 0. Predefinição: 1000 |
max_bytes | integer | não | Limite máximo do tamanho cumulativo, em bytes, dos documentos que a cache contém. A predefinição é 100000000 (100 MB). 0 desativa o eixo dos bytes (nenhuma remoção desencadeada pelo total de bytes). Mínimo: 0. Predefinição: 100000000 |
Não são permitidas propriedades adicionais.
aggrega-config.compiled_module_cache
Limite máximo de tamanho para a cache em disco de módulos compilados, o armazenamento de código máquina que o compilador reutiliza para que um plugin Wasm seja compilado uma vez por máquina em vez de uma vez por compilação. É partilhada por todos os espaços de trabalho da máquina, pelo que esta chave pertence ao ficheiro de configuração global quando se pretende uma única resposta para toda a máquina. O limite máximo é aplicado uma vez por invocação, antes de qualquer plugin ser carregado, removendo entradas inteiras a começar pelas compiladas há mais tempo até que o restante caiba — nunca enquanto uma compilação está a decorrer. Remover uma entrada custa uma recompilação posterior e nada mais, pelo que é seguro baixar o limite máximo. aggrega cache status indica o tamanho atual do armazenamento, e aggrega cache evict --max-size reduz-o a pedido para um limite máximo indicado na linha de comandos. Distinto de artifact_cache_dir (conteúdo obtido dos registos) e de parse_cache (a cache de análise em memória do daemon).
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
max_bytes | integer | não | Limite máximo dos bytes que a cache de módulos compilados ocupa em disco. A predefinição é 53687091200 (50 GiB), um teto que trava o crescimento ilimitado e não um orçamento destinado a fazer-se sentir — um único plugin compilado chega a centenas de megabytes, pelo que uma máquina que compila muitas versões de plugins acumula gigabytes. Deve ser definido acima daquilo que uma compilação compila: o limite máximo é aplicado antes de uma compilação compilar o que quer que seja, pelo que um limite máximo abaixo do conjunto de trabalho de uma única compilação faz com que cada compilação descarte e recompile os mesmos módulos, e o armazenamento deixa de poupar o que quer que seja. Como o limite máximo é aplicado primeiro e a compilação escreve depois aquilo que compila, o armazenamento pode ficar acima do limite máximo entre compilações; volta a ser reduzido no início da compilação seguinte. 0 desativa o limite máximo (o armazenamento cresce sem limite e nada é alguma vez removido automaticamente). Como o armazenamento é um único diretório que todos os espaços de trabalho partilham, este limite máximo não é por projeto, mesmo quando o próprio ficheiro de um projeto o contém: o valor é resolvido da mesma forma que qualquer outra chave, prevalecendo o ficheiro mais próximo, mas o armazenamento continua a ter um único tamanho. O limite máximo em vigor é o da compilação mais recente, pelo que dois projetos que o definem de forma diferente produzem ambos efeito, alternadamente, e um limite máximo baixo num deles descarta código máquina que o outro compilou. Defini-lo uma vez no ficheiro de configuração global é o que dá a toda a máquina uma única resposta. aggrega config show --origin nomeia o ficheiro de onde provém o valor efetivo de cada definição. Mínimo: 0. Predefinição: 53687091200 |
Não são permitidas propriedades adicionais.
aggrega-config.concurrency
Definições de concorrência do despacho de pedidos do daemon. O daemon lê os pedidos a partir de um único fluxo stdin e executa cada um através de um conjunto de workers que esvazia uma fila de pedidos limitada; as respostas são emitidas pela ordem de chegada dos pedidos, independentemente da ordem de conclusão.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
pool_size | integer | não | Número de workers que atendem a fila de pedidos. A predefinição é 4, o que despacha até quatro pedidos em simultâneo; para executar os pedidos em série, pela ordem de chegada, define-se como 1. Um valor inferior a 1 é elevado para 1 quando o daemon arranca. Mínimo: 1. Predefinição: 4 |
Não são permitidas propriedades adicionais.
aggrega-config.serve
Definições de comportamento do daemon (aggrega serve) para o compilador como serviço consumido pelas integrações com IDE.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
build_on_inspect | booleana | não | Determina se o daemon executa a etapa de renderização de artefactos ao inspecionar um grafo IR, para que os avisos informativos que aggrega build emite durante a renderização apareçam também como problemas no editor. Não acrescenta nenhuma das verificações em que uma compilação é interrompida. Em nenhum dos casos é escrito nada em disco — nenhum artefacto renderizado, nenhum diretório de saída, nenhum ficheiro de bloqueio — e a etapa de renderização nunca altera o grafo, pelo que, onde a inspeção responde com um, é o mesmo grafo em ambos os casos. A predefinição é false, em linha com aggrega inspect: o comando do terminal não chega à etapa de renderização ao inspecionar um grafo, pelo que também não emite nenhum aviso desse tipo, e uma inspeção no editor que não emite nenhum mostra o mesmo que o terminal mostra. Para pedir ao editor essa camada adicional, define-se como true. Predefinição: false |
lint_on_validate | booleana | não | Determina se o daemon executa a verificação das convenções de publicação ao validar uma entidade de catálogo, para que as constatações que aggrega lint reporta sobre essa entidade apareçam também como problemas no editor. As constatações são informativas: um documento que as recebe continua a ser validado, e a sua Release continua a ser resolvida e renderizada. Só é executada a verificação que lê conteúdo local — não é consultado nenhum registo, nada é obtido e nada é escrito — e é avaliada sobre o buffer que o editor mantém e não sobre o ficheiro em disco, pelo que um nome corrigido deixa de ser reportado antes de ser guardado. A predefinição é false: uma sessão do editor indica se um documento está correto e nada diz sobre se uma entidade é publicável, até que se peça essa segunda camada. Para a pedir, define-se como true. Independentemente desta chave, um editor pode sempre pedir diretamente a verificação, e é também assim que se chega à comparação prévia à publicação com a versão publicada anteriormente. Predefinição: false |
Não são permitidas propriedades adicionais.
aggrega-config.mcp
Definições do servidor Model Context Protocol (aggrega mcp). transport escolhe a forma como o servidor é alcançado — através da entrada e da saída padrão do processo, ou através de HTTP — e é lido seja qual for a escolha. announce_tools também é lido em ambos os transportes, porque as ferramentas oferecidas a um cliente são uma propriedade do servidor e não da forma como um cliente o alcançou. Todas as outras chaves configuram o listener que o transporte HTTP inicia e não são usadas enquanto o servidor comunica através da entrada e da saída padrão — listen incluída, que aí só é lida para que o servidor possa dizer, numa linha no seu fluxo de erros, que o endereço não é usado. Cada chave abaixo indica qual é o seu caso. Distinto de serve, que configura o daemon de backend do editor.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
transport | string (enum) | não | Como o servidor é alcançado: stdio fala o protocolo através da entrada e da saída padrão do processo, que é a forma como o alcança um cliente que lança o comando como subprocesso; http serve-o através de HTTP no endereço que listen nomeia, e através de HTTPS onde tls nomeia um certificado e uma chave. aggrega mcp --transport stdio|http substitui esta chave para uma única invocação. A predefinição é stdio, pelo que um espaço de trabalho que nunca nomeia um transporte é servido através da entrada e da saída padrão, seja o que for que este bloco contenha além disso — um listener só arranca onde http é escolhido, aqui ou na linha de comandos. Qualquer outro valor é recusado quando a configuração é carregada. Define-se http na configuração de um servidor que os chamadores alcançam através da rede, e deixa-se a chave por definir onde é um cliente a lançar o próprio servidor: com stdio escolhido, um endereço em listen não é usado, e o servidor indica-o numa linha no seu fluxo de erros. Valores permitidos: "stdio", "http" Predefinição: "stdio" |
listen | string | não | Endereço ao qual o listener se associa quando o transporte HTTP é escolhido. Nomeia onde escutar e não escolhe nada: a escolha do transporte cabe a transport, e com stdio escolhido esta chave não é usada. São aceites duas formas: host:port para um endereço TCP, e unix: seguido de um caminho do sistema de ficheiros para um socket de domínio Unix. aggrega mcp --listen <address> substitui esta chave para uma única invocação. A predefinição é vazia, e o transporte HTTP precisa de um endereço vindo de um ou de outro: sem nenhum dos dois, um arranque que o escolha é recusado antes de qualquer associação. Um endereço em texto simples — alcançado sem certificado e chave em tls — só é aceite num endereço de loopback (127.0.0.1, ::1 ou localhost que se resolva para um deles) ou num socket Unix, que é a forma que um servidor usa quando um proxy à frente faz a terminação de TLS; qualquer outro endereço é recusado antes de qualquer associação, nomeando mcp.tls.cert_file e mcp.tls.key_file. Essas mesmas duas formas são as únicas aceites, com ou sem certificado, onde authorization.trusted_proxy está definido, porque um cabeçalho só pode ser considerado fiável como credencial onde nada além do proxy o pode definir. Predefinição: "" |
tls | objeto | não | Certificado e chave para fazer a terminação de TLS dentro do processo que serve. Definem-se ambos para servir HTTPS diretamente a partir do listener que listen nomeia. Deixam-se ambos por definir para servir em texto simples, o que restringe listen a um endereço de loopback ou a um socket Unix — a forma a usar quando um proxy à frente detém o certificado. Ambas as chaves são caminhos para ficheiros em disco; nenhuma contém material de chave inline. |
allowed_origins | string[] | não | Origens aceites no cabeçalho Origin de um pedido. Um pedido cujo cabeçalho Origin nomeia uma origem que esta lista não contém é recusado com 403; um pedido que nomeia uma origem listada, ou que não tem nenhum cabeçalho Origin, é servido. Uma entrada é comparada exatamente com o cabeçalho, pelo que cada uma se escreve da forma como um navegador envia uma origem: um esquema em minúsculas, ://, um host em minúsculas — um nome, um endereço IPv4 ou um endereço IPv6 entre parênteses retos — e : com a porta quando esta não é a predefinida do esquema, sem nada depois. Por exemplo https://app.example.com ou http://localhost:3000. Uma entrada com qualquer outra forma nunca poderia ser igual ao que um navegador envia, pelo que é recusada quando o ficheiro de configuração é carregado, nomeando o ficheiro e a entrada: uma com uma / final ou um caminho (https://app.example.com/), uma sem esquema (app.example.com) e uma que contenha uma letra maiúscula ou um espaço. A predefinição é vazia, pelo que nenhuma origem é aceite e só é servido um chamador que não envie nenhum cabeçalho Origin. Um cliente baseado num navegador precisa, portanto, que a sua origem esteja listada aqui; um cliente que não é um navegador não envia esse cabeçalho e não precisa de nenhuma entrada. Cada entrada corresponde ao padrão ^[a-z][a-z0-9+.-]*://(?:[a-z0-9._-]+|\[[0-9a-f:.]+\])(?::[0-9]{1,5})?$. Predefinição: [] |
limits | objeto | não | Limites máximos que o listener HTTP aplica ao tráfego que aceita, para que um único chamador não consiga esgotar o processo que serve. Limitam o tamanho que um único pedido pode ter, quantos pedidos são executados em simultâneo e a que ritmo um chamador pode enviar. Nenhum deles pode ser desativado. |
authorization | objeto | não | O que este servidor declara sobre os bearer tokens que os seus chamadores apresentam: que servidor de autorização os emite, o endereço que este servidor publica para si próprio como o recurso para o qual são emitidos, opcionalmente um ficheiro a partir do qual ler as chaves de verificação desse servidor e, opcionalmente, os cabeçalhos que um proxy à frente define quando é esse proxy a validar os tokens. issuer e resource são obrigatórios sempre que o transporte HTTP é escolhido, e sem eles um listener é recusado antes de qualquer associação; um servidor que comunica através da entrada e da saída padrão não lê nenhum deles. Ambos são publicados no documento de metadados OAuth do recurso protegido que o listener serve, que é a única resposta que um chamador HTTP recebe sem que lhe seja pedida qualquer credencial, porque um cliente o lê para descobrir onde obter um token. Este bloco não contém material secreto: um token é apresentado por um chamador no pedido que faz e nunca é um campo de configuração, e jwks_file nomeia chaves públicas de verificação e não algo que assine. |
deny_reach | string (enum)[] | não | Tipos de alcance que este servidor não oferece, seja o que for que o token de um chamador diga. Cada operação 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 host partilham — e nomear um tipo aqui retira deste servidor todas as ferramentas desse tipo. Uma ferramenta retirada fica ausente da lista de ferramentas e daquilo que describe-capabilities responde, para todos os chamadores, e chamá-la mesmo assim é recusado nomeando esta definição, porque nenhum âmbito a poderia admitir. A predefinição é vazia, pelo que o servidor oferece tudo o que os âmbitos dos seus chamadores admitem. É um limite que o servidor impõe a si próprio, além do limite por chamador que os âmbitos definem: um servidor que serve leituras e nada mais nomeia aqui os três tipos que escrevem e deixa então de poder publicar, mesmo para um chamador cujo token tem todos os âmbitos. Nomear machine é aceite e não altera nada — nenhuma ferramenta desse tipo é oferecida através de HTTP, o que é uma propriedade do transporte e não uma definição. Lido quando o listener arranca: um valor fora dos quatro é recusado quando a configuração é carregada, e alterá-lo exige um reinício. Não é lido de todo enquanto o servidor comunica através da entrada e da saída padrão, onde o chamador é a pessoa que lançou o processo. Valores permitidos para cada entrada: "none", "workspace", "registry", "machine". Predefinição: [] |
announce_tools | string[] | não | Ferramentas que este servidor anuncia, nomeadas exatamente como a lista de ferramentas as indica. Se a chave for omitida, é anunciada cada ferramenta que este servidor oferece, que é o que espera um cliente que segue o protocolo: obtém a lista completa de ferramentas e decide por si quanto dela apresentar a um modelo. Se for escrita uma lista, são anunciadas exatamente essas ferramentas — uma deixada de fora fica ausente da lista de ferramentas, ausente daquilo que describe-capabilities responde, e é recusada quando chamada pelo nome, nomeando esta definição. Se for escrita uma lista vazia, nada é anunciado. Define-se a chave onde o cliente na outra ponta limita quantas ferramentas vai registar — alguns clientes aplicam esse limite máximo a todos os servidores a que estão ligados em simultâneo — e nomeiam-se as ferramentas de que esse cliente precisa. Restringe o que é anunciado e nada mais: não pode alargar deny_reach, que retira uma capacidade por completo, nem os âmbitos que o token de um chamador tem. Uma ferramenta nomeada aqui de um tipo que deny_reach retira fica fora da lista de ferramentas e é recusada quando chamada, nomeando essa definição; uma nomeada aqui que os âmbitos do chamador não admitem continua listada, e uma chamada a ela é recusada nomeando o âmbito que a admitiria. Cada nome tem de ser um que este binário oferece: um nome ao qual nenhuma ferramenta responde é recusado quando o servidor arranca, porque, caso contrário, quem pediu uma superfície mais restrita receberia uma diferente sem que nada o indicasse. Um nome da família cli-, que executa um comando aggrega num processo separado, é aceite em ambos os transportes e não anuncia nada através de HTTP, onde nenhuma ferramenta desse tipo é oferecida a qualquer chamador. Lido em ambos os transportes quando o servidor arranca, pelo que o conjunto anunciado fica fixo durante toda a vida do processo e alterá-lo exige um reinício. |
health | objeto | não | Onde um supervisor pergunta se este processo está ativo e se está pronto para responder a uma chamada. As duas verificações são respondidas num endereço próprio e nunca no endereço que listen nomeia: cada pedido ao endpoint tem um bearer token, pelo que uma sonda respondida aí daria a qualquer coisa que consiga alcançar o endpoint uma leitura não autenticada do processo, juntamente com um meio gratuito de o pôr a trabalhar. O endpoint responde a /healthz e /readyz com o mesmo 404 que dá a qualquer caminho que não serve, com token ou sem ele. |
Não são permitidas propriedades adicionais.
aggrega-config.mcp.tls
Certificado e chave para fazer a terminação de TLS dentro do processo que serve. Definem-se ambos para servir HTTPS diretamente a partir do listener que listen nomeia. Deixam-se ambos por definir para servir em texto simples, o que restringe listen a um endereço de loopback ou a um socket Unix — a forma a usar quando um proxy à frente detém o certificado. Ambas as chaves são caminhos para ficheiros em disco; nenhuma contém material de chave inline.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
cert_file | string | não | Caminho para a cadeia de certificados PEM que o listener apresenta, lido quando o processo arranca. Define-se juntamente com key_file. A predefinição é vazia, pelo que o listener serve em texto simples e listen fica restrito a um endereço de loopback ou a um socket Unix. Predefinição: "" |
key_file | string | não | Caminho para a chave privada PEM do certificado em cert_file, lido quando o processo arranca. Define-se juntamente com essa definição. Um caminho para um ficheiro, nunca material de chave inline. A predefinição é vazia, pelo que o listener serve em texto simples e listen fica restrito a um endereço de loopback ou a um socket Unix. Predefinição: "" |
Não são permitidas propriedades adicionais.
aggrega-config.mcp.limits
Limites máximos que o listener HTTP aplica ao tráfego que aceita, para que um único chamador não consiga esgotar o processo que serve. Limitam o tamanho que um único pedido pode ter, quantos pedidos são executados em simultâneo e a que ritmo um chamador pode enviar. Nenhum deles pode ser desativado.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
max_body_bytes | integer | não | Maior corpo de pedido que o listener aceita, em bytes. Um pedido cujo corpo o exceda é recusado com 413, e o corpo não é lido para além do limite máximo. A predefinição é 4194304 (4 MiB), bem acima de uma chamada de ferramenta que contenha um documento de autoria inteiro e bem abaixo do que permitiria a um único chamador ocupar uma parte significativa da memória do processo. O mínimo é 1, pelo que não existe nenhum valor que desative o limite máximo; deve ser aumentado onde os chamadores enviam legitimamente documentos maiores. Mínimo: 1. Predefinição: 4194304 |
max_concurrent_requests | integer | não | Quantos pedidos o listener executa em simultâneo. Um pedido que chegue quando essa quantidade já está em curso é recusado com 503 em vez de ser colocado em fila, pelo que um chamador é informado de que deve tentar novamente em vez de esperar atrás de trabalho que não consegue ver. A predefinição é 16, o que deixa margem para várias chamadas de ferramentas em simultâneo mantendo um host pequeno responsivo; num host maior, deve ser aumentado. O mínimo é 1, pelo que não existe nenhum valor que desative o limite máximo. Mínimo: 1. Predefinição: 16 |
requests_per_minute | integer | não | Quantos pedidos um chamador pode enviar num minuto. A contagem é feita por chamador e não por servidor — face ao sujeito que o token do chamador nomeia, ou à identidade que um proxy de confiança afirmou — pelo que um chamador muito ativo não pode gastar a quota de outro. Um chamador pode enviar essa quantidade de uma só vez; a quota é depois reposta de forma constante, ao ritmo de mais um pedido a cada 60 / requests_per_minute segundos, e um pedido que chegue quando não resta nenhum é recusado com 429. A predefinição é 120, ou seja, dois por segundo de forma sustentada: muito acima do que um assistente que opera um espaço de trabalho envia, e ainda assim um limite para um cliente que entrou em ciclo. O mínimo é 1, pelo que não existe nenhum valor que desative o limite máximo. Mínimo: 1. Predefinição: 120 |
Não são permitidas propriedades adicionais.
aggrega-config.mcp.authorization
O que este servidor declara sobre os bearer tokens que os seus chamadores apresentam: que servidor de autorização os emite, o endereço que este servidor publica para si próprio como o recurso para o qual são emitidos, opcionalmente um ficheiro a partir do qual ler as chaves de verificação desse servidor e, opcionalmente, os cabeçalhos que um proxy à frente define quando é esse proxy a validar os tokens. issuer e resource são obrigatórios sempre que o transporte HTTP é escolhido, e sem eles um listener é recusado antes de qualquer associação; um servidor que comunica através da entrada e da saída padrão não lê nenhum deles. Ambos são publicados no documento de metadados OAuth do recurso protegido que o listener serve, que é a única resposta que um chamador HTTP recebe sem que lhe seja pedida qualquer credencial, porque um cliente o lê para descobrir onde obter um token. Este bloco não contém material secreto: um token é apresentado por um chamador no pedido que faz e nunca é um campo de configuração, e jwks_file nomeia chaves públicas de verificação e não algo que assine.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
issuer | string | não | Endereço do servidor de autorização que emite os tokens que este listener aceita, escrito da forma como esse servidor declara o seu próprio identificador de emissor — por exemplo https://login.example.com. É publicado na lista authorization_servers do documento de metadados do recurso protegido, que é a forma como um cliente fica a saber onde obter um token para este listener. A predefinição é vazia, o que não é um valor utilizável: um listener é recusado antes de qualquer associação, a menos que esta chave contenha um endereço completo, com esquema e host incluídos. É um endereço https, a menos que o servidor de autorização seja executado nesta máquina: http simples só é aceite para um host de loopback, como localhost, 127.0.0.1 ou ::1, e um emissor http simples em qualquer outro host é recusado antes de qualquer associação, nomeando esta chave e pedindo um endereço https. Isto aplica-se quer as chaves sejam lidas a partir do emissor ou de jwks_file, quer um trusted_proxy à frente verifique os tokens, porque cada cliente é enviado para o emissor para obter o seu token. Predefinição: "" |
resource | string | não | Endereço que este servidor publica para si próprio, tal como um chamador o alcança — por exemplo https://mcp.example.com/mcp. Deve ser escrito o endereço que os chamadores realmente usam, incluindo o host que um proxy à frente apresenta, porque este é o identificador que um cliente entrega ao servidor de autorização quando pede um token para este servidor, e é publicado sem alterações como o campo resource do documento de metadados do recurso protegido. O local onde esse documento é servido deriva dele, inserindo /.well-known/oauth-protected-resource entre o host e o caminho: um servidor publicado como https://mcp.example.com/mcp serve-o em https://mcp.example.com/.well-known/oauth-protected-resource/mcp, e também nesse caminho well-known sem nada depois, que é onde um cliente procura em segundo lugar. Um token só é aceite quando este endereço está entre as audiências que nomeia. A predefinição é vazia, o que não é um valor utilizável: um listener é recusado antes de qualquer associação, a menos que esta chave contenha um endereço completo, com esquema e host incluídos. Predefinição: "" |
jwks_file | string | não | Caminho para um ficheiro que contém o JSON Web Key Set face ao qual são verificados os tokens que este servidor aceita, lido quando o processo arranca. A predefinição é vazia, que é o caso habitual: as chaves são lidas a partir do próprio servidor de autorização, perguntando a issuer onde as publica e obtendo-as a partir do endereço que indica, e são relidas uma vez quando chega um token assinado por um identificador de chave que o conjunto mantido não contém. Define-se esta chave onde o espaço de trabalho está offline, caso em que, sem ela, um listener é recusado antes de qualquer associação, porque um espaço de trabalho offline não faz nenhum pedido de rede e não existe outra forma de obter as chaves; o ficheiro contém então as únicas chaves aceites, e o servidor de autorização nunca é contactado. O ficheiro contém chaves públicas de verificação e nunca algo que assine. Um caminho relativo é resolvido relativamente ao diretório do ficheiro de configuração que o declarou. Predefinição: "" |
trusted_proxy | objeto | não | Lê quem é um chamador a partir de cabeçalhos que um proxy à frente define, em vez de validar aqui um bearer token. Só deve ser definido onde ambas as condições se verificam: um proxy à frente valida ele próprio os tokens, e nada além desse proxy consegue alcançar o listener: com isto definido, listen tem de ser um endereço de loopback ou um socket Unix, e qualquer outro endereço é recusado antes de qualquer associação, nomeando ambas as definições. Um cabeçalho é fiável exatamente na medida do conjunto de chamadores que o podem definir, e num endereço que a rede alcança qualquer chamador pode definir qualquer cabeçalho que queira, pelo que um listener neste modo num endereço desses permitiria a qualquer chamador alegar ser qualquer pessoa. Com isto definido, não é lido nenhum token — nem do cabeçalho Authorization, nem de qualquer outro lado, e não é obtido nenhum conjunto de chaves —, a identidade do chamador é o valor de principal_header, um pedido que não tenha esse cabeçalho recebe a resposta 401, e os dois cabeçalhos nomeados aqui são os únicos lidos. Se for omitido, que é a predefinição, este servidor valida ele próprio os bearer tokens. |
Não são permitidas propriedades adicionais.
aggrega-config.mcp.authorization.trusted_proxy
Lê quem é um chamador a partir de cabeçalhos que um proxy à frente define, em vez de validar aqui um bearer token. Só deve ser definido onde ambas as condições se verificam: um proxy à frente valida ele próprio os tokens, e nada além desse proxy consegue alcançar o listener: com isto definido, listen tem de ser um endereço de loopback ou um socket Unix, e qualquer outro endereço é recusado antes de qualquer associação, nomeando ambas as definições. Um cabeçalho é fiável exatamente na medida do conjunto de chamadores que o podem definir, e num endereço que a rede alcança qualquer chamador pode definir qualquer cabeçalho que queira, pelo que um listener neste modo num endereço desses permitiria a qualquer chamador alegar ser qualquer pessoa. Com isto definido, não é lido nenhum token — nem do cabeçalho Authorization, nem de qualquer outro lado, e não é obtido nenhum conjunto de chaves —, a identidade do chamador é o valor de principal_header, um pedido que não tenha esse cabeçalho recebe a resposta 401, e os dois cabeçalhos nomeados aqui são os únicos lidos. Se for omitido, que é a predefinição, este servidor valida ele próprio os bearer tokens.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
principal_header | string | sim | Cabeçalho no qual o proxy à frente coloca a identidade do chamador — por exemplo X-Forwarded-User. Escreve-se como um nome de cabeçalho HTTP: letras, algarismos e hífenes, e os restantes caracteres que um nome de cabeçalho pode conter (!#$%&'*+.^_|~ e o acento grave), sem espaço, dois pontos ou outro separador. Um nome com qualquer outra forma é recusado quando o ficheiro de configuração é carregado, nomeando o ficheiro e a chave, porque nenhum pedido pode ter um cabeçalho desses. Um vazio também é recusado: deixaria este servidor a verificar ele próprio os tokens enquanto o bloco diz que é um proxy à frente que o faz. Para deixar este modo desativado, omite-se trusted_proxy. O valor do cabeçalho é tomado exatamente como está escrito e não é comparado com nada, da mesma forma que o sujeito de um token que este servidor valida ele próprio é registado e não é comparado com nada. É a credencial inteira neste modo, pelo que é obrigatório sempre que trusted_proxy está definido, e um pedido que chegue sem ele recebe a resposta 401. Padrão: ^[!#$%&'*+.^_`|~0-9A-Za-z-]+$. |
scopes_header | string | não | Cabeçalho no qual o proxy à frente coloca os âmbitos concedidos ao chamador, separados por espaços — por exemplo X-Forwarded-Scopes. Escreve-se como um nome de cabeçalho HTTP, com a mesma forma que principal_header, ou deixa-se vazio. Um nome com qualquer outra forma é recusado quando o ficheiro de configuração é carregado, nomeando o ficheiro e a chave, porque nenhum pedido pode ter um cabeçalho desses e a nenhum chamador seria alguma vez concedido um âmbito. A predefinição é vazia, o que não afirma nenhum âmbito para nenhum chamador. Seja qual for o seu nome, não é lido nenhum cabeçalho além deste e de principal_header. Padrão: ^[!#$%&'*+.^_`|~0-9A-Za-z-]*$. Predefinição: "" |
Não são permitidas propriedades adicionais.
aggrega-config.mcp.health
Onde um supervisor pergunta se este processo está ativo e se está pronto para responder a uma chamada. As duas verificações são respondidas num endereço próprio e nunca no endereço que listen nomeia: cada pedido ao endpoint tem um bearer token, pelo que uma sonda respondida aí daria a qualquer coisa que consiga alcançar o endpoint uma leitura não autenticada do processo, juntamente com um meio gratuito de o pôr a trabalhar. O endpoint responde a /healthz e /readyz com o mesmo 404 que dá a qualquer caminho que não serve, com token ou sem ele.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
listen | string | não | Endereço no qual as verificações de atividade e de prontidão são respondidas, nas mesmas duas formas que listen aceita: host:port, ou unix: seguido de um caminho do sistema de ficheiros. A predefinição é vazia, pelo que não é iniciado nenhum segundo listener e nenhuma das duas verificações é respondida em lado nenhum. Com um endereço definido, GET /healthz é respondido com 200 a partir do momento em que o processo está em execução, e GET /readyz é respondido com 503 até que o espaço de trabalho tenha sido resolvido e o endpoint tenha feito a associação, e com 200 a partir daí — que é a distinção de que um supervisor precisa, uma vez que um processo que está ativo ainda não é um processo capaz de responder a uma chamada. Cada resposta é um código de estado com corpo vazio, não é pedido nenhum token e não é lido nenhum cabeçalho; qualquer outro caminho neste endereço resulta em 404, e qualquer outro método nestes dois resulta em 405. Ao contrário de listen, este endereço não está restrito ao loopback ou a um socket Unix e nenhum endereço é recusado para ele: deve ser apontado para um desses, que é a sua finalidade, tendo em conta que qualquer coisa que consiga alcançar o endereço escolhido pode ler essas duas respostas. Predefinição: "" |
Não são permitidas propriedades adicionais.
Definições
ReleaseCatalogConfig
Os diretórios de catálogo próprios de uma Release: as mesmas duas chaves que o bloco workspace contém, com âmbito restrito a essa Release.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
catalog_dirs | string[] | não | Diretórios de catálogo a partir dos quais esta Release lê entidades locais em vez do catalog_dirs do espaço de trabalho, cada um resolvido relativamente ao ficheiro que o declara. A mesma pilha de pesquisa ordenada em que vence o primeiro da lista do espaço de trabalho, com o diretório catalog na raiz do espaço de trabalho lido depois dela quando esse diretório existe e nenhuma entrada listada já o contém. Se esta chave for omitida, a Release mantém a lista do espaço de trabalho; se for escrita como [], não é lido nenhum catálogo local. |
catalog_dirs_append | string[] | não | Diretórios de catálogo acrescentados depois da lista desta Release — o seu próprio catalog_dirs quando a entrada escreve um, caso contrário o do espaço de trabalho —, cada um resolvido relativamente ao ficheiro que o declara. Predefinição: [] |
Não são permitidas propriedades adicionais.
RegistryConfig
Definições e política de confiança de assinaturas com âmbito restrito a um único host de registo OCI.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
host | string | sim | O host de registo ao qual estas definições se aplicam (p. ex. hub.aggrega.ai). É comparado com o host de registo do destino do push/pull, pelo que se escreve na grafia em que essa comparação é feita: um nome de host em minúsculas que contém um ponto, localhost, um único nome seguido de uma porta (registry:5000), um endereço IPv4 ou um endereço IPv6 entre parênteses retos, cada um com um :port opcional — sem esquema, caminho, credenciais, espaços em branco nem maiúsculas. A porta 443 num host alcançado por HTTPS é a porta predefinida desse host, e escrevê-la é recusado quando a configuração é carregada, nomeando o host a escrever sem ela, porque uma entrada escrita dessa forma nunca seria a encontrada; localhost e os restantes endereços de loopback são alcançados por HTTP simples, pelo que aí 443 é uma porta comum e é mantida. aggrega registry add e aggrega config init --registry indexam a entrada sob o host que o seu argumento nomeia e recusam um que não esteja escrito desta forma. O host é avaliado apenas pela sua grafia: não se verifica se o nome é resolvido nem se um registo responde aí. Padrão: ^(?:(?:(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?|localhost|(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])(?:\.(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])){3}|\[(?:(?:[0-9a-f]{1,4}:){7}[0-9a-f]{1,4}|(?:[0-9a-f]{1,4}:){1,7}:|(?:[0-9a-f]{1,4}:){1,6}:[0-9a-f]{1,4}|(?:[0-9a-f]{1,4}:){1,5}(?::[0-9a-f]{1,4}){1,2}|(?:[0-9a-f]{1,4}:){1,4}(?::[0-9a-f]{1,4}){1,3}|(?:[0-9a-f]{1,4}:){1,3}(?::[0-9a-f]{1,4}){1,4}|(?:[0-9a-f]{1,4}:){1,2}(?::[0-9a-f]{1,4}){1,5}|[0-9a-f]{1,4}:(?::[0-9a-f]{1,4}){1,6}|:(?:(?::[0-9a-f]{1,4}){1,7}|:))\])(?::(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?|[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?:(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))$. |
name | string | não | Alias descritivo opcional para este registo. O host é a identidade; name é um seletor de conveniência que é resolvido para o host desta entrada onde quer que um registo seja nomeado (por exemplo --registry, ou default_registry). Um alias tem de ser único entre as entradas. |
trusted_identities | TrustedIdentity[] | não | Conjunto OR de identidades de assinatura keyless aceites para artefactos obtidos por pull a partir deste registo. Uma assinatura é verificada quando o seu certificado corresponde a qualquer uma das entradas. Usado pelo caminho de verificação keyless. Predefinição: [] |
trusted_deprecation_identities | TrustedIdentity[] | não | Conjunto OR de identidades keyless aceites adicionalmente para assinar um marcador de descontinuação retroativo de um artefacto obtido por pull a partir deste registo. Um marcador de descontinuação é respeitado quando a sua assinatura corresponde ao signatário do artefacto original OR a qualquer entrada daqui — pelo que o proprietário de um registo ou uma equipa de segurança pode retirar um artefacto que o publicador original já não consegue alcançar, sem que lhe seja confiada a assinatura dos próprios artefactos. Usado apenas pelo caminho de descoberta de descontinuações; nunca alarga o conjunto de confiança para assinaturas de artefactos. Predefinição: [] |
public_key | string | não | Chave pública fixada compatível com cosign para um registo em modo com chave, escrita inline como um bloco PEM: o texto desde uma linha -----BEGIN PUBLIC KEY----- (ou -----BEGIN RSA PUBLIC KEY-----) até à respetiva linha -----END, tal como aggrega registry add --key a copia de um ficheiro de chave. Quando definida, as assinaturas deste registo são verificadas offline face a esta chave em vez de face a identidades keyless. Um valor que não contenha nenhuma linha -----BEGIN … PUBLIC KEY----- é recusado quando o ficheiro de configuração é carregado, nomeando o ficheiro e a entrada, e o mesmo acontece com uma chave privada colada aqui por engano. A linha pode estar em qualquer ponto do valor, porque a chave é lida a partir do bloco PEM que o valor contém e qualquer texto antes desse bloco é ignorado. Só essa linha é verificada aqui: se o bloco contém uma chave que se descodifica descobre-se quando uma assinatura deste registo é verificada face a ela. O valor é declarado sensível (x-aggrega-sensitive), pelo que um valor recusado — sobretudo uma chave privada escolhida por engano — nunca é citado: a recusa nomeia o ficheiro, a entrada e a restrição que o valor não cumpriu — o padrão acima, ou o tipo string — e mostra <redacted> onde estaria o valor. Uma chave pública que é carregada é lida e mostrada tal como está escrita. Padrão: -----BEGIN [A-Z ]*PUBLIC KEY-----. |
trusted_root | string | não | Caminho opcional para um bundle de raiz de confiança do Sigstore fixado, para a verificação keyless em ambientes isolados da rede. Quando definido, a âncora de confiança keyless é carregada a partir deste ficheiro sem rede; quando vazio, a raiz de confiança public-good é obtida e guardada em cache. |
advisory | booleana | não | Quando é true, uma falha de verificação de assinatura para este registo é despromovida a aviso em vez de interromper o pull. A verificação continua a ser executada e a falha é reportada; o pull prossegue. A predefinição é false. Predefinição: false |
skip_signature_verification | booleana | não | Desativação de emergência (break-glass) por host da verificação de assinaturas — o mesmo interruptor skip_signature_verification que o global, com âmbito restrito a este host pela sua colocação. Não anula a política signing.required de nível superior: uma assinatura exigida pela organização continua a ser verificada neste host independentemente deste interruptor; só o interruptor global a pode desativar. Defini-lo juntamente com um signing.required por registo no mesmo host é permitido, e combina uma assinatura exigida no push com a verificação omitida no pull: a omissão prevalece do lado da verificação, uma vez que uma posição que exige assinatura definida por host (ao contrário da de nível superior) não é imune à omissão por host. A predefinição é false. Predefinição: false |
signing | SigningConfig | não | O bloco de assinatura deste registo: os URL dos serviços keyless, um caminho opcional de chave para assinatura com chave e a posição de confiança por host. Os campos dos endpoints substituem o bloco signing global para os pushes para este host; uma flag da CLI substitui ambos. required e kinds são lidos a partir da colocação — sob uma entrada de registo, restringem a única posição de confiança a este host (publicar um artefacto não assinado dentro do âmbito é recusado, e consumir um não assinado é recusado), o mesmo conceito que o bloco signing de nível superior tem para todos os registos. |
Não são permitidas propriedades adicionais.
SigningConfig
Um bloco de assinatura: os URL dos serviços keyless, uma referência opcional a um ficheiro de chave para assinatura com chave e a posição de confiança (required e kinds). Colocado no nível superior, aplica-se a todos os registos; colocado sob uma entrada de registries[], aplica-se a esse host — cada campo obtém o seu âmbito a partir da colocação. required é uma única posição de confiança que abrange ambas as direções (um push não assinado dentro do âmbito é recusado e um pull não assinado dentro do âmbito é recusado). Segurança: não contém nenhum material secreto — o token de identidade OIDC nunca é um campo de configuração (é de curta duração e fornecido em tempo de execução), e key_path é um caminho para um ficheiro de chave, nunca bytes de chave inline. Isto espelha a assimetria do lado da verificação: aí é permitida uma public_key inline, mas o lado da assinatura tem apenas um caminho de chave. Um servidor aggrega mcp alcançado por HTTP não consulta nenhum key_path em nenhuma das duas colocações, pelo que a assinatura com chave é inalcançável através de um listener desse tipo: uma chamada a que responda assina apenas com um token de identidade que essa chamada tem.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
fulcio_url | string | não | URL da autoridade de certificação Fulcio para assinatura keyless. Quando não está definido, é usada a instância public-good do Fulcio. Escreve-se como um URL https absoluto: https://, um host e, opcionalmente, uma porta e um caminho, sem espaços em branco — por exemplo https://fulcio.sigstore.dev. Um valor com qualquer outra forma, como um sem esquema (fulcio.example.com) ou um que começa por http://, é recusado quando o ficheiro de configuração é carregado, nomeando o ficheiro e a chave. O ficheiro é verificado antes de qualquer outra coisa ser aplicada sobre ele, pelo que o mesmo endpoint fornecido por AGGREGA_SIGNING_FULCIO_URL, pela flag --fulcio-url ou num pedido de publicação de um editor ou de um assistente não está sujeito a esta forma. Padrão: ^https://[^\s/?#]+(?:[/?#]\S*)?$. |
rekor_url | string | não | URL do registo de transparência Rekor para assinatura keyless. Quando não está definido, é usada a instância public-good do Rekor. Escreve-se como um URL https absoluto: https://, um host e, opcionalmente, uma porta e um caminho, sem espaços em branco — por exemplo https://rekor.sigstore.dev. Um valor com qualquer outra forma, como um sem esquema (rekor.example.com) ou um que começa por http://, é recusado quando o ficheiro de configuração é carregado, nomeando o ficheiro e a chave. O ficheiro é verificado antes de qualquer outra coisa ser aplicada sobre ele, pelo que o mesmo endpoint fornecido por AGGREGA_SIGNING_REKOR_URL, pela flag --rekor-url ou num pedido de publicação de um editor ou de um assistente não está sujeito a esta forma. Padrão: ^https://[^\s/?#]+(?:[/?#]\S*)?$. |
timestamp_url | string | não | URL da autoridade de carimbo temporal RFC3161 para assinatura keyless. Não tem predefinição: quando não está definido, nenhuma autoridade de carimbo temporal é contactada, e a hora fidedigna de uma assinatura keyless vem da sua entrada no registo de transparência. Escreve-se como um URL https absoluto: https://, um host e, opcionalmente, uma porta e um caminho, sem espaços em branco — por exemplo https://tsa.example.com/api/v1/timestamp. Um valor com qualquer outra forma, como um sem esquema (tsa.example.com) ou um que começa por http://, é recusado quando o ficheiro de configuração é carregado, nomeando o ficheiro e a chave. O ficheiro é verificado antes de qualquer outra coisa ser aplicada sobre ele, pelo que o mesmo endpoint fornecido por AGGREGA_SIGNING_TIMESTAMP_URL, pela flag --timestamp-url ou num pedido de publicação de um editor ou de um assistente não está sujeito a esta forma. Padrão: ^https://[^\s/?#]+(?:[/?#]\S*)?$. |
key_path | string | não | Caminho para um ficheiro PEM com uma chave privada ECDSA P-256 própria para assinatura com chave offline. Um caminho para um ficheiro, nunca material de chave inline. Quando não está definido, é usado o caminho keyless. Um servidor aggrega mcp alcançado por HTTP nunca consulta esta chave, onde quer que esteja definida — no bloco signing de nível superior, no de uma entrada de registo ou através de AGGREGA_SIGNING_KEY_PATH: uma chamada a que um listener desse tipo responda assina apenas com um token de identidade que a própria chamada tem, ou é recusada. Um servidor alcançado através da entrada e da saída padrão assina com ela tal como um terminal. |
required | booleana | não | A única posição de confiança para o âmbito deste bloco: quando é true, publicar um tipo de artefacto dentro do âmbito exige uma assinatura (um push não assinado dentro do âmbito é recusado), e consumir um exige uma assinatura (um pull não assinado dentro do âmbito é recusado). O âmbito é dado pela colocação — no bloco signing de nível superior abrange todos os registos; sob o bloco signing de uma entrada de registries[] abrange esse único host. Um nome, uma função, ambos os âmbitos. A política de nível superior compõe-se de forma monótona ao longo da cascata de configurações — qualquer camada que a defina como true torna-a efetivamente true, e nenhuma camada de precedência inferior a pode voltar a desativar — pelo que não pode ser removida por uma edição comum da configuração. A predefinição é false. Predefinição: false |
kinds | string[] | não | Restringe required a tipos de artefacto específicos. Vazio ou uma única entrada all significa todos os tipos assináveis; caso contrário, a posição aplica-se exatamente aos tipos listados, correspondentes ao valor kind: da entidade (por exemplo Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, Aggregate, Plugin). No bloco signing de nível superior compõe-se como uma união ao longo da cascata — uma camada pode alargar o âmbito, mas nunca reduzi-lo. O âmbito é dado pela colocação, tal como em required. Predefinição: [] |
Não são permitidas propriedades adicionais.
TrustedIdentity
Uma identidade de assinatura keyless aceitável: um sujeito de certificado (a identidade OIDC) associado ao emissor OIDC que a garantiu.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
identity | string | não | Nome alternativo do sujeito exato do certificado — a identidade OIDC vinculada ao certificado de assinatura de curta duração (por exemplo o e-mail de um responsável pela manutenção ou o URI de um workflow de CI). |
identity_regexp | string | não | Expressão regular comparada com o sujeito do certificado, usada em vez de uma identity exata (por exemplo, para aceitar qualquer workflow de uma organização). |
issuer | string | sim | URL do emissor OIDC que emitiu o token de identidade (por exemplo https://accounts.google.com ou https://token.actions.githubusercontent.com). |
Não são permitidas propriedades adicionais.
PluginRef
Referência a um plugin Wasm anexado a um socket cuja função de entrada o anexo pode nomear — as listas governance e linter. Os sockets cujo ponto de entrada é fixo usam, em vez disso, FixedEntryPluginRef, que tem estes mesmos campos sem function. uri e capability selecionam em conjunto o plugin: apenas uri é um anexo direto (o plugin com essa identidade é anexado tal como está — a via dos sockets transversais, uma vez que os seus plugins não declaram capacidades servidas); apenas capability resolve o plugin que serve essa capacidade (o nome simples da capacidade que uma Recipe associa através de spec.capability, por exemplo helm); ambos em conjunto desambiguam — capability nomeia o que resolver e uri seleciona o plugin de qual publicador a serve, pela identidade simples desse plugin, num catálogo federado em que mais de um plugin serve a capacidade. function substitui a função de entrada predefinida do socket; quando é omitido, aplica-se a predefinição documentada do socket — numa entrada de governação, essa predefinição decorre de role. role nomeia o papel de anexo de governação e só é lido numa entrada de governação. with tem dados de entrada opcionais do momento do anexo que o plugin lê.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
uri | string | não | Identificador do Plugin: a identidade simples de uma entidade Plugin — o caminho <pluginType>/<name>, por exemplo governance/redact ou provider/helm —, um caminho do sistema de ficheiros local ou um alias de registo. Opcional: uma entrada pode, em vez disso, selecionar o plugin por capability. Um :version final opcional fixa a versão nas mesmas três formas de qualquer fixação de versão (simples, exata :1.0.0 ou intervalo compatível com a versão principal :^1.0.0). |
role | string (enum) | não | O papel do pipeline a que um anexo de governação está ligado, lido apenas numa entrada governance: annotation-transform injeta anotações nos componentes resolvidos antes da expansão de anotações, pelo que as injeções ligadas se tornam anexos de Feature; label-transform atribui automaticamente etiquetas aos nós do grafo de topologia durante a construção da topologia; ir-verdict emite um veredicto de aceitação ou rejeição sobre o grafo IR durante a análise estática; render-verdict emite um veredicto sobre os artefactos renderizados durante a renderização. É o papel — e não o tipo declarado do plugin — que define aquilo que o plugin pode emitir: a saída de um papel de veredicto só pode ser lida como um veredicto, nunca aplicada como uma alteração; a saída de um papel de transformação fica confinada pelo host à sua faceta (anotações ou etiquetas). Também seleciona a função de entrada predefinida (annotation-transform → transform_annotations; label-transform → mutate; ir-verdict → verdict_ir; render-verdict → verdict_render). Valores permitidos: "annotation-transform", "label-transform", "ir-verdict", "render-verdict" |
capability | string | não | A capacidade do fornecedor para a qual esta entrada seleciona um plugin — o nome simples da capacidade que uma Recipe associa através de spec.capability (por exemplo helm, compose). Opcional: uma entrada pode, em vez disso, anexar um plugin diretamente por uri. As associações do fornecedor usam isto para selecionar o plugin de qual publicador serve uma capacidade num catálogo federado; os sockets transversais deixam-no vazio e anexam por uri. |
function | string | não | Substituição opcional da função de entrada predefinida do socket. Quando é omitida, aplica-se a predefinição documentada do socket (governação annotation-transform → transform_annotations, governação label-transform → mutate, governação ir-verdict → verdict_ir, governação render-verdict → verdict_render, linter → lint_rules). A substituição pode nomear qualquer exportação que o plugin declare, e a exportação que nomeia tem de devolver a forma de saída que esse socket lê: a compilação é interrompida quando essa saída tem um campo de nível superior que a forma não declara, nomeando a exportação chamada e o campo inesperado. A verificação lê que nomes de campo de nível superior estão presentes, e não quais estão ausentes nem o que está aninhado abaixo deles, pelo que não é uma validação completa da saída. |
with | PluginRefWith | não | Dados de entrada opcionais do momento do anexo que o plugin lê. Ambos os membros são opcionais e agnósticos em relação ao socket, pelo que qualquer socket pode reutilizar esta superfície. |
Não são permitidas propriedades adicionais.
FixedEntryPluginRef
Referência a um plugin Wasm anexado a um socket cujo ponto de entrada é fixo em vez de nomeado pelo anexo — a lista importer e as associações providers. Tem os mesmos campos de PluginRef sem function: o socket importador chama a única função de entrada que o contrato do seu socket nomeia, e um fornecedor aciona um conjunto fixo de exportações indexadas por fase em vez de um único ponto de entrada selecionável, pelo que em nenhuma das duas listas há um ponto de entrada que function possa nomear, e a chave não é aceite aí. uri e capability selecionam em conjunto o plugin: apenas uri é um anexo direto (o plugin com essa identidade é anexado tal como está — a via do socket importador, uma vez que os seus plugins não declaram capacidades servidas); apenas capability resolve o plugin que serve essa capacidade (o nome simples da capacidade que uma Recipe associa através de spec.capability, por exemplo helm); ambos em conjunto desambiguam — capability nomeia o que resolver e uri seleciona o plugin de qual publicador a serve, pela identidade simples desse plugin, num catálogo federado em que mais de um plugin serve a capacidade. role é aceite aqui, mas não é lido em nenhuma das duas listas que esta forma serve: o papel de anexo de governação que nomeia é lido numa entrada governance, que usa PluginRef, pelo que um papel definido numa destas entradas não tem efeito. with tem dados de entrada opcionais do momento do anexo que o plugin lê; uma associação do fornecedor obtém, em vez disso, a sua configuração de renderização a partir da Recipe, pelo que with: numa delas é recusado no carregamento.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
uri | string | não | Identificador do Plugin: a identidade simples de uma entidade Plugin — o caminho <pluginType>/<name>, por exemplo governance/redact ou provider/helm —, um caminho do sistema de ficheiros local ou um alias de registo. Opcional: uma entrada pode, em vez disso, selecionar o plugin por capability. Um :version final opcional fixa a versão nas mesmas três formas de qualquer fixação de versão (simples, exata :1.0.0 ou intervalo compatível com a versão principal :^1.0.0). |
role | string (enum) | não | O papel de anexo de governação. Nenhuma das duas listas que usam esta forma o lê — o papel é lido numa entrada governance, e essas entradas usam PluginRef — pelo que um papel definido aqui é aceite e não tem efeito. Os valores admitidos são os quatro papéis de governação, e o que cada um significa está descrito em PluginRef. Valores permitidos: "annotation-transform", "label-transform", "ir-verdict", "render-verdict" |
capability | string | não | A capacidade do fornecedor para a qual esta entrada seleciona um plugin — o nome simples da capacidade que uma Recipe associa através de spec.capability (por exemplo helm, compose). Opcional: uma entrada pode, em vez disso, anexar um plugin diretamente por uri. As associações do fornecedor usam isto para selecionar o plugin de qual publicador serve uma capacidade num catálogo federado; os sockets transversais deixam-no vazio e anexam por uri. |
with | PluginRefWith | não | Dados de entrada opcionais do momento do anexo que o plugin lê. Ambos os membros são opcionais e agnósticos em relação ao socket, pelo que qualquer socket pode reutilizar esta superfície. |
Não são permitidas propriedades adicionais.
CLIPluginRef
Um plugin de extensão da CLI fixado, instalado como comando aggrega de nível superior: a referência de artefacto resolvida e fixada numa versão que o comando resolve e executa, e o digest de conteúdo dos bytes do guest para os quais essa referência foi resolvida no momento da instalação. Em conjunto, fixam exatamente que bytes o comando executa; o digest também indexa a cache de describe que fornece os nomes e a ajuda do comando sem carregar o guest.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
uri | string | sim | A referência de artefacto resolvida e fixada numa versão que o comando resolve e executa, por exemplo oci://hub.aggrega.ai/plugin/cli/<name>:1.2.0, fixada na instalação. |
digest | string | sim | O digest de conteúdo dos bytes .wasm do guest para os quais a referência foi resolvida na instalação, escrito como sha256: seguido dos 64 algarismos hexadecimais minúsculos do SHA-256 dos bytes — a grafia que aggrega plugin add cli regista, e a grafia em que os bytes resolvidos são comparados. Um digest em qualquer outra grafia — hexadecimal simples sem o prefixo sha256:, maiúsculas ou um comprimento diferente — nunca lhe poderia ser igual, pelo que é recusado quando o ficheiro de configuração é carregado, nomeando o ficheiro e a entrada. Fixa os bytes exatos que o comando executa — uma resolução posterior cujos bytes produzem um hash diferente interrompe o comando — e é a chave na cache de describe que gera a ajuda do comando sem carregar o guest. Padrão: ^sha256:[0-9a-f]{64}$. |
Não são permitidas propriedades adicionais.
PluginRefWith
Dados de entrada opcionais do momento do anexo que um plugin lê. Ambos os membros são opcionais e a superfície é geral, pelo que qualquer socket a pode reutilizar.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
sources | string[] | não | Caminhos de ficheiros de definição que o host lê em tempo de compilação e entrega ao plugin. Cada entrada é um caminho do sistema de ficheiros resolvido face ao diretório do ficheiro de configuração que a declara. |
settings | objeto | não | Objeto de definições de forma livre entregue ao plugin tal como está. O host não interpreta a sua forma; o plugin define as chaves que lê. |
Não são permitidas propriedades adicionais.