aggrega mcp
Einen Model-Context-Protocol-Server über Standardein- und -ausgabe oder über HTTP ausführen, für die Integration von KI-Assistenten
Übersicht
aggrega mcp [flags]Beschreibung
Run Aggrega as a Model Context Protocol (MCP) server, so an AIassistant can discover and drive Aggrega operations through a structuredprotocol instead of scraping command output.
Two transports reach the same server, and --transport chooses betweenthem, with mcp.transport in the workspace configuration as the key itoverrides. The default, stdio, speaks newline-delimited JSON-RPC 2.0 overthe process's standard input and output, which is how an MCP-capableclient runs it: spawned as a subprocess, not typed by hand. http servesthe protocol over HTTP instead — one long-running process on a host,reached by callers who are not at its keyboard — on the address --listennames, or mcp.listen when the flag is absent.
An address chooses no transport. --listen given with the stdio transportis 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 inputand output, which says so in one line on stderr, so a client can launchthis command in a directory whose configuration is written for alistener. And the http transport with no address from either is refusedbefore anything binds.
It speaks two MCP protocol revisions on both transports, 2026-07-28 and2025-06-18, so a client of either connects. In 2026-07-28 nothing issettled for the connection as a whole: every request states the protocolversion it speaks and the capabilities its sender offers, and the serverreads both from the request it is answering rather than holding anythingbetween 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 samethings about it either way. A client on 2026-07-28 calls server/discoverfor the revisions the server speaks, the capabilities it advertises —tools, resources, and prompts — and the guidance it offers a modelbefore the first call. A client on 2025-06-18 receives those samecapabilities, and that same guidance, in the reply to its handshake.
From there the client discovers the server's surface through the listmethods (tools, resources, resource templates, and prompts) and invokesit through tools/call and resources/read. The server exposes Aggregaoperations — compiling and inspecting a Release, reading catalogentities — as tools and resources an assistant can call directly.
On standard input and output, stream discipline is strict: stdout carriesonly protocol messages, one JSON object per line, so the client can parsethe stream without heuristics. Every log, warning, and diagnostic iswritten to stderr instead. The server reads one message per line andexits cleanly when stdin reaches end of stream, so a client that closesthe connection shuts the server down. A client ends one call by namingits id, and every other call carries on.
Over HTTP there is one endpoint, /mcp, accepting POST. Every message isits own request and no session of any kind is kept, so nothing a clientsends first decides how a later request is answered. Closing theconnection ends the call it carried. A request carrying an Origin headeris checked against mcp.allowed_origins, and mcp.limits bounds how largeone request body may be, how many requests are answered at once, and howmany one caller may send in a minute. A caller sending faster thanmcp.limits.requests_per_minute is answered 429, counted against thatcaller alone.
Every request to /mcp carries a credential, and which one depends onwhether a proxy in front has already checked it. By default it is abearer token the server verifies itself, against the keysmcp.authorization.issuer publishes: it must come from that issuer, namemcp.authorization.resource among its audiences, be inside its validitywindow, and be signed with an asymmetric algorithm. A request carrying notoken is answered 401 with a challenge, and so is one whose token failsany of those. A token is never accepted from the address, never forwardedanywhere, never exchanged, and never written to any log; the subject itnames is recorded and compared to nothing.
Set mcp.authorization.trusted_proxy instead and the caller is read from aheader the proxy sets rather than from a token, with its scopes from asecond header; no token is read at all in that mode, and a requestwithout the principal header is answered 401. Because that header is thenthe whole credential, it is trustworthy only where nothing else can setit: the process is refused before it binds unless mcp.listen is loopbackor a Unix socket.
The challenge names where to obtain a token. A listener publishes anOAuth protected-resource metadata document, with no credential asked for,naming the authorization server, this deployment's own address and thescopes that exist; it is served at /.well-known/oauth-protected-resourceand at that path followed by the endpoint path, which are the two placesa client looks. A client reads it before it can hold a token, which iswhy it is the one answer given without one. What that document publishescomes from mcp.authorization.issuer and mcp.authorization.resource, and alistener is refused before it binds unless both are set.
The issuer is an https address unless the authorization server runs onthis machine (localhost, 127.0.0.1 or ::1), and that holds in everymode: with the keys read from the issuer, with a key file, and with aproxy 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'sauthorization code and token across the network unprotected, and alistener naming one is refused before it binds.
The verification keys are read from the issuer itself, by asking it whereit publishes them and fetching them from the address it names, and readagain once when a token arrives signed by a key identifier the held setdoes not carry. That address is held to the same rule as the issuer, andso is every redirect either read is answered with: a plain http addresson another host is never asked, and a token needing those keys isanswered 503 until the authorization server publishes its metadata andkeys over https. A workspace that is offline makes no such request, sothere mcp.authorization.jwks_file names a file holding those keys and alistener 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 isrunning 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. Theaddress opens before the workspace is resolved, so a supervisor sees theprocess alive while it is still deciding whether it can serve at all.Leave the key unset and no second listener exists. The endpoint itselfanswers both paths the same not-found it gives every path it does notserve, with a token and without one, so reaching this process over thenetwork is never a way to probe it.
The workspace this process serves is fixed when it starts, on eithertransport: --workspace-root names it, and AGGREGA_WORKSPACE_ROOT suppliesit when the flag is absent. The folder named is the workspace rootitself, as it is for every command: a call naming no workspace of itsown is answered there, and nothing above it is searched for a workspace,so name the folder that holds the workspace's .aggrega-config.yaml. Anamed folder that does not exist is refused, naming the flag or thevariable that supplied it and the value as it was given: a listener isrefused before it binds, while a server on standard input and outputwrites the refusal to stderr and starts all the same, answering everycall that acts in that workspace with it, so a client that showsnothing of stderr still shows the refusal. An emptyAGGREGA_WORKSPACE_ROOT is read as unset, but for one launch: a serveron standard input and output given no --workspace-root, whoseenvironment carries the AGGREGA_BUNDLE_VERSION the desktop bundle sets,was started with the desktop application's Workspace folder settingempty. It is served the same way, the refusal naming that setting, sono call naming no workspace of its own is answered in the directory itwas started in. In every other case where neither names a root, aserver on standard input and output resolves the workspace from thedirectory it was started in, while a listener is refused before itbinds unless a workspace resolves there: one reachedover HTTP serves a workspace an operator chose rather thanwhichever directory it happened to be started in. Where that directoryanchors no workspace, a call naming no workspace of its own that namesits Release or document by an absolute path is answered in the workspacethat file's folder resolves, as the same command typed at a terminal inthat directory would be.
For the same reason a call arriving over HTTP cannot name a workspace ofits own. Sending workspace_root or catalog_dirs is refused, naming theargument, and the directories searched for catalog entities beside theserved workspace are the ones that workspace itself resolves: its ownworkspace.catalog_dirs setting — or, for a Release it gives directoriesof its own under workspace.releases, that Release's — then its catalogdirectory. Overstandard input and output both arguments are honoured: the client thatlaunched 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 asgiven. A relative one is read from the root a call naming no workspaceof its own is answered in — the folder --workspace-root orAGGREGA_WORKSPACE_ROOT names, which the desktop application sets fromits Workspace folder, or, where neither names one, the workspace rootthe directory the server was started in resolves to — so a client thatcannot see where that folder sits on the machine still names a folderinside it, as quickstart-ai/1. Where there is no such root to read itfrom, a relative one is refused as a call naming none is refused, andan absolute one is answered as it always is.
Asking the process itself to stop — an interrupt from the terminal, or atermination request from a supervisor or container runtime — shuts theserver down on the first request, whether or not a client is sendinganything: it stops accepting messages, ends the work a call in progressis doing, and exits cleanly. A listener stops accepting and lets a callalready being answered finish, within a bounded budget, before theprocess exits. A second request ends the process at once.Flags
| Flag | Standard | Beschreibung |
|---|---|---|
--listen | — | Die Adresse, auf der der HTTP-Transport lauscht, in einer von zwei Formen: host:port oder unix: gefolgt von einem Dateisystempfad. Sie gibt an, wo gelauscht wird, und wählt keinen Transport: Sie wird mit —transport http oder mit mcp.transport: http in der Workspace-Konfiguration gelesen und zusammen mit dem stdio-Transport abgelehnt. Ein Listener ohne Zertifikat liefert Klartext aus und ist nur auf Loopback (127.0.0.1, ::1, localhost) oder auf einem Unix-Socket erlaubt, was die Form ist, die ein Server hinter einem terminierenden Proxy annimmt; jede andere Adresse benötigt mcp.tls.cert_file und mcp.tls.key_file, mit denen dieser Prozess TLS dann selbst terminiert. Wenn gesetzt, überschreibt sie den Konfigurationsschlüssel mcp.listen. |
--transport | — | Wie der Server erreicht wird: stdio spricht das Protokoll über Standardeingabe und -ausgabe, so erreicht ihn ein Client, der diesen Befehl als Unterprozess startet; http liefert es über HTTP auf der Adresse aus, die —listen oder mcp.listen nennt, und über HTTPS, wo mcp.tls ein Zertifikat und einen Schlüssel nennt. Wenn gesetzt, überschreibt es den Konfigurationsschlüssel mcp.transport, dessen Standardwert stdio ist. |
Funktionsweise
aggrega mcp führt einen Model-Context-Protocol-Server aus. Zwei Transporte erreichen ihn, und --transport wählt zwischen ihnen: stdio oder http, mit mcp.transport in der Workspace-Konfiguration als dem Schlüssel, den das Flag überschreibt, und stdio als Standard.
Über stdio, den Standard, kommuniziert er über die Standardeingabe und -ausgabe des Prozesses. In dieser Form ist er kein Befehl, den Sie interaktiv ausführen — ein MCP-fähiger Client startet ihn als Unterprozess und spricht das Protokoll über stdio; Den MCP-Server verbinden listet auf, wo jeder Client den Eintrag aufbewahrt, der ihn startet. Ihn auszuführen macht die CLI zu einem Aggrega-kundigen Authoring-Assistenten in Ihrem Editor oder Chat-Client.
Über http liefert er das Protokoll stattdessen über HTTP aus: ein einzelner, lang laufender Prozess auf einem Host, erreicht von Aufrufern, die nicht an seiner Tastatur sitzen, und lauschend auf der Adresse, die --listen nennt, oder mcp.listen, wenn das Flag fehlt. Unter Den Server über HTTPS erreichen erfahren Sie, wie dieser Listener konfiguriert wird und was er annimmt.
Er spricht zwei Revisionen des Protokolls, 2026-07-28 und 2025-06-18, sodass sich ein Client beider Revisionen verbinden kann und dieselben Oberflächen erreicht. Welche ein Aufruf spricht, wird bei diesem Aufruf angegeben, statt einmal für die Verbindung vereinbart zu werden. Ein Client auf 2026-07-28 sendet mit jeder Anfrage die Protokollversion, die er spricht, und seine eigenen Fähigkeiten und fragt server/discover, was der Server unterstützt; ein Client auf 2025-06-18 legt dieselben Dinge einmal fest, indem er die Verbindung mit einem initialize-Handshake eröffnet. So oder so hält der Server zwischen Nachrichten nichts fest, sodass das, was Sie zuerst senden, nichts darüber entscheidet, wie ein späterer Aufruf beantwortet wird. Eine Anfrage, die eine Revision nennt, die der Server nicht spricht, wird abgelehnt, und ihr wird mitgeteilt, welche zwei sie anfordern kann, statt so beantwortet zu werden, als hätte sie eine davon angefordert.
Der Server stellt dem verbundenen Assistenten drei Oberflächen bereit:
-
Prompts — zwei Familien, und der Unterschied liegt darin, was jede beantwortet. Authoring-Prompts beantworten „Was schreibe ich?“: eine Persona pro Rolle (Entwicklung, Architektur, Betrieb) sowie eine fokussierte Vorlage pro Entität. Jede rahmt die Rolle und verweist den Assistenten auf das richtige Schema, die richtige Referenzseite und den richtigen Authoring-Leitfaden, sodass seine Vorschläge innerhalb der Säulen bleiben, die diese Rolle verantwortet. Workflow-Prompts beantworten „Welche Aufrufe, in welcher Reihenfolge?“: Jeder legt die geordnete Abfolge von Tool-Aufrufen dar, die ein Ziel über mehrere Operationen hinweg erreicht, mit den Entscheidungspunkten dazwischen — ein neues Aggregate und sein Release von Grund auf zusammenstellen, ein vorhandenes Chart, Infrastrukturmodul oder eine Container-Compose-Datei in Aggrega überführen, herausfinden, warum ein Build nicht kompiliert oder die falschen Artefakte rendert.
prompts/listzählt beide Familien auf undprompts/getrendert einen davon, sodass die Menge vom Server gelesen wird statt von dieser Seite.Ein Workflow-Prompt nennt die Aufrufe, und Sie führen sie aus, einen nach dem anderen, und lesen jedes Ergebnis vor dem nächsten. Es gibt keinen Aufruf, der ein ganzes Ziel erledigt: Jedes Tool kapselt eine Operation, die Sie prüfen können, sodass die Abfolge das ist, was Sie ans Ziel bringt. Die Authoring-Personas nehmen optional einen
kindan, auf den sie sich konzentrieren, die Vorlage pro Entität verlangt einen, und einkind, dem kein Schema entspricht, wird mit der Liste der akzeptierten Werte abgelehnt, statt stillschweigend ignoriert zu werden. -
Ressourcen — schreibgeschütztes Referenzmaterial, inline ausgeliefert:
schema://<kind>für das JSON Schema einer Entität,langref://<path>für jede Seite der Sprachreferenz,authoring://<topic>für den Authoring-Leitfaden,catalog://<kind>/<name>für die verfasste YAML einer Katalogentität undcli://<command>für die eigene Hilfe eines Befehls, mitcli://allein als Einstiegspunkt — diese Hilfe wird aus den Befehlen beantwortet, die der Server selbst mitbringt, sodass das Lesen einer Hilfe keinen Prozess startet und denselben Text zurückgibt, den der Befehl für--helpausgibt. Eincatalog://-Lesezugriff auf eine Entität, die der Katalog nicht enthält, wird als nicht gefunden beantwortet; wo das daran liegt, dass genau eine Katalogdatei, die die Entität deklariert, beim Laden übersprungen wurde, nennt die Meldung der Antwort diese Datei, die Einschränkung, gegen die sie verstößt, und den Kurzcode der Bedingung statt nur der URI — die Ablehnung, mit deraggrega buildfür dieselbe Datei beginnt.resources/listzählt diejenigen auf, die ohne Parameter adressierbar sind, undresources/templates/listgibt die URI-Form jeder Familie bekannt. -
Tools — Aktionen auf Ihrem Workspace, und
tools/listantwortet mit allen.Die Tools, denen ein Assistent zuerst begegnet, sind auf die Authoring-Schleife zugeschnitten:
list-entitiesundlist-releases, um herauszufinden, was der Workspace enthält,scaffoldfür ein Gerüst mit den Feldern, die seine Art verlangt, und einem Platzhalter überall dort, wo ein Wert fällig ist — oder, mitexample, um eines der ausführbaren Beispiele der Dokumentation in ein neues Verzeichnis zu schreiben, mit dem Ort dieses Verzeichnisses, den geschriebenen Dateien und den Befehlen zum Bauen als Antwort, und mitlist: true, um die Beispiele aufzulisten —get-schemafür das JSON Schema einer Entität,validatezum Validieren eines Entwurfs (es nennt jeden Platzhalter, den der Entwurf noch trägt, und was jeder annimmt),describezum Beschreiben einer Katalogentität — oder einer per Referenz aus ihrer Registry gelesenen Entität —,pull, um die Abhängigkeiten eines Release in den lokalen Cache aufzulösen und seine Lockfile zu schreiben,build, um ein Release in seine gerenderten Artefakte zu bauen — standardmäßig im Speicher, ohne dass ein Artefakt auf die Festplatte geschrieben wird, oder nachdist/im Workspace-Stamm geschrieben, woaggrega buildsie schreibt, wenn Siewritesenden (und die Abhängigkeiten werden nur dann zuerst aufgelöst, wenn Sieauto_pullsenden) —,gen-catalog, um Plugin-Entitäten aus Wasm-Gästen zu erzeugen, undexplain-error, um eine Compiler-Diagnose zu umsetzbaren Hinweisen zu erweitern — einschließlich, wo die Diagnose mit dem Kurzcode einer Abbruchbedingung beginnt, dieser Bedingung und der veröffentlichten Schritt-für-Schritt-Anleitung zur Behebung im Authoring, derselben Erweiterung, dieaggrega explainfür denselben Code in einem Terminal liefert.Der Rest der Oberfläche steckt in derselben Antwort statt dahinter: weitere Tools, die innerhalb des Servers laufen —
lint, das Tool, das die an einer Stelle in einem Dokument geschriebene Verbindung nennt, die beiden Kandidatur-Tools, die Tools für Anhangscontainer und Einfügepunkt, das Tool, das eine begrenzte Bearbeitung auf ein Dokument anwendet,pin, das die Inhalts-Pins für die Eingaben einer Entität aufzeichnet, wie Die eigenen Eingaben einer Entität pinnen es darlegt, und die vier unten beschriebenen Veröffentlichungs-Tools, dazu Inventare der Caches und der konfigurierten Registries — und, für einen Client, der diesen Server über seine Standardeingabe und -ausgabe gestartet hat, ein Tool für jeden Befehl, den Sie sonst eingeben könnten, benannt nach seinem Aufrufpfad. Diese Befehls-Tools gibt es nur auf diesem Transport: Ein über HTTP erreichter Server bietet keines davon an, aus dem unter Den Server über HTTPS erreichen genannten Grund. Nichts wird für einen späteren Aufruf zurückgehalten. Wie viel einer Tool-Liste einem Modell vorgelegt wird, entscheidet der Client — er ruft die Definitionen ab und wählt, was er lädt —, und eine Definition, die ein Client nie erhalten hat, ist eine Operation, die ein Modell nie aufrufen kann, wie erreichbar der Name dieses Tools auf der Leitung auch sein mag. Wo die ganze Liste mehr ist, als Ihr Client aufnimmt, ist Eingrenzen, was der Server ankündigt der Weg, sie zu kürzen.describe-capabilitiesgrenzt diese Oberfläche auf die Entitätsart ein, die Sie verfassen. Mit einemkindantwortet es mit den Tools, die diese Art bedienen, ermittelt aus den Arten, die jedes Tool deklariert, statt aus den Wörtern einer Beschreibung; ohne Argumente antwortet es mit demselben Index über jedes Tool, das dieser Server Ihnen anbietet — jeweils Name, Zweck in einer Zeile, bediente Arten und ob es schreibt, ohne Argumentschemas, sodass die ganze Oberfläche in einer lesbaren Antwort ankommt. Bei einemcli--Tool hängt die Frage, ob es schreibt, davon ab, ob der Befehl schreibt, den es ausführt:cli-buildwird als schreibend gemeldet, weil der Befehl die gerenderten Artefakte unterhalb des Workspace-Stamms speichert, und ebensocli-scaffold, weil der Befehl mitexampleeines der ausführbaren Beispiele der Dokumentation in ein neues Verzeichnis schreibt, während ein Befehl, der nur liest, als nur lesend gemeldet wird, selbst wo er unterwegs einen Cache füllt, den alle Projekte auf dem Rechner teilen, so wie das Tool, das dieselbe Operation innerhalb des Servers ausführt; mittools, das ein oder mehrere Tools nennt, antwortet es mit genau deren vollständigen Definitionen und Argumentschemas. Diecli--Tools werden nie nach Art eingegrenzt, weil nichts festhält, welche Entitätsart ein Befehl bedient, sodass eine auf eine Art beschränkte Antwort sie auslässt und der argumentlose Index der Ort ist, an dem Sie sie lesen. Argumente eines Befehls-Tools sind nach den eigenen Flags des Befehls benannt, sodass--output-diralsoutput_dirgesendet wird, und ein unbekannter Name wird mit der Liste der akzeptierten Schreibweisen abgelehnt, statt stillschweigend verworfen zu werden.Manche Fähigkeiten sind auf Standardeingabe und -ausgabe doppelt vorhanden: Ein auf die Authoring-Schleife zugeschnittenes Tool führt die Operation innerhalb des Servers aus, und das Tool, das nach dem Befehl mit derselben Fähigkeit benannt ist, führt diesen Befehl aus. Die beiden verhalten sich nicht gleich, daher nennt auf diesem Transport jedes das andere und gibt den Unterschied an; über HTTP fehlen die Befehls-Tools, und der Satz zur Paarung wird weggelassen, statt auf ein Tool zu verweisen, das der Aufrufer nicht erreichen kann. Das innerhalb des Servers laufende ist dasjenige, zu dem man greifen sollte — es antwortet neben dem lesbaren Text mit einem maschinenlesbaren Ergebnis, sodass ein Assistent ein Urteil, eine Dateiliste oder eine Diagnose als Felder erhält statt als zu parsendes Protokoll. Das Befehls-Tool startet den echten Befehl in einem separaten Prozess, tut also alles, was dieser Befehl auf dem Rechner tut, auf dem er läuft, einschließlich des Schreibens auf die Festplatte, wo der Befehl schreibt —
cli-buildschreibt die gerenderten Artefakte nachdist/im Workspace-Stamm und die Dateien eines getracten Builds nach.trace/daneben, und die abschließende Zeile, die es zurückgibt, nennt dieses Verzeichnis vollständig —, und gibt nur die ausgeführte Befehlszeile und den Text zurück, den dieser Befehl ausgegeben hat. Greifen Sie dazu, wenn Sie ein Flag benötigen, das der Befehl deklariert und das andere Tool nicht annimmt.Diese Befehlszeile beginnt mit den globalen Flags, mit denen dieser Server gestartet wurde und die über die Konfiguration entscheiden —
--configund--offline, sofern Sie sie angegeben haben —, vor dem Befehl und den eigenen Flags des Aufrufs. So liest der Befehl die Konfiguration, die jedes andere Tool hier liest: Ein mit--offlinegestarteter Server führt seine Befehle offline aus, und einer, der mit--configgestartet wurde, führt sie über dieser globalen Datei aus. Ein Flag, das der Aufruf für sich selbst sendet, folgt danach und gewinnt, sodassoffline: falsebei einem Aufruf nur für diesen Aufruf das Netzwerk erreicht, und die zurückgegebene Befehlszeile zeigt beides. Wo der Server mit einem Workspace-Stamm gestartet wurde — durch--workspace-rootoder durchAGGREGA_WORKSPACE_ROOT—, beginnt die Befehlszeile mit diesem Stamm als--workspace-root, vor jenen beiden, sodass der Befehl dieses Verzeichnis als Workspace-Stamm nimmt, wie er es mit demselben Flag eingegeben täte und wie es jedes innerhalb des Servers laufende Tool nimmt, statt seinen Workspace vom Verzeichnis aus zu finden, in dem der Server gestartet wurde. Ein Aufruf, derworkspace_rootsendet, nennt seinen eigenen, und die Befehlszeile trägt nur diesen — einschließlich eines leeren Werts, den der Befehl so liest, wie--workspace-root ""in einem Terminal gelesen wird: den Workspace vom Verzeichnis aus finden, in dem der Server gestartet wurde. Ein Server, der mit keinem von beiden gestartet wurde, übergibt keinen Stamm, sodass seine Befehle ihren Workspace von diesem Verzeichnis aus finden, nach der Regel, die In welchem Workspace ein Aufruf beantwortet wird für jedes Tool festlegt — ausgenommen der Start des Desktop-Bundles mit leerer Einstellung Workspace folder, bei dem ein Aufruf, der keinen eigenen Workspace nennt, keinen Befehl startet und mit der Ablehnung dieser Einstellung beantwortet wird. Der Befehl startet im Workspace-Stamm, den der Aufruf oder der Start nennt: dem eigenenworkspace_rootdes Aufrufs, so gelesen, wie jedes Tool ihn liest — ein absoluter so, wie er gesendet wurde, ein relativer ausgehend von dem Stamm, in dem ein Aufruf ohne eigenen beantwortet wird — und in seiner absoluten Form an den Befehl übergeben, andernfalls dem Stamm, mit dem der Server gestartet wurde. Ein relativer Pfad, den ein Aufruf als zu lesende Datei übergibt — ein Dokument fürvalidate, ein--releaseoder ein--catalog—, wird also innerhalb dieses Workspaces gelesen, wie in einem dort geöffneten Terminal, und ein Build, den der Befehl ausführt, schreibtdist/unterhalb dieses Stamms. Wo nichts einen Stamm nennt — kein Startstamm und keinworkspace_rootoder ein leerer —, startet der Befehl in dem Verzeichnis, in dem der Server gestartet wurde, und liest einen relativen Pfad von dort aus; einworkspace_root, der keinen vorhandenen Ordner nennt, wird so weitergegeben, wie er gelesen wurde — ein absoluter so, wie er gesendet wurde, ein relativer in seiner vollständigen Form —, und der Befehl lehnt ihn mit eigenen Worten ab. Ein Befehl, den ein Befehlserweiterungs-Plugin registriert, erhält keines davon, weil er jedes Argument ungelesen an das Plugin weitergibt, statt ein globales Flag zu parsen, im Terminal wie hier; er startet im selben Ordner wie jeder andere Befehl.Einige Befehle fehlen bewusst selbst auf Standardeingabe und -ausgabe, wo es die Befehls-Tools überhaupt gibt — über HTTP fehlen sie alle, und das ist eine Eigenschaft des Transports, nicht eines Befehls. Auf Standardeingabe und -ausgabe ist jeder dieser Befehle aus einem angegebenen Grund ausgelassen: Der Daemon und dieser Server selbst würden nie ein Ergebnis zurückgeben; ein Befehl, der ein Passwort vom Terminal liest, hat nichts, wovon er es lesen könnte; einer, der ein Shell-Vervollständigungsskript schreibt, hat keine Shell, in die er es installieren könnte; das Entfernen eines gespeicherten Credentials wirkt auf den rechnerweiten Speicher statt auf einen Workspace, den Sie genannt haben; und das interaktive Beschaffen eines Identitätstokens hat keine nicht interaktive Form anzubieten. Aus demselben rechnerweiten Grund fehlt
aggrega plugin run-local, das einen.wasm-Gast aus einem von Ihnen angegebenen Pfad lädt: Wozu der Befehl da ist, ist das Lesen einer Datei, wo auch immer Sie sie abgelegt haben, sodass es keinen Workspace gibt, auf den er beschränkt werden könnte, und das Lesen geschieht im Prozess selbst, bevor der Gast existiert. Dem Gast wird nichts gewährt, wenn er läuft — keine Verzeichnisse, keine Sockets, keine Umgebung —, aber das ist eine Beschränkung des Moduls, nicht des Lesens, und entscheidet daher nicht darüber. Führen Sie ihn in Ihrem Terminal aus, wo Sie selbst den Pfad nennen. Signieren und Veröffentlichen sind ein ganz anderer Fall, und dieser Unterschied hält sie von dieser Liste fern. Jedes davon ermittelt eine Identität aus einer angegebenen oder umgebungsbedingten Eingabe und lehnt ausdrücklich ab, wenn keine verfügbar ist, sodass jedes eine Form hat, die ohne Zuschauer abgeschlossen wird — während das interaktive Beschaffen eines Tokens ein Verb ist, das keine Eingabe auch nur im Prinzip erfüllen kann. Daher sind sie doppelt vorhanden: als die Befehle und als die vier prozessinternen Tools, die unter Veröffentlichen, Signieren und Zurückziehen beschrieben sind. Wo die Befehlszeile einen Browser öffnen würde, lehnen sie ab und nennen, was stattdessen anzugeben ist, statt auf eine Person zu warten, die nicht da ist.
In welchem Workspace ein Aufruf beantwortet wird
Ein Aufruf nennt seinen Workspace mit workspace_root; andernfalls wird er in dem Workspace beantwortet, über dem der Server gestartet wurde. Wo der Start einen Stamm genannt hat, mit --workspace-root oder AGGREGA_WORKSPACE_ROOT, ist dieser Stamm selbst der Workspace-Stamm, so wie das Flag es bei jedem Befehl ist: Oberhalb davon wird nach keinem umschließenden Workspace gesucht, sodass ein Start den Ordner nennt, der die .aggrega-config.yaml des Workspaces enthält, und ein Aufruf dort sowohl von den innerhalb des Servers laufenden Tools als auch von den Befehls-Tools beantwortet wird. Wo der Start keinen genannt hat, wird der Workspace vom Verzeichnis aus gefunden, in dem der Server gestartet wurde, genau so, wie ein dort in einem Terminal eingegebener Befehl ihn ermittelt — die Reihenfolge ist unter Die anderen Arten, wie ein Projektstamm erkannt wird dargelegt —, außer beim Start des Desktop-Bundles mit leerer Einstellung Workspace folder, der einen solchen Aufruf stattdessen ablehnt, wie unten dargelegt. Ein relativer workspace_root wird ausgehend von dem Stamm gelesen, in dem ein Aufruf ohne eigenen beantwortet wird — dem Stamm, den der Start genannt hat, oder, wo er keinen genannt hat, dem Workspace-Stamm, zu dem sich das Verzeichnis auflöst, in dem der Server gestartet wurde —, sodass ein Aufruf einen Ordner innerhalb des Workspaces nennt, etwa quickstart-ai/1, ohne zu wissen, wo der Workspace auf dem Rechner liegt; ein absoluter wird so verwendet, wie er angegeben ist. Jedes Tool liest ihn so, die Befehls-Tools eingeschlossen. Wo es keinen Stamm gibt, von dem aus ein relativer gelesen werden kann — ein Startstamm, der kein vorhandener Ordner ist, oder der Desktop-Start mit leerem Workspace folder —, wird ein relativer so abgelehnt wie ein Aufruf, der keinen nennt. Ein workspace_root, der keinen vorhandenen Ordner oder eine Datei nennt, wird abgelehnt, bevor das Tool irgendetwas anderes tut, wobei das Argument genannt und der Wert zitiert wird — ein absoluter so, wie er gesendet wurde, ein relativer in der vollständigen Form, in der er gelesen wurde —, so wie ein Befehl --workspace-root ablehnt.
Ein Startstamm, der kein vorhandener Ordner ist, wird auf Standardeingabe und -ausgabe als Ablehnung ausgeliefert. Wo --workspace-root oder AGGREGA_WORKSPACE_ROOT einen Ordner nennt, der nicht existiert, oder eine Datei nennt, schreibt der Server die Ablehnung in seinen Fehlerstrom und startet trotzdem, sodass ein Client, der seinem Benutzer nichts von diesem Strom zeigt, dennoch den Grund zeigt. Er beantwortet initialize und seine Tool-, Ressourcen- und Prompt-Listen, und jeder Aufruf, der in diesem Workspace wirken würde, wird mit der Ablehnung beantwortet: ein Tool-Aufruf als fehlgeschlagenes Ergebnis, das Lesen einer catalog://-Entität oder einer Dokumentationsseite als Fehler. Die Ablehnung nennt das Flag oder die Variable zusammen mit der Einstellung Workspace folder der Desktop-Anwendung, die sie setzt — der Einstellung, die Claude Desktop beschreibt —, und zitiert den Wert genau so, wie er angegeben wurde; ein Wert, den der Client gesendet hat, ohne ihn auszufüllen, wird so zitiert, wie er angekommen ist, und nichts darin wird interpretiert. Ein Tool, das einen Befehl ausführt, startet für einen Aufruf, der keinen eigenen Workspace nennt, keinen, da der Ordner, in dem dieser Befehl starten würde, nicht vorhanden ist, und antwortet mit derselben Ablehnung. Ein Aufruf, der einen eigenen Workspace mit einem absoluten Pfad nennt, wird dort beantwortet; einer, der ihn mit einem relativen Pfad nennt, hat keinen Ordner, von dem aus er gelesen werden kann, und wird mit derselben Ablehnung beantwortet. Was in keinem Workspace wirkt — ein Schema, ein Prompt, die Hilfe eines Befehls —, wird wie auf jedem Server beantwortet. Ein Listener wird stattdessen beim Start abgelehnt, bevor irgendetwas gebunden wird, mit derselben Ablehnung, sodass jeder, der ihn überwacht, den Fehler dort liest, wo er danach sucht.
Ein Desktop-Start mit leerer Einstellung Workspace folder wird auf dieselbe Weise als Ablehnung ausgeliefert. Das Desktop-Bundle übergibt dem Server immer AGGREGA_WORKSPACE_ROOT mit dem, was Workspace folder enthält, und setzt daneben AGGREGA_BUNDLE_VERSION, während die Anwendung den Server in einem Ordner ihrer Wahl startet — oft einem Systemordner — statt in Ihrem Projekt. Ein Server auf Standardeingabe und -ausgabe, der ohne --workspace-root gestartet wurde und dessen Umgebung AGGREGA_BUNDLE_VERSION und ein leeres oder fehlendes AGGREGA_WORKSPACE_ROOT trägt, sucht daher nicht vom Ordner aus nach einem Workspace, in dem er gestartet wurde. Er schreibt die Ablehnung in seinen Fehlerstrom und startet trotzdem und antwortet so wie bei einem Startstamm, der nicht vorhanden ist: Jeder Aufruf, der in einem Workspace wirken würde und keinen eigenen nennt, wird mit einer Ablehnung beantwortet, die besagt, dass die Desktop-Anwendung den Server mit leerer Einstellung Workspace folder gestartet hat, sodass AGGREGA_WORKSPACE_ROOT keinen Workspace-Stamm nennt, die Sie auffordert, Workspace folder auf den Ordner zu setzen, der die .aggrega-config.yaml Ihres Workspaces enthält, und die besagt, dass ein nach dem Start des Servers gesetzter Ordner wirksam wird, sobald die Erweiterung aus- und wieder eingeschaltet oder die Anwendung neu gestartet wird, weil die Anwendung die Einstellung dem Server nur übergibt, wenn sie ihn startet. Ein Tool, das einen Befehl ausführt, startet für einen solchen Aufruf keinen. Ein Aufruf, der einen eigenen Workspace mit einem absoluten Pfad nennt, wird dort beantwortet, und einer, der ihn mit einem relativen Pfad nennt, wird mit derselben Ablehnung beantwortet, da es keinen Workspace folder gibt, von dem aus er gelesen werden kann; was in keinem Workspace wirkt, wird wie auf jedem Server beantwortet. Der Server erkennt den Start allein an AGGREGA_BUNDLE_VERSION: Bei einem Bundle, das keine solche Variable setzt, wird eine leere Einstellung als kein Stamm gelesen, und ein Start, der die Variable von Hand setzt und keinen Stamm nennt, wird wie der des Bundles abgelehnt. Jeder andere leere Wert nennt weiterhin keinen Stamm — ein leeres AGGREGA_WORKSPACE_ROOT bei einem Start ohne AGGREGA_BUNDLE_VERSION, ein leer eingegebenes --workspace-root, ein Listener, aggrega serve und jeder andere Befehl lesen ihn jeweils als nicht gesetzt.
Wo kein Workspace gefunden und keiner genannt wurde, sagt eine Antwort, die den Workspace betrifft, welchen Ordner sie verwendet hat. Ohne Startstamm, ohne workspace_root beim Aufruf und ohne etwas, das einen Workspace vom Ordner aus verankert, in dem der Aufruf beantwortet wurde, wird der Aufruf in diesem Ordner beantwortet. Wo das Ergebnis des Tools vom Workspace abhängt — bei denselben Tools, deren Befehle auf der Kommandozeile warnen —, endet sein Text mit der Warnung der Kommandozeile, <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace, und einer Zeile, die Sie auffordert, workspace_root mit dem Ordner zu senden, der die .aggrega-config.yaml Ihres Workspaces enthält; eine Antwort, die nicht vom Workspace abhängt, etwa das Auslesen der Konfiguration oder die Auflistung der Plugins, sagt nichts über Workspaces. Der Satz fügt dem strukturierten Ergebnis kein eigenes Feld hinzu; das strukturierte Ergebnis trägt ihn in text_answer, das den Text enthält, wie Die zwei Teile einer Antwort es darlegt. Ein Tool, das einen Befehl in einem separaten Prozess ausführt, trägt die eigene Zeile des Befehls, die dasselbe besagt, so wie der Befehl sie ausgegeben hat. In einem solchen Ordner wird nichts in einen Artefakt-Cache geschrieben: Ein Pull oder ein Build, der seine Abhängigkeiten zuerst auflösen soll, wird dort abgelehnt, bevor irgendetwas abgerufen wird, wobei der Ordner und die zwei Möglichkeiten genannt werden — workspace_root senden oder dem Ordner eine .aggrega-config.yaml mit einem workspace:-Block geben. Ein Pin oder eine Veröffentlichung eines Recipe oder FeatureRecipe wird auf dieselbe Weise abgelehnt, wo er eine entfernte Quelle abrufen würde, die die Entität vollständig ausschreibt — um sie zu pinnen oder ihren Pin zu vergleichen —, bevor diese Quelle abgerufen wird; wo er keine abruft, weil die Entität keine Quelle hat, eine lokale oder eine, deren Koordinaten jedes Release ausfüllt, wird er wie überall sonst beantwortet. Ein Build dort, der zuvor nichts auflöst, rendert trotzdem, aber eine externe Eingabe, die seine Lockfile pinnt und die der Cache nicht mehr enthält, wird nicht erneut abgerufen: Dem Rendern wird anstelle der Eingabe derselbe Satz mitgeteilt, so wie ihm der eines Offline-Modus mitgeteilt wird. Keine Antwort über HTTP trägt den Satz: Ein Listener bedient immer einen Workspace, der ihm gegeben wurde oder den er gefunden hat. Ebenso wenig der Start des Desktop-Bundles mit leerer Einstellung Workspace folder, der einen Aufruf, der keinen eigenen Workspace nennt, ablehnt, statt ihn in dem Ordner zu beantworten, in dem er gestartet wurde.
Ein Aufruf zu einem Release oder einem Dokument, das er mit einem absoluten Pfad nennt, wird im eigenen Workspace dieser Datei beantwortet, wenn nichts anderes einen festgelegt hat. Wo der Start keinen Stamm genannt hat, der Aufruf kein workspace_root sendet und das Verzeichnis, in dem der Server gestartet wurde, keinen Workspace verankert, wird der Workspace erneut vom Ordner aus ermittelt, in dem diese Datei liegt, und was auch immer dabei gefunden wird — das Projekt, zu dem die Datei gehört, oder, wenn alles andere fehlschlägt, dieser Ordner —, ist derjenige, in dem der Aufruf beantwortet wird. Das ist die Regel, der ein in einem Terminal eingegebener Befehl folgt, daher gilt sie für jedes Tool, dessen Aufruf ein Release oder ein Entitätsdokument betrifft, das er nennt: einen Build, einen Pull, eine Validierung, einen Lint, eine Beschreibung, eine Auflistung in den Begriffen eines Release, eine Frage zu einem Knoten des Graphen eines Release, einen Pin, die Veröffentlichung einer Entität, eine Bearbeitung und eine in einem Dokument gelesene Position. Wo ein Aufruf sowohl ein Release als auch ein Dokument nennt, entscheidet das Release. So wird bei einem Client, der den Server außerhalb Ihres Projekts gestartet hat, ein Release darin dennoch aus der eigenen Konfiguration des Projekts gebaut. Die anderen Pfade, die der Aufruf nennt, werden wie immer gelesen — ein relativer vom Verzeichnis aus, in dem der Server gestartet wurde —, und ein Tool, das einen Befehl in einem separaten Prozess ausführt, wird aus demselben Workspace beantwortet, weil der Befehl in demselben Verzeichnis derselben Regel folgt. Ein Stamm, den der Start genannt hat, ein workspace_root, den der Aufruf sendet, ein Startverzeichnis, das selbst innerhalb eines Workspaces liegt, und ein Release oder Dokument, das mit einem relativen Pfad genannt wird, werden so verwendet, wie sie sind. Über HTTP stellt sich nichts davon: Ein Listener bedient immer einen Workspace, der ihm gegeben wurde oder den er gefunden hat, und jeder Pfad, den ein Aufruf nennt, ist relativ zu ihm. Ebenso wenig beim Start des Desktop-Bundles mit leerer Einstellung Workspace folder, der einen Aufruf, der keinen eigenen Workspace nennt, ablehnt, welche Datei er auch nennt.
Eingrenzen, was der Server ankündigt
mcp.announce_tools benennt die Tools, die dieser Server ankündigt, genau so geschrieben, wie die Tool-Liste sie meldet. Lassen Sie den Schlüssel weg, wird jedes Tool angekündigt, das dieser Server mitbringt; das ist der Standard und die Form, die ein protokollkonformer Client erwartet. Schreiben Sie eine Liste, werden genau diese Tools angekündigt: Ein ausgelassenes fehlt in der Tool-Liste, fehlt in dem, was describe-capabilities antwortet, und wird abgewiesen, wenn es trotzdem namentlich aufgerufen wird, wobei die Abweisung diese Einstellung nennt. Schreiben Sie eine leere Liste, wird überhaupt nichts angekündigt — den Schlüssel wegzulassen und [] zu schreiben sind also verschiedene Aussagen, und die Einstellung hat keinen Standard, der für Sie eingesetzt wird.
Setzen Sie sie dort, wo der Client am anderen Ende begrenzt, wie viele Tools er registriert, manchmal über alle Server hinweg, mit denen er gleichzeitig verbunden ist, und benennen Sie die Tools, die dieser Client braucht. Diese Obergrenze ist der Fall, für den die Einstellung existiert, und der Client, für den sie gilt, ist meist derjenige, der diesen Server über seine eigene Standardeingabe und -ausgabe gestartet hat — daher wird dieser Schlüssel, anders als der Rest des Blocks mcp, der den vom Transport http gestarteten Listener konfiguriert, gelesen, gleich welchen Transport der Server spricht.
Sie grenzt ein, was angekündigt wird, und nichts weiter. Ein hier genanntes Tool erweitert nichts. Sie hebt mcp.deny_reach nicht auf, das eine Fähigkeit vollständig entzieht; ein hier genanntes Tool einer Art, die jene Einstellung entzieht, bleibt also aus der Liste und wird mit Nennung jener Einstellung abgewiesen. Ebenso wenig hebt sie die Scopes auf, die das Token eines Aufrufers trägt: Ein hier genanntes Tool wird aufgeführt, gleich welche Scopes das sind, und ein Aufruf, den sie nicht zulassen, wird dennoch abgewiesen, unter Nennung des Scopes, der ihn zuließe. In beiden Fällen ist die Abweisung, auf die ein Aufrufer trifft, die jener anderen Grenze und nicht dieser. Eine Abweisung durch diese Einstellung trägt keine Challenge und nennt keinen Scope, weil keine Berechtigung ändert, was ein Server anzubieten beschlossen hat — stattdessen nennt sie die Einstellung, das Einzige, worauf jemand, der die Abweisung liest, reagieren kann.
Jeder Name muss einer sein, den dieses Binary mitbringt. Ein Name, auf den kein Tool hört, stoppt den Server, bevor er irgendetwas bedient, und die Abweisung listet die Tools auf, die er hat — so fällt ein Tippfehler beim Start auf statt durch eine Oberfläche, die stillschweigend schmaler ist als die angeforderte. Ein Name der Familie cli-, die einen aggrega-Befehl in einem separaten Prozess ausführt, wird auf beiden Transporten akzeptiert und kündigt über HTTP nichts an, wo ein solches Tool ohnehin keinem Aufrufer angeboten wird.
Die angekündigte Menge wird beim Start des Prozesses festgelegt, eine Änderung erfordert also einen Neustart, und nichts lässt die Liste unter einem bereits verbundenen Client wachsen.
Aus welcher Version der Server stammt
describe-capabilities ohne Argumente gesendet gibt an, aus welcher Version dieser Server stammt. Seine strukturierte Antwort enthält server_version, die Version, die die ausführbare Datei aggrega für sich selbst meldet — die, die aggrega version für dieselbe Datei ausgibt —, und sein Text beginnt mit einer Zeile, die sie nennt, vor dem Index. Die strukturierte Antwort enthält dieselbe Zeile als version_summary, Wort für Wort, sodass ein Client, der einem Modell nur die strukturierte Antwort übergibt, ihm auch die Zeile übergibt.
Wo das Desktop-Bundle den Server gestartet hat, nennt dieselbe Antwort daneben die Version des Bundles. Das Bundle enthält kein Programm: Es startet die ausführbare Datei aggrega, die seine Einstellung Path to the aggrega executable nennt, standardmäßig den Befehlsnamen aggrega, den die Anwendung in ihrem PATH sucht. Bundle und ausführbare Datei werden also getrennt installiert und können aus verschiedenen Versionen stammen, und die Anwendung, die das Bundle auflistet, zeigt nur die Version des Bundles selbst. Das Bundle übergibt dem Server seine Version als AGGREGA_BUNDLE_VERSION in dessen Umgebung; der Server liest sie einmal, beim Start, und die Antwort enthält sie als bundle_version. Die beiden werden genau so verglichen, wie sie geschrieben sind, was ein fairer Vergleich ist, weil Bundle und ausführbare Datei einer Version mit der Versionsangabe dieser Version in derselben Form gestempelt werden, während sich ein Entwicklungs-Build von jeder Version unterscheidet. Sind beide gleich, nennt die Zeile beide und sagt nichts weiter. Unterscheiden sie sich, sagt die Zeile unter Nennung beider, dass die ausführbare Datei und das Bundle aus verschiedenen Versionen stammen, und die Hinweise, die der Server einem Modell beim Verbinden gibt, beginnen mit genau diesem Satz, sodass der Unterschied dem Modell vorliegt, bevor es fragt.
Ein Server, den kein Bundle gestartet hat, meldet nur seine eigene Version. Aus einem Terminal, aus der Konfiguration eines Editors oder als Listener gestartet, enthält er kein bundle_version, es sei denn, etwas setzt die Variable in seiner Umgebung. Ein Server über Standardeingabe und -ausgabe, der die Variable trägt, gilt in einer weiteren Hinsicht als vom Bundle gestartet: Ist ihm kein Stammverzeichnis genannt, weist er die leere Einstellung Workspace folder ab, wie In welchem Workspace ein Aufruf beantwortet wird darlegt. Ein describe-capabilities-Aufruf, dem kind oder tools gesendet wurde, enthält weder server_version, bundle_version noch version_summary und keine solche Zeile, weil er über Tools Auskunft gibt und nicht über den Server.
Ein Unterschied wird gemeldet und nie abgewiesen. Der Server startet und beantwortet jeden Aufruf genau so, wie er es täte, wenn beide übereinstimmten. Was ein Unterschied für eine Desktop-Installation bedeutet und wie man beide in Einklang bringt, steht in Den MCP-Server verbinden.
Den Server über HTTPS erreichen
aggrega mcp --transport http stellt das Protokoll über HTTP statt über Standardeingabe und -ausgabe bereit. mcp.transport in der Workspace-Konfiguration ist der Schlüssel, den dieses Flag überschreibt, und sein Standard, stdio, ist das, was ein Client erwartet, der den Befehl startet — ein Server, den andere Personen erreichen, trägt also transport: http in seiner Konfiguration, und ein Client, der aus einem von dieser Konfiguration erfassten Verzeichnis gestartet wird, erreicht den Server trotzdem über seine eigenen Streams. Es ist in beiden Fällen derselbe Server — derselbe Workspace und dieselben Protokolloberflächen —, und was sich ändert, ist, wie eine Nachricht ihn erreicht, wie ein Aufruf endet und was derjenige, der ihn betreibt, bereithalten muss. Dieser Abschnitt beschreibt, was ein Betreiber konfiguriert; der Eintrag, den ein Client braucht, um einen laufenden Server zu erreichen, steht in Den MCP-Server verbinden.
Eine Adresse wählt keinen Transport. --listen <address> oder, wenn das Flag fehlt, mcp.listen gibt an, wo der Listener sich bindet, sobald http gewählt ist, und nichts weiter. http ohne Adresse aus einer der beiden Quellen wird also abgewiesen, bevor irgendetwas gebunden wird, und die Abweisung nennt beide. --listen, eingegeben, während der Transport stdio ist — eingegeben als --transport stdio, konfiguriert als mcp.transport: stdio oder auf dem Standard belassen —, wird ebenfalls abgewiesen, unter Nennung von --transport http als dem Flag, das auf dieser Adresse bedienen würde; ein --listen mit leerem Wert wird abgewiesen, weil er keine Adresse nennt, gleich welcher Transport. Und eine Adresse, die nur die Konfiguration nennt, bleibt von einem Server, der über seine eigenen Streams spricht, ungenutzt; er meldet dies in einer Zeile auf seinem Fehlerstrom und nennt dabei die Datei, die sie gesetzt hat, und mcp.transport: http. Dieser letzte Fall wird absichtlich nirgends abgewiesen: Es ist der Start, den ein Client vornimmt, wenn er den Befehl in einem Verzeichnis startet, dessen Konfiguration die Einstellungen eines Listeners enthält, und eine Listener-Konfiguration, die transport: http vergisst, startet überhaupt keinen Listener, und genau dort fällt es auf.
Ein über HTTP erreichter Server bietet kein Tool an, das einen aggrega-Befehl in einem separaten Prozess ausführt. Diese Tools existieren nur für einen Client, der diesen Server über seine Standardeingabe und -ausgabe gestartet hat, auf dem eigenen Rechner dieses Clients, wo das Nennen eines Ordners oder Flags dem Aufrufer nichts gewährt, was er nicht ohnehin schon hatte. Ein Aufrufer, der den Server über HTTP erreicht, besitzt den Host nicht, auf dem dieser läuft; ein Befehl, der mit der Autorität des Servers auf das Dateisystem dieses Hosts einwirken würde, wird daher stattdessen in einem Terminal auf dem Host ausgeführt. Die Tools fehlen in der Liste und in describe-capabilities, statt angeboten und abgewiesen zu werden, und ein Aufruf, der eines nennt, wird mit einem Fehler beantwortet, der dies sagt. Das ist eine Eigenschaft des Transports, keine Einstellung: Es gibt keine Konfiguration, die sie zurückbringt.
Lesen Sie Ohne Berechtigungsnachweis wird nichts bereitgestellt, bevor Sie einen solchen Server bereitstellen. Jede Anfrage an den Endpunkt trägt einen Berechtigungsnachweis, und es gibt keine Einstellung, die eine Anfrage ohne einen solchen bedient — eine Einstellung wählt nur, ob dieser Server selbst ein Bearer-Token prüft oder einen Aufrufer liest, den ein vorgeschalteter Proxy bereits geprüft hat.
Die zwei Bereitstellungsformen
Der Prozess terminiert TLS selbst. Setzen Sie mcp.tls.cert_file auf eine PEM-Zertifikatskette und mcp.tls.key_file auf deren privaten Schlüssel, und der Listener stellt HTTPS direkt auf der Adresse bereit, die Sie ihm gegeben haben. Beide Dateien werden beim Start des Prozesses gelesen, ein ersetztes Zertifikat wird also durch einen Neustart des Prozesses übernommen. Nur eine der beiden zu setzen wird beim Start abgewiesen, statt auf etwas anderes zurückzufallen: Ein Zertifikat ohne Schlüssel kann nicht vorgelegt werden, ein Schlüssel ohne Zertifikat benennt nichts, und ein Tippfehler in einem Pfad ist kein Grund, unverschlüsselten Datenverkehr zu bedienen.
Ein vorgeschalteter Proxy terminiert TLS und leitet an einen eingeschränkten Listener weiter. Lassen Sie beide Schlüssel ungesetzt, und der Listener arbeitet im Klartext, was nur auf Loopback oder einem Unix-Socket akzeptiert wird — so kann nichts, was nicht bereits auf diesem Host ist, ihn erreichen. Das ist die Form, die ein Reverse Proxy, ein Sidecar oder ein Service Mesh verwendet, und es ist diejenige, bei der das Zertifikat vor diesem Prozess liegt statt in ihm.
Ein Klartext-Listener auf jeder anderen Adresse wird abgewiesen, bevor irgendetwas gebunden wird, und die Abweisung nennt beide TLS-Schlüssel. Es gibt keine Einstellung, die das aufhebt, und keine Adresse, die eine Ausnahme ist: Ein Listener, der ohne eigenes Zertifikat Verbindungen aus dem Netzwerk annimmt, ist nie sicher, daher verweigert der Prozess den Start, statt in dieser Form zu starten.
Die Adressformen
--listen und mcp.listen nehmen eine von zwei Formen an:
host:port— eine TCP-Adresse wie127.0.0.1:7777oder0.0.0.0:8443. Loopback bedeutet127.0.0.1,::1oderlocalhost, wenn jede Adresse, in die dieser Name aufgelöst wird, eine Loopback-Adresse ist. Alles andere ist eine Netzwerkadresse und braucht ein Zertifikat: ein leerer Host, also jede Schnittstelle des Rechners; die Adresse einer bestimmten Schnittstelle; und jeder andere Name, selbst einer, der in diesem Moment in eine Loopback-Adresse aufgelöst wird, denn wo sich ein Listener binden darf, sollte nicht von einer Auflösung abhängen, die sich unter ihm ändern kann.unix:gefolgt von einem Dateisystempfad — ein Unix-Domain-Socket wieunix:/run/aggrega/mcp.sock. Ein Socket ist nur von dem Host aus erreichbar, auf dem er liegt, daher braucht er kein Zertifikat.
Ein Socket-Pfad wird genau so genommen, wie er geschrieben ist, auch ein relativer. Er wird bewusst nicht relativ zu der Konfigurationsdatei aufgelöst, die ihn deklariert hat, denn dieselbe Adresse kommt auch über --listen, das keine deklarierende Datei hat — siehe wohin ein relativer Pfad zeigt.
Was der Listener annimmt
Ein Endpunkt, /mcp, der POST annimmt. Jede JSON-RPC-Nachricht ist eine eigene Anfrage, und es wird keinerlei Sitzung gehalten: Nichts, was ein Client zuerst sendet, entscheidet, wie eine spätere Anfrage beantwortet wird, es wird nie eine Sitzungskennung erzeugt, und ein Sitzungs- oder Stream-Wiederaufnahme-Header, den ein Client sendet, wird ignoriert. Jede andere Methode auf diesem Endpunkt wird mit 405 und Allow: POST beantwortet, jeder andere Pfad mit 404 — beides wird vor der Prüfung des Berechtigungsnachweises entschieden, sodass Sondieren nichts aus einer Challenge auf einem Pfad oder einer Methode erfährt, die ohnehin nichts bedienen würde.
Eine Anfrage wird mit einem JSON-Objekt und einem Statuscode beantwortet — oder, wo der Aufruf auf dem Weg zu diesem Objekt Fortschritt gemeldet hat, mit einem Strom von Ereignissen, der darin endet, wie Erfahren, wie ein langer Aufruf vorankommt darlegt. Eine Benachrichtigung — eine Nachricht ohne id — wird mit 202 und leerem Body beantwortet. Eine Nachricht, die keines von beiden ist, einschließlich einer JSON-RPC-Antwort, wird mit 400 beantwortet, weil ein Client diesem Server Anfragen und Benachrichtigungen sendet und sonst nichts.
Beide Protokollrevisionen werden hier genau so bedient wie über Standardeingabe und -ausgabe. Eine 2026-07-28-Anfrage spiegelt ihren Body in Transport-Headern, damit ein Zwischenglied sie weiterleiten kann, ohne den Body zu parsen: MCP-Protocol-Version trägt die Revision, die der Body angibt, Mcp-Method die Methode, die er nennt, und Mcp-Name das Ziel, bei den Methoden, die eines namentlich adressieren. Ein Header, der dem Body widerspricht, wird mit 400 beantwortet. Ein 2025-06-18-Client beginnt mit einem initialize-Handshake, der zustandslos beantwortet wird; er kann den Versions-Header mit dieser Revision tragen oder ihn weglassen. Eine Anfrage, die eine Revision nennt, die der Server nicht spricht, wird mit 400 beantwortet, unter Auflistung der beiden, die er spricht, und eine, die eine Methode nennt, die er nicht bedient, mit 404.
mcp.allowed_origins wird nur herangezogen, wenn eine Anfrage einen Origin-Header trägt, was in der Praxis bedeutet, dass ein Browser sie gesendet hat: Eine Anfrage, die einen Origin nennt, den die Liste nicht enthält, wird mit 403 beantwortet, und eine ohne solchen Header wird bedient. Ein Client, der kein Browser ist, sendet keinen solchen Header und braucht keinen Eintrag. Ein browserbasierter braucht immer einen Eintrag: Die Liste ist leer, bis ein Betreiber sie schreibt, bis dahin ist also überhaupt kein Origin enthalten, und jede Browser-Anfrage wird mit 403 beantwortet — auch eine von einer Seite, die unter der eigenen Adresse des Endpunkts bereitgestellt wird. Der Eintrag wird exakt mit dem Header verglichen, er wird also so geschrieben, wie ein Browser einen Origin sendet — ein kleingeschriebenes Schema, ://, ein kleingeschriebener Host und, wo er nicht dem Standard des Schemas entspricht, : und der Port, etwa https://app.example.com —, und ein Eintrag mit einem Pfad, einem abschließenden /, ohne Schema oder mit einem Großbuchstaben wird beim Laden der Konfiguration unter Nennung des Eintrags abgewiesen, weil er nie übereinstimmen könnte.
mcp.limits begrenzt den angenommenen Datenverkehr. Ein Body über max_body_bytes wird mit 413 beantwortet und nicht über die Grenze hinaus gelesen. Eine Anfrage, die eintrifft, während bereits max_concurrent_requests in Bearbeitung sind, wird mit 503 beantwortet, statt hinter Arbeit eingereiht zu werden, die sie nicht sehen kann. Ein Aufrufer, der innerhalb einer Minute mehr als requests_per_minute sendet, wird mit 429 beantwortet, gezählt nur für diesen Aufrufer, sodass ein Aufrufer, der stark sendet, einen anderen nichts kostet. Der Standard jeder Grenze steht neben ihrem Schlüssel in der Konfigurationsreferenz, und keine von ihnen hat einen Wert, der sie abschaltet.
Ein Prozess, ein Workspace
Der Workspace, für den ein bereitstellender Prozess antwortet, wird beim Start festgelegt. --workspace-root benennt ihn; die Variable AGGREGA_WORKSPACE_ROOT liefert ihn, wenn das Flag fehlt. Der genannte Ordner ist das Workspace-Stammverzeichnis selbst, ohne dass darüber gesucht wird, und ein Ordner, der nicht existiert, wird abgewiesen, unter Nennung derjenigen der beiden Quellen, die ihn geliefert hat, und unter Zitierung des Werts wie angegeben — von einem Listener, bevor er sich bindet, und von einem Server über Standardeingabe und -ausgabe in seiner Antwort auf jeden Aufruf, der in diesem Workspace handelt, wie In welchem Workspace ein Aufruf beantwortet wird darlegt —, sodass ein Start, den ein Client zusammengesetzt statt jemand eingetippt hat, dennoch sagt, was ihm übergeben wurde. Ohne beides löst ein Server über Standardeingabe und -ausgabe den Workspace aus dem Verzeichnis auf, in dem er gestartet wurde — wo dort nichts einen Workspace verankert, sagt jede Antwort, die den Workspace betrifft, welchen Ordner sie verwendet hat, und der Start des Desktop-Bundles mit leerer Einstellung Workspace folder weist stattdessen einen Aufruf ab, der keinen eigenen Workspace nennt, wie In welchem Workspace ein Aufruf beantwortet wird darlegt —, und ein Listener wird abgewiesen, bevor er sich bindet, sofern dort kein Workspace aufgelöst wird — ein über HTTP erreichter Prozess beantwortet Aufrufer, die den Rechner nicht sehen können, daher bedient er einen Workspace, den ein Betreiber gewählt hat, statt des Verzeichnisses, in dem er zufällig gestartet wurde. Um mehrere Projekte bereitzustellen, führen Sie einen Prozess pro Projekt-Stammverzeichnis aus.
Ein über HTTP eintreffender Aufruf kann keinen eigenen Workspace nennen. workspace_root und catalog_dirs werden unter Nennung des gesendeten Arguments abgewiesen, statt stillschweigend verworfen zu werden: Ein stillschweigend ignoriertes Argument sieht für seinen Absender genauso aus wie ein berücksichtigtes. Die neben dem bereitgestellten Workspace durchsuchten Katalogverzeichnisse sind die eigene Einstellung workspace.catalog_dirs dieses Workspace — oder, für ein Release, dem er unter workspace.releases eigene Verzeichnisse gibt, die dieses Release —, die der Betreiber schreibt. Über Standardeingabe und -ausgabe werden beide Argumente berücksichtigt, weil der Client, der den Server gestartet hat, auf dem eigenen Rechner des Aufrufers läuft. Dort ist ein catalog_dirs-Eintrag absolut oder relativ zu dem Workspace-Stammverzeichnis, aus dem ein relatives release gelesen wird — dem Stammverzeichnis, das das eigene workspace_root des Aufrufs, der Start oder das Verzeichnis, in dem der Server gestartet wurde, zuerst festgelegt hat, und demjenigen, aus dem weiterhin gelesen wird, wo ein absolut genanntes Release den Aufruf in den eigenen Workspace dieses Release verlegt — und nicht zu dem Verzeichnis, in dem der Server läuft, wo dieses woanders liegt.
Auch ein Pfad, den ein Aufruf nennt, bleibt innerhalb dieses Workspace. Über HTTP wird ein Pfadargument relativ zum Workspace-Stammverzeichnis aufgelöst und abgewiesen, wenn es darüber hinausreicht — ein relativer Pfad, der aus dem Workspace hinaufsteigt, ein absoluter Pfad, der woandershin zeigt, und ein relativer Pfad, der über einen Link zu einer dort liegenden Datei oder einem dort liegenden Verzeichnis aus dem Workspace hinausführt, kommen jeweils als Fehler zurück, der das Argument nennt, aber weder das Workspace-Stammverzeichnis noch den Ort, den der Pfad erreicht hätte; ein relativer Pfad wird so zurückgegeben, wie Sie ihn gesendet haben. Jedes Pfadargument wird danach beurteilt, wohin es führt, nach der Definition von „innerhalb“, die Die Workspace-Grenze angibt, ob das Tool es liest oder schreibt — das Verzeichnis, in das gen-catalog seine Ausgabe schreibt, das Dokument, das edit-document zurückschreibt, und die Entität, neben die pin seine Sperre schreibt, ebenso wie ein Dokument, das ein Tool liest —, sodass ein noch nicht angelegter Pfad unter einem Link, der aus dem Workspace hinausführt, wie dieser Link abgewiesen wird, ohne dass etwas gelesen oder geschrieben wird. Ein release, das ein Release nennt, das die Konfiguration des bereitgestellten Workspace als build.authoring_release oder als Schlüssel von workspace.releases nennt, wird über diese Konfiguration erreicht und über einen Link akzeptiert, wo auch immer seine Datei liegt; kein anderes Argument hat diese Ausnahme. Wo der gemeinte Pfad innerhalb dieses Workspace liegt, aber absolut geschrieben wurde, gibt Ihnen die Abweisung die stammverzeichnisrelative Schreibweise an, die Sie stattdessen senden können, sodass ein Aufrufer, der die falsche Form geraten hat, die richtige erfährt statt nur, dass sie falsch war. Das gilt für die Pfade, die ein Aufruf als seinen Gegenstand nennt — das zu validierende Dokument, das zu bauende Release, das Verzeichnis, in das eine Generierung ihre Ausgabe schreibt —, und für die, in die ein Tool schreibt, nicht weniger als für die, die es liest: Ein Aufrufer, der einen Server über das Netzwerk erreicht, bittet einen Rechner, den er nicht sehen kann, Dateien zu lesen und zu schreiben, und der vom Betreiber gewählte Workspace ist der Ort, an dem dieses Lesen und Schreiben gehalten wird. Über Standardeingabe und -ausgabe behalten die Pfadargumente jedes Tools den unten bei diesem Tool beschriebenen Vertrag, bei dem ein Pfad absolut sein und aus dem Workspace hinauszeigen darf — die aufrufende Person besitzt den Rechner, auf dem der Server läuft, sie auf ein Verzeichnis zu beschränken, das sie selbst gewählt hat, brächte also nichts. Die beiden Tools, deren Operation selbst nur über ein Dokument Auskunft gibt, das der Workspace enthält, insertion-point und edit-document, behalten das auf beiden Transporten bei und weisen ein Dokument außerhalb des Workspace ab, ob es so geschrieben oder über einen hinausführenden Link erreicht wird. Was über Standardeingabe und -ausgabe berücksichtigt wird, ist der Pfad, den ein Aufruf nennt, und nichts darüber hinaus. Was die Operation dann auf eigene Rechnung liest und schreibt, wird auf beiden Transporten genau so gehalten wie beim Eintippen desselben Befehls in einem Terminal: Ein Durchlauf oder ein Nachschlagen liest nicht über einen Link, der aus dem Workspace hinausführt, eine Datei, die ein Release im Workspace oder sein Manifest über einen Pfad nennt, wird nicht von außerhalb des Workspace gelesen — und eine, die ein vom Aufruf außerhalb des Workspace genanntes Release nennt, wird nicht von außerhalb des Verzeichnisses gelesen, das dieses Release enthält —, und eine unterhalb eines Verzeichnisses — des Workspace oder eines vom Aufruf genannten — geschriebene Datei bleibt innerhalb dieses Verzeichnisses. Die Workspace-Grenze stellt die beiden Transporte neben die Kommandozeile und den Editor und gibt an, was über Standardeingabe und -ausgabe offen bleibt: Ein Dokument in einem von Ihnen geklonten Workspace kann einen Assistenten dazu bringen, einen Pfad außerhalb des Workspace zu nennen, und dieser Pfad wird wie genannt berücksichtigt.
Was eine Antwort über das Dateisystem des Servers sagt
Über HTTP nennt eine Antwort einen Ort im Dateisystem des Servers relativ zum Workspace-Stammverzeichnis oder hält ihn zurück. Ein Client, der den Server gestartet hat, läuft dort, wo der Server läuft, daher nennt über Standardeingabe und -ausgabe jede Antwort jeden Ort so, wie die Operation ihn hält — absolut, wo er so gehalten wird —, und jeder ist ein Ort, den dieser Aufrufer bereits besitzt. Ein Aufrufer, der einen Listener erreicht, hat keinen dieser Orte gewählt und kann sie nicht öffnen, und ein Server, der sie ihm offengelegt hat, kann sie nicht zurücknehmen. Über HTTP sagt eine Antwort diesem Aufrufer daher eines von zwei Dingen über einen Ort:
- Ein Ort innerhalb des Workspace wird relativ zum Workspace-Stammverzeichnis genannt — dieselbe Form, die ein von Ihnen gesendeter Pfad hat, sodass ein aus einer Antwort gelesener Name im nächsten Aufruf unverändert zurückgesendet werden kann. Ein Release im Stammverzeichnis ist
release.yaml, und seine Lockdatei istrelease.lock. - Ein Ort außerhalb des Workspace wird zurückgehalten, ebenso das Workspace-Stammverzeichnis selbst. Das Feld trägt keinen Wert — es ist
nulloder weggelassen, und beiattachment-container, dessen Antwort die Form behält, in der jede Oberfläche sie meldet, bleibtfileleer —, und eine Markierung daneben, benannt nach dem Feld mit angehängtem_withheld, sagt, dass es zurückgehalten und nicht ungesetzt ist:workspace_root_withheldnebenworkspace_root,file_withheldnebenfile. Eine Markierung ist nur dort vorhanden, wo etwas zurückgehalten wurde. Das Stammverzeichnis wird zurückgehalten, weil ein Listener genau einen Workspace bedient; wo dieser Workspace liegt, benennt also nichts, was Sie brauchen, um zu benennen, was in ihm liegt.
Ob ein Ort innerhalb liegt, wird danach beurteilt, wie er geschrieben ist, nicht nach der Datei, die er erreicht. Ein Pfad, der über das Ziel eines symbolischen Links statt über das Stammverzeichnis geschrieben ist, über dem der Server gestartet wurde, und ein Pfad, der aus dem Stammverzeichnis hinaus- und wieder hineinsteigt, gelten jeweils als außerhalb des Workspace und werden zurückgehalten. Die Beurteilung irrt in Richtung weniger Auskunft, nie in Richtung der Nennung eines Orts außerhalb des Workspace.
Über HTTP folgt der lesbare Text einer Antwort derselben Regel. Wo der Text, eine Diagnosezeile oder die Meldung eines Fehlers einen Ort nennt, den der Workspace enthält — sein Stammverzeichnis oder etwas darunter, eine Konfigurationsdatei, aus der seine Konfiguration gelesen wurde, ein Verzeichnis, aus dem sein Katalog gelesen wird —, wird dieser Ort relativ zum Stammverzeichnis geschrieben oder lautet (location withheld), wo er außerhalb des Workspace liegt oder das Stammverzeichnis ist. Text, den eine Antwort über ihren eigenen Workspace verfasst, nennt ihn den Workspace, den dieser Server bedient. Ein Ort außerhalb all dieser, den eine Operation in eine Meldung schreibt, wird nicht als solcher erkannt und erreicht Sie so, wie er geschrieben wurde.
Die Antworten, die dies über HTTP betrifft:
list-entities,list-releases,cache-status,registry-list,search,attach-candidates,connection-candidates,insertion-point,attachment-container,connection-at-positionundedit-documenthaltenworkspace_rootzurück. Die Pfade, die sie bereits relativ zum Stammverzeichnis angeben — die Quelldatei einer Entität, der Pfad eines Release und seine Lockdatei unterlockfiles, das Dokument, um das es bei einem Einfügepunkt oder einer Bearbeitung geht, die von einer Bearbeitung geschriebenen Dateien —, lauten auf beiden Transporten gleich.cache-statushält außerdem zurück, was ein Plugin benennt, das der Server aus einer Datei auf seinem Host geladen hat. Eine solche Identität ist an ihrer Stelle inprovenance[].identitiesnull, jede andere Identität behält ihre Position, und der Eintrag wird mitidentities_withheldmarkiert. Dienoteeines kompilierten Moduls ist ein Satz, der die Identitäten nennt, für die das Modul gebaut wurde; wo eine davon eine solche Datei nennt, wird dienotedaher vollständig weggelassen und mitnote_withheldmarkiert; derdigestdes Moduls ist weiterhin vorhanden. Eine Identität, die eine Registry-Referenz oder eine Plugin-Entität nennt, wird vollständig beantwortet, ebenso einenote, die nur solche nennt. Daslabeleines Quellartefakts ist sein Ort im Cache, gebildet aus Host und Pfad der URL, aus der es aufgelöst wurde; bei einem Repository, das aus dem eigenen Dateisystem des Servers gelesen wird — über einefile://-URL oder einen Pfad —, wird daslabeldaher weggelassen und mitlabel_withheldmarkiert, seinesizeund seindigestsind weiterhin vorhanden, und einlabel, das einen Netzwerk-Host nennt, wird vollständig beantwortet. Der Text der Auflistung lautet(location withheld), wo er einen solchen genannt hätte.validatenennttargetund bei einem Releasereleaserelativ zum Stammverzeichnis; für den gesamten Katalog isttargetdas Stammverzeichnis und wird zurückgehalten. Ein Ort indiagnosticsodernoticesfolgt der Regel für Text.buildnenntreleaserelativ zum Stammverzeichnis, und ein Build, der zuerst seine Abhängigkeiten aufgelöst hat, trägtdependency_resolutionso, wiepulles beantwortet. Ein Build, demwritegesendet wurde, nennt das Verzeichnis, in das er geschrieben hat, alsoutput_dir, dasdistlautet — relativ zum Stammverzeichnis —, und jeder Pfad infilesist relativ zu diesem Verzeichnis. Einrefusalund jeder Eintrag seinerfindingsnennt seinefilerelativ zum Stammverzeichnis oder hält sie zurück, wo das Dokument außerhalb des Workspace liegt.advisories,deprecations,declined_external_inputsund jedemessagedesrefusalfolgen der Regel für Text.pullnenntreleaseundlockfilerelativ zum Stammverzeichnis.diagnosticsundincomplete_external_inputsfolgen der Regel für Text. Diesourcejedesresolved-Eintrags wird auf beiden Transporten vollständig beantwortet: Sie nennt, was der Lauf getan hat, nie einen Ort auf dem Host.describenennt dasreleaseeines Release relativ zum Stammverzeichnis und diefileeiner Entität relativ zum Stammverzeichnis, wo ihr Dokument innerhalb des Workspace liegt; bei einer Entität, die aus einem Katalogverzeichnis außerhalb des Workspace gelesen wurde, wird diefilezurückgehalten.mapping_diagnosticsunddeprecationsfolgen der Regel für Text.lintnennt daslocation.filejedes Befunds relativ zum Stammverzeichnis oder hält es zurück, wo die Entität außerhalb des Workspace liegt. Diemessageund dersuggesteines Befunds folgen der Regel für Text.pinnenntentityundlockrelativ zum Stammverzeichnis, und ebenso derpin, den eine Veröffentlichung enthält.gen-catalognennt jede inoutputaufgeführte Datei relativ zum Stammverzeichnis.importhältworkspace_rootzurück, undoutput_dir, wo die Entwürfe in dieses Stammverzeichnis gingen; ein Verzeichnis, das Sie inoutput_dirgenannt haben, wird mit seinem Namen relativ zum Stammverzeichnis angegeben. Jeder Entwurfspfad inwrittenunddraftsist relativ zuoutput_dir, sodass in jedem Fall in der Antwort steht, wohin die Entwürfe gingen. Diemessageeiner Diagnose sowieparams_summary,rationaleundswap_hinteiner Entscheidung sind vom Importer verfasster Fließtext und folgen der Regel für Text.config-showundplugin-listhalten mehr als das Stammverzeichnis zurück, weil das meiste, was sie melden, Konfiguration ist, die Orte nennt, wie Was ein Listener Ihnen nicht über seinen Host sagt darlegt.scaffoldnennt beim Schreiben eines Beispielsdirso, wie Sie es gesendet haben, relativ zum Stammverzeichnis, und jeden Pfad infilesrelativ zu diesem Verzeichnis; das Entwerfen und das Auflisten nennen keinen Ort.- Die Veröffentlichungs-Tools,
sign-artifacts,deprecate-artifact,get-schema,explain-errorunddescribe-capabilitiesnennen von sich aus keinen Ort auf dem Host. Die Fehlermeldung jedes von ihnen folgt der Regel für Text: Die Abweisung, die ein Offline-Workspace auslöst, nennt seine.aggrega-config.yamlrelativ zum Stammverzeichnis. - Ein Pfadargument, das abgewiesen wird, weil es aus dem Workspace hinausreicht, wird abgewiesen, ohne das Stammverzeichnis oder den Ort zu nennen, den es erreicht hätte, wie oben beschrieben.
Wie ein Aufruf endet
Das Schließen der Verbindung bricht den Aufruf ab, den sie trug. Das ist das Abbruchsignal dieses Transports: Der Server behandelt die Trennung durch einen Aufrufer als Abbruch dieser Anfrage, beendet die Arbeit, die er gerade erledigte, und schreibt nichts weiter dafür. Hier wird keine Abbruchnachricht benötigt oder erwartet — das Gegenteil von Standardeingabe und -ausgabe, wo es keinen Stream pro Anfrage zum Schließen gibt und ein Client einen Aufruf stattdessen durch Nennung seiner id beendet. Eine Abbruchnachricht, die über HTTP doch eintrifft, wird angenommen und beendet nichts.
Das Stoppen des Prozesses leert den Listener. Ein Interrupt oder eine Beendigungsanforderung von einem Supervisor oder einer Container-Runtime lässt den Listener keine Verbindungen mehr annehmen und lässt einen Aufruf, der bereits beantwortet wird, innerhalb eines begrenzten Zeitbudgets fertig werden, sodass ein Aufrufer, der vor dem Stopp etwas angefragt hat, seine Antwort noch erhält. Ein Aufruf, der innerhalb dieses Budgets nicht fertig ist, verliert seine Verbindung. Eine zweite Stopp-Anforderung beendet den Prozess sofort.
Liveness und Readiness, auf einer eigenen Adresse
mcp.health.listen ist der Ort, an dem ein Supervisor fragt, ob dieser Prozess läuft und ob er einen Aufruf beantworten kann. Geben Sie ihm eine Adresse in einer der obigen Formen, und ein zweiter Listener beantwortet dort GET /healthz und GET /readyz. Lassen Sie es weg — das ist der Standard —, und es wird kein zweiter Listener gestartet und keine der beiden Prüfungen irgendwo beantwortet.
Die beiden Antworten sagen Verschiedenes, und dieser Unterschied ist der Grund, warum es zwei gibt. /healthz wird ab dem Moment, in dem der Prozess läuft, mit 200 beantwortet, und das ist alles, was Liveness behauptet: Er läuft, und ein Supervisor, der überhaupt keine Antwort erhält, sollte ihn neu starten. /readyz wird mit 503 beantwortet, bis der Workspace, den dieser Prozess bedient, aufgelöst ist und der Endpunkt sich gebunden hat, und ab dann mit 200 — so hält ein Load Balancer den Datenverkehr zurück, bis der Prozess tatsächlich einen Aufruf beantworten kann, statt die erste Anfrage an einen zu senden, der noch startet. Jede Antwort ist ein Statuscode mit leerem Body; es wird kein Berechtigungsnachweis verlangt, und nichts, was der Aufrufer gesendet hat, wird gelesen.
Der Endpunkt beantwortet diese beiden Pfade nie. GET /healthz und GET /readyz auf der von mcp.listen genannten Adresse werden mit 404 beantwortet, genau wie jeder andere Pfad, den dieser Endpunkt nicht bedient, mit Token wie ohne. Dort eine Prüfung zu beantworten, gäbe allem, was den Endpunkt erreicht, kostenlos Auskunft darüber, ob der Prozess läuft, zusammen mit einer kostenlosen Möglichkeit, ihn Arbeit verrichten zu lassen — auf einem Listener, der sonst jede Anfrage ohne Berechtigungsnachweis abweist.
Wo die Health-Adresse liegt, wählen Sie selbst, und sie ist nicht so eingeschränkt wie mcp.listen. Keine Adresse wird dafür abgewiesen. Richten Sie sie auf Loopback oder einen Unix-Socket, wofür sie gedacht ist: einen Supervisor, einen Load Balancer oder eine Container-Runtime, die neben diesem Prozess auf demselben Host läuft. Alles, was die gewählte Adresse erreichen kann, kann diese beiden Antworten lesen; eine Adresse, die das offene Netzwerk erreicht, veröffentlicht sie also im offenen Netzwerk.
Ohne Berechtigungsnachweis wird nichts bereitgestellt
Jede Anfrage an den Endpunkt trägt einen Berechtigungsnachweis, und welchen, hängt davon ab, ob ein vorgeschalteter Proxy ihn bereits geprüft hat. Standardmäßig ist es ein Bearer-Token, das dieser Server selbst überprüft, beschrieben im Rest dieses Abschnitts. Setzen Sie mcp.authorization.trusted_proxy, und es ist stattdessen ein Header, den dieser Proxy setzt, beschrieben unter Den Aufrufer von einem vorgeschalteten Proxy lesen — wo überhaupt kein Token gelesen wird. Keine der beiden Formen bedient eine Anfrage, die nichts vorlegt.
Standardmäßig prüft der Server selbst ein Bearer-Token. Er liest das Token aus dem Header Authorization und akzeptiert es nur, wenn die Signatur gegen einen Schlüssel verifiziert wird, den der Autorisierungsserver veröffentlicht, das Token mcp.authorization.issuer als Aussteller nennt, es die eigene mcp.authorization.resource dieser Bereitstellung unter seinen Zielgruppen nennt, es innerhalb seines Gültigkeitszeitraums liegt und es angibt, wer es vorgelegt hat. Ein Token, das eine dieser Prüfungen nicht besteht, wird mit 401 beantwortet, wobei error="invalid_token" derselben Challenge hinzugefügt wird, die ein Aufrufer ohne Nachweis erhält — und die Antwort ist identisch, gleich welche Prüfung es abgewiesen hat, sodass ein Aufrufer erfährt, dass er ein anderes Token braucht, nicht aber, welcher Teil des gesendeten falsch war. Nur asymmetrische Signaturalgorithmen werden akzeptiert: Ein unsigniertes Token und eines, das einen symmetrischen Algorithmus nennt, werden abgewiesen, bevor etwas daraus gelesen wird.
Ein Token kann angeben, welche Art von Token es ist, und vier Formen werden akzeptiert. Ein JWT kann einen typ-Header tragen, der seinen eigenen Typ nennt. Dieser Server akzeptiert at+jwt und application/at+jwt, die beiden für ein Access Token registrierten Schreibweisen; JWT, das nur sagt, dass das Token ein JWT ist; und ein Token, das überhaupt keinen Typ deklariert. Alles andere wird mit 401 beantwortet, genau wie jedes andere abgewiesene Token. Die Menge ist fest, und keine Einstellung erweitert oder verengt sie, weil der Autorisierungsserver, der das Token ausgestellt hat, entscheidet, welche Form dort erscheint, und nicht die Bereitstellung, die es empfängt. Dass JWT akzeptiert wird, bedeutet zwar, dass der deklarierte Typ allein ein Access Token nicht mehr von einem Identity Token unterscheidet — die Zielgruppenprüfung unterscheidet sie, und deshalb ist diese Prüfung die tragende: Die Zielgruppe eines Identity Token ist der Client, für den es ausgestellt wurde, nie die eigene mcp.authorization.resource dieser Bereitstellung, sodass ein Token, das für etwas anderes als diese Bereitstellung ausgestellt wurde, abgewiesen wird, wie auch immer es sich selbst bezeichnet.
Welche Autorisierungsserver das zulässt. Microsoft Entra ID stellt Access Tokens vom Typ JWT aus. Keycloak stellt at+jwt aus, und JWT, wenn sein OpenID-Connect-Kompatibilitätsmodus aktiv ist. Auth0 stellt JWT unter seinem eigenen Token-Profil und at+jwt unter seinem RFC-9068-Profil aus. Ein Token von jedem dieser Server besteht diese Prüfung, gleich welche der beiden Formen es trägt. Okta wird nicht unterstützt: Seine Access Tokens deklarieren einen eigenen Typ, der keiner der vier oben genannten ist, daher weist dieser Server sie ab.
Ein abgewiesenes Token hinterlässt den Grund auf dem eigenen Fehlerstrom des Servers. Dem Aufrufer wird nur mitgeteilt, dass das Vorgelegte nicht akzeptiert wurde; der bereitstellende Prozess schreibt eine Zeile, die die Prüfung nennt, die das Token abgewiesen hat — die Zielgruppe, den Aussteller, den Gültigkeitszeitraum, die Signatur, die Schlüsselkennung, den deklarierten Typ und jede der anderen. Diese Zeile ist es, wodurch eine Bereitstellung, die jede Anfrage abweist, von demjenigen diagnostiziert werden kann, der sie betreibt, und nicht nur von demjenigen, der sie aufruft. Sie enthält keinen Teil des Tokens. Eine Anfrage ganz ohne Berechtigungsnachweis schreibt keine Zeile, weil die Challenge der Weg ist, auf dem ein Client überhaupt erst erfährt, wo er ein Token erhält; es ist also das Erste, was jeder korrekt arbeitende Client tut.
Ein Token gehört in den Header und nirgendwo anders hin. Eines, das als Query-Parameter access_token gesendet wird, wird mit 400 beantwortet und nie gelesen, weil eine Adresse von jedem Proxy-Log, jedem Browserverlauf und jedem Referrer-Header aufgezeichnet wird, den die Anfrage passiert; ein auf diesem Weg eingetroffenes Token ist also bereits offengelegt. Der Server schreibt nie ein Token in ein Log, sendet nie eines irgendwohin und beschafft oder tauscht nie eines im Namen eines Aufrufers: Er liest, was vorgelegt wurde, entscheidet und behält nichts davon. Das Subjekt, das das Token nennt, wird aufgezeichnet und mit nichts verglichen.
Die Prüfschlüssel stammen vom Autorisierungsserver oder aus einer von Ihnen genannten Datei. Ist mcp.authorization.jwks_file nicht gesetzt, liest der Server die Metadaten des Autorisierungsservers unter dessen Well-known-Adresse, folgt der dort veröffentlichten jwks_uri und hält die gefundenen Schlüssel vor; ein Token, das mit einer Schlüsselkennung signiert ist, die diese Schlüssel nicht enthalten, löst ein erneutes Lesen aus, und nicht mehr als eines innerhalb eines kurzen Intervalls, sodass ein Aufrufer, der erfundene Schlüsselkennungen sendet, keine ausgehende Anfrage pro Anfrage erzwingen kann. Das Lesen vom Autorisierungsserver erfordert eine https-Schlüsseladresse oder eine reine http-Adresse auf diesem Rechner: Eine jwks_uri, die reines http auf einem anderen Host ist, wird nie abgefragt, und einer Umleitung, die eines der beiden Lesevorgänge auf reines http auf einem anderen Host schicken würde, wird nicht gefolgt, weil jeder, der sich auf einem ungeschützten Weg zu den Schlüsseln befindet, mit eigenen Schlüsseln antworten könnte. Ein Token, das diese Schlüssel braucht, wird dann mit 503 beantwortet, genau wie bei Schlüsseln, die nicht gelesen werden können, und die Zeile, die der Server für diese Anfrage schreibt, sagt, dass das Lesen wegen reinem http abgewiesen wurde, und nicht, dass der Autorisierungsserver nicht erreichbar war — die Abhilfe liegt beim Autorisierungsserver, der seine Metadaten und Schlüssel über https veröffentlichen muss. Ist jwks_file gesetzt, werden die Schlüssel aus dieser Datei gelesen, und der Autorisierungsserver wird nie kontaktiert — das braucht ein Workspace, der offline: true deklariert, und ein solcher Workspace wird abgewiesen, bevor sich sein Listener bindet, sofern die Datei nicht genannt ist. Wo die Schlüssel überhaupt nicht gelesen werden können, werden Anfragen mit 503 ohne Challenge beantwortet: Nichts, was ein Aufrufer vorgelegt hat, wurde als unzureichend befunden, daher würde es nicht helfen, es mit einem anderen Token erneut zu senden.
Die einzige Antwort, für die keine Anmeldeinformation verlangt wird, ist das Metadatendokument der geschützten Ressource. Ein Client muss es lesen, bevor er ein Token besitzen kann, sodass eine Anforderung dort die einzige Tür hinein verschließen würde. Es wird unter /.well-known/oauth-protected-resource beantwortet und — wo die Adresse, die mcp.authorization.resource nennt, einen eigenen Pfad hat — zusätzlich unter diesem Well-known-Pfad mit angehängtem Pfad. Das sind die beiden Stellen, an denen ein Client nachsieht, und die Form mit angehängtem Pfad ist die Adresse, die die Challenge nennt. Das Dokument führt diese Adresse als die Ressource, unter der dieses Deployment angesprochen wird, mcp.authorization.issuer als den Autorisierungsserver, von dem ein Token zu beziehen ist, header als einzigen Weg, ein Token vorzulegen, und die drei unten genannten Scope-Namen.
Der Issuer ist eine https-Adresse, sofern der Autorisierungsserver nicht auf diesem Rechner läuft. Einfaches http wird für einen Issuer unter localhost, 127.0.0.1 oder ::1 akzeptiert, was die Form eines lokalen Tests mit einem lokalen Autorisierungsserver ist; ein Issuer mit einfachem http auf einem anderen Host wird abgelehnt, bevor der Listener gebunden wird, und die Ablehnung nennt mcp.authorization.issuer und verlangt eine https-Adresse. Das gilt in jedem Modus — mit den vom Issuer gelesenen Schlüsseln, mit mcp.authorization.jwks_file und mit einem vorgeschalteten Proxy —, weil jeder Modus den Issuer in diesem Dokument veröffentlicht: Ein Client, der ihm folgt, führt seinen Autorisierungsablauf gegen diese Adresse aus, sodass über einfaches http der Autorisierungscode und das damit bezogene Token ungeschützt über das Netzwerk gingen, ob dieser Server von dort jemals einen Schlüssel liest oder nicht. Wo er seine Schlüssel von dort liest, könnte zudem jeder auf diesem Weg mit eigenen Schlüsseln antworten, und jedes damit signierte Token würde zugelassen.
Die Scope-Namen, die dieses Deployment veröffentlicht, sind aggrega:read, aggrega:workspace-write und aggrega:registry-write. Das sind die Namen, die am Autorisierungsserver zu registrieren sind, und die Namen, die ein Client dort anfordert, und die Challenge, die ein abgelehnter Aufrufer erhält, nennt aggrega:read als den zuerst zu beziehenden. Was jeder davon zulässt — und die zweite Grenze, die dieses Deployment sich selbst setzt —, steht unten unter Was ein Aufrufer erreichen darf.
Den Aufrufer aus einem vorgeschalteten Proxy lesen
Wo ein vorgeschalteter Proxy Tokens bereits validiert, weist mcp.authorization.trusted_proxy diesen Server an, den Aufrufer von dort zu lesen, statt ein Token ein zweites Mal zu prüfen. Geben Sie principal_header an, den Header, den dieser Proxy setzt, um zu sagen, wer der Aufrufer ist, und optional scopes_header, einen zweiten Header, der die Scopes dieses Aufrufers durch Leerzeichen getrennt trägt. Beide sind HTTP-Header-Namen wie X-Forwarded-User, ohne Leerzeichen oder Doppelpunkt; ein Name in jeder anderen Form wird beim Laden der Konfiguration unter Nennung des Schlüssels abgelehnt, ebenso ein leerer principal_header — lassen Sie den Block weg, um diesen Modus ausgeschaltet zu lassen. Diese beiden Header sind die einzigen, die gelesen werden: Kein Forwarded-Address-Header und kein anderer Header wirkt mit. Eine Anfrage ohne den Principal-Header wird mit 401 beantwortet, und in diesem Modus wird überhaupt kein Token gelesen — eine Anfrage mit einem Token, das dieser Server sonst abgelehnt hätte, wird bedient, wenn ihr Principal-Header vorhanden ist, und eine mit einem Token, das dieser Server akzeptiert hätte, wird dennoch abgelehnt, wenn dieser Header fehlt.
Dieser Modus wird nur auf Loopback oder einem Unix-Socket akzeptiert, und der Prozess wird abgelehnt, bevor er sich anderswo bindet. Ein Header ist genau dann vertrauenswürdig, wenn nichts außer dem Proxy ihn setzen kann. Auf einer Adresse, die das Netzwerk erreicht, kann ihn alles setzen — ein Listener in diesem Modus auf einer solchen Adresse würde also jeden Aufrufer sich nennen lassen, wie er wollte. Die Ablehnung nennt beide Einstellungen, die in Konflikt stehen, sodass Sie sie aufheben können, indem Sie die Adresse verlegen oder den Block entfernen.
Was der Proxy behauptet, glaubt dieser Server, und das ist die Abmachung. Dieser Server prüft in diesem Modus keine Signatur und vergleicht den behaupteten Aufrufer mit nichts, genau wie er das Subject eines Tokens mit nichts vergleicht. Ob der Proxy validiert hat, was er weiterleitete, und ob irgendetwas diesen Listener erreichen kann, ohne den Proxy zu passieren, muss das Deployment richtig machen; die obige Beschränkung macht es möglich, das richtig zu machen, ist aber keine Garantie, dass es richtig gemacht wurde.
Das Setzen von mcp.authorization.trusted_proxy hebt die übrigen Anforderungen nicht auf. issuer und resource werden weiterhin benötigt, weil das Metadatendokument weiterhin veröffentlicht wird und die Challenge es weiterhin nennt — ein Client hinter dem Proxy muss weiterhin erfahren, wo er das Token bezieht, das der Proxy prüfen wird. Aus demselben Grund ist der Issuer weiterhin eine https-Adresse, sofern er nicht auf diesem Rechner läuft: Dieser Client bezieht sein Token vom Issuer, sodass ein Issuer mit einfachem http auf einem anderen Host in diesem Modus genau wie in jedem anderen abgelehnt wird, bevor der Listener gebunden wird, obwohl dieser Server nichts von ihm liest.
Was ein Aufrufer erreichen darf
Zwei Grenzen entscheiden, was ein Aufrufer über HTTP erreicht, und sie werden von unterschiedlichen Personen gesetzt. Die eigene Anmeldeinformation des Aufrufers ist die erste; was dieser Server überhaupt anbietet, ist die zweite. Beide werden gelesen, bevor irgendetwas ausgeführt wird, aus einer Deklaration, die jede Operation über sich selbst macht, und sie erreichen einen Client an unterschiedlichen Stellen: Die Tool-Liste zeigt, was dieser Server anbietet und ankündigt, und die Antwort, die jeder Aufruf erhält, zeigt, was die Anmeldeinformation zulässt.
Jede Operation deklariert, wie weit ihre eigenen Wirkungen reichen, und es gibt vier Arten, die weiteste zuletzt:
- Erreicht nichts — liest eine Definition, untersucht, was ein Release festlegt, rendert Artefakte im Speicher und gibt sie zurück. Sie hinterlässt nichts: Nichts wird geschrieben, und die Antwort ist alles, was sie erzeugt.
- Erreicht den Workspace — schreibt innerhalb des Workspace, den dieser Prozess bedient: die Lockdatei eines Release, den Artefakt-Cache, generierte Entitäten, ein bearbeitetes Dokument.
- Erreicht eine Registry — veröffentlicht, signiert oder hängt eine Rückzugsmarkierung an etwas bereits Veröffentlichtes. Was sie ändert, ist, was jeder Konsument dieser Registry auflöst, und nichts davon kann von jemandem zurückgeholt werden, der es bereits abgerufen hat.
- Erreicht den Rechner — ändert, was alle Workspaces auf dem Host gemeinsam nutzen, darunter den Speicher kompilierter Module, die allen gemeinsame Konfigurationsdatei und den Anmeldeinformationsspeicher. Ein Cache, den ein einzelnes Projekt in seinem eigenen Cache-Verzeichnis hält, gehört nicht zu dieser Art, und
cache-statusmeldet, welche dieser Arten jeder aufgeführte Cache trägt.
Die Art ist eine Eigenschaft der Operation und nicht des Tools, das sie anbietet, und sie umfasst, was die Operation hinterlässt — nicht, wohin eine Oberfläche die zurückgegebene Antwort legt. Das Rendern eines Release erzeugt Artefakte als Antwort und erreicht daher nichts; eine Kommandozeile, die diese Artefakte anschließend in ein von Ihnen genanntes Verzeichnis speichert, liefert diese Antwort aus, statt weiter zu reichen. Andersherum gelesen, nähme jede Operation, die mit Inhalten antwortet, die Art derjenigen Oberfläche an, die sie zufällig speichert, und die Art wäre überhaupt keine Eigenschaft der Operation mehr. Aus demselben Grund erreicht describe, wenn es eine Entität über ihre Registry-Referenz liest, nichts: Es kontaktiert diese Registry, um seine Antwort abzurufen, und hinterlässt nichts, weder in der Registry noch auf diesem Rechner, und welche Registrys es kontaktieren darf, ist unter Welche Anmeldeinformationen ein Aufruf verwendet beschrieben. Ein einzelner Aufruf kann dennoch weiter reichen als die Art seiner Operation, wo der Aufruf selbst einen Schreibvorgang verlangt: Ein mit write gesendeter Build speichert seine Artefakte im Workspace, den dieser Server bedient, sodass dieser Aufruf den Workspace erreicht, ebenso wie ein Build, der zuerst seine Abhängigkeiten auflöst.
Ein Scope lässt eine Art zu, und jeder Schreib-Scope schließt den Lese-Scope ein. aggrega:read lässt eine Operation zu, die nichts erreicht. aggrega:workspace-write lässt eine zu, die den Workspace erreicht, und schließt den Lese-Scope ein. aggrega:registry-write lässt eine zu, die eine Registry erreicht, und schließt ebenfalls den Lese-Scope ein. Ein Client fordert bei seinem Autorisierungsserver also den Schreib-Scope an, den er braucht, und muss nicht zusätzlich den Lese-Scope anfordern.
Kein Scope lässt die Art „Rechner“ zu, und keine Einstellung fügt einen hinzu. Die Operationen dieser Art werden nur von den Tools angeboten, die einen aggrega-Befehl in einem separaten Prozess ausführen, und ein über HTTP erreichter Server bietet keines davon an, aus dem oben unter Den Server über HTTPS erreichen genannten Grund. Führen Sie sie in einem Terminal auf dem Host aus.
Die Tool-Liste zeigt jedes Tool, das dieser Server anbietet und ankündigt, unabhängig davon, welche Scopes die aufrufende Anmeldeinformation hält, und die Anmeldeinformation entscheidet, welche davon ein Aufruf ausführen darf. describe-capabilities indiziert und definiert dieselbe Menge. Ein Aufruf, den die Anmeldeinformation nicht zulässt, wird mit 403 und error="insufficient_scope" in der Challenge beantwortet, die den einen Scope nennt, der ihn zulassen würde, und nichts von dem, was der Aufruf verlangt hat, wurde ausgeführt. Diese Ablehnung ist diejenige, auf die das Step-up des Protokolls antwortet: Ein Client, der Step-up implementiert, bittet Sie, sich für den Scope, den die Challenge nennt, erneut anzumelden. Die Liste ändert sich nicht mit der Anmeldeinformation, sodass ein Client, der sich erneut angemeldet hat, bereits die richtige hält. Eine Anmeldeinformation, die keinen der drei Scopes trägt, erhält dieselbe Tool-Liste und kann keines der darin enthaltenen Tools aufrufen, describe-capabilities eingeschlossen.
Ein Build ist der Fall, den man kennen sollte. Für sich genommen ändert er nichts und braucht daher nur aggrega:read, aber ein Build, der schreibt, braucht aggrega:workspace-write: Einer, der mit write gesendet wird, speichert seine Artefakte nach dist/ im Workspace-Stammverzeichnis, und einer, der zuerst seine Abhängigkeiten auflöst, schreibt die Lockdatei — ob der Aufruf das mit auto_pull verlangt hat oder die eigene auto_pull-Einstellung des Workspace. Das Tool wird einem Aufrufer mit Lese-Scope wie jedes Tool aufgeführt, und die Builds, die im Speicher bleiben, stehen ihm tatsächlich zur Verfügung; abgelehnt wird, unter Nennung von aggrega:workspace-write, der Aufruf, der schreibt.
Einem Client, der kein Step-up durchführt, können die Schreib-Scopes dennoch gegeben werden, und das wird am Autorisierungsserver geregelt. Wer den Autorisierungsserver betreibt, macht die Schreib-Scopes zu Standard-Scopes für diesen Client — Scopes, die er in jedes Token schreibt, das er diesem Client ausstellt, ob der Client sie angefordert hat oder nicht —, sodass das Token, das seine erste Anmeldung bezieht, sie bereits trägt. Ein Client, der sich bei jeder Verbindung neu beim Autorisierungsserver registriert, ist dort jedes Mal ein neuer Client, und eine bei einer früheren Registrierung vorgenommene Einstellung wird nicht übernommen; für einen solchen Client gilt als Einstellung die Menge der Standard-Scopes, die der Autorisierungsserver jedem Client gibt, den er registriert. Der Preis ist, dass jede Anmeldung über diesen Client dann Schreibreichweite trägt, ob die anstehende Arbeit sie braucht oder nicht — und wo die Standardwerte die bei der Registrierung vergebenen sind, trägt jeder auf diese Weise registrierte Client diese Reichweite ebenfalls. Machen Sie nur den Schreib-Scope zum Standard, den diese Arbeit braucht: aggrega:workspace-write und aggrega:registry-write lassen unterschiedliche Arten zu, und keiner schließt den anderen ein.
mcp.deny_reach ist die Stelle, an der der Betreiber dieses Servers ihm eine Art entzieht, und es ist eine der beiden Einstellungen, die die Tool-Liste verkürzen. Führen Sie die Arten auf — none, workspace, registry, machine —, die dieser Server nicht anbietet, und jedes Tool, das eine davon erreicht, fehlt in der Tool-Liste jedes Aufrufers und in describe-capabilities, gleichgültig, was das Token dieses Aufrufers sagt, und wird, falls es dennoch aufgerufen wird, mit einem Fehler abgelehnt, der diese Einstellung nennt. Es ist die eigene Grenze des Servers und nicht die des Aufrufers, sodass keine Anmeldeinformation sie aufhebt und die Ablehnung keine Challenge trägt: Ein Server, der nur Lesezugriffe bedienen soll und sonst nichts, führt hier workspace, registry und machine auf und kann dann selbst für einen Aufrufer, dessen Token alle drei Scopes trägt, nicht veröffentlichen. Lassen Sie sie weg, was der Standard ist, dann entzieht dieser Server keine Art, und welche Arten ein Aufruf erreicht, entscheiden die eigenen Scopes des Aufrufers. machine anzugeben wird akzeptiert und ändert nichts, da hier von vornherein nichts dieser Art angeboten wird. Ein Wert, der keiner der vier ist, wird beim Laden der Konfiguration abgelehnt, statt übergangen zu werden — ein Betreiber, der eine Art falsch schreibt, hat eine Grenze verlangt, und stillschweigend ohne sie bedient zu werden, ist die falsche Antwort darauf.
mcp.announce_tools ist die andere Einstellung, die die Tool-Liste verkürzt, und die beiden sind nicht dieselbe Grenze. deny_reach entzieht eine Fähigkeit: Eine Operation einer dort genannten Art wird hier für niemanden angeboten. announce_tools entzieht nur eine Ankündigung: Die Tools, die es auslässt, sind Fähigkeiten, die dieser Server weiterhin hat, und es beantwortet die eigene Obergrenze eines Clients dafür, wie viele Tools er registriert. Wo beide gesetzt sind, gewinnt der Entzug, sodass ein Tool einer entzogenen Art fehlt, wie auch immer announce_tools es nennt, und die Ablehnung, auf die ein Aufrufer trifft, nennt den Entzug. Nichts, was die Liste verkürzt, liest die Scopes des Aufrufers: Ein Scope, der dem Aufrufer fehlt, lehnt einen Aufruf ab und entfernt niemals ein Tool aus der Liste. Eingrenzen, was der Server ankündigt beschreibt den Rest.
Welche Anmeldeinformationen ein Aufruf verwendet
Schlüsselloses Signieren über einen Listener bezieht seine Identität aus dem identity_token, das der Aufruf trägt, und aus nichts anderem. Ein im Aufruf gesendetes Token ist eine Anmeldeinformation, die der Aufrufer hält: Er musste es beziehen, es ist an ihn gebunden, und die damit erzeugte Signatur ist ihm zuzurechnen. Jede andere Quelle, aus der eine Identität kommen könnte, gehört demjenigen, der diesen Prozess gestartet hat, sodass die Auflösung auf diesem Transport eine Umgebung erhält, die nichts beantwortet. AGGREGA_IDENTITY_TOKEN und SIGSTORE_ID_TOKEN in der Umgebung des Servers werden nicht gelesen, und der umgebende OIDC-Endpunkt von GitHub Actions wird nicht erreicht. Sie sind unerreichbar und nicht bloß nicht empfohlen — es gibt für die Auflösung nichts zu finden. Ein Aufruf, der kein identity_token sendet, wird abgelehnt, und die Ablehnung nennt identity_token als das, was zu senden ist, und nennt weder eine Variable noch einen Endpunkt: Ein Aufrufer, der nicht an der Tastatur dieses Rechners sitzt, kann hier nichts exportieren, sodass die Nennung einer solchen ihn aufforderte, etwas einzurichten, das die Antwort nicht ändern kann.
Ein auf diesem Rechner gehaltener Signaturschlüssel kann auf keinem der beiden Wege ausgewählt werden. key_path wird abgelehnt, bevor irgendetwas aufgelöst wird, und fehlt in den Argumentschemata, die publish-entity, sign-artifacts und deprecate-artifact hier anbieten, sodass einem Aufrufer nie ein Argument angeboten wird, das nicht erfolgreich sein könnte. Auch der Signaturschlüssel, den die eigene Konfiguration des bedienten Workspace nennt, wird nicht erreicht — signing.key_path, ob für den Workspace als Ganzes gesetzt, für eine einzelne Registry gesetzt oder aus der Umgebung geliefert. Ein Grund deckt beides ab: Ein Schlüsselpfad ist keine Anmeldeinformation, sondern ein Name für ein Geheimnis, das dieser Server hält. Ein Aufrufer, der einen angibt, beweist nichts, jeder, der diese Adresse erreicht, könnte denselben Namen angeben, und die folgende Signatur würde besagen, dass der Betreiber für das Artefakt bürgt und nicht der Aufrufer. Das Argument zu schließen und die Konfiguration offen zu lassen, hieße, eine Tür zu einem Raum zu schließen, den die andere weiterhin öffnet. Signieren mit Schlüssel ist über einen Listener daher unerreichbar: Nur ein im Aufruf gesendetes Token signiert.
fulcio_url, rekor_url und timestamp_url sind nicht betroffen und bleiben auf beiden Transporten verfügbar. Sie nennen zu kontaktierende Dienste und nichts, was dieser Rechner hält, sodass ein Aufrufer, der keinen Schlüssel auswählen kann, dennoch gegen die Endpunkte signiert, die dieses Deployment konfiguriert.
Ein Listener, der über einem Workspace gestartet wird, der einen Signaturschlüssel nennt, sagt das einmal beim Start. Der Prozess schreibt eine Zeile in seinen eigenen Fehlerstrom, die die Einstellung nennt und besagt, dass ein Aufrufer, der diesen Listener erreicht, diesen Schlüssel nicht verwenden kann — so erfährt ein Betreiber es von dem Prozess, den er gestartet hat, und nicht aus einer Signatur, die er nicht erwartet hat. Ein Workspace, der keinen Schlüssel nennt, erzeugt keine solche Zeile, weil es darüber nichts zu sagen gibt. Die Zeile trägt den Namen der Einstellung und weder den Schlüssel noch irgendetwas über die Datei, auf die sie verweist.
Über Standardeingabe und -ausgabe gilt nichts davon. Dort wird die Umgebung gelesen, und key_path wählt einen auf diesem Rechner gehaltenen Schlüssel aus, weil der Client, der diesen Server gestartet hat, auf dem eigenen Rechner des Aufrufers läuft und das, was dieser Prozess erreichen kann, diesem Aufrufer selbst zur Verwendung gehört.
Das Lesen einer Entität über ihre Registry-Referenz kontaktiert eine einzige Registry, mit der eigenen Anmeldung dieses Hosts, und über einen Listener nur eine Registry, mit der der bediente Workspace konfiguriert ist. describe, dem eine oci://-Referenz als name gesendet wird, liest die an dieser Koordinate veröffentlichte Entität — derselbe Lesevorgang, den aggrega inspect ausführt — aus der einen Registry, die die Referenz nennt, mit der Anmeldung, die dieser Host für diese Registry bereits hält. Der Aufruf trägt keine Anmeldeinformation, und describe nimmt keine entgegen. Über HTTP muss die Registry eine sein, mit der der bediente Workspace konfiguriert ist: der Host, den sein default_registry nennt, oder ein unter registries aufgeführter Host, exakt und mit Port verglichen. Eine Referenz auf einen anderen Host — eine Adresse auf diesem Rechner eingeschlossen — wird abgelehnt, bevor dieser Host kontaktiert wird, und die Ablehnung nennt den Host, sodass ein Aufrufer diesen Server nicht auf ein Ziel seiner Wahl richten kann. Was erreichbar bleibt, ist beabsichtigt: Ein Aufrufer mit aggrega:read kann alles lesen, was die Anmeldung dieses Hosts auf einer Registry lesen kann, mit der der Workspace konfiguriert ist, und das ist auch das, was eine Person am Terminal dieses Hosts lesen kann. Über Standardeingabe und -ausgabe wird eine Referenz auf jede Registry gelesen, wie auf der Kommandozeile. Das Beschreiben einer Entität über ihren Katalognamen ist nicht betroffen.
Ein Registry-Aufruf verwendet den Anmeldeinformationsspeicher des Betriebssystembenutzers, unter dem dieser Prozess läuft, genau wie derselbe Aufruf in einem Terminal auf diesem Host. Es gibt keine Anmeldeinformationsquelle pro Workspace und keine Einstellung, die eine hinzufügt, weshalb registry-list den Anmeldestatus eines Hosts in jedem Workspace auf diesem Rechner gleich meldet. Ein Deployment, das möchte, dass verschiedene Workspaces verschiedene Registry-Anmeldeinformationen halten, führt sie als verschiedene Betriebssystembenutzer aus — ein Prozess pro Workspace, jeder als eigener Benutzer gestartet. Daher kommt die Trennung, und sie einzurichten ist Sache des Betreibers.
Was der Server aufzeichnet
Jede Anfrage, die dieser Endpunkt beantwortet, hinterlässt eine Zeile im Fehlerstrom des Prozesses, und diese Zeile ist ein einzelnes JSON-Objekt. Sie trägt die time, zu der sie geschrieben wurde, und eine request_id, die dieser Prozess für den Aufruf erzeugt hat und nicht an den Aufrufer zurücksendet; subject und issuer, wie die vorgelegte Anmeldeinformation sie behauptet hat, mit client_id, wo sie einen nannte; workspace_root, den Workspace, den dieser Prozess bedient; method und target, wo die Methode etwas über einen Namen anspricht; reach, die Art, die die Operation deklariert, und reach_escalated_to, wo der Aufruf weiter reichte; outcome; duration_ms; und transport. Ein Feld, das nichts zu sagen hat, wird weggelassen, statt leer geschrieben zu werden, sodass eine fehlende client_id eine Anmeldeinformation ist, die keinen Client nannte, und ein fehlendes reach_escalated_to ein Aufruf, der genau das erreichte, was seine Operation deklariert.
outcome sagt, was aus dem Aufruf wurde, und die Werte sind unterschiedlich, damit Sie sie getrennt zählen können. ok wurde ausgeführt und war erfolgreich. tool-failure wurde ausgeführt und kam als ein Fehler gekennzeichnet zurück, den der Aufrufer beheben kann — ein Aufruf, den dieser Server bedient und nicht abgelehnt hat, sodass er nicht zu Ihren Ablehnungen gehört. error ist eine Ablehnung, die als Fehler-Envelope des Protokolls zurückgegeben wird. unauthenticated, forbidden und rate-capped sind die Anmeldeinformation, die Herkunfts- oder Scope-Grenze und die Ratenbegrenzung pro Aufrufer, die eine Anfrage abweisen. cancelled ist ein Aufrufer, der seine Verbindung geschlossen hat, bevor er eine Antwort erhielt.
Der Grund, aus dem eine abgelehnte Anmeldeinformation abgewiesen wurde, ist ein Feld derselben Zeile und keine eigene Zeile. Eine abgelehnte Anfrage hinterlässt einen Datensatz wie jede andere, wobei refusal die Prüfung nennt, die sie abgewiesen hat. Keine Anmeldeinformation und kein Teil davon gelangt in irgendeine Zeile — weder bei einer Ablehnung noch bei einem bedienten Aufruf.
Ein Aufrufer, der überhaupt nichts vorgelegt hat, hinterlässt keine Zeile. Eine Challenge zu erhalten ist der Weg, auf dem ein Client herausfindet, wo er ein Token bezieht, also ist es das Erste, was jeder sich korrekt verhaltende Client tut, und eine Zeile für jeden dieser Fälle würde die Ablehnungen begraben, die etwas bedeuten. Auch eine Anfrage, die einen Pfad oder eine Methode nennt, die dieser Endpunkt nicht bedient, hinterlässt keine: Beides wird entschieden, bevor irgendetwas über einen Aufrufer gelesen wird, sodass das Abtasten der Adresse nichts in das schreibt, was den Strom sammelt.
Trace-Kontext, den ein Client sendet, wird wörtlich in die Zeile kopiert. traceparent und daneben tracestate und baggage, wo diese ebenfalls gesendet werden, werden genau so übernommen, wie sie empfangen wurden, sodass das, was diesen Strom sammelt, ihn mit den eigenen Aufzeichnungen des Aufrufers verknüpfen kann. Eine Anfrage, die keinen sendet oder einen sendet, der kein wohlgeformter W3C-Trace-Kontext ist, erzeugt eine Zeile ohne diese Schlüssel: Nichts wird erfunden, und nichts wird unterwegs verändert.
Der Prozess zeichnet sein eigenes Leben in derselben Form und im selben Strom auf, wobei jede dieser Zeilen ein event nennt, wo eine Anfragezeile eine Methode und einen Aufrufer nennt: startup beim Beginn, listening mit der gebundenen Adresse, startup-refused mit dem Grund, aus dem ein Start abgelehnt wurde, bevor er bediente, signing-key-ignored, wo der bediente Workspace einen Signaturschlüssel nennt, den kein Aufrufer, der diesen Listener erreicht, verwenden kann, docs-bundle mit dem Ergebnis des Beziehens des Dokumentationsbundles und shutdown am Ende des Laufs. Am Vorhandensein von event werden die beiden Arten von Zeilen unterschieden.
Sie sammeln alles aus dem Fehlerstrom des Prozesses, und das ist die gesamte Auslieferung. Es gibt keinen Exporter zu konfigurieren, keine Datei zu nennen und keine Einstellung, die irgendetwas davon ein-, aus- oder umschaltet: Was diesen Prozess überwacht — eine Container-Runtime, ein Dienstmanager, ein Log-Shipper —, ist das, was diesen Strom sammelt, und der Ort, an dem Sie ihn anschließend abfragen. Über Standardeingabe und -ausgabe trägt derselbe Strom stattdessen lesbaren Fließtext, weil der Client, der ihn liest, den Prozess gestartet hat und auf demselben Rechner sitzt.
Nichts davon wird an den Aufrufer gesendet. Der Server veröffentlicht auf keinem der beiden Transporte einen Log-Strom über das Protokoll, und eine Anfrage, die das Log-Level-Feld pro Anfrage des Protokolls trägt, wird genauso beantwortet wie eine, die es nicht trägt: Was hier aufgezeichnet wird, gehört dem Betreiber und geht allein in den Strom des Betreibers.
Was der Server dem Modell beim Verbinden mitteilt
Der Server bietet einen Block mit Hinweisen für das Modell an, den Ihr Client ihm vor dem ersten Aufruf vorlegen kann. Ein Client auf 2026-07-28 liest ihn aus der Antwort auf server/discover; ein Client auf 2025-06-18 liest ihn aus der Antwort auf seinen initialize-Handshake. Es ist auf beiden Wegen derselbe Text, Byte für Byte, und derselbe Text für jeden Client, der einen Prozess erreicht: Nichts darin wird ausgehandelt, und nichts wird aus dem abgeleitet, was der Client gesendet hat, oder aus der Anmeldeinformation, die er vorgelegt hat, sodass das, was einem Modell beim Verbinden gesagt wird, weder zwischen Sitzungen noch zwischen Clients variiert.
Zwei Dinge variieren, und keines davon ist der Client. Der abschließende Absatz wird für den Transport zusammengestellt, den ein Prozess bedient, sodass ein Server, der über Standardeingabe und -ausgabe spricht, und ein Listener einem Modell unterschiedlichen Schlusstext übergeben. Und wo das Desktop-Bundle, das einen Server gestartet hat, aus einer anderen Version stammt als die ausführbare Datei aggrega, die es gestartet hat, beginnen die Hinweise mit dem einen Satz, der das sagt und beide Versionen nennt — dem Satz, mit dem die argumentlose Antwort von describe-capabilities beginnt, wie Aus welcher Version der Server stammt beschreibt; ein Start, den kein Bundle ausgelöst hat, und einer, dessen Bundle aus der Version der ausführbaren Datei selbst stammt, übergeben die Hinweise ohne ihn. Beides wird beim Start des Prozesses festgelegt, und innerhalb jedes Prozesses liefern die beiden Revisionen dennoch identisch den eigenen Text dieses Prozesses.
Er vermittelt das mentale Modell, das das Argumentschema eines Tools allein nicht vermitteln kann:
- Was der Compiler tut und was er bewusst nicht tut — dass er Text weiterleitet und Label-Übereinstimmungen auswertet, statt zu interpretieren, was ein Wert bedeutet, dass er meinungslos gegenüber den Inhalten ist, die Sie in Ihre Dokumente schreiben, und dass er sich beim Kompilieren nie bei einem Anbieter authentifiziert, nie den Zustand eines Clusters liest und nie ein Geheimnis in Klartext verwandelt. Ein Wert, der erst existiert, wenn die Infrastruktur läuft, wird als Zeigerzeichenkette durchgereicht, die die Zielumgebung später ausfüllt.
- Das Authoring-Vokabular und wie die Arten zusammenhängen — wozu jede Art dient und gegen welche ein Build tatsächlich ausgeführt wird, sodass ein Assistent die Form eines Deployments nicht aus der Tool-Liste ableiten muss.
- Die Reihenfolge, in der die Authoring-Schleife abläuft — den Vertrag lesen, daraus ein Gerüst erzeugen, untersuchen, womit Sie verbinden, und dann vor dem Rendern prüfen.
- Wann ein Prompt statt eines Tools angebracht ist — ein Tool zum Handeln, ein Prompt, um eine Aufgabe einzurahmen.
- Dass die Tool-Liste die gesamte Oberfläche ist — jedes Tool, das dieser Server anbietet, ist darin enthalten, und welche Tools ein Server anbietet, hängt davon ab, wie er eingerichtet wurde, sodass ein Assistent aus dieser Liste und aus
describe-capabilitiesliest, was hier ist, statt nach einer zweiten zu suchen. Wo die Verbindung eine Anmeldeinformation vorgelegt hat, sagt er, dass die Anmeldeinformation entscheidet, welche dieser Tools ein Aufruf ausführen darf, und nie, welche davon aufgeführt werden: Ein Aufruf, den sie nicht zulässt, wird unter Nennung des Scopes abgelehnt, der ihn zulassen würde, und der Client kann sich für diesen Scope erneut anmelden. - Was ein leerer Workspace bedeutet und was das Modell dagegen tun darf — der Absatz, der sich je nach Transport unterscheidet, siehe unten.
Er nennt die Oberflächen, statt sie zu wiederholen. Jedes Tool trägt bereits seine eigene Beschreibung und sein Argumentschema in tools/list, und der Vertrag jeder Art steht bereits in ihrem Schema und auf ihrer Referenzseite, sodass die Hinweise darauf verweisen und aufhören — ein Ort pro Aussage. Ein Tool, das sie nennen, ist ein Tool, das der Server bedient, und sie verweisen auf jede Ressourcenfamilie, die die Leseoberfläche auflöst, sodass nichts, wohin sie einen Assistenten schicken, eine Sackgasse ist.
Er enthält keinen Index der Tools selbst, und das ist dieselbe Regel und keine Auslassung daraus. Ein Client hält die Definition jedes Tools aus tools/list, bevor er ein Wort dieses Textes liest, sodass eine Zeile pro Tool hier eine zweite Kopie von Zwecken wäre, die er bereits hat — bezahlt in jeder Sitzung, von jedem Client, und frei, von der Tool-Liste abzuweichen, sobald eines von beiden bearbeitet wird.
Er sagt auch, was er nicht aufzählt, und warum: Die verfügbaren Render-Ziele und die installierten Bibliotheksarten sind Eigenschaften Ihrer Plug-ins und Ihres Schemasatzes, sodass die Ressourcenoberflächen sie direkt melden, statt dass die Hinweise eine Kopie tragen, die abweichen könnte.
Was einem Modell über einen leeren Workspace gesagt wird
Der abschließende Absatz beantwortet die Frage, auf die ein Modell bei einem Workspace, der nichts enthält, zuerst trifft: was ein leeres list-entities bedeutet und was es dagegen tun darf. Sein Anfang ist auf beiden Transporten derselbe — eine leere Auflistung bedeutet, dass der Workspace, den dieser Prozess aufgelöst hat, keine Aggrega-Dokumente enthält, die er lesen kann, und dass auch die daneben konfigurierten Katalogverzeichnisse keine deklarieren —, und was folgt, hängt davon ab, welchen Transport dieser Prozess bedient, weil die ehrliche Antwort auf den beiden nicht dieselbe ist.
Über Standardeingabe und -ausgabe wird dem Modell gesagt, dass es den Workspace untersuchen und reparieren darf. Ihm wird gesagt, wo ein Aufruf beantwortet wird, der keinen Workspace nennt — in dem Ordner, mit dem der Server gestartet wurde, wo er mit einem gestartet wurde, und andernfalls in dem Workspace, der von dem Ordner aus gefunden wird, in dem er gestartet wurde, was dieser Ordner selbst sein kann —, und dass workspace_root bei einem Aufruf einen anderen nennt. Es wird auf config-show für die geltende Konfiguration und die Ebene, die jede Einstellung entschieden hat, verwiesen und auf cli-config-init, um eine funktionierende anzulegen; beide stehen auf diesem Transport in der Tool-Liste. Der Client, der den Server ausführt, befindet sich auf dem eigenen Rechner des Aufrufers, sodass das, was dieser Prozess erreichen kann, diesem Aufrufer selbst zur Verwendung gehört — und wo Sie die Grenze setzen, ist dort, wo sie für jedes andere Tool gesetzt wird, in Ihrem MCP-Client, wie Was ein Assistent tun kann, ohne Sie vorher zu fragen beschreibt.
Über HTTP wird dem Modell gesagt, zu berichten statt zu konfigurieren. Der Workspace ist derjenige, über dem Sie den Prozess gestartet haben, und bleibt für dessen Lebensdauer fest; ein Aufruf, der workspace_root oder catalog_dirs nennt, wird unter Nennung des Arguments abgelehnt; und kein Tool, das Konfiguration schreibt, wird hier irgendeinem Aufrufer angeboten, gleich welche Scopes seine Anmeldeinformation trägt. Diese Operationen werden nur von den Tools angeboten, die einen aggrega-Befehl in einem separaten Prozess ausführen, und eine über HTTP erreichte Sitzung wird ohne sie zusammengestellt — die Grenze ist also die Zusammenstellung und nicht ein Scope, und kein Token erweitert sie. Ein Modell, das Ihr Deployment über einen Listener erreicht, kann daher auf Ihrem Host weder eine Registry anlegen noch eine Vertrauensrichtlinie umschreiben, und der Absatz sagt ihm das, statt es versuchen und die Ablehnung lesen zu lassen.
Was ein Assistent tun kann, ohne Sie vorher zu fragen
Ein Assistent, der über Standardeingabe und -ausgabe mit diesem Server verbunden ist, kann jedes Tool aufrufen, das der Server bereitstellt, ohne Sie zu fragen, sofern Ihr Client nicht so konfiguriert ist, dass er es verweigert. Auf diesem Transport bietet der Server die Tools an und entscheidet nicht, welche davon ein bestimmter Aufruf verwenden darf: Diese Entscheidung liegt bei Ihrem Client, und Sie treffen sie dort. Über HTTP ist es nicht dasselbe: Der Server führt jedes Tool auf, das er anbietet und ankündigt, und lehnt einen Aufruf ab, den die Scopes des aufrufenden Tokens nicht zulassen, sodass die Grenze sowohl beim Server als auch beim Client liegt.
Das ist wichtig, weil die Tool-Oberfläche die Kommandozeile ist. Alles, was Sie eintippen können, kann ein Assistent aufrufen — einschließlich der Operationen, die Ihren Rechner verändern.
Einige dieser Operationen reichen über den Workspace hinaus, in dem Sie arbeiten, und lassen sich nicht rückgängig machen, indem man etwas anderes ausführt. Diese sollte man beim Namen kennen, die mit der weitesten Reichweite zuerst:
publish-entity,publish-artifact,sign-artifactsunddeprecate-artifactreichen vollständig über den Rechner hinaus. Sie legen Bytes, eine Signatur oder eine Rückzugsmarkierung in einer Registry ab, sodass das, was sie ändern, das ist, was jeder Konsument dieser Registry auflöst — nicht nur das, was dieser Rechner tut. Das erneute Veröffentlichen anderer Inhalte über einem Tag wird abgelehnt statt angeboten, sodass nichts hier eine Veröffentlichung zurücknimmt; die Antwort ist, eine neue Version zu veröffentlichen. Eine Signatur und eine Rückzugsmarkierung lassen die Bytes des Artefakts unberührt, aber jeder, der dieses Artefakt danach abruft, ruft sie ebenfalls ab, und keines von beiden kann von jemandem zurückgeholt werden, der es bereits hat. Über Standardeingabe und -ausgabe sind dieselben vier Fähigkeiten auch alscli-push,cli-push-artifact,cli-signundcli-deprecateerreichbar, die die Befehle ausführen; über HTTP gibt es diese vier Tools nicht.- Signieren verwendet Anmeldeinformationen. Über Standardeingabe und -ausgabe bezieht schlüsselloses Signieren ein Identitätstoken aus dem Argument
identity_tokendes Aufrufs, ausAGGREGA_IDENTITY_TOKENoderSIGSTORE_ID_TOKENin der Umgebung des Servers oder aus dem umgebenden OIDC-Endpunkt von GitHub Actions, wo einer erreichbar ist;key_pathwählt stattdessen einen offline gehaltenen Schlüssel aus. Ein Assistent, der diese Tools aufrufen kann, kann daher als Sie signieren, mit welcher Identität auch immer der Rechner, auf dem der Server läuft, bereits ausgestattet ist — und eine Signatur ist eine Aussage darüber, wer für ein Artefakt bürgt, weshalb dies die Operation ist, über die man am gründlichsten nachdenken sollte, bevor man sie erlaubt. Über einen Listener signiert nur ein im Aufruf gesendetes Token: Nichts in der Umgebung des Servers wird gelesen, und kein auf dem Host gehaltener Schlüssel kann über ein Argument oder über die Konfiguration des bedienten Workspace ausgewählt werden, wie Welche Anmeldeinformationen ein Aufruf verwendet beschreibt. aggrega cache evictverkleinert den Speicher kompilierter Module, undaggrega cache clearleert ihn. Dieser Speicher wird von jedem Aggrega-Projekt auf dem Rechner gemeinsam genutzt. Daraus entfernte Module werden bei Bedarf neu kompiliert, sodass nichts dauerhaft verloren geht — aber der nächste Build jedes Projekts trägt diese Kosten.aggrega cache clearentfernt außerdem das Dokumentationsbundle, das jedes Projekt auf dem Rechner liest und das erneut abgerufen wird, wenn eines von ihnen es das nächste Mal bezieht.aggrega cache prunegibt Einträge des Artefakt-Caches frei, auf die keine Lockdatei verweist. Wo die Lockdatei eines Projekts nicht zum Lesen vorhanden ist, sind dessen festgelegte Artefakte nicht durch sie geschützt, und sie freizugeben bedeutet, sie erneut abrufen zu müssen.aggrega registry addundaggrega registry removeschreiben standardmäßig in die Konfiguration, die alle Workspaces gemeinsam nutzen, sodass sie ändern, was überall auf dem Rechner aufgelöst wird, nicht nur hier.aggrega registry addfragt außerdem die genannte Registry nach der Vertrauensrichtlinie, die diese Registry anbietet, und legt fest, was es erhält, genau wie in einem Terminal. In einem Offline-Workspace wird dieser Abruf abgelehnt, bevor irgendeine Verbindung aufgebaut wird, sodass das Hinzufügen einer anderen Registry als des offiziellen Hubs abgelehnt wird — KurzcodeE0310, mit demselben Wortlaut —, sofern der Aufruf nichtidentityoderkeyangibt;aggrega config init, das keines von beiden entgegennimmt, kann offline nur den Hub anlegen. Über Standardeingabe und -ausgabe sind sie alscli-registry-addundcli-registry-removeerreichbar und das Anlegen alscli-config-init, die die Befehle ausführen; über HTTP gibt es diese Tools nicht.pullliest aus einer Registry und schreibt innerhalb des Workspace, auf den es gerichtet ist. Es schreibt die Lockdatei dieses Release, füllt den Artefakt-Cache mit dem, was es aufgelöst hat, und zeichnet neben der Lockdatei die Identität jedes Verdikt-liefernden Plug-ins auf, das Ihr Workspace anhängt. Mitpin_sourcesgesendet — oder in einem Workspace, in dempin_sources_at_pulleingeschaltet ist, und bei einem Aufruf, der es nicht als false sendet — führt es außerdem den Pin-Schritt des Entitätsautors über die Recipes und FeatureRecipes aus, die das Release aus Ihren Katalogverzeichnissen baut, und schreibt jeweils daneben dieentity.lock; ohne ihn wird ein Pull über eine solche Entität, deren Lock für eine von ihr gelesene Eingabe keinen Pin verzeichnet, unter Nennung des Schritts abgelehnt. Die Entitätsdateien selbst werden nie geschrieben. Nichts davon verlässt den Rechner, und erneutes Auflösen ist der Weg, das Aufgezeichnete zu ändern, sodass dies die mildeste der hier genannten schreibenden Operationen ist. Es ist eines der für die Authoring-Schleife gestalteten Tools, die innerhalb des Workspace schreiben:pinschreibt dieentity.lockneben das Recipe oder FeatureRecipe, das Sie nennen, wie Die eigenen Eingaben einer Entität festlegen beschreibt;gen-catalogschreibt generierte Plugin-Entitäten in das Verzeichnis, das Sie nennen;edit-documentwendet eine begrenzte strukturierte Bearbeitung auf ein Dokument an, das Sie bereits haben, und schreibt es zurück, wobei jedes Byte erhalten bleibt, das die Bearbeitung nicht berührt, wie Eine begrenzte Bearbeitung auf ein Dokument anwenden beschreibt; undimportwandelt eine von einem anderen Tool erzeugte Beschreibung in Entwurfs-Authoring-Dateien um und schreibt sie in den Workspace, wie Eine fremde Beschreibung in Entwurfsentitäten umwandeln beschreibt; undscaffoldschreibt, mitexamplegesendet, eines der ausführbaren Beispiele der Dokumentation in ein neues oder leeres Verzeichnis,dir, wie esaggrega scaffold --exampletut, was über HTTP der Scope für Schreibzugriffe auf den Workspace zulässt. Dieses Ausgabeverzeichnis, der Guest, dengen-catalogliest, und jedes Overlay, das Sie ihm geben, sind jeweils relativ zum Workspace-Stammverzeichnis oder über Standardeingabe und -ausgabe absolut — derselbe Vertrag, den jedes andere Pfadargument auf dieser Oberfläche verwendet. Über Standardeingabe und -ausgabe ist dieselbe Fähigkeit auch alscli-pullerreichbar, das den Befehl ausführt; über HTTP gibt es dieses Tool nicht.buildliest dieselbe Registry und führt denselben Schreibvorgang aus, wenn Sie ihmauto_pullsenden, und nur dann. Das Auflösen der Abhängigkeiten eines Release ist eine einzige Operation, wo immer sie verlangt wird, sodass ein Build, der zuerst auflösen soll, genau das tut, waspulltut, und dann gegen das rendert, was er geschrieben hat — weshalb er dieselbe Reichweite trägt und keine geringere. Mitwritegesendet, schreibt er außerdem die gerenderten Artefakte nachdist/im Workspace-Stammverzeichnis, wohinaggrega buildsie schreibt, und über denselben Schreibvorgang, sodass er für diesen Aufruf den Workspace erreicht; er schreibt nirgendwo sonst hin, und eindist, das ein aus dem Workspace hinausführender Link ist, wird abgelehnt, bevor darin irgendetwas entfernt oder geschrieben wird. Ohne eines der beiden Argumente, was der Standard ist, rendertbuildaus den Pins, die der Workspace bereits hält, und erreicht nichts. Lesen Sie Gegen die Inhalte bauen, die ein Release bereits festlegt, um zu erfahren, was das Argument ändert und was es unberührt lässt.
Die Inventar-Tools sagen es in ihren eigenen Antworten. cache-status kennzeichnet jede Cache-Klasse mit ihrer Reichweite — workspace für den Artefakt-Cache im eigenen Cache-Verzeichnis dieses Projekts, machine für die Speicher, die alle Projekte gemeinsam nutzen — und nennt die rechnerweiten ausdrücklich, sodass einem Assistenten, der das Inventar liest, bevor er eine Bereinigung vorschlägt, gesagt wird, welche Teile davon nicht Ihnen allein gehören. Die Wartungsoperationen melden dieselbe Reichweite für jedes Element, das sie entfernt haben. Jedes der vier Veröffentlichungsergebnisse trägt ein eigenes reach, das registries enthält — jeden Registry-Host, den der Aufruf angesprochen hat, jeden einmal genannt, in der Reihenfolge, in der er sie zuerst angesprochen hat — und beyond_this_machine, das daraus abgelesen wird, was der Aufruf tatsächlich angehängt hat, und nicht daraus, was er verlangt hat: true, sobald er Inhalte hochgeladen oder eine Signatur, ein Veröffentlichungsdatum oder eine Deprecation-Markierung angehängt hat, und false für einen Probelauf und für einen Aufruf, der alles bereits vorfand, etwa eine erneut über einer vollständigen Version ausgeführte Veröffentlichung oder ein Signierstapel, dessen Referenzen alle bereits signiert waren.
Wo Sie die Grenze setzen. Das Protokoll selbst definiert keine Berechtigung pro Tool — seine Authentifizierung betrifft, ob ein Client sich überhaupt verbinden darf, nicht, welche Tools er dann aufrufen darf. Die Berechtigungsentscheidung liegt in Ihrem MCP-Client. Weit verbreitete Clients können in der Regel einzelne Tools eines Servers nach Namen erlauben und verweigern und einen Server für ein bestimmtes Projekt vollständig deaktivieren; Name und Ort der Einstellung unterscheiden sich je nach Client, konsultieren Sie daher die Dokumentation Ihres Clients zu Tool-Berechtigungen. Wenn Sie die Lese- und nicht die Schreibzugriffe wollen, erlauben Sie dort die gewünschten Tools und verweigern Sie den Rest. Eine freizügige Konfiguration oder ein Client ohne eine solche Einstellung lässt jedes bereitgestellte Tool aufrufbar.
Herausfinden, was ein Workspace enthält
Die meisten Tools nehmen ein Subjekt entgegen: einen Entitätsnamen oder den Pfad eines Release. Die beiden folgenden nehmen keines entgegen, und über sie erhält ein Assistent, der gerade erst angekommen ist, eines.
list-entities beantwortet, was der Workspace enthält, und list-releases beantwortet die engere Frage, die der Rest der Oberfläche immer wieder stellt: welche Releases es gibt. Keines von beiden nimmt ein Subjekt entgegen, denn was ein Workspace enthält, ist eine Eigenschaft des Workspace und nicht von etwas, das der Aufrufer zuerst kennen muss.
Jedes antwortet in einer von zwei Formen, und ein Aufruf, der keine Form nennt, erhält die Zusammenfassung. Dieser Standard gilt nur für diese beiden, und er ist das Gegenteil dessen, den build, describe und validate verwenden. Jene werden zu einem Subjekt befragt, das der Aufrufer bereits genannt hat, sodass die ausführlichere Antwort die erfragte ist und die knappe die optionale. Diese beiden werden gefragt, was hier ist, von einem Aufrufer, der noch nichts zu nennen hat und nicht wissen kann, was die Antwort kosten wird, bevor sie eintrifft – daher melden sie zuerst Größe und Form des Workspace und liefern Datensätze erst auf Anfrage.
Die Zusammenfassung sagt, was hier ist und wie viel davon. list-entities meldet das Workspace-Stammverzeichnis – über HTTP zurückgehalten, wie Was eine Antwort über das Dateisystem des Servers aussagt darlegt –, die Gesamtzahl der Entitäten und eine Anzahl pro Art; list-releases meldet die Gesamtzahl und eine Anzahl pro Verzeichnis der obersten Ebene, sodass Sie erfahren, wie viele Releases es gibt und in welchem Teil des Baums sie liegen. Beide Aufschlüsselungen werden aus den Dokumenten selbst gelesen, sodass ein Workspace, der auf eine Weise aufgebaut ist, mit der niemand gerechnet hat, ebenso genau zusammengefasst wird wie einer, bei dem das nicht so ist. Beide enthalten eine Zeile pro Art oder pro Verzeichnis der obersten Ebene, sodass ihre Größe davon abhängt, wie viele Arten ein Workspace deklariert und in wie vielen Verzeichnissen seine Releases liegen, und nicht davon, wie viele Dokumente er enthält: Verhundertfachen Sie die Dokumente eines Workspace bei unveränderten Arten, und die Zusammenfassung wächst nur um die wenigen Bytes, die das Schreiben der größeren Zahlen kostet. Mehr Arten zu deklarieren ist das, was sie verlängert. Keine von beiden ist eine erste Seite von Datensätzen, und genau auf diesen Unterschied kommt es an: „Hier sind einige der Entitäten“ ist eine andere Antwort als „Daraus besteht der Workspace“, und nur die zweite sagt Ihnen, ob Sie überhaupt Datensätze wollen, und welche.
Senden Sie response_format: detailed für die Datensätze, und sie kommen seitenweise. list-entities meldet dann für jede Entität Art, Namen, apiVersion, Beschreibung, Labels und Quelldatei, direkt aus dem Dokument gelesen, das sie deklariert. Es meldet auch die Features, die Ihre konfigurierten Katalogverzeichnisse deklarieren, sodass ein Feature, das Ihnen als anhängbar angeboten wird, auch eines ist, das Sie nachschlagen können; diese haben keine Quelldatei, weil der einzige Pfad, den sie haben, einer auf dem Rechner ist, auf dem der Server läuft, und jedes gibt an, woher es stammt, sodass eine leere Datei als „aus dem Katalog aufgelöst“ gelesen wird und nicht als fehlender Wert. list-releases meldet den Pfad jedes Release, und lockfiles ordnet jedem zurückgegebenen Pfad den Pfad der Lockfile dieses Release zu, in derselben Koordinate: die Datei, die pull dafür schreibt und build liest, dieselbe Datei, die die Release-Antworten des Language Servers nennen. Die Zuordnung beschreibt die Pfade, die diese Antwort enthält, folgt also der Seite, und die Zusammenfassung enthält sie leer.
detailed und concise sind die einzigen Werte, die response_format annimmt, und sie werden exakt abgeglichen. Jede andere Schreibweise – ein anderes Wort, eine andere Groß- und Kleinschreibung oder Leerraum um einen von ihnen – wird abgelehnt, und die Ablehnung nennt das Gesendete neben den Werten, die das Argument akzeptiert. response_format wegzulassen ist die Art, den Standard anzufordern, der für diese beiden Tools die Zusammenfassung ist. Dasselbe gilt überall, wo das Argument vorkommt: build, describe und validate nehmen dieselben zwei Werte zu denselben Bedingungen an, und ihr Standard ist die ausführlichere Form und nicht die knappe.
Die Datensätze sind begrenzt, ob Sie sie begrenzen oder nicht. limit gibt an, wie viele eine Antwort enthält, zwischen 1 und 500, mit dem Standardwert 50 – ein Aufruf, der Datensätze anfordert und keine Seitengröße nennt, ist also dennoch begrenzt, und kein Aufruf eines der beiden Tools liefert eine Antwort, deren Umfang die Größe des Workspace bestimmt. offset gibt an, wo in der Auflistung begonnen wird, gezählt ab 0. Beide begrenzen die Datensätze, sodass keines davon Auswirkungen auf die Zusammenfassung hat, die keine enthält. Ein limit außerhalb dieses Bereichs wird abgelehnt und nennt die Grenze; ein offset hinter dem Ende der Auflistung kommt leer zurück, weil dort nichts ist, und nicht, weil mit der Frage etwas nicht stimmt.
Setzen Sie eine Auflistung fort, indem Sie drei Felder aus der Antwort lesen. count gibt an, wie viele Datensätze der Workspace enthält, offset und returned sagen, wo diese Antwort beginnt und wie viele sie enthält, und more_remaining sagt, ob noch welche übrig sind. Solange more_remaining true ist, rufen Sie erneut mit offset plus returned auf. Dieses Signal wird aus der Seite im Verhältnis zur Gesamtzahl berechnet und nicht in die Antwort geschrieben, sodass es nicht melden kann, dass nichts übrig ist, während noch Datensätze übrig sind.
Das alles ist wichtig, weil die Tools, die einen Namen entgegennehmen, einen Namen, den sie nicht auflösen können, ablehnen, statt mit einem leeren Ergebnis zu antworten. Die Ablehnung ist beabsichtigt – eine leere Antwort würde einen vertippten Namen als Subjekt darstellen, das nichts zu bieten hat –, bedeutet aber, dass ein Aufrufer ohne Namen keinen durch Raten erhalten kann. Auflisten ist der Weg, einen zu erhalten.
Die beiden lassen sich kombinieren, miteinander und mit dem Rest der Oberfläche:
- Rufen Sie
list-entitiesfür die Zusammenfassung auf, um zu sehen, welche Arten der Workspace enthält und wie viele von jeder, rufen Sie es dann erneut mitresponse_format: detailedfür die Datensätze auf, nehmen Sie einen Namen aus dem Ergebnis und übergeben Sie ihn andescribe, um die vollständig aufgelöste Definition dieser Entität zu sehen. Es ist die Definition, mit deraggrega/entityDefinitiondes Language Servers antwortet, als JSON übertragen: jeder Schlüssel unter dem Namen, den sein Autor schreibt, in der Reihenfolge, in der die Definition ihn enthält, ein Schema als das Schema, das der Autor geschrieben hat, und ein Schema, das die Entität nicht deklariert, weggelassen – die Sockets einer Component jeweils mit den Slots, die ihre Verbindungen füllen können. - Gehen Sie mit
list-releasesgenauso vor, nehmen Sie einen Pfad aus dem detaillierten Ergebnis und übergeben Sie ihn andescribeoderbuildals das Release, mit dem gearbeitet werden soll. - Der Pfad, den
list-releaseszurückgibt, ist relativ zum Workspace-Stammverzeichnis, also derselben Koordinate, unter derlist-entitieseine Datei meldet, sodass die beiden Antworten sich an der Datei ausrichten und zusammen gelesen werden können. Seine Lockfile unterlockfilesist relativ zum selben Stammverzeichnis, sodass Sie diese Datei lesen oder vergleichen können, ohne herausfinden zu müssen, wo sie liegt.
Beide entscheiden, was zählt, indem sie das eigene kind jedes Dokuments lesen, niemals seinen Dateinamen. Ein Release, das ohne konventionelles Präfix benannt ist, wird aufgelistet; eine Datei, die lediglich wie eines benannt ist, nicht, und sie erscheint unter der Art, die sie tatsächlich deklariert. YAML, das überhaupt kein kind deklariert – die Values-Datei eines Charts, eine Konfigurationsdatei, die zufällig im Baum liegt –, ist keine Entität und wird nicht gemeldet, ebenso wenig ein Dokument, das zu einem anderen Projekt gehört, etwa ein gerendertes Kubernetes-Manifest. Ein Dokument zählt als Entität, wenn es sowohl ein kind als auch einen Namen deklariert, weil diese beiden zusammen es später adressierbar machen, und keine apiVersion außerhalb der eigenen Gruppe von Aggrega deklariert. Eines, das überhaupt keine apiVersion deklariert, wird gemeldet, da es ein Aggrega-Dokument mit einem fehlenden Feld ist und keine Datei eines anderen Projekts. list-releases durchsucht kein Verzeichnis außerhalb des Workspace-Stammverzeichnisses, sodass ein Release, das Ihr Editor unter einem Link anzeigt, der zu einem solchen Verzeichnis führt, nicht aufgelistet wird; unread_linked_dirs nennt jeden Link, der dort steht, wo die Auflistung ein Verzeichnis lesen würde, und aus dem Stammverzeichnis hinausführt – über den eigenen Pfad des Links relativ zum Stammverzeichnis, niemals über sein Ziel –, in beiden Formen und über beide Transporte, und ist leer, wo es keinen gibt. Ebenso wenig liest es eine Datei außerhalb des Stammverzeichnisses über einen Link: unread_linked_files nennt auf dieselbe Weise jeden Link, dessen eigener Name auf .yaml oder .yml endet und der zu einer Datei außerhalb des Stammverzeichnisses führt, gleich, was diese Datei enthält, sodass ein Release, das nur über einen solchen Link erreicht wird, nicht aufgelistet wird – es sei denn, die Workspace-Konfiguration nennt dieses Release, als build.authoring_release oder als Schlüssel von workspace.releases; in diesem Fall wird es an der eigenen Stelle des Links gelesen und aufgelistet und nicht genannt. Auch list-entities liest kein Dokument hinter einem Link, der aus dem Workspace hinausführt – es durchsucht kein Verzeichnis außerhalb des Stammverzeichnisses und liest keine Datei außerhalb davon, gleich, was diese Datei deklariert –, und nennt jeden solchen Link auf dieselbe Weise, in seinen eigenen unread_linked_dirs und unread_linked_files, in beiden Formen und über beide Transporte. Das gilt unabhängig davon, was das Dokument deklariert, mit der einen Ausnahme, die list-releases macht: Ein Release, das die Workspace-Konfiguration nennt, als build.authoring_release oder als Schlüssel von workspace.releases, wird an der eigenen Stelle des Links gelesen und aufgelistet und nicht genannt, während eine von einer dieser Einstellungen genannte Datei, die etwas anderes als ein Release deklariert, nicht aufgelistet und ihr Link genannt wird. Über die konfigurierten Katalogverzeichnisse liest ein Workspace andere Entitäten, die anderswo liegen, sodass ein Link zu einem Verzeichnis, das die Konfiguration unter catalog_dirs aufführt, oder zu einem Verzeichnis darunter, von keiner der beiden Auflistungen genannt wird: Die Konfiguration hat es erreicht. Die Features, die list-entities aus den Katalogverzeichnissen übernimmt, enthalten niemals eines hinter einem Link, der aus dem Verzeichnis hinausführt, in dem die Lesevorgänge eines Katalogverzeichnisses bleiben müssen – dem Workspace für ein Katalogverzeichnis darin oder dem Verzeichnis selbst für eines, das die Konfiguration außerhalb davon nennt –, sodass eine Entität, die als hinter einem nicht gelesenen Link liegend genannt wird, niemals neben diesem Namen aufgelistet wird. Ein Link, den die Auflistung auslässt – aufgrund seines Namens, seiner Lage oder einer .gitignore –, wird nicht genannt, und mit release ebenso wenig einer unter einem Katalogverzeichnis, das nur andere Releases lesen; eine .gitignore, die selbst ein aus dem Workspace hinausführender Link ist, wird nicht gelesen. Wo eine dieser Listen einen Link nennt, endet die Textantwort mit einer eigenen Zeile, die darauf hinweist.
Ein Workspace, dessen Konfigurationsdatei aus ihm hinausführt, wird dennoch aufgelistet, und sonst wird für ihn nichts beantwortet. Wo die eigene .aggrega-config.yaml des Workspace oder das CI-eigene Overlay daneben ein Link ist, der aus dem Workspace hinausführt, wird seine Konfiguration nicht gelesen, wie im Terminal, und nichts von dem, was sie konfiguriert hätte, wird an ihrer Stelle gelesen. Der Server startet dennoch über Standardeingabe und -ausgabe und weist in einer Zeile auf seinem Fehlerstrom darauf hin. list-entities und list-releases antworten mit den eigenen Dokumenten des Workspace, gelesen ohne jede Konfiguration, sodass keine Features eines Katalogverzeichnisses aufgelistet werden. Jedes nennt die zurückgehaltene Datei in unread_linked_files und in der Zeile, die seinen Text abschließt, ob die Auflistung auf sie gestoßen ist oder nicht – an diesem Namen erkennen Sie, dass die Konfiguration des Workspace aus ihm hinausführt. Eine Auflistung, der release oder catalog_dirs gesendet wurde, und jedes andere Tool, das diesen Workspace nennt, hängt von der nicht gelesenen Konfiguration ab, sodass jedes mit E0321 abgelehnt wird, unter Nennung des Links und seines Ziels. Ein Server, dem auf seiner Befehlszeile gesagt wird, zu lauschen – --transport http oder --listen –, startet über einem solchen Workspace nicht, weil die Adresse, an die er sich binden würde, sein Zertifikat und wer ihn aufrufen darf, genau das sind, was diese Konfiguration entscheidet. Entfernen Sie den Link oder lassen Sie ihn auf eine Datei innerhalb des Workspace verweisen, und der nächste Aufruf liest die Konfiguration. Siehe die Workspace-Grenze.
Fragen in den Begriffen eines Release
Ein Workspace kann jedem Release eigene Katalogverzeichnisse geben – siehe Einem Release eigene Katalogverzeichnisse geben – und so eine Variante einer Entität pro Release nebeneinander halten. Drei Tools, die sonst über die eigenen Katalogverzeichnisse des Workspace antworten, nehmen ein optionales release entgegen, den Pfad einer Release-Datei, und antworten dann in den Begriffen dieses Release:
list-entitiesmitreleaselistet die Entitäten auf, die dieses Release sieht. Die aufgelisteten Features sind diejenigen, die seine Katalogverzeichnisse deklarieren, und ein Workspace-Dokument unter einem Katalogverzeichnis, das nur andere Releases lesen, wird ausgelassen, sodass jede Variante für das Release aufgelistet wird, das mit ihr baut, und für kein anderes. Ein Dokument, das unter überhaupt keinem Katalogverzeichnis liegt – ein Release, sein Aggregate und sein Manifest, neben den Katalogen geschrieben –, wird für jedes Release aufgelistet.describemit einemnameund einemreleaselöst den Namen über die Katalogverzeichnisse dieses Release auf, sodass ein Name, den mehrere Varianten deklarieren, zu derjenigen aufgelöst wird, mit der dieses Release baut. Ein Name, den diese Verzeichnisse nicht auflösen, wird mit einer Erläuterung abgelehnt, die den Eintrag dieses Release unterworkspace.releasesnennt. Eine Registry-Referenz wird aus ihrer Registry gelesen, gleich, welches Release genannt ist, und wird daher neben einemreleaseabgelehnt. Ein ohnenamegesendetesreleaseist weiterhin das Release, dasdescribezusammenfasst.validatemit einerentityund einemreleaseführt die Prüfungen für eine einzelne Entität in den Begriffen dieses Release aus: Die Referenzen der Entität – die Component, die ein Recipe implementiert, eine SchemaLibrary, auf die eine Säule verweist – werden über die Katalogverzeichnisse dieses Release aufgelöst, und die Antwort nennt das Release neben der Entität. Es wird keine Hülle validiert; ein ohneentitygesendetesreleaseist weiterhin der Release-Bereich.catalog_dirswird hier wie überall den Verzeichnissen des Release vorangestellt. Ein Verzeichnis, das die Workspace-Konfiguration aufführt und das kein Verzeichnis ist – weil dort zum Beispiel nichts existiert –, für dieses Release oder für den Workspace, wenn keinreleasegesendet wird, führt zur Ablehnung des Aufrufs, bevor irgendetwas geprüft wird, wobei der Text die Ablehnung trägt, die jeder Befehl dafür ausgibt, und den Eintrag sowie die Konfigurationsdatei und die Zeile nennt, die ihn aufführen (Woher lokale Entitäten gelesen werden), so wieaggrega validatees ablehnt.
Ein release, das eine nicht existierende Datei oder ein Verzeichnis nennt, wird von allen drei abgelehnt, statt in den Begriffen des Workspace beantwortet zu werden. Wird keines gesendet, wird über die eigenen Katalogverzeichnisse des Workspace geantwortet.
describe lehnt beim Nachschlagen eines Namens ein Katalogverzeichnis, über das es den Namen auflösen würde und das nicht durchlaufen werden kann, ab, so wie aggrega inspect es ablehnt – die Verzeichnisse dieses Release, wenn ein release gesendet wird, die eigenen des Workspace, wenn keines gesendet wird, und alle, die der Aufruf in catalog_dirs nennt. Ein vom Aufruf genanntes Verzeichnis, das nicht existiert, oder eines, das vorhanden ist und nicht gelesen werden kann, wird abgelehnt, bevor der Name nachgeschlagen wird, und der Text nennt das Verzeichnis so, wie die Befehlszeile es meldet, in einer Zeile – das Verzeichnis, catalog load und den Grund, den das Dateisystem angegeben hat –, statt den Namen aus den verbleibenden Verzeichnissen aufzulösen. Ein Verzeichnis, das die Workspace-Konfiguration aufführt und das kein Verzeichnis ist, wird im selben Moment abgelehnt, wobei der Text die Ablehnung trägt, die jeder Befehl dafür ausgibt (Woher lokale Entitäten gelesen werden). Ein release, das eine nicht existierende Datei nennt, wird schon davor abgelehnt, wie oben. Ein Katalogverzeichnis, das einen Link enthält, der aus dem Verzeichnis hinausführt, in dem seine Lesevorgänge bleiben müssen, wird auf dieselbe Weise abgelehnt, wobei der Text den Link und sein Ziel nennt, weil ein ohne es aufgelöster Name an seiner Stelle zu einer anderen Entität gleichen Namens aufgelöst werden könnte. Das Beschreiben der Abhängigkeitshülle eines Release wird von einem Verzeichnis, das nicht durchlaufen werden kann, nicht beeinträchtigt und antwortet über die Verzeichnisse, die durchlaufen werden können, wie es aggrega inspect --closure tut – ausgenommen ein Verzeichnis, das die Workspace-Konfiguration für dieses Release aufführt und das kein Verzeichnis ist; dieses lehnt es ab, so wie aggrega inspect --closure es ablehnt; ein Link, der aus den Lesevorgängen eines Katalogverzeichnisses oder aus den Dokumenten neben dem Release hinausführt, hält es an, so wie er einen Build anhält.
validate mit einer entity meldet ein Rendering, das es nicht beurteilen kann, als nicht versucht, in den Begriffen eines Release oder ohne. Es setzt die Component eines Recipe in einen synthetisierten Build, der keine Verbindung verdrahtet und kein Feature anhängt, sodass ein Recipe, dessen Rendering anhält, während seine Templates – einschließlich der Dateien und Bibliothekseinträge, die sie importieren – etwas unter .context.inject, .context.uses oder .features lesen, mit valid: true und nichts in diagnostics antwortet; sein Text enthält Render: not attempted (this Recipe reads values a build of one cannot supply), die Lesevorgänge, derentwegen es zurückgestellt wurde, und den Satz, an dem das Rendering anhielt. Entscheidend ist, was das Recipe liest, sodass ein eigener Fehler des Recipe neben einem solchen Lesevorgang mit ihm zurückgestellt wird, während ein Template, das sich nicht parsen lässt, und eine Referenz, die das Rendering ablehnt, weiterhin valid: false ergeben. aggrega validate kommt bei denselben Eingaben zum selben Urteil.
validate mit einer entity meldet eine fehlgeschlagene Assertion als Warnung, in den Begriffen eines Release oder ohne. Eine Assertion, die fail aufruft – die des Recipe selbst oder eine, die die von ihm implementierte Component deklariert –, ergibt valid: true mit nichts in diagnostics. Der synthetisierte Build enthält Platzhalter und Schema-Standardwerte anstelle der Werte, die ein echtes Release setzt, sodass eine Assertion über einen solchen Wert dort fehlschlägt, ob das Recipe korrekt ist oder nicht, und die Prüfung eine Assertion, die auf ein Release wartet, nicht von einer defekten unterscheiden kann. Der Fehlschlag folgt den übrigen notices, in der vollständigen Meldung der Assertion, abgeschlossen durch den Satz A Release must satisfy this assertion before a build of it can pass., und der Text enthält ihn in einer mit warning: eingeleiteten Zeile neben der Berichtszeile, die sagt, wo der Lauf anhielt. Eine Assertion, die an einem Schlüssel anhält, den sie liest, aber nicht findet, ist ein Fehler in ihrem eigenen Text und keine fehlgeschlagene Assertion und wird wie jeder andere Halt beurteilt; ein Build eines Release, das eine Assertion nicht erfüllt, wird deswegen weiterhin abgelehnt. aggrega validate kommt bei denselben Eingaben zum selben Urteil.
Die geltende Konfiguration und die von diesem Server aufgelösten Plugins lesen
config-show meldet die geltende Konfiguration und welche Ebene jede Einstellung entschieden hat. plugin-list meldet die Plugins, die dieser Server auflösen kann, und was jedes davon über sich selbst sagt. Beide lesen und schreiben nichts, sodass keines etwas erreicht und aggrega:read sie zulässt – und keines verlangt von Ihnen, ein Subjekt zu nennen, denn was konfiguriert ist und was sich auflöst, sind Eigenschaften dieses Servers und nicht von etwas, das Sie zuerst kennen müssen. Jedes nimmt über Standardeingabe und -ausgabe ein optionales workspace_root entgegen; über HTTP wird dieses Argument abgelehnt, wie Ein Prozess, ein Workspace darlegt.
Zusammen beantworten sie eine Frage in zwei Hälften: ob eine Fähigkeit fehlt oder hier lediglich nicht konfiguriert ist. Die Konfiguration sagt, ob ein Provider, ein Importer oder eine Governance-Prüfung überhaupt angehängt ist; das Lesen der Plugins sagt, ob ein Anhang einen Gast erreicht, der sich auflöst, sich selbst beschreibt und bereitstellt, was er zu bieten behauptet. Von überall sonst auf dieser Oberfläche sehen diese beiden gleich aus, und sie erfordern entgegengesetzte nächste Schritte.
config-show meldet einen Eintrag pro Einstellung: ihr field, ihren effektiven value und die source, die sie entschieden hat – eine Konfigurationsdatei, eine Umgebungsvariable, ein Befehlszeilen-Flag oder die eingebauten Standardwerte. Daneben enthält layers die beitragenden Ebenen in der Reihenfolge ihres Vorrangs, die niedrigste zuerst. Die source einer Einstellung ist genau so geschrieben wie der entsprechende Eintrag in layers, sodass sich die beiden direkt verknüpfen lassen, und eine Einstellung, die die Standardwerte entschieden haben, nennt überhaupt keine Ebene, weil die Standardwerte keine beitragende Ebene sind. Die globale Ebene ist die Datei, die die eigene Befehlszeile des Servers auswählt – die, die --config beim Start nannte, andernfalls die, die die Umgebungsvariable AGGREGA_CONFIG nennt, andernfalls der Standardort –, sodass eine Einstellung, die diese Datei entscheidet, dieser Datei zugeordnet wird, genau wie aggrega config show --origin sie zuordnet, und ein dem Server übergebenes Flag wie --offline als dieses Flag gemeldet wird. Es nimmt weder response_format noch eine Seitengröße entgegen: Die Einstellungen sind die feste Menge, die diese Binärdatei berücksichtigt, und jede Auflösung meldet sie alle, sodass die Größe der Antwort der Binärdatei folgt und nicht dem, was Sie konfigurieren.
plugin-list antwortet in den zwei Formen, die die Workspace-Auflistungen verwenden, und ein Aufruf, der keine Form nennt, erhält die Zusammenfassung. Die Zusammenfassung ist eine Anzahl pro Gruppe, und es gibt zwei Gruppen – embedded, die in diese Binärdatei kompilierten Gäste, die ohne Zugriff auf Dateisystem, Cache oder Netzwerk aufgelöst werden, und configured, die eigenen Bindungen des Workspace. Senden Sie response_format: detailed für die Datensätze: die Gruppe jedes Plugins, die Referenz, unter der es gefunden wurde, wo diese Referenz gebunden wurde, seinen selbst gemeldeten Typ, seine Version, seinen Commit, seine bereitgestellten Fähigkeiten, gerenderten Eingabearten, seine Grenz-Assembly und Exporte, seine Bereitschaft, sofern es eine hat, und ob es aufgelöst wurde. Die Datensätze werden durch limit und offset zu denselben Bedingungen begrenzt, die die Entitätsauflistung verwendet, mit count, returned und more_remaining zum Fortsetzen. Diese Antwort wächst sehr wohl mit dem, was Sie konfigurieren – die eingebauten sind fest, die Bindungen sind Ihre –, weshalb sie seitenweise ausgegeben wird und das Lesen der Konfiguration nicht.
Ein Plugin, das fehlschlägt, wird mit seinem Fehler gemeldet, statt aus der Auflistung entfernt zu werden. resolved sagt, ob die Referenz überhaupt Modul-Bytes erreicht hat, und ein Plugin, das aufgelöst wurde, sich aber nicht selbst beschreiben konnte, wird genau so gemeldet – sodass ein Anhang, der vorhanden und unbrauchbar ist, von einem unterscheidbar ist, der nie hergestellt wurde.
Was ein Listener Ihnen nicht über seinen Host verrät
Über HTTP meldet keines der beiden Lesevorgänge einen Wert, der einen Ort im Dateisystem des Servers nennt. Ein Client, der den Server gestartet hat, läuft dort, wo der Server läuft, sodass jeder Ort, den eine der beiden Antworten nennen könnte, einer ist, den dieser Aufrufer bereits besitzt und sich ansehen kann. Ein Aufrufer, der einen Listener erreicht, hat keinen davon gewählt, kann mit ihrer Kenntnis nichts anfangen, und ein Server, der sie einem solchen Aufrufer offengelegt hat, kann sie nicht zurücknehmen. Über diesen Transport fehlen diese Werte; über Standardeingabe und -ausgabe sind sie alle vorhanden. Es ist die Regel, der jede Antwort auf dieser Oberfläche folgt, wie Was eine Antwort über das Dateisystem des Servers aussagt darlegt, und bei diesen beiden Lesevorgängen reicht sie am weitesten, weil das meiste dessen, was sie melden, Konfiguration ist, die Orte nennt.
Was zurückgehalten wird. Aus config-show: der value einer Einstellung, wo der eigene Wert dieser Einstellung ein Ort ist – eine Bereitstellungs- oder Health-Adresse, die eine Socket-Datei sein kann; eine Zertifikats-, Private-Key- oder Key-Set-Datei; ein Katalogverzeichnis sowie die eigenen Katalogverzeichnisse eines Release unter workspace.releases, deren Einträge jeweils durch eine Release-Datei verschlüsselt sind; eine Plugin-Referenz; ein Authoring-Release. Außerdem die source einer Einstellung, wo die Ebene, die sie entschieden hat, eine Konfigurationsdatei ist, da eine solche Ebene durch den eigenen Pfad dieser Datei benannt wird – und in derselben Schreibweise und aus demselben Grund die Konfigurationsdatei-Einträge von layers. Aus plugin-list: die uri eines Plugins, wo diese Referenz selbst ein Dateisystempfad ist, und der Text eines Auflösungs- oder Beschreibungsfehlers, der aus den versuchten Orten zusammengesetzt ist und daher Orte nennt, die die Referenz selbst nicht nennt. Aus beiden: workspace_root.
Was vollständig gemeldet wird, über beide Transporte. Eine Registry-Referenz, eine Version, ein Commit, ein Digest, eine bereitgestellte Fähigkeit, ein Bereitschafts-Label, der Name einer Umgebungsvariablen oder eines Flags und eine Ebene, die keine Datei ist. origin in einem Plugin-Datensatz ist eines davon: Es ist der Konfigurationsschlüssel, unter dem eine Bindung geschrieben wurde, oder der gepinnte Digest, den eine installierte Befehlserweiterung trägt, und ein eingebautes Plugin trägt keinen – es ist also dieselbe Zeichenkette, wo auch immer das Plugin gelesen wird. resolved ist ein weiteres: Ob ein Plugin fehlgeschlagen ist, wird jedem Aufrufer gemeldet, auch dort, wo der Grund dafür nicht gemeldet wird.
Ein fehlender Wert sagt immer, dass er zurückgehalten wurde, und das macht die Antwort verwendbar. Ein zurückgehaltener Wert wird als fehlend gemeldet, mit einer Markierung daneben – value_withheld und source_withheld bei einer Einstellung, withheld bei einem Ebeneneintrag, uri_withheld und error_withheld bei einem Plugin-Datensatz und workspace_root_withheld bei der Antwort. Eine Einstellung, die niemand gesetzt hat, trägt den leeren Wert, als den ihre Form dargestellt wird, und keine Markierung. „Dieser Server verrät Ihnen nicht, wo der Signaturschlüssel liegt“ und „Es ist kein Signaturschlüssel konfiguriert“ sind verschiedene Antworten, die verschiedene nächste Schritte erfordern, und ein Lesevorgang, der sie identisch meldete, würde Ihnen nichts sagen, worauf Sie handeln könnten. Jede Antwort trägt außerdem stets host_locations_withheld, das sagt, welche der beiden Antworten Sie vor sich haben: Eine Antwort ohne Markierungen ist sonst dieselbe, ob diese Regel sie geformt hat und auf dem Host nichts zurückzuhalten war oder ob sie nie angewendet wurde. Der lesbare Text neben den Feldern sagt dasselbe in Worten.
Die Regel ist eine Eigenschaft und keine Liste von Feldnamen: Ein Wert wird zurückgehalten, wenn er einen Ort im Dateisystem des Hosts nennt, gleich, wer ihn gesetzt hat und aus welcher Ebene er stammt. Ein Wert, der später einem der beiden Lesevorgänge hinzugefügt wird, unterliegt derselben Eigenschaft.
Über Standardeingabe und -ausgabe ist jede Fähigkeit auch als das nach ihrem Befehl benannte Tool erreichbar – cli-config-show und cli-plugin-list –, das diesen Befehl in einem separaten Prozess ausführt und den ausgegebenen Text zurückgibt; über HTTP gibt es diese Tools nicht. Die beiden hier beschriebenen liefern stattdessen die Werte, sodass Sie lesen können, ob eine Fähigkeit angehängt ist, oder die Version eines Plugins herausgreifen können, ohne ein Spaltenlayout in das zurückzuparsen, woraus es gerendert wurde.
Fragen, was angehängt werden darf und was sich womit verbinden darf
Zwei Tools beantworten die Fragen, bei denen ein Assistent sonst raten müsste: welche Features an einen Knoten angehängt werden dürfen und womit sich ein Knoten verbinden darf. Beide führen denselben Label-Abgleich aus, den der Compiler ausführt, sodass das, was der Assistent Ihnen anbietet, die Menge ist, die ein Build abgleichen würde, und keine aus dem Schema abgeleitete Menge.
attach-candidates meldet die Features, deren deklarierte Anwendbarkeit die Labels eines Knotens erfüllen. Adressieren Sie den Knoten auf genau eine von drei Arten:
node– dermetadata.nameeiner Workspace-Entität, wielist-entitiesihn meldet. Der Abgleich läuft über die Labels, die dieses Dokument deklariert.graph_nodemitrelease– ein Knoten in einem kompilierten Graphen, mit dem Schlüssel, den der Graph ihm gibt, einschließlich der qualifizierten Form, die ein von einem Sub-Aggregat beigetragener Knoten trägt. Der Abgleich läuft über die finalisierten Labels dieses Knotens, also diejenigen, die ein Build auswertet.labels– eine Label-Menge für sich, die keinen Knoten nennt. Sie benötigt überhaupt keine Koordinate, sodass dies die zu verwendende Form ist, wenn Sie die Labels eines Knotens bereits haben; sie schlägt nichts nach und baut keinen Graphen neu auf.
Die Antwort enthält die Labels, über die der Abgleich lief, und aus welcher der drei Mengen sie stammen, sodass Sie jeden Kandidaten – oder das Fehlen eines solchen – aus der Antwort selbst erklären können, statt ihn erneut herzuleiten. Sie auf einem zweiten Weg zurückzulesen ist genau der Punkt, an dem Ihre Vorstellung von den Labels eines Knotens und die des Compilers auseinandergehen.
Um zu fragen, was an eine einzelne Verbindung angehängt werden darf, die ein Knoten zieht, fügen Sie connection neben graph_node und release hinzu – ihr socket und ihren alias, wie der Autor sie geschrieben hat. Eine Verbindung trägt Anhänge, die die Slots füllen, die ihr Socket an der konsumierenden Component deklariert, sodass die Antwort dann auch slots enthält: jeden Slot, den der Socket deklariert, mit seinen selector, required, inject, sensitive und description genau so, wie die Component sie deklariert, und die candidates, die ihn füllen dürfen. Das sind die Features, deren Anwendbarkeit die Labels des Knotens erfüllen, und deren eigene Labels der Selektor des Slots zulässt – die beiden Regeln, an denen ein Build einen solchen Anhang misst –, sodass die Kandidaten eines Slots immer unter denen des Knotens selbst sind. Wo nichts gefüllt werden darf, ist slots leer, und noSlotReason sagt, warum: feature-created-connection (ein Feature hat die Verbindung gezogen, und an eine solche wird nichts angehängt), ad-hoc-socket (der Socket ist einer, den die Component nicht deklariert) oder no-slot-declared (der Socket deklariert keinen). Lesen Sie ein leeres slots nicht als „nichts hat gepasst“; genau das soll der Grund ausschließen, und er fehlt überall, wo ein Slot existiert. candidates daneben behält seine Bedeutung – was an den Knoten selbst angehängt werden darf –, und document, falls Sie eines senden, ändert hier nichts. connection neben node oder labels oder ohne Angabe eines Sockets oder Alias wird abgelehnt, ebenso eine Verbindung, die der Knoten nicht zieht. Dies sind dieselben Antworten, die der Language Server gibt, zu denselben Bedingungen.
connection-candidates meldet die Abhängigkeits-Sockets, die eine Entität deklariert, und pro Socket die Workspace-Components, deren deklarierte Labels die Einschränkung erfüllen, die dieser Socket über seine Ziele deklariert. Es nimmt den metadata.name der Entität in node entgegen. Anders als attach-candidates hat es keine koordinatenfreie Form: Es gibt hier keine Label-Mengen-Form, weil die Sockets aus der eigenen Deklaration der genannten Entität gelesen werden.
Seine beiden Hälften sind nicht gleich vollständig, und die Antwort sagt, welche welche ist – stellen Sie sie nicht als eine Liste dar. Die Ziele sind vollständig: Es sind die Komponenten, die dieselbe Einschränkung während eines Builds zulässt. Die Sockets sind es nicht und können es nicht sein. Ein Konsument darf eine Verbindung erfinden, aber nur konsumieren, was ein Produzent deklariert, sodass ein Autor legitimerweise einen Socket schreiben darf, den die Katalogentität nie deklariert hat, und die deklarierten Sockets sind ein hilfreicher Anfang und nicht die Menge der zulässigen Namen. Jeder Socket sagt daher, ob er declared oder ad-hoc ist, und die Antwort sagt, ob ein nicht deklarierter Socket auf dieser Entität überhaupt akzeptiert wird – die Abhängigkeitsoberfläche einer Component akzeptiert einen, weil ein Autor die Topologie seiner Anwendung verantwortet; die Anhangsoberfläche eines Feature nicht, weil ein Anhang an der Topologie teilnimmt, die das angehängte Feature deklariert, statt eine eigene zu entwerfen. Diese Offenheit ist eine Folge Ihrer Freiheit beim Authoring, keine Lücke: Übergeben Sie socket mit einem Namen, den die Entität nicht deklariert, um danach zu fragen.
Beide antworten und halten an. Keines erstellt einen Anhang, erstellt eine Kante, schreibt in eine Datei oder schlägt den Text eines solchen vor; das Verfassen und Anwenden der darauf folgenden Bearbeitung liegt bei Ihnen.
Beide geben dieselbe minimale Identität zurück, die jede andere Antwort hier verwendet – Art, Name und Quelldatei – und nichts weiter. Alles andere, was Sie über eine Entität anzeigen möchten, steht bereits in list-entities für dieselben drei Felder, sodass Sie die beiden Antworten verknüpfen, statt zwei Kopien zu lesen, die sich widersprechen könnten. Beide lehnen einen Namen, den sie nicht auflösen können, ab, statt mit einer leeren Liste zu antworten, aus demselben Grund wie der Rest der Oberfläche: Eine leere Antwort würde einen Tippfehler als Subjekt darstellen, das nichts zu bieten hat. Ein labels-Aufruf hat keinen Namen, den man vertippen könnte, sodass ein leeres Ergebnis dort bedeutet, was es sagt.
Alles, was der Server zum Nachschlagen liest, wird von diesem Rechner bereitgestellt – die JSON Schemas sind in die Binärdatei eingebaut, und die Dokumentation wird aus dem Cache für Dokumentationspakete gelesen, den der Rechner vorhält, wie unten beschrieben. Das Entwerfen eines Startdokuments, Validieren, Beschreiben, Bauen und Linten laufen alle gegen Ihren Workspace und die lokalen Caches, und keines davon erreicht von sich aus eine Registry: Ein Rendering stellt eine gepinnte externe Referenz aus dem inhaltsadressierten Speicher bereit und verweigert eine nicht gepinnte, statt sie abzurufen, was die gesamte Schleife aus Inspizieren und Rendern offline hält. Zwei Registry-Lesevorgänge können Sie anfordern: describe mit einer Registry-Referenz, das diese eine Koordinate abruft, nichts schreibt und über HTTP nur eine Registry erreicht, mit der der bereitgestellte Workspace konfiguriert ist; und scaffold mit example oder list, das das Dokumentationspaket aus der Standard-Registry des Workspace bezieht, wenn der Rechner keine Kopie hält, die die Signaturrichtlinie des Workspace zulässt, und es vor dem Aufbewahren verifiziert, wie es aggrega scaffold --example tut. Veröffentlichen und Signieren sind die bewusste Gegenseite dazu und werden oben behandelt.
Zwischen beiden liegt das Auflösen der Abhängigkeiten eines Release, das hier als Einziges etwas beschafft: Es erreicht eine Registry, weil die Aufforderung, Abhängigkeiten aufzulösen, die Aufforderung ist, sie abzurufen. Es geschieht nur, wenn Sie es anfordern, und es gibt genau zwei Wege, es anzufordern – den Aufruf von pull, dessen einzige Aufgabe es ist, oder das Senden von auto_pull an build, das dieselbe Auflösung als ersten Schritt des Builds ausführt. Sonst führt nichts in Ihrem Namen einen Pull aus, und ein Build, dem Sie kein auto_pull gesendet haben, erreicht keine Registry. Die einzige Einstellung, die das ändert, ist das eigene auto_pull des Workspace: Ein so konfigurierter Workspace fordert jeden Build darin auf, zuerst aufzulösen, gleich, von wo dieser Build ausgeführt wird, wie unten beschrieben.
Die eine Ausnahme unter diesen Nachschlage-Lesevorgängen ist das Beschaffen des Dokumentationspakets selbst, und es geschieht abseits jedes Lesevorgangs. Das Paket wird einmal pro Rechner vorgehalten, im Cache, den jedes Aggrega-Projekt teilt, eine Kopie für jede Registry und Version – sodass ein Server, der in einem Ordner gestartet wird, in dem kein Workspace-Cache angelegt werden kann, es trotzdem vorhält (siehe aggrega cache). Beim Start des Servers, bevor er auf irgendetwas antwortet, das Sie senden, sucht er dort nach einer Kopie, die die Signaturprüfung Ihres eigenen Workspace zulässt – dieselbe Prüfung, der ein Pull des Pakets unterliegt –, und ruft das Paket über dieselben Egress-Einstellungen ab, die der Rest der CLI verwendet, nur wenn es keine gibt. Das Paket, nach dem er sucht, ist das für die Version von aggrega veröffentlichte, die der Server ausführt, oder, wo für sie keines veröffentlicht ist, das neueste für eine frühere Version veröffentlichte – dieselbe Wahl, die aggrega explain und aggrega scaffold --example treffen –, und jede Seite, die er bereitstellt, und jede Erklärung wird aus dem Paket gelesen, das er bezogen hat. So sind die Seiten bereits vorhanden, wenn etwas eine anfordert, gleich, was Ihr Client zuerst sendet, und ein anderer Server oder aggrega explain in einem anderen Projekt findet dieselbe Kopie, statt sie erneut herunterzuladen.
Das Bereitstellen einer Seite ist dann ein Lesevorgang dieser Kopie und erreicht keine Registry. Bevor eine Seite bereitgestellt wird, werden die neben der Kopie gespeicherten Signaturen unter der Prüfung Ihres Workspace erneut verifiziert, sodass Ihnen eine Kopie, die die lockerere Einstellung eines anderen Projekts zugelassen hat, nicht bereitgestellt wird: Wo die Prüfung einen Schlüssel oder eine Trust Root pinnt, läuft diese Verifizierung offline, und wo sie keines von beiden pinnt – die eingebaute Prüfung des offiziellen Hubs ist eine solche –, bezieht sie die öffentliche Sigstore-Trust-Root, wie es ein Pull tut. Ein Offline-Workspace kann diese Trust Root nicht abrufen, daher verifiziert er offline gegen die Trust Root, die ein früherer Online-Abruf auf diesem Rechner in dem Cache hinterlassen hat, den der Sigstore-Client unter .sigstore in Ihrem Home-Verzeichnis vorhält, wie lange dieser Abruf auch zurückliegt, und ruft nichts ab; auf einem Rechner, der sie nie abgerufen hat, kann die Prüfung offline nicht laufen, die Kopie wird nicht bereitgestellt, und der Log-Stream weist darauf hin. Diese Verifizierung läuft einmal für jede Kopie und jede Prüfung, solange der Server läuft, und die danach gelesenen Seiten werden auf Grundlage dessen bereitgestellt, was sie zugelassen hat: Eine seitdem abgerufene Kopie, ein Workspace, dessen Prüfung abweicht – einschließlich einer vor Ort bearbeiteten gepinnten Trust Root –, ein offline vorgenommener Lesevorgang oder ein Offline-Lesevorgang, der eine andere auf dem Rechner hinterlassene Trust Root vorfindet, wird für sich verifiziert. Eine Kopie, die Ihre Prüfung abgelehnt hat, wird beim nächsten Lesevorgang erneut geprüft, sodass ein Abruf, der sie inzwischen zugelassen hat, nicht übergangen wird. Wenn das Paket nicht beschafft werden kann oder die einzige Kopie eine ist, die Ihre Prüfung ablehnt, und ihr erneuter Abruf unter dieser Prüfung fehlschlägt, startet der Server dennoch, und jede andere Oberfläche funktioniert; Dokumentationsanfragen antworten mit not-found, und der Log-Stream des Servers sagt, warum.
Gegen die Inhalte bauen, die ein Release bereits pinnt
build rendert ein Release im Speicher in seine Artefakte, und ein Rendering kann Inhalte von einer entfernten URL anfordern – etwa das Values-Schema eines Charts mit einer entfernten Referenz. Externe Eingaben sind für den Aufruf eingefroren. Eine Referenz, die das Lockfile des Release bereits pinnt, wird aus dem inhaltsadressierten Store bedient, was ein Lesen bereits auf der Festplatte vorhandener Inhalte ist und kein Abruf. Eine Referenz, die das Lockfile nicht pinnt, wird zurückgewiesen und benannt, statt abgerufen zu werden: Angefordert haben Sie ein Rendering, und das Beschaffen einer Referenz würde sowohl das Netzwerk erreichen als auch einen Blob in den Store schreiben, als Nebeneffekt der Erzeugung von Bytes. Dieses Einfrieren ist eine Eigenschaft des Renderings. Das Auflösen ist der Schritt, der beschafft: Es rendert das Release, um herauszufinden, welche entfernten Referenzen dieses Rendering anfordert, ruft sie ab und hält sie in demselben Lockfile-Schreibvorgang fest, der die Abhängigkeits-Pins enthält. Was das Auflösen ändert, ist also, welche Referenzen gepinnt sind, wenn ein Rendering läuft, nie, was ein Rendering erreichen darf – und eine Referenz, die keine Auflösung gepinnt hat, wird bei einem Aufruf, der zuerst aufgelöst hat, genauso zurückgewiesen wie bei einem, der das nicht getan hat.
Die Dateien kommen als die Bytes zurück, die ein echter Build ausgibt, und zwei Dinge zusammen sorgen dafür. Das eine ist das oben beschriebene Einfrieren: Eine gepinnte Referenz wird aus dem Store gelesen statt abgerufen. Das andere ist, dass das Lockfile, aus dem gelesen wird, noch beschreibt, wozu das Release aufgelöst wird – daher prüft build das und lehnt ein Lockfile ab, das nicht mehr übereinstimmt, genau wie aggrega build im Terminal. Das Lesen gepinnter Bytes sagt für sich allein nichts darüber aus, ob es die richtigen Bytes zum Lesen waren.
Alle drei Lockfile-Zustände, damit das Verhalten explizit ist. Ganz ohne Lockfile rendert build aus dem, was der Workspace bereits pinnt, und weist jede externe Referenz zurück, die es nicht bedienen kann, wobei es jede einzeln benennt; sich selbst überlassen verlangt es weder ein Lockfile noch schreibt es eines, und daran ändert die oben beschriebene Prüfung nichts – es gibt kein Lockfile zu vergleichen, also wird nichts abgelehnt. Mit einem Lockfile, das übereinstimmt, rendert es. Mit einem Lockfile, das nicht mehr übereinstimmt, lehnt es ab, und die Ablehnung nennt, wie sich das beheben lässt: Rufen Sie pull mit demselben release und ohne upgrade_targets auf, was das Lockfile mit dem abgleicht, wozu das Release heute aufgelöst wird. Die Ablehnung enthält auch die Terminal-Form derselben Operation, aggrega pull --release <release>. Beide Aufrufe beheben es; sie sind eine Operation, die von zwei Stellen aus erreichbar ist, nicht zwei Anweisungen, zwischen denen man wählen müsste. Wenn pull erfolgreich abschließt und die Ablehnung zurückkehrt, haben die beiden Aufrufe über unterschiedliche Eingaben aufgelöst – meist catalog_dirs, das dem einen übergeben wurde und dem anderen nicht, oder eine zwischen ihnen bearbeitete Workspace-Konfiguration – und die Ablehnung sagt das: Rufen Sie beide mit denselben auf.
validate und describe sind, wenn ihnen nur ein release übergeben wird, an dasselbe Lockfile gebunden. Bei einem Lockfile, das nicht mehr zu dem passt, wozu das Release aufgelöst wird, lehnt jedes ab, statt zu antworten, und sein Text enthält den Drift-Abbruch, mit dem build ablehnt, und denselben Weg, ihn zu beheben — so wie aggrega validate --release und aggrega inspect --closure im Terminal ablehnen. Mit einem passenden Lockfile oder ganz ohne antwortet jedes so, wie es das sonst tut.
Einen Build auffordern, zuerst seine Abhängigkeiten aufzulösen
Senden Sie auto_pull, und der Build löst auf, bevor er rendert. Er führt dieselbe Auflösung aus, die pull ausführt – die Operation selbst, nicht eine zweite, für einen Build geschriebene, sodass ein von einem Build befüllter Workspace und einer, der von einem pull-Aufruf befüllt wurde, identisch befüllt sind –, schreibt das Lockfile des Release und rendert dann gegen das, was er geschrieben hat. Dieser Schritt erreicht eine Registry und schreibt, was sonst nichts an build tut außer write, und write erreicht keine Registry – daher ist er deaktiviert, sofern er nicht angefordert wird.
Er beantwortet die beiden oben genannten Ablehnungen, ohne das Protokoll zu verlassen. Ein Release, das noch niemand aufgelöst hat, rendert aus den Pins, die gerade vorhanden sind, und weist den Rest zurück; ein abgedriftetes Lockfile stoppt den Build ohne Weiteres. Das Senden von auto_pull löst zuerst auf und rendert gegen ein Lockfile, das aus der Hülle abgeleitet ist, um die es bei diesem Build geht, sodass beide Fälle als Rendering zurückkommen statt als etwas, das man erst beheben muss. Wenn Sie die Auflösung und das Rendering als getrennte Schritte wünschen – um zu lesen, was gepinnt wurde, bevor es gerendert wird –, rufen Sie pull und dann build auf; das sind dieselben zwei Operationen mit einem Blick dazwischen.
Ein Aufruf rendert das Release einmal. Herauszufinden, welche entfernten Referenzen ein Release verwendet, ist selbst ein Rendering, also hat eine Auflösung das Release, um das es beim Build geht, bereits gerendert – gegen genau die Pins, die sie gerade geschrieben hat, mit jeder Prüfung, die ein Build ausführt. Der Build wird aus diesem Rendering beantwortet, statt es zu wiederholen, weshalb das Senden von auto_pull eine Auflösung kostet und kein zweites Rendering. Nur ein Rendering, das abgeschlossen wurde, wird so verwendet: Wenn eine Auflösung ihre Abhängigkeiten gepinnt hat, die Ermittlung der externen Referenzen aber nicht abschließen konnte, rendert der Build selbst gegen die Pins, die tatsächlich geschrieben wurden, und eine nicht gepinnte Referenz hält ihn dann unter ihrem Namen an, statt als Dateiliste zurückzukommen, die hinter dem zurückbleibt, was ein Build ausgibt.
Was zurückkommt, sagt, was aufgelöst wurde. Ein Build, der befüllt hat, trägt dependency_resolution in seiner Antwort, in der Form, in der pull antwortet: das Lockfile, das er geschrieben hat, jede Referenz, die die Auflösung erreicht hat, mit der Version, zu der jede aufgelöst wurde, und woher die Auflösung dieses Builds sie bezogen hat, die Zählungen, die das Lockfile danach enthält, und den eigenen Bericht der Auflösung, Zeile für Zeile. Ein Build, der nicht befüllt hat, trägt dieses Feld überhaupt nicht, sodass Sie die beiden an seinem Vorhandensein unterscheiden, ohne die Festplatte zu lesen. Die gerenderten Dateien werden genau wie bei jedem anderen Build gemeldet und weiterhin im Speicher zurückgegeben, sofern dem Aufruf nicht auch write gesendet wurde – das Auflösen schreibt das Lockfile und den Artefakt-Cache, nie ein Artefakt.
Ein Workspace kann es dauerhaft anfordern, und ein Aufruf kann das nicht abschalten. Die eigene Einstellung auto_pull des Workspace schaltet denselben Schritt für jeden Build in diesem Workspace ein, und auto_pull bei einem Aufruf ergänzt diese Einstellung, statt sie zu überschreiben: Eines von beiden genügt, und es gibt kein Argument, das eine vom Workspace angeforderte Auflösung unterdrückt. Auf dieselbe Weise kombinieren sich die Einstellung und aggrega build --auto-pull im Terminal, sodass ein Workspace gleich antwortet, über welche Oberfläche ein Build auch ankommt.
Das Zurückweisen wird gemeldet statt verschluckt, und mit den Providern, die dieses Binary mitbringt, stoppt ein Zurückweisen das Rendering: Der Provider, der die Referenz angefordert hat, gibt die Ablehnung zurück, sodass der Aufruf mit diesem Fehler antwortet und keine Dateien zurückgibt. Die Referenz wird dort benannt, wo ein Leser darauf reagieren kann, neben dem Befehl, der sie pinnt: aggrega pull --release <path>. Dasselbe Pinnen ist auf dieser Oberfläche als Tool pull erreichbar, beschrieben unten in Auflösen, wovon ein Release abhängt, sodass ein Assistent, der auf diese Ablehnung trifft, darauf reagieren kann, ohne das Protokoll zu verlassen. Ein vollständig gepinntes Rendering sagt zu alldem nichts. Siehe aggrega pull dazu, was das Pinnen abruft und festhält, und aggrega build, wo eine nicht gepinnte Referenz gemeldet wird und den Lauf auf dieselbe Weise anhält.
Die Artefakte dort schreiben, wo aggrega build sie schreibt
Senden Sie write, und das fertige Rendering wird außerdem nach dist/ im Workspace-Stammverzeichnis geschrieben, wo aggrega build es schreibt. Das Verzeichnis ist dasjenige, das die Befehlszeile unter demselben Workspace-Stammverzeichnis zusammensetzt, und der Schreibvorgang ist derjenige, den sie ausführt, sodass für ein Release in einem Workspace aggrega build, das aggrega/build des Language Servers ohne outputParent und dieser Aufruf einen einzigen Baum schreiben, Byte für Byte, und dieses Verzeichnis gleich benennen – die abschließende Zeile des Befehls, das outputDirectory des Language Servers und das output_dir dieser Antwort. Ein dist, das ein Link ist, der aus dem Workspace hinausführt, wird abgelehnt, bevor darin etwas entfernt oder geschrieben wird, wie im Terminal. Weggelassen, was der Standard ist, werden die Artefakte im Speicher zurückgegeben, und es wird nichts geschrieben.
Das Workspace-Stammverzeichnis ist das des Aufrufs selbst. Über Standardeingabe und -ausgabe ist es das Stammverzeichnis des Workspace, den der Aufruf aufgelöst hat, wie In welchem Workspace ein Aufruf beantwortet wird darlegt: das Stammverzeichnis, das workspace_root nennt, sonst das Stammverzeichnis, mit dem der Server gestartet wurde, sonst der Workspace, der von dem Verzeichnis aus gefunden wird, in dem der Server gestartet wurde – und, wenn ein über einen absoluten Pfad benanntes Release den Aufruf in den eigenen Workspace dieses Release verlegt, das Stammverzeichnis dieses Workspace. Es ist das Stammverzeichnis, unter das aggrega build für dasselbe Release und dasselbe benannte Stammverzeichnis schreibt, sodass der Ordner, in dem der Server gerade läuft, nur dann ein dist erhält, wenn dieser Ordner das Stammverzeichnis ist, das der Aufruf aufgelöst hat, so wie es in einem dort geöffneten Terminal wäre. Über HTTP ist es der Workspace, den der Server bedient, und außerhalb davon wird nichts geschrieben.
Schreiben erreicht den Workspace, daher erfordert es über HTTP aggrega:workspace-write. Ein Aufruf, dem write gesendet wurde, erreicht den Workspace für diesen Aufruf, genau wie ein Build, der zuerst seine Abhängigkeiten auflöst: Eine Berechtigung, die nur aggrega:read trägt, wird mit 403 unter Nennung von aggrega:workspace-write beantwortet, und es wird nichts geschrieben, und ein Server, dessen mcp.deny_reach workspace nennt, lehnt den Aufruf unter Nennung dieser Einstellung ab. Das Tool bleibt in der Tool-Liste jedes Aufrufers, und ein Build, dem kein write gesendet wurde, bleibt für einen Aufrufer mit Lese-Scope verfügbar.
Er schreibt zuletzt. Auch mit auto_pull löst der Aufruf auf, rendert und schreibt dann, in dieser Reihenfolge. Ein Aufruf, der an einem früheren Punkt abgelehnt wird – sein Release, sein Workspace, ein Katalogverzeichnis, die Auflösung, das Rendering –, schreibt kein Artefakt.
Die Antwort benennt, was geschrieben wurde. output_dir ist das Verzeichnis – vollständig über Standardeingabe und -ausgabe, dist über HTTP –, und files listet jede geschriebene Datei relativ dazu auf, mit ihrem Inhalt bei response_format: detailed und nur ihrem Pfad bei concise; der Text sagt, wie viele Dateien wohin geschrieben wurden. Ein Aufruf, dem kein write gesendet wurde, trägt kein output_dir, sodass Sie an dessen Fehlen erkennen, dass nichts geschrieben wurde. Ein Schreibvorgang, der fehlschlägt, nachdem das Rendering abgeschlossen ist – etwa in ein Workspace-Stammverzeichnis, in das niemand schreiben darf –, antwortet als Fehler, der das Verzeichnis und die Ursache nennt, und listet keine Datei als geschrieben auf: Ein Teil des Schreibvorgangs kann auf der Festplatte liegen, und die gerenderten Dateien als geschrieben zu bezeichnen, würde mehr behaupten, als geschehen ist.
Kein Argument benennt ein Verzeichnis, und keines fordert einen Trace an. Wohin die Artefakte gehen, entscheidet der Workspace, den der Aufruf aufgelöst hat, nie der Aufruf, und ein von hier aus geschriebener Build hinterlässt kein .trace-Verzeichnis neben seiner Ausgabe; ein Build mit Trace ist aggrega build --trace.
Was Ihnen ein Build neben seinen Dateien mitteilt
Ein Build trägt jeden Hinweis, den er ausgelöst hat, in der Antwort selbst. Das sind die Befunde, die aggrega build während der Arbeit ausgibt – ein Name, der eine Bearbeitung von einem deklarierten entfernt ist, ein Parameter, den nichts liest, ein Ziel, das ein vom Autor geschriebenes Feld nicht berücksichtigen kann, ein nicht anhaltendes Governance-Urteil, ein Begrenzungsverzeichnis, das ein Release von dem Release geerbt hat, das es erweitert, und das zum selben Pfad aufgelöst wird, eine Eigenschaft, die eine Component oder ein Feature, die das Release erreicht, sowohl in der Säule values als auch in der Säule infra deklariert. Keiner davon ändert das Ergebnis: Ein Build mit Hinweisen ist dennoch erfolgreich, und die Dateien, die er zurückgibt, sind die Dateien, die er erzeugt hat. Sie kommen in der Reihenfolge an, in der ein Terminal sie ausgibt, sodass jemand, der beide vergleicht, eine einzige Abfolge statt zwei vorfindet: zuerst alles, was das Rendering ausgelöst hat, in der Reihenfolge, in der es dies ausgelöst hat, dann die Befunde über das Release und das, was es erreicht, die aggrega build ausgibt, sobald das Rendering zurückgekehrt ist, und zuletzt, bei einem Build, dem write gesendet wurde, die Warnung, die jede Datei nennt, die der Schreibvorgang neben seinen eigenen gefunden und nicht geschrieben hat und die er an ihrem Platz lässt – dieselbe, die aggrega build ausgibt, sobald seine Dateien geschrieben sind (Dateien, die der Build nicht geschrieben hat).
Sie stehen in der Antwort und nicht nur im Zusammenfassungstext, weil ein Assistent, der diese Oberfläche steuert, kein Terminal liest, und ein Befund, über den niemand informiert wird, ein Befund ist, der nicht gemacht wurde. Jeder trägt eine severity – warn für etwas, das Aufmerksamkeit erfordert, info für eine festgehaltene Beobachtung – und eine message; einen code, wo seine Klasse einen zuweist, sodass Sie auf eine bestimmte Bedingung reagieren können, ohne Text abzugleichen; und einen key_path, der den Schlüssel im verfassten Dokument nennt, um den es beim Befund geht, sofern es um einen geht. Ein Befund über die Form der bereitgestellten Topologie nennt keinen Schlüssel, weil seine Koordinaten die des Deployments sind und nicht die eines Dokuments, und sagt stattdessen in seiner Meldung, worum es geht.
Zwei Arten von Befunden, die ein Terminal ausgibt, erreichen diese Antwort an einer anderen Stelle als advisories, weil jede einen Ort hat, der mehr aussagt. Eine festgehaltene Deprecation-Markierung steht in deprecations, ob die Lockdatei sie für eine gepinnte Referenz festgehalten hat oder der Plugin-Vertrauensdatensatz daneben für ein Plugin, das in einer Rolle angehängt ist, die ein Urteil über Annehmen oder Ablehnen zurückgibt. describe eines Release nennt dieselbe Menge in seinen eigenen deprecations und validate eines Release unter seinen notices, wobei jedes das Urteil lässt, wie es ist; ein Vertrauensdatensatz, der vorhanden ist und nicht gelesen werden kann, führt zur Ablehnung beider Aufrufe, statt als einer durchzugehen, der nichts festhält. Ein Elternteil, von dem eine Entität erbt und das nicht aufgelöst werden konnte, stoppt den Build, daher wird es im Text der Ablehnung benannt, statt als Befund aufgeführt zu werden, der nichts geändert hat. Eine Art ist durch das begrenzt, was dieses Tool lädt, und nicht durch das, was seine Antwort trägt: aggrega build lädt jedes konfigurierte Katalogverzeichnis, bevor es ein Release auflöst, und ein Hinweis auf eine veraltete Katalogform würde aus diesem Laden stammen, während dieses Tool nur liest, was das Release erreicht, und kein solches Laden ausführt, sodass es keinen solchen Hinweis meldet. Derzeit löst kein Build einen aus, also melden beide dieselben Befunde.
Ein Release, das nichts auslöst, sagt nichts: Der Schlüssel fehlt, statt vorhanden und leer zu sein, sodass allein sein Vorhandensein Ihnen sagt, dass es etwas zu lesen gibt.
Was ein abgelehnter Build zurückgibt
Ein Build, der ablehnt, antwortet in denselben Feldern wie ein erfolgreicher Build, befüllt so weit, wie der Lauf gekommen ist. Er kommt als Fehler gekennzeichnet zurück, mit der Korrektur als Text, und die strukturierte Nutzlast steht neben diesem Text, statt durch ihn ersetzt zu werden. Eine Ablehnung, die während des Renderings des Release ausgelöst wird, liest sich in den Worten des Compilers, wie unten unter Eine beim Rendern ausgelöste Ablehnung beschrieben, und fügt ein eigenes Feld hinzu. Die Hinweise sind darin enthalten: Die gelaufenen Phasen haben ausgelöst, was sie ausgelöst haben, und das sind die Befunde, auf die Sie reagieren müssen, um an der Ablehnung vorbeizukommen, daher kommen sie als Einträge an, die Sie abgleichen können, statt als Fließtext, den Sie parsen müssten. deprecations und declined_external_inputs sind aus demselben Grund enthalten – eine festgehaltene Markierung wird gemeldet, weil eine Markierung festgehalten wurde, und eine zurückgewiesene Referenz, weil eine Referenz zurückgewiesen wurde, und keine dieser Tatsachen ist eine Folge davon, wie der Lauf endete.
files meldet bei einer Ablehnung nichts, und es ist nicht das Feld, aus dem das Ergebnis zu lesen ist. Es wurde nichts ausgegeben, also gibt es keine Artefakte zu benennen. Verzweigen Sie nicht danach, ob der Schlüssel vorhanden ist: Er wird in beiden Fällen gemeldet, und ein leeres files kann für sich allein einen Build, der abgelehnt hat, nicht von einem unterscheiden, der lief und nichts ausgab. Lesen Sie das Fehler-Flag am Ergebnis – das ist das eigene Unterscheidungsmerkmal des Protokolls – und lesen Sie files als das, was es ist: die Liste dessen, was gerendert und, wo dem Aufruf write gesendet wurde, auch geschrieben wurde.
Was die Hinweise bei einer Ablehnung begrenzt, ist, wie weit der Lauf gekommen ist, nicht, was die Antwort tragen kann. Eine Ablehnung durch eine Prüfung, die läuft, bevor das Release aufgelöst ist – ein gepinnter Eintrag im Cache stimmt nicht mehr mit dem für ihn festgehaltenen Digest überein und kein Katalogverzeichnis enthält die gepinnten Bytes, oder das, wovon das Release abhängt, konnte nicht aufgelöst werden –, meldet keine Hinweise, weil bis dahin nichts ausgelöst worden war. Die Befunde darüber, wie sich ein Release mit dem Release zusammensetzt, das es erweitert, werden in dem Moment ausgelöst, in dem es aufgelöst wird, vor jeder folgenden Prüfung, sodass jede spätere Ablehnung sie trägt: Das Manifest bildet einen Typ auf ein Rezept ab, das ihn nicht implementiert, eine Entität, die das Release erreicht, erfüllt ihr Schema nicht, das Lockfile stimmt nicht mehr mit dem überein, wozu das Release aufgelöst wird. Die eigenen Befunde des Renderings werden ausgelöst, während das Rendering läuft, sodass eine Ablehnung durch eine dieser früheren Prüfungen keinen davon trägt und eine Ablehnung durch das Rendering alles trägt, was davor ausgelöst wurde. Lesen Sie advisories bei einer Ablehnung also genau so, wie Sie es bei einem Erfolg lesen: was dieser Lauf gefunden hat, in der Reihenfolge, in der ein Terminal es ausgibt.
Eine Ablehnung, weil eine Entität von einem Elternteil erbt, das nicht aufgelöst werden konnte, benennt jede solche Vererbung in ihrem Text, in den Worten, die aggrega build dafür ausgibt, sodass Sie wissen, welche zu reparieren ist. Dieses Detail ist der Grund, warum der Build gestoppt hat, weshalb es im Text steht und nicht unter den Befunden, die nichts geändert haben; die davor ausgelösten Kompositionsbefunde stehen in advisories wie bei jeder späteren Ablehnung.
Ein Katalogverzeichnis, das das Release liest und das nicht durchlaufen werden kann, wird abgelehnt, bevor irgendetwas geschrieben wird, so wie aggrega build es ablehnt. Das ist ein Verzeichnis, das der Aufruf in catalog_dirs nennt und das nicht existiert, so wie aggrega build ein nicht existierendes --catalog-Verzeichnis ablehnt, oder eines, das vorhanden ist und nicht gelesen werden kann. aggrega build lädt jedes Verzeichnis, das das Release liest, bevor es das Release auflöst, und stoppt bei einem, das es nicht durchlaufen kann; build durchläuft zuerst dieselben Verzeichnisse, ohne darin ein Dokument zu lesen, vor jeder Abhängigkeitsauflösung und vor dem Rendering – sodass ein Build, dem auto_pull gesendet wurde, kein Lockfile schreibt und nichts gerendert wird. Der Text nennt das Verzeichnis so, wie die Befehlszeile es meldet, in einer Zeile: das Verzeichnis, catalog load und den Grund, den das Dateisystem angegeben hat. Die Nutzlast nennt das Release, mit einem leeren files und keinem Befund, weil nichts gelaufen war. Ein Verzeichnis, das die Workspace-Konfiguration auflistet und das kein Verzeichnis ist – dort existiert zum Beispiel nichts –, wird vor diesem Durchlauf abgelehnt, in derselben Form, wobei der Text die Ablehnung enthält, die aggrega build dafür ausgibt, und den Eintrag sowie die Konfigurationsdatei und die Zeile nennt, die ihn auflisten (Woher lokale Entitäten gelesen werden). Ein Katalogverzeichnis, das einen Link enthält, der aus dem Verzeichnis hinausführt, in dem seine Lesevorgänge bleiben müssen, wird im selben Moment abgelehnt, ohne dass etwas geschrieben wird, wobei der Text den Link nennt und wohin er führt – aggrega build lehnt es auf dieselbe Weise ab.
Ein ausgearbeitetes Beispiel, damit die beiden Hälften greifbar werden. Ein Release, das einen Parameter deklariert, den keine Referenz liest, und dessen Rendering dann nicht abgeschlossen werden kann, kommt als Fehler zurück, dessen Text die Ablehnung des Renderings trägt und dessen Nutzlast den Hinweis auf den ungelesenen Parameter mit seiner severity, seiner message, seinem code und seinem key_path trägt – derselbe Eintrag mit denselben Werten, den dasselbe Release in der Antwort meldet, wenn das Rendering abgeschlossen wird – neben dem Eintrag refusal für das, was das Rendering gestoppt hat. Ein Release, das ein anderes erweitert und ein Grenzverzeichnis ohne Template-Variable erbt und dessen Manifest einen Typ auf ein Rezept abbildet, das ihn nicht implementiert, kommt als diese Ablehnung mit einem advisories-Eintrag pro geerbtem Verzeichnis zurück, jeweils mit code inherited-boundary-directory-is-literal. Ein Release, dessen Abhängigkeiten nicht aufgelöst werden können, in einem Workspace, dessen aufgelistete Katalogverzeichnisse alle existieren, kommt als Fehler ganz ohne advisories-Schlüssel zurück, weil nichts ausgelöst worden war, als es stoppte.
Eine beim Rendern ausgelöste Ablehnung
Ein Release, das der Compiler beim Rendern ablehnt – ein Workload, der einen Slot nennt, den seine Component nicht deklariert, eine fehlschlagende Assertion, ein Template, das nicht ausgewertet werden kann –, kommt mit der Ablehnung in den Worten des Compilers und mit jeder Ursache darunter zurück, den Worten, die cli-build für dasselbe Release zurückgibt: der Knoten, der gerendert wird, dann das, was darin abgelehnt hat. Wo die Ablehnung eine registrierte Bedingung nennt, fügt der Text hinzu, wie diese Bedingung heißt – den Kurzcode und den beschreibenden Code zum Abgleichen –, wie explain-error es tun würde. Der Text beginnt mit der Angabe, welche Phase abgelehnt hat: The build failed during rendering; nothing was written to disk. für eine Ablehnung, die das Rendering ausgelöst hat, und The build refused before rendering anything; nothing was written to disk. für eine, die der Compiler-Lauf ausgelöst hat, bevor irgendetwas gerendert wurde – die Komposition des Graphen, mit dem das Rendering arbeitet, lehnt ab, oder eine Assertion, die eine Component oder ein Feature deklariert.
Die Nutzlast trägt dieselbe Ablehnung als einen Eintrag, refusal, sodass ein Aufrufer, der ein Dokument ändern muss, liest, welches und wo, ohne den Satz zu parsen:
file– das Dokument, auf das die Ablehnung verweist: das Recipe eines Workload, das Recipe oder FeatureRecipe, das eine fehlschlagende Assertion deklariert, das Release oder das Aggregate, das einen Eintrag geschrieben hat, den die Komposition des Graphen ablehnt, oder das Aggregate des Release bei einer Ablehnung, die auf kein Dokument verweist.key_path– der Schlüssel dort, sofern die Ablehnung einen nennt:.spec.workloadfür eine Ablehnung, die einen Workload betrifft, der eigene Schlüssel der Assertion unter.spec.assertionsfür eine fehlschlagende Assertion, der eigene Schlüssel des Eintrags für die Ablehnung eines Eintrags. Eine Ablehnung, die einen Workload betrifft, wird auf seinen Schlüsselworkloadgesetzt und nicht feiner, weil der Workload, den eine Prüfung beurteilt, das ist, was sein Template erzeugt hat, und ein Template Zeilen schreibt, die sein Autor nie geschrieben hat; die Pfade, die die Ablehnung innerhalb dieses gerenderten Workload nennt, bleiben in ihrermessage.lineundcolumn– die Position dieses Schlüssels, gezählt ab eins, die Spalte in UTF-16-Einheiten. Fehlen, wenn die Ablehnung keinen Schlüssel nennt oder das Dokument ihn nicht enthält: Eine Position wird nur angegeben, wo eine gefunden wurde.severity–halt, der Schweregrad des Befunds, der einen Build gestoppt hat.codeundshort_code– die beiden Bezeichner der Bedingung, sofern die Ablehnung eine registrierte Bedingung nennt.message– der Text der Ablehnung, genau so, wie er im Text der Antwort erscheint.findings– nur vorhanden, wenn die Ablehnung mehrere Befunde zusammenfasst, wie es die Komposition des Graphen mit jedem gefundenen Verstoß tut: ein Eintrag pro Befund, in der Reihenfolge, in der die Ablehnung sie nennt, jeder in genau dieser Form – mit eigenemfile,key_path,line,column,severity,code,short_codeundmessage. Die eigenen Felder der Ablehnung nennen dann, worauf ihr erster Befund verweist, und ihremessageträgt jeden Befund, wie der Text; die Befehlszeile gibt jeden Befund als eigene Diagnose aus.
Der Eintrag ist immer dann vorhanden, wenn der eigene Lauf des Compilers abgelehnt hat – beim Rendern oder bevor er rendert: bei der Komposition des Graphen oder bei einer Assertion, die eine Component oder ein Feature deklariert, die kein Dokument nennt, sodass ihr Eintrag das Aggregate nennt. Ein erfolgreicher Build trägt keinen, ebenso wenig einer, der durch eine Prüfung abgelehnt wurde, die vor dem Start des Compilers läuft – das Lockfile, die Zuordnungen des Manifest, das, wovon das Release abhängt –, deren Ablehnung allein der Text ist. Ein Wert, den ein Autor als sensibel deklariert hat, wird in der Ablehnung zurückgehalten, wo der Compiler sie auslöst, sodass der Eintrag und der Text das tragen, was cli-build und das Terminal tragen – siehe was eine Ablehnung über einen deklarierten Wert sagt.
Auflösen, wovon ein Release abhängt
pull löst die Katalog- und Quellabhängigkeiten eines Release in den lokalen Cache auf und schreibt das Lockfile dieses Release. Es ist aus einem erwähnenswerten Grund auf dieser Oberfläche: Die beiden oben genannten Ablehnungen – ein Rendering, das eine nicht gepinnte externe Referenz zurückgewiesen hat, und ein Build, der gestoppt hat, weil das Lockfile nicht mehr mit dem übereinstimmt, wozu das Release aufgelöst wird – werden beide durch Pinnen beantwortet, und ein Assistent, der Sie bitten muss, einen Befehl auszuführen, hat keine Möglichkeit, sie selbst zu beantworten. Lesen Sie Was ein Assistent tun kann, ohne Sie vorher zu fragen dazu, was es schreibt und wie weit das reicht.
Übergeben Sie release, den Release-Pfad, absolut oder relativ zum Workspace-Stammverzeichnis – derselbe Vertrag, den jedes andere Pfadargument hier verwendet. workspace_root und catalog_dirs überschreiben die Workspace- und Katalogerkennung genau wie bei build. Beide gelten auf einem Server, der über Standardeingabe und -ausgabe erreicht wird; über HTTPS werden diese beiden Argumente abgelehnt, und der Pfad muss innerhalb des Workspace aufgelöst werden, den der Prozess bedient, wie Ein Prozess, ein Workspace darlegt.
Standardmäßig gleicht es ab, statt neu aufzulösen. Ein Pin, den das Lockfile bereits festhält, wird respektiert und in dieser Version abgerufen, und abgelehnt, statt stillschweigend neu gepinnt zu werden, wenn die Registry diese Bytes nicht mehr bereitstellt. Eine Referenz ohne Pin – neu hinzugefügt oder von Hand aus dem Lockfile entfernt – wird neu aufgelöst und hinzugefügt. Eine Referenz, die nicht mehr zu den aufgelösten Abhängigkeiten gehört, wird entfernt. Eine unveränderte Abhängigkeitsmenge lässt die Datei daher Byte für Byte identisch, einschließlich ihres festgehaltenen Zeitstempels, sodass ein Aufruf, der keinen Pin geändert hat, für niemanden, der den Workspace danach prüft, einen Diff erzeugt.
verify vergleicht und lässt das Lockfile, wie es ist. Es prüft das festgehaltene Lockfile gegen die Auflösung, die der oben beschriebene abgleichende Aufruf jetzt ausführen würde, wobei es die festgehaltenen Pins genau so respektiert wie dieser Aufruf, und kommt bei einer Abweichung als Fehler zurück, oder wenn es kein Lockfile zum Vergleichen gibt – so findet ein Assistent heraus, ob Pinnen nötig ist, bevor irgendetwas das Lockfile neu schreibt. Nichts, was dieser Aufruf festhält, wird geschrieben – weder das Lockfile noch die daneben festgehaltenen Plugin-Identitäten noch ein entity.lock –, während der Inhalts-Cache genau so gelesen und befüllt wird, wie dieser Aufruf ihn liest und befüllt. Es meldet auch die Toolchain, die das Lockfile festhält: die Compiler-Version, die die Datei geschrieben hat, und die Version jedes Kern-Plugins, das dieser Compiler mitbrachte. Das wird zu Prüfzwecken gemeldet und nie mit dem laufenden Binary verglichen, weil die Toolchain nicht zu dem gehört, was das Lockfile pinnt, und ihre Prüfung den Compiler indirekt pinnen würde – ein Toolchain-Unterschied ist keine Abweichung.
upgrade_targets löst die Referenzen neu auf, die Sie nennen, und nichts sonst. Übergeben Sie eine oder mehrere Entitäts-URIs in der schlichten verfassten Form – core/database, keine versionierte Form. Jeder genannte Pin wird verworfen und auf die höchste verfügbare Version neu aufgelöst, während jeder andere Pin und die festgehaltenen externen Eingaben unverändert bleiben. Eine URI, die weder einem festgehaltenen Pin noch einem konfigurierten Anhang entspricht, wird abgelehnt statt ignoriert.
Es gibt bewusst kein Argument, das alles auf einmal neu auflöst. Die Befehlszeile hat diese Form, und sie verwirft das gesamte Lockfile, bevor sie vom aktuellen Registry-Zustand aus neu auflöst. Auf dieser Oberfläche existiert das Argument nicht, sodass der Aufruf gar nicht erst zusammengesetzt werden kann, statt angenommen und dann abgelehnt zu werden: Niemand beobachtet einen Protokollstrom, also hat ein vollständiges Verwerfen niemanden, der es bestätigt. Wo Sie es wünschen, und nur über Standardeingabe und -ausgabe, führt cli-pull den Befehl aus, und das ist die Oberfläche, an der eine Person anwesend ist; ein Aufrufer, der diesen Server über HTTP erreicht, führt ihn stattdessen in einem Terminal auf dem Host aus. verify kann nicht mit upgrade_targets kombiniert werden – das eine lässt das Lockfile, wie es ist, das andere schreibt es neu –, noch mit pin_sources, welchen Wert es auch trägt: Dieses Argument entscheidet, ob eine Auflösung die Pins festhält, die einem entity.lock fehlen, oder deswegen ablehnt, und ein Vergleich schreibt kein entity.lock, würde also keines von beiden tun. Ein Aufruf, der eines der beiden Paare sendet, wird abgelehnt, bevor irgendetwas aufgelöst wird, mit einem Satz, der das Paar nennt. Das angekündigte Schema des Tools gibt diese beiden Ausschlüsse nicht an, weil ein Client, der einen davon darstellt, ihn als Anforderung lesen kann, verify zu senden; die Ablehnung ist der Ort, an dem ein Client sie erfährt. Die Befehlszeile und der Daemon lehnen dieselben Paare ab.
Das Ergebnis benennt, was aufgelöst wurde, nicht bloß, dass etwas aufgelöst wurde. Es trägt das Lockfile, das es geschrieben oder mit dem es verglichen hat; resolved, jede Referenz, die die Auflösung erreicht hat, mit der Version, zu der jede aufgelöst wurde, der Art, die ein Autor schreibt, sofern die Auflösung eine festhält, und ihrer source – woher dieser Lauf die Referenz bezogen hat, mit dem Wort, das aggrega pull --detail für dieselbe Auflösung ausgibt: fetched-fresh, cache-reuse, local, in-binary oder external; die Anzahl der Quellartefakte, externen Eingaben und vertrauenswürdigen Plugin-Identitäten, die das Lockfile danach enthält; und diagnostics, den eigenen Bericht der Auflösung in der Reihenfolge, in der sie jede Zeile ausgelöst hat – welcher Pin wiederverwendet, welche Signatur geprüft, welche Version als zurückgezogen übersprungen wurde. Diese Zeilen erreichen ein Terminal, wenn Sie den Befehl ausführen; hier stehen sie in der Antwort, weil ein Aufrufer, der kein Terminal liest, keinen anderen Weg hat, sie zu erhalten. verified ist nur bei einem Vergleich vorhanden, sodass Sie an seinem Fehlen einen Lauf, der geschrieben hat, von einem unterscheiden, der nur verglichen hat. Eine source beschreibt diesen Lauf auf diesem Rechner, daher hält das Lockfile sie nicht fest, und describe, das meldet, wovon ein Release abhängt, nennt keine.
Eine Ablehnung antwortet in denselben Feldern, befüllt so weit, wie der Lauf gekommen ist. Sobald die Auflösung berechnet wurde, wird resolved unabhängig vom Urteil mitgeführt – ganz besonders bei einem Abweichungsurteil, da dies die Ablehnung ist, bei der ein Aufrufer entscheiden muss, was zu ändern ist. Eine Ablehnung vor diesem Punkt, etwa ein Release-Pfad, der sich nicht auflösen lässt, trägt die Korrektur als Text und keine Auflösung, weil es keine gab, die sie hätte tragen können.
Wenn die Pins vollständig sind und die externen Eingaben nicht, ist der Aufruf dennoch erfolgreich und sagt das. Herauszufinden, welche externen Eingaben ein Release verwendet, ist ein Rendering, und ein Rendering kann fehlschlagen, nachdem die Abhängigkeits-Pins bereits korrekt und auf der Festplatte sind. Den gesamten Aufruf als fehlgeschlagen zu melden, würde Ihnen sagen, korrekte Arbeit zu wiederholen, daher wird stattdessen incomplete_external_inputs im erfolgreichen Ergebnis gesetzt und benennt, was gestoppt hat: Die Abhängigkeits-Pins sind vollständig, die Pins der externen Eingaben möglicherweise nicht.
Dies ist das langsamste Tool hier, und der abgleichende Leerlauf ist kein schneller Pfad. Eine Auflösung zahlt ihre vollen Kosten, um festzustellen, dass eine Abhängigkeitsmenge unverändert ist, sodass ein Aufruf, der nichts neu schreibt, so viel kostet wie eine erste Auflösung – bei einem kleinen Release Sekunden statt Millisekunden, und es wächst mit der Größe der Abhängigkeitsmenge. Ein verify ist die günstigere der beiden Formen, weil ein Vergleich den Abstieg in die Quellen pro Komponente überspringt, den ein schreibender Lauf ausführt. Wenn Ihr Client ein Timeout pro Aufruf vorgibt, ist dies das Tool, an dem Sie es prüfen sollten. Sich über den Fortschritt informieren zu lassen, wie unten beschrieben, bedeutet, dass etwas ankommt, während der Aufruf läuft, statt nichts bis zu seinem Ende – das beantwortet ein Leerlauf-Timeout in Ihrem Client oder in allem, was zwischen Ihnen und einem über HTTP erreichten Server sitzt, aber keine Obergrenze dafür, wie lange ein Aufruf insgesamt dauern darf.
Eine Entität, deren entity.lock keinen Pin für eine Eingabe festhält, die sie liest, lehnt den Pull ab, und die Ablehnung nennt den Schritt, der ihn festhält. Von einem Recipe oder FeatureRecipe, das das Release aus Ihren Katalogverzeichnissen baut und das eine vollständig ausgeschriebene entfernte Quelle liest oder über seine Artefakte eine Datei importiert, wird erwartet, dass es diese Pins bereits neben sich trägt – sein Autor hält sie mit pin fest, siehe unten. pin_sources fordert diesen Aufruf auf, diesen Schritt im Namen des Autors über jede solche Entität auszuführen, statt abzulehnen, und dabei das entity.lock neben jede zu schreiben; es ist derselbe Schritt, den das Tool pin ausführt, und es schreibt dieselben Bytes. Lassen Sie es weg, entscheidet das pin_sources_at_pull des Workspace; senden Sie es, entscheidet es in beide Richtungen, sodass pin_sources: false auch in einem zum Pinnen konfigurierten Workspace ablehnt. Eine Entität, die die Auflösung im Cache statt in einem Ihrer Katalogverzeichnisse erreicht hat, hat hier keinen beschreibbaren Ort und wird von diesem Aufruf nie gepinnt.
Die eigenen Eingaben einer Entität pinnen
pin hält im entity.lock neben einem Recipe oder FeatureRecipe den Inhalts-Pin für jede Eingabe fest, die die Entität von außerhalb ihres eigenen Dokuments liest: eine entfernte Quelle, deren Koordinaten vollständig ausgeschrieben sind, und eine Datei, die ein Artefakteintrag importiert. Es ist derselbe Schritt, den aggrega pin im Terminal ausführt, und das Lock, das es schreibt, ist Byte für Byte identisch mit dem, das dieser Befehl schreibt. Übergeben Sie entity, das Entitätsdokument, absolut oder relativ zum Workspace-Stammverzeichnis nach demselben Vertrag, dem jedes andere Pfadargument hier folgt; über HTTPS muss es innerhalb des Workspace aufgelöst werden, den der Prozess bedient.
Es wird kein Release genannt, weil keines benötigt wird. Eine Quelle, deren Koordinaten kein Template enthalten, benennt ein einziges Artefakt für jedes Release, das die Entität verwendet, sodass der Schritt sie ohne etwas auflöst und pinnt, das ein Release liefert. Eine Quelle, deren Koordinaten aus einem Template stammen, wird hier nicht gepinnt: Welches Artefakt sie benennt, entscheidet jedes Release, und pull pinnt jede Identität, zu der sie aufgelöst wird, im Lockfile dieses Release.
Das Ergebnis sagt, was der Schritt mit dem Lock gemacht hat. Es trägt die entity, ihren kind und ihren name sowie pinnable, das false ist für eine Art, die nichts liest, was ein Lock festhält – eine Component oder ein Feature –; in diesem Fall wurde neben der Entität nichts angefasst, und die anderen Felder fehlen. Andernfalls trägt es das lock, das es geschrieben hat, changed, false, wenn das Lock bereits jeden Pin festhielt und Byte für Byte identisch belassen wurde, removed, wenn die Entität jetzt nichts mehr liest, was ein Lock festhält, und ihr Lock gelöscht wurde, und pins, einen Eintrag pro Pin-Klasse mit der Anzahl, die das Lock danach enthält. dry_run antwortet mit dem Lock, das der Schritt schreiben würde, als content und schreibt nichts neben die Entität; der Inhalts-Cache wird dennoch befüllt, weil die Eingaben genau so aufgelöst werden, wie sie es sonst würden.
Es schreibt innerhalb des Workspace und erreicht die Hosts, die die Quellen der Entität nennen – ein Chart-Repository, einen Git-Host, eine URL –, daher wird es über HTTP für eine Berechtigung zugelassen, die den Scope trägt, der pull zulässt, und für eine, die nur lesen darf, abgelehnt. Über Standardeingabe und -ausgabe ist dieselbe Fähigkeit auch als cli-pin erreichbar, das den Befehl ausführt; über HTTP existiert dieses Tool nicht.
Über den Fortschritt eines langen Aufrufs informiert werden
Ein Aufruf meldet seinen Fortschritt, wenn Sie darum bitten, und darum zu bitten ist ein einziges Feld. Setzen Sie progressToken in das _meta des Aufrufs – eine Zeichenkette oder eine Zahl, frei wählbar. Es kommt in jeder Meldung genau so zurück, wie Sie es geschrieben haben, und es ist das Einzige in einer Meldung, das auf Ihren Aufruf zurückverweist: Eine Meldung beantwortet nichts, daher trägt sie keine ID. Senden Sie kein Token oder senden Sie es als null, und nichts ändert sich – der Aufruf wird genauso beantwortet wie ohne. Ein Token jeder anderen Form wird abgelehnt, bevor der Aufruf irgendetwas tut, unter Nennung der beiden Formen, die es annehmen darf, statt übergangen zu werden: Ein Aufrufer, der um Information gebeten hat und dann auf Schweigen trifft, hat nichts, worauf er reagieren könnte.
Was ankommt, ist notifications/progress, mit Ihrem Token und einem Zähler, der mit jeder Meldung steigt. Es gibt keine Gesamtzahl und keine Meldung, und keines von beiden ist eine Auslassung, die auf Arbeit wartet: Was die Arbeit meldet, ist, dass sie in eine weitere Phase eingetreten ist, sodass eine Gesamtzahl nur erfunden und ein Satz nur hier verfasst statt durchgereicht werden könnte. Zeichnen Sie einen unbestimmten Indikator anhand des steigenden Zählers; es gibt keinen Bruchteil, mit dem sich ein Balken füllen ließe.
Über HTTP wird die Antwort zu einem Ereignisstrom, und zwar erst, wenn tatsächlich etwas gemeldet hat. Sie wird als text/event-stream bereitgestellt, als nicht zu cachen gekennzeichnet und mit X-Accel-Buffering: no für einen Vermittler, der sonst jedes Ereignis bis zum Ende der Arbeit zurückhalten und den Strom in eine langsame Einzelantwort verwandeln würde. Jede Meldung ist ein Ereignis, und die eigene Antwort des Aufrufs ist das letzte Ereignis, bevor der Strom geschlossen wird. Solange die Arbeit ruhig ist, trägt der Strom in Abständen eine Kommentarzeile, die alles, was dazwischen sitzt, als Bytes auf einer aktiven Verbindung erreicht und Ihren Client als gar nichts. Ein Aufruf, der um Fortschritt gebeten hat und auf Arbeit getroffen ist, die keinen meldet, wird dennoch mit einem einzigen JSON-Objekt beantwortet, weil das, was den Strom öffnet, die erste Meldung ist und nicht das Token.
Lesen Sie in einem Strom das Ergebnis aus diesem letzten Ereignis statt aus dem Statuscode. Der Status und die Header werden geschrieben, wenn der Strom geöffnet wird, also bevor die Arbeit erledigt ist, sodass ein Aufruf, der meldet und dann ablehnt, seine Ablehnung als letztes Ereignis unter dem bereits gesendeten Status trägt. Das Schließen der Verbindung mitten im Strom beendet die Arbeit, und es wird nichts weiter dafür geschrieben, genau wie Wie ein Aufruf endet es für jeden anderen Aufruf beschreibt.
Über Standardeingabe und -ausgabe sind die Meldungen Zeilen vor der Antwortzeile, gerahmt wie jede andere Nachricht auf diesem Strom – ein JSON-Objekt pro Zeile, in der Reihenfolge, in der sie geschrieben wurden –, und die Antwortzeile folgt ihnen. Sobald ein Aufruf vorbei ist, wird auf keinem der beiden Transporte etwas gemeldet.
Das Auflösen der Abhängigkeiten eines Release ist das, was hier meldet. pull meldet jedes Mal, wenn die Auflösung in eine Phase eintritt. build meldet nur, wenn es zuerst auflöst – weil Sie auto_pull gesendet haben oder weil die eigene Einstellung des Workspace jeden Build darin zum Auflösen auffordert –, da das Melden zu diesem Schritt gehört: Ein Build, der aus den bereits vorhandenen Pins rendert, erreicht nichts und meldet nichts, sodass ein Token bei diesem Aufruf nichts daran ändert, wie er beantwortet wird. Jeder Aufruf meldet außerdem jeden Schritt, in den seine Arbeit eintritt und auf den sie wartet – das Lesen einer Registry, das Abrufen eines Artefakts oder eines Dokumentationspakets, das erstmalige Kompilieren eines Plugins –, also die Schritte, die die Befehlszeile einer Person neben ihrer Fortschrittsanzeige zeigt. Ein Aufruf, dessen Arbeit auf keinen dieser Schritte wartet, meldet nichts, was harmlos und kein Fehler ist: Die Antwort ist diejenige, die Sie auch ohne erhalten hätten.
Abfragen, welche Verbindung an einer Stelle in einem Dokument geschrieben ist
connection-at-position beantwortet die Frage, die der Verbindungshälfte der beiden oben beschriebenen Tools vorausgeht, für den Fall, dass Sie eine Stelle in einem Dokument statt eines Knotens in einem Graphen vor sich haben — eine Zeile, die Sie in einem Aggregate oder einem Release betrachten. Übergeben Sie file, das Dokument, relativ zum Workspace-Root oder absolut und so von der Festplatte gelesen, wie insertion-point eines liest; position, eine line und ein character, beide ab null gezählt und in den Einheiten gemessen, die position_encoding angibt, genau so, wie insertion-point dieses Argument liest; und release, das Release, dessen kompilierter Graph die Verbindungen festhält. Das Release ist auch für eine Stelle im Aggregate erforderlich: Ein Graphknoten und eine Verbindung existieren nur in einem kompilierten Graphen.
Die Antwort ist eine von zwei Hälften. Liegt die Stelle auf dem Eintrag einer Verbindung, enthält sie graphNode und connection — deren socket, deren alias und das document, in dem die Stelle gelesen wurde —, also genau das, was attach-candidates neben graph_node und release entgegennimmt, und das, was attachment-container entgegennimmt, um anzugeben, wohin eine Anbindung an diese Verbindung gehört; dieser Container liegt innerhalb genau des Eintrags, in den die Stelle fiel. Andernfalls enthält sie noConnectionReason aus einer geschlossenen Menge: no-connection-entry (die Stelle liegt auf keinem Eintrag, in den eine Anbindung geschrieben wird), feature-created-connection (die Stelle liegt auf dem Eintrag des Release für eine Verbindung, die ein Feature gezogen hat) oder unknown-connection (die Stelle liegt auf einem Eintrag, den das Release für eine Verbindung schreibt, die der kompilierte Graph nicht enthält). Die lesbare Antwort nennt den Grund in Worten.
Eine Stelle irgendwo innerhalb eines Eintrags liegt in ihm — auf dem Alias, auf seinem target, innerhalb seiner features —, und wo Einträge verschachtelt sind, gewinnt der innerste. Eine Stelle auf dem Schlüssel eines Sockets selbst, oberhalb der Aliase darunter, liegt in keinem von ihnen. Die Einträge sind diejenigen, die der kompilierte Graph festhält: im Aggregate jede Verbindung, die eine Komponente zieht, an ihrem Eintrag unter dem Alias der Verbindung in dem Dokument, in dem die Komponente verfasst wurde, was für eine Komponente, die ein importiertes Modul beisteuert, das eigene Dokument dieses Moduls ist; im Release jeder Eintrag pro Kante, den es schreibt. Eine als Liste von Zielen geschriebene Verbindung und eine, die der eigene Abhängigkeitsblock eines Features zieht, haben keinen Eintrag, in den eine Anbindung geschrieben wird. Ob ein Schlüssel eine Verbindung ist, wird nie aus seinem Namen abgeleitet.
Es antwortet und hält an. Es schreibt nichts in eine Datei. Ein Dokument, das nicht im Workspace liegt, nicht gelesen werden kann oder kein wohlgeformtes YAML ist, kommt als fehlgeschlagenes Ergebnis zurück, das nennt, was zu ändern ist, wie bei insertion-point; ebenso eine Stelle, der ihre line oder ihr character fehlt, und ein position_encoding außerhalb der drei.
Abfragen, in welchen Container eine Anbindung gehört
attachment-container beantwortet die Frage zwischen einer Kandidatur-Antwort und einer Einfügeposition. Sie haben festgelegt, was an einen Knoten angebunden werden soll; bevor Sie fragen können, wo in einer Datei es zu schreiben ist, müssen Sie wissen, welche Datei und welcher Container darin. Übergeben Sie graph_node — eine Knoten-ID in einem kompilierten Graphen, so wie der Graph sie als Schlüssel führt — und release, das Release, zu dem der Graph gehört. Beide sind erforderlich: Eine Knoten-ID ist ein Schlüssel im Graphen eines Release und bedeutet ohne dieses nichts.
Setzen Sie diesen Pfad nicht selbst zusammen. Die ID eines Knotens und der Pfad des ihn umschließenden Subsystems werden beide mit Punkten zwischen ihren Teilen geschrieben, und ein Punkt ist ein zulässiges Zeichen in einem Namen, den ein Autor eingibt — von außerhalb des Dokuments lässt sich ein struktureller Punkt also nicht von einem Punkt innerhalb eines Namens unterscheiden. Ein von Ihnen zusammengesetzter Pfad würde korrekt aussehen und einen Schlüssel adressieren, den niemand geschrieben hat, und die anschließende Bearbeitung würde diesen Schlüssel anlegen, statt abgelehnt zu werden. Schlimmer noch: Eine Knoten-ID trägt überhaupt keine Spur ihres umschließenden Subsystems. Eine innerhalb von subsystems.billing.subsystems.payments verfasste Komponente hat den Schlüssel ledger, genau wie eine Komponente auf oberster Ebene. Fragen Sie nach dem Container.
Die Antwort enthält node, den betreffenden Knoten; file, das Dokument, in dem dieser Knoten verfasst wurde; und container, den strukturellen Pfad von der Wurzel dieses Dokuments als Liste von Segmenten — ["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. Es ist bewusst eine Liste und kein zusammengefügter String: Ein zusammengefügter Pfad müsste vom Empfänger wieder aufgeteilt werden, womit die oben beschriebene Mehrdeutigkeit einen Aufruf später zurückkäme. Übergeben Sie file und container unverändert an insertion-point.
file ist Teil der Antwort und nicht etwas, das Sie bereits wissen. Ein Knoten, den ein importiertes Modul beigesteuert hat, wurde im eigenen Dokument dieses Moduls unter dem Namen verfasst, den das Modul ihm gegeben hat, sodass sich sowohl die Datei als auch das letzte Segment des Containers von allem unterscheiden, was Sie gesendet haben.
Für eine Anbindung an eine Verbindung, die der Knoten zieht, fügen Sie connection hinzu mit ihrem socket, ihrem alias und ihrem document, das hier erforderlich ist, weil jedes der beiden Dokumente eine solche enthalten kann. Mit aggregate ist die Antwort der eigene Eintrag der Verbindung in dem Dokument, in dem der Knoten verfasst wurde, mit ihrem features-Block zuletzt; eine Verbindung, die das Release gezogen hat, hat dort keinen Eintrag und wird abgelehnt. Mit release ist es der Eintrag pro Kante unter dem Eintrag des Release für den Knoten — ["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"] —, gemeldet unabhängig davon, ob das Release diesen Eintrag pro Kante bereits schreibt, sodass insertion-point die noch zu schreibenden Schlüssel nennt; ein Release, das keinen Eintrag für den Knoten schreibt, wird abgelehnt, da es nicht Sache dieses Tools ist zu entscheiden, wo der Knoten platziert wird. Eine Verbindung, die ein Feature gezogen hat, wird in beiden Dokumenten abgelehnt.
Es antwortet und hält an. Es legt keine Anbindung an, schreibt nichts in eine Datei und verfasst keinen Text. Es entscheidet auch nicht darüber, was angebunden werden darf — das ist attach-candidates. Ein Knoten, den der Graph nicht enthält, oder einer, für den er kein Dokument festhält, kommt als fehlgeschlagenes Ergebnis zurück, das nennt, was zu ändern ist, statt als Antwort mit einem leeren Feld.
Ermitteln, wohin ein Eintrag in einem Dokument gehört
insertion-point beantwortet die Frage, die auf eine Kandidatur-Antwort folgt. Sie haben festgelegt, was angebunden oder verbunden werden soll; nun müssen Sie wissen, wo in der Datei es zu schreiben ist. Es gibt eine Position und die Spalten für die Einrückung zurück, sodass Sie die Bearbeitung anwenden können, ohne das Dokument selbst zu parsen. Da es die eigene Struktur eines Dokuments liest und nicht die Form einer bestimmten Art, indexiert describe-capabilities es unter jeder Entitätsart, auf die Sie eingrenzen.
Übergeben Sie file — das Dokument, relativ zum Workspace-Root oder absolut, und innerhalb des Workspace: Eines, das über einen aus ihm hinausführenden Link erreicht wird, zur Datei oder zu einem Verzeichnis auf dem Weg dorthin, liegt nicht darin und wird auf beiden Transporten abgelehnt — und container, den strukturellen Pfad von der Dokumentwurzel bis zu dem Container, in den der Eintrag gehört, wobei jedes Element ein Mapping-Schlüssel oder eine dezimal geschriebene Sequenzposition ist.
Den Container-Pfad liefern Sie. Das Tool liest die Struktur des Dokuments und leitet nie aus dem Namen, dem Typ oder der scheinbaren Bedeutung von etwas ab, wohin es gehört. Sie sagen, welcher Schlüssel; es sagt, wohin die Einträge dieses Schlüssels in diesem Dokument gehören — welche Segmente des Pfads die Datei bereits enthält, in welchen Spalten ihre Einträge stehen und bis zu welcher letzten Zeile ihr innerster Block reicht. Für die Anbindung eines Features an einen Knoten eines kompilierten Graphen müssen Sie diesen Schlüssel nicht selbst kennen: attachment-container oben meldet das Dokument und den Container, und beide werden hier unverändert übergeben.
Die Antwort ist eine position der Breite null, deren line und character beide ab null zählen; entryIndent und indentStep, die Spalten, in denen zu schreiben ist; und missingContainerKeys, die Container-Schlüssel, die dieses Dokument noch nicht enthält, der äußerste zuerst, die Sie vor dem Eintrag schreiben. entryShape meldet, ob der Container ein mapping oder eine sequence enthält, und meldet unknown, wo der Container noch nicht vorhanden ist oder nichts enthält, weil das Dokument es nicht festgelegt hat — die Form wählen dann Sie. indentStepMeasured gibt an, ob die Schrittweite aus der eigenen Verschachtelung dieses Dokuments gemessen wurde oder ein Ersatzwert für ein Dokument ist, das keine aufweist. Wo precededByLineBreak gesetzt ist, beginnen Sie Ihren Text mit einem Zeilenumbruch: Die Position liegt am Ende der Zeile, auf die der Eintrag folgt, was gültig ist, ob die Datei mit einem Zeilenumbruch endet oder nicht, und kein bereits geschriebenes Byte verändert. Lesen Sie missingContainerKeys auch dort, wo Sie erwarten, dass der Container vorhanden ist — eine Position, die ohne die ihr vorangehenden Schlüssel angewendet wird, erzeugt ein Dokument, das sich nicht mehr parsen lässt.
position_encoding gibt die Einheiten an, in denen der gemeldete Zeichenversatz gemessen wird: utf-8, utf-16 oder utf-32. Es ist hier ein Argument, weil keine der beiden Revisionen dieses Protokolls eine aushandelt, und der Standardwert ist utf-16, den eine Editor-Sitzung verwendet, wenn ein Client nichts aushandelt — ein Aufrufer, der nichts angibt, erhält also auf beiden Oberflächen dieselbe Antwort. Ein Wert, der keiner der drei ist, wird abgelehnt, statt stillschweigend durch den Standardwert ersetzt zu werden, denn auf eine Weise gemessene und in einen anders gemessenen Puffer angewendete Versätze beschädigen das Dokument beim ersten Zeichen außerhalb von ASCII.
Es antwortet und hält an. Es schreibt nichts in eine Datei, verfasst keinen Eintragstext und wendet keine Bearbeitung an; den Text zu verfassen und zu entscheiden, ob er angewendet wird, ist Ihre Sache. Eine Anfrage, die keine Stelle adressiert, an die ein Eintrag gehören kann, kommt als fehlgeschlagenes Ergebnis zurück, das nennt, was zu ändern ist — ein Dokument, das nicht im Workspace liegt, nicht gelesen werden kann oder kein wohlgeformtes YAML ist; ein Container-Pfad ohne Segmente oder mit einem leeren Segment; ein Pfad, der durch einen Skalar führt, in den nichts angehängt werden kann; ein Pfad, der eine im Flow-Stil geschriebene Collection erreicht, bei der das Anhängen bereits vom Autor geschriebene Bytes umschreiben würde, statt eine Zeile hinzuzufügen; oder ein Pfad, der eine Block-Sequenz mit etwas adressiert, das keiner ihrer Indizes ist. Wenn Sie die Bearbeitung lieber anwenden lassen möchten, statt sie selbst anzuwenden, ist Eine begrenzte Bearbeitung auf ein Dokument anwenden das Tool, das dies tut.
Eine begrenzte Bearbeitung auf ein Dokument anwenden
edit-document wendet an, was die beiden oben beschriebenen Tools ermitteln. Ein Aufruf fügt einen Eintrag unter einem Container hinzu oder setzt einen Skalar, und er kann nichts anderes. Es schreibt das von Ihnen angegebene Dokument innerhalb des Workspace, daher benötigt es über HTTPS aggrega:workspace-write: Ein Aufrufer, der nur aggrega:read besitzt, findet es in der Tool-Liste, und ein Aufruf von ihm wird unter Nennung dieses Scopes abgelehnt.
Geben Sie die Bearbeitung in edit an; die Menge ist geschlossen. add-component fügt eine Komponenteninstanz unter einem Komponenten-Container hinzu; attach-feature bindet ein Feature an den von Ihnen angegebenen Knoten an; wire-edge verdrahtet eine Verbindung innerhalb eines der Sockets dieses Knotens; set-value setzt einen Wert an diesem Knoten. Ein Name außerhalb dieser vier wird abgelehnt statt interpretiert. Es gibt keine Bearbeitung, die löscht, einen bereits geschriebenen Block ersetzt, etwas umordnet oder von Ihnen gelieferte Bytes wörtlich schreibt — dies ist also kein Werkzeug zum Schreiben von Dateien und kann nicht als solches verwendet werden.
Übergeben Sie file, das Dokument — relativ zum Workspace-Root oder absolut, und innerhalb des Workspace: Eines außerhalb davon, wie geschrieben oder über einen aus ihm hinausführenden Link, wird auf beiden Transporten abgelehnt, ohne dass etwas gelesen oder geschrieben wird; node, den strukturellen Pfad von der Dokumentwurzel als Liste von Segmenten; name, den Schlüssel, unter dem der Eintrag geschrieben wird; und value, was dieser Eintrag enthält. node ist aus demselben Grund eine Liste, aus dem attachment-container mit einer antwortet: Ein Punkt ist in einem Namen, den ein Autor eingibt, zulässig, sodass ein zusammengefügter Pfad einen Schlüssel adressieren könnte, den niemand geschrieben hat, und der Eintrag dort angelegt statt abgelehnt würde. Für add-component nennt der Pfad den Komponenten-Container selbst, weil der hinzugefügte Eintrag der Knoten ist; für die anderen drei nennt er den Knoten, um den es bei der Bearbeitung geht, und der Container ergibt sich aus der Bearbeitung. socket wird für wire-edge gelesen und sonst ignoriert. Was value bedeutet, ergibt sich aus edit — die Entität, die der Eintrag anfordert, der Knoten, auf den eine Verbindung zeigt, oder der Skalar, auf den ein Wert gesetzt wird —, und es ist ein JSON-Wert seines eigenen Typs: Eine Zahl bleibt eine Zahl, eine Ziffer in Anführungszeichen bleibt Text, und wird er weggelassen, wird gar nichts gesetzt. Ein Mapping oder eine Sequenz wird abgelehnt, weil das Schreiben eines Blocks keine dieser Bearbeitungen ist.
Jedes Byte, das die Bearbeitung nicht berührt, bleibt erhalten. Das Dokument wird nur geparst, um den Container und die Zeile zu finden, an der sein Block endet, sodass Kommentare, Leerzeilen, Anführungsstil, gefaltete und literale Skalare und die Form des abschließenden Zeilenumbruchs vollständig erhalten bleiben, und die Verschachtelungsschrittweite wird aus der eigenen Einrückung des Dokuments gemessen statt vorgegeben. Dieselbe Anfrage an dasselbe Dokument erzeugt dieselben Bytes.
Das Ergebnis muss ein Dokument sein, das Sie auch selbst hätten eingeben können, und daran ist das Schreiben geknüpft. Das zusammengesetzte Dokument wird gegen das Schema seiner eigenen Art geprüft und erreicht die Festplatte nur, wenn diese Prüfung besteht. Eine Anfrage, die etwas erzeugen würde, das das Schema ablehnt, wird abgelehnt, unter Nennung der Eigenschaft, die das Schema nicht zulassen würde, und wo, und die Datei bleibt Byte für Byte, wie sie war — eine abgelehnte Bearbeitung ist also nicht von einer nie versuchten zu unterscheiden, und Sie können eine korrigierte Anfrage gegen das Dokument wiederholen, mit dem Sie begonnen haben. Ein bereits vorhandener Eintrag, der enthält, was Sie angefordert haben, bewirkt nichts; ein Eintrag dieses Namens, der etwas anderes enthält, wird abgelehnt statt ersetzt.
Die Antwort enthält container, den strukturellen Pfad, in dem der Eintrag gelandet ist; created_containers, die Container-Ebenen, die diese Bearbeitung anlegen musste, die äußerste zuerst, leer im gewöhnlichen Fall, in dem der gesamte Pfad bereits vorhanden war; und written, das Dokument, das die Festplatte erreicht hat, leer, wo nichts sie erreicht hat. Lesen Sie created_containers: Eine Bearbeitung, die stillschweigend zwei verschachtelte Blöcke geschrieben hat, die das Dokument nicht enthielt, ist sonst nicht von einer zu unterscheiden, die einem selbst geschriebenen Block einen einzelnen Eintrag hinzugefügt hat.
dry_run tut alles außer schreiben. Das bearbeitete Dokument kommt als content zurück, nichts wird angelegt, und written ist leer — für einen Client, der dem Autor das Ergebnis vorlegt, bevor es gespeichert wird. Jedes andere Verhalten ist das des Schreibens, die Schemaprüfung eingeschlossen, sodass eine Anfrage, die das Schreiben ablehnen würde, auch damit abgelehnt wird. Ohne es wird das Dokument geschrieben und content fehlt, weil das Dokument dann auf der Festplatte liegt und written es nennt.
Ob das, was Sie verdrahten, semantisch zulässig ist — ob ein Socket einer ist, den der Producer deklariert, oder ob die Anwendbarkeit eines Features erfüllt ist —, wird hier nicht entschieden. Das beantwortet validate.
Über Standardeingabe und -ausgabe ist dieselbe Fähigkeit auch als cli-edit-document erreichbar, das den Befehl ausführt und den ausgegebenen Text zurückgibt; über HTTP existiert dieses Tool nicht, und dort wird die Fähigkeit über dieses hier erreicht.
Eine fremde Beschreibung in Entitätsentwürfe umwandeln
import wandelt eine Beschreibung, die ein anderes Tool erzeugt hat — etwa einen aus einem Agent-Builder exportierten Flow —, in Aggrega-Authoring-Dateien als Entwurf um. Es schreibt diese Dateien in den Workspace, den dieser Server bedient, daher benötigt es über HTTPS aggrega:workspace-write: Ein Aufrufer, der nur aggrega:read besitzt, findet es in der Tool-Liste, und ein Aufruf von ihm wird unter Nennung dieses Scopes abgelehnt.
Übergeben Sie source, die zu konvertierende Datei oder das zu konvertierende Verzeichnis. Die Angabe ist absolut oder relativ zum Workspace-Root, derselbe Vertrag, den jedes andere Pfadargument auf dieser Oberfläche verwendet, und auf einem über HTTPS erreichten Server wird sie innerhalb des Workspace aufgelöst, den dieser Server bedient.
Von einem Verzeichnis werden genau die Dateien eingelesen, die die Dateimuster seines Importers auswählen. Ein Chart oder ein Projekt ist ein Verzeichnis, und source kann eines angeben. Dem Importer werden dann diejenigen seiner Dateien in beliebiger Tiefe übergeben, die eines der von seinen Signaturen deklarierten Dateimuster auswählt, jede benannt nach ihrem Pfad innerhalb des Verzeichnisses, mit Schrägstrichen geschrieben, in sortierter Reihenfolge, zusammen mit den Dateien, die seine plugins.importer-Anbindung unter with.sources nennt, unter ihren Basisnamen; eine Verzeichnisdatei und eine with.sources-Datei gleichen Namens werden abgelehnt, statt dass die eine die andere verdeckt. Ein Importer, der keine Dateimuster deklariert, liest eine Datei und lehnt ein Verzeichnis ab, unter der Bedingung An importer that declares no file patterns is handed a directory (Einem Importer, der keine Dateimuster deklariert, wird ein Verzeichnis übergeben), und ein Verzeichnis, das keine von seinen Mustern ausgewählte Datei enthält, wird ebenfalls abgelehnt. Das Verzeichnis bleibt auf sich selbst beschränkt, wo immer es liegt: Ein Link unter den Dateien, die der Import lesen würde, oder zu einem Verzeichnis, der aus ihm hinausführt, wird abgelehnt, bevor etwas gelesen wird, und ein Link zu einem Verzeichnis wird nie betreten — wie Ein Verzeichnis, das Sie importieren darlegt. Auf einem über HTTPS erreichten Server wird das Verzeichnis selbst innerhalb des Workspace aufgelöst, und damit auch jede daraus gelesene Datei.
Der Importer ist einer, den der Katalog Ihres Workspace enthält, oder einer der Core-Importer des Compilers. Die Übersetzung leistet das Importer-Plugin, das das Format der Quelle ankündigt: eines, das der Katalog Ihres Workspace enthält, oder einer der Core-Importer des Compilers, die ihre Formate in jedem Workspace ohne Katalogeintrag bedienen. Dieses Tool wählt ihn aus, führt ihn aus und schreibt, was er erzeugt hat. Eine plugins.importer-Anbindung, deren uri einen Importer über seine Identität und Version nennt — importer/<name>:<version>, wie aggrega plugin add importer es schreibt —, bindet diesen Importer an: Wo er das Format der Quelle ankündigt, ist er derjenige, der ausgeführt wird, in dieser Version, welcher andere Importer das Format auch ankündigen mag, und ihm werden die with-Quellen und -Einstellungen dieser Anbindung übergeben, die kein anderer Importer erhält. Wo mehrere Importer das Format ankündigen und keiner von ihnen allein angebunden ist — darunter ein Core-Importer und ein Importer anderen Namens, den Ihr Katalog für dasselbe Format enthält —, wird der Aufruf unter Nennung dieser Importer abgelehnt, wie Konfiguration beschreibt. Ein von Ihnen angegebenes Format, das kein Importer ankündigt, wird unter Nennung der Fähigkeit abgelehnt, die ein Importer ankündigen müsste — import:langflow für eine Langflow-Quelle —, also dessen, was ein Importer deklariert, den Sie dem Katalog hinzufügen, statt mit einem allgemeinen Fehlschlag, den Sie dann interpretieren müssten.
Ein Core-Importer, den die Maschine des Servers nicht vorhält, wird einmal abgerufen, und zwar vom ersten Import, der ihn benötigt. Der Import ruft ihn aus der Standard-Registry des bedienten Workspace ab, gleicht ihn mit dem Modul ab, das die Compiler-Version veröffentlicht, prüft seine Signatur gemäß der Vertrauensrichtlinie dieser Registry sowie die Host-Funktionen, die er verwendet, so wie ein Pull ein abgerufenes Plugin prüft, und legt ihn im Inhalts-Cache des Workspace ab, sodass jeder spätere Import ihn von dort liest und keine Registry kontaktiert. Nichts anderes wird für ihn geschrieben — keine Lockfile und kein Eintrag vertrauenswürdiger Plugins. Über HTTPS ist dies die einzige Registry, die ein Aufruf dieses Tools den Server kontaktieren lassen kann, innerhalb der Grenze, die Welche Anmeldedaten ein Aufruf verwendet für einen Registry-Lesezugriff setzt: Die Registry ist die Standard-Registry des Workspace, den dieser Server bedient, also eine, mit der dieser Workspace konfiguriert ist; nichts im Aufruf nennt eine Registry oder trägt Anmeldedaten; und der Abruf verwendet die eigene Anmeldung und Vertrauensrichtlinie dieses Hosts. Das Tool erreicht weiterhin den Workspace und nichts darüber hinaus, daher ist aggrega:workspace-write alles, was ein Aufruf benötigt: Was der Abruf hinterlässt, ist ein Modul im eigenen Inhalts-Cache des Workspace. Ein Modul, das die Prüfung nicht besteht, wird wie an einem Terminal abgelehnt, und nichts wird aufbewahrt. Wo das Modul nicht abgerufen werden kann — der Workspace ist offline, seine Registry ist nicht erreichbar oder die Registry enthält es nicht —, wird der Aufruf unter A plugin’s .wasm is not on this machine (Die .wasm-Datei eines Plugins liegt nicht auf dieser Maschine) abgelehnt, unter Nennung des Importers, seiner Version und dessen, was sein Modul auf die Maschine bringt.
Wo der Workspace keinen Katalogordner nennt, liest der Import den Katalog, den seine Standard-Registry veröffentlicht. Ein Workspace, dessen workspace.catalog_dirs, AGGREGA_CATALOG_DIRS und Wurzel keinen Katalogordner nennen, liest den Katalog der Standardbibliothek als einen einzigen signierten Snapshot, unter catalog/snapshot in der Standard-Registry des bedienten Workspace — derselben Registry, aus der ein Core-Importer geholt wird, erreicht zu denselben Bedingungen, ohne dass etwas im Aufruf eine Registry nennt oder Anmeldedaten mitführt. Ein Snapshot wird einmal geholt: Seine Signatur wird unter der Vertrauensrichtlinie dieser Registry verifiziert, und er wird im Inhalts-Cache des Workspace abgelegt und dort als Katalogordner gelesen, an seinen Digest gebunden, ohne dass eine Registry erneut danach gefragt wird. Welchen Snapshot ein Aufruf liest: mit upgrade den neuesten; andernfalls den, den die Aufzeichnung im Ausgabeverzeichnis nennt, über seinen Digest geholt, wo die Maschine ihn nicht vorhält; andernfalls den, den der Workspace zuletzt als den neuesten geholt hat; andernfalls den neuesten. Die Aufzeichnung, die der Import schreibt, nennt den gelesenen Snapshot über seinen Digest, sodass ein späterer Aufruf, der in dasselbe Verzeichnis entwirft, denselben Katalog liest. Offline wird ein Aufruf, der einen Snapshot holen müsste, abgelehnt, wobei genannt wird, was auszuführen ist, und upgrade wird abgelehnt, gleich was die Maschine vorhält, da nur die Registry sagen kann, welcher Snapshot der neueste ist. Eine Registry, die keinen Snapshot veröffentlicht, lässt den Import ohne Katalog, und ein Eintrag warn in diagnostics meldet das. Ein Workspace, der einen Katalogordner nennt, importiert gegen diesen und holt keinen Snapshot, und upgrade ändert dort nichts.
Lassen Sie format weg, wird das Format anhand der Signaturen erkannt, die die Importer deklarieren — die Ihres Katalogs und die der Core-Importer gleichermaßen. Die Plugin-Entität jedes Importers hält sie fest: die Syntax, in der eine Quelle gelesen wird, die Dateinamen, für die eine Signatur gilt, und die Pfade, die der geparste Baum enthalten muss oder nicht enthalten darf. Die Quelle wird geparst, über den Parser, den der Katalog Ihres Workspace für eine Syntax bereitstellt — oder, für eine Syntax, für die Ihr Katalog keinen Parser bereitstellt, über den, den der Compiler selbst mitbringt —, einmal für jede Syntax, in der eine für ihren Namen geltende Signatur sie liest, und verwendet wird das Format des einen Importers, dessen Signatur passt. Der Importer liest die Quelle dann über denselben Parser. Die Signaturen der Core-Importer lesen eine Datei als JSON oder YAML, und diejenigen, die keine Datei nennen, lesen sie als JSON — die des Dify-Importers als YAML —, sodass das Erkennen einer für sich allein importierten Datei sie in beiden liest und keinen Parser im Katalog Ihres Workspace benötigt: Der Compiler bringt einen JSON- und einen YAML-Parser mit, und einer, den Ihr Katalog bereitstellt, wird an dessen Stelle verwendet. Ein Verzeichnis wird auf dieselbe Weise über seine Dateien erkannt: Jede Signatur wird an denjenigen seiner Dateien erprobt, die ihre Muster auswählen, und eine Signatur, die kein Muster deklariert, gilt für keine davon. Die Erkennung liest die von Ihnen angegebene Datei — oder, bei einem Verzeichnis, nur die Dateien, die die Muster einer Signatur auswählen — und kein Netzwerk. Eine Quelle, auf die keine Signatur passt, wird abgelehnt, mit der Aufforderung, format zu senden, und unter Nennung der Formate, die die Importer ankündigen — oder, bei einem Verzeichnis, mit der Aufforderung, eine seiner Dateien für sich allein als source zu senden oder ein format, dessen Importer Dateimuster deklariert, unter Nennung nur dieser Formate —, unter der Bedingung No importer recognises the source (Kein Importer erkennt die Quelle); eine Quelle, auf die Signaturen mehr als eines Formats passen, wird unter Nennung dieser Formate abgelehnt, unter der Bedingung More than one importer recognises the source (Mehr als ein Importer erkennt die Quelle); keine von beiden wird einem geratenen Importer übergeben. Senden Sie format, um das Format in beiden Fällen ausdrücklich zu nennen — bei einem Verzeichnis eines, dessen Importer Dateimuster deklariert, da ein Verzeichnis nur über diese gelesen wird. Ein leeres format wird abgelehnt, statt so gelesen zu werden, als hätten Sie es weggelassen, denn das sind verschiedene Anfragen.
Senden Sie target, um das Manifest zu entwerfen, gegen das das entworfene Release für einen Provider baut. target ist eine Provider-Fähigkeit — das Wort, an das sich das spec.capability eines Recipe bindet, etwa compose oder helm —, und es ist das --target von aggrega import, zusammengesetzt durch dieselbe Operation, sodass ein Aufruf und der Befehl aus derselben Quelle dieselben Dateien entwerfen. Für jeden Komponententyp und jeden Feature-Typ, den die Entwürfe benötigen — bei den Komponenten des entworfenen Aggregate, ihren Verbindungen und seinen Subsystemen, bei den Katalog-Aggregates, die es zusammensetzt, und bei den Anbindungen des entworfenen Release —, in der Reihenfolge, in der die Entwürfe ihn zuerst deklarieren, sucht der Import im Katalog des Workspace nach den Recipes oder, für einen Feature-Typ, nach den Feature-Rezepten, die den Typ implementieren und sich an diese Fähigkeit binden. Wo es genau eines gibt — mehrere Versionen eines davon zählen als eines —, ordnet das Manifest den Typ ihm über seinen fähigkeitsqualifizierten Namen ohne Version zu, etwa compose/postgres, den der erste Pull in der Lockfile auf die höchste verfügbare Version festlegt. Wo es mehrere mit unterschiedlichen Namen gibt, ordnet es dasjenige zu, das nach dem Typ selbst benannt ist, etwa helm/postgres für core/datastore/postgres. Wo es keines gibt oder mehrere, von denen keines so benannt ist, bleibt der Typ ohne Zuordnung, und ein warn-Eintrag in diagnostics nennt ihn und den Grund — die mehreren jeweils mit Namen —, sodass ein Build der Entwürfe unter Nennung jeder seiner Instanzen oder Anbindungen anhält, unter No Recipe is mapped for a component or feature instance (Für eine Komponenten- oder Feature-Instanz ist kein Recipe zugeordnet), bis die Zuordnung hinzugefügt wird. Wo der Importer das Manifest selbst entwirft, um das Recipe zu wählen, über das eine Instanz rendert, oder ein Feature-Rezept unter mehreren, bleibt jede von ihm geschriebene Zuordnung erhalten, die der Katalog für diesen Typ und diese Fähigkeit anbietet, jede andere wird mit einem warn-Eintrag verworfen, und die Typen, die er offen lässt, werden wie oben zugeordnet. Das Manifest wird als manifest.yaml neben dem entworfenen Release entworfen, mit demselben Namen und derselben Version wie das Release, und das spec.manifest des Release wird auf diesen Namen gesetzt — der Kommentar, den der Importer an seiner Stelle geschrieben hat, wird ersetzt, und nichts anderes im Release ändert sich. Ein Release, das bereits ein Manifest nennt, bleibt unverändert, und wo der Import kein Release entwirft, wird das Manifest neben dem Aggregate entworfen, mit dessen Namen und Version, und ein info-Eintrag besagt, dass nichts darauf verweist. Das Manifest und das bearbeitete Release sind Entwürfe wie die anderen: in written, in der Aufzeichnung und unter dry_run zurückgegeben. Ein target, an das sich kein Recipe im Katalog bindet, wird abgelehnt, bevor der Importer läuft, unter An import’s target names a capability no Recipe in the catalog binds to (Das Ziel eines Imports nennt eine Fähigkeit, an die sich kein Recipe im Katalog bindet), unter Nennung des Ziels, wie Sie es gesendet haben, und der Fähigkeiten, an die sich die Recipes des Katalogs binden, und nichts wird geschrieben. Lassen Sie target weg, wird kein Manifest entworfen — außer unter sync, das für das Ziel entwirft, mit dem der frühere Import gesendet wurde; ein leeres target wird abgelehnt, statt so gelesen zu werden, als hätten Sie es weggelassen.
Senden Sie output_dir, um das Verzeichnis anzugeben, in das die Entwürfe geschrieben werden. Lassen Sie es weg, landen sie unterhalb des Root des Workspace, den der Aufruf aufgelöst hat — dort, wo aggrega import sie schreibt, wenn Sie kein Ziel angeben, wo immer Sie es ausführen, und dort, wo aggrega/import des Language Servers sie schreibt, wenn seine Anfrage keines nennt. Das Ziel ist bei allen dreien optional und wird genauso angegeben wie jeder Pfad, den Sie an diesen Server senden. Über HTTP ist es ein Verzeichnis innerhalb des Workspace, den dieser Server bedient, relativ zu dessen Root geschrieben: Ein Wert, der aus dem Root heraussteigt, ein absoluter Ort außerhalb davon und ein Verzeichnis, das über einen Link aus ihm hinausführt — einschließlich eines noch nicht angelegten Verzeichnisses unterhalb eines solchen Links —, werden jeweils unter Nennung von output_dir abgelehnt, und nichts wird gelesen oder geschrieben. Über Standardeingabe und -ausgabe wird es so genommen, wie es angegeben ist, wie jeder Pfad dort: Ein relativer Wert wird gegen den Workspace-Root aufgelöst, den der Aufruf aufgelöst hat, und ein absoluter kann ein Verzeichnis außerhalb des Workspace nennen, in das so entworfen wird, wie aggrega import --output-dir dorthin entwirft. Was dort geschrieben wird, bleibt mit aufgelösten Links auf den Workspace beschränkt — oder, bei einem außerhalb davon angegebenen Verzeichnis, auf dieses Verzeichnis —, sodass ein Link darin, der aus ihm hinausführt, abgelehnt und nichts geschrieben wird. Ein leeres output_dir wird abgelehnt, statt so gelesen zu werden, als hätten Sie es weggelassen. Über Standardeingabe und -ausgabe führt cli-import das --output-dir des Befehls ebenfalls als eigenes output_dir; ein relativer Wert wird dort in dem Ordner aufgelöst, in dem der Befehl läuft: dem Workspace-Root, den der Aufruf nennt, sonst dem, mit dem der Server gestartet wurde, sonst dem Ordner, in dem der Server läuft.
Jeder entworfene Pfad wird gegen das Ausgabeverzeichnis geprüft, bevor irgendetwas geschrieben wird. Ein Pfad, der aus ihm hinausreicht, wird unter Nennung sowohl des Pfads als auch des Verzeichnisses abgelehnt, und es wird überhaupt nichts geschrieben — nicht einmal die Dateien desselben Satzes, deren eigene Pfade in Ordnung waren, denn ein abgelehnter Import, der einen Teil von sich zurücklässt, ist ein Ergebnis, um das niemand gebeten hat. Ein entworfener Pfad stammt vom Importer-Plugin und nicht von Ihnen, weshalb er aus demselben Grund geprüft wird wie ein Pfad, den Sie senden.
Jeder Import, der etwas entwirft, schreibt zusätzlich .aggrega-import.json neben seine Entwürfe: die Aufzeichnung dessen, was er geschrieben hat — das target, mit dem er gesendet wurde, sofern eines gesendet wurde, den Katalog-Snapshot, den er gelesen hat, sofern er einen gelesen hat, und jede entworfene Datei sowie, in einem entworfenen Aggregate oder Release, jeden Schlüssel in jeder Tiefe, mit einem Digest des dort geschriebenen Texts; jede andere entworfene Datei wird als Ganzes aufgezeichnet. Der Text eines Schlüssels ist seine Zeile, die Zeilen seines Werts, wo dieser Wert kein Mapping von Schlüsseln ist, und die Kommentarzeilen, die direkt darüber in seiner eigenen Einrückung stehen. written nennt die Aufzeichnung zusammen mit den Entwürfen, und unter dry_run gehört sie zu den zurückgegebenen Entwürfen. Die Aufzeichnung ist JSON, sodass nichts, was die YAML-Dokumente des Workspace liest, sie liest.
Ein Aufruf überschreibt nie ein Aggregate, das bereits im Ausgabeverzeichnis liegt. Ein Aggregate ist das Dokument, das ein Autor weiter bearbeitet, sobald es entworfen ist, sodass ein Aufruf, bei dem einer seiner Entwürfe auf einer Datei landen würde, die sich als Aggregate liest, unter Nennung des Entwurfs und des Verzeichnisses abgelehnt und überhaupt nichts geschrieben wird — auch unter dry_run, da ein Probelauf ablehnt, was das Schreiben ablehnt. Jede andere Datei, die bereits auf einem entworfenen Pfad liegt, wird überschrieben, und eine Datei, die ein früherer Import entworfen hat und dieser nicht entwirft, bleibt, wo sie ist.
Senden Sie sync, um stattdessen das, was ein früherer Import entworfen hat, mit der Quelle auf den neuesten Stand zu bringen, wobei nur geändert wird, was der Import geschrieben hat. Eine Synchronisierung, der kein target gesendet wurde, entwirft für das Ziel, das die Aufzeichnung nennt, und entwirft so das Manifest, das der frühere Import entworfen hat; eine, der ein target gesendet wurde, entwirft dafür, und die Aufzeichnung nennt es danach. Ein aufgezeichnetes Ziel, an das sich kein Recipe im Katalog bindet, wird wie ein gesendetes abgelehnt, wobei die Ablehnung angibt, dass es das aufgezeichnete Ziel ist. Jeder Teil wird auf drei Arten beurteilt — was laut Aufzeichnung der Import zuletzt dort geschrieben hat, was auf der Festplatte liegt und was die Quelle jetzt entwirft. Ein Teil, den die Quelle so gelassen hat, wie der Import ihn zuletzt geschrieben hat, bleibt genau so, wie er auf der Festplatte ist, ob ein Autor ihn bearbeitet hat oder nicht. Ein Teil, den die Quelle geändert hat, wird neu geschrieben, ein Teil, den sie entfernt hat, wird entfernt — eine entworfene Datei als Ganzes gelöscht —, und ein Teil, den sie hinzugewonnen hat, wird neben den Teilen hinzugefügt, die der Entwurf um ihn herum nennt, jeweils nur dort, wo das, was auf der Festplatte liegt, das ist, was der Import zuletzt geschrieben hat, und nichts enthält, was ein Autor hinzugefügt hat. Alles andere bleibt Byte für Byte erhalten: ein Schlüssel, den ein Autor irgendwo hinzugefügt hat — ein Parameter, ein Feature, auch unter einer entworfenen Component-Instanz, eine weitere Component, die Umgebung, die ein entworfenes Release seinem Autor überlässt —, ein Kommentar, der nicht direkt über einem entworfenen Schlüssel steht, und jede Datei, die die Aufzeichnung nicht aufführt. Das drift der Antwort listet jeden aktualisierten Teil auf — oder, unter dry_run, jeden Teil, der aktualisiert würde — in der Reihenfolge, in der der Entwurf sie nennt, jeweils als change (added, removed oder changed), file, die entworfene Datei, in der er liegt, und key, die zu ihm führenden Schlüssel in einem entworfenen Aggregate oder Release als Liste, leer, wo der Teil die ganze Datei ist; die Textantwort nennt jeden in einer eigenen Zeile mit den Worten, die aggrega import auf die Standardfehlerausgabe schreibt, <change> <key> in <file> oder <change> <file>. Ein leeres drift unter dry_run besagt, dass die Entwürfe mit der Quelle übereinstimmen. Unter dry_run sind die zurückgegebenen Entwürfe die Dateien, die die Synchronisierung schreiben würde, mit dem Inhalt, den sie ihnen geben würde. Eine Synchronisierung, die einen von einem Autor bearbeiteten Teil ändern oder entfernen, einen Teil hinzufügen würde, wo ein Autor bereits einen geschrieben hat, oder einen Teil entfernen würde, der etwas von einem Autor Hinzugefügtes enthält, wird abgelehnt, unter Nennung jedes solchen Teils und des Grundes, und nichts wird geschrieben; ein direkt über einem entworfenen Schlüssel geschriebener Kommentar bearbeitet diesen Schlüssel. Eine Synchronisierung über ein Aggregate, das keine Aufzeichnung aufführt, wird mit einem entsprechenden Hinweis abgelehnt, ebenso eine, deren Aufzeichnung nicht gelesen werden kann, und eine Synchronisierung, deren Importer nicht fertig werden konnte, schreibt nichts. Eine Synchronisierung in ein Verzeichnis, das keine Aufzeichnung und nichts an seinen entworfenen Pfaden enthält, schreibt den gesamten Entwurf. drift ist eine leere Liste für einen Aufruf, der keine Synchronisierung ist.
Die Antwort enthält source, wie Sie sie angegeben haben; format, wie die Quelle gelesen wurde; workspace_root, den Root des Workspace, den der Aufruf aufgelöst hat; output_dir, das Verzeichnis, zu dem die entworfenen Pfade relativ sind; written, die Dateien, die die Festplatte erreicht haben; drift, was eine Synchronisierung aktualisiert hat; diagnostics, einen Eintrag je Konstrukt, das der Importer nicht übersetzen konnte; decisions, wie der Importer jeden Quellknoten zugeordnet hat; und halted. output_dir ist das Verzeichnis, das Sie gesendet haben, oder dieser Root, wo Sie keines gesendet haben, abgelesen an dem, was der Import tatsächlich verwendet hat, und es wird auch unter dry_run gemeldet, wo nichts geschrieben wird, aber jeder entworfene Pfad dennoch relativ dazu ist. Über HTTP wird workspace_root zurückgehalten und mit workspace_root_withheld markiert, weil der Root ein Ort auf dem Host des Servers ist, wie Was eine Antwort über das Dateisystem des Servers aussagt darlegt; output_dir wird zurückgehalten und mit output_dir_withheld markiert, wo es dieser Root ist, und andernfalls mit seinem Namen relativ zum Root angegeben — der Form, die Ihre eigenen Pfade haben —, sodass der Ort der Entwürfe weiterhin in der Antwort steht. Ein Import, den der Importer nicht abschließen konnte, entwirft dennoch, was er konnte, und kommt als Fehlschlag markiert mit dieser vollständigen Antwort zurück — halted auf true, die Dateien, die die Festplatte tatsächlich erreicht haben, in written genannt, und daneben die Diagnosen, die nennen, was fehlt. Das ist ein Teilergebnis, das Sie behalten oder verwerfen können, kein Aufruf, der nichts getan hat.
decisions sagt, wo der Import geraten hat. Es enthält einen Eintrag je Quellknoten, den der Importer zugeordnet hat, in der Reihenfolge des Importers: source_node, die id, den type und die params_summary des Knotens; candidates, jede Katalog-Component, die der Importer dafür abgewogen hat, als component, score, tier und signals — was jedes seiner Signale beigetragen hat, unter table, category, domain_labels, shape und name; chosen, das gewählte target, den mode, in dem er es geschrieben hat — eine reference auf eine vorhandene Component oder ein draft —, und den tier der Wahl; rationale, die Begründung; und swap_hint, wie anders gewählt werden kann. candidates fehlt, wo der Importer keine abgewogen hat, chosen, wo er keine Wahl getroffen hat, und rationale und swap_hint, wo er keine geschrieben hat. Jeder Wert stammt vom Importer selbst — wie er einen Kandidaten bewertet und wo seine Stufen liegen, entscheidet er —, lesen Sie einen Eintrag also als seine Darstellung der Zuordnung. decisions steht unter dry_run und bei einem angehaltenen Import gleichermaßen in der Antwort und ist eine leere Liste für einen Importer, der keine meldet. Die Textantwort nennt jede Entscheidung in einer eigenen Zeile nach den Diagnosen, mit den Worten, die aggrega import auf die Standardfehlerausgabe schreibt: mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, wobei der Score der des besten Kandidaten ist.
dry_run tut alles außer schreiben. Jede entworfene Datei kommt unter drafts mit ihrem Pfad relativ zu output_dir und ihrem Inhalt zurück, und nichts wird angelegt — für einen Client, der Ihnen das Ergebnis vorlegt, bevor es gespeichert wird. Jedes andere Verhalten ist das des Schreibens, derselbe Importer über dieselbe Quelle, der dieselben Diagnosen meldet, sodass eine Quelle, die das Schreiben ablehnen würde, auch damit abgelehnt wird. Ohne es liegen die Dateien auf der Festplatte und written nennt sie, und drafts fehlt, statt Bytes zu wiederholen, deren Schreiben Sie angefordert haben.
Die Entwürfe sind ein Ausgangspunkt, der Ihnen gehört und den Sie weiter bearbeiten. Ob das, was sie aussagen, zulässig ist — ob ein Socket einer ist, den der Producer deklariert, oder ob die Anwendbarkeit eines Features erfüllt ist —, wird hier nicht entschieden. Das beantwortet validate.
Über Standardeingabe und -ausgabe ist dieselbe Fähigkeit auch als cli-import erreichbar, das den Befehl ausführt und den ausgegebenen Text zurückgibt; über HTTP existiert dieses Tool nicht, und dort wird die Fähigkeit über dieses hier erreicht.
Veröffentlichen, Signieren und Zurückziehen
Vier Tools legen etwas dort ab, wo andere es auflösen werden. publish-entity bündelt eine Katalog-Entität und veröffentlicht sie; publish-artifact veröffentlicht eine eigenständige Datei, etwa ein Dokumentationsbündel, wobei ihre Bytes opak bleiben und kein Entitäts-Envelope geparst wird; sign-artifacts signiert bereits veröffentlichte Referenzen und hängt jede Signatur an, wobei eine Referenz, die bereits eine von der Vertrauensrichtlinie ihrer Registry verifizierte Signatur trägt, unverändert bleibt; deprecate-artifact hängt an eine Referenz eine signierte Rückzugsmarkierung an. Lesen Sie Was ein Assistent tun kann, ohne Sie vorher zu fragen, bevor Sie eines davon zulassen: Dies sind die Tools, deren Wirkungen die Maschine verlassen.
publish-entity nimmt entity entgegen, das zu veröffentlichende Dokument, und ein Plugin benötigt zusätzlich plugin, die in seinem Manifest veröffentlichte ausführbare Datei. publish-artifact nimmt file mit dem name und dem tag entgegen, unter denen sie veröffentlicht wird. Jedes Pfadargument ist hier absolut oder relativ zum Workspace-Stamm, derselbe Vertrag, den jedes andere Tool dieser Oberfläche verwendet, und workspace_root benennt den Workspace, den der Aufruf meint — bei einem Server, der über Standardeingabe und -ausgabe erreicht wird. Ein über HTTPS erreichter Server lehnt workspace_root ab und verlangt, dass sich jeder dieser Pfade innerhalb des Workspace auflöst, den er bedient, wie Ein Prozess, ein Workspace darlegt. registry ist das Ziel und hat als Standard die im Workspace konfigurierte Registry; wird keines von beiden gesendet und ist kein Standard konfiguriert, wird der Aufruf abgelehnt und benennt, was zu senden ist. sign-artifacts nimmt references entgegen, eine oder mehrere Registry-Adressen statt Pfaden, und optional jobs, wie viele davon gleichzeitig signiert werden: Wird es weggelassen, werden sie nacheinander signiert, und ein Wert unter 1 wird abgelehnt, wobei benannt wird, was zu senden ist. Jede wird dennoch genau so signiert, wie sie allein signiert würde, wie aggrega sign beschreibt. deprecate-artifact nimmt entweder reference mit severity und reason entgegen oder from, das eine Batch-Datei benennt — und lehnt Inhaltsargumente, die zusammen mit einer Batch-Datei gesendet werden, ab, statt sie zu verwerfen, denn eine Batch-Datei liefert ihre eigenen, und ein stillschweigend ignoriertes Argument liest sich wie eines, das berücksichtigt wurde.
Die beiden Veröffentlichungs-Tools nehmen dry_run entgegen, das zeigt, was eine Veröffentlichung senden würde, ohne eine Registry zu kontaktieren. Es berechnet das Bündel, meldet, was es veröffentlicht hätte, und antwortet mit beyond_this_machine false und dem Ziel, das es angesprochen hätte, in registries; publish-entity antwortet außerdem mit dem digest, den diese Veröffentlichung ergeben würde, demselben, den aggrega push --dry-run ausgibt. So zeigt man jemandem eine vorgeschlagene Veröffentlichung, bevor sie zu einer wird. Signieren und Zurückziehen haben keine solche Form: Beide wirken auf etwas bereits Veröffentlichtes, es gibt also nichts in der Vorschau zu zeigen.
publish-entity antwortet mit windows_unusable_entries, wenn das veröffentlichte Archiv Einträge enthält, die Windows nicht so speichern kann, wie sie geschrieben sind — ein Pfad mit einem Teil, der nach einem Gerät benannt ist, etwa CON, AUX oder NUL, in beliebiger Groß- und Kleinschreibung und mit beliebiger nachfolgender Erweiterung, oder ein Teil, der auf einen Punkt oder ein Leerzeichen endet — und benennt jeden davon, zuerst den Dateinamen des Entitätsdokuments selbst, dann die Dateien, die es mitführt. Das Feld fehlt, wenn es keine gibt, was eine nur als Dokument veröffentlichte Entität einschließt. aggrega lehnt unter Windows das Entpacken eines solchen Eintrags ab, sodass ein Windows-Workspace die Version nicht verwenden kann; dies sind die Einträge, vor denen aggrega push warnt, und auch der Text der Antwort benennt sie. Sie lehnen nichts ab: Der Aufruf wird genau so ausgeführt oder abgelehnt, wie es ohne sie geschähe, dry_run eingeschlossen.
publish-entity nimmt pin_sources entgegen, das den Pin-Schritt des Entitätsautors auf der Entität ausführt, bevor sie gebündelt wird, sodass die entity.lock, die der Schritt daneben schreibt, Teil dessen ist, was veröffentlicht wird. Es ist derselbe Schritt, den das Tool pin ausführt, schreibt dieselben Bytes und läuft vor jeder Ablehnung, die die Entität beurteilt — eine dort abgelehnte Veröffentlichung, etwa wegen einer fehlenden Signatur, hinterlässt die Lock-Datei also trotzdem neben der Entität. Eine Ablehnung, die den Aufruf selbst betrifft, etwa ein Offline-Workspace oder ein fehlendes Ziel, kommt zuerst und pinnt nichts. Lassen Sie es weg, entscheidet pin_sources_at_push des Workspace; senden Sie es, entscheidet es in beide Richtungen. Eine Veröffentlichung, die pinnt, schreibt sowohl in den Workspace als auch in die Registry, benötigt über HTTP also eine Anmeldeinformation mit beiden Scopes, und eine, die nur den Scope für das Veröffentlichen trägt, wird unter Nennung des anderen abgelehnt. Das Ergebnis enthält pin in der Form, mit der das Tool pin antwortet, wenn der Schritt ausgeführt wurde; unter dry_run meldet der Schritt die Lock-Datei, die er schreiben würde, und schreibt nichts. Wird der Schritt nicht ausgeführt, wird ein Recipe oder FeatureRecipe abgelehnt, dessen entity.lock für eine gelesene Eingabe keinen Pin verzeichnet — oder eines, dem die Eingabe nicht mehr entspricht — bevor irgendetwas gebündelt wird, dry_run eingeschlossen, unter Nennung von aggrega pin, pin_sources und pin_sources_at_push. Es ist die Ablehnung, die pull über dieselbe Lock-Datei auslöst, und ihre Prüfung lädt jede entfernte Quelle, die die Entität vollständig ausschreibt, so herunter, wie es der Schritt täte.
Beim Signieren wird die Anmeldeinformation eingesetzt, und drei der vier Tools tun es — die Veröffentlichung eines Datenartefakts signiert nichts und wird anschließend per Referenz signiert. identity_token liefert eine schlüssellose Identität für den Aufruf. Bei einem über Standardeingabe und -ausgabe erreichten Server greift ohne dieses Argument die Identität, die die eigene Umgebung dieses Servers mitbringt, und key_path wählt stattdessen einen offline gehaltenen Schlüssel. Über einen Listener ist keines von beiden erreichbar: Die Umgebung wird nicht gelesen, key_path wird abgelehnt und aus dem herausgenommen, was diese drei Tools ankündigen, und ein Schlüssel, den die Konfiguration des bedienten Workspace benennt, wird nicht erreicht — es signiert also nur ein im Aufruf gesendetes Token, wie Welche Anmeldeinformationen ein Aufruf einsetzt darlegt. Ein Aufruf signiert mit einer Anmeldeinformation. Jede an sign-artifacts gesendete Referenz und jeder Eintrag einer Batch-Datei, die deprecate-artifact liest, wird mit demselben gehaltenen Schlüssel oder derselben schlüssellosen Identität signiert; benennt die Konfiguration des bedienten Workspace einen Schlüssel für die Registry einer Referenz und keinen für die einer anderen, oder zwei verschiedene Schlüssel, signiert der Aufruf nichts und wird unter Nennung der Registries auf jeder Seite abgelehnt, bevor eine Identität aufgelöst oder eine Registry gelesen wird — senden Sie einen Aufruf pro Anmeldeinformation oder über Standardeingabe und -ausgabe einen key_path für alle. Über einen Listener wird kein konfigurierter Schlüssel erreicht, dort wird also jede Referenz mit der Identität signiert, die der Aufruf sendet, und der Aufruf wird deswegen nie abgelehnt. Die Ablehnung ist in References signed together need different signing credentials (Gemeinsam signierte Referenzen benötigen unterschiedliche Signatur-Anmeldeinformationen) beschrieben. fulcio_url, rekor_url und timestamp_url überschreiben die vom Workspace konfigurierten schlüssellosen Endpunkte, auf beiden Transporten. Löst sich überhaupt keine Identität auf, lehnt der Aufruf ab und benennt, was zu senden ist — nichts hier öffnet einen Browser oder wartet auf eine Person, denn niemand beobachtet einen Protokollstrom, und ein hängender Aufruf wäre genau das stille Versagen, das diese Ablehnung verhindern soll. Bei publish-entity richtet sich, ob überhaupt eine Signatur angehängt wird, nach der Richtlinie der Ziel-Registry, sofern sign nichts anderes sagt, und eine Registry, die Signaturen verlangt, lehnt eine unsignierte Veröffentlichung ab, was immer Sie senden: Es gibt kein Argument, das diese Ablehnung umgeht. Siehe aggrega sign für die beiden Signaturmodi und das, was jeder kontaktiert.
Jedes Ergebnis enthält die Fakten statt eines Protokolls: wo das Artefakt gelandet ist, sein Tag, der veröffentlichte Digest — oder, beim Dry Run einer Katalog-Entität, der Digest, den eine Veröffentlichung ergeben würde — ob der Tag bereits auf byte-identischen Inhalt zeigte, ob eine Veröffentlichung signiert wurde, und ihr reach. Ein Signatur-Batch meldet jede signierte Referenz mit dem Digest, auf den sich ihre Signatur festlegt, in der Reihenfolge, in der die Referenzen angegeben wurden, und ein Batch, in dem eine Referenz fehlgeschlagen ist, kommt als Fehlschlag zurück, der jede davon benennt, statt als Ergebnis mit einer verkürzten Liste — ein als Erfolg gemeldeter Teil-Batch ist genau der Weg, auf dem eine Ablehnung als Bestehen gelesen wird. Eine Deprecation meldet jede Markierung mit ihrem eigenen Digest, da eine Markierung als ungetaggter Referrer des zurückgezogenen Artefakts angehängt wird und nichts anderes sie adressiert. Das Signieren oder Zurückziehen einer Referenz, die nichts veröffentlicht hat, wird abgelehnt, statt an nichts angehängt zu werden.
Die beiden Teile einer Antwort
Jedes Tool antwortet mit einem lesbaren Text und, wo immer die Operation eines hat, mit einem strukturierten Ergebnis daneben. Der Text ist für eine Person geschrieben, die die Unterhaltung liest. Das strukturierte Ergebnis trägt dieselbe Antwort als Felder, die ein Programm liest — ein Urteil, eine Liste von Dateien, eine Diagnose — und auch eine Ablehnung trägt eines, wenn die Operation bei der Ablehnung Befunde vorliegen hatte, wie Was ein abgelehnter Build zurückgibt für einen Build beschreibt.
Das strukturierte Ergebnis enthält auch den Text, als text_answer. Das strukturierte Ergebnis jedes Tools hat ein Feld text_answer, das den Text der Antwort genau so enthält, wie der Text ihn trägt: jeden Satz, in Reihenfolge, unverändert. Ein Client, der seinem Modell das strukturierte Ergebnis statt des Textes übergibt, wie es Claude Desktop tut, übergibt ihm also dennoch jeden Satz des Textes — die Zeile, mit der die argumentlose Antwort von describe-capabilities beginnt, die geltende Konfiguration, die config-show meldet, den Satz, der den Ordner benennt, den eine Antwort verwendet hat, wenn kein Workspace gefunden wurde. text_answer wird zuerst geschrieben, vor den Feldern, mit denen das Tool antwortet, und es ist der Text, den der Aufrufer erhält: Über HTTP benennt es jeden Ort auf dem Host des Servers so, wie der Text es tut, wie Was eine Antwort über das Dateisystem des Servers aussagt darlegt. Der Text selbst bleibt die Prosa, die er ist, für die Clients, die ihn lesen, sodass dieselben Worte in jeder Antwort zweimal übertragen werden.
Kein Tool ist eine Ausnahme, auch lint nicht. Kein Tool antwortet mit einem eigenen Feld namens text_answer, sodass das Feld nie an die Stelle eines solchen tritt. Das strukturierte Ergebnis von lint behält sein summary — die Anzahl der geprüften Entitäten und der Befunde, insgesamt und nach Schweregrad, unter den Namen, die aggrega lint mit -o json schreibt — und trägt text_answer daneben. Auch describe-capabilities behält seine eigenen Felder: version_summary, die Versionszeile für sich, wenn es ohne Argumente aufgerufen wird, und in jedem Eintrag seines index ein summary, den einzeiligen Zweck dieses Tools.
Kein Tool kündigt ein Ausgabeschema an. Die Auflistung eines Tools enthält ein Schema für die Argumente, die es entgegennimmt, und keines für sein Ergebnis, daher wird text_answer hier statt in einem Schema benannt.
Eine Antwort ohne strukturiertes Ergebnis ist allein ihr Text. Die Ablehnung der Argumente eines Aufrufs und jeder andere Fehlschlag, für den die Operation nichts Strukturiertes zu melden hatte, kommt als Text und nichts anderes zurück, und der Text ist dann der einzige Teil, den ein Client seinem Modell zeigen kann.
Wenn ein Aufruf nicht gelingt
Wo die Antwort ankommt, hängt von einer Sache ab: ob der Aufrufer das Problem beheben kann, indem er die Argumente eines existierenden Tools ändert.
Alles, was sich so beheben lässt, kommt als eigenes Ergebnis des Tools zurück, als Fehlschlag gekennzeichnet und mit der Korrektur als Text — eine Kombination von Selektoren, die das Tool nicht akzeptiert, ein ausgelassenes erforderliches Argument, ein mit dem falschen JSON-Typ gesendetes Argument, ein Pfad, der sich nicht auflöst, eine Diagnose des Compilers. Das ist der Kanal, der einem Assistenten gezeigt wird, sodass er liest, was schiefgelaufen ist, und mit korrigiertem Argument erneut aufruft.
Der Fehlerkanal des Protokolls ist dem vorbehalten, was kein Tool-Ergebnis hat, in dem es stehen könnte: ein Tool-Name, den der Server nicht bedient, eine Anfrage, deren Parameter er nicht lesen kann, eine Methode, die er nicht implementiert, und eine Nachricht, die überhaupt kein gültiges JSON ist. Auch das Lesen einer Ressource und das Rendern eines Prompts antworten dort, weil keines dieser Ergebnisse ein eigenes Fehlschlag-Flag trägt.
Das angekündigte Schema eines Tools deklariert auch die meisten Regeln, die seine Argumente erfüllen müssen — welche Selektoren sich gegenseitig ausschließen, welches Argument nur zusammen mit einem anderen sinnvoll ist und welche erforderlich sind —, sodass ein Client, der Aufrufe anhand des deklarierten Schemas zusammenstellt, selten einen Aufruf ausführen muss, um sie zu erfahren. Eine Regel, die das Schema nicht angibt, wird dennoch abgelehnt, mit einem Satz, der sie benennt; die Regel von pull, dass verify nicht mit upgrade_targets oder pin_sources kombiniert wird, ist absichtlich der Ablehnung überlassen, aus dem unter Auflösen, wovon ein Release abhängt genannten Grund.
Was den Server beendet
Über Standardeingabe und -ausgabe beendet das Schließen der Verbindung ihn. Der Server liest eine Nachricht pro Zeile und beendet sich sauber, wenn seine Standardeingabe das Ende des Datenstroms erreicht, sodass ein Client, der die Verbindung schließt, den Server herunterfährt. Das ist auf diesem Transport der Normalfall, denn Sie starten den Befehl nie selbst: Der Client, der ihn gestartet hat, beendet ihn auch, sodass das Beenden Ihres Editors oder das Deaktivieren dieses Servers für ein Projekt das ist, wie das Anhalten gewöhnlich aussieht.
Den Prozess selbst zum Beenden aufzufordern erreicht den Server auf beiden Transporten. Ein Interrupt von einem Terminal oder eine Beendigungsanforderung von einem Supervisor oder einer Container-Laufzeit fährt ihn bei der ersten Anforderung herunter, unabhängig davon, ob ein Client gerade etwas sendet: Er nimmt keine Nachrichten mehr an, beendet die Arbeit, die ein laufender Aufruf ausführt, und beendet sich sauber. Eine zweite Anforderung beendet den Prozess sofort. Über Standardeingabe und -ausgabe wird ein Aufruf, der noch läuft, wenn der Prozess zum Beenden aufgefordert wird, daher nicht abgeschlossen; ein Listener dagegen läuft leer und lässt einen Aufruf, der bereits beantwortet wird, innerhalb eines begrenzten Zeitbudgets abschließen, bevor der Prozess sich beendet.
Ein Client kann auch einen einzelnen Aufruf beenden, ohne den Server zu beenden, und wie er das tut, hängt vom Transport ab. Aufrufe werden nebenläufig beantwortet, daher wird das Beenden eines Aufrufs bearbeitet, während dieser Aufruf noch läuft, statt hinter ihm zu warten. Über Standardeingabe und -ausgabe benennt ein Client die ID des Aufrufs; das Abbrechen eines bereits beantworteten Aufrufs oder eines, an dem der Server nicht arbeitet, bewirkt nichts — was es sicher macht, eine solche Nachricht zu senden, ohne vorher zu wissen, ob die Antwort bereits unterwegs ist. Über HTTP gibt es keine Nachricht zu senden: Das Schließen der Verbindung, die den Aufruf getragen hat, beendet ihn. In beiden Fällen wird dem Aufruf mitgeteilt, dass er anhalten soll — seine Arbeit endet am nächsten Punkt, an dem die Operation prüft, und eine Operation, die nie prüft, läuft bis zu ihrem Ende —, für diesen Aufruf wird nichts weiter gesendet, jeder andere laufende Aufruf läuft weiter, und der Server bedient weiterhin.
Wann es zu verwenden ist
Verwenden Sie aggrega mcp, wenn ein KI-Assistent beim Verfassen von Aggrega-Entitäten anhand der echten Schemas und Referenz helfen soll — sodass seine Vorschläge auf der exakten Struktur beruhen, die der Compiler akzeptiert, statt geraten zu sein. Es passt direkt in die Authoring-Schleife: Der Assistent liest das Schema und die Referenz einer Art, erstellt ein Gerüst, füllt die Felder aus, die Ihrer Rolle gehören, und validiert, bevor er den Entwurf zurückgibt. Siehe Aggrega-Dateien verfassen für diese Schleife.
Über Standardeingabe und -ausgabe tippen Sie aggrega mcp in der Regel nie selbst ein. Stattdessen benennen Sie es einmal in der MCP-Konfiguration Ihres Clients, und der Client startet und beendet es für Sie. Ein Listener ist der andere Fall: Dort führen Sie den Prozess aus, und er läuft weiter für Aufrufer, die ihn nicht gestartet haben.
Beispiel: Client-Konfiguration über Standardeingabe und -ausgabe
Verweisen Sie einen MCP-Client mit einem stdio-Servereintrag auf den Befehl:
{ "mcpServers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}Die einzige Voraussetzung ist die installierte Binärdatei aggrega im PATH des Clients. Für Konfigurationspfade je Client und Fehlerbehebung siehe Den MCP-Server verbinden. Um ein Schema ohne Client direkt über die Befehlszeile abzurufen, siehe aggrega get-schema.