Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Разрешение зависимостей

Разрешение зависимостей в Aggrega & столп структурной топологии

В архитектуре Aggrega топологические зависимости явно отображаются через столп схемы uses, чтобы сохранить полностью непрозрачную полезную нагрузку values. Определение того, «кто с кем общается», представляет особую задачу: сложные многоузловые топологии приложений нужно отобразить, не заставляя разработчика писать явную сетевую маршрутизацию, порядок выполнения на уровне оркестратора или инфраструктурные зависимости.

1. Базовая философия: почему uses?

Блок uses объявляет зависимости между компонентами как чистую топологию: сущность Component A зависит от публичного контракта provides сущности Component B, а не от физического адреса или деталей подключения сущности Component B. Топология живёт в uses; конфигурация живёт в values. Такое разделение позволяет компилятору явно видеть все рёбра между компонентами, не выводя их из содержимого values.

Aggrega решает это, возводя топологию в полноправный столп схемы под названием uses.

  • Аргумент семантического прокси: ключевое слово uses выражает семантическое намерение уровня L7. Если агент uses базу данных, это остаётся семантически верным, даже если Platform Ops внедряет между ними прозрачные сетки прокси Wasm.
  • Математическая нейтральность: компилятор Go нативно разбирает структуру uses, чтобы построить граф промежуточного представления (IR). Он никогда не пытается разбирать или запрашивать логику приложения разработчика (values).
  • Атомарность сущности Feature: столп uses одинаково применяется к Components и Features (включая Features для учётных данных). Это позволяет прокси-sidecar (сущности Feature) или средству получения учётных данных автономно объявлять собственные сетевые зависимости, не засоряя конфигурацию родительской сущности Component.

2. Механика единого контракта схемы

Чтобы извлекать операционные инструкции без разбора полезной нагрузки приложения, система опирается на строгие объявления JSON Schema 2020-12, которые регулируют явно разделённые структуры YAML.

Домен 2: разделённая схема (usesSchema & schema) Чтобы каталог платформы не распался на неуправляемые файлы схем, Aggrega использует движок разделённой схемы. Нативная YAML-схема usesSchema строго определяет и проверяет топологию, а schema: (JSON Schema 2020-12 — обычно записывается через компактную сокращённую форму) проверяет содержимое столпов values и infra и объявляет форму столпа provides. values, которые пишет разработчик, и infra, которую задаёт оператор, проверяются на соответствие объявленным типам; подсхема provides объявляет имена ключей и типы нисходящего контракта, который создаёт сущность Recipe, а компилятор проверяет, что каждая ссылка inject называет объявленный ключ provides, — но сами созданные значения provides передаются дальше как непрозрачные строки, которые компилятор пропускает без интерпретации, а не как значения, тип которых он проверяет, поскольку ядро не интерпретирует, что означает передаваемое значение. Именно в usesSchema сокет объявляется, и именно объявление даёт ему контракт. Сокет, объявленный сущностью каталога, несёт ограничения этой сущности: селектор, определяющий, каких целей он может достигать, список разрешённых inject и valueSchema / infraSchema для каждого ребра. Внутри usesSchema архитекторы платформы используют поле selector: — оно читается как строка, которую написал архитектор, и не копируется ни в какую сгенерированную схему, — а встроенный движок селекторов Go вычисляет его, чтобы обеспечить типобезопасность между узлами для объявленных сокетов. Это гарантирует, что если сокет требует базу данных, разработчик не сможет подключить к нему веб-сервер.

Селектор подчиняется своей грамматике в момент вычисления, то есть один раз для каждого ребра, проведённого через сокет. Селектор, который движок не может прочитать как одну из шести своих форм требования, — пустое требование, оставленное лишней запятой, ключ с пробельными символами или с одним из символов, которыми грамматика различает свои формы (=, !, (, ) и запятая), или множество без закрывающей скобки, — останавливает сборку на этом ребре с указанием требования, вместо того чтобы быть прочитанным как другой селектор. Именно эта строгость сохраняет проверку честной: при снисходительном чтении !tier=frontend, написанный, чтобы не допустить фронтенды, требовал бы лишь, чтобы ни одна метка не называлась tier=frontend, и каждая цель — включая фронтенды — прошла бы. Та же грамматика регулирует селекторы слотов вложений и appliesTo сущности Feature; грамматика селекторов перечисляет каждую форму и каждый отказ. Сборка никогда не вычисляет сокет, через который не проведено ни одного ребра, поэтому aggrega validate — по всему каталогу или по сущности Component либо Feature, объявляющей сокет, — читает селектор каждого объявленного сокета и отклоняет некорректный уже на этом этапе, с тем же кодом и в тех же формулировках, что и сборка, проводящая ребро через этот сокет.

Однако объявление сокета — не единственный способ провести ребро. Автор сущности Aggregate может назвать на собственном компоненте сокет, который сущность каталога не объявляет, — даже на типе компонента, который вовсе не объявляет usesSchema, — и ребро будет построено. Каталог, не объявляющий записи для сокета, не предусмотрел соединение, а это не то же самое, что запретить его, и топология приложения принадлежит разработчику. Такой сокет называется ad hoc, и его цена — ровно то, что даёт объявление: записи в каталоге нет, значит, нет ни селектора, ни контракта для ребра, и типобезопасности между узлами нечего вычислять. То, что ребро может переносить, не меняется — каждый ключ, который оно внедряет, по-прежнему должен называть ключ, объявленный в provides цели, а цель по-прежнему должна существовать. Каждое ребро в выведенном графе фиксирует, какой из двух случаев оно представляет, так что потребителю никогда не приходится гадать; см. governance-and-compliance о том, как оператор полностью запрещает сокеты ad hoc.

Две поверхности намеренно не открыты таким образом, поскольку они не создают топологию приложения. uses вложения сущности Feature может называть только сокет, объявленный прикреплённой сущностью Feature, а uses для ребра в сущности Release может называть только сокет, который сущность каталога компонента-потребителя объявляет в своей usesSchema, и никогда не сокет, созданный сущностью Aggregate ad hoc, — оператор настраивает и соединяет в рамках архитектуры, а сущность Feature участвует в топологии, которую объявляет её собственная сущность каталога. Кроме того, объявление сокета в каталоге остаётся лучшим путём, и именно так поступает каталог стандартной библиотеки: сокет ad hoc — это запасной выход, а не новое поведение по умолчанию.

Домен 1: опыт разработчика (полиморфизм) Разработчики пишут uses: на одном уровне с values: и features:. Чтобы обеспечить UX без трения, схема нативно поддерживает полиморфизм:

  • Массивы строк: используются для простых логических ссылок на компоненты (например, tools: ["search-api"]), когда достаточно стандартной маршрутизации.
  • Карты объектов: используются, когда требуются строгие контракты доставки (например, databases: { hr_db: { target: "corporate-hr", inject: { env: [{ in: DB_URL, from: "host" }] } } }).
  • Никаких подстановочных знаков: формы с подстановочным знаком нет, что предотвращает «призрачные зависимости» и несанкционированное автоподключение: каждая запись называет один компонент, поэтому ["*"] останавливает сборку как несуществующая цель — ни одно имя компонента не может содержать *.

Домен 3: реальность Ops (нормализация) Чтобы шаблоны Go оставались предсказуемыми, компилятор Go нормализует полиморфные входные данные uses. Массивы логических ссылок на компоненты преобразуются в стандартные объекты, прежде чем попасть в строгий плоский словарь, известный как .context.uses.


3. Сквозные примеры

Два следующих примера демонстрируют два отдельных свойства явного столпа топологии: пример A доказывает, авторизовано ли соединение (типобезопасность между узлами), а пример B доказывает, как данные соединения физически доставляются (полиморфизм & нормализация).

Пример A: топологическая валидация и типобезопасность между узлами

Этот сценарий прослеживает, как селектор объявленного сокета обнаруживает, что ИИ-агент собирается подключиться к базе данных без обязательных меток соответствия, и останавливает сборку. Компилятор вычисляет написанный архитектором селектор меток по меткам цели как строки; он не интерпретирует значение метки, и никакой плагин политики в этом не участвует.

1. Стандартная библиотека (унифицированная schema: в каталоге) Архитектор платформы определяет структуру схемы, нативно отделяя когнитивную логику от топологических целей.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/enterprise-agent
version: 1.0.0
labels:
component.aggrega.ai/type: "worker"
spec:
usesSchema:
datastores:
selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
schema:
# 1. The Cognitive Intent
values:
system_prompt: { type: string, required: true }

2. Намерение разработчика (сущность Aggregate) Разработчик чётко отделяет то, что агент делает (values), от того, к чему агент подключается (uses).

components:
my_secure_vector_db:
type: core/qdrant-secure:1.0.0
values:
collection_name: finance_data
auditing_agent:
type: core/enterprise-agent:1.0.0
values:
system_prompt: "You are a financial auditing AI..."
uses:
datastores:
finance_memory: { target: "my_secure_vector_db" }

3. Выполнение компилятора и топологическая валидация

  1. Локальная валидация: при разрешении компилятор Go проверяет весь объект по разрешённой JSON Schema. Он проверяет базовые метки каталога у my_secure_vector_db. Если бы у базы данных не было метки restricted, компилятор немедленно остановил бы сборку с нарушением типобезопасности.
  2. Построение графа: при построении топологии компилятор Go полностью игнорирует содержимое, проверенное схемой. Он нативно читает uses.datastores.finance_memory.target из YAML и рисует явное ребро в графе IR.

Пример B: полиморфизм и нормализованный .context.uses

Этот сценарий показывает, как компилятор обрабатывает и ИИ-инструмент типа «чёрный ящик» (переданный как массив), и унаследованную реляционную базу данных (требующую карты с контрактом inject).

1. Каталог (домен 2): объявление schema: Архитектор допускает полиморфные массивы для инструментов, но требует строгих объектов для баз данных.

spec:
usesSchema:
# Polymorphic Array Socket (No injection needed)
tools:
selector: "tool.aggrega.ai/impact=read-only"
# Strict Map Socket (Requires delivery contract)
databases:
selector: "component.aggrega.ai/type=stateful-server"
inject: ["env", "file"]
schema:
values:
system_prompt: { type: string, required: true }

2. Намерение разработчика (домен 1): сущность Aggregate Разработчик использует простой массив для инструмента и явную карту для базы данных.

components:
my-agent:
type: core/python-worker:1.0.0
values:
system_prompt: "You are an HR bot."
uses:
# 1. Polymorphic Array: Simple logical component reference
tools:
- "corporate-search-api"
# 2. Strict Map: Dictating the environment variable delivery
databases:
hr_db:
target: corporate-hr-db
inject:
env:
- in: HR_DATABASE_URI # Local env var
from: "host" # Target provides key

3. Реальность Ops (домен 3): сущность Recipe Компилятор Go нормализует полиморфизм. Ops получает плоский, предсказуемый словарь .context.uses. Достаточно пройти циклом по каналу .context.inject в соответствующих разделах шаблона.

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: generic-worker
version: 1.0.0
spec:
capability: helm
implements: core/python-worker:1.0.0
source: "./charts/internal/python-runner"
locals:
primary_compute: worker-container
valuesMapping: |
env:
# Ops uses the pre-resolved inject map, kept apart from values and topology loops
{{- range $key, $value := .context.inject.env }}
- name: {{ $key }}
value: "{{ $value }}"
{{- end }}