aggrega mcp
Yapay zekâ asistanı entegrasyonu için standart girdi ve çıktı ya da HTTP üzerinden bir Model Context Protocol sunucusu çalıştırır
Kullanım
aggrega mcp [flags]Açıklama
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.Bayraklar
| Bayrak | Varsayılan | Açıklama |
|---|---|---|
--listen | — | HTTP aktarımının dinlediği adres; iki biçimden birinde verilir: host:port ya da unix: ve ardından bir dosya sistemi yolu. Nerede dinleneceğini belirtir ve aktarım seçmez: —transport http ile ya da çalışma alanı yapılandırmasındaki mcp.transport: http ile okunur; stdio aktarımıyla verildiğinde ise reddedilir. Sertifikası olmayan bir dinleyici düz metin sunar ve yalnızca geri döngü adresinde (127.0.0.1, ::1, localhost) ya da bir Unix soketinde izin verilir; bu, sonlandırıcı bir vekil sunucunun arkasındaki bir sunucunun aldığı biçimdir. Başka herhangi bir adres mcp.tls.cert_file ve mcp.tls.key_file gerektirir; bu süreç TLS’yi kendisi sonlandırmak için bunları kullanır. Ayarlandığında mcp.listen yapılandırma anahtarını geçersiz kılar. |
--transport | — | Sunucuya nasıl erişileceği: stdio, protokolü standart girdi ve çıktı üzerinden konuşur; bu komutu bir alt süreç olarak başlatan bir istemci sunucuya bu yolla erişir. http ise protokolü —listen ya da mcp.listen ile belirtilen adreste HTTP üzerinden, mcp.tls bir sertifika ve anahtar belirttiğinde de HTTPS üzerinden sunar. Ayarlandığında, varsayılanı stdio olan mcp.transport yapılandırma anahtarını geçersiz kılar. |
Ne yapar
aggrega mcp bir Model Context Protocol sunucusu çalıştırır. Sunucuya iki aktarım yoluyla ulaşılır ve aralarında --transport seçim yapar: stdio veya http; bayrağın geçersiz kıldığı anahtar çalışma alanı yapılandırmasındaki mcp.transport’tur ve varsayılan stdio’dur.
Varsayılan olan stdio üzerinden, sürecin standart girdi ve çıktısı aracılığıyla konuşur. Bu biçimde etkileşimli olarak çalıştırdığınız bir komut değildir: MCP destekli bir istemci onu bir alt süreç olarak başlatır ve protokolü stdio üzerinden konuşur; her istemcinin onu başlatan girdiyi nerede tuttuğu MCP sunucusunu bağlama sayfasında listelenir. Onu çalıştırmak, CLI’ı düzenleyicinizin veya sohbet istemcinizin içinde Aggrega’yı tanıyan bir yazım asistanına dönüştürür.
http üzerinden ise protokolü HTTP ile sunar: bir ana makinede uzun süre çalışan, klavyesinin başında olmayan çağıranların ulaştığı tek bir süreçtir ve --listen’in adlandırdığı adresi, bayrak yoksa mcp.listen’i dinler. Bu dinleyicinin nasıl yapılandırıldığı ve neyi kabul ettiği için Sunucuya HTTPS üzerinden ulaşmak bölümüne bakın.
Protokolün iki revizyonunu, 2026-07-28 ve 2025-06-18’i konuşur; böylece ikisinden birini kullanan bir istemci bağlanır ve aynı yüzeylere ulaşır. Bir çağrının hangisini konuştuğu, bağlantı için bir kez kararlaştırılmak yerine o çağrının üzerinde belirtilir. 2026-07-28 kullanan bir istemci, konuştuğu protokol sürümünü ve kendi yeteneklerini her istekle gönderir ve sunucunun neyi desteklediğini server/discover’a sorar; 2025-06-18 kullanan bir istemci ise aynı şeyleri bağlantıyı bir initialize el sıkışmasıyla açarak bir kez belirler. Her iki durumda da sunucu iletiler arasında hiçbir şey tutmaz; dolayısıyla ilk gönderdiğiniz şey, sonraki bir çağrının nasıl yanıtlanacağı hakkında hiçbir şeye karar vermez. Sunucunun konuşmadığı bir revizyonu adlandıran istek, bunlardan birini istemiş gibi yanıtlanmak yerine reddedilir ve hangi ikisini isteyebileceği kendisine bildirilir.
Sunucu, bağlı asistana üç yüzey sunar:
-
Komut istemleri (prompts): iki aile vardır ve aralarındaki fark her birinin neyi yanıtladığıdır. Yazım istemleri “ne yazıyorum” sorusunu yanıtlar: her rol için bir persona (geliştirici, mimar, operasyon) ile varlığa özgü odaklı bir şablon. Her biri rolü çerçeveler ve asistanı doğru şemaya, başvuru sayfasına ve yazım kılavuzuna yönlendirir; böylece önerileri o rolün sahip olduğu sütunların içinde kalır. İş akışı istemleri “hangi çağrılar, hangi sırayla” sorusunu yanıtlar: her biri, birkaç işlemi kapsayan bir hedefe ulaşan araç çağrılarının sıralı dizisini, aralarındaki karar noktalarıyla birlikte ortaya koyar: sıfırdan yeni bir Aggregate ve onun Release’ini oluşturmak, mevcut bir chart’ı, altyapı modülünü veya container-compose dosyasını Aggrega’ya getirmek, bir derlemenin neden derlenmediğini ya da neden yanlış yapıtları oluşturduğunu bulmak.
prompts/listiki aileyi de listeler veprompts/getbirini oluşturur; böylece küme bu sayfadan değil sunucudan okunur.Bir iş akışı istemi çağrıları adlandırır ve onları siz yaparsınız, birer birer, bir sonrakinden önce her sonucu okuyarak. Bütün bir hedefi gerçekleştiren bir çağrı yoktur: her araç denetleyebileceğiniz tek bir işlemi sarar, dolayısıyla sizi oraya götüren şey dizidir. Yazım personaları odaklanmak için isteğe bağlı bir
kindalır, varlığa özgü şablon bir tane gerektirir ve hiçbir şemanın karşılık gelmediği birkindsessizce yok sayılmak yerine kabul edilen küme listelenerek reddedilir. -
Kaynaklar: satır içinde sunulan salt okunur başvuru malzemesi: bir varlığın JSON Schema’sı için
schema://<kind>, herhangi bir dil başvurusu sayfası içinlangref://<path>, yazım kılavuzu içinauthoring://<topic>, bir katalog varlığının yazılmış YAML’ı içincatalog://<kind>/<name>ve bir komutun kendi yardımı içincli://<command>; giriş noktası tek başınacli://’dir. Bu yardım sunucunun kendi taşıdığı komutlardan yanıtlanır; dolayısıyla birini okumak hiçbir süreç başlatmaz ve komutun--helpiçin yazdırdığı metnin aynısını döndürür. Kataloğun barındırmadığı bir varlığıncatalog://ile okunması bulunamadı olarak yanıtlanır; bunun nedeni varlığı bildiren tam olarak bir katalog dosyasının yükleme sırasında atlanmış olmasıysa, yanıtın iletisi yalnızca URI yerine o dosyayı, çiğnediği kısıtı ve koşulun kısa kodunu belirtir; bu,aggrega buildkomutunun aynı dosya için en başta verdiği rettir.resources/listparametre olmadan adreslenebilenleri listeler veresources/templates/listher ailenin URI biçimini duyurur. -
Araçlar: çalışma alanınıza karşı eylemler;
tools/listhepsiyle yanıt verir.Bir asistanın ilk karşılaştığı araçlar yazım döngüsüne göre biçimlendirilmiştir: çalışma alanının neler içerdiğini bulmak için
list-entitiesvelist-releases; türünün gerektirdiği alanları taşıyan, bir değer gereken her yerde yer tutucu bulunan bir iskelet içinscaffold(ya daexamplegönderildiğinde belgelerin çalıştırılabilir örneklerinden birini yeni bir dizine yazar ve o dizinin nerede olduğunu, yazılan dosyaları ve onu derlemeye yarayan komutları yanıt olarak verir;list: truegönderildiğinde örnekleri listeler); bir varlığın JSON Schema’sı içinget-schema; bir taslağı doğrulamak içinvalidate(taslağın hâlâ taşıdığı her yer tutucuyu ve her birinin ne aldığını adlandırır); bir katalog varlığını ya da kayıt defterinden başvuruyla okunan bir varlığı betimlemek içindescribe; bir Release’in bağımlılıklarını yerel önbelleğe çözümlemek ve kilit dosyasını yazmak içinpull; bir Release’i oluşturulmuş yapıtlarına derlemek içinbuild(varsayılan olarak bellekte, diske hiçbir yapıt yazılmadan;writegönderdiğinizde iseaggrega build’in yazdığı yer olan çalışma alanı kökündekidist/’e yazılır; bağımlılıklar yalnızcaauto_pullgönderirseniz önce çözümlenir); Wasm konuklarından Plugin varlıkları üretmek içingen-catalog; ve bir derleyici tanılamasını uygulanabilir yönergelere genişletmek içinexplain-error: tanılama bir durdurma koşulunun kısa koduyla başladığında bu, o koşulu ve yazım düzeltmesinin yayımlanmış adım adım anlatımını da içerir; bu,aggrega explain’in bir terminalde aynı kod için verdiği genişletmenin aynısıdır.Yüzeyin geri kalanı onun arkasında değil aynı yanıttadır: sunucunun içinde çalışan diğer araçlar (
lint, bir belgedeki bir yerde yazılı bağlantıyı adlandıran araç, iki adaylık aracı, ek kapsayıcısı ve ekleme noktası araçları, bir belgeye sınırlı tek bir düzenleme uygulayan araç, bir varlığın girdileri için içerik sabitlemelerini Bir varlığın kendi girdilerini sabitleme bölümünde anlatıldığı gibi kaydedenpinve aşağıda açıklanan dört yayımlama aracı, ayrıca önbelleklerin ve yapılandırılmış kayıt defterlerinin envanterleri) ve bu sunucuyu standart girdi ve çıktısı üzerinden başlatan bir istemci için, aksi hâlde yazabileceğiniz her komut için çağırma yoluna göre adlandırılmış bir araç. Bu komut araçları yalnızca o aktarımda bulunur: HTTP üzerinden ulaşılan bir sunucu, Sunucuya HTTPS üzerinden ulaşmak altında verilen nedenle bunların hiçbirini sunmaz. Sonraki bir çağrı için hiçbir şey geri tutulmaz. Bir araç listesinin ne kadarının bir modelin önüne konacağı istemcinin vereceği bir karardır: tanımları getirir ve neyi yükleyeceğini seçer; bir istemcinin hiç almadığı bir tanım, o aracın adına iletişim hattı üzerinden ne kadar ulaşılabilir olursa olsun, bir modelin asla çağıramayacağı bir işlemdir. Listenin tamamı istemcinizin alabileceğinden fazlaysa, onu Sunucunun duyurduklarını daraltmak yoluyla kısaltırsınız.describe-capabilitiesbu yüzeyi yazmakta olduğunuz varlık türüne daraltır. Birkindgönderildiğinde, o türe hizmet eden araçlarla yanıt verir; bunlar bir açıklamadaki sözcüklerden değil, her aracın bildirdiği türlerden okunur; hiçbir argüman gönderilmediğinde, bu sunucunun size sunduğu her araç üzerinde aynı dizinle yanıt verir: her birinin adı, tek satırlık amacı, hizmet ettiği türler ve yazıp yazmadığı, argüman şemaları olmadan; böylece yüzeyin tamamı tek bir okunabilir yanıtta gelir. Bircli-aracı için yazıp yazmadığı, çalıştırdığı komutun yazıp yazmadığıdır:cli-buildyazıyor olarak bildirilir, çünkü komut oluşturulmuş yapıtları çalışma alanı kökünün altına kaydeder;cli-scaffoldde yazıyor olarak bildirilir, çünküexamplegönderildiğinde komut belgelerin çalıştırılabilir örneklerinden birini yeni bir dizine yazar; yalnızca okuyan bir komut ise, yol üzerinde makinedeki her projenin paylaştığı bir önbelleği doldursa bile, aynı işlemi sunucunun içinde çalıştıran araç gibi yalnızca okuyor olarak bildirilir; bir veya daha fazlasını adlandırantoolsgönderildiğinde, tam olarak o araçların tam tanımları ve argüman şemalarıyla yanıt verir.cli-araçları hiçbir zaman türe göre daraltılmaz, çünkü bir komutun hangi varlık türüne hizmet ettiğini hiçbir şey kaydetmez; bu yüzden türle sınırlanmış bir yanıt onları dışarıda bırakır ve onları argümansız dizinde okursunuz. Bir komut aracındaki argümanlar komutun kendi bayraklarına göre adlandırılır; dolayısıyla--output-dir,output_dirolarak gönderilir ve tanınmayan bir ad, sessizce düşürülmek yerine kabul edilen yazımlar listelenerek reddedilir.Bazı yetenekler standart girdi ve çıktı üzerinde iki kez bulunur: yazım döngüsüne göre biçimlendirilmiş bir araç işlemi sunucunun içinde çalıştırır, aynı yeteneği taşıyan komutun adını alan araç ise o komutu çalıştırır. İkisi aynı biçimde davranmaz; bu nedenle o aktarımda her biri diğerini adlandırır ve farkı belirtir; HTTP üzerinde komut araçları yoktur ve eşleştirme cümlesi, çağıranın ulaşamayacağı bir aracı göstermek yerine verilmez. Tercih edilmesi gereken, sunucunun içinde çalışandır: okunabilir metnin yanında makinece okunabilir bir sonuç da döndürür; böylece bir asistan bir kararı, bir dosya listesini ya da bir tanılamayı ayrıştırılacak bir döküm olarak değil, alanlar olarak alır. Komut aracı gerçek komutu ayrı bir süreçte başlatır; dolayısıyla o komutun çalıştığı makinede yaptığı her şeyi yapar, komutun yazdığı yerde diske yazmak da dahil —
cli-buildişlenmiş yapıtları çalışma alanı kökündekidist/dizinine, izlenen bir derlemenin dosyalarını da onun yanındaki.trace/dizinine yazar ve döndürdüğü son satır o dizini tam olarak adlandırır — ve yalnızca çalıştırdığı komut satırını ve o komutun yazdırdığı metni döndürür. Komutun tanımladığı ama diğer aracın kabul etmediği bir bayrağa ihtiyaç duyduğunuzda ona başvurun.O komut satırı, komuttan ve çağrının kendi bayraklarından önce, bu sunucunun başlatıldığı ve yapılandırmayı belirleyen genel bayraklarla — verdiyseniz
--configve--offlineile — başlar. Böylece komut, buradaki diğer her aracın okuduğu yapılandırmayı okur:--offlineile başlatılan bir sunucu komutlarını çevrimdışı çalıştırır,--configile başlatılan ise onları o genel dosya üzerinden çalıştırır. Çağrının kendisi için gönderdiği bir bayrak bunlardan sonra gelir ve geçerli olur; dolayısıyla bir çağrıdakioffline: falseyalnızca o çağrı için ağa erişir ve döndürülen komut satırı her ikisini de gösterir. Sunucu bir çalışma alanı köküyle —--workspace-rootile ya daAGGREGA_WORKSPACE_ROOTile — başlatıldıysa komut satırı, o ikisinden önce, bu kökü--workspace-rootolarak vererek başlar; böylece komut, çalışma alanını sunucunun başlatıldığı dizinden bulmak yerine, aynı bayrakla yazıldığında olacağı gibi ve sunucunun içinde çalışan her aracın aldığı gibi o dizini çalışma alanı kökü olarak alır.workspace_rootgönderen bir çağrı kendi kökünü adlandırır ve komut satırı yalnızca onu taşır — boş bir değer de dahil; komut bunu, bir terminalde--workspace-root ""nasıl okunuyorsa öyle okur: çalışma alanını sunucunun başlatıldığı dizinden bul. İkisiyle de başlatılmamış bir sunucu kök vermez; dolayısıyla komutları çalışma alanlarını, Bir çağrının hangi çalışma alanında yanıtlandığı bölümünün her araç için belirttiği kurala göre o dizinden bulur — masaüstü paketinin Workspace folder ayarı boş bırakılarak yapılan başlatması hariç; bu durumda kendi çalışma alanını adlandırmayan bir çağrı hiçbir komut başlatmaz ve o ayarın reddiyle yanıtlanır. Komut, çağrının ya da başlatmanın adlandırdığı çalışma alanı kökünde başlar: çağrının kendiworkspace_rootdeğeri, her aracın okuduğu gibi okunur — mutlak olan gönderildiği gibi, göreli olan ise hiçbir kök belirtmeyen bir çağrının yanıtlandığı kökten — ve komuta mutlak biçimiyle verilir; yoksa sunucunun başlatıldığı kök kullanılır. Böylece bir çağrının okunacak dosya olarak verdiği göreli bir yol —validateiçin bir belge, bir--releaseya da bir--catalog— orada açılmış bir terminalde olduğu gibi o çalışma alanının içinde okunur ve komutun çalıştırdığı bir derlemedist/dizinini o kökün altına yazar. Hiçbir şeyin kök adlandırmadığı durumda — başlatma kökü yoksa veworkspace_rootyoksa ya da boşsa — komut sunucunun başlatıldığı dizinde başlar ve göreli yolu oradan okur; var olmayan bir klasörü adlandıranworkspace_rootokunduğu haliyle — mutlak olan gönderildiği gibi, göreli olan tam biçimiyle — iletilir ve komut onu kendi sözleriyle reddeder. Bir komut uzantısı eklentisinin kaydettiği komuta bunların hiçbiri verilmez; çünkü o komut, bir terminalde de burada olduğu gibi, genel bir bayrağı ayrıştırmak yerine her argümanı okumadan eklentiye iletir; diğer her komutla aynı klasörde başlar.Birkaç komut komut araçlarının var olduğu standart girdi ve çıktıda bile bilinçli olarak yoktur — HTTP üzerinde bunların hepsi yoktur ve bu, herhangi bir komutun değil aktarımın bir özelliğidir. Standart girdi ve çıktıda bunların her biri belirtilmiş bir nedenle dışarıda bırakılır: arka plan hizmeti ve bu sunucunun kendisi hiçbir zaman bir sonuç döndürmez; terminalden parola okuyan bir komutun onu okuyacağı bir yer yoktur; kabuk tamamlama betiği yazan bir komutun onu kuracağı bir kabuk yoktur; depolanmış bir kimlik bilgisini kaldırmak, adlandırdığınız herhangi bir çalışma alanı üzerinde değil makine genelindeki depo üzerinde işlem yapar; etkileşimli olarak kimlik belirteci edinmenin ise sunabileceği etkileşimsiz bir biçimi yoktur. Aynı makine geneli gerekçesiyle
aggrega plugin run-localda yoktur; bu komut, verdiğiniz bir yoldan bir.wasmkonuğu yükler: komutun amacı bir dosyayı nereye koyduysanız oradan okumaktır; dolayısıyla sınırlandırılabileceği bir çalışma alanı yoktur ve okuma, konuk var olmadan önce sürecin kendisinde gerçekleşir. Konuk çalıştığında ona hiçbir şey verilmez — dizin yok, soket yok, ortam yok — ama bu, okuma üzerinde değil modül üzerinde bir sınırdır; dolayısıyla buna karar veren o değildir. Yolu adlandıranın siz olduğunuz terminalinizde çalıştırın. İmzalama ve yayımlama tamamen farklı bir durumdur ve onları bu listenin dışında tutan da bu farktır. Her biri sağlanan ya da ortamdan gelen bir girdiden bir kimlik çözümler ve hiçbiri mevcut değilse açıkça reddeder; dolayısıyla her birinin kimse izlemeden tamamlanan bir biçimi vardır — oysa etkileşimli olarak belirteç edinmek, ilke olarak bile hiçbir girdinin karşılayamayacağı bir eylemdir. Bu yüzden iki kez bulunurlar: komutlar olarak ve Yayımlama, imzalama ve geri çekme altında açıklanan dört süreç içi araç olarak. Komut satırının bir tarayıcı açacağı yerde, orada olmayan bir kişiyi beklemek yerine reddederler ve bunun yerine neyin sağlanması gerektiğini belirtirler.
Bir çağrının hangi çalışma alanında yanıtlandığı
Bir çağrı, çalışma alanını workspace_root ile belirtir; aksi halde sunucunun üzerinde başlatıldığı çalışma alanında yanıtlanır. Başlatma bir kök belirttiyse (--workspace-root veya AGGREGA_WORKSPACE_ROOT ile), bu kök, bayrağın her komutta olduğu gibi, çalışma alanı kökünün kendisidir: üstünde kapsayan bir çalışma alanı aranmaz; bu nedenle başlatma, çalışma alanının .aggrega-config.yaml dosyasını barındıran klasörü belirtir ve bir çağrı hem sunucu içinde çalışan araçlar hem de komut araçları tarafından orada yanıtlanır. Başlatma hiçbir kök belirtmediyse çalışma alanı, sunucunun başlatıldığı dizinden, orada bir terminalde yazılan bir komutun bulduğu biçimde bulunur — sıra The other ways a project root is recognised altında açıklanır —; ancak masaüstü paketinin Workspace folder ayarı boş bırakılmış başlatması bunun dışındadır: bu başlatma, aşağıda açıklandığı gibi, böyle bir çağrıyı reddeder. Göreli bir workspace_root, hiçbir kök belirtmeyen bir çağrının yanıtlandığı kökten okunur — başlatmanın belirttiği kök ya da hiçbiri belirtilmediyse sunucunun başlatıldığı dizinin çözümlendiği çalışma alanı kökü —; böylece bir çağrı, çalışma alanının makinede nerede durduğunu bilmeden quickstart-ai/1 gibi çalışma alanı içindeki bir klasörü belirtir; mutlak olan verildiği gibi kullanılır. Komut araçları da dahil her araç onu böyle okur. Göreli olanın okunacağı bir kök yoksa — var olan bir klasör olmayan bir başlatma kökü ya da Workspace folder boşken yapılan masaüstü başlatması — göreli olan, hiçbir kök belirtmeyen bir çağrı gibi reddedilir. Var olan bir klasörü belirtmeyen ya da bir dosyayı belirten workspace_root, araç başka bir şey yapmadan önce reddedilir; ret, bir komutun --workspace-root değerini reddettiği gibi, argümanı adlandırır ve değeri aktarır — mutlak olanı gönderildiği haliyle, göreli olanı okunduğu tam biçimiyle.
Var olan bir klasör olmayan bir başlatma kökü, standart girdi ve çıktı üzerinden bir ret olarak sunulur. --workspace-root veya AGGREGA_WORKSPACE_ROOT var olmayan bir klasörü ya da bir dosyayı belirttiğinde sunucu, reddi hata akışına yazar ve yine de başlar; böylece kullanıcısına bu akıştan hiçbir şey göstermeyen bir istemci bile nedenini gösterir. Sunucu initialize isteğini ve araç, kaynak ve istem listelerini yanıtlar; o çalışma alanında işlem yapacak her çağrı ise reddle yanıtlanır: bir araç çağrısı başarısız bir sonuç olarak, bir catalog:// varlığının veya bir belgelendirme sayfasının okunması bir hata olarak. Ret, bayrağı ya da değişkeni, onu ayarlayan masaüstü uygulamasının Workspace folder ayarıyla birlikte — Claude Desktop bölümünün açıkladığı ayar — adlandırır ve değeri tam olarak verildiği haliyle aktarır; istemcinin doldurmadan gönderdiği bir değer geldiği haliyle aktarılır ve içindeki hiçbir şey tanınmaz. Bir komut çalıştıran bir araç, kendi çalışma alanını belirtmeyen bir çağrı için hiçbir komut başlatmaz, çünkü o komutun başlayacağı klasör yoktur; aynı retle yanıt verir. Kendi çalışma alanını mutlak bir yolla belirten bir çağrı orada yanıtlanır; onu göreli bir yolla belirten bir çağrının bu yolu okuyacağı bir klasör yoktur ve aynı retle yanıtlanır. Hiçbir çalışma alanında işlem yapmayan şeyler — bir şema, bir istem, bir komutun yardımı — herhangi bir sunucuda olduğu gibi yanıtlanır. Bir dinleyici ise bunun yerine, herhangi bir şey bağlanmadan önce, başlangıçta aynı retle reddedilir; böylece onu denetleyen kişi hatayı, hata aradığı yerde okur.
Workspace folder ayarı boş olan bir masaüstü başlatması da aynı şekilde bir ret olarak sunulur. Masaüstü paketi sunucuya her zaman Workspace folder içinde ne varsa onu taşıyan AGGREGA_WORKSPACE_ROOT değişkenini verir ve yanında AGGREGA_BUNDLE_VERSION değişkenini ayarlar; uygulama ise sunucuyu projenizde değil, kendi seçtiği bir klasörde — çoğunlukla bir sistem klasöründe — başlatır. Bu nedenle --workspace-root olmadan başlatılmış, ortamı AGGREGA_BUNDLE_VERSION ile boş ya da hiç olmayan bir AGGREGA_WORKSPACE_ROOT taşıyan, standart girdi ve çıktı üzerinden çalışan bir sunucu, başlatıldığı klasörden bir çalışma alanı aramaz. Reddi hata akışına yazar ve yine de başlar; var olmayan bir başlatma köküne verdiği gibi yanıt verir: bir çalışma alanında işlem yapacak ve kendi çalışma alanını belirtmeyen her çağrı, masaüstü uygulamasının sunucuyu Workspace folder ayarı boşken başlattığını, dolayısıyla AGGREGA_WORKSPACE_ROOT değişkeninin hiçbir çalışma alanı kökü belirtmediğini söyleyen, Workspace folder ayarını çalışma alanınızın .aggrega-config.yaml dosyasını barındıran klasöre ayarlamanızı isteyen ve sunucu başladıktan sonra ayarlanan bir klasörün, uygulama ayarı sunucuya yalnızca onu başlatırken verdiği için, uzantı kapatılıp yeniden açıldığında ya da uygulama yeniden başlatıldığında etkili olacağını belirten bir retle yanıtlanır. Bir komut çalıştıran bir araç, böyle bir çağrı için hiçbir komut başlatmaz. Kendi çalışma alanını mutlak bir yolla belirten bir çağrı orada yanıtlanır; onu göreli bir yolla belirten bir çağrı ise, bu yolun okunacağı bir Workspace folder olmadığından aynı retle yanıtlanır; hiçbir çalışma alanında işlem yapmayan şeyler herhangi bir sunucuda olduğu gibi yanıtlanır. Sunucu başlatmayı yalnızca AGGREGA_BUNDLE_VERSION ile tanır: böyle bir değişken ayarlamayan bir pakette boş ayar, kök yok olarak okunur; değişkeni elle ayarlayan ve hiçbir kök belirtmeyen bir başlatma ise paketinki gibi reddedilir. Diğer her boş değer yine kök belirtmez — AGGREGA_BUNDLE_VERSION taşımayan bir başlatmadaki boş AGGREGA_WORKSPACE_ROOT, boş yazılmış bir --workspace-root, bir dinleyici, aggrega serve ve diğer tüm komutlar bunu ayarlanmamış olarak okur.
Hiçbir çalışma alanı bulunmadığında ve hiçbiri belirtilmediğinde, çalışma alanıyla ilgili bir yanıt hangi klasörü kullandığını söyler. Başlatma kökü yoksa, çağrıda workspace_root yoksa ve çağrının yanıtlandığı klasörden bir çalışma alanını sabitleyen hiçbir şey yoksa çağrı o klasörde yanıtlanır. Aracın sonucu çalışma alanına bağlıysa — komutları komut satırında uyarı veren araçların aynısı — metni, komut satırının uyarısı olan <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace ile ve çalışma alanınızın .aggrega-config.yaml dosyasını barındıran klasörü belirten workspace_root göndermenizi isteyen bir satırla biter; yapılandırmanın okunması ya da eklenti listesi gibi çalışma alanının belirlemediği bir yanıt, çalışma alanları hakkında hiçbir şey söylemez. Bu cümle yapılandırılmış sonuca kendine ait bir alan eklemez; yapılandırılmış sonuç onu, The two parts of an answer bölümünde açıklandığı gibi, metni tutan text_answer içinde taşır. Bir komutu ayrı bir süreçte çalıştıran bir araç, aynı şeyi söyleyen komutun kendi satırını, komutun yazdırdığı haliyle taşır. Böyle bir klasördeki bir yapıt önbelleğine hiçbir şey yazılmaz: orada bir çekme ya da önce bağımlılıklarını çözmesi istenen bir derleme, herhangi bir şey getirilmeden önce reddedilir; ret klasörü ve iki çıkış yolunu adlandırır — workspace_root göndermek ya da klasöre bir workspace: bloğu taşıyan bir .aggrega-config.yaml vermek. Bir sabitleme ya da bir Recipe veya FeatureRecipe yayımlaması, varlığın tam olarak yazdığı uzak bir kaynağı getireceği yerde — onu sabitlemek ya da sabitlemesini karşılaştırmak için — o kaynak getirilmeden önce aynı şekilde reddedilir; hiçbir şey getirmediği yerde, çünkü varlığın kaynağı yoktur, yereldir ya da koordinatlarını her Release doldurur, başka her yerdeki gibi yanıtlanır. Orada önce hiçbir şeyi çözmeyen bir derleme yine de işler, ancak kilit dosyasının sabitlediği ve önbelleğin artık tutmadığı bir dış girdi yeniden getirilmez: işleme, girdinin yerine, çevrimdışı bir duruşunkinin söylendiği gibi aynı cümle söylenir. HTTP üzerinden hiçbir yanıt bu cümleyi taşımaz: bir dinleyici her zaman kendisine verilen ya da bulduğu bir çalışma alanına hizmet eder. Workspace folder ayarı boş olan masaüstü paketi başlatması da taşımaz; bu başlatma, kendi çalışma alanını belirtmeyen bir çağrıyı başlatıldığı klasörde yanıtlamak yerine reddeder.
Mutlak yolla adlandırdığı bir Release ya da belge hakkındaki bir çağrı, başka hiçbir şey bir çalışma alanı belirlememişse o dosyanın kendi çalışma alanında yanıtlanır. Başlatma hiçbir kök adlandırmamışsa, çağrı workspace_root göndermiyorsa ve sunucunun başlatıldığı dizin hiçbir çalışma alanına bağlanmıyorsa, çalışma alanı o dosyanın bulunduğu klasörden yeniden bulunur ve bunun bulduğu şey — dosyanın ait olduğu proje ya da her şey başarısız olursa o klasör — çağrının yanıtlandığı çalışma alanı olur. Bu, bir terminalde yazılan bir komutun izlediği kuraldır; bu nedenle çağrısı adlandırdığı bir Release ya da varlık belgesi hakkında olan her araç için geçerlidir: bir derleme, bir çekme, bir doğrulama, bir lint, bir açıklama, bir Release’in terimleriyle bir listeleme, bir Release’in grafiğindeki bir düğüm hakkında bir soru, bir sabitleme, bir varlığın yayımlanması, bir düzenleme ve bir belgede okunan bir konum. Bir çağrı hem bir Release’i hem de bir belgeyi adlandırıyorsa Release belirleyicidir. Böylece sunucuyu projenizin dışında başlatmış bir istemci, yine de projenin kendi yapılandırmasından derlenmiş bir Release’e sahip olur. Çağrının adlandırdığı diğer yollar her zamanki gibi okunur — göreli bir yol, sunucunun başlatıldığı dizinden — ve bir komutu ayrı bir süreçte çalıştıran bir araç da aynı çalışma alanından yanıtlanır, çünkü komut aynı dizinde aynı kuralı izler. Başlatmanın adlandırdığı bir kök, çağrının gönderdiği bir workspace_root, kendisi bir çalışma alanının içinde olan bir başlangıç dizini ve göreli bir yolla adlandırılmış bir Release ya da belge olduğu gibi kullanılır. HTTP üzerinden bunların hiçbiri söz konusu olmaz: bir dinleyici her zaman kendisine verilen ya da bulduğu bir çalışma alanına hizmet eder ve bir çağrının adlandırdığı her yol ona görelidir. Workspace folder ayarı boş olan masaüstü paketi başlatmasında da söz konusu olmaz; bu başlatma, kendine ait hiçbir çalışma alanı adlandırmayan bir çağrıyı, hangi dosyayı adlandırırsa adlandırsın reddeder.
Sunucunun duyurduklarını daraltmak
mcp.announce_tools, bu sunucunun duyurduğu araçları, araç listesinin bildirdiği yazımla birebir adlandırır. Anahtar yazılmazsa bu sunucunun taşıdığı her araç duyurulur; bu varsayılandır ve protokolü izleyen bir istemcinin beklediği biçimdir. Bir liste yazılırsa tam olarak o araçlar duyurulur: dışarıda bırakılan bir araç araç listesinde yer almaz, describe-capabilities’in yanıtında yer almaz ve yine de adıyla çağrılırsa reddedilir; ret bu ayarı adlandırır. Boş bir liste yazılırsa hiçbir şey duyurulmaz; dolayısıyla anahtarı yazmamak ile [] yazmak farklı ifadelerdir ve ayar sizin için doldurulan bir varsayılana sahip değildir.
Bu ayarı, diğer uçtaki istemcinin kaydedeceği araç sayısını sınırladığı durumlarda kullanın; bu sınır bazen istemcinin aynı anda bağlı olduğu tüm sunucular genelinde geçerlidir. O istemcinin ihtiyaç duyduğu araçları adlandırın. Bu sınır, ayarın var olma nedeni olan durumdur ve uygulandığı istemci genellikle bu sunucuyu kendi standart girdi ve çıktısı üzerinden başlatan istemcidir; bu nedenle http aktarımının başlattığı dinleyiciyi yapılandıran mcp bloğunun geri kalanından farklı olarak bu anahtar, sunucu hangi aktarımı kullanırsa kullansın okunur.
Bu ayar yalnızca duyurulanı daraltır, başka bir şey yapmaz. Bir aracı burada adlandırmak hiçbir şeyi genişletmez. Bir yeteneği tamamen geri çeken mcp.deny_reach’i kaldırmaz; dolayısıyla burada adlandırılan ve o ayarın geri çektiği türden bir araç listenin dışında kalır ve o ayar adlandırılarak reddedilir. Çağıranın belirtecinin taşıdığı kapsamları da kaldırmaz: burada adlandırılan bir araç bu kapsamlar ne olursa olsun listelenir ve kapsamların izin vermediği bir çağrı, izin verecek kapsam adlandırılarak yine reddedilir. Her iki durumda da çağıranın karşılaştığı ret, bu sınırın değil o diğer sınırın reddidir. Bu ayardan gelen bir ret hiçbir sınama taşımaz ve hiçbir kapsamı adlandırmaz; çünkü hiçbir kimlik bilgisi bir sunucunun sunmayı seçtiği şeyi değiştirmez. Bunun yerine adlandırdığı şey ayardır; reddi okuyan herkesin üzerinde işlem yapabileceği tek şey de budur.
Her ad, bu ikili dosyanın taşıdığı bir araca ait olmalıdır. Hiçbir aracın karşılık gelmediği bir ad, sunucuyu herhangi bir şey sunmadan önce durdurur ve ret, sunucunun sahip olduğu araçları listeler; böylece bir yazım hatası, istediğinizden sessizce daha dar bir yüzeyle değil, başlangıçta fark edilir. Ayrı bir süreçte bir aggrega komutu çalıştıran cli- ailesindeki bir ad her iki aktarımda da kabul edilir ve HTTP üzerinden hiçbir şey duyurmaz; çünkü orada böyle bir araç zaten hiçbir çağırana sunulmaz.
Duyurulan küme süreç başladığında sabitlenir; bu nedenle onu değiştirmek yeniden başlatma gerektirir ve zaten bağlanmış bir istemcinin altında listeyi hiçbir şey büyütmez.
Sunucunun hangi sürümden geldiği
Argümansız gönderilen describe-capabilities, bu sunucunun hangi sürümden geldiğini söyler. Yapılandırılmış yanıtı server_version alanını taşır; bu, aggrega yürütülebilir dosyasının kendisi için bildirdiği sürümdür, yani aggrega version komutunun aynı dosya için yazdırdığı sürüm. Metni ise dizinden önce bu sürümü adlandıran tek bir satırla başlar. Yapılandırılmış yanıt aynı satırı kelimesi kelimesine version_summary olarak taşır; böylece modele yalnızca yapılandırılmış yanıtı veren bir istemci bu satırı da vermiş olur.
Sunucuyu masaüstü paketi başlattıysa, aynı yanıt bunun yanında paketin sürümünü de adlandırır. Paket bir program taşımaz: Path to the aggrega executable ayarının adlandırdığı aggrega yürütülebilir dosyası hangisiyse onu başlatır (varsayılan olarak bu aggrega komut adıdır ve uygulama onu kendi PATH’inde arar); dolayısıyla paket ve yürütülebilir dosya ayrı ayrı kurulur ve farklı sürümlerden gelebilir, paketi listeleyen uygulama ise yalnızca paketin kendi sürümünü gösterir. Paket, sürümünü sunucuya ortamında AGGREGA_BUNDLE_VERSION olarak iletir; sunucu bunu başlarken bir kez okur ve yanıt bunu bundle_version olarak taşır. İkisi tam yazıldığı gibi karşılaştırılır; bu adil bir karşılaştırmadır, çünkü aynı sürümün paketi ve yürütülebilir dosyası o sürümün numarasıyla aynı biçimde damgalanır, bir geliştirme derlemesi ise her sürümden farklı okunur. İkisi eşitse satır ikisini de adlandırır ve başka bir şey söylemez. Farklıysa satır, ikisini de adlandırarak, yürütülebilir dosya ile paketin farklı sürümlerden geldiğini söyler; sunucunun bağlanan bir modele sunduğu yönlendirme de aynı cümleyle başlar, böylece fark model sormadan önce önüne konmuş olur.
Hiçbir paketin başlatmadığı bir sunucu yalnızca kendi sürümünü bildirir. Bir terminalden, bir düzenleyicinin yapılandırmasından ya da bir dinleyici olarak başlatılan sunucu, ortamında bu değişkeni bir şey ayarlamadıkça bundle_version taşımaz. Standart girdi ve çıktı üzerinden çalışan ve değişkeni taşıyan bir sunucu, bir açıdan daha paketin başlattığı sunucu sayılır: kendisine kök adlandırılmamışsa, Bir çağrının hangi çalışma alanında yanıtlandığı bölümünde anlatıldığı gibi boş Workspace folder ayarını reddeder. kind ya da tools gönderilen bir describe-capabilities çağrısı server_version, bundle_version veya version_summary taşımaz ve böyle bir satır içermez, çünkü sunucu hakkında değil araçlar hakkında yanıt verir.
Bir fark bildirilir, asla reddedilmez. Sunucu başlar ve her çağrıyı, ikisi uyumlu olsaydı nasıl yanıtlayacaksa tam öyle yanıtlar. Farkın bir masaüstü kurulumu için ne anlama geldiği ve ikisinin nasıl uyumlu hale getirileceği MCP sunucusunu bağlama sayfasındadır.
Sunucuya HTTPS üzerinden erişmek
aggrega mcp --transport http, protokolü standart girdi ve çıktı yerine HTTP üzerinden sunar. Çalışma alanı yapılandırmasındaki mcp.transport, bu bayrağın geçersiz kıldığı anahtardır ve varsayılan değeri olan stdio, komutu başlatan bir istemcinin beklediği değerdir; dolayısıyla başkalarının eriştiği bir sunucu yapılandırmasında transport: http taşır ve bu yapılandırmanın kapsadığı bir dizinden başlatılan bir istemci sunucuya yine kendi akışları üzerinden erişir. Her iki durumda da sunucu aynıdır (aynı çalışma alanı ve aynı protokol yüzeyleri); değişen, bir mesajın sunucuya nasıl ulaştığı, bir çağrının nasıl sona erdiği ve sunucuyu çalıştıran kişinin neye sahip olması gerektiğidir. Bu bölüm, bir operatörün yapılandırdıklarını anlatır; bir istemcinin çalışan bir sunucuya erişmek için ihtiyaç duyduğu girdi MCP sunucusunu bağlama sayfasındadır.
Bir adres taşıma yöntemi seçmez. --listen <address> ya da bayrak yoksa mcp.listen, http seçildiğinde dinleyicinin nereye bağlanacağını belirtir, başka bir şey değil. Bu nedenle ikisinden de adres gelmeden http seçilmesi, hiçbir şey bağlanmadan önce reddedilir ve ret mesajı ikisini de belirtir. Taşıma yöntemi stdio iken (--transport stdio olarak yazılmış, mcp.transport: stdio olarak yapılandırılmış ya da varsayılan olarak bırakılmış olsun) yazılan --listen de reddedilir ve o adreste hizmet verecek bayrak olarak --transport http belirtilir; boş bir değer verilen --listen ise taşıma yöntemi ne olursa olsun adres belirtmediği gerekçesiyle reddedilir. Yalnızca yapılandırmanın belirttiği bir adres ise kendi akışları üzerinden konuşan bir sunucu tarafından kullanılmadan bırakılır; sunucu bunu hata akışında tek bir satırla, adresi ayarlayan dosyayı ve mcp.transport: http ifadesini belirterek bildirir. Bu son durum bilerek hiçbir yerde reddedilmez: bu, bir istemcinin komutu yapılandırması bir dinleyicinin ayarlarını taşıyan bir dizinde başlattığında yaptığı başlatmadır; transport: http ifadesini unutan bir dinleyici yapılandırması ise hiç dinleyici başlatmaz ve sorun tam da orada görülür.
HTTP üzerinden erişilen bir sunucu, ayrı bir süreçte aggrega komutu çalıştıran hiçbir araç sunmaz. Bu araçlar yalnızca bu sunucuyu kendi makinesinde standart girdi ve çıktı üzerinden başlatan bir istemci için vardır; orada bir klasörü ya da bayrağı belirtmek, çağırana zaten sahip olmadığı hiçbir şeyi vermez. HTTP üzerinden sunucuya erişen bir çağıran, sunucunun çalıştığı ana makinenin sahibi değildir; bu nedenle o ana makinenin dosya sistemi üzerinde sunucunun kendi yetkisiyle işlem yapacak bir komut, bunun yerine ana makinedeki bir terminalde çalıştırılır. Araçlar sunulup reddedilmek yerine listede ve describe-capabilities içinde hiç yer almaz; bunlardan birini belirten bir çağrı da bunu bildiren bir hatayla yanıtlanır. Bu bir ayar değil, taşıma yönteminin bir özelliğidir: onları geri getiren bir yapılandırma yoktur.
Bir sunucu dağıtmadan önce Kimlik bilgisi olmadan hiçbir şey sunulmaz bölümünü okuyun. Uç noktaya yapılan her istek bir kimlik bilgisi taşır ve kimlik bilgisi olmayan bir isteğe hizmet veren bir ayar yoktur; bir ayarın seçtiği şey, bu sunucunun bir bearer token’ı kendisinin mi denetleyeceği yoksa önündeki bir proxy’nin zaten denetlediği çağıranı mı okuyacağıdır.
İki dağıtım biçimi
Süreç TLS’i kendisi sonlandırır. mcp.tls.cert_file anahtarını bir PEM sertifika zincirine, mcp.tls.key_file anahtarını da onun özel anahtarına ayarlayın; dinleyici, verdiğiniz adres her neyse orada doğrudan HTTPS sunar. Her iki dosya da süreç başladığında okunur; bu nedenle değiştirilen bir sertifika, süreç yeniden başlatılarak devreye alınır. Birini diğeri olmadan ayarlamak, bir geri dönüşe başvurmak yerine başlangıçta reddedilir: anahtarı olmayan bir sertifika sunulamaz, sertifikası olmayan bir anahtar hiçbir şeyi belirtmez ve bir yoldaki yazım hatası, şifrelenmemiş trafik sunmaya başlamak için bir gerekçe değildir.
Öndeki bir proxy TLS’i sonlandırır ve sınırlandırılmış bir dinleyiciye iletir. Her iki anahtarı da ayarlanmamış bırakın; dinleyici düz metin sunar ve bu yalnızca loopback’te ya da bir Unix soketinde kabul edilir; böylece o ana makinede olmayan hiçbir şey ona erişemez. Bu, bir ters proxy’nin, bir sidecar’ın ya da bir service mesh’in kullandığı biçimdir ve sertifikanın bu sürecin içinde değil, önünde bulunduğu biçim de budur.
Başka herhangi bir adresteki düz metin dinleyici, hiçbir şey bağlanmadan önce reddedilir ve ret mesajı her iki TLS anahtarını da belirtir. Bunu kaldıran bir ayar ve istisna olan bir adres yoktur: kendi sertifikası olmadan ağdan bağlantı kabul eden bir dinleyici asla güvenli değildir; bu nedenle süreç o biçimde başlamak yerine başlamayı reddeder.
Adres biçimleri
--listen ve mcp.listen iki biçimden birini alır:
host:port:127.0.0.1:7777ya da0.0.0.0:8443gibi bir TCP adresi. Loopback;127.0.0.1,::1ya da o adın çözümlendiği her adres bir loopback adresi olduğundalocalhostanlamına gelir. Bunların dışındaki her şey bir ağ adresidir ve sertifika gerektirir: makinenin sahip olduğu her arabirim anlamına gelen boş bir ana makine; belirli bir arabirim adresi; ve şu anda bir loopback adresine çözümlenen bir ad bile olsa başka herhangi bir ad; çünkü bir dinleyicinin nereye bağlanabileceği, altında değişebilecek bir çözümlemeye bağlı olmamalıdır.unix:ve ardından bir dosya sistemi yolu:unix:/run/aggrega/mcp.sockgibi bir Unix etki alanı soketi. Bir sokete yalnızca bulunduğu ana makineden erişilebilir; bu nedenle sertifika gerektirmez.
Bir soket yolu, göreli olanlar da dahil olmak üzere tam olarak yazıldığı gibi alınır. Onu bildiren yapılandırma dosyasına göre bilerek çözümlenmez, çünkü aynı adres bildiren bir dosyası olmayan --listen üzerinden de gelir; bkz. göreli bir yolun nereyi gösterdiği.
Dinleyicinin kabul ettikleri
POST kabul eden tek bir uç nokta: /mcp. Her JSON-RPC mesajı kendi isteğidir ve hiçbir türde oturum tutulmaz: bir istemcinin önce gönderdiği hiçbir şey sonraki bir isteğin nasıl yanıtlanacağını belirlemez, hiçbir zaman oturum tanımlayıcısı üretilmez ve bir istemcinin gönderdiği oturum ya da akış sürdürme başlığı yok sayılır. O uç noktadaki başka herhangi bir yöntem Allow: POST ile 405, başka herhangi bir yol ise 404 olarak yanıtlanır; her ikisi de kimlik bilgisi denetiminden önce belirlenir, böylece yoklama, zaten hiçbir şey sunmayacak bir yol ya da yöntemdeki bir sınamadan hiçbir şey öğrenmez.
Bir istek tek bir JSON nesnesi ve bir durum koduyla yanıtlanır; çağrı o nesneye giden yolda ilerleme bildirdiyse, Uzun bir çağrının nasıl gittiğinin bildirilmesi bölümünde açıklandığı gibi, o nesneyle biten bir olay akışıyla yanıtlanır. Bir bildirim (id taşımayan bir mesaj) boş bir gövdeyle 202 olarak yanıtlanır. Bir JSON-RPC yanıtı da dahil olmak üzere ikisi de olmayan bir mesaj 400 olarak yanıtlanır, çünkü bir istemci bu sunucuya istekler ve bildirimler gönderir, başka bir şey göndermez.
Her iki protokol revizyonu da burada standart girdi ve çıktı üzerinden olduğu gibi aynen sunulur. Bir 2026-07-28 isteği, bir aracının gövdeyi ayrıştırmadan yönlendirebilmesi için gövdesini taşıma başlıklarına yansıtır: MCP-Protocol-Version gövdenin belirttiği revizyonu, Mcp-Method gövdenin adlandırdığı yöntemi, Mcp-Name ise bir hedefi adıyla belirten yöntemler için o hedefi taşır. Gövdeyle çelişen bir başlık 400 olarak yanıtlanır. Bir 2025-06-18 istemcisi, durumsuz olarak yanıtlanan bir initialize el sıkışmasıyla başlar; bu revizyonu belirten sürüm başlığını taşıyabilir ya da atlayabilir. Sunucunun konuşmadığı bir revizyonu belirten bir istek, konuştuğu iki revizyonu listeleyen bir 400 ile, sunmadığı bir yöntemi belirten bir istek ise 404 ile yanıtlanır.
mcp.allowed_origins yalnızca bir istek Origin başlığı taşıdığında dikkate alınır; bu da pratikte isteği bir tarayıcının gönderdiği anlamına gelir: listede bulunmayan bir kaynağı belirten bir istek 403 olarak yanıtlanır, böyle bir başlık taşımayan bir istek ise sunulur. Tarayıcı olmayan bir istemci böyle bir başlık göndermez ve bir girdiye ihtiyaç duymaz. Tarayıcı tabanlı bir istemci ise her zaman bir girdiye ihtiyaç duyar: liste, bir operatör yazana kadar boştur; bu nedenle o zamana kadar hiçbir kaynak bulunmaz ve uç noktanın kendi adresinde sunulan bir sayfadan gelen de dahil her tarayıcı isteği 403 olarak yanıtlanır. Girdi başlıkla tam olarak karşılaştırılır; bu yüzden bir tarayıcının kaynak gönderdiği biçimde yazılır: küçük harfli bir şema, ://, küçük harfli bir ana makine ve şemanın varsayılanı değilse : ile bağlantı noktası, örneğin https://app.example.com. Yol, sonda /, şema eksikliği ya da büyük harf içeren bir girdi, asla eşleşemeyeceği için yapılandırma yüklendiğinde girdi belirtilerek reddedilir.
mcp.limits, kabul edilen trafiği sınırlar. max_body_bytes değerini aşan bir gövde 413 olarak yanıtlanır ve sınırın ötesinde okunmaz. Halihazırda max_concurrent_requests kadar istek işlenirken gelen bir istek, göremediği işlerin arkasında kuyruğa alınmak yerine 503 olarak yanıtlanır. Bir dakika içinde requests_per_minute değerinden fazla istek gönderen bir çağıran 429 olarak yanıtlanır; bu yalnızca o çağırana karşı sayılır, böylece yoğun istek gönderen bir çağıran başka birine hiçbir şey kaybettirmez. Her sınırın varsayılanı yapılandırma başvurusunda anahtarının yanında belirtilir ve hiçbirinin onu kapatan bir değeri yoktur.
Bir süreç, bir çalışma alanı
Hizmet veren bir sürecin yanıt verdiği çalışma alanı, süreç başladığında sabitlenir. --workspace-root onu adlandırır; bayrak yoksa AGGREGA_WORKSPACE_ROOT değişkeni onu sağlar. Adlandırılan klasör çalışma alanı kökünün kendisidir, üstünde hiçbir şey aranmaz ve var olmayan bir klasör reddedilir; ret, ikisinden hangisi sağladıysa onu adlandırır ve değeri verildiği gibi aktarır — bir dinleyicide bağlanmadan önce, standart giriş ve çıkış üzerindeki bir sunucuda ise o çalışma alanında işlem yapan her çağrıya verdiği yanıtta, Bir çağrının hangi çalışma alanında yanıtlandığı bölümünde açıklandığı gibi — böylece elle yazılmak yerine bir istemci tarafından oluşturulan bir başlatma da kendisine ne verildiğini yine söyler. İkisi de yoksa standart giriş ve çıkış üzerindeki bir sunucu, çalışma alanını başlatıldığı dizinden çözer — orada bir çalışma alanını sabitleyen hiçbir şey yoksa çalışma alanıyla ilgili her yanıt hangi klasörü kullandığını söyler ve masaüstü paketinin Workspace folder ayarı boş olan başlatması bunun yerine kendine ait bir çalışma alanı adlandırmayan çağrıyı reddeder, Bir çağrının hangi çalışma alanında yanıtlandığı bölümünde açıklandığı gibi — ve bir dinleyici, orada bir çalışma alanı çözülmedikçe bağlanmadan önce reddedilir — HTTP üzerinden erişilen bir süreç makineyi göremeyen çağıranlara yanıt verir, bu yüzden rastgele başlatıldığı dizine değil, bir operatörün seçtiği çalışma alanına hizmet eder. Birden çok projeye hizmet vermek için her proje kökü başına bir süreç çalıştırın.
HTTP üzerinden gelen bir çağrı kendine ait bir çalışma alanı adlandıramaz. workspace_root ve catalog_dirs, sessizce yok sayılmak yerine gönderilen argüman adlandırılarak reddedilir: sessizce yok sayılan bir argüman, göndericisine tam olarak dikkate alınmış bir argüman gibi görünür. Hizmet verilen çalışma alanının yanında aranan katalog dizinleri, o çalışma alanının kendi workspace.catalog_dirs ayarıdır — ya da workspace.releases altında kendine ait dizinler verdiği bir Release için o Release’inkidir — ve bunu operatör yazar. Standart giriş ve çıkış üzerinden her iki argüman da dikkate alınır, çünkü sunucuyu başlatan istemci çağıranın kendi makinesinde çalışmaktadır. Orada bir catalog_dirs girdisi mutlaktır ya da göreli bir release’in okunduğu çalışma alanı köküne görelidir — çağrının kendi workspace_root’unun, başlatmanın veya sunucunun başlatıldığı dizinin önce belirlediği kök; mutlak olarak adlandırılmış bir Release çağrıyı o Release’in kendi çalışma alanına taşıdığında da okumanın sürdüğü kök budur — ve bu, farklı bir yerdeyse sunucunun çalıştığı dizine göreli değildir.
Bir çağrının adlandırdığı yol da o çalışma alanının içinde kalır. HTTP üzerinden bir yol argümanı çalışma alanı köküne göre çözülür ve kökün dışına uzanıyorsa reddedilir — çalışma alanından dışarı tırmanan göreli bir yol, başka bir yeri adlandıran mutlak bir yol ve çalışma alanındaki bir dosyaya ya da dizine yönelen bir bağlantı üzerinden çalışma alanının dışına çıkan göreli bir yol, her biri argümanı adlandıran, ancak ne çalışma alanı kökünü ne de yolun ulaşacağı yeri adlandıran bir hata olarak döner; göreli bir yol gönderdiğiniz gibi aktarılır. Her yol argümanı, araç onu okusun ya da yazsın, Çalışma alanı sınırı bölümünün belirttiği “içeride” tanımına göre nereye çıktığıyla değerlendirilir — gen-catalog’un çıktısını yazdığı dizin, edit-document’in geri yazdığı belge ve pin’in kilidini yanına yazdığı varlık, bir aracın okuduğu belge kadar buna tabidir — bu nedenle çalışma alanının dışına çıkan bir bağlantının altında henüz oluşturulmamış bir yol, o bağlantı gibi reddedilir ve hiçbir şey okunmaz ya da yazılmaz. Hizmet verilen çalışma alanının yapılandırmasının build.authoring_release olarak ya da workspace.releases’in bir anahtarı olarak adlandırdığı bir Release’i adlandıran bir release, o yapılandırma üzerinden erişilir ve dosyası nerede olursa olsun bir bağlantı üzerinden kabul edilir; başka hiçbir argümanın bu istisnası yoktur. Kastettiğiniz yol o çalışma alanının içindeyse ama mutlak olarak yazılmışsa ret, bunun yerine göndermeniz gereken köke göreli yazımı verir; böylece yanlış biçimi tahmin eden bir çağırana yalnızca yanlış olduğu değil, doğru biçim de söylenir. Bu, bir çağrının konusu olarak adlandırdığı yollar — doğrulanacak belge, derlenecek Release, bir üretimin çıktısını yazdığı dizin — için geçerlidir ve bir aracın yazdığı yollar için de okuduğu yollar kadar geçerlidir: sunucuya ağ üzerinden erişen bir çağıran, göremediği bir makineden dosya okumasını ve yazmasını istemektedir ve bu okuma ile yazma, operatörün seçtiği çalışma alanında tutulur. Standart giriş ve çıkış üzerinden her aracın yol argümanları, aşağıda o araç altında açıklanan sözleşmeyi korur; orada bir yol mutlak olabilir ve çalışma alanının dışını gösterebilir — çağıran kişi sunucunun çalıştığı makinenin sahibidir, bu yüzden onu kendi seçtiği bir dizine kısıtlamak hiçbir şey kazandırmaz. İşlemi yalnızca çalışma alanının taşıdığı bir belge hakkında yanıt veren iki araç, insertion-point ve edit-document, bunu her iki aktarımda da korur ve çalışma alanının dışındaki bir belgeyi, ister o şekilde yazılmış olsun ister dışarı çıkan bir bağlantı üzerinden erişilmiş olsun, reddeder. Standart giriş ve çıkış üzerinden dikkate alınan, bir çağrının adlandırdığı yoldur ve ötesinde hiçbir şey değildir. İşlemin daha sonra kendi hesabına okuduğu ve yazdığı şeyler, her iki aktarımda da aynı komut bir terminalde yazıldığında olduğu gibi tutulur: bir tarama ya da arama, çalışma alanının dışına çıkan bir bağlantı üzerinden okuma yapmaz; çalışma alanındaki bir Release’in ya da onun Manifest’inin bir yolla adlandırdığı dosya çalışma alanının dışından okunmaz — ve çağrının çalışma alanı dışında adlandırdığı bir Release’in adlandırdığı dosya, o Release’i barındıran dizinin dışından okunmaz — ve bir dizinin altına yazılan dosya — çalışma alanı ya da çağrının adlandırdığı bir dizin — o dizinin içinde kalır. Çalışma alanı sınırı bölümü iki aktarımı komut satırı ve düzenleyiciyle yan yana koyar ve standart giriş ve çıkış üzerinden neyin açık kaldığını belirtir: klonladığınız bir çalışma alanındaki bir belge, bir asistanı çalışma alanının dışında bir yol adlandırmaya yönlendirebilir ve o yol adlandırıldığı gibi dikkate alınır.
Bir yanıtın sunucunun dosya sistemi hakkında söyledikleri
HTTP üzerinden bir yanıt, sunucunun dosya sistemindeki bir yeri çalışma alanı köküne göreli olarak adlandırır ya da gizli tutar. Sunucuyu başlatan bir istemci, sunucunun çalıştığı yerde çalışır; bu nedenle standart girdi ve çıktı üzerinden her yanıt her yeri işlemin tuttuğu biçimde adlandırır — böyle tutuluyorsa mutlak olarak — ve her biri o çağıranın zaten sahip olduğu bir yerdir. Bir dinleyiciye ulaşan çağıran bu yerlerin hiçbirini seçmemiştir ve onları açamaz; bunları ona yayımlamış bir sunucu da yayımlamayı geri alamaz. Bu nedenle HTTP üzerinden bir yanıt, o çağırana bir yer hakkında iki şeyden birini söyler:
- Çalışma alanının içindeki bir yer, çalışma alanı köküne göreli olarak adlandırılır — gönderdiğiniz bir yolun aldığı biçimin aynısıdır; böylece bir yanıttan okunan bir ad, bir sonraki çağrıda değiştirilmeden geri gönderilebilir. Kökteki bir Release
release.yaml’dır ve kilit dosyasırelease.lock’tur. - Çalışma alanının dışındaki bir yer gizli tutulur; çalışma alanı kökünün kendisi de öyle. Alan hiçbir değer taşımaz —
null’dır ya da dışarıda bırakılır; yanıtı her yüzeyin bildirdiği biçimi koruyanattachment-container’da isefileboş bırakılır — ve yanında, alanın adına_withheldeklenerek adlandırılan bir işaret, alanın ayarlanmamış değil gizli tutulmuş olduğunu söyler:workspace_rootyanındaworkspace_root_withheld,fileyanındafile_withheld. Bir işaret yalnızca bir şeyin gizli tutulduğu yerde bulunur. Kök gizli tutulur, çünkü bir dinleyici tam olarak tek bir çalışma alanına hizmet eder; dolayısıyla o çalışma alanının nerede durduğu, içindekini adlandırmak için ihtiyaç duyduğunuz hiçbir şeyi adlandırmaz.
Bir yerin içeride olup olmadığı, ulaştığı dosyaya göre değil, nasıl yazıldığına göre değerlendirilir. Sunucunun başlatıldığı kök yerine bir sembolik bağlantının hedefi üzerinden yazılmış bir yol ve kökten dışarı çıkıp geri giren bir yol, her biri çalışma alanının dışında sayılır ve gizli tutulur. Değerlendirme, çalışma alanının dışındaki bir yeri adlandırma yönünde değil, her zaman size daha az söyleme yönünde yanılır.
HTTP üzerinden bir yanıtın okunabilir metni de aynı kuralı izler. Metin, bir tanılama satırı ya da bir hatanın mesajı çalışma alanının tuttuğu bir yeri adlandırdığında — kökünü ya da altındaki herhangi bir şeyi, yapılandırmasının okunduğu bir config dosyasını, kataloğunun okunduğu bir dizini — o yer köke göreli olarak yazılır; çalışma alanının dışında kalıyorsa ya da kökün kendisiyse (location withheld) olarak okunur. Bir yanıtın kendi çalışma alanı hakkında oluşturduğu metin, onu bu sunucunun hizmet ettiği çalışma alanı olarak anar. Bir işlemin bir mesaja yazdığı, bunların tümünün dışındaki bir yer, bir yer olarak tanınmaz ve size yazıldığı gibi ulaşır.
HTTP üzerinden bunun ulaştığı yanıtlar:
list-entities,list-releases,cache-status,registry-list,search,attach-candidates,connection-candidates,insertion-point,attachment-container,connection-at-positionveedit-document,workspace_root’u gizli tutar. Bunların zaten köke göreli verdiği yollar — bir varlığın kaynak dosyası, bir Release’in yolu velockfilesaltındaki kilit dosyası, bir ekleme noktasının ya da bir düzenlemenin ilgili olduğu belge, bir düzenlemenin yazdığı dosyalar — her iki aktarımda da aynı okunur.cache-status, sunucunun kendi ana makinesindeki bir dosyadan yüklediği bir eklentiyi adlandıran şeyi de gizli tutar. Böyle bir kimlikprovenance[].identitiesiçindeki yerindenullolur, diğer her kimlik konumunu korur ve girdiidentities_withheldolarak işaretlenir. Derlenmiş bir modülünnote’u, modülün derlendiği kimlikleri adlandıran tek bir cümledir; bu nedenle bunlardan herhangi biri böyle bir dosyayı adlandırıyorsanotebütünüyle dışarıda bırakılır venote_withheldolarak işaretlenir; modülündigest’i yine yerindedir. Bir kayıt defteri başvurusunu ya da bir Plugin varlığını adlandıran bir kimlik bütünüyle yanıtlanır; yalnızca bunları adlandıran birnoteda öyle. Bir kaynak yapıtınlabel’ı, önbellekteki yeridir ve çözümlendiği URL’nin ana makinesi ile yolundan yazılır; bu nedenle sunucunun kendi dosya sisteminden — birfile://URL’si ya da bir yol aracılığıyla — okunan bir depo içinlabeldışarıda bırakılır velabel_withheldolarak işaretlenir,sizevedigestyine yerindedir; bir ağ ana makinesini adlandıran birlabelise bütünüyle yanıtlanır. Listenin metni, böyle bir yeri adlandıracağı yerde(location withheld)olarak okunur.validate,target’ı ve bir Release içinrelease’i köke göreli olarak adlandırır; kataloğun tamamı içintargetköktür ve gizli tutulur.diagnosticsya danoticesiçindeki bir yer, metin kuralını izler.build,release’i köke göreli olarak adlandırır ve bağımlılıklarını önce çözümlemiş bir derleme,dependency_resolution’ıpull’un yanıtladığı biçimde taşır.writegönderilmiş bir derleme, yazdığı dizinioutput_dirolarak adlandırır; bu, köke göreli olarakdistokunur vefilesiçindeki her yol o dizine görelidir. Birrefusalve onunfindings’inin her girdisi,file’ını köke göreli olarak adlandırır ya da belge çalışma alanının dışındaysa gizli tutar.advisories,deprecations,declined_external_inputsverefusal’ın hermessage’ı metin kuralını izler.pull,release’i velockfile’ı köke göreli olarak adlandırır.diagnosticsveincomplete_external_inputsmetin kuralını izler. Herresolvedgirdisininsource’u her iki aktarımda da bütünüyle yanıtlanır: çalıştırmanın ne yaptığını adlandırır, hiçbir zaman ana makinedeki bir yeri değil.describe, bir Release’inrelease’ini köke göreli olarak adlandırır; bir varlığınfile’ını ise belgesi çalışma alanının içindeyse köke göreli olarak adlandırır; çalışma alanının dışındaki bir katalog dizininden okunan bir varlığınfile’ı gizli tutulur.mapping_diagnosticsvedeprecationsmetin kuralını izler.lint, her bulgununlocation.file’ını köke göreli olarak adlandırır ya da varlık çalışma alanının dışındaysa gizli tutar. Bir bulgununmessage’ı vesuggest’i metin kuralını izler.pin,entity’yi velock’u köke göreli olarak adlandırır; bir yayımın taşıdığıpinde öyle.gen-catalog,outputiçinde listelenen her dosyayı köke göreli olarak adlandırır.import,workspace_root’u ve taslaklar o köke gittiyseoutput_dir’ı gizli tutar;output_diriçinde adlandırdığınız bir dizin, köke göreli adıyla bildirilir.writtenvedraftsiçindeki her taslak yoluoutput_dir’a görelidir; böylece taslakların nereye gittiği her iki durumda da yanıtta yer alır. Bir tanılamanınmessage’ı ile bir kararınparams_summary,rationaleveswap_hint’i, içe aktarıcının oluşturduğu düzyazıdır ve metin kuralını izler.config-showveplugin-listkökten fazlasını gizli tutar, çünkü bildirdiklerinin çoğu yerleri adlandıran yapılandırmadır; What a listener does not tell you about its host (Bir dinleyicinin ana makinesi hakkında size söylemedikleri) bunu açıklar.- Bir örnek yazan
scaffold,dirdeğerini gönderdiğiniz gibi köke göreli olarak,filesiçindeki her yolu ise o dizine göreli olarak adlandırır; taslak oluşturma ve listeleme hiçbir yer adlandırmaz. - Yayım araçları,
sign-artifacts,deprecate-artifact,get-schema,explain-errorvedescribe-capabilities, ana makinede kendilerine ait hiçbir yeri adlandırmaz. Bunlardan herhangi birinin hata mesajı metin kuralını izler: çevrimdışı bir çalışma alanının yükselttiği ret,.aggrega-config.yaml’ını köke göreli olarak adlandırır. - Çalışma alanının dışına ulaştığı için reddedilen bir yol argümanı, yukarıda olduğu gibi, kökü ya da ulaşacağı yeri adlandırmadan reddedilir.
Bir çağrı nasıl sona erer
Bağlantıyı kapatmak, taşıdığı çağrıyı iptal eder. Bu, bu aktarımın iptal sinyalidir: sunucu, bir çağıranın bağlantıyı kesmesini o isteğin iptali olarak ele alır, yaptığı işi sonlandırır ve onun için başka hiçbir şey yazmaz. Burada hiçbir iptal mesajı gerekmez ya da beklenmez — bu, kapatılacak istek başına bir akışın bulunmadığı ve bir istemcinin bir çağrıyı bunun yerine kimliğini adlandırarak sonlandırdığı standart girdi ve çıktının tersidir. HTTP üzerinden yine de gelen bir iptal mesajı kabul edilir ve hiçbir şeyi sonlandırmaz.
Süreci durdurmak dinleyiciyi boşaltır. Bir kesme ya da bir denetleyiciden veya bir kapsayıcı çalışma zamanından gelen bir sonlandırma isteği, dinleyicinin kabul etmesini durdurur ve zaten yanıtlanmakta olan bir çağrının sınırlı bir süre içinde bitmesine izin verir; böylece durdurmadan önce bir şey istemiş bir çağıran yanıtını yine alır. Bu süre içinde bitmemiş bir çağrı bağlantısını kaybeder. İkinci bir durdurma isteği süreci hemen sonlandırır.
Kendi adresinde canlılık ve hazır olma
mcp.health.listen, bir denetleyicinin bu sürecin ayakta olup olmadığını ve bir çağrıyı yanıtlayıp yanıtlayamayacağını sorduğu yerdir. Ona yukarıdaki biçimlerden birinde bir adres verin; ikinci bir dinleyici orada GET /healthz ve GET /readyz isteklerini yanıtlar. Bunu belirtmezseniz (varsayılan budur) ikinci bir dinleyici başlatılmaz ve iki denetim de hiçbir yerde yanıtlanmaz.
İki yanıt farklı şeyler söyler ve iki tane olmasının nedeni bu farktır. /healthz, süreç çalıştığı andan itibaren 200 ile yanıtlanır; canlılığın iddia ettiği şeyin tamamı budur: süreç ayaktadır ve hiç yanıt alamayan bir denetleyici onu yeniden başlatmalıdır. /readyz, bu sürecin sunduğu çalışma alanı çözümlenip uç nokta bağlanana kadar 503, o andan itibaren 200 ile yanıtlanır; böylece bir yük dengeleyici, ilk isteği hâlâ başlamakta olan bir sürece göndermek yerine süreç bir çağrıyı gerçekten yanıtlayabilene kadar trafiği bekletir. Her yanıt, gövdesi boş bir durum kodudur; kimlik bilgisi istenmez ve çağıranın gönderdiği hiçbir şey okunmaz.
Uç nokta bu iki yolu asla yanıtlamaz. mcp.listen ile belirtilen adreste GET /healthz ve GET /readyz, o uç noktanın sunmadığı diğer her yol gibi, belirteçle de belirteçsiz de 404 ile yanıtlanır. Orada bir yoklamayı yanıtlamak, uç noktaya ulaşan her şeye sürecin ayakta olup olmadığını ücretsiz okuma imkânı ve onu ücretsiz olarak iş yapmaya zorlama yolu verirdi; üstelik kimlik bilgisi taşımayan her isteği aksi hâlde reddeden bir dinleyicide.
Sağlık adresinin nerede duracağını siz seçersiniz ve bu adres mcp.listen gibi kısıtlanmaz. Bunun için hiçbir adres reddedilmez. Onu loopback’e veya bir Unix soketine yöneltin; amacı budur: aynı ana bilgisayarda bu sürecin yanında çalışan bir denetleyici, yük dengeleyici veya konteyner çalışma zamanı. Seçtiğiniz adrese ulaşabilen her şey bu iki yanıtı okuyabilir; dolayısıyla açık ağın ulaştığı bir adres bunları açık ağa yayımlar.
Kimlik bilgisi olmadan hiçbir şey sunulmaz
Uç noktaya yapılan her istek bir kimlik bilgisi taşır ve hangisini taşıdığı, öndeki bir proxy’nin onu zaten denetleyip denetlemediğine bağlıdır. Varsayılan olarak bu, bu sunucunun kendisinin doğruladığı, bu bölümün geri kalanında açıklanan bir taşıyıcı (bearer) belirteçtir. mcp.authorization.trusted_proxy ayarlanırsa bunun yerine o proxy’nin ayarladığı bir başlıktır; bu, Çağıranı öndeki bir proxy’den okuma altında açıklanır ve orada hiçbir belirteç okunmaz. İki biçim de hiçbir şey sunmayan bir isteğe hizmet vermez.
Varsayılan olarak sunucu taşıyıcı belirteci kendisi denetler. Belirteci Authorization başlığından okur ve yalnızca şu koşullarda kabul eder: imza, yetkilendirme sunucusunun yayımladığı bir anahtara karşı doğrulanır, belirteç yayımlayıcı olarak mcp.authorization.issuer değerini belirtir, hedef kitleleri arasında bu dağıtımın kendi mcp.authorization.resource değerini belirtir, geçerlilik aralığı içindedir ve onu kimin sunduğunu söyler. Bunlardan herhangi birini karşılamayan bir belirteç 401 ile yanıtlanır; hiçbir şey taşımayan bir çağıranın aldığı aynı meydan okumaya error="invalid_token" eklenir. Yanıt, onu hangi denetim reddetmiş olursa olsun aynıdır; böylece çağıran, gönderdiği belirtecin hangi kısmının yanlış olduğunu değil, farklı bir belirtece ihtiyaç duyduğunu öğrenir. Yalnızca asimetrik imza algoritmaları kabul edilir: imzasız bir belirteç ve simetrik bir algoritma belirten belirteç, ondan herhangi bir şey okunmadan reddedilir.
Bir belirteç ne tür bir belirteç olduğunu söyleyebilir ve dört biçim kabul edilir. Bir JWT, kendi türünü belirten bir typ başlığı taşıyabilir. Bu sunucu, erişim belirteci için kayıtlı iki yazım olan at+jwt ve application/at+jwt değerlerini; yalnızca belirtecin bir JWT olduğunu söyleyen JWT değerini; ve hiç tür bildirmeyen bir belirteci kabul eder. Diğer her şey, reddedilen diğer her belirteç gibi 401 ile yanıtlanır. Küme sabittir ve hiçbir ayar onu genişletmez veya daraltmaz; çünkü orada hangi biçimin görüneceğine, belirteci alan dağıtım değil, onu üreten yetkilendirme sunucusu karar verir. JWT kabul edilmesi, bildirilen türün tek başına bir erişim belirtecini bir kimlik belirtecinden artık ayırt etmediği anlamına gelir; onları ayıran hedef kitle denetimidir ve asıl yükü taşıyan denetimin bu olmasının nedeni budur: bir kimlik belirtecinin hedef kitlesi, verildiği istemcidir, asla bu dağıtımın kendi mcp.authorization.resource değeri değildir; dolayısıyla bu dağıtım dışında herhangi bir şey için verilmiş bir belirteç, kendini ne olarak adlandırırsa adlandırsın reddedilir.
Bunun hangi yetkilendirme sunucularını kabul ettiği. Microsoft Entra ID, JWT türünde erişim belirteçleri verir. Keycloak at+jwt verir; OpenID Connect uyumluluk modu açıksa JWT verir. Auth0, kendi belirteç profili altında JWT, RFC 9068 profili altında at+jwt verir. Bunlardan herhangi birinden gelen bir belirteç, iki biçimden hangisini taşırsa taşısın bu denetimi karşılar. Okta desteklenmez: erişim belirteçleri, yukarıdaki dördünden hiçbiri olmayan kendine özgü bir tür bildirir; bu yüzden bu sunucu onları reddeder.
Reddedilen bir belirteç, nedenini sunucunun kendi hata akışına bırakır. Çağırana yalnızca sunduğu şeyin kabul edilmediği söylenir; sunan süreç, belirteci reddeden denetimi belirten tek bir satır yazar: hedef kitle, yayımlayıcı, geçerlilik aralığı, imza, anahtar tanımlayıcısı, bildirilen tür ve diğerlerinin her biri. Bu satır, her isteği reddeden bir dağıtımın yalnızca onu çağıran tarafından değil, onu çalıştıran tarafından da teşhis edilebilmesini sağlar. Satır belirtecin hiçbir parçasını taşımaz. Hiç kimlik bilgisi sunmayan bir istek satır yazmaz; çünkü meydan okumayla karşılaşmak, bir istemcinin ilk başta nereden belirteç alacağını öğrenme yoludur ve bu yüzden düzgün davranan her istemcinin yaptığı ilk şeydir.
Belirtecin yeri başlıktır, başka hiçbir yer değil. access_token sorgu parametresi olarak gönderilen bir belirteç 400 ile yanıtlanır ve asla okunmaz; çünkü bir adres, isteğin geçtiği her proxy günlüğüne, tarayıcı geçmişine ve referrer başlığına kaydedilir, dolayısıyla bu yolla gelen bir belirteç zaten açığa çıkmıştır. Sunucu bir belirteci asla günlüğe yazmaz, asla bir yere göndermez ve çağıran adına asla belirteç edinmez veya değiş tokuş etmez: sunulanı okur, karar verir ve hiçbirini saklamaz. Belirtecin belirttiği özne kaydedilir ve hiçbir şeyle karşılaştırılmaz.
Doğrulama anahtarları yetkilendirme sunucusundan veya sizin belirttiğiniz bir dosyadan gelir. mcp.authorization.jwks_file ayarlanmamışsa sunucu, yetkilendirme sunucusunun meta verilerini bilinen (well-known) adresinden okur, orada yayımlanan jwks_uri adresini izler ve bulduğu anahtarları tutar; bu anahtarların taşımadığı bir anahtar tanımlayıcısıyla imzalanmış bir belirteç bir kez yeniden okumayı tetikler ve kısa bir aralıkta bundan fazlası yapılmaz; böylece uydurma anahtar tanımlayıcıları gönderen bir çağıran, istek başına bir giden istek yaptıramaz. Anahtarları yetkilendirme sunucusundan okumak bir https anahtar adresi gerektirir ya da bu makinede düz bir http adresi: başka bir ana bilgisayarda düz http olan bir jwks_uri adresine asla sorulmaz ve iki okumadan birini başka bir ana bilgisayardaki düz http adresine gönderecek bir yönlendirme izlenmez; çünkü anahtarlara giden korumasız bir yolda bulunan herkes kendi anahtarlarıyla yanıt verebilir. Bu anahtarlara ihtiyaç duyan bir belirteç bu durumda, okunamayan anahtarlarda olduğu gibi 503 ile yanıtlanır ve sunucunun o istek için yazdığı satır, yetkilendirme sunucusuna ulaşılamadığını değil, okumanın düz http nedeniyle reddedildiğini söyler; düzeltme, meta verilerini ve anahtarlarını https üzerinden yayımlaması gereken yetkilendirme sunucusu tarafındadır. jwks_file ayarlanmışsa anahtarlar o dosyadan okunur ve yetkilendirme sunucusuyla hiç iletişim kurulmaz; offline: true bildiren bir çalışma alanının ihtiyacı budur ve böyle bir çalışma alanı, dosya belirtilmedikçe dinleyicisi bağlanmadan önce reddedilir. Anahtarlar hiç okunamıyorsa istekler meydan okuma olmadan 503 ile yanıtlanır: çağıranın sunduğu hiçbir şey yetersiz bulunmamıştır, dolayısıyla onu başka bir belirteç almaya göndermek işe yaramaz.
Kimlik bilgisi istenmeden verilen tek yanıt, korunan kaynak meta veri belgesidir. Bir istemcinin token edinebilmesi için önce bu belgeyi okuması gerekir; dolayısıyla burada token istemek içeri giden tek kapıyı kapatırdı. Belge /.well-known/oauth-protected-resource adresinde ve — mcp.authorization.resource’un adlandırdığı adresin kendine ait bir yolu varsa — bu iyi bilinen yola o yol eklenmiş biçimde de yanıtlanır. Bir istemcinin baktığı iki yer bunlardır ve eklenmiş biçim, sınamanın adlandırdığı adrestir. Belge bu adresi bu dağıtımın adı olan kaynak olarak, mcp.authorization.issuer’ı token edinilecek yetkilendirme sunucusu olarak, header’ı token sunmanın tek yolu olarak ve aşağıdaki üç kapsam adını taşır.
Yetkilendirme sunucusu bu makinede çalışmıyorsa, düzenleyici bir https adresidir. localhost, 127.0.0.1 veya ::1 üzerindeki bir düzenleyici için düz http kabul edilir; yerel bir yetkilendirme sunucusuyla yapılan yerel bir testin biçimi budur. Başka herhangi bir ana makinedeki düz http düzenleyici, dinleyici bağlanmadan önce reddedilir ve ret, mcp.authorization.issuer’ı adlandırıp bir https adresi ister. Bu her kipte geçerlidir — anahtarlar düzenleyiciden okunduğunda, mcp.authorization.jwks_file ile ve önde bir proxy varken — çünkü her kip düzenleyiciyi bu belgede yayımlar: onu izleyen bir istemci yetkilendirme akışını o adrese karşı yürütür, bu nedenle düz http üzerinden yetkilendirme kodu ve edindiği token, bu sunucu oradan hiç anahtar okusun ya da okumasın, ağı korumasız geçer. Sunucu anahtarlarını oradan okuyorsa, o yol üzerinde bulunan herhangi biri kendi anahtarlarıyla da yanıt verebilir ve bu anahtarlarla imzalanan her token kabul edilirdi.
Bu dağıtımın yayımladığı kapsam adları aggrega:read, aggrega:workspace-write ve aggrega:registry-write’tır. Yetkilendirme sunucusuna kaydedilecek adlar ve bir istemcinin ondan isteyeceği adlar bunlardır; reddedilen bir çağırana gelen sınama, önce edinilecek kapsam olarak aggrega:read’i adlandırır. Her birinin neye izin verdiği — ve ikinci sınır, yani bu dağıtımın kendine koyduğu sınır — aşağıda Bir çağıranın nelere erişebileceği altında anlatılır.
Çağıranı öndeki bir proxy’den okumak
Öndeki bir proxy token’ları zaten doğruluyorsa, mcp.authorization.trusted_proxy bu sunucuya bir token’ı ikinci kez denetlemek yerine çağıranı o proxy’den okumasını söyler. Ona, o proxy’nin çağıranın kim olduğunu belirtmek için ayarladığı üst bilgi olan principal_header’ı ve isteğe bağlı olarak, o çağıranın kapsamlarını boşluklarla ayrılmış biçimde taşıyan ikinci bir üst bilgi olan scopes_header’ı verin. Her biri, X-Forwarded-User gibi, boşluk veya iki nokta içermeyen bir HTTP üst bilgi adıdır; başka biçimdeki bir ad, yapılandırma yüklenirken anahtar adlandırılarak reddedilir, boş bir principal_header da öyle — bu kipi kapalı bırakmak için bloğu çıkarın. Okunan üst bilgiler yalnızca bu ikisidir: hiçbir yönlendirilmiş adres üst bilgisi ve başka hiçbir üst bilgi işe karışmaz. Principal üst bilgisi olmadan gelen bir istek 401 ile yanıtlanır ve bu kipte hiç token okunmaz — bu sunucunun aksi halde reddedeceği bir token taşıyan istek, principal üst bilgisi varsa sunulur; bu sunucunun kabul edeceği bir token taşıyan istek ise o üst bilgi yoksa yine reddedilir.
Bu kip yalnızca loopback veya bir Unix soketi üzerinde kabul edilir ve süreç başka bir yere bağlanmadan önce reddedilir. Bir üst bilgi, tam olarak onu proxy’den başka hiçbir şey ayarlayamadığında güvenilirdir. Ağın eriştiği bir adreste ise onu her şey ayarlayabilir — dolayısıyla böyle bir adreste bu kipteki bir dinleyici, her çağıranın kendine dilediği adı vermesine izin verirdi. Ret, çakışan iki ayarı da adlandırır; böylece adresi taşıyarak ya da bloğu kaldırarak onu aşabilirsiniz.
Proxy’nin öne sürdüğü şey, bu sunucunun inandığı şeydir; pazarlık budur. Bu sunucu bu kipte hiçbir imzayı denetlemez ve öne sürülen çağıranı, bir token’ın öznesini hiçbir şeyle karşılaştırmadığı gibi, hiçbir şeyle karşılaştırmaz. Proxy’nin ilettiği şeyi doğrulayıp doğrulamadığı ve o dinleyiciye proxy’den geçmeden herhangi bir şeyin erişip erişemediği, doğru kurulması dağıtıma düşen konulardır; yukarıdaki kısıtlama bunların doğru kurulmasını mümkün kılar, doğru kurulduklarının güvencesi değildir.
mcp.authorization.trusted_proxy’yi ayarlamak diğer gereksinimleri kaldırmaz. issuer ve resource yine gereklidir, çünkü meta veri belgesi yine yayımlanır ve sınama yine onu adlandırır — proxy’nin arkasındaki bir istemcinin, proxy’nin denetleyeceği token’ı nereden edineceğini yine öğrenmesi gerekir. Aynı nedenle düzenleyici, bu makinede çalışmıyorsa, yine bir https adresidir: o istemci token’ını düzenleyiciden edinir; bu nedenle başka bir ana makinedeki düz http düzenleyici, bu sunucu ondan hiçbir şey okumasa da, bu kipte de diğer her kipte olduğu gibi dinleyici bağlanmadan önce reddedilir.
Bir çağıranın nelere erişebileceği
Bir çağıranın HTTP üzerinden nelere eriştiğini iki sınır belirler ve bunları farklı kişiler koyar. Birincisi çağıranın kendi kimlik bilgisidir; ikincisi bu sunucunun neleri barındırdığıdır. İkisi de hiçbir şey çalışmadan önce, her işlemin kendisi hakkında yaptığı bir bildirimden okunur ve bir istemciye farklı yerlerde ulaşır: araç listesi bu sunucunun neleri barındırıp duyurduğunu, her çağrının aldığı yanıt ise kimlik bilgisinin neye izin verdiğini gösterir.
Her işlem kendi etkilerinin ne kadar uzağa ulaştığını bildirir ve dört tür vardır; en geniş olanı en sondadır:
- Hiçbir şeye erişmez — bir tanımı okur, bir Release’in sabitlediklerini inceler, yapıtları bellekte oluşturur ve geri verir. Arkasında hiçbir şey bırakmaz: hiçbir şey yazılmaz ve yanıt, ürettiği şeyin tamamıdır.
- Çalışma alanına erişir — bu sürecin hizmet verdiği çalışma alanının içine yazar: bir Release’in kilit dosyası, yapıt önbelleği, üretilmiş varlıklar, düzenlenmiş bir belge.
- Bir kayıt defterine erişir — yayımlar, imzalar ya da zaten yayımlanmış bir şeye geri çekme işareti ekler. Değiştirdiği şey, o kayıt defterinin her tüketicisinin çözümlediği şeydir ve bunların hiçbiri, onu zaten almış birinden geri çağrılamaz.
- Makineye erişir — ana makinedeki her çalışma alanının paylaştığı şeyleri değiştirir; bunlar arasında derlenmiş modül deposu, hepsine ortak yapılandırma dosyası ve kimlik bilgisi deposu vardır. Tek bir projenin kendi önbellek dizini altında tuttuğu bir önbellek bu türden değildir;
cache-status, listelediği her önbelleğin bu türlerden hangisini taşıdığını bildirir.
Tür, onu sunan aracın değil işlemin bir özelliğidir ve işlemin arkasında bıraktığını kapsar — bir yüzeyin geri verdiği yanıtı nereye koyduğunu değil. Bir Release’i oluşturmak yanıt olarak yapıtlar üretir, dolayısıyla hiçbir şeye erişmez; ardından bu yapıtları adlandırdığınız bir dizine kaydeden bir komut satırı, daha uzağa erişmiyor, o yanıtı teslim ediyordur. Tersinden okunursa, içerikle yanıt veren her işlem, onu kaydeden yüzey hangisiyse onun türünü alırdı ve tür artık işlemin bir özelliği olmaktan çıkardı. Aynı nedenle bir varlığı kayıt defteri başvurusuyla okuyan describe hiçbir şeye erişmez: yanıtını almak için o kayıt defteriyle iletişim kurar, ama ne kayıt defterinde ne de bu makinede arkasında bir şey bırakır; hangi kayıt defterleriyle iletişim kurabileceği Bir çağrının hangi kimlik bilgilerini harcadığı altında anlatılır. Çağrının kendisi bir yazma istediğinde, tek bir çağrı yine de işleminin türünden daha uzağa erişebilir: write gönderilen bir derleme, yapıtlarını bu sunucunun hizmet verdiği çalışma alanına kaydeder; dolayısıyla bu çağrı, bağımlılıklarını önce çözümleyen bir derlemede olduğu gibi, çalışma alanına erişir.
Bir kapsam bir türe izin verir ve her yazma kapsamı okuma kapsamını içerir. aggrega:read, hiçbir şeye erişmeyen bir işleme izin verir. aggrega:workspace-write, çalışma alanına erişen bir işleme izin verir ve okuma kapsamını içerir. aggrega:registry-write, bir kayıt defterine erişen bir işleme izin verir ve okuma kapsamını da içerir. Böylece bir istemci, yetkilendirme sunucusundan ihtiyaç duyduğu yazma kapsamını ister ve ayrıca okuma kapsamını istemesi gerekmez.
Hiçbir kapsam makine türünü kabul etmez ve hiçbir ayar böyle bir kapsam eklemez. Bu türdeki işlemleri yalnızca ayrı bir süreçte bir aggrega komutu çalıştıran araçlar taşır ve HTTP üzerinden erişilen bir sunucu, yukarıda Sunucuya HTTPS üzerinden erişmek altında verilen nedenle bunların hiçbirini sunmaz. Bunları ana makinedeki bir terminalde çalıştırın.
Araç listesi, çağıran kimlik bilgisi hangi kapsamları taşırsa taşısın, bu sunucunun taşıdığı ve duyurduğu her aracı gösterir; bir çağrının bunlardan hangisini çalıştırabileceğine kimlik bilgisi karar verir. describe-capabilities aynı kümeyi dizinler ve tanımlar. Kimlik bilgisinin kabul etmediği bir çağrı, meydan okumada error="insufficient_scope" ile 403 olarak yanıtlanır, onu kabul edecek tek kapsamı adlandırır ve çağrının istediği hiçbir şey çalışmamıştır. Bu ret, protokolün yükseltme (step-up) mekanizmasının yanıtladığı rettir: yükseltmeyi uygulayan bir istemci, meydan okumanın adlandırdığı kapsam için sizden yeniden oturum açmanızı ister. Liste kimlik bilgisiyle değişmez; bu nedenle yeniden oturum açmış bir istemci doğru kapsamı zaten taşır. Üç kapsamdan hiçbirini taşımayan bir kimlik bilgisi aynı araç listesini alır ve describe-capabilities dahil, listedeki araçların hiçbirini çağıramaz.
Bilinmeye değer durum bir derlemedir. Derleme kendi başına hiçbir şeyi değiştirmez ve bu nedenle yalnızca aggrega:read gerektirir; ancak yazan bir derleme aggrega:workspace-write gerektirir: write gönderilen bir derleme yapıtlarını çalışma alanı kökündeki dist/ dizinine kaydeder, bağımlılıklarını önce çözümleyen bir derleme ise kilit dosyasını yazar — bunu çağrının kendisinin auto_pull ile istemiş olması ya da çalışma alanının kendi auto_pull ayarının istemiş olması fark etmez. Araç, her araç gibi okuma kapsamlı bir çağırana listelenir ve bellekte kalan derlemeler ona gerçekten açıktır; reddedilen, aggrega:workspace-write adlandırılarak, yazan çağrıdır.
Yükseltme yapmayan bir istemciye yine de yazma kapsamları verilebilir ve bu, yetkilendirme sunucusunda belirlenir. Yetkilendirme sunucusunu çalıştıran kişi, yazma kapsamlarını o istemci için varsayılan kapsamlar yapar — istemci istemiş olsun ya da olmasın, sunucunun o istemciye verdiği her belirteçe koyduğu kapsamlar —; böylece ilk oturum açmanın edindiği belirteç bunları zaten taşır. Her bağlandığında yetkilendirme sunucusuna yeniden kaydolan bir istemci, orada her seferinde yeni bir istemcidir ve önceki bir kayıtta yapılan ayar aktarılmaz; böyle bir istemci için geçerli olan ayar, yetkilendirme sunucusunun kaydettiği her istemciye verdiği varsayılan kapsamlardır. Bunun bedeli, o istemci üzerinden yapılan her oturum açmanın, eldeki iş gerektirsin ya da gerektirmesin, yazma erişimi taşımasıdır — ve varsayılanlar kayıt sırasında verilenlerse, bu şekilde kaydedilen her istemci de bu erişimi taşır. Yalnızca işin gerektirdiği yazma kapsamını varsayılan yapın: aggrega:workspace-write ve aggrega:registry-write farklı türleri kabul eder ve hiçbiri diğerini kapsamaz.
mcp.deny_reach, bu sunucuyu çalıştıran kişinin ondan bir türü geri çektiği yerdir ve araç listesini kısaltan iki ayardan biridir. Bu sunucunun taşımadığı türleri — none, workspace, registry, machine — listeleyin; bunlardan birine erişen her araç, çağıranın belirteci ne derse desin her çağıranın araç listesinden ve describe-capabilities çıktısından çıkarılır ve yine de çağrılırsa bu ayarı adlandıran bir hatayla reddedilir. Bu, çağıranın değil sunucunun kendi sınırıdır; bu yüzden hiçbir kimlik bilgisi onu kaldıramaz ve ret hiçbir meydan okuma taşımaz: yalnızca okuma sunmak için tasarlanmış bir sunucu burada workspace, registry ve machine türlerini listeler ve ardından belirteci üç kapsamın tümünü taşıyan bir çağıran için bile yayımlayamaz. Varsayılan olarak bunu dışarıda bırakırsanız sunucu hiçbir türü geri çekmez; bir çağrının hangi türlere eriştiğine çağıranın kendi kapsamları karar verir. machine adlandırmak kabul edilir ve hiçbir şeyi değiştirmez, çünkü bu türden hiçbir şey zaten burada sunulmaz. Dördünden biri olmayan bir değer, atlanmak yerine yapılandırma yüklenirken reddedilir — bir türü yanlış yazan operatör bir sınır istemiştir ve sessizce sınırsız hizmet almak buna verilecek yanlış yanıttır.
mcp.announce_tools, araç listesini kısaltan diğer ayardır ve ikisi aynı sınır değildir. deny_reach bir yeteneği geri çeker: orada adlandırılan türden bir işlem, hiç kimse için burada taşınmaz. announce_tools yalnızca bir duyuruyu geri çeker: dışarıda bıraktığı araçlar bu sunucunun hâlâ sahip olduğu yeteneklerdir ve yanıtladığı şey, bir istemcinin kaç araç kaydedeceğine dair kendi üst sınırıdır. İkisi de ayarlandığında geri çekme kazanır; bu nedenle geri çekilmiş bir türdeki araç, announce_tools onu nasıl adlandırırsa adlandırsın listede yer almaz ve çağıranın karşılaştığı ret geri çekmeyi adlandırır. Listeyi kısaltan hiçbir şey çağıranın kapsamlarını okumaz: çağıranda eksik olan bir kapsam bir çağrıyı reddeder, listeden hiçbir zaman bir araç çıkarmaz. Gerisini Sunucunun duyurduklarını daraltmak açıklar.
Bir çağrı hangi kimlik bilgilerini kullanır
Bir dinleyici üzerinden anahtarsız imzalama, kimliğini yalnızca çağrının taşıdığı identity_token’dan alır, başka hiçbir yerden almaz. Çağrıda gönderilen bir belirteç, çağıranın elinde tuttuğu bir kimlik bilgisidir: onu edinmek zorunda kalmıştır, belirteç ona bağlıdır ve oluşturduğu imza ona atfedilebilir. Bir kimliğin gelebileceği diğer her yer bu süreci başlatan kişiye aittir; bu nedenle bu aktarım üzerinde çözümlemeye hiçbir şey yanıtlamayan bir ortam verilir. Sunucunun ortamındaki AGGREGA_IDENTITY_TOKEN ve SIGSTORE_ID_TOKEN okunmaz ve ortamdaki GitHub Actions OIDC uç noktasına erişilmez. Bunlar önerilmeyen değil, erişilemeyen şeylerdir — çözümlemenin bulabileceği hiçbir şey yoktur. identity_token göndermeyen bir çağrı reddedilir ve ret, gönderilecek şey olarak identity_token’ı adlandırır, hiçbir değişkeni ve hiçbir uç noktayı adlandırmaz: bu makinenin klavyesinde olmayan bir çağıran burada hiçbir şeyi dışa aktaramaz, dolayısıyla birini adlandırmak ona yanıtı değiştiremeyecek bir şeyi düzenlemesini söylemek olurdu.
Bu makinede tutulan bir imzalama anahtarı, iki yoldan hiçbiriyle seçilemez. key_path herhangi bir şey çözümlenmeden önce reddedilir ve publish-entity, sign-artifacts ve deprecate-artifact’ın burada duyurduğu argüman şemalarında yer almaz; böylece çağırana başarılı olamayacak bir argüman hiçbir zaman sunulmaz. Sunulan çalışma alanının kendi yapılandırmasının adlandırdığı imzalama anahtarına da erişilmez — signing.key_path, ister çalışma alanının tamamı için ayarlanmış, ister tek bir kayıt defterine karşı ayarlanmış, ister ortamdan sağlanmış olsun. Her ikisini de tek bir neden kapsar: bir anahtar yolu bir kimlik bilgisi değildir, bu sunucunun tuttuğu bir sırrın adıdır. Bir yol sağlayan çağıran hiçbir şey kanıtlamaz, bu adrese erişen herkes aynı adı sağlayabilirdi ve ardından gelen imza, yapıta çağıranın değil operatörün kefil olduğunu söylerdi. Yapılandırmayı açık bırakırken argümanı kapatmak, diğerinin hâlâ açtığı bir odaya açılan tek bir kapıyı kapatmak olurdu. Bu yüzden bir dinleyici üzerinden anahtarlı imzalamaya erişilemez: yalnızca çağrıda gönderilen bir belirteç imzalar.
fulcio_url, rekor_url ve timestamp_url etkilenmez ve her iki aktarımda da kalır. Bunlar bu makinenin tuttuğu bir şeyi değil, iletişim kurulacak hizmetleri adlandırır; bu nedenle anahtar seçemeyen bir çağıran yine de bu dağıtımın yapılandırdığı uç noktalara karşı imzalar.
Bir imzalama anahtarı adlandıran bir çalışma alanı üzerinde başlatılan dinleyici, bunu başlarken bir kez söyler. Süreç, kendi hata akışına ayarı adlandıran ve bu dinleyiciye erişen bir çağıranın o anahtarı kullanamayacağını söyleyen bir satır yazar — böylece operatör bunu beklemediği bir imzadan değil, başlattığı süreçten öğrenir. Hiçbir anahtar adlandırmayan bir çalışma alanı böyle bir satır üretmez, çünkü onunla ilgili söylenecek bir şey yoktur. Satır ayarın adını taşır; ne anahtarı ne de işaret ettiği dosya hakkında herhangi bir şeyi taşır.
Standart girdi ve çıktı üzerinden yukarıdakilerin hiçbiri geçerli değildir. Orada ortam okunur ve key_path bu makinede tutulan bir anahtarı seçer, çünkü bu sunucuyu başlatan istemci çağıranın kendi makinesinde çalışmaktadır ve o sürecin erişebildiği şey, o çağıranın kendi kullanabileceği şeydir.
Bir varlığı kayıt defteri başvurusuyla okumak, bu ana makinenin kendi oturum açma bilgisiyle tek bir kayıt defteriyle iletişim kurar; bir dinleyici üzerinden ise yalnızca sunulan çalışma alanının yapılandırıldığı bir kayıt defteriyle. name olarak bir oci:// başvurusu gönderilen describe, o koordinatta yayımlanmış varlığı — aggrega inspect’in gerçekleştirdiği okumanın aynısıyla — başvurunun adlandırdığı tek kayıt defterinden, bu ana makinenin o kayıt defteri için zaten tuttuğu oturum açma bilgisini kullanarak okur. Çağrı hiçbir kimlik bilgisi taşımaz ve describe de hiçbirini almaz. HTTP üzerinden kayıt defteri, sunulan çalışma alanının yapılandırıldığı biri olmalıdır: default_registry’nin adlandırdığı ana makine ya da registries altında listelenen bir ana makine; karşılaştırma tam olarak ve bağlantı noktasıyla birlikte yapılır. Başka herhangi bir ana makineye — bu makinedeki bir adres de dahil — yapılan başvuru, o ana makineyle iletişim kurulmadan önce reddedilir ve ret ana makineyi adlandırır; böylece bir çağıran bu sunucuyu kendi seçtiği bir hedefe yönlendiremez. Erişilebilir kalan şey kasıtlıdır: aggrega:read tutan bir çağıran, çalışma alanının yapılandırıldığı bir kayıt defterinde bu ana makinenin oturum açma bilgisinin okuyabildiği her şeyi okuyabilir; bu da bu ana makinenin terminalindeki bir kişinin de okuyabildiği şeydir. Standart girdi ve çıktı üzerinden, komut satırında olduğu gibi, herhangi bir kayıt defterine yapılan başvuru okunur. Bir varlığı katalog adıyla tanımlamak bundan etkilenmez.
Bir kayıt defteri çağrısı, bu sürecin altında çalıştığı işletim sistemi kullanıcısının kimlik bilgisi deposunu kullanır; aynı çağrının bu ana makinedeki bir terminalde yaptığı gibi. Çalışma alanı başına bir kimlik bilgisi kaynağı ve bunu ekleyen bir ayar yoktur; registry-list’in bir ana makinenin kimlik bilgisi durumunu bu makinedeki her çalışma alanında aynı şekilde bildirmesinin nedeni budur. Farklı çalışma alanlarının farklı kayıt defteri kimlik bilgileri tutmasını isteyen bir dağıtım, onları farklı işletim sistemi kullanıcıları olarak çalıştırır — çalışma alanı başına bir süreç, her biri kendi kullanıcısı olarak başlatılır. Ayrım buradan gelir ve bunu düzenlemek operatöre aittir.
Sunucunun kaydettikleri
Bu uç noktanın yanıtladığı her istek, sürecin hata akışında bir satır bırakır ve bu satır tek bir JSON nesnesidir. Satır şunları taşır: yazıldığı time; bu sürecin çağrı için ürettiği ve çağırana geri göndermediği bir request_id; sunulan kimlik bilgisinin ileri sürdüğü biçimiyle subject ve issuer, bir istemci adlandırdığı yerde client_id ile birlikte; bu sürecin hizmet verdiği çalışma alanı olan workspace_root; method ve yöntemin bir şeyi adıyla hedeflediği yerde target; işlemin bildirdiği tür olan reach ve çağrının bundan daha öteye ulaştığı yerde reach_escalated_to; outcome; duration_ms; ve transport. Söyleyecek bir şeyi olmayan alan boş yazılmak yerine dışarıda bırakılır; dolayısıyla eksik bir client_id, hiçbir istemci adlandırmayan bir kimlik bilgisi demektir, eksik bir reach_escalated_to ise işleminin bildirdiğine tam olarak ulaşan bir çağrı demektir.
outcome çağrının ne olduğunu söyler ve değerler, onları ayrı ayrı sayabilmeniz için birbirinden farklıdır. ok çalışmış ve başarılı olmuştur. tool-failure çalışmış ve çağıranın düzeltebileceği bir hata olarak işaretlenmiş şekilde dönmüştür — bu sunucunun reddettiği değil, hizmet verdiği bir çağrıdır, bu yüzden retleriniz arasına girmez. error, bir protokol hata zarfı olarak geri taşınan bir rettir. unauthenticated, forbidden ve rate-capped sırasıyla kimlik bilgisinin, köken ya da kapsam sınırının ve çağıran başına hız sınırının bir isteği geri çevirmesidir. cancelled, yanıtlanmadan önce bağlantısını kapatan bir çağırandır.
Reddedilen bir kimlik bilgisinin geri çevrilme nedeni ayrı bir satır değil, aynı satırın bir alanıdır. Reddedilen bir istek de diğerleri gibi tek bir kayıt bırakır ve refusal, onu geri çeviren denetimi adlandırır. Hiçbir kimlik bilgisi ya da onun herhangi bir parçası hiçbir satıra ulaşmaz — ne bir retle ne de hizmet verilen bir çağrıda.
Hiçbir şey sunmayan bir çağıran satır bırakmaz. Sınamaya tabi tutulmak, bir istemcinin token’ı nereden alacağını öğrenme yoludur; bu yüzden düzgün davranan her istemcinin yaptığı ilk şeydir ve bunların her biri için bir satır, anlam taşıyan retleri gömerdi. Bu uç noktanın hizmet vermediği bir yolu ya da yöntemi adlandıran istek de satır bırakmaz: ikisi de çağıran hakkında herhangi bir şey okunmadan önce karara bağlanır, dolayısıyla adresin taranması akışı toplayan şeye hiçbir şey yazmaz.
İstemcinin gönderdiği iz bağlamı satıra olduğu gibi kopyalanır. traceparent ve gönderildikleri yerde yanındaki tracestate ile baggage, tam alındıkları gibi taşınır; böylece bu akışı toplayan şey onu çağıranın kendi kayıtlarıyla birleştirebilir. Hiçbirini göndermeyen ya da düzgün biçimlendirilmiş W3C iz bağlamı olmayan bir tane gönderen istek, bu anahtarlar olmadan bir satır üretir: hiçbir şey uydurulmaz ve geçiş sırasında hiçbir şey değiştirilmez.
Süreç kendi yaşamını da aynı biçimde ve aynı akışa kaydeder; bu satırların her biri, istek satırının bir yöntem ve çağıran adlandırdığı yerde bir event adlandırır: başlarken startup, bağlandığı adresle listening, bir başlatmanın hizmet vermeden önce reddedilme nedeniyle startup-refused, hizmet verdiği çalışma alanının bu dinleyiciye ulaşan hiçbir çağıranın kullanamayacağı bir imzalama anahtarı adlandırdığı yerde signing-key-ignored, belge paketini edinmenin sonucuyla docs-bundle ve çalışma sona ererken shutdown. İki satır türü, event alanının varlığına bakılarak birbirinden ayrılır.
Bunların hepsini sürecin hata akışından toplarsınız ve teslimatın tamamı budur. Yapılandırılacak bir dışa aktarıcı, adlandırılacak bir dosya ya da bunlardan herhangi birini açan, kapatan veya başka yere yönlendiren bir ayar yoktur: bu süreci denetleyen şey — bir konteyner çalışma zamanı, bir hizmet yöneticisi, bir log gönderici — o akışı toplayan ve sonrasında sorguladığınız yerdir. Standart giriş ve çıkış üzerinden aynı akış bunun yerine okunabilir düz metin taşır, çünkü onu okuyan istemci süreci başlatmıştır ve aynı makinede bulunur.
Bunların hiçbiri çağırana gönderilmez. Sunucu, iki aktarımın hiçbirinde protokol üzerinden log akışı yayımlamaz ve protokolün istek başına log düzeyi alanını taşıyan bir istek, bu alanı taşımayan bir istekle tamamen aynı şekilde yanıtlanır: burada kaydedilen operatöre aittir ve yalnızca operatörün akışına gider.
Sunucu bağlandığında modele ne söyler
Sunucu, model için bir yönlendirme metni sunar; istemciniz bunu ilk çağrıdan önce modele iletebilir. 2026-07-28 üzerindeki bir istemci bunu server/discover yanıtından okur; 2025-06-18 üzerindeki bir istemci ise initialize el sıkışmasına verilen yanıttan okur. Her iki yolda da metin bayt bayt aynıdır ve tek bir sürece ulaşan her istemci için de aynıdır: içindeki hiçbir şey müzakere edilmez, hiçbir şey istemcinin gönderdiğinden veya sunduğu kimlik bilgisinden türetilmez; dolayısıyla bir modele bağlantı sırasında söylenenler oturumlar veya istemciler arasında değişmez.
İki şey değişir ve hiçbiri istemci değildir. Kapanış paragrafı, sürecin hizmet verdiği aktarım için oluşturulur; bu nedenle standart girdi ve çıktı üzerinden konuşan bir sunucu ile bir dinleyici modele farklı kapanış metinleri verir. Ayrıca bir sunucuyu başlatan masaüstü paketi, başlattığı aggrega yürütülebilir dosyasından farklı bir sürümden geliyorsa, yönlendirme metni bunu belirten ve her iki sürümü de adlandıran tek bir cümleyle açılır — bu, Sunucunun hangi sürümden geldiği bölümünde açıklandığı gibi, argümansız describe-capabilities yanıtının açıldığı cümledir; hiçbir paketin başlatmadığı bir süreç ve paketi yürütülebilir dosyanın kendi sürümünden gelen bir süreç, yönlendirme metnini bu cümle olmadan verir. Her ikisi de süreç başladığında sabitlenir ve her iki süreçte de iki revizyon o sürecin kendi metnini yine aynı şekilde sunar.
Bir aracın argüman şemasının tek başına aktaramayacağı zihinsel modeli öğretir:
- Derleyicinin ne yaptığı ve bilerek ne yapmadığı — bir değerin ne anlama geldiğini yorumlamak yerine metni yönlendirdiği ve etiket eşleşmelerini değerlendirdiği, belgelerinize koyduğunuz içerik konusunda kendi görüşü olmayan bir yapıda olduğu ve derleme sırasında hiçbir zaman bir provider ile kimlik doğrulaması yapmadığı, bir kümenin durumunu okumadığı ve bir sırrı düz metne dönüştürmediği. Yalnızca altyapı çalışmaya başladığında var olan bir değer, hedef ortamın daha sonra dolduracağı bir işaretçi dizesi olarak aktarılır.
- Yazım sözlüğü ve türlerin birbiriyle ilişkisi — her türün ne işe yaradığı ve bir derlemenin aslında hangisine karşı çalıştırıldığı; böylece bir asistan, bir dağıtımın biçimini araç listesinden çıkarmak zorunda kalmaz.
- Yazım döngüsünün çalıştığı sıra — sözleşmeyi okuyun, ondan iskelet oluşturun, bağladığınız şeyi inceleyin, ardından işlemeden önce denetleyin.
- Ne zaman araç yerine bir istem kullanılacağı — eylem için araç, bir görevi çerçevelemek için istem.
- Araç listesinin yüzeyin tamamı olduğu — bu sunucunun sunduğu her araç listededir ve bir sunucunun hangi araçları sunduğu nasıl kurulduğuna bağlıdır; bu nedenle bir asistan, ikinci bir liste aramaya gitmek yerine burada ne olduğunu o listeden ve
describe-capabilities’ten okur. Bağlantı bir kimlik bilgisi sunduysa metin, bu kimlik bilgisinin söz konusu araçlardan hangilerinin listeleneceğine değil, bir çağrının hangilerini çalıştırabileceğine karar verdiğini belirtir: kimlik bilgisinin kabul etmediği bir çağrı, onu kabul ettirecek kapsam adlandırılarak reddedilir ve istemci o kapsam için yeniden oturum açabilir. - Boş bir çalışma alanının ne anlama geldiği ve modelin bu konuda ne yapabileceği — aşağıda, aktarıma göre farklılık gösteren paragraf.
Yüzeyleri yeniden anlatmak yerine adlandırır. Her araç kendi açıklamasını ve argüman şemasını zaten tools/list içinde taşır ve her türün sözleşmesi zaten kendi şemasında ve başvuru sayfasında bulunur; bu nedenle yönlendirme metni bunlara işaret eder ve orada durur — her ifade için tek bir yer. Adını verdiği bir araç sunucunun sunduğu bir araçtır ve okuma yüzeyinin çözümlediği her kaynak ailesine işaret eder; böylece bir asistanı peşinden gönderdiği hiçbir şey çıkmaz sokak değildir.
Araçların kendilerine ait bir dizin taşımaz; bu da bir eksiklik değil, aynı ilkenin sonucudur. Bir istemci, bu metnin tek kelimesini okumadan önce her aracın tanımını tools/list’ten almış olur; dolayısıyla burada araç başına bir satır, istemcinin zaten sahip olduğu amaçların ikinci bir kopyası olurdu — her oturumda, her istemci tarafından bedeli ödenen ve ikisinden biri düzenlendiği anda araç listesiyle çelişebilecek bir kopya.
Ayrıca neyi listelemediğini ve nedenini de belirtir: kullanılabilir işleme hedefleri ve kurulu kütüphane türleri, plugin’lerinizin ve şema kümenizin özellikleridir; bu nedenle yönlendirme metni bunların çelişebilecek bir kopyasını taşımak yerine, kaynak yüzeyleri bunları doğrudan bildirir.
Boş bir çalışma alanı hakkında modele ne söylenir
Kapanış paragrafı, bir modelin hiçbir şey içermeyen bir çalışma alanında ilk karşılaştığı soruyu yanıtlar: boş bir list-entities ne anlama gelir ve model bu konuda ne yapabilir. Açılışı her iki aktarımda da aynıdır — boş bir listeleme, bu sürecin çözümlediği çalışma alanının okuyabileceği hiçbir Aggrega belgesi içermediği ve yanında yapılandırılmış katalog dizinlerinin de hiçbirini bildirmediği anlamına gelir — ardından gelenler ise bu sürecin hangi aktarıma hizmet verdiğine bağlıdır, çünkü dürüst yanıt ikisinde aynı değildir.
Standart girdi ve çıktı üzerinden modele, çalışma alanının incelemesi ve onarması için kendisine ait olduğu söylenir. Modele, hiçbir çalışma alanı adlandırmayan bir çağrının nerede yanıtlandığı söylenir — sunucu bir klasörle başlatıldıysa o klasörde, aksi hâlde başlatıldığı klasörden bulunan çalışma alanında (bu, o klasörün kendisi olabilir) — ve bir çağrıdaki workspace_root’un başka bir çalışma alanını adlandırdığı söylenir. Geçerli yapılandırma ve her ayara hangi katmanın karar verdiği için config-show’a, çalışan bir yapılandırma oluşturmak için cli-config-init’e yönlendirilir; her ikisi de bu aktarımda araç listesindedir. Sunucuyu çalıştıran istemci, çağıranın kendi makinesindedir; dolayısıyla o sürecin ulaşabildikleri, o çağıranın kendi kullanımındadır — ve sınırı belirlediğiniz yer, Bir asistanın size sormadan neler yapabileceği bölümünde açıklandığı gibi, diğer tüm araçlar için belirlendiği yerdir: MCP istemcinizdir.
HTTP üzerinden modele, yapılandırmak yerine raporlaması söylenir. Çalışma alanı, süreci üzerinde başlattığınız çalışma alanıdır ve süreç boyunca sabittir; workspace_root veya catalog_dirs adlandıran bir çağrı, argüman adlandırılarak reddedilir; ve kimlik bilgisi hangi kapsamları taşırsa taşısın, burada hiçbir çağırana yapılandırma yazan bir araç sunulmaz. Bu işlemler yalnızca ayrı bir süreçte bir aggrega komutu çalıştıran araçlar tarafından taşınır ve HTTP üzerinden ulaşılan bir oturum bunlar olmadan oluşturulur — dolayısıyla sınır bir kapsam değil, bileşimin kendisidir ve hiçbir belirteç onu genişletmez. Bu nedenle dağıtımınıza bir dinleyici üzerinden ulaşan bir model, ana makinenizde bir kayıt defteri oluşturamaz veya bir güven ilkesini yeniden yazamaz; paragraf da modelin denemesine ve reddi okumasına izin vermek yerine bunu ona söyler.
Bir asistanın size önce sormadan yapabilecekleri
Bu sunucuya standart giriş ve çıkış üzerinden bağlanan bir asistan, istemciniz bunu reddedecek şekilde yapılandırılmadıkça, sunucunun sunduğu her aracı size sormadan çağırabilir. Bu aktarımda sunucu araçları sunar ve herhangi bir çağrının bunlardan hangisini kullanmasına izin verildiğine karar vermez: bu karar istemcinizindir ve onu orada siz verirsiniz. HTTP üzerinden durum aynı değildir: sunucu taşıdığı ve duyurduğu her aracı listeler ve çağıran token’ın kapsamlarının kabul etmediği bir çağrıyı reddeder; böylece sınır istemcinin olduğu kadar sunucunundur da.
Bu önemlidir, çünkü araç yüzeyi komut satırının kendisidir. Yazabildiğiniz her şeyi bir asistan çağırabilir — makinenizi değiştiren işlemler de dahil.
Bu işlemlerin bazıları üzerinde çalıştığınız çalışma alanının ötesine uzanır ve başka bir şey çalıştırılarak geri alınamaz. Adıyla bilinmeye değer olanlar, en geniş erişimliden başlayarak şunlardır:
publish-entity,publish-artifact,sign-artifactsvedeprecate-artifactmakinenin tamamen ötesine uzanır. Bir kayıt defterine bayt, imza veya geri çekme işareti koyarlar; dolayısıyla değiştirdikleri şey yalnızca bu makinenin değil, o kayıt defterinin her tüketicisinin çözümlediği şeydir. Bir etiketin üzerine farklı içeriğin yeniden yayımlanması sunulmaz, reddedilir; bu nedenle buradaki hiçbir şey bir yayını geri almaz; çözüm yeni bir sürüm yayımlamaktır. İmza ve geri çekme işareti yapıtın baytlarına dokunmaz, ancak o yapıtı sonradan getiren herkes bunları da getirir ve hiçbiri, onu zaten edinmiş olan birinden geri çağrılamaz. Standart giriş ve çıkışta aynı dört yetenek, komutları çalıştırancli-push,cli-push-artifact,cli-signvecli-deprecateolarak da erişilebilirdir; HTTP üzerinden bu dört araç yoktur.- İmzalama kimlik bilgileri kullanır. Standart giriş ve çıkış üzerinden anahtarsız imzalama, kimlik token’ını çağrının
identity_tokenargümanından, sunucunun ortamındakiAGGREGA_IDENTITY_TOKENveyaSIGSTORE_ID_TOKENdeğişkeninden ya da erişilebildiği yerde ortamdaki GitHub Actions OIDC uç noktasından alır;key_pathbunun yerine çevrimdışı tutulan bir anahtar seçer. Bu nedenle bu araçları çağırabilen bir asistan, sunucuyu çalıştıran makinenin zaten taşıdığı kimlik neyse onunla sizin adınıza imzalayabilir — ve imza, bir yapıta kimin kefil olduğuna dair bir beyandır; izin vermeden önce üzerinde en çok düşünülmesi gereken işlemin bu olmasının nedeni budur. Bir dinleyici üzerinden yalnızca çağrıda gönderilen token imzalar: sunucunun ortamındaki hiçbir şey okunmaz ve ana makinede tutulan hiçbir anahtar bir argümanla veya sunulan çalışma alanının yapılandırmasıyla seçilemez; bkz. Bir çağrının harcadığı kimlik bilgileri. aggrega cache evictderlenmiş modül deposunu budar,aggrega cache clearise onu siler. Bu depo makinedeki her Aggrega projesi tarafından paylaşılır. Depodan kaldırılan modüller talep üzerine yeniden derlenir, böylece hiçbir şey kalıcı olarak kaybolmaz — ancak herhangi bir projenin sonraki derlemesi bu maliyeti öder.aggrega cache clear, makinedeki her projenin okuduğu dokümantasyon paketini de kaldırır; bu paket, projelerden biri onu bir sonraki edinişinde yeniden getirilir.aggrega cache prune, hiçbir kilit dosyasının başvurmadığı yapıt önbelleği girdilerini geri kazanır. Bir projenin kilit dosyası okunmak üzere mevcut değilse, sabitlenmiş yapıtları onun tarafından korunmaz ve bunları geri kazanmak onları yeniden getirmek anlamına gelir.aggrega registry addveaggrega registry removevarsayılan olarak tüm çalışma alanlarınca paylaşılan yapılandırmaya yazar; dolayısıyla yalnızca burada değil, makinenin her yerinde neyin çözümlendiğini değiştirirler.aggrega registry addayrıca adını verdiği kayıt defterinden, o kayıt defterinin duyurduğu güven politikasını ister ve kendisine verileni sabitler; tıpkı bir terminalde yaptığı gibi. Çevrimdışı bir çalışma alanında bu getirme, herhangi bir bağlantı kurulmadan reddedilir; bu nedenle çağrıidentityveyakeysağlamadıkça resmî hub dışındaki bir kayıt defterini eklemek reddedilir — kısa kodE0310, aynı sözcüklerle; ikisini de almayanaggrega config init, çevrimdışıyken yalnızca hub’ı ekleyebilir. Standart giriş ve çıkışta bunlar, komutları çalıştırancli-registry-addvecli-registry-removeolarak, ilk yapılandırma isecli-config-initolarak erişilebilirdir; HTTP üzerinden bu araçlar yoktur.pullbir kayıt defterinden okur ve yöneltildiği çalışma alanının içine yazar. O Release’in kilit dosyasını yazar, yapıt önbelleğini çözümlediği şeylerle doldurur ve çalışma alanınızın eklediği, karar döndüren her eklentinin kimliğini kilit dosyasının yanına kaydeder.pin_sourcesgönderildiğinde — ya dapin_sources_at_pullayarı açık olan bir çalışma alanında, bunu false olarak göndermeyen bir çağrıda — Release’in katalog dizinlerinizden derlendiği Recipes ve FeatureRecipes üzerinde varlık yazarının sabitleme adımını da çalıştırır ve her birinin yanınaentity.lockyazar; bu olmadan, kilidi okuduğu bir girdi için sabitleme kaydetmeyen böyle bir varlık üzerindeki pull, adımı adlandırarak reddedilir. Varlık dosyalarının kendisine hiçbir zaman yazılmaz. Bunların hiçbiri makineden dışarı çıkmaz ve kaydedileni değiştirmenin yolu yeniden çözümlemektir; dolayısıyla bu, buradaki yazan işlemlerin en hafifidir. Çalışma alanının içine yazan, yazım döngüsü için biçimlendirilmiş araçlardan biridir:pin, adını verdiğiniz Recipe veya FeatureRecipe’in yanınaentity.lockyazar, bkz. Bir varlığın kendi girdilerini sabitleme;gen-catalog, oluşturulan Plugin varlıklarını adını verdiğiniz dizinin altına yazar;edit-document, elinizde olan bir belgeye tek bir sınırlı yapısal düzenleme uygular ve düzenlemenin dokunmadığı her baytı koruyarak geri yazar, bkz. Bir belgeye tek bir sınırlı düzenleme uygulama;importise başka bir aracın ürettiği bir tanımı taslak yazım dosyalarına dönüştürür ve bunları çalışma alanına yazar, bkz. Yabancı bir tanımı taslak varlıklara dönüştürme;examplegönderilenscaffolddeaggrega scaffold --examplegibi, belgelerin çalıştırılabilir örneklerinden birinidirile belirtilen yeni ya da boş bir dizine yazar; HTTP üzerinden buna workspace-write kapsamı izin verir. Bu çıktı dizini,gen-catalog’un okuduğu konuk ve ona verdiğiniz her katman, çalışma alanı köküne göreli ya da standart giriş ve çıkış üzerinden mutlaktır; bu yüzeydeki diğer her yol argümanının kullandığı sözleşmenin aynısıdır. Standart giriş ve çıkışta aynı yetenek, komutu çalıştırancli-pullolarak da erişilebilirdir; HTTP üzerinden bu araç yoktur.build, onaauto_pullgönderdiğinizde ve yalnızca o zaman, aynı kayıt defterini okur ve aynı yazmayı gerçekleştirir. Bir Release’in bağımlılıklarını çözümlemek, nerede istenirse istensin tek bir işlemdir; dolayısıyla önce çözümlemesi söylenen bir derleme tam olarakpull’un yaptığını yapar ve ardından yazdığı şeye karşı işler — daha dar değil aynı erişimi taşımasının nedeni budur.writegönderildiğinde, işlenmiş yapıtları da çalışma alanı kökündekidist/dizinine yazar;aggrega build’in onları yazdığı yere ve aynı yazma yoluyla; böylece o çağrı için çalışma alanına erişir; başka hiçbir yere yazmaz ve çalışma alanının dışına çıkan bir bağlantı olandist, içindeki herhangi bir şey kaldırılmadan veya yazılmadan önce reddedilir. Varsayılan olan, iki argümanın da gönderilmediği durumdabuild, çalışma alanının zaten tuttuğu sabitlemelerden işler ve hiçbir şeye erişmez. Argümanın neyi değiştirdiğini ve neyi olduğu gibi bıraktığını öğrenmek için Bir Release’in zaten sabitlediği içeriğe karşı derleme bölümünü okuyun.
Envanter araçları bunu kendi yanıtlarında belirtir. cache-status her önbellek sınıfını erişim alanıyla işaretler — bu projenin kendi önbellek dizini altındaki yapıt önbelleği için workspace, her projenin paylaştığı depolar için machine — ve makine genelindeki olanları açıkça adlandırır; böylece bir geri kazanım önermeden önce envanteri okuyan bir asistana, envanterin hangi kısımlarının yalnızca size ait olmadığı bildirilir. Bakım işlemleri, kaldırdıkları her öğe için aynı erişim alanını bildirir. Dört yayımlama sonucunun her biri kendine ait bir reach taşır; bu alan registries değerini — çağrının hitap ettiği her kayıt defteri ana bilgisayarı, her biri bir kez ve ilk hitap edildiği sırayla — ve çağrının ne istediğine göre değil gerçekte ne eklediğine göre okunan beyond_this_machine değerini tutar: çağrı içerik yüklediği ya da bir imza, bir yayımlama tarihi veya bir kullanımdan kaldırma işareti eklediği anda doğrudur; bir deneme çalıştırması için ve tamamının zaten orada olduğunu bulan bir çağrı için, örneğin eksiksiz bir sürüm üzerinde yeniden çalıştırılan bir yayımlama ya da başvurularının tümü zaten imzalanmış bir imzalama toplu işi için yanlıştır.
Sınırı nerede belirlersiniz. Protokolün kendisi araç başına bir izin tanımlamaz — kimlik doğrulaması, bir istemcinin hangi araçları çağırabileceğiyle değil, bağlanıp bağlanamayacağıyla ilgilidir. İzin kararı MCP istemcinizde bulunur. Yaygın olarak kullanılan istemciler genellikle tek bir sunucudaki araçlara adlarıyla tek tek izin verebilir ya da onları reddedebilir ve belirli bir proje için bir sunucuyu tamamen devre dışı bırakabilir; ayarın adı ve konumu istemciden istemciye değişir, bu nedenle araç izinleri için istemcinizin kendi belgelerine başvurun. Yazma işlemlerini değil de okuma işlemlerini istiyorsanız, istediğiniz araçlara orada izin verin ve geri kalanını reddedin. İzin verici bir yapılandırma ya da böyle bir ayarı olmayan bir istemci, sunulan her aracı çağrılabilir bırakır.
Bir çalışma alanının ne içerdiğini öğrenmek
Araçların çoğu bir özne alır: bir varlık adı ya da bir Release’in yolu. Aşağıdaki iki araç hiçbir özne almaz ve yeni gelmiş bir asistan bir özneyi bunlarla edinir.
list-entities çalışma alanının ne içerdiğini yanıtlar, list-releases ise yüzeyin geri kalanının sürekli sorduğu daha dar soruyu yanıtlar: hangi Releases var. İkisi de özne almaz, çünkü bir çalışma alanının ne içerdiği, çağıranın önceden bilmesi gereken herhangi bir şeyin değil, çalışma alanının bir özelliğidir.
Her biri iki biçimden biriyle yanıt verir ve hiçbir biçim belirtmeyen bir çağrı özeti alır. Bu varsayılan yalnızca bu ikisine aittir ve build, describe ve validate araçlarının aldığı varsayılanın tersidir. Onlara, çağıranın zaten adlandırdığı bir özne hakkında soru sorulur; bu yüzden istenen yanıt daha kapsamlı olandır ve kısa olan isteğe bağlıdır. Bu ikisine ise henüz adlandıracak hiçbir şeyi olmayan ve yanıt gelmeden onun ne kadar tutacağını bilmesinin hiçbir yolu bulunmayan bir çağıran tarafından burada ne olduğu sorulur; bu yüzden önce çalışma alanının boyutunu ve yapısını bildirir, kayıtları ancak istendiğinde verirler.
Özet, burada ne olduğunu ve ne kadar olduğunu söyler. list-entities çalışma alanı kökünü (HTTP üzerinden, Bir yanıtın sunucunun dosya sistemi hakkında söyledikleri bölümünde açıklandığı gibi, verilmez), toplam varlık sayısını ve tür başına bir sayıyı bildirir; list-releases ise toplamı ve üst düzey dizin başına bir sayıyı bildirir, böylece kaç Releases olduğunu ve ağacın hangi bölümünde bulunduklarını öğrenirsiniz. Her iki döküm de belgelerin kendisinden okunur; bu nedenle kimsenin öngörmediği biçimde düzenlenmiş bir çalışma alanı da öngörülmüş biri kadar doğru özetlenir. Her ikisi de tür başına ya da üst düzey dizin başına bir satır taşır; bu yüzden boyutları, çalışma alanının kaç belge içerdiğine değil, kaç tür bildirdiğine ve Releases’inin kaç dizinde bulunduğuna bağlıdır: türlerini değiştirmeden bir çalışma alanındaki belgeleri yüzle çarpın, özet yalnızca büyüyen sayıların yazılması için gereken birkaç bayt kadar büyür. Onu uzatan, daha fazla tür bildirmektir. İkisi de kayıtların ilk sayfası değildir ve asıl mesele bu farktır: “işte varlıkların bazıları” ile “çalışma alanı bunlardan oluşuyor” farklı yanıtlardır ve yalnızca ikincisi size herhangi bir kayıt isteyip istemediğinizi ve hangilerini istediğinizi söyler.
Kayıtlar için response_format: detailed gönderin; kayıtlar sayfa sayfa gelir. Bu durumda list-entities her varlığın türünü, adını, apiVersion değerini, açıklamasını, etiketlerini ve kaynak dosyasını, onu bildiren belgeden doğrudan okuyarak bildirir. Ayrıca yapılandırılmış katalog dizinlerinizin bildirdiği Features’ı da bildirir; böylece size eklenebilir olarak sunulan bir Feature aynı zamanda arayabileceğiniz bir Feature olur. Bunlar kaynak dosya taşımaz, çünkü sahip oldukları tek yol sunucunun çalıştığı makinedeki bir yoldur; her biri nereden geldiğini belirtir, böylece boş bir dosya alanı eksik bir değer olarak değil, “katalogdan çözümlendi” olarak okunur. list-releases her Release’in yolunu bildirir ve lockfiles, döndürdüğü her yolu o Release’in kilit dosyasının yoluna aynı koordinatta eşler: pull aracının onun için yazdığı ve build aracının okuduğu dosya, dil sunucusunun Release yanıtlarının adlandırdığı dosyanın ta kendisi. Eşleme bu yanıtın taşıdığı yolları tanımlar; bu yüzden sayfayı izler ve özet onu boş taşır.
response_format yalnızca detailed ve concise değerlerini alır ve bunlar tam olarak eşleştirilir. Başka herhangi bir yazım (farklı bir sözcük, farklı bir büyük/küçük harf ya da birinin çevresinde boşluk) reddedilir ve ret, gönderileni bağımsız değişkenin kabul ettiği değerlerle birlikte belirtir. response_format değerini dışarıda bırakmak varsayılanı istemenin yoludur; bu iki araç için varsayılan özettir. Bağımsız değişken nerede görünürse görünsün aynısı geçerlidir: build, describe ve validate aynı iki değeri aynı koşullarla alır ve onların varsayılanı kısa biçim değil, daha kapsamlı biçimdir.
Kayıtlar, siz sınırlasanız da sınırlamasanız da sınırlıdır. limit, bir yanıtın kaç kayıt taşıdığıdır; 1 ile 500 arasındadır ve varsayılanı 50’dir. Bu nedenle kayıt isteyen ve sayfa boyutu belirtmeyen bir çağrı yine sınırlıdır ve iki araçtan hiçbirinin hiçbir çağrısı, boyutunu çalışma alanının kendi büyüklüğünün belirlediği bir yanıt döndürmez. offset, listede nereden başlanacağıdır ve 0’dan sayılır. İkisi de kayıtları sınırlar; bu yüzden hiç kayıt taşımayan özet üzerinde hiçbir etkileri yoktur. Bu aralığın dışındaki bir limit reddedilir ve ret sınırı belirtir; listenin sonunu aşan bir offset boş döner, çünkü soruda bir yanlışlık yoktur, yalnızca orada bir şey yoktur.
Bir listeye, yanıttan üç alan okuyarak devam edin. count, çalışma alanının kaç kayıt içerdiğidir; offset ve returned bu yanıtın nereden başladığını ve kaç kayıt taşıdığını söyler; more_remaining ise kalan olup olmadığını söyler. more_remaining true olduğu sürece offset artı returned ile yeniden çağırın. Bu sinyal yanıtın üzerine yazılmaz, sayfanın toplamla karşılaştırılmasıyla hesaplanır; bu yüzden kayıtlar kalmışken hiçbir şey kalmadığını bildiremez.
Bunların hepsi önemlidir, çünkü ad alan araçlar çözümleyemedikleri bir adı boş bir sonuçla yanıtlamak yerine reddeder. Ret kasıtlıdır (boş bir yanıt, yanlış yazılmış bir adı sunacak hiçbir şeyi olmayan bir özne olarak bildirirdi), ancak bu, hiçbir adı olmayan bir çağıranın tahmin yoluyla bir ad edinemeyeceği anlamına gelir. Bir ad edinmenin yolu listelemektir.
İkisi birbiriyle ve yüzeyin geri kalanıyla birleştirilebilir:
- Çalışma alanının hangi türleri ve her birinden kaç tane içerdiğini görmek için özet amacıyla
list-entitiesçağırın, ardından kayıtlar içinresponse_format: detailedile yeniden çağırın, sonuçtan bir ad alın ve o varlığın tamamen çözümlenmiş tanımını görmek için bunudescribearacına verin. Bu, dil sunucusununaggrega/entityDefinitionisteğine verdiği yanıttaki tanımdır ve JSON olarak taşınır: her anahtar yazarının yazdığı adla ve tanımın tuttuğu sırayla, bir şema yazarın yazdığı şema olarak yer alır, varlığın bildirmediği bir şema ise dışarıda bırakılır; bir Component’in soketlerinin her biri, bağlantılarının doldurabileceği yuvalarla birlikte gelir. - Aynısını
list-releasesile yapın, ayrıntılı sonuçtan bir yol alın ve üzerinde çalışılacak Release olarak bunudescribeya dabuildaracına verin. list-releasesaracının döndürdüğü yol çalışma alanı köküne görelidir; bu,list-entitiesaracının bir dosyayı altında bildirdiği koordinatın aynısıdır, bu yüzden iki yanıt dosya üzerinde örtüşür ve birlikte okunabilir.lockfilesaltındaki kilit dosyası da aynı köke görelidir; böylece o dosyanın nerede bulunduğunu çıkarmanıza gerek kalmadan onu okuyabilir ya da karşılaştırabilirsiniz.
Her ikisi de neyin sayılacağına, dosya adına göre değil, her belgenin kendi kind değerini okuyarak karar verir. Geleneksel bir önek olmadan adlandırılmış bir Release listelenir; yalnızca bir Release gibi adlandırılmış bir dosya listelenmez ve gerçekte bildirdiği tür ne ise onun altında görünür. Hiç kind bildirmeyen YAML — bir chart’ın değerler dosyası, ağaçta bulunuveren bir yapılandırma dosyası — bir varlık değildir ve raporlanmaz; işlenmiş bir Kubernetes manifest’i gibi başka bir projeye ait bir belge de raporlanmaz. Bir belge, hem bir kind hem de bir ad bildirdiğinde varlık sayılır, çünkü sonradan adreslenebilir olmasını bu ikisi birlikte sağlar; ayrıca Aggrega’nın kendi grubu dışında bir apiVersion bildirmemelidir. Hiç apiVersion bildirmeyen bir belge raporlanır, çünkü başka bir projenin dosyası değil, bir alanı eksik olan bir Aggrega belgesidir. list-releases çalışma alanı kökü dışındaki hiçbir dizinde arama yapmaz; bu nedenle düzenleyicinizin dışarıdaki bir dizine giden bir bağlantının altında gösterdiği bir Release listelenmez. unread_linked_dirs, listelemenin bir dizin okuyacağı yerde bulunan ve kökün dışına giden her bağlantıyı — nereye gittiğine göre değil, bağlantının köke göre kendi yoluyla — her iki biçimde ve her iki taşıma yönteminde adlandırır, böyle bir bağlantı yoksa boştur. Kök dışındaki bir dosyayı bir bağlantı üzerinden de okumaz: unread_linked_files, kendi adı .yaml veya .yml ile biten ve kök dışındaki bir dosyaya giden her bağlantıyı, o dosya ne içerirse içersin, aynı şekilde adlandırır; bu nedenle yalnızca böyle bir bağlantı üzerinden ulaşılan bir Release listelenmez — çalışma alanı yapılandırması o Release’i build.authoring_release olarak veya workspace.releases altındaki bir anahtar olarak adlandırmadıkça; bu durumda Release okunur, bağlantının kendi yerinde listelenir ve adlandırılmaz. list-entities da çalışma alanının dışına giden bir bağlantının arkasındaki hiçbir belgeyi okumaz — kök dışındaki hiçbir dizinde arama yapmaz ve kök dışındaki hiçbir dosyayı, o dosya ne bildirirse bildirsin, okumaz — ve bu tür her bağlantıyı aynı şekilde, kendi unread_linked_dirs ve unread_linked_files alanlarında, her iki biçimde ve her iki taşıma yönteminde adlandırır. Bu, belge ne bildirirse bildirsin geçerlidir; tek istisna list-releases’in yaptığı istisnadır: çalışma alanı yapılandırmasının build.authoring_release olarak veya workspace.releases altındaki bir anahtar olarak adlandırdığı bir Release okunur, bağlantının kendi yerinde listelenir ve adlandırılmaz; bu ayarlardan birinin adlandırdığı ancak Release dışında bir şey bildiren bir dosya ise listelenmez ve bağlantısı adlandırılır. Yapılandırılmış katalog dizinleri, bir çalışma alanının başka yerde tutulan diğer varlıkları okuma yoludur; bu nedenle yapılandırmanın catalog_dirs altında listelediği bir dizine veya onun altındaki bir dizine giden bir bağlantı iki listelemeden hiçbiri tarafından adlandırılmaz: yapılandırma ona ulaşmıştır. list-entities’in katalog dizinlerinden aldığı Features, bir katalog dizininin okumalarının içinde kalması gereken dizinin — çalışma alanının içindeki bir katalog dizini için çalışma alanı, yapılandırmanın dışarıda adlandırdığı bir dizin için ise dizinin kendisi — dışına giden bir bağlantının arkasındakileri asla içermez; bu nedenle okunmamış bir bağlantının arkasında olarak adlandırılan bir varlık asla o adın yanında listelenmez. Listelemenin dışarıda bıraktığı bir bağlantı — adı, bulunduğu yer veya bir .gitignore nedeniyle — adlandırılmaz; release ile, yalnızca diğer Releases’in okuduğu bir katalog dizininin altındaki bağlantı da adlandırılmaz. Kendisi çalışma alanının dışına giden bir bağlantı olan bir .gitignore okunmaz. Bu listelerden herhangi biri bir bağlantıyı adlandırdığında, metin yanıtı bunu belirten kendine ait bir satırla kapanır.
Yapılandırma dosyası dışarıya giden bir çalışma alanı yine listelenir, ancak onun için başka hiçbir şey yanıtlanmaz. Çalışma alanının kendi .aggrega-config.yaml dosyası veya yanındaki CI’a ait katman, çalışma alanının dışına giden bir bağlantı olduğunda, yapılandırması bir terminalde olduğu gibi okunmaz ve yapılandıracağı hiçbir şey onun yerine okunmaz. Sunucu yine de standart girdi ve çıktı üzerinden başlar ve bunu hata akışında tek bir satırla belirtir. list-entities ve list-releases, hiçbir şey yapılandırılmadan okunan çalışma alanının kendi belgeleriyle yanıt verir; bu nedenle hiçbir katalog dizininin Features’ı listelenmez. Her biri, listeleme ona rastlamış olsun ya da olmasın, tutulan dosyayı unread_linked_files içinde ve metnini kapatan satırda adlandırır — çalışma alanının yapılandırmasının dışarıya gittiğini bu addan anlarsınız. release veya catalog_dirs gönderilen bir listeleme ve o çalışma alanını adlandıran diğer her araç, okunmamış yapılandırmaya göre belirlenir; bu nedenle her biri bağlantıyı ve nereye gittiğini adlandıran E0321 ile reddedilir. Komut satırında dinlemesi söylenen — --transport http veya --listen — bir sunucu böyle bir çalışma alanı üzerinde başlamaz, çünkü bağlanacağı adresi, sertifikasını ve onu kimin çağırabileceğini o yapılandırma belirler. Bağlantıyı kaldırın veya çalışma alanı içindeki bir dosyaya gitmesini sağlayın; sonraki çağrı yapılandırmayı okur. Bkz. çalışma alanı sınırı.
Tek bir Release’in terimleriyle sormak
Bir çalışma alanı her Release’e kendi katalog dizinlerini verebilir — bkz. Bir Release’e kendi katalog dizinlerini vermek — ve böylece bir varlığın her Release için bir varyantını yan yana tutabilir. Aksi hâlde çalışma alanının kendi katalog dizinleri üzerinden yanıt veren üç araç, isteğe bağlı bir release (bir Release dosyasının yolu) alır ve bu durumda o Release’in terimleriyle yanıt verir:
releaseilelist-entities, o Release’in gördüğü varlıkları listeler. Listelenen Features, onun katalog dizinlerinin bildirdikleridir; yalnızca başka Releases’in okuduğu bir katalog dizini altındaki bir çalışma alanı belgesi dışarıda bırakılır, böylece her varyant onunla derleme yapan Release için listelenir, başka hiçbiri için listelenmez. Hiçbir katalog dizini altında olmayan bir belge — kataloglarin yanına yazılmış bir Release, onun Aggregate’i ve Manifest’i — her Release için listelenir.- Bir
nameve birreleaseiledescribe, adı o Release’in katalog dizinleri üzerinden çözümler; böylece birkaç varyantın bildirdiği bir ad, o Release’in derleme yaptığı varyanta çözümlenir. Bu dizinlerin çözümleyemediği bir ad, o Release’inworkspace.releasesaltındaki girdisini adlandıran bir açıklamayla reddedilir. Bir kayıt defteri başvurusu, hangi Release adlandırılırsa adlandırılsın kendi kayıt defterinden okunur; bu nedenle birreleaseile birlikte reddedilir.nameolmadan gönderilen birrelease, yinedescribe’ın özetlediği Release’tir. - Bir
entityve birreleaseilevalidate, tek varlık denetimlerini o Release’in terimleriyle çalıştırır: varlığın başvuruları — bir Recipe’nin uyguladığı Component, bir sütunun başvurduğu SchemaLibrary — o Release’in katalog dizinleri üzerinden çözümlenir ve yanıt, varlığın yanında Release’i de adlandırır. Hiçbir kapanış doğrulanmaz;entityolmadan gönderilen birreleaseyine Release kapsamıdır.catalog_dirs, her yerde olduğu gibi burada da Release’in dizinlerinin önüne eklenir. Çalışma alanı yapılandırmasının listelediği ama aslında dizin olmayan bir dizin — örneğin orada hiçbir şey bulunmuyorsa —, o Release için ya dareleasegönderilmediğinde çalışma alanı için, herhangi bir şey denetlenmeden önce çağrının reddedilmesine yol açar; metni, her komutun ona verdiği reddi taşır ve girdiyi, onu listeleyen yapılandırma dosyasını ve satırı adlandırır (Yerel varlıkların nereden okunduğu); bu,aggrega validate’in onu reddetmesiyle aynıdır.
Var olmayan bir dosyayı ya da bir dizini adlandıran bir release, çalışma alanının terimleriyle yanıtlanmak yerine üç araçta da reddedilir. Hiçbiri gönderilmezse çalışma alanının kendi katalog dizinleri üzerinden yanıt verilir.
Bir adı arayan describe, adı üzerinden çözümleyeceği ve dolaşılamayan bir katalog dizinini, aggrega inspect’in reddettiği gibi reddeder — bir release gönderildiğinde o Release’in dizinleri, gönderilmediğinde çalışma alanının kendi dizinleri ve çağrının catalog_dirs içinde adlandırdığı her dizin. Çağrının adlandırdığı, var olmayan ya da var olup okunamayan bir dizin, ad aranmadan önce reddedilir ve metin, adı kalan dizinlerden çözümlemek yerine dizini komut satırının bildirdiği gibi tek satırda adlandırır — dizin, catalog load ve dosya sisteminin verdiği neden. Çalışma alanı yapılandırmasının listelediği ama aslında dizin olmayan bir dizin aynı anda reddedilir; metni, her komutun ona verdiği reddi taşır (Yerel varlıkların nereden okunduğu). Var olmayan bir dosyayı adlandıran bir release, yukarıda belirtildiği gibi bundan önce reddedilir. Okumalarının içinde kalması gereken dizinin dışına çıkan bir bağlantı içeren katalog dizini de aynı şekilde reddedilir ve metin bağlantıyı ve nereye çıktığını adlandırır; çünkü o olmadan çözümlenen bir ad, yerine aynı adlı başka bir varlığa çözümlenebilirdi. Bir Release’in bağımlılık kapanışını betimlemek, dolaşılamayan bir dizinden etkilenmez ve aggrega inspect --closure’ın yaptığı gibi dolaşılabilen dizinler üzerinden yanıt verir — çalışma alanı yapılandırmasının o Release için listelediği ama aslında dizin olmayan bir dizin hariç; onu, aggrega inspect --closure’ın reddettiği gibi reddeder; bir katalog dizininin okumalarının ya da Release’in yanındaki belgelerin dışına çıkan bir bağlantı ise, bir derlemeyi durdurduğu gibi onu da durdurur.
Bir entity ile validate, değerlendiremediği bir render işlemini, bir Release’in terimleriyle olsun ya da olmasın, denenmedi olarak bildirir. Bir Recipe’nin Component’ini hiçbir bağlantı kurmayan ve hiçbir Feature eklemeyen sentezlenmiş bir derlemeye yerleştirir; bu nedenle şablonları — içe aktardıkları dosyalar ve kitaplık girdileri dahil — .context.inject, .context.uses ya da .features altında herhangi bir şey okurken render işlemi duran bir Recipe, diagnostics içinde hiçbir şey olmadan valid: true yanıtını verir; metni Render: not attempted (this Recipe reads values a build of one cannot supply) ifadesini, bir kenara konmasına neden olan okumaları ve render işleminin durduğu cümleyi taşır. Belirleyici olan Recipe’nin ne okuduğudur; bu nedenle böyle bir okumanın yanındaki Recipe’nin kendi hatası da onunla birlikte bir kenara konur, ayrıştırılamayan bir şablon ve render işleminin reddettiği bir başvuru ise yine valid: false yanıtını verir. aggrega validate aynı girdilerde aynı kararı verir.
Bir entity ile validate, başarısız bir onaylamayı, bir Release’in terimleriyle olsun ya da olmasın, uyarı olarak bildirir. fail çağıran bir onaylama — Recipe’nin kendisininki ya da uyguladığı Component’in bildirdiği bir onaylama — diagnostics içinde hiçbir şey olmadan valid: true yanıtını verir. Sentezlenmiş derleme, gerçek bir Release’in ayarladığı değerlerin yerine yer tutucular ve şema varsayılanları taşır; bu nedenle böyle bir değer üzerindeki onaylama, Recipe sağlam olsun ya da olmasın orada başarısız olur ve denetim, bir Release’i bekleyen bir onaylamayı bozuk olandan ayırt edemez. Başarısızlık, diğer notices girdilerinin ardından, A Release must satisfy this assertion before a build of it can pass. cümlesiyle kapanan tam onaylama iletisiyle gelir ve metin onu, çalıştırmanın nerede durduğunu söyleyen rapor satırının yanında, warning: ile açılan bir satırda taşır. Okuduğu ama bulamadığı bir anahtarda duran bir onaylama, başarısız bir onaylama değil kendi metnindeki bir hatadır ve diğer her durma gibi değerlendirilir; bir onaylamayı karşılamayan bir Release’in derlemesi yine de bu nedenle reddedilir. aggrega validate aynı girdilerde aynı kararı verir.
Geçerli yapılandırmayı ve bu sunucunun çözümlediği eklentileri okumak
config-show, geçerli yapılandırmayı ve her ayarı hangi katmanın belirlediğini bildirir. plugin-list, bu sunucunun çözümleyebildiği eklentileri ve her birinin kendisi hakkında söylediklerini bildirir. İkisi de hiçbir şey okumaz ve yazmaz; bu nedenle hiçbiri hiçbir yere erişmez ve aggrega:read onlara izin verir. Hiçbiri de sizden bir konu belirtmenizi istemez, çünkü neyin yapılandırıldığı ve neyin çözümlendiği, önceden bilmeniz gereken bir şeyin değil bu sunucunun özellikleridir. Her biri standart girdi ve çıktı üzerinden isteğe bağlı bir workspace_root alır; HTTP üzerinden bu argüman, Tek süreç, tek çalışma alanı bölümünde açıklandığı gibi reddedilir.
Birlikte tek bir soruyu iki yarıda yanıtlarlar: bir yeteneğin yok mu olduğunu, yoksa yalnızca burada yapılandırılmamış mı olduğunu. Yapılandırma; bir sağlayıcının, bir içe aktarıcının ya da bir yönetişim denetiminin hiç bağlı olup olmadığını söyler; eklenti okuması ise bir bağlantının çözümlenen, kendini tanımlayan ve iddia ettiği şeyi sunan bir konuğa ulaşıp ulaşmadığını söyler. Bu yüzeyin başka her yerinden bakıldığında bu ikisi birbirine benzer ve birbirine zıt sonraki adımlar gerektirir.
config-show, ayar başına bir girdi bildirir: ayarın field değeri, etkin value değeri ve onu belirleyen source: bir yapılandırma dosyası, bir ortam değişkeni, bir komut satırı bayrağı ya da yerleşik varsayılanlar. Bunların yanında layers, katkıda bulunan katmanları öncelik sırasına göre, en düşük olan ilk sırada olmak üzere taşır. Bir ayarın source değeri, layers içindeki eşleşen girdiyle tam olarak aynı biçimde yazılır; böylece ikisi doğrudan birleştirilebilir. Varsayılanların belirlediği bir ayar hiçbir katmanı adlandırmaz, çünkü varsayılanlar katkıda bulunan bir katman değildir. Genel katman, sunucunun kendi komut satırının seçtiği dosyadır: sunucu başlatılırken --config ile adlandırılan dosya, yoksa AGGREGA_CONFIG ortam değişkeninin adlandırdığı dosya, o da yoksa varsayılan konum. Dolayısıyla bu dosyanın belirlediği bir ayar, tam olarak aggrega config show --origin komutunun yaptığı gibi bu dosyaya atfedilir; sunucuya verilen --offline gibi bir bayrak da o bayrak olarak bildirilir. response_format ve sayfa boyutu almaz: ayarlar bu ikili dosyanın hesaba kattığı sabit kümedir ve her çözümleme hepsini bildirir; bu nedenle yanıtın boyutu sizin yapılandırdıklarınıza değil ikili dosyaya bağlıdır.
plugin-list, çalışma alanı listelemelerinin kullandığı iki biçimde yanıt verir; biçim belirtmeyen bir çağrı özeti alır. Özet, grup başına bir sayıdır ve iki grup vardır: embedded, yani bu ikili dosyaya derlenmiş, dosya sistemi, önbellek ya da ağ erişimi olmadan çözümlenen konuklar; ve configured, yani çalışma alanının kendi bağlamaları. Kayıtlar için response_format: detailed gönderin: her eklentinin grubu, bulunduğu başvuru, bu başvurunun nerede bağlandığı, kendi bildirdiği türü, sürümü, commit’i, sunduğu yetenekler, işlediği girdi türleri, sınır derlemesi ve dışa aktarımları, varsa hazırlık durumu ve çözümlenip çözümlenmediği. Kayıtlar, varlık listelemesinin kullandığı koşullarla limit ve offset ile sınırlanır; devam etmek için count, returned ve more_remaining sağlanır. Bu yanıt sizin yapılandırdıklarınızla birlikte büyür (yerleşikler sabittir, bağlamalar sizindir); bu yüzden sayfalanır, yapılandırma okuması ise sayfalanmaz.
Başarısız olan bir eklenti listeden çıkarılmaz, hatasıyla birlikte bildirilir. resolved, başvurunun modül baytlarına hiç ulaşıp ulaşmadığını söyler; çözümlenen ama kendini tanımlayamayan bir eklenti de tam olarak böyle bildirilir. Böylece mevcut ama kullanılamaz bir bağlantı, hiç yapılmamış bir bağlantıdan ayırt edilebilir.
Bir dinleyicinin ana makinesi hakkında size söylemedikleri
HTTP üzerinden iki okumadan hiçbiri, sunucunun dosya sistemindeki bir yeri adlandıran bir değer bildirmez. Sunucuyu başlatan bir istemci, sunucunun çalıştığı yerde çalışır; bu nedenle iki yanıtın adlandırabileceği her konum, o çağıranın zaten sahip olduğu ve gidip bakabileceği bir konumdur. Bir dinleyiciye ulaşan bir çağıran bunların hiçbirini seçmemiştir, onları bilmesine dayanarak bir şey yapamaz; bunları böyle bir çağırana yayımlamış bir sunucu da onları geri alamaz. Bu aktarım üzerinden bu değerler yoktur; standart girdi ve çıktı üzerinden hepsi vardır. Bu, Bir yanıtın sunucunun dosya sistemi hakkında söyledikleri bölümünde açıklandığı gibi bu yüzeydeki her yanıtın izlediği kuraldır ve en çok bu iki okumada etkili olur, çünkü bildirdiklerinin çoğu yerleri adlandıran yapılandırmadır.
Neler saklanır. config-show içinden: kendi değeri bir konum olan bir ayarın value değeri; yani bir soket dosyası olabilecek bir sunum ya da sağlık adresi; bir sertifika, özel anahtar ya da anahtar kümesi dosyası; bir katalog dizini ve her girdisi bir Release dosyasıyla anahtarlanan, workspace.releases altındaki bir Release’in kendi katalog dizinleri; bir eklenti başvurusu; bir yazım Release’i. Ayrıca, onu belirleyen katman bir yapılandırma dosyası olduğunda bir ayarın source değeri, çünkü böyle bir katman o dosyanın kendi yoluyla adlandırılır; aynı yazımla ve aynı nedenle layers içindeki yapılandırma dosyası girdileri de. plugin-list içinden: başvurunun kendisi bir dosya sistemi yolu olduğunda bir eklentinin uri değeri ve denenen yerlerden oluşturulduğu için başvurunun kendisinin adlandırmadığı konumları adlandıran çözümleme ya da tanımlama hatasının metni. Her ikisinden: workspace_root.
Her iki aktarımda da eksiksiz bildirilenler. Bir kayıt defteri başvurusu, bir sürüm, bir commit, bir özet (digest), sunulan bir yetenek, bir hazırlık etiketi, bir ortam değişkeninin ya da bir bayrağın adı ve dosya olmayan bir katman. Bir eklenti kaydındaki origin bunlardan biridir: bir bağlamanın yazıldığı yapılandırma anahtarı ya da kurulu bir komut uzantısının taşıdığı sabitlenmiş özettir; yerleşik bir eklenti hiçbirini taşımaz. Bu nedenle eklenti nereden okunursa okunsun aynı dizedir. resolved de bunlardan biridir: bir eklentinin başarısız olup olmadığı, nedeni bildirilmese bile her çağırana bildirilir.
Eksik bir değer her zaman saklandığını belirtir ve yanıtı kullanılabilir kılan da budur. Saklanan bir değer, yanında bir işaretle eksik olarak bildirilir: bir ayarda value_withheld ve source_withheld, bir katman girdisinde withheld, bir eklenti kaydında uri_withheld ve error_withheld, yanıtta ise workspace_root_withheld. Kimsenin ayarlamadığı bir ayar, biçiminin gösterdiği boş değeri taşır ve hiçbir işaret taşımaz. “Bu sunucu imzalama anahtarının nerede olduğunu size söylemiyor” ile “hiçbir imzalama anahtarı yapılandırılmamış” farklı sonraki adımlar gerektiren farklı yanıtlardır; bunları aynı biçimde bildiren bir okuma, size üzerine işlem yapabileceğiniz hiçbir şey söylemezdi. Her yanıt ayrıca her zaman host_locations_withheld taşır; bu, iki yanıttan hangisini elinizde tuttuğunuzu söyler: işaret taşımayan bir yanıt, bu kural onu biçimlendirmiş ve ana makinede saklanacak bir şey olmamış olsa da, kural hiç uygulanmamış olsa da aynıdır. Alanların yanındaki okunabilir metin aynı şeyi sözcüklerle söyler.
Kural, alan adlarından oluşan bir liste değil bir özelliktir: bir değer, kimin ayarladığından ve hangi katmandan geldiğinden bağımsız olarak ana makinenin dosya sistemindeki bir yeri adlandırıyorsa saklanır. İleride iki okumadan birine eklenen bir değer de aynı özelliğe tabidir.
Standart girdi ve çıktı üzerinden her yeteneğe, komutunun adını taşıyan araçla da (cli-config-show ve cli-plugin-list) ulaşılabilir; bu araçlar o komutu ayrı bir süreçte çalıştırır ve yazdırdığı metni geri verir. HTTP üzerinden bu araçlar yoktur. Burada açıklanan iki araç bunun yerine değerleri taşır; böylece bir sütun düzenini oluşturulduğu veriye geri ayrıştırmadan bir yeteneğin bağlı olup olmadığını okuyabilir ya da bir eklentinin sürümünü seçip alabilirsiniz.
Neyin bağlanabileceğini ve neyin neye bağlanabileceğini sormak
İki araç, bir asistanın aksi takdirde tahmin etmek zorunda kalacağı soruları yanıtlar: bir düğüme hangi Features’ın bağlanabileceği ve bir düğümün neye bağlanabileceği. İkisi de derleyicinin çalıştırdığı etiket eşleştirmesinin aynısını çalıştırır; böylece asistanın size sunduğu küme, şemadan çıkarılmış bir küme değil, bir derlemenin eşleştireceği kümedir.
attach-candidates, bildirilmiş uygulanabilirliğini bir düğümün etiketlerinin karşıladığı Features’ı raporlar. Düğümü üç yoldan tam olarak biriyle belirtin:
node—list-entities’in raporladığı biçimde bir çalışma alanı varlığınınmetadata.namedeğeri. Eşleştirme, o belgenin bildirdiği etiketler üzerinde çalışır.releaseile birliktegraph_node— derlenmiş bir graf üzerindeki, grafın anahtarladığı biçimde anahtarlanmış bir düğüm; bir alt aggregate’in katkıda bulunduğu bir düğümün taşıdığı nitelikli biçim de buna dahildir. Eşleştirme, o düğümün kesinleşmiş etiketleri üzerinde çalışır; bunlar bir derlemenin değerlendirdiği etiketlerdir.labels— hiçbir düğümü adlandırmayan, kendi başına bir etiket kümesi. Hiçbir koordinat gerektirmez; dolayısıyla bir düğümün etiketlerine zaten sahipseniz kullanılacak biçim budur. Hiçbir şey aramaz ve hiçbir grafı yeniden oluşturmaz.
Yanıt, eşleştirmenin üzerinde çalıştığı etiketleri ve bunların o üç kümeden hangisinden geldiğini taşır; böylece herhangi bir adayı — ya da bir adayın yokluğunu — yeniden hesaplamak yerine yanıtın kendisinden açıklayabilirsiniz. Bunları ikinci bir yolla yeniden okumak, bir düğümün etiketleri hakkındaki sizin fikrinizle derleyicinin fikrinin birbirinden ayrılmasına yol açar.
Bir düğümün çizdiği tek bir bağlantıya neyin bağlanabileceğini sormak için graph_node ve release yanına connection ekleyin — yazarın yazdığı biçimde socket ve alias değerleriyle. Bir bağlantı, soketinin tüketen Component üzerinde bildirdiği yuvaları dolduran bağlantıları taşır; bu nedenle yanıt ayrıca slots alanını da taşır: soketin bildirdiği her yuva; selector, required, inject, sensitive ve description değerleri Component’in bildirdiği biçimde tam olarak, ve onu doldurabilecek candidates ile birlikte. Bunlar, uygulanabilirliğini düğümün etiketlerinin karşıladığı ve kendi etiketlerini yuvanın seçicisinin kabul ettiği Features’tır — bir derlemenin böyle bir bağlantıya uyguladığı iki kural — dolayısıyla bir yuvanın adayları her zaman düğümün kendi adayları arasındadır. Hiçbir şeyin doldurulamadığı yerde slots boştur ve noSlotReason nedenini söyler: feature-created-connection (bağlantıyı bir Feature çizmiştir ve böyle bir bağlantıya hiçbir şey bağlanmaz), ad-hoc-socket (soket, Component’in bildirmediği bir sokettir) ya da no-slot-declared (soket hiçbir yuva bildirmez). Boş bir slots alanını “hiçbir şey eşleşmedi” olarak okumayın; nedenin orada bulunmasının amacı bunu dışlamaktır ve bir yuvanın var olduğu her yerde neden yoktur. Yanlarındaki candidates anlamını korur — düğümün kendisine neyin bağlanabileceği — ve bir document gönderirseniz bu, burada hiçbir şeyi değiştirmez. node ya da labels yanında verilen veya hiçbir soket ya da takma ad adlandırmayan bir connection reddedilir; düğümün çizmediği bir bağlantı da reddedilir. Bunlar, dil sunucusunun aynı koşullarla verdiği yanıtların aynısıdır.
connection-candidates, bir varlığın bildirdiği bağımlılık soketlerini ve her soket için, bildirilmiş etiketleri o soketin hedefleri üzerinde bildirdiği kısıtı karşılayan çalışma alanı Components’ını raporlar. Varlığın metadata.name değerini node içinde alır. attach-candidates’in aksine koordinatsız bir biçimi yoktur: burada etiket kümesi biçimi bulunmaz, çünkü soketler adlandırılan varlığın kendi bildiriminden okunur.
İki yarısı eşit derecede eksiksiz değildir ve yanıt hangisinin hangisi olduğunu söyler — bunları tek bir liste olarak sunmayın. Hedefler eksiksizdir: bunlar, aynı kısıtın bir derleme sırasında kabul ettiği bileşenlerdir. Soketler ise eksiksiz değildir ve olamaz. Bir tüketici bir bağlantı icat edebilir, ancak yalnızca bir üreticinin bildirdiğini tüketebilir; dolayısıyla bir yazar, katalog varlığının hiç bildirmediği bir soketi meşru olarak yazabilir ve bildirilmiş soketler, geçerli adlar kümesi değil, yararlı bir başlangıçtır. Bu nedenle her soket declared mı yoksa ad-hoc mı olduğunu söyler ve yanıt, bildirilmemiş bir soketin o varlıkta kabul edilip edilmediğini söyler — bir Component’in kendi bağımlılık yüzeyi bunu kabul eder, çünkü bir yazar kendi uygulamasının topolojisine sahiptir; bir Feature’ın bağlantı yüzeyi kabul etmez, çünkü bir bağlantı, bir topoloji yazmak yerine bağlanılan Feature’ın bildirdiği topolojiye katılır. Bu açıklık bir eksiklik değil, yazarlık özgürlüğünüzün bir sonucudur: varlığın bildirmediği bir soketi sormak için o adla socket geçirin.
İkisi de yanıtlar ve durur. Hiçbiri bağlantı oluşturmaz, kenar oluşturmaz, herhangi bir dosyaya yazmaz ya da bunlardan birinin metnini önermez; ardından gelen düzenlemeyi oluşturmak ve uygulamak size kalmıştır.
İkisi de buradaki diğer her yanıtın kullandığı aynı asgari kimliği — tür, ad ve kaynak dosya — döndürür, fazlasını değil. Bir varlık hakkında görüntülemek isteyeceğiniz diğer her şey aynı üç alan için zaten list-entities içindedir; dolayısıyla birbiriyle çelişebilecek iki kopyayı okumak yerine iki yanıtı birleştirirsiniz. İkisi de çözümleyemedikleri bir adı boş bir listeyle yanıtlamak yerine reddeder; nedeni yüzeyin geri kalanınınkiyle aynıdır: boş bir yanıt, bir yazım hatasını sunacak hiçbir şeyi olmayan bir konu olarak raporlar. Bir labels çağrısında yanlış yazılacak bir ad yoktur; bu yüzden orada boş bir sonuç söylediği anlamı taşır.
Sunucunun başvuru için okuduğu her şey bu makineden sunulur — JSON Schema’lar ikili dosyaya gömülüdür ve belgeler, aşağıda açıklandığı gibi, makinenin tuttuğu belge paketi önbelleğinden okunur. Başlangıç belgesi taslağı oluşturma, doğrulama, tanımlama, derleme ve lint işlemlerinin tümü çalışma alanınıza ve yerel önbelleklere karşı çalışır ve hiçbiri kendiliğinden bir kayıt defterine ulaşmaz: bir işleme, sabitlenmiş bir harici başvuruyu içerik adresli depodan sunar ve sabitlenmemiş birini getirmek yerine reddeder; inceleme ve işleme döngüsünün tamamını çevrimdışı tutan budur. İsteyebileceğiniz iki kayıt defteri okuması vardır: bir kayıt defteri başvurusu verilen describe; bu, o tek koordinatı getirir, hiçbir şey yazmaz ve HTTP üzerinden yalnızca sunulan çalışma alanının yapılandırıldığı bir kayıt defterine ulaşır; ve example ya da list gönderilen scaffold; bu, makinede çalışma alanının imza ilkesinin kabul ettiği bir kopya bulunmadığında belge paketini çalışma alanının varsayılan kayıt defterinden edinir ve saklamadan önce doğrular; aggrega scaffold --example de aynısını yapar. Yayımlama ve imzalama bunun bilinçli olarak diğer tarafıdır ve yukarıda ele alınmıştır.
İkisinin arasında bir Release’in bağımlılıklarını çözümlemek yer alır; bu, buradaki edinen tek şeydir: bir kayıt defterine ulaşır, çünkü bağımlılıkları çözümlemenin istenmesi onları getirmenin istenmesidir. Yalnızca siz istediğinizde gerçekleşir ve istemenin tam olarak iki yolu vardır — tüm işi bu olan pull’u çağırmak ya da aynı çözümlemeyi derlemenin ilk adımı olarak gerçekleştiren build’e auto_pull göndermek. Bunun dışında hiçbir şey sizin adınıza çekme yapmaz ve auto_pull göndermediğiniz bir derleme hiçbir kayıt defterine ulaşmaz. Bunu değiştiren tek ayar, çalışma alanının kendi auto_pull ayarıdır: böyle yapılandırılmış bir çalışma alanı, içindeki her derlemenin, nereden çalıştırılırsa çalıştırılsın, önce çözümleme yapmasını ister; bu aşağıda ele alınmıştır.
Bu başvuru okumaları arasındaki tek istisna, belge paketinin kendisinin edinilmesidir ve bu, her okumadan ayrı gerçekleşir. Paket, her Aggrega projesinin paylaştığı önbellekte, makine başına bir kez, her kayıt defteri ve sürüm için bir kopya olarak tutulur — dolayısıyla hiçbir çalışma alanı önbelleğinin oluşturulamadığı bir klasörde başlatılan bir sunucu da onu yine tutar (bkz. aggrega cache). Sunucu başladığında, gönderdiğiniz herhangi bir şeyi yanıtlamadan önce, orada çalışma alanınızın kendi imza denetiminin kabul ettiği bir kopya arar — paketin bir çekmesinin tabi olduğu denetimin aynısı — ve yalnızca hiç kopya yoksa paketi, CLI’nin geri kalanının kullandığı aynı çıkış ayarları üzerinden çeker. Aradığı paket, sunucunun çalıştırdığı aggrega sürümü için yayımlanmış olandır ya da o sürüm için hiçbiri yayımlanmamışsa daha önceki bir sürüm için yayımlanmış en yenisidir — aggrega explain ve aggrega scaffold --example komutlarının yaptığı seçimin aynısı — ve sunduğu her sayfa ile her açıklama, edindiği paketten okunur. Böylece istemciniz ilk olarak ne gönderirse göndersin, herhangi bir şey bir sayfa istediğinde sayfalar zaten oradadır ve başka bir sunucu ya da başka bir projedeki aggrega explain, onu yeniden indirmek yerine aynı kopyayı bulur.
Bir sayfanın sunulması bundan sonra o kopyanın okunmasıdır ve hiçbir kayıt defterine erişmez. Bir sayfa sunulmadan önce, kopyanın yanında tutulan imzalar çalışma alanınızın denetimi altında yeniden doğrulanır; böylece başka bir projenin daha gevşek ayarının içeri aldığı bir kopya size sunulmaz: denetimin bir anahtarı veya bir güven kökünü sabitlediği yerde bu doğrulama çevrimdışı çalışır, hiçbirini sabitlemediği yerde ise — resmî hub’ın yerleşik denetimi bunlardan biridir — bir pull işleminin yaptığı gibi herkese açık Sigstore güven kökünü edinir. Çevrimdışı bir çalışma alanı o güven kökünü getiremez; bu nedenle çevrimdışıyken, bu makinede daha önce yapılmış çevrimiçi bir getirmenin Sigstore istemcisinin ana dizininizde .sigstore altında tuttuğu önbellekte bıraktığı güven köküne karşı doğrular — o getirme ne kadar önce yapılmış olursa olsun — ve hiçbir şey getirmez; bu kökü hiç getirmemiş bir makinede denetim çevrimdışı çalışamaz, kopya sunulmaz ve günlük akışı bunu bildirir. Bu doğrulama, sunucu çalıştığı sürece her kopya ve her denetim için bir kez çalışır ve ondan sonra okunan sayfalar onun kabul ettiğine dayanarak sunulur: o zamandan beri getirilmiş bir kopya, denetimi farklı olan bir çalışma alanı — yerinde düzenlenmiş sabitlenmiş bir güven kökü de buna dahildir —, çevrimdışı yapılan bir okuma veya makinede bırakılmış farklı bir güven kökü bulan çevrimdışı bir okuma kendi başına doğrulanır. Denetiminizin reddettiği bir kopya bir sonraki okumada yeniden denetlenir; böylece o zamandan beri onu kabul etmiş bir getirme geçersiz kılınmaz. Paket edinilemezse ya da tek kopya denetiminizin reddettiği bir kopyaysa ve onu o denetim altında yeniden getirme başarısız olursa, sunucu yine de başlar ve diğer tüm yüzeyler çalışır; dokümantasyon istekleri bulunamadı yanıtını verir ve sunucunun günlük akışı nedenini bildirir.
Bir Release’in zaten sabitlediği içeriğe karşı derleme
build, bir Release’i bellekte yapıtlarına dönüştürür ve bir render işlemi uzak bir URL’den içerik isteyebilir; örneğin uzak bir referans içeren bir chart’ın values şeması. Dış girdiler çağrı süresince dondurulur. Release’in kilit dosyasının zaten sabitlediği bir referans, içerik adresli depodan sunulur; bu bir getirme değil, diskte zaten bulunan içeriğin okunmasıdır. Kilit dosyasının sabitlemediği bir referans ise getirilmek yerine reddedilir ve adıyla belirtilir: istediğiniz şey bir render’dır ve bir referansı edinmek, bayt üretmenin yan etkisi olarak hem ağa erişmek hem de depoya bir blob yazmak anlamına gelir. Bu dondurma, render’ın bir özelliğidir. Edinen adım çözümlemedir: Release’i, o render’ın hangi uzak referansları istediğini bulmak için render eder, bunları getirir ve bağımlılık sabitlemelerini taşıyan aynı kilit dosyası yazımında kaydeder. Dolayısıyla çözümlemenin değiştirdiği şey, bir render’ın neye erişebileceği değil, bir render çalıştığında hangi referansların sabitlenmiş olduğudur; hiçbir çözümlemenin sabitlemediği bir referans, önce çözümleme yapan bir çağrıda da yapmayan bir çağrıda olduğu gibi aynen reddedilir.
Dosyalar, gerçek bir derlemenin ürettiği baytlar olarak geri gelir ve bunu doğru kılan iki şey birlikte vardır. Biri yukarıdaki dondurmadır: sabitlenmiş bir referans getirilmek yerine depodan okunur. Diğeri, okunan kilit dosyasının hâlâ Release’in çözümlendiği şeyi tanımlamasıdır; bu yüzden build bunu denetler ve artık eşleşmeyen bir kilit dosyasını, bir terminaldeki aggrega build gibi aynen reddeder. Sabitlenmiş baytları okumak, tek başına bunların okunması gereken doğru baytlar olup olmadığı hakkında hiçbir şey söylemez.
Tutumun açık olması için kilit dosyasının üç durumu. Hiç kilit dosyası yoksa build, çalışma alanının zaten sabitlediği her şeyden render eder ve sunamadığı her dış referansı, her birini adıyla belirterek reddeder; kendi hâline bırakıldığında ne bir kilit dosyası gerektirir ne de bir tane yazar ve bu, yukarıdaki denetimle değişmez: karşılaştıracağı bir kilit dosyası olmadığından hiçbir şey reddedilmez. Eşleşen bir kilit dosyasıyla render eder. Artık eşleşmeyen bir kilit dosyasıyla reddeder ve ret, durumun nasıl giderileceğini belirtir: pull aracını aynı release ile ve upgrade_targets olmadan çağırın; bu, kilit dosyasını Release’in bugün çözümlendiği şeyle uzlaştırır. Ret ayrıca aynı işlemin terminal biçimini de taşır: aggrega pull --release <release>. İki çağrı da durumu giderir; bunlar arasında seçim yapılacak iki talimat değil, iki yerden erişilebilen tek bir işlemdir. pull tamamlandığı hâlde ret geri geliyorsa, iki çağrı farklı girdiler üzerinden çözümleme yapmıştır; çoğunlukla catalog_dirs birine verilip diğerine verilmemiştir ya da aralarında bir çalışma alanı yapılandırması düzenlenmiştir. Ret bunu belirtir: ikisini de aynı girdilerle çağırın.
Yalnızca bir release gönderilen validate ve describe aynı kilit dosyasına tabidir. Release’in çözümlendiği şeyle artık eşleşmeyen bir kilit dosyası karşısında her biri yanıt vermek yerine reddeder; metni, build aracının reddederken kullandığı sapma durdurmasını ve onu gidermenin aynı yolunu taşır — tıpkı aggrega validate --release ve aggrega inspect --closure komutlarının terminalde reddettiği gibi. Eşleşen bir kilit dosyasıyla ya da hiç kilit dosyası olmadan her biri normalde nasıl yanıt veriyorsa öyle yanıt verir.
Bir derlemeden önce bağımlılıklarını çözümlemesini isteme
auto_pull gönderin; derleme render etmeden önce çözümleme yapar. pull aracının yaptığı çözümlemenin aynısını yapar (bir derleme için yazılmış ikinci bir işlem değil, işlemin kendisi; böylece bir derlemenin doldurduğu çalışma alanı ile bir pull çağrısının doldurduğu çalışma alanı aynı biçimde doldurulur), Release’in kilit dosyasını yazar ve ardından yazdığı şeye karşı render eder. Bu adım bir kayıt defterine erişir ve yazar; build ile ilgili başka hiçbir şey bunu yapmaz, write dışında, ve write hiçbir kayıt defterine erişmez. Bu yüzden istenmedikçe kapalıdır.
Yukarıdaki iki reddi protokolden çıkmadan yanıtlar. Henüz kimsenin çözümlemediği bir Release, o anda orada bulunan sabitlemelerden render eder ve gerisini reddeder; sapmış bir kilit dosyası derlemeyi doğrudan durdurur. auto_pull göndermek önce çözümleme yapar ve bu derlemenin ilgilendiği kapanıştan türetilmiş bir kilit dosyasına karşı render eder; böylece her iki durum da gidip düzeltilecek bir şey olarak değil, bir render olarak geri gelir. Çözümleme ile render’ı ayrı adımlar olarak istediğiniz yerde (render etmeden önce neyin sabitlendiğini okumak için) pull ve ardından build çağırın; bu, arada bir bakışla aynı iki işlemdir.
Tek bir çağrı Release’i bir kez render eder. Bir Release’in hangi uzak referansları kullandığını bulmak başlı başına bir render’dır; dolayısıyla bir çözümleme, derlemenin ilgilendiği Release’i zaten render etmiştir: tam da az önce yazdığı sabitlemelere karşı ve bir derlemenin çalıştırdığı her denetimle. Derleme, render’ı yinelemek yerine o render’dan yanıtlanır; auto_pull göndermenin ikinci bir render’a değil bir çözümlemeye mal olmasının nedeni budur. Bu şekilde yalnızca tamamlanmış bir render kullanılır: bir çözümleme bağımlılıklarını sabitlediği ama dış referansları keşfetmeyi bitiremediği yerde, derleme yerleşen sabitlemelere karşı kendisi render eder ve sabitlenmemiş bir referans bu durumda, bir derlemenin ürettiğinin gerisinde kalan bir dosya listesi olarak geri gelmek yerine derlemeyi adıyla durdurur.
Geri gelen yanıt neyin çözümlendiğini söyler. Doldurma yapan bir derleme, yanıtında pull aracının yanıt verdiği biçimde dependency_resolution taşır: yazdığı kilit dosyası, çözümlemenin eriştiği her referans ile her birinin çözümlendiği sürüm ve bu derlemenin çözümlemesinin onu nereden aldığı, kilit dosyasının sonrasında tuttuğu sayılar ve çözümlemenin satır satır kendi dökümü. Doldurma yapmayan bir derleme böyle bir alanı hiç taşımaz; dolayısıyla bu alanın varlığı, diski okumadan ikisini ayırt etmenin yoludur. Render edilen dosyalar, diğer her derlemede olduğu gibi aynen bildirilir ve çağrıya ayrıca write gönderilmedikçe yine bellekte döndürülür: çözümleme kilit dosyasını ve yapıt önbelleğini yazar, hiçbir zaman bir yapıtı yazmaz.
Bir çalışma alanı bunu kalıcı olarak isteyebilir ve bir çağrı bunu kapatamaz. Çalışma alanının kendi auto_pull ayarı, aynı adımı o çalışma alanındaki her derleme için açar ve bir çağrıdaki auto_pull bu ayarı geçersiz kılmaz, ona eklenir: ikisinden biri yeterlidir ve çalışma alanının istediği bir çözümlemeyi bastıran hiçbir argüman yoktur. Bu, ayarın ve aggrega build --auto-pull seçeneğinin bir terminalde birleştiği yolun aynısıdır; böylece bir derleme hangi yüzeyden gelirse gelsin tek bir çalışma alanı aynı biçimde yanıt verir.
Ret sessizce yutulmaz, bildirilir ve bu ikili dosyanın taşıdığı sağlayıcılarla bir ret render’ı durdurur: referansı isteyen sağlayıcı reddi geri verir, böylece çağrı bu hatayla yanıt verir ve hiçbir dosya döndürmez. Referans, okuyanın üzerinde işlem yapabileceği bir yerde, onu sabitleyen komutla birlikte adıyla belirtilir: aggrega pull --release <path>. Aynı sabitlemeye bu yüzeyde pull aracı olarak erişilebilir; bu araç aşağıda Bir Release’in neye bağlı olduğunu çözümleme bölümünde açıklanır. Böylece bu retle karşılaşan bir asistan, protokolden çıkmadan bunun üzerine işlem yapabilir. Tamamen sabitlenmiş bir render bunların hiçbirinden söz etmez. Sabitlemenin neyi getirip kaydettiği için aggrega pull sayfasına, sabitlenmemiş bir referansın aynı şekilde bildirilip çalıştırmayı durdurduğu durum için aggrega build sayfasına bakın.
Yapıtları aggrega build komutunun yazdığı yere yazmak
write gönderin; tamamlanan render ayrıca çalışma alanı kökündeki dist/ dizinine, aggrega build komutunun yazdığı yere yazılır. Dizin, komut satırının aynı çalışma alanı kökü altında oluşturduğu dizindir ve yazma işlemi de onun gerçekleştirdiği işlemdir; dolayısıyla tek bir çalışma alanındaki tek bir Release için aggrega build, dil sunucusunun hiçbir outputParent belirtmeyen aggrega/build isteği ve bu çağrı bayt bayt aynı ağacı yazar ve o dizini aynı biçimde adlandırır: komutun son satırı, dil sunucusunun outputDirectory değeri ve bu yanıtın output_dir alanı. Çalışma alanının dışına çıkan bir bağlantı olan dist, terminalde olduğu gibi, içindeki herhangi bir şey silinmeden veya yazılmadan önce reddedilir. Varsayılan durumda olduğu gibi gönderilmezse yapıtlar bellekte döndürülür ve hiçbir şey yazılmaz.
Çalışma alanı kökü çağrının kendisine aittir. Standart giriş ve çıkış üzerinden bu, Bir çağrının hangi çalışma alanında yanıtlandığı bölümünde açıklandığı gibi çağrının çözümlediği çalışma alanının köküdür: workspace_root değerinin belirttiği kök, yoksa sunucunun başlatıldığı kök, o da yoksa sunucunun başlatıldığı dizinden bulunan çalışma alanı; mutlak yolla belirtilen bir Release çağrıyı o Release’in kendi çalışma alanına taşıyorsa da o çalışma alanının kökü. Bu, aggrega build komutunun aynı Release ve aynı belirtilen kök için altına yazdığı köktür; dolayısıyla sunucunun o an çalıştığı klasör, ancak o klasör çağrının çözümlediği kökse, tıpkı orada açılmış bir terminalde olacağı gibi bir dist alır. HTTP üzerinden bu, sunucunun hizmet verdiği çalışma alanıdır ve onun dışına hiçbir şey yazılmaz.
Yazma çalışma alanına erişir, bu nedenle HTTP üzerinden aggrega:workspace-write gerektirir. write gönderilen bir çağrı, bağımlılıklarını önce çözümleyen bir derlemenin yaptığı gibi, o çağrı için çalışma alanına erişir: yalnızca aggrega:read taşıyan bir kimlik bilgisi aggrega:workspace-write adını veren bir 403 ile yanıtlanır ve hiçbir şey yazılmaz; mcp.deny_reach ayarı workspace değerini içeren bir sunucu da çağrıyı bu ayarı adlandırarak reddeder. Araç her çağıranın araç listesinde kalır ve write gönderilmeyen bir derleme, okuma kapsamlı bir çağırana açık kalır.
En son yazar. auto_pull da gönderildiğinde çağrı sırasıyla çözümler, render eder ve ardından yazar. Daha önceki herhangi bir noktada (Release’i, çalışma alanı, bir katalog dizini, çözümleme, render) reddedilen bir çağrı hiçbir yapıt yazmaz.
Yanıt, yazılanları adlandırır. output_dir dizindir (standart giriş ve çıkış üzerinden tam yoluyla, HTTP üzerinden dist olarak) ve files yazılan her dosyayı bu dizine göreli olarak listeler: response_format: detailed altında içeriğiyle, concise altında yalnızca yoluyla; metin kaç dosyanın nereye yazıldığını belirtir. write gönderilmeyen bir çağrı output_dir taşımaz; dolayısıyla bu alanın yokluğu, hiçbir şeyin yazılmadığını anlamanızı sağlar. Render tamamlandıktan sonra başarısız olan bir yazma (örneğin kimsenin yazamadığı bir çalışma alanı köküne) dizini ve nedeni adlandıran bir hata olarak yanıtlanır ve hiçbir dosyayı yazılmış olarak listelemez: yazmanın bir kısmı diskte olabilir ve render edilen dosyaları yazılmış olarak adlandırmak gerçekleşenden fazlasını iddia etmek olur.
Hiçbir argüman bir dizin belirtmez ve hiçbiri iz istemez. Yapıtların nereye gideceğine çağrı değil, çağrının çözümlediği çalışma alanı karar verir; buradan yazılan bir derleme çıktısının yanında .trace dizini bırakmaz. İzli bir derleme için aggrega build --trace kullanılır.
Bir derlemenin dosyaları dışında size söyledikleri
Bir derleme, ortaya çıkardığı her uyarıyı yanıtın kendisinde taşır. Bunlar aggrega build’in çalışırken yazdırdığı bulgulardır: bildirilmiş bir addan tek düzenleme uzaklıktaki bir ad, hiçbir şeyin okumadığı bir parametre, yazılmış bir alanı karşılayamayan bir hedef, durdurmayan bir yönetişim kararı, bir Release’in genişlettiği Release’ten devraldığı ve aynı yola çözümlenen bir sınır dizini, Release’in ulaştığı bir Component’in veya Feature’ın hem values hem de infra sütunlarında bildirdiği bir özellik. Bunların hiçbiri sonucu değiştirmez: uyarı taşıyan bir derleme yine de başarılı olmuştur ve döndürdüğü dosyalar ürettiği dosyalardır. Uyarılar bir terminalin onları yazdırdığı sırayla gelir; böylece ikisini karşılaştıran bir okuyucu iki değil tek bir dizi bulur: önce render işleminin ortaya çıkardığı her şey, ortaya çıkardığı sırayla, ardından da aggrega build’in render işlemi döndükten sonra yazdırdığı, Release ve ulaştıklarıyla ilgili bulgular ve son olarak, write gönderilmiş bir derlemede, yazma işleminin kendi dosyalarının yanında bulduğu ve kendisinin yazmadığı her dosyayı adlandıran, bu dosyaları yerinde bırakan uyarı — aggrega build’in dosyalarını yazdıktan sonra yazdırdığı uyarı (Derlemenin yazmadığı dosyalar).
Bunlar yalnızca özet metinde değil yanıtın üzerinde de bulunur; çünkü bu yüzeyi yöneten bir asistan hiçbir terminal okumaz ve kimseye bildirilmeyen bir bulgu, yapılmamış bir bulgudur. Her biri bir severity (dikkat gerektiren bir şey için warn, kaydedilen bir gözlem için info) ve bir message taşır; sınıfının atadığı yerde bir code taşır, böylece metin eşleştirmeden belirli bir duruma tepki verebilirsiniz; ve bulgu yazılmış belgedeki bir anahtarla ilgiliyse o anahtarı adlandıran bir key_path taşır. Dağıtılan topolojinin biçimiyle ilgili bir bulgu hiçbir anahtarı adlandırmaz, çünkü koordinatları bir belgeye değil dağıtıma aittir; bunun yerine neyle ilgili olduğunu mesajında söyler.
Bir terminalin yazdırdığı iki tür bulgu bu yanıta advisories dışında bir yerden ulaşır, çünkü her birinin daha fazlasını söyleyen bir yeri vardır. Kaydedilmiş bir kullanımdan kaldırma işareti, ister lockfile onu sabitlenmiş bir başvuruya karşı kaydetmiş olsun ister yanındaki eklenti güven kaydı onu kabul ya da ret kararı döndüren bir rolde bağlanmış bir eklentiye karşı kaydetmiş olsun, deprecations üzerindedir. Bir Release’in describe çağrısı aynı kümeyi kendi deprecations alanında, bir Release’in validate çağrısı ise notices arasında adlandırır ve her biri kararı olduğu gibi bırakır; mevcut olup okunamayan bir güven kaydı, hiçbir şey kaydetmeyen bir kayıt sayılmak yerine her iki çağrının da reddedilmesine yol açar. Bir varlığın devraldığı ve çözümlenemeyen bir üst öğe derlemeyi durdurur; bu nedenle hiçbir şeyi değiştirmemiş bir bulgu olarak listelenmez, reddin metninde adlandırılır. Bir tür ise bu aracın yanıtının taşıdıklarıyla değil yükledikleriyle sınırlıdır: aggrega build bir Release’i çözümlemeden önce yapılandırılmış her katalog dizinini yükler ve kullanımdan kaldırılmış bir katalog biçimiyle ilgili bir bildirim bu yüklemeden gelir; bu araç ise yalnızca Release’in ulaştığı şeyleri okur ve böyle bir yükleme yapmaz, dolayısıyla böyle bir bildirim raporlamaz. Şu anda hiçbir derleme böyle bir bildirim ortaya çıkarmadığından ikisi aynı bulguları raporlar.
Hiçbir şey ortaya çıkarmayan bir Release hiçbir şey söylemez: anahtar mevcut ve boş olmak yerine hiç bulunmaz; bu nedenle yalnızca varlığı, okunacak bir şey olduğunu size söyler.
Reddedilen bir derlemenin geri döndürdükleri
Reddeden bir derleme, başarılı bir derlemenin yanıt verdiği alanlarla yanıt verir; bu alanlar çalıştırmanın ulaştığı noktaya kadar doldurulur. Yanıt, metni düzeltme olan bir hata olarak işaretlenmiş şekilde döner ve yapılandırılmış yük bu metnin yerine geçmez, onun yanında durur. Release işlenirken ortaya çıkan bir ret, aşağıda İşleme sırasında ortaya çıkan bir ret bölümünün açıkladığı gibi derleyicinin sözcükleriyle okunur ve kendine ait bir alan ekler. Uyarılar yanıttadır: çalışan aşamalar ne ortaya çıkardıysa onu ortaya çıkarmıştır ve bunlar reddi aşmak için üzerinde işlem yapmanız gereken bulgulardır; bu yüzden ayrıştırmanız gereken düz yazı olarak değil, eşleştirebileceğiniz girdiler olarak gelirler. deprecations ve declined_external_inputs da aynı nedenle yanıttadır: kaydedilmiş bir işaret, bir işaret kaydedildiği için bildirilir; reddedilmiş bir başvuru da bir başvuru reddedildiği için bildirilir ve bu olguların hiçbiri çalıştırmanın nasıl sona erdiğinin bir sonucu değildir.
files bir ret durumunda hiçbir şey bildirmez ve sonucun okunacağı alan değildir. Hiçbir şey üretilmediği için adlandırılacak yapıt yoktur. Anahtarın var olup olmamasına göre dallanmayın: anahtar her iki durumda da bildirilir ve boş bir files tek başına, reddeden bir derlemeyi çalışıp hiçbir şey üretmeyen bir derlemeden ayırt edemez. Sonuçtaki hata işaretini okuyun (protokolün kendi ayırt edicisi budur) ve files alanını ne ise o olarak okuyun: işlenenlerin listesi ve çağrıya write gönderildiği durumda yazılanların da listesi.
Bir ret durumunda uyarıları sınırlayan, yanıtın neyi taşıyabildiği değil, çalıştırmanın ne kadar ilerlediğidir. Release çözümlenmeden önce çalışan bir denetimden gelen ret (önbellekteki sabitlenmiş bir girdi artık kendisi için kaydedilen özetle eşleşmiyorsa ve sabitlenmiş baytları hiçbir katalog dizini barındırmıyorsa ya da Release’in bağlı olduğu şeyler çözümlenemiyorsa) hiçbir uyarı bildirmez, çünkü henüz hiçbir şey ortaya çıkmamıştır. Bir Release’in genişlettiği Release ile nasıl birleştiğine ilişkin bulgular, Release çözümlendiği anda ve ardından gelen her denetimden önce ortaya çıkar; bu nedenle sonraki her ret bunları taşır: Manifest bir türü onu uygulamayan bir recipe’ye eşler, Release’in ulaştığı bir varlık şemasını karşılamaz, kilit dosyası artık Release’in çözümlendiği şeyle eşleşmez. İşlemenin kendi bulguları işleme çalışırken ortaya çıkar; bu nedenle bu önceki denetimlerden birinden gelen bir ret bunların hiçbirini taşımaz, işlemeden gelen bir ret ise kendisinden önce ortaya çıkan her şeyi taşır. Dolayısıyla bir ret durumunda advisories alanını tam olarak başarı durumunda okuduğunuz gibi okuyun: bu çalıştırmanın bulduklarını, bir terminalin yazdırdığı sırayla.
Bir varlığın çözümlenemeyen bir üst öğeden devraldığı için verilen ret, metninde bu tür her devralmayı adlandırır; bunu aggrega build komutunun yazdırdığı sözcüklerle yapar, böylece hangisini onarmanız gerektiğini bilirsiniz. Bu ayrıntı derlemenin durma nedenidir; bu yüzden hiçbir şeyi değiştirmeyen bulgular arasında değil, metindedir. Ondan önce ortaya çıkan birleşim bulguları, sonraki herhangi bir retteki gibi advisories alanındadır.
Release’in okuduğu ve dolaşılamayan bir katalog dizini, herhangi bir şey yazılmadan önce, aggrega build komutunun reddettiği gibi reddedilir. Bu, çağrının catalog_dirs içinde adlandırdığı ve var olmayan bir dizindir (aggrega build komutunun var olmayan bir --catalog dizinini reddettiği gibi) ya da var olan ama okunamayan bir dizindir. aggrega build, Release’i çözümlemeden önce Release’in okuduğu her dizini yükler ve dolaşamadığı bir dizinde durur; build aynı dizinleri, içlerindeki hiçbir belgeyi okumadan, herhangi bir bağımlılık çözümlemesinden ve işlemeden önce dolaşır. Bu yüzden auto_pull gönderilmiş bir derleme hiçbir kilit dosyası yazmaz ve hiçbir şey işlenmez. Metin dizini komut satırının bildirdiği şekilde, tek satırda adlandırır: dizin, catalog load ve dosya sisteminin verdiği neden. Yük, Release’i boş bir files ile ve hiçbir bulgu olmadan adlandırır, çünkü hiçbir şey çalışmamıştır. Çalışma alanı yapılandırmasının dizin olarak listelediği ama dizin olmayan bir yol (örneğin orada hiçbir şey bulunmuyorsa) o dolaşmadan önce, aynı biçimde reddedilir; metin, aggrega build komutunun buna verdiği reddi taşır ve girdiyi, onu listeleyen yapılandırma dosyasını ve satırı adlandırır (Yerel varlıkların okunduğu yer). Okumalarının içinde kalması gereken dizinin dışına çıkan bir bağlantı barındıran bir katalog dizini de aynı anda, hiçbir şey yazılmadan reddedilir; metin bağlantıyı ve nereye çıktığını adlandırır. aggrega build de bunu aynı şekilde reddeder.
Yarıların somutlaşması için işlenmiş bir örnek. Hiçbir başvurunun okumadığı bir parametre bildiren ve ardından işlemesi tamamlanamayan bir Release, metni işlemenin reddini taşıyan ve yükü okunmamış parametre uyarısını severity, message, code ve key_path alanlarıyla taşıyan bir hata olarak döner (aynı Release’in işleme tamamlandığında yanıtta bildirdiği, aynı değerlere sahip aynı girdi); bu girdi, işlemeyi durduran şey için refusal girdisinin yanındadır. Başka bir Release’i genişleten ve şablon değişkeni taşımayan bir sınır dizinini devralan, Manifest’i bir türü onu uygulamayan bir recipe’ye eşleyen bir Release, devralınan her dizin için bir advisories girdisiyle, her biri code değeri inherited-boundary-directory-is-literal olacak şekilde, o ret olarak döner. Listelenen katalog dizinlerinin tümü var olan bir çalışma alanında bağımlılıkları çözümlenemeyen bir Release, hiçbir advisories anahtarı olmayan bir hata olarak döner, çünkü durduğunda henüz hiçbir şey ortaya çıkmamıştır.
Render sırasında yükseltilen bir ret
Derleyicinin render sırasında reddettiği bir Release — Component’inin bildirmediği bir slotu adlandıran bir Workload, başarısız olan bir doğrulama, değerlendirilemeyen bir şablon — reddi derleyicinin kendi sözcükleriyle ve altındaki her nedenle birlikte döner; bunlar cli-build aracının aynı Release için döndürdüğü sözcüklerdir: render edilen düğüm, ardından o düğümde neyin reddettiği. Ret kayıtlı bir koşulu adlandırdığında metin, explain-error aracının yapacağı gibi, o koşulun adını — eşleştirme için kısa kodu ve açıklayıcı kodu — ekler. Metin, hangi aşamanın reddettiğini söyleyerek başlar: render’ın yükselttiği bir ret için The build failed during rendering; nothing was written to disk., derleyicinin çalışmasının herhangi bir şey render edilmeden önce yükselttiği bir ret için ise The build refused before rendering anything; nothing was written to disk. — render’ın üzerinde çalıştığı grafiğin bileşiminin reddetmesi ya da bir Component’in veya bir Feature’ın bildirdiği bir doğrulama.
Yük, aynı reddi tek bir girdi olarak, refusal olarak taşır; böylece bir belgeyi değiştirmesi gereken bir çağıran, cümleyi ayrıştırmadan hangi belgeyi ve nerede değiştireceğini okur:
file— reddin işaret ettiği belge: bir Workload’un Recipe’si, başarısız bir doğrulamayı bildiren Recipe ya da FeatureRecipe, grafiğin bileşiminin reddettiği bir girdiyi yazan Release ya da Aggregate veya hiçbir belgeyi işaret etmeyen bir ret için Release’in Aggregate’i.key_path— ret bir anahtar adlandırdığında oradaki anahtar: bir Workload hakkındaki ret için.spec.workload, başarısız bir doğrulama için doğrulamanın.spec.assertionsaltındaki kendi anahtarı, bir girdinin reddi için girdinin kendi anahtarı. Bir Workload hakkındaki ret, onunworkloadanahtarına yerleştirilir ve daha ince bir düzeye inilmez; çünkü bir denetimin değerlendirdiği Workload, şablonunun ürettiği şeydir ve bir şablon, yazarının hiç yazmadığı satırlar yazar; reddin render edilmiş o Workload içinde adlandırdığı yollarmessageiçinde kalır.linevecolumn— o anahtarın konumu, birden başlayarak sayılır; sütun UTF-16 birimleriyle verilir. Ret hiçbir anahtar adlandırmadığında ya da belge o anahtarı içermediğinde yoktur: konum yalnızca bir konum bulunduğunda verilir.severity—halt, bir derlemeyi durduran bulgunun önem derecesi.codeveshort_code— ret kayıtlı bir koşulu adlandırdığında, koşulun iki tanımlayıcısı.message— reddin metni, yanıtın metninde göründüğü biçimiyle aynen.findings— yalnızca ret birden çok bulguyu birleştirdiğinde bulunur; grafiğin bileşiminin bulduğu her ihlalle yaptığı gibi: bulgu başına bir girdi, reddin onları belirttiği sırayla, her biri bu aynı biçimde — kendifile,key_path,line,column,severity,code,short_codevemessagealanlarıyla. Bu durumda reddin kendi alanları ilk bulgusunun işaret ettiği yeri adlandırır vemessagealanı, metnin yaptığı gibi, her bulguyu taşır; komut satırı her bulguyu ayrı bir tanılama olarak yazdırır.
Girdi, derleyicinin kendi çalışması her reddettiğinde bulunur — render sırasında ya da render etmeden önce: grafiğin bileşiminde veya bir Component’in ya da bir Feature’ın bildirdiği, hiçbir belgeyi adlandırmayan bir doğrulamada; bu durumda girdisi Aggregate’i adlandırır. Başarılı bir derleme hiçbir girdi taşımaz; derleyici başlamadan önce çalışan bir denetimin — lockfile, Manifest’in eşlemeleri, Release’in neye bağımlı olduğu — reddettiği bir derleme de taşımaz; onun reddi yalnızca metindir. Bir yazarın hassas olarak bildirdiği bir değer, derleyicinin reddi yükselttiği yerde retten saklanır; böylece girdi ve metin, cli-build aracının ve terminalin taşıdığını taşır — bkz. bir reddin bildirilmiş bir değer hakkında söyledikleri.
Bir Release’in neye bağlı olduğunu çözümleme
pull, bir Release’in katalog ve kaynak bağımlılıklarını yerel önbelleğe çözümler ve o Release’in kilit dosyasını yazar. Bu yüzeyde bulunmasının belirtilmeye değer bir nedeni vardır: yukarıdaki iki ret — sabitlenmemiş bir harici başvuruyu reddeden bir render ve kilit dosyası artık Release’in çözümlendiği şeyle eşleşmediği için duran bir derleme — sabitlemeyle yanıtlanır ve sizden bir komut çalıştırmanızı istemek zorunda kalan bir asistanın bunları kendisinin yanıtlama yolu yoktur. Neyi yazdığı ve bunun nereye kadar uzandığı için Bir asistanın size sormadan yapabilecekleri bölümünü okuyun.
release olarak Release yolunu, mutlak ya da çalışma alanı köküne göreli biçimde verin — buradaki diğer her yol argümanının kullandığı sözleşmenin aynısı. workspace_root ve catalog_dirs, çalışma alanı ve katalog keşfini tam olarak build üzerinde yaptıkları gibi geçersiz kılar. Her ikisi de standart giriş ve çıkış üzerinden erişilen bir sunucuda geçerlidir; HTTPS üzerinden bu iki argüman reddedilir ve yol, Tek süreç, tek çalışma alanı bölümünde açıklandığı gibi sürecin hizmet verdiği çalışma alanının içinde çözümlenmelidir.
Varsayılan olarak yeniden çözümlemek yerine uzlaştırır. Kilit dosyasının zaten kaydettiği bir sabitleme dikkate alınır ve o sürümde getirilir; kayıt defteri artık bu baytları sunmuyorsa sessizce yeniden sabitlenmek yerine reddedilir. Sabitlemesi olmayan bir başvuru — yeni eklenmiş ya da kilit dosyasından elle kaldırılmış — baştan çözümlenir ve eklenir. Artık çözümlenen bağımlılıklar arasında olmayan bir başvuru budanır. Bu nedenle değişmemiş bir bağımlılık kümesi dosyayı kaydedilmiş zaman damgası dahil bayt bayt aynı bırakır; böylece hiçbir sabitlemeyi değiştirmeyen bir çağrı, çalışma alanını sonradan inceleyen kimse için bir fark üretmez.
verify karşılaştırır ve kilit dosyasını olduğu gibi bırakır. Kaydedilmiş kilit dosyasını, yukarıdaki uzlaştırıcı çağrının şu anda gerçekleştireceği çözümlemeyle karşılaştırır, kaydedilmiş sabitlemeleri tam olarak o çağrının yaptığı gibi dikkate alır ve sapma olduğunda ya da karşılaştırılacak bir kilit dosyası olmadığında başarısızlık olarak döner — dolayısıyla bir asistan, herhangi bir şey kilit dosyasını yeniden yazmadan önce sabitlemenin gerekip gerekmediğini bu yolla öğrenir. O çağrının kaydettiği hiçbir şey yazılmaz — ne kilit dosyası, ne yanında kaydedilen plugin kimlikleri, ne bir entity.lock — oysa içerik önbelleği tam olarak o çağrının okuyup doldurduğu gibi okunur ve doldurulur. Ayrıca kilit dosyasının kaydettiği araç zincirini de bildirir: dosyayı yazan derleyici sürümü ve o derleyicinin taşıdığı her çekirdek plugin’in sürümü. Bu, denetim için bildirilir ve çalışan ikili dosyayla asla karşılaştırılmaz; çünkü araç zinciri kilit dosyasının sabitlediği şeyin bir parçası değildir ve onu denetlemek derleyiciyi dolaylı olarak sabitlemek olurdu — bir araç zinciri farkı sapma değildir.
upgrade_targets yalnızca adını verdiğiniz başvuruları yeniden çözümler, başka hiçbir şeyi değil. Ona yazıldığı çıplak biçimde bir ya da daha fazla varlık URI’si verin — sürümlü bir biçim değil, core/database. Adı verilen her sabitleme bırakılır ve mevcut en yüksek sürüme yeniden çözümlenir; diğer tüm sabitlemeler ve kaydedilmiş harici girdiler değiştirilmeden tutulur. Ne kaydedilmiş bir sabitlemeyle ne de yapılandırılmış bir eklemeyle eşleşen bir URI yok sayılmak yerine reddedilir.
Her şeyi tek seferde yeniden çözümleyen bir argüman bilerek yoktur. Komut satırında bu biçim vardır ve güncel kayıt defteri durumundan yeniden çözümlemeden önce kilit dosyasının tamamını atar. Bu yüzeyde argüman mevcut değildir; böylece çağrı kabul edilip ardından reddedilmek yerine hiç oluşturulamaz: bir protokol akışını kimse izlemiyordur, dolayısıyla toptan bir atmayı onaylayacak kimse yoktur. Bunu istediğiniz yerde, ve yalnızca standart giriş ve çıkış üzerinde, komutu cli-pull çalıştırır; bu, bir kişinin bulunduğu yüzeydir; bu sunucuya HTTP üzerinden erişen bir çağıran ise bunun yerine komutu ana makinedeki bir terminalde çalıştırır. verify, upgrade_targets ile birleştirilemez — biri kilit dosyasını olduğu gibi bırakır, diğeri yeniden yazar — taşıdığı değer ne olursa olsun pin_sources ile de birleştirilemez: o argüman, bir çözümlemenin bir entity.lock içinde eksik olan sabitlemeleri kaydedip kaydetmeyeceğine ya da bunlar yüzünden reddedip reddetmeyeceğine karar verir; bir karşılaştırma ise hiçbir entity.lock yazmaz, dolayısıyla ikisini de yapmazdı. Bu çiftlerden birini gönderen bir çağrı, herhangi bir şey çözümlenmeden önce, çifti adlandıran bir cümleyle reddedilir. Aracın duyurulan şeması bu iki dışlamayı belirtmez, çünkü onu görüntüleyen bir istemci bunu verify gönderme zorunluluğu olarak okuyabilir; istemci bunları retten öğrenir. Komut satırı ve daemon aynı çiftleri reddeder.
Sonuç, yalnızca bir şeyin çözümlendiğini değil, neyin çözümlendiğini adlandırır. Yazdığı ya da karşılaştırdığı kilit dosyasını taşır; resolved: çözümlemenin ulaştığı her başvuru, her birinin çözümlendiği sürüm, çözümlemenin bir tür kaydettiği yerde bir yazarın yazdığı tür ve source değeri — bu çalıştırmanın başvuruyu nereden aldığı; aggrega pull --detail komutunun aynı çözümleme için yazdırdığı sözcükle: fetched-fresh, cache-reuse, local, in-binary ya da external; kilit dosyasının sonrasında tuttuğu kaynak yapıtların, harici girdilerin ve güvenilen plugin kimliklerinin sayıları; ve diagnostics: çözümlemenin her satırı ortaya çıkardığı sırayla kendi hakkındaki anlatımı — hangi sabitlemenin yeniden kullanıldığı, hangi imzanın denetlendiği, hangi sürümün geri çekildiği için atlandığı. Komutu çalıştırdığınızda bu satırlar bir terminale ulaşır; burada yanıtın içindedirler, çünkü hiçbir terminal okumayan bir çağıranın onları almanın başka yolu yoktur. verified yalnızca bir karşılaştırmada bulunur; dolayısıyla yazan bir çalıştırmayı yalnızca karşılaştıran bir çalıştırmadan onun yokluğuyla ayırt edersiniz. Bir source bu makinedeki bu çalıştırmayı tanımlar; bu yüzden kilit dosyası onu kaydetmez ve bir Release’in neye bağlı olduğunu bildiren describe hiçbirini adlandırmaz.
Bir ret, çalıştırmanın ulaşabildiği ölçüde doldurulmuş aynı alanlarla yanıt verir. Çözümleme hesaplandıktan sonra, karar ne olursa olsun resolved taşınır — en çok da bir sapma kararında, çünkü bu, çağıranın neyi değiştireceğine karar vermesi gereken rettir. O noktadan önceki bir ret, örneğin çözümlenmeyen bir Release yolu, düzeltmeyi metni olarak taşır ve çözümleme taşımaz, çünkü taşınacak bir çözümleme yoktu.
Sabitlemeler tamam, harici girdiler değilse çağrı yine de başarılı olur ve bunu belirtir. Bir Release’in hangi harici girdileri tükettiğini keşfetmek bir render’dır ve bir render, bağımlılık sabitlemeleri zaten doğru ve diskte olduktan sonra başarısız olabilir. Çağrının tamamını başarısız olarak bildirmek size doğru olan işi yeniden yapmanızı söylerdi; bu yüzden bunun yerine başarılı sonuçta incomplete_external_inputs ayarlanır ve neyin durduğunu adlandırır: bağımlılık sabitlemeleri tamamdır, harici girdi sabitlemeleri olmayabilir.
Buradaki en yavaş araç budur ve uzlaştırıcı boş işlem hızlı bir yol değildir. Bir çözümleme, bir bağımlılık kümesinin değişmediğini saptamak için tam maliyetini öder; dolayısıyla hiçbir şeyi yeniden yazmayan bir çağrı, ilk çözümlemenin maliyeti kadar tutar — küçük bir Release’te milisaniyeler değil saniyeler — ve bağımlılık kümesinin boyutuyla büyür. Bir verify iki biçimden daha ucuz olanıdır, çünkü bir karşılaştırma, yazan bir çalıştırmanın gerçekleştirdiği bileşen başına kaynak inişini atlar. İstemciniz çağrı başına bir zaman aşımı uyguluyorsa, onu karşılaştırmanız gereken araç budur. Aşağıda anlatıldığı gibi nasıl gittiğinin size bildirilmesini istemek, çağrı bitene kadar hiçbir şey gelmemesi yerine çağrı çalışırken bir şeylerin gelmesi anlamına gelir — bu, istemcinizdeki ya da sizinle HTTP üzerinden erişilen bir sunucu arasında duran herhangi bir şeydeki boşta kalma zaman aşımını karşılar, ancak tek bir çağrının toplamda ne kadar sürebileceğine dair bir üst sınırı karşılamaz.
entity.lock dosyası, okuduğu bir girdi için hiçbir pin kaydetmeyen bir varlık pull işlemini reddeder ve ret, bu pini kaydeden adımı adlandırır. Release’in sizin katalog dizinlerinizden derlediği, tam olarak yazılmış uzak bir kaynağı okuyan ya da artifacts aracılığıyla bir dosya içe aktaran bir Recipe veya FeatureRecipe’in bu pinleri zaten yanında taşıması beklenir; yazarı bunları aşağıdaki pin ile kaydeder. pin_sources, bu çağrıdan reddetmek yerine bu adımı yazar adına her böyle varlık üzerinde çalıştırmasını ve her birinin yanına entity.lock yazmasını ister; bu, pin aracının çalıştırdığı adımın aynısıdır ve aynı baytları yazar. Gönderilmezse çalışma alanının pin_sources_at_pull ayarı karar verir; gönderilirse her iki yönde de o karar verir, dolayısıyla pin_sources: false, pinlemeye yapılandırılmış bir çalışma alanında bile reddeder. Çözümlemenin katalog dizinlerinizden birinde değil de önbellekte ulaştığı bir varlığın burada yazılabilir bir yeri yoktur ve bu çağrı tarafından asla pinlenmez.
Bir varlığın kendi girdilerini pinleme
pin, bir Recipe veya FeatureRecipe’in yanındaki entity.lock dosyasına, varlığın kendi belgesinin dışından okuduğu her girdinin içerik pinini kaydeder: koordinatları tam olarak yazılmış uzak bir kaynak ve bir artifacts girdisinin içe aktardığı dosya. Bu, aggrega pin komutunun bir terminalde çalıştırdığı adımın aynısıdır ve yazdığı kilit, o komutun yazdığıyla bayt bayt aynıdır. entity olarak varlık belgesini, buradaki diğer her yol argümanının taşıdığı sözleşmeyle mutlak ya da çalışma alanı köküne göreli olarak verin; HTTPS üzerinden bu yol, sürecin hizmet verdiği çalışma alanının içinde çözümlenmelidir.
Hiçbir Release adlandırılmaz, çünkü gerek yoktur. Koordinatları şablon içermeyen bir kaynak, varlığı kullanan her Release için tek bir artifact’i adlandırır; bu nedenle adım onu bir Release’in sağladığı hiçbir şeye ihtiyaç duymadan çözümler ve pinler. Koordinatları bir şablondan gelen bir kaynak burada pinlenmez: hangi artifact’i adlandırdığına her Release karar verir ve pull, çözümlediği her kimliği o Release’in lockfile’ına pinler.
Sonuç, adımın kilide ne yaptığını söyler. Sonuç entity’yi, onun kind ve name değerlerini ve bir kilidin kaydettiği hiçbir şeyi okumayan bir tür (bir Component veya bir Feature) için false olan pinnable’ı taşır; bu durumda varlığın yanındaki hiçbir şeye dokunulmamıştır ve diğer alanlar yoktur. Aksi halde yazdığı lock’u; kilit her pini zaten kaydetmişse ve bayt bayt aynı bırakılmışsa false olan changed’i; varlık artık bir kilidin kaydettiği hiçbir şeyi okumuyorsa ve kilidi silinmişse removed’ı; ve pin sınıfı başına bir giriş olmak üzere kilidin sonrasında tuttuğu sayıyla pins’i taşır. dry_run, adımın yazacağı kilidi content olarak döndürür ve varlığın yanına hiçbir şey yazmaz; içerik önbelleği yine dolar, çünkü girdiler başka türlü nasıl çözümlenecekse tam öyle çözümlenir.
Çalışma alanının içine yazar ve varlığın kaynaklarının adlandırdığı ana makinelere ulaşır (bir chart deposu, bir Git ana makinesi, bir URL); bu nedenle HTTP üzerinden pull’a izin veren kapsamı taşıyan bir kimlik bilgisine izin verilir, yalnızca okuyabilen bir kimlik bilgisine ise reddedilir. Standart girdi ve çıktı üzerinde aynı yetenek, komutu çalıştıran cli-pin olarak da erişilebilirdir; HTTP üzerinden bu araç yoktur.
Uzun bir çağrının nasıl ilerlediğinden haberdar olma
Bir çağrı, haberdar edilmeyi istediğinizde ilerlemesini bildirir ve bunu istemek tek bir alandır. Çağrının _meta alanına progressToken koyun; bu, seçimi size ait bir dize veya sayıdır. Her bildirimde tam olarak yazdığınız gibi geri gelir ve bir bildirimde çağrınıza geri işaret eden tek şeydir: bir bildirim hiçbir şeye yanıt vermez, bu yüzden id taşımaz. Token göndermezseniz ya da null olarak gönderirseniz hiçbir şey değişmez; çağrı, token olmadan nasıl yanıtlanıyorsa öyle yanıtlanır. Başka herhangi bir biçimdeki token reddedilir; bu, çağrı herhangi bir şey yapmadan önce, göz ardı edilmek yerine alabileceği iki biçimi adlandırarak yapılır: haberdar edilmeyi isteyip ardından sessizlikle karşılaşan bir çağıranın üzerine harekete geçebileceği hiçbir şey yoktur.
Gelen şey, token’ınızı ve her birinde artan bir sayacı taşıyan notifications/progress’tir. Toplam ve mesaj yoktur ve ikisi de üzerinde çalışılmayı bekleyen bir eksiklik değildir: işin bildirdiği şey başka bir aşamaya girdiğidir, dolayısıyla bir toplam ancak uydurulabilir ve bir cümle aktarılmak yerine ancak burada oluşturulabilirdi. Artan sayaçtan belirsiz bir gösterge çizin; bir çubuğu dolduracak bir oran yoktur.
HTTP üzerinden yanıt bir olay akışına dönüşür ve bu yalnızca bir şey gerçekten bildirildiğinde olur. text/event-stream olarak sunulur, önbelleğe alınmaması işaretlenir ve aksi halde iş bitene kadar her olayı tutup akışı yavaş tek bir yanıta dönüştürecek bir aracı için X-Accel-Buffering: no taşır. Her bildirim bir olaydır ve çağrının kendi yanıtı, akış kapanmadan önceki son olaydır. İş sessizken akış aralıklarla bir yorum satırı taşır; bu satır aradaki her şeye canlı bir bağlantıdaki baytlar olarak ulaşır, istemcinize ise hiçbir şey olarak ulaşır. İlerleme isteyen ve hiçbir şey bildirmeyen bir işe ulaşan bir çağrı yine tek bir JSON nesnesiyle yanıtlanır, çünkü akışı açan şey token değil ilk bildirimdir.
Bir akışta sonucu durum kodundan değil o son olaydan okuyun. Durum ve başlıklar akış açıldığında, yani iş bitmeden önce yazılır; bu yüzden bildirimde bulunup ardından reddeden bir çağrı, reddini zaten gönderilmiş durum altında son olay olarak taşır. Bağlantıyı akışın ortasında kapatmak işi sonlandırır ve onun için başka hiçbir şey yazılmaz; bu, Bir çağrı nasıl sona erer bölümünün diğer her çağrı için anlattığıyla tamamen aynıdır.
Standart girdi ve çıktı üzerinde bildirimler, yanıt satırından önce gelen satırlardır; o akıştaki diğer her mesaj nasıl çerçeveleniyorsa öyle çerçevelenir (satır başına bir JSON nesnesi, yazıldıkları sırayla) ve yanıt satırı onları izler. Hiçbir aktarımda, bir çağrı bittikten sonra hiçbir şey bildirilmez.
Burada bildirimde bulunan şey, bir Release’in bağımlılıklarının çözümlenmesidir. pull, çözümleme her aşamaya girdiğinde bildirir. build yalnızca önce çözümleme yapıyorsa bildirir (auto_pull gönderdiğiniz için ya da çalışma alanının kendi ayarı içindeki her build’in çözümleme yapmasını istediği için), çünkü bildirim o adıma aittir: zaten tuttuğu pinlerden render eden bir build hiçbir şeye ulaşmaz ve hiçbir şey bildirmez, dolayısıyla o çağrıdaki bir token, çağrının nasıl yanıtlandığı konusunda hiçbir şeyi değiştirmez. Her çağrı ayrıca işinin girdiği ve beklediği her adımı da bildirir — bir kayıt defterini okumak, bir yapıtı ya da bir belge paketini getirmek, bir plugin’i ilk kez derlemek —, yani komut satırının bir kişiye döner göstergesinin yanında gösterdiği adımları. İşi bunların hiçbirini beklemeyen bir çağrı hiçbir şey bildirmez; bu bir hata değil zararsız bir durumdur: yanıt, token olmadan alacağınız yanıtın aynısıdır.
Bir belgedeki bir konumda hangi bağlantının yazılı olduğunu sormak
connection-at-position, yukarıdaki iki aracın bağlantı yarısından önce gelen soruyu yanıtlar; elinizde bir grafikteki düğüm yerine bir belgedeki konum olduğunda kullanılır — bir Aggregate’te ya da bir Release’te baktığınız bir satır gibi. file olarak belgeyi, çalışma alanı köküne göre göreli ya da mutlak biçimde verin; belge, insertion-point aracının okuduğu şekilde diskten okunur. position olarak, ikisi de sıfırdan sayılan bir line ve bir character verin; bunlar, insertion-point aracının bu argümanı okuduğu şekilde, tam olarak position_encoding değerinin adlandırdığı birimlerle ölçülür. Son olarak, derlenmiş grafiği bağlantıları kaydeden release değerini verin. Aggregate içindeki bir konum için de Release gereklidir: bir grafik düğümü ve bir bağlantı yalnızca derlenmiş bir grafikte var olur.
Yanıt iki yarıdan biridir. Konum bir bağlantının girdisi üzerindeyse yanıt graphNode ve connection değerlerini taşır — bağlantının socket, alias değerleri ve konumun okunduğu document ile birlikte. Bunlar tam olarak attach-candidates aracının graph_node ve release yanında aldığı değerlerdir; ayrıca attachment-container aracının, o bağlantı üzerindeki bir eklentinin nereye gideceğini adlandırmak için aldığı değerlerdir. Bu kapsayıcı, konumun düştüğü girdinin tam içinde yer alır. Aksi hâlde yanıt, kapalı bir kümeden gelen noConnectionReason değerini taşır: no-connection-entry (konum, içine eklenti yazılan hiçbir girdi üzerinde değildir), feature-created-connection (konum, Release’in bir Feature’ın çizdiği bir bağlantı için yazdığı girdi üzerindedir) ya da unknown-connection (konum, Release’in derlenmiş grafiğin taşımadığı bir bağlantı için yazdığı bir girdi üzerindedir). Okunabilir yanıt nedeni sözcüklerle belirtir.
Bir girdinin herhangi bir yerindeki konum o girdinin içindedir — takma adın üzerinde, target değerinin üzerinde, features içinde — ve girdiler iç içe geçtiğinde en içteki girdi geçerli olur. Bir soketin kendi anahtarı üzerindeki, altındaki takma adların üstünde kalan bir konum bunların hiçbirinin içinde değildir. Girdiler, derlenmiş grafiğin kaydettikleridir: Aggregate’te, bir bileşenin çizdiği her bağlantı, bileşenin yazıldığı belgede bağlantının takma adı altındaki girdisinde yer alır; içe aktarılan bir modülün katkıda bulunduğu bir bileşen için bu belge o modülün kendi belgesidir. Release’te ise yazdığı her kenar başına girdidir. Hedef listesi olarak yazılmış bir bağlantı ve bir Feature’ın kendi bağımlılık bloğunun çizdiği bir bağlantı, içine eklenti yazılan bir girdi taşımaz. Bir anahtarın bağlantı olup olmadığı asla adından çıkarılmaz.
Yanıt verir ve durur. Hiçbir dosyaya bir şey yazmaz. Çalışma alanında olmayan, okunamayan ya da iyi biçimlendirilmiş YAML olmayan bir belge, insertion-point aracında olduğu gibi, neyin değiştirilmesi gerektiğini adlandıran başarısız bir sonuç olarak döner; line ya da character değeri eksik bir konum ve üç değerin dışındaki bir position_encoding de öyle.
Bir eklentinin hangi kapsayıcıya ait olduğunu sormak
attachment-container, bir adaylık yanıtı ile bir ekleme noktası arasındaki soruyu yanıtlar. Bir düğüme neyin ekleneceğine karar verdiniz; bunu bir dosyanın neresine yazacağınızı sormadan önce hangi dosyayı ve onun içindeki hangi kapsayıcıyı kullanacağınızı bilmeniz gerekir. graph_node — derlenmiş bir graf üzerindeki, grafın anahtarladığı biçimdeki bir düğüm kimliği — ve grafı ona ait olan release değerini verin. İkisi de zorunludur: bir düğüm kimliği tek bir Release’in grafının anahtarıdır ve o olmadan hiçbir anlam taşımaz.
Bu yolu kendiniz oluşturmayın. Bir düğümün kimliği de onu kapsayan alt sistem yolu da parçaları arasında noktalarla yazılır ve nokta, bir yazarın yazdığı bir adda geçerli bir karakterdir — dolayısıyla belgenin dışından yapısal bir noktayı bir adın içindeki noktadan ayırt etmenin yolu yoktur. Sizin oluşturduğunuz bir yol doğru okunur ve kimsenin yazmadığı bir anahtarı adresler; ardından gelen düzenleme de reddedilmek yerine o anahtarı oluşturur. Daha kötüsü, bir düğüm kimliği kapsayan alt sisteminin hiçbir izini taşımaz: subsystems.billing.subsystems.payments içinde yazılmış bir component, tıpkı üst düzey bir component gibi ledger olarak anahtarlanır. Kapsayıcıyı sorun.
Yanıt şunları taşır: node, yanıtın ilgili olduğu düğüm; file, o düğümün yazıldığı belge; ve container, o belgenin kökünden itibaren yapısal yol, bir parça listesi olarak — ["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. Birleştirilmiş bir dize yerine bir liste olması bilinçlidir: birleştirilmiş bir yolun, onu alan kişi tarafından yeniden bölünmesi gerekirdi; bu da yukarıdaki belirsizliğin bir çağrı sonra yeniden ortaya çıkması demektir. file ve container değerlerini insertion-point’e değiştirmeden verin.
file, zaten bildiğiniz bir şey değil, yanıtın bir parçasıdır. İçe aktarılan bir modülün katkıda bulunduğu bir düğüm, o modülün kendi belgesinde, modülün ona verdiği adla yazılmıştır; bu nedenle hem dosya hem de kapsayıcının son parçası gönderdiğiniz her şeyden farklıdır.
Düğümün çizdiği tek bir bağlantı üzerindeki bir ek için connection ekleyin; bunu socket, alias ve document değerleriyle birlikte verin. Belgenin belirtilmesi burada zorunludur, çünkü bağlantı her iki belgede de bulunabilir. aggregate ile yanıt, bağlantının düğümün yazıldığı belgedeki kendi girdisidir ve sonunda features bloğu yer alır; Release’in çizdiği bir bağlantının orada girdisi yoktur ve reddedilir. release ile yanıt, Release’in düğüm için yazdığı girdinin altındaki kenar başına girdidir (["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"]). Bu girdi, Release o kenar başına girdiyi henüz yazmış olsun ya da olmasın bildirilir; böylece insertion-point hâlâ yazılması gereken anahtarları belirtir. Düğüm için hiçbir girdi yazmayan bir Release reddedilir, çünkü düğümün nereye yerleştirileceğine bu araç karar vermez. Bir Feature’ın çizdiği bağlantı her iki belgede de reddedilir.
Yanıtlar ve durur. Hiçbir eklenti oluşturmaz, hiçbir dosyaya bir şey yazmaz ve hiçbir metin oluşturmaz. Neyin eklenebileceğine de karar vermez — bu attach-candidates’in işidir. Grafın taşımadığı bir düğüm ya da grafın hiçbir belge kaydetmediği bir düğüm, boş bir alan içeren bir yanıt olarak değil, neyin değiştirileceğini belirten başarısız bir sonuç olarak döner.
Bir girdinin belgede nereye ait olduğunu bulma
insertion-point, bir adaylık yanıtının ardından gelen soruyu yanıtlar. Neyi ekleyeceğinize veya bağlayacağınıza karar verdiniz; şimdi bunu dosyanın neresine yazacağınızı bilmeniz gerekir. Araç bir konum ve girinti sütunlarını döndürür; böylece belgeyi kendiniz ayrıştırmadan düzenlemeyi uygulayabilirsiniz. Okuduğu şey herhangi bir türün biçimi değil belgenin kendi yapısı olduğundan, describe-capabilities onu hangi varlık türüne daraltırsanız daraltın o türün altında listeler.
file — çalışma alanı köküne göreli ya da mutlak, ve çalışma alanının içinde olan belge: dışarıya çıkan bir bağlantı üzerinden, dosyaya ya da yoldaki bir dizine ulaşılan belge içeride sayılmaz ve her iki aktarımda da reddedilir — ve container, belge kökünden girdinin içine gireceği kapsayıcıya giden yapısal yol; her öğe bir eşleme anahtarı ya da ondalık olarak yazılmış bir dizi konumudur.
Kapsayıcı yolunu sağlamak size düşer. Araç belgenin yapısını okur ve bir şeyin nereye ait olduğunu asla adından, taşıdığı türden ya da ne anlama geliyor göründüğünden çıkarmaz. Hangi anahtar olduğunu siz söylersiniz; araç o anahtarın girdilerinin bu belgede nereye gittiğini söyler — yolun hangi kısımlarını dosyanın zaten taşıdığını, girdilerinin hangi sütunlarda durduğunu ve en içteki bloğun ulaştığı son satırı. Derlenmiş bir grafiğin bir düğümüne Feature eklemek için o anahtarı kendiniz bilmeniz gerekmez: yukarıdaki attachment-container belgeyi ve kapsayıcıyı bildirir ve ikisi de buraya değiştirilmeden verilir.
Yanıt, line ve character değerlerinin ikisi de sıfırdan sayılan sıfır genişlikli bir position; yazılacak sütunlar olan entryIndent ve indentStep; ve bu belgenin henüz taşımadığı, en dıştakinden başlayarak sıralanan ve girdiden önce yazdığınız kapsayıcı anahtarları olan missingContainerKeys içerir. entryShape, kapsayıcının bir mapping mi yoksa bir sequence mi tuttuğunu bildirir; kapsayıcı henüz yoksa ya da boşsa, belge bunu söylemediği için unknown bildirir — bu durumda biçimi seçmek size kalır. indentStepMeasured, adımın bu belgenin kendi iç içe yapısından mı ölçüldüğünü yoksa hiç iç içe yapı göstermeyen bir belge için bir geri dönüş değeri mi olduğunu söyler. precededByLineBreak ayarlıysa metninize bir satır sonuyla başlayın: konum, girdinin ardından geldiği satırın sonunda durur; bu, dosya bir yeni satırla bitsin ya da bitmesin aralık içindedir ve zaten yazılmış hiçbir baytı bozmaz. Kapsayıcının orada olmasını beklediğiniz durumlarda bile missingContainerKeys değerini okuyun — kendisinden önce gelmesi gereken anahtarlar olmadan uygulanan bir konum, artık ayrıştırılamayan bir belge üretir.
position_encoding, bildirilen karakter ofsetinin ölçüldüğü birimleri adlandırır: utf-8, utf-16 ya da utf-32. Burada bir argümandır, çünkü bu protokolün iki sürümünden hiçbiri bunu müzakere etmez; varsayılanı utf-16’dır, bu da bir istemci hiçbir şey müzakere etmediğinde bir editör oturumunun aldığı değerdir — böylece hiçbir şey belirtmeyen bir çağırana her iki yüzeyde de aynı yanıt verilir. Bu üçünden hiçbiri olmayan bir değer sessizce varsayılana çekilmek yerine reddedilir, çünkü bir şekilde ölçülüp başka şekilde ölçülen bir arabelleğe uygulanan ofsetler, belgeyi ASCII dışındaki ilk karakterde bozar.
Yanıtlar ve durur. Hiçbir dosyaya bir şey yazmaz, girdi metni oluşturmaz ve düzenleme uygulamaz; metni oluşturmak ve uygulayıp uygulamamaya karar vermek size kalır. Bir girdinin gidebileceği bir yeri göstermeyen bir istek, neyin değiştirileceğini belirten başarısız bir sonuç olarak döner — çalışma alanında olmayan, okunamayan ya da iyi biçimli YAML olmayan bir belge; hiç kısım taşımayan ya da boş bir kısım taşıyan bir kapsayıcı yolu; içine hiçbir şey eklenemeyen bir skalerden geçen bir yol; ekleme yapmanın bir satır eklemek yerine yazarın zaten yazdığı baytları yeniden yazacağı, akış stilinde yazılmış bir koleksiyona ulaşan bir yol; ya da bir blok dizisini dizinlerinden biri olmayan bir şeyle gösteren bir yol. Düzenlemeyi kendiniz uygulamak yerine uygulanmasını tercih ediyorsanız, bunu yapan araç Bir belgeye sınırlı tek bir düzenleme uygulama aracıdır.
Bir belgeye tek bir sınırlı düzenleme uygulamak
edit-document, yukarıdaki iki aracın konumunu belirlediğini uygular. Tek bir çağrı, tek bir kapsayıcının altına tek bir girdi ekler ya da tek bir skaler değer ayarlar; başka hiçbir şey yapamaz. Adını verdiğiniz belgeyi, çalışma alanının içinde yazar; bu nedenle HTTPS üzerinden aggrega:workspace-write gerektirir: yalnızca aggrega:read sahibi bir çağıran aracı araç listesinde bulur, ancak yaptığı bir çağrı bu kapsamın adı verilerek reddedilir.
Düzenlemeyi edit içinde adlandırın; küme kapalıdır. add-component, bir components kapsayıcısının altına bir bileşen örneği ekler; attach-feature, adını verdiğiniz düğüme bir Feature bağlar; wire-edge, o düğümün soketlerinden birinin içinde bir bağlantı kurar; set-value, o düğümde tek bir değer ayarlar. Bu dördünün dışındaki bir ad yorumlanmak yerine reddedilir. Silen, önceden yazdığınız bir bloğu değiştiren, herhangi bir şeyi yeniden sıralayan ya da sağladığınız baytları olduğu gibi yazan bir düzenleme yoktur; dolayısıyla bu bir dosya yazıcısı değildir ve öyle kullanılamaz.
file olarak belgeyi verin; çalışma alanı köküne göreli ya da mutlak olabilir ve çalışma alanının içinde olmalıdır: yazıldığı hâliyle ya da dışarıya çıkan bir bağlantı üzerinden onun dışında kalan bir belge, iki aktarımda da hiçbir şey okunmadan veya yazılmadan reddedilir. node olarak belge kökünden itibaren yapısal yolu bir segment listesi biçiminde; name olarak girdinin altına yazılacağı anahtarı; value olarak da o girdinin taşıdığı şeyi verin. node, attachment-container’ın tek bir yanıtta yanıtladığı nedenle bir listedir: bir yazarın yazdığı adın içinde nokta geçerlidir; bu yüzden birleştirilmiş bir yol, kimsenin yazmadığı bir anahtarı adresleyebilir ve girdi reddedilmek yerine orada oluşturulurdu. add-component için yol, components kapsayıcısının kendisini adlandırır, çünkü eklenen girdi düğümün kendisidir; diğer üçü için düzenlemenin ilgili olduğu düğümü adlandırır ve kapsayıcı düzenlemeden çıkar. socket, wire-edge için okunur, diğer durumlarda yok sayılır. value’nun anlamı edit’ten çıkar: girdinin istediği varlık, bir bağlantının işaret ettiği düğüm ya da bir değerin ayarlandığı skaler. Kendi türünde bir JSON değeridir; böylece bir sayı sayı olarak kalır, tırnak içindeki bir rakam metin olarak kalır ve değerin verilmemesi hiçbir şey ayarlamaz. Bir eşleme ya da dizi reddedilir, çünkü blok yazmak bu düzenlemelerden biri değildir.
Düzenlemenin dokunmadığı her bayt korunur. Belge yalnızca kapsayıcının ve bloğunun bittiği satırın yerini bulmak için ayrıştırılır; böylece yorumlar, boş satırlar, tırnaklama stili, katlanmış ve harfî skalerler ile sondaki yeni satır biçimi olduğu gibi aktarılır, iç içelik adımı da dayatılmak yerine belgenin kendi girintisinden ölçülür. Aynı belgeye karşı yapılan aynı istek aynı baytları üretir.
Sonuç, sizin de yazabileceğiniz bir belge olmalıdır ve yazma işlemi buna bağlıdır. Oluşturulan belge kendi türünün şemasına göre denetlenir ve diske yalnızca bu denetimi geçerse ulaşır. Şemanın reddedeceği bir şey üretecek istek, şemanın kabul etmeyeceği özellik ve yeri belirtilerek reddedilir ve dosya bayt bayt önceki hâliyle bırakılır; böylece reddedilen bir düzenleme hiç denenmemiş olandan ayırt edilemez ve düzeltilmiş bir isteği başladığınız belgeye karşı yeniden deneyebilirsiniz. İstediğinizi zaten taşıyan bir girdi işlem yapılmamasıyla sonuçlanır; aynı adda başka bir şey taşıyan bir girdi ise değiştirilmek yerine reddedilir.
Yanıt şunları taşır: container, girdinin yerleştiği yapısal yol; created_containers, bu düzenlemenin oluşturmak zorunda kaldığı kapsayıcı düzeyleri, en dıştaki önce gelecek biçimde ve yolun tamamının zaten var olduğu olağan durumda boş; ve written, diske ulaşan belge, hiçbir şey ulaşmadığında boş. created_containers’ı okuyun: belgenin taşımadığı iç içe iki bloğu sessizce yazan bir düzenleme, aksi takdirde kendi yazdığınız bir bloğa tek bir girdi ekleyen düzenlemeden ayırt edilemez.
dry_run, yazma dışında her şeyi yapar. Düzenlenen belge content olarak geri döner, hiçbir şey oluşturulmaz ve written boştur; bu, sonucu kaydedilmeden önce yazarın önüne koyan bir istemci içindir. Şema denetimi de dahil olmak üzere diğer tüm davranışlar yazma işlemininkiyle aynıdır; dolayısıyla yazmanın reddedeceği bir istek bu kipte de reddedilir. Bu seçenek olmadan belge yazılır ve content bulunmaz, çünkü belge artık diskte olur ve written onu adlandırır.
Bağladığınız şeyin anlamsal olarak kabul edilebilir olup olmadığı, yani bir soketin üreticinin bildirdiği bir soket olup olmadığı ya da bir Feature’ın uygulanabilirliğinin karşılanıp karşılanmadığı burada belirlenmez. Bunu validate yanıtlar.
Standart girdi ve çıktı üzerinde aynı yeteneğe cli-edit-document olarak da erişilebilir; bu araç komutu çalıştırır ve yazdırdığı metni geri verir. HTTP üzerinden bu araç yoktur ve orada yeteneğe bu araçla erişilir.
Yabancı bir tanımı taslak varlıklara dönüştürme
import, başka bir aracın ürettiği bir tanımı (örneğin bir ajan oluşturucudan dışa aktarılmış bir akışı) taslak Aggrega yazım dosyalarına dönüştürür. Bu dosyaları bu sunucunun hizmet verdiği çalışma alanına yazar; bu nedenle HTTPS üzerinden aggrega:workspace-write gerektirir: yalnızca aggrega:read yetkisine sahip bir çağıran onu araç listesinde bulur, ancak yaptığı bir çağrı bu kapsamı belirtilerek reddedilir.
Dönüştürülecek dosyayı veya dizini source olarak iletin. Bu değer mutlaktır ya da çalışma alanı köküne görelidir; bu yüzeydeki diğer tüm yol bağımsız değişkenlerinin kullandığı sözleşmenin aynısıdır. HTTPS üzerinden erişilen bir sunucuda ise o sunucunun hizmet verdiği çalışma alanının içinde çözümlenir.
Bir dizin, tam olarak içe aktarıcısının dosya desenlerinin seçtiği dosyalar olarak okunur. Bir chart veya bir proje bir dizindir ve source bir dizini adlandırabilir. Bu durumda içe aktarıcıya, dizinin herhangi bir derinlikteki dosyalarından imzalarının bildirdiği dosya desenlerinden birinin seçtikleri verilir. Her dosya, dizin içindeki yoluyla, eğik çizgilerle yazılmış biçimde ve sıralı olarak adlandırılır. Bunlarla birlikte plugins.importer eklentisinin with.sources altında adlandırdığı dosyalar da temel adlarıyla verilir. Aynı ada sahip bir dizin dosyası ile bir with.sources dosyası, birinin diğerini gizlemesine izin verilmeden reddedilir. Hiçbir dosya deseni bildirmeyen bir içe aktarıcı tek bir dosya okur ve bir dizini An importer that declares no file patterns is handed a directory (Hiçbir dosya deseni bildirmeyen bir içe aktarıcıya bir dizin verildi) koşulu altında reddeder. Desenlerinin seçtiği hiçbir dosyayı içermeyen bir dizin de reddedilir. Dizin, nerede bulunursa bulunsun kendi sınırları içinde tutulur: içe aktarmanın okuyacağı dosyalar arasında veya bir dizine giden ve dizinin dışına çıkan bir bağlantı, herhangi bir şey okunmadan önce reddedilir ve bir dizine giden bağlantıya hiçbir zaman girilmez; bu, A directory you import bölümünde açıklanmıştır. HTTPS üzerinden erişilen bir sunucuda dizinin kendisi çalışma alanının içinde çözümlenir, dolayısıyla ondan okunan her dosya da öyle çözümlenir.
İçe aktarıcı, çalışma alanınızın kataloğunun tuttuğu bir içe aktarıcı ya da derleyicinin çekirdek içe aktarıcılarından biridir. Çeviri, kaynağın biçimini duyuran içe aktarıcı eklentinin işidir: bu, çalışma alanınızın kataloğunun tuttuğu bir eklenti ya da derleyicinin, hiçbir katalog girdisi olmadan her çalışma alanında kendi biçimlerine hizmet eden çekirdek içe aktarıcılarından biridir. Bu araç onu seçer, çalıştırır ve ürettiğini yazar. uri değeri bir içe aktarıcıyı kimliği ve sürümüyle (aggrega plugin add importer komutunun yazdığı biçimde importer/<name>:<version>) adlandıran bir plugins.importer eklentisi o içe aktarıcıyı bağlar: kaynağın biçimini duyurduğu durumda, biçimi başka hangi içe aktarıcı duyurursa duyursun çalışan odur, o sürümle çalışır ve ona, başka hiçbir içe aktarıcıya verilmeyen, o eklentinin with kaynakları ve ayarları verilir. Birden fazla içe aktarıcının biçimi duyurduğu ve bunlardan hiçbirinin tek başına bağlanmadığı durumda (aralarında bir çekirdek içe aktarıcı ile kataloğunuzun aynı biçim için tuttuğu başka adlı bir içe aktarıcı olsa bile), çağrı bunlar adlandırılarak reddedilir; bu, Configuration bölümünde açıklanmıştır. Hiçbir içe aktarıcının duyurmadığı, sizin adlandırdığınız bir biçim, sonradan yorumlamanız gereken genel bir bulunamama yerine, bir içe aktarıcının duyurması gereken yetenek (bir Langflow kaynağı için import:langflow) adlandırılarak reddedilir; kataloğa eklediğiniz bir içe aktarıcının bildirdiği de budur.
Sunucunun makinesinde bulunmayan bir çekirdek içe aktarıcı, ona ihtiyaç duyan ilk içe aktarma tarafından bir kez getirilir. İçe aktarma onu sunulan çalışma alanının varsayılan kayıt defterinden getirir, derleyicinin sürümünün yayımladığı modüle karşı denetler, bir pull işleminin getirdiği bir eklentiyi doğruladığı gibi imzasını o kayıt defterinin güven politikasına ve kullandığı ana makine işlevlerine göre doğrular ve onu çalışma alanının içerik önbelleğinde tutar; böylece sonraki her içe aktarma onu oradan okur ve hiçbir kayıt defterine ulaşmaz. Onun için başka hiçbir şey yazılmaz: ne bir kilit dosyası ne de güvenilen eklentilerin bir kaydı. HTTPS üzerinden bu, bu araca yapılan bir çağrının sunucuya başvurtabileceği tek kayıt defteridir ve Bir çağrı hangi kimlik bilgilerini harcar bölümünün bir kayıt defteri okuması için koyduğu sınıra tabidir: kayıt defteri bu sunucunun sunduğu çalışma alanının varsayılan kayıt defteridir, dolayısıyla o çalışma alanının yapılandırıldığı bir kayıt defteridir; çağrıdaki hiçbir şey bir kayıt defteri adlandırmaz ya da bir kimlik bilgisi taşımaz; ve getirme işlemi bu ana makinenin kendi oturumunu ve güven politikasını harcar. Araç yine de çalışma alanına ulaşır ve daha ötesine ulaşmaz, bu yüzden bir çağrının ihtiyaç duyduğu tek şey aggrega:workspace-write’tır: getirmenin geride bıraktığı şey, çalışma alanının kendi içerik önbelleğindeki bir modüldür. Doğrulanmayan bir modül, bir terminalde olduğu gibi reddedilir ve hiçbir şey tutulmaz. Modül getirilemediğinde (çalışma alanı çevrimdışıysa, kayıt defterine ulaşılamıyorsa ya da kayıt defteri onu barındırmıyorsa) çağrı, içe aktarıcıyı, sürümünü ve modülünü makineye neyin koyacağını adlandırarak A plugin’s .wasm is not on this machine (Bir eklentinin .wasm dosyası bu makinede değil) koşulu altında reddedilir.
Çalışma alanı hiçbir katalog klasörü belirtmediğinde, içe aktarma varsayılan kayıt defterinin yayımladığı kataloğu okur. workspace.catalog_dirs, AGGREGA_CATALOG_DIRS ve kök dizini hiçbir katalog klasörü belirtmeyen bir çalışma alanı, standart kütüphane kataloğunu, hizmet verilen çalışma alanının varsayılan kayıt defterinde catalog/snapshot konumundaki tek bir imzalı anlık görüntü olarak okur; bu, bir çekirdek içe aktarıcının getirildiği kayıt defterinin aynısıdır, aynı koşullarla erişilir ve çağrıdaki hiçbir şey bir kayıt defteri belirtmez ya da kimlik bilgisi taşımaz. Bir anlık görüntü bir kez getirilir: imzası o kayıt defterinin güven ilkesine göre doğrulanır, çalışma alanının içerik önbelleğinde tutulur ve orada özetine bağlı olarak bir katalog klasörü gibi okunur; hiçbir kayıt defterinden yeniden istenmez. Bir çağrının hangi anlık görüntüyü okuduğu: upgrade ile en yenisi; aksi takdirde çıktı dizinindeki kaydın adlandırdığı, makinede yoksa özetiyle getirilen anlık görüntü; aksi takdirde çalışma alanının en son en yeni olarak getirdiği; aksi takdirde en yenisi. İçe aktarmanın yazdığı kayıt, okuduğu anlık görüntüyü özetiyle adlandırır; böylece aynı dizine taslak çıkaran sonraki bir çağrı aynı kataloğu okur. Çevrimdışıyken bir anlık görüntü getirmesi gereken çağrı, neyin çalıştırılacağını belirterek reddedilir ve makinede ne olursa olsun upgrade reddedilir, çünkü hangi anlık görüntünün en yeni olduğunu yalnızca kayıt defteri söyleyebilir. Hiçbir anlık görüntü yayımlamayan bir kayıt defteri içe aktarmayı katalogsuz bırakır ve diagnostics içindeki bir warn girdisi bunu bildirir. Bir katalog klasörü belirten çalışma alanı ona göre içe aktarır ve hiçbir anlık görüntü getirmez; orada upgrade hiçbir şeyi değiştirmez.
format değerini vermezseniz biçim, içe aktarıcıların bildirdiği imzalarla tanınır; bu, hem kataloğunuzun hem de çekirdek içe aktarıcıların imzaları için geçerlidir. Her içe aktarıcının Plugin varlığı bunları kaydeder: bir kaynağın okunduğu sözdizimi, bir imzanın uygulandığı dosya adları ve ayrıştırılmış ağacın taşıması veya taşımaması gereken yollar. Kaynak, adına uygulanan bir imzanın onu okuduğu her sözdizimi için bir kez, çalışma alanınızın kataloğunun o sözdizimi için sunduğu ayrıştırıcıyla (veya kataloğunuzun ayrıştırıcı sunmadığı bir sözdizimi için derleyicinin kendisinin taşıdığı ayrıştırıcıyla) ayrıştırılır ve imzası eşleşen tek içe aktarıcının biçimi kullanılır. İçe aktarıcı daha sonra kaynağı aynı ayrıştırıcıyla okur. Çekirdek içe aktarıcıların imzaları bir dosyayı JSON veya YAML olarak okur; hiçbir dosya adlandırmayanlar onu JSON olarak okur (Dify içe aktarıcısınınki ise YAML olarak). Bu nedenle tek başına içe aktarılan bir dosyanın tanınması onu her ikisinde de okur ve çalışma alanınızın kataloğunda bir ayrıştırıcı gerektirmez: derleyici bir JSON ve bir YAML ayrıştırıcısı taşır, kataloğunuzun sunduğu bir ayrıştırıcı ise onun yerine kullanılır. Bir dizin de dosyaları üzerinden aynı şekilde tanınır: her imza, dizinin desenlerinin seçtiği dosyalarına karşı denenir ve hiçbir desen bildirmeyen bir imza bunların hiçbirine uygulanmaz. Tanıma, adlandırdığınız dosyayı (veya bir dizin için yalnızca bir imzanın desenlerinin seçtiği dosyaları) okur ve ağa erişmez. Hiçbir imzanın eşleşmediği bir kaynak, format istenerek ve içe aktarıcıların duyurduğu biçimler adlandırılarak (bir dizin için ise dosyalarından birinin tek başına source olarak gönderilmesi ya da içe aktarıcısı dosya desenleri bildiren bir format istenerek ve yalnızca bu biçimler adlandırılarak) No importer recognises the source (Hiçbir içe aktarıcı kaynağı tanımıyor) koşulu altında reddedilir; birden fazla biçimin imzalarının eşleştiği bir kaynak ise bu biçimler adlandırılarak More than one importer recognises the source (Birden fazla içe aktarıcı kaynağı tanıyor) koşulu altında reddedilir; ikisi de tahmin edilen bir içe aktarıcıya verilmez. Her iki durumda da biçimi doğrudan adlandırmak için format gönderin; bir dizin için bu, içe aktarıcısı dosya desenleri bildiren bir biçimdir, çünkü bir dizin yalnızca bu desenler aracılığıyla okunur. Boş bir format, onu hiç vermemişsiniz gibi okunmak yerine reddedilir, çünkü bunlar farklı isteklerdir.
Taslağı çıkarılan Release’in bir sağlayıcı için derlendiği Manifest’in taslağını çıkarmak için target gönderin. target bir sağlayıcı yeteneğidir (bir Recipe’in spec.capability alanının bağlandığı sözcük, örneğin compose veya helm) ve aggrega import komutunun --target seçeneğidir; aynı işlemle oluşturulur, dolayısıyla bir çağrı ile komut aynı kaynaktan aynı dosyaların taslağını çıkarır. Taslakların ihtiyaç duyduğu her bileşen türü ve her özellik türü için (taslağı çıkarılan Aggregate’in bileşenlerinde, bunların bağlantılarında ve alt sistemlerinde, oluşturduğu katalog Aggregates’inde ve taslağı çıkarılan Release’in eklerinde), taslakların onu ilk bildirdiği sırayla, içe aktarma çalışma alanının kataloğunda bu türü uygulayan ve o yeteneğe bağlanan Recipes’i, bir özellik türü için ise özellik tariflerini arar. Tam olarak bir tane olduğunda (bunlardan birinin birden fazla sürümü bir tane sayılır) Manifest türü, sürümsüz ve yetenekle nitelenmiş adıyla (örneğin compose/postgres) ona eşler; ilk çekme bunu kilit dosyasında mevcut en yüksek sürüme sabitler. Farklı adlara sahip birden fazla olduğunda, türün kendisinin adını taşıyanı eşler; örneğin core/datastore/postgres için helm/postgres. Hiç olmadığında ya da birden fazla olup hiçbiri bu şekilde adlandırılmamışsa tür eşlenmeden bırakılır ve diagnostics içindeki bir warn girdisi türü ve nedenini (birden fazla olanları tek tek adlarıyla) belirtir; böylece taslakların bir derlemesi, eşleme eklenene kadar türün her örneğini veya ekini adlandırarak No Recipe is mapped for a component or feature instance (Bir bileşen veya özellik örneği için hiçbir Recipe eşlenmemiş) altında durur. Manifest’in taslağını içe aktarıcının kendisi çıkardığında, bir örneğin işlendiği Recipe’i veya birkaç özellik tarifinden birini seçmek için, yazdığı eşlemelerden kataloğun o tür ve yetenek için sunduğu her biri korunur, diğerleri bir warn girdisiyle atılır ve bıraktığı türler yukarıdaki gibi eşlenir. Manifest, taslağı çıkarılan Release’in yanına manifest.yaml olarak, Release ile aynı ad ve sürümle çıkarılır ve Release’in spec.manifest alanı bu ada ayarlanır; içe aktarıcının onun yerine yazdığı yorum değiştirilir ve Release’te başka hiçbir şey değişmez. Zaten bir Manifest adlandıran bir Release olduğu gibi bırakılır; içe aktarma hiçbir Release taslağı çıkarmadığında ise Manifest, Aggregate’in yanına onun ad ve sürümüyle çıkarılır ve bir info girdisi ona hiçbir şeyin başvurmadığını belirtir. Manifest ve düzenlenen Release diğerleri gibi taslaktır: written içinde ve kayıtta yer alır, dry_run altında geri verilir. Katalogdaki hiçbir Recipe’in bağlanmadığı bir target, içe aktarıcı çalışmadan önce An import’s target names a capability no Recipe in the catalog binds to (Bir içe aktarmanın hedefi, katalogdaki hiçbir Recipe’in bağlanmadığı bir yeteneği adlandırıyor) altında, gönderdiğiniz biçimiyle ve katalogdaki Recipes’in bağlandığı yetenekler adlandırılarak reddedilir ve hiçbir şey yazılmaz. target değerini vermezseniz hiçbir Manifest taslağı çıkarılmaz; bunun istisnası, önceki içe aktarmanın gönderildiği hedef için taslak çıkaran sync işlemidir. Boş bir target, onu hiç vermemişsiniz gibi okunmak yerine reddedilir.
Taslakların gideceği dizini adlandırmak için output_dir gönderin. Vermezseniz taslaklar, çağrının çözümlediği çalışma alanının kökü altına yerleşir; bu, hiçbir hedef adlandırmadığınızda aggrega import komutunun, nerede çalıştırırsanız çalıştırın, onları yazdığı yer ve dil sunucusunun aggrega/import isteğinin hiçbir hedef adlandırmadığında onları yazdığı yerdir. Hedef her üçünde de isteğe bağlıdır ve bu sunucuya gönderdiğiniz her yol gibi adlandırılır. HTTP üzerinden bu, sunucunun hizmet verdiği çalışma alanının içinde, köküne göre yazılmış bir dizindir: kökün dışına tırmanan bir değer, kökün dışında mutlak bir konum ve bir bağlantı aracılığıyla kökün dışına çıkan bir dizin (böyle bir bağlantının altında henüz oluşturulmamış bir dizin de dahil) output_dir adlandırılarak reddedilir ve hiçbir şey okunmaz veya yazılmaz. Standart giriş ve çıkış üzerinden ise oradaki her yol gibi adlandırıldığı şekliyle alınır: göreli bir değer, çağrının çözümlediği çalışma alanı köküne göre çözümlenir; mutlak bir değer ise çalışma alanının dışında bir dizini adlandırabilir ve o dizine aggrega import --output-dir komutunun yaptığı gibi taslak yazılır. Oraya yazılanlar, bağlantıları çözümlenmiş olarak çalışma alanıyla (veya dışında adlandırdığınız bir dizin için o dizinle) sınırlı tutulur; dolayısıyla içinde dışarıya çıkan bir bağlantı reddedilir ve hiçbir şey yazılmaz. Boş bir output_dir, onu hiç vermemişsiniz gibi okunmak yerine reddedilir. Standart giriş ve çıkışta cli-import da komutun --output-dir seçeneğini kendi output_dir değeri olarak taşır; oradaki göreli bir değer komutun çalıştığı klasörde çözümlenir: çağrının adlandırdığı çalışma alanı kökü, yoksa sunucunun başlatıldığı kök, o da yoksa sunucunun çalıştığı klasör.
Taslağı çıkarılan her yol, herhangi bir şey yazılmadan önce çıktı dizinine karşı denetlenir. Dizinin dışına uzanan bir yol, hem yol hem de dizin adlandırılarak reddedilir ve hiçbir şey yazılmaz; aynı kümede kendi yolları sorunsuz olan dosyalar bile yazılmaz, çünkü reddedilmiş ama kendinden bir parça bırakmış bir içe aktarma kimsenin istemediği bir sonuçtur. Taslağı çıkarılan bir yol sizden değil içe aktarıcı eklentiden gelir; bu yüzden gönderdiğiniz bir yolun denetlendiği nedenle denetlenir.
Herhangi bir taslak çıkaran her içe aktarma, taslaklarının yanına .aggrega-import.json dosyasını da yazar: bu, yazdıklarının kaydıdır; gönderildiyse gönderildiği target, okuduysa okuduğu katalog anlık görüntüsü, taslağı çıkarılan her dosya ve taslağı çıkarılan bir Aggregate veya Release içinde her derinlikteki her anahtar, oraya yazılan metnin bir özetiyle birlikte kaydedilir; taslağı çıkarılan diğer dosyalar bütün olarak kaydedilir. Bir anahtarın metni; satırı, değeri bir anahtar eşlemesi değilse değerinin satırları ve doğrudan üstüne kendi girintisinde yazılmış yorum satırlarıdır. written kaydı taslaklarla birlikte adlandırır; dry_run altında ise kayıt geri verilen taslaklar arasındadır. Kayıt JSON’dur, dolayısıyla çalışma alanının YAML belgelerini okuyan hiçbir şey onu okumaz.
Bir çağrı, çıktı dizininde zaten bulunan bir Aggregate’in üzerine asla yazmaz. Aggregate, taslağı çıkarıldıktan sonra bir yazarın düzenlemeye devam ettiği belgedir; bu nedenle taslaklarından biri Aggregate olarak okunan bir dosyanın üzerine düşecek bir çağrı, taslak ve dizin adlandırılarak reddedilir ve hiçbir şey yazılmaz; bu dry_run altında da geçerlidir, çünkü bir deneme çalıştırması yazmanın reddettiğini reddeder. Taslağı çıkarılan bir yolda zaten bulunan diğer her dosyanın üzerine yazılır ve önceki bir içe aktarmanın taslağını çıkardığı ama bu içe aktarmanın çıkarmadığı bir dosya olduğu yerde bırakılır.
Önceki bir içe aktarmanın taslak olarak yazdıklarını kaynakla güncel hâle getirmek için bunun yerine sync gönderin; yalnızca içe aktarmanın yazdıkları değişir. target gönderilmemiş bir sync, kaydın adlandırdığı hedef için taslak üretir; böylece önceki içe aktarmanın taslak olarak yazdığı Manifest’i üretir. target gönderilmiş bir sync ise o hedef için taslak üretir ve kayıt bundan sonra o hedefi adlandırır. Katalogdaki hiçbir Recipe’in bağlanmadığı kayıtlı bir hedef, gönderilmiş bir hedef gibi reddedilir; ret, hedefin kayıtlı hedef olduğunu belirtir. Her parça üç açıdan değerlendirilir: kaydın, içe aktarmanın oraya en son ne yazdığını söylediği, diskte ne olduğu ve kaynağın şimdi ne ürettiği. Kaynağın, içe aktarmanın en son yazdığı gibi bıraktığı bir parça, bir yazar onu düzenlemiş olsun ya da olmasın, diskte olduğu gibi kalır. Kaynağın değiştirdiği bir parça yeniden yazılır, kaynağın çıkardığı bir parça kaldırılır (taslak bir dosya bütünüyle silinir), kaynağın kazandığı bir parça ise taslağın çevresinde adlandırdığı parçaların yanına eklenir; bunların her biri yalnızca diskteki içerik, içe aktarmanın en son yazdığı içerikse ve bir yazarın eklediği hiçbir şeyi barındırmıyorsa yapılır. Geri kalan her şey bayt bayt korunur: bir yazarın herhangi bir yere eklediği bir anahtar (bir parametre, taslak bir Component örneğinin altında da olsa bir Feature, başka bir Component, taslak bir Release’in yazarına bıraktığı ortam), taslak bir anahtarın doğrudan üstüne yazılmamış bir yorum ve kaydın listelemediği her dosya. Yanıtın drift alanı, güncel hâle getirilen (ya da dry_run altında getirilecek olan) her parçayı taslağın adlandırdığı sırayla listeler; her biri change (added, removed veya changed), içinde bulunduğu taslak dosya olan file ve taslak bir Aggregate ya da Release içinde ona giden anahtarların liste olarak verildiği, parça dosyanın tamamı olduğunda boş olan key ile verilir. Metin yanıtı her birini, aggrega import komutunun standart hataya yazdığı sözcüklerle, <change> <key> in <file> veya <change> <file> biçiminde ayrı bir satırda adlandırır. dry_run altında boş bir drift, taslakların kaynakla uyumlu olduğunu söyler. dry_run altında geri verilen taslaklar, sync’in yazacağı dosyalardır ve onlara vereceği içeriği taşır. Bir yazarın düzenlediği bir parçayı değiştirecek ya da kaldıracak, bir yazarın zaten bir parça yazdığı yere parça ekleyecek veya bir yazarın eklediği bir şeyi barındıran bir parçayı kaldıracak bir sync reddedilir; ret bu tür her parçayı ve nedenini adlandırır ve hiçbir şey yazılmaz. Taslak bir anahtarın doğrudan üstüne yazılmış bir yorum, o anahtarı düzenlemiş sayılır. Hiçbir kaydın listelemediği bir Aggregate üzerindeki sync bunu belirterek reddedilir; kaydı okunamayan bir sync de öyle. İçe aktarıcısı işini bitiremeyen bir sync hiçbir şey yazmaz. Kayıt barındırmayan ve taslak yollarında hiçbir şey bulunmayan bir dizine yapılan sync, taslağın tamamını yazar. Sync olmayan bir çağrıda drift boş bir listedir.
Yanıt şunları taşır: adlandırdığınız biçimiyle source; kaynağın nasıl okunduğunu belirten format; çağrının çözümlediği çalışma alanının kökü olan workspace_root; taslak yolların göreli olduğu dizin olan output_dir; diske ulaşan dosyalar olan written; bir sync’in güncel hâle getirdikleri olan drift; içe aktarıcının çeviremediği her yapı için bir girdi içeren diagnostics; içe aktarıcının her kaynak düğümü nasıl eşlediğini belirten decisions; ve halted. output_dir, gönderdiğiniz dizindir ya da hiçbir dizin göndermediyseniz o köktür; içe aktarmanın gerçekte kullandığı değerden okunur ve hiçbir şeyin yazılmadığı ama her taslak yolun yine ona göreli olduğu dry_run altında da bildirilir. HTTP üzerinden workspace_root geri tutulur ve workspace_root_withheld ile işaretlenir; çünkü kök, Bir yanıtın sunucunun dosya sistemi hakkında söyledikleri bölümünde açıklandığı gibi sunucunun ana makinesindeki bir konumdur. output_dir, o kök olduğunda geri tutulur ve output_dir_withheld ile işaretlenir; aksi hâlde köke göreli adıyla (kendi yollarınızın aldığı biçimde) bildirilir; böylece taslakların nereye gittiği yanıtta yine yer alır. İçe aktarıcının bitiremediği bir içe aktarma yine de yapabildiği kadar taslak üretir ve bu tam yanıtı taşıyan bir hata olarak işaretlenmiş şekilde döner: halted true olur, diske ulaşan dosyalar written içinde adlandırılır ve yanlarındaki tanılama girdileri neyin eksik olduğunu adlandırır. Bu, saklayabileceğiniz ya da atabileceğiniz kısmi bir sonuçtur; hiçbir şey yapmamış bir çağrı değildir.
decisions, içe aktarmanın nerede tahmin yürüttüğünü söyler. İçe aktarıcının eşlediği her kaynak düğüm için, içe aktarıcının sırasıyla bir girdi taşır: düğümün id, type ve params_summary değerlerini içeren source_node; içe aktarıcının bu düğüm için tarttığı her katalog Component’ini component, score, tier ve signals (sinyallerinin her birinin katkısı; table, category, domain_labels, shape ve name altında) olarak veren candidates; seçtiği target’ı, onu yazdığı mode’u (var olan bir Component’e reference ya da bir draft) ve seçimin tier değerini veren chosen; nedenini açıklayan rationale; ve farklı bir seçimin nasıl yapılacağını belirten swap_hint. İçe aktarıcı hiçbir aday tartmadıysa candidates, hiçbir seçim yapmadıysa chosen, hiçbir açıklama yazmadıysa rationale ve swap_hint yer almaz. Her değer içe aktarıcının kendisine aittir (bir adayı nasıl puanladığı ve kademelerinin nereye düştüğü onun seçimleridir); bu nedenle bir girdiyi, eşlemenin onun tarafından yapılmış bir açıklaması olarak okuyun. decisions, dry_run altında da içe aktarma durduğunda da yanıtta bulunur ve hiçbir karar bildirmeyen bir içe aktarıcı için boş bir listedir. Metin yanıtı her kararı tanılama girdilerinden sonra ayrı bir satırda, aggrega import komutunun standart hataya yazdığı sözcüklerle adlandırır: mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>; buradaki puan en iyi adayın puanıdır.
dry_run, yazma dışında her şeyi yapar. Her taslak dosya, output_dir’a göreli yolu ve içeriğiyle drafts altında döner ve hiçbir şey oluşturulmaz; bu, sonucu kaydedilmeden önce önünüze koyan bir istemci içindir. Diğer tüm davranışlar yazmanınkiyle aynıdır: aynı kaynak üzerinde aynı içe aktarıcı aynı tanılama girdilerini bildirir; dolayısıyla yazmanın reddedeceği bir kaynak bunun altında da reddedilir. Bu olmadan dosyalar diske yazılır ve written onları adlandırır; drafts ise yazılmasını istediğiniz baytları tekrarlamak yerine yer almaz.
Taslaklar, sahibi olduğunuz ve düzenlemeye devam ettiğiniz bir başlangıç noktasıdır. Söyledikleri şeyin kabul edilebilir olup olmadığı (bir soketin üreticinin bildirdiği bir soket olup olmadığı ya da bir Feature’ın uygulanabilirliğinin karşılanıp karşılanmadığı) burada belirlenmez. Bunu validate yanıtlar.
Standart girdi ve çıktı üzerinden aynı yeteneğe, komutu çalıştırıp yazdırdığı metni geri veren cli-import olarak da ulaşılabilir; HTTP üzerinden bu araç yoktur ve yeteneğe orada bu araçla ulaşılır.
Yayımlama, imzalama ve geri çekme
Dört araç, bir şeyi başkalarının çözümleyeceği bir yere koyar. publish-entity bir katalog varlığını paketleyip yayımlar; publish-artifact, örneğin bir belge paketi gibi bağımsız bir dosyayı, baytları opak kalacak ve hiçbir varlık zarfı ayrıştırılmayacak şekilde yayımlar; sign-artifacts önceden yayımlanmış başvuruları imzalar ve her imzayı ekler, kayıt defterinin güven ilkesinin doğruladığı bir imzayı zaten taşıyan başvuruyu olduğu gibi bırakır; deprecate-artifact bir başvuruya imzalı bir geri çekme işareti ekler. Bunlardan herhangi birine izin vermeden önce Bir asistanın size sormadan yapabilecekleri bölümünü okuyun: etkileri makinenin dışına çıkan araçlar bunlardır.
publish-entity, yayımlanacak belge olan entity’yi alır; bir Plugin ayrıca manifestinin içinde yayımlanan yürütülebilir dosya olan plugin’e de ihtiyaç duyar. publish-artifact, file’ı, altında yayımlanacağı name ve tag ile birlikte alır. Buradaki her yol bağımsız değişkeni mutlaktır ya da çalışma alanı köküne görelidir; bu, bu yüzeydeki diğer her aracın kullandığı sözleşmenin aynısıdır ve workspace_root, standart girdi ve çıktı üzerinden erişilen bir sunucuda, çağrının kastettiği çalışma alanını adlandırır. HTTPS üzerinden erişilen bir sunucu, Tek süreç, tek çalışma alanı bölümünde açıklandığı gibi workspace_root’u reddeder ve bu yolların her birinin sunduğu çalışma alanının içinde çözümlenmesini gerektirir. registry hedeftir ve varsayılan olarak çalışma alanında yapılandırılmış olanı kullanır; hiçbir varsayılan yapılandırılmamışken ikisinin de gönderilmemesi, neyin gönderileceği belirtilerek reddedilir. sign-artifacts, yollar yerine bir veya daha fazla kayıt defteri adresi olan references’ı ve isteğe bağlı olarak bunlardan kaçının aynı anda imzalanacağını belirten jobs’u alır: belirtilmezse birbiri ardına imzalanırlar ve 1’den küçük bir değer, neyin gönderileceği belirtilerek reddedilir. Her biri yine de, aggrega sign belgesinde açıklandığı gibi, tek başına imzalanacağı şekilde imzalanır. deprecate-artifact ya severity ve reason ile birlikte reference’ı ya da bir toplu iş dosyasını adlandıran from’u alır ve bir toplu iş dosyasıyla birlikte gönderilen içerik bağımsız değişkenlerini yok saymak yerine reddeder; çünkü toplu iş dosyası kendi içeriğini sağlar ve sessizce yok sayılan bir bağımsız değişken, dikkate alınmış gibi görünür.
İki yayımlama aracı, herhangi bir kayıt defteriyle iletişim kurmadan bir yayının ne göndereceğini gösteren dry_run’ı alır. Paketi hesaplar, neyi yayımlamış olacağını bildirir ve beyond_this_machine false değeriyle ve registries içinde ulaşacağı hedefle yanıt verir; publish-entity ayrıca o yayının oluşturacağı digest ile, yani aggrega push --dry-run komutunun yazdırdığı özetle yanıt verir. Önerilen bir yayını, yayın hâline gelmeden önce birine göstermenin yolu budur. İmzalama ve geri çekmenin böyle bir biçimi yoktur: ikisi de önceden yayımlanmış bir şey üzerinde çalışır, dolayısıyla önizlenecek bir şey yoktur.
publish-entity, yayımladığı arşiv Windows’un yazıldığı hâliyle tutamayacağı girdiler taşıdığında windows_unusable_entries ile yanıt verir: harf büyüklüğü ne olursa olsun ve ardından hangi uzantı gelirse gelsin CON, AUX veya NUL gibi bir aygıtın adını taşıyan bir parçaya sahip yol ya da nokta veya boşlukla biten bir parça. Her birini, önce varlık belgesinin kendi dosya adını, ardından taşıdığı dosyaları adlandırarak listeler. Böyle bir girdi yoksa yoktur; buna yalnızca belgesiyle yayımlanan bir varlık da dahildir. Windows üzerinde çalışan aggrega böyle bir girdiyi açmayı reddeder, bu nedenle bir Windows çalışma alanı o sürümü kullanamaz; bunlar aggrega push komutunun uyardığı girdilerdir ve yanıtın metni de bunları adlandırır. Hiçbir şeyi reddettirmezler: çağrı, dry_run dahil, bunlar olmasaydı nasıl olacaksa tam olarak öyle ilerler ya da reddedilir.
publish-entity, varlık paketlenmeden önce varlık yazarının sabitleme adımını varlık üzerinde çalıştıran pin_sources’ı alır; böylece adımın varlığın yanına yazdığı entity.lock yayımlananın bir parçası olur. Bu, pin aracının çalıştırdığı adımın aynısıdır, aynı baytları yazar ve varlığı değerlendiren her türlü retten önce çalışır; dolayısıyla orada, örneğin eksik bir imza nedeniyle reddedilen bir yayın, kilidi yine de varlığın yanına yazılmış olarak bırakır. Çevrimdışı bir çalışma alanı veya hedefin olmaması gibi çağrının kendisiyle ilgili bir ret önce gelir ve hiçbir şeyi sabitlemez. Gönderilmezse çalışma alanının pin_sources_at_push ayarı karar verir; gönderilirse her iki yönde de o karar verir. Sabitleme yapan bir yayın, kayıt defterinin yanı sıra çalışma alanının içine de yazar; bu nedenle HTTP üzerinden her iki kapsamı da taşıyan bir kimlik bilgisi gerektirir ve yalnızca yayımlamaya izin veren kapsamı taşıyan bir kimlik bilgisi, diğer kapsam adlandırılarak reddedilir. Adım çalıştığında sonuç, pin aracının yanıt verdiği biçimde pin’i taşır; dry_run altında adım yazacağı kilidi bildirir ve hiçbir şey yazmaz. Adım çalışmadığında, entity.lock dosyası okuduğu bir girdi için hiçbir sabitleme kaydetmeyen bir Recipe veya FeatureRecipe reddedilir (ya da girdinin artık eşleşmediği bir sabitleme kaydeden); bu ret, dry_run dahil, herhangi bir şey paketlenmeden önce aggrega pin, pin_sources ve pin_sources_at_push adlandırılarak gerçekleşir. Bu, pull’un aynı kilit üzerinde verdiği rettir ve bunun denetlenmesi, adımın yapacağı gibi, varlığın yazdığı her uzak kaynağı tam olarak getirir.
İmzalama, kimlik bilgisinin harcandığı yerdir ve dört araçtan üçü bunu yapar: bir veri yapıtı yayını hiçbir şeyi imzalamaz ve sonradan başvuru yoluyla imzalanır. identity_token, çağrı için anahtarsız bir kimlik sağlar. Standart girdi ve çıktı üzerinden erişilen bir sunucuda, bu gönderilmezse o sunucunun kendi ortamının taşıdığı kimliğe geçilir ve key_path bunun yerine çevrimdışı tutulan bir anahtarı seçer. Bir dinleyici üzerinden bunların hiçbirine erişilemez: ortam okunmaz, key_path reddedilir ve bu üç aracın duyurduklarından çıkarılır, sunulan çalışma alanının yapılandırmasının adlandırdığı bir anahtara da erişilmez; bu nedenle Bir çağrının hangi kimlik bilgilerini harcadığı bölümünde açıklandığı gibi yalnızca çağrıda gönderilen bir belirteç imzalar. Bir çağrı tek bir kimlik bilgisiyle imzalar. sign-artifacts’a gönderilen her başvuru ve deprecate-artifact’ın okuduğu bir toplu iş dosyasının her girdisi, aynı tutulan anahtarla veya aynı anahtarsız kimlikle imzalanır; sunulan çalışma alanının yapılandırması bir başvurunun kayıt defteri için bir anahtar adlandırıp diğerininki için hiçbirini adlandırmıyorsa ya da iki farklı anahtar adlandırıyorsa, çağrı hiçbir şeyi imzalamaz ve herhangi bir kimlik çözümlenmeden veya herhangi bir kayıt defteri okunmadan önce her iki taraftaki kayıt defterleri adlandırılarak reddedilir; her kimlik bilgisi için bir çağrı gönderin ya da standart girdi ve çıktı üzerinde hepsi için tek bir key_path gönderin. Bir dinleyici üzerinden yapılandırılmış hiçbir anahtara erişilmez; bu nedenle orada her başvuru çağrının gönderdiği kimlikle imzalanır ve çağrı bu nedenle asla reddedilmez. Ret, References signed together need different signing credentials (Birlikte imzalanan başvurular farklı imzalama kimlik bilgileri gerektiriyor) bölümünde açıklanır. fulcio_url, rekor_url ve timestamp_url, her iki aktarımda da çalışma alanının yapılandırdığı anahtarsız uç noktaları geçersiz kılar. Hiçbir kimlik çözümlenmediğinde çağrı reddeder ve neyin gönderileceğini belirtir: burada hiçbir şey bir tarayıcı açmaz veya bir kişiyi beklemez, çünkü bir protokol akışını izleyen kimse yoktur ve takılıp kalan bir çağrı, reddin önlemek için var olduğu sessiz hata olurdu. publish-entity’de, sign aksini söylemedikçe bir imzanın eklenip eklenmeyeceği hedef kayıt defterinin ilkesine göre belirlenir ve imza gerektiren bir kayıt defteri, ne gönderirseniz gönderin imzasız bir yayını reddeder: bu reddi atlatan bir bağımsız değişken yoktur. İki imzalama kipi ve her birinin neyle iletişim kurduğu için aggrega sign bölümüne bakın.
Her sonuç bir döküm yerine olguları taşır: artifact’in nereye yerleştiği, etiketi, yayımlanan özet — ya da bir katalog varlığının deneme çalıştırması için bir yayının yerleştireceği özet —, etiketin zaten bayt bayt aynı içeriği gösterip göstermediği, bir yayının imzalanıp imzalanmadığı ve reach değeri. Bir imzalama toplu işi, imzalanan her referansı imzasının bağlandığı özetle birlikte, referansların verildiği sırayla bildirir; herhangi bir referansın başarısız olduğu bir toplu iş ise kısa bir listeli sonuç olarak değil, her birini adlandıran bir hata olarak döner — başarı olarak bildirilen kısmi bir toplu iş, bir reddin geçiş olarak okunmasına yol açar. Bir kullanımdan kaldırma işlemi her işaretçiyi kendi özetiyle bildirir; çünkü bir işaretçi, geri çektiği artifact’in etiketsiz bir yönlendiricisi olarak eklenir ve onu başka hiçbir şey adreslemez. Hiçbir şeyin yayımlamadığı bir referansı imzalamak ya da geri çekmek, hiçbir şeye eklenmek yerine reddedilir.
Bir yanıtın iki parçası
Her araç okunabilir bir metinle ve işlemin yapılandırılmış bir sonucu olduğu her yerde bunun yanında yapılandırılmış bir sonuçla yanıt verir. Metin, konuşmayı okuyan bir kişi için yazılır. Yapılandırılmış sonuç aynı yanıtı bir programın okuduğu alanlar olarak taşır — bir karar, bir dosya listesi, bir tanılama — ve işlem reddettiği anda elinde bulgular varsa bir ret de böyle bir sonuç taşır; bir derleme için bu, Reddedilen bir derlemenin geri verdikleri bölümünde açıklanır.
Yapılandırılmış sonuç metni de text_answer olarak taşır. Her aracın yapılandırılmış sonucunda, yanıtın metnini tam olarak metnin taşıdığı biçimde tutan bir text_answer alanı bulunur: her cümle, sırasıyla ve değişmeden. Böylece modeline metin yerine yapılandırılmış sonucu veren bir istemci de, Claude Desktop’un yaptığı gibi, metnin söylediği her cümleyi yine modele iletir — argümansız describe-capabilities yanıtının başladığı satırı, config-show komutunun bildirdiği yürürlükteki yapılandırmayı, hiçbir çalışma alanı bulunamadığında bir yanıtın kullandığı klasörü adlandıran cümleyi. text_answer, aracın yanıt verdiği alanlardan önce, ilk olarak yazılır ve çağıranın aldığı metin odur: HTTP üzerinden, sunucunun ana makinesindeki her konumu metnin adlandırdığı gibi adlandırır; bu, Bir yanıtın sunucunun dosya sistemi hakkında söyledikleri bölümünde açıklanır. Metnin kendisi, onu okuyan istemciler için olduğu gibi düz yazı olarak kalır; dolayısıyla aynı sözcükler her yanıtta iki kez taşınır.
lint dahil hiçbir araç istisna değildir. Hiçbir araç text_answer adlı kendine ait bir alanla yanıt vermez, bu nedenle bu alan hiçbir zaman böyle bir alanın yerini tutmaz. lint’in yapılandırılmış sonucu summary alanını korur — denetlenen varlıkların ve bulguların toplam ve önem derecesine göre sayısı, aggrega lint komutunun -o json ile yazdığı adlar altında — ve yanında text_answer alanını taşır. describe-capabilities de kendi alanlarını korur: hiçbir argüman gönderilmediğinde tek başına sürüm satırı olan version_summary ve index alanının her girdisinde o aracın tek satırlık amacı olan bir summary.
Hiçbir araç bir çıktı şeması duyurmaz. Bir aracın listesi, aldığı argümanlar için bir şema taşır ve sonucu için hiçbir şema taşımaz; bu nedenle text_answer bir şemada değil burada adlandırılır.
Yapılandırılmış sonucu olmayan bir yanıt yalnızca metninden oluşur. Bir çağrının argümanlarının reddi ve işlemin bildirecek yapılandırılmış hiçbir şeyi olmadığı diğer her başarısızlık, yalnızca metni olarak geri döner; bu durumda metin, bir istemcinin modeline gösterebileceği tek parçadır.
Bir çağrı başarılı olmadığında
Yanıtın nereye geldiği tek bir şeye bağlıdır: çağıranın bunu var olan bir aracın argümanlarını değiştirerek düzeltip düzeltemeyeceğine.
Bu şekilde düzeltilebilen her şey, aracın kendi sonucu olarak, başarısızlık olarak işaretlenmiş ve düzeltmeyi metni olarak taşıyarak geri döner: aracın kabul etmediği bir seçici birleşimi, atlanmış zorunlu bir argüman, yanlış JSON türünde gönderilmiş bir argüman, çözümlenmeyen bir yol, derleyiciden gelen bir tanılama. Bir asistana gösterilen kanal budur; böylece asistan neyin yanlış gittiğini okur ve argümanı düzelterek yeniden çağırır.
Protokolün hata kanalı, içinde yer alacağı bir araç sonucu olmayan durumlar için ayrılmıştır: sunucunun sunmadığı bir araç adı, parametrelerini okuyamadığı bir istek, uygulamadığı bir yöntem ve hiç geçerli JSON olmayan bir mesaj. Bir kaynağı okumak ve bir istemi işlemek de orada yanıtlanır, çünkü bu sonuçların hiçbiri kendine ait bir başarısızlık işareti taşımaz.
Bir aracın duyurduğu şema, argümanlarının karşılaması gereken kuralların çoğunu da bildirir: hangi seçicilerin birbirini dışladığını, hangi argümanın yalnızca bir başkasıyla birlikte anlamlı olduğunu ve hangilerinin zorunlu olduğunu. Bu nedenle bildirilen şemaya göre çağrı oluşturan bir istemcinin bunları öğrenmek için çağrıyı yapması nadiren gerekir. Şemanın belirtmediği bir kural yine de, onu adlandıran bir cümleyle reddedilir; pull’un verify’ın upgrade_targets veya pin_sources ile birleştirilmemesi kuralı, Bir Release’in neye bağlı olduğunu çözümleme altında verilen nedenle bilerek reddetmeye bırakılmıştır.
Sunucuyu ne durdurur
Standart girdi ve çıktı üzerinden, bağlantının kapatılması sunucuyu durdurur. Sunucu her satırda bir mesaj okur ve standart girdisi akışın sonuna ulaştığında temiz bir şekilde çıkar; dolayısıyla bağlantıyı kapatan bir istemci sunucuyu kapatır. Bu aktarımda olağan durum budur, çünkü komutu hiçbir zaman kendiniz başlatmazsınız: onu başlatan istemci onu sonlandıran da olur; bu nedenle durdurma genellikle düzenleyicinizden çıkmak ya da bu sunucuyu bir proje için devre dışı bırakmak şeklinde gerçekleşir.
Sürecin kendisinden durmasını istemek, sunucuya her iki aktarımda da ulaşır. Bir terminalden gelen kesme ya da bir denetleyiciden veya bir konteyner çalışma zamanından gelen sonlandırma isteği, bir istemcinin bir şey gönderip göndermediğinden bağımsız olarak sunucuyu ilk istekte kapatır: sunucu mesaj kabul etmeyi bırakır, sürmekte olan bir çağrının yaptığı işi sonlandırır ve temiz bir şekilde çıkar. İkinci bir istek süreci hemen sonlandırır. Bu nedenle standart girdi ve çıktı üzerinden, sürecin durması istendiğinde hâlâ çalışan bir çağrı tamamlanmaz; buna karşılık bir dinleyici boşaltma yapar ve süreç çıkmadan önce yanıtlanmakta olan bir çağrının sınırlı bir süre içinde tamamlanmasına izin verir.
Bir istemci, sunucuyu durdurmadan tek bir çağrıyı da durdurabilir; bunun nasıl yapılacağını aktarım belirler. Çağrılar eşzamanlı olarak yanıtlanır; bu nedenle bir çağrıyı sonlandırma isteği, o çağrının arkasında beklemek yerine çağrı hâlâ çalışırken işleme alınır. Standart girdi ve çıktı üzerinden istemci çağrının id’sini belirtir; zaten yanıtlanmış bir çağrıyı ya da sunucunun üzerinde çalışmadığı bir çağrıyı iptal etmek hiçbir şey yapmaz — bu da böyle bir mesajın, yanıtın zaten yolda olup olmadığını önceden bilmeden gönderilmesini güvenli kılar. HTTP üzerinden gönderilecek bir mesaj yoktur: çağrıyı taşıyan bağlantının kapatılması onu sonlandırır. Her iki durumda da çağrıya durması bildirilir — işi, işlemin denetim yaptığı bir sonraki noktada sona erer ve hiç denetim yapmayan bir işlem sonuna kadar çalışır —, o çağrı için başka bir şey gönderilmez, sürmekte olan diğer tüm çağrılar devam eder ve sunucu hizmet vermeyi sürdürür.
Ne zaman kullanılır
Bir yapay zekâ asistanının Aggrega varlıklarını gerçek şemalara ve başvuru belgelerine göre yazmanıza yardım etmesini istediğinizde aggrega mcp kullanın; böylece önerileri tahmine değil, derleyicinin kabul ettiği yapının tam kendisine dayanır. Doğrudan yazma döngüsüne uyar: asistan bir türün şemasını ve başvuru belgesini okur, bir iskelet oluşturur, rolünüzün sahip olduğu alanları doldurur ve taslağı size geri vermeden önce doğrular. Bu döngü için Aggrega dosyalarını yazma sayfasına bakın.
Standart girdi ve çıktı üzerinden aggrega mcp komutunu genellikle hiçbir zaman kendiniz yazmazsınız. Bunun yerine istemcinizin MCP yapılandırmasında onu bir kez adlandırırsınız ve istemci onu sizin için başlatıp durdurur. Dinleyici ise diğer durumdur: orada süreci siz çalıştırırsınız ve süreç, onu başlatmamış çağıranlar için çalışmaya devam eder.
Örnek: standart giriş ve çıkış üzerinden istemci yapılandırması
Bir MCP istemcisini, bir stdio sunucu girdisiyle komuta yönlendirin:
{ "mcpServers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}Tek ön koşul, kurulu aggrega ikili dosyasının istemcinin PATH’inde bulunmasıdır. İstemciye özgü yapılandırma yolları ve sorun giderme için MCP sunucusunu bağlama sayfasına bakın. Bir şemayı istemci olmadan doğrudan komut satırından almak için aggrega get-schema sayfasına bakın.