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

Gniazdo, którego nikt nie zadeklarował, dostarczające prawdziwe wartości

Ten przykład uczy jednego zdania i obu jego połówek:

Konsument może wymyślić połączenie. Może jednak konsumować tylko to, co deklaruje producent.

Autor encji Aggregate zapisuje wpis uses: we własnym komponencie pod nazwą gniazda, której nie deklaruje żadna encja katalogu. Krawędź zostaje zbudowana i dostarcza — wartość trafia do wyrenderowanego artefaktu dokładnie tak, jak trafiłaby przez zadeklarowane gniazdo. Jednak klucze, które ta krawędź może przenosić, nadal deklaruje cel: jeśli wskaże się klucz, którego cel nie deklaruje, kompilacja zostaje przerwana.

Wszystko tutaj jest rozwiązywane z katalogu biblioteki standardowej. Przestrzeń robocza nie definiuje żadnej własnej encji Component, Feature ani Recipe.

Stos

Trzy komponenty, z których jeden jest połączony na dwa różne sposoby:

instancjatypczym jest
dbcore/datastore/mariadbbaza danych
modelcore/ai-model/anthropicendpoint modelu; realizacja w formie referencji, więc nie uruchamia się dla niego żadna moc obliczeniowa
webcore/devtool/adminerkonsola, konsumująca oba

core/devtool/adminer deklaruje dokładnie jedno gniazdo:

usesSchema:
databases:
selector: "component.aggrega.ai/type=stateful-server"
inject: [env]

To wszystko, co przewidział jego autor. Konsola obsługująca bazę danych to połączenie, które miał na myśli; konsola przenosząca endpoint modelu w swoim środowisku — nie.

Co zapisuje encja Aggregate

aggregate-delivers.yaml łączy obie krawędzie z jednego bloku uses::

web:
type: core/devtool/adminer
uses:
databases: # DECLARED — the socket the Component's usesSchema names
db:
target: db
inject:
env:
- in: ADMINER_DEFAULT_SERVER
from: host
assistant: # AD-HOC — declared nowhere
model:
target: model
inject:
env:
- in: ASSISTANT_ENDPOINT
from: endpoint
- in: ASSISTANT_MODEL
from: model

assistant nie występuje w żadnym usesSchema, ani w tej encji Component, ani w żadnej innej. Mimo to jest dozwolone: milczenie katalogu o gnieździe oznacza, że połączenia nie przewidziano, a nie że jest zabronione, a deweloper jest właścicielem topologii własnej aplikacji.

Gniazdo ad hoc traci dokładnie to, co przeniósłby brakujący wpis usesSchema — nie ma selector, więc nic nie ogranicza, do którego komponentu może sięgać krawędź, a międzywęzłowe sprawdzanie bezpieczeństwa typów nie ma czego oceniać; nie ma listy dozwolonych inject:; nie ma valueSchema ani infraSchema na poziomie krawędzi, więc values: i infra: krawędzi nie mają kontraktu, względem którego można je sprawdzić, ani zadeklarowanych wartości domyślnych do odziedziczenia. Konfiguracja krawędzi zapisana w takim gnieździe jest akceptowana i przekazywana bez sprawdzania, tak jak zachowuje się każde gniazdo bez kontraktu dla danego filaru — zadeklarowane gniazdo, które nie definiuje valueSchema, jest w tej samej sytuacji.

Nie traci natomiast tego, co krawędź może przenosić. endpoint i model to klucze, które core/ai-model/anthropic deklaruje w swoim filarze provides.

Generowanie przykładu

Ten przykład można zbudować za pomocą poniższych poleceń albo zlecić jego zbudowanie asystentowi AI.

Należy zapisać przykład w nowym folderze nazwanym tak jak on:

Terminal window
aggrega scaffold --example adhoc-uses-socket

Następnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:

Terminal window
cd adhoc-uses-socket

Kompilacja

Terminal window
aggrega build --release release-delivers.yaml --auto-pull

Wyrenderowane wyjście i plik blokady są generowane, a nie dostarczane: ten przykład zatwierdza swoje dane wejściowe i generuje ponownie całą resztę. --auto-pull rozwiązuje plik blokady podczas kompilacji; jednorazowe wcześniejsze aggrega pull --release release-delivers.yaml robi to samo i pozwala kolejnym kompilacjom działać bez żadnej flagi. Encje katalogu są rozwiązywane z hub.aggrega.ai, domyślnego rejestru wskazanego w .aggrega-config.yaml, więc ani kompilacja, ani aggrega inspect nie potrzebują flagi --catalog.

Z asystentem AI

Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić mu ten prompt.

Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder obszaru roboczego nie zawiera jeszcze folderu `adhoc-uses-socket`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `adhoc-uses-socket` i bez `dir`: zapisze ono przykład w nowym folderze `adhoc-uses-socket`. Następnie wywołaj narzędzie `build` z `workspace_root` ustawionym na `adhoc-uses-socket`, `release` ustawionym na `release-delivers.yaml`, `auto_pull` ustawionym na true i `write` ustawionym na true. Powiedz mi, które pliki zapisało budowanie; znajdują się w `adhoc-uses-socket/dist/`.

Odczyt wyjścia

dist/compose/docker-compose.yaml, usługa web:

web:
image: adminer:4
environment:
ADMINER_DESIGN: pepa-linha-dark
ADMINER_DEFAULT_SERVER: db
ASSISTANT_ENDPOINT: https://api.anthropic.com
ASSISTANT_MODEL: claude-sonnet-4-5
[… omitted: the service's ports, provenance labels, networks, depends_on and healthcheck]

Cztery zmienne, z czego trzy dostarczone przez krawędzie, a wyjście nie rejestruje, które gniazdo zostało zadeklarowane:

  • ADMINER_DEFAULT_SERVER: db dotarło przez databases, zadeklarowane gniazdo. Jego wartością jest provides.host encji Recipe bazy danych — nazwa usługi Compose.
  • ASSISTANT_ENDPOINT i ASSISTANT_MODEL dotarły przez assistant, gniazdo ad hoc, przenosząc provides.endpoint i provides.model encji Recipe modelu.

Znajdują się w jednej mapie, w kolejności autora, bez znacznika, bez adnotacji i bez różnicy w kolejności między nimi. O to właśnie chodzi: gniazdo ad hoc to coś innego przy deklarowaniu, a nie przy dostarczaniu. Istnieje jedna ścieżka dostarczania i obie krawędzie z niej korzystają.

ASSISTANT_ENDPOINT warto też odczytać jako fakt kompilacji ahead-of-time. Kompilator nie kontaktował się z Anthropic, aby ustalić https://api.anthropic.com; encja Recipe wyemitowała go jako deterministyczny łańcuch wskaźnika pochodzący z infra.endpoint komponentu modelu, a kompilator przekazał ten łańcuch bez interpretowania go. Sam Adminer nie odczytuje żadnej ze zmiennych ASSISTANT_* — to deweloper wybrał te klucze dostarczania, a kontener konsoli przenosi je dla tego, co je tam odczytuje.

Graf emitowany przez kompilację rejestruje to rozróżnienie, choć wyrenderowany artefakt tego nie robi: każda krawędź ma pole socket_declaration o wartości declared lub ad-hoc, więc organizacja, która chce, aby każde połączenie przechodziło przez gniazdo zadeklarowane przez jej architektów, wyraża to jako politykę nadzoru, zamiast polegać na tym, że kompilator będzie miał własne zdanie. Zob. architecture/11-governance-and-compliance.md.

Próba kontrolna: czego konsument nadal nie może wymyślić

aggregate-undeclared-key.yaml to aggregate-delivers.yaml z jedną zmianą. Krawędź ad hoc żąda trzeciego klucza:

- in: ASSISTANT_API_KEY
from: api_key

core/ai-model/anthropic deklaruje w swoim filarze provides klucze endpoint i model i nic więcej. Kompilacja powinna zakończyć się niepowodzeniem:

Terminal window
aggrega build --release release-negative-undeclared-key.yaml --auto-pull
# [… omitted: a refused: line carrying the message below]
# [DEVELOPER_ERROR E0156] .spec.components.web.uses.assistant.model
# invalid inject key: the from-key must name a provides key its source publishes
# (Aggregate adhoc-uses-socket-undeclared-key,
# at .spec.components.web.uses.assistant.model, "env", "ASSISTANT_API_KEY", "api_key",
# "core/ai-model/anthropic", "endpoint", "model")

Przerwanie jest lekcją, a warte uwagi jest to, gdzie następuje: błędna ścieżka wskazuje gniazdo ad hoc, uses.assistant, i kończy się na połączeniu, a nie na wpisie dostarczania w nim. Klucz from: jest sprawdzany względem zadeklarowanych provides docelowej encji Component na każdej krawędzi, a to, że gniazdo jest ad hoc, niczego w tym sprawdzeniu nie zmienia. Autor, który może wymyślić nazwę gniazda, nadal nie może wymyślić klucza wyjściowego w cudzym komponencie.

Najpierw pojawia się odmowa, potem encja Aggregate i ścieżka, w której zapisano krawędź, mechanizm i klucz dostarczania, pod którym zapisano wpis, błędny klucz, typ komponentu, względem którego go rozwiązano, oraz zadeklarowane klucze tego typu w kolejności posortowanej — dzięki temu poprawka wynika z samego komunikatu. Docelowa encja Component, która w ogóle nie deklaruje provides, tak samo odrzuca każde odwołanie from: do niej; po prostu nie ma zadeklarowanych kluczy do wymienienia, więc komunikat kończy się po typie komponentu.

Którą formę zapisać

Zadeklarowanie gniazda w katalogu pozostaje lepszą drogą i tak właśnie postępuje katalog biblioteki standardowej. Zadeklarowane gniazdo ma selector, który ogranicza, do których komponentów może sięgać krawędź, listę dozwolonych inject:, kontrakt krawędzi z własnymi wartościami domyślnymi oraz opis — podlegającą przeglądowi deklarację przewidzianego połączenia, wersjonowaną razem z encją, która ją składa. Gniazdo ad hoc nie ma niczego z tych rzeczy, a krawędź jest tylko tak bezpieczna jak autor, który ją zapisał.

Forma ad hoc to furtka na przypadek pokazany w tym przykładzie: połączenie, którego autor katalogu nie przewidział, potrzebne jednemu wdrożeniu, gdy czekanie na zmianę w katalogu oznaczałoby czekanie z wydaniem. Należy po nią sięgać ze świadomością jej kosztów.

Dwa koszty warto wyraźnie wskazać:

  • Błędnie zapisana nazwa gniazda jest dozwolonym gniazdem ad hoc, a nie błędem. Zapisanie databses zamiast databases daje udaną kompilację, w której nic nie płynie przez zamierzone gniazdo. Kompilator zgłasza nazwę gniazda różniącą się o jedną edycję od zadeklarowanej jako ostrzeżenie podające obie pisownie — zob. errors/warnings.md „Uses-socket near-miss lint” — ale jest to ostrzeżenie i nigdy nie zmienia wyniku kompilacji.
  • Dwie powierzchnie celowo nie są w ten sposób otwarte. uses w dołączeniu encji Feature może wskazywać tylko gniazdo deklarowane przez dołączoną encję Feature, a uses krawędzi w encji Release może wskazywać tylko gniazdo deklarowane przez konsumującą encję Component. Operator konfiguruje i łączy w ramach architektury; nie jest jej autorem. release-delivers.yaml zawiera więc infra: i nic o gniazdach — gniazdo assistant należy do autora encji Aggregate i tylko do niego.

Pełny kontrakt opisano w entities/component.md „Topology Sockets: usesSchema” oraz architecture/07-dependency-resolution.md.