Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

aggrega mcp

Chạy một máy chủ Model Context Protocol qua đầu vào và đầu ra chuẩn, hoặc qua HTTP, để tích hợp với trợ lý AI

Cú pháp

aggrega mcp [flags]

Mô tả

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.

Cờ

CờMặc địnhMô tả
--listen—Địa chỉ mà transport HTTP lắng nghe, ở một trong hai dạng: host:port, hoặc unix: theo sau là một đường dẫn hệ thống tệp. Nó chỉ định nơi lắng nghe và không chọn transport nào: nó được đọc khi có —transport http, hoặc mcp.transport: http trong cấu hình workspace, và nếu được đưa ra cùng transport stdio thì sẽ bị từ chối. Một listener không có chứng chỉ sẽ phục vụ văn bản thuần và chỉ được phép trên loopback (127.0.0.1, ::1, localhost) hoặc trên một Unix socket, đó là dạng mà một máy chủ đứng sau một proxy kết thúc TLS sử dụng; mọi địa chỉ khác cần mcp.tls.cert_file và mcp.tls.key_file, mà tiến trình này khi đó dùng để tự kết thúc TLS. Khi được đặt, ghi đè khóa cấu hình mcp.listen.
--transport—Cách tiếp cận máy chủ: stdio nói giao thức qua đầu vào và đầu ra chuẩn, đó là cách một client khởi chạy lệnh này như một tiến trình con tiếp cận nó; http phục vụ giao thức qua HTTP trên địa chỉ mà —listen hoặc mcp.listen chỉ định, và qua HTTPS khi mcp.tls chỉ định một chứng chỉ và khóa. Khi được đặt, ghi đè khóa cấu hình mcp.transport, có giá trị mặc định là stdio.

Chức năng

aggrega mcp chạy một máy chủ Model Context Protocol. Có hai phương thức truyền tải để kết nối tới máy chủ, và --transport chọn giữa chúng: stdio hoặc http, với mcp.transport trong cấu hình workspace là khóa mà cờ này ghi đè, và stdio là mặc định.

Qua stdio, phương thức mặc định, máy chủ giao tiếp qua đầu vào và đầu ra chuẩn của tiến trình. Ở dạng đó, đây không phải là lệnh bạn chạy tương tác — một client hỗ trợ MCP khởi chạy nó như một tiến trình con và giao tiếp theo giao thức qua stdio; trang Kết nối máy chủ MCP liệt kê nơi mỗi client giữ mục khởi chạy nó. Việc chạy nó biến CLI thành một trợ lý soạn thảo hiểu Aggrega ngay trong trình soạn thảo hoặc ứng dụng chat của bạn.

Qua http, máy chủ phục vụ giao thức qua HTTP: một tiến trình chạy lâu dài trên một máy chủ, được truy cập bởi những bên gọi không ngồi trước bàn phím của máy đó, lắng nghe trên địa chỉ mà --listen chỉ định, hoặc mcp.listen khi không có cờ này. Xem Truy cập máy chủ qua HTTPS để biết cách cấu hình listener đó và những gì nó chấp nhận.

Máy chủ hỗ trợ hai phiên bản của giao thức, 2026-07-28 và 2025-06-18, nên client dùng phiên bản nào cũng kết nối được và truy cập được cùng các bề mặt. Phiên bản mà một lệnh gọi sử dụng được nêu trên chính lệnh gọi đó, chứ không được thỏa thuận một lần cho cả kết nối. Một client dùng 2026-07-28 gửi phiên bản giao thức mà nó dùng và các khả năng của chính nó kèm theo mỗi yêu cầu, và hỏi server/discover xem máy chủ hỗ trợ những gì; một client dùng 2025-06-18 xác lập những điều đó một lần, bằng cách mở kết nối với bước bắt tay initialize. Dù theo cách nào, máy chủ cũng không giữ lại gì giữa các thông điệp, nên những gì bạn gửi trước không quyết định cách một lệnh gọi sau đó được trả lời. Một yêu cầu nêu một phiên bản mà máy chủ không hỗ trợ sẽ bị từ chối và được cho biết hai phiên bản nó có thể yêu cầu, thay vì được trả lời như thể nó đã yêu cầu một trong hai phiên bản đó.

Máy chủ cung cấp ba bề mặt cho trợ lý đã kết nối:

  • Prompts — hai nhóm, và điểm khác nhau là câu hỏi mà mỗi nhóm trả lời. Các prompt soạn thảo trả lời câu hỏi “tôi đang viết gì”: một persona cho mỗi vai trò (developer, architect, operations), cùng với một mẫu tập trung cho từng loại thực thể. Mỗi prompt định khung vai trò và chỉ cho trợ lý đúng schema, trang tham chiếu và hướng dẫn soạn thảo, để các gợi ý của nó nằm trong những trụ cột mà vai trò đó sở hữu. Các prompt quy trình trả lời câu hỏi “gọi những gì, theo thứ tự nào”: mỗi prompt trình bày chuỗi lệnh gọi công cụ có thứ tự để đạt một mục tiêu trải qua nhiều thao tác, kèm các điểm quyết định giữa chúng — soạn một Aggregate mới và Release của nó từ đầu, đưa một chart, module hạ tầng hoặc tệp container-compose có sẵn vào Aggrega, tìm hiểu vì sao một bản build không biên dịch được hoặc kết xuất sai artifact. prompts/list liệt kê cả hai nhóm và prompts/get kết xuất một prompt, nên tập prompt được đọc từ máy chủ chứ không phải từ trang này.

    Một prompt quy trình nêu tên các lệnh gọi và bạn thực hiện chúng, từng lệnh một, đọc kết quả của mỗi lệnh trước lệnh kế tiếp. Không có lệnh gọi nào thực hiện trọn một mục tiêu: mỗi công cụ bọc một thao tác mà bạn có thể kiểm tra, nên chính chuỗi lệnh mới đưa bạn tới đích. Các persona soạn thảo nhận một kind tùy chọn để tập trung vào, mẫu theo từng thực thể thì bắt buộc phải có, và một kind không khớp với schema nào sẽ bị từ chối kèm danh sách các giá trị được chấp nhận, thay vì bị lặng lẽ bỏ qua.

  • Resources — tài liệu tham chiếu chỉ đọc được phục vụ trực tiếp: schema://<kind> cho JSON Schema của một thực thể, langref://<path> cho bất kỳ trang tham chiếu ngôn ngữ nào, authoring://<topic> cho hướng dẫn soạn thảo, catalog://<kind>/<name> cho YAML đã soạn của một thực thể trong catalog, và cli://<command> cho phần trợ giúp của chính một lệnh, với cli:// đứng riêng là điểm vào của nó — phần trợ giúp đó được trả lời từ các lệnh mà chính máy chủ mang theo, nên việc đọc nó không khởi động tiến trình nào và trả về đúng văn bản mà lệnh in ra cho --help. Một lần đọc catalog:// cho một thực thể mà catalog không có sẽ được trả lời là không tìm thấy; khi điều đó là do đúng một tệp catalog khai báo thực thể đã bị bỏ qua lúc nạp, thông điệp của câu trả lời nêu tên tệp đó, ràng buộc mà nó vi phạm và mã ngắn của điều kiện thay vì chỉ URI — chính lời từ chối mà aggrega build đưa ra đầu tiên cho cùng tệp đó. resources/list liệt kê những tài nguyên có thể truy cập mà không cần tham số và resources/templates/list công bố dạng URI của mọi nhóm.

  • Tools — các hành động trên workspace của bạn, và tools/list trả lời với tất cả chúng.

    Các công cụ mà trợ lý gặp đầu tiên được thiết kế cho vòng lặp soạn thảo: list-entities và list-releases để tìm hiểu workspace chứa gì, scaffold một khung mang các trường mà loại của nó yêu cầu, với một placeholder ở mọi chỗ cần một giá trị — hoặc, khi được gửi example, ghi một trong các ví dụ chạy được của tài liệu vào một thư mục mới, trả lời bằng vị trí của thư mục đó, các tệp đã ghi và các lệnh để build nó, và khi được gửi list: true, liệt kê các ví dụ — get-schema cho JSON Schema của một thực thể, validate một bản nháp (nó nêu mọi placeholder mà bản nháp vẫn còn mang, và mỗi placeholder nhận gì), describe một thực thể trong catalog — hoặc một thực thể được đọc từ registry của nó theo tham chiếu — pull để phân giải các phụ thuộc của một Release vào bộ nhớ đệm cục bộ và ghi lockfile của nó, build một Release thành các artifact đã kết xuất — mặc định trong bộ nhớ, không ghi artifact nào ra đĩa, hoặc ghi vào dist/ tại gốc workspace, nơi aggrega build ghi chúng, khi bạn gửi write (và các phụ thuộc chỉ được phân giải trước nếu bạn gửi auto_pull), gen-catalog để tạo các thực thể Plugin từ các guest Wasm, và explain-error để mở rộng một chẩn đoán của trình biên dịch thành hướng dẫn có thể hành động — bao gồm, khi chẩn đoán mở đầu bằng mã ngắn của một điều kiện dừng, điều kiện đó và bản hướng dẫn từng bước đã công bố về cách sửa khi soạn thảo, cũng chính là phần mở rộng mà aggrega explain đưa ra cho cùng mã đó tại terminal.

    Phần còn lại của bề mặt nằm trong cùng câu trả lời chứ không ẩn sau nó: các công cụ khác chạy bên trong máy chủ — lint, công cụ nêu tên kết nối được viết tại một vị trí trong tài liệu, hai công cụ ứng viên, các công cụ container đính kèm và điểm chèn, công cụ áp dụng một chỉnh sửa có giới hạn cho một tài liệu, pin, công cụ ghi lại các content pin cho đầu vào của một thực thể như Ghim các đầu vào của chính một thực thể trình bày, và bốn công cụ phát hành mô tả bên dưới, cùng với danh mục các bộ nhớ đệm và các registry đã cấu hình — và, đối với client đã khởi chạy máy chủ này qua đầu vào và đầu ra chuẩn của nó, một công cụ cho mỗi lệnh mà bạn có thể gõ thay vào đó, được đặt tên theo đường dẫn gọi của lệnh. Các công cụ lệnh đó chỉ tồn tại trên phương thức truyền tải ấy: một máy chủ được truy cập qua HTTP không cung cấp công cụ nào trong số đó, vì lý do nêu tại Truy cập máy chủ qua HTTPS. Không có gì bị giữ lại cho một lệnh gọi sau. Đưa bao nhiêu phần của danh sách công cụ cho mô hình là quyết định của client — nó lấy các định nghĩa và chọn những gì cần nạp — và một định nghĩa mà client chưa bao giờ nhận được là một thao tác mà mô hình không bao giờ gọi được, dù tên công cụ đó có truy cập được trên đường truyền đến đâu. Khi toàn bộ danh sách nhiều hơn mức client của bạn chấp nhận, Thu hẹp những gì máy chủ công bố là cách bạn rút gọn nó. describe-capabilities thu hẹp bề mặt đó theo loại thực thể mà bạn đang soạn. Khi được gửi một kind, nó trả lời với các công cụ phục vụ loại đó, đọc từ các loại mà mỗi công cụ khai báo chứ không phải từ các từ trong mô tả; khi không được gửi đối số nào, nó trả lời với chính chỉ mục đó trên mọi công cụ mà máy chủ này cung cấp cho bạn — tên của từng công cụ, mục đích trong một dòng, các loại nó phục vụ và việc nó có ghi hay không, không kèm schema đối số, nên toàn bộ bề mặt đến trong một câu trả lời dễ đọc. Với một công cụ cli-, việc nó có ghi hay không là việc lệnh mà nó chạy có ghi hay không: cli-build được báo cáo là có ghi, vì lệnh đó lưu các artifact đã kết xuất bên dưới gốc workspace, và cli-scaffold cũng vậy, vì khi được gửi example lệnh đó ghi một trong các ví dụ chạy được của tài liệu vào một thư mục mới, trong khi một lệnh chỉ đọc được báo cáo là chỉ đọc, ngay cả khi trên đường đi nó làm đầy một bộ nhớ đệm mà mọi dự án trên máy cùng dùng chung, giống như công cụ chạy cùng thao tác bên trong máy chủ; khi được gửi tools nêu tên một hoặc nhiều công cụ, nó trả lời với đúng các định nghĩa đầy đủ và schema đối số của những công cụ đó. Các công cụ cli- không bao giờ bị thu hẹp theo loại, vì không có gì ghi lại loại thực thể mà một lệnh phục vụ, nên câu trả lời giới hạn theo loại sẽ bỏ chúng ra và chỉ mục không đối số là nơi bạn đọc chúng. Các đối số của một công cụ lệnh được đặt tên theo chính các cờ của lệnh, nên --output-dir được gửi dưới dạng output_dir, và một tên không được nhận ra sẽ bị từ chối kèm danh sách các cách viết được chấp nhận, thay vì bị lặng lẽ bỏ đi.

    Một số khả năng được cung cấp hai lần trên đầu vào và đầu ra chuẩn: một công cụ được định hình cho vòng lặp soạn thảo chạy thao tác bên trong máy chủ, và công cụ mang tên lệnh có cùng khả năng đó chạy chính lệnh ấy. Hai công cụ không hoạt động giống nhau, nên trên giao thức truyền tải đó mỗi công cụ nêu tên công cụ kia và nói rõ sự khác biệt; qua HTTP các công cụ lệnh không có mặt, và câu ghép cặp được lược bỏ thay vì chỉ tới một công cụ mà bên gọi không thể truy cập. Công cụ chạy bên trong máy chủ là công cụ nên dùng — nó trả về một kết quả máy đọc được bên cạnh văn bản dễ đọc, nên trợ lý nhận được một phán quyết, một danh sách tệp hay một chẩn đoán dưới dạng các trường thay vì một bản ghi cần phân tích. Công cụ lệnh khởi động lệnh thật trong một tiến trình riêng, nên nó làm mọi việc lệnh đó làm trên máy nơi nó chạy, kể cả ghi ra đĩa ở nơi lệnh ghi — cli-build ghi các artifact đã kết xuất vào dist/ tại gốc workspace, và các tệp của một bản build có truy vết vào .trace/ bên cạnh, và dòng kết thúc nó trả về nêu đầy đủ thư mục đó — và chỉ trả về dòng lệnh nó đã chạy cùng văn bản lệnh đó đã in ra. Hãy dùng nó khi bạn cần một flag mà lệnh khai báo nhưng công cụ kia không chấp nhận.

    Dòng lệnh đó mở đầu bằng các flag toàn cục quyết định cấu hình mà máy chủ này được khởi động cùng — --config và --offline, nếu bạn đã đưa chúng — đứng trước lệnh và các flag riêng của lời gọi. Vì vậy lệnh đọc cùng cấu hình mà mọi công cụ khác ở đây đọc: một máy chủ được khởi động với --offline chạy các lệnh của nó ở chế độ ngoại tuyến, và một máy chủ được khởi động với --config chạy chúng trên tệp toàn cục đó. Một flag mà lời gọi tự gửi đứng sau chúng và được ưu tiên, nên offline: false trên một lời gọi sẽ truy cập mạng chỉ cho lời gọi đó, và dòng lệnh trả về hiển thị cả hai. Nơi máy chủ được khởi động với một gốc workspace — bằng --workspace-root, hoặc bằng AGGREGA_WORKSPACE_ROOT — dòng lệnh mở đầu bằng gốc đó dưới dạng --workspace-root, đứng trước hai flag kia, nên lệnh lấy thư mục đó làm gốc workspace, như khi gõ với cùng flag và như mọi công cụ chạy bên trong máy chủ lấy nó, thay vì tìm workspace từ thư mục nơi máy chủ được khởi động. Một lời gọi gửi workspace_root tự nêu gốc của riêng nó, và dòng lệnh chỉ mang gốc đó — kể cả một giá trị rỗng, mà lệnh đọc như --workspace-root "" được đọc tại terminal: tìm workspace từ thư mục nơi máy chủ được khởi động. Một máy chủ được khởi động không có cả hai thì không chuyển gốc nào, nên các lệnh của nó tìm workspace từ thư mục đó, theo quy tắc mà Lời gọi được trả lời trong workspace nào đặt ra cho mọi công cụ — ngoại trừ lần khởi chạy của gói desktop với thiết lập Workspace folder để trống, khi đó một lời gọi không nêu workspace riêng sẽ không khởi động lệnh nào và được trả lời bằng lời từ chối của thiết lập đó. Lệnh khởi động trong gốc workspace mà lời gọi hoặc lần khởi chạy nêu ra: workspace_root riêng của lời gọi, được đọc như mọi công cụ đọc nó — đường dẫn tuyệt đối đúng như đã gửi, đường dẫn tương đối tính từ gốc mà một lời gọi không nêu gốc nào được trả lời trong đó — và được chuyển cho lệnh ở dạng tuyệt đối của nó, nếu không thì là gốc mà máy chủ được khởi động cùng. Vì vậy một đường dẫn tương đối mà lời gọi truyền làm tệp cần đọc — một tài liệu cho validate, một --release hay một --catalog — được đọc bên trong workspace đó, như tại một terminal mở ở đó, và một bản build mà lệnh chạy sẽ ghi dist/ bên dưới gốc đó. Nơi không có gì nêu gốc — không có gốc khởi chạy, và không có workspace_root hoặc có nhưng rỗng — lệnh khởi động trong thư mục nơi máy chủ được khởi động và đọc đường dẫn tương đối từ đó; một workspace_root nêu một thư mục không tồn tại được chuyển tiếp đúng như khi được đọc — đường dẫn tuyệt đối đúng như đã gửi, đường dẫn tương đối ở dạng đầy đủ — và lệnh từ chối nó bằng lời của chính nó. Một lệnh do plugin mở rộng lệnh đăng ký không được chuyển flag nào trong số đó, vì nó chuyển mọi đối số cho plugin mà không đọc thay vì phân tích flag toàn cục, tại terminal cũng như ở đây; nó khởi động trong cùng thư mục như mọi lệnh khác.

    Một vài lệnh được cố ý loại bỏ ngay cả trên đầu vào và đầu ra chuẩn, nơi các công cụ lệnh có tồn tại — qua HTTP thì tất cả đều vắng mặt, và đó là đặc tính của giao thức truyền tải chứ không phải của lệnh nào. Trên đầu vào và đầu ra chuẩn, mỗi lệnh này bị loại vì một lý do được nêu rõ: daemon và chính máy chủ này sẽ không bao giờ trả về kết quả; một lệnh đọc mật khẩu từ terminal không có chỗ nào để đọc; một lệnh ghi script hoàn thành lệnh cho shell không có shell nào để cài đặt vào; việc xóa một thông tin xác thực đã lưu tác động lên kho lưu trữ toàn máy thay vì lên bất kỳ workspace nào bạn đã nêu; và việc lấy token định danh theo kiểu tương tác không có dạng phi tương tác nào để cung cấp. Vắng mặt vì cùng lý do toàn máy đó là aggrega plugin run-local, lệnh nạp một guest .wasm từ một đường dẫn bạn đưa cho nó: mục đích của lệnh là đọc một tệp ở bất cứ đâu bạn đặt, nên không có workspace nào để giới hạn nó, và việc đọc diễn ra ngay trong tiến trình trước khi guest tồn tại. Guest không được cấp gì khi nó thực sự chạy — không thư mục, không socket, không biến môi trường — nhưng đó là giới hạn đối với module chứ không phải đối với việc đọc, nên đó không phải điều quyết định việc này. Hãy chạy nó tại terminal của bạn, nơi chính bạn là người nêu đường dẫn. Ký và xuất bản là một trường hợp hoàn toàn khác, và sự khác biệt đó là điều giữ chúng ngoài danh sách này. Mỗi thao tác phân giải một danh tính từ một đầu vào được cung cấp hoặc có sẵn trong môi trường và từ chối rõ ràng khi không có, nên mỗi thao tác có một dạng hoàn tất được mà không cần ai theo dõi — trong khi lấy token theo kiểu tương tác là một động từ mà không đầu vào nào có thể đáp ứng, ngay cả về nguyên tắc. Vì vậy chúng có mặt hai lần: dưới dạng các lệnh, và dưới dạng bốn công cụ chạy trong tiến trình được mô tả tại Xuất bản, ký và thu hồi. Nơi dòng lệnh sẽ mở trình duyệt, chúng từ chối và nêu điều cần cung cấp thay vào đó, thay vì chờ một người không có mặt.

Một lời gọi được trả lời trong workspace nào

Một lời gọi chỉ định workspace của nó bằng workspace_root; nếu không, nó được trả lời trong workspace mà máy chủ được khởi động trên đó. Khi lần khởi chạy đã chỉ định một thư mục gốc, bằng --workspace-root hoặc AGGREGA_WORKSPACE_ROOT, thì thư mục gốc đó chính là thư mục gốc của workspace, giống như cờ này trên mọi lệnh: không có gì phía trên nó được tìm kiếm để tìm một workspace bao quanh, vì vậy lần khởi chạy chỉ định thư mục chứa .aggrega-config.yaml của workspace, và một lời gọi được trả lời ở đó bởi cả các công cụ chạy bên trong máy chủ lẫn các công cụ lệnh. Khi lần khởi chạy không chỉ định thư mục gốc nào, workspace được tìm từ thư mục mà máy chủ được khởi động trong đó, đúng như cách một lệnh gõ tại terminal ở đó phát hiện nó — thứ tự được trình bày trong The other ways a project root is recognised — ngoại trừ lần khởi chạy của gói desktop với thiết lập Workspace folder để trống, vốn từ chối lời gọi như vậy, như được trình bày bên dưới. Một workspace_root tương đối được đọc từ thư mục gốc mà một lời gọi không chỉ định gốc nào được trả lời trong đó — thư mục gốc mà lần khởi chạy đã chỉ định, hoặc, khi không chỉ định, thư mục gốc workspace mà thư mục nơi máy chủ được khởi động phân giải tới — nên một lời gọi chỉ định một thư mục bên trong workspace, chẳng hạn quickstart-ai/1, mà không cần biết workspace nằm ở đâu trên máy; một đường dẫn tuyệt đối được dùng đúng như được cung cấp. Mọi công cụ đều đọc nó như vậy, kể cả các công cụ lệnh. Khi không có thư mục gốc nào để đọc một đường dẫn tương đối — một thư mục gốc khởi chạy không phải là thư mục tồn tại, hoặc lần khởi chạy desktop với Workspace folder để trống — một đường dẫn tương đối bị từ chối giống như một lời gọi không chỉ định gốc nào. Một workspace_root không chỉ định thư mục nào tồn tại, hoặc chỉ định một tệp, sẽ bị từ chối trước khi công cụ làm bất cứ điều gì khác, với thông báo nêu tên đối số và trích dẫn giá trị — đường dẫn tuyệt đối đúng như khi được gửi, đường dẫn tương đối ở dạng đầy đủ như khi được đọc — giống như một lệnh từ chối --workspace-root.

Một thư mục gốc khởi chạy không phải là thư mục tồn tại được phục vụ dưới dạng một lời từ chối qua đầu vào và đầu ra chuẩn. Khi --workspace-root hoặc AGGREGA_WORKSPACE_ROOT chỉ định một thư mục không tồn tại, hoặc chỉ định một tệp, máy chủ ghi lời từ chối vào luồng lỗi của nó và vẫn khởi động, để một client không hiển thị gì từ luồng đó cho người dùng vẫn cho thấy lý do. Nó trả lời initialize và các danh sách công cụ, tài nguyên và prompt của nó, còn mọi lời gọi sẽ hoạt động trong workspace đó đều được trả lời bằng lời từ chối: một lời gọi công cụ dưới dạng kết quả thất bại, một lần đọc thực thể catalog:// hoặc một trang tài liệu dưới dạng lỗi. Lời từ chối nêu tên cờ, hoặc biến cùng với thiết lập Workspace folder của ứng dụng desktop đặt giá trị cho nó — thiết lập mà Claude Desktop mô tả — và trích dẫn giá trị đúng như khi được cung cấp; một giá trị mà client gửi mà không điền vào được trích dẫn đúng như khi đến, và không có gì trong đó được nhận diện. Một công cụ chạy lệnh sẽ không khởi động lệnh nào cho một lời gọi không chỉ định workspace riêng, vì thư mục mà lệnh đó sẽ khởi động trong đó không tồn tại, và trả lời bằng cùng lời từ chối. Một lời gọi chỉ định workspace riêng bằng đường dẫn tuyệt đối được trả lời ở đó; một lời gọi chỉ định nó bằng đường dẫn tương đối không có thư mục nào để đọc nó, và được trả lời bằng cùng lời từ chối. Những gì không hoạt động trong workspace nào — một schema, một prompt, phần trợ giúp của một lệnh — được trả lời như trên bất kỳ máy chủ nào. Thay vào đó, một listener bị từ chối ngay khi khởi động, trước khi bất cứ thứ gì được bind, với cùng lời từ chối, để người giám sát nó đọc được lỗi ở nơi họ tìm lỗi.

Một lần khởi chạy desktop với thiết lập Workspace folder để trống được phục vụ dưới dạng lời từ chối theo cùng cách. Gói desktop luôn truyền cho máy chủ AGGREGA_WORKSPACE_ROOT, mang bất cứ giá trị nào Workspace folder chứa, và đặt AGGREGA_BUNDLE_VERSION bên cạnh nó, trong khi ứng dụng khởi động máy chủ trong một thư mục do nó tự chọn — thường là một thư mục hệ thống — chứ không phải trong dự án của bạn. Vì vậy, một máy chủ qua đầu vào và đầu ra chuẩn được khởi động không có --workspace-root, mà môi trường của nó mang AGGREGA_BUNDLE_VERSION và một AGGREGA_WORKSPACE_ROOT trống hoặc vắng mặt, sẽ không tìm workspace từ thư mục mà nó được khởi động trong đó. Nó ghi lời từ chối vào luồng lỗi và vẫn khởi động, trả lời như với một thư mục gốc khởi chạy không tồn tại: mọi lời gọi sẽ hoạt động trong một workspace mà không chỉ định workspace riêng đều được trả lời bằng một lời từ chối nói rằng ứng dụng desktop đã khởi chạy máy chủ với thiết lập Workspace folder để trống, nên AGGREGA_WORKSPACE_ROOT không chỉ định thư mục gốc workspace nào, yêu cầu bạn đặt Workspace folder thành thư mục chứa .aggrega-config.yaml của workspace, và cho biết một thư mục được đặt sau khi máy chủ đã khởi động chỉ có hiệu lực khi tiện ích mở rộng được tắt rồi bật lại hoặc ứng dụng được khởi động lại, vì ứng dụng chỉ truyền thiết lập cho máy chủ khi khởi động nó. Một công cụ chạy lệnh sẽ không khởi động lệnh nào cho lời gọi như vậy. Một lời gọi chỉ định workspace riêng bằng đường dẫn tuyệt đối được trả lời ở đó, và một lời gọi chỉ định nó bằng đường dẫn tương đối được trả lời bằng cùng lời từ chối, vì không có Workspace folder nào để đọc nó; những gì không hoạt động trong workspace nào được trả lời như trên bất kỳ máy chủ nào. Máy chủ nhận diện lần khởi chạy chỉ bằng AGGREGA_BUNDLE_VERSION: một gói không đặt biến như vậy thì thiết lập trống được đọc là không có thư mục gốc, và một lần khởi chạy tự đặt biến đó và không chỉ định thư mục gốc nào sẽ bị từ chối như của gói. Mọi giá trị trống khác vẫn không chỉ định thư mục gốc nào — một AGGREGA_WORKSPACE_ROOT trống trong lần khởi chạy không mang AGGREGA_BUNDLE_VERSION, một --workspace-root gõ trống, một listener, aggrega serve và mọi lệnh khác đều đọc nó là chưa đặt.

Khi không tìm thấy workspace nào và không có workspace nào được chỉ định, một câu trả lời liên quan đến workspace cho biết nó đã dùng thư mục nào. Khi không có thư mục gốc khởi chạy, không có workspace_root trong lời gọi, và không có gì neo một workspace từ thư mục mà lời gọi được trả lời trong đó, lời gọi được trả lời trong thư mục đó. Khi kết quả của công cụ phụ thuộc vào workspace — chính là những công cụ có lệnh đưa ra cảnh báo trên dòng lệnh — văn bản của nó kết thúc bằng cảnh báo của dòng lệnh, <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace, và một dòng yêu cầu bạn gửi workspace_root chỉ định thư mục chứa .aggrega-config.yaml của workspace; một câu trả lời không do workspace quyết định, chẳng hạn việc đọc cấu hình hoặc danh sách plugin, không nói gì về workspace. Câu đó không thêm trường riêng nào vào kết quả có cấu trúc; kết quả có cấu trúc mang nó trong text_answer, trường chứa văn bản, như The two parts of an answer trình bày. Một công cụ chạy lệnh trong một tiến trình riêng mang dòng riêng của lệnh nói cùng điều đó, đúng như lệnh đã in ra. Không có gì được ghi vào bộ nhớ đệm artifact trong thư mục như vậy: một lần pull, hoặc một lần build được yêu cầu giải quyết các phụ thuộc trước, ở đó sẽ bị từ chối trước khi bất cứ thứ gì được tải về, với thông báo nêu tên thư mục và hai lối ra — gửi workspace_root, hoặc cho thư mục một .aggrega-config.yaml mang khối workspace:. Một lần pin, hoặc một lần xuất bản Recipe hoặc FeatureRecipe, bị từ chối theo cùng cách khi nó sẽ tải về một nguồn từ xa mà thực thể ghi đầy đủ — để pin nó, hoặc để so sánh pin của nó — trước khi nguồn đó được tải về; khi nó không tải về nguồn nào, vì thực thể không có nguồn, có nguồn cục bộ hoặc nguồn có tọa độ do mỗi Release điền vào, nó được trả lời như ở bất kỳ nơi nào khác. Một lần build ở đó không giải quyết gì trước vẫn render, nhưng một đầu vào bên ngoài mà lockfile của nó pin và bộ nhớ đệm không còn giữ sẽ không được tải lại: quá trình render được báo chính câu đó thay cho đầu vào, như khi nó được báo về chế độ offline. Không câu trả lời nào qua HTTP mang câu đó: một listener luôn phục vụ một workspace mà nó được cung cấp hoặc đã tìm thấy. Lần khởi chạy của gói desktop với thiết lập Workspace folder trống cũng vậy, vì nó từ chối lời gọi không chỉ định workspace riêng thay vì trả lời trong thư mục mà nó được khởi động.

Một lệnh gọi về một Release hoặc một tài liệu mà nó nêu bằng đường dẫn tuyệt đối được trả lời trong workspace của chính tệp đó khi không có gì khác xác định một workspace. Khi lần khởi chạy không nêu gốc nào, lệnh gọi không gửi workspace_root, và thư mục mà server được khởi động trong đó không neo workspace nào, thì workspace được tìm lại từ thư mục chứa tệp đó, và bất cứ gì việc tìm đó thấy — dự án mà tệp thuộc về, hoặc, nếu mọi cách đều không được, chính thư mục đó — là workspace mà lệnh gọi được trả lời trong đó. Đó là quy tắc mà một lệnh gõ tại terminal tuân theo, nên nó áp dụng cho mọi công cụ có lệnh gọi liên quan đến một Release hoặc một tài liệu thực thể mà nó nêu: một bản build, một lần pull, một lần xác thực, một lần lint, một mô tả, một danh sách theo các thuật ngữ của một Release, một câu hỏi về một nút trong đồ thị của một Release, một pin, việc xuất bản một thực thể, một chỉnh sửa, và việc đọc một vị trí trong tài liệu. Khi một lệnh gọi nêu cả một Release lẫn một tài liệu, Release quyết định. Vì vậy, một client đã khởi chạy server bên ngoài dự án của bạn vẫn có một Release trong đó được build từ cấu hình riêng của dự án. Các đường dẫn khác mà lệnh gọi nêu được đọc như mọi khi — đường dẫn tương đối được tính từ thư mục mà server được khởi động trong đó — và một công cụ chạy một lệnh trong một tiến trình riêng được trả lời từ cùng workspace đó, vì lệnh tuân theo cùng quy tắc trong cùng thư mục đó. Một gốc mà lần khởi chạy đã nêu, một workspace_root mà lệnh gọi gửi, một thư mục khởi động tự nó nằm trong một workspace, và một Release hoặc tài liệu được nêu bằng đường dẫn tương đối đều được dùng nguyên như vậy. Qua HTTP, không điều nào trong số này xảy ra: một listener luôn phục vụ một workspace mà nó được cung cấp hoặc đã tìm thấy, và mọi đường dẫn mà một lệnh gọi nêu đều tương đối với workspace đó. Điều này cũng không xảy ra với lần khởi chạy của gói desktop có thiết lập Workspace folder để trống, vốn từ chối một lệnh gọi không nêu workspace nào của riêng nó, bất kể nó nêu tệp nào.

Thu hẹp những gì máy chủ công bố

mcp.announce_tools nêu tên các công cụ mà máy chủ này công bố, viết đúng như danh sách công cụ báo cáo chúng. Bỏ khóa này đi thì mọi công cụ máy chủ này mang đều được công bố; đó là mặc định và là dạng mà một client tuân theo giao thức mong đợi. Viết một danh sách thì đúng những công cụ đó được công bố: một công cụ bị bỏ ra sẽ vắng mặt trong danh sách công cụ, vắng mặt trong câu trả lời của describe-capabilities, và bị từ chối nếu vẫn được gọi theo tên, với lời từ chối nêu tên thiết lập này. Viết một danh sách rỗng thì không có gì được công bố cả — vì vậy bỏ khóa đi và viết [] là hai khẳng định khác nhau, và thiết lập này không có giá trị mặc định nào được điền sẵn cho bạn.

Hãy đặt nó khi client ở đầu bên kia giới hạn số công cụ mà nó sẽ đăng ký, đôi khi tính gộp trên mọi máy chủ mà nó kết nối cùng lúc, và nêu tên các công cụ mà client đó cần. Giới hạn đó là trường hợp mà thiết lập này tồn tại để phục vụ, và client mà nó áp dụng thường là client đã khởi chạy máy chủ này qua đầu vào và đầu ra chuẩn của chính nó — vì vậy, khác với phần còn lại của khối mcp, vốn cấu hình listener mà transport http khởi động, khóa này được đọc bất kể máy chủ dùng transport nào.

Nó thu hẹp những gì được công bố và không gì hơn. Nêu tên một công cụ ở đây không mở rộng điều gì. Nó không gỡ bỏ mcp.deny_reach, thiết lập rút hẳn một năng lực, nên một công cụ được nêu tên ở đây thuộc loại mà thiết lập đó rút đi vẫn nằm ngoài danh sách và bị từ chối với lời từ chối nêu tên thiết lập đó. Nó cũng không gỡ bỏ các scope mà token của bên gọi mang: một công cụ được nêu tên ở đây được liệt kê bất kể các scope đó là gì, và một lời gọi mà chúng không cho phép vẫn bị từ chối, nêu tên scope có thể cho phép. Dù thế nào, lời từ chối mà bên gọi gặp là của giới hạn kia chứ không phải của giới hạn này. Một lời từ chối từ thiết lập này không mang challenge và không nêu tên scope nào, vì không thông tin xác thực nào thay đổi được những gì một máy chủ đã chọn cung cấp — thay vào đó, nó nêu tên thiết lập, là thứ duy nhất mà người đọc lời từ chối có thể xử lý.

Mọi tên phải là tên của một công cụ mà tệp nhị phân này mang. Một tên không ứng với công cụ nào sẽ dừng máy chủ trước khi nó phục vụ bất cứ gì, và lời từ chối liệt kê các công cụ mà nó có — vì vậy một lỗi chính tả được phát hiện ngay lúc khởi động thay vì qua một bề mặt lặng lẽ hẹp hơn bề mặt bạn yêu cầu. Một tên thuộc họ cli-, vốn chạy một lệnh aggrega trong một tiến trình riêng, được chấp nhận trên cả hai transport và không công bố gì qua HTTP, nơi ngay từ đầu không công cụ nào như vậy được cung cấp cho bất kỳ bên gọi nào.

Tập hợp được công bố được cố định khi tiến trình khởi động, nên muốn thay đổi nó phải khởi động lại, và không có gì làm danh sách lớn thêm đối với một client đã kết nối.

Máy chủ đến từ bản phát hành nào

describe-capabilities khi được gửi không kèm đối số sẽ cho biết máy chủ này đến từ bản phát hành nào. Câu trả lời có cấu trúc của nó mang server_version, phiên bản mà tệp thực thi aggrega tự báo cáo — chính là phiên bản mà aggrega version in ra cho cùng tệp đó — và phần văn bản của nó mở đầu bằng một dòng nêu phiên bản này, trước phần chỉ mục. Câu trả lời có cấu trúc mang chính dòng đó dưới dạng version_summary, nguyên văn từng chữ, nên một client chỉ chuyển cho mô hình câu trả lời có cấu trúc thì cũng chuyển luôn dòng đó.

Khi gói desktop khởi chạy máy chủ, cùng câu trả lời đó nêu thêm phiên bản của gói bên cạnh. Gói không chứa chương trình nào: nó khởi chạy tệp thực thi aggrega mà thiết lập Path to the aggrega executable của nó chỉ định — theo mặc định là tên lệnh aggrega, mà ứng dụng tìm trong PATH của nó — nên gói và tệp thực thi được cài đặt riêng và có thể đến từ các bản phát hành khác nhau, còn ứng dụng liệt kê gói chỉ hiển thị phiên bản của chính gói. Gói truyền phiên bản của nó cho máy chủ dưới dạng AGGREGA_BUNDLE_VERSION trong môi trường; máy chủ đọc biến này một lần, khi khởi động, và câu trả lời mang nó dưới dạng bundle_version. Hai giá trị được so sánh đúng như được viết, đây là cách so sánh hợp lý vì gói và tệp thực thi của cùng một bản phát hành được đóng dấu phiên bản của bản phát hành đó theo cùng một dạng, còn một bản dựng phát triển thì đọc khác với mọi bản phát hành. Khi hai giá trị bằng nhau, dòng đó nêu cả hai và không nói gì thêm. Khi chúng khác nhau, dòng đó nói, kèm tên cả hai, rằng tệp thực thi và gói đến từ các bản phát hành khác nhau, và phần hướng dẫn mà máy chủ đưa cho mô hình khi kết nối cũng mở đầu bằng chính câu đó, nên sự khác biệt đã hiện ra trước mô hình trước khi nó hỏi.

Một máy chủ không do gói nào khởi chạy chỉ báo cáo phiên bản của chính nó. Khi được khởi động từ terminal, từ cấu hình của trình soạn thảo hoặc dưới dạng listener, nó không mang bundle_version, trừ khi có thứ gì đó đặt biến này trong môi trường của nó. Một máy chủ chạy qua đầu vào và đầu ra chuẩn có mang biến này được coi là do gói khởi chạy thêm ở một khía cạnh nữa: khi không được chỉ định thư mục gốc, nó từ chối thiết lập Workspace folder trống, như Lời gọi được trả lời trong workspace nào trình bày. Một lời gọi describe-capabilities được gửi kèm kind hoặc tools không mang server_version, bundle_version hay version_summary và không có dòng nào như vậy, vì nó trả lời về các công cụ chứ không phải về máy chủ.

Sự khác biệt được báo cáo và không bao giờ bị từ chối. Máy chủ vẫn khởi động và trả lời mọi lời gọi y hệt như khi hai phiên bản khớp nhau. Sự khác biệt có ý nghĩa gì đối với một bản cài đặt desktop, và cách đưa hai phiên bản về khớp nhau, được trình bày trong Kết nối máy chủ MCP.

Truy cập máy chủ qua HTTPS

aggrega mcp --transport http phục vụ giao thức qua HTTP thay vì qua đầu vào và đầu ra chuẩn. mcp.transport trong cấu hình workspace là khóa mà cờ đó ghi đè, và giá trị mặc định của nó, stdio, là điều một client khởi chạy lệnh mong đợi — vì vậy một máy chủ mà người khác truy cập mang transport: http trong cấu hình của nó, còn một client được khởi chạy từ một thư mục mà cấu hình đó bao phủ vẫn truy cập máy chủ qua các luồng của chính nó. Dù theo cách nào thì đó vẫn là cùng một máy chủ — cùng workspace và cùng các bề mặt giao thức — và điều thay đổi là cách một thông điệp đến được máy chủ, cách một lệnh gọi kết thúc, và những gì người vận hành nó phải nắm giữ. Phần này là những gì người vận hành cấu hình; mục mà một client cần để truy cập một máy chủ đang chạy nằm trong Kết nối máy chủ MCP.

Một địa chỉ không chọn transport. --listen <address>, hoặc mcp.listen khi không có cờ, chỉ định nơi listener gắn kết khi http đã được chọn, và không gì hơn. Vì vậy http mà không có địa chỉ từ nguồn nào bị từ chối trước khi bất cứ thứ gì được gắn kết, và lời từ chối nêu tên cả hai. --listen được gõ khi transport là stdio — được gõ dưới dạng --transport stdio, được cấu hình là mcp.transport: stdio, hoặc để mặc định — cũng bị từ chối, nêu --transport http là cờ sẽ phục vụ trên địa chỉ đó; một --listen được cho giá trị rỗng bị từ chối vì không chỉ định địa chỉ nào, bất kể transport là gì. Và một địa chỉ chỉ do cấu hình chỉ định sẽ không được dùng bởi một máy chủ giao tiếp qua các luồng của chính nó; máy chủ này nói điều đó trong một dòng trên luồng lỗi của nó, nêu tên tệp đã đặt địa chỉ và mcp.transport: http. Trường hợp cuối cùng đó cố ý không bị từ chối ở đâu cả: đó là lần khởi chạy mà một client thực hiện khi nó khởi động lệnh trong một thư mục có cấu hình mang các thiết lập của listener, và một cấu hình listener quên transport: http sẽ không khởi động listener nào, và đó là nơi điều này được nhận ra.

Một máy chủ được truy cập qua HTTP không cung cấp công cụ nào chạy một lệnh aggrega trong một tiến trình riêng. Các công cụ đó chỉ tồn tại cho một client đã khởi chạy máy chủ này qua đầu vào và đầu ra chuẩn của nó, trên chính máy của client đó, nơi việc chỉ định một thư mục hay một cờ không trao cho bên gọi điều gì mà họ chưa có. Một bên gọi truy cập máy chủ qua HTTP không sở hữu máy chủ chủ mà nó chạy trên đó, vì vậy một lệnh sẽ tác động lên hệ thống tệp của máy đó với quyền hạn của chính máy chủ thì được chạy tại một terminal trên máy đó. Các công cụ này vắng mặt khỏi danh sách và khỏi describe-capabilities thay vì được cung cấp rồi bị từ chối, và một lệnh gọi chỉ định một công cụ trong số đó được trả lời bằng một lỗi nói như vậy. Đó là một thuộc tính của transport, không phải một thiết lập: không có cấu hình nào đưa chúng trở lại.

Hãy đọc Nothing is served without a credential trước khi bạn triển khai một máy chủ. Mọi yêu cầu tới endpoint đều mang một thông tin xác thực, và không có thiết lập nào phục vụ một yêu cầu không có thông tin xác thực — điều một thiết lập lựa chọn là máy chủ này tự kiểm tra một bearer token hay đọc một bên gọi mà một proxy phía trước đã kiểm tra.

Hai dạng triển khai

Tiến trình tự kết thúc TLS. Đặt mcp.tls.cert_file thành một chuỗi chứng chỉ PEM và mcp.tls.key_file thành khóa riêng của nó, và listener phục vụ HTTPS trực tiếp trên bất kỳ địa chỉ nào bạn đã cho nó. Cả hai tệp được đọc khi tiến trình khởi động, vì vậy một chứng chỉ được thay thế sẽ được nạp bằng cách khởi động lại tiến trình. Việc đặt một khóa mà không đặt khóa kia bị từ chối khi khởi động thay vì chuyển sang phương án dự phòng: một chứng chỉ không có khóa thì không thể trình ra và một khóa không có chứng chỉ thì không chỉ định gì, và một lỗi gõ trong một đường dẫn không phải là lý do để bắt đầu phục vụ lưu lượng không mã hóa.

Một proxy phía trước kết thúc TLS và chuyển tiếp tới một listener bị giới hạn. Để trống cả hai khóa và listener phục vụ văn bản thuần, điều chỉ được chấp nhận trên loopback hoặc trên một Unix socket — vì vậy không gì không nằm sẵn trên máy đó có thể truy cập nó. Đó là dạng mà một reverse proxy, một sidecar hoặc một service mesh sử dụng, và đó là dạng mà chứng chỉ nằm phía trước tiến trình này chứ không nằm trong nó.

Một listener văn bản thuần trên bất kỳ địa chỉ nào khác bị từ chối trước khi bất cứ thứ gì được gắn kết, và lời từ chối nêu tên cả hai khóa TLS. Không có thiết lập nào gỡ bỏ điều này và không có địa chỉ nào là ngoại lệ: một listener nhận kết nối từ mạng mà không có chứng chỉ của riêng nó thì không bao giờ an toàn, vì vậy tiến trình từ chối khởi động thay vì khởi động ở dạng đó.

Các dạng địa chỉ

--listen và mcp.listen nhận một trong hai dạng:

  • host:port — một địa chỉ TCP, chẳng hạn 127.0.0.1:7777 hoặc 0.0.0.0:8443. Loopback nghĩa là 127.0.0.1, ::1, hoặc localhost khi mọi địa chỉ mà tên đó phân giải tới đều là địa chỉ loopback. Mọi thứ khác là một địa chỉ mạng và cần một chứng chỉ: một host rỗng, tức là mọi giao diện mà máy có; một địa chỉ giao diện cụ thể; và bất kỳ tên nào khác, kể cả một tên đang phân giải tới một địa chỉ loopback vào lúc này, vì nơi một listener có thể gắn kết không nên phụ thuộc vào một kết quả phân giải có thể thay đổi bên dưới nó.
  • unix: theo sau là một đường dẫn hệ thống tệp — một Unix-domain socket, chẳng hạn unix:/run/aggrega/mcp.sock. Một socket chỉ có thể truy cập từ máy mà nó nằm trên đó, vì vậy nó không cần chứng chỉ.

Một đường dẫn socket được lấy đúng như được viết, kể cả đường dẫn tương đối. Nó cố ý không được phân giải tương đối với tệp cấu hình đã khai báo nó, vì cùng địa chỉ đó cũng đến từ --listen, vốn không có tệp khai báo — xem nơi một đường dẫn tương đối trỏ tới.

Những gì listener chấp nhận

Một endpoint, /mcp, chấp nhận POST. Mỗi thông điệp JSON-RPC là một yêu cầu riêng và không giữ phiên dưới bất kỳ hình thức nào: không điều gì client gửi trước quyết định cách một yêu cầu sau được trả lời, không có định danh phiên nào được tạo ra, và header phiên hoặc header tiếp tục luồng mà client gửi đều bị bỏ qua. Mọi phương thức khác trên endpoint đó được trả lời 405 kèm Allow: POST, và mọi đường dẫn khác được trả lời 404 — cả hai đều được quyết định trước khi kiểm tra thông tin xác thực, nên việc thăm dò không học được gì từ một yêu cầu xác thực trên một đường dẫn hay một phương thức vốn dĩ không phục vụ gì.

Một yêu cầu được trả lời bằng một đối tượng JSON và một mã trạng thái — hoặc, khi lời gọi báo cáo tiến độ trên đường đi tới đối tượng đó, bằng một luồng sự kiện kết thúc bằng đối tượng ấy, như Được thông báo về tiến trình của một lời gọi dài trình bày. Một notification — thông điệp không mang id — được trả lời 202 với phần thân rỗng. Một thông điệp không thuộc loại nào trong hai loại đó, kể cả một JSON-RPC response, được trả lời 400, vì client chỉ gửi cho máy chủ này các request và notification, không gì khác.

Cả hai phiên bản giao thức được phục vụ ở đây giống hệt như qua đầu vào và đầu ra chuẩn. Một yêu cầu 2026-07-28 phản chiếu phần thân của nó trong các header truyền tải để một bên trung gian có thể định tuyến mà không cần phân tích phần thân: MCP-Protocol-Version mang phiên bản mà phần thân nêu, Mcp-Method mang phương thức nó gọi tên, và Mcp-Name mang đích, đối với các phương thức nhắm tới một đích theo tên. Một header không khớp với phần thân được trả lời 400. Một client 2025-06-18 mở đầu bằng bắt tay initialize, được trả lời mà không giữ trạng thái; nó có thể mang header phiên bản nêu phiên bản đó hoặc bỏ qua. Một yêu cầu nêu phiên bản mà máy chủ không hỗ trợ được trả lời 400 kèm danh sách hai phiên bản nó hỗ trợ, và yêu cầu nêu một phương thức nó không phục vụ được trả lời 404.

mcp.allowed_origins chỉ được tham chiếu khi yêu cầu mang header Origin, mà trên thực tế có nghĩa là một trình duyệt đã gửi nó: yêu cầu nêu một origin không có trong danh sách được trả lời 403, còn yêu cầu không mang header như vậy thì được phục vụ. Một client không phải trình duyệt không gửi header như vậy và không cần mục nào. Một client chạy trên trình duyệt luôn cần một mục: danh sách rỗng cho tới khi người vận hành viết nó, nên trước đó không có origin nào được chấp nhận và mọi yêu cầu từ trình duyệt đều được trả lời 403 — kể cả yêu cầu từ một trang được phục vụ tại chính địa chỉ của endpoint. Mục được so sánh chính xác với header, nên phải được viết đúng như trình duyệt gửi origin — một scheme chữ thường, ://, một host chữ thường và, khi không phải cổng mặc định của scheme, : cùng cổng, ví dụ https://app.example.com — và một mục có đường dẫn, có / ở cuối, không có scheme hoặc có chữ hoa sẽ bị từ chối khi cấu hình được tải, kèm tên mục đó, vì nó không bao giờ có thể khớp.

mcp.limits giới hạn lưu lượng được chấp nhận. Phần thân vượt quá max_body_bytes được trả lời 413 và không được đọc quá mức giới hạn. Một yêu cầu đến khi đã có max_concurrent_requests yêu cầu đang xử lý được trả lời 503 thay vì bị xếp hàng sau công việc mà nó không thấy được. Một bên gọi gửi quá requests_per_minute yêu cầu trong một phút được trả lời 429, chỉ tính riêng cho bên gọi đó, nên một bên gọi gửi dồn dập không làm tốn gì của bên khác. Giá trị mặc định của mỗi giới hạn được nêu cạnh khóa của nó trong tài liệu tham chiếu cấu hình, và không giới hạn nào có giá trị để tắt nó đi.

Một tiến trình, một workspace

Workspace mà một tiến trình phục vụ trả lời được cố định khi nó khởi động. --workspace-root chỉ định nó; biến AGGREGA_WORKSPACE_ROOT cung cấp nó khi không có cờ. Thư mục được chỉ định chính là gốc workspace, không tìm kiếm gì phía trên nó, và một thư mục không tồn tại sẽ bị từ chối, kèm tên của nguồn nào trong hai nguồn đã cung cấp nó và trích dẫn giá trị như đã nhận — bởi listener trước khi nó bind, và bởi server trên đầu vào và đầu ra chuẩn trong câu trả lời cho mọi lời gọi hoạt động trong workspace đó, như Which workspace a call is answered in trình bày — nhờ vậy một lần khởi chạy do client soạn thay vì gõ tay vẫn cho biết nó đã được trao gì. Khi không có cả hai, server trên đầu vào và đầu ra chuẩn xác định workspace từ thư mục nó được khởi động — nơi không có gì neo một workspace ở đó, mỗi câu trả lời liên quan đến workspace cho biết nó đã dùng thư mục nào, còn lần khởi chạy của gói desktop với thiết lập Workspace folder để trống thì thay vào đó từ chối lời gọi không tự chỉ định workspace, như Which workspace a call is answered in trình bày — và listener bị từ chối trước khi bind trừ khi một workspace được xác định ở đó — một tiến trình được truy cập qua HTTP trả lời những bên gọi không nhìn thấy máy, nên nó phục vụ workspace do người vận hành chọn thay vì bất kỳ thư mục nào nó tình cờ được khởi động. Để phục vụ nhiều dự án, hãy chạy một tiến trình cho mỗi gốc dự án.

Một lời gọi đến qua HTTP không thể tự chỉ định workspace. workspace_root và catalog_dirs bị từ chối, kèm tên đối số đã gửi, thay vì bị lặng lẽ bỏ qua: một đối số bị âm thầm bỏ qua trông với bên gửi giống hệt một đối số đã được chấp nhận. Các thư mục catalog được tìm kiếm bên cạnh workspace được phục vụ là thiết lập workspace.catalog_dirs riêng của workspace đó — hoặc, với một Release mà nó cấp các thư mục riêng trong workspace.releases, là thiết lập của Release đó — do người vận hành viết. Qua đầu vào và đầu ra chuẩn, cả hai đối số đều được chấp nhận, vì client đã khởi chạy server đang chạy trên chính máy của bên gọi. Ở đó, một mục catalog_dirs là tuyệt đối, hoặc tương đối so với gốc workspace mà một release tương đối được đọc từ đó — gốc được xác định trước tiên bởi workspace_root của chính lời gọi, bởi lần khởi chạy, hoặc bởi thư mục server được khởi động, và là gốc vẫn được đọc từ đó khi một Release được chỉ định tuyệt đối chuyển lời gọi sang workspace riêng của Release đó — chứ không phải so với thư mục server đang chạy, nếu đó là nơi khác.

Một đường dẫn mà lời gọi chỉ định cũng nằm trong workspace đó. Qua HTTP, một đối số đường dẫn được phân giải theo gốc workspace và bị từ chối nếu vươn ra ngoài nó — một đường dẫn tương đối leo ra khỏi workspace, một đường dẫn tuyệt đối chỉ đến nơi khác, và một đường dẫn tương đối dẫn ra khỏi workspace qua một liên kết đến tệp hoặc thư mục có ở đó, đều trả về một lỗi nêu tên đối số, không nêu gốc workspace lẫn nơi đường dẫn lẽ ra đã đến; một đường dẫn tương đối được trích dẫn lại đúng như bạn đã gửi. Mọi đối số đường dẫn được đánh giá theo nơi nó dẫn đến, theo định nghĩa “bên trong” mà The workspace boundary nêu, dù công cụ đọc hay ghi nó — thư mục mà gen-catalog ghi đầu ra vào, tài liệu mà edit-document ghi lại và thực thể mà pin ghi khóa bên cạnh cũng như một tài liệu mà công cụ đọc — nên một đường dẫn chưa được tạo nằm dưới một liên kết dẫn ra khỏi workspace bị từ chối như chính liên kết đó, không có gì được đọc hay ghi. Một release chỉ định một Release mà cấu hình của workspace được phục vụ nêu tên, dưới dạng build.authoring_release hoặc một khóa của workspace.releases, được truy cập qua cấu hình đó và được chấp nhận qua liên kết bất kể tệp của nó nằm ở đâu; không đối số nào khác có ngoại lệ này. Khi đường dẫn bạn muốn nằm trong workspace đó nhưng được viết dạng tuyệt đối, lời từ chối cho bạn cách viết tương đối theo gốc để gửi thay thế, nhờ vậy bên gọi đoán sai dạng được cho biết dạng đúng chứ không chỉ biết là sai. Điều đó áp dụng cho các đường dẫn mà lời gọi nêu làm đối tượng — tài liệu cần xác thực, Release cần build, thư mục mà một lần sinh ghi đầu ra vào — và cho những đường dẫn công cụ ghi vào không kém gì những đường dẫn nó đọc: bên gọi truy cập server qua mạng đang yêu cầu một máy mà nó không nhìn thấy đọc và ghi tệp, và workspace do người vận hành chọn là nơi việc đọc ghi đó được giới hạn. Qua đầu vào và đầu ra chuẩn, các đối số đường dẫn của mỗi công cụ giữ hợp đồng được mô tả dưới công cụ đó bên dưới, nơi một đường dẫn có thể là tuyệt đối và có thể trỏ ra ngoài workspace — người gọi sở hữu máy mà server đang chạy, nên giới hạn họ vào một thư mục do chính họ chọn chẳng mang lại gì. Hai công cụ mà bản thân thao tác chỉ trả lời về một tài liệu workspace chứa, insertion-point và edit-document, giữ điều đó trên cả hai phương thức truyền tải, và từ chối một tài liệu ngoài workspace dù nó được viết như vậy hay được truy cập qua một liên kết dẫn ra ngoài. Điều được chấp nhận qua đầu vào và đầu ra chuẩn là đường dẫn mà lời gọi chỉ định và không gì hơn. Những gì thao tác sau đó tự đọc và ghi được giữ trên cả hai phương thức truyền tải đúng như khi cùng lệnh đó được gõ trong terminal: một lần duyệt hay tra cứu không đọc qua liên kết dẫn ra khỏi workspace, một tệp mà một Release trong workspace hoặc Manifest của nó chỉ định bằng đường dẫn không được đọc từ ngoài workspace — và một tệp mà một Release được lời gọi chỉ định ngoài workspace nêu tên không được đọc từ ngoài thư mục chứa Release đó — và một tệp được ghi bên dưới một thư mục — workspace, hoặc thư mục mà lời gọi chỉ định — vẫn nằm trong thư mục đó. The workspace boundary đặt hai phương thức truyền tải bên cạnh dòng lệnh và trình soạn thảo, và nêu những gì vẫn còn mở qua đầu vào và đầu ra chuẩn: một tài liệu trong workspace bạn đã clone có thể dẫn dắt trợ lý chỉ định một đường dẫn ngoài workspace, và đường dẫn đó được chấp nhận như đã chỉ định.

Câu trả lời nói gì về hệ thống tệp của máy chủ

Qua HTTP, câu trả lời nêu một vị trí trong hệ thống tệp của máy chủ theo đường dẫn tương đối với gốc workspace, hoặc giữ kín vị trí đó. Một client đã khởi chạy máy chủ thì chạy ở cùng nơi máy chủ chạy, nên qua đầu vào và đầu ra chuẩn, mọi câu trả lời nêu mỗi vị trí đúng như thao tác đang giữ nó — tuyệt đối, nếu nó được giữ như vậy — và mỗi vị trí đều là nơi mà bên gọi đó vốn đã sở hữu. Một bên gọi kết nối tới listener không chọn vị trí nào trong số đó và không thể mở chúng, còn một máy chủ đã công bố chúng cho bên gọi ấy thì không thể thu hồi lại. Vì vậy, qua HTTP, câu trả lời cho bên gọi đó biết một trong hai điều về một vị trí:

  • Một vị trí bên trong workspace được nêu theo đường dẫn tương đối với gốc workspace — cùng dạng với đường dẫn bạn gửi, nên một tên đọc từ câu trả lời này có thể được gửi lại nguyên vẹn trong lần gọi tiếp theo. Một Release ở gốc là release.yaml, và lockfile của nó là release.lock.
  • Một vị trí bên ngoài workspace bị giữ kín, và chính gốc workspace cũng vậy. Trường đó không mang giá trị — nó là null hoặc bị lược bỏ, và trên attachment-container, nơi câu trả lời giữ nguyên dạng mà mọi bề mặt báo cáo, file được để trống — và một dấu đánh bên cạnh, đặt tên theo trường với hậu tố _withheld, cho biết nó bị giữ kín chứ không phải chưa được đặt: workspace_root_withheld bên cạnh workspace_root, file_withheld bên cạnh file. Dấu đánh chỉ xuất hiện ở nơi có thứ bị giữ kín. Gốc bị giữ kín vì một listener phục vụ đúng một workspace, nên vị trí của workspace đó không cho bạn biết điều gì cần thiết để nêu những gì nằm bên trong nó.

Việc một vị trí có nằm bên trong hay không được đánh giá theo cách nó được viết, không theo tệp mà nó trỏ tới. Một đường dẫn viết qua đích của một liên kết tượng trưng thay vì qua gốc mà máy chủ được khởi chạy trên đó, và một đường dẫn leo ra khỏi gốc rồi quay lại, đều được coi là bên ngoài workspace và bị giữ kín. Phép đánh giá này thiên về việc cho bạn biết ít hơn, không bao giờ thiên về việc nêu một vị trí bên ngoài workspace.

Qua HTTP, văn bản đọc được của câu trả lời tuân theo cùng quy tắc. Khi văn bản, một dòng chẩn đoán hoặc thông báo của một lỗi nêu một vị trí mà workspace chứa — gốc của nó hoặc bất cứ thứ gì bên dưới, một tệp cấu hình mà cấu hình của nó được đọc từ đó, một thư mục mà catalog của nó được đọc từ đó — vị trí đó được viết tương đối với gốc, hoặc hiển thị (location withheld) nếu nó nằm ngoài workspace hoặc chính là gốc. Văn bản mà câu trả lời soạn về workspace của chính nó gọi đó là workspace mà máy chủ này phục vụ. Một vị trí nằm ngoài tất cả những thứ đó mà một thao tác ghi vào thông báo sẽ không được nhận diện là vị trí, và đến với bạn đúng như nó được viết.

Các câu trả lời chịu ảnh hưởng của điều này, qua HTTP:

  • list-entities, list-releases, cache-status, registry-list, search, attach-candidates, connection-candidates, insertion-point, attachment-container, connection-at-position và edit-document giữ kín workspace_root. Các đường dẫn mà chúng vốn đã nêu tương đối với gốc — tệp nguồn của một thực thể, đường dẫn của một Release và lockfile của nó trong lockfiles, tài liệu mà một điểm chèn hoặc một chỉnh sửa nói tới, các tệp mà một chỉnh sửa đã ghi — hiển thị giống nhau trên cả hai phương thức truyền.
  • cache-status cũng giữ kín những gì nêu tên một plugin mà máy chủ đã nạp từ một tệp trên máy chủ của nó. Danh tính như vậy là null tại vị trí của nó trong provenance[].identities, mọi danh tính khác giữ nguyên vị trí, và mục đó được đánh dấu identities_withheld. note của một module đã biên dịch là một câu nêu các danh tính mà module được xây dựng cho, nên khi bất kỳ danh tính nào trong đó nêu tên một tệp như vậy, toàn bộ note bị lược bỏ và được đánh dấu note_withheld; digest của module vẫn còn đó. Một danh tính nêu một tham chiếu registry hoặc một thực thể Plugin được trả về đầy đủ, và một note chỉ nêu những thứ đó cũng vậy. label của một artifact nguồn là vị trí của nó trong bộ nhớ đệm, được viết từ host và đường dẫn của URL mà nó được phân giải từ đó, nên với một kho đọc từ hệ thống tệp của chính máy chủ — qua URL file:// hoặc một đường dẫn — label bị lược bỏ và được đánh dấu label_withheld, size và digest của nó vẫn còn đó, và một label nêu một host mạng được trả về đầy đủ. Văn bản của danh sách hiển thị (location withheld) ở nơi lẽ ra nó nêu một vị trí như vậy.
  • validate nêu target, và release đối với một Release, tương đối với gốc; với toàn bộ catalog, target là gốc và bị giữ kín. Một vị trí trong diagnostics hoặc notices tuân theo quy tắc cho văn bản.
  • build nêu release tương đối với gốc, và một lần build đã phân giải các phụ thuộc trước sẽ mang dependency_resolution như pull trả về. Một lần build được gửi write nêu thư mục nó đã ghi dưới dạng output_dir, hiển thị là dist — tương đối với gốc — và mỗi đường dẫn trong files là tương đối với thư mục đó. Một refusal, và mỗi mục trong findings của nó, nêu file của nó tương đối với gốc, hoặc giữ kín nếu tài liệu nằm ngoài workspace. advisories, deprecations, declined_external_inputs và mỗi message của refusal tuân theo quy tắc cho văn bản.
  • pull nêu release và lockfile tương đối với gốc. diagnostics và incomplete_external_inputs tuân theo quy tắc cho văn bản. source của mỗi mục resolved được trả về đầy đủ trên cả hai phương thức truyền: nó nêu những gì lần chạy đã làm, không bao giờ nêu một vị trí trên máy chủ.
  • describe nêu release của một Release tương đối với gốc, và file của một thực thể tương đối với gốc khi tài liệu của nó nằm trong workspace; một thực thể đọc từ thư mục catalog bên ngoài workspace có file bị giữ kín. mapping_diagnostics và deprecations tuân theo quy tắc cho văn bản.
  • lint nêu location.file của mỗi phát hiện tương đối với gốc, hoặc giữ kín nếu thực thể nằm ngoài workspace. message và suggest của một phát hiện tuân theo quy tắc cho văn bản.
  • pin nêu entity và lock tương đối với gốc, và pin mà một lần công bố mang theo cũng vậy.
  • gen-catalog nêu mỗi tệp liệt kê trong output tương đối với gốc.
  • import giữ kín workspace_root, và output_dir khi các bản nháp được ghi vào gốc đó; một thư mục bạn đã nêu trong output_dir được cho biết bằng tên tương đối với gốc. Mọi đường dẫn bản nháp trong written và drafts là tương đối với output_dir, nên nơi các bản nháp được ghi vẫn có trong câu trả lời trong cả hai trường hợp. message của một chẩn đoán, và params_summary, rationale và swap_hint của một quyết định, là văn bản do trình nhập soạn và tuân theo quy tắc cho văn bản.
  • config-show và plugin-list giữ kín nhiều hơn gốc, vì phần lớn những gì chúng báo cáo là cấu hình nêu các vị trí, như được trình bày trong Những gì listener không cho bạn biết về máy chủ của nó.
  • scaffold khi ghi một ví dụ sẽ nêu dir đúng như bạn đã gửi, tương đối với gốc, và mỗi đường dẫn trong files tương đối với thư mục đó; việc soạn bản nháp và liệt kê không nêu vị trí nào.
  • Các công cụ công bố, sign-artifacts, deprecate-artifact, get-schema, explain-error và describe-capabilities tự chúng không nêu vị trí nào trên máy chủ. Thông báo lỗi từ bất kỳ công cụ nào trong số đó tuân theo quy tắc cho văn bản: lời từ chối mà một workspace ngoại tuyến đưa ra nêu .aggrega-config.yaml của nó tương đối với gốc.
  • Một tham số đường dẫn bị từ chối vì vươn ra ngoài workspace sẽ bị từ chối mà không nêu gốc hay vị trí mà nó lẽ ra đã trỏ tới, như đã nói ở trên.

Một lần gọi kết thúc như thế nào

Đóng kết nối sẽ hủy lần gọi mà kết nối đó mang. Đó là tín hiệu hủy của phương thức truyền này: máy chủ coi việc bên gọi ngắt kết nối là hủy yêu cầu đó, dừng công việc đang làm và không ghi gì thêm cho nó. Ở đây không cần và không mong đợi thông điệp hủy — điều này ngược với đầu vào và đầu ra chuẩn, nơi không có luồng riêng cho từng yêu cầu để đóng và client kết thúc một lần gọi bằng cách nêu id của nó. Một thông điệp hủy nếu có đến qua HTTP sẽ được chấp nhận nhưng không kết thúc gì cả.

Dừng tiến trình sẽ xả listener. Một tín hiệu ngắt, hoặc một yêu cầu kết thúc từ trình giám sát hay container runtime, khiến listener ngừng nhận và để lần gọi đang được trả lời hoàn tất, trong một khoảng thời gian giới hạn, nên bên gọi đã yêu cầu điều gì đó trước khi dừng vẫn nhận được câu trả lời. Một lần gọi chưa hoàn tất trong khoảng thời gian đó sẽ mất kết nối. Yêu cầu dừng thứ hai sẽ kết thúc tiến trình ngay lập tức.

Liveness và readiness, trên một địa chỉ riêng

mcp.health.listen là nơi một trình giám sát hỏi xem tiến trình này có đang chạy không và có trả lời được một lệnh gọi không. Hãy cho nó một địa chỉ theo một trong hai dạng ở trên và một listener thứ hai sẽ trả lời GET /healthz và GET /readyz tại đó. Bỏ nó đi — đây là mặc định — thì không listener thứ hai nào được khởi động và không kiểm tra nào được trả lời ở đâu cả.

Hai câu trả lời nói những điều khác nhau, và sự khác biệt đó là lý do có hai. /healthz được trả lời 200 ngay từ lúc tiến trình chạy, đó là toàn bộ những gì liveness khẳng định: nó đang chạy, và một trình giám sát không nhận được câu trả lời nào thì nên khởi động lại nó. /readyz được trả lời 503 cho đến khi workspace mà tiến trình này phục vụ đã được phân giải và endpoint đã bind, và 200 từ đó trở đi — để một bộ cân bằng tải giữ lưu lượng lại cho đến khi tiến trình thực sự trả lời được một lệnh gọi, thay vì gửi yêu cầu đầu tiên vào một tiến trình vẫn đang khởi động. Mọi câu trả lời là một mã trạng thái với phần thân rỗng; không yêu cầu thông tin xác thực nào, và không gì bên gọi gửi đến được đọc.

Endpoint không bao giờ trả lời hai đường dẫn đó. GET /healthz và GET /readyz trên địa chỉ mà mcp.listen chỉ định được trả lời 404, đúng như mọi đường dẫn khác mà endpoint đó không phục vụ, dù có token hay không. Trả lời một probe ở đó sẽ trao cho bất cứ thứ gì chạm tới endpoint một cách miễn phí để biết tiến trình có đang chạy không, cùng với một cách miễn phí để bắt nó làm việc — trên một listener vốn từ chối mọi yêu cầu không mang thông tin xác thực.

Địa chỉ health đặt ở đâu là do bạn chọn, và nó không bị giới hạn như mcp.listen. Không địa chỉ nào bị từ chối cho nó. Hãy trỏ nó vào loopback hoặc một Unix socket, vì đó là mục đích của nó: một trình giám sát, một bộ cân bằng tải hoặc một container runtime chạy cạnh tiến trình này trên cùng máy chủ. Bất cứ thứ gì chạm tới được địa chỉ bạn chọn đều đọc được hai câu trả lời đó, nên một địa chỉ mà mạng mở chạm tới được sẽ công bố chúng ra mạng mở.

Không gì được phục vụ khi không có thông tin xác thực

Mọi yêu cầu gửi đến endpoint đều mang một thông tin xác thực, và đó là loại nào tùy thuộc vào việc một proxy phía trước đã kiểm tra nó hay chưa. Mặc định, đó là một bearer token mà chính máy chủ này xác minh, được mô tả trong phần còn lại của mục này. Đặt mcp.authorization.trusted_proxy thì thay vào đó nó là một header mà proxy đó đặt, được mô tả trong Đọc bên gọi từ một proxy phía trước — nơi không token nào được đọc cả. Không dạng nào phục vụ một yêu cầu không xuất trình gì.

Mặc định, máy chủ tự kiểm tra một bearer token. Nó đọc token từ header Authorization và chỉ chấp nhận khi chữ ký được xác minh với một khóa mà máy chủ ủy quyền công bố, token ghi mcp.authorization.issuer là bên phát hành, nó ghi mcp.authorization.resource của chính triển khai này trong số các audience, nó nằm trong khoảng thời gian hiệu lực, và nó cho biết ai đã xuất trình nó. Một token không đạt bất kỳ điều nào trong số đó được trả lời 401, với error="invalid_token" được thêm vào cùng challenge mà một bên gọi không mang gì nhận được — và câu trả lời giống hệt nhau bất kể kiểm tra nào đã từ chối nó, nên bên gọi biết rằng nó cần một token khác chứ không biết phần nào của token đã gửi bị sai. Chỉ các thuật toán chữ ký bất đối xứng được chấp nhận: một token không ký, và một token ghi một thuật toán đối xứng, bị từ chối trước khi bất cứ thứ gì được đọc từ nó.

Một token có thể cho biết nó là loại token gì, và bốn dạng được chấp nhận. Một JWT có thể mang header typ ghi loại của chính nó. Máy chủ này chấp nhận at+jwt và application/at+jwt, hai cách viết được đăng ký cho access token; JWT, chỉ nói rằng token là một JWT; và một token không khai báo loại nào. Mọi thứ khác được trả lời 401 đúng như mọi token bị từ chối khác. Tập hợp này cố định và không thiết lập nào mở rộng hay thu hẹp nó, vì dạng nào xuất hiện ở đó do máy chủ ủy quyền đã tạo token quyết định chứ không phải triển khai nhận nó. Việc chấp nhận JWT đồng nghĩa là chỉ riêng loại được khai báo không còn phân biệt được access token với identity token — kiểm tra audience mới phân biệt chúng, và đó là lý do kiểm tra đó là kiểm tra chịu lực: audience của một identity token là client mà nó được cấp cho, không bao giờ là mcp.authorization.resource của chính triển khai này, nên một token được cấp cho bất cứ thứ gì khác ngoài triển khai này đều bị từ chối bất kể nó tự gọi mình là gì.

Điều đó chấp nhận những máy chủ ủy quyền nào. Microsoft Entra ID cấp access token có loại JWT. Keycloak cấp at+jwt, và JWT khi chế độ tương thích OpenID Connect của nó được bật. Auth0 cấp JWT theo profile token riêng và at+jwt theo profile RFC 9068. Một token từ bất kỳ máy chủ nào trong số đó đều đạt kiểm tra này dù nó mang dạng nào trong hai dạng. Okta không được hỗ trợ: access token của nó khai báo một loại riêng không thuộc bốn dạng trên, nên máy chủ này từ chối chúng.

Một token bị từ chối để lại lý do trên luồng lỗi riêng của máy chủ. Bên gọi chỉ được cho biết rằng thứ nó xuất trình không được chấp nhận; tiến trình phục vụ ghi một dòng nêu kiểm tra đã từ chối token — audience, bên phát hành, khoảng thời gian hiệu lực, chữ ký, định danh khóa, loại được khai báo, và từng kiểm tra còn lại. Dòng đó là cách để một triển khai từ chối mọi yêu cầu có thể được chẩn đoán bởi người vận hành nó chứ không chỉ bởi người đang gọi nó. Nó không chứa phần nào của token. Một yêu cầu không xuất trình thông tin xác thực nào thì không ghi dòng nào, vì bị challenge là cách một client biết ngay từ đầu nơi để lấy token, nên đó là việc đầu tiên mà mọi client hoạt động đúng đắn đều làm.

Token thuộc về header và không ở đâu khác. Một token được gửi dưới dạng tham số truy vấn access_token được trả lời 400 và không bao giờ được đọc, vì một địa chỉ được ghi lại bởi mọi log proxy, lịch sử trình duyệt và header referrer mà yêu cầu đi qua, nên một token đến theo cách đó đã bị lộ. Máy chủ không bao giờ ghi token vào log, không bao giờ gửi token đi đâu, và không bao giờ lấy hay trao đổi token thay cho bên gọi: nó đọc thứ được xuất trình, quyết định, và không giữ lại gì. Chủ thể mà token ghi được lưu lại và không được so sánh với gì cả.

Các khóa xác minh đến từ máy chủ ủy quyền, hoặc từ một tệp bạn chỉ định. Khi mcp.authorization.jwks_file không được đặt, máy chủ đọc metadata của máy chủ ủy quyền tại địa chỉ well-known của nó, đi theo jwks_uri được công bố ở đó, và giữ các khóa nó tìm thấy; một token được ký bởi một định danh khóa mà các khóa đó không có sẽ gây ra một lần đọc lại, và không quá một lần trong một khoảng ngắn, nên một bên gọi gửi các định danh khóa bịa đặt không thể gây ra một yêu cầu đi ra cho mỗi yêu cầu. Đọc chúng từ máy chủ ủy quyền cần một địa chỉ khóa https, hoặc một địa chỉ http thường trên máy này: một jwks_uri là http thường trên máy chủ khác không bao giờ được hỏi, và một chuyển hướng sẽ đưa một trong hai lần đọc đến http thường trên máy chủ khác không được đi theo, vì bất kỳ ai nằm trên một đường dẫn không được bảo vệ đến các khóa đều có thể trả lời bằng khóa của riêng họ. Một token cần các khóa đó khi ấy được trả lời 503, đúng như với các khóa không đọc được, và dòng mà máy chủ ghi cho yêu cầu đó nói rằng lần đọc bị từ chối vì http thường chứ không phải là không liên lạc được với máy chủ ủy quyền — cách khắc phục nằm ở phía máy chủ ủy quyền, vốn phải công bố metadata và khóa qua https. Khi jwks_file được đặt, các khóa được đọc từ tệp đó và máy chủ ủy quyền không bao giờ được liên lạc — đó là điều một workspace khai báo offline: true cần, và một workspace như vậy bị từ chối trước khi listener của nó bind trừ khi tệp được chỉ định. Khi các khóa hoàn toàn không đọc được, các yêu cầu được trả lời 503 không kèm challenge: không có gì bên gọi xuất trình bị coi là thiếu sót, nên gửi nó đi lấy token khác cũng không giúp được gì.

Câu trả lời duy nhất được đưa ra mà không đòi thông tin xác thực là tài liệu siêu dữ liệu của tài nguyên được bảo vệ. Một client phải đọc nó trước khi có thể giữ một token, nên đòi token ở đó sẽ đóng lại lối vào duy nhất. Nó được trả lời tại /.well-known/oauth-protected-resource, và — khi địa chỉ mà mcp.authorization.resource chỉ định có đường dẫn riêng — cũng tại đường dẫn well-known đó với đường dẫn ấy được nối thêm vào. Đó là hai nơi một client tìm đến, và dạng có nối thêm là địa chỉ mà challenge nêu ra. Tài liệu mang địa chỉ đó làm tên tài nguyên của triển khai này, mcp.authorization.issuer làm máy chủ ủy quyền để lấy token, header làm cách duy nhất để trình token, và ba tên scope dưới đây.

Issuer là một địa chỉ https, trừ khi máy chủ ủy quyền chạy trên chính máy này. http thường được chấp nhận cho một issuer tại localhost, 127.0.0.1 hoặc ::1, đó là dạng của một bài kiểm thử cục bộ với máy chủ ủy quyền cục bộ; một issuer http thường trên bất kỳ host nào khác bị từ chối trước khi listener bind, và lời từ chối nêu mcp.authorization.issuer và yêu cầu một địa chỉ https. Điều đó đúng trong mọi chế độ — khi khóa được đọc từ issuer, khi dùng mcp.authorization.jwks_file, và khi có proxy phía trước — vì mọi chế độ đều công bố issuer trong tài liệu này: một client làm theo nó sẽ chạy luồng ủy quyền với địa chỉ đó, nên qua http thường, mã ủy quyền và token nó lấy được sẽ đi qua mạng mà không được bảo vệ, dù máy chủ này có bao giờ đọc khóa từ đó hay không. Khi nó thực sự đọc khóa từ đó, bất kỳ ai nằm trên đường đi ấy cũng có thể trả lời bằng khóa của riêng họ, và mọi token ký bằng các khóa đó sẽ được chấp nhận.

Các tên scope mà triển khai này công bố là aggrega:read, aggrega:workspace-write và aggrega:registry-write. Đó là các tên cần đăng ký tại máy chủ ủy quyền và là các tên client yêu cầu từ nó, và challenge mà một caller bị từ chối nhận được nêu aggrega:read là scope cần lấy trước tiên. Mỗi scope cho phép gì — và giới hạn thứ hai, giới hạn mà triển khai này tự đặt cho mình — được trình bày tại Caller có thể chạm tới những gì bên dưới.

Đọc caller từ một proxy phía trước

Khi một proxy phía trước đã xác thực token, mcp.authorization.trusted_proxy bảo máy chủ này đọc caller từ proxy đó thay vì kiểm tra token lần thứ hai. Hãy cung cấp principal_header, header mà proxy đó đặt để cho biết caller là ai, và tùy chọn scopes_header, một header thứ hai mang các scope của caller đó, phân tách bằng dấu cách. Mỗi giá trị là một tên header HTTP như X-Forwarded-User, không có dấu cách hay dấu hai chấm; một tên ở bất kỳ dạng nào khác bị từ chối khi cấu hình được nạp, kèm tên khóa, và một principal_header rỗng cũng vậy — hãy bỏ khối này đi để tắt chế độ này. Hai header đó là những header duy nhất được đọc: không header địa chỉ chuyển tiếp nào và không header nào khác tham gia. Một request đến mà không có principal header được trả lời 401, và không token nào được đọc trong chế độ này — một request mang token mà máy chủ này lẽ ra đã từ chối vẫn được phục vụ khi có principal header, và một request mang token mà máy chủ này lẽ ra đã chấp nhận vẫn bị từ chối khi thiếu header đó.

Chế độ đó chỉ được chấp nhận trên loopback hoặc Unix socket, và tiến trình bị từ chối trước khi bind ở bất kỳ nơi nào khác. Một header đáng tin cậy đúng khi không gì ngoài proxy có thể đặt nó. Trên một địa chỉ mà mạng chạm tới được, bất cứ thứ gì cũng có thể đặt nó — nên một listener ở chế độ này trên địa chỉ như vậy sẽ cho phép mọi caller tự xưng là bất kỳ ai nó muốn. Lời từ chối nêu cả hai thiết lập xung đột, để bạn có thể gỡ bỏ nó bằng cách đổi địa chỉ hoặc xóa khối này.

Điều proxy khẳng định là điều máy chủ này tin, và đó là thỏa thuận. Trong chế độ này, máy chủ không kiểm tra chữ ký nào và không so sánh caller được khẳng định với bất cứ thứ gì, đúng như nó không so sánh subject của token với bất cứ thứ gì. Việc proxy có xác thực những gì nó chuyển tiếp hay không, và việc có thứ gì có thể chạm tới listener đó mà không đi qua proxy hay không, là việc triển khai phải làm đúng; sự giới hạn ở trên là điều giúp có thể làm đúng, chứ không phải bảo đảm rằng chúng đã được làm đúng.

Đặt mcp.authorization.trusted_proxy không loại bỏ các yêu cầu khác. issuer và resource vẫn cần thiết, vì tài liệu siêu dữ liệu vẫn được công bố và challenge vẫn nêu nó — một client phía sau proxy vẫn phải biết lấy token mà proxy sẽ kiểm tra ở đâu. Cũng vì lý do đó, issuer vẫn là một địa chỉ https trừ khi nó chạy trên máy này: client đó lấy token từ issuer, nên một issuer http thường trên host khác bị từ chối trước khi listener bind trong chế độ này đúng như trong mọi chế độ khác, dù máy chủ này không đọc gì từ nó.

Caller có thể chạm tới những gì

Hai giới hạn quyết định những gì một caller chạm tới qua HTTP, và chúng do những người khác nhau đặt ra. Thông tin xác thực của chính caller là giới hạn thứ nhất; những gì máy chủ này có mang hay không là giới hạn thứ hai. Cả hai được đọc trước khi bất cứ thứ gì chạy, từ một khai báo mà mỗi thao tác đưa ra về chính nó, và chúng đến với client ở những nơi khác nhau: danh sách tool cho thấy những gì máy chủ này mang và công bố, còn câu trả lời mà mỗi lời gọi nhận được cho thấy thông tin xác thực cho phép những gì.

Mỗi thao tác khai báo tác động của nó đi xa đến đâu, và có bốn loại, rộng nhất ở cuối:

  • Không chạm tới gì — đọc một định nghĩa, kiểm tra những gì một Release ghim, render artifact trong bộ nhớ và trả chúng lại. Nó không để lại gì: không gì được ghi, và câu trả lời là toàn bộ những gì nó tạo ra.
  • Chạm tới workspace — ghi bên trong workspace mà tiến trình này phục vụ: lockfile của một Release, bộ nhớ đệm artifact, các thực thể được sinh ra, một tài liệu đã chỉnh sửa.
  • Chạm tới một registry — công bố, ký, hoặc gắn một dấu thu hồi vào thứ đã được công bố. Điều nó thay đổi là những gì mọi bên tiêu thụ registry đó resolve, và không phần nào có thể thu hồi lại từ bất kỳ ai đã tải về.
  • Chạm tới máy — thay đổi những gì mọi workspace trên host dùng chung, trong đó có kho module đã biên dịch, tệp cấu hình chung cho tất cả, và kho thông tin xác thực. Một bộ nhớ đệm mà một dự án riêng lẻ giữ trong thư mục cache của chính nó không thuộc loại này, và cache-status báo cáo mỗi bộ nhớ đệm nó liệt kê mang loại nào trong số này.

Loại là thuộc tính của thao tác chứ không phải của tool cung cấp nó, và nó bao quát những gì thao tác để lại — chứ không phải nơi một bề mặt đặt câu trả lời nó trả về. Render một Release tạo ra artifact làm câu trả lời, nên nó không chạm tới gì; một dòng lệnh sau đó lưu các artifact đó vào thư mục bạn chỉ định là đang chuyển giao câu trả lời đó chứ không chạm xa hơn. Nếu hiểu theo cách ngược lại, mọi thao tác trả lời bằng nội dung sẽ mang loại của bất kỳ bề mặt nào tình cờ lưu nó, và loại sẽ không còn là thuộc tính của thao tác nữa. Cũng vì lý do đó, describe đọc một thực thể bằng tham chiếu registry của nó không chạm tới gì: nó liên hệ registry đó để lấy câu trả lời và không để lại gì, trong registry hay trên máy này, và những registry nào nó có thể liên hệ được trình bày tại Một lời gọi dùng những thông tin xác thực nào. Một lời gọi vẫn có thể chạm xa hơn loại của thao tác, khi chính lời gọi yêu cầu ghi: một bản build được gửi write lưu artifact vào workspace mà máy chủ này phục vụ, nên lời gọi đó chạm tới workspace, cũng như một bản build resolve các phụ thuộc trước.

Một scope cho phép một loại, và mỗi scope ghi bao hàm scope đọc. aggrega:read cho phép thao tác không chạm tới gì. aggrega:workspace-write cho phép thao tác chạm tới workspace, và bao hàm scope đọc. aggrega:registry-write cho phép thao tác chạm tới một registry, và cũng bao hàm scope đọc. Vì vậy client yêu cầu máy chủ ủy quyền cấp scope ghi nó cần mà không phải yêu cầu thêm scope đọc.

Không scope nào cho phép loại máy, và không thiết lập nào thêm một scope như vậy. Các thao tác thuộc loại đó chỉ được mang bởi những công cụ chạy một lệnh aggrega trong một tiến trình riêng, và một máy chủ được truy cập qua HTTP hoàn toàn không cung cấp công cụ nào trong số đó, vì lý do đã nêu tại Truy cập máy chủ qua HTTPS ở trên. Hãy chạy chúng tại một terminal trên máy chủ.

Danh sách công cụ hiển thị mọi công cụ mà máy chủ này mang và công bố, bất kể thông tin xác thực gọi đến giữ những scope nào, và thông tin xác thực quyết định lời gọi được chạy công cụ nào trong số đó. describe-capabilities lập chỉ mục và định nghĩa đúng tập hợp đó. Một lời gọi mà thông tin xác thực không cho phép sẽ được trả lời 403 kèm error="insufficient_scope" trong challenge, nêu tên scope duy nhất sẽ cho phép nó, và không có gì lời gọi yêu cầu đã được chạy. Lời từ chối đó chính là lời từ chối mà step-up của giao thức đáp lại: một client triển khai step-up sẽ yêu cầu bạn đăng nhập lại cho scope mà challenge nêu tên. Danh sách không thay đổi theo thông tin xác thực, nên một client đã đăng nhập lại thì đã giữ đúng scope cần thiết. Một thông tin xác thực không mang scope nào trong ba scope nhận được cùng danh sách công cụ đó và không thể gọi công cụ nào trong đó, kể cả describe-capabilities.

Bản build là trường hợp đáng lưu ý. Bản thân nó không thay đổi gì nên chỉ cần aggrega:read, nhưng một bản build có ghi thì cần aggrega:workspace-write: một bản build được gửi write sẽ lưu các artifact của nó vào dist/ tại gốc workspace, và một bản build phân giải các phụ thuộc trước sẽ ghi lockfile — dù lời gọi yêu cầu điều đó bằng auto_pull hay do thiết lập auto_pull của chính workspace. Công cụ này được liệt kê cho một bên gọi có scope đọc như mọi công cụ khác, và các bản build chỉ ở trong bộ nhớ thực sự khả dụng cho bên gọi đó; điều bị từ chối, kèm tên aggrega:workspace-write, là lời gọi có ghi.

Một client không step-up vẫn có thể được cấp các scope ghi, và việc này được giải quyết tại máy chủ ủy quyền. Người vận hành máy chủ ủy quyền đặt các scope ghi làm scope mặc định cho client đó — những scope được đưa vào mọi token cấp cho client đó, dù client có yêu cầu hay không — nên token mà lần đăng nhập đầu tiên nhận được đã mang sẵn chúng. Một client tự đăng ký lại với máy chủ ủy quyền mỗi lần kết nối thì mỗi lần là một client mới ở đó, và thiết lập đặt cho một lần đăng ký trước không được giữ lại; với client như vậy, thiết lập có hiệu lực là các scope mặc định mà máy chủ ủy quyền cấp cho mọi client nó đăng ký. Cái giá là mọi lần đăng nhập qua client đó khi ấy đều mang quyền ghi, dù công việc đang làm có cần hay không — và khi các scope mặc định là những scope được cấp lúc đăng ký, mọi client đăng ký theo cách đó cũng mang quyền đó. Chỉ đặt làm mặc định scope ghi mà công việc đó cần: aggrega:workspace-write và aggrega:registry-write cho phép các loại khác nhau, và không scope nào bao hàm scope kia.

mcp.deny_reach là nơi người vận hành máy chủ này rút một loại khỏi nó, và đây là một trong hai thiết lập làm ngắn danh sách công cụ. Hãy liệt kê các loại — none, workspace, registry, machine — mà máy chủ này không mang, và mọi công cụ chạm tới một trong các loại đó sẽ vắng mặt khỏi danh sách công cụ của mọi bên gọi và khỏi describe-capabilities bất kể token của bên gọi nói gì, và bị từ chối nếu vẫn được gọi, với một lỗi nêu tên thiết lập này. Đây là giới hạn của chính máy chủ chứ không phải của bên gọi, nên không thông tin xác thực nào gỡ bỏ được nó và lời từ chối không kèm challenge: một máy chủ chỉ nhằm phục vụ thao tác đọc thì liệt kê workspace, registry và machine ở đây, và khi đó không thể publish ngay cả cho một bên gọi có token mang cả ba scope. Nếu bỏ qua thiết lập này, vốn là mặc định, máy chủ này không rút loại nào, nên lời gọi chạm tới loại nào do chính các scope của bên gọi quyết định. Việc nêu machine được chấp nhận và không thay đổi gì, vì ngay từ đầu không có gì thuộc loại đó được cung cấp ở đây. Một giá trị không thuộc bốn giá trị trên sẽ bị từ chối khi tải cấu hình, thay vì bị bỏ qua — một người vận hành viết sai tên loại là đã yêu cầu một giới hạn, và việc âm thầm phục vụ mà không có giới hạn đó là cách đáp sai.

mcp.announce_tools là thiết lập còn lại làm ngắn danh sách công cụ, và hai thiết lập này không phải cùng một giới hạn. deny_reach rút một khả năng: một thao tác thuộc loại được nêu ở đó hoàn toàn không được mang ở đây, đối với bất kỳ ai. announce_tools chỉ rút một lời công bố: những công cụ nó bỏ ra vẫn là khả năng mà máy chủ này có, và điều nó đáp ứng là giới hạn riêng của một client về số công cụ client đó sẽ đăng ký. Khi cả hai được đặt, việc rút khả năng thắng, nên một công cụ thuộc loại bị rút vẫn vắng mặt dù announce_tools có nêu tên nó thế nào, và lời từ chối mà bên gọi gặp sẽ nêu việc rút khả năng. Không có gì làm ngắn danh sách đọc các scope của bên gọi: một scope mà bên gọi thiếu sẽ từ chối một lời gọi và không bao giờ loại một công cụ khỏi danh sách. Thu hẹp những gì máy chủ công bố trình bày phần còn lại.

Một lệnh gọi sử dụng thông tin xác thực nào

Ký không cần khóa qua một listener lấy danh tính từ identity_token mà lệnh gọi mang theo, và không từ nguồn nào khác. Một token được gửi trong lệnh gọi là thông tin xác thực mà bên gọi nắm giữ: họ phải tự lấy nó, nó gắn với họ, và chữ ký nó tạo ra có thể quy cho họ. Mọi nơi khác mà một danh tính có thể đến từ đó đều thuộc về người đã khởi động tiến trình này, vì vậy trên kênh truyền này, quá trình phân giải được trao một môi trường không trả lời gì cả. AGGREGA_IDENTITY_TOKEN và SIGSTORE_ID_TOKEN trong môi trường của máy chủ không được đọc, và endpoint OIDC của GitHub Actions có sẵn trong môi trường không được truy cập. Chúng nằm ngoài tầm với chứ không chỉ là không được khuyến khích — quá trình phân giải không có gì để tìm thấy. Một lệnh gọi không gửi identity_token sẽ bị từ chối, và lời từ chối nêu identity_token là thứ cần gửi, không nêu biến hay endpoint nào: một bên gọi không ngồi trước bàn phím của máy này thì không thể export gì ở đây, nên nêu ra một biến sẽ là bảo họ sắp đặt một thứ không thể thay đổi câu trả lời.

Không thể chọn một khóa ký được lưu trên máy này, theo cả hai cách. key_path bị từ chối trước khi bất cứ thứ gì được phân giải, và nó không có trong các lược đồ đối số mà publish-entity, sign-artifacts và deprecate-artifact công bố ở đây, nên bên gọi không bao giờ được đưa ra một đối số không thể thành công. Khóa ký mà chính cấu hình của workspace được phục vụ nêu ra cũng không được truy cập — signing.key_path, dù nó được đặt cho toàn bộ workspace, đặt cho một registry, hay được cung cấp từ môi trường. Một lý do bao gồm cả hai: đường dẫn khóa không phải là thông tin xác thực, nó là một cái tên cho một bí mật mà máy chủ này nắm giữ. Bên gọi cung cấp nó không chứng minh được gì, bất kỳ ai truy cập được địa chỉ này cũng có thể cung cấp cùng cái tên đó, và chữ ký tạo ra sau đó sẽ nói rằng người vận hành đã bảo chứng cho artifact chứ không phải bên gọi. Đóng đối số trong khi để ngỏ cấu hình sẽ là đóng một cánh cửa dẫn vào căn phòng mà cánh cửa kia vẫn mở. Vì vậy, ký bằng khóa không thể truy cập qua một listener: chỉ một token được gửi trong lệnh gọi mới ký.

fulcio_url, rekor_url và timestamp_url không bị ảnh hưởng và vẫn có trên cả hai kênh truyền. Chúng nêu tên các dịch vụ cần liên hệ chứ không phải thứ gì máy này nắm giữ, nên một bên gọi không thể chọn khóa vẫn ký với các endpoint mà bản triển khai này cấu hình.

Một listener khởi động trên một workspace có nêu khóa ký sẽ thông báo điều đó một lần, khi khởi động. Tiến trình ghi một dòng trên luồng lỗi của chính nó, nêu tên thiết lập và cho biết bên gọi truy cập listener này không thể sử dụng khóa đó — để người vận hành biết điều này từ tiến trình họ khởi động chứ không phải từ một chữ ký họ không ngờ tới. Một workspace không nêu khóa nào thì không tạo ra dòng như vậy, vì không có gì để nói về nó. Dòng này mang tên của thiết lập, không mang khóa cũng như bất cứ thông tin gì về tệp mà nó trỏ tới.

Qua đầu vào và đầu ra chuẩn, không điều nào ở trên áp dụng. Ở đó môi trường được đọc và key_path chọn một khóa lưu trên máy này, vì client đã khởi chạy máy chủ này đang chạy trên chính máy của bên gọi, và những gì tiến trình đó truy cập được là của chính bên gọi để sử dụng.

Đọc một entity theo tham chiếu registry của nó sẽ liên hệ một registry, bằng thông tin đăng nhập của chính host này, và qua một listener thì chỉ một registry mà workspace được phục vụ đã được cấu hình. describe khi được gửi một tham chiếu oci:// làm name sẽ đọc entity được công bố tại tọa độ đó — cùng thao tác đọc mà aggrega inspect thực hiện — từ một registry mà tham chiếu nêu ra, dùng thông tin đăng nhập host này đã có cho registry đó. Lệnh gọi không mang thông tin xác thực nào, và describe cũng không nhận. Qua HTTP, registry phải là một registry mà workspace được phục vụ đã được cấu hình: host mà default_registry của nó nêu, hoặc một host được liệt kê trong registries, so sánh chính xác và kèm cả cổng. Một tham chiếu tới bất kỳ host nào khác — kể cả một địa chỉ trên máy này — bị từ chối trước khi host đó được liên hệ, và lời từ chối nêu tên host, nên bên gọi không thể trỏ máy chủ này tới một đích tùy ý. Những gì vẫn truy cập được là có chủ ý: bên gọi có aggrega:read có thể đọc bất cứ thứ gì thông tin đăng nhập của host này đọc được trên một registry mà workspace đã cấu hình, cũng chính là những gì một người ngồi tại terminal của host này đọc được. Qua đầu vào và đầu ra chuẩn, tham chiếu tới bất kỳ registry nào cũng được đọc, như tại dòng lệnh. Việc mô tả một entity theo tên trong catalog không bị ảnh hưởng.

Một lệnh gọi registry dùng kho thông tin xác thực của người dùng hệ điều hành mà tiến trình này chạy dưới danh nghĩa, giống hệt như cùng lệnh gọi đó tại một terminal trên host này. Không có nguồn thông tin xác thực riêng cho từng workspace và không có thiết lập nào thêm một nguồn như vậy, đó là lý do registry-list báo cáo trạng thái thông tin xác thực của một host theo cùng một cách trong mọi workspace trên máy này. Một bản triển khai muốn các workspace khác nhau giữ thông tin xác thực registry khác nhau sẽ chạy chúng dưới các người dùng hệ điều hành khác nhau — mỗi workspace một tiến trình, mỗi tiến trình khởi động dưới người dùng riêng. Sự tách biệt đến từ đó, và việc sắp đặt nó là trách nhiệm của người vận hành.

Những gì máy chủ ghi lại

Mỗi yêu cầu mà endpoint này trả lời để lại một dòng trên luồng lỗi của tiến trình, và dòng đó là một đối tượng JSON duy nhất. Dòng đó chứa time lúc nó được ghi và một request_id mà tiến trình này tạo ra cho lời gọi và không gửi lại cho bên gọi; subject và issuer như thông tin xác thực được xuất trình đã khẳng định, cùng client_id nếu thông tin xác thực có nêu; workspace_root, workspace mà tiến trình này phục vụ; method, và target khi phương thức nhắm tới một thứ theo tên; reach, loại mà thao tác khai báo, và reach_escalated_to khi lời gọi vươn xa hơn mức đó; outcome; duration_ms; và transport. Một trường không có gì để nói sẽ bị bỏ đi thay vì được ghi rỗng, nên việc thiếu client_id nghĩa là thông tin xác thực không nêu client nào, và việc thiếu reach_escalated_to nghĩa là lời gọi vươn tới đúng những gì thao tác của nó khai báo.

outcome cho biết lời gọi đã kết thúc ra sao, và các giá trị đều khác nhau để bạn có thể đếm riêng từng loại. ok đã chạy và thành công. tool-failure đã chạy và trả về được đánh dấu là một lỗi mà bên gọi có thể sửa — một lời gọi máy chủ này đã phục vụ chứ không phải đã từ chối, nên nó không thuộc về các lần từ chối của bạn. error là một lần từ chối được trả về dưới dạng phong bì lỗi giao thức. unauthenticated, forbidden và rate-capped là thông tin xác thực, giới hạn về nguồn gốc hoặc phạm vi, và giới hạn tần suất theo từng bên gọi từ chối một yêu cầu. cancelled là một bên gọi đã đóng kết nối trước khi được trả lời.

Lý do một thông tin xác thực bị từ chối là một trường của chính dòng đó chứ không phải một dòng riêng. Một yêu cầu bị từ chối để lại một bản ghi như mọi yêu cầu khác, với refusal nêu bước kiểm tra đã từ chối nó. Không có thông tin xác thực nào, dù chỉ một phần, xuất hiện trong bất kỳ dòng nào — kể cả khi bị từ chối lẫn khi lời gọi được phục vụ.

Một bên gọi không xuất trình gì cả thì không để lại dòng nào. Bị yêu cầu xác thực là cách một client biết nơi lấy token, nên đó là việc đầu tiên mọi client hoạt động đúng đắn đều làm, và một dòng cho mỗi lần như vậy sẽ vùi lấp những lần từ chối có ý nghĩa. Một yêu cầu nêu một đường dẫn hoặc một phương thức mà endpoint này không phục vụ cũng không để lại dòng nào: cả hai đều được giải quyết trước khi đọc bất cứ điều gì về bên gọi, nên việc dò quét địa chỉ không ghi gì vào nơi thu thập luồng.

Trace context mà client gửi được sao chép nguyên văn vào dòng. traceparent, cùng tracestate và baggage bên cạnh nếu chúng cũng được gửi, được chuyển qua đúng như khi nhận, để nơi thu thập luồng này có thể nối nó với các bản ghi riêng của bên gọi. Một yêu cầu không gửi trường nào, hoặc gửi một trường không phải W3C trace context hợp lệ, tạo ra một dòng không có các khóa đó: không có gì được bịa ra, và không có gì bị thay đổi trên đường đi.

Tiến trình ghi lại vòng đời của chính nó theo cùng định dạng và trên cùng luồng, mỗi dòng như vậy nêu một event ở chỗ dòng yêu cầu nêu một phương thức và một bên gọi: startup khi bắt đầu, listening cùng địa chỉ nó đã gắn, startup-refused cùng lý do một lần khởi chạy bị từ chối trước khi phục vụ, signing-key-ignored khi workspace nó phục vụ nêu một khóa ký mà không bên gọi nào tới listener này có thể dùng, docs-bundle cùng kết quả của việc lấy gói tài liệu, và shutdown khi lần chạy kết thúc. Kiểm tra sự có mặt của event là cách phân biệt hai loại dòng.

Bạn thu thập tất cả từ luồng lỗi của tiến trình, và đó là toàn bộ cách chuyển giao. Không có exporter nào để cấu hình, không có tệp nào để đặt tên, và không có thiết lập nào để bật, tắt hay chuyển hướng bất kỳ phần nào: bất cứ thứ gì giám sát tiến trình này — một container runtime, một trình quản lý dịch vụ, một công cụ chuyển log — là thứ thu thập luồng đó, và là nơi bạn truy vấn nó sau này. Qua đầu vào và đầu ra chuẩn, cùng luồng đó mang văn bản dễ đọc thay thế, vì client đọc nó đã khởi chạy tiến trình và nằm trên cùng máy.

Không phần nào trong đó được gửi tới bên gọi. Máy chủ không phát hành luồng log nào qua giao thức trên cả hai phương thức truyền tải, và một yêu cầu mang trường mức log theo từng yêu cầu của giao thức được trả lời y hệt như một yêu cầu không mang trường đó: những gì được ghi lại ở đây thuộc về người vận hành, và chỉ đi tới luồng của người vận hành.

Máy chủ cho mô hình biết gì khi kết nối

Máy chủ cung cấp một khối hướng dẫn cho mô hình, mà client của bạn có thể đưa cho mô hình trước lần gọi đầu tiên. Một client dùng 2026-07-28 đọc nó từ câu trả lời server/discover; một client dùng 2025-06-18 đọc nó từ phản hồi cho bước bắt tay initialize. Đó là cùng một văn bản trên cả hai đường, giống nhau từng byte, và là cùng một văn bản cho mọi client kết nối tới một tiến trình: không có gì trong đó được thương lượng, và không có gì được suy ra từ những gì client gửi hay từ thông tin xác thực nó xuất trình, nên những gì mô hình được cho biết khi kết nối không thay đổi giữa các phiên hay giữa các client.

Có hai điều thay đổi, và không điều nào là client. Đoạn kết được soạn cho giao thức truyền tải mà tiến trình phục vụ, nên một máy chủ nói qua đầu vào và đầu ra chuẩn và một listener trao cho mô hình đoạn kết khác nhau. Và khi gói desktop đã khởi chạy máy chủ đến từ một bản phát hành khác với tệp thực thi aggrega mà nó khởi chạy, phần hướng dẫn mở đầu bằng một câu nói rõ điều đó, nêu tên cả hai phiên bản — chính câu mà câu trả lời describe-capabilities không đối số mở đầu, như Máy chủ đến từ bản phát hành nào trình bày; một lần khởi chạy không do gói nào tạo ra, và một lần mà gói đến từ chính bản phát hành của tệp thực thi, trao phần hướng dẫn không có câu đó. Cả hai được cố định khi tiến trình khởi động, và trong mỗi tiến trình, hai bản sửa đổi vẫn phục vụ văn bản riêng của tiến trình đó giống hệt nhau.

Nó dạy mô hình tư duy mà lược đồ đối số của một công cụ tự nó không truyền đạt được:

  • Trình biên dịch làm gì, và cố ý không làm gì — rằng nó định tuyến văn bản và đánh giá các khớp nhãn thay vì diễn giải ý nghĩa của một giá trị, rằng nó không có quan điểm riêng về nội dung bạn đặt trong tài liệu, và rằng trong khi biên dịch, nó không bao giờ xác thực với một provider, không bao giờ đọc trạng thái của một cụm, và không bao giờ biến một bí mật thành văn bản thuần. Một giá trị chỉ tồn tại khi hạ tầng đang chạy được truyền qua dưới dạng một chuỗi con trỏ mà môi trường đích điền vào sau.
  • Từ vựng soạn thảo, và các loại liên quan với nhau thế nào — mỗi loại dùng để làm gì và bản build thực sự chạy trên loại nào, để trợ lý không phải suy đoán hình dạng của một triển khai từ danh sách công cụ.
  • Thứ tự chạy của vòng soạn thảo — đọc hợp đồng, dựng khung từ nó, kiểm tra những gì bạn đang nối tới, rồi kiểm tra trước khi render.
  • Khi nào dùng prompt thay vì công cụ — công cụ để hành động, prompt để định khung một tác vụ.
  • Rằng danh sách công cụ là toàn bộ bề mặt — mọi công cụ máy chủ này cung cấp đều nằm trong đó, và máy chủ cung cấp những công cụ nào phụ thuộc vào cách nó được thiết lập, nên trợ lý đọc những gì có ở đây từ danh sách đó và từ describe-capabilities thay vì đi tìm một danh sách thứ hai. Khi kết nối đã xuất trình thông tin xác thực, nó nói rằng thông tin xác thực quyết định một lần gọi được chạy những công cụ nào trong số đó và không bao giờ quyết định công cụ nào được liệt kê: một lần gọi không được chấp nhận sẽ bị từ chối kèm tên scope sẽ chấp nhận nó, và client có thể đăng nhập lại cho scope đó.
  • Một workspace trống có nghĩa là gì, và mô hình có thể làm gì với nó — đoạn văn khác nhau theo giao thức truyền tải, bên dưới.

Nó nêu tên các bề mặt thay vì nhắc lại chúng. Mỗi công cụ đã mang mô tả và lược đồ đối số riêng trong tools/list, và hợp đồng của mỗi loại đã nằm trong lược đồ và trang tham chiếu của nó, nên phần hướng dẫn chỉ tới đó và dừng lại — mỗi phát biểu một nơi. Một công cụ nó nêu tên là công cụ máy chủ phục vụ, và nó chỉ tới mọi họ tài nguyên mà bề mặt đọc phân giải, nên không có gì nó hướng trợ lý tới là ngõ cụt.

Nó không mang chỉ mục của chính các công cụ, và đó là cùng quy tắc ấy chứ không phải một thiếu sót. Client đã có định nghĩa của mọi công cụ từ tools/list trước khi đọc một chữ của văn bản này, nên mỗi dòng cho một công cụ ở đây sẽ là bản sao thứ hai của những mục đích nó đã có — phải trả giá trong mọi phiên, bởi mọi client, và có thể mâu thuẫn với danh sách công cụ ngay khi một trong hai bị sửa.

Nó cũng nói rõ những gì nó không liệt kê, và tại sao: các đích render có sẵn và các loại thư viện đã cài đặt là thuộc tính của plugin và bộ lược đồ của bạn, nên các bề mặt tài nguyên báo cáo chúng trực tiếp thay vì phần hướng dẫn mang một bản sao có thể mâu thuẫn.

Mô hình được cho biết gì về một workspace trống

Đoạn kết trả lời câu hỏi mà mô hình gặp đầu tiên trên một workspace không chứa gì: một list-entities trống có nghĩa là gì, và nó có thể làm gì với điều đó. Phần mở đầu giống nhau trên cả hai giao thức truyền tải — một danh sách trống nghĩa là workspace mà tiến trình này phân giải không chứa tài liệu Aggrega nào nó đọc được và các thư mục catalog được cấu hình bên cạnh cũng không khai báo tài liệu nào — và phần tiếp theo phụ thuộc vào giao thức truyền tải mà tiến trình phục vụ, vì câu trả lời trung thực không giống nhau trên hai giao thức.

Qua đầu vào và đầu ra chuẩn, mô hình được cho biết workspace là của nó để kiểm tra và sửa chữa. Nó được cho biết một lần gọi không nêu workspace được trả lời ở đâu — trong thư mục máy chủ được khởi chạy kèm, nếu được khởi chạy kèm một thư mục, và nếu không thì trong workspace tìm thấy từ thư mục nó được khởi động, có thể chính là thư mục đó — và rằng workspace_root trên một lần gọi nêu một workspace khác. Nó được chỉ tới config-show cho cấu hình đang có hiệu lực và lớp nào quyết định từng thiết lập, và tới cli-config-init để khởi tạo một cấu hình hoạt động được; cả hai đều có trong danh sách công cụ trên giao thức đó. Client chạy máy chủ nằm trên chính máy của người gọi, nên những gì tiến trình đó chạm tới được là của chính người gọi để sử dụng — và nơi bạn đặt ranh giới là nơi nó được đặt cho mọi công cụ khác, trong MCP client của bạn, như Trợ lý có thể làm gì mà không hỏi bạn trước trình bày.

Qua HTTP, mô hình được bảo hãy báo cáo thay vì cấu hình. Workspace là workspace bạn đã khởi động tiến trình trên đó và cố định suốt vòng đời của nó; một lần gọi nêu workspace_root hoặc catalog_dirs bị từ chối, kèm tên đối số; và không công cụ nào ghi cấu hình được cung cấp cho bất kỳ người gọi nào ở đây, bất kể thông tin xác thực mang scope nào. Các thao tác đó chỉ được thực hiện bởi các công cụ chạy một lệnh aggrega trong tiến trình riêng, và một phiên kết nối qua HTTP được tạo thành mà không có chúng — nên ranh giới là thành phần cấu tạo chứ không phải một scope, và không token nào nới rộng nó. Vì vậy, một mô hình tiếp cận triển khai của bạn qua listener không thể khởi tạo registry hay ghi lại chính sách tin cậy trên máy chủ của bạn, và đoạn văn cho nó biết điều đó thay vì để nó thử rồi đọc lời từ chối.

Những gì trợ lý có thể làm mà không cần hỏi bạn trước

Một trợ lý kết nối với máy chủ này qua đầu vào và đầu ra chuẩn có thể gọi mọi công cụ mà máy chủ cung cấp, không cần hỏi bạn, trừ khi client của bạn được cấu hình để từ chối. Trên phương thức truyền tải đó, máy chủ cung cấp các công cụ và không quyết định lời gọi cụ thể nào được phép dùng công cụ nào: quyết định đó thuộc về client của bạn, và bạn là người đưa ra quyết định ở đó. Qua HTTP thì không giống vậy: máy chủ liệt kê mọi công cụ nó mang và công bố, đồng thời từ chối lời gọi mà các phạm vi (scope) của token gọi không cho phép, nên giới hạn thuộc về cả máy chủ lẫn client.

Điều này quan trọng vì bề mặt công cụ chính là dòng lệnh. Bất cứ thứ gì bạn có thể gõ, trợ lý đều có thể gọi — kể cả các thao tác làm thay đổi máy của bạn.

Một số thao tác đó vươn xa hơn workspace bạn đang làm việc, và không thể hoàn tác bằng cách chạy một thứ khác. Đây là những thao tác đáng biết tên, theo thứ tự phạm vi rộng nhất trước:

  • publish-entity, publish-artifact, sign-artifacts và deprecate-artifact vươn ra hoàn toàn ngoài máy. Chúng đặt byte, chữ ký hoặc dấu thu hồi vào một registry, nên thứ chúng thay đổi là thứ mà mọi bên tiêu thụ registry đó phân giải — không chỉ thứ máy này phân giải. Việc xuất bản lại nội dung khác đè lên một tag bị từ chối chứ không được cung cấp, nên không có gì ở đây rút lại một bản xuất bản; cách giải quyết là xuất bản một phiên bản mới. Chữ ký và dấu thu hồi giữ nguyên byte của artifact, nhưng bất kỳ ai tải artifact đó về sau cũng tải cả chúng, và không thể thu hồi cái nào từ người đã có nó. Trên đầu vào và đầu ra chuẩn, bốn khả năng này cũng có thể truy cập dưới dạng cli-push, cli-push-artifact, cli-sign và cli-deprecate, vốn chạy các lệnh tương ứng; qua HTTP bốn công cụ đó không tồn tại.
  • Việc ký sử dụng thông tin xác thực. Qua đầu vào và đầu ra chuẩn, ký không khóa (keyless) lấy identity token từ đối số identity_token của lời gọi, từ AGGREGA_IDENTITY_TOKEN hoặc SIGSTORE_ID_TOKEN trong môi trường của máy chủ, hoặc từ endpoint OIDC của GitHub Actions sẵn có trong môi trường nếu truy cập được; key_path chọn một khóa được giữ ngoại tuyến thay thế. Vì vậy, một trợ lý có thể gọi các công cụ này có thể ký thay bạn, với bất kỳ danh tính nào mà máy chạy máy chủ đã mang sẵn — và chữ ký là một tuyên bố về việc ai bảo chứng cho một artifact, đó là lý do đây là thao tác cần cân nhắc kỹ nhất trước khi cho phép. Qua listener, chỉ token gửi trong lời gọi mới ký được: không gì trong môi trường của máy chủ được đọc, và không khóa nào được giữ trên host có thể được chọn bằng đối số hay bằng cấu hình của workspace được phục vụ, như Which credentials a call spends trình bày.
  • aggrega cache evict cắt giảm kho module đã biên dịch, còn aggrega cache clear xóa sạch nó. Kho đó được chia sẻ bởi mọi dự án Aggrega trên máy. Các module bị xóa khỏi kho được biên dịch lại khi cần, nên không có gì mất vĩnh viễn — nhưng lần build tiếp theo của bất kỳ dự án nào phải trả chi phí đó. aggrega cache clear cũng xóa gói tài liệu mà mọi dự án trên máy đọc, gói này được tải lại vào lần tiếp theo một dự án cần đến nó.
  • aggrega cache prune thu hồi các mục trong artifact cache mà không lockfile nào tham chiếu. Nếu lockfile của một dự án không có mặt để đọc, các artifact được ghim của dự án đó không được nó bảo vệ, và thu hồi chúng đồng nghĩa với việc phải tải lại.
  • aggrega registry add và aggrega registry remove mặc định ghi vào cấu hình dùng chung cho mọi workspace, nên chúng thay đổi thứ được phân giải ở mọi nơi trên máy, không chỉ ở đây. aggrega registry add cũng hỏi registry mà nó nêu tên về chính sách tin cậy registry đó công bố và ghim thứ nhận được, đúng như khi chạy ở terminal. Trong một workspace ngoại tuyến, việc tải đó bị từ chối trước khi bất kỳ kết nối nào được thực hiện, nên việc thêm một registry khác với hub chính thức bị từ chối — mã ngắn E0310, với cùng lời lẽ — trừ khi lời gọi cung cấp identity hoặc key; aggrega config init, vốn không nhận cái nào, chỉ có thể khởi tạo hub khi ngoại tuyến. Trên đầu vào và đầu ra chuẩn, chúng có thể truy cập dưới dạng cli-registry-add và cli-registry-remove, còn việc khởi tạo là cli-config-init, vốn chạy các lệnh; qua HTTP các công cụ đó không tồn tại.
  • pull đọc từ một registry và ghi bên trong workspace mà nó được trỏ tới. Nó ghi lockfile của Release đó, nạp vào artifact cache những gì đã phân giải, và ghi lại danh tính của từng plugin trả về phán quyết mà workspace của bạn gắn kèm, cạnh lockfile. Khi được gửi pin_sources — hoặc trong một workspace có pin_sources_at_pull bật và lời gọi không gửi nó là false — nó cũng chạy bước ghim của tác giả entity trên các Recipes và FeatureRecipes mà Release build từ các thư mục catalog của bạn, ghi entity.lock cạnh mỗi cái; không có nó, một lần pull trên entity như vậy mà lock không ghi pin cho một đầu vào nó đọc sẽ bị từ chối, kèm tên bước đó. Bản thân các tệp entity không bao giờ bị ghi. Không gì trong đó rời khỏi máy, và phân giải lại là cách bạn thay đổi những gì nó đã ghi, nên đây là thao tác ghi nhẹ nhất trong số các thao tác ở đây. Nó là một trong các công cụ được thiết kế cho vòng lặp soạn thảo có ghi bên trong workspace: pin ghi entity.lock cạnh Recipe hoặc FeatureRecipe bạn nêu tên, như Ghim các đầu vào của chính một thực thể trình bày; gen-catalog ghi các entity Plugin được sinh ra dưới thư mục bạn nêu tên; edit-document áp dụng một chỉnh sửa có cấu trúc, có giới hạn lên một tài liệu bạn đã có và ghi lại, giữ nguyên mọi byte mà chỉnh sửa không chạm tới, như Áp dụng một chỉnh sửa có giới hạn lên tài liệu trình bày; import biến một mô tả do công cụ khác tạo ra thành các tệp soạn thảo nháp và ghi chúng vào workspace, như Chuyển một mô tả bên ngoài thành các entity nháp trình bày; và scaffold khi được gửi example sẽ ghi một trong các ví dụ chạy được của tài liệu vào một thư mục mới hoặc trống, dir, như aggrega scaffold --example vẫn làm, điều mà qua HTTP phạm vi workspace-write cho phép. Thư mục đầu ra đó, guest mà gen-catalog đọc và bất kỳ overlay nào bạn cung cấp đều tương đối so với gốc workspace, hoặc tuyệt đối qua đầu vào và đầu ra chuẩn, cùng hợp đồng mà mọi đối số đường dẫn khác trên bề mặt này sử dụng. Trên đầu vào và đầu ra chuẩn, khả năng này cũng có thể truy cập dưới dạng cli-pull, vốn chạy lệnh tương ứng; qua HTTP công cụ đó không tồn tại.
  • build đọc cùng registry và thực hiện cùng thao tác ghi khi bạn gửi auto_pull, và chỉ khi đó. Phân giải các phụ thuộc của một Release là cùng một thao tác ở bất cứ đâu nó được yêu cầu, nên một lần build được bảo phân giải trước sẽ làm đúng những gì pull làm rồi render dựa trên những gì nó đã ghi — đó là lý do nó mang cùng phạm vi chứ không phải phạm vi hẹp hơn. Khi được gửi write, nó cũng ghi các artifact đã render vào dist/ tại gốc workspace, nơi aggrega build ghi chúng và qua cùng thao tác ghi, nên nó vươn tới workspace cho lời gọi đó; nó không ghi ở đâu khác, và một dist là liên kết dẫn ra ngoài workspace sẽ bị từ chối trước khi bất cứ thứ gì trong đó bị xóa hoặc ghi. Không có đối số nào, vốn là mặc định, build render từ các pin mà workspace đã giữ và không vươn tới đâu cả. Đọc Build dựa trên nội dung mà một Release đã ghim để biết đối số thay đổi gì và giữ nguyên gì.

Các công cụ kiểm kê tự nói rõ điều này trong câu trả lời của chúng. cache-status đánh dấu từng lớp cache với phạm vi tác động của nó — workspace cho artifact cache nằm dưới thư mục cache riêng của dự án này, machine cho các kho mà mọi dự án dùng chung — và gọi tên thẳng những kho có phạm vi toàn máy, để một trợ lý đọc bản kiểm kê trước khi đề xuất thu hồi dung lượng được biết phần nào trong đó không chỉ thuộc về riêng bạn. Các thao tác bảo trì báo cáo cùng phạm vi đó cho từng phần tử chúng đã xóa. Mỗi kết quả trong bốn kết quả xuất bản mang một reach riêng, chứa registries — mọi registry host mà lệnh gọi đã hướng tới, mỗi host được nêu một lần, theo thứ tự lần đầu được hướng tới — và beyond_this_machine, được xác định từ những gì lệnh gọi thực sự đã gắn vào chứ không phải những gì nó yêu cầu: true khi nó đã tải nội dung lên hoặc đã gắn một chữ ký, một ngày xuất bản hay một dấu ngừng hỗ trợ, và false đối với một lần chạy thử (dry run) và đối với một lệnh gọi thấy rằng tất cả đã có sẵn, chẳng hạn một lần xuất bản chạy lại trên một phiên bản đã hoàn chỉnh hoặc một lô ký mà mọi tham chiếu đều đã được ký.

Nơi bạn đặt ranh giới. Bản thân giao thức không định nghĩa quyền theo từng công cụ — cơ chế xác thực của nó chỉ xét việc một client có được kết nối hay không, chứ không xét client đó sau đó được gọi những công cụ nào. Quyết định cấp quyền nằm ở MCP client của bạn. Các client phổ biến nhìn chung có thể cho phép và từ chối từng công cụ theo tên từ một server, và vô hiệu hóa hoàn toàn một server cho một dự án nhất định; tên và vị trí của thiết lập này khác nhau tùy client, vì vậy hãy tham khảo tài liệu riêng của client về quyền công cụ. Nếu bạn muốn các thao tác đọc mà không muốn các thao tác ghi, hãy cho phép những công cụ bạn muốn và từ chối phần còn lại tại đó. Một cấu hình dễ dãi, hoặc một client không có thiết lập như vậy, sẽ để mọi công cụ được cung cấp đều có thể gọi được.

Tìm hiểu một workspace chứa những gì

Hầu hết các công cụ nhận một đối tượng: tên một thực thể, hoặc đường dẫn của một Release. Hai công cụ dưới đây không nhận đối tượng nào, và chúng là cách một trợ lý vừa mới đến lấy được một đối tượng.

list-entities trả lời workspace chứa những gì, còn list-releases trả lời câu hỏi hẹp hơn mà phần còn lại của giao diện liên tục đặt ra: có những Releases nào. Không công cụ nào nhận đối tượng, vì những gì một workspace chứa là thuộc tính của workspace chứ không phải của thứ mà bên gọi phải biết trước.

Mỗi công cụ trả lời theo một trong hai dạng, và lệnh gọi không chỉ định dạng nào sẽ nhận bản tóm tắt. Mặc định đó chỉ thuộc về hai công cụ này, và nó ngược với mặc định mà build, describe và validate dùng. Những công cụ kia được hỏi về một đối tượng mà bên gọi đã nêu tên, nên câu trả lời đầy đủ hơn là thứ được yêu cầu và câu trả lời ngắn gọn là tùy chọn. Hai công cụ này được hỏi ở đây có gì, bởi một bên gọi chưa có gì để nêu tên và không có cách nào biết câu trả lời sẽ tốn bao nhiêu trước khi nó đến — nên chúng báo cáo kích thước và hình dạng của workspace trước và chỉ trao bản ghi khi được yêu cầu.

Bản tóm tắt cho biết ở đây có gì và bao nhiêu. list-entities báo cáo thư mục gốc của workspace — được giữ lại qua HTTP, như Câu trả lời nói gì về hệ thống tệp của server trình bày — tổng số thực thể, và số lượng theo từng kind; list-releases báo cáo tổng số và số lượng theo từng thư mục cấp cao nhất, để bạn biết có bao nhiêu Releases và chúng nằm ở phần nào của cây. Cả hai bảng phân tích đều được đọc từ chính các tài liệu, nên một workspace được bố trí theo cách không ai lường trước cũng được tóm tắt chính xác như một workspace bình thường. Cả hai có một hàng cho mỗi kind, hoặc mỗi thư mục cấp cao nhất, nên kích thước của chúng phụ thuộc vào số kind mà workspace khai báo và số thư mục chứa các Releases của nó, chứ không phụ thuộc vào số tài liệu nó chứa: nhân số tài liệu trong một workspace lên một trăm lần, giữ nguyên các kind, thì bản tóm tắt chỉ tăng thêm vài byte cần để viết các con số lớn hơn. Khai báo thêm kind mới là điều làm nó dài hơn. Không bản nào là trang bản ghi đầu tiên, và sự khác biệt đó chính là mấu chốt: “đây là một số thực thể” là câu trả lời khác với “workspace được tạo nên từ những thứ này”, và chỉ câu thứ hai cho bạn biết bạn có cần bản ghi nào không, và bản ghi nào.

Gửi response_format: detailed để nhận bản ghi, và chúng đến theo từng trang. Khi đó list-entities báo cáo kind, tên, apiVersion, mô tả, nhãn và tệp nguồn của mỗi thực thể, đọc trực tiếp từ tài liệu khai báo nó. Nó cũng báo cáo các Features mà các thư mục catalog đã cấu hình khai báo, để một Feature được đề xuất cho bạn là có thể gắn vào cũng là Feature bạn có thể tra cứu; chúng không có tệp nguồn, vì đường dẫn duy nhất chúng có là đường dẫn trên máy chạy server, và mỗi cái cho biết nó đến từ đâu để một tệp trống được hiểu là “được phân giải từ catalog” chứ không phải một giá trị bị thiếu. list-releases báo cáo đường dẫn của mỗi Release, và lockfiles ánh xạ mỗi đường dẫn nó trả về tới đường dẫn lockfile của Release đó, trong cùng hệ tọa độ: tệp mà pull ghi cho nó và build đọc, cũng là tệp mà các câu trả lời về Release của language server nêu tên. Ánh xạ mô tả các đường dẫn mà câu trả lời này mang, nên nó đi theo trang, và bản tóm tắt mang nó ở dạng rỗng.

detailed và concise là hai giá trị duy nhất mà response_format nhận, và chúng được so khớp chính xác. Mọi cách viết khác — một từ khác, chữ hoa/thường khác, hoặc khoảng trắng quanh một trong hai — đều bị từ chối, và lời từ chối nêu giá trị đã gửi cùng với các giá trị mà đối số chấp nhận. Bỏ response_format đi là cách yêu cầu mặc định, mà với hai công cụ này là bản tóm tắt. Điều tương tự áp dụng ở mọi nơi đối số xuất hiện: build, describe và validate nhận cùng hai giá trị theo cùng điều kiện, và mặc định của chúng là dạng đầy đủ hơn chứ không phải dạng ngắn gọn.

Các bản ghi được giới hạn dù bạn có giới hạn chúng hay không. limit là số bản ghi một câu trả lời mang, từ 1 đến 500, và mặc định là 50 — nên một lệnh gọi yêu cầu bản ghi mà không nêu kích thước trang vẫn bị giới hạn, và không lần gọi nào của hai công cụ trả về câu trả lời do kích thước của chính workspace quyết định. offset là vị trí bắt đầu trong danh sách, đếm từ 0. Cả hai giới hạn các bản ghi, nên không cái nào ảnh hưởng đến bản tóm tắt, vốn không mang bản ghi nào. Một limit nằm ngoài phạm vi đó bị từ chối và nêu giới hạn; một offset vượt quá cuối danh sách trả về rỗng, vì ở đó không có gì chứ không phải câu hỏi có gì sai.

Tiếp tục một danh sách bằng cách đọc ba trường từ câu trả lời. count là số bản ghi workspace chứa, offset và returned cho biết câu trả lời này bắt đầu ở đâu và mang bao nhiêu bản ghi, còn more_remaining cho biết còn lại bản ghi nào không. Khi more_remaining còn là true, hãy gọi lại với offset cộng returned. Tín hiệu đó được tính từ trang so với tổng số chứ không được ghi sẵn vào câu trả lời, nên nó không thể báo không còn gì trong khi vẫn còn bản ghi.

Tất cả điều đó quan trọng vì các công cụ có nhận tên sẽ từ chối một tên chúng không phân giải được thay vì trả lời bằng kết quả rỗng. Việc từ chối là có chủ ý — một câu trả lời rỗng sẽ báo một tên gõ sai như một đối tượng không có gì để cung cấp — nhưng nó có nghĩa là bên gọi chưa có tên nào không thể có được tên bằng cách đoán. Liệt kê là cách để có được tên.

Hai công cụ này kết hợp với nhau, và với phần còn lại của giao diện:

  • Gọi list-entities để lấy bản tóm tắt nhằm xem workspace chứa những kind nào và mỗi kind bao nhiêu, rồi gọi lại với response_format: detailed để lấy bản ghi, lấy một tên từ kết quả, và chuyển nó cho describe để xem định nghĩa đã phân giải đầy đủ của thực thể đó. Đó là định nghĩa mà aggrega/entityDefinition của language server trả lời, được mang dưới dạng JSON: mỗi khóa theo tên tác giả viết, theo thứ tự định nghĩa lưu, một schema đúng như schema tác giả đã viết, và schema nào thực thể không khai báo thì bị bỏ đi — các socket của một Component, mỗi socket kèm các slot mà kết nối của nó có thể lấp đầy.
  • Làm tương tự với list-releases, lấy một đường dẫn từ kết quả chi tiết, và chuyển nó cho describe hoặc build làm Release để làm việc.
  • Đường dẫn mà list-releases trả về là tương đối so với thư mục gốc của workspace, cũng là hệ tọa độ mà list-entities dùng để báo cáo tệp, nên hai câu trả lời khớp nhau theo tệp và có thể đọc cùng nhau. Lockfile của nó, trong lockfiles, cũng tương đối so với cùng thư mục gốc, nên bạn có thể đọc hoặc so sánh tệp đó mà không cần tìm ra nó nằm ở đâu.

Cả hai quyết định cái gì được tính bằng cách đọc kind của chính mỗi tài liệu, không bao giờ dựa vào tên tệp. Một Release được đặt tên không theo tiền tố quy ước vẫn được liệt kê; một tệp chỉ được đặt tên giống một Release thì không, và xuất hiện dưới bất kỳ kind nào mà nó thực sự khai báo. YAML không khai báo kind nào cả — tệp values của một chart, một tệp cấu hình tình cờ nằm trong cây — không phải là một thực thể và không được báo cáo, và một tài liệu thuộc về dự án khác, chẳng hạn một manifest Kubernetes đã được render, cũng vậy. Một tài liệu được tính là thực thể khi nó khai báo cả kind lẫn tên, vì hai thứ đó cùng nhau làm cho nó có thể được tham chiếu về sau, và không khai báo apiVersion nào nằm ngoài nhóm riêng của Aggrega. Một tài liệu không khai báo apiVersion nào cả vẫn được báo cáo, vì đó là một tài liệu Aggrega thiếu một trường chứ không phải tệp của dự án khác. list-releases không tìm kiếm thư mục nào bên ngoài gốc workspace, nên một Release mà trình soạn thảo của bạn hiển thị dưới một liên kết dẫn tới một thư mục như vậy sẽ không được liệt kê; unread_linked_dirs nêu tên từng liên kết nằm ở chỗ mà việc liệt kê lẽ ra sẽ đọc một thư mục và dẫn ra ngoài gốc — theo đường dẫn của chính liên kết tương đối với gốc, không bao giờ theo nơi nó dẫn tới — ở cả hai dạng và trên cả hai phương thức truyền tải, và để trống khi không có liên kết nào. Nó cũng không đọc tệp nào bên ngoài gốc thông qua một liên kết: unread_linked_files nêu tên, theo cùng cách, từng liên kết mà tên của chính nó kết thúc bằng .yaml hoặc .yml và dẫn tới một tệp bên ngoài gốc, bất kể tệp đó chứa gì, nên một Release chỉ đến được qua một liên kết như vậy sẽ không được liệt kê — trừ khi cấu hình workspace nêu tên Release đó, dưới dạng build.authoring_release hoặc một khóa của workspace.releases, khi đó nó được đọc và liệt kê tại vị trí của chính liên kết và không bị nêu tên. list-entities cũng không đọc tài liệu nào nằm sau một liên kết dẫn ra khỏi workspace — nó không tìm kiếm thư mục nào bên ngoài gốc, và không đọc tệp nào bên ngoài gốc bất kể tệp đó khai báo gì — và nêu tên từng liên kết như vậy theo cùng cách, trong unread_linked_dirs và unread_linked_files của riêng nó, ở cả hai dạng và trên cả hai phương thức truyền tải. Điều đó đúng bất kể tài liệu khai báo gì, với một ngoại lệ duy nhất mà list-releases cũng có: một Release mà cấu hình workspace nêu tên, dưới dạng build.authoring_release hoặc một khóa của workspace.releases, được đọc và liệt kê tại vị trí của chính liên kết và không bị nêu tên, còn một tệp mà một trong các thiết lập đó nêu tên nhưng khai báo bất cứ thứ gì khác ngoài một Release thì không được liệt kê, và liên kết của nó bị nêu tên. Các thư mục catalog đã cấu hình là cách một workspace đọc những thực thể khác được lưu ở nơi khác, nên một liên kết tới một thư mục mà cấu hình liệt kê dưới catalog_dirs, hoặc tới một thư mục bên dưới thư mục đó, không bị cả hai danh sách nêu tên: cấu hình đã đến được nó. Các Features mà list-entities lấy từ các thư mục catalog không bao giờ bao gồm một Feature nằm sau liên kết dẫn ra khỏi thư mục mà các lần đọc của một thư mục catalog phải nằm trong — workspace, đối với thư mục catalog nằm trong nó, hoặc chính thư mục đó, đối với thư mục mà cấu hình nêu tên ở bên ngoài — nên một thực thể được nêu tên là nằm sau một liên kết không được đọc thì không bao giờ được liệt kê bên cạnh tên đó. Một liên kết mà việc liệt kê bỏ qua — do tên của nó, do vị trí của nó hoặc do một .gitignore — không bị nêu tên, và với release thì một liên kết nằm dưới thư mục catalog mà chỉ các Releases khác đọc cũng vậy; một .gitignore mà bản thân nó là liên kết dẫn ra khỏi workspace thì không được đọc. Khi bất kỳ danh sách nào trong số này nêu tên một liên kết, câu trả lời dạng văn bản kết thúc bằng một dòng riêng nói điều đó.

Một workspace có tệp cấu hình dẫn ra khỏi nó vẫn được liệt kê, và không có gì khác được trả lời cho nó. Khi .aggrega-config.yaml của chính workspace, hoặc lớp phủ do CI sở hữu nằm bên cạnh nó, là một liên kết dẫn ra khỏi workspace, cấu hình của nó không được đọc, như tại terminal, và không có gì mà nó lẽ ra đã cấu hình được đọc thay thế. Máy chủ vẫn khởi động qua đầu vào và đầu ra chuẩn, và thông báo điều đó bằng một dòng trên luồng lỗi của nó. list-entities và list-releases trả lời bằng các tài liệu của chính workspace, được đọc mà không có gì được cấu hình, nên không có Features nào của thư mục catalog được liệt kê. Mỗi công cụ nêu tên tệp bị giữ lại trong unread_linked_files, và trong dòng kết thúc văn bản của nó, bất kể việc liệt kê có gặp tệp đó hay không — cái tên đó là cách bạn biết rằng cấu hình của workspace dẫn ra bên ngoài nó. Một lệnh liệt kê được gửi kèm release hoặc catalog_dirs, và mọi công cụ khác nêu tên workspace đó, đều được quyết định bởi cấu hình không được đọc, nên mỗi lệnh đều bị từ chối với E0321, nêu tên liên kết và nơi nó dẫn tới. Một máy chủ được yêu cầu lắng nghe trên dòng lệnh — --transport http, hoặc --listen — sẽ không khởi động trên một workspace như vậy, vì địa chỉ nó sẽ bind, chứng chỉ của nó và ai được phép gọi nó là những gì cấu hình đó quyết định. Hãy gỡ bỏ liên kết, hoặc làm cho nó dẫn tới một tệp bên trong workspace, và lần gọi tiếp theo sẽ đọc cấu hình. Xem ranh giới workspace.

Hỏi theo các điều kiện của một Release

Một workspace có thể cấp cho mỗi Release các thư mục catalog riêng — xem Cấp cho một Release các thư mục catalog riêng — và nhờ đó giữ song song một biến thể của một thực thể cho mỗi Release. Ba công cụ vốn trả lời trên các thư mục catalog riêng của workspace nhận một release tùy chọn, là đường dẫn của một tệp Release, và khi đó trả lời theo các điều kiện của Release đó:

  • list-entities với release liệt kê các thực thể mà Release đó thấy. Các Features được liệt kê là những Features mà các thư mục catalog của nó khai báo, và một tài liệu của workspace nằm dưới một thư mục catalog mà chỉ các Releases khác đọc sẽ bị loại ra, nên mỗi biến thể được liệt kê cho Release build với nó và không cho Release nào khác. Một tài liệu không nằm dưới thư mục catalog nào — một Release, Aggregate của nó và Manifest của nó được viết bên cạnh các catalog — được liệt kê cho mọi Release.
  • describe với một name và một release phân giải tên qua các thư mục catalog của Release đó, nên một tên mà nhiều biến thể khai báo sẽ phân giải thành biến thể mà Release đó build cùng. Một tên mà các thư mục đó không phân giải được sẽ bị từ chối kèm một giải thích nêu mục của Release đó dưới workspace.releases. Một tham chiếu registry được đọc từ registry của nó bất kể Release nào được nêu, nên nó bị từ chối khi đi kèm một release. Một release được gửi mà không có name vẫn là Release mà describe tóm tắt.
  • validate với một entity và một release chạy các kiểm tra trên một thực thể theo các điều kiện của Release đó: các tham chiếu của thực thể — Component mà một Recipe hiện thực, một SchemaLibrary mà một pillar tham chiếu — được phân giải qua các thư mục catalog của Release đó, và câu trả lời nêu Release bên cạnh thực thể. Không có closure nào được kiểm tra; một release được gửi mà không có entity vẫn là phạm vi Release. catalog_dirs được thêm vào trước các thư mục của Release ở đây cũng như ở mọi nơi. Một thư mục mà cấu hình workspace liệt kê nhưng không phải là thư mục — chẳng hạn không có gì tồn tại ở đó — đối với Release đó, hoặc đối với workspace khi không gửi release, sẽ khiến lời gọi bị từ chối trước khi bất cứ thứ gì được kiểm tra, văn bản mang theo lời từ chối mà mọi lệnh đưa ra cho nó, nêu mục đó cùng tệp cấu hình và dòng liệt kê nó (Nơi các thực thể cục bộ được đọc), như aggrega validate từ chối nó.

Một release nêu một tệp không tồn tại, hoặc nêu một thư mục, sẽ bị từ chối trên cả ba công cụ thay vì được trả lời theo các điều kiện của workspace. Không gửi gì thì câu trả lời dựa trên các thư mục catalog riêng của workspace.

describe khi tra cứu một tên sẽ từ chối một thư mục catalog mà nó sẽ phân giải tên qua đó nhưng không thể duyệt được, như aggrega inspect từ chối nó — các thư mục của Release đó khi gửi một release, các thư mục riêng của workspace khi không gửi, và mọi thư mục mà lời gọi nêu trong catalog_dirs. Một thư mục mà lời gọi nêu nhưng không tồn tại, hoặc có tồn tại nhưng không đọc được, bị từ chối trước khi tên được tra cứu, và văn bản nêu thư mục như dòng lệnh báo cáo nó, trên một dòng — thư mục, catalog load, và lý do mà hệ thống tệp đưa ra — thay vì phân giải tên từ các thư mục còn lại. Một thư mục mà cấu hình workspace liệt kê nhưng không phải là thư mục bị từ chối ngay tại thời điểm đó, văn bản mang theo lời từ chối mà mọi lệnh đưa ra cho nó (Nơi các thực thể cục bộ được đọc). Một release nêu một tệp không tồn tại bị từ chối trước cả điều đó, như đã nói ở trên. Một thư mục catalog chứa một liên kết dẫn ra ngoài thư mục mà các lần đọc của nó phải ở bên trong cũng bị từ chối theo cách tương tự, văn bản nêu liên kết và nơi nó dẫn tới, vì một tên được phân giải mà không có nó có thể phân giải thành một thực thể khác cùng tên thay thế. Việc mô tả dependency closure của một Release không bị ảnh hưởng bởi một thư mục không duyệt được, và trả lời dựa trên các thư mục duyệt được, như aggrega inspect --closure làm — ngoại trừ một thư mục mà cấu hình workspace liệt kê cho Release đó nhưng không phải là thư mục, thứ mà nó từ chối như aggrega inspect --closure từ chối; một liên kết dẫn ra ngoài phạm vi đọc của một thư mục catalog, hoặc ra ngoài các tài liệu bên cạnh Release, sẽ làm nó dừng lại, như nó làm một build dừng lại.

validate với một entity báo cáo một lần render mà nó không thể đánh giá là chưa được thực hiện, dù theo các điều kiện của một Release hay không. Nó đặt Component của một Recipe vào một build tổng hợp không nối kết nối nào và không gắn Feature nào, nên một Recipe có lần render dừng lại trong khi các template của nó — kể cả các tệp và các mục thư viện mà chúng import — đọc bất cứ thứ gì dưới .context.inject, .context.uses hoặc .features sẽ trả lời valid: true mà không có gì trong diagnostics; văn bản của nó mang Render: not attempted (this Recipe reads values a build of one cannot supply), các lần đọc khiến nó bị gác lại, và câu mà lần render dừng lại. Điều quyết định là những gì Recipe đọc, nên một lỗi riêng của Recipe đi kèm một lần đọc như vậy cũng bị gác lại cùng nó, trong khi một template không parse được và một tham chiếu mà lần render từ chối vẫn trả lời valid: false. aggrega validate đưa ra cùng kết luận trên cùng các đầu vào.

validate với một entity báo cáo một assertion thất bại như một cảnh báo, dù theo các điều kiện của một Release hay không. Một assertion gọi fail — của chính Recipe, hoặc một assertion mà Component nó hiện thực khai báo — trả lời valid: true mà không có gì trong diagnostics. Build tổng hợp mang các giá trị giữ chỗ và giá trị mặc định của schema thay cho các giá trị mà một Release thực sự đặt, nên một assertion trên giá trị như vậy sẽ thất bại ở đó dù Recipe có đúng hay không, và việc kiểm tra không thể phân biệt một assertion đang chờ một Release với một assertion bị hỏng. Lỗi thất bại đi sau các notices khác, dưới dạng thông báo đầy đủ của assertion kết thúc bằng câu A Release must satisfy this assertion before a build of it can pass., và văn bản mang nó trên một dòng mở đầu bằng warning:, bên cạnh dòng báo cáo cho biết lần chạy dừng ở đâu. Một assertion dừng lại ở một khóa mà nó đọc nhưng không tìm thấy là một lỗi trong chính văn bản của nó chứ không phải một assertion thất bại, và được đánh giá như mọi lần dừng khác; một build của một Release không thỏa mãn một assertion vẫn bị từ chối vì nó. aggrega validate đưa ra cùng kết luận trên cùng các đầu vào.

Đọc cấu hình đang có hiệu lực và các plugin mà máy chủ này phân giải

config-show báo cáo cấu hình đang có hiệu lực và lớp nào đã quyết định từng thiết lập. plugin-list báo cáo các plugin mà máy chủ này có thể phân giải và những gì mỗi plugin tự mô tả về mình. Cả hai đều không đọc và không ghi gì, nên mỗi công cụ không chạm tới gì và aggrega:read cho phép nó — và không công cụ nào yêu cầu bạn nêu tên một đối tượng, vì những gì được cấu hình và những gì phân giải được là thuộc tính của máy chủ này chứ không phải của thứ gì bạn phải biết trước. Mỗi công cụ nhận một workspace_root tùy chọn trên đầu vào và đầu ra chuẩn; qua HTTP, đối số đó bị từ chối, như Một tiến trình, một workspace trình bày.

Cùng nhau, chúng trả lời một câu hỏi theo hai nửa: một khả năng là không có, hay chỉ là chưa được cấu hình ở đây. Cấu hình cho biết một provider, một importer hay một bước kiểm tra quản trị có được gắn vào hay không; việc đọc plugin cho biết một liên kết có tới được một guest phân giải được, tự mô tả được và phục vụ đúng những gì nó tuyên bố hay không. Từ mọi nơi khác trên bề mặt này, hai trường hợp đó trông giống nhau, và chúng đòi hỏi các bước tiếp theo trái ngược nhau.

config-show báo cáo một mục cho mỗi thiết lập: field của nó, value có hiệu lực của nó, và source đã quyết định nó — một tệp cấu hình, một biến môi trường, một cờ dòng lệnh, hoặc các giá trị mặc định tích hợp sẵn. Bên cạnh đó, layers chứa các lớp đã đóng góp theo thứ tự ưu tiên, thấp nhất trước. source của một thiết lập được viết đúng như mục tương ứng trong layers, nên hai thứ khớp nối trực tiếp với nhau, và một thiết lập do giá trị mặc định quyết định thì không nêu lớp nào, vì giá trị mặc định không phải là một lớp đã đóng góp. Lớp toàn cục là tệp mà chính dòng lệnh của máy chủ chọn — tệp mà --config đã chỉ định khi máy chủ được khởi động, nếu không thì tệp mà biến môi trường AGGREGA_CONFIG chỉ định, nếu không nữa thì vị trí mặc định — nên một thiết lập do tệp đó quyết định được quy cho tệp đó, đúng như aggrega config show --origin quy cho nó, và một cờ như --offline truyền cho máy chủ được báo cáo là cờ đó. Công cụ này không nhận response_format và không có kích thước trang: các thiết lập là tập cố định mà binary này quản lý và mỗi lần phân giải đều báo cáo tất cả chúng, nên kích thước câu trả lời phụ thuộc vào binary chứ không vào những gì bạn cấu hình.

plugin-list trả lời theo hai dạng mà các danh sách workspace sử dụng, và một lời gọi không nêu dạng nào sẽ nhận bản tóm tắt. Bản tóm tắt là số lượng theo từng nhóm, và có hai nhóm — embedded, các guest được biên dịch vào binary này, phân giải mà không cần truy cập hệ thống tệp, bộ nhớ đệm hay mạng, và configured, các liên kết riêng của workspace. Gửi response_format: detailed để nhận các bản ghi: nhóm của mỗi plugin, tham chiếu mà nó được tìm thấy, nơi tham chiếu đó được liên kết, loại, phiên bản, commit do nó tự báo cáo, các khả năng được phục vụ, các loại đầu vào được render, boundary assembly và các export, trạng thái sẵn sàng nếu có, và việc nó có phân giải được hay không. Các bản ghi được giới hạn bởi limit và offset theo cùng điều kiện mà danh sách thực thể sử dụng, với count, returned và more_remaining để tiếp tục. Câu trả lời này có tăng theo những gì bạn cấu hình — phần tích hợp sẵn là cố định, các liên kết là của bạn — và đó là lý do nó được phân trang còn việc đọc cấu hình thì không.

Một plugin bị lỗi được báo cáo kèm lỗi của nó thay vì bị loại khỏi danh sách. resolved cho biết tham chiếu có tới được các byte của module hay không, và một plugin đã phân giải nhưng không thể tự mô tả được báo cáo đúng như vậy — nên một liên kết có mặt nhưng không dùng được có thể phân biệt với một liên kết chưa bao giờ được tạo.

Những gì một listener không cho bạn biết về máy chủ của nó

Qua HTTP, không bản đọc nào báo cáo một giá trị chỉ một vị trí trên hệ thống tệp của máy chủ. Một client đã khởi chạy máy chủ thì chạy ở nơi máy chủ chạy, nên mọi vị trí mà một trong hai câu trả lời có thể nêu đều là vị trí mà bên gọi đó đã sở hữu và có thể tự đến xem. Một bên gọi tới một listener không chọn vị trí nào trong số đó, không thể hành động dựa trên việc biết chúng, và một máy chủ đã công bố chúng cho bên gọi như vậy thì không thể rút lại. Qua phương thức truyền đó, các giá trị ấy vắng mặt; qua đầu vào và đầu ra chuẩn, tất cả đều có mặt. Đây là quy tắc mà mọi câu trả lời trên bề mặt này tuân theo, như Câu trả lời nói gì về hệ thống tệp của máy chủ trình bày, và hai bản đọc này là nơi nó vươn xa nhất, vì phần lớn những gì chúng báo cáo là cấu hình chỉ đến các vị trí.

Những gì bị giữ lại. Từ config-show: value của một thiết lập khi giá trị của chính thiết lập đó là một vị trí — một địa chỉ phục vụ hoặc kiểm tra sức khỏe, có thể là một tệp socket; một tệp chứng chỉ, khóa riêng hoặc tập khóa; một thư mục catalog, và các thư mục catalog riêng của một Release trong workspace.releases, mà mọi mục đều được khóa theo một tệp Release; một tham chiếu plugin; một Release dùng để soạn thảo. Ngoài ra còn source của một thiết lập khi lớp quyết định nó là một tệp cấu hình, vì lớp như vậy được đặt tên theo chính đường dẫn của tệp đó — và, cùng cách viết và cùng lý do, các mục tệp cấu hình của layers. Từ plugin-list: uri của một plugin khi chính tham chiếu đó là một đường dẫn hệ thống tệp, và văn bản của một lỗi phân giải hoặc mô tả, vốn được tạo từ các vị trí đã thử và do đó nêu những vị trí mà chính tham chiếu không nêu. Từ cả hai: workspace_root.

Những gì được báo cáo đầy đủ, trên cả hai phương thức truyền. Một tham chiếu registry, một phiên bản, một commit, một digest, một khả năng được phục vụ, một nhãn sẵn sàng, tên của một biến môi trường hoặc của một cờ, và một lớp không phải là tệp. origin trên một bản ghi plugin là một trong số này: đó là khóa cấu hình nơi một liên kết được viết, hoặc digest được ghim mà một phần mở rộng lệnh đã cài đặt mang theo, và một plugin tích hợp sẵn không mang gì — nên nó là cùng một chuỗi bất kể plugin được đọc từ đâu. resolved là một thứ khác: việc một plugin bị lỗi được báo cho mọi bên gọi, ngay cả khi lý do của lỗi thì không.

Một giá trị vắng mặt luôn cho biết nó đã bị giữ lại, và chính điều đó làm cho câu trả lời dùng được. Một giá trị bị giữ lại được báo cáo là vắng mặt với một dấu bên cạnh — value_withheld và source_withheld trên một thiết lập, withheld trên một mục lớp, uri_withheld và error_withheld trên một bản ghi plugin, và workspace_root_withheld trên câu trả lời. Một thiết lập không ai đặt mang giá trị rỗng mà dạng của nó hiển thị, và không mang dấu nào. “Máy chủ này không cho bạn biết khóa ký nằm ở đâu” và “không có khóa ký nào được cấu hình” là hai câu trả lời khác nhau đòi hỏi các bước tiếp theo khác nhau, và một bản đọc báo cáo chúng giống hệt nhau sẽ không cho bạn biết điều gì để hành động. Mỗi câu trả lời cũng luôn mang host_locations_withheld, cho biết bạn đang cầm câu trả lời nào trong hai: một câu trả lời không mang dấu nào thì nếu không có trường này sẽ giống nhau dù quy tắc này đã định hình nó mà không có gì trên máy chủ cần giữ lại, hay quy tắc chưa bao giờ được áp dụng. Văn bản dễ đọc bên cạnh các trường nói cùng điều đó bằng lời.

Quy tắc là một thuộc tính chứ không phải một danh sách tên trường: một giá trị bị giữ lại khi nó chỉ một vị trí trong hệ thống tệp của máy chủ, bất kể ai đặt nó và nó đến từ lớp nào. Một giá trị được thêm vào một trong hai bản đọc sau này cũng tuân theo cùng thuộc tính đó.

Trên đầu vào và đầu ra chuẩn, mỗi khả năng cũng có thể truy cập dưới dạng công cụ đặt tên theo lệnh của nó — cli-config-show và cli-plugin-list — chạy lệnh đó trong một tiến trình riêng và trả lại văn bản mà lệnh in ra; qua HTTP, các công cụ đó không tồn tại. Hai công cụ được mô tả ở đây mang các giá trị thay vào đó, nên bạn đọc được một khả năng có được gắn hay không, hoặc lấy ra phiên bản của một plugin, mà không phải phân tích ngược một bố cục cột về dữ liệu mà nó được render từ đó.

Hỏi những gì có thể gắn vào, và cái gì có thể kết nối tới cái gì

Hai công cụ trả lời những câu hỏi mà nếu không có chúng, trợ lý sẽ phải đoán: những Features nào có thể gắn vào một nút, và một nút có thể kết nối tới cái gì. Cả hai chạy cùng phép so khớp nhãn mà trình biên dịch chạy, nên những gì trợ lý đề xuất cho bạn là tập hợp mà một bản dựng sẽ khớp, chứ không phải một tập hợp được suy ra từ lược đồ.

attach-candidates báo cáo các Features có phạm vi áp dụng được khai báo mà nhãn của một nút thỏa mãn. Hãy chỉ định nút theo đúng một trong ba cách:

  • node — metadata.name của một thực thể trong workspace, như list-entities báo cáo. Phép so khớp chạy trên các nhãn mà tài liệu đó khai báo.
  • graph_node cùng với release — một nút trên đồ thị đã biên dịch, được định khóa như đồ thị định khóa nó, bao gồm cả dạng có định danh đầy đủ mà một nút do sub-aggregate đóng góp mang theo. Phép so khớp chạy trên các nhãn đã hoàn thiện của nút đó, tức là các nhãn mà một bản dựng đánh giá.
  • labels — một tập nhãn đứng riêng, không chỉ định nút nào. Nó không cần tọa độ nào cả, nên nếu bạn đã có nhãn của một nút thì đây là dạng nên dùng; nó không tra cứu gì và không dựng lại đồ thị nào.

Câu trả lời mang theo các nhãn mà phép so khớp đã chạy trên đó và cho biết chúng đến từ tập nào trong ba tập trên, nên bạn có thể giải thích bất kỳ ứng viên nào — hoặc việc không có ứng viên — từ chính câu trả lời thay vì tự suy luận lại. Đọc lại chúng theo một cách thứ hai chính là cách mà hình dung của bạn về nhãn của một nút và của trình biên dịch trở nên khác nhau.

Để hỏi những gì có thể gắn vào một kết nối mà một nút vẽ ra, hãy thêm connection bên cạnh graph_node và release — gồm socket và alias của nó, đúng như tác giả đã viết. Một kết nối mang các phần gắn lấp vào các khe mà socket của nó khai báo trên Component tiêu thụ, nên khi đó câu trả lời cũng mang theo slots: mỗi khe mà socket khai báo, với selector, required, inject, sensitive và description đúng như Component khai báo, cùng các candidates có thể lấp vào khe đó. Đó là các Features có phạm vi áp dụng mà nhãn của nút thỏa mãn và có nhãn riêng được selector của khe chấp nhận — hai quy tắc mà một bản dựng áp cho một phần gắn như vậy — nên các ứng viên của một khe luôn nằm trong số ứng viên của chính nút đó. Khi không có gì có thể được lấp, slots rỗng và noSlotReason cho biết lý do: feature-created-connection (một Feature đã vẽ kết nối, và không có gì được gắn vào kết nối như vậy), ad-hoc-socket (socket là một socket mà Component không khai báo) hoặc no-slot-declared (socket không khai báo khe nào). Đừng hiểu một slots rỗng là “không có gì khớp”; lý do đó có mặt chính là để loại trừ cách hiểu này, và nó vắng mặt ở bất cứ nơi nào có khe. candidates bên cạnh chúng giữ nguyên ý nghĩa — những gì có thể gắn vào chính nút — và document, nếu bạn gửi, không thay đổi gì ở đây. connection đặt bên cạnh node hoặc labels, hoặc không chỉ định socket hay alias, sẽ bị từ chối, và một kết nối mà nút không vẽ ra cũng vậy. Đây là những câu trả lời giống với câu trả lời mà language server đưa ra, theo cùng các điều kiện.

connection-candidates báo cáo các socket phụ thuộc mà một thực thể khai báo và, cho từng socket, các Components trong workspace có nhãn được khai báo thỏa mãn ràng buộc mà socket đó khai báo đối với đích của nó. Nó nhận metadata.name của thực thể trong node. Khác với attach-candidates, nó không có dạng không cần tọa độ: ở đây không có dạng tập nhãn, vì các socket được đọc từ chính khai báo của thực thể được chỉ định.

Hai nửa của nó không đầy đủ như nhau, và câu trả lời cho biết nửa nào là nửa nào — đừng trình bày chúng như một danh sách duy nhất. Các đích là đầy đủ: đó là các component mà cùng ràng buộc đó chấp nhận trong một bản dựng. Các socket thì không, và không thể đầy đủ. Bên tiêu thụ có thể tự tạo một kết nối nhưng chỉ có thể tiêu thụ những gì bên cung cấp khai báo, nên tác giả hoàn toàn có thể viết một socket mà thực thể trong catalog chưa từng khai báo, và các socket đã khai báo là một điểm khởi đầu hữu ích chứ không phải tập hợp các tên hợp lệ. Vì vậy mỗi socket cho biết nó là declared hay ad-hoc, và câu trả lời cho biết thực thể đó có chấp nhận một socket chưa khai báo hay không — bề mặt phụ thuộc của một Component chấp nhận, vì tác giả sở hữu topo của ứng dụng mình; bề mặt gắn của một Feature thì không, vì một phần gắn tham gia vào topo mà Feature được gắn khai báo chứ không tự tạo ra topo. Sự mở này là hệ quả của quyền tự do soạn thảo của bạn, không phải một lỗ hổng: hãy truyền socket với một tên mà thực thể không khai báo để hỏi về nó.

Cả hai trả lời rồi dừng. Không công cụ nào tạo phần gắn, tạo cạnh, ghi vào tệp nào, hay đề xuất văn bản cho những việc đó; việc soạn và áp dụng bất kỳ chỉnh sửa nào tiếp theo là của bạn.

Cả hai trả về cùng một định danh tối thiểu mà mọi câu trả lời khác ở đây dùng — kind, tên và tệp nguồn — và không gì hơn. Mọi thứ khác bạn muốn hiển thị về một thực thể đã có sẵn trong list-entities cho cùng ba trường đó, nên bạn ghép hai câu trả lời thay vì đọc hai bản sao có thể mâu thuẫn nhau. Cả hai từ chối một tên mà chúng không phân giải được thay vì trả lời bằng một danh sách rỗng, vì cùng lý do như phần còn lại của bề mặt này: một câu trả lời rỗng sẽ báo cáo một lỗi gõ nhầm như một đối tượng không có gì để đề xuất. Một lệnh gọi labels không có tên nào để gõ nhầm, nên một kết quả rỗng ở đó có đúng ý nghĩa của nó.

Mọi thứ máy chủ đọc để tham chiếu đều được phục vụ từ máy này — các JSON Schema được tích hợp sẵn trong tệp nhị phân và tài liệu được đọc từ bộ nhớ đệm gói tài liệu mà máy lưu giữ, như mô tả bên dưới. Việc soạn một tài liệu khởi đầu, xác thực, mô tả, dựng và lint đều chạy trên workspace của bạn và các bộ nhớ đệm cục bộ, và không việc nào tự ý truy cập registry: một lần render phục vụ một tham chiếu bên ngoài đã ghim từ kho lưu trữ định địa chỉ theo nội dung và từ chối một tham chiếu chưa ghim thay vì tải nó về, đó là điều giữ cho toàn bộ vòng lặp kiểm tra và render chạy ngoại tuyến. Có hai lần đọc registry mà bạn có thể yêu cầu: describe với một tham chiếu registry, lệnh này tải đúng một tọa độ đó, không ghi gì, và qua HTTP chỉ truy cập registry mà workspace được phục vụ đã được cấu hình; và scaffold khi được gửi example hoặc list, lệnh này lấy gói tài liệu từ registry mặc định của workspace khi máy không giữ bản sao nào mà chính sách chữ ký của workspace chấp nhận, và xác minh nó trước khi lưu giữ, như aggrega scaffold --example vẫn làm. Phát hành và ký là phía còn lại có chủ đích của điều đó, và đã được trình bày ở trên.

Nằm giữa hai phía đó là việc phân giải các phụ thuộc của một Release, đây là việc duy nhất ở đây có thu nhận nội dung: nó truy cập registry vì được yêu cầu phân giải phụ thuộc chính là được yêu cầu tải chúng về. Việc này chỉ xảy ra khi bạn yêu cầu, và có đúng hai cách để yêu cầu — gọi pull, công cụ chỉ làm đúng việc này, hoặc gửi auto_pull cho build, công cụ thực hiện cùng phép phân giải đó như bước đầu tiên của bản dựng. Ngoài ra không có gì tự kéo về thay bạn, và một bản dựng mà bạn không gửi auto_pull sẽ không truy cập registry nào. Thiết lập duy nhất thay đổi điều này là auto_pull của chính workspace: một workspace được cấu hình như vậy đang yêu cầu mọi bản dựng trong nó phân giải trước, bất kể bản dựng đó được chạy từ đâu, điều này được trình bày bên dưới.

Ngoại lệ duy nhất trong số các lần đọc tham chiếu đó là việc thu nhận chính gói tài liệu, và việc này diễn ra tách biệt khỏi mọi lần đọc. Gói được lưu một lần cho mỗi máy, trong bộ nhớ đệm mà mọi dự án Aggrega dùng chung, một bản sao cho mỗi registry và phiên bản — nên một máy chủ được khởi động trong thư mục không thể tạo bộ nhớ đệm workspace vẫn giữ được nó (xem aggrega cache). Khi máy chủ khởi động, trước khi trả lời bất cứ điều gì bạn gửi, nó tìm ở đó một bản sao mà phép kiểm tra chữ ký của chính workspace bạn chấp nhận — cùng phép kiểm tra mà một lần pull gói phải tuân theo — và chỉ pull gói, thông qua cùng các thiết lập egress mà phần còn lại của CLI dùng, khi không có bản nào. Gói mà nó tìm là gói được phát hành cho phiên bản aggrega mà máy chủ đang chạy, hoặc, khi không có gói nào được phát hành cho phiên bản đó, là gói mới nhất được phát hành cho một phiên bản trước đó — cùng lựa chọn mà aggrega explain và aggrega scaffold --example đưa ra — và mọi trang nó phục vụ, cũng như mọi phần giải thích, đều được đọc từ gói mà nó đã thu nhận. Vì vậy các trang đã có sẵn khi có bất cứ thứ gì yêu cầu, bất kể client của bạn gửi gì trước, và một máy chủ khác, hoặc aggrega explain trong một dự án khác, tìm thấy cùng bản sao đó thay vì tải lại.

Khi đó, việc phục vụ một trang là một lần đọc bản sao đó, và nó không truy cập registry nào. Trước khi một trang được phục vụ, các chữ ký lưu cạnh bản sao được xác minh lại theo cơ chế kiểm tra của workspace của bạn, nên một bản sao được thiết lập lỏng hơn của một dự án khác cho vào sẽ không được phục vụ cho bạn: nơi cơ chế kiểm tra ghim một khóa hoặc một trust root, việc xác minh đó chạy ngoại tuyến, còn nơi nó không ghim cái nào — cơ chế kiểm tra tích hợp sẵn của hub chính thức là một trường hợp như vậy — nó lấy trust root công khai của Sigstore, giống như một lần pull. Một workspace ngoại tuyến không thể tải trust root đó, nên khi ngoại tuyến nó xác minh dựa trên trust root mà một lần tải trực tuyến trước đó trên máy này để lại trong bộ nhớ đệm mà Sigstore client giữ dưới .sigstore trong thư mục home của bạn, bất kể lần tải đó đã cách đây bao lâu, và không tải gì cả; trên một máy chưa bao giờ tải nó, việc kiểm tra không thể chạy ngoại tuyến, bản sao không được phục vụ, và luồng log sẽ nói rõ điều đó. Việc xác minh đó chạy một lần cho mỗi bản sao và mỗi cơ chế kiểm tra trong khi server chạy, và các trang được đọc sau đó được phục vụ dựa trên những gì nó đã chấp nhận: một bản sao được tải sau đó, một workspace có cơ chế kiểm tra khác — kể cả một trust root được ghim bị sửa tại chỗ —, một lần đọc thực hiện ngoại tuyến, hoặc một lần đọc ngoại tuyến tìm thấy một trust root khác còn lại trên máy đều được xác minh riêng. Một bản sao mà cơ chế kiểm tra của bạn đã từ chối sẽ được kiểm tra lại ở lần đọc tiếp theo, để một lần tải mà sau đó đã chấp nhận nó không bị bác bỏ. Nếu không thể lấy được bundle, hoặc bản sao duy nhất là bản mà cơ chế kiểm tra của bạn từ chối và việc tải lại nó theo cơ chế kiểm tra đó thất bại, server vẫn khởi động và mọi bề mặt khác vẫn hoạt động; các yêu cầu tài liệu trả lời not-found, và luồng log của server nói rõ lý do.

Build dựa trên nội dung mà một Release đã ghim sẵn

build render một Release thành các artifact của nó trong bộ nhớ, và một lần render có thể yêu cầu nội dung từ một URL từ xa — chẳng hạn schema values của một chart có tham chiếu từ xa. Các đầu vào bên ngoài được đóng băng trong suốt lời gọi. Một tham chiếu mà lockfile của Release đã ghim được phục vụ từ kho lưu trữ định địa chỉ theo nội dung, tức là đọc nội dung đã có trên đĩa chứ không phải tải về. Một tham chiếu mà lockfile không ghim sẽ bị từ chối và được nêu tên thay vì được tải về: điều bạn yêu cầu là một lần render, và việc thu nhận một tham chiếu vừa chạm tới mạng vừa ghi một blob vào kho như một tác dụng phụ của việc tạo ra các byte. Sự đóng băng đó là một thuộc tính của lần render. Phân giải mới là bước thu nhận: nó render Release để biết lần render đó yêu cầu những tham chiếu từ xa nào, tải chúng về và ghi lại chúng trong cùng lần ghi lockfile chứa các ghim phụ thuộc. Vì vậy, điều mà phân giải thay đổi là những tham chiếu nào đã được ghim vào lúc một lần render chạy, chứ không bao giờ là những gì một lần render được phép chạm tới — và một tham chiếu mà không lần phân giải nào ghim sẽ bị từ chối trên một lời gọi đã phân giải trước y hệt như trên một lời gọi không phân giải.

Các tệp được trả về đúng là các byte mà một lần build thật tạo ra, và có hai điều cùng nhau làm cho điều đó đúng. Thứ nhất là sự đóng băng ở trên: một tham chiếu đã ghim được đọc từ kho chứ không được tải về. Thứ hai là lockfile được đọc vẫn mô tả đúng những gì Release phân giải thành — nên build kiểm tra điều đó và từ chối một lockfile không còn khớp, y hệt như aggrega build làm tại terminal. Bản thân việc đọc các byte đã ghim không nói lên điều gì về việc chúng có phải là các byte đúng cần đọc hay không.

Cả ba trạng thái của lockfile, để lập trường được nêu rõ. Khi hoàn toàn không có lockfile, build render từ bất cứ thứ gì workspace đã ghim và từ chối mọi tham chiếu bên ngoài mà nó không phục vụ được, nêu tên từng tham chiếu; tự nó không yêu cầu lockfile cũng không ghi lockfile, và điều đó không thay đổi bởi phép kiểm tra ở trên — không có lockfile để so sánh, nên không có gì bị từ chối. Với một lockfile khớp, nó render. Với một lockfile không còn khớp, nó từ chối, và lời từ chối nêu cách khắc phục: gọi pull với cùng release và không có upgrade_targets, thao tác này đối chiếu lại lockfile với những gì Release phân giải thành hôm nay. Lời từ chối cũng kèm theo dạng terminal của chính thao tác đó, aggrega pull --release <release>. Cách gọi nào cũng khắc phục được; đó là một thao tác có thể tiếp cận từ hai nơi, không phải hai chỉ dẫn để lựa chọn. Khi pull hoàn tất mà lời từ chối vẫn quay lại, hai lời gọi đã phân giải trên các đầu vào khác nhau — thường gặp nhất là catalog_dirs được truyền cho lời gọi này mà không cho lời gọi kia, hoặc cấu hình workspace bị sửa giữa hai lần — và lời từ chối nói rõ điều đó: hãy gọi cả hai với cùng các đầu vào.

validate và describe khi chỉ được gửi một release cũng bị ràng buộc bởi cùng lockfile đó. Với một lockfile không còn khớp với những gì Release phân giải thành, mỗi công cụ từ chối thay vì trả lời, văn bản của nó mang điểm dừng do sai lệch mà build dùng để từ chối và cùng cách khắc phục — như aggrega validate --release và aggrega inspect --closure từ chối tại terminal. Với một lockfile khớp, hoặc khi không có lockfile, mỗi công cụ trả lời như bình thường.

Yêu cầu một lần build phân giải các phụ thuộc của nó trước

Gửi auto_pull và lần build sẽ phân giải trước khi render. Nó thực hiện cùng phép phân giải mà pull thực hiện — chính thao tác đó, không phải một thao tác thứ hai viết riêng cho build, nên một workspace được lấp đầy bởi một lần build và một workspace được lấp đầy bởi một lời gọi pull là giống hệt nhau — ghi lockfile của Release, rồi render dựa trên những gì nó đã ghi. Bước đó chạm tới một registry và ghi dữ liệu, điều mà không phần nào khác của build làm ngoài write, và write không chạm tới registry nào — nên nó bị tắt trừ khi được yêu cầu.

Nó giải quyết hai trường hợp từ chối ở trên mà không cần rời khỏi giao thức. Một Release chưa ai phân giải sẽ render từ bất cứ ghim nào tình cờ có ở đó và từ chối phần còn lại; một lockfile đã lệch sẽ dừng hẳn lần build. Gửi auto_pull sẽ phân giải trước và render dựa trên một lockfile được suy ra từ bao đóng mà lần build này hướng tới, nên cả hai trường hợp đều trả về một lần render thay vì một thứ cần đi sửa. Khi bạn muốn phân giải và render là hai bước riêng — để đọc những gì đã được ghim trước khi render — hãy gọi pull rồi build, tức là cùng hai thao tác đó với một lần xem xét ở giữa.

Một lời gọi render Release một lần. Việc tìm ra một Release sử dụng những tham chiếu từ xa nào tự nó đã là một lần render, nên một lần phân giải đã render chính Release mà lần build hướng tới — dựa trên chính các ghim nó vừa ghi, với mọi cổng kiểm tra mà một lần build chạy. Lần build được trả lời từ lần render đó thay vì lặp lại nó, đó là lý do gửi auto_pull tốn một lần phân giải chứ không phải một lần render thứ hai. Chỉ một lần render đã hoàn tất mới được dùng như vậy: khi một lần phân giải đã ghim các phụ thuộc nhưng không thể hoàn tất việc phát hiện các tham chiếu bên ngoài, lần build tự render dựa trên các ghim đã có, và khi đó một tham chiếu chưa ghim sẽ dừng nó kèm theo tên thay vì trả về một danh sách tệp thiếu so với những gì một lần build tạo ra.

Những gì được trả về cho biết những gì đã được phân giải. Một lần build đã lấp đầy mang dependency_resolution trong câu trả lời, theo dạng mà pull trả lời: lockfile nó đã ghi, mọi tham chiếu mà lần phân giải đã chạm tới cùng phiên bản mỗi tham chiếu được phân giải thành và nơi lần phân giải của build này lấy nó, các số đếm mà lockfile chứa sau đó, và bản tường thuật của chính lần phân giải theo từng dòng. Một lần build không lấp đầy hoàn toàn không mang trường đó, nên sự hiện diện của nó là cách bạn phân biệt hai trường hợp mà không cần đọc đĩa. Các tệp đã render được báo cáo đúng như đối với bất kỳ lần build nào khác, và chúng vẫn được trả về trong bộ nhớ trừ khi lời gọi cũng được gửi write — phân giải ghi lockfile và bộ nhớ đệm artifact, không bao giờ ghi một artifact.

Một workspace có thể yêu cầu điều này thường trực, và một lời gọi không thể tắt nó. Thiết lập auto_pull riêng của workspace bật cùng bước đó cho mọi lần build trong workspace đó, và auto_pull trên một lời gọi bổ sung cho thiết lập đó chứ không ghi đè nó: chỉ cần một trong hai là đủ, và không có đối số nào ngăn một lần phân giải mà workspace đã yêu cầu. Đó cũng là cách thiết lập này và aggrega build --auto-pull kết hợp tại terminal, nên một workspace trả lời theo cùng một cách bất kể lần build đến qua bề mặt nào.

Việc từ chối được báo cáo chứ không bị nuốt đi, và với các provider mà binary này mang theo, một lần từ chối sẽ dừng lần render: provider đã yêu cầu tham chiếu trả lại lời từ chối, nên lời gọi trả lời bằng lỗi đó và không trả về tệp nào. Tham chiếu được nêu tên ở nơi người đọc có thể xử lý, kèm theo lệnh ghim nó: aggrega pull --release <path>. Cùng thao tác ghim đó có thể tiếp cận trên bề mặt này dưới dạng công cụ pull, được mô tả trong Phân giải những gì một Release phụ thuộc vào bên dưới, nên một trợ lý gặp lời từ chối này có thể xử lý mà không cần rời khỏi giao thức. Một lần render đã được ghim đầy đủ không nói gì về những điều này. Xem aggrega pull để biết việc ghim tải về và ghi lại những gì, và aggrega build, nơi một tham chiếu chưa ghim được báo cáo và dừng lần chạy theo cùng cách.

Ghi các artifact vào nơi aggrega build ghi chúng

Gửi write thì bản render đã hoàn tất cũng được ghi vào dist/ tại thư mục gốc của workspace, nơi aggrega build ghi nó. Thư mục này chính là thư mục mà dòng lệnh dựng bên dưới cùng thư mục gốc workspace, và thao tác ghi chính là thao tác mà lệnh đó thực hiện, nên với một Release trong một workspace, aggrega build, lệnh aggrega/build của language server không nêu outputParent, và lệnh gọi này ghi ra cùng một cây thư mục, giống nhau đến từng byte, và gọi tên thư mục đó như nhau — dòng kết thúc của lệnh, outputDirectory của language server và output_dir của câu trả lời này. Một dist là liên kết dẫn ra ngoài workspace bị từ chối trước khi bất cứ thứ gì trong đó bị xóa hoặc được ghi, giống như tại terminal. Nếu bỏ qua, vốn là mặc định, các artifact được trả về trong bộ nhớ và không có gì được ghi.

Thư mục gốc workspace là của chính lệnh gọi. Qua đầu vào và đầu ra chuẩn, đó là thư mục gốc của workspace mà lệnh gọi đã xác định, như Lệnh gọi được trả lời trong workspace nào trình bày: thư mục gốc mà workspace_root nêu, nếu không thì thư mục gốc mà server được khởi chạy cùng, nếu không nữa thì workspace tìm được từ thư mục server được khởi động trong đó — và, khi một Release được nêu bằng đường dẫn tuyệt đối chuyển lệnh gọi vào workspace riêng của Release đó, thì là thư mục gốc của workspace ấy. Đó là thư mục gốc mà aggrega build ghi bên dưới cho cùng Release và cùng thư mục gốc được nêu, nên thư mục mà server tình cờ chạy trong đó chỉ nhận một dist khi thư mục đó là thư mục gốc mà lệnh gọi đã xác định, như khi mở terminal tại đó. Qua HTTP, đó là workspace mà server phục vụ, và không có gì được ghi ra ngoài nó.

Việc ghi chạm tới workspace, nên qua HTTP nó cần aggrega:workspace-write. Một lệnh gọi được gửi write chạm tới workspace cho lệnh gọi đó, đúng như một bản build phân giải các phụ thuộc của nó trước: một thông tin xác thực chỉ mang aggrega:read được trả lời 403 nêu tên aggrega:workspace-write, và không có gì được ghi, còn một server có mcp.deny_reach nêu workspace sẽ từ chối lệnh gọi và nêu tên thiết lập đó. Công cụ vẫn nằm trong danh sách công cụ của mọi bên gọi, và một bản build không được gửi write vẫn khả dụng cho bên gọi chỉ có phạm vi đọc.

Nó ghi sau cùng. Khi có thêm auto_pull, lệnh gọi phân giải, render rồi mới ghi, theo đúng thứ tự đó. Một lệnh gọi bị từ chối ở bất kỳ bước nào trước đó — Release, workspace, một thư mục catalog, việc phân giải, việc render — không ghi artifact nào.

Câu trả lời nêu những gì đã được ghi. output_dir là thư mục — đầy đủ qua đầu vào và đầu ra chuẩn, dist qua HTTP — và files liệt kê từng tệp đã ghi, tương đối với thư mục đó, kèm nội dung khi dùng response_format: detailed và chỉ đường dẫn khi dùng concise; phần văn bản cho biết đã ghi bao nhiêu tệp và ở đâu. Một lệnh gọi không được gửi write không mang output_dir, nên việc thiếu trường này cho bạn biết không có gì được ghi. Một thao tác ghi thất bại sau khi render đã hoàn tất — chẳng hạn vào một thư mục gốc workspace mà không ai được ghi — được trả lời là thất bại, nêu thư mục và nguyên nhân, và không liệt kê tệp nào là đã ghi: một phần dữ liệu có thể đã nằm trên đĩa, và nêu các tệp đã render là đã ghi sẽ khẳng định nhiều hơn những gì đã xảy ra.

Không đối số nào nêu một thư mục, và không đối số nào yêu cầu trace. Nơi các artifact được ghi do workspace mà lệnh gọi đã xác định quyết định, không bao giờ do lệnh gọi, và một bản build được ghi từ đây không để lại thư mục .trace nào bên cạnh đầu ra của nó; bản build có trace là aggrega build --trace.

Một bản build cho bạn biết gì ngoài các tệp của nó

Một bản build mang theo mọi cảnh báo mà nó đã phát ra, ngay trên câu trả lời. Đây là những phát hiện mà aggrega build in ra trong khi chạy — một tên chỉ cách một tên đã khai báo một lần chỉnh sửa, một tham số không có gì đọc, một target không thể đáp ứng một trường đã viết, một phán quyết quản trị không gây dừng, một thư mục ranh giới mà một Release kế thừa từ Release nó mở rộng và phân giải về cùng một đường dẫn, một thuộc tính mà một Component hoặc Feature mà Release chạm tới khai báo trong cả hai trụ values và infra. Không cái nào trong số đó thay đổi kết quả: một bản build mang cảnh báo vẫn thành công, và các tệp nó trả về là các tệp nó đã tạo ra. Chúng đến theo thứ tự mà terminal in ra, nên người đọc so sánh hai bên sẽ thấy một chuỗi chứ không phải hai: đầu tiên là mọi thứ mà quá trình render phát ra, theo thứ tự nó phát ra, rồi đến các phát hiện về Release và những gì nó chạm tới, điều mà aggrega build in ra khi quá trình render đã trả về, và cuối cùng, với một bản build được gửi write, là cảnh báo nêu tên từng tệp mà việc ghi tìm thấy bên cạnh các tệp của chính nó nhưng không do nó ghi, những tệp mà nó để nguyên tại chỗ — chính cảnh báo mà aggrega build in ra sau khi đã ghi xong các tệp của mình (Các tệp mà bản build không ghi).

Chúng nằm trên câu trả lời chứ không chỉ trong văn bản tóm tắt, vì một trợ lý điều khiển bề mặt này không đọc terminal nào, và một phát hiện không ai được thông báo thì cũng như chưa từng được tìm ra. Mỗi phát hiện mang một severity — warn cho điều cần chú ý, info cho một quan sát được ghi lại — và một message; một code nếu lớp của nó gán mã, để bạn có thể phản ứng với một điều kiện cụ thể mà không cần khớp văn bản; và một key_path nêu tên khóa trong tài liệu đã viết mà phát hiện nói đến, nếu nó nói về một khóa. Một phát hiện về hình dạng của topology đã triển khai không nêu khóa nào, vì tọa độ của nó thuộc về bản triển khai chứ không thuộc về một tài liệu, và thay vào đó nó nói nó liên quan đến điều gì trong message của mình.

Hai loại phát hiện mà terminal in ra đến câu trả lời này ở nơi khác ngoài advisories, vì mỗi loại có một chỗ nói được nhiều hơn. Một dấu hiệu ngừng hỗ trợ đã được ghi lại nằm trên deprecations, dù lockfile ghi nhận nó đối với một tham chiếu đã ghim hay bản ghi tin cậy plugin bên cạnh ghi nhận nó đối với một plugin được gắn trong một vai trò trả về phán quyết chấp nhận-hoặc-từ chối. describe của một Release nêu cùng tập hợp đó trong deprecations của chính nó, và validate của một Release nêu trong số các notices của nó, mỗi bên đều giữ nguyên phán quyết; một bản ghi tin cậy có tồn tại nhưng không đọc được sẽ khiến cả hai lời gọi bị từ chối thay vì được coi như một bản ghi không ghi nhận gì. Một parent mà một entity kế thừa nhưng không thể phân giải sẽ dừng bản build, nên nó được nêu tên trong văn bản của lời từ chối thay vì được liệt kê như một phát hiện không thay đổi gì. Một loại bị giới hạn bởi những gì công cụ này tải chứ không bởi những gì câu trả lời của nó mang: aggrega build tải mọi thư mục catalog đã cấu hình trước khi phân giải một Release, và một thông báo về một hình dạng catalog đã ngừng hỗ trợ sẽ đến từ lần tải đó, trong khi công cụ này chỉ đọc những gì Release chạm tới và không thực hiện lần tải như vậy, nên nó không báo cáo thông báo như thế. Hiện tại không bản build nào phát ra thông báo này, nên cả hai báo cáo cùng các phát hiện.

Một Release không phát ra gì thì không nói gì: khóa vắng mặt chứ không hiện diện và rỗng, nên chỉ riêng sự hiện diện của nó đã cho bạn biết có điều gì đó cần đọc.

Một bản build bị từ chối trả lại những gì

Một bản build bị từ chối trả lời trong cùng các trường mà một bản build thành công trả lời, được điền đến mức lượt chạy đã đi tới. Nó trả về được đánh dấu là thất bại với nội dung sửa lỗi làm văn bản, và payload có cấu trúc nằm bên cạnh văn bản đó thay vì bị văn bản thay thế. Một lời từ chối phát sinh trong khi Release được render sẽ dùng lời lẽ của trình biên dịch, như Lời từ chối phát sinh trong khi render bên dưới mô tả, và thêm một trường riêng. Các khuyến cáo có trong đó: các giai đoạn đã chạy đã nêu ra những gì chúng nêu ra, và đó là những phát hiện bạn phải xử lý để vượt qua lời từ chối, nên chúng đến dưới dạng các mục bạn có thể so khớp thay vì văn xuôi bạn phải phân tích. deprecations và declined_external_inputs có trong đó vì cùng lý do — một dấu đánh ngừng hỗ trợ được báo cáo vì một dấu đã được ghi nhận, và một tham chiếu bị từ chối được báo cáo vì một tham chiếu đã bị từ chối, và không sự việc nào trong số đó là hệ quả của cách lượt chạy kết thúc.

files không báo cáo gì khi bị từ chối, và đó không phải là trường để đọc kết quả. Không có gì được xuất ra, nên không có artifact nào để nêu tên. Đừng rẽ nhánh dựa trên việc khóa có mặt hay không: nó được báo cáo trong cả hai trường hợp, và một files rỗng tự nó không thể phân biệt một bản build bị từ chối với một bản build đã chạy và không xuất ra gì. Hãy đọc cờ thất bại trên kết quả — đó là bộ phân biệt riêng của giao thức — và đọc files đúng với bản chất của nó, danh sách những gì đã được render, và cũng đã được ghi nếu lời gọi được gửi kèm write.

Điều giới hạn các khuyến cáo khi bị từ chối là lượt chạy đã đi được bao xa, chứ không phải câu trả lời có thể mang được những gì. Một lời từ chối từ một bước kiểm tra chạy trước khi Release được phân giải — một mục được ghim trong cache không còn khớp với digest được ghi cho nó và không thư mục catalog nào chứa các byte được ghim, hoặc những gì Release phụ thuộc vào không thể phân giải — không báo cáo khuyến cáo nào, vì chưa có gì được nêu ra. Các phát hiện về cách một Release kết hợp với Release mà nó mở rộng được nêu ra ngay khi nó được phân giải, trước mọi bước kiểm tra theo sau, nên mọi lời từ chối về sau đều mang chúng: Manifest ánh xạ một kiểu lên một recipe không triển khai nó, một thực thể mà Release chạm tới không thỏa mãn schema của nó, lockfile không còn khớp với những gì Release phân giải ra. Các phát hiện riêng của quá trình render được nêu ra khi render chạy, nên một lời từ chối từ một trong các bước kiểm tra trước đó không mang phát hiện nào trong số đó, và một lời từ chối từ quá trình render mang mọi thứ đã được nêu ra trước nó. Vì vậy hãy đọc advisories khi bị từ chối đúng như khi bạn đọc nó lúc thành công: những gì lượt chạy này đã phát hiện, theo thứ tự một terminal in ra.

Một lời từ chối vì một thực thể kế thừa từ một parent không thể phân giải sẽ nêu tên mọi sự kế thừa như vậy trong văn bản của nó, bằng lời lẽ mà aggrega build in ra cho nó, để bạn biết cần sửa cái nào. Chi tiết đó là lý do bản build dừng lại, đó là lý do nó nằm trong văn bản thay vì trong các phát hiện không làm thay đổi gì; các phát hiện về kết hợp được nêu ra trước nó nằm trên advisories như với mọi lời từ chối về sau.

Một thư mục catalog mà Release đọc nhưng không thể duyệt sẽ bị từ chối trước khi bất cứ thứ gì được ghi, như aggrega build từ chối nó. Đó là một thư mục mà lời gọi nêu tên trong catalog_dirs nhưng không tồn tại, như aggrega build từ chối một thư mục --catalog không tồn tại, hoặc một thư mục có tồn tại nhưng không thể đọc. aggrega build tải mọi thư mục mà Release đọc trước khi phân giải Release, và dừng lại ở thư mục nó không thể duyệt; build duyệt cùng các thư mục đó trước tiên, không đọc tài liệu nào trong đó, trước mọi bước phân giải phụ thuộc và trước quá trình render — nên một bản build được gửi kèm auto_pull không ghi lockfile nào, và không có gì được render. Văn bản nêu tên thư mục như dòng lệnh báo cáo, trên một dòng: thư mục, catalog load, và lý do mà hệ thống tệp đưa ra. Payload nêu tên Release, với một files rỗng và không có phát hiện nào, vì chưa có gì chạy. Một thư mục mà cấu hình workspace liệt kê nhưng không phải là thư mục — chẳng hạn không có gì tồn tại ở đó — sẽ bị từ chối trước bước duyệt đó, theo cùng hình thức, với văn bản mang lời từ chối mà aggrega build đưa ra cho nó, nêu tên mục đó cùng tệp cấu hình và dòng liệt kê nó (Nơi đọc các thực thể cục bộ). Một thư mục catalog chứa một liên kết dẫn ra ngoài thư mục mà các lần đọc của nó phải nằm bên trong sẽ bị từ chối ở cùng thời điểm, không có gì được ghi, văn bản nêu tên liên kết và nơi nó dẫn tới — aggrega build từ chối nó theo cùng cách.

Một ví dụ cụ thể, để hai nửa trở nên rõ ràng. Một Release khai báo một tham số mà không tham chiếu nào đọc, và quá trình render của nó sau đó không thể hoàn tất, trả về một thất bại có văn bản mang lời từ chối của quá trình render và payload mang khuyến cáo về tham số không được đọc với severity, message, code và key_path của nó — cùng một mục, với cùng các giá trị, mà cùng Release đó báo cáo trên câu trả lời khi quá trình render hoàn tất — bên cạnh mục refusal cho điều đã làm dừng quá trình render. Một Release mở rộng một Release khác và kế thừa một thư mục biên không chứa biến template nào, có Manifest ánh xạ một kiểu lên một recipe không triển khai nó, trả về lời từ chối đó với một mục advisories cho mỗi thư mục được kế thừa, mỗi mục có code là inherited-boundary-directory-is-literal. Một Release có các phụ thuộc không thể phân giải, trong một workspace mà mọi thư mục catalog được liệt kê đều tồn tại, trả về một thất bại hoàn toàn không có khóa advisories, vì chưa có gì được nêu ra khi nó dừng lại.

Lời từ chối phát sinh trong khi render

Một Release mà trình biên dịch từ chối trong khi render — một Workload nêu tên một slot mà Component của nó không khai báo, một assertion thất bại, một template không thể đánh giá — trả về lời từ chối bằng chính lời của trình biên dịch, kèm mọi nguyên nhân bên dưới nó, đúng những lời mà cli-build trả về cho cùng Release đó: nút đang được render, rồi đến phần nào trong nó đã từ chối. Khi lời từ chối nêu tên một điều kiện đã đăng ký, văn bản bổ sung tên gọi của điều kiện đó — mã ngắn và mã mô tả để đối chiếu — như explain-error sẽ làm. Văn bản mở đầu bằng việc cho biết giai đoạn nào đã từ chối: The build failed during rendering; nothing was written to disk. cho một lời từ chối do quá trình render đưa ra, và The build refused before rendering anything; nothing was written to disk. cho một lời từ chối do lần chạy của trình biên dịch đưa ra trước khi bất cứ thứ gì được render — việc kết hợp đồ thị mà quá trình render dựa vào bị từ chối, hoặc một assertion mà một Component hay một Feature khai báo.

Payload mang cùng lời từ chối đó dưới dạng một mục, refusal, để bên gọi cần sửa một tài liệu đọc được tài liệu nào, và ở đâu, mà không phải phân tích câu văn:

  • file — tài liệu mà lời từ chối trỏ tới: Recipe của một Workload, Recipe hoặc FeatureRecipe khai báo một assertion thất bại, Release hoặc Aggregate đã viết một mục mà việc kết hợp đồ thị từ chối, hoặc Aggregate của Release đối với một lời từ chối không trỏ tới tài liệu nào.
  • key_path — khóa tại đó, khi lời từ chối nêu tên một khóa: .spec.workload cho một lời từ chối về một Workload, khóa riêng của assertion dưới .spec.assertions cho một assertion thất bại, khóa riêng của mục cho một lời từ chối đối với một mục. Một lời từ chối về một Workload được đặt tại khóa workload của nó và không chi tiết hơn, vì Workload mà một phép kiểm tra đánh giá là thứ template của nó tạo ra, và một template viết ra những dòng mà tác giả của nó chưa từng viết; các đường dẫn mà lời từ chối nêu bên trong Workload đã render đó vẫn nằm trong message của nó.
  • line và column — vị trí của khóa đó, đếm từ một, cột tính theo đơn vị UTF-16. Vắng mặt khi lời từ chối không nêu khóa nào hoặc tài liệu không chứa khóa đó: vị trí chỉ được đưa ra khi tìm thấy.
  • severity — halt, mức độ nghiêm trọng của phát hiện đã dừng một bản build.
  • code và short_code — hai định danh của điều kiện, khi lời từ chối nêu tên một điều kiện đã đăng ký.
  • message — văn bản của lời từ chối, đúng như nó xuất hiện trong văn bản của câu trả lời.
  • findings — chỉ có mặt khi lời từ chối gộp nhiều phát hiện, như việc kết hợp đồ thị làm với mọi vi phạm mà nó tìm thấy: mỗi phát hiện một mục, theo thứ tự lời từ chối nêu chúng, mỗi mục cùng dạng này — với file, key_path, line, column, severity, code, short_code và message riêng. Khi đó các trường riêng của lời từ chối chỉ ra nơi phát hiện đầu tiên trỏ tới, và message của nó mang mọi phát hiện, như văn bản; dòng lệnh in mỗi phát hiện thành một chẩn đoán riêng.

Mục này có mặt bất cứ khi nào chính lần chạy của trình biên dịch từ chối — trong khi render, hoặc trước khi render: tại bước kết hợp đồ thị, hoặc tại một assertion mà một Component hay một Feature khai báo, vốn không nêu tài liệu nào, nên mục của nó nêu Aggregate. Một bản build thành công không mang mục này, và một bản build bị từ chối bởi một phép kiểm tra chạy trước khi trình biên dịch bắt đầu cũng vậy — lockfile, các ánh xạ của Manifest, những gì Release phụ thuộc vào — vì lời từ chối đó chỉ có văn bản. Một giá trị mà tác giả khai báo là nhạy cảm được giữ lại khỏi lời từ chối tại nơi trình biên dịch đưa ra nó, nên mục và văn bản mang đúng những gì cli-build và terminal mang — xem lời từ chối nói gì về một giá trị đã khai báo.

Phân giải những gì một Release phụ thuộc vào

pull phân giải các phụ thuộc catalog và nguồn của một Release vào bộ nhớ đệm cục bộ và ghi lockfile của Release đó. Nó có mặt trên bề mặt này vì một lý do đáng nêu: hai lần từ chối ở trên — một lần render đã từ chối một tham chiếu ngoài chưa được ghim, và một lần build dừng lại vì lockfile không còn khớp với những gì Release phân giải ra — đều được giải quyết bằng cách ghim, và một trợ lý phải nhờ bạn chạy một lệnh thì không có cách nào tự giải quyết chúng. Hãy đọc Những gì một trợ lý có thể làm mà không cần hỏi bạn trước để biết nó ghi những gì và phạm vi đó rộng đến đâu.

Truyền release, đường dẫn của Release, dạng tuyệt đối hoặc tương đối so với thư mục gốc của workspace — cùng một quy định mà mọi đối số đường dẫn khác ở đây sử dụng. workspace_root và catalog_dirs ghi đè việc phát hiện workspace và catalog đúng như chúng làm trên build. Cả hai đều có hiệu lực trên một máy chủ được truy cập qua đầu vào và đầu ra chuẩn; qua HTTPS, hai đối số đó bị từ chối và đường dẫn phải phân giải bên trong workspace mà tiến trình phục vụ, như Một tiến trình, một workspace trình bày.

Theo mặc định, nó đối chiếu thay vì phân giải lại. Một ghim mà lockfile đã ghi được tôn trọng và được tải về ở đúng phiên bản đó, và bị từ chối thay vì âm thầm ghim lại nếu registry không còn phục vụ các byte đó. Một tham chiếu không có ghim — mới được thêm, hoặc bị xóa khỏi lockfile bằng tay — được phân giải mới và thêm vào. Một tham chiếu không còn nằm trong các phụ thuộc đã phân giải sẽ bị loại bỏ. Do đó, một tập phụ thuộc không đổi sẽ giữ tệp giống hệt từng byte, kể cả dấu thời gian đã ghi, nên một lần gọi không thay đổi ghim nào sẽ không tạo ra diff nào cho bất kỳ ai xem xét workspace sau đó.

verify so sánh, và giữ nguyên lockfile. Nó kiểm tra lockfile đã ghi so với kết quả phân giải mà lần gọi đối chiếu ở trên sẽ thực hiện lúc này, tôn trọng các ghim đã ghi đúng như lần gọi đó, và trả về thất bại khi có sai lệch, hoặc khi không có lockfile để so sánh — vì vậy đây là cách một trợ lý biết liệu có cần ghim hay không trước khi bất cứ thứ gì ghi lại lockfile. Không có gì mà lần gọi đó ghi lại được ghi ra — không phải lockfile, không phải các danh tính plugin được ghi bên cạnh nó, không phải một entity.lock — trong khi bộ nhớ đệm nội dung được đọc và nạp đúng như lần gọi đó đọc và nạp. Nó cũng báo cáo bộ công cụ mà lockfile ghi lại: phiên bản trình biên dịch đã ghi tệp và phiên bản của từng plugin lõi mà trình biên dịch đó mang theo. Thông tin đó được báo cáo để kiểm toán và không bao giờ được so sánh với tệp nhị phân đang chạy, vì bộ công cụ không thuộc những gì lockfile ghim và việc kiểm tra nó sẽ gián tiếp ghim trình biên dịch — một khác biệt về bộ công cụ không phải là sai lệch.

upgrade_targets phân giải lại các tham chiếu bạn nêu tên, và không gì khác. Hãy đưa cho nó một hoặc nhiều URI thực thể ở dạng viết trần — core/database, không phải dạng có phiên bản. Mỗi ghim được nêu tên sẽ bị bỏ và phân giải lại về phiên bản cao nhất hiện có, trong khi mọi ghim khác và các đầu vào ngoài đã ghi được giữ nguyên. Một URI không khớp với ghim đã ghi nào cũng như attachment đã cấu hình nào sẽ bị từ chối thay vì bị bỏ qua.

Có chủ ý không có đối số nào phân giải lại mọi thứ cùng lúc. Dòng lệnh có dạng đó, và nó loại bỏ toàn bộ lockfile trước khi phân giải lại từ trạng thái registry hiện tại. Trên bề mặt này, đối số đó không tồn tại, nên lần gọi hoàn toàn không thể được tạo ra thay vì được chấp nhận rồi bị từ chối: không ai theo dõi một luồng giao thức, nên một lần loại bỏ toàn bộ không có ai để xác nhận. Khi bạn muốn điều đó, và chỉ trên đầu vào và đầu ra chuẩn, cli-pull chạy lệnh, đây là bề mặt có một người hiện diện; một bên gọi truy cập máy chủ này qua HTTP thì chạy nó tại một terminal trên máy chủ thay vào đó. verify không thể kết hợp với upgrade_targets — một bên giữ nguyên lockfile còn bên kia ghi lại nó — cũng không với pin_sources, bất kể giá trị nó mang: đối số đó quyết định liệu một lần phân giải sẽ ghi các ghim mà một entity.lock còn thiếu hay từ chối vì chúng, và một phép so sánh không ghi entity.lock nào, nên nó sẽ không làm điều nào cả. Một lần gọi gửi một trong hai cặp này bị từ chối trước khi bất cứ thứ gì được phân giải, kèm một câu nêu tên cặp đó. Schema được công bố của công cụ không nêu hai loại trừ này, vì một client hiển thị một loại trừ có thể hiểu nó như yêu cầu phải gửi verify; lời từ chối là nơi client biết đến chúng. Dòng lệnh và daemon từ chối cùng các cặp đó.

Kết quả nêu tên những gì đã được phân giải, không chỉ cho biết có thứ gì đó đã được phân giải. Nó mang lockfile mà nó đã ghi hoặc đã so sánh; resolved, mọi tham chiếu mà lần phân giải đạt tới cùng phiên bản mà mỗi tham chiếu phân giải ra, loại mà tác giả viết khi lần phân giải ghi lại một loại, và source của nó — nơi lần chạy này lấy tham chiếu, theo đúng từ mà aggrega pull --detail in ra cho cùng lần phân giải: fetched-fresh, cache-reuse, local, in-binary hoặc external; số lượng các artifact nguồn, đầu vào ngoài và danh tính plugin tin cậy mà lockfile chứa sau đó; và diagnostics, lời tường thuật của chính lần phân giải về bản thân theo thứ tự nó đưa ra từng dòng — ghim nào được dùng lại, chữ ký nào được kiểm tra, phiên bản nào bị bỏ qua vì đã bị rút. Những dòng đó đến terminal khi bạn chạy lệnh; ở đây chúng nằm trong câu trả lời, vì một bên gọi không đọc terminal nào không có cách nào khác để nhận chúng. verified chỉ có mặt trong một phép so sánh, nên việc nó vắng mặt là cách bạn phân biệt một lần chạy đã ghi với một lần chỉ so sánh. Một source mô tả lần chạy này trên máy này, nên lockfile không ghi lại nó, và describe, vốn báo cáo những gì một Release phụ thuộc vào, không nêu tên nguồn nào.

Một lần từ chối trả lời bằng cùng các trường, được điền đến mức lần chạy đã đạt tới. Khi lần phân giải đã được tính xong, resolved được mang theo bất kể kết luận — nhất là một kết luận sai lệch, vì đó là lần từ chối mà bên gọi phải quyết định cần thay đổi gì. Một lần từ chối trước thời điểm đó, chẳng hạn một đường dẫn Release không phân giải được, mang cách sửa làm văn bản của nó và không có kết quả phân giải nào, vì không có gì để mang.

Khi các ghim đã đầy đủ còn các đầu vào ngoài thì chưa, lần gọi vẫn thành công và nói rõ điều đó. Việc phát hiện những đầu vào ngoài mà một Release sử dụng là một lần render, và một lần render có thể thất bại sau khi các ghim phụ thuộc đã đúng và đã nằm trên đĩa. Báo cả lần gọi là thất bại sẽ bảo bạn làm lại công việc vốn đúng, nên incomplete_external_inputs được đặt trên kết quả thành công thay vào đó, nêu tên điều đã dừng lại: các ghim phụ thuộc đã đầy đủ, các ghim đầu vào ngoài có thể chưa.

Đây là công cụ chậm nhất ở đây, và lần đối chiếu không thay đổi gì không phải là đường tắt nhanh. Một lần phân giải phải trả toàn bộ chi phí để xác lập rằng một tập phụ thuộc không đổi, nên một lần gọi không ghi lại gì tốn bằng một lần phân giải đầu tiên — trên một Release nhỏ là vài giây chứ không phải vài mili giây, và tăng theo kích thước tập phụ thuộc. Một verify là dạng rẻ hơn trong hai dạng, vì phép so sánh bỏ qua việc đi sâu vào nguồn của từng component mà một lần chạy có ghi thực hiện. Nếu client của bạn áp đặt thời gian chờ cho mỗi lần gọi, đây là công cụ cần kiểm tra với nó. Yêu cầu được thông báo tiến độ, ở dưới, nghĩa là có thứ gì đó đến trong khi lần gọi chạy thay vì không có gì cho đến khi kết thúc — điều này giải quyết thời gian chờ khi rảnh trong client của bạn, hoặc trong bất cứ thứ gì nằm giữa bạn và một máy chủ được truy cập qua HTTP, nhưng không giải quyết giới hạn tổng thời gian một lần gọi được phép kéo dài.

Một thực thể có entity.lock không ghi pin cho một đầu vào mà nó đọc sẽ từ chối lệnh pull, và lời từ chối nêu tên bước ghi pin đó. Một Recipe hoặc FeatureRecipe mà Release dựng từ các thư mục catalog của bạn, đọc một nguồn từ xa được viết đầy đủ, hoặc nhập một tệp qua các artifact của nó, được kỳ vọng là đã mang sẵn các pin đó bên cạnh — tác giả của nó ghi chúng bằng pin, ở bên dưới. pin_sources yêu cầu lệnh gọi này chạy bước đó thay cho tác giả trên mọi thực thể như vậy thay vì từ chối, ghi entity.lock bên cạnh từng thực thể; đó chính là bước mà công cụ pin chạy, và nó ghi ra cùng các byte. Nếu bỏ qua, pin_sources_at_pull của workspace sẽ quyết định; nếu gửi, nó quyết định theo cả hai chiều, nên pin_sources: false sẽ từ chối ngay cả trong một workspace được cấu hình để pin. Một thực thể mà quá trình phân giải tìm thấy trong cache thay vì trong một thư mục catalog của bạn thì không có chỗ ghi được ở đây và không bao giờ được lệnh gọi này pin.

Pin các đầu vào riêng của một thực thể

pin ghi, trong entity.lock bên cạnh một Recipe hoặc FeatureRecipe, pin nội dung cho mọi đầu vào mà thực thể đọc từ bên ngoài tài liệu của chính nó: một nguồn từ xa có tọa độ được viết đầy đủ, và một tệp mà một mục artifacts nhập vào. Đó là cùng bước mà aggrega pin chạy tại terminal, và tệp lock nó ghi giống hệt từng byte với tệp mà lệnh đó ghi. Truyền entity, tài liệu thực thể, dạng tuyệt đối hoặc tương đối so với thư mục gốc của workspace theo cùng hợp đồng mà mọi đối số đường dẫn khác ở đây tuân theo; qua HTTPS, nó phải phân giải vào bên trong workspace mà tiến trình phục vụ.

Không nêu tên Release nào, vì không cần. Một nguồn có tọa độ không chứa template sẽ chỉ một artifact duy nhất cho mọi Release dùng thực thể, nên bước này phân giải và pin nó mà không cần gì do Release cung cấp. Một nguồn có tọa độ đến từ template thì không được pin ở đây: artifact nó chỉ đến do từng Release quyết định, và pull pin từng định danh mà nó phân giải ra trong lockfile của Release đó.

Kết quả cho biết bước này đã làm gì với tệp lock. Nó mang entity, kind và name của thực thể, cùng pinnable, có giá trị false với một kind không đọc gì mà tệp lock ghi lại — một Component hoặc một Feature — khi đó không có gì bên cạnh thực thể bị động đến và các trường khác vắng mặt. Ngược lại, nó mang lock đã ghi, changed có giá trị false khi tệp lock đã ghi sẵn mọi pin và được giữ nguyên từng byte, removed khi thực thể giờ không đọc gì mà tệp lock ghi lại và tệp lock của nó đã bị xóa, và pins, mỗi mục cho một loại pin kèm số lượng mà tệp lock giữ sau đó. dry_run trả về tệp lock mà bước này sẽ ghi dưới dạng content và không ghi gì bên cạnh thực thể; cache nội dung vẫn được nạp, vì các đầu vào được phân giải đúng như bình thường.

Nó ghi bên trong workspace và kết nối tới các host mà nguồn của thực thể nêu tên — một kho chart, một host Git, một URL — nên qua HTTP nó được chấp nhận với một thông tin xác thực mang phạm vi cho phép pull, và bị từ chối với một thông tin xác thực chỉ có quyền đọc. Trên đầu vào và đầu ra chuẩn, cùng khả năng đó cũng có thể truy cập dưới tên cli-pin, công cụ chạy lệnh; qua HTTP công cụ đó không tồn tại.

Được thông báo tiến độ của một lệnh gọi dài

Một lệnh gọi báo cáo tiến độ khi bạn yêu cầu, và việc yêu cầu chỉ là một trường. Đặt progressToken vào _meta của lệnh gọi — một chuỗi hoặc một số, do bạn chọn. Nó được trả lại trong mọi báo cáo đúng như bạn đã viết, và đó là thứ duy nhất trong báo cáo trỏ ngược về lệnh gọi của bạn: một báo cáo không trả lời gì, nên nó không mang id. Không gửi token, hoặc gửi null, thì không có gì thay đổi — lệnh gọi được trả lời giống như khi không có token. Token có bất kỳ dạng nào khác sẽ bị từ chối, trước khi lệnh gọi làm bất cứ điều gì, kèm tên hai dạng mà nó có thể có thay vì bị bỏ qua: một bên gọi đã yêu cầu được thông báo mà sau đó chỉ gặp im lặng thì không có gì để hành động.

Thứ được gửi đến là notifications/progress, mang token của bạn và một bộ đếm tăng lên sau mỗi báo cáo. Không có tổng và không có thông điệp, và cả hai đều không phải thiếu sót đang chờ bổ sung: điều mà công việc báo cáo là nó đã bước sang một giai đoạn khác, nên một tổng chỉ có thể được bịa ra và một câu chỉ có thể được soạn ở đây chứ không phải được chuyển tiếp. Hãy vẽ một chỉ báo không xác định dựa trên bộ đếm tăng dần; không có tỉ lệ nào để lấp đầy một thanh tiến độ.

Qua HTTP, câu trả lời trở thành một luồng sự kiện, và chỉ khi đã thực sự có báo cáo. Nó được phục vụ dưới dạng text/event-stream, được đánh dấu không lưu cache, và mang X-Accel-Buffering: no dành cho một trung gian mà nếu không sẽ giữ mọi sự kiện cho đến khi công việc xong và biến luồng thành một câu trả lời đơn lẻ chậm chạp. Mỗi báo cáo là một sự kiện, và câu trả lời của chính lệnh gọi là sự kiện cuối cùng trước khi luồng đóng. Trong lúc công việc im lặng, luồng gửi một dòng chú thích theo chu kỳ, đến được bất cứ thứ gì nằm ở giữa dưới dạng các byte trên một kết nối đang sống và đến client của bạn như không có gì cả. Một lệnh gọi đã yêu cầu tiến độ nhưng gặp công việc không báo cáo gì vẫn được trả lời bằng một đối tượng JSON duy nhất, vì thứ mở luồng là báo cáo đầu tiên chứ không phải token.

Trên một luồng, hãy đọc kết quả từ sự kiện cuối cùng đó thay vì từ mã trạng thái. Trạng thái và các header được ghi khi luồng mở, tức là trước khi công việc xong, nên một lệnh gọi đã báo cáo rồi từ chối sẽ mang lời từ chối của nó như sự kiện cuối cùng dưới trạng thái đã gửi. Đóng kết nối giữa chừng sẽ kết thúc công việc và không có gì thêm được ghi cho nó, đúng như Một lệnh gọi kết thúc thế nào mô tả cho mọi lệnh gọi khác.

Qua đầu vào và đầu ra chuẩn, các báo cáo là các dòng đứng trước dòng phản hồi, được đóng khung theo cách mọi thông điệp khác trên luồng đó được đóng khung — mỗi dòng một đối tượng JSON, theo thứ tự được ghi — và dòng phản hồi theo sau chúng. Không có gì được báo cáo sau khi lệnh gọi đã xong, trên cả hai phương thức truyền tải.

Việc phân giải các phụ thuộc của một Release là thứ báo cáo ở đây. pull báo cáo mỗi khi quá trình phân giải bước vào một giai đoạn. build chỉ báo cáo khi nó phân giải trước — vì bạn đã gửi auto_pull, hoặc vì thiết lập riêng của workspace yêu cầu mọi bản build trong đó phân giải — bởi việc báo cáo thuộc về bước đó: một bản build render từ các pin nó đã có thì không chạm tới gì và không báo cáo gì, nên một token trên lệnh gọi đó không thay đổi gì về cách nó được trả lời. Mọi lệnh gọi cũng báo cáo từng bước mà công việc của nó bước vào và phải chờ — đọc một registry, tải một artifact hoặc một gói tài liệu, biên dịch một plugin lần đầu — tức là các bước mà dòng lệnh hiển thị cho người dùng bên cạnh biểu tượng chờ của nó. Một lệnh gọi mà công việc không phải chờ bước nào trong số đó thì không báo cáo gì, điều này vô hại chứ không phải lỗi: câu trả lời chính là câu bạn sẽ nhận được khi không có token.

Hỏi kết nối nào được viết tại một vị trí trong tài liệu

connection-at-position trả lời câu hỏi đứng trước nửa về kết nối của hai công cụ ở trên, dành cho khi bạn có một vị trí trong tài liệu thay vì một nút trên đồ thị — một dòng bạn đang xem trong một Aggregate hoặc một Release. Truyền file, tài liệu, tương đối với thư mục gốc của workspace hoặc tuyệt đối và được đọc từ đĩa theo cách insertion-point đọc; position, gồm một line và một character đều đếm từ không, đo theo đơn vị mà position_encoding chỉ định, đúng như cách insertion-point đọc đối số đó; và release có đồ thị đã biên dịch ghi lại các kết nối. Release là bắt buộc ngay cả với một vị trí trong Aggregate: một nút đồ thị và một kết nối chỉ tồn tại trên một đồ thị đã biên dịch.

Câu trả lời là một trong hai nửa. Khi vị trí nằm trên mục của một kết nối, nó mang graphNode và connection — gồm socket, alias và document nơi vị trí được đọc — đó chính xác là những gì attach-candidates nhận cùng với graph_node và release, và là những gì attachment-container nhận để chỉ ra nơi một attachment trên kết nối đó được đặt; container đó nằm ngay bên trong mục mà vị trí rơi vào. Ngược lại, nó mang noConnectionReason, từ một tập đóng: no-connection-entry (vị trí không nằm trên mục nào mà attachment được viết vào), feature-created-connection (vị trí nằm trên mục của Release cho một kết nối do một Feature tạo ra) hoặc unknown-connection (vị trí nằm trên một mục mà Release viết cho một kết nối mà đồ thị đã biên dịch không có). Câu trả lời dạng đọc được nêu lý do bằng lời.

Một vị trí ở bất kỳ đâu bên trong một mục là ở bên trong mục đó — trên alias, trên target của nó, bên trong features của nó — và mục trong cùng sẽ thắng khi các mục lồng nhau. Một vị trí trên chính khóa của một socket, phía trên các alias dưới nó, không nằm trong mục nào cả. Các mục là những mục mà đồ thị đã biên dịch ghi lại: trong Aggregate, mọi kết nối mà một component tạo ra, tại mục của nó dưới alias của kết nối trong tài liệu nơi component được viết, mà với một component do một module được import đóng góp thì đó là tài liệu riêng của module đó; trong Release, mọi mục theo từng cạnh mà nó viết. Một kết nối được viết dưới dạng danh sách đích, và một kết nối do khối phụ thuộc riêng của một Feature tạo ra, không mang mục nào mà attachment được viết vào. Việc một khóa có phải là kết nối hay không không bao giờ được suy ra từ tên của nó.

Nó trả lời rồi dừng. Nó không ghi gì vào bất kỳ tệp nào. Một tài liệu không nằm trong workspace, không đọc được, hoặc không phải YAML hợp lệ sẽ trả về một kết quả thất bại nêu rõ cần thay đổi gì, như với insertion-point; một vị trí thiếu line hoặc character, và một position_encoding nằm ngoài ba giá trị cũng vậy.

Hỏi một attachment thuộc về container nào

attachment-container trả lời câu hỏi nằm giữa một câu trả lời về ứng viên và một điểm chèn. Bạn đã quyết định cái gì sẽ gắn vào một node; trước khi có thể hỏi nên viết nó ở đâu trong một tệp, bạn cần biết tệp nào và container nào bên trong tệp đó. Truyền graph_node — một node id trên một đồ thị đã biên dịch, đúng như đồ thị dùng làm khóa — và release sở hữu đồ thị đó. Cả hai đều bắt buộc: một node id là khóa của đồ thị thuộc một Release và không có ý nghĩa gì nếu thiếu Release đó.

Đừng tự lắp ráp đường dẫn đó. Id của một node và đường dẫn subsystem bao quanh nó đều được viết với dấu chấm giữa các phần, và dấu chấm là ký tự hợp lệ trong một tên mà tác giả gõ — nên từ bên ngoài tài liệu, không có cách nào phân biệt một dấu chấm cấu trúc với một dấu chấm nằm trong tên. Một đường dẫn bạn tự ghép sẽ trông đúng nhưng trỏ tới một khóa không ai viết, và thao tác chỉnh sửa theo sau sẽ tạo ra khóa đó thay vì bị từ chối. Tệ hơn, một node id hoàn toàn không mang dấu vết nào của subsystem bao quanh nó: một component được viết bên trong subsystems.billing.subsystems.payments có khóa là ledger, giống hệt một component ở cấp cao nhất. Hãy hỏi để lấy container.

Câu trả lời mang node, node mà nó nói đến; file, tài liệu nơi node đó được viết; và container, đường dẫn cấu trúc từ gốc của tài liệu đó dưới dạng một danh sách các phân đoạn — ["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. Nó là một danh sách thay vì một chuỗi đã nối là có chủ đích: một đường dẫn đã nối sẽ phải được người nhận tách ra lại, tức là sự mơ hồ ở trên quay trở lại ngay ở lời gọi kế tiếp. Truyền file và container cho insertion-point mà không thay đổi.

file là một phần của câu trả lời chứ không phải thứ bạn đã biết sẵn. Một node do một module được import đóng góp được viết trong tài liệu riêng của module đó, dưới tên mà module đặt cho nó, nên cả tệp lẫn phân đoạn cuối của container đều khác với bất cứ thứ gì bạn đã gửi.

Với một phần đính kèm trên một kết nối mà node đó vẽ, hãy thêm connection kèm socket, alias và document của nó; tham số này bắt buộc ở đây vì tài liệu nào trong hai cũng có thể chứa một kết nối. Với aggregate, câu trả lời là mục riêng của kết nối trong tài liệu nơi node được viết, với khối features ở cuối; một kết nối do Release vẽ không có mục ở đó và bị từ chối. Với release, đó là mục theo từng cạnh nằm dưới mục của Release dành cho node — ["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"] — được báo cáo dù Release đã viết mục theo từng cạnh đó hay chưa, để insertion-point nêu ra các khóa còn phải viết; một Release không viết mục nào cho node sẽ bị từ chối, vì việc node được đặt ở đâu không phải do công cụ này quyết định. Một kết nối do một Feature vẽ bị từ chối ở cả hai tài liệu.

Nó trả lời rồi dừng. Nó không tạo attachment nào, không ghi gì vào bất kỳ tệp nào và không soạn văn bản nào. Nó cũng không phán định cái gì được phép gắn — đó là việc của attach-candidates. Một node mà đồ thị không chứa, hoặc một node mà đồ thị không ghi nhận tài liệu nào, sẽ được trả về dưới dạng một kết quả thất bại nêu rõ cần thay đổi gì, thay vì một câu trả lời có trường rỗng.

Xác định vị trí của một mục trong tài liệu

insertion-point trả lời câu hỏi tiếp theo sau một câu trả lời về ứng viên. Bạn đã quyết định cái gì sẽ gắn hoặc kết nối; giờ bạn cần biết viết nó vào đâu trong tệp. Công cụ trả về một vị trí và các cột cần thụt lề, để bạn có thể áp dụng chỉnh sửa mà không phải tự phân tích tài liệu. Vì thứ nó đọc là cấu trúc riêng của tài liệu chứ không phải hình dạng của một loại cụ thể nào, describe-capabilities liệt kê nó dưới bất kỳ loại thực thể nào bạn thu hẹp đến.

Truyền file — tài liệu, tương đối so với thư mục gốc của workspace hoặc tuyệt đối, và nằm trong workspace: một tài liệu được truy cập qua một liên kết dẫn ra ngoài workspace, tới tệp hoặc tới một thư mục trên đường đi, thì không nằm trong đó và bị từ chối trên cả hai phương thức truyền tải — và container, đường dẫn cấu trúc từ gốc tài liệu tới container chứa mục, mỗi phần tử là một khóa mapping hoặc một vị trí trong sequence viết ở hệ thập phân.

Đường dẫn container là do bạn cung cấp. Công cụ đọc cấu trúc của tài liệu và không bao giờ suy ra vị trí của một thứ từ tên gọi, kiểu dữ liệu hay ý nghĩa bề ngoài của nó. Bạn nói khóa nào; nó nói các mục của khóa đó nằm ở đâu trong tài liệu này — những phân đoạn nào của đường dẫn tệp đã có, các cột mà các mục của nó nằm ở đó, và dòng cuối cùng mà khối trong cùng của nó đạt tới. Với việc gắn một Feature lên một node của đồ thị đã biên dịch, bạn không cần tự biết khóa đó: attachment-container ở trên báo cáo tài liệu và container, và cả hai được truyền vào đây nguyên vẹn.

Câu trả lời gồm một position có độ rộng bằng không, với line và character đều đếm từ không; entryIndent và indentStep, các cột để viết; và missingContainerKeys, các khóa container mà tài liệu này chưa có, ngoài cùng trước, mà bạn viết trước mục. entryShape cho biết container chứa một mapping hay một sequence, và báo unknown khi container chưa tồn tại hoặc không chứa gì, vì tài liệu chưa cho biết — khi đó hình dạng là do bạn chọn. indentStepMeasured cho biết bước thụt lề được đo từ cách lồng nhau của chính tài liệu này hay là giá trị dự phòng cho một tài liệu không có lồng nhau nào. Khi precededByLineBreak được đặt, hãy bắt đầu văn bản của bạn bằng một dấu xuống dòng: vị trí nằm ở cuối dòng mà mục theo sau, vị trí này hợp lệ dù tệp có kết thúc bằng ký tự xuống dòng hay không và không làm xáo trộn byte nào đã viết. Hãy đọc missingContainerKeys ngay cả khi bạn nghĩ container đã có — một vị trí được áp dụng mà thiếu các khóa phải đứng trước nó sẽ tạo ra một tài liệu không còn phân tích được.

position_encoding cho biết đơn vị dùng để đo offset ký tự được báo cáo: utf-8, utf-16 hoặc utf-32. Đây là một đối số vì không phiên bản nào của giao thức này thương lượng đơn vị, và mặc định là utf-16, là đơn vị mà một phiên trình soạn thảo dùng khi client không thương lượng gì — nên một bên gọi không chỉ định gì sẽ nhận câu trả lời giống hệt nhau trên cả hai bề mặt. Một giá trị không thuộc ba giá trị trên sẽ bị từ chối thay vì âm thầm dùng mặc định, vì các offset đo theo một cách rồi áp dụng vào một bộ đệm đo theo cách khác sẽ làm hỏng tài liệu ngay tại ký tự đầu tiên nằm ngoài ASCII.

Nó trả lời rồi dừng. Nó không ghi gì vào tệp nào, không soạn văn bản mục nào và không áp dụng chỉnh sửa nào; việc soạn văn bản và quyết định có áp dụng hay không là của bạn. Một yêu cầu không trỏ tới một nơi có thể đặt mục sẽ trả về một kết quả thất bại nêu rõ cần thay đổi gì — một tài liệu không nằm trong workspace, không đọc được, hoặc không phải YAML hợp lệ; một đường dẫn container không có phân đoạn nào hoặc có một phân đoạn rỗng; một đường dẫn đi qua một scalar, nơi không thể nối thêm gì vào bên trong; một đường dẫn tới một collection viết theo kiểu flow, nơi việc nối thêm sẽ viết lại các byte tác giả đã viết thay vì thêm một dòng; hoặc một đường dẫn trỏ tới một block sequence bằng thứ không phải là một chỉ số của nó. Khi bạn muốn chỉnh sửa được áp dụng thay vì tự áp dụng, Áp dụng một chỉnh sửa có giới hạn vào tài liệu là công cụ làm việc đó.

Áp dụng một chỉnh sửa có giới hạn cho một tài liệu

edit-document áp dụng những gì hai công cụ ở trên định vị. Một lệnh gọi thêm một mục dưới một container, hoặc đặt một giá trị vô hướng, và không thể làm gì khác. Nó ghi vào tài liệu bạn chỉ định, bên trong workspace, nên qua HTTPS nó cần aggrega:workspace-write: một bên gọi chỉ có aggrega:read vẫn thấy nó trong danh sách công cụ, nhưng lệnh gọi của họ bị từ chối kèm tên phạm vi đó.

Chỉ định chỉnh sửa trong edit, và tập hợp này là đóng. add-component thêm một thể hiện component dưới một container components; attach-feature gắn một Feature vào nút bạn chỉ định; wire-edge nối một kết nối bên trong một trong các socket của nút đó; set-value đặt một giá trị trên nút đó. Một tên nằm ngoài bốn tên này bị từ chối thay vì được diễn giải. Không có chỉnh sửa nào xóa, thay thế một khối bạn đã viết, sắp xếp lại bất cứ thứ gì, hoặc ghi nguyên văn các byte bạn cung cấp — vì vậy đây không phải là một công cụ ghi tệp và không thể dùng như vậy.

Truyền file, tài liệu — tương đối với thư mục gốc của workspace hoặc tuyệt đối, và nằm trong workspace: một tài liệu nằm ngoài nó, theo cách viết hoặc qua một liên kết dẫn ra ngoài, bị từ chối trên cả hai phương thức truyền mà không đọc hay ghi gì; node, đường dẫn cấu trúc từ gốc tài liệu dưới dạng danh sách các đoạn; name, khóa mà mục được ghi dưới đó; và value, nội dung mục đó mang. node là một danh sách vì cùng lý do attachment-container trả lời bằng một danh sách: dấu chấm là hợp lệ bên trong một tên do tác giả gõ, nên một đường dẫn được nối lại có thể trỏ tới một khóa không ai viết và mục sẽ được tạo ở đó thay vì bị từ chối. Với add-component, đường dẫn chỉ chính container components, vì mục được thêm chính là nút; với ba chỉnh sửa còn lại, nó chỉ nút mà chỉnh sửa nhắm tới, và container được suy ra từ chỉnh sửa. socket được đọc cho wire-edge và bị bỏ qua trong các trường hợp khác. Ý nghĩa của value tùy theo edit — thực thể mà mục yêu cầu, nút mà một kết nối trỏ tới, hoặc giá trị vô hướng được đặt — và nó là một giá trị JSON mang kiểu riêng, nên một số vẫn là số, một chữ số trong dấu nháy vẫn là văn bản, và bỏ nó đi thì không đặt gì cả. Một mapping hoặc một sequence bị từ chối, vì ghi một khối không phải là một trong các chỉnh sửa này.

Mọi byte mà chỉnh sửa không chạm tới đều được giữ nguyên. Tài liệu chỉ được phân tích để định vị container và dòng mà khối của nó kết thúc, nên chú thích, dòng trống, kiểu đặt dấu nháy, các giá trị vô hướng dạng folded và literal cùng dạng dòng mới ở cuối đều được giữ lại, và bước lồng được đo từ cách thụt lề của chính tài liệu thay vì bị áp đặt. Cùng một yêu cầu trên cùng một tài liệu tạo ra cùng các byte.

Kết quả phải là một tài liệu bạn có thể đã tự gõ, và việc ghi phụ thuộc vào điều đó. Tài liệu được soạn được kiểm tra theo schema của chính loại của nó và chỉ được ghi xuống đĩa nếu vượt qua. Một yêu cầu sẽ tạo ra thứ mà schema từ chối thì bị từ chối, kèm tên thuộc tính mà schema không chấp nhận và vị trí của nó, và tệp được giữ nguyên từng byte như trước — nên một chỉnh sửa bị từ chối không khác gì một chỉnh sửa chưa từng được thử, và bạn có thể thử lại một yêu cầu đã sửa trên đúng tài liệu ban đầu. Một mục đã tồn tại và mang đúng nội dung bạn yêu cầu thì không làm gì; một mục cùng tên mang nội dung khác thì bị từ chối thay vì bị thay thế.

Câu trả lời mang container, đường dẫn cấu trúc nơi mục được đặt vào; created_containers, các cấp container mà chỉnh sửa này phải tạo ra, cấp ngoài cùng trước và rỗng trong trường hợp thông thường khi toàn bộ đường dẫn đã có sẵn; và written, tài liệu đã được ghi xuống đĩa, rỗng khi không có gì được ghi. Hãy đọc created_containers: một chỉnh sửa lặng lẽ ghi hai khối lồng nhau mà tài liệu chưa có sẽ không thể phân biệt được với một chỉnh sửa chỉ thêm một mục vào một khối do bạn tự viết.

dry_run làm mọi thứ trừ việc ghi. Tài liệu đã chỉnh sửa được trả về dưới dạng content, không có gì được tạo và written rỗng — dành cho một client đưa kết quả ra trước tác giả trước khi lưu. Mọi hành vi khác đều giống như khi ghi, bao gồm cả cổng kiểm tra schema, nên một yêu cầu mà việc ghi sẽ từ chối thì cũng bị từ chối trong chế độ này. Khi không có nó, tài liệu được ghi và content vắng mặt, vì khi đó tài liệu đã nằm trên đĩa và written chỉ tên nó.

Việc những gì bạn nối có được chấp nhận về mặt ngữ nghĩa hay không — socket có phải là socket mà bên cung cấp khai báo hay không, hoặc điều kiện áp dụng của một Feature có được thỏa mãn hay không — không được quyết định ở đây. Đó là điều validate trả lời.

Trên đầu vào và đầu ra chuẩn, cùng khả năng này còn có thể truy cập qua cli-edit-document, công cụ chạy lệnh và trả về văn bản lệnh đã in ra; qua HTTP công cụ đó không tồn tại, và công cụ này là cách truy cập khả năng đó ở đó.

Chuyển một mô tả từ bên ngoài thành các thực thể nháp

import chuyển đổi một mô tả do công cụ khác tạo ra — chẳng hạn một luồng được xuất từ một trình dựng agent — thành các tệp soạn thảo Aggrega dạng nháp. Nó ghi các tệp đó vào workspace mà máy chủ này phục vụ, vì vậy qua HTTPS nó cần aggrega:workspace-write: một bên gọi chỉ có aggrega:read sẽ thấy nó trong danh sách công cụ, và lời gọi mà bên đó thực hiện bị từ chối với thông báo nêu tên phạm vi đó.

Truyền source, tệp hoặc thư mục cần chuyển đổi. Đường dẫn này là tuyệt đối hoặc tương đối so với gốc workspace, cùng một quy định mà mọi đối số đường dẫn khác trên giao diện này sử dụng, và trên một máy chủ được truy cập qua HTTPS, nó được phân giải bên trong workspace mà máy chủ đó phục vụ.

Một thư mục được đọc thành đúng những tệp mà các mẫu tệp của importer của nó chọn. Một chart hay một dự án là một thư mục, và source có thể nêu tên một thư mục. Khi đó importer được trao các tệp trong thư mục, ở bất kỳ độ sâu nào, mà một trong các mẫu tệp do các chữ ký của nó khai báo chọn, mỗi tệp được gọi bằng đường dẫn bên trong thư mục, viết bằng dấu gạch chéo xuôi, theo thứ tự đã sắp xếp, cùng với các tệp mà attachment plugins.importer của nó nêu dưới with.sources, theo tên cơ sở của chúng; một tệp trong thư mục và một tệp with.sources cùng tên bị từ chối thay vì để tệp này che tệp kia. Một importer không khai báo mẫu tệp nào thì đọc một tệp và từ chối thư mục, theo điều kiện An importer that declares no file patterns is handed a directory (Một importer không khai báo mẫu tệp nào được trao một thư mục), và một thư mục không chứa tệp nào mà các mẫu của nó chọn cũng bị từ chối. Thư mục được giới hạn trong chính nó dù nằm ở đâu: một liên kết trong số các tệp mà việc import sẽ đọc, hoặc tới một thư mục, dẫn ra ngoài nó thì bị từ chối trước khi bất cứ thứ gì được đọc, và một liên kết tới thư mục không bao giờ được đi vào — như Một thư mục bạn import trình bày. Trên một máy chủ được truy cập qua HTTPS, bản thân thư mục được phân giải bên trong workspace, nên mọi tệp đọc từ nó cũng vậy.

Importer là một importer mà catalog của workspace bạn chứa, hoặc một trong các importer lõi của trình biên dịch. Việc chuyển đổi là công việc của plugin importer quảng bá định dạng của nguồn: một plugin mà catalog của workspace bạn chứa, hoặc một trong các importer lõi của trình biên dịch, vốn phục vụ các định dạng của chúng trong mọi workspace mà không cần mục catalog nào. Công cụ này chọn nó, chạy nó và ghi những gì nó tạo ra. Một attachment plugins.importer có uri nêu tên một importer theo danh tính và phiên bản — importer/<name>:<version>, như aggrega plugin add importer ghi nó — sẽ gắn importer đó: khi nó quảng bá định dạng của nguồn, nó là importer được chạy, ở phiên bản đó, bất kể importer nào khác cũng quảng bá định dạng này, và nó được trao các nguồn và thiết lập with của attachment đó, điều mà không importer nào khác được trao. Khi nhiều importer quảng bá định dạng và không có importer nào trong số đó được gắn — trong đó có một importer lõi và một importer tên khác mà catalog của bạn chứa cho cùng định dạng — lời gọi bị từ chối với thông báo nêu tên chúng, như Cấu hình mô tả. Một định dạng bạn nêu mà không importer nào quảng bá sẽ bị từ chối với thông báo nêu tên khả năng mà một importer phải quảng bá — import:langflow cho một nguồn Langflow — tức là điều mà một importer bạn thêm vào catalog khai báo, thay vì một thông báo không tìm thấy chung chung mà bạn phải tự diễn giải.

Một core importer mà máy của server không có sẽ được tải về một lần, bởi lần import đầu tiên cần đến nó. Lần import tải nó từ registry mặc định của workspace được phục vụ, đối chiếu nó với module mà bản phát hành của compiler công bố, xác minh chữ ký của nó theo chính sách tin cậy của registry đó cùng các hàm host mà nó dùng, như một lần pull xác minh một plugin mà nó tải về, rồi giữ nó trong bộ nhớ đệm nội dung của workspace, nên mọi lần import sau đều đọc nó từ đó và không truy cập registry nào. Không có gì khác được ghi cho nó — không có lockfile, và không có bản ghi nào về các plugin được tin cậy. Qua HTTPS, đây là registry duy nhất mà một lời gọi công cụ này có thể khiến server liên hệ, trong giới hạn mà Một lời gọi dùng những thông tin xác thực nào đặt ra cho việc đọc registry: registry đó là registry mặc định của workspace mà server này phục vụ, nên nó là registry mà workspace đó được cấu hình; không có gì trong lời gọi chỉ định một registry hay mang theo thông tin xác thực; và việc tải về dùng thông tin đăng nhập và chính sách tin cậy của chính host này. Công cụ vẫn chỉ truy cập workspace và không gì xa hơn, nên aggrega:workspace-write là tất cả những gì một lời gọi cần: thứ mà việc tải về để lại là một module trong bộ nhớ đệm nội dung của chính workspace. Một module không xác minh được sẽ bị từ chối như khi ở terminal, và không có gì được giữ lại. Khi không thể tải được module — workspace đang ngoại tuyến, không thể truy cập registry của nó, hoặc registry không có module đó — lời gọi bị từ chối theo A plugin’s .wasm is not on this machine (Tệp .wasm của một plugin không có trên máy này), nêu tên importer, phiên bản của nó và cách đưa module của nó lên máy.

Khi workspace không chỉ định thư mục danh mục nào, import đọc danh mục mà registry mặc định của nó phát hành. Một workspace có workspace.catalog_dirs, AGGREGA_CATALOG_DIRS và thư mục gốc không chỉ định thư mục danh mục nào sẽ đọc danh mục thư viện chuẩn dưới dạng một bản chụp nhanh duy nhất có chữ ký, tại catalog/snapshot trên registry mặc định của workspace được phục vụ — cũng chính là registry mà từ đó một trình import lõi được tải về, được truy cập theo cùng các điều kiện, và không có gì trong lời gọi chỉ định registry hay mang thông tin xác thực. Một bản chụp nhanh chỉ được tải về một lần: chữ ký của nó được xác minh theo chính sách tin cậy của registry đó, rồi nó được lưu trong bộ nhớ đệm nội dung của workspace và được đọc ở đó như một thư mục danh mục, gắn với digest của nó, mà không phải yêu cầu lại từ registry nào. Bản chụp nhanh mà một lời gọi đọc là: với upgrade, bản mới nhất; nếu không, bản mà bản ghi trong thư mục đầu ra nêu tên, được tải về theo digest của nó nếu máy chưa có; nếu không, bản mà workspace tải về gần nhất dưới dạng bản mới nhất; nếu không, bản mới nhất. Bản ghi mà import ghi ra nêu tên bản chụp nhanh nó đã đọc, theo digest của nó, nên một lời gọi sau này soạn nháp vào cùng thư mục sẽ đọc cùng danh mục. Khi ngoại tuyến, một lời gọi cần tải về một bản chụp nhanh sẽ bị từ chối, kèm theo việc nêu lệnh cần chạy, và upgrade bị từ chối bất kể máy đang có gì, vì chỉ registry mới có thể cho biết bản chụp nhanh nào là mới nhất. Một registry không phát hành bản chụp nhanh nào sẽ khiến import không có danh mục, và một mục warn trong diagnostics cho biết điều đó. Một workspace chỉ định thư mục danh mục sẽ import dựa trên thư mục đó và không tải về bản chụp nhanh nào, và upgrade không thay đổi gì ở đó.

Bỏ qua format thì định dạng được nhận diện bằng các chữ ký mà các importer khai báo — của catalog của bạn cũng như của các importer lõi. Thực thể Plugin của mỗi importer ghi lại chúng: cú pháp mà một nguồn được đọc theo, các tên tệp mà một chữ ký áp dụng, và các đường dẫn mà cây đã phân tích phải có hoặc không được có. Nguồn được phân tích, qua trình phân tích mà catalog của workspace bạn phục vụ cho một cú pháp — hoặc, với cú pháp mà catalog của bạn không phục vụ trình phân tích nào, trình phân tích mà chính trình biên dịch mang theo — một lần cho mỗi cú pháp mà một chữ ký áp dụng cho tên của nó dùng để đọc, và định dạng của importer duy nhất có chữ ký khớp là định dạng được dùng. Sau đó importer đọc nguồn qua cùng trình phân tích đó. Các chữ ký của importer lõi đọc tệp dưới dạng JSON hoặc YAML, và những chữ ký không nêu tệp nào đọc nó dưới dạng JSON — của importer Dify thì dưới dạng YAML — nên việc nhận diện một tệp được import riêng lẻ đọc nó theo cả hai và không cần trình phân tích nào trong catalog của workspace bạn: trình biên dịch mang theo một trình phân tích JSON và một trình phân tích YAML, và trình phân tích mà catalog của bạn phục vụ được dùng thay thế. Một thư mục được nhận diện theo cùng cách trên các tệp của nó: mỗi chữ ký được thử với các tệp trong thư mục mà các mẫu của nó chọn, và một chữ ký không khai báo mẫu nào không áp dụng cho tệp nào. Việc nhận diện đọc tệp bạn đã nêu — hoặc, với thư mục, chỉ các tệp mà mẫu của một chữ ký chọn — và không dùng mạng. Một nguồn không khớp chữ ký nào bị từ chối với yêu cầu cung cấp format và nêu tên các định dạng mà các importer quảng bá — hoặc, với thư mục, yêu cầu gửi riêng một trong các tệp của nó làm source hoặc một format có importer khai báo mẫu tệp, chỉ nêu tên các định dạng đó — theo điều kiện No importer recognises the source (Không importer nào nhận diện được nguồn); một nguồn khớp chữ ký của nhiều hơn một định dạng bị từ chối với thông báo nêu tên chúng, theo điều kiện More than one importer recognises the source (Nhiều hơn một importer nhận diện được nguồn); không trường hợp nào được trao cho một importer đoán chừng. Gửi format để nêu thẳng định dạng trong cả hai trường hợp — với thư mục, là một định dạng có importer khai báo mẫu tệp, vì thư mục chỉ được đọc qua các mẫu đó. Một format để trống bị từ chối thay vì được hiểu như thể bạn đã bỏ qua nó, vì đó là hai yêu cầu khác nhau.

Gửi target để soạn bản nháp Manifest mà Release được soạn sẽ build theo cho một provider. target là một capability của provider — từ mà spec.capability của một Recipe gắn với, chẳng hạn compose hoặc helm — và nó chính là --target của aggrega import, được hợp thành bởi cùng một thao tác, nên một lời gọi và lệnh này soạn ra cùng các tệp từ cùng một nguồn. Với mỗi loại component và mỗi loại feature mà các bản nháp cần — trên các component của Aggregate được soạn, các kết nối của chúng và các hệ thống con của nó, trên các Aggregates trong catalog mà nó hợp thành, và trên các attachment của Release được soạn — theo thứ tự các bản nháp khai báo lần đầu, quá trình import tìm trong catalog của workspace các Recipes, hoặc với một loại feature thì các feature recipe, hiện thực loại đó và gắn với capability đó. Khi có đúng một — nhiều phiên bản của cùng một cái được tính là một — Manifest ánh xạ loại đó tới nó bằng tên có kèm capability và không có phiên bản, chẳng hạn compose/postgres, mà lần pull đầu tiên sẽ ghim trong lockfile ở phiên bản cao nhất hiện có. Khi có nhiều cái mang các tên khác nhau, nó ánh xạ tới cái được đặt tên theo chính loại đó, chẳng hạn helm/postgres cho core/datastore/postgres. Khi không có, hoặc có nhiều nhưng không cái nào được đặt tên như vậy, loại đó được để chưa ánh xạ và một mục warn trong diagnostics nêu tên nó và lý do — liệt kê từng cái theo tên khi có nhiều — nên một lần build các bản nháp sẽ dừng lại và nêu tên từng instance hoặc attachment của nó, theo No Recipe is mapped for a component or feature instance (Không có Recipe nào được ánh xạ cho một instance component hoặc feature), cho đến khi ánh xạ được thêm vào. Khi importer tự soạn Manifest, để chọn Recipe mà một instance được render qua hoặc một feature recipe trong số nhiều cái, mỗi ánh xạ nó đã viết mà catalog cung cấp cho loại và capability đó được giữ lại, mọi ánh xạ khác bị loại bỏ kèm một mục warn, và các loại nó để lại được ánh xạ như trên. Manifest được soạn thành manifest.yaml bên cạnh Release được soạn, mang tên và phiên bản giống Release, và spec.manifest của Release được đặt thành tên đó — chú thích mà importer đã viết ở vị trí đó được thay thế, và không có gì khác trong Release thay đổi. Một Release đã nêu tên một Manifest được giữ nguyên, và khi quá trình import không soạn Release nào thì Manifest được soạn bên cạnh Aggregate, với tên và phiên bản của nó, và một mục info cho biết không có gì tham chiếu tới nó. Manifest và Release đã chỉnh sửa là bản nháp như các bản khác: có trong written, trong bản ghi, và được trả lại dưới dry_run. Một target mà không Recipe nào trong catalog gắn với sẽ bị từ chối trước khi importer chạy, theo An import’s target names a capability no Recipe in the catalog binds to (Target của lần import nêu một capability mà không Recipe nào trong catalog gắn với), nêu nó đúng như bạn đã gửi và các capability mà các Recipes của catalog gắn với, và không có gì được ghi. Bỏ target đi thì không Manifest nào được soạn — trừ khi dùng sync, vốn soạn cho target mà lần import trước đã được gửi; một target rỗng bị từ chối thay vì được hiểu như thể bạn đã bỏ nó đi.

Gửi output_dir để nêu thư mục chứa các bản nháp. Bỏ nó đi thì chúng được đặt dưới gốc của workspace mà lời gọi đã phân giải — nơi aggrega import ghi chúng khi bạn không nêu đích đến, dù bạn chạy nó ở đâu, và nơi aggrega/import của language server ghi chúng khi yêu cầu của nó không nêu đích đến nào. Đích đến là tùy chọn ở cả ba, và được nêu theo cùng cách như mọi đường dẫn bạn gửi tới server này. Qua HTTP nó là một thư mục bên trong workspace mà server này phục vụ, viết tương đối với gốc của nó: một giá trị leo ra khỏi gốc, một vị trí tuyệt đối nằm ngoài gốc, và một thư mục dẫn ra ngoài gốc qua một liên kết — kể cả một thư mục chưa được tạo nằm dưới liên kết như vậy — đều bị từ chối với tên output_dir, và không có gì được đọc hay ghi. Qua standard input và output nó được lấy đúng như đã nêu, như mọi đường dẫn ở đó: một giá trị tương đối được phân giải theo gốc workspace mà lời gọi đã phân giải, và một giá trị tuyệt đối có thể nêu một thư mục nằm ngoài workspace, nơi bản nháp được soạn vào giống như aggrega import --output-dir soạn vào. Những gì được ghi ở đó, sau khi phân giải các liên kết, bị giới hạn trong workspace — hoặc, với một thư mục bạn nêu nằm ngoài nó, trong thư mục đó — nên một liên kết bên trong dẫn ra ngoài sẽ bị từ chối và không có gì được ghi. Một output_dir rỗng bị từ chối thay vì được hiểu như thể bạn đã bỏ nó đi. Trên standard input và output, cli-import cũng mang --output-dir của lệnh dưới dạng output_dir của riêng nó; một giá trị tương đối ở đó được phân giải trong thư mục mà lệnh chạy: gốc workspace mà lời gọi nêu, nếu không thì gốc mà server được khởi động cùng, nếu không nữa thì thư mục mà server đang chạy.

Mọi đường dẫn được soạn đều được kiểm tra với thư mục đầu ra trước khi bất cứ thứ gì được ghi. Một đường dẫn vươn ra ngoài thư mục đó bị từ chối, nêu cả đường dẫn lẫn thư mục, và hoàn toàn không có gì được ghi — kể cả các tệp trong cùng tập có đường dẫn hợp lệ, vì một lần import bị từ chối mà để lại một phần của nó là kết quả không ai yêu cầu. Một đường dẫn được soạn đến từ plugin importer chứ không phải từ bạn, đó là lý do nó được kiểm tra vì cùng lý do như một đường dẫn bạn gửi.

Mọi lần import có soạn ra thứ gì đều ghi thêm .aggrega-import.json bên cạnh các bản nháp: bản ghi những gì nó đã ghi — target mà nó được gửi, nếu có, bản chụp nhanh danh mục mà nó đã đọc, nếu có, và từng tệp được soạn cùng, trong một Aggregate hoặc Release được soạn, từng khóa ở mọi độ sâu, với một digest của văn bản được ghi ở đó; mọi tệp được soạn khác được ghi nhận nguyên tệp. Văn bản của một khóa gồm dòng của nó, các dòng giá trị của nó khi giá trị không phải là một ánh xạ các khóa, và các dòng chú thích được viết ngay phía trên nó ở cùng mức thụt lề. written nêu bản ghi cùng các bản nháp, và dưới dry_run nó nằm trong số các bản nháp được trả lại. Bản ghi là JSON, nên không thứ gì đọc các tài liệu YAML của workspace sẽ đọc nó.

Một lời gọi không bao giờ ghi đè lên một Aggregate đã có trong thư mục đầu ra. Aggregate là tài liệu mà tác giả tiếp tục chỉnh sửa sau khi nó được soạn, nên một lời gọi có bản nháp sẽ rơi vào một tệp được đọc là Aggregate sẽ bị từ chối, nêu bản nháp và thư mục, và hoàn toàn không có gì được ghi — kể cả dưới dry_run, vì một lần chạy thử từ chối những gì lần ghi từ chối. Mọi tệp khác đã có ở một đường dẫn được soạn đều bị ghi đè, và một tệp mà lần import trước đã soạn nhưng lần này không soạn thì được giữ nguyên tại chỗ.

Gửi sync để thay vào đó cập nhật những gì một lần import trước đã soạn cho khớp với nguồn, chỉ thay đổi những gì lần import đó đã ghi. Một lần sync không được gửi target sẽ soạn cho target mà bản ghi nêu, nên nó soạn Manifest mà lần import trước đã soạn; một lần được gửi target sẽ soạn cho target đó, và sau đó bản ghi nêu target ấy. Một target đã ghi mà không Recipe nào trong catalog gắn với nó sẽ bị từ chối giống như một target được gửi, lời từ chối cho biết target đó là target đã ghi. Mỗi phần được xét theo ba cách — những gì bản ghi nói lần import đã ghi ở đó lần cuối, những gì có trên đĩa, và những gì nguồn soạn ra bây giờ. Một phần mà nguồn để nguyên như lần import đã ghi lần cuối sẽ giữ nguyên chính xác như trên đĩa, dù tác giả có chỉnh sửa nó hay không. Một phần mà nguồn đã thay đổi sẽ được ghi lại mới, một phần mà nguồn đã bỏ sẽ bị xóa — một tệp đã soạn bị xóa toàn bộ — và một phần mà nguồn có thêm sẽ được thêm vào cạnh các phần mà bản nháp nêu xung quanh nó, mỗi việc chỉ khi những gì trên đĩa đúng là những gì lần import đã ghi lần cuối và không chứa gì tác giả đã thêm. Mọi thứ khác giữ nguyên từng byte: một khóa tác giả đã thêm ở bất kỳ đâu — một tham số, một Feature, kể cả dưới một instance Component đã soạn, một Component khác, môi trường mà một Release đã soạn để lại cho tác giả của nó — một chú thích không được viết ngay phía trên một khóa đã soạn, và mọi tệp mà bản ghi không liệt kê. drift của câu trả lời liệt kê từng phần được cập nhật — hoặc, dưới dry_run, từng phần sẽ được cập nhật — theo thứ tự bản nháp nêu chúng, mỗi phần gồm change (added, removed hoặc changed), file, tệp đã soạn chứa nó, và key, các khóa dẫn tới nó trong một Aggregate hoặc Release đã soạn dưới dạng danh sách, rỗng khi phần đó là cả tệp; câu trả lời dạng văn bản nêu mỗi phần trên một dòng riêng bằng đúng cách diễn đạt mà aggrega import ghi ra standard error, <change> <key> in <file> hoặc <change> <file>. Một drift rỗng dưới dry_run cho biết các bản nháp đã khớp với nguồn. Dưới dry_run, các bản nháp được trả về là những tệp mà lần sync sẽ ghi, với nội dung nó sẽ ghi vào. Một lần sync sẽ thay đổi hoặc xóa một phần tác giả đã chỉnh sửa, thêm một phần vào chỗ tác giả đã viết sẵn một phần, hoặc xóa một phần chứa thứ tác giả đã thêm thì bị từ chối, nêu từng phần như vậy và lý do, và không có gì được ghi; một chú thích được viết ngay phía trên một khóa đã soạn được xem là chỉnh sửa khóa đó. Một lần sync trên một Aggregate mà không bản ghi nào liệt kê sẽ bị từ chối kèm lời giải thích như vậy, cũng như một lần sync có bản ghi không đọc được, và một lần sync mà importer không thể hoàn tất thì không ghi gì. Một lần sync vào một thư mục không chứa bản ghi nào và không có gì tại các đường dẫn đã soạn sẽ ghi toàn bộ bản nháp. drift là danh sách rỗng đối với một lời gọi không phải sync.

Câu trả lời mang source, đúng như bạn đã nêu; format, cách nguồn đã được đọc; workspace_root, gốc của workspace mà lời gọi đã phân giải; output_dir, thư mục mà các đường dẫn đã soạn tương đối theo; written, các tệp đã được ghi xuống đĩa; drift, những gì một lần sync đã cập nhật; diagnostics, một mục cho mỗi cấu trúc mà importer không thể dịch; decisions, cách importer ánh xạ từng nút nguồn; và halted. output_dir là thư mục bạn đã gửi, hoặc là gốc đó nếu bạn không gửi, được lấy từ những gì lần import thực sự đã dùng, và nó cũng được báo cáo dưới dry_run, nơi không có gì được ghi nhưng mỗi đường dẫn đã soạn vẫn tương đối theo nó. Qua HTTP, workspace_root bị giữ lại và được đánh dấu workspace_root_withheld, vì gốc là một vị trí trên máy chủ của server, như Câu trả lời nói gì về hệ thống tệp của server trình bày; output_dir bị giữ lại và được đánh dấu output_dir_withheld khi nó chính là gốc đó, còn không thì được cho biết bằng tên tương đối theo gốc — dạng mà các đường dẫn của chính bạn dùng — nên nơi các bản nháp được đặt vẫn có trong câu trả lời. Một lần import mà importer không thể hoàn tất vẫn soạn những gì nó có thể, và trả về được gắn cờ là thất bại kèm toàn bộ câu trả lời đó — halted là true, các tệp đã thực sự được ghi xuống đĩa được nêu trong written, và các chẩn đoán bên cạnh nêu những gì còn thiếu. Đó là một kết quả một phần mà bạn có thể giữ hoặc bỏ, không phải một lời gọi không làm gì.

decisions cho biết lần import đã phỏng đoán ở đâu. Nó mang một mục cho mỗi nút nguồn mà importer đã ánh xạ, theo thứ tự của importer: source_node, gồm id, type và params_summary của nút; candidates, mỗi Component trong catalog mà importer đã cân nhắc cho nút đó, dưới dạng component, score, tier và signals — mức đóng góp của từng tín hiệu, dưới table, category, domain_labels, shape và name; chosen, target mà nó đã chọn, mode mà nó đã ghi target đó — một reference tới một Component có sẵn hoặc một draft — và tier của lựa chọn; rationale, lý do; và swap_hint, cách chọn khác đi. candidates vắng mặt khi importer không cân nhắc ứng viên nào, chosen vắng mặt khi nó không đưa ra lựa chọn, và rationale cùng swap_hint vắng mặt khi nó không viết gì. Mọi giá trị đều là của chính importer — cách nó chấm điểm một ứng viên và các tier của nó rơi vào đâu là lựa chọn của nó — nên hãy đọc một mục như lời giải thích của nó về việc ánh xạ. decisions có trong câu trả lời cả dưới dry_run lẫn khi lần import bị dừng, và là danh sách rỗng đối với một importer không báo cáo gì. Câu trả lời dạng văn bản nêu mỗi quyết định trên một dòng riêng sau các chẩn đoán, bằng đúng cách diễn đạt mà aggrega import ghi ra standard error: mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, trong đó điểm là điểm của ứng viên tốt nhất.

dry_run làm mọi thứ trừ việc ghi. Mỗi tệp đã soạn được trả về dưới drafts cùng đường dẫn của nó, tương đối theo output_dir, và nội dung của nó, và không có gì được tạo ra — dành cho một client đưa kết quả ra trước mắt bạn trước khi lưu. Mọi hành vi khác đều giống lần ghi, cùng importer trên cùng nguồn báo cáo cùng các chẩn đoán, nên một nguồn mà lần ghi sẽ từ chối cũng bị từ chối dưới nó. Không có nó thì các tệp nằm trên đĩa và written nêu chúng, còn drafts vắng mặt thay vì lặp lại các byte bạn đã yêu cầu ghi.

Các bản nháp là điểm khởi đầu thuộc về bạn và bạn tiếp tục chỉnh sửa. Việc những gì chúng nói có được chấp nhận hay không — một socket có phải là socket mà producer khai báo, hay khả năng áp dụng của một Feature có được thỏa mãn — không được quyết định ở đây. Đó là điều validate trả lời.

Trên standard input và output, cùng khả năng này cũng truy cập được dưới dạng cli-import, công cụ chạy lệnh và trả về văn bản nó đã in; qua HTTP công cụ đó không tồn tại, và công cụ này là cách truy cập khả năng đó ở đó.

Xuất bản, ký và thu hồi

Bốn công cụ đặt một thứ vào nơi người khác sẽ phân giải nó. publish-entity đóng gói một thực thể catalog và xuất bản nó; publish-artifact xuất bản một tệp độc lập, chẳng hạn một gói tài liệu, với các byte được giữ nguyên dạng mờ và không phân tích phong bì thực thể nào; sign-artifacts ký các tham chiếu đã được xuất bản và đính kèm từng chữ ký, giữ nguyên một tham chiếu đã mang một chữ ký mà chính sách tin cậy của registry của nó xác minh được; deprecate-artifact đính kèm một dấu thu hồi đã ký vào một tham chiếu. Hãy đọc What an assistant can do without asking you first trước khi bạn cho phép bất kỳ công cụ nào trong số này: đây là những công cụ có tác động vượt ra ngoài máy.

publish-entity nhận entity, tài liệu cần xuất bản, và một Plugin còn cần plugin, tệp thực thi được xuất bản bên trong manifest của nó. publish-artifact nhận file cùng với name và tag mà nó được xuất bản dưới đó. Mọi đối số đường dẫn ở đây là tuyệt đối hoặc tương đối với gốc workspace, cùng một hợp đồng mà mọi công cụ khác trên bề mặt này sử dụng, và workspace_root chỉ định workspace mà lệnh gọi muốn nói đến — trên một server được truy cập qua đầu vào và đầu ra chuẩn. Một server được truy cập qua HTTPS từ chối workspace_root và yêu cầu mỗi đường dẫn đó phải phân giải bên trong workspace mà nó phục vụ, như One process, one workspace trình bày. registry là đích đến và mặc định là registry được cấu hình của workspace; không gửi cả hai, khi không có mặc định nào được cấu hình, sẽ bị từ chối kèm theo việc nêu rõ cần gửi gì. sign-artifacts nhận references, một hoặc nhiều địa chỉ registry thay vì đường dẫn, và tùy chọn jobs, số lượng tham chiếu được ký cùng lúc: nếu bỏ qua, chúng được ký lần lượt từng cái, và một giá trị nhỏ hơn 1 sẽ bị từ chối kèm theo việc nêu rõ cần gửi gì. Mỗi tham chiếu vẫn được ký đúng như khi được ký riêng, như aggrega sign mô tả. deprecate-artifact nhận hoặc reference cùng với severity và reason, hoặc from chỉ định một tệp lô — và từ chối các đối số nội dung được gửi kèm một tệp lô thay vì bỏ qua chúng, vì một tệp lô tự cung cấp nội dung của riêng nó và một đối số bị lặng lẽ bỏ qua sẽ trông như một đối số đã được tôn trọng.

Hai công cụ xuất bản nhận dry_run, cho thấy một lần xuất bản sẽ gửi gì mà không liên hệ với registry nào. Nó tính toán gói, báo cáo những gì nó lẽ ra đã xuất bản, và trả lời với beyond_this_machine là false cùng đích đến mà nó lẽ ra đã gửi tới trong registries; publish-entity cũng trả lời với digest mà lần xuất bản đó sẽ tạo ra, chính là digest mà aggrega push --dry-run in ra. Đây là cách để cho ai đó xem một lần xuất bản được đề xuất trước khi nó trở thành thật. Việc ký và thu hồi không có dạng như vậy: cả hai đều tác động lên thứ đã được xuất bản, nên không có gì để xem trước.

publish-entity trả lời với windows_unusable_entries khi kho lưu trữ mà nó xuất bản chứa các mục mà Windows không thể lưu giữ như đã viết — một đường dẫn có một phần được đặt tên theo một thiết bị, chẳng hạn CON, AUX hoặc NUL, ở bất kỳ kiểu chữ hoa thường nào và bất kể phần mở rộng nào theo sau, hoặc một phần kết thúc bằng dấu chấm hay dấu cách — nêu tên từng mục, tên tệp của chính tài liệu thực thể trước, rồi đến các tệp mà nó mang theo. Trường này vắng mặt khi không có mục nào, bao gồm cả trường hợp một thực thể được xuất bản chỉ với tài liệu của nó. aggrega chạy trên Windows từ chối giải nén một mục như vậy, nên một workspace Windows không thể sử dụng phiên bản đó; đây là những mục mà aggrega push cảnh báo, và văn bản của câu trả lời cũng nêu tên chúng. Chúng không từ chối gì cả: lệnh gọi vẫn tiếp tục hoặc bị từ chối đúng như khi không có chúng, kể cả với dry_run.

publish-entity nhận pin_sources, chạy bước pin của tác giả thực thể trên thực thể trước khi nó được đóng gói, nên entity.lock mà bước này ghi bên cạnh nó là một phần của những gì được xuất bản. Đó là cùng bước mà công cụ pin chạy, ghi cùng các byte, và nó chạy trước mọi sự từ chối đánh giá thực thể — nên một lần xuất bản bị từ chối ở đó, chẳng hạn vì thiếu chữ ký, vẫn để lại tệp lock đã được ghi bên cạnh thực thể. Một sự từ chối về chính lệnh gọi, chẳng hạn một workspace ngoại tuyến hoặc không có đích đến, sẽ đến trước và không pin gì cả. Bỏ nó đi thì pin_sources_at_push của workspace quyết định; gửi nó thì nó quyết định theo cả hai hướng. Một lần xuất bản có pin sẽ ghi vào bên trong workspace cũng như vào registry, nên qua HTTP nó cần một thông tin xác thực mang cả hai phạm vi, và một thông tin xác thực chỉ mang phạm vi cho phép xuất bản sẽ bị từ chối kèm theo việc nêu tên phạm vi còn lại. Kết quả mang pin, theo dạng mà công cụ pin trả lời, khi bước này đã chạy; dưới dry_run bước này báo cáo tệp lock mà nó sẽ ghi và không ghi gì. Khi bước này không chạy, một Recipe hoặc FeatureRecipe mà entity.lock của nó không ghi nhận pin nào cho một đầu vào mà nó đọc sẽ bị từ chối — hoặc một pin mà đầu vào không còn khớp nữa — trước khi bất cứ thứ gì được đóng gói, kể cả với dry_run, kèm theo việc nêu tên aggrega pin, pin_sources và pin_sources_at_push. Đó là sự từ chối mà pull đưa ra đối với cùng tệp lock, và việc kiểm tra nó sẽ tải đầy đủ từng nguồn từ xa mà thực thể ghi ra, như bước này sẽ làm.

Việc ký là nơi thông tin xác thực được sử dụng, và ba trong bốn công cụ làm việc này — một lần xuất bản artifact dữ liệu không ký gì, và được ký sau đó theo tham chiếu. identity_token cung cấp một danh tính không khóa cho lệnh gọi. Trên một server được truy cập qua đầu vào và đầu ra chuẩn, bỏ nó đi sẽ chuyển sang danh tính mà môi trường riêng của server đó mang theo, và key_path chọn một khóa được giữ ngoại tuyến thay thế. Qua một listener thì không thể truy cập cả hai thứ đó: môi trường không được đọc, key_path bị từ chối và bị loại khỏi những gì ba công cụ này quảng bá, và một khóa mà cấu hình của workspace được phục vụ chỉ định sẽ không được truy cập — nên chỉ một token được gửi trong lệnh gọi mới ký, như Which credentials a call spends trình bày. Một lệnh gọi ký bằng một thông tin xác thực. Mọi tham chiếu được gửi đến sign-artifacts, và mọi mục của một tệp lô mà deprecate-artifact đọc, đều được ký bằng cùng một khóa được giữ hoặc cùng một danh tính không khóa; khi cấu hình của workspace được phục vụ chỉ định một khóa cho registry của một tham chiếu và không có khóa nào cho registry của tham chiếu khác, hoặc hai khóa khác nhau, lệnh gọi không ký gì và bị từ chối kèm theo việc nêu tên các registry ở mỗi bên, trước khi bất kỳ danh tính nào được phân giải hay bất kỳ registry nào được đọc — hãy gửi một lệnh gọi cho mỗi thông tin xác thực, hoặc một key_path cho tất cả trên đầu vào và đầu ra chuẩn. Qua một listener không khóa được cấu hình nào được truy cập, nên ở đó mọi tham chiếu được ký bằng danh tính mà lệnh gọi gửi và lệnh gọi không bao giờ bị từ chối vì lý do này. Sự từ chối được mô tả trong References signed together need different signing credentials (Các tham chiếu được ký cùng nhau cần các thông tin xác thực ký khác nhau). fulcio_url, rekor_url và timestamp_url ghi đè các endpoint không khóa mà workspace cấu hình, trên cả hai phương thức truyền tải. Khi không có danh tính nào được phân giải, lệnh gọi từ chối và nêu rõ cần gửi gì — không có gì ở đây mở trình duyệt hay chờ một người, vì không có ai theo dõi một luồng giao thức, và một lệnh gọi bị treo sẽ là sự thất bại thầm lặng mà sự từ chối tồn tại để ngăn chặn. Trên publish-entity, việc có đính kèm chữ ký hay không tuân theo chính sách của registry đích trừ khi sign nói khác, và một registry yêu cầu chữ ký sẽ từ chối một lần xuất bản không được ký bất kể bạn gửi gì: không có đối số nào vượt qua sự từ chối đó. Xem aggrega sign để biết hai chế độ ký và những gì mỗi chế độ liên hệ.

Mỗi kết quả mang các dữ kiện chứ không phải một bản ghi lại diễn biến: nơi artifact được đưa tới, tag của nó, digest đã công bố — hoặc, với lần chạy thử của một thực thể catalog, digest mà một lần công bố sẽ tạo ra — tag đó có đã trỏ tới nội dung giống hệt từng byte hay chưa, một lần công bố có được ký hay không, và reach của nó. Một lô ký báo cáo mọi tham chiếu đã được ký cùng digest mà chữ ký của nó cam kết, theo thứ tự các tham chiếu được đưa ra, và một lô trong đó có bất kỳ tham chiếu nào thất bại sẽ trả về dưới dạng một lỗi nêu tên từng tham chiếu, chứ không phải một kết quả với danh sách thiếu — một lô chỉ hoàn thành một phần mà được báo là thành công chính là cách một lần từ chối bị đọc thành một lần thông qua. Một lần ngừng hỗ trợ báo cáo mỗi dấu đánh với digest riêng của nó, vì một dấu đánh được gắn như một referrer không có tag của artifact mà nó rút lại và không có gì khác trỏ tới nó. Việc ký hoặc rút lại một tham chiếu mà chưa có gì được công bố sẽ bị từ chối chứ không được gắn vào hư không.

Hai phần của một câu trả lời

Mọi công cụ đều trả lời bằng một văn bản dễ đọc, kèm theo một kết quả có cấu trúc ở bất cứ nơi nào thao tác có kết quả đó. Văn bản được viết cho người đọc cuộc hội thoại. Kết quả có cấu trúc mang cùng câu trả lời dưới dạng các trường mà chương trình đọc được — một phán quyết, một danh sách tệp, một chẩn đoán — và một lần từ chối cũng mang một kết quả như vậy khi thao tác đã có các phát hiện trong tay lúc từ chối, như Một bản build bị từ chối trả lại những gì mô tả cho một bản build.

Kết quả có cấu trúc cũng mang văn bản, dưới dạng text_answer. Kết quả có cấu trúc của mọi công cụ đều có trường text_answer chứa văn bản của câu trả lời đúng như văn bản đó: mọi câu, theo đúng thứ tự, không thay đổi. Vì vậy, một client đưa cho mô hình của nó kết quả có cấu trúc thay vì văn bản, như Claude Desktop làm, vẫn đưa cho mô hình mọi câu mà văn bản nói — dòng mở đầu câu trả lời của describe-capabilities khi không có đối số, cấu hình đang có hiệu lực mà config-show báo cáo, câu nêu tên thư mục mà một câu trả lời đã dùng khi không tìm thấy workspace nào. text_answer được ghi đầu tiên, trước các trường mà công cụ trả lời, và đó là văn bản mà bên gọi nhận được: qua HTTP, nó gọi tên từng vị trí trên máy chủ của server giống như văn bản, như Một câu trả lời nói gì về hệ thống tệp của server trình bày. Bản thân văn bản vẫn là văn xuôi như vốn có, dành cho các client đọc nó, nên cùng những từ ngữ đó xuất hiện hai lần trong mỗi câu trả lời.

Không công cụ nào là ngoại lệ, kể cả lint. Không công cụ nào trả lời bằng một trường riêng tên là text_answer, nên trường này không bao giờ thay thế cho một trường như vậy. Kết quả có cấu trúc của lint giữ summary của nó — số thực thể đã kiểm tra và số phát hiện, tổng cộng và theo mức độ nghiêm trọng, dưới các tên mà aggrega lint ghi với -o json — và mang text_answer bên cạnh. describe-capabilities cũng giữ các trường riêng của nó: version_summary, riêng dòng phiên bản, khi nó được gửi mà không có đối số, và trong mỗi mục của index là một summary, mục đích một dòng của công cụ đó.

Không công cụ nào quảng bá một output schema. Danh sách của một công cụ mang schema cho các đối số nó nhận và không có schema nào cho kết quả của nó, nên text_answer được nêu tên ở đây thay vì trong một schema.

Một câu trả lời không có kết quả có cấu trúc thì chỉ là văn bản của nó. Việc từ chối các đối số của một lời gọi, và bất kỳ lỗi nào khác mà thao tác không có gì có cấu trúc để báo cáo, sẽ trả về dưới dạng văn bản và không gì khác, và khi đó văn bản là phần duy nhất mà client có để đưa cho mô hình của nó.

Khi một lệnh gọi không thành công

Câu trả lời đến qua kênh nào phụ thuộc vào một điều duy nhất: bên gọi có thể khắc phục nó bằng cách thay đổi các đối số của một công cụ đang tồn tại hay không.

Mọi thứ có thể khắc phục theo cách đó đều được trả về dưới dạng kết quả của chính công cụ, được đánh dấu là thất bại và mang nội dung sửa lỗi làm văn bản của nó — một tổ hợp bộ chọn mà công cụ không chấp nhận, một đối số bắt buộc bị bỏ sót, một đối số được gửi sai kiểu JSON, một đường dẫn không phân giải được, một chẩn đoán từ trình biên dịch. Đó là kênh mà trợ lý được hiển thị, nên nó đọc được điều gì đã sai và gọi lại với đối số đã được sửa.

Kênh lỗi của giao thức được dành cho những gì không có kết quả công cụ để chứa: một tên công cụ mà máy chủ không phục vụ, một yêu cầu có tham số mà máy chủ không đọc được, một phương thức mà máy chủ không triển khai, và một thông điệp hoàn toàn không phải JSON hợp lệ. Việc đọc một tài nguyên và hiển thị một prompt cũng trả lời qua kênh đó, vì cả hai kết quả này đều không mang cờ thất bại riêng.

Schema được công bố của một công cụ cũng khai báo phần lớn các quy tắc mà đối số của nó phải thỏa mãn — những bộ chọn nào loại trừ lẫn nhau, đối số nào chỉ có ý nghĩa khi đi kèm một đối số khác, và những đối số nào là bắt buộc — nên một client soạn lệnh gọi theo schema đã khai báo hiếm khi phải thực hiện lệnh gọi mới biết được chúng. Một quy tắc mà schema không nêu vẫn bị từ chối, kèm một câu nêu tên quy tắc đó; quy tắc của pull rằng verify không được kết hợp với upgrade_targets hoặc pin_sources được cố ý để cho việc từ chối xử lý, vì lý do được nêu tại Phân giải những gì một Release phụ thuộc vào.

Điều gì dừng máy chủ

Qua đầu vào và đầu ra chuẩn, việc đóng kết nối sẽ dừng máy chủ. Máy chủ đọc mỗi dòng một thông điệp và thoát gọn gàng khi đầu vào chuẩn của nó đến cuối luồng, nên một client đóng kết nối sẽ tắt máy chủ. Đó là trường hợp thông thường trên phương thức truyền này, vì bạn không bao giờ tự khởi chạy lệnh: chính client đã khởi động nó là thứ kết thúc nó, nên việc thoát trình soạn thảo, hoặc tắt máy chủ này cho một dự án, thường là cách dừng nó.

Yêu cầu chính tiến trình dừng lại sẽ tác động đến máy chủ trên cả hai phương thức truyền. Một tín hiệu ngắt từ terminal, hoặc một yêu cầu kết thúc từ trình giám sát hay container runtime, sẽ tắt máy chủ ngay ở yêu cầu đầu tiên, dù client có đang gửi gì hay không: máy chủ ngừng nhận thông điệp, kết thúc công việc mà lời gọi đang xử lý, và thoát gọn gàng. Yêu cầu thứ hai sẽ kết thúc tiến trình ngay lập tức. Do đó, qua đầu vào và đầu ra chuẩn, một lời gọi vẫn đang chạy khi tiến trình được yêu cầu dừng sẽ không hoàn tất; còn một listener thì xả hết, cho phép lời gọi đang được trả lời hoàn tất trong một khoảng thời gian giới hạn trước khi tiến trình thoát.

Client cũng có thể dừng một lời gọi mà không dừng máy chủ, và cách thực hiện tùy thuộc vào phương thức truyền. Các lời gọi được trả lời đồng thời, nên việc kết thúc một lời gọi được xử lý ngay khi lời gọi đó vẫn đang chạy thay vì phải chờ sau nó. Qua đầu vào và đầu ra chuẩn, client nêu id của lời gọi; hủy một lời gọi đã được trả lời, hoặc một lời gọi mà máy chủ không xử lý, sẽ không có tác dụng gì — chính điều đó khiến việc gửi thông điệp như vậy là an toàn mà không cần biết trước câu trả lời đã đang trên đường trở về hay chưa. Qua HTTP thì không có thông điệp nào để gửi: đóng kết nối mang lời gọi sẽ kết thúc nó. Dù theo cách nào, lời gọi đều được yêu cầu dừng — công việc của nó kết thúc tại điểm kiểm tra tiếp theo của thao tác, và một thao tác không bao giờ kiểm tra sẽ chạy đến hết — không có gì được gửi thêm cho lời gọi đó, mọi lời gọi khác đang diễn ra vẫn tiếp tục, và máy chủ vẫn tiếp tục phục vụ.

Khi nào nên dùng

Hãy dùng aggrega mcp khi bạn muốn một trợ lý AI giúp soạn các thực thể Aggrega dựa trên các schema và tài liệu tham chiếu thực — để các gợi ý của nó dựa trên đúng cấu trúc mà trình biên dịch chấp nhận thay vì phỏng đoán. Nó khớp trực tiếp với vòng lặp soạn thảo: trợ lý đọc schema và tài liệu tham chiếu của một loại, dựng một bộ khung, điền các trường mà vai trò của bạn sở hữu, và xác thực trước khi trả bản nháp lại. Xem Soạn thảo tệp Aggrega để biết về vòng lặp đó.

Qua đầu vào và đầu ra chuẩn, thông thường bạn không bao giờ tự gõ aggrega mcp. Thay vào đó, bạn khai báo nó một lần trong cấu hình MCP của client, và client sẽ khởi động và dừng nó cho bạn. Một listener là trường hợp còn lại: khi đó bạn tự chạy tiến trình, và nó tiếp tục chạy cho những bên gọi không phải là người đã khởi động nó.

Ví dụ: cấu hình client qua đầu vào và đầu ra chuẩn

Trỏ một MCP client tới lệnh này bằng một mục máy chủ stdio:

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

Điều kiện tiên quyết duy nhất là tệp nhị phân aggrega đã được cài đặt và nằm trong PATH của client. Để biết đường dẫn cấu hình cho từng client và cách khắc phục sự cố, xem Kết nối máy chủ MCP. Để lấy một schema trực tiếp từ dòng lệnh mà không cần client, xem aggrega get-schema.