Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

aggrega mcp

Uruchamia serwer Model Context Protocol przez standardowe wejście i wyjście lub przez HTTP do integracji z asystentami AI

Składnia

aggrega mcp [flags]

Opis

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.

Flagi

FlagaDomyślnieOpis
--listen—Adres, na którym nasłuchuje transport HTTP, w jednej z dwóch postaci: host:port albo unix:, po którym następuje ścieżka w systemie plików. Wskazuje, gdzie nasłuchiwać, i nie wybiera transportu: jest odczytywany przy —transport http lub mcp.transport: http w konfiguracji obszaru roboczego, a podany przy transporcie stdio jest odrzucany. Nasłuch bez certyfikatu obsługuje ruch niezaszyfrowany i jest dozwolony tylko na interfejsie pętli zwrotnej (127.0.0.1, ::1, localhost) lub na gnieździe Unix, co odpowiada serwerowi działającemu za proxy terminującym TLS; każdy inny adres wymaga mcp.tls.cert_file i mcp.tls.key_file, których ten proces używa wtedy do samodzielnego terminowania TLS. Po ustawieniu nadpisuje klucz konfiguracji mcp.listen.
--transport—Sposób dostępu do serwera: stdio obsługuje protokół przez standardowe wejście i wyjście, w ten sposób dociera do niego klient uruchamiający to polecenie jako podproces; http udostępnia go przez HTTP pod adresem wskazanym przez —listen lub mcp.listen, a przez HTTPS, gdy mcp.tls wskazuje certyfikat i klucz. Po ustawieniu nadpisuje klucz konfiguracji mcp.transport, którego wartością domyślną jest stdio.

Działanie

aggrega mcp uruchamia serwer Model Context Protocol. Można się z nim połączyć przez dwa transporty, a --transport wybiera między nimi: stdio lub http; klucz konfiguracji obszaru roboczego, który ta flaga nadpisuje, to mcp.transport, a wartością domyślną jest stdio.

W domyślnym transporcie stdio serwer komunikuje się przez standardowe wejście i wyjście procesu. W tej postaci nie jest to polecenie uruchamiane interaktywnie — klient obsługujący MCP uruchamia je jako podproces i komunikuje się w protokole przez stdio; strona Podłączanie serwera MCP podaje, gdzie każdy klient przechowuje wpis, który je uruchamia. Uruchomienie go zmienia CLI w asystenta tworzenia znającego Aggrega, działającego w edytorze lub kliencie czatu.

W transporcie http serwer udostępnia protokół przez HTTP: jeden długo działający proces na hoście, do którego łączą się wywołujący, którzy nie siedzą przy jego klawiaturze, nasłuchujący pod adresem wskazanym przez --listen lub, gdy flagi brak, przez mcp.listen. Sposób konfiguracji tego nasłuchu i to, co on przyjmuje, opisano w sekcji Łączenie z serwerem przez HTTPS.

Serwer obsługuje dwie rewizje protokołu, 2026-07-28 i 2025-06-18, więc klient każdej z nich łączy się i ma dostęp do tych samych powierzchni. To, w której rewizji odbywa się wywołanie, jest określane w samym wywołaniu, a nie uzgadniane raz dla całego połączenia. Klient w rewizji 2026-07-28 wysyła obsługiwaną wersję protokołu i własne możliwości z każdym żądaniem oraz pyta server/discover, co obsługuje serwer; klient w rewizji 2025-06-18 ustala te same rzeczy jednorazowo, otwierając połączenie uzgadnianiem initialize. W obu przypadkach serwer nie przechowuje niczego między komunikatami, więc to, co zostanie wysłane najpierw, nie decyduje o tym, jak zostanie obsłużone późniejsze wywołanie. Żądanie wskazujące rewizję, której serwer nie obsługuje, jest odrzucane wraz z informacją, o które dwie można prosić, zamiast być obsłużone tak, jakby prosiło o jedną z nich.

Serwer udostępnia podłączonemu asystentowi trzy powierzchnie:

  • Prompty — dwie rodziny, różniące się tym, na co każda odpowiada. Prompty tworzenia odpowiadają na pytanie „co piszę”: jedna persona na rolę (programista, architekt, operacje) oraz ukierunkowany szablon dla każdej encji. Każdy z nich określa rolę i kieruje asystenta do właściwego schematu, strony referencyjnej i przewodnika tworzenia, aby jego sugestie pozostawały w obrębie filarów, za które ta rola odpowiada. Prompty przepływu pracy odpowiadają na pytanie „jakie wywołania, w jakiej kolejności”: każdy przedstawia uporządkowaną sekwencję wywołań narzędzi prowadzącą do celu obejmującego kilka operacji, wraz z punktami decyzyjnymi między nimi — tworzenie od zera nowej encji Aggregate i jej encji Release, przenoszenie istniejącego chartu, modułu infrastruktury lub pliku container-compose do Aggrega, ustalanie, dlaczego kompilacja się nie kompiluje lub renderuje niewłaściwe artefakty. prompts/list wylicza obie rodziny, a prompts/get renderuje jeden prompt, więc zestaw odczytuje się z serwera, a nie z tej strony.

    Prompt przepływu pracy wymienia wywołania, a wykonuje się je samodzielnie, jedno po drugim, odczytując każdy wynik przed następnym. Nie ma wywołania realizującego cały cel: każde narzędzie obejmuje jedną operację, którą można sprawdzić, więc do celu prowadzi właśnie sekwencja. Persony tworzenia przyjmują opcjonalny kind, na którym mają się skupić, szablon dla encji go wymaga, a kind, któremu nie odpowiada żaden schemat, jest odrzucany z listą akceptowanych wartości, a nie po cichu ignorowany.

  • Zasoby — materiały referencyjne tylko do odczytu, udostępniane bezpośrednio: schema://<kind> dla JSON Schema encji, langref://<path> dla dowolnej strony dokumentacji języka, authoring://<topic> dla przewodnika tworzenia, catalog://<kind>/<name> dla napisanego YAML encji katalogu oraz cli://<command> dla pomocy danego polecenia, z samym cli:// jako punktem wejścia — ta pomoc jest udzielana na podstawie poleceń, które zawiera sam serwer, więc jej odczytanie nie uruchamia żadnego procesu i zwraca ten sam tekst, który polecenie wypisuje dla --help. Odczyt catalog:// encji, której katalog nie zawiera, otrzymuje odpowiedź „nie znaleziono”; jeśli dzieje się tak dlatego, że dokładnie jeden plik katalogu deklarujący tę encję został pominięty przy ładowaniu, komunikat odpowiedzi wskazuje ten plik, naruszane przez niego ograniczenie i krótki kod warunku zamiast samego URI — odmowę, od której aggrega build zaczyna dla tego samego pliku. resources/list wylicza zasoby adresowalne bez parametru, a resources/templates/list ogłasza kształt URI każdej rodziny.

  • Narzędzia — działania na obszarze roboczym; tools/list odpowiada listą wszystkich.

    Narzędzia, z którymi asystent styka się najpierw, są dopasowane do pętli tworzenia: list-entities i list-releases, aby ustalić, co zawiera obszar roboczy; scaffold tworzy szkielet z polami wymaganymi przez dany rodzaj i z symbolem zastępczym wszędzie tam, gdzie należy podać wartość — albo, po otrzymaniu example, zapisuje jeden z uruchamialnych przykładów z dokumentacji do nowego katalogu, odpowiadając lokalizacją tego katalogu, listą zapisanych plików i poleceniami do jego zbudowania, a po otrzymaniu list: true wypisuje przykłady; get-schema zwraca JSON Schema encji; validate sprawdza szkic (wymienia każdy symbol zastępczy, który szkic nadal zawiera, i to, co każdy przyjmuje); describe opisuje encję katalogu — lub encję odczytaną z jej rejestru przez referencję; pull rozwiązuje zależności encji Release do lokalnej pamięci podręcznej i zapisuje jej plik blokady; build buduje encję Release do wyrenderowanych artefaktów — domyślnie w pamięci, bez zapisywania artefaktów na dysk, lub z zapisem do dist/ w katalogu głównym obszaru roboczego, gdzie zapisuje je aggrega build, gdy wysłano write (a zależności są najpierw rozwiązywane tylko wtedy, gdy wysłano auto_pull); gen-catalog generuje encje Plugin z gości Wasm; a explain-error rozwija diagnostykę kompilatora w praktyczne wskazówki — w tym, gdy diagnostyka zaczyna się od krótkiego kodu warunku zatrzymania, ten warunek i opublikowany opis poprawki w tworzeniu, czyli to samo rozwinięcie, które aggrega explain podaje dla tego samego kodu w terminalu.

    Reszta powierzchni jest w tej samej odpowiedzi, a nie za nią: kolejne narzędzia działające wewnątrz serwera — lint, narzędzie wskazujące połączenie zapisane w danym miejscu dokumentu, dwa narzędzia kandydatury, narzędzia kontenera załączników i punktu wstawienia, narzędzie stosujące jedną ograniczoną edycję do dokumentu, pin, które zapisuje przypięcia treści dla wejść encji zgodnie z opisem w sekcji Przypinanie własnych wejść encji, oraz cztery narzędzia publikacji opisane poniżej, a także spisy pamięci podręcznych i skonfigurowanych rejestrów — oraz, dla klienta, który uruchomił ten serwer przez standardowe wejście i wyjście, narzędzie dla każdego polecenia, które można by inaczej wpisać, nazwane według ścieżki jego wywołania. Te narzędzia poleceń istnieją tylko w tym transporcie: serwer osiągany przez HTTP nie oferuje żadnego z nich, z powodu podanego w sekcji Łączenie z serwerem przez HTTPS. Nic nie jest wstrzymywane na późniejsze wywołanie. O tym, ile z listy narzędzi przedstawić modelowi, decyduje klient — pobiera definicje i wybiera, co załadować — a definicja, której klient nigdy nie otrzymał, jest operacją, której model nigdy nie wywoła, niezależnie od tego, jak osiągalna jest nazwa tego narzędzia w protokole. Gdy cała lista przekracza to, co przyjmie klient, można ją skrócić w sposób opisany w sekcji Zawężanie tego, co ogłasza serwer. describe-capabilities zawęża tę powierzchnię do rodzaju encji, nad którym się pracuje. Po wysłaniu kind odpowiada narzędziami obsługującymi ten rodzaj, odczytanymi z rodzajów deklarowanych przez każde narzędzie, a nie ze słów w opisie; wywołane bez argumentów odpowiada tym samym indeksem dla każdego narzędzia, które oferuje ten serwer — nazwą każdego, jednowierszowym celem, obsługiwanymi rodzajami i informacją, czy zapisuje, bez schematów argumentów, więc cała powierzchnia przychodzi w jednej czytelnej odpowiedzi. Dla narzędzia cli- to, czy zapisuje, zależy od tego, czy zapisuje uruchamiane przez nie polecenie: cli-build jest zgłaszane jako zapisujące, ponieważ polecenie zapisuje wyrenderowane artefakty pod katalogiem głównym obszaru roboczego, podobnie jak cli-scaffold, ponieważ po otrzymaniu example polecenie zapisuje jeden z uruchamialnych przykładów z dokumentacji do nowego katalogu, natomiast polecenie, które tylko odczytuje, jest zgłaszane jako tylko odczytujące, nawet jeśli po drodze wypełnia pamięć podręczną współdzieloną przez wszystkie projekty na maszynie, tak jak narzędzie wykonujące tę samą operację wewnątrz serwera; po wysłaniu tools z jedną lub kilkoma nazwami odpowiada pełnymi definicjami i schematami argumentów dokładnie tych narzędzi. Narzędzia cli- nigdy nie są zawężane według rodzaju, ponieważ nic nie rejestruje, jaki rodzaj encji obsługuje polecenie, więc odpowiedź ograniczona do rodzaju je pomija, a odczytuje się je z indeksu bez argumentów. Argumenty narzędzia polecenia są nazwane według flag samego polecenia, więc --output-dir wysyła się jako output_dir, a nierozpoznana nazwa jest odrzucana z listą akceptowanych zapisów, a nie po cichu pomijana.

    Niektóre możliwości są dostępne dwukrotnie na standardowym wejściu i wyjściu: narzędzie przystosowane do pętli tworzenia wykonuje operację wewnątrz serwera, a narzędzie nazwane od polecenia, które zapewnia tę samą możliwość, uruchamia to polecenie. Oba działają inaczej, dlatego w tym transporcie każde z nich wskazuje drugie i opisuje różnicę; przez HTTP narzędzia poleceń są niedostępne, a zdanie o parze jest pomijane, zamiast wskazywać narzędzie, do którego wywołujący nie ma dostępu. Należy sięgać po to, które działa wewnątrz serwera — odpowiada ono wynikiem czytelnym maszynowo obok czytelnego tekstu, dzięki czemu asystent otrzymuje werdykt, listę plików lub diagnostykę jako pola, a nie jako zapis do przetworzenia. Narzędzie polecenia uruchamia prawdziwe polecenie w osobnym procesie, więc robi wszystko, co to polecenie robi na maszynie, na której działa, łącznie z zapisem na dysk tam, gdzie polecenie zapisuje — cli-build zapisuje wyrenderowane artefakty do dist/ w katalogu głównym obszaru roboczego, a pliki kompilacji ze śledzeniem do .trace/ obok niego, a zwracany przez nie wiersz końcowy podaje pełną nazwę tego katalogu — i zwraca jedynie uruchomiony wiersz polecenia oraz tekst wypisany przez to polecenie. Warto po nie sięgnąć, gdy potrzebna jest flaga deklarowana przez polecenie, której drugie narzędzie nie przyjmuje.

    Ten wiersz polecenia zaczyna się od flag globalnych, z którymi uruchomiono serwer i które decydują o konfiguracji — --config i --offline, o ile je podano — przed poleceniem i własnymi flagami wywołania. Dzięki temu polecenie odczytuje tę samą konfigurację, którą odczytuje każde inne narzędzie tutaj: serwer uruchomiony z --offline wykonuje swoje polecenia w trybie offline, a serwer uruchomiony z --config wykonuje je z tym plikiem globalnym. Flaga wysłana przez samo wywołanie pojawia się po nich i ma pierwszeństwo, więc offline: false w jednym wywołaniu sięga do sieci tylko dla tego wywołania, a zwrócony wiersz polecenia pokazuje obie. Jeśli serwer uruchomiono z katalogiem głównym obszaru roboczego — przez --workspace-root lub przez AGGREGA_WORKSPACE_ROOT — wiersz polecenia zaczyna się od tego katalogu jako --workspace-root, przed tymi dwiema flagami, więc polecenie traktuje ten katalog jako katalog główny obszaru roboczego, tak jak po wpisaniu z tą samą flagą i tak jak traktuje go każde narzędzie działające wewnątrz serwera, zamiast wyszukiwać obszar roboczy od katalogu, w którym uruchomiono serwer. Wywołanie, które wysyła workspace_root, podaje własny katalog, a wiersz polecenia zawiera wyłącznie ten — łącznie z wartością pustą, którą polecenie odczytuje tak, jak w terminalu odczytywane jest --workspace-root "": obszar roboczy należy znaleźć od katalogu, w którym uruchomiono serwer. Serwer uruchomiony bez żadnego z nich nie przekazuje katalogu głównego, więc jego polecenia znajdują obszar roboczy od tego katalogu, zgodnie z regułą, którą sekcja Which workspace a call is answered in określa dla każdego narzędzia — z wyjątkiem uruchomienia z pakietu desktopowego z pustym ustawieniem Workspace folder, przy którym wywołanie niepodające własnego obszaru roboczego nie uruchamia żadnego polecenia i otrzymuje odmowę związaną z tym ustawieniem. Polecenie startuje w katalogu głównym obszaru roboczego wskazanym przez wywołanie lub uruchomienie: we własnym workspace_root wywołania, odczytanym tak, jak odczytuje go każde narzędzie — bezwzględny w postaci, w jakiej go wysłano, względny od katalogu głównego, w którym odpowiedź otrzymuje wywołanie niepodające żadnego — i przekazanym poleceniu w jego bezwzględnej postaci, a w przeciwnym razie w katalogu głównym, z którym uruchomiono serwer. Dlatego ścieżka względna, którą wywołanie przekazuje jako plik do odczytu — dokument dla validate, --release lub --catalog — jest odczytywana wewnątrz tego obszaru roboczego, jak w terminalu otwartym w tym miejscu, a kompilacja uruchomiona przez polecenie zapisuje dist/ pod tym katalogiem głównym. Gdy nic nie wskazuje katalogu głównego — brak katalogu z uruchomienia i brak workspace_root lub jest on pusty — polecenie startuje w katalogu, w którym uruchomiono serwer, i stamtąd odczytuje ścieżki względne; workspace_root wskazujący nieistniejący folder jest przekazywany w postaci, w jakiej go odczytano — bezwzględny tak, jak go wysłano, względny w pełnej postaci — a polecenie odrzuca go własnymi słowami. Polecenie rejestrowane przez plugin rozszerzający polecenia nie otrzymuje żadnej z tych flag, ponieważ przekazuje wszystkie argumenty do pluginu bez ich odczytywania, zamiast parsować flagę globalną, zarówno w terminalu, jak i tutaj; startuje w tym samym folderze co każde inne polecenie.

    Kilka poleceń celowo pominięto nawet na standardowym wejściu i wyjściu, gdzie narzędzia poleceń w ogóle istnieją — przez HTTP niedostępne są wszystkie, co jest właściwością transportu, a nie żadnego polecenia. Na standardowym wejściu i wyjściu każde z nich pominięto z podanego powodu: demon i sam ten serwer nigdy nie zwróciłyby wyniku; polecenie odczytujące hasło z terminala nie ma skąd go odczytać; polecenie zapisujące skrypt uzupełniania powłoki nie ma powłoki, w której mogłoby go zainstalować; usunięcie zapisanego poświadczenia działa na magazynie całej maszyny, a nie na wskazanym obszarze roboczym; a interaktywne pozyskanie tokenu tożsamości nie ma nieinteraktywnej postaci. Z tego samego powodu dotyczącego całej maszyny pominięto aggrega plugin run-local, które wczytuje gościa .wasm ze wskazanej ścieżki: celem tego polecenia jest odczyt pliku, gdziekolwiek się znajduje, więc nie ma obszaru roboczego, do którego można by je ograniczyć, a odczyt następuje w samym procesie, zanim gość powstanie. Gość, gdy już działa, nie otrzymuje niczego — żadnych katalogów, gniazd ani środowiska — ale jest to ograniczenie modułu, a nie odczytu, więc nie ono o tym decyduje. Należy uruchamiać je w terminalu, gdzie to użytkownik wskazuje ścieżkę. Podpisywanie i publikowanie to zupełnie inny przypadek i właśnie ta różnica sprawia, że nie ma ich na tej liście. Każde z nich ustala tożsamość z podanego lub zastanego wejścia i jawnie odmawia, gdy żadne nie jest dostępne, więc każde ma postać, która kończy się bez niczyjego nadzoru — podczas gdy interaktywnego pozyskania tokenu żadne wejście nie może zaspokoić nawet w zasadzie. Dlatego są dostępne dwukrotnie: jako polecenia i jako cztery narzędzia działające w procesie, opisane w sekcji Publishing, signing and withdrawing. Tam, gdzie wiersz polecenia otworzyłby przeglądarkę, odmawiają i wskazują, co podać zamiast tego, zamiast czekać na osobę, której nie ma.

W którym obszarze roboczym udzielana jest odpowiedź na wywołanie

Wywołanie wskazuje swój obszar roboczy przez workspace_root; w przeciwnym razie odpowiedź jest udzielana w obszarze roboczym, nad którym uruchomiono serwer. Jeśli przy uruchomieniu wskazano katalog główny, przez --workspace-root lub AGGREGA_WORKSPACE_ROOT, ten katalog jest samym katalogiem głównym obszaru roboczego, tak jak ta flaga działa w każdym poleceniu: nic powyżej niego nie jest przeszukiwane w poszukiwaniu obejmującego obszaru roboczego, więc uruchomienie wskazuje folder zawierający plik .aggrega-config.yaml obszaru roboczego, a na wywołanie odpowiadają tam zarówno narzędzia działające wewnątrz serwera, jak i narzędzia poleceń. Jeśli przy uruchomieniu nie wskazano żadnego, obszar roboczy jest wyszukiwany od katalogu, w którym uruchomiono serwer, dokładnie tak, jak wykrywa go polecenie wpisane tam w terminalu — kolejność opisano w sekcji The other ways a project root is recognised — z wyjątkiem uruchomienia z pakietu desktopowego z pustym ustawieniem Workspace folder, które zamiast tego odrzuca takie wywołanie, jak opisano poniżej. Względny workspace_root jest odczytywany od katalogu głównego, w którym odpowiedź otrzymuje wywołanie niepodające żadnego — katalogu wskazanego przy uruchomieniu lub, jeśli nie wskazano żadnego, katalogu głównego obszaru roboczego, do którego prowadzi katalog, w którym uruchomiono serwer — dzięki czemu wywołanie wskazuje folder wewnątrz obszaru roboczego, na przykład quickstart-ai/1, nie wiedząc, gdzie obszar roboczy znajduje się na maszynie; bezwzględny jest używany w podanej postaci. Każde narzędzie odczytuje go w ten sposób, łącznie z narzędziami poleceń. Gdy nie ma katalogu głównego, od którego można odczytać względny — katalog główny uruchomienia nie jest istniejącym folderem lub jest to uruchomienie desktopowe z pustym Workspace folder — względny jest odrzucany tak samo jak wywołanie niepodające żadnego. Wartość workspace_root, która nie wskazuje istniejącego folderu lub wskazuje plik, jest odrzucana, zanim narzędzie zrobi cokolwiek innego, z podaniem nazwy argumentu i przytoczeniem wartości — bezwzględnej w postaci, w jakiej została wysłana, względnej w pełnej postaci, w jakiej została odczytana — tak jak polecenie odrzuca --workspace-root.

Katalog główny uruchomienia, który nie jest istniejącym folderem, jest obsługiwany jako odmowa przez standardowe wejście i wyjście. Jeśli --workspace-root lub AGGREGA_WORKSPACE_ROOT wskazuje folder, który nie istnieje, lub wskazuje plik, serwer zapisuje odmowę do swojego strumienia błędów i mimo to się uruchamia, dzięki czemu klient, który nie pokazuje użytkownikowi niczego z tego strumienia, i tak pokazuje przyczynę. Serwer odpowiada na initialize oraz na żądania list narzędzi, zasobów i promptów, a na każde wywołanie, które działałoby w tym obszarze roboczym, odpowiada odmową: na wywołanie narzędzia — wynikiem zakończonym niepowodzeniem, na odczyt encji catalog:// lub strony dokumentacji — błędem. Odmowa podaje nazwę flagi albo zmiennej wraz z ustawieniem Workspace folder aplikacji desktopowej, które ją ustawia — ustawieniem opisanym w sekcji Claude Desktop — i przytacza wartość dokładnie w takiej postaci, w jakiej ją podano; wartość, którą klient wysłał bez jej uzupełnienia, jest przytaczana tak, jak dotarła, i nic w niej nie jest rozpoznawane. Narzędzie uruchamiające polecenie nie uruchamia żadnego dla wywołania, które nie wskazuje własnego obszaru roboczego, ponieważ folderu, w którym polecenie by się uruchomiło, nie ma, i odpowiada tą samą odmową. Na wywołanie wskazujące własny obszar roboczy ścieżką bezwzględną odpowiedź jest udzielana w nim; wywołanie wskazujące go ścieżką względną nie ma folderu, od którego można by ją odczytać, i otrzymuje tę samą odmowę. Na to, co nie działa w żadnym obszarze roboczym — schemat, prompt, pomoc polecenia — odpowiedź jest udzielana jak na każdym serwerze. Nasłuchujący serwer jest natomiast odrzucany przy starcie, zanim cokolwiek zostanie powiązane, z tą samą odmową, dzięki czemu ten, kto go nadzoruje, odczyta błąd tam, gdzie go szuka.

Uruchomienie desktopowe z pustym ustawieniem Workspace folder jest obsługiwane jako odmowa w ten sam sposób. Pakiet desktopowy zawsze przekazuje serwerowi AGGREGA_WORKSPACE_ROOT z zawartością pola Workspace folder i ustawia obok niej AGGREGA_BUNDLE_VERSION, a aplikacja uruchamia serwer w wybranym przez siebie folderze — często folderze systemowym — a nie w projekcie. Dlatego serwer działający przez standardowe wejście i wyjście, uruchomiony bez --workspace-root, którego środowisko zawiera AGGREGA_BUNDLE_VERSION oraz puste lub nieobecne AGGREGA_WORKSPACE_ROOT, nie szuka obszaru roboczego od folderu, w którym go uruchomiono. Zapisuje odmowę do swojego strumienia błędów i mimo to się uruchamia, odpowiadając tak jak w przypadku nieistniejącego katalogu głównego uruchomienia: na każde wywołanie, które działałoby w obszarze roboczym i nie wskazuje własnego, odpowiada odmową informującą, że aplikacja desktopowa uruchomiła serwer z pustym ustawieniem Workspace folder, więc AGGREGA_WORKSPACE_ROOT nie wskazuje katalogu głównego obszaru roboczego, nakazującą ustawić Workspace folder na folder zawierający plik .aggrega-config.yaml obszaru roboczego i informującą, że folder ustawiony po uruchomieniu serwera zaczyna obowiązywać po wyłączeniu i ponownym włączeniu rozszerzenia lub po ponownym uruchomieniu aplikacji, ponieważ aplikacja przekazuje to ustawienie serwerowi tylko przy jego uruchamianiu. Narzędzie uruchamiające polecenie nie uruchamia żadnego dla takiego wywołania. Na wywołanie wskazujące własny obszar roboczy ścieżką bezwzględną odpowiedź jest udzielana w nim, a wywołanie wskazujące go ścieżką względną otrzymuje tę samą odmowę, ponieważ nie ma Workspace folder, od którego można by ją odczytać; na to, co nie działa w żadnym obszarze roboczym, odpowiedź jest udzielana jak na każdym serwerze. Serwer rozpoznaje takie uruchomienie wyłącznie po AGGREGA_BUNDLE_VERSION: w pakiecie, który nie ustawia tej zmiennej, puste ustawienie jest odczytywane jako brak katalogu głównego, a uruchomienie, które ustawia tę zmienną ręcznie i nie wskazuje katalogu głównego, jest odrzucane tak samo jak uruchomienie z pakietu. Każda inna pusta wartość nadal nie wskazuje katalogu głównego — puste AGGREGA_WORKSPACE_ROOT przy uruchomieniu bez AGGREGA_BUNDLE_VERSION, --workspace-root wpisane jako puste, nasłuchujący serwer, aggrega serve i każde inne polecenie traktują ją jako nieustawioną.

Jeśli nie znaleziono ani nie wskazano obszaru roboczego, odpowiedź dotycząca obszaru roboczego podaje, którego folderu użyto. Gdy nie ma katalogu głównego uruchomienia, wywołanie nie zawiera workspace_root i nic nie zakotwicza obszaru roboczego od folderu, w którym udzielono odpowiedzi, odpowiedź jest udzielana w tym folderze. Jeśli wynik narzędzia zależy od obszaru roboczego — chodzi o te same narzędzia, których polecenia wyświetlają ostrzeżenie w wierszu poleceń — jego tekst kończy się ostrzeżeniem z wiersza poleceń, <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace, oraz wierszem nakazującym wysłać workspace_root wskazujące folder zawierający plik .aggrega-config.yaml obszaru roboczego; odpowiedź, o której obszar roboczy nie decyduje, taka jak odczyt konfiguracji czy lista wtyczek, nie mówi nic o obszarach roboczych. To zdanie nie dodaje własnego pola do wyniku strukturalnego; wynik strukturalny zawiera je w text_answer, które przechowuje tekst, jak opisano w sekcji The two parts of an answer. Narzędzie uruchamiające polecenie w osobnym procesie zawiera własny wiersz polecenia mówiący to samo, w postaci, w jakiej polecenie go wypisało. W takim folderze nic nie jest zapisywane do pamięci podręcznej artefaktów: pobranie albo budowanie, które ma najpierw rozwiązać zależności, jest tam odrzucane, zanim cokolwiek zostanie pobrane, z podaniem folderu i dwóch wyjść — wysłania workspace_root lub umieszczenia w folderze pliku .aggrega-config.yaml z blokiem workspace:. Przypięcie lub publikacja encji Recipe albo FeatureRecipe jest odrzucana w ten sam sposób, jeśli pobierałaby zdalne źródło, które encja zapisuje w całości — aby je przypiąć lub porównać jego przypięcie — zanim to źródło zostanie pobrane; jeśli nie pobiera żadnego, ponieważ encja nie ma źródła, ma źródło lokalne lub takie, którego współrzędne uzupełnia każda encja Release, odpowiedź jest udzielana jak w każdym innym miejscu. Budowanie, które niczego wcześniej nie rozwiązuje, nadal renderuje, ale zewnętrzne wejście przypięte w pliku blokady, którego pamięć podręczna już nie zawiera, nie jest pobierane ponownie: renderowanie otrzymuje to samo zdanie zamiast wejścia, tak jak otrzymuje komunikat trybu offline. Żadna odpowiedź przez HTTP nie zawiera tego zdania: nasłuchujący serwer zawsze obsługuje obszar roboczy, który mu wskazano lub który znalazł. Nie zawiera go też uruchomienie z pakietu desktopowego z pustym ustawieniem Workspace folder, które odrzuca wywołanie niewskazujące własnego obszaru roboczego, zamiast odpowiadać na nie w folderze, w którym je uruchomiono.

Wywołanie dotyczące encji Release lub dokumentu, które wskazuje ścieżką bezwzględną, otrzymuje odpowiedź we własnym obszarze roboczym tego pliku, gdy nic innego go nie ustaliło. Jeśli przy uruchomieniu nie wskazano katalogu głównego, wywołanie nie przesyła workspace_root, a katalog, w którym uruchomiono serwer, nie zakotwicza żadnego obszaru roboczego, obszar roboczy jest wykrywany ponownie od folderu, w którym znajduje się ten plik, a to, co zostanie w ten sposób znalezione — projekt, do którego plik należy, albo, gdy wszystko inne zawiedzie, ten folder — jest obszarem, w którym wywołanie otrzymuje odpowiedź. Tej samej reguły przestrzega polecenie wpisane w terminalu, więc obowiązuje ona dla każdego narzędzia, którego wywołanie dotyczy wskazanej encji Release lub dokumentu encji: kompilacji, pobrania, walidacji, lintowania, opisu, listowania w kategoriach encji Release, pytania o węzeł grafu encji Release, przypięcia, publikacji encji, edycji oraz odczytu pozycji w dokumencie. Jeśli wywołanie wskazuje zarówno encję Release, jak i dokument, decyduje Release. Dzięki temu klient, który uruchomił serwer poza projektem, nadal otrzymuje zbudowaną w nim encję Release na podstawie własnej konfiguracji projektu. Pozostałe ścieżki wskazane w wywołaniu są odczytywane jak zawsze — ścieżka względna od katalogu, w którym uruchomiono serwer — a narzędzie uruchamiające polecenie w osobnym procesie otrzymuje odpowiedź z tego samego obszaru roboczego, ponieważ polecenie przestrzega tej samej reguły w tym samym katalogu. Katalog główny wskazany przy uruchomieniu, workspace_root przesłany w wywołaniu, katalog startowy, który sam znajduje się wewnątrz obszaru roboczego, oraz encja Release lub dokument wskazane ścieżką względną są używane takie, jakie są. Przez HTTP nic z tego nie występuje: serwer nasłuchujący zawsze obsługuje obszar roboczy, który otrzymał lub znalazł, a każda ścieżka wskazana w wywołaniu jest względna wobec niego. Nie występuje to też przy uruchomieniu z pakietu desktopowego z pustym ustawieniem Workspace folder, które odrzuca wywołanie niewskazujące własnego obszaru roboczego, niezależnie od tego, jaki plik wskazuje.

Zawężanie tego, co serwer ogłasza

mcp.announce_tools wymienia narzędzia, które ten serwer ogłasza, zapisane dokładnie tak, jak podaje je lista narzędzi. Jeśli klucz zostanie pominięty, ogłaszane jest każde narzędzie, które ten serwer posiada; jest to ustawienie domyślne i kształt, jakiego oczekuje klient zgodny z protokołem. Jeśli zostanie zapisana lista, ogłaszane są dokładnie te narzędzia: narzędzie pominięte nie występuje na liście narzędzi ani w odpowiedzi describe-capabilities, a wywołane mimo to po nazwie zostaje odrzucone, przy czym odmowa wskazuje to ustawienie. Jeśli zostanie zapisana pusta lista, nie jest ogłaszane nic — pominięcie klucza i zapisanie [] to więc różne stwierdzenia, a ustawienie nie ma wartości domyślnej uzupełnianej automatycznie.

Należy je ustawić tam, gdzie klient po drugiej stronie ogranicza liczbę narzędzi, które zarejestruje, czasem łącznie dla wszystkich serwerów, z którymi jest jednocześnie połączony, i wymienić narzędzia, których ten klient potrzebuje. Takie ograniczenie jest przypadkiem, dla którego to ustawienie istnieje, a klient, którego dotyczy, to zwykle ten, który uruchomił ten serwer przez własne standardowe wejście i wyjście — dlatego w odróżnieniu od reszty bloku mcp, który konfiguruje nasłuch uruchamiany przez transport http, ten klucz jest odczytywany niezależnie od transportu, którym posługuje się serwer.

Zawęża ono to, co jest ogłaszane, i nic ponadto. Wymienienie tu narzędzia niczego nie poszerza. Nie znosi mcp.deny_reach, które całkowicie odbiera daną możliwość, więc wymienione tu narzędzie rodzaju odebranego przez tamto ustawienie pozostaje poza listą i jest odrzucane ze wskazaniem tamtego ustawienia. Nie znosi też zakresów, które niesie token wywołującego: wymienione tu narzędzie jest wyświetlane na liście niezależnie od tych zakresów, a wywołanie, którego one nie dopuszczają, nadal jest odrzucane ze wskazaniem zakresu, który by je dopuścił. W obu przypadkach wywołujący napotyka odmowę tamtego ograniczenia, a nie tego. Odmowa wynikająca z tego ustawienia nie zawiera wyzwania i nie wskazuje żadnego zakresu, ponieważ żadne poświadczenie nie zmienia tego, co serwer postanowił udostępnić — zamiast tego wskazuje ustawienie, które jest jedynym, na co czytający odmowę może zareagować.

Każda nazwa musi należeć do narzędzia, które ten plik binarny posiada. Nazwa, której nie odpowiada żadne narzędzie, zatrzymuje serwer, zanim cokolwiek obsłuży, a odmowa wymienia narzędzia, które on ma — dzięki temu literówka zostaje wykryta przy uruchomieniu, a nie przez zestaw po cichu węższy od zamierzonego. Nazwa z rodziny cli-, która uruchamia polecenie aggrega w osobnym procesie, jest akceptowana w obu transportach i przez HTTP nie ogłasza niczego, ponieważ tam żadne takie narzędzie nie jest w ogóle oferowane żadnemu wywołującemu.

Ogłaszany zestaw jest ustalany przy starcie procesu, więc jego zmiana wymaga ponownego uruchomienia i nic nie rozszerza listy klientowi, który już się połączył.

Z którego wydania pochodzi serwer

describe-capabilities wywołane bez argumentów podaje, z którego wydania pochodzi ten serwer. Jego ustrukturyzowana odpowiedź zawiera server_version, czyli wersję, którą plik wykonywalny aggrega zgłasza dla siebie — tę samą, którą aggrega version wypisuje dla tego samego pliku — a jego tekst zaczyna się od jednego wiersza, który ją podaje, przed indeksem. Ustrukturyzowana odpowiedź zawiera ten sam wiersz jako version_summary, słowo w słowo, więc klient, który przekazuje modelowi tylko ustrukturyzowaną odpowiedź, przekazuje mu również ten wiersz.

Jeśli serwer został uruchomiony przez pakiet desktopowy, ta sama odpowiedź podaje obok wersję pakietu. Pakiet nie zawiera programu: uruchamia ten plik wykonywalny aggrega, który wskazuje jego ustawienie Path to the aggrega executable — domyślnie nazwę polecenia aggrega, którą aplikacja wyszukuje w swoim PATH — więc pakiet i plik wykonywalny są instalowane oddzielnie i mogą pochodzić z różnych wydań, a aplikacja wyświetlająca pakiet pokazuje tylko własną wersję pakietu. Pakiet przekazuje serwerowi swoją wersję jako AGGREGA_BUNDLE_VERSION w jego środowisku; serwer odczytuje ją raz, przy starcie, a odpowiedź zawiera ją jako bundle_version. Obie wersje są porównywane dokładnie w zapisanej postaci, co jest rzetelnym porównaniem, ponieważ pakiet i plik wykonywalny jednego wydania są oznaczone wersją tego wydania w tej samej formie, a kompilacja deweloperska odczytuje się inaczej niż każde wydanie. Jeśli obie są równe, wiersz podaje obie i nic więcej. Jeśli się różnią, wiersz stwierdza, podając obie, że plik wykonywalny i pakiet pochodzą z różnych wydań, a wskazówki, które serwer przekazuje modelowi przy połączeniu, zaczynają się od tego samego zdania, więc model widzi tę różnicę, zanim o cokolwiek zapyta.

Serwer, którego nie uruchomił pakiet, zgłasza tylko własną wersję. Uruchomiony z terminala, z konfiguracji edytora lub jako nasłuchujący, nie zawiera bundle_version, chyba że coś ustawi tę zmienną w jego środowisku. Serwer działający przez standardowe wejście i wyjście, który ma tę zmienną, jest traktowany jako uruchomiony przez pakiet jeszcze pod jednym względem: gdy nie wskazano mu katalogu głównego, odrzuca puste ustawienie Workspace folder, jak opisano w sekcji W którym obszarze roboczym odpowiadane jest wywołanie. Wywołanie describe-capabilities z kind lub tools nie zawiera server_version, bundle_version ani version_summary ani takiego wiersza, ponieważ odpowiada na temat narzędzi, a nie serwera.

Różnica jest zgłaszana i nigdy nie powoduje odmowy. Serwer uruchamia się i odpowiada na każde wywołanie dokładnie tak, jak gdyby obie wersje były zgodne. Co różnica oznacza dla instalacji desktopowej i jak ujednolicić obie wersje, opisano na stronie Podłączanie serwera MCP.

Dostęp do serwera przez HTTPS

aggrega mcp --transport http udostępnia protokół przez HTTP zamiast przez standardowe wejście i wyjście. mcp.transport w konfiguracji obszaru roboczego to klucz, który ta flaga nadpisuje, a jego wartość domyślna, stdio, jest tym, czego oczekuje klient uruchamiający polecenie — dlatego serwer, z którym łączą się inne osoby, ma w swojej konfiguracji transport: http, a klient uruchomiony z katalogu objętego tą konfiguracją nadal łączy się z serwerem przez jego własne strumienie. W obu przypadkach jest to ten sam serwer — ten sam obszar roboczy i te same powierzchnie protokołu — a zmienia się to, jak wiadomość do niego dociera, jak kończy się wywołanie i co musi posiadać ten, kto go uruchamia. Ta sekcja opisuje to, co konfiguruje operator; wpis, którego klient potrzebuje, aby połączyć się z działającym serwerem, znajduje się na stronie Podłączanie serwera MCP.

Adres nie wybiera transportu. --listen <address> lub mcp.listen, gdy flagi brak, wskazuje, gdzie listener się wiąże po wybraniu http, i nic więcej. Dlatego http bez adresu z żadnego z tych źródeł jest odrzucane, zanim cokolwiek zostanie powiązane, a odmowa wymienia oba. --listen podane, gdy transportem jest stdio — wpisanym jako --transport stdio, skonfigurowanym jako mcp.transport: stdio lub pozostawionym jako domyślny — również jest odrzucane, a komunikat wskazuje --transport http jako flagę, która udostępniałaby usługę pod tym adresem; --listen z pustą wartością jest odrzucane jako niewskazujące żadnego adresu, niezależnie od transportu. Natomiast adres podany tylko w konfiguracji pozostaje nieużywany przez serwer komunikujący się przez własne strumienie, który informuje o tym jednym wierszem w swoim strumieniu błędów, wskazując plik, który go ustawił, oraz mcp.transport: http. Ten ostatni przypadek celowo nigdzie nie jest odrzucany: tak właśnie uruchamia serwer klient, który startuje polecenie w katalogu, którego konfiguracja zawiera ustawienia listenera, a konfiguracja listenera, w której zapomniano o transport: http, nie uruchamia żadnego listenera, i to właśnie tam widać problem.

Serwer dostępny przez HTTP nie oferuje żadnego narzędzia, które uruchamia polecenie aggrega w osobnym procesie. Te narzędzia istnieją tylko dla klienta, który uruchomił ten serwer przez jego standardowe wejście i wyjście, na własnej maszynie tego klienta, gdzie wskazanie folderu lub flagi nie daje wywołującemu niczego, czego już nie miał. Wywołujący łączący się z serwerem przez HTTP nie jest właścicielem hosta, na którym serwer działa, dlatego polecenie, które działałoby na systemie plików tego hosta z uprawnieniami samego serwera, uruchamia się zamiast tego w terminalu na hoście. Narzędzi tych nie ma na liście ani w describe-capabilities, zamiast być oferowanymi i odrzucanymi, a na wywołanie wskazujące jedno z nich odpowiada się błędem, który o tym informuje. Jest to właściwość transportu, a nie ustawienie: żadna konfiguracja ich nie przywraca.

Przed wdrożeniem takiego serwera należy przeczytać Nic nie jest udostępniane bez poświadczenia. Każde żądanie do punktu końcowego zawiera poświadczenie i nie istnieje ustawienie, które obsłuży żądanie bez niego — ustawienie wybiera jedynie, czy ten serwer sam sprawdza token typu bearer, czy odczytuje wywołującego, którego sprawdził już proxy stojący przed nim.

Dwa kształty wdrożenia

Proces sam terminuje TLS. Należy ustawić mcp.tls.cert_file na łańcuch certyfikatów PEM, a mcp.tls.key_file na jego klucz prywatny, a listener będzie udostępniał HTTPS bezpośrednio pod podanym adresem. Oba pliki są odczytywane przy starcie procesu, więc wymieniony certyfikat zostaje wczytany po ponownym uruchomieniu procesu. Ustawienie jednego bez drugiego jest odrzucane przy starcie, zamiast przejścia na tryb zastępczy: certyfikatu bez klucza nie można przedstawić, klucz bez certyfikatu niczego nie identyfikuje, a literówka w jednej ścieżce nie jest powodem, by zacząć udostępniać nieszyfrowany ruch.

Proxy stojący przed procesem terminuje TLS i przekazuje ruch do ograniczonego listenera. Gdy oba klucze pozostaną nieustawione, listener udostępnia zwykły tekst, co jest akceptowane tylko na interfejsie loopback lub na gnieździe Unix — więc nic, co nie znajduje się już na tym hoście, nie może się z nim połączyć. Jest to kształt, którego używa odwrotne proxy, sidecar lub service mesh, i to w nim certyfikat znajduje się przed tym procesem, a nie w nim.

Listener bez szyfrowania pod jakimkolwiek innym adresem jest odrzucany, zanim cokolwiek zostanie powiązane, a odmowa wymienia oba klucze TLS. Żadne ustawienie tego nie znosi i żaden adres nie jest wyjątkiem: listener przyjmujący połączenia z sieci bez własnego certyfikatu nigdy nie jest bezpieczny, dlatego proces odmawia startu, zamiast uruchomić się w takim kształcie.

Formy adresu

--listen i mcp.listen przyjmują jedną z dwóch form:

  • host:port — adres TCP, na przykład 127.0.0.1:7777 lub 0.0.0.0:8443. Loopback oznacza 127.0.0.1, ::1 lub localhost, gdy każdy adres, na który ta nazwa się rozwiązuje, jest adresem loopback. Wszystko inne jest adresem sieciowym i wymaga certyfikatu: pusty host, czyli każdy interfejs maszyny; adres konkretnego interfejsu; oraz każda inna nazwa, nawet taka, która w tej chwili rozwiązuje się na adres loopback, ponieważ to, gdzie listener może się powiązać, nie powinno zależeć od rozwiązania nazwy, które może się zmienić bez jego wiedzy.
  • unix:, a po nim ścieżka w systemie plików — gniazdo domeny Unix, na przykład unix:/run/aggrega/mcp.sock. Gniazdo jest osiągalne tylko z hosta, na którym się znajduje, więc nie wymaga certyfikatu.

Ścieżka gniazda jest przyjmowana dokładnie tak, jak została zapisana, także ścieżka względna. Celowo nie jest rozwiązywana względem pliku konfiguracyjnego, który ją zadeklarował, ponieważ ten sam adres może też pochodzić z --listen, które nie ma pliku deklarującego — zob. dokąd wskazuje ścieżka względna.

Co przyjmuje listener

Jeden punkt końcowy, /mcp, przyjmujący POST. Każda wiadomość JSON-RPC jest osobnym żądaniem i nie jest utrzymywana żadna sesja: nic, co klient wyśle wcześniej, nie decyduje o tym, jak zostanie obsłużone późniejsze żądanie, nigdy nie jest tworzony identyfikator sesji, a nagłówek sesji lub wznawiania strumienia wysłany przez klienta jest ignorowany. Na każdą inną metodę w tym punkcie końcowym odpowiedzią jest 405 z Allow: POST, a na każdą inną ścieżkę 404 — oba przypadki są rozstrzygane przed sprawdzeniem poświadczenia, więc sondowanie nie dowiaduje się niczego z wezwania do uwierzytelnienia na ścieżce lub metodzie, która i tak niczego by nie udostępniła.

Na żądanie odpowiada się jednym obiektem JSON i kodem statusu — albo, gdy wywołanie zgłaszało postęp w drodze do tego obiektu, strumieniem zdarzeń kończącym się nim, co opisuje Informowanie o przebiegu długiego wywołania. Na powiadomienie — wiadomość bez id — odpowiedzią jest 202 z pustą treścią. Na wiadomość, która nie jest żadnym z nich, w tym na odpowiedź JSON-RPC, odpowiedzią jest 400, ponieważ klient wysyła do tego serwera żądania i powiadomienia, i nic więcej.

Obie wersje protokołu są tu obsługiwane dokładnie tak samo jak przez standardowe wejście i wyjście. Żądanie 2026-07-28 odzwierciedla swoją treść w nagłówkach transportu, aby pośrednik mógł je kierować bez parsowania treści: MCP-Protocol-Version zawiera wersję podaną w treści, Mcp-Method nazwę metody, a Mcp-Name cel — w przypadku metod, które wskazują go z nazwy. Na nagłówek niezgodny z treścią odpowiedzią jest 400. Klient 2025-06-18 zaczyna od uzgadniania initialize, na które odpowiada się bezstanowo; może przesłać nagłówek wersji wskazujący tę wersję lub go pominąć. Na żądanie wskazujące wersję, której serwer nie obsługuje, odpowiedzią jest 400 z listą dwóch obsługiwanych wersji, a na żądanie wskazujące metodę, której serwer nie obsługuje — 404.

mcp.allowed_origins jest sprawdzane tylko wtedy, gdy żądanie zawiera nagłówek Origin, co w praktyce oznacza, że wysłała je przeglądarka: na żądanie wskazujące pochodzenie, którego nie ma na liście, odpowiedzią jest 403, a żądanie bez takiego nagłówka jest obsługiwane. Klient, który nie jest przeglądarką, nie wysyła takiego nagłówka i nie potrzebuje wpisu. Klient działający w przeglądarce zawsze potrzebuje wpisu: lista jest pusta, dopóki operator jej nie wypełni, więc do tego czasu nie ma na niej żadnego pochodzenia i na każde żądanie przeglądarki odpowiedzią jest 403 — także na żądanie ze strony udostępnianej pod własnym adresem punktu końcowego. Wpis jest porównywany z nagłówkiem dokładnie, więc zapisuje się go tak, jak przeglądarka wysyła pochodzenie — schemat małymi literami, ://, host małymi literami oraz, jeśli nie jest domyślny dla schematu, : i port, na przykład https://app.example.com — a wpis ze ścieżką, końcowym /, bez schematu lub z wielką literą jest odrzucany przy wczytywaniu konfiguracji, z podaniem wpisu, ponieważ nigdy nie mógłby zostać dopasowany.

mcp.limits ogranicza przyjmowany ruch. Na treść przekraczającą max_body_bytes odpowiedzią jest 413, a treść nie jest czytana poza limit. Na żądanie, które nadchodzi, gdy w toku jest już max_concurrent_requests żądań, odpowiedzią jest 503, zamiast kolejkowania go za pracą, której nie widzi. Na wywołującego, który wysyła więcej niż requests_per_minute w ciągu minuty, odpowiedzią jest 429, liczone tylko dla tego wywołującego, więc jeden intensywnie wysyłający wywołujący niczego nie kosztuje innych. Wartość domyślna każdego limitu jest podana obok jego klucza w dokumentacji konfiguracji i żaden z nich nie ma wartości, która by go wyłączała.

Jeden proces, jeden obszar roboczy

Obszar roboczy, w imieniu którego odpowiada proces obsługujący, jest ustalany przy jego uruchomieniu. Wskazuje go --workspace-root; gdy flagi brak, dostarcza go zmienna AGGREGA_WORKSPACE_ROOT. Wskazany folder jest samym katalogiem głównym obszaru roboczego, bez przeszukiwania niczego powyżej, a folder, który nie istnieje, jest odrzucany z podaniem, które z tych dwóch źródeł go dostarczyło, i z przytoczeniem wartości w podanej postaci — przez listener przed powiązaniem z adresem, a przez serwer na standardowym wejściu i wyjściu w odpowiedzi na każde wywołanie działające w tym obszarze roboczym, jak opisuje Which workspace a call is answered in — dzięki czemu uruchomienie złożone przez klienta, a nie wpisane ręcznie, nadal mówi, co otrzymało. Gdy nie ma żadnego z nich, serwer na standardowym wejściu i wyjściu ustala obszar roboczy na podstawie katalogu, w którym go uruchomiono — tam, gdzie nic go w nim nie zakotwicza, każda odpowiedź dotycząca obszaru roboczego podaje, którego folderu użyto, a uruchomienie z pakietu desktopowego z pustym ustawieniem Workspace folder zamiast tego odrzuca wywołanie niewskazujące własnego obszaru roboczego, jak opisuje Which workspace a call is answered in — a listener jest odrzucany przed powiązaniem z adresem, chyba że obszar roboczy zostanie tam ustalony — proces osiągany przez HTTP odpowiada wywołującym, którzy nie widzą maszyny, więc obsługuje obszar roboczy wybrany przez operatora, a nie dowolny katalog, w którym akurat go uruchomiono. Aby obsługiwać kilka projektów, należy uruchomić jeden proces na każdy katalog główny projektu.

Wywołanie przychodzące przez HTTP nie może wskazać własnego obszaru roboczego. workspace_root i catalog_dirs są odrzucane z podaniem wysłanego argumentu, zamiast być po cichu pomijane: argument po cichu zignorowany wygląda dla nadawcy dokładnie tak samo jak uwzględniony. Katalogi katalogu przeszukiwane obok obsługiwanego obszaru roboczego to własne ustawienie workspace.catalog_dirs tego obszaru — lub, dla encji Release, której nadaje on własne katalogi w workspace.releases, ustawienie tej encji Release — zapisywane przez operatora. Przez standardowe wejście i wyjście oba argumenty są uwzględniane, ponieważ klient, który uruchomił serwer, działa na własnej maszynie wywołującego. Tam wpis catalog_dirs jest bezwzględny lub względny wobec katalogu głównego obszaru roboczego, z którego odczytywany jest względny release — katalogu głównego ustalonego najpierw przez własne workspace_root wywołania, przez uruchomienie lub przez katalog, w którym uruchomiono serwer, i pozostającego katalogiem odczytu tam, gdzie encja Release wskazana ścieżką bezwzględną przenosi wywołanie do własnego obszaru roboczego tej encji Release — a nie wobec katalogu, w którym działa serwer, jeśli jest to inne miejsce.

Ścieżka wskazana przez wywołanie również pozostaje wewnątrz tego obszaru roboczego. Przez HTTP argument ścieżki jest rozwiązywany względem katalogu głównego obszaru roboczego i odrzucany, jeśli sięga poza niego — ścieżka względna wychodząca z obszaru roboczego, ścieżka bezwzględna wskazująca inne miejsce oraz ścieżka względna prowadząca poza obszar roboczy przez znajdujące się w nim dowiązanie do pliku lub katalogu kończą się błędem podającym argument, a niepodającym ani katalogu głównego obszaru roboczego, ani miejsca, do którego ścieżka by sięgnęła; ścieżka względna jest przytaczana w postaci, w jakiej została wysłana. Każdy argument ścieżki jest oceniany według tego, dokąd prowadzi, zgodnie z definicją wnętrza podaną w The workspace boundary, niezależnie od tego, czy narzędzie go odczytuje, czy zapisuje — katalog, do którego gen-catalog zapisuje wynik, dokument, który edit-document zapisuje z powrotem, i encja, obok której pin zapisuje swoją blokadę, w takim samym stopniu jak dokument odczytywany przez narzędzie — więc ścieżka jeszcze nieutworzona pod dowiązaniem prowadzącym poza obszar roboczy jest odrzucana tak jak to dowiązanie, bez odczytu ani zapisu czegokolwiek. release wskazujący encję Release, którą wymienia konfiguracja obsługiwanego obszaru roboczego, jako build.authoring_release lub jako klucz workspace.releases, jest osiągany przez tę konfigurację i akceptowany przez dowiązanie, gdziekolwiek leży jego plik; żaden inny argument nie ma tego wyjątku. Gdy zamierzona ścieżka leży wewnątrz obszaru roboczego, ale zapisano ją jako bezwzględną, odmowa podaje zapis względem katalogu głównego do wysłania zamiast niej, dzięki czemu wywołujący, który odgadł niewłaściwą postać, dowiaduje się, jaka jest właściwa, a nie tylko, że się pomylił. Dotyczy to ścieżek wskazywanych przez wywołanie jako jego przedmiot — dokumentu do walidacji, encji Release do zbudowania, katalogu, do którego generowanie zapisuje wynik — i ścieżek, do których narzędzie zapisuje, w nie mniejszym stopniu niż tych, które odczytuje: wywołujący łączący się z serwerem przez sieć prosi niewidoczną dla siebie maszynę o odczyt i zapis plików, a obszar roboczy wybrany przez operatora jest miejscem, w którym ten odczyt i zapis są utrzymywane. Przez standardowe wejście i wyjście argumenty ścieżek każdego narzędzia zachowują kontrakt opisany przy tym narzędziu poniżej, gdzie ścieżka może być bezwzględna i może wskazywać poza obszar roboczy — osoba wywołująca jest właścicielem maszyny, na której działa serwer, więc ograniczanie jej do katalogu, który sama wybrała, niczego by nie dało. Dwa narzędzia, których sama operacja odpowiada wyłącznie na temat dokumentu zawartego w obszarze roboczym, insertion-point i edit-document, zachowują to na obu transportach i odrzucają dokument spoza obszaru roboczego, niezależnie od tego, czy tak go zapisano, czy osiągnięto go przez dowiązanie prowadzące poza obszar. Przez standardowe wejście i wyjście uwzględniana jest ścieżka wskazana przez wywołanie i nic poza nią. To, co operacja następnie odczytuje i zapisuje na własny rachunek, jest utrzymywane na obu transportach dokładnie tak jak przy wpisaniu tego samego polecenia w terminalu: przechodzenie ani wyszukiwanie nie odczytuje przez dowiązanie prowadzące poza obszar roboczy, plik wskazany ścieżką przez encję Release w obszarze roboczym lub jej Manifest nie jest odczytywany spoza obszaru roboczego — a plik wskazany przez encję Release, którą wywołanie wskazało poza obszarem roboczym, nie jest odczytywany spoza katalogu zawierającego tę encję Release — a plik zapisany pod katalogiem — obszarem roboczym lub katalogiem wskazanym przez wywołanie — pozostaje wewnątrz tego katalogu. The workspace boundary zestawia oba transporty z wierszem poleceń i edytorem oraz opisuje, co pozostaje otwarte przez standardowe wejście i wyjście: dokument w sklonowanym obszarze roboczym może nakłonić asystenta do wskazania ścieżki spoza obszaru roboczego, a ta ścieżka jest uwzględniana tak, jak ją wskazano.

Co odpowiedź mówi o systemie plików serwera

Przez HTTP odpowiedź podaje miejsce w systemie plików serwera względem katalogu głównego obszaru roboczego albo je zataja. Klient, który uruchomił serwer, działa tam, gdzie serwer, więc przez standardowe wejście i wyjście każda odpowiedź podaje każde miejsce tak, jak przechowuje je operacja — w postaci bezwzględnej, jeśli tak jest przechowywane — a każde z nich jest miejscem, które ten wywołujący już posiada. Wywołujący, który łączy się z nasłuchującym serwerem, nie wybrał żadnego z tych miejsc i nie może ich otworzyć, a serwer, który mu je ujawnił, nie może tego cofnąć. Dlatego przez HTTP odpowiedź przekazuje temu wywołującemu o miejscu jedną z dwóch rzeczy:

  • Miejsce wewnątrz obszaru roboczego jest podawane względem katalogu głównego obszaru roboczego — w tej samej postaci, jaką przyjmuje wysyłana ścieżka, więc nazwę odczytaną z jednej odpowiedzi można bez zmian odesłać w następnym wywołaniu. Encja Release w katalogu głównym to release.yaml, a jej plik blokady to release.lock.
  • Miejsce poza obszarem roboczym jest zatajane, podobnie jak sam katalog główny obszaru roboczego. Pole nie zawiera wartości — ma wartość null lub jest pominięte, a w attachment-container, którego odpowiedź zachowuje kształt, w jakim zgłasza ją każdy interfejs, file pozostaje puste — a znacznik obok niego, nazwany od pola z dopisanym _withheld, informuje, że wartość zatajono, a nie że jej nie ustawiono: workspace_root_withheld obok workspace_root, file_withheld obok file. Znacznik występuje tylko tam, gdzie coś zatajono. Katalog główny jest zatajany, ponieważ nasłuchujący serwer obsługuje dokładnie jeden obszar roboczy, więc to, gdzie ten obszar się znajduje, nie jest potrzebne do nazwania tego, co jest w jego wnętrzu.

O tym, czy miejsce jest wewnątrz, decyduje sposób zapisu ścieżki, a nie plik, do którego prowadzi. Ścieżka zapisana przez cel dowiązania symbolicznego zamiast przez katalog główny, nad którym uruchomiono serwer, oraz ścieżka, która wychodzi poza katalog główny i do niego wraca, są traktowane jako leżące poza obszarem roboczym i zatajane. Ocena skłania się ku przekazaniu mniej informacji, nigdy ku podaniu miejsca poza obszarem roboczym.

Przez HTTP czytelny tekst odpowiedzi podlega tej samej regule. Gdy tekst, wiersz diagnostyki lub komunikat błędu wskazuje miejsce należące do obszaru roboczego — jego katalog główny lub cokolwiek pod nim, plik konfiguracyjny, z którego odczytano jego konfigurację, katalog, z którego odczytywany jest jego katalog encji — miejsce to jest zapisywane względem katalogu głównego albo jako (location withheld), jeśli leży poza obszarem roboczym lub jest katalogiem głównym. Tekst, który odpowiedź tworzy o własnym obszarze roboczym, nazywa go obszarem roboczym obsługiwanym przez ten serwer. Miejsce spoza tego wszystkiego, które operacja wpisuje do komunikatu, nie jest rozpoznawane jako takie i dociera w postaci, w jakiej je zapisano.

Odpowiedzi, których to dotyczy, przez HTTP:

  • list-entities, list-releases, cache-status, registry-list, search, attach-candidates, connection-candidates, insertion-point, attachment-container, connection-at-position i edit-document zatajają workspace_root. Ścieżki, które już podają względem katalogu głównego — plik źródłowy encji, ścieżka encji Release i jej plik blokady w lockfiles, dokument, którego dotyczy punkt wstawienia lub edycja, pliki zapisane przez edycję — wyglądają tak samo w obu transportach.
  • cache-status zataja również to, co wskazuje wtyczkę wczytaną przez serwer z pliku na jego hoście. Taka tożsamość ma wartość null na swoim miejscu w provenance[].identities, każda inna tożsamość zachowuje swoją pozycję, a wpis jest oznaczony identities_withheld. note skompilowanego modułu to jedno zdanie wymieniające tożsamości, dla których moduł zbudowano, więc gdy którakolwiek z nich wskazuje taki plik, note jest w całości pomijane i oznaczane note_withheld; digest modułu pozostaje. Tożsamość wskazująca odwołanie do rejestru lub encję Plugin jest podawana w całości, podobnie jak note wymieniające tylko takie tożsamości. label artefaktu źródłowego to jego miejsce w pamięci podręcznej, zapisane na podstawie hosta i ścieżki URL, z którego go rozwiązano, więc dla repozytorium odczytanego z własnego systemu plików serwera — przez URL file:// lub ścieżkę — label jest pomijany i oznaczany label_withheld, jego size i digest pozostają, a label wskazujący host sieciowy jest podawany w całości. Tekst listy zawiera (location withheld) tam, gdzie wskazałby takie miejsce.
  • validate podaje target, a dla encji Release także release, względem katalogu głównego; dla całego katalogu encji target jest katalogiem głównym i jest zatajany. Miejsce w diagnostics lub notices podlega regule dla tekstu.
  • build podaje release względem katalogu głównego, a kompilacja, która najpierw rozwiązała swoje zależności, zawiera dependency_resolution w postaci, w jakiej odpowiada pull. Kompilacja wywołana z write podaje katalog, do którego zapisała, jako output_dir, który ma wartość dist — względem katalogu głównego — a każda ścieżka w files jest względna wobec tego katalogu. refusal oraz każdy wpis jego findings podaje swój file względem katalogu głównego albo go zataja, jeśli dokument leży poza obszarem roboczym. advisories, deprecations, declined_external_inputs i każdy message w refusal podlegają regule dla tekstu.
  • pull podaje release i lockfile względem katalogu głównego. diagnostics i incomplete_external_inputs podlegają regule dla tekstu. source każdego wpisu resolved jest podawane w całości w obu transportach: wskazuje to, co zrobiło uruchomienie, nigdy miejsce na hoście.
  • describe podaje release encji Release względem katalogu głównego, a file encji względem katalogu głównego, jeśli jej dokument leży wewnątrz obszaru roboczego; dla encji odczytanej z katalogu encji spoza obszaru roboczego file jest zatajany. mapping_diagnostics i deprecations podlegają regule dla tekstu.
  • lint podaje location.file każdego wyniku względem katalogu głównego albo go zataja, jeśli encja leży poza obszarem roboczym. message i suggest wyniku podlegają regule dla tekstu.
  • pin podaje entity i lock względem katalogu głównego; tak samo czyni pin zawarty w publikacji.
  • gen-catalog podaje każdy plik wymieniony w output względem katalogu głównego.
  • import zataja workspace_root oraz output_dir, jeśli szkice trafiły do tego katalogu głównego; katalog podany w output_dir jest wskazywany nazwą względną wobec katalogu głównego. Każda ścieżka szkicu w written i drafts jest względna wobec output_dir, więc miejsce, do którego trafiły szkice, jest w odpowiedzi w każdym przypadku. message diagnostyki oraz params_summary, rationale i swap_hint decyzji to proza utworzona przez importer i podlegają regule dla tekstu.
  • config-show i plugin-list zatajają więcej niż katalog główny, ponieważ większość tego, co zgłaszają, to konfiguracja wskazująca miejsca, jak opisano w sekcji Czego nasłuchujący serwer nie ujawnia o swoim hoście.
  • scaffold zapisujące przykład podaje dir tak, jak został wysłany, względem katalogu głównego, a każdą ścieżkę w files względem tego katalogu; tworzenie szkicu i wypisywanie listy nie wskazują żadnego miejsca.
  • Narzędzia publikacji, sign-artifacts, deprecate-artifact, get-schema, explain-error i describe-capabilities same nie wskazują żadnego miejsca na hoście. Komunikat błędu każdego z nich podlega regule dla tekstu: odmowa zgłaszana przez obszar roboczy w trybie offline podaje jego .aggrega-config.yaml względem katalogu głównego.
  • Argument ścieżki odrzucony za wyjście poza obszar roboczy jest odrzucany bez podania katalogu głównego ani miejsca, do którego by prowadził, jak opisano wyżej.

Jak kończy się wywołanie

Zamknięcie połączenia anuluje przenoszone przez nie wywołanie. To sygnał anulowania w tym transporcie: serwer traktuje rozłączenie wywołującego jako anulowanie tego żądania, kończy wykonywaną pracę i nie zapisuje dla niego nic więcej. Komunikat anulowania nie jest tu potrzebny ani oczekiwany — odwrotnie niż w przypadku standardowego wejścia i wyjścia, gdzie nie ma strumienia na żądanie, który można zamknąć, i klient kończy wywołanie, podając jego id. Komunikat anulowania, który mimo to dotrze przez HTTP, jest przyjmowany i niczego nie kończy.

Zatrzymanie procesu opróżnia nasłuchujący serwer. Przerwanie lub żądanie zakończenia od nadzorcy albo środowiska uruchomieniowego kontenerów sprawia, że serwer przestaje przyjmować połączenia i pozwala dokończyć wywołanie, na które już odpowiada, w ograniczonym czasie, więc wywołujący, który poprosił o coś przed zatrzymaniem, nadal otrzymuje odpowiedź. Wywołanie, które nie zakończy się w tym czasie, traci połączenie. Drugie żądanie zatrzymania natychmiast kończy proces.

Żywotność i gotowość pod osobnym adresem

mcp.health.listen to miejsce, w którym nadzorca pyta, czy ten proces działa i czy może odpowiedzieć na wywołanie. Po podaniu adresu w jednej z powyższych form drugi nasłuchiwacz odpowiada tam na GET /healthz i GET /readyz. Jeśli klucz zostanie pominięty — co jest ustawieniem domyślnym — drugi nasłuchiwacz nie jest uruchamiany i żadne z tych sprawdzeń nie jest nigdzie obsługiwane.

Obie odpowiedzi mówią co innego i właśnie z powodu tej różnicy są dwie. /healthz odpowiada 200 od chwili uruchomienia procesu, co stanowi całość tego, co deklaruje żywotność: proces działa, a nadzorca, który nie otrzymuje żadnej odpowiedzi, powinien go zrestartować. /readyz odpowiada 503, dopóki obszar roboczy obsługiwany przez ten proces nie zostanie rozwiązany, a punkt końcowy nie zostanie powiązany z adresem, a od tej chwili 200 — dzięki temu load balancer wstrzymuje ruch, dopóki proces rzeczywiście nie będzie mógł odpowiedzieć na wywołanie, zamiast kierować pierwsze żądanie do procesu, który wciąż się uruchamia. Każda odpowiedź to kod statusu z pustą treścią; nie jest wymagane żadne poświadczenie i nic, co wysłał wywołujący, nie jest odczytywane.

Punkt końcowy nigdy nie odpowiada na te dwie ścieżki. GET /healthz i GET /readyz pod adresem wskazanym przez mcp.listen otrzymują odpowiedź 404, dokładnie tak jak każda inna ścieżka, której ten punkt końcowy nie obsługuje, zarówno z tokenem, jak i bez niego. Odpowiadanie tam na sondę dawałoby wszystkiemu, co dociera do punktu końcowego, darmową informację o tym, czy proces działa, a wraz z nią darmowy sposób zmuszenia go do pracy — na nasłuchiwaczu, który poza tym odrzuca każde żądanie bez poświadczenia.

Położenie adresu kontroli stanu można wybrać dowolnie i nie jest ono ograniczone tak jak mcp.listen. Żaden adres nie jest dla niego odrzucany. Należy wskazać interfejs loopback lub gniazdo Unix, bo do tego on służy: dla nadzorcy, load balancera lub środowiska uruchomieniowego kontenerów działającego obok tego procesu na tym samym hoście. Wszystko, co może dotrzeć do wybranego adresu, może odczytać te dwie odpowiedzi, więc adres osiągalny z otwartej sieci publikuje je w otwartej sieci.

Bez poświadczenia nic nie jest obsługiwane

Każde żądanie do punktu końcowego niesie poświadczenie, a to, jakie, zależy od tego, czy proxy znajdujące się przed serwerem już je sprawdziło. Domyślnie jest to token typu bearer, który ten serwer weryfikuje sam, opisany w dalszej części tej sekcji. Po ustawieniu mcp.authorization.trusted_proxy jest to natomiast nagłówek ustawiany przez to proxy, opisany w sekcji Odczytywanie wywołującego z proxy znajdującego się przed serwerem — gdzie żaden token nie jest w ogóle odczytywany. Żaden z tych wariantów nie obsługuje żądania, które nie przedstawia niczego.

Domyślnie serwer sam sprawdza token typu bearer. Odczytuje token z nagłówka Authorization i akceptuje go tylko wtedy, gdy podpis weryfikuje się kluczem publikowanym przez serwer autoryzacji, token wskazuje mcp.authorization.issuer jako wystawcę, wymienia własny mcp.authorization.resource tego wdrożenia wśród odbiorców, mieści się w swoim oknie ważności i określa, kto go przedstawił. Token, który nie spełnia któregokolwiek z tych warunków, otrzymuje odpowiedź 401 z error="invalid_token" dodanym do tego samego wyzwania, które otrzymuje wywołujący bez żadnego poświadczenia — a odpowiedź jest identyczna niezależnie od tego, które sprawdzenie go odrzuciło, więc wywołujący dowiaduje się, że potrzebuje innego tokenu, a nie tego, która część wysłanego tokenu była błędna. Akceptowane są wyłącznie asymetryczne algorytmy podpisu: token niepodpisany oraz token wskazujący algorytm symetryczny są odrzucane, zanim cokolwiek zostanie z nich odczytane.

Token może określać, jakiego jest rodzaju, i akceptowane są cztery formy. JWT może zawierać nagłówek typ wskazujący jego własny typ. Ten serwer akceptuje at+jwt i application/at+jwt, czyli dwie pisownie zarejestrowane dla tokenu dostępu; JWT, który mówi jedynie, że token jest tokenem JWT; oraz token, który nie deklaruje żadnego typu. Wszystko inne otrzymuje odpowiedź 401, dokładnie tak jak każdy inny odrzucony token. Zbiór jest stały i żadne ustawienie go nie rozszerza ani nie zawęża, ponieważ o tym, która forma tam występuje, decyduje serwer autoryzacji, który wystawił token, a nie wdrożenie, które go otrzymuje. Akceptowanie JWT oznacza, że sam zadeklarowany typ nie odróżnia już tokenu dostępu od tokenu tożsamości — rozróżnia je sprawdzenie odbiorcy i dlatego to właśnie ono jest kluczowe: odbiorcą tokenu tożsamości jest klient, dla którego go wystawiono, nigdy własny mcp.authorization.resource tego wdrożenia, więc token wystawiony dla czegokolwiek innego niż to wdrożenie jest odrzucany niezależnie od tego, jak sam siebie określa.

Które serwery autoryzacji to dopuszcza. Microsoft Entra ID wystawia tokeny dostępu o typie JWT. Keycloak wystawia at+jwt, a JWT, gdy włączony jest jego tryb zgodności z OpenID Connect. Auth0 wystawia JWT w ramach własnego profilu tokenów i at+jwt w ramach profilu RFC 9068. Token z każdego z nich przechodzi to sprawdzenie niezależnie od tego, którą z dwóch form zawiera. Okta nie jest obsługiwana: jej tokeny dostępu deklarują własny typ, który nie jest żadną z czterech powyższych form, więc ten serwer je odrzuca.

Odrzucony token pozostawia przyczynę w strumieniu błędów serwera. Wywołujący dowiaduje się jedynie, że to, co przedstawił, nie zostało zaakceptowane; proces obsługujący zapisuje jeden wiersz wskazujący sprawdzenie, które odrzuciło token — odbiorcę, wystawcę, okno ważności, podpis, identyfikator klucza, zadeklarowany typ i każde z pozostałych. Dzięki temu wierszowi wdrożenie odrzucające każde żądanie może zdiagnozować ten, kto je uruchamia, a nie tylko ten, kto je wywołuje. Wiersz nie zawiera żadnej części tokenu. Żądanie bez żadnego poświadczenia nie zapisuje wiersza, ponieważ otrzymanie wyzwania jest sposobem, w jaki klient w ogóle dowiaduje się, skąd uzyskać token, więc jest to pierwsza rzecz, którą robi każdy poprawnie działający klient.

Token należy umieszczać w nagłówku i nigdzie indziej. Token wysłany jako parametr zapytania access_token otrzymuje odpowiedź 400 i nigdy nie jest odczytywany, ponieważ adres jest zapisywany przez każdy log proxy, historię przeglądarki i nagłówek referrer, przez które przechodzi żądanie, więc token, który dotarł w ten sposób, został już ujawniony. Serwer nigdy nie zapisuje tokenu w logu, nigdy go nigdzie nie wysyła i nigdy nie uzyskuje ani nie wymienia tokenu w imieniu wywołującego: odczytuje to, co przedstawiono, podejmuje decyzję i niczego nie zachowuje. Podmiot wskazany przez token jest zapisywany i z niczym nie jest porównywany.

Klucze weryfikacyjne pochodzą z serwera autoryzacji lub ze wskazanego pliku. Gdy mcp.authorization.jwks_file nie jest ustawiony, serwer odczytuje metadane serwera autoryzacji pod jego dobrze znanym adresem, podąża za opublikowanym tam jwks_uri i przechowuje znalezione klucze; token podpisany identyfikatorem klucza, którego te klucze nie zawierają, powoduje jedno ponowne odczytanie, i nie więcej niż jedno w krótkim przedziale czasu, więc wywołujący wysyłający zmyślone identyfikatory kluczy nie może wymusić jednego żądania wychodzącego na każde żądanie. Odczytanie ich z serwera autoryzacji wymaga adresu kluczy https lub zwykłego http na tej maszynie: jwks_uri będący zwykłym http na innym hoście nigdy nie jest odpytywany, a przekierowanie, które skierowałoby którykolwiek odczyt na zwykłe http na innym hoście, nie jest wykonywane, ponieważ ktoś znajdujący się na niechronionej ścieżce do kluczy mógłby odpowiedzieć własnymi kluczami. Token wymagający tych kluczy otrzymuje wówczas odpowiedź 503, dokładnie tak jak w przypadku kluczy, których nie da się odczytać, a wiersz zapisywany przez serwer dla tego żądania mówi, że odczyt odrzucono z powodu zwykłego http, a nie że nie udało się połączyć z serwerem autoryzacji — poprawka leży po stronie serwera autoryzacji, który musi publikować metadane i klucze przez https. Gdy jwks_file jest ustawiony, klucze są odczytywane z tego pliku, a serwer autoryzacji nigdy nie jest kontaktowany — czego potrzebuje obszar roboczy deklarujący offline: true, a taki obszar roboczy jest odrzucany przed powiązaniem nasłuchiwacza z adresem, jeśli plik nie zostanie wskazany. Gdy kluczy nie da się w ogóle odczytać, żądania otrzymują odpowiedź 503 bez wyzwania: nic, co przedstawił wywołujący, nie zostało uznane za niewystarczające, więc wysłanie go po inny token nie pomogłoby.

Jedyną odpowiedzią udzielaną bez żądania poświadczenia jest dokument metadanych chronionego zasobu. Klient musi go odczytać, zanim będzie mógł uzyskać token, więc wymaganie tokenu w tym miejscu zamknęłoby jedyne wejście. Dokument jest udostępniany pod /.well-known/oauth-protected-resource, a — jeśli adres wskazywany przez mcp.authorization.resource ma własną ścieżkę — także pod tą znaną ścieżką z dołączoną tą ścieżką. Są to dwa miejsca, w których klient go szuka, a forma z dołączoną ścieżką to adres wskazywany w wyzwaniu. Dokument zawiera ten adres jako nazwę zasobu tego wdrożenia, mcp.authorization.issuer jako serwer autoryzacji, od którego należy uzyskać token, header jako jedyny sposób przedstawienia tokenu oraz trzy nazwy zakresów podane poniżej.

Wystawca jest adresem https, chyba że serwer autoryzacji działa na tej maszynie. Zwykły http jest akceptowany dla wystawcy pod localhost, 127.0.0.1 lub ::1, co odpowiada lokalnemu testowi z lokalnym serwerem autoryzacji; wystawca ze zwykłym http na dowolnym innym hoście jest odrzucany, zanim nasłuchiwacz się zwiąże, a komunikat odmowy wskazuje mcp.authorization.issuer i prosi o adres https. Dotyczy to każdego trybu — z kluczami odczytywanymi od wystawcy, z mcp.authorization.jwks_file i z serwerem proxy przed serwerem — ponieważ każdy tryb publikuje wystawcę w tym dokumencie: klient, który za nim podąża, przeprowadza przepływ autoryzacji pod tym adresem, więc przy zwykłym http kod autoryzacji i uzyskany token przechodziłyby przez sieć bez ochrony, niezależnie od tego, czy ten serwer kiedykolwiek odczytuje stamtąd klucz. Tam, gdzie odczytuje stamtąd klucze, ktoś znajdujący się na tej ścieżce mógłby też odpowiedzieć własnymi kluczami, a każdy podpisany nimi token zostałby przyjęty.

Nazwy zakresów publikowane przez to wdrożenie to aggrega:read, aggrega:workspace-write i aggrega:registry-write. Te nazwy należy zarejestrować w serwerze autoryzacji i o nie klient go prosi, a wyzwanie otrzymywane przez odrzuconego wywołującego wskazuje aggrega:read jako zakres do uzyskania w pierwszej kolejności. Co dopuszcza każdy z nich — oraz drugie ograniczenie, które to wdrożenie nakłada samo na siebie — opisano poniżej w sekcji Do czego wywołujący ma dostęp.

Odczytywanie wywołującego z serwera proxy przed serwerem

Jeśli serwer proxy przed serwerem już weryfikuje tokeny, mcp.authorization.trusted_proxy nakazuje temu serwerowi odczytywać wywołującego od niego zamiast sprawdzać token po raz drugi. Należy podać principal_header, nagłówek, który ten serwer proxy ustawia, aby wskazać wywołującego, oraz opcjonalnie scopes_header, drugi nagłówek zawierający zakresy tego wywołującego rozdzielone spacjami. Każdy z nich jest nazwą nagłówka HTTP, taką jak X-Forwarded-User, bez spacji ani dwukropka; nazwa w innej postaci jest odrzucana podczas wczytywania konfiguracji z podaniem klucza, podobnie jak pusty principal_header — aby pozostawić ten tryb wyłączony, należy pominąć cały blok. Odczytywane są wyłącznie te dwa nagłówki: nie uczestniczy żaden nagłówek przekazywanego adresu ani żaden inny. Żądanie bez nagłówka podmiotu otrzymuje odpowiedź 401, a w tym trybie żaden token nie jest w ogóle odczytywany — żądanie z tokenem, który ten serwer w przeciwnym razie by odrzucił, jest obsługiwane, gdy obecny jest nagłówek podmiotu, a żądanie z tokenem, który ten serwer by przyjął, nadal jest odrzucane, gdy tego nagłówka brak.

Ten tryb jest akceptowany tylko na interfejsie pętli zwrotnej lub gnieździe Unix, a proces jest odrzucany, zanim zwiąże się z jakimkolwiek innym adresem. Nagłówek jest wiarygodny dokładnie wtedy, gdy nikt poza serwerem proxy nie może go ustawić. Na adresie osiągalnym z sieci może go ustawić cokolwiek — więc nasłuchiwacz w tym trybie na takim adresie pozwoliłby każdemu wywołującemu przedstawić się, jak tylko zechce. Komunikat odmowy wskazuje oba kolidujące ustawienia, więc można ją znieść, zmieniając adres lub usuwając blok.

To, co twierdzi serwer proxy, ten serwer przyjmuje za prawdę — i na tym polega ten układ. W tym trybie ten serwer nie sprawdza żadnego podpisu i nie porównuje wskazanego wywołującego z niczym, dokładnie tak jak nie porównuje z niczym podmiotu tokenu. To, czy serwer proxy zweryfikował to, co przekazał, i czy cokolwiek może dotrzeć do tego nasłuchiwacza z pominięciem serwera proxy, jest sprawą wdrożenia; opisane wyżej ograniczenie umożliwia poprawne rozwiązanie tych kwestii, ale nie gwarantuje, że zostały rozwiązane.

Ustawienie mcp.authorization.trusted_proxy nie znosi pozostałych wymagań. issuer i resource są nadal potrzebne, ponieważ dokument metadanych jest nadal publikowany, a wyzwanie nadal go wskazuje — klient za serwerem proxy nadal musi się dowiedzieć, skąd uzyskać token, który serwer proxy sprawdzi. Z tego samego powodu wystawca nadal musi być adresem https, chyba że działa na tej maszynie: ten klient uzyskuje token od wystawcy, więc wystawca ze zwykłym http na innym hoście jest w tym trybie odrzucany, zanim nasłuchiwacz się zwiąże, dokładnie tak jak w każdym innym, mimo że ten serwer niczego od niego nie odczytuje.

Do czego wywołujący ma dostęp

O tym, do czego wywołujący ma dostęp przez HTTP, decydują dwa ograniczenia, ustalane przez różne osoby. Pierwszym jest własne poświadczenie wywołującego; drugim — to, co ten serwer w ogóle udostępnia. Oba są odczytywane przed uruchomieniem czegokolwiek, z deklaracji, którą każda operacja składa o sobie, i docierają do klienta w różnych miejscach: lista narzędzi pokazuje, co ten serwer udostępnia i ogłasza, a odpowiedź na każde wywołanie pokazuje, na co pozwala poświadczenie.

Każda operacja deklaruje, jak daleko sięgają jej skutki; istnieją cztery rodzaje, od najwęższego do najszerszego:

  • Nie sięga niczego — odczytuje definicję, sprawdza, co przypina encja Release, renderuje artefakty w pamięci i je zwraca. Nie pozostawia niczego: nic nie jest zapisywane, a odpowiedź jest całością tego, co wytwarza.
  • Sięga obszaru roboczego — zapisuje wewnątrz obszaru roboczego obsługiwanego przez ten proces: plik blokady encji Release, pamięć podręczną artefaktów, wygenerowane encje, edytowany dokument.
  • Sięga rejestru — publikuje, podpisuje lub dołącza znacznik wycofania do czegoś już opublikowanego. To, co zmienia, wpływa na to, co rozwiązuje każdy konsument tego rejestru, i niczego z tego nie można odwołać u nikogo, kto już to pobrał.
  • Sięga maszyny — zmienia to, co współdzielą wszystkie obszary robocze na hoście, w tym magazyn skompilowanych modułów, wspólny dla nich wszystkich plik konfiguracyjny oraz magazyn poświadczeń. Pamięć podręczna, którą pojedynczy projekt utrzymuje we własnym katalogu pamięci podręcznej, nie należy do tego rodzaju, a cache-status podaje, do którego z tych rodzajów należy każda wymieniona przez niego pamięć podręczna.

Rodzaj jest właściwością operacji, a nie narzędzia, które ją oferuje, i obejmuje to, co operacja pozostawia — a nie miejsce, w którym dany interfejs umieszcza zwracaną odpowiedź. Renderowanie encji Release wytwarza artefakty jako odpowiedź, więc nie sięga niczego; wiersz poleceń, który następnie zapisuje te artefakty we wskazanym katalogu, dostarcza tę odpowiedź, a nie sięga dalej. Gdyby przyjąć odwrotne rozumienie, każda operacja odpowiadająca treścią przyjmowałaby rodzaj interfejsu, który akurat ją zapisał, i rodzaj przestałby w ogóle być właściwością operacji. Z tego samego powodu describe odczytujące encję według jej odwołania do rejestru nie sięga niczego: kontaktuje się z tym rejestrem, aby pobrać odpowiedź, i niczego nie pozostawia ani w rejestrze, ani na tej maszynie, a to, z którymi rejestrami może się kontaktować, opisano w sekcji Które poświadczenia zużywa wywołanie. Pojedyncze wywołanie może jednak sięgać dalej niż rodzaj jego operacji, jeśli samo żąda zapisu: kompilacja wysłana z write zapisuje artefakty w obszarze roboczym obsługiwanym przez ten serwer, więc to wywołanie sięga obszaru roboczego, podobnie jak kompilacja, która najpierw rozwiązuje swoje zależności.

Zakres dopuszcza rodzaj, a każdy zakres zapisu obejmuje zakres odczytu. aggrega:read dopuszcza operację, która nie sięga niczego. aggrega:workspace-write dopuszcza operację sięgającą obszaru roboczego i obejmuje zakres odczytu. aggrega:registry-write dopuszcza operację sięgającą rejestru i również obejmuje zakres odczytu. Klient prosi więc serwer autoryzacji o potrzebny zakres zapisu i nie musi dodatkowo prosić o zakres odczytu.

Żaden zakres nie dopuszcza rodzaju „maszyna” i żadne ustawienie go nie dodaje. Operacje tego rodzaju są dostępne wyłącznie w narzędziach, które uruchamiają polecenie aggrega w osobnym procesie, a serwer osiągany przez HTTP nie oferuje żadnego z nich, z powodu opisanego wyżej w sekcji Dostęp do serwera przez HTTPS. Należy je uruchamiać w terminalu na hoście.

Lista narzędzi pokazuje każde narzędzie, które ten serwer udostępnia i ogłasza, niezależnie od zakresów posiadanych przez poświadczenie wywołującego, a poświadczenie decyduje, które z nich wywołanie może uruchomić. describe-capabilities indeksuje i definiuje ten sam zestaw. Na wywołanie, którego poświadczenie nie dopuszcza, serwer odpowiada 403 z error="insufficient_scope" w wyzwaniu, wskazując jedyny zakres, który by je dopuścił, i nic z tego, o co prosiło wywołanie, nie zostało uruchomione. Tę właśnie odmowę obsługuje step-up protokołu: klient implementujący step-up prosi o ponowne zalogowanie się dla zakresu wskazanego w wyzwaniu. Lista nie zmienia się wraz z poświadczeniem, więc klient, który zalogował się ponownie, ma już właściwe. Poświadczenie bez żadnego z trzech zakresów otrzymuje tę samą listę narzędzi i nie może wywołać żadnego z nich, łącznie z describe-capabilities.

Build to przypadek, który warto znać. Sam w sobie niczego nie zmienia, więc wymaga tylko aggrega:read, ale build, który zapisuje, wymaga aggrega:workspace-write: build wysłany z write zapisuje swoje artefakty w dist/ w katalogu głównym obszaru roboczego, a build, który najpierw rozwiązuje zależności, zapisuje plik blokady — niezależnie od tego, czy wywołanie poprosiło o to przez auto_pull, czy zrobiło to własne ustawienie auto_pull obszaru roboczego. Narzędzie jest widoczne dla wywołującego z zakresem odczytu jak każde inne, a buildy pozostające w pamięci są dla niego rzeczywiście dostępne; odrzucane, ze wskazaniem aggrega:workspace-write, jest wywołanie, które zapisuje.

Klientowi, który nie obsługuje step-up, nadal można nadać zakresy zapisu, a rozstrzyga się to na serwerze autoryzacji. Administrator serwera autoryzacji ustawia zakresy zapisu jako zakresy domyślne dla tego klienta — zakresy umieszczane w każdym tokenie wydawanym temu klientowi, niezależnie od tego, czy klient o nie prosił — dzięki czemu token uzyskany przy pierwszym logowaniu już je zawiera. Klient, który przy każdym połączeniu rejestruje się w serwerze autoryzacji od nowa, jest tam za każdym razem nowym klientem, a ustawienie z wcześniejszej rejestracji nie przechodzi dalej; dla takiego klienta obowiązują zakresy domyślne, które serwer autoryzacji nadaje każdemu rejestrowanemu klientowi. Kosztem jest to, że każde logowanie przez tego klienta niesie wtedy uprawnienia zapisu, niezależnie od tego, czy bieżąca praca ich potrzebuje — a gdy domyślne są te nadawane przy rejestracji, takie uprawnienia ma też każdy klient zarejestrowany w ten sposób. Jako domyślny należy ustawić tylko ten zakres zapisu, którego praca wymaga: aggrega:workspace-write i aggrega:registry-write dopuszczają różne rodzaje i żaden nie implikuje drugiego.

mcp.deny_reach to miejsce, w którym administrator tego serwera wycofuje z niego dany rodzaj, i jedno z dwóch ustawień skracających listę narzędzi. Należy wymienić rodzaje — none, workspace, registry, machine — których ten serwer nie udostępnia; każde narzędzie sięgające jednego z nich znika z listy narzędzi każdego wywołującego i z describe-capabilities, niezależnie od tokenu wywołującego, a wywołane mimo to jest odrzucane z błędem wskazującym to ustawienie. Jest to ograniczenie samego serwera, a nie wywołującego, więc żadne poświadczenie go nie znosi, a odmowa nie zawiera wyzwania: serwer przeznaczony wyłącznie do odczytów wymienia tu workspace, registry i machine i wtedy nie może publikować nawet dla wywołującego, którego token ma wszystkie trzy zakresy. Pominięcie ustawienia, co jest wartością domyślną, oznacza, że serwer nie wycofuje żadnego rodzaju, więc o tym, jakie rodzaje osiąga wywołanie, decydują zakresy wywołującego. Podanie machine jest akceptowane i niczego nie zmienia, ponieważ nic tego rodzaju nie jest tu w ogóle oferowane. Wartość spoza tych czterech jest odrzucana przy wczytywaniu konfiguracji, zamiast zostać pominięta — operator, który pomylił nazwę rodzaju, poprosił o ograniczenie, a obsługiwanie go po cichu bez niego byłoby niewłaściwą odpowiedzią.

mcp.announce_tools to drugie ustawienie skracające listę narzędzi, a oba nie są tym samym ograniczeniem. deny_reach wycofuje możliwość: operacja wskazanego tam rodzaju nie jest tu udostępniana w ogóle, dla nikogo. announce_tools wycofuje jedynie ogłoszenie: pominięte przez nie narzędzia to możliwości, które serwer nadal ma, a ustawienie odpowiada na własny limit klienta co do liczby rejestrowanych narzędzi. Gdy ustawione są oba, wygrywa wycofanie, więc narzędzie wycofanego rodzaju pozostaje nieobecne niezależnie od tego, jak wskazuje je announce_tools, a odmowa, którą otrzymuje wywołujący, wskazuje wycofanie. Nic, co skraca listę, nie odczytuje zakresów wywołującego: brak zakresu powoduje odrzucenie wywołania i nigdy nie usuwa narzędzia z listy. Pozostałe szczegóły opisuje sekcja Zawężanie tego, co serwer ogłasza.

Które poświadczenia zużywa wywołanie

Podpisywanie bezkluczowe przez listener pobiera tożsamość z identity_token przesłanego w wywołaniu i z niczego innego. Token przesłany w wywołaniu jest poświadczeniem, które posiada wywołujący: musiał go uzyskać, jest z nim powiązany, a złożony nim podpis można mu przypisać. Każde inne miejsce, z którego mogłaby pochodzić tożsamość, należy do tego, kto uruchomił ten proces, dlatego w tym transporcie mechanizm rozstrzygania otrzymuje środowisko, które niczego nie zwraca. AGGREGA_IDENTITY_TOKEN i SIGSTORE_ID_TOKEN w środowisku serwera nie są odczytywane, a otoczeniowy punkt końcowy OIDC GitHub Actions nie jest wywoływany. Są one poza zasięgiem, a nie jedynie odradzane — mechanizm rozstrzygania nie ma tam czego znaleźć. Wywołanie, które nie przesyła identity_token, jest odrzucane, a odmowa wskazuje identity_token jako to, co należy przesłać, i nie wymienia żadnej zmiennej ani punktu końcowego: wywołujący, który nie siedzi przy klawiaturze tej maszyny, nie może niczego tu wyeksportować, więc wskazanie zmiennej oznaczałoby polecenie mu przygotowania czegoś, co nie może zmienić odpowiedzi.

Klucza podpisującego przechowywanego na tej maszynie nie można wybrać żadną z dróg. key_path jest odrzucany, zanim cokolwiek zostanie rozstrzygnięte, i nie występuje w schematach argumentów, które ogłaszają tu publish-entity, sign-artifacts i deprecate-artifact, więc wywołującemu nigdy nie jest oferowany argument, który nie mógłby się powieść. Klucz podpisujący wskazany we własnej konfiguracji obsługiwanego obszaru roboczego również nie jest używany — signing.key_path, niezależnie od tego, czy jest ustawiony dla całego obszaru roboczego, dla jednego rejestru, czy dostarczony ze środowiska. Obie sytuacje mają jedną przyczynę: ścieżka klucza nie jest poświadczeniem, lecz nazwą sekretu, który przechowuje ten serwer. Wywołujący, który ją podaje, niczego nie dowodzi — każdy, kto dotarł do tego adresu, mógłby podać tę samą nazwę, a powstały podpis świadczyłby, że za artefakt ręczy operator, a nie wywołujący. Zamknięcie argumentu przy pozostawieniu otwartej konfiguracji byłoby zamknięciem jednych drzwi do pokoju, który otwierają drugie. Dlatego podpisywanie kluczem jest przez listener nieosiągalne: podpisuje wyłącznie token przesłany w wywołaniu.

fulcio_url, rekor_url i timestamp_url pozostają bez zmian i działają w obu transportach. Wskazują usługi, z którymi należy się skontaktować, a nie coś, co przechowuje ta maszyna, więc wywołujący, który nie może wybrać klucza, nadal podpisuje względem punktów końcowych skonfigurowanych w tym wdrożeniu.

Listener uruchomiony nad obszarem roboczym, który wskazuje klucz podpisujący, informuje o tym raz, przy starcie. Proces zapisuje w swoim strumieniu błędów jeden wiersz, który wymienia to ustawienie i stwierdza, że wywołujący docierający do tego listenera nie może użyć tego klucza — dzięki temu operator dowiaduje się o tym z procesu, który uruchomił, a nie z podpisu, którego się nie spodziewał. Obszar roboczy niewskazujący żadnego klucza nie generuje takiego wiersza, ponieważ nie ma o czym informować. Wiersz zawiera nazwę ustawienia, ale ani klucza, ani żadnych informacji o pliku, na który wskazuje.

W przypadku standardowego wejścia i wyjścia nic z powyższego nie ma zastosowania. Tam środowisko jest odczytywane, a key_path wybiera klucz przechowywany na tej maszynie, ponieważ klient, który uruchomił ten serwer, działa na własnej maszynie wywołującego, a to, do czego ten proces ma dostęp, należy do wywołującego i może on z tego korzystać.

Odczyt encji przez jej referencję rejestru kontaktuje się z jednym rejestrem, przy użyciu logowania tego hosta, a przez listener — wyłącznie z rejestrem, z którym skonfigurowano obsługiwany obszar roboczy. describe, któremu jako name przesłano referencję oci://, odczytuje encję opublikowaną pod tą współrzędną — ten sam odczyt, który wykonuje aggrega inspect — z jednego rejestru wskazanego w referencji, przy użyciu logowania, które ten host już ma dla tego rejestru. Wywołanie nie zawiera poświadczenia, a describe żadnego nie przyjmuje. Przez HTTP rejestr musi być jednym z tych, z którymi skonfigurowano obsługiwany obszar roboczy: hostem wskazanym w jego default_registry lub hostem wymienionym w registries, porównywanym dokładnie i wraz z portem. Referencja do każdego innego hosta — łącznie z adresem na tej maszynie — jest odrzucana, zanim nastąpi kontakt z tym hostem, a odmowa wymienia host, więc wywołujący nie może skierować tego serwera do wybranego przez siebie miejsca docelowego. To, co pozostaje osiągalne, jest zamierzone: wywołujący z aggrega:read może odczytać wszystko, co logowanie tego hosta może odczytać w rejestrze skonfigurowanym dla obszaru roboczego, czyli to samo, co może odczytać osoba przy terminalu tego hosta. Przez standardowe wejście i wyjście odczytywana jest referencja do dowolnego rejestru, tak jak w wierszu poleceń. Opisywanie encji przez jej nazwę w katalogu pozostaje bez zmian.

Wywołanie rejestru korzysta z magazynu poświadczeń użytkownika systemu operacyjnego, jako który działa ten proces, dokładnie tak jak to samo wywołanie w terminalu na tym hoście. Nie ma źródła poświadczeń dla poszczególnych obszarów roboczych ani ustawienia, które by je dodawało, dlatego registry-list zgłasza stan poświadczeń hosta tak samo w każdym obszarze roboczym na tej maszynie. Wdrożenie, w którym różne obszary robocze mają mieć różne poświadczenia rejestru, uruchamia je jako różnych użytkowników systemu operacyjnego — jeden proces na obszar roboczy, każdy uruchomiony jako osobny użytkownik. Stąd bierze się separacja, a jej zorganizowanie należy do operatora.

Co rejestruje serwer

Każde żądanie, na które odpowiada ten punkt końcowy, pozostawia jeden wiersz w strumieniu błędów procesu, a ten wiersz jest pojedynczym obiektem JSON. Zawiera time jego zapisu oraz request_id, który ten proces wygenerował dla wywołania i którego nie odsyła wywołującemu; subject i issuer w postaci, w jakiej stwierdziło je przedstawione poświadczenie, wraz z client_id, jeśli je wskazało; workspace_root, czyli obszar roboczy obsługiwany przez ten proces; method oraz target, jeśli metoda odnosi się do czegoś po nazwie; reach, czyli rodzaj deklarowany przez operację, oraz reach_escalated_to, jeśli wywołanie sięgnęło dalej; outcome; duration_ms; oraz transport. Pole, które nie ma nic do przekazania, jest pomijane, a nie zapisywane jako puste, więc brak client_id oznacza poświadczenie, które nie wskazało klienta, a brak reach_escalated_to oznacza wywołanie, które sięgnęło dokładnie tego, co deklaruje jego operacja.

outcome mówi, co stało się z wywołaniem, a wartości są rozłączne, aby można je było liczyć osobno. ok – wywołanie wykonano i zakończyło się powodzeniem. tool-failure – wywołanie wykonano i wróciło oznaczone jako błąd, który wywołujący może poprawić; jest to wywołanie obsłużone przez serwer, a nie odrzucone, więc nie należy go zaliczać do odmów. error to odmowa przekazana jako koperta błędu protokołu. unauthenticated, forbidden i rate-capped oznaczają odrzucenie żądania odpowiednio przez poświadczenie, ograniczenie pochodzenia lub zakresu oraz limit częstotliwości na wywołującego. cancelled oznacza wywołującego, który zamknął połączenie przed otrzymaniem odpowiedzi.

Powód odrzucenia poświadczenia jest polem tego samego wiersza, a nie osobnym wierszem. Odrzucone żądanie pozostawia jeden rekord, jak każde inne, z polem refusal wskazującym kontrolę, która je odrzuciła. Żadne poświadczenie ani żadna jego część nie trafia do żadnego wiersza – ani przy odmowie, ani przy obsłużonym wywołaniu.

Wywołujący, który nie przedstawił niczego, nie pozostawia wiersza. Otrzymanie wezwania do uwierzytelnienia to sposób, w jaki klient dowiaduje się, gdzie uzyskać token, więc jest to pierwsza rzecz, jaką robi każdy poprawnie działający klient, a wiersz dla każdego takiego przypadku zagrzebałby odmowy, które coś znaczą. Żądanie wskazujące ścieżkę lub metodę, której ten punkt końcowy nie obsługuje, również nie pozostawia wiersza: oba przypadki są rozstrzygane, zanim cokolwiek o wywołującym zostanie odczytane, więc skanowanie adresu niczego nie zapisuje w tym, co zbiera strumień.

Kontekst śledzenia wysłany przez klienta jest kopiowany do wiersza dosłownie. traceparent oraz obok niego tracestate i baggage, jeśli także zostały wysłane, są przenoszone dokładnie w postaci, w jakiej je odebrano, aby to, co zbiera ten strumień, mogło powiązać go z własnymi rekordami wywołującego. Żądanie, które ich nie wysyła lub wysyła kontekst niebędący poprawnym kontekstem śledzenia W3C, daje wiersz bez tych kluczy: nic nie jest wymyślane i nic nie jest zmieniane po drodze.

Proces rejestruje własny cykl życia w tym samym kształcie i w tym samym strumieniu, a każdy z tych wierszy wskazuje event tam, gdzie wiersz żądania wskazuje metodę i wywołującego: startup przy starcie, listening z adresem, na którym nasłuchuje, startup-refused z powodem odmowy uruchomienia przed rozpoczęciem obsługi, signing-key-ignored, gdy obsługiwany obszar roboczy wskazuje klucz podpisujący, którego żaden wywołujący docierający do tego nasłuchu nie może użyć, docs-bundle z wynikiem pozyskania pakietu dokumentacji oraz shutdown przy zakończeniu działania. Obecność event pozwala odróżnić oba rodzaje wierszy.

Wszystko to zbiera się ze strumienia błędów procesu i na tym polega całe dostarczanie. Nie ma eksportera do skonfigurowania, pliku do wskazania ani ustawienia, które cokolwiek z tego włącza, wyłącza lub przekierowuje: to, co nadzoruje ten proces – środowisko uruchomieniowe kontenerów, menedżer usług, narzędzie do przesyłania logów – zbiera ten strumień i tam można go później przeszukiwać. Przy standardowym wejściu i wyjściu ten sam strumień przenosi zamiast tego czytelny tekst, ponieważ odczytujący go klient uruchomił proces i działa na tej samej maszynie.

Nic z tego nie jest wysyłane wywołującemu. Serwer nie publikuje strumienia logów przez protokół w żadnym transporcie, a żądanie zawierające pole protokołu określające poziom logowania dla żądania otrzymuje dokładnie taką odpowiedź jak żądanie bez niego: to, co jest tu rejestrowane, należy do operatora i trafia wyłącznie do strumienia operatora.

Co serwer przekazuje modelowi przy połączeniu

Serwer udostępnia blok wskazówek dla modelu, który klient może mu przekazać przed pierwszym wywołaniem. Klient w wersji 2026-07-28 odczytuje go z odpowiedzi server/discover; klient w wersji 2025-06-18 odczytuje go z odpowiedzi na swoje uzgadnianie initialize. Na obu ścieżkach jest to ten sam tekst, bajt w bajt, i ten sam tekst dla każdego klienta łączącego się z jednym procesem: nic w nim nie jest negocjowane i nic nie wynika z tego, co klient przesłał, ani z poświadczenia, które przedstawił, więc to, co model słyszy przy połączeniu, nie różni się między sesjami ani między klientami.

Zmieniają się dwie rzeczy i żadna z nich nie zależy od klienta. Akapit zamykający jest układany dla transportu, który obsługuje proces, więc serwer komunikujący się przez standardowe wejście i wyjście oraz nasłuchujący serwer przekazują modelowi różny tekst zamykający. Ponadto gdy pakiet desktopowy, który uruchomił serwer, pochodzi z innego wydania niż uruchomiony przez niego plik wykonywalny aggrega, wskazówki zaczynają się od jednego zdania, które to stwierdza i podaje obie wersje — tego samego zdania, od którego zaczyna się odpowiedź describe-capabilities bez argumentów, jak opisano w sekcji Z którego wydania pochodzi serwer; uruchomienie, którego nie wykonał żaden pakiet, oraz uruchomienie z pakietu pochodzącego z wydania samego pliku wykonywalnego przekazują wskazówki bez niego. Obie rzeczy są ustalane przy starcie procesu, a w obrębie każdego procesu obie rewizje nadal serwują jego własny tekst identycznie.

Wskazówki uczą modelu myślowego, którego schemat argumentów narzędzia sam nie przekaże:

  • Co kompilator robi, a czego celowo nie robi — że przekazuje tekst i ocenia dopasowania etykiet zamiast interpretować znaczenie wartości, że jest bez własnego zdania co do treści umieszczanej w dokumentach oraz że podczas kompilacji nigdy nie uwierzytelnia się u dostawcy, nigdy nie odczytuje stanu klastra i nigdy nie zamienia sekretu na tekst jawny. Wartość, która istnieje dopiero wtedy, gdy infrastruktura działa, przechodzi dalej jako ciąg wskaźnikowy, który środowisko docelowe wypełnia później.
  • Słownictwo tworzenia i powiązania między rodzajami — do czego służy każdy rodzaj i względem którego faktycznie uruchamiana jest kompilacja, tak aby asystent nie musiał wnioskować kształtu wdrożenia z listy narzędzi.
  • Kolejność pętli tworzenia — odczytać kontrakt, wygenerować na jego podstawie szkielet, przejrzeć to, z czym się łączy, a następnie sprawdzić przed renderowaniem.
  • Kiedy sięgnąć po prompt zamiast narzędzia — narzędzie służy do działania, prompt do ujęcia zadania.
  • Że lista narzędzi to cała powierzchnia — znajduje się w niej każde narzędzie oferowane przez serwer, a to, jakie narzędzia serwer oferuje, zależy od jego konfiguracji, więc asystent odczytuje dostępne możliwości z tej listy i z describe-capabilities, zamiast szukać drugiej. Gdy połączenie przedstawiło poświadczenie, wskazówki stwierdzają, że poświadczenie decyduje o tym, które z tych narzędzi może uruchomić wywołanie, a nigdy o tym, które są wymienione: wywołanie, którego nie dopuszcza, zostaje odrzucone ze wskazaniem zakresu, który by je dopuścił, a klient może zalogować się ponownie z tym zakresem.
  • Co oznacza pusta przestrzeń robocza i co model może z tym zrobić — akapit różniący się w zależności od transportu, opisany poniżej.

Wskazówki wymieniają powierzchnie zamiast je powtarzać. Każde narzędzie ma już własny opis i schemat argumentów w tools/list, a kontrakt każdego rodzaju znajduje się już w jego schemacie i na jego stronie referencyjnej, więc wskazówki odsyłają do nich i na tym poprzestają — jedno miejsce na każde stwierdzenie. Narzędzie, które wymieniają, jest narzędziem serwowanym przez serwer, a wskazują każdą rodzinę zasobów rozwiązywaną przez powierzchnię odczytu, więc nic, po co odsyłają asystenta, nie jest ślepym zaułkiem.

Wskazówki nie zawierają indeksu samych narzędzi i jest to ta sama zasada, a nie odstępstwo od niej. Klient ma definicję każdego narzędzia z tools/list, zanim przeczyta choć słowo tego tekstu, więc wiersz na każde narzędzie byłby tu drugą kopią celów, które już zna — opłacaną w każdej sesji, przez każdego klienta, i mogącą rozejść się z listą narzędzi w chwili, gdy którąkolwiek z nich zmieniono.

Wskazówki stwierdzają też, czego nie wyliczają, i dlaczego: dostępne cele renderowania i zainstalowane rodzaje bibliotek są właściwościami wtyczek i zestawu schematów, więc powierzchnie zasobów zgłaszają je bezpośrednio, zamiast żeby wskazówki niosły kopię, która mogłaby się z nimi nie zgadzać.

Co model słyszy o pustej przestrzeni roboczej

Akapit zamykający odpowiada na pytanie, które model napotyka najpierw w przestrzeni roboczej niczego niezawierającej: co oznacza pusty wynik list-entities i co może z tym zrobić. Jego początek jest taki sam na obu transportach — pusta lista oznacza, że przestrzeń robocza rozwiązana przez ten proces nie zawiera żadnych dokumentów Aggrega, które może odczytać, a skonfigurowane obok niej katalogi również żadnych nie deklarują — a to, co następuje dalej, zależy od transportu obsługiwanego przez proces, ponieważ uczciwa odpowiedź nie jest na obu taka sama.

Przez standardowe wejście i wyjście model słyszy, że może przeglądać i naprawiać przestrzeń roboczą. Dowiaduje się, gdzie obsługiwane jest wywołanie niewskazujące przestrzeni roboczej — w folderze, z którym uruchomiono serwer, jeśli go podano, a w przeciwnym razie w przestrzeni roboczej odnalezionej od folderu, w którym go uruchomiono, co może być tym samym folderem — oraz że workspace_root w wywołaniu wskazuje inną. Jest odsyłany do config-show, aby poznać obowiązującą konfigurację i warstwę, która zdecydowała o każdym ustawieniu, oraz do cli-config-init, aby utworzyć działającą; oba są na liście narzędzi na tym transporcie. Klient uruchamiający serwer działa na własnej maszynie wywołującego, więc to, do czego ten proces ma dostęp, należy do tego wywołującego — a granicę wyznacza się tam, gdzie dla każdego innego narzędzia, w kliencie MCP, jak opisano w sekcji Co asystent może zrobić bez pytania.

Przez HTTP model słyszy, że ma zgłaszać, a nie konfigurować. Przestrzeń robocza to ta, nad którą uruchomiono proces, i pozostaje stała przez cały jego czas życia; wywołanie wskazujące workspace_root lub catalog_dirs zostaje odrzucone ze wskazaniem argumentu; i żadne narzędzie zapisujące konfigurację nie jest tu oferowane żadnemu wywołującemu, niezależnie od zakresów jego poświadczenia. Te operacje realizują wyłącznie narzędzia uruchamiające polecenie aggrega w osobnym procesie, a sesja osiągnięta przez HTTP jest składana bez nich — granicą jest więc skład, a nie zakres, i żaden token jej nie poszerza. Model łączący się z wdrożeniem przez nasłuchujący serwer nie może zatem utworzyć rejestru ani przepisać polityki zaufania na hoście, a akapit mówi mu to wprost, zamiast pozwolić mu spróbować i odczytać odmowę.

Co asystent może zrobić bez pytania o zgodę

Asystent połączony z tym serwerem przez standardowe wejście i wyjście może wywołać każde narzędzie udostępniane przez serwer bez pytania o zgodę, chyba że klient jest skonfigurowany tak, by mu tego odmawiać. Na tym transporcie serwer oferuje narzędzia i nie decyduje, których z nich może użyć dane wywołanie: ta decyzja należy do klienta i to w nim należy ją podjąć. Przez HTTP jest inaczej: serwer wymienia każde narzędzie, które posiada i ogłasza, a odrzuca wywołanie, którego nie dopuszczają zakresy tokenu wywołującego, więc granicę wyznacza zarówno serwer, jak i klient.

Ma to znaczenie, ponieważ powierzchnią narzędzi jest wiersz poleceń. Wszystko, co można wpisać, asystent może wywołać — łącznie z operacjami, które zmieniają maszynę.

Niektóre z tych operacji sięgają dalej niż bieżąca przestrzeń robocza i nie da się ich cofnąć, uruchamiając coś innego. Warto znać je z nazwy; poniżej uporządkowano je od najszerszego zasięgu:

  • publish-entity, publish-artifact, sign-artifacts i deprecate-artifact sięgają całkowicie poza maszynę. Umieszczają w rejestrze bajty, podpis lub znacznik wycofania, więc zmieniają to, co rozwiązuje każdy konsument tego rejestru — nie tylko ta maszyna. Ponowna publikacja innej treści pod tym samym tagiem jest odrzucana, a nie oferowana, więc żadna z tych operacji nie cofa publikacji; rozwiązaniem jest opublikowanie nowej wersji. Podpis i znacznik wycofania nie zmieniają bajtów artefaktu, ale każdy, kto później pobierze ten artefakt, pobierze także je, i żadnego z nich nie można odwołać u kogoś, kto już go ma. Przez standardowe wejście i wyjście te same cztery możliwości są dostępne także jako cli-push, cli-push-artifact, cli-sign i cli-deprecate, które uruchamiają polecenia; przez HTTP tych czterech narzędzi nie ma.
  • Podpisywanie korzysta z poświadczeń. Przez standardowe wejście i wyjście podpisywanie bezkluczowe pobiera token tożsamości z argumentu identity_token wywołania, ze zmiennej AGGREGA_IDENTITY_TOKEN lub SIGSTORE_ID_TOKEN w środowisku serwera albo z dostępnego w otoczeniu punktu końcowego OIDC GitHub Actions, jeśli jest osiągalny; key_path wybiera zamiast tego klucz przechowywany offline. Asystent, który może wywoływać te narzędzia, może więc podpisywać w imieniu użytkownika, dowolną tożsamością, którą już posiada maszyna uruchamiająca serwer — a podpis jest oświadczeniem o tym, kto ręczy za artefakt, dlatego nad tą operacją należy zastanowić się najdłużej przed jej dopuszczeniem. Przez listener podpisuje wyłącznie token przesłany w wywołaniu: nic ze środowiska serwera nie jest odczytywane, a żadnego klucza przechowywanego na hoście nie można wybrać argumentem ani konfiguracją obsługiwanej przestrzeni roboczej, jak opisano w sekcji Które poświadczenia zużywa wywołanie.
  • aggrega cache evict przycina magazyn skompilowanych modułów, a aggrega cache clear go czyści. Ten magazyn jest współdzielony przez każdy projekt Aggrega na maszynie. Usunięte z niego moduły są ponownie kompilowane na żądanie, więc nic nie ginie trwale — ale następna kompilacja dowolnego projektu ponosi ten koszt. aggrega cache clear usuwa także pakiet dokumentacji odczytywany przez każdy projekt na maszynie, który jest pobierany ponownie, gdy któryś z nich następnym razem go pozyska.
  • aggrega cache prune odzyskuje wpisy pamięci podręcznej artefaktów, do których nie odwołuje się żaden plik blokady. Jeśli pliku blokady projektu nie ma do odczytania, nie chroni on przypiętych artefaktów tego projektu, a ich odzyskanie oznacza ponowne pobranie.
  • aggrega registry add i aggrega registry remove domyślnie zapisują do konfiguracji współdzielonej przez wszystkie przestrzenie robocze, więc zmieniają to, co jest rozwiązywane w całej maszynie, a nie tylko tutaj. aggrega registry add prosi też wskazany rejestr o ogłaszaną przez niego politykę zaufania i przypina to, co otrzyma, dokładnie tak jak w terminalu. W przestrzeni roboczej offline to pobranie jest odrzucane, zanim cokolwiek zostanie wybrane, więc dodanie rejestru innego niż oficjalny hub jest odrzucane — kod skrócony E0310, tymi samymi słowami — chyba że wywołanie poda identity lub key; aggrega config init, które nie przyjmuje żadnego z nich, może offline zainicjować tylko hub. Przez standardowe wejście i wyjście są one dostępne jako cli-registry-add i cli-registry-remove, a inicjowanie jako cli-config-init, które uruchamiają polecenia; przez HTTP tych narzędzi nie ma.
  • pull czyta z rejestru i zapisuje wewnątrz wskazanej przestrzeni roboczej. Zapisuje plik blokady danej encji Release, wypełnia pamięć podręczną artefaktów tym, co rozwiązał, i obok pliku blokady zapisuje tożsamość każdego zwracającego werdykt pluginu dołączanego przez przestrzeń roboczą. Po otrzymaniu pin_sources — lub w przestrzeni roboczej z włączonym pin_sources_at_pull, gdy wywołanie nie przesyła go jako false — wykonuje także krok przypinania autora encji dla encji Recipes i FeatureRecipes, z których encja Release buduje z katalogów, zapisując obok każdej entity.lock; bez tego pull dla takiej encji, której blokada nie zawiera przypięcia dla odczytywanego wejścia, jest odrzucany z podaniem tego kroku. Same pliki encji nigdy nie są zapisywane. Nic z tego nie opuszcza maszyny, a ponowne rozwiązanie zmienia to, co zostało zapisane, więc jest to najłagodniejsza z zapisujących operacji opisanych tutaj. Jest to jedno z narzędzi przeznaczonych dla pętli tworzenia, które zapisują wewnątrz przestrzeni roboczej: pin zapisuje entity.lock obok wskazanej encji Recipe lub FeatureRecipe, jak opisano w sekcji Przypinanie własnych wejść encji; gen-catalog zapisuje wygenerowane encje Plugin we wskazanym katalogu; edit-document stosuje jedną ograniczoną, strukturalną edycję do istniejącego dokumentu i zapisuje go z powrotem, zachowując każdy bajt, którego edycja nie dotyka, jak opisano w sekcji Stosowanie jednej ograniczonej edycji do dokumentu; import przekształca opis wygenerowany przez inne narzędzie w robocze pliki źródłowe i zapisuje je w przestrzeni roboczej, jak opisano w sekcji Przekształcanie obcego opisu w robocze encje; a scaffold po otrzymaniu example zapisuje jeden z uruchamialnych przykładów z dokumentacji do nowego lub pustego katalogu dir, tak jak robi to aggrega scaffold --example, na co przez HTTP pozwala zakres workspace-write. Ten katalog wyjściowy, gość odczytywany przez gen-catalog i każda podana mu nakładka są ścieżkami względnymi wobec katalogu głównego przestrzeni roboczej lub, przez standardowe wejście i wyjście, bezwzględnymi — według tego samego kontraktu co każdy inny argument ścieżki na tej powierzchni. Przez standardowe wejście i wyjście ta sama możliwość jest dostępna także jako cli-pull, które uruchamia polecenie; przez HTTP tego narzędzia nie ma.
  • build czyta z tego samego rejestru i wykonuje ten sam zapis, gdy otrzyma auto_pull, i tylko wtedy. Rozwiązywanie zależności encji Release jest jedną operacją, niezależnie od tego, gdzie jest wywoływane, więc kompilacja z poleceniem wcześniejszego rozwiązania robi dokładnie to, co pull, a następnie renderuje względem tego, co zapisała — dlatego ma ten sam zasięg, a nie mniejszy. Po otrzymaniu write zapisuje także wyrenderowane artefakty do dist/ w katalogu głównym przestrzeni roboczej, tam gdzie zapisuje je aggrega build i tym samym zapisem, więc w tym wywołaniu sięga do przestrzeni roboczej; nie zapisuje nigdzie indziej, a dist będący dowiązaniem prowadzącym poza przestrzeń roboczą jest odrzucany, zanim cokolwiek w nim zostanie usunięte lub zapisane. Bez żadnego z tych argumentów, co jest domyślne, build renderuje z przypięć, które przestrzeń robocza już ma, i nie sięga nigdzie. W sekcji Kompilowanie względem treści już przypiętej przez encję Release opisano, co ten argument zmienia, a czego nie.

Narzędzia inwentaryzacyjne mówią o tym we własnych odpowiedziach. cache-status oznacza każdą klasę pamięci podręcznej jej zasięgiem — workspace dla pamięci podręcznej artefaktów w katalogu pamięci podręcznej tego projektu, machine dla magazynów współdzielonych przez wszystkie projekty — i wprost wymienia te obejmujące całą maszynę, dzięki czemu asystent czytający inwentarz przed zaproponowaniem odzyskania miejsca dowiaduje się, które jego części nie należą wyłącznie do użytkownika. Operacje konserwacyjne zgłaszają ten sam zasięg dla każdego usuniętego elementu. Każdy z czterech wyników publikacji zawiera własne pole reach, w którym znajdują się registries — każdy host rejestru, do którego odwołało się wywołanie, wymieniony raz, w kolejności pierwszego odwołania — oraz beyond_this_machine, odczytywane z tego, co wywołanie faktycznie dołączyło, a nie z tego, o co prosiło: true, gdy przesłało treść lub dołączyło podpis, datę publikacji albo znacznik wycofania, oraz false dla przebiegu próbnego i dla wywołania, które zastało to wszystko już na miejscu, na przykład ponownej publikacji kompletnej wersji lub partii podpisywania, w której wszystkie referencje były już podpisane.

Gdzie ustawia się granicę. Sam protokół nie definiuje uprawnień dla poszczególnych narzędzi — jego uwierzytelnianie dotyczy tego, czy klient w ogóle może się połączyć, a nie tego, które narzędzia może następnie wywołać. Decyzja o uprawnieniach należy do klienta MCP. Popularne klienty zazwyczaj pozwalają zezwalać na poszczególne narzędzia jednego serwera lub ich zabraniać według nazwy oraz całkowicie wyłączyć serwer dla danego projektu; nazwa i położenie tego ustawienia różnią się między klientami, dlatego należy sprawdzić w dokumentacji własnego klienta, jak konfiguruje się uprawnienia narzędzi. Aby dopuścić odczyty, a nie zapisy, należy tam zezwolić na wybrane narzędzia i zabronić pozostałych. Liberalna konfiguracja lub klient bez takiego ustawienia pozostawia możliwość wywołania każdego udostępnionego narzędzia.

Sprawdzanie, co zawiera przestrzeń robocza

Większość narzędzi przyjmuje podmiot: nazwę encji lub ścieżkę encji Release. Dwa opisane poniżej nie przyjmują żadnego i to dzięki nim asystent, który dopiero się połączył, może go uzyskać.

list-entities odpowiada na pytanie, co zawiera przestrzeń robocza, a list-releases na węższe pytanie, które reszta interfejsu zadaje nieustannie: jakie są encje Releases. Żadne z nich nie przyjmuje podmiotu, ponieważ zawartość przestrzeni roboczej jest właściwością samej przestrzeni, a nie czegoś, co wywołujący musi wiedzieć wcześniej.

Każde z nich odpowiada w jednym z dwóch kształtów, a wywołanie, które nie wskazuje kształtu, otrzymuje podsumowanie. Ta wartość domyślna dotyczy wyłącznie tych dwóch narzędzi i jest przeciwieństwem tej, którą przyjmują build, describe i validate. Te pytane są o podmiot, który wywołujący już wskazał, więc pełniejsza odpowiedź jest tą, o którą poproszono, a zwięzła jest opcjonalna. Tych dwóch pyta się, co tu jest, i to wywołujący, który nie ma jeszcze czego wskazać ani możliwości, by przed nadejściem odpowiedzi ocenić jej koszt — dlatego najpierw podają rozmiar i kształt przestrzeni roboczej, a rekordy przekazują dopiero na żądanie.

Podsumowanie mówi, co tu jest i ile tego jest. list-entities podaje katalog główny przestrzeni roboczej — wstrzymywany przez HTTP, jak opisuje Co odpowiedź mówi o systemie plików serwera — łączną liczbę encji oraz liczbę dla każdego rodzaju; list-releases podaje sumę oraz liczbę dla każdego katalogu najwyższego poziomu, dzięki czemu wiadomo, ile jest encji Releases i w której części drzewa się znajdują. Oba zestawienia są odczytywane z samych dokumentów, więc przestrzeń robocza zorganizowana w sposób, którego nikt nie przewidział, jest podsumowana równie dokładnie jak każda inna. Oba zawierają jeden wiersz na rodzaj lub na katalog najwyższego poziomu, więc ich rozmiar zależy od liczby rodzajów deklarowanych w przestrzeni roboczej i liczby katalogów, w których znajdują się jej encje Releases, a nie od liczby dokumentów: po stokrotnym zwiększeniu liczby dokumentów bez zmiany rodzajów podsumowanie wydłuża się tylko o kilka bajtów potrzebnych na zapis większych liczb. Wydłuża je dopiero deklarowanie większej liczby rodzajów. Żadne z nich nie jest pierwszą stroną rekordów i właśnie o tę różnicę chodzi: „oto niektóre encje” to inna odpowiedź niż „z tego składa się przestrzeń robocza” i tylko druga pozwala ocenić, czy w ogóle potrzebne są jakieś rekordy, a jeśli tak, to które.

Aby otrzymać rekordy, należy wysłać response_format: detailed; przychodzą one stronami. list-entities podaje wtedy dla każdej encji rodzaj, nazwę, apiVersion, opis, etykiety i plik źródłowy, odczytane bezpośrednio z dokumentu, który ją deklaruje. Podaje też encje Features deklarowane przez skonfigurowane katalogi katalogowe, aby każdą encję Feature oferowaną jako możliwą do dołączenia można było również wyszukać; nie mają one pliku źródłowego, ponieważ jedyna ich ścieżka istnieje na maszynie, na której działa serwer, a każda z nich podaje swoje pochodzenie, aby pusty plik był odczytywany jako „rozwiązany z katalogu”, a nie jako brakująca wartość. list-releases podaje ścieżkę każdej encji Release, a lockfiles przypisuje każdej zwróconej ścieżce ścieżkę pliku blokady tej encji Release w tym samym układzie współrzędnych: plik, który zapisuje dla niej pull i który odczytuje build, ten sam, który wskazują odpowiedzi serwera językowego dotyczące encji Release. Mapa opisuje ścieżki zawarte w tej odpowiedzi, więc podąża za stroną, a w podsumowaniu jest pusta.

detailed i concise to jedyne wartości, jakie przyjmuje response_format, i są dopasowywane dokładnie. Każda inna pisownia — inne słowo, inna wielkość liter lub białe znaki wokół jednej z nich — jest odrzucana, a odmowa podaje wysłaną wartość obok wartości akceptowanych przez argument. Pominięcie response_format oznacza żądanie wartości domyślnej, którą dla tych dwóch narzędzi jest podsumowanie. To samo obowiązuje wszędzie, gdzie pojawia się ten argument: build, describe i validate przyjmują te same dwie wartości na tych samych zasadach, a ich wartością domyślną jest pełniejszy kształt, a nie zwięzły.

Liczba rekordów jest ograniczona niezależnie od tego, czy się ją ograniczy. limit określa, ile rekordów zawiera jedna odpowiedź, od 1 do 500, a domyślnie wynosi 50 — więc wywołanie, które żąda rekordów bez podania rozmiaru strony, nadal jest ograniczone i żadne wywołanie któregokolwiek z narzędzi nie zwraca odpowiedzi, której rozmiar wyznacza wielkość przestrzeni roboczej. offset określa, od którego miejsca listy zacząć, licząc od 0. Oba ograniczają rekordy, więc żaden nie wpływa na podsumowanie, które rekordów nie zawiera. limit spoza tego zakresu jest odrzucany, a odmowa podaje granicę; offset poza końcem listy zwraca pustą odpowiedź, ponieważ po prostu nic tam nie ma, a nie dlatego, że pytanie jest błędne.

Aby kontynuować listę, należy odczytać z odpowiedzi trzy pola. count to liczba rekordów w przestrzeni roboczej, offset i returned mówią, gdzie zaczyna się ta odpowiedź i ile rekordów zawiera, a more_remaining mówi, czy jakieś pozostały. Dopóki more_remaining ma wartość true, należy wywołać narzędzie ponownie z offset powiększonym o returned. Ten sygnał jest obliczany ze strony względem sumy, a nie zapisywany w odpowiedzi, więc nie może zgłosić, że nic nie zostało, gdy rekordy pozostają.

Wszystko to ma znaczenie, ponieważ narzędzia, które przyjmują nazwę, odrzucają nazwę, której nie potrafią rozwiązać, zamiast odpowiadać pustym wynikiem. Odmowa jest celowa — pusta odpowiedź przedstawiałaby błędnie wpisaną nazwę jako podmiot, który nie ma nic do zaoferowania — ale oznacza, że wywołujący bez nazwy nie uzyska jej przez zgadywanie. Sposobem na jej uzyskanie jest wyliczenie.

Oba narzędzia dają się łączyć ze sobą i z resztą interfejsu:

  • Należy wywołać list-entities po podsumowanie, aby zobaczyć, jakie rodzaje zawiera przestrzeń robocza i ile jest każdego z nich, następnie wywołać je ponownie z response_format: detailed po rekordy, wybrać nazwę z wyniku i przekazać ją do describe, aby zobaczyć w pełni rozwiązaną definicję tej encji. Jest to definicja, którą zwraca aggrega/entityDefinition serwera językowego, przekazana jako JSON: każdy klucz pod nazwą, którą pisze jego autor, w kolejności, w jakiej zawiera go definicja, schemat jako schemat napisany przez autora, a schemat, którego encja nie deklaruje, pominięty — gniazda encji Component, każde ze slotami, które mogą wypełniać ich połączenia.
  • To samo można zrobić z list-releases: wybrać ścieżkę ze szczegółowego wyniku i przekazać ją do describe lub build jako encję Release, na której należy pracować.
  • Ścieżka zwracana przez list-releases jest względna wobec katalogu głównego przestrzeni roboczej, czyli tego samego układu współrzędnych, w którym list-entities podaje plik, więc obie odpowiedzi zgadzają się co do pliku i można je czytać razem. Jej plik blokady, pod lockfiles, jest względny wobec tego samego katalogu głównego, więc można ten plik odczytać lub porównać bez ustalania, gdzie się znajduje.

Oba narzędzia rozstrzygają, co się liczy, na podstawie własnego pola kind każdego dokumentu, nigdy na podstawie nazwy pliku. Encja Release nazwana bez konwencjonalnego prefiksu jest wymieniana; plik jedynie nazwany jak taka encja nie jest i pojawia się pod tym rodzajem, który faktycznie deklaruje. YAML, który w ogóle nie deklaruje kind — plik wartości chartu, plik konfiguracyjny, który akurat leży w drzewie — nie jest encją i nie jest zgłaszany; nie jest nim też dokument należący do innego projektu, taki jak wyrenderowany manifest Kubernetes. Dokument liczy się jako encja, gdy deklaruje zarówno kind, jak i nazwę, ponieważ te dwa elementy razem czynią go później adresowalnym, i nie deklaruje apiVersion spoza własnej grupy Aggrega. Dokument, który w ogóle nie deklaruje apiVersion, jest zgłaszany, ponieważ jest dokumentem Aggrega z brakującym polem, a nie plikiem innego projektu. list-releases nie przeszukuje żadnego katalogu poza katalogiem głównym przestrzeni roboczej, więc encja Release, którą edytor pokazuje pod dowiązaniem prowadzącym do takiego katalogu, nie jest wymieniana; unread_linked_dirs wskazuje każde dowiązanie, które stoi tam, gdzie lista odczytałaby katalog, i prowadzi poza katalog główny — przez własną ścieżkę dowiązania względem katalogu głównego, nigdy przez miejsce, do którego prowadzi — w obu kształtach i w obu transportach, i jest puste, gdy takich nie ma. Narzędzie nie odczytuje też pliku spoza katalogu głównego przez dowiązanie: unread_linked_files wskazuje w ten sam sposób każde dowiązanie, którego własna nazwa kończy się na .yaml lub .yml i które prowadzi do pliku poza katalogiem głównym, niezależnie od zawartości tego pliku, więc encja Release osiągalna tylko przez takie dowiązanie nie jest wymieniana — chyba że konfiguracja przestrzeni roboczej wskazuje tę encję Release, jako build.authoring_release lub jako klucz workspace.releases; wtedy jest ona odczytywana i wymieniana w miejscu samego dowiązania, a dowiązanie nie jest wskazywane. list-entities również nie odczytuje żadnego dokumentu za dowiązaniem prowadzącym poza przestrzeń roboczą — nie przeszukuje katalogów poza katalogiem głównym i nie odczytuje plików spoza niego, niezależnie od tego, co deklarują — i wskazuje każde takie dowiązanie w ten sam sposób, we własnych unread_linked_dirs i unread_linked_files, w obu kształtach i w obu transportach. Obowiązuje to niezależnie od tego, co dokument deklaruje, z jednym wyjątkiem, który robi list-releases: encja Release wskazana przez konfigurację przestrzeni roboczej, jako build.authoring_release lub jako klucz workspace.releases, jest odczytywana i wymieniana w miejscu samego dowiązania, a dowiązanie nie jest wskazywane, natomiast plik wskazany przez jedno z tych ustawień, który deklaruje cokolwiek innego niż Release, nie jest wymieniany, a jego dowiązanie jest wskazywane. Skonfigurowane katalogi katalogów są sposobem, w jaki przestrzeń robocza odczytuje inne encje przechowywane gdzie indziej, więc dowiązanie do katalogu, który konfiguracja wymienia w catalog_dirs, lub do katalogu pod nim, nie jest wskazywane przez żadną z list: konfiguracja do niego sięgnęła. Encje Features, które list-entities pobiera z katalogów katalogów, nigdy nie obejmują encji za dowiązaniem prowadzącym poza katalog, w którym muszą pozostać odczyty katalogu katalogów — przestrzeń roboczą w przypadku katalogu katalogów leżącego w niej albo sam ten katalog w przypadku katalogu wskazanego przez konfigurację poza nią — więc encja wskazana jako leżąca za nieodczytanym dowiązaniem nigdy nie jest wymieniana obok tej nazwy. Dowiązanie, które lista pomija — ze względu na nazwę, położenie lub plik .gitignore — nie jest wskazywane, a przy release nie jest też wskazywane dowiązanie pod katalogiem katalogów odczytywanym tylko przez inne encje Releases; plik .gitignore, który sam jest dowiązaniem prowadzącym poza przestrzeń roboczą, nie jest odczytywany. Gdy którakolwiek z tych list wskazuje dowiązanie, odpowiedź tekstowa kończy się osobnym wierszem, który o tym informuje.

Przestrzeń robocza, której plik konfiguracyjny prowadzi poza nią, jest nadal wymieniana, ale na nic innego dla niej nie ma odpowiedzi. Gdy własny plik .aggrega-config.yaml przestrzeni roboczej lub należąca do CI nakładka obok niego jest dowiązaniem prowadzącym poza przestrzeń roboczą, jej konfiguracja nie jest odczytywana, tak jak w terminalu, i nic, co by skonfigurowała, nie jest odczytywane w jej miejsce. Serwer nadal uruchamia się na standardowym wejściu i wyjściu i informuje o tym jednym wierszem w swoim strumieniu błędów. list-entities i list-releases odpowiadają własnymi dokumentami przestrzeni roboczej, odczytanymi bez żadnej konfiguracji, więc nie są wymieniane encje Features z żadnego katalogu katalogów. Każde z tych narzędzi wskazuje zatrzymany plik w unread_linked_files oraz w wierszu zamykającym swój tekst, niezależnie od tego, czy lista na niego natrafiła — ta nazwa pozwala stwierdzić, że konfiguracja przestrzeni roboczej prowadzi poza nią. Wywołanie listy z release lub catalog_dirs oraz każde inne narzędzie wskazujące tę przestrzeń roboczą zależy od konfiguracji, która nie została odczytana, więc każde z nich jest odrzucane z E0321, ze wskazaniem dowiązania i miejsca, do którego prowadzi. Serwer, któremu w wierszu poleceń polecono nasłuchiwać — --transport http lub --listen — nie uruchamia się dla takiej przestrzeni roboczej, ponieważ adres, pod którym miałby nasłuchiwać, jego certyfikat i to, kto może go wywoływać, rozstrzyga właśnie ta konfiguracja. Wystarczy usunąć dowiązanie lub sprawić, by prowadziło do pliku wewnątrz przestrzeni roboczej, a następne wywołanie odczyta konfigurację. Zob. granica przestrzeni roboczej.

Zapytania w kontekście jednej encji Release

Przestrzeń robocza może nadać każdej encji Release własne katalogi katalogowe — zob. Nadawanie encji Release własnych katalogów katalogowych — i w ten sposób przechowywać obok siebie wariant jednej encji dla każdej encji Release. Trzy narzędzia, które w przeciwnym razie odpowiadają na podstawie katalogów katalogowych samej przestrzeni roboczej, przyjmują opcjonalny release, czyli ścieżkę pliku Release, i wtedy odpowiadają w kontekście tej encji Release:

  • list-entities z release wyświetla encje widoczne dla tej encji Release. Wymienione Features to te, które deklarują jej katalogi katalogowe, a dokument przestrzeni roboczej znajdujący się w katalogu katalogowym czytanym wyłącznie przez inne Releases jest pomijany, więc każdy wariant jest wymieniany dla encji Release, która buduje z jego użyciem, i dla żadnej innej. Dokument spoza wszystkich katalogów katalogowych — encja Release, jej Aggregate i jej Manifest zapisane obok katalogów — jest wymieniany dla każdej encji Release.
  • describe z name i release rozwiązuje nazwę przez katalogi katalogowe tej encji Release, więc nazwa deklarowana przez kilka wariantów rozwiązuje się do tego, z którym buduje ta encja Release. Nazwa, której te katalogi nie rozwiązują, jest odrzucana z wyjaśnieniem wskazującym wpis tej encji Release w workspace.releases. Odwołanie do rejestru jest odczytywane z rejestru niezależnie od wskazanej encji Release, dlatego jest odrzucane w połączeniu z release. release wysłany bez name nadal oznacza encję Release, którą describe podsumowuje.
  • validate z entity i release wykonuje kontrole pojedynczej encji w kontekście tej encji Release: odwołania encji — Component implementowany przez Recipe, SchemaLibrary, do której odwołuje się filar — rozwiązują się przez katalogi katalogowe tej encji Release, a odpowiedź wskazuje encję Release obok encji. Żadne domknięcie nie jest walidowane; release wysłany bez entity nadal oznacza zakres encji Release. catalog_dirs jest tu, jak wszędzie, dołączany przed katalogami encji Release. Katalog wymieniony w konfiguracji przestrzeni roboczej, który nie jest katalogiem — bo na przykład nic tam nie istnieje — dla tej encji Release albo dla przestrzeni roboczej, gdy nie wysłano release, powoduje odrzucenie wywołania przed sprawdzeniem czegokolwiek, a jego tekst zawiera odmowę, jaką daje mu każde polecenie, i wskazuje wpis oraz plik konfiguracji i wiersz, który go wymienia (Skąd odczytywane są encje lokalne), tak jak odrzuca go aggrega validate.

release wskazujący nieistniejący plik albo katalog jest odrzucany we wszystkich trzech narzędziach, zamiast otrzymać odpowiedź w kontekście przestrzeni roboczej. Brak tego argumentu oznacza odpowiedź na podstawie katalogów katalogowych samej przestrzeni roboczej.

describe wyszukujący nazwę odrzuca katalog katalogowy, przez który rozwiązywałby nazwę, a którego nie można przejść, tak jak odrzuca go aggrega inspect — katalogi tej encji Release, gdy wysłano release, katalogi samej przestrzeni roboczej, gdy go nie wysłano, oraz wszystkie wskazane przez wywołanie w catalog_dirs. Katalog wskazany przez wywołanie, który nie istnieje albo istnieje, lecz nie da się go odczytać, jest odrzucany przed wyszukaniem nazwy, a tekst wskazuje katalog tak, jak zgłasza go wiersz poleceń, w jednym wierszu — katalog, catalog load i przyczynę podaną przez system plików — zamiast rozwiązywać nazwę z pozostałych katalogów. Katalog wymieniony w konfiguracji przestrzeni roboczej, który nie jest katalogiem, jest odrzucany w tym samym momencie, a tekst zawiera odmowę, jaką daje mu każde polecenie (Skąd odczytywane są encje lokalne). release wskazujący nieistniejący plik jest odrzucany wcześniej, jak opisano powyżej. Katalog katalogowy zawierający dowiązanie prowadzące poza katalog, w którym muszą pozostać jego odczyty, jest odrzucany w ten sam sposób, a tekst wskazuje dowiązanie i miejsce, do którego prowadzi, ponieważ nazwa rozwiązana bez niego mogłaby w jego miejsce rozwiązać się do innej encji o tej samej nazwie. Na opis domknięcia zależności encji Release katalog, którego nie można przejść, nie ma wpływu — odpowiedź opiera się na katalogach, które da się przejść, tak jak robi to aggrega inspect --closure — z wyjątkiem katalogu wymienionego w konfiguracji przestrzeni roboczej dla tej encji Release, który nie jest katalogiem, a który opis odrzuca, tak jak odrzuca go aggrega inspect --closure; dowiązanie prowadzące poza odczyty katalogu katalogowego albo poza dokumenty obok encji Release zatrzymuje go, tak jak zatrzymuje budowanie.

validate z entity zgłasza renderowanie, którego nie może ocenić, jako niepodjęte — w kontekście encji Release lub bez niego. Umieszcza Component encji Recipe w syntetycznym buildzie, który nie zestawia żadnego połączenia i nie dołącza żadnej encji Feature, więc Recipe, którego renderowanie zatrzymuje się, gdy jego szablony — łącznie z importowanymi przez nie plikami i wpisami bibliotek — odczytują cokolwiek z .context.inject, .context.uses lub .features, otrzymuje odpowiedź valid: true z pustym diagnostics; jego tekst zawiera Render: not attempted (this Recipe reads values a build of one cannot supply), odczyty, z powodu których je pominięto, oraz zdanie, na którym renderowanie się zatrzymało. Rozstrzyga to, co odczytuje Recipe, więc własny błąd encji Recipe obok takiego odczytu jest pomijany razem z nim, natomiast szablon, którego nie da się sparsować, i odwołanie odrzucone przez renderowanie nadal dają valid: false. aggrega validate wydaje ten sam werdykt dla tych samych danych wejściowych.

validate z entity zgłasza nieudaną asercję jako ostrzeżenie — w kontekście encji Release lub bez niego. Asercja wywołująca fail — własna asercja encji Recipe albo zadeklarowana przez Component, który ona implementuje — daje odpowiedź valid: true z pustym diagnostics. Syntetyczny build zawiera symbole zastępcze i domyślne wartości schematu zamiast wartości ustawianych przez rzeczywistą encję Release, więc asercja dotycząca takiej wartości kończy się tam niepowodzeniem niezależnie od tego, czy Recipe jest poprawny, a kontrola nie potrafi odróżnić asercji czekającej na encję Release od asercji błędnej. Niepowodzenie następuje po pozostałych notices, w postaci pełnego komunikatu asercji zakończonego zdaniem A Release must satisfy this assertion before a build of it can pass., a tekst zawiera je w wierszu rozpoczynającym się od warning:, obok wiersza raportu wskazującego, gdzie przebieg się zatrzymał. Asercja, która zatrzymuje się na kluczu, który odczytuje, ale go nie znajduje, jest błędem we własnym tekście, a nie nieudaną asercją, i jest oceniana jak każde inne zatrzymanie; build encji Release, która nie spełnia asercji, nadal jest z jej powodu odrzucany. aggrega validate wydaje ten sam werdykt dla tych samych danych wejściowych.

Odczyt obowiązującej konfiguracji i wtyczek rozwiązywanych przez ten serwer

config-show raportuje obowiązującą konfigurację oraz to, która warstwa rozstrzygnęła każde ustawienie. plugin-list raportuje wtyczki, które ten serwer potrafi rozwiązać, oraz to, co każda z nich mówi o sobie. Obie niczego nie odczytują ani nie zapisują, więc żadna z nich niczego nie osiąga i aggrega:read je dopuszcza — i żadna nie wymaga wskazania podmiotu, ponieważ to, co jest skonfigurowane, i to, co się rozwiązuje, to właściwości tego serwera, a nie czegoś, co trzeba znać wcześniej. Każda przyjmuje opcjonalny workspace_root na standardowym wejściu i wyjściu; przez HTTP ten argument jest odrzucany, jak opisano w Jeden proces, jeden obszar roboczy.

Razem odpowiadają na jedno pytanie w dwóch połowach: czy dana możliwość jest nieobecna, czy jedynie nieskonfigurowana w tym miejscu. Konfiguracja mówi, czy dostawca, importer lub kontrola zarządcza są w ogóle podłączone; odczyt wtyczek mówi, czy podłączenie osiąga gościa, który się rozwiązuje, opisuje siebie i obsługuje to, co deklaruje. Z każdego innego miejsca tej powierzchni oba przypadki wyglądają tak samo, a wymagają przeciwnych dalszych kroków.

config-show raportuje jeden wpis na ustawienie: jego field, efektywną wartość value oraz source, które je rozstrzygnęło — plik konfiguracyjny, zmienną środowiskową, flagę wiersza poleceń lub wbudowane wartości domyślne. Obok nich layers zawiera warstwy, które się przyczyniły, w kolejności pierwszeństwa, od najniższej. source ustawienia jest zapisane dokładnie tak jak odpowiadający mu wpis w layers, więc oba można bezpośrednio połączyć, a ustawienie rozstrzygnięte przez wartości domyślne nie wskazuje żadnej warstwy, ponieważ wartości domyślne nie są warstwą, która się przyczyniła. Warstwą globalną jest plik wybrany przez własny wiersz poleceń serwera — ten wskazany przez --config przy uruchomieniu, w przeciwnym razie ten wskazany przez zmienną środowiskową AGGREGA_CONFIG, a w przeciwnym razie lokalizacja domyślna — więc ustawienie rozstrzygnięte przez ten plik jest przypisywane temu plikowi, dokładnie tak jak przypisuje je aggrega config show --origin, a flaga taka jak --offline podana serwerowi jest raportowana jako ta flaga. Narzędzie nie przyjmuje response_format ani rozmiaru strony: ustawienia stanowią stały zbiór, który obsługuje ten plik binarny, a każde rozwiązanie raportuje każde z nich, więc rozmiar odpowiedzi zależy od pliku binarnego, a nie od tego, co zostało skonfigurowane.

plugin-list odpowiada w dwóch kształtach używanych przez listy obszaru roboczego, a wywołanie, które nie wskazuje kształtu, otrzymuje podsumowanie. Podsumowanie to liczba na grupę, a grupy są dwie — embedded, czyli goście wkompilowani w ten plik binarny, którzy rozwiązują się bez dostępu do systemu plików, pamięci podręcznej czy sieci, oraz configured, czyli własne powiązania obszaru roboczego. Aby otrzymać rekordy, należy wysłać response_format: detailed: dla każdej wtyczki jej grupa, odwołanie, pod którym ją znaleziono, miejsce, w którym to odwołanie powiązano, deklarowany przez nią typ, wersja, commit, obsługiwane możliwości, renderowane rodzaje wejścia, zestaw granicy i eksporty, jej gotowość, jeśli ją ma, oraz to, czy się rozwiązała. Rekordy są ograniczane przez limit i offset na tych samych zasadach co lista encji, z count, returned i more_remaining do kontynuacji. Ta odpowiedź rośnie wraz z tym, co zostało skonfigurowane — elementy wbudowane są stałe, powiązania należą do użytkownika — i dlatego jest stronicowana, a odczyt konfiguracji nie.

Wtyczka, która zawodzi, jest raportowana wraz z błędem, a nie pomijana na liście. resolved mówi, czy odwołanie w ogóle dotarło do bajtów modułu, a wtyczka, która się rozwiązała, lecz nie potrafiła się opisać, jest raportowana dokładnie jako taka — dzięki temu podłączenie obecne, ale bezużyteczne, da się odróżnić od takiego, którego nigdy nie utworzono.

Czego nasłuchujący serwer nie mówi o swoim hoście

Przez HTTP żaden z odczytów nie raportuje wartości wskazującej miejsce w systemie plików serwera. Klient, który uruchomił serwer, działa tam, gdzie serwer, więc każda lokalizacja, którą mogłaby wskazać którakolwiek odpowiedź, należy już do wywołującego i może on ją sam obejrzeć. Wywołujący, który łączy się z nasłuchującym serwerem, żadnej z nich nie wybrał, nie może nic zrobić z ich znajomością, a serwer, który je takiemu wywołującemu opublikował, nie może tej publikacji cofnąć. W tym transporcie te wartości są nieobecne; na standardowym wejściu i wyjściu wszystkie są obecne. To zasada, której przestrzega każda odpowiedź na tej powierzchni, jak opisano w Co odpowiedź mówi o systemie plików serwera, a te dwa odczyty to miejsce, w którym sięga ona najdalej, ponieważ większość tego, co raportują, to konfiguracja wskazująca miejsca.

Co jest zatrzymywane. Z config-show: value ustawienia, jeśli wartością tego ustawienia jest lokalizacja — adres serwowania lub kontroli stanu, który może być plikiem gniazda; plik certyfikatu, klucza prywatnego lub zestawu kluczy; katalog katalogu encji oraz własne katalogi encji Release w workspace.releases, których każdy wpis jest kluczowany plikiem encji Release; odwołanie do wtyczki; autorski Release. Także source ustawienia, jeśli warstwą, która je rozstrzygnęła, jest plik konfiguracyjny, ponieważ taka warstwa jest nazywana własną ścieżką tego pliku — oraz, w tej samej pisowni i z tego samego powodu, wpisy plików konfiguracyjnych w layers. Z plugin-list: uri wtyczki, jeśli to odwołanie samo jest ścieżką w systemie plików, oraz tekst błędu rozwiązania lub opisu, który powstaje z miejsc, które sprawdzono, i dlatego wskazuje lokalizacje, których samo odwołanie nie wskazuje. Z obu: workspace_root.

Co jest raportowane w całości, w obu transportach. Odwołanie do rejestru, wersja, commit, skrót, obsługiwana możliwość, etykieta gotowości, nazwa zmiennej środowiskowej lub flagi oraz warstwa, która nie jest plikiem. origin w rekordzie wtyczki jest jednym z nich: to klucz konfiguracji, pod którym zapisano powiązanie, lub przypięty skrót, który niesie zainstalowane rozszerzenie polecenia, a element wbudowany nie niesie żadnego — jest to więc ten sam ciąg, skądkolwiek wtyczka jest odczytywana. resolved to kolejny: to, czy wtyczka zawiodła, jest raportowane każdemu wywołującemu, nawet gdy jego przyczyna nie jest.

Nieobecna wartość zawsze informuje, że została zatrzymana, i to właśnie czyni odpowiedź użyteczną. Wartość zatrzymana jest raportowana jako nieobecna, z oznaczeniem obok — value_withheld i source_withheld w ustawieniu, withheld we wpisie warstwy, uri_withheld i error_withheld w rekordzie wtyczki oraz workspace_root_withheld w odpowiedzi. Ustawienie, którego nikt nie ustawił, niesie pustą wartość, w jakiej renderuje się jego kształt, i nie niesie oznaczenia. „Ten serwer nie mówi, gdzie jest klucz podpisujący” i „nie skonfigurowano klucza podpisującego” to różne odpowiedzi wymagające różnych dalszych kroków, a odczyt, który raportowałby je identycznie, nie dawałby żadnej informacji, na podstawie której można działać. Każda odpowiedź niesie też zawsze host_locations_withheld, które mówi, z którą z dwóch odpowiedzi ma się do czynienia: odpowiedź bez oznaczeń wygląda inaczej tak samo, niezależnie od tego, czy ukształtowała ją ta zasada i na hoście nie było nic do zatrzymania, czy zasada w ogóle nie miała zastosowania. Czytelny tekst obok pól mówi to samo słowami.

Zasada jest właściwością, a nie listą nazw pól: wartość jest zatrzymywana, gdy wskazuje miejsce w systemie plików hosta, niezależnie od tego, kto ją ustawił i z której warstwy pochodzi. Wartość dodana później do któregokolwiek odczytu podlega tej samej właściwości.

Na standardowym wejściu i wyjściu każda możliwość jest też osiągalna jako narzędzie nazwane od swojego polecenia — cli-config-show i cli-plugin-list — które uruchamiają to polecenie w osobnym procesie i zwracają wypisany przez nie tekst; przez HTTP te narzędzia nie istnieją. Dwa opisane tutaj niosą zamiast tego wartości, więc można odczytać, czy dana możliwość jest podłączona, lub wyłuskać wersję wtyczki bez parsowania układu kolumn z powrotem do tego, z czego go wyrenderowano.

Pytanie o to, co można dołączyć i co z czym można połączyć

Dwa narzędzia odpowiadają na pytania, na które asystent musiałby w przeciwnym razie zgadywać odpowiedź: które encje Features można dołączyć do węzła i z czym węzeł może się połączyć. Oba wykonują to samo dopasowanie etykiet, które wykonuje kompilator, więc to, co proponuje asystent, jest zbiorem, który dopasowałaby kompilacja, a nie zbiorem wywnioskowanym ze schematu.

attach-candidates zwraca encje Features, których zadeklarowaną stosowalność spełniają etykiety węzła. Węzeł należy wskazać dokładnie na jeden z trzech sposobów:

  • node — metadata.name encji z przestrzeni roboczej, tak jak zwraca je list-entities. Dopasowanie obejmuje etykiety zadeklarowane w tym dokumencie.
  • graph_node z release — węzeł skompilowanego grafu, z kluczem takim, jakim opatruje go graf, w tym w postaci kwalifikowanej, którą ma węzeł wniesiony przez podagregat. Dopasowanie obejmuje sfinalizowane etykiety tego węzła, czyli te, które ocenia kompilacja.
  • labels — sam zbiór etykiet, bez wskazywania węzła. Nie wymaga żadnej współrzędnej, więc jeśli etykiety węzła są już znane, należy użyć tej postaci; niczego nie wyszukuje i nie odbudowuje grafu.

Odpowiedź zawiera etykiety, na których przeprowadzono dopasowanie, oraz informację, z którego z tych trzech zbiorów pochodzą, dzięki czemu każdego kandydata — lub jego brak — można wyjaśnić na podstawie samej odpowiedzi, bez ponownego wyliczania. Odczytywanie ich drugi raz inną drogą to sposób, w jaki wyobrażenie o etykietach węzła rozchodzi się z tym, co ustala kompilator.

Aby zapytać, co można dołączyć do jednego połączenia, które rysuje węzeł, należy dodać connection obok graph_node i release — jego socket i alias, tak jak zapisał je autor. Połączenie niesie dołączenia wypełniające sloty, które jego gniazdo deklaruje w konsumującej encji Component, więc odpowiedź zawiera wtedy również slots: każdy slot deklarowany przez gniazdo, z polami selector, required, inject, sensitive i description dokładnie tak, jak deklaruje je Component, oraz candidates, które mogą go wypełnić. Są to encje Features, których stosowalność spełniają etykiety węzła i których własne etykiety dopuszcza selektor slotu — dwie reguły, którym kompilacja poddaje takie dołączenie — więc kandydaci slotu zawsze należą do kandydatów samego węzła. Gdy niczego nie można wypełnić, slots jest puste, a noSlotReason podaje przyczynę: feature-created-connection (połączenie narysowała encja Feature, a do takiego nic się nie dołącza), ad-hoc-socket (gniazdo nie jest zadeklarowane przez Component) lub no-slot-declared (gniazdo nie deklaruje żadnego slotu). Pustego slots nie należy odczytywać jako „nic nie pasuje”; właśnie to ma wykluczyć przyczyna, której nie ma tam, gdzie slot istnieje. candidates obok nich zachowuje swoje znaczenie — to, co można dołączyć do samego węzła — a document, jeśli zostanie wysłany, niczego tu nie zmienia. connection obok node lub labels albo bez wskazania gniazda lub aliasu jest odrzucane, podobnie jak połączenie, którego węzeł nie rysuje. Są to te same odpowiedzi, których udziela serwer języka, na tych samych warunkach.

connection-candidates zwraca gniazda zależności deklarowane przez encję oraz, dla każdego gniazda, encje Components z przestrzeni roboczej, których zadeklarowane etykiety spełniają ograniczenie nałożone przez to gniazdo na jego cele. Przyjmuje metadata.name encji w node. W odróżnieniu od attach-candidates nie ma postaci bez współrzędnej: nie ma tu kształtu zbioru etykiet, ponieważ gniazda są odczytywane z własnej deklaracji wskazanej encji.

Jego dwie połowy nie są jednakowo kompletne, a odpowiedź mówi, która jest którą — nie należy przedstawiać ich jako jednej listy. Cele są kompletne: to komponenty, które to samo ograniczenie dopuszcza podczas kompilacji. Gniazda nie są i nie mogą być. Konsument może wymyślić połączenie, ale może konsumować tylko to, co deklaruje producent, więc autor może zasadnie zapisać gniazdo, którego encja z katalogu nigdy nie zadeklarowała, a zadeklarowane gniazda są pomocnym punktem wyjścia, a nie zbiorem dozwolonych nazw. Każde gniazdo mówi więc, czy jest declared, czy ad-hoc, a odpowiedź mówi, czy niezadeklarowane gniazdo jest w ogóle akceptowane w tej encji — własna powierzchnia zależności encji Component je akceptuje, ponieważ autor jest właścicielem topologii swojej aplikacji; powierzchnia dołączeń encji Feature nie, ponieważ dołączenie uczestniczy w topologii deklarowanej przez dołączaną encję Feature, a nie tworzy własnej. Ta otwartość jest konsekwencją swobody autora, a nie luką: aby o nie zapytać, należy przekazać socket z nazwą, której encja nie deklaruje.

Oba odpowiadają i na tym kończą. Żadne nie tworzy dołączenia ani krawędzi, nie zapisuje żadnego pliku ani nie proponuje tekstu takiej zmiany; przygotowanie i zastosowanie ewentualnej edycji należy do użytkownika.

Oba zwracają tę samą minimalną tożsamość, której używa tu każda inna odpowiedź — rodzaj, nazwę i plik źródłowy — i nic więcej. Wszystko inne, co warto wyświetlić o encji, jest już w list-entities dla tych samych trzech pól, więc należy złączyć obie odpowiedzi zamiast czytać dwie kopie, które mogłyby się różnić. Oba odrzucają nazwę, której nie mogą rozwiązać, zamiast odpowiadać pustą listą, z tego samego powodu co reszta tej powierzchni: pusta odpowiedź przedstawiłaby literówkę jako obiekt, który nie ma nic do zaoferowania. Wywołanie z labels nie ma nazwy, w której można się pomylić, więc pusty wynik oznacza tam dokładnie to, co mówi.

Wszystko, co serwer odczytuje jako materiały referencyjne, jest serwowane z tej maszyny — schematy JSON Schema są wbudowane w plik binarny, a dokumentacja jest odczytywana z pamięci podręcznej pakietu dokumentacji przechowywanej na maszynie, jak opisano poniżej. Tworzenie szkicu dokumentu startowego, walidacja, opisywanie, kompilacja i linting działają na przestrzeni roboczej i lokalnych pamięciach podręcznych, a żadne z nich nie sięga z własnej inicjatywy do rejestru: renderowanie serwuje przypiętą zewnętrzną referencję z magazynu adresowanego treścią i odrzuca nieprzypiętą, zamiast ją pobierać, co utrzymuje całą pętlę inspekcji i renderowania w trybie offline. Można poprosić o dwa odczyty z rejestru: describe z referencją do rejestru, które pobiera tę jedną współrzędną, niczego nie zapisuje, a przez HTTP sięga wyłącznie do rejestru skonfigurowanego w serwowanej przestrzeni roboczej; oraz scaffold z wysłanym example lub list, które pobiera pakiet dokumentacji z domyślnego rejestru przestrzeni roboczej, gdy maszyna nie przechowuje kopii dopuszczanej przez politykę podpisów przestrzeni roboczej, i weryfikuje go przed zachowaniem, tak jak robi to aggrega scaffold --example. Publikowanie i podpisywanie stanowią świadomą drugą stronę tego podejścia i zostały omówione wyżej.

Pomiędzy nimi znajduje się rozwiązywanie zależności encji Release — jedyna operacja tutaj, która pozyskuje treść: sięga do rejestru, ponieważ prośba o rozwiązanie zależności jest prośbą o ich pobranie. Dzieje się to tylko na żądanie i są dokładnie dwa sposoby, by o to poprosić — wywołanie pull, którego jest to jedynym zadaniem, lub wysłanie auto_pull do build, które wykonuje to samo rozwiązywanie jako pierwszy krok kompilacji. Poza tym nic nie pobiera niczego w imieniu użytkownika, a kompilacja, do której nie wysłano auto_pull, nie sięga do żadnego rejestru. Jedynym ustawieniem, które to zmienia, jest własne auto_pull przestrzeni roboczej: przestrzeń robocza tak skonfigurowana prosi każdą kompilację w niej o wcześniejsze rozwiązanie zależności, niezależnie od tego, skąd kompilacja jest uruchamiana, co omówiono poniżej.

Jedynym wyjątkiem wśród tych odczytów referencyjnych jest pozyskanie samego pakietu dokumentacji, które odbywa się niezależnie od wszystkich odczytów. Pakiet jest przechowywany raz na maszynę, w pamięci podręcznej współdzielonej przez wszystkie projekty Aggrega, po jednej kopii dla każdego rejestru i wersji — więc serwer uruchomiony w folderze, w którym nie można utworzyć pamięci podręcznej przestrzeni roboczej, i tak go zachowuje (zob. aggrega cache). Przy starcie, zanim odpowie na cokolwiek, serwer szuka tam kopii, którą dopuszcza sprawdzenie podpisu skonfigurowane w przestrzeni roboczej — to samo, któremu podlega pobranie pakietu — i pobiera pakiet, z użyciem tych samych ustawień ruchu wychodzącego co reszta CLI, tylko wtedy, gdy takiej kopii nie ma. Szukany pakiet to ten opublikowany dla wersji aggrega, którą uruchamia serwer, lub, jeśli dla niej żaden nie został opublikowany, najnowszy opublikowany dla wcześniejszej wersji — ten sam wybór, którego dokonują aggrega explain i aggrega scaffold --example — a każda strona, którą serwer udostępnia, i każde wyjaśnienie są odczytywane z pakietu, który uzyskał. Strony są więc już dostępne, zanim cokolwiek o nie poprosi, niezależnie od tego, co klient wyśle jako pierwsze, a inny serwer lub aggrega explain w innym projekcie znajduje tę samą kopię zamiast pobierać ją ponownie.

Udostępnienie strony jest wtedy odczytem tej kopii i nie sięga do żadnego rejestru. Zanim strona zostanie udostępniona, podpisy przechowywane obok kopii są ponownie weryfikowane według kontroli obowiązującej w obszarze roboczym, więc kopia wpuszczona przez luźniejsze ustawienie innego projektu nie zostanie udostępniona: gdy kontrola przypina klucz lub korzeń zaufania, weryfikacja działa offline, a gdy nie przypina żadnego z nich — jednym z takich przypadków jest wbudowana kontrola oficjalnego huba — pobiera publiczny korzeń zaufania Sigstore, tak jak robi to pull. Obszar roboczy offline nie może pobrać tego korzenia zaufania, więc offline weryfikuje względem korzenia zaufania, który wcześniejsze pobranie online na tej maszynie zostawiło w pamięci podręcznej przechowywanej przez klienta Sigstore w katalogu .sigstore w katalogu domowym, niezależnie od tego, jak dawno to pobranie nastąpiło, i niczego nie pobiera; na maszynie, która nigdy go nie pobrała, kontrola nie może zostać wykonana offline, kopia nie jest udostępniana, a strumień logów to odnotowuje. Ta weryfikacja jest wykonywana raz dla każdej kopii i każdej kontroli w czasie działania serwera, a strony odczytywane po niej są udostępniane na podstawie tego, co dopuściła: kopia pobrana później, obszar roboczy z inną kontrolą — w tym ze zmienionym w miejscu przypiętym korzeniem zaufania — odczyt wykonany offline lub odczyt offline, który znajduje na maszynie inny korzeń zaufania, są weryfikowane osobno. Kopia odrzucona przez kontrolę jest sprawdzana ponownie przy następnym odczycie, więc pobranie, które ją w międzyczasie dopuściło, nie zostaje unieważnione. Jeśli pakietu nie można pozyskać albo jedyna kopia jest odrzucana przez kontrolę, a ponowne pobranie jej według tej kontroli się nie powiedzie, serwer i tak się uruchamia, a wszystkie pozostałe funkcje działają; żądania dokumentacji zwracają odpowiedź „nie znaleziono”, a strumień logów serwera podaje przyczynę.

Budowanie na treści, którą Release już przypina

build renderuje Release do jego artefaktów w pamięci, a renderowanie może zażądać treści spod zdalnego adresu URL — na przykład schematu wartości wykresu ze zdalnym odwołaniem. Wejścia zewnętrzne są zamrożone na czas wywołania. Odwołanie, które plik blokady encji Release już przypina, jest obsługiwane z magazynu adresowanego treścią, co jest odczytem treści już obecnej na dysku, a nie pobraniem. Odwołanie, którego plik blokady nie przypina, jest odrzucane i wskazywane z nazwy zamiast pobierane: żądanie dotyczyło renderowania, a pozyskanie odwołania zarówno sięgnęłoby do sieci, jak i zapisałoby obiekt blob w magazynie jako skutek uboczny wytwarzania bajtów. To zamrożenie jest właściwością renderowania. Rozwiązywanie jest krokiem, który pozyskuje: renderuje Release, aby ustalić, o które zdalne odwołania prosi to renderowanie, pobiera je i zapisuje w tym samym zapisie pliku blokady, który zawiera przypięcia zależności. Rozwiązywanie zmienia więc to, które odwołania są przypięte w chwili uruchomienia renderowania, nigdy to, do czego renderowanie może sięgnąć — a odwołanie, którego żadne rozwiązanie nie przypięło, jest odrzucane w wywołaniu, które najpierw przeprowadziło rozwiązanie, dokładnie tak samo jak w takim, które tego nie zrobiło.

Pliki wracają jako bajty, które emituje rzeczywista kompilacja, a prawdziwość tego zapewniają dwie rzeczy łącznie. Pierwszą jest opisane wyżej zamrożenie: przypięte odwołanie jest odczytywane z magazynu, a nie pobierane. Drugą jest to, że odczytywany plik blokady nadal opisuje to, do czego Release się rozwiązuje — dlatego build to sprawdza i odrzuca plik blokady, który już nie pasuje, dokładnie tak jak aggrega build w terminalu. Odczyt przypiętych bajtów sam w sobie nie mówi nic o tym, czy były to właściwe bajty do odczytania.

Wszystkie trzy stany pliku blokady, aby postawa była jawna. Gdy pliku blokady nie ma wcale, build renderuje na podstawie tego, co obszar roboczy już przypina, i odrzuca każde zewnętrzne odwołanie, którego nie może obsłużyć, wskazując każde z nazwy; pozostawiony sam sobie ani nie wymaga pliku blokady, ani go nie zapisuje, a opisane wyżej sprawdzenie tego nie zmienia — nie ma pliku blokady do porównania, więc nic nie zostaje odrzucone. Gdy plik blokady pasuje, renderuje. Gdy plik blokady już nie pasuje, odmawia, a odmowa wskazuje, jak ją usunąć: należy wywołać pull z tym samym release i bez upgrade_targets, co uzgadnia plik blokady z tym, do czego Release rozwiązuje się obecnie. Odmowa zawiera też terminalową postać tej samej operacji, aggrega pull --release <release>. Każde z tych wywołań ją usuwa; to jedna operacja dostępna z dwóch miejsc, a nie dwie instrukcje do wyboru. Jeśli pull się kończy, a odmowa wraca, oba wywołania rozwiązywały na różnych wejściach — najczęściej catalog_dirs podane jednemu, a drugiemu nie, lub konfiguracja obszaru roboczego edytowana między nimi — i odmowa to stwierdza: należy wywołać oba z tymi samymi.

validate i describe wywołane z samym release podlegają temu samemu plikowi blokady. Gdy plik blokady nie odpowiada już temu, do czego rozwiązuje się Release, każde z nich odmawia zamiast odpowiedzieć, a jego tekst zawiera zatrzymanie z powodu rozbieżności, z którym odmawia build, i ten sam sposób jego usunięcia — tak jak w terminalu odmawiają aggrega validate --release i aggrega inspect --closure. Gdy plik blokady pasuje lub go nie ma, każde odpowiada tak jak zwykle.

Żądanie, aby kompilacja najpierw rozwiązała zależności

Po wysłaniu auto_pull kompilacja rozwiązuje zależności przed renderowaniem. Wykonuje to samo rozwiązywanie, które wykonuje pull — samą tę operację, a nie drugą napisaną dla kompilacji, więc obszar roboczy wypełniony przez kompilację i wypełniony przez wywołanie pull są wypełnione identycznie — zapisuje plik blokady encji Release, a następnie renderuje na podstawie tego, co zapisała. Ten krok sięga do rejestru i zapisuje, czego nie robi nic innego w build poza write, a write nie sięga do żadnego rejestru — dlatego jest wyłączony, chyba że się go zażąda.

Odpowiada na obie powyższe odmowy bez opuszczania protokołu. Release, którego nikt jeszcze nie rozwiązał, renderuje się z tych przypięć, które akurat istnieją, i odrzuca resztę; plik blokady, który się rozjechał, zatrzymuje kompilację od razu. Wysłanie auto_pull najpierw rozwiązuje i renderuje na podstawie pliku blokady wyprowadzonego z domknięcia, którego dotyczy ta kompilacja, więc oba przypadki wracają jako renderowanie, a nie jako coś do naprawienia. Aby rozwiązywanie i renderowanie były osobnymi krokami — by przeczytać, co zostało przypięte, przed renderowaniem — należy wywołać pull, a potem build, co stanowi te same dwie operacje z wglądem pomiędzy nimi.

Jedno wywołanie renderuje Release raz. Ustalenie, które zdalne odwołania konsumuje Release, samo jest renderowaniem, więc rozwiązywanie już wyrenderowało Release, którego dotyczy kompilacja — na podstawie właśnie zapisanych przypięć, ze wszystkimi bramkami, które uruchamia kompilacja. Kompilacja otrzymuje odpowiedź z tego renderowania zamiast je powtarzać, dlatego wysłanie auto_pull kosztuje jedno rozwiązanie, a nie drugie renderowanie. W ten sposób używane jest tylko renderowanie, które się zakończyło: jeśli rozwiązanie przypięło zależności, ale nie zdołało dokończyć wykrywania zewnętrznych odwołań, kompilacja renderuje sama na podstawie przypięć, które trafiły na miejsce, a nieprzypięte odwołanie zatrzymuje ją wtedy z nazwy, zamiast wrócić jako lista plików niepełna wobec tego, co emituje kompilacja.

To, co wraca, mówi, co zostało rozwiązane. Kompilacja, która wypełniła obszar roboczy, zawiera w odpowiedzi dependency_resolution, w kształcie, w jakim odpowiada pull: zapisany plik blokady, każde odwołanie, do którego sięgnęło rozwiązanie, z wersją, do której każde się rozwiązało, i miejscem, z którego pobrało je rozwiązanie tej kompilacji, liczby, które plik blokady zawiera potem, oraz własną relację rozwiązania wiersz po wierszu. Kompilacja, która nie wypełniała, nie zawiera takiego pola wcale, więc jego obecność pozwala rozróżnić oba przypadki bez czytania dysku. Wyrenderowane pliki są raportowane dokładnie tak jak w każdej innej kompilacji i nadal są zwracane w pamięci, chyba że wywołaniu wysłano też write — rozwiązywanie zapisuje plik blokady i pamięć podręczną artefaktów, nigdy artefakt.

Obszar roboczy może żądać tego na stałe, a wywołanie nie może tego wyłączyć. Własne ustawienie auto_pull obszaru roboczego włącza ten sam krok dla każdej kompilacji w tym obszarze, a auto_pull w wywołaniu dodaje się do tego ustawienia zamiast je nadpisywać: wystarczy jedno z nich i nie ma argumentu, który tłumiłby rozwiązywanie, o które poprosił obszar roboczy. W ten sam sposób ustawienie i aggrega build --auto-pull łączą się w terminalu, więc jeden obszar roboczy odpowiada tak samo niezależnie od tego, którą drogą przychodzi kompilacja.

Odrzucenie jest raportowane, a nie pochłaniane, i przy dostawcach, które zawiera ten plik binarny, odrzucenie zatrzymuje renderowanie: dostawca, który zażądał odwołania, zwraca odmowę, więc wywołanie odpowiada tym błędem i nie zwraca plików. Odwołanie jest wskazywane z nazwy tam, gdzie czytelnik może na nie zareagować, wraz z poleceniem, które je przypina: aggrega pull --release <path>. To samo przypinanie jest dostępne w tym interfejsie jako narzędzie pull, opisane poniżej w sekcji Rozwiązywanie zależności encji Release, więc asystent, który napotka tę odmowę, może na nią zareagować bez opuszczania protokołu. W pełni przypięte renderowanie nie mówi nic o żadnej z tych rzeczy. Zobacz aggrega pull, aby dowiedzieć się, co przypinanie pobiera i zapisuje, oraz aggrega build, gdzie nieprzypięte odwołanie jest raportowane i zatrzymuje przebieg w ten sam sposób.

Zapisywanie artefaktów tam, gdzie zapisuje je aggrega build

Po przesłaniu write ukończony render jest również zapisywany do dist/ w katalogu głównym obszaru roboczego, tam gdzie zapisuje go aggrega build. Jest to ten sam katalog, który wiersz poleceń wyznacza pod tym samym katalogiem głównym obszaru roboczego, a zapis jest tym samym zapisem, który on wykonuje, więc dla jednej encji Release w jednym obszarze roboczym aggrega build, aggrega/build serwera języka bez outputParent oraz to wywołanie zapisują jedno drzewo, bajt w bajt, i jednakowo nazywają ten katalog — w ostatnim wierszu polecenia, w outputDirectory serwera języka i w output_dir tej odpowiedzi. Katalog dist będący dowiązaniem prowadzącym poza obszar roboczy zostaje odrzucony, zanim cokolwiek w nim zostanie usunięte lub zapisane, tak jak w terminalu. W przypadku pominięcia, co jest ustawieniem domyślnym, artefakty są zwracane w pamięci i nic nie jest zapisywane.

Katalog główny obszaru roboczego należy do samego wywołania. Przez standardowe wejście i wyjście jest to katalog główny obszaru roboczego wyznaczonego przez wywołanie, jak opisano w sekcji W którym obszarze roboczym odpowiadane jest wywołanie: katalog wskazany przez workspace_root, w przeciwnym razie katalog główny, z którym uruchomiono serwer, a w przeciwnym razie obszar roboczy odnaleziony na podstawie katalogu, w którym serwer został uruchomiony — a jeśli encja Release wskazana ścieżką bezwzględną przenosi wywołanie do własnego obszaru roboczego tej encji Release, to katalog główny tego obszaru. Jest to katalog główny, pod którym aggrega build zapisuje dla tej samej encji Release i tego samego wskazanego katalogu głównego, więc folder, w którym akurat działa serwer, otrzymuje dist tylko wtedy, gdy jest katalogiem głównym wyznaczonym przez wywołanie, tak jak w terminalu otwartym w tym miejscu. Przez HTTP jest to obszar roboczy obsługiwany przez serwer i nic nie jest zapisywane poza nim.

Zapis sięga do obszaru roboczego, więc przez HTTP wymaga aggrega:workspace-write. Wywołanie z write sięga do obszaru roboczego na potrzeby tego wywołania, dokładnie tak jak kompilacja, która najpierw rozwiązuje swoje zależności: dane uwierzytelniające zawierające tylko aggrega:read otrzymują odpowiedź 403 wskazującą aggrega:workspace-write i nic nie jest zapisywane, a serwer, którego mcp.deny_reach wymienia workspace, odrzuca wywołanie, wskazując to ustawienie. Narzędzie pozostaje na liście narzędzi każdego wywołującego, a kompilacja bez write pozostaje dostępna dla wywołującego z zakresem tylko do odczytu.

Zapis następuje na końcu. Gdy przesłano również auto_pull, wywołanie rozwiązuje zależności, renderuje, a następnie zapisuje, w tej kolejności. Wywołanie odrzucone na dowolnym wcześniejszym etapie — encji Release, obszaru roboczego, katalogu katalogu wpisów, rozwiązywania, renderowania — nie zapisuje żadnego artefaktu.

Odpowiedź wskazuje, co zostało zapisane. output_dir to katalog — pełny przez standardowe wejście i wyjście, dist przez HTTP — a files wymienia każdy zapisany plik względem niego, z zawartością przy response_format: detailed i samą ścieżką przy concise; tekst podaje, ile plików zapisano i gdzie. Wywołanie bez write nie zawiera output_dir, więc jego brak oznacza, że nic nie zostało zapisane. Zapis, który kończy się niepowodzeniem po zakończeniu renderowania — na przykład do katalogu głównego obszaru roboczego, w którym nikt nie może zapisywać — daje odpowiedź o niepowodzeniu wskazującą katalog i przyczynę i nie wymienia żadnego pliku jako zapisanego: część zapisu może znajdować się na dysku, a wymienienie wyrenderowanych plików jako zapisanych twierdziłoby więcej, niż się stało.

Żaden argument nie wskazuje katalogu i żaden nie żąda śladu. O tym, dokąd trafiają artefakty, decyduje obszar roboczy wyznaczony przez wywołanie, nigdy samo wywołanie, a kompilacja zapisana stąd nie pozostawia katalogu .trace obok swoich wyników; kompilacja ze śladem to aggrega build --trace.

Co build mówi oprócz swoich plików

Build przenosi każde zgłoszone przez siebie ostrzeżenie w samej odpowiedzi. Są to ustalenia, które aggrega build wypisuje w trakcie pracy: nazwa różniąca się o jedną edycję od zadeklarowanej, parametr, którego nic nie odczytuje, cel, który nie może uwzględnić napisanego pola, niezatrzymujący werdykt nadzoru, katalog graniczny odziedziczony przez encję Release po rozszerzanej encji Release, który rozwiązuje się do tej samej ścieżki, właściwość, którą encja Component lub Feature osiągana przez Release deklaruje zarówno w filarze values, jak i infra. Żadne z nich nie zmienia wyniku: build zawierający ostrzeżenia nadal się powiódł, a zwracane pliki są plikami, które wytworzył. Przychodzą w kolejności, w jakiej wypisuje je terminal, więc czytelnik porównujący oba źródła widzi jedną sekwencję, a nie dwie: najpierw wszystko, co zgłosił render, w kolejności zgłoszenia, potem ustalenia dotyczące encji Release i tego, co ona osiąga, które aggrega build wypisuje po zakończeniu renderu, a na końcu, w buildzie wysłanym z write, ostrzeżenie wskazujące każdy plik, który zapis znalazł obok własnych, a którego sam nie zapisał, i który pozostawia na miejscu — to samo, które aggrega build wypisuje po zapisaniu swoich plików (Pliki, których kompilacja nie zapisała).

Znajdują się w odpowiedzi, a nie tylko w tekście podsumowania, ponieważ asystent obsługujący ten interfejs nie czyta żadnego terminala, a ustalenie, o którym nikt się nie dowie, jest ustaleniem, którego nie dokonano. Każde zawiera severity — warn dla czegoś wymagającego uwagi, info dla odnotowanej obserwacji — oraz message; code, jeśli jego klasa go przypisuje, dzięki czemu można reagować na konkretny warunek bez dopasowywania tekstu; oraz key_path wskazujący klucz w napisanym dokumencie, którego dotyczy ustalenie, jeśli dotyczy ono klucza. Ustalenie dotyczące kształtu wdrożonej topologii nie wskazuje żadnego klucza, ponieważ jego współrzędne należą do wdrożenia, a nie do dokumentu, i zamiast tego w komunikacie podaje, czego dotyczy.

Dwa rodzaje ustaleń wypisywanych przez terminal trafiają do tej odpowiedzi w inne miejsce niż advisories, ponieważ każdy ma miejsce, które mówi więcej. Zarejestrowany znacznik wycofania znajduje się w deprecations, niezależnie od tego, czy zarejestrował go plik blokady dla przypiętego odwołania, czy rejestr zaufania wtyczek obok niego dla wtyczki dołączonej w roli zwracającej werdykt akceptacji lub odrzucenia. describe encji Release wymienia ten sam zbiór we własnym deprecations, a validate encji Release wśród swoich notices, przy czym żadne z nich nie zmienia werdyktu; rejestr zaufania, który istnieje, ale nie można go odczytać, powoduje odrzucenie każdego z tych wywołań, zamiast zostać uznany za rejestr, który niczego nie odnotowuje. Rodzic, po którym dziedziczy encja, a którego nie udało się rozwiązać, zatrzymuje build, więc jest wymieniony w tekście odmowy, a nie na liście jako ustalenie, które niczego nie zmieniło. Jeden rodzaj jest ograniczony tym, co to narzędzie wczytuje, a nie tym, co zawiera jego odpowiedź: aggrega build wczytuje każdy skonfigurowany katalog encji przed rozwiązaniem encji Release, a powiadomienie o wycofanym kształcie katalogu pochodziłoby z tego wczytania, natomiast to narzędzie odczytuje tylko to, co osiąga Release, i nie wykonuje takiego wczytania, więc nie zgłasza takiego powiadomienia. Obecnie żaden build go nie zgłasza, więc oba zgłaszają te same ustalenia.

Release, który niczego nie zgłasza, niczego nie mówi: klucz jest nieobecny, a nie obecny i pusty, więc sama jego obecność oznacza, że jest coś do przeczytania.

Co zwraca odrzucona kompilacja

Kompilacja, która odmawia, odpowiada w tych samych polach co kompilacja zakończona powodzeniem, wypełnionych w takim zakresie, w jakim przebieg dotarł. Wraca oznaczona jako niepowodzenie, z poprawką jako tekstem, a ustrukturyzowany ładunek znajduje się obok tego tekstu, zamiast zostać nim zastąpiony. Odmowa zgłoszona podczas renderowania encji Release jest wyrażona słowami kompilatora, jak opisuje to sekcja Odmowa zgłoszona podczas renderowania poniżej, i dodaje jedno własne pole. Ostrzeżenia są w nim zawarte: fazy, które się wykonały, zgłosiły to, co zgłosiły, a są to ustalenia, na które należy zareagować, aby obejść odmowę, dlatego przychodzą jako wpisy, do których można dopasowywać, a nie jako proza, którą trzeba by parsować. deprecations i declined_external_inputs są w nim z tego samego powodu — zarejestrowany znacznik jest zgłaszany, ponieważ znacznik został zarejestrowany, a odrzucone odwołanie, ponieważ odwołanie zostało odrzucone, i żaden z tych faktów nie wynika ze sposobu, w jaki przebieg się zakończył.

files nie zgłasza niczego przy odmowie i nie jest polem, z którego należy odczytywać wynik. Nic nie zostało wyemitowane, więc nie ma artefaktów do wymienienia. Nie należy rozgałęziać logiki na podstawie obecności klucza: jest on zgłaszany w obu przypadkach, a puste files samo w sobie nie pozwala odróżnić kompilacji, która odmówiła, od takiej, która się wykonała i niczego nie wyemitowała. Należy odczytać flagę niepowodzenia w wyniku — jest to własny wyróżnik protokołu — a files odczytywać jako to, czym jest: listę tego, co zostało wyrenderowane, a także zapisane, gdy wywołanie otrzymało write.

Zakres ostrzeżeń przy odmowie wyznacza to, jak daleko dotarł przebieg, a nie to, co odpowiedź jest w stanie przenieść. Odmowa ze sprawdzenia wykonywanego przed rozwiązaniem encji Release — przypięty wpis w pamięci podręcznej nie odpowiada już zarejestrowanemu dla niego skrótowi i żaden katalog nie przechowuje przypiętych bajtów albo nie udało się rozwiązać zależności encji Release — nie zgłasza żadnych ostrzeżeń, ponieważ nic nie zostało jeszcze zgłoszone. Ustalenia dotyczące tego, jak encja Release składa się z encją Release, którą rozszerza, są zgłaszane w chwili jej rozwiązania, przed każdym kolejnym sprawdzeniem, więc niesie je każda późniejsza odmowa: Manifest mapuje typ na recipe, która go nie implementuje, encja osiągana przez Release nie spełnia swojego schematu, plik blokady nie odpowiada już temu, do czego rozwiązuje się Release. Własne ustalenia renderowania są zgłaszane w trakcie renderowania, więc odmowa z jednego z tych wcześniejszych sprawdzeń nie niesie żadnego z nich, a odmowa z renderowania niesie wszystko, co zgłoszono przed nią. Dlatego advisories przy odmowie należy czytać dokładnie tak samo jak przy powodzeniu: to, co znalazł ten przebieg, w kolejności, w jakiej wypisuje to terminal.

Odmowa z powodu dziedziczenia encji po rodzicu, którego nie udało się rozwiązać, wymienia w swoim tekście każde takie dziedziczenie, słowami, które wypisuje dla niego aggrega build, aby było wiadomo, które naprawić. Ten szczegół jest powodem zatrzymania kompilacji, dlatego znajduje się w tekście, a nie wśród ustaleń, które niczego nie zmieniły; ustalenia dotyczące kompozycji zgłoszone przed nim są w advisories, jak przy każdej późniejszej odmowie.

Katalog odczytywany przez Release, którego nie da się przejść, jest odrzucany, zanim cokolwiek zostanie zapisane, tak jak odrzuca go aggrega build. Jest to katalog wskazany przez wywołanie w catalog_dirs, który nie istnieje — tak jak aggrega build odrzuca nieistniejący katalog --catalog — albo taki, który istnieje, ale nie da się go odczytać. aggrega build wczytuje każdy katalog odczytywany przez Release przed rozwiązaniem encji Release i zatrzymuje się na tym, którego nie może przejść; build najpierw przechodzi te same katalogi, nie odczytując w nich żadnego dokumentu, przed jakimkolwiek rozwiązywaniem zależności i przed renderowaniem — więc kompilacja z auto_pull nie zapisuje pliku blokady i nic nie jest renderowane. Tekst wskazuje katalog tak, jak zgłasza go wiersz poleceń, w jednym wierszu: katalog, catalog load i powód podany przez system plików. Ładunek wskazuje encję Release, z pustym files i bez ustaleń, ponieważ nic się nie wykonało. Katalog wymieniony w konfiguracji obszaru roboczego, który nie jest katalogiem — na przykład nic tam nie istnieje — jest odrzucany przed tym przejściem, w tej samej postaci, a tekst zawiera odmowę, którą wydaje dla niego aggrega build, wskazując wpis oraz plik konfiguracyjny i wiersz, które go wymieniają (Skąd są odczytywane encje lokalne). Katalog zawierający dowiązanie prowadzące poza katalog, wewnątrz którego muszą pozostać jego odczyty, jest odrzucany w tym samym momencie, bez zapisania czegokolwiek, a tekst wskazuje dowiązanie i miejsce, do którego prowadzi — aggrega build odrzuca go w ten sam sposób.

Przykładowy kształt, aby obie połowy były konkretne. Release deklarująca parametr, którego nie odczytuje żadne odwołanie, i której renderowanie nie może się następnie zakończyć, wraca jako niepowodzenie, którego tekst niesie odmowę renderowania, a ładunek niesie ostrzeżenie o nieodczytanym parametrze z jego severity, message, code i key_path — ten sam wpis, z tymi samymi wartościami, który ta sama Release zgłasza w odpowiedzi, gdy renderowanie się kończy — obok wpisu refusal dotyczącego tego, co zatrzymało renderowanie. Release, która rozszerza inną i dziedziczy katalog graniczny niezawierający zmiennej szablonu, a której Manifest mapuje typ na recipe, która go nie implementuje, wraca jako ta odmowa z jednym wpisem advisories na każdy odziedziczony katalog, każdy z code inherited-boundary-directory-is-literal. Release, której zależności nie da się rozwiązać, w obszarze roboczym, w którym wszystkie wymienione katalogi istnieją, wraca jako niepowodzenie bez klucza advisories, ponieważ nic nie zostało zgłoszone w chwili zatrzymania.

Odmowa zgłoszona podczas renderowania

Encja Release, której kompilator odmawia podczas renderowania — Workload wskazujący slot, którego jego Component nie deklaruje, asercja, która nie jest spełniona, szablon, którego nie da się obliczyć — wraca z odmową sformułowaną słowami kompilatora i z każdą przyczyną pod nią, tymi samymi słowami, które cli-build zwraca dla tej samej encji Release: najpierw renderowany węzeł, potem to, co w nim odmówiło. Gdy odmowa wskazuje zarejestrowany warunek, tekst dodaje jego nazwę — krótki kod i kod opisowy, do dopasowywania — tak jak zrobiłoby to explain-error. Tekst zaczyna się od wskazania etapu, który odmówił: The build failed during rendering; nothing was written to disk. dla odmowy zgłoszonej przez renderowanie oraz The build refused before rendering anything; nothing was written to disk. dla odmowy zgłoszonej przez przebieg kompilatora, zanim cokolwiek zostało wyrenderowane — gdy odmawia kompozycja grafu, na którym pracuje renderowanie, albo asercja zadeklarowana przez encję Component lub Feature.

Ładunek zawiera tę samą odmowę jako jeden wpis, refusal, dzięki czemu wywołujący, który musi zmienić dokument, odczytuje, który to dokument i w którym miejscu, bez parsowania zdania:

  • file — dokument, na który wskazuje odmowa: Recipe encji Workload, Recipe lub FeatureRecipe deklarujący niespełnioną asercję, encja Release lub Aggregate, która zapisała wpis odrzucany przez kompozycję grafu, albo Aggregate encji Release w przypadku odmowy, która nie wskazuje żadnego dokumentu.
  • key_path — klucz w tym dokumencie, jeśli odmowa go wskazuje: .spec.workload dla odmowy dotyczącej encji Workload, własny klucz asercji pod .spec.assertions dla niespełnionej asercji, własny klucz wpisu dla odmowy wpisu. Odmowa dotycząca encji Workload jest umieszczana na jej kluczu workload i nie dokładniej, ponieważ Workload oceniany przez sprawdzenie to wynik szablonu, a szablon zapisuje wiersze, których jego autor nigdy nie napisał; ścieżki wskazywane przez odmowę wewnątrz tego wyrenderowanego encji Workload pozostają w jej message.
  • line i column — pozycja tego klucza, liczona od jedynki, przy czym kolumna w jednostkach UTF-16. Brak ich, gdy odmowa nie wskazuje klucza lub dokument go nie zawiera: pozycja jest podawana tylko wtedy, gdy została znaleziona.
  • severity — halt, poziom ważności ustalenia, które zatrzymało kompilację.
  • code i short_code — dwa identyfikatory warunku, jeśli odmowa wskazuje zarejestrowany warunek.
  • message — tekst odmowy, dokładnie taki, jaki występuje w tekście odpowiedzi.
  • findings — obecne tylko wtedy, gdy odmowa łączy kilka ustaleń, jak robi to kompozycja grafu z każdym znalezionym naruszeniem: jeden wpis na ustalenie, w kolejności podanej przez odmowę, każdy w tym samym kształcie — z własnymi file, key_path, line, column, severity, code, short_code i message. Własne pola odmowy wskazują wtedy miejsce jej pierwszego ustalenia, a jej message zawiera wszystkie ustalenia, tak jak tekst; wiersz poleceń wypisuje każde ustalenie jako osobną diagnostykę.

Wpis jest obecny zawsze, gdy odmówił sam przebieg kompilatora — podczas renderowania lub przed nim: przy kompozycji grafu albo przy asercji zadeklarowanej przez encję Component lub Feature, która nie wskazuje żadnego dokumentu, więc jej wpis wskazuje Aggregate. Kompilacja zakończona powodzeniem nie zawiera go, podobnie jak kompilacja odrzucona przez sprawdzenie wykonywane przed uruchomieniem kompilatora — plik blokady, mapowania encji Manifest, zależności encji Release — której odmowa składa się wyłącznie z tekstu. Wartość, którą autor zadeklarował jako wrażliwą, jest ukrywana w odmowie, gdy zgłasza ją kompilator, więc wpis i tekst zawierają to samo, co cli-build i terminal — zob. co odmowa mówi o zadeklarowanej wartości.

Rozwiązywanie zależności encji Release

pull rozwiązuje zależności katalogowe i źródłowe encji Release do lokalnej pamięci podręcznej i zapisuje plik blokady tej encji Release. Znajduje się na tej powierzchni z powodu wartego wyjaśnienia: obie powyższe odmowy — renderowanie, które odrzuciło nieprzypięte odwołanie zewnętrzne, oraz kompilacja zatrzymana, ponieważ plik blokady nie odpowiada już temu, do czego rozwiązuje się Release — rozwiązuje się przez przypięcie, a asystent, który musi poprosić użytkownika o uruchomienie polecenia, nie ma możliwości rozwiązania ich samodzielnie. Sekcja Co asystent może zrobić bez pytania użytkownika opisuje, co zapisuje i jak daleko to sięga.

Należy przekazać release, ścieżkę encji Release, bezwzględną lub względną wobec katalogu głównego obszaru roboczego — według tej samej umowy, której używa każdy inny argument ścieżki w tym miejscu. workspace_root i catalog_dirs nadpisują wykrywanie obszaru roboczego i katalogów dokładnie tak samo jak w build. Oba obowiązują na serwerze osiąganym przez standardowe wejście i wyjście; przez HTTPS te dwa argumenty są odrzucane, a ścieżka musi rozwiązywać się wewnątrz obszaru roboczego obsługiwanego przez proces, jak opisuje Jeden proces, jeden obszar roboczy.

Domyślnie uzgadnia, zamiast rozwiązywać od nowa. Przypięcie zapisane już w pliku blokady jest respektowane i pobierane w tej wersji, a jeśli rejestr nie udostępnia już tych bajtów, zostaje odrzucone, a nie po cichu przypięte na nowo. Odwołanie bez przypięcia — nowo dodane lub ręcznie usunięte z pliku blokady — jest rozwiązywane od nowa i dodawane. Odwołanie, którego nie ma już wśród rozwiązanych zależności, jest usuwane. Niezmieniony zbiór zależności pozostawia więc plik identyczny co do bajtu, łącznie z zapisanym znacznikiem czasu, dzięki czemu wywołanie, które nie zmieniło żadnego przypięcia, nie tworzy różnic dla nikogo, kto później przegląda obszar roboczy.

verify porównuje i pozostawia plik blokady bez zmian. Sprawdza zapisany plik blokady względem rozwiązania, które powyższe wywołanie uzgadniające wykonałoby teraz, respektując zapisane przypięcia dokładnie tak jak to wywołanie, i zwraca niepowodzenie w przypadku rozbieżności lub gdy nie ma pliku blokady do porównania — w ten sposób asystent sprawdza, czy przypięcie jest potrzebne, zanim cokolwiek przepisze plik blokady. Nic, co zapisuje tamto wywołanie, nie jest zapisywane — ani plik blokady, ani zapisane obok niego tożsamości wtyczek, ani entity.lock — natomiast pamięć podręczna treści jest odczytywana i wypełniana dokładnie tak, jak odczytuje i wypełnia ją tamto wywołanie. Raportuje też zestaw narzędzi zapisany w pliku blokady: wersję kompilatora, który zapisał plik, oraz wersję każdej wtyczki podstawowej, którą ten kompilator zawierał. Jest to raportowane na potrzeby audytu i nigdy nie jest porównywane z uruchomionym plikiem binarnym, ponieważ zestaw narzędzi nie należy do tego, co przypina plik blokady, a sprawdzanie go pośrednio przypinałoby kompilator — różnica zestawu narzędzi nie jest rozbieżnością.

upgrade_targets rozwiązuje od nowa wskazane odwołania i nic więcej. Należy podać jeden lub więcej URI encji w czystej postaci autorskiej — core/database, a nie postać z wersją. Każde wskazane przypięcie jest usuwane i rozwiązywane od nowa do najwyższej dostępnej wersji, a wszystkie inne przypięcia i zapisane wejścia zewnętrzne pozostają bez zmian. URI, który nie pasuje ani do zapisanego przypięcia, ani do skonfigurowanego dołączenia, jest odrzucany, a nie ignorowany.

Celowo nie ma argumentu, który rozwiązuje wszystko od nowa naraz. Wiersz poleceń ma taką postać i odrzuca ona cały plik blokady przed ponownym rozwiązaniem z bieżącego stanu rejestru. Na tej powierzchni argument nie istnieje, więc takiego wywołania w ogóle nie da się złożyć, zamiast być przyjętym, a potem odrzuconym: nikt nie obserwuje strumienia protokołu, więc nie ma nikogo, kto potwierdziłby całościowe odrzucenie. Gdy jest to potrzebne, i tylko przez standardowe wejście i wyjście, polecenie uruchamia cli-pull, czyli powierzchnia, przy której obecny jest człowiek; wywołujący, który łączy się z tym serwerem przez HTTP, uruchamia je zamiast tego w terminalu na hoście. verify nie można łączyć z upgrade_targets — jeden pozostawia plik blokady bez zmian, a drugi go przepisuje — ani z pin_sources, niezależnie od jego wartości: ten argument decyduje, czy rozwiązanie zapisuje przypięcia brakujące w entity.lock, czy z ich powodu odmawia, a porównanie nie zapisuje entity.lock, więc nie zrobiłoby żadnej z tych rzeczy. Wywołanie wysyłające którąkolwiek z tych par jest odrzucane, zanim cokolwiek zostanie rozwiązane, ze zdaniem wskazującym parę. Publikowany schemat narzędzia nie określa tych dwóch wykluczeń, ponieważ klient, który je renderuje, może odczytać je jako wymóg wysłania verify; klient poznaje je z odmowy. Wiersz poleceń i demon odrzucają te same pary.

Wynik wskazuje, co zostało rozwiązane, a nie tylko, że coś zostało. Zawiera plik blokady, który zapisano lub z którym porównano; resolved, każde odwołanie, do którego dotarło rozwiązanie, z wersją, do której każde się rozwiązało, rodzajem zapisywanym przez autora, jeśli rozwiązanie go zapisuje, oraz jego source — skąd ten przebieg wziął odwołanie, słowem, które aggrega pull --detail wypisuje dla tego samego rozwiązania: fetched-fresh, cache-reuse, local, in-binary lub external; liczby artefaktów źródłowych, wejść zewnętrznych i zaufanych tożsamości wtyczek, które plik blokady zawiera potem; oraz diagnostics, własną relację rozwiązania w kolejności zgłaszania każdego wiersza — które przypięcie użyto ponownie, który podpis sprawdzono, którą wersję pominięto jako wycofaną. Przy uruchomieniu polecenia te wiersze trafiają do terminala; tutaj są w odpowiedzi, ponieważ wywołujący, który nie czyta terminala, nie ma innego sposobu ich otrzymania. verified występuje tylko przy porównaniu, więc jego brak pozwala odróżnić przebieg, który zapisywał, od takiego, który tylko porównywał. source opisuje ten przebieg na tej maszynie, więc plik blokady go nie zapisuje, a describe, który raportuje zależności encji Release, nie podaje żadnego.

Odmowa odpowiada w tych samych polach, wypełnionych na tyle, na ile przebieg dotarł. Po obliczeniu rozwiązania resolved jest przekazywane niezależnie od werdyktu — zwłaszcza przy werdykcie rozbieżności, ponieważ to właśnie ta odmowa, przy której wywołujący musi zdecydować, co zmienić. Odmowa sprzed tego momentu, na przykład ścieżka encji Release, która się nie rozwiązuje, przekazuje poprawkę jako tekst i żadnego rozwiązania, ponieważ nie było czego przekazać.

Gdy przypięcia są kompletne, a wejścia zewnętrzne nie, wywołanie i tak kończy się powodzeniem i to zgłasza. Ustalenie, jakie wejścia zewnętrzne zużywa Release, jest renderowaniem, a renderowanie może się nie powieść, gdy przypięcia zależności są już poprawne i zapisane na dysku. Zgłoszenie całego wywołania jako nieudanego kazałoby powtórzyć poprawną pracę, dlatego zamiast tego w wyniku powodzenia ustawiane jest incomplete_external_inputs, wskazujące, co się zatrzymało: przypięcia zależności są kompletne, przypięcia wejść zewnętrznych mogą nie być.

To najwolniejsze narzędzie w tym miejscu, a uzgadniająca operacja pusta nie jest szybką ścieżką. Rozwiązanie ponosi pełny koszt, aby ustalić, że zbiór zależności się nie zmienił, więc wywołanie, które niczego nie przepisuje, kosztuje tyle co pierwsze rozwiązanie — przy małej encji Release sekundy, a nie milisekundy, i rośnie wraz z rozmiarem zbioru zależności. verify jest tańszą z dwóch postaci, ponieważ porównanie pomija zejście do źródeł poszczególnych komponentów, które wykonuje przebieg zapisujący. Jeśli klient narzuca limit czasu na wywołanie, to właśnie to narzędzie należy z nim porównać. Prośba o informowanie o postępie, opisana niżej, oznacza, że w trakcie wywołania coś nadchodzi, a nie nic aż do końca — co rozwiązuje problem limitu bezczynności w kliencie lub w czymkolwiek, co znajduje się między klientem a serwerem osiąganym przez HTTP, ale nie limitu łącznego czasu trwania jednego wywołania.

Encja, której entity.lock nie zapisuje przypięcia dla odczytywanego przez nią wejścia, powoduje odmowę pobrania, a odmowa wskazuje krok, który je zapisuje. Od encji Recipe lub FeatureRecipe, z której Release buduje z katalogów, i która odczytuje zdalne źródło zapisane w pełnej postaci lub importuje plik przez swoje artefakty, oczekuje się, że już ma te przypięcia obok siebie — jej autor zapisuje je za pomocą pin, opisanego niżej. pin_sources prosi to wywołanie o wykonanie tego kroku w imieniu autora dla każdej takiej encji zamiast odmowy, zapisując entity.lock obok każdej z nich; jest to ten sam krok, który wykonuje narzędzie pin, i zapisuje te same bajty. Jeśli argument zostanie pominięty, decyduje ustawienie pin_sources_at_pull przestrzeni roboczej; jeśli zostanie wysłany, decyduje w obu kierunkach, więc pin_sources: false powoduje odmowę nawet w przestrzeni roboczej skonfigurowanej do przypinania. Encja, do której rozwiązywanie dotarło w pamięci podręcznej, a nie w jednym z katalogów, nie ma tu zapisywalnego miejsca i nigdy nie jest przypinana przez to wywołanie.

Przypinanie własnych wejść encji

pin zapisuje w entity.lock obok encji Recipe lub FeatureRecipe przypięcie treści dla każdego wejścia, które encja odczytuje spoza własnego dokumentu: zdalnego źródła, którego współrzędne są zapisane w pełnej postaci, oraz pliku importowanego przez wpis artifacts. Jest to ten sam krok, który aggrega pin wykonuje w terminalu, a zapisywany plik blokady jest identyczny bajt po bajcie z tym, który zapisuje to polecenie. Należy przekazać entity, dokument encji, jako ścieżkę bezwzględną lub względną wobec katalogu głównego przestrzeni roboczej, na tej samej zasadzie co każdy inny argument ścieżki w tym miejscu; przez HTTPS musi ona wskazywać miejsce wewnątrz przestrzeni roboczej obsługiwanej przez proces.

Nie podaje się encji Release, ponieważ żadna nie jest potrzebna. Źródło, którego współrzędne nie zawierają szablonu, wskazuje jeden artefakt dla każdej encji Release używającej tej encji, więc krok rozwiązuje je i przypina bez niczego, co dostarcza Release. Źródło, którego współrzędne pochodzą z szablonu, nie jest tu przypinane: to, jaki artefakt wskazuje, rozstrzyga każda encja Release, a pull przypina każdą tożsamość, do której się ono rozwiązuje, w pliku blokady tej encji Release.

Wynik mówi, co krok zrobił z plikiem blokady. Zawiera entity, jej kind i name oraz pinnable, które ma wartość false dla rodzaju nieodczytującego niczego, co zapisuje plik blokady — encji Component lub Feature — i wtedy nic obok encji nie zostało zmienione, a pozostałe pola są nieobecne. W przeciwnym razie zawiera zapisany lock, changed o wartości false, gdy plik blokady zawierał już każde przypięcie i pozostał identyczny bajt po bajcie, removed, gdy encja nie odczytuje już niczego, co zapisuje plik blokady, i jej plik blokady został usunięty, oraz pins, po jednym wpisie na klasę przypięć z liczbą przypięć w pliku blokady po operacji. dry_run zwraca plik blokady, który krok by zapisał, jako content i nie zapisuje niczego obok encji; pamięć podręczna treści nadal się wypełnia, ponieważ wejścia są rozwiązywane dokładnie tak samo jak w innym przypadku.

Zapisuje wewnątrz przestrzeni roboczej i łączy się z hostami, które wskazują źródła encji — repozytorium chartów, hostem Git, adresem URL — więc przez HTTP jest dopuszczane dla poświadczenia o zakresie dopuszczającym pull i odrzucane dla poświadczenia uprawniającego tylko do odczytu. Przez standardowe wejście i wyjście ta sama możliwość jest dostępna również jako cli-pin, które uruchamia polecenie; przez HTTP to narzędzie nie istnieje.

Informowanie o postępie długiego wywołania

Wywołanie raportuje postęp, gdy się o to poprosi, a prośba to jedno pole. Należy umieścić progressToken w _meta wywołania — ciąg znaków lub liczbę, dowolnie wybraną. Wraca on w każdym raporcie dokładnie w podanej postaci i jest jedynym elementem raportu wskazującym na wywołanie: raport na nic nie odpowiada, więc nie ma identyfikatora. Jeśli token nie zostanie wysłany lub zostanie wysłany jako null, nic się nie zmienia — wywołanie otrzymuje taką samą odpowiedź jak bez niego. Token o jakimkolwiek innym kształcie jest odrzucany, zanim wywołanie cokolwiek zrobi, z podaniem dwóch dopuszczalnych form, zamiast zostać pominięty: wywołujący, który poprosił o informacje i spotkał się z ciszą, nie ma na czym oprzeć działania.

Przychodzi notifications/progress z tokenem i licznikiem rosnącym z każdym raportem. Nie ma sumy ani komunikatu i żadne z nich nie jest brakiem czekającym na uzupełnienie: praca raportuje, że weszła w kolejną fazę, więc sumę można by tylko wymyślić, a zdanie można by tylko ułożyć tutaj zamiast przekazać dalej. Na podstawie rosnącego licznika należy rysować wskaźnik nieokreślony; nie ma ułamka, którym można by wypełnić pasek.

Przez HTTP odpowiedź staje się strumieniem zdarzeń, i to dopiero wtedy, gdy coś faktycznie zostanie zaraportowane. Jest serwowana jako text/event-stream, oznaczona jako nieprzeznaczona do buforowania i z nagłówkiem X-Accel-Buffering: no dla pośrednika, który w przeciwnym razie przetrzymywałby każde zdarzenie do końca pracy i zamieniał strumień w powolną pojedynczą odpowiedź. Każdy raport to jedno zdarzenie, a właściwa odpowiedź wywołania jest ostatnim zdarzeniem przed zamknięciem strumienia. Gdy praca milczy, strumień co pewien czas przenosi wiersz komentarza, który dla wszystkiego pośrodku jest bajtami na aktywnym połączeniu, a do klienta nie dociera jako nic. Wywołanie, które poprosiło o postęp i trafiło na pracę niczego nieraportującą, nadal otrzymuje odpowiedź w postaci jednego obiektu JSON, ponieważ strumień otwiera pierwszy raport, a nie token.

W strumieniu wynik należy odczytywać z ostatniego zdarzenia, a nie z kodu statusu. Status i nagłówki są zapisywane przy otwarciu strumienia, czyli przed zakończeniem pracy, więc wywołanie, które raportuje, a potem odmawia, przekazuje odmowę jako ostatnie zdarzenie pod już wysłanym statusem. Zamknięcie połączenia w trakcie strumienia kończy pracę i nic więcej nie jest dla niej zapisywane, dokładnie tak jak Jak kończy się wywołanie opisuje dla każdego innego wywołania.

Przez standardowe wejście i wyjście raporty są wierszami poprzedzającymi wiersz odpowiedzi, ujętymi tak jak każdy inny komunikat w tym strumieniu — jeden obiekt JSON na wiersz, w kolejności zapisu — a po nich następuje wiersz odpowiedzi. Po zakończeniu wywołania nic nie jest raportowane w żadnym z transportów.

Raportuje tu rozwiązywanie zależności encji Release. pull raportuje za każdym razem, gdy rozwiązywanie wchodzi w fazę. build raportuje tylko wtedy, gdy najpierw rozwiązuje — ponieważ wysłano auto_pull albo ponieważ własne ustawienie przestrzeni roboczej wymaga rozwiązywania przy każdej kompilacji — gdyż raportowanie należy do tego kroku: kompilacja renderująca z już posiadanych przypięć do niczego nie dociera i niczego nie raportuje, więc token w tym wywołaniu nie zmienia sposobu odpowiedzi. Każde wywołanie raportuje też każdy krok, w który wchodzi jego praca i na który czeka — odczyt rejestru, pobranie artefaktu lub pakietu dokumentacji, pierwszą kompilację wtyczki — czyli kroki, które wiersz poleceń pokazuje osobie obok wskaźnika postępu. Wywołanie, którego praca nie czeka na żaden z nich, niczego nie raportuje, co jest nieszkodliwe, a nie jest błędem: odpowiedź jest taka sama jak bez niego.

Sprawdzanie, które połączenie jest zapisane w danym miejscu dokumentu

connection-at-position odpowiada na pytanie poprzedzające część dotyczącą połączeń w dwóch powyższych narzędziach, na wypadek gdy dysponuje się miejscem w dokumencie, a nie węzłem na grafie — linią, na którą się patrzy w encji Aggregate lub Release. Należy przekazać file, czyli dokument, względny wobec katalogu głównego obszaru roboczego lub bezwzględny i odczytywany z dysku tak, jak odczytuje go insertion-point; position, czyli line i character, oba liczone od zera, mierzone w jednostkach wskazanych przez position_encoding dokładnie tak, jak insertion-point odczytuje ten argument; oraz release, którego skompilowany graf rejestruje połączenia. Encja Release jest wymagana także dla miejsca w encji Aggregate: węzeł grafu i połączenie istnieją tylko na skompilowanym grafie.

Odpowiedź jest jedną z dwóch połówek. Gdy miejsce leży na wpisie połączenia, zawiera graphNode i connection — jego socket, jego alias oraz document, w którym odczytano miejsce — czyli dokładnie to, co attach-candidates przyjmuje obok graph_node i release, oraz to, co attachment-container przyjmuje, aby wskazać, gdzie trafia załącznik do tego połączenia; ten kontener znajduje się wewnątrz tego samego wpisu, w którym wypadło miejsce. W przeciwnym razie zawiera noConnectionReason z zamkniętego zbioru: no-connection-entry (miejsce nie leży na żadnym wpisie, w którym zapisuje się załącznik), feature-created-connection (miejsce leży na wpisie encji Release dla połączenia utworzonego przez encję Feature) lub unknown-connection (miejsce leży na wpisie, który encja Release zapisuje dla połączenia nieobecnego w skompilowanym grafie). Czytelna odpowiedź podaje przyczynę słowami.

Miejsce w dowolnym punkcie wpisu jest wewnątrz niego — na aliasie, na jego target, wewnątrz jego features — a gdy wpisy są zagnieżdżone, wygrywa najbardziej wewnętrzny. Miejsce na własnym kluczu gniazda, powyżej aliasów pod nim, nie jest wewnątrz żadnego z nich. Wpisy to te, które rejestruje skompilowany graf: w encji Aggregate każde połączenie tworzone przez komponent, przy jego wpisie pod aliasem połączenia w dokumencie, w którym komponent został napisany, a dla komponentu wniesionego przez zaimportowany moduł jest to własny dokument tego modułu; w encji Release każdy wpis dla krawędzi, który ona zapisuje. Połączenie zapisane jako lista celów oraz połączenie tworzone przez własny blok zależności encji Feature nie mają wpisu, w którym zapisuje się załącznik. To, czy klucz jest połączeniem, nigdy nie jest ustalane na podstawie jego nazwy.

Odpowiada i kończy działanie. Niczego nie zapisuje do żadnego pliku. Dokument spoza obszaru roboczego, którego nie da się odczytać lub który nie jest poprawnym składniowo YAML, wraca jako nieudany wynik wskazujący, co należy zmienić, tak jak w przypadku insertion-point; tak samo miejsce bez line lub character oraz position_encoding spoza trzech dopuszczalnych wartości.

Pytanie, w którym kontenerze należy umieścić dołączenie

attachment-container odpowiada na pytanie pośrednie między odpowiedzią o kandydatach a punktem wstawienia. Wiadomo już, co dołączyć do węzła; zanim można zapytać, w którym miejscu pliku to zapisać, trzeba wiedzieć, w którym pliku i w którym kontenerze wewnątrz niego. Należy przekazać graph_node — identyfikator węzła na skompilowanym grafie, w postaci, w jakiej graf go kluczuje — oraz release, do którego należy ten graf. Oba są wymagane: identyfikator węzła jest kluczem grafu jednej encji Release i bez niej nic nie znaczy.

Nie należy samodzielnie składać tej ścieżki. Identyfikator węzła i ścieżka obejmującego go podsystemu są zapisywane z kropkami między częściami, a kropka jest dozwolonym znakiem w nazwie wpisywanej przez autora — dlatego spoza dokumentu nie da się odróżnić kropki strukturalnej od kropki wewnątrz nazwy. Samodzielnie złożona ścieżka wyglądałaby poprawnie, a wskazywałaby klucz, którego nikt nie zapisał, i następująca po niej edycja utworzyłaby ten klucz, zamiast zostać odrzucona. Co gorsza, identyfikator węzła w ogóle nie zawiera śladu obejmującego go podsystemu: komponent zdefiniowany wewnątrz subsystems.billing.subsystems.payments ma klucz ledger, dokładnie tak jak komponent najwyższego poziomu. Należy zapytać o kontener.

Odpowiedź zawiera node, czyli węzeł, którego dotyczy; file, czyli dokument, w którym ten węzeł zdefiniowano; oraz container, czyli ścieżkę strukturalną od korzenia tego dokumentu w postaci listy segmentów — ["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. Celowo jest to lista, a nie połączony ciąg znaków: połączoną ścieżkę odbiorca musiałby ponownie podzielić, co przywracałoby opisaną wyżej niejednoznaczność jedno wywołanie później. Należy przekazać file i container do insertion-point bez zmian.

file jest częścią odpowiedzi, a nie czymś, co już wiadomo. Węzeł wniesiony przez zaimportowany moduł został zdefiniowany we własnym dokumencie tego modułu pod nazwą nadaną mu przez moduł, więc zarówno plik, jak i ostatni segment kontenera różnią się od wszystkiego, co zostało wysłane.

W przypadku dołączenia do jednego połączenia, które rysuje węzeł, należy dodać connection z jego socket, alias i document, który jest tu wymagany, ponieważ wpis może się znajdować w każdym z dwóch dokumentów. Przy aggregate odpowiedzią jest własny wpis połączenia w dokumencie, w którym zdefiniowano węzeł, z blokiem features na końcu; połączenie narysowane przez encję Release nie ma tam wpisu i zostaje odrzucone. Przy release jest to wpis dla krawędzi pod wpisem encji Release dla węzła — ["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"] — zgłaszany niezależnie od tego, czy encja Release już zapisuje ten wpis dla krawędzi, tak aby insertion-point wskazał klucze, które pozostają do zapisania; encja Release, która nie zapisuje żadnego wpisu dla węzła, zostaje odrzucona, ponieważ to nie to narzędzie decyduje, gdzie węzeł zostaje umieszczony. Połączenie narysowane przez encję Feature zostaje odrzucone w obu dokumentach.

Odpowiada i kończy działanie. Nie tworzy dołączenia, niczego nie zapisuje do żadnego pliku i nie układa tekstu. Nie rozstrzyga też, co może zostać dołączone — od tego jest attach-candidates. Węzeł, którego graf nie zawiera, lub węzeł, dla którego graf nie rejestruje dokumentu, zwraca nieudany wynik wskazujący, co należy zmienić, a nie odpowiedź z pustym polem.

Ustalanie, gdzie w dokumencie należy umieścić wpis

insertion-point odpowiada na pytanie, które następuje po odpowiedzi o kandydatach. Gdy już ustalono, co dołączyć lub połączyć, trzeba jeszcze wiedzieć, w którym miejscu pliku to zapisać. Narzędzie zwraca pozycję i kolumny wcięcia, dzięki czemu edycję można zastosować bez samodzielnego parsowania dokumentu. Ponieważ odczytuje ono strukturę samego dokumentu, a nie kształt jakiegokolwiek konkretnego rodzaju, describe-capabilities indeksuje je pod każdym rodzajem encji, do którego zawęża się wynik.

Należy przekazać file — dokument, względny wobec katalogu głównego obszaru roboczego lub bezwzględny, znajdujący się wewnątrz obszaru roboczego: dokument osiągnięty przez dowiązanie prowadzące poza obszar, do pliku lub do katalogu po drodze, nie znajduje się w nim i jest odrzucany w obu transportach — oraz container, ścieżkę strukturalną od korzenia dokumentu do kontenera, w którym ma się znaleźć wpis; każdy element jest kluczem mapowania lub pozycją w sekwencji zapisaną dziesiętnie.

Ścieżkę kontenera podaje wywołujący. Narzędzie odczytuje strukturę dokumentu i nigdy nie wywnioskowuje, gdzie coś należy umieścić, na podstawie nazwy, typu ani pozornego znaczenia. Wywołujący wskazuje klucz, a narzędzie mówi, gdzie w tym dokumencie trafiają wpisy tego klucza — które segmenty ścieżki plik już zawiera, w jakich kolumnach leżą jego wpisy i do którego ostatniego wiersza sięga jego najbardziej wewnętrzny blok. W przypadku dołączenia encji Feature do węzła skompilowanego grafu nie trzeba znać tego klucza samodzielnie: opisane wyżej attachment-container zwraca dokument i kontener, a oba trafiają tutaj bez zmian.

Odpowiedź zawiera position o zerowej szerokości, której line i character liczone są od zera; entryIndent i indentStep, czyli kolumny, od których należy pisać; oraz missingContainerKeys, klucze kontenera, których ten dokument jeszcze nie zawiera, od najbardziej zewnętrznego, zapisywane przed wpisem. entryShape informuje, czy kontener zawiera mapping, czy sequence, i zwraca unknown, gdy kontenera jeszcze nie ma lub jest pusty, ponieważ dokument tego nie określa — wtedy kształt wybiera wywołujący. indentStepMeasured mówi, czy krok został zmierzony na podstawie zagnieżdżeń samego dokumentu, czy jest wartością zastępczą dla dokumentu, który żadnych nie zawiera. Gdy ustawione jest precededByLineBreak, tekst należy zacząć od znaku nowego wiersza: pozycja leży na końcu wiersza, po którym następuje wpis, co mieści się w zakresie niezależnie od tego, czy plik kończy się znakiem nowego wiersza, i nie narusza żadnego już zapisanego bajtu. missingContainerKeys należy odczytać nawet wtedy, gdy kontener powinien istnieć — pozycja zastosowana bez kluczy, które muszą ją poprzedzać, daje dokument, którego nie da się już sparsować.

position_encoding określa jednostki, w których mierzone jest zwracane przesunięcie znaku: utf-8, utf-16 lub utf-32. Jest to tutaj argument, ponieważ żadna z wersji tego protokołu go nie negocjuje, a domyślnie przyjmuje utf-16, czyli to, co przyjmuje sesja edytora, gdy klient niczego nie negocjuje — dlatego wywołujący, który niczego nie określi, otrzymuje identyczną odpowiedź w obu interfejsach. Wartość spoza tych trzech jest odrzucana, a nie po cichu zastępowana domyślną, ponieważ przesunięcia zmierzone w jeden sposób i zastosowane w buforze mierzonym inaczej uszkadzają dokument przy pierwszym znaku spoza ASCII.

Narzędzie odpowiada i na tym kończy. Niczego nie zapisuje w żadnym pliku, nie tworzy tekstu wpisu i nie stosuje żadnej edycji; utworzenie tekstu i decyzja o jego zastosowaniu należą do wywołującego. Żądanie, które nie wskazuje miejsca, w którym może się znaleźć wpis, wraca jako nieudany wynik z informacją, co zmienić — dokument spoza obszaru roboczego, nieczytelny lub niebędący poprawnym YAML; ścieżka kontenera bez segmentów lub z pustym segmentem; ścieżka przechodząca przez skalar, wewnątrz którego nie można niczego dopisać; ścieżka prowadząca do kolekcji zapisanej w stylu przepływowym, gdzie dopisanie przepisałoby bajty już zapisane przez autora zamiast dodać wiersz; albo ścieżka adresująca sekwencję blokową czymś, co nie jest jednym z jej indeksów. Jeśli edycja ma zostać zastosowana przez narzędzie, a nie samodzielnie, służy do tego Zastosowanie jednej ograniczonej edycji do dokumentu.

Stosowanie jednej ograniczonej edycji do dokumentu

edit-document stosuje to, co lokalizują dwa powyższe narzędzia. Jedno wywołanie dodaje jeden wpis w jednym kontenerze albo ustawia jeden skalar i nie może zrobić nic innego. Zapisuje wskazany dokument wewnątrz obszaru roboczego, dlatego przez HTTPS wymaga aggrega:workspace-write: wywołujący, który ma tylko aggrega:read, widzi je na liście narzędzi, ale jego wywołanie zostaje odrzucone z podaniem tego zakresu.

Edycję wskazuje się w edit, a zbiór jest zamknięty. add-component dodaje instancję komponentu w kontenerze komponentów; attach-feature dołącza Feature do wskazanego węzła; wire-edge tworzy połączenie w jednym z gniazd tego węzła; set-value ustawia jedną wartość w tym węźle. Nazwa spoza tych czterech jest odrzucana, a nie interpretowana. Nie ma edycji, która usuwa, zastępuje już napisany blok, zmienia kolejność czegokolwiek lub zapisuje dosłownie podane bajty — nie jest to więc narzędzie do zapisu plików i nie można go w ten sposób używać.

Należy przekazać file, dokument — względny wobec katalogu głównego obszaru roboczego lub bezwzględny, i wewnątrz obszaru roboczego: dokument spoza niego, wskazany wprost lub przez dowiązanie wyprowadzające poza niego, jest odrzucany w obu transportach bez niczego odczytanego ani zapisanego; node, ścieżkę strukturalną od korzenia dokumentu jako listę segmentów; name, klucz, pod którym zapisywany jest wpis; oraz value, zawartość tego wpisu. node jest listą z tego samego powodu, dla którego attachment-container odpowiada listą: kropka jest dozwolona w nazwie wpisanej przez autora, więc złączona ścieżka mogłaby wskazać klucz, którego nikt nie napisał, a wpis zostałby tam utworzony zamiast odrzucony. Dla add-component ścieżka wskazuje sam kontener komponentów, ponieważ dodawany wpis jest węzłem; dla pozostałych trzech wskazuje węzeł, którego dotyczy edycja, a kontener wynika z edycji. socket jest odczytywany dla wire-edge i ignorowany w pozostałych przypadkach. Znaczenie value wynika z edit — encja, której żąda wpis, węzeł, na który wskazuje połączenie, lub skalar, na który ustawiana jest wartość — i jest to wartość JSON własnego typu, więc liczba pozostaje liczbą, cyfra w cudzysłowie pozostaje tekstem, a pominięcie jej nie ustawia niczego. Mapowanie lub sekwencja są odrzucane, ponieważ zapisanie bloku nie należy do tych edycji.

Każdy bajt, którego edycja nie dotyka, zostaje zachowany. Dokument jest parsowany wyłącznie po to, by zlokalizować kontener i wiersz, na którym kończy się jego blok, więc komentarze, puste wiersze, styl cudzysłowów, skalary złożone i dosłowne oraz kształt końcowego znaku nowego wiersza zostają zachowane, a krok zagnieżdżenia jest mierzony na podstawie własnych wcięć dokumentu, a nie narzucany. To samo żądanie wobec tego samego dokumentu daje te same bajty.

Wynik musi być dokumentem, który można by napisać ręcznie, i od tego zależy zapis. Złożony dokument jest sprawdzany względem schematu jego własnego rodzaju i trafia na dysk tylko wtedy, gdy przejdzie tę kontrolę. Żądanie, które dałoby coś odrzucanego przez schemat, jest odrzucane z podaniem właściwości, której schemat nie dopuszcza, i jej miejsca, a plik pozostaje bajt w bajt taki, jaki był — odrzucona edycja jest więc nieodróżnialna od niepodjętej i można ponowić poprawione żądanie wobec dokumentu wyjściowego. Wpis, który już istnieje i zawiera to, o co poproszono, jest operacją pustą; wpis o tej nazwie zawierający coś innego jest odrzucany, a nie zastępowany.

Odpowiedź zawiera container, ścieżkę strukturalną, w której znalazł się wpis; created_containers, poziomy kontenerów, które ta edycja musiała utworzyć, od najbardziej zewnętrznego, puste w zwykłym przypadku, gdy cała ścieżka już istniała; oraz written, dokument, który trafił na dysk, puste, gdy nic nie trafiło. Należy odczytać created_containers: edycja, która po cichu zapisała dwa zagnieżdżone bloki nieobecne w dokumencie, jest inaczej nieodróżnialna od takiej, która dodała jeden wpis do bloku napisanego samodzielnie.

dry_run robi wszystko oprócz zapisu. Edytowany dokument wraca jako content, nic nie jest tworzone, a written jest puste — dla klienta, który przedstawia wynik autorowi przed zapisaniem. Każde inne zachowanie jest takie jak przy zapisie, łącznie z kontrolą schematu, więc żądanie, które zapis by odrzucił, jest odrzucane również w tym trybie. Bez tej opcji dokument jest zapisywany, a content jest nieobecne, ponieważ dokument jest wtedy na dysku i wskazuje go written.

To, czy tworzone połączenie jest semantycznie dopuszczalne — czy gniazdo jest jednym z deklarowanych przez producenta albo czy spełniona jest stosowalność Feature — nie jest tu rozstrzygane. Na to odpowiada validate.

Na standardowym wejściu i wyjściu ta sama funkcja jest dostępna również jako cli-edit-document, które uruchamia polecenie i zwraca wypisany przez nie tekst; przez HTTP to narzędzie nie istnieje i funkcja jest tam dostępna przez to opisane tutaj.

Przekształcanie obcego opisu w szkice encji

import przekształca opis wytworzony przez inne narzędzie — na przykład przepływ wyeksportowany z kreatora agentów — w szkice plików autorskich Aggrega. Zapisuje te pliki w przestrzeni roboczej obsługiwanej przez ten serwer, dlatego przez HTTPS wymaga aggrega:workspace-write: wywołujący, który ma tylko aggrega:read, widzi to narzędzie na liście narzędzi, ale jego wywołanie zostaje odrzucone ze wskazaniem tego zakresu.

Należy przekazać source, czyli plik lub katalog do przekształcenia. Ścieżka jest bezwzględna lub względna wobec katalogu głównego przestrzeni roboczej — to ta sama umowa, której używa każdy inny argument ścieżki w tym interfejsie — a na serwerze osiąganym przez HTTPS jest rozwiązywana wewnątrz przestrzeni roboczej obsługiwanej przez ten serwer.

Katalog jest wczytywany dokładnie jako te pliki, które wybierają wzorce plików jego importera. Wykres (chart) lub projekt to katalog i source może go wskazywać. Importer otrzymuje wtedy te pliki katalogu, na dowolnej głębokości, które wybiera jeden ze wzorców plików zadeklarowanych w jego sygnaturach, każdy nazwany swoją ścieżką wewnątrz katalogu zapisaną ukośnikami, w kolejności posortowanej, wraz z plikami, które jego załącznik plugins.importer wskazuje w with.sources, pod ich nazwami bazowymi; plik z katalogu i plik z with.sources o tej samej nazwie są odrzucane, zamiast by jeden przesłaniał drugi. Importer, który nie deklaruje wzorców plików, wczytuje jeden plik i odrzuca katalog, w warunku An importer that declares no file patterns is handed a directory (Importer, który nie deklaruje wzorców plików, otrzymuje katalog), a katalog niezawierający żadnego pliku wybieranego przez jego wzorce również jest odrzucany. Katalog jest ograniczony do samego siebie, gdziekolwiek się znajduje: dowiązanie wśród plików, które import by wczytał, lub do katalogu, prowadzące poza niego, jest odrzucane, zanim cokolwiek zostanie wczytane, a do dowiązania do katalogu nigdy się nie wchodzi — jak opisuje A directory you import. Na serwerze osiąganym przez HTTPS sam katalog jest rozwiązywany wewnątrz przestrzeni roboczej, a więc także każdy wczytany z niego plik.

Importer to jeden z przechowywanych w katalogu przestrzeni roboczej albo jeden z importerów rdzenia kompilatora. Tłumaczenie wykonuje plugin importera, który ogłasza format źródła: jeden z przechowywanych w katalogu przestrzeni roboczej albo jeden z importerów rdzenia kompilatora, które obsługują swoje formaty w każdej przestrzeni roboczej bez wpisu w katalogu. To narzędzie go wybiera, uruchamia i zapisuje to, co wytworzył. Załącznik plugins.importer, którego uri wskazuje importer po tożsamości i wersji — importer/<name>:<version>, tak jak zapisuje go aggrega plugin add importer — dołącza ten importer: jeśli ogłasza on format źródła, to on jest uruchamiany, w tej wersji, niezależnie od tego, jaki inny importer również ogłasza ten format, i otrzymuje źródła i ustawienia with tego załącznika, których nie otrzymuje żaden inny importer. Jeśli format ogłasza kilka importerów i żaden z nich nie jest dołączony — między innymi importer rdzenia i importer o innej nazwie przechowywany w katalogu dla tego samego formatu — wywołanie zostaje odrzucone z ich wskazaniem, jak opisuje Configuration. Wskazany format, którego nie ogłasza żaden importer, zostaje odrzucony ze wskazaniem możliwości, którą importer musiałby ogłosić — import:langflow dla źródła Langflow — czyli tego, co deklaruje importer dodawany do katalogu, a nie z ogólnym brakiem, który trzeba potem interpretować.

Importer podstawowy, którego maszyna serwera nie posiada, jest pobierany jeden raz, przez pierwszy import, który go potrzebuje. Import pobiera go z domyślnego rejestru obsługiwanego obszaru roboczego, sprawdza jego zgodność z modułem publikowanym przez wydanie kompilatora, weryfikuje jego podpis zgodnie z polityką zaufania tego rejestru oraz używane przez niego funkcje hosta, tak jak pull weryfikuje pobierany plugin, i przechowuje go w pamięci podręcznej treści obszaru roboczego, dzięki czemu każdy późniejszy import odczytuje go stamtąd i nie łączy się z żadnym rejestrem. Nic innego nie jest dla niego zapisywane — ani plik blokady, ani zapis zaufanych pluginów. Przez HTTPS jest to jedyny rejestr, z którym wywołanie tego narzędzia może skłonić serwer do połączenia, w granicach, które Jakie poświadczenia zużywa wywołanie wyznacza dla odczytu z rejestru: rejestr jest domyślnym rejestrem obszaru roboczego obsługiwanego przez ten serwer, więc jest to rejestr skonfigurowany dla tego obszaru roboczego; nic w wywołaniu nie wskazuje rejestru ani nie przenosi poświadczeń; a pobranie korzysta z własnego logowania i polityki zaufania tego hosta. Narzędzie nadal sięga do obszaru roboczego i nigdzie dalej, więc aggrega:workspace-write to wszystko, czego potrzebuje wywołanie: po pobraniu pozostaje jedynie moduł we własnej pamięci podręcznej treści obszaru roboczego. Moduł, który nie przejdzie weryfikacji, jest odrzucany tak samo jak w terminalu i nic nie jest zachowywane. Gdy modułu nie można pobrać — obszar roboczy jest offline, jego rejestr jest nieosiągalny lub rejestr go nie zawiera — wywołanie jest odrzucane w ramach A plugin’s .wasm is not on this machine (plik .wasm pluginu nie znajduje się na tej maszynie), z podaniem importera, jego wersji oraz tego, co umieszcza jego moduł na maszynie.

Gdy przestrzeń robocza nie wskazuje żadnego folderu katalogu, import odczytuje katalog publikowany przez jej domyślny rejestr. Przestrzeń robocza, w której workspace.catalog_dirs, AGGREGA_CATALOG_DIRS i folder główny nie wskazują żadnego folderu katalogu, odczytuje katalog biblioteki standardowej jako jedną podpisaną migawkę, w catalog/snapshot w domyślnym rejestrze obsługiwanej przestrzeni roboczej — tym samym rejestrze, z którego pobierany jest importer podstawowy, osiąganym na tych samych warunkach, przy czym nic w wywołaniu nie wskazuje rejestru ani nie przenosi poświadczeń. Migawka jest pobierana raz: jej podpis jest weryfikowany zgodnie z polityką zaufania tego rejestru, a sama migawka jest przechowywana w pamięci podręcznej treści przestrzeni roboczej i odczytywana tam jako folder katalogu, powiązana ze swoim skrótem, bez ponownego zwracania się o nią do żadnego rejestru. Którą migawkę odczytuje wywołanie: z upgrade — najnowszą; w przeciwnym razie tę, którą wskazuje rekord w folderze wyjściowym, pobraną za pomocą jej skrótu, jeśli maszyna jej nie przechowuje; w przeciwnym razie tę, którą przestrzeń robocza ostatnio pobrała jako najnowszą; w przeciwnym razie najnowszą. Rekord zapisywany przez import wskazuje odczytaną migawkę za pomocą jej skrótu, więc późniejsze wywołanie tworzące szkice w tym samym folderze odczytuje ten sam katalog. W trybie offline wywołanie, które musiałoby pobrać migawkę, jest odrzucane ze wskazaniem, co uruchomić, a upgrade jest odrzucane niezależnie od tego, co przechowuje maszyna, ponieważ tylko rejestr może stwierdzić, która migawka jest najnowsza. Rejestr, który nie publikuje żadnej migawki, pozostawia import bez katalogu, a wpis warn w diagnostics to zgłasza. Przestrzeń robocza, która wskazuje folder katalogu, importuje względem niego i nie pobiera żadnej migawki, a upgrade niczego tam nie zmienia.

Jeśli pominie się format, format jest rozpoznawany na podstawie sygnatur deklarowanych przez importery — zarówno z katalogu, jak i importerów rdzenia. Zapisuje je encja Plugin każdego importera: składnię, w której wczytuje się źródło, nazwy plików, do których sygnatura się stosuje, oraz ścieżki, które przetworzone drzewo musi lub nie może zawierać. Źródło jest parsowane — parserem, który katalog przestrzeni roboczej udostępnia dla danej składni, albo, dla składni, dla której katalog nie udostępnia parsera, parserem wbudowanym w kompilator — raz dla każdej składni, w której wczytuje je sygnatura stosująca się do jego nazwy, a używany jest format tego jednego importera, którego sygnatura pasuje. Importer wczytuje następnie źródło tym samym parserem. Sygnatury importerów rdzenia wczytują plik jako JSON lub YAML, a te, które nie wskazują pliku, wczytują go jako JSON — importera Dify jako YAML — więc rozpoznanie pliku importowanego samodzielnie wczytuje go w obu i nie wymaga parsera w katalogu przestrzeni roboczej: kompilator ma wbudowany parser JSON i YAML, a parser udostępniany przez katalog jest używany zamiast nich. Katalog jest rozpoznawany w ten sam sposób na podstawie swoich plików: każdą sygnaturę sprawdza się względem plików katalogu wybieranych przez jej wzorce, a sygnatura bez wzorca nie stosuje się do żadnego z nich. Rozpoznawanie czyta wskazany plik — lub, w przypadku katalogu, tylko pliki wybierane przez wzorce sygnatury — i nie korzysta z sieci. Źródło, do którego nie pasuje żadna sygnatura, zostaje odrzucone z prośbą o format i wskazaniem formatów ogłaszanych przez importery — albo, w przypadku katalogu, z prośbą o przesłanie jednego z jego plików osobno jako source lub o format, którego importer deklaruje wzorce plików, ze wskazaniem tylko tych formatów — w warunku No importer recognises the source (Żaden importer nie rozpoznaje źródła); źródło, do którego pasują sygnatury więcej niż jednego formatu, zostaje odrzucone z ich wskazaniem, w warunku More than one importer recognises the source (Więcej niż jeden importer rozpoznaje źródło); w żadnym z tych przypadków źródło nie trafia do zgadniętego importera. W obu przypadkach należy przesłać format, aby wskazać format wprost — w przypadku katalogu taki, którego importer deklaruje wzorce plików, ponieważ katalog jest wczytywany wyłącznie za ich pomocą. Pusty format jest odrzucany, a nie traktowany tak, jakby go pominięto, ponieważ są to różne żądania.

Przesłanie target powoduje utworzenie szkicu encji Manifest, względem której buduje się szkicowana encja Release, dla jednego dostawcy. target to zdolność dostawcy — słowo, z którym wiąże się spec.capability encji Recipe, np. compose lub helm — i jest to --target polecenia aggrega import, składane przez tę samą operację, więc wywołanie i polecenie tworzą te same pliki z tego samego źródła. Dla każdego typu komponentu i każdego typu funkcji, których potrzebują szkice — w komponentach szkicowanej encji Aggregate, ich połączeniach i jej podsystemach, w encjach Aggregates z katalogu, które ona składa, oraz w dołączeniach szkicowanej encji Release — w kolejności, w jakiej szkice deklarują go po raz pierwszy, import szuka w katalogu obszaru roboczego encji Recipes, a dla typu funkcji receptur funkcji, które implementują ten typ i wiążą się z tą zdolnością. Gdy jest dokładnie jedna — kilka wersji jednej z nich liczy się jako jedna — Manifest mapuje typ na nią przez jej nazwę kwalifikowaną zdolnością, bez wersji, np. compose/postgres, którą pierwszy pull przypina w pliku blokady w najwyższej dostępnej wersji. Gdy jest ich kilka o różnych nazwach, mapuje tę nazwaną tak jak sam typ, np. helm/postgres dla core/datastore/postgres. Gdy nie ma żadnej albo jest kilka i żadna nie nosi takiej nazwy, typ pozostaje niezmapowany, a wpis warn w diagnostics podaje go i przyczynę — w przypadku kilku każdą z nazwy — więc budowanie szkiców zatrzymuje się, wskazując każdą jego instancję lub dołączenie, z błędem No Recipe is mapped for a component or feature instance (Żadna encja Recipe nie jest zmapowana dla instancji komponentu lub funkcji), dopóki mapowanie nie zostanie dodane. Gdy importer sam szkicuje Manifest, aby wybrać encję Recipe, przez którą renderuje się instancja, lub recepturę funkcji spośród kilku, każde zapisane przez niego mapowanie, które katalog oferuje dla tego typu i tej zdolności, zostaje zachowane, każde inne jest odrzucane z wpisem warn, a typy, które pozostawia, są mapowane jak wyżej. Manifest jest szkicowany jako manifest.yaml obok szkicowanej encji Release, z nazwą i wersją takimi jak Release, a spec.manifest encji Release otrzymuje tę nazwę — komentarz, który importer zapisał w tym miejscu, zostaje zastąpiony i nic innego w encji Release się nie zmienia. Encja Release, która już wskazuje Manifest, pozostaje bez zmian, a gdy import nie tworzy szkicu encji Release, Manifest jest szkicowany obok encji Aggregate, z jej nazwą i wersją, a wpis info informuje, że nic się do niego nie odwołuje. Manifest i zmieniona encja Release są szkicami jak pozostałe: w written, w rejestrze i zwracane przy dry_run. Wartość target, z którą nie wiąże się żadna encja Recipe w katalogu, jest odrzucana przed uruchomieniem importera z błędem An import’s target names a capability no Recipe in the catalog binds to (Cel importu wskazuje zdolność, z którą nie wiąże się żadna encja Recipe w katalogu), z podaniem jej w przesłanej postaci oraz zdolności, z którymi wiążą się Recipes katalogu, i nic nie jest zapisywane. Bez target żaden Manifest nie jest szkicowany — z wyjątkiem sync, który tworzy szkic dla celu przesłanego do wcześniejszego importu; pusty target jest odrzucany, a nie traktowany tak, jakby go pominięto.

Należy przesłać output_dir, aby wskazać katalog na szkice. Jeśli się go pominie, szkice trafiają pod katalog główny przestrzeni roboczej rozwiązanej przez wywołanie — tam, gdzie zapisuje je aggrega import, gdy nie wskazano miejsca docelowego, niezależnie od miejsca uruchomienia, i tam, gdzie zapisuje je aggrega/import serwera języka, gdy jego żądanie żadnego nie wskazuje. Miejsce docelowe jest opcjonalne we wszystkich trzech i wskazuje się je tak samo jak każdą ścieżkę przesyłaną do tego serwera. Przez HTTP jest to katalog wewnątrz przestrzeni roboczej obsługiwanej przez ten serwer, zapisany względem jej katalogu głównego: wartość wychodząca poza katalog główny, bezwzględna lokalizacja poza nim oraz katalog prowadzący poza niego przez dowiązanie — włącznie z katalogiem, który jeszcze nie istnieje pod takim dowiązaniem — są odrzucane ze wskazaniem output_dir, a nic nie zostaje wczytane ani zapisane. Przez standardowe wejście i wyjście jest przyjmowany tak, jak go wskazano, jak każda ścieżka tam: wartość względna jest rozwiązywana względem katalogu głównego przestrzeni roboczej rozwiązanej przez wywołanie, a bezwzględna może wskazywać katalog poza przestrzenią roboczą, w którym szkice są tworzone tak, jak tworzy je aggrega import --output-dir. To, co jest tam zapisywane, jest ograniczone, po rozwiązaniu dowiązań, do przestrzeni roboczej — lub, dla katalogu wskazanego poza nią, do tego katalogu — więc dowiązanie wewnątrz niego prowadzące na zewnątrz jest odrzucane i nic nie zostaje zapisane. Pusty output_dir jest odrzucany, a nie traktowany tak, jakby go pominięto. Na standardowym wejściu i wyjściu cli-import przenosi --output-dir polecenia także jako własny output_dir; wartość względna jest tam rozwiązywana w folderze, w którym działa polecenie: w katalogu głównym przestrzeni roboczej wskazanym przez wywołanie, w przeciwnym razie w tym, z którym uruchomiono serwer, a w przeciwnym razie w folderze, w którym działa serwer.

Każda szkicowana ścieżka jest sprawdzana względem katalogu wyjściowego, zanim cokolwiek zostanie zapisane. Ścieżka wychodząca poza niego jest odrzucana ze wskazaniem zarówno ścieżki, jak i katalogu, a nic nie zostaje zapisane — nawet pliki z tego samego zestawu, których ścieżki były poprawne, ponieważ odrzucony import, który pozostawił część siebie, to wynik, o który nikt nie prosił. Szkicowana ścieżka pochodzi od pluginu importera, a nie od użytkownika, i dlatego jest sprawdzana z tego samego powodu co przesłana ścieżka.

Każdy import, który cokolwiek szkicuje, zapisuje też .aggrega-import.json obok swoich szkiców: rekord tego, co zapisał — target, który mu przesłano, jeśli go przesłano, migawkę katalogu, którą odczytał, jeśli ją odczytał, oraz każdy szkicowany plik i, w szkicowanej encji Aggregate lub Release, każdy klucz na każdej głębokości, ze skrótem zapisanego tam tekstu; każdy inny szkicowany plik jest rejestrowany w całości. Tekst klucza to jego wiersz, wiersze jego wartości, jeśli wartość nie jest mapowaniem kluczy, oraz wiersze komentarza zapisane bezpośrednio nad nim z tym samym wcięciem. written wskazuje rekord razem ze szkicami, a w trybie dry_run jest on wśród zwracanych szkiców. Rekord jest w formacie JSON, więc nic, co czyta dokumenty YAML przestrzeni roboczej, go nie czyta.

Wywołanie nigdy nie nadpisuje encji Aggregate, która już jest w katalogu wyjściowym. Aggregate to dokument, który autor dalej edytuje po utworzeniu szkicu, więc wywołanie, którego jeden ze szkiców trafiłby na plik odczytywany jako Aggregate, zostaje odrzucone ze wskazaniem szkicu i katalogu, a nic nie zostaje zapisane — także w trybie dry_run, ponieważ przebieg próbny odrzuca to, co odrzuca zapis. Każdy inny plik znajdujący się już pod szkicowaną ścieżką jest nadpisywany, a plik szkicowany przez wcześniejszy import, którego ten import nie szkicuje, pozostaje na miejscu.

Wysłanie sync zamiast tego aktualizuje to, co wcześniejszy import przygotował, zgodnie ze źródłem, zmieniając wyłącznie to, co zapisał import. Synchronizacja bez target przygotowuje szkice dla celu zapisanego w rekordzie, więc przygotowuje ten Manifest, który przygotował wcześniejszy import; synchronizacja z target przygotowuje szkice dla niego, a rekord od tej chwili go wskazuje. Zapisany cel, z którym nie wiąże się żadna encja Recipe w katalogu, jest odrzucany tak jak wysłany, a odmowa informuje, że chodzi o cel zapisany. Każda część jest oceniana na trzy sposoby: co według rekordu import ostatnio w niej zapisał, co jest na dysku i co źródło przygotowuje teraz. Część, którą źródło pozostawiło tak, jak import ją ostatnio zapisał, pozostaje dokładnie taka, jaka jest na dysku, niezależnie od tego, czy autor ją edytował. Część zmieniona przez źródło jest zapisywana od nowa, część usunięta ze źródła jest usuwana — przygotowany plik jest kasowany w całości — a część dodana w źródle jest dopisywana obok części, które szkic wymienia wokół niej, każda tylko tam, gdzie zawartość dysku jest tym, co import ostatnio zapisał, i nie zawiera niczego dodanego przez autora. Wszystko inne pozostaje bajt w bajt: klucz dodany przez autora w dowolnym miejscu — parametr, encja Feature, także pod przygotowaną instancją Component, inna encja Component, środowisko, które przygotowana encja Release pozostawia autorowi — komentarz niezapisany bezpośrednio nad przygotowanym kluczem oraz każdy plik, którego rekord nie wymienia. Pole drift odpowiedzi wymienia każdą zaktualizowaną część — lub, przy dry_run, każdą, która zostałaby zaktualizowana — w kolejności, w jakiej wymienia je szkic, każdą jako change (added, removed lub changed), file, czyli przygotowany plik, w którym się znajduje, oraz key, czyli prowadzące do niej klucze w przygotowanej encji Aggregate lub Release w postaci listy, pustej, gdy częścią jest cały plik; odpowiedź tekstowa wymienia każdą w osobnym wierszu słowami, które aggrega import wypisuje na standardowe wyjście błędów: <change> <key> in <file> lub <change> <file>. Puste drift przy dry_run oznacza, że szkice są zgodne ze źródłem. Przy dry_run zwracane szkice to pliki, które synchronizacja by zapisała, z treścią, jaką by im nadała. Synchronizacja, która zmieniłaby lub usunęła część edytowaną przez autora, dodała część tam, gdzie autor już ją zapisał, lub usunęła część zawierającą coś dodanego przez autora, jest odrzucana, z podaniem każdej takiej części i przyczyny, i nic nie jest zapisywane; komentarz zapisany bezpośrednio nad przygotowanym kluczem jest edycją tego klucza. Synchronizacja nad encją Aggregate, której nie wymienia żaden rekord, jest odrzucana z odpowiednią informacją, podobnie jak synchronizacja, której rekordu nie można odczytać, a synchronizacja, której importer nie mógł dokończyć, niczego nie zapisuje. Synchronizacja do katalogu, w którym nie ma rekordu ani niczego pod przygotowanymi ścieżkami, zapisuje cały szkic. Dla wywołania niebędącego synchronizacją drift jest pustą listą.

Odpowiedź zawiera: source w postaci, w jakiej je podano; format, czyli sposób odczytania źródła; workspace_root, katalog główny przestrzeni roboczej ustalonej przez wywołanie; output_dir, katalog, względem którego podane są przygotowane ścieżki; written, pliki, które trafiły na dysk; drift, czyli to, co zaktualizowała synchronizacja; diagnostics, po jednym wpisie na każdą konstrukcję, której importer nie mógł przetłumaczyć; decisions, czyli sposób, w jaki importer odwzorował każdy węzeł źródła; oraz halted. output_dir to wysłany katalog lub, jeśli go nie wysłano, wspomniany katalog główny, odczytany z tego, czego import faktycznie użył; jest zgłaszany także przy dry_run, gdy nic nie jest zapisywane, ale każda przygotowana ścieżka nadal jest względna wobec niego. Przez HTTP workspace_root jest wstrzymywany i oznaczany workspace_root_withheld, ponieważ katalog główny jest miejscem na hoście serwera, jak opisano w sekcji Co odpowiedź mówi o systemie plików serwera; output_dir jest wstrzymywany i oznaczany output_dir_withheld, gdy jest tym katalogiem głównym, a w przeciwnym razie podawany pod nazwą względną wobec katalogu głównego — w postaci, jaką mają wysyłane ścieżki — więc informacja o miejscu szkiców nadal jest w odpowiedzi. Import, którego importer nie mógł dokończyć, nadal przygotowuje to, co mógł, i wraca oznaczony jako niepowodzenie z całą tą odpowiedzią — halted ma wartość true, pliki, które trafiły na dysk, są wymienione w written, a diagnostyka obok nich wskazuje, czego brakuje. To częściowy wynik, który można zachować lub odrzucić, a nie wywołanie, które nic nie zrobiło.

decisions pokazuje, gdzie import zgadywał. Zawiera po jednym wpisie na każdy odwzorowany przez importer węzeł źródła, w kolejności importera: source_node, czyli id, type i params_summary węzła; candidates, każdą encję Component z katalogu, którą importer rozważał dla węzła, jako component, score, tier i signals — wkład każdego z jej sygnałów, pod table, category, domain_labels, shape i name; chosen, czyli wybrany target, mode, w jakim go zapisał — reference do istniejącej encji Component lub draft — oraz tier wyboru; rationale, czyli uzasadnienie; oraz swap_hint, czyli sposób dokonania innego wyboru. candidates nie występuje, gdy importer nie rozważał żadnego kandydata, chosen — gdy nie dokonał wyboru, a rationale i swap_hint — gdy ich nie zapisał. Każda wartość pochodzi od importera — sposób oceniania kandydata i progi poziomów to jego wybory — dlatego wpis należy czytać jako jego relację z odwzorowania. decisions występuje w odpowiedzi zarówno przy dry_run, jak i gdy import się zatrzymał, a dla importera, który nie zgłasza decyzji, jest pustą listą. Odpowiedź tekstowa wymienia każdą decyzję w osobnym wierszu po diagnostyce, słowami, które aggrega import wypisuje na standardowe wyjście błędów: mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, gdzie wynik jest wynikiem najlepszego kandydata.

dry_run robi wszystko oprócz zapisu. Każdy przygotowany plik wraca w drafts ze ścieżką względną wobec output_dir i treścią, a nic nie jest tworzone — z myślą o kliencie, który pokazuje wynik przed jego zapisaniem. Całe pozostałe zachowanie jest takie jak przy zapisie: ten sam importer nad tym samym źródłem zgłasza tę samą diagnostykę, więc źródło, które zapis by odrzucił, jest odrzucane także w tym trybie. Bez niego pliki trafiają na dysk i wymienia je written, a drafts nie występuje, zamiast powtarzać bajty, których zapisu zażądano.

Szkice są punktem wyjścia, który należy do autora i który dalej się edytuje. Nie rozstrzyga się tu, czy ich treść jest dopuszczalna — czy gniazdo jest zadeklarowane przez producenta lub czy warunki stosowalności encji Feature są spełnione. Na to odpowiada validate.

Przez standardowe wejście i wyjście ta sama funkcja jest dostępna także jako cli-import, które uruchamia polecenie i zwraca wypisany przez nie tekst; przez HTTP to narzędzie nie istnieje i funkcja jest tam dostępna przez to narzędzie.

Publikowanie, podpisywanie i wycofywanie

Cztery narzędzia umieszczają coś tam, skąd będą to rozwiązywać inne osoby. publish-entity pakuje encję katalogu i ją publikuje; publish-artifact publikuje samodzielny plik, taki jak pakiet dokumentacji, traktując jego bajty jako nieprzezroczyste i nie parsując żadnej koperty encji; sign-artifacts podpisuje już opublikowane referencje i dołącza każdy podpis, pozostawiając bez zmian referencję, która ma już podpis weryfikowany przez politykę zaufania jej rejestru; deprecate-artifact dołącza do referencji podpisany znacznik wycofania. Przed dopuszczeniem któregokolwiek z nich należy przeczytać Co asystent może zrobić bez pytania o zgodę: są to narzędzia, których skutki wychodzą poza maszynę.

publish-entity przyjmuje entity, dokument do opublikowania, a encja Plugin wymaga też plugin, pliku wykonywalnego publikowanego wewnątrz jej manifestu. publish-artifact przyjmuje file wraz z name i tag, pod którymi plik jest publikowany. Każdy argument ścieżki jest tu bezwzględny lub względny wobec katalogu głównego obszaru roboczego — to ten sam kontrakt, którego używa każde inne narzędzie tej powierzchni — a workspace_root wskazuje obszar roboczy, o który chodzi w wywołaniu — na serwerze osiąganym przez standardowe wejście i wyjście. Serwer osiągany przez HTTPS odrzuca workspace_root i wymaga, aby każda z tych ścieżek rozwiązywała się wewnątrz obsługiwanego przez niego obszaru roboczego, jak opisuje Jeden proces, jeden obszar roboczy. registry to miejsce docelowe; domyślnie jest to rejestr skonfigurowany w obszarze roboczym. Niewysłanie żadnego, gdy nie skonfigurowano wartości domyślnej, jest odrzucane ze wskazaniem, co należy wysłać. sign-artifacts przyjmuje references, jeden lub więcej adresów w rejestrze, a nie ścieżek, oraz opcjonalnie jobs, czyli liczbę referencji podpisywanych jednocześnie: gdy go pominąć, są podpisywane jedna po drugiej, a wartość mniejsza niż 1 jest odrzucana ze wskazaniem, co należy wysłać. Każda referencja jest nadal podpisywana dokładnie tak, jak byłaby podpisana osobno, jak opisuje aggrega sign. deprecate-artifact przyjmuje albo reference wraz z severity i reason, albo from wskazujące plik wsadowy — i odrzuca argumenty treści wysłane razem z plikiem wsadowym, zamiast je pomijać, ponieważ plik wsadowy dostarcza własnych, a po cichu zignorowany argument wygląda na uwzględniony.

Oba narzędzia publikujące przyjmują dry_run, które pokazuje, co publikacja by wysłała, bez kontaktowania się z żadnym rejestrem. Oblicza pakiet, raportuje, co zostałoby opublikowane, i odpowiada z beyond_this_machine równym false oraz miejscem docelowym, do którego by się zwróciło, w registries; publish-entity odpowiada też wartością digest, pod którą trafiłaby ta publikacja — tą samą, którą wypisuje aggrega push --dry-run. W ten sposób można pokazać komuś proponowaną publikację, zanim nią się stanie. Podpisywanie i wycofywanie nie mają takiej formy: obie operacje działają na czymś już opublikowanym, więc nie ma czego podglądać.

publish-entity odpowiada z windows_unusable_entries, gdy publikowane archiwum zawiera wpisy, których Windows nie może przechować w zapisanej postaci — ścieżkę z członem nazwanym jak urządzenie, np. CON, AUX lub NUL, w dowolnej wielkości liter i z dowolnym rozszerzeniem, albo członem kończącym się kropką lub spacją — wymieniając każdy z nich, najpierw nazwę pliku samego dokumentu encji, potem pliki, które encja zawiera. Pole jest nieobecne, gdy takich wpisów nie ma, co obejmuje encję publikowaną jako sam dokument. aggrega uruchomiona w systemie Windows odmawia rozpakowania takiego wpisu, więc obszar roboczy w Windows nie może użyć tej wersji; są to wpisy, przed którymi ostrzega aggrega push, a tekst odpowiedzi również je wymienia. Niczego nie odrzucają: wywołanie przebiega lub jest odrzucane dokładnie tak, jak bez nich, łącznie z dry_run.

publish-entity przyjmuje pin_sources, które przed spakowaniem uruchamia na encji krok przypinania autora encji, dzięki czemu entity.lock zapisany przez ten krok obok niej staje się częścią publikacji. Jest to ten sam krok, który uruchamia narzędzie pin, zapisujący te same bajty, i działa przed każdym odrzuceniem oceniającym encję — więc publikacja tam odrzucona, np. z powodu brakującego podpisu, i tak pozostawia zapisaną blokadę obok encji. Odrzucenie dotyczące samego wywołania, np. obszar roboczy offline lub brak miejsca docelowego, następuje wcześniej i niczego nie przypina. Gdy argument zostanie pominięty, decyduje pin_sources_at_push obszaru roboczego; gdy zostanie wysłany, decyduje w obu kierunkach. Publikacja, która przypina, zapisuje zarówno w obszarze roboczym, jak i w rejestrze, więc przez HTTP wymaga poświadczenia z oboma zakresami, a poświadczenie mające tylko zakres dopuszczający publikowanie jest odrzucane ze wskazaniem brakującego. Wynik zawiera pin w kształcie odpowiedzi narzędzia pin, gdy krok został uruchomiony; w trybie dry_run krok raportuje blokadę, którą by zapisał, i niczego nie zapisuje. Gdy krok nie jest uruchamiany, encja Recipe lub FeatureRecipe, której entity.lock nie zapisuje przypięcia dla odczytywanego wejścia, jest odrzucana — podobnie jak taka, której wejście przestało pasować — zanim cokolwiek zostanie spakowane, łącznie z dry_run, ze wskazaniem aggrega pin, pin_sources i pin_sources_at_push. Jest to to samo odrzucenie, które zgłasza pull dla tej samej blokady, a jego sprawdzenie pobiera w całości każde zdalne źródło zapisywane przez encję, tak jak zrobiłby to krok.

Podpisywanie to miejsce, w którym zużywane jest poświadczenie, a robią to trzy z czterech narzędzi — publikacja artefaktu danych niczego nie podpisuje i jest podpisywana później przez referencję. identity_token dostarcza tożsamość bezkluczową dla wywołania. Na serwerze osiąganym przez standardowe wejście i wyjście pominięcie go powoduje użycie tożsamości ze środowiska tego serwera, a key_path wybiera zamiast tego klucz przechowywany offline. Przez nasłuch żadne z nich nie jest osiągalne: środowisko nie jest odczytywane, key_path jest odrzucany i ukrywany w tym, co ogłaszają te trzy narzędzia, a klucz wskazany w konfiguracji obsługiwanego obszaru roboczego nie jest używany — podpisuje więc tylko token wysłany w wywołaniu, jak opisuje Które poświadczenia zużywa wywołanie. Jedno wywołanie podpisuje jednym poświadczeniem. Każda referencja wysłana do sign-artifacts i każdy wpis pliku wsadowego odczytywanego przez deprecate-artifact są podpisywane tym samym przechowywanym kluczem lub tą samą tożsamością bezkluczową; gdy konfiguracja obsługiwanego obszaru roboczego wskazuje klucz dla rejestru jednej referencji, a dla innej żadnego, albo dwa różne klucze, wywołanie niczego nie podpisuje i jest odrzucane ze wskazaniem rejestrów po każdej stronie, zanim zostanie rozwiązana jakakolwiek tożsamość lub odczytany jakikolwiek rejestr — należy wysłać jedno wywołanie na poświadczenie albo, na standardowym wejściu i wyjściu, jeden key_path dla wszystkich. Przez nasłuch żaden skonfigurowany klucz nie jest używany, więc każda referencja jest tam podpisywana tożsamością wysłaną w wywołaniu i wywołanie nigdy nie jest z tego powodu odrzucane. Odrzucenie opisano w References signed together need different signing credentials (Referencje podpisywane razem wymagają różnych poświadczeń podpisu). fulcio_url, rekor_url i timestamp_url nadpisują punkty końcowe trybu bezkluczowego skonfigurowane w obszarze roboczym, w obu transportach. Gdy nie rozwiązuje się żadna tożsamość, wywołanie jest odrzucane ze wskazaniem, co należy wysłać — nic tutaj nie otwiera przeglądarki ani nie czeka na człowieka, ponieważ nikt nie obserwuje strumienia protokołu, a zawieszone wywołanie byłoby właśnie tą cichą awarią, której odrzucenie ma zapobiegać. W publish-entity to, czy podpis w ogóle zostanie dołączony, wynika z polityki rejestru docelowego, chyba że sign stanowi inaczej, a rejestr wymagający podpisów odrzuca niepodpisaną publikację niezależnie od wysłanych argumentów: nie ma argumentu omijającego to odrzucenie. Opis obu trybów podpisywania i tego, z czym każdy się kontaktuje, zawiera aggrega sign.

Każdy wynik zawiera fakty, a nie zapis przebiegu: gdzie trafił artefakt, jego tag, opublikowany skrót — lub, w przypadku przebiegu próbnego dla encji katalogu, skrót, pod którym trafiłaby publikacja — czy tag wskazywał już na treść identyczną bajt po bajcie, czy publikacja została podpisana, oraz jej reach. Partia podpisywania zgłasza każdą podpisaną referencję wraz ze skrótem, do którego zobowiązuje się jej podpis, w kolejności, w jakiej podano referencje, a partia, w której nie powiodła się którakolwiek referencja, wraca jako niepowodzenie wymieniające każdą z nich, a nie jako wynik ze skróconą listą — częściowa partia zgłoszona jako sukces to sposób, w jaki odmowa zostaje odczytana jako pozytywny wynik. Wycofanie zgłasza każdy znacznik z jego własnym skrótem, ponieważ znacznik jest dołączany jako nieotagowany referrer artefaktu, który wycofuje, i nic innego go nie adresuje. Podpisanie lub wycofanie referencji, pod którą nic nie opublikowano, jest odrzucane, zamiast zostać dołączone do niczego.

Dwie części odpowiedzi

Każde narzędzie odpowiada czytelnym tekstem, a obok niego wynikiem ustrukturyzowanym wszędzie tam, gdzie operacja go ma. Tekst jest przeznaczony dla osoby czytającej rozmowę. Wynik ustrukturyzowany zawiera tę samą odpowiedź w postaci pól odczytywanych przez program — werdyktu, listy plików, diagnostyki — a odmowa również go zawiera, jeśli operacja miała w chwili odmowy jakieś ustalenia, co dla kompilacji opisuje sekcja Co zwraca odrzucona kompilacja.

Wynik ustrukturyzowany zawiera również tekst, jako text_answer. Wynik ustrukturyzowany każdego narzędzia ma pole text_answer zawierające tekst odpowiedzi dokładnie w takiej postaci, w jakiej niesie go tekst: każde zdanie, w tej samej kolejności, bez zmian. Dzięki temu klient, który przekazuje swojemu modelowi wynik ustrukturyzowany zamiast tekstu, jak robi to Claude Desktop, nadal przekazuje mu każde zdanie zawarte w tekście — wiersz, od którego zaczyna się odpowiedź describe-capabilities wywołanego bez argumentów, obowiązującą konfigurację zgłaszaną przez config-show, zdanie wskazujące folder użyty przez odpowiedź, gdy nie znaleziono żadnego obszaru roboczego. text_answer jest zapisywane jako pierwsze, przed polami, którymi odpowiada narzędzie, i jest to tekst, który otrzymuje wywołujący: przez HTTP wskazuje ono każde miejsce na hoście serwera tak samo jak tekst, co opisuje sekcja Co odpowiedź mówi o systemie plików serwera. Sam tekst pozostaje prozą, którą jest, dla klientów, którzy go czytają, więc te same słowa występują w każdej odpowiedzi dwukrotnie.

Żadne narzędzie nie jest wyjątkiem, w tym lint. Żadne narzędzie nie odpowiada własnym polem o nazwie text_answer, więc to pole nigdy żadnego nie zastępuje. Wynik ustrukturyzowany lint zachowuje swoje pole summary — liczbę sprawdzonych encji i ustaleń, łącznie i według ważności, pod nazwami, które aggrega lint zapisuje z -o json — i zawiera obok niego text_answer. describe-capabilities również zachowuje własne pola: version_summary, czyli sam wiersz wersji, gdy nie przekazano mu argumentów, oraz w każdym wpisie swojego index pole summary, czyli jednowierszowy opis przeznaczenia danego narzędzia.

Żadne narzędzie nie ogłasza schematu wyjścia. Opis narzędzia zawiera schemat przyjmowanych argumentów, a nie zawiera schematu wyniku, dlatego text_answer jest wymienione tutaj, a nie w schemacie.

Odpowiedź bez wyniku ustrukturyzowanego to sam jej tekst. Odrzucenie argumentów wywołania oraz każdy inny błąd, dla którego operacja nie miała nic ustrukturyzowanego do zgłoszenia, wraca jako sam tekst, a tekst jest wtedy jedyną częścią, którą klient może pokazać swojemu modelowi.

Gdy wywołanie nie kończy się powodzeniem

To, gdzie trafia odpowiedź, zależy od jednego: czy wywołujący może naprawić problem, zmieniając argumenty istniejącego narzędzia.

Wszystko, co można naprawić w ten sposób, wraca jako własny wynik narzędzia, oznaczony jako niepowodzenie i zawierający poprawkę jako tekst — kombinacja selektorów, której narzędzie nie akceptuje, pominięty wymagany argument, argument wysłany jako niewłaściwy typ JSON, ścieżka, której nie da się rozwiązać, diagnostyka kompilatora. To ten kanał jest pokazywany asystentowi, więc odczytuje on, co poszło nie tak, i wywołuje narzędzie ponownie z poprawionym argumentem.

Kanał błędów protokołu jest zarezerwowany dla tego, co nie ma wyniku narzędzia, w którym mogłoby się znaleźć: nazwy narzędzia, którego serwer nie obsługuje, żądania, którego parametrów serwer nie potrafi odczytać, metody, której nie implementuje, oraz wiadomości, która w ogóle nie jest poprawnym JSON. Odczyt zasobu i renderowanie promptu również zwracają tam odpowiedź, ponieważ żaden z tych wyników nie ma własnej flagi niepowodzenia.

Ogłaszany schemat narzędzia deklaruje też większość reguł, które muszą spełniać jego argumenty — które selektory wzajemnie się wykluczają, który argument ma znaczenie tylko razem z innym i które są wymagane — więc klient komponujący wywołania zgodnie z zadeklarowanym schematem rzadko musi wykonać wywołanie, aby je poznać. Reguła, której schemat nie określa, nadal powoduje odmowę, ze zdaniem, które ją nazywa; reguła pull, zgodnie z którą verify nie łączy się z upgrade_targets ani pin_sources, jest celowo pozostawiona odmowie, z powodu podanego w sekcji Rozwiązywanie zależności encji Release.

Co zatrzymuje serwer

Przy standardowym wejściu i wyjściu zatrzymuje go zamknięcie połączenia. Serwer odczytuje jeden komunikat na wiersz i kończy działanie w sposób uporządkowany, gdy jego standardowe wejście osiągnie koniec strumienia, więc klient, który zamyka połączenie, wyłącza serwer. Na tym transporcie jest to zwykły przypadek, ponieważ polecenia nigdy nie uruchamia się samodzielnie: kończy je klient, który je uruchomił, więc zatrzymanie serwera zwykle polega na zamknięciu edytora lub wyłączeniu tego serwera dla projektu.

Prośba skierowana do samego procesu o zatrzymanie dociera do serwera na obu transportach. Przerwanie z terminala albo żądanie zakończenia od nadzorcy lub środowiska uruchomieniowego kontenerów wyłącza go przy pierwszym żądaniu, niezależnie od tego, czy klient coś wysyła: serwer przestaje przyjmować komunikaty, kończy pracę wykonywaną przez trwające wywołanie i kończy działanie w sposób uporządkowany. Drugie żądanie natychmiast kończy proces. Dlatego przy standardowym wejściu i wyjściu wywołanie, które wciąż trwa w chwili, gdy proces zostaje poproszony o zatrzymanie, nie zostaje ukończone; nasłuchujący serwer natomiast opróżnia kolejkę, pozwalając wywołaniu, na które już udziela odpowiedzi, zakończyć się w ograniczonym limicie czasu, zanim proces zakończy działanie.

Klient może też zatrzymać jedno wywołanie bez zatrzymywania serwera, a sposób, w jaki to robi, zależy od transportu. Wywołania są obsługiwane współbieżnie, więc zakończenie jednego z nich jest realizowane jeszcze w trakcie jego trwania, a nie czeka w kolejce za nim. Przy standardowym wejściu i wyjściu klient podaje identyfikator wywołania; anulowanie wywołania, na które już udzielono odpowiedzi, lub takiego, nad którym serwer nie pracuje, nie ma żadnego skutku — dzięki temu taki komunikat można bezpiecznie wysłać, nie wiedząc wcześniej, czy odpowiedź jest już w drodze. Przez HTTP nie wysyła się żadnego komunikatu: wywołanie kończy zamknięcie połączenia, które je przeniosło. W obu przypadkach wywołanie otrzymuje polecenie zatrzymania — jego praca kończy się w najbliższym punkcie, w którym operacja to sprawdza, a operacja, która nigdy tego nie sprawdza, działa do końca — dla tego wywołania nic więcej nie jest wysyłane, wszystkie pozostałe trwające wywołania są kontynuowane, a serwer nadal działa.

Kiedy używać

Polecenia aggrega mcp należy używać, gdy asystent AI ma pomagać w tworzeniu encji Aggrega na podstawie rzeczywistych schematów i dokumentacji referencyjnej — tak aby jego sugestie opierały się na dokładnej strukturze akceptowanej przez kompilator, a nie na domysłach. Wpisuje się to bezpośrednio w pętlę tworzenia: asystent odczytuje schemat i dokumentację referencyjną danego rodzaju, generuje szkielet, wypełnia pola należące do danej roli i przeprowadza walidację, zanim zwróci szkic. Opis tej pętli zawiera strona Tworzenie plików Aggrega.

Przy standardowym wejściu i wyjściu zazwyczaj nigdy nie wpisuje się aggrega mcp samodzielnie. Zamiast tego wskazuje się je raz w konfiguracji MCP klienta, a klient sam je uruchamia i zatrzymuje. Inaczej jest w przypadku nasłuchiwania: wtedy proces uruchamia się samodzielnie i działa on dalej dla wywołujących, którzy go nie uruchomili.

Przykład: konfiguracja klienta przez standardowe wejście i wyjście

Klienta MCP należy skierować na to polecenie za pomocą wpisu serwera stdio:

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

Jedynym wymaganiem wstępnym jest zainstalowany plik binarny aggrega dostępny w PATH klienta. Ścieżki konfiguracji poszczególnych klientów i rozwiązywanie problemów opisano na stronie Podłączanie serwera MCP. Aby pobrać schemat bezpośrednio z wiersza poleceń, bez klienta, należy użyć aggrega get-schema.