Konfigurasi
Dari mana aggrega membaca pengaturannya, dan di file mana suatu pengaturan harus diletakkan.
Kasus sederhana
Dua file, dan sebagian besar proyek tidak memerlukan apa pun selain itu.
Satu file di proyek Anda, bernama .aggrega-config.yaml, yang berada di root proyek. File ini memuat
cara proyek ini dibangun: direktori mana yang memuat konten katalog yang di-vendor, plugin mana yang merender
target mana, aturan lint mana yang dilonggarkan, dan ke mana cache lokal disimpan. File ini di-commit, sehingga
rekan tim yang meng-clone proyek membangunnya dengan cara yang sama.
Blok workspace: di dalamnya adalah penanda bahwa direktori tersebut adalah root proyek:
# <project>/.aggrega-config.yamlworkspace: catalog_dirs: - ./catalogauto_pull: trueBlok ini hanya memuat direktori katalog yang mendefinisikan root; setiap pengaturan lain berada di tingkat
atas di sampingnya. Proyek yang tidak me-vendor konten katalog apa pun tetap menulis blok ini, kosong —
workspace: {} — karena keberadaan blok itulah penandanya.
Satu file global di mesin Anda, di ~/.config/aggrega/config.yaml — di Windows, di
aggrega\config.yaml di dalam direktori yang ditunjuk oleh variabel lingkungan APPDATA. Setiap workspace
di mesin tersebut di-resolve melaluinya, dan file ini memuat
pengaturan yang menjadi milik mesin, bukan milik satu
proyek tertentu — registry tempat Anda melakukan pull beserta kebijakan kepercayaan tanda tangan untuk masing-masing, seberapa besar
penyimpanan modul terkompilasi boleh tumbuh, dan plugin ekstensi perintah apa pun yang telah Anda instal. Semua itu
sama di mana pun Anda bekerja, sehingga mendeklarasikannya sekali saja adalah tujuannya. File ini dimuat secara otomatis jika
ada, dan tidak ada yang rusak jika tidak ada.
registries: - host: hub.aggrega.ai signing: required: trueaggrega config init menulis file global tersebut untuk Anda, mendaftarkan sebuah registry bersama
kebijakan kepercayaan tanda tangan yang diiklankannya, dan memberi tahu lokasi file di mesin Anda serta lokasi
penyimpanan cache seluruh mesin. aggrega config show mencetak apa yang berlaku saat ini, dan
aggrega config show --origin memberi tahu file mana — atau variabel lingkungan mana — yang menentukan setiap
pengaturan.
Rahasia bukanlah konfigurasi. Kata sandi registry dan token identitas penandatanganan tidak pernah menjadi field di kedua file; keduanya diberikan melalui variabel lingkungan atau flag pada saat dibutuhkan. Lihat environment-variables.md.
Dari mana entitas lokal dibaca
Proyek yang menyimpan konten katalognya sendiri — sebuah Component, Feature, Recipe, atau salah satu jenis library — memiliki dua cara untuk menyatakan lokasi konten tersebut, dan cara pertama sama sekali tidak memerlukan konfigurasi.
Direktori catalog di root proyek dibaca baik ada maupun tidak ada yang menyebutnya. Letakkan
sebuah entitas di bawah <project>/catalog/ dan setiap perintah yang memuat katalog akan membacanya, termasuk di
proyek yang blok workspace:-nya kosong. Direktori katalog dibaca secara rekursif, sehingga cara Anda
menyusun subdirektori di dalamnya terserah Anda.
Direktori yang dicantumkan di bawah workspace.catalog_dirs juga dibaca, dan dibaca lebih dulu.
Daftar ini adalah tumpukan pencarian berurutan: direktori pertama yang mendeklarasikan sebuah identitas memilikinya, dan
identitas yang sama di direktori berikutnya akan tertutupi (shadowed). catalog dibaca setelah semua yang dicantumkan — kecuali
jika direktori yang dicantumkan sudah memuatnya, dalam hal ini ia dibaca sebagai bagian dari direktori tersebut — sehingga
mencantumkan direktori menambah apa yang sudah ada alih-alih menggantikannya. --catalog <dir> yang dapat diulang
di baris perintah dibaca sebelum keduanya, dan path relatif yang diberikan di sana di-resolve terhadap
direktori tempat Anda menjalankan perintah, karena tidak ada file konfigurasi yang mendeklarasikannya. Direktori yang disebut lebih
dari sekali — di baris perintah dan di daftar, atau dua kali di daftar — dibaca sekali, di tempat ia
pertama kali disebut, sehingga tidak ada isinya yang dilaporkan tertutupi oleh dirinya sendiri: shadow selalu berupa dua file
berbeda yang mendeklarasikan satu identitas. Dua penulisan dari satu direktori, path menuju direktori itu melalui link, dan — pada
sistem file yang mengabaikan huruf besar-kecil — penulisan dengan huruf berbeda semuanya menunjuk direktori yang sama. Direktori
di dalam direktori lain yang dicantumkan tetap dibaca sebagai entri tersendiri. Proyek yang menyimpan
varian katalog per Release dapat memberi setiap Release daftarnya sendiri — lihat
Memberi Release direktori katalognya sendiri.
Mencantumkan direktori adalah cara proyek membaca entitas yang disimpan di luarnya. Direktori yang dicantumkan dapat berada di mana saja — checkout yang bersebelahan, direktori yang dibagi dengan proyek lain — dan dibaca di tempatnya, bahkan ketika direktori itu sendiri adalah symbolic link. Tidak ada hal lain yang menjangkau sejauh itu: link di dalam proyek yang mengarah ke tempat lain tidak diikuti, dan dokumen yang menyebut file di luar proyek melalui path ditolak, sehingga entitas yang disimpan di tempat lain dijangkau dengan mencantumkan direktori yang memuatnya dan menyebut entitas itu dengan namanya. Direktori yang dicantumkan di luar proyek adalah root tersendiri, sehingga link di bawahnya yang mengarah keluar darinya juga tidak dibaca. Batas workspace menyatakan aturan lengkapnya.
Direktori yang dicantumkan harus berupa direktori. Path yang dicantumkan tempat tidak ada apa pun, atau tempat terdapat file atau tautan yang tidak mengarah ke mana pun, ditolak sebelum apa pun dibaca atau ditulis oleh setiap perintah yang membaca katalog — pull, build, validasi, inspeksi, lint, serta operasi yang sama yang dijalankan dari editor melalui aggrega serve atau dari asisten melalui aggrega mcp — sehingga build tidak pernah berjalan dengan katalog yang lebih sedikit daripada yang Anda cantumkan. Penolakan menyebutkan entri sebagaimana ditulis, path tempat entri itu di-resolve, file konfigurasi dan baris yang mencantumkannya, serta daftar tempat entri itu berada:
<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 invalidBuat direktori tersebut, atau hapus entrinya: salinan proyek yang diambil tanpa checkout bersebelahan yang dicantumkannya menghapus entri itu, dan me-resolve dari registry apa yang akan disediakan checkout tersebut. Hal yang sama berlaku untuk direktori yang dicantumkan oleh entri milik Release, untuk direktori yang ditambahkan oleh file konfigurasi milik pipeline Anda atau oleh file global, dan untuk direktori yang dibawa AGGREGA_CATALOG_DIRS, yang disebutkan penolakan sebagai ganti file. Konfigurasi itu sendiri tetap dimuat, sehingga perintah yang tidak membaca katalog apa pun tetap berjalan. Direktori --catalog yang tidak ada diketik untuk satu perintah, dan aggrega build menolaknya dengan menyebutkan direktori tersebut. Direktori yang dicantumkan yang ada tetapi tidak dapat dibaca ditolak oleh perintah yang memuat seluruh katalog, dengan menyebutkannya.
Menulis daftar sebagai kosong menyatakan bahwa proyek ini sama sekali tidak memiliki katalog lokal, dan itulah satu-satunya
penulisan yang juga menghentikan pembacaan catalog:
# <project>/.aggrega-config.yamlworkspace: catalog_dirs: []Menghilangkan key tersebut adalah pernyataan yang berbeda: daftar yang dihilangkan adalah kasus biasa, dan catalog
tetap dibaca.
Build, pull, validasi, atau aggrega inspect yang tidak menemukan entitas dengan nama yang Anda gunakan memberi tahu dari mana proyek ini membaca entitas lokal dan apa yang perlu diubah agar entitas yang Anda sebut dibaca. Pesan semacam itu tidak diberikan jika Anda menulis daftar kosong — tidak membaca katalog lokal adalah apa yang Anda deklarasikan di sana, dan saran untuk mengubahnya berarti membantah Anda. Pesan itu juga tidak diberikan jika dokumen yang mendeklarasikan nama tersebut telah dibaca dan ditolak: dokumen itu sudah berada di tempat yang dibaca katalog, sehingga laporan menyebut apa yang dilanggar dokumen tersebut, yaitu baris dan batasannya, dan memindahkannya tidak akan memperbaiki apa pun. Dokumen yang terlalu rusak sehingga nama yang dideklarasikannya sama sekali tidak dapat dibaca tidak dapat dicocokkan dengan nama yang Anda gunakan, sehingga penjelasan tersebut tetap diberikan — dan jika dokumen itu mendeklarasikan apiVersion Aggrega, build, pull, atau validasi sebuah Release menyebutkannya di samping penjelasan tersebut, beserta alasan dari parser itu sendiri, karena dokumen itu mungkin file yang perlu dibuka. Kegagalan yang menemukan entitas tetapi tidak dapat menerimanya — registry yang kini menyajikan byte lain untuk versi yang di-pin oleh lockfile Anda, file yang dibawa entitas yang tidak dapat dibaca — juga bukan entitas yang hilang, dan hanya melaporkan solusinya sendiri.
Apakah pull atau push mem-pin sebuah entitas
Sebuah Recipe atau FeatureRecipe membawa pin untuk input yang dibacanya — source: jarak jauh yang ditulis
lengkap, file yang diimpor oleh entri artifacts, file dari source: di sampingnya — dalam entity.lock di sampingnya, dan mencatatnya adalah
langkah penulis entitas, aggrega pin. Secara default, baik pull maupun push
tidak menjalankan langkah itu: pull berhenti pada entitas yang tidak di-pin oleh lock-nya, dan push menolak menerbitkannya.
Dua key, satu per perintah, menjadikan langkah itu default perintah tersebut:
# <project>/.aggrega-config.yamlworkspace: {}pin_sources_at_pull: truepin_sources_at_push: trueSetiap key hanya mengatur perintahnya sendiri dan tidak yang lain, dan --pin-sources milik setiap perintah menimpa
key-nya sendiri ke dua arah — --pin-sources=false mematikan langkah itu untuk satu kali jalan di proyek yang
dikonfigurasi untuk mem-pin. Build yang mengisi lockfile-nya sendiri adalah pull dan mengikuti
pin_sources_at_pull. Key ini termasuk dalam file proyek, bukan file global: apakah pull suatu
proyek mencatat pin adalah kebijakan proyek tersebut, dan rekan tim yang meng-clone-nya semestinya mendapatkan
jawaban yang sama. pin_sources_at_pull juga merupakan cara proyek yang menggunakan katalog tanpa pin milik pihak lain
mencatat pin tersebut sekali alih-alih berhenti pada setiap pull.
Plugin mana yang merender sebuah kapabilitas
Sebuah Recipe menyebutkan kapabilitas yang digunakannya untuk merender — capability: helm — dan plugin yang melayani kapabilitas tersebut merendernya. Jika tepat satu plugin melayani suatu kapabilitas, tidak ada yang perlu dikonfigurasi. Jika lebih dari satu, entri plugins.providers menyatakan plugin yang mana, berdasarkan identitas plugin tersebut:
# <project>/.aggrega-config.yamlworkspace: {}plugins: providers: - capability: helm uri: provider/helmSebuah pull me-resolve entri tersebut dan mencatat plugin yang dipilihnya dalam lockfile milik Release, dan sebuah build merender melalui apa yang dicatat lockfile, sehingga suntingan di sini berlaku pada pull berikutnya.
uri menyebut plugin berdasarkan identitasnya, provider/<name>, tidak pernah berdasarkan tempat plugin itu dipublikasikan. aggrega plugin add provider <query> --capability <capability> menulis entri dalam bentuk tersebut, tanpa versi: entri memilih plugin mana yang melayani kapabilitas tersebut, versinya adalah versi yang disematkan Recipe atau, jika tidak ada, versi tertinggi yang tersedia, dan lockfile mencatat versi yang dipilih oleh pull. Plugin yang dibawa kompiler di dalam dirinya dilayani pada versi kompiler itu sendiri, sehingga versi yang ditulis pada entri untuk plugin semacam itu hanya ter-resolve jika memang versi tersebut. Entri yang uri-nya berupa lokasi registry — oci://hub.aggrega.ai/plugin/provider/helm — tidak menyebut identitas plugin mana pun, dan ditolak saat berkas dimuat, dengan menyebut entri tersebut dan bentuk yang harus ditulis.
Entri ditulis sekali untuk seluruh proyek, sedangkan sebuah build adalah untuk satu Release, sehingga entri untuk kapabilitas yang tidak pernah diminta oleh Release ini sah — Release lain dalam proyek membacanya — dan tidak dilaporkan sama sekali. Yang diperiksa oleh setiap build dan setiap aggrega validate --release adalah setiap entri, baik ada maupun tidak ada Recipe yang meminta kapabilitasnya, berdasarkan apa yang disebutkan entri tersebut:
- Entri yang menyebutkan plugin yang tidak melayani kapabilitasnya menghentikan build dan menggagalkan
validasi. Sebuah pull me-resolve setiap entri yang menyebutkan plugin, dan menolak entri yang tidak dapat di-resolve,
sehingga setelah sebuah entri melalui pull, build memegang plugin-nya dan mengetahui apa yang dilayaninya; entri
yang menyebutkan plugin yang belum dipegang build dinilai setelah pull mengambilnya. Pesannya
menyebutkan entri, plugin,
apa yang sebenarnya dilayani plugin itu, dan ejaan yang berjarak satu suntingan jika ada — bentuk yang diambil salah ketik
seperti
hlemuntukhelm. - Entri yang hanya menyebutkan kapabilitas yang tidak dilayani oleh plugin mana pun yang dibaca build merupakan peringatan, dan build tetap berlanjut. Plugin yang melayaninya mungkin hanya dibaca oleh Release lain, yang tidak dapat dilihat build ini, dan entri yang tidak menyebutkan plugin tidak memilih apa pun yang tidak akan dipilih oleh resolusi kapabilitas tanpanya.
Kapabilitas di sini tidak pernah mengandung titik dua, dan kapabilitas yang mengandungnya ditolak saat berkas dimuat. capability: milik sebuah
Recipe dibaca sebagai kapabilitas hingga titik dua terakhirnya dan pin versi setelahnya, sehingga
entri berkunci helm:1.0.0 tidak akan pernah dapat ditemukan. Sebagai gantinya, sematkan versi pada plugin —
uri: provider/helm:1.0.0 — atau dalam Recipe.
Importer mana yang mengubah sumber menjadi draf
aggrega import menyerahkan sumber kepada importer yang mengiklankan format sumber tersebut — importer dalam
katalog Anda atau salah satu importer inti compiler, import:langflow untuk alur Langflow. Jika tepat satu importer mengiklankannya, tidak ada
yang perlu dikonfigurasi. Entri plugins.importer melampirkan importer dengan menyebutkannya dalam uri-nya, berdasarkan
identitas dan versinya, dan menyerahkan kepadanya apa yang dibawa entri di bawah with:
# <project>/.aggrega-config.yamlworkspace: {}plugins: importer: - uri: importer/agent-flows:1.2.0 with: settings: target_namespace: paymentsaggrega plugin add importer menulis uri tepat dalam bentuk itu. Versinya eksak — :1.2.0
— atau rentang — :^1.2.0 untuk versi tertinggi yang sama dengan atau di atasnya dalam versi mayor yang sama. Tulis salah satu
dari keduanya: pada daftar ini, uri tanpa titik dua dibaca sebagai path sistem berkas, seperti yang dijelaskan
Ke mana path relatif menunjuk, dan tidak menyebutkan importer apa pun.
Apa yang dilakukan sebuah entri bergantung pada apakah importer yang disebutkannya mengiklankan format yang diminta oleh sebuah import:
- Jika ya: importer itulah yang dijalankan, pada versi yang disebutkan
uri, berapa pun banyaknya importer lain dalam katalog yang juga mengiklankan format tersebut, dan importer itu menerimawith.sourcesdanwith.settingsmilik entri. Entri adalah cara workspace yang katalognya memfederasikan importer dari dua penerbit untuk satu format menyatakan importer mana yang digunakannya. - Jika tidak — entri menyebutkan importer format lain, plugin jenis lain, atau sesuatu yang tidak dipegang katalog
Anda maupun dibawa compiler: entri tersebut tidak berperan dalam import itu. Entri tersebut tidak memilih apa pun, dan
with-nya tidak diserahkan kepada importer mana pun. Pengaturan sebuah entri hanya mencapai importer yang disebutkannya, sehingga workspace yang melampirkan satu importer per format mengonfigurasi masing-masing tanpa pengaturan yang satu mencapai yang lain.
Jika lebih dari satu importer mengiklankan format tersebut dan tidak ada satu pun di antaranya yang dilampirkan secara tunggal — tidak ada yang dilampirkan, atau entri menyebutkan dua di antaranya — import ditolak, dengan menyebutkan importer-importer yang tidak dapat dipilihnya. Entri yang menyebutkan importer yang mengiklankan format tersebut, pada versi yang tidak dipenuhi oleh versi mana pun dari importer itu dalam katalog — versi eksak yang tidak dipegang katalog, atau rentang yang tidak mencakup satu pun versinya — juga ditolak, dengan menyebutkan versinya, alih-alih menjalankan versi lain sebagai gantinya; nilai yang sama sekali bukan versi, seperti :latest, ditolak karena formatnya salah. Entitas Plugin dari salah satu importer inti compiler yang tidak memiliki modul di sampingnya dalam folder katalognya bukanlah kandidat: pada versi compiler itu sendiri, importer inti dijalankan menggantikannya, dan pada versi lain mana pun entitas itu tetap menjadi kandidat hanya jika sebuah entri menyebutkan tepat versi tersebut atau tidak ada importer bernama sama yang dapat dijalankan yang mengiklankan format tersebut, sebagaimana dijelaskan dalam Mana yang dijalankan di samping importer Anda sendiri.
Setiap importer dilampirkan oleh satu entri. Dua entri yang menyebutkan satu importer — identitas yang sama, pada
satu versi atau dua versi — ditolak saat konfigurasi dimuat, perintah mana pun yang membacanya,
dengan menyebutkan kedua entri dan berkas tempat keduanya ditulis. Ketentuan ini mencakup setiap berkas yang berkontribusi
pada daftar: entri dalam berkas global, entri dalam berkas proyek, entri di bawah importer_append, dan
entri dalam .aggrega-config-append-ci.yaml milik pipeline semuanya dihitung, sehingga memindahkan importer ke versi
baru berarti mengubah versi pada satu-satunya entrinya. aggrega plugin add importer melakukan tepat hal itu
ketika daftar plugins.importer dari berkas yang ditulisnya sudah menyebutkan importer tersebut: perintah ini memindahkan entri
itu ke versi yang di-resolve-nya, dengan mempertahankan posisi entri dan with-nya, alih-alih menambahkan
entri kedua. Perintah ini tidak membaca daftar lain, sehingga importer yang dilampirkan di bawah importer_append, atau dalam
.aggrega-config-append-ci.yaml milik pipeline, dilampirkan untuk kedua kalinya oleh perintah tersebut dan pasangan itu
ditolak saat konfigurasi dimuat; ubah versi pada entri semacam itu di tempat entri tersebut ditulis.
Entri yang uri-nya berupa path sistem berkas tidak menyebutkan importer dan tidak dibandingkan, dan daftar
plugins.governance dan plugins.linter tidak terikat pada ketentuan ini: satu plugin dapat dilampirkan
pada daftar tersebut lebih dari sekali, masing-masing dengan with-nya sendiri.
Parser yang digunakan sebuah import untuk membaca tidak memerlukan entri. Importer membaca sumbernya — dan import yang tidak menyebutkan format mengenalinya — melalui parser untuk sintaksis sumber tersebut: parser yang dilayani katalog Anda untuk sintaksis itu, dan, untuk sintaksis yang tidak memiliki parser dalam katalog Anda, parser yang dibawa oleh compiler itu sendiri, termasuk JSON. Jadi workspace yang katalognya tidak memegang parser dapat meng-import alur Langflow atau Flowise tanpa konfigurasi apa pun. Tidak ada daftar yang melampirkan parser: parser yang dilayani katalog Anda untuk suatu sintaksis adalah yang digunakan, dan dua parser dengan nama berbeda yang melayani satu sintaksis ditolak, seperti yang dijelaskan A parse or import format is advertised by more than one plugin (Format parse atau import diiklankan oleh lebih dari satu plugin).
Memulai dari nol
aggrega yang baru dipasang tidak memiliki kedua berkas tersebut, dan itu merupakan keadaan yang berfungsi, bukan keadaan yang
rusak: setiap pengaturan kembali ke nilai bawaannya dan perintah tetap berjalan. Yang belum ada adalah
registry untuk melakukan pull konten katalog, beserta kebijakan kepercayaan yang menyatakan tanda tangan mana yang
diterima — yang persis ditulis oleh aggrega config init.
Anda tidak perlu mengetahuinya sebelumnya. Perintah yang membaca konfigurasinya dan tidak menemukan berkas
di mana pun akan menyampaikannya sekali, pada standard error, dan menyebutkan aggrega config init sebagai cara untuk membuatnya.
Ini adalah saran, bukan kegagalan: standard output tidak tersentuh, tidak ada yang diminta dari Anda, dan
status keluar adalah apa pun yang akan dilaporkan perintah tersebut. Saran ini hanya ditulis ketika standard
error berupa terminal, sehingga sampai kepada Anda di papan ketik dan tidak pernah menumpuk dalam log pipeline.
Setelah salah satu berkas ada — berkas proyek Anda atau berkas global — saran ini tidak lagi muncul.
Untuk mengisi berkas global dengan hub resmi dan kebijakan kepercayaan yang diiklankan hub tersebut:
aggrega config initBerikan --registry <host> untuk mengisi registry lain, --workspace untuk menulis entri ke berkas
proyek ini alih-alih berkas global, dan --dry-run untuk melihat konten yang akan ditulis tanpa
membuat apa pun. aggrega-config.md membahas perintah ini secara lengkap.
Cara menulis host registry
Setiap registries[].host menyebut sebuah host registry. Demikian pula default_registry — yang secara opsional diikuti oleh path repositori — kecuali jika ia menyebut salah satu entri tersebut (lihat di bawah). Host ditulis sebagai host itu sendiri, dalam satu-satunya ejaan yang dipakai untuk menyimpan kebijakan kepercayaan registry tersebut:
- nama host huruf kecil yang mengandung titik, seperti
registry.example.com; localhost, atau satu nama yang diikuti port, sepertiregistry:5000;- alamat IPv4 seperti
127.0.0.1, atau alamat IPv6 dalam kurung siku seperti[::1];
masing-masing dengan :port opsional, dan tidak ada yang lain — tanpa skema, tanpa path, tanpa kredensial, tanpa spasi
dan tanpa huruf kapital. Satu nama tanpa port bukan host registry, karena itulah bentuk
segmen pertama nama entitas katalog — core dalam core/web-api — dan keduanya
tidak boleh sampai terbaca sebagai satu sama lain.
# <project>/.aggrega-config.yamlworkspace: {}default_registry: registry.example.comregistries: - host: registry.example.com signing: required: trueEjaan merupakan bagian dari kebijakan. Entri registries berlaku untuk host yang disebut oleh host:-nya,
dan persyaratan tanda tangan bawaan hub resmi berlaku untuk hub.aggrega.ai, sehingga host yang ditulis
dengan cara lain akan mencapai registry yang benar tetapi melewatkan kebijakan yang ditulis untuknya. Karena itu, host tersebut ditolak saat
konfigurasi dimuat, dan penolakan itu menyebut ejaan yang harus ditulis: HUB.AGGREGA.AI dan
https://registry.example.com ditolak dengan menyebut hub.aggrega.ai dan registry.example.com, dan
begitu pula registry.example.com/charts sebagai registries[].host, yang tidak memuat path. Port 443 adalah
port default host yang dicapai melalui HTTPS, sehingga hub.aggrega.ai:443 ditolak dengan cara yang sama, dengan menyebut
hub.aggrega.ai. localhost dan alamat loopback lainnya justru dicapai melalui HTTP biasa,
tempat 443 adalah port biasa, sehingga localhost:443 diterima sebagaimana ditulis. default_registry
yang kosong tidak menyebut registry default apa pun.
default_registry dapat memuat path repositori. Banyak registry menyimpan setiap repositori di bawah
pemilik atau proyek — ghcr.io/<owner>, <host>/<project> di Harbor — dan registry default pada salah satunya
ditulis sebagai host yang diikuti path tersebut:
# <project>/.aggrega-config.yamlworkspace: {}default_registry: ghcr.io/acmeregistries: - host: ghcr.io signing: required: truePath tersebut adalah tempat konten dipublikasikan dan diambil. Melalui default ini, aggrega push memublikasikan
core/api-server versi 1.0.0 di ghcr.io/acme/component/core/api-server:1.0.0, dan pull yang
me-resolve core/api-server mengambilnya dari tempat yang sama, sehingga tanda tangan yang dilampirkan saat
dipublikasikan juga ditemukan di sana. Path tersebut adalah path repositori dalam tata bahasa distribusi OCI: satu atau
lebih segmen berupa huruf kecil dan angka yang digabungkan dengan /, yang di dalam satu segmen dapat dipisahkan
oleh ., _, __ atau tanda hubung, tanpa tag, digest, atau / di akhir.
Path tidak pernah menjadi bagian dari cara registry dipercaya. Entri registries yang kebijakannya
berlaku, kredensial yang disimpan aggrega login, persyaratan penandatanganan, dan identitas tepercaya
semuanya ditemukan berdasarkan host saja, sehingga entri untuk ghcr.io di atas mengatur ghcr.io/acme dan setiap path lain
pada host tersebut, dan tidak ada ejaan path yang dapat melampauinya; host: sebuah entri sendiri tidak memuat
path. Host yang ditulis dengan ejaan lain sebelum path ditolak dengan menyebut lokasi yang harus ditulis —
GHCR.io/acme dan https://ghcr.io/acme menyebut ghcr.io/acme — dan apa pun yang mengikuti host jika itu
bukan path repositori ditolak dengan menyebut host yang diikutinya.
default_registry dapat menyebut sebuah entri sebagai gantinya. Jika ditulis sebagai name: dari sebuah entri di bawah
registries, nilai itu mewakili host: entri tersebut. Publikasi, pull, verifikasi tanda tangan, dan
setiap pengaturan kepercayaan per registry kemudian menggunakan host itu, dan tidak ada konten yang diambil dari host yang dieja
seperti nama tersebut:
# <project>/.aggrega-config.yamlworkspace: {}default_registry: localregistries: - name: local host: 127.0.0.1:5000Nama dicocokkan sebelum ejaan host, sebagaimana flag --registry mencocokkannya, sehingga nilai yang merupakan
name: sebuah entri mewakili entri tersebut meskipun juga dieja seperti host. Nama yang dimiliki dua
entri ditolak karena ambigu, dengan menyebut kedua host. Entri tersebut dapat berada di file mana pun —
default_registry milik proyek dapat menyebut entri yang dideklarasikan file global — karena nama dibaca
sekali, terhadap entri yang berlaku setelah setiap file dan lingkungan dibaca. Nilai
yang bukan nama entri maupun host registry — sendiri atau diikuti path repositori —
ditolak, dan penolakan itu menyatakan bahwa salah satunya akan memperbaikinya. Nama yang diikuti path, seperti local/acme,
juga ditolak: nama mewakili host entrinya dan bukan lokasi di bawahnya, sehingga penolakan itu
menyebut dua ejaan yang harus ditulis sebagai gantinya — local, atau host entri yang diikuti path,
127.0.0.1:5000/acme. Menghapus entri dengan aggrega registry remove membiarkan default_registry sebagaimana
ditulis, sehingga default yang menyebut entri yang dihapus tidak lagi menyebut apa pun dan ditolak sampai
ditulis ulang.
Setiap lapisan tunduk pada ejaan yang sama. Nilai ditolak dengan kata-kata yang sama, baik berasal
dari file konfigurasi, dari AGGREGA_DEFAULT_REGISTRY, maupun dari flag --registry yang menyebut
tujuan satu aggrega push atau aggrega push-artifact. Flag tersebut menyebut host, dan
publikasi yang diarahkannya mendarat di host itu tanpa path repositori: path adalah milik
default_registry. aggrega registry add dan
aggrega config init --registry juga menerapkan ketentuan ini pada host yang diberikan kepadanya; keduanya juga menerima
referensi sebagai gantinya, dan menyimpan entri di bawah host yang disebut referensi tersebut. Penolakan dari file
menyebut file dan kuncinya; penolakan dari lingkungan menyebut variabelnya. Skema menyatakan bentuk host
sebagai pola pada registries[].host dan tidak menyatakan apa pun pada default_registry, yang nilainya dapat berupa
nama entri mana pun — sehingga editor yang hanya membaca skema tidak menandai default yang salah ketik, dan
pemuatan konfigurasilah yang menolaknya.
Host dinilai berdasarkan ejaannya saja, demikian pula path. Apakah nama tersebut dapat di-resolve, apakah ada registry yang menjawab di sana, atau apakah path tersebut ada di dalamnya, tidak diperiksa saat konfigurasi dimuat.
Apa yang menimpa apa
CLI flag > environment variable > configuration file > built-in defaultFlag adalah sinyal paling eksplisit yang ada dan langsung menang. Variabel lingkungan menimpa file yang di-commit, yang memungkinkan pipeline mengubah pengaturan tanpa mengedit file yang dilacak. Variabel yang tidak diatur — atau diatur ke string kosong — diteruskan ke lapisan di bawahnya alih-alih mengosongkan nilai yang telah dikonfigurasi. Di antara kedua file, file proyek Anda menang atas file global.
Flag menang karena telah diketik, bukan karena nilai yang dibawanya, dan untuk pengaturan benar-atau-salah
itulah perbedaan antara lapisan teratas yang dapat digunakan dan tidak ada sama sekali. --offline mengaktifkan mode tersebut untuk satu
kali eksekusi; --offline=false menonaktifkannya untuk satu kali eksekusi ketika file yang di-commit atau variabel yang diekspor telah
mengaktifkannya. Lapisan yang hanya membaca nilai tidak dapat membedakan “mati” dari “tidak disebut”, sehingga setiap
perintah akan tampak seolah-olah meminta nilai default flag dan tidak akan ada cara untuk
membatalkan pengaturan yang telah dikonfigurasi sama sekali.
Itulah keseluruhan model untuk satu proyek di satu mesin. Semua yang berikut ada untuk proyek yang sudah melampauinya.
Di luar dua file
Mekanisme ini dibuat untuk bentuk yang lebih besar — monorepo berisi proyek-proyek yang saling terkait, pipeline yang menyumbangkan pengaturannya sendiri, katalog bersama yang diperluas oleh beberapa proyek. Gunakan salah satunya ketika Anda menghadapi masalah yang diselesaikannya.
Lebih dari satu file konfigurasi di dalam proyek
Setiap .aggrega-config.yaml dari root proyek hingga direktori tempat perintah dijalankan ikut berkontribusi, dan file yang lebih dekat menimpa file yang lebih jauh. Dengan demikian, subproyek dapat memiliki file sendiri yang menyesuaikan apa yang dideklarasikan root, tanpa mengulanginya.
Hanya file yang memuat blok workspace: yang menandai root. File tanpa blok tersebut tetap menyumbangkan pengaturannya — file itu hanya tidak menjadikan direktorinya root proyek, dan inilah yang mencegah file pengaturan subproyek mendefinisikan ulang tempat proyek dimulai.
Meneruskan --workspace-root mengubah hal ini selain melewati penemuan: file konfigurasi milik root yang disebut adalah satu-satunya yang dikumpulkan, sehingga file di direktori di bawahnya tidak berkontribusi. Hal ini menjaga konfigurasi root yang disematkan tetap sama dari mana pun perintah dijalankan.
Setiap file yang dikumpulkan dengan cara ini dibaca dari dalam proyek. File yang merupakan tautan simbolik yang mengarah ke luar proyek — atau yang berada di direktori yang dicapai melalui tautan semacam itu — tidak dibaca, dan setiap perintah yang membaca konfigurasi berhenti padanya dengan menyebut tautan tersebut, alih-alih mengonfigurasi proyek dari file yang tersisa; hal yang sama berlaku untuk file milik pipeline, di bawah. Beberapa perintah yang tidak pernah membacanya, seperti aggrega version dan aggrega help, tetap berjalan dengan peringatan yang menyebut tautan tersebut. Language server editor dan alat milik asisten membaca konfigurasi dengan cara yang sama, dan tetap berjalan pada proyek semacam itu agar proyek dapat didaftar: daftar Release dan entitas mereka tetap menjawab, dibaca tanpa konfigurasi apa pun, dan menyebut file tersebut di antara tautan yang tidak dibaca, sementara setiap permintaan lain yang ditentukan oleh konfigurasi berhenti padanya, dengan menyebut tautan tersebut. Konfigurasi yang disimpan di luar proyek dibaca dengan menyebutnya sebagai file global, seperti dijelaskan dalam Menyebut file global secara eksplisit. Lihat Batas workspace.
Memperluas daftar alih-alih menggantinya
Pengaturan bernilai daftar berperilaku seperti pengaturan lainnya: nilai file yang lebih dekat menggantikan nilai file yang lebih jauh. Jika Anda ingin menambahkan ke apa yang dideklarasikan file luar alih-alih menyatakannya ulang, gunakan pendamping append di sebelahnya:
| pengaturan daftar | pendamping append-nya |
|---|---|
workspace.catalog_dirs | catalog_dirs_append |
plugins.governance | governance_append |
plugins.linter | linter_append |
plugins.importer | importer_append |
plugins.providers | providers_append |
Entri di bawah pendamping digabungkan ke daftar yang telah di-resolve pada setiap lapisan alih-alih membayanginya, sehingga subproyek menambahkan linter ke apa pun yang sudah dideklarasikan root:
# <project>/services/api/.aggrega-config.yamlplugins: linter_append: - uri: ./lint/api-rules.wasmJika satu file menetapkan daftar dasar dan pendampingnya sekaligus, nilai file tersebut adalah daftar dasar diikuti entri yang ditambahkan.
Blok workspace: adalah pengecualian terhadap tempat pendamping dapat ditulis. File yang memuat blok tersebut menandai direktorinya sendiri sebagai root proyek, sehingga file subproyek yang menulis workspace.catalog_dirs_append akan memulai proyeknya sendiri alih-alih menambah proyek yang melingkupinya. Pendamping direktori katalog tersusun antara file global Anda dan file root proyek.
Daftar plugins.cli tersusun lintas file dengan sendirinya dan tidak memiliki pendamping: ekstensi perintah yang dideklarasikan di file global mendaftarkan perintahnya di setiap proyek, yang dideklarasikan di suatu proyek hanya mendaftar di sana, dan keduanya terdaftar bersama. Setiap entri menyematkan satu plugin: uri yang di-resolve-nya dan digest dari byte yang diverifikasi oleh aggrega plugin add cli, ditulis sebagai sha256: diikuti 64 digit heksadesimal huruf kecil. Digest dengan ejaan lain tidak akan pernah sama dengan digest hasil hash byte yang di-resolve, sehingga digest tersebut ditolak saat file dimuat, dengan menyebut file dan entrinya.
Memberi Release direktori katalognya sendiri
Sebuah proyek dapat menyimpan beberapa varian katalog berdampingan — satu per target, masing-masing memuat Recipes yang merender Components yang sama untuk provider yang berbeda — dan membangun setiap Release terhadap salah satunya. Sebut setiap Release di bawah workspace.releases dan berikan catalog_dirs miliknya sendiri:
# <project>/.aggrega-config.yamlworkspace: releases: release-compose.yaml: catalog_dirs: - ./catalog-compose release-helm.yaml: catalog_dirs: - ./catalog-helmSetiap kunci adalah file Release, ditulis relatif terhadap file konfigurasi yang menyebutnya. Sebuah kunci — seperti build.authoring_release — dapat menyebut Release yang disimpan di luar proyek, dan menyebutnya di sini adalah cara proyek menjangkaunya: tautan di dalam proyek yang mengarah ke sana dibaca alih-alih dilewati, seperti dijelaskan dalam Batas workspace. Dua kunci di bawahnya bermakna sama seperti pada blok workspace:, dengan cakupan Release tersebut saja:
catalog_dirsmenggantikan daftar workspace untuk Release tersebut. Urutan pencarian, direktoricatalogyang dibaca setelahnya, dan arti daftar kosong sama seperti untuk daftar milik workspace sendiri.catalog_dirs_appenddibaca setelah daftar milik Release. Entri yang hanya menuliscatalog_dirs_appendmempertahankan daftar workspace dan menambahkannya.
Release yang tidak disebut oleh map membaca workspace.catalog_dirs milik workspace sendiri. Release yang disebut oleh map membaca direktorinya sendiri bagaimanapun ia dibangun — aggrega build atau aggrega pull di terminal, editor melalui aggrega serve, asisten melalui aggrega mcp — sehingga tidak satu pun memerlukan flag untuk menemukan katalognya. --catalog <dir> di baris perintah tetap dicari lebih dulu sebelum direktori milik Release, untuk satu pemanggilan tersebut. Dan pencarian yang tidak menemukan entitas dengan nama yang Anda gunakan menyebut entri Release tersebut sebagai tempat untuk mencantumkan direktori yang memuatnya.
Entri yang menyebut file yang tidak ada ditolak saat konfigurasi dimuat, dengan menyebut entri dan filenya. Karena itu, mengganti nama Release menghentikan setiap perintah hingga entrinya ikut diganti namanya, alih-alih membiarkan Release dibangun terhadap daftar workspace tanpa pemberitahuan apa pun. Direktori yang dicantumkan sebuah entri harus berupa direktori, sebagaimana direktori yang disebut daftar workspace: yang bukan direktori ditolak oleh setiap perintah yang membaca katalog Release tersebut, dengan menyebut entri dan barisnya.
Hal yang tidak menyangkut satu Release tertentu tetap membaca daftar workspace: lint atau validasi seluruh katalog, pencarian entitas berdasarkan nama, Aggregate yang diperiksa tersendiri, dan daftar entitas workspace di editor. AGGREGA_CATALOG_DIRS menetapkan daftar workspace dan tidak menjangkau entri apa pun di sini, dan file konfigurasi milik pipeline Anda sama sekali tidak membaca map tersebut.
File konfigurasi milik pipeline Anda
File bernama .aggrega-config-append-ci.yaml dapat berada di samping file yang ditulis manual di direktori mana pun yang dikunjungi penelusuran. File ini terpisah agar pipeline otomatis dapat memilikinya dan menimpanya seluruhnya tanpa pernah menyentuh apa yang ditulis seseorang.
File ini hanya bersifat aditif. Entrinya untuk lima pengaturan daftar di atas digabungkan ke daftar yang telah di-resolve; file ini tidak dapat menghapus apa pun atau menimpa skalar. Kunci skalar atau map yang ditulis di dalamnya tidak memiliki makna aditif, sehingga diabaikan dan disebut dalam peringatan alih-alih diterapkan diam-diam. File ini juga tidak pernah menandai root proyek, sehingga meletakkannya di suatu direktori menambahkan lampiran tanpa memindahkan tempat proyek dimulai.
Ke mana path relatif menunjuk
Path sistem berkas relatif di-resolve terhadap direktori berkas yang mendeklarasikannya — bukan terhadap root proyek, dan bukan terhadap direktori tempat Anda menjalankan perintah. Inilah aturan yang layak dibaca dua kali, karena path yang tampak relatif terhadap proyek di-resolve ke tempat lain dan build tetap berhasil, terhadap konten yang tidak Anda maksudkan.
Aturan ini berlaku untuk workspace.catalog_dirs, untuk berkas Release yang dijadikan kunci di bawah workspace.releases dan
direktori yang dicantumkan setiap entri, untuk path sistem berkas lokal pada lampiran plugins.governance atau
plugins.linter — sebuah uri yang menamai berkas .wasm di disk, dan setiap entri di bawah with.sources lampiran tersebut — serta untuk setiap entri di bawah with.sources milik lampiran plugins.importer. Pada ketiga daftar, sebuah uri tanpa titik dua yang tidak menamai registry —
importer/agent-flows sama halnya dengan ./lint/api-rules.wasm — adalah path semacam itu, sedangkan uri yang menamai
plugin berdasarkan identitasnya membawa versi setelah titik dua, importer/agent-flows:1.2.0, dan dibiarkan
persis seperti tertulis. uri pada lampiran importer menamai importer yang dilampirkannya, seperti dijelaskan
Importer mana yang mengubah sumber menjadi draf; sebuah
impor tidak membaca modul apa pun dari path yang ditulis di sana.
Aturan ini juga berlaku untuk entri di bawah pendamping append, dan masing-masing berjangkar pada
berkas yang mendeklarasikannya sendiri, bukan pada berkas tempat penggabungan kebetulan berakhir. Aturan ini juga berlaku untuk
mcp.tls.cert_file, mcp.tls.key_file dan
mcp.authorization.jwks_file, sehingga berkas di samping berkas yang menamainya ditemukan di mana pun server dijalankan.
Jadi, dengan tata letak berikut:
myproject/├── .aggrega-config.yaml└── services/ ├── .aggrega-config.yaml └── catalog/dan ./catalog ditulis di berkas root, path tersebut menamai myproject/catalog. Jika ditulis di
services/.aggrega-config.yaml, teks yang sama persis menamai myproject/services/catalog. Path absolut
dibiarkan persis seperti tertulis, demikian pula referensi registry seperti
oci://hub.aggrega.ai/plugins/helm:1.0.0.
Pengaturan berikut sengaja tidak mengikuti aturan ini, karena tidak memiliki berkas pendeklarasi sebagai jangkar atau karena setiap pembacanya me-resolve-nya di tempat lain:
artifact_cache_dirditafsirkan relatif terhadap root proyek, dari mana pun perintah dijalankan, sehingga cache berupa satu direktori, bukan satu per lokasi pemanggilan. Nilai absolut ditolak saat konfigurasi dimuat.AGGREGA_CATALOG_DIRSberasal dari environment dan sama sekali tidak memiliki berkas pendeklarasi, jadi berikan path absolut di dalamnya.mcp.listendiambil persis seperti tertulis, termasuk path sistem berkas dalam bentukunix:<path>. Alamat yang sama juga dapat datang dariaggrega mcp --listen, yang tidak memiliki berkas pendeklarasi, sehingga menjangkarkan hanya penulisan yang dikonfigurasi akan membuat satu string menamai dua tempat berbeda tergantung dari mana asalnya. Berikan path absolut untuk socket.
Satu pengaturan yang penyimpanannya dipakai bersama
Hampir setiap pengaturan mengatur sesuatu yang dimiliki proyek tempat Anda bekerja — direktori mana yang digunakannya untuk me-resolve konten katalog, plugin mana yang merender targetnya, seberapa ketat kontennya dinilai, seberapa besar cache dalam memori milik daemon boleh tumbuh. Nilai di berkas proyek mengatur hal milik proyek itu sendiri, dan tidak ada yang perlu diwaspadai.
compiled_module_cache.max_bytes adalah satu-satunya pengecualian, karena yang dibatasinya tidak bersifat per proyek.
Kode plugin yang telah dikompilasi disimpan dalam satu direktori yang digunakan ulang oleh setiap proyek di mesin Anda, sehingga
sebuah plugin dikompilasi sekali, bukan sekali per proyek. Batas itu sendiri di-resolve seperti pengaturan
lainnya — tulis di berkas proyek dan nilai itu berlaku untuk proyek tersebut — tetapi penyimpanan tetap
hanya memiliki satu ukuran, dan ukuran yang berlaku adalah ukuran dari build terbaru. Dua proyek yang
membatasinya secara berbeda akan berlaku bergantian, dan batas yang lebih rendah membuang kode terkompilasi yang telah dibayar
oleh proyek lainnya.
Jadi, letakkan di berkas global bila Anda menginginkan satu jawaban untuk semua yang Anda build, dan pertahankan di atas
apa yang dikompilasi oleh satu build. aggrega cache status melaporkan isi penyimpanan saat ini, dan
aggrega config show --origin memberi tahu Anda dari berkas mana batas yang sedang berlaku sebenarnya
berasal.
Pengaturan untuk server yang dijangkau orang lain
aggrega mcp menggunakan Model Context Protocol. Di mesin Anda sendiri, klien menjalankannya sebagai
subproses dan berkomunikasi dengannya melalui standard input dan output, yang merupakan default, dan satu-satunya
pengaturan yang memengaruhi bentuk itu adalah mcp.transport, dibiarkan pada default tersebut, dan mcp.announce_tools. Bagian
lain dari blok mcp adalah untuk bentuk lainnya, yang dipilih oleh mcp.transport: http: satu
proses berjalan lama di sebuah host, dijangkau melalui HTTP oleh pemanggil yang tidak berada di depan keyboard-nya.
# <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:7778mcp.transport adalah yang memilih transport. http memulai listener; stdio, default-nya,
berkomunikasi melalui standard input dan output, yang diharapkan oleh klien subproses. Nilai lainnya
ditolak saat berkas ini dimuat. aggrega mcp --transport <stdio|http> melakukan hal yang sama untuk satu
pemanggilan dan mengalahkan kunci tersebut, sebagaimana setiap flag mengalahkan setiap berkas.
mcp.listen menamai tempat listener tersebut melakukan bind, dan tidak memilih apa pun. Berikan alamat host:port
atau socket unix:<path>; aggrega mcp --listen <address> mengalahkannya untuk satu pemanggilan.
Dengan http dipilih dan tanpa alamat dari keduanya, peluncuran ditolak sebelum apa pun melakukan bind. Dengan
stdio dipilih, --listen yang diketikkan ditolak, dan alamat yang hanya dinamai oleh kunci ini dibiarkan tidak terpakai —
server menyatakannya dalam satu baris di aliran error-nya, dengan menamai berkas ini dan mcp.transport: http. Jadi,
server yang dijangkau orang lain menetapkan kedua kunci, seperti di atas, dan klien yang diluncurkan dari direktori yang dicakup berkas itu
tetap menjangkau server melalui alirannya sendiri. Path unix: diambil seperti tertulis, bukan dijangkarkan —
lihat Ke mana path relatif menunjuk.
mcp.tls.cert_file dan mcp.tls.key_file menempatkan TLS di dalam proses. Tetapkan keduanya dan listener
melayani HTTPS sendiri. Hilangkan keduanya dan listener melayani plaintext, yang hanya diterima pada loopback atau
pada Unix socket — bentuk yang Anda gunakan ketika proxy di depan memegang sertifikat dan meneruskan ke
proses. Listener plaintext pada alamat lain ditolak sebelum apa pun melakukan bind, dengan menamai
kedua kunci ini, demikian pula jika salah satu dari keduanya ditetapkan tanpa yang lain. Keduanya adalah path sistem berkas dan
mengikuti aturan di atas: path relatif di-resolve terhadap direktori berkas yang mendeklarasikannya,
sehingga sertifikat yang di-commit di samping berkas itu ditemukan di mana pun server diluncurkan. Tuliskan
sebagai path absolut jika sertifikat dikelola di luar proyek.
mcp.authorization.issuer dan mcp.authorization.resource menyatakan siapa yang menerbitkan token yang diajukan pemanggil, dan apa nama server ini sebagai sumber daya yang menjadi tujuan penerbitan token tersebut. Keduanya wajib setiap kali transport http dipilih, dan tanpa keduanya sebuah listener ditolak sebelum apa pun di-bind, karena setiap permintaan ke endpoint dijawab dengan tantangan bearer-token, dan tantangan yang tidak menunjuk ke mana pun adalah tantangan yang tidak dapat ditindaklanjuti oleh klien. Tuliskan alamat lengkap, termasuk skema dan host: issuer persis seperti server otorisasi tersebut menyatakan pengenalnya sendiri, dan resource sebagai alamat yang benar-benar dicapai pemanggil Anda — host yang ditampilkan oleh proxy di depan, jika ada, bukan alamat yang di-bind oleh proses ini. Keduanya dipublikasikan, tanpa meminta kredensial, dalam dokumen metadata OAuth protected-resource yang dilayani listener, yaitu tempat klien mencari tahu di mana memperoleh token. Tidak satu pun menyimpan sesuatu yang rahasia: token tiba pada permintaan yang mengajukannya dan tidak pernah ditulis dalam berkas konfigurasi. Issuer adalah alamat https kecuali server otorisasi berjalan di mesin ini — localhost, 127.0.0.1 atau ::1 — dan listener yang menyebut issuer http biasa pada host lain ditolak sebelum apa pun di-bind, bagaimana pun cara listener itu membaca kunci dan pemanggilnya: setiap klien diarahkan ke issuer untuk memperoleh tokennya, sehingga melalui http biasa kode otorisasi dan tokennya akan melintasi jaringan tanpa perlindungan, dan jika kunci juga dibaca dari sana, siapa pun yang berada di jalur tersebut dapat menggantinya.
mcp.authorization.jwks_file menyebut berkas yang menyimpan kunci untuk memverifikasi token, alih-alih membacanya dari server otorisasi. Jika dihilangkan, server membaca metadata server tersebut di alamat well-known-nya dan mengikuti jwks_uri yang dipublikasikan di sana, yang merupakan perilaku workspace dengan akses jaringan. Alamat kunci tersebut tunduk pada aturan yang sama dengan issuer, demikian pula setiap alamat tujuan pengalihan dari kedua pembacaan itu: alamat http biasa pada host lain tidak pernah dihubungi, dan token yang memerlukan kunci tersebut dijawab 503 hingga server otorisasi memublikasikan metadata dan kuncinya melalui https. Jika ditetapkan, server otorisasi tidak pernah dihubungi — yang dibutuhkan oleh workspace yang mendeklarasikan offline: true, dan workspace seperti itu ditolak sebelum listener-nya di-bind kecuali kunci ini menyebut sebuah berkas. Nilainya berupa path dan mengikuti aturan di atas: path relatif di-resolve terhadap direktori berkas yang mendeklarasikannya, sehingga set kunci yang di-commit di samping berkas itu ditemukan dari mana pun server dijalankan. Berkas tersebut berisi kunci verifikasi publik, yaitu yang dipublikasikan server otorisasi — tidak ada yang menandatangani, dan tidak ada yang rahasia.
mcp.allowed_origins hanya diperiksa ketika permintaan membawa header Origin, yang dalam praktiknya berarti peramban yang mengirimnya. Cantumkan di sana origin yang Anda layani; permintaan yang menyebut origin yang tidak tercantum ditolak, dan permintaan tanpa header tersebut tetap dilayani. Klien yang bukan peramban tidak mengirim header tersebut dan tidak memerlukan entri. Entri dibandingkan dengan header secara persis, jadi tuliskan seperti yang dikirim peramban: skema huruf kecil, ://, host huruf kecil, dan : beserta port hanya jika port bukan default skema — https://studio.example.com, atau http://localhost:3000 untuk halaman yang dilayani di mesin Anda sendiri — tanpa path dan tanpa / di akhir. Entri dalam bentuk lain tidak akan pernah cocok, dan ditolak saat berkas ini dimuat, dengan menyebut entri tersebut.
mcp.limits membatasi apa yang dapat diminta oleh satu pemanggil — seberapa besar badan satu permintaan, berapa banyak permintaan yang berjalan bersamaan, dan berapa banyak yang boleh dikirim satu pemanggil dalam satu menit. Ketiganya selalu berlaku; tidak ada nilai yang menghapusnya. Yang ketiga, requests_per_minute, dihitung terhadap setiap pemanggil secara terpisah, sehingga satu pemanggil yang mengirim secara intensif tidak merugikan pemanggil lain.
mcp.authorization.trusted_proxy membaca pemanggil dari proxy di depan alih-alih memeriksa token di sini. Tetapkan principal_header ke header yang digunakan proxy tersebut untuk menyatakan siapa pemanggilnya, dan secara opsional scopes_header ke header yang membawa scope pemanggil tersebut. Keduanya adalah nama header HTTP, seperti X-Forwarded-User — huruf, angka, tanda hubung, dan beberapa karakter lain yang boleh ada dalam nama header, tanpa spasi atau titik dua — dan nama dalam bentuk lain ditolak saat berkas ini dimuat, dengan menyebut kuncinya, karena tidak ada permintaan yang dapat membawanya. Dalam mode itu tidak ada token yang dibaca sama sekali, dan permintaan tanpa principal header ditolak. Karena header tersebut kemudian menjadi seluruh kredensial, header itu hanya dapat dipercaya jika tidak ada pihak lain yang dapat menetapkannya: proses ditolak sebelum di-bind kecuali mcp.listen berupa loopback atau Unix socket. Jika blok ini dihilangkan, server ini memeriksa token sendiri, yang merupakan default; blok yang principal_header-nya kosong ditolak alih-alih dibaca sebagai default tersebut.
mcp.deny_reach mencabut suatu jenis jangkauan dari deployment ini. Setiap operasi yang dilakukan server mendeklarasikan seberapa jauh efeknya menjangkau — none untuk operasi yang membaca atau merender dan tidak meninggalkan apa pun, workspace untuk operasi yang menulis di dalam workspace yang dilayani proses ini, registry untuk operasi yang memublikasikan, menandatangani, atau menarik kembali, dan machine untuk operasi yang mengubah apa yang dibagikan oleh setiap workspace di host. Menyebut suatu jenis di sini mencabut setiap tool yang menjangkaunya: tool tersebut tidak ada dalam daftar tool setiap pemanggil apa pun yang dibawa token pemanggil itu, dan panggilan ke tool tersebut ditolak dengan menyebut pengaturan ini. Hal itu menjadikannya batas milik deployment, bukan milik pemanggil, dan tidak ada kredensial yang menghapusnya — server yang dimaksudkan hanya melayani pembacaan mencantumkan ketiga jenis penulisan di sini sehingga tidak dapat memublikasikan bahkan untuk pemanggil yang tokennya membawa setiap scope. Jika dihilangkan, yang merupakan default, deployment ini membawa apa pun yang diizinkan oleh scope pemanggilnya. Nilai yang bukan salah satu dari keempatnya ditolak saat berkas ini dimuat, alih-alih dilewati. Tidak ada operasi berjenis machine yang ditawarkan melalui HTTP apa pun isi pengaturan ini, sehingga menyebutnya diterima dan tidak mengubah apa pun; aggrega-mcp.md menjabarkan jenis-jenis tersebut dan scope yang mengizinkannya.
mcp.announce_tools mempersempit apa yang diumumkan server, dan ini adalah batas yang berbeda dari kunci di atas. Sebutkan tool yang diumumkan server ini, dieja seperti yang dilaporkan daftar tool, dan tepat tool itulah yang diumumkan: tool yang tidak disebut tidak ada dalam daftar tool setiap pemanggil dan ditolak jika tetap dipanggil dengan namanya, dengan menyebut pengaturan ini. Jika kunci ini dihilangkan — default — setiap tool yang dibawa server diumumkan; jika ditulis daftar kosong, tidak ada yang diumumkan, sehingga kedua penulisan itu merupakan pernyataan yang berbeda dan tidak ada default yang diisikan untuk Anda. Yang membedakannya dari deny_reach adalah apa yang diambil masing-masing. deny_reach mengambil sebuah kemampuan: operasi berjenis yang dicabut sama sekali tidak dibawa di sini dan tidak ada kredensial yang mengembalikannya. announce_tools hanya mengambil sebuah pengumuman — tool yang tidak disebutnya tetap merupakan kemampuan yang dimiliki server — dan yang dijawabnya adalah klien yang membatasi berapa banyak tool yang akan didaftarkannya, terkadang di seluruh server yang terhubung dengannya sekaligus. Jika keduanya ditetapkan, pencabutan yang menang, sehingga tool berjenis yang dicabut tetap tidak ada bagaimana pun kunci ini menyebutnya. Nama yang tidak cocok dengan tool mana pun menghentikan server sebelum melayani apa pun, dengan mencantumkan tool yang dimilikinya, alih-alih meninggalkan Anda dengan permukaan yang lebih sempit daripada yang Anda minta. Tidak seperti kunci lain di sini, yang mengonfigurasi listener yang dijalankan transport http, kunci ini dibaca transport apa pun yang digunakan server, karena klien yang menjadi tujuan penyempitan biasanya adalah klien yang meluncurkan proses melalui standard input dan output-nya sendiri; aggrega-mcp.md menjabarkan selebihnya.
mcp.health.listen menempatkan pemeriksaan liveness dan readiness pada alamatnya sendiri. Berikan alamat dalam salah satu dari dua bentuk mcp.listen, dan listener kedua menjawab GET /healthz di sana —
200 sejak proses berjalan — dan GET /readyz — 503 hingga workspace selesai di-resolve dan endpoint telah terikat, 200 sejak saat itu, yang memungkinkan balancer menahan lalu lintas
hingga proses benar-benar dapat menjawab panggilan. Jika dihilangkan, kedua pemeriksaan tidak dijawab
di mana pun. Keduanya tidak pernah dijawab pada alamat yang disebut mcp.listen, yang memberi keduanya 404 seperti yang diberikannya
untuk setiap path yang tidak dilayaninya: probe di sana akan menjadi pembacaan tanpa autentikasi terhadap listener
yang menolak segala hal lainnya. Berbeda dengan mcp.listen, alamat ini tidak dibatasi dan tidak ada alamat yang
ditolak untuknya — arahkan ke loopback atau Unix socket, yang dapat dijangkau oleh supervisor di samping proses ini, dan perhatikan bahwa apa pun yang dapat menjangkau alamat yang Anda pilih dapat membaca kedua jawaban tersebut.
schema/other/aggrega-config.md menyatakan setiap kunci ini beserta nilai default-nya, jika ada.
Cara lain root proyek dikenali
--workspace-root <path>, atau padanannya AGGREGA_WORKSPACE_ROOT, menyebut root secara langsung dan
melewati penemuan. Folder yang disebutnya harus ada: path yang tidak menunjuk apa pun, atau menunjuk sebuah file,
ditolak sebelum perintah melakukan hal lain, dan penolakan itu menyebut mana di antara keduanya yang memberikan
nilai tersebut serta mengutipnya sebagaimana diberikan. Jika tidak, penemuan berjalan ke atas dari direktori kerja,
dan jenis-jenis jangkar diperingkat satu sama lain, bukan berdasarkan kedekatan:
.aggrega-config.yamlyang memuat blokworkspace:langsung menang, pada kedalaman mana pun ia berada. Penelusuran terus naik untuk mencarinya bahkan setelah melewati penanda jenis di bawah, sehingga root yang ditandai secara eksplisit di atas selalu mengalahkan penanda kebetulan di bawahnya.- Jika tidak ada, penanda terdekat berikut menjadi jangkar root, dan dalam satu direktori penanda-penanda ini
diperingkat dengan urutan: direktori
.aggrega/, laluaggregate*.yaml, lalurelease*.yaml, lalumanifest*.yaml. - Jika semuanya gagal, direktori kerja yang digunakan — perintah tetap berjalan alih-alih menolak untuk dimulai. Perintah yang hasilnya bergantung pada workspace — perintah yang membaca atau menulis dokumen workspace, membaca atau mengisi cache artefaknya, atau melayaninya — memberi peringatan sekali di standard error:
warning: <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace. Perintah yang hasilnya tidak bergantung pada folder mana yang menjadi root tidak mengatakan apa pun, bahkan ketika membaca konfigurasi: di antaranyaaggrega version,aggrega config show,aggrega plugin list,aggrega registry list,aggrega explaindanaggrega login.aggrega config capture, yang tugasnya menulis berkas konfigurasi milik workspace itu sendiri, tidak menulis apa pun di folder seperti itu dan keluar dengan kesalahan yang menyatakan hal tersebut.
Tidak ada yang ditulis ke cache artefak di folder seperti itu. Direktori .aggrega/ sendiri merupakan salah satu
penanda di atas, sehingga cache yang ditulis di sana akan menjadikan folder itu workspace hanya karena sesuatu pernah
diambil di dalamnya. Perintah yang pekerjaannya mengisi cache — aggrega pull, build yang me-resolve
dependensinya terlebih dahulu, aggrega registry update, penambahan plugin ekstensi perintah dari registry —
ditolak sebelum mengambil apa pun, dengan menyebut folder tersebut dan dua jalan keluarnya: sebut workspace dengan
--workspace-root atau AGGREGA_WORKSPACE_ROOT, atau berikan folder itu .aggrega-config.yaml yang memuat
blok workspace:. aggrega pin, dan aggrega push untuk Recipe atau FeatureRecipe, yang terikat pada
pin yang dicatat entity.lock di sampingnya, mengisi cache hanya dengan sumber jarak jauh yang ditulis lengkap oleh entitas,
yang diambil saat mem-pin entitas atau membandingkan pin-nya: perintah-perintah itu ditolak dengan cara yang sama jika
akan mengambil sumber seperti itu, sebelum mengambilnya. Entitas tanpa sumber seperti itu — tanpa sumber sama
sekali, sumber lokal, atau sumber yang koordinatnya diisi oleh setiap Release — di-pin atau dipublikasikan di sana seperti
di tempat lain. Build di sana tidak ditolak, tetapi
input eksternal yang di-pin lockfile-nya dan tidak lagi disimpan cache tidak diambil ulang untuk memperbaikinya: proses
render diberi kalimat yang sama sebagai pengganti input itu, seperti saat diberi kalimat untuk postur offline, dan
melaporkannya. Tempat artifact_cache_dir menaruh cache tidak mengubah apa pun di sini, karena direktori itu
digabungkan ke root mana pun yang ditemukan. Perintah yang hanya membaca tetap menjawab.
Fallback terakhir itu memiliki satu pengecualian. Jika tidak ada yang menyebut root dan direktori kerja tidak menjadi jangkar
apa pun, perintah yang menyangkut satu Release atau satu dokumen entitas yang menyebut file tersebut dengan path absolut
menemukan root lagi, berjalan ke atas dari folder tempat file itu berada, dan menggunakan apa pun yang
ditemukannya: workspace tempat file itu berada, atau, jika semuanya gagal, folder itu. File tersebut adalah file yang
disebut --release pada aggrega build dan aggrega pull; Release yang diberikan kepada aggrega validate,
aggrega lint dan aggrega inspect, atau jika tidak, file yang diberikan kepadanya; dan dokumen yang diberikan kepada
aggrega pin, aggrega push dan aggrega edit-document. Jadi Release sebuah proyek yang di-build dari
luar proyek membaca konfigurasi proyek itu sendiri, sama seperti saat perintah dijalankan di dalamnya,
dan peringatan konfigurasi yang dicetak perintah adalah milik workspace tersebut. Jika folder file itu sendiri
juga tidak menjadi jangkar apa pun, folder itulah yang disebut dalam pemberitahuan perintah dan yang tidak ditulisi cache.
Path relatif dibaca terhadap direktori tempat Anda menjalankan perintah dan tidak mengubah
apa pun, dan root yang disebut, atau direktori kerja yang sendirinya berada di dalam workspace, digunakan apa
adanya.
Server asisten menerapkan aturan yang sama pada
panggilan yang menyebut Release atau dokumennya dengan path absolut.
Menandai root dengan blok workspace: adalah pilihan eksplisit dan yang lebih disarankan; penanda file
dan direktori memungkinkan proyek yang belum mendeklarasikannya tetap dapat di-build.
Menyebut file global secara eksplisit
Lapisan global di-resolve dengan urutan berikut:
--config <path>, bentuk per pemanggilan.- Variabel lingkungan
AGGREGA_CONFIG. - Lokasi default: di Windows
aggrega\config.yamldi dalam direktori yang disebut variabel lingkunganAPPDATA, dan di tempat lainaggrega/config.yamldi dalam direktori yang disebutXDG_CONFIG_HOME, dengan fallback ke~/.config/aggrega/config.yaml.
Dua yang pertama menyebut file secara eksplisit, sehingga path yang tidak ada merupakan error yang jelas, bukan
fallback diam-diam — Anda meminta file tertentu. Perintah yang membaca konfigurasinya berhenti
dengan satu kalimat yang diakhiri dengan path tersebut, sehingga Anda dapat menyalinnya. aggrega config init adalah
pengecualian, karena membuat file
tersebut memang tujuannya: perintah ini membuat file yang disebut dan memberitahukannya. Lokasi default dimuat jika
file ada di sana dan dilewati tanpa pemberitahuan jika tidak ada. File mana pun yang ter-resolve, file-file proyek Anda
tetap dilapiskan di atasnya.
Jika tidak satu pun dari ini ter-resolve — tidak ada file yang disebut, dan variabel tempat lokasi default dibaca tidak diatur — perintah yang menulis file global berhenti dan menyebut apa yang perlu diatur. Variabel lingkungan mencantumkan, per platform, variabel tempat setiap lokasi dibaca.
Pilihan itu juga menentukan tempat perintah penulis konfigurasi menulis. Perintah yang dijalankan dengan
--config <path> membaca konfigurasinya dari file itu dan menerapkan perubahannya ke file yang sama,
sehingga apa yang ditulis satu perintah adalah apa yang dibaca kembali oleh perintah berikutnya.
File mana dari keduanya yang ditulisi perintah secara default ditentukan oleh sifat pengaturannya:
perkakas tingkat mesin seperti registry masuk ke file global, sedangkan pengaturan yang ikut serta dalam build
seperti binding provider atau lampiran socket masuk ke file proyek yang di-commit, sehingga
ikut berpindah bersama proyek. Berikan --global atau --workspace untuk menimpanya, dan perintah mencetak
file yang ditulisinya.
Lihat juga
- aggrega-config.md — perintah
aggrega configyang menyemai, memeriksa, dan membekukan konfigurasi. - environment-variables.md — setiap variabel berawalan
AGGREGA_, dan tempat rahasia disediakan. - global-flags.md —
--config,--workspace-root, dan flag lain yang diterima setiap subperintah. - schema/other/aggrega-config.md — setiap kunci konfigurasi, tipenya, dan nilai bawaannya.
- aggrega-cache.md — apa yang sebenarnya disimpan oleh
artifact_cache_dir. - workspace-boundary.md — path mana yang tetap berada di dalam workspace, dan bagaimana direktori dan file yang dinamai konfigurasi ini menjangkau ke luarnya.
- aggrega-mcp.md — server yang dikonfigurasi oleh blok
mcp.