依赖解析
Aggrega 依赖解析与结构拓扑支柱
在 Aggrega 架构中,拓扑依赖通过 uses schema 支柱显式映射,以保持 values 载荷完全不透明。解析“谁与谁通信”是一项特定的挑战:必须映射复杂的多节点应用拓扑,同时不强迫开发者编写显式的网络路由、编排器层面的执行顺序或基础设施依赖。
1. 核心理念:为什么是 uses?
uses 块将跨组件依赖声明为纯粹的拓扑:Component A 依赖于 Component B 的公开 provides 契约,而不是 Component B 的物理地址或连接细节。拓扑位于 uses 中;配置位于 values 中。这种分离使编译器能够显式地看到所有跨组件的边,而无需从 values 的内容中推断。
Aggrega 通过将拓扑提升为名为 uses 的一等 schema 支柱来解决这一问题。
- **语义代理论点:**关键字
uses表示 L7 语义意图。如果一个 agentuses一个数据库,即使平台运维在两者之间注入透明的 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/v1beta1kind: Componentmetadata: 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. 编译器执行与拓扑验证
- 本地验证: Go 编译器在解析阶段根据解析后的 JSON Schema 评估整个对象。它会检查
my_secure_vector_db底层的目录标签。如果该数据库缺少restricted标签,编译器会立即以类型安全违规中止构建。 - 绘制图: 在拓扑构建阶段,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 key3. 运维现实(域 3):Recipe Go 编译器对多态进行规范化。Ops 得到一个扁平、可预测的 .context.uses 字典,只需在模板的相关部分遍历 .context.inject 管道即可。
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: generic-worker version: 1.0.0spec: 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 }}