跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

aggrega mcp

通过标准输入输出或 HTTP 运行 Model Context Protocol 服务器,用于 AI 助手集成

概要

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 握手打开连接,一次性确定这些内容。无论哪种方式,服务器在消息之间不保留任何状态,因此你先发送的内容不会决定之后的调用如何被应答。指定了服务器不支持的修订版本的请求会被拒绝,并被告知可以请求哪两个版本,而不会被当作请求了其中一个版本来应答。

服务器向已连接的助手公开三类接口:

  • Prompts——分为两类,区别在于各自回答的问题。编写提示回答“我在写什么”:每个角色(开发者、架构师、运维)一个角色设定,外加一个针对单个实体的专用模板。每个提示设定角色,并将助手指向正确的 schema、参考页面和编写指南,使其建议始终处于该角色负责的支柱范围内。工作流提示回答“调用哪些、按什么顺序”:每个提示列出达成一个跨越多个操作的目标所需的有序工具调用序列,以及其间的决策点——从零开始组合一个新的 Aggregate 及其 Release,将现有的 chart、基础设施模块或 container-compose 文件引入 Aggrega,查明某个构建为何无法编译或渲染出错误的产物。prompts/list 列出这两类提示,prompts/get 渲染其中一个,因此该集合以服务器为准,而非以本页为准。

    工作流提示列出调用,由你逐个执行,在下一个之前先读取每个结果。没有能完成整个目标的单一调用:每个工具封装一个你可以检查的操作,因此正是这个序列让你达成目标。编写角色设定接受一个可选的 kind 作为关注点,单实体模板则要求提供一个;没有任何 schema 对应的 kind 会被拒绝,并列出可接受的集合,而不会被悄悄忽略。

  • Resources——以内联方式提供的只读参考资料:schema://<kind> 对应实体的 JSON Schema,langref://<path> 对应任意语言参考页面,authoring://<topic> 对应编写指南,catalog://<kind>/<name> 对应目录实体的原始 YAML,cli://<command> 对应命令自身的帮助,单独的 cli:// 为其入口——这些帮助由服务器自身携带的命令回答,因此读取时不会启动任何进程,返回的文本与该命令针对 --help 打印的相同。对目录中不存在的实体进行 catalog:// 读取,会得到未找到的回答;如果这是因为恰好有一个声明该实体的目录文件在加载时被跳过,回答的消息会指出该文件、它违反的约束以及该情况的短代码,而不只是给出 URI——这正是 aggrega build 针对同一文件首先给出的拒绝。resources/list 列出无需参数即可寻址的资源,resources/templates/list 公布每一类资源的 URI 形式。

  • Tools——针对你的工作区的操作,tools/list 会返回全部工具。

    助手最先接触的工具是为编写循环设计的:list-entities 和 list-releases 用于了解工作区包含什么;scaffold 生成一个带有其 kind 所需字段的骨架,在每个待填值处放置占位符——或者,发送 example 时,将文档中的一个可运行示例写入新目录,并返回该目录的位置、写入的文件和构建它的命令;发送 list: true 时,列出这些示例;get-schema 获取实体的 JSON Schema;validate 校验草稿(它会列出草稿中仍存在的每个占位符及其各自接受的内容);describe 描述一个目录实体——或按引用从其注册表读取的实体;pull 将 Release 的依赖解析到本地缓存并写入其锁文件;build 将 Release 构建为渲染后的产物——默认在内存中进行,不向磁盘写入任何产物;当你发送 write 时,则写入工作区根目录下的 dist/,即 aggrega build 写入的位置(仅当你发送 auto_pull 时才会先解析依赖);gen-catalog 从 Wasm guest 生成 Plugin 实体;explain-error 将编译器诊断展开为可操作的指导——包括在诊断以某个中止条件的短代码开头时,给出该条件以及已发布的编写修复演练,与 aggrega explain 在终端中针对同一代码给出的展开相同。

    其余接口也在同一应答中,而不是隐藏在其后:在服务器内部运行的更多工具——lint、给出文档中某处所写连接的工具、两个候选工具、附加容器工具和插入点工具、对文档应用一次有界编辑的工具、pin(按固定实体自身的输入所述记录实体输入的内容固定),以及下文介绍的四个发布工具,外加缓存和已配置注册表的清单——并且,对于通过标准输入输出启动此服务器的客户端,还为你原本可以键入的每个命令提供一个工具,以其调用路径命名。这些命令工具仅存在于该传输方式上:通过 HTTP 访问的服务器不提供任何命令工具,原因见通过 HTTPS 访问服务器。没有任何内容留待之后的调用。 向模型展示多少工具列表由客户端决定——它获取定义并选择加载哪些——而客户端从未收到的定义,就是模型永远无法调用的操作,无论该工具名称在通信中多么可达。当整个列表超出客户端的承受范围时,可以通过缩小服务器公布的内容来缩短它。describe-capabilities 将该接口缩小到你正在编写的实体 kind。 发送 kind 时,它返回服务于该 kind 的工具,依据是每个工具声明的 kind,而非描述中的文字;不带参数发送时,它返回覆盖此服务器向你提供的所有工具的同一索引——每个工具的名称、一行用途说明、所服务的 kind 以及是否写入,不含参数 schema,因此整个接口在一个可读的应答中呈现。对于 cli- 工具,是否写入取决于其运行的命令是否写入:cli-build 被报告为写入,因为该命令会将渲染后的产物保存到工作区根目录下;cli-scaffold 同样被报告为写入,因为发送 example 时,该命令会将文档中的一个可运行示例写入新目录;而只读取的命令被报告为只读,即使它在过程中填充了机器上所有项目共享的缓存,与在服务器内部运行同一操作的工具一样;发送 tools 并指定一个或多个工具时,它恰好返回这些工具的完整定义和参数 schema。cli- 工具从不按 kind 缩小,因为没有任何记录表明某个命令服务于哪个实体 kind,所以按 kind 限定的应答不包含它们,应在无参数的索引中查看。命令工具的参数以命令自身的标志命名,因此 --output-dir 以 output_dir 发送;无法识别的名称会被拒绝,并列出可接受的写法,而不会被悄悄丢弃。

    有些能力在标准输入和输出上提供了两份:一个为编写循环设计的工具在服务器内部执行该操作,而以承载同一能力的命令命名的工具则运行该命令。两者行为不同,因此在该传输方式上,每个工具都会指明另一个并说明差异;通过 HTTP 时命令工具不存在,这句配对说明也会被省略,而不是指向调用方无法访问的工具。应优先使用在服务器内部运行的那个:它在可读文本之外还返回机器可读的结果,因此助手以字段形式得到结论、文件列表或诊断信息,而不是一段需要解析的输出记录。命令工具在单独的进程中启动真实的命令,因此它会在其运行的机器上做该命令所做的一切,包括在命令写入的位置写入磁盘——cli-build 会将渲染出的制品写入工作区根目录下的 dist/,并将追踪构建的文件写入其旁边的 .trace/,它返回的最后一行会给出该目录的完整路径——并且只返回它运行的命令行以及该命令打印的文本。当你需要使用命令声明、而另一个工具不接受的标志时,再使用它。

    该命令行以启动此服务器时所用的、决定配置的全局标志开头——--config 和 --offline(如果你提供了它们)——位于命令及该调用自身的标志之前。 因此该命令读取的配置与这里其他每个工具读取的相同:以 --offline 启动的服务器会离线运行其命令,以 --config 启动的服务器则基于该全局文件运行它们。调用自己发送的标志位于其后并优先生效,因此某次调用上的 offline: false 仅对该次调用访问网络,返回的命令行会同时显示两者。如果服务器启动时指定了工作区根目录——通过 --workspace-root 或 AGGREGA_WORKSPACE_ROOT——命令行会以该根目录作为 --workspace-root 开头,位于上述两个标志之前,因此该命令将该目录作为其工作区根目录,就像在终端中使用同一标志输入时一样,也与服务器内部运行的每个工具的处理方式相同,而不是从服务器启动时所在的目录查找工作区。发送了 workspace_root 的调用会指定自己的根目录,命令行只携带这一个——包括空值,命令对空值的解读与在终端中对 --workspace-root "" 的解读相同:从服务器启动时所在的目录查找工作区。两者都未指定而启动的服务器不传递根目录,因此其命令会从该目录查找工作区,遵循 调用在哪个工作区中得到响应 为每个工具规定的规则——但桌面捆绑包在其 Workspace folder 设置为空时的启动除外:此时未指定自身工作区的调用不会启动任何命令,并以该设置对应的拒绝作为响应。命令在调用或启动所指定的工作区根目录中启动:即调用自身的 workspace_root(按每个工具的读取方式读取——绝对路径按发送的原样,相对路径则相对于未指定根目录的调用得到应答的根目录——并以其绝对形式传给命令),否则为服务器启动时指定的根目录。因此,调用作为待读取文件传入的相对路径——交给 validate 的文档、--release 或 --catalog——会在该工作区内读取,就像在该处打开的终端中一样,而命令运行的构建会在该根目录下写入 dist/。如果没有任何东西指定根目录——没有启动根目录,且没有 workspace_root 或其为空——命令会在服务器启动时所在的目录中启动并从那里读取相对路径;指向不存在文件夹的 workspace_root 会按读取时的形式传递——绝对路径按发送的原样,相对路径则为其完整形式——由命令用自己的措辞拒绝。命令扩展插件注册的命令不会接收其中任何一项,因为它会将每个参数原封不动地传给插件,而不解析全局标志,在终端中和这里都是如此;它与其他每个命令在同一文件夹中启动。

    有少数命令被有意排除,即使在标准输入和输出上(也就是命令工具存在的唯一传输方式)也是如此——通过 HTTP 时它们全部不存在,而这是传输方式的属性,而非任何命令的属性。在标准输入和输出上,每个被排除的命令都有明确的理由:守护进程和此服务器本身永远不会返回结果;从终端读取密码的命令无处读取;编写 shell 补全脚本的命令没有可安装的 shell;删除已存储的凭据作用于整台机器范围的存储,而非你指定的任何工作区;交互式获取身份令牌则没有可提供的非交互形式。基于同样的整机范围理由而被排除的还有 aggrega plugin run-local,它从你给出的路径加载 .wasm guest:该命令的用途就是读取你放在任意位置的文件,因此没有可以将其限制在内的工作区,而且读取发生在进程本身中、guest 存在之前。guest 真正运行时不会被授予任何东西——没有目录、没有套接字、没有环境变量——但这是对模块的限制,而不是对读取的限制,因此并不是决定此事的因素。请在你的终端中运行它,由你自己来指定路径。签名和发布则完全是另一种情况,正是这种差异使它们不在该列表中。 它们各自从提供的或环境中的输入解析身份,在无可用身份时明确拒绝,因此各自都有一种无人值守即可完成的形式——而交互式获取令牌是任何输入在原则上都无法满足的操作。因此它们出现了两次:作为命令,以及作为 发布、签名和撤回 中描述的四个进程内工具。在命令行会打开浏览器的情况下,它们会拒绝并指明应改为提供什么,而不是等待一个不在场的人。

调用在哪个工作区中得到应答

调用通过 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 中描述的设置——并完全按给定的原样引用其值;客户端未填写便发送的值按到达时的原样引用,其中的任何内容都不会被识别。对于未指定自身工作区的调用,运行命令的工具不会启动任何命令,因为该命令本应启动所在的文件夹并不存在,并以同样的拒绝作为应答。通过绝对路径指定了自身工作区的调用在该工作区中得到应答;通过相对路径指定的调用没有可用来读取它的文件夹,会以同样的拒绝作为应答。不在任何工作区中执行的操作——schema、提示、命令帮助——则与在任何服务器上一样得到应答。监听器则改为在启动时、在绑定任何内容之前以同样的拒绝被拒绝,这样负责监管它的人可以在查找故障的地方读到该故障。

Workspace folder 设置为空的桌面启动同样以拒绝的形式提供服务。 桌面捆绑包始终向服务器传递 AGGREGA_WORKSPACE_ROOT,其中携带 Workspace folder 中的任何内容,并同时设置 AGGREGA_BUNDLE_VERSION,而应用程序会在其自行选择的文件夹(通常是系统文件夹)中启动服务器,而不是在你的项目中。因此,一个基于标准输入输出、未使用 --workspace-root 启动、环境中带有 AGGREGA_BUNDLE_VERSION 且 AGGREGA_WORKSPACE_ROOT 为空或不存在的服务器,不会从其启动所在的文件夹查找工作区。它将拒绝信息写入错误流并照常启动,应答方式与启动根目录不存在时相同:每个会在工作区中执行操作且未指定自身工作区的调用,都以一条拒绝作为应答,说明桌面应用程序在 Workspace folder 设置为空的情况下启动了服务器,因此 AGGREGA_WORKSPACE_ROOT 未指定工作区根目录,并提示你将 Workspace folder 设置为包含工作区 .aggrega-config.yaml 的文件夹,同时说明在服务器启动后设置的文件夹要在关闭并重新开启该扩展或重启应用程序后才会生效,因为应用程序只在启动服务器时才将该设置传给服务器。对于此类调用,运行命令的工具不会启动任何命令。通过绝对路径指定了自身工作区的调用在该工作区中得到应答,通过相对路径指定的调用则以同样的拒绝作为应答,因为没有可用来读取它的 Workspace folder;不在任何工作区中执行的操作则与在任何服务器上一样得到应答。服务器仅通过 AGGREGA_BUNDLE_VERSION 识别这种启动:不设置该变量的捆绑包,其空设置被视为没有根目录;手动设置该变量且未指定根目录的启动,会像捆绑包的启动一样被拒绝。其他所有空值仍然表示没有根目录——在未携带 AGGREGA_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,以及一行提示,让你发送 workspace_root,指向包含工作区 .aggrega-config.yaml 的文件夹;不由工作区决定的应答,例如配置读取或插件列表,不会提及工作区。这句话不会在结构化结果中添加自己的字段;结构化结果将其包含在存放文本的 text_answer 中,详见应答的两个部分。在独立进程中运行命令的工具会携带命令自身输出的同样内容的那一行。在这样的文件夹中不会向任何制品缓存写入内容:在此处执行的拉取,或要求先解析依赖项的构建,会在获取任何内容之前被拒绝,并指明该文件夹和两种解决方法——发送 workspace_root,或为该文件夹提供一个带有 workspace: 块的 .aggrega-config.yaml。如果固定版本或发布 Recipe 或 FeatureRecipe 时需要获取实体完整写出的远程来源——为了固定它或比较其固定版本——则同样会在获取该来源之前被拒绝;如果无需获取任何来源,因为该实体没有来源、来源是本地的或其坐标由每个 Release 填写,则与在其他任何地方一样得到应答。在此处不先解析任何内容的构建仍会渲染,但其 lockfile 固定而缓存中已不再持有的外部输入不会被重新获取:渲染会收到同样那句话来代替该输入,就像在离线状态下收到的提示一样。通过 HTTP 的应答都不会携带这句话:监听器始终服务于它被给定或找到的工作区。在 Workspace folder 设置为空的情况下由桌面捆绑包启动时也不会携带,因为它会拒绝未指定自身工作区的调用,而不是在其启动所在的文件夹中应答。

如果没有其他方式确定工作区,则对于以绝对路径指名某个 Release 或文档的调用,在该文件自身所在的工作区中应答。 如果启动时未指定根目录、调用未发送 workspace_root,且服务器的启动目录也无法锚定任何工作区,则会从该文件所在的文件夹重新发现工作区,所找到的结果——该文件所属的项目,或在一切都失败时就是该文件夹本身——即为应答该调用的工作区。这正是在终端中输入的命令所遵循的规则,因此它适用于每一个调用涉及其所指名的 Release 或实体文档的工具:构建、拉取、验证、lint、描述、按某个 Release 的术语列出、关于某个 Release 图中节点的查询、固定版本(pin)、发布实体、编辑,以及读取文档中的位置。如果调用同时指名了一个 Release 和一个文档,则以该 Release 为准。因此,即使客户端在你的项目之外启动了服务器,其中的 Release 仍会依据项目自身的配置进行构建。调用所指名的其他路径照常读取——相对路径从服务器的启动目录解析——而在单独进程中运行命令的工具也从同一工作区应答,因为该命令在同一目录中遵循相同的规则。启动时指定的根目录、调用发送的 workspace_root、本身位于某个工作区内的启动目录,以及以相对路径指名的 Release 或文档,均按原样使用。通过 HTTP 时不会出现上述情况:监听器始终服务于它被给定或找到的工作区,调用所指名的每个路径都相对于该工作区。在桌面安装包以空的 Workspace folder 设置启动时也不会出现:无论调用指名哪个文件,只要它未指名自己的工作区,就会被拒绝。

收窄服务器公布的内容

mcp.announce_tools 指定此服务器公布哪些工具,名称须与工具列表报告的写法完全一致。 省略该键,则公布此服务器携带的所有工具,这是默认行为,也是遵循协议的客户端所期望的形式。写一个列表,则恰好公布列表中的工具:未列入的工具不会出现在工具列表中,也不会出现在 describe-capabilities 的回答中;即使按名称调用它,也会被拒绝,拒绝信息会指明此设置。写一个空列表,则什么都不公布——因此省略该键与写 [] 是两种不同的声明,该设置不会替你填入默认值。

当另一端的客户端限制其注册的工具数量时设置它(有时这一上限针对它同时连接的所有服务器),并列出该客户端需要的工具。这一上限正是该设置存在的原因,而受此上限约束的客户端通常就是通过自身标准输入和输出启动此服务器的那个客户端——因此,与 mcp 块的其余部分(它们配置 http 传输启动的监听器)不同,无论服务器使用哪种传输,都会读取此键。

它只收窄公布的内容,除此之外什么也不做。 在此列出一个工具不会放宽任何限制。它不会解除 mcp.deny_reach,后者会彻底撤销某项能力,因此在此列出、但属于该设置所撤销类别的工具仍不会出现在列表中,调用时会被拒绝并指明该设置。它也不会解除调用方令牌所携带的作用域:在此列出的工具无论这些作用域如何都会被列出,但作用域不允许的调用仍会被拒绝,并指明能允许该调用的作用域。无论哪种情况,调用方遇到的拒绝都来自那另一项限制,而非此设置。此设置产生的拒绝不带质询,也不指明作用域,因为任何凭据都无法改变服务器选择提供的内容——它指明的是该设置,这是任何阅读拒绝信息的人唯一能采取行动的对象。

每个名称都必须是此二进制文件携带的工具。 没有工具对应的名称会让服务器在提供任何服务之前停止,拒绝信息会列出它实际拥有的工具——因此拼写错误会在启动时被发现,而不是悄无声息地得到一个比你所要求的更窄的工具面。cli- 系列的名称(在单独的进程中运行一条 aggrega 命令)在两种传输上都被接受,但通过 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 中,而不是被提供后再拒绝;指定其中某个工具的调用会收到说明这一点的错误。这是传输方式的属性,而非一项设置:没有任何配置能让它们恢复。

部署之前,请先阅读没有凭据则不提供任何服务。 发往该端点的每个请求都携带凭据,也没有任何设置能在没有凭据的情况下处理请求——设置所选择的是由此服务器自行检查 bearer token,还是读取前置代理已检查过的调用方。

两种部署形态

进程自行终止 TLS。 将 mcp.tls.cert_file 设为 PEM 证书链,将 mcp.tls.key_file 设为其私钥,监听器即在你给出的任何地址上直接提供 HTTPS 服务。两个文件都在进程启动时读取,因此替换证书后需重启进程才能生效。只设置其中一个会在启动时被拒绝,而不是回退:没有私钥的证书无法出示,没有证书的私钥毫无指向,而某个路径中的拼写错误不应成为开始提供未加密流量的理由。

由前置代理终止 TLS,并转发到受限的监听器。 两个键都不设置时,监听器提供明文服务,这仅在回环地址或 Unix 套接字上被接受——因此不在该主机上的任何东西都无法访问它。这是反向代理、sidecar 或服务网格所使用的形态,在这种形态下证书位于此进程之前,而非进程之内。

其他任何地址上的明文监听器都会在绑定任何内容之前被拒绝,拒绝信息会指出两个 TLS 键。没有任何设置能解除这一限制,也没有任何地址是例外:从网络接受连接却没有自己证书的监听器永远不安全,因此进程会拒绝启动,而不是以这种形态启动。

地址格式

--listen 和 mcp.listen 接受以下两种格式之一:

  • host:port——TCP 地址,例如 127.0.0.1:7777 或 0.0.0.0:8443。回环地址指 127.0.0.1、::1,或在该名称解析到的每个地址都是回环地址时的 localhost。其他任何地址都是网络地址,需要证书:空主机(即机器的所有网络接口);某个具体的接口地址;以及任何其他名称,即使它此刻解析到回环地址也是如此,因为监听器可以绑定的位置不应依赖于可能随时变化的解析结果。
  • unix: 后跟文件系统路径——Unix 域套接字,例如 unix:/run/aggrega/mcp.sock。套接字只能从其所在的主机访问,因此不需要证书。

套接字路径完全按原样使用,相对路径也是如此。它特意不相对于声明它的配置文件进行解析,因为同一地址也可能来自 --listen,而后者没有声明文件——参见相对路径指向何处。

监听器接受什么

一个端点 /mcp,接受 POST。 每条 JSON-RPC 消息都是一个独立的请求,并且不保留任何形式的会话:客户端先发送的任何内容都不会决定后续请求如何应答,从不生成会话标识符,客户端发送的会话或流恢复头会被忽略。该端点上的任何其他方法都以 405 和 Allow: POST 应答,任何其他路径都以 404 应答——两者都在凭据检查之前确定,因此探测者无法从一个本就不提供任何服务的路径或方法上的质询中获知任何信息。

请求以一个 JSON 对象和一个状态码应答——或者,若调用在得出该对象的过程中报告了进度,则以一个以该对象结尾的事件流应答,详见获知长时间调用的进展。通知(不带 id 的消息)以 202 和空正文应答。两者都不是的消息,包括 JSON-RPC 响应,以 400 应答,因为客户端只向此服务器发送请求和通知。

两个协议修订版在这里的服务方式与通过标准输入输出时完全相同。 2026-07-28 请求会在传输头中镜像其正文,以便中间方无需解析正文即可路由:MCP-Protocol-Version 携带正文声明的修订版,Mcp-Method 携带其指定的方法,Mcp-Name 携带目标(针对按名称寻址目标的方法)。与正文不一致的头以 400 应答。2025-06-18 客户端以 initialize 握手开始,该握手以无状态方式应答;它可以携带指明该修订版的版本头,也可以省略。指明服务器不支持的修订版的请求以 400 应答,并列出它支持的两个修订版;指明服务器不提供的方法的请求以 404 应答。

仅当请求携带 Origin 头时才会参考 mcp.allowed_origins,实际上这意味着请求由浏览器发出:指明列表中没有的源的请求以 403 应答,不带该头的请求照常处理。非浏览器客户端不发送该头,也不需要条目。基于浏览器的客户端始终需要条目:在运维人员写入之前列表为空,因此在此之前不包含任何源,所有浏览器请求都以 403 应答——包括来自端点自身地址上所提供页面的请求。条目与该头进行精确比较,因此要按浏览器发送源的方式书写——小写的 scheme、://、小写的主机,以及在非该 scheme 默认端口时的 : 和端口,例如 https://app.example.com——带路径、末尾 /、缺少 scheme 或含大写字母的条目会在配置加载时被拒绝,并指明该条目,因为它永远无法匹配。

mcp.limits 限制所接受的流量。 超过 max_body_bytes 的正文以 413 应答,且读取不会超过该上限。在已有 max_concurrent_requests 个请求处理中时到达的请求以 503 应答,而不是排在它看不到的工作后面。一分钟内发送超过 requests_per_minute 个请求的调用方以 429 应答,计数只针对该调用方,因此一个调用方的大量请求不会让另一个调用方付出任何代价。每项上限的默认值都在配置参考中对应键旁说明,并且没有任何值可以关闭它们。

一个进程,一个工作区

**服务进程所应答的工作区在其启动时即已固定。**由 --workspace-root 指定;未给出该标志时,由 AGGREGA_WORKSPACE_ROOT 变量提供。所指定的文件夹本身就是工作区根目录,不会向上搜索;不存在的文件夹会被拒绝,拒绝信息会指出是两者中的哪一个提供了它,并按原样引用该值——监听器在绑定之前拒绝,基于标准输入输出的服务器则在其对每个在该工作区中执行操作的调用的应答中拒绝,详见调用在哪个工作区中得到应答——因此由客户端组装而非手动输入的启动命令同样会说明它收到了什么。两者都未给出时,基于标准输入输出的服务器从其启动所在的目录解析工作区——若该处没有任何东西锚定工作区,每个与工作区相关的应答都会说明它使用了哪个文件夹;而桌面捆绑包在 Workspace folder 设置为空时启动,则会拒绝未指定自身工作区的调用,详见调用在哪个工作区中得到应答——而监听器除非能在该处解析出工作区,否则会在绑定之前被拒绝:通过 HTTP 访问的进程应答的是看不到这台机器的调用方,因此它服务的是操作员选定的工作区,而不是它恰好在其中启动的任意目录。如需服务多个项目,请为每个项目根目录运行一个进程。

通过 HTTP 到达的调用不能指定自己的工作区。workspace_root 和 catalog_dirs 会被拒绝,并指出所发送的参数,而不是被悄悄丢弃:一个被静默忽略的参数,在发送方看来与被采纳的参数毫无区别。在所服务的工作区之外一并搜索的目录目录,是该工作区自身的 workspace.catalog_dirs 设置——或者,对于在 workspace.releases 下为其指定了自有目录的 Release,则是该 Release 的设置——由操作员编写。通过标准输入输出时,这两个参数都会被采纳,因为启动服务器的客户端运行在调用方自己的机器上。在这种情况下,catalog_dirs 条目要么是绝对路径,要么相对于读取相对 release 所依据的工作区根目录——即调用自身的 workspace_root、启动参数或服务器启动所在目录最先确定的那个根目录,并且当以绝对路径指定的 Release 将调用移入该 Release 自己的工作区时,仍然相对于该根目录读取——而不是相对于服务器运行所在的目录(如果二者不同)。

**调用所指定的路径同样限定在该工作区内。**通过 HTTP 时,路径参数会相对于工作区根目录解析,若超出范围则被拒绝——向上越出工作区的相对路径、指向其他位置的绝对路径,以及经由工作区内指向文件或目录的链接而通向工作区外的相对路径,都会返回一个失败,指出该参数,但既不指出工作区根目录,也不指出该路径本会到达的位置;相对路径会按你发送的原样引用回来。每个路径参数都按其最终通向的位置、依据工作区边界所述的“内部”定义来判断,无论工具是读取还是写入它——gen-catalog 写入输出的目录、edit-document 写回的文档、pin 在其旁边写入锁文件的实体,与工具读取的文档一视同仁——因此,位于通向工作区外的链接之下、尚未创建的路径,会像该链接一样被拒绝,不读取也不写入任何内容。若 release 指定的是所服务工作区的配置中以 build.authoring_release 或 workspace.releases 的键所指定的 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,应答的可读文本遵循同一规则。 当文本、诊断行或失败消息指明工作区所持有的位置——其根目录或其下任何内容、读取其配置的配置文件、读取其目录(catalog)的目录——该位置会写成相对于根目录的形式;若位于工作区外或就是根目录,则写作 (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;对于整个目录(catalog),target 就是根目录,因而被隐去。diagnostics 或 notices 中的位置遵循文本规则。
  • build 以相对于根目录的形式指明 release,先解析了依赖的构建会携带 dependency_resolution,其形式与 pull 的应答相同。收到 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;从工作区外的目录(catalog)目录读取的实体,其 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 套接字,这正是它的用途:供与此进程在同一主机上运行的监管程序、负载均衡器或容器运行时使用。凡是能访问你所选地址的对象都能读取这两个应答,因此开放网络能访问到的地址会把它们公开给开放网络。

没有凭据就不提供任何服务

**发往端点的每个请求都携带凭据,具体是哪种凭据,取决于前置代理是否已经检查过它。**默认情况下,它是由此服务器自行验证的 bearer 令牌,本节其余部分对此进行说明。设置 mcp.authorization.trusted_proxy 后,它改为由该代理设置的一个标头,详见从前置代理读取调用方,在这种情况下完全不读取令牌。两种方式都不会为不出示任何凭据的请求提供服务。

**默认情况下,服务器自行检查 bearer 令牌。**它从 Authorization 标头中读取令牌,并且只在以下条件全部满足时才接受:签名能够用授权服务器公布的密钥验证通过;令牌将 mcp.authorization.issuer 指定为其签发方;令牌在其受众中包含此部署自身的 mcp.authorization.resource;令牌处于有效期内;令牌声明了出示者是谁。未通过其中任一项检查的令牌会得到 401 应答,并在不携带任何凭据的调用方所收到的同一质询中附加 error="invalid_token"。无论是哪一项检查拒绝了令牌,应答都完全相同,因此调用方只会得知它需要另一个令牌,而不会得知所发令牌的哪一部分有误。只接受非对称签名算法:未签名的令牌以及声明对称算法的令牌,会在读取其中任何内容之前被拒绝。

**令牌可以声明自身的类型,共接受四种形式。**JWT 可以携带 typ 标头来声明自身类型。此服务器接受 at+jwt 和 application/at+jwt,即为访问令牌注册的两种写法;接受 JWT,它只表明该令牌是一个 JWT;也接受完全不声明类型的令牌。其他任何类型都会得到 401 应答,与其他被拒绝的令牌完全相同。这个集合是固定的,没有任何设置可以扩大或缩小它,因为那里出现哪种形式,取决于签发令牌的授权服务器,而不是接收令牌的部署。接受 JWT 确实意味着仅凭声明的类型已无法区分访问令牌与身份令牌:区分二者依靠的是受众检查,这也是该检查起关键作用的原因。身份令牌的受众是它所签发给的客户端,绝不会是此部署自身的 mcp.authorization.resource,因此为此部署以外任何对象签发的令牌,无论自称什么类型,都会被拒绝。

**这允许哪些授权服务器。**Microsoft Entra ID 签发类型为 JWT 的访问令牌。Keycloak 签发 at+jwt,在启用其 OpenID Connect 兼容模式时签发 JWT。Auth0 在其自身的令牌配置下签发 JWT,在其 RFC 9068 配置下签发 at+jwt。来自上述任一授权服务器的令牌,无论携带这两种形式中的哪一种,都能通过此检查。不支持 Okta:它的访问令牌声明的是其自有类型,不属于上述四种之一,因此此服务器会拒绝它们。

**令牌被拒绝时,原因会留在服务器自身的错误流中。**调用方只会被告知它出示的内容未被接受;提供服务的进程会写入一行,指明拒绝该令牌的检查项:受众、签发方、有效期、签名、密钥标识符、声明的类型,以及其他各项。正是借助这一行,当部署拒绝所有请求时,运行它的人才能诊断问题,而不是只有调用它的人才能察觉。这一行不包含令牌的任何部分。完全不出示凭据的请求不会写入任何行,因为客户端正是通过接受质询才得知从哪里获取令牌,所以这是每个行为规范的客户端首先会做的事。

**令牌只能放在标头中,不能放在其他任何地方。**以 access_token 查询参数发送的令牌会得到 400 应答,且从不被读取,因为请求经过的每个代理日志、浏览器历史记录和 referrer 标头都会记录地址,所以以这种方式到达的令牌已经暴露。服务器从不把令牌写入日志,从不把令牌发送到任何地方,也从不代表调用方获取或交换令牌:它读取所出示的内容,作出判断,不保留其中任何部分。令牌所指明的主体会被记录,但不与任何内容比较。

**验证密钥来自授权服务器,或来自你指定的文件。**未设置 mcp.authorization.jwks_file 时,服务器从授权服务器的 well-known 地址读取其元数据,跟随其中公布的 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 地址,除非授权服务器运行在本机上。**对于位于 localhost、127.0.0.1 或 ::1 的签发方,接受普通 http,这正是使用本地授权服务器进行本地测试时的形式;其他任何主机上的普通 http 签发方都会在监听器绑定之前被拒绝,拒绝信息会指明 mcp.authorization.issuer 并要求提供 https 地址。这在每种模式下都成立:无论密钥从签发方读取、使用 mcp.authorization.jwks_file,还是前置代理,因为每种模式都会在此文档中公布签发方:遵循该文档的客户端会针对该地址运行其授权流程,因此通过普通 http,授权码及其获取的令牌会在网络上不受保护地传输,无论此服务器是否从那里读取密钥。如果服务器确实从那里读取密钥,那么任何处于该路径上的人还可以用自己的密钥作答,而用这些密钥签名的每个令牌都会被接受。

**此部署公布的作用域名称是 aggrega:read、aggrega:workspace-write 和 aggrega:registry-write。**这些是要在授权服务器上注册的名称,也是客户端向授权服务器请求的名称,而被拒绝的调用方收到的质询会指明 aggrega:read 为首先要获取的作用域。每个作用域允许什么,以及第二重界限(即此部署为自身设置的界限),参见下文调用方可以访问什么。

从前置代理读取调用方

如果前置代理已经验证令牌,mcp.authorization.trusted_proxy 会让此服务器从代理读取调用方,而不是再检查一次令牌。为它提供 principal_header,即该代理设置的用于说明调用方身份的标头,还可以选择提供 scopes_header,即携带该调用方以空格分隔的作用域的第二个标头。每一项都是 HTTP 标头名称,例如 X-Forwarded-User,不含空格或冒号;其他形式的名称会在加载配置时被拒绝,并指明该键,空的 principal_header 同样如此;要关闭此模式,省略整个块即可。只读取这两个标头:转发地址标头和其他任何标头都不参与。未携带主体标头的请求会得到 401 应答,并且此模式下完全不读取令牌:携带此服务器原本会拒绝的令牌的请求,只要存在主体标头就会得到服务;携带此服务器原本会接受的令牌的请求,只要缺少该标头仍会被拒绝。

**该模式只在回环地址或 Unix 套接字上被接受,在其他任何地方,进程都会在绑定之前被拒绝。**只有当除代理之外没有任何对象能设置标头时,标头才是可信的。在网络能访问到的地址上,任何对象都能设置它,因此在这种地址上以此模式运行的监听器会让每个调用方随意自称任何身份。拒绝信息会指明相互冲突的两个设置,因此你可以通过移动地址或删除该块来解除拒绝。

**代理声明什么,此服务器就相信什么,这就是其中的交换条件。**在此模式下,此服务器不检查任何签名,也不将所声明的调用方与任何内容比较,正如它不将令牌的主体与任何内容比较一样。代理是否验证了它转发的内容,以及是否有任何对象能不经过代理就访问该监听器,都需要部署自行确保正确;上述限制使确保正确成为可能,但并不保证已经正确。

**设置 mcp.authorization.trusted_proxy 并不会取消其他要求。**仍然需要 issuer 和 resource,因为元数据文档仍会公布,质询仍会指明它:代理后面的客户端仍需得知从哪里获取代理将要检查的令牌。出于同样的原因,签发方仍需是 https 地址,除非它运行在本机上:该客户端从签发方获取令牌,因此在此模式下,其他主机上的普通 http 签发方会与在其他所有模式下一样,在监听器绑定之前被拒绝,即使此服务器不从它读取任何内容。

调用方可以访问什么

有两重界限决定调用方通过 HTTP 能访问什么,它们由不同的人设置。第一重是调用方自身的凭据;第二重是此服务器究竟承载什么。两者都在任何内容运行之前,从每个操作对自身所作的声明中读取,并且在不同的位置呈现给客户端:工具列表显示此服务器承载并公布的内容,每次调用收到的应答显示凭据允许的内容。

每个操作都会声明其自身效果的影响范围,共有四类,范围最广的排在最后:

  • 不触及任何内容:读取定义、检查 Release 固定的内容、在内存中渲染制品并将其返回。它不留下任何东西:不写入任何内容,应答就是它产生的全部内容。
  • 触及工作区:在此进程所服务的工作区中写入:Release 的锁文件、制品缓存、生成的实体、编辑后的文档。
  • 触及注册表:发布、签名,或为已发布的内容附加撤回标记。它改变的是该注册表每个使用者解析到的内容,而且这些改变都无法从已获取它的任何人那里收回。
  • 触及机器:改变主机上所有工作区共享的内容,其中包括已编译模块存储、所有工作区共用的配置文件以及凭据存储。单个项目保存在自身缓存目录下的缓存不属于此类,cache-status 会报告它列出的每个缓存属于哪一类。

类别是操作的属性,而不是提供该操作的工具的属性,它涵盖的是操作留下的东西,而不是某个界面把它返回的应答放在哪里。渲染 Release 会产生制品作为应答,因此它不触及任何内容;随后把这些制品保存到你指定目录中的命令行,是在交付该应答,而不是触及更远的范围。反过来理解,每个以内容作答的操作都会采用恰好保存它的那个界面的类别,类别就完全不再是操作的属性了。出于同样的原因,通过注册表引用读取实体的 describe 不触及任何内容:它联系该注册表以获取应答,不会在注册表或本机上留下任何东西,它可以联系哪些注册表,参见调用会使用哪些凭据。如果调用本身请求写入,一次调用仍可能触及超出其操作类别的范围:发送了 write 的构建会把制品保存在此服务器所服务的工作区中,因此该调用触及工作区,先解析依赖项的构建也是如此。

作用域允许某一类别,每个写入作用域都隐含读取作用域。aggrega:read 允许不触及任何内容的操作。aggrega:workspace-write 允许触及工作区的操作,并隐含读取作用域。aggrega:registry-write 允许触及注册表的操作,同样隐含读取作用域。因此,客户端向其授权服务器请求所需的写入作用域即可,无需另外请求读取作用域。

**没有任何 scope 准许 machine 类,也没有任何设置能添加这样的 scope。**该类操作只由在独立进程中运行 aggrega 命令的工具承载,而通过 HTTP 访问的服务器根本不提供这些工具,原因见上文通过 HTTPS 访问服务器。请在主机的终端上运行它们。

无论调用方凭据持有哪些 scope,工具列表都会显示该服务器承载并公布的每个工具,而由凭据决定一次调用可以运行其中哪些工具。describe-capabilities 索引并定义的也是同一组工具。凭据不准许的调用会得到 403 应答,质询中带有 error="insufficient_scope",并指明能够准许该调用的那一个 scope,且调用所请求的任何内容都未运行。协议的 step-up 正是针对这种拒绝:实现了 step-up 的客户端会请你针对质询指明的 scope 重新登录。列表不随凭据变化,因此重新登录后的客户端已经持有正确的 scope。不带三个 scope 中任何一个的凭据会收到同样的工具列表,但无法调用其中任何工具,包括 describe-capabilities。

**构建是值得了解的情形。**构建本身不改变任何东西,因此只需要 aggrega:read;但会写入的构建需要 aggrega:workspace-write:发送了 write 的构建会把产物保存到工作区根目录下的 dist/,而先解析依赖的构建会写入 lockfile——无论这是调用通过 auto_pull 请求的,还是工作区自身的 auto_pull 设置所致。该工具和其他所有工具一样会列给只有读 scope 的调用方,而停留在内存中的构建对其确实可用;被拒绝并指明 aggrega:workspace-write 的,是会写入的那次调用。

**不支持 step-up 的客户端仍可被授予写 scope,这在授权服务器上设定。**运行授权服务器的人将写 scope 设为该客户端的默认 scope——即授权服务器向该客户端签发的每个令牌中都会放入的 scope,无论客户端是否请求——这样客户端首次登录获得的令牌就已带有它们。每次连接时都向授权服务器重新注册自身的客户端,每次在那里都是一个新客户端,在先前注册上所做的设置不会延续;对于这样的客户端,生效的是授权服务器给其注册的每个客户端的默认 scope。代价是,此后通过该客户端的每次登录都带有写访问范围,无论手头的工作是否需要——而当默认值是注册时给出的那些时,以这种方式注册的每个客户端也都带有该访问范围。只把工作所需的那个写 scope 设为默认:aggrega:workspace-write 和 aggrega:registry-write 准许不同的类,且互不蕴含。

**mcp.deny_reach 是运行该服务器的人从中撤除某个类的地方,也是缩短工具列表的两个设置之一。**列出该服务器不承载的类——none、workspace、registry、machine——则每个触及其中某个类的工具都会从每个调用方的工具列表和 describe-capabilities 中消失,无论该调用方的令牌如何声明;如果仍被调用,则会被拒绝,错误中会指明此设置。这是服务器自身的边界而非调用方的边界,因此任何凭据都无法解除它,拒绝也不带质询:只打算提供读取的服务器在此列出 workspace、registry 和 machine,之后即使调用方的令牌带有全部三个 scope,也无法发布。省略此设置(默认如此),该服务器就不撤除任何类,一次调用能触及哪些类由调用方自身的 scope 决定。指定 machine 会被接受但不改变任何东西,因为该类的任何操作本来就不在此提供。不属于这四者的值会在加载配置时被拒绝,而不是被忽略——拼错某个类的运维人员要的是一个边界,静默地在没有边界的情况下提供服务是错误的回应方式。

mcp.announce_tools 是另一个缩短工具列表的设置,两者不是同一种边界。deny_reach 撤除的是能力:在那里指定的类的操作在此根本不被承载,对任何人都是如此。announce_tools 撤除的只是公布:它省略的工具仍是该服务器具备的能力,它应对的是客户端自身对将注册多少工具的上限。两者都设置时以撤除为准,因此被撤除类的工具无论 announce_tools 如何指定都保持缺席,调用方遇到的拒绝会指明该撤除。缩短列表的任何设置都不读取调用方的 scope:调用方缺少的 scope 会拒绝调用,但绝不会从列表中移除工具。其余内容见缩小服务器公布的内容。

一次调用消耗哪些凭据

通过监听器进行的无密钥签名,其身份只取自调用携带的 identity_token,别无其他来源。 调用中发送的令牌是调用方持有的凭据:调用方必须自行获取它,它绑定于调用方,它所生成的签名也可归属于调用方。身份可能来自的其他任何地方都属于启动此进程的人,因此在这种传输方式下,解析过程拿到的是一个什么也不回答的环境。服务器环境中的 AGGREGA_IDENTITY_TOKEN 和 SIGSTORE_ID_TOKEN 不会被读取,环境中的 GitHub Actions OIDC 端点也不会被访问。它们是无法触及,而不仅仅是不被鼓励——解析过程根本找不到任何东西。未发送 identity_token 的调用会被拒绝,拒绝信息指出应发送 identity_token,而不提及任何变量或端点:不在这台机器键盘前的调用方无法在这里导出任何东西,提及它们就等于让调用方去安排一件无法改变结果的事。

这台机器上持有的签名密钥无法通过任何一种途径被选中。 key_path 在任何解析发生之前就会被拒绝,而且它不出现在 publish-entity、sign-artifacts 和 deprecate-artifact 在此处公布的参数 schema 中,因此调用方永远不会被提供一个不可能成功的参数。所服务工作区自身配置中指定的签名密钥同样无法触及——即 signing.key_path,无论它是为整个工作区设置、针对某个 registry 设置,还是由环境提供。两者出于同一个原因:密钥路径不是凭据,而是此服务器所持有的某个秘密的名称。调用方提供它并不能证明任何事,任何能访问此地址的人都能提供同样的名称,随后产生的签名表明的是运营者而非调用方为该制品作保。只关闭参数而保留配置,就如同关上一扇门,而另一扇门仍通向同一个房间。因此,通过监听器无法进行基于密钥的签名:只有调用中发送的令牌才能签名。

fulcio_url、rekor_url 和 timestamp_url 不受影响,在两种传输方式下都保留。 它们指定的是要联系的服务,而不是这台机器持有的任何东西,因此无法选择密钥的调用方仍然会针对此部署所配置的端点进行签名。

在指定了签名密钥的工作区上启动的监听器会在启动时说明一次。 进程会在自己的错误流中写入一行,指出该设置,并说明访问此监听器的调用方无法使用该密钥——这样运营者是从自己启动的进程中得知这一点,而不是从一个意料之外的签名中得知。未指定密钥的工作区不会产生这样一行,因为没有什么可说的。该行只包含设置的名称,既不包含密钥,也不包含有关其所指文件的任何信息。

通过标准输入和输出时,以上各条均不适用。 此时会读取环境,key_path 会选择这台机器上持有的密钥,因为启动此服务器的客户端运行在调用方自己的机器上,该进程能触及的东西本就归调用方自己使用。

按 registry 引用读取实体只会联系一个 registry,使用本主机自己的登录凭据;通过监听器时,只能是所服务工作区已配置的 registry。 向 describe 发送一个 oci:// 引用作为其 name,会读取发布在该坐标处的实体——与 aggrega inspect 执行的读取相同——从该引用指定的那个 registry 读取,使用本主机已为该 registry 持有的登录凭据。调用不携带凭据,describe 也不接受凭据。通过 HTTP 时,该 registry 必须是所服务工作区已配置的:其 default_registry 指定的主机,或 registries 下列出的主机,按精确匹配(包括端口)比较。指向任何其他主机的引用——包括这台机器上的地址——会在联系该主机之前被拒绝,拒绝信息会指出该主机,因此调用方无法让此服务器指向其任意选择的目的地。仍可访问的部分是有意为之:持有 aggrega:read 的调用方可以读取本主机登录凭据在工作区已配置的 registry 上能读取的任何内容,这也正是坐在本主机终端前的人能读取的内容。通过标准输入和输出时,指向任何 registry 的引用都会被读取,与命令行中一样。按目录名描述实体不受影响。

registry 调用使用此进程运行时所用操作系统用户的凭据存储,与在本主机终端执行同一调用完全相同。不存在按工作区划分的凭据来源,也没有可以添加这种来源的设置,这就是为什么 registry-list 在这台机器上的每个工作区中报告某主机凭据状态的方式都相同。希望不同工作区持有不同 registry 凭据的部署,应以不同的操作系统用户运行它们——每个工作区一个进程,各自以自己的用户身份启动。隔离由此而来,安排这一点是运营者的事。

服务器记录的内容

该端点应答的每个请求都会在进程的错误流上留下一行,该行是单个 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 应答开头的那句话,如服务器来自哪个版本所述;不是由桌面包发起的启动,以及桌面包与可执行文件来自同一版本的启动,交出的指导说明都不含这句话。这两者都在进程启动时确定,并且在任一进程中,两个协议修订版仍以完全相同的方式提供该进程自己的文本。

它传授的是工具的参数 schema 本身无法传达的心智模型:

  • 编译器做什么,以及它刻意不做什么——它路由文本并计算标签匹配,而不解释值的含义;它对你放入文档的内容不预设立场;在编译过程中,它从不向 provider 进行身份验证,从不读取集群的状态,也从不把 secret 转换为明文。只有在基础设施运行后才存在的值,会作为一个指针字符串传递下去,由目标环境稍后填入。
  • 编写词汇,以及各种 kind 之间的关系——每种 kind 的用途,以及构建实际针对的是哪一种,这样助手就不必从工具列表中推断部署的形态。
  • 编写循环的运行顺序——先读契约,据此生成脚手架,检查你要连接的对象,然后在渲染前进行检查。
  • 何时使用 prompt 而不是工具——工具用于执行操作,prompt 用于框定任务。
  • 工具列表就是全部接口——该服务器提供的每个工具都在其中,而服务器提供哪些工具取决于它的设置方式,因此助手应从该列表和 describe-capabilities 中了解这里有什么,而不是去寻找第二份列表。如果连接出示了凭据,它会说明:凭据决定一次调用可以运行其中哪些工具,但从不决定列出哪些工具;不被允许的调用会被拒绝,并给出能够允许它的 scope,客户端可以针对该 scope 重新登录。
  • 空工作区意味着什么,以及模型可以对此做什么——即下文中因传输方式而异的那一段。

它指明各个接口,而不是复述它们。 每个工具已经在 tools/list 中带有自己的描述和参数 schema,每种 kind 的契约也已存在于其 schema 和参考页面中,因此指导说明只指向这些内容而不再展开——每条陈述只有一处归属。它提到的工具都是服务器所提供的工具,并且它指向读取接口所解析的每一个资源族,因此它让助手去查找的内容都不会是死胡同。

它不包含工具本身的索引,这正是同一规则的体现,而不是对该规则的遗漏。客户端在读到这段文本的一个字之前,就已经从 tools/list 获得了每个工具的定义,因此在这里为每个工具写一行,就是对其已有用途的第二份副本——每个会话、每个客户端都要为此付出代价,而且一旦其中任一方被编辑,两者就可能互相矛盾。

它还说明了它不枚举哪些内容以及原因:可用的渲染目标和已安装的库 kind 是你的插件和 schema 集合的属性,因此由资源接口直接报告,而不是由指导说明携带一份可能不一致的副本。

模型对空工作区被告知什么

结尾段落回答的是模型在一个空工作区上首先遇到的问题:空的 list-entities 意味着什么,以及它可以对此做什么。其开头在两种传输方式上相同——空列表意味着该进程解析到的工作区中没有它能读取的 Aggrega 文档,并且在其旁边配置的目录目录中也没有声明任何文档——而后续内容取决于该进程服务的是哪种传输方式,因为在两者上诚实的答案并不相同。

通过标准输入输出时,模型被告知该工作区可由它检查和修复。 它会被告知未指定工作区的调用在哪里得到应答——如果服务器启动时指定了文件夹,就在该文件夹中;否则在从其启动所在文件夹找到的工作区中,该工作区可能就是这个文件夹本身——并且调用中的 workspace_root 可以指定另一个工作区。它会被引导使用 config-show 查看当前生效的配置以及每项设置由哪一层决定,使用 cli-config-init 生成一份可用的配置;在该传输方式下,这两个工具都在工具列表中。运行服务器的客户端位于调用者自己的机器上,因此该进程能触及的内容由调用者自行支配——而你设定边界的位置与其他所有工具相同,即在你的 MCP 客户端中,如助手无需事先询问你就能做什么所述。

通过 HTTP 时,模型被告知应当报告而不是配置。 工作区是你启动进程时指定的那个,并在进程生命周期内固定不变;指定 workspace_root 或 catalog_dirs 的调用会被拒绝,并指出该参数;无论调用者的凭据带有哪些 scope,这里都不会向任何调用者提供写入配置的工具。这些操作只由在独立进程中运行 aggrega 命令的工具承担,而通过 HTTP 建立的会话在组合时不包含这些工具——因此边界在于组合本身而不是 scope,任何令牌都无法扩大它。因此,通过监听器访问你的部署的模型无法在你的主机上生成 registry 或改写信任策略,而该段落会直接告诉它这一点,而不是让它尝试后再去读取拒绝信息。

助手无需先询问你即可执行的操作

通过标准输入和输出连接到此服务器的助手可以调用服务器公开的每个工具,无需询问你,除非你的客户端配置为拒绝。 在该传输方式下,服务器提供工具,但不决定任何特定调用可以使用其中哪些工具:这一决定属于你的客户端,由你在那里做出。通过 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 端点获取身份令牌;key_path 则改为选择离线持有的密钥。因此,能够调用这些工具的助手可以以你的身份签名,使用运行服务器的机器已具有的任何身份——而签名是关于谁为制品担保的声明,这正是在允许之前最需要慎重考虑此操作的原因。通过监听器时,只有调用中发送的令牌才能签名:不会读取服务器环境中的任何内容,主机上持有的任何密钥也无法通过参数或所服务工作区的配置选中,详见调用使用哪些凭据。
  • aggrega cache evict 精简已编译模块存储,aggrega cache clear 则将其清空。该存储由机器上的每个 Aggrega 项目共享。从中删除的模块会按需重新编译,因此不会永久丢失任何内容——但任何项目的下一次构建都要承担该开销。aggrega cache clear 还会删除机器上每个项目读取的文档包,下次其中某个项目获取它时会重新下载。
  • aggrega cache prune 回收没有任何锁文件引用的制品缓存条目。如果某个项目的锁文件不存在而无法读取,其固定的制品就不受它保护,回收它们意味着需要重新获取。
  • aggrega registry add 和 aggrega registry remove 默认写入所有工作区共享的配置,因此它们改变的是整台机器上的解析结果,而不仅是这里。aggrega registry add 还会向其指定的注册表请求该注册表公布的信任策略,并固定所得到的内容,与在终端中的行为完全相同。在离线工作区中,该获取会在发起任何连接之前被拒绝,因此添加官方 hub 以外的注册表会被拒绝——短代码 E0310,措辞相同——除非调用提供 identity 或 key;aggrega config init 两者都不接受,离线时只能初始化 hub。在标准输入和输出上,它们可通过 cli-registry-add 和 cli-registry-remove 使用,初始化则通过 cli-config-init,它们会运行相应命令;通过 HTTP 时这些工具不存在。
  • pull 从注册表读取,并写入其指向的工作区内。 它写入该 Release 的锁文件,用其解析的内容填充制品缓存,并在锁文件旁记录你的工作区所附加的每个返回裁决的插件的身份。若发送了 pin_sources——或者在 pin_sources_at_pull 开启的工作区中且调用未将其作为 false 发送——它还会对该 Release 从你的目录目录构建所用的 Recipes 和 FeatureRecipes 运行实体作者的固定步骤,在每个旁边写入 entity.lock;若没有它,对于锁未记录其所读输入固定的此类实体,拉取会被拒绝,并指明该步骤。实体文件本身永远不会被写入。所有这些都不会离开本机,而再次解析即可更改其记录的内容,因此这是这里会写入的操作中最温和的一个。它是为创作循环设计的、在工作区内写入的工具之一:pin 在你指定的 Recipe 或 FeatureRecipe 旁写入 entity.lock,详见固定实体自身的输入;gen-catalog 在你指定的目录下写入生成的 Plugin 实体;edit-document 对你已有的文档应用一次有界的结构化编辑并写回,保留编辑未触及的每个字节,详见对文档应用一次有界编辑;import 将另一工具生成的描述转换为草稿创作文件并写入工作区,详见将外部描述转换为草稿实体;发送了 example 的 scaffold 则会像 aggrega scaffold --example 一样,将文档中的一个可运行示例写入新的或空的目录 dir,在 HTTP 上,workspace-write 作用域允许这一操作。该输出目录、gen-catalog 读取的 guest 以及你提供的任何覆盖层,都相对于工作区根目录,或者在标准输入和输出上可以是绝对路径,这与此界面上其他所有路径参数遵循的约定相同。在标准输入和输出上,同一能力也可通过 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 时不予提供,详见回答对服务器文件系统透露了什么)、实体总数以及每种 kind 的数量;list-releases 报告总数以及每个顶层目录的数量,因此你能知道有多少个 Releases 以及它们位于目录树的哪一部分。两种细分都是从文档本身读取的,因此一个以无人预料的方式组织的工作区,其摘要与常规组织的工作区一样准确。两者都是每种 kind 或每个顶层目录一行,因此其大小取决于工作区声明了多少种 kind、其 Releases 位于多少个目录,而不是它包含多少文档:把工作区中的文档数量乘以一百而 kind 不变,摘要只会增加书写更大数字所需的几个字节。声明更多 kind 才会让它变长。两者都不是记录的第一页,而这一区别正是关键所在:“这是部分实体”与“这是工作区的构成”是不同的回答,只有后者能告诉你是否需要任何记录,以及需要哪些。

发送 response_format: detailed 以获取记录,记录按页返回。 此时 list-entities 报告每个实体的 kind、名称、apiVersion、描述、标签和源文件,均直接读取自声明它的文档。它还会报告你所配置的目录录目录中声明的 Features,使得作为可附加项提供给你的 Feature 也能被查到;这些条目不带源文件,因为它们唯一的路径是服务器所在机器上的路径,并且每个条目都会说明其来源,使空的文件字段读作“从目录录解析”,而不是缺失的值。list-releases 报告每个 Release 的路径,lockfiles 则把它返回的每个路径映射到该 Release 的 lockfile 路径,采用相同的坐标:即 pull 为它写入、build 读取的文件,也就是语言服务器的 Release 回答所指明的同一个文件。该映射描述本次回答所携带的路径,因此随页面变化,摘要中它为空。

detailed 和 concise 是 response_format 仅接受的两个值,并且按精确匹配。 任何其他写法——不同的词、不同的大小写,或在值前后加空白——都会被拒绝,拒绝信息会列出所发送的内容以及该参数接受的值。省略 response_format 即请求默认值,对这两个工具而言就是摘要。凡是出现该参数的地方都同样适用:build、describe 和 validate 以相同条件接受相同的两个值,而它们的默认值是更完整的形态而非简短形态。

无论你是否限定,记录都有上限。 limit 是一次回答携带的记录数,范围为 1 到 500,默认为 50——因此请求记录却未指定页大小的调用仍然有上限,两个工具的任何调用都不会返回由工作区自身规模决定大小的回答。offset 是列表中的起始位置,从 0 开始计数。两者都只限定记录,因此对不含记录的摘要没有任何影响。超出该范围的 limit 会被拒绝,并指明上限;超过列表末尾的 offset 返回空结果,因为那里只是没有内容,而不是问题本身有误。

从回答中读取三个字段即可继续列表。 count 是工作区包含的记录数,offset 和 returned 说明本次回答的起始位置和携带数量,more_remaining 说明是否还有剩余。只要 more_remaining 为 true,就以 offset 加 returned 再次调用。该信号是根据页面与总数计算得出的,而不是写入回答的,因此不会在仍有记录时报告没有剩余。

这一切之所以重要,是因为接受名称的工具在无法解析名称时会拒绝,而不是返回空结果。这种拒绝是有意为之——空回答会把拼错的名称报告为一个无可提供的主体——但这意味着手中没有名称的调用方无法靠猜测获得名称。枚举才是获得名称的途径。

这两个工具可以相互组合,也可以与其余工具组合:

  • 调用 list-entities 获取摘要,查看工作区包含哪些 kind 以及各有多少,然后用 response_format: detailed 再次调用以获取记录,从结果中取出一个名称,交给 describe 以查看该实体完全解析后的定义。它就是语言服务器的 aggrega/entityDefinition 所回答的定义,以 JSON 形式承载:每个键使用其作者书写的名称,按定义中的顺序排列,schema 保持作者所写的样子,实体未声明的 schema 则被省略——一个 Component 的每个 socket 都带有其连接可填充的 slot。
  • 对 list-releases 也照此操作,从详细结果中取出一个路径,作为要处理的 Release 交给 describe 或 build。
  • list-releases 返回的路径相对于工作区根目录,这与 list-entities 报告文件所用的坐标相同,因此两个回答在文件上对齐,可以结合阅读。其 lockfile(位于 lockfiles 下)同样相对于该根目录,因此你无需推算它的位置即可读取或比较该文件。

两者都通过读取每个文档自身的 kind 来判定哪些文档计入,从不依据文件名。未使用约定前缀命名的 Release 会被列出;仅仅命名得像 Release 的文件则不会,它会出现在其实际声明的 kind 之下。完全没有声明 kind 的 YAML——chart 的 values 文件、恰好位于目录树中的配置文件——不是实体,不会被报告;属于其他项目的文档(例如渲染出的 Kubernetes manifest)也同样不会。一个文档同时声明了 kind 和名称,且未声明 Aggrega 自身组之外的 apiVersion 时,才算作实体,因为这两者合在一起才使它在之后可被寻址。完全没有声明 apiVersion 的文档会被报告,因为它是一个缺少字段的 Aggrega 文档,而不是其他项目的文件。list-releases 不搜索工作区根目录之外的任何目录,因此编辑器在一个指向外部目录的链接下显示的 Release 不会被列出;unread_linked_dirs 列出每个位于列举本应读取目录之处、且指向根目录之外的链接——以链接自身相对于根目录的路径表示,从不以其指向的位置表示——在两种形态和两种传输方式下皆如此,没有此类链接时为空。它也不会通过链接读取根目录之外的文件:unread_linked_files 以同样方式列出每个自身名称以 .yaml 或 .yml 结尾、且指向根目录之外文件的链接,无论该文件包含什么,因此仅能通过此类链接到达的 Release 不会被列出——除非工作区配置以 build.authoring_release 或 workspace.releases 的键指定了该 Release,此时它会在链接自身的位置被读取并列出,而不会被列为链接。list-entities 同样不读取指向工作区之外的链接背后的任何文档——它不搜索根目录之外的任何目录,也不读取根目录之外的任何文件,无论该文件声明了什么——并以同样方式在其自身的 unread_linked_dirs 和 unread_linked_files 中列出每个此类链接,在两种形态和两种传输方式下皆如此。无论文档声明了什么,这一点都成立,唯一的例外与 list-releases 相同:工作区配置以 build.authoring_release 或 workspace.releases 的键指定的 Release 会在链接自身的位置被读取并列出,而不会被列为链接;而这些设置所指定的、声明了 Release 以外内容的文件不会被列出,其链接会被列出。配置的 catalog 目录是工作区读取存放在别处的其他实体的方式,因此指向配置在 catalog_dirs 下列出的目录(或其下级目录)的链接不会被任一列举列出:配置已经到达了它。list-entities 从 catalog 目录获取的 Features 中,从不包含位于某个链接背后的 Feature——该链接指向 catalog 目录的读取必须限定其中的目录之外(对于工作区内的 catalog 目录,该目录是工作区;对于配置在工作区之外指定的 catalog 目录,则是该目录本身)——因此被列为位于未读取链接背后的实体,从不会与该名称并列出现。列举所排除的链接——因其名称、所在位置或 .gitignore 而排除——不会被列出;使用 release 时,仅由其他 Releases 读取的 catalog 目录下的链接也不会被列出;本身是指向工作区之外链接的 .gitignore 不会被读取。只要这些列表中任何一个列出了链接,文本回答的末尾就会单独用一行说明这一点。

配置文件指向工作区之外的工作区仍会被列举,但不会为它回答其他任何内容。 当工作区自身的 .aggrega-config.yaml,或其旁边由 CI 拥有的覆盖文件,是指向工作区之外的链接时,其配置不会被读取(与在终端中相同),它本应配置的任何内容也不会被替代读取。服务器仍会通过标准输入和输出启动,并在其错误流中用一行说明这一点。list-entities 和 list-releases 以工作区自身的文档作答,按无任何配置读取,因此不会列出任何 catalog 目录的 Features。两者都会在 unread_linked_files 中以及文本末尾的那一行中列出被搁置的文件,无论列举是否遇到了它——这个名称就是你判断工作区配置指向其外部的依据。发送了 release 或 catalog_dirs 的列举,以及指定该工作区的其他所有工具,都取决于未被读取的配置,因此均会以 E0321 被拒绝,并指出该链接及其指向的位置。命令行指示其监听的服务器——--transport http 或 --listen——不会在此类工作区上启动,因为它要绑定的地址、它的证书以及谁可以调用它,都由该配置决定。删除该链接,或使其指向工作区内的文件,下一次调用就会读取配置。参见工作区边界。

按单个 Release 的视角查询

工作区可以为每个 Release 指定其自己的目录(catalog)目录——参见为 Release 指定其自己的目录目录——从而让同一实体的各个变体按 Release 并存。有三个工具在其他情况下基于工作区自身的目录目录作答,它们接受一个可选的 release(某个 Release 文件的路径),此时便按该 Release 的视角作答:

  • 带 release 的 list-entities 列出该 Release 可见的实体。所列的 Features 是其目录目录所声明的那些;位于仅由其他 Releases 读取的目录目录下的工作区文档会被排除,因此每个变体只针对使用它进行构建的 Release 列出,而不针对其他 Release。完全不在任何目录目录下的文档——例如写在目录旁边的 Release、其 Aggregate 和其 Manifest——会针对每个 Release 列出。
  • 带 name 和 release 的 describe 通过该 Release 的目录目录解析名称,因此由多个变体声明的名称会解析为该 Release 构建时使用的那一个。这些目录无法解析的名称会被拒绝,并附带一段说明,指出该 Release 在 workspace.releases 下的条目。无论指定哪个 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 的合成构建中,因此,若某个 Recipe 的模板(包括其导入的文件和库条目)读取了 .context.inject、.context.uses 或 .features 下的任何内容而导致渲染停止,它会答复 valid: true,且 diagnostics 中为空;其文本带有 Render: not attempted (this Recipe reads values a build of one cannot supply)、导致搁置的读取,以及渲染停止时的那句话。决定这一点的是 Recipe 读取的内容,因此与此类读取并存的 Recipe 自身错误也会一并搁置,而无法解析的模板和被渲染拒绝的引用仍会答复 valid: false。aggrega validate 对相同输入给出相同结论。

带 entity 的 validate 会将失败的断言报告为警告,无论是否按某个 Release 的视角。 调用 fail 的断言——无论是 Recipe 自身的,还是其所实现的 Component 声明的——会答复 valid: true,且 diagnostics 中为空。合成构建以占位符和 schema 默认值代替真实 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 或治理检查是否已挂接;插件读取说明某个挂接是否到达一个能够解析、能描述自身并提供其声称能力的 guest。从这个接口的其他任何地方看,这两种情况都一样,而它们需要的后续步骤恰恰相反。

config-show 对每项设置报告一个条目:其 field、其生效的 value,以及决定它的 source——配置文件、环境变量、命令行标志或内置默认值。此外,layers 按优先级顺序(从低到高)列出起作用的各层。设置的 source 与 layers 中对应条目的写法完全相同,因此两者可以直接关联;由默认值决定的设置不指向任何层,因为默认值不是起作用的层。全局层是服务器自身命令行选定的文件——启动时 --config 指定的文件,否则为 AGGREGA_CONFIG 环境变量指定的文件,否则为默认位置——因此由该文件决定的设置归属于该文件,与 aggrega config show --origin 的归属方式完全一致;传给服务器的 --offline 之类的标志则报告为该标志。它不接受 response_format,也没有分页大小:这些设置是此二进制文件涵盖的固定集合,每次解析都会报告全部设置,因此回答的大小取决于二进制文件,而不是你的配置。

**plugin-list 以工作区列表所用的两种形式回答,未指定形式的调用得到摘要。**摘要是每组的计数,共有两组——embedded,即编译进此二进制文件的 guest,解析时无需文件系统、缓存或网络访问;以及 configured,即工作区自身的绑定。发送 response_format: detailed 可获取记录:每个插件的所属组、发现它所用的引用、该引用的绑定位置、其自报的类型、版本、提交、提供的能力、渲染的输入种类、边界程序集和导出、其就绪状态(如有),以及是否解析成功。记录受 limit 和 offset 限制,条件与实体列表相同,并通过 count、returned 和 more_remaining 继续获取。这个回答确实会随你的配置增长——内置项是固定的,绑定由你决定——这就是它分页而配置读取不分页的原因。

失败的插件会连同其失败信息一起报告,而不是从列表中删除。resolved 表示引用是否到达了模块字节,已解析但无法描述自身的插件也会如实报告——因此存在但无法使用的挂接与从未建立的挂接可以区分开来。

监听器不会告诉你的宿主信息

**通过 HTTP 时,两种读取都不报告指向服务器文件系统中某个位置的值。**启动服务器的客户端与服务器运行在同一处,因此任一回答可能指出的位置都是调用方已拥有并可以自行查看的。访问监听器的调用方并未选择这些位置,知道它们也无法据此行动,而服务器一旦向这样的调用方公开了它们,就无法撤回。在该传输方式上这些值不存在;在标准输入输出上它们全部存在。这是该接口上每个回答都遵循的规则,详见回答对服务器文件系统说了什么,而这两种读取是它涉及最广的地方,因为它们报告的大部分内容都是指向位置的配置。

**哪些内容会被保留不报。**来自 config-show:自身值为位置的设置的 value——服务或健康检查地址(可能是套接字文件);证书、私钥或密钥集文件;catalog 目录,以及 workspace.releases 下各 Release 自己的 catalog 目录(其每个条目都以 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 可以挂接到某个节点,以及某个节点可以连接到什么。两者运行的都是编译器所运行的同一套标签匹配,因此助手向你提供的是构建时会匹配到的集合,而不是从 schema 推断出的集合。

attach-candidates 报告其声明的适用性被节点标签满足的 Features。用以下三种方式中的恰好一种指定节点:

  • node——工作区实体的 metadata.name,即 list-entities 所报告的名称。匹配基于该文档声明的标签运行。
  • graph_node 加 release——已编译图上的一个节点,按图对其使用的键来指定,包括由子 aggregate 贡献的节点所带的限定形式。匹配基于该节点最终确定的标签运行,也就是构建时求值的那些标签。
  • labels——单独的一个标签集,不指定任何节点。它完全不需要坐标,因此如果你已经持有某个节点的标签,就应使用这种形式;它不查找任何东西,也不重建任何图。

答案会带上匹配所基于的标签,以及这些标签来自上述三个集合中的哪一个,因此你可以直接根据答案本身解释任何候选项——或候选项的缺失——而不必重新推算。用另一种方式重新读取标签,正是你对节点标签的理解与编译器的理解出现分歧的原因。

要询问节点所画出的某条连接可以挂接什么,请在 graph_node 和 release 旁添加 connection——即作者所写的其 socket 和 alias。一条连接携带的挂接会填充其 socket 在消费方 Component 上声明的槽位,因此答案还会带上 slots:该 socket 声明的每个槽位,包括与 Component 声明完全一致的 selector、required、inject、sensitive 和 description,以及可以填充它的 candidates。这些是其适用性被节点标签满足,并且其自身标签被该槽位选择器接受的 Features——这是构建对此类挂接所要求的两条规则——因此一个槽位的候选项始终在该节点自身的候选项之内。在没有任何可填充之处时,slots 为空,noSlotReason 说明原因:feature-created-connection(连接由某个 Feature 画出,而此类连接上不挂接任何东西)、ad-hoc-socket(该 socket 不是 Component 声明的)或 no-slot-declared(该 socket 未声明任何槽位)。不要把空的 slots 理解为“没有匹配项”;该原因正是为了排除这种理解,而只要存在槽位,它就不会出现。旁边的 candidates 保持其含义——可以挂接到节点本身的内容——而如果你发送了 document,在这里不会改变任何东西。connection 与 node 或 labels 一起使用,或未指定 socket 或 alias,都会被拒绝;节点没有画出的连接同样会被拒绝。这些答案与语言服务器给出的相同,条件也相同。

connection-candidates 报告一个实体声明的依赖 socket,并针对每个 socket 报告其声明标签满足该 socket 对其目标所声明约束的工作区 Components。它在 node 中接收实体的 metadata.name。与 attach-candidates 不同,它没有不带坐标的形式:这里没有标签集形态,因为 socket 是从所指定实体自身的声明中读取的。

**它的两部分完整程度不同,答案会说明哪部分是哪种——不要把它们作为一个列表呈现。**目标是完整的:它们是构建期间同一约束所接受的 components。socket 则不完整,也不可能完整。消费方可以自创连接,但只能消费生产方声明的内容,因此作者可以合法地写出目录实体从未声明过的 socket,已声明的 socket 只是一个有用的起点,而不是合法名称的集合。因此每个 socket 都会说明它是 declared 还是 ad-hoc,答案也会说明该实体是否接受未声明的 socket——Component 自身的依赖面接受,因为作者拥有其应用的拓扑;Feature 的挂接面不接受,因为挂接参与的是被挂接 Feature 所声明的拓扑,而不是自行编写拓扑。这种开放性源于你的编写自由,而不是缺陷:传入带有实体未声明名称的 socket 即可询问它。

两者都只回答然后停止。两者都不会创建挂接、创建边、写入任何文件,也不会提议相应的文本;随后的任何编辑由你来编写和应用。

两者返回的都是此处其他所有答案所用的同一最小标识——kind、名称和源文件——仅此而已。你想显示的关于实体的其他所有内容,都已经在 list-entities 中以这三个字段对应给出,因此你应将两个答案关联起来,而不是读取两份可能不一致的副本。两者都会拒绝无法解析的名称,而不是以空列表回答,原因与此接口其余部分相同:空答案会把拼写错误报告为一个没有可提供内容的对象。labels 调用没有可拼错的名称,因此那里的空结果就表示字面意思。

服务器读取以供参考的所有内容都由本机提供——JSON Schema 内置于二进制文件中,文档则从本机保留的文档包缓存中读取,如下所述。起草初始文档、验证、描述、构建和 lint 都基于你的工作区和本地缓存运行,它们都不会自行访问 registry:渲染从内容寻址存储中提供已固定的外部引用,并拒绝未固定的引用而不去获取它,这正是让整个检查与渲染循环保持离线的原因。你可以请求两种 registry 读取:给定 registry 引用的 describe,它只获取该坐标,不写入任何内容,并且在 HTTP 上只访问所服务工作区已配置的 registry;以及发送了 example 或 list 的 scaffold,当本机没有工作区签名策略所接受的副本时,它会从工作区的默认 registry 获取文档包,并在保留之前进行验证,与 aggrega scaffold --example 的做法相同。发布和签名是与此相对的、有意为之的另一面,已在上文介绍。

介于两者之间的是解析 Release 的依赖,这是此处唯一会获取内容的操作:它会访问 registry,因为被要求解析依赖就是被要求获取依赖。它只在你请求时发生,而且请求方式恰好有两种——调用 pull(这正是它的全部职责),或向 build 发送 auto_pull,后者会把同样的解析作为构建的第一步执行。除此之外,没有任何东西会代你拉取,而未发送 auto_pull 的构建不会访问任何 registry。唯一改变这一点的设置是工作区自身的 auto_pull:如此配置的工作区会要求其中的每次构建先进行解析,无论该构建从何处运行,下文会对此进行介绍。

这些参考读取中唯一的例外是获取文档包本身,而它发生在所有读取之外。文档包在每台机器上只保留一份,位于每个 Aggrega 项目共享的缓存中,每个 registry 和版本各一份副本——因此即使服务器在无法创建工作区缓存的文件夹中启动,也照样保留它(参见 aggrega cache)。服务器启动时,在回答你发送的任何内容之前,会在那里查找一份能通过你工作区自身签名检查的副本——与拉取文档包时所遵循的检查相同——只有在没有这样的副本时,才会通过 CLI 其余部分所用的同一出站设置拉取文档包。它查找的文档包是为服务器所运行的 aggrega 版本发布的那个;若没有为该版本发布的文档包,则是为更早版本发布的最新文档包——与 aggrega explain 和 aggrega scaffold --example 的选择相同——而它提供的每个页面和每条解释,都读取自它所获得的那一份。因此,无论你的客户端先发送什么,在任何请求要求页面时页面都已就位,而另一个服务器或另一个项目中的 aggrega explain 会找到同一份副本,而不是再次下载。

此后提供页面就是读取该副本,不会访问任何 registry。提供页面之前,会按你的工作区的检查再次验证保存在副本旁的签名,因此另一个项目较宽松的设置所放入的副本不会提供给你:检查固定了密钥或信任根时,验证离线进行;两者都未固定时(官方 hub 的内置检查即属此类),它会像 pull 一样获取公共 Sigstore 信任根。离线工作区无法获取该信任根,因此离线时会依据本机此前一次在线获取留在缓存中的信任根进行验证,该缓存由 Sigstore 客户端保存在你主目录下的 .sigstore 中,无论那次获取距今多久,且不获取任何内容;在从未获取过信任根的机器上,检查无法离线运行,副本不会被提供,日志流会说明这一点。服务器运行期间,该验证对每个副本和每种检查各运行一次,之后读取的页面依据它所接纳的结果提供:此后获取的副本、检查不同的工作区(包括原地编辑了固定信任根的情况)、离线进行的读取,或离线读取发现机器上留有不同的信任根,都会单独验证。被你的检查拒绝的副本会在下一次读取时再次检查,因此此后已接纳它的一次获取不会被推翻。如果无法获取文档包,或者唯一的副本被你的检查拒绝且在该检查下重新获取失败,服务器仍会启动,其他所有功能照常工作;文档请求返回未找到,服务器的日志流会说明原因。

基于 Release 已固定的内容进行构建

build 在内存中将一个 Release 渲染为其制品,而渲染可能会请求来自远程 URL 的内容——例如带有远程引用的 chart 值 schema。外部输入在本次调用中被冻结。 Release 的 lockfile 已固定的引用由内容寻址存储提供,这是读取磁盘上已有的内容,而不是拉取。lockfile 未固定的引用会被拒绝并指名,而不会被拉取:你请求的是一次渲染,而获取引用既会访问网络,又会作为生成字节的副作用向存储写入一个 blob。这种冻结是渲染的属性。解析才是进行获取的步骤:它渲染该 Release,以找出该渲染请求了哪些远程引用,拉取它们,并将其记录在承载依赖固定项的同一次 lockfile 写入中。因此,解析改变的是渲染运行时哪些引用已被固定,而绝不是渲染可以访问什么——没有任何解析固定过的引用,在先进行了解析的调用中被拒绝的方式,与在未解析的调用中完全相同。

返回的文件就是真实构建所输出的字节,这一点由两件事共同保证。 其一是上述冻结:已固定的引用从存储中读取,而不是拉取。其二是所读取的 lockfile 仍然描述该 Release 解析到的内容——因此 build 会检查这一点,并拒绝不再匹配的 lockfile,与在终端中运行 aggrega build 完全一样。仅读取已固定的字节,本身并不能说明读取的是否是正确的字节。

lockfile 的全部三种状态,使行为一目了然。 完全没有 lockfile 时,build 基于工作区已固定的任何内容进行渲染,并拒绝其无法提供的每个外部引用,逐一指名;在不加干预的情况下,它既不要求 lockfile,也不写入 lockfile,上述检查也不改变这一点——没有可供比较的 lockfile,因此不会拒绝任何内容。lockfile 匹配时,它进行渲染。lockfile 不再匹配时,它拒绝,并在拒绝中说明如何解决:使用相同的 release 且不带 upgrade_targets 调用 pull,这会将 lockfile 与该 Release 当前解析到的内容进行协调。拒绝中还附带同一操作的终端形式 aggrega pull --release <release>。两种调用方式都能解决它;它们是从两个地方可达的同一个操作,而不是需要二选一的两条指令。如果 pull 完成后拒绝仍然返回,说明两次调用基于不同的输入进行了解析——最常见的是只给其中一次提供了 catalog_dirs,或在两次调用之间编辑了工作区配置——拒绝会说明这一点:请用相同的输入调用两者。

仅传入 release 的 validate 和 describe 同样受该 lockfile 约束。 如果 lockfile 已不再与该 Release 解析到的内容匹配,二者都会拒绝而不作答,其文本带有 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 的代价是一次解析,而不是第二次渲染。只有已完成的渲染才会被这样使用:如果解析固定了其依赖,但未能完成对外部引用的发现,构建会基于已落定的固定项自行渲染,此时未固定的引用会指名使其停止,而不是返回一个达不到构建应输出内容的文件列表。

返回内容会说明解析了什么。 进行了填充的构建会在其应答中带有 dependency_resolution,其形式与 pull 的应答相同:它写入的 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,完成的渲染结果还会被写入工作区根目录下的 dist/,即 aggrega build 写入的位置。 该目录就是命令行在同一工作区根目录下组合出的目录,写入操作也与命令行执行的相同,因此对于同一工作区中的同一个 Release,aggrega build、未指定 outputParent 的语言服务器 aggrega/build 以及本调用写出的是同一棵目录树,逐字节一致,并以相同方式指明该目录——命令的最后一行、语言服务器的 outputDirectory 以及本应答的 output_dir。若 dist 是指向工作区之外的链接,则在删除或写入其中任何内容之前就会被拒绝,与在终端中一样。省略时(即默认情况),制品在内存中返回,不写入任何内容。

工作区根目录由调用自身决定。 通过标准输入输出时,它是该调用所解析的工作区的根目录,如调用在哪个工作区中得到应答所述:即 workspace_root 指定的根目录,否则为服务器启动时指定的根目录,否则为从服务器启动所在目录找到的工作区——并且,若以绝对路径指定的 Release 将调用移入该 Release 自己的工作区,则为那个工作区的根目录。它就是 aggrega build 针对同一 Release 和同一指定根目录所写入的根目录,因此只有当服务器恰好运行所在的文件夹正是调用所解析的根目录时,该文件夹才会得到一个 dist,就像在该文件夹中打开的终端一样。通过 HTTP 时,它是服务器所服务的工作区,不会在其外部写入任何内容。

写入会触及工作区,因此通过 HTTP 时需要 aggrega:workspace-write。 发送了 write 的调用会为该调用触及工作区,与先解析依赖的构建完全相同:仅携带 aggrega:read 的凭据会得到指明 aggrega:workspace-write 的 403 应答,且不写入任何内容;而 mcp.deny_reach 包含 workspace 的服务器会拒绝该调用,并指明该设置。该工具仍保留在每个调用方的工具列表中,未发送 write 的构建对只读范围的调用方仍然可用。

写入在最后进行。 同时使用 auto_pull 时,调用依次进行解析、渲染,然后写入。在任何更早阶段被拒绝的调用——其 Release、其工作区、某个目录(catalog directory)、解析、渲染——都不会写入任何制品。

应答会指明写入了什么。 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 渲染期间引发的拒绝使用编译器的原话,如下文渲染期间引发的拒绝所述,并额外添加一个自己的字段。其中包含 advisories:已运行的阶段引发了它们所引发的内容,而这些正是你要越过该拒绝必须处理的发现,因此它们以可供匹配的条目返回,而不是需要你解析的文字。deprecations 和 declined_external_inputs 也出于同样的原因包含在内——记录了弃用标记,就报告该标记;拒绝了某个引用,就报告该引用,这两个事实都不取决于运行如何结束。

**files 在拒绝时不报告任何内容,它也不是用来读取结果的字段。**没有产出任何内容,因此没有可列出的产物。不要根据该键是否存在来做分支判断:无论哪种情况它都会被报告,而空的 files 本身无法区分被拒绝的构建与运行后未产出任何内容的构建。请读取结果上的失败标记——这是协议自身的判别依据——并按其本义读取 files:已渲染内容的列表,在调用传入了 write 时也是已写入内容的列表。

**拒绝时 advisories 的范围取决于运行进行到了哪一步,而不是答复能够承载什么。**在 Release 解析之前运行的检查所引发的拒绝——缓存中某个固定的条目不再与为其记录的摘要匹配,且没有任何目录目录保存这些固定的字节,或者 Release 所依赖的内容无法解析——不报告任何 advisories,因为此时尚未引发任何内容。关于一个 Release 如何与其所扩展的 Release 组合的发现,在其解析的那一刻引发,早于随后的每一项检查,因此之后的每一次拒绝都带有它们:Manifest 将某个类型映射到未实现该类型的 recipe,Release 所触及的某个实体不满足其 schema,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,会以失败返回:其文本带有渲染的拒绝,其载荷带有未读参数的 advisory 及其 severity、message、code 和 key_path——与同一 Release 在渲染完成时在答复中报告的条目相同,值也相同——旁边是关于渲染因何停止的 refusal 条目。一个扩展另一个 Release、继承了不含任何模板变量的边界目录、且其 Manifest 将某个类型映射到未实现该类型的 recipe 的 Release,会以该拒绝返回,每个继承的目录对应一个 advisories 条目,每个条目的 code 为 inherited-boundary-directory-is-literal。一个依赖无法解析的 Release,在其列出的目录目录全部存在的工作区中,会以失败返回,且完全没有 advisories 键,因为在它停止时尚未引发任何内容。

渲染期间引发的拒绝

编译器在渲染时拒绝的 Release——某个 Workload 指定了其 Component 未声明的插槽、某个断言失败、某个模板无法求值——返回时会以编译器的原话给出该拒绝,并附上其下的每一个原因,即 cli-build 对同一 Release 返回的文字:先是正在渲染的节点,然后是其中拒绝的内容。当拒绝指向某个已注册的条件时,文本会像 explain-error 那样补充该条件的名称——可供匹配的短代码和描述性代码。文本开头说明是哪个阶段拒绝的:渲染引发的拒绝为 The build failed during rendering; nothing was written to disk.,编译器运行在任何内容渲染之前引发的拒绝为 The build refused before rendering anything; nothing was written to disk.——即渲染所依据的图的组合发生拒绝,或 Component 或 Feature 声明的某个断言失败。

载荷以一个条目 refusal 携带同一拒绝,因此需要修改文档的调用方无需解析句子即可读出是哪个文档、在何处:

  • file——拒绝所指向的文档: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。成功的构建不带该条目;在编译器启动之前运行的检查(lockfile、Manifest 的映射、Release 的依赖)所拒绝的构建也不带,其拒绝只有文本。作者声明为敏感的值会在编译器引发拒绝时从中隐去,因此该条目和文本所携带的内容与 cli-build 和终端所携带的一致——参见拒绝对已声明的值会说明什么。

解析一个 Release 的依赖

pull 将一个 Release 的目录依赖和源依赖解析到本地缓存中,并写入该 Release 的 lockfile。它出现在这一接口上有一个值得说明的理由:上面的两种拒绝——渲染拒绝了未固定的外部引用,以及构建因 lockfile 与该 Release 解析结果不再一致而停止——都通过固定版本来解决,而一个必须请你运行命令的助手无法自行解决它们。关于它写入什么以及影响范围,请阅读助手无需先询问你即可做什么。

传入 release,即 Release 路径,可以是绝对路径,也可以是相对于工作区根目录的路径——与这里其他所有路径参数遵循相同的约定。workspace_root 和 catalog_dirs 覆盖工作区和目录的发现,方式与在 build 上完全相同。这两者在通过标准输入输出访问的服务器上都有效;通过 HTTPS 时这两个参数会被拒绝,且路径必须解析到该进程所服务的工作区之内,详见一个进程,一个工作区。

默认情况下,它执行协调而不是重新解析。 lockfile 中已记录的固定版本会被遵循并按该版本获取;如果注册表不再提供这些字节,则予以拒绝,而不是静默地重新固定。没有固定版本的引用——新添加的,或被手动从 lockfile 中删除的——会被重新解析并添加。不再属于已解析依赖的引用会被删除。因此,依赖集未变化时,文件保持逐字节相同,包括其中记录的时间戳,这样未改变任何固定版本的调用不会给之后审阅该工作区的人带来任何差异。

verify 只做比较,不改动 lockfile。 它将已记录的 lockfile 与上述协调调用此刻会执行的解析进行比较,并像该调用一样严格遵循已记录的固定版本;出现偏差,或没有可比较的 lockfile 时,以失败返回——因此助手可借此在任何内容重写 lockfile 之前判断是否需要固定版本。该调用会记录的内容一概不写入——不写 lockfile,不写记录在其旁的插件身份,也不写 entity.lock——而内容缓存的读取和填充与该调用完全相同。它还会报告 lockfile 记录的工具链:写入该文件的编译器版本,以及该编译器附带的每个核心插件的版本。这仅用于审计,从不与正在运行的二进制文件比较,因为工具链不属于 lockfile 固定的内容,检查它等于间接固定了编译器——工具链的差异不算偏差。

upgrade_targets 只重新解析你指定的引用。 给它一个或多个以原始编写形式书写的实体 URI——写 core/database,而不是带版本的形式。每个被指定的固定版本会被丢弃,并重新解析到可用的最高版本,而其他所有固定版本和已记录的外部输入保持不变。既不匹配已记录的固定版本、也不匹配已配置附件的 URI 会被拒绝,而不是被忽略。

这里有意不提供一次性重新解析全部内容的参数。 命令行有这种形式,它会丢弃整个 lockfile,再根据注册表的当前状态重新解析。在这一接口上该参数不存在,因此这样的调用根本无法构造,而不是先被接受再被拒绝:没有人在盯着协议流,整体丢弃也就无人确认。需要这样做时,仅在标准输入输出上,可由 cli-pull 运行该命令,那是有人在场的接口;通过 HTTP 访问该服务器的调用方则改为在主机的终端上运行它。verify 不能与 upgrade_targets 组合——一个保持 lockfile 不变,另一个重写它——也不能与 pin_sources 组合,无论后者取何值:该参数决定解析是记录 entity.lock 缺失的固定版本还是因此拒绝,而比较不写入 entity.lock,所以两者都不会发生。发送其中任一组合的调用会在解析任何内容之前被拒绝,并附一句指明该组合的说明。该工具公布的 schema 没有声明这两项互斥,因为渲染 schema 的客户端可能把它理解为必须发送 verify;客户端通过拒绝信息了解这些限制。命令行和守护进程拒绝相同的组合。

结果会指明解析了什么,而不只是说明有内容被解析。 它包含所写入或用于比较的 lockfile;resolved,即解析涉及的每个引用及其解析到的版本、在解析记录了种类时作者所写的种类,以及其 source——本次运行从何处获取该引用,用词与 aggrega pull --detail 对同一解析打印的一致:fetched-fresh、cache-reuse、local、in-binary 或 external;lockfile 此后所含的源制品、外部输入和受信任插件身份的数量;以及 diagnostics,即解析对自身的记录,按各行产生的顺序排列——复用了哪个固定版本、检查了哪个签名、哪个版本因已撤回而被跳过。运行命令时这些行会输出到终端;在这里它们出现在应答中,因为不读取终端的调用方没有其他途径接收它们。verified 仅在比较时出现,因此根据它是否存在可以区分写入的运行与仅做比较的运行。source 描述的是本机上的本次运行,因此 lockfile 不记录它,而报告 Release 依赖内容的 describe 也不列出它。

拒绝使用相同的字段作答,按运行进行到的程度填充。 一旦解析已计算完成,无论结论如何都会带上 resolved——偏差结论尤其如此,因为调用方正需要据此决定要修改什么。在此之前发生的拒绝,例如无法解析的 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 的锁文件中。

结果说明该步骤对锁文件做了什么。 它包含 entity、其 kind 和 name,以及 pinnable:对于不读取任何锁文件所记录内容的类型(一个 Component 或一个 Feature),该字段为 false,此时实体旁的任何内容都未被改动,其他字段也不出现。否则,它包含所写入的 lock;changed,当锁文件已记录所有固定项并保持字节完全相同时为 false;removed,出现在实体现在不再读取任何锁文件所记录的内容、其锁文件已被删除的情况下;以及 pins,每类固定项一个条目,附带锁文件此后持有的数量。dry_run 以 content 返回该步骤将要写入的锁文件,且不在实体旁写入任何内容;内容缓存仍会被填充,因为输入的解析方式与其他情况完全相同。

它在工作区内写入,并访问实体的源所指定的主机——chart 仓库、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,或因为工作区自身的设置要求其中每次构建都先解析——因为报告属于该步骤:基于已持有的固定版本进行渲染的构建不会到达任何报告点,也不报告任何内容,因此该调用上的令牌不会改变其应答方式。任何调用还会报告其工作进入并等待的每个步骤——读取 registry、获取制品或文档包、首次编译插件——也就是命令行在其进度指示器旁向用户显示的那些步骤。工作不等待其中任何步骤的调用不报告任何内容,这是无害的,而不是错误:应答与没有令牌时你会收到的相同。

查询文档中某个位置上写的是哪条连接

connection-at-position 回答的是在上述两个工具的连接部分之前的问题,适用于你手中持有的是文档中的一个位置而不是图上的一个节点的情形——例如你正在查看的 Aggregate 或 Release 中的某一行。传入 file,即该文档,可以相对于工作区根目录,也可以是绝对路径,并按照 insertion-point 读取文档的方式从磁盘读取;传入 position,即一个 line 和一个 character,两者都从零开始计数,其单位由 position_encoding 指定,与 insertion-point 读取该参数的方式完全相同;再传入 release,其编译后的图记录了这些连接。即使位置在 Aggregate 中,也必须提供 Release:图节点和连接只存在于编译后的图上。

答案是两种情形之一。如果该位置位于某条连接的条目上,答案携带 graphNode 和 connection——包括其 socket、其 alias 以及读取该位置所在的 document——它们正是 attach-candidates 在 graph_node 和 release 之外所接受的参数,也是 attachment-container 用来指明该连接上的附件应放在何处的参数;该容器就位于该位置所在的那个条目之内。否则,答案携带 noConnectionReason,取值来自一个封闭集合:no-connection-entry(该位置不在任何用于编写附件的条目上)、feature-created-connection(该位置位于 Release 中为某个 Feature 所建立的连接编写的条目上)或 unknown-connection(该位置位于 Release 为编译后的图中不存在的连接编写的条目上)。可读的答案会用文字说明原因。

条目内的任何位置都算在该条目之内——无论是在别名上、在其 target 上,还是在其 features 之内——条目嵌套时,最内层的条目优先。位于某个 socket 自身键上、在其下各别名之上的位置,不属于其中任何一个条目。这些条目就是编译后的图所记录的条目:在 Aggregate 中,是每个组件建立的每条连接,位于编写该组件的文档中该连接别名下的条目处;对于由导入模块贡献的组件,该文档就是该模块自身的文档;在 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,其键为 ledger,与顶层 component 完全相同。请查询容器。

答案包含 node,即所涉及的节点;file,即该节点编写所在的文档;以及 container,即从该文档根开始的结构路径,以段列表表示:["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]。它有意采用列表而非拼接后的字符串:拼接后的路径需要接收方再次拆分,这等于在下一次调用中重新引入上述歧义。将 file 和 container 原样传给 insertion-point。

file 是答案的一部分,而不是你事先已知的内容。由导入模块提供的节点,是在该模块自己的文档中以模块赋予的名称编写的,因此文件和容器的最后一段都与你发送的任何内容不同。

对于节点所建立的某一条连接上的附加项,请添加 connection,并给出其 socket、alias 和 document;这里必须给出所属文档,因为两个文档都可能包含该连接。使用 aggregate 时,答案是该连接在节点编写所在文档中的自有条目,最后一段为其 features 块;由 Release 建立的连接在那里没有条目,会被拒绝。使用 release 时,答案是该 Release 中节点条目下的逐边条目——["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"]——无论该 Release 是否已写出这个逐边条目都会报告,这样 insertion-point 会列出仍需写入的键;没有为该节点写出条目的 Release 会被拒绝,因为节点放在何处不由此工具决定。由 Feature 建立的连接在任一文档中都会被拒绝。

**它只作答,然后停止。**它不创建附加项,不写入任何文件,也不组织任何文本。它也不裁定可以附加什么,那是 attach-candidates 的职责。图中不包含的节点,或图中未记录其文档的节点,会以失败结果返回并指出需要修改的内容,而不是返回一个字段为空的答案。

定位条目在文档中的位置

insertion-point 回答的是候选答案之后的问题。你已经确定了要附加或连接什么;现在需要知道在文件中的哪个位置写入它。它返回一个位置以及缩进所用的列数,因此你无需自行解析文档即可应用编辑。由于它读取的是文档自身的结构,而不是某一种类的形状,describe-capabilities 会在你所限定的任何实体种类下列出它。

传入 file——即该文档,可以相对于工作区根目录,也可以是绝对路径,且必须位于工作区内:通过指向工作区外部的链接(无论链接指向该文件还是途经的某个目录)到达的文档不算在工作区内,在任一传输方式下都会被拒绝——以及 container,即从文档根到条目所在容器的结构路径,其中每个元素是一个映射键或一个以十进制书写的序列位置。

容器路径由你提供。 该工具读取文档的结构,从不根据某个东西的名称、它携带的类型或它看起来的含义来推断它应该放在哪里。你指定哪个键;它告诉你该键的条目在这个文档中放在哪里——文件已包含路径中的哪些段、其条目所在的列,以及其最内层块到达的最后一行。对于已编译图中某个节点上的 Feature 附加,你无需自己知道那个键:上文的 attachment-container 会报告文档和容器,两者原样传入此处即可。

答案包括一个零宽度的 position,其 line 和 character 均从零开始计数;entryIndent 和 indentStep,即写入所用的列数;以及 missingContainerKeys,即该文档尚未包含的容器键,按从外到内排列,你需要在条目之前写入它们。entryShape 报告容器包含的是 mapping 还是 sequence,在容器尚不存在或为空时报告 unknown,因为文档尚未表明——此时形状由你选择。indentStepMeasured 说明缩进步长是根据该文档自身的嵌套测得的,还是针对没有任何嵌套的文档所用的回退值。设置了 precededByLineBreak 时,你的文本应以换行开头:该位置位于条目所跟随行的末尾,无论文件是否以换行结尾,该位置都在有效范围内,且不会改动任何已写入的字节。即使你认为容器已经存在,也要读取 missingContainerKeys——在缺少必须位于其前面的键的情况下应用某个位置,会生成一个无法再解析的文档。

position_encoding 指定所报告的字符偏移量的度量单位:utf-8、utf-16 或 utf-32。它之所以在这里作为参数,是因为该协议的两个修订版本都不协商编码;其默认值为 utf-16,即客户端未协商任何编码时编辑器会话所采用的编码——因此未指定编码的调用方在两个接口上得到相同的答案。不属于这三者的值会被拒绝,而不是悄悄使用默认值,因为以一种方式度量的偏移量应用到以另一种方式度量的缓冲区时,会在第一个非 ASCII 字符处损坏文档。

它只回答,然后停止。 它不向任何文件写入内容,不编写条目文本,也不应用编辑;编写文本以及决定是否应用它都由你负责。未指向条目可放置之处的请求会作为失败结果返回,并指明需要更改的内容——文档不在工作区内、无法读取或不是格式正确的 YAML;容器路径不含任何段或包含空段;路径经过一个标量,而标量内无法追加任何内容;路径到达一个以流式风格书写的集合,在其中追加会重写作者已写入的字节而不是添加一行;或者路径以非索引的内容访问一个块序列。如果你希望由工具应用编辑而不是自己应用,对文档应用一次有界编辑就是执行此操作的工具。

对文档应用一次有界编辑

edit-document 应用上面两个工具所定位的内容。一次调用在一个容器下添加一个条目,或设置一个标量,除此之外什么也做不了。它会写入你指定的、位于工作区内的文档,因此通过 HTTPS 调用时需要 aggrega:workspace-write:只持有 aggrega:read 的调用方能在工具列表中看到它,但其发起的调用会被拒绝,并指明所需的该作用域。

在 edit 中指定编辑类型,且可选集合是封闭的。 add-component 在一个 components 容器下添加一个组件实例;attach-feature 将一个 Feature 附加到你指定的节点上;wire-edge 在该节点的某个 socket 内连接一条连接;set-value 在该节点上设置一个值。这四个之外的名称会被拒绝,而不会被解释。不存在删除、替换你已写好的块、重新排序任何内容或逐字写入你提供的字节的编辑——因此这不是文件写入器,也无法当作文件写入器使用。

传入 file,即文档——相对于工作区根目录或为绝对路径,且位于工作区内:位于工作区之外的文档,无论是直接写明的,还是通过指向工作区外的链接到达的,在两种传输方式下都会被拒绝,且不读取或写入任何内容;node,从文档根开始、以片段列表表示的结构路径;name,条目写入时所用的键;以及 value,该条目承载的内容。node 是列表,原因与 attachment-container 以列表作答相同:作者输入的名称中可以合法地包含点号,因此拼接起来的路径可能指向一个没人写过的键,条目便会在那里被创建而不是被拒绝。对于 add-component,路径指向 components 容器本身,因为被添加的条目就是节点;对于其他三种编辑,路径指向该编辑所涉及的节点,容器由编辑类型决定。socket 仅在 wire-edge 时读取,其他情况下忽略。value 的含义由 edit 决定——条目所请求的实体、连接所指向的节点,或某个值被设置成的标量——它是一个保留自身类型的 JSON 值,因此数字仍是数字,带引号的数字仍是文本,省略它则什么也不设置。映射或序列会被拒绝,因为写入块不属于这些编辑。

编辑未触及的每个字节都会保留。 解析文档只是为了定位容器及其块结束的行,因此注释、空行、引号风格、折叠与字面标量以及末尾换行的形态都会原样保留,缩进步长也是根据文档自身的缩进测得,而非强加。对同一文档发出相同请求会产生相同的字节。

结果必须是你本可以手写出来的文档,写入正是以此为准入条件。 组合后的文档会根据其自身类型的 schema 进行检查,只有通过检查才会写入磁盘。会产生 schema 所拒绝内容的请求会被拒绝,并指明 schema 不接受的属性及其位置,且文件逐字节保持原样——因此被拒绝的编辑与从未尝试过的编辑无法区分,你可以针对最初的文档重试修正后的请求。已存在且内容与请求相同的条目不做任何操作;同名但内容不同的条目会被拒绝,而不会被替换。

答复包含 container,即条目所落入的结构路径;created_containers,即本次编辑不得不新建的容器层级,由外到内排列,在整条路径都已存在的通常情况下为空;以及 written,即写入磁盘的文档,未写入任何内容时为空。请读取 created_containers:否则,一次悄悄写入了文档原本没有的两层嵌套块的编辑,与一次只在你自己写的块中添加单个条目的编辑无法区分。

dry_run 执行除写入之外的一切。 编辑后的文档以 content 返回,不创建任何内容,written 为空——适用于在保存前将结果呈现给作者的客户端。其他所有行为都与写入相同,包括 schema 检查,因此写入时会被拒绝的请求在此模式下也会被拒绝。不使用它时,文档会被写入且 content 不存在,因为此时文档已在磁盘上,由 written 指明。

你所连接的内容在语义上是否可接受——某个 socket 是否为生产方所声明的,或某个 Feature 的适用条件是否满足——不在这里判定。这由 validate 回答。

在标准输入输出上,同一能力也可以通过 cli-edit-document 使用,它运行该命令并返回其打印的文本;通过 HTTP 时该工具不存在,那里就通过本工具使用该能力。

将外部描述转换为草稿实体

import 将另一工具生成的描述(例如从智能体构建器导出的流程)转换为 Aggrega 编写文件的草稿。它把这些文件写入本服务器所服务的工作区,因此通过 HTTPS 调用时需要 aggrega:workspace-write:仅持有 aggrega:read 的调用方能在工具列表中看到它,但其调用会被拒绝,并指明该作用域。

传入 source,即要转换的文件或目录。它可以是绝对路径,也可以是相对于工作区根目录的路径,与此接口上其他所有路径参数遵循同一约定;在通过 HTTPS 访问的服务器上,它在该服务器所服务的工作区内解析。

目录只会读取其导入器的文件模式所选中的那些文件。 chart 或项目是一个目录,source 可以指向目录。此时导入器会收到该目录中(任意深度)被其签名所声明的某个文件模式选中的文件,每个文件以其在目录内、使用正斜杠书写的路径命名,并按排序顺序排列;同时还会收到其 plugins.importer 附件在 with.sources 下指定的文件,以其基本名命名;目录中的文件与 with.sources 中的文件同名时会被拒绝,而不是让其中一个遮蔽另一个。未声明任何文件模式的导入器只读取单个文件并拒绝目录,对应条件为 An importer that declares no file patterns is handed a directory(向未声明文件模式的导入器传入了目录);不包含任何被其模式选中文件的目录同样会被拒绝。无论目录位于何处,读取都限定在目录自身之内:导入将读取的文件中,若有指向目录外的链接,或指向某个目录且通向目录外的链接,会在读取任何内容之前被拒绝;指向目录的链接永远不会被进入——详见 A directory you import。在通过 HTTPS 访问的服务器上,目录本身在工作区内解析,因此从中读取的每个文件也都在工作区内。

导入器是你的工作区目录中的某个导入器,或编译器的某个核心导入器。 转换工作由声明支持该源格式的导入器插件完成:它要么是你的工作区目录中的导入器,要么是编译器的某个核心导入器,后者无需目录条目即可在每个工作区中服务其格式。本工具负责选择并运行它,并写入其产出。如果某个 plugins.importer 附件的 uri 以标识和版本指定一个导入器——即 importer/<name>:<version>,与 aggrega plugin add importer 写入的形式相同——则附加该导入器:只要它声明支持源格式,运行的就是它,且为该版本,无论是否还有其他导入器声明支持该格式;它会收到该附件的 with 源和设置,其他导入器则不会。当多个导入器声明支持该格式且其中没有任何一个被单独附加时——例如一个核心导入器与你的目录中另一名称、同一格式的导入器——调用会被拒绝并列出它们,详见 Configuration。你指定的格式若没有任何导入器声明支持,会被拒绝,并指明导入器需要声明的能力——对于 Langflow 源为 import:langflow——这正是你添加到目录中的导入器所声明的内容,而不是一个需要你自行解读的笼统未命中。

服务器所在机器上没有的核心导入器,会由第一次需要它的导入获取一次。 导入从所服务工作区的默认注册表获取它,将其与编译器的 release 所发布的模块核对,按照该注册表的信任策略验证其签名及其使用的宿主函数(与 pull 验证其获取的插件的方式相同),并将其保存在工作区的内容缓存中,之后的每次导入都从缓存读取,不再访问任何注册表。除此之外不会为它写入任何内容——没有 lockfile,也没有受信任插件的记录。通过 HTTPS 时,这是对此工具的调用唯一能让服务器联系的注册表,并受 Which credentials a call spends(调用使用哪些凭据) 为注册表读取所设的限制:该注册表是此服务器所服务工作区的默认注册表,因此是该工作区已配置的注册表;调用中没有任何内容指定注册表或携带凭据;获取使用的是此主机自身的登录信息和信任策略。该工具仍然只触及工作区,不涉及更多,因此调用只需要 aggrega:workspace-write:获取留下的只是工作区自身内容缓存中的一个模块。未通过验证的模块会像在终端中一样被拒绝,且不保留任何内容。若无法获取该模块——工作区处于离线状态、其注册表无法访问,或注册表中没有该模块——调用会以 A plugin’s .wasm is not on this machine(插件的 .wasm 文件不在此机器上) 被拒绝,并指明该导入器、其版本以及如何将其模块放到此机器上。

当工作区未指定目录文件夹时,导入会读取其默认注册表发布的目录。 如果工作区的 workspace.catalog_dirs、AGGREGA_CATALOG_DIRS 和根目录都没有指定目录文件夹,它会将标准库目录作为一个签名快照读取,该快照位于所服务工作区默认注册表上的 catalog/snapshot——与获取核心导入器的注册表相同,以相同的条件访问,调用中没有任何内容指定注册表或携带凭据。快照只获取一次:其签名按照该注册表的信任策略进行验证,然后保存在工作区的内容缓存中,并作为目录文件夹在那里读取,与其摘要绑定,不会再向任何注册表请求它。调用读取哪个快照:使用 upgrade 时,读取最新的快照;否则读取输出目录中的记录所指定的快照,若本机没有则按其摘要获取;否则读取工作区上一次作为最新快照获取的那个;否则读取最新的快照。导入写入的记录会按摘要指明它读取的快照,因此之后向同一输出目录起草的调用会读取同一份目录。离线时,需要获取快照的调用会被拒绝,并指明要运行什么;无论本机保存了什么,upgrade 都会被拒绝,因为只有注册表才能说明哪个快照是最新的。不发布任何快照的注册表会使导入没有目录可用,diagnostics 中的一个 warn 条目会说明这一点。指定了目录文件夹的工作区会针对该文件夹导入,不获取任何快照,upgrade 在那里不会改变任何内容。

省略 format 时,格式由导入器声明的签名识别——你的目录中的导入器和核心导入器都是如此。每个导入器的 Plugin 实体都记录了这些签名:读取源所用的语法、签名适用的文件名,以及解析树必须或不得包含的路径。源会经由你的工作区目录为某种语法提供的解析器(若你的目录未为该语法提供解析器,则使用编译器自带的解析器)进行解析,对于适用于其名称的签名所使用的每种语法各解析一次,签名匹配的那唯一一个导入器的格式即被采用。随后导入器通过同一解析器读取源。核心导入器的签名以 JSON 或 YAML 读取文件,未指定文件名的签名以 JSON 读取(Dify 导入器的以 YAML 读取),因此识别单独导入的文件时会以两种方式读取,且无需你的工作区目录中有解析器:编译器自带 JSON 和 YAML 解析器,你的目录提供的解析器会替代它们使用。目录以同样方式按其文件识别:每个签名都会针对其模式选中的目录文件进行尝试,未声明模式的签名不适用于其中任何文件。识别只读取你指定的文件(对于目录,只读取签名模式选中的文件),且不访问网络。没有任何签名匹配的源会被拒绝,要求提供 format 并列出各导入器声明的格式(对于目录,则要求将其中一个文件单独作为 source 发送,或提供一个其导入器声明了文件模式的 format,并只列出这些格式),对应条件为 No importer recognises the source(没有导入器能识别该源);被多个格式的签名匹配的源会被拒绝并列出这些格式,对应条件为 More than one importer recognises the source(有多个导入器能识别该源);两种情况都不会交给猜测出的导入器。在任一情况下,发送 format 即可直接指定格式;对于目录,则指定其导入器声明了文件模式的格式,因为目录只通过这些模式读取。空的 format 会被拒绝,而不会被当作省略处理,因为这是两种不同的请求。

发送 target,为某一个 provider 起草所起草的 Release 据以构建的 Manifest。target 是一种 provider 能力——即 Recipe 的 spec.capability 所绑定的词,例如 compose 或 helm——它就是 aggrega import 的 --target,由同一操作组合而成,因此一次调用与该命令会从同一来源起草出相同的文件。对于草稿所需的每个组件类型和每个功能类型——涉及所起草的 Aggregate 的组件、这些组件的连接及其子系统,它所组合的目录 Aggregates,以及所起草的 Release 的附加项——按草稿首次声明的顺序,导入会在工作区的目录中查找实现该类型并绑定到该能力的 Recipes(对于功能类型则查找功能配方)。若恰好有一个——其中某一个的多个版本算作一个——Manifest 就以不带版本的能力限定名称将该类型映射到它,例如 compose/postgres,首次 pull 会在锁文件中将其固定为可用的最高版本。若有多个且名称各不相同,则映射以该类型本身命名的那一个,例如为 core/datastore/postgres 映射 helm/postgres。若一个都没有,或有多个但没有一个如此命名,该类型就保持未映射,diagnostics 中的一条 warn 条目会指明它及其原因——多个时逐一列出名称——因此在添加映射之前,对这些草稿的构建会停止并指明它的每个实例或附加项,归于 No Recipe is mapped for a component or feature instance(没有为组件或 Feature 实例映射 Recipe)。若由导入器自己起草 Manifest,用以选择某个实例渲染所经由的 Recipe,或在多个功能配方中选择一个,则它写下的、目录为该类型和该能力所提供的每个映射都会保留,其他映射则被丢弃并附一条 warn 条目,它留下的类型按上述方式映射。Manifest 起草为所起草的 Release 旁边的 manifest.yaml,其名称和版本与该 Release 相同,并且该 Release 的 spec.manifest 被设为该名称——导入器在该位置写下的注释会被替换,Release 中的其他内容不变。已经指定了 Manifest 的 Release 保持原样;若导入未起草 Release,Manifest 就起草在 Aggregate 旁边,采用其名称和版本,并有一条 info 条目说明没有任何内容引用它。Manifest 和编辑过的 Release 与其他草稿一样:列在 written 中,记录在记录里,并在 dry_run 下返回。若目录中没有任何 Recipe 绑定到该 target,会在导入器运行之前被拒绝,归于 An import’s target names a capability no Recipe in the catalog binds to(导入的 target 指定了目录中没有任何 Recipe 绑定的能力),并给出你发送的值以及目录中 Recipes 所绑定的能力,且不写入任何内容。省略 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;那里的相对值在命令运行的文件夹中解析:即调用指定的工作区根目录,否则为服务器启动时使用的根目录,否则为服务器运行所在的文件夹。

每个起草路径都会在写入任何内容之前对照输出目录进行检查。越出该目录的路径会被拒绝,并同时指出该路径和该目录,且完全不写入任何内容——即使同一组中自身路径没有问题的文件也不写入,因为被拒绝的导入留下部分内容是没人想要的结果。起草路径来自导入器插件而非你,这正是它与你发送的路径出于同样理由受到检查的原因。

每次起草了内容的导入还会在其草稿旁写入 .aggrega-import.json:即其写入内容的记录——发送给它的 target(如果发送了的话)、它读取的目录快照(如果读取了的话),以及每个起草的文件,并且在起草的 Aggregate 或 Release 中,记录每一层级的每个键,附带写入该处文本的摘要;其他起草的文件则整体记录。一个键的文本包括其所在行、其值不是键映射时其值的各行,以及在其自身缩进处直接写在其上方的注释行。written 会将该记录与草稿一同列出,在 dry_run 下它也在返回的草稿之中。该记录是 JSON,因此读取工作区 YAML 文档的任何程序都不会读取它。

**调用永远不会覆盖输出目录中已有的 Aggregate。**Aggregate 是作者在起草后会继续编辑的文档,因此如果某次调用的某个草稿会落在一个读作 Aggregate 的文件上,该调用会被拒绝,并指出该草稿和该目录,且完全不写入任何内容——在 dry_run 下同样如此,因为 dry run 会拒绝写入所拒绝的内容。起草路径上已有的其他文件都会被覆盖,而先前导入起草、本次导入未起草的文件保持原处不动。

发送 sync,即可改为让先前一次导入所起草的内容与源保持同步,且只更改导入所写的部分。未发送 target 的同步按记录中写明的目标起草,因此会起草先前导入所起草的 Manifest;发送了 target 的同步按该目标起草,记录随后写明该目标。目录中没有任何 Recipe 绑定到的已记录目标,会像发送的目标一样被拒绝,拒绝信息会说明该目标是已记录的目标。每个部分都从三方面判断:记录所说的导入上次在此写入的内容、磁盘上的内容,以及源现在起草的内容。源保持为导入上次所写状态的部分,完全保持磁盘上的原样,无论作者是否编辑过它。源更改的部分会重新写入,源删除的部分会被移除(被起草的文件整体删除),源新增的部分会添加到草稿中围绕它的那些部分旁边;每一项都只在磁盘上的内容就是导入上次所写的内容、且不含作者添加的任何内容时才进行。其他一切逐字节保持不变:作者在任何位置添加的键(一个参数、一个 Feature,包括在被起草的 Component 实例下的,另一个 Component,被起草的 Release 留给作者的环境)、未直接写在被起草键上方的注释,以及记录未列出的每个文件。应答中的 drift 列出每个被同步的部分(或在 dry_run 下,每个将被同步的部分),顺序与草稿中的顺序一致,每项以 change(added、removed 或 changed)、file(该部分所在的被起草文件)以及 key(在被起草的 Aggregate 或 Release 中通往该部分的键,以列表表示,若该部分是整个文件则为空)表示;文本应答将每项单独列为一行,措辞与 aggrega import 写到标准错误的相同:<change> <key> in <file> 或 <change> <file>。dry_run 下为空的 drift 表示草稿与源一致。在 dry_run 下,返回的草稿就是同步将写入的文件,内容为同步将赋予它们的内容。若同步会更改或移除作者编辑过的部分、在作者已写入某部分的位置添加部分,或移除包含作者所添加内容的部分,则会被拒绝,拒绝信息会写明每个此类部分及原因,且不写入任何内容;直接写在被起草键上方的注释视为对该键的编辑。针对没有任何记录列出的 Aggregate 的同步会被拒绝并说明这一点,记录无法读取的同步同样如此;导入器未能完成的同步不写入任何内容。在不含记录、且其被起草路径上没有任何内容的目录中进行的同步,会写入整个草稿。对于非同步的调用,drift 为空列表。

应答包含:source,即你所指定的源;format,源的读取方式;workspace_root,调用所解析到的工作区的根目录;output_dir,被起草路径所相对的目录;written,已写入磁盘的文件;drift,同步所更新的内容;diagnostics,导入器无法翻译的每个结构各一项;decisions,导入器如何映射每个源节点;以及 halted。output_dir 是你发送的目录,未发送时则是该根目录,取自导入实际使用的值;在 dry_run 下同样会报告它,此时不写入任何内容,但每个被起草路径仍相对于它。通过 HTTP 时,workspace_root 会被保留不返回,并标记为 workspace_root_withheld,因为根目录是服务器主机上的位置,详见应答对服务器文件系统的说明;output_dir 在等于该根目录时被保留不返回并标记为 output_dir_withheld,否则以其相对于根目录的名称给出(即你自己的路径所采用的形式),因此应答中仍可看出草稿的去向。导入器未能完成的导入仍会起草它能起草的内容,并以失败标记返回,同时携带完整应答:halted 为 true,确实写入磁盘的文件列在 written 中,旁边的诊断信息写明缺失的内容。这是一个你可以保留或丢弃的部分结果,而不是一次什么都没做的调用。

**decisions 说明导入在哪些地方做了推测。**它为导入器映射的每个源节点各带一个条目,按导入器的顺序排列:source_node,即该节点的 id、type 和 params_summary;candidates,即导入器为它权衡过的每个目录 Component,以 component、score、tier 和 signals 表示——其中列出它的每个信号贡献了什么,分为 table、category、domain_labels、shape 和 name;chosen,即它选定的 target、写入时所用的 mode(对现有 Component 的 reference,或一个 draft),以及该选择的 tier;rationale,即原因;以及 swap_hint,即如何做出不同的选择。导入器未权衡任何候选时没有 candidates,未做选择时没有 chosen,未写出原因和提示时没有 rationale 和 swap_hint。每个值都出自导入器本身——如何为候选打分、各档位的划分都由它决定——因此应把一个条目读作它对该映射的说明。无论是在 dry_run 下还是导入中止时,答复中都有 decisions;对于不报告任何决策的导入器,它是一个空列表。文本答复在诊断信息之后为每个决策单独占一行,措辞与 aggrega import 写入标准错误的相同:mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>,其中的分数是最佳候选的分数。

dry_run 执行除写入以外的一切操作。 每个被起草的文件都在 drafts 下返回,附带其相对于 output_dir 的路径及内容,且不创建任何文件,适用于在保存前先将结果呈现给你的客户端。其他所有行为都与写入相同:同一导入器处理同一源,报告相同的诊断信息,因此写入会拒绝的源在它之下同样会被拒绝。不使用它时,文件会写入磁盘并由 written 列出,且没有 drafts,以免重复你已要求写入的字节。

这些草稿是归你所有、供你继续编辑的起点。它们所述内容是否可接受(某个 socket 是否为生产方所声明的,或某个 Feature 的适用条件是否满足)不在此处判定。这由 validate 回答。

在标准输入和输出上,同一能力也可通过 cli-import 使用,它运行该命令并返回命令打印的文本;通过 HTTP 时该工具不存在,此工具就是在那里使用该能力的方式。

发布、签名与撤回

有四个工具会把内容放到其他人将要解析的位置。publish-entity 打包一个目录实体并发布它;publish-artifact 发布一个独立文件,例如文档包,其字节不透明,也不解析任何实体封装;sign-artifacts 为已发布的引用签名并附加每个签名,若某个引用已带有一个其注册表信任策略可验证的签名,则保持原样;deprecate-artifact 为一个引用附加经签名的撤回标记。在允许其中任何一个之前,请先阅读助手无需先询问你即可执行的操作:这些工具的影响会离开本机。

publish-entity 接受 entity,即要发布的文档;Plugin 还需要 plugin,即发布在其清单内的可执行文件。publish-artifact 接受 file 以及发布时使用的 name 和 tag。这里的每个路径参数都是绝对路径或相对于工作区根目录的路径,与此接口上其他所有工具使用的约定相同;workspace_root 指明调用所指的工作区——适用于通过标准输入输出访问的服务器。通过 HTTPS 访问的服务器拒绝 workspace_root,并要求这些路径都解析到它所服务的工作区之内,详见一个进程,一个工作区。registry 是目标位置,默认为工作区配置的注册表;两者都未提供且未配置默认值时,调用会被拒绝,并指明应发送什么。sign-artifacts 接受 references,即一个或多个注册表地址,而非路径,并可选接受 jobs,即同时签名的数量:省略时逐个签名,小于 1 的值会被拒绝,并指明应发送什么。每个引用的签名方式仍与单独签名时完全相同,如 aggrega sign 所述。deprecate-artifact 要么接受 reference 以及 severity 和 reason,要么接受指明批处理文件的 from——并且对于与批处理文件一起发送的内容参数,它会拒绝而不是丢弃,因为批处理文件自带这些内容,而被悄悄忽略的参数会被误读为已被采纳。

两个发布工具接受 dry_run,它展示一次发布将发送的内容,而不联系任何注册表。 它计算出包,报告本会发布的内容,并在应答中给出值为 false 的 beyond_this_machine,以及在 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 下,该步骤报告它将写入的锁文件,而不写入任何内容。步骤未运行时,若某个 Recipe 或 FeatureRecipe 的 entity.lock 未记录它所读取的某个输入的固定值——或输入已不再与之匹配——则会在打包任何内容之前被拒绝,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。一个签名批次会按引用给出的顺序报告每个已签名的引用及其签名所承诺的摘要;而任何引用失败的批次会作为一次失败返回,并逐一指出每个失败的引用,而不是作为一个附带缩短列表的结果返回——把部分完成的批次报告为成功,正是拒绝被误读为通过的原因。一次弃用会报告每个标记及其自身的摘要,因为标记是作为其所撤回制品的一个无标签引用者附加的,除此之外没有任何东西指向它。对一个未发布任何内容的引用进行签名或撤回会被拒绝,而不会附加到空处。

答复的两个部分

每个工具都以一段可读文本作答;凡是该操作有结构化结果的,还会在文本旁附上结构化结果。 文本是写给阅读对话的人看的。结构化结果以程序可读取的字段承载同一答复——一个判定、一个文件列表、一条诊断;拒绝时,如果该操作在拒绝时已有发现,拒绝也会附带结构化结果,被拒绝的构建返回什么描述了构建的这种情况。

结构化结果也以 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,即该工具的一行用途说明。

没有工具声明输出 schema。 工具的列表信息带有其所接受参数的 schema,但不带结果的 schema,因此 text_answer 在此处说明,而不是在 schema 中说明。

没有结构化结果的答复仅由其文本构成。 对调用参数的拒绝,以及操作没有任何结构化内容可报告的其他失败,都只以文本返回,此时文本是客户端唯一可以展示给模型的部分。

调用未成功时

应答从哪里返回只取决于一点:调用方能否通过修改某个现有工具的参数来解决问题。

凡是能这样解决的问题,都作为该工具自身的结果返回,标记为失败,并以文本形式给出修正说明——工具不接受的选择器组合、遗漏的必需参数、以错误 JSON 类型发送的参数、无法解析的路径、来自编译器的诊断。助手看到的正是这一通道,因此它能读到出了什么问题,并修正参数后再次调用。

协议的错误通道保留给没有工具结果可承载的情况:服务器不提供的工具名称、无法读取其参数的请求、未实现的方法,以及根本不是有效 JSON 的消息。读取资源和渲染提示词的失败也从这里返回,因为这两种结果都没有自己的失败标记。

工具公布的 schema 还声明了其参数必须满足的大部分规则——哪些选择器互斥、哪个参数只有与另一个参数同时出现才有意义、哪些参数是必需的——因此按声明的 schema 组织调用的客户端很少需要实际发起调用才能了解这些规则。schema 未说明的规则仍会被拒绝,并附上一句指明该规则的说明;pull 中 verify 不能与 upgrade_targets 或 pin_sources 组合使用的规则是有意留给拒绝来处理的,原因见解析 Release 的依赖。

什么会停止服务器

通过标准输入和输出时,关闭连接即停止服务器。 服务器每行读取一条消息,并在其标准输入到达流末尾时正常退出,因此关闭连接的客户端会关闭服务器。这是该传输方式下的常见情况,因为你从不自己启动该命令:启动它的客户端也是结束它的一方,所以退出编辑器,或为某个项目禁用此服务器,通常就是停止它的方式。

请求进程本身停止,在两种传输方式下都会作用于服务器。 来自终端的中断,或来自监管程序或容器运行时的终止请求,会在第一次请求时关闭服务器,无论客户端是否正在发送内容:它停止接受消息,结束正在进行的调用所做的工作,然后正常退出。第二次请求会立即结束进程。因此,通过标准输入和输出时,进程被请求停止时仍在运行的调用不会完成;而监听器则会排空,让已在应答中的调用在有限的时间预算内完成,然后进程才退出。

客户端也可以只停止一个调用而不停止服务器,具体方式取决于传输方式。 调用是并发应答的,因此结束某个调用的请求会在该调用仍在运行时得到处理,而不是排在它后面等待。通过标准输入和输出时,客户端指明该调用的 id;取消一个已经应答的调用,或服务器并未在处理的调用,不会产生任何效果——正因如此,发送这样的消息是安全的,无需事先知道应答是否已在返回途中。通过 HTTP 时没有需要发送的消息:关闭承载该调用的连接即可结束它。无论哪种方式,该调用都会被告知停止——其工作在操作下一次检查时结束,而从不检查的操作会一直运行到结束——该调用不会再发送任何内容,其他所有进行中的调用继续执行,服务器也继续提供服务。

使用场景

当你希望 AI 助手依据真实的 schema 和参考文档帮助编写 Aggrega 实体时,请使用 aggrega mcp,这样它的建议基于编译器所接受的确切结构,而不是凭猜测得出。它可以直接融入编写流程:助手读取某个 kind 的 schema 和参考文档,生成骨架,填写你的角色负责的字段,并在交回草稿之前进行校验。有关该流程,请参阅编写 Aggrega 文件。

通过标准输入和输出使用时,你通常无需亲自输入 aggrega mcp,而是在客户端的 MCP 配置中指定一次,由客户端替你启动和停止它。监听器则是另一种情况:此时由你运行该进程,它会持续运行,为并非由其启动它的调用方提供服务。

示例:通过标准输入和输出的客户端配置

用一个 stdio 服务器条目将 MCP 客户端指向该命令:

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

唯一的前提是已安装的 aggrega 二进制文件位于客户端的 PATH 中。各客户端的配置路径和故障排查,请参见连接 MCP 服务器。若要不借助客户端、直接从命令行获取 schema,请参见 aggrega get-schema。