一个无人声明的 socket,交付真实的值
本示例讲授一句话,以及它的两个部分:
消费方可以自创连接,但只能消费生产方声明的内容。
一位 Aggregate 作者在自己的 component 上编写了一个 uses: 条目,所用的 socket
名称没有任何目录实体声明过。该边会被构建并且能够交付——值到达渲染产物的方式
与通过已声明 socket 完全相同。但
该边可以携带哪些键仍由目标声明:一旦指定了目标未声明的键,构建就会中止。
这里的一切都从标准库目录解析。该工作区 没有编写任何自己的 Component、Feature 或 Recipe。
技术栈
三个 component,其中一个以两种不同方式连接:
| 实例 | 类型 | 说明 |
|---|---|---|
db | core/datastore/mariadb | 数据库 |
model | core/ai-model/anthropic | 模型端点;引用形式的实现,因此不为其运行任何计算资源 |
web | core/devtool/adminer | 控制台,同时消费两者 |
core/devtool/adminer 只声明了一个 socket:
usesSchema: databases: selector: "component.aggrega.ai/type=stateful-server" inject: [env]这就是其作者所预见的全部内容。位于数据库前端的控制台 是作者设想的连接;在环境变量中携带模型端点的控制台 则不是。
Aggregate 中写了什么
aggregate-delivers.yaml 在一个 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: modelassistant 没有出现在任何 usesSchema 中,无论是这个 Component 还是其他 Component。但它
仍然合法:目录对某个 socket 保持沉默,意味着该连接未被
预见,而不是被禁止;开发者拥有自己
应用的拓扑。
临时 socket 所放弃的,恰恰是缺失的 usesSchema 条目
本应携带的内容——没有 selector,因此没有任何东西约束该边可以到达哪个 component,
跨节点类型安全检查也无可评估;没有
inject: 允许列表;没有逐边的 valueSchema 或 infraSchema,因此逐边的
values: 和 infra: 没有可供检查的契约,也没有可继承的已声明
默认值。在此类 socket 上编写的逐边配置会被接受
并在未经检查的情况下传递,这正是每个在该支柱上没有契约的 socket 的行为——未编写 valueSchema 的已声明 socket 也处于
相同境地。
它没有放弃的,是该边可以携带的内容。endpoint 和 model
都是 core/ai-model/anthropic 在其 provides 支柱中声明的键。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example adhoc-uses-socket然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd adhoc-uses-socket构建
aggrega build --release release-delivers.yaml --auto-pull渲染输出和锁文件是生成的,而非随附提供:本示例只提交输入,其余内容全部重新生成。--auto-pull 在构建期间解析锁文件;事先运行一次 aggrega pull --release release-delivers.yaml 效果相同,并且之后的构建无需任何标志即可运行。目录实体从 hub.aggrega.ai 解析,即 .aggrega-config.yaml 指定的默认注册表,因此构建和 aggrega inspect 都不需要 --catalog 标志。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 的工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `adhoc-uses-socket` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `adhoc-uses-socket`,且不提供 `dir`:它会把示例写入一个新的 `adhoc-uses-socket` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `adhoc-uses-socket`,`release` 设为 `release-delivers.yaml`,`auto_pull` 设为 true,`write` 设为 true。告诉我构建写入了哪些文件;它们位于 `adhoc-uses-socket/dist/` 下。阅读输出
dist/compose/docker-compose.yaml 中的 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]四个变量,其中三个通过边交付,而且输出并不 记录哪个 socket 是已声明的:
ADMINER_DEFAULT_SERVER: db经由已声明的 socketdatabases到达。其 值是数据库 Recipe 的provides.host——一个 Compose 服务名。ASSISTANT_ENDPOINT和ASSISTANT_MODEL经由临时 socketassistant到达,携带模型 Recipe 的provides.endpoint和provides.model。
它们位于同一个映射中,按作者编写的顺序排列,彼此之间没有标记、没有注解,也没有 顺序差异。这正是关键所在:临时 socket 在声明上有所 不同,在交付上并无不同。只有一条 交付路径,两条边都走这条路径。
ASSISTANT_ENDPOINT 也值得作为一个预先编译(ahead-of-time)的事实来解读。
编译器并没有联系 Anthropic 来发现 https://api.anthropic.com;
是 Recipe 将其作为一个确定性的指针字符串发出,来源于模型
component 的 infra.endpoint,编译器只是路由该字符串而不
解释它。Adminer 本身并不读取任何 ASSISTANT_* 变量——这些
交付键由开发者选择,控制台的容器携带它们,
供容器中任何读取它们的程序使用。
即使渲染产物不记录这一区别,构建发出的图也会记录:每条边都带有一个 socket_declaration 字段,值为
declared 或 ad-hoc,因此如果某个组织希望每个连接都经过
其架构师声明的 socket,就应将其表达为治理策略,
而不是依赖编译器持有某种立场。参见
architecture/11-governance-and-compliance.md。
对照:消费方仍然不能自创的内容
aggregate-undeclared-key.yaml 是在 aggregate-delivers.yaml 基础上做了一处修改。该
临时边请求了第三个键:
- in: ASSISTANT_API_KEY from: api_keycore/ai-model/anthropic 在其 provides
支柱中只声明了 endpoint 和 model。该构建预期会失败:
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")中止本身就是要点,而值得注意的是它在何处触发:
出错路径指向临时 socket uses.assistant,并停在
连接层面,而不是其中的交付条目。在每条边上,from: 键都会
对照目标 Component 已声明的 provides 进行检查,socket 是否临时
对这一检查毫无影响。可以自创
socket 名称的作者,仍然不能在别人的 component 上自创输出键。
消息首先给出拒绝说明,然后是 Aggregate 以及编写该边的路径,
条目所在的机制和交付键,出错的键,解析时所依据的 component 类型,以及该类型已声明的键
(按排序顺序)——因此仅凭消息就能看出修复方法。完全未声明 provides 的目标
Component 同样会拒绝所有指向它的 from: 引用;只是没有已声明的键可列出,因此消息在
component 类型之后结束。
该写哪一种
在目录中声明 socket 仍是更好的做法,标准库目录也正是这样做的。已声明的 socket 带有一个 selector,
用于约束该边可以到达哪些 component,还带有 inject: 允许列表、
具有自身默认值的逐边契约,以及一段描述——这是对预期连接的一份可审查
陈述,并随提出它的实体一起进行版本管理。
临时 socket 不具备其中任何一项,该边的安全程度完全取决于
编写它的作者。
临时形式是一个逃生舱口,适用于本示例所展示的情形:目录作者 未预见、某一次部署需要的连接,而等待 目录变更就意味着推迟发布。使用它时要清楚它的代价。
有两项代价值得明确说明:
- 拼错的 socket 名称是一个合法的临时 socket,而不是错误。在本应写
databases的地方写成databses,会得到一次成功的构建,但没有任何内容 经由预期的 socket 流动。对于与已声明 socket 名称只差一处编辑的名称,编译器会给出一条同时列出两种拼写的提示——参见 errors/warnings.md 中的“Uses-socket near-miss lint”—— 但这只是警告,绝不会改变构建的结果。 - 有两个入口刻意不以这种方式开放。 Feature 挂载的
uses只能指定所挂载 Feature 声明的 socket,Release 的 逐边uses只能指定消费方 Component 声明的 socket。 运维人员在架构之内进行配置和连接;他们并不编写架构。 因此release-delivers.yaml只携带infra:,不涉及任何 socket——assistantsocket 属于 Aggregate 作者,且仅属于他们。
完整契约请参见
entities/component.md 中的“Topology Sockets: usesSchema”以及
architecture/07-dependency-resolution.md。