aggrega mcp
Запустити сервер Model Context Protocol через стандартні введення й виведення або через HTTP для інтеграції з ШІ-помічниками
Синтаксис
aggrega mcp [flags]Опис
Run Aggrega as a Model Context Protocol (MCP) server, so an AIassistant can discover and drive Aggrega operations through a structuredprotocol instead of scraping command output.
Two transports reach the same server, and --transport chooses betweenthem, with mcp.transport in the workspace configuration as the key itoverrides. The default, stdio, speaks newline-delimited JSON-RPC 2.0 overthe process's standard input and output, which is how an MCP-capableclient runs it: spawned as a subprocess, not typed by hand. http servesthe protocol over HTTP instead — one long-running process on a host,reached by callers who are not at its keyboard — on the address --listennames, or mcp.listen when the flag is absent.
An address chooses no transport. --listen given with the stdio transportis refused, whether stdio was typed, configured or left as the default,because it names where to listen for a transport that does not listen.An address mcp.listen names is left unused by a server on standard inputand output, which says so in one line on stderr, so a client can launchthis command in a directory whose configuration is written for alistener. And the http transport with no address from either is refusedbefore anything binds.
It speaks two MCP protocol revisions on both transports, 2026-07-28 and2025-06-18, so a client of either connects. In 2026-07-28 nothing issettled for the connection as a whole: every request states the protocolversion it speaks and the capabilities its sender offers, and the serverreads both from the request it is answering rather than holding anythingbetween messages. In 2025-06-18 a client settles those same facts once,by opening the connection with an initialize handshake.
Both revisions reach the same server, and a client learns the samethings about it either way. A client on 2026-07-28 calls server/discoverfor the revisions the server speaks, the capabilities it advertises —tools, resources, and prompts — and the guidance it offers a modelbefore the first call. A client on 2025-06-18 receives those samecapabilities, and that same guidance, in the reply to its handshake.
From there the client discovers the server's surface through the listmethods (tools, resources, resource templates, and prompts) and invokesit through tools/call and resources/read. The server exposes Aggregaoperations — compiling and inspecting a Release, reading catalogentities — as tools and resources an assistant can call directly.
On standard input and output, stream discipline is strict: stdout carriesonly protocol messages, one JSON object per line, so the client can parsethe stream without heuristics. Every log, warning, and diagnostic iswritten to stderr instead. The server reads one message per line andexits cleanly when stdin reaches end of stream, so a client that closesthe connection shuts the server down. A client ends one call by namingits id, and every other call carries on.
Over HTTP there is one endpoint, /mcp, accepting POST. Every message isits own request and no session of any kind is kept, so nothing a clientsends first decides how a later request is answered. Closing theconnection ends the call it carried. A request carrying an Origin headeris checked against mcp.allowed_origins, and mcp.limits bounds how largeone request body may be, how many requests are answered at once, and howmany one caller may send in a minute. A caller sending faster thanmcp.limits.requests_per_minute is answered 429, counted against thatcaller alone.
Every request to /mcp carries a credential, and which one depends onwhether a proxy in front has already checked it. By default it is abearer token the server verifies itself, against the keysmcp.authorization.issuer publishes: it must come from that issuer, namemcp.authorization.resource among its audiences, be inside its validitywindow, and be signed with an asymmetric algorithm. A request carrying notoken is answered 401 with a challenge, and so is one whose token failsany of those. A token is never accepted from the address, never forwardedanywhere, never exchanged, and never written to any log; the subject itnames is recorded and compared to nothing.
Set mcp.authorization.trusted_proxy instead and the caller is read from aheader the proxy sets rather than from a token, with its scopes from asecond header; no token is read at all in that mode, and a requestwithout the principal header is answered 401. Because that header is thenthe whole credential, it is trustworthy only where nothing else can setit: the process is refused before it binds unless mcp.listen is loopbackor a Unix socket.
The challenge names where to obtain a token. A listener publishes anOAuth protected-resource metadata document, with no credential asked for,naming the authorization server, this deployment's own address and thescopes that exist; it is served at /.well-known/oauth-protected-resourceand at that path followed by the endpoint path, which are the two placesa client looks. A client reads it before it can hold a token, which iswhy it is the one answer given without one. What that document publishescomes from mcp.authorization.issuer and mcp.authorization.resource, and alistener is refused before it binds unless both are set.
The issuer is an https address unless the authorization server runs onthis machine (localhost, 127.0.0.1 or ::1), and that holds in everymode: with the keys read from the issuer, with a key file, and with aproxy in front. Every client is sent to the issuer to obtain its token,so a plain http issuer on another host would carry each client'sauthorization code and token across the network unprotected, and alistener naming one is refused before it binds.
The verification keys are read from the issuer itself, by asking it whereit publishes them and fetching them from the address it names, and readagain once when a token arrives signed by a key identifier the held setdoes not carry. That address is held to the same rule as the issuer, andso is every redirect either read is answered with: a plain http addresson another host is never asked, and a token needing those keys isanswered 503 until the authorization server publishes its metadata andkeys over https. A workspace that is offline makes no such request, sothere mcp.authorization.jwks_file names a file holding those keys and alistener is refused before it binds without it.
Liveness and readiness are answered on a second address, and only there.Set mcp.health.listen and a GET of /healthz reports that the process isrunning while a GET of /readyz reports whether it can answer a call yet,each a status code with an empty body and no credential asked for. Theaddress opens before the workspace is resolved, so a supervisor sees theprocess alive while it is still deciding whether it can serve at all.Leave the key unset and no second listener exists. The endpoint itselfanswers both paths the same not-found it gives every path it does notserve, with a token and without one, so reaching this process over thenetwork is never a way to probe it.
The workspace this process serves is fixed when it starts, on eithertransport: --workspace-root names it, and AGGREGA_WORKSPACE_ROOT suppliesit when the flag is absent. The folder named is the workspace rootitself, as it is for every command: a call naming no workspace of itsown is answered there, and nothing above it is searched for a workspace,so name the folder that holds the workspace's .aggrega-config.yaml. Anamed folder that does not exist is refused, naming the flag or thevariable that supplied it and the value as it was given: a listener isrefused before it binds, while a server on standard input and outputwrites the refusal to stderr and starts all the same, answering everycall that acts in that workspace with it, so a client that showsnothing of stderr still shows the refusal. An emptyAGGREGA_WORKSPACE_ROOT is read as unset, but for one launch: a serveron standard input and output given no --workspace-root, whoseenvironment carries the AGGREGA_BUNDLE_VERSION the desktop bundle sets,was started with the desktop application's Workspace folder settingempty. It is served the same way, the refusal naming that setting, sono call naming no workspace of its own is answered in the directory itwas started in. In every other case where neither names a root, aserver on standard input and output resolves the workspace from thedirectory it was started in, while a listener is refused before itbinds unless a workspace resolves there: one reachedover HTTP serves a workspace an operator chose rather thanwhichever directory it happened to be started in. Where that directoryanchors no workspace, a call naming no workspace of its own that namesits Release or document by an absolute path is answered in the workspacethat file's folder resolves, as the same command typed at a terminal inthat directory would be.
For the same reason a call arriving over HTTP cannot name a workspace ofits own. Sending workspace_root or catalog_dirs is refused, naming theargument, and the directories searched for catalog entities beside theserved workspace are the ones that workspace itself resolves: its ownworkspace.catalog_dirs setting — or, for a Release it gives directoriesof its own under workspace.releases, that Release's — then its catalogdirectory. Overstandard input and output both arguments are honoured: the client thatlaunched the server is running on this machine.
A workspace_root such a call sends is read the same way by every tool,the tools that run a command included. An absolute one is used asgiven. A relative one is read from the root a call naming no workspaceof its own is answered in — the folder --workspace-root orAGGREGA_WORKSPACE_ROOT names, which the desktop application sets fromits Workspace folder, or, where neither names one, the workspace rootthe directory the server was started in resolves to — so a client thatcannot see where that folder sits on the machine still names a folderinside it, as quickstart-ai/1. Where there is no such root to read itfrom, a relative one is refused as a call naming none is refused, andan absolute one is answered as it always is.
Asking the process itself to stop — an interrupt from the terminal, or atermination request from a supervisor or container runtime — shuts theserver down on the first request, whether or not a client is sendinganything: it stops accepting messages, ends the work a call in progressis doing, and exits cleanly. A listener stops accepting and lets a callalready being answered finish, within a bounded budget, before theprocess exits. A second request ends the process at once.Прапорці
| Прапорець | За замовчуванням | Опис |
|---|---|---|
--listen | — | Адреса, яку прослуховує транспорт HTTP, в одній із двох форм: host:port або unix:, за яким іде шлях у файловій системі. Вона визначає, де прослуховувати, і не обирає транспорт: її зчитують за —transport http або mcp.transport: http у конфігурації робочого простору, а разом із транспортом stdio її відхиляють. Слухач без сертифіката обслуговує відкритий текст і дозволений лише на loopback (127.0.0.1, ::1, localhost) або на Unix-сокеті — саме такий вигляд має сервер за проксі, що термінує TLS; будь-яка інша адреса потребує 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 у локальний кеш і записати її lock-файл;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, а не пропонуються й відхиляються, а на виклик, що називає один із них, надходить помилка, яка про це повідомляє. Це властивість транспорту, а не налаштування: жодна конфігурація не повертає їх.
Прочитайте Без облікових даних нічого не обслуговується, перш ніж розгортати такий сервер. Кожен запит до кінцевої точки містить облікові дані, і немає налаштування, яке обслуговує запит без них, — налаштування обирає лише те, чи перевіряє цей сервер токен bearer сам, чи зчитує викликача, якого вже перевірив проксі перед ним.
Дві схеми розгортання
Процес сам завершує TLS. Задайте mcp.tls.cert_file як ланцюжок сертифікатів PEM, а mcp.tls.key_file — як його приватний ключ, і слухач обслуговуватиме HTTPS безпосередньо на тій адресі, яку ви йому дали. Обидва файли зчитуються під час запуску процесу, тож замінений сертифікат підхоплюється перезапуском процесу. Задання одного без іншого відхиляється під час запуску, а не призводить до відкату: сертифікат без ключа не можна пред’явити, ключ без сертифіката нічого не називає, а помилка в одному шляху — не причина почати обслуговувати незашифрований трафік.
Проксі перед сервером завершує TLS і пересилає трафік обмеженому слухачеві. Залиште обидва ключі незаданими, і слухач обслуговуватиме відкритий текст, що приймається лише на loopback або на сокеті Unix, — тож ніщо поза цим хостом не може до нього дістатися. Таку схему використовують зворотний проксі, sidecar або service mesh, і в ній сертифікат розміщено перед цим процесом, а не в ньому.
Слухач відкритого тексту на будь-якій іншій адресі відхиляється ще до будь-якої прив’язки, і у відмові названо обидва ключі 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 задає його, коли прапорця немає. Названа тека і є коренем робочого простору, нічого вище за неї не шукається, а тека, якої не існує, відхиляється із зазначенням того з двох джерел, що її задало, і з цитуванням значення в тому вигляді, у якому його передано, — слухачем до того, як він прив’яжеться до адреси, а сервером на стандартному введенні й виведенні — у його відповіді на кожен виклик, що діє в цьому робочому просторі, як описано в розділі У якому робочому просторі обробляється виклик, — тож запуск, сформований клієнтом, а не набраний вручну, все одно повідомляє, що йому передали. Якщо немає ні того, ні іншого, сервер на стандартному введенні й виведенні визначає робочий простір за каталогом, у якому його запущено, — де там ніщо не закріплює робочий простір, кожна відповідь, що стосується робочого простору, повідомляє, яку теку використано, а запуск із настільного пакета з порожнім параметром Workspace folder натомість відхиляє виклик, що не називає власного робочого простору, як описано в розділі У якому робочому просторі обробляється виклик, — а слухач відхиляється до прив’язки до адреси, якщо там не визначається робочий простір: процес, доступний через HTTP, відповідає абонентам, які не бачать машини, тож він обслуговує робочий простір, обраний оператором, а не той каталог, у якому його випадково запущено. Щоб обслуговувати кілька проєктів, запустіть по одному процесу на корінь кожного проєкту.
Виклик, що надходить через HTTP, не може назвати власний робочий простір. workspace_root і catalog_dirs відхиляються із зазначенням надісланого аргументу, а не відкидаються мовчки: аргумент, який мовчки проігноровано, для відправника виглядає так само, як врахований. Каталоги каталогу, у яких виконується пошук поряд з обслуговуваним робочим простором, — це власне налаштування workspace.catalog_dirs цього робочого простору, а для сутності Release, якій він задає власні каталоги в workspace.releases, — налаштування цієї сутності Release; його пише оператор. На стандартному введенні й виведенні обидва аргументи враховуються, бо клієнт, що запустив сервер, працює на власній машині абонента. Там запис catalog_dirs є абсолютним або відносним щодо кореня робочого простору, з якого читається відносний release, — кореня, який першим визначили власний workspace_root виклику, запуск або каталог, у якому запущено сервер, і з якого читання триває й тоді, коли сутність Release, названа абсолютно, переносить виклик у власний робочий простір цієї сутності Release, — а не щодо каталогу, у якому працює сервер, якщо той розташований деінде.
Шлях, який називає виклик, теж залишається в межах цього робочого простору. Через HTTP аргумент-шлях розв’язується відносно кореня робочого простору й відхиляється, якщо виходить за його межі: відносний шлях, що піднімається за межі робочого простору, абсолютний шлях, що вказує деінде, і відносний шлях, що виводить за межі робочого простору через посилання на наявний там файл чи каталог, — кожен повертається як збій із зазначенням аргументу, але без зазначення кореня робочого простору чи місця, куди привів би шлях; відносний шлях цитується так, як ви його надіслали. Кожен аргумент-шлях оцінюється за тим, куди він веде, згідно з визначенням «усередині», яке наводить розділ Межа робочого простору, незалежно від того, читає його інструмент чи записує, — каталог, у який gen-catalog записує вивід, документ, який edit-document записує назад, і сутність, поряд з якою pin записує свій лок, так само як документ, що його читає інструмент, — тож ще не створений шлях під посиланням, що виводить за межі робочого простору, відхиляється так само, як це посилання, і нічого не читається й не записується. release, що називає сутність Release, яку називає конфігурація обслуговуваного робочого простору — як build.authoring_release або як ключ workspace.releases, — досягається через цю конфігурацію і приймається через посилання, де б не лежав її файл; жоден інший аргумент не має такого винятку. Якщо потрібний вам шлях розташований у цьому робочому просторі, але записаний абсолютно, відмова повідомляє запис відносно кореня, який слід надіслати натомість, тож абонент, що вгадав неправильну форму, дізнається правильну, а не лише те, що помилився. Це стосується шляхів, які виклик називає своїм предметом, — документа для перевірки, сутності Release для збирання, каталогу, у який генерація записує вивід, — і шляхів, у які інструмент записує, не менше, ніж тих, які він читає: абонент, що звертається до сервера через мережу, просить машину, якої не бачить, читати й записувати файли, і обраний оператором робочий простір — це місце, де це читання й запис утримуються. На стандартному введенні й виведенні аргументи-шляхи кожного інструмента дотримуються контракту, описаного для цього інструмента нижче, де шлях може бути абсолютним і може вказувати за межі робочого простору: особа, що викликає, володіє машиною, на якій працює сервер, тож обмеження її каталогом, який вона сама обрала, нічого б не дало. Два інструменти, сама операція яких відповідає лише щодо документа з робочого простору, insertion-point і edit-document, зберігають це на обох транспортах і відхиляють документ поза робочим простором, хоч записаний він так, хоч досягнутий через посилання, що виводить за межі. На стандартному введенні й виведенні враховується шлях, який називає виклик, і нічого понад нього. Те, що операція потім читає й записує від власного імені, обмежується на обох транспортах точно так само, як коли ту саму команду набрано в терміналі: обхід чи пошук не читає через посилання, що виводить за межі робочого простору; файл, який сутність Release у робочому просторі або її Manifest називає шляхом, не читається поза робочим простором, — а файл, який називає сутність Release, названа викликом поза робочим простором, не читається поза каталогом, що містить цю сутність Release, — а файл, записаний під каталогом (робочим простором або названим викликом), залишається в цьому каталозі. Розділ Межа робочого простору зіставляє два транспорти з командним рядком і редактором і описує, що залишається відкритим на стандартному введенні й виведенні: документ у клонованому вами робочому просторі може спонукати асистента назвати шлях поза робочим простором, і цей шлях враховується так, як його названо.
Що відповідь повідомляє про файлову систему сервера
Через HTTP відповідь називає місце у файловій системі сервера відносно кореня робочого простору або приховує його. Клієнт, який запустив сервер, працює там само, де й сервер, тому через стандартні введення й виведення кожна відповідь називає кожне місце так, як його зберігає операція, — абсолютно, якщо саме так його зберігають, — і кожне з них є місцем, яким цей викликач уже володіє. Викликач, що звертається до слухача, не обирав жодного з цих місць і не може їх відкрити, а сервер, який їх йому опублікував, не може скасувати цю публікацію. Тому через HTTP відповідь повідомляє такому викликачу про місце одне з двох:
- Місце всередині робочого простору називається відносно кореня робочого простору — у тій самій формі, що й шлях, який надсилаєте ви, тож назву, прочитану з однієї відповіді, можна без змін надіслати в наступному виклику. Сутність Release у корені — це
release.yaml, а її lock-файл —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 та її lock-файл уlockfiles, документ, якого стосується точка вставлення чи редагування, файли, записані редагуванням, — однакові на обох транспортах.cache-statusтакож приховує те, що називає плагін, який сервер завантажив із файлу на своєму хості. Така ідентичність має значенняnullна своєму місці вprovenance[].identities, кожна інша ідентичність зберігає свою позицію, а запис позначаєтьсяidentities_withheld.noteскомпільованого модуля — це одне речення, що називає ідентичності, для яких модуль було зібрано, тому якщо будь-яка з них називає такий файл,noteпропускається повністю й позначаєтьсяnote_withheld;digestмодуля при цьому залишається. Ідентичність, що називає посилання на реєстр або сутність Plugin, повертається повністю, так само як іnote, що називає лише такі.labelартефакту джерела — це його місце в кеші, записане з хоста й шляху URL, з якого його отримано, тому для репозиторію, прочитаного з власної файлової системи сервера — через URLfile://або шлях, —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, рендерить артефакти в пам’яті й повертає їх. Вона нічого по собі не залишає: нічого не записується, і відповідь — це все, що вона створює.
- Досягає робочого простору — записує всередині робочого простору, який обслуговує цей процес: lock-файл сутності 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, саме виклику, що записує.
Клієнтові, який не підтримує step-up, усе одно можна надати області запису, і це вирішується на сервері авторизації. Той, хто керує сервером авторизації, робить області запису стандартними областями для цього клієнта — областями, які сервер додає до кожного токена, виданого цьому клієнтові, незалежно від того, чи клієнт їх просив, — тож токен, отриманий під час першого входу, уже їх містить. Клієнт, який щоразу під час підключення заново реєструється на сервері авторизації, щоразу є там новим клієнтом, і налаштування, зроблене для попередньої реєстрації, не переноситься; для такого клієнта діє налаштування стандартних областей, які сервер авторизації надає кожному клієнтові, якого реєструє. Ціна в тому, що кожен вхід через такого клієнта тоді має доступ на запис, незалежно від того, чи потребує його поточна робота, — а якщо стандартні області задаються під час реєстрації, такий доступ має й кожен клієнт, зареєстрований у такий спосіб. Робіть стандартною лише ту область запису, яка потрібна для роботи: 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 без аргументів, як описано в розділі Which release the server comes from (З якого випуску походить сервер); запуск без пакета, а також запуск, пакет якого походить із власного випуску виконуваного файлу, передають настанови без нього. Обидві речі фіксуються під час старту процесу, і в межах будь-якого процесу обидві ревізії однаково віддають власний текст цього процесу.
Він пояснює ментальну модель, яку схема аргументів інструмента сама по собі передати не може:
- Що компілятор робить і чого він свідомо не робить — що він маршрутизує текст і обчислює збіги міток, а не інтерпретує, що означає значення, що він без власної позиції щодо вмісту, який ви розміщуєте у своїх документах, і що під час компіляції він ніколи не автентифікується в провайдера, ніколи не читає стан кластера й ніколи не перетворює секрет на відкритий текст. Значення, яке існує лише після запуску інфраструктури, проходить як рядок-вказівник, який цільове середовище заповнить пізніше.
- Словник автора і зв’язки між видами — для чого призначений кожен вид і з яким саме з них насправді запускається збирання, щоб асистентові не доводилося виводити форму розгортання зі списку інструментів.
- Порядок циклу авторської роботи — прочитати контракт, створити заготовку на його основі, оглянути те, до чого ви під’єднуєтеся, а потім перевірити перед рендерингом.
- Коли братися за промпт, а не за інструмент — інструмент, щоб діяти, промпт, щоб сформулювати завдання.
- Що список інструментів — це вся поверхня — у ньому є кожен інструмент, який пропонує цей сервер, а які інструменти пропонує сервер, залежить від того, як його налаштовано, тож асистент дізнається, що тут є, з цього списку й із
describe-capabilities, а не шукає другий. Якщо підключення пред’явило облікові дані, настанови повідомляють, що облікові дані визначають, які з цих інструментів може запустити виклик, і ніколи — які з них перелічено: виклик, який вони не допускають, відхиляється із зазначенням області доступу, що його допустила б, і клієнт може повторно ввійти для цієї області. - Що означає порожній робочий простір і що модель може з цим зробити — абзац, який відрізняється залежно від транспорту, нижче.
Настанови називають поверхні, а не переказують їх. Кожен інструмент уже має власний опис і схему аргументів у tools/list, а контракт кожного виду вже міститься в його схемі та на його довідковій сторінці, тож настанови вказують на них і на цьому зупиняються — одне місце для кожного твердження. Інструмент, який вони називають, — це інструмент, який обслуговує сервер, і вони вказують на кожне сімейство ресурсів, яке розв’язує поверхня читання, тож ніщо, по що вони посилають асистента, не веде в глухий кут.
Настанови не містять покажчика самих інструментів, і це те саме правило, а не виняток із нього. Клієнт має визначення кожного інструмента з tools/list ще до того, як прочитає бодай слово цього тексту, тож рядок для кожного інструмента тут був би другою копією призначень, які в нього вже є, — за яку платив би кожен сеанс і кожен клієнт і яка могла б розійтися зі списком інструментів, щойно одне з них відредагують.
Настанови також повідомляють, чого вони не перелічують і чому: доступні цілі рендерингу та встановлені види бібліотек — це властивості ваших плагінів і вашого набору схем, тож поверхні ресурсів повідомляють про них безпосередньо, а не настанови містять копію, яка могла б розійтися.
Що модель чує про порожній робочий простір
Завершальний абзац відповідає на запитання, з яким модель стикається першим у робочому просторі, де нічого немає: що означає порожній list-entities і що вона може з цим зробити. Його початок однаковий на обох транспортах — порожній перелік означає, що робочий простір, який розв’язав цей процес, не містить документів Aggrega, які він може прочитати, і каталоги, налаштовані поруч із ним, теж їх не оголошують, — а те, що йде далі, залежить від транспорту, який обслуговує цей процес, бо чесна відповідь на двох транспортах різна.
Через стандартні введення й виведення моделі кажуть, що робочий простір — її, щоб оглядати й виправляти. Їй кажуть, де відповідають на виклик, який не називає робочого простору, — у теці, з якою запущено сервер, якщо його запущено з нею, а інакше в робочому просторі, знайденому від теки, у якій його запущено, і це може бути сама ця тека, — і що workspace_root у виклику називає інший. Її спрямовують до config-show щодо чинної конфігурації та того, який рівень визначив кожне налаштування, і до cli-config-init для створення робочої конфігурації; обидва є в списку інструментів на цьому транспорті. Клієнт, що запускає сервер, перебуває на власній машині того, хто викликає, тож усе, до чого може дістатися цей процес, належить самому цьому користувачеві, — а межу ви встановлюєте там само, де й для кожного іншого інструмента, у своєму клієнті MCP, як описано в розділі What an assistant can do without asking you first (Що асистент може робити, не питаючи вас).
Через 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, названу без звичного префікса, буде включено до списку; файл, лише названий як вона, — ні, і він з’явиться під тим видом, який фактично оголошує. 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-адреси — наприклад, схему значень чарту з віддаленим посиланням. Зовнішні вхідні дані заморожуються на час виклику. Посилання, яке lock-файл сутності Release уже закріплює, подається зі сховища з адресацією за вмістом, тобто це читання вмісту, що вже є на диску, а не завантаження. Посилання, яке lock-файл не закріплює, відхиляється з зазначенням його назви, а не завантажується: ви просили рендер, а отримання посилання і звернулося б до мережі, і записало б blob у сховище як побічний ефект створення байтів. Це заморожування — властивість рендера. Розв’язання — це крок, який отримує: він рендерить сутність Release, щоб з’ясувати, які віддалені посилання запитує цей рендер, завантажує їх і записує їх тим самим записом lock-файлу, що містить закріплення залежностей. Тож розв’язання змінює те, які посилання закріплені на момент запуску рендера, і ніколи не змінює того, до чого рендер може звертатися, — а посилання, яке жодне розв’язання не закріпило, відхиляється у виклику, що спершу виконав розв’язання, так само, як і у виклику, що його не виконував.
Файли повертаються як ті самі байти, які видає справжнє збирання, і це забезпечують дві речі разом. Перша — описане вище заморожування: закріплене посилання читається зі сховища, а не завантажується. Друга — lock-файл, з якого відбувається читання, досі описує те, до чого розв’язується сутність Release, — тому build це перевіряє і відхиляє lock-файл, який більше не відповідає, так само, як aggrega build у терміналі. Читання закріплених байтів саме собою нічого не каже про те, чи це були правильні байти для читання.
Усі три стани lock-файлу, щоб позиція була явною. Коли lock-файлу немає взагалі, build рендерить на основі всього, що вже закріплює робочий простір, і відхиляє кожне зовнішнє посилання, яке не може подати, називаючи кожне з них; сам по собі він не вимагає lock-файлу й не записує його, і перевірка вище цього не змінює — немає lock-файлу для порівняння, тож нічого не відхиляється. Коли lock-файл відповідає, він рендерить. Коли lock-файл більше не відповідає, він відмовляє, і відмова вказує, як це виправити: викличте pull з тим самим release і без upgrade_targets, що узгоджує lock-файл із тим, до чого сутність Release розв’язується сьогодні. Відмова також містить термінальну форму тієї самої операції — aggrega pull --release <release>. Будь-який із цих викликів це виправляє; це одна операція, доступна з двох місць, а не дві інструкції, з яких треба вибирати. Якщо pull завершується, а відмова повертається знову, два виклики виконали розв’язання над різними вхідними даними — найчастіше catalog_dirs передано одному з них і не передано іншому, або конфігурацію робочого простору змінено між ними, — і відмова про це повідомляє: викличте обидва з однаковими параметрами.
validate і describe, яким передано лише release, підпорядковані тому самому lock-файлу. Якщо lock-файл більше не відповідає тому, до чого розв’язується Release, кожен із них відмовляє замість відповіді, а його текст містить зупинку через розбіжність, з якою відмовляє build, і той самий спосіб її усунути, — так само, як aggrega validate --release і aggrega inspect --closure відмовляють у терміналі. З lock-файлом, що відповідає, або без нього кожен відповідає як зазвичай.
Як попросити збирання спершу розв’язати залежності
Передайте auto_pull, і збирання виконає розв’язання перед рендером. Воно виконує те саме розв’язання, що й pull, — саму цю операцію, а не другу, написану для збирання, тож робочий простір, заповнений збиранням, і заповнений викликом pull заповнюються однаково, — записує lock-файл сутності Release, а потім рендерить на основі записаного. Цей крок звертається до реєстру і записує, чого більше ніщо в build не робить, окрім write, а write до реєстру не звертається, — тому він вимкнений, якщо його не запитано.
Це вирішує обидві відмови вище, не виходячи з протоколу. Сутність Release, яку ще ніхто не розв’язував, рендериться з тих закріплень, які випадково є, а решту відхиляє; lock-файл, що розійшовся, зупиняє збирання одразу. Передавання auto_pull спершу виконує розв’язання й рендерить на основі lock-файлу, отриманого із замикання, якого стосується це збирання, тож обидва випадки повертаються як рендер, а не як щось, що треба піти й виправити. Якщо ви хочете, щоб розв’язання й рендер були окремими кроками — щоб прочитати, що було закріплено, перед рендером, — викличте pull, а потім build: це ті самі дві операції з переглядом між ними.
Один виклик рендерить сутність Release один раз. З’ясування того, які віддалені посилання споживає сутність Release, саме є рендером, тож розв’язання вже відрендерило сутність Release, якої стосується збирання, — на основі щойно записаних закріплень, з усіма перевірками, які виконує збирання. Збирання відповідає на основі цього рендера, а не повторює його, тому передавання auto_pull коштує одного розв’язання, а не другого рендера. Так використовується лише рендер, що завершився: якщо розв’язання закріпило залежності, але не змогло завершити виявлення зовнішніх посилань, збирання рендерить самостійно на основі закріплень, які таки з’явилися, і тоді незакріплене посилання зупиняє його із зазначенням назви, а не повертається як список файлів, неповніший за те, що видає збирання.
Те, що повертається, повідомляє, що було розв’язано. Збирання, яке виконало заповнення, містить у відповіді dependency_resolution у формі, якою відповідає pull: записаний lock-файл, кожне посилання, до якого звернулося розв’язання, з версією, до якої його розв’язано, і джерелом, звідки його взяло розв’язання цього збирання, кількості, які містить lock-файл після цього, і власний звіт розв’язання рядок за рядком. Збирання, яке не виконувало заповнення, взагалі не містить такого поля, тож його наявність дає змогу розрізнити ці два випадки, не читаючи диск. Відрендерені файли повідомляються так само, як і для будь-якого іншого збирання, і досі повертаються в пам’яті, якщо виклику не передано також write, — розв’язання записує lock-файл і кеш артефактів, але ніколи не артефакт.
Робочий простір може запитати це постійно, і виклик не може цього вимкнути. Власне налаштування 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, яку вона розширює, що вказує на той самий шлях; властивість, яку сутність Component або Feature, досяжна з Release, оголошує і в стовпі 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, сформульована словами компілятора, як описано нижче в розділі Відмова, що виникла під час рендерингу, і додає одне власне поле. Рекомендаційні повідомлення в ній присутні: фази, що виконалися, повідомили те, що повідомили, і саме на ці знахідки вам слід зреагувати, щоб подолати відмову, тому вони надходять як записи, які можна зіставляти, а не як текст, який довелося б розбирати. deprecations і declined_external_inputs присутні з тієї ж причини — записаний маркер повідомляється тому, що маркер було записано, а відхилене посилання — тому, що посилання було відхилено, і жоден із цих фактів не є наслідком того, як завершився запуск.
files у разі відмови нічого не повідомляє, і це не те поле, з якого слід читати результат. Нічого не було згенеровано, тож немає артефактів, які можна назвати. Не робіть розгалуження за наявністю ключа: він повідомляється в будь-якому разі, і порожній files сам по собі не може відрізнити збірку, яку відхилено, від тієї, що виконалася й нічого не згенерувала. Читайте позначку невдачі в результаті — це власний дискримінатор протоколу — а files читайте як те, чим він є: список того, що було відрендерено, а також записано, якщо виклику було надіслано write.
Рекомендаційні повідомлення у разі відмови обмежує те, наскільки просунувся запуск, а не те, що здатна вмістити відповідь. Відмова від перевірки, що виконується до розв’язання сутності Release, — закріплений запис у кеші більше не відповідає записаному для нього дайджесту, і жоден каталог не містить закріплених байтів, або не вдалося розв’язати залежності сутності Release — не повідомляє жодних рекомендаційних повідомлень, бо ще нічого не було повідомлено. Знахідки про те, як сутність Release компонується з сутністю Release, яку вона розширює, повідомляються в момент її розв’язання, перед кожною наступною перевіркою, тому кожна пізніша відмова їх містить: Manifest зіставляє тип із recipe, який його не реалізує, сутність, до якої сягає 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 зіставляє тип із recipe, який його не реалізує, повертається як ця відмова з одним записом 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 у локальний кеш і записує lockfile цієї сутності Release. Він є на цій поверхні з причини, яку варто назвати: обидві відмови вище — рендеринг, що відхилив незакріплене зовнішнє посилання, і збірка, що зупинилася, бо lockfile більше не відповідає тому, у що розв’язується Release, — усуваються закріпленням, а асистент, якому доводиться просити вас виконати команду, не може усунути їх сам. Прочитайте Що асистент може робити, не питаючи вас, щоб дізнатися, що він записує і як далеко це сягає.
Передайте release — шлях до сутності Release, абсолютний або відносний до кореня робочого простору, за тим самим контрактом, що й кожен інший аргумент-шлях тут. workspace_root і catalog_dirs перевизначають виявлення робочого простору й каталогів так само, як у build. Обидва діють на сервері, до якого звертаються через стандартні вхід і вихід; через HTTPS ці два аргументи відхиляються, і шлях має розв’язуватися всередині робочого простору, який обслуговує процес, як описано в Один процес, один робочий простір.
Типово він узгоджує, а не розв’язує заново. Закріплення, яке lockfile уже записує, шанується й завантажується в цій версії, а якщо реєстр більше не віддає ці байти, відхиляється, а не мовчки перезакріплюється. Посилання без закріплення — щойно додане або вручну вилучене з lockfile — розв’язується заново й додається. Посилання, якого більше немає серед розв’язаних залежностей, вилучається. Тож незмінений набір залежностей залишає файл побайтово ідентичним, включно із записаною міткою часу, і виклик, що не змінив жодного закріплення, не створює жодного diff для того, хто згодом переглядатиме робочий простір.
verify порівнює й залишає lockfile як є. Він звіряє записаний lockfile з розв’язанням, яке зараз виконав би описаний вище узгоджувальний виклик, шануючи записані закріплення точно так, як той виклик, і повертає невдачу в разі розбіжності або коли немає lockfile для порівняння, — тож саме так асистент з’ясовує, чи потрібне закріплення, перш ніж щось перепише lockfile. Нічого з того, що записує той виклик, не записується — ні lockfile, ні записані поруч ідентичності плагінів, ні entity.lock, — тоді як кеш вмісту читається й заповнюється точно так, як той виклик його читає й заповнює. Він також повідомляє інструментарій, який записує lockfile: версію компілятора, що записала файл, і версію кожного основного плагіна, який містив той компілятор. Це повідомляється для аудиту й ніколи не порівнюється із запущеним бінарним файлом, бо інструментарій не належить до того, що закріплює lockfile, і перевірка його опосередковано закріпила б компілятор, — відмінність інструментарію не є розбіжністю.
upgrade_targets заново розв’язує названі вами посилання, і нічого більше. Передайте один або кілька URI сутностей у голій авторській формі — core/database, а не форму з версією. Кожне назване закріплення відкидається й заново розв’язується до найвищої доступної версії, тоді як усі інші закріплення та записані зовнішні вхідні дані лишаються незмінними. URI, що не відповідає ні записаному закріпленню, ні налаштованому приєднанню, відхиляється, а не ігнорується.
Аргументу, що заново розв’язує все одразу, навмисно немає. Командний рядок має таку форму, і вона відкидає весь lockfile перед повторним розв’язанням з поточного стану реєстру. На цій поверхні такого аргументу не існує, тож такий виклик узагалі неможливо скласти, а не прийняти й потім відхилити: за потоком протоколу ніхто не стежить, тож оптове відкидання нікому підтвердити. Якщо воно вам потрібне, то лише через стандартні вхід і вихід команду виконує cli-pull — це поверхня, де присутня людина; той, хто звертається до цього сервера через HTTP, натомість виконує її в терміналі на хості. verify не можна поєднувати з upgrade_targets — один залишає lockfile як є, а інший його переписує, — ні з pin_sources, хоч яке значення він має: цей аргумент вирішує, чи розв’язання записує закріплення, яких бракує в entity.lock, чи відхиляється через них, а порівняння не записує жодного entity.lock, тож не зробило б ні того, ні іншого. Виклик, що надсилає будь-яку з цих пар, відхиляється ще до будь-якого розв’язання з реченням, що називає пару. Оголошена схема інструмента не вказує цих двох винятків, бо клієнт, що її відображає, може сприйняти це як вимогу надсилати verify; клієнт дізнається про них із відмови. Командний рядок і демон відхиляють ті самі пари.
Результат називає, що саме розв’язано, а не лише те, що щось розв’язано. Він містить lockfile, який записав або з яким порівнював; resolved — кожне посилання, до якого дійшло розв’язання, з версією, до якої воно розв’язалося, видом, який пише автор, там, де розв’язання його записує, і його source — звідки цей запуск узяв посилання, тим словом, яке aggrega pull --detail виводить для того самого розв’язання: fetched-fresh, cache-reuse, local, in-binary або external; кількість артефактів джерел, зовнішніх вхідних даних і довірених ідентичностей плагінів, які lockfile містить після цього; і diagnostics — власний звіт розв’язання про себе в порядку, в якому воно видало кожен рядок: яке закріплення використано повторно, який підпис перевірено, яку версію пропущено як відкликану. Під час виконання команди ці рядки потрапляють у термінал; тут вони у відповіді, бо той, хто не читає термінал, не має іншого способу їх отримати. verified присутній лише при порівнянні, тож за його відсутністю можна відрізнити запуск, що записував, від запуску, що лише порівнював. source описує цей запуск на цій машині, тож lockfile його не записує, і 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, бо потік відкриває перше повідомлення, а не токен.
У потоці зчитуйте результат з останньої події, а не з коду стану. Стан і заголовки записуються під час відкриття потоку, тобто до завершення роботи, тож виклик, який повідомляє, а потім відмовляє, передає відмову як останню подію під уже надісланим станом. Закриття з’єднання посеред потоку завершує роботу, і для неї більше нічого не записується, точно як Як завершується виклик описує для кожного іншого виклику.
Через стандартне введення й виведення повідомлення є рядками перед рядком відповіді, оформленими так само, як кожне інше повідомлення в цьому потоці, — один об’єкт 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; шлях до контейнера без сегментів або з порожнім сегментом; шлях, що проходить крізь скаляр, усередину якого нічого не можна додати; шлях до колекції, записаної в потоковому стилі, де додавання переписало б уже записані автором байти замість додати рядок; або шлях, що адресує блокову послідовність чимось, що не є одним із її індексів. Якщо ви волієте, щоб редагування застосували за вас, Applying one bounded edit to a document (Застосування одного обмеженого редагування до документа) — це інструмент, який це робить.
Застосування однієї обмеженої правки до документа
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 (Імпортерові, що не оголошує шаблонів файлів, передано каталог), а каталог, що не містить жодного файлу, вибраного його шаблонами, також відхиляється. Каталог обмежується самим собою, де б він не розташовувався: посилання серед файлів, які читав би імпорт, або на каталог, що веде за його межі, відхиляється до того, як щось буде прочитано, а в посилання на каталог ніколи не заходять — як описано в A directory you import. На сервері, до якого звертаються через HTTPS, сам каталог розв’язується всередині робочого простору, тож і кожен прочитаний із нього файл теж.
Імпортер — це той, що міститься в каталозі вашого робочого простору, або один із базових імпортерів компілятора. Перетворення виконує плагін-імпортер, що оголошує формат джерела: той, що міститься в каталозі вашого робочого простору, або один із базових імпортерів компілятора, які обслуговують свої формати в кожному робочому просторі без запису в каталозі. Цей інструмент вибирає його, запускає і записує те, що він створив. Приєднання plugins.importer, чий uri називає імпортер за його ідентичністю та версією — importer/<name>:<version>, як його записує aggrega plugin add importer, — приєднує цей імпортер: якщо він оголошує формат джерела, запускається саме він, у цій версії, хоч би який інший імпортер теж оголошував цей формат, і він отримує джерела та налаштування with цього приєднання, яких не отримує жоден інший імпортер. Якщо формат оголошують кілька імпортерів і жоден із них не приєднано окремо — серед них, наприклад, базовий імпортер і імпортер з іншим іменем, що міститься у вашому каталозі для того самого формату, — виклик відхиляється з їх переліком, як описано в Configuration. Названий вами формат, якого не оголошує жоден імпортер, відхиляється з назвою можливості, яку мав би оголосити імпортер, — import:langflow для джерела Langflow, — саме її оголошує імпортер, який ви додаєте до каталогу, а не загальна невдача, яку потім доводиться тлумачити.
Базовий імпортер, якого немає на машині сервера, завантажується один раз — першим імпортом, якому він потрібен. Імпорт завантажує його з реєстру за замовчуванням обслуговуваного робочого простору, звіряє його з модулем, який публікує випуск компілятора, перевіряє його підпис згідно з політикою довіри цього реєстру та функції хоста, які він використовує, так само як pull перевіряє завантажуваний плагін, і зберігає його в кеші вмісту робочого простору, тож кожен наступний імпорт читає його звідти й не звертається до жодного реєстру. Більше для нього нічого не записується — ні lockfile, ні запису про довірені плагіни. Через HTTPS це єдиний реєстр, до якого виклик цього інструмента може змусити сервер звернутися, у межах, які Які облікові дані витрачає виклик встановлює для читання з реєстру: це реєстр за замовчуванням робочого простору, який обслуговує цей сервер, тож цей робочий простір налаштований на нього; ніщо у виклику не називає реєстр і не передає облікових даних; а завантаження використовує власний вхід і політику довіри цього хоста. Інструмент і далі звертається лише до робочого простору, тож виклику достатньо 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, яке перше витягування фіксує у файлі блокування на найвищій доступній версії. Якщо їх кілька з різними іменами, зіставляється та, що названа за самим типом, наприклад 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. Пакет підписування повідомляє кожне підписане посилання разом із дайджестом, до якого прив’язаний його підпис, у тому порядку, в якому було задано посилання, а пакет, у якому хоча б одне посилання не вдалося обробити, повертається як збій, що називає кожне таке посилання, а не як результат зі скороченим списком: саме через частковий пакет, поданий як успіх, відмову починають сприймати як проходження. Позначення застарілим повідомляє кожен маркер із його власним дайджестом, оскільки маркер прикріплюється як нетегований referrer артефакту, який він відкликає, і ніщо інше на нього не посилається. Підписування або відкликання посилання, за яким нічого не опубліковано, відхиляється, а не прикріплюється до порожнечі.
Дві частини відповіді
Кожен інструмент відповідає читабельним текстом, а поруч із ним — структурованим результатом, якщо операція його має. Текст написано для людини, яка читає розмову. Структурований результат містить ту саму відповідь у вигляді полів, які читає програма, — вердикт, список файлів, діагностику, — і відмова теж його містить, якщо на момент відмови операція мала результати перевірки, як описує Що повертає відхилена збірка для збірки.
Структурований результат також містить текст у полі 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, коли хочете, щоб AI-асистент допомагав створювати сутності Aggrega за справжніми схемами й довідкою, — тоді його пропозиції спираються на точну структуру, яку приймає компілятор, а не на здогадки. Це безпосередньо вписується в цикл створення: асистент читає схему й довідку типу, створює заготовку, заповнює поля, за які відповідає ваша роль, і виконує валідацію, перш ніж повернути чернетку. Опис цього циклу див. у розділі Написання файлів Aggrega.
Через стандартне введення й виведення вам зазвичай не доводиться самостійно вводити aggrega mcp. Натомість ви один раз вказуєте її в MCP-конфігурації свого клієнта, і клієнт запускає та зупиняє її за вас. Слухач — інший випадок: тут процес запускаєте ви, і він продовжує працювати для викликачів, які його не запускали.
Приклад: конфігурація клієнта через стандартні введення та виведення
Спрямуйте клієнт MCP на цю команду за допомогою запису сервера stdio:
{ "mcpServers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}Єдина передумова — встановлений двійковий файл aggrega у PATH клієнта. Шляхи до конфігурації для окремих клієнтів і усунення несправностей див. у розділі Підключення сервера MCP. Щоб отримати схему безпосередньо з командного рядка без клієнта, див. aggrega get-schema.