Referência da linguagem
O «quê» e o «como usar» do Aggrega. Sintaxe, invocação da CLI, catálogo de erros, exemplos trabalhados.
Os capítulos abaixo leem-se por ordem para uma primeira compreensão. Os subdiretórios de referência estão listados sob o respetivo capítulo — salte diretamente para eles quando procurar uma entidade, palavra-chave, provider, comando da CLI ou erro específico.
Antes de ler a sequência de capítulos, consulte Estado da linguagem para conhecer o estado atual de prontidão — que superfícies da linguagem estão disponíveis hoje, quais são aceites mas o compilador ainda não lhes dá seguimento, e quais estão planeadas para iterações futuras. Compatibilidade indica o que uma versão promete para os esquemas, a linha de comandos, as ferramentas do assistente, os códigos de erro e os kits de plugins.
Modelo de níveis de entidades
Os tipos de entidade de autoria do Aggrega estão organizados em três níveis que refletem a progressão da adoção (abaixo). Ao lado deles está o Workload detido pela plataforma, que não é um tipo de autoria próprio — é a forma que a entrada sintetizada de uma Recipe assume, exprimindo a forma de computação através do vocabulário form: (stateless, stateful, daemon, scheduled, task, reference). A divisão em níveis é um mecanismo de documentação e de integração, não uma restrição em tempo de execução: todos os tipos de entidade são cidadãos de primeira classe da linguagem; o compilador trata-os de forma uniforme; o Aggrega open source suporta todos os níveis sem licenciamento nem restrição de funcionalidades. Os marcadores de nível sinalizam «avançado; ignore se não precisar» para a navegação, e não capacidade.
| Nível | Tipos de entidade | Quando adotar |
|---|---|---|
| Nível 1 — a superfície mínima viável | Aggregate, Component, Recipe, Manifest, Release | Dia 1 — fundadores individuais e equipas pequenas entregam software funcional apenas com o nível 1. O modelo mental: «Tenho uma aplicação; quero implementá-la; é assim que se faz.» |
| Nível 2 — separação de papéis | Feature, FeatureRecipe, Plugin | Dia 30 — equipas pequenas em que os papéis se separam (programador + Ops + por vezes Segurança). O nível 2 entra através de Plugins de renderização de provider (a equipa de Ops escolhe entre Helm, helm-chart, Compose, Terraform e CloudFormation), de Features (a equipa de Segurança gere as credenciais separadamente da configuração da aplicação) e de FeatureRecipes (personalização por provider no momento da associação). |
| Nível 3 — reutilização cross-Component | SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary | Dia 365 — catálogos maduros em que formas comuns se repetem em muitas entidades. O limiar é informal: quando uma forma (por exemplo, PodResources) aparece em 5 ou mais Components e coordenar as atualizações gera atrito, uma entrada de SchemaLibrary justifica-se por si. |
Cada progressão é opcional. Um fundador individual nunca é obrigado a olhar para o nível 3; um catálogo empresarial tem acesso total ao nível 3 conforme necessário. O nível 1 é completo para o caso de uso do fundador individual — um programador pode entregar aplicações funcionais usando apenas entidades do nível 1. Esta é uma propriedade de desenho forte: o nível 1 não é um «subconjunto que compila»; é um «subconjunto que entrega software».
A superfície de cinco entidades do nível 1 tem um custo de entrada — Aggregate + Component + Recipe + Manifest + Release é mais cerimónia do que «largar um ficheiro YAML e obter um serviço em execução». O custo é o preço da separação de autoria em quatro domínios (intenção do programador / catálogo da plataforma / Platform Ops / encaminhamento) que distingue o Aggrega do Helm ou do Terraform puros. Os tutoriais do nível 1 percorrem explicitamente a configuração das cinco entidades.
No nível 3, o mecanismo spec.templates / $instantiate: (helpers paramétricos na SchemaLibrary) está documentado como uma subfuncionalidade ainda mais avançada. A maioria dos adotantes do nível 3 não recorre a spec.templates de início; o limiar é «quando a biblioteca tiver 6 ou mais esquemas que partilham estrutura parametrizada».
Ordem de leitura
- Como utilizar esta referência
- Convenções de nomenclatura
- Visão geral da referência de entidades
- Nível 1: aggregate, component, recipe, manifest, release
- Nível 2: feature, featurerecipe, plugin
- Nível 3: schemalibrary, mappinglibrary, workloadlibrary, artifactlibrary
- Transversal: workload (tipo de compilador detido pela plataforma, consumido dentro do
workload:da Recipe)
- Visão geral do vocabulário
- Referência de vocabulário: topology-triad (provides, inject, uses), data-pillars (values, infra, parameters, locals), inheritance-and-interface (extends, implements), modifier-system (appliesTo, selectors), compact-form-authoring, cross-document-ref, labels-and-annotations, publishing-surface, social-contracts, validation-surface, output-composition, uri-grammar, version-resolution
- Visão geral dos templates
- Referência de templates: expansion-matrix, template-context-contract, sprig-functions, parameters-context, assertions-block, rendered-resource-names
- Visão geral dos Providers
- Referência de Providers: architecture, well-known-annotations, reference-matrix, helm, helm-chart, compose, terraform, cloudformation
- Visão geral da CLI
- Referência da CLI: aggrega-build, aggrega-inspect, aggrega-pull, aggrega-lint, aggrega-auth, aggrega-cache, aggrega-config, aggrega-deprecate, aggrega-edit-document, aggrega-explain, aggrega-get-schema, aggrega-import e o ficheiro de respostas da importação, aggrega-login, aggrega-logout, aggrega-mcp, aggrega-pin, aggrega-plugin, aggrega-push, aggrega-push-artifact, aggrega-registry, aggrega-scaffold, aggrega-search, aggrega-serve, aggrega-sign, aggrega-skills, aggrega-validate, aggrega-version, global-flags, configuration, environment-variables, workspace-boundary
- Visão geral dos erros
- Referência de erros: fatal-halts, warnings, sentinels, error-translation
- Visão geral dos exemplos
- Referência de exemplos: 01-getting-started, 02-data-model, 03-features-and-policies, 04-secrets, 05-credential-features, 06-composition, 07-input-kinds, 08-advanced-patterns, 09-cross-boundary-routing; workspaces executáveis: Exemplos executáveis
Referência de autoria de Plugin
A superfície de plugins Wasm está ao lado da sequência de capítulos e não dentro dela: um autor de plugins lê-a independentemente do percurso de autoria de entidades. A página de entidade plugin aborda a superfície de autoria do catálogo; as páginas abaixo abordam os sockets, as cargas e o fluxo de trabalho do autor.
- plugin-contract — os sockets a que um plugin se associa, a sua colocação no pipeline e as formas de entrada e de saída de cada socket.
- plugin-developer-guide — o fluxo de trabalho do autor de ponta a ponta:
describe(), declarações de capacidades, limites de tempo de execução, o ciclo de vida publish/pull/build, assinatura, versionamento. - policy-socket — o socket de governação em profundidade: os seus quatro papéis, as severidades dos veredictos, o canal de entrada do operador e a escrita de uma política para qualquer dos motores que vêm dentro do compilador.
- governance-attachment-facts — os factos por associação que uma política de governação lê do grafo do build, incluindo as três unidades da marcação de sensibilidade e porque é que a ausência de marcação não é uma permissão.
- when-to-use-a-pipeline-step — escolher entre um passo de pipeline e uma FeatureRecipe com templates.
- embedded-plugins — os plugins incorporados no binário do compilador.
- tagging-plugins — os dois plugins de governação integrados que escrevem etiquetas sem uma política,
governance/label-injectoregovernance/selector-tagger: as suas definições e o que cada um escreve. - core-importers — os dez importadores do compilador, de Langflow, Flowise e n8n a Compose, MCP e às frameworks de agentes: o que cada um lê e esboça, as suas definições e a sua publicação com cada versão do compilador.
- authoring-a-provider-walkthrough — um percurso guiado pela autoria de um guest de provider, desde um diretório vazio até um build que escreve os ficheiros que o provider renderizou.
- writing-a-governance-plugin — escrever um plugin de governação próprio a partir do esqueleto de adaptador do kit de plugins: uma regra, o export de cada papel executado à mão, uma entidade
Pluginno catálogo do workspace e um build que o plugin recusa. - compatibility — como os kits de plugins são versionados: o que uma versão de correção e uma versão menor de um kit podem alterar, e o que permite que um plugin já compilado continue a carregar.