Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Konfiguracja

Skąd aggrega odczytuje swoje ustawienia i w którym pliku należy umieścić dane ustawienie.

Przypadek prosty

Dwa pliki — i większość projektów nie potrzebuje niczego więcej.

Jeden plik w projekcie, o nazwie .aggrega-config.yaml, umieszczony w katalogu głównym projektu. Określa, jak buduje się ten projekt: które katalogi zawierają dołączoną treść katalogu, które pluginy renderują które cele, które reguły lintera są złagodzone, gdzie trafia lokalna pamięć podręczna. Jest commitowany, więc współpracownik, który sklonuje projekt, zbuduje go w ten sam sposób.

To jego blok workspace: oznacza katalog jako katalog główny projektu:

# <project>/.aggrega-config.yaml
workspace:
catalog_dirs:
- ./catalog
auto_pull: true

Blok zawiera wyłącznie katalogi katalogu definiujące katalog główny; każde inne ustawienie znajduje się na najwyższym poziomie obok niego. Projekt, który nie dołącza żadnej treści katalogu, nadal zapisuje ten blok, pusty — workspace: {} — ponieważ znacznikiem jest sama obecność bloku.

Jeden plik globalny na komputerze, w ~/.config/aggrega/config.yaml — w systemie Windows w pliku aggrega\config.yaml w katalogu wskazanym przez zmienną środowiskową APPDATA. Przez niego rozwiązywany jest każdy obszar roboczy na tym komputerze, a zawiera on ustawienia należące do komputera, a nie do żadnego konkretnego projektu — rejestry, z których się pobiera, i politykę zaufania do podpisów dla każdego z nich, maksymalny rozmiar magazynu skompilowanych modułów oraz wszelkie zainstalowane pluginy rozszerzające polecenia. Są one takie same niezależnie od miejsca pracy, dlatego chodzi właśnie o to, by zadeklarować je raz. Plik ładuje się automatycznie, gdy istnieje, a gdy go nie ma, nic się nie psuje.

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

aggrega config init zapisuje ten plik globalny, rejestrując rejestr wraz z polityką zaufania do podpisów, którą ten rejestr ogłasza, i informuje, gdzie plik znajduje się na komputerze oraz gdzie przechowywane są pamięci podręczne całego komputera. aggrega config show wypisuje to, co obowiązuje w danej chwili, a aggrega config show --origin informuje, który plik — lub która zmienna środowiskowa — przesądził o każdym ustawieniu.

Sekrety nie są konfiguracją. Hasło do rejestru i token tożsamości podpisującej nigdy nie są polami w żadnym z plików; podaje się je zmienną środowiskową lub flagą w chwili, gdy są potrzebne. Zob. environment-variables.md.

Skąd odczytywane są lokalne encje

Projekt, który utrzymuje własną treść katalogu — encję Component, Feature, Recipe lub jeden z rodzajów bibliotek — ma dwa sposoby wskazania, gdzie ta treść się znajduje, a pierwszy nie wymaga żadnej konfiguracji.

Katalog catalog w katalogu głównym projektu jest odczytywany niezależnie od tego, czy cokolwiek go wskazuje. Encję umieszczoną w <project>/catalog/ odczytuje każde polecenie ładujące katalog, także w projekcie, którego blok workspace: jest pusty. Katalog jest odczytywany rekurencyjnie, więc układ podkatalogów wewnątrz niego zależy od autora.

Katalogi wymienione w workspace.catalog_dirs są odczytywane również, i to w pierwszej kolejności. Lista jest uporządkowanym stosem wyszukiwania: pierwszy katalog, który deklaruje daną tożsamość, staje się jej właścicielem, a ta sama tożsamość w późniejszym katalogu zostaje przesłonięta. catalog jest odczytywany po wszystkich wymienionych — chyba że któryś z wymienionych katalogów już go zawiera, a wtedy jest odczytywany jako część tego katalogu — więc wymienienie katalogu rozszerza dotychczasowy zestaw, a nie go zastępuje. Powtarzalna flaga --catalog <dir> w wierszu poleceń jest odczytywana przed obydwoma, a podana w niej ścieżka względna jest rozwiązywana względem katalogu, z którego uruchomiono polecenie, ponieważ nie zadeklarował jej żaden plik konfiguracyjny. Katalog wskazany więcej niż raz — w wierszu poleceń i na liście albo dwukrotnie na liście — jest odczytywany raz, w miejscu, w którym wskazano go po raz pierwszy, więc nic w nim nie jest zgłaszane jako przesłonięte przez samo siebie: przesłonięcie to zawsze dwa różne pliki deklarujące jedną tożsamość. Dwa zapisy tego samego katalogu, ścieżka do niego przez dowiązanie oraz — w systemie plików ignorującym wielkość liter — zapis inną wielkością liter wskazują ten sam katalog. Katalog znajdujący się wewnątrz innego wymienionego katalogu jest nadal odczytywany jako osobna pozycja. Projekt, który utrzymuje wariant katalogu dla każdej encji Release, może zamiast tego nadać każdej encji Release własną listę — zob. Nadawanie encji Release własnych katalogów katalogu.

Wymienienie katalogu to sposób, w jaki projekt odczytuje encje przechowywane poza nim. Wymieniony katalog może leżeć gdziekolwiek — w sąsiednim checkoucie, w katalogu współdzielonym z innymi projektami — i jest odczytywany tam, gdzie się znajduje, nawet jeśli sam jest dowiązaniem symbolicznym. Nic innego nie sięga tak daleko: dowiązanie wewnątrz projektu prowadzące gdzie indziej nie jest śledzone, a dokument wskazujący ścieżką plik spoza projektu jest odrzucany, więc do encji przechowywanej gdzie indziej dociera się, wymieniając zawierający ją katalog i wskazując encję jej nazwą. Wymieniony katalog spoza projektu jest osobnym korzeniem, więc dowiązanie pod nim wyprowadzające poza niego również nie jest odczytywane. Pełną regułę podaje Granica obszaru roboczego.

Wymieniony katalog musi być katalogiem. Wymieniona ścieżka, pod którą nic nie istnieje albo pod którą znajduje się plik lub dowiązanie prowadzące donikąd, jest odrzucana, zanim cokolwiek zostanie odczytane lub zapisane, przez każde polecenie odczytujące katalog encji — pobranie, budowanie, walidację, inspekcję, lint oraz te same operacje uruchamiane z edytora przez aggrega serve lub z asystenta przez aggrega mcp — więc budowanie nigdy nie jest uruchamiane na mniejszej liczbie katalogów, niż wymieniono. Odrzucenie wskazuje wpis w zapisanej postaci, ścieżkę, na którą został rozwiązany, plik konfiguracyjny i wiersz, które go wymieniają, oraz listę, w której się znajduje:

<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

Należy utworzyć katalog albo usunąć wpis: kopia projektu wykonana bez sąsiedniego checkoutu, który projekt wymienia, usuwa ten wpis i rozwiązuje z rejestru to, co ten checkout by dostarczył. To samo dotyczy katalogu wymienionego we własnym wpisie encji Release, katalogu dodanego przez plik konfiguracyjny należący do potoku albo przez plik globalny oraz katalogu przekazanego w zmiennej AGGREGA_CATALOG_DIRS, którą odrzucenie wskazuje zamiast pliku. Sama konfiguracja nadal się wczytuje, więc polecenie, które nie odczytuje żadnego katalogu encji, nadal działa. Nieistniejący katalog --catalog został wpisany dla jednego polecenia i aggrega build go odrzuca, wskazując ten katalog. Wymieniony katalog, który istnieje, ale nie może zostać odczytany, jest odrzucany przez polecenia wczytujące cały katalog encji, które go wskazują.

Zapisanie pustej listy oznacza, że projekt nie ma w ogóle lokalnego katalogu, i jest to jedyny zapis, który powstrzymuje także odczyt catalog:

# <project>/.aggrega-config.yaml
workspace:
catalog_dirs: []

Pominięcie klucza oznacza coś innego: pominięta lista to zwykły przypadek, a catalog jest nadal odczytywany.

Budowanie, pobranie, walidacja lub aggrega inspect, które nie znajdą encji o użytej nazwie, informują, skąd projekt odczytuje lokalne encje i co zmienić, aby wskazana encja została odczytana. Nie mówią nic takiego, gdy zapisano pustą listę — brak odczytu lokalnego katalogu został tam zadeklarowany, a sugestia jego zmiany byłaby sprzeczaniem się z użytkownikiem. Nie mówią tego również, gdy dokument deklarujący tę nazwę został odczytany i odrzucony: ten dokument już znajduje się tam, skąd katalog czyta, więc raport wskazuje zamiast tego, co dokument narusza — wiersz i ograniczenie — a przeniesienie go niczego by nie naprawiło. Dokumentu tak zniekształconego, że deklarowanej w nim nazwy w ogóle nie da się odczytać, nie można dopasować do użytej nazwy, więc opis jest mimo to podawany — a gdy ten dokument deklaruje apiVersion Aggrega, budowanie, pobranie lub walidacja encji Release wymienia go obok opisu, wraz z powodem podanym przez sam parser, ponieważ może to być plik, który należy otworzyć. Błąd, w którym encję znaleziono, ale nie można jej było przyjąć — rejestr serwujący teraz inne bajty pod wersją przypiętą w lockfile’u, plik, który encja zawiera, a którego nie można odczytać — również nie jest brakiem encji i zgłasza wyłącznie własny sposób naprawy.

Czy pobranie lub wypchnięcie przypina encję

Encja Recipe lub FeatureRecipe przechowuje przypięcia odczytywanych przez siebie wejść — zdalnego source: zapisanego w całości, pliku importowanego przez pozycję artifacts, plików source: obok niej — w entity.lock obok niej, a ich zapisanie to krok autora encji, aggrega pin. Domyślnie ani pull, ani push nie wykonuje tego kroku: pobranie zatrzymuje się na encji, której lock jej nie przypina, a wypchnięcie odmawia jej opublikowania. Dwa klucze, po jednym na polecenie, sprawiają, że wykonanie tego kroku staje się domyślne dla danego polecenia:

# <project>/.aggrega-config.yaml
workspace: {}
pin_sources_at_pull: true
pin_sources_at_push: true

Każdy klucz steruje własnym poleceniem i niczym więcej, a flaga --pin-sources każdego polecenia nadpisuje jego klucz w obu kierunkach — --pin-sources=false wyłącza ten krok na jedno uruchomienie w projekcie skonfigurowanym do przypinania. Budowanie, które wypełnia własny lockfile, jest pobraniem i podlega pin_sources_at_pull. Klucze te należą do pliku projektu, a nie do globalnego: to, czy pobrania projektu zapisują przypięcia, jest polityką tego projektu, a współpracownik, który go sklonuje, powinien otrzymać taki sam wynik. pin_sources_at_pull pozwala też projektowi korzystającemu z cudzego nieprzypiętego katalogu zapisać te przypięcia raz, zamiast zatrzymywać się przy każdym pobraniu.

Który plugin renderuje daną funkcjonalność

Encja Recipe wskazuje funkcjonalność, przez którą renderuje — capability: helm — a renderuje ją plugin obsługujący tę funkcjonalność. Gdy daną funkcjonalność obsługuje dokładnie jeden plugin, nie trzeba niczego konfigurować. Gdy obsługuje ją więcej niż jeden, wpis plugins.providers wskazuje który, za pomocą tożsamości pluginu:

# <project>/.aggrega-config.yaml
workspace: {}
plugins:
providers:
- capability: helm
uri: provider/helm

Pull rozwiązuje wpis i zapisuje wybrany plugin w pliku lock encji Release, a build renderuje przez to, co zapisano w pliku lock, więc zmiana w tym miejscu zaczyna obowiązywać przy następnym pullu.

Pole uri wskazuje plugin za pomocą jego tożsamości, provider/<name>, nigdy za pomocą miejsca, w którym go opublikowano. aggrega plugin add provider <query> --capability <capability> zapisuje wpis w tej formie, bez wersji: wpis wybiera, który plugin obsługuje daną funkcjonalność, wersją jest ta, którą przypina encja Recipe, a w przeciwnym razie najwyższa dostępna, a plik lock zapisuje tę, którą wybrał pull. Plugin wbudowany w kompilator jest udostępniany w wersji samego kompilatora, więc wersja zapisana we wpisie dla takiego pluginu zostaje rozwiązana tylko wtedy, gdy jest właśnie tą wersją. Wpis, którego uri jest lokalizacją w rejestrze — oci://hub.aggrega.ai/plugin/provider/helm — nie wskazuje tożsamości żadnego pluginu i jest odrzucany przy wczytywaniu pliku, z podaniem wpisu i formy, którą należy zapisać.

Wpisy są zapisywane raz dla całego projektu, a build dotyczy jednej encji Release, więc wpis dla funkcjonalności, o którą ta encja Release nigdy nie prosi, jest dozwolony — odczytuje go inna encja Release w projekcie — i nie jest w ogóle zgłaszany. Każdy build i każde aggrega validate --release sprawdza natomiast każdy wpis, niezależnie od tego, czy jakakolwiek encja Recipe prosi o jego funkcjonalność, według tego, co wpis wskazuje:

  • Wpis wskazujący plugin, który nie obsługuje jego funkcjonalności, zatrzymuje build i powoduje niepowodzenie walidacji. Pull rozwiązuje każdy wpis wskazujący plugin i odrzuca taki, którego nie potrafi rozwiązać, więc gdy wpis przeszedł już przez pull, build ma jego plugin i wie, co on obsługuje; wpis wskazujący plugin, którego build jeszcze nie ma, jest oceniany, gdy pull go pobierze. Komunikat wskazuje wpis, plugin, to, co ten plugin faktycznie obsługuje, oraz pisownię różniącą się o jedną edycję, jeśli taka istnieje — taką postać przybiera literówka w rodzaju hlem zamiast helm.
  • Wpis wskazujący tylko funkcjonalność, której nie obsługuje żaden plugin odczytywany przez build, jest ostrzeżeniem, a build jest kontynuowany. Plugin, który ją obsługuje, może być odczytywany tylko przez inną encję Release, której ten build nie widzi, a wpis niewskazujący żadnego pluginu nie wybiera niczego, czego rozwiązanie funkcjonalności nie wybrałoby bez niego.

Funkcjonalność w tym miejscu nigdy nie zawiera dwukropka, a taka, która go zawiera, jest odrzucana przy wczytywaniu pliku. Pole capability: encji Recipe jest odczytywane jako funkcjonalność do ostatniego dwukropka i przypięcie wersji po nim, więc wpisu o kluczu helm:1.0.0 nigdy nie dałoby się odnaleźć. Wersję należy zamiast tego przypiąć w pluginie — uri: provider/helm:1.0.0 — lub w encji Recipe.

Który importer przekształca źródło w szkice

aggrega import przekazuje źródło importerowi, który deklaruje format tego źródła — jednemu z katalogu lub jednemu z importerów podstawowych kompilatora, import:langflow dla przepływu Langflow. Gdy format deklaruje dokładnie jeden importer, nie trzeba niczego konfigurować. Wpis plugins.importer dołącza importer, wskazując go w swoim uri przez jego tożsamość i wersję, i przekazuje mu to, co zawiera pod with:

# <project>/.aggrega-config.yaml
workspace: {}
plugins:
importer:
- uri: importer/agent-flows:1.2.0
with:
settings:
target_namespace: payments

aggrega plugin add importer zapisuje uri dokładnie w tej postaci. Wersja jest dokładna — :1.2.0 — lub jest zakresem — :^1.2.0 dla najwyższej wersji równej jej lub wyższej w obrębie tej samej wersji głównej. Należy zapisać jedno albo drugie: na tej liście uri bez dwukropka jest odczytywane jako ścieżka w systemie plików, jak opisuje Gdzie wskazuje ścieżka względna, i nie wskazuje żadnego importera.

Działanie wpisu zależy od tego, czy wskazany w nim importer deklaruje format, o który prosi import:

  • Deklaruje: uruchamiany jest ten importer, w wersji wskazanej przez uri, niezależnie od tego, ile innych importerów w katalogu również deklaruje ten format, i otrzymuje on with.sources oraz with.settings wpisu. Za pomocą wpisu obszar roboczy, którego katalog federuje importery dwóch wydawców dla jednego formatu, wskazuje, którego z nich używa.
  • Nie deklaruje — wskazuje importer innego formatu, plugin innego rodzaju albo nic, co zawiera katalog lub co dostarcza kompilator: wpis nie bierze udziału w tym imporcie. Niczego nie wybiera, a jego with nie jest przekazywane żadnemu importerowi. Ustawienia wpisu trafiają tylko do wskazanego w nim importera, więc obszar roboczy dołączający po jednym importerze na format konfiguruje każdy z nich bez przenikania ustawień jednego do drugiego.

Gdy format deklaruje więcej niż jeden importer, a żaden pojedynczy z nich nie jest dołączony — nie jest żaden albo wpisy wskazują dwa z nich — import jest odrzucany z podaniem importerów, między którymi nie mógł wybrać. Wpis wskazujący importer deklarujący format, w wersji, której nie spełnia żadna jego wersja w katalogu — dokładnej wersji, której katalog nie zawiera, lub zakresu, w który nie wpada żadna z jego wersji — również jest odrzucany z podaniem wersji, zamiast uruchomienia w jej miejsce innej wersji; wersja, która w ogóle nie jest wersją, na przykład :latest, jest odrzucana jako niepoprawna. Encja Plugin jednego z podstawowych importerów kompilatora bez modułu obok niej w jej folderze katalogu nie jest kandydatem: w wersji samego kompilatora zamiast niej działa importer podstawowy, a w każdej innej wersji encja pozostaje kandydatem tylko wtedy, gdy wpis wskazuje dokładnie tę wersję albo gdy żaden importer o jej nazwie, który może zostać uruchomiony, nie deklaruje formatu, jak opisuje Który z nich działa obok własnych importerów.

Każdy importer jest dołączany jednym wpisem. Dwa wpisy wskazujące jeden importer — tę samą tożsamość, w jednej wersji lub w dwóch — są odrzucane przy wczytywaniu konfiguracji, niezależnie od polecenia, które ją odczytuje, z podaniem obu wpisów i plików, w których je zapisano. Reguła obejmuje każdy plik, który wnosi coś do listy: wpis w pliku globalnym, wpis w pliku projektu, wpis pod importer_append i wpis w .aggrega-config-append-ci.yaml potoku — wszystkie się liczą, więc przeniesienie importera na nową wersję oznacza zmianę wersji w jego jedynym wpisie. aggrega plugin add importer robi dokładnie to, gdy lista plugins.importer w zapisywanym przez nie pliku już wskazuje ten importer: przenosi ten wpis na rozwiązaną wersję, zachowując miejsce wpisu i jego with, zamiast dodawać drugi. Nie odczytuje żadnej innej listy, więc importer dołączony pod importer_append lub w .aggrega-config-append-ci.yaml potoku zostaje przez to polecenie dołączony po raz drugi, a para jest odrzucana przy wczytywaniu konfiguracji; wersję takiego wpisu należy zmienić tam, gdzie go zapisano. Wpis, którego uri jest ścieżką w systemie plików, nie wskazuje żadnego importera i nie jest porównywany, a listy plugins.governance i plugins.linter nie podlegają tej regule: jeden plugin może być do nich dołączony więcej niż raz, za każdym razem z własnym with.

Parsery, przez które czyta import, nie wymagają wpisu. Importer odczytuje swoje źródło — a import niewskazujący formatu go rozpoznaje — przez parser składni źródła: ten, który katalog udostępnia dla tej składni, a dla składni, dla której katalog nie udostępnia parsera, ten, który dostarcza sam kompilator, w tym JSON. Dlatego obszar roboczy, którego katalog nie zawiera parsera, importuje przepływ Langflow lub Flowise bez żadnej konfiguracji. Żadna lista nie dołącza parsera: używany jest parser, który katalog udostępnia dla składni, a dwa parsery o różnych nazwach obsługujące jedną składnię są odrzucane, jak opisuje A parse or import format is advertised by more than one plugin (Format parsowania lub importu jest deklarowany przez więcej niż jeden plugin).

Start od zera

Świeżo zainstalowany aggrega nie ma żadnego z tych plików i jest to stan działający, a nie wadliwy: każde ustawienie przyjmuje wbudowaną wartość domyślną, a polecenia działają. Brakuje rejestru, z którego można pobierać zawartość katalogu, wraz z polityką zaufania określającą, które podpisy akceptować — i dokładnie to zapisuje aggrega config init.

Nie trzeba tego wiedzieć z góry. Polecenie, które odczytuje konfigurację i nigdzie nie znajduje pliku, informuje o tym raz, na standardowym wyjściu błędów, i wskazuje aggrega config init jako sposób jego utworzenia. Jest to porada, a nie błąd: standardowe wyjście pozostaje nienaruszone, nie jest zadawane żadne pytanie, a kod wyjścia jest taki, jaki polecenie zgłosiłoby i tak. Komunikat jest wypisywany tylko wtedy, gdy standardowe wyjście błędów jest terminalem, więc dociera do osoby przy klawiaturze i nigdy nie gromadzi się w logu potoku. Gdy istnieje którykolwiek z plików — plik projektu lub globalny — komunikat przestaje się pojawiać.

Aby zainicjować plik globalny oficjalnym hubem i polityką zaufania, którą ten hub deklaruje:

Terminal window
aggrega config init

Opcja --registry <host> inicjuje inny rejestr, --workspace zapisuje wpis w pliku tego projektu zamiast w pliku globalnym, a --dry-run pokazuje treść, która zostałaby zapisana, bez tworzenia czegokolwiek. aggrega-config.md opisuje polecenie w całości.

Jak zapisuje się host rejestru

Każde registries[].host wskazuje host rejestru. Podobnie default_registry — opcjonalnie z następującą po nim ścieżką repozytorium — chyba że zamiast tego wskazuje jeden z tych wpisów (zob. niżej). Host zapisuje się jako sam host, w jedynej pisowni, pod którą przechowywana jest polityka zaufania rejestru:

  • nazwa hosta pisana małymi literami i zawierająca kropkę, np. registry.example.com;
  • localhost lub pojedyncza nazwa z następującym po niej portem, np. registry:5000;
  • adres IPv4, np. 127.0.0.1, lub adres IPv6 w nawiasach kwadratowych, np. [::1];

każda z opcjonalnym :port i niczym więcej — bez schematu, bez ścieżki, bez poświadczeń, bez białych znaków i bez wielkich liter. Pojedyncza nazwa bez portu nie jest hostem rejestru, ponieważ ma kształt pierwszego segmentu nazwy encji katalogu — core w core/web-api — a tych dwóch nie wolno nigdy pomylić.

# <project>/.aggrega-config.yaml
workspace: {}
default_registry: registry.example.com
registries:
- host: registry.example.com
signing:
required: true

Pisownia jest częścią polityki. Wpis registries dotyczy hosta wskazanego przez jego host:, a wbudowany wymóg podpisu oficjalnego huba dotyczy hub.aggrega.ai, więc host zapisany w jakikolwiek inny sposób trafiłby do właściwego rejestru, ale ominąłby zapisaną dla niego politykę. Dlatego zamiast tego jest odrzucany podczas wczytywania konfiguracji, a odmowa wskazuje pisownię, której należy użyć: HUB.AGGREGA.AI i https://registry.example.com są odrzucane ze wskazaniem hub.aggrega.ai i registry.example.com, podobnie jak registry.example.com/charts jako registries[].host, które nie zawiera ścieżki. Port 443 jest domyślnym portem hosta osiąganego przez HTTPS, więc hub.aggrega.ai:443 jest odrzucany w ten sam sposób, ze wskazaniem hub.aggrega.ai. localhost i inne adresy pętli zwrotnej są natomiast osiągane przez zwykły HTTP, gdzie 443 jest zwykłym portem, więc localhost:443 jest akceptowany w zapisanej postaci. Puste default_registry nie wskazuje żadnego domyślnego rejestru.

default_registry może zawierać ścieżkę repozytorium. Wiele rejestrów przechowuje każde repozytorium pod właścicielem lub projektem — ghcr.io/<owner>, <host>/<project> w Harbor — a domyślny rejestr w jednym z nich zapisuje się jako host, po którym następuje ta ścieżka:

# <project>/.aggrega-config.yaml
workspace: {}
default_registry: ghcr.io/acme
registries:
- host: ghcr.io
signing:
required: true

Ścieżka to miejsce, w którym treści są publikowane i z którego są pobierane. Przy tym ustawieniu domyślnym aggrega push publikuje core/api-server w wersji 1.0.0 pod ghcr.io/acme/component/core/api-server:1.0.0, a pull rozwiązujący core/api-server pobiera go z tego samego miejsca, więc podpis dołączony przy publikacji również jest tam znajdowany. Ścieżka jest ścieżką repozytorium w gramatyce dystrybucji OCI: jeden lub więcej segmentów złożonych z małych liter i cyfr, połączonych znakiem /, które wewnątrz segmentu mogą być rozdzielone przez ., _, __ lub myślniki, bez tagu, skrótu (digest) ani końcowego /.

Ścieżka nigdy nie wpływa na sposób, w jaki rejestr jest obdarzany zaufaniem. Wpis registries, którego polityka ma zastosowanie, poświadczenie przechowywane przez aggrega login, wymóg podpisywania i zaufane tożsamości są wyszukiwane wyłącznie po hoście, więc powyższy wpis dla ghcr.io obejmuje ghcr.io/acme i każdą inną ścieżkę na tym hoście, a żadna pisownia ścieżki nie pozwala go obejść; samo host: wpisu nie zawiera ścieżki. Host zapisany w innej pisowni przed ścieżką jest odrzucany ze wskazaniem lokalizacji, którą należy zapisać — GHCR.io/acme i https://ghcr.io/acme wskazują ghcr.io/acme — a to, co następuje po hoście, jeśli nie jest ścieżką repozytorium, jest odrzucane ze wskazaniem hosta, po którym następuje.

default_registry może zamiast tego wskazywać wpis. Zapisane jako name: wpisu w registries oznacza host: tego wpisu. Publikowanie, pobieranie, weryfikacja podpisów i każde ustawienie zaufania dla danego rejestru używają wtedy tego hosta, a żadna treść nie jest pobierana z hosta zapisanego tak jak ta nazwa:

# <project>/.aggrega-config.yaml
workspace: {}
default_registry: local
registries:
- name: local
host: 127.0.0.1:5000

Nazwa jest dopasowywana przed pisownią hosta, tak jak dopasowuje ją flaga --registry, więc wartość będąca name: wpisu oznacza ten wpis nawet wtedy, gdy jest również zapisana jak host. Nazwa występująca w dwóch wpisach jest odrzucana jako niejednoznaczna, ze wskazaniem obu hostów. Wpis może znajdować się w dowolnym z plików — default_registry projektu może wskazywać wpis zadeklarowany w pliku globalnym — ponieważ nazwa jest odczytywana jednokrotnie, względem wpisów obowiązujących po odczytaniu wszystkich plików i środowiska. Wartość, która nie jest ani nazwą wpisu, ani hostem rejestru — samodzielnie lub z następującą po nim ścieżką repozytorium — jest odrzucana, a odmowa informuje, że naprawi to jedno lub drugie. Nazwa z następującą po niej ścieżką, np. local/acme, również jest odrzucana: nazwa oznacza host swojego wpisu, a nie lokalizację pod nim, więc odmowa wskazuje dwie pisownie, których można użyć zamiast tego — local albo host wpisu z następującą po nim ścieżką, 127.0.0.1:5000/acme. Usunięcie wpisu za pomocą aggrega registry remove pozostawia default_registry w zapisanej postaci, więc wartość domyślna, która wskazywała usunięty wpis, nie wskazuje potem niczego i jest odrzucana, dopóki nie zostanie zapisana na nowo.

Każda warstwa podlega tej samej pisowni. Wartość jest odrzucana tymi samymi słowami niezależnie od tego, czy pochodzi z pliku konfiguracyjnego, z AGGREGA_DEFAULT_REGISTRY, czy z flagi --registry wskazującej miejsce docelowe jednego aggrega push lub aggrega push-artifact. Ta flaga wskazuje host, a kierowana przez nią publikacja trafia do tego hosta bez ścieżki repozytorium: ścieżka należy do default_registry. aggrega registry add i aggrega config init --registry również stosują tę zasadę do otrzymanego hosta; przyjmują też w jego miejsce referencję i zapisują wpis pod hostem, który ta referencja wskazuje. Odmowa dotycząca pliku wskazuje plik i klucz; odmowa dotycząca środowiska wskazuje zmienną. Schemat określa kształt hosta jako wzorzec dla registries[].host i nie określa żadnego dla default_registry, którego wartością może być nazwa dowolnego wpisu — więc edytor czytający sam schemat nie oznacza błędnie wpisanej wartości domyślnej, a odrzuca ją dopiero wczytanie konfiguracji.

Host jest oceniany wyłącznie po pisowni, podobnie jak ścieżka. Podczas wczytywania konfiguracji nie jest sprawdzane, czy nazwa się rozwiązuje, czy pod nią odpowiada rejestr ani czy ścieżka na nim istnieje.

Co nadpisuje co

CLI flag > environment variable > configuration file > built-in default

Flaga jest najbardziej jawnym sygnałem i wygrywa bezwzględnie. Zmienna środowiskowa nadpisuje zatwierdzony plik, co pozwala potokowi zmienić ustawienie bez edytowania śledzonego pliku. Zmienna nieustawiona — lub ustawiona na pusty ciąg — przechodzi do niższej warstwy, zamiast czyścić skonfigurowaną wartość. Spośród dwóch plików plik projektu wygrywa z plikiem globalnym.

Flaga wygrywa dlatego, że została wpisana, a nie z powodu niesionej wartości, a w przypadku ustawienia typu prawda/fałsz decyduje to o tym, czy górna warstwa jest użyteczna, czy nie ma jej wcale. --offline włącza ten tryb na jedno uruchomienie; --offline=false wyłącza go na jedno uruchomienie tam, gdzie włączył go zatwierdzony plik lub wyeksportowana zmienna. Warstwa, która odczytywałaby tylko wartość, nie odróżniłaby „wyłączone” od „niewspomniane”, więc każde polecenie wyglądałoby tak, jakby zażądało domyślnej wartości flagi, i nie byłoby w ogóle sposobu na unieważnienie skonfigurowanego ustawienia.

To cały model dla pojedynczego projektu na pojedynczej maszynie. Wszystko, co opisano poniżej, istnieje dla projektów, które go przerastają.

Poza dwoma plikami

Te mechanizmy są przeznaczone dla większych struktur — monorepo powiązanych projektów, potoku, który wnosi własne ustawienia, współdzielonego katalogu rozszerzanego przez kilka projektów. Po dany mechanizm warto sięgnąć wtedy, gdy występuje problem, który on rozwiązuje.

Więcej niż jeden plik konfiguracyjny w projekcie

Każdy plik .aggrega-config.yaml od katalogu głównego projektu aż do katalogu, w którym uruchomiono polecenie, wnosi swój wkład, a plik bliższy nadpisuje plik dalszy. Podprojekt może więc mieć własny plik, który dostosowuje to, co zadeklarował katalog główny, bez powtarzania tego.

Katalog główny wyznacza tylko plik zawierający blok workspace:. Plik bez takiego bloku nadal wnosi swoje ustawienia — po prostu nie czyni swojego katalogu katalogiem głównym projektu, dzięki czemu plik ustawień podprojektu nie przedefiniowuje miejsca, w którym zaczyna się projekt.

Przekazanie --workspace-root zmienia to, a także pomija wykrywanie: zbierany jest wyłącznie plik konfiguracyjny wskazanego katalogu głównego, więc pliki w katalogach poniżej niego nie wnoszą wkładu. Dzięki temu konfiguracja przypiętego katalogu głównego jest taka sama niezależnie od tego, skąd uruchomiono polecenie.

Każdy zebrany w ten sposób plik jest odczytywany z wnętrza projektu. Plik będący dowiązaniem symbolicznym prowadzącym poza projekt — lub znajdujący się w katalogu osiągniętym przez takie dowiązanie — nie jest odczytywany, a każde polecenie, które odczytuje konfigurację, zatrzymuje się na nim, wskazując dowiązanie, zamiast konfigurować projekt na podstawie pozostałych plików; to samo dotyczy pliku potoku, opisanego niżej. Nieliczne polecenia, które nigdy jej nie odczytują, takie jak aggrega version i aggrega help, działają z ostrzeżeniem wskazującym dowiązanie. Serwer językowy edytora i narzędzia asystenta odczytują konfigurację w ten sam sposób i mimo to uruchamiają się dla takiego projektu, aby można go było wylistować: ich listy encji Release i encji odpowiadają, odczytane bez żadnej konfiguracji, i wymieniają plik wśród nieodczytanych dowiązań, natomiast każde inne żądanie, o którym decyduje konfiguracja, zatrzymuje się na nim, wskazując dowiązanie. Konfigurację przechowywaną poza projektem odczytuje się, wskazując ją jako plik globalny, jak opisano w sekcji Jawne wskazanie pliku globalnego. Zob. Granica przestrzeni roboczej.

Rozszerzanie listy zamiast jej zastępowania

Ustawienie o wartości listowej zachowuje się jak każde inne ustawienie: wartość z bliższego pliku zastępuje wartość z dalszego. Aby dodać coś do tego, co zadeklarował plik zewnętrzny, zamiast powtarzać to od nowa, należy użyć towarzyszącego mu ustawienia dołączającego:

ustawienie listowejego ustawienie dołączające
workspace.catalog_dirscatalog_dirs_append
plugins.governancegovernance_append
plugins.linterlinter_append
plugins.importerimporter_append
plugins.providersproviders_append

Wpisy w ustawieniu dołączającym są doklejane do rozwiązanej listy na każdej warstwie, zamiast ją przesłaniać, więc podprojekt dodaje linter do tego, co zadeklarował już katalog główny:

# <project>/services/api/.aggrega-config.yaml
plugins:
linter_append:
- uri: ./lint/api-rules.wasm

Jeśli jeden plik ustawia zarówno listę bazową, jak i jej ustawienie dołączające, wartością tego pliku jest lista bazowa, po której następują dołączone wpisy.

Blok workspace: jest wyjątkiem co do miejsca, w którym można zapisać ustawienie dołączające. Plik zawierający ten blok wyznacza swój katalog jako katalog główny projektu, więc plik podprojektu, który zapisałby workspace.catalog_dirs_append, rozpocząłby własny projekt, zamiast uzupełniać projekt nadrzędny. Ustawienie dołączające dla katalogów katalogu łączy się między plikiem globalnym a plikiem głównym projektu.

Lista plugins.cli sama łączy się między plikami i nie ma ustawienia dołączającego: rozszerzenie poleceń zadeklarowane w pliku globalnym rejestruje swoje polecenie w każdym projekcie, rozszerzenie zadeklarowane w projekcie rejestruje je tylko tam, a oba rejestrują się razem. Każdy wpis przypina jedną wtyczkę: uri, które rozwiązuje, oraz digest bajtów zweryfikowanych przez aggrega plugin add cli, zapisany jako sha256:, po którym następują 64 cyfry szesnastkowe pisane małymi literami. Skrót zapisany w jakiejkolwiek innej pisowni nigdy nie mógłby być równy skrótowi rozwiązanych bajtów, więc jest odrzucany podczas wczytywania pliku, ze wskazaniem pliku i wpisu.

Własne katalogi katalogu dla encji Release

Projekt może przechowywać obok siebie kilka wariantów katalogu — po jednym na cel, z których każdy zawiera Recipes renderujące te same Components dla innego dostawcy — i budować każdą encję Release względem jednego z nich. Należy wskazać każdą encję Release w workspace.releases i nadać jej własne catalog_dirs:

# <project>/.aggrega-config.yaml
workspace:
releases:
release-compose.yaml:
catalog_dirs:
- ./catalog-compose
release-helm.yaml:
catalog_dirs:
- ./catalog-helm

Każdy klucz jest plikiem Release zapisanym względem pliku konfiguracyjnego, który go wskazuje. Klucz — taki jak build.authoring_release — może wskazywać encję Release przechowywaną poza projektem, a wskazanie jej tutaj jest sposobem, w jaki projekt do niej sięga: dowiązanie wewnątrz projektu prowadzące do niej jest odczytywane, a nie pomijane, jak opisano w sekcji Granica przestrzeni roboczej. Dwa klucze pod nim znaczą to samo co w bloku workspace:, z zakresem ograniczonym do tej jednej encji Release:

  • catalog_dirs zastępuje listę przestrzeni roboczej dla tej encji Release. Kolejność wyszukiwania, katalog catalog odczytywany po niej i znaczenie pustej listy są takie same jak dla listy samej przestrzeni roboczej.
  • catalog_dirs_append jest odczytywane po liście encji Release. Wpis zawierający tylko catalog_dirs_append zachowuje listę przestrzeni roboczej i ją uzupełnia.

Encja Release, której mapa nie wskazuje, odczytuje własne workspace.catalog_dirs przestrzeni roboczej. Encja Release wskazana w mapie odczytuje własne katalogi niezależnie od sposobu budowania — aggrega build lub aggrega pull w terminalu, edytor przez aggrega serve, asystent przez aggrega mcp — więc żaden z nich nie potrzebuje flagi, aby znaleźć swój katalog. --catalog <dir> w wierszu poleceń jest nadal przeszukiwany przed katalogami encji Release, dla tego jednego wywołania. A wyszukiwanie, które nie znajduje encji o użytej nazwie, wskazuje wpis tej encji Release jako miejsce, w którym należy wymienić katalog ją zawierający.

Wpis wskazujący nieistniejący plik jest odrzucany podczas wczytywania konfiguracji, ze wskazaniem wpisu i pliku. Zmiana nazwy encji Release zatrzymuje więc każde polecenie, dopóki wraz z nią nie zmieni się nazwy wpisu, zamiast pozwolić encji Release budować się względem listy przestrzeni roboczej bez żadnej informacji o tym. Katalog wymieniony we wpisie musi być katalogiem, tak jak katalog wskazany na liście przestrzeni roboczej: taki, który nim nie jest, jest odrzucany przez każde polecenie odczytujące katalog tej encji Release, ze wskazaniem wpisu i jego wiersza.

To, co nie dotyczy żadnej pojedynczej encji Release, nadal odczytuje listę przestrzeni roboczej: lint lub walidacja całego katalogu, wyszukiwanie encji po nazwie, encja Aggregate badana samodzielnie oraz lista encji przestrzeni roboczej w edytorze. AGGREGA_CATALOG_DIRS ustawia listę przestrzeni roboczej i nie dociera do żadnego z tych wpisów, a plik konfiguracyjny należący do potoku w ogóle nie odczytuje tej mapy.

Plik konfiguracyjny należący do potoku

Plik o nazwie .aggrega-config-append-ci.yaml może znajdować się obok pliku tworzonego ręcznie w dowolnym katalogu odwiedzanym podczas przechodzenia. Jest to osobny plik, aby zautomatyzowany potok mógł nim zarządzać i nadpisywać go w całości, nigdy nie naruszając tego, co napisał człowiek.

Działa on wyłącznie addytywnie. Jego wpisy dla pięciu powyższych ustawień listowych są doklejane do rozwiązanych list; nie może niczego usunąć ani nadpisać wartości skalarnej. Zapisany w nim klucz skalarny lub klucz mapy nie ma znaczenia addytywnego, więc jest ignorowany i wymieniany w ostrzeżeniu, zamiast być po cichu stosowany. Nigdy też nie wyznacza katalogu głównego projektu, więc umieszczenie go w katalogu dodaje dołączenia bez przesuwania miejsca, w którym zaczyna się projekt.

Dokąd wskazuje ścieżka względna

Względna ścieżka w systemie plików jest rozwiązywana względem katalogu pliku, który ją zadeklarował — nie względem katalogu głównego projektu i nie względem katalogu, z którego uruchomiono polecenie. Tę regułę warto przeczytać dwa razy, ponieważ ścieżka, która wygląda na względną wobec projektu, zostaje rozwiązana gdzie indziej, a kompilacja i tak kończy się powodzeniem, na treści, której nie zamierzano użyć.

Dotyczy ona workspace.catalog_dirs, plików encji Release podanych jako klucze w workspace.releases oraz katalogów wymienionych w każdym wpisie, lokalnych ścieżek w systemie plików w podłączeniu plugins.governance lub plugins.linter — uri wskazującego plik .wasm na dysku oraz każdego wpisu w with.sources tego podłączenia — a także każdego wpisu w with.sources podłączenia plugins.importer. Na wszystkich trzech listach uri bez dwukropka, który nie wskazuje żadnego rejestru — zarówno importer/agent-flows, jak i ./lint/api-rules.wasm — jest taką ścieżką, natomiast uri wskazujący plugin przez jego tożsamość zawiera wersję po dwukropku, importer/agent-flows:1.2.0, i pozostaje dokładnie w zapisanej postaci. uri podłączenia importera wskazuje podłączany importer, jak opisano w sekcji Który importer zamienia źródło w szkice; import nie wczytuje żadnego modułu ze ścieżki tam zapisanej. Reguła dotyczy również wpisów w towarzyszących kluczach dołączających, a każdy z nich jest zakotwiczony w swoim własnym pliku deklarującym, a nie w pliku, na którym akurat kończy się scalanie. Dotyczy też mcp.tls.cert_file, mcp.tls.key_file i mcp.authorization.jwks_file, dzięki czemu plik leżący obok pliku, który go wskazuje, zostaje znaleziony niezależnie od miejsca uruchomienia serwera.

Przy takim układzie:

myproject/
├── .aggrega-config.yaml
└── services/
├── .aggrega-config.yaml
└── catalog/

i ./catalog zapisanym w pliku głównym ścieżka wskazuje myproject/catalog. Zapisany w services/.aggrega-config.yaml identyczny tekst wskazuje myproject/services/catalog. Ścieżka bezwzględna pozostaje dokładnie w zapisanej postaci, podobnie jak odwołanie do rejestru, takie jak oci://hub.aggrega.ai/plugins/helm:1.0.0.

Poniższe ustawienia celowo nie podlegają tej regule, ponieważ nie mają pliku deklarującego, w którym można by je zakotwiczyć, albo ponieważ każdy, kto je odczytuje, rozwiązuje je gdzie indziej:

  • artifact_cache_dir jest interpretowane względem katalogu głównego projektu, niezależnie od miejsca uruchomienia polecenia, dzięki czemu pamięć podręczna jest jednym katalogiem, a nie osobnym dla każdego miejsca wywołania. Wartość bezwzględna jest odrzucana podczas wczytywania konfiguracji.
  • AGGREGA_CATALOG_DIRS pochodzi ze środowiska i nie ma żadnego pliku deklarującego, dlatego należy podawać w nim ścieżki bezwzględne.
  • mcp.listen jest przyjmowane dokładnie w zapisanej postaci, łącznie ze ścieżką w systemie plików w formie unix:<path>. Ten sam adres może też pochodzić z aggrega mcp --listen, które nie ma pliku deklarującego, więc zakotwiczenie tylko wersji z konfiguracji sprawiłoby, że jeden ciąg wskazywałby dwa różne miejsca w zależności od swojego pochodzenia. Gniazdu należy nadać ścieżkę bezwzględną.

Jedno ustawienie ze współdzielonym magazynem

Niemal każde ustawienie dotyczy czegoś, co należy do projektu, nad którym się pracuje — przez które katalogi rozwiązywana jest treść katalogu, które pluginy renderują jego cele, jak surowo oceniana jest jego treść, jak duże mogą być pamięci podręczne demona w pamięci operacyjnej. Wartość w pliku projektu dotyczy tylko tego projektu i nie ma tu na co uważać.

compiled_module_cache.max_bytes jest jedynym wyjątkiem, ponieważ to, co ogranicza, nie jest przypisane do projektu. Skompilowany kod pluginów jest przechowywany w jednym katalogu, z którego korzysta każdy projekt na danej maszynie, więc dany plugin jest kompilowany raz, a nie raz dla każdego projektu. Sam limit jest rozwiązywany jak każde inne ustawienie — zapisany w pliku projektu, obowiązuje dla tego projektu — ale magazyn nadal ma tylko jeden rozmiar, a obowiązuje rozmiar z ostatniej kompilacji. Dwa projekty o różnych limitach działają na zmianę, a niższy limit usuwa skompilowany kod, za który zapłacił drugi projekt.

Dlatego należy umieścić je w pliku globalnym, gdy ma obowiązywać jedna wartość dla wszystkiego, co się kompiluje, i utrzymywać je powyżej tego, co kompiluje pojedyncza kompilacja. aggrega cache status pokazuje, co magazyn obecnie zawiera, a aggrega config show --origin wskazuje, z którego pliku faktycznie pochodzi obowiązujący limit.

Ustawienia serwera, z którym łączą się inni

aggrega mcp obsługuje protokół Model Context Protocol. Na własnej maszynie klient uruchamia go jako podproces i komunikuje się z nim przez standardowe wejście i wyjście, co jest ustawieniem domyślnym, a jedynymi ustawieniami wpływającymi na ten tryb są mcp.transport, pozostawione na wartości domyślnej, oraz mcp.announce_tools. Pozostała część bloku mcp dotyczy drugiego trybu, wybieranego przez mcp.transport: http: jednego długo działającego procesu na hoście, z którym przez HTTP łączą się wywołujący, którzy nie siedzą przy jego klawiaturze.

# <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

To mcp.transport wybiera transport. http uruchamia nasłuchiwanie; stdio, wartość domyślna, komunikuje się przez standardowe wejście i wyjście, czego oczekuje klient uruchamiający podproces. Każda inna wartość jest odrzucana podczas wczytywania tego pliku. aggrega mcp --transport <stdio|http> robi to samo dla jednego wywołania i ma pierwszeństwo przed kluczem, tak jak każda flaga ma pierwszeństwo przed każdym plikiem.

mcp.listen wskazuje, gdzie wiąże się nasłuchiwanie, i niczego nie wybiera. Należy podać adres host:port lub gniazdo unix:<path>; aggrega mcp --listen <address> ma przed nim pierwszeństwo dla jednego wywołania. Gdy wybrano http, a żadne z nich nie podaje adresu, uruchomienie jest odrzucane, zanim cokolwiek się zwiąże. Gdy wybrano stdio, podane --listen jest odrzucane, a adres wskazany tylko przez ten klucz pozostaje nieużywany — serwer informuje o tym jednym wierszem w swoim strumieniu błędów, wskazując ten plik i mcp.transport: http. Dlatego serwer, z którym łączą się inni, ustawia oba klucze, jak powyżej, a klient uruchomiony z katalogu objętego tym plikiem nadal łączy się z serwerem przez jego własne strumienie. Ścieżka unix: jest przyjmowana w zapisanej postaci, a nie zakotwiczana — zob. Dokąd wskazuje ścieżka względna.

mcp.tls.cert_file i mcp.tls.key_file przenoszą TLS do procesu. Po ustawieniu obu nasłuchiwanie samo obsługuje HTTPS. Po pominięciu obu obsługuje tekst jawny, co jest akceptowane tylko na interfejsie loopback lub w gnieździe Unix — w układzie, w którym certyfikat przechowuje proxy stojące przed procesem i przekazuje do niego ruch. Nasłuchiwanie tekstem jawnym pod każdym innym adresem jest odrzucane, zanim cokolwiek się zwiąże, ze wskazaniem tych dwóch kluczy; podobnie odrzucane jest ustawienie jednego z nich bez drugiego. Oba są ścieżkami w systemie plików i podlegają powyższej regule: ścieżka względna jest rozwiązywana względem katalogu pliku, który ją zadeklarował, więc certyfikat zatwierdzony w repozytorium obok tego pliku zostaje znaleziony niezależnie od miejsca uruchomienia serwera. Należy podawać je jako bezwzględne, gdy certyfikat jest zarządzany poza projektem.

mcp.authorization.issuer i mcp.authorization.resource określają, kto wystawia tokeny przedstawiane przez wywołujących oraz jak nazywa się ten serwer jako zasób, dla którego są one wystawiane. Oba są wymagane zawsze, gdy wybrano transport http, a bez nich listener zostaje odrzucony, zanim cokolwiek zostanie powiązane, ponieważ każde żądanie do punktu końcowego otrzymuje w odpowiedzi wyzwanie bearer-token, a wyzwanie, które nie wskazuje, dokąd się udać, jest takim, na które klient nie może zareagować. Należy podawać pełne adresy, łącznie ze schematem i hostem: wystawcę dokładnie tak, jak ten serwer autoryzacji podaje własny identyfikator, a zasób jako adres, do którego faktycznie docierają wywołujący — host przedstawiany przez proxy stojące przed serwerem, jeśli takie istnieje, a nie adres, z którym wiąże się ten proces. Oba są publikowane, bez żądania jakichkolwiek poświadczeń, w dokumencie metadanych chronionego zasobu OAuth udostępnianym przez listener, w którym klient sprawdza, gdzie uzyskać token. Żaden z nich nie zawiera niczego tajnego: token przychodzi w żądaniu, które go przedstawia, i nigdy nie jest zapisywany w pliku konfiguracyjnym. Wystawca jest adresem https, chyba że serwer autoryzacji działa na tej maszynie — localhost, 127.0.0.1 lub ::1 — a listener wskazujący zwykłego wystawcę http na jakimkolwiek innym hoście zostaje odrzucony, zanim cokolwiek zostanie powiązane, niezależnie od tego, w jaki sposób odczytuje swoje klucze i swoich wywołujących: każdy klient jest kierowany do wystawcy po token, więc przez zwykłe http jego kod autoryzacji i token przechodziłyby przez sieć bez ochrony, a tam, gdzie również klucze są odczytywane tą drogą, każdy, kto znajduje się na tej ścieżce, mógłby je podmienić.

mcp.authorization.jwks_file wskazuje plik zawierający klucze, względem których weryfikowane są tokeny, zamiast odczytywać je z serwera autoryzacji. Jeśli zostanie pominięty, serwer odczytuje metadane tamtego serwera pod jego dobrze znanym adresem i podąża za opublikowanym tam jwks_uri, co robi przestrzeń robocza z dostępem do sieci. Ten adres kluczy podlega tej samej regule co wystawca, podobnie jak każdy adres, na który przekierowany zostanie którykolwiek z tych odczytów: adres korzystający ze zwykłego http na innym hoście nigdy nie jest odpytywany, a token wymagający tych kluczy otrzymuje odpowiedź 503, dopóki serwer autoryzacji nie opublikuje swoich metadanych i kluczy przez https. Jeśli zostanie ustawiony, serwer autoryzacji nigdy nie jest kontaktowany — czego potrzebuje przestrzeń robocza deklarująca offline: true, a taka przestrzeń robocza zostaje odrzucona, zanim jej listener zostanie powiązany, chyba że ten klucz wskazuje plik. Jest to ścieżka i podlega powyższej regule: ścieżka względna jest rozwiązywana względem katalogu pliku, który ją zadeklarował, więc zestaw kluczy zatwierdzony obok tego pliku zostanie znaleziony niezależnie od tego, skąd serwer zostanie uruchomiony. Plik zawiera publiczne klucze weryfikacyjne, czyli to, co publikuje serwer autoryzacji — nic, co podpisuje, i nic tajnego.

mcp.allowed_origins jest sprawdzany tylko wtedy, gdy żądanie zawiera nagłówek Origin, co w praktyce oznacza, że wysłała je przeglądarka. Należy wymienić tam obsługiwane źródła; żądanie wskazujące źródło, którego nie ma na liście, zostaje odrzucone, a żądanie bez takiego nagłówka jest obsługiwane mimo to. Klient, który nie jest przeglądarką, nie wysyła takiego nagłówka i nie potrzebuje wpisu. Wpis jest porównywany z nagłówkiem dokładnie, więc należy zapisać go tak, jak wysyła go przeglądarka: schemat małymi literami, ://, host małymi literami oraz : z portem tylko wtedy, gdy port nie jest domyślnym portem schematu — https://studio.example.com lub http://localhost:3000 dla strony serwowanej na własnej maszynie — bez ścieżki i bez końcowego /. Wpis w jakiejkolwiek innej postaci nigdy nie mógłby pasować i zostaje odrzucony podczas wczytywania tego pliku, z podaniem tego wpisu.

mcp.limits ogranicza to, o co może poprosić jeden wywołujący — jak duża może być treść pojedynczego żądania, ile żądań działa jednocześnie i ile może wysłać jeden wywołujący w ciągu minuty. Wszystkie trzy limity obowiązują zawsze; żaden nie ma wartości, która by go znosiła. Trzeci, requests_per_minute, jest liczony osobno dla każdego wywołującego, więc jeden wywołujący wysyłający intensywnie nie kosztuje innego niczego.

mcp.authorization.trusted_proxy odczytuje wywołującego z proxy stojącego przed serwerem zamiast sprawdzać token tutaj. W principal_header należy ustawić nagłówek, którym to proxy wskazuje, kim jest wywołujący, a opcjonalnie w scopes_header nagłówek przenoszący zakresy tego wywołującego. Oba są nazwami nagłówków HTTP, takimi jak X-Forwarded-User — litery, cyfry, łączniki i kilka innych znaków dopuszczalnych w nazwie nagłówka, bez spacji i dwukropka — a nazwa w jakiejkolwiek innej postaci zostaje odrzucona podczas wczytywania tego pliku, z podaniem klucza, ponieważ żadne żądanie nie mogłoby jej zawierać. W tym trybie żaden token nie jest w ogóle odczytywany, a żądanie bez nagłówka podmiotu zostaje odrzucone. Ponieważ nagłówek jest wtedy całym poświadczeniem, można mu ufać tylko tam, gdzie nic innego nie może go ustawić: proces zostaje odrzucony przed powiązaniem, chyba że mcp.listen to loopback lub gniazdo Unix. Jeśli blok zostanie pominięty, ten serwer sam sprawdza tokeny, co jest zachowaniem domyślnym; blok, którego principal_header jest pusty, zostaje odrzucony, a nie odczytany jako to zachowanie domyślne.

mcp.deny_reach odbiera temu wdrożeniu dany rodzaj zasięgu. Każda operacja wykonywana przez serwer deklaruje, jak daleko sięgają jej skutki — none dla takiej, która odczytuje lub renderuje i niczego nie pozostawia, workspace dla takiej, która zapisuje wewnątrz przestrzeni roboczej obsługiwanej przez ten proces, registry dla takiej, która publikuje, podpisuje lub wycofuje, oraz machine dla takiej, która zmienia to, co współdzielą wszystkie przestrzenie robocze na hoście. Wskazanie tu rodzaju odbiera każde narzędzie, które go osiąga: narzędzie nie występuje na liście narzędzi żadnego wywołującego, niezależnie od tego, co zawiera jego token, a wywołanie go zostaje odrzucone z podaniem tego ustawienia. Dzięki temu jest to ograniczenie wdrożenia, a nie wywołującego, i żadne poświadczenie go nie znosi — serwer przeznaczony wyłącznie do obsługi odczytów wymienia tu trzy rodzaje zapisujące i wtedy nie może publikować nawet dla wywołującego, którego token zawiera wszystkie zakresy. Jeśli zostanie pominięty, co jest zachowaniem domyślnym, to wdrożenie obsługuje wszystko, na co pozwalają zakresy jego wywołujących. Wartość spoza tych czterech zostaje odrzucona podczas wczytywania tego pliku, a nie pominięta. Niczego z rodzaju machine nie udostępnia się przez HTTP niezależnie od tego ustawienia, więc wskazanie go jest akceptowane i niczego nie zmienia; aggrega-mcp.md opisuje te rodzaje i zakresy, które na nie pozwalają.

mcp.announce_tools zawęża to, co serwer ogłasza, i jest innym ograniczeniem niż klucz powyżej. Należy wymienić narzędzia, które ten serwer ogłasza, zapisane tak, jak podaje je lista narzędzi, a ogłaszane są dokładnie one: pominięte nie występuje na liście narzędzi żadnego wywołującego i zostaje odrzucone, jeśli mimo to zostanie wywołane po nazwie, z podaniem tego ustawienia. Jeśli klucz zostanie pominięty — co jest zachowaniem domyślnym — ogłaszane jest każde narzędzie, które serwer posiada; jeśli zostanie zapisana pusta lista, nie jest ogłaszane żadne, więc te dwa zapisy są różnymi stwierdzeniami i żadna wartość domyślna nie jest uzupełniana automatycznie. Od deny_reach odróżnia go to, co każdy z nich odbiera. deny_reach odbiera możliwość: operacje wycofanego rodzaju w ogóle nie są tu obsługiwane i żadne poświadczenie ich nie przywraca. announce_tools odbiera tylko ogłoszenie — pominięte narzędzia to możliwości, które serwer nadal ma — a odpowiada na potrzeby klienta ograniczającego liczbę narzędzi, które zarejestruje, czasem łącznie dla wszystkich serwerów, z którymi jest jednocześnie połączony. Gdy ustawione są oba, wygrywa wycofanie, więc narzędzie wycofanego rodzaju pozostaje nieobecne niezależnie od tego, jak ten klucz je wskazuje. Nazwa, której nie odpowiada żadne narzędzie, zatrzymuje serwer, zanim cokolwiek obsłuży, z wypisaniem narzędzi, które ma, zamiast pozostawiać powierzchnię węższą niż żądana. W odróżnieniu od pozostałych kluczy tutaj, które konfigurują listener uruchamiany przez transport http, jest on odczytywany niezależnie od transportu, którym posługuje się serwer, ponieważ klient, dla którego istnieje zawężenie, to zwykle ten, który uruchomił proces przez własne standardowe wejście i wyjście; aggrega-mcp.md opisuje resztę.

mcp.health.listen umieszcza sprawdzenia żywotności i gotowości pod osobnym adresem. Należy podać adres w jednej z dwóch form mcp.listen, a drugi listener odpowiada tam na GET /healthz — 200 od chwili uruchomienia procesu — oraz na GET /readyz — 503, dopóki przestrzeń robocza nie zostanie rozwiązana, a punkt końcowy powiązany, a od tej chwili 200, co pozwala load balancerowi wstrzymać ruch, dopóki proces nie będzie w stanie faktycznie odpowiedzieć na wywołanie. Jeśli klucz zostanie pominięty, żadne z tych sprawdzeń nie jest nigdzie obsługiwane. Nigdy nie są one obsługiwane pod adresem wskazanym przez mcp.listen, który zwraca dla nich 404, tak jak dla każdej ścieżki, której nie obsługuje: sonda pod tym adresem byłaby nieuwierzytelnionym odczytem listenera, który odrzuca wszystko inne. W przeciwieństwie do mcp.listen ten adres nie jest ograniczony i żaden adres nie jest dla niego odrzucany — należy wskazać loopback lub gniazdo Unix, do którego sięga nadzorca działający obok tego procesu, i pamiętać, że wszystko, co może sięgnąć wybranego adresu, może odczytać te dwie odpowiedzi.

schema/other/aggrega-config.md podaje każdy z tych kluczy wraz z jego wartością domyślną, jeśli ją ma.

Inne sposoby rozpoznawania katalogu głównego projektu

--workspace-root <path> lub jego odpowiednik AGGREGA_WORKSPACE_ROOT wskazuje katalog główny wprost i pomija wykrywanie. Wskazany folder musi istnieć: ścieżka, która nie wskazuje niczego lub wskazuje plik, jest odrzucana, zanim polecenie zrobi cokolwiek innego, a komunikat o odrzuceniu wymienia, które z tych dwóch źródeł dostarczyło wartość, i cytuje ją w podanej postaci. W przeciwnym razie wykrywanie przechodzi w górę od katalogu roboczego, a rodzaje znaczników są szeregowane względem siebie, a nie według odległości:

  • Plik .aggrega-config.yaml zawierający blok workspace: wygrywa bezwarunkowo, na dowolnej głębokości. Przeszukiwanie wspina się dalej w jego poszukiwaniu nawet po minięciu znacznika opisanego niżej, więc jawnie oznaczony katalog główny powyżej zawsze wygrywa z przypadkowym znacznikiem poniżej.
  • W przeciwnym razie katalog główny wyznacza najbliższy z tych znaczników, a w obrębie jednego katalogu mają one następującą kolejność: katalog .aggrega/, następnie aggregate*.yaml, następnie release*.yaml, następnie manifest*.yaml.
  • Gdy wszystko zawiedzie, używany jest katalog roboczy — polecenia działają zamiast odmawiać uruchomienia. Polecenie, którego wynik zależy od przestrzeni roboczej — takie, które odczytuje lub zapisuje dokumenty przestrzeni roboczej, odczytuje lub wypełnia jej pamięć podręczną artefaktów albo ją udostępnia — wyświetla jednokrotnie ostrzeżenie na standardowym wyjściu błędów: warning: <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace. Polecenie, którego wynik nie zależy od tego, który folder jest katalogiem głównym, nic nie wyświetla, nawet jeśli odczytuje konfigurację: należą do nich między innymi aggrega version, aggrega config show, aggrega plugin list, aggrega registry list, aggrega explain i aggrega login. aggrega config capture, którego zadaniem jest zapisanie własnego pliku konfiguracyjnego przestrzeni roboczej, w takim folderze niczego nie zapisuje i kończy działanie błędem, który to komunikuje.

W takim folderze nic nie jest zapisywane do pamięci podręcznej artefaktów. Katalog .aggrega/ sam jest jednym ze znaczników opisanych wyżej, więc zapisana w nim pamięć podręczna uczyniłaby z folderu przestrzeń roboczą tylko dlatego, że kiedyś coś w nim pobrano. Polecenie, którego praca zapełnia pamięć podręczną — aggrega pull, kompilacja, która najpierw rozwiązuje swoje zależności, aggrega registry update, dodanie pluginu rozszerzającego polecenia z rejestru — jest odrzucane, zanim cokolwiek pobierze, z podaniem folderu i dwóch wyjść: wskazania przestrzeni roboczej za pomocą --workspace-root lub AGGREGA_WORKSPACE_ROOT albo umieszczenia w folderze pliku .aggrega-config.yaml zawierającego blok workspace:. aggrega pin oraz aggrega push encji Recipe lub FeatureRecipe, które jest związane przypięciami zapisanymi w leżącym obok entity.lock, zapełniają pamięć podręczną wyłącznie zdalnymi źródłami, które encja zapisuje w pełnej postaci i które pobiera jej przypięcie lub porównanie przypięcia: są odrzucane w ten sam sposób tam, gdzie pobrałyby takie źródło, zanim je pobiorą. Encja bez takiego źródła — bez żadnego źródła, ze źródłem lokalnym lub ze źródłem, którego współrzędne uzupełnia każda encja Release — jest tam przypinana lub publikowana tak jak wszędzie indziej. Kompilacja nie jest tam odrzucana, ale zewnętrzne wejście przypięte w jej pliku blokady, którego pamięć podręczna już nie zawiera, nie jest ponownie pobierane w celu naprawy: zamiast tego wejścia renderowanie otrzymuje to samo zdanie, tak jak otrzymuje zdanie trybu offline, i je zgłasza. Miejsce, w którym artifact_cache_dir umieszcza pamięć podręczną, niczego tu nie zmienia, ponieważ katalog jest dołączany do znalezionego katalogu głównego. Polecenia, które tylko odczytują, nadal odpowiadają.

Ta ostatnia ścieżka awaryjna ma jeden wyjątek. Gdy nic nie wskazało katalogu głównego, a katalog roboczy nie wyznacza żadnego, polecenie dotyczące jednej encji Release lub jednego dokumentu encji, które wskazuje ten plik ścieżką bezwzględną, ponownie wykrywa katalog główny, przechodząc w górę od folderu, w którym leży plik, i używa tego, co znajdzie: przestrzeni roboczej, do której należy plik, a gdy nic nie zadziała — tego folderu. Plikiem tym jest plik wskazany przez --release w aggrega build i aggrega pull; encja Release przekazana do aggrega validate, aggrega lint i aggrega inspect, a w przeciwnym razie przekazany im plik; oraz dokument przekazany do aggrega pin, aggrega push i aggrega edit-document. Dzięki temu encja Release projektu skompilowana spoza projektu odczytuje własną konfigurację projektu, tak jak przy uruchomieniu polecenia w jego wnętrzu, a ostrzeżenia konfiguracyjne wypisywane przez polecenie dotyczą tej przestrzeni roboczej. Jeśli folder pliku również niczego nie wyznacza, to właśnie ten folder podaje komunikat polecenia i w nim nie jest zapisywana pamięć podręczna. Ścieżka względna jest odczytywana względem katalogu, w którym uruchamiane jest polecenie, i niczego nie zmienia, a wskazany katalog główny lub katalog roboczy, który sam leży w przestrzeni roboczej, jest używany bez zmian. Serwer asystenta stosuje tę samą regułę do wywołania, które wskazuje swoją encję Release lub dokument ścieżką bezwzględną.

Oznaczenie katalogu głównego blokiem workspace: jest wyborem jawnym i zalecanym; znaczniki w postaci plików i katalogów pozwalają skompilować także projekt, który takiego bloku nie zadeklarował.

Jawne wskazanie pliku globalnego

Warstwa globalna jest rozwiązywana w następującej kolejności:

  1. --config <path>, forma dla pojedynczego wywołania.
  2. Zmienna środowiskowa AGGREGA_CONFIG.
  3. Lokalizacja domyślna: w systemie Windows aggrega\config.yaml w katalogu wskazanym przez zmienną środowiskową APPDATA, a w pozostałych systemach aggrega/config.yaml w katalogu wskazanym przez XDG_CONFIG_HOME, z ~/.config/aggrega/config.yaml jako wartością awaryjną.

Pierwsze dwie wskazują jawny plik, więc nieistniejąca ścieżka jest głośnym błędem, a nie cichym przejściem do wartości awaryjnej — zażądano konkretnego pliku. Polecenie, które odczytuje swoją konfigurację, zatrzymuje się z jednym zdaniem kończącym się ścieżką, aby można było ją skopiować. aggrega config init jest wyjątkiem, ponieważ utworzenie tego pliku jest jego zadaniem: tworzy wskazany plik i to zgłasza. Lokalizacja domyślna jest wczytywana, gdy plik istnieje, i cicho pomijana, gdy go nie ma. Niezależnie od tego, który plik zostanie rozwiązany, pliki projektu nadal nakładają się na niego.

Gdy żadna z tych opcji nie zostanie rozwiązana — nie wskazano pliku, a zmienne, z których odczytywana jest lokalizacja domyślna, nie są ustawione — polecenie zapisujące plik globalny zatrzymuje się i podaje, co należy ustawić. Zmienne środowiskowe wymieniają, dla każdej platformy, zmienne, z których odczytywana jest każda lokalizacja.

Ten wybór określa także, gdzie zapisuje polecenie zapisujące konfigurację. Polecenie uruchomione z --config <path> odczytuje konfigurację z tego pliku i wprowadza zmianę w tym samym pliku, więc to, co zapisze jedno polecenie, odczyta następne.

To, do którego z dwóch plików polecenie domyślnie zapisuje, wynika z natury ustawienia: narzędzia dla całej maszyny, takie jak rejestr, trafiają do pliku globalnego, a ustawienia uczestniczące w kompilacji, takie jak powiązanie dostawcy lub podłączenie gniazda, trafiają do zatwierdzonego pliku projektu, aby przenosiły się wraz z projektem. Aby to zmienić, należy przekazać --global lub --workspace; polecenie wypisuje plik, do którego zapisało.

Zobacz także

  • aggrega-config.md — polecenia aggrega config, które inicjują, sprawdzają i zamrażają konfigurację.
  • environment-variables.md — wszystkie zmienne z prefiksem AGGREGA_ oraz miejsca, w których podaje się sekrety.
  • global-flags.md — --config, --workspace-root i pozostałe flagi akceptowane przez każde podpolecenie.
  • schema/other/aggrega-config.md — każdy klucz konfiguracji, jego typ i wartość domyślna.
  • aggrega-cache.md — co faktycznie przechowuje artifact_cache_dir.
  • workspace-boundary.md — które ścieżki pozostają wewnątrz obszaru roboczego i jak katalogi oraz pliki wskazane w tej konfiguracji sięgają poza niego.
  • aggrega-mcp.md — serwer konfigurowany przez blok mcp.