Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler o original em inglês.

Escrever ficheiros do Aggrega

A autoria em Aggrega é um ciclo curto e repetível. Seja qual for a entidade que se escreve — o Aggregate de um programador, o Component de um arquiteto, uma Recipe de operações ou a Release de um operador —, os mesmos cinco passos levam de um ficheiro em branco a um ficheiro validado:

  1. Escolher a entidade que o seu papel detém.
  2. Aprender a sua forma a partir do JSON Schema e da página de referência.
  3. Partir de um esqueleto em vez de um ficheiro em branco.
  4. Preencher os campos que o seu papel detém, deixando os restantes aos respetivos donos.
  5. Validar e depois compilar.

Esta página percorre o ciclo uma vez, tanto para uma pessoa que escreve à mão como para um assistente de IA que escreve através do servidor Model Context Protocol. Os dois caminhos são o mesmo ciclo sobre as mesmas superfícies de referência. Ambos precisam do binário aggrega: Instalar o binário instala-o com um único comando.

1. Escolher a entidade que o seu papel detém

O Aggrega separa a autoria em quatro papéis colaborativos — a intenção do programador, o catálogo da plataforma, as receitas de infraestrutura e a ligação da implementação. Cada papel detém normalmente um conjunto específico de tipos de entidade. Quem já conhece o seu papel pode saltar para a entidade de que precisa; caso contrário, convém ler Personas para os quatro papéis e Entidades por papel para o mapa completo de tipos por papel.

A separação é uma orientação, não uma regra que o compilador imponha. Um autor individual é livre de assumir todos os papéis e escrever todas as entidades de uma só vez; o compilador aceita qualquer padrão de autoria que passe a validação de esquema. Os papéis existem para manter as preocupações claras, não para restringir o que se pode escrever.

2. Aprender a sua forma

Cada tipo de entidade tem um JSON Schema canónico e uma página de referência campo a campo. Convém ler ambos antes de escrever:

  • O esquema é a estrutura exata: campos obrigatórios, valores permitidos e aninhamento. Na linha de comandos, aggrega get-schema <kind> imprime-o; aggrega get-schema --list nomeia todos os tipos que se podem pedir. Um assistente lê os mesmos bytes a partir do recurso schema://<kind>. Ver a referência de aggrega get-schema.
  • A página de referência explica o que cada campo significa e como os campos se relacionam. As páginas de entidades estão em language-reference/entities/ — por exemplo component ou aggregate. Um assistente lê a mesma página a partir do recurso langref://entities/<kind>.

O esquema diz o que é estruturalmente válido; a referência diz o que é sensato. O esquema serve para evitar a rejeição no momento da validação, e a referência para escrever algo que faça o que se pretende.

3. Partir de um esqueleto

Partir de um esqueleto é mais rápido e menos propenso a erros do que um ficheiro em branco. Um assistente ligado ao servidor MCP chama a ferramenta scaffold com um tipo e um nome para obter um ponto de partida mínimo que contém todos os campos que o tipo exige, com um marcador de posição onde quer que ainda falte um valor. Ao escrever à mão, aggrega scaffold <kind> <name> imprime o mesmo ponto de partida na saída padrão, pelo que deve ser redirecionado para um ficheiro; ou copie o exemplo trabalhado mais próximo e reduza-o ao necessário.

Em qualquer dos casos, o esqueleto já contém os campos de nível superior obrigatórios (apiVersion, kind, metadata.name) na forma correta, pelo que a atenção vai para os campos que o seu papel detém e não para código repetitivo.

4. Preencher os campos que o seu papel detém

Preencha apenas os pilares pelos quais o seu papel é responsável e deixe os outros aos respetivos donos. Um programador fornece a intenção da aplicação e os valores; um arquiteto declara o contrato — os valores que um programador pode fornecer, os outputs que um componente fornece, os sockets que expõe; as operações mapeiam esse contrato para um provider específico sem alterar a superfície voltada para o programador; um operador liga a implementação. Entidades por papel indica que pilares pertencem a que papel, para cada tipo.

Manter cada valor no pilar que o seu dono controla é o que permite que a mesma intenção do programador vise infraestruturas diferentes em ambientes diferentes sem que o ficheiro do programador mude. É essa a razão de a superfície de autoria estar dividida.

Manter a descrição em poucos parágrafos curtos. O metadata.description de uma entidade é a prosa que um leitor encontra antes de a escolher: é publicado com a entidade como a sua descrição pesquisável, e o aggrega search compara uma consulta com ela. Deve ser escrita para esse momento, em parágrafos curtos — num bloco dobrado description: >, uma linha em branco inicia um novo — dizendo o que a entidade é, como um leitor a usa, onde é realizada e o que não faz. Um limite que um leitor tenha de conhecer antes de escolher a entidade também pertence aí, dito de forma breve. Tudo o resto — porque é que uma predefinição é a que é, como uma definição se comporta num destino, o que um valor significa em cada realização — vai para comentários YAML ao lado do campo ou bloco que explica, onde a pessoa que trabalha com esse campo os lerá. Nada no compilador limita o comprimento de uma descrição nem age sobre o que ela diz, pelo que mantê-la curta é para benefício do leitor.

5. Validar e depois compilar

Verifique o ficheiro antes de depender dele:

  • Um assistente chama a ferramenta validate, que reporta inline os erros de esquema e de referência para que possa corrigir o rascunho antes de o devolver.
  • À mão, aggrega validate <file> verifica um único ficheiro de Component, Feature, Recipe, FeatureRecipe, Workload ou Plugin, e aggrega validate --release <release> verifica tudo o que uma Release alcança, incluindo o seu Aggregate e o seu Manifest. aggrega lint aplica as regras de disciplina de publicação a uma entidade de catálogo, e aggrega inspect resolve e mostra o que o compilador vê. Quando toda a topologia estiver pronta, aggrega pull --release <release> resolve as suas dependências e escreve o seu lockfile, e aggrega build --release <release> compila depois a Release em artefactos por fronteira — um build falhado nomeia exatamente o que corrigir.

Validar cedo é mais barato do que um build falhado tarde. Escrever, validar, corrigir e só depois compilar.

Autoria com um assistente de IA

O comando aggrega mcp executa um servidor Model Context Protocol que transforma qualquer cliente compatível com MCP num assistente de autoria que conhece o Aggrega. Uma vez ligado, o assistente pode:

  • Assumir um papel através dos prompts de autoria incorporados — um por persona (programador, arquiteto, operações) mais um template focado por entidade. Cada prompt enquadra o papel e aponta o assistente para o esquema, a página de referência e este guia, para que as suas sugestões fiquem dentro dos pilares que o papel detém.
  • Ler a referência através de recursos: schema://<kind> para o JSON Schema de um tipo, langref://<path> para qualquer página de referência e authoring://<topic> para este guia.
  • Agir sobre o workspace através de ferramentas: scaffold para iniciar um esqueleto correto, validate para verificar um rascunho, describe para inspecionar uma entidade de catálogo e get-schema para obter um esquema por tipo.

Tudo o que o assistente lê é servido a partir da sua máquina: os esquemas estão integrados no binário, e as páginas do guia e da referência vêm do pacote de documentação mantido na cache da sua máquina, que o servidor obtém do registo quando arranca e não encontra aí nenhuma cópia. Ler uma página, criar um esqueleto e validar não acedem à rede; onde o pacote não pode ser obtido, os esquemas continuam a ser servidos e as páginas não. Para ligar um cliente, siga Ligar o servidor MCP; O que o seu assistente pode fazer com o Aggrega cobre o resto daquilo a que chega. Para o comando em si, consulte a referência do aggrega mcp.

Para onde ir a seguir