Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

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.yaml
workspace:
catalog_dirs:
- ./catalog
auto_pull: true

Blok 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.

~/.config/aggrega/config.yaml
registries:
- host: hub.aggrega.ai
signing:
required: true

aggrega 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 invalid

Buat 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.yaml
workspace:
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.yaml
workspace: {}
pin_sources_at_pull: true
pin_sources_at_push: true

Setiap 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.yaml
workspace: {}
plugins:
providers:
- capability: helm
uri: provider/helm

Sebuah 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 hlem untuk helm.
  • 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.yaml
workspace: {}
plugins:
importer:
- uri: importer/agent-flows:1.2.0
with:
settings:
target_namespace: payments

aggrega 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 menerima with.sources dan with.settings milik 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:

Terminal window
aggrega config init

Berikan --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, seperti registry: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.yaml
workspace: {}
default_registry: registry.example.com
registries:
- host: registry.example.com
signing:
required: true

Ejaan 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.yaml
workspace: {}
default_registry: ghcr.io/acme
registries:
- host: ghcr.io
signing:
required: true

Path 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.yaml
workspace: {}
default_registry: local
registries:
- name: local
host: 127.0.0.1:5000

Nama 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 default

Flag 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 daftarpendamping append-nya
workspace.catalog_dirscatalog_dirs_append
plugins.governancegovernance_append
plugins.linterlinter_append
plugins.importerimporter_append
plugins.providersproviders_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.yaml
plugins:
linter_append:
- uri: ./lint/api-rules.wasm

Jika 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.yaml
workspace:
releases:
release-compose.yaml:
catalog_dirs:
- ./catalog-compose
release-helm.yaml:
catalog_dirs:
- ./catalog-helm

Setiap 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_dirs menggantikan daftar workspace untuk Release tersebut. Urutan pencarian, direktori catalog yang dibaca setelahnya, dan arti daftar kosong sama seperti untuk daftar milik workspace sendiri.
  • catalog_dirs_append dibaca setelah daftar milik Release. Entri yang hanya menulis catalog_dirs_append mempertahankan 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_dir ditafsirkan 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_DIRS berasal dari environment dan sama sekali tidak memiliki berkas pendeklarasi, jadi berikan path absolut di dalamnya.
  • mcp.listen diambil persis seperti tertulis, termasuk path sistem berkas dalam bentuk unix:<path>. Alamat yang sama juga dapat datang dari aggrega 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.yaml
mcp:
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:7778

mcp.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.yaml yang memuat blok workspace: 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/, lalu aggregate*.yaml, lalu release*.yaml, lalu manifest*.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 antaranya aggrega version, aggrega config show, aggrega plugin list, aggrega registry list, aggrega explain dan aggrega 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:

  1. --config <path>, bentuk per pemanggilan.
  2. Variabel lingkungan AGGREGA_CONFIG.
  3. Lokasi default: di Windows aggrega\config.yaml di dalam direktori yang disebut variabel lingkungan APPDATA, dan di tempat lain aggrega/config.yaml di dalam direktori yang disebut XDG_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