aggrega mcp
Menjalankan server Model Context Protocol melalui input dan output standar, atau melalui HTTP, untuk integrasi asisten AI
Sinopsis
aggrega mcp [flags]Deskripsi
Run Aggrega as a Model Context Protocol (MCP) server, so an AIassistant can discover and drive Aggrega operations through a structuredprotocol instead of scraping command output.
Two transports reach the same server, and --transport chooses betweenthem, with mcp.transport in the workspace configuration as the key itoverrides. The default, stdio, speaks newline-delimited JSON-RPC 2.0 overthe process's standard input and output, which is how an MCP-capableclient runs it: spawned as a subprocess, not typed by hand. http servesthe protocol over HTTP instead — one long-running process on a host,reached by callers who are not at its keyboard — on the address --listennames, or mcp.listen when the flag is absent.
An address chooses no transport. --listen given with the stdio transportis refused, whether stdio was typed, configured or left as the default,because it names where to listen for a transport that does not listen.An address mcp.listen names is left unused by a server on standard inputand output, which says so in one line on stderr, so a client can launchthis command in a directory whose configuration is written for alistener. And the http transport with no address from either is refusedbefore anything binds.
It speaks two MCP protocol revisions on both transports, 2026-07-28 and2025-06-18, so a client of either connects. In 2026-07-28 nothing issettled for the connection as a whole: every request states the protocolversion it speaks and the capabilities its sender offers, and the serverreads both from the request it is answering rather than holding anythingbetween messages. In 2025-06-18 a client settles those same facts once,by opening the connection with an initialize handshake.
Both revisions reach the same server, and a client learns the samethings about it either way. A client on 2026-07-28 calls server/discoverfor the revisions the server speaks, the capabilities it advertises —tools, resources, and prompts — and the guidance it offers a modelbefore the first call. A client on 2025-06-18 receives those samecapabilities, and that same guidance, in the reply to its handshake.
From there the client discovers the server's surface through the listmethods (tools, resources, resource templates, and prompts) and invokesit through tools/call and resources/read. The server exposes Aggregaoperations — compiling and inspecting a Release, reading catalogentities — as tools and resources an assistant can call directly.
On standard input and output, stream discipline is strict: stdout carriesonly protocol messages, one JSON object per line, so the client can parsethe stream without heuristics. Every log, warning, and diagnostic iswritten to stderr instead. The server reads one message per line andexits cleanly when stdin reaches end of stream, so a client that closesthe connection shuts the server down. A client ends one call by namingits id, and every other call carries on.
Over HTTP there is one endpoint, /mcp, accepting POST. Every message isits own request and no session of any kind is kept, so nothing a clientsends first decides how a later request is answered. Closing theconnection ends the call it carried. A request carrying an Origin headeris checked against mcp.allowed_origins, and mcp.limits bounds how largeone request body may be, how many requests are answered at once, and howmany one caller may send in a minute. A caller sending faster thanmcp.limits.requests_per_minute is answered 429, counted against thatcaller alone.
Every request to /mcp carries a credential, and which one depends onwhether a proxy in front has already checked it. By default it is abearer token the server verifies itself, against the keysmcp.authorization.issuer publishes: it must come from that issuer, namemcp.authorization.resource among its audiences, be inside its validitywindow, and be signed with an asymmetric algorithm. A request carrying notoken is answered 401 with a challenge, and so is one whose token failsany of those. A token is never accepted from the address, never forwardedanywhere, never exchanged, and never written to any log; the subject itnames is recorded and compared to nothing.
Set mcp.authorization.trusted_proxy instead and the caller is read from aheader the proxy sets rather than from a token, with its scopes from asecond header; no token is read at all in that mode, and a requestwithout the principal header is answered 401. Because that header is thenthe whole credential, it is trustworthy only where nothing else can setit: the process is refused before it binds unless mcp.listen is loopbackor a Unix socket.
The challenge names where to obtain a token. A listener publishes anOAuth protected-resource metadata document, with no credential asked for,naming the authorization server, this deployment's own address and thescopes that exist; it is served at /.well-known/oauth-protected-resourceand at that path followed by the endpoint path, which are the two placesa client looks. A client reads it before it can hold a token, which iswhy it is the one answer given without one. What that document publishescomes from mcp.authorization.issuer and mcp.authorization.resource, and alistener is refused before it binds unless both are set.
The issuer is an https address unless the authorization server runs onthis machine (localhost, 127.0.0.1 or ::1), and that holds in everymode: with the keys read from the issuer, with a key file, and with aproxy in front. Every client is sent to the issuer to obtain its token,so a plain http issuer on another host would carry each client'sauthorization code and token across the network unprotected, and alistener naming one is refused before it binds.
The verification keys are read from the issuer itself, by asking it whereit publishes them and fetching them from the address it names, and readagain once when a token arrives signed by a key identifier the held setdoes not carry. That address is held to the same rule as the issuer, andso is every redirect either read is answered with: a plain http addresson another host is never asked, and a token needing those keys isanswered 503 until the authorization server publishes its metadata andkeys over https. A workspace that is offline makes no such request, sothere mcp.authorization.jwks_file names a file holding those keys and alistener is refused before it binds without it.
Liveness and readiness are answered on a second address, and only there.Set mcp.health.listen and a GET of /healthz reports that the process isrunning while a GET of /readyz reports whether it can answer a call yet,each a status code with an empty body and no credential asked for. Theaddress opens before the workspace is resolved, so a supervisor sees theprocess alive while it is still deciding whether it can serve at all.Leave the key unset and no second listener exists. The endpoint itselfanswers both paths the same not-found it gives every path it does notserve, with a token and without one, so reaching this process over thenetwork is never a way to probe it.
The workspace this process serves is fixed when it starts, on eithertransport: --workspace-root names it, and AGGREGA_WORKSPACE_ROOT suppliesit when the flag is absent. The folder named is the workspace rootitself, as it is for every command: a call naming no workspace of itsown is answered there, and nothing above it is searched for a workspace,so name the folder that holds the workspace's .aggrega-config.yaml. Anamed folder that does not exist is refused, naming the flag or thevariable that supplied it and the value as it was given: a listener isrefused before it binds, while a server on standard input and outputwrites the refusal to stderr and starts all the same, answering everycall that acts in that workspace with it, so a client that showsnothing of stderr still shows the refusal. An emptyAGGREGA_WORKSPACE_ROOT is read as unset, but for one launch: a serveron standard input and output given no --workspace-root, whoseenvironment carries the AGGREGA_BUNDLE_VERSION the desktop bundle sets,was started with the desktop application's Workspace folder settingempty. It is served the same way, the refusal naming that setting, sono call naming no workspace of its own is answered in the directory itwas started in. In every other case where neither names a root, aserver on standard input and output resolves the workspace from thedirectory it was started in, while a listener is refused before itbinds unless a workspace resolves there: one reachedover HTTP serves a workspace an operator chose rather thanwhichever directory it happened to be started in. Where that directoryanchors no workspace, a call naming no workspace of its own that namesits Release or document by an absolute path is answered in the workspacethat file's folder resolves, as the same command typed at a terminal inthat directory would be.
For the same reason a call arriving over HTTP cannot name a workspace ofits own. Sending workspace_root or catalog_dirs is refused, naming theargument, and the directories searched for catalog entities beside theserved workspace are the ones that workspace itself resolves: its ownworkspace.catalog_dirs setting — or, for a Release it gives directoriesof its own under workspace.releases, that Release's — then its catalogdirectory. Overstandard input and output both arguments are honoured: the client thatlaunched the server is running on this machine.
A workspace_root such a call sends is read the same way by every tool,the tools that run a command included. An absolute one is used asgiven. A relative one is read from the root a call naming no workspaceof its own is answered in — the folder --workspace-root orAGGREGA_WORKSPACE_ROOT names, which the desktop application sets fromits Workspace folder, or, where neither names one, the workspace rootthe directory the server was started in resolves to — so a client thatcannot see where that folder sits on the machine still names a folderinside it, as quickstart-ai/1. Where there is no such root to read itfrom, a relative one is refused as a call naming none is refused, andan absolute one is answered as it always is.
Asking the process itself to stop — an interrupt from the terminal, or atermination request from a supervisor or container runtime — shuts theserver down on the first request, whether or not a client is sendinganything: it stops accepting messages, ends the work a call in progressis doing, and exits cleanly. A listener stops accepting and lets a callalready being answered finish, within a bounded budget, before theprocess exits. A second request ends the process at once.Flag
| Flag | Default | Deskripsi |
|---|---|---|
--listen | — | Alamat tempat transport HTTP mendengarkan, dalam salah satu dari dua bentuk: host:port, atau unix: diikuti path sistem file. Flag ini menentukan tempat mendengarkan dan tidak memilih transport: flag ini dibaca dengan —transport http, atau mcp.transport: http di konfigurasi workspace, dan bila diberikan bersama transport stdio, flag ini ditolak. Listener tanpa sertifikat melayani teks biasa dan hanya diizinkan pada loopback (127.0.0.1, ::1, localhost) atau pada socket Unix, yaitu bentuk yang diambil server di balik proxy terminasi; alamat lain mana pun memerlukan mcp.tls.cert_file dan mcp.tls.key_file, yang kemudian digunakan proses ini untuk menerminasi TLS sendiri. Bila diatur, flag ini menimpa kunci konfigurasi mcp.listen. |
--transport | — | Cara server dijangkau: stdio menjalankan protokol melalui input dan output standar, yaitu cara klien yang meluncurkan perintah ini sebagai subproses menjangkaunya; http melayaninya melalui HTTP di alamat yang disebutkan —listen atau mcp.listen, dan melalui HTTPS bila mcp.tls menyebutkan sertifikat dan kunci. Bila diatur, flag ini menimpa kunci konfigurasi mcp.transport, yang default-nya adalah stdio. |
Apa yang dilakukannya
aggrega mcp menjalankan server Model Context Protocol. Dua transport menjangkaunya, dan --transport memilih di antara keduanya: stdio atau http, dengan mcp.transport di konfigurasi workspace sebagai kunci yang ditimpa flag tersebut, dan stdio sebagai default.
Melalui stdio, yang merupakan default, server berkomunikasi melalui input dan output standar proses. Dalam bentuk itu, server ini bukan perintah yang Anda jalankan secara interaktif — klien yang mendukung MCP meluncurkannya sebagai subproses dan menjalankan protokol melalui stdio; halaman Menghubungkan server MCP mencantumkan tempat setiap klien menyimpan entri yang meluncurkannya. Menjalankannya mengubah CLI menjadi asisten penulisan yang memahami Aggrega di dalam editor atau klien chat Anda.
Melalui http, server justru melayani protokol melalui HTTP: satu proses yang berjalan lama di sebuah host, dijangkau oleh pemanggil yang tidak berada di depan keyboard-nya, mendengarkan di alamat yang disebutkan --listen, atau mcp.listen bila flag tersebut tidak ada. Lihat Menjangkau server melalui HTTPS untuk cara listener tersebut dikonfigurasi dan apa yang diterimanya.
Server ini mendukung dua revisi protokol, 2026-07-28 dan 2025-06-18, sehingga klien dari salah satunya dapat terhubung dan menjangkau permukaan yang sama. Revisi yang digunakan sebuah panggilan dinyatakan pada panggilan itu, bukan disepakati sekali untuk koneksi. Klien pada 2026-07-28 mengirimkan versi protokol yang digunakannya dan kapabilitasnya sendiri bersama setiap permintaan, dan menanyakan kepada server/discover apa yang didukung server; klien pada 2025-06-18 menetapkan hal-hal yang sama itu sekali saja, dengan membuka koneksi menggunakan handshake initialize. Bagaimanapun, server tidak menyimpan apa pun di antara pesan, sehingga apa yang Anda kirim pertama kali tidak menentukan apa pun tentang bagaimana panggilan berikutnya dijawab. Permintaan yang menyebutkan revisi yang tidak didukung server akan ditolak dan diberi tahu dua revisi mana yang dapat dimintanya, alih-alih dijawab seolah-olah meminta salah satunya.
Server mengekspos tiga permukaan kepada asisten yang terhubung:
-
Prompt — dua kelompok, dan perbedaannya terletak pada apa yang dijawab masing-masing. Prompt penulisan menjawab “apa yang sedang saya tulis”: satu persona per peran (pengembang, arsitek, operasi), ditambah satu template terfokus per entitas. Masing-masing membingkai peran dan mengarahkan asisten ke schema, halaman referensi, dan panduan penulisan yang tepat, sehingga sarannya tetap berada di dalam pilar yang menjadi tanggung jawab peran tersebut. Prompt alur kerja menjawab “panggilan apa, dalam urutan apa”: masing-masing menguraikan urutan panggilan alat yang mencapai tujuan yang mencakup beberapa operasi, dengan titik-titik keputusan di antaranya — menyusun Aggregate baru dan Release-nya dari awal, membawa chart, modul infrastruktur, atau file container-compose yang sudah ada ke dalam Aggrega, mencari tahu mengapa sebuah build tidak terkompilasi atau me-render artefak yang salah.
prompts/listmengenumerasi kedua kelompok danprompts/getme-render salah satunya, sehingga himpunannya dibaca dari server, bukan dari halaman ini.Prompt alur kerja menyebutkan panggilan-panggilannya dan Anda yang melakukannya, satu per satu, dengan membaca setiap hasil sebelum panggilan berikutnya. Tidak ada panggilan yang menjalankan seluruh tujuan: setiap alat membungkus satu operasi yang dapat Anda periksa, sehingga urutan itulah yang membawa Anda ke sana. Persona penulisan menerima
kindopsional untuk difokuskan, template per entitas mewajibkannya, dankindyang tidak dijawab oleh schema mana pun ditolak dengan menyertakan daftar nilai yang diterima, alih-alih diabaikan diam-diam. -
Sumber daya — materi referensi hanya-baca yang disajikan secara inline:
schema://<kind>untuk JSON Schema sebuah entitas,langref://<path>untuk halaman referensi bahasa mana pun,authoring://<topic>untuk panduan penulisan,catalog://<kind>/<name>untuk YAML yang ditulis dari sebuah entitas katalog, dancli://<command>untuk bantuan milik sebuah perintah, dengancli://saja sebagai titik masuknya — bantuan tersebut dijawab dari perintah-perintah yang dibawa server itu sendiri, sehingga membacanya tidak memulai proses apa pun dan mengembalikan teks yang sama dengan yang dicetak perintah untuk--help. Pembacaancatalog://atas entitas yang tidak dimiliki katalog dijawab sebagai tidak ditemukan; jika hal itu terjadi karena tepat satu file katalog yang mendeklarasikan entitas tersebut dilewati saat pemuatan, pesan jawaban menyebutkan file tersebut, batasan yang dilanggarnya, dan kode pendek kondisinya, alih-alih hanya URI — penolakan yang ditampilkan pertama olehaggrega builduntuk file yang sama.resources/listmengenumerasi sumber daya yang dapat dialamatkan tanpa parameter danresources/templates/listmengumumkan bentuk URI setiap kelompok. -
Alat — tindakan terhadap workspace Anda, dan
tools/listmenjawab dengan semuanya.Alat-alat yang pertama kali ditemui asisten dirancang untuk siklus penulisan:
list-entitiesdanlist-releasesuntuk mengetahui isi workspace,scaffolduntuk kerangka yang membawa kolom-kolom yang diwajibkan jenisnya, dengan placeholder di mana pun sebuah nilai diperlukan — atau, bila dikirimiexample, untuk menulis salah satu contoh dokumentasi yang dapat dijalankan ke direktori baru, dengan menjawab berupa lokasi direktori tersebut, file yang ditulis, dan perintah untuk membangunnya, dan bila dikirimilist: true, untuk mencantumkan contoh-contoh tersebut —get-schemauntuk JSON Schema sebuah entitas,validateuntuk memvalidasi draf (alat ini menyebutkan setiap placeholder yang masih dibawa draf, dan apa yang diterima masing-masing),describeuntuk mendeskripsikan entitas katalog — atau entitas yang dibaca dari registry-nya melalui referensi —pulluntuk me-resolve dependensi sebuah Release ke dalam cache lokal dan menulis lockfile-nya,builduntuk membangun Release menjadi artefak yang di-render — di memori secara default, tanpa artefak yang ditulis ke disk, atau ditulis kedist/di root workspace, tempataggrega buildmenuliskannya, bila Anda mengirimwrite(dan dependensi di-resolve terlebih dahulu hanya bila Anda mengirimauto_pull),gen-cataloguntuk menghasilkan entitas Plugin dari guest Wasm, danexplain-erroruntuk menjabarkan diagnostik kompiler menjadi panduan yang dapat ditindaklanjuti — termasuk, bila diagnostik dimulai dengan kode singkat sebuah kondisi penghentian, kondisi tersebut dan panduan langkah demi langkah yang dipublikasikan untuk perbaikan penulisannya, penjabaran yang sama dengan yang diberikanaggrega explainuntuk kode yang sama di terminal.Sisa permukaan ada di jawaban yang sama, bukan di baliknya: alat-alat lain yang berjalan di dalam server —
lint, alat yang menyebutkan koneksi yang ditulis di suatu tempat dalam dokumen, dua alat kandidasi, alat kontainer lampiran dan titik penyisipan, alat yang menerapkan satu suntingan terbatas pada dokumen,pin, yang mencatat pin konten untuk input sebuah entitas sebagaimana diuraikan di Menyematkan input milik entitas sendiri, dan empat alat publikasi yang dijelaskan di bawah, ditambah inventaris cache dan registry yang dikonfigurasi — dan, untuk klien yang meluncurkan server ini melalui input dan output standarnya, satu alat untuk setiap perintah yang sebenarnya dapat Anda ketik, yang dinamai menurut path pemanggilannya. Alat-alat perintah tersebut hanya ada pada transport itu: server yang dijangkau melalui HTTP tidak menawarkan satu pun di antaranya, karena alasan yang diberikan di Menjangkau server melalui HTTPS. Tidak ada yang ditahan untuk panggilan berikutnya. Seberapa banyak daftar alat yang disodorkan kepada model adalah keputusan klien — klien mengambil definisi dan memilih apa yang dimuat — dan definisi yang tidak pernah diterima klien adalah operasi yang tidak pernah dapat dipanggil model, betapapun terjangkaunya nama alat tersebut di wire. Bila seluruh daftar melebihi apa yang dapat diterima klien Anda, Mempersempit apa yang diumumkan server adalah cara untuk memperpendeknya.describe-capabilitiesmempersempit permukaan tersebut ke jenis entitas yang sedang Anda tulis. Bila dikirimikind, alat ini menjawab dengan alat-alat yang melayani jenis tersebut, yang dibaca dari jenis-jenis yang dideklarasikan setiap alat, bukan dari kata-kata dalam deskripsi; tanpa argumen, alat ini menjawab dengan indeks yang sama atas setiap alat yang ditawarkan server ini kepada Anda — nama masing-masing, tujuan dalam satu baris, jenis yang dilayaninya, dan apakah alat itu menulis, tanpa schema argumen, sehingga seluruh permukaan tiba dalam satu jawaban yang mudah dibaca. Untuk alatcli-, apakah alat itu menulis bergantung pada apakah perintah yang dijalankannya menulis:cli-builddilaporkan sebagai menulis, karena perintahnya menyimpan artefak yang di-render di bawah root workspace, demikian pulacli-scaffold, karena bila dikirimiexampleperintahnya menulis salah satu contoh dokumentasi yang dapat dijalankan ke direktori baru, sedangkan perintah yang hanya membaca dilaporkan sebagai hanya-baca, bahkan bila dalam prosesnya perintah itu mengisi cache yang digunakan bersama oleh semua proyek di mesin tersebut, sama seperti alat yang menjalankan operasi yang sama di dalam server; bila dikirimitoolsyang menyebutkan satu alat atau lebih, alat ini menjawab dengan tepat definisi lengkap dan schema argumen alat-alat tersebut. Alatcli-tidak pernah dipersempit menurut jenis, karena tidak ada yang mencatat jenis entitas mana yang dilayani sebuah perintah, sehingga jawaban yang dibatasi pada satu jenis tidak menyertakannya dan indeks tanpa argumen adalah tempat Anda membacanya. Argumen pada alat perintah dinamai menurut flag milik perintah itu sendiri, sehingga--output-dirdikirim sebagaioutput_dir, dan nama yang tidak dikenali ditolak dengan menyertakan daftar ejaan yang diterima, alih-alih dibuang diam-diam.Beberapa kapabilitas tersedia dua kali pada input dan output standar: alat yang dirancang untuk siklus penulisan menjalankan operasi di dalam server, dan alat yang dinamai menurut perintah yang membawa kapabilitas yang sama menjalankan perintah tersebut. Keduanya tidak berperilaku sama, sehingga pada transport itu masing-masing menyebutkan yang lain dan menyatakan perbedaannya; melalui HTTP, alat-alat perintah tidak ada, dan kalimat pemasangannya dihilangkan alih-alih menunjuk ke alat yang tidak dapat dijangkau pemanggil. Alat yang berjalan di dalam server adalah yang sebaiknya digunakan — alat ini menjawab dengan hasil yang dapat dibaca mesin di samping teks yang dapat dibaca, sehingga asisten mendapatkan putusan, daftar file, atau diagnostik sebagai kolom, bukan sebagai transkrip yang harus di-parse. Alat perintah memulai perintah sebenarnya dalam proses terpisah, sehingga alat ini melakukan apa pun yang dilakukan perintah tersebut di mesin tempatnya berjalan, termasuk menulis ke disk di tempat perintah menulis —
cli-buildmenulis artefak yang di-render kedist/di root workspace, dan file-file build yang dilacak ke.trace/di sampingnya, dan baris penutup yang dikembalikannya menyebutkan direktori tersebut secara lengkap — dan hanya mengembalikan baris perintah yang dijalankannya serta teks yang dicetak perintah tersebut. Gunakan alat ini bila Anda memerlukan flag yang dideklarasikan perintah tetapi tidak diterima alat yang lain.Baris perintah tersebut dimulai dengan flag global yang digunakan untuk memulai server ini dan yang menentukan konfigurasi —
--configdan--offline, bila Anda memberikannya — sebelum perintah dan flag milik panggilan itu sendiri. Jadi perintah tersebut membaca konfigurasi yang dibaca setiap alat lain di sini: server yang dimulai dengan--offlinemenjalankan perintah-perintahnya secara offline, dan server yang dimulai dengan--configmenjalankannya dengan file global tersebut. Flag yang dikirim panggilan untuk dirinya sendiri datang setelahnya dan menang, sehinggaoffline: falsepada sebuah panggilan menjangkau jaringan hanya untuk panggilan itu, dan baris perintah yang dikembalikan menunjukkan keduanya. Bila server dimulai dengan root workspace — melalui--workspace-root, atau melaluiAGGREGA_WORKSPACE_ROOT— baris perintah dimulai dengan root tersebut sebagai--workspace-root, sebelum kedua flag itu, sehingga perintah mengambil direktori tersebut sebagai root workspace-nya, sebagaimana bila diketik dengan flag yang sama dan sebagaimana setiap alat yang berjalan di dalam server mengambilnya, alih-alih menemukan workspace-nya dari direktori tempat server dimulai. Panggilan yang mengirimworkspace_rootmenyebutkan root miliknya sendiri, dan baris perintah hanya membawa root tersebut — termasuk nilai kosong, yang dibaca perintah sebagaimana--workspace-root ""dibaca di terminal: temukan workspace dari direktori tempat server dimulai. Server yang dimulai tanpa keduanya tidak menyerahkan root, sehingga perintah-perintahnya menemukan workspace dari direktori tersebut, sesuai aturan yang ditetapkan Di workspace mana sebuah panggilan dijawab untuk setiap alat — kecuali peluncuran bundle desktop dengan pengaturan Workspace folder kosong, yang padanya panggilan yang tidak menyebutkan workspace miliknya sendiri tidak memulai perintah apa pun dan dijawab dengan penolakan dari pengaturan tersebut. Perintah dimulai di root workspace yang disebutkan oleh panggilan atau peluncuran:workspace_rootmilik panggilan itu sendiri, yang dibaca sebagaimana setiap alat membacanya — yang absolut sebagaimana dikirim, yang relatif dari root tempat panggilan yang tidak menyebutkan root dijawab — dan diserahkan ke perintah dalam bentuk absolutnya, atau jika tidak, root yang digunakan untuk memulai server. Jadi path relatif yang diteruskan sebuah panggilan sebagai file untuk dibaca — dokumen untukvalidate,--release, atau--catalog— dibaca di dalam workspace tersebut, seperti di terminal yang dibuka di sana, dan build yang dijalankan perintah menulisdist/di bawah root tersebut. Bila tidak ada yang menyebutkan root — tidak ada root peluncuran, dan tidak adaworkspace_rootatau yang kosong — perintah dimulai di direktori tempat server dimulai dan membaca path relatif dari sana;workspace_rootyang tidak menyebutkan folder yang ada diserahkan sebagaimana dibaca — yang absolut sebagaimana dikirim, yang relatif dalam bentuk lengkapnya — dan perintah menolaknya dengan kata-katanya sendiri. Perintah yang didaftarkan oleh plugin ekstensi perintah tidak menerima satu pun dari flag tersebut, karena perintah itu meneruskan setiap argumen ke plugin tanpa membacanya alih-alih mem-parse flag global, baik di terminal maupun di sini; perintah itu dimulai di folder yang sama dengan setiap perintah lainnya.Beberapa perintah sengaja tidak ada bahkan pada input dan output standar, tempat alat-alat perintah memang tersedia — melalui HTTP, semuanya tidak ada, dan itu adalah sifat transport, bukan sifat perintah mana pun. Pada input dan output standar, masing-masing perintah ini dikecualikan karena alasan yang dinyatakan: daemon dan server ini sendiri tidak akan pernah mengembalikan hasil; perintah yang membaca kata sandi dari terminal tidak memiliki sumber untuk membacanya; perintah yang menulis skrip pelengkapan shell tidak memiliki shell untuk memasangnya; menghapus kredensial yang tersimpan bekerja pada penyimpanan seluruh mesin, bukan pada workspace yang Anda sebutkan; dan memperoleh token identitas secara interaktif tidak memiliki bentuk non-interaktif untuk ditawarkan. Tidak ada pula, atas dasar seluruh mesin yang sama,
aggrega plugin run-local, yang memuat guest.wasmdari path yang Anda berikan: kegunaan perintah ini adalah membaca file di mana pun Anda meletakkannya, sehingga tidak ada workspace yang dapat membatasinya, dan pembacaan terjadi di dalam proses itu sendiri sebelum guest ada. Guest tidak diberi apa pun saat dijalankan — tidak ada direktori, tidak ada socket, tidak ada lingkungan — tetapi itu adalah batasan pada modul, bukan pada pembacaan, sehingga bukan hal itu yang menentukan. Jalankan perintah ini di terminal Anda, tempat Anda sendiri yang menyebutkan path-nya. Penandatanganan dan publikasi adalah kasus yang sama sekali berbeda, dan perbedaan itulah yang membuat keduanya tidak masuk daftar tersebut. Masing-masing me-resolve identitas dari input yang diberikan atau dari lingkungan dan menolak secara tegas bila tidak ada yang tersedia, sehingga masing-masing memiliki bentuk yang dapat selesai tanpa ada yang mengawasi — sedangkan memperoleh token secara interaktif adalah tindakan yang tidak dapat dipenuhi input apa pun, bahkan secara prinsip. Jadi keduanya tersedia dua kali: sebagai perintah, dan sebagai empat alat dalam proses yang dijelaskan di Memublikasikan, menandatangani, dan menarik. Bila baris perintah akan membuka browser, keduanya menolak dan menyebutkan apa yang harus diberikan sebagai gantinya, alih-alih menunggu orang yang tidak ada.
Di workspace mana sebuah panggilan dijawab
Sebuah panggilan menyebutkan workspace-nya dengan workspace_root; jika tidak, panggilan dijawab di workspace tempat server dimulai. Bila peluncuran menyebutkan root, dengan --workspace-root atau AGGREGA_WORKSPACE_ROOT, root tersebut adalah root workspace itu sendiri, sebagaimana flag tersebut pada setiap perintah: tidak ada yang dicari di atasnya untuk menemukan workspace yang melingkupinya, sehingga peluncuran menyebutkan folder yang berisi .aggrega-config.yaml milik workspace, dan panggilan dijawab di sana baik oleh alat-alat yang berjalan di dalam server maupun oleh alat-alat perintah. Bila peluncuran tidak menyebutkan root, workspace ditemukan dari direktori tempat server dimulai, persis seperti perintah yang diketik di terminal di sana menemukannya — urutannya diuraikan di Cara lain root proyek dikenali — kecuali pada peluncuran bundle desktop dengan pengaturan Workspace folder kosong, yang justru menolak panggilan semacam itu, sebagaimana diuraikan di bawah. workspace_root relatif dibaca dari root tempat panggilan yang tidak menyebutkan root dijawab — root yang disebutkan peluncuran, atau, bila peluncuran tidak menyebutkannya, root workspace yang menjadi hasil resolusi direktori tempat server dimulai — sehingga panggilan menyebutkan folder di dalam workspace, seperti quickstart-ai/1, tanpa mengetahui di mana workspace berada di mesin; yang absolut digunakan sebagaimana diberikan. Setiap alat membacanya demikian, termasuk alat-alat perintah. Bila tidak ada root untuk membaca yang relatif — root peluncuran yang bukan folder yang ada, atau peluncuran desktop dengan Workspace folder kosong — yang relatif ditolak sebagaimana panggilan yang tidak menyebutkan root. workspace_root yang tidak menyebutkan folder yang ada, atau yang menyebutkan file, ditolak sebelum alat melakukan hal lain apa pun, dengan menyebutkan argumennya dan mengutip nilainya — yang absolut sebagaimana dikirim, yang relatif dalam bentuk lengkap sebagaimana dibaca — sama seperti perintah menolak --workspace-root.
Root peluncuran yang bukan folder yang ada dilayani sebagai penolakan pada input dan output standar. Bila --workspace-root atau AGGREGA_WORKSPACE_ROOT menyebutkan folder yang tidak ada, atau menyebutkan file, server menulis penolakan ke aliran error-nya dan tetap dimulai, sehingga klien yang tidak menampilkan apa pun dari aliran tersebut kepada penggunanya tetap menampilkan alasannya. Server menjawab initialize serta daftar alat, sumber daya, dan prompt-nya, dan setiap panggilan yang akan bertindak di workspace tersebut dijawab dengan penolakan: panggilan alat sebagai hasil yang gagal, pembacaan entitas catalog:// atau halaman dokumentasi sebagai error. Penolakan tersebut menyebutkan flag-nya, atau variabelnya bersama pengaturan Workspace folder milik aplikasi desktop yang mengaturnya — pengaturan yang dijelaskan Claude Desktop — dan mengutip nilainya persis sebagaimana diberikan; nilai yang dikirim klien tanpa diisi dikutip sebagaimana tibanya, dan tidak ada isinya yang ditafsirkan. Alat yang menjalankan perintah tidak memulai perintah apa pun untuk panggilan yang tidak menyebutkan workspace miliknya sendiri, karena folder tempat perintah tersebut akan dimulai tidak ada, dan menjawab dengan penolakan yang sama. Panggilan yang menyebutkan workspace miliknya sendiri dengan path absolut dijawab di sana; panggilan yang menyebutkannya dengan path relatif tidak memiliki folder untuk membacanya, dan dijawab dengan penolakan yang sama. Apa yang tidak bertindak di workspace mana pun — schema, prompt, bantuan sebuah perintah — dijawab seperti di server mana pun. Listener justru ditolak saat dimulai, sebelum apa pun di-bind, dengan penolakan yang sama, sehingga siapa pun yang mengawasinya membaca kegagalan tersebut di tempat mereka mencarinya.
Peluncuran desktop dengan pengaturan Workspace folder kosong dilayani sebagai penolakan dengan cara yang sama. Bundle desktop selalu menyerahkan AGGREGA_WORKSPACE_ROOT kepada server, berisi apa pun yang ada di Workspace folder, dan mengatur AGGREGA_BUNDLE_VERSION di sampingnya, sementara aplikasi memulai server di folder pilihannya sendiri — sering kali folder sistem — alih-alih di proyek Anda. Jadi server pada input dan output standar yang dimulai tanpa --workspace-root, yang lingkungannya membawa AGGREGA_BUNDLE_VERSION dan AGGREGA_WORKSPACE_ROOT yang kosong atau tidak ada, tidak mencari workspace dari folder tempatnya dimulai. Server menulis penolakan ke aliran error-nya dan tetap dimulai, menjawab seperti halnya untuk root peluncuran yang tidak ada: setiap panggilan yang akan bertindak di sebuah workspace dan tidak menyebutkan workspace miliknya sendiri dijawab dengan penolakan yang menyatakan bahwa aplikasi desktop meluncurkan server dengan pengaturan Workspace folder kosong, sehingga AGGREGA_WORKSPACE_ROOT tidak menyebutkan root workspace, meminta Anda mengatur Workspace folder ke folder yang berisi .aggrega-config.yaml milik workspace Anda, dan menyatakan bahwa folder yang diatur setelah server dimulai baru berlaku setelah ekstensi dinonaktifkan lalu diaktifkan kembali atau aplikasi dimulai ulang, karena aplikasi menyerahkan pengaturan tersebut kepada server hanya saat memulainya. Alat yang menjalankan perintah tidak memulai perintah apa pun untuk panggilan semacam itu. Panggilan yang menyebutkan workspace miliknya sendiri dengan path absolut dijawab di sana, dan panggilan yang menyebutkannya dengan path relatif dijawab dengan penolakan yang sama, karena tidak ada Workspace folder untuk membacanya; apa yang tidak bertindak di workspace mana pun dijawab seperti di server mana pun. Server mengenali peluncuran tersebut hanya dari AGGREGA_BUNDLE_VERSION: pada bundle yang tidak mengatur variabel tersebut, pengaturan kosong dibaca sebagai tanpa root, dan peluncuran yang mengatur variabel itu secara manual dan tidak menyebutkan root ditolak seperti peluncuran bundle. Setiap nilai kosong lainnya tetap tidak menyebutkan root — AGGREGA_WORKSPACE_ROOT kosong pada peluncuran yang tidak membawa AGGREGA_BUNDLE_VERSION, --workspace-root yang diketik kosong, listener, aggrega serve, dan setiap perintah lainnya masing-masing membacanya sebagai tidak diatur.
Bila tidak ada workspace yang ditemukan dan tidak ada yang disebutkan, jawaban tentang workspace menyatakan folder mana yang digunakannya. Tanpa root peluncuran, tanpa workspace_root pada panggilan, dan tanpa apa pun yang menjangkarkan workspace dari folder tempat panggilan dijawab, panggilan dijawab di folder tersebut. Bila hasil alat bergantung pada workspace — alat-alat yang sama yang perintahnya memberi peringatan di baris perintah — teksnya diakhiri dengan peringatan baris perintah, <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace, dan satu baris yang meminta Anda mengirim workspace_root yang menyebutkan folder berisi .aggrega-config.yaml milik workspace Anda; jawaban yang tidak ditentukan oleh workspace, seperti pembacaan konfigurasi atau daftar plugin, tidak menyatakan apa pun tentang workspace. Kalimat tersebut tidak menambahkan kolom tersendiri ke hasil terstruktur; hasil terstruktur membawanya di text_answer, yang berisi teksnya, sebagaimana diuraikan Dua bagian sebuah jawaban. Alat yang menjalankan perintah dalam proses terpisah membawa baris milik perintah itu sendiri yang menyatakan hal yang sama, sebagaimana dicetak perintah tersebut. Tidak ada yang ditulis ke cache artefak di folder semacam itu: pull, atau build yang diminta me-resolve dependensinya terlebih dahulu, ditolak di sana sebelum apa pun diambil, dengan menyebutkan folder tersebut dan dua pilihan yang tersedia — mengirim workspace_root, atau memberi folder tersebut .aggrega-config.yaml yang membawa blok workspace:. Pin, atau publikasi sebuah Recipe atau FeatureRecipe, ditolak dengan cara yang sama bila akan mengambil sumber jarak jauh yang ditulis lengkap oleh entitas — untuk menyematkannya, atau untuk membandingkan pin-nya — sebelum sumber tersebut diambil; bila tidak mengambil sumber apa pun, karena entitas tidak memiliki sumber, memiliki sumber lokal, atau memiliki sumber yang koordinatnya diisi oleh setiap Release, panggilan dijawab seperti di tempat lain. Build di sana yang tidak me-resolve apa pun terlebih dahulu tetap melakukan render, tetapi input eksternal yang disematkan lockfile-nya dan tidak lagi disimpan cache tidak diambil ulang: proses render diberi tahu kalimat yang sama itu sebagai pengganti input tersebut, sebagaimana ia diberi tahu kalimat untuk mode offline. Tidak ada jawaban melalui HTTP yang membawa kalimat tersebut: listener selalu melayani workspace yang diberikan kepadanya atau yang ditemukannya. Demikian pula peluncuran bundle desktop dengan pengaturan Workspace folder kosong, yang menolak panggilan yang tidak menyebutkan workspace miliknya sendiri alih-alih menjawabnya di folder tempatnya dimulai.
Panggilan tentang sebuah Release atau dokumen yang disebutkannya dengan path absolut dijawab di workspace milik file tersebut bila tidak ada hal lain yang menetapkannya. Bila peluncuran tidak menyebutkan root, panggilan tidak mengirim workspace_root, dan direktori tempat server dimulai tidak menjangkarkan workspace apa pun, workspace ditemukan kembali dari folder tempat file tersebut berada, dan apa pun yang ditemukan — proyek tempat file tersebut berada, atau, bila semua gagal, folder itu — adalah workspace tempat panggilan dijawab. Itulah aturan yang diikuti perintah yang diketik di terminal, sehingga aturan ini berlaku untuk setiap alat yang panggilannya menyangkut Release atau dokumen entitas yang disebutkannya: build, pull, validasi, lint, deskripsi, daftar dalam istilah sebuah Release, pertanyaan tentang simpul graf sebuah Release, pin, publikasi sebuah entitas, suntingan, dan posisi yang dibaca dalam dokumen. Bila sebuah panggilan menyebutkan Release sekaligus dokumen, Release yang menentukan. Jadi bagi klien yang meluncurkan server di luar proyek Anda, sebuah Release di dalam proyek tersebut tetap dibangun dari konfigurasi milik proyek itu sendiri. Path lain yang disebutkan panggilan dibaca seperti biasa — path relatif dari direktori tempat server dimulai — dan alat yang menjalankan perintah dalam proses terpisah dijawab dari workspace yang sama, karena perintah mengikuti aturan yang sama di direktori yang sama. Root yang disebutkan peluncuran, workspace_root yang dikirim panggilan, direktori awal yang berada di dalam sebuah workspace, dan Release atau dokumen yang disebutkan dengan path relatif digunakan apa adanya. Melalui HTTP, tidak satu pun dari hal ini terjadi: listener selalu melayani workspace yang diberikan kepadanya atau yang ditemukannya, dan setiap path yang disebutkan panggilan bersifat relatif terhadapnya. Demikian pula pada peluncuran bundle desktop dengan pengaturan Workspace folder kosong, yang menolak panggilan yang tidak menyebutkan workspace miliknya sendiri, file apa pun yang disebutkannya.
Mempersempit apa yang diumumkan server
mcp.announce_tools menyebutkan tool yang diumumkan server ini, dieja persis seperti yang dilaporkan daftar tool. Jika kunci ini dihilangkan, setiap tool yang dibawa server ini diumumkan, yang merupakan default dan bentuk yang diharapkan klien yang mengikuti protokol. Jika sebuah daftar ditulis, tepat tool-tool itulah yang diumumkan: tool yang tidak dicantumkan tidak ada dalam daftar tool, tidak ada dalam jawaban describe-capabilities, dan ditolak jika tetap dipanggil dengan namanya, dengan penolakan yang menyebutkan pengaturan ini. Jika daftar kosong ditulis, tidak ada yang diumumkan sama sekali — jadi menghilangkan kunci dan menulis [] adalah dua pernyataan yang berbeda, dan pengaturan ini tidak memiliki default yang diisikan untuk Anda.
Tetapkan pengaturan ini ketika klien di ujung lain membatasi berapa banyak tool yang akan didaftarkannya, terkadang di seluruh server yang terhubung dengannya sekaligus, dan sebutkan tool yang dibutuhkan klien tersebut. Batas itulah kasus yang menjadi alasan pengaturan ini ada, dan klien yang dikenainya biasanya adalah klien yang meluncurkan server ini melalui standard input dan output miliknya sendiri — jadi, berbeda dengan bagian lain dari blok mcp, yang mengonfigurasi listener yang dijalankan oleh transport http, kunci ini dibaca apa pun transport yang digunakan server.
Pengaturan ini mempersempit apa yang diumumkan dan tidak lebih. Menyebutkan sebuah tool di sini tidak memperluas apa pun. Pengaturan ini tidak mencabut mcp.deny_reach, yang menarik sebuah kapabilitas sepenuhnya, sehingga tool yang disebutkan di sini dengan jenis yang ditarik oleh pengaturan itu tetap tidak ada dalam daftar dan ditolak dengan menyebutkan pengaturan itu. Pengaturan ini juga tidak mencabut scope yang dibawa token pemanggil: tool yang disebutkan di sini tetap dicantumkan apa pun scope tersebut, dan panggilan yang tidak diizinkan oleh scope itu tetap ditolak, dengan menyebutkan scope yang akan mengizinkannya. Dalam kedua kasus, penolakan yang diterima pemanggil berasal dari batas lain itu, bukan dari batas ini. Penolakan dari pengaturan ini tidak membawa challenge dan tidak menyebutkan scope, karena tidak ada kredensial yang mengubah apa yang telah dipilih server untuk ditawarkan — yang disebutkannya adalah pengaturan tersebut, satu-satunya hal yang dapat ditindaklanjuti oleh siapa pun yang membaca penolakan itu.
Setiap nama harus merupakan nama yang dibawa biner ini. Nama yang tidak dijawab oleh tool mana pun menghentikan server sebelum melayani apa pun, dan penolakannya mencantumkan tool yang dimilikinya — sehingga salah ketik terdeteksi saat startup, bukan melalui permukaan yang diam-diam lebih sempit daripada yang Anda minta. Nama dalam keluarga cli-, yang menjalankan perintah aggrega dalam proses terpisah, diterima di kedua transport dan tidak mengumumkan apa pun melalui HTTP, tempat tool seperti itu memang tidak ditawarkan kepada pemanggil mana pun.
Himpunan yang diumumkan ditetapkan saat proses dimulai, sehingga mengubahnya memerlukan restart dan tidak ada yang menambah daftar di bawah klien yang sudah terhubung.
Dari rilis mana server berasal
describe-capabilities yang dikirim tanpa argumen menyatakan dari rilis mana server ini berasal. Jawaban terstrukturnya membawa server_version, versi yang dilaporkan executable aggrega untuk dirinya sendiri — versi yang dicetak aggrega version untuk file yang sama — dan teksnya dibuka dengan satu baris yang menyebutkannya, sebelum indeks. Jawaban terstruktur membawa baris yang sama itu sebagai version_summary, kata demi kata, sehingga klien yang hanya menyerahkan jawaban terstruktur kepada model juga menyerahkan baris tersebut.
Jika bundle desktop yang meluncurkan server, jawaban yang sama menyebutkan versi bundle di sampingnya. Bundle tidak membawa program apa pun: bundle meluncurkan executable aggrega mana pun yang disebutkan oleh pengaturan Path to the aggrega executable miliknya — secara default nama perintah aggrega, yang dicari aplikasi di PATH miliknya — sehingga bundle dan executable dipasang secara terpisah dan dapat berasal dari rilis yang berbeda, dan aplikasi yang mencantumkan bundle hanya menampilkan versi bundle itu sendiri. Bundle menyerahkan versinya kepada server sebagai AGGREGA_BUNDLE_VERSION dalam lingkungannya; server membacanya sekali, saat dimulai, dan jawaban membawanya sebagai bundle_version. Keduanya dibandingkan persis seperti yang tertulis, yang merupakan perbandingan yang adil karena bundle dan executable dari satu rilis dicap dengan versi rilis tersebut dalam bentuk yang sama, sedangkan build pengembangan terbaca berbeda dari setiap rilis. Jika keduanya sama, baris tersebut menyebutkan keduanya dan tidak mengatakan apa-apa lagi. Jika berbeda, baris tersebut menyatakan, dengan menyebutkan keduanya, bahwa executable dan bundle berasal dari rilis yang berbeda, dan panduan yang diberikan server kepada model saat terhubung dibuka dengan kalimat yang sama, sehingga perbedaan itu sudah ada di hadapan model sebelum ia bertanya.
Server yang tidak diluncurkan oleh bundle hanya melaporkan versinya sendiri. Jika dijalankan dari terminal, dari konfigurasi editor, atau sebagai listener, server tidak membawa bundle_version, kecuali ada sesuatu yang menetapkan variabel tersebut dalam lingkungannya. Server melalui standard input dan output yang membawa variabel tersebut dianggap diluncurkan oleh bundle dalam satu hal lagi: jika tidak diberi root, server menolak pengaturan Workspace folder yang kosong, seperti yang dijelaskan dalam Di workspace mana sebuah panggilan dijawab. Panggilan describe-capabilities yang dikirim dengan kind atau tools tidak membawa server_version, bundle_version, atau version_summary, dan tidak membawa baris tersebut, karena panggilan itu menjawab tentang tool, bukan tentang server.
Perbedaan dilaporkan dan tidak pernah ditolak. Server dimulai dan menjawab setiap panggilan persis seperti jika keduanya selaras. Apa arti perbedaan bagi instalasi desktop, dan cara menyelaraskan keduanya, dijelaskan di Menghubungkan server MCP.
Menjangkau server melalui HTTPS
aggrega mcp --transport http melayani protokol melalui HTTP, bukan melalui standard input dan output. mcp.transport dalam konfigurasi workspace adalah kunci yang ditimpa oleh flag tersebut, dan default-nya, stdio, adalah yang diharapkan klien yang menjalankan perintah tersebut — sehingga server yang dijangkau orang lain membawa transport: http dalam konfigurasinya, dan klien yang diluncurkan dari direktori yang tercakup konfigurasi itu tetap menjangkau server melalui stream miliknya sendiri. Server itu sama dalam kedua cara — workspace yang sama dan permukaan protokol yang sama — dan yang berubah adalah bagaimana sebuah pesan sampai kepadanya, bagaimana sebuah panggilan berakhir, dan apa yang harus dimiliki oleh siapa pun yang menjalankannya. Bagian ini menjelaskan apa yang dikonfigurasi operator; entri yang dibutuhkan klien untuk menjangkau server yang sedang berjalan ada di Menghubungkan server MCP.
Alamat tidak memilih transport. --listen <address>, atau mcp.listen jika flag tidak ada, menyebutkan tempat listener melakukan bind setelah http dipilih, dan tidak lebih. Jadi http tanpa alamat dari salah satunya ditolak sebelum apa pun di-bind, dan penolakannya menyebutkan keduanya. --listen yang diketik saat transport adalah stdio — diketik sebagai --transport stdio, dikonfigurasi sebagai mcp.transport: stdio, atau dibiarkan sebagai default — juga ditolak, dengan menyebutkan --transport http sebagai flag yang akan melayani pada alamat tersebut; --listen yang diberi nilai kosong ditolak karena tidak menyebutkan alamat, apa pun transport-nya. Dan alamat yang hanya disebutkan oleh konfigurasi dibiarkan tidak terpakai oleh server yang berkomunikasi melalui stream miliknya sendiri, yang menyatakannya dalam satu baris di stream error-nya, dengan menyebutkan file yang menetapkannya dan mcp.transport: http. Kasus terakhir itu sengaja tidak ditolak di mana pun: itulah peluncuran yang dilakukan klien saat menjalankan perintah di direktori yang konfigurasinya membawa pengaturan listener, dan konfigurasi listener yang lupa transport: http sama sekali tidak menjalankan listener, dan di situlah hal itu terlihat.
Server yang dijangkau melalui HTTP tidak menawarkan tool yang menjalankan perintah aggrega dalam proses terpisah. Tool tersebut hanya ada untuk klien yang meluncurkan server ini melalui standard input dan output miliknya, di mesin milik klien itu sendiri, tempat menyebutkan folder atau flag tidak memberi pemanggil apa pun yang belum dimilikinya. Pemanggil yang menjangkau server melalui HTTP tidak memiliki host tempat server berjalan, sehingga perintah yang akan bertindak atas filesystem host tersebut dengan otoritas server itu sendiri dijalankan dari terminal di host tersebut. Tool tersebut tidak ada dalam daftar dan dalam describe-capabilities, alih-alih ditawarkan lalu ditolak, dan panggilan yang menyebutkan salah satunya dijawab dengan error yang menyatakan hal itu. Itu adalah sifat transport, bukan pengaturan: tidak ada konfigurasi yang mengembalikannya.
Baca Tidak ada yang dilayani tanpa kredensial sebelum Anda men-deploy server seperti ini. Setiap permintaan ke endpoint membawa kredensial, dan tidak ada pengaturan yang melayani permintaan tanpa kredensial — yang dipilih oleh pengaturan adalah apakah server ini memeriksa sendiri bearer token atau membaca pemanggil yang sudah diperiksa oleh proxy di depannya.
Dua bentuk deployment
Proses menghentikan TLS sendiri. Tetapkan mcp.tls.cert_file ke rantai sertifikat PEM dan mcp.tls.key_file ke kunci privatnya, dan listener melayani HTTPS langsung pada alamat apa pun yang Anda berikan. Kedua file dibaca saat proses dimulai, sehingga sertifikat yang diganti diterapkan dengan me-restart proses. Menetapkan salah satu tanpa yang lain ditolak saat startup alih-alih beralih ke hal lain: sertifikat tanpa kunci tidak dapat disajikan, kunci tanpa sertifikat tidak menyebutkan apa pun, dan salah ketik pada satu path bukan alasan untuk mulai melayani lalu lintas tanpa enkripsi.
Proxy di depan menghentikan TLS dan meneruskan ke listener yang dibatasi. Biarkan kedua kunci tidak ditetapkan dan listener melayani plaintext, yang hanya diterima pada loopback atau pada socket Unix — sehingga tidak ada yang belum berada di host tersebut yang dapat menjangkaunya. Itulah bentuk yang digunakan reverse proxy, sidecar, atau service mesh, dan itulah bentuk di mana sertifikat berada di depan proses ini, bukan di dalamnya.
Listener plaintext pada alamat lain mana pun ditolak sebelum apa pun di-bind, dan penolakannya menyebutkan kedua kunci TLS. Tidak ada pengaturan yang mencabut ini dan tidak ada alamat yang menjadi pengecualian: listener yang menerima koneksi dari jaringan tanpa sertifikatnya sendiri tidak pernah aman, sehingga proses menolak untuk dimulai alih-alih dimulai dalam bentuk itu.
Bentuk-bentuk alamat
--listen dan mcp.listen menerima salah satu dari dua bentuk:
host:port— alamat TCP, seperti127.0.0.1:7777atau0.0.0.0:8443. Loopback berarti127.0.0.1,::1, ataulocalhostjika setiap alamat yang menjadi hasil resolusi nama itu adalah alamat loopback. Selain itu adalah alamat jaringan dan memerlukan sertifikat: host kosong, yaitu setiap antarmuka yang dimiliki mesin; alamat antarmuka tertentu; dan nama lain apa pun, bahkan nama yang saat ini di-resolve ke alamat loopback, karena tempat listener boleh melakukan bind tidak seharusnya bergantung pada resolusi yang dapat berubah di bawahnya.unix:diikuti path filesystem — socket domain Unix, sepertiunix:/run/aggrega/mcp.sock. Socket hanya dapat dijangkau dari host tempatnya berada, sehingga tidak memerlukan sertifikat.
Path socket diambil persis seperti yang tertulis, termasuk path relatif. Path ini sengaja tidak di-resolve terhadap file konfigurasi yang mendeklarasikannya, karena alamat yang sama juga datang dari --listen, yang tidak memiliki file yang mendeklarasikan — lihat ke mana path relatif menunjuk.
Apa yang diterima listener
Satu endpoint, /mcp, yang menerima POST. Setiap pesan JSON-RPC adalah permintaan tersendiri dan tidak ada sesi jenis apa pun yang disimpan: tidak ada yang dikirim klien lebih dulu yang menentukan bagaimana permintaan berikutnya dijawab, tidak ada pengidentifikasi sesi yang pernah dibuat, dan header sesi atau header pelanjutan stream yang dikirim klien diabaikan. Metode lain apa pun pada endpoint itu dijawab 405 dengan Allow: POST, dan path lain apa pun 404 — keduanya diputuskan sebelum pemeriksaan kredensial, sehingga upaya probing tidak mempelajari apa pun dari challenge pada path atau metode yang toh tidak akan melayani apa pun.
Permintaan dijawab dengan satu objek JSON dan satu kode status — atau, jika panggilan melaporkan kemajuan dalam perjalanannya menuju objek itu, dengan stream event yang berakhir dengan objek tersebut, seperti yang dijelaskan dalam Diberi tahu bagaimana kemajuan panggilan yang panjang. Notifikasi — pesan yang tidak membawa id — dijawab 202 dengan body kosong. Pesan yang bukan keduanya, termasuk respons JSON-RPC, dijawab 400, karena klien mengirim permintaan dan notifikasi kepada server ini dan tidak ada yang lain.
Kedua revisi protokol dilayani di sini persis seperti melalui standard input dan output. Permintaan 2026-07-28 mencerminkan body-nya dalam header transport sehingga perantara dapat merutekannya tanpa mem-parsing body: MCP-Protocol-Version membawa revisi yang dinyatakan body, Mcp-Method metode yang disebutkannya, dan Mcp-Name targetnya, untuk metode yang menyasar target berdasarkan nama. Header yang tidak sesuai dengan body dijawab 400. Klien 2025-06-18 membuka dengan handshake initialize, yang dijawab secara stateless; klien dapat membawa header versi yang menyebutkan revisi itu atau menghilangkannya. Permintaan yang menyebutkan revisi yang tidak digunakan server dijawab 400 dengan mencantumkan dua revisi yang digunakannya, dan permintaan yang menyebutkan metode yang tidak dilayaninya dijawab 404.
mcp.allowed_origins hanya dirujuk jika permintaan membawa header Origin, yang dalam praktiknya berarti browser yang mengirimnya: permintaan yang menyebutkan origin yang tidak ada dalam daftar dijawab 403, dan permintaan yang tidak membawa header tersebut dilayani. Klien yang bukan browser tidak mengirim header tersebut dan tidak memerlukan entri. Klien berbasis browser selalu memerlukan entri: daftar ini kosong sampai operator menuliskannya, sehingga sampai saat itu tidak ada origin sama sekali dan setiap permintaan browser dijawab 403 — termasuk permintaan dari halaman yang dilayani di alamat endpoint itu sendiri. Entri dibandingkan persis dengan header, sehingga entri ditulis seperti browser mengirim origin — skema huruf kecil, ://, host huruf kecil dan, jika bukan default skema, : serta port, seperti https://app.example.com — dan entri dengan path, / di akhir, tanpa skema, atau dengan huruf kapital ditolak saat konfigurasi dimuat, dengan menyebutkan entri tersebut, karena entri itu tidak akan pernah cocok.
mcp.limits membatasi lalu lintas yang diterima. Body yang melebihi max_body_bytes dijawab 413 dan tidak dibaca melewati batas. Permintaan yang tiba saat max_concurrent_requests sudah sedang diproses dijawab 503 alih-alih diantrekan di belakang pekerjaan yang tidak dapat dilihatnya. Pemanggil yang mengirim lebih dari requests_per_minute dalam satu menit dijawab 429, yang dihitung hanya untuk pemanggil itu, sehingga satu pemanggil yang mengirim banyak tidak merugikan pemanggil lain. Default setiap batas dinyatakan di samping kuncinya dalam referensi konfigurasi, dan tidak ada satu pun yang memiliki nilai untuk menonaktifkannya.
Satu proses, satu workspace
Workspace yang dilayani oleh proses penyaji ditetapkan saat proses itu dimulai. --workspace-root menyebutkannya; variabel AGGREGA_WORKSPACE_ROOT menyediakannya jika flag tidak ada. Folder yang disebutkan adalah root workspace itu sendiri, tanpa pencarian di atasnya, dan folder yang tidak ada ditolak, dengan menyebutkan mana dari keduanya yang menyediakannya dan mengutip nilainya sebagaimana diberikan — oleh listener sebelum melakukan bind, dan oleh server melalui standard input dan output dalam jawabannya untuk setiap panggilan yang bertindak di workspace tersebut, seperti yang dijelaskan dalam Di workspace mana sebuah panggilan dijawab — sehingga peluncuran yang disusun oleh klien alih-alih diketik tetap menyatakan apa yang diserahkan kepadanya. Tanpa keduanya, server melalui standard input dan output me-resolve workspace dari direktori tempat ia dimulai — jika tidak ada yang menambatkan workspace di sana, setiap jawaban tentang workspace menyatakan folder mana yang digunakannya, dan peluncuran bundle desktop dengan pengaturan Workspace folder yang kosong justru menolak panggilan yang tidak menyebutkan workspace-nya sendiri, seperti yang dijelaskan dalam Di workspace mana sebuah panggilan dijawab — dan listener ditolak sebelum melakukan bind kecuali sebuah workspace ter-resolve di sana — proses yang dijangkau melalui HTTP menjawab pemanggil yang tidak dapat melihat mesinnya, sehingga ia melayani workspace yang dipilih operator, bukan direktori mana pun tempat ia kebetulan dimulai. Untuk melayani beberapa proyek, jalankan satu proses per root proyek.
Panggilan yang tiba melalui HTTP tidak dapat menyebutkan workspace-nya sendiri. workspace_root dan catalog_dirs ditolak, dengan menyebutkan argumen yang dikirim, alih-alih dibuang diam-diam: argumen yang diabaikan diam-diam terlihat bagi pengirimnya persis seperti argumen yang dipatuhi. Direktori katalog yang dicari di samping workspace yang dilayani adalah pengaturan workspace.catalog_dirs milik workspace itu sendiri — atau, untuk sebuah Release yang diberinya direktori sendiri di bawah workspace.releases, milik Release tersebut — yang ditulis operator. Melalui standard input dan output, kedua argumen dipatuhi, karena klien yang meluncurkan server berjalan di mesin milik pemanggil sendiri. Di sana entri catalog_dirs bersifat absolut, atau relatif terhadap root workspace tempat release relatif dibaca — root yang lebih dulu ditetapkan oleh workspace_root milik panggilan itu sendiri, oleh peluncuran, atau oleh direktori tempat server dimulai, dan root yang tetap menjadi tempat pembacaan ketika sebuah Release yang disebutkan secara absolut memindahkan panggilan ke workspace milik Release tersebut — dan bukan relatif terhadap direktori tempat server berjalan, jika direktori itu berada di tempat lain.
Path yang disebutkan sebuah panggilan juga tetap berada di dalam workspace tersebut. Melalui HTTP, argumen path di-resolve terhadap root workspace dan ditolak jika menjangkau ke luarnya — path relatif yang naik keluar dari workspace, path absolut yang menunjuk tempat lain, dan path relatif yang keluar dari workspace melalui link ke file atau direktori yang ada di sana, masing-masing kembali sebagai kegagalan yang menyebutkan argumen tersebut, tanpa menyebutkan root workspace maupun tempat yang akan dicapai path itu; path relatif dikutip kembali sebagaimana Anda mengirimnya. Setiap argumen path dinilai berdasarkan ke mana ia mengarah, menurut definisi “di dalam” yang dinyatakan Batas workspace, baik tool membacanya maupun menulisnya — direktori tempat gen-catalog menulis output-nya, dokumen yang ditulis kembali oleh edit-document, dan entitas yang di sampingnya pin menulis lock-nya sama halnya dengan dokumen yang dibaca tool — sehingga path yang belum dibuat di bawah link yang mengarah keluar dari workspace ditolak sebagaimana link itu ditolak, tanpa ada yang dibaca atau ditulis. release yang menyebutkan sebuah Release yang disebutkan oleh konfigurasi workspace yang dilayani, sebagai build.authoring_release atau sebagai kunci dari workspace.releases, dijangkau melalui konfigurasi tersebut dan diterima melalui link di mana pun file-nya berada; tidak ada argumen lain yang memiliki pengecualian itu. Jika path yang Anda maksud berada di dalam workspace tersebut tetapi dieja secara absolut, penolakan memberi Anda ejaan relatif-root untuk dikirim sebagai gantinya, sehingga pemanggil yang menebak bentuk yang salah diberi tahu bentuk yang benar, bukan hanya bahwa bentuknya salah. Hal itu berlaku untuk path yang disebutkan panggilan sebagai subjeknya — dokumen yang akan divalidasi, Release yang akan di-build, direktori tempat sebuah generasi menulis output-nya — dan untuk path yang ditulisi tool, tidak kurang dari path yang dibacanya: pemanggil yang menjangkau server melalui jaringan meminta mesin yang tidak dapat dilihatnya untuk membaca dan menulis file, dan workspace yang dipilih operator adalah tempat pembacaan dan penulisan itu dibatasi. Melalui standard input dan output, argumen path setiap tool mempertahankan kontrak yang dijelaskan di bawah tool tersebut di bagian berikut, di mana path boleh absolut dan boleh menunjuk ke luar workspace — orang yang memanggil memiliki mesin tempat server berjalan, sehingga membatasinya pada direktori yang ia pilih sendiri tidak akan menghasilkan apa pun. Dua tool yang operasinya sendiri hanya menjawab tentang dokumen yang dimuat workspace, insertion-point dan edit-document, mempertahankan hal itu di kedua transport, dan menolak dokumen di luar workspace, baik yang ditulis demikian maupun yang dijangkau melalui link yang mengarah keluar darinya. Yang dipatuhi melalui standard input dan output adalah path yang disebutkan panggilan dan tidak lebih dari itu. Apa yang kemudian dibaca dan ditulis operasi atas inisiatifnya sendiri dibatasi di kedua transport persis seperti saat perintah yang sama diketik di terminal: penelusuran atau pencarian tidak membaca melalui link yang mengarah keluar dari workspace, file yang disebutkan dengan path oleh sebuah Release di workspace atau Manifest-nya tidak dibaca dari luar workspace — dan file yang disebutkan oleh Release yang disebutkan panggilan di luar workspace tidak dibaca dari luar direktori yang memuat Release tersebut — dan file yang ditulis di bawah sebuah direktori — workspace, atau direktori yang disebutkan panggilan — tetap berada di dalam direktori itu. Batas workspace menempatkan kedua transport di samping command line dan editor, dan menyatakan apa yang tetap terbuka melalui standard input dan output: dokumen di workspace yang Anda kloning dapat mengarahkan asisten untuk menyebutkan path di luar workspace, dan path itu dipatuhi sebagaimana disebutkan.
Apa yang dikatakan jawaban tentang filesystem server
Melalui HTTP, jawaban menyebutkan sebuah tempat di filesystem server secara relatif terhadap root workspace, atau menahannya. Klien yang meluncurkan server berjalan di tempat server berjalan, sehingga melalui standard input dan output setiap jawaban menyebutkan setiap tempat sebagaimana operasi memegangnya — secara absolut, jika memang begitu cara memegangnya — dan masing-masing adalah tempat yang sudah dimiliki pemanggil tersebut. Pemanggil yang menjangkau listener tidak memilih satu pun dari tempat-tempat itu dan tidak dapat membukanya, dan server yang telah mengungkapkannya kepada pemanggil itu tidak dapat menariknya kembali. Jadi melalui HTTP, jawaban memberi tahu pemanggil tersebut salah satu dari dua hal tentang sebuah tempat:
- Tempat di dalam workspace disebutkan secara relatif terhadap root workspace — bentuk yang sama dengan path yang Anda kirim, sehingga nama yang dibaca dari satu jawaban dapat dikirim kembali tanpa perubahan dalam panggilan berikutnya. Release di root adalah
release.yaml, dan lockfile-nya adalahrelease.lock. - Tempat di luar workspace ditahan, begitu pula root workspace itu sendiri. Kolom tersebut tidak membawa nilai — nilainya
nullatau dihilangkan, dan padaattachment-container, yang jawabannya mempertahankan bentuk yang dilaporkan setiap permukaan,filedibiarkan kosong — dan sebuah penanda di sampingnya, yang dinamai sesuai kolom dengan tambahan_withheld, menyatakan bahwa kolom itu ditahan, bukan tidak ditetapkan:workspace_root_withhelddi sampingworkspace_root,file_withhelddi sampingfile. Penanda hanya ada jika ada sesuatu yang ditahan. Root ditahan karena listener melayani tepat satu workspace, sehingga lokasi workspace itu tidak menyebutkan apa pun yang Anda butuhkan untuk menyebutkan apa yang ada di dalamnya.
Apakah sebuah tempat berada di dalam dinilai dari cara penulisannya, bukan dari file yang dijangkaunya. Path yang ditulis melalui target symbolic link alih-alih melalui root tempat server dimulai, dan path yang keluar dari root lalu masuk kembali, masing-masing terbaca sebagai di luar workspace dan ditahan. Penilaian ini cenderung memberi tahu Anda lebih sedikit, tidak pernah cenderung menyebutkan tempat di luar workspace.
Melalui HTTP, teks yang dapat dibaca dalam jawaban mengikuti aturan yang sama. Jika teks, baris diagnostik, atau pesan kegagalan menyebutkan tempat yang dimuat workspace — root-nya atau apa pun di bawahnya, file config tempat konfigurasinya dibaca, direktori tempat katalognya dibaca — tempat itu ditulis secara relatif terhadap root, atau terbaca (location withheld) jika berada di luar workspace atau merupakan root. Teks yang disusun jawaban tentang workspace-nya sendiri menyebutnya workspace yang dilayani server ini. Tempat di luar semua itu yang ditulis operasi ke dalam pesan tidak dikenali sebagai tempat, dan sampai kepada Anda sebagaimana ditulis.
Jawaban yang dijangkau hal ini, melalui HTTP:
list-entities,list-releases,cache-status,registry-list,search,attach-candidates,connection-candidates,insertion-point,attachment-container,connection-at-position, danedit-documentmenahanworkspace_root. Path yang sudah mereka berikan secara relatif terhadap root — file sumber sebuah entitas, path sebuah Release dan lockfile-nya di bawahlockfiles, dokumen yang menjadi pokok titik penyisipan atau suntingan, file yang ditulis oleh suntingan — terbaca sama di kedua transport.cache-statusjuga menahan apa yang menyebutkan plugin yang dimuat server dari file di host-nya. Identitas seperti itu bernilainulldi tempatnya dalamprovenance[].identities, setiap identitas lain mempertahankan posisinya, dan entri tersebut ditandaiidentities_withheld.notesebuah modul terkompilasi adalah satu kalimat yang menyebutkan identitas yang menjadi tujuan modul itu di-build, sehingga jika salah satunya menyebutkan file seperti itu,notedihilangkan seluruhnya dan ditandainote_withheld;digestmodul tetap ada. Identitas yang menyebutkan referensi registry atau entitas Plugin dijawab utuh, begitu pulanoteyang hanya menyebutkan hal-hal tersebut.labelsebuah artefak sumber adalah tempatnya di cache, dieja dari host dan path URL tempat artefak itu di-resolve, sehingga untuk repositori yang dibaca dari filesystem milik server sendiri — melalui URLfile://atau path —labeldihilangkan dan ditandailabel_withheld,sizedandigest-nya tetap ada, danlabelyang menyebutkan host jaringan dijawab utuh. Teks daftar terbaca(location withheld)di tempat yang seharusnya menyebutkan salah satunya.validatemenyebutkantarget, danreleaseuntuk sebuah Release, secara relatif terhadap root; untuk seluruh katalog,targetadalah root dan ditahan. Tempat dalamdiagnosticsataunoticesmengikuti aturan untuk teks.buildmenyebutkanreleasesecara relatif terhadap root, dan build yang lebih dulu me-resolve dependensinya membawadependency_resolutionsebagaimanapullmenjawabnya. Build yang dikirim denganwritemenyebutkan direktori tempat ia menulis sebagaioutput_dir, yang terbacadist— relatif terhadap root — dan setiap path dalamfilesrelatif terhadap direktori itu. Sebuahrefusal, dan setiap entri darifindings-nya, menyebutkanfile-nya secara relatif terhadap root, atau menahannya jika dokumen berada di luar workspace.advisories,deprecations,declined_external_inputs, dan setiapmessagedarirefusalmengikuti aturan untuk teks.pullmenyebutkanreleasedanlockfilesecara relatif terhadap root.diagnosticsdanincomplete_external_inputsmengikuti aturan untuk teks.sourcesetiap entriresolveddijawab utuh di kedua transport: ia menyebutkan apa yang dilakukan eksekusi, tidak pernah sebuah tempat di host.describemenyebutkanreleasesebuah Release secara relatif terhadap root, danfilesebuah entitas secara relatif terhadap root jika dokumennya berada di dalam workspace; entitas yang dibaca dari direktori katalog di luar workspace memilikifileyang ditahan.mapping_diagnosticsdandeprecationsmengikuti aturan untuk teks.lintmenyebutkanlocation.filesetiap temuan secara relatif terhadap root, atau menahannya jika entitas berada di luar workspace.messagedansuggestsebuah temuan mengikuti aturan untuk teks.pinmenyebutkanentitydanlocksecara relatif terhadap root, begitu pulapinyang dibawa sebuah publikasi.gen-catalogmenyebutkan setiap file yang tercantum dalamoutputsecara relatif terhadap root.importmenahanworkspace_root, danoutput_dirjika draf masuk ke root tersebut; direktori yang Anda sebutkan dalamoutput_dirdiberitahukan dengan namanya yang relatif terhadap root. Setiap path draf dalamwrittendandraftsrelatif terhadapoutput_dir, sehingga ke mana draf itu masuk tetap ada dalam jawaban.messagesebuah diagnostik, sertaparams_summary,rationale, danswap_hintsebuah keputusan, adalah prosa yang disusun importer dan mengikuti aturan untuk teks.config-showdanplugin-listmenahan lebih dari root, karena sebagian besar yang mereka laporkan adalah konfigurasi yang menyebutkan tempat, seperti yang dijelaskan dalam Apa yang tidak diberitahukan listener kepada Anda tentang host-nya.scaffoldyang menulis contoh menyebutkandirsebagaimana Anda mengirimnya, relatif terhadap root, dan setiap path dalamfilesrelatif terhadap direktori tersebut; penyusunan draf dan pencantuman daftar tidak menyebutkan tempat apa pun.- Tool publikasi,
sign-artifacts,deprecate-artifact,get-schema,explain-error, dandescribe-capabilitiestidak menyebutkan tempat apa pun di host dengan sendirinya. Pesan kegagalan dari salah satunya mengikuti aturan untuk teks: penolakan yang dimunculkan workspace offline menyebutkan.aggrega-config.yaml-nya secara relatif terhadap root. - Argumen path yang ditolak karena menjangkau ke luar workspace ditolak tanpa menyebutkan root atau tempat yang akan dicapainya, seperti di atas.
Bagaimana sebuah panggilan berakhir
Menutup koneksi membatalkan panggilan yang dibawanya. Itulah sinyal pembatalan transport ini: server memperlakukan terputusnya pemanggil sebagai pembatalan permintaan itu, mengakhiri pekerjaan yang sedang dilakukannya, dan tidak menulis apa pun lagi untuknya. Di sini tidak diperlukan atau diharapkan pesan pembatalan — kebalikan dari standard input dan output, di mana tidak ada stream per permintaan untuk ditutup dan klien mengakhiri sebuah panggilan dengan menyebutkan id-nya. Pesan pembatalan yang tetap tiba melalui HTTP diterima dan tidak mengakhiri apa pun.
Menghentikan proses mengosongkan listener. Interupsi, atau permintaan terminasi dari supervisor atau runtime container, membuat listener berhenti menerima dan membiarkan panggilan yang sudah sedang dijawab selesai, dalam batas waktu tertentu, sehingga pemanggil yang meminta sesuatu sebelum penghentian tetap menerima jawabannya. Panggilan yang belum selesai dalam batas waktu itu kehilangan koneksinya. Permintaan penghentian kedua langsung mengakhiri proses.
Liveness dan readiness, di alamat tersendiri
mcp.health.listen adalah tempat supervisor menanyakan apakah proses ini aktif dan apakah ia dapat menjawab panggilan. Beri ia alamat dalam salah satu bentuk di atas, dan listener kedua menjawab GET /healthz dan GET /readyz di sana. Jika dihilangkan — yang merupakan default — tidak ada listener kedua yang dijalankan dan tidak satu pun dari kedua pemeriksaan itu dijawab di mana pun.
Kedua jawaban menyatakan hal yang berbeda, dan perbedaan itulah alasan adanya dua. /healthz dijawab 200 sejak saat proses berjalan, yang merupakan keseluruhan klaim liveness: proses aktif, dan supervisor yang sama sekali tidak mendapat jawaban sebaiknya me-restart-nya. /readyz dijawab 503 sampai workspace yang dilayani proses ini telah di-resolve dan endpoint telah melakukan bind, lalu 200 sejak saat itu — sehingga load balancer menahan lalu lintas sampai proses benar-benar dapat menjawab panggilan, alih-alih mengirim permintaan pertama ke proses yang masih dalam tahap mulai. Setiap jawaban adalah kode status dengan body kosong; tidak ada kredensial yang diminta, dan tidak ada yang dikirim pemanggil yang dibaca.
Endpoint tidak pernah menjawab kedua path tersebut. GET /healthz dan GET /readyz pada alamat yang disebutkan mcp.listen dijawab 404, persis seperti setiap path lain yang tidak dilayani endpoint itu, baik dengan token maupun tanpa token. Menjawab probe di sana akan memberi apa pun yang menjangkau endpoint itu pembacaan gratis tentang apakah proses aktif, bersama dengan cara gratis untuk membuatnya bekerja — pada listener yang selain itu menolak setiap permintaan yang tidak membawa kredensial.
Letak alamat health adalah pilihan Anda, dan alamat itu tidak dibatasi seperti mcp.listen. Tidak ada alamat yang ditolak untuknya. Arahkan ke loopback atau ke socket Unix, yang memang menjadi tujuannya: supervisor, load balancer, atau runtime container yang berjalan di samping proses ini di host yang sama. Apa pun yang dapat menjangkau alamat yang Anda pilih dapat membaca kedua jawaban itu, sehingga alamat yang dijangkau jaringan terbuka memublikasikannya ke jaringan terbuka.
Tidak ada yang dilayani tanpa kredensial
Setiap permintaan ke endpoint membawa kredensial, dan kredensial yang mana bergantung pada apakah proxy di depan sudah memeriksanya. Secara default, kredensial itu adalah bearer token yang diverifikasi sendiri oleh server ini, yang dijelaskan di sisa bagian ini. Tetapkan mcp.authorization.trusted_proxy, dan kredensial itu menjadi header yang ditetapkan proxy tersebut, yang dijelaskan di Membaca pemanggil dari proxy di depan — di mana tidak ada token yang dibaca sama sekali. Tidak satu pun dari kedua bentuk itu melayani permintaan yang tidak menyajikan apa pun.
Secara default, server memeriksa sendiri bearer token. Server membaca token dari header Authorization dan hanya menerimanya jika tanda tangannya terverifikasi terhadap kunci yang dipublikasikan server otorisasi, token menyebutkan mcp.authorization.issuer sebagai penerbitnya, token menyebutkan mcp.authorization.resource milik deployment ini di antara audiens-nya, token berada dalam jendela validitasnya, dan token menyatakan siapa yang menyajikannya. Token yang gagal dalam salah satu pemeriksaan itu dijawab 401, dengan error="invalid_token" ditambahkan ke challenge yang sama yang diterima pemanggil yang tidak membawa apa pun — dan jawabannya identik apa pun pemeriksaan yang menolaknya, sehingga pemanggil mengetahui bahwa ia memerlukan token yang berbeda, bukan bagian mana dari token yang dikirimnya yang salah. Hanya algoritme tanda tangan asimetris yang diterima: token yang tidak ditandatangani, dan token yang menyebutkan algoritme simetris, ditolak sebelum apa pun dibaca darinya.
Token dapat menyatakan jenis tokennya, dan empat bentuk diterima. JWT dapat membawa header typ yang menyebutkan jenisnya sendiri. Server ini menerima at+jwt dan application/at+jwt, dua ejaan yang terdaftar untuk access token; JWT, yang hanya menyatakan bahwa token itu adalah JWT; dan token yang sama sekali tidak mendeklarasikan jenis. Selain itu dijawab 401 persis seperti setiap token lain yang ditolak. Himpunan ini tetap dan tidak ada pengaturan yang memperluas atau mempersempitnya, karena bentuk mana yang muncul di sana ditentukan oleh server otorisasi yang menerbitkan token, bukan oleh deployment yang menerimanya. Menerima JWT memang berarti bahwa jenis yang dideklarasikan saja tidak lagi membedakan access token dari identity token — pemeriksaan audiens yang membedakan keduanya, dan itulah sebabnya pemeriksaan itu yang menjadi penopang: audiens identity token adalah klien yang menjadi tujuan penerbitannya, tidak pernah mcp.authorization.resource milik deployment ini, sehingga token yang diterbitkan untuk apa pun selain deployment ini ditolak apa pun sebutan yang dipakainya untuk dirinya sendiri.
Server otorisasi mana yang diizinkan oleh hal itu. Microsoft Entra ID menerbitkan access token berjenis JWT. Keycloak menerbitkan at+jwt, dan JWT jika mode kompatibilitas OpenID Connect-nya aktif. Auth0 menerbitkan JWT di bawah profil tokennya sendiri dan at+jwt di bawah profil RFC 9068-nya. Token dari salah satu server tersebut lolos pemeriksaan ini, bentuk mana pun dari keduanya yang dibawanya. Okta tidak didukung: access token-nya mendeklarasikan jenisnya sendiri yang bukan salah satu dari empat bentuk di atas, sehingga server ini menolaknya.
Token yang ditolak meninggalkan alasannya di stream error milik server sendiri. Pemanggil hanya diberi tahu bahwa apa yang disajikannya tidak diterima; proses penyaji menulis satu baris yang menyebutkan pemeriksaan yang menolak token tersebut — audiens, penerbit, jendela validitas, tanda tangan, pengidentifikasi kunci, jenis yang dideklarasikan, dan masing-masing pemeriksaan lainnya. Baris itulah yang membuat deployment yang menolak setiap permintaan dapat didiagnosis oleh siapa pun yang menjalankannya, bukan hanya oleh siapa pun yang memanggilnya. Baris itu tidak memuat bagian apa pun dari token. Permintaan yang sama sekali tidak menyajikan kredensial tidak menulis baris apa pun, karena menerima challenge adalah cara klien mengetahui sejak awal di mana memperoleh token, sehingga itulah hal pertama yang dilakukan setiap klien yang berperilaku baik.
Token tempatnya di header dan tidak di tempat lain. Token yang dikirim sebagai parameter query access_token dijawab 400 dan tidak pernah dibaca, karena sebuah alamat direkam oleh setiap log proxy, riwayat browser, dan header referrer yang dilewati permintaan, sehingga token yang tiba dengan cara itu sudah terekspos. Server tidak pernah menulis token ke log, tidak pernah mengirimkannya ke mana pun, dan tidak pernah memperoleh atau menukarkannya atas nama pemanggil: server membaca apa yang disajikan, memutuskan, dan tidak menyimpan apa pun darinya. Subjek yang disebutkan token dicatat dan tidak dibandingkan dengan apa pun.
Kunci verifikasi berasal dari server otorisasi, atau dari file yang Anda sebutkan. Jika mcp.authorization.jwks_file tidak ditetapkan, server membaca metadata server otorisasi di alamat well-known-nya, mengikuti jwks_uri yang dipublikasikan di sana, dan menyimpan kunci yang ditemukannya; token yang ditandatangani dengan pengidentifikasi kunci yang tidak dimuat kunci-kunci itu memicu satu kali pembacaan ulang, dan tidak lebih dari satu dalam interval singkat, sehingga pemanggil yang mengirim pengidentifikasi kunci rekaan tidak dapat memicu satu permintaan keluar per permintaan. Membacanya dari server otorisasi memerlukan alamat kunci https, atau alamat http biasa di mesin ini: jwks_uri yang berupa http biasa di host lain tidak pernah ditanyai, dan redirect yang akan mengirim salah satu pembacaan ke http biasa di host lain tidak diikuti, karena siapa pun yang berada di jalur tak terlindungi menuju kunci dapat menjawab dengan kunci miliknya sendiri. Token yang memerlukan kunci tersebut kemudian dijawab 503, persis seperti untuk kunci yang tidak dapat dibaca, dan baris yang ditulis server untuk permintaan itu menyatakan bahwa pembacaan ditolak karena http biasa, bukan bahwa server otorisasi tidak dapat dijangkau — perbaikannya ada di pihak server otorisasi, yang harus memublikasikan metadata dan kuncinya melalui https. Jika jwks_file ditetapkan, kunci dibaca dari file tersebut dan server otorisasi tidak pernah dihubungi — itulah yang dibutuhkan workspace yang mendeklarasikan offline: true, dan workspace seperti itu ditolak sebelum listener-nya melakukan bind kecuali file tersebut disebutkan. Jika kunci sama sekali tidak dapat dibaca, permintaan dijawab 503 tanpa challenge: tidak ada yang disajikan pemanggil yang dinilai kurang, sehingga mengirimnya lagi dengan token lain tidak akan membantu.
Satu-satunya jawaban yang diberikan tanpa meminta kredensial adalah dokumen metadata sumber daya terlindungi. Klien harus membacanya sebelum dapat memegang token, sehingga mewajibkan token di sana akan menutup satu-satunya pintu masuk. Dokumen ini dijawab di /.well-known/oauth-protected-resource, dan — jika alamat yang disebut oleh mcp.authorization.resource memiliki path sendiri — juga di path well-known tersebut dengan path itu ditambahkan di belakangnya. Itulah dua tempat yang diperiksa klien, dan bentuk dengan path yang ditambahkan adalah alamat yang disebut oleh challenge. Dokumen ini memuat alamat tersebut sebagai sumber daya yang menjadi nama deployment ini, mcp.authorization.issuer sebagai server otorisasi tempat memperoleh token, header sebagai satu-satunya cara menyajikan token, dan tiga nama scope di bawah.
Issuer adalah alamat https, kecuali server otorisasi berjalan di mesin ini. http biasa diterima untuk issuer di localhost, 127.0.0.1, atau ::1, yang merupakan bentuk pengujian lokal dengan server otorisasi lokal; issuer http biasa di host lain mana pun ditolak sebelum listener melakukan bind, dan penolakannya menyebut mcp.authorization.issuer serta meminta alamat https. Hal ini berlaku di setiap mode — dengan kunci yang dibaca dari issuer, dengan mcp.authorization.jwks_file, dan dengan proxy di depan — karena setiap mode memublikasikan issuer dalam dokumen ini: klien yang mengikutinya menjalankan alur otorisasinya terhadap alamat tersebut, sehingga melalui http biasa kode otorisasi dan token yang diperolehnya akan melintasi jaringan tanpa perlindungan, baik server ini pernah membaca kunci dari sana maupun tidak. Jika server ini memang membaca kuncinya dari sana, siapa pun yang berada di jalur itu juga dapat menjawab dengan kunci miliknya sendiri, dan setiap token yang ditandatangani dengannya akan diterima.
Nama scope yang dipublikasikan deployment ini adalah aggrega:read, aggrega:workspace-write, dan aggrega:registry-write. Itulah nama yang harus didaftarkan di server otorisasi dan nama yang diminta klien darinya, dan challenge yang diterima pemanggil yang ditolak menyebut aggrega:read sebagai yang harus diperoleh lebih dulu. Apa yang diizinkan masing-masing — dan batas kedua, yang ditetapkan deployment ini pada dirinya sendiri — dijelaskan di Apa yang dapat dijangkau pemanggil di bawah.
Membaca pemanggil dari proxy di depan
Jika proxy di depan sudah memvalidasi token, mcp.authorization.trusted_proxy memberi tahu server ini untuk membaca pemanggil darinya alih-alih memeriksa token untuk kedua kalinya. Berikan principal_header, header yang ditetapkan proxy tersebut untuk menyatakan siapa pemanggilnya, dan secara opsional scopes_header, header kedua yang memuat scope pemanggil tersebut dipisahkan spasi. Masing-masing adalah nama header HTTP seperti X-Forwarded-User, tanpa spasi atau titik dua; nama dalam bentuk lain apa pun ditolak saat konfigurasi dimuat, dengan menyebut kuncinya, begitu pula principal_header yang kosong — hilangkan blok tersebut agar mode ini tetap nonaktif. Kedua header itu adalah satu-satunya yang dibaca: tidak ada header alamat yang diteruskan maupun header lain yang ikut berperan. Permintaan yang tiba tanpa header principal dijawab 401, dan dalam mode ini sama sekali tidak ada token yang dibaca — permintaan yang membawa token yang sebenarnya akan ditolak server ini tetap dilayani jika header principal-nya ada, dan permintaan yang membawa token yang akan diterima server ini tetap ditolak jika header tersebut tidak ada.
Mode itu hanya diterima pada loopback atau socket Unix, dan proses ditolak sebelum melakukan bind di tempat lain. Sebuah header dapat dipercaya tepat ketika tidak ada yang selain proxy dapat menetapkannya. Pada alamat yang dapat dijangkau jaringan, apa saja dapat menetapkannya — sehingga listener dalam mode ini pada alamat semacam itu akan membiarkan setiap pemanggil menamai dirinya sesuka hati. Penolakannya menyebut kedua pengaturan yang bertentangan, sehingga Anda dapat mencabutnya dengan memindahkan alamat atau menghapus blok tersebut.
Apa yang dinyatakan proxy adalah apa yang dipercaya server ini, dan itulah kesepakatannya. Dalam mode ini server ini tidak memeriksa tanda tangan apa pun dan tidak membandingkan pemanggil yang dinyatakan dengan apa pun, persis seperti ia tidak membandingkan subject token dengan apa pun. Apakah proxy memvalidasi apa yang diteruskannya, dan apakah ada sesuatu yang dapat menjangkau listener tersebut tanpa melewati proxy, adalah tanggung jawab deployment untuk dilakukan dengan benar; pembatasan di atas adalah hal yang memungkinkan semua itu dilakukan dengan benar, bukan jaminan bahwa semuanya sudah benar.
Menetapkan mcp.authorization.trusted_proxy tidak menghapus persyaratan lainnya. issuer dan resource tetap diperlukan, karena dokumen metadata tetap dipublikasikan dan challenge tetap menyebutnya — klien di belakang proxy tetap harus mengetahui tempat memperoleh token yang akan diperiksa proxy. Dengan alasan yang sama, issuer tetap merupakan alamat https kecuali berjalan di mesin ini: klien tersebut memperoleh tokennya dari issuer, sehingga issuer http biasa di host lain ditolak sebelum listener melakukan bind dalam mode ini persis seperti dalam mode lainnya, meskipun server ini tidak membaca apa pun darinya.
Apa yang dapat dijangkau pemanggil
Dua batas menentukan apa yang dijangkau pemanggil melalui HTTP, dan keduanya ditetapkan oleh orang yang berbeda. Kredensial milik pemanggil sendiri adalah yang pertama; apa yang ditawarkan server ini sama sekali adalah yang kedua. Keduanya dibaca sebelum apa pun dijalankan, dari deklarasi yang dibuat setiap operasi tentang dirinya sendiri, dan keduanya sampai ke klien di tempat yang berbeda: daftar tool menunjukkan apa yang ditawarkan dan diumumkan server ini, dan jawaban yang diterima setiap panggilan menunjukkan apa yang diizinkan kredensial.
Setiap operasi mendeklarasikan seberapa jauh efeknya sendiri menjangkau, dan ada empat jenis, yang terluas paling akhir:
- Tidak menjangkau apa pun — membaca definisi, memeriksa apa yang dipin oleh sebuah Release, merender artefak di memori, dan mengembalikannya. Operasi ini tidak meninggalkan apa pun: tidak ada yang ditulis, dan jawabannya adalah keseluruhan yang dihasilkannya.
- Menjangkau workspace — menulis di dalam workspace yang dilayani proses ini: lockfile sebuah Release, cache artefak, entitas yang dihasilkan, dokumen yang diedit.
- Menjangkau registry — memublikasikan, menandatangani, atau melampirkan penanda penarikan pada sesuatu yang sudah dipublikasikan. Yang diubahnya adalah apa yang di-resolve oleh setiap konsumen registry tersebut, dan tidak satu pun darinya dapat ditarik kembali dari siapa pun yang sudah mengambilnya.
- Menjangkau mesin — mengubah apa yang dipakai bersama oleh setiap workspace di host, di antaranya penyimpanan modul terkompilasi, file konfigurasi yang sama bagi semuanya, dan penyimpanan kredensial. Cache yang disimpan satu proyek di bawah direktori cache-nya sendiri bukan jenis ini, dan
cache-statusmelaporkan jenis mana dari jenis-jenis ini yang dimiliki setiap cache yang dicantumkannya.
Jenis adalah properti operasi, bukan properti tool yang menawarkannya, dan jenis mencakup apa yang ditinggalkan operasi — bukan tempat sebuah antarmuka meletakkan jawaban yang dikembalikannya. Merender sebuah Release menghasilkan artefak sebagai jawabannya, sehingga tidak menjangkau apa pun; baris perintah yang kemudian menyimpan artefak tersebut ke direktori yang Anda sebutkan sedang menyerahkan jawaban itu, bukan menjangkau lebih jauh. Jika dibaca sebaliknya, setiap operasi yang menjawab dengan konten akan mengambil jenis antarmuka mana pun yang kebetulan menyimpannya, dan jenis sama sekali tidak lagi menjadi properti operasi. Dengan alasan yang sama, describe yang membaca entitas melalui referensi registry-nya tidak menjangkau apa pun: ia menghubungi registry tersebut untuk mengambil jawabannya dan tidak meninggalkan apa pun, baik di registry maupun di mesin ini, dan registry mana yang boleh dihubunginya dijelaskan di Kredensial mana yang digunakan sebuah panggilan. Satu panggilan tetap dapat menjangkau lebih jauh daripada jenis operasinya, jika panggilan itu sendiri meminta penulisan: build yang dikirim dengan write menyimpan artefaknya di workspace yang dilayani server ini, sehingga panggilan tersebut menjangkau workspace, sebagaimana build yang lebih dulu me-resolve dependensinya.
Sebuah scope mengizinkan satu jenis, dan setiap scope tulis mencakup scope baca. aggrega:read mengizinkan operasi yang tidak menjangkau apa pun. aggrega:workspace-write mengizinkan operasi yang menjangkau workspace, dan mencakup scope baca. aggrega:registry-write mengizinkan operasi yang menjangkau registry, dan juga mencakup scope baca. Jadi klien meminta kepada server otorisasinya scope tulis yang dibutuhkannya dan tidak perlu meminta scope baca juga.
Tidak ada scope yang mengizinkan jenis mesin, dan tidak ada pengaturan yang menambahkannya. Operasi jenis itu hanya ditawarkan oleh tool yang menjalankan perintah aggrega dalam proses terpisah, dan server yang dijangkau melalui HTTP sama sekali tidak menawarkan tool tersebut, dengan alasan yang diberikan di Menjangkau server melalui HTTPS di atas. Jalankan operasi tersebut di terminal pada host.
Daftar tool menampilkan setiap tool yang ditawarkan dan diumumkan server ini, apa pun scope yang dimiliki kredensial pemanggil, dan kredensial menentukan tool mana yang boleh dijalankan sebuah panggilan. describe-capabilities mengindeks dan mendefinisikan kumpulan yang sama. Panggilan yang tidak diizinkan kredensial dijawab 403 dengan error="insufficient_scope" pada challenge, yang menyebut satu-satunya scope yang akan mengizinkannya, dan tidak ada yang diminta panggilan tersebut yang telah dijalankan. Penolakan itulah yang dijawab oleh step-up protokol: klien yang mengimplementasikan step-up meminta Anda masuk lagi untuk scope yang disebut challenge. Daftar tersebut tidak berubah mengikuti kredensial, sehingga klien yang telah masuk lagi sudah memegang daftar yang benar. Kredensial yang tidak membawa satu pun dari ketiga scope menerima daftar tool yang sama dan tidak dapat memanggil satu pun tool di dalamnya, termasuk describe-capabilities.
Build adalah kasus yang perlu diketahui. Build tidak mengubah apa pun dengan sendirinya sehingga hanya membutuhkan aggrega:read, tetapi build yang menulis membutuhkan aggrega:workspace-write: build yang dikirim dengan write menyimpan artefaknya ke dist/ di root workspace, dan build yang lebih dulu me-resolve dependensinya menulis lockfile — baik panggilan memintanya dengan auto_pull maupun pengaturan auto_pull milik workspace sendiri yang melakukannya. Tool ini dicantumkan bagi pemanggil dengan scope baca sebagaimana setiap tool, dan build yang tetap berada di memori benar-benar tersedia baginya; yang ditolak, dengan menyebut aggrega:workspace-write, adalah panggilan yang menulis.
Klien yang tidak melakukan step-up tetap dapat diberi scope tulis, dan hal itu diatur di server otorisasi. Siapa pun yang menjalankan server otorisasi menjadikan scope tulis sebagai scope default untuk klien tersebut — scope yang dimasukkannya ke setiap token yang diterbitkannya untuk klien itu, baik klien memintanya maupun tidak — sehingga token yang diperoleh saat masuk pertama kali sudah membawanya. Klien yang mendaftarkan dirinya kembali ke server otorisasi setiap kali terhubung adalah klien baru di sana setiap kali, dan pengaturan yang dibuat pada pendaftaran sebelumnya tidak terbawa; untuk klien seperti itu, pengaturan yang berlaku adalah scope default yang diberikan server otorisasi kepada setiap klien yang didaftarkannya. Konsekuensinya, setiap proses masuk melalui klien tersebut kemudian membawa jangkauan tulis, baik pekerjaan yang sedang dilakukan membutuhkannya maupun tidak — dan jika default-nya adalah yang diberikan saat pendaftaran, setiap klien yang didaftarkan dengan cara itu juga membawa jangkauan tersebut. Jadikan default hanya scope tulis yang dibutuhkan pekerjaan itu: aggrega:workspace-write dan aggrega:registry-write mengizinkan jenis yang berbeda, dan tidak ada yang mencakup yang lain.
mcp.deny_reach adalah tempat siapa pun yang menjalankan server ini mencabut sebuah jenis darinya, dan ini adalah salah satu dari dua pengaturan yang memendekkan daftar tool. Cantumkan jenis — none, workspace, registry, machine — yang tidak ditawarkan server ini, dan setiap tool yang menjangkau salah satunya tidak ada di daftar tool setiap pemanggil maupun di describe-capabilities apa pun isi token pemanggil tersebut, dan ditolak jika tetap dipanggil, dengan galat yang menyebut pengaturan ini. Ini adalah batas milik server sendiri, bukan milik pemanggil, sehingga tidak ada kredensial yang mencabutnya dan penolakannya tidak membawa challenge: server yang dimaksudkan hanya untuk melayani pembacaan dan tidak ada yang lain mencantumkan workspace, registry, dan machine di sini, sehingga tidak dapat memublikasikan bahkan untuk pemanggil yang tokennya membawa ketiga scope. Hilangkan pengaturan ini, yang merupakan default, maka server ini tidak mencabut jenis apa pun, sehingga jenis mana yang dijangkau sebuah panggilan ditentukan oleh scope milik pemanggil sendiri. Menyebut machine diterima dan tidak mengubah apa pun, karena sejak awal tidak ada apa pun dari jenis itu yang ditawarkan di sini. Nilai yang bukan salah satu dari keempatnya ditolak saat konfigurasi dimuat, alih-alih dilewati — operator yang salah mengeja sebuah jenis telah meminta sebuah batas, dan dilayani diam-diam tanpa batas itu adalah cara yang salah untuk menjawabnya.
mcp.announce_tools adalah pengaturan lain yang memendekkan daftar tool, dan keduanya bukan batas yang sama. deny_reach mencabut sebuah kemampuan: operasi dari jenis yang disebut di sana sama sekali tidak ditawarkan di sini, kepada siapa pun. announce_tools hanya mencabut sebuah pengumuman: tool yang dikecualikannya adalah kemampuan yang masih dimiliki server ini, dan yang dijawabnya adalah batas yang ditetapkan klien sendiri atas berapa banyak tool yang akan didaftarkannya. Jika keduanya ditetapkan, pencabutan yang menang, sehingga tool dari jenis yang dicabut tetap tidak ada bagaimanapun announce_tools menyebutnya, dan penolakan yang dihadapi pemanggil menyebut pencabutan tersebut. Tidak ada yang memendekkan daftar yang membaca scope pemanggil: scope yang tidak dimiliki pemanggil menolak sebuah panggilan dan tidak pernah menghapus tool dari daftar. Mempersempit apa yang diumumkan server menjelaskan sisanya.
Kredensial mana yang digunakan sebuah panggilan
Penandatanganan keyless melalui listener mengambil identitasnya dari identity_token yang dibawa panggilan, dan bukan dari yang lain. Token yang dikirim dalam panggilan adalah kredensial yang dipegang pemanggil: ia harus memperolehnya, token itu terikat padanya, dan tanda tangan yang dibuatnya dapat diatribusikan kepadanya. Setiap tempat lain asal sebuah identitas dapat berasal adalah milik siapa pun yang memulai proses ini, sehingga pada transport ini proses resolusi diberi lingkungan yang tidak menjawab apa pun. AGGREGA_IDENTITY_TOKEN dan SIGSTORE_ID_TOKEN di lingkungan server tidak dibaca, dan endpoint OIDC ambien GitHub Actions tidak dijangkau. Semuanya berada di luar jangkauan, bukan sekadar tidak dianjurkan — tidak ada apa pun yang dapat ditemukan oleh resolusi. Panggilan yang tidak mengirim identity_token ditolak, dan penolakannya menyebut identity_token sebagai hal yang harus dikirim serta tidak menyebut variabel maupun endpoint apa pun: pemanggil yang tidak berada di depan papan ketik mesin ini tidak dapat mengekspor apa pun di sini, sehingga menyebut salah satunya berarti menyuruhnya menyiapkan sesuatu yang tidak dapat mengubah jawabannya.
Kunci penandatanganan yang disimpan di mesin ini tidak dapat dipilih, melalui kedua jalur mana pun. key_path ditolak sebelum apa pun di-resolve, dan tidak ada dalam skema argumen yang diiklankan publish-entity, sign-artifacts, dan deprecate-artifact di sini, sehingga pemanggil tidak pernah ditawari argumen yang tidak mungkin berhasil. Kunci penandatanganan yang disebut oleh konfigurasi milik workspace yang dilayani juga tidak dijangkau — signing.key_path, baik ditetapkan untuk workspace secara keseluruhan, ditetapkan untuk satu registry, maupun disediakan dari lingkungan. Satu alasan mencakup keduanya: path kunci bukanlah kredensial, melainkan nama untuk rahasia yang disimpan server ini. Pemanggil yang memberikannya tidak membuktikan apa pun, siapa pun yang menjangkau alamat ini dapat memberikan nama yang sama, dan tanda tangan yang dihasilkan akan menyatakan bahwa operatorlah yang menjamin artefak tersebut, bukan pemanggil. Menutup argumen sambil membiarkan konfigurasi terbuka sama dengan menutup satu pintu menuju ruangan yang masih dibuka oleh pintu lainnya. Jadi penandatanganan dengan kunci tidak dapat dijangkau melalui listener: hanya token yang dikirim dalam panggilan yang menandatangani.
fulcio_url, rekor_url, dan timestamp_url tidak terpengaruh dan tetap tersedia di kedua transport. Ketiganya menyebut layanan yang harus dihubungi, bukan sesuatu yang disimpan mesin ini, sehingga pemanggil yang tidak dapat memilih kunci tetap menandatangani terhadap endpoint yang dikonfigurasi deployment ini.
Listener yang dimulai pada workspace yang menyebut kunci penandatanganan menyatakannya sekali, saat dimulai. Proses menulis satu baris pada aliran galatnya sendiri yang menyebut pengaturan tersebut dan menyatakan bahwa pemanggil yang menjangkau listener ini tidak dapat menggunakan kunci itu — sehingga operator mengetahuinya dari proses yang dimulainya, bukan dari tanda tangan yang tidak diharapkannya. Workspace yang tidak menyebut kunci tidak menghasilkan baris seperti itu, karena tidak ada yang perlu disampaikan tentangnya. Baris tersebut memuat nama pengaturan, dan bukan kuncinya maupun apa pun tentang file yang ditunjuknya.
Melalui standard input dan output, tidak satu pun hal di atas berlaku. Di sana lingkungan dibaca dan key_path memilih kunci yang disimpan di mesin ini, karena klien yang meluncurkan server ini berjalan di mesin milik pemanggil sendiri, dan apa yang dapat dijangkau proses itu adalah hak pemanggil itu sendiri untuk digunakan.
Membaca entitas melalui referensi registry-nya menghubungi satu registry, dengan login milik host ini sendiri, dan melalui listener hanya registry yang dikonfigurasi untuk workspace yang dilayani. describe yang dikirimi referensi oci:// sebagai name-nya membaca entitas yang dipublikasikan pada koordinat tersebut — pembacaan yang sama yang dilakukan aggrega inspect — dari satu registry yang disebut referensi tersebut, menggunakan login yang sudah dimiliki host ini untuk registry itu. Panggilan tidak membawa kredensial, dan describe tidak menerima kredensial apa pun. Melalui HTTP, registry tersebut harus salah satu yang dikonfigurasi untuk workspace yang dilayani: host yang disebut oleh default_registry-nya, atau host yang dicantumkan di registries, dibandingkan secara persis dan beserta port-nya. Referensi ke host lain mana pun — termasuk alamat di mesin ini — ditolak sebelum host tersebut dihubungi, dan penolakannya menyebut host tersebut, sehingga pemanggil tidak dapat mengarahkan server ini ke tujuan pilihannya. Apa yang tetap dapat dijangkau memang disengaja: pemanggil yang memegang aggrega:read dapat membaca apa pun yang dapat dibaca login host ini pada registry yang dikonfigurasi untuk workspace, yang juga merupakan apa yang dapat dibaca seseorang di terminal host ini. Melalui standard input dan output, referensi ke registry mana pun dibaca, seperti di baris perintah. Mendeskripsikan entitas melalui nama katalognya tidak terpengaruh.
Panggilan registry menggunakan penyimpanan kredensial milik pengguna sistem operasi yang menjalankan proses ini, persis seperti panggilan yang sama di terminal pada host ini. Tidak ada sumber kredensial per workspace dan tidak ada pengaturan yang menambahkannya, itulah sebabnya registry-list melaporkan status kredensial sebuah host dengan cara yang sama di setiap workspace di mesin ini. Deployment yang ingin agar workspace yang berbeda memegang kredensial registry yang berbeda menjalankannya sebagai pengguna sistem operasi yang berbeda — satu proses per workspace, masing-masing dimulai sebagai penggunanya sendiri. Dari situlah pemisahan berasal, dan mengaturnya adalah tugas operator.
Apa yang dicatat server
Setiap permintaan yang dijawab endpoint ini meninggalkan satu baris di aliran galat proses, dan baris itu adalah satu objek JSON. Baris tersebut memuat time saat ditulis dan request_id yang dibuat proses ini untuk panggilan tersebut dan tidak dikirim kembali ke pemanggil; subject dan issuer sebagaimana dinyatakan oleh kredensial yang disajikan, dengan client_id jika kredensial itu menyebutnya; workspace_root, workspace yang dilayani proses ini; method, dan target jika metode tersebut merujuk sesuatu berdasarkan nama; reach, jenis yang dideklarasikan operasi, dan reach_escalated_to jika panggilan menjangkau lebih jauh dari itu; outcome; duration_ms; dan transport. Bidang yang tidak memiliki isi dihilangkan alih-alih ditulis kosong, sehingga client_id yang tidak ada berarti kredensial yang tidak menyebut klien, dan reach_escalated_to yang tidak ada berarti panggilan yang menjangkau tepat apa yang dideklarasikan operasinya.
outcome menyatakan apa yang terjadi pada panggilan, dan nilainya dibedakan agar Anda dapat menghitungnya secara terpisah. ok berarti dijalankan dan berhasil. tool-failure berarti dijalankan dan kembali dengan tanda kegagalan yang dapat diperbaiki pemanggil — panggilan yang dilayani server ini, bukan yang ditolaknya, sehingga tidak termasuk di antara penolakan Anda. error adalah penolakan yang dikembalikan sebagai envelope galat protokol. unauthenticated, forbidden, dan rate-capped adalah kredensial, batas asal atau scope, dan batas laju per pemanggil yang menolak sebuah permintaan. cancelled adalah pemanggil yang menutup koneksinya sebelum dijawab.
Alasan kredensial yang ditolak dikembalikan adalah bidang pada baris yang sama itu, bukan baris tersendiri. Permintaan yang ditolak meninggalkan satu catatan seperti permintaan lainnya, dengan refusal yang menyebut pemeriksaan yang menolaknya. Tidak ada kredensial, maupun bagian darinya, yang sampai ke baris mana pun — tidak pada penolakan, dan tidak pada panggilan yang dilayani.
Pemanggil yang sama sekali tidak menyajikan apa pun tidak meninggalkan baris. Menerima challenge adalah cara klien mengetahui tempat memperoleh token, sehingga itulah hal pertama yang dilakukan setiap klien yang berperilaku baik, dan satu baris untuk setiap kejadian itu akan mengubur penolakan yang benar-benar bermakna. Permintaan yang menyebut path atau metode yang tidak dilayani endpoint ini juga tidak meninggalkan baris: keduanya diputuskan sebelum apa pun tentang pemanggil dibaca, sehingga memindai alamat tidak menulis apa pun ke apa pun yang mengumpulkan aliran tersebut.
Konteks trace yang dikirim klien disalin apa adanya ke baris tersebut. traceparent, dan di sampingnya tracestate serta baggage jika keduanya juga dikirim, diteruskan persis seperti diterima, sehingga apa pun yang mengumpulkan aliran ini dapat menggabungkannya dengan catatan milik pemanggil sendiri. Permintaan yang tidak mengirim satu pun, atau mengirim yang bukan konteks trace W3C yang terbentuk dengan baik, menghasilkan baris tanpa kunci-kunci tersebut: tidak ada yang dibuat-buat, dan tidak ada yang diubah di sepanjang jalan.
Proses mencatat riwayat hidupnya sendiri dalam bentuk yang sama dan pada aliran yang sama, dengan setiap baris tersebut menyebut sebuah event di tempat baris permintaan menyebut metode dan pemanggil: startup saat dimulai, listening dengan alamat tempat ia melakukan bind, startup-refused dengan alasan peluncuran ditolak sebelum melayani, signing-key-ignored jika workspace yang dilayaninya menyebut kunci penandatanganan yang tidak dapat digunakan oleh pemanggil mana pun yang menjangkau listener ini, docs-bundle dengan hasil pengambilan bundel dokumentasi, dan shutdown saat eksekusi berakhir. Keberadaan event adalah cara membedakan kedua jenis baris tersebut.
Anda mengumpulkan semuanya dari aliran galat proses, dan itulah keseluruhan pengirimannya. Tidak ada exporter yang perlu dikonfigurasi, tidak ada file yang perlu disebut, dan tidak ada pengaturan yang menyalakan, mematikan, atau mengalihkan apa pun darinya: apa pun yang mengawasi proses ini — container runtime, pengelola layanan, pengirim log — itulah yang mengumpulkan aliran tersebut, dan tempat Anda mengkuerinya sesudahnya. Melalui standard input dan output, aliran yang sama justru membawa prosa yang dapat dibaca, karena klien yang membacanya meluncurkan proses tersebut dan berada di mesin yang sama.
Tidak ada satu pun darinya yang dikirim ke pemanggil. Server tidak memublikasikan aliran log melalui protokol di transport mana pun, dan permintaan yang membawa bidang tingkat log per permintaan milik protokol dijawab persis seperti permintaan yang tidak membawanya: apa yang dicatat di sini adalah milik operator, dan hanya masuk ke aliran milik operator.
Apa yang disampaikan server kepada model saat terhubung
Server menawarkan satu blok panduan untuk model, yang dapat disajikan klien Anda kepadanya sebelum panggilan pertama. Klien pada 2026-07-28 membacanya dari jawaban server/discover; klien pada 2025-06-18 membacanya dari balasan atas handshake initialize-nya. Teksnya sama di kedua jalur, byte demi byte, dan sama untuk setiap klien yang menjangkau satu proses: tidak ada yang dinegosiasikan di dalamnya, dan tidak ada yang diturunkan dari apa yang dikirim klien atau dari kredensial yang disajikannya, sehingga apa yang disampaikan kepada model saat terhubung tidak berbeda antarsesi maupun antarklien.
Dua hal bervariasi, dan tidak satu pun adalah klien. Paragraf penutup disusun untuk transport yang dilayani sebuah proses, sehingga server yang berkomunikasi melalui standard input dan output dan sebuah listener menyerahkan teks penutup yang berbeda kepada model. Dan jika bundel desktop yang meluncurkan server berasal dari rilis yang berbeda dengan executable aggrega yang diluncurkannya, panduan dibuka dengan satu kalimat yang menyatakan hal itu, menyebut kedua versinya — kalimat yang membuka jawaban describe-capabilities tanpa argumen, sebagaimana dijelaskan di Dari rilis mana server berasal; peluncuran yang tidak dilakukan oleh bundel, dan peluncuran yang bundelnya berasal dari rilis executable itu sendiri, menyerahkan panduan tanpa kalimat tersebut. Keduanya ditetapkan saat proses dimulai, dan di dalam masing-masing proses kedua revisi tetap menyajikan teks milik proses tersebut secara identik.
Panduan ini mengajarkan model mental yang tidak dapat disampaikan skema argumen sebuah tool dengan sendirinya:
- Apa yang dilakukan compiler, dan apa yang sengaja tidak dilakukannya — bahwa ia merutekan teks dan mengevaluasi kecocokan label alih-alih menafsirkan arti sebuah nilai, bahwa ia tanpa opini sendiri tentang konten yang Anda masukkan ke dokumen Anda, dan bahwa selama kompilasi ia tidak pernah melakukan autentikasi dengan penyedia, tidak pernah membaca status kluster, dan tidak pernah mengubah rahasia menjadi teks biasa. Nilai yang baru ada setelah infrastruktur berjalan diteruskan sebagai string penunjuk yang diisi lingkungan target kemudian.
- Kosakata authoring, dan bagaimana jenis-jenisnya saling berhubungan — untuk apa setiap jenis dan terhadap jenis mana build benar-benar dijalankan, sehingga asisten tidak perlu menyimpulkan bentuk sebuah deployment dari daftar tool.
- Urutan berjalannya siklus authoring — baca kontraknya, buat kerangka darinya, periksa apa yang Anda hubungkan, lalu periksa sebelum merender.
- Kapan memakai prompt alih-alih tool — tool untuk bertindak, prompt untuk membingkai tugas.
- Bahwa daftar tool adalah seluruh antarmuka — setiap tool yang ditawarkan server ini ada di dalamnya, dan tool mana yang ditawarkan sebuah server bergantung pada cara server itu disiapkan, sehingga asisten membaca apa yang ada di sini dari daftar itu dan dari
describe-capabilitiesalih-alih mencari daftar kedua. Jika koneksi menyajikan kredensial, panduan menyatakan bahwa kredensial menentukan tool mana yang boleh dijalankan sebuah panggilan dan tidak pernah menentukan tool mana yang dicantumkan: panggilan yang tidak diizinkannya ditolak dengan menyebut scope yang akan mengizinkannya, dan klien dapat masuk lagi untuk scope tersebut. - Apa arti workspace yang kosong, dan apa yang boleh dilakukan model terhadapnya — paragraf yang berbeda menurut transport, di bawah.
Panduan menyebut antarmukanya alih-alih menyatakannya ulang. Setiap tool sudah membawa deskripsi dan skema argumennya sendiri di tools/list, dan kontrak setiap jenis sudah ada di skemanya dan halaman referensinya, sehingga panduan menunjuk ke sana lalu berhenti — satu tempat untuk setiap pernyataan. Tool yang disebutnya adalah tool yang dilayani server, dan panduan menunjuk ke setiap keluarga sumber daya yang di-resolve oleh antarmuka baca, sehingga tidak ada tempat yang dituju asisten atas arahannya yang merupakan jalan buntu.
Panduan tidak memuat indeks tool itu sendiri, dan itu adalah aturan yang sama, bukan pengecualian darinya. Klien memegang definisi setiap tool dari tools/list sebelum membaca satu kata pun dari teks ini, sehingga satu baris per tool di sini akan menjadi salinan kedua dari tujuan yang sudah dimilikinya — dibayar di setiap sesi, oleh setiap klien, dan bebas berbeda dari daftar tool begitu salah satunya diedit.
Panduan juga menyatakan apa yang tidak dirincinya, dan alasannya: target render yang tersedia dan jenis pustaka yang terpasang adalah properti plugin Anda dan kumpulan skema Anda, sehingga antarmuka sumber daya melaporkannya secara langsung alih-alih panduan membawa salinan yang bisa berbeda.
Apa yang disampaikan kepada model tentang workspace yang kosong
Paragraf penutup menjawab pertanyaan yang pertama kali dihadapi model pada workspace yang tidak berisi apa pun: apa arti list-entities yang kosong, dan apa yang boleh dilakukannya terhadap hal itu. Pembukaannya sama di kedua transport — daftar yang kosong berarti workspace yang di-resolve proses ini tidak berisi dokumen Aggrega yang dapat dibacanya dan direktori katalog yang dikonfigurasi di sampingnya juga tidak mendeklarasikan satu pun — dan apa yang menyusul bergantung pada transport yang dilayani proses ini, karena jawaban yang jujur tidak sama di keduanya.
Melalui standard input dan output, model diberi tahu bahwa workspace itu boleh diperiksa dan diperbaikinya. Model diberi tahu di mana panggilan yang tidak menyebut workspace dijawab — di folder yang digunakan untuk meluncurkan server, jika server diluncurkan dengan folder, dan jika tidak, di workspace yang ditemukan dari folder tempat server dimulai, yang bisa saja folder itu sendiri — dan bahwa workspace_root pada sebuah panggilan menyebut workspace lain. Model diarahkan ke config-show untuk konfigurasi yang berlaku dan lapisan mana yang menentukan setiap pengaturan, dan ke cli-config-init untuk menyiapkan konfigurasi yang berfungsi; keduanya ada di daftar tool pada transport tersebut. Klien yang menjalankan server berada di mesin milik pemanggil sendiri, sehingga apa yang dapat dijangkau proses itu adalah hak pemanggil itu sendiri untuk digunakan — dan tempat Anda menetapkan batas adalah tempat batas itu ditetapkan untuk setiap tool lainnya, yaitu di klien MCP Anda, sebagaimana dijelaskan di Apa yang dapat dilakukan asisten tanpa bertanya kepada Anda lebih dulu.
Melalui HTTP, model diminta melaporkan alih-alih mengonfigurasi. Workspace-nya adalah workspace tempat Anda memulai proses dan bersifat tetap sepanjang masa hidupnya; panggilan yang menyebut workspace_root atau catalog_dirs ditolak, dengan menyebut argumennya; dan tidak ada tool yang menulis konfigurasi yang ditawarkan kepada pemanggil mana pun di sini, apa pun scope yang dibawa kredensialnya. Operasi tersebut hanya ditawarkan oleh tool yang menjalankan perintah aggrega dalam proses terpisah, dan sesi yang dijangkau melalui HTTP disusun tanpa tool tersebut — jadi batasnya adalah komposisi, bukan scope, dan tidak ada token yang memperluasnya. Karena itu, model yang menjangkau deployment Anda melalui listener tidak dapat menyiapkan registry atau menulis ulang kebijakan kepercayaan di host Anda, dan paragraf tersebut memberitahunya hal itu alih-alih membiarkannya mencoba lalu membaca penolakannya.
Apa yang dapat dilakukan asisten tanpa bertanya kepada Anda lebih dulu
Asisten yang terhubung ke server ini melalui standard input dan output dapat memanggil setiap tool yang diekspos server, tanpa bertanya kepada Anda, kecuali klien Anda dikonfigurasi untuk menolaknya. Pada transport itu server menawarkan tool dan tidak menentukan tool mana yang boleh digunakan oleh panggilan tertentu: keputusan itu milik klien Anda, dan Andalah yang membuatnya di sana. Melalui HTTP tidak demikian: server mencantumkan setiap tool yang ditawarkan dan diumumkannya, dan menolak panggilan yang tidak diizinkan oleh scope token pemanggil, sehingga batasnya milik server sekaligus milik klien.
Hal ini penting karena antarmuka tool adalah baris perintah. Apa pun yang dapat Anda ketik dapat dipanggil oleh asisten — termasuk operasi yang mengubah mesin Anda.
Beberapa operasi tersebut menjangkau lebih jauh daripada workspace tempat Anda bekerja, dan tidak dapat dibatalkan dengan menjalankan hal lain. Berikut operasi yang perlu diketahui namanya, dimulai dari jangkauan terluas:
publish-entity,publish-artifact,sign-artifacts, dandeprecate-artifactmenjangkau sepenuhnya melampaui mesin. Semuanya menaruh byte, tanda tangan, atau penanda penarikan di registry, sehingga yang diubahnya adalah apa yang di-resolve oleh setiap konsumen registry tersebut — bukan hanya apa yang dilakukan mesin ini. Memublikasikan ulang konten yang berbeda pada sebuah tag ditolak alih-alih ditawarkan, sehingga tidak ada apa pun di sini yang menarik kembali sebuah publikasi; jawabannya adalah memublikasikan versi baru. Tanda tangan dan penanda penarikan membiarkan byte artefak tidak tersentuh, tetapi siapa pun yang mengambil artefak tersebut sesudahnya juga mengambil keduanya, dan tidak satu pun dapat ditarik kembali dari siapa pun yang sudah memilikinya. Melalui standard input dan output, keempat kemampuan yang sama juga dapat dijangkau sebagaicli-push,cli-push-artifact,cli-sign, dancli-deprecate, yang menjalankan perintahnya; melalui HTTP keempat tool tersebut tidak ada.- Penandatanganan menggunakan kredensial. Melalui standard input dan output, penandatanganan keyless mengambil token identitas dari argumen
identity_tokenmilik panggilan, dariAGGREGA_IDENTITY_TOKENatauSIGSTORE_ID_TOKENdi lingkungan server, atau dari endpoint OIDC ambien GitHub Actions jika ada yang dapat dijangkau;key_pathjustru memilih kunci yang disimpan secara offline. Karena itu, asisten yang dapat memanggil tool ini dapat menandatangani atas nama Anda, dengan identitas apa pun yang sudah dimiliki mesin yang menjalankan server — dan tanda tangan adalah pernyataan tentang siapa yang menjamin sebuah artefak, itulah sebabnya ini adalah operasi yang paling perlu dipikirkan matang-matang sebelum diizinkan. Melalui listener hanya token yang dikirim dalam panggilan yang menandatangani: tidak ada apa pun di lingkungan server yang dibaca, dan tidak ada kunci yang disimpan di host yang dapat dipilih oleh argumen atau oleh konfigurasi workspace yang dilayani, sebagaimana dijelaskan di Kredensial mana yang digunakan sebuah panggilan. aggrega cache evictmemangkas penyimpanan modul terkompilasi, danaggrega cache clearmengosongkannya. Penyimpanan itu dipakai bersama oleh setiap proyek Aggrega di mesin. Modul yang dihapus darinya dikompilasi ulang sesuai kebutuhan, sehingga tidak ada yang hilang secara permanen — tetapi build berikutnya dari proyek mana pun menanggung biaya itu.aggrega cache clearjuga menghapus bundel dokumentasi yang dibaca setiap proyek di mesin, yang diambil lagi saat salah satunya memperolehnya berikutnya.aggrega cache prunemembebaskan entri cache artefak yang tidak dirujuk lockfile mana pun. Jika lockfile sebuah proyek tidak ada untuk dibaca, artefak yang dipin olehnya tidak terlindungi, dan membebaskannya berarti harus mengambilnya lagi.aggrega registry adddanaggrega registry removesecara default menulis ke konfigurasi yang dipakai bersama oleh setiap workspace, sehingga keduanya mengubah apa yang di-resolve di mana pun di mesin, bukan hanya di sini.aggrega registry addjuga meminta kepada registry yang disebutnya kebijakan kepercayaan yang diiklankan registry tersebut dan mem-pin apa yang diterimanya, persis seperti di terminal. Di workspace offline, pengambilan itu ditolak sebelum koneksi apa pun dibuat, sehingga menambahkan registry selain hub resmi ditolak — kode pendekE0310, dengan kata-kata yang sama — kecuali panggilan menyediakanidentityataukey;aggrega config init, yang tidak menerima keduanya, hanya dapat menyiapkan hub secara offline. Melalui standard input dan output, keduanya dapat dijangkau sebagaicli-registry-adddancli-registry-remove, dan penyiapan sebagaicli-config-init, yang menjalankan perintahnya; melalui HTTP tool tersebut tidak ada.pullmembaca dari registry dan menulis di dalam workspace yang ditujunya. Ia menulis lockfile Release tersebut, mengisi cache artefak dengan apa yang di-resolve-nya, dan mencatat di samping lockfile identitas setiap plugin pengembali putusan yang dilampirkan workspace Anda. Jika dikirim denganpin_sources— atau di workspace yangpin_sources_at_pull-nya aktif dan dengan panggilan yang tidak mengirimnya sebagai false — ia juga menjalankan langkah pin milik pembuat entitas atas Recipes dan FeatureRecipes yang dibangun Release dari direktori katalog Anda, sambil menulisentity.lockdi samping masing-masing; tanpanya, pull atas entitas semacam itu yang lock-nya tidak mencatat pin untuk input yang dibacanya ditolak, dengan menyebut langkah tersebut. File entitas itu sendiri tidak pernah ditulis. Tidak satu pun darinya meninggalkan mesin, dan me-resolve ulang adalah cara mengubah apa yang dicatatnya, sehingga inilah operasi penulisan yang paling ringan di sini. Ini adalah salah satu tool yang dirancang untuk siklus authoring yang menulis di dalam workspace:pinmenulisentity.lockdi samping Recipe atau FeatureRecipe yang Anda sebutkan, sebagaimana dijelaskan di Mem-pin input milik entitas sendiri;gen-catalogmenulis entitas Plugin yang dihasilkan di bawah direktori yang Anda sebutkan;edit-documentmenerapkan satu suntingan terstruktur yang terbatas pada dokumen yang sudah Anda miliki dan menuliskannya kembali, dengan mempertahankan setiap byte yang tidak disentuh suntingan, sebagaimana dijelaskan di Menerapkan satu suntingan terbatas pada dokumen;importmengubah deskripsi yang dihasilkan tool lain menjadi file authoring draf dan menuliskannya ke workspace, sebagaimana dijelaskan di Mengubah deskripsi asing menjadi entitas draf; danscaffoldyang dikirimiexamplemenulis salah satu contoh dokumentasi yang dapat dijalankan ke direktori baru atau kosong,dir, sebagaimana dilakukanaggrega scaffold --example, yang melalui HTTP diizinkan oleh scope workspace-write. Direktori output tersebut, guest yang dibacagen-catalog, dan overlay apa pun yang Anda berikan kepadanya masing-masing relatif terhadap root workspace, atau absolut melalui standard input dan output, kontrak yang sama yang digunakan setiap argumen path lain di antarmuka ini. Melalui standard input dan output, kemampuan yang sama juga dapat dijangkau sebagaicli-pull, yang menjalankan perintahnya; melalui HTTP tool tersebut tidak ada.buildmembaca registry yang sama dan melakukan penulisan yang sama ketika Anda mengirimkanauto_pullkepadanya, dan hanya saat itu. Me-resolve dependensi sebuah Release adalah satu operasi di mana pun ia diminta, sehingga build yang diminta me-resolve lebih dulu melakukan persis apa yang dilakukanpulllalu merender terhadap apa yang ditulisnya — itulah sebabnya ia membawa jangkauan yang sama, bukan yang lebih kecil. Jika dikirim denganwrite, ia juga menulis artefak yang dirender kedist/di root workspace, tempataggrega buildmenuliskannya dan melalui penulisan yang sama, sehingga untuk panggilan itu ia menjangkau workspace; ia tidak menulis di tempat lain, dandistyang merupakan tautan yang mengarah ke luar workspace ditolak sebelum apa pun di dalamnya dihapus atau ditulis. Tanpa kedua argumen tersebut, yang merupakan default,buildmerender dari pin yang sudah dimiliki workspace dan tidak menjangkau apa pun. Baca Membangun terhadap konten yang sudah dipin oleh sebuah Release untuk mengetahui apa yang diubah argumen tersebut dan apa yang dibiarkannya.
Tool inventaris menyatakannya dalam jawabannya sendiri. cache-status menandai setiap kelas cache dengan jangkauannya — workspace untuk cache artefak di bawah direktori cache milik proyek ini sendiri, machine untuk penyimpanan yang dipakai bersama oleh setiap proyek — dan menyebut secara eksplisit yang berlaku untuk seluruh mesin, sehingga asisten yang membaca inventaris sebelum mengusulkan pembersihan diberi tahu bagian mana yang bukan milik Anda saja. Operasi pemeliharaan melaporkan jangkauan yang sama untuk setiap elemen yang dihapusnya. Masing-masing dari keempat hasil publikasi membawa reach-nya sendiri, yang memuat registries — setiap host registry yang dituju panggilan, masing-masing disebut sekali, dalam urutan pertama kali dituju — dan beyond_this_machine, yang dibaca dari apa yang benar-benar dilampirkan panggilan, bukan dari apa yang dimintanya: true begitu ia telah mengunggah konten atau melampirkan tanda tangan, tanggal publikasi, atau penanda deprekasi, dan false untuk dry run dan untuk panggilan yang mendapati semuanya sudah ada, seperti publikasi yang dijalankan lagi atas versi yang lengkap atau batch penandatanganan yang referensinya semuanya sudah ditandatangani.
Tempat Anda menetapkan batas. Protokol itu sendiri tidak mendefinisikan izin per tool — autentikasinya menyangkut apakah klien boleh terhubung sama sekali, bukan tool mana yang kemudian boleh dipanggilnya. Keputusan izin berada di klien MCP Anda. Klien yang banyak digunakan umumnya dapat mengizinkan dan menolak tool individual berdasarkan nama dari satu server, dan menonaktifkan server sepenuhnya untuk proyek tertentu; nama dan lokasi pengaturannya berbeda di setiap klien, jadi lihat dokumentasi klien Anda sendiri tentang izin tool. Jika Anda menginginkan pembacaan dan bukan penulisan, izinkan tool yang Anda inginkan dan tolak sisanya di sana. Konfigurasi yang permisif, atau klien tanpa pengaturan semacam itu, membiarkan setiap tool yang diekspos dapat dipanggil.
Mengetahui isi sebuah workspace
Sebagian besar tool menerima sebuah subjek: nama entitas, atau path sebuah Release. Dua tool di bawah ini tidak menerima subjek apa pun, dan melalui keduanyalah asisten yang baru tiba mendapatkan subjek.
list-entities menjawab apa isi workspace dan list-releases menjawab pertanyaan yang lebih sempit yang terus diajukan oleh bagian lain dari permukaan ini: Releases apa saja yang ada. Keduanya tidak menerima subjek, karena isi sebuah workspace adalah properti workspace itu, bukan properti sesuatu yang harus diketahui pemanggil terlebih dahulu.
Masing-masing menjawab dalam salah satu dari dua bentuk, dan panggilan yang tidak menyebutkan bentuk apa pun mendapatkan ringkasan. Bawaan ini hanya berlaku untuk kedua tool ini, dan merupakan kebalikan dari bawaan yang digunakan build, describe, dan validate. Tool-tool tersebut ditanya tentang subjek yang sudah disebutkan pemanggil, sehingga jawaban yang lebih lengkap adalah yang diminta dan jawaban ringkas adalah pilihan tambahan. Kedua tool ini ditanya apa yang ada di sini, oleh pemanggil yang belum memiliki apa pun untuk disebutkan dan tidak dapat mengetahui berapa biaya jawabannya sebelum jawaban itu tiba — sehingga keduanya melaporkan ukuran dan bentuk workspace terlebih dahulu dan baru menyerahkan rekaman jika diminta.
Ringkasan menyebutkan apa yang ada di sini dan berapa banyak. list-entities melaporkan root workspace — yang ditahan melalui HTTP, sebagaimana dijelaskan dalam Apa yang dikatakan jawaban tentang sistem file server — jumlah total entitas, dan jumlah per jenis; list-releases melaporkan total dan jumlah per direktori tingkat atas, sehingga Anda mengetahui berapa banyak Releases yang ada dan di bagian pohon mana Releases tersebut berada. Kedua rincian dibaca dari dokumen itu sendiri, sehingga workspace yang disusun dengan cara yang tidak diantisipasi siapa pun diringkas seakurat workspace lainnya. Keduanya memuat satu baris per jenis, atau per direktori tingkat atas, sehingga ukurannya mengikuti berapa banyak jenis yang dideklarasikan workspace dan di berapa direktori Releases-nya berada, bukan berapa banyak dokumen yang dimuatnya: kalikan dokumen dalam sebuah workspace seratus kali tanpa mengubah jenisnya, dan ringkasan hanya bertambah beberapa byte yang diperlukan untuk menulis angka yang lebih besar. Mendeklarasikan lebih banyak jenislah yang membuatnya lebih panjang. Keduanya bukan halaman pertama rekaman, dan justru di situlah perbedaannya: “berikut sebagian entitasnya” adalah jawaban yang berbeda dari “inilah susunan workspace ini”, dan hanya yang kedua yang memberi tahu Anda apakah Anda menginginkan rekaman sama sekali, dan rekaman yang mana.
Kirim response_format: detailed untuk mendapatkan rekaman, dan rekaman tersebut tiba satu halaman setiap kali. list-entities kemudian melaporkan jenis, nama, apiVersion, deskripsi, label, dan file sumber setiap entitas, yang dibaca langsung dari dokumen yang mendeklarasikannya. Tool ini juga melaporkan Features yang dideklarasikan oleh direktori katalog yang Anda konfigurasi, sehingga Feature yang ditawarkan kepada Anda sebagai dapat dilampirkan juga merupakan Feature yang dapat Anda cari; Features tersebut tidak memiliki file sumber, karena satu-satunya path yang dimilikinya adalah path di mesin tempat server berjalan, dan masing-masing menyebutkan asalnya sehingga file yang kosong terbaca sebagai “diresolusi dari katalog”, bukan sebagai nilai yang hilang. list-releases melaporkan path setiap Release, dan lockfiles memetakan setiap path yang dikembalikannya ke path lockfile Release tersebut, dalam koordinat yang sama: file yang ditulis pull untuknya dan dibaca build, file yang sama yang disebutkan oleh jawaban Release dari language server. Peta tersebut menjelaskan path yang dimuat jawaban ini, sehingga mengikuti halaman, dan ringkasan memuatnya dalam keadaan kosong.
detailed dan concise adalah satu-satunya nilai yang diterima response_format, dan keduanya dicocokkan secara persis. Ejaan lain apa pun — kata yang berbeda, huruf besar-kecil yang berbeda, atau spasi di sekitar salah satunya — ditolak, dan penolakan tersebut menyebutkan apa yang dikirim beserta nilai-nilai yang diterima argumen tersebut. Menghilangkan response_format adalah cara meminta nilai bawaan, yang untuk kedua tool ini adalah ringkasan. Hal yang sama berlaku di mana pun argumen ini muncul: build, describe, dan validate menerima dua nilai yang sama dengan ketentuan yang sama, dan nilai bawaan mereka adalah bentuk yang lebih lengkap, bukan yang ringkas.
Rekaman dibatasi, baik Anda membatasinya maupun tidak. limit adalah jumlah rekaman yang dimuat satu jawaban, antara 1 dan 500, dengan nilai bawaan 50 — sehingga panggilan yang meminta rekaman tanpa menyebutkan ukuran halaman tetap dibatasi, dan tidak ada pemanggilan salah satu tool yang mengembalikan jawaban yang ukurannya ditentukan oleh ukuran workspace. offset adalah posisi awal dalam daftar, dihitung dari 0. Keduanya membatasi rekaman, sehingga tidak satu pun berpengaruh pada ringkasan, yang tidak memuat rekaman. limit di luar rentang tersebut ditolak dan menyebutkan batasnya; offset yang melewati akhir daftar kembali kosong, karena memang tidak ada apa-apa di sana, bukan karena ada yang salah dengan pertanyaannya.
Lanjutkan sebuah daftar dengan membaca tiga field dari jawaban. count adalah jumlah rekaman yang dimuat workspace, offset dan returned menyebutkan di mana jawaban ini dimulai dan berapa banyak yang dimuatnya, dan more_remaining menyebutkan apakah masih ada yang tersisa. Selama more_remaining bernilai true, panggil lagi dengan offset ditambah returned. Sinyal tersebut dihitung dari halaman terhadap total, bukan ditulis ke dalam jawaban, sehingga tidak mungkin melaporkan bahwa tidak ada yang tersisa padahal masih ada rekaman.
Semua itu penting karena tool yang menerima nama menolak nama yang tidak dapat diresolusinya alih-alih menjawab dengan hasil kosong. Penolakan ini disengaja — jawaban kosong akan melaporkan nama yang salah ketik sebagai subjek yang tidak memiliki apa pun untuk ditawarkan — tetapi itu berarti pemanggil yang tidak memegang nama tidak dapat memperolehnya dengan menebak. Membuat daftar adalah cara untuk memperolehnya.
Keduanya dapat digabungkan, satu sama lain dan dengan bagian lain dari permukaan ini:
- Panggil
list-entitiesuntuk mendapatkan ringkasan guna melihat jenis apa saja yang dimuat workspace dan berapa banyak masing-masing, lalu panggil lagi denganresponse_format: detaileduntuk mendapatkan rekaman, ambil sebuah nama dari hasilnya, dan serahkan kedescribeuntuk melihat definisi entitas tersebut yang telah diresolusi sepenuhnya. Itu adalah definisi yang menjadi jawabanaggrega/entityDefinitiondari language server, dibawa sebagai JSON: setiap kunci dengan nama yang ditulis pembuatnya, dalam urutan yang dimuat definisi tersebut, skema sebagaimana skema yang ditulis pembuatnya, dan skema yang tidak dideklarasikan entitas tersebut dihilangkan — socket sebuah Component masing-masing dengan slot yang dapat diisi oleh koneksinya. - Lakukan hal yang sama dengan
list-releases, ambil sebuah path dari hasil terperinci, dan serahkan kedescribeataubuildsebagai Release yang akan dikerjakan. - Path yang dikembalikan
list-releasesbersifat relatif terhadap root workspace, yaitu koordinat yang sama dengan tempatlist-entitiesmelaporkan sebuah file, sehingga kedua jawaban sejajar pada file tersebut dan dapat dibaca bersama. Lockfile-nya, di bawahlockfiles, relatif terhadap root yang sama, sehingga Anda dapat membaca atau membandingkan file tersebut tanpa perlu mencari tahu letaknya.
Keduanya menentukan apa yang dihitung dengan membaca kind milik setiap dokumen itu sendiri, tidak pernah nama filenya. Release yang dinamai tanpa prefiks konvensional tetap dicantumkan; file yang sekadar dinamai seperti Release tidak, dan muncul di bawah jenis apa pun yang benar-benar dideklarasikannya. YAML yang sama sekali tidak mendeklarasikan kind — file values sebuah chart, file konfigurasi yang kebetulan berada di dalam pohon — bukan entitas dan tidak dilaporkan, begitu pula dokumen milik proyek lain, seperti manifest Kubernetes yang telah dirender. Sebuah dokumen dihitung sebagai entitas jika mendeklarasikan kind sekaligus nama, karena keduanya bersama-samalah yang membuatnya dapat dialamatkan setelahnya, dan tidak mendeklarasikan apiVersion di luar grup milik Aggrega sendiri. Dokumen yang sama sekali tidak mendeklarasikan apiVersion tetap dilaporkan, karena merupakan dokumen Aggrega yang kehilangan satu field, bukan file proyek lain. list-releases tidak menelusuri direktori apa pun di luar root workspace, sehingga Release yang ditampilkan editor Anda di bawah link yang mengarah ke direktori semacam itu tidak dicantumkan; unread_linked_dirs menyebutkan setiap link yang berada di tempat daftar akan membaca sebuah direktori dan mengarah ke luar root — berdasarkan path link itu sendiri yang relatif terhadap root, tidak pernah berdasarkan tujuannya — dalam kedua bentuk dan pada kedua transport, dan kosong jika tidak ada. Tool ini juga tidak membaca file di luar root melalui link: unread_linked_files menyebutkan, dengan cara yang sama, setiap link yang namanya sendiri berakhiran .yaml atau .yml dan mengarah ke file di luar root, apa pun isi file tersebut, sehingga Release yang hanya dapat dijangkau melalui link semacam itu tidak dicantumkan — kecuali konfigurasi workspace menyebutkan Release tersebut, sebagai build.authoring_release atau sebagai kunci dari workspace.releases, dan dalam hal ini Release tersebut dibaca dan dicantumkan di tempat link itu sendiri dan tidak disebutkan. list-entities juga tidak membaca dokumen apa pun di balik link yang mengarah ke luar workspace — tool ini tidak menelusuri direktori apa pun di luar root, dan tidak membaca file apa pun di luarnya apa pun yang dideklarasikan file tersebut — dan menyebutkan setiap link semacam itu dengan cara yang sama, dalam unread_linked_dirs dan unread_linked_files miliknya sendiri, dalam kedua bentuk dan pada kedua transport. Hal itu berlaku apa pun yang dideklarasikan dokumen tersebut, dengan satu pengecualian yang juga dibuat list-releases: Release yang disebutkan konfigurasi workspace, sebagai build.authoring_release atau sebagai kunci dari workspace.releases, dibaca dan dicantumkan di tempat link itu sendiri dan tidak disebutkan, sedangkan file yang disebutkan salah satu pengaturan tersebut yang mendeklarasikan sesuatu selain Release tidak dicantumkan, dan link-nya disebutkan. Direktori katalog yang dikonfigurasi adalah cara workspace membaca entitas lain yang disimpan di tempat lain, sehingga link ke direktori yang dicantumkan konfigurasi di bawah catalog_dirs, atau ke direktori di bawahnya, tidak disebutkan oleh kedua daftar: konfigurasi telah menjangkaunya. Features yang diambil list-entities dari direktori katalog tidak pernah mencakup Feature di balik link yang mengarah ke luar direktori tempat pembacaan sebuah direktori katalog harus tetap berada — workspace, untuk direktori katalog di dalamnya, atau direktori itu sendiri, untuk direktori yang disebutkan konfigurasi di luarnya — sehingga entitas yang disebutkan berada di balik link yang tidak dibaca tidak pernah dicantumkan di samping nama tersebut. Link yang dikecualikan daftar — karena namanya, letaknya, atau sebuah .gitignore — tidak disebutkan, dan dengan release begitu pula link di bawah direktori katalog yang hanya dibaca oleh Releases lain; .gitignore yang dirinya sendiri merupakan link yang mengarah ke luar workspace tidak dibaca. Jika salah satu daftar ini menyebutkan sebuah link, jawaban teks ditutup dengan baris tersendiri yang menyatakan hal itu.
Workspace yang file konfigurasinya mengarah ke luar workspace tersebut tetap dicantumkan, dan tidak ada hal lain yang dijawab untuknya. Jika .aggrega-config.yaml milik workspace itu sendiri, atau overlay milik CI di sampingnya, merupakan link yang mengarah ke luar workspace, konfigurasinya tidak dibaca, sama seperti di terminal, dan tidak ada apa pun yang akan dikonfigurasinya yang dibaca sebagai gantinya. Server tetap dimulai melalui input dan output standar, dan menyatakannya dalam satu baris pada stream error-nya. list-entities dan list-releases menjawab dengan dokumen milik workspace itu sendiri, yang dibaca tanpa konfigurasi apa pun, sehingga tidak ada Features dari direktori katalog mana pun yang dicantumkan. Masing-masing menyebutkan file yang ditahan dalam unread_linked_files, dan dalam baris penutup teksnya, baik daftar tersebut menemuinya maupun tidak — nama itulah cara Anda mengetahui bahwa konfigurasi workspace mengarah ke luar workspace tersebut. Daftar yang dikirimi release atau catalog_dirs, dan setiap tool lain yang menyebutkan workspace tersebut, bergantung pada konfigurasi yang tidak dibaca, sehingga masing-masing ditolak dengan E0321, yang menyebutkan link tersebut dan tujuannya. Server yang diperintahkan melalui baris perintahnya untuk mendengarkan — --transport http, atau --listen — tidak dimulai pada workspace semacam itu, karena alamat yang akan diikatnya, sertifikatnya, dan siapa yang boleh memanggilnya adalah hal-hal yang ditentukan konfigurasi tersebut. Hapus link tersebut, atau buat agar mengarah ke file di dalam workspace, dan panggilan berikutnya akan membaca konfigurasi. Lihat batas workspace.
Bertanya dalam ketentuan sebuah Release
Workspace dapat memberikan direktori katalog tersendiri kepada setiap Release — lihat Memberikan direktori katalog tersendiri kepada sebuah Release — sehingga dapat menyimpan satu varian sebuah entitas per Release secara berdampingan. Tiga tool yang biasanya menjawab berdasarkan direktori katalog milik workspace sendiri menerima release opsional, yaitu path file Release, lalu menjawab dalam ketentuan Release tersebut:
list-entitiesdenganreleasemencantumkan entitas yang dilihat Release tersebut. Features yang dicantumkan adalah yang dideklarasikan oleh direktori katalognya, dan dokumen workspace di bawah direktori katalog yang hanya dibaca oleh Releases lain dikecualikan, sehingga setiap varian dicantumkan untuk Release yang melakukan build dengannya dan tidak untuk Release lain. Dokumen yang sama sekali tidak berada di bawah direktori katalog mana pun — sebuah Release, Aggregate-nya, dan Manifest-nya yang ditulis di samping katalog — dicantumkan untuk setiap Release.describedengannamedanreleasemeresolusi nama tersebut melalui direktori katalog Release itu, sehingga nama yang dideklarasikan oleh beberapa varian diresolusi ke varian yang digunakan Release tersebut untuk build. Nama yang tidak dapat diresolusi oleh direktori tersebut ditolak dengan penjelasan yang menyebutkan entri Release tersebut di bawahworkspace.releases. Referensi registry dibaca dari registry-nya apa pun Release yang disebutkan, sehingga ditolak jika disertairelease.releaseyang dikirim tanpanametetap merupakan Release yang diringkas olehdescribe.validatedenganentitydanreleasemenjalankan pemeriksaan entitas tunggal dalam ketentuan Release tersebut: referensi entitas — Component yang diimplementasikan sebuah Recipe, SchemaLibrary yang dirujuk sebuah pilar — diresolusi melalui direktori katalog Release tersebut, dan jawabannya menyebutkan Release itu di samping entitas. Tidak ada closure yang divalidasi;releaseyang dikirim tanpaentitytetap merupakan cakupan Release.catalog_dirsditambahkan di depan direktori Release di sini sebagaimana di mana pun. Direktori yang dicantumkan konfigurasi workspace tetapi bukan direktori — misalnya tidak ada apa pun di sana — untuk Release tersebut, atau untuk workspace jika tidak adareleaseyang dikirim, membuat panggilan ditolak sebelum apa pun diperiksa, dengan teks yang membawa penolakan yang diberikan setiap perintah kepadanya, serta menyebutkan entri tersebut beserta file konfigurasi dan baris yang mencantumkannya (Tempat entitas lokal dibaca), sebagaimanaaggrega validatemenolaknya.
release yang menyebutkan file yang tidak ada, atau menyebutkan sebuah direktori, ditolak oleh ketiganya alih-alih dijawab dalam ketentuan workspace. Jika tidak ada yang dikirim, jawaban diberikan berdasarkan direktori katalog milik workspace sendiri.
describe yang mencari sebuah nama menolak direktori katalog yang akan digunakannya untuk meresolusi nama tersebut tetapi tidak dapat ditelusuri, sebagaimana aggrega inspect menolaknya — direktori milik Release tersebut jika release dikirim, direktori milik workspace sendiri jika tidak, dan direktori apa pun yang disebutkan panggilan dalam catalog_dirs. Direktori yang disebutkan panggilan tetapi tidak ada, atau yang ada tetapi tidak dapat dibaca, ditolak sebelum nama dicari, dan teksnya menyebutkan direktori tersebut sebagaimana baris perintah melaporkannya, dalam satu baris — direktori, catalog load, dan alasan yang diberikan sistem file — alih-alih meresolusi nama dari direktori yang tersisa. Direktori yang dicantumkan konfigurasi workspace tetapi bukan direktori ditolak pada saat yang sama, dengan teks yang membawa penolakan yang diberikan setiap perintah kepadanya (Tempat entitas lokal dibaca). release yang menyebutkan file yang tidak ada ditolak sebelum itu, seperti di atas. Direktori katalog yang memuat link yang mengarah ke luar direktori tempat pembacaannya harus tetap berada ditolak dengan cara yang sama, dengan teks yang menyebutkan link tersebut dan tujuannya, karena nama yang diresolusi tanpanya dapat teresolusi ke entitas lain bernama sama sebagai gantinya. Mendeskripsikan closure dependensi sebuah Release tidak terpengaruh oleh direktori yang tidak dapat ditelusuri, dan menjawab berdasarkan direktori yang dapat ditelusuri, sebagaimana yang dilakukan aggrega inspect --closure — kecuali direktori yang dicantumkan konfigurasi workspace untuk Release tersebut tetapi bukan direktori, yang ditolaknya sebagaimana aggrega inspect --closure menolaknya; link yang mengarah ke luar pembacaan direktori katalog, atau ke luar dokumen di samping Release, menghentikannya, sebagaimana link itu menghentikan build.
validate dengan entity melaporkan render yang tidak dapat dinilainya sebagai tidak dicoba, dalam ketentuan sebuah Release atau tanpa ketentuan apa pun. Tool ini menempatkan Component sebuah Recipe dalam build sintetis yang tidak menyambungkan koneksi apa pun dan tidak melampirkan Feature apa pun, sehingga Recipe yang render-nya berhenti saat template-nya — termasuk file dan entri library yang diimpornya — membaca apa pun di bawah .context.inject, .context.uses, atau .features menjawab valid: true tanpa apa pun dalam diagnostics; teksnya memuat Render: not attempted (this Recipe reads values a build of one cannot supply), pembacaan yang menjadi alasan Recipe itu dikesampingkan, dan kalimat tempat render berhenti. Yang menentukan adalah apa yang dibaca Recipe, sehingga kesalahan milik Recipe itu sendiri di samping pembacaan semacam itu ikut dikesampingkan, sedangkan template yang tidak dapat di-parse dan referensi yang ditolak render tetap menjawab valid: false. aggrega validate memberikan putusan yang sama untuk input yang sama.
validate dengan entity melaporkan asersi yang gagal sebagai peringatan, dalam ketentuan sebuah Release atau tanpa ketentuan apa pun. Asersi yang memanggil fail — milik Recipe itu sendiri, atau yang dideklarasikan Component yang diimplementasikannya — menjawab valid: true tanpa apa pun dalam diagnostics. Build sintetis memuat placeholder dan nilai bawaan skema sebagai pengganti nilai yang ditetapkan Release sungguhan, sehingga asersi atas nilai semacam itu gagal di sana terlepas dari apakah Recipe tersebut benar atau tidak, dan pemeriksaan tidak dapat membedakan asersi yang menunggu sebuah Release dari asersi yang rusak. Kegagalan tersebut menyusul notices lainnya, dalam pesan lengkap asersi yang ditutup dengan kalimat A Release must satisfy this assertion before a build of it can pass., dan teksnya memuatnya pada baris yang diawali warning:, di samping baris laporan yang menyebutkan di mana proses berhenti. Asersi yang berhenti pada kunci yang dibacanya tetapi tidak ditemukannya adalah kesalahan dalam teksnya sendiri, bukan asersi yang gagal, dan dinilai seperti penghentian lainnya; build sebuah Release yang tidak memenuhi suatu asersi tetap ditolak karenanya. aggrega validate memberikan putusan yang sama untuk input yang sama.
Membaca konfigurasi yang berlaku dan plugin yang diresolusi server ini
config-show melaporkan konfigurasi yang berlaku dan lapisan mana yang menentukan setiap pengaturan. plugin-list melaporkan plugin yang dapat diresolusi server ini dan apa yang dikatakan masing-masing plugin tentang dirinya. Keduanya tidak membaca dan tidak menulis apa pun, sehingga tidak satu pun menjangkau apa pun dan aggrega:read mengizinkannya — dan tidak satu pun meminta Anda menyebutkan subjek, karena apa yang dikonfigurasi dan apa yang teresolusi adalah properti server ini, bukan properti sesuatu yang harus Anda ketahui terlebih dahulu. Masing-masing menerima workspace_root opsional melalui input dan output standar; melalui HTTP argumen tersebut ditolak, sebagaimana dijelaskan dalam Satu proses, satu workspace.
Bersama-sama keduanya menjawab satu pertanyaan dalam dua bagian: apakah sebuah kemampuan tidak ada, atau sekadar tidak dikonfigurasi di sini. Konfigurasi menyebutkan apakah sebuah provider, importer, atau pemeriksaan tata kelola dilampirkan sama sekali; pembacaan plugin menyebutkan apakah sebuah lampiran menjangkau guest yang teresolusi, mendeskripsikan dirinya, dan menyajikan apa yang diklaimnya. Dari tempat lain mana pun di permukaan ini keduanya tampak sama, padahal keduanya menuntut langkah berikutnya yang berlawanan.
config-show melaporkan satu entri per pengaturan: field-nya, value efektifnya, dan source yang menentukannya — file konfigurasi, variabel lingkungan, flag baris perintah, atau nilai bawaan internal. Di sampingnya, layers memuat lapisan yang berkontribusi dalam urutan prioritas, dari yang terendah. source sebuah pengaturan dieja persis seperti entri yang sesuai dalam layers, sehingga keduanya dapat digabungkan secara langsung, dan pengaturan yang ditentukan oleh nilai bawaan sama sekali tidak menyebutkan lapisan, karena nilai bawaan bukan lapisan yang berkontribusi. Lapisan global adalah file yang dipilih oleh baris perintah server itu sendiri — file yang disebutkan --config saat server dimulai, jika tidak ada maka file yang disebutkan variabel lingkungan AGGREGA_CONFIG, jika tidak ada maka lokasi bawaan — sehingga pengaturan yang ditentukan file tersebut diatribusikan ke file tersebut, persis seperti aggrega config show --origin mengatribusikannya, dan flag seperti --offline yang diberikan kepada server dilaporkan sebagai flag tersebut. Tool ini tidak menerima response_format maupun ukuran halaman: pengaturan merupakan himpunan tetap yang diperhitungkan binary ini dan setiap resolusi melaporkan semuanya, sehingga ukuran jawaban mengikuti binary, bukan apa yang Anda konfigurasi.
plugin-list menjawab dalam dua bentuk yang digunakan daftar workspace, dan panggilan yang tidak menyebutkan bentuk apa pun mendapatkan ringkasan. Ringkasan adalah jumlah per grup, dan ada dua grup — embedded, guest yang dikompilasi ke dalam binary ini, yang teresolusi tanpa akses sistem file, cache, atau jaringan, dan configured, binding milik workspace sendiri. Kirim response_format: detailed untuk mendapatkan rekaman: grup setiap plugin, referensi tempat plugin itu ditemukan, tempat referensi itu di-bind, jenis, versi, commit, kemampuan yang disajikan, jenis input yang dirender, assembly batas, dan export yang dilaporkannya sendiri, kesiapannya jika ada, dan apakah plugin itu teresolusi. Rekaman dibatasi oleh limit dan offset dengan ketentuan yang sama seperti daftar entitas, dengan count, returned, dan more_remaining untuk melanjutkan. Jawaban ini memang bertambah besar sesuai apa yang Anda konfigurasi — yang bawaan bersifat tetap, binding-nya milik Anda — itulah sebabnya jawaban ini dibagi per halaman sedangkan pembacaan konfigurasi tidak.
Plugin yang gagal dilaporkan beserta kegagalannya alih-alih dihapus dari daftar. resolved menyebutkan apakah referensi tersebut menjangkau byte modul sama sekali, dan plugin yang teresolusi tetapi tidak dapat mendeskripsikan dirinya dilaporkan persis seperti itu — sehingga lampiran yang ada tetapi tidak dapat digunakan dapat dibedakan dari lampiran yang tidak pernah dibuat.
Apa yang tidak diberitahukan listener tentang host-nya
Melalui HTTP, tidak satu pun dari kedua pembacaan melaporkan nilai yang menyebutkan suatu tempat di sistem file server. Klien yang meluncurkan server berjalan di tempat server berjalan, sehingga setiap lokasi yang dapat disebutkan oleh salah satu jawaban adalah lokasi yang sudah dimiliki pemanggil tersebut dan dapat dilihatnya. Pemanggil yang menjangkau listener tidak memilih satu pun lokasi itu, tidak dapat bertindak berdasarkan pengetahuan tentangnya, dan server yang telah memublikasikannya kepada pemanggil semacam itu tidak dapat menariknya kembali. Melalui transport tersebut nilai-nilai itu tidak ada; melalui input dan output standar semuanya ada. Ini adalah aturan yang diikuti setiap jawaban di permukaan ini, sebagaimana dijelaskan dalam Apa yang dikatakan jawaban tentang sistem file server, dan kedua pembacaan ini adalah tempat aturan tersebut menjangkau paling jauh, karena sebagian besar yang dilaporkannya adalah konfigurasi yang menyebutkan tempat.
Apa yang ditahan. Dari config-show: value sebuah pengaturan jika nilai pengaturan itu sendiri adalah lokasi — alamat penyajian atau health, yang dapat berupa file socket; file sertifikat, kunci privat, atau set kunci; direktori katalog, serta direktori katalog milik sebuah Release di bawah workspace.releases, yang setiap entrinya berkunci file Release; referensi plugin; Release authoring. Juga source sebuah pengaturan jika lapisan yang menentukannya adalah file konfigurasi, karena lapisan semacam itu dinamai dengan path file itu sendiri — dan, dengan ejaan yang sama dan untuk alasan yang sama, entri file konfigurasi dalam layers. Dari plugin-list: uri sebuah plugin jika referensi tersebut sendiri merupakan path sistem file, dan teks kegagalan resolusi atau deskripsi, yang disusun dari tempat-tempat yang dicoba sehingga menyebutkan lokasi yang tidak disebutkan oleh referensi itu sendiri. Dari keduanya: workspace_root.
Apa yang dilaporkan utuh, pada kedua transport. Referensi registry, versi, commit, digest, kemampuan yang disajikan, label kesiapan, nama variabel lingkungan atau flag, dan lapisan yang bukan file. origin pada rekaman plugin adalah salah satunya: nilai ini adalah kunci konfigurasi tempat sebuah binding ditulis, atau digest yang dipin yang dibawa oleh ekstensi perintah yang terinstal, dan plugin bawaan tidak membawanya — sehingga nilainya adalah string yang sama di mana pun plugin itu dibaca. resolved adalah yang lain: apakah sebuah plugin gagal dilaporkan kepada setiap pemanggil, bahkan ketika alasannya tidak dilaporkan.
Nilai yang tidak ada selalu menyatakan bahwa nilai itu ditahan, dan itulah yang membuat jawaban dapat digunakan. Nilai yang ditahan dilaporkan sebagai tidak ada dengan tanda di sampingnya — value_withheld dan source_withheld pada pengaturan, withheld pada entri lapisan, uri_withheld dan error_withheld pada rekaman plugin, dan workspace_root_withheld pada jawaban. Pengaturan yang tidak ditetapkan siapa pun memuat nilai kosong yang menjadi tampilan bentuknya, dan tidak memuat tanda. “Server ini tidak memberi tahu Anda di mana kunci penandatanganan berada” dan “tidak ada kunci penandatanganan yang dikonfigurasi” adalah jawaban berbeda yang menuntut langkah berikutnya yang berbeda, dan pembacaan yang melaporkan keduanya secara identik tidak akan memberi tahu Anda apa pun yang dapat ditindaklanjuti. Setiap jawaban juga selalu memuat host_locations_withheld, yang menyebutkan jawaban mana dari keduanya yang sedang Anda pegang: jika tidak, jawaban tanpa tanda akan sama saja, baik aturan ini membentuknya dan tidak ada apa pun di host yang perlu ditahan, maupun aturan ini tidak pernah diterapkan. Teks yang dapat dibaca di samping field menyatakan hal yang sama dalam kata-kata.
Aturan ini adalah sebuah properti, bukan daftar nama field: sebuah nilai ditahan jika menyebutkan suatu tempat di sistem file host, siapa pun yang menetapkannya dan dari lapisan mana pun asalnya. Nilai yang kelak ditambahkan ke salah satu pembacaan tunduk pada properti yang sama.
Melalui input dan output standar, setiap kemampuan juga dapat dijangkau sebagai tool yang dinamai sesuai perintahnya — cli-config-show dan cli-plugin-list — yang menjalankan perintah tersebut dalam proses terpisah dan mengembalikan teks yang dicetaknya; melalui HTTP tool tersebut tidak ada. Dua tool yang dijelaskan di sini memuat nilai-nilainya, sehingga Anda dapat membaca apakah sebuah kemampuan dilampirkan, atau mengambil versi sebuah plugin, tanpa mengurai kembali tata letak kolom menjadi data asal tata letak itu dirender.
Menanyakan apa yang boleh dilampirkan, dan apa yang boleh terhubung ke apa
Dua tool menjawab pertanyaan yang jika tidak demikian harus ditebak oleh asisten: Features mana yang boleh dilampirkan ke sebuah node, dan ke apa sebuah node boleh terhubung. Keduanya menjalankan pencocokan label yang sama dengan yang dijalankan compiler, sehingga yang ditawarkan asisten kepada Anda adalah himpunan yang akan dicocokkan oleh build, bukan himpunan yang disimpulkan dari skema.
attach-candidates melaporkan Features yang penerapan terdeklarasinya dipenuhi oleh label sebuah node. Tunjuk node tersebut dengan tepat salah satu dari tiga cara:
node—metadata.namesebuah entitas workspace, sebagaimana dilaporkanlist-entities. Pencocokan dijalankan atas label yang dideklarasikan dokumen tersebut.graph_nodedenganrelease— sebuah node pada graf yang telah dikompilasi, dengan kunci sebagaimana graf memberinya kunci, termasuk bentuk terkualifikasi yang dibawa node yang disumbangkan oleh sub-agregat. Pencocokan dijalankan atas label final node tersebut, yaitu label yang dievaluasi oleh build.labels— sebuah himpunan label tersendiri, tanpa menyebutkan node. Bentuk ini sama sekali tidak memerlukan koordinat, sehingga jika Anda sudah memegang label sebuah node, inilah bentuk yang digunakan; bentuk ini tidak mencari apa pun dan tidak membangun ulang graf apa pun.
Jawaban memuat label yang menjadi dasar pencocokan dan dari himpunan mana di antara ketiganya label tersebut berasal, sehingga Anda dapat menjelaskan setiap kandidat — atau ketiadaannya — dari jawaban itu sendiri alih-alih menyimpulkannya ulang. Membacanya kembali dengan cara kedua adalah titik di mana gagasan Anda tentang label sebuah node dan gagasan compiler mulai berbeda.
Untuk menanyakan apa yang boleh dilampirkan ke satu koneksi yang ditarik sebuah node, tambahkan connection di samping graph_node dan release — socket dan alias-nya, sebagaimana ditulis pembuatnya. Sebuah koneksi membawa lampiran yang mengisi slot yang dideklarasikan socket-nya pada Component konsumen, sehingga jawaban kemudian juga memuat slots: setiap slot yang dideklarasikan socket tersebut, dengan selector, required, inject, sensitive, dan description-nya persis seperti yang dideklarasikan Component, serta candidates yang boleh mengisinya. Itu adalah Features yang penerapannya dipenuhi oleh label node dan yang labelnya sendiri diterima oleh selector slot tersebut — dua aturan yang diterapkan build pada lampiran semacam itu — sehingga kandidat sebuah slot selalu termasuk di antara kandidat node itu sendiri. Jika tidak ada yang boleh diisi, slots kosong dan noSlotReason menyebutkan alasannya: feature-created-connection (sebuah Feature menarik koneksi tersebut, dan tidak ada apa pun yang dilampirkan pada koneksi semacam itu), ad-hoc-socket (socket tersebut tidak dideklarasikan oleh Component) atau no-slot-declared (socket tersebut tidak mendeklarasikan slot apa pun). Jangan membaca slots yang kosong sebagai “tidak ada yang cocok”; justru itulah yang hendak disingkirkan oleh alasan tersebut, dan alasan itu tidak ada di mana pun sebuah slot ada. candidates di sampingnya tetap memiliki maknanya — apa yang boleh dilampirkan ke node itu sendiri — dan document, jika Anda mengirimkannya, tidak mengubah apa pun di sini. connection di samping node atau labels, atau yang tidak menyebutkan socket atau alias, ditolak, begitu pula koneksi yang tidak ditarik oleh node tersebut. Ini adalah jawaban yang sama dengan yang diberikan language server, dengan ketentuan yang sama.
connection-candidates melaporkan socket dependensi yang dideklarasikan sebuah entitas dan, per socket, Components workspace yang label terdeklarasinya memenuhi batasan yang dideklarasikan socket tersebut atas targetnya. Tool ini menerima metadata.name entitas dalam node. Tidak seperti attach-candidates, tool ini tidak memiliki bentuk tanpa koordinat: tidak ada bentuk himpunan label di sini, karena socket dibaca dari deklarasi entitas yang disebutkan itu sendiri.
Kedua bagiannya tidak sama lengkapnya, dan jawabannya menyebutkan mana yang mana — jangan menyajikannya sebagai satu daftar. Targetnya lengkap: itu adalah komponen yang diterima oleh batasan yang sama selama build. Socket-nya tidak lengkap, dan tidak mungkin lengkap. Konsumen boleh menciptakan koneksi tetapi hanya boleh mengonsumsi apa yang dideklarasikan produsen, sehingga pembuat dapat secara sah menulis socket yang tidak pernah dideklarasikan oleh entitas katalog, dan socket yang dideklarasikan adalah titik awal yang membantu, bukan himpunan nama yang sah. Karena itu setiap socket menyebutkan apakah socket itu declared atau ad-hoc, dan jawabannya menyebutkan apakah socket yang tidak dideklarasikan diterima sama sekali pada entitas tersebut — permukaan dependensi sebuah Component menerimanya, karena pembuat memiliki topologi aplikasinya sendiri; permukaan lampiran sebuah Feature tidak, karena lampiran ikut serta dalam topologi yang dideklarasikan Feature yang dilampiri alih-alih menyusun topologinya sendiri. Keterbukaan tersebut merupakan konsekuensi kebebasan authoring Anda, bukan kekurangan: berikan socket dengan nama yang tidak dideklarasikan entitas tersebut untuk menanyakannya.
Keduanya menjawab lalu berhenti. Tidak satu pun membuat lampiran, membuat edge, menulis ke file apa pun, atau mengusulkan teks perubahan; menyusun dan menerapkan perubahan apa pun yang menyusul adalah tugas Anda.
Keduanya mengembalikan identitas minimal yang sama dengan yang digunakan setiap jawaban lain di sini — jenis, nama, dan file sumber — dan tidak lebih. Semua hal lain yang ingin Anda tampilkan tentang sebuah entitas sudah ada dalam list-entities untuk tiga field yang sama, sehingga Anda menggabungkan kedua jawaban alih-alih membaca dua salinan yang bisa saja tidak sesuai. Keduanya menolak nama yang tidak dapat diresolusinya alih-alih menjawab dengan daftar kosong, dengan alasan yang sama seperti bagian lain permukaan ini: jawaban kosong akan melaporkan salah ketik sebagai subjek yang tidak memiliki apa pun untuk ditawarkan. Panggilan labels tidak memiliki nama yang dapat salah diketik, sehingga hasil kosong di sana berarti persis apa yang dikatakannya.
Semua yang dibaca server sebagai rujukan disajikan dari mesin ini — JSON Schema dibangun ke dalam binary dan dokumentasi dibaca dari cache bundel dokumentasi yang disimpan mesin, sebagaimana dijelaskan di bawah. Penyusunan draf dokumen awal, validasi, deskripsi, build, dan linting semuanya dijalankan terhadap workspace Anda dan cache lokal, dan tidak satu pun menjangkau registry atas inisiatifnya sendiri: render menyajikan referensi eksternal yang dipin dari penyimpanan beralamat konten dan menolak dengan halus referensi yang tidak dipin alih-alih mengambilnya, dan itulah yang membuat seluruh siklus inspeksi dan render tetap offline. Ada dua pembacaan registry yang dapat Anda minta: describe dengan referensi registry, yang mengambil satu koordinat tersebut, tidak menulis apa pun, dan melalui HTTP hanya menjangkau registry yang dikonfigurasi untuk workspace yang disajikan; dan scaffold yang dikirimi example atau list, yang memperoleh bundel dokumentasi dari registry default workspace bila mesin tidak menyimpan salinan yang diterima kebijakan tanda tangan workspace, dan memverifikasinya sebelum disimpan, sebagaimana dilakukan aggrega scaffold --example. Publikasi dan penandatanganan adalah sisi lain yang disengaja dari hal itu, dan telah dibahas di atas.
Di antara keduanya terdapat resolusi dependensi sebuah Release, yang merupakan satu-satunya hal di sini yang mengakuisisi: proses ini menjangkau registry karena diminta meresolusi dependensi berarti diminta mengambilnya. Hal ini hanya terjadi jika Anda memintanya, dan ada tepat dua cara untuk memintanya — memanggil pull, yang memang seluruh tugasnya adalah itu, atau mengirim auto_pull ke build, yang menjalankan resolusi yang sama sebagai langkah pertama build. Tidak ada hal lain yang melakukan pull atas nama Anda, dan build yang tidak Anda kirimi auto_pull tidak menjangkau registry. Satu-satunya pengaturan yang mengubah hal ini adalah auto_pull milik workspace sendiri: workspace yang dikonfigurasi seperti itu meminta setiap build di dalamnya untuk meresolusi terlebih dahulu, dari mana pun build itu dijalankan, yang dibahas di bawah.
Satu-satunya pengecualian di antara pembacaan rujukan tersebut adalah akuisisi bundel dokumentasi itu sendiri, dan hal itu terjadi terpisah dari setiap pembacaan. Bundel disimpan sekali per mesin, dalam cache yang digunakan bersama oleh setiap proyek Aggrega, satu salinan untuk setiap registry dan versi — sehingga server yang dimulai di folder tempat cache workspace tidak dapat dibuat tetap menyimpannya (lihat aggrega cache). Saat server dimulai, sebelum menjawab apa pun yang Anda kirim, server mencari di sana salinan yang diterima oleh pemeriksaan tanda tangan workspace Anda sendiri — pemeriksaan yang sama yang berlaku untuk pull bundel — dan mengambil bundel tersebut, melalui pengaturan egress yang sama dengan yang digunakan bagian lain CLI, hanya jika tidak ada salinan semacam itu. Bundel yang dicarinya adalah bundel yang dipublikasikan untuk versi aggrega yang dijalankan server, atau, jika tidak ada yang dipublikasikan untuk versi itu, bundel terbaru yang dipublikasikan untuk versi sebelumnya — pilihan yang sama dengan yang dibuat aggrega explain dan aggrega scaffold --example — dan setiap halaman yang dilayaninya, serta setiap penjelasan, dibaca dari bundel yang diperolehnya. Dengan demikian halaman-halaman sudah tersedia saat ada yang memintanya, apa pun yang kebetulan dikirim klien Anda terlebih dahulu, dan server lain, atau aggrega explain di proyek lain, menemukan salinan yang sama alih-alih mengunduhnya lagi.
Menyajikan sebuah halaman kemudian merupakan pembacaan salinan tersebut, dan tidak menjangkau registry. Sebelum sebuah halaman disajikan, tanda tangan yang disimpan di samping salinan diverifikasi lagi berdasarkan pemeriksaan workspace Anda, sehingga salinan yang diloloskan oleh pengaturan proyek lain yang lebih longgar tidak disajikan kepada Anda: jika pemeriksaan mem-pin sebuah kunci atau trust root, verifikasi tersebut berjalan offline, dan jika tidak mem-pin keduanya — pemeriksaan bawaan hub resmi adalah salah satunya — verifikasi memperoleh trust root Sigstore publik, seperti yang dilakukan pull. Workspace offline tidak dapat mengambil trust root tersebut, sehingga secara offline ia memverifikasi terhadap trust root yang ditinggalkan oleh pengambilan online sebelumnya di mesin ini dalam cache yang disimpan klien Sigstore di bawah .sigstore di direktori home Anda, betapa pun lamanya pengambilan itu terjadi, dan tidak mengambil apa pun; pada mesin yang belum pernah mengambilnya, pemeriksaan tidak dapat berjalan secara offline, salinan tidak disajikan, dan stream log menyatakannya. Verifikasi tersebut berjalan sekali untuk setiap salinan dan setiap pemeriksaan selama server berjalan, dan halaman yang dibaca setelahnya disajikan berdasarkan apa yang telah diterimanya: salinan yang diambil sejak itu, workspace yang pemeriksaannya berbeda — termasuk trust root yang dipin yang diedit di tempat — pembacaan yang dilakukan secara offline, atau pembacaan offline yang menemukan trust root berbeda yang tertinggal di mesin, diverifikasi tersendiri. Salinan yang ditolak pemeriksaan Anda diperiksa lagi pada pembacaan berikutnya, sehingga pengambilan yang sejak itu telah menerimanya tidak dibatalkan. Jika bundel tidak dapat diakuisisi, atau satu-satunya salinan adalah salinan yang ditolak pemeriksaan Anda dan pengambilan ulangnya berdasarkan pemeriksaan tersebut gagal, server tetap dimulai dan setiap permukaan lainnya berfungsi; permintaan dokumentasi menjawab not-found, dan stream log server menyebutkan alasannya.
Membangun berdasarkan konten yang sudah disematkan oleh sebuah Release
build merender sebuah Release menjadi artefaknya di dalam memori, dan sebuah render dapat meminta konten dari URL jarak jauh — misalnya skema values sebuah chart dengan referensi jarak jauh. Input eksternal dibekukan selama panggilan. Referensi yang sudah disematkan oleh lockfile Release dilayani dari penyimpanan beralamat konten, yang merupakan pembacaan konten yang sudah ada di disk, bukan pengambilan. Referensi yang tidak disematkan oleh lockfile dikesampingkan dan disebutkan namanya alih-alih diambil: yang Anda minta adalah sebuah render, dan memperoleh sebuah referensi berarti menjangkau jaringan sekaligus menulis sebuah blob ke penyimpanan sebagai efek samping dari menghasilkan byte. Pembekuan itu adalah sifat render. Resolusi adalah langkah yang memperoleh: langkah ini merender Release untuk mengetahui referensi jarak jauh mana yang diminta render tersebut, mengambilnya, dan mencatatnya dalam penulisan lockfile yang sama dengan yang memuat sematan dependensi. Jadi yang diubah oleh resolusi adalah referensi mana yang sudah disematkan saat sebuah render berjalan, tidak pernah apa yang boleh dijangkau oleh sebuah render — dan referensi yang tidak disematkan oleh resolusi mana pun dikesampingkan pada panggilan yang melakukan resolusi terlebih dahulu persis seperti pada panggilan yang tidak melakukannya.
File kembali sebagai byte yang dihasilkan oleh build sungguhan, dan dua hal bersama-sama yang membuat hal itu benar. Yang pertama adalah pembekuan di atas: referensi yang disematkan dibaca dari penyimpanan alih-alih diambil. Yang kedua adalah bahwa lockfile yang dibaca masih menggambarkan hasil resolusi Release — sehingga build memeriksanya, dan menolak lockfile yang tidak lagi cocok, persis seperti yang dilakukan aggrega build di terminal. Membaca byte yang disematkan tidak mengatakan apa pun dengan sendirinya tentang apakah itu byte yang tepat untuk dibaca.
Ketiga keadaan lockfile, agar perilakunya eksplisit. Tanpa lockfile sama sekali, build merender dari apa pun yang sudah disematkan oleh ruang kerja dan mengesampingkan setiap referensi eksternal yang tidak dapat dilayaninya, sambil menyebutkan masing-masing; jika dibiarkan, ia tidak mewajibkan lockfile dan tidak menulisnya, dan hal itu tidak berubah oleh pemeriksaan di atas — tidak ada lockfile untuk dibandingkan, jadi tidak ada yang ditolak. Dengan lockfile yang cocok, ia merender. Dengan lockfile yang tidak lagi cocok, ia menolak, dan penolakan itu menyebutkan cara mengatasinya: panggil pull dengan release yang sama dan tanpa upgrade_targets, yang merekonsiliasi lockfile dengan hasil resolusi Release saat ini. Penolakan itu juga memuat bentuk terminal dari operasi yang sama, aggrega pull --release <release>. Kedua pemanggilan mengatasinya; keduanya adalah satu operasi yang dapat dijangkau dari dua tempat, bukan dua instruksi untuk dipilih. Jika pull selesai dan penolakan itu muncul kembali, kedua panggilan melakukan resolusi atas input yang berbeda — paling sering catalog_dirs diberikan kepada yang satu dan tidak kepada yang lain, atau konfigurasi ruang kerja diedit di antara keduanya — dan penolakan itu mengatakannya: panggil keduanya dengan input yang sama.
validate dan describe yang hanya diberi release tunduk pada lockfile yang sama. Pada lockfile yang tidak lagi cocok dengan hasil resolusi Release, masing-masing menolak alih-alih menjawab, dengan teks yang memuat penghentian drift yang digunakan build untuk menolak dan cara yang sama untuk mengatasinya — sebagaimana aggrega validate --release dan aggrega inspect --closure menolak di terminal. Dengan lockfile yang cocok, atau tanpa lockfile, masing-masing menjawab seperti biasanya.
Meminta build untuk me-resolve dependensinya terlebih dahulu
Kirim auto_pull dan build melakukan resolusi sebelum merender. Build menjalankan resolusi yang sama dengan yang dijalankan pull — operasi itu sendiri, bukan operasi kedua yang ditulis untuk build, sehingga ruang kerja yang diisi oleh build dan ruang kerja yang diisi oleh panggilan pull terisi secara identik — menulis lockfile Release, lalu merender berdasarkan apa yang ditulisnya. Langkah itu menjangkau registry dan menulis, yang tidak dilakukan oleh hal lain dalam build selain write, dan write tidak menjangkau registry mana pun — jadi langkah ini nonaktif kecuali diminta.
Ini menjawab kedua penolakan di atas tanpa meninggalkan protokol. Release yang belum pernah di-resolve oleh siapa pun merender dari sematan apa pun yang kebetulan ada dan mengesampingkan sisanya; lockfile yang telah bergeser langsung menghentikan build. Mengirim auto_pull melakukan resolusi terlebih dahulu dan merender berdasarkan lockfile yang diturunkan dari closure yang menjadi pokok build ini, sehingga kedua kasus kembali sebagai render alih-alih sebagai sesuatu yang harus diperbaiki. Jika Anda menginginkan resolusi dan render sebagai langkah terpisah — untuk membaca apa yang disematkan sebelum merendernya — panggil pull lalu build, yang merupakan dua operasi yang sama dengan satu kali pemeriksaan di antaranya.
Satu panggilan merender Release satu kali. Mengetahui referensi jarak jauh mana yang digunakan sebuah Release itu sendiri adalah sebuah render, jadi resolusi sudah merender Release yang menjadi pokok build — berdasarkan sematan yang baru saja ditulisnya, dengan setiap pemeriksaan yang dijalankan build. Build dijawab dari render itu alih-alih mengulanginya, itulah sebabnya mengirim auto_pull membutuhkan biaya satu resolusi dan bukan render kedua. Hanya render yang selesai yang digunakan dengan cara itu: jika resolusi telah menyematkan dependensinya tetapi tidak dapat menyelesaikan penemuan referensi eksternal, build merender sendiri berdasarkan sematan yang memang tertulis, dan referensi yang tidak disematkan kemudian menghentikannya dengan menyebut namanya alih-alih kembali sebagai daftar file yang kurang dari apa yang dihasilkan build.
Apa yang kembali menyatakan apa yang di-resolve. Build yang melakukan pengisian membawa dependency_resolution pada jawabannya, dalam bentuk yang digunakan pull untuk menjawab: lockfile yang ditulisnya, setiap referensi yang dijangkau resolusi beserta versi hasil resolusi masing-masing dan dari mana resolusi build ini mengambilnya, jumlah yang dimuat lockfile sesudahnya, dan laporan resolusi tentang dirinya sendiri baris demi baris. Build yang tidak melakukan pengisian sama sekali tidak membawa field tersebut, jadi keberadaannya adalah cara Anda membedakan keduanya tanpa membaca disk. File yang dirender dilaporkan persis seperti untuk build lainnya, dan tetap dikembalikan di dalam memori kecuali panggilan itu juga dikirimi write — resolusi menulis lockfile dan cache artefak, tidak pernah sebuah artefak.
Ruang kerja dapat memintanya secara tetap, dan panggilan tidak dapat menonaktifkannya. Pengaturan auto_pull milik ruang kerja mengaktifkan langkah yang sama untuk setiap build di ruang kerja tersebut, dan auto_pull pada sebuah panggilan menambah pengaturan itu alih-alih menimpanya: salah satunya sudah cukup, dan tidak ada argumen yang menekan resolusi yang diminta ruang kerja. Itu adalah cara yang sama dengan cara pengaturan tersebut dan aggrega build --auto-pull digabungkan di terminal, sehingga satu ruang kerja menjawab dengan cara yang sama melalui permukaan mana pun build tiba.
Pengesampingan dilaporkan alih-alih diserap, dan dengan penyedia yang dibawa biner ini, pengesampingan menghentikan render: penyedia yang meminta referensi tersebut mengembalikan penolakan, sehingga panggilan menjawab dengan kegagalan itu dan tidak mengembalikan file apa pun. Referensi tersebut disebutkan di tempat pembaca dapat menindaklanjutinya, di samping perintah yang menyematkannya: aggrega pull --release <path>. Penyematan yang sama dapat dijangkau di permukaan ini sebagai tool pull, yang dijelaskan di bawah dalam Me-resolve apa yang menjadi dependensi sebuah Release, sehingga asisten yang menemui penolakan ini dapat menindaklanjutinya tanpa meninggalkan protokol. Render yang sepenuhnya tersemat tidak mengatakan apa pun tentang semua ini. Lihat aggrega pull untuk apa yang diambil dan dicatat oleh penyematan, dan aggrega build, tempat referensi yang tidak disematkan dilaporkan dan menghentikan proses dengan cara yang sama.
Menulis artefak di tempat aggrega build menulisnya
Kirim write dan render yang selesai juga ditulis ke dist/ di root ruang kerja, tempat aggrega build menulisnya. Direktori tersebut adalah direktori yang disusun baris perintah di bawah root ruang kerja yang sama, dan penulisannya adalah penulisan yang dilakukannya, sehingga untuk satu Release di satu ruang kerja, aggrega build, aggrega/build milik language server yang tidak menyebutkan outputParent, dan panggilan ini menulis satu pohon, byte demi byte, dan menamai direktori itu dengan cara yang sama — baris penutup perintah, outputDirectory milik language server, dan output_dir jawaban ini. dist yang merupakan tautan yang mengarah ke luar ruang kerja ditolak sebelum apa pun di dalamnya dihapus atau ditulis, seperti di terminal. Jika dihilangkan, yang merupakan nilai bawaan, artefak dikembalikan di dalam memori dan tidak ada yang ditulis.
Root ruang kerja adalah milik panggilan itu sendiri. Melalui input dan output standar, root tersebut adalah root ruang kerja yang di-resolve oleh panggilan, sebagaimana dijelaskan dalam Di ruang kerja mana sebuah panggilan dijawab: root yang disebutkan oleh workspace_root, jika tidak ada maka root yang digunakan saat server diluncurkan, jika tidak ada maka ruang kerja yang ditemukan dari direktori tempat server dijalankan — dan, jika sebuah Release yang disebutkan dengan jalur absolut memindahkan panggilan ke ruang kerja milik Release tersebut, root ruang kerja itu. Itu adalah root tempat aggrega build menulis untuk Release yang sama dan root bernama yang sama, sehingga folder tempat server kebetulan berjalan menerima dist hanya jika folder itu adalah root yang di-resolve oleh panggilan, seperti yang akan terjadi di terminal yang dibuka di sana. Melalui HTTP, root tersebut adalah ruang kerja yang dilayani server, dan tidak ada yang ditulis di luarnya.
Penulisan menjangkau ruang kerja, sehingga melalui HTTP diperlukan aggrega:workspace-write. Panggilan yang dikirimi write menjangkau ruang kerja untuk panggilan tersebut, persis seperti build yang me-resolve dependensinya terlebih dahulu: kredensial yang hanya membawa aggrega:read dijawab dengan 403 yang menyebutkan aggrega:workspace-write, dan tidak ada yang ditulis, dan server yang mcp.deny_reach-nya menyebutkan workspace menolak panggilan dengan menyebutkan pengaturan tersebut. Tool ini tetap ada di daftar tool setiap pemanggil, dan build yang tidak dikirimi write tetap tersedia bagi pemanggil dengan cakupan baca.
Penulisan dilakukan paling akhir. Dengan auto_pull juga, panggilan melakukan resolusi, merender, lalu menulis, dalam urutan itu. Panggilan yang ditolak pada titik mana pun sebelumnya — Release-nya, ruang kerjanya, sebuah direktori katalog, resolusi, render — tidak menulis artefak apa pun.
Jawaban menyebutkan apa yang ditulis. output_dir adalah direktorinya — lengkap melalui input dan output standar, dist melalui HTTP — dan files mencantumkan setiap file yang ditulis, relatif terhadapnya, beserta isinya pada response_format: detailed dan hanya jalurnya pada concise; teksnya menyatakan berapa banyak file yang ditulis dan di mana. Panggilan yang tidak dikirimi write tidak membawa output_dir, jadi ketiadaannya adalah cara Anda mengetahui bahwa tidak ada yang ditulis. Penulisan yang gagal setelah render selesai — misalnya ke root ruang kerja yang tidak boleh ditulisi siapa pun — menjawab sebagai kegagalan yang menyebutkan direktori dan penyebabnya, dan tidak mencantumkan file apa pun sebagai tertulis: sebagian penulisan mungkin ada di disk, dan menyebut file yang dirender sebagai tertulis akan mengklaim lebih dari yang terjadi.
Tidak ada argumen yang menyebutkan direktori, dan tidak ada yang meminta trace. Ke mana artefak pergi ditentukan oleh ruang kerja yang di-resolve oleh panggilan, tidak pernah oleh panggilan, dan build yang ditulis dari sini tidak meninggalkan direktori .trace di samping output-nya; build dengan trace adalah aggrega build --trace.
Apa yang disampaikan build selain file-filenya
Build membawa setiap peringatan yang dimunculkannya, pada jawaban itu sendiri. Ini adalah temuan yang dicetak aggrega build saat bekerja — nama yang berjarak satu suntingan dari nama yang dideklarasikan, parameter yang tidak dibaca oleh apa pun, target yang tidak dapat memenuhi field yang ditulis penulis, putusan tata kelola yang tidak menghentikan, direktori batas yang diwarisi sebuah Release dari Release yang diperluasnya dan yang ter-resolve ke jalur yang sama, properti yang dideklarasikan oleh sebuah Component atau Feature yang dijangkau Release di kedua pilar values dan infra-nya. Tidak satu pun dari temuan itu mengubah hasilnya: build yang membawa peringatan tetap berhasil, dan file yang dikembalikannya adalah file yang dihasilkannya. Temuan tersebut tiba dalam urutan yang dicetak oleh terminal, sehingga pembaca yang membandingkan keduanya menemukan satu urutan, bukan dua: pertama semua yang dimunculkan render, dalam urutan kemunculannya, lalu temuan tentang Release dan apa yang dijangkaunya, yang dicetak aggrega build setelah render kembali, dan terakhir, pada build yang dikirimi write, peringatan yang menyebutkan setiap file yang ditemukan penulisan di samping file miliknya sendiri yang tidak ditulisnya, yang dibiarkannya di tempat — peringatan yang dicetak aggrega build setelah file-filenya ditulis (File yang tidak ditulis oleh build).
Temuan tersebut ada pada jawaban dan bukan hanya pada teks ringkasan karena asisten yang mengendalikan permukaan ini tidak membaca terminal, dan temuan yang tidak diberitahukan kepada siapa pun adalah temuan yang tidak pernah dibuat. Masing-masing membawa severity — warn untuk sesuatu yang memerlukan perhatian, info untuk observasi yang dicatat — dan message; code jika kelasnya menetapkan satu, sehingga Anda dapat bereaksi terhadap kondisi tertentu tanpa mencocokkan teks; dan key_path yang menyebutkan kunci dalam dokumen yang ditulis penulis yang menjadi pokok temuan tersebut, jika memang menyangkut satu kunci. Temuan tentang bentuk topologi yang di-deploy tidak menyebutkan kunci, karena koordinatnya adalah milik deployment, bukan milik dokumen, dan sebagai gantinya menyatakan dalam pesannya apa yang dibahasnya.
Dua jenis temuan yang dicetak terminal mencapai jawaban ini di tempat selain advisories, karena masing-masing memiliki tempat yang menyatakan lebih banyak. Penanda deprecation yang tercatat ada di deprecations, baik yang dicatat lockfile terhadap referensi yang di-pin maupun yang dicatat catatan kepercayaan plugin di sampingnya terhadap plugin yang dilampirkan dalam peran yang mengembalikan putusan terima-atau-tolak. describe atas sebuah Release menyebutkan himpunan yang sama dalam deprecations miliknya sendiri, dan validate atas sebuah Release menyebutkannya di antara notices-nya, masing-masing membiarkan putusan apa adanya; catatan kepercayaan yang ada tetapi tidak dapat dibaca membuat kedua panggilan tersebut ditolak alih-alih dianggap sebagai catatan yang tidak mencatat apa pun. Induk yang diwarisi sebuah entitas dan yang tidak dapat di-resolve menghentikan build, sehingga disebutkan dalam teks penolakan alih-alih dicantumkan sebagai temuan yang tidak mengubah apa pun. Satu jenis dibatasi oleh apa yang dimuat tool ini, bukan oleh apa yang dibawa jawabannya: aggrega build memuat setiap direktori katalog yang dikonfigurasi sebelum me-resolve sebuah Release, dan pemberitahuan tentang bentuk katalog yang sudah usang akan berasal dari pemuatan itu, sedangkan tool ini hanya membaca apa yang dijangkau Release dan tidak melakukan pemuatan semacam itu, sehingga tidak melaporkan pemberitahuan semacam itu. Saat ini tidak ada build yang memunculkannya, jadi keduanya melaporkan temuan yang sama.
Release yang tidak memunculkan apa pun tidak menyatakan apa pun: kuncinya tidak ada alih-alih ada dan kosong, sehingga keberadaannya saja sudah memberi tahu Anda bahwa ada sesuatu untuk dibaca.
Apa yang dikembalikan build yang ditolak
Build yang menolak menjawab dalam field yang sama dengan build yang berhasil, diisi sejauh proses itu berjalan. Build tersebut kembali dengan tanda kegagalan dengan koreksi sebagai teksnya, dan payload terstruktur berada di samping teks itu alih-alih digantikan olehnya. Penolakan yang dimunculkan saat Release dirender dibaca dalam kata-kata compiler, seperti yang dijelaskan di bawah dalam Penolakan yang dimunculkan saat merender, dan menambahkan satu field miliknya sendiri. Peringatan ada di dalamnya: fase yang berjalan memunculkan apa yang dimunculkannya, dan itulah temuan yang harus Anda tindak lanjuti untuk melewati penolakan, sehingga temuan tersebut tiba sebagai entri yang dapat Anda cocokkan alih-alih sebagai prosa yang harus Anda urai. deprecations dan declined_external_inputs ada di dalamnya karena alasan yang sama — penanda yang tercatat dilaporkan karena sebuah penanda telah dicatat, dan referensi yang dikesampingkan karena sebuah referensi telah dikesampingkan, dan tidak satu pun dari fakta itu merupakan akibat dari cara proses berakhir.
files tidak melaporkan apa pun pada penolakan, dan bukan field untuk membaca hasilnya. Tidak ada yang dihasilkan, jadi tidak ada artefak untuk disebutkan. Jangan membuat percabangan berdasarkan ada tidaknya kunci tersebut: kunci itu dilaporkan dalam kedua kasus, dan files yang kosong tidak dapat dengan sendirinya membedakan build yang menolak dari build yang berjalan dan tidak menghasilkan apa pun. Bacalah tanda kegagalan pada hasil — itulah pembeda milik protokol itu sendiri — dan bacalah files sebagaimana adanya, yaitu daftar apa yang dirender, dan juga ditulis jika panggilan dikirimi write.
Yang membatasi peringatan pada penolakan adalah sejauh mana proses berjalan, bukan apa yang mampu dibawa jawaban. Penolakan dari pemeriksaan yang berjalan sebelum Release di-resolve — entri tersemat di cache tidak lagi cocok dengan digest yang tercatat untuknya dan tidak ada direktori katalog yang memuat byte yang disematkan, atau dependensi Release tidak dapat di-resolve — tidak melaporkan peringatan apa pun, karena belum ada yang dimunculkan. Temuan tentang cara sebuah Release tersusun dengan Release yang diperluasnya dimunculkan saat Release itu di-resolve, sebelum setiap pemeriksaan berikutnya, sehingga setiap penolakan sesudahnya membawanya: Manifest memetakan sebuah tipe ke resep yang tidak mengimplementasikannya, entitas yang dijangkau Release tidak memenuhi skemanya, lockfile tidak lagi cocok dengan hasil resolusi Release. Temuan milik render sendiri dimunculkan selama render berjalan, sehingga penolakan dari salah satu pemeriksaan sebelumnya itu tidak membawa satu pun darinya, dan penolakan dari render membawa semua yang dimunculkan sebelumnya. Jadi bacalah advisories pada penolakan persis seperti Anda membacanya pada keberhasilan: apa yang ditemukan proses ini, dalam urutan yang dicetak terminal.
Penolakan karena sebuah entitas mewarisi dari induk yang tidak dapat di-resolve menyebutkan setiap pewarisan semacam itu dalam teksnya, dengan kata-kata yang dicetak aggrega build untuknya, sehingga Anda tahu mana yang harus diperbaiki. Detail itu adalah alasan build berhenti, itulah sebabnya detail itu ada di teks alih-alih di antara temuan yang tidak mengubah apa pun; temuan komposisi yang dimunculkan sebelumnya ada di advisories seperti pada penolakan lain sesudahnya.
Direktori katalog yang dibaca Release dan tidak dapat ditelusuri ditolak sebelum apa pun ditulis, sebagaimana aggrega build menolaknya. Itu adalah direktori yang disebutkan panggilan dalam catalog_dirs dan tidak ada, sebagaimana aggrega build menolak direktori --catalog yang tidak ada, atau direktori yang ada tetapi tidak dapat dibaca. aggrega build memuat setiap direktori yang dibaca Release sebelum me-resolve Release tersebut, dan berhenti pada direktori yang tidak dapat ditelusurinya; build menelusuri direktori yang sama terlebih dahulu, tanpa membaca dokumen apa pun di dalamnya, sebelum resolusi dependensi apa pun dan sebelum render — sehingga build yang dikirimi auto_pull tidak menulis lockfile, dan tidak ada yang dirender. Teksnya menyebutkan direktori tersebut sebagaimana baris perintah melaporkannya, dalam satu baris: direktori, catalog load, dan alasan yang diberikan sistem file. Payload-nya menyebutkan Release, dengan files yang kosong dan tanpa temuan, karena belum ada yang berjalan. Direktori yang dicantumkan konfigurasi ruang kerja yang ternyata bukan direktori — misalnya tidak ada apa pun di sana — ditolak sebelum penelusuran itu, dalam bentuk yang sama, dengan teks yang membawa penolakan yang diberikan aggrega build untuknya, menyebutkan entri tersebut serta file konfigurasi dan baris yang mencantumkannya (Dari mana entitas lokal dibaca). Direktori katalog yang memuat tautan yang mengarah ke luar direktori tempat pembacaannya harus tetap berada ditolak pada saat yang sama, tanpa ada yang ditulis, dengan teks yang menyebutkan tautan tersebut dan ke mana arahnya — aggrega build menolaknya dengan cara yang sama.
Contoh konkret, agar kedua bagian itu jelas. Release yang mendeklarasikan parameter yang tidak dibaca oleh referensi mana pun, dan yang render-nya kemudian tidak dapat selesai, kembali sebagai kegagalan yang teksnya membawa penolakan render dan payload-nya membawa peringatan parameter yang tidak dibaca beserta severity, message, code, dan key_path-nya — entri yang sama, dengan nilai yang sama, yang dilaporkan Release yang sama pada jawaban ketika render memang selesai — di samping entri refusal untuk apa yang menghentikan render. Release yang memperluas Release lain dan mewarisi direktori batas yang tidak memuat variabel template, yang Manifest-nya memetakan sebuah tipe ke resep yang tidak mengimplementasikannya, kembali sebagai penolakan itu dengan satu entri advisories per direktori yang diwarisi, masing-masing dengan code inherited-boundary-directory-is-literal. Release yang dependensinya tidak dapat di-resolve, di ruang kerja yang direktori katalog tercantumnya semuanya ada, kembali sebagai kegagalan tanpa kunci advisories sama sekali, karena belum ada yang dimunculkan ketika Release itu berhenti.
Penolakan yang dimunculkan saat merender
Release yang ditolak compiler saat merender — sebuah Workload yang menyebutkan slot yang tidak dideklarasikan oleh Component-nya, asersi yang gagal, template yang tidak dapat dievaluasi — kembali dengan penolakan dalam kata-kata compiler dan dengan setiap penyebab di bawahnya, kata-kata yang dikembalikan cli-build untuk Release yang sama: node yang sedang dirender, lalu apa di dalamnya yang menolak. Jika penolakan menyebutkan kondisi yang terdaftar, teks tersebut menambahkan nama kondisi itu — kode pendek dan kode deskriptif untuk dicocokkan — seperti yang akan dilakukan explain-error. Teks dibuka dengan menyatakan tahap mana yang menolak: The build failed during rendering; nothing was written to disk. untuk penolakan yang dimunculkan render, dan The build refused before rendering anything; nothing was written to disk. untuk penolakan yang dimunculkan proses compiler sebelum apa pun dirender — komposisi graf yang menjadi dasar kerja render menolak, atau asersi yang dideklarasikan oleh sebuah Component atau Feature.
Payload membawa penolakan yang sama sebagai satu entri, refusal, sehingga pemanggil yang harus mengubah sebuah dokumen dapat membaca dokumen yang mana, dan di mana, tanpa mengurai kalimatnya:
file— dokumen yang ditunjuk penolakan: Recipe sebuah Workload, Recipe atau FeatureRecipe yang mendeklarasikan asersi yang gagal, Release atau Aggregate yang menulis entri yang ditolak komposisi graf, atau Aggregate milik Release untuk penolakan yang tidak menunjuk dokumen apa pun.key_path— kunci di dokumen itu, jika penolakan menyebutkan satu:.spec.workloaduntuk penolakan tentang sebuah Workload, kunci asersi itu sendiri di bawah.spec.assertionsuntuk asersi yang gagal, kunci entri itu sendiri untuk penolakan sebuah entri. Penolakan tentang sebuah Workload ditempatkan pada kunciworkload-nya dan tidak lebih rinci, karena Workload yang dinilai sebuah pemeriksaan adalah apa yang dihasilkan template-nya, dan template menulis baris yang tidak pernah ditulis penulisnya; jalur yang disebutkan penolakan di dalam Workload yang dirender itu tetap berada dimessage-nya.linedancolumn— posisi kunci tersebut, dihitung mulai dari satu, kolom dalam satuan UTF-16. Tidak ada jika penolakan tidak menyebutkan kunci atau dokumen tidak memuatnya: posisi hanya diberikan jika ditemukan.severity—halt, tingkat keparahan temuan yang menghentikan build.codedanshort_code— dua pengenal kondisi, jika penolakan menyebutkan kondisi yang terdaftar.message— teks penolakan, persis seperti yang muncul dalam teks jawaban.findings— hanya ada jika penolakan menggabungkan beberapa temuan, seperti yang dilakukan komposisi graf dengan setiap pelanggaran yang ditemukannya: satu entri per temuan, dalam urutan yang dinyatakan penolakan, masing-masing dalam bentuk yang sama ini — denganfile,key_path,line,column,severity,code,short_code, danmessagemiliknya sendiri. Field milik penolakan itu sendiri kemudian menyebutkan ke mana temuan pertamanya menunjuk, danmessage-nya membawa setiap temuan, seperti halnya teks; baris perintah mencetak setiap temuan sebagai diagnostik tersendiri.
Entri ini ada setiap kali proses compiler itu sendiri menolak — saat merender, atau sebelum merender: pada komposisi graf, atau pada asersi yang dideklarasikan oleh sebuah Component atau Feature, yang tidak menyebutkan dokumen apa pun, sehingga entrinya menyebutkan Aggregate. Build yang berhasil tidak membawanya, begitu pula build yang ditolak oleh pemeriksaan yang berjalan sebelum compiler dimulai — lockfile, pemetaan Manifest, dependensi Release — yang penolakannya hanya berupa teks. Nilai yang dideklarasikan penulis sebagai sensitif ditahan dari penolakan di tempat compiler memunculkannya, sehingga entri dan teks membawa apa yang dibawa cli-build dan terminal — lihat apa yang dinyatakan penolakan tentang nilai yang dideklarasikan.
Me-resolve apa yang menjadi dependensi sebuah Release
pull me-resolve dependensi katalog dan sumber sebuah Release ke dalam cache lokal dan menulis lockfile Release tersebut. Tool ini ada di permukaan ini karena alasan yang layak dinyatakan: kedua penolakan di atas — render yang mengesampingkan referensi eksternal yang tidak disematkan, dan build yang berhenti karena lockfile tidak lagi cocok dengan hasil resolusi Release — sama-sama dijawab dengan penyematan, dan asisten yang harus meminta Anda menjalankan perintah tidak memiliki cara untuk menjawabnya sendiri. Bacalah Apa yang dapat dilakukan asisten tanpa bertanya kepada Anda terlebih dahulu untuk mengetahui apa yang ditulisnya dan seberapa jauh jangkauannya.
Berikan release, jalur Release, absolut atau relatif terhadap root ruang kerja — kontrak yang sama yang digunakan setiap argumen jalur lain di sini. workspace_root dan catalog_dirs menimpa penemuan ruang kerja dan katalog persis seperti pada build. Keduanya berlaku pada server yang dijangkau melalui input dan output standar; melalui HTTPS kedua argumen itu ditolak dan jalurnya harus ter-resolve di dalam ruang kerja yang dilayani proses, sebagaimana dijelaskan dalam Satu proses, satu ruang kerja.
Secara bawaan, tool ini merekonsiliasi alih-alih me-resolve ulang. Sematan yang sudah dicatat lockfile dihormati dan diambil pada versi tersebut, dan ditolak alih-alih disematkan ulang secara diam-diam jika registry tidak lagi menyajikan byte tersebut. Referensi tanpa sematan — yang baru ditambahkan, atau dihapus dari lockfile secara manual — di-resolve dari awal dan ditambahkan. Referensi yang tidak lagi termasuk dependensi yang di-resolve dipangkas. Dengan demikian, kumpulan dependensi yang tidak berubah membiarkan file identik byte demi byte, termasuk stempel waktu yang tercatat, sehingga panggilan yang tidak mengubah sematan apa pun tidak menghasilkan diff bagi siapa pun yang meninjau ruang kerja sesudahnya.
verify membandingkan, dan membiarkan lockfile apa adanya. Tool ini memeriksa lockfile yang tercatat terhadap resolusi yang akan dilakukan panggilan rekonsiliasi di atas saat ini, dengan menghormati sematan yang tercatat persis seperti panggilan itu, dan kembali sebagai kegagalan jika terjadi pergeseran, atau jika tidak ada lockfile untuk dibandingkan — jadi itulah cara asisten mengetahui apakah penyematan diperlukan sebelum apa pun menulis ulang lockfile. Tidak ada yang dicatat panggilan itu yang ditulis — bukan lockfile, bukan identitas plugin yang dicatat di sampingnya, bukan entity.lock — sementara cache konten dibaca dan diisi persis seperti panggilan itu membaca dan mengisinya. Tool ini juga melaporkan toolchain yang dicatat lockfile: versi compiler yang menulis file tersebut dan versi setiap plugin inti yang dibawa compiler itu. Hal itu dilaporkan untuk audit dan tidak pernah dibandingkan dengan biner yang sedang berjalan, karena toolchain bukan bagian dari apa yang disematkan lockfile dan memeriksanya akan menyematkan compiler secara tidak langsung — perbedaan toolchain bukanlah pergeseran.
upgrade_targets me-resolve ulang referensi yang Anda sebutkan, dan tidak ada yang lain. Berikan satu atau beberapa URI entitas dalam bentuk tertulis polos — core/database, bukan bentuk berversi. Setiap sematan yang disebutkan dibuang dan di-resolve ulang ke versi tertinggi yang tersedia, sementara setiap sematan lain dan input eksternal yang tercatat dipertahankan tanpa perubahan. URI yang tidak cocok dengan sematan yang tercatat maupun lampiran yang dikonfigurasi ditolak alih-alih diabaikan.
Dengan sengaja tidak ada argumen yang me-resolve ulang semuanya sekaligus. Baris perintah memiliki bentuk itu, dan bentuk itu membuang seluruh lockfile sebelum me-resolve ulang dari keadaan registry saat ini. Di permukaan ini argumen tersebut tidak ada, sehingga panggilan itu sama sekali tidak dapat disusun alih-alih diterima lalu ditolak: tidak ada yang mengamati aliran protokol, jadi pembuangan menyeluruh tidak memiliki siapa pun untuk mengonfirmasinya. Jika Anda menginginkannya, dan hanya melalui input dan output standar, cli-pull menjalankan perintah tersebut, dan itulah permukaan tempat seseorang hadir; pemanggil yang menjangkau server ini melalui HTTP menjalankannya di terminal pada host sebagai gantinya. verify tidak dapat digabungkan dengan upgrade_targets — yang satu membiarkan lockfile apa adanya dan yang lain menulisnya ulang — maupun dengan pin_sources, apa pun nilainya: argumen itu menentukan apakah resolusi mencatat sematan yang belum ada di entity.lock atau menolak karenanya, dan perbandingan tidak menulis entity.lock, sehingga tidak akan melakukan keduanya. Panggilan yang mengirim salah satu dari kedua pasangan itu ditolak sebelum apa pun di-resolve, dengan kalimat yang menyebutkan pasangan tersebut. Skema yang diumumkan tool ini tidak menyatakan kedua pengecualian ini, karena klien yang menampilkan salah satunya dapat membacanya sebagai keharusan untuk mengirim verify; penolakan adalah tempat klien mengetahuinya. Baris perintah dan daemon menolak pasangan yang sama.
Hasilnya menyebutkan apa yang di-resolve, bukan sekadar bahwa sesuatu telah di-resolve. Hasil itu membawa lockfile yang ditulisnya atau yang menjadi pembandingnya; resolved, setiap referensi yang dijangkau resolusi beserta versi hasil resolusi masing-masing, jenis yang ditulis penulis jika resolusi mencatatnya, dan source-nya — dari mana proses ini mengambil referensi tersebut, dengan kata yang dicetak aggrega pull --detail untuk resolusi yang sama: fetched-fresh, cache-reuse, local, in-binary, atau external; jumlah artefak sumber, input eksternal, dan identitas plugin tepercaya yang dimuat lockfile sesudahnya; dan diagnostics, laporan resolusi tentang dirinya sendiri dalam urutan kemunculan setiap baris — sematan mana yang digunakan ulang, tanda tangan mana yang diperiksa, versi mana yang dilewati karena ditarik. Baris-baris itu mencapai terminal ketika Anda menjalankan perintah; di sini baris-baris itu ada di jawaban, karena pemanggil yang tidak membaca terminal tidak memiliki cara lain untuk menerimanya. verified hanya ada pada perbandingan, jadi ketiadaannya adalah cara Anda membedakan proses yang menulis dari proses yang hanya membandingkan. source menggambarkan proses ini di mesin ini, sehingga lockfile tidak mencatatnya, dan describe, yang melaporkan dependensi sebuah Release, tidak menyebutkannya.
Penolakan menjawab dalam field yang sama, diisi sejauh proses berjalan. Setelah resolusi dihitung, resolved dibawa apa pun putusannya — terutama putusan pergeseran, karena itulah penolakan yang mengharuskan pemanggil memutuskan apa yang akan diubah. Penolakan sebelum titik itu, seperti jalur Release yang tidak dapat di-resolve, membawa koreksi sebagai teksnya dan tidak membawa resolusi, karena tidak ada resolusi untuk dibawa.
Jika sematan sudah lengkap dan input eksternal belum, panggilan tetap berhasil dan menyatakannya. Mengetahui input eksternal mana yang digunakan sebuah Release adalah sebuah render, dan render dapat gagal setelah sematan dependensi sudah benar dan ada di disk. Melaporkan seluruh panggilan sebagai gagal akan menyuruh Anda mengulang pekerjaan yang sudah benar, jadi incomplete_external_inputs ditetapkan pada hasil yang berhasil sebagai gantinya, dengan menyebutkan apa yang terhenti: sematan dependensi sudah lengkap, sematan input eksternal mungkin belum.
Ini adalah tool paling lambat di sini, dan rekonsiliasi tanpa perubahan bukanlah jalur cepat. Resolusi membayar biaya penuhnya untuk memastikan bahwa kumpulan dependensi tidak berubah, sehingga panggilan yang tidak menulis ulang apa pun memakan biaya yang sama dengan resolusi pertama — pada Release kecil, hitungan detik alih-alih milidetik, dan bertambah seiring ukuran kumpulan dependensi. verify adalah bentuk yang lebih murah dari keduanya, karena perbandingan melewati penelusuran sumber per komponen yang dilakukan proses penulisan. Jika klien Anda menerapkan batas waktu per panggilan, inilah tool yang perlu diperiksa terhadapnya. Meminta diberi tahu tentang kemajuannya, di bawah, berarti sesuatu tiba selama panggilan berjalan alih-alih tidak ada apa pun sampai panggilan berakhir — yang menjawab batas waktu menganggur di klien Anda, atau di apa pun yang berada di antara Anda dan server yang dijangkau melalui HTTP, tetapi tidak menjawab batas atas total durasi satu panggilan.
Entitas yang entity.lock-nya tidak mencatat sematan untuk input yang dibacanya menolak pull, dan penolakan itu menyebutkan langkah yang mencatatnya. Recipe atau FeatureRecipe yang dibangun Release dari direktori katalog Anda dan yang membaca sumber jarak jauh yang ditulis lengkap, atau mengimpor file melalui artefaknya, diharapkan sudah membawa sematan tersebut di sampingnya — penulisnya mencatatnya dengan pin, di bawah. pin_sources meminta panggilan ini menjalankan langkah itu atas nama penulis pada setiap entitas semacam itu alih-alih menolak, dengan menulis entity.lock di samping masing-masing; itu adalah langkah yang sama dengan yang dijalankan tool pin, dan menulis byte yang sama. Jika dihilangkan, pin_sources_at_pull milik ruang kerja yang menentukan; jika dikirim, argumen ini menentukan ke arah mana pun, sehingga pin_sources: false menolak bahkan di ruang kerja yang dikonfigurasi untuk menyematkan. Entitas yang dijangkau resolusi di cache alih-alih di salah satu direktori katalog Anda tidak memiliki tempat yang dapat ditulisi di sini dan tidak pernah disematkan oleh panggilan ini.
Menyematkan input milik sebuah entitas
pin mencatat, di entity.lock di samping sebuah Recipe atau FeatureRecipe, sematan konten untuk setiap input yang dibaca entitas dari luar dokumennya sendiri: sumber jarak jauh yang koordinatnya ditulis lengkap, dan file yang diimpor oleh entri artefak. Itu adalah langkah yang sama dengan yang dijalankan aggrega pin di terminal, dan lock yang ditulisnya identik byte demi byte dengan yang ditulis perintah tersebut. Berikan entity, dokumen entitas, absolut atau relatif terhadap root ruang kerja berdasarkan kontrak yang sama dengan setiap argumen jalur lain di sini; melalui HTTPS jalur itu harus ter-resolve di dalam ruang kerja yang dilayani proses.
Tidak ada Release yang disebutkan, karena tidak ada yang diperlukan. Sumber yang koordinatnya tidak memuat template menyebutkan satu artefak untuk setiap Release yang menggunakan entitas tersebut, sehingga langkah ini me-resolve dan menyematkannya tanpa apa pun yang disediakan Release. Sumber yang koordinatnya berasal dari template tidak disematkan di sini: artefak mana yang disebutkannya ditentukan oleh setiap Release, dan pull menyematkan setiap identitas hasil resolusinya di lockfile Release tersebut.
Hasilnya menyatakan apa yang dilakukan langkah ini terhadap lock. Hasil itu membawa entity, kind dan name-nya, serta pinnable, yang bernilai false untuk jenis yang tidak membaca apa pun yang dicatat lock — sebuah Component atau Feature — dalam hal ini tidak ada apa pun di samping entitas yang disentuh dan field lainnya tidak ada. Jika tidak, hasil itu membawa lock yang ditulisnya, changed, yang bernilai false jika lock sudah mencatat setiap sematan dan dibiarkan identik byte demi byte, removed jika entitas kini tidak membaca apa pun yang dicatat lock dan lock-nya dihapus, dan pins, satu entri per kelas sematan beserta jumlah yang dimuat lock sesudahnya. dry_run menjawab dengan lock yang akan ditulis langkah ini sebagai content dan tidak menulis apa pun di samping entitas; cache konten tetap terisi, karena input di-resolve persis seperti sebaliknya.
Langkah ini menulis di dalam ruang kerja dan menjangkau host yang disebutkan oleh sumber entitas — repositori chart, host Git, sebuah URL — sehingga melalui HTTP langkah ini diizinkan bagi kredensial yang membawa cakupan yang mengizinkan pull, dan ditolak bagi kredensial yang hanya dapat membaca. Melalui input dan output standar, kemampuan yang sama juga dapat dijangkau sebagai cli-pin, yang menjalankan perintah tersebut; melalui HTTP tool itu tidak ada.
Diberi tahu tentang kemajuan panggilan yang lama
Panggilan melaporkan kemajuannya jika Anda meminta untuk diberi tahu, dan memintanya cukup dengan satu field. Letakkan progressToken di _meta panggilan — sebuah string atau angka, sesuai pilihan Anda. Token itu kembali pada setiap laporan persis seperti yang Anda tulis, dan itulah satu-satunya hal dalam laporan yang merujuk kembali ke panggilan Anda: laporan tidak menjawab apa pun, sehingga tidak membawa id. Jangan kirim token, atau kirim sebagai null, dan tidak ada yang berubah — panggilan dijawab dengan cara yang sama seperti tanpa token. Token dengan bentuk lain apa pun ditolak, sebelum panggilan melakukan apa pun, dengan menyebutkan dua bentuk yang boleh digunakannya alih-alih dilewati begitu saja: pemanggil yang meminta diberi tahu lalu hanya menemui keheningan tidak memiliki apa pun untuk ditindaklanjuti.
Yang tiba adalah notifications/progress, yang membawa token Anda dan hitungan yang bertambah pada setiap laporan. Tidak ada total dan tidak ada pesan, dan keduanya bukan kelalaian yang menunggu pengerjaan: yang dilaporkan pekerjaan adalah bahwa ia telah memasuki fase lain, sehingga total hanya dapat dikarang dan kalimat hanya dapat disusun di sini alih-alih diteruskan. Gambarlah indikator tak tentu berdasarkan hitungan yang bertambah; tidak ada pecahan untuk mengisi sebuah bilah.
Melalui HTTP jawaban menjadi aliran peristiwa, dan hanya setelah sesuatu benar-benar melapor. Jawaban itu disajikan sebagai text/event-stream, ditandai agar tidak di-cache, dan membawa X-Accel-Buffering: no untuk perantara yang jika tidak akan menahan setiap peristiwa sampai pekerjaan selesai dan mengubah aliran menjadi satu jawaban yang lambat. Setiap laporan adalah satu peristiwa, dan jawaban panggilan itu sendiri adalah peristiwa terakhir sebelum aliran ditutup. Selama pekerjaan sedang senyap, aliran membawa baris komentar secara berkala, yang mencapai apa pun yang berada di antaranya sebagai byte pada koneksi yang hidup dan tidak mencapai klien Anda sama sekali. Panggilan yang meminta kemajuan dan menjangkau pekerjaan yang tidak melaporkan apa pun tetap dijawab dengan satu objek JSON, karena yang membuka aliran adalah laporan pertama, bukan token.
Pada aliran, bacalah hasilnya dari peristiwa terakhir itu, bukan dari kode status. Status dan header ditulis ketika aliran dibuka, yaitu sebelum pekerjaan selesai, sehingga panggilan yang melapor lalu menolak membawa penolakannya sebagai peristiwa terakhir di bawah status yang sudah terkirim. Menutup koneksi di tengah aliran mengakhiri pekerjaan dan tidak ada lagi yang ditulis untuknya, persis seperti yang dijelaskan Bagaimana sebuah panggilan berakhir untuk setiap panggilan lainnya.
Melalui input dan output standar, laporan berupa baris-baris yang mendahului baris respons, dibingkai dengan cara yang sama seperti setiap pesan lain pada aliran tersebut — satu objek JSON per baris, dalam urutan penulisannya — dan baris respons mengikutinya. Tidak ada yang dilaporkan setelah panggilan selesai, pada kedua transport.
Me-resolve dependensi sebuah Release adalah hal yang melapor di sini. pull melapor setiap kali resolusi memasuki sebuah fase. build melapor hanya ketika melakukan resolusi terlebih dahulu — karena Anda mengirim auto_pull, atau karena pengaturan milik ruang kerja itu sendiri meminta setiap build di dalamnya melakukan resolusi — sebab pelaporan merupakan bagian dari langkah itu: build yang merender dari sematan yang sudah dimilikinya tidak menjangkau apa pun dan tidak melaporkan apa pun, sehingga token pada panggilan itu tidak mengubah apa pun tentang cara panggilan dijawab. Setiap panggilan juga melaporkan setiap langkah yang dimasuki dan ditunggu oleh pekerjaannya — membaca registry, mengambil artefak atau bundel dokumentasi, mengompilasi plugin untuk pertama kalinya — yaitu langkah-langkah yang ditampilkan baris perintah kepada seseorang di samping indikator putarnya. Panggilan yang pekerjaannya tidak menunggu satu pun dari langkah itu tidak melaporkan apa pun, yang tidak berbahaya dan bukan kesalahan: jawabannya adalah jawaban yang akan Anda terima tanpa token.
Menanyakan koneksi mana yang tertulis di suatu tempat dalam dokumen
connection-at-position menjawab pertanyaan yang mendahului bagian koneksi dari dua tool di atas, untuk saat Anda memegang suatu tempat dalam dokumen alih-alih node pada graf — sebuah baris yang sedang Anda lihat dalam sebuah Aggregate atau Release. Berikan file, dokumennya, relatif terhadap root ruang kerja atau absolut dan dibaca dari disk dengan cara yang sama seperti insertion-point membacanya; position, sebuah line dan sebuah character yang keduanya dihitung dari nol, diukur dalam satuan yang disebutkan position_encoding persis seperti insertion-point membaca argumen tersebut; dan release, Release yang graf terkompilasinya mencatat koneksi-koneksi tersebut. Release juga wajib untuk tempat di dalam Aggregate: node graf dan koneksi hanya ada pada graf terkompilasi.
Jawabannya adalah salah satu dari dua bagian. Jika tempat itu berada pada entri sebuah koneksi, jawaban memuat graphNode dan connection — socket-nya, alias-nya, dan document tempat lokasi itu dibaca — yang persis merupakan apa yang diterima attach-candidates di samping graph_node dan release, dan apa yang diterima attachment-container untuk menyebutkan ke mana lampiran pada koneksi itu ditempatkan; kontainer tersebut berada di dalam entri yang sama tempat lokasi itu jatuh. Jika tidak, jawaban memuat noConnectionReason, dari himpunan tertutup: no-connection-entry (tempat itu tidak berada pada entri mana pun tempat lampiran ditulis), feature-created-connection (tempat itu berada pada entri Release untuk koneksi yang dibuat oleh sebuah Feature), atau unknown-connection (tempat itu berada pada entri yang ditulis Release untuk koneksi yang tidak dimuat oleh graf terkompilasi). Jawaban yang dapat dibaca menyatakan alasannya dengan kata-kata.
Tempat di mana pun di dalam sebuah entri berada di dalam entri tersebut — pada alias, pada target-nya, di dalam features-nya — dan jika entri bersarang, entri terdalam yang berlaku. Tempat pada kunci socket itu sendiri, di atas alias-alias di bawahnya, tidak berada di dalam satu pun dari alias tersebut. Entri-entri tersebut adalah yang dicatat oleh graf terkompilasi: dalam Aggregate, setiap koneksi yang dibuat oleh sebuah komponen, pada entrinya di bawah alias koneksi dalam dokumen tempat komponen itu ditulis, yang untuk komponen yang disumbangkan oleh modul yang diimpor adalah dokumen milik modul itu sendiri; dalam Release, setiap entri per sisi yang ditulisnya. Koneksi yang ditulis sebagai daftar target, dan koneksi yang dibuat oleh blok dependensi milik sebuah Feature, tidak memiliki entri tempat lampiran ditulis. Apakah sebuah kunci merupakan koneksi tidak pernah disimpulkan dari namanya.
Tool ini menjawab lalu berhenti. Tool ini tidak menulis apa pun ke file mana pun. Dokumen yang tidak berada di ruang kerja, tidak dapat dibaca, atau bukan YAML yang terbentuk dengan baik dikembalikan sebagai hasil gagal yang menyebutkan apa yang perlu diubah, sebagaimana dari insertion-point; begitu pula tempat yang tidak memiliki line atau character-nya, dan position_encoding di luar ketiga nilai tersebut.
Menanyakan kontainer tempat sebuah lampiran ditempatkan
attachment-container menjawab pertanyaan di antara jawaban kandidat dan titik penyisipan. Anda telah menetapkan apa yang akan dilampirkan ke sebuah node; sebelum dapat menanyakan di mana dalam file hal itu ditulis, Anda perlu mengetahui file mana dan kontainer mana di dalamnya. Berikan graph_node — id node pada graf terkompilasi, sebagaimana graf menggunakannya sebagai kunci — dan release, Release pemilik graf tersebut. Keduanya wajib: id node adalah kunci dari graf sebuah Release dan tidak bermakna tanpanya.
Jangan menyusun jalur itu sendiri. Id sebuah node dan jalur subsistem yang melingkupinya sama-sama ditulis dengan titik di antara bagian-bagiannya, dan titik adalah karakter yang sah dalam nama yang diketik seorang penulis — sehingga dari luar dokumen tidak ada cara untuk membedakan titik struktural dari titik di dalam nama. Jalur yang Anda susun akan terbaca benar dan menunjuk ke kunci yang tidak pernah ditulis siapa pun, dan suntingan berikutnya akan membuat kunci itu alih-alih ditolak. Lebih buruk lagi, id node sama sekali tidak membawa jejak subsistem yang melingkupinya: komponen yang ditulis di dalam subsystems.billing.subsystems.payments memiliki kunci ledger, persis seperti komponen tingkat atas. Mintalah kontainernya.
Jawaban memuat node, node yang dimaksud; file, dokumen tempat node itu ditulis; dan container, jalur struktural dari root dokumen tersebut sebagai daftar segmen — ["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. Bentuknya sengaja berupa daftar, bukan string gabungan: jalur gabungan harus dipecah lagi oleh siapa pun yang menerimanya, yang berarti ambiguitas di atas muncul kembali satu panggilan kemudian. Berikan file dan container ke insertion-point tanpa diubah.
file adalah bagian dari jawaban, bukan sesuatu yang sudah Anda ketahui. Node yang disumbangkan oleh modul yang diimpor ditulis dalam dokumen milik modul itu sendiri dengan nama yang diberikan modul tersebut, sehingga baik file maupun segmen terakhir kontainer berbeda dari apa pun yang Anda kirim.
Untuk lampiran pada satu koneksi yang dibuat oleh node, tambahkan connection dengan socket, alias, dan document-nya, yang wajib di sini karena kedua dokumen dapat memuat koneksi tersebut. Dengan aggregate, jawabannya adalah entri milik koneksi itu dalam dokumen tempat node ditulis, dengan blok features-nya di akhir; koneksi yang dibuat oleh Release tidak memiliki entri di sana dan ditolak. Dengan release, jawabannya adalah entri per sisi di bawah entri Release untuk node tersebut — ["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"] — yang dilaporkan baik Release sudah menulis entri per sisi itu maupun belum, sehingga insertion-point menyebutkan kunci yang masih harus ditulis; Release yang tidak menulis entri untuk node tersebut ditolak, karena di mana node ditempatkan bukan wewenang tool ini untuk memutuskan. Koneksi yang dibuat oleh sebuah Feature ditolak di kedua dokumen.
Tool ini menjawab lalu berhenti. Tool ini tidak membuat lampiran, tidak menulis apa pun ke file mana pun, dan tidak menyusun teks. Tool ini juga tidak memutuskan apa yang boleh dilampirkan — itu tugas attach-candidates. Node yang tidak dimuat graf, atau node yang tidak dicatat dokumennya, dikembalikan sebagai hasil gagal yang menyebutkan apa yang perlu diubah, bukan sebagai jawaban dengan kolom kosong.
Menemukan tempat sebuah entri dalam dokumen
insertion-point menjawab pertanyaan yang menyusul jawaban kandidat. Anda telah menetapkan apa yang akan dilampirkan atau dihubungkan; kini Anda perlu mengetahui di mana dalam file hal itu ditulis. Tool ini mengembalikan posisi dan kolom indentasi, sehingga Anda dapat menerapkan suntingan tanpa mengurai dokumen sendiri. Karena yang dibacanya adalah struktur dokumen itu sendiri, bukan bentuk jenis tertentu, describe-capabilities mengindeksnya di bawah jenis entitas apa pun yang Anda pilih untuk mempersempit.
Berikan file — dokumennya, relatif terhadap root ruang kerja atau absolut, dan berada di dalam ruang kerja: dokumen yang dicapai melalui tautan yang mengarah ke luar ruang kerja, baik ke file maupun ke direktori di sepanjang jalurnya, tidak termasuk, dan ditolak pada kedua transport — dan container, jalur struktural dari root dokumen ke kontainer tempat entri ditempatkan, dengan setiap elemen berupa kunci mapping atau posisi sequence yang ditulis dalam desimal.
Jalur kontainer Anda yang menyediakan. Tool ini membaca struktur dokumen dan tidak pernah menyimpulkan tempat sesuatu dari namanya, tipe yang dibawanya, atau maknanya yang tampak. Anda menyebutkan kunci yang mana; tool ini menyebutkan di mana entri kunci tersebut ditempatkan dalam dokumen ini — segmen jalur mana yang sudah dimuat file, kolom tempat entri-entrinya berada, dan baris terakhir yang dicapai blok terdalamnya. Untuk lampiran Feature pada node graf terkompilasi, Anda tidak perlu mengetahui kunci itu sendiri: attachment-container di atas melaporkan dokumen dan kontainernya, dan keduanya diberikan di sini tanpa diubah.
Jawabannya adalah position dengan lebar nol, yang line dan character-nya sama-sama dihitung dari nol; entryIndent dan indentStep, kolom tempat menulis; dan missingContainerKeys, kunci kontainer yang belum dimuat dokumen ini, dimulai dari yang terluar, yang Anda tulis sebelum entri. entryShape melaporkan apakah kontainer memuat mapping atau sequence, dan melaporkan unknown jika kontainer belum ada atau tidak memuat apa pun, karena dokumen belum menentukannya — bentuknya kemudian Anda yang memilih. indentStepMeasured menyatakan apakah langkah indentasi diukur dari susunan bersarang dokumen ini sendiri atau merupakan nilai cadangan untuk dokumen yang tidak memperlihatkannya. Jika precededByLineBreak diatur, awali teks Anda dengan pemisah baris: posisi berada di akhir baris yang diikuti entri, yang valid baik file diakhiri baris baru maupun tidak, dan tidak mengubah satu byte pun yang sudah ditulis. Bacalah missingContainerKeys bahkan ketika Anda mengira kontainer sudah ada — posisi yang diterapkan tanpa kunci yang harus mendahuluinya menghasilkan dokumen yang tidak lagi dapat diurai.
position_encoding menyebutkan satuan pengukuran offset karakter yang dilaporkan: utf-8, utf-16, atau utf-32. Parameter ini menjadi argumen di sini karena kedua revisi protokol ini tidak menegosiasikannya, dan nilai bawaannya adalah utf-16, yang digunakan sesi editor ketika klien tidak menegosiasikan apa pun — sehingga pemanggil yang tidak menyebutkan apa pun mendapat jawaban yang identik di kedua permukaan. Nilai di luar ketiganya ditolak alih-alih diam-diam diganti dengan nilai bawaan, karena offset yang diukur dengan satu cara lalu diterapkan ke buffer yang diukur dengan cara lain akan merusak dokumen pada karakter pertama di luar ASCII.
Tool ini menjawab lalu berhenti. Tool ini tidak menulis apa pun ke file mana pun, tidak menyusun teks entri, dan tidak menerapkan suntingan; menyusun teks dan memutuskan apakah akan menerapkannya adalah urusan Anda. Permintaan yang tidak menunjuk ke tempat yang dapat diisi entri dikembalikan sebagai hasil gagal yang menyebutkan apa yang perlu diubah — dokumen yang tidak berada di ruang kerja, tidak dapat dibaca, atau bukan YAML yang terbentuk dengan baik; jalur kontainer tanpa segmen atau dengan segmen kosong; jalur yang melewati skalar, yang di dalamnya tidak ada yang dapat ditambahkan; jalur yang mencapai koleksi yang ditulis dalam gaya flow, tempat penambahan akan menulis ulang byte yang sudah ditulis penulis alih-alih menambahkan baris; atau jalur yang menunjuk ke sequence blok dengan sesuatu yang bukan salah satu indeksnya. Jika Anda lebih suka suntingan diterapkan alih-alih menerapkannya sendiri, Menerapkan satu suntingan terbatas pada dokumen adalah tool yang melakukannya.
Menerapkan satu suntingan terbatas pada dokumen
edit-document menerapkan apa yang ditemukan oleh dua tool di atas. Satu panggilan menambahkan satu entri di bawah satu kontainer, atau menetapkan satu skalar, dan tidak dapat melakukan hal lain. Tool ini menulis dokumen yang Anda sebutkan, di dalam ruang kerja, sehingga melalui HTTPS tool ini memerlukan aggrega:workspace-write: pemanggil yang hanya memegang aggrega:read menemukannya dalam daftar tool, dan panggilan yang dilakukannya ditolak dengan menyebutkan cakupan tersebut.
Sebutkan suntingan dalam edit; himpunannya tertutup. add-component menambahkan instans komponen di bawah kontainer komponen; attach-feature melampirkan sebuah Feature ke node yang Anda sebutkan; wire-edge menyambungkan koneksi di dalam salah satu socket node tersebut; set-value menetapkan satu nilai pada node tersebut. Nama di luar keempat itu ditolak alih-alih ditafsirkan. Tidak ada suntingan yang menghapus, mengganti blok yang sudah Anda tulis, menyusun ulang apa pun, atau menulis apa adanya byte yang Anda berikan — jadi ini bukan penulis file dan tidak dapat digunakan sebagai penulis file.
Berikan file, dokumennya — relatif terhadap root ruang kerja atau absolut, dan berada di dalam ruang kerja: dokumen di luarnya, sebagaimana ditulis atau melalui tautan yang mengarah ke luar, ditolak pada kedua transport tanpa ada yang dibaca atau ditulis; node, jalur struktural dari root dokumen sebagai daftar segmen; name, kunci tempat entri ditulis; dan value, apa yang dimuat entri tersebut. node berupa daftar karena alasan yang sama dengan attachment-container menjawab dengan daftar: titik sah di dalam nama yang diketik penulis, sehingga jalur gabungan dapat menunjuk ke kunci yang tidak pernah ditulis siapa pun dan entri akan dibuat di sana alih-alih ditolak. Untuk add-component, jalur menyebutkan kontainer komponen itu sendiri, karena entri yang ditambahkan adalah node-nya; untuk tiga lainnya, jalur menyebutkan node yang menjadi sasaran suntingan, dan kontainernya mengikuti dari suntingan. socket dibaca untuk wire-edge dan diabaikan untuk yang lain. Makna value mengikuti dari edit — entitas yang diminta entri, node yang dituju sebuah koneksi, atau skalar yang menjadi nilai yang ditetapkan — dan merupakan nilai JSON dengan tipenya sendiri, sehingga angka tetap angka, digit yang diapit tanda kutip tetap teks, dan menghilangkannya tidak menetapkan apa pun. Mapping atau sequence ditolak, karena menulis blok bukan salah satu dari suntingan ini.
Setiap byte yang tidak disentuh suntingan tetap utuh. Dokumen hanya diurai untuk menemukan kontainer dan baris tempat bloknya berakhir, sehingga komentar, baris kosong, gaya tanda kutip, skalar folded dan literal, serta bentuk baris baru di akhir semuanya terbawa, dan langkah susunan bersarang diukur dari indentasi dokumen itu sendiri alih-alih dipaksakan. Permintaan yang sama terhadap dokumen yang sama menghasilkan byte yang sama.
Hasilnya harus berupa dokumen yang dapat Anda ketik sendiri, dan itulah syarat penulisan. Dokumen yang disusun diperiksa terhadap skema jenisnya sendiri dan hanya mencapai disk jika lolos. Permintaan yang akan menghasilkan sesuatu yang ditolak skema akan ditolak, dengan menyebutkan properti yang tidak akan diterima skema beserta lokasinya, dan file dibiarkan byte demi byte seperti semula — sehingga suntingan yang ditolak tidak dapat dibedakan dari suntingan yang tidak pernah dicoba, dan Anda dapat mencoba ulang permintaan yang telah diperbaiki terhadap dokumen awal Anda. Entri yang sudah ada dengan isi yang Anda minta tidak menimbulkan perubahan apa pun; entri dengan nama itu yang berisi hal lain ditolak alih-alih diganti.
Jawaban memuat container, jalur struktural tempat entri berakhir; created_containers, tingkat-tingkat kontainer yang harus dibuat oleh suntingan ini, dimulai dari yang terluar, dan kosong dalam kasus biasa ketika seluruh jalur sudah ada; serta written, dokumen yang mencapai disk, kosong jika tidak ada yang mencapainya. Bacalah created_containers: suntingan yang diam-diam menulis dua blok bersarang yang tidak dimuat dokumen tidak dapat dibedakan dari suntingan yang menambahkan satu entri ke blok yang Anda tulis sendiri.
dry_run melakukan segalanya kecuali menulis. Dokumen yang disunting dikembalikan sebagai content, tidak ada yang dibuat, dan written kosong — untuk klien yang menampilkan hasilnya kepada penulis sebelum disimpan. Setiap perilaku lainnya sama dengan penulisan, termasuk pemeriksaan skema, sehingga permintaan yang akan ditolak penulisan juga ditolak dalam mode ini. Tanpanya, dokumen ditulis dan content tidak ada, karena dokumen kemudian sudah berada di disk dan written menyebutkannya.
Apakah yang Anda sambungkan dapat diterima secara semantik — apakah sebuah socket merupakan salah satu yang dideklarasikan produsen, atau apakah syarat keberlakuan sebuah Feature terpenuhi — tidak diputuskan di sini. Itulah yang dijawab oleh validate.
Pada input dan output standar, kapabilitas yang sama juga dapat dicapai sebagai cli-edit-document, yang menjalankan perintah dan mengembalikan teks yang dicetaknya; melalui HTTP tool tersebut tidak ada, dan di sana kapabilitas ini dicapai melalui tool ini.
Mengubah deskripsi asing menjadi draf entitas
import mengonversi deskripsi yang dihasilkan tool lain — misalnya alur yang diekspor dari agent builder — menjadi draf file authoring Aggrega. Tool ini menulis file-file tersebut ke ruang kerja yang dilayani server ini, sehingga melalui HTTPS tool ini memerlukan aggrega:workspace-write: pemanggil yang hanya memegang aggrega:read menemukannya dalam daftar tool, dan panggilan yang dilakukannya ditolak dengan menyebutkan cakupan tersebut.
Berikan source, file atau direktori yang akan dikonversi. Nilainya absolut atau relatif terhadap root ruang kerja, kontrak yang sama dengan yang digunakan setiap argumen jalur lain pada permukaan ini, dan pada server yang dicapai melalui HTTPS nilainya diselesaikan di dalam ruang kerja yang dilayani server tersebut.
Dari sebuah direktori, yang dibaca persis file-file yang dipilih oleh pola file importernya. Chart atau proyek adalah direktori, dan source dapat menyebutkan salah satunya. Importer kemudian diberi file-file di dalamnya, pada kedalaman berapa pun, yang dipilih oleh salah satu pola file yang dideklarasikan tanda tangannya, masing-masing dinamai berdasarkan jalurnya di dalam direktori yang ditulis dengan garis miring, dalam urutan terurut, bersama file-file yang disebutkan lampiran plugins.importer-nya di bawah with.sources, dengan nama dasarnya; file direktori dan file with.sources dengan nama yang sama ditolak alih-alih yang satu menyembunyikan yang lain. Importer yang tidak mendeklarasikan pola file membaca satu file dan menolak direktori, dengan kondisi An importer that declares no file patterns is handed a directory (Sebuah direktori diberikan kepada importer yang tidak mendeklarasikan pola file), dan direktori yang tidak memuat file yang dipilih polanya juga ditolak. Direktori dibatasi pada dirinya sendiri di mana pun letaknya: tautan di antara file yang akan dibaca impor, atau ke sebuah direktori, yang mengarah ke luar direktori itu ditolak sebelum apa pun dibaca, dan tautan ke direktori tidak pernah dimasuki — sebagaimana dijelaskan dalam Direktori yang Anda impor. Pada server yang dicapai melalui HTTPS, direktori itu sendiri diselesaikan di dalam ruang kerja, demikian pula setiap file yang dibaca darinya.
Importer tersebut adalah importer yang dimuat katalog ruang kerja Anda, atau salah satu importer inti kompiler. Penerjemahan dilakukan oleh plugin importer yang mengiklankan format sumber: importer yang dimuat katalog ruang kerja Anda, atau salah satu importer inti kompiler, yang melayani formatnya di setiap ruang kerja tanpa entri katalog. Tool ini memilihnya, menjalankannya, dan menulis apa yang dihasilkannya. Lampiran plugins.importer yang uri-nya menyebutkan importer berdasarkan identitas dan versinya — importer/<name>:<version>, sebagaimana ditulis oleh aggrega plugin add importer — melampirkan importer tersebut: jika importer itu mengiklankan format sumber, importer itulah yang dijalankan, pada versi tersebut, importer lain mana pun yang juga mengiklankan format itu, dan importer itu diberi sumber dan pengaturan with dari lampiran tersebut, yang tidak diterima importer lain. Jika beberapa importer mengiklankan format tersebut dan tidak ada satu pun yang dilampirkan secara tunggal — di antaranya importer inti dan importer dengan nama lain yang dimuat katalog Anda untuk format yang sama — panggilan ditolak dengan menyebutkan importer-importer itu, sebagaimana dijelaskan dalam Konfigurasi. Format yang Anda sebutkan dan tidak diiklankan importer mana pun ditolak dengan menyebutkan kapabilitas yang harus diiklankan importer — import:langflow untuk sumber Langflow — yaitu apa yang dideklarasikan importer yang Anda tambahkan ke katalog, alih-alih kegagalan umum yang kemudian harus Anda tafsirkan.
Importer inti yang tidak dimiliki mesin server diambil satu kali, oleh impor pertama yang membutuhkannya. Impor mengambilnya dari registri bawaan ruang kerja yang dilayani, mencocokkannya dengan modul yang diterbitkan rilis kompiler, memverifikasi tanda tangannya berdasarkan kebijakan kepercayaan registri tersebut serta fungsi host yang digunakannya, sebagaimana pull memverifikasi plugin yang diambilnya, dan menyimpannya di cache konten ruang kerja, sehingga setiap impor berikutnya membacanya dari sana dan tidak menghubungi registri apa pun. Tidak ada hal lain yang ditulis untuknya — tidak ada lockfile, dan tidak ada catatan plugin tepercaya. Melalui HTTPS, ini adalah satu-satunya registri yang dapat dihubungi server akibat panggilan ke tool ini, dalam batas yang ditetapkan Kredensial mana yang digunakan sebuah panggilan untuk pembacaan registri: registri tersebut adalah registri bawaan ruang kerja yang dilayani server ini, sehingga merupakan registri yang dikonfigurasi untuk ruang kerja itu; tidak ada apa pun dalam panggilan yang menyebutkan registri atau membawa kredensial; dan pengambilan menggunakan login dan kebijakan kepercayaan milik host ini sendiri. Tool ini tetap hanya menjangkau ruang kerja dan tidak lebih, sehingga aggrega:workspace-write adalah semua yang dibutuhkan sebuah panggilan: yang ditinggalkan pengambilan adalah modul di cache konten milik ruang kerja itu sendiri. Modul yang tidak lolos verifikasi ditolak sebagaimana di terminal, dan tidak ada yang disimpan. Jika modul tidak dapat diambil — ruang kerja sedang offline, registrinya tidak dapat dijangkau, atau registri tidak memuatnya — panggilan ditolak dengan kondisi A plugin’s .wasm is not on this machine (.wasm sebuah plugin tidak ada di mesin ini), dengan menyebutkan importer, versinya, dan apa yang menempatkan modulnya di mesin.
Jika ruang kerja tidak menyebutkan folder katalog apa pun, impor membaca katalog yang diterbitkan registry default-nya. Ruang kerja yang workspace.catalog_dirs, AGGREGA_CATALOG_DIRS, dan root-nya tidak menyebutkan folder katalog apa pun membaca katalog pustaka standar sebagai satu snapshot bertanda tangan, di catalog/snapshot pada registry default ruang kerja yang dilayani — registry yang sama dengan tempat importer inti diambil, dijangkau dengan ketentuan yang sama, tanpa ada apa pun dalam panggilan yang menyebutkan registry atau membawa kredensial. Snapshot diambil sekali: tanda tangannya diverifikasi berdasarkan kebijakan kepercayaan registry tersebut, lalu snapshot disimpan di cache konten ruang kerja dan dibaca di sana sebagai folder katalog, terikat pada digest-nya, tanpa diminta lagi dari registry mana pun. Snapshot mana yang dibaca sebuah panggilan: dengan upgrade, yang terbaru; jika tidak, yang disebutkan catatan di direktori keluaran, diambil melalui digest-nya jika mesin tidak menyimpannya; jika tidak, yang terakhir diambil ruang kerja sebagai yang terbaru; jika tidak, yang terbaru. Catatan yang ditulis impor menyebutkan snapshot yang dibacanya, melalui digest-nya, sehingga panggilan berikutnya yang membuat draf ke direktori yang sama membaca katalog yang sama. Saat offline, panggilan yang harus mengambil snapshot ditolak dengan menyebutkan apa yang perlu dijalankan, dan upgrade ditolak apa pun yang disimpan mesin, karena hanya registry yang dapat menyatakan snapshot mana yang terbaru. Registry yang tidak menerbitkan snapshot apa pun membuat impor tanpa katalog, dan entri warn di diagnostics menyatakannya. Ruang kerja yang menyebutkan folder katalog mengimpor terhadap folder itu dan tidak mengambil snapshot apa pun, dan upgrade tidak mengubah apa pun di sana.
Jika format dihilangkan, format dikenali dari tanda tangan yang dideklarasikan importer — baik milik katalog Anda maupun milik importer inti. Entitas Plugin setiap importer mencatatnya: sintaks yang digunakan untuk membaca sumber, nama file yang dikenai tanda tangan, dan jalur yang wajib atau tidak boleh dimuat pohon hasil penguraian. Sumber diurai, melalui parser yang dilayani katalog ruang kerja Anda untuk sebuah sintaks — atau, untuk sintaks yang tidak dilayani parser oleh katalog Anda, parser yang dibawa kompiler itu sendiri — satu kali untuk setiap sintaks yang digunakan tanda tangan yang berlaku untuk namanya, dan format yang digunakan adalah format dari satu-satunya importer yang tanda tangannya cocok. Importer kemudian membaca sumber melalui parser yang sama. Tanda tangan importer inti membaca file sebagai JSON atau YAML, dan tanda tangan yang tidak menyebutkan file membacanya sebagai JSON — milik importer Dify sebagai YAML — sehingga mengenali file yang diimpor secara tersendiri membacanya dalam keduanya dan tidak memerlukan parser di katalog ruang kerja Anda: kompiler membawa parser JSON dan parser YAML, dan parser yang dilayani katalog Anda digunakan sebagai gantinya. Direktori dikenali dengan cara yang sama atas file-filenya: setiap tanda tangan dicoba terhadap file-file di dalamnya yang dipilih polanya, dan tanda tangan yang tidak mendeklarasikan pola tidak berlaku untuk satu pun dari file tersebut. Pengenalan membaca file yang Anda sebutkan — atau, untuk direktori, hanya file yang dipilih pola sebuah tanda tangan — dan tidak mengakses jaringan. Sumber yang tidak cocok dengan tanda tangan mana pun ditolak dengan meminta format dan menyebutkan format yang diiklankan importer — atau, untuk direktori, meminta salah satu filenya dikirim tersendiri sebagai source atau format yang importernya mendeklarasikan pola file, dengan hanya menyebutkan format tersebut — dengan kondisi No importer recognises the source (Tidak ada importer yang mengenali sumber); sumber yang cocok dengan tanda tangan lebih dari satu format ditolak dengan menyebutkan format-format tersebut, dengan kondisi More than one importer recognises the source (Lebih dari satu importer mengenali sumber); keduanya tidak diserahkan kepada importer hasil tebakan. Kirim format untuk menyebutkan format secara langsung dalam kedua kasus — untuk direktori, format yang importernya mendeklarasikan pola file, karena direktori hanya dibaca melalui pola tersebut. format yang kosong ditolak alih-alih dibaca seolah-olah Anda menghilangkannya, karena keduanya adalah permintaan yang berbeda.
Kirim target untuk membuat draf Manifest yang menjadi dasar build Release draf untuk satu provider. target adalah kapabilitas provider — kata yang menjadi ikatan spec.capability sebuah Recipe, seperti compose atau helm — dan merupakan --target milik aggrega import, disusun oleh operasi yang sama, sehingga sebuah panggilan dan perintah tersebut membuat draf file yang sama dari sumber yang sama. Untuk setiap tipe komponen dan setiap tipe fitur yang dibutuhkan draf — pada komponen Aggregate draf, koneksinya, dan subsistemnya, pada Aggregates katalog yang disusunnya, serta pada lampiran Release draf — dalam urutan pertama kali dideklarasikan oleh draf, impor mencari di katalog ruang kerja Recipes, atau untuk tipe fitur resep fitur, yang mengimplementasikan tipe tersebut dan terikat pada kapabilitas itu. Jika ada tepat satu — beberapa versi dari salah satunya dihitung sebagai satu — Manifest memetakan tipe tersebut ke sana melalui nama yang dikualifikasi kapabilitas tanpa versi, seperti compose/postgres, yang dipatok oleh pull pertama dalam lockfile pada versi tertinggi yang tersedia. Jika ada beberapa dengan nama berbeda, Manifest memetakan yang dinamai sesuai tipe itu sendiri, seperti helm/postgres untuk core/datastore/postgres. Jika tidak ada, atau ada beberapa tetapi tidak satu pun bernama demikian, tipe tersebut dibiarkan tidak terpetakan dan entri warn dalam diagnostics menyebutkannya beserta alasannya — beberapa itu masing-masing dengan namanya — sehingga build draf berhenti dengan menyebutkan setiap instans atau lampirannya, dengan kondisi No Recipe is mapped for a component or feature instance (Tidak ada Recipe yang dipetakan untuk instans komponen atau fitur), hingga pemetaan ditambahkan. Jika importer membuat draf Manifest sendiri, untuk memilih Recipe yang digunakan untuk merender sebuah instans atau sebuah resep fitur di antara beberapa, setiap pemetaan yang ditulisnya dan ditawarkan katalog untuk tipe dan kapabilitas tersebut dipertahankan, pemetaan lainnya dibuang dengan entri warn, dan tipe yang ditinggalkannya dipetakan seperti di atas. Manifest dibuat sebagai manifest.yaml di samping Release draf, dengan nama dan versi yang sama dengan Release, dan spec.manifest milik Release ditetapkan ke nama tersebut — komentar yang ditulis importer di tempatnya diganti, dan tidak ada hal lain dalam Release yang berubah. Release yang sudah menyebutkan sebuah Manifest dibiarkan apa adanya, dan jika impor tidak membuat draf Release, Manifest dibuat di samping Aggregate, dengan nama dan versinya, dan entri info menyatakan bahwa tidak ada yang merujuknya. Manifest dan Release yang disunting adalah draf seperti yang lain: ada dalam written, dalam catatan, dan dikembalikan di bawah dry_run. target yang tidak menjadi ikatan Recipe mana pun dalam katalog ditolak sebelum importer dijalankan, dengan kondisi An import’s target names a capability no Recipe in the catalog binds to (Target sebuah impor menyebutkan kapabilitas yang tidak menjadi ikatan Recipe mana pun dalam katalog), dengan menyebutkannya sebagaimana Anda kirim beserta kapabilitas yang menjadi ikatan Recipes dalam katalog, dan tidak ada yang ditulis. Jika target dihilangkan, tidak ada Manifest yang dibuat — kecuali di bawah sync, yang membuat draf untuk target yang dikirim bersama impor sebelumnya; target yang kosong ditolak alih-alih dibaca seolah-olah Anda menghilangkannya.
Kirim output_dir untuk menyebutkan direktori tempat draf ditempatkan. Jika dihilangkan, draf ditempatkan di bawah root ruang kerja yang diselesaikan oleh panggilan — tempat aggrega import menulisnya ketika Anda tidak menyebutkan tujuan, di mana pun Anda menjalankannya, dan tempat aggrega/import milik language server menulisnya ketika permintaannya tidak menyebutkan tujuan. Tujuan bersifat opsional pada ketiganya, dan disebutkan dengan cara yang sama seperti setiap jalur yang Anda kirim ke server ini. Melalui HTTP, nilainya adalah direktori di dalam ruang kerja yang dilayani server ini, ditulis relatif terhadap root-nya: nilai yang naik keluar dari root, lokasi absolut di luarnya, dan direktori yang mengarah ke luar melalui tautan — termasuk direktori yang belum dibuat di bawah tautan semacam itu — masing-masing ditolak dengan menyebutkan output_dir, dan tidak ada yang dibaca atau ditulis. Melalui input dan output standar, nilainya diambil sebagaimana disebutkan, seperti setiap jalur di sana: nilai relatif diselesaikan terhadap root ruang kerja yang diselesaikan oleh panggilan, dan nilai absolut dapat menyebutkan direktori di luar ruang kerja, yang menjadi tempat draf dibuat sebagaimana aggrega import --output-dir membuat draf di sana. Apa yang ditulis di sana dibatasi, dengan tautan-tautannya diselesaikan, pada ruang kerja — atau, untuk direktori yang Anda sebutkan di luarnya, pada direktori tersebut — sehingga tautan di dalamnya yang mengarah ke luar ditolak dan tidak ada yang ditulis. output_dir yang kosong ditolak alih-alih dibaca seolah-olah Anda menghilangkannya. Pada input dan output standar, cli-import juga membawa --output-dir milik perintah sebagai output_dir-nya sendiri; di sana nilai relatif diselesaikan dalam folder tempat perintah dijalankan: root ruang kerja yang disebutkan panggilan, jika tidak ada maka root yang digunakan saat server dimulai, dan jika tidak ada juga maka folder tempat server berjalan.
Setiap jalur draf diperiksa terhadap direktori output sebelum apa pun ditulis. Jalur yang menjangkau ke luar direktori itu ditolak dengan menyebutkan jalur dan direktorinya, dan tidak ada apa pun yang ditulis — bahkan file dalam set yang sama yang jalurnya sendiri sudah benar, karena impor yang ditolak tetapi meninggalkan sebagian dirinya adalah hasil yang tidak diminta siapa pun. Jalur draf berasal dari plugin importer, bukan dari Anda, itulah sebabnya jalur tersebut diperiksa dengan alasan yang sama seperti jalur yang Anda kirim.
Setiap impor yang membuat draf apa pun juga menulis .aggrega-import.json di samping draf-drafnya: catatan tentang apa yang ditulisnya — target yang dikirim bersamanya, jika ada yang dikirim, snapshot katalog yang dibacanya, jika ada yang dibaca, dan setiap file draf serta, dalam Aggregate atau Release draf, setiap kunci di setiap kedalaman, dengan digest dari teks yang ditulis di sana; file draf lainnya dicatat secara utuh. Teks sebuah kunci adalah barisnya, baris-baris nilainya jika nilainya bukan mapping kunci, dan baris komentar yang ditulis tepat di atasnya pada indentasinya sendiri. written menyebutkan catatan bersama draf-draf tersebut, dan di bawah dry_run catatan termasuk di antara draf yang dikembalikan. Catatan berformat JSON, sehingga tidak ada hal yang membaca dokumen YAML ruang kerja yang membacanya.
Sebuah panggilan tidak pernah menimpa Aggregate yang sudah ada di direktori output. Aggregate adalah dokumen yang terus disunting penulis setelah draf dibuat, sehingga panggilan yang salah satu drafnya akan mendarat pada file yang terbaca sebagai Aggregate ditolak, dengan menyebutkan draf dan direktorinya, dan tidak ada apa pun yang ditulis — juga di bawah dry_run, karena dry run menolak apa yang ditolak penulisan. Setiap file lain yang sudah ada pada jalur draf ditimpa, dan file yang dibuat oleh impor sebelumnya tetapi tidak dibuat oleh impor ini dibiarkan di tempatnya.
Kirim sync untuk memperbarui apa yang dibuat oleh impor sebelumnya agar sesuai dengan sumber, dengan hanya mengubah apa yang ditulis impor. Sinkronisasi yang tidak dikirimi target membuat draf untuk target yang disebutkan catatan, sehingga membuat draf Manifest yang dibuat oleh impor sebelumnya; sinkronisasi yang dikirimi target membuat draf untuk target itu, dan catatan kemudian menyebutkannya. Target tercatat yang tidak menjadi ikatan Recipe mana pun dalam katalog ditolak seperti target yang dikirim, dengan penolakan yang menyatakan bahwa target tersebut adalah target yang tercatat. Setiap bagian dinilai dengan tiga cara — apa yang menurut catatan terakhir kali ditulis impor di sana, apa yang ada di disk, dan apa yang dibuat sumber sekarang. Bagian yang dibiarkan sumber seperti terakhir kali ditulis impor tetap persis seperti di disk, baik disunting penulis maupun tidak. Bagian yang diubah sumber ditulis ulang, bagian yang dihapus sumber dihilangkan — file draf dihapus secara utuh — dan bagian yang ditambahkan sumber ditambahkan di samping bagian-bagian yang disebutkan draf di sekitarnya, masing-masing hanya jika apa yang ada di disk adalah apa yang terakhir kali ditulis impor dan tidak memuat apa pun yang ditambahkan penulis. Segala hal lainnya tetap byte demi byte: kunci yang ditambahkan penulis di mana pun — sebuah parameter, sebuah Feature, juga di bawah instans Component draf, Component lain, lingkungan yang disisakan Release draf untuk penulisnya — komentar yang tidak ditulis tepat di atas kunci draf, dan setiap file yang tidak tercantum dalam catatan. drift dalam jawaban mencantumkan setiap bagian yang diperbarui — atau, di bawah dry_run, setiap bagian yang akan diperbarui — dalam urutan penyebutannya oleh draf, masing-masing sebagai change (added, removed, atau changed), file, file draf tempat bagian itu berada, dan key, kunci-kunci yang mengarah ke bagian itu dalam Aggregate atau Release draf, sebagai daftar, kosong jika bagian itu adalah seluruh file; jawaban teks menyebutkan masing-masing pada barisnya sendiri dengan kata-kata yang ditulis aggrega import ke standard error, <change> <key> in <file> atau <change> <file>. drift yang kosong di bawah dry_run menyatakan bahwa draf sudah selaras dengan sumber. Di bawah dry_run, draf yang dikembalikan adalah file-file yang akan ditulis sinkronisasi, dengan konten yang akan diberikannya. Sinkronisasi yang akan mengubah atau menghapus bagian yang disunting penulis, menambahkan bagian di tempat penulis sudah menulisnya, atau menghapus bagian yang memuat sesuatu yang ditambahkan penulis ditolak, dengan menyebutkan setiap bagian tersebut beserta alasannya, dan tidak ada yang ditulis; komentar yang ditulis tepat di atas kunci draf menyunting kunci tersebut. Sinkronisasi atas Aggregate yang tidak tercantum dalam catatan mana pun ditolak dengan menyatakan hal itu, demikian pula sinkronisasi yang catatannya tidak dapat dibaca, dan sinkronisasi yang importernya tidak dapat menyelesaikan pekerjaan tidak menulis apa pun. Sinkronisasi ke direktori yang tidak memuat catatan dan tidak ada apa pun pada jalur drafnya menulis seluruh draf. drift adalah daftar kosong untuk panggilan yang bukan sinkronisasi.
Jawaban memuat source, sebagaimana Anda sebutkan; format, cara sumber dibaca; workspace_root, root ruang kerja yang diselesaikan panggilan; output_dir, direktori yang menjadi acuan relatif jalur-jalur draf; written, file-file yang mencapai disk; drift, apa yang diperbarui oleh sinkronisasi; diagnostics, satu entri per konstruksi yang tidak dapat diterjemahkan importer; decisions, cara importer memetakan setiap node sumber; dan halted. output_dir adalah direktori yang Anda kirim, atau root tersebut jika Anda tidak mengirimnya, dibaca dari apa yang benar-benar digunakan impor, dan dilaporkan juga di bawah dry_run, ketika tidak ada yang ditulis tetapi setiap jalur draf tetap relatif terhadapnya. Melalui HTTP, workspace_root ditahan dan ditandai workspace_root_withheld, karena root adalah lokasi di host server, sebagaimana dijelaskan dalam Apa yang dinyatakan jawaban tentang sistem file server; output_dir ditahan dan ditandai output_dir_withheld jika nilainya adalah root tersebut, dan jika tidak, dinyatakan dengan namanya yang relatif terhadap root — bentuk yang digunakan jalur-jalur Anda sendiri — sehingga tujuan draf tetap ada dalam jawaban. Impor yang tidak dapat diselesaikan importer tetap membuat draf sejauh yang dapat dilakukannya, dan dikembalikan dengan tanda gagal yang memuat seluruh jawaban itu — halted bernilai true, file-file yang benar-benar mencapai disk disebutkan dalam written, dan diagnostik di sampingnya yang menyebutkan apa yang kurang. Itu adalah hasil parsial yang dapat Anda simpan atau buang, bukan panggilan yang tidak melakukan apa pun.
decisions menyatakan di mana impor menebak. Isinya satu entri per node sumber yang dipetakan importer, dalam urutan importer: source_node, yaitu id, type, dan params_summary node tersebut; candidates, setiap Component katalog yang dipertimbangkan importer untuknya sebagai component, score, tier, dan signals — kontribusi setiap sinyalnya, di bawah table, category, domain_labels, shape, dan name; chosen, target yang dipilihnya, mode yang digunakannya untuk menulisnya — reference ke Component yang sudah ada atau draft — dan tier pilihan tersebut; rationale, alasannya; dan swap_hint, cara memilih secara berbeda. candidates tidak ada jika importer tidak mempertimbangkan satu pun, chosen jika importer tidak membuat pilihan, serta rationale dan swap_hint jika importer tidak menulisnya. Setiap nilai adalah milik importer sendiri — cara importer memberi skor kandidat dan letak tingkatannya adalah pilihannya — jadi bacalah sebuah entri sebagai penjelasannya tentang pemetaan. decisions ada dalam jawaban baik di bawah dry_run maupun ketika impor terhenti, dan berupa daftar kosong untuk importer yang tidak melaporkan apa pun. Jawaban teks menyebutkan setiap keputusan pada barisnya sendiri setelah diagnostik, dengan kata-kata yang ditulis aggrega import ke standard error: mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, dengan skor milik kandidat terbaik.
dry_run melakukan segalanya kecuali menulis. Setiap file draf dikembalikan di bawah drafts dengan jalurnya, relatif terhadap output_dir, dan kontennya, dan tidak ada yang dibuat — untuk klien yang menampilkan hasilnya kepada Anda sebelum disimpan. Setiap perilaku lainnya sama dengan penulisan, importer yang sama atas sumber yang sama melaporkan diagnostik yang sama, sehingga sumber yang akan ditolak penulisan juga ditolak dalam mode ini. Tanpanya, file-file berada di disk dan written menyebutkannya, dan drafts tidak ada alih-alih mengulang byte yang Anda minta untuk ditulis.
Draf adalah titik awal yang menjadi milik Anda dan terus Anda sunting. Apakah isinya dapat diterima — apakah sebuah socket merupakan salah satu yang dideklarasikan produsen, atau apakah syarat keberlakuan sebuah Feature terpenuhi — tidak diputuskan di sini. Itulah yang dijawab oleh validate.
Pada input dan output standar, kapabilitas yang sama juga dapat dicapai sebagai cli-import, yang menjalankan perintah dan mengembalikan teks yang dicetaknya; melalui HTTP tool tersebut tidak ada, dan di sana kapabilitas ini dicapai melalui tool ini.
Memublikasikan, menandatangani, dan menarik
Empat alat menempatkan sesuatu di tempat orang lain akan me-resolve-nya. publish-entity membundel sebuah entitas katalog dan memublikasikannya; publish-artifact memublikasikan file mandiri, seperti bundel dokumentasi, dengan byte-nya yang buram dan tanpa mem-parse amplop entitas apa pun; sign-artifacts menandatangani referensi yang sudah dipublikasikan dan melampirkan setiap tanda tangan, dengan membiarkan apa adanya referensi yang sudah membawa tanda tangan yang diverifikasi oleh kebijakan kepercayaan registry-nya; deprecate-artifact melampirkan penanda penarikan yang ditandatangani ke sebuah referensi. Baca Apa yang dapat dilakukan asisten tanpa bertanya kepada Anda terlebih dahulu sebelum Anda mengizinkan salah satunya: inilah alat-alat yang efeknya keluar dari mesin.
publish-entity menerima entity, dokumen yang akan dipublikasikan, dan sebuah Plugin juga memerlukan plugin, file eksekusi yang dipublikasikan di dalam manifesnya. publish-artifact menerima file beserta name dan tag yang digunakan untuk memublikasikannya. Setiap argumen jalur di sini bersifat absolut atau relatif terhadap root workspace, kontrak yang sama yang digunakan oleh setiap alat lain di permukaan ini, dan workspace_root menyebutkan workspace yang dimaksud oleh panggilan — pada server yang dijangkau melalui input dan output standar. Server yang dijangkau melalui HTTPS menolak workspace_root dan mengharuskan setiap jalur tersebut ter-resolve di dalam workspace yang dilayaninya, sebagaimana dijelaskan dalam Satu proses, satu workspace. registry adalah tujuan dan secara default bernilai registry yang dikonfigurasi di workspace; tidak mengirim keduanya, tanpa default yang dikonfigurasi, akan ditolak dengan menyebutkan apa yang harus dikirim. sign-artifacts menerima references, satu atau beberapa alamat registry, bukan jalur, dan secara opsional jobs, berapa banyak yang ditandatangani sekaligus: jika dihilangkan, referensi ditandatangani satu per satu, dan nilai di bawah 1 ditolak dengan menyebutkan apa yang harus dikirim. Masing-masing tetap ditandatangani persis seperti bila ditandatangani sendiri, sebagaimana dijelaskan aggrega sign. deprecate-artifact menerima reference beserta severity dan reason, atau from yang menyebutkan file batch — dan menolak argumen konten yang dikirim bersama file batch alih-alih membuangnya, karena file batch menyediakan argumennya sendiri dan argumen yang diabaikan secara diam-diam terbaca seperti argumen yang dihormati.
Kedua alat publikasi menerima dry_run, yang menunjukkan apa yang akan dikirim oleh sebuah publikasi tanpa menghubungi registry mana pun. Opsi ini menghitung bundel, melaporkan apa yang akan dipublikasikannya, dan menjawab dengan beyond_this_machine bernilai false serta tujuan yang akan dituju dalam registries; publish-entity juga menjawab dengan digest yang akan dihasilkan oleh publikasi tersebut, yaitu yang dicetak oleh aggrega push --dry-run. Inilah cara untuk menunjukkan kepada seseorang sebuah usulan publikasi sebelum benar-benar menjadi publikasi. Penandatanganan dan penarikan tidak memiliki bentuk seperti itu: keduanya bertindak atas sesuatu yang sudah dipublikasikan, sehingga tidak ada yang perlu dipratinjau.
publish-entity menjawab dengan windows_unusable_entries ketika arsip yang dipublikasikannya berisi entri yang tidak dapat disimpan oleh Windows sebagaimana tertulis — jalur dengan bagian yang dinamai sesuai perangkat, seperti CON, AUX, atau NUL, dalam huruf besar atau kecil apa pun dan apa pun ekstensi yang mengikutinya, atau bagian yang diakhiri titik atau spasi — dengan menyebutkan masing-masing, pertama nama file dokumen entitas itu sendiri, lalu file-file yang dibawanya. Bidang ini tidak ada jika tidak ada entri seperti itu, termasuk untuk entitas yang dipublikasikan sebagai dokumennya saja. aggrega yang berjalan di Windows menolak membongkar entri seperti itu, sehingga workspace Windows tidak dapat menggunakan versi tersebut; inilah entri-entri yang diperingatkan oleh aggrega push, dan teks jawaban juga menyebutkannya. Entri-entri ini tidak menolak apa pun: panggilan tetap berjalan atau ditolak persis seperti tanpa entri tersebut, termasuk dry_run.
publish-entity menerima pin_sources, yang menjalankan langkah pin milik penulis entitas pada entitas sebelum dibundel, sehingga entity.lock yang ditulis langkah tersebut di sampingnya menjadi bagian dari apa yang dipublikasikan. Ini adalah langkah yang sama dengan yang dijalankan alat pin, menulis byte yang sama, dan berjalan sebelum penolakan apa pun yang menilai entitas — sehingga publikasi yang ditolak di sana, misalnya karena tanda tangan yang hilang, tetap meninggalkan lock yang ditulis di samping entitas. Penolakan tentang panggilan itu sendiri, seperti workspace offline atau tidak adanya tujuan, datang lebih dulu dan tidak melakukan pin apa pun. Jika dihilangkan, pin_sources_at_push milik workspace yang menentukan; jika dikirim, opsi inilah yang menentukan ke arah mana pun. Publikasi yang melakukan pin menulis di dalam workspace selain ke registry, sehingga melalui HTTP memerlukan kredensial yang membawa kedua scope, dan kredensial yang hanya membawa scope yang mengizinkan publikasi akan ditolak dengan menyebutkan scope lainnya. Hasilnya membawa pin, dalam bentuk yang digunakan alat pin untuk menjawab, ketika langkah tersebut dijalankan; di bawah dry_run langkah tersebut melaporkan lock yang akan ditulisnya dan tidak menulis apa pun. Ketika langkah tersebut tidak dijalankan, sebuah Recipe atau FeatureRecipe yang entity.lock-nya tidak mencatat pin untuk input yang dibacanya akan ditolak — atau yang inputnya tidak lagi cocok — sebelum apa pun dibundel, termasuk dry_run, dengan menyebutkan aggrega pin, pin_sources, dan pin_sources_at_push. Ini adalah penolakan yang dimunculkan pull atas lock yang sama, dan pemeriksaannya mengambil setiap sumber jarak jauh yang ditulis lengkap oleh entitas, sebagaimana yang akan dilakukan langkah tersebut.
Penandatanganan adalah saat kredensial digunakan, dan tiga dari empat alat melakukannya — publikasi artefak data tidak menandatangani apa pun, dan ditandatangani setelahnya melalui referensi. identity_token menyediakan identitas tanpa kunci untuk panggilan. Pada server yang dijangkau melalui input dan output standar, menghilangkannya akan beralih ke identitas yang dibawa oleh lingkungan server itu sendiri, dan key_path sebagai gantinya memilih kunci yang disimpan secara offline. Melalui listener, keduanya tidak dapat dijangkau: lingkungan tidak dibaca, key_path ditolak dan dihapus dari apa yang diiklankan ketiga alat ini, dan kunci yang disebutkan oleh konfigurasi workspace yang dilayani tidak dijangkau — sehingga hanya token yang dikirim dalam panggilan yang menandatangani, sebagaimana dijelaskan dalam Kredensial mana yang digunakan sebuah panggilan. Satu panggilan menandatangani dengan satu kredensial. Setiap referensi yang dikirim ke sign-artifacts, dan setiap entri file batch yang dibaca deprecate-artifact, ditandatangani dengan kunci tersimpan yang sama atau identitas tanpa kunci yang sama; ketika konfigurasi workspace yang dilayani menyebutkan kunci untuk registry satu referensi dan tidak ada untuk registry referensi lain, atau dua kunci yang berbeda, panggilan tidak menandatangani apa pun dan ditolak dengan menyebutkan registry di setiap sisi, sebelum identitas apa pun di-resolve atau registry apa pun dibaca — kirim satu panggilan per kredensial, atau satu key_path untuk semuanya melalui input dan output standar. Melalui listener tidak ada kunci terkonfigurasi yang dijangkau, sehingga di sana setiap referensi ditandatangani dengan identitas yang dikirim panggilan dan panggilan tidak pernah ditolak karena hal ini. Penolakan tersebut dijelaskan dalam References signed together need different signing credentials (Referensi yang ditandatangani bersama memerlukan kredensial penandatanganan yang berbeda). fulcio_url, rekor_url, dan timestamp_url menimpa endpoint tanpa kunci yang dikonfigurasi workspace, pada transport mana pun. Ketika tidak ada identitas yang ter-resolve sama sekali, panggilan menolak dan menyebutkan apa yang harus dikirim — tidak ada apa pun di sini yang membuka browser atau menunggu seseorang, karena tidak ada yang mengamati aliran protokol, dan panggilan yang macet akan menjadi kegagalan diam-diam yang justru dicegah oleh penolakan tersebut. Pada publish-entity, apakah tanda tangan dilampirkan atau tidak mengikuti kebijakan registry tujuan kecuali sign menyatakan lain, dan registry yang mewajibkan tanda tangan menolak publikasi tanpa tanda tangan apa pun yang Anda kirim: tidak ada argumen yang dapat melewati penolakan tersebut. Lihat aggrega sign untuk dua mode penandatanganan dan apa yang dihubungi masing-masing.
Setiap hasil membawa fakta, bukan transkrip: di mana artefak berakhir, tag-nya, digest yang dipublikasikan — atau, untuk dry run entitas katalog, digest yang akan dihasilkan oleh publikasi — apakah tag sudah menunjuk ke konten yang identik byte demi byte, apakah publikasi ditandatangani, dan reach-nya. Batch penandatanganan melaporkan setiap referensi yang ditandatangani beserta digest yang menjadi komitmen tanda tangannya, sesuai urutan referensi diberikan, dan batch yang salah satu referensinya gagal kembali sebagai kegagalan yang menyebutkan masing-masing, bukan sebagai hasil dengan daftar yang terpotong — batch parsial yang dilaporkan sebagai keberhasilan adalah cara sebuah penolakan akhirnya terbaca sebagai lolos. Deprekasi melaporkan setiap penanda dengan digest-nya sendiri, karena penanda dilampirkan sebagai referrer tanpa tag dari artefak yang ditariknya dan tidak ada hal lain yang mengalamatkannya. Menandatangani atau menarik referensi yang tidak pernah dipublikasikan apa pun akan ditolak, alih-alih dilampirkan ke ketiadaan.
Dua bagian sebuah jawaban
Setiap alat menjawab dengan teks yang dapat dibaca, dan dengan hasil terstruktur di sampingnya di mana pun operasi memilikinya. Teks ditulis untuk orang yang membaca percakapan. Hasil terstruktur membawa jawaban yang sama sebagai bidang yang dibaca program — sebuah putusan, daftar file, sebuah diagnostik — dan penolakan juga membawanya ketika operasi memiliki temuan saat menolak, sebagaimana dijelaskan Apa yang dikembalikan build yang ditolak untuk sebuah build.
Hasil terstruktur juga membawa teks, sebagai text_answer. Hasil terstruktur setiap alat memiliki bidang text_answer yang memuat teks jawaban persis seperti yang dibawa teks: setiap kalimat, berurutan, tidak berubah. Dengan begitu, klien yang menyerahkan hasil terstruktur kepada modelnya alih-alih teks, seperti yang dilakukan Claude Desktop, tetap menyerahkan setiap kalimat yang ada dalam teks — baris pembuka jawaban describe-capabilities tanpa argumen, konfigurasi yang berlaku yang dilaporkan config-show, kalimat yang menyebutkan folder yang digunakan sebuah jawaban ketika tidak ada workspace yang ditemukan. text_answer ditulis pertama, sebelum bidang-bidang yang digunakan alat untuk menjawab, dan inilah teks yang diterima pemanggil: melalui HTTP teks ini menyebutkan setiap lokasi di host server sebagaimana teks menyebutkannya, sebagaimana dijelaskan dalam Apa yang dikatakan jawaban tentang sistem file server. Teks itu sendiri tetap berupa prosa, untuk klien yang membacanya, sehingga kata-kata yang sama dikirim dua kali dalam setiap jawaban.
Tidak ada alat yang menjadi pengecualian, termasuk lint. Tidak ada alat yang menjawab dengan bidangnya sendiri yang bernama text_answer, sehingga bidang ini tidak pernah menggantikan bidang lain. Hasil terstruktur lint mempertahankan summary-nya — jumlah entitas yang diperiksa dan jumlah temuan, secara total dan menurut tingkat keparahan, dengan nama-nama yang ditulis aggrega lint dengan -o json — dan membawa text_answer di sampingnya. describe-capabilities juga mempertahankan bidangnya sendiri: version_summary, baris versi saja, ketika tidak diberi argumen, dan di setiap entri index-nya sebuah summary, tujuan alat tersebut dalam satu baris.
Tidak ada alat yang mengiklankan skema output. Daftar sebuah alat membawa skema untuk argumen yang diterimanya dan tidak ada skema untuk hasilnya, sehingga text_answer disebutkan di sini, bukan dalam skema.
Jawaban tanpa hasil terstruktur hanyalah teksnya. Penolakan atas argumen sebuah panggilan, dan kegagalan lain apa pun yang operasinya tidak memiliki apa pun yang terstruktur untuk dilaporkan, kembali sebagai teksnya dan tidak ada yang lain, dan teks tersebut menjadi satu-satunya bagian yang dapat ditunjukkan klien kepada modelnya.
Ketika panggilan tidak berhasil
Di mana jawaban tiba bergantung pada satu hal: apakah pemanggil dapat memperbaikinya dengan mengubah argumen dari alat yang ada.
Segala sesuatu yang dapat diperbaiki dengan cara itu kembali sebagai hasil alat itu sendiri, ditandai sebagai kegagalan dan membawa koreksi sebagai teksnya — kombinasi selektor yang tidak diterima alat, argumen wajib yang terlewat, argumen yang dikirim dengan tipe JSON yang salah, jalur yang tidak ter-resolve, diagnostik dari compiler. Itulah saluran yang ditunjukkan kepada asisten, sehingga asisten membaca apa yang salah dan memanggil lagi dengan argumen yang sudah diperbaiki.
Saluran kesalahan protokol disediakan untuk hal-hal yang tidak memiliki hasil alat untuk ditempati: nama alat yang tidak dilayani server, permintaan yang parameternya tidak dapat dibaca server, metode yang tidak diimplementasikannya, dan pesan yang sama sekali bukan JSON yang valid. Membaca sumber daya dan merender prompt juga menjawab di sana, karena tidak satu pun dari hasil tersebut membawa penanda kegagalannya sendiri.
Skema yang diiklankan sebuah alat juga mendeklarasikan sebagian besar aturan yang harus dipenuhi argumennya — selektor mana yang saling eksklusif, argumen mana yang hanya bermakna bersama argumen lain, dan mana yang wajib — sehingga klien yang menyusun panggilan berdasarkan skema yang dideklarasikan jarang perlu melakukan panggilan untuk mengetahuinya. Aturan yang tidak dinyatakan skema tetap ditolak, dengan kalimat yang menyebutkannya; aturan pull bahwa verify tidak dikombinasikan dengan upgrade_targets atau pin_sources sengaja diserahkan kepada penolakan, karena alasan yang diberikan dalam Me-resolve apa yang menjadi dependensi sebuah Release.
Apa yang menghentikan server
Melalui input dan output standar, menutup koneksi akan menghentikannya. Server membaca satu pesan per baris dan keluar dengan bersih ketika input standarnya mencapai akhir aliran, sehingga klien yang menutup koneksi akan mematikan server. Itulah kasus biasa pada transport tersebut, karena Anda tidak pernah menjalankan perintah itu sendiri: klien yang memulainyalah yang mengakhirinya, sehingga keluar dari editor Anda, atau menonaktifkan server ini untuk sebuah proyek, adalah bentuk penghentian yang biasa.
Meminta proses itu sendiri untuk berhenti menjangkau server pada transport mana pun. Interupsi dari terminal, atau permintaan terminasi dari supervisor atau runtime kontainer, mematikannya pada permintaan pertama, baik ada klien yang sedang mengirim sesuatu maupun tidak: server berhenti menerima pesan, mengakhiri pekerjaan yang sedang dilakukan panggilan yang berjalan, dan keluar dengan bersih. Permintaan kedua langsung mengakhiri proses. Karena itu, melalui input dan output standar, panggilan yang masih berjalan ketika proses diminta berhenti tidak akan selesai; sebaliknya, listener melakukan pengurasan, membiarkan panggilan yang sudah sedang dijawab selesai dalam batas waktu tertentu sebelum proses keluar.
Klien juga dapat menghentikan satu panggilan tanpa menghentikan server, dan caranya bergantung pada transport. Panggilan dijawab secara konkuren, sehingga pengakhiran satu panggilan ditindaklanjuti selagi panggilan itu masih berjalan, bukan menunggu di belakangnya. Melalui input dan output standar, klien menyebutkan id panggilan; membatalkan panggilan yang sudah dijawab, atau panggilan yang tidak sedang dikerjakan server, tidak melakukan apa pun — dan itulah yang membuat pesan seperti itu aman dikirim tanpa terlebih dahulu mengetahui apakah jawabannya sudah dalam perjalanan. Melalui HTTP tidak ada pesan yang perlu dikirim: menutup koneksi yang membawa panggilan akan mengakhirinya. Dalam kedua cara, panggilan diberi tahu untuk berhenti — pekerjaannya berakhir pada titik berikutnya ketika operasi memeriksa, dan operasi yang tidak pernah memeriksa berjalan sampai selesai — tidak ada lagi yang dikirim untuk panggilan tersebut, setiap panggilan lain yang sedang berjalan terus berlanjut, dan server tetap melayani.
Kapan menggunakannya
Gunakan aggrega mcp ketika Anda ingin asisten AI membantu menulis entitas Aggrega berdasarkan skema dan referensi yang sebenarnya — sehingga sarannya berlandaskan struktur persis yang diterima compiler, bukan tebakan. Alat ini cocok langsung dengan siklus penulisan: asisten membaca skema dan referensi sebuah jenis, membuat kerangka, mengisi bidang-bidang yang menjadi milik peran Anda, dan memvalidasi sebelum menyerahkan draf kembali. Lihat Menulis file Aggrega untuk siklus tersebut.
Melalui input dan output standar, Anda biasanya tidak pernah mengetik aggrega mcp sendiri. Sebaliknya, Anda menyebutkannya sekali dalam konfigurasi MCP klien Anda, dan klien memulai serta menghentikannya untuk Anda. Listener adalah kasus lainnya: di sana Andalah yang menjalankan proses, dan proses tersebut terus berjalan untuk pemanggil yang tidak memulainya.
Contoh: konfigurasi klien melalui input dan output standar
Arahkan klien MCP ke perintah tersebut dengan entri server stdio:
{ "mcpServers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}Satu-satunya prasyarat adalah biner aggrega yang terinstal di PATH klien. Untuk jalur konfigurasi per klien dan pemecahan masalah, lihat Menghubungkan server MCP. Untuk mengambil skema langsung dari baris perintah tanpa klien, lihat aggrega get-schema.