跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

依赖解析

Aggrega 依赖解析与结构拓扑支柱

在 Aggrega 架构中,拓扑依赖通过 uses schema 支柱显式映射,以保持 values 载荷完全不透明。解析“谁与谁通信”是一项特定的挑战:必须映射复杂的多节点应用拓扑,同时不强迫开发者编写显式的网络路由、编排器层面的执行顺序或基础设施依赖。

1. 核心理念:为什么是 uses?

uses 块将跨组件依赖声明为纯粹的拓扑:Component A 依赖于 Component B 的公开 provides 契约,而不是 Component B 的物理地址或连接细节。拓扑位于 uses 中;配置位于 values 中。这种分离使编译器能够显式地看到所有跨组件的边,而无需从 values 的内容中推断。

Aggrega 通过将拓扑提升为名为 uses 的一等 schema 支柱来解决这一问题。

  • **语义代理论点:**关键字 uses 表示 L7 语义意图。如果一个 agent uses 一个数据库,即使平台运维在两者之间注入透明的 Wasm 代理网格,这在语义上依然成立。
  • **数学中立性:**Go 编译器原生解析 uses 结构来绘制中间表示(IR)图。它从不尝试解析或查询开发者的应用逻辑(values)。
  • Feature 原子性:uses 支柱同样适用于 Components 和 Features(包括凭据 Features)。这使得 sidecar 代理(一个 Feature)或凭据获取器能够自主声明自身的网络依赖,而不会污染其父 Component 的配置。

2. 统一 Schema 契约的机制

为了在不解析应用载荷的情况下提取运维指令,系统依赖严格的 JSON Schema 2020-12 声明,这些声明约束显式分离的 YAML 结构。

领域 2:拆分 Schema(usesSchema 与 schema) 为防止平台目录碎片化为难以管理的 schema 文件,Aggrega 使用拆分 Schema 引擎。原生 YAML usesSchema 严格定义并校验拓扑,而 schema:(JSON Schema 2020-12,通常以紧凑形式的简写编写)校验 values 和 infra 支柱的内容,并声明 provides 支柱的形状。开发者编写的 values 和运维人员设置的 infra 会按其声明的类型进行检查;provides 子 schema 声明一个 Recipe 所产生的下游契约的键名和类型,编译器会检查每个 inject 引用都指向一个已声明的 provides 键——但所产生的 provides 值本身以不透明字符串的形式传往下游,由编译器原样传递而不做解释,而不是由它进行类型检查,因为核心不解释所传递的值的含义。usesSchema 是声明套接字的地方,而声明套接字正是赋予它契约的方式。目录实体声明的套接字带有该实体的约束:一个说明它可以连接哪些目标的选择器、一个 inject 允许列表,以及每条边的 valueSchema / infraSchema。在 usesSchema 内部,平台架构师使用 selector: 字段——按架构师所写的字符串读取,不会复制到任何生成的 schema 中——由原生 Go 选择器引擎对其求值,以在已声明的套接字上强制实施跨节点类型安全。它确保如果某个套接字要求一个数据库,开发者就不能接入一个 Web 服务器。

选择器在被求值时须符合其语法,而对通过该套接字连接的每条边都会求值一次。引擎无法将其读作六种要求形式之一的选择器——由多余逗号留下的空要求、含有空白或语法用于区分各形式的字符之一(=、!、(、) 和逗号)的键,或缺少右括号的集合——会在该边上中止构建,并指出该要求,而不会被当作其他某个选择器来读取。正是这种严格性使检查保持可靠:如果宽松地读取,为排除前端而编写的 !tier=frontend 将只要求没有标签名为 tier=frontend,于是每个目标——包括前端——都会通过。同一语法也适用于附加槽选择器和 Feature 的 appliesTo;选择器语法列出了每种形式和每种拒绝情况。构建永远不会对没有边连接的套接字求值,因此 aggrega validate——无论针对整个目录,还是针对声明该套接字的 Component 或 Feature——都会读取每个已声明套接字的选择器,并在此时就拒绝格式错误的选择器,所用的代码和措辞与连接该套接字的构建相同。

然而,声明套接字并不是绘制边的唯一方式。Aggregate 作者可以在自己的组件上指定一个目录实体未声明的套接字——包括在完全未声明 usesSchema 的组件类型上——边依然会被构建。目录未为某个套接字声明条目,意味着它没有预见到该连接,这并不等同于禁止它,而应用的拓扑由开发者负责。这样的套接字称为**临时(ad-hoc)**套接字,其代价恰恰是声明所带来的东西:没有目录条目,因此没有选择器,也没有每条边的契约,跨节点类型安全无从求值。边可以承载的内容不变——它注入的每个键仍须指向目标的 provides 所声明的键,且目标仍须存在。输出图中的每条边都会记录它属于这两种中的哪一种,因此使用方无需猜测;关于运维人员如何彻底禁止临时套接字,请参阅 governance-and-compliance。

有两个层面有意不以这种方式开放,因为它们不编写应用的拓扑。Feature 附加的 uses 只能指定所附加的 Feature 声明的套接字,而 Release 的每条边 uses 只能指定使用方组件的目录实体在其 usesSchema 中声明的套接字,而不能是 Aggregate 临时编写的套接字——运维人员在架构内部进行配置和连接,而 Feature 参与的是其自身目录实体所声明的拓扑。在目录中声明套接字仍然是更好的途径,也是标准库目录的做法:临时套接字是一个逃生舱口,而不是新的默认方式。

领域 1:开发者体验(多态) 开发者将 uses: 写作 values: 和 features: 的同级项。为确保顺畅的用户体验,schema 原生支持多态:

  • **字符串数组:**用于标准路由即可满足需求的简单逻辑组件引用(例如 tools: ["search-api"])。
  • **对象映射:**用于需要严格交付契约的场景(例如 databases: { hr_db: { target: "corporate-hr", inject: { env: [{ in: DB_URL, from: "host" }] } } })。
  • 无通配符: 不存在通配符形式,从而防止“幽灵依赖”和未经授权的自动连接:每个条目都指定一个组件,因此 ["*"] 会作为不存在的目标中止构建——任何组件名称都不能包含 *。

领域 3:运维现实(规范化) 为保持 Go 模板的可预测性,Go 编译器会对多态的 uses 输入进行规范化。逻辑组件引用数组会先被转换为标准对象,再传入称为 .context.uses 的严格扁平字典。


3. 端到端示例

以下两个示例展示了显式拓扑支柱的两种不同特性:示例 A 证明连接是否获得授权(跨节点类型安全),示例 B 证明连接数据如何被实际交付(多态与规范化)。

示例 A:拓扑验证与跨节点类型安全

本场景展示了已声明套接字上的选择器如何检测到某个 AI Agent 即将连接到缺少所需合规标签的数据库,并中止构建。编译器将架构师编写的标签选择器作为字符串,针对目标的标签求值;它不解释标签的含义,也不涉及任何策略插件。

1. 标准库(目录中的统一 schema:) 平台架构师定义 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) 开发者清晰地将 agent 做什么(values)与 agent 连接到什么(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 编译器完全忽略经过 schema 验证的内容。它直接从 YAML 中原生读取 uses.datastores.finance_memory.target,并在 IR 图中绘制显式的边。

示例 B:多态与规范化的 .context.uses

本场景演示编译器如何同时处理黑盒 AI 工具(以数组形式传入)和传统关系型数据库(需要带有 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. 运维现实(域 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 }}