콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

aggrega mcp

AI 도우미 통합을 위해 표준 입출력 또는 HTTP를 통해 Model Context Protocol 서버 실행

개요

aggrega mcp [flags]

설명

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

플래그

플래그기본값설명
--listen—HTTP 전송이 수신 대기하는 주소이며, host:port 또는 unix: 뒤에 파일 시스템 경로가 오는 두 가지 형식 중 하나입니다. 수신 대기할 위치만 지정하고 전송 방식은 선택하지 않습니다. —transport http 또는 워크스페이스 구성의 mcp.transport: http와 함께 읽히며, stdio 전송과 함께 지정하면 거부됩니다. 인증서가 없는 리스너는 평문으로 제공되며 루프백(127.0.0.1, ::1, localhost) 또는 Unix 소켓에서만 허용됩니다. 이는 종단 프록시 뒤에 있는 서버가 취하는 형태입니다. 그 밖의 주소에는 mcp.tls.cert_file과 mcp.tls.key_file이 필요하며, 이 프로세스는 이를 사용해 직접 TLS를 종단합니다. 설정하면 mcp.listen 구성 키를 재정의합니다.
--transport—서버에 도달하는 방식입니다. stdio는 표준 입출력을 통해 프로토콜을 주고받으며, 이 명령을 하위 프로세스로 실행하는 클라이언트가 서버에 도달하는 방식입니다. http는 —listen 또는 mcp.listen이 지정하는 주소에서 HTTP로 프로토콜을 제공하며, mcp.tls가 인증서와 키를 지정하면 HTTPS로 제공합니다. 설정하면 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를 처음부터 구성하기, 기존 차트·인프라 모듈·컨테이너 compose 파일을 Aggrega로 가져오기, 빌드가 컴파일되지 않거나 잘못된 아티팩트를 렌더링하는 이유 파악하기 등입니다. prompts/list는 두 계열을 모두 나열하고 prompts/get은 하나를 렌더링하므로, 목록은 이 페이지가 아니라 서버에서 읽습니다.

    워크플로 프롬프트는 호출을 지정하고, 호출은 사용자가 하나씩, 각 결과를 읽은 뒤 다음 호출을 합니다. 목표 전체를 수행하는 호출은 없습니다. 각 도구는 확인할 수 있는 하나의 작업을 감싸므로, 목표에 도달하게 하는 것은 순서입니다. 작성 페르소나는 초점을 맞출 kind를 선택적으로 받고, 엔터티별 템플릿은 이를 필수로 받으며, 어떤 스키마에도 해당하지 않는 kind는 조용히 무시되지 않고 허용되는 값 목록과 함께 거부됩니다.

  • 리소스 — 인라인으로 제공되는 읽기 전용 참조 자료입니다. 엔터티의 JSON Schema에는 schema://<kind>, 모든 언어 참조 페이지에는 langref://<path>, 작성 가이드에는 authoring://<topic>, 카탈로그 엔터티의 작성된 YAML에는 catalog://<kind>/<name>, 명령의 도움말에는 cli://<command>를 사용하며, cli://만 쓰면 그 진입점입니다. 이 도움말은 서버 자체에 포함된 명령에서 응답되므로, 읽어도 프로세스가 시작되지 않으며 명령이 --help에 출력하는 것과 같은 텍스트를 반환합니다. 카탈로그에 없는 엔터티에 대한 catalog:// 읽기는 찾을 수 없음으로 응답합니다. 그 이유가 해당 엔터티를 선언하는 카탈로그 파일 정확히 하나가 로드 시 건너뛰어졌기 때문이라면, 응답 메시지는 URI만이 아니라 그 파일, 그 파일이 위반하는 제약, 그 조건의 짧은 코드를 제시합니다. 이는 같은 파일에 대해 aggrega build가 맨 앞에 내놓는 거부입니다. resources/list는 매개변수 없이 지정할 수 있는 리소스를 나열하고 resources/templates/list는 모든 계열의 URI 형태를 알립니다.

  • 도구 — 워크스페이스에 대한 작업이며, tools/list가 그 전체로 응답합니다.

    어시스턴트가 처음 만나는 도구들은 작성 루프에 맞춰져 있습니다. 워크스페이스에 무엇이 있는지 알아보는 list-entities와 list-releases, 해당 종류가 요구하는 필드를 담고 값이 필요한 곳마다 자리 표시자를 둔 골격을 만드는 scaffold(또는 example을 보내면 문서의 실행 가능한 예제 하나를 새 디렉터리에 기록하고 그 디렉터리의 위치, 기록한 파일, 그것을 빌드하는 명령으로 응답하며, list: true를 보내면 예제 목록을 보여 줍니다), 엔터티의 JSON Schema를 가져오는 get-schema, 초안을 검증하는 validate(초안에 아직 남아 있는 모든 자리 표시자와 각각에 들어갈 값을 알려 줍니다), 카탈로그 엔터티 또는 참조로 레지스트리에서 읽은 엔터티를 설명하는 describe, Release의 의존성을 로컬 캐시로 해석하고 잠금 파일을 작성하는 pull, Release를 렌더링된 아티팩트로 빌드하는 build(기본적으로 메모리 안에서 빌드하며 디스크에 아티팩트를 쓰지 않고, write를 보내면 aggrega build가 쓰는 위치인 워크스페이스 루트의 dist/에 기록합니다. 의존성은 auto_pull을 보낸 경우에만 먼저 해석됩니다), Wasm 게스트에서 Plugin 엔터티를 생성하는 gen-catalog, 그리고 컴파일러 진단을 실행 가능한 안내로 확장하는 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 ""를 읽는 것처럼 읽습니다. 즉 서버가 시작된 디렉터리에서 워크스페이스를 찾습니다. 둘 다 없이 시작된 서버는 루트를 넘기지 않으므로, 그 명령들은 Which workspace a call is answered in에서 모든 도구에 대해 설명하는 규칙에 따라 그 디렉터리에서 워크스페이스를 찾습니다. 단, 데스크톱 번들이 Workspace folder 설정을 비운 채 실행한 경우는 예외로, 자체 워크스페이스를 지정하지 않은 호출은 명령을 시작하지 않고 그 설정에 대한 거부로 응답받습니다. 명령은 호출 또는 실행이 지정한 워크스페이스 루트에서 시작합니다. 즉 호출 자체의 workspace_root를 모든 도구가 읽는 방식대로 읽어(절대 경로는 보낸 그대로, 상대 경로는 루트를 지정하지 않은 호출이 응답되는 루트를 기준으로) 그 절대 경로 형태로 명령에 넘기며, 없으면 서버가 시작될 때 지정된 루트를 사용합니다. 따라서 호출이 읽을 파일로 전달하는 상대 경로, 예를 들어 validate할 문서나 --release, --catalog는 그 워크스페이스에서 연 터미널에서처럼 그 워크스페이스 안에서 읽히고, 명령이 실행하는 빌드는 그 루트 아래에 dist/를 씁니다. 아무것도 루트를 지정하지 않는 경우, 즉 실행 루트도 없고 workspace_root도 없거나 비어 있는 경우, 명령은 서버가 시작된 디렉터리에서 시작하고 상대 경로를 그곳에서 읽습니다. 존재하지 않는 폴더를 지정하는 workspace_root는 읽힌 그대로(절대 경로는 보낸 그대로, 상대 경로는 전체 형태로) 전달되며, 명령이 자체 메시지로 이를 거부합니다. 명령 확장 플러그인이 등록한 명령에는 이 중 어느 것도 넘겨지지 않습니다. 그 명령은 터미널에서와 마찬가지로 여기서도 전역 플래그를 파싱하지 않고 모든 인수를 읽지 않은 채 플러그인에 전달하기 때문입니다. 그 명령도 다른 모든 명령과 같은 폴더에서 시작합니다.

    몇몇 명령은 명령 도구가 존재하는 표준 입력과 출력에서도 의도적으로 제외됩니다. HTTP에서는 명령 도구가 모두 없으며, 이는 어떤 명령의 특성이 아니라 전송 방식의 특성입니다. 표준 입력과 출력에서는 다음 명령들이 각각 명시된 이유로 제외됩니다. 데몬과 이 서버 자체는 결과를 돌려주지 않습니다. 터미널에서 비밀번호를 읽는 명령은 읽을 곳이 없습니다. 셸 자동 완성 스크립트를 쓰는 명령은 설치할 셸이 없습니다. 저장된 자격 증명을 제거하는 명령은 지정한 워크스페이스가 아니라 머신 전체의 저장소에 작용합니다. 대화형으로 ID 토큰을 발급받는 명령은 제공할 비대화형 형태가 없습니다. 같은 머신 전체라는 이유로 aggrega plugin run-local도 제외됩니다. 이 명령은 지정한 경로에서 .wasm 게스트를 로드합니다. 이 명령의 목적이 파일을 어디에 두든 읽는 것이므로 제한할 수 있는 워크스페이스가 없으며, 읽기는 게스트가 존재하기 전에 프로세스 자체에서 일어납니다. 게스트는 실행될 때 아무것도 부여받지 않지만(디렉터리, 소켓, 환경 모두 없음), 이는 읽기가 아니라 모듈에 대한 제한이므로 이 결정의 근거가 아닙니다. 경로를 직접 지정하는 터미널에서 실행하십시오. 서명과 게시는 전혀 다른 경우이며, 그 차이 때문에 이 목록에 포함되지 않습니다. 각각은 제공된 입력이나 주변 환경의 입력에서 ID를 확인하고, 사용할 수 있는 것이 없으면 명시적으로 거부하므로, 지켜보는 사람 없이도 완료되는 형태가 있습니다. 반면 대화형으로 토큰을 발급받는 것은 원칙적으로도 어떤 입력으로도 충족할 수 없는 동작입니다. 그래서 서명과 게시는 명령으로서, 그리고 Publishing, signing and withdrawing에서 설명하는 네 가지 프로세스 내 도구로서 두 번 제공됩니다. 명령줄이 브라우저를 열게 되는 경우, 이 도구들은 자리에 없는 사람을 기다리는 대신 거부하고 대신 제공해야 할 것을 알려 줍니다.

호출이 응답되는 워크스페이스

호출은 workspace_root로 자신의 워크스페이스를 지정하며, 지정하지 않으면 서버가 시작된 워크스페이스에서 응답됩니다. 실행 시 --workspace-root 또는 AGGREGA_WORKSPACE_ROOT로 루트를 지정한 경우, 모든 명령에서 이 플래그가 그렇듯 그 루트가 곧 워크스페이스 루트입니다. 그 위로는 상위 워크스페이스를 찾지 않으므로, 실행 시에는 워크스페이스의 .aggrega-config.yaml이 있는 폴더를 지정해야 하며, 호출은 서버 내부에서 실행되는 도구와 명령 도구 모두에서 그곳에서 응답됩니다. 실행 시 루트를 지정하지 않은 경우, 워크스페이스는 서버가 시작된 디렉터리에서 찾으며, 이는 그 디렉터리의 터미널에서 입력한 명령이 워크스페이스를 찾는 방식과 정확히 같습니다. 그 순서는 프로젝트 루트를 인식하는 다른 방법에 설명되어 있습니다. 단, 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 설정이 비어 있는 데스크톱 실행도 같은 방식으로 거부로 제공됩니다. 데스크톱 번들은 항상 Workspace folder의 값을 담은 AGGREGA_WORKSPACE_ROOT를 서버에 전달하고 그와 함께 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_BUNDLE_VERSION이 없는 실행의 빈 AGGREGA_WORKSPACE_ROOT, 빈 값으로 입력한 --workspace-root, 리스너, aggrega serve 및 그 밖의 모든 명령은 각각 이를 설정되지 않은 것으로 읽습니다.

워크스페이스를 찾지 못했고 지정되지도 않은 경우, 워크스페이스에 관한 응답은 어떤 폴더를 사용했는지 알려 줍니다. 실행 루트가 없고, 호출에 workspace_root가 없으며, 호출이 응답된 폴더에서 워크스페이스를 고정하는 것이 없으면, 호출은 그 폴더에서 응답됩니다. 도구의 결과가 워크스페이스에 따라 달라지는 경우(명령줄에서 명령이 경고를 표시하는 바로 그 도구들), 그 텍스트는 명령줄의 경고인 <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace와, 워크스페이스의 .aggrega-config.yaml이 있는 폴더를 가리키는 workspace_root를 보내라고 안내하는 한 줄로 끝납니다. 구성 읽기나 플러그인 목록처럼 워크스페이스가 결정하지 않는 응답은 워크스페이스에 대해 아무것도 말하지 않습니다. 이 문장은 구조화된 결과에 별도의 필드를 추가하지 않습니다. 응답의 두 부분에서 설명하듯, 구조화된 결과는 텍스트를 담는 text_answer에 이 문장을 담습니다. 별도 프로세스에서 명령을 실행하는 도구는 같은 내용을 말하는 명령 자체의 줄을 명령이 출력한 그대로 담습니다. 그러한 폴더에서는 아티팩트 캐시에 아무것도 쓰이지 않습니다. 그곳에서의 pull, 또는 먼저 의존성을 해석하도록 요청된 빌드는 무엇이든 가져오기 전에 거부되며, 해당 폴더와 두 가지 해결 방법(workspace_root를 보내거나, 폴더에 workspace: 블록을 담은 .aggrega-config.yaml을 두는 것)을 밝힙니다. pin, 또는 Recipe나 FeatureRecipe의 게시도 엔터티가 전체를 기술하는 원격 소스를 가져오려는 경우(이를 pin하거나 pin을 비교하기 위해) 그 소스를 가져오기 전에 같은 방식으로 거부됩니다. 엔터티에 소스가 없거나, 로컬 소스이거나, 좌표를 각 Release가 채우는 소스여서 아무것도 가져오지 않는 경우에는 다른 곳에서와 같이 응답됩니다. 그곳에서 먼저 아무것도 해석하지 않는 빌드는 여전히 렌더링하지만, lockfile이 pin하고 캐시에 더 이상 없는 외부 입력은 다시 가져오지 않습니다. 렌더링에는 오프라인 상태일 때처럼 입력 대신 같은 문장이 전달됩니다. HTTP를 통한 응답에는 이 문장이 포함되지 않습니다. 리스너는 항상 주어지거나 찾은 워크스페이스를 제공하기 때문입니다. Workspace folder 설정이 비어 있는 데스크톱 번들의 실행도 마찬가지로, 자신의 워크스페이스를 지정하지 않은 호출을 시작된 폴더에서 응답하지 않고 거부합니다.

절대 경로로 지정한 Release나 문서에 관한 호출은, 다른 무엇으로도 워크스페이스가 정해지지 않았을 때 그 파일 자신의 워크스페이스에서 응답됩니다. 실행 시 루트를 지정하지 않았고, 호출이 workspace_root를 보내지 않았으며, 서버가 시작된 디렉터리가 어떤 워크스페이스의 기준도 되지 않는 경우, 워크스페이스는 그 파일이 있는 폴더에서 다시 탐색되며, 그 탐색이 찾아낸 것 — 파일이 속한 프로젝트, 또는 아무것도 찾지 못하면 그 폴더 — 이 호출이 응답되는 워크스페이스가 됩니다. 이는 터미널에서 입력한 명령이 따르는 규칙과 같으므로, 호출이 지정한 Release나 엔터티 문서에 관한 모든 도구에 적용됩니다. 빌드, pull, 검증, lint, 설명, Release 기준의 목록 조회, Release 그래프의 노드에 관한 질의, 고정(pin), 엔터티 게시, 편집, 문서 내 위치 읽기가 이에 해당합니다. 호출이 Release와 문서를 모두 지정하면 Release가 결정합니다. 따라서 프로젝트 밖에서 서버를 실행한 클라이언트라도 그 안의 Release는 프로젝트 자체의 구성으로 빌드됩니다. 호출이 지정하는 그 밖의 경로는 항상 그렇듯 읽히며 — 상대 경로는 서버가 시작된 디렉터리를 기준으로 합니다 — 별도 프로세스에서 명령을 실행하는 도구도 같은 워크스페이스에서 응답됩니다. 명령이 같은 디렉터리에서 같은 규칙을 따르기 때문입니다. 실행 시 지정한 루트, 호출이 보내는 workspace_root, 그 자체로 워크스페이스 안에 있는 시작 디렉터리, 그리고 상대 경로로 지정한 Release나 문서는 있는 그대로 사용됩니다. HTTP에서는 이런 상황이 생기지 않습니다. 리스너는 항상 주어졌거나 찾아낸 워크스페이스를 제공하며, 호출이 지정하는 모든 경로는 그 워크스페이스를 기준으로 합니다. Workspace folder 설정이 비어 있는 데스크톱 번들의 실행에서도 생기지 않습니다. 이 경우 자체 워크스페이스를 지정하지 않은 호출은 어떤 파일을 지정하든 거부됩니다.

서버가 알리는 범위 좁히기

mcp.announce_tools는 이 서버가 알리는 도구를 도구 목록이 보고하는 철자 그대로 지정합니다. 키를 생략하면 이 서버가 가진 모든 도구가 알려지며, 이것이 기본값이자 프로토콜을 따르는 클라이언트가 기대하는 형태입니다. 목록을 작성하면 정확히 그 도구들만 알려집니다. 목록에서 빠진 도구는 도구 목록에도, describe-capabilities의 응답에도 나타나지 않으며, 그래도 이름으로 호출하면 이 설정을 명시한 거부로 처리됩니다. 빈 목록을 작성하면 아무것도 알려지지 않습니다. 따라서 키를 생략하는 것과 []를 작성하는 것은 서로 다른 의미이며, 이 설정에는 자동으로 채워지는 기본값이 없습니다.

반대편 클라이언트가 등록할 도구 수에 상한을 두는 경우에 설정하십시오. 이 상한은 때로 클라이언트가 동시에 연결된 모든 서버에 걸쳐 적용됩니다. 그리고 그 클라이언트에 필요한 도구를 지정하십시오. 이 설정은 바로 그런 상한을 위해 존재하며, 상한이 적용되는 클라이언트는 대개 자신의 표준 입력과 출력으로 이 서버를 실행한 클라이언트입니다. 따라서 http 전송이 시작하는 리스너를 구성하는 mcp 블록의 나머지 키와 달리, 이 키는 서버가 어떤 전송을 사용하든 읽힙니다.

이 설정은 알리는 범위를 좁힐 뿐 그 이상은 하지 않습니다. 여기에 도구를 지정해도 아무것도 넓어지지 않습니다. 기능을 완전히 철회하는 mcp.deny_reach를 해제하지 않으므로, 그 설정이 철회하는 종류의 도구는 여기에 지정되더라도 목록에서 빠진 채로 남고 그 설정을 명시한 거부로 처리됩니다. 호출자의 토큰이 가진 스코프도 해제하지 않습니다. 여기에 지정된 도구는 스코프와 관계없이 목록에 표시되지만, 스코프가 허용하지 않는 호출은 여전히 거부되며 허용에 필요한 스코프가 명시됩니다. 어느 경우든 호출자가 받는 거부는 이 설정이 아니라 다른 제한에서 비롯된 것입니다. 이 설정에 의한 거부에는 챌린지가 없고 스코프도 명시되지 않습니다. 어떤 자격 증명도 서버가 제공하기로 선택한 내용을 바꾸지 못하기 때문입니다. 대신 거부는 이 설정을 명시하며, 거부를 읽는 사람이 조치할 수 있는 것은 이 설정뿐입니다.

모든 이름은 이 바이너리가 가진 도구여야 합니다. 어떤 도구에도 해당하지 않는 이름은 서버가 아무것도 제공하기 전에 서버를 중지시키며, 거부에는 서버가 가진 도구 목록이 표시됩니다. 따라서 철자 오류는 요청한 것보다 조용히 좁아진 범위로 나타나는 대신 시작 시점에 드러납니다. 별도 프로세스에서 aggrega 명령을 실행하는 cli- 계열의 이름은 두 전송 모두에서 허용되지만, HTTP에서는 아무것도 알리지 않습니다. HTTP에서는 애초에 그런 도구가 어떤 호출자에게도 제공되지 않기 때문입니다.

알리는 도구 집합은 프로세스가 시작될 때 고정됩니다. 따라서 변경하려면 재시작해야 하며, 이미 연결된 클라이언트에서 목록이 늘어나는 일은 없습니다.

서버가 어느 릴리스에서 온 것인가

인수 없이 보낸 describe-capabilities는 이 서버가 어느 릴리스에서 온 것인지 알려 줍니다. 구조화된 응답에는 server_version이 담기며, 이는 aggrega 실행 파일이 스스로 보고하는 버전, 즉 같은 파일에 대해 aggrega version이 출력하는 버전입니다. 텍스트는 인덱스 앞에 그 버전을 밝히는 한 줄로 시작합니다. 구조화된 응답은 같은 줄을 version_summary로 한 글자도 다르지 않게 담으므로, 모델에 구조화된 응답만 넘기는 클라이언트도 그 줄을 함께 넘기게 됩니다.

데스크톱 번들이 서버를 실행한 경우, 같은 응답은 그 옆에 번들의 버전도 밝힙니다. 번들에는 프로그램이 들어 있지 않습니다. 번들은 Path to the aggrega executable 설정이 가리키는 aggrega 실행 파일(기본값은 명령 이름 aggrega이며, 애플리케이션이 자신의 PATH에서 찾습니다)을 실행할 뿐이므로, 번들과 실행 파일은 따로 설치되며 서로 다른 릴리스에서 올 수 있고, 번들을 나열하는 애플리케이션은 번들 자체의 버전만 보여 줍니다. 번들은 환경 변수 AGGREGA_BUNDLE_VERSION으로 서버에 자신의 버전을 넘기고, 서버는 시작할 때 이를 한 번 읽으며, 응답은 이를 bundle_version으로 담습니다. 두 값은 쓰인 그대로 비교됩니다. 한 릴리스의 번들과 실행 파일에는 같은 형식으로 그 릴리스의 버전이 찍히고, 개발 빌드는 어떤 릴리스와도 다르게 읽히므로 이는 공정한 비교입니다. 두 값이 같으면 그 줄은 둘 다 밝히고 그 이상은 말하지 않습니다. 다르면 그 줄은 둘 다 밝히면서 실행 파일과 번들이 서로 다른 릴리스에서 왔다고 말하고, 서버가 연결 시 모델에 제공하는 안내도 같은 문장으로 시작하므로, 모델은 묻기 전에 그 차이를 알게 됩니다.

번들이 실행하지 않은 서버는 자신의 버전만 보고합니다. 터미널에서, 편집기 구성에서, 또는 리스너로 시작된 서버는 환경에 그 변수를 설정하는 무언가가 없는 한 bundle_version을 담지 않습니다. 표준 입출력으로 동작하면서 그 변수를 가진 서버는 한 가지 점에서 더 번들이 실행한 것으로 간주됩니다. 루트가 지정되지 않으면 호출이 어느 워크스페이스에서 응답되는가에서 설명하듯 빈 Workspace folder 설정을 거부합니다. kind나 tools를 보낸 describe-capabilities 호출은 서버가 아니라 도구에 대해 답하므로 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는 바인딩 전에 거부되며, 거부 메시지는 둘 다를 언급합니다. 전송 방식이 stdio인 상태에서 입력한 --listen도 거부됩니다. 이는 --transport stdio로 입력했든, mcp.transport: stdio로 구성했든, 기본값으로 두었든 마찬가지이며, 거부 메시지는 해당 주소에서 서비스할 플래그로 --transport http를 안내합니다. 빈 값이 주어진 --listen은 전송 방식과 관계없이 주소를 지정하지 않은 것으로 거부됩니다. 그리고 구성에서만 지정한 주소는 자신의 스트림으로 통신하는 서버에서 사용되지 않으며, 서버는 오류 스트림에 그 사실을 한 줄로 알리면서 주소를 설정한 파일과 mcp.transport: http를 언급합니다. 이 마지막 경우는 의도적으로 어디에서도 거부되지 않습니다. 구성에 리스너 설정이 있는 디렉터리에서 클라이언트가 명령을 시작할 때 이루어지는 실행이기 때문이며, transport: http를 빠뜨린 리스너 구성은 리스너를 전혀 시작하지 않으므로 그 시점에서 문제가 드러납니다.

HTTP로 연결한 서버는 별도 프로세스에서 aggrega 명령을 실행하는 도구를 제공하지 않습니다. 이러한 도구는 표준 입력과 출력으로 이 서버를 실행한 클라이언트에게만, 그리고 그 클라이언트 자신의 머신에서만 존재합니다. 그곳에서는 폴더나 플래그를 지정해도 호출자가 이미 갖지 않은 권한이 주어지지 않습니다. HTTP로 서버에 연결하는 호출자는 서버가 실행되는 호스트의 소유자가 아니므로, 서버 자신의 권한으로 그 호스트의 파일 시스템에 작용하는 명령은 대신 호스트의 터미널에서 실행합니다. 이 도구들은 제공된 뒤 거부되는 것이 아니라 목록과 describe-capabilities에서 아예 빠져 있으며, 이 중 하나를 지정한 호출에는 그 사실을 알리는 오류로 응답합니다. 이는 설정이 아니라 전송 방식의 속성이며, 이 도구들을 되살리는 구성은 없습니다.

배포하기 전에 자격 증명 없이는 아무것도 제공되지 않음을 읽으십시오. 엔드포인트에 대한 모든 요청에는 자격 증명이 있으며, 자격 증명 없는 요청을 처리하는 설정은 없습니다. 설정으로 선택하는 것은 이 서버가 베어러 토큰을 직접 확인할지, 아니면 앞단의 프록시가 이미 확인한 호출자를 읽을지입니다.

두 가지 배포 형태

프로세스가 직접 TLS를 종료합니다. mcp.tls.cert_file을 PEM 인증서 체인으로, mcp.tls.key_file을 그 개인 키로 설정하면 리스너는 지정한 주소에서 HTTPS를 직접 제공합니다. 두 파일은 프로세스가 시작될 때 읽히므로, 교체한 인증서는 프로세스를 다시 시작해야 적용됩니다. 둘 중 하나만 설정하면 대체 동작 없이 시작 시 거부됩니다. 키 없는 인증서는 제시할 수 없고 인증서 없는 키는 아무것도 가리키지 않으며, 경로 하나의 오타가 암호화되지 않은 트래픽을 제공할 이유가 되지는 않습니다.

앞단의 프록시가 TLS를 종료하고 제한된 리스너로 전달합니다. 두 키를 모두 설정하지 않으면 리스너는 평문을 제공하며, 이는 루프백이나 Unix 소켓에서만 허용됩니다. 따라서 해당 호스트에 있지 않은 것은 리스너에 도달할 수 없습니다. 이것이 리버스 프록시, 사이드카 또는 서비스 메시가 사용하는 형태이며, 인증서가 이 프로세스 안이 아니라 앞단에 있는 형태입니다.

그 밖의 주소에서의 평문 리스너는 바인딩 전에 거부되며, 거부 메시지는 두 TLS 키를 모두 언급합니다. 이를 해제하는 설정도, 예외가 되는 주소도 없습니다. 자체 인증서 없이 네트워크에서 연결을 받는 리스너는 결코 안전하지 않으므로, 프로세스는 그런 형태로 시작하는 대신 시작을 거부합니다.

주소 형식

--listen과 mcp.listen은 두 가지 형식 중 하나를 받습니다.

  • host:port — 127.0.0.1:7777이나 0.0.0.0:8443과 같은 TCP 주소입니다. 루프백은 127.0.0.1, ::1, 또는 그 이름이 해석되는 모든 주소가 루프백 주소인 경우의 localhost를 뜻합니다. 그 밖의 것은 모두 네트워크 주소이며 인증서가 필요합니다. 머신의 모든 인터페이스를 뜻하는 빈 호스트, 특정 인터페이스 주소, 그리고 그 밖의 모든 이름이 여기에 해당하며, 지금 이 순간 루프백 주소로 해석되는 이름도 마찬가지입니다. 리스너가 바인딩할 수 있는 위치는 도중에 바뀔 수 있는 이름 해석에 좌우되어서는 안 되기 때문입니다.
  • unix: 뒤에 파일 시스템 경로 — unix:/run/aggrega/mcp.sock과 같은 Unix 도메인 소켓입니다. 소켓은 그것이 있는 호스트에서만 연결할 수 있으므로 인증서가 필요하지 않습니다.

소켓 경로는 상대 경로를 포함하여 적힌 그대로 사용됩니다. 같은 주소가 선언 파일이 없는 --listen에서도 오기 때문에, 이를 선언한 구성 파일을 기준으로 의도적으로 해석하지 않습니다. 상대 경로가 가리키는 위치를 참조하십시오.

리스너가 받아들이는 것

POST를 받아들이는 엔드포인트 /mcp 하나입니다. 모든 JSON-RPC 메시지는 각각 독립된 요청이며 어떤 종류의 세션도 유지되지 않습니다. 클라이언트가 먼저 보낸 어떤 것도 이후 요청에 대한 응답 방식을 결정하지 않고, 세션 식별자는 결코 발급되지 않으며, 클라이언트가 보내는 세션 헤더나 스트림 재개 헤더는 무시됩니다. 이 엔드포인트에 대한 다른 메서드에는 Allow: POST와 함께 405로, 다른 경로에는 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으로 응답받습니다. 1분 안에 requests_per_minute개를 넘게 보내는 호출자에게는 429로 응답하며, 이는 해당 호출자에게만 집계되므로 한 호출자가 요청을 많이 보내도 다른 호출자에게는 아무런 영향이 없습니다. 각 한도의 기본값은 구성 레퍼런스에서 해당 키 옆에 명시되어 있으며, 어느 한도에도 이를 끄는 값은 없습니다.

프로세스 하나, 워크스페이스 하나

서비스 중인 프로세스가 응답하는 워크스페이스는 시작할 때 고정됩니다. --workspace-root가 이를 지정하며, 플래그가 없으면 AGGREGA_WORKSPACE_ROOT 변수가 이를 제공합니다. 지정된 폴더가 곧 워크스페이스 루트이며 그 위는 탐색하지 않습니다. 존재하지 않는 폴더는 거부되며, 거부 시 둘 중 어느 쪽이 그 값을 제공했는지 밝히고 주어진 값을 그대로 인용합니다. 리스너는 바인딩하기 전에 거부하고, 표준 입출력 서버는 해당 워크스페이스에서 동작하는 모든 호출에 대한 응답에서 거부합니다. 이는 호출이 어느 워크스페이스에서 응답되는가에서 설명합니다. 따라서 직접 입력하지 않고 클라이언트가 구성한 실행이라도 무엇을 전달받았는지 알려 줍니다. 둘 다 없으면 표준 입출력 서버는 자신이 시작된 디렉터리에서 워크스페이스를 결정합니다. 그곳에 워크스페이스를 고정하는 것이 없으면 워크스페이스에 관한 각 응답이 어느 폴더를 사용했는지 알려 주며, 데스크톱 번들이 Workspace folder 설정을 비워 둔 채 실행되면 자체 워크스페이스를 지정하지 않은 호출을 대신 거부합니다. 이는 호출이 어느 워크스페이스에서 응답되는가에서 설명합니다. 리스너는 그곳에서 워크스페이스가 결정되지 않으면 바인딩하기 전에 거부됩니다. HTTP로 접근하는 프로세스는 그 머신을 볼 수 없는 호출자에게 응답하므로, 우연히 시작된 디렉터리가 아니라 운영자가 선택한 워크스페이스를 서비스합니다. 여러 프로젝트를 서비스하려면 프로젝트 루트마다 프로세스를 하나씩 실행합니다.

HTTP로 도착한 호출은 자체 워크스페이스를 지정할 수 없습니다. workspace_root와 catalog_dirs는 조용히 무시되지 않고, 전송된 인수를 밝히며 거부됩니다. 조용히 무시된 인수는 보낸 쪽에게 받아들여진 인수와 똑같아 보이기 때문입니다. 서비스 중인 워크스페이스 옆에서 탐색되는 카탈로그 디렉터리는 그 워크스페이스 자체의 workspace.catalog_dirs 설정이며, workspace.releases 아래에서 자체 디렉터리를 지정한 Release의 경우 그 Release의 설정입니다. 이는 운영자가 작성합니다. 표준 입출력에서는 두 인수가 모두 받아들여집니다. 서버를 실행한 클라이언트가 호출자 자신의 머신에서 실행되기 때문입니다. 이때 catalog_dirs 항목은 절대 경로이거나, 상대 release를 읽어 들이는 워크스페이스 루트에 대한 상대 경로입니다. 이 루트는 호출 자체의 workspace_root, 실행 설정, 또는 서버가 시작된 디렉터리가 먼저 결정한 루트이며, 절대 경로로 지정된 Release가 호출을 그 Release 자체의 워크스페이스로 옮기는 경우에도 계속 이 루트를 기준으로 읽습니다. 서버가 실행되는 디렉터리가 다른 곳이라면 그 디렉터리를 기준으로 하지 않습니다.

호출이 지정하는 경로 역시 해당 워크스페이스 안에 머뭅니다. HTTP에서 경로 인수는 워크스페이스 루트를 기준으로 결정되며, 그 밖으로 벗어나면 거부됩니다. 워크스페이스 밖으로 올라가는 상대 경로, 다른 곳을 가리키는 절대 경로, 워크스페이스 안에 있는 파일이나 디렉터리 링크를 통해 워크스페이스 밖으로 이어지는 상대 경로는 모두 인수를 밝히는 실패로 돌아오며, 워크스페이스 루트나 그 경로가 도달했을 위치는 밝히지 않습니다. 상대 경로는 보낸 그대로 인용됩니다. 모든 경로 인수는 도구가 읽든 쓰든 워크스페이스 경계가 정하는 안쪽의 정의에 따라 그 경로가 이어지는 곳으로 판단됩니다. gen-catalog가 출력을 쓰는 디렉터리, edit-document가 다시 쓰는 문서, pin이 잠금을 옆에 쓰는 엔터티도 도구가 읽는 문서와 똑같이 판단됩니다. 따라서 워크스페이스 밖으로 이어지는 링크 아래의 아직 만들어지지 않은 경로는 그 링크와 마찬가지로 거부되며, 아무것도 읽거나 쓰지 않습니다. 서비스 중인 워크스페이스의 구성이 build.authoring_release 또는 workspace.releases의 키로 지정하는 Release를 가리키는 release는 그 구성을 통해 도달하므로, 파일이 어디에 있든 링크를 통해서도 받아들여집니다. 다른 인수에는 이러한 예외가 없습니다. 의도한 경로가 워크스페이스 안에 있지만 절대 경로로 작성된 경우, 거부 응답이 대신 보낼 루트 기준 상대 표기를 알려 줍니다. 따라서 잘못된 형식을 추측한 호출자는 틀렸다는 사실만이 아니라 올바른 형식을 안내받습니다. 이는 호출이 대상으로 지정하는 경로(검증할 문서, 빌드할 Release, 생성 결과를 쓸 디렉터리)에 적용되며, 도구가 읽는 경로뿐 아니라 쓰는 경로에도 똑같이 적용됩니다. 네트워크로 서버에 접근하는 호출자는 볼 수 없는 머신에 파일을 읽고 쓰도록 요청하는 것이며, 운영자가 선택한 워크스페이스가 그 읽기와 쓰기가 머무는 곳입니다. 표준 입출력에서는 각 도구의 경로 인수가 아래 해당 도구 항목에서 설명하는 계약을 따르며, 경로는 절대 경로일 수 있고 워크스페이스 밖을 가리킬 수도 있습니다. 호출하는 사람이 서버가 실행되는 머신의 소유자이므로, 스스로 선택한 디렉터리에 가두어도 얻는 것이 없기 때문입니다. 동작 자체가 워크스페이스에 있는 문서에 대해서만 응답하는 두 도구 insertion-point와 edit-document는 두 전송 방식 모두에서 이를 유지하며, 워크스페이스 밖의 문서는 그렇게 작성되었든 밖으로 이어지는 링크를 통해 도달했든 거부합니다. 표준 입출력에서 받아들여지는 것은 호출이 지정한 경로뿐이며 그 이상은 아닙니다. 그 후 동작이 자체적으로 읽고 쓰는 것은 두 전송 방식 모두에서 같은 명령을 터미널에 입력했을 때와 똑같이 제한됩니다. 탐색이나 조회는 워크스페이스 밖으로 이어지는 링크를 통해 읽지 않고, 워크스페이스 안의 Release나 그 Manifest가 경로로 지정하는 파일은 워크스페이스 밖에서 읽지 않으며(호출이 워크스페이스 밖에서 지정한 Release가 지정하는 파일은 그 Release를 담은 디렉터리 밖에서 읽지 않습니다), 디렉터리(워크스페이스 또는 호출이 지정한 디렉터리) 아래에 쓰는 파일은 그 디렉터리 안에 머뭅니다. 워크스페이스 경계는 두 전송 방식을 명령줄 및 편집기와 나란히 놓고, 표준 입출력에서 여전히 열려 있는 부분을 설명합니다. 복제한 워크스페이스의 문서가 어시스턴트를 유도해 워크스페이스 밖의 경로를 지정하게 할 수 있으며, 그 경로는 지정된 그대로 받아들여집니다.

응답이 서버의 파일 시스템에 대해 알려 주는 것

HTTP를 통한 응답은 서버 파일 시스템의 위치를 워크스페이스 루트 기준 상대 경로로 나타내거나 숨깁니다. 서버를 실행한 클라이언트는 서버와 같은 곳에서 실행되므로, 표준 입력과 출력을 통한 모든 응답은 각 위치를 작업이 보유한 형태 그대로 나타냅니다. 작업이 절대 경로로 보유하고 있다면 절대 경로로 나타내며, 각 위치는 그 호출자가 이미 소유한 곳입니다. 리스너에 접속하는 호출자는 그 위치 중 어느 것도 선택하지 않았고 열 수도 없으며, 서버가 한 번 공개한 위치는 되돌릴 수 없습니다. 따라서 HTTP를 통한 응답은 위치에 대해 호출자에게 다음 두 가지 중 하나를 알려 줍니다.

  • 워크스페이스 안의 위치는 워크스페이스 루트 기준 상대 경로로 나타냅니다. 이는 보내는 경로와 같은 형태이므로, 한 응답에서 읽은 이름을 다음 호출에 그대로 보낼 수 있습니다. 루트에 있는 Release는 release.yaml이고, 그 잠금 파일은 release.lock입니다.
  • 워크스페이스 밖의 위치는 숨기며, 워크스페이스 루트 자체도 숨깁니다. 해당 필드에는 값이 없습니다. 값은 null이거나 생략되며, 모든 표면에서 보고되는 형태를 유지하는 응답을 가진 attachment-container에서는 file이 비어 있습니다. 그리고 필드 이름 뒤에 _withheld를 붙인 표시가 그 옆에 있어, 값이 설정되지 않은 것이 아니라 숨겨졌음을 알려 줍니다. workspace_root 옆의 workspace_root_withheld, file 옆의 file_withheld가 그 예입니다. 표시는 무언가를 숨긴 경우에만 나타납니다. 루트를 숨기는 이유는 리스너가 정확히 하나의 워크스페이스만 제공하므로, 그 워크스페이스가 어디에 있는지는 그 안의 것을 지칭하는 데 필요하지 않기 때문입니다.

위치가 안에 있는지는 도달하는 파일이 아니라 표기 방식으로 판단합니다. 서버가 시작된 루트가 아니라 심볼릭 링크의 대상을 거쳐 작성한 경로와, 루트 밖으로 나갔다가 다시 들어오는 경로는 모두 워크스페이스 밖으로 간주되어 숨겨집니다. 이 판단은 덜 알려 주는 쪽으로 기울며, 워크스페이스 밖의 위치를 나타내는 쪽으로는 결코 기울지 않습니다.

HTTP를 통한 응답의 읽을 수 있는 텍스트도 같은 규칙을 따릅니다. 텍스트, 진단 줄 또는 실패 메시지가 워크스페이스가 보유한 위치(루트나 그 아래의 모든 것, 구성을 읽어 온 구성 파일, 카탈로그를 읽어 오는 디렉터리)를 나타내는 경우, 그 위치는 루트 기준 상대 경로로 쓰이거나, 워크스페이스 밖에 있거나 루트인 경우 (location withheld)로 표시됩니다. 응답이 자신의 워크스페이스에 대해 작성하는 텍스트는 그것을 이 서버가 제공하는 워크스페이스라고 부릅니다. 작업이 메시지에 쓰는, 이 모든 것 밖의 위치는 위치로 인식되지 않으며 쓰인 그대로 전달됩니다.

HTTP를 통해 이 규칙이 적용되는 응답:

  • list-entities, list-releases, cache-status, registry-list, search, attach-candidates, connection-candidates, insertion-point, attachment-container, connection-at-position, edit-document는 workspace_root를 숨깁니다. 이미 루트 기준 상대 경로로 제공하는 경로(엔티티의 소스 파일, Release의 경로와 lockfiles 아래의 잠금 파일, 삽입 지점이나 편집의 대상 문서, 편집이 쓴 파일)는 두 전송 방식에서 동일하게 표시됩니다.
  • cache-status는 서버가 호스트의 파일에서 로드한 플러그인을 나타내는 것도 숨깁니다. 그러한 식별자는 provenance[].identities의 해당 자리에서 null이 되고, 다른 모든 식별자는 위치를 유지하며, 해당 항목에는 identities_withheld 표시가 붙습니다. 컴파일된 모듈의 note는 모듈이 빌드된 대상 식별자를 나열하는 한 문장이므로, 그중 하나라도 그러한 파일을 나타내면 note 전체가 생략되고 note_withheld 표시가 붙습니다. 모듈의 digest는 그대로 남습니다. 레지스트리 참조나 Plugin 엔티티를 나타내는 식별자는 전체가 응답되며, 그것들만 나타내는 note도 마찬가지입니다. 소스 아티팩트의 label은 캐시 내 위치로, 해석된 URL의 호스트와 경로로 표기됩니다. 따라서 서버 자체 파일 시스템에서 file:// URL이나 경로를 통해 읽은 저장소의 경우 label이 생략되고 label_withheld 표시가 붙으며, size와 digest는 그대로 남습니다. 네트워크 호스트를 나타내는 label은 전체가 응답됩니다. 목록의 텍스트는 그러한 위치를 나타냈을 자리에 (location withheld)로 표시됩니다.
  • validate는 target과, Release의 경우 release를 루트 기준 상대 경로로 나타냅니다. 카탈로그 전체의 경우 target은 루트이므로 숨겨집니다. diagnostics나 notices의 위치는 텍스트 규칙을 따릅니다.
  • build는 release를 루트 기준 상대 경로로 나타내며, 의존성을 먼저 해석한 빌드는 pull이 응답하는 형태의 dependency_resolution을 포함합니다. write를 받은 빌드는 쓴 디렉터리를 output_dir로 나타내며, 이는 루트 기준 상대 경로로 dist이고, files의 각 경로는 그 디렉터리 기준 상대 경로입니다. refusal과 그 findings의 각 항목은 file을 루트 기준 상대 경로로 나타내거나, 문서가 워크스페이스 밖에 있으면 숨깁니다. advisories, deprecations, declined_external_inputs와 refusal의 각 message는 텍스트 규칙을 따릅니다.
  • pull은 release와 lockfile을 루트 기준 상대 경로로 나타냅니다. diagnostics와 incomplete_external_inputs는 텍스트 규칙을 따릅니다. 각 resolved 항목의 source는 두 전송 방식 모두에서 전체가 응답됩니다. 이는 실행이 한 일을 나타낼 뿐 호스트의 위치를 나타내지 않습니다.
  • 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으로 응답합니다. 따라서 밸런서는 아직 시작 중인 프로세스에 첫 요청을 보내는 대신, 프로세스가 실제로 호출에 응답할 수 있을 때까지 트래픽을 보류합니다. 모든 응답은 본문이 비어 있는 상태 코드이며, 자격 증명을 요구하지 않고 호출자가 보낸 내용을 읽지 않습니다.

엔드포인트는 이 두 경로에 결코 응답하지 않습니다. mcp.listen이 지정한 주소의 GET /healthz와 GET /readyz는 토큰 유무와 관계없이, 엔드포인트가 제공하지 않는 다른 모든 경로와 똑같이 404로 응답됩니다. 그곳에서 프로브에 응답하면, 자격 증명이 없는 모든 요청을 거부하는 리스너에서 엔드포인트에 도달하는 누구에게나 프로세스 실행 여부를 공짜로 알려 주고 프로세스에 작업을 시킬 수단까지 공짜로 내주게 됩니다.

상태 확인 주소의 위치는 직접 선택하며, mcp.listen처럼 제한되지 않습니다. 이 주소에 대해서는 어떤 주소도 거부되지 않습니다. 루프백이나 Unix 소켓을 지정하십시오. 이 주소는 같은 호스트에서 이 프로세스와 함께 실행되는 감독자, 밸런서 또는 컨테이너 런타임을 위한 것입니다. 선택한 주소에 도달할 수 있는 것은 무엇이든 이 두 응답을 읽을 수 있으므로, 공개 네트워크에서 도달할 수 있는 주소는 응답을 공개 네트워크에 공개합니다.

자격 증명 없이는 아무것도 제공되지 않음

엔드포인트에 대한 모든 요청은 자격 증명을 포함하며, 어떤 자격 증명인지는 앞단의 프록시가 이미 확인했는지에 따라 달라집니다. 기본적으로는 이 서버가 직접 검증하는 베어러 토큰이며, 이 절의 나머지 부분에서 설명합니다. mcp.authorization.trusted_proxy를 설정하면 대신 프록시가 설정하는 헤더가 되며, 앞단의 프록시에서 호출자 읽기에서 설명합니다. 이 경우 토큰은 전혀 읽지 않습니다. 어느 방식이든 아무것도 제시하지 않는 요청은 처리하지 않습니다.

기본적으로 서버는 베어러 토큰을 직접 확인합니다. 서버는 Authorization 헤더에서 토큰을 읽고, 권한 부여 서버가 공개한 키로 서명이 검증되고, 토큰이 발급자로 mcp.authorization.issuer를 지정하고, 대상 중에 이 배포 자체의 mcp.authorization.resource를 포함하고, 유효 기간 안에 있으며, 제시한 주체를 밝히는 경우에만 토큰을 수락합니다. 이 중 하나라도 통과하지 못한 토큰은 401로 응답되며, 아무것도 제시하지 않은 호출자가 받는 것과 같은 챌린지에 error="invalid_token"이 추가됩니다. 응답은 어느 검사에서 거부되었든 동일하므로, 호출자는 보낸 토큰의 어느 부분이 잘못되었는지가 아니라 다른 토큰이 필요하다는 것만 알게 됩니다. 비대칭 서명 알고리즘만 수락합니다. 서명되지 않은 토큰과 대칭 알고리즘을 지정한 토큰은 내용을 읽기 전에 거부됩니다.

토큰은 자신이 어떤 종류의 토큰인지 밝힐 수 있으며, 네 가지 형태를 수락합니다. JWT는 자신의 유형을 나타내는 typ 헤더를 포함할 수 있습니다. 이 서버는 액세스 토큰용으로 등록된 두 표기인 at+jwt와 application/at+jwt, 토큰이 JWT라는 것만 나타내는 JWT, 그리고 유형을 전혀 선언하지 않은 토큰을 수락합니다. 그 밖의 것은 다른 모든 거부된 토큰과 똑같이 401로 응답됩니다. 이 집합은 고정되어 있으며 어떤 설정으로도 넓히거나 좁힐 수 없습니다. 그곳에 어떤 형태가 나타나는지는 토큰을 받는 배포가 아니라 토큰을 발급한 권한 부여 서버가 결정하기 때문입니다. JWT를 수락하면 선언된 유형만으로는 액세스 토큰과 ID 토큰을 더 이상 구별할 수 없습니다. 이 둘을 구별하는 것은 대상 검사이며, 그래서 이 검사가 핵심입니다. ID 토큰의 대상은 토큰이 발급된 클라이언트이지 결코 이 배포 자체의 mcp.authorization.resource가 아니므로, 이 배포가 아닌 다른 대상에 발급된 토큰은 스스로를 무엇이라 칭하든 거부됩니다.

이로써 허용되는 권한 부여 서버. Microsoft Entra ID는 유형이 JWT인 액세스 토큰을 발급합니다. Keycloak은 at+jwt를 발급하며, OpenID Connect 호환 모드가 켜져 있으면 JWT를 발급합니다. Auth0은 자체 토큰 프로필에서는 JWT를, RFC 9068 프로필에서는 at+jwt를 발급합니다. 이들 중 어느 서버의 토큰이든 두 형태 중 무엇을 포함하든 이 검사를 통과합니다. Okta는 지원되지 않습니다: Okta의 액세스 토큰은 위 네 가지 중 어느 것도 아닌 자체 유형을 선언하므로 이 서버는 이를 거부합니다.

토큰이 거부된 이유는 서버 자체의 오류 스트림에 남습니다. 호출자에게는 제시한 것이 수락되지 않았다는 사실만 알려 주며, 서비스 프로세스는 토큰을 거부한 검사(대상, 발급자, 유효 기간, 서명, 키 식별자, 선언된 유형 및 그 밖의 각 검사)를 나타내는 줄 하나를 씁니다. 이 줄이 있기에 모든 요청을 거부하는 배포를 호출하는 쪽뿐 아니라 운영하는 쪽에서도 진단할 수 있습니다. 이 줄에는 토큰의 어떤 부분도 포함되지 않습니다. 자격 증명을 전혀 제시하지 않은 요청은 줄을 쓰지 않습니다. 챌린지를 받는 것이 클라이언트가 애초에 토큰을 어디서 얻을지 알아내는 방법이므로, 올바르게 동작하는 모든 클라이언트가 가장 먼저 하는 일이기 때문입니다.

토큰은 헤더에만 있어야 합니다. access_token 쿼리 매개변수로 보낸 토큰은 400으로 응답되며 읽히지 않습니다. 주소는 요청이 거치는 모든 프록시 로그, 브라우저 기록, 리퍼러 헤더에 기록되므로, 그렇게 도착한 토큰은 이미 노출된 것이기 때문입니다. 서버는 토큰을 로그에 쓰지 않고, 어디로도 보내지 않으며, 호출자를 대신해 토큰을 얻거나 교환하지 않습니다. 제시된 것을 읽고 판단할 뿐 아무것도 보관하지 않습니다. 토큰이 지정한 주체는 기록되지만 어떤 것과도 비교되지 않습니다.

검증 키는 권한 부여 서버나 지정한 파일에서 가져옵니다. mcp.authorization.jwks_file이 설정되지 않으면 서버는 잘 알려진 주소에서 권한 부여 서버의 메타데이터를 읽고, 그곳에 게시된 jwks_uri를 따라가 찾은 키를 보관합니다. 그 키에 없는 키 식별자로 서명된 토큰은 다시 읽기를 한 번 유발하며, 짧은 간격 안에 한 번을 넘지 않으므로 지어낸 키 식별자를 보내는 호출자가 요청마다 외부 요청을 일으킬 수는 없습니다. 권한 부여 서버에서 키를 읽으려면 https 키 주소가 필요합니다. 또는 이 머신의 일반 http 주소도 됩니다. 다른 호스트의 일반 http인 jwks_uri에는 요청하지 않으며, 어느 읽기든 다른 호스트의 일반 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를 지정합니다. 각각은 X-Forwarded-User와 같은 HTTP 헤더 이름으로, 공백이나 콜론을 포함하지 않습니다. 다른 형태의 이름은 구성을 불러올 때 해당 키를 지정하며 거부되고, 빈 principal_header도 마찬가지입니다. 이 모드를 끄려면 블록을 생략합니다. 읽는 헤더는 이 두 개뿐이며, 전달 주소 헤더나 그 밖의 헤더는 관여하지 않습니다. principal 헤더 없이 도착한 요청은 401로 응답되며, 이 모드에서는 토큰을 전혀 읽지 않습니다. 이 서버가 원래라면 거부했을 토큰을 담은 요청도 principal 헤더가 있으면 처리되고, 이 서버가 수락했을 토큰을 담은 요청도 그 헤더가 없으면 여전히 거부됩니다.

이 모드는 루프백이나 Unix 소켓에서만 허용되며, 그 밖의 곳에 바인딩하려 하면 프로세스가 바인딩 전에 거부됩니다. 헤더는 프록시 외에는 아무것도 그 헤더를 설정할 수 없을 때에만 신뢰할 수 있습니다. 네트워크에서 도달할 수 있는 주소에서는 무엇이든 그 헤더를 설정할 수 있으므로, 그런 주소에서 이 모드로 동작하는 리스너는 모든 호출자가 자신을 원하는 대로 지칭하게 허용하게 됩니다. 거부 메시지는 충돌하는 두 설정을 모두 지정하므로, 주소를 옮기거나 블록을 제거하여 거부를 해소할 수 있습니다.

프록시가 주장하는 내용이 곧 이 서버가 믿는 내용이며, 그것이 이 모드의 조건입니다. 이 모드에서 이 서버는 서명을 확인하지 않으며, 토큰의 subject를 아무것과도 비교하지 않는 것과 마찬가지로 주장된 호출자도 아무것과도 비교하지 않습니다. 프록시가 전달한 내용을 검증했는지, 그리고 프록시를 거치지 않고 그 리스너에 도달할 수 있는 것이 있는지는 배포 측이 올바르게 갖추어야 할 사항입니다. 위의 제한은 이를 올바르게 갖출 수 있게 해 줄 뿐, 실제로 갖추어졌다는 보장은 아닙니다.

mcp.authorization.trusted_proxy를 설정해도 다른 요구 사항은 사라지지 않습니다. 메타데이터 문서는 여전히 게시되고 챌린지도 여전히 그 문서를 지정하므로 issuer와 resource는 여전히 필요합니다. 프록시 뒤의 클라이언트도 프록시가 확인할 토큰을 어디서 받을지 알아야 하기 때문입니다. 같은 이유로 발급자는 이 머신에서 실행되는 경우가 아니라면 여전히 https 주소여야 합니다. 그 클라이언트는 발급자에게서 토큰을 받으므로, 이 서버가 그곳에서 아무것도 읽지 않더라도 다른 호스트의 일반 http 발급자는 다른 모든 모드에서와 똑같이 이 모드에서도 리스너가 바인딩되기 전에 거부됩니다.

호출자가 도달할 수 있는 범위

HTTP를 통해 호출자가 도달하는 범위는 두 가지 경계가 결정하며, 이 경계들은 서로 다른 사람이 설정합니다. 첫 번째는 호출자 자신의 자격 증명이고, 두 번째는 이 서버가 애초에 제공하는 범위입니다. 둘 다 무엇이든 실행되기 전에, 각 작업이 스스로에 대해 하는 선언으로부터 읽히며, 클라이언트에게는 서로 다른 곳에서 드러납니다. 도구 목록은 이 서버가 제공하고 알리는 것을 보여 주고, 각 호출이 받는 응답은 자격 증명이 허용하는 것을 보여 줍니다.

모든 작업은 자신의 효과가 미치는 범위를 선언하며, 그 종류는 네 가지입니다(가장 넓은 것이 마지막):

  • 아무 데도 도달하지 않음 — 정의를 읽고, Release가 고정하는 내용을 검사하고, 아티팩트를 메모리에서 렌더링하여 돌려줍니다. 아무것도 남기지 않습니다. 아무것도 기록되지 않으며, 응답이 생성되는 것의 전부입니다.
  • 워크스페이스에 도달함 — 이 프로세스가 제공하는 워크스페이스 안에 기록합니다. Release의 lockfile, 아티팩트 캐시, 생성된 엔터티, 편집된 문서가 이에 해당합니다.
  • 레지스트리에 도달함 — 게시하거나, 서명하거나, 이미 게시된 것에 철회 표식을 첨부합니다. 이 작업이 바꾸는 것은 해당 레지스트리의 모든 소비자가 해석하는 내용이며, 이미 가져간 사람에게서는 어느 것도 회수할 수 없습니다.
  • 머신에 도달함 — 호스트의 모든 워크스페이스가 공유하는 것을 바꿉니다. 컴파일된 모듈 저장소, 모든 워크스페이스에 공통된 구성 파일, 자격 증명 저장소 등이 이에 해당합니다. 단일 프로젝트가 자체 캐시 디렉터리 아래에 유지하는 캐시는 이 종류가 아니며, cache-status는 나열하는 각 캐시가 이 종류들 중 어느 것에 해당하는지 보고합니다.

종류는 작업을 제공하는 도구가 아니라 작업 자체의 속성이며, 표면이 돌려주는 응답을 어디에 두는지가 아니라 작업이 남기는 것을 다룹니다. Release 렌더링은 응답으로 아티팩트를 생성하므로 아무 데도 도달하지 않습니다. 그 뒤 명령줄이 지정한 디렉터리에 그 아티팩트를 저장하는 것은 더 멀리 도달하는 것이 아니라 그 응답을 전달하는 것입니다. 반대로 해석하면, 내용으로 응답하는 모든 작업이 우연히 그것을 저장한 표면의 종류를 갖게 되어, 종류는 더 이상 작업의 속성이 아니게 됩니다. 같은 이유로 레지스트리 참조로 엔터티를 읽는 describe는 아무 데도 도달하지 않습니다. 응답을 가져오기 위해 해당 레지스트리에 접속하지만 레지스트리에도 이 머신에도 아무것도 남기지 않으며, 접속할 수 있는 레지스트리는 호출이 사용하는 자격 증명에 설명되어 있습니다. 호출 자체가 기록을 요청하는 경우, 한 호출은 작업의 종류보다 더 멀리 도달할 수 있습니다. write가 전달된 빌드는 이 서버가 제공하는 워크스페이스에 아티팩트를 저장하므로 그 호출은 워크스페이스에 도달하며, 의존성을 먼저 해석하는 빌드도 마찬가지입니다.

스코프는 종류를 허용하며, 각 쓰기 스코프는 읽기 스코프를 포함합니다. aggrega:read는 아무 데도 도달하지 않는 작업을 허용합니다. aggrega:workspace-write는 워크스페이스에 도달하는 작업을 허용하며 읽기 스코프를 포함합니다. aggrega:registry-write는 레지스트리에 도달하는 작업을 허용하며 역시 읽기 스코프를 포함합니다. 따라서 클라이언트는 필요한 쓰기 스코프를 인가 서버에 요청하면 되고, 읽기 스코프를 따로 요청할 필요가 없습니다.

machine 종류를 허용하는 스코프는 없으며, 이를 추가하는 설정도 없습니다. 이 종류의 작업은 별도 프로세스에서 aggrega 명령을 실행하는 도구만 제공하며, HTTP로 접근하는 서버는 앞의 HTTPS로 서버에 접근하기에서 설명한 이유로 그러한 도구를 전혀 제공하지 않습니다. 이러한 작업은 호스트의 터미널에서 실행하십시오.

도구 목록은 호출하는 자격 증명이 어떤 스코프를 가지고 있든 이 서버가 제공하고 알리는 모든 도구를 보여 주며, 호출이 그중 어느 도구를 실행할 수 있는지는 자격 증명이 결정합니다. describe-capabilities도 같은 집합을 색인하고 정의합니다. 자격 증명이 허용하지 않는 호출에는 챌린지에 error="insufficient_scope"를 담은 403으로 응답하며, 이 챌린지는 해당 호출을 허용할 하나의 스코프를 명시하고, 호출이 요청한 것은 아무것도 실행되지 않습니다. 이 거부는 프로토콜의 step-up이 응답하는 거부입니다. step-up을 구현한 클라이언트는 챌린지가 명시한 스코프로 다시 로그인하도록 요청합니다. 목록은 자격 증명에 따라 바뀌지 않으므로, 다시 로그인한 클라이언트는 이미 올바른 도구를 보유하고 있습니다. 세 스코프 중 어느 것도 가지지 않은 자격 증명도 같은 도구 목록을 받지만, describe-capabilities를 포함하여 목록의 어떤 도구도 호출할 수 없습니다.

빌드는 알아 둘 만한 경우입니다. 빌드는 그 자체로는 아무것도 바꾸지 않으므로 aggrega:read만 필요하지만, 쓰기를 하는 빌드에는 aggrega:workspace-write가 필요합니다. write를 보낸 빌드는 아티팩트를 워크스페이스 루트의 dist/에 저장하고, 의존성을 먼저 해결하는 빌드는 lockfile을 씁니다. 이는 호출이 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은 읽히지 않으며, 주변 환경의 GitHub Actions OIDC 엔드포인트에도 접근하지 않습니다. 이들은 권장되지 않는 것이 아니라 접근할 수 없는 것입니다. 신원 확인 과정이 찾을 수 있는 것이 아무것도 없습니다. identity_token을 보내지 않은 호출은 거부되며, 거부 응답은 보내야 할 것으로 identity_token을 지목하고 어떤 변수나 엔드포인트도 지목하지 않습니다. 이 머신의 키보드 앞에 있지 않은 호출자는 여기서 아무것도 export할 수 없으므로, 그런 것을 지목하면 응답을 바꿀 수 없는 무언가를 준비하라고 알려 주는 셈이 되기 때문입니다.

이 머신에 보관된 서명 키는 어느 경로로도 선택할 수 없습니다. key_path는 무엇이든 확인되기 전에 거부되며, 여기서 publish-entity, sign-artifacts, deprecate-artifact가 알리는 인수 스키마에도 없으므로, 호출자에게 성공할 수 없는 인수가 제시되는 일은 없습니다. 서비스되는 워크스페이스의 자체 구성이 지정하는 서명 키에도 접근하지 않습니다. 이는 signing.key_path가 워크스페이스 전체에 설정되었든, 한 레지스트리에 대해 설정되었든, 환경에서 제공되었든 마찬가지입니다. 두 경우 모두 이유는 같습니다. 키 경로는 자격 증명이 아니라 이 서버가 보유한 비밀의 이름입니다. 호출자가 그 이름을 제공해도 아무것도 증명되지 않습니다. 이 주소에 접근한 누구든 같은 이름을 제공할 수 있고, 그 결과 만들어진 서명은 호출자가 아니라 운영자가 아티팩트를 보증했다고 말하게 됩니다. 인수는 막고 구성은 열어 두면, 한쪽 문은 닫았지만 다른 문으로 같은 방에 여전히 들어갈 수 있는 셈입니다. 따라서 리스너를 통해서는 키 기반 서명에 접근할 수 없으며, 호출에 담아 보낸 토큰만 서명합니다.

fulcio_url, rekor_url, timestamp_url은 영향을 받지 않으며 두 전송 방식 모두에서 유지됩니다. 이들은 이 머신이 보유한 무언가가 아니라 접속할 서비스를 지정하므로, 키를 선택할 수 없는 호출자도 이 배포가 구성한 엔드포인트를 대상으로 서명합니다.

서명 키를 지정하는 워크스페이스에서 시작된 리스너는 시작할 때 이 사실을 한 번 알립니다. 프로세스는 자체 오류 스트림에 해당 설정을 지목하고 이 리스너에 접근하는 호출자가 그 키를 사용할 수 없다는 내용을 담은 한 줄을 씁니다. 따라서 운영자는 예상하지 못한 서명이 아니라 자신이 시작한 프로세스를 통해 이를 알게 됩니다. 키를 지정하지 않은 워크스페이스는 알릴 내용이 없으므로 그런 줄을 만들지 않습니다. 그 줄에는 설정의 이름만 담기며, 키나 키가 가리키는 파일에 관한 어떤 정보도 담기지 않습니다.

표준 입력과 출력을 통해서는 위의 어느 것도 적용되지 않습니다. 이 경우 환경을 읽으며 key_path는 이 머신에 보관된 키를 선택합니다. 이 서버를 실행한 클라이언트가 호출자 자신의 머신에서 실행 중이고, 그 프로세스가 접근할 수 있는 것은 호출자 자신이 사용할 수 있는 것이기 때문입니다.

레지스트리 참조로 엔터티를 읽으면 이 호스트 자체의 로그인으로 하나의 레지스트리에 접속하며, 리스너를 통해서는 서비스되는 워크스페이스에 구성된 레지스트리에만 접속합니다. name으로 oci:// 참조를 받은 describe는 그 좌표에 게시된 엔터티를 읽습니다. 이는 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 응답이 시작하는 문장과 같으며, 서버가 어느 릴리스에서 왔는지에서 설명합니다. 번들 없이 이루어진 실행이나 번들이 실행 파일과 같은 릴리스에서 온 실행은 이 문장 없이 안내를 전달합니다. 두 가지 모두 프로세스가 시작될 때 고정되며, 어느 프로세스 안에서든 두 리비전은 그 프로세스 고유의 텍스트를 여전히 동일하게 제공합니다.

이 안내는 도구의 인수 스키마만으로는 전달할 수 없는 멘탈 모델을 가르칩니다.

  • 컴파일러가 하는 일과 의도적으로 하지 않는 일 — 컴파일러는 값의 의미를 해석하는 대신 텍스트를 라우팅하고 레이블 일치를 평가한다는 것, 문서에 넣는 내용에 대해 주관이 없는 것, 그리고 컴파일하는 동안 provider로 인증하지 않고, 클러스터의 상태를 읽지 않으며, 시크릿을 평문으로 바꾸지 않는다는 것입니다. 인프라가 실행된 후에야 존재하는 값은 대상 환경이 나중에 채우는 포인터 문자열로 전달됩니다.
  • 작성 어휘와 각 kind의 관계 — 각 kind의 용도와 실제로 빌드가 어느 kind를 대상으로 실행되는지를 설명하므로, 어시스턴트가 도구 목록에서 배포의 형태를 추론할 필요가 없습니다.
  • 작성 루프가 실행되는 순서 — 계약을 읽고, 그로부터 스캐폴드를 만들고, 연결할 대상을 살펴본 다음, 렌더링 전에 검사합니다.
  • 도구 대신 프롬프트를 사용할 때 — 동작하려면 도구를, 작업의 틀을 잡으려면 프롬프트를 사용합니다.
  • 도구 목록이 표면의 전부라는 것 — 이 서버가 제공하는 모든 도구가 그 안에 있고, 서버가 어떤 도구를 제공하는지는 설정 방식에 따라 달라지므로, 어시스턴트는 두 번째 목록을 찾아다니는 대신 그 목록과 describe-capabilities에서 여기 있는 것을 읽습니다. 연결이 자격 증명을 제시한 경우, 그 자격 증명은 호출이 어느 도구를 실행할 수 있는지를 결정할 뿐 어느 도구가 나열되는지는 결정하지 않는다고 알립니다. 자격 증명이 허용하지 않는 호출은 그 호출을 허용할 범위를 명시하며 거부되고, 클라이언트는 그 범위로 다시 로그인할 수 있습니다.
  • 빈 워크스페이스의 의미와 모델이 그에 대해 할 수 있는 일 — 아래에 설명하는, 전송 방식에 따라 달라지는 단락입니다.

안내는 표면을 다시 설명하지 않고 이름만 제시합니다. 각 도구는 이미 tools/list에 자체 설명과 인수 스키마를 담고 있고, 각 kind의 계약은 이미 스키마와 참조 페이지에 있으므로, 안내는 그것들을 가리키는 데서 멈춥니다. 하나의 진술에는 하나의 출처만 있습니다. 안내가 이름을 드는 도구는 서버가 제공하는 도구이며, 안내는 읽기 표면이 해석하는 모든 리소스 계열을 가리키므로, 안내가 어시스턴트를 보내는 곳 중 막다른 곳은 없습니다.

안내에는 도구 자체의 색인이 없으며, 이는 같은 원칙에 따른 것이지 원칙에서 빠진 것이 아닙니다. 클라이언트는 이 텍스트를 한 글자라도 읽기 전에 tools/list에서 모든 도구의 정의를 받아 두므로, 여기에 도구마다 한 줄씩 두면 이미 가진 용도의 두 번째 사본이 됩니다. 그 사본은 모든 세션에서 모든 클라이언트가 비용을 치르고, 둘 중 하나가 수정되는 순간 도구 목록과 어긋날 수 있습니다.

안내는 열거하지 않는 것과 그 이유도 밝힙니다. 사용 가능한 렌더 대상과 설치된 라이브러리 kind는 플러그인과 스키마 집합의 속성이므로, 안내가 어긋날 수 있는 사본을 담는 대신 리소스 표면이 이를 직접 보고합니다.

빈 워크스페이스에 대해 모델이 전달받는 내용

마지막 단락은 아무것도 없는 워크스페이스에서 모델이 처음 마주하는 질문, 즉 빈 list-entities가 무엇을 의미하며 모델이 그에 대해 무엇을 할 수 있는지에 답합니다. 시작 부분은 두 전송 방식에서 같습니다. 빈 목록은 이 프로세스가 해석한 워크스페이스에 읽을 수 있는 Aggrega 문서가 없고, 그 옆에 구성된 카탈로그 디렉터리에도 선언된 것이 없다는 뜻입니다. 그 뒤의 내용은 이 프로세스가 어느 전송 방식을 제공하는지에 따라 달라지는데, 정직한 답이 두 방식에서 같지 않기 때문입니다.

표준 입력과 출력에서는 워크스페이스를 모델이 직접 살펴보고 고칠 수 있다고 알립니다. 워크스페이스를 지정하지 않은 호출이 어디에서 처리되는지도 알립니다. 서버가 폴더를 지정해 실행된 경우 그 폴더에서, 그렇지 않으면 서버가 시작된 폴더에서 찾은 워크스페이스(그 폴더 자체일 수도 있음)에서 처리되며, 호출의 workspace_root가 다른 워크스페이스를 지정한다는 것도 알립니다. 적용 중인 구성과 각 설정을 어느 계층이 결정했는지는 config-show를, 작동하는 구성을 만들려면 cli-config-init를 안내하며, 둘 다 이 전송 방식의 도구 목록에 있습니다. 서버를 실행하는 클라이언트는 호출자 자신의 머신에 있으므로, 그 프로세스가 닿을 수 있는 것은 호출자 자신이 쓸 수 있는 것입니다. 경계를 설정하는 곳은 다른 모든 도구와 마찬가지로 MCP 클라이언트이며, 어시스턴트가 먼저 묻지 않고 할 수 있는 일에서 설명합니다.

HTTP에서는 구성하지 말고 보고하라고 알립니다. 워크스페이스는 프로세스를 시작할 때 지정한 것이며 프로세스 수명 동안 고정됩니다. workspace_root나 catalog_dirs를 지정한 호출은 해당 인수를 명시하며 거부되고, 자격 증명이 어떤 범위를 가졌든 구성을 쓰는 도구는 여기서 어떤 호출자에게도 제공되지 않습니다. 그런 작업은 별도 프로세스에서 aggrega 명령을 실행하는 도구에만 있으며, HTTP로 접속한 세션은 그 도구 없이 구성됩니다. 따라서 경계는 범위가 아니라 구성 자체이며, 어떤 토큰도 이를 넓히지 못합니다. 그러므로 리스너를 통해 배포에 접속한 모델은 호스트에서 레지스트리를 설정하거나 신뢰 정책을 다시 쓸 수 없으며, 단락은 모델이 시도한 뒤 거부를 읽게 두는 대신 이를 미리 알려 줍니다.

어시스턴트가 먼저 묻지 않고 할 수 있는 일

표준 입력과 출력으로 이 서버에 연결된 어시스턴트는 클라이언트가 거부하도록 구성되어 있지 않은 한, 묻지 않고 서버가 노출하는 모든 도구를 호출할 수 있습니다. 이 전송 방식에서 서버는 도구를 제공할 뿐, 특정 호출이 그중 어떤 도구를 사용할 수 있는지 결정하지 않습니다. 그 결정은 클라이언트의 몫이며, 그곳에서 사용자가 내려야 합니다. HTTP에서는 다릅니다. 서버는 자신이 갖추고 알리는 모든 도구를 나열하고, 호출하는 토큰의 범위가 허용하지 않는 호출을 거부하므로, 경계는 클라이언트뿐 아니라 서버의 몫이기도 합니다.

이것이 중요한 이유는 도구 표면이 곧 명령줄이기 때문입니다. 입력할 수 있는 것은 무엇이든 어시스턴트가 호출할 수 있으며, 여기에는 머신을 변경하는 작업도 포함됩니다.

이러한 작업 중 일부는 작업 중인 워크스페이스보다 더 멀리 영향을 미치며, 다른 무언가를 실행해서 되돌릴 수 없습니다. 이름으로 알아 둘 만한 작업은 다음과 같으며, 영향 범위가 넓은 것부터 나열합니다.

  • publish-entity, publish-artifact, sign-artifacts, deprecate-artifact는 머신을 완전히 넘어서 영향을 미칩니다. 이들은 바이트, 서명 또는 철회 마커를 레지스트리에 기록하므로, 이들이 변경하는 것은 이 머신이 해석하는 것만이 아니라 그 레지스트리의 모든 소비자가 해석하는 것입니다. 태그 위에 다른 내용을 다시 게시하는 것은 제공되지 않고 거부되므로, 여기서 게시를 되돌리는 방법은 없습니다. 해결책은 새 버전을 게시하는 것입니다. 서명과 철회 마커는 아티팩트의 바이트를 건드리지 않지만, 이후에 그 아티팩트를 가져오는 사람은 이것들도 함께 가져오며, 이미 가지고 있는 사람에게서는 어느 것도 회수할 수 없습니다. 표준 입력과 출력에서는 같은 네 가지 기능을 명령을 실행하는 cli-push, cli-push-artifact, cli-sign, cli-deprecate로도 사용할 수 있으며, HTTP에서는 이 네 도구가 존재하지 않습니다.
  • 서명에는 자격 증명이 사용됩니다. 표준 입력과 출력에서 키리스 서명은 호출의 identity_token 인수, 서버 환경의 AGGREGA_IDENTITY_TOKEN 또는 SIGSTORE_ID_TOKEN, 또는 도달 가능한 경우 주변의 GitHub Actions OIDC 엔드포인트에서 ID 토큰을 가져오며, key_path는 대신 오프라인으로 보관된 키를 선택합니다. 따라서 이 도구를 호출할 수 있는 어시스턴트는 서버를 실행하는 머신이 이미 가진 어떤 ID로든 사용자로서 서명할 수 있습니다. 서명은 누가 아티팩트를 보증하는지에 대한 진술이므로, 허용하기 전에 가장 신중하게 고려해야 할 작업이 바로 이것입니다. 리스너에서는 호출에 담겨 전송된 토큰만 서명에 사용됩니다. 서버 환경의 어떤 것도 읽지 않으며, 호스트에 보관된 키는 인수로도, 제공되는 워크스페이스의 구성으로도 선택할 수 없습니다. 자세한 내용은 호출이 사용하는 자격 증명에서 설명합니다.
  • aggrega cache evict는 컴파일된 모듈 저장소를 정리하고, aggrega cache clear는 이를 지웁니다. 이 저장소는 머신의 모든 Aggrega 프로젝트가 공유합니다. 저장소에서 제거된 모듈은 필요할 때 다시 컴파일되므로 영구적으로 잃는 것은 없지만, 모든 프로젝트의 다음 빌드가 그 비용을 치릅니다. aggrega cache clear는 머신의 모든 프로젝트가 읽는 문서 번들도 제거하며, 이 번들은 프로젝트 중 하나가 다음에 이를 획득할 때 다시 가져옵니다.
  • aggrega cache prune은 어떤 lockfile도 참조하지 않는 아티팩트 캐시 항목을 회수합니다. 프로젝트의 lockfile을 읽을 수 없는 경우 그 프로젝트가 고정한 아티팩트는 lockfile로 보호되지 않으며, 이를 회수하면 다시 가져와야 합니다.
  • aggrega registry add와 aggrega registry remove는 기본적으로 모든 워크스페이스가 공유하는 구성에 기록하므로, 여기만이 아니라 머신의 모든 곳에서 해석되는 것을 변경합니다. aggrega registry add는 또한 터미널에서와 똑같이, 지정한 레지스트리에 그 레지스트리가 알리는 신뢰 정책을 요청하고 받은 것을 고정합니다. 오프라인 워크스페이스에서는 그 가져오기가 어떤 연결도 시도하기 전에 거부되므로, 호출이 identity 또는 key를 제공하지 않는 한 공식 허브가 아닌 레지스트리를 추가하는 것은 같은 문구로 단축 코드 E0310과 함께 거부됩니다. 둘 다 받지 않는 aggrega config init은 오프라인에서 허브만 초기 설정할 수 있습니다. 표준 입력과 출력에서는 이들을 명령을 실행하는 cli-registry-add와 cli-registry-remove로, 초기 설정을 cli-config-init으로 사용할 수 있으며, HTTP에서는 이 도구들이 존재하지 않습니다.
  • pull은 레지스트리에서 읽고, 지정된 워크스페이스 내부에 기록합니다. 해당 Release의 lockfile을 기록하고, 해석한 것으로 아티팩트 캐시를 채우며, 워크스페이스가 연결하는 판정 반환 플러그인 각각의 ID를 lockfile 옆에 기록합니다. pin_sources를 보내거나, pin_sources_at_pull이 켜진 워크스페이스에서 호출이 이를 false로 보내지 않으면, Release가 카탈로그 디렉터리에서 빌드하는 Recipes와 FeatureRecipes에 대해 엔터티 작성자의 고정 단계도 실행하여 각각의 옆에 entity.lock을 기록합니다. 이것이 없으면, 읽는 입력에 대한 고정이 lock에 기록되지 않은 엔터티에 대한 pull은 해당 단계를 명시하며 거부됩니다. 엔터티 파일 자체는 절대 기록되지 않습니다. 이 중 어느 것도 머신을 벗어나지 않으며, 다시 해석하는 것이 기록된 내용을 변경하는 방법이므로, 이는 여기서 기록하는 작업 중 가장 온건한 작업입니다. 이는 워크스페이스 내부에 기록하는, 작성 루프를 위해 설계된 도구 중 하나입니다. pin은 지정한 Recipe 또는 FeatureRecipe 옆에 entity.lock을 기록하며, 이는 엔터티 자체 입력 고정에서 설명합니다. gen-catalog는 지정한 디렉터리 아래에 생성된 Plugin 엔터티를 기록합니다. edit-document는 이미 있는 문서에 하나의 범위가 제한된 구조적 편집을 적용하고 편집이 건드리지 않는 모든 바이트를 보존하며 다시 기록하며, 이는 문서에 하나의 범위가 제한된 편집 적용에서 설명합니다. import는 다른 도구가 생성한 설명을 초안 작성 파일로 변환하여 워크스페이스에 기록하며, 이는 외부 설명을 초안 엔터티로 변환에서 설명합니다. 그리고 example을 보낸 scaffold는 aggrega scaffold --example 명령과 마찬가지로 문서의 실행 가능한 예제 하나를 새 디렉터리 또는 빈 디렉터리인 dir에 기록하며, 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는 반환된 각 경로를 같은 좌표계에서 해당 Release의 잠금 파일 경로에 매핑합니다. 이 파일은 pull이 그 Release에 대해 쓰고 build가 읽는 파일이며, 언어 서버의 Release 응답이 가리키는 파일과 같습니다. 이 매핑은 해당 답이 담은 경로를 설명하므로 페이지를 따르며, 요약에서는 비어 있습니다.

response_format이 받는 값은 detailed와 concise뿐이며, 정확히 일치해야 합니다. 다른 단어, 다른 대소문자, 또는 앞뒤 공백이 있는 등 그 밖의 표기는 거부되며, 거부 시에는 보낸 값과 함께 인수가 허용하는 값을 알려줍니다. 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로도 같은 방식으로, 자세한 결과에서 경로를 하나 골라 작업할 Release로 describe나 build에 넘기십시오.
  • list-releases가 반환하는 경로는 워크스페이스 루트에 대한 상대 경로이며, 이는 list-entities가 파일을 보고하는 좌표계와 같으므로 두 답은 파일 기준으로 맞아떨어져 함께 읽을 수 있습니다. lockfiles 아래의 잠금 파일도 같은 루트에 대한 상대 경로이므로, 파일 위치를 따로 알아내지 않고도 그 파일을 읽거나 비교할 수 있습니다.

두 도구 모두 무엇을 셀지를 파일 이름이 아니라 각 문서 자체의 kind를 읽어 결정합니다. 관례적인 접두사 없이 이름 지어진 Release도 나열되며, 단지 Release처럼 이름만 붙은 파일은 나열되지 않고 실제로 선언한 kind 아래에 나타납니다. kind를 전혀 선언하지 않은 YAML — 차트의 values 파일이나 우연히 트리 안에 있는 구성 파일 — 은 엔터티가 아니므로 보고되지 않으며, 렌더링된 Kubernetes 매니페스트처럼 다른 프로젝트에 속한 문서도 마찬가지입니다. 문서는 kind와 이름을 모두 선언하고 Aggrega 자체 그룹 밖의 apiVersion을 선언하지 않을 때 엔터티로 셉니다. 이 두 가지가 함께 있어야 이후에 그 문서를 지정할 수 있기 때문입니다. 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와 같은 하나뿐입니다. 워크스페이스 구성이 build.authoring_release로 또는 workspace.releases의 키로 지정한 Release는 링크 자체의 위치에서 읽혀 나열되고 링크는 나열되지 않으며, 이 설정 중 하나가 지정한 파일이 Release가 아닌 다른 것을 선언하면 나열되지 않고 그 링크가 나열됩니다. 구성된 카탈로그 디렉터리는 워크스페이스가 다른 곳에 보관된 다른 엔터티를 읽는 방법이므로, 구성이 catalog_dirs 아래에 나열한 디렉터리나 그 아래의 디렉터리로 이어지는 링크는 어느 목록에서도 나열되지 않습니다. 구성이 이미 그곳에 도달했기 때문입니다. list-entities가 카탈로그 디렉터리에서 가져오는 Features에는 카탈로그 디렉터리의 읽기가 머물러야 하는 디렉터리 — 워크스페이스 안의 카탈로그 디렉터리라면 워크스페이스, 구성이 워크스페이스 밖에 지정한 디렉터리라면 그 디렉터리 자체 — 밖으로 이어지는 링크 뒤의 Feature가 결코 포함되지 않으므로, 읽히지 않은 링크 뒤에 있다고 나열된 엔터티가 그 이름 옆에 나열되는 일은 없습니다. 목록이 — 이름, 위치 또는 .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 기준으로 응답합니다.

  • **release를 지정한 list-entities**는 해당 Release가 보는 엔터티를 나열합니다. 나열되는 Features는 그 Release의 카탈로그 디렉터리가 선언하는 것이며, 다른 Releases만 읽는 카탈로그 디렉터리 아래의 워크스페이스 문서는 제외됩니다. 따라서 각 변형은 그것으로 빌드하는 Release에 대해서만 나열되고 다른 Release에 대해서는 나열되지 않습니다. 어떤 카탈로그 디렉터리 아래에도 있지 않은 문서(카탈로그 옆에 작성된 Release, 그 Aggregate, 그 Manifest)는 모든 Release에 대해 나열됩니다.
  • **name과 release를 지정한 describe**는 해당 Release의 카탈로그 디렉터리를 통해 이름을 해석하므로, 여러 변형이 선언하는 이름은 그 Release가 빌드에 사용하는 변형으로 해석됩니다. 해당 디렉터리로 해석되지 않는 이름은 workspace.releases 아래의 해당 Release 항목을 명시하는 설명과 함께 거부됩니다. 레지스트리 참조는 어떤 Release를 지정하든 해당 레지스트리에서 읽으므로 release와 함께 보내면 거부됩니다. name 없이 보낸 release는 여전히 describe가 요약하는 Release입니다.
  • **entity와 release를 지정한 validate**는 단일 엔터티 검사를 해당 Release 기준으로 실행합니다. 엔터티의 참조(Recipe가 구현하는 Component, 필러가 참조하는 SchemaLibrary)는 해당 Release의 카탈로그 디렉터리를 통해 해석되며, 응답은 엔터티와 함께 Release를 명시합니다. 클로저는 검증되지 않으며, entity 없이 보낸 release는 여전히 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 옆 문서들 밖으로 이어지는 링크는 빌드를 중단시키는 것과 마찬가지로 이 작업을 중단시킵니다.

entity를 지정한 validate는 판단할 수 없는 렌더링을 Release 기준이든 아니든 시도하지 않은 것으로 보고합니다. 이 도구는 Recipe의 Component를 연결을 배선하지 않고 Feature를 부착하지 않는 합성 빌드에 배치합니다. 따라서 템플릿(템플릿이 가져오는 파일과 라이브러리 항목 포함)이 .context.inject, .context.uses 또는 .features 아래의 값을 읽는 동안 렌더링이 멈추는 Recipe는 diagnostics가 비어 있는 valid: true로 응답합니다. 그 텍스트에는 Render: not attempted (this Recipe reads values a build of one cannot supply), 렌더링을 보류하게 된 읽기, 렌더링이 멈춘 문장이 담깁니다. 판단 기준은 Recipe가 읽는 내용이므로, 이러한 읽기와 함께 있는 Recipe 자체의 결함도 함께 보류되지만, 구문 분석되지 않는 템플릿과 렌더링이 거부하는 참조는 여전히 valid: false로 응답합니다. aggrega validate도 같은 입력에 대해 같은 판정을 내립니다.

entity를 지정한 validate는 실패한 어서션을 Release 기준이든 아니든 경고로 보고합니다. fail을 호출하는 어서션(Recipe 자체의 어서션 또는 Recipe가 구현하는 Component가 선언하는 어서션)은 diagnostics가 비어 있는 valid: true로 응답합니다. 합성 빌드는 실제 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에서는 하나의 프로세스, 하나의 워크스페이스에서 설명하는 대로 이 인수가 거부됩니다.

둘은 함께 하나의 질문에 두 부분으로 답합니다. 즉 어떤 기능이 없는 것인지, 아니면 단지 여기에 구성되지 않은 것인지입니다. 구성은 provider, importer 또는 거버넌스 검사가 애초에 연결되어 있는지를 알려 주고, 플러그인 읽기는 그 연결이 해석되고, 스스로를 기술하며, 주장하는 것을 제공하는 게스트에 도달하는지를 알려 줍니다. 이 인터페이스의 다른 어느 곳에서도 이 둘은 똑같아 보이지만, 필요한 다음 단계는 정반대입니다.

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 — list-entities가 보고하는 대로의 워크스페이스 엔터티의 metadata.name입니다. 매칭은 해당 문서가 선언한 레이블을 대상으로 실행됩니다.
  • graph_node와 release — 컴파일된 그래프상의 노드로, 그래프가 키를 지정하는 방식 그대로 지정하며, 하위 aggregate가 기여한 노드가 갖는 정규화된 형태도 포함합니다. 매칭은 해당 노드의 최종 레이블, 즉 빌드가 평가하는 레이블을 대상으로 실행됩니다.
  • labels — 노드를 지정하지 않는 단독 레이블 집합입니다. 좌표가 전혀 필요 없으므로, 이미 노드의 레이블을 가지고 있다면 이 형태를 사용합니다. 아무것도 조회하지 않으며 그래프를 다시 빌드하지도 않습니다.

답변에는 매칭에 사용된 레이블과 그 레이블이 세 집합 중 어디에서 왔는지가 담겨 있으므로, 어떤 후보든, 또는 후보가 없다는 사실이든 다시 계산하지 않고 답변 자체로 설명할 수 있습니다. 레이블을 다른 방식으로 다시 읽으면 노드의 레이블에 대한 사용자의 이해와 컴파일러의 이해가 어긋나게 됩니다.

노드가 그리는 하나의 연결에 무엇이 부착될 수 있는지 물으려면 graph_node와 release 옆에 connection을 추가합니다. 이때 작성자가 작성한 그대로의 socket과 alias를 지정합니다. 연결은 소비하는 Component에서 그 소켓이 선언하는 슬롯을 채우는 부착물을 가지므로, 이 경우 답변에는 slots도 포함됩니다. 이는 소켓이 선언하는 각 슬롯과, Component가 선언한 그대로의 selector, required, inject, sensitive, description, 그리고 그 슬롯을 채울 수 있는 candidates입니다. 이들은 노드의 레이블이 적용 가능성을 충족하는 동시에 슬롯의 셀렉터가 자신의 레이블을 허용하는 Features입니다. 이는 빌드가 그러한 부착물에 적용하는 두 가지 규칙이므로, 슬롯의 후보는 항상 노드 자신의 후보에 포함됩니다. 채울 수 있는 것이 없으면 slots는 비어 있고 noSlotReason이 그 이유를 알려 줍니다. feature-created-connection(Feature가 연결을 그렸으며, 그러한 연결에는 아무것도 부착되지 않음), ad-hoc-socket(Component가 선언하지 않은 소켓임), no-slot-declared(소켓이 슬롯을 선언하지 않음)입니다. 빈 slots를 “일치하는 것이 없음”으로 읽지 마십시오. 이유 필드는 바로 그 해석을 배제하기 위해 있으며, 슬롯이 존재하는 경우에는 나타나지 않습니다. 그 옆의 candidates는 노드 자체에 무엇이 부착될 수 있는지라는 원래 의미를 유지하며, document를 보내더라도 여기서는 아무것도 달라지지 않습니다. node나 labels 옆에 지정한 connection, 소켓이나 별칭을 지정하지 않은 연결은 거부되며, 노드가 그리지 않는 연결도 마찬가지로 거부됩니다. 이는 언어 서버가 같은 조건에서 제공하는 것과 동일한 답변입니다.

connection-candidates는 엔터티가 선언한 의존성 소켓과, 소켓별로 해당 소켓이 대상에 대해 선언한 제약 조건을 선언된 레이블이 충족하는 워크스페이스 Components를 보고합니다. 엔터티의 metadata.name을 node로 받습니다. attach-candidates와 달리 좌표 없는 형태가 없습니다. 소켓은 지정된 엔터티 자체의 선언에서 읽기 때문에 여기에는 레이블 집합 형태가 없습니다.

두 부분의 완전성은 같지 않으며, 답변은 어느 쪽이 어떤지 알려 줍니다. 두 부분을 하나의 목록으로 제시하지 마십시오. 대상은 완전합니다. 이는 빌드 중에 같은 제약 조건이 허용하는 component입니다. 소켓은 완전하지 않으며, 완전할 수도 없습니다. 소비자는 연결을 새로 만들 수 있지만 생산자가 선언한 것만 소비할 수 있으므로, 작성자는 카탈로그 엔터티가 선언한 적 없는 소켓을 정당하게 작성할 수 있으며, 선언된 소켓은 유효한 이름의 집합이 아니라 도움이 되는 출발점입니다. 따라서 각 소켓은 declared인지 ad-hoc인지 표시하며, 답변은 해당 엔터티에서 선언되지 않은 소켓이 허용되는지 여부를 알려 줍니다. Component 자체의 의존성 표면은 이를 허용합니다. 작성자가 자신의 애플리케이션 토폴로지를 소유하기 때문입니다. Feature의 부착 표면은 허용하지 않습니다. 부착물은 토폴로지를 작성하는 것이 아니라 부착된 Feature가 선언한 토폴로지에 참여하기 때문입니다. 이러한 개방성은 결함이 아니라 작성의 자유에서 비롯된 결과입니다. 엔터티가 선언하지 않은 이름을 socket으로 전달하면 그에 대해 물을 수 있습니다.

두 도구 모두 답하고 멈춥니다. 어느 쪽도 부착물이나 에지를 생성하지 않고, 파일에 쓰지 않으며, 그러한 편집의 텍스트를 제안하지도 않습니다. 이어지는 편집을 구성하고 적용하는 것은 사용자의 몫입니다.

두 도구 모두 이곳의 다른 모든 답변이 사용하는 것과 동일한 최소 식별 정보, 즉 종류, 이름, 소스 파일만 반환합니다. 엔터티에 대해 표시하고 싶은 나머지 정보는 모두 같은 세 필드로 list-entities에 이미 있으므로, 서로 어긋날 수 있는 두 사본을 읽는 대신 두 답변을 결합합니다. 두 도구 모두 확인할 수 없는 이름에 대해 빈 목록으로 답하지 않고 거부합니다. 이는 표면의 나머지 부분과 같은 이유로, 빈 답변은 오타를 제공할 것이 없는 대상으로 보고하게 되기 때문입니다. labels 호출에는 잘못 입력할 이름이 없으므로, 그 경우의 빈 결과는 말 그대로의 의미입니다.

서버가 참조용으로 읽는 모든 것은 이 머신에서 제공됩니다. JSON Schema는 바이너리에 내장되어 있고, 문서는 아래에 설명된 대로 머신이 유지하는 문서 번들 캐시에서 읽습니다. 시작 문서 초안 작성, 검증, 설명, 빌드, 린트는 모두 워크스페이스와 로컬 캐시를 대상으로 실행되며, 어느 것도 스스로 레지스트리에 접근하지 않습니다. 렌더링은 고정된 외부 참조를 콘텐츠 주소 지정 저장소에서 제공하고, 고정되지 않은 참조는 가져오지 않고 거절합니다. 이 덕분에 검사와 렌더링의 전체 루프가 오프라인으로 유지됩니다. 요청할 수 있는 레지스트리 읽기는 두 가지입니다. 레지스트리 참조를 지정한 describe는 해당 좌표 하나를 가져오고 아무것도 쓰지 않으며, HTTP에서는 제공되는 워크스페이스에 구성된 레지스트리에만 접근합니다. 그리고 example 또는 list를 보낸 scaffold는 워크스페이스의 서명 정책이 승인하는 사본이 머신에 없을 때 워크스페이스의 기본 레지스트리에서 문서 번들을 가져오며, 보관하기 전에 검증합니다. 이는 aggrega scaffold --example 명령이 하는 것과 같습니다. 게시와 서명은 그 반대편에 의도적으로 놓인 것으로, 위에서 다루었습니다.

그 둘 사이에 Release의 의존성 확인이 있으며, 이는 여기서 무언가를 획득하는 유일한 작업입니다. 의존성 확인을 요청받는 것은 곧 가져오기를 요청받는 것이므로 레지스트리에 접근합니다. 요청할 때만 수행되며, 요청하는 방법은 정확히 두 가지입니다 — 그것이 전부인 pull을 호출하거나, 빌드의 첫 단계로 같은 확인을 수행하는 build에 auto_pull을 보내는 것입니다. 그 밖에는 아무것도 사용자를 대신해 가져오지 않으며, auto_pull을 보내지 않은 빌드는 레지스트리에 접근하지 않습니다. 이를 바꾸는 유일한 설정은 워크스페이스 자체의 auto_pull입니다. 그렇게 구성된 워크스페이스는 어디서 실행되든 그 안의 모든 빌드에 먼저 확인하도록 요청하는 것이며, 이는 아래에서 다룹니다.

이러한 참조 읽기 중 유일한 예외는 문서 번들 자체를 획득하는 것이며, 이는 모든 읽기와 별개로 이루어집니다. 번들은 머신당 한 번, 모든 Aggrega 프로젝트가 공유하는 캐시에 레지스트리와 버전별로 하나씩 보관됩니다. 따라서 워크스페이스 캐시를 만들 수 없는 폴더에서 시작된 서버도 번들을 그대로 보관합니다(aggrega cache 참조). 서버는 시작할 때, 보내는 어떤 요청에도 답하기 전에, 워크스페이스 자체의 서명 검사가 허용하는 사본이 그곳에 있는지 확인합니다. 이는 번들 pull이 따르는 것과 같은 검사이며, 사본이 없을 때만 CLI의 나머지 부분이 사용하는 것과 같은 송신 설정을 통해 번들을 pull합니다. 서버가 찾는 번들은 서버가 실행하는 aggrega 버전용으로 게시된 번들이며, 그 버전용으로 게시된 것이 없으면 이전 버전용으로 게시된 번들 중 최신 번들입니다. 이는 aggrega explain과 aggrega scaffold --example이 하는 것과 같은 선택이며, 서버가 제공하는 모든 페이지와 모든 설명은 서버가 얻은 그 번들에서 읽습니다. 따라서 클라이언트가 무엇을 먼저 보내든 무언가가 페이지를 요청할 때쯤이면 페이지는 이미 있으며, 다른 서버나 다른 프로젝트의 aggrega explain은 다시 다운로드하지 않고 같은 사본을 찾습니다.

이후 페이지를 제공하는 것은 그 사본을 읽는 일이며, 어떤 레지스트리에도 접근하지 않습니다. 페이지를 제공하기 전에 사본 옆에 보관된 서명을 워크스페이스의 검사로 다시 검증하므로, 다른 프로젝트의 더 느슨한 설정이 받아들인 사본은 제공되지 않습니다. 검사가 키나 신뢰 루트를 고정하는 경우 이 검증은 오프라인으로 실행되며, 둘 다 고정하지 않는 경우(공식 허브의 내장 검사가 그러한 예입니다) pull과 마찬가지로 공개 Sigstore 신뢰 루트를 가져옵니다. 오프라인 워크스페이스는 그 신뢰 루트를 가져올 수 없으므로, 오프라인에서는 이 머신에서 이전에 온라인으로 가져온 신뢰 루트, 즉 Sigstore 클라이언트가 홈 디렉터리의 .sigstore 아래에 보관하는 캐시에 남겨 둔 신뢰 루트를 기준으로 검증하며(그 가져오기가 얼마나 오래전이었든 상관없습니다) 아무것도 가져오지 않습니다. 한 번도 가져온 적이 없는 머신에서는 검사를 오프라인으로 실행할 수 없으므로 사본이 제공되지 않으며, 로그 스트림이 그 사실을 알립니다. 이 검증은 서버가 실행되는 동안 사본과 검사 조합마다 한 번 실행되고, 그 이후에 읽는 페이지는 검증이 받아들인 결과를 바탕으로 제공됩니다. 그 이후에 가져온 사본, 검사가 다른 워크스페이스(제자리에서 편집된 고정 신뢰 루트 포함), 오프라인에서 수행된 읽기, 또는 머신에 남아 있는 다른 신뢰 루트를 발견한 오프라인 읽기는 각각 따로 검증됩니다. 검사가 거부한 사본은 다음 읽기에서 다시 검사되므로, 그 사이에 이를 받아들인 가져오기가 무효화되지 않습니다. 번들을 획득할 수 없거나, 유일한 사본이 검사가 거부하는 것이고 그 검사로 다시 가져오는 데 실패하더라도 서버는 시작되며 다른 모든 기능은 동작합니다. 문서 요청은 not-found로 응답하고, 서버의 로그 스트림이 그 이유를 알립니다.

Release가 이미 고정한 콘텐츠를 기준으로 빌드하기

build는 Release를 메모리 안에서 아티팩트로 렌더링하며, 렌더링은 원격 URL의 콘텐츠를 요청할 수 있습니다. 예를 들어 원격 참조가 있는 차트의 values 스키마가 그렇습니다. 외부 입력은 호출 동안 고정됩니다. Release의 lockfile이 이미 고정한 참조는 콘텐츠 주소 지정 저장소에서 제공되며, 이는 가져오기가 아니라 이미 디스크에 있는 콘텐츠를 읽는 것입니다. lockfile이 고정하지 않은 참조는 가져오지 않고 거부되며 그 이름이 제시됩니다. 요청한 것은 렌더링이며, 참조를 획득하면 바이트를 생성하는 부수 효과로 네트워크에 접근하고 저장소에 blob을 쓰게 되기 때문입니다. 이 고정은 렌더링의 속성입니다. 획득하는 단계는 해석(resolve)입니다. 해석은 Release를 렌더링하여 그 렌더링이 어떤 원격 참조를 요청하는지 알아내고, 그것들을 가져온 뒤, 의존성 고정을 담는 동일한 lockfile 쓰기에 기록합니다. 따라서 해석이 바꾸는 것은 렌더링이 실행될 때까지 어떤 참조가 고정되어 있는가이며, 렌더링이 접근할 수 있는 대상은 결코 바꾸지 않습니다. 어떤 해석도 고정하지 않은 참조는 먼저 해석한 호출에서도 해석하지 않은 호출에서와 똑같이 거부됩니다.

파일은 실제 빌드가 내보내는 바이트 그대로 반환되며, 이를 참으로 만드는 것은 두 가지가 함께 작용하기 때문입니다. 하나는 위의 고정입니다. 고정된 참조는 가져오지 않고 저장소에서 읽습니다. 다른 하나는 읽어 들이는 lockfile이 여전히 Release가 해석되는 결과를 기술한다는 점입니다. 그래서 build는 이를 확인하고, 더 이상 일치하지 않는 lockfile을 터미널에서 aggrega build가 하는 것과 똑같이 거부합니다. 고정된 바이트를 읽는다는 것만으로는 그것이 읽어야 할 올바른 바이트였는지에 대해 아무것도 말해 주지 않습니다.

lockfile의 세 가지 상태 모두를 들어, 동작 방식을 명시합니다. lockfile이 전혀 없으면 build는 작업 공간이 이미 고정한 것으로 렌더링하고, 제공할 수 없는 외부 참조는 하나하나 이름을 제시하며 모두 거부합니다. 그대로 두면 lockfile을 요구하지도 쓰지도 않으며, 이는 위의 확인으로도 바뀌지 않습니다. 비교할 lockfile이 없으므로 아무것도 거부되지 않습니다. lockfile이 일치하면 렌더링합니다. lockfile이 더 이상 일치하지 않으면 거부하며, 거부 메시지는 해결 방법을 제시합니다. 같은 release로 upgrade_targets 없이 pull을 호출하면 lockfile을 Release가 현재 해석되는 결과와 맞춥니다. 거부 메시지에는 같은 작업의 터미널 형식인 aggrega pull --release <release>도 담겨 있습니다. 어느 호출로든 해결됩니다. 두 곳에서 접근할 수 있는 하나의 작업이지, 둘 중에서 골라야 하는 두 가지 지시가 아닙니다. pull이 완료되었는데도 거부가 다시 돌아온다면 두 호출이 서로 다른 입력으로 해석한 것입니다. 대개는 catalog_dirs를 한쪽에만 지정했거나 두 호출 사이에 작업 공간 구성이 편집된 경우이며, 거부 메시지가 이를 알려 줍니다. 두 호출에 같은 입력을 지정하십시오.

release만 전달한 validate와 describe도 같은 lockfile을 따릅니다. Release가 해석되는 결과와 더 이상 일치하지 않는 lockfile에 대해서는 둘 다 응답하지 않고 거부하며, 그 텍스트에는 build가 거부할 때의 드리프트 중단과 같은 해결 방법이 담깁니다. 이는 aggrega validate --release와 aggrega inspect --closure가 터미널에서 거부하는 방식과 같습니다. lockfile이 일치하거나 없으면 둘 다 평소대로 응답합니다.

빌드에 의존성을 먼저 해석하도록 요청하기

auto_pull을 보내면 빌드가 렌더링 전에 해석합니다. pull이 수행하는 것과 같은 해석을 수행하며(빌드용으로 따로 작성된 작업이 아니라 그 작업 자체이므로, 빌드로 채운 작업 공간과 pull 호출로 채운 작업 공간은 똑같이 채워집니다), Release의 lockfile을 쓴 다음 쓴 내용을 기준으로 렌더링합니다. 이 단계는 레지스트리에 접근하고 씁니다. build의 다른 어떤 부분도 그렇게 하지 않으며 예외는 write뿐이고, write는 레지스트리에 접근하지 않습니다. 그래서 이 단계는 요청하지 않으면 꺼져 있습니다.

프로토콜을 벗어나지 않고 위의 두 가지 거부에 대응합니다. 아무도 아직 해석하지 않은 Release는 마침 있는 고정으로 렌더링하고 나머지는 거부합니다. 어긋난 lockfile은 빌드를 곧바로 중단시킵니다. auto_pull을 보내면 먼저 해석하고 이 빌드가 대상으로 하는 클로저에서 도출한 lockfile을 기준으로 렌더링하므로, 두 경우 모두 가서 고쳐야 할 문제가 아니라 렌더링 결과로 돌아옵니다. 해석과 렌더링을 별도 단계로 나누고 싶다면(렌더링하기 전에 무엇이 고정되었는지 읽기 위해) pull을 호출한 다음 build를 호출하십시오. 이는 중간에 확인하는 과정이 들어간 같은 두 작업입니다.

한 번의 호출은 Release를 한 번 렌더링합니다. Release가 어떤 원격 참조를 사용하는지 알아내는 일 자체가 렌더링이므로, 해석은 이미 빌드 대상인 Release를 렌더링한 상태입니다. 방금 쓴 고정을 기준으로, 빌드가 실행하는 모든 검사를 거쳐서입니다. 빌드는 렌더링을 반복하지 않고 그 렌더링으로 응답하며, 그래서 auto_pull을 보내는 비용은 두 번째 렌더링이 아니라 해석 한 번입니다. 이렇게 사용되는 것은 완료된 렌더링뿐입니다. 해석이 의존성은 고정했지만 외부 참조 탐색을 끝내지 못한 경우, 빌드는 실제로 반영된 고정을 기준으로 직접 렌더링하며, 이때 고정되지 않은 참조는 빌드가 내보내는 것에 못 미치는 파일 목록으로 돌아오는 대신 이름이 제시되며 빌드를 중단시킵니다.

돌아오는 응답이 무엇이 해석되었는지 알려 줍니다. 채운 빌드는 응답에 pull이 응답하는 형태의 dependency_resolution을 담습니다. 쓴 lockfile, 해석이 접근한 모든 참조와 각각 해석된 버전 및 이 빌드의 해석이 그것을 가져온 위치, 이후 lockfile이 담고 있는 개수, 그리고 해석 자체의 경과를 한 줄씩 기록한 내용입니다. 채우지 않은 빌드에는 이 필드가 아예 없으므로, 필드의 존재 여부로 디스크를 읽지 않고도 둘을 구별할 수 있습니다. 렌더링된 파일은 다른 빌드와 똑같이 보고되며, 호출에 write도 보내지 않았다면 여전히 메모리 안에서 반환됩니다. 해석은 lockfile과 아티팩트 캐시를 쓸 뿐, 아티팩트는 결코 쓰지 않습니다.

작업 공간은 이를 상시로 요청할 수 있으며, 호출로는 이를 끌 수 없습니다. 작업 공간 자체의 auto_pull 설정은 그 작업 공간의 모든 빌드에 같은 단계를 켜며, 호출의 auto_pull은 그 설정을 덮어쓰지 않고 더해집니다. 둘 중 하나만으로 충분하며, 작업 공간이 요청한 해석을 억제하는 인수는 없습니다. 이는 터미널에서 설정과 aggrega build --auto-pull이 결합하는 방식과 같으므로, 하나의 작업 공간은 빌드가 어느 표면으로 도착하든 같은 방식으로 응답합니다.

거부는 흡수되지 않고 보고되며, 이 바이너리에 포함된 provider에서는 거부가 렌더링을 중단시킵니다. 참조를 요청한 provider가 거부를 돌려주므로, 호출은 그 실패로 응답하고 파일을 반환하지 않습니다. 참조는 읽는 사람이 조치할 수 있는 곳에 그것을 고정하는 명령과 함께 제시됩니다: aggrega pull --release <path>. 같은 고정은 이 표면에서 pull 도구로도 할 수 있습니다. 아래 Release가 의존하는 대상 해석하기에서 설명하며, 이 거부를 만난 어시스턴트는 프로토콜을 벗어나지 않고 조치할 수 있습니다. 모든 것이 고정된 렌더링은 이에 대해 아무것도 말하지 않습니다. 고정이 무엇을 가져오고 기록하는지는 aggrega pull을, 고정되지 않은 참조가 같은 방식으로 보고되고 실행을 중단시키는 경우는 aggrega build를 참조하십시오.

aggrega build가 쓰는 위치에 아티팩트 쓰기

write를 보내면 완료된 렌더가 aggrega build가 쓰는 위치인 워크스페이스 루트의 dist/에도 기록됩니다. 이 디렉터리는 명령줄이 같은 워크스페이스 루트 아래에 구성하는 디렉터리이고, 쓰기도 명령줄이 수행하는 쓰기와 같습니다. 따라서 한 워크스페이스의 한 Release에 대해 aggrega build, outputParent를 지정하지 않은 언어 서버의 aggrega/build, 그리고 이 호출은 바이트 단위로 동일한 하나의 트리를 쓰고, 그 디렉터리를 같은 방식으로 알려 줍니다. 명령의 마지막 줄, 언어 서버의 outputDirectory, 이 응답의 output_dir이 그것입니다. 워크스페이스 밖으로 이어지는 링크인 dist는 터미널에서와 마찬가지로 그 안의 어떤 것도 제거되거나 쓰이기 전에 거부됩니다. 기본값처럼 생략하면 아티팩트는 메모리로 반환되고 아무것도 쓰이지 않습니다.

워크스페이스 루트는 호출 자신의 것입니다. 표준 입출력에서는 호출이 어느 워크스페이스에서 응답되는가에서 설명한 대로 호출이 확인한 워크스페이스의 루트입니다. 즉 workspace_root가 지정하는 루트, 없으면 서버가 실행될 때 받은 루트, 그것도 없으면 서버가 시작된 디렉터리에서 찾은 워크스페이스이며, 절대 경로로 지정된 Release가 호출을 그 Release 자신의 워크스페이스로 옮기는 경우에는 그 워크스페이스의 루트입니다. 이는 같은 Release와 같은 지정 루트에 대해 aggrega build가 그 아래에 쓰는 루트이므로, 서버가 우연히 실행 중인 폴더는 그 폴더가 호출이 확인한 루트일 때에만 dist를 받습니다. 그 폴더에서 연 터미널에서와 같습니다. HTTP에서는 서버가 제공하는 워크스페이스이며, 그 밖에는 아무것도 쓰이지 않습니다.

쓰기는 워크스페이스에 도달하므로 HTTP에서는 aggrega:workspace-write가 필요합니다. write를 받은 호출은 의존성을 먼저 해결하는 빌드와 똑같이 그 호출에 대해 워크스페이스에 도달합니다. aggrega:read만 가진 자격 증명에는 aggrega:workspace-write를 지정한 403으로 응답하고 아무것도 쓰지 않으며, mcp.deny_reach가 workspace를 지정하는 서버는 그 설정을 지정하며 호출을 거부합니다. 이 도구는 모든 호출자의 도구 목록에 남아 있으며, write를 받지 않은 빌드는 읽기 범위의 호출자도 계속 사용할 수 있습니다.

쓰기는 마지막에 합니다. auto_pull도 함께 보내면 호출은 해결, 렌더, 쓰기를 이 순서로 수행합니다. 그보다 앞선 어느 지점에서든 거부된 호출(Release, 워크스페이스, 카탈로그 디렉터리, 해결, 렌더)은 아티팩트를 쓰지 않습니다.

응답은 쓰인 것을 알려 줍니다. output_dir은 디렉터리(표준 입출력에서는 전체 경로, HTTP에서는 dist)이고, files는 쓰인 각 파일을 그 디렉터리 기준 상대 경로로 나열하며, response_format: detailed에서는 내용과 함께, concise에서는 경로만 담습니다. 텍스트는 몇 개의 파일이 어디에 쓰였는지 알려 줍니다. write를 받지 않은 호출에는 output_dir이 없으므로, 이것이 없으면 아무것도 쓰이지 않았음을 알 수 있습니다. 렌더가 끝난 뒤 실패한 쓰기(예: 아무도 쓸 수 없는 워크스페이스 루트에 쓰는 경우)는 디렉터리와 원인을 지정한 실패로 응답하며, 어떤 파일도 쓰인 것으로 나열하지 않습니다. 쓰기의 일부가 디스크에 남아 있을 수 있으며, 렌더된 파일을 쓰인 것으로 알리면 실제로 일어난 것보다 많은 것을 주장하게 되기 때문입니다.

디렉터리를 지정하는 인수도, 추적을 요청하는 인수도 없습니다. 아티팩트가 어디로 갈지는 호출이 아니라 호출이 확인한 워크스페이스가 결정하며, 여기에서 쓰인 빌드는 출력 옆에 .trace 디렉터리를 남기지 않습니다. 추적되는 빌드는 aggrega build --trace입니다.

빌드가 파일 외에 알려 주는 것

빌드는 자신이 제기한 모든 권고를 응답 자체에 담습니다. 이는 aggrega build가 작업하는 동안 출력하는 발견 사항입니다. 선언된 이름과 한 번의 편집 차이인 이름, 아무것도 읽지 않는 매개변수, 작성된 필드를 따를 수 없는 대상, 중단을 일으키지 않는 거버넌스 판정, Release가 확장하는 Release로부터 상속했지만 같은 경로로 해석되는 경계 디렉터리, Release가 도달하는 Component나 Feature가 values와 infra 두 축 모두에 선언한 속성 등이 이에 해당합니다. 이들 중 어느 것도 결과를 바꾸지 않습니다. 권고를 담은 빌드도 성공한 것이며, 반환하는 파일은 빌드가 생성한 파일입니다. 권고는 터미널이 출력하는 순서대로 도착하므로, 둘을 비교하는 사람은 두 개가 아닌 하나의 순서를 보게 됩니다. 먼저 렌더링이 제기한 모든 것이 제기된 순서대로 오고, 이어서 Release와 그것이 도달하는 대상에 관한 발견 사항이 오며, 이는 aggrega build가 렌더링이 반환된 뒤 출력하는 것입니다. 마지막으로 write를 보낸 빌드에서는 쓰기 과정에서 자신의 파일 옆에서 발견한, 자신이 쓰지 않은 각 파일을 지목하는 경고가 오며, 그 파일들은 그대로 남겨 둡니다. 이는 aggrega build가 파일을 모두 쓴 뒤 출력하는 경고입니다(빌드가 쓰지 않은 파일).

권고가 요약 텍스트에만 있지 않고 응답에 담기는 것은 이 인터페이스를 구동하는 어시스턴트가 터미널을 읽지 않기 때문이며, 아무도 알려 받지 못한 발견 사항은 발견되지 않은 것과 같기 때문입니다. 각 항목은 severity(주의가 필요한 것에는 warn, 기록된 관찰에는 info)와 message를 담습니다. 해당 분류가 코드를 부여하는 경우 code를 담으므로 텍스트를 대조하지 않고도 특정 조건에 대응할 수 있습니다. 또한 발견 사항이 작성된 문서의 특정 키에 관한 것인 경우, 그 키를 가리키는 key_path를 담습니다. 배포된 토폴로지의 형태에 관한 발견 사항은 좌표가 문서가 아니라 배포에 속하므로 키를 가리키지 않으며, 대신 무엇에 관한 것인지를 메시지에서 설명합니다.

터미널이 출력하는 발견 사항 중 두 종류는 advisories가 아닌 다른 곳으로 이 응답에 도달합니다. 각각 더 많은 것을 알려 주는 자리가 있기 때문입니다. 기록된 지원 중단 표시는 잠금 파일이 고정된 참조에 대해 기록한 것이든, 그 옆의 플러그인 신뢰 기록이 수락 또는 거부 판정을 반환하는 역할로 연결된 플러그인에 대해 기록한 것이든 deprecations에 있습니다. Release에 대한 describe는 같은 집합을 자체 deprecations에 명시하고, Release에 대한 validate는 notices 중에 명시하며, 둘 다 판정은 그대로 둡니다. 존재하지만 읽을 수 없는 신뢰 기록이 있으면 아무것도 기록하지 않은 기록으로 통과되는 대신 두 호출 모두 거부됩니다. 엔터티가 상속하는 부모를 해석할 수 없으면 빌드가 중지되므로, 이는 아무것도 바꾸지 않은 발견 사항으로 나열되지 않고 거부 텍스트에 명시됩니다. 한 종류는 응답이 담는 것이 아니라 이 도구가 로드하는 것에 의해 제한됩니다. aggrega build는 Release를 해석하기 전에 구성된 모든 카탈로그 디렉터리를 로드하며, 지원 중단된 카탈로그 형태에 관한 알림은 그 로드에서 나옵니다. 반면 이 도구는 Release가 도달하는 것만 읽고 그러한 로드를 수행하지 않으므로 그런 알림을 보고하지 않습니다. 현재는 그런 알림을 제기하는 빌드가 없으므로 둘은 같은 발견 사항을 보고합니다.

아무것도 제기하지 않는 Release는 아무것도 말하지 않습니다. 키는 비어 있는 채로 존재하는 것이 아니라 아예 없으므로, 키가 존재한다는 것만으로 읽을 내용이 있음을 알 수 있습니다.

거부된 빌드가 돌려주는 것

거부된 빌드는 성공한 빌드가 응답하는 것과 같은 필드로 응답하며, 실행이 진행된 만큼 채워집니다. 응답은 실패로 표시되고 수정 방법을 텍스트로 담으며, 구조화된 페이로드는 그 텍스트로 대체되지 않고 텍스트 옆에 함께 놓입니다. Release가 렌더링되는 동안 발생한 거부는 아래 렌더링 중 발생한 거부에서 설명하듯 컴파일러의 문구로 표현되며, 고유한 필드 하나를 추가합니다. 권고 사항도 여기에 포함됩니다. 실행된 단계는 발생시킨 것을 발생시켰고, 그것들이 거부를 넘어서기 위해 조치해야 할 발견 사항이므로, 파싱해야 하는 산문이 아니라 매칭할 수 있는 항목으로 전달됩니다. deprecations와 declined_external_inputs도 같은 이유로 포함됩니다. 기록된 마커는 마커가 기록되었기 때문에 보고되고, 거절된 참조는 참조가 거절되었기 때문에 보고되며, 어느 사실도 실행이 어떻게 끝났는지에 따른 결과가 아닙니다.

files는 거부 시 아무것도 보고하지 않으며, 결과를 읽어야 할 필드가 아닙니다. 아무것도 출력되지 않았으므로 이름을 댈 아티팩트가 없습니다. 키의 존재 여부로 분기하지 마십시오. 키는 어느 경우든 보고되며, 빈 files만으로는 거부된 빌드와 실행되었지만 아무것도 출력하지 않은 빌드를 구별할 수 없습니다. 결과의 실패 플래그를 읽으십시오. 그것이 프로토콜 자체의 판별자입니다. 그리고 files는 그 본래 의미대로, 즉 렌더링된 것의 목록이자 호출에 write가 전달된 경우 기록된 것의 목록으로 읽으십시오.

거부 시 권고 사항의 범위를 정하는 것은 응답이 담을 수 있는 것이 아니라 실행이 진행된 정도입니다. Release가 해석되기 전에 실행되는 검사에서 나온 거부, 즉 캐시에 고정된 항목이 그에 대해 기록된 다이제스트와 더 이상 일치하지 않고 고정된 바이트를 가진 카탈로그 디렉터리도 없는 경우나, Release가 의존하는 것을 해석할 수 없는 경우의 거부는 권고 사항을 보고하지 않습니다. 아직 아무것도 발생하지 않았기 때문입니다. Release가 확장하는 Release와 어떻게 구성되는지에 관한 발견 사항은 해석되는 즉시, 뒤따르는 모든 검사보다 먼저 발생하므로, 이후의 모든 거부가 이를 담습니다. 예를 들어 Manifest가 타입을 그것을 구현하지 않는 recipe에 매핑하는 경우, Release가 도달하는 엔터티가 스키마를 충족하지 않는 경우, lockfile이 Release가 해석되는 결과와 더 이상 일치하지 않는 경우입니다. 렌더 자체의 발견 사항은 렌더가 실행되는 동안 발생하므로, 그 이전 검사 중 하나에서 나온 거부는 이를 전혀 담지 않고, 렌더에서 나온 거부는 그보다 먼저 발생한 모든 것을 담습니다. 따라서 거부 시의 advisories는 성공 시와 똑같이 읽으십시오. 이번 실행이 발견한 것이며, 터미널이 출력하는 순서를 따릅니다.

엔터티가 해석할 수 없는 부모로부터 상속하여 발생한 거부는 그러한 상속을 모두 텍스트에 명시하며, aggrega build가 출력하는 문구를 사용하므로 어느 것을 고쳐야 하는지 알 수 있습니다. 그 세부 사항이 빌드가 멈춘 이유이며, 그래서 아무것도 바꾸지 않은 발견 사항들 사이가 아니라 텍스트에 있습니다. 그보다 먼저 발생한 구성 발견 사항은 이후의 다른 거부와 마찬가지로 advisories에 있습니다.

Release가 읽는 카탈로그 디렉터리를 탐색할 수 없으면, aggrega build가 거부하는 것처럼 아무것도 기록되기 전에 거부됩니다. 이는 호출이 catalog_dirs에 지정했지만 존재하지 않는 디렉터리(aggrega build가 존재하지 않는 --catalog 디렉터리를 거부하는 것과 같습니다)이거나, 존재하지만 읽을 수 없는 디렉터리입니다. aggrega build는 Release를 해석하기 전에 Release가 읽는 모든 디렉터리를 로드하고, 탐색할 수 없는 디렉터리에서 멈춥니다. build는 같은 디렉터리들을 먼저 탐색하되 그 안의 문서는 읽지 않으며, 모든 의존성 해석과 렌더보다 먼저 수행합니다. 따라서 auto_pull이 전달된 빌드는 lockfile을 기록하지 않으며, 아무것도 렌더링되지 않습니다. 텍스트는 명령줄이 보고하는 방식대로 한 줄에 디렉터리를 명시합니다. 디렉터리, catalog load, 그리고 파일 시스템이 제시한 이유입니다. 페이로드는 Release를 명시하며, 아무것도 실행되지 않았으므로 빈 files와 함께 발견 사항이 없습니다. 워크스페이스 구성이 나열한 디렉터리가 디렉터리가 아닌 경우(예를 들어 그곳에 아무것도 존재하지 않는 경우) 그 탐색보다 먼저 같은 형태로 거부되며, 텍스트에는 aggrega build가 그에 대해 내는 거부가 담기고, 해당 항목과 그것을 나열한 구성 파일 및 줄이 명시됩니다(로컬 엔터티를 읽는 위치). 읽기가 머물러야 하는 디렉터리 밖으로 이어지는 링크를 담은 카탈로그 디렉터리도 같은 시점에 거부되며, 아무것도 기록되지 않고, 텍스트는 링크와 그 링크가 이어지는 곳을 명시합니다. aggrega build도 같은 방식으로 이를 거부합니다.

두 부분을 구체적으로 보여 주는 예시 형태입니다. 어떤 참조도 읽지 않는 매개변수를 선언하고 이후 렌더를 완료할 수 없는 Release는, 텍스트에는 렌더의 거부를 담고 페이로드에는 severity, message, code, key_path를 갖춘 읽히지 않은 매개변수 권고 사항을 담은 실패로 돌아옵니다. 이 항목은 같은 Release가 렌더를 완료했을 때 응답에 보고하는 것과 같은 값을 가진 같은 항목이며, 렌더를 멈춘 원인에 대한 refusal 항목 옆에 놓입니다. 다른 Release를 확장하여 템플릿 변수가 없는 경계 디렉터리를 상속하고, 그 Manifest가 타입을 그것을 구현하지 않는 recipe에 매핑하는 Release는, 상속된 디렉터리마다 advisories 항목 하나씩을 가진 그 거부로 돌아오며, 각 항목의 code는 inherited-boundary-directory-is-literal입니다. 나열된 카탈로그 디렉터리가 모두 존재하는 워크스페이스에서 의존성을 해석할 수 없는 Release는 advisories 키가 전혀 없는 실패로 돌아옵니다. 멈춘 시점에 아무것도 발생하지 않았기 때문입니다.

렌더링 중에 발생한 거부

컴파일러가 렌더링 중에 거부하는 Release — Component가 선언하지 않은 슬롯을 지정하는 Workload, 실패하는 어서션, 평가할 수 없는 템플릿 — 는 컴파일러의 문구로 된 거부와 그 아래의 모든 원인과 함께 반환됩니다. 이는 같은 Release에 대해 cli-build가 반환하는 문구로, 렌더링 중인 노드와 그 안에서 거부한 대상을 차례로 담습니다. 거부가 등록된 조건을 지정하는 경우, 텍스트에는 explain-error처럼 그 조건의 이름, 즉 매칭에 사용할 짧은 코드와 설명 코드가 추가됩니다. 텍스트는 어느 단계에서 거부했는지로 시작합니다. 렌더가 발생시킨 거부에는 The build failed during rendering; nothing was written to disk., 아무것도 렌더링되기 전에 컴파일러 실행이 발생시킨 거부 — 렌더가 기반으로 하는 그래프의 구성이 거부하는 경우, 또는 Component나 Feature가 선언한 어서션 — 에는 The build refused before rendering anything; nothing was written to disk.가 사용됩니다.

페이로드는 같은 거부를 하나의 항목 refusal로 담습니다. 따라서 문서를 변경해야 하는 호출자는 문장을 파싱하지 않고도 어느 문서의 어디인지 읽을 수 있습니다.

  • file — 거부가 가리키는 문서입니다. Workload의 Recipe, 실패하는 어서션을 선언하는 Recipe 또는 FeatureRecipe, 그래프 구성이 거부하는 항목을 작성한 Release 또는 Aggregate이며, 어떤 문서도 가리키지 않는 거부에는 Release의 Aggregate입니다.
  • key_path — 거부가 키를 지정하는 경우 그 문서 안의 키입니다. Workload에 관한 거부에는 .spec.workload, 실패하는 어서션에는 .spec.assertions 아래의 해당 어서션 키, 항목에 대한 거부에는 해당 항목의 키입니다. Workload에 관한 거부는 workload 키에 배치되며 그보다 세밀하게 배치되지 않습니다. 검사가 판단하는 Workload는 템플릿이 생성한 것이고, 템플릿은 작성자가 직접 쓰지 않은 줄을 쓰기 때문입니다. 거부가 렌더링된 Workload 내부에서 지정하는 경로는 message에 남습니다.
  • line과 column — 그 키의 위치로, 1부터 세며 열은 UTF-16 단위입니다. 거부가 키를 지정하지 않거나 문서에 그 키가 없으면 존재하지 않습니다. 위치는 찾은 경우에만 제공됩니다.
  • severity — halt, 빌드를 중단시킨 발견 사항의 심각도입니다.
  • code와 short_code — 거부가 등록된 조건을 지정하는 경우 그 조건의 두 식별자입니다.
  • message — 거부의 텍스트로, 답변 텍스트에 나타나는 것과 정확히 같습니다.
  • findings — 그래프 구성이 발견한 모든 위반을 묶는 것처럼 거부가 여러 발견 사항을 묶는 경우에만 존재합니다. 발견 사항마다 하나의 항목이 거부가 서술하는 순서대로 있으며, 각각 같은 형태로 자체 file, key_path, line, column, severity, code, short_code, message를 가집니다. 이때 거부 자체의 필드는 첫 번째 발견 사항이 가리키는 위치를 지정하고, message는 텍스트와 마찬가지로 모든 발견 사항을 담습니다. 명령줄은 각 발견 사항을 개별 진단으로 출력합니다.

이 항목은 컴파일러 자체 실행이 거부할 때마다 존재합니다. 렌더링 중이든, 렌더링 전 — 그래프 구성 단계, 또는 Component나 Feature가 선언한 어서션 단계(이 경우 문서를 지정하지 않으므로 항목은 Aggregate를 지정합니다) — 이든 마찬가지입니다. 성공한 빌드에는 이 항목이 없으며, 컴파일러가 시작되기 전에 실행되는 검사 — 잠금 파일, Manifest의 매핑, Release가 의존하는 대상 — 가 거부한 빌드에도 없습니다. 이 경우 거부는 텍스트뿐입니다. 작성자가 민감하다고 선언한 값은 컴파일러가 거부를 발생시키는 지점에서 거부로부터 제외되므로, 항목과 텍스트는 cli-build와 터미널이 담는 내용을 담습니다. 선언된 값에 대해 거부가 말하는 내용을 참고하십시오.

Release가 의존하는 것 해석하기

pull은 Release의 카탈로그 및 소스 의존성을 로컬 캐시로 해석하고 해당 Release의 lockfile을 작성합니다. 이 도구가 이 인터페이스에 있는 데는 짚어 둘 만한 이유가 있습니다. 앞에서 설명한 두 가지 거부, 즉 고정되지 않은 외부 참조를 거절한 렌더와 lockfile이 더 이상 Release가 해석되는 결과와 일치하지 않아 중단된 빌드는 모두 고정(pinning)으로 해결되는데, 명령 실행을 사용자에게 요청해야 하는 어시스턴트는 이를 스스로 해결할 방법이 없기 때문입니다. 무엇을 쓰는지, 그리고 그 범위가 어디까지인지는 어시스턴트가 먼저 묻지 않고 할 수 있는 일을 참고하십시오.

release에 Release 경로를 절대 경로 또는 워크스페이스 루트 기준 상대 경로로 전달합니다. 이는 여기의 다른 모든 경로 인수가 따르는 것과 같은 계약입니다. workspace_root와 catalog_dirs는 build에서와 똑같이 워크스페이스 및 카탈로그 탐색을 재정의합니다. 두 인수 모두 표준 입력과 출력으로 연결된 서버에서 유효하며, HTTPS에서는 이 두 인수가 거부되고 경로는 하나의 프로세스, 하나의 워크스페이스에서 설명하듯 프로세스가 제공하는 워크스페이스 안으로 해석되어야 합니다.

기본적으로 다시 해석하지 않고 조정합니다. lockfile에 이미 기록된 고정은 존중되어 해당 버전으로 가져오며, 레지스트리가 더 이상 그 바이트를 제공하지 않으면 조용히 다시 고정하지 않고 거부합니다. 고정이 없는 참조, 즉 새로 추가되었거나 lockfile에서 수동으로 제거된 참조는 새로 해석되어 추가됩니다. 해석된 의존성에 더 이상 포함되지 않는 참조는 제거됩니다. 따라서 의존성 집합이 바뀌지 않았다면 파일은 기록된 타임스탬프까지 포함하여 바이트 단위로 동일하게 유지되므로, 고정을 하나도 바꾸지 않은 호출은 나중에 워크스페이스를 검토하는 사람에게 아무 diff도 만들지 않습니다.

verify는 비교만 하고 lockfile은 그대로 둡니다. 기록된 lockfile을 위의 조정 호출이 지금 수행할 해석과 비교하며, 기록된 고정을 그 호출과 똑같이 존중합니다. 차이(drift)가 있거나 비교할 lockfile이 없으면 실패로 돌아오므로, 어시스턴트는 무언가가 lockfile을 다시 쓰기 전에 고정이 필요한지를 이 방법으로 알아냅니다. 그 호출이 기록하는 것은 아무것도 쓰지 않습니다. lockfile도, 그 옆에 기록되는 플러그인 식별 정보도, entity.lock도 쓰지 않지만, 콘텐츠 캐시는 그 호출과 똑같이 읽고 채웁니다. 또한 lockfile이 기록한 툴체인, 즉 파일을 쓴 컴파일러 버전과 그 컴파일러에 포함된 각 코어 플러그인의 버전도 보고합니다. 이는 감사 목적으로 보고될 뿐 실행 중인 바이너리와는 절대 비교하지 않습니다. 툴체인은 lockfile이 고정하는 대상이 아니며, 이를 검사하면 간접적으로 컴파일러를 고정하게 되기 때문입니다. 툴체인 차이는 drift가 아닙니다.

upgrade_targets는 지정한 참조만 다시 해석하고 그 외에는 아무것도 하지 않습니다. 버전이 붙은 형태가 아니라 작성된 그대로의 형태, 예를 들어 core/database로 하나 이상의 엔티티 URI를 지정합니다. 지정된 각 고정은 삭제된 뒤 사용 가능한 가장 높은 버전으로 다시 해석되며, 다른 모든 고정과 기록된 외부 입력은 변경되지 않고 유지됩니다. 기록된 고정이나 구성된 attachment 어느 것과도 일치하지 않는 URI는 무시되지 않고 거부됩니다.

모든 것을 한 번에 다시 해석하는 인수는 의도적으로 없습니다. 명령줄에는 그런 형태가 있으며, 현재 레지스트리 상태에서 다시 해석하기 전에 lockfile 전체를 폐기합니다. 이 인터페이스에는 그 인수가 존재하지 않으므로, 그런 호출은 받아들여진 뒤 거부되는 것이 아니라 아예 구성할 수 없습니다. 프로토콜 스트림을 지켜보는 사람이 없으므로 전체 폐기를 확인해 줄 사람도 없기 때문입니다. 필요하다면 표준 입력과 출력에서만 cli-pull이 명령을 실행하며, 이는 사람이 있는 인터페이스입니다. HTTP로 이 서버에 연결하는 호출자는 대신 호스트의 터미널에서 실행합니다. verify는 upgrade_targets와 함께 쓸 수 없고(하나는 lockfile을 그대로 두고 다른 하나는 다시 씁니다), 값이 무엇이든 pin_sources와도 함께 쓸 수 없습니다. 이 인수는 해석 과정에서 entity.lock에 빠진 고정을 기록할지 아니면 그 때문에 거부할지를 결정하는데, 비교는 entity.lock을 쓰지 않으므로 둘 다 하지 않기 때문입니다. 두 조합 중 하나를 보내는 호출은 아무것도 해석하기 전에 그 조합을 명시하는 문장과 함께 거부됩니다. 도구가 공개하는 스키마는 이 두 가지 배타 관계를 명시하지 않는데, 이를 렌더링하는 클라이언트가 verify를 보내야 한다는 요구 사항으로 읽을 수 있기 때문입니다. 클라이언트는 거부를 통해 이를 알게 됩니다. 명령줄과 데몬도 같은 조합을 거부합니다.

결과는 무언가가 해석되었다는 사실만이 아니라 무엇이 해석되었는지를 알려 줍니다. 결과에는 작성했거나 비교한 lockfile, resolved(해석이 도달한 모든 참조와 각각이 해석된 버전, 해석이 기록하는 경우 작성자가 쓰는 kind, 그리고 source: 이번 실행이 참조를 가져온 곳으로, 같은 해석에 대해 aggrega pull --detail이 출력하는 단어인 fetched-fresh, cache-reuse, local, in-binary 또는 external), 이후 lockfile이 보유한 소스 아티팩트, 외부 입력, 신뢰된 플러그인 식별 정보의 개수, 그리고 diagnostics(해석이 각 줄을 출력한 순서대로 기록한 자체 설명으로, 어떤 고정이 재사용되었는지, 어떤 서명이 확인되었는지, 어떤 버전이 철회되어 건너뛰어졌는지)가 포함됩니다. 이 줄들은 명령을 실행하면 터미널에 표시되지만, 여기서는 답변에 포함됩니다. 터미널을 읽지 않는 호출자는 달리 받을 방법이 없기 때문입니다. verified는 비교에서만 존재하므로, 이것이 없으면 작성한 실행이고 있으면 비교만 한 실행임을 구분할 수 있습니다. source는 이 머신에서의 이번 실행을 설명하므로 lockfile에는 기록되지 않으며, Release가 의존하는 것을 보고하는 describe도 이를 명시하지 않습니다.

거부도 같은 필드로 답하며, 실행이 진행된 만큼 채워집니다. 해석이 계산된 이후에는 판정이 무엇이든 resolved가 포함됩니다. 특히 drift 판정이 그렇습니다. 호출자가 무엇을 바꿀지 결정해야 하는 거부가 바로 그것이기 때문입니다. 해석되지 않는 Release 경로처럼 그 시점 이전의 거부는 수정 방법을 텍스트로 담고 해석 결과는 담지 않습니다. 담을 해석 결과가 없었기 때문입니다.

고정은 완전하지만 외부 입력은 그렇지 않은 경우에도 호출은 성공하며 그 사실을 알려 줍니다. Release가 어떤 외부 입력을 소비하는지 알아내는 것은 렌더이며, 렌더는 의존성 고정이 이미 올바르게 디스크에 기록된 후에 실패할 수 있습니다. 호출 전체를 실패로 보고하면 올바른 작업을 다시 하라고 알리는 셈이 되므로, 대신 성공한 결과에 incomplete_external_inputs를 설정하여 무엇이 중단되었는지 명시합니다. 의존성 고정은 완전하지만 외부 입력 고정은 그렇지 않을 수 있습니다.

이것은 여기서 가장 느린 도구이며, 아무것도 바꾸지 않는 조정도 빠른 경로가 아닙니다. 해석은 의존성 집합이 바뀌지 않았음을 확인하는 데 전체 비용을 치르므로, 아무것도 다시 쓰지 않는 호출도 첫 해석과 같은 비용이 듭니다. 작은 Release에서도 밀리초가 아니라 초 단위이며, 의존성 집합의 크기에 따라 늘어납니다. verify는 두 형태 중 더 저렴한데, 비교는 작성하는 실행이 수행하는 컴포넌트별 소스 탐색을 건너뛰기 때문입니다. 클라이언트가 호출별 타임아웃을 적용한다면 이 도구를 기준으로 확인하십시오. 아래에서 설명하는 진행 상황 알림을 요청하면 호출이 끝날 때까지 아무것도 오지 않는 대신 실행 중에 무언가가 도착합니다. 이는 클라이언트나 HTTP로 연결된 서버 사이에 있는 무언가의 유휴 타임아웃에는 대응하지만, 한 호출의 총 소요 시간 상한에는 대응하지 않습니다.

읽는 입력에 대한 핀을 entity.lock에 기록하지 않은 엔터티는 pull을 거부하며, 그 거부는 핀을 기록하는 단계를 알려 줍니다. Release가 카탈로그 디렉터리에서 빌드하는 Recipe 또는 FeatureRecipe가 전체가 기술된 원격 소스를 읽거나 artifacts를 통해 파일을 가져오는 경우, 그 핀을 이미 옆에 두고 있어야 합니다. 이 핀은 작성자가 아래의 pin으로 기록합니다. pin_sources는 이 호출이 거부하는 대신 작성자를 대신해 그러한 모든 엔터티에 대해 그 단계를 실행하고 각 엔터티 옆에 entity.lock을 쓰도록 요청합니다. 이는 pin 도구가 실행하는 것과 같은 단계이며 같은 바이트를 씁니다. 생략하면 워크스페이스의 pin_sources_at_pull이 결정하고, 보내면 어느 방향으로든 그 값이 결정하므로 pin_sources: false는 핀을 기록하도록 구성된 워크스페이스에서도 거부합니다. 해석이 카탈로그 디렉터리가 아닌 캐시에서 도달한 엔터티는 여기서 쓸 수 있는 위치가 없으므로 이 호출로 핀이 기록되지 않습니다.

엔터티 자체 입력의 핀 기록

pin은 Recipe 또는 FeatureRecipe 옆의 entity.lock에, 엔터티가 자신의 문서 밖에서 읽는 모든 입력의 콘텐츠 핀을 기록합니다. 대상은 좌표가 전체로 기술된 원격 소스와 artifacts 항목이 가져오는 파일입니다. 이는 aggrega pin이 터미널에서 실행하는 것과 같은 단계이며, 쓰는 잠금 파일은 그 명령이 쓰는 것과 바이트 단위로 동일합니다. 엔터티 문서인 entity를 전달하며, 여기의 다른 모든 경로 인수와 같은 계약에 따라 절대 경로 또는 워크스페이스 루트 기준 상대 경로로 지정합니다. HTTPS에서는 프로세스가 제공하는 워크스페이스 안으로 해석되어야 합니다.

필요하지 않으므로 Release를 지정하지 않습니다. 좌표에 템플릿이 없는 소스는 그 엔터티를 사용하는 모든 Release에 대해 하나의 아티팩트를 가리키므로, 이 단계는 Release가 제공하는 것 없이 이를 해석하고 핀을 기록합니다. 좌표가 템플릿에서 오는 소스는 여기서 핀이 기록되지 않습니다. 어떤 아티팩트를 가리키는지는 각 Release가 결정하며, pull이 해석된 각 식별자의 핀을 그 Release의 잠금 파일에 기록합니다.

결과는 이 단계가 lock에 무엇을 했는지 알려 줍니다. 결과에는 entity, 그 kind와 name, 그리고 pinnable이 담깁니다. 이 값은 lock이 기록하는 것을 아무것도 읽지 않는 kind, 즉 Component나 Feature에서는 false이며, 이 경우 엔터티 옆의 어떤 것도 건드리지 않았고 나머지 필드는 없습니다. 그 밖의 경우에는 기록한 lock, lock이 이미 모든 핀을 기록하고 있어 바이트 단위로 동일하게 남았을 때 false인 changed, 엔터티가 이제 lock이 기록하는 것을 아무것도 읽지 않아 lock이 삭제된 경우의 removed, 그리고 핀의 클래스마다 하나씩 그 이후 lock이 보유한 개수를 담은 항목인 pins가 담깁니다. dry_run은 이 단계가 기록할 lock을 content로 답하고 엔터티 옆에는 아무것도 기록하지 않습니다. 입력은 그렇지 않은 경우와 똑같이 해석되므로 콘텐츠 캐시는 여전히 채워집니다.

워크스페이스 안에 쓰고 엔터티의 소스가 지정하는 호스트(차트 저장소, Git 호스트, URL)에 접근하므로, HTTP에서는 pull을 허용하는 범위를 가진 자격 증명에 허용되고 읽기만 가능한 자격 증명에는 거부됩니다. 표준 입출력에서는 같은 기능을 명령을 실행하는 cli-pin으로도 사용할 수 있으며, HTTP에서는 그 도구가 존재하지 않습니다.

긴 호출의 진행 상황 알림 받기

호출은 알려 달라고 요청할 때 진행 상황을 보고하며, 요청은 필드 하나입니다. 호출의 _meta에 progressToken을 넣습니다. 문자열이나 숫자 중 원하는 것을 고르면 됩니다. 이 값은 모든 보고에 작성한 그대로 되돌아오며, 보고 안에서 호출을 가리키는 유일한 것입니다. 보고는 아무것에도 응답하지 않으므로 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에는 둘 다 0부터 세는 line과 character를 전달하며, 이 값은 insertion-point가 해당 인수를 읽는 방식과 똑같이 position_encoding이 지정하는 단위로 측정됩니다. 그리고 컴파일된 그래프에 연결이 기록된 release를 전달합니다. Aggregate 안의 위치에 대해서도 Release는 필수입니다. 그래프 노드와 연결은 컴파일된 그래프에만 존재하기 때문입니다.

답은 두 가지 중 하나입니다. 위치가 연결의 항목 위에 있으면 답에는 graphNode와 connection(해당 연결의 socket, alias, 그리고 위치를 읽은 document)이 담깁니다. 이는 attach-candidates가 graph_node 및 release와 함께 받는 값이자, attachment-container가 해당 연결의 첨부가 들어갈 곳을 지정하기 위해 받는 값과 정확히 같습니다. 그 컨테이너는 위치가 속한 바로 그 항목 안에 있습니다. 그렇지 않으면 답에는 닫힌 집합에서 고른 noConnectionReason이 담깁니다. no-connection-entry(위치가 첨부를 작성하는 어떤 항목에도 있지 않음), feature-created-connection(위치가 Feature가 그린 연결에 대한 Release의 항목 위에 있음), unknown-connection(위치가 컴파일된 그래프에 없는 연결에 대해 Release가 작성한 항목 위에 있음) 중 하나입니다. 읽기용 답은 그 이유를 문장으로 설명합니다.

항목 안의 어느 곳에 있는 위치든 그 항목 안에 있는 것입니다. 별칭 위, 그 target 위, 그 features 안이 모두 그렇습니다. 항목이 중첩된 경우에는 가장 안쪽 항목이 우선합니다. 소켓 자체의 키 위, 즉 그 아래 별칭들보다 위에 있는 위치는 어느 항목 안에도 있지 않습니다. 항목은 컴파일된 그래프가 기록하는 것입니다. Aggregate에서는 컴포넌트가 그리는 모든 연결이며, 해당 컴포넌트가 작성된 문서에서 연결의 별칭 아래에 있는 항목입니다. 가져온 모듈이 기여한 컴포넌트라면 그 문서는 해당 모듈 자체의 문서입니다. Release에서는 Release가 작성하는 모든 에지별 항목입니다. 대상 목록으로 작성된 연결과 Feature 자체의 의존성 블록이 그리는 연결에는 첨부를 작성하는 항목이 없습니다. 키가 연결인지 여부는 결코 그 키의 이름으로 판단하지 않습니다.

답하고 멈춥니다. 어떤 파일에도 아무것도 쓰지 않습니다. 워크스페이스에 없거나, 읽을 수 없거나, 올바른 형식의 YAML이 아닌 문서는 insertion-point에서와 마찬가지로 무엇을 바꿔야 하는지 알려 주는 실패 결과로 돌아옵니다. line이나 character가 빠진 위치, 그리고 세 가지 중 어디에도 속하지 않는 position_encoding도 마찬가지입니다.

어태치먼트가 들어갈 컨테이너 묻기

attachment-container는 후보 여부에 대한 답과 삽입 위치 사이에 놓인 질문에 답합니다. 노드에 무엇을 어태치할지는 이미 정했지만, 파일의 어느 위치에 쓸지 묻기 전에 어느 파일의 어느 컨테이너인지 알아야 합니다. graph_node(그래프가 키로 쓰는 형태 그대로의, 컴파일된 그래프상의 노드 id)와 그 그래프의 release를 전달합니다. 둘 다 필수입니다. 노드 id는 하나의 Release 그래프의 키이며 그 Release 없이는 아무 의미가 없습니다.

그 경로를 직접 조립하지 마십시오. 노드의 id와 그 노드를 둘러싼 서브시스템 경로는 모두 각 부분 사이에 점을 넣어 쓰며, 점은 작성자가 입력하는 이름에 쓸 수 있는 문자입니다. 따라서 문서 밖에서는 구조상의 점과 이름 안의 점을 구별할 방법이 없습니다. 직접 조합한 경로는 올바르게 읽히지만 아무도 쓰지 않은 키를 가리키며, 뒤이은 편집은 거부되는 대신 그 키를 만들어 버립니다. 더구나 노드 id에는 둘러싼 서브시스템의 흔적이 전혀 없습니다. subsystems.billing.subsystems.payments 안에서 작성된 component는 최상위 component와 똑같이 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는 후보 판정 답변 다음에 오는 질문에 답합니다. 무엇을 연결하거나 접속할지는 이미 정했고, 이제 파일의 어디에 그것을 써야 하는지 알아야 합니다. 이 도구는 위치와 들여쓰기할 열을 돌려주므로, 문서를 직접 파싱하지 않고도 편집을 적용할 수 있습니다. 이 도구가 읽는 것은 특정 kind의 형태가 아니라 문서 자체의 구조이므로, describe-capabilities는 어떤 엔티티 kind로 좁히든 이 도구를 색인에 포함합니다.

file에는 문서를 전달합니다. 워크스페이스 루트에 대한 상대 경로나 절대 경로로 지정하며, 워크스페이스 안에 있어야 합니다. 워크스페이스 밖으로 이어지는 링크를 거쳐 도달하는 문서는, 링크가 파일에 걸려 있든 경로상의 디렉터리에 걸려 있든 워크스페이스 안에 있는 것이 아니며 어느 전송 방식에서든 거부됩니다. container에는 문서 루트에서 항목이 들어갈 컨테이너까지의 구조적 경로를 전달하며, 각 요소는 매핑 키이거나 십진수로 쓴 시퀀스 위치입니다.

컨테이너 경로는 직접 제공해야 합니다. 이 도구는 문서의 구조를 읽을 뿐, 무언가의 이름이나 타입, 의미로 보이는 것으로부터 그것이 들어갈 위치를 추론하지 않습니다. 어떤 키인지는 호출하는 쪽이 말하고, 도구는 이 문서에서 그 키의 항목이 어디에 들어가는지를 말합니다. 즉 경로의 어떤 세그먼트를 파일이 이미 가지고 있는지, 그 항목들이 놓인 열, 그리고 가장 안쪽 블록이 도달하는 마지막 줄을 알려 줍니다. 컴파일된 그래프의 노드에 Feature를 연결하는 경우에는 그 키를 직접 알 필요가 없습니다. 위의 attachment-container가 문서와 컨테이너를 보고하며, 둘 다 그대로 여기에 전달하면 됩니다.

답변에는 너비가 0인 position(line과 character 모두 0부터 셈), 써야 할 열인 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는 components 컨테이너 아래에 컴포넌트 인스턴스를 추가하고, attach-feature는 지정한 노드에 Feature를 연결하며, wire-edge는 그 노드의 소켓 중 하나 안에 연결을 배선하고, set-value는 그 노드에 값 하나를 설정합니다. 이 네 가지 외의 이름은 해석되지 않고 거부됩니다. 삭제하거나, 이미 작성한 블록을 교체하거나, 무언가의 순서를 바꾸거나, 제공한 바이트를 그대로 쓰는 편집은 없습니다. 따라서 이 도구는 파일 작성기가 아니며 파일 작성기로 사용할 수도 없습니다.

file에는 문서를 전달합니다. 워크스페이스 루트에 대한 상대 경로나 절대 경로이며 워크스페이스 안에 있어야 합니다. 작성된 그대로든 워크스페이스 밖으로 이어지는 링크를 통해서든 워크스페이스 밖에 있는 문서는 어느 전송 방식에서나 아무것도 읽거나 쓰지 않은 채 거부됩니다. node에는 문서 루트로부터의 구조적 경로를 세그먼트 목록으로, name에는 항목이 작성될 키를, value에는 그 항목이 담을 내용을 전달합니다. node가 목록인 이유는 attachment-container가 목록으로 답하는 이유와 같습니다. 작성자가 입력하는 이름 안에는 점이 올 수 있으므로, 이어 붙인 경로는 아무도 쓰지 않은 키를 가리킬 수 있고, 그러면 항목이 거부되지 않고 그곳에 생성됩니다. add-component의 경우 추가되는 항목이 곧 노드이므로 경로는 components 컨테이너 자체를 가리킵니다. 나머지 세 가지의 경우 경로는 편집 대상 노드를 가리키며, 컨테이너는 편집에 따라 정해집니다. 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로 접근하는 서버에서는 디렉터리 자체가 워크스페이스 안에서 해석되므로, 거기서 읽는 모든 파일도 마찬가지입니다.

임포터는 워크스페이스의 카탈로그가 보유한 것이거나 컴파일러의 코어 임포터 중 하나입니다. 변환은 소스의 형식을 알리는 임포터 플러그인이 수행합니다. 이는 워크스페이스의 카탈로그가 보유한 것이거나, 카탈로그 항목 없이 모든 워크스페이스에서 해당 형식을 제공하는 컴파일러의 코어 임포터 중 하나입니다. 이 도구는 임포터를 선택하고 실행한 뒤 그 결과를 기록합니다. uri가 임포터를 식별자와 버전으로 지정하는 plugins.importer 연결(aggrega plugin add importer가 기록하는 형태인 importer/<name>:<version>)은 그 임포터를 연결합니다. 그 임포터가 소스의 형식을 알리는 경우, 다른 임포터가 같은 형식을 알리더라도 해당 버전의 그 임포터가 실행되며, 다른 어떤 임포터에도 전달되지 않는 그 연결의 with 소스와 설정이 전달됩니다. 여러 임포터가 형식을 알리고 그중 어느 하나도 연결되지 않은 경우(같은 형식에 대한 코어 임포터와 카탈로그가 보유한 다른 이름의 임포터가 함께 있는 경우 등), 호출은 Configuration에서 설명하는 대로 그 임포터들을 명시하며 거부됩니다. 지정한 형식을 알리는 임포터가 없으면, 해석해야 하는 일반적인 실패 대신 임포터가 알려야 할 기능(Langflow 소스의 경우 import:langflow)을 명시하며 거부됩니다. 이것이 카탈로그에 추가하는 임포터가 선언하는 내용입니다.

서버 머신에 없는 core importer는 그것이 필요한 첫 import가 한 번 가져옵니다. import는 이를 서비스되는 워크스페이스의 기본 레지스트리에서 가져오고, 컴파일러의 릴리스가 게시하는 모듈과 일치하는지 확인하며, pull이 가져오는 플러그인을 검증하는 것과 같이 해당 레지스트리의 신뢰 정책과 사용하는 호스트 함수에 따라 서명을 검증한 뒤, 워크스페이스의 콘텐츠 캐시에 보관합니다. 따라서 이후의 모든 import는 그곳에서 읽으며 어떤 레지스트리에도 접속하지 않습니다. 이를 위해 그 밖에 기록되는 것은 없습니다. lockfile도, 신뢰하는 플러그인의 기록도 없습니다. HTTPS에서는 이 레지스트리가 이 도구에 대한 호출이 서버로 하여금 접속하게 할 수 있는 유일한 레지스트리이며, Which credentials a call spends가 레지스트리 읽기에 대해 정하는 한계를 따릅니다. 이 레지스트리는 이 서버가 서비스하는 워크스페이스의 기본 레지스트리이므로 해당 워크스페이스에 구성된 레지스트리입니다. 호출의 어떤 내용도 레지스트리를 지정하거나 자격 증명을 전달하지 않으며, 가져오기에는 이 호스트 자체의 로그인과 신뢰 정책이 사용됩니다. 도구는 여전히 워크스페이스에만 접근하고 그 너머에는 접근하지 않으므로 호출에 필요한 것은 aggrega:workspace-write뿐입니다. 가져오기가 남기는 것은 워크스페이스 자체 콘텐츠 캐시의 모듈입니다. 검증되지 않는 모듈은 터미널에서와 마찬가지로 거부되며 아무것도 보관되지 않습니다. 모듈을 가져올 수 없는 경우(워크스페이스가 오프라인이거나, 레지스트리에 연결할 수 없거나, 레지스트리에 모듈이 없는 경우) 호출은 A plugin’s .wasm is not on this machine (플러그인의 Wasm 파일이 이 머신에 없음)으로 거부되며, importer와 그 버전, 그리고 해당 모듈을 머신에 두는 방법을 명시합니다.

워크스페이스가 카탈로그 폴더를 지정하지 않으면, 가져오기는 기본 레지스트리가 게시하는 카탈로그를 읽습니다. workspace.catalog_dirs, AGGREGA_CATALOG_DIRS, 루트 중 어느 것도 카탈로그 폴더를 지정하지 않는 워크스페이스는 표준 라이브러리 카탈로그를 하나의 서명된 스냅샷으로 읽으며, 이 스냅샷은 서비스되는 워크스페이스의 기본 레지스트리의 catalog/snapshot에 있습니다. 이는 코어 임포터를 받아 오는 것과 같은 레지스트리로, 같은 조건으로 접근하며, 호출의 어떤 부분도 레지스트리를 지정하거나 자격 증명을 담지 않습니다. 스냅샷은 한 번만 받아 옵니다. 그 서명은 해당 레지스트리의 신뢰 정책에 따라 검증되고, 스냅샷은 워크스페이스의 콘텐츠 캐시에 보관되어 그곳에서 카탈로그 폴더로 읽히며, 다이제스트에 고정되어 어떤 레지스트리에도 다시 요청되지 않습니다. 호출이 읽는 스냅샷은 다음과 같습니다. upgrade를 지정하면 최신 스냅샷입니다. 그렇지 않으면 출력 디렉터리의 기록이 지정하는 스냅샷이며, 머신에 없으면 그 다이제스트로 받아 옵니다. 그렇지 않으면 워크스페이스가 마지막으로 최신 스냅샷으로 받아 온 스냅샷이고, 그렇지 않으면 최신 스냅샷입니다. 가져오기가 작성하는 기록은 읽은 스냅샷을 다이제스트로 지정하므로, 나중에 같은 디렉터리에 초안을 작성하는 호출은 같은 카탈로그를 읽습니다. 오프라인에서는 스냅샷을 받아 와야 하는 호출이 실행할 명령을 알려 주며 거부되고, 어떤 스냅샷이 최신인지는 레지스트리만 알 수 있으므로 머신이 무엇을 보유하든 upgrade는 거부됩니다. 스냅샷을 게시하지 않는 레지스트리에서는 가져오기에 카탈로그가 없게 되며, diagnostics의 warn 항목이 이를 알립니다. 카탈로그 폴더를 지정하는 워크스페이스는 그 폴더를 기준으로 가져오고 스냅샷을 받아 오지 않으며, 그곳에서 upgrade는 아무것도 바꾸지 않습니다.

format을 생략하면 임포터가 선언한 시그니처로 형식을 인식합니다. 카탈로그의 임포터와 코어 임포터 모두 마찬가지입니다. 각 임포터의 Plugin 엔터티는 시그니처를 기록합니다. 소스를 읽는 구문, 시그니처가 적용되는 파일 이름, 파싱된 트리가 가져야 하거나 가지지 말아야 하는 경로입니다. 소스는 이름에 적용되는 시그니처가 읽는 각 구문마다 한 번씩, 워크스페이스의 카탈로그가 그 구문에 제공하는 파서(카탈로그가 파서를 제공하지 않는 구문이면 컴파일러 자체가 가진 파서)로 파싱되며, 시그니처가 일치하는 단 하나의 임포터의 형식이 사용됩니다. 그런 다음 임포터는 같은 파서로 소스를 읽습니다. 코어 임포터의 시그니처는 파일을 JSON 또는 YAML로 읽으며, 파일을 지정하지 않는 시그니처는 JSON으로 읽습니다(Dify 임포터의 것은 YAML). 따라서 단독으로 임포트하는 파일을 인식할 때는 두 가지로 모두 읽으며 워크스페이스 카탈로그에 파서가 필요하지 않습니다. 컴파일러는 JSON 파서와 YAML 파서를 가지고 있으며, 카탈로그가 제공하는 파서가 있으면 그것이 대신 사용됩니다. 디렉터리도 그 파일들에 대해 같은 방식으로 인식됩니다. 각 시그니처는 그 패턴이 선택하는 디렉터리 파일에 대해 시도되며, 패턴을 선언하지 않은 시그니처는 그중 어느 파일에도 적용되지 않습니다. 인식 과정은 지정한 파일(디렉터리의 경우 시그니처의 패턴이 선택하는 파일만)을 읽으며 네트워크에는 접근하지 않습니다. 어떤 시그니처도 일치하지 않는 소스는 No importer recognises the source (소스를 인식하는 임포터가 없음) 조건으로, format을 요구하고 임포터가 알리는 형식을 명시하며 거부됩니다. 디렉터리의 경우에는 그 파일 중 하나를 단독으로 source로 보내거나 임포터가 파일 패턴을 선언한 format을 보내도록 요구하며, 그런 형식만 명시합니다. 둘 이상의 형식의 시그니처가 일치하는 소스는 More than one importer recognises the source (둘 이상의 임포터가 소스를 인식함) 조건으로 그 형식들을 명시하며 거부됩니다. 어느 경우에도 추측한 임포터에 전달되지 않습니다. 두 경우 모두 format을 보내 형식을 직접 지정하십시오. 디렉터리의 경우에는 임포터가 파일 패턴을 선언한 형식을 지정합니다. 디렉터리는 그 패턴을 통해서만 읽히기 때문입니다. 빈 format은 생략한 것으로 읽히지 않고 거부됩니다. 두 요청은 서로 다르기 때문입니다.

하나의 provider를 대상으로 초안 Release가 빌드할 기준이 되는 Manifest를 초안으로 작성하려면 target을 보냅니다. target은 provider capability로, Recipe의 spec.capability가 바인딩하는 단어(예: compose 또는 helm)이며, aggrega import의 --target과 같고 같은 연산으로 구성됩니다. 따라서 호출과 명령은 같은 소스에서 같은 파일을 초안으로 작성합니다. 초안에 필요한 각 component 유형과 각 feature 유형에 대해(초안 Aggregate의 component, 그 연결과 하위 시스템, 그것이 구성하는 카탈로그 Aggregates, 초안 Release의 첨부에서), 초안이 처음 선언한 순서대로, 가져오기는 워크스페이스의 카탈로그에서 그 유형을 구현하고 해당 capability에 바인딩하는 Recipes를, feature 유형의 경우에는 feature recipe를 찾습니다. 정확히 하나가 있으면(그중 하나의 여러 버전은 하나로 셉니다) Manifest는 그 유형을 버전 없이 capability로 한정된 이름(예: compose/postgres)으로 매핑하며, 첫 pull이 이를 사용 가능한 가장 높은 버전으로 lockfile에 고정합니다. 이름이 다른 것이 여러 개 있으면 유형 자체의 이름을 딴 것(예: core/datastore/postgres에 대한 helm/postgres)으로 매핑합니다. 하나도 없거나, 여러 개 있지만 그렇게 이름 붙은 것이 없으면 그 유형은 매핑되지 않은 채로 남고, diagnostics의 warn 항목이 그 유형과 이유를(여러 개인 경우 각각을 이름으로) 밝힙니다. 따라서 매핑이 추가될 때까지 초안의 빌드는 그 유형의 각 인스턴스 또는 첨부를 이름으로 밝히며 No Recipe is mapped for a component or feature instance (component 또는 feature 인스턴스에 매핑된 Recipe가 없음)로 중단됩니다. importer가 직접 Manifest를 초안으로 작성하여 한 인스턴스가 렌더링되는 Recipe나 여러 feature recipe 중 하나를 선택하는 경우, importer가 작성한 매핑 중 카탈로그가 해당 유형과 capability에 대해 제공하는 것은 각각 유지되고, 그 밖의 매핑은 warn 항목과 함께 제거되며, importer가 남긴 유형은 위와 같이 매핑됩니다. Manifest는 초안 Release 옆에 manifest.yaml로 작성되며, Release와 같은 이름과 버전을 가지고, Release의 spec.manifest는 그 이름으로 설정됩니다. 그 자리에 importer가 작성한 주석은 대체되며, Release의 다른 부분은 바뀌지 않습니다. 이미 Manifest를 지정하는 Release는 그대로 두며, 가져오기가 Release를 초안으로 작성하지 않는 경우 Manifest는 Aggregate 옆에 그 이름과 버전으로 작성되고, info 항목이 아무것도 이를 참조하지 않는다고 알립니다. Manifest와 편집된 Release는 다른 초안과 마찬가지로 written과 기록에 포함되며, dry_run에서는 반환됩니다. 카탈로그의 어떤 Recipe도 바인딩하지 않는 target은 importer가 실행되기 전에 An import’s target names a capability no Recipe in the catalog binds to (가져오기의 target이 카탈로그의 어떤 Recipe도 바인딩하지 않는 capability를 지정함)로 거부되며, 보낸 그대로의 target과 카탈로그의 Recipes가 바인딩하는 capability를 밝히고, 아무것도 작성되지 않습니다. target을 생략하면 Manifest는 작성되지 않습니다. 단, sync에서는 이전 가져오기에 보낸 target을 대상으로 초안을 작성합니다. 빈 target은 생략한 것으로 읽히지 않고 거부됩니다.

초안이 들어갈 디렉터리를 지정하려면 output_dir을 보냅니다. 생략하면 초안은 호출이 확인한 워크스페이스의 루트 아래에 놓입니다. 이는 대상을 지정하지 않았을 때 어디서 실행하든 aggrega import가 초안을 작성하는 위치이며, 요청에 대상이 없을 때 언어 서버의 aggrega/import가 작성하는 위치이기도 합니다. 대상은 세 가지 모두에서 선택 사항이며, 이 서버에 보내는 모든 경로와 같은 방식으로 지정합니다. HTTP를 통해서는 이 서버가 제공하는 워크스페이스 안의 디렉터리로, 루트에 대한 상대 경로로 작성합니다. 루트 밖으로 올라가는 값, 루트 밖의 절대 위치, 링크를 통해 밖으로 이어지는 디렉터리(그러한 링크 아래에 아직 만들어지지 않은 디렉터리 포함)는 각각 output_dir을 밝히며 거부되고, 아무것도 읽거나 작성되지 않습니다. 표준 입력과 출력을 통해서는 그곳의 모든 경로와 마찬가지로 지정된 그대로 받아들여집니다. 상대 값은 호출이 확인한 워크스페이스 루트를 기준으로 확인되고, 절대 값은 워크스페이스 밖의 디렉터리를 지정할 수 있으며, 그 디렉터리에는 aggrega import --output-dir이 작성하는 것과 같이 초안이 작성됩니다. 그곳에 작성되는 내용은 링크를 확인한 상태로 워크스페이스에(워크스페이스 밖에 지정한 디렉터리의 경우 그 디렉터리에) 한정되므로, 그 안에서 밖으로 이어지는 링크는 거부되고 아무것도 작성되지 않습니다. 빈 output_dir은 생략한 것으로 읽히지 않고 거부됩니다. 표준 입력과 출력에서는 cli-import도 명령의 --output-dir을 자체 output_dir로 전달합니다. 그곳의 상대 값은 명령이 실행되는 폴더, 즉 호출이 지정한 워크스페이스 루트, 없으면 서버가 시작될 때의 루트, 그것도 없으면 서버가 실행되는 폴더에서 확인됩니다.

초안으로 작성되는 모든 경로는 무엇이든 작성되기 전에 출력 디렉터리를 기준으로 검사됩니다. 디렉터리 밖에 닿는 경로는 경로와 디렉터리를 모두 밝히며 거부되고, 아무것도 작성되지 않습니다. 같은 집합에서 자체 경로에 문제가 없던 파일도 마찬가지입니다. 일부만 남긴 채 거부된 가져오기는 누구도 요청하지 않은 결과이기 때문입니다. 초안 경로는 사용자가 아니라 importer 플러그인에서 나오므로, 사용자가 보낸 경로와 같은 이유로 검사됩니다.

무엇이든 초안으로 작성하는 모든 가져오기는 초안 옆에 .aggrega-import.json도 작성합니다. 이는 가져오기가 작성한 내용의 기록으로, target을 보낸 경우 보낸 target, 카탈로그 스냅샷을 읽은 경우 읽은 카탈로그 스냅샷, 그리고 초안으로 작성된 각 파일과, 초안 Aggregate 또는 Release에서는 모든 깊이의 각 키를 그곳에 작성된 텍스트의 다이제스트와 함께 담습니다. 그 밖의 초안 파일은 전체가 기록됩니다. 키의 텍스트는 그 키의 줄, 값이 키의 매핑이 아닌 경우 값의 줄들, 그리고 같은 들여쓰기로 바로 위에 작성된 주석 줄입니다. written은 초안과 함께 기록을 밝히며, dry_run에서는 기록이 반환되는 초안에 포함됩니다. 기록은 JSON이므로 워크스페이스의 YAML 문서를 읽는 어떤 것도 이를 읽지 않습니다.

호출은 출력 디렉터리에 이미 있는 Aggregate를 결코 덮어쓰지 않습니다. Aggregate는 초안으로 작성된 뒤 작성자가 계속 편집하는 문서이므로, 초안 중 하나가 Aggregate로 읽히는 파일 위에 놓이게 되는 호출은 그 초안과 디렉터리를 밝히며 거부되고 아무것도 작성되지 않습니다. dry_run에서도 마찬가지인데, 드라이 런은 쓰기가 거부하는 것을 거부하기 때문입니다. 초안 경로에 이미 있는 그 밖의 파일은 덮어쓰며, 이전 가져오기가 작성했으나 이번 가져오기가 작성하지 않는 파일은 그대로 남습니다.

대신 sync를 보내면 이전 import가 초안으로 작성한 내용을 소스에 맞게 최신 상태로 갱신하며, import가 작성한 부분만 변경합니다. target을 보내지 않은 sync는 기록이 명시하는 대상에 대해 초안을 작성하므로, 이전 import가 초안으로 작성한 Manifest를 작성합니다. target을 보낸 sync는 그 대상에 대해 초안을 작성하며, 이후 기록은 그 대상을 명시합니다. 카탈로그의 어떤 Recipe도 바인딩하지 않는 기록된 대상은 보낸 대상과 마찬가지로 거부되며, 거부 메시지는 그 대상이 기록된 대상임을 밝힙니다. 각 부분은 세 가지 기준으로 판단합니다. 즉 import가 그 자리에 마지막으로 작성했다고 기록이 말하는 내용, 디스크에 있는 내용, 그리고 소스가 지금 초안으로 작성하는 내용입니다. 소스가 import가 마지막으로 작성한 그대로 둔 부분은 작성자가 편집했든 아니든 디스크에 있는 그대로 유지됩니다. 소스가 변경한 부분은 새로 작성되고, 소스가 없앤 부분은 제거되며(초안으로 작성된 파일은 통째로 삭제됩니다), 소스가 새로 얻은 부분은 초안에서 그 주변에 명시된 부분 옆에 추가됩니다. 이는 각각 디스크에 있는 내용이 import가 마지막으로 작성한 내용이고 작성자가 추가한 것을 담고 있지 않은 경우에만 해당합니다. 그 밖의 모든 것은 바이트 단위로 그대로 유지됩니다. 작성자가 어디에든 추가한 키(매개변수, Feature, 초안으로 작성된 Component 인스턴스 아래에 추가한 것도 포함, 다른 Component, 초안으로 작성된 Release가 작성자에게 남겨 두는 환경), 초안으로 작성된 키 바로 위에 작성되지 않은 주석, 그리고 기록이 나열하지 않는 모든 파일이 그렇습니다. 응답의 drift는 최신 상태로 갱신된 각 부분(dry_run에서는 갱신될 각 부분)을 초안이 명시하는 순서대로 나열하며, 각 항목은 change(added, removed 또는 changed), 해당 부분이 들어 있는 초안 파일인 file, 그리고 초안으로 작성된 Aggregate 또는 Release에서 해당 부분에 이르는 키들을 목록으로 나타낸 key로 이루어집니다. 이 목록은 해당 부분이 파일 전체인 경우 비어 있습니다. 텍스트 응답은 각 항목을 aggrega import가 표준 오류에 쓰는 문구인 <change> <key> in <file> 또는 <change> <file>로 한 줄에 하나씩 명시합니다. dry_run에서 빈 drift는 초안이 소스와 일치한다는 뜻입니다. dry_run에서 반환되는 초안은 sync가 작성할 파일이며, sync가 부여할 내용을 담고 있습니다. 작성자가 편집한 부분을 변경하거나 제거하는 sync, 작성자가 이미 작성한 자리에 부분을 추가하는 sync, 작성자가 추가한 것을 담은 부분을 제거하는 sync는 거부되며, 그러한 각 부분과 그 이유를 명시하고 아무것도 작성하지 않습니다. 초안으로 작성된 키 바로 위에 작성된 주석은 그 키를 편집한 것으로 간주됩니다. 어떤 기록에도 나열되지 않은 Aggregate에 대한 sync는 그 사실을 밝히며 거부되고, 기록을 읽을 수 없는 sync도 마찬가지이며, importer가 끝마치지 못한 sync는 아무것도 작성하지 않습니다. 기록이 없고 초안 경로에 아무것도 없는 디렉터리로의 sync는 초안 전체를 작성합니다. sync가 아닌 호출에서 drift는 빈 목록입니다.

응답에는 다음이 포함됩니다. 지정한 그대로의 source, 소스를 읽은 방식인 format, 호출이 확인한 워크스페이스의 루트인 workspace_root, 초안 경로의 기준 디렉터리인 output_dir, 디스크에 기록된 파일인 written, sync가 최신 상태로 갱신한 내용인 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(기존 Component에 대한 reference 또는 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은 작성을 제외한 모든 것을 수행합니다. 초안으로 작성된 각 파일은 output_dir를 기준으로 한 경로와 내용과 함께 drafts 아래에 반환되며, 아무것도 생성되지 않습니다. 이는 저장하기 전에 결과를 보여 주는 클라이언트를 위한 것입니다. 그 밖의 모든 동작은 작성할 때와 같아서, 같은 소스에 대해 같은 가져오기 플러그인이 같은 진단 정보를 보고하므로, 작성 시 거부될 소스는 이 경우에도 거부됩니다. 이를 지정하지 않으면 파일이 디스크에 기록되고 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는 severity 및 reason과 함께 reference를 받거나, 배치 파일을 지정하는 from을 받습니다. 배치 파일과 함께 보낸 내용 인수는 버리지 않고 거부하는데, 배치 파일은 자체 내용을 제공하며 조용히 무시된 인수는 반영된 인수처럼 읽히기 때문입니다.

두 게시 도구는 dry_run을 받으며, 이는 어떤 레지스트리에도 접속하지 않고 게시가 무엇을 보낼지 보여 줍니다. 번들을 계산하고, 무엇을 게시했을지 보고하며, beyond_this_machine을 false로, 주소를 지정했을 대상을 registries에 담아 응답합니다. publish-entity는 해당 게시가 남길 digest도 함께 응답하며, 이는 aggrega push --dry-run이 출력하는 것과 같습니다. 이는 제안된 게시가 실제 게시가 되기 전에 다른 사람에게 보여 주는 방법입니다. 서명과 철회에는 이러한 형태가 없습니다. 둘 다 이미 게시된 것에 작용하므로 미리 볼 것이 없습니다.

publish-entity는 게시하는 아카이브에 Windows가 쓰인 그대로 담을 수 없는 항목이 있으면 windows_unusable_entries로 응답합니다. 이는 대소문자와 뒤따르는 확장자에 관계없이 CON, AUX, NUL과 같은 장치 이름을 딴 부분이 있는 경로나, 마침표 또는 공백으로 끝나는 부분이 있는 경로이며, 엔터티 문서 자체의 파일 이름을 먼저, 그다음에 그것이 담은 파일을 각각 지정합니다. 해당 항목이 없으면 이 필드는 없으며, 문서만으로 게시된 엔터티도 여기에 포함됩니다. Windows에서 실행되는 aggrega는 그러한 항목의 압축 해제를 거부하므로 Windows 워크스페이스는 해당 버전을 사용할 수 없습니다. 이들은 aggrega push가 경고하는 항목이며, 응답의 텍스트도 이를 지정합니다. 이 항목들은 아무것도 거부하지 않습니다. 호출은 dry_run을 포함해 이 항목들이 없을 때와 정확히 같게 진행되거나 거부됩니다.

publish-entity는 pin_sources를 받으며, 이는 엔터티를 번들로 묶기 전에 엔터티 작성자의 고정 단계를 실행합니다. 따라서 이 단계가 엔터티 옆에 쓰는 entity.lock이 게시 대상에 포함됩니다. 이는 pin 도구가 실행하는 것과 같은 단계로 같은 바이트를 쓰며, 엔터티를 판정하는 어떤 거부보다도 먼저 실행됩니다. 따라서 예를 들어 서명 누락으로 거기서 거부된 게시도 엔터티 옆에 잠금 파일을 써 둡니다. 오프라인 워크스페이스나 대상 없음과 같은 호출 자체에 대한 거부는 먼저 일어나며 아무것도 고정하지 않습니다. 이를 생략하면 워크스페이스의 pin_sources_at_push가 결정하고, 보내면 어느 방향으로든 이 값이 결정합니다. 고정하는 게시는 레지스트리뿐 아니라 워크스페이스 안에도 쓰므로, HTTP에서는 두 범위를 모두 가진 자격 증명이 필요하며 게시를 허용하는 범위만 가진 자격 증명은 다른 범위를 지정하며 거부됩니다. 단계가 실행된 경우 결과에는 pin 도구가 응답하는 형태의 pin이 담깁니다. dry_run에서는 단계가 쓸 잠금 파일을 보고하고 아무것도 쓰지 않습니다. 단계가 실행되지 않으면, entity.lock이 읽는 입력에 대한 고정을 기록하지 않은 Recipe 또는 FeatureRecipe는 거부됩니다. 입력이 더 이상 일치하지 않는 경우도 마찬가지이며, 이는 dry_run을 포함해 무엇이든 번들로 묶기 전에 aggrega pin, pin_sources, pin_sources_at_push를 지정하며 일어납니다. 이는 같은 잠금 파일에 대해 pull이 일으키는 거부이며, 이를 확인하려면 단계가 그러듯 엔터티가 기록하는 각 원격 소스를 전부 가져옵니다.

서명은 자격 증명이 사용되는 곳이며, 네 도구 중 세 도구가 서명합니다. 데이터 아티팩트 게시는 아무것도 서명하지 않으며 나중에 참조로 서명됩니다. 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이 전혀 아닌 메시지가 그렇습니다. 리소스 읽기와 프롬프트 렌더링도 그 채널로 응답하는데, 두 결과 모두 자체 실패 플래그를 담지 않기 때문입니다.

도구가 공개하는 스키마는 인수가 충족해야 하는 규칙의 대부분도 선언합니다. 어떤 선택자가 서로 배타적인지, 어떤 인수가 다른 인수와 함께일 때만 의미가 있는지, 어떤 인수가 필수인지가 그렇습니다. 따라서 선언된 스키마에 맞추어 호출을 구성하는 클라이언트는 이를 알기 위해 실제로 호출해야 하는 경우가 드뭅니다. 스키마가 명시하지 않는 규칙도 여전히 거부되며, 그 규칙을 지목하는 문장이 함께 돌아옵니다. verify를 upgrade_targets 또는 pin_sources와 함께 쓰지 않는다는 pull의 규칙은 Release가 의존하는 것 해석하기에서 설명하는 이유로 의도적으로 거부에 맡겨 둡니다.

서버를 멈추는 방법

표준 입력과 출력에서는 연결을 닫으면 서버가 멈춥니다. 서버는 한 줄에 메시지 하나씩 읽으며, 표준 입력이 스트림의 끝에 도달하면 정상적으로 종료합니다. 따라서 연결을 닫는 클라이언트는 서버를 종료시킵니다. 이 전송 방식에서는 이것이 일반적인 경우입니다. 명령을 직접 실행하는 일이 없기 때문입니다. 명령을 시작한 클라이언트가 명령을 끝내므로, 보통은 편집기를 종료하거나 프로젝트에서 이 서버를 비활성화하는 것이 곧 서버를 멈추는 방법입니다.

프로세스 자체에 중지를 요청하면 어느 전송 방식에서든 서버에 전달됩니다. 터미널의 인터럽트나 수퍼바이저 또는 컨테이너 런타임의 종료 요청은, 클라이언트가 무언가를 보내고 있는지와 관계없이 첫 번째 요청에서 서버를 종료합니다. 서버는 메시지 수신을 중단하고, 진행 중인 호출이 하던 작업을 끝낸 뒤, 정상적으로 종료합니다. 두 번째 요청은 프로세스를 즉시 끝냅니다. 따라서 표준 입력과 출력에서는 프로세스에 중지가 요청될 때 아직 실행 중인 호출은 완료되지 않습니다. 반면 리스너는 드레인을 수행하여, 이미 응답 중인 호출이 정해진 시간 한도 안에서 완료되도록 한 뒤 프로세스를 종료합니다.

클라이언트는 서버를 멈추지 않고 호출 하나만 멈출 수도 있으며, 그 방법은 전송 방식에 따라 다릅니다. 호출은 동시에 처리되므로, 호출 하나를 끝내는 요청은 그 호출 뒤에서 기다리지 않고 호출이 아직 실행 중일 때 처리됩니다. 표준 입력과 출력에서는 클라이언트가 호출의 id를 지정합니다. 이미 응답된 호출이나 서버가 처리하고 있지 않은 호출을 취소하면 아무 일도 일어나지 않습니다. 그래서 응답이 이미 돌아오는 중인지 먼저 알지 못해도 이런 메시지를 안전하게 보낼 수 있습니다. HTTP에서는 보낼 메시지가 없습니다. 호출을 전달한 연결을 닫으면 호출이 끝납니다. 어느 쪽이든 호출에 중지가 통보됩니다. 호출의 작업은 연산이 다음으로 확인하는 지점에서 끝나고, 확인을 전혀 하지 않는 연산은 끝까지 실행됩니다. 그 호출에 대해서는 더 이상 아무것도 전송되지 않으며, 진행 중인 다른 모든 호출은 계속되고, 서버도 계속 서비스합니다.

사용 시기

AI 어시스턴트가 실제 스키마와 레퍼런스를 바탕으로 Aggrega 엔터티 작성을 돕게 하려면 aggrega mcp를 사용합니다. 그러면 어시스턴트의 제안이 추측이 아니라 컴파일러가 받아들이는 정확한 구조에 근거합니다. 이 명령은 작성 루프에 그대로 맞아떨어집니다. 어시스턴트는 kind의 스키마와 레퍼런스를 읽고, 골격을 만들고, 사용자의 역할이 담당하는 필드를 채운 다음, 초안을 돌려주기 전에 검증합니다. 이 루프에 대해서는 Aggrega 파일 작성을 참조하십시오.

표준 입력과 출력을 사용하는 경우에는 일반적으로 aggrega mcp를 직접 입력할 일이 없습니다. 대신 클라이언트의 MCP 구성에 한 번 지정해 두면 클라이언트가 대신 시작하고 중지합니다. 리스너는 이와 다른 경우입니다. 이때는 사용자가 직접 프로세스를 실행하며, 프로세스는 그것을 시작하지 않은 호출자를 위해 계속 실행됩니다.

예시: 표준 입력과 출력을 통한 클라이언트 구성

stdio 서버 항목으로 MCP 클라이언트가 이 명령을 가리키도록 설정합니다:

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

유일한 전제 조건은 클라이언트의 PATH에 설치된 aggrega 바이너리입니다. 클라이언트별 구성 경로와 문제 해결은 MCP 서버 연결을 참조하십시오. 클라이언트 없이 명령줄에서 스키마를 직접 가져오려면 aggrega get-schema를 참조하십시오.