Yapılandırma
aggrega’nın ayarlarını nereden okuduğu ve bir ayarın hangi dosyaya konacağı.
Basit durum
İki dosya; çoğu projenin başka bir şeye ihtiyacı yoktur.
Projenizde bir dosya: proje kökünde duran .aggrega-config.yaml adlı dosya. Bu dosya
bu projenin nasıl derlendiğini tutar: hangi dizinlerin vendor edilmiş katalog içeriğini barındırdığını, hangi plugin’lerin
hangi hedefleri render ettiğini, hangi lint kurallarının gevşetildiğini, yerel önbelleğin nereye gittiğini. Commit edilir; böylece
projeyi klonlayan bir ekip arkadaşı onu aynı şekilde derler.
Dizini proje kökü olarak işaretleyen, dosyanın workspace: bloğudur:
# <project>/.aggrega-config.yamlworkspace: catalog_dirs: - ./catalogauto_pull: trueBlok yalnızca kökü tanımlayan katalog dizinlerini taşır; diğer her ayar onun yanında en üst
düzeydedir. Hiç katalog içeriği vendor etmeyen bir proje de bloğu boş olarak yazar —
workspace: {} — çünkü işaret, bloğun varlığıdır.
Makinenizde bir global dosya: ~/.config/aggrega/config.yaml konumunda — Windows’ta ise
APPDATA ortam değişkeninin gösterdiği dizinin içindeki aggrega\config.yaml konumunda. O makinedeki her çalışma alanı
onun üzerinden çözümlenir ve dosya,
herhangi bir projeye değil makineye ait ayarları tutar — çektiğiniz registry’ler ve her biri için imza güven politikası, derlenmiş modül deposunun ne kadar
büyüyebileceği ve kurduğunuz her komut uzantısı plugin’i. Bunlar nerede çalışırsanız çalışın
aynıdır; amaç, onları bir kez bildirmektir. Dosya mevcutsa otomatik olarak yüklenir, mevcut değilse
hiçbir şey bozulmaz.
registries: - host: hub.aggrega.ai signing: required: trueaggrega config init bu global dosyayı sizin için yazar; bir registry’yi, ilan ettiği imza
güven politikasıyla birlikte kaydeder ve dosyanın makinenizde nerede olduğunu, makine genelindeki önbelleklerin
nerede tutulduğunu söyler. aggrega config show şu anda geçerli olanı yazdırır,
aggrega config show --origin ise her ayarı hangi dosyanın — ya da hangi ortam değişkeninin — belirlediğini
söyler.
Gizli bilgiler yapılandırma değildir. Bir registry parolası ve bir imzalama kimlik belirteci hiçbir zaman iki dosyadan herhangi birinde alan olarak yer almaz; gerektikleri anda ortam değişkeni ya da bayrak ile sağlanırlar. Bkz. environment-variables.md.
Yerel varlıkların okunduğu yer
Kendine ait katalog içeriği tutan bir proje — bir Component, bir Feature, bir Recipe, kütüphane türlerinden biri — bu içeriğin nerede bulunduğunu iki şekilde söyleyebilir ve birincisi hiç yapılandırma gerektirmez.
Proje kökündeki bir catalog dizini, onu bir şeyin adlandırıp adlandırmadığına bakılmaksızın okunur. Bir
varlığı <project>/catalog/ altına koyun; katalog yükleyen her komut onu okur, workspace: bloğu
boş olan bir projede bile. Bir katalog dizini özyinelemeli olarak okunur; dolayısıyla içindeki alt dizinleri
nasıl düzenleyeceğiniz size kalmıştır.
workspace.catalog_dirs altında listelenen dizinler de okunur ve önce onlar okunur.
Liste sıralı bir arama yığınıdır: bir kimliği ilk bildiren dizin ona sahip olur ve
sonraki bir dizindeki aynı kimlik gölgelenir. catalog, listelenen her şeyden sonra okunur — listelenen
bir dizin onu zaten içermiyorsa; içeriyorsa o dizinin parçası olarak okunur — böylece
bir dizini listelemek, elinizdekinin yerine geçmek yerine ona ekleme yapar. Komut satırında tekrarlanabilir bir --catalog <dir>
her ikisinden önce okunur ve orada verilen göreli bir yol, hiçbir yapılandırma dosyası onu bildirmediğinden,
komutu çalıştırdığınız dizine göre çözümlenir. Birden fazla kez adlandırılan bir dizin
— komut satırında ve listede, ya da listede iki kez — bir kez, ilk adlandırıldığı yerde okunur;
böylece içindeki hiçbir şey kendisi tarafından gölgelenmiş olarak raporlanmaz: bir gölge her zaman tek bir kimliği
bildiren iki farklı dosyadır. Bir dizinin iki farklı yazımı, ona bir bağlantı üzerinden giden bir yol ve —
büyük/küçük harfi yok sayan bir dosya sisteminde — başka bir harf büyüklüğüyle yazımı, hepsi o tek dizini adlandırır.
Listelenen başka bir dizinin içindeki bir dizin yine kendi girdisi olarak okunur. Her Release için bir
katalog varyantı tutan bir proje, bunun yerine her Release’e kendine ait bir liste verebilir — bkz.
Bir Release’e kendi katalog dizinlerini vermek.
Bir dizini listelemek, bir projenin kendi dışında tutulan varlıkları okuma yoludur. Listelenen bir dizin herhangi bir yerde olabilir — kardeş bir checkout, başka projelerle paylaşılan bir dizin — ve kendisi sembolik bir bağlantı olsa bile bulunduğu yerde okunur. Başka hiçbir şey o kadar uzağa erişmez: proje içinde başka bir yere giden bir bağlantının içinden okunmaz ve proje dışındaki bir dosyayı yol ile adlandıran bir belge reddedilir; böylece başka bir yerde tutulan bir varlığa, onu barındıran dizini listeleyerek ve varlığı adıyla anarak erişilir. Proje dışındaki listelenmiş bir dizin kendi başına bir köktür; dolayısıyla altında, onun dışına giden bir bağlantı da okunmaz. Çalışma alanı sınırı kuralın tamamını belirtir.
Listelenen bir dizin bir dizin olmalıdır. Hiçbir şeyin bulunmadığı ya da bir dosyanın veya hiçbir yere götürmeyen bir bağlantının durduğu listelenmiş bir yol, kataloğu okuyan her komut tarafından herhangi bir şey okunmadan veya yazılmadan önce reddedilir — bir pull, bir build, bir doğrulama, bir inceleme, bir lint ve düzenleyiciden aggrega serve üzerinden ya da bir asistandan aggrega mcp üzerinden yürütülen aynı işlemler — böylece bir build hiçbir zaman listelediğinizden daha az katalogla çalışmaz. Ret; girdiyi yazıldığı biçimiyle, çözümlendiği yolu, onu listeleyen yapılandırma dosyasını ve satırı ve içinde bulunduğu listeyi adlandırır:
<project>/.aggrega-config.yaml:4: the `workspace.catalog_dirs` entry "../shared/aggrega-catalog" names <directory>, which does not exist; create that directory, or remove the entry: workspace configuration is invalidDizini oluşturun ya da girdiyi kaldırın: bir projenin, listelediği kardeş bir checkout olmadan alınmış bir kopyası o girdiyi kaldırır ve checkout’un sağlayacağı şeyi bir registry’den çözümler. Aynısı, bir Release’in kendi girdisinin listelediği dizin, pipeline’ınıza ait bir yapılandırma dosyasının ya da genel dosyanın eklediği dizin ve AGGREGA_CATALOG_DIRS’in taşıdığı dizin için de geçerlidir; sonuncusunda ret, bir dosya yerine bu değişkeni adlandırır. Yapılandırmanın kendisi yine yüklenir, bu nedenle hiçbir katalog okumayan bir komut yine çalışır. Var olmayan bir --catalog dizini tek bir komut için yazılmıştır ve aggrega build dizini adlandırarak onu reddeder. Var olan ama okunamayan listelenmiş bir dizin, tüm kataloğu yükleyen komutlar tarafından adlandırılarak reddedilir.
Listeyi boş yazmak, bu projenin hiç yerel kataloğu olmadığını söyler ve catalog dizininin de
okunmasını durduran tek yazım budur:
# <project>/.aggrega-config.yamlworkspace: catalog_dirs: []Anahtarı hiç yazmamak farklı bir ifadedir: atlanmış bir liste olağan durumdur ve catalog
yine okunur.
Kullandığınız bir ad altında hiçbir varlık bulamayan bir build, bir pull, bir doğrulama ya da bir aggrega inspect, bu projenin yerel varlıkları nereden okuduğunu ve adlandırdığınız varlığın okunması için neyin değiştirilmesi gerektiğini söyler. Boş listeyi yazdığınız yerde böyle bir şey söylemez — yerel katalog okumamak orada bildirdiğiniz şeydir ve onu değiştirme önerisi sizinle tartışmak olurdu. O adı bildiren belgenin okunup reddedildiği yerde de söylemez: o belge zaten kataloğun okuduğu yerde durmaktadır; bu nedenle rapor bunun yerine belgenin neyi ihlal ettiğini, satırı ve kısıtı adlandırır; belgeyi taşımak hiçbir şeyi düzeltmezdi. Bildirdiği adın hiç okunamayacağı kadar bozuk bir belge kullandığınız adla eşleştirilemez, bu nedenle açıklama yine de verilir — ve o belge bir Aggrega apiVersion’ı bildiriyorsa, bir Release’in build’i, pull’u ya da doğrulaması onu açıklamanın yanında, ayrıştırıcının kendi gerekçesiyle adlandırır, çünkü açılması gereken dosya o olabilir. Varlığı bulan ancak onu kabul edemeyen bir hata — lockfile’ınızın sabitlediği bir sürüm altında artık başka baytlar sunan bir registry, varlığın taşıdığı okunamayan bir dosya — da eksik varlık değildir ve yalnızca kendi çözümünü raporlar.
Bir pull’un ya da push’un bir varlığı sabitleyip sabitlemediği
Bir Recipe ya da FeatureRecipe, okuduğu girdilerin sabitlemelerini — tam olarak yazılmış uzak bir source:,
bir artifacts girdisinin içe aktardığı bir dosya, yanındaki bir source: dosyaları — yanındaki entity.lock içinde taşır ve bunları kaydetmek
varlık yazarının adımıdır: aggrega pin. Varsayılan olarak ne pull ne de push
bu adımı çalıştırır: bir pull, kilidinin sabitlemediği bir varlıkta durur ve bir push onu yayımlamayı reddeder.
Her komut için bir tane olmak üzere iki anahtar, bu adımı çalıştırmayı o komutun varsayılanı yapar:
# <project>/.aggrega-config.yamlworkspace: {}pin_sources_at_pull: truepin_sources_at_push: trueHer anahtar yalnızca kendi komutunu yönetir, ve her komutun --pin-sources bayrağı kendi anahtarını
her iki yönde geçersiz kılar — --pin-sources=false, sabitleme yapacak şekilde yapılandırılmış bir projede adımı
tek bir çalıştırma için kapatır. Kendi lockfile’ını dolduran bir build bir pull’dur ve
pin_sources_at_pull anahtarını izler. Bu anahtarların yeri global dosya değil proje dosyasıdır: bir projenin
pull’larının sabitleme kaydedip kaydetmediği o projenin politikasıdır ve projeyi klonlayan bir ekip arkadaşı
aynı yanıtı almalıdır. pin_sources_at_pull aynı zamanda başka birinin sabitlenmemiş kataloğunu kullanan bir projenin
her pull’da durmak yerine bu sabitlemeleri bir kez kaydetme yoludur.
Bir yeteneği hangi eklentinin işlediği
Bir Recipe, üzerinden işlendiği yeteneği adlandırır — capability: helm — ve o yeteneği sunan bir eklenti onu işler. Bir yeteneği tam olarak bir eklenti sunuyorsa hiçbir şeyin yapılandırılması gerekmez. Birden fazla eklenti sunuyorsa, bir plugins.providers girdisi hangisinin kullanılacağını eklentinin kimliğiyle belirtir:
# <project>/.aggrega-config.yamlworkspace: {}plugins: providers: - capability: helm uri: provider/helmBir pull, girdiyi çözümler ve seçtiği eklentiyi Release’in kilit dosyasına kaydeder; bir build ise kilit dosyasının kaydettiği üzerinden işler, bu nedenle burada yapılan bir düzenleme bir sonraki pull’da etkili olur.
uri, eklentiyi yayımlandığı yerle değil, her zaman kimliğiyle, provider/<name> ile adlandırır. aggrega plugin add provider <query> --capability <capability> girdiyi bu biçimde ve sürümsüz yazar: girdi, yeteneği hangi eklentinin sunacağını seçer; sürüm, Recipe’in sabitlediği sürüm ya da yoksa mevcut en yüksek sürümdür ve kilit dosyası pull’un seçtiği sürümü kaydeder. Derleyicinin kendi içinde taşıdığı bir eklenti derleyicinin kendi sürümünde sunulur; bu nedenle bunlardan biri için bir girdiye yazılan sürüm yalnızca tam olarak o sürüm olduğunda çözümlenir. uri değeri bir registry konumu olan bir girdi — oci://hub.aggrega.ai/plugin/provider/helm — hiçbir eklentinin kimliğini adlandırmaz ve dosya yüklenirken, girdiyi ve yazılması gereken biçimi adlandırarak reddedilir.
Girdiler tüm proje için bir kez yazılır, oysa bir build tek bir Release içindir; bu nedenle bu Release’in hiç istemediği bir yetenek için bir girdi geçerlidir — projedeki başka bir Release onu okur — ve hiçbir şey olarak raporlanır. Her build’in ve her aggrega validate --release çalıştırmasının denetlediği şey ise, bir Recipe yeteneğini istesin ya da istemesin, her girdidir ve girdinin adlandırdığı şeye göre denetlenir:
- Eklentisi kendi yeteneğini sunmayan bir eklentiyi adlandıran girdi, build’i durdurur ve doğrulamayı başarısız kılar. Bir pull, bir eklenti adlandıran her girdiyi çözümler ve çözümleyemediğini reddeder; bu nedenle bir girdi bir pull’dan geçtikten sonra build onun eklentisine sahiptir ve neyi sunduğunu bilir; build’in henüz sahip olmadığı bir eklentiyi adlandıran girdi, bir pull onu getirdikten sonra değerlendirilir. İleti
girdiyi, eklentiyi,
o eklentinin gerçekte neyi sunduğunu ve varsa tek düzenleme uzaklıktaki bir yazımı adlandırır —
helmyerinehlemgibi bir yazım hatasının aldığı biçim. - Yalnızca build’in okuduğu hiçbir eklentinin sunmadığı bir yeteneği adlandıran girdi bir uyarıdır ve build devam eder. Onu sunan eklenti yalnızca başka bir Release’in okuduğu, bu build’in göremediği bir eklenti olabilir; hiçbir eklenti adlandırmayan bir girdi ise yeteneğin çözümlemesinin o girdi olmadan seçmeyeceği hiçbir şeyi seçmez.
Burada bir yetenek asla iki nokta üst üste içermez ve içeren bir yetenek dosya yüklenirken reddedilir. Bir
Recipe’in capability: değeri, son iki noktaya kadar yetenek ve ondan sonrası bir sürüm sabitlemesi olarak okunur; bu nedenle helm:1.0.0 anahtarlı bir girdi asla aranamaz. Bunun yerine sürümü eklentide sabitleyin —
uri: provider/helm:1.0.0 — ya da Recipe’te.
Bir kaynağı hangi içe aktarıcının taslaklara dönüştürdüğü
aggrega import, bir kaynağı o kaynağın biçimini duyuran içe aktarıcıya verir — kataloğunuzdaki bir içe aktarıcıya ya da derleyicinin çekirdek içe aktarıcılarından birine; bir Langflow akışı için import:langflow. Biçimi tam olarak bir içe aktarıcı duyuruyorsa hiçbir şeyin
yapılandırılması gerekmez. Bir plugins.importer girdisi, bir içe aktarıcıyı uri içinde kimliği ve sürümüyle adlandırarak bağlar ve ona with altında taşıdıklarını verir:
# <project>/.aggrega-config.yamlworkspace: {}plugins: importer: - uri: importer/agent-flows:1.2.0 with: settings: target_namespace: paymentsaggrega plugin add importer, uri değerini tam olarak bu biçimde yazar. Sürüm ya tamdır — :1.2.0
— ya da bir aralıktır — aynı ana sürüm içinde ona eşit ya da daha yüksek en yüksek sürüm için :^1.2.0. Birini ya da diğerini yazın: bu listede iki nokta üst üste içermeyen bir uri,
Göreli bir yolun nereyi gösterdiği bölümünün açıkladığı gibi bir dosya sistemi yolu olarak okunur ve hiçbir içe aktarıcıyı adlandırmaz.
Bir girdinin ne yaptığı, adlandırdığı içe aktarıcının bir içe aktarmanın istediği biçimi duyurup duyurmadığına bağlıdır:
- Duyuruyorsa: çalışan içe aktarıcı odur; katalogdaki başka kaç içe aktarıcı biçimi duyurursa duyursun
urideğerinin adlandırdığı sürümde çalışır ve ona girdininwith.sourcesvewith.settingsdeğerleri verilir. Bir girdi, kataloğu tek bir biçim için iki yayıncının içe aktarıcılarını birleştiren bir çalışma alanının hangisini kullandığını belirtme yoludur. - Duyurmuyorsa — başka bir biçimin içe aktarıcısını, başka türde bir eklentiyi ya da kataloğunuzun
içermediği veya derleyicinin taşımadığı bir şeyi adlandırıyorsa: girdi o içe aktarmada hiçbir rol oynamaz. Hiçbir şey seçmez ve
withdeğeri hiçbir içe aktarıcıya verilmez. Bir girdinin ayarları yalnızca adlandırdığı içe aktarıcıya ulaşır; bu nedenle biçim başına bir içe aktarıcı bağlayan bir çalışma alanı, birinin ayarları diğerine ulaşmadan her birini yapılandırır.
Biçimi birden fazla içe aktarıcı duyuruyor ve bunlardan tek biri bağlanmamışsa — hiçbiri bağlanmamışsa ya da girdiler bunlardan ikisini adlandırıyorsa — içe aktarma reddedilir ve aralarında seçim yapamadığı içe aktarıcılar adlandırılır. Biçimi duyuran bir içe aktarıcıyı, katalogdaki hiçbir sürümünün karşılamadığı bir sürümde adlandıran girdi — katalogda bulunmayan tam bir sürüm ya da hiçbir sürümünün içine düşmediği bir aralık — da reddedilir ve yerine başka bir sürüm çalıştırılmak yerine sürüm adlandırılır; :latest gibi hiç sürüm olmayan bir değer hatalı biçimli olarak reddedilir. Derleyicinin çekirdek içe aktarıcılarından birine ait olup katalog klasöründe yanında modül bulunmayan bir Plugin varlığı aday değildir: derleyicinin kendi sürümünde onun yerine çekirdek içe aktarıcı çalışır, başka herhangi bir sürümde ise varlık yalnızca bir girdi tam olarak o sürümü adlandırdığında ya da o adı taşıyan ve çalışabilen hiçbir içe aktarıcı biçimi duyurmadığında aday olarak kalır; bu, Kendi içe aktarıcılarınızın yanında hangisi çalışır bölümünde anlatılır.
Her içe aktarıcı tek bir girdiyle bağlanır. Bir içe aktarıcıyı adlandıran iki girdi — aynı kimlik, ister tek sürümde ister iki sürümde — hangi komut okursa okusun yapılandırma yüklenirken reddedilir ve
her iki girdi ile yazıldıkları dosyalar adlandırılır. Kural listeye katkıda bulunan her dosyayı kapsar: genel dosyadaki bir girdi, bir projenin dosyasındaki bir girdi, importer_append altındaki bir girdi ve
bir işlem hattının .aggrega-config-append-ci.yaml dosyasındaki bir girdi sayılır; bu nedenle bir içe aktarıcıyı yeni bir
sürüme taşımak, tek girdisindeki sürümü değiştirmek demektir. aggrega plugin add importer, yazdığı dosyanın plugins.importer listesi içe aktarıcıyı zaten adlandırıyorsa tam olarak bunu yapar: ikinci bir girdi eklemek yerine o girdiyi çözümlediği sürüme taşır ve girdinin yerini ve with değerini korur. Başka hiçbir listeyi okumaz; bu nedenle importer_append altında ya da bir
işlem hattının .aggrega-config-append-ci.yaml dosyasında bağlanmış bir içe aktarıcı komut tarafından ikinci kez bağlanır ve bu çift
yapılandırma yüklenirken reddedilir; böyle bir girdideki sürümü yazıldığı yerde değiştirin.
uri değeri bir dosya sistemi yolu olan girdi hiçbir içe aktarıcıyı adlandırmaz ve karşılaştırılmaz; plugins.governance ve plugins.linter listeleri ise bu kurala tabi değildir: bir eklenti bunlara her seferinde kendi with değeriyle birden fazla kez bağlanabilir.
Bir içe aktarmanın üzerinden okuduğu ayrıştırıcılar girdi gerektirmez. Bir içe aktarıcı kaynağını — ve hiçbir biçim adlandırmayan bir içe aktarma kaynağın biçimini — kaynağın sözdizimi için bir ayrıştırıcı üzerinden okur: kataloğunuzun o sözdizimi için sunduğu ayrıştırıcı ve kataloğunuzun ayrıştırıcı sunmadığı bir sözdizimi için derleyicinin kendisinin taşıdığı ayrıştırıcı; JSON da bunlar arasındadır. Bu nedenle kataloğunda hiç ayrıştırıcı bulunmayan bir çalışma alanı, hiçbir şey yapılandırmadan bir Langflow ya da Flowise akışını içe aktarır. Hiçbir liste ayrıştırıcı bağlamaz: kataloğunuzun bir sözdizimi için sunduğu ayrıştırıcı kullanılır ve tek bir sözdizimini sunan farklı adlardaki iki ayrıştırıcı, A parse or import format is advertised by more than one plugin (Bir ayrıştırma ya da içe aktarma biçimi birden fazla eklenti tarafından duyuruluyor) sayfasının açıkladığı gibi reddedilir.
Sıfırdan başlamak
Yeni kurulmuş bir aggrega dosyalardan hiçbirine sahip değildir ve bu bozuk değil çalışan bir durumdur: her ayar yerleşik varsayılanına döner ve komutlar çalışır. Eksik olan, katalog içeriğinin çekileceği bir kayıt defteri ve hangi imzaların kabul edileceğini belirten güven politikasıdır — aggrega config init tam olarak bunu yazar.
Bunu önceden bilmeniz gerekmez. Yapılandırmasını okuyan ve hiçbir yerde dosya bulamayan bir komut bunu standart hataya bir kez bildirir ve bir dosya oluşturmanın yolu olarak aggrega config init komutunu adlandırır.
Bu bir hata değil, bir öneridir: standart çıktıya dokunulmaz, sizden hiçbir şey istenmez ve çıkış durumu komutun zaten bildireceği durumdur. Yalnızca standart hata bir terminal olduğunda yazılır; böylece klavyenin başındaki size ulaşır ve bir işlem hattının günlüğünde asla birikmez.
Dosyalardan biri — projenizinki ya da genel olan — var olduğunda görünmez olur.
Genel dosyayı resmi hub ve o hub’ın duyurduğu güven politikasıyla başlatmak için:
aggrega config initFarklı bir kayıt defteriyle başlatmak için --registry <host>, girdiyi genel dosya yerine bu projenin dosyasına yazmak için --workspace ve hiçbir şey oluşturmadan yazacağı içeriği görmek için --dry-run verin. Komutun tamamı aggrega-config.md sayfasında ele alınır.
Bir kayıt defteri ana makinesi nasıl yazılır
Her registries[].host bir kayıt defteri ana makinesini adlandırır. default_registry de — isteğe bağlı olarak ardından bir
depo yolu gelerek — bunun yerine bu girdilerden birini adlandırmıyorsa (aşağıya bakın) aynısını yapar. Bir ana makine,
ana makinenin kendisi olarak, kayıt defterinin güven politikasının altında tutulduğu tek yazımla yazılır:
registry.example.comgibi, nokta içeren küçük harfli bir ana makine adı;localhostya daregistry:5000gibi, ardından bir port gelen tek bir ad;127.0.0.1gibi bir IPv4 adresi ya da[::1]gibi köşeli parantez içinde bir IPv6 adresi;
her biri isteğe bağlı bir :port ile ve başka hiçbir şey olmadan — şema yok, yol yok, kimlik bilgisi yok, boşluk yok
ve büyük harf yok. Portu olmayan tek bir ad bir kayıt defteri ana makinesi değildir, çünkü bu, bir katalog varlığının adının
ilk bölümünün biçimidir — core/web-api içindeki core — ve ikisi asla birbiri olarak okunmamalıdır.
# <project>/.aggrega-config.yamlworkspace: {}default_registry: registry.example.comregistries: - host: registry.example.com signing: required: trueYazım, politikanın bir parçasıdır. Bir registries girdisi, host: alanının adlandırdığı ana makineye uygulanır
ve resmî hub’ın yerleşik imza gereksinimi hub.aggrega.ai için geçerlidir; bu yüzden başka bir biçimde yazılmış bir ana makine
doğru kayıt defterine ulaşır ama onun için yazılmış politikayı kaçırır. Bunun yerine yapılandırma yüklenirken reddedilir ve
ret mesajı yazılması gereken yazımı belirtir: HUB.AGGREGA.AI ve https://registry.example.com, hub.aggrega.ai ve
registry.example.com belirtilerek reddedilir; yol taşımayan bir registries[].host olarak registry.example.com/charts da
öyle. 443 numaralı port, HTTPS üzerinden ulaşılan bir ana makinenin varsayılan portudur, bu yüzden hub.aggrega.ai:443 de aynı şekilde,
hub.aggrega.ai belirtilerek reddedilir. localhost ve diğer geri döngü adreslerine ise düz HTTP üzerinden ulaşılır;
orada 443 sıradan bir porttur, bu yüzden localhost:443 yazıldığı gibi kabul edilir. Boş bir
default_registry hiçbir varsayılan kayıt defterini adlandırmaz.
default_registry bir depo yolu taşıyabilir. Birçok kayıt defteri her depoyu bir sahip ya da proje altında
tutar — ghcr.io/<owner>, Harbor’da <host>/<project> — ve bunlardan biri üzerindeki varsayılan kayıt defteri, ana makine
ve ardından o yol olarak yazılır:
# <project>/.aggrega-config.yamlworkspace: {}default_registry: ghcr.io/acmeregistries: - host: ghcr.io signing: required: trueYol, öğelerin yayımlandığı ve getirildiği yerdir. Bu varsayılan aracılığıyla aggrega push, core/api-server
sürüm 1.0.0’ı ghcr.io/acme/component/core/api-server:1.0.0 adresinde yayımlar ve core/api-server’ı çözümleyen bir pull
onu aynı yerden getirir; böylece yayımlandığında eklenen bir imza da orada bulunur. Yol, OCI dağıtım dilbilgisindeki bir depo
yoludur: / ile birleştirilen, küçük harf ve rakamlardan oluşan bir ya da daha fazla bölüm; bir bölüm içinde ., _, __
ya da tirelerle ayrılabilir; etiket, özet (digest) ya da sondaki / olmaz.
Yol, kayıt defterine nasıl güvenildiğinin asla bir parçası değildir. Politikası uygulanan registries girdisi,
aggrega login’in sakladığı kimlik bilgisi, imzalama gereksinimi ve güvenilen kimliklerin
tümü yalnızca ana makineye göre bulunur; bu yüzden yukarıdaki ghcr.io girdisi ghcr.io/acme’yi ve o ana makinedeki diğer her
yolu yönetir ve hiçbir yol yazımı onu aşamaz; bir girdinin host: alanı da yol taşımaz. Bir yoldan önce başka bir yazımla
yazılmış ana makine, yazılması gereken konum belirtilerek reddedilir —
GHCR.io/acme ve https://ghcr.io/acme için ghcr.io/acme belirtilir — ve ana makineden sonra gelen kısım bir depo yolu
değilse, izlediği ana makine belirtilerek reddedilir.
default_registry bunun yerine bir girdiyi adlandırabilir. registries altındaki bir girdinin name: değeri olarak
yazıldığında, o girdinin host: değerini temsil eder. Yayımlama, çekme, imza doğrulama ve
kayıt defterine özgü her güven ayarı bu durumda o ana makineyi kullanır ve adla aynı biçimde yazılmış bir ana makineden
hiçbir içerik getirilmez:
# <project>/.aggrega-config.yamlworkspace: {}default_registry: localregistries: - name: local host: 127.0.0.1:5000--registry bayrağının yaptığı gibi, ad bir ana makine yazımından önce eşleştirilir; bu yüzden bir girdinin name:
değeri olan bir değer, bir ana makine gibi yazılmış olsa bile o girdiyi temsil eder. İki girdinin taşıdığı bir ad, iki ana makine
de belirtilerek belirsiz olduğu için reddedilir. Girdi her iki dosyada da bulunabilir — bir projenin default_registry’si
global dosyanın bildirdiği bir girdiyi adlandırabilir — çünkü ad, tüm dosyalar ve ortam okunduktan sonra geçerli olan
girdilere karşı bir kez okunur. Ne bir girdinin adı ne de bir kayıt defteri ana makinesi olan — tek başına ya da ardından bir
depo yolu gelerek — bir değer reddedilir ve ret mesajı ikisinden birinin sorunu çözeceğini söyler. local/acme gibi ardından
bir yol gelen ad da reddedilir: bir ad, girdisinin ana makinesini temsil eder, onun altındaki bir konumu değil; bu yüzden ret
mesajı bunun yerine yazılabilecek iki yazımı belirtir — local ya da girdinin ana makinesi ve ardından yol,
127.0.0.1:5000/acme. aggrega registry remove ile bir girdiyi kaldırmak default_registry’yi yazıldığı gibi bırakır;
bu yüzden kaldırılan girdiyi adlandıran bir varsayılan bundan sonra hiçbir şeyi adlandırmaz ve yeniden yazılana kadar reddedilir.
Her katman aynı yazıma tabidir. Bir değer, bir yapılandırma dosyasından, AGGREGA_DEFAULT_REGISTRY’den ya da bir
aggrega push veya aggrega push-artifact işleminin hedefini adlandıran --registry bayrağından gelse de aynı sözlerle
reddedilir. Bu bayrak bir ana makineyi adlandırır ve yönlendirdiği yayın o ana makineye depo yolu olmadan ulaşır: yol
default_registry’ye aittir. aggrega registry add ve
aggrega config init --registry de kendilerine verilen ana makineyi bu yazıma tabi tutar; ayrıca onun yerine bir
referans kabul eder ve girdiyi referansın adlandırdığı ana makine altında anahtarlarlar. Bir dosyadan gelen ret mesajı dosyayı
ve anahtarı belirtir; ortamdan gelen değişkeni belirtir. Şema, ana makine biçimini registries[].host üzerinde bir desen olarak
belirtir, değeri herhangi bir girdinin adı olabilen default_registry üzerinde ise hiçbir desen belirtmez — bu yüzden yalnızca
şemayı okuyan bir düzenleyici yanlış yazılmış bir varsayılanı işaretlemez ve onu reddeden yapılandırma yüklemesidir.
Bir ana makine yalnızca yazımına göre değerlendirilir, bir yol da öyle. Adın çözümlenip çözümlenmediği, orada bir kayıt defterinin yanıt verip vermediği ya da yolun üzerinde var olup olmadığı yapılandırma yüklenirken denetlenmez.
Neyin neyi geçersiz kıldığı
CLI flag > environment variable > configuration file > built-in defaultBayrak, var olan en açık sinyaldir ve doğrudan kazanır. Bir ortam değişkeni, commit edilmiş dosyayı geçersiz kılar; bir pipeline’ın izlenen bir dosyayı düzenlemeden bir ayarı değiştirmesini sağlayan budur. Ayarlanmamış — ya da boş bir dizeye ayarlanmış — bir değişken, yapılandırılmış bir değeri boşaltmak yerine alttaki katmana düşer. İki dosya arasında, projenizin dosyası global olana üstün gelir.
Bir bayrak, taşıdığı değerle değil, yazılmış olmasıyla kazanır ve doğru-yanlış türündeki bir ayar için bu,
kullanılabilir bir üst katman ile hiç olmaması arasındaki farktır. --offline bu duruşu tek bir çalıştırma için açar;
--offline=false, commit edilmiş bir dosya ya da dışa aktarılmış bir değişken onu açmışken tek bir çalıştırma için kapatır.
Yalnızca değeri okuyan bir katman “kapalı” ile “belirtilmemiş”i ayırt edemezdi; bu yüzden her komut bayrağın varsayılanını
istemiş gibi görünür ve yapılandırılmış bir ayarı geri almanın hiçbir yolu olmazdı.
Tek bir makinedeki tek bir proje için modelin tamamı budur. Aşağıdaki her şey, bunun ötesine geçen projeler için vardır.
İki dosyanın ötesinde
Bu mekanizmalar daha büyük yapılar için tasarlanmıştır — ilişkili projelerden oluşan bir monorepo, kendi ayarlarını katan bir pipeline, birkaç projenin genişlettiği paylaşılan bir katalog. Birini, çözdüğü sorunla karşılaştığınızda kullanın.
Bir proje içinde birden fazla yapılandırma dosyası
Proje kökünden komutun çalıştığı dizine kadar her .aggrega-config.yaml katkıda bulunur ve daha yakın bir dosya daha uzak olanı geçersiz kılar. Böylece bir alt proje, kökün bildirdiğini tekrarlamadan onu ayarlayan kendi dosyasını taşıyabilir.
Yalnızca bir workspace: bloğu taşıyan dosya bir kökü işaretler. Böyle bir bloğu olmayan dosya yine de ayarlarına katkıda bulunur — yalnızca dizinini bir proje köküne dönüştürmez; bir alt projenin ayar dosyasının projenin nerede başladığını yeniden tanımlamasını önleyen budur.
--workspace-root geçirmek keşfi atlamanın yanı sıra bunu da değiştirir: yalnızca adlandırılan kökün kendi yapılandırma dosyası toplanır, bu yüzden onun altındaki dizinlerdeki dosyalar katkıda bulunmaz. Bu, sabitlenmiş bir kökün yapılandırmasını komut nereden çalıştırılırsa çalıştırılsın aynı tutar.
Bu şekilde toplanan her dosya proje içinden okunur. Projenin dışına çıkan bir sembolik bağlantı olan — ya da böyle bir bağlantı üzerinden ulaşılan bir dizinde bulunan — dosya okunmaz ve yapılandırmayı okuyan her komut, projeyi kalan dosyalardan yapılandırmak yerine bağlantıyı belirterek orada durur; aynısı aşağıdaki pipeline dosyası için de geçerlidir. aggrega version ve aggrega help gibi yapılandırmayı hiç okumayan birkaç komut, bağlantıyı belirten bir uyarıyla çalışır. Düzenleyicinin dil sunucusu ve bir asistanın araçları yapılandırmayı aynı şekilde okur ve böyle bir projede listelenebilmesi için yine de başlar: Release ve varlık listeleri, hiçbir şey yapılandırılmamış olarak okunup yanıt verir ve dosyayı okunmayan bağlantılar arasında belirtir; yapılandırmanın belirlediği diğer her istek ise bağlantıyı belirterek orada durur. Proje dışında tutulan bir yapılandırma, Global dosyayı açıkça adlandırma bölümünde açıklandığı gibi global dosya olarak adlandırılarak okunur. Bkz. Çalışma alanı sınırı.
Bir listeyi değiştirmek yerine genişletme
Liste değerli bir ayar diğer her ayar gibi davranır: daha yakın dosyanın değeri daha uzak olanınkinin yerini alır. Dış bir dosyanın bildirdiğini yeniden belirtmek yerine ona eklemek istediğinizde, yanındaki ekleme eşini kullanın:
| liste ayarı | ekleme eşi |
|---|---|
workspace.catalog_dirs | catalog_dirs_append |
plugins.governance | governance_append |
plugins.linter | linter_append |
plugins.importer | importer_append |
plugins.providers | providers_append |
Bir eşin altındaki girdiler, çözümlenen listeyi gölgelemek yerine her katmanda ona eklenir; böylece bir alt proje, kökün zaten bildirdiği her şeye bir linter ekler:
# <project>/services/api/.aggrega-config.yamlplugins: linter_append: - uri: ./lint/api-rules.wasmBir dosya hem temel listeyi hem de eşini ayarladığında, o dosyanın değeri temel liste ve ardından eklenen girdilerdir.
workspace: bloğu, bir eşin nereye yazılabileceği konusunda istisnadır. Bu bloğu taşıyan bir dosya kendi dizinini proje kökü olarak işaretler; bu yüzden workspace.catalog_dirs_append yazan bir alt proje dosyası, çevreleyen projeye eklemek yerine kendi projesini başlatırdı. Katalog dizini eşi, global dosyanız ile projenin kök dosyası arasında birleşir.
plugins.cli listesi dosyalar arasında kendiliğinden birleşir ve eşi yoktur: global dosyada bildirilen bir komut uzantısı komutunu her projede kaydeder, bir projede bildirilen yalnızca orada kaydeder ve ikisi birlikte kaydolur. Her girdi bir eklentiyi sabitler: çözümlediği uri ve aggrega plugin add cli komutunun doğruladığı baytların digest değeri; bu değer sha256: ve ardından 64 küçük harfli onaltılık basamak olarak yazılır. Başka bir yazımdaki özet, çözümlenen baytların karmasına asla eşit olamayacağından, dosya yüklenirken dosya ve girdi belirtilerek reddedilir.
Bir Release’e kendi katalog dizinlerini verme
Bir proje birkaç katalog varyantını yan yana tutabilir — her hedef için bir tane, her biri aynı Components’ı farklı bir sağlayıcı için işleyen Recipes’i barındırır — ve her Release’i bunlardan birine karşı derleyebilir. Her Release’i workspace.releases altında adlandırın ve ona kendi catalog_dirs listesini verin:
# <project>/.aggrega-config.yamlworkspace: releases: release-compose.yaml: catalog_dirs: - ./catalog-compose release-helm.yaml: catalog_dirs: - ./catalog-helmHer anahtar, onu adlandıran yapılandırma dosyasına göreli olarak yazılmış bir Release dosyasıdır. Bir anahtar — build.authoring_release gibi — proje dışında tutulan bir Release’i adlandırabilir ve onu burada adlandırmak, bir projenin ona ulaşma yoludur: proje içinde ona giden bir bağlantı, Çalışma alanı sınırı bölümünde açıklandığı gibi atlanmak yerine okunur. Altındaki iki anahtar, workspace: bloğundaki anlamlarını taşır ve o tek Release ile sınırlıdır:
catalog_dirs, o Release için çalışma alanının listesinin yerini alır. Arama sırası, ondan sonra okunancatalogdizini ve boş bir listenin ne anlama geldiği, çalışma alanının kendi listesiyle aynıdır.catalog_dirs_append, Release’in listesinden sonra okunur. Yalnızcacatalog_dirs_appendyazan bir girdi, çalışma alanının listesini korur ve ona ekler.
Haritanın adlandırmadığı bir Release, çalışma alanının kendi workspace.catalog_dirs’ını okur. Haritanın adlandırdığı bir Release ise nasıl derlenirse derlensin kendi dizinlerini okur — bir terminalde aggrega build ya da aggrega pull, aggrega serve üzerinden düzenleyici, aggrega mcp üzerinden bir asistan — bu yüzden hiçbiri kataloğunu bulmak için bir bayrağa ihtiyaç duymaz. Komut satırındaki bir --catalog <dir>, o tek çağrı için yine Release’in dizinlerinden önce aranır. Ve kullandığınız bir ad altında hiçbir varlık bulamayan bir arama, onu barındıran dizini listelemek için yer olarak o Release’in girdisini belirtir.
Var olmayan bir dosyayı adlandıran bir girdi, yapılandırma yüklenirken girdi ve dosya belirtilerek reddedilir. Bu nedenle bir Release’i yeniden adlandırmak, Release’in bunu belirten hiçbir şey olmadan çalışma alanının listesine karşı derlenmesine izin vermek yerine, girdi de onunla birlikte yeniden adlandırılana kadar her komutu durdurur. Bir girdinin listelediği dizin, çalışma alanının listesinin adlandırdığı dizin gibi bir dizin olmalıdır: dizin olmayan bir yol, o Release’in kataloğunu okuyan her komut tarafından girdi ve satırı belirtilerek reddedilir.
Tek bir Release’i ilgilendirmeyen şeyler yine çalışma alanının listesini okur: tüm kataloğun lint’i ya da doğrulaması, bir varlığın adla aranması, tek başına incelenen bir Aggregate ve bir düzenleyicinin çalışma alanı varlıklarını listelemesi. AGGREGA_CATALOG_DIRS çalışma alanının listesini ayarlar ve buradaki hiçbir girdiye ulaşmaz; pipeline’ınızın sahip olduğu bir yapılandırma dosyası ise haritayı hiç okumaz.
Pipeline’ınızın sahip olduğu bir yapılandırma dosyası
.aggrega-config-append-ci.yaml adlı bir dosya, taramanın ziyaret ettiği herhangi bir dizinde elle yazılmış dosyanın yanında bulunabilir. Ayrı bir dosyadır; böylece otomatik bir pipeline, bir kişinin yazdığına hiç dokunmadan ona sahip olabilir ve onu tümüyle üzerine yazabilir.
Yalnızca eklemelidir. Yukarıdaki beş liste ayarı için girdileri çözümlenen listelere eklenir; hiçbir şeyi kaldıramaz ya da bir skaler değeri geçersiz kılamaz. İçine yazılan bir skaler ya da harita anahtarının eklemeli bir anlamı yoktur; bu yüzden sessizce uygulanmak yerine yok sayılır ve bir uyarıda belirtilir. Ayrıca asla bir proje kökünü işaretlemez; bu yüzden bir dizine böyle bir dosya bırakmak, projenin başladığı yeri değiştirmeden eklentiler ekler.
Göreli bir yolun gösterdiği yer
Göreli bir dosya sistemi yolu, onu bildiren dosyanın dizinine göre çözümlenir; proje köküne göre de, komutu çalıştırdığınız dizine göre de değil. Bu, iki kez okunmaya değer kuraldır; çünkü projeye göreli görünen bir yol başka bir yere çözümlenir ve derleme yine de, kastetmediğiniz içerikle başarılı olur.
Kural workspace.catalog_dirs için, workspace.releases altında anahtar olarak verilen Release dosyaları ve her girdinin listelediği dizinler için, bir plugins.governance ya da plugins.linter eklentisindeki yerel dosya sistemi yolları için (diskteki bir .wasm dosyasını adlandıran bir uri ve o eklentinin with.sources altındaki her girdi) ve bir plugins.importer eklentisinin with.sources altındaki her girdi için geçerlidir. Üç listenin hepsinde, iki nokta içermeyen ve hiçbir kayıt defterini adlandırmayan bir uri (./lint/api-rules.wasm kadar importer/agent-flows da) böyle bir yoldur; bir eklentiyi kimliğiyle adlandıran bir uri ise sürümü iki noktadan sonra taşır, importer/agent-flows:1.2.0, ve tam yazıldığı gibi bırakılır. Bir importer eklentisinin uri değeri, Bir kaynağı hangi importer taslaklara dönüştürür bölümünde anlatıldığı gibi, eklediği importer’ı adlandırır; bir içe aktarma, oraya yazılmış bir yoldan modül okumaz.
Kural, ekleme eşlerinin altındaki girdilere de uygulanır ve bunların her biri, birleştirmenin sona erdiği dosyaya değil kendi bildiren dosyasına bağlanır. Ayrıca mcp.tls.cert_file, mcp.tls.key_file ve
mcp.authorization.jwks_file için de geçerlidir; böylece onu adlandıran dosyanın yanındaki bir dosya, sunucu nereden başlatılırsa başlatılsın bulunur.
Dolayısıyla şu düzen verildiğinde:
myproject/├── .aggrega-config.yaml└── services/ ├── .aggrega-config.yaml └── catalog/ve ./catalog kök dosyaya yazıldığında, yol myproject/catalog dizinini adlandırır. services/.aggrega-config.yaml içine yazıldığında aynı metin myproject/services/catalog dizinini adlandırır. Mutlak bir yol tam yazıldığı gibi bırakılır; oci://hub.aggrega.ai/plugins/helm:1.0.0 gibi bir kayıt defteri başvurusu da öyle.
Şu ayarlar bu kurala bilerek uymaz; çünkü bağlanacakları bir bildiren dosyaları yoktur ya da onları okuyan herkes onları başka bir yere göre çözümler:
artifact_cache_dir, komut nereden çalışırsa çalışsın proje köküne göre yorumlanır; böylece önbellek, her çağrı konumu için ayrı bir dizin değil tek bir dizin olur. Mutlak bir değer, yapılandırma yüklenirken reddedilir.AGGREGA_CATALOG_DIRSortamdan gelir ve hiçbir bildiren dosyası yoktur; bu nedenle içinde mutlak yollar verin.mcp.listentam yazıldığı gibi alınır ve bunaunix:<path>biçimindeki dosya sistemi yolu da dahildir. Aynı adres, bildiren dosyası olmayanaggrega mcp --listenüzerinden de gelir; bu yüzden yalnızca yapılandırılmış yazımı bağlamak, tek bir dizenin nereden geldiğine göre iki farklı yeri adlandırmasına yol açardı. Sokete mutlak bir yol verin.
Deposu paylaşılan tek ayar
Hemen her ayar, üzerinde çalıştığınız projeye ait bir şeyi yönetir: katalog içeriğini hangi dizinler üzerinden çözümlediğini, hedeflerini hangi eklentilerin işlediğini, içeriğinin ne kadar sıkı değerlendirildiğini, daemon’un bellek içi önbelleklerinin ne kadar büyüyebileceğini. Bir projenin dosyasındaki değer o projenin kendi şeyini yönetir ve dikkat edilecek bir şey yoktur.
compiled_module_cache.max_bytes tek istisnadır, çünkü sınırladığı şey projeye özgü değildir. Derlenmiş eklenti kodu, makinenizdeki her projenin yeniden kullandığı tek bir dizinde tutulur; böylece bir eklenti her proje için ayrı ayrı değil bir kez derlenir. Sınırın kendisi diğer her ayar gibi çözümlenir (bir projenin dosyasına yazın, o proje için o değer geçerli olur), ancak deponun yine tek bir boyutu vardır ve yürürlükteki boyut en son derlemeden gelendir. Sınırı farklı belirleyen iki proje sırayla etkili olur ve düşük sınır, diğer projenin bedelini ödediği derlenmiş kodu atar.
Bu nedenle, derlediğiniz her şey için tek bir yanıt istediğinizde onu genel dosyaya koyun ve tek bir derlemenin derlediğinin üzerinde tutun. aggrega cache status deponun o anda ne tuttuğunu bildirir; aggrega config show --origin ise altında çalıştığınız sınırın gerçekte hangi dosyadan geldiğini söyler.
Başkalarının eriştiği bir sunucu için ayarlar
aggrega mcp, Model Context Protocol’ü konuşur. Kendi makinenizde bir istemci onu bir alt süreç olarak başlatır ve onunla standart giriş ve çıkış üzerinden konuşur; varsayılan budur ve bu biçimin okuduğu tek ayarlar, o varsayılanda bırakılan mcp.transport ile mcp.announce_tools ayarlarıdır. mcp bloğunun geri kalanı, mcp.transport: http ile seçilen diğer biçim içindir: bir ana makinede uzun süre çalışan, klavyesinin başında olmayan çağıranların HTTP üzerinden eriştiği tek bir süreç.
# <project>/.aggrega-config.yamlmcp: transport: http listen: 127.0.0.1:7777 authorization: issuer: https://login.example.com resource: https://mcp.example.com/mcp allowed_origins: - https://studio.example.com limits: max_concurrent_requests: 32 deny_reach: - registry announce_tools: - list-entities - get-schema - validate - build health: listen: 127.0.0.1:7778Aktarımı seçen mcp.transport ayarıdır. http bir dinleyici başlatır; varsayılan olan stdio ise standart giriş ve çıkış üzerinden konuşur, bir alt süreç istemcisinin beklediği de budur. Başka herhangi bir değer, bu dosya yüklenirken reddedilir. aggrega mcp --transport <stdio|http> aynı işi tek bir çağrı için yapar ve her bayrağın her dosyaya üstün gelmesi gibi anahtara üstün gelir.
mcp.listen o dinleyicinin nereye bağlanacağını adlandırır ve hiçbir şey seçmez. Ona bir host:port adresi ya da bir unix:<path> soketi verin; aggrega mcp --listen <address> tek bir çağrı için ona üstün gelir. http seçiliyken ikisinden de adres gelmezse, başlatma hiçbir şey bağlanmadan önce reddedilir. stdio seçiliyken yazılmış bir --listen reddedilir ve yalnızca bu anahtarın adlandırdığı bir adres kullanılmadan bırakılır; sunucu bunu hata akışında, bu dosyayı ve mcp.transport: http ayarını adlandıran tek bir satırla bildirir. Dolayısıyla başkalarının eriştiği bir sunucu, yukarıdaki gibi iki anahtarı da ayarlar ve o dosyanın kapsadığı bir dizinden başlatılan bir istemci sunucuya yine kendi akışları üzerinden erişir. Bir unix: yolu bağlanmak yerine yazıldığı gibi alınır; bkz. Göreli bir yolun gösterdiği yer.
mcp.tls.cert_file ve mcp.tls.key_file, TLS’i sürecin içine koyar. İkisini de ayarlayın, dinleyici HTTPS’i kendisi sunar. İkisini de dışarıda bırakın, düz metin sunar; bu yalnızca loopback üzerinde ya da bir Unix soketinde kabul edilir: öndeki bir proxy’nin sertifikayı tuttuğu ve sürece ilettiği durumda kullandığınız biçim budur. Başka herhangi bir adresteki düz metin dinleyici, bu iki anahtarı adlandırarak hiçbir şey bağlanmadan önce reddedilir; ikisinden yalnızca biri ayarlanmışsa da öyle. İkisi de dosya sistemi yoludur ve yukarıdaki kurala uyar: göreli olan, onu bildiren dosyanın dizinine göre çözümlenir; böylece o dosyanın yanına commit edilmiş bir sertifika, sunucu nereden başlatılırsa başlatılsın bulunur. Sertifikanın proje dışında yönetildiği yerde onları mutlak yazın.
mcp.authorization.issuer ve mcp.authorization.resource, çağıranların sunduğu belirteçleri kimin verdiğini ve bu sunucunun, belirteçlerin verildiği kaynak olarak nasıl adlandırıldığını belirtir. http aktarımı seçildiğinde ikisi de zorunludur ve bunlar olmadan bir dinleyici, herhangi bir şey bağlanmadan önce reddedilir; çünkü uç noktaya yapılan her istek bir bearer-token sınamasıyla yanıtlanır ve gidilecek hiçbir yeri adlandırmayan bir sınama, istemcinin üzerine işlem yapamayacağı bir sınamadır. Adresleri şema ve ana makine dahil eksiksiz yazın: issuer’ı tam olarak o yetkilendirme sunucusunun kendi tanımlayıcısını belirttiği gibi, resource’u ise çağıranlarınızın gerçekte ulaştığı adres olarak; önde bir proxy varsa bu, sürecin bağlandığı adres değil, o proxy’nin sunduğu ana makinedir. İkisi de dinleyicinin sunduğu OAuth korumalı kaynak meta veri belgesinde, hiçbir kimlik bilgisi istenmeden yayımlanır; bir istemci belirteci nereden alacağını öğrenmek için buraya bakar. Hiçbiri gizli bir şey içermez: belirteç, onu sunan istekle gelir ve hiçbir zaman bir yapılandırma dosyasına yazılmaz. Yetkilendirme sunucusu bu makinede (localhost, 127.0.0.1 veya ::1) çalışmadığı sürece issuer bir https adresidir; başka herhangi bir ana makinede düz bir http issuer’ı adlandıran bir dinleyici, anahtarlarını ve çağıranlarını hangi yolla okursa okusun, herhangi bir şey bağlanmadan önce reddedilir: her istemci belirtecini almak için issuer’a gönderilir, dolayısıyla düz http üzerinden yetkilendirme kodu ve belirteci ağı korumasız geçer; anahtarların da oradan okunduğu durumda ise o yol üzerinde bulunan herkes bunları değiştirebilir.
mcp.authorization.jwks_file, belirteçlerin doğrulandığı anahtarları içeren bir dosyayı adlandırır; anahtarlar yetkilendirme sunucusundan okunmaz. Bunu belirtmezseniz sunucu, o sunucunun meta verilerini bilinen (well-known) adresinden okur ve orada yayımlanan jwks_uri’yi izler; ağ erişimi olan bir çalışma alanı bunu yapar. Bu anahtar adresi de issuer ile aynı kurala tabidir; iki okumadan birinin yönlendirildiği her adres de öyle: başka bir ana makinedeki düz http adresine hiçbir zaman istek yapılmaz ve bu anahtarlara ihtiyaç duyan bir belirteç, yetkilendirme sunucusu meta verilerini ve anahtarlarını https üzerinden yayımlayana kadar 503 ile yanıtlanır. Bunu ayarlarsanız yetkilendirme sunucusuyla hiçbir zaman iletişim kurulmaz; offline: true bildiren bir çalışma alanının ihtiyacı budur ve böyle bir çalışma alanı, bu anahtar bir dosya adlandırmadıkça dinleyicisi bağlanmadan önce reddedilir. Bu bir yoldur ve yukarıdaki kurala uyar: göreli bir yol, onu bildiren dosyanın dizinine göre çözümlenir; böylece o dosyanın yanına işlenmiş bir anahtar kümesi, sunucu nereden başlatılırsa başlatılsın bulunur. Dosya, bir yetkilendirme sunucusunun yayımladığı türden ortak doğrulama anahtarlarını içerir; imzalayan hiçbir şey ve gizli hiçbir şey içermez.
mcp.allowed_origins yalnızca bir istek Origin başlığı taşıdığında dikkate alınır; bu pratikte isteği bir tarayıcının gönderdiği anlamına gelir. Sunduğunuz origin’leri burada listeleyin; listede olmayan bir origin’i adlandıran istek reddedilir, böyle bir başlık taşımayan istek ise her durumda sunulur. Tarayıcı olmayan bir istemci böyle bir başlık göndermez ve bir girdiye ihtiyaç duymaz. Bir girdi başlıkla birebir karşılaştırılır; bu yüzden onu bir tarayıcının gönderdiği biçimde yazın: küçük harfli bir şema, ://, küçük harfli bir ana makine ve yalnızca bağlantı noktası şemanın varsayılanı olmadığında bağlantı noktasıyla birlikte : (https://studio.example.com ya da kendi makinenizde sunulan bir sayfa için http://localhost:3000); yol ve sonda / olmadan. Başka herhangi bir biçimdeki girdi hiçbir zaman eşleşemez ve bu dosya yüklenirken, girdi adlandırılarak reddedilir.
mcp.limits, bir çağıranın neler isteyebileceğini sınırlar: tek bir istek gövdesinin ne kadar büyük olabileceğini, aynı anda kaç isteğin çalışacağını ve bir çağıranın bir dakikada kaç istek gönderebileceğini. Üçü de her zaman yürürlüktedir; hiçbirinin onu kaldıran bir değeri yoktur. Üçüncüsü olan requests_per_minute, her çağıran için ayrı sayılır; bu nedenle yoğun istek gönderen bir çağıran diğerine hiçbir şey kaybettirmez.
mcp.authorization.trusted_proxy, burada bir belirteç denetlemek yerine çağıranı öndeki bir proxy’den okur. principal_header’ı o proxy’nin çağıranın kim olduğunu söylemek için kullandığı başlığa, isteğe bağlı olarak scopes_header’ı da o çağıranın kapsamlarını taşıyan başlığa ayarlayın. İkisi de X-Forwarded-User gibi HTTP başlık adlarıdır: harfler, rakamlar, kısa çizgiler ve bir başlık adının taşıyabileceği diğer birkaç karakter; boşluk veya iki nokta içermez. Başka herhangi bir biçimdeki ad, hiçbir istek onu taşıyamayacağı için bu dosya yüklenirken anahtar adlandırılarak reddedilir. Bu kipte hiçbir belirteç okunmaz ve principal başlığı olmayan bir istek reddedilir. Bu durumda başlık kimlik bilgisinin tamamı olduğundan, yalnızca onu başka hiçbir şeyin ayarlayamadığı yerde güvenilirdir: mcp.listen loopback ya da bir Unix soketi olmadıkça süreç bağlanmadan önce reddedilir. Bloğu belirtmezseniz bu sunucu belirteçleri kendisi denetler; varsayılan budur. principal_header’ı boş olan bir blok o varsayılan olarak okunmaz, reddedilir.
mcp.deny_reach, bu dağıtımdan bir erişim türünü geri çeker. Sunucunun gerçekleştirdiği her işlem, kendi etkilerinin ne kadar uzağa ulaştığını bildirir: okuyan ya da işleyen ve arkasında hiçbir şey bırakmayan işlem için none, bu sürecin hizmet verdiği çalışma alanının içine yazan işlem için workspace, yayımlayan, imzalayan ya da geri çeken işlem için registry ve ana makinedeki tüm çalışma alanlarının paylaştığı şeyi değiştiren işlem için machine. Burada bir türü adlandırmak, ona ulaşan her aracı geri çeker: araç, çağıranın belirteci ne taşırsa taşısın her çağıranın araç listesinde yer almaz ve ona yapılan bir çağrı bu ayar adlandırılarak reddedilir. Bu, onu çağıranın değil dağıtımın sınırı yapar ve hiçbir kimlik bilgisi onu kaldırmaz: yalnızca okuma sunmak için tasarlanmış bir sunucu, üç yazma türünü burada listeler ve ardından belirteci her kapsamı taşıyan bir çağıran için bile yayımlama yapamaz. Bunu belirtmezseniz (varsayılan budur) bu dağıtım, çağıranlarının kapsamlarının izin verdiği her şeyi taşır. Dördünden biri olmayan bir değer atlanmaz, bu dosya yüklenirken reddedilir. Bu ayar ne derse desin machine türünden hiçbir şey HTTP üzerinden sunulmaz; bu yüzden onu adlandırmak kabul edilir ve hiçbir şeyi değiştirmez; türleri ve onlara izin veren kapsamları aggrega-mcp.md açıklar.
mcp.announce_tools, sunucunun duyurduklarını daraltır ve yukarıdaki anahtardan farklı bir sınırdır. Bu sunucunun duyuracağı araçları, araç listesinin bildirdiği yazımla adlandırın; tam olarak bunlar duyurulur: dışarıda bırakılan bir araç her çağıranın araç listesinde yer almaz ve yine de adıyla çağrılırsa bu ayar adlandırılarak reddedilir. Anahtarı belirtmezseniz (varsayılan budur) sunucunun taşıdığı her araç duyurulur; boş bir liste yazarsanız hiçbiri duyurulmaz; dolayısıyla bu iki yazım farklı ifadelerdir ve sizin yerinize hiçbir varsayılan doldurulmaz. Onu deny_reach’ten ayıran, her birinin neyi elinden aldığıdır. deny_reach bir yeteneği elinden alır: geri çekilmiş bir türün işlemleri burada hiç taşınmaz ve hiçbir kimlik bilgisi birini geri getirmez. announce_tools yalnızca bir duyuruyu elinden alır (dışarıda bıraktığı araçlar sunucunun hâlâ sahip olduğu yeteneklerdir) ve yanıt verdiği şey, kaydedeceği araç sayısını, bazen bağlı olduğu tüm sunucular genelinde aynı anda sınırlayan bir istemcidir. İkisi de ayarlandığında geri çekme kazanır; bu nedenle geri çekilmiş bir türün aracı, bu anahtar onu nasıl adlandırırsa adlandırsın görünmez kalır. Hiçbir aracın karşılık gelmediği bir ad, sizi istediğinizden daha dar bir yüzeyle bırakmak yerine sunucuyu herhangi bir şey sunmadan önce durdurur ve sahip olduğu araçları listeler. Buradaki, http aktarımının başlattığı dinleyiciyi yapılandıran diğer anahtarların aksine, bu anahtar sunucu hangi aktarımı konuşursa konuşsun okunur; çünkü daraltmanın var olduğu istemci genellikle süreci kendi standart girdisi ve çıktısı üzerinden başlatan istemcidir; geri kalanını aggrega-mcp.md açıklar.
mcp.health.listen, canlılık ve hazırlık denetimlerini kendilerine ait bir adrese yerleştirir. Ona mcp.listen’in iki biçiminden birinde bir adres verin; ikinci bir dinleyici orada GET /healthz isteğini — süreç çalıştığı andan itibaren 200 ile — ve GET /readyz isteğini — çalışma alanı çözümlenip uç nokta bağlanana kadar 503, o andan sonra 200 ile — yanıtlar; bu da bir yük dengeleyicinin, süreç bir çağrıyı gerçekten yanıtlayabilene kadar trafiği bekletmesini sağlar. Bunu belirtmezseniz denetimlerden hiçbiri hiçbir yerde yanıtlanmaz. Bu denetimler mcp.listen’in adlandırdığı adreste asla yanıtlanmaz; o adres, sunmadığı her yola verdiği 404 yanıtını bunlara da verir: orada bir yoklama, diğer her şeyi reddeden bir dinleyicinin kimlik doğrulamasız okunması olurdu. mcp.listen’den farklı olarak bu adres sınırlandırılmamıştır ve onun için hiçbir adres reddedilmez — bunu, bu sürecin yanındaki bir denetleyicinin eriştiği yer olan loopback’e veya bir Unix soketine yönlendirin ve seçtiğiniz adrese erişebilen her şeyin bu iki yanıtı okuyabileceğini göz önünde bulundurun.
schema/other/aggrega-config.md, bu anahtarların her birini, varsa varsayılan değeriyle birlikte belirtir.
Proje kökünün tanınmasının diğer yolları
--workspace-root <path> ya da onun karşılığı olan AGGREGA_WORKSPACE_ROOT, kökü doğrudan adlandırır ve keşfi atlar. Adlandırdığı klasör var olmalıdır: hiçbir şeyi adlandırmayan ya da bir dosyayı adlandıran bir yol, komut başka herhangi bir şey yapmadan önce reddedilir ve ret, değeri ikisinden hangisinin sağladığını belirtir ve değeri verildiği gibi aktarır. Aksi halde keşif çalışma dizininden yukarı doğru ilerler ve bağlantı noktası türleri yakınlığa göre değil, birbirlerine göre sıralanır:
workspace:bloğu taşıyan bir.aggrega-config.yamldoğrudan kazanır, hangi derinlikte bulunursa bulunsun. İlerleme, aşağıdaki türden bir işaretçiyi geçtikten sonra bile böyle bir dosya aramak için yukarı çıkmayı sürdürür; böylece yukarıda açıkça işaretlenmiş bir kök, altındaki rastlantısal bir işaretçiyi her zaman yener.- Bu olmazsa, bu işaretçilerden en yakını kökü belirler ve tek bir dizin içinde şu sırayla
sıralanırlar: bir
.aggrega/dizini, ardından biraggregate*.yaml, ardından birrelease*.yaml, ardından birmanifest*.yaml. - Hiçbiri yoksa çalışma dizini kullanılır — komutlar başlamayı reddetmek yerine çalışır. Sonucu çalışma alanına bağlı olan bir komut — çalışma alanının belgelerini okuyan ya da yazan, yapıt önbelleğini okuyan ya da dolduran veya onu sunan bir komut — standart hataya bir kez uyarı verir:
warning: <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace. Sonucu hangi klasörün kök olduğuna bağlı olmayan bir komut, yapılandırmayı okuduğu durumda bile hiçbir şey söylemez:aggrega version,aggrega config show,aggrega plugin list,aggrega registry list,aggrega explainveaggrega loginbunlar arasındadır. İşi çalışma alanının kendi yapılandırma dosyasını yazmak olanaggrega config capture, böyle bir klasörde hiçbir şey yazmaz ve bunu belirten bir hatayla çıkar.
Böyle bir klasörde bir yapıt önbelleğine hiçbir şey yazılmaz. Bir .aggrega/ dizini kendisi de yukarıdaki işaretçilerden biridir; bu yüzden oraya yazılan bir önbellek, içinde bir zamanlar bir şey getirildiği için klasörü bir çalışma alanına dönüştürürdü. İşi önbelleği dolduran bir komut — aggrega pull, önce bağımlılıklarını çözümleyen bir derleme, aggrega registry update, bir kayıt defterinden bir komut uzantısı eklentisi eklemek — herhangi bir şey getirmeden önce reddedilir; ret, klasörü ve iki çıkış yolunu belirtir: çalışma alanını --workspace-root ya da AGGREGA_WORKSPACE_ROOT ile adlandırmak veya klasöre workspace: bloğu taşıyan bir .aggrega-config.yaml vermek. aggrega pin ile, yanındaki entity.lock’un kaydettiği sabitlemelere bağlı olan bir Recipe ya da FeatureRecipe için aggrega push, önbelleği yalnızca varlığın tam olarak yazdığı ve birini sabitlemenin ya da sabitlemesini karşılaştırmanın getirdiği uzak kaynaklarla doldurur: böyle bir kaynağı getirecekleri yerde, onu getirmeden önce aynı şekilde reddedilirler. Böyle bir kaynağı olmayan bir varlık — hiç kaynağı olmayan, yerel bir kaynağı olan ya da koordinatlarını her Release’in doldurduğu bir kaynağı olan — orada da her yerde olduğu gibi sabitlenir veya yayımlanır. Orada bir derleme reddedilmez, ancak kilit dosyasının sabitlediği ve önbelleğin artık tutmadığı bir dış girdi, onarmak için yeniden getirilmez: işleme, o girdinin yerine aynı cümle, çevrimdışı duruşunkinin iletildiği şekilde iletilir ve işleme bunu raporlar. artifact_cache_dir’in önbelleği nereye koyduğu burada hiçbir şeyi değiştirmez, çünkü dizin bulunan kök hangisiyse ona eklenir. Yalnızca okuyan komutlar yine yanıt verir.
Bu son geri dönüşün bir istisnası vardır. Kökü hiçbir şey adlandırmadığında ve çalışma dizini hiçbir şeyi belirlemediğinde, bir Release ya da bir varlık belgesi hakkında olup o dosyayı mutlak bir yolla adlandıran bir komut, dosyanın bulunduğu klasörden yukarı doğru ilerleyerek kökü yeniden keşfeder ve ne bulursa onu kullanır: dosyanın ait olduğu çalışma alanını ya da hiçbiri olmazsa o klasörü. Dosya, aggrega build ve aggrega pull üzerinde --release’in adlandırdığı dosyadır; aggrega validate, aggrega lint ve aggrega inspect’e verilen Release ya da bu olmazsa onlara verilen dosyadır; ve aggrega pin, aggrega push ve aggrega edit-document’e verilen belgedir. Böylece bir projenin projenin dışından derlenen Release’i, komut projenin içinde çalıştığında olduğu gibi projenin kendi yapılandırmasını okur ve komutun yazdırdığı yapılandırma uyarıları o çalışma alanına aittir. Dosyanın kendi klasörü de hiçbir şeyi belirlemediğinde, komutun bildiriminin adlandırdığı ve hiçbir önbelleğin yazılmadığı klasör odur. Göreli bir yol, komutu çalıştırdığınız dizine göre okunur ve hiçbir şeyi değiştirmez; adlandırılmış bir kök ya da kendisi bir çalışma alanının içinde olan bir çalışma dizini olduğu gibi kullanılır.
Asistan sunucusu, Release’ini ya da belgesini mutlak bir yolla adlandıran bir çağrıya aynı kuralı uygular.
Kökü bir workspace: bloğuyla işaretlemek açık seçimdir ve tercih edilecek olandır; dosya ve dizin işaretçileri, bunu bildirmemiş bir projenin de derlenebilmesini sağlar.
Genel dosyayı açıkça adlandırmak
Genel katman şu sırayla çözümlenir:
--config <path>, çağrı başına biçim.AGGREGA_CONFIGortam değişkeni.- Varsayılan konum: Windows’ta
APPDATAortam değişkeninin adlandırdığı dizin içindekiaggrega\config.yaml, diğer platformlarda iseXDG_CONFIG_HOME’un adlandırdığı dizin içindekiaggrega/config.yaml; bu yoksa~/.config/aggrega/config.yaml.
İlk ikisi açık bir dosyayı adlandırır; bu yüzden var olmayan bir yol sessiz bir geri dönüş değil, belirgin bir hatadır — belirli bir dosya istediniz. Yapılandırmasını okuyan bir komut, yolla biten tek bir cümleyle durur; böylece yolu kopyalayabilirsiniz. aggrega config init istisnadır, çünkü o
dosyayı oluşturmak tam da onun amacıdır: adlandırılan dosyayı oluşturur ve bunu bildirir. Varsayılan konum, dosya oradaysa yüklenir, değilse sessizce geçilir. Hangi dosya çözümlenirse çözümlensin, projenizin dosyaları yine onun üzerine katmanlanır.
Bunların hiçbiri çözümlenmediğinde — hiçbir dosya adlandırılmadığında ve varsayılan konumun okunduğu değişkenler ayarlanmadığında — genel dosyaya yazan bir komut durur ve neyin ayarlanacağını belirtir. Ortam değişkenleri, her platform için her konumun okunduğu değişkenleri listeler.
Bu seçim, yapılandırma yazan bir komutun nereye yazacağını da belirler. --config <path> ile çalıştırılan bir komut yapılandırmasını o dosyadan okur ve değişikliğini aynı dosyaya uygular; böylece bir komutun yazdığı, bir sonrakinin geri okuduğudur.
Bir komutun varsayılan olarak iki dosyadan hangisine yazacağı ayarın niteliğinden gelir: kayıt defteri gibi makine genelindeki araçlar genel dosyaya gider; provider bağlaması veya soket eklemesi gibi derlemeye katılan ayarlar ise projenin kayıtlı dosyasına gider, böylece projeyle birlikte taşınırlar. Geçersiz kılmak için --global ya da --workspace geçirin; komut yazdığı dosyayı yazdırır.
Ayrıca bakınız
- aggrega-config.md — yapılandırmayı başlatan, inceleyen ve
donduran
aggrega configkomutları. - environment-variables.md —
AGGREGA_önekli her değişken ve gizli bilgilerin nerede sağlandığı. - global-flags.md —
--config,--workspace-rootve her alt komutun kabul ettiği diğer bayraklar. - schema/other/aggrega-config.md — her yapılandırma anahtarı, türü ve varsayılan değeri.
- aggrega-cache.md —
artifact_cache_dir’in gerçekte ne tuttuğu. - workspace-boundary.md — hangi yolların çalışma alanının içinde kaldığı ve bu yapılandırmanın adlandırdığı dizin ve dosyaların onun dışına nasıl ulaştığı.
- aggrega-mcp.md —
mcpbloğunun yapılandırdığı sunucu.