Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

aggrega mcp

Запуск сервера Model Context Protocol через стандартный ввод и вывод или через HTTP для интеграции с ИИ-помощником

Синтаксис

aggrega mcp [flags]

Описание

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

Флаги

ФлагПо умолчаниюОписание
--listen—Адрес, который прослушивает транспорт HTTP, в одной из двух форм: host:port или unix:, за которым следует путь в файловой системе. Он задаёт, где слушать, и не выбирает транспорт: он читается при —transport http или mcp.transport: http в конфигурации рабочего пространства, а с транспортом stdio отклоняется. Слушатель без сертификата обслуживает открытый текст и допускается только на loopback (127.0.0.1, ::1, localhost) или на Unix-сокете — такую форму принимает сервер за терминирующим прокси; любому другому адресу нужны mcp.tls.cert_file и mcp.tls.key_file, которые этот процесс затем использует, чтобы самостоятельно терминировать TLS. Если задан, переопределяет ключ конфигурации mcp.listen.
--transport—Способ обращения к серверу: stdio передаёт протокол через стандартный ввод и вывод — так к нему обращается клиент, запускающий эту команду как подпроцесс; http обслуживает его через HTTP по адресу, который задаёт —listen или mcp.listen, и через HTTPS, если mcp.tls указывает сертификат и ключ. Если задан, переопределяет ключ конфигурации mcp.transport, значение которого по умолчанию — stdio.

Что делает команда

aggrega mcp запускает сервер Model Context Protocol. До него можно добраться через два транспорта, и --transport выбирает между ними: stdio или http; ключ mcp.transport в конфигурации рабочего пространства — это ключ, который переопределяет флаг, а stdio используется по умолчанию.

Через stdio, транспорт по умолчанию, сервер обменивается данными через стандартный ввод и вывод процесса. В таком виде это не команда, которую запускают интерактивно: клиент с поддержкой MCP запускает её как подпроцесс и говорит по протоколу через stdio; в разделе Подключение сервера MCP указано, где каждый клиент хранит запись, которая её запускает. Запуск превращает CLI в помощника по написанию, знающего Aggrega, прямо в вашем редакторе или чат-клиенте.

Через http сервер обслуживает протокол по HTTP: это один долгоживущий процесс на хосте, к которому обращаются вызывающие стороны, не сидящие за его клавиатурой; он слушает адрес, заданный --listen, или mcp.listen, если флаг не указан. О том, как настраивается этот слушатель и что он принимает, см. Доступ к серверу по HTTPS.

Сервер поддерживает две редакции протокола, 2026-07-28 и 2025-06-18, поэтому клиент любой из них подключается и получает доступ к тем же поверхностям. Редакция указывается в каждом вызове, а не согласуется один раз на соединение. Клиент на 2026-07-28 отправляет версию протокола и свои возможности с каждым запросом и спрашивает у server/discover, что поддерживает сервер; клиент на 2025-06-18 устанавливает то же самое один раз, открывая соединение рукопожатием initialize. В обоих случаях сервер ничего не хранит между сообщениями, поэтому то, что вы отправили первым, никак не влияет на ответ на последующий вызов. Запрос с редакцией, которую сервер не поддерживает, отклоняется с указанием двух допустимых, а не обрабатывается так, будто запрошена одна из них.

Сервер предоставляет подключённому помощнику три поверхности:

  • Промпты — два семейства, и различаются они тем, на что отвечают. Промпты написания отвечают на вопрос «что я пишу»: по одной персоне на роль (разработчик, архитектор, эксплуатация) плюс узкий шаблон для каждой сущности. Каждый задаёт роль и направляет помощника к нужной схеме, справочной странице и руководству по написанию, чтобы его предложения оставались в пределах опор, которыми владеет эта роль. Промпты рабочих процессов отвечают на вопрос «какие вызовы и в каком порядке»: каждый излагает упорядоченную последовательность вызовов инструментов, ведущую к цели, охватывающей несколько операций, с точками принятия решений между ними — создание нового Aggregate и его Release с нуля, перенос существующего чарта, модуля инфраструктуры или файла container-compose в Aggrega, выяснение, почему сборка не компилируется или рендерит не те артефакты. prompts/list перечисляет оба семейства, а prompts/get рендерит один промпт, поэтому набор читается с сервера, а не с этой страницы.

    Промпт рабочего процесса называет вызовы, а выполняете их вы — по одному, читая каждый результат перед следующим. Нет вызова, выполняющего всю цель целиком: каждый инструмент оборачивает одну операцию, которую можно проверить, поэтому к цели ведёт именно последовательность. Персоны написания принимают необязательный kind, на котором следует сосредоточиться, шаблон для сущности его требует, а kind, которому не соответствует ни одна схема, отклоняется со списком допустимых значений, а не молча игнорируется.

  • Ресурсы — справочные материалы только для чтения, отдаваемые непосредственно: schema://<kind> для JSON Schema сущности, langref://<path> для любой страницы справочника по языку, authoring://<topic> для руководства по написанию, catalog://<kind>/<name> для авторского YAML сущности каталога и cli://<command> для справки самой команды, с cli:// в качестве точки входа — эта справка формируется из команд, которые содержит сам сервер, поэтому её чтение не запускает процесс и возвращает тот же текст, что команда выводит для --help. Чтение catalog:// сущности, которой нет в каталоге, получает ответ «не найдено»; если причина в том, что ровно один файл каталога, объявляющий эту сущность, был пропущен при загрузке, сообщение ответа называет этот файл, нарушаемое им ограничение и короткий код условия, а не только URI, — тот самый отказ, с которого aggrega build начинает для того же файла. resources/list перечисляет ресурсы, адресуемые без параметра, а resources/templates/list объявляет форму URI каждого семейства.

  • Инструменты — действия над вашим рабочим пространством; tools/list возвращает их все.

    Инструменты, с которыми помощник сталкивается первыми, рассчитаны на цикл написания: list-entities и list-releases, чтобы узнать, что содержит рабочее пространство; scaffold — заготовка с полями, которые требует её вид, и заполнителем везде, где нужно значение, — или, если отправлен example, запись одного из запускаемых примеров документации в новый каталог с ответом в виде расположения этого каталога, записанных файлов и команд для его сборки, а если отправлен list: true, — список примеров; get-schema для JSON Schema сущности; validate для черновика (он называет каждый заполнитель, оставшийся в черновике, и что тот принимает); describe для сущности каталога — или сущности, прочитанной из её реестра по ссылке; pull, чтобы разрешить зависимости Release в локальный кэш и записать его lockfile; build, чтобы собрать Release в отрендеренные артефакты — по умолчанию в памяти, без записи артефактов на диск, или с записью в dist/ в корне рабочего пространства, куда их пишет aggrega build, если вы отправите write (а зависимости сначала разрешаются, только если вы отправите auto_pull); gen-catalog для генерации сущностей Plugin из гостевых модулей Wasm; и explain-error, чтобы развернуть диагностику компилятора в практические рекомендации — в том числе, если диагностика начинается с короткого кода останавливающего условия, это условие и опубликованное пошаговое описание исправления, то же развёртывание, которое aggrega explain даёт для того же кода в терминале.

    Остальная поверхность находится в том же ответе, а не за ним: другие инструменты, работающие внутри сервера, — lint, инструмент, называющий соединение, записанное в определённом месте документа, два инструмента кандидатуры, инструменты контейнера вложения и точки вставки, инструмент, применяющий одну ограниченную правку к документу, pin, записывающий пины содержимого для входных данных сущности, как описано в разделе Закрепление собственных входных данных сущности, и четыре инструмента публикации, описанные ниже, а также описи кэшей и настроенных реестров — и, для клиента, запустившего этот сервер через стандартный ввод и вывод, по инструменту на каждую команду, которую вы иначе могли бы набрать, названному по пути её вызова. Эти инструменты команд существуют только на этом транспорте: сервер, доступный по HTTP, не предлагает ни одного из них по причине, указанной в разделе Доступ к серверу по HTTPS. Ничего не откладывается на более поздний вызов. Какую часть списка инструментов показывать модели, решает клиент — он получает определения и выбирает, что загрузить, — а определение, которое клиент так и не получил, — это операция, которую модель никогда не сможет вызвать, как бы доступно ни было имя инструмента в протоколе. Если весь список больше, чем примет ваш клиент, сократить его можно способом, описанным в разделе Сужение того, что объявляет сервер. describe-capabilities сужает эту поверхность до вида сущности, который вы пишете. Получив kind, он возвращает инструменты, обслуживающие этот вид, определяя их по видам, которые объявляет каждый инструмент, а не по словам в описании; без аргументов он возвращает тот же индекс по всем инструментам, которые предлагает вам этот сервер, — имя каждого, назначение в одну строку, обслуживаемые виды и то, выполняет ли он запись, без схем аргументов, так что вся поверхность приходит одним читаемым ответом. Для инструмента cli- выполнение записи определяется тем, пишет ли запускаемая им команда: cli-build считается записывающим, поскольку команда сохраняет отрендеренные артефакты в корне рабочего пространства, как и cli-scaffold, поскольку при отправке example команда записывает один из запускаемых примеров документации в новый каталог, а команда, которая только читает, считается только читающей, даже если по пути она заполняет кэш, общий для всех проектов на машине, как и инструмент, выполняющий ту же операцию внутри сервера; получив tools с одним или несколькими именами, он возвращает полные определения и схемы аргументов именно этих инструментов. Инструменты cli- никогда не сужаются по виду, поскольку нигде не записано, какой вид сущности обслуживает команда, поэтому ответ с ограничением по виду их не включает, и читать их следует в индексе без аргументов. Аргументы инструмента команды называются по собственным флагам команды, так что --output-dir отправляется как output_dir, а нераспознанное имя отклоняется со списком допустимых написаний, а не молча отбрасывается.

    Некоторые возможности представлены дважды на стандартном вводе и выводе: инструмент, рассчитанный на цикл написания, выполняет операцию внутри сервера, а инструмент, названный по команде с той же возможностью, запускает эту команду. Ведут они себя по-разному, поэтому на этом транспорте каждый из них называет другой и указывает разницу; по HTTP командных инструментов нет, и фраза о паре не выводится, чтобы не указывать на инструмент, недоступный вызывающей стороне. Предпочтительнее тот, что работает внутри сервера: вместе с читаемым текстом он возвращает машиночитаемый результат, так что ассистент получает вердикт, список файлов или диагностику в виде полей, а не стенограммы, которую нужно разбирать. Командный инструмент запускает настоящую команду в отдельном процессе, поэтому делает всё, что эта команда делает на машине, где выполняется, включая запись на диск туда, куда пишет команда, — cli-build записывает отрисованные артефакты в dist/ в корне рабочего пространства, а файлы трассированной сборки — в .trace/ рядом с ним, и возвращаемая им заключительная строка называет этот каталог полностью, — и возвращает только выполненную командную строку и текст, который вывела команда. Используйте его, когда нужен флаг, который объявляет команда, но не принимает другой инструмент.

    Эта командная строка начинается с глобальных флагов, с которыми был запущен сервер и которые определяют конфигурацию, — --config и --offline, если вы их указали, — перед командой и собственными флагами вызова. Поэтому команда читает ту же конфигурацию, что и все остальные инструменты здесь: сервер, запущенный с --offline, выполняет свои команды в автономном режиме, а запущенный с --config — с этим глобальным файлом. Флаг, который вызов передаёт сам, идёт после них и имеет приоритет, так что offline: false в одном вызове обращается к сети только для этого вызова, а возвращаемая командная строка показывает оба. Если сервер был запущен с корнем рабочего пространства — через --workspace-root или AGGREGA_WORKSPACE_ROOT, — командная строка начинается с этого корня в виде --workspace-root, перед этими двумя, так что команда принимает этот каталог за корень рабочего пространства, как если бы её набрали с тем же флагом, и как его принимает каждый инструмент, работающий внутри сервера, а не ищет рабочее пространство от каталога, в котором был запущен сервер. Вызов, передающий workspace_root, называет собственный корень, и командная строка несёт только его — включая пустое значение, которое команда читает так же, как --workspace-root "" в терминале: найти рабочее пространство от каталога, в котором был запущен сервер. Сервер, запущенный без того и другого, корня не передаёт, поэтому его команды находят рабочее пространство от этого каталога по правилу, которое Какое рабочее пространство отвечает на вызов задаёт для всех инструментов, — кроме запуска из настольного пакета с пустым параметром Workspace folder, при котором вызов, не называющий собственного рабочего пространства, не запускает команду и получает отказ, связанный с этим параметром. Команда запускается в корне рабочего пространства, который называет вызов или запуск: собственный workspace_root вызова, прочитанный так, как его читает каждый инструмент, — абсолютный в том виде, в каком отправлен, относительный — от корня, в котором обрабатывается вызов, не указывающий никакого, — и переданный команде в абсолютном виде, иначе — корень, с которым был запущен сервер. Поэтому относительный путь, который вызов передаёт как файл для чтения, — документ для validate, --release или --catalog, — читается внутри этого рабочего пространства, как в терминале, открытом там, а сборка, выполняемая командой, записывает dist/ под этим корнем. Если корень ничем не задан — нет корня запуска и нет workspace_root или он пуст, — команда запускается в каталоге, где был запущен сервер, и читает относительный путь оттуда; workspace_root, не указывающий на существующую папку, передаётся в том виде, в каком был прочитан, — абсолютный как отправлен, относительный в полной форме, — и команда отклоняет его собственными словами. Команде, которую регистрирует плагин расширения команд, ни один из них не передаётся, потому что она передаёт плагину все аргументы, не читая их, а не разбирает глобальные флаги, — как в терминале, так и здесь; запускается она в той же папке, что и любая другая команда.

    Несколько команд намеренно отсутствуют даже на стандартном вводе и выводе, где командные инструменты вообще есть, — по HTTP отсутствуют все они, и это свойство транспорта, а не какой-либо команды. На стандартном вводе и выводе каждая из них исключена по указанной причине: демон и сам этот сервер никогда не вернули бы результат; команде, читающей пароль из терминала, неоткуда его читать; команде, записывающей скрипт автодополнения оболочки, некуда его установить; удаление сохранённых учётных данных действует на общесистемное хранилище, а не на названное вами рабочее пространство; а интерактивное получение токена идентификации не имеет неинтерактивной формы. По той же общесистемной причине отсутствует aggrega plugin run-local, загружающая гостевой модуль .wasm по указанному вами пути: команда предназначена для чтения файла, где бы вы его ни разместили, поэтому нет рабочего пространства, которым её можно было бы ограничить, а чтение происходит в самом процессе ещё до появления гостевого модуля. При выполнении гостевому модулю ничего не предоставляется — ни каталогов, ни сокетов, ни окружения, — но это ограничение на модуль, а не на чтение, поэтому решающим оно не является. Запускайте её в своём терминале, где путь называете вы сами. Подписание и публикация — совсем другой случай, и именно это отличие не даёт им попасть в этот список. Каждая из этих операций определяет идентичность по переданным или окружающим входным данным и явно отказывает, если их нет, поэтому у каждой есть форма, завершающаяся без присутствия человека, — тогда как интерактивное получение токена — действие, которое никакие входные данные не могут удовлетворить даже в принципе. Поэтому они представлены дважды: как команды и как четыре внутрипроцессных инструмента, описанные в разделе Публикация, подписание и отзыв. Там, где командная строка открыла бы браузер, они отказывают и называют, что передать вместо этого, а не ждут человека, которого нет.

В каком рабочем пространстве обрабатывается вызов

Вызов указывает своё рабочее пространство через workspace_root; в противном случае он обрабатывается в рабочем пространстве, над которым был запущен сервер. Если при запуске был указан корень — через --workspace-root или AGGREGA_WORKSPACE_ROOT, — этот корень и является корнем рабочего пространства, как и для флага в любой команде: выше него объемлющее рабочее пространство не ищется, поэтому при запуске указывается папка, содержащая файл .aggrega-config.yaml рабочего пространства, и вызов обрабатывается там как инструментами, работающими внутри сервера, так и инструментами команд. Если при запуске корень не указан, рабочее пространство определяется от каталога, в котором был запущен сервер, точно так же, как его находит команда, набранная в терминале в этом каталоге, — порядок описан в разделе The other ways a project root is recognised, — за исключением запуска из настольного пакета с пустой настройкой Workspace folder: в этом случае такой вызов отклоняется, как описано ниже. Относительный workspace_root читается от корня, в котором обрабатывается вызов, не указывающий никакого, — корня, указанного при запуске, или, если он не указан, корня рабочего пространства, к которому приводит каталог запуска сервера, — так что вызов указывает папку внутри рабочего пространства, например quickstart-ai/1, не зная, где рабочее пространство находится на машине; абсолютный используется как задан. Так его читает каждый инструмент, включая инструменты команд. Если корня, от которого можно прочитать относительный путь, нет — корень запуска не является существующей папкой или это запуск из настольного приложения с пустой настройкой Workspace folder, — относительный отклоняется так же, как вызов, не указывающий никакого. Значение workspace_root, которое не указывает на существующую папку или указывает на файл, отклоняется до того, как инструмент сделает что-либо ещё; в отказе называется аргумент и цитируется значение — абсолютное в том виде, в каком оно было отправлено, относительное в полной форме, в которой оно было прочитано, — так же как команда отклоняет --workspace-root.

Корень запуска, не являющийся существующей папкой, при работе через стандартный ввод и вывод обслуживается как отказ. Если --workspace-root или AGGREGA_WORKSPACE_ROOT указывает на несуществующую папку или на файл, сервер записывает отказ в свой поток ошибок и всё равно запускается, так что клиент, который не показывает пользователю ничего из этого потока, всё же показывает причину. Сервер отвечает на initialize и на запросы списков инструментов, ресурсов и промптов, а каждый вызов, который действовал бы в этом рабочем пространстве, получает отказ: вызов инструмента — как неуспешный результат, чтение сущности catalog:// или страницы документации — как ошибку. В отказе называется флаг либо переменная вместе с задающей её настройкой Workspace folder настольного приложения — настройкой, описанной в разделе Claude Desktop, — и значение цитируется точно в том виде, в каком было передано; значение, которое клиент отправил незаполненным, цитируется так, как пришло, и ничто в нём не распознаётся. Инструмент, запускающий команду, не запускает её для вызова, не указывающего собственное рабочее пространство, поскольку папки, в которой запустилась бы команда, нет, и отвечает тем же отказом. Вызов, указывающий собственное рабочее пространство абсолютным путём, обрабатывается в нём; вызову, указывающему его относительным путём, не от чего его прочитать, и он получает тот же отказ. То, что не действует ни в каком рабочем пространстве, — схема, промпт, справка команды, — обрабатывается как на любом сервере. Слушающий сервер вместо этого отклоняется при запуске, до привязки чего-либо, тем же отказом, чтобы тот, кто его контролирует, увидел сбой там, где его ищет.

Запуск из настольного приложения с пустой настройкой Workspace folder обслуживается как отказ таким же образом. Настольный пакет всегда передаёт серверу AGGREGA_WORKSPACE_ROOT с тем значением, которое содержит Workspace folder, и рядом задаёт AGGREGA_BUNDLE_VERSION, а приложение запускает сервер в папке по собственному выбору — часто в системной папке, — а не в вашем проекте. Поэтому сервер, работающий через стандартный ввод и вывод, запущенный без --workspace-root, в окружении которого есть AGGREGA_BUNDLE_VERSION и пустая или отсутствующая AGGREGA_WORKSPACE_ROOT, не ищет рабочее пространство от папки, в которой был запущен. Он записывает отказ в свой поток ошибок и всё равно запускается, отвечая так же, как при отсутствующем корне запуска: каждый вызов, который действовал бы в рабочем пространстве и не указывает собственного, получает отказ, сообщающий, что настольное приложение запустило сервер с пустой настройкой Workspace folder, поэтому AGGREGA_WORKSPACE_ROOT не указывает корень рабочего пространства, предлагающий задать в Workspace folder папку, содержащую .aggrega-config.yaml вашего рабочего пространства, и сообщающий, что папка, заданная после запуска сервера, вступает в силу после выключения и повторного включения расширения или перезапуска приложения, потому что приложение передаёт настройку серверу только при его запуске. Инструмент, запускающий команду, не запускает её для такого вызова. Вызов, указывающий собственное рабочее пространство абсолютным путём, обрабатывается в нём, а вызов, указывающий его относительным путём, получает тот же отказ, поскольку нет Workspace folder, от которой его можно прочитать; то, что не действует ни в каком рабочем пространстве, обрабатывается как на любом сервере. Сервер распознаёт такой запуск только по AGGREGA_BUNDLE_VERSION: в пакете, который не задаёт эту переменную, пустая настройка читается как отсутствие корня, а запуск, в котором переменная задана вручную и корень не указан, отклоняется так же, как запуск из пакета. Любое другое пустое значение по-прежнему не указывает корень — пустая AGGREGA_WORKSPACE_ROOT при запуске без AGGREGA_BUNDLE_VERSION, --workspace-root, набранный пустым, слушающий сервер, aggrega serve и любая другая команда читают его как незаданное.

Если рабочее пространство не найдено и не указано, ответ, касающийся рабочего пространства, сообщает, какая папка была использована. Если нет корня запуска, у вызова нет workspace_root и ничто не закрепляет рабочее пространство от папки, в которой обрабатывался вызов, вызов обрабатывается в этой папке. Если результат инструмента зависит от рабочего пространства — это те же инструменты, чьи команды выводят предупреждение в командной строке, — его текст заканчивается предупреждением командной строки, <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace, и строкой, которая предлагает отправить workspace_root с папкой, содержащей .aggrega-config.yaml вашего рабочего пространства; ответ, который не зависит от рабочего пространства, например чтение конфигурации или список плагинов, ничего не говорит о рабочих пространствах. Это предложение не добавляет собственного поля в структурированный результат; структурированный результат несёт его в text_answer, где хранится текст, как описано в разделе The two parts of an answer. Инструмент, запускающий команду в отдельном процессе, передаёт собственную строку команды с тем же сообщением в том виде, в каком команда её напечатала. В кэш артефактов в такой папке ничего не записывается: pull или сборка, которой предписано сначала разрешить зависимости, там отклоняется до какой-либо загрузки, с указанием папки и двух выходов — отправить workspace_root или снабдить папку файлом .aggrega-config.yaml с блоком workspace:. Закрепление или публикация сущности Recipe или FeatureRecipe отклоняется так же, если она загружала бы удалённый источник, который сущность записывает полностью, — чтобы закрепить его или сравнить его закрепление, — до загрузки этого источника; если она ничего не загружает, потому что у сущности нет источника, источник локальный или его координаты заполняет каждая сущность Release, она обрабатывается как в любом другом месте. Сборка там, которая ничего не разрешает заранее, всё равно выполняет рендеринг, но внешний вход, закреплённый её lock-файлом и уже отсутствующий в кэше, повторно не загружается: рендерингу вместо этого входа сообщается то же предложение, как сообщается и при офлайн-режиме. Ни один ответ через HTTP не содержит этого предложения: слушающий сервер всегда обслуживает рабочее пространство, которое ему передано или которое он нашёл. Не содержит его и запуск из настольного пакета с пустой настройкой Workspace folder: он отклоняет вызов, не указывающий собственного рабочего пространства, а не обрабатывает его в папке, в которой был запущен.

Вызов, касающийся сущности Release или документа, названного по абсолютному пути, обслуживается в собственном рабочем пространстве этого файла, если ничто другое его не определило. Если при запуске корень не был указан, вызов не передаёт workspace_root, а каталог, в котором был запущен сервер, не закрепляет никакого рабочего пространства, рабочее пространство заново определяется от папки, в которой лежит этот файл, и то, что будет найдено — проект, к которому принадлежит файл, или, если ничего не нашлось, сама эта папка, — и есть то, в котором обслуживается вызов. Этому же правилу следует команда, введённая в терминале, поэтому оно действует для каждого инструмента, вызов которого касается названной им сущности Release или документа сущности: сборки, загрузки, валидации, проверки линтером, описания, перечисления в терминах сущности Release, вопроса об узле графа сущности Release, закрепления версии, публикации сущности, правки и чтения позиции в документе. Если вызов называет и сущность Release, и документ, решает Release. Так клиент, запустивший сервер вне вашего проекта, всё равно получает собранную в нём сущность Release из собственной конфигурации проекта. Остальные пути, которые называет вызов, читаются как обычно — относительный от каталога, в котором был запущен сервер, — а инструмент, выполняющий команду в отдельном процессе, получает ответ из того же рабочего пространства, поскольку команда следует тому же правилу в том же каталоге. Корень, указанный при запуске, workspace_root, переданный вызовом, начальный каталог, который сам находится внутри рабочего пространства, а также сущность Release или документ, названные по относительному пути, используются как есть. По HTTP ничего из этого не возникает: слушатель всегда обслуживает рабочее пространство, которое ему передали или которое он нашёл, и каждый путь, названный вызовом, отсчитывается от него. Не возникает этого и при запуске из настольного пакета с пустой настройкой Workspace folder: такой запуск отклоняет вызов, не называющий собственного рабочего пространства, какой бы файл он ни называл.

Сужение того, что объявляет сервер

mcp.announce_tools перечисляет инструменты, которые объявляет этот сервер, в точности так, как их называет список инструментов. Если ключ не указан, объявляется каждый инструмент этого сервера: это поведение по умолчанию и та форма, которую ожидает клиент, следующий протоколу. Если указан список, объявляются ровно эти инструменты: не вошедший в него инструмент отсутствует в списке инструментов, отсутствует в ответе describe-capabilities и отклоняется, если его всё же вызвать по имени, причём отказ называет этот параметр. Если указан пустой список, не объявляется ничего, поэтому отсутствие ключа и значение [] означают разное, и у параметра нет значения по умолчанию, подставляемого за вас.

Задавайте его там, где клиент на другой стороне ограничивает число инструментов, которые он зарегистрирует, иногда суммарно по всем серверам, к которым он подключён одновременно, и перечисляйте инструменты, нужные этому клиенту. Именно для такого ограничения параметр и существует, а клиент, к которому оно относится, обычно тот, что запустил этот сервер через собственные стандартный ввод и вывод, поэтому, в отличие от остальной части блока mcp, которая настраивает слушатель, запускаемый транспортом http, этот ключ читается при любом транспорте сервера.

Он сужает то, что объявляется, и ничего больше. Указание инструмента здесь ничего не расширяет. Оно не снимает mcp.deny_reach, который полностью отзывает возможность, поэтому указанный здесь инструмент того вида, который отзывает этот параметр, остаётся вне списка и отклоняется с указанием того параметра. Не снимает оно и области действия, которые несёт токен вызывающей стороны: указанный здесь инструмент присутствует в списке независимо от этих областей, а вызов, который они не допускают, по-прежнему отклоняется с указанием области, которая бы его допустила. В обоих случаях вызывающая сторона получает отказ того, другого ограничения, а не этого. Отказ по этому параметру не содержит запроса учётных данных и не называет области, поскольку никакие учётные данные не меняют того, что сервер решил предложить; вместо этого он называет параметр — единственное, с чем может что-то сделать читающий отказ.

Каждое имя должно принадлежать инструменту этого исполняемого файла. Имя, которому не соответствует ни один инструмент, останавливает сервер до того, как он начнёт что-либо обслуживать, а отказ перечисляет имеющиеся инструменты, поэтому опечатка обнаруживается при запуске, а не по молча суженной относительно запрошенной поверхности. Имя из семейства cli-, запускающего команду aggrega в отдельном процессе, принимается на обоих транспортах и ничего не объявляет через HTTP, где такой инструмент изначально не предлагается ни одной вызывающей стороне.

Объявляемый набор фиксируется при запуске процесса, поэтому для его изменения нужен перезапуск, и ничто не расширяет список для уже подключившегося клиента.

Из какого релиза взят сервер

Вызов describe-capabilities без аргументов сообщает, из какого релиза взят этот сервер. Его структурированный ответ содержит server_version — версию, которую исполняемый файл aggrega сообщает о себе, ту же, что aggrega version выводит для того же файла, — а его текст открывается одной строкой с этой версией, перед индексом. Структурированный ответ содержит ту же строку как version_summary, слово в слово, так что клиент, передающий модели только структурированный ответ, передаёт ей и эту строку.

Если сервер запущен настольным пакетом, тот же ответ называет рядом и версию пакета. Пакет не содержит программы: он запускает тот исполняемый файл aggrega, который указан в его настройке Path to the aggrega executable (по умолчанию — имя команды aggrega, которое приложение ищет в своём PATH), поэтому пакет и исполняемый файл устанавливаются отдельно и могут быть из разных релизов, а приложение, в котором указан пакет, показывает только собственную версию пакета. Пакет передаёт серверу свою версию в переменной окружения AGGREGA_BUNDLE_VERSION; сервер считывает её один раз, при запуске, и ответ содержит её как bundle_version. Две версии сравниваются точно в том виде, в каком они записаны, и это корректное сравнение, поскольку пакет и исполняемый файл одного релиза помечаются версией этого релиза в одной и той же форме, а сборка для разработки читается иначе, чем любой релиз. Если версии совпадают, строка называет обе и больше ничего не говорит. Если они различаются, строка сообщает, называя обе, что исполняемый файл и пакет взяты из разных релизов, и указания, которые сервер даёт модели при подключении, открываются тем же предложением, так что модель видит расхождение ещё до того, как задаст вопрос.

Сервер, запущенный не пакетом, сообщает только собственную версию. При запуске из терминала, из конфигурации редактора или в роли слушателя он не содержит bundle_version, если только что-то не задаёт эту переменную в его окружении. Сервер, работающий через стандартный ввод и вывод и имеющий эту переменную, считается запущенным пакетом ещё в одном отношении: если корень не указан, он отклоняет пустую настройку Workspace folder, как описано в разделе Which workspace a call is answered in. Вызов describe-capabilities с kind или tools не содержит server_version, bundle_version и version_summary, а также такой строки, поскольку он отвечает об инструментах, а не о сервере.

Расхождение сообщается, но никогда не приводит к отказу. Сервер запускается и отвечает на каждый вызов точно так же, как если бы версии совпадали. Что расхождение означает для настольной установки и как согласовать версии, описано в разделе Подключение сервера MCP.

Доступ к серверу по HTTPS

aggrega mcp --transport http обслуживает протокол по HTTP вместо стандартного ввода и вывода. mcp.transport в конфигурации рабочего пространства — ключ, который переопределяет этот флаг, а его значение по умолчанию, stdio, — то, чего ожидает клиент, запускающий команду, поэтому сервер, к которому обращаются другие люди, содержит transport: http в своей конфигурации, а клиент, запущенный из каталога, на который распространяется эта конфигурация, по-прежнему обращается к серверу через собственные потоки. В обоих случаях это один и тот же сервер — то же рабочее пространство и те же поверхности протокола, — а меняется то, как до него доходит сообщение, как завершается вызов и что должен иметь тот, кто его запускает. В этом разделе описано то, что настраивает оператор; запись, которая нужна клиенту, чтобы обратиться к работающему серверу, приведена в разделе Подключение сервера MCP.

Адрес не выбирает транспорт. --listen <address> или, если флаг не указан, mcp.listen задаёт, где привязывается слушатель после выбора http, и ничего больше. Поэтому http без адреса из любого из этих источников отклоняется до какой-либо привязки, и в отказе названы оба. --listen, указанный при транспорте stdio — заданном как --transport stdio, настроенном как mcp.transport: stdio или оставленном по умолчанию, — тоже отклоняется с указанием --transport http как флага, который обслуживал бы этот адрес; --listen с пустым значением отклоняется как не задающий адреса при любом транспорте. А адрес, заданный только в конфигурации, не используется сервером, работающим через собственные потоки, и тот сообщает об этом одной строкой в потоке ошибок, называя файл, который его задал, и mcp.transport: http. Последний случай намеренно нигде не отклоняется: именно так клиент запускает команду в каталоге, конфигурация которого содержит настройки слушателя, а конфигурация слушателя, в которой забыт transport: http, вообще не запускает слушатель, и именно там это становится заметно.

Сервер, к которому обращаются по HTTP, не предлагает инструментов, запускающих команду aggrega в отдельном процессе. Эти инструменты существуют только для клиента, запустившего этот сервер через стандартный ввод и вывод на собственной машине, где указание папки или флага не даёт вызывающей стороне ничего, чего у неё уже не было. Вызывающая сторона, обращающаяся к серверу по HTTP, не владеет хостом, на котором он работает, поэтому команда, которая действовала бы на файловую систему этого хоста с полномочиями самого сервера, вместо этого запускается в терминале на хосте. Эти инструменты отсутствуют в списке и в describe-capabilities, а не предлагаются с последующим отказом, и на вызов, называющий один из них, возвращается ошибка с соответствующим сообщением. Это свойство транспорта, а не настройка: никакая конфигурация не возвращает их.

Прочитайте раздел Без учётных данных ничего не обслуживается, прежде чем развёртывать такой сервер. Каждый запрос к конечной точке содержит учётные данные, и нет настройки, которая обслуживала бы запрос без них: настройка выбирает лишь, проверяет ли этот сервер токен на предъявителя сам или считывает вызывающую сторону, уже проверенную прокси-сервером перед ним.

Два варианта развёртывания

Процесс сам завершает TLS. Задайте в mcp.tls.cert_file цепочку сертификатов PEM, а в mcp.tls.key_file — её закрытый ключ, и слушатель будет обслуживать HTTPS напрямую на указанном вами адресе. Оба файла считываются при запуске процесса, поэтому заменённый сертификат подхватывается перезапуском процесса. Задание одного без другого отклоняется при запуске, а не приводит к откату: сертификат без ключа нельзя предъявить, ключ без сертификата ничего не называет, а опечатка в одном пути — не причина начинать обслуживать незашифрованный трафик.

Прокси-сервер перед процессом завершает TLS и перенаправляет трафик на ограниченный слушатель. Оставьте оба ключа незаданными, и слушатель будет обслуживать открытый текст, что допускается только на loopback-интерфейсе или на сокете Unix, — так до него не сможет добраться ничто, что ещё не находится на этом хосте. Этот вариант используют обратный прокси-сервер, sidecar или сервисная сетка, и в нём сертификат находится перед этим процессом, а не в нём.

Слушатель открытого текста на любом другом адресе отклоняется до какой-либо привязки, и в отказе названы оба ключа TLS. Нет настройки, которая это снимает, и нет адреса-исключения: слушатель, принимающий соединения из сети без собственного сертификата, никогда не безопасен, поэтому процесс отказывается запускаться, а не запускается в таком виде.

Формы адреса

--listen и mcp.listen принимают одну из двух форм:

  • host:port — TCP-адрес, например 127.0.0.1:7777 или 0.0.0.0:8443. Loopback означает 127.0.0.1, ::1 или localhost, если каждый адрес, в который разрешается это имя, является loopback-адресом. Всё остальное — сетевой адрес, которому нужен сертификат: пустой хост, то есть все интерфейсы машины; адрес конкретного интерфейса; и любое другое имя, даже разрешающееся в данный момент в loopback-адрес, потому что место привязки слушателя не должно зависеть от разрешения, которое может измениться.
  • unix:, за которым следует путь в файловой системе, — сокет домена Unix, например unix:/run/aggrega/mcp.sock. Сокет доступен только с хоста, на котором он находится, поэтому сертификат ему не нужен.

Путь к сокету берётся точно в том виде, в каком он записан, включая относительный. Он намеренно не разрешается относительно объявившего его файла конфигурации, потому что тот же адрес приходит и из --listen, у которого нет объявляющего файла, — см. куда указывает относительный путь.

Что принимает слушатель

Одна конечная точка, /mcp, принимающая POST. Каждое сообщение JSON-RPC — отдельный запрос, и никакие сеансы не сохраняются: ничто из того, что клиент отправляет первым, не определяет ответ на последующий запрос, идентификатор сеанса никогда не выдаётся, а заголовок сеанса или возобновления потока, отправленный клиентом, игнорируется. На любой другой метод на этой конечной точке возвращается 405 с Allow: POST, а на любой другой путь — 404; и то и другое решается до проверки учётных данных, поэтому зондирование ничего не узнаёт из запроса аутентификации на пути или методе, которые всё равно ничего бы не обслужили.

На запрос возвращается один объект JSON и код состояния, а если вызов сообщал о ходе выполнения на пути к этому объекту, — поток событий, завершающийся им, как описано в разделе Сведения о ходе долгого вызова. На уведомление — сообщение без id — возвращается 202 с пустым телом. На сообщение, которое не является ни тем ни другим, включая ответ JSON-RPC, возвращается 400, потому что клиент отправляет этому серверу запросы и уведомления и ничего больше.

Обе ревизии протокола обслуживаются здесь точно так же, как через стандартный ввод и вывод. Запрос 2026-07-28 дублирует своё тело в заголовках транспорта, чтобы посредник мог маршрутизировать его, не разбирая тело: MCP-Protocol-Version содержит ревизию, указанную в теле, Mcp-Method — названный в нём метод, а Mcp-Name — цель для методов, обращающихся к ней по имени. На заголовок, расходящийся с телом, возвращается 400. Клиент 2025-06-18 начинает с рукопожатия initialize, на которое отвечают без сохранения состояния; он может передать заголовок версии с этой ревизией или опустить его. На запрос с ревизией, которую сервер не поддерживает, возвращается 400 со списком двух поддерживаемых, а на запрос с методом, который сервер не обслуживает, — 404.

mcp.allowed_origins учитывается, только когда запрос содержит заголовок Origin, что на практике означает, что его отправил браузер: на запрос с источником, которого нет в списке, возвращается 403, а запрос без такого заголовка обслуживается. Клиент, не являющийся браузером, не отправляет такой заголовок, и запись для него не нужна. Клиенту на основе браузера запись нужна всегда: список пуст, пока его не заполнит оператор, поэтому до тех пор ни один источник не допускается и на каждый запрос браузера возвращается 403 — включая запрос со страницы, обслуживаемой по собственному адресу конечной точки. Запись сравнивается с заголовком точно, поэтому её записывают так, как браузер отправляет источник: схема в нижнем регистре, ://, хост в нижнем регистре и, если порт не является портом схемы по умолчанию, : и порт, например https://app.example.com; запись с путём, завершающим /, без схемы или с заглавной буквой отклоняется при загрузке конфигурации с указанием этой записи, потому что она никогда не могла бы совпасть.

mcp.limits ограничивает принимаемый трафик. На тело, превышающее max_body_bytes, возвращается 413, и оно не читается дальше предела. На запрос, поступивший, когда уже выполняется max_concurrent_requests запросов, возвращается 503, а не ставится в очередь за работой, которой он не видит. Вызывающей стороне, отправившей больше requests_per_minute запросов в течение минуты, возвращается 429; учёт ведётся отдельно для каждой вызывающей стороны, поэтому одна интенсивно отправляющая сторона ничего не стоит другой. Значение каждого ограничения по умолчанию указано рядом с его ключом в справочнике по конфигурации, и ни у одного из них нет значения, которое его отключает.

Один процесс — одно рабочее пространство

Рабочее пространство, которое обслуживает процесс, фиксируется при его запуске. Его задаёт --workspace-root; при отсутствии флага его задаёт переменная AGGREGA_WORKSPACE_ROOT. Указанная папка сама является корнем рабочего пространства, и ничего выше неё не просматривается; несуществующая папка отклоняется с указанием того, какой из двух источников её задал, и с цитированием значения в том виде, в каком оно было передано, — слушателем до привязки к адресу, а сервером на стандартном вводе и выводе — в ответе на каждый вызов, действующий в этом рабочем пространстве, как описано в разделе Which workspace a call is answered in, — так что запуск, составленный клиентом, а не набранный вручную, всё равно сообщает, что ему было передано. Если не задано ни то ни другое, сервер на стандартном вводе и выводе определяет рабочее пространство по каталогу, в котором он был запущен, — если там ничто его не закрепляет, каждый ответ, касающийся рабочего пространства, сообщает, какую папку он использовал, а запуск из настольного пакета с пустым параметром Workspace folder вместо этого отклоняет вызов, не называющий собственного рабочего пространства, как описано в разделе Which workspace a call is answered in, — а слушатель отклоняется до привязки, если рабочее пространство там не определяется: процесс, доступный по HTTP, отвечает вызывающим, которые не видят машину, поэтому он обслуживает рабочее пространство, выбранное оператором, а не тот каталог, в котором ему довелось быть запущенным. Чтобы обслуживать несколько проектов, запускайте по одному процессу на корень каждого проекта.

Вызов, пришедший по HTTP, не может назвать собственное рабочее пространство. workspace_root и catalog_dirs отклоняются с указанием переданного аргумента, а не отбрасываются молча: молча проигнорированный аргумент выглядит для отправителя точно так же, как учтённый. Каталоги, просматриваемые рядом с обслуживаемым рабочим пространством, — это собственный параметр workspace.catalog_dirs этого рабочего пространства, а для сущности Release, которой оно задаёт собственные каталоги в workspace.releases, — параметр этой сущности Release; их записывает оператор. На стандартном вводе и выводе оба аргумента учитываются, поскольку клиент, запустивший сервер, работает на собственной машине вызывающего. Там запись catalog_dirs либо абсолютна, либо отсчитывается от корня рабочего пространства, от которого читается относительный release, — корня, который первым определили собственный workspace_root вызова, запуск или каталог, где был запущен сервер, и от которого чтение продолжается, даже когда сущность Release, названная абсолютно, переносит вызов в собственное рабочее пространство этой сущности Release, — а не от каталога, в котором работает сервер, если он находится в другом месте.

Путь, который называет вызов, тоже остаётся внутри этого рабочего пространства. По HTTP аргумент-путь разрешается относительно корня рабочего пространства и отклоняется, если выходит за его пределы: относительный путь, поднимающийся из рабочего пространства, абсолютный путь, указывающий в другое место, и относительный путь, выводящий из рабочего пространства через ссылку на находящийся там файл или каталог, — каждый возвращается как ошибка, называющая аргумент, но не называющая ни корень рабочего пространства, ни место, куда привёл бы путь; относительный путь цитируется так, как вы его отправили. Каждый аргумент-путь оценивается по тому, куда он ведёт, согласно определению понятия «внутри», которое даёт раздел The workspace boundary, независимо от того, читает его инструмент или записывает, — каталог, в который gen-catalog записывает свой вывод, документ, который записывает обратно edit-document, и сущность, рядом с которой pin записывает свою блокировку, — так же, как документ, который инструмент читает; поэтому ещё не созданный путь под ссылкой, ведущей из рабочего пространства, отклоняется так же, как эта ссылка, и ничего не читается и не записывается. release, называющий сущность Release, которую называет конфигурация обслуживаемого рабочего пространства — как build.authoring_release или как ключ workspace.releases, — достигается через эту конфигурацию и принимается через ссылку, где бы ни находился его файл; ни у одного другого аргумента такого исключения нет. Если нужный вам путь находится внутри этого рабочего пространства, но записан абсолютно, отказ сообщает вам запись относительно корня, которую следует отправить вместо него, так что вызывающий, угадавший неверную форму, узнаёт правильную, а не только то, что его форма неверна. Это касается путей, которые вызов называет своим предметом, — документа для проверки, сущности Release для сборки, каталога, в который генерация записывает вывод, — и путей, в которые инструмент пишет, не меньше, чем тех, которые он читает: вызывающий, обращающийся к серверу по сети, просит невидимую ему машину читать и записывать файлы, и выбранное оператором рабочее пространство — это место, в котором такое чтение и запись удерживаются. На стандартном вводе и выводе аргументы-пути каждого инструмента сохраняют контракт, описанный для этого инструмента ниже, где путь может быть абсолютным и указывать за пределы рабочего пространства: вызывающий владеет машиной, на которой работает сервер, поэтому ограничивать его каталогом, который он сам выбрал, ничего бы не дало. Два инструмента, сама операция которых отвечает только о документе, содержащемся в рабочем пространстве, — insertion-point и edit-document, — сохраняют это на обоих транспортах и отклоняют документ вне рабочего пространства, записан ли он так или достигнут через ссылку, ведущую из него. На стандартном вводе и выводе учитывается путь, который называет вызов, и ничего сверх него. То, что операция затем читает и записывает по собственной инициативе, на обоих транспортах ограничено точно так же, как при вводе той же команды в терминале: обход или поиск не читает через ссылку, ведущую из рабочего пространства; файл, который сущность Release в рабочем пространстве или её сущность Manifest называет по пути, не читается извне рабочего пространства, а файл, который называет сущность Release, указанная вызовом вне рабочего пространства, не читается извне каталога, содержащего эту сущность Release; а файл, записанный внутри каталога — рабочего пространства или названного вызовом, — остаётся внутри этого каталога. Раздел The workspace boundary сопоставляет два транспорта с командной строкой и редактором и указывает, что остаётся открытым на стандартном вводе и выводе: документ в клонированном вами рабочем пространстве может подтолкнуть ассистента к тому, чтобы назвать путь вне рабочего пространства, и этот путь учитывается так, как назван.

Что ответ сообщает о файловой системе сервера

По HTTP ответ называет место в файловой системе сервера относительно корня рабочей области или скрывает его. Клиент, запустивший сервер, работает там же, где и сервер, поэтому по стандартному вводу и выводу каждый ответ называет каждое место так, как его хранит операция, — абсолютным, если оно хранится именно так, — и каждое из этих мест уже принадлежит вызывающей стороне. Вызывающая сторона, обращающаяся к слушателю, не выбирала ни одного из этих мест и не может их открыть, а сервер, опубликовавший их ей, не может отозвать эту публикацию. Поэтому по HTTP ответ сообщает такой вызывающей стороне о месте одно из двух:

  • Место внутри рабочей области называется относительно корня рабочей области — в той же форме, что и путь, который отправляете вы, поэтому имя, прочитанное из одного ответа, можно без изменений отправить в следующем вызове. Сущность Release в корне — это release.yaml, а её файл блокировки — release.lock.
  • Место вне рабочей области скрывается, как и сам корень рабочей области. Поле не несёт значения — оно равно null или опущено, а в attachment-container, ответ которого сохраняет форму, в которой его сообщает каждая поверхность, поле file остаётся пустым, — а отметка рядом с ним, названная по имени поля с добавлением _withheld, говорит, что значение скрыто, а не не задано: workspace_root_withheld рядом с workspace_root, file_withheld рядом с file. Отметка присутствует только там, где что-то было скрыто. Корень скрывается потому, что слушатель обслуживает ровно одну рабочую область, так что её расположение не нужно вам, чтобы назвать то, что находится внутри неё.

Находится ли место внутри, определяется по его написанию, а не по файлу, к которому оно ведёт. Путь, записанный через цель символической ссылки, а не через корень, над которым был запущен сервер, и путь, который выходит из корня и возвращается обратно, считаются находящимися вне рабочей области и скрываются. Это решение склоняется к тому, чтобы сообщить вам меньше, и никогда — к тому, чтобы назвать место вне рабочей области.

По HTTP читаемый текст ответа следует тому же правилу. Там, где текст, строка диагностики или сообщение о сбое называет место, которое содержит рабочая область, — её корень или что-либо под ним, файл конфигурации, из которого была прочитана её конфигурация, каталог, из которого читается её каталог сущностей, — это место записывается относительно корня или читается как (location withheld), если оно лежит вне рабочей области или является корнем. Текст, который ответ составляет о собственной рабочей области, называет её рабочей областью, которую обслуживает этот сервер. Место вне всего перечисленного, которое операция записывает в сообщение, не распознаётся как место и доходит до вас в том виде, в каком было записано.

Ответы, которых это касается, по HTTP:

  • list-entities, list-releases, cache-status, registry-list, search, attach-candidates, connection-candidates, insertion-point, attachment-container, connection-at-position и edit-document скрывают workspace_root. Пути, которые они уже дают относительно корня, — исходный файл сущности, путь сущности Release и её файл блокировки в lockfiles, документ, к которому относится точка вставки или правка, файлы, записанные правкой, — выглядят одинаково на обоих транспортах.
  • cache-status также скрывает то, что называет плагин, загруженный сервером из файла на его хосте. Такой идентификатор равен null на своём месте в provenance[].identities, все остальные идентификаторы сохраняют свои позиции, а запись помечается identities_withheld. note скомпилированного модуля — это одно предложение, называющее идентификаторы, для которых был собран модуль, поэтому если любой из них называет такой файл, note опускается целиком и помечается note_withheld; digest модуля при этом остаётся. Идентификатор, называющий ссылку на реестр или сущность Plugin, возвращается целиком, как и note, называющий только такие идентификаторы. label исходного артефакта — это его место в кеше, записанное по хосту и пути URL, из которого он был разрешён, поэтому для репозитория, прочитанного из собственной файловой системы сервера — через URL file:// или путь, — label опускается и помечается label_withheld, его size и digest остаются, а label, называющий сетевой хост, возвращается целиком. Текст списка содержит (location withheld) там, где назвал бы такое место.
  • validate называет target, а для сущности Release и release, относительно корня; для всего каталога target — это корень, и он скрывается. Место в diagnostics или notices следует правилу для текста.
  • build называет release относительно корня, а сборка, которая сначала разрешила свои зависимости, содержит dependency_resolution в том виде, в каком отвечает pull. Сборка, которой передан write, называет записанный каталог как output_dir, который читается как dist — относительно корня, — а каждый путь в files указан относительно этого каталога. refusal и каждая запись его findings называют свой file относительно корня или скрывают его, если документ лежит вне рабочей области. advisories, deprecations, declined_external_inputs и каждое message в refusal следуют правилу для текста.
  • pull называет release и lockfile относительно корня. diagnostics и incomplete_external_inputs следуют правилу для текста. source каждой записи resolved возвращается целиком на обоих транспортах: он называет то, что сделал запуск, и никогда — место на хосте.
  • describe называет release сущности Release относительно корня, а file сущности — относительно корня, если её документ лежит внутри рабочей области; у сущности, прочитанной из каталога вне рабочей области, file скрывается. mapping_diagnostics и deprecations следуют правилу для текста.
  • lint называет location.file каждой находки относительно корня или скрывает его, если сущность лежит вне рабочей области. message и suggest находки следуют правилу для текста.
  • pin называет entity и lock относительно корня, как и pin, который содержит публикация.
  • gen-catalog называет каждый файл, перечисленный в output, относительно корня.
  • import скрывает workspace_root, а также output_dir, если черновики были записаны в этот корень; каталог, который вы указали в output_dir, сообщается по его имени относительно корня. Каждый путь черновика в written и drafts указан относительно output_dir, так что место, куда попали черновики, есть в ответе в любом случае. message диагностики, а также params_summary, rationale и swap_hint решения — это текст, составленный импортёром, и они следуют правилу для текста.
  • config-show и plugin-list скрывают больше, чем корень, потому что бо́льшая часть того, что они сообщают, — это конфигурация, называющая места, как описано в разделе Что слушатель не сообщает о своём хосте.
  • scaffold, записывая пример, называет dir так, как вы его отправили, относительно корня, а каждый путь в files — относительно этого каталога; создание черновика и вывод списка не называют никаких мест.
  • Инструменты публикации, sign-artifacts, deprecate-artifact, get-schema, explain-error и describe-capabilities сами не называют никаких мест на хосте. Сообщение о сбое любого из них следует правилу для текста: отказ, который выдаёт автономная рабочая область, называет её .aggrega-config.yaml относительно корня.
  • Аргумент-путь, отклонённый за выход за пределы рабочей области, отклоняется без указания корня или места, к которому он привёл бы, как описано выше.

Как завершается вызов

Закрытие соединения отменяет вызов, который оно несло. Это сигнал отмены данного транспорта: сервер воспринимает отключение вызывающей стороны как отмену этого запроса, завершает выполнявшуюся работу и больше ничего для него не записывает. Сообщение об отмене здесь не нужно и не ожидается — в противоположность стандартному вводу и выводу, где нет отдельного потока на запрос, который можно закрыть, и клиент завершает вызов, указывая его id. Сообщение об отмене, всё же пришедшее по HTTP, принимается и ничего не завершает.

Остановка процесса опустошает слушатель. Прерывание или запрос на завершение от супервизора или среды выполнения контейнеров прекращает приём новых соединений слушателем и позволяет вызову, на который уже идёт ответ, завершиться в пределах ограниченного времени, так что вызывающая сторона, запросившая что-то до остановки, всё равно получит свой ответ. Вызов, не завершившийся за это время, теряет соединение. Второй запрос на остановку немедленно завершает процесс.

Проверки работоспособности и готовности на отдельном адресе

mcp.health.listen — адрес, по которому супервизор спрашивает, запущен ли процесс и может ли он ответить на вызов. Укажите в нём адрес в любой из описанных выше форм, и второй слушатель будет отвечать там на GET /healthz и GET /readyz. Если его не указать (это значение по умолчанию), второй слушатель не запускается и ни на одну из проверок нигде не отвечают.

Два ответа сообщают разное, и именно поэтому их два. На /healthz отвечают 200 с момента запуска процесса — и это всё, что утверждает проверка работоспособности: процесс запущен, а супервизор, не получивший никакого ответа, должен его перезапустить. На /readyz отвечают 503, пока рабочее пространство, которое обслуживает процесс, не разрешено и конечная точка не привязана, и 200 после этого — так балансировщик придерживает трафик, пока процесс действительно не сможет ответить на вызов, а не отправляет первый запрос в процесс, который ещё запускается. Каждый ответ — это код состояния с пустым телом; учётные данные не запрашиваются, и ничего из отправленного вызывающей стороной не читается.

Конечная точка никогда не отвечает на эти два пути. На GET /healthz и GET /readyz по адресу, который задаёт mcp.listen, отвечают 404 — точно так же, как на любой другой путь, который эта конечная точка не обслуживает, с токеном и без него. Ответ на проверку там дал бы всякому, кто достигает конечной точки, бесплатный способ узнать, запущен ли процесс, и вместе с тем бесплатный способ заставить его выполнять работу — на слушателе, который в остальном отклоняет каждый запрос без учётных данных.

Где находится адрес проверок, выбираете вы, и он не ограничен так, как mcp.listen. Ни один адрес для него не отклоняется. Направьте его на loopback или на Unix-сокет — для этого он и предназначен: для супервизора, балансировщика или среды выполнения контейнеров, работающих рядом с этим процессом на том же хосте. Всё, что может достичь выбранного адреса, может прочитать эти два ответа, поэтому адрес, доступный из открытой сети, публикует их в открытую сеть.

Без учётных данных ничего не обслуживается

Каждый запрос к конечной точке несёт учётные данные, и какие именно — зависит от того, проверил ли их уже прокси перед сервером. По умолчанию это bearer-токен, который сервер проверяет сам; он описан в остальной части этого раздела. Если задать mcp.authorization.trusted_proxy, вместо него используется заголовок, который устанавливает этот прокси, — см. Чтение вызывающей стороны из прокси перед сервером; в этом случае токен не читается вовсе. Ни один из вариантов не обслуживает запрос, который ничего не предъявляет.

По умолчанию сервер проверяет bearer-токен сам. Он читает токен из заголовка Authorization и принимает его, только если подпись проверяется ключом, который публикует сервер авторизации, токен называет mcp.authorization.issuer своим издателем, называет собственный mcp.authorization.resource этого развёртывания среди своих аудиторий, находится в пределах срока действия и указывает, кто его предъявил. На токен, не прошедший любую из этих проверок, отвечают 401, добавляя error="invalid_token" к тому же запросу аутентификации, который получает вызывающая сторона без учётных данных, — и ответ одинаков, какая бы проверка ни отклонила токен, поэтому вызывающая сторона узнаёт, что ей нужен другой токен, а не какая часть отправленного оказалась неверной. Принимаются только асимметричные алгоритмы подписи: неподписанный токен и токен с симметричным алгоритмом отклоняются до того, как из них что-либо будет прочитано.

Токен может указывать, какого он вида, и принимаются четыре формы. JWT может нести заголовок typ с собственным типом. Этот сервер принимает at+jwt и application/at+jwt — два зарегистрированных написания для токена доступа; JWT, который говорит лишь о том, что токен является JWT; и токен, не объявляющий тип вовсе. На всё остальное отвечают 401, точно так же, как на любой другой отклонённый токен. Набор фиксирован, и никакая настройка не расширяет и не сужает его, потому что форму, которая там появляется, определяет сервер авторизации, выпустивший токен, а не принимающее его развёртывание. Принятие JWT действительно означает, что один лишь объявленный тип больше не отличает токен доступа от токена идентификации, — их различает проверка аудитории, и поэтому именно она несущая: аудитория токена идентификации — это клиент, которому он выдан, и никогда не собственный mcp.authorization.resource этого развёртывания, поэтому токен, выданный для чего-либо, кроме этого развёртывания, отклоняется, как бы он себя ни называл.

Какие серверы авторизации это допускает. Microsoft Entra ID выпускает токены доступа с типом JWT. Keycloak выпускает at+jwt, а JWT — при включённом режиме совместимости с OpenID Connect. Auth0 выпускает JWT в своём собственном профиле токенов и at+jwt в профиле RFC 9068. Токен от любого из них проходит эту проверку, какую бы из двух форм он ни нёс. Okta не поддерживается: её токены доступа объявляют собственный тип, не входящий в четыре перечисленных выше, поэтому этот сервер их отклоняет.

Отклонённый токен оставляет причину в собственном потоке ошибок сервера. Вызывающей стороне сообщается лишь, что предъявленное не принято; обслуживающий процесс записывает одну строку с названием проверки, отклонившей токен, — аудитория, издатель, срок действия, подпись, идентификатор ключа, объявленный тип и каждая из остальных. Благодаря этой строке развёртывание, отклоняющее все запросы, может диагностировать тот, кто его эксплуатирует, а не только тот, кто к нему обращается. Она не содержит никакой части токена. Запрос вообще без учётных данных строки не записывает, потому что получение запроса аутентификации — это то, как клиент вообще узнаёт, где получить токен, и это первое, что делает каждый корректно работающий клиент.

Токену место в заголовке и больше нигде. На токен, отправленный как параметр запроса access_token, отвечают 400, и он никогда не читается, потому что адрес записывается в каждом журнале прокси, истории браузера и заголовке referrer, через которые проходит запрос, так что токен, пришедший таким путём, уже раскрыт. Сервер никогда не записывает токен в журнал, никуда его не отправляет и никогда не получает и не обменивает токен от имени вызывающей стороны: он читает предъявленное, принимает решение и ничего из этого не хранит. Субъект, названный в токене, записывается и ни с чем не сравнивается.

Ключи проверки берутся с сервера авторизации или из указанного вами файла. Если mcp.authorization.jwks_file не задан, сервер читает метаданные сервера авторизации по его well-known адресу, переходит по опубликованному там jwks_uri и хранит найденные ключи; токен, подписанный ключом с идентификатором, которого нет среди этих ключей, вызывает одно повторное чтение, и не более одного за короткий интервал, поэтому вызывающая сторона, отправляющая выдуманные идентификаторы ключей, не может вызывать исходящий запрос на каждый запрос. Для чтения ключей с сервера авторизации нужен адрес ключей https, либо простой http на этой машине: к jwks_uri с простым http на другом хосте сервер никогда не обращается, а перенаправлению, которое отправило бы любое из чтений на простой http на другом хосте, не следует, потому что тот, кто находится на незащищённом пути к ключам, мог бы ответить собственными ключами. На токен, которому нужны эти ключи, тогда отвечают 503 — точно так же, как при ключах, которые невозможно прочитать, — а строка, которую сервер записывает для этого запроса, сообщает, что чтение отклонено из-за простого http, а не что сервер авторизации недоступен: исправление на стороне сервера авторизации, который должен публиковать свои метаданные и ключи по https. Если задан jwks_file, ключи читаются из этого файла и к серверу авторизации никогда не обращаются — это то, что нужно рабочему пространству, объявляющему offline: true, и такое рабочее пространство отклоняется до привязки слушателя, если файл не указан. Если ключи вообще невозможно прочитать, на запросы отвечают 503 без запроса аутентификации: ничего из предъявленного вызывающей стороной не было признано недостаточным, поэтому отправка запроса с другим токеном не поможет.

Единственный ответ, для которого учётные данные не запрашиваются, — документ метаданных защищённого ресурса. Клиент должен прочитать его прежде, чем сможет получить токен, поэтому требование токена здесь закрыло бы единственный вход. Он отдаётся по адресу /.well-known/oauth-protected-resource, а также — если адрес, который называет mcp.authorization.resource, имеет собственный путь, — по этому well-known пути с добавленным к нему этим путём. Это два места, где ищет клиент, и форма с добавленным путём — это адрес, который называет вызов аутентификации. Документ содержит этот адрес как ресурс, которым называется это развёртывание, mcp.authorization.issuer как сервер авторизации, у которого следует получить токен, header как единственный способ предъявить токен, а также три имени областей, приведённые ниже.

Издатель — это адрес https, если только сервер авторизации не работает на этой машине. Обычный http принимается для издателя на localhost, 127.0.0.1 или ::1 — так выглядит локальный тест с локальным сервером авторизации; издатель с обычным http на любом другом хосте отклоняется до привязки слушателя, и в отказе называется mcp.authorization.issuer и запрашивается адрес https. Это действует в любом режиме — когда ключи читаются у издателя, с mcp.authorization.jwks_file и с прокси перед сервером, — потому что в каждом режиме издатель публикуется в этом документе: клиент, следующий ему, выполняет свой поток авторизации с этим адресом, поэтому по обычному http код авторизации и полученный токен передавались бы по сети без защиты, независимо от того, читает ли этот сервер оттуда ключ. Если же он читает оттуда свои ключи, то тот, кто находится на этом пути, мог бы также ответить собственными ключами, и любой подписанный ими токен был бы принят.

Это развёртывание публикует имена областей aggrega:read, aggrega:workspace-write и aggrega:registry-write. Именно эти имена следует зарегистрировать на сервере авторизации и именно их клиент у него запрашивает, а вызов аутентификации, который получает отклонённый вызывающий, называет aggrega:read как область, которую нужно получить первой. Что допускает каждая из них — и вторая граница, которую это развёртывание устанавливает само себе, — описано ниже в разделе Что доступно вызывающему.

Чтение вызывающего из прокси перед сервером

Если прокси перед сервером уже проверяет токены, mcp.authorization.trusted_proxy указывает этому серверу брать вызывающего у прокси, а не проверять токен повторно. Укажите principal_header — заголовок, который прокси устанавливает, чтобы сообщить, кто вызывающий, — и при необходимости scopes_header — второй заголовок с областями этого вызывающего, разделёнными пробелами. Каждый из них — имя HTTP-заголовка, например X-Forwarded-User, без пробелов и двоеточий; имя любой другой формы отклоняется при загрузке конфигурации с указанием ключа, как и пустой principal_header — чтобы этот режим был выключен, не указывайте блок. Читаются только эти два заголовка: ни заголовок с пересланным адресом, ни какой-либо другой не участвуют. На запрос без заголовка с принципалом отвечается 401, и в этом режиме токен не читается вообще — запрос с токеном, который этот сервер иначе отклонил бы, обслуживается при наличии заголовка с принципалом, а запрос с токеном, который сервер принял бы, всё равно отклоняется при отсутствии этого заголовка.

Этот режим принимается только на loopback или Unix-сокете, а на любом другом адресе процесс отклоняется до привязки. Заголовку можно доверять ровно тогда, когда установить его не может никто, кроме прокси. На адресе, доступном из сети, его может установить кто угодно — поэтому слушатель в этом режиме на таком адресе позволил бы каждому вызывающему назваться кем угодно. В отказе называются обе конфликтующие настройки, так что снять его можно, перенеся адрес или удалив блок.

Что утверждает прокси, тому этот сервер и верит, — таково условие сделки. В этом режиме сервер не проверяет подписи и ни с чем не сравнивает заявленного вызывающего — точно так же, как ни с чем не сравнивает субъект токена. Проверил ли прокси то, что переслал, и может ли что-либо достичь этого слушателя в обход прокси — это забота развёртывания; описанное выше ограничение делает возможным сделать это правильно, но не гарантирует, что так и сделано.

Установка mcp.authorization.trusted_proxy не отменяет остальных требований. issuer и resource по-прежнему нужны, потому что документ метаданных по-прежнему публикуется и вызов аутентификации по-прежнему на него ссылается — клиенту за прокси всё равно нужно узнать, где получить токен, который проверит прокси. По той же причине издатель по-прежнему должен быть адресом https, если он не работает на этой машине: клиент получает свой токен у издателя, поэтому издатель с обычным http на другом хосте отклоняется до привязки слушателя в этом режиме точно так же, как в любом другом, хотя этот сервер ничего у него не читает.

Что доступно вызывающему

То, что доступно вызывающему по HTTP, определяют две границы, и устанавливают их разные люди. Первая — собственные учётные данные вызывающего; вторая — то, что этот сервер вообще поддерживает. Обе считываются до любого выполнения из объявления, которое каждая операция делает о себе, и доходят до клиента в разных местах: список инструментов показывает, что этот сервер поддерживает и объявляет, а ответ на каждый вызов показывает, что допускают учётные данные.

Каждая операция объявляет, как далеко распространяются её собственные эффекты, и видов таких четыре, от самого узкого к самому широкому:

  • Ничего не затрагивает — читает определение, проверяет, что закрепляет Release, отрисовывает артефакты в памяти и возвращает их. После неё ничего не остаётся: ничего не записывается, и ответ — это всё, что она производит.
  • Затрагивает рабочую область — пишет внутри рабочей области, которую обслуживает этот процесс: lockfile сущности Release, кэш артефактов, сгенерированные сущности, отредактированный документ.
  • Затрагивает реестр — публикует, подписывает или прикрепляет маркер отзыва к уже опубликованному. Она меняет то, что разрешает каждый потребитель этого реестра, и ничего из этого нельзя отозвать у тех, кто уже это получил.
  • Затрагивает машину — меняет то, что общее для всех рабочих областей на хосте, в том числе хранилище скомпилированных модулей, общий для всех них файл конфигурации и хранилище учётных данных. Кэш, который отдельный проект держит в собственном каталоге кэша, к этому виду не относится, а cache-status сообщает, к какому из этих видов относится каждый перечисленный им кэш.

Вид — это свойство операции, а не инструмента, который её предоставляет, и он описывает то, что операция оставляет после себя, — а не то, куда интерфейс помещает возвращаемый ответ. Отрисовка сущности Release производит артефакты в качестве ответа, поэтому ничего не затрагивает; командная строка, которая затем сохраняет эти артефакты в указанный вами каталог, доставляет этот ответ, а не затрагивает что-то дальше. Если понимать иначе, каждая операция, отвечающая содержимым, получала бы вид того интерфейса, который его сохранил, и вид перестал бы быть свойством операции. По той же причине describe, читающий сущность по ссылке на реестр, ничего не затрагивает: он обращается к реестру за ответом и ничего не оставляет ни в реестре, ни на этой машине, а то, к каким реестрам он может обращаться, описано в разделе Какие учётные данные расходует вызов. Отдельный вызов всё же может затронуть больше, чем вид его операции, если сам вызов запрашивает запись: сборка с write сохраняет свои артефакты в рабочей области, которую обслуживает этот сервер, поэтому такой вызов затрагивает рабочую область — как и сборка, которая сначала разрешает свои зависимости.

Область допускает вид, и каждая область записи подразумевает область чтения. aggrega:read допускает операцию, которая ничего не затрагивает. aggrega:workspace-write допускает операцию, затрагивающую рабочую область, и подразумевает область чтения. aggrega:registry-write допускает операцию, затрагивающую реестр, и также подразумевает область чтения. Поэтому клиент запрашивает у сервера авторизации нужную ему область записи и не обязан дополнительно запрашивать область чтения.

Ни одна область действия не допускает вид «машина», и никакая настройка не добавляет такую область. Операции этого вида выполняются только инструментами, которые запускают команду aggrega в отдельном процессе, а сервер, доступный по HTTP, вообще не предлагает ни одного из них — по причине, изложенной выше в разделе Доступ к серверу по HTTPS. Выполняйте их в терминале на хосте.

Список инструментов показывает все инструменты, которые этот сервер содержит и объявляет, независимо от областей действия вызывающих учётных данных, а учётные данные определяют, какие из них может выполнить вызов. describe-capabilities индексирует и описывает тот же набор. На вызов, который учётные данные не допускают, приходит ответ 403 с error="insufficient_scope" в запросе аутентификации, где названа единственная область действия, которая допустила бы его, и ничего из запрошенного вызовом не выполняется. Именно на этот отказ отвечает повышение привилегий (step-up) в протоколе: клиент, реализующий step-up, просит вас снова войти для области действия, названной в запросе аутентификации. Список не меняется вместе с учётными данными, поэтому клиент, выполнивший повторный вход, уже имеет нужную область. Учётные данные без какой-либо из трёх областей действия получают тот же список инструментов и не могут вызвать ни один из них, включая describe-capabilities.

Сборка — случай, который стоит знать. Сама по себе она ничего не меняет и поэтому требует только aggrega:read, но сборка, которая записывает, требует aggrega:workspace-write: сборка с параметром write сохраняет свои артефакты в dist/ в корне рабочего пространства, а сборка, которая сначала разрешает свои зависимости, записывает lock-файл — независимо от того, запросил ли это вызов через auto_pull или это сделала собственная настройка auto_pull рабочего пространства. Инструмент показывается вызывающей стороне с областью чтения, как и любой инструмент, и сборки, остающиеся в памяти, действительно ей доступны; отклоняется — с указанием aggrega:workspace-write — именно вызов, который записывает.

Клиенту, который не поддерживает повышение привилегий, всё равно можно выдать области записи, и это решается на сервере авторизации. Тот, кто управляет сервером авторизации, делает области записи областями по умолчанию для этого клиента — областями, которые он включает в каждый токен, выдаваемый этому клиенту, независимо от того, запрашивал ли их клиент, — поэтому токен, полученный при первом входе, уже содержит их. Клиент, который заново регистрируется на сервере авторизации при каждом подключении, каждый раз является там новым клиентом, и настройка, сделанная при предыдущей регистрации, не переносится; для такого клиента действуют области по умолчанию, которые сервер авторизации выдаёт каждому регистрируемому клиенту. Цена в том, что каждый вход через этого клиента затем несёт право записи, нужно оно текущей работе или нет, — а там, где используются области по умолчанию, выдаваемые при регистрации, это право несёт и каждый клиент, зарегистрированный таким образом. Делайте областью по умолчанию только ту область записи, которая нужна работе: aggrega:workspace-write и aggrega:registry-write допускают разные виды, и ни одна не подразумевает другую.

mcp.deny_reach — это место, где тот, кто запускает этот сервер, отзывает у него вид, и это одна из двух настроек, сокращающих список инструментов. Перечислите виды — none, workspace, registry, machine, — которые этот сервер не содержит, и каждый инструмент, затрагивающий один из них, исчезает из списка инструментов любой вызывающей стороны и из describe-capabilities, что бы ни говорил её токен, а при попытке вызова отклоняется с ошибкой, называющей эту настройку. Это собственное ограничение сервера, а не вызывающей стороны, поэтому никакие учётные данные его не снимают и отказ не содержит запроса аутентификации: сервер, предназначенный только для чтения, перечисляет здесь workspace, registry и machine и тогда не может публиковать даже для вызывающей стороны, чей токен содержит все три области действия. Если не указывать настройку (это значение по умолчанию), сервер не отзывает ни одного вида, и то, какие виды затрагивает вызов, определяется собственными областями действия вызывающей стороны. Указание machine допускается и ничего не меняет, поскольку ничего этого вида здесь и так не предлагается. Значение, не входящее в эти четыре, отклоняется при загрузке конфигурации, а не пропускается: оператор, опечатавшийся в названии вида, запросил ограничение, и молча обслуживать его без ограничения — неправильный ответ на это.

mcp.announce_tools — вторая настройка, сокращающая список инструментов, и это не одно и то же ограничение. deny_reach отзывает возможность: операция вида, названного там, здесь вообще не выполняется — ни для кого. announce_tools отзывает только объявление: инструменты, которые она опускает, остаются возможностями этого сервера, а отвечает она на собственное ограничение клиента на количество регистрируемых им инструментов. Если заданы обе настройки, побеждает отзыв, поэтому инструмент отозванного вида остаётся отсутствующим, как бы его ни называла announce_tools, а отказ, который получает вызывающая сторона, называет отзыв. Ничто из сокращающего список не читает области действия вызывающей стороны: отсутствующая у неё область отклоняет вызов, но никогда не удаляет инструмент из списка. Остальное изложено в разделе Сужение того, что объявляет сервер.

Какие учётные данные расходует вызов

Бесключевая подпись через слушатель берёт удостоверение из identity_token, переданного в вызове, и ни из чего другого. Токен, отправленный в вызове, — это учётные данные, которыми владеет вызывающая сторона: ей пришлось его получить, он привязан к ней, и созданная им подпись приписывается ей. Любой другой источник, из которого могло бы взяться удостоверение, принадлежит тому, кто запустил этот процесс, поэтому на этом транспорте разрешению передаётся окружение, которое ничего не возвращает. AGGREGA_IDENTITY_TOKEN и SIGSTORE_ID_TOKEN в окружении сервера не читаются, а к окружающей конечной точке OIDC GitHub Actions обращения нет. Они недоступны, а не просто нежелательны: разрешению нечего найти. Вызов без identity_token отклоняется, и в отказе в качестве того, что нужно отправить, названо identity_token, а не какая-либо переменная или конечная точка: вызывающая сторона, которая не сидит за клавиатурой этой машины, ничего здесь экспортировать не может, так что назвать переменную означало бы предложить ей устроить то, что не может изменить ответ.

Ключ подписи, хранящийся на этой машине, выбрать нельзя ни одним из путей. key_path отклоняется до какого-либо разрешения и отсутствует в схемах аргументов, которые здесь объявляют publish-entity, sign-artifacts и deprecate-artifact, поэтому вызывающей стороне никогда не предлагается аргумент, который не может сработать. Ключ подписи, указанный в собственной конфигурации обслуживаемого рабочего пространства, тоже недоступен — signing.key_path, задан ли он для рабочего пространства в целом, для одного реестра или передан через окружение. Обе меры объясняются одной причиной: путь к ключу — не учётные данные, а имя секрета, который хранит этот сервер. Вызывающая сторона, указавшая его, ничего не доказывает: любой, кто достучался до этого адреса, мог бы указать то же имя, и полученная подпись говорила бы, что за артефакт ручается оператор, а не вызывающая сторона. Закрыть аргумент, оставив открытой конфигурацию, значило бы запереть одну дверь в комнату, которую открывает другая. Поэтому подпись ключом через слушатель недоступна: подписывает только токен, отправленный в вызове.

fulcio_url, rekor_url и timestamp_url не затрагиваются и сохраняются на обоих транспортах. Они называют сервисы, к которым нужно обращаться, а не что-либо, хранящееся на этой машине, поэтому вызывающая сторона, которая не может выбрать ключ, всё равно подписывает с использованием конечных точек, настроенных в этом развёртывании.

Слушатель, запущенный над рабочим пространством, в котором указан ключ подписи, сообщает об этом один раз при запуске. Процесс пишет в свой поток ошибок одну строку, где названа эта настройка и сказано, что вызывающая сторона, обращающаяся к этому слушателю, не может воспользоваться этим ключом, — так оператор узнаёт об этом из запущенного им процесса, а не из неожиданной подписи. Рабочее пространство без ключа такой строки не порождает, потому что сообщать не о чем. Строка содержит имя настройки и не содержит ни ключа, ни чего-либо о файле, на который она указывает.

При работе через стандартные ввод и вывод ничего из сказанного выше не применяется. Там окружение читается, а key_path выбирает ключ, хранящийся на этой машине, потому что клиент, запустивший этот сервер, работает на собственной машине вызывающей стороны, и всё, до чего может дотянуться этот процесс, принадлежит самой вызывающей стороне.

Чтение сущности по ссылке на реестр обращается к одному реестру с собственным входом этого хоста, а через слушатель — только к реестру, настроенному в обслуживаемом рабочем пространстве. describe, которому в качестве name передана ссылка oci://, читает сущность, опубликованную по этой координате, — то же чтение, что выполняет aggrega inspect, — из единственного реестра, названного в ссылке, используя вход, который у этого хоста уже есть для этого реестра. Вызов не несёт учётных данных, и describe их не принимает. Через HTTP реестр должен быть настроен в обслуживаемом рабочем пространстве: это хост, указанный в его default_registry, или хост из списка registries; сравнение точное и с учётом порта. Ссылка на любой другой хост, включая адрес на этой машине, отклоняется до обращения к этому хосту, и в отказе назван хост, поэтому вызывающая сторона не может направить этот сервер по адресу на свой выбор. То, что остаётся доступным, оставлено намеренно: вызывающая сторона с aggrega:read может прочитать всё, что может прочитать вход этого хоста в реестре, настроенном в рабочем пространстве, — то же, что может прочитать человек за терминалом этого хоста. Через стандартные ввод и вывод читается ссылка на любой реестр, как и в командной строке. Описание сущности по её имени в каталоге не затрагивается.

Обращение к реестру использует хранилище учётных данных того пользователя операционной системы, от имени которого работает этот процесс, точно так же, как тот же вызов в терминале на этом хосте. Нет ни источника учётных данных для отдельного рабочего пространства, ни настройки, которая бы его добавила, поэтому registry-list сообщает состояние учётных данных хоста одинаково во всех рабочих пространствах на этой машине. Развёртывание, в котором разные рабочие пространства должны иметь разные учётные данные реестров, запускает их от имени разных пользователей операционной системы — по одному процессу на рабочее пространство, каждый под своим пользователем. Именно отсюда берётся разделение, и обеспечивает его оператор.

Что записывает сервер

Каждый запрос, на который отвечает эта конечная точка, оставляет одну строку в потоке ошибок процесса, и эта строка — один объект JSON. Она содержит time, когда она записана, и request_id, который этот процесс выпустил для вызова и не отправляет обратно вызывающей стороне; subject и issuer в том виде, в каком их заявили предъявленные учётные данные, и client_id, если они назвали клиента; workspace_root — рабочее пространство, которое обслуживает этот процесс; method и target, если метод обращается к чему-либо по имени; reach — вид, который объявляет операция, и reach_escalated_to, если вызов дотянулся дальше этого; outcome; duration_ms; и transport. Поле, которому нечего сообщить, опускается, а не записывается пустым, поэтому отсутствие client_id означает учётные данные, не назвавшие клиента, а отсутствие reach_escalated_to — вызов, дотянувшийся ровно до того, что объявляет его операция.

outcome сообщает, чем закончился вызов, и значения различны, чтобы их можно было подсчитывать по отдельности. ok — вызов выполнен и успешен. tool-failure — вызов выполнен и вернулся с пометкой о сбое, который вызывающая сторона может исправить: это вызов, который сервер обслужил, а не отклонил, поэтому ему не место среди ваших отказов. error — отказ, возвращённый как конверт ошибки протокола. unauthenticated, forbidden и rate-capped — запрос отклонили соответственно учётные данные, ограничение по источнику или области и ограничение частоты для вызывающей стороны. cancelled — вызывающая сторона закрыла соединение до получения ответа.

Причина, по которой отклонены учётные данные, — это поле той же строки, а не отдельная строка. Отклонённый запрос оставляет одну запись, как и любой другой, где refusal называет проверку, которая его отклонила. Ни учётные данные, ни какая-либо их часть не попадают ни в одну строку — ни при отказе, ни при обслуженном вызове.

Вызывающая сторона, не предъявившая вообще ничего, строки не оставляет. Получив запрос на аутентификацию, клиент узнаёт, где получить токен, поэтому это первое, что делает каждый корректный клиент, и строка для каждого такого случая похоронила бы отказы, которые что-то значат. Запрос к пути или методу, которые эта конечная точка не обслуживает, тоже строки не оставляет: оба случая решаются до того, как что-либо о вызывающей стороне прочитано, поэтому сканирование адреса ничего не записывает в то, что собирает поток.

Контекст трассировки, отправленный клиентом, копируется в строку дословно. traceparent, а также tracestate и baggage, если они тоже отправлены, передаются ровно в том виде, в каком получены, чтобы то, что собирает этот поток, могло связать его с собственными записями вызывающей стороны. Запрос, который их не отправляет или отправляет некорректный контекст трассировки W3C, даёт строку без этих ключей: ничего не придумывается и ничего не изменяется по пути.

Процесс записывает собственный жизненный цикл в той же форме и в тот же поток, и каждая такая строка называет event там, где строка запроса называет метод и вызывающую сторону: startup при запуске, listening с адресом, к которому он привязался, startup-refused с причиной, по которой запуск был отклонён до начала обслуживания, signing-key-ignored, если обслуживаемое рабочее пространство называет ключ подписи, который не может использовать ни одна вызывающая сторона этого слушателя, docs-bundle с результатом получения пакета документации и shutdown при завершении работы. Два вида строк различают по наличию event.

Всё это вы собираете из потока ошибок процесса, и в этом состоит вся доставка. Нет экспортера для настройки, нет файла для указания и нет параметра, который включает, выключает или перенаправляет что-либо из этого: то, что управляет этим процессом, — среда выполнения контейнеров, менеджер служб, отправщик журналов, — и собирает этот поток, и там же вы затем делаете запросы к нему. При работе через стандартный ввод и вывод тот же поток содержит вместо этого читаемый текст, потому что клиент, который его читает, запустил процесс и находится на той же машине.

Ничего из этого не отправляется вызывающей стороне. Сервер не публикует поток журналов через протокол ни на одном транспорте, а на запрос с полем уровня журналирования для отдельного запроса из протокола отвечают ровно так же, как на запрос без него: то, что здесь записывается, принадлежит оператору и направляется только в поток оператора.

Что сервер сообщает модели при подключении

Сервер предлагает блок указаний для модели, который ваш клиент может показать ей до первого вызова. Клиент на 2026-07-28 читает его из ответа server/discover; клиент на 2025-06-18 — из ответа на своё рукопожатие initialize. На обоих путях это один и тот же текст, байт в байт, и один и тот же текст для каждого клиента, обращающегося к одному процессу: ничто в нём не согласуется и ничто не выводится из того, что прислал клиент, или из предъявленных им учётных данных, поэтому то, что модели сообщается при подключении, не меняется ни между сеансами, ни между клиентами.

Меняются две вещи, и ни одна из них не зависит от клиента. Заключительный абзац составляется для транспорта, который обслуживает процесс, поэтому сервер, работающий через стандартный ввод и вывод, и слушатель передают модели разный заключительный текст. А если десктопный пакет, запустивший сервер, относится к другому выпуску, чем запущенный им исполняемый файл aggrega, указания начинаются с одного предложения, сообщающего об этом и называющего обе версии, — того же предложения, с которого начинается ответ describe-capabilities без аргументов, как описано в разделе Из какого выпуска сервер; запуск, выполненный не пакетом, и запуск, чей пакет относится к собственному выпуску исполняемого файла, передают указания без него. Обе вещи фиксируются при старте процесса, и в пределах каждого процесса обе ревизии по-прежнему отдают собственный текст этого процесса одинаково.

Они объясняют мысленную модель, которую схема аргументов инструмента сама по себе передать не может:

  • Что компилятор делает и чего он намеренно не делает — что он передаёт текст и вычисляет совпадения меток, а не интерпретирует смысл значения, что он без собственного мнения относительно содержимого, которое вы помещаете в документы, и что во время компиляции он никогда не проходит аутентификацию у провайдера, никогда не читает состояние кластера и никогда не превращает секрет в открытый текст. Значение, которое существует только после запуска инфраструктуры, проходит как строка-указатель, которую целевая среда заполняет позже.
  • Словарь авторинга и связи между видами — для чего предназначен каждый вид и против какого из них фактически выполняется сборка, чтобы ассистенту не приходилось выводить форму развёртывания из списка инструментов.
  • Порядок цикла авторинга — прочитать контракт, создать по нему заготовку, изучить то, к чему выполняется подключение, затем проверить перед рендерингом.
  • Когда обращаться к промпту, а не к инструменту — инструмент для действия, промпт для постановки задачи.
  • Что список инструментов — это вся поверхность — в нём есть каждый инструмент, который предлагает этот сервер, а набор предлагаемых сервером инструментов зависит от того, как он настроен, поэтому ассистент узнаёт, что здесь есть, из этого списка и из describe-capabilities, а не ищет второй. Если соединение предъявило учётные данные, указания сообщают, что учётные данные определяют, какие из этих инструментов может выполнить вызов, но никогда — какие из них перечислены: вызов, который они не допускают, отклоняется с указанием области, которая бы его допустила, и клиент может снова войти для этой области.
  • Что означает пустое рабочее пространство и что модель может с этим сделать — абзац, который различается в зависимости от транспорта, см. ниже.

Они называют поверхности, а не пересказывают их. Каждый инструмент уже несёт собственное описание и схему аргументов в tools/list, а контракт каждого вида уже находится в его схеме и на его справочной странице, поэтому указания ссылаются на них и на этом останавливаются — у каждого утверждения одно место. Инструмент, который они называют, — это инструмент, который обслуживает сервер, и они указывают на каждое семейство ресурсов, которое разрешает поверхность чтения, поэтому ничто, за чем они отправляют ассистента, не ведёт в тупик.

Они не содержат перечня самих инструментов, и это то же правило, а не упущение из него. Клиент получает определение каждого инструмента из tools/list раньше, чем прочтёт хотя бы слово этого текста, поэтому строка на каждый инструмент здесь была бы второй копией уже известных ему назначений — оплачиваемой в каждом сеансе каждым клиентом и способной разойтись со списком инструментов, как только один из них будет изменён.

Они также сообщают, что не перечисляют, и почему: доступные цели рендеринга и установленные виды библиотек — это свойства ваших плагинов и вашего набора схем, поэтому поверхности ресурсов сообщают о них напрямую, вместо того чтобы указания несли копию, которая может расходиться.

Что модели сообщается о пустом рабочем пространстве

Заключительный абзац отвечает на вопрос, с которым модель сталкивается первым в пустом рабочем пространстве: что означает пустой list-entities и что она может с этим сделать. Его начало одинаково на обоих транспортах — пустой список означает, что разрешённое этим процессом рабочее пространство не содержит документов Aggrega, которые он может прочитать, и настроенные рядом с ним каталоги тоже их не объявляют, — а продолжение зависит от того, какой транспорт обслуживает процесс, потому что честный ответ на двух транспортах не совпадает.

Через стандартный ввод и вывод модели сообщается, что рабочее пространство она может изучать и исправлять. Ей сообщается, где отвечается вызов, не называющий рабочее пространство, — в папке, с которой был запущен сервер, если он был запущен с ней, а иначе в рабочем пространстве, найденном от папки, в которой он был запущен, и это может быть сама эта папка, — и что workspace_root в вызове называет другое. Её направляют к config-show за действующей конфигурацией и за тем, какой уровень определил каждую настройку, и к cli-config-init для создания рабочей конфигурации; оба есть в списке инструментов на этом транспорте. Клиент, запускающий сервер, находится на собственной машине вызывающего, поэтому всё, до чего может дотянуться этот процесс, принадлежит самому вызывающему, — а граница задаётся там же, где и для любого другого инструмента, в вашем MCP-клиенте, как описано в разделе Что ассистент может сделать, не спрашивая вас.

Через HTTP модели сообщается, что нужно сообщать о проблеме, а не настраивать. Рабочее пространство — то, над которым вы запустили процесс, и оно фиксировано на всё время его жизни; вызов, называющий workspace_root или catalog_dirs, отклоняется с указанием аргумента; и ни один инструмент, записывающий конфигурацию, здесь не предлагается никакому вызывающему, какие бы области ни несли его учётные данные. Эти операции выполняются только инструментами, которые запускают команду aggrega в отдельном процессе, а сеанс, установленный через HTTP, составляется без них, — поэтому граница задаётся составом, а не областью, и никакой токен её не расширяет. Модель, обращающаяся к вашему развёртыванию через слушатель, поэтому не может создать реестр или переписать политику доверия на вашем хосте, и абзац сообщает ей об этом, вместо того чтобы позволить ей попытаться и прочитать отказ.

Что ассистент может делать, не спрашивая вас

Ассистент, подключённый к этому серверу через стандартный ввод и вывод, может вызывать любой инструмент, который предоставляет сервер, не спрашивая вас, если ваш клиент не настроен это запрещать. На этом транспорте сервер предлагает инструменты и не решает, какие из них разрешено использовать тому или иному вызову: это решение принимает ваш клиент, и принимать его вам — там. Через HTTP всё иначе: сервер перечисляет все инструменты, которые несёт и объявляет, и отклоняет вызов, который не допускают области действия вызывающего токена, так что ограничение задаёт и сервер, и клиент.

Это важно, потому что поверхность инструментов — это командная строка. Всё, что можете набрать вы, может вызвать ассистент, — включая операции, изменяющие вашу машину.

Некоторые из этих операций действуют шире рабочего пространства, в котором вы работаете, и их нельзя отменить запуском чего-то другого. Вот те, которые стоит знать по именам, начиная с самых широких по охвату:

  • publish-entity, publish-artifact, sign-artifacts и deprecate-artifact выходят далеко за пределы машины. Они помещают в реестр байты, подпись или маркер отзыва, поэтому изменяют то, что разрешает каждый потребитель этого реестра, — а не только эта машина. Повторная публикация другого содержимого поверх тега отклоняется, а не предлагается, поэтому ничто здесь не отменяет публикацию; выход — опубликовать новую версию. Подпись и маркер отзыва не трогают байты артефакта, но каждый, кто затем загружает этот артефакт, загружает и их, и ни то, ни другое нельзя отозвать у тех, у кого они уже есть. Через стандартный ввод и вывод те же четыре возможности доступны также как cli-push, cli-push-artifact, cli-sign и cli-deprecate, которые запускают соответствующие команды; через HTTP этих четырёх инструментов нет.
  • Подписание использует учётные данные. Через стандартный ввод и вывод бесключевое подписание берёт токен идентичности из аргумента вызова identity_token, из AGGREGA_IDENTITY_TOKEN или SIGSTORE_ID_TOKEN в окружении сервера либо из окружающей конечной точки OIDC GitHub Actions, если она доступна; key_path вместо этого выбирает ключ, хранящийся офлайн. Поэтому ассистент, который может вызывать эти инструменты, может подписывать от вашего имени — любой идентичностью, которая уже есть у машины, где запущен сервер, — а подпись является заявлением о том, кто ручается за артефакт; именно поэтому над этой операцией стоит подумать тщательнее всего, прежде чем её разрешить. Через слушатель подписывает только токен, переданный в вызове: из окружения сервера ничего не читается, и ни один ключ, хранящийся на хосте, нельзя выбрать ни аргументом, ни конфигурацией обслуживаемого рабочего пространства, как описано в разделе Какие учётные данные расходует вызов.
  • aggrega cache evict сокращает хранилище скомпилированных модулей, а aggrega cache clear полностью его очищает. Это хранилище общее для всех проектов Aggrega на машине. Удалённые из него модули перекомпилируются по требованию, поэтому ничего не теряется безвозвратно, — но следующая сборка любого проекта платит эту цену. aggrega cache clear также удаляет пакет документации, который читает каждый проект на машине; он загружается снова, когда один из них в следующий раз его запрашивает.
  • aggrega cache prune освобождает записи кэша артефактов, на которые не ссылается ни один lock-файл. Если lock-файла проекта нет и его нельзя прочитать, закреплённые в нём артефакты им не защищены, и их освобождение означает, что их придётся загрузить снова.
  • aggrega registry add и aggrega registry remove по умолчанию записывают в конфигурацию, общую для всех рабочих пространств, поэтому изменяют то, что разрешается везде на машине, а не только здесь. aggrega registry add также запрашивает у указанного реестра политику доверия, которую этот реестр объявляет, и закрепляет полученное — точно так же, как в терминале. В офлайн-рабочем пространстве этот запрос отклоняется до какого-либо соединения, поэтому добавление реестра, отличного от официального хаба, отклоняется — короткий код E0310, теми же словами, — если вызов не передаёт identity или key; aggrega config init, который не принимает ни того, ни другого, офлайн может инициализировать только хаб. Через стандартный ввод и вывод они доступны как cli-registry-add и cli-registry-remove, а инициализация — как cli-config-init; эти инструменты запускают соответствующие команды; через HTTP этих инструментов нет.
  • pull читает из реестра и записывает внутри рабочего пространства, на которое указывает. Он записывает lock-файл этого Release, заполняет кэш артефактов тем, что разрешил, и записывает рядом с lock-файлом идентичность каждого возвращающего вердикт плагина, который подключает ваше рабочее пространство. Если передан pin_sources — или в рабочем пространстве, где включён pin_sources_at_pull, а вызов не передаёт его как false, — он также выполняет шаг закрепления автора сущности над Recipes и FeatureRecipes, из которых Release собирается в ваших каталогах, записывая entity.lock рядом с каждой; без этого pull над такой сущностью, чей lock не содержит закрепления для читаемого ею входа, отклоняется с указанием этого шага. Сами файлы сущностей никогда не записываются. Ничто из этого не покидает машину, а повторное разрешение — способ изменить записанное, поэтому это самая мягкая из записывающих операций здесь. Это один из инструментов, созданных для цикла создания, которые записывают внутри рабочего пространства: pin записывает entity.lock рядом с указанной вами сущностью Recipe или FeatureRecipe, как описано в разделе Закрепление собственных входов сущности; gen-catalog записывает сгенерированные сущности Plugin в указанный вами каталог; edit-document применяет одну ограниченную структурированную правку к уже имеющемуся документу и записывает его обратно, сохраняя каждый байт, которого правка не касается, как описано в разделе Применение одной ограниченной правки к документу; import превращает описание, созданное другим инструментом, в черновые файлы и записывает их в рабочее пространство, как описано в разделе Преобразование стороннего описания в черновые сущности; а scaffold с отправленным example записывает один из запускаемых примеров документации в новый или пустой каталог dir, как это делает aggrega scaffold --example, что по HTTP допускает область действия workspace-write. Этот выходной каталог, гостевой модуль, который читает gen-catalog, и любой переданный ему оверлей задаются относительно корня рабочего пространства или абсолютно через стандартный ввод и вывод — по тому же контракту, что и любой другой аргумент-путь на этой поверхности. Через стандартный ввод и вывод та же возможность доступна также как cli-pull, который запускает команду; через HTTP этого инструмента нет.
  • build читает тот же реестр и выполняет ту же запись, если вы передаёте ему auto_pull, и только тогда. Разрешение зависимостей Release — одна и та же операция, где бы её ни запрашивали, поэтому сборка, которой велено сначала разрешить зависимости, делает в точности то же, что pull, а затем выполняет рендеринг по записанному — именно поэтому у неё тот же охват, а не меньший. Если передан write, она также записывает отрендеренные артефакты в dist/ в корне рабочего пространства, куда их записывает aggrega build, и той же записью, поэтому на время этого вызова она затрагивает рабочее пространство; больше она никуда не пишет, а dist, являющийся ссылкой за пределы рабочего пространства, отклоняется до того, как в нём что-либо удаляется или записывается. Без обоих аргументов, что является поведением по умолчанию, build выполняет рендеринг по закреплениям, которые уже есть в рабочем пространстве, и ничего не затрагивает. О том, что меняет этот аргумент и что он оставляет нетронутым, см. раздел Сборка по содержимому, которое Release уже закрепляет.

Инструменты инвентаризации сообщают об этом в своих собственных ответах. cache-status помечает каждый класс кэша его охватом — workspace для кэша артефактов в собственном каталоге кэша этого проекта, machine для хранилищ, общих для всех проектов, — и прямо называет общемашинные, так что ассистент, читающий инвентаризацию перед тем, как предложить освобождение места, узнаёт, какие её части принадлежат не только вам. Операции обслуживания сообщают тот же охват для каждого удалённого элемента. Каждый из четырёх результатов публикации несёт собственное поле reach, содержащее registries — каждый хост реестра, к которому обращался вызов, каждый указан один раз, в порядке первого обращения, — и beyond_this_machine, значение которого определяется тем, что вызов фактически прикрепил, а не тем, что он запросил: true, как только он загрузил содержимое или прикрепил подпись, дату публикации или маркер устаревания, и false для пробного запуска и для вызова, который обнаружил, что всё это уже на месте, например для повторной публикации поверх полной версии или для пакета подписания, все ссылки которого уже были подписаны.

Где вы задаёте границу. Сам протокол не определяет разрешений для отдельных инструментов — его аутентификация касается того, может ли клиент вообще подключиться, а не того, какие инструменты он затем может вызывать. Решение о разрешениях принимается в вашем MCP-клиенте. Широко используемые клиенты, как правило, позволяют разрешать и запрещать отдельные инструменты одного сервера по имени, а также полностью отключать сервер для конкретного проекта; название и расположение этой настройки различаются от клиента к клиенту, поэтому сведения о разрешениях для инструментов ищите в документации вашего клиента. Если вам нужны чтения, но не записи, разрешите там нужные инструменты и запретите остальные. Разрешительная конфигурация или клиент без такой настройки оставляют доступным для вызова каждый предоставленный инструмент.

Как узнать, что содержит рабочее пространство

Большинство инструментов принимают субъект: имя сущности или путь к сущности Release. Два инструмента ниже не принимают ничего, и именно с их помощью только что подключившийся ассистент получает субъект.

list-entities отвечает, что содержит рабочее пространство, а list-releases — на более узкий вопрос, который остальные инструменты задают постоянно: какие Releases существуют. Ни один из них не принимает субъект, потому что содержимое рабочего пространства — свойство самого рабочего пространства, а не чего-либо, что вызывающей стороне нужно знать заранее.

Каждый отвечает в одной из двух форм, и вызов, не указавший форму, получает сводку. Это значение по умолчанию свойственно только этим двум инструментам и противоположно тому, которое принимают build, describe и validate. Тех спрашивают о субъекте, который вызывающая сторона уже назвала, поэтому запрошен именно полный ответ, а краткий включается явно. Этих же двух спрашивают, что здесь есть, причём вызывающая сторона ещё ничего не может назвать и не может знать, во что обойдётся ответ, пока он не придёт, — поэтому они сначала сообщают размер и структуру рабочего пространства и выдают записи только по запросу.

Сводка сообщает, что здесь есть и сколько. list-entities сообщает корень рабочего пространства (по HTTP он не передаётся, как описано в разделе Что ответ сообщает о файловой системе сервера), общее число сущностей и их количество по каждому виду; list-releases сообщает общее число и количество по каждому каталогу верхнего уровня, так что вы узнаёте, сколько существует Releases и в какой части дерева они находятся. Обе разбивки считываются из самих документов, поэтому рабочее пространство, устроенное так, как никто не предполагал, описывается так же точно, как и любое другое. Обе содержат по одной строке на вид или на каталог верхнего уровня, поэтому их размер зависит от того, сколько видов объявляет рабочее пространство и в скольких каталогах лежат его Releases, а не от числа документов: если увеличить число документов в сто раз, не меняя видов, сводка вырастет лишь на несколько байтов, нужных для записи бо́льших чисел. Длиннее её делает объявление новых видов. Ни одна из них не является первой страницей записей, и в этом весь смысл: «вот некоторые из сущностей» — это иной ответ, чем «вот из чего состоит рабочее пространство», и только второй говорит, нужны ли вам записи вообще и какие.

Отправьте response_format: detailed, чтобы получить записи, и они придут постранично. Тогда list-entities сообщает для каждой сущности её вид, имя, apiVersion, описание, метки и исходный файл, прочитанные непосредственно из документа, который её объявляет. Он также сообщает сущности Features, которые объявляют настроенные каталоги, чтобы сущность Feature, предложенную вам как присоединяемую, можно было и найти; у них нет исходного файла, потому что единственный путь, который у них есть, — это путь на машине, где работает сервер, и каждая указывает, откуда она взялась, так что пустой файл читается как «получено из каталога», а не как отсутствующее значение. list-releases сообщает путь каждой сущности Release, а lockfiles сопоставляет каждому возвращённому пути путь к lock-файлу этой сущности Release в той же системе координат: это файл, который для неё записывает pull и читает build, тот же файл, который называют ответы языкового сервера о сущностях Release. Это сопоставление описывает пути, которые несёт данный ответ, поэтому оно следует за страницей, а в сводке оно пустое.

detailed и concise — единственные значения, которые принимает response_format, и они сопоставляются точно. Любое другое написание — другое слово, другой регистр или пробелы вокруг значения — отклоняется, и отказ называет отправленное значение вместе с допустимыми. Чтобы запросить значение по умолчанию, опустите response_format; для этих двух инструментов это сводка. То же действует везде, где встречается этот аргумент: build, describe и validate принимают те же два значения на тех же условиях, но по умолчанию у них полная форма, а не краткая.

Число записей ограничено, даже если вы его не ограничиваете. limit — сколько записей содержит один ответ, от 1 до 500, по умолчанию 50, поэтому вызов, запрашивающий записи без указания размера страницы, всё равно ограничен, и ни один вызов этих инструментов не возвращает ответ, размер которого определяется размером рабочего пространства. offset — позиция в списке, с которой начинать, отсчёт с 0. Оба ограничивают записи, поэтому никак не влияют на сводку, в которой записей нет. Значение limit вне этого диапазона отклоняется с указанием границы; offset за концом списка возвращает пустой ответ, потому что там просто ничего нет, а не потому, что вопрос ошибочен.

Чтобы продолжить список, прочитайте в ответе три поля. count — сколько записей содержит рабочее пространство, offset и returned указывают, с какой позиции начинается этот ответ и сколько записей он содержит, а more_remaining — остались ли ещё записи. Пока more_remaining равно true, вызывайте снова с offset плюс returned. Этот признак вычисляется по странице относительно общего числа, а не записывается в ответ отдельно, поэтому он не может сообщить, что ничего не осталось, когда записи ещё есть.

Всё это важно, потому что инструменты, принимающие имя, отклоняют имя, которое не удаётся разрешить, а не отвечают пустым результатом. Отказ преднамерен — пустой ответ выдал бы опечатку в имени за субъект, которому нечего предложить, — но он означает, что вызывающая сторона без имени не может получить его угадыванием. Получить имя можно перечислением.

Эти два инструмента сочетаются друг с другом и с остальными:

  • Вызовите list-entities для сводки, чтобы узнать, какие виды есть в рабочем пространстве и сколько сущностей каждого вида, затем вызовите его снова с response_format: detailed для записей, возьмите имя из результата и передайте его в describe, чтобы увидеть полностью разрешённое определение этой сущности. Это то же определение, которым отвечает aggrega/entityDefinition языкового сервера, переданное в JSON: каждый ключ под тем именем, которое пишет автор, в том порядке, в каком он стоит в определении, схема — в том виде, в каком её написал автор, а схема, которую сущность не объявляет, опущена; например, у сущности Component — сокеты, каждый со слотами, которые могут заполнять их соединения.
  • Сделайте то же с list-releases: возьмите путь из подробного результата и передайте его в describe или build как сущность Release, с которой нужно работать.
  • Путь, который возвращает list-releases, задан относительно корня рабочего пространства — в той же системе координат, в которой list-entities сообщает файлы, поэтому оба ответа совпадают по файлу и их можно читать вместе. Её lock-файл в lockfiles задан относительно того же корня, поэтому этот файл можно прочитать или сравнить, не выясняя, где он находится.

Оба инструмента решают, что учитывать, читая собственный kind каждого документа, а не имя его файла. Release, названный без принятого префикса, попадает в список; файл, лишь названный как Release, — нет, и он появляется под тем видом, который фактически объявляет. YAML, не объявляющий kind вообще, — файл значений чарта, файл конфигурации, оказавшийся в дереве, — не является сущностью и не выводится, как и документ, принадлежащий другому проекту, например отрисованный манифест Kubernetes. Документ считается сущностью, когда он объявляет и kind, и имя, потому что именно эти два поля вместе делают его адресуемым в дальнейшем, и не объявляет apiVersion вне собственной группы Aggrega. Документ, не объявляющий apiVersion вовсе, выводится, поскольку это документ Aggrega с недостающим полем, а не файл другого проекта. list-releases не ищет ни в одном каталоге вне корня рабочего пространства, поэтому сущность Release, которую ваш редактор показывает под ссылкой, ведущей в такой каталог, в список не попадает; unread_linked_dirs называет каждую ссылку, которая стоит там, где листинг читал бы каталог, и ведёт за пределы корня, — по собственному пути ссылки относительно корня, а не по тому, куда она ведёт, — в обеих формах и на обоих транспортах, и пуст, если таких нет. Не читает он и файл вне корня через ссылку: unread_linked_files называет тем же способом каждую ссылку, собственное имя которой оканчивается на .yaml или .yml и которая ведёт к файлу вне корня, что бы этот файл ни содержал, поэтому сущность Release, доступная только через такую ссылку, в список не попадает — если только конфигурация рабочего пространства не называет эту сущность Release как build.authoring_release или как ключ workspace.releases; в этом случае она читается и выводится на собственном месте ссылки, а ссылка не называется. list-entities тоже не читает ни одного документа за ссылкой, ведущей из рабочего пространства, — он не ищет ни в одном каталоге вне корня и не читает ни одного файла вне его, что бы этот файл ни объявлял, — и называет каждую такую ссылку тем же способом, в собственных unread_linked_dirs и unread_linked_files, в обеих формах и на обоих транспортах. Это верно, что бы ни объявлял документ, с единственным исключением, которое делает list-releases: сущность Release, которую называет конфигурация рабочего пространства как build.authoring_release или как ключ workspace.releases, читается и выводится на собственном месте ссылки, а ссылка не называется, тогда как файл, названный одной из этих настроек и объявляющий что-либо, кроме Release, в список не попадает, а его ссылка называется. Настроенные каталоги каталогов — это способ, которым рабочее пространство читает другие сущности, хранящиеся в другом месте, поэтому ссылка на каталог, который конфигурация перечисляет в catalog_dirs, или на каталог внутри него не называется ни одним из листингов: конфигурация до него дошла. Среди сущностей Features, которые list-entities берёт из каталогов каталогов, никогда нет таких, что находятся за ссылкой, ведущей из каталога, в пределах которого должно оставаться чтение каталога каталогов, — рабочего пространства для каталога каталогов внутри него или самого каталога для того, который конфигурация называет вне рабочего пространства, — поэтому сущность, названная как находящаяся за непрочитанной ссылкой, никогда не выводится рядом с этим именем. Ссылка, которую листинг исключает — по её имени, по её расположению или по .gitignore, — не называется, а с release не называется и ссылка внутри каталога каталогов, который читают только другие сущности Releases; .gitignore, который сам является ссылкой, ведущей из рабочего пространства, не читается. Если какой-либо из этих списков называет ссылку, текстовый ответ завершается отдельной строкой, сообщающей об этом.

Рабочее пространство, файл конфигурации которого ведёт за его пределы, всё равно выводится в листинге, и ничего другого для него не отвечается. Если собственный .aggrega-config.yaml рабочего пространства или принадлежащий CI оверлей рядом с ним является ссылкой, ведущей из рабочего пространства, его конфигурация не читается, как и в терминале, и ничего из того, что она настроила бы, не читается вместо неё. Сервер всё равно запускается через стандартный ввод и вывод и сообщает об этом одной строкой в своём потоке ошибок. list-entities и list-releases отвечают собственными документами рабочего пространства, прочитанными без какой-либо настройки, поэтому сущности Features ни одного каталога каталогов не выводятся. Каждый из них называет удержанный файл в unread_linked_files и в строке, завершающей его текст, независимо от того, встретил ли его листинг, — по этому имени можно понять, что конфигурация рабочего пространства ведёт за его пределы. Листинг, которому передан release или catalog_dirs, и любой другой инструмент, называющий это рабочее пространство, определяются непрочитанной конфигурацией, поэтому каждый отклоняется с E0321, с указанием ссылки и того, куда она ведёт. Сервер, которому в командной строке указано слушать, — --transport http или --listen, — не запускается над таким рабочим пространством, потому что адрес, к которому он привязался бы, его сертификат и то, кто может его вызывать, определяет именно эта конфигурация. Удалите ссылку или сделайте так, чтобы она вела к файлу внутри рабочего пространства, и следующий вызов прочитает конфигурацию. См. границу рабочего пространства.

Запрос в терминах одной сущности Release

Рабочее пространство может задать каждой сущности Release собственные каталожные директории — см. Собственные каталожные директории для Release — и так хранить рядом вариант одной сущности для каждой Release. Три инструмента, которые иначе отвечают по собственным каталожным директориям рабочего пространства, принимают необязательный release — путь к файлу Release — и тогда отвечают в терминах этой Release:

  • list-entities с release перечисляет сущности, которые видит эта Release. Перечисляются те Features, которые объявлены в её каталожных директориях, а документ рабочего пространства в каталожной директории, которую читают только другие Releases, пропускается, так что каждый вариант перечисляется для той Release, которая с ним собирается, и ни для какой другой. Документ, не лежащий ни в одной каталожной директории, — Release, её Aggregate и её Manifest, написанные рядом с каталогами, — перечисляется для каждой Release.
  • describe с name и release разрешает имя через каталожные директории этой Release, так что имя, объявленное несколькими вариантами, разрешается в тот, с которым собирается эта Release. Имя, которое эти директории не разрешают, отклоняется с пояснением, называющим запись этой Release в workspace.releases. Ссылка на реестр читается из своего реестра, какая бы Release ни была названа, поэтому вместе с release она отклоняется. release, отправленный без name, по-прежнему задаёт Release, которую резюмирует describe.
  • validate с entity и release выполняет проверки одной сущности в терминах этой Release: ссылки сущности — Component, который реализует Recipe, SchemaLibrary, на которую ссылается опора, — разрешаются через каталожные директории этой Release, а ответ называет Release рядом с сущностью. Замыкание не проверяется; release, отправленный без entity, по-прежнему задаёт область Release. catalog_dirs и здесь, как везде, добавляется перед директориями Release. Директория, указанная в конфигурации рабочего пространства и не являющаяся директорией, — скажем, там ничего нет, — для этой Release или для рабочего пространства, если release не отправлен, приводит к отклонению вызова до какой-либо проверки, и текст несёт отказ, который даёт ей каждая команда, называя запись, а также файл конфигурации и строку, где она указана (Откуда читаются локальные сущности), так же как её отклоняет aggrega validate.

release, указывающий на несуществующий файл или на директорию, отклоняется всеми тремя инструментами, а не получает ответ в терминах рабочего пространства. Если он не отправлен, ответ даётся по собственным каталожным директориям рабочего пространства.

describe при поиске имени отклоняет каталожную директорию, через которую он разрешал бы имя и которую нельзя обойти, так же как её отклоняет aggrega inspect — директории этой Release, если отправлен release, собственные директории рабочего пространства, если нет, и любые, названные вызовом в catalog_dirs. Названная вызовом директория, которая не существует или существует, но не читается, отклоняется до поиска имени, и текст называет директорию так, как её сообщает командная строка, в одной строке — директория, catalog load и причина, которую дала файловая система, — вместо того чтобы разрешать имя по оставшимся директориям. Директория, указанная в конфигурации рабочего пространства и не являющаяся директорией, отклоняется в тот же момент, и текст несёт отказ, который даёт ей каждая команда (Откуда читаются локальные сущности). release, указывающий на несуществующий файл, отклоняется ещё раньше, как описано выше. Каталожная директория, содержащая ссылку, ведущую за пределы директории, внутри которой должно оставаться её чтение, отклоняется так же, и текст называет ссылку и то, куда она ведёт, потому что имя, разрешённое без неё, могло бы разрешиться в другую сущность с тем же именем. На описание замыкания зависимостей Release директория, которую нельзя обойти, не влияет: ответ даётся по директориям, которые можно обойти, как это делает aggrega inspect --closure, — кроме директории, указанной в конфигурации рабочего пространства для этой Release и не являющейся директорией: её он отклоняет так же, как её отклоняет aggrega inspect --closure; ссылка, ведущая за пределы чтения каталожной директории или за пределы документов рядом с Release, останавливает его, как останавливает сборку.

validate с entity сообщает о рендере, который не может оценить, как о непредпринятом — в терминах Release или без них. Он помещает Component сущности Recipe в синтезированную сборку, которая не создаёт соединений и не подключает ни одной Feature, поэтому Recipe, рендер которого останавливается, пока его шаблоны — включая импортируемые ими файлы и записи библиотек — читают что-либо из .context.inject, .context.uses или .features, получает ответ valid: true с пустым diagnostics; его текст содержит Render: not attempted (this Recipe reads values a build of one cannot supply), чтения, из-за которых он был отложен, и предложение, на котором остановился рендер. Решает то, что читает Recipe, поэтому собственная ошибка Recipe рядом с таким чтением откладывается вместе с ним, тогда как шаблон, который не разбирается, и ссылка, которую рендер отклоняет, по-прежнему дают valid: false. aggrega validate выносит тот же вердикт на тех же входных данных.

validate с entity сообщает о неудавшемся утверждении как о предупреждении — в терминах Release или без них. Утверждение, вызывающее fail, — собственное утверждение Recipe или объявленное в Component, который он реализует, — даёт ответ valid: true с пустым diagnostics. Синтезированная сборка содержит заполнители и значения по умолчанию из схемы вместо значений, которые задаёт реальная Release, поэтому утверждение над таким значением там не выполняется независимо от корректности Recipe, и проверка не может отличить утверждение, ожидающее Release, от сломанного. Сбой следует за остальными notices в виде полного сообщения утверждения, завершённого предложением A Release must satisfy this assertion before a build of it can pass., а текст содержит его в строке, начинающейся с warning:, рядом со строкой отчёта о том, где остановился запуск. Утверждение, которое останавливается на ключе, который оно читает, но не находит, — это ошибка в его собственном тексте, а не неудавшееся утверждение, и оценивается как любая другая остановка; сборка Release, не удовлетворяющей утверждению, по-прежнему из-за него отклоняется. aggrega validate выносит тот же вердикт на тех же входных данных.

Чтение действующей конфигурации и плагинов, которые разрешает этот сервер

config-show сообщает действующую конфигурацию и то, какой слой определил каждую настройку. plugin-list сообщает плагины, которые этот сервер может разрешить, и то, что каждый из них сообщает о себе. Оба ничего не читают и ничего не записывают, поэтому ни один из них никуда не обращается и aggrega:read их допускает, — и ни один не просит вас назвать предмет запроса, потому что то, что настроено и что разрешается, — свойства этого сервера, а не чего-то, что нужно знать заранее. Каждый принимает необязательный workspace_root при работе через стандартный ввод и вывод; по HTTP этот аргумент отклоняется, как описано в разделе Один процесс, одно рабочее пространство.

Вместе они отвечают на один вопрос в двух половинах: отсутствует ли возможность или просто не настроена здесь. Конфигурация говорит, подключён ли вообще провайдер, импортёр или проверка управления; чтение плагинов говорит, доходит ли подключение до гостевого модуля, который разрешается, описывает себя и обслуживает то, что заявляет. Со всех остальных мест этого интерфейса эти два случая выглядят одинаково, а следующие шаги для них противоположны.

config-show сообщает по одной записи на настройку: её field, её действующее значение value и источник source, который её определил, — файл конфигурации, переменная окружения, флаг командной строки или встроенные значения по умолчанию. Рядом с ними layers содержит слои, внёсшие вклад, в порядке приоритета, начиная с наименьшего. source настройки записывается в точности как соответствующая запись в layers, поэтому их можно сопоставить напрямую, а настройка, определённая значениями по умолчанию, не называет никакого слоя, потому что значения по умолчанию — не слой, внёсший вклад. Глобальный слой — это файл, который выбирает собственная командная строка сервера: тот, что был указан в --config при запуске, иначе тот, что называет переменная окружения AGGREGA_CONFIG, иначе расположение по умолчанию, — поэтому настройка, определённая этим файлом, приписывается этому файлу, в точности как её приписывает aggrega config show --origin, а флаг вроде --offline, переданный серверу, сообщается как этот флаг. Инструмент не принимает ни response_format, ни размера страницы: настройки — это фиксированный набор, который учитывает этот двоичный файл, и каждое разрешение сообщает их все, поэтому размер ответа зависит от двоичного файла, а не от того, что вы настраиваете.

plugin-list отвечает в двух формах, которые используют списки рабочего пространства, а вызов, не указавший форму, получает сводку. Сводка — это счётчик по группам, и групп две: embedded — гостевые модули, скомпилированные в этот двоичный файл, которые разрешаются без доступа к файловой системе, кэшу или сети, и configured — собственные привязки рабочего пространства. Отправьте response_format: detailed, чтобы получить записи: для каждого плагина — его группу, ссылку, по которой он найден, место, где эта ссылка привязана, его самоописанные тип, версию, коммит, обслуживаемые возможности, виды отображаемых входных данных, граничную сборку и экспорты, его готовность, если она у него есть, и то, разрешился ли он. Записи ограничиваются limit и offset на тех же условиях, что и список сущностей, с count, returned и more_remaining для продолжения. Этот ответ действительно растёт вместе с тем, что вы настраиваете, — встроенные модули фиксированы, привязки ваши, — поэтому он разбит на страницы, а чтение конфигурации нет.

Плагин, который даёт сбой, сообщается вместе со своим сбоем, а не исключается из списка. resolved говорит, дошла ли ссылка вообще до байтов модуля, а плагин, который разрешился, но не смог описать себя, сообщается именно так, — поэтому подключение, которое присутствует, но непригодно, можно отличить от того, которое так и не было сделано.

Что слушатель не сообщает о своём хосте

По HTTP ни одно из чтений не сообщает значение, называющее место в файловой системе сервера. Клиент, запустивший сервер, работает там же, где сервер, поэтому каждое расположение, которое мог бы назвать любой из ответов, уже принадлежит этому вызывающему, и он может пойти и посмотреть на него. Вызывающий, обращающийся к слушателю, не выбирал ни одного из них, не может ничего сделать, зная их, а сервер, опубликовавший их такому вызывающему, не может отозвать публикацию. Через этот транспорт эти значения отсутствуют; через стандартный ввод и вывод все они присутствуют. Это правило, которому следует каждый ответ этого интерфейса, как описано в разделе Что ответ говорит о файловой системе сервера, и в этих двух чтениях оно действует шире всего, потому что бо́льшая часть того, что они сообщают, — конфигурация, называющая места.

Что скрывается. Из config-show: value настройки, если собственное значение этой настройки — расположение: адрес обслуживания или проверки работоспособности, который может быть файлом сокета; файл сертификата, закрытого ключа или набора ключей; каталог каталога сущностей, а также собственные каталоги сущностей Release в workspace.releases, каждая запись которых имеет ключом файл Release; ссылка на плагин; авторская сущность Release. Также source настройки, если определивший её слой — файл конфигурации, поскольку такой слой называется собственным путём этого файла, — и, в том же написании и по той же причине, записи layers для файлов конфигурации. Из plugin-list: uri плагина, если сама эта ссылка — путь в файловой системе, и текст сбоя разрешения или описания, который составляется из мест, где выполнялись попытки, и поэтому называет расположения, которых сама ссылка не называет. Из обоих: workspace_root.

Что сообщается полностью, на обоих транспортах. Ссылка на реестр, версия, коммит, дайджест, обслуживаемая возможность, метка готовности, имя переменной окружения или флага, а также слой, не являющийся файлом. origin в записи плагина относится к этому: это ключ конфигурации, под которым записана привязка, или закреплённый дайджест, который несёт установленное расширение команды, а встроенный модуль не несёт ничего, — поэтому это одна и та же строка, откуда бы ни читался плагин. resolved — тоже: то, дал ли плагин сбой, сообщается каждому вызывающему, даже если причина сбоя не сообщается.

Отсутствующее значение всегда говорит о том, что оно скрыто, и именно это делает ответ пригодным. Скрытое значение сообщается как отсутствующее с отметкой рядом: value_withheld и source_withheld у настройки, withheld у записи слоя, uri_withheld и error_withheld у записи плагина и workspace_root_withheld у ответа. Настройка, которую никто не задавал, несёт пустое значение, в которое отображается её форма, и не несёт отметки. «Этот сервер не сообщает вам, где находится ключ подписи» и «ключ подписи не настроен» — разные ответы, требующие разных следующих шагов, и чтение, сообщающее их одинаково, не сказало бы ничего, на основе чего можно действовать. Каждый ответ также всегда несёт host_locations_withheld, которое говорит, какой из двух ответов у вас в руках: ответ без отметок в остальном одинаков, сформировало ли его это правило и на хосте было нечего скрывать, или правило вообще не применялось. Читаемый текст рядом с полями говорит то же самое словами.

Правило — это свойство, а не список имён полей: значение скрывается, если оно называет место в файловой системе хоста, кто бы его ни задал и из какого бы слоя оно ни пришло. Значение, добавленное в любое из чтений позднее, подчиняется тому же свойству.

Через стандартный ввод и вывод каждая возможность также доступна как инструмент, названный по её команде, — cli-config-show и cli-plugin-list, — которые запускают эту команду в отдельном процессе и возвращают напечатанный ею текст; по HTTP этих инструментов нет. Два описанных здесь инструмента вместо этого несут значения, поэтому вы узнаёте, подключена ли возможность, или извлекаете версию плагина, не разбирая колоночную разметку обратно в то, из чего она была отображена.

Что может присоединяться и что с чем может соединяться

Два инструмента отвечают на вопросы, о которых ассистенту иначе пришлось бы догадываться: какие Features могут присоединяться к узлу и с чем узел может соединяться. Оба выполняют то же сопоставление меток, что и компилятор, поэтому ассистент предлагает вам тот набор, который сопоставила бы сборка, а не набор, выведенный из схемы.

attach-candidates сообщает Features, объявленной применимости которых удовлетворяют метки узла. Укажите узел ровно одним из трёх способов:

  • node — metadata.name сущности рабочей области в том виде, в каком его сообщает list-entities. Сопоставление выполняется по меткам, которые объявляет этот документ.
  • graph_node вместе с release — узел скомпилированного графа с ключом в том виде, в каком его задаёт граф, включая квалифицированную форму, которую имеет узел, добавленный вложенным агрегатом. Сопоставление выполняется по окончательным меткам этого узла, то есть по тем, которые вычисляет сборка.
  • labels — отдельный набор меток без указания узла. Эта форма не требует никаких координат, поэтому если метки узла у вас уже есть, используйте её; она ничего не ищет и не перестраивает граф.

Ответ содержит метки, по которым выполнялось сопоставление, и указывает, из какого из этих трёх наборов они взяты, поэтому любого кандидата — или его отсутствие — можно объяснить по самому ответу, не вычисляя его заново. Если считывать их повторно другим способом, ваше представление о метках узла и представление компилятора расходятся.

Чтобы узнать, что может присоединяться к одному соединению, которое проводит узел, добавьте connection рядом с graph_node и release — его socket и его alias так, как их записал автор. Соединение несёт присоединения, заполняющие слоты, которые его сокет объявляет в потребляющей сущности Component, поэтому ответ тогда содержит также slots: каждый слот, объявленный сокетом, с его selector, required, inject, sensitive и description в точности так, как их объявляет Component, и candidates, которые могут его заполнить. Это Features, применимости которых удовлетворяют метки узла, и собственные метки которых допускает селектор слота, — два правила, которым сборка подчиняет такое присоединение, — поэтому кандидаты слота всегда входят в число кандидатов самого узла. Если заполнять нечего, slots пуст, а noSlotReason объясняет почему: feature-created-connection (соединение провела Feature, а к такому соединению ничего не присоединяется), ad-hoc-socket (сокет не объявлен в Component) или no-slot-declared (сокет не объявляет слотов). Не воспринимайте пустой slots как «ничего не совпало»: именно это причина и призвана исключить, и она отсутствует везде, где слот существует. candidates рядом с ними сохраняет своё значение — что может присоединяться к самому узлу, — а document, если вы его передадите, здесь ничего не меняет. connection рядом с node или labels, а также без указания сокета или псевдонима отклоняется, как и соединение, которого узел не проводит. Это те же ответы, что даёт языковой сервер, на тех же условиях.

connection-candidates сообщает сокеты зависимостей, которые объявляет сущность, и для каждого сокета — сущности Components рабочей области, объявленные метки которых удовлетворяют ограничению, объявленному этим сокетом для своих целей. Он принимает metadata.name сущности в node. В отличие от attach-candidates, у него нет формы без координат: формы с набором меток здесь нет, потому что сокеты считываются из собственного объявления названной сущности.

Две его половины неодинаково полны, и ответ указывает, какая есть какая, — не представляйте их как один список. Цели полны: это те компоненты, которые то же ограничение допускает во время сборки. Сокеты — нет, и быть полными не могут. Потребитель может придумать соединение, но может потреблять только то, что объявляет производитель, поэтому автор вправе записать сокет, который сущность каталога никогда не объявляла, а объявленные сокеты — полезная отправная точка, а не набор допустимых имён. Поэтому каждый сокет указывает, является ли он declared или ad-hoc, а ответ указывает, принимается ли необъявленный сокет для этой сущности вообще: собственная поверхность зависимостей сущности Component его принимает, потому что топология приложения принадлежит автору; поверхность присоединения сущности Feature — нет, потому что присоединение участвует в топологии, которую объявляет присоединяемая Feature, а не создаёт свою. Эта открытость — следствие вашей свободы авторинга, а не пробел: передайте socket с именем, которое сущность не объявляет, чтобы спросить о нём.

Оба отвечают и останавливаются. Ни один не создаёт присоединение, не создаёт ребро, не записывает ни в какой файл и не предлагает текст такой правки; составление и применение последующей правки — за вами.

Оба возвращают ту же минимальную идентификацию, что и все остальные ответы здесь, — вид, имя и исходный файл — и ничего больше. Всё остальное, что вы хотели бы показать о сущности, уже есть в list-entities по тем же трём полям, поэтому вы объединяете два ответа, а не читаете две копии, которые могут расходиться. Оба отклоняют имя, которое не могут разрешить, вместо того чтобы отвечать пустым списком, по той же причине, что и остальная поверхность: пустой ответ выдал бы опечатку за субъект, которому нечего предложить. В вызове с labels нет имени, в котором можно опечататься, поэтому пустой результат там означает ровно то, что говорит.

Всё, что сервер читает для справки, обслуживается с этой машины: схемы JSON Schema встроены в двоичный файл, а документация читается из кэша пакетов документации, который хранит машина, как описано ниже. Создание черновика начального документа, проверка, описание, сборка и линтинг выполняются над вашей рабочей областью и локальными кэшами, и ни одна из этих операций не обращается к реестру по собственной инициативе: рендеринг берёт закреплённую внешнюю ссылку из хранилища с адресацией по содержимому и отклоняет незакреплённую, а не загружает её, — именно это сохраняет весь цикл проверки и рендеринга автономным. Из реестра можно запросить два чтения: describe со ссылкой на реестр, который загружает эту одну координату, ничего не записывает и по HTTP обращается только к реестру, настроенному для обслуживаемой рабочей области; и scaffold с отправленным example или list, который получает пакет документации из реестра рабочей области по умолчанию, если на машине нет копии, допускаемой политикой подписей рабочей области, и проверяет его перед сохранением, как это делает aggrega scaffold --example. Публикация и подписание — сознательная обратная сторона этого, они описаны выше.

Между ними находится разрешение зависимостей сущности Release — единственное здесь действие, которое что-то получает: оно обращается к реестру, потому что просьба разрешить зависимости и есть просьба их загрузить. Это происходит только по вашему запросу, и запросить можно ровно двумя способами — вызвав pull, в чём и состоит вся его задача, или передав auto_pull в build, который выполняет то же разрешение первым шагом сборки. Иначе ничто не выполняет загрузку от вашего имени, и сборка, которой вы не передали auto_pull, к реестру не обращается. Единственная настройка, меняющая это, — собственный auto_pull рабочей области: рабочая область, настроенная так, требует, чтобы каждая сборка в ней сначала выполняла разрешение, откуда бы эта сборка ни запускалась; это описано ниже.

Единственное исключение среди этих справочных чтений — получение самого пакета документации, и оно происходит отдельно от всех чтений. Пакет хранится один раз на машину, в кэше, общем для всех проектов Aggrega, по одной копии на каждый реестр и версию, — поэтому сервер, запущенный в папке, где кэш рабочей области создать нельзя, всё равно его хранит (см. aggrega cache). При запуске, прежде чем ответить на что-либо, что вы отправите, сервер ищет там копию, которую допускает проверка подписи вашей рабочей области, — та же проверка, которой подчиняется загрузка пакета, — и загружает пакет через те же настройки исходящего трафика, что использует остальной CLI, только если такой копии нет. Пакет, который он ищет, — это пакет, опубликованный для версии aggrega, которую запускает сервер, или, если для неё ничего не опубликовано, самый новый из опубликованных для более ранней версии, — тот же выбор, что делают aggrega explain и aggrega scaffold --example, — и каждая страница, которую он отдаёт, и каждое объяснение читаются из полученного им пакета. Так страницы уже на месте к моменту, когда что-либо их запросит, что бы ни отправил ваш клиент первым, а другой сервер или aggrega explain в другом проекте находит ту же копию, а не загружает её заново.

Выдача страницы после этого — это чтение этой копии, и она не обращается ни к какому реестру. Перед выдачей страницы подписи, хранящиеся рядом с копией, снова проверяются по проверке вашего рабочего пространства, поэтому копия, которую впустила более мягкая настройка другого проекта, вам не выдаётся: если проверка закрепляет ключ или корень доверия, эта верификация выполняется офлайн, а если не закрепляет ни того, ни другого — такова, например, встроенная проверка официального хаба, — она получает публичный корень доверия Sigstore, как это делает pull. Офлайн-рабочее пространство не может загрузить этот корень доверия, поэтому в офлайн-режиме оно проверяет по корню доверия, который более ранняя онлайн-загрузка на этой машине оставила в кэше, хранимом клиентом Sigstore в .sigstore в вашем домашнем каталоге, как бы давно ни была та загрузка, и ничего не загружает; на машине, которая ни разу его не загружала, проверка не может выполниться офлайн, копия не выдаётся, и поток журнала сообщает об этом. Эта верификация выполняется один раз для каждой копии и каждой проверки, пока работает сервер, и страницы, читаемые после неё, выдаются на основании того, что она допустила: копия, загруженная с тех пор, рабочее пространство с другой проверкой — включая закреплённый корень доверия, отредактированный на месте, — чтение, выполненное офлайн, или офлайн-чтение, обнаружившее на машине другой корень доверия, проверяются отдельно. Копия, отклонённая вашей проверкой, проверяется снова при следующем чтении, поэтому загрузка, которая с тех пор её допустила, не отменяется. Если пакет документации не удаётся получить или единственная копия — та, которую ваша проверка отклоняет, а повторная загрузка с этой проверкой завершается неудачей, сервер всё равно запускается и все остальные поверхности работают; запросы документации отвечают «не найдено», а поток журнала сервера сообщает почему.

Сборка на основе содержимого, уже закреплённого сущностью Release

build отрисовывает сущность Release в её артефакты в памяти, и отрисовка может запросить содержимое по удалённому URL — например, схему values чарта с удалённой ссылкой. Внешние входные данные на время вызова заморожены. Ссылка, которую lockfile сущности Release уже закрепляет, обслуживается из контентно-адресуемого хранилища, то есть это чтение содержимого, уже находящегося на диске, а не загрузка. Ссылка, которую lockfile не закрепляет, отклоняется и называется, а не загружается: вы запросили отрисовку, а получение ссылки означало бы и обращение к сети, и запись blob-объекта в хранилище как побочный эффект создания байтов. Эта заморозка — свойство отрисовки. Разрешение — это шаг, который получает данные: он отрисовывает сущность Release, чтобы выяснить, какие удалённые ссылки запрашивает эта отрисовка, загружает их и записывает в той же записи lockfile, которая содержит закрепления зависимостей. Поэтому разрешение меняет то, какие ссылки закреплены к моменту запуска отрисовки, но никогда не то, к чему отрисовка может обращаться, — и ссылка, которую не закрепило ни одно разрешение, отклоняется в вызове, выполнившем разрешение заранее, точно так же, как в вызове, который этого не сделал.

Файлы возвращаются в виде тех же байтов, которые выдаёт настоящая сборка, и это обеспечивают две вещи вместе. Первая — описанная выше заморозка: закреплённая ссылка читается из хранилища, а не загружается. Вторая — то, что читаемый lockfile по-прежнему описывает, во что разрешается сущность Release, поэтому build проверяет это и отклоняет lockfile, который больше не соответствует, точно так же, как aggrega build в терминале. Само по себе чтение закреплённых байтов ничего не говорит о том, были ли это нужные байты.

Все три состояния lockfile, чтобы позиция была явной. При отсутствии lockfile build отрисовывает на основе того, что уже закреплено в рабочем пространстве, и отклоняет каждую внешнюю ссылку, которую не может обслужить, называя каждую; сам по себе он не требует lockfile и не записывает его, и описанная выше проверка этого не меняет — сравнивать не с чем, поэтому ничего не отклоняется. С lockfile, который соответствует, он выполняет отрисовку. С lockfile, который больше не соответствует, он отказывает, и отказ называет способ это устранить: вызвать pull с тем же release и без upgrade_targets, что согласует lockfile с тем, во что сущность Release разрешается сегодня. Отказ также содержит терминальную форму той же операции — aggrega pull --release <release>. Любой из вызовов устраняет его; это одна операция, доступная из двух мест, а не две инструкции на выбор. Если pull завершается, а отказ возвращается снова, два вызова выполняли разрешение по разным входным данным — чаще всего catalog_dirs передан одному и не передан другому, или конфигурация рабочего пространства изменена между ними, — и отказ сообщает об этом: вызовите оба с одинаковыми параметрами.

validate и describe, которым передан только release, подчиняются тому же lockfile. Если lockfile больше не соответствует тому, во что разрешается Release, каждый из них отказывает вместо ответа, и его текст содержит остановку по расхождению, с которой отказывает build, и тот же способ её устранить, — так же, как aggrega validate --release и aggrega inspect --closure отказывают в терминале. С соответствующим lockfile или без него каждый отвечает как обычно.

Запрос сборки с предварительным разрешением зависимостей

Передайте auto_pull, и сборка выполнит разрешение перед отрисовкой. Она выполняет то же разрешение, что и pull, — саму эту операцию, а не вторую, написанную для сборки, поэтому рабочее пространство, заполненное сборкой, и рабочее пространство, заполненное вызовом pull, заполняются одинаково, — записывает lockfile сущности Release, а затем выполняет отрисовку на основе записанного. Этот шаг обращается к реестру и выполняет запись, чего в build больше не делает ничто, кроме write, а write к реестру не обращается, — поэтому он выключен, если его не запросить.

Он решает проблему обоих описанных выше отказов, не выходя из протокола. Сущность Release, которую ещё никто не разрешал, отрисовывается на основе тех закреплений, что окажутся в наличии, а остальное отклоняется; lockfile, который разошёлся с источником, сразу останавливает сборку. Передача auto_pull сначала выполняет разрешение и отрисовывает на основе lockfile, полученного из замыкания, к которому относится эта сборка, поэтому оба случая возвращаются как отрисовка, а не как то, что нужно пойти и исправить. Если разрешение и отрисовку нужно выполнить отдельными шагами — чтобы прочитать закреплённое до отрисовки, — вызовите pull, а затем build: это те же две операции с просмотром между ними.

Один вызов отрисовывает сущность Release один раз. Выяснение того, какие удалённые ссылки потребляет сущность Release, само по себе является отрисовкой, поэтому разрешение уже отрисовало сущность Release, к которой относится сборка, — на основе только что записанных закреплений и со всеми проверками, которые выполняет сборка. Ответ сборки берётся из этой отрисовки, а не из её повторения, поэтому передача auto_pull стоит одного разрешения, а не второй отрисовки. Так используется только завершившаяся отрисовка: если разрешение закрепило зависимости, но не смогло завершить обнаружение внешних ссылок, сборка выполняет собственную отрисовку на основе тех закреплений, которые были записаны, и тогда незакреплённая ссылка останавливает её с указанием имени, а не возвращается в виде списка файлов, не дотягивающего до того, что выдаёт сборка.

Возвращаемый ответ сообщает, что было разрешено. Сборка, выполнившая заполнение, содержит в ответе dependency_resolution в той же форме, в которой отвечает pull: записанный lockfile, каждую ссылку, к которой обратилось разрешение, с версией, в которую она разрешилась, и источником, откуда её взяло разрешение этой сборки, количества, содержащиеся в lockfile после этого, и построчный отчёт самого разрешения. Сборка, не выполнявшая заполнение, такого поля не содержит вовсе, поэтому по его наличию можно различить эти два случая, не читая диск. Отрисованные файлы сообщаются точно так же, как для любой другой сборки, и по-прежнему возвращаются в памяти, если вызову не был передан также write, — разрешение записывает lockfile и кеш артефактов, но никогда не артефакт.

Рабочее пространство может запросить это на постоянной основе, и вызов не может это отключить. Собственная настройка auto_pull рабочего пространства включает тот же шаг для каждой сборки в нём, а auto_pull в вызове дополняет эту настройку, а не переопределяет её: достаточно любой из них, и нет аргумента, подавляющего разрешение, которое запросило рабочее пространство. Точно так же настройка и aggrega build --auto-pull сочетаются в терминале, поэтому одно рабочее пространство отвечает одинаково, через какой бы интерфейс ни пришла сборка.

Об отклонении сообщается, а не замалчивается, и с провайдерами, входящими в этот исполняемый файл, отклонение останавливает отрисовку: провайдер, запросивший ссылку, возвращает отказ, поэтому вызов отвечает этой ошибкой и не возвращает файлов. Ссылка называется там, где читатель может на это отреагировать, вместе с командой, которая её закрепляет: aggrega pull --release <path>. То же закрепление доступно в этом интерфейсе как инструмент pull, описанный ниже в разделе Разрешение зависимостей сущности Release, поэтому ассистент, получивший этот отказ, может отреагировать на него, не выходя из протокола. Полностью закреплённая отрисовка ничего об этом не сообщает. О том, что загружает и записывает закрепление, см. aggrega pull, а также aggrega build, где о незакреплённой ссылке сообщается и она так же останавливает выполнение.

Запись артефактов туда, куда их записывает aggrega build

Передайте write, и завершённый рендеринг также будет записан в dist/ в корне рабочего пространства — туда же, куда его записывает aggrega build. Это тот же каталог, который командная строка формирует под тем же корнем рабочего пространства, и запись выполняется так же, поэтому для одной сущности Release в одном рабочем пространстве aggrega build, вызов aggrega/build языкового сервера без outputParent и этот вызов записывают одно и то же дерево, байт в байт, и одинаково называют этот каталог — в завершающей строке команды, в outputDirectory языкового сервера и в output_dir этого ответа. Если dist — ссылка, ведущая за пределы рабочего пространства, вызов отклоняется до того, как в нём что-либо будет удалено или записано, так же как в терминале. Если параметр опущен (по умолчанию), артефакты возвращаются в памяти и ничего не записывается.

Корень рабочего пространства определяется самим вызовом. При работе через стандартный ввод и вывод это корень рабочего пространства, которое определил вызов, как описано в разделе В каком рабочем пространстве обрабатывается вызов: корень, указанный в workspace_root, иначе корень, с которым был запущен сервер, иначе рабочее пространство, найденное от каталога, в котором был запущен сервер, — а если сущность Release, указанная абсолютным путём, переносит вызов в собственное рабочее пространство этой сущности Release, то корень этого рабочего пространства. Это тот же корень, под которым пишет aggrega build для той же сущности Release и того же указанного корня, поэтому каталог, в котором запущен сервер, получает dist только тогда, когда он и есть корень, определённый вызовом, — так же, как в терминале, открытом в нём. При работе через HTTP это рабочее пространство, которое обслуживает сервер, и за его пределами ничего не записывается.

Запись затрагивает рабочее пространство, поэтому через HTTP для неё нужна область aggrega:workspace-write. Вызов с write затрагивает рабочее пространство так же, как сборка, которая сначала разрешает свои зависимости: на учётные данные только с aggrega:read возвращается 403 с указанием aggrega:workspace-write, и ничего не записывается, а сервер, у которого mcp.deny_reach содержит workspace, отклоняет вызов с указанием этого параметра. Инструмент остаётся в списке инструментов любого вызывающего, а сборка без write остаётся доступной вызывающему с правами только на чтение.

Запись выполняется последней. Если передан также auto_pull, вызов разрешает зависимости, выполняет рендеринг и затем записывает — именно в таком порядке. Вызов, отклонённый на любом более раннем этапе — из-за сущности Release, рабочего пространства, каталога каталогов, разрешения или рендеринга, — не записывает ни одного артефакта.

Ответ указывает, что было записано. output_dir — это каталог (полностью при работе через стандартный ввод и вывод, dist через HTTP), а files перечисляет каждый записанный файл относительно него: с содержимым при response_format: detailed и только с путём при concise; текст сообщает, сколько файлов записано и куда. Вызов без write не содержит output_dir, поэтому по его отсутствию можно понять, что ничего не записано. Запись, которая не удалась уже после завершения рендеринга — например, в корень рабочего пространства, куда никому нельзя писать, — возвращается как ошибка с указанием каталога и причины и не перечисляет ни одного файла как записанного: часть записи может оказаться на диске, а называть отрендеренные файлы записанными значило бы утверждать больше, чем произошло.

Ни один аргумент не задаёт каталог и ни один не запрашивает трассировку. Куда попадают артефакты, определяет рабочее пространство, которое разрешил вызов, а не сам вызов, и сборка, записанная отсюда, не оставляет рядом со своим выводом каталог .trace; сборка с трассировкой — это aggrega build --trace.

Что сборка сообщает помимо своих файлов

Сборка несёт каждое поднятое ею предупреждение прямо в ответе. Это те находки, которые aggrega build печатает по ходу работы: имя, отличающееся одной правкой от объявленного; параметр, который никто не читает; целевая платформа, не способная учесть заданное автором поле; неостанавливающий вердикт управления; граничный каталог, унаследованный сущностью Release от расширяемой ею сущности Release и разрешающийся в тот же путь; свойство, которое достижимая из сущности Release сущность Component или Feature объявляет одновременно в своих разделах values и infra. Ни одна из них не меняет исход: сборка с предупреждениями всё равно завершилась успешно, а возвращаемые ею файлы — это файлы, которые она создала. Они приходят в том порядке, в каком их печатает терминал, поэтому читатель, сравнивающий их, видит одну последовательность, а не две: сначала всё, что подняла отрисовка, в порядке появления; затем находки о сущности Release и о том, что из неё достижимо, — aggrega build печатает их после завершения отрисовки; и последним, для сборки, которой передан write, — предупреждение, называющее каждый файл, который запись нашла рядом со своими и который она не записывала, оставляя его на месте, — то самое, которое aggrega build печатает после записи своих файлов (Файлы, которые сборка не записывала).

Они находятся в ответе, а не только в итоговом тексте, потому что ассистент, работающий с этим интерфейсом, не читает терминал, а находка, о которой никому не сообщили, — это находка, которой не было. Каждая содержит severity — warn для того, что требует внимания, info для зафиксированного наблюдения — и message; code, если её класс его назначает, чтобы можно было реагировать на конкретное условие без сопоставления текста; и key_path, называющий ключ в авторском документе, к которому относится находка, если она относится к нему. Находка о форме развёрнутой топологии не называет ключа, поскольку её координаты принадлежат развёртыванию, а не документу, и вместо этого сообщает в своём сообщении, к чему она относится.

Два вида находок, которые печатает терминал, попадают в этот ответ не в advisories, потому что у каждого есть место, сообщающее больше. Зафиксированная пометка об устаревании находится в deprecations независимо от того, записал ли её lock-файл для закреплённой ссылки или запись доверия плагинов рядом с ним — для плагина, подключённого в роли, которая возвращает вердикт «принять или отклонить». describe для сущности Release называет тот же набор в собственном deprecations, а validate для сущности Release — среди своих notices, и каждый оставляет вердикт без изменений; запись доверия, которая существует, но не может быть прочитана, приводит к отказу в любом из этих вызовов, а не принимается за запись, в которой ничего не записано. Родитель, от которого наследует сущность и который не удалось разрешить, останавливает сборку, поэтому он назван в тексте отказа, а не указан как находка, ничего не изменившая. Ещё один вид ограничен тем, что загружает этот инструмент, а не тем, что несёт его ответ: aggrega build загружает каждый настроенный каталог до разрешения сущности Release, и уведомление об устаревшей форме каталога исходило бы из этой загрузки, тогда как этот инструмент читает только то, что достижимо из сущности Release, и такой загрузки не выполняет, поэтому подобного уведомления не сообщает. В настоящее время ни одна сборка его не поднимает, так что оба сообщают одни и те же находки.

Если сущность Release ничего не поднимает, она ничего и не сообщает: ключ отсутствует, а не присутствует пустым, поэтому само его наличие говорит о том, что есть что читать.

Что возвращает отклонённая сборка

Отклонённая сборка отвечает в тех же полях, что и успешная, заполненных настолько, насколько продвинулся запуск. Она возвращается с пометкой о сбое и с исправлением в качестве текста, а структурированные данные располагаются рядом с этим текстом, а не заменяются им. Отказ, возникший при рендеринге сущности Release, излагается словами компилятора, как описано ниже в разделе A refusal raised while rendering, и добавляет одно собственное поле. Рекомендации в нём присутствуют: выполненные фазы выдали то, что выдали, и именно на эти находки нужно отреагировать, чтобы пройти отказ, поэтому они приходят как записи, которые можно сопоставлять, а не как текст, который пришлось бы разбирать. deprecations и declined_external_inputs присутствуют в нём по той же причине: записанная отметка сообщается, потому что отметка была записана, а отклонённая ссылка — потому что ссылка была отклонена, и ни один из этих фактов не зависит от того, чем закончился запуск.

files при отказе ничего не сообщает, и результат следует читать не из этого поля. Ничего не было выпущено, поэтому называть нечего. Не ветвитесь по наличию ключа: он сообщается в любом случае, и пустой files сам по себе не позволяет отличить отклонённую сборку от сборки, которая выполнилась и ничего не выпустила. Читайте флаг сбоя в результате — это собственный дискриминатор протокола, — а files читайте как то, чем он является: список того, что было отрендерено, а также записано, если вызову был передан write.

Рекомендации при отказе ограничены тем, насколько продвинулся запуск, а не тем, что может вместить ответ. Отказ от проверки, выполняемой до разрешения сущности Release, — закреплённая запись в кэше больше не соответствует записанному для неё дайджесту и ни один каталог не содержит закреплённых байтов, или зависимости Release не удалось разрешить, — не сообщает никаких рекомендаций, потому что ещё ничего не было выдано. Находки о том, как Release компонуется с расширяемой сущностью Release, выдаются в момент её разрешения, до всех последующих проверок, поэтому их несёт каждый более поздний отказ: Manifest сопоставляет тип с рецептом, который его не реализует; сущность, достижимая из Release, не соответствует своей схеме; lock-файл больше не соответствует тому, во что разрешается Release. Собственные находки рендеринга выдаются по ходу рендеринга, поэтому отказ от одной из этих более ранних проверок не несёт ни одной из них, а отказ при рендеринге несёт всё, что было выдано до него. Поэтому читайте advisories при отказе так же, как при успехе: то, что обнаружил этот запуск, в том порядке, в каком это выводит терминал.

Отказ из-за того, что сущность наследуется от родителя, которого не удалось разрешить, называет в своём тексте каждое такое наследование теми словами, которыми его выводит aggrega build, чтобы вы знали, что исправить. Эта деталь — причина остановки сборки, поэтому она находится в тексте, а не среди находок, которые ничего не изменили; находки о композиции, выданные до неё, находятся в advisories, как и для любого более позднего отказа.

Каталог, который читает Release и который невозможно обойти, отклоняется до какой-либо записи, так же как его отклоняет aggrega build. Это каталог, указанный вызовом в catalog_dirs, который не существует, — так же как aggrega build отклоняет несуществующий каталог --catalog, — или существующий, но нечитаемый. aggrega build загружает каждый каталог, который читает Release, до разрешения Release и останавливается на каталоге, который не может обойти; build сначала обходит те же каталоги, не читая в них ни одного документа, до любого разрешения зависимостей и до рендеринга, — поэтому сборка, которой передан auto_pull, не записывает lock-файл, и ничего не рендерится. Текст называет каталог так, как его сообщает командная строка, в одной строке: каталог, catalog load и причина, которую назвала файловая система. Данные называют Release, с пустым files и без находок, потому что ничего не выполнялось. Каталог, перечисленный в конфигурации рабочего пространства, который не является каталогом, — например, там ничего не существует, — отклоняется до этого обхода, в той же форме, а текст содержит отказ, который выдаёт для него aggrega build, и называет запись, а также файл конфигурации и строку, где она указана (Откуда читаются локальные сущности). Каталог, содержащий ссылку, ведущую за пределы каталога, внутри которого должно оставаться чтение, отклоняется в тот же момент, без какой-либо записи, а текст называет ссылку и то, куда она ведёт, — aggrega build отклоняет его так же.

Рабочий пример, чтобы обе половины были конкретными. Release, объявляющая параметр, который не читает ни одна ссылка, и рендеринг которой затем не может завершиться, возвращается как сбой, текст которого несёт отказ рендеринга, а данные — рекомендацию о непрочитанном параметре с её severity, message, code и key_path — ту же запись с теми же значениями, которую та же Release сообщает в ответе, когда рендеринг завершается, — рядом с записью refusal о том, что остановило рендеринг. Release, которая расширяет другую и наследует каталог границы без переменной шаблона и чей Manifest сопоставляет тип с рецептом, который его не реализует, возвращается как этот отказ с одной записью advisories на каждый унаследованный каталог, каждая с code inherited-boundary-directory-is-literal. Release, зависимости которой не удаётся разрешить, в рабочем пространстве, где все перечисленные каталоги существуют, возвращается как сбой вообще без ключа advisories, потому что к моменту остановки ничего не было выдано.

Отказ, возникший при рендеринге

Сущность Release, от которой компилятор отказывается во время рендеринга — Workload, называющий слот, который его Component не объявляет, не выполненное утверждение, шаблон, который не удаётся вычислить, — возвращается с отказом в формулировке компилятора и со всеми причинами под ним, теми же словами, которые cli-build возвращает для той же сущности Release: сначала рендерируемый узел, затем то, что в нём отказало. Если отказ называет зарегистрированное условие, текст добавляет название этого условия — короткий код и описательный код, по которым можно сопоставлять, — как это сделал бы explain-error. Текст начинается с указания этапа, на котором произошёл отказ: The build failed during rendering; nothing was written to disk. для отказа, возникшего при рендеринге, и The build refused before rendering anything; nothing was written to disk. для отказа, возникшего в ходе работы компилятора до того, как что-либо было отрендерено, — когда отказывает композиция графа, с которым работает рендеринг, или утверждение, объявленное сущностью Component или Feature.

Полезная нагрузка несёт тот же отказ в виде одной записи, refusal, поэтому вызывающая сторона, которой нужно изменить документ, узнаёт, какой именно и где, не разбирая предложение:

  • file — документ, на который указывает отказ: Recipe сущности Workload, Recipe или FeatureRecipe, объявляющий невыполненное утверждение, сущность Release или Aggregate, записавшая запись, от которой отказывается композиция графа, либо Aggregate сущности Release для отказа, который не указывает ни на какой документ.
  • key_path — ключ в этом документе, если отказ его называет: .spec.workload для отказа, касающегося сущности Workload, собственный ключ утверждения в .spec.assertions для невыполненного утверждения, собственный ключ записи для отказа от записи. Отказ, касающийся сущности Workload, привязывается к её ключу workload и не точнее, поскольку Workload, который оценивает проверка, — это результат работы его шаблона, а шаблон пишет строки, которых его автор никогда не писал; пути, которые отказ называет внутри этого отрендеренного Workload, остаются в его message.
  • line и column — позиция этого ключа, отсчитываемая от единицы, столбец — в единицах UTF-16. Отсутствуют, если отказ не называет ключа или документ его не содержит: позиция указывается только там, где она была найдена.
  • severity — halt, серьёзность находки, остановившей сборку.
  • code и short_code — два идентификатора условия, если отказ называет зарегистрированное условие.
  • message — текст отказа, в точности такой же, как в тексте ответа.
  • findings — присутствует, только если отказ объединяет несколько находок, как это делает композиция графа со всеми найденными нарушениями: одна запись на находку, в том порядке, в котором их перечисляет отказ, каждая той же формы — со своими file, key_path, line, column, severity, code, short_code и message. Собственные поля отказа тогда указывают, куда указывает его первая находка, а его message содержит все находки, как и текст; командная строка выводит каждую находку как отдельную диагностику.

Запись присутствует всякий раз, когда отказала собственная работа компилятора — во время рендеринга или до него: при композиции графа или на утверждении, объявленном сущностью Component или Feature, которое не называет документа, поэтому его запись называет Aggregate. Успешная сборка её не содержит, как и сборка, отклонённая проверкой, выполняемой до запуска компилятора, — lockfile, сопоставления Manifest, зависимости сущности Release, — чей отказ представлен только текстом. Значение, которое автор объявил чувствительным, скрывается из отказа там, где его выдаёт компилятор, поэтому запись и текст содержат то же, что cli-build и терминал, — см. что отказ сообщает об объявленном значении.

Разрешение зависимостей сущности Release

pull разрешает каталожные зависимости и зависимости от исходников сущности Release в локальный кэш и записывает lock-файл этой сущности Release. Этот инструмент присутствует здесь по причине, которую стоит назвать: оба отказа, описанные выше, — рендеринг, отклонивший незакреплённую внешнюю ссылку, и сборка, остановленная из-за того, что lock-файл больше не соответствует тому, во что разрешается Release, — устраняются закреплением, а у ассистента, которому приходится просить вас выполнить команду, нет способа устранить их самостоятельно. О том, что он записывает и насколько далеко это распространяется, см. Что ассистент может делать, не спрашивая вас.

Передайте release — путь к Release, абсолютный или относительный корня рабочего пространства, по тому же контракту, что и у всех остальных аргументов-путей здесь. workspace_root и catalog_dirs переопределяют обнаружение рабочего пространства и каталогов точно так же, как в build. Оба действуют на сервере, доступном через стандартный ввод и вывод; по HTTPS эти два аргумента отклоняются, и путь должен разрешаться внутри рабочего пространства, которое обслуживает процесс, как описано в разделе Один процесс — одно рабочее пространство.

По умолчанию инструмент согласовывает, а не разрешает заново. Закрепление, уже записанное в lock-файле, соблюдается и загружается в этой версии, а если реестр больше не отдаёт эти байты, оно отклоняется, а не молча перезакрепляется. Ссылка без закрепления — только что добавленная или удалённая из lock-файла вручную — разрешается заново и добавляется. Ссылка, которой больше нет среди разрешённых зависимостей, удаляется. Поэтому при неизменном наборе зависимостей файл остаётся побайтово идентичным, включая записанную метку времени, и вызов, не изменивший ни одного закрепления, не даёт никакого diff тому, кто потом просматривает рабочее пространство.

verify сравнивает и оставляет lock-файл как есть. Он сверяет записанный lock-файл с разрешением, которое сейчас выполнил бы описанный выше согласующий вызов, соблюдая записанные закрепления точно так же, как этот вызов, и возвращает неудачу при расхождении или при отсутствии lock-файла для сравнения — так ассистент узнаёт, нужно ли закрепление, до того как что-либо перезапишет lock-файл. Ничего из того, что записал бы этот вызов, не записывается — ни lock-файл, ни записываемые рядом с ним идентичности плагинов, ни entity.lock, — тогда как кэш содержимого читается и заполняется точно так же, как этим вызовом. Он также сообщает инструментарий, записанный в lock-файле: версию компилятора, записавшего файл, и версию каждого основного плагина, поставлявшегося с этим компилятором. Это сообщается для аудита и никогда не сравнивается с запущенным бинарным файлом, потому что инструментарий не входит в то, что закрепляет lock-файл, и его проверка косвенно закрепила бы компилятор, — различие в инструментарии не является расхождением.

upgrade_targets заново разрешает названные вами ссылки и ничего больше. Передайте один или несколько URI сущностей в чистой авторской форме — core/database, а не версионированную форму. Каждое названное закрепление сбрасывается и заново разрешается до наивысшей доступной версии, а все остальные закрепления и записанные внешние входные данные остаются неизменными. URI, не совпадающий ни с записанным закреплением, ни с настроенным подключением, отклоняется, а не игнорируется.

Аргумента, заново разрешающего всё сразу, намеренно нет. В командной строке такая форма есть, и она отбрасывает весь lock-файл перед повторным разрешением по текущему состоянию реестра. Здесь такого аргумента не существует, поэтому такой вызов вообще невозможно составить, а не принять и затем отклонить: за потоком протокола никто не следит, так что полное отбрасывание некому подтвердить. Если оно вам нужно, команду выполняет cli-pull, и только через стандартный ввод и вывод — там, где присутствует человек; вызывающая сторона, обращающаяся к серверу по HTTP, выполняет её в терминале на хосте. verify нельзя сочетать с upgrade_targets — один оставляет lock-файл как есть, а другой перезаписывает его, — а также с pin_sources, какое бы значение он ни нёс: этот аргумент решает, записывает ли разрешение закрепления, которых не хватает в entity.lock, или отклоняется из-за них, а сравнение не записывает entity.lock, так что не делало бы ни того, ни другого. Вызов с любой из этих пар отклоняется до какого-либо разрешения, с фразой, называющей пару. Объявленная схема инструмента не указывает эти два исключения, потому что клиент, отображающий их, может прочитать это как требование отправлять verify; клиент узнаёт о них из отказа. Командная строка и демон отклоняют те же пары.

Результат называет, что именно было разрешено, а не просто сообщает, что что-то разрешилось. Он содержит lock-файл, который был записан или с которым шло сравнение; resolved — каждую ссылку, до которой дошло разрешение, с версией, в которую она разрешилась, видом, который пишет автор, где разрешение его записывает, и её source — откуда этот запуск взял ссылку, тем словом, которое aggrega pull --detail выводит для того же разрешения: fetched-fresh, cache-reuse, local, in-binary или external; количество исходных артефактов, внешних входных данных и доверенных идентичностей плагинов, содержащихся в lock-файле после запуска; и diagnostics — собственный отчёт разрешения о себе в порядке появления каждой строки: какое закрепление было переиспользовано, какая подпись проверена, какая версия пропущена как отозванная. При запуске команды эти строки попадают в терминал; здесь они находятся в ответе, потому что у вызывающей стороны, не читающей терминал, нет другого способа их получить. verified присутствует только при сравнении, поэтому по его отсутствию запуск с записью отличается от запуска, который только сравнивал. source описывает этот запуск на этой машине, поэтому lock-файл его не записывает, а describe, сообщающий, от чего зависит Release, его не называет.

Отказ отвечает в тех же полях, заполненных настолько, насколько продвинулся запуск. Когда разрешение вычислено, resolved передаётся при любом вердикте — прежде всего при вердикте о расхождении, поскольку именно по этому отказу вызывающей стороне нужно решить, что менять. Отказ до этого момента, например из-за пути к Release, который не разрешается, несёт исправление в тексте и не несёт разрешения, потому что передавать нечего.

Если закрепления полны, а внешние входные данные — нет, вызов всё равно завершается успешно и сообщает об этом. Выяснение того, какие внешние входные данные потребляет Release, — это рендеринг, а рендеринг может завершиться неудачей, когда закрепления зависимостей уже верны и записаны на диск. Сообщение о неудаче всего вызова побудило бы вас переделывать правильную работу, поэтому вместо этого в успешном результате устанавливается incomplete_external_inputs с указанием того, что остановило процесс: закрепления зависимостей полны, а закрепления внешних входных данных могут быть неполными.

Это самый медленный инструмент здесь, и согласующий холостой вызов — не быстрый путь. Разрешение полностью платит свою цену, чтобы установить, что набор зависимостей не изменился, поэтому вызов, ничего не перезаписывающий, стоит столько же, сколько первое разрешение, — для небольшого Release это секунды, а не миллисекунды, и время растёт с размером набора зависимостей. verify — более дешёвая из двух форм, потому что сравнение пропускает спуск по исходникам каждого компонента, выполняемый записывающим запуском. Если ваш клиент задаёт таймаут на вызов, сверяйте его именно с этим инструментом. Запрос сообщений о ходе выполнения, описанный ниже, означает, что что-то приходит во время выполнения вызова, а не ничего до его окончания, — это решает проблему таймаута простоя в вашем клиенте или в том, что стоит между вами и сервером, доступным по HTTP, но не ограничения на общую длительность одного вызова.

Сущность, чей entity.lock не фиксирует пин для читаемого ею входа, отклоняет pull, и отказ называет шаг, который его фиксирует. Ожидается, что сущность Recipe или FeatureRecipe, которую Release собирает из ваших каталогов, и которая читает удалённый источник, записанный полностью, или импортирует файл через свои артефакты, уже несёт эти пины рядом с собой — их автор фиксирует их с помощью pin, см. ниже. pin_sources просит этот вызов выполнить этот шаг от имени автора для каждой такой сущности вместо отказа, записывая entity.lock рядом с каждой; это тот же шаг, что выполняет инструмент pin, и он записывает те же байты. Если аргумент не передан, решает настройка рабочего пространства pin_sources_at_pull; если передан, он решает в любую сторону, так что pin_sources: false приводит к отказу даже в рабочем пространстве, настроенном на закрепление. Сущность, которую разрешение нашло в кэше, а не в одном из ваших каталогов, не имеет здесь места для записи и этим вызовом никогда не закрепляется.

Закрепление собственных входов сущности

pin записывает в entity.lock рядом с сущностью Recipe или FeatureRecipe пин содержимого для каждого входа, который сущность читает вне собственного документа: удалённого источника, чьи координаты записаны полностью, и файла, который импортирует запись artifacts. Это тот же шаг, что aggrega pin выполняет в терминале, и записываемый им lock побайтно идентичен тому, что записывает эта команда. Передайте entity — документ сущности, абсолютный или относительный к корню рабочего пространства путь по тому же контракту, что и у всех остальных аргументов-путей здесь; через HTTPS он должен разрешаться внутри рабочего пространства, которое обслуживает процесс.

Release не указывается, потому что он не нужен. Источник, чьи координаты не содержат шаблона, называет один артефакт для каждой сущности Release, использующей сущность, поэтому шаг разрешает и закрепляет его без чего-либо, что предоставляет Release. Источник, чьи координаты берутся из шаблона, здесь не закрепляется: какой артефакт он называет, решает каждый Release, и pull закрепляет каждую идентичность, в которую он разрешается, в lock-файле этого Release.

Результат сообщает, что шаг сделал с lock. Он содержит entity, её kind и name, а также pinnable, равный false для вида, который не читает ничего, что фиксирует lock, — Component или Feature; в этом случае рядом с сущностью ничего не затронуто, а остальные поля отсутствуют. В остальных случаях он содержит записанный lock, changed — false, если lock уже фиксировал каждый пин и остался побайтно идентичным, removed — если сущность теперь не читает ничего, что фиксирует lock, и её lock удалён, и pins — по одной записи на класс пинов с числом, которое lock содержит после вызова. dry_run возвращает lock, который записал бы шаг, как content и ничего не записывает рядом с сущностью; кэш содержимого всё равно заполняется, потому что входы разрешаются точно так же, как и в обычном случае.

Он пишет внутри рабочего пространства и обращается к хостам, которые называют источники сущности — репозиторию чартов, Git-хосту, URL, — поэтому через HTTP он допускается для учётных данных с областью, допускающей pull, и отклоняется для тех, что могут только читать. Через стандартный ввод и вывод та же возможность доступна также как cli-pin, который запускает команду; через HTTP этого инструмента нет.

Получение сведений о ходе долгого вызова

Вызов сообщает о своём ходе, если вы об этом попросите, и для этого нужно одно поле. Поместите progressToken в _meta вызова — строку или число по вашему выбору. Он возвращается в каждом отчёте точно в том виде, в каком вы его написали, и это единственное в отчёте, что указывает на ваш вызов: отчёт ни на что не отвечает, поэтому не несёт id. Если токен не передан или передан как null, ничего не меняется — на вызов отвечают так же, как без него. Токен любой другой формы отклоняется до того, как вызов что-либо сделает, с указанием двух допустимых форм, а не пропускается: вызывающая сторона, которая попросила сообщать и затем встретила молчание, не может ничего предпринять.

Приходит notifications/progress с вашим токеном и счётчиком, который растёт с каждым отчётом. Нет ни общего количества, ни сообщения, и ни то ни другое не упущение, ожидающее доработки: работа сообщает о том, что вошла в очередную фазу, поэтому общее количество можно было бы только выдумать, а фразу — только сочинить здесь, а не передать дальше. Рисуйте неопределённый индикатор по растущему счётчику; доли для заполнения полосы нет.

Через HTTP ответ становится потоком событий, и только после того, как что-то действительно сообщило о ходе. Он отдаётся как text/event-stream, помеченный как не подлежащий кэшированию, и с X-Accel-Buffering: no для посредника, который иначе удерживал бы каждое событие до окончания работы и превратил бы поток в медленный единый ответ. Каждый отчёт — одно событие, а собственный ответ вызова — последнее событие перед закрытием потока. Пока работа молчит, поток с интервалами передаёт строку комментария, которая доходит до всего, что стоит посередине, как байты в живом соединении, а до вашего клиента не доходит вовсе. На вызов, который запросил ход выполнения и попал на работу, не сообщающую о нём, всё равно отвечают одним объектом JSON, потому что поток открывает первый отчёт, а не токен.

В потоке определяйте результат по последнему событию, а не по коду состояния. Состояние и заголовки записываются при открытии потока, то есть до завершения работы, поэтому вызов, который сообщает о ходе, а затем отказывает, передаёт отказ последним событием под уже отправленным состоянием. Закрытие соединения посреди потока завершает работу, и для неё больше ничего не записывается, точно так, как How a call ends описывает для любого другого вызова.

Через стандартный ввод и вывод отчёты — это строки перед строкой ответа, оформленные так же, как любое другое сообщение в этом потоке, — один объект JSON на строку в порядке записи, — и строка ответа следует за ними. После завершения вызова ни на одном транспорте ничего не сообщается.

Здесь о ходе сообщает разрешение зависимостей сущности Release. pull сообщает каждый раз, когда разрешение входит в фазу. build сообщает, только когда сначала выполняет разрешение — потому что вы передали auto_pull или потому что собственная настройка рабочего пространства требует разрешения при каждой сборке в нём, — поскольку отчёты относятся к этому шагу: сборка, выполняющая рендеринг по уже имеющимся пинам, ни до чего не доходит и ни о чём не сообщает, так что токен в этом вызове ничего не меняет в том, как на него отвечают. Любой вызов также сообщает о каждом шаге, в который входит его работа и которого она ждёт, — чтении реестра, получении артефакта или пакета документации, первой компиляции плагина, — то есть о шагах, которые командная строка показывает человеку рядом со своим индикатором ожидания. Вызов, работа которого не ждёт ни одного из них, ни о чём не сообщает, что безвредно, а не является ошибкой: ответ тот же, что вы получили бы без него.

Как узнать, какое соединение записано в данном месте документа

connection-at-position отвечает на вопрос, предшествующий половине двух описанных выше инструментов, касающейся соединений, — для случая, когда у вас есть место в документе, а не узел графа: строка, которую вы видите в сущности Aggregate или Release. Передайте file — документ, относительный к корню рабочего пространства или абсолютный, который читается с диска так же, как его читает insertion-point; position — line и character, оба отсчитываются от нуля и измеряются в единицах, которые задаёт position_encoding, точно так же, как этот аргумент читает insertion-point; и release, скомпилированный граф которого записывает соединения. Сущность Release обязательна и для места в Aggregate: узел графа и соединение существуют только на скомпилированном графе.

Ответ — одна из двух половин. Если место находится на записи соединения, ответ содержит graphNode и connection — его socket, его alias и document, в котором было прочитано место, — то есть ровно то, что attach-candidates принимает наряду с graph_node и release, и то, что attachment-container принимает, чтобы указать, куда помещается вложение на этом соединении; этот контейнер находится внутри той самой записи, в которую попало место. В противном случае ответ содержит noConnectionReason из закрытого набора: no-connection-entry (место не находится ни на одной записи, в которой пишется вложение), feature-created-connection (место находится на записи сущности Release для соединения, проведённого сущностью Feature) или unknown-connection (место находится на записи, которую Release пишет для соединения, отсутствующего на скомпилированном графе). Читаемый ответ излагает причину словами.

Место в любой точке записи находится внутри неё — на псевдониме, на его target, внутри его features, — а при вложенных записях побеждает самая внутренняя. Место на собственном ключе сокета, выше псевдонимов под ним, не находится ни в одной из них. Записи — это те, что записывает скомпилированный граф: в Aggregate — каждое соединение, которое проводит компонент, в его записи под псевдонимом соединения в документе, где компонент был написан, а для компонента, который вносит импортированный модуль, это собственный документ этого модуля; в Release — каждая запись на ребро, которую он пишет. Соединение, записанное как список целей, и соединение, которое проводит собственный блок зависимостей сущности Feature, не имеют записи, в которой пишется вложение. Является ли ключ соединением, никогда не определяется по его имени.

Он отвечает и останавливается. Он ничего не записывает ни в один файл. Документ, который не находится в рабочем пространстве, не может быть прочитан или не является корректным YAML, возвращается как неудачный результат с указанием того, что нужно изменить, — так же, как от insertion-point; так же возвращаются место без line или character и position_encoding вне трёх допустимых значений.

Как узнать, в каком контейнере должно находиться присоединение

attachment-container отвечает на вопрос, стоящий между ответом о кандидатах и точкой вставки. Вы уже решили, что присоединить к узлу; прежде чем спрашивать, в какое место файла это записать, нужно знать, в какой файл и в какой контейнер внутри него. Передайте graph_node — идентификатор узла на скомпилированном графе в том виде, в каком его задаёт граф, — и release, которому принадлежит этот граф. Оба аргумента обязательны: идентификатор узла — это ключ графа одной сущности Release, и без неё он ничего не означает.

Не собирайте этот путь сами. Идентификатор узла и путь объемлющей его подсистемы записываются с точками между частями, а точка — допустимый символ в имени, которое вводит автор, поэтому извне документа невозможно отличить структурную точку от точки внутри имени. Составленный вами путь будет выглядеть правильно, но адресовать ключ, который никто не писал, и последующая правка создаст этот ключ, а не будет отклонена. Хуже того, идентификатор узла вообще не несёт следа объемлющей подсистемы: компонент, созданный внутри subsystems.billing.subsystems.payments, имеет ключ ledger — точно так же, как компонент верхнего уровня. Запрашивайте контейнер.

Ответ содержит node — узел, о котором идёт речь; file — документ, в котором этот узел был создан; и container — структурный путь от корня этого документа в виде списка сегментов: ["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. Это список, а не объединённая строка, намеренно: объединённый путь пришлось бы снова разбивать получателю, что вернуло бы описанную выше неоднозначность одним вызовом позже. Передавайте file и container в insertion-point без изменений.

file входит в ответ, а не является тем, что вы уже знаете. Узел, добавленный импортированным модулем, был создан в собственном документе этого модуля под именем, которое дал ему модуль, поэтому и файл, и последний сегмент контейнера отличаются от всего, что вы передали.

Для присоединения к одному из соединений, которые проводит узел, добавьте connection с его socket, alias и document; последний здесь обязателен, поскольку соединение может содержаться в любом из двух документов. С aggregate ответом будет собственная запись соединения в документе, в котором был создан узел, с блоком features в конце; соединение, проведённое сущностью Release, не имеет там записи и отклоняется. С release это запись для отдельного ребра в записи сущности Release для узла — ["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"], — которая сообщается независимо от того, записывает ли уже Release эту запись для ребра, так что insertion-point называет ключи, которые ещё нужно записать; если Release не записывает запись для узла, запрос отклоняется, поскольку решать, где размещён узел, не дело этого инструмента. Соединение, проведённое сущностью Feature, отклоняется в любом документе.

Он отвечает и останавливается. Он не создаёт присоединений, ничего не записывает в файлы и не составляет текст. Он также не решает, что может быть присоединено, — это делает attach-candidates. Узел, которого нет на графе, или узел, для которого граф не записывает документ, возвращается как неуспешный результат с указанием, что изменить, а не как ответ с пустым полем.

Поиск места для записи в документе

insertion-point отвечает на вопрос, который следует за ответом о кандидатах. Вы уже решили, что присоединить или подключить; теперь нужно знать, где в файле это записать. Инструмент возвращает позицию и столбцы для отступа, чтобы вы могли применить правку, не разбирая документ самостоятельно. Поскольку он читает собственную структуру документа, а не форму какого-либо одного вида, describe-capabilities индексирует его под любым видом сущности, которым вы сужаете список.

Передайте file — документ, относительный от корня рабочего пространства или абсолютный, и находящийся внутри рабочего пространства: документ, достигнутый через ссылку, ведущую наружу, — на сам файл или на каталог по пути к нему, — внутри не находится и отклоняется на любом транспорте, — и container, структурный путь от корня документа до контейнера, в который помещается запись; каждый элемент — ключ отображения или позиция в последовательности, записанная в десятичном виде.

Путь к контейнеру указываете вы. Инструмент читает структуру документа и никогда не определяет, куда что-то относится, по тому, как оно называется, какой тип несёт или что, по-видимому, означает. Вы говорите, какой ключ; он говорит, куда идут записи этого ключа в этом документе — какие сегменты пути файл уже содержит, в каких столбцах стоят его записи и до какой последней строки доходит самый внутренний блок. Для присоединения сущности Feature к узлу скомпилированного графа знать этот ключ самому не нужно: attachment-container выше сообщает документ и контейнер, и оба передаются сюда без изменений.

Ответ содержит позицию нулевой ширины position, у которой и line, и character отсчитываются от нуля; entryIndent и indentStep — столбцы, с которых следует писать; и missingContainerKeys — ключи контейнера, которых в документе ещё нет, начиная с внешнего; их вы записываете перед записью. entryShape сообщает, содержит ли контейнер mapping или sequence, и сообщает unknown, если контейнера ещё нет или он пуст, потому что документ об этом ничего не сказал, — тогда форму выбираете вы. indentStepMeasured указывает, измерен ли шаг по собственной вложенности документа или это значение по умолчанию для документа, в котором вложенности нет. Если установлен precededByLineBreak, начните текст с переноса строки: позиция стоит в конце строки, за которой следует запись; она допустима независимо от того, заканчивается ли файл переводом строки, и не затрагивает ни одного уже записанного байта. Читайте missingContainerKeys, даже если ожидаете, что контейнер существует: позиция, применённая без ключей, которые должны ей предшествовать, даёт документ, который больше не разбирается.

position_encoding задаёт единицы, в которых измеряется сообщаемое смещение символа: utf-8, utf-16 или utf-32. Здесь это аргумент, потому что ни одна из ревизий этого протокола его не согласовывает; по умолчанию используется utf-16 — то, что принимает сеанс редактора, когда клиент ничего не согласовал, — поэтому вызывающий, который ничего не указал, получает одинаковый ответ на обеих поверхностях. Значение, не совпадающее ни с одним из трёх, отклоняется, а не молча заменяется значением по умолчанию, потому что смещения, измеренные одним способом и применённые к буферу, измеренному другим, портят документ на первом же символе вне ASCII.

Он отвечает и останавливается. Он ничего не пишет ни в один файл, не составляет текст записи и не применяет правку; составить текст и решить, применять ли его, — ваша задача. Запрос, который не указывает на место, куда может пойти запись, возвращается как неудачный результат с указанием, что изменить: документ не в рабочем пространстве, не читается или не является корректным YAML; путь к контейнеру без сегментов или с пустым сегментом; путь, проходящий через скаляр, внутрь которого ничего нельзя добавить; путь к коллекции в потоковом стиле, где добавление переписало бы байты, уже записанные автором, а не добавило бы строку; или путь, обращающийся к блочной последовательности чем-то, что не является одним из её индексов. Если вы предпочитаете, чтобы правку применили за вас, это делает инструмент Применение одной ограниченной правки к документу.

Применение одной ограниченной правки к документу

edit-document применяет то, что находят два описанных выше инструмента. Один вызов добавляет одну запись в один контейнер или задаёт одно скалярное значение и ничего другого делать не может. Он записывает указанный вами документ внутри рабочего пространства, поэтому через HTTPS ему нужна aggrega:workspace-write: вызывающая сторона, у которой есть только aggrega:read, видит его в списке инструментов, но её вызов отклоняется с указанием этой области доступа.

Укажите правку в edit; набор правок закрыт. add-component добавляет экземпляр компонента в контейнер компонентов; attach-feature присоединяет Feature к указанному узлу; wire-edge прокладывает соединение внутри одного из сокетов этого узла; set-value задаёт одно значение на этом узле. Имя вне этих четырёх отклоняется, а не интерпретируется. Нет правки, которая удаляет, заменяет уже написанный вами блок, что-либо переупорядочивает или записывает переданные вами байты дословно, поэтому это не средство записи файлов и использовать его так нельзя.

Передайте file — документ, относительно корня рабочего пространства или абсолютным путём, и внутри рабочего пространства: документ вне его, указанный напрямую или через ссылку, ведущую наружу, отклоняется на любом транспорте, и ничего не читается и не записывается; node — структурный путь от корня документа в виде списка сегментов; name — ключ, под которым записывается запись; и value — то, что содержит эта запись. node — список по той же причине, по которой attachment-container отвечает списком: точка допустима внутри имени, которое вводит автор, поэтому склеенный путь мог бы адресовать ключ, которого никто не писал, и запись была бы создана там, а не отклонена. Для add-component путь указывает сам контейнер компонентов, поскольку добавляемая запись и есть узел; для остальных трёх он указывает узел, к которому относится правка, а контейнер следует из правки. socket читается для wire-edge и в остальных случаях игнорируется. Смысл value следует из edit — сущность, которую запрашивает запись, узел, на который указывает соединение, или скалярное значение, которое задаётся, — и это JSON-значение собственного типа, поэтому число остаётся числом, цифра в кавычках остаётся текстом, а если его опустить, ничего не задаётся. Отображение или последовательность отклоняются, поскольку запись блока не входит в число этих правок.

Каждый байт, которого правка не касается, сохраняется. Документ разбирается только для того, чтобы найти контейнер и строку, на которой заканчивается его блок, поэтому комментарии, пустые строки, стиль кавычек, свёрнутые и литеральные скаляры и наличие завершающего перевода строки переносятся без изменений, а шаг вложенности измеряется по собственным отступам документа, а не навязывается. Один и тот же запрос к одному и тому же документу даёт одни и те же байты.

Результат должен быть документом, который вы могли бы набрать сами, и именно от этого зависит запись. Составленный документ проверяется по схеме его собственного вида и попадает на диск, только если проверка проходит. Запрос, который привёл бы к тому, что схема отвергает, отклоняется с указанием свойства, которое схема не допустила бы, и места, и файл остаётся побайтово таким, каким был, поэтому отклонённую правку невозможно отличить от никогда не предпринимавшейся, и можно повторить исправленный запрос к исходному документу. Запись, которая уже есть и содержит запрошенное, — пустая операция; запись с этим именем, содержащая что-то другое, отклоняется, а не заменяется.

Ответ содержит container — структурный путь, в который попала запись; created_containers — уровни контейнеров, которые этой правке пришлось создать, начиная с внешнего, пустой в обычном случае, когда весь путь уже существовал; и written — документ, попавший на диск, пустой, если ничего не попало. Читайте created_containers: иначе правку, которая незаметно записала два вложенных блока, отсутствовавших в документе, невозможно отличить от правки, добавившей одну запись в блок, написанный вами самими.

dry_run делает всё, кроме записи. Отредактированный документ возвращается как content, ничего не создаётся, и written пуст — это для клиента, который показывает результат автору до сохранения. Всё остальное поведение такое же, как у записи, включая проверку по схеме, поэтому запрос, который запись отклонила бы, отклоняется и в этом режиме. Без него документ записывается, а content отсутствует, поскольку документ тогда уже на диске и его называет written.

Допустимо ли семантически то, что вы соединяете, — объявляет ли производитель этот сокет, выполнены ли условия применимости Feature, — здесь не решается. На это отвечает validate.

Через стандартный ввод и вывод та же возможность доступна также как cli-edit-document, который запускает команду и возвращает выведенный ею текст; через HTTP этого инструмента нет, и там возможность доступна через данный инструмент.

Преобразование стороннего описания в черновые сущности

import преобразует описание, созданное другим инструментом, — например, поток, экспортированный из конструктора агентов, — в черновые файлы авторинга Aggrega. Он записывает эти файлы в рабочее пространство, которое обслуживает этот сервер, поэтому через HTTPS ему нужна область aggrega:workspace-write: вызывающая сторона, у которой есть только aggrega:read, видит его в списке инструментов, но её вызов отклоняется с указанием этой области.

Передайте source — файл или каталог для преобразования. Путь абсолютный или относительный корня рабочего пространства — тот же контракт, что и у всех остальных аргументов-путей на этой поверхности, — а на сервере, к которому обращаются через HTTPS, он разрешается внутри рабочего пространства, которое обслуживает этот сервер.

Из каталога читаются ровно те файлы, которые выбирают шаблоны файлов его импортёра. Чарт или проект — это каталог, и source может указывать на него. Тогда импортёр получает файлы этого каталога на любой глубине, которые выбирает один из шаблонов файлов, объявленных в его сигнатурах, — каждый под своим путём внутри каталога, записанным через прямые косые черты, в отсортированном порядке, — вместе с файлами, которые его подключение plugins.importer указывает в with.sources, под их базовыми именами; файл каталога и файл из with.sources с одинаковым именем отклоняются, а не скрывают один другой. Импортёр, не объявляющий шаблонов файлов, читает один файл и отклоняет каталог с условием An importer that declares no file patterns is handed a directory (Импортёру, не объявляющему шаблонов файлов, передан каталог); каталог, в котором нет ни одного файла, выбираемого его шаблонами, тоже отклоняется. Каталог ограничен самим собой, где бы он ни находился: ссылка среди файлов, которые прочитал бы импорт, или ссылка на каталог, ведущая за его пределы, отклоняется до какого-либо чтения, а в ссылку на каталог вход никогда не выполняется — как описано в разделе Импортируемый каталог. На сервере, к которому обращаются через HTTPS, сам каталог разрешается внутри рабочего пространства, а значит, и каждый прочитанный из него файл.

Импортёр — это импортёр из каталога вашего рабочего пространства или один из базовых импортёров компилятора. Преобразование выполняет плагин-импортёр, объявляющий формат источника: из каталога вашего рабочего пространства или один из базовых импортёров компилятора, которые обслуживают свои форматы в любом рабочем пространстве без записи в каталоге. Этот инструмент выбирает его, запускает и записывает созданное им. Подключение plugins.importer, чей uri указывает импортёр по идентичности и версии — importer/<name>:<version>, как записывает его aggrega plugin add importer, — подключает этот импортёр: если он объявляет формат источника, запускается именно он, в этой версии, какой бы другой импортёр ни объявлял тот же формат, и ему передаются источники и настройки with этого подключения, которые не получает ни один другой импортёр. Если формат объявляют несколько импортёров и ни один из них не подключён отдельно — например, базовый импортёр и импортёр с другим именем из вашего каталога для того же формата, — вызов отклоняется с их перечислением, как описано в разделе Конфигурация. Указанный вами формат, который не объявляет ни один импортёр, отклоняется с указанием возможности, которую импортёр должен был бы объявить, — import:langflow для источника Langflow, — то есть того, что объявляет импортёр, добавляемый вами в каталог, а не с общим сообщением о промахе, которое пришлось бы истолковывать.

Базовый импортёр, которого нет на машине сервера, загружается один раз — первым импортом, которому он нужен. Импорт загружает его из реестра по умолчанию обслуживаемого рабочего пространства, сверяет его с модулем, который публикует выпуск компилятора, проверяет его подпись по политике доверия этого реестра и используемые им функции хоста — так же, как pull проверяет загружаемый плагин, — и сохраняет его в кэше содержимого рабочего пространства, так что каждый последующий импорт читает его оттуда и не обращается ни к какому реестру. Больше для него ничего не записывается — ни lock-файл, ни запись о доверенных плагинах. По HTTPS это единственный реестр, к которому вызов этого инструмента может заставить сервер обратиться, в пределах, которые Which credentials a call spends устанавливает для чтения из реестра: это реестр по умолчанию рабочего пространства, которое обслуживает этот сервер, а значит, реестр, с которым это рабочее пространство настроено; ничто в вызове не называет реестр и не несёт учётных данных; а загрузка использует собственный вход и политику доверия этого хоста. Инструмент по-прежнему обращается только к рабочему пространству и никуда дальше, поэтому вызову достаточно aggrega:workspace-write: после загрузки остаётся лишь модуль в собственном кэше содержимого рабочего пространства. Модуль, не прошедший проверку, отклоняется так же, как в терминале, и ничего не сохраняется. Если модуль невозможно загрузить — рабочее пространство работает офлайн, его реестр недоступен или в реестре его нет, — вызов отклоняется с условием A plugin’s .wasm is not on this machine (файла .wasm плагина нет на этой машине), где называются импортёр, его версия и то, что помещает его модуль на машину.

Если рабочее пространство не указывает ни одной папки каталога, импорт читает каталог, который публикует его реестр по умолчанию. Рабочее пространство, в котором workspace.catalog_dirs, AGGREGA_CATALOG_DIRS и корень не указывают ни одной папки каталога, читает каталог стандартной библиотеки как один подписанный снимок по адресу catalog/snapshot в реестре по умолчанию обслуживаемого рабочего пространства — том же реестре, из которого получается базовый импортёр, на тех же условиях, причём ничто в вызове не называет реестр и не передаёт учётные данные. Снимок получается один раз: его подпись проверяется согласно политике доверия этого реестра, а сам снимок сохраняется в кэше содержимого рабочего пространства и читается там как папка каталога, привязанный к своему дайджесту, и ни один реестр больше о нём не запрашивается. Какой снимок читает вызов: с upgrade — новейший; иначе тот, который называет запись в выходной папке, полученный по его дайджесту, если на машине его нет; иначе тот, который рабочее пространство в последний раз получило как новейший; иначе новейший. Запись, которую создаёт импорт, называет прочитанный снимок по его дайджесту, поэтому более поздний вызов, создающий черновики в той же папке, читает тот же каталог. В автономном режиме вызов, которому пришлось бы получить снимок, отклоняется с указанием, что запустить, а upgrade отклоняется независимо от того, что хранится на машине, поскольку только реестр может сказать, какой снимок новейший. Реестр, не публикующий ни одного снимка, оставляет импорт без каталога, и элемент warn в diagnostics сообщает об этом. Рабочее пространство, указывающее папку каталога, импортирует на её основе и не получает ни одного снимка, и upgrade там ничего не меняет.

Не указывайте format, и формат будет распознан по сигнатурам, которые объявляют импортёры, — как из вашего каталога, так и базовые. Их записывает сущность Plugin каждого импортёра: синтаксис, в котором читается источник, имена файлов, к которым применяется сигнатура, и пути, которые разобранное дерево должно или не должно содержать. Источник разбирается — парсером, который каталог вашего рабочего пространства предоставляет для синтаксиса, или, для синтаксиса, для которого ваш каталог парсера не предоставляет, парсером, встроенным в сам компилятор, — по одному разу для каждого синтаксиса, в котором его читает сигнатура, применимая к его имени, и используется формат того единственного импортёра, чья сигнатура совпала. Затем импортёр читает источник тем же парсером. Сигнатуры базовых импортёров читают файл как JSON или YAML, а сигнатуры без указания файла читают его как JSON — у импортёра Dify как YAML, — поэтому распознавание отдельно импортируемого файла читает его в обоих синтаксисах и не требует парсера в каталоге вашего рабочего пространства: компилятор содержит парсеры JSON и YAML, а парсер из вашего каталога используется вместо них. Каталог распознаётся так же по своим файлам: каждая сигнатура проверяется на файлах каталога, выбираемых её шаблонами, а сигнатура без шаблона не применяется ни к одному из них. Распознавание читает указанный вами файл — или, для каталога, только файлы, выбираемые шаблонами сигнатуры, — и не обращается к сети. Источник, которому не соответствует ни одна сигнатура, отклоняется с запросом format и перечислением форматов, объявленных импортёрами, — или, для каталога, с запросом одного из его файлов, переданного отдельно как source, либо format, импортёр которого объявляет шаблоны файлов, с перечислением только таких форматов, — с условием No importer recognises the source (Ни один импортёр не распознаёт источник); источник, которому соответствуют сигнатуры более чем одного формата, отклоняется с их перечислением, с условием More than one importer recognises the source (Источник распознаёт более чем один импортёр); ни в одном из случаев источник не передаётся угаданному импортёру. В любом из случаев передайте format, чтобы явно указать формат, — для каталога такой, импортёр которого объявляет шаблоны файлов, поскольку каталог читается только через них. Пустой format отклоняется, а не трактуется так, будто вы его не указали, поскольку это разные запросы.

Передайте target, чтобы составить черновик Manifest, относительно которого собирается черновик Release для одного провайдера. target — это возможность провайдера (слово, к которому привязывается spec.capability сущности Recipe, например compose или helm), и это --target команды aggrega import, составляемый той же операцией, поэтому вызов и команда создают одинаковые черновики из одного и того же источника. Для каждого типа компонента и каждого типа функции, которые нужны черновикам, — в компонентах черновика Aggregate, их связях и его подсистемах, в сущностях Aggregates каталога, которые он компонует, и в присоединениях черновика Release — в порядке их первого объявления в черновиках импорт ищет в каталоге рабочего пространства сущности Recipes, а для типа функции — рецепты функций, реализующие этот тип и привязанные к этой возможности. Если такая ровно одна (несколько версий одной из них считаются одной), Manifest сопоставляет тип с ней по её имени, уточнённому возможностью, без версии, например compose/postgres; первый pull фиксирует его в lockfile на самой высокой доступной версии. Если их несколько с разными именами, сопоставляется та, что названа по самому типу, например helm/postgres для core/datastore/postgres. Если таких нет или их несколько, но ни одна так не названа, тип остаётся несопоставленным, а запись warn в diagnostics называет его и причину (каждую из нескольких — по имени), поэтому сборка черновиков останавливается, называя каждый его экземпляр или присоединение, с ошибкой No Recipe is mapped for a component or feature instance (Для экземпляра компонента или функции не сопоставлен Recipe), пока сопоставление не будет добавлено. Если импортёр сам составляет черновик Manifest, чтобы выбрать сущность Recipe, через которую рендерится экземпляр, или рецепт функции из нескольких, каждое записанное им сопоставление, которое каталог предлагает для этого типа и возможности, сохраняется, любое другое отбрасывается с записью warn, а оставшиеся типы сопоставляются, как описано выше. Manifest создаётся как manifest.yaml рядом с черновиком Release, с тем же именем и версией, что и Release, а spec.manifest сущности Release устанавливается на это имя: комментарий, который импортёр написал на этом месте, заменяется, и больше ничего в Release не меняется. Release, который уже называет Manifest, остаётся как есть, а если импорт не создаёт черновик Release, Manifest создаётся рядом с Aggregate, с его именем и версией, и запись info сообщает, что на него ничто не ссылается. Manifest и изменённый Release — такие же черновики, как остальные: они указаны в written, в записи и возвращаются при dry_run. Значение target, к которому не привязана ни одна сущность Recipe в каталоге, отклоняется до запуска импортёра с ошибкой An import’s target names a capability no Recipe in the catalog binds to (Цель импорта называет возможность, к которой не привязан ни один Recipe в каталоге), с указанием значения в том виде, в каком вы его передали, и возможностей, к которым привязаны Recipes каталога, и ничего не записывается. Если не указать target, Manifest не создаётся — кроме случая sync, который создаёт черновик для цели, переданной предыдущему импорту; пустой target отклоняется, а не воспринимается так, будто вы его не указали.

Передайте output_dir, чтобы указать каталог для черновиков. Если его не указать, они помещаются в корень рабочего пространства, определённого вызовом, — туда же, куда их записывает aggrega import, когда вы не указываете место назначения, где бы вы её ни запускали, и куда их записывает aggrega/import языкового сервера, когда в его запросе место не указано. Место назначения необязательно во всех трёх случаях и указывается так же, как любой путь, передаваемый этому серверу. Через HTTP это каталог внутри рабочего пространства, которое обслуживает этот сервер, записанный относительно его корня: значение, выходящее за пределы корня, абсолютный путь вне его и каталог, ведущий за его пределы через ссылку, — включая ещё не созданный каталог под такой ссылкой, — отклоняются с указанием output_dir, и ничего не читается и не записывается. Через стандартный ввод и вывод он принимается как указан, как и любой путь там: относительное значение разрешается относительно корня рабочего пространства, определённого вызовом, а абсолютное может указывать каталог вне рабочего пространства, в который черновики записываются так же, как это делает aggrega import --output-dir. Записываемое туда, с разрешёнными ссылками, ограничено рабочим пространством — или, для указанного вами каталога вне его, этим каталогом, — поэтому ссылка внутри, ведущая за его пределы, отклоняется, и ничего не записывается. Пустой output_dir отклоняется, а не трактуется так, будто вы его не указали. На стандартном вводе и выводе cli-import также передаёт --output-dir команды как собственный output_dir; относительное значение там разрешается в папке, в которой выполняется команда: в корне рабочего пространства, указанном вызовом, иначе в том, с которым был запущен сервер, иначе в папке, в которой работает сервер.

Каждый путь черновика проверяется относительно выходного каталога до какой-либо записи. Путь, выходящий за его пределы, отклоняется с указанием и пути, и каталога, и не записывается вообще ничего — даже файлы того же набора с допустимыми путями, поскольку отклонённый импорт, оставивший после себя часть результата, — это результат, которого никто не просил. Путь черновика исходит от плагина-импортёра, а не от вас, поэтому он проверяется по той же причине, что и переданный вами путь.

Каждый импорт, создающий хоть что-то, также записывает рядом с черновиками .aggrega-import.json: запись о том, что он записал, — target, который ему передан, если он был передан, снимок каталога, который он прочитал, если прочитал, и каждый черновой файл, а в черновой сущности Aggregate или Release — каждый ключ на любой глубине с дайджестом записанного там текста; любой другой черновой файл записывается целиком. Текст ключа — это его строка, строки его значения, если значение не является отображением ключей, и строки комментариев, записанные непосредственно над ним с тем же отступом. written называет запись вместе с черновиками, а при dry_run она входит в возвращаемые черновики. Запись имеет формат JSON, поэтому ничто, читающее YAML-документы рабочего пространства, её не читает.

Вызов никогда не перезаписывает сущность Aggregate, уже находящуюся в выходном каталоге. Aggregate — это документ, который автор продолжает редактировать после создания черновика, поэтому вызов, один из черновиков которого попал бы на файл, читаемый как Aggregate, отклоняется с указанием черновика и каталога, и не записывается вообще ничего — в том числе при dry_run, поскольку пробный запуск отклоняет то же, что отклоняет запись. Любой другой файл, уже находящийся по пути черновика, перезаписывается, а файл, созданный предыдущим импортом, но не создаваемый этим, остаётся на месте.

Передайте sync, чтобы вместо этого привести то, что набросал предыдущий импорт, в соответствие с источником, изменяя только то, что записал импорт. Синхронизация без target создаёт черновики для цели, указанной в записи, то есть набрасывает тот же Manifest, что и предыдущий импорт; синхронизация с target создаёт черновики для этой цели, и после этого запись указывает её. Записанная цель, к которой не привязан ни один Recipe в каталоге, отклоняется так же, как переданная, причём в отказе сказано, что цель взята из записи. Каждая часть оценивается с трёх сторон: что, согласно записи, импорт записал туда в последний раз, что лежит на диске и что источник даёт сейчас. Часть, которую источник оставил такой, какой её в последний раз записал импорт, остаётся в точности такой, как на диске, независимо от того, редактировал ли её автор. Часть, которую источник изменил, записывается заново, часть, которую он убрал, удаляется (черновой файл удаляется целиком), а часть, которую он добавил, добавляется рядом с частями, которые черновик называет вокруг неё, — каждое только там, где на диске находится то, что импорт записал в последний раз, и нет ничего добавленного автором. Всё остальное сохраняется байт в байт: ключ, добавленный автором где угодно (параметр, сущность Feature, в том числе внутри чернового экземпляра Component, другая сущность Component, окружение, которое черновой Release оставляет своему автору), комментарий, записанный не непосредственно над черновым ключом, и каждый файл, не перечисленный в записи. Поле ответа drift перечисляет каждую приведённую в соответствие часть (или, при dry_run, каждую часть, которая была бы приведена) в том порядке, в каком их называет черновик: каждую как change (added, removed или changed), file — черновой файл, в котором она находится, и key — ключи, ведущие к ней в черновом Aggregate или Release, в виде списка, пустого, если часть — это весь файл; текстовый ответ называет каждую на отдельной строке теми же словами, которые aggrega import пишет в стандартный поток ошибок: <change> <key> in <file> или <change> <file>. Пустой drift при dry_run означает, что черновики согласованы с источником. При dry_run возвращаемые черновики — это файлы, которые записала бы синхронизация, с тем содержимым, которое она бы им дала. Синхронизация, которая изменила бы или удалила часть, отредактированную автором, добавила бы часть там, где автор уже написал свою, или удалила бы часть, содержащую что-то добавленное автором, отклоняется, с указанием каждой такой части и причины, и ничего не записывается; комментарий, записанный непосредственно над черновым ключом, считается правкой этого ключа. Синхронизация поверх Aggregate, не указанного ни в одной записи, отклоняется с соответствующим сообщением, как и синхронизация, запись которой не удаётся прочитать, а синхронизация, импортёр которой не смог завершить работу, ничего не записывает. Синхронизация в каталог, где нет записи и ничего нет по черновым путям, записывает весь черновик. Для вызова, не являющегося синхронизацией, drift — пустой список.

Ответ содержит source — в том виде, в каком вы его указали; format — как был прочитан источник; workspace_root — корень рабочего пространства, определённого вызовом; output_dir — каталог, относительно которого заданы черновые пути; written — файлы, попавшие на диск; drift — что синхронизация привела в соответствие; diagnostics — по одной записи на каждую конструкцию, которую импортёр не смог перевести; decisions — как импортёр сопоставил каждый узел источника; и halted. output_dir — это переданный вами каталог или, если вы его не передали, тот самый корень, взятый из того, что фактически использовал импорт; он сообщается и при dry_run, когда ничего не записывается, но каждый черновой путь по-прежнему задан относительно него. По HTTP workspace_root не возвращается и помечается workspace_root_withheld, потому что корень — это место на хосте сервера, как описано в разделе Что ответ сообщает о файловой системе сервера; output_dir не возвращается и помечается output_dir_withheld, если он совпадает с этим корнем, а иначе сообщается по имени относительно корня — в той форме, в какой задаются ваши собственные пути, — так что в ответе всё равно видно, куда попали черновики. Импорт, который импортёр не смог завершить, всё равно создаёт те черновики, которые смог, и возвращается помеченным как сбой, неся весь этот ответ: halted равно true, файлы, всё же попавшие на диск, названы в written, а диагностика рядом с ними называет, чего не хватает. Это частичный результат, который можно сохранить или отбросить, а не вызов, который ничего не сделал.

decisions показывает, где импорт угадывал. Он содержит по одной записи на каждый узел источника, сопоставленный импортёром, в порядке импортёра: source_node — id, type и params_summary узла; candidates — каждую сущность Component из каталога, которую импортёр рассматривал для него, в виде component, score, tier и signals (вклад каждого из её сигналов в полях table, category, domain_labels, shape и name); chosen — выбранную цель target, режим mode, в котором она записана (reference на существующую сущность Component или draft), и уровень tier выбора; rationale — почему; и swap_hint — как выбрать иначе. candidates отсутствует, если импортёр никого не рассматривал, chosen — если он ничего не выбрал, а rationale и swap_hint — если он их не записал. Все значения принадлежат самому импортёру: как он оценивает кандидата и где проходят границы его уровней — его выбор, поэтому читайте запись как его отчёт о сопоставлении. decisions присутствует в ответе и при dry_run, и при остановке импорта, а для импортёра, который ничего не сообщает, это пустой список. Текстовый ответ называет каждое решение на отдельной строке после диагностики теми же словами, которые aggrega import пишет в стандартный поток ошибок: mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, где оценка — оценка лучшего кандидата.

dry_run делает всё, кроме записи. Каждый черновой файл возвращается в drafts со своим путём относительно output_dir и содержимым, и ничего не создаётся — это для клиента, который показывает вам результат до сохранения. Всё остальное поведение такое же, как при записи: тот же импортёр над тем же источником сообщает ту же диагностику, поэтому источник, который запись отклонила бы, отклоняется и в этом режиме. Без него файлы оказываются на диске и перечисляются в written, а drafts отсутствует, чтобы не повторять байты, которые вы попросили записать.

Черновики — это отправная точка, которой вы владеете и которую продолжаете редактировать. Допустимо ли то, что в них сказано (объявляет ли производитель данный сокет, выполнена ли применимость сущности Feature), здесь не решается. На это отвечает validate.

Через стандартный ввод и вывод та же возможность доступна также как cli-import, который запускает команду и возвращает напечатанный ею текст; по HTTP этого инструмента нет, и там возможность доступна через этот.

Публикация, подпись и отзыв

Четыре инструмента помещают что-либо туда, откуда это будут разрешать другие люди. publish-entity упаковывает сущность каталога и публикует её; publish-artifact публикует отдельный файл, например пакет документации, байты которого непрозрачны и конверт сущности не разбирается; sign-artifacts подписывает уже опубликованные ссылки и прикрепляет каждую подпись, оставляя как есть ссылку, которая уже несёт подпись, проверяемую политикой доверия её реестра; deprecate-artifact прикрепляет к ссылке подписанный маркер отзыва. Прочтите Что ассистент может делать, не спрашивая вас, прежде чем разрешать какой-либо из них: это инструменты, последствия которых выходят за пределы машины.

publish-entity принимает entity — документ для публикации, а для сущности Plugin нужен также plugin — исполняемый файл, публикуемый внутри её манифеста. publish-artifact принимает file вместе с name и tag, под которыми он публикуется. Каждый аргумент-путь здесь абсолютный или относительный к корню рабочего пространства — тот же контракт, что используют все остальные инструменты этой поверхности, а workspace_root указывает рабочее пространство, о котором идёт речь в вызове, — на сервере, доступном через стандартный ввод и вывод. Сервер, доступный по HTTPS, отклоняет workspace_root и требует, чтобы каждый из этих путей разрешался внутри обслуживаемого им рабочего пространства, как описано в разделе Один процесс — одно рабочее пространство. registry — место назначения; по умолчанию это реестр, настроенный в рабочем пространстве; если не передано ни то, ни другое и реестр по умолчанию не настроен, вызов отклоняется с указанием, что нужно передать. sign-artifacts принимает references — один или несколько адресов в реестре, а не пути, — и, необязательно, jobs — сколько из них подписывается одновременно: если параметр опущен, они подписываются по очереди, а значение меньше 1 отклоняется с указанием, что нужно передать. Каждая ссылка при этом подписывается точно так же, как если бы подписывалась отдельно, как описано в aggrega sign. deprecate-artifact принимает либо reference с severity и reason, либо from, указывающий пакетный файл, — и отклоняет аргументы содержимого, переданные вместе с пакетным файлом, а не отбрасывает их, потому что пакетный файл задаёт собственные, а молча проигнорированный аргумент выглядит как учтённый.

Оба инструмента публикации принимают dry_run, который показывает, что отправила бы публикация, не обращаясь ни к одному реестру. Он вычисляет пакет, сообщает, что было бы опубликовано, и отвечает с beyond_this_machine, равным false, и местом назначения, к которому он обратился бы, в registries; publish-entity также отвечает с digest, который получила бы публикация, — тем же, что выводит aggrega push --dry-run. Так можно показать кому-либо предлагаемую публикацию до того, как она состоится. У подписи и отзыва такой формы нет: оба действуют на уже опубликованное, поэтому предварительно показывать нечего.

publish-entity отвечает с windows_unusable_entries, если публикуемый им архив содержит записи, которые Windows не может хранить в записанном виде, — путь с частью, названной по имени устройства, например CON, AUX или NUL, в любом регистре и с любым последующим расширением, либо частью, оканчивающейся точкой или пробелом, — перечисляя каждую: сначала имя файла самого документа сущности, затем файлы, которые она несёт. Если таких нет, поле отсутствует, в том числе для сущности, опубликованной только в виде её документа. aggrega, запущенный в Windows, отказывается распаковывать такую запись, поэтому рабочее пространство в Windows не может использовать эту версию; это те записи, о которых предупреждает aggrega push, и текст ответа тоже их называет. Они ничего не отклоняют: вызов выполняется или отклоняется точно так же, как без них, включая dry_run.

publish-entity принимает pin_sources, который выполняет для сущности шаг закрепления автора сущности до её упаковки, так что entity.lock, записанный этим шагом рядом с ней, входит в публикуемое. Это тот же шаг, что выполняет инструмент pin, записывающий те же байты, и он выполняется до любого отказа, оценивающего сущность, — поэтому публикация, отклонённая на этом этапе, скажем, из-за отсутствующей подписи, всё равно оставляет lock-файл записанным рядом с сущностью. Отказ, касающийся самого вызова, например офлайн-режим рабочего пространства или отсутствие места назначения, наступает раньше и ничего не закрепляет. Если параметр не передан, решает pin_sources_at_push рабочего пространства; если передан, он решает в любую сторону. Публикация с закреплением пишет и в рабочее пространство, и в реестр, поэтому по HTTP ей нужны учётные данные с обеими областями, а учётные данные только с областью, допускающей публикацию, отклоняются с указанием второй. Если шаг выполнялся, результат содержит pin в той форме, в которой отвечает инструмент pin; при dry_run шаг сообщает, какой lock-файл он записал бы, и ничего не пишет. Если шаг не выполняется, сущность Recipe или FeatureRecipe, чей entity.lock не содержит закрепления для читаемого ею входа, — или содержит закрепление, которому вход больше не соответствует, — отклоняется до какой-либо упаковки, включая dry_run, с указанием aggrega pin, pin_sources и pin_sources_at_push. Это тот же отказ, что выдаёт pull для того же lock-файла, и его проверка полностью загружает каждый удалённый источник, который выписывает сущность, как это сделал бы шаг.

Подпись — то место, где расходуются учётные данные, и её выполняют три инструмента из четырёх: публикация артефакта данных ничего не подписывает и подписывается впоследствии по ссылке. identity_token предоставляет для вызова бесключевую идентичность. На сервере, доступном через стандартный ввод и вывод, если его не передать, используется идентичность из собственного окружения этого сервера, а key_path вместо этого выбирает хранимый офлайн-ключ. Через слушатель ни то, ни другое недоступно: окружение не читается, key_path отклоняется и не объявляется этими тремя инструментами, а ключ, указанный в конфигурации обслуживаемого рабочего пространства, не используется, — поэтому подписывает только токен, переданный в вызове, как описано в разделе Какие учётные данные расходует вызов. Один вызов подписывает одними учётными данными. Каждая ссылка, переданная sign-artifacts, и каждая запись пакетного файла, читаемого deprecate-artifact, подписываются одним и тем же хранимым ключом или одной и той же бесключевой идентичностью; если конфигурация обслуживаемого рабочего пространства указывает ключ для реестра одной ссылки и не указывает для реестра другой либо указывает два разных ключа, вызов ничего не подписывает и отклоняется с указанием реестров с каждой стороны, прежде чем будет разрешена какая-либо идентичность или прочитан какой-либо реестр, — отправляйте по одному вызову на каждые учётные данные или один key_path для всех через стандартный ввод и вывод. Через слушатель настроенный ключ не используется, поэтому там каждая ссылка подписывается идентичностью, переданной в вызове, и по этой причине вызов никогда не отклоняется. Этот отказ описан в разделе References signed together need different signing credentials (Ссылкам, подписываемым вместе, нужны разные учётные данные для подписи). fulcio_url, rekor_url и timestamp_url переопределяют бесключевые конечные точки, настроенные в рабочем пространстве, на любом транспорте. Если ни одна идентичность не разрешается, вызов отклоняется и указывает, что нужно передать: здесь ничто не открывает браузер и не ждёт человека, потому что за потоком протокола никто не следит, а зависший вызов был бы той самой тихой ошибкой, для предотвращения которой и существует отказ. В publish-entity прикрепляется ли подпись вообще, определяется политикой реестра назначения, если sign не указывает иное, а реестр, требующий подписей, отклоняет неподписанную публикацию, что бы вы ни передали: аргумента, обходящего этот отказ, нет. Два режима подписи и то, к чему обращается каждый из них, описаны в aggrega sign.

Каждый результат содержит факты, а не стенограмму: куда попал артефакт, его тег, опубликованный дайджест — или, для пробного запуска с сущностью каталога, дайджест, который получила бы публикация, — указывал ли тег уже на побайтно идентичное содержимое, была ли публикация подписана, а также её reach. Пакет подписания сообщает каждую подписанную ссылку вместе с дайджестом, к которому привязана её подпись, в том порядке, в котором были заданы ссылки, а пакет, в котором хотя бы одна ссылка не прошла, возвращается как сбой с указанием каждой такой ссылки, а не как результат с неполным списком: частичный пакет, представленный как успех, — это путь, которым отказ начинают воспринимать как прохождение. Отзыв сообщает каждый маркер с его собственным дайджестом, поскольку маркер прикрепляется как нетегированный реферер отзываемого артефакта и никакой другой адрес на него не указывает. Подписание или отзыв ссылки, по которой ничего не опубликовано, отклоняется, а не прикрепляется к пустоте.

Две части ответа

Каждый инструмент отвечает читаемым текстом, а там, где у операции он есть, — ещё и структурированным результатом рядом с ним. Текст написан для человека, читающего диалог. Структурированный результат несёт тот же ответ в виде полей, которые читает программа, — вердикт, список файлов, диагностику, — и отказ тоже несёт его, если на момент отказа у операции были результаты проверки, как описывает для сборки раздел Что возвращает отклонённая сборка.

Структурированный результат также несёт текст — в поле text_answer. В структурированном результате каждого инструмента есть поле text_answer, содержащее текст ответа точно в том виде, в каком его несёт текст: каждое предложение, по порядку, без изменений. Поэтому клиент, который передаёт своей модели структурированный результат, а не текст, как это делает Claude Desktop, всё равно передаёт ей каждое предложение текста — строку, с которой начинается ответ describe-capabilities без аргументов, действующую конфигурацию, о которой сообщает config-show, предложение с именем папки, использованной ответом, когда рабочее пространство не найдено. text_answer записывается первым, перед полями, которыми отвечает инструмент, и это именно тот текст, который получает вызывающая сторона: при работе по HTTP он называет каждое место на хосте сервера так же, как текст, — см. раздел Что ответ сообщает о файловой системе сервера. Сам текст остаётся прозой для клиентов, которые его читают, поэтому одни и те же слова передаются в каждом ответе дважды.

Исключений нет ни для одного инструмента, включая lint. Ни один инструмент не отвечает собственным полем с именем text_answer, поэтому это поле никогда не подменяет другое. Структурированный результат lint сохраняет своё поле summary — количество проверенных сущностей и найденных проблем, всего и по уровням серьёзности, под теми именами, которые aggrega lint выводит с -o json, — и несёт text_answer рядом с ним. describe-capabilities тоже сохраняет свои поля: version_summary — отдельную строку версии, когда инструмент вызван без аргументов, и в каждой записи своего index — summary, однострочное описание назначения соответствующего инструмента.

Ни один инструмент не объявляет схему вывода. Описание инструмента в списке содержит схему принимаемых аргументов и не содержит схемы результата, поэтому text_answer описан здесь, а не в схеме.

Ответ без структурированного результата состоит только из текста. Отказ из-за аргументов вызова, как и любой другой сбой, о котором операции нечего было сообщить в структурированном виде, возвращается только в виде текста, и тогда текст — единственная часть, которую клиент может показать своей модели.

Когда вызов не завершается успешно

То, куда приходит ответ, зависит от одного: может ли вызывающая сторона исправить ошибку, изменив аргументы существующего инструмента.

Всё, что можно исправить таким образом, возвращается как собственный результат инструмента, помеченный как сбой и содержащий исправление в виде текста: сочетание селекторов, которое инструмент не принимает, пропущенный обязательный аргумент, аргумент, переданный с неверным типом JSON, путь, который не разрешается, диагностика компилятора. Именно этот канал видит ассистент, поэтому он читает, что пошло не так, и повторяет вызов с исправленным аргументом.

Канал ошибок протокола оставлен для того, чему негде разместиться в результате инструмента: имени инструмента, который сервер не обслуживает, запроса, параметры которого он не может прочитать, метода, который он не реализует, и сообщения, которое вообще не является корректным JSON. Чтение ресурса и отрисовка промпта также отвечают через этот канал, поскольку ни один из этих результатов не несёт собственного флага сбоя.

Объявленная схема инструмента также описывает большинство правил, которым должны удовлетворять его аргументы: какие селекторы взаимно исключают друг друга, какой аргумент имеет смысл только вместе с другим и какие аргументы обязательны, поэтому клиенту, составляющему вызовы по объявленной схеме, редко приходится выполнять вызов, чтобы узнать эти правила. Правило, которого схема не указывает, всё равно приводит к отказу с предложением, называющим это правило; правило pull, согласно которому verify не сочетается с upgrade_targets или pin_sources, намеренно оставлено на отказ по причине, изложенной в разделе Разрешение того, от чего зависит сущность Release.

Что останавливает сервер

При работе через стандартный ввод и вывод сервер останавливается закрытием соединения. Сервер читает по одному сообщению в строке и корректно завершается, когда его стандартный ввод достигает конца потока, поэтому клиент, закрывший соединение, тем самым завершает работу сервера. Для этого транспорта это обычный случай, поскольку вы никогда не запускаете команду сами: её завершает тот клиент, который её запустил, так что остановка сервера обычно выглядит как выход из редактора или отключение этого сервера для проекта.

Запрос на остановку, адресованный самому процессу, доходит до сервера при любом транспорте. Прерывание из терминала или запрос на завершение от супервизора или среды выполнения контейнеров останавливает сервер при первом же запросе, независимо от того, отправляет ли клиент что-либо: сервер перестаёт принимать сообщения, прекращает работу, которую выполняет текущий вызов, и корректно завершается. Второй запрос немедленно завершает процесс. Поэтому при работе через стандартный ввод и вывод вызов, который ещё выполняется в момент запроса на остановку, не завершается; слушатель же, напротив, дорабатывает: вызову, на который уже формируется ответ, даётся завершиться в пределах ограниченного времени, прежде чем процесс завершится.

Клиент может также остановить отдельный вызов, не останавливая сервер, и способ зависит от транспорта. Вызовы обрабатываются параллельно, поэтому запрос на завершение одного из них выполняется, пока этот вызов ещё работает, а не ждёт его окончания. При работе через стандартный ввод и вывод клиент указывает id вызова; отмена вызова, на который уже дан ответ, или вызова, над которым сервер не работает, ни на что не влияет — именно поэтому такое сообщение безопасно отправлять, не зная заранее, не отправлен ли уже ответ. По HTTP отправлять сообщение не нужно: закрытие соединения, по которому был сделан вызов, завершает его. В любом случае вызову сообщается об остановке — его работа прекращается в следующей точке, где операция выполняет проверку, а операция, которая никогда не выполняет проверку, доходит до конца, — по этому вызову больше ничего не отправляется, все остальные текущие вызовы продолжаются, и сервер продолжает работу.

Когда использовать

Используйте aggrega mcp, когда хотите, чтобы ИИ-ассистент помогал создавать сущности Aggrega на основе реальных схем и справочника, — так его предложения опираются на точную структуру, которую принимает компилятор, а не на догадки. Команда напрямую вписывается в цикл создания: ассистент читает схему и справочник по виду сущности, создаёт заготовку, заполняет поля, за которые отвечает ваша роль, и выполняет проверку, прежде чем вернуть черновик. Описание этого цикла см. в разделе Написание файлов Aggrega.

При работе через стандартный ввод и вывод вам, как правило, никогда не приходится вводить aggrega mcp самостоятельно. Вместо этого вы один раз указываете команду в конфигурации MCP вашего клиента, и клиент сам запускает и останавливает её. Слушатель — другой случай: здесь процесс запускаете вы, и он продолжает работать для вызывающих сторон, которые его не запускали.

Пример: конфигурация клиента через стандартный ввод и вывод

Укажите MCP-клиенту эту команду с помощью записи сервера stdio:

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

Единственное предварительное условие — установленный исполняемый файл aggrega в PATH клиента. Пути конфигурации для отдельных клиентов и устранение неполадок описаны в разделе Подключение сервера MCP. Чтобы получить схему напрямую из командной строки без клиента, см. aggrega get-schema.