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

aggrega mcp

Executar um servidor Model Context Protocol sobre a entrada e saída padrão, ou sobre HTTP, para integração com assistentes de IA

Sinopse

aggrega mcp [flags]

Descrição

Run Aggrega as a Model Context Protocol (MCP) server, so an AI
assistant can discover and drive Aggrega operations through a structured
protocol instead of scraping command output.
Two transports reach the same server, and --transport chooses between
them, with mcp.transport in the workspace configuration as the key it
overrides. The default, stdio, speaks newline-delimited JSON-RPC 2.0 over
the process's standard input and output, which is how an MCP-capable
client runs it: spawned as a subprocess, not typed by hand. http serves
the protocol over HTTP instead — one long-running process on a host,
reached by callers who are not at its keyboard — on the address --listen
names, or mcp.listen when the flag is absent.
An address chooses no transport. --listen given with the stdio transport
is refused, whether stdio was typed, configured or left as the default,
because it names where to listen for a transport that does not listen.
An address mcp.listen names is left unused by a server on standard input
and output, which says so in one line on stderr, so a client can launch
this command in a directory whose configuration is written for a
listener. And the http transport with no address from either is refused
before anything binds.
It speaks two MCP protocol revisions on both transports, 2026-07-28 and
2025-06-18, so a client of either connects. In 2026-07-28 nothing is
settled for the connection as a whole: every request states the protocol
version it speaks and the capabilities its sender offers, and the server
reads both from the request it is answering rather than holding anything
between messages. In 2025-06-18 a client settles those same facts once,
by opening the connection with an initialize handshake.
Both revisions reach the same server, and a client learns the same
things about it either way. A client on 2026-07-28 calls server/discover
for the revisions the server speaks, the capabilities it advertises —
tools, resources, and prompts — and the guidance it offers a model
before the first call. A client on 2025-06-18 receives those same
capabilities, and that same guidance, in the reply to its handshake.
From there the client discovers the server's surface through the list
methods (tools, resources, resource templates, and prompts) and invokes
it through tools/call and resources/read. The server exposes Aggrega
operations — compiling and inspecting a Release, reading catalog
entities — as tools and resources an assistant can call directly.
On standard input and output, stream discipline is strict: stdout carries
only protocol messages, one JSON object per line, so the client can parse
the stream without heuristics. Every log, warning, and diagnostic is
written to stderr instead. The server reads one message per line and
exits cleanly when stdin reaches end of stream, so a client that closes
the connection shuts the server down. A client ends one call by naming
its id, and every other call carries on.
Over HTTP there is one endpoint, /mcp, accepting POST. Every message is
its own request and no session of any kind is kept, so nothing a client
sends first decides how a later request is answered. Closing the
connection ends the call it carried. A request carrying an Origin header
is checked against mcp.allowed_origins, and mcp.limits bounds how large
one request body may be, how many requests are answered at once, and how
many one caller may send in a minute. A caller sending faster than
mcp.limits.requests_per_minute is answered 429, counted against that
caller alone.
Every request to /mcp carries a credential, and which one depends on
whether a proxy in front has already checked it. By default it is a
bearer token the server verifies itself, against the keys
mcp.authorization.issuer publishes: it must come from that issuer, name
mcp.authorization.resource among its audiences, be inside its validity
window, and be signed with an asymmetric algorithm. A request carrying no
token is answered 401 with a challenge, and so is one whose token fails
any of those. A token is never accepted from the address, never forwarded
anywhere, never exchanged, and never written to any log; the subject it
names is recorded and compared to nothing.
Set mcp.authorization.trusted_proxy instead and the caller is read from a
header the proxy sets rather than from a token, with its scopes from a
second header; no token is read at all in that mode, and a request
without the principal header is answered 401. Because that header is then
the whole credential, it is trustworthy only where nothing else can set
it: the process is refused before it binds unless mcp.listen is loopback
or a Unix socket.
The challenge names where to obtain a token. A listener publishes an
OAuth protected-resource metadata document, with no credential asked for,
naming the authorization server, this deployment's own address and the
scopes that exist; it is served at /.well-known/oauth-protected-resource
and at that path followed by the endpoint path, which are the two places
a client looks. A client reads it before it can hold a token, which is
why it is the one answer given without one. What that document publishes
comes from mcp.authorization.issuer and mcp.authorization.resource, and a
listener is refused before it binds unless both are set.
The issuer is an https address unless the authorization server runs on
this machine (localhost, 127.0.0.1 or ::1), and that holds in every
mode: with the keys read from the issuer, with a key file, and with a
proxy in front. Every client is sent to the issuer to obtain its token,
so a plain http issuer on another host would carry each client's
authorization code and token across the network unprotected, and a
listener naming one is refused before it binds.
The verification keys are read from the issuer itself, by asking it where
it publishes them and fetching them from the address it names, and read
again once when a token arrives signed by a key identifier the held set
does not carry. That address is held to the same rule as the issuer, and
so is every redirect either read is answered with: a plain http address
on another host is never asked, and a token needing those keys is
answered 503 until the authorization server publishes its metadata and
keys over https. A workspace that is offline makes no such request, so
there mcp.authorization.jwks_file names a file holding those keys and a
listener is refused before it binds without it.
Liveness and readiness are answered on a second address, and only there.
Set mcp.health.listen and a GET of /healthz reports that the process is
running while a GET of /readyz reports whether it can answer a call yet,
each a status code with an empty body and no credential asked for. The
address opens before the workspace is resolved, so a supervisor sees the
process alive while it is still deciding whether it can serve at all.
Leave the key unset and no second listener exists. The endpoint itself
answers both paths the same not-found it gives every path it does not
serve, with a token and without one, so reaching this process over the
network is never a way to probe it.
The workspace this process serves is fixed when it starts, on either
transport: --workspace-root names it, and AGGREGA_WORKSPACE_ROOT supplies
it when the flag is absent. The folder named is the workspace root
itself, as it is for every command: a call naming no workspace of its
own is answered there, and nothing above it is searched for a workspace,
so name the folder that holds the workspace's .aggrega-config.yaml. A
named folder that does not exist is refused, naming the flag or the
variable that supplied it and the value as it was given: a listener is
refused before it binds, while a server on standard input and output
writes the refusal to stderr and starts all the same, answering every
call that acts in that workspace with it, so a client that shows
nothing of stderr still shows the refusal. An empty
AGGREGA_WORKSPACE_ROOT is read as unset, but for one launch: a server
on standard input and output given no --workspace-root, whose
environment carries the AGGREGA_BUNDLE_VERSION the desktop bundle sets,
was started with the desktop application's Workspace folder setting
empty. It is served the same way, the refusal naming that setting, so
no call naming no workspace of its own is answered in the directory it
was started in. In every other case where neither names a root, a
server on standard input and output resolves the workspace from the
directory it was started in, while a listener is refused before it
binds unless a workspace resolves there: one reached
over HTTP serves a workspace an operator chose rather than
whichever directory it happened to be started in. Where that directory
anchors no workspace, a call naming no workspace of its own that names
its Release or document by an absolute path is answered in the workspace
that file's folder resolves, as the same command typed at a terminal in
that directory would be.
For the same reason a call arriving over HTTP cannot name a workspace of
its own. Sending workspace_root or catalog_dirs is refused, naming the
argument, and the directories searched for catalog entities beside the
served workspace are the ones that workspace itself resolves: its own
workspace.catalog_dirs setting — or, for a Release it gives directories
of its own under workspace.releases, that Release's — then its catalog
directory. Over
standard input and output both arguments are honoured: the client that
launched the server is running on this machine.
A workspace_root such a call sends is read the same way by every tool,
the tools that run a command included. An absolute one is used as
given. A relative one is read from the root a call naming no workspace
of its own is answered in — the folder --workspace-root or
AGGREGA_WORKSPACE_ROOT names, which the desktop application sets from
its Workspace folder, or, where neither names one, the workspace root
the directory the server was started in resolves to — so a client that
cannot see where that folder sits on the machine still names a folder
inside it, as quickstart-ai/1. Where there is no such root to read it
from, a relative one is refused as a call naming none is refused, and
an absolute one is answered as it always is.
Asking the process itself to stop — an interrupt from the terminal, or a
termination request from a supervisor or container runtime — shuts the
server down on the first request, whether or not a client is sending
anything: it stops accepting messages, ends the work a call in progress
is doing, and exits cleanly. A listener stops accepting and lets a call
already being answered finish, within a bounded budget, before the
process exits. A second request ends the process at once.

Flags

FlagPredefiniçãoDescrição
--listen—O endereço em que o transporte HTTP escuta, numa de duas formas: host:port, ou unix: seguido de um caminho no sistema de ficheiros. Indica onde escutar e não escolhe nenhum transporte: é lido com —transport http, ou com mcp.transport: http na configuração do espaço de trabalho, e é recusado quando dado com o transporte stdio. Um listener sem certificado serve em texto simples e só é permitido em loopback (127.0.0.1, ::1, localhost) ou num socket Unix, que é a forma que assume um servidor por detrás de um proxy que termina a ligação; qualquer outro endereço precisa de mcp.tls.cert_file e mcp.tls.key_file, que este processo usa então para terminar ele próprio o TLS. Quando definido, substitui a chave de configuração mcp.listen.
--transport—Como se chega ao servidor: stdio fala o protocolo através da entrada e saída padrão, que é a forma como um cliente que lança este comando como subprocesso chega a ele; http serve-o através de HTTP no endereço que —listen ou mcp.listen nomeia, e através de HTTPS quando mcp.tls nomeia um certificado e uma chave. Quando definido, substitui a chave de configuração mcp.transport, cuja predefinição é stdio.

O que faz

aggrega mcp executa um servidor Model Context Protocol. Há dois transportes que chegam a ele, e --transport escolhe entre eles: stdio ou http, com mcp.transport na configuração do espaço de trabalho como a chave que a flag substitui, e stdio como predefinição.

Através de stdio, a predefinição, comunica pela entrada e saída padrão do processo. Nessa forma, não é um comando que se execute interativamente — um cliente compatível com MCP lança-o como subprocesso e fala o protocolo através de stdio; Ligar o servidor MCP indica onde cada cliente guarda a entrada que o lança. Executá-lo transforma a CLI num assistente de autoria que conhece o Aggrega dentro do editor ou do cliente de chat.

Através de http, serve o protocolo através de HTTP: um processo de longa duração num anfitrião, contactado por chamadores que não estão ao seu teclado, a escutar no endereço que --listen nomeia, ou mcp.listen quando a flag está ausente. Consulte Chegar ao servidor através de HTTPS para saber como esse listener é configurado e o que aceita.

Fala duas revisões do protocolo, 2026-07-28 e 2025-06-18, pelo que um cliente de qualquer uma delas se liga e chega às mesmas superfícies. A revisão que uma chamada fala é indicada nessa chamada e não acordada uma vez para a ligação. Um cliente em 2026-07-28 envia a versão do protocolo que fala e as suas próprias capacidades com cada pedido, e pergunta a server/discover o que o servidor suporta; um cliente em 2025-06-18 estabelece essas mesmas coisas uma vez, abrindo a ligação com um handshake initialize. Em qualquer dos casos, o servidor não guarda nada entre mensagens, pelo que o que se envia primeiro não decide nada sobre a forma como uma chamada posterior é respondida. Um pedido que nomeie uma revisão que o servidor não fala é recusado e informado das duas que pode pedir, em vez de ser respondido como se tivesse pedido uma delas.

O servidor expõe três superfícies ao assistente ligado:

  • Prompts — duas famílias, e a diferença está no que cada uma responde. Os prompts de autoria respondem a «o que estou a escrever»: uma persona por função (programador, arquiteto, operações), mais um template específico por entidade. Cada um enquadra a função e aponta o assistente para o esquema, a página de referência e o guia de autoria certos, para que as suas sugestões fiquem dentro dos pilares que essa função detém. Os prompts de fluxo de trabalho respondem a «que chamadas, por que ordem»: cada um expõe a sequência ordenada de chamadas de ferramentas que alcança um objetivo que abrange várias operações, com os pontos de decisão entre elas — compor um novo Aggregate e a sua Release de raiz, trazer um chart, um módulo de infraestrutura ou um ficheiro container-compose existente para o Aggrega, descobrir porque é que uma compilação não compila ou renderiza os artefactos errados. prompts/list enumera ambas as famílias e prompts/get apresenta um, pelo que o conjunto é lido a partir do servidor e não desta página.

    Um prompt de fluxo de trabalho nomeia as chamadas e é o utilizador que as faz, uma de cada vez, lendo cada resultado antes da seguinte. Não há nenhuma chamada que execute um objetivo completo: cada ferramenta encapsula uma operação que se pode verificar, pelo que é a sequência que leva ao objetivo. As personas de autoria aceitam um kind opcional em que se concentrar, o template por entidade exige um, e um kind a que nenhum esquema corresponda é recusado com o conjunto aceite listado em vez de ser ignorado discretamente.

  • Recursos — material de referência só de leitura servido inline: schema://<kind> para o JSON Schema de uma entidade, langref://<path> para qualquer página da referência da linguagem, authoring://<topic> para o guia de autoria, catalog://<kind>/<name> para o YAML escrito de uma entidade de catálogo, e cli://<command> para a ajuda de um comando, com cli:// isoladamente como ponto de entrada — essa ajuda é respondida a partir dos comandos que o próprio servidor contém, pelo que ler uma não inicia nenhum processo e devolve o mesmo texto que o comando imprime para --help. Uma leitura catalog:// de uma entidade que o catálogo não contém é respondida como não encontrada; quando isso se deve a exatamente um ficheiro de catálogo que declara a entidade ter sido ignorado no carregamento, a mensagem da resposta indica esse ficheiro, a restrição que viola e o código curto da condição, em vez de apenas o URI — a recusa com que aggrega build começa para o mesmo ficheiro. resources/list enumera os que são endereçáveis sem parâmetro e resources/templates/list anuncia a forma de URI de cada família.

  • Ferramentas — ações sobre o espaço de trabalho, e tools/list responde com todas elas.

    As ferramentas que um assistente encontra primeiro estão moldadas para o ciclo de autoria: list-entities e list-releases para descobrir o que o espaço de trabalho contém, scaffold um esqueleto com os campos que o seu tipo exige, com um marcador de posição onde quer que seja devido um valor — ou, quando recebe example, escrever um dos exemplos executáveis da documentação num novo diretório, respondendo com a localização desse diretório, os ficheiros escritos e os comandos para o compilar, e, quando recebe list: true, listar os exemplos — get-schema para o JSON Schema de uma entidade, validate um rascunho (nomeia todos os marcadores de posição que o rascunho ainda contém e o que cada um aceita), describe uma entidade de catálogo — ou uma entidade lida do seu registo por referência —, pull para resolver as dependências de uma Release para a cache local e escrever o seu lockfile, build uma Release nos seus artefactos renderizados — em memória por predefinição, sem nenhum artefacto escrito em disco, ou escritos em dist/ na raiz do espaço de trabalho, onde aggrega build os escreve, quando se envia write (e as dependências só são resolvidas primeiro se se enviar auto_pull) —, gen-catalog para gerar entidades Plugin a partir de guests Wasm, e explain-error para expandir um diagnóstico do compilador em orientações acionáveis — incluindo, quando o diagnóstico começa com o código curto de uma condição de paragem, essa condição e o percurso guiado publicado da correção de autoria, a mesma expansão que aggrega explain dá para o mesmo código num terminal.

    O resto da superfície está na mesma resposta e não por detrás dela: outras ferramentas que são executadas dentro do servidor — lint, a ferramenta que nomeia a ligação escrita num local de um documento, as duas ferramentas de candidatura, as ferramentas de contentor de anexações e de ponto de inserção, a ferramenta que aplica uma edição delimitada a um documento, pin, que regista as fixações de conteúdo para as entradas de uma entidade como estabelece Fixar as entradas próprias de uma entidade, e as quatro ferramentas de publicação descritas abaixo, além de inventários das caches e dos registos configurados — e, para um cliente que lançou este servidor através da sua entrada e saída padrão, uma ferramenta para cada comando que de outro modo se escreveria, com o nome do seu caminho de invocação. Essas ferramentas de comando existem apenas nesse transporte: um servidor contactado através de HTTP não oferece nenhuma delas, pela razão indicada em Chegar ao servidor através de HTTPS. Nada é retido para uma chamada posterior. Quanto de uma lista de ferramentas colocar à frente de um modelo é uma decisão do cliente — obtém as definições e escolhe o que carregar — e uma definição que um cliente nunca recebeu é uma operação que um modelo nunca pode chamar, por mais acessível que o nome dessa ferramenta seja na transmissão. Quando a lista completa é maior do que o cliente aceita, Restringir o que o servidor anuncia é a forma de a encurtar. describe-capabilities restringe essa superfície ao tipo de entidade que se está a escrever. Quando recebe um kind, responde com as ferramentas que servem esse tipo, lidas a partir dos tipos que cada ferramenta declara e não das palavras de uma descrição; quando não recebe argumentos, responde com esse mesmo índice sobre todas as ferramentas que este servidor oferece — o nome de cada uma, uma finalidade numa linha, os tipos que serve e se escreve, e nenhum esquema de argumentos, pelo que toda a superfície chega numa única resposta legível. Para uma ferramenta cli-, escrever ou não é o mesmo que o comando que executa escrever ou não: cli-build é reportada como escrevendo, porque o comando guarda os artefactos renderizados sob a raiz do espaço de trabalho, e o mesmo acontece com cli-scaffold, porque, quando recebe example, o comando escreve um dos exemplos executáveis da documentação num novo diretório, enquanto um comando que apenas lê é reportado como só de leitura, mesmo quando preenche pelo caminho uma cache que todos os projetos da máquina partilham, tal como a ferramenta que executa a mesma operação dentro do servidor; quando recebe tools a nomear uma ou mais, responde com exatamente as definições completas e os esquemas de argumentos dessas ferramentas. As ferramentas cli- nunca são restringidas por tipo, porque nada regista que tipo de entidade um comando serve, pelo que uma resposta circunscrita a um tipo as deixa de fora e o índice sem argumentos é onde se leem. Os argumentos de uma ferramenta de comando têm os nomes das flags do próprio comando, pelo que --output-dir é enviado como output_dir, e um nome não reconhecido é recusado com as grafias aceites listadas em vez de ser descartado discretamente.

    Algumas capacidades existem em duplicado na entrada e saída padrão: uma ferramenta moldada para o ciclo de autoria executa a operação dentro do servidor, e a ferramenta com o nome do comando que contém a mesma capacidade executa esse comando. As duas não se comportam da mesma forma, pelo que nesse transporte cada uma nomeia a outra e indica a diferença; através de HTTP as ferramentas de comando estão ausentes, e a frase de emparelhamento é omitida em vez de apontar para uma ferramenta a que o chamador não consegue chegar. A que é executada dentro do servidor é a que se deve usar — responde com um resultado legível por máquina ao lado do texto legível, pelo que um assistente obtém um veredicto, uma lista de ficheiros ou um diagnóstico como campos e não como uma transcrição a analisar. A ferramenta de comando inicia o comando real num processo separado, pelo que faz tudo o que esse comando faz na máquina em que é executado, incluindo escrever em disco onde o comando escreve — cli-build escreve os artefactos renderizados em dist/ na raiz do espaço de trabalho, e os ficheiros de uma compilação com rastreio em .trace/ ao lado, e a linha final que devolve nomeia esse diretório por extenso — e devolve apenas a linha de comandos que executou e o texto que esse comando imprimiu. Recorra a ela quando precisar de uma flag que o comando declara e que a outra ferramenta não aceita.

    Essa linha de comandos começa com as flags globais com que este servidor foi iniciado e que decidem a configuração — --config e --offline, quando foram dadas — antes do comando e das flags próprias da chamada. Assim, o comando lê a configuração que todas as outras ferramentas aqui leem: um servidor iniciado com --offline executa os seus comandos offline, e um iniciado com --config executa-os sobre esse ficheiro global. Uma flag que a chamada envia por si própria vem depois delas e prevalece, pelo que offline: false numa chamada acede à rede apenas para essa chamada, e a linha de comandos devolvida mostra ambas. Quando o servidor foi iniciado com uma raiz de espaço de trabalho — por --workspace-root ou por AGGREGA_WORKSPACE_ROOT — a linha de comandos começa com essa raiz como --workspace-root, antes dessas duas, para que o comando tome esse diretório como a sua raiz de espaço de trabalho, como faria se escrito com a mesma flag e como todas as ferramentas executadas dentro do servidor a tomam, em vez de encontrar o seu espaço de trabalho a partir do diretório em que o servidor foi iniciado. Uma chamada que envia workspace_root nomeia a sua própria, e a linha de comandos contém apenas essa — incluindo um valor vazio, que o comando lê tal como --workspace-root "" é lido num terminal: encontrar o espaço de trabalho a partir do diretório em que o servidor foi iniciado. Um servidor iniciado sem nenhuma delas não passa nenhuma raiz, pelo que os seus comandos encontram o seu espaço de trabalho a partir desse diretório, segundo a regra que Em que espaço de trabalho é respondida uma chamada estabelece para todas as ferramentas — exceto no lançamento do pacote de ambiente de trabalho com a sua definição Workspace folder vazia, em que uma chamada que não nomeia nenhum espaço de trabalho próprio não inicia nenhum comando e é respondida com a recusa dessa definição. O comando é iniciado na raiz do espaço de trabalho que a chamada ou o lançamento nomeia: o workspace_root da própria chamada, lido tal como todas as ferramentas o leem — um absoluto tal como foi enviado, um relativo a partir da raiz em que é respondida uma chamada que não nomeia nenhum — e passado ao comando na sua forma absoluta, ou, caso contrário, a raiz com que o servidor foi iniciado. Assim, um caminho relativo que uma chamada passa como ficheiro a ler — um documento a validate, um --release ou um --catalog — é lido dentro desse espaço de trabalho, como num terminal aberto aí, e uma compilação que o comando executa escreve dist/ sob essa raiz. Quando nada nomeia uma raiz — nenhuma raiz de lançamento, e nenhum workspace_root ou um vazio — o comando é iniciado no diretório em que o servidor foi iniciado e lê um caminho relativo a partir daí; um workspace_root que não nomeie nenhuma pasta existente é passado tal como foi lido — um absoluto tal como foi enviado, um relativo na sua forma completa — e o comando recusa-o nas suas próprias palavras. Um comando que um plugin de extensão de comandos regista não recebe nenhuma delas, porque passa todos os argumentos ao plugin sem os ler em vez de analisar uma flag global, num terminal como aqui; é iniciado na mesma pasta que todos os outros comandos.

    Alguns comandos estão deliberadamente ausentes mesmo na entrada e saída padrão, onde as ferramentas de comando existem — através de HTTP estão todos ausentes, e isso é uma propriedade do transporte e não de nenhum comando. Na entrada e saída padrão, cada um destes é deixado de fora por uma razão declarada: o daemon e este próprio servidor nunca devolveriam um resultado; um comando que lê uma palavra-passe do terminal não tem de onde a ler; um que escreve um script de conclusão automática da shell não tem nenhuma shell onde o instalar; remover uma credencial guardada atua sobre o armazenamento de toda a máquina e não sobre nenhum espaço de trabalho nomeado; e adquirir um token de identidade interativamente não tem nenhuma forma não interativa a oferecer. Ausente pela mesma razão de abranger toda a máquina está aggrega plugin run-local, que carrega um guest .wasm a partir de um caminho que se lhe dá: aquilo para que serve o comando é ler um ficheiro onde quer que tenha sido colocado, pelo que não há nenhum espaço de trabalho a que possa ser confinado, e a leitura acontece no próprio processo antes de o guest existir. O guest não recebe nada quando é executado — nenhum diretório, nenhum socket, nenhum ambiente — mas isso é um limite sobre o módulo e não sobre a leitura, pelo que não é o que decide isto. Execute-o no seu terminal, onde é o utilizador que nomeia o caminho. A assinatura e a publicação são um caso totalmente diferente, e a diferença é o que as mantém fora dessa lista. Cada uma delas resolve uma identidade a partir de uma entrada fornecida ou do ambiente e recusa de forma explícita quando nenhuma está disponível, pelo que cada uma tem uma forma que se completa sem ninguém a observar — enquanto adquirir um token interativamente é um verbo que nenhuma entrada consegue satisfazer, nem sequer em princípio. Por isso estão presentes duas vezes: como os comandos e como as quatro ferramentas dentro do processo descritas em Publicar, assinar e retirar. Quando a linha de comandos abriria um browser, recusam e nomeiam o que fornecer em alternativa, em vez de esperarem por uma pessoa que não está lá.

Em que espaço de trabalho é respondida uma chamada

Uma chamada nomeia o seu espaço de trabalho com workspace_root; caso contrário, é respondida no espaço de trabalho sobre o qual o servidor foi iniciado. Quando o lançamento nomeou uma raiz, com --workspace-root ou AGGREGA_WORKSPACE_ROOT, essa raiz é a própria raiz do espaço de trabalho, tal como a flag o é em todos os comandos: nada acima dela é pesquisado em busca de um espaço de trabalho envolvente, pelo que um lançamento nomeia a pasta que contém o .aggrega-config.yaml do espaço de trabalho, e uma chamada é aí respondida tanto pelas ferramentas executadas dentro do servidor como pelas ferramentas de comando. Quando o lançamento não nomeou nenhuma, o espaço de trabalho é encontrado a partir do diretório em que o servidor foi iniciado, exatamente como um comando escrito num terminal aí o descobre — a ordem é exposta em As outras formas de reconhecer a raiz de um projeto — exceto no lançamento do pacote de ambiente de trabalho com a sua definição Workspace folder vazia, que recusa uma chamada dessas, como se expõe abaixo. Um workspace_root relativo é lido a partir da raiz em que é respondida uma chamada que não nomeia nenhum — a raiz que o lançamento nomeou ou, quando não nomeou nenhuma, a raiz do espaço de trabalho a que corresponde o diretório em que o servidor foi iniciado — pelo que uma chamada nomeia uma pasta dentro do espaço de trabalho, como quickstart-ai/1, sem saber onde o espaço de trabalho se encontra na máquina; um absoluto é usado tal como é dado. Todas as ferramentas o leem assim, incluindo as ferramentas de comando. Quando não há nenhuma raiz a partir da qual ler um relativo — uma raiz de lançamento que não seja uma pasta existente, ou o lançamento de ambiente de trabalho com Workspace folder vazio — um relativo é recusado tal como o é uma chamada que não nomeia nenhum. Um workspace_root que não nomeie nenhuma pasta existente, ou que nomeie um ficheiro, é recusado antes de a ferramenta fazer qualquer outra coisa, nomeando o argumento e citando o valor — um absoluto tal como foi enviado, um relativo na forma completa em que foi lido — tal como um comando recusa --workspace-root.

Uma raiz de lançamento que não seja uma pasta existente é servida como recusa na entrada e saída padrão. Quando --workspace-root ou AGGREGA_WORKSPACE_ROOT nomeia uma pasta que não existe, ou nomeia um ficheiro, o servidor escreve a recusa no seu fluxo de erros e arranca mesmo assim, para que um cliente que não mostra ao utilizador nada desse fluxo mostre ainda assim o porquê. Responde a initialize e às suas listas de ferramentas, recursos e prompts, e todas as chamadas que atuariam nesse espaço de trabalho são respondidas com a recusa: uma chamada de ferramenta como resultado falhado, uma leitura de uma entidade catalog:// ou de uma página de documentação como erro. A recusa nomeia a flag, ou a variável juntamente com a definição Workspace folder da aplicação de ambiente de trabalho que a define — a definição que Claude Desktop descreve — e cita o valor exatamente como foi dado; um valor que o cliente enviou sem o preencher é citado tal como chegou, e nada nele é reconhecido. Uma ferramenta que executa um comando não inicia nenhum para uma chamada que não nomeia nenhum espaço de trabalho próprio, já que a pasta em que esse comando seria iniciado não existe, e responde com a mesma recusa. Uma chamada que nomeia um espaço de trabalho próprio por um caminho absoluto é aí respondida; uma que o nomeia por um caminho relativo não tem nenhuma pasta a partir da qual o ler, e é respondida com a mesma recusa. O que não atua em nenhum espaço de trabalho — um esquema, um prompt, a ajuda de um comando — é respondido como em qualquer servidor. Um listener é, em vez disso, recusado no arranque, antes de qualquer associação, com a mesma recusa, para que quem o supervisiona leia a falha onde a procura.

Um lançamento de ambiente de trabalho com a sua definição Workspace folder vazia é servido como recusa da mesma forma. O pacote de ambiente de trabalho passa sempre ao servidor AGGREGA_WORKSPACE_ROOT, com o que quer que Workspace folder contenha, e define AGGREGA_BUNDLE_VERSION ao lado, enquanto a aplicação inicia o servidor numa pasta à sua escolha — muitas vezes uma pasta do sistema — e não no projeto. Assim, um servidor na entrada e saída padrão iniciado sem --workspace-root, cujo ambiente contém AGGREGA_BUNDLE_VERSION e um AGGREGA_WORKSPACE_ROOT vazio ou ausente, não procura um espaço de trabalho a partir da pasta em que foi iniciado. Escreve a recusa no seu fluxo de erros e arranca mesmo assim, respondendo como responde a uma raiz de lançamento inexistente: todas as chamadas que atuariam num espaço de trabalho e não nomeiam nenhum próprio são respondidas com uma recusa que indica que a aplicação de ambiente de trabalho lançou o servidor com a sua definição Workspace folder vazia, pelo que AGGREGA_WORKSPACE_ROOT não nomeia nenhuma raiz de espaço de trabalho, que diz para definir Workspace folder com a pasta que contém o .aggrega-config.yaml do espaço de trabalho, e que indica que uma pasta definida depois de o servidor arrancar só produz efeito quando a extensão é desativada e reativada ou a aplicação é reiniciada, porque a aplicação só passa a definição ao servidor quando o inicia. Uma ferramenta que executa um comando não inicia nenhum para uma chamada dessas. Uma chamada que nomeia um espaço de trabalho próprio por um caminho absoluto é aí respondida, e uma que o nomeia por um caminho relativo é respondida com a mesma recusa, já que não existe nenhum Workspace folder a partir do qual o ler; o que não atua em nenhum espaço de trabalho é respondido como em qualquer servidor. O servidor reconhece o lançamento apenas por AGGREGA_BUNDLE_VERSION: num pacote que não defina essa variável, uma definição vazia é lida como ausência de raiz, e um lançamento que define a variável à mão e não nomeia nenhuma raiz é recusado como o do pacote. Qualquer outro valor vazio continua a não nomear nenhuma raiz — um AGGREGA_WORKSPACE_ROOT vazio num lançamento sem AGGREGA_BUNDLE_VERSION, um --workspace-root escrito vazio, um listener, aggrega serve e todos os outros comandos leem-no como não definido.

Quando nenhum espaço de trabalho foi encontrado e nenhum foi nomeado, uma resposta sobre o espaço de trabalho indica que pasta usou. Sem raiz de lançamento, sem workspace_root na chamada e sem nada que ancore um espaço de trabalho a partir da pasta em que a chamada foi respondida, a chamada é respondida nessa pasta. Quando o resultado da ferramenta depende do espaço de trabalho — as mesmas ferramentas cujos comandos emitem um aviso na linha de comandos — o seu texto termina com o aviso da linha de comandos, <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace, e com uma linha a dizer para enviar workspace_root a nomear a pasta que contém o .aggrega-config.yaml do espaço de trabalho; uma resposta que o espaço de trabalho não determina, como a leitura da configuração ou a listagem de plugins, não diz nada sobre espaços de trabalho. A frase não acrescenta nenhum campo próprio ao resultado estruturado; o resultado estruturado contém-na em text_answer, que contém o texto, como estabelece As duas partes de uma resposta. Uma ferramenta que executa um comando num processo separado contém a própria linha do comando a dizer o mesmo, tal como o comando a imprimiu. Nada é escrito numa cache de artefactos numa pasta dessas: um pull, ou uma compilação a que se pediu que resolvesse primeiro as suas dependências, é aí recusado antes de qualquer obtenção, nomeando a pasta e as duas saídas — enviar workspace_root, ou dar à pasta um .aggrega-config.yaml com um bloco workspace:. Uma fixação, ou uma publicação de uma Recipe ou FeatureRecipe, é recusada da mesma forma quando obteria uma fonte remota que a entidade escreve por extenso — para a fixar, ou para comparar a sua fixação — antes de essa fonte ser obtida; quando não obtém nenhuma, porque a entidade não tem fonte, tem uma local ou uma cujas coordenadas cada Release preenche, é respondida como em qualquer outro local. Uma compilação aí que não resolve nada primeiro continua a renderizar, mas uma entrada externa que o seu lockfile fixa e que a cache já não contém não é obtida novamente: a renderização recebe essa mesma frase em lugar da entrada, tal como recebe a de uma postura offline. Nenhuma resposta através de HTTP contém a frase: um listener serve sempre um espaço de trabalho que lhe foi dado ou que encontrou. Nem o lançamento do pacote de ambiente de trabalho com uma definição Workspace folder vazia, que recusa uma chamada que não nomeia nenhum espaço de trabalho próprio em vez de a responder na pasta em que foi iniciado.

Uma chamada sobre uma Release ou um documento que nomeia por um caminho absoluto é respondida no próprio espaço de trabalho desse ficheiro quando nada mais estabeleceu um. Quando o lançamento não nomeou nenhuma raiz, a chamada não envia nenhum workspace_root e o diretório em que o servidor foi iniciado não ancora nenhum espaço de trabalho, o espaço de trabalho é novamente descoberto a partir da pasta em que esse ficheiro se encontra, e o que quer que isso encontre — o projeto a que o ficheiro pertence ou, na falta de tudo, essa pasta — é aquele em que a chamada é respondida. É essa a regra que um comando escrito num terminal segue, pelo que se aplica a todas as ferramentas cuja chamada diz respeito a uma Release ou a um documento de entidade que nomeia: uma compilação, um pull, uma validação, um lint, uma descrição, uma listagem nos termos de uma Release, uma pergunta sobre um nó do grafo de uma Release, uma fixação, a publicação de uma entidade, uma edição e uma posição lida num documento. Quando uma chamada nomeia tanto uma Release como um documento, a Release decide. Assim, um cliente que lançou o servidor fora do projeto continua a ter uma Release desse projeto compilada a partir da própria configuração do projeto. Os outros caminhos que a chamada nomeia são lidos como sempre — um relativo a partir do diretório em que o servidor foi iniciado — e uma ferramenta que executa um comando num processo separado é respondida a partir do mesmo espaço de trabalho, porque o comando segue a mesma regra nesse mesmo diretório. Uma raiz que o lançamento nomeou, um workspace_root que a chamada envia, um diretório inicial que esteja ele próprio dentro de um espaço de trabalho, e uma Release ou um documento nomeados por um caminho relativo são usados tal como estão. Através de HTTP, nada disto acontece: um listener serve sempre um espaço de trabalho que lhe foi dado ou que encontrou, e todos os caminhos que uma chamada nomeia são relativos a ele. Nem no lançamento do pacote de ambiente de trabalho com uma definição Workspace folder vazia, que recusa uma chamada que não nomeia nenhum espaço de trabalho próprio, seja qual for o ficheiro que nomeie.

Restringir o que o servidor anuncia

mcp.announce_tools nomeia as ferramentas que este servidor anuncia, escritas exatamente como a lista de ferramentas as reporta. Se a chave for omitida, todas as ferramentas que este servidor contém são anunciadas, que é a predefinição e a forma que um cliente que segue o protocolo espera. Escreva uma lista e são anunciadas exatamente essas ferramentas: uma deixada de fora está ausente da lista de ferramentas, ausente do que describe-capabilities responde e é recusada se mesmo assim for chamada pelo nome, com a recusa a nomear esta definição. Escreva uma lista vazia e nada é anunciado — pelo que omitir a chave e escrever [] são afirmações diferentes, e a definição não tem nenhuma predefinição preenchida pelo utilizador.

Defina-a quando o cliente do outro lado limita quantas ferramentas regista, por vezes em todos os servidores a que está ligado ao mesmo tempo, e nomeie as ferramentas de que esse cliente precisa. Esse limite é o caso para o qual a definição existe, e o cliente a que se aplica é normalmente o que lançou este servidor através da sua própria entrada e saída padrão — pelo que, ao contrário do resto do bloco mcp, que configura o listener que o transporte http inicia, esta chave é lida seja qual for o transporte que o servidor fala.

Restringe o que é anunciado e nada mais. Nomear aqui uma ferramenta não alarga nada. Não levanta mcp.deny_reach, que retira uma capacidade por completo, pelo que uma ferramenta aqui nomeada de um tipo que essa definição retira fica fora da lista e é recusada nomeando essa definição. Também não levanta os âmbitos que o token de um chamador contém: uma ferramenta aqui nomeada é listada sejam quais forem esses âmbitos, e uma chamada que eles não admitam continua a ser recusada, nomeando o âmbito que a admitiria. Em qualquer dos casos, a recusa que um chamador encontra é a desse outro limite e não a deste. Uma recusa desta definição não contém nenhum desafio e não nomeia nenhum âmbito, porque nenhuma credencial altera o que um servidor escolheu oferecer — o que nomeia é a definição, que é a única coisa sobre a qual quem lê a recusa pode agir.

Cada nome tem de ser um que este binário contenha. Um nome a que nenhuma ferramenta corresponda faz parar o servidor antes de servir o que quer que seja, e a recusa lista as ferramentas que tem — pelo que um erro de escrita é detetado no arranque e não através de uma superfície discretamente mais restrita do que a pedida. 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 dessas é oferecida a nenhum chamador.

O conjunto anunciado é fixado quando o processo arranca, pelo que alterá-lo exige um reinício e nada faz crescer a lista para um cliente que já está ligado.

De que versão vem o servidor

describe-capabilities sem argumentos indica de que versão vem este servidor. A sua resposta estruturada contém server_version, a versão que o executável aggrega reporta para si próprio — a que aggrega version imprime para o mesmo ficheiro —, e o seu texto começa com uma linha que a nomeia, antes do índice. A resposta estruturada contém essa mesma linha como version_summary, palavra por palavra, para que um cliente que entregue a um modelo apenas a resposta estruturada lhe entregue também a linha.

Quando foi o pacote de ambiente de trabalho a lançar o servidor, a mesma resposta nomeia a versão do pacote ao lado. O pacote não contém nenhum programa: lança o executável aggrega que a sua definição Path to the aggrega executable nomeia — por predefinição, o nome de comando aggrega, que a aplicação procura no seu PATH —, pelo que o pacote e o executável são instalados separadamente e podem vir de versões diferentes, e a aplicação que lista o pacote mostra apenas a versão do próprio pacote. O pacote passa ao servidor a sua versão como AGGREGA_BUNDLE_VERSION no seu ambiente; o servidor lê-a uma vez, quando arranca, e a resposta contém-na como bundle_version. As duas são comparadas exatamente como estão escritas, o que é uma comparação justa porque o pacote e o executável de uma mesma versão são marcados com a versão dessa versão na mesma forma, enquanto uma compilação de desenvolvimento se lê de forma diferente de todas as versões. Quando as duas são iguais, a linha nomeia ambas e não diz mais nada. Quando diferem, a linha indica, nomeando ambas, que o executável e o pacote vêm de versões diferentes, e a orientação que o servidor oferece a um modelo quando este se liga começa com essa mesma frase, para que a diferença esteja à frente do modelo antes de ele perguntar.

Um servidor que nenhum pacote lançou reporta apenas a sua própria versão. Iniciado a partir de um terminal, da configuração de um editor ou como listener, não contém nenhum bundle_version, a menos que algo defina a variável no seu ambiente. Um servidor na entrada e saída padrão que contenha a variável é tomado como o lançamento do pacote em mais um aspeto: sem raiz nomeada, recusa a definição Workspace folder vazia, como estabelece Em que espaço de trabalho é respondida uma chamada. Uma chamada describe-capabilities que receba kind ou tools não contém nenhum server_version, bundle_version ou version_summary nem nenhuma linha dessas, porque responde sobre ferramentas e não sobre o servidor.

Uma diferença é reportada e nunca recusada. O servidor arranca e responde a todas as chamadas exatamente como faria com os dois em sintonia. O que uma diferença significa para uma instalação de ambiente de trabalho, e como alinhar os dois, está em Ligar o servidor MCP.

Chegar ao servidor através de HTTPS

aggrega mcp --transport http serve o protocolo através de HTTP em vez de através da entrada e saída padrão. mcp.transport na configuração do espaço de trabalho é a chave que essa flag substitui, e a sua predefinição, stdio, é o que um cliente que lança o comando espera — pelo que um servidor contactado por outras pessoas contém transport: http na sua configuração, e um cliente lançado a partir de um diretório abrangido por essa configuração continua a chegar ao servidor através dos seus próprios fluxos. É o mesmo servidor em qualquer dos casos — o mesmo espaço de trabalho e as mesmas superfícies de protocolo — e o que muda é a forma como uma mensagem lhe chega, como uma chamada termina e o que quem o executa tem de ter. Esta secção é o que um operador configura; a entrada de que um cliente precisa para chegar a um servidor em execução está em Ligar o servidor MCP.

Um endereço não escolhe nenhum transporte. --listen <address>, ou mcp.listen quando a flag está ausente, nomeia onde o listener se associa depois de http ser escolhido, e nada mais. Assim, http sem endereço de nenhuma das duas é recusado antes de qualquer associação, e a recusa nomeia ambas. --listen escrito enquanto o transporte é stdio — escrito como --transport stdio, configurado como mcp.transport: stdio ou deixado como predefinição — é também recusado, nomeando --transport http como a flag que serviria nesse endereço; um --listen com um valor vazio é recusado por não nomear nenhum endereço, seja qual for o transporte. E um endereço que só a configuração nomeia fica sem uso num servidor que fala através dos seus próprios fluxos, que o indica numa linha no seu fluxo de erros, nomeando o ficheiro que o definiu e mcp.transport: http. Este último caso não é recusado em lado nenhum de propósito: é o lançamento que um cliente faz quando inicia o comando num diretório cuja configuração contém as definições de um listener, e a configuração de um listener que esqueça transport: http não inicia nenhum listener, que é onde isso se vê.

Um servidor contactado através de HTTP não oferece nenhuma ferramenta que execute um comando aggrega num processo separado. Essas ferramentas só existem para um cliente que lançou este servidor através da sua entrada e saída padrão, na própria máquina desse cliente, onde nomear uma pasta ou uma flag não concede ao chamador nada que ele ainda não tivesse. Um chamador que chega ao servidor através de HTTP não é dono do anfitrião em que este é executado, pelo que um comando que atuaria sobre o sistema de ficheiros desse anfitrião com a autoridade do próprio servidor é, em vez disso, executado num terminal no anfitrião. As ferramentas estão ausentes da lista e de describe-capabilities em vez de serem oferecidas e recusadas, e uma chamada que nomeie uma delas é respondida com um erro que o indica. Isso é uma propriedade do transporte, não uma definição: não há nenhuma configuração que as reponha.

Leia Nada é servido sem uma credencial antes de implementar um. Cada pedido ao endpoint contém uma credencial, e não há nenhuma definição que sirva um pedido sem ela — o que uma definição escolhe é se este servidor verifica ele próprio um bearer token ou lê um chamador que um proxy à frente já verificou.

As duas formas de implementação

O processo termina ele próprio o TLS. Defina mcp.tls.cert_file com uma cadeia de certificados PEM e mcp.tls.key_file com a respetiva chave privada, e o listener serve HTTPS diretamente em qualquer endereço que lhe tenha sido dado. Ambos os ficheiros são lidos quando o processo arranca, pelo que um certificado substituído é carregado reiniciando o processo. Definir um sem o outro é recusado no arranque em vez de recorrer a uma alternativa: um certificado sem chave não pode ser apresentado e uma chave sem certificado não nomeia nada, e um erro de escrita num caminho não é razão para começar a servir tráfego não encriptado.

Um proxy à frente termina o TLS e reencaminha para um listener confinado. Deixe ambas as chaves por definir e o listener serve texto simples, o que só é aceite em loopback ou num socket Unix — pelo que nada que não esteja já nesse anfitrião lhe consegue chegar. É essa a forma que usa um proxy inverso, um sidecar ou uma service mesh, e é aquela em que o certificado fica à frente deste processo e não nele.

Um listener em texto simples em qualquer outro endereço é recusado antes de qualquer associação, e a recusa nomeia ambas as chaves TLS. Não há nenhuma definição que levante isto nem nenhum endereço que seja exceção: um listener que aceita ligações da rede sem certificado próprio nunca é seguro, pelo que o processo se recusa a arrancar em vez de arrancar nessa forma.

As formas de endereço

--listen e mcp.listen aceitam uma de duas formas:

  • host:port — um endereço TCP, como 127.0.0.1:7777 ou 0.0.0.0:8443. Loopback significa 127.0.0.1, ::1 ou localhost quando todos os endereços em que esse nome se resolve são endereços de loopback. Tudo o resto é um endereço de rede e precisa de um certificado: um anfitrião vazio, que corresponde a todas as interfaces da máquina; um endereço de interface específico; e qualquer outro nome, mesmo um que neste momento se resolva num endereço de loopback, porque o local onde um listener se pode associar não deve depender de uma resolução que pode mudar sem aviso.
  • unix: seguido de um caminho no sistema de ficheiros — um socket de domínio Unix, como unix:/run/aggrega/mcp.sock. Um socket só é acessível a partir do anfitrião em que se encontra, pelo que não precisa de certificado.

Um caminho de socket é tomado exatamente como está escrito, incluindo um relativo. Não é deliberadamente resolvido em relação ao ficheiro de configuração que o declarou, porque o mesmo endereço também chega a partir de --listen, que não tem ficheiro declarante — consulte para onde aponta um caminho relativo.

O que o listener aceita

Um endpoint, /mcp, que aceita POST. Cada mensagem JSON-RPC é um pedido próprio e não é mantida nenhuma sessão de qualquer tipo: nada do que um cliente envia primeiro decide como um pedido posterior é respondido, nenhum identificador de sessão é alguma vez emitido, e um cabeçalho de sessão ou de retoma de fluxo que um cliente envie é ignorado. Qualquer outro método nesse endpoint é respondido com 405 e Allow: POST, e qualquer outro caminho com 404 — ambos decididos antes da verificação da credencial, para que uma sondagem não aprenda nada com um desafio num caminho ou num método que de qualquer forma não serviria nada.

Um pedido é respondido com um objeto JSON e um código de estado — ou, quando a chamada reportou progresso a caminho desse objeto, com um fluxo de eventos que termina nele, como estabelece Ser informado do andamento de uma chamada longa. Uma notificação — uma mensagem sem id — é respondida com 202 e um corpo vazio. Uma mensagem que não seja nenhuma das duas, incluindo uma resposta JSON-RPC, é respondida com 400, porque um cliente envia a este servidor pedidos e notificações e nada mais.

Ambas as revisões do protocolo são servidas aqui exatamente como através da entrada e saída padrão. Um pedido 2026-07-28 reflete o seu corpo em cabeçalhos de transporte para que um intermediário o possa encaminhar sem analisar o corpo: MCP-Protocol-Version contém a revisão que o corpo indica, Mcp-Method o método que nomeia e Mcp-Name o alvo, para os métodos que endereçam um pelo nome. Um cabeçalho que discorde do corpo é respondido com 400. Um cliente 2025-06-18 começa com um handshake initialize, que é respondido sem estado; pode conter o cabeçalho de versão a nomear essa revisão ou omiti-lo. Um pedido que nomeie uma revisão que o servidor não fala é respondido com 400, listando as duas que fala, e um que nomeie um método que não serve é respondido com 404.

mcp.allowed_origins só é consultado quando um pedido contém um cabeçalho Origin, o que na prática significa que foi um browser a enviá-lo: um pedido que nomeie uma origem que a lista não contém é respondido com 403, e um que não contenha esse cabeçalho é servido. Um cliente que não seja um browser não envia esse cabeçalho e não precisa de entrada. Um baseado em browser precisa sempre de uma entrada: a lista está vazia até que um operador a escreva, pelo que até lá nenhuma origem é aceite e todos os pedidos de browser são respondidos com 403 — incluindo um vindo de uma página servida no próprio endereço do endpoint. A entrada é comparada com o cabeçalho de forma exata, pelo que é escrita como um browser envia uma origem — um esquema em minúsculas, ://, um anfitrião em minúsculas e, quando não é a predefinição do esquema, : e a porta, como https://app.example.com — e uma entrada com um caminho, uma / final, sem esquema ou com uma letra maiúscula é recusada quando a configuração é carregada, nomeando a entrada, porque nunca poderia corresponder.

mcp.limits limita o tráfego que é aceite. Um corpo que ultrapasse max_body_bytes é respondido com 413 e não é lido para além do limite. Um pedido que chegue enquanto max_concurrent_requests já estão em curso é respondido com 503 em vez de ficar em fila atrás de trabalho que não consegue ver. Um chamador que envie mais de requests_per_minute num minuto é respondido com 429, contabilizado apenas para esse chamador, pelo que um chamador que envie muito não custa nada a outro. A predefinição de cada limite está indicada ao lado da sua chave em a referência de configuração, e nenhum deles tem um valor que o desative.

Um processo, um espaço de trabalho

O espaço de trabalho que um processo servidor serve é fixado quando arranca. --workspace-root indica-o; a variável AGGREGA_WORKSPACE_ROOT fornece-o quando a flag está ausente. A pasta indicada é a própria raiz do espaço de trabalho, sem que se pesquise nada acima dela, e uma pasta que não existe é recusada, indicando qual das duas a forneceu e citando o valor tal como foi dado — por um listener antes de se associar ao endereço, e por um servidor em entrada e saída padrão na resposta a cada chamada que atue nesse espaço de trabalho, como Em que espaço de trabalho é respondida uma chamada expõe — para que um arranque composto por um cliente, e não escrito à mão, continue a dizer o que lhe foi entregue. Sem nenhuma das duas, um servidor em entrada e saída padrão resolve o espaço de trabalho a partir do diretório em que foi iniciado — onde nada ancora um espaço de trabalho, cada resposta sobre o espaço de trabalho indica a pasta que usou, e o arranque do pacote de ambiente de trabalho com a definição Workspace folder vazia recusa, em vez disso, uma chamada que não indique um espaço de trabalho próprio, como Em que espaço de trabalho é respondida uma chamada expõe — e um listener é recusado antes de se associar ao endereço, a menos que aí se resolva um espaço de trabalho — um processo alcançado por HTTP responde a chamadores que não veem a máquina, por isso serve um espaço de trabalho escolhido por um operador e não o diretório em que, por acaso, foi iniciado. Para servir vários projetos, execute-se um processo por raiz de projeto.

Uma chamada que chega por HTTP não pode indicar um espaço de trabalho próprio. workspace_root e catalog_dirs são recusados, indicando o argumento enviado, em vez de serem descartados em silêncio: um argumento ignorado em silêncio parece ao remetente exatamente igual a um que foi respeitado. Os diretórios de catálogo pesquisados junto ao espaço de trabalho servido são a definição workspace.catalog_dirs desse próprio espaço de trabalho — ou, para uma Release a que este atribui diretórios próprios em workspace.releases, os dessa Release — que o operador escreve. Em entrada e saída padrão ambos os argumentos são respeitados, porque o cliente que lançou o servidor está a correr na própria máquina do chamador. Aí, uma entrada de catalog_dirs é absoluta, ou relativa à raiz do espaço de trabalho a partir da qual se lê um release relativo — a raiz que o próprio workspace_root da chamada, o arranque ou o diretório em que o servidor foi iniciado fixaram primeiro, e aquela a partir da qual continua a ser lido quando uma Release indicada de forma absoluta leva a chamada para o espaço de trabalho dessa Release — e não ao diretório em que o servidor corre, quando este é outro.

Um caminho que uma chamada indica também fica dentro desse espaço de trabalho. Por HTTP, um argumento de caminho é resolvido em relação à raiz do espaço de trabalho e recusado se sair dela — um caminho relativo que sobe para fora do espaço de trabalho, um caminho absoluto que indica outro sítio e um caminho relativo que sai do espaço de trabalho através de uma ligação para um ficheiro ou diretório que lá está regressam, cada um, como uma falha que indica o argumento, sem indicar a raiz do espaço de trabalho nem o sítio a que o caminho teria chegado; um caminho relativo é citado tal como foi enviado. Cada argumento de caminho é avaliado pelo sítio a que conduz, segundo a definição de «dentro» que O limite do espaço de trabalho estabelece, quer a ferramenta o leia quer o escreva — o diretório em que gen-catalog escreve a sua saída, o documento que edit-document reescreve e a entidade junto à qual pin escreve o seu lock tanto quanto um documento que uma ferramenta lê — pelo que um caminho ainda não criado sob uma ligação que sai do espaço de trabalho é recusado tal como essa ligação, sem nada lido nem escrito. Um release que indique uma Release que a configuração do espaço de trabalho servido indica, como build.authoring_release ou como chave de workspace.releases, é alcançado através dessa configuração e aceite através de uma ligação onde quer que o seu ficheiro esteja; nenhum outro argumento tem essa exceção. Quando o caminho pretendido está dentro desse espaço de trabalho mas foi escrito de forma absoluta, a recusa indica a forma relativa à raiz a enviar, para que um chamador que adivinhou a forma errada saiba qual é a certa e não apenas que errou. Isto vale para os caminhos que uma chamada indica como seu objeto — o documento a validar, a Release a compilar, o diretório em que uma geração escreve a sua saída — e tanto para os que uma ferramenta escreve como para os que lê: um chamador que alcança um servidor pela rede está a pedir a uma máquina que não vê que leia e escreva ficheiros, e o espaço de trabalho escolhido pelo operador é onde essa leitura e escrita ficam contidas. Em entrada e saída padrão, os argumentos de caminho de cada ferramenta mantêm o contrato descrito para essa ferramenta abaixo, em que um caminho pode ser absoluto e apontar para fora do espaço de trabalho — quem chama é dono da máquina em que o servidor corre, pelo que confiná-lo a um diretório que ele próprio escolheu não traria nada. As duas ferramentas cuja própria operação responde apenas sobre um documento que o espaço de trabalho contém, insertion-point e edit-document, mantêm essa regra em ambos os transportes e recusam um documento fora do espaço de trabalho, quer esteja escrito assim quer seja alcançado através de uma ligação que sai dele. O que se respeita em entrada e saída padrão é o caminho que uma chamada indica e nada além dele. O que a operação depois lê e escreve por conta própria é contido em ambos os transportes exatamente como quando o mesmo comando é escrito num terminal: uma travessia ou uma pesquisa não lê através de uma ligação que sai do espaço de trabalho, um ficheiro que uma Release no espaço de trabalho ou o seu Manifest indicam por um caminho não é lido de fora do espaço de trabalho — e um que uma Release indicada pela chamada fora do espaço de trabalho indica não é lido de fora do diretório que contém essa Release — e um ficheiro escrito sob um diretório — o espaço de trabalho, ou um que a chamada indicou — fica dentro desse diretório. O limite do espaço de trabalho coloca os dois transportes lado a lado com a linha de comandos e o editor, e indica o que permanece em aberto em entrada e saída padrão: um documento num espaço de trabalho clonado pode levar um assistente a indicar um caminho fora do espaço de trabalho, e esse caminho é respeitado tal como foi indicado.

O que uma resposta diz sobre o sistema de ficheiros do servidor

Por HTTP, uma resposta indica um sítio no sistema de ficheiros do servidor de forma relativa à raiz do espaço de trabalho, ou retém-no. Um cliente que lançou o servidor corre onde o servidor corre, por isso, em entrada e saída padrão, cada resposta indica cada sítio tal como a operação o guarda — absoluto, quando é assim que é guardado — e cada um é um sítio que esse chamador já possui. Um chamador que alcança um listener não escolheu nenhum desses sítios e não os pode abrir, e um servidor que os tenha publicado não os pode «despublicar». Assim, por HTTP, uma resposta diz a esse chamador uma de duas coisas sobre um sítio:

  • Um sítio dentro do espaço de trabalho é indicado de forma relativa à raiz do espaço de trabalho — a mesma forma que toma um caminho enviado, pelo que um nome lido numa resposta pode ser reenviado sem alterações na chamada seguinte. Uma Release na raiz é release.yaml, e o seu lockfile é release.lock.
  • Um sítio fora do espaço de trabalho é retido, tal como a própria raiz do espaço de trabalho. O campo não tem valor — é null ou omitido, e em attachment-container, cuja resposta mantém a forma em que todas as superfícies a reportam, file fica vazio — e uma marca junto a ele, com o nome do campo seguido de _withheld, diz que foi retido e não que ficou por definir: workspace_root_withheld junto a workspace_root, file_withheld junto a file. Uma marca só está presente onde algo foi retido. A raiz é retida porque um listener serve exatamente um espaço de trabalho, pelo que o sítio onde esse espaço de trabalho está não indica nada de que se precise para nomear o que está dentro dele.

Se um sítio está dentro é avaliado pela forma como está escrito, não pelo ficheiro a que chega. Um caminho escrito através do destino de uma ligação simbólica, e não através da raiz sobre a qual o servidor foi iniciado, e um caminho que sai da raiz e volta a entrar, são ambos lidos como fora do espaço de trabalho e retidos. A avaliação erra no sentido de dizer menos, nunca no de indicar um sítio fora do espaço de trabalho.

Por HTTP, o texto legível de uma resposta segue a mesma regra. Onde o texto, uma linha de diagnóstico ou a mensagem de uma falha indicam um sítio que o espaço de trabalho contém — a sua raiz ou algo sob ela, um ficheiro de configuração de onde a sua configuração foi lida, um diretório de onde o seu catálogo é lido — esse sítio é escrito de forma relativa à raiz, ou surge como (location withheld) quando fica fora do espaço de trabalho ou é a raiz. O texto que uma resposta compõe sobre o seu próprio espaço de trabalho chama-lhe o espaço de trabalho que este servidor serve. Um sítio fora de todos estes que uma operação escreva numa mensagem não é reconhecido como tal e chega tal como foi escrito.

As respostas abrangidas, por HTTP:

  • list-entities, list-releases, cache-status, registry-list, search, attach-candidates, connection-candidates, insertion-point, attachment-container, connection-at-position e edit-document retêm workspace_root. Os caminhos que já dão de forma relativa à raiz — o ficheiro de origem de uma entidade, o caminho de uma Release e o seu lockfile em lockfiles, o documento a que respeita um ponto de inserção ou uma edição, os ficheiros que uma edição escreveu — leem-se da mesma forma em ambos os transportes.
  • cache-status retém também o que indica um plugin que o servidor carregou de um ficheiro no seu anfitrião. Uma tal identidade é null na sua posição em provenance[].identities, todas as outras identidades mantêm a sua posição e a entrada é marcada com identities_withheld. A note de um módulo compilado é uma frase que indica as identidades para as quais o módulo foi compilado, pelo que, quando alguma delas indica um tal ficheiro, a note é omitida por inteiro e marcada com note_withheld; o digest do módulo continua presente. Uma identidade que indique uma referência de registo ou uma entidade Plugin é devolvida por inteiro, tal como uma note que indique apenas essas. O label de um artefacto de origem é o seu lugar na cache, escrito a partir do anfitrião e do caminho do URL de onde foi resolvido, pelo que, para um repositório lido do próprio sistema de ficheiros do servidor — através de um URL file:// ou de um caminho — o label é omitido e marcado com label_withheld, o seu size e o seu digest continuam presentes, e um label que indique um anfitrião de rede é devolvido por inteiro. O texto da listagem mostra (location withheld) onde teria indicado um.
  • validate indica target, e release no caso de uma Release, de forma relativa à raiz; para o catálogo inteiro, target é a raiz e é retido. Um sítio em diagnostics ou notices segue a regra do texto.
  • build indica release de forma relativa à raiz, e uma build que resolveu primeiro as suas dependências inclui dependency_resolution tal como pull o devolve. Uma build a que se enviou write indica o diretório em que escreveu como output_dir, que mostra dist — relativo à raiz — e cada caminho em files é relativo a esse diretório. Uma refusal, e cada entrada dos seus findings, indica o seu file de forma relativa à raiz, ou retém-no quando o documento fica fora do espaço de trabalho. advisories, deprecations, declined_external_inputs e cada message da refusal seguem a regra do texto.
  • pull indica release e lockfile de forma relativa à raiz. diagnostics e incomplete_external_inputs seguem a regra do texto. A source de cada entrada de resolved é devolvida por inteiro em ambos os transportes: indica o que a execução fez, nunca um sítio no anfitrião.
  • describe indica o release de uma Release de forma relativa à raiz, e o file de uma entidade de forma relativa à raiz quando o seu documento fica dentro do espaço de trabalho; uma entidade lida de um diretório de catálogo fora do espaço de trabalho tem o seu file retido. mapping_diagnostics e deprecations seguem a regra do texto.
  • lint indica o location.file de cada constatação de forma relativa à raiz, ou retém-no quando a entidade fica fora do espaço de trabalho. A message e a suggest de uma constatação seguem a regra do texto.
  • pin indica entity e lock de forma relativa à raiz, tal como o pin que uma publicação inclui.
  • gen-catalog indica cada ficheiro listado em output de forma relativa à raiz.
  • import retém workspace_root, e output_dir quando os rascunhos foram para essa raiz; um diretório indicado em output_dir é dado pelo seu nome relativo à raiz. Cada caminho de rascunho em written e drafts é relativo a output_dir, pelo que o destino dos rascunhos consta da resposta em qualquer dos casos. A message de um diagnóstico, e o params_summary, a rationale e o swap_hint de uma decisão, são prosa composta pelo importador e seguem a regra do texto.
  • config-show e plugin-list retêm mais do que a raiz, porque a maior parte do que reportam é configuração que indica sítios, como O que um listener não diz sobre o seu anfitrião expõe.
  • scaffold, ao escrever um exemplo, indica dir tal como foi enviado, de forma relativa à raiz, e cada caminho em files de forma relativa a esse diretório; a criação de rascunhos e a listagem não indicam nenhum sítio.
  • As ferramentas de publicação, sign-artifacts, deprecate-artifact, get-schema, explain-error e describe-capabilities não indicam por si nenhum sítio no anfitrião. A mensagem de falha de qualquer uma delas segue a regra do texto: a recusa que um espaço de trabalho offline levanta indica o seu .aggrega-config.yaml de forma relativa à raiz.
  • Um argumento de caminho recusado por sair do espaço de trabalho é recusado sem indicar a raiz nem o sítio a que teria chegado, como acima.

Como termina uma chamada

Fechar a ligação cancela a chamada que ela transportava. É esse o sinal de cancelamento deste transporte: o servidor trata a desconexão de um chamador como cancelamento desse pedido, termina o trabalho que estava a fazer e não escreve mais nada para ele. Aqui não é necessária nem esperada nenhuma mensagem de cancelamento — ao contrário da entrada e saída padrão, onde não há um fluxo por pedido para fechar e um cliente termina uma chamada indicando o seu id. Uma mensagem de cancelamento que chegue por HTTP é aceite e não termina nada.

Parar o processo esvazia o listener. Uma interrupção, ou um pedido de terminação de um supervisor ou de um runtime de contentores, faz o listener deixar de aceitar e deixa terminar, dentro de um orçamento limitado, uma chamada que já está a ser respondida, para que um chamador que pediu algo antes da paragem ainda receba a sua resposta. Uma chamada que não tenha terminado dentro desse orçamento perde a ligação. Um segundo pedido de paragem termina o processo de imediato.

Vivacidade e prontidão, num endereço próprio

mcp.health.listen é onde um supervisor pergunta se este processo está ativo e se consegue responder a uma chamada. Dê-se-lhe um endereço em qualquer das formas acima e um segundo listener responde aí a GET /healthz e GET /readyz. Omita-se — que é a predefinição — e não é iniciado nenhum segundo listener nem nenhuma das verificações é respondida em lado nenhum.

As duas respostas dizem coisas diferentes, e essa diferença é a razão de haver duas. /healthz responde 200 a partir do momento em que o processo está a correr, que é tudo o que a vivacidade afirma: está ativo, e um supervisor que não obtenha qualquer resposta deve reiniciá-lo. /readyz responde 503 até que o espaço de trabalho que este processo serve esteja resolvido e o endpoint associado ao endereço, e 200 a partir daí — para que um balanceador retenha o tráfego até o processo conseguir de facto responder a uma chamada, em vez de enviar o primeiro pedido para um que ainda está a arrancar. Cada resposta é um código de estado com corpo vazio; não é pedida nenhuma credencial e nada do que o chamador enviou é lido.

O endpoint nunca responde a esses dois caminhos. GET /healthz e GET /readyz no endereço que mcp.listen indica recebem 404, exatamente como qualquer outro caminho que esse endpoint não serve, com ou sem token. Responder ali a uma sonda daria a qualquer coisa que alcance o endpoint uma leitura gratuita de se o processo está ativo, juntamente com uma forma gratuita de o pôr a trabalhar — num listener que, de resto, recusa todos os pedidos sem credencial.

O sítio onde fica o endereço de saúde é à escolha, e não é confinado como mcp.listen. Nenhum endereço é recusado para ele. Aponte-se para loopback ou para um socket Unix, que é para o que serve: um supervisor, um balanceador ou um runtime de contentores a correr ao lado deste processo no mesmo anfitrião. Tudo o que consiga alcançar o endereço escolhido pode ler essas duas respostas, pelo que um endereço alcançável a partir da rede aberta publica-as para a rede aberta.

Nada é servido sem uma credencial

Cada pedido ao endpoint traz uma credencial, e qual depende de um proxy à frente já a ter verificado. Por predefinição é um bearer token que este servidor verifica ele próprio, descrito no resto desta secção. Defina-se mcp.authorization.trusted_proxy e passa a ser um cabeçalho que esse proxy define, descrito em Ler o chamador a partir de um proxy à frente — onde não se lê token nenhum. Nenhuma das formas serve um pedido que não apresente nada.

Por predefinição, o servidor verifica ele próprio um bearer token. Lê o token do cabeçalho Authorization e só o aceita quando a assinatura é verificada com uma chave que o servidor de autorização publica, o token indica mcp.authorization.issuer como emissor, indica o próprio mcp.authorization.resource desta implementação entre os seus destinatários, está dentro da sua janela de validade e diz quem o apresentou. Um token que falhe qualquer destas verificações recebe 401, com error="invalid_token" acrescentado ao mesmo desafio que recebe um chamador que não traz nada — e a resposta é idêntica qualquer que seja a verificação que o rejeitou, para que um chamador saiba que precisa de outro token e não qual parte do que enviou estava errada. Só são aceites algoritmos de assinatura assimétricos: um token não assinado, e um que indique um algoritmo simétrico, são recusados antes de se ler o que quer que seja dele.

Um token pode dizer que tipo de token é, e são aceites quatro formas. Um JWT pode trazer um cabeçalho typ que indica o seu próprio tipo. Este servidor aceita at+jwt e application/at+jwt, as duas grafias registadas para um token de acesso; JWT, que diz apenas que o token é um JWT; e um token que não declare tipo nenhum. Tudo o resto recebe 401, exatamente como qualquer outro token recusado. O conjunto é fixo e nenhuma definição o alarga ou restringe, porque a forma que aí aparece é decidida pelo servidor de autorização que emitiu o token e não pela implementação que o recebe. Aceitar JWT significa, de facto, que o tipo declarado já não basta para distinguir um token de acesso de um token de identidade — é a verificação de destinatário que os distingue, e é por isso que essa verificação é a que sustenta tudo: o destinatário de um token de identidade é o cliente a que foi emitido, nunca o próprio mcp.authorization.resource desta implementação, pelo que um token emitido para algo que não esta implementação é recusado, chame-se a si mesmo o que se chamar.

Que servidores de autorização isto admite. O Microsoft Entra ID emite tokens de acesso com o tipo JWT. O Keycloak emite at+jwt, e JWT quando o seu modo de compatibilidade OpenID Connect está ativo. O Auth0 emite JWT no seu próprio perfil de token e at+jwt no seu perfil RFC 9068. Um token de qualquer destes satisfaz esta verificação, seja qual for a das duas formas que traga. O Okta não é suportado: os seus tokens de acesso declaram um tipo próprio que não é nenhum dos quatro acima, pelo que este servidor os recusa.

Um token recusado deixa o motivo no próprio fluxo de erros do servidor. Ao chamador diz-se apenas que o que apresentou não foi aceite; o processo servidor escreve uma linha que indica a verificação que rejeitou o token — o destinatário, o emissor, a janela de validade, a assinatura, o identificador de chave, o tipo declarado e cada uma das restantes. É essa linha que torna diagnosticável, por quem a executa e não só por quem a chama, uma implementação que recusa todos os pedidos. Não contém nenhuma parte do token. Um pedido que não apresente credencial nenhuma não escreve linha, porque ser desafiado é a forma de um cliente descobrir onde obter um token, pelo que é a primeira coisa que qualquer cliente bem-comportado faz.

Um token pertence ao cabeçalho e a mais lado nenhum. Um enviado como parâmetro de consulta access_token recebe 400 e nunca é lido, porque um endereço fica registado em todos os logs de proxy, históricos de navegador e cabeçalhos referrer por onde o pedido passa, pelo que um token que chegou assim já foi exposto. O servidor nunca escreve um token num log, nunca o envia para lado nenhum e nunca obtém nem troca um em nome de um chamador: lê o que foi apresentado, decide e não guarda nada disso. O sujeito que o token indica é registado e não é comparado com nada.

As chaves de verificação vêm do servidor de autorização, ou de um ficheiro indicado. Com mcp.authorization.jwks_file por definir, o servidor lê os metadados do servidor de autorização no seu endereço well-known, segue o jwks_uri aí publicado e guarda as chaves que encontra; um token assinado com um identificador de chave que essas chaves não incluem provoca uma nova leitura, e não mais de uma num intervalo curto, para que um chamador que envie identificadores de chave inventados não consiga provocar um pedido de saída por cada pedido. Lê-las do servidor de autorização exige um endereço de chaves https, ou um http simples nesta máquina: um jwks_uri em http simples noutro anfitrião nunca é consultado, e um redirecionamento que enviaria qualquer das leituras para http simples noutro anfitrião não é seguido, porque quem estiver num caminho desprotegido até às chaves poderia responder com chaves suas. Um token que precise dessas chaves recebe então 503, exatamente como no caso de chaves que não podem ser lidas, e a linha que o servidor escreve para esse pedido diz que a leitura foi recusada por ser http simples, e não que o servidor de autorização não pôde ser alcançado — a correção é do lado do servidor de autorização, que tem de publicar os seus metadados e chaves por https. Com jwks_file definido, as chaves são lidas desse ficheiro e o servidor de autorização nunca é contactado — que é o que precisa um espaço de trabalho que declare offline: true, e um tal espaço de trabalho é recusado antes de o seu listener se associar ao endereço, a menos que o ficheiro seja indicado. Quando as chaves não podem de todo ser lidas, os pedidos recebem 503 sem desafio: nada do que um chamador apresentou foi considerado insuficiente, por isso ir buscar outro token não ajudaria.

A única resposta dada sem pedir credencial é o documento de metadados do recurso protegido. Um cliente tem de o ler antes de poder ter um token, pelo que exigir um ali fecharia a única porta de entrada. É servido em /.well-known/oauth-protected-resource e — quando o endereço que mcp.authorization.resource indica tem um caminho próprio — também nesse caminho well-known com esse caminho acrescentado. São esses os dois sítios onde um cliente procura, e a forma acrescentada é o endereço que o desafio indica. O documento traz esse endereço como o nome do recurso desta implementação, mcp.authorization.issuer como o servidor de autorização junto do qual obter um token, header como a única forma de apresentar um token e os três nomes de âmbito abaixo.

O emissor é um endereço https, a menos que o servidor de autorização corra nesta máquina. O http simples é aceite para um emissor em localhost, 127.0.0.1 ou ::1, que é a forma de um teste local com um servidor de autorização local; um emissor em http simples em qualquer outro anfitrião é recusado antes de o listener se associar ao endereço, e a recusa indica mcp.authorization.issuer e pede um endereço https. Isto vale em todos os modos — com as chaves lidas do emissor, com mcp.authorization.jwks_file e com um proxy à frente — porque todos os modos publicam o emissor neste documento: um cliente que o siga executa o seu fluxo de autorização contra esse endereço, pelo que, em http simples, o código de autorização e o token que obtém atravessariam a rede sem proteção, quer este servidor alguma vez leia ou não uma chave dali. Quando lê dali as suas chaves, quem estiver nesse caminho poderia também responder com chaves suas, e todos os tokens assinados com elas seriam admitidos.

Os nomes de âmbito que esta implementação publica são aggrega:read, aggrega:workspace-write e aggrega:registry-write. São os nomes a registar no servidor de autorização e os nomes que um cliente lhe pede, e o desafio que um chamador recusado recebe indica aggrega:read como o primeiro a obter. O que cada um admite — e o segundo limite, o que esta implementação impõe a si própria — está em O que um chamador pode alcançar abaixo.

Ler o chamador a partir de um proxy à frente

Quando um proxy à frente já valida tokens, mcp.authorization.trusted_proxy diz a este servidor que leia o chamador a partir dele em vez de verificar um token uma segunda vez. Indique-se principal_header, o cabeçalho que esse proxy define para dizer quem é o chamador, e opcionalmente scopes_header, um segundo cabeçalho que traz os âmbitos desse chamador separados por espaços. Cada um é um nome de cabeçalho HTTP como X-Forwarded-User, sem espaços nem dois pontos; um nome com qualquer outra forma é recusado quando a configuração é carregada, indicando a chave, tal como um principal_header vazio — para deixar este modo desativado, omita-se o bloco. Esses dois cabeçalhos são os únicos lidos: nenhum cabeçalho de endereço reencaminhado nem qualquer outro cabeçalho participa. Um pedido que chegue sem o cabeçalho do principal recebe 401, e neste modo não se lê token nenhum — um pedido que traga um token que este servidor teria recusado é servido quando o cabeçalho do principal está presente, e um que traga um token que este servidor teria aceitado continua a ser recusado quando esse cabeçalho está ausente.

Esse modo só é aceite em loopback ou num socket Unix, e o processo é recusado antes de se associar a qualquer outro endereço. Um cabeçalho é fiável exatamente quando nada além do proxy o pode definir. Num endereço alcançável pela rede, qualquer coisa o pode definir — pelo que um listener neste modo num tal endereço deixaria cada chamador identificar-se como bem entendesse. A recusa indica ambas as definições em conflito, para que se possa levantá-la mudando o endereço ou removendo o bloco.

O que o proxy afirma é o que este servidor acredita, e é esse o acordo. Neste modo, este servidor não verifica assinatura nenhuma e não compara o chamador afirmado com nada, exatamente como não compara com nada o sujeito de um token. Se o proxy validou o que reencaminhou, e se algo consegue alcançar esse listener sem passar pelo proxy, cabe à implementação acertar; o confinamento acima é o que torna possível acertar, não uma garantia de que se acertou.

Definir mcp.authorization.trusted_proxy não remove os restantes requisitos. issuer e resource continuam a ser necessários, porque o documento de metadados continua a ser publicado e o desafio continua a indicá-lo — um cliente atrás do proxy continua a ter de saber onde obter o token que o proxy irá verificar. Pela mesma razão, o emissor continua a ser um endereço https, a menos que corra nesta máquina: esse cliente obtém o seu token do emissor, pelo que um emissor em http simples noutro anfitrião é recusado antes de o listener se associar ao endereço neste modo exatamente como em qualquer outro, embora este servidor não leia nada dele.

O que um chamador pode alcançar

Dois limites decidem o que um chamador alcança por HTTP, e são definidos por pessoas diferentes. A própria credencial do chamador é o primeiro; aquilo que este servidor oferece de todo é o segundo. Ambos são lidos antes de qualquer execução, a partir de uma declaração que cada operação faz sobre si própria, e chegam a um cliente em sítios diferentes: a lista de ferramentas mostra o que este servidor oferece e anuncia, e a resposta que cada chamada recebe mostra o que a credencial admite.

Cada operação declara até onde chegam os seus próprios efeitos, e há quatro tipos, do mais restrito ao mais amplo:

  • Não alcança nada — lê uma definição, inspeciona o que uma Release fixa, renderiza artefactos em memória e devolve-os. Não deixa nada para trás: nada é escrito, e a resposta é tudo o que produz.
  • Alcança o espaço de trabalho — escreve dentro do espaço de trabalho que este processo serve: o lockfile de uma Release, a cache de artefactos, entidades geradas, um documento editado.
  • Alcança um registo — publica, assina ou anexa um marcador de retirada a algo já publicado. O que altera é o que todos os consumidores desse registo resolvem, e nada disso pode ser recuperado de quem já o obteve.
  • Alcança a máquina — altera o que todos os espaços de trabalho no anfitrião partilham, entre eles o armazenamento de módulos compilados, o ficheiro de configuração comum a todos e o armazenamento de credenciais. Uma cache que um único projeto mantém no seu próprio diretório de cache não é deste tipo, e cache-status indica qual destes tipos tem cada cache que lista.

O tipo é uma propriedade da operação e não da ferramenta que a oferece, e abrange o que a operação deixa para trás — não o sítio onde uma superfície coloca a resposta que devolve. Renderizar uma Release produz artefactos como resposta, por isso não alcança nada; uma linha de comandos que depois guarda esses artefactos num diretório indicado está a entregar essa resposta, não a ir mais longe. Lido ao contrário, cada operação que responde com conteúdo assumiria o tipo da superfície que, por acaso, o guardasse, e o tipo deixaria de todo de ser uma propriedade da operação. Pela mesma razão, describe a ler uma entidade pela sua referência de registo não alcança nada: contacta esse registo para obter a sua resposta e não deixa nada para trás, nem no registo nem nesta máquina, e os registos que pode contactar estão definidos em Que credenciais uma chamada gasta. Uma chamada pode ainda assim ir além do tipo da sua operação, quando a própria chamada pede uma escrita: uma build a que se enviou write guarda os seus artefactos no espaço de trabalho que este servidor serve, pelo que essa chamada alcança o espaço de trabalho, tal como uma build que resolve primeiro as suas dependências.

Um âmbito admite um tipo, e cada âmbito de escrita implica o âmbito de leitura. aggrega:read admite uma operação que não alcança nada. aggrega:workspace-write admite uma que alcança o espaço de trabalho, e implica o âmbito de leitura. aggrega:registry-write admite uma que alcança um registo, e também implica o âmbito de leitura. Assim, um cliente pede ao seu servidor de autorização o âmbito de escrita de que precisa e não tem de pedir também o de leitura.

Nenhum âmbito admite o tipo máquina, e nenhuma definição acrescenta um. As operações desse tipo são oferecidas apenas pelas ferramentas que executam um comando aggrega num processo separado, e um servidor alcançado por HTTP não oferece nenhuma delas, pela razão dada em Alcançar o servidor por HTTPS acima. Executem-se num terminal no anfitrião.

A lista de ferramentas mostra todas as ferramentas que este servidor oferece e anuncia, quaisquer que sejam os âmbitos da credencial que chama, e é a credencial que decide quais delas uma chamada pode executar. describe-capabilities indexa e define esse mesmo conjunto. Uma chamada que a credencial não admite recebe 403 com error="insufficient_scope" no desafio, indicando o único âmbito que a admitiria, e nada do que a chamada pediu foi executado. Essa recusa é a que o step-up do protocolo responde: um cliente que implemente step-up pede ao utilizador que volte a iniciar sessão para o âmbito que o desafio indica. A lista não muda com a credencial, pelo que um cliente que voltou a iniciar sessão já tem a credencial certa. Uma credencial sem nenhum dos três âmbitos recebe a mesma lista de ferramentas e não pode chamar nenhuma delas, incluindo describe-capabilities.

Uma build é o caso que vale a pena conhecer. Não altera nada por si e por isso precisa apenas de aggrega:read, mas uma build que escreve precisa de aggrega:workspace-write: uma a que se enviou write guarda os seus artefactos em dist/ na raiz do espaço de trabalho, e uma que resolve primeiro as suas dependências escreve o lockfile — quer tenha sido a chamada a pedi-lo com auto_pull, quer a própria definição auto_pull do espaço de trabalho. A ferramenta é listada a um chamador com âmbito de leitura como qualquer ferramenta, e as builds que ficam em memória estão-lhe genuinamente disponíveis; o que é recusado, indicando aggrega:workspace-write, é a chamada que escreve.

Um cliente que não faz step-up pode ainda assim receber os âmbitos de escrita, e isso resolve-se no servidor de autorização. Quem gere o servidor de autorização torna os âmbitos de escrita âmbitos predefinidos para esse cliente — âmbitos que coloca em todos os tokens que emite para esse cliente, quer este os peça quer não — pelo que o token que o seu primeiro início de sessão obtém já os traz. Um cliente que se regista de novo no servidor de autorização sempre que se liga é aí um cliente novo de cada vez, e uma definição feita num registo anterior não transita; para um tal cliente, a definição que produz efeito são os âmbitos predefinidos que o servidor de autorização dá a cada cliente que regista. O custo é que cada início de sessão através desse cliente passa a ter alcance de escrita, quer o trabalho em curso precise dele quer não — e, quando as predefinições são as dadas no registo, todos os clientes registados dessa forma têm também esse alcance. Torne-se predefinido apenas o âmbito de escrita de que esse trabalho precisa: aggrega:workspace-write e aggrega:registry-write admitem tipos diferentes, e nenhum implica o outro.

mcp.deny_reach é onde quem gere este servidor lhe retira um tipo, e é uma das duas definições que encurtam a lista de ferramentas. Listem-se os tipos — none, workspace, registry, machine — que este servidor não oferece, e todas as ferramentas que alcançam um deles ficam ausentes da lista de ferramentas de todos os chamadores e de describe-capabilities, diga o token desse chamador o que disser, e são recusadas se chamadas mesmo assim, com um erro que indica esta definição. É o limite do próprio servidor e não o do chamador, pelo que nenhuma credencial o levanta e a recusa não traz desafio: um servidor destinado a servir leituras e nada mais lista aqui workspace, registry e machine, e depois não consegue publicar nem para um chamador cujo token traga os três âmbitos. Omita-se, que é a predefinição, e este servidor não retira tipo nenhum, pelo que os tipos que uma chamada alcança são decididos pelos próprios âmbitos do chamador. Indicar machine é aceite e não altera nada, já que nada desse tipo é oferecido aqui à partida. Um valor que não seja um dos quatro é recusado quando a configuração é carregada, em vez de ser ignorado — um operador que escreve mal um tipo pediu um limite, e ser servido sem ele em silêncio é a resposta errada.

mcp.announce_tools é a outra definição que encurta a lista de ferramentas, e as duas não são o mesmo limite. deny_reach retira uma capacidade: uma operação de um tipo aí indicado não é oferecida aqui de todo, a ninguém. announce_tools retira apenas um anúncio: as ferramentas que deixa de fora são capacidades que este servidor continua a ter, e aquilo a que responde é o limite próprio de um cliente quanto ao número de ferramentas que regista. Quando ambas estão definidas, prevalece a retirada, pelo que uma ferramenta de um tipo retirado continua ausente, indique-a announce_tools como indicar, e a recusa com que um chamador se depara indica a retirada. Nada do que encurta a lista lê os âmbitos do chamador: um âmbito que falte ao chamador recusa uma chamada e nunca remove uma ferramenta da lista. Restringir o que o servidor anuncia expõe o resto.

Que credenciais uma chamada gasta

A assinatura sem chave através de um listener obtém a sua identidade do identity_token que a chamada traz, e de mais nada. Um token enviado na chamada é uma credencial que o chamador detém: teve de o obter, está associado a ele, e a assinatura que produz é-lhe atribuível. Qualquer outro sítio de onde uma identidade pudesse vir pertence a quem iniciou este processo, pelo que, neste transporte, a resolução recebe um ambiente que não responde nada. AGGREGA_IDENTITY_TOKEN e SIGSTORE_ID_TOKEN no ambiente do servidor não são lidos, e o endpoint OIDC ambiente do GitHub Actions não é alcançado. Estão fora de alcance, não apenas desaconselhados — não há nada que a resolução possa encontrar. Uma chamada que não envie identity_token é recusada, e a recusa indica identity_token como aquilo a enviar e não indica nenhuma variável nem endpoint: um chamador que não está ao teclado desta máquina não pode exportar nada aqui, pelo que indicar uma seria dizer-lhe para preparar algo que não pode mudar a resposta.

Uma chave de assinatura guardada nesta máquina não pode ser selecionada, por nenhuma das vias. key_path é recusado antes de se resolver o que quer que seja, e está ausente dos esquemas de argumentos que publish-entity, sign-artifacts e deprecate-artifact anunciam aqui, para que nunca se ofereça a um chamador um argumento que não poderia ter êxito. A chave de assinatura que a própria configuração do espaço de trabalho servido indica também não é alcançada — signing.key_path, quer esteja definida para o espaço de trabalho como um todo, definida para um registo ou fornecida pelo ambiente. Uma razão cobre ambos os casos: um caminho de chave não é uma credencial, é um nome para um segredo que este servidor guarda. Um chamador que forneça um não prova nada, qualquer um que alcançasse este endereço poderia fornecer o mesmo nome, e a assinatura que se seguisse diria que foi o operador a garantir o artefacto e não o chamador. Fechar o argumento deixando a configuração aberta seria fechar uma porta para uma sala que a outra continua a abrir. Por isso, a assinatura com chave é inalcançável através de um listener: só assina um token enviado na chamada.

fulcio_url, rekor_url e timestamp_url não são afetados e mantêm-se em ambos os transportes. Indicam serviços a contactar e não algo que esta máquina guarde, pelo que um chamador que não pode selecionar uma chave continua a assinar contra os endpoints que esta implementação configura.

Um listener iniciado sobre um espaço de trabalho que indica uma chave de assinatura di-lo uma vez, ao arrancar. O processo escreve uma linha no seu próprio fluxo de erros que indica a definição e diz que um chamador que alcance este listener não pode gastar essa chave — para que um operador o saiba pelo processo que iniciou e não por uma assinatura que não esperava. Um espaço de trabalho que não indica chave nenhuma não produz tal linha, porque não há nada a dizer sobre ela. A linha traz o nome da definição e nem a chave nem nada sobre o ficheiro para que aponta.

Em entrada e saída padrão, nada do acima se aplica. Aí o ambiente é lido e key_path seleciona uma chave guardada nesta máquina, porque o cliente que lançou este servidor está a correr na própria máquina do chamador e o que esse processo pode alcançar é desse chamador para gastar.

Ler uma entidade pela sua referência de registo contacta um registo, com o próprio login deste anfitrião, e, através de um listener, apenas um registo com que o espaço de trabalho servido esteja configurado. describe, ao receber uma referência oci:// como name, lê a entidade publicada nessa coordenada — a mesma leitura que aggrega inspect executa — a partir do único registo que a referência indica, usando o login que este anfitrião já detém para esse registo. A chamada não traz credencial, e describe não aceita nenhuma. Por HTTP, o registo tem de ser um com que o espaço de trabalho servido esteja configurado: o anfitrião que o seu default_registry indica, ou um anfitrião listado em registries, comparado de forma exata e com a porta. Uma referência a qualquer outro anfitrião — incluindo um endereço nesta máquina — é recusada antes de esse anfitrião ser contactado, e a recusa indica o anfitrião, para que um chamador não possa apontar este servidor para um destino à sua escolha. O que continua alcançável é deliberado: um chamador com aggrega:read pode ler tudo o que o login deste anfitrião consegue ler num registo com que o espaço de trabalho esteja configurado, que é também o que uma pessoa ao terminal deste anfitrião consegue ler. Em entrada e saída padrão, uma referência a qualquer registo é lida, tal como na linha de comandos. Descrever uma entidade pelo seu nome de catálogo não é afetado.

Uma chamada a um registo usa o armazenamento de credenciais do utilizador do sistema operativo com que este processo corre, exatamente como a mesma chamada num terminal neste anfitrião. Não há uma fonte de credenciais por espaço de trabalho nem nenhuma definição que acrescente uma, e é por isso que registry-list reporta o estado das credenciais de um anfitrião da mesma forma em todos os espaços de trabalho desta máquina. Uma implementação que queira que espaços de trabalho diferentes tenham credenciais de registo diferentes executa-os como utilizadores diferentes do sistema operativo — um processo por espaço de trabalho, cada um iniciado como o seu próprio utilizador. É daí que vem a separação, e organizá-la cabe ao operador.

O que o servidor regista

Cada pedido a que este endpoint responde deixa uma linha no fluxo de erros do processo, e essa linha é um único objeto JSON. Contém o time em que foi escrita e um request_id que este processo gerou para a chamada e não devolve ao chamador; subject e issuer tal como a credencial apresentada os afirmou, com client_id quando indicou um; workspace_root, o espaço de trabalho que este processo serve; method, e target quando o método se dirige a algo pelo nome; reach, o tipo que a operação declara, e reach_escalated_to quando a chamada foi além disso; outcome; duration_ms; e transport. Um campo sem nada a dizer é omitido em vez de escrito vazio, pelo que um client_id ausente é uma credencial que não indicou cliente nenhum, e um reach_escalated_to ausente é uma chamada que alcançou exatamente o que a sua operação declara.

outcome diz o que aconteceu à chamada, e os valores são distintos para que se possam contar separadamente. ok foi executada e teve êxito. tool-failure foi executada e regressou marcada como uma falha que o chamador pode corrigir — uma chamada que este servidor serviu e não uma que recusou, pelo que não pertence às recusas. error é uma recusa devolvida como envelope de erro do protocolo. unauthenticated, forbidden e rate-capped são, respetivamente, a credencial, o limite de origem ou de âmbito e o limite de taxa por chamador a rejeitar um pedido. cancelled é um chamador que fechou a ligação antes de receber resposta.

O motivo pelo qual uma credencial recusada foi rejeitada é um campo dessa mesma linha e não uma linha própria. Um pedido recusado deixa um registo como qualquer outro, com refusal a indicar a verificação que o rejeitou. Nenhuma credencial, nem parte de uma, chega a qualquer linha — nem numa recusa, nem numa chamada que foi servida.

Um chamador que não apresentou nada não deixa linha. Ser desafiado é a forma de um cliente descobrir onde obter um token, pelo que é a primeira coisa que qualquer cliente bem-comportado faz, e uma linha para cada uma dessas soterraria as recusas que significam algo. Um pedido que indique um caminho ou um método que este endpoint não serve também não deixa nenhuma: ambos são resolvidos antes de se ler o que quer que seja sobre um chamador, pelo que sondar o endereço não escreve nada no que quer que recolha o fluxo.

O contexto de rastreio que um cliente envia é copiado para a linha tal e qual. traceparent, e tracestate e baggage ao lado quando também são enviados, são transportados exatamente como recebidos, para que o que quer que recolha este fluxo o possa juntar aos registos próprios do chamador. Um pedido que não envie nenhum, ou envie um que não seja contexto de rastreio W3C bem formado, produz uma linha sem essas chaves: nada é inventado, e nada é alterado pelo caminho.

O processo regista a sua própria vida na mesma forma e no mesmo fluxo, cada uma dessas linhas indicando um event onde uma linha de pedido indica um método e um chamador: startup ao começar, listening com o endereço a que se associou, startup-refused com o motivo pelo qual um arranque foi recusado antes de servir, signing-key-ignored quando o espaço de trabalho que serve indica uma chave de assinatura que nenhum chamador que alcance este listener pode gastar, docs-bundle com o resultado da aquisição do pacote de documentação, e shutdown quando a execução termina. A presença de event é o que distingue os dois tipos de linha.

Tudo isto é recolhido do fluxo de erros do processo, e essa é toda a entrega. Não há exportador a configurar, ficheiro a indicar nem definição que ligue, desligue ou redirecione qualquer parte: o que quer que supervisione este processo — um runtime de contentores, um gestor de serviços, um expedidor de logs — é o que recolhe esse fluxo, e é onde se consulta depois. Em entrada e saída padrão, o mesmo fluxo traz em vez disso prosa legível, porque o cliente que o lê lançou o processo e está na mesma máquina.

Nada disto é enviado ao chamador. O servidor não publica nenhum fluxo de logs pelo protocolo em nenhum dos transportes, e um pedido que traga o campo de nível de log por pedido do protocolo é respondido exatamente como um que não o traga: o que aqui se regista pertence ao operador e vai apenas para o fluxo do operador.

O que o servidor diz ao modelo quando se liga

O servidor oferece um bloco de orientações para o modelo, que o cliente pode apresentar-lhe antes da primeira chamada. Um cliente em 2026-07-28 lê-o da resposta a server/discover; um cliente em 2025-06-18 lê-o da resposta ao seu handshake initialize. É o mesmo texto nos dois caminhos, byte a byte, e o mesmo texto para todos os clientes que alcancem um processo: nada nele é negociado, e nada é derivado do que o cliente enviou nem da credencial que apresentou, pelo que o que é dito a um modelo ao ligar-se não varia entre sessões nem entre clientes.

Variam duas coisas, e nenhuma delas é o cliente. O parágrafo final é composto para o transporte que um processo serve, pelo que um servidor em entrada e saída padrão e um listener entregam a um modelo textos finais diferentes. E, quando o pacote de ambiente de trabalho que lançou um servidor vem de uma versão diferente da do executável aggrega que lançou, as orientações abrem com a frase que o diz, indicando ambas as versões — a frase com que abre a resposta de describe-capabilities sem argumentos, como De que versão vem o servidor expõe; um arranque que nenhum pacote fez, e um cujo pacote vem da mesma versão do executável, entregam as orientações sem ela. Ambas ficam fixadas quando o processo arranca, e dentro de qualquer processo as duas revisões continuam a servir de forma idêntica o texto desse processo.

Ensinam o modelo mental que o esquema de argumentos de uma ferramenta não consegue transmitir sozinho:

  • O que o compilador faz, e o que deliberadamente não faz — que encaminha texto e avalia correspondências de etiquetas em vez de interpretar o significado de um valor, que é sem opiniões próprias quanto ao conteúdo colocado nos documentos e que, ao compilar, nunca se autentica junto de um provider, nunca lê o estado de um cluster e nunca transforma um segredo em texto simples. Um valor que só existe quando a infraestrutura está a correr passa como uma string apontadora que o ambiente de destino preenche mais tarde.
  • O vocabulário de autoria, e como os tipos se relacionam — para que serve cada tipo e contra qual deles uma build é efetivamente executada, para que um assistente não tenha de inferir a forma de uma implementação a partir da lista de ferramentas.
  • A ordem em que o ciclo de autoria decorre — ler o contrato, gerar o esqueleto a partir dele, inspecionar aquilo a que se está a ligar, e depois verificar antes de renderizar.
  • Quando recorrer a um prompt em vez de a uma ferramenta — uma ferramenta para agir, um prompt para enquadrar uma tarefa.
  • Que a lista de ferramentas é toda a superfície — todas as ferramentas que este servidor oferece estão nela, e as ferramentas que um servidor oferece dependem de como foi configurado, pelo que um assistente lê o que existe aqui nessa lista e em describe-capabilities em vez de ir procurar uma segunda. Quando a ligação apresentou uma credencial, diz que a credencial decide quais dessas ferramentas uma chamada pode executar e nunca quais são listadas: uma chamada que não admite é recusada indicando o âmbito que a admitiria, e o cliente pode voltar a iniciar sessão para esse âmbito.
  • O que significa um espaço de trabalho vazio, e o que o modelo pode fazer a esse respeito — o parágrafo que difere consoante o transporte, abaixo.

Nomeiam as superfícies em vez de as repetir. Cada ferramenta já traz a sua própria descrição e esquema de argumentos em tools/list, e o contrato de cada tipo já vive no seu esquema e na sua página de referência, pelo que as orientações apontam para eles e param aí — um único sítio para cada afirmação. Uma ferramenta que nomeiam é uma ferramenta que o servidor serve, e apontam para todas as famílias de recursos que a superfície de leitura resolve, pelo que nada para onde enviam um assistente é um beco sem saída.

Não contêm nenhum índice das próprias ferramentas, e isso é a mesma regra e não uma omissão a ela. Um cliente tem a definição de cada ferramenta de tools/list antes de ler uma palavra deste texto, pelo que uma linha por ferramenta aqui seria uma segunda cópia de propósitos que já tem — paga em cada sessão, por cada cliente, e livre de divergir da lista de ferramentas no momento em que qualquer delas fosse editada.

Indicam também o que não enumeram, e porquê: os destinos de renderização disponíveis e os tipos de biblioteca instalados são propriedades dos plugins e do conjunto de esquemas, pelo que as superfícies de recursos os reportam diretamente, em vez de as orientações trazerem uma cópia que poderia divergir.

O que é dito a um modelo sobre um espaço de trabalho vazio

O parágrafo final responde à pergunta com que um modelo se depara primeiro num espaço de trabalho que não contém nada: o que significa um list-entities vazio, e o que pode fazer a esse respeito. A sua abertura é igual em ambos os transportes — uma listagem vazia significa que o espaço de trabalho que este processo resolveu não contém documentos Aggrega que consiga ler e que os diretórios de catálogo configurados junto a ele também não declaram nenhum — e o que se segue depende do transporte que este processo serve, porque a resposta honesta não é a mesma nos dois.

Em entrada e saída padrão, diz-se ao modelo que o espaço de trabalho é seu para inspecionar e reparar. É-lhe dito onde é respondida uma chamada que não indica espaço de trabalho — na pasta com que o servidor foi lançado, quando foi lançado com uma, e caso contrário no espaço de trabalho encontrado a partir da pasta em que foi iniciado, que pode ser essa própria pasta — e que workspace_root numa chamada indica outro. É encaminhado para config-show, para a configuração em vigor e a camada que decidiu cada definição, e para cli-config-init, para criar uma configuração funcional; ambas estão na lista de ferramentas nesse transporte. O cliente que executa o servidor está na própria máquina do chamador, pelo que o que esse processo pode alcançar é desse chamador para gastar — e o limite define-se onde se define para todas as outras ferramentas, no cliente MCP, como O que um assistente pode fazer sem perguntar primeiro expõe.

Por HTTP, diz-se ao modelo que reporte em vez de configurar. O espaço de trabalho é aquele sobre o qual o processo foi iniciado e fica fixo durante toda a sua vida; uma chamada que indique workspace_root ou catalog_dirs é recusada, indicando o argumento; e nenhuma ferramenta que escreva configuração é oferecida aqui a nenhum chamador, quaisquer que sejam os âmbitos da sua credencial. Essas operações são oferecidas apenas pelas ferramentas que executam um comando aggrega num processo separado, e uma sessão alcançada por HTTP é composta sem elas — pelo que o limite é a composição e não um âmbito, e nenhum token o alarga. Um modelo que alcance a implementação através de um listener não pode, por isso, criar um registo nem reescrever uma política de confiança no anfitrião, e o parágrafo di-lo em vez de o deixar tentar e ler a recusa.

O que um assistente pode fazer sem perguntar primeiro

Um assistente ligado a este servidor em entrada e saída padrão pode chamar todas as ferramentas que o servidor expõe, sem perguntar, a menos que o cliente esteja configurado para o impedir. Nesse transporte, o servidor oferece as ferramentas e não decide quais delas uma dada chamada pode usar: essa decisão é do cliente, e cabe ao utilizador tomá-la aí. Por HTTP não é assim: o servidor lista todas as ferramentas que oferece e anuncia, e recusa uma chamada que os âmbitos do token não admitem, pelo que o limite é do servidor tanto quanto do cliente.

Isto importa porque a superfície de ferramentas é a linha de comandos. Tudo o que se pode escrever, um assistente pode chamar — incluindo as operações que alteram a máquina.

Algumas dessas operações vão além do espaço de trabalho em que se está a trabalhar, e não podem ser desfeitas executando outra coisa. São estas as que vale a pena conhecer pelo nome, da de maior alcance para a de menor:

  • publish-entity, publish-artifact, sign-artifacts e deprecate-artifact vão inteiramente além da máquina. Colocam bytes, uma assinatura ou um marcador de retirada num registo, pelo que o que alteram é o que todos os consumidores desse registo resolvem — não apenas o que esta máquina faz. Republicar conteúdo diferente sobre uma tag é recusado em vez de oferecido, pelo que nada aqui anula uma publicação; a resposta é publicar uma nova versão. Uma assinatura e um marcador de retirada deixam intactos os bytes do artefacto, mas quem obtiver esse artefacto depois obtém-nos também, e nenhum pode ser recuperado de quem já o tem. Em entrada e saída padrão, as mesmas quatro capacidades estão também acessíveis como cli-push, cli-push-artifact, cli-sign e cli-deprecate, que executam os comandos; por HTTP essas quatro ferramentas não existem.
  • Assinar usa credenciais. Em entrada e saída padrão, a assinatura sem chave obtém um token de identidade do argumento identity_token da chamada, de AGGREGA_IDENTITY_TOKEN ou SIGSTORE_ID_TOKEN no ambiente do servidor, ou do endpoint OIDC ambiente do GitHub Actions quando um está acessível; key_path seleciona, em vez disso, uma chave guardada offline. Um assistente que possa chamar estas ferramentas pode, portanto, assinar em nome do utilizador, com qualquer identidade que a máquina que executa o servidor já tenha — e uma assinatura é uma declaração sobre quem garante um artefacto, razão pela qual esta é a operação em que mais se deve pensar antes de a permitir. Através de um listener, só assina um token enviado na chamada: nada no ambiente do servidor é lido, e nenhuma chave guardada no anfitrião pode ser selecionada por um argumento nem pela configuração do espaço de trabalho servido, como Que credenciais uma chamada gasta expõe.
  • aggrega cache evict reduz o armazenamento de módulos compilados, e aggrega cache clear apaga-o. Esse armazenamento é partilhado por todos os projetos Aggrega da máquina. Os módulos removidos são recompilados a pedido, pelo que nada se perde definitivamente — mas a build seguinte de qualquer projeto paga esse custo. aggrega cache clear remove também o pacote de documentação que todos os projetos da máquina leem, que é obtido de novo da próxima vez que um deles o adquirir.
  • aggrega cache prune recupera entradas da cache de artefactos que nenhum lockfile referencia. Quando o lockfile de um projeto não está presente para ser lido, os artefactos fixados desse projeto não são protegidos por ele, e recuperá-los significa obtê-los de novo.
  • aggrega registry add e aggrega registry remove escrevem, por predefinição, na configuração partilhada por todos os espaços de trabalho, pelo que alteram o que se resolve em toda a máquina, não só aqui. aggrega registry add pede também ao registo que indica a política de confiança que esse registo anuncia e fixa o que recebe, exatamente como faz num terminal. Num espaço de trabalho offline essa obtenção é recusada antes de se estabelecer qualquer ligação, pelo que adicionar um registo que não seja o hub oficial é recusado — código curto E0310, nas mesmas palavras — a menos que a chamada forneça identity ou key; aggrega config init, que não aceita nenhum deles, só pode criar o hub offline. Em entrada e saída padrão estão acessíveis como cli-registry-add e cli-registry-remove, e a criação como cli-config-init, que executam os comandos; por HTTP essas ferramentas não existem.
  • pull lê de um registo e escreve dentro do espaço de trabalho para que é apontado. Escreve o lockfile dessa Release, preenche a cache de artefactos com o que resolveu e regista, junto ao lockfile, a identidade de cada plugin que devolve veredictos que o espaço de trabalho anexa. Ao receber pin_sources — ou num espaço de trabalho com pin_sources_at_pull ativo e numa chamada que não o envie como false — executa também o passo de fixação do autor da entidade sobre as Recipes e FeatureRecipes que a Release compila a partir dos diretórios de catálogo, escrevendo o entity.lock junto a cada uma; sem isso, um pull sobre uma tal entidade cujo lock não regista fixação para uma entrada que lê é recusado, indicando o passo. Os próprios ficheiros de entidade nunca são escritos. Nada disto sai da máquina, e resolver de novo é a forma de alterar o que foi registado, pelo que esta é a mais suave das operações daqui que escrevem. É uma das ferramentas pensadas para o ciclo de autoria que escrevem dentro do espaço de trabalho: pin escreve o entity.lock junto à Recipe ou FeatureRecipe indicada, como Fixar as entradas próprias de uma entidade expõe; gen-catalog escreve entidades Plugin geradas sob o diretório indicado; edit-document aplica uma edição estruturada e delimitada a um documento existente e reescreve-o, preservando cada byte que a edição não toca, como Aplicar uma edição delimitada a um documento expõe; e import transforma uma descrição produzida por outra ferramenta em ficheiros de autoria em rascunho e escreve-os no espaço de trabalho, como Transformar uma descrição externa em entidades em rascunho expõe; e scaffold, ao receber example, escreve um dos exemplos executáveis da documentação num diretório novo ou vazio, dir, tal como aggrega scaffold --example faz, o que por HTTP o âmbito de escrita no espaço de trabalho admite. Esse diretório de saída, o guest que gen-catalog lê e qualquer overlay que se lhe dê são, cada um, relativos à raiz do espaço de trabalho, ou absolutos em entrada e saída padrão, o mesmo contrato que todos os outros argumentos de caminho desta superfície usam. Em entrada e saída padrão, a mesma capacidade está também acessível como cli-pull, que executa o comando; por HTTP essa ferramenta não existe.
  • build lê o mesmo registo e faz a mesma escrita quando se lhe envia auto_pull, e só nesse caso. Resolver as dependências de uma Release é uma única operação onde quer que seja pedida, pelo que uma build a que se diz para resolver primeiro faz exatamente o que pull faz e depois renderiza contra o que escreveu — razão pela qual tem o mesmo alcance e não um menor. Ao receber write, escreve também os artefactos renderizados em dist/ na raiz do espaço de trabalho, onde aggrega build os escreve e através da mesma escrita, pelo que alcança o espaço de trabalho nessa chamada; não escreve em mais lado nenhum, e um dist que seja uma ligação que sai do espaço de trabalho é recusado antes de se remover ou escrever o que quer que seja nele. Sem nenhum dos argumentos, que é a predefinição, build renderiza a partir das fixações que o espaço de trabalho já tem e não alcança nada. Leia-se Compilar contra o conteúdo que uma Release já fixa para saber o que o argumento altera e o que deixa como está.

As ferramentas de inventário dizem-no nas suas próprias respostas. cache-status marca cada classe de cache com o seu alcance — workspace para a cache de artefactos no próprio diretório de cache deste projeto, machine para os armazenamentos que todos os projetos partilham — e nomeia explicitamente os que abrangem a máquina, para que um assistente que leia o inventário antes de propor uma recuperação saiba que partes dele não são só do utilizador. As operações de manutenção reportam o mesmo alcance para cada elemento que removeram. Cada um dos quatro resultados de publicação traz um reach próprio, com registries — cada anfitrião de registo a que a chamada se dirigiu, cada um nomeado uma vez, pela ordem em que se dirigiu a eles pela primeira vez — e beyond_this_machine, que é lido a partir do que a chamada efetivamente anexou e não do que pediu: true assim que carregou conteúdo ou anexou uma assinatura, uma data de publicação ou um marcador de descontinuação, e false para uma execução de ensaio e para uma chamada que encontrou tudo já presente, como uma publicação executada de novo sobre uma versão completa ou um lote de assinatura cujas referências já estavam todas assinadas.

Onde se define o limite. O próprio protocolo não define nenhuma permissão por ferramenta — a sua autenticação diz respeito a se um cliente se pode ligar de todo, não a que ferramentas pode depois chamar. A decisão de permissão vive no cliente MCP. Os clientes mais usados conseguem geralmente permitir e negar ferramentas individuais pelo nome a partir de um único servidor, e desativar um servidor por completo para um dado projeto; o nome e a localização da definição diferem consoante o cliente, por isso consulte-se a documentação do próprio cliente sobre permissões de ferramentas. Se se pretendem as leituras e não as escritas, permitam-se aí as ferramentas pretendidas e neguem-se as restantes. Uma configuração permissiva, ou um cliente sem tal definição, deixa todas as ferramentas expostas chamáveis.

Descobrir o que um espaço de trabalho contém

A maioria das ferramentas aceita um objeto: um nome de entidade, ou o caminho de uma Release. As duas abaixo não aceitam nenhum, e são a forma de um assistente acabado de chegar obter um.

list-entities responde ao que o espaço de trabalho contém e list-releases responde à pergunta mais restrita que o resto da superfície não para de fazer: que Releases existem. Nenhuma aceita um objeto, porque o que um espaço de trabalho contém é uma propriedade do espaço de trabalho e não de algo que o chamador tenha de saber primeiro.

Cada uma responde numa de duas formas, e uma chamada que não indique forma recebe o resumo. Essa predefinição pertence só a estas duas, e é o oposto da que build, describe e validate adotam. A estas pergunta-se sobre um objeto que o chamador já indicou, pelo que a resposta mais completa é a que foi pedida e a resposta concisa é opcional. Às outras duas pergunta-se o que existe aqui, por um chamador que ainda não tem nada para indicar e não tem forma de saber quanto custará a resposta antes de ela chegar — por isso reportam primeiro a dimensão e a forma do espaço de trabalho e só entregam registos quando lhos pedem.

O resumo diz o que existe aqui e em que quantidade. list-entities reporta a raiz do espaço de trabalho — retida por HTTP, como O que uma resposta diz sobre o sistema de ficheiros do servidor expõe — o número total de entidades e uma contagem por tipo; list-releases reporta o total e uma contagem por diretório de primeiro nível, para se saber quantas Releases existem e em que parte da árvore estão. Ambas as decomposições são lidas dos próprios documentos, pelo que um espaço de trabalho organizado de uma forma que ninguém previu é resumido com a mesma exatidão que um que não o é. Ambas trazem uma linha por tipo, ou por diretório de primeiro nível, pelo que a sua dimensão acompanha quantos tipos um espaço de trabalho declara e em quantos diretórios estão as suas Releases, e não quantos documentos contém: multiplique-se por cem os documentos de um espaço de trabalho, mantendo os seus tipos, e o resumo cresce apenas os poucos bytes que os números maiores ocupam. Declarar mais tipos é o que o torna mais longo. Nenhuma das duas é uma primeira página de registos, e a diferença é precisamente essa: «eis algumas das entidades» é uma resposta diferente de «é disto que o espaço de trabalho é feito», e só a segunda diz se se quer algum registo, e quais.

Envie-se response_format: detailed para obter os registos, e estes chegam uma página de cada vez. list-entities reporta então o tipo, o nome, a apiVersion, a descrição, as etiquetas e o ficheiro de origem de cada entidade, lidos diretamente do documento que a declara. Reporta também as Features que os diretórios de catálogo configurados declaram, para que uma Feature oferecida como anexável seja uma que também se possa consultar; essas não trazem ficheiro de origem, porque o único caminho que têm é um na máquina em que o servidor corre, e cada uma diz de onde veio, para que um ficheiro vazio se leia como «resolvido a partir do catálogo» e não como um valor em falta. list-releases reporta o caminho de cada Release, e lockfiles faz corresponder cada caminho devolvido ao caminho do lockfile dessa Release, na mesma coordenada: o ficheiro que pull escreve para ela e que build lê, o mesmo ficheiro que as respostas do servidor de linguagem sobre Releases indicam. O mapa descreve os caminhos que esta resposta traz, pelo que acompanha a página, e o resumo trá-lo vazio.

detailed e concise são os únicos valores que response_format aceita, e são comparados de forma exata. Qualquer outra grafia — outra palavra, outra capitalização, ou espaços em branco à volta de um deles — é recusada, e a recusa indica o que foi enviado juntamente com os valores que o argumento aceita. Omitir response_format é a forma de pedir a predefinição, que para estas duas ferramentas é o resumo. O mesmo vale onde quer que o argumento apareça: build, describe e validate aceitam os mesmos dois valores nos mesmos termos, e a sua predefinição é a forma mais completa e não a concisa.

Os registos são limitados quer se limitem quer não. limit é quantos traz uma resposta, entre 1 e 500, e a predefinição é 50 — pelo que uma chamada que pede registos e não indica tamanho de página continua limitada, e nenhuma invocação de qualquer das ferramentas devolve uma resposta cuja dimensão seja decidida pela do espaço de trabalho. offset é onde começar na listagem, a contar de 0. Ambos limitam os registos, pelo que nenhum tem efeito no resumo, que não traz nenhum. Um limit fora desse intervalo é recusado e indica o limite; um offset para lá do fim da listagem regressa vazio, porque não há nada aí e não porque a pergunta esteja errada.

Continua-se uma listagem lendo três campos da resposta. count é quantos registos o espaço de trabalho contém, offset e returned dizem onde começa esta resposta e quantos traz, e more_remaining diz se ainda restam alguns. Enquanto more_remaining for true, chame-se de novo com offset mais returned. Esse sinal é calculado a partir da página em relação ao total e não escrito na resposta, pelo que não pode indicar que nada resta quando ainda restam registos.

Tudo isto importa porque as ferramentas que aceitam um nome recusam um que não consigam resolver em vez de responderem com um resultado vazio. A recusa é deliberada — uma resposta vazia apresentaria um nome mal escrito como um objeto sem nada a oferecer — mas significa que um chamador sem nome nenhum não consegue obter um por adivinhação. Enumerar é a forma de obter um.

As duas combinam-se, e com o resto da superfície:

  • Chame-se list-entities para obter o resumo e ver que tipos o espaço de trabalho contém e quantos de cada, depois chame-se de novo com response_format: detailed para obter os registos, retire-se um nome do resultado e entregue-se a describe para ver a definição totalmente resolvida dessa entidade. É a definição com que responde o aggrega/entityDefinition do servidor de linguagem, transportada como JSON: cada chave com o nome que o seu autor escreve, pela ordem em que a definição a guarda, um esquema como o esquema que o autor escreveu, e um esquema que a entidade não declara omitido — os sockets de um Component, cada um com os slots que as suas ligações podem preencher.
  • Faça-se o mesmo com list-releases, retire-se um caminho do resultado detalhado e entregue-se a describe ou a build como a Release sobre a qual trabalhar.
  • O caminho que list-releases devolve é relativo à raiz do espaço de trabalho, que é a mesma coordenada em que list-entities reporta um ficheiro, pelo que as duas respostas se alinham no ficheiro e podem ser lidas em conjunto. O seu lockfile, em lockfiles, é relativo à mesma raiz, pelo que se pode ler ou comparar esse ficheiro sem descobrir onde está.

Ambas decidem o que conta lendo o próprio kind de cada documento, nunca o nome do ficheiro. Uma Release com nome sem prefixo convencional é listada; um ficheiro que apenas tem nome de uma não o é, e aparece sob o tipo que realmente declara. YAML que não declara kind nenhum — o ficheiro de valores de um chart, um ficheiro de configuração que por acaso está na árvore — não é uma entidade e não é reportado, tal como não o é um documento pertencente a outro projeto, como um manifesto Kubernetes renderizado. Um documento conta como entidade quando declara um kind e um nome, porque são esses dois em conjunto que o tornam endereçável depois, e não declara nenhuma apiVersion fora do próprio grupo do Aggrega. Um que não declare apiVersion nenhuma é reportado, por ser um documento Aggrega com um campo em falta e não o ficheiro de outro projeto. list-releases não pesquisa nenhum diretório fora da raiz do espaço de trabalho, pelo que uma Release que o editor mostra sob uma ligação que conduz a um não é listada; unread_linked_dirs indica cada ligação que está onde a listagem leria um diretório e conduz para fora da raiz — pelo próprio caminho da ligação relativo à raiz, nunca pelo sítio para onde conduz — em ambas as formas e em ambos os transportes, e fica vazio quando não há nenhuma. Também não lê um ficheiro fora da raiz através de uma ligação: unread_linked_files indica, da mesma forma, cada ligação cujo próprio nome termina em .yaml ou .yml e que conduz a um ficheiro fora da raiz, seja qual for o conteúdo desse ficheiro, pelo que uma Release alcançada apenas através de uma não é listada — a menos que a configuração do espaço de trabalho indique essa Release, como build.authoring_release ou como chave de workspace.releases, caso em que é lida e listada no próprio sítio da ligação e não é indicada. list-entities também não lê nenhum documento atrás de uma ligação que sai do espaço de trabalho — não pesquisa nenhum diretório fora da raiz e não lê nenhum ficheiro fora dela, declare esse ficheiro o que declarar — e indica cada uma dessas ligações da mesma forma, nos seus próprios unread_linked_dirs e unread_linked_files, em ambas as formas e em ambos os transportes. Isto vale declare o documento o que declarar, com a única exceção que list-releases faz: uma Release que a configuração do espaço de trabalho indica, como build.authoring_release ou como chave de workspace.releases, é lida e listada no próprio sítio da ligação e não é indicada, enquanto um ficheiro indicado por uma dessas definições que declare algo que não uma Release não é listado, e a sua ligação é indicada. Os diretórios de catálogo configurados são a forma de um espaço de trabalho ler outras entidades guardadas noutro sítio, pelo que uma ligação para um diretório que a configuração lista em catalog_dirs, ou para um diretório abaixo de um, não é indicada por nenhuma das listagens: a configuração alcançou-o. As Features que list-entities obtém dos diretórios de catálogo nunca incluem uma atrás de uma ligação que sai do diretório dentro do qual as leituras de um diretório de catálogo têm de ficar — o espaço de trabalho, para um diretório de catálogo dentro dele, ou o próprio diretório, para um que a configuração indica fora dele — pelo que uma entidade indicada como estando atrás de uma ligação que não foi lida nunca é listada junto a esse nome. Uma ligação que a listagem deixa de fora — pelo seu nome, pelo sítio onde está ou por um .gitignore — não é indicada, e com release também não o é uma sob um diretório de catálogo que só outras Releases leem; um .gitignore que seja ele próprio uma ligação que sai do espaço de trabalho não é lido. Quando alguma destas listas indica uma ligação, a resposta em texto termina com uma linha própria que o diz.

Um espaço de trabalho cujo ficheiro de configuração conduz para fora dele continua a ser listado, e mais nada é respondido para ele. Quando o próprio .aggrega-config.yaml do espaço de trabalho, ou o overlay gerido pela CI ao lado dele, é uma ligação que sai do espaço de trabalho, a sua configuração não é lida, tal como num terminal, e nada do que teria configurado é lido em seu lugar. O servidor continua a arrancar em entrada e saída padrão, e di-lo numa linha no seu fluxo de erros. list-entities e list-releases respondem com os documentos próprios do espaço de trabalho, lidos sem nada configurado, pelo que não são listadas as Features de nenhum diretório de catálogo. Cada uma indica o ficheiro retido em unread_linked_files, e na linha que fecha o seu texto, quer a listagem o tenha encontrado quer não — esse nome é a forma de saber que a configuração do espaço de trabalho conduz para fora dele. Uma listagem a que se enviou release ou catalog_dirs, e qualquer outra ferramenta que indique esse espaço de trabalho, depende da configuração que não foi lida, pelo que cada uma é recusada com E0321, indicando a ligação e para onde conduz. Um servidor a que se disse na linha de comandos para escutar — --transport http, ou --listen — não arranca sobre um tal espaço de trabalho, porque o endereço a que se associaria, o seu certificado e quem o pode chamar são o que essa configuração decide. Remova-se a ligação, ou faça-se com que conduza a um ficheiro dentro do espaço de trabalho, e a chamada seguinte lê a configuração. Consulte-se o limite do espaço de trabalho.

Perguntar nos termos de uma Release

Um espaço de trabalho pode dar a cada Release diretórios de catálogo próprios — ver Dar a uma Release os seus próprios diretórios de catálogo — e assim manter lado a lado uma variante de uma entidade por Release. Três ferramentas que, de outro modo, respondem sobre os próprios diretórios de catálogo do espaço de trabalho aceitam um release opcional, o caminho de um ficheiro de Release, e respondem então nos termos dessa Release:

  • list-entities com release lista as entidades que essa Release vê. As Features listadas são as que os seus diretórios de catálogo declaram, e um documento do espaço de trabalho sob um diretório de catálogo que só outras Releases leem é deixado de fora, pelo que cada variante é listada para a Release que compila com ela e para nenhuma outra. Um documento fora de qualquer diretório de catálogo — uma Release, o seu Aggregate e o seu Manifest escritos junto aos catálogos — é listado para todas as Releases.
  • describe com um name e um release resolve o nome através dos diretórios de catálogo dessa Release, pelo que um nome que várias variantes declaram resolve para aquela com que essa Release compila. Um nome que esses diretórios não resolvem é recusado com uma explicação que indica a entrada dessa Release em workspace.releases. Uma referência de registo é lida do seu registo seja qual for a Release indicada, pelo que é recusada junto a um release. Um release enviado sem name continua a ser a Release que describe resume.
  • validate com um entity e um release executa as verificações de entidade única nos termos dessa Release: as referências da entidade — o Component que uma Recipe implementa, uma SchemaLibrary a que um pilar se refere — são resolvidas através dos diretórios de catálogo dessa Release, e a resposta indica a Release junto à entidade. Nenhum fecho é validado; um release enviado sem entity continua a ser o âmbito da Release. catalog_dirs é acrescentado à frente dos diretórios da Release aqui como em todo o lado. Um diretório que a configuração do espaço de trabalho lista e que não é um diretório — por nada existir aí, por exemplo —, para essa Release, ou para o espaço de trabalho quando não se envia release, faz recusar a chamada antes de qualquer verificação, com o texto a trazer a recusa que todos os comandos lhe dão e a indicar a entrada e o ficheiro e a linha de configuração que a listam (De onde são lidas as entidades locais), tal como aggrega validate o recusa.

Um release que indique um ficheiro que não existe, ou que indique um diretório, é recusado nas três em vez de ser respondido nos termos do espaço de trabalho. Não enviar nenhum responde sobre os próprios diretórios de catálogo do espaço de trabalho.

describe, ao procurar um nome, recusa um diretório de catálogo através do qual resolveria o nome e que não pode ser percorrido, tal como aggrega inspect o recusa — os diretórios dessa Release quando se envia um release, os do próprio espaço de trabalho quando não se envia, e quaisquer que a chamada indique em catalog_dirs. Um diretório indicado pela chamada que não existe, ou um que existe e não pode ser lido, é recusado antes de se procurar o nome, e o texto indica o diretório tal como a linha de comandos o reporta, numa linha — o diretório, catalog load e o motivo dado pelo sistema de ficheiros — em vez de resolver o nome a partir dos diretórios restantes. Um diretório que a configuração do espaço de trabalho lista e que não é um diretório é recusado no mesmo momento, com o texto a trazer a recusa que todos os comandos lhe dão (De onde são lidas as entidades locais). Um release que indique um ficheiro que não existe é recusado antes disso, como acima. Um diretório de catálogo que contenha uma ligação que sai do diretório dentro do qual as suas leituras têm de ficar é recusado da mesma forma, com o texto a indicar a ligação e para onde conduz, porque um nome resolvido sem ela poderia resolver outra entidade com o mesmo nome em seu lugar. Descrever o fecho de dependências de uma Release não é afetado por um diretório que não pode ser percorrido, e responde sobre os diretórios que podem, tal como aggrega inspect --closure faz — exceto um diretório que a configuração do espaço de trabalho lista para essa Release e que não é um diretório, que essa descrição recusa tal como aggrega inspect --closure o recusa; uma ligação que sai das leituras de um diretório de catálogo, ou dos documentos junto à Release, interrompe-o, tal como interrompe uma build.

validate com um entity reporta uma renderização que não consegue avaliar como não tentada, nos termos de uma Release ou de nenhuma. Coloca o Component de uma Recipe numa build sintetizada que não liga nenhuma ligação nem anexa nenhuma Feature, pelo que uma Recipe cuja renderização para enquanto os seus templates — incluindo os ficheiros e as entradas de biblioteca que importam — leem algo sob .context.inject, .context.uses ou .features responde valid: true sem nada em diagnostics; o seu texto traz Render: not attempted (this Recipe reads values a build of one cannot supply), as leituras pelas quais foi posta de parte e a frase em que a renderização parou. O que o decide é o que a Recipe lê, pelo que uma falha da própria Recipe junto a uma tal leitura é posta de parte com ela, enquanto um template que não faz parse e uma referência que a renderização recusa continuam a responder valid: false. aggrega validate dá o mesmo veredicto com as mesmas entradas.

validate com um entity reporta uma asserção falhada como um aviso, nos termos de uma Release ou de nenhuma. Uma asserção que chama fail — a da própria Recipe, ou uma que o Component que implementa declara — responde valid: true sem nada em diagnostics. A build sintetizada traz marcadores de posição e predefinições do esquema em vez dos valores que uma Release real define, pelo que uma asserção sobre um tal valor falha aí quer a Recipe esteja correta quer não, e a verificação não consegue distinguir uma asserção à espera de uma Release de uma que está avariada. A falha segue as outras notices, na mensagem completa da asserção terminada pela frase A Release must satisfy this assertion before a build of it can pass., e o texto trá-la numa linha iniciada por warning:, junto à linha de relatório que diz onde a execução parou. Uma asserção que para numa chave que lê mas não encontra é uma falha no seu próprio texto e não uma asserção falhada, e é avaliada como qualquer outra paragem; uma build de uma Release que não satisfaz uma asserção continua a ser recusada por ela. aggrega validate dá o mesmo veredicto com as mesmas entradas.

Ler a configuração em vigor e os plugins que este servidor resolve

config-show reporta a configuração em vigor e a camada que decidiu cada definição. plugin-list reporta os plugins que este servidor consegue resolver e o que cada um deles diz sobre si próprio. Nenhuma das duas lê nem escreve nada, pelo que cada uma não alcança nada e aggrega:read a admite — e nenhuma pede que se indique um objeto, porque o que está configurado e o que se resolve são propriedades deste servidor e não de algo que se tenha de saber primeiro. Cada uma aceita um workspace_root opcional em entrada e saída padrão; por HTTP esse argumento é recusado, como Um processo, um espaço de trabalho expõe.

Em conjunto, respondem a uma pergunta em duas metades: se uma capacidade está ausente ou apenas não está configurada aqui. A configuração diz se um provider, um importador ou uma verificação de governação está de todo anexado; a leitura de plugins diz se um anexo chega a um guest que se resolve, se descreve a si próprio e serve o que afirma servir. A partir de qualquer outro ponto desta superfície, as duas situações parecem iguais, e pedem passos seguintes opostos.

config-show reporta uma entrada por definição: o seu field, o seu value efetivo e a source que o decidiu — um ficheiro de configuração, uma variável de ambiente, uma flag da linha de comandos ou as predefinições incorporadas. Junto a elas, layers traz as camadas que contribuíram, por ordem de precedência, da mais baixa para a mais alta. A source de uma definição é escrita exatamente como a entrada correspondente em layers, pelo que as duas se juntam diretamente, e uma definição decidida pelas predefinições não indica camada nenhuma, porque as predefinições não são uma camada que tenha contribuído. A camada global é o ficheiro que a própria linha de comandos do servidor seleciona — o que --config indicou quando foi iniciado, caso contrário o que a variável de ambiente AGGREGA_CONFIG indica, caso contrário a localização predefinida — pelo que uma definição que esse ficheiro decide é atribuída a esse ficheiro, exatamente como aggrega config show --origin a atribui, e uma flag como --offline dada ao servidor é reportada como essa flag. Não aceita response_format nem tamanho de página: as definições são o conjunto fixo que este binário contempla e cada resolução reporta todas, pelo que a dimensão da resposta acompanha o binário e não o que se configura.

plugin-list responde nas duas formas que as listagens do espaço de trabalho usam, e uma chamada que não indique forma recebe o resumo. O resumo é uma contagem por grupo, e há dois grupos — embedded, os guests compilados neste binário, que se resolvem sem acesso ao sistema de ficheiros, à cache nem à rede, e configured, as associações próprias do espaço de trabalho. Envie-se response_format: detailed para obter os registos: o grupo de cada plugin, a referência sob a qual foi encontrado, onde essa referência foi associada, o tipo que reporta sobre si, a versão, o commit, as capacidades servidas, os tipos de entrada renderizados, a montagem de fronteira e as exportações, a prontidão, quando a tem, e se foi resolvido. Os registos são limitados por limit e offset nos mesmos termos que a listagem de entidades usa, com count, returned e more_remaining para continuar. Esta resposta cresce de facto com o que se configura — os incorporados são fixos, as associações são do utilizador — e é por isso que é paginada e a leitura da configuração não é.

Um plugin que falha é reportado com a sua falha em vez de ser retirado da listagem. resolved diz se a referência chegou de todo aos bytes do módulo, e um plugin que se resolveu mas não conseguiu descrever-se é reportado exatamente assim — pelo que um anexo presente e inutilizável se distingue de um que nunca foi feito.

O que um listener não diz sobre o seu anfitrião

Por HTTP, nenhuma das leituras reporta um valor que indique um sítio no sistema de ficheiros do servidor. Um cliente que lançou o servidor corre onde o servidor corre, pelo que cada localização que qualquer das respostas poderia indicar é uma que esse chamador já possui e pode ir ver. Um chamador que alcança um listener não escolheu nenhuma delas, não pode agir com base em conhecê-las, e um servidor que as tenha publicado a um tal chamador não as pode «despublicar». Nesse transporte esses valores estão ausentes; em entrada e saída padrão estão todos presentes. É a regra que todas as respostas desta superfície seguem, como O que uma resposta diz sobre o sistema de ficheiros do servidor expõe, e estas duas leituras são onde ela vai mais longe, porque a maior parte do que reportam é configuração que indica sítios.

O que é retido. De config-show: o value de uma definição quando o próprio valor dessa definição é uma localização — um endereço de serviço ou de saúde, que pode ser um ficheiro de socket; um ficheiro de certificado, de chave privada ou de conjunto de chaves; um diretório de catálogo, e os diretórios de catálogo próprios de uma Release em workspace.releases, cujas entradas são todas indexadas por um ficheiro de Release; uma referência de plugin; uma Release de autoria. Também a source de uma definição quando a camada que a decidiu é um ficheiro de configuração, já que uma tal camada é indicada pelo próprio caminho desse ficheiro — e, na mesma grafia e pela mesma razão, as entradas de ficheiro de configuração de layers. De plugin-list: o uri de um plugin quando essa referência é ela própria um caminho do sistema de ficheiros, e o texto de uma falha de resolução ou descrição, que é composto a partir dos sítios tentados e indica, por isso, localizações que a própria referência não indica. De ambas: workspace_root.

O que é reportado por inteiro, em ambos os transportes. Uma referência de registo, uma versão, um commit, um digest, uma capacidade servida, uma etiqueta de prontidão, o nome de uma variável de ambiente ou de uma flag, e uma camada que não seja um ficheiro. origin num registo de plugin é um destes: é a chave de configuração em que uma associação foi escrita, ou o digest fixado que uma extensão de comando instalada traz, e um incorporado não traz nenhum — pelo que é a mesma string seja de onde for que o plugin seja lido. resolved é outro: se um plugin falhou é reportado a todos os chamadores, mesmo quando o motivo não o é.

Um valor ausente diz sempre que foi retido, e é isso que torna a resposta utilizável. Um valor retido é reportado como ausente com uma marca ao lado — value_withheld e source_withheld numa definição, withheld numa entrada de camada, uri_withheld e error_withheld num registo de plugin, e workspace_root_withheld na resposta. Uma definição que ninguém definiu traz o valor vazio em que a sua forma se representa, e não traz marca. «Este servidor não está a dizer onde está a chave de assinatura» e «não está configurada nenhuma chave de assinatura» são respostas diferentes que pedem passos seguintes diferentes, e uma leitura que as reportasse de forma idêntica não diria nada sobre o qual se pudesse agir. Cada resposta traz também host_locations_withheld, sempre, que diz qual das duas respostas se tem em mãos: uma resposta sem marcas é, de outro modo, igual quer esta regra a tenha moldado e não houvesse nada no anfitrião a reter, quer nunca se tenha aplicado. O texto legível junto aos campos diz o mesmo por palavras.

A regra é uma propriedade e não uma lista de nomes de campos: um valor é retido quando indica um sítio no sistema de ficheiros do anfitrião, seja quem for que o definiu e seja qual for a camada de onde veio. Um valor acrescentado mais tarde a qualquer das leituras fica sujeito a essa mesma propriedade.

Em entrada e saída padrão, cada capacidade está também acessível como a ferramenta com o nome do seu comando — cli-config-show e cli-plugin-list — que executam esse comando num processo separado e devolvem o texto que imprimiu; por HTTP essas ferramentas não existem. As duas aqui descritas trazem os valores em vez disso, para que se leia se uma capacidade está anexada, ou se retire a versão de um plugin, sem ter de converter um layout em colunas de volta naquilo a partir do qual foi renderizado.

Perguntar o que pode ser anexado, e o que pode ligar-se a quê

Duas ferramentas respondem às perguntas que um assistente teria de outro modo de adivinhar: que Features podem ser anexadas a um nó, e a que pode um nó ligar-se. Ambas executam a mesma correspondência de etiquetas que o compilador executa, pelo que o que o assistente oferece é o conjunto que uma build faria corresponder e não um conjunto inferido a partir do esquema.

attach-candidates reporta as Features cuja aplicabilidade declarada as etiquetas de um nó satisfazem. Endereça-se o nó exatamente de uma de três formas:

  • node — o metadata.name de uma entidade do espaço de trabalho, tal como list-entities o reporta. A correspondência é feita sobre as etiquetas que esse documento declara.
  • graph_node com release — um nó num grafo compilado, identificado como o grafo o identifica, incluindo a forma qualificada que traz um nó contribuído por um sub-agregado. A correspondência é feita sobre as etiquetas finalizadas desse nó, que são as que uma build avalia.
  • labels — um conjunto de etiquetas por si só, sem indicar nó nenhum. Não precisa de coordenada nenhuma, pelo que, se já se têm as etiquetas de um nó, é esta a forma a usar; não procura nada nem reconstrói nenhum grafo.

A resposta traz as etiquetas sobre as quais a correspondência foi feita e de qual desses três conjuntos vieram, para que se possa explicar qualquer candidato — ou a ausência de um — a partir da própria resposta, em vez de o recalcular. Lê-las de volta de uma segunda forma é como a ideia que se tem das etiquetas de um nó e a do compilador divergem.

Para perguntar o que pode ser anexado a uma ligação que um nó estabelece, acrescente-se connection junto a graph_node e release — o seu socket e o seu alias, tal como o autor os escreveu. Uma ligação traz anexos que preenchem os slots que o seu socket declara no Component consumidor, pelo que a resposta traz então também slots: cada slot que o socket declara, com o seu selector, required, inject, sensitive e description exatamente como o Component os declara, e os candidates que o podem preencher. São as Features cuja aplicabilidade as etiquetas do nó satisfazem e cujas próprias etiquetas o seletor do slot admite — as duas regras a que uma build sujeita um tal anexo — pelo que os candidatos de um slot estão sempre entre os do próprio nó. Quando nada pode ser preenchido, slots fica vazio e noSlotReason diz porquê: feature-created-connection (uma Feature estabeleceu a ligação, e nada é anexado a uma tal ligação), ad-hoc-socket (o socket é um que o Component não declara) ou no-slot-declared (o socket não declara nenhum). Não se leia um slots vazio como «nada correspondeu»; é isso que o motivo está lá para excluir, e está ausente sempre que existe um slot. candidates ao lado mantém o seu significado — o que pode ser anexado ao próprio nó — e document, se for enviado, não altera nada aqui. connection junto a node ou labels, ou sem indicar socket nem alias, é recusado, tal como uma ligação que o nó não estabelece. São as mesmas respostas que o servidor de linguagem dá, nos mesmos termos.

connection-candidates reporta os sockets de dependência que uma entidade declara e, por socket, os Components do espaço de trabalho cujas etiquetas declaradas satisfazem a restrição que esse socket declara sobre os seus destinos. Aceita o metadata.name da entidade em node. Ao contrário de attach-candidates, não tem forma sem coordenada: aqui não existe a forma de conjunto de etiquetas, porque os sockets são lidos da própria declaração da entidade indicada.

As suas duas metades não são igualmente completas, e a resposta diz qual é qual — não as apresente como uma única lista. Os destinos são completos: são os componentes que a mesma restrição admite durante uma build. Os sockets não o são, nem podem ser. Um consumidor pode inventar uma ligação mas só pode consumir o que um produtor declara, pelo que um autor pode legitimamente escrever um socket que a entidade de catálogo nunca declarou, e os sockets declarados são um ponto de partida útil e não o conjunto de nomes legais. Cada socket diz, por isso, se é declared ou ad-hoc, e a resposta diz se um socket não declarado é de todo aceite nessa entidade — a superfície de dependências própria de um Component aceita um, porque um autor é dono da topologia da sua aplicação; a superfície de anexos de uma Feature não, porque um anexo participa na topologia que a Feature anexada declara em vez de criar uma. Essa abertura é uma consequência da liberdade de autoria, não uma lacuna: passe-se socket com um nome que a entidade não declara para perguntar sobre ele.

Ambas respondem e param. Nenhuma cria um anexo, cria uma aresta, escreve em ficheiro algum ou propõe o texto de um; compor e aplicar a edição que se seguir cabe ao utilizador.

Ambas devolvem a mesma identidade mínima que todas as outras respostas daqui usam — tipo, nome e ficheiro de origem — e nada mais. Tudo o resto que se queira mostrar sobre uma entidade já está em list-entities para os mesmos três campos, pelo que se juntam as duas respostas em vez de ler duas cópias que poderiam divergir. Ambas recusam um nome que não conseguem resolver em vez de responderem com uma lista vazia, pela mesma razão que o resto da superfície: uma resposta vazia apresentaria um erro de escrita como um objeto sem nada a oferecer. Uma chamada com labels não tem nome para escrever mal, pelo que um resultado vazio aí significa o que diz.

Tudo o que o servidor lê para referência é servido a partir desta máquina — os JSON Schemas estão incorporados no binário e a documentação é lida da cache do pacote de documentação que a máquina mantém, como descrito abaixo. Redigir um documento inicial, validar, descrever, compilar e fazer lint correm todos contra o espaço de trabalho e as caches locais, e nenhum deles alcança um registo por iniciativa própria: uma renderização serve uma referência externa fixada a partir do armazenamento endereçado por conteúdo e recusa uma não fixada em vez de a obter, que é o que mantém offline todo o ciclo de inspeção e renderização. Há duas leituras de registo que se podem pedir: describe com uma referência de registo, que obtém essa coordenada, não escreve nada e, por HTTP, só alcança um registo com que o espaço de trabalho servido esteja configurado; e scaffold com example ou list, que obtém o pacote de documentação a partir do registo predefinido do espaço de trabalho quando a máquina não guarda nenhuma cópia que a política de assinaturas do espaço de trabalho admita, verificado antes de ser guardado, tal como aggrega scaffold --example faz. Publicar e assinar são o outro lado deliberado disso, e estão descritos acima.

Entre os dois fica a resolução das dependências de uma Release, que é a única coisa aqui que adquire: alcança um registo porque pedir para resolver dependências é pedir para as obter. Só acontece quando é pedida, e há exatamente duas formas de a pedir — chamar pull, cuja função é toda essa, ou enviar auto_pull a build, que executa essa mesma resolução como primeiro passo da build. Fora disso, nada faz pull em nome do utilizador, e uma build a que não se enviou auto_pull não alcança nenhum registo. A única definição que altera isto é o próprio auto_pull do espaço de trabalho: um espaço de trabalho configurado assim está a pedir que todas as builds nele resolvam primeiro, seja de onde for que a build seja executada, o que é descrito abaixo.

A única exceção entre essas leituras de referência é a aquisição do próprio pacote de documentação, e acontece à margem de todas as leituras. O pacote é guardado uma vez por máquina, na cache que todos os projetos Aggrega partilham, uma cópia por registo e versão — pelo que um servidor iniciado numa pasta onde não pode ser criada nenhuma cache de espaço de trabalho o guarda na mesma (ver aggrega cache). Quando o servidor arranca, antes de responder ao que quer que seja enviado, procura aí uma cópia que a própria verificação de assinatura do espaço de trabalho admita — a mesma verificação a que responde um pull do pacote — e só faz pull do pacote, através das mesmas definições de saída de rede que o resto da CLI usa, quando não existe nenhuma. O pacote que procura é o publicado para a versão do aggrega que o servidor executa ou, quando não existe nenhum publicado para ela, o mais recente publicado para uma versão anterior — a mesma escolha que aggrega explain e aggrega scaffold --example fazem — e cada página que serve, e cada explicação, é lida a partir daquele que obteve. Assim, as páginas já estão lá quando alguma coisa pede uma, seja o que for que o cliente envie primeiro, e outro servidor, ou aggrega explain noutro projeto, encontra a mesma cópia em vez de a descarregar de novo.

Servir uma página é então uma leitura dessa cópia, e não alcança nenhum registo. Antes de uma página ser servida, as assinaturas guardadas junto à cópia são verificadas de novo segundo a verificação do espaço de trabalho, pelo que uma cópia que a definição mais permissiva de outro projeto deixou entrar não é servida: quando a verificação fixa uma chave ou uma raiz de confiança, essa verificação corre offline, e quando não fixa nenhuma — a verificação incorporada do hub oficial é uma dessas — obtém a raiz de confiança pública do Sigstore, tal como um pull. Um espaço de trabalho offline não pode obter essa raiz de confiança, pelo que, offline, verifica contra a raiz de confiança que uma obtenção online anterior nesta máquina deixou na cache que o cliente Sigstore mantém em .sigstore no diretório pessoal, por mais antiga que essa obtenção seja, e não obtém nada; numa máquina que nunca a obteve, a verificação não pode correr offline, a cópia não é servida e o fluxo de logs di-lo. Essa verificação corre uma vez por cada cópia e cada verificação enquanto o servidor corre, e as páginas lidas depois dela são servidas com base no que admitiu: uma cópia obtida entretanto, um espaço de trabalho cuja verificação difere — incluindo uma raiz de confiança fixada editada no local —, uma leitura feita offline, ou uma leitura offline que encontre outra raiz de confiança deixada na máquina é verificada por si. Uma cópia que a verificação recusou é verificada de novo na leitura seguinte, para que uma obtenção que entretanto a admitiu não seja contrariada. Se o pacote não puder ser adquirido, ou se a única cópia for uma que a verificação recusa e obtê-la de novo segundo essa verificação falhar, o servidor arranca na mesma e todas as outras superfícies funcionam; os pedidos de documentação respondem not-found, e o fluxo de logs do servidor diz porquê.

Compilar contra o conteúdo que uma Release já fixa

build renderiza uma Release nos seus artefactos em memória, e uma renderização pode pedir conteúdo de um URL remoto — o esquema de valores de um chart com uma referência remota, por exemplo. As entradas externas ficam congeladas durante a chamada. Uma referência que o lockfile da Release já fixa é servida a partir do armazenamento endereçado por conteúdo, o que é uma leitura de conteúdo já em disco e não uma obtenção. Uma referência que o lockfile não fixa é recusada e indicada em vez de obtida: o que se pediu foi uma renderização, e adquirir uma referência significaria tanto alcançar a rede como escrever um blob no armazenamento como efeito secundário de produzir bytes. Esse congelamento é uma propriedade da renderização. Resolver é o passo que adquire: renderiza a Release para descobrir que referências remotas essa renderização pede, obtém-nas e regista-as na mesma escrita do lockfile que traz as fixações de dependências. Assim, o que resolver altera é que referências estão fixadas quando uma renderização corre, nunca o que uma renderização pode alcançar — e uma referência que nenhuma resolução fixou é recusada numa chamada que resolveu primeiro exatamente como numa que não o fez.

Os ficheiros regressam como os bytes que uma build real emite, e são duas coisas em conjunto que o garantem. Uma é o congelamento acima: uma referência fixada é lida do armazenamento em vez de obtida. A outra é que o lockfile de onde se lê continua a descrever aquilo para que a Release resolve — por isso build verifica-o, e recusa um lockfile que já não corresponde, exatamente como aggrega build faz num terminal. Ler bytes fixados não diz, por si, nada sobre se eram os bytes certos a ler.

Os três estados do lockfile, para que a postura seja explícita. Sem lockfile nenhum, build renderiza a partir do que o espaço de trabalho já fixa e recusa cada referência externa que não consegue servir, indicando cada uma; entregue a si próprio, não exige um lockfile nem escreve um, e isso não muda com a verificação acima — não há lockfile para comparar, pelo que nada é recusado. Com um lockfile que corresponde, renderiza. Com um lockfile que já não corresponde, recusa, e a recusa indica como resolver: chamar pull com o mesmo release e sem upgrade_targets, o que reconcilia o lockfile com aquilo para que a Release resolve hoje. A recusa traz também a forma de terminal dessa mesma operação, aggrega pull --release <release>. Qualquer das invocações a resolve; são uma operação acessível a partir de dois sítios, não duas instruções entre as quais escolher. Quando pull termina e a recusa regressa, as duas chamadas resolveram sobre entradas diferentes — na maioria dos casos catalog_dirs dado a uma e não à outra, ou uma configuração do espaço de trabalho editada entre elas — e a recusa di-lo: chamem-se ambas com as mesmas.

validate e describe, quando recebem apenas um release, ficam sujeitos ao mesmo lockfile. Perante um lockfile que já não corresponde àquilo para que a Release resolve, cada um recusa em vez de responder, com um texto que contém a paragem por desvio com que build recusa e a mesma forma de a resolver — tal como aggrega validate --release e aggrega inspect --closure recusam num terminal. Com um lockfile que corresponde, ou sem nenhum, cada um responde como responderia de outro modo.

Pedir a uma build que resolva primeiro as suas dependências

Envie-se auto_pull e a build resolve antes de renderizar. Executa a mesma resolução que pull executa — a própria operação, não uma segunda escrita para uma build, pelo que um espaço de trabalho preenchido por uma build e um preenchido por uma chamada pull ficam preenchidos de forma idêntica — escreve o lockfile da Release e depois renderiza contra o que escreveu. Esse passo alcança um registo e escreve, o que mais nada em build faz além de write, e write não alcança nenhum registo — por isso está desligado a menos que seja pedido.

Responde às duas recusas acima sem sair do protocolo. Uma Release que ninguém resolveu ainda renderiza a partir das fixações que por acaso existam e recusa as restantes; um lockfile que divergiu para a build por completo. Enviar auto_pull resolve primeiro e renderiza contra um lockfile derivado do fecho a que esta build respeita, pelo que ambos os casos regressam como uma renderização e não como algo a ir corrigir. Quando se querem a resolução e a renderização como passos separados — para ler o que foi fixado antes de o renderizar — chame-se pull e depois build, que são as mesmas duas operações com uma inspeção pelo meio.

Uma chamada renderiza a Release uma vez. Descobrir que referências remotas uma Release consome é em si uma renderização, pelo que uma resolução já renderizou a Release a que a build respeita — contra as próprias fixações que acabou de escrever, com todas as barreiras que uma build executa. A build é respondida a partir dessa renderização em vez de a repetir, razão pela qual enviar auto_pull custa uma resolução e não uma segunda renderização. Só uma renderização que terminou é usada assim: quando uma resolução fixou as suas dependências mas não conseguiu terminar a descoberta das referências externas, a build renderiza por si contra as fixações que foram efetivamente gravadas, e uma referência não fixada interrompe-a então pelo nome, em vez de regressar como uma lista de ficheiros aquém do que uma build emite.

O que regressa diz o que foi resolvido. Uma build que preencheu traz dependency_resolution na sua resposta, na forma com que pull responde: o lockfile que escreveu, cada referência que a resolução alcançou com a versão para que cada uma resolveu e de onde a resolução desta build a obteve, as contagens que o lockfile contém depois, e o relato que a própria resolução faz de si, linha a linha. Uma build que não preencheu não traz esse campo de todo, pelo que a sua presença é a forma de distinguir as duas sem ler o disco. Os ficheiros renderizados são reportados exatamente como em qualquer outra build, e continuam a ser devolvidos em memória a menos que a chamada tenha recebido também write — resolver escreve o lockfile e a cache de artefactos, nunca um artefacto.

Um espaço de trabalho pode pedi-lo de forma permanente, e uma chamada não o pode desligar. A própria definição auto_pull do espaço de trabalho liga o mesmo passo para todas as builds nesse espaço de trabalho, e auto_pull numa chamada soma-se a essa definição em vez de a sobrepor: qualquer um dos dois basta, e não há nenhum argumento que suprima uma resolução que o espaço de trabalho pediu. É da mesma forma que a definição e aggrega build --auto-pull se combinam num terminal, pelo que um espaço de trabalho responde da mesma forma seja qual for a superfície por onde chega uma build.

A recusa é reportada e não absorvida, e com os providers que este binário traz uma recusa para a renderização: o provider que pediu a referência devolve a recusa, pelo que a chamada responde com essa falha e não devolve ficheiros. A referência é indicada onde um leitor pode agir sobre ela, juntamente com o comando que a fixa: aggrega pull --release <path>. A mesma fixação está acessível nesta superfície como a ferramenta pull, descrita em Resolver aquilo de que uma Release depende abaixo, pelo que um assistente que encontre esta recusa pode agir sobre ela sem sair do protocolo. Uma renderização totalmente fixada não diz nada sobre nada disto. Consulte-se aggrega pull para saber o que a fixação obtém e regista, e aggrega build, onde uma referência não fixada é reportada e interrompe a execução da mesma forma.

Escrever os artefactos onde aggrega build os escreve

Envie-se write e a renderização terminada é também escrita em dist/ na raiz do espaço de trabalho, onde aggrega build a escreve. O diretório é o que a linha de comandos compõe sob a mesma raiz do espaço de trabalho, e a escrita é a que ela executa, pelo que, para uma Release num espaço de trabalho, aggrega build, o aggrega/build do servidor de linguagem sem indicar outputParent e esta chamada escrevem uma única árvore, byte a byte, e indicam esse diretório da mesma forma — a linha final do comando, o outputDirectory do servidor de linguagem e o output_dir desta resposta. Um dist que seja uma ligação que sai do espaço de trabalho é recusado antes de se remover ou escrever o que quer que seja nele, tal como num terminal. Se for omitido, que é a predefinição, os artefactos são devolvidos em memória e nada é escrito.

A raiz do espaço de trabalho é a da própria chamada. Em entrada e saída padrão, é a raiz do espaço de trabalho que a chamada resolveu, como Em que espaço de trabalho é respondida uma chamada expõe: a raiz que workspace_root indica, caso contrário a raiz com que o servidor foi lançado, caso contrário o espaço de trabalho encontrado a partir do diretório em que o servidor foi iniciado — e, quando uma Release indicada por um caminho absoluto leva a chamada para o espaço de trabalho dessa Release, a raiz desse espaço de trabalho. É a raiz sob a qual aggrega build escreve para a mesma Release e a mesma raiz indicada, pelo que a pasta em que o servidor por acaso corre só recebe um dist quando essa pasta é a raiz que a chamada resolveu, tal como aconteceria num terminal aberto aí. Por HTTP, é o espaço de trabalho que o servidor serve, e nada é escrito fora dele.

Escrever alcança o espaço de trabalho, pelo que, por HTTP, precisa de aggrega:workspace-write. Uma chamada a que se enviou write alcança o espaço de trabalho nessa chamada, exatamente como uma build que resolve primeiro as suas dependências: uma credencial que traga apenas aggrega:read recebe 403 indicando aggrega:workspace-write, e nada é escrito, e um servidor cujo mcp.deny_reach indique workspace recusa a chamada indicando essa definição. A ferramenta continua na lista de ferramentas de todos os chamadores, e uma build a que não se enviou write continua disponível a um chamador com âmbito de leitura.

Escreve em último lugar. Com auto_pull também, a chamada resolve, renderiza e depois escreve, por esta ordem. Uma chamada recusada em qualquer ponto anterior — a sua Release, o seu espaço de trabalho, um diretório de catálogo, a resolução, a renderização — não escreve nenhum artefacto.

A resposta indica o que foi escrito. output_dir é o diretório — completo em entrada e saída padrão, dist por HTTP — e files lista cada ficheiro escrito, relativo a ele, com o seu conteúdo em response_format: detailed e só o seu caminho em concise; o texto diz quantos ficheiros foram escritos e onde. Uma chamada a que não se enviou write não traz output_dir, pelo que a sua ausência é a forma de saber que nada foi escrito. Uma escrita que falha depois de a renderização terminar — numa raiz de espaço de trabalho onde ninguém pode escrever, por exemplo — responde como uma falha que indica o diretório e a causa, e não lista nenhum ficheiro como escrito: parte da escrita pode estar em disco, e indicar os ficheiros renderizados como escritos afirmaria mais do que aconteceu.

Nenhum argumento indica um diretório, e nenhum pede um rastreio. O destino dos artefactos é decidido pelo espaço de trabalho que a chamada resolveu, nunca pela chamada, e uma build escrita a partir daqui não deixa nenhum diretório .trace junto à sua saída; uma build com rastreio é aggrega build --trace.

O que uma build diz além dos seus ficheiros

Uma build traz cada aviso que levantou, na própria resposta. São as constatações que aggrega build imprime enquanto trabalha — um nome a uma única edição de distância de um declarado, um parâmetro que nada lê, um destino que não consegue respeitar um campo escrito pelo autor, um veredicto de governação que não interrompe a build, um diretório de fronteira que uma Release herdou da Release que estende e que se resolve para o mesmo caminho, uma propriedade que um Component ou uma Feature alcançado pela Release declara tanto no pilar values como no pilar infra. Nenhum deles altera o resultado: uma build que traz avisos teve sucesso na mesma, e os ficheiros que devolve são os ficheiros que produziu. Chegam pela ordem em que um terminal os imprime, pelo que quem compara os dois encontra uma única sequência e não duas: primeiro tudo o que a renderização levantou, pela ordem em que o levantou, depois as constatações sobre a Release e o que ela alcança, que aggrega build imprime assim que a renderização termina, e por último, numa build que recebeu write, o aviso que indica cada ficheiro que a escrita encontrou junto aos seus e que não escreveu, e que deixa no lugar — o mesmo que aggrega build imprime depois de escrever os seus ficheiros (Ficheiros que a build não escreveu).

Estão na resposta e não apenas no texto de resumo porque um assistente que conduz esta superfície não lê nenhum terminal, e uma constatação de que ninguém é informado é uma constatação que não foi feita. Cada uma traz uma severity — warn para algo que exige atenção, info para uma observação registada — e uma message; um code quando a sua classe atribui um, para que se possa reagir a uma condição específica sem comparar texto; e um key_path que indica a chave no documento escrito pelo autor a que a constatação respeita, quando respeita a uma. Uma constatação sobre a forma da topologia implementada não indica chave nenhuma, porque as suas coordenadas são as da implementação e não as de um documento, e diz na sua mensagem a que respeita.

Dois tipos de constatação que um terminal imprime chegam a esta resposta noutro sítio que não advisories, porque cada um tem um lugar que diz mais. Um marcador de descontinuação registado está em deprecations, quer o lockfile o tenha registado para uma referência fixada, quer o registo de confiança dos plugins junto a ele o tenha registado para um plugin anexado numa função que devolve um veredicto de aceitar ou rejeitar. describe de uma Release indica o mesmo conjunto nas suas próprias deprecations, e validate de uma Release entre as suas notices, cada um deixando o veredicto como está; um registo de confiança que existe e não pode ser lido faz recusar qualquer das duas chamadas em vez de passar por um que não regista nada. Um pai de quem uma entidade herda e que não pôde ser resolvido interrompe a build, pelo que é indicado no texto da recusa e não listado como uma constatação que não alterou nada. Um tipo é limitado pelo que esta ferramenta carrega e não pelo que a sua resposta traz: aggrega build carrega todos os diretórios de catálogo configurados antes de resolver uma Release, e um aviso sobre uma forma de catálogo descontinuada viria desse carregamento, enquanto esta ferramenta só lê o que a Release alcança e não faz tal carregamento, pelo que não reporta tal aviso. Nenhuma build levanta um atualmente, pelo que as duas reportam as mesmas constatações.

Uma Release que não levanta nada não diz nada: a chave está ausente e não presente e vazia, pelo que a sua presença, por si só, indica que há algo para ler.

O que uma build recusada devolve

Uma build que recusa responde nos mesmos campos em que responde uma build que teve êxito, preenchidos até onde a execução chegou. Regressa marcada como falha com a correção como texto, e o conteúdo estruturado fica ao lado desse texto em vez de ser substituído por ele. Uma recusa levantada enquanto a Release renderiza lê-se nas palavras do compilador, como Uma recusa levantada durante a renderização abaixo descreve, e acrescenta um campo próprio. Os avisos estão nela: as fases que correram levantaram o que levantaram, e essas são as constatações sobre as quais é preciso agir para ultrapassar a recusa, pelo que chegam como entradas que se podem comparar e não como prosa que seria preciso analisar. deprecations e declined_external_inputs estão nela pela mesma razão — um marcador registado é reportado porque foi registado um marcador, e uma referência recusada porque uma referência foi recusada, e nenhum desses factos é consequência da forma como a execução terminou.

files não reporta nada numa recusa, e não é o campo de onde ler o resultado. Nada foi emitido, pelo que não há artefactos a indicar. Não se tome uma decisão com base em a chave estar presente: é reportada de qualquer forma, e um files vazio não consegue, por si, distinguir uma build que recusou de uma que correu e não emitiu nada. Leia-se a marca de falha no resultado — esse é o discriminador próprio do protocolo — e leia-se files pelo que é, a lista do que foi renderizado, e também escrito quando a chamada recebeu write.

O que limita os avisos numa recusa é até onde a execução chegou, não o que a resposta é capaz de trazer. Uma recusa de uma verificação que corre antes de a Release estar resolvida — uma entrada fixada na cache já não corresponde ao digest registado para ela e nenhum diretório de catálogo contém os bytes fixados, ou aquilo de que a Release depende não pôde ser resolvido — não reporta nenhum aviso, porque nada tinha sido levantado ainda. As constatações sobre a forma como uma Release se compõe com a Release que estende são levantadas no momento em que é resolvida, antes de todas as verificações seguintes, pelo que todas as recusas posteriores as trazem: o Manifest faz corresponder um tipo a uma recipe que não o implementa, uma entidade que a Release alcança não satisfaz o seu esquema, o lockfile já não corresponde àquilo para que a Release resolve. As constatações próprias da renderização são levantadas à medida que a renderização corre, pelo que uma recusa de uma dessas verificações anteriores não traz nenhuma delas, e uma recusa da renderização traz tudo o que foi levantado antes dela. Por isso, leia-se advisories numa recusa exatamente como num êxito: o que esta execução encontrou, pela ordem em que um terminal o imprime.

Uma recusa porque uma entidade herda de um pai que não pôde ser resolvido indica cada uma dessas heranças no seu texto, nas palavras que aggrega build imprime para ela, para que se saiba qual reparar. Esse detalhe é a razão pela qual a build parou, e é por isso que está no texto e não entre as constatações que não alteraram nada; as constatações de composição levantadas antes dela estão em advisories, como em qualquer recusa posterior.

Um diretório de catálogo que a Release lê e que não pode ser percorrido é recusado antes de qualquer escrita, tal como aggrega build o recusa. Trata-se de um diretório que a chamada indica em catalog_dirs e que não existe, tal como aggrega build recusa um diretório --catalog que não existe, ou de um que existe e não pode ser lido. aggrega build carrega todos os diretórios que a Release lê antes de resolver a Release, e para num que não consegue percorrer; build percorre os mesmos diretórios primeiro, sem ler nenhum documento neles, antes de qualquer resolução de dependências e antes da renderização — pelo que uma build a que se enviou auto_pull não escreve nenhum lockfile, e nada é renderizado. O texto indica o diretório tal como a linha de comandos o reporta, numa linha: o diretório, catalog load e o motivo dado pelo sistema de ficheiros. O conteúdo estruturado indica a Release, com um files vazio e nenhuma constatação, porque nada tinha corrido. Um diretório que a configuração do espaço de trabalho lista e que não é um diretório — nada existe lá, por exemplo — é recusado antes desse percurso, da mesma forma, com o texto a incluir a recusa que aggrega build lhe dá, indicando a entrada e o ficheiro de configuração e a linha que a listam (De onde são lidas as entidades locais). Um diretório de catálogo que contenha uma ligação que sai do diretório dentro do qual as suas leituras têm de ficar é recusado no mesmo momento, sem nada escrito, com o texto a indicar a ligação e para onde conduz — aggrega build recusa-o da mesma forma.

Um exemplo concreto, para que as metades fiquem claras. Uma Release que declara um parâmetro que nenhuma referência lê, e cuja renderização depois não consegue terminar, regressa como uma falha cujo texto traz a recusa da renderização e cujo conteúdo estruturado traz o aviso de parâmetro não lido com a sua severity, message, code e key_path — a mesma entrada, com os mesmos valores, que a mesma Release reporta na resposta quando a renderização termina — junto à entrada refusal relativa ao que parou a renderização. Uma Release que estende outra e herda um diretório de fronteira sem variável de template, cujo Manifest faz corresponder um tipo a uma recipe que não o implementa, regressa como essa recusa com uma entrada de advisories por diretório herdado, cada uma com code inherited-boundary-directory-is-literal. Uma Release cujas dependências não podem ser resolvidas, num espaço de trabalho cujos diretórios de catálogo listados existem todos, regressa como uma falha sem chave advisories nenhuma, porque nada tinha sido levantado quando parou.

Uma recusa levantada durante a renderização

Uma Release que o compilador recusa enquanto renderiza — um Workload que indica um slot que o seu Component não declara, uma asserção que falha, um template que não pode ser avaliado — regressa com a recusa nas palavras do compilador e com todas as causas por baixo dela, as palavras que cli-build devolve para a mesma Release: o nó a ser renderizado, depois o que nele recusou. Quando a recusa indica uma condição registada, o texto acrescenta o nome dessa condição — o código curto e o código descritivo para comparação — como explain-error faria. O texto começa por dizer que fase recusou: The build failed during rendering; nothing was written to disk. para uma recusa levantada pela renderização, e The build refused before rendering anything; nothing was written to disk. para uma levantada pela execução do compilador antes de qualquer renderização — a composição do grafo a partir do qual a renderização trabalha a recusar, ou uma asserção que um Component ou uma Feature declaram.

O conteúdo estruturado traz a mesma recusa como uma entrada, refusal, para que um chamador que tenha de alterar um documento leia qual, e onde, sem analisar a frase:

  • file — o documento para que a recusa aponta: a Recipe de um Workload, a Recipe ou FeatureRecipe que declara uma asserção que falha, a Release ou o Aggregate que escreveu uma entrada que a composição do grafo recusa, ou o Aggregate da Release no caso de uma recusa que não aponta para nenhum documento.
  • key_path — a chave aí, quando a recusa indica uma: .spec.workload para uma recusa sobre um Workload, a própria chave da asserção em .spec.assertions para uma asserção que falha, a própria chave da entrada para a recusa de uma entrada. Uma recusa sobre um Workload é colocada na sua chave workload e não mais fina, porque o Workload que uma verificação avalia é o que o seu template produziu, e um template escreve linhas que o seu autor nunca escreveu; os caminhos que a recusa indica dentro desse Workload renderizado ficam na sua message.
  • line e column — a posição dessa chave, contada a partir de um, com a coluna em unidades UTF-16. Ausentes quando a recusa não indica chave ou o documento não a contém: só se dá uma posição quando foi encontrada.
  • severity — halt, a severidade da constatação que parou uma build.
  • code e short_code — os dois identificadores da condição, quando a recusa indica uma condição registada.
  • message — o texto da recusa, exatamente como aparece no texto da resposta.
  • findings — presente apenas quando a recusa junta várias constatações, como a composição do grafo faz com todas as violações que encontrou: uma entrada por constatação, pela ordem em que a recusa as enuncia, cada uma nesta mesma forma — o seu próprio file, key_path, line, column, severity, code, short_code e message. Os campos próprios da recusa indicam então para onde aponta a sua primeira constatação, e a sua message traz todas as constatações, tal como o texto; a linha de comandos imprime cada constatação como um diagnóstico próprio.

A entrada está presente sempre que a própria execução do compilador recusou — durante a renderização, ou antes de renderizar: na composição do grafo, ou numa asserção que um Component ou uma Feature declaram, que não indica nenhum documento, pelo que a sua entrada indica o Aggregate. Uma build que tem êxito não traz nenhuma, tal como uma recusada por uma verificação que corre antes de o compilador arrancar — o lockfile, as correspondências do Manifest, aquilo de que a Release depende — cuja recusa é apenas o texto. Um valor que um autor declarou sensível é retido da recusa onde o compilador o levanta, pelo que a entrada e o texto trazem o que cli-build e o terminal trazem — ver o que uma recusa diz sobre um valor declarado.

Resolver aquilo de que uma Release depende

pull resolve as dependências de catálogo e de origem de uma Release para a cache local e escreve o lockfile dessa Release. Está nesta superfície por uma razão que vale a pena enunciar: as duas recusas acima — uma renderização que recusou uma referência externa não fixada, e uma build que parou porque o lockfile já não corresponde àquilo para que a Release resolve — são ambas resolvidas pela fixação, e um assistente que tenha de pedir ao utilizador que execute um comando não tem forma de as resolver por si. Leia-se O que um assistente pode fazer sem perguntar primeiro para saber o que escreve e até onde isso chega.

Passe-se release, o caminho da Release, absoluto ou relativo à raiz do espaço de trabalho — o mesmo contrato que todos os outros argumentos de caminho daqui usam. workspace_root e catalog_dirs sobrepõem-se à descoberta do espaço de trabalho e do catálogo exatamente como em build. Ambos valem num servidor alcançado em entrada e saída padrão; por HTTPS esses dois argumentos são recusados e o caminho tem de resolver dentro do espaço de trabalho que o processo serve, como Um processo, um espaço de trabalho expõe.

Por predefinição, reconcilia em vez de resolver tudo de novo. Uma fixação que o lockfile já regista é respeitada e obtida nessa versão, e recusada em vez de refixada em silêncio se o registo já não servir esses bytes. Uma referência sem fixação — recém-adicionada, ou removida do lockfile à mão — é resolvida de raiz e acrescentada. Uma referência que já não está entre as dependências resolvidas é eliminada. Um conjunto de dependências inalterado deixa, por isso, o ficheiro idêntico byte a byte, incluindo o seu carimbo temporal registado, pelo que uma chamada que não alterou nenhuma fixação não produz nenhuma diferença para quem revir o espaço de trabalho depois.

verify compara, e deixa o lockfile como está. Verifica o lockfile registado contra a resolução que a chamada de reconciliação acima faria agora, respeitando as fixações registadas exatamente como essa chamada, e regressa como falha em caso de divergência, ou quando não há lockfile com que comparar — pelo que é a forma de um assistente descobrir se a fixação é necessária antes de algo reescrever o lockfile. Nada do que essa chamada regista é escrito — nem o lockfile, nem as identidades de plugins registadas junto a ele, nem um entity.lock — enquanto a cache de conteúdo é lida e preenchida exatamente como essa chamada a lê e preenche. Reporta também a toolchain que o lockfile regista: a versão do compilador que escreveu o ficheiro e a versão de cada plugin nuclear que esse compilador trazia. Isto é reportado para auditoria e nunca comparado com o binário em execução, porque a toolchain não faz parte do que o lockfile fixa e verificá-la fixaria o compilador por tabela — uma diferença de toolchain não é divergência.

upgrade_targets resolve de novo as referências indicadas, e mais nada. Dê-se-lhe um ou mais URIs de entidade na forma simples escrita pelo autor — core/database, não uma forma com versão. Cada fixação indicada é descartada e resolvida de novo para a versão mais alta disponível, enquanto todas as outras fixações e as entradas externas registadas se mantêm inalteradas. Um URI que não corresponda nem a uma fixação registada nem a um anexo configurado é recusado em vez de ignorado.

Deliberadamente, não há nenhum argumento que resolva tudo de novo de uma só vez. A linha de comandos tem essa forma, e descarta o lockfile inteiro antes de resolver de novo a partir do estado atual do registo. Nesta superfície o argumento não existe, pelo que a chamada não pode sequer ser composta, em vez de ser aceite e depois recusada: ninguém está a observar um fluxo de protocolo, pelo que um descarte por atacado não tem quem o confirme. Quando se quiser, e apenas em entrada e saída padrão, cli-pull executa o comando, que é a superfície onde está presente uma pessoa; um chamador que alcance este servidor por HTTP executa-o, em vez disso, num terminal no anfitrião. verify não pode ser combinado com upgrade_targets — um deixa o lockfile como está e o outro reescreve-o — nem com pin_sources, seja qual for o valor que traga: esse argumento decide se uma resolução regista as fixações que faltam a um entity.lock ou recusa por causa delas, e uma comparação não escreve nenhum entity.lock, pelo que não faria nenhuma das duas coisas. Uma chamada que envie qualquer destes pares é recusada antes de se resolver o que quer que seja, com uma frase que indica o par. O esquema anunciado da ferramenta não enuncia estas duas exclusões, porque um cliente que represente uma pode lê-la como uma exigência de enviar verify; é na recusa que um cliente as aprende. A linha de comandos e o daemon recusam os mesmos pares.

O resultado indica o que foi resolvido, e não apenas que algo foi. Traz o lockfile que escreveu ou com que comparou; resolved, cada referência que a resolução alcançou com a versão para que cada uma resolveu, o tipo que um autor escreve quando a resolução regista um, e a sua source — de onde esta execução obteve a referência, na palavra que aggrega pull --detail imprime para a mesma resolução: fetched-fresh, cache-reuse, local, in-binary ou external; contagens dos artefactos de origem, entradas externas e identidades de plugins de confiança que o lockfile contém depois; e diagnostics, o relato que a própria resolução faz de si, pela ordem em que levantou cada linha — que fixação foi reutilizada, que assinatura foi verificada, que versão foi ignorada por ter sido retirada. Essas linhas chegam a um terminal quando se executa o comando; aqui estão na resposta, porque um chamador que não lê nenhum terminal não tem outra forma de as receber. verified só está presente numa comparação, pelo que a sua ausência é a forma de distinguir uma execução que escreveu de uma que apenas comparou. Uma source descreve esta execução nesta máquina, pelo que o lockfile não a regista, e describe, que reporta aquilo de que uma Release depende, não indica nenhuma.

Uma recusa responde nos mesmos campos, preenchidos até onde a execução chegou. Depois de calculada a resolução, resolved é incluído seja qual for o veredicto — sobretudo num veredicto de divergência, já que essa é a recusa em que um chamador tem de decidir o que alterar. Uma recusa anterior a esse ponto, como um caminho de Release que não resolve, traz a correção como texto e nenhuma resolução, porque não havia nenhuma a trazer.

Quando as fixações estão completas e as entradas externas não, a chamada tem êxito na mesma e di-lo. Descobrir que entradas externas uma Release consome é uma renderização, e uma renderização pode falhar depois de as fixações de dependências já estarem corretas e em disco. Reportar a chamada inteira como falhada diria ao utilizador para refazer trabalho que está certo, pelo que incomplete_external_inputs é definido no resultado com êxito, indicando o que parou: as fixações de dependências estão completas, as fixações de entradas externas podem não estar.

Esta é a ferramenta mais lenta daqui, e a reconciliação sem alterações não é um atalho rápido. Uma resolução paga o seu custo total para estabelecer que um conjunto de dependências está inalterado, pelo que uma chamada que não reescreve nada custa o mesmo que uma primeira resolução — numa Release pequena, segundos e não milissegundos, e cresce com a dimensão do conjunto de dependências. Um verify é a mais barata das duas formas, porque uma comparação salta a descida pelas origens de cada componente que uma execução que escreve faz. Se o cliente impõe um tempo limite por chamada, é com esta ferramenta que o deve verificar. Pedir para ser informado do andamento, abaixo, significa que algo chega enquanto a chamada corre, em vez de nada até ela terminar — o que responde a um tempo limite de inatividade no cliente, ou no que quer que esteja entre o utilizador e um servidor alcançado por HTTP, mas não a um limite à duração total de uma chamada.

Uma entidade cujo entity.lock não regista fixação para uma entrada que lê recusa o pull, e a recusa indica o passo que a regista. Uma Recipe ou FeatureRecipe que a Release compila a partir dos diretórios de catálogo e que lê uma origem remota escrita por extenso, ou importa um ficheiro através dos seus artefactos, deve já trazer essas fixações junto a si — o seu autor regista-as com pin, abaixo. pin_sources pede a esta chamada que execute esse passo em nome do autor sobre cada uma dessas entidades em vez de recusar, escrevendo o entity.lock junto a cada uma; é o mesmo passo que a ferramenta pin executa, e escreve os mesmos bytes. Omita-se e decide o pin_sources_at_pull do espaço de trabalho; envie-se e decide em qualquer dos sentidos, pelo que pin_sources: false recusa mesmo num espaço de trabalho configurado para fixar. Uma entidade que a resolução alcançou na cache e não num dos diretórios de catálogo não tem aqui um sítio gravável e nunca é fixada por esta chamada.

Fixar as entradas próprias de uma entidade

pin regista, no entity.lock junto a uma Recipe ou FeatureRecipe, a fixação de conteúdo de cada entrada que a entidade lê de fora do seu próprio documento: uma origem remota cujas coordenadas estão escritas por extenso, e um ficheiro que uma entrada de artefactos importa. É o mesmo passo que aggrega pin executa num terminal, e o lock que escreve é idêntico byte a byte ao que esse comando escreve. Passe-se entity, o documento da entidade, absoluto ou relativo à raiz do espaço de trabalho segundo o mesmo contrato que todos os outros argumentos de caminho daqui seguem; por HTTPS tem de resolver dentro do espaço de trabalho que o processo serve.

Não se indica nenhuma Release, porque nenhuma é necessária. Uma origem cujas coordenadas não trazem template indica um único artefacto para todas as Releases que usam a entidade, pelo que o passo a resolve e fixa sem nada que uma Release forneça. Uma origem cujas coordenadas vêm de um template não é fixada aqui: o artefacto que indica é decidido por cada Release, e pull fixa cada identidade para que resolve no lockfile dessa Release.

O resultado diz o que o passo fez ao lock. Traz a entity, o seu kind e name, e pinnable, que é false para um tipo que não lê nada que um lock registe — um Component ou uma Feature — caso em que nada junto à entidade foi tocado e os outros campos estão ausentes. Caso contrário, traz o lock que escreveu, changed, false quando o lock já registava todas as fixações e ficou idêntico byte a byte, removed quando a entidade já não lê nada que um lock registe e o seu lock foi apagado, e pins, uma entrada por classe de fixação com a contagem que o lock contém depois. dry_run responde com o lock que o passo escreveria como content e não escreve nada junto à entidade; a cache de conteúdo continua a ser preenchida, porque as entradas são resolvidas exatamente como seriam de outro modo.

Escreve dentro do espaço de trabalho e alcança os anfitriões que as origens da entidade indicam — um repositório de charts, um anfitrião Git, um URL — pelo que, por HTTP, é admitido a uma credencial que traga o âmbito que admite pull, e recusado a uma que só pode ler. Em entrada e saída padrão, a mesma capacidade está também acessível como cli-pin, que executa o comando; por HTTP essa ferramenta não existe.

Ser informado do andamento de uma chamada longa

Uma chamada reporta o seu progresso quando se pede para ser informado, e pedi-lo é um campo. Coloque-se progressToken no _meta da chamada — uma string ou um número, à escolha. Regressa em cada relatório exatamente como foi escrito, e é a única coisa num relatório que aponta para a chamada: um relatório não responde a nada, por isso não traz id. Não se envie token, ou envie-se como null, e nada muda — a chamada é respondida da mesma forma que sem ele. Um token de qualquer outra forma é recusado, antes de a chamada fazer o que quer que seja, indicando as duas formas que pode ter, em vez de ser ignorado: um chamador que pediu para ser informado e depois se depara com silêncio não tem nada sobre o qual agir.

O que chega é notifications/progress, com o token e uma contagem que sobe a cada um. Não há total nem mensagem, e nenhum dos dois é uma omissão à espera de trabalho: o que o trabalho reporta é que entrou noutra fase, pelo que um total só poderia ser inventado e uma frase só poderia ser composta aqui em vez de transmitida. Desenhe-se um indicador indeterminado a partir da contagem crescente; não há fração com que encher uma barra.

Por HTTP, a resposta passa a ser um fluxo de eventos, e só depois de algo ter efetivamente reportado. É servida como text/event-stream, marcada para não ser guardada em cache e com X-Accel-Buffering: no para um intermediário que, de outro modo, reteria todos os eventos até o trabalho terminar e transformaria o fluxo numa única resposta lenta. Cada relatório é um evento, e a própria resposta da chamada é o último evento antes de o fluxo fechar. Enquanto o trabalho está calado, o fluxo traz uma linha de comentário a intervalos, que chega ao que quer que esteja pelo meio como bytes numa ligação viva e chega ao cliente como nada. Uma chamada que pediu progresso e chegou a trabalho que não reporta nenhum continua a ser respondida com um único objeto JSON, porque o que abre o fluxo é o primeiro relatório e não o token.

Num fluxo, leia-se o resultado a partir desse último evento e não do código de estado. O estado e os cabeçalhos são escritos quando o fluxo abre, o que acontece antes de o trabalho estar feito, pelo que uma chamada que reporta e depois recusa traz a sua recusa como último evento sob o estado já enviado. Fechar a ligação a meio do fluxo termina o trabalho e nada mais é escrito para ele, exatamente como Como termina uma chamada descreve para qualquer outra chamada.

Em entrada e saída padrão, os relatórios são linhas antes da linha de resposta, enquadradas como qualquer outra mensagem nesse fluxo — um objeto JSON por linha, pela ordem em que foram escritos — e a linha de resposta segue-se-lhes. Nada é reportado depois de uma chamada terminar, em nenhum dos transportes.

Resolver as dependências de uma Release é o que reporta aqui. pull reporta cada vez que a resolução entra numa fase. build só reporta quando está a resolver primeiro — porque se enviou auto_pull, ou porque a própria definição do espaço de trabalho pede a todas as builds nele que resolvam — já que o relatório pertence a esse passo: uma build que renderiza a partir das fixações que já tem não alcança nada e não reporta nada, pelo que um token nessa chamada não altera nada na forma como é respondida. Qualquer chamada reporta também cada passo em que o seu trabalho entra e pelo qual espera — ler um registo, obter um artefacto ou um pacote de documentação, compilar um plugin pela primeira vez —, os passos que a linha de comandos mostra a uma pessoa ao lado do seu indicador de atividade. Uma chamada cujo trabalho não espera por nenhum deles não reporta nada, o que é inofensivo e não um erro: a resposta é a que se teria recebido sem ele.

Perguntar que ligação está escrita num sítio de um documento

connection-at-position responde à pergunta que antecede a metade relativa a ligações das duas ferramentas acima, para quando se tem um sítio num documento e não um nó num grafo — uma linha que se está a ver num Aggregate ou numa Release. Passe-se file, o documento, relativo à raiz do espaço de trabalho ou absoluto e lido do disco da forma como insertion-point lê um; position, uma line e um character, ambos contados a partir de zero, medidos nas unidades que position_encoding indica exatamente como insertion-point lê esse argumento; e o release cujo grafo compilado regista as ligações. A Release é obrigatória também para um sítio no Aggregate: um nó de grafo e uma ligação só existem num grafo compilado.

A resposta é uma de duas metades. Quando o sítio está na entrada de uma ligação, traz graphNode e connection — o seu socket, o seu alias e o document em que o sítio foi lido — que são exatamente o que attach-candidates aceita junto a graph_node e release, e o que attachment-container aceita para indicar onde vai um anexo nessa ligação; esse contentor fica dentro da própria entrada em que o sítio caiu. Caso contrário, traz noConnectionReason, de um conjunto fechado: no-connection-entry (o sítio não está em nenhuma entrada em que se escreva um anexo), feature-created-connection (o sítio está na entrada da Release para uma ligação que uma Feature estabeleceu) ou unknown-connection (o sítio está numa entrada que a Release escreve para uma ligação que o grafo compilado não contém). A resposta legível enuncia o motivo por palavras.

Um sítio em qualquer ponto dentro de uma entrada está dentro dela — no alias, no seu target, dentro das suas features — e prevalece a entrada mais interior quando as entradas se aninham. Um sítio na própria chave de um socket, acima dos aliases sob ela, não está dentro de nenhum deles. As entradas são as que o grafo compilado regista: no Aggregate, cada ligação que um componente estabelece, na sua entrada sob o alias da ligação no documento em que o componente foi escrito, que, para um componente contribuído por um módulo importado, é o próprio documento desse módulo; na Release, cada entrada por aresta que ela escreve. Uma ligação escrita como uma lista de destinos, e uma que o próprio bloco de dependências de uma Feature estabelece, não trazem nenhuma entrada em que se escreva um anexo. Se uma chave é uma ligação nunca é deduzido a partir do nome que tem.

Responde e para. Não escreve nada em ficheiro algum. Um documento que não está no espaço de trabalho, não pode ser lido ou não é YAML bem formado regressa como um resultado falhado que indica o que alterar, tal como acontece com insertion-point; o mesmo acontece com um sítio a que falta a line ou o character, e com um position_encoding fora dos três.

Perguntar a que contentor pertence um anexo

attachment-container responde à pergunta entre uma resposta de candidatura e um ponto de inserção. Já se decidiu o que anexar a um nó; antes de se poder perguntar onde, num ficheiro, o escrever, é preciso saber que ficheiro e que contentor dentro dele. Passe-se graph_node — um id de nó num grafo compilado, tal como o grafo o identifica — e o release cujo grafo é. Ambos são obrigatórios: um id de nó é uma chave do grafo de uma Release e não significa nada sem ela.

Não se monte esse caminho à mão. O id de um nó e o caminho de subsistema que o envolve são ambos escritos com pontos entre as suas partes, e um ponto é um carácter legal num nome que um autor escreve — pelo que, de fora do documento, não há forma de distinguir um ponto estrutural de um dentro de um nome. Um caminho composto à mão leria corretamente e endereçaria uma chave que ninguém escreveu, e a edição que se seguisse criaria essa chave em vez de ser recusada. Pior, um id de nó não traz qualquer vestígio do subsistema que o envolve: um componente escrito dentro de subsystems.billing.subsystems.payments é identificado como ledger, exatamente como seria um componente de primeiro nível. Peça-se o contentor.

A resposta traz node, o nó a que respeita; file, o documento em que esse nó foi escrito; e container, o caminho estrutural a partir da raiz desse documento como uma lista de segmentos — ["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. É uma lista e não uma string unida de propósito: um caminho unido teria de ser separado de novo por quem o recebesse, o que reintroduziria a ambiguidade acima uma chamada mais tarde. Passem-se file e container a insertion-point sem alterações.

file faz parte da resposta e não é algo que já se saiba. Um nó contribuído por um módulo importado foi escrito no próprio documento desse módulo sob o nome que o módulo lhe deu, pelo que tanto o ficheiro como o último segmento do contentor diferem de tudo o que se enviou.

Para um anexo numa ligação que o nó estabelece, acrescente-se connection com o seu socket, o seu alias e o seu document, que aqui é obrigatório porque qualquer dos documentos pode conter uma. Com aggregate, a resposta é a própria entrada da ligação no documento em que o nó foi escrito, com o seu bloco features em último lugar; uma ligação que a Release estabeleceu não tem aí entrada e é recusada. Com release, é a entrada por aresta sob a entrada da Release para o nó — ["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"] — reportada quer a Release já escreva essa entrada por aresta quer não, para que insertion-point indique as chaves ainda por escrever; uma Release que não escreve nenhuma entrada para o nó é recusada, já que o sítio onde o nó é colocado não cabe a esta ferramenta decidir. Uma ligação que uma Feature estabeleceu é recusada em qualquer dos documentos.

Responde e para. Não cria nenhum anexo, não escreve nada em ficheiro algum e não compõe texto. Também não decide o que pode ser anexado — isso é attach-candidates. Um nó que o grafo não contém, ou um para o qual não regista nenhum documento, regressa como um resultado falhado que indica o que alterar, em vez de uma resposta com um campo vazio.

Localizar onde pertence uma entrada num documento

insertion-point responde à pergunta que se segue a uma resposta de candidatura. Já se decidiu o que anexar ou ligar; agora é preciso saber onde, no ficheiro, o escrever. Devolve uma posição e as colunas em que indentar, para que se possa aplicar a edição sem analisar o documento por conta própria. Como o que lê é a estrutura própria de um documento e não a forma de um tipo em particular, describe-capabilities indexa-a sob qualquer tipo de entidade a que se restrinja.

Passe-se file — o documento, relativo à raiz do espaço de trabalho ou absoluto, e dentro do espaço de trabalho: um alcançado através de uma ligação que sai dele, para o ficheiro ou para um diretório pelo caminho, não o está, e é recusado em qualquer dos transportes — e container, o caminho estrutural desde a raiz do documento até ao contentor dentro do qual a entrada vai, sendo cada elemento uma chave de mapeamento ou uma posição de sequência escrita em decimal.

O caminho do contentor é fornecido pelo utilizador. A ferramenta lê a estrutura do documento e nunca deduz onde algo pertence a partir do nome que tem, do tipo que traz ou do que parece significar. O utilizador diz qual chave; ela diz onde vão as entradas dessa chave neste documento — que segmentos do caminho o ficheiro já contém, as colunas em que as suas entradas estão e a última linha a que o seu bloco mais interior chega. Para um anexo de Feature num nó de um grafo compilado não é preciso conhecer essa chave: attachment-container acima reporta o documento e o contentor, e ambos vêm para aqui sem alterações.

A resposta é uma position de largura zero, cujos line e character contam ambos a partir de zero; entryIndent e indentStep, as colunas em que escrever; e missingContainerKeys, as chaves de contentor que este documento ainda não contém, da mais exterior para a mais interior, que se escrevem antes da entrada. entryShape reporta se o contentor contém um mapping ou uma sequence, e reporta unknown quando o contentor ainda não existe ou não contém nada, porque o documento não o disse — a forma fica então à escolha. indentStepMeasured diz se o passo foi medido a partir do aninhamento do próprio documento ou é um valor de recurso para um documento que não apresenta nenhum. Quando precededByLineBreak está definido, comece-se o texto com uma quebra de linha: a posição fica no fim da linha a que a entrada se segue, que está dentro do intervalo quer o ficheiro termine numa nova linha quer não, e não perturba nenhum byte já escrito. Leia-se missingContainerKeys mesmo quando se espera que o contentor exista — uma posição aplicada sem as chaves que a têm de preceder produz um documento que deixa de fazer parse.

position_encoding indica as unidades em que o deslocamento de carácter reportado é medido: utf-8, utf-16 ou utf-32. É aqui um argumento porque nenhuma revisão deste protocolo negoceia um, e a predefinição é utf-16, que é o que uma sessão de editor adota quando um cliente não negoceia nada — pelo que um chamador que não indique nada é respondido de forma idêntica em ambas as superfícies. Um valor que não seja nenhum dos três é recusado em vez de silenciosamente substituído pela predefinição, porque deslocamentos medidos de uma forma e aplicados num buffer medido de outra corrompem o documento no primeiro carácter fora do ASCII.

Responde e para. Não escreve nada em ficheiro algum, não compõe texto de entrada e não aplica nenhuma edição; compor o texto e decidir se o aplicar cabe ao utilizador. Um pedido que não endereça um sítio onde possa ir uma entrada regressa como um resultado falhado que indica o que alterar — um documento que não está no espaço de trabalho, não pode ser lido ou não é YAML bem formado; um caminho de contentor sem segmentos ou com um vazio; um caminho que atravessa um escalar, dentro do qual nada pode ser acrescentado; um caminho que chega a uma coleção escrita em estilo flow, onde acrescentar reescreveria bytes que o autor já escreveu em vez de adicionar uma linha; ou um caminho que endereça uma sequência em bloco com algo que não é um dos seus índices. Quando se prefere que a edição seja aplicada em vez de a aplicar por conta própria, Aplicar uma edição delimitada a um documento é a ferramenta que o faz.

Aplicar uma edição delimitada a um documento

edit-document aplica o que as duas ferramentas acima localizam. Uma chamada acrescenta uma entrada sob um contentor, ou define um escalar, e não pode fazer mais nada. Escreve o documento indicado, dentro do espaço de trabalho, pelo que, por HTTPS, precisa de aggrega:workspace-write: um chamador que tenha apenas aggrega:read encontra-a na lista de ferramentas, e uma chamada que faça é recusada indicando esse âmbito.

Indique-se a edição em edit; o conjunto é fechado. add-component acrescenta uma instância de componente sob um contentor de componentes; attach-feature anexa uma Feature ao nó indicado; wire-edge liga uma ligação dentro de um dos sockets desse nó; set-value define um valor nesse nó. Um nome fora destes quatro é recusado em vez de interpretado. Não há nenhuma edição que apague, substitua um bloco já escrito, reordene o que quer que seja ou escreva tal e qual bytes fornecidos — pelo que isto não é um escritor de ficheiros e não pode ser usado como tal.

Passe-se file, o documento — relativo à raiz do espaço de trabalho ou absoluto, e dentro do espaço de trabalho: um fora dele, tal como escrito ou através de uma ligação que sai dele, é recusado em qualquer dos transportes sem nada lido nem escrito; node, o caminho estrutural desde a raiz do documento como uma lista de segmentos; name, a chave sob a qual a entrada é escrita; e value, o que essa entrada traz. node é uma lista pela mesma razão pela qual attachment-container responde com uma: um ponto é legal dentro de um nome que um autor escreve, pelo que um caminho unido poderia endereçar uma chave que ninguém escreveu e a entrada seria criada aí em vez de recusada. Para add-component, o caminho indica o próprio contentor de componentes, porque a entrada acrescentada é o nó; para as outras três, indica o nó a que a edição respeita, e o contentor decorre da edição. socket é lido para wire-edge e ignorado nos restantes casos. O significado de value decorre de edit — a entidade que a entrada pede, o nó para que uma ligação aponta, ou o escalar para que um valor é definido — e é um valor JSON do seu próprio tipo, pelo que um número continua a ser um número, um dígito entre aspas continua a ser texto, e omiti-lo não define nada. Um mapeamento ou uma sequência é recusado, porque escrever um bloco não é uma destas edições.

Cada byte que a edição não toca sobrevive. O documento só é analisado para localizar o contentor e a linha em que o seu bloco termina, pelo que comentários, linhas em branco, estilo de aspas, escalares dobrados e literais e a forma da nova linha final passam todos intactos, e o passo de aninhamento é medido a partir da própria indentação do documento em vez de imposto. O mesmo pedido contra o mesmo documento produz os mesmos bytes.

O resultado tem de ser um documento que se poderia ter escrito à mão, e é disso que a escrita depende. O documento composto é verificado contra o esquema do seu próprio tipo e só chega ao disco se passar. Um pedido que produziria algo que o esquema recusa é recusado, indicando a propriedade que o esquema não admitiria e onde, e o ficheiro fica byte a byte como estava — pelo que uma edição recusada é indistinguível de uma nunca tentada, e pode-se repetir um pedido corrigido contra o documento de partida. Uma entrada que já existe com aquilo que se pediu não produz efeito; uma entrada com esse nome que traga outra coisa é recusada em vez de substituída.

A resposta traz container, o caminho estrutural em que a entrada ficou; created_containers, os níveis de contentor que esta edição teve de criar, do mais exterior para o mais interior e vazio no caso habitual em que o caminho inteiro já existia; e written, o documento que chegou ao disco, vazio quando nada chegou. Leia-se created_containers: uma edição que escreveu discretamente dois blocos aninhados que o documento não continha é, de outro modo, indistinguível de uma que acrescentou uma única entrada a um bloco escrito pelo próprio utilizador.

dry_run faz tudo exceto escrever. O documento editado regressa como content, nada é criado e written fica vazio — para um cliente que mostra o resultado ao autor antes de ser guardado. Todos os outros comportamentos são os da escrita, incluindo a barreira do esquema, pelo que um pedido que a escrita recusaria é também recusado com ele. Sem ele, o documento é escrito e content fica ausente, porque o documento está então em disco e written indica-o.

Se aquilo que se liga é semanticamente admissível — se um socket é um que o produtor declara, ou se a aplicabilidade de uma Feature é satisfeita — não é decidido aqui. É a isso que validate responde.

Em entrada e saída padrão, a mesma capacidade está também acessível como cli-edit-document, que executa o comando e devolve o texto que imprimiu; por HTTP essa ferramenta não existe, e é esta a forma de aceder à capacidade aí.

Transformar uma descrição externa em entidades em rascunho

import converte uma descrição produzida por outra ferramenta — um fluxo exportado de um construtor de agentes, por exemplo — em ficheiros de autoria Aggrega em rascunho. Escreve esses ficheiros no espaço de trabalho que este servidor serve, pelo que, por HTTPS, precisa de aggrega:workspace-write: um chamador que tenha apenas aggrega:read encontra-a na lista de ferramentas, e uma chamada que faça é recusada indicando esse âmbito.

Passe-se source, o ficheiro ou o diretório a converter. É absoluto ou relativo à raiz do espaço de trabalho, o mesmo contrato que todos os outros argumentos de caminho desta superfície usam, e, num servidor alcançado por HTTPS, resolve dentro do espaço de trabalho que esse servidor serve.

Um diretório é lido exatamente nos ficheiros que os padrões de ficheiro do seu importador selecionam. Um chart ou um projeto é um diretório, e source pode indicar um. O importador recebe então os ficheiros dele, a qualquer profundidade, que um dos padrões de ficheiro declarados pelas suas assinaturas seleciona, cada um indicado pelo seu caminho dentro do diretório escrito com barras normais, por ordem ordenada, juntamente com os ficheiros que o seu anexo plugins.importer indica em with.sources, pelos seus nomes base; um ficheiro do diretório e um ficheiro de with.sources com o mesmo nome são recusados, em vez de um esconder o outro. Um importador que não declara padrões de ficheiro lê um único ficheiro e recusa um diretório, sob a condição An importer that declares no file patterns is handed a directory (Um importador que não declara padrões de ficheiro recebe um diretório), e um diretório que não contém nenhum ficheiro que os seus padrões selecionem é também recusado. O diretório fica contido em si próprio onde quer que esteja: uma ligação entre os ficheiros que a importação leria, ou para um diretório, que sai dele é recusada antes de se ler o que quer que seja, e uma ligação para um diretório nunca é seguida — como Um diretório que se importa expõe. Num servidor alcançado por HTTPS, o próprio diretório resolve dentro do espaço de trabalho, pelo que todos os ficheiros lidos dele também.

O importador é um que o catálogo do espaço de trabalho contém, ou um dos importadores nucleares do compilador. A tradução é obra do plugin importador que anuncia o formato da origem: um que o catálogo do espaço de trabalho contém, ou um dos importadores nucleares do compilador, que servem os seus formatos em todos os espaços de trabalho sem entrada de catálogo. Esta ferramenta seleciona-o, executa-o e escreve o que ele produziu. Um anexo plugins.importer cujo uri indica um importador pela sua identidade e versão — importer/<name>:<version>, tal como aggrega plugin add importer o escreve — anexa esse importador: quando anuncia o formato da origem, é ele o que corre, nessa versão, seja qual for outro importador que também anuncie o formato, e recebe as origens e definições with desse anexo, que nenhum outro importador recebe. Quando vários importadores anunciam o formato e nenhum deles em particular está anexado — entre eles um importador nuclear e um importador de outro nome que o catálogo contém para o mesmo formato — a chamada é recusada indicando-os, como Configuração descreve. Um formato indicado que nenhum importador anuncia é recusado indicando a capacidade que um importador teria de anunciar — import:langflow para uma origem Langflow — que é o que declara um importador que se acrescente ao catálogo, em vez de uma falha genérica que depois seria preciso interpretar.

Um importador nuclear que a máquina do servidor não tem é obtido uma vez, pela primeira importação que precisar dele. A importação obtém-no do registo predefinido do espaço de trabalho servido, sujeita-o ao módulo que a versão do compilador publica, verifica a sua assinatura segundo a política de confiança desse registo e as funções de anfitrião que usa, tal como um pull verifica um plugin que obtém, e guarda-o na cache de conteúdo do espaço de trabalho, pelo que todas as importações seguintes o leem daí e não alcançam nenhum registo. Mais nada é escrito para ele — nenhum lockfile, e nenhum registo de plugins de confiança. Por HTTPS, este é o único registo que uma chamada a esta ferramenta pode levar o servidor a contactar, sob o limite que Que credenciais uma chamada gasta define para uma leitura de registo: o registo é o registo predefinido do espaço de trabalho que este servidor serve, pelo que é um com que esse espaço de trabalho está configurado; nada na chamada indica um registo nem traz uma credencial; e a obtenção gasta o próprio login e a política de confiança deste anfitrião. A ferramenta continua a alcançar o espaço de trabalho e nada além dele, pelo que aggrega:workspace-write é tudo de que uma chamada precisa: o que a obtenção deixa para trás é um módulo na própria cache de conteúdo do espaço de trabalho. Um módulo que não passa na verificação é recusado tal como num terminal, e nada é guardado. Quando o módulo não pode ser obtido — o espaço de trabalho está offline, o seu registo não pode ser alcançado ou o registo não o contém — a chamada é recusada sob A plugin’s .wasm is not on this machine (O módulo de um plugin não está nesta máquina), indicando o importador, a sua versão e o que coloca o seu módulo na máquina.

Quando o espaço de trabalho não indica nenhuma pasta de catálogo, a importação lê o catálogo que o seu registry predefinido publica. Um espaço de trabalho cujos workspace.catalog_dirs, AGGREGA_CATALOG_DIRS e raiz não indicam nenhuma pasta de catálogo lê o catálogo da biblioteca padrão como um único snapshot assinado, em catalog/snapshot no registry predefinido do espaço de trabalho servido — o mesmo registry de onde é obtido um importador do núcleo, acedido nas mesmas condições, sem que nada na chamada indique um registry ou transporte uma credencial. Um snapshot é obtido uma única vez: a sua assinatura é verificada segundo a política de confiança desse registry, e é guardado na cache de conteúdo do espaço de trabalho e lido aí como uma pasta de catálogo, vinculado ao seu digest, sem que nenhum registry volte a ser consultado. Que snapshot uma chamada lê: com upgrade, o mais recente; caso contrário, o que o registo no diretório de saída indica, obtido pelo seu digest quando a máquina não o tem; caso contrário, o que o espaço de trabalho obteve por último como o mais recente; caso contrário, o mais recente. O registo que a importação escreve indica o snapshot que leu, pelo seu digest, pelo que uma chamada posterior que crie rascunhos no mesmo diretório lê o mesmo catálogo. Offline, uma chamada que tivesse de obter um snapshot é recusada indicando o que executar, e upgrade é recusado independentemente do que a máquina tenha, já que só o registry pode dizer qual snapshot é o mais recente. Um registry que não publica nenhum snapshot deixa a importação sem catálogo, e uma entrada warn em diagnostics assinala-o. Um espaço de trabalho que indica uma pasta de catálogo importa com base nela e não obtém nenhum snapshot, e aí upgrade não altera nada.

Omita-se format e o formato é reconhecido pelas assinaturas que os importadores declaram — as do catálogo e as dos importadores nucleares por igual. A entidade Plugin de cada importador regista-as: a sintaxe em que uma origem é lida, os nomes de ficheiro a que uma assinatura se aplica e os caminhos que a árvore analisada tem ou não de conter. A origem é analisada, através do parser que o catálogo do espaço de trabalho serve para uma sintaxe — ou, para uma sintaxe para a qual o catálogo não serve parser, o que o próprio compilador traz — uma vez por cada sintaxe em que uma assinatura aplicável ao seu nome a lê, e o formato usado é o do único importador cuja assinatura corresponde. O importador lê então a origem através do mesmo parser. As assinaturas dos importadores nucleares leem um ficheiro como JSON ou YAML, e as que não indicam ficheiro leem-no como JSON — a do importador Dify como YAML — pelo que reconhecer um ficheiro importado por si só lê-o em ambos e não precisa de nenhum parser no catálogo do espaço de trabalho: o compilador traz um parser de JSON e um de YAML, e um que o catálogo sirva é usado no seu lugar. Um diretório é reconhecido da mesma forma sobre os seus ficheiros: cada assinatura é testada contra os ficheiros dele que os seus padrões selecionam, e uma assinatura que não declara padrão não se aplica a nenhum. O reconhecimento lê o ficheiro indicado — ou, de um diretório, apenas os ficheiros que os padrões de uma assinatura selecionam — e não acede à rede. Uma origem a que nenhuma assinatura corresponde é recusada pedindo format e indicando os formatos que os importadores anunciam — ou, para um diretório, pedindo um dos seus ficheiros enviado por si só como source ou um format cujo importador declare padrões de ficheiro, indicando apenas esses formatos —, sob a condição No importer recognises the source (Nenhum importador reconhece a origem); uma origem a que correspondem assinaturas de mais de um formato é recusada indicando-os, sob a condição More than one importer recognises the source (Mais de um importador reconhece a origem); nenhuma é entregue a um importador adivinhado. Envie-se format para indicar o formato explicitamente em qualquer dos casos — para um diretório, um cujo importador declare padrões de ficheiro, uma vez que um diretório só é lido através deles. Um format em branco é recusado em vez de ser lido como se tivesse sido omitido, porque são pedidos diferentes.

Envie-se target para criar o rascunho do Manifest contra o qual a Release em rascunho compila para um provider. target é uma capacidade de provider — a palavra a que o spec.capability de uma Recipe se associa, como compose ou helm — e é o --target de aggrega import, composto pela mesma operação, pelo que uma chamada e o comando criam os mesmos ficheiros a partir da mesma origem. Para cada tipo de componente e cada tipo de feature de que os rascunhos precisam — nos componentes do Aggregate em rascunho, nas suas ligações e nos seus subsistemas, nos Aggregates do catálogo que compõe e nos anexos da Release em rascunho —, pela ordem em que os rascunhos o declaram pela primeira vez, a importação procura no catálogo do espaço de trabalho as Recipes, ou, para um tipo de feature, as receitas de feature, que implementam o tipo e se associam a essa capacidade. Quando há exatamente uma — várias versões de uma contam como uma — o Manifest faz corresponder o tipo a ela pelo seu nome qualificado pela capacidade e sem versão, como compose/postgres, que o primeiro pull fixa no lockfile na versão mais alta disponível. Quando há várias de nomes diferentes, faz corresponder aquela que tem o nome do próprio tipo, como helm/postgres para core/datastore/postgres. Quando não há nenhuma, ou há várias sem nenhuma com esse nome, o tipo fica sem correspondência e uma entrada warn em diagnostics indica-o e porquê — as várias, cada uma pelo nome — pelo que uma build dos rascunhos para indicando cada instância ou anexo dele, sob No Recipe is mapped for a component or feature instance (Nenhuma Recipe está mapeada para uma instância de componente ou de feature), até que a correspondência seja acrescentada. Quando é o próprio importador a criar o Manifest, para escolher a Recipe através da qual uma instância é renderizada ou uma receita de feature entre várias, cada correspondência que escreveu e que o catálogo oferece para esse tipo e essa capacidade é mantida, qualquer outra é descartada com uma entrada warn, e os tipos que deixa recebem correspondência como acima. O Manifest é criado como manifest.yaml junto à Release em rascunho, com o nome e a versão da Release, e o spec.manifest da Release é definido com esse nome — o comentário que o importador escreveu no seu lugar é substituído, e nada mais na Release muda. Uma Release que já indica um Manifest fica como está, e quando a importação não cria nenhuma Release o Manifest é criado junto ao Aggregate, com o nome e a versão deste, e uma entrada info diz que nada o referencia. O Manifest e a Release editada são rascunhos como os outros: em written, no registo, e devolvidos com dry_run. Um target a que nenhuma Recipe do catálogo se associa é recusado antes de o importador correr, sob An import’s target names a capability no Recipe in the catalog binds to (O destino de uma importação indica uma capacidade a que nenhuma Recipe do catálogo se associa), indicando-o tal como foi enviado e as capacidades a que as Recipes do catálogo se associam, e nada é escrito. Omita-se target e nenhum Manifest é criado — exceto com sync, que cria o rascunho para o destino que foi enviado à importação anterior; um target vazio é recusado em vez de ser lido como se tivesse sido omitido.

Envie-se output_dir para indicar o diretório para onde vão os rascunhos. Omita-se e ficam sob a raiz do espaço de trabalho que a chamada resolveu — o sítio onde aggrega import os escreve quando não se indica destino, seja onde for que se execute, e o sítio onde o aggrega/import do servidor de linguagem os escreve quando o seu pedido não indica nenhum. O destino é opcional nos três, e indicado da mesma forma que qualquer caminho enviado a este servidor. Por HTTP, é um diretório dentro do espaço de trabalho que este servidor serve, escrito de forma relativa à sua raiz: um valor que sobe para fora da raiz, uma localização absoluta fora dela e um diretório que sai dela através de uma ligação — incluindo um diretório ainda não criado sob uma tal ligação — são, cada um, recusados indicando output_dir, e nada é lido nem escrito. Em entrada e saída padrão, é tomado tal como indicado, como todos os caminhos aí: um valor relativo resolve em relação à raiz do espaço de trabalho que a chamada resolveu, e um absoluto pode indicar um diretório fora do espaço de trabalho, onde os rascunhos são criados tal como aggrega import --output-dir os cria. O que aí é escrito fica contido, com as suas ligações resolvidas, ao espaço de trabalho — ou, para um diretório indicado fora dele, a esse diretório — pelo que uma ligação dentro dele que sai dele é recusada e nada é escrito. Um output_dir vazio é recusado em vez de ser lido como se tivesse sido omitido. Em entrada e saída padrão, cli-import traz também o --output-dir do comando como o seu próprio output_dir; aí, um valor relativo resolve na pasta em que o comando corre: a raiz do espaço de trabalho que a chamada indica, caso contrário aquela com que o servidor foi iniciado, caso contrário a pasta em que o servidor corre.

Cada caminho de rascunho é verificado contra o diretório de saída antes de se escrever o que quer que seja. Um caminho que sai dele é recusado indicando tanto o caminho como o diretório, e nada é escrito — nem sequer os ficheiros do mesmo conjunto cujos caminhos estavam corretos, porque uma importação recusada que deixasse parte de si para trás seria um resultado que ninguém pediu. Um caminho de rascunho vem do plugin importador e não do utilizador, e é por isso que é verificado pela mesma razão que um caminho enviado.

Cada importação que cria algum rascunho escreve também .aggrega-import.json junto aos seus rascunhos: o registo do que escreveu — o target que lhe foi enviado, quando foi enviado um, o snapshot do catálogo que leu, quando leu um, e cada ficheiro criado e, num Aggregate ou numa Release em rascunho, cada chave a qualquer profundidade, com um digest do texto aí escrito; qualquer outro ficheiro criado é registado por inteiro. O texto de uma chave é a sua linha, as linhas do seu valor quando o valor não é um mapeamento de chaves, e as linhas de comentário escritas imediatamente acima dela com a sua própria indentação. written indica o registo juntamente com os rascunhos, e com dry_run está entre os rascunhos devolvidos. O registo é JSON, pelo que nada do que lê os documentos YAML do espaço de trabalho o lê.

Uma chamada nunca escreve por cima de um Aggregate que já esteja no diretório de saída. Um Aggregate é o documento que um autor continua a editar depois de criado o rascunho, pelo que uma chamada em que um dos rascunhos iria parar a um ficheiro que se lê como um Aggregate é recusada, indicando o rascunho e o diretório, e nada é escrito — também com dry_run, já que uma execução de ensaio recusa o que a escrita recusa. Qualquer outro ficheiro já presente num caminho de rascunho é sobrescrito, e um ficheiro que uma importação anterior criou e que esta não cria fica onde está.

Envie-se sync para, em vez disso, atualizar o que uma importação anterior criou de acordo com a origem, alterando apenas o que a importação escreveu. Um sync a que não se enviou target cria rascunhos para o destino que o registo indica, pelo que cria o Manifest que a importação anterior criou; um a que se enviou um target cria rascunhos para ele, e o registo passa então a indicá-lo. Um destino registado a que nenhuma Recipe do catálogo se associa é recusado tal como um enviado, com a recusa a dizer que o destino é o registado. Cada parte é avaliada de três formas — o que o registo diz que a importação escreveu aí da última vez, o que está em disco e o que a origem cria agora. Uma parte que a origem deixou como a importação a escreveu da última vez fica exatamente como está em disco, quer um autor a tenha editado quer não. Uma parte que a origem alterou é escrita de novo, uma parte que deixou cair é removida — um ficheiro criado é apagado por inteiro — e uma parte que ganhou é acrescentada junto às partes que o rascunho indica à sua volta, cada uma apenas quando o que está em disco é o que a importação escreveu da última vez e não contém nada que um autor tenha acrescentado. Tudo o resto fica byte a byte: uma chave que um autor acrescentou em qualquer sítio — um parâmetro, uma Feature, também sob uma instância de Component criada, outro Component, o ambiente que uma Release em rascunho deixa ao seu autor — um comentário não escrito imediatamente acima de uma chave criada, e todos os ficheiros que o registo não lista. O drift da resposta lista cada parte atualizada — ou, com dry_run, cada parte que o seria — pela ordem em que o rascunho as indica, cada uma como change (added, removed ou changed), file, o ficheiro criado em que está, e key, as chaves que conduzem a ela num Aggregate ou numa Release em rascunho, como uma lista, vazia quando a parte é o ficheiro inteiro; a resposta em texto indica cada uma numa linha própria nas palavras que aggrega import escreve no erro padrão, <change> <key> in <file> ou <change> <file>. Um drift vazio com dry_run diz que os rascunhos estão em sintonia com a origem. Com dry_run, os rascunhos devolvidos são os ficheiros que o sync escreveria, com o conteúdo que lhes daria. Um sync que alteraria ou removeria uma parte que um autor editou, acrescentaria uma parte onde um autor já escreveu uma, ou removeria uma parte que contém algo que um autor acrescentou é recusado, indicando cada uma dessas partes e porquê, e nada é escrito; um comentário escrito imediatamente acima de uma chave criada edita essa chave. Um sync sobre um Aggregate que nenhum registo lista é recusado dizendo-o, tal como um cujo registo não pode ser lido, e um sync cujo importador não conseguiu terminar não escreve nada. Um sync para um diretório que não contém registo nem nada nos seus caminhos de rascunho escreve o rascunho inteiro. drift é uma lista vazia para uma chamada que não é um sync.

A resposta traz source, tal como foi indicada; format, como a origem foi lida; workspace_root, a raiz do espaço de trabalho que a chamada resolveu; output_dir, o diretório a que os caminhos de rascunho são relativos; written, os ficheiros que chegaram ao disco; drift, o que um sync atualizou; diagnostics, uma entrada por construção que o importador não conseguiu traduzir; decisions, como o importador mapeou cada nó da origem; e halted. output_dir é o diretório enviado, ou essa raiz quando não se enviou nenhum, lido a partir do que a importação efetivamente usou, e é reportado também com dry_run, onde nada é escrito mas cada caminho de rascunho continua a ser relativo a ele. Por HTTP, workspace_root é retido e marcado com workspace_root_withheld, porque a raiz é um sítio no anfitrião do servidor, como O que uma resposta diz sobre o sistema de ficheiros do servidor expõe; output_dir é retido e marcado com output_dir_withheld quando é essa raiz, e caso contrário é dado pelo seu nome relativo à raiz — a forma que tomam os caminhos do próprio utilizador — pelo que o destino dos rascunhos continua a constar da resposta. Uma importação que o importador não conseguiu terminar cria mesmo assim os rascunhos que conseguiu, e regressa marcada como falha com toda essa resposta — halted a true, os ficheiros que chegaram ao disco indicados em written, e os diagnósticos junto a eles a indicar o que falta. Isto é um resultado parcial que se pode manter ou descartar, não uma chamada que não fez nada.

decisions diz onde a importação adivinhou. Traz uma entrada por cada nó da origem que o importador mapeou, pela ordem do importador: source_node, o id, o type e o params_summary do nó; candidates, cada Component do catálogo que o importador ponderou para ele, como component, score, tier e signals — o que cada um dos seus sinais contribuiu, em table, category, domain_labels, shape e name; chosen, o target que escolheu, o mode em que o escreveu — uma reference a um Component existente ou um draft — e o tier da escolha; rationale, porquê; e swap_hint, como escolher de outra forma. candidates está ausente quando o importador não ponderou nenhum, chosen quando não fez escolha, e rationale e swap_hint quando não escreveu nenhum. Cada valor é do próprio importador — como pontua um candidato e onde caem os seus níveis são escolhas dele — pelo que se deve ler uma entrada como o relato que ele faz do mapeamento. decisions está na resposta tanto com dry_run como quando a importação parou, e é uma lista vazia para um importador que não reporta nenhuma. A resposta em texto indica cada decisão numa linha própria depois dos diagnósticos, nas palavras que aggrega import escreve no erro padrão: mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, sendo a pontuação a do melhor candidato.

dry_run faz tudo exceto escrever. Cada ficheiro criado regressa em drafts com o seu caminho, relativo a output_dir, e o seu conteúdo, e nada é criado — para um cliente que mostra o resultado ao utilizador antes de ser guardado. Todos os outros comportamentos são os da escrita, o mesmo importador sobre a mesma origem a reportar os mesmos diagnósticos, pelo que uma origem que a escrita recusaria é também recusada com ele. Sem ele, os ficheiros estão em disco e written indica-os, e drafts está ausente em vez de repetir bytes que se pediu que fossem escritos.

Os rascunhos são um ponto de partida que pertence ao utilizador e que este continua a editar. Se o que dizem é admissível — se um socket é um que o produtor declara, ou se a aplicabilidade de uma Feature é satisfeita — não é decidido aqui. É a isso que validate responde.

Em entrada e saída padrão, a mesma capacidade está também acessível como cli-import, que executa o comando e devolve o texto que imprimiu; por HTTP essa ferramenta não existe, e é esta a forma de aceder à capacidade aí.

Publicar, assinar e retirar

Quatro ferramentas colocam algo onde outras pessoas o irão resolver. publish-entity empacota uma entidade de catálogo e publica-a; publish-artifact publica um ficheiro autónomo, como um pacote de documentação, com os seus bytes opacos e sem analisar nenhum envelope de entidade; sign-artifacts assina referências já publicadas e anexa cada assinatura, deixando como está uma referência que já traga uma que a política de confiança do seu registo verifica; deprecate-artifact anexa um marcador de retirada assinado a uma. Leia-se O que um assistente pode fazer sem perguntar primeiro antes de permitir qualquer delas: são as ferramentas cujos efeitos saem da máquina.

publish-entity aceita entity, o documento a publicar, e um Plugin precisa também de plugin, o executável publicado dentro do seu manifesto. publish-artifact aceita file com o name e a tag sob os quais é publicado. Todos os argumentos de caminho aqui são absolutos ou relativos à raiz do espaço de trabalho, o mesmo contrato que todas as outras ferramentas desta superfície usam, e workspace_root indica o espaço de trabalho a que a chamada se refere — num servidor alcançado em entrada e saída padrão. Um servidor alcançado por HTTPS recusa workspace_root e exige que cada um desses caminhos resolva dentro do espaço de trabalho que serve, como Um processo, um espaço de trabalho expõe. registry é o destino e, por predefinição, é o configurado no espaço de trabalho; não enviar nenhum, sem predefinição configurada, é recusado indicando o que enviar. sign-artifacts aceita references, um ou mais endereços de registo e não caminhos, e opcionalmente jobs, quantos deles são assinados ao mesmo tempo: se for omitido, são assinados um após o outro, e um valor inferior a 1 é recusado indicando o que enviar. Cada um continua a ser assinado exatamente como seria sozinho, como descreve aggrega sign. deprecate-artifact aceita ou reference com severity e reason, ou from a indicar um ficheiro de lote — e recusa argumentos de conteúdo enviados juntamente com um ficheiro de lote em vez de os descartar, porque um ficheiro de lote fornece os seus próprios e um argumento ignorado em silêncio parece um que foi respeitado.

As duas ferramentas de publicação aceitam dry_run, que mostra o que uma publicação enviaria sem contactar nenhum registo. Calcula o pacote, reporta o que teria publicado e responde com beyond_this_machine a false e o destino a que se teria dirigido em registries; publish-entity responde também com o digest que essa publicação produziria, o que aggrega push --dry-run imprime. É a forma de mostrar a alguém uma publicação proposta antes de ela se tornar uma. Assinar e retirar não têm tal forma: ambos atuam sobre algo já publicado, pelo que não há nada a pré-visualizar.

publish-entity responde com windows_unusable_entries quando o arquivo que publica contém entradas que o Windows não consegue guardar tal como estão escritas — um caminho com uma parte com o nome de um dispositivo, como CON, AUX ou NUL, em qualquer capitalização e seja qual for a extensão que se siga, ou uma parte que termine num ponto final ou num espaço — indicando cada uma, primeiro o nome de ficheiro do próprio documento da entidade, depois os ficheiros que traz. Está ausente quando não há nenhuma, o que inclui uma entidade publicada apenas como o seu documento. O aggrega a correr em Windows recusa-se a desempacotar uma tal entrada, pelo que um espaço de trabalho Windows não pode usar a versão; são as entradas sobre as quais aggrega push avisa, e o texto da resposta indica-as também. Não recusam nada: a chamada prossegue ou é recusada exatamente como seria sem elas, incluindo com dry_run.

publish-entity aceita pin_sources, que executa o passo de fixação do autor da entidade sobre a entidade antes de ela ser empacotada, pelo que o entity.lock que o passo escreve junto a ela faz parte do que é publicado. É o mesmo passo que a ferramenta pin executa, escrevendo os mesmos bytes, e corre antes de qualquer recusa que avalie a entidade — pelo que uma publicação recusada aí, por falta de uma assinatura, por exemplo, deixa mesmo assim o lock escrito junto à entidade. Uma recusa relativa à própria chamada, como um espaço de trabalho offline ou a falta de destino, vem primeiro e não fixa nada. Omita-se e decide o pin_sources_at_push do espaço de trabalho; envie-se e decide em qualquer dos sentidos. Uma publicação que fixa escreve dentro do espaço de trabalho além de no registo, pelo que, por HTTP, precisa de uma credencial com ambos os âmbitos, e uma que traga apenas o âmbito que admite publicar é recusada indicando o outro. O resultado traz pin, na forma com que a ferramenta pin responde, quando o passo correu; com dry_run, o passo reporta o lock que escreveria e não escreve nada. Quando o passo não corre, uma Recipe ou FeatureRecipe cujo entity.lock não regista fixação para uma entrada que lê é recusada — ou uma com que a entrada já não corresponde — antes de se empacotar o que quer que seja, incluindo com dry_run, indicando aggrega pin, pin_sources e pin_sources_at_push. É a recusa que pull levanta sobre o mesmo lock, e verificá-la obtém cada origem remota que a entidade escreve por extenso, tal como o passo faria.

Assinar é onde a credencial é gasta, e três das quatro ferramentas fazem-no — uma publicação de artefacto de dados não assina nada, e é assinada depois por referência. identity_token fornece uma identidade sem chave para a chamada. Num servidor alcançado em entrada e saída padrão, omiti-lo recorre à identidade que o próprio ambiente desse servidor traz, e key_path seleciona, em vez disso, uma chave guardada offline. Através de um listener, nenhuma das duas é alcançável: o ambiente não é lido, key_path é recusado e retirado do que estas três ferramentas anunciam, e uma chave que a configuração do espaço de trabalho servido indique não é alcançada — pelo que só assina um token enviado na chamada, como Que credenciais uma chamada gasta expõe. Uma chamada assina com uma credencial. Cada referência enviada a sign-artifacts, e cada entrada de um ficheiro de lote que deprecate-artifact lê, é assinada com a mesma chave guardada ou a mesma identidade sem chave; quando a configuração do espaço de trabalho servido indica uma chave para o registo de uma referência e nenhuma para o de outra, ou duas chaves diferentes, a chamada não assina nada e é recusada indicando os registos de cada lado, antes de se resolver qualquer identidade ou ler qualquer registo — envie-se uma chamada por credencial, ou um único key_path para todas em entrada e saída padrão. Através de um listener, nenhuma chave configurada é alcançada, pelo que aí todas as referências são assinadas com a identidade que a chamada envia e a chamada nunca é recusada por isto. A recusa está descrita em References signed together need different signing credentials (Referências assinadas em conjunto precisam de credenciais de assinatura diferentes). fulcio_url, rekor_url e timestamp_url sobrepõem-se aos endpoints sem chave que o espaço de trabalho configura, em qualquer dos transportes. Quando nenhuma identidade se resolve, a chamada recusa e indica o que enviar — nada aqui abre um navegador nem espera por uma pessoa, porque ninguém está a observar um fluxo de protocolo, e uma chamada que ficasse pendurada seria a falha silenciosa que essa recusa existe para evitar. Em publish-entity, se é anexada uma assinatura de todo segue a política do registo de destino, a menos que sign diga o contrário, e um registo que exige assinaturas recusa uma publicação não assinada seja o que for que se envie: não há nenhum argumento que contorne essa recusa. Consulte-se aggrega sign para os dois modos de assinatura e o que cada um contacta.

Cada resultado traz os factos e não uma transcrição: onde o artefacto foi parar, a sua tag, o digest publicado — ou, para a execução de ensaio de uma entidade de catálogo, o digest que uma publicação produziria — se a tag já apontava para conteúdo idêntico byte a byte, se uma publicação foi assinada, e o seu reach. Um lote de assinatura reporta cada referência assinada com o digest a que a sua assinatura se compromete, pela ordem em que as referências foram dadas, e um lote em que alguma referência falhou regressa como uma falha que indica cada uma, e não como um resultado com uma lista mais curta — um lote parcial reportado como êxito é a forma de uma recusa acabar lida como uma aprovação. Uma descontinuação reporta cada marcador com o seu próprio digest, já que um marcador é anexado como referrer sem tag do artefacto que retira e nada mais o endereça. Assinar ou retirar uma referência que nada publicou é recusado em vez de ser anexado a nada.

As duas partes de uma resposta

Todas as ferramentas respondem com um texto legível, e com um resultado estruturado ao lado sempre que a operação tem um. O texto é escrito para uma pessoa que lê a conversa. O resultado estruturado traz a mesma resposta como campos que um programa lê — um veredicto, uma lista de ficheiros, um diagnóstico — e uma recusa também traz um quando a operação tinha constatações em mãos quando recusou, como O que uma build recusada devolve descreve para uma build.

O resultado estruturado traz também o texto, como text_answer. O resultado estruturado de todas as ferramentas tem um campo text_answer com o texto da resposta exatamente como o texto o traz: cada frase, pela ordem, sem alterações. Assim, um cliente que entrega ao seu modelo o resultado estruturado em vez do texto, como faz o Claude Desktop, entrega-lhe mesmo assim cada frase que o texto diz — a linha com que abre a resposta de describe-capabilities sem argumentos, a configuração em vigor que config-show reporta, a frase que indica a pasta que uma resposta usou quando não foi encontrado nenhum espaço de trabalho. text_answer é escrito primeiro, antes dos campos com que a ferramenta responde, e é o texto que o chamador recebe: por HTTP, indica cada sítio no anfitrião do servidor tal como o texto, como O que uma resposta diz sobre o sistema de ficheiros do servidor expõe. O próprio texto continua a ser a prosa que é, para os clientes que o leem, pelo que as mesmas palavras viajam duas vezes em cada resposta.

Nenhuma ferramenta é exceção, incluindo lint. Nenhuma ferramenta responde com um campo próprio chamado text_answer, pelo que o campo nunca toma o lugar de um. O resultado estruturado de lint mantém o seu summary — o número de entidades verificadas e de constatações, no total e por severidade, com os nomes que aggrega lint escreve com -o json — e traz text_answer ao lado. describe-capabilities mantém também os seus próprios campos: version_summary, a linha de versão por si só, quando não recebe argumentos, e em cada entrada do seu index um summary, o propósito dessa ferramenta numa linha.

Nenhuma ferramenta anuncia um esquema de saída. A listagem de uma ferramenta traz um esquema para os argumentos que aceita e nenhum para o seu resultado, pelo que text_answer é indicado aqui e não num esquema.

Uma resposta sem resultado estruturado é apenas o seu texto. Uma recusa dos argumentos de uma chamada, e qualquer outra falha para a qual a operação não tinha nada de estruturado a reportar, regressa como o seu texto e nada mais, e o texto é então a única parte que um cliente tem para mostrar ao seu modelo.

Quando uma chamada não tem êxito

Onde chega a resposta depende de uma coisa: se o chamador a pode corrigir alterando os argumentos de uma ferramenta que existe.

Tudo o que pode ser corrigido dessa forma regressa como o próprio resultado da ferramenta, marcado como falha e com a correção como texto — uma combinação de seletores que a ferramenta não aceita, um argumento obrigatório omitido, um argumento enviado com o tipo JSON errado, um caminho que não resolve, um diagnóstico do compilador. É esse o canal que é mostrado a um assistente, pelo que ele lê o que correu mal e chama de novo com o argumento corrigido.

O canal de erros do protocolo fica reservado para o que não tem resultado de ferramenta onde viver: um nome de ferramenta que o servidor não serve, um pedido cujos parâmetros não consegue ler, um método que não implementa, e uma mensagem que nem sequer é JSON válido. Ler um recurso e renderizar um prompt também respondem aí, porque nenhum desses resultados traz uma marca de falha própria.

O esquema anunciado de uma ferramenta declara também a maioria das regras que os seus argumentos têm de cumprir — que seletores são mutuamente exclusivos, que argumento só tem significado junto a outro e quais são obrigatórios — pelo que um cliente que compõe chamadas segundo o esquema declarado raramente tem de fazer a chamada para as aprender. Uma regra que o esquema não enuncia continua a ser recusada, com uma frase que a indica; a regra de pull segundo a qual verify não se combina com upgrade_targets nem com pin_sources fica de propósito para a recusa, pela razão dada em Resolver aquilo de que uma Release depende.

O que para o servidor

Em entrada e saída padrão, fechar a ligação para-o. O servidor lê uma mensagem por linha e termina de forma limpa quando a sua entrada padrão chega ao fim do fluxo, pelo que um cliente que fecha a ligação desliga o servidor. É esse o caso habitual nesse transporte, porque nunca se lança o comando à mão: o cliente que o iniciou é o que o termina, pelo que sair do editor, ou desativar este servidor para um projeto, é como normalmente se para.

Pedir ao próprio processo que pare chega ao servidor em qualquer dos transportes. Uma interrupção a partir de um terminal, ou um pedido de terminação de um supervisor ou de um runtime de contentores, desliga-o ao primeiro pedido, quer um cliente esteja a enviar algo quer não: deixa de aceitar mensagens, termina o trabalho que uma chamada em curso está a fazer e sai de forma limpa. Um segundo pedido termina o processo de imediato. Em entrada e saída padrão, uma chamada ainda em curso quando se pede ao processo que pare não termina, portanto; um listener, pelo contrário, esvazia-se, deixando terminar dentro de um orçamento limitado uma chamada que já está a ser respondida antes de o processo sair.

Um cliente pode também parar uma chamada sem parar o servidor, e a forma de o fazer depende do transporte. As chamadas são respondidas em simultâneo, pelo que terminar uma é tratado enquanto essa chamada ainda está a correr, em vez de esperar atrás dela. Em entrada e saída padrão, um cliente indica o id da chamada; cancelar uma chamada que já foi respondida, ou uma em que o servidor não está a trabalhar, não faz nada — e é isso que torna seguro enviar tal mensagem sem saber primeiro se a resposta já vem a caminho. Por HTTP não há mensagem a enviar: fechar a ligação que transportava a chamada termina-a. Em qualquer dos casos, diz-se à chamada que pare — o seu trabalho termina no ponto seguinte em que a operação verifica, e uma operação que nunca verifica corre até ao fim — nada mais é enviado para essa chamada, todas as outras chamadas em curso prosseguem, e o servidor continua a servir.

Quando o usar

Use-se aggrega mcp quando se pretende que um assistente de IA ajude a escrever entidades Aggrega segundo os esquemas e a referência reais — para que as suas sugestões assentem na estrutura exata que o compilador aceita, em vez de serem adivinhadas. Encaixa diretamente no ciclo de autoria: o assistente lê o esquema e a referência de um tipo, gera um esqueleto, preenche os campos que cabem ao papel do utilizador e valida antes de devolver o rascunho. Consulte-se Escrever ficheiros do Aggrega para esse ciclo.

Em entrada e saída padrão, normalmente nunca se escreve aggrega mcp à mão. Em vez disso, indica-se uma vez na configuração MCP do cliente, e o cliente inicia-o e para-o. Um listener é o outro caso: aí é o utilizador que executa o processo, e este continua a correr para chamadores que não o iniciaram.

Exemplo: configuração do cliente em entrada e saída padrão

Aponte-se um cliente MCP para o comando com uma entrada de servidor stdio:

{
"mcpServers": {
"aggrega": {
"command": "aggrega",
"args": ["mcp"]
}
}
}

O único pré-requisito é o binário aggrega instalado no PATH do cliente. Para os caminhos de configuração de cada cliente e a resolução de problemas, consulte-se Ligar o servidor MCP. Para obter um esquema diretamente a partir da linha de comandos sem um cliente, consulte-se aggrega get-schema.