Wasm 插件契约
Aggrega 的编译流水线包含若干指定的插槽点,WebAssembly(Wasm)插件在这些位置扩展编译器的行为:治理插槽的四个角色(其中包括拓扑构建阶段的变更关卡(Mutation Gate)和静态分析阶段的验证关卡(Validation Gate));用于 FeatureRecipe 和 Recipe 步骤的渲染后插件流水线;provider 渲染插槽;解析器插槽;导入器插槽;以及带外的 lint 插槽。本页记录公开的 Wasm 插件契约:有哪些插槽、每个插槽消费和产生什么、每个插槽位于编译流水线的哪个位置,以及每个插件在其中执行的沙箱。
本页介绍插槽——流水线中的位置及其输入/输出结构。关于插件——Plugin 实体、按导出声明的能力、运行时限制,以及 publish→pull→build 生命周期——请参阅 Wasm 插件开发者指南。
Aggrega 内嵌一个 Wasm 宿主运行时(基于 Wazero 引擎的 Extism),它在一道 AOT 纯度防火墙之后加载并执行插件:宿主不授予客体任何环境能力——没有网络、没有文件系统、没有环境变量、stdio 被丢弃、可观测的挂钟时间被冻结在一个与构建无关的固定时刻——因此插件无法破坏编译器的预先编译(ahead-of-time)保证。完整的能力面——加载时的导入模块规则、实例化时的拒绝项以及精选的宿主函数——见下文的沙箱契约。Plugin 作者通过三语言 PDK(Go、Rust、TypeScript)面向宿主进行开发。aggrega lint 经由宿主分派 linter 套接字——即标准的 publishing-linter。当工作区配置了治理套接字的构建期角色时,aggrega build 会分派这些角色:解析期间的注解转换角色和拓扑构建时的标签转换角色(二者都会塑造输出),以及静态分析时的 IR 裁决和针对已渲染制品的渲染裁决。当某个角色上未挂接插件时,该角色不执行任何操作,因此没有治理配置的构建不受影响。aggrega build 还会在结束渲染的插件流水线中分派 FeatureRecipe 和 Recipe 的 pipeline:——每个声明的步骤都经由宿主针对已渲染的文档集运行,应用该步骤的 RFC 6902 补丁并产生其副作用。参见语言状态 → 编译流水线阶段。
沙箱契约
每个插槽都通过同一个宿主沙箱调度其插件。沙箱有两个相互独立的层:加载时的结构检查和实例化时的能力拒绝,二者共同界定了插件能访问什么、不能访问什么,以及插件自身需要负责什么。
导入模块规则(加载时)。 加载器遍历插件二进制文件的导入段,只允许三个模块命名空间下的函数导入:wasi_snapshot_preview1(客体语言运行时所链接的 WASI preview-1 运行时)、extism:host/env(Extism 运行时 ABI,即 PDK 自身的内存与 IO 内建函数)以及 extism:host/user(Aggrega 精选的宿主函数)。客体可以在允许的模块下导入任意函数名;任何其他模块下的导入指向的是宿主不提供的接口面,插件会在加载时被拒绝,并给出指明该模块和该导入的诊断。该规则有意不审查单个 WASI 函数名:静态链接的语言运行时会导入其实际代码路径从不调用的文件系统和套接字函数(由依赖传递引入),而声明一个导入并不授予任何能力。保证不发生 I/O 的是实例化时的能力拒绝,而不是导入审查。
零环境能力(实例化时)。 宿主以真实的 WASI 行为和零环境权限实例化客体:
- 没有文件系统:没有预打开的目录,因此文件系统调用会在调用边界处失败;
- 没有网络套接字;
- 空的环境变量;
- 丢弃的 stdio:客体写入 stdout 或 stderr 的任何内容都不会到达宿主的流;
- 冻结的可观测挂钟,固定在一个与构建无关的不变时刻,因此读取时间的客体无法把构建时间泄露到输出中;
- 真实且递增的单调时钟:客体语言运行时启动时需要它,而单调时间度量的是经过的时长,而非挂钟时刻;
- 真实的宿主熵:固定的熵会使语言运行时的内部哈希种子保持稳定,从而掩盖客体的不确定性,而不是让它以输出差异的形式显现;
- 单个合成的程序名作为 argv。
客体实际发起的 I/O 调用(打开文件、连接套接字)会在调用边界处失败。这正是 WASI 自身基于能力的安全模型:沙箱拒绝的是能力,而不是去监管代码。
输入只通过载荷和精选的宿主函数到达。 插件渲染或求值所需的一切,都在其插槽携带的载荷中接收:图与节点投影、值以及渲染上下文。载荷采用哪种编码按插槽固定,并在下文该插槽自己的章节中注明;每个已发布的载荷类型都为其插槽的编码提供编码和解码入口点,因此客体只需调用一个函数,而无需选择解析器。对于带源的 provider 渲染,载荷携带的是源清单而不是源字节:节点源根目录下一组排好序的 {path, is_dir} 条目,宿主不对其做任何 provider 布局解释。客体应用自己的布局逻辑(选择唯一的 compose 文件、下降到 chart 根目录、要求存在 Chart.yaml、递归引入模块),并通过宿主回调精确读回它所选择的部分。在载荷之外,宿主绑定一组精选的最小权限宿主函数,并只向插件授予其二进制文件所导入的那些函数:
aggrega_log:写入宿主日志目标的一行日志。aggrega_emit_warning:宿主在调用结束后呈现的结构化警告。aggrega_fetch_external_input:外部输入获取通道(见下文)。aggrega_pack_source:源选择回调:客体在源根目录下指定一个{file | dir | tree, path}选择,宿主在一个将路径解析到根目录之下并拒绝..的沙箱中,精确读取并打包该选择。aggrega_read_source_file:在同一沙箱下读取单个文件的内容,用于依赖内容的源选择。aggrega_parse_source:生产者消费回调:客体指定一种语法格式并交出源字节,宿主为该格式解析出一个解析器、运行它,并返回其生成的规范树。消费者借此通过宿主获取生产者的输出,而不必自己调用生产者客体;宿主将其限制为单层,以这种方式到达的生产者若再次调用它会被拒绝,因此消费者对每个源调用一次,并可依次消费多个源。
宿主从插件的 .wasm 二进制文件推导出其导入的函数集合,依据精选的允许列表进行校验,并与客体 describe() 声明的宿主函数交叉核对。aggrega plugin sync 将该集合记录在实体的 spec.runtime.hostFunctions 中,发布时会拒绝记录与二进制文件不一致的实体,因此每个插件的宿主接口面在目录中可见,且不会与二进制文件产生偏差。
回调失败携带可机器匹配的代码,位于 hostfunc_error_code 下。 返回应答的宿主回调(aggrega_fetch_external_input、aggrega_pack_source、aggrega_read_source_file 以及生产者消费回调 aggrega_parse_source)以带内方式传递失败:应答信封携带一条人类可读的消息,并在其旁边携带一个位于 hostfunc_error_code 下、取自封闭词汇表的可选可机器匹配代码。消息是写给人看的自由文本;代码是客体无需解析消息即可据以分支的稳定标识。成功时没有代码;失败时宿主同时设置两者。PDK 将这一对值呈现为类型化错误,其文本为消息,其代码字段供客体与该语言重新导出的代码常量进行匹配。客体通过回退到消息来容忍缺失的代码和它无法识别的代码,因此按代码匹配是叠加在始终存在的消息之上的尽力而为的细化,绝不能替代消息。封闭的取值集合见宿主函数错误代码 schema。
🔴 在这一边界上有两套不同的词汇表命名失败,你读取的键表明你拿到的是哪一套。 混淆两者是这里唯一值得特别指出的错误,因为两者的值都是普通字符串,宿主和客体都不会检查它来自哪个集合。
hostfunc_error_code,位于宿主发给客体的应答上。 其值是上面链接的封闭目录中的成员,这是一份固定、变化缓慢的列表,列出宿主回调可能失败的方式。由于集合是封闭的,客体可以将值与其工具包重新导出的具名常量进行匹配,并根据结果分支。condition_code与condition_short_code,位于客体返回给宿主的插槽输出上。 它们是客体自身引发的终止条件的两个标识符,来自编译器注册的开放且不断增长的条件集合,而不是来自该目录。condition_code是该条件注册时使用的描述性代码;condition_short_code是紧凑形式(字母E加四位数字),供读者引用、搜索并粘贴到报告中。宿主会在其渲染的诊断的方括号头部打印短代码,因此客体引发的条件与编译器引发的条件一样可以被准确引用。宿主不推导这两个值,但会检查它们:若短代码不对应本编译器声明的任何条件,或对应的条件编号已被废弃,构建会终止,而不是让读者看到一个无法解析到任何内容的标识符。
guest 一侧的两个标识符一起报告:只设置其中一个而未设置另一个的 guest 命名了一个主机无法解析的条件,此时主机改为报告它自己的通用插件失败条件,消息中仍携带完整的失败信息。而且 condition_code 绝不是主机函数目录中的成员,因此将其与重新导出的常量比较永远不会匹配——这正是每个键各自命名自己的词汇表、而非泛指失败的原因。
每个回调的槽都有明确的编码,凡是存放负载文档的槽都以二进制形式存放。 主机回调接受的每个参数都是指向 guest 内存的指针,aggrega_log 的数值级别除外;返回应答的回调也以指针作答。每个槽存放的内容按回调固定:
| 回调 | 参数槽 | 应答槽 |
|---|---|---|
aggrega_log, aggrega_emit_warning | UTF-8 文本——无负载文档 | 无应答 |
aggrega_fetch_external_input | 纯 UTF-8 URL——无负载文档 | 规范 CBOR |
aggrega_pack_source, aggrega_read_source_file, aggrega_parse_source | 规范 CBOR(RFC 8949 §4.2.1) | 规范 CBOR |
该表按每个槽存放的内容划分,而不是按回调本身:存放负载文档的槽携带规范 CBOR,存放纯字符串(日志行、诊断字段、URL)的槽携带 UTF-8 文本。aggrega_fetch_external_input 是唯一两个槽不同的回调:其参数是纯 URL,按 UTF-8 文本读取;其应答是规范 CBOR 编码的负载文档。
guest 在携带负载的槽上要做什么、绝不能做什么。 🔴 存放负载文档的槽存放的是不透明的字节序列,而非 UTF-8 文本——因此这是 guest 声明的形态,而不只是它放入的字节。将此类请求按字符串分配、或将此类应答按字符串读取的 guest 无法互通:任一方向的文本转换都会破坏二进制字节。失败是显式的而非部分的:主机无法解码的请求会以携带 request_undecodable 代码的应答信封返回,形态与其他回调失败一样都在带内,因此 guest 会报告它,而不是基于读了一半的负载继续执行。负载类型为:aggrega_pack_source 的 SourcePackRequest 和 SourcePackResponse,aggrega_read_source_file 的 SourceFileRequest 和 SourceFileResponse,aggrega_parse_source 的 ParseInput 和 ParseSourceResponse,以及 aggrega_fetch_external_input 仅有的应答类型 FetchExternalInputResponse,其 URL 按文本分配。各工具包的具体做法如下:
- Go——用请求类型的
EncodeCBOR()构建请求,用pdk.AllocateBytes(而非pdk.AllocateString)分配,并对应答指针所指向的内存调用ReadBytes()读取应答,再交给应答类型的DecodeCBOR。请求一侧的例外是 fetch URL,用pdk.AllocateString分配;其应答的读取方式与其他回调相同。//go:wasmimport声明无论哪种情况都是指针,因此签名中看不出形态——形态体现在分配和读取上。 - Rust——
#[host_fn]声明直接表明形态:三个负载回调均写作fn <callback>(request: Vec<u8>) -> Vec<u8>;,fetch 回调写作fn aggrega_fetch_external_input(url: String) -> Vec<u8>;。用请求类型的encode_cbor()构建请求,用应答类型的decode_cbor(&raw)读取应答。 - TypeScript——用请求类型的
encodeCBOR…函数构建请求,用Memory.fromBuffer(而非Memory.fromString)分配,并用readBytes()读取应答,交给应答类型的decodeCBOR…函数。fetch URL 用Memory.fromString分配;其应答与其他回调一样用readBytes()读取。与 Go 一样,declare module条目无论哪种情况都是指针。
调用 PDK 包装函数的 guest 无需做上述任何事。 包装函数——FetchExternalInput、PackSource、ReadSourceFile 和 ParseSource,按各语言自己的拼写——负责分配和编码,且其签名都不涉及线上类型,因此通过工具包调用这些回调的 guest 自身无需分配或解码任何内容;自行声明并调用主机函数的 guest 则按上文所述分配并读取其内存。以文本分配的请求会被拒绝而非得到一半的服务,以文本读取的应答无法解码,因此两侧之间的不匹配会明确暴露,而不会悄无声息。
有两个可以依赖的特性。应答无论成功或失败都采用相同的编码:guest 读取一个槽,在解码之前无法知道其中是哪一种,因此用一个解码入口点读取两者,上文所述的错误代码和消息也经由它到达。并且 guest 以其工具包自身的字段类型填充字节值字段——Go 中为字节切片,Rust 和 TypeScript 中为 base64 字符串——因为转换为二进制编码所携带的原始字节序列是生成的编码器的工作,在输出时完成,在输入时逆转。这涵盖 ParseInput 的源字节、aggrega_read_source_file 返回的文件内容、aggrega_fetch_external_input 获取的内容,以及 pack-source 应答中每个打包文件的内容:这些字节只跨越边界一次,而非双重编码,也没有 guest 需要对编码器即将解除 base64 的内容做 base64。read-source-file 和 fetch 应答的 content 字段为空时会被省略,因此空文件或零长度获取负载的应答完全不携带内容;这样的应答仍是成功,因为失败总是携带消息和代码,每个工具包的包装函数会为其返回空字节。aggrega_parse_source 返回的树以字节序列传输,原样承载其自身的 JSON 文档;主机既不读取也不重塑它。解析器在其自身的 parse 导出上以相同编码读取相同的 ParseInput——参见解析器插槽。
规范意味着相同的输入在每一侧都产生相同的字节,这使得负载可以在三个插件工具包之间进行比较,而不只是往返转换,也正因如此,构建的输出保持字节一致。guest 中不需要 CBOR 库,也无需手工解析字节:每个已发布的负载类型都附带其槽编码所需的编码和解码入口点。
确定性由插件作者负责。 主机原样使用 guest 的输出字节,不对其运行任何序列化器,因此每个插件必须遵守的契约是:相同的输入产生相同的输出字节。沙箱移除了环境中的不确定性来源——挂钟时间、环境变量、文件系统状态——但有意不掩盖其余部分:将熵或流逝的单调时间编码进输出的 guest,会在多次运行之间产生明显不同的字节,而不是一个被稳定隐藏的缺陷。
外部输入获取通道。 aggrega_fetch_external_input 是获取远程内容的唯一许可通道,它由主机代理,而非 guest 的网络访问:guest 指定一个 URL,主机按外部输入固定规则提供字节。在 Release 的 lockfile 中固定的 URL 从本地内容寻址存储提供,并按其记录的摘要校验;未固定的 URL 会被拒绝,并给出指明该 URL 及固定它的步骤的诊断,因为渲染只使用其 lockfile 记录的闭包,绝不扩大它。固定记录在解析 Release 的依赖时写入,这是唯一会固定任何内容的时机。开发者指南完整介绍了编写方法和固定规则。
保持顺序的映射
载荷携带的某些映射在其插槽的 schema 中被标记为保序,因为其条目的顺序是其所承载内容的一部分:构建的节点、节点的标签、节点上的附件、流水线步骤的输入和输出、provider 声明的键空间。已发布的载荷类型将每个此类映射保存在一个按设置顺序保留条目的容器中:
| 工具包 | 容器 |
|---|---|
| Go | aggrega.OrderedMap[V]——工具包对 ABI 包中 abi.OrderedMap[V] 的命名 |
| Rust | 来自 aggrega-abi crate 的 OrderedMap<V>,由工具包重新导出 |
| TypeScript | 该语言自身的 Map<string, V> |
Go 和 Rust 的容器提供映射的各项操作:查找键、设置键、删除键、读取键、按顺序遍历条目、计数。设置容器中已有的键会替换其值并保留其位置;新键排在所有现有键之后。
顺序在两种编码中都得以保留。 在二进制编码中,被标记的映射按容器的顺序写为一个有序的条目列表——每个条目是一个二元列表,先键后值——而规范编码原本会将映射按键排序写出。在文本编码中,它是一个 JSON 对象,其成员按容器的顺序写出。任一编码的解码器都会拒绝包含重复键的映射,并指出该键。schema 未标记的映射在二进制编码中保持排序映射形式,在已发布的类型中使用语言的普通映射类型。
对 guest 的三点影响:
- 顺序即输出。 由于被标记的映射按填充顺序写出,guest 若从没有固定顺序的来源填充它(例如遍历 Go 内置 map),对相同输入的多次运行会写出不同的字节。请按固定顺序填充。
- 仅当映射保留在其容器中时,顺序才得以保持。 guest 若将载荷转换为其语言的通用值类型,就会得到该类型的顺序:Go 的
map[string]any没有顺序,而 Rust 的serde_json::Value会将对象键排序,除非该 crate 以其preserve_orderfeature 构建。 - 在 TypeScript 中,通过生成的函数进行读写。 包含被标记映射的类型会逐个成员解码其 JSON,因此读起来像数组索引的键(如
"8080")会保持原位,而JSON.parse会把它移到对象开头;其编码器将每个Map写为对象,而JSON.stringify会把Map写为{}。Map的Object.keys也为空:请使用Map自身的keys()读取其键。
输入标记为敏感的值
插件在其返回的拒绝或警告中,绝不引用其输入标记为敏感的值——无论是按键标记,还是作为整体被标记的负载的一部分。 拒绝是输出携带的 error;警告是输出携带的 Diagnostic(无论其严重级别),或通过 aggrega_emit_warning 发出的警告。宿主在报告该文本的任何地方——命令行、语言服务器和编辑器的问题列表、助手工具——都原样传递它,且不会从中读取任何值,因此插件是唯一能够将该值排除在外的一方。请改为指明键、设置或位置:读者可以据此找到该值。
该规则既适用于插件自己写的文本,也同样适用于库为插件写的文本。模板引擎会报告它正在求值的数据,schema 校验器会引用未通过 pattern 的值,解析器会引用它无法读取的词法单元。若此类失败涉及输入所标记的值,报告时应不带该值——例如,将每个被标记的值替换为占位符后再次运行同一步骤,若该次运行在同一位置失败,则报告该次运行的失败,否则说明失败文本已被隐去。在作为整体被标记的负载中,该负载中的每个值都是被标记的值,而其键——即文档的结构——仍可读取。
输入将键或负载标记为敏感的位置,按线上格式中的名称书写:
| Socket 与导出 | 读取标记的位置 |
|---|---|
provider render_node 与 validate_node_input(RenderNodeInput) | node.sensitive_rendered_keys:每个键指向 node.values 的一个条目(当这些值是该 Component 自身的值,并以其声明的叶子为键时——Recipe 的 valuesMapping 写入的键不对应任何声明,因此这里不会标记其中任何一个),或指向工作负载容器 attachments 映射中读取了声明为敏感的槽位的条目。node.sensitive_values 将 node.values 作为整体标记:当由某个 valuesMapping(Recipe 的,或某个附件的 FeatureRecipe 的)生成这些值且其读取了作者声明为敏感的值时,它为 true。当工作负载的模板读取了此类值时,workload_projection.sensitive_workload 以同样方式标记该工作负载的每个值;artifacts_projection.entries 的每个条目针对其自身内容携带 sensitive_content,其中包括解析器关于该内容的消息。当生成 omits 某个条目的 kind、name 或 namespace 中任一项的模板读取了此类值时,该条目携带 sensitive,此时该条目的每个字段都是被标记的值。node.features 的每个条目携带其自身附件的标记:sensitive_payload_leaves(其 Feature 声明为敏感的 values.<path> 与 infra.<path> 叶子)、sensitive_inject(读取了其 Feature 声明为敏感的 provides 键的 inject 交付键)以及 sensitive(该附件是否处理任何声明为敏感的内容)。 |
governance ir-verdict(PolicyInput) | graph:每个节点的 sensitive_payload_leaves,以及每个附件的 sensitive_payload_leaves、sensitive_inject 和 sensitive。这些标记所指的每个值到达时都已是隐去标记 {"aggrega_withheld": "declared"},因此值本身永远不会到达插件。 |
其他任何 socket 输入,以及其他任何 provider 导出的输入,都不携带标记。键标记只指向它能与某个声明精确关联的内容,因此键未被标记绝不意味着该值可以安全引用:它意味着没有任何声明能与该键关联。负载标记读取自生成该负载的模板的引用——引用触及了已声明的值、模板传递了其全部数据,或模板无法解析——而从不读取自值本身,因此没有该标记意味着就其引用所示,该模板未读取任何已声明的值,或者没有模板生成该负载;它并不表明该负载不含任何敏感内容。
Wasm 插槽在流水线中的位置
编译流水线预留了以下插槽点。形态标签沿用 Status 页面中的四标签分类法。
| 插槽 | 流水线位置 | 当前状态 |
|---|---|---|
治理插槽,annotation-transform 角色 | 解析(在注解展开之前) | 可用 —— 当工作区挂接 annotation-transform 插件时调度;注入的注解会由展开转换为 Feature 挂接 |
治理插槽,label-transform 角色 | 拓扑构建(Topology Builder) | 可用 —— 当工作区挂接 label-transform 插件时调度;通过 JSON Patch 自动为节点标签打标 |
治理插槽,ir-verdict 角色 | 静态分析(Static Analyzer,作用于 IR 图) | 可用 —— 当工作区挂接 ir-verdict 插件时调度;halt 裁决会终止构建 |
治理插槽,render-verdict 角色 | 渲染(作用于渲染产物) | 可用 —— 当工作区挂接 render-verdict 插件时调度;halt 裁决会终止构建 |
FeatureRecipe 和 Recipe pipeline: 插件 | 插件流水线(渲染后变更) | 可用 —— 每个声明的步骤针对渲染后的文档集运行,应用 RFC 6902 补丁并产生副作用 |
| Provider 渲染插件(helm、helm-chart、compose、terraform、cloudformation) | 基础渲染(各 provider) | 可用 —— 每个 provider 都通过其 Wasm guest 进行渲染;渲染仅限 Wasm,没有宿主内渲染器回退 |
解析器插件(parse:<format>) | 渲染阶段(用于 render-verdict 策略);以及带外(用于导入) | 可用——当制品的格式是 render-verdict 策略无法原生读取的格式时调用,经由 aggrega_parse_source 为导入器调用,以及用于识别未指明格式的导入的格式 |
导入器插件(import:<format>) | 带外(aggrega import) | 可用——由 aggrega import、编辑器会话和面向助手的工具分派 |
Linter 插件(linter/publishing) | 带外(aggrega lint) | 可用 —— publishing-linter 已随附发布,并通过 aggrega lint 经由宿主运行 |
注解驱动的 Feature 展开子阶段属于解析的一部分,是原生 Go 流水线阶段,而不是 Wasm 插槽。它依据目标 Feature 的 spec.schema 校验注解值,并在 IR 构建时注入合成的 Feature 挂接。关于六个承载注解和标签的界面,参见 vocabulary/labels-and-annotations.md;关于绑定形态与编写指导,参见 providers/well-known-annotations.md。
输出形状契约——当前已有的内容
治理插槽在其四个角色中的每一个上都带有一个类型化的契约面,具体是哪一个由角色决定。Plugin 作者实现生成文档所述结构的 guest 端代码;当工作区在某个角色上挂接插件时,host 会在构建时读取这些结构,每个已配置的插件读取一次。下面各小节按流水线调度它们的顺序排列。
annotation-transform 角色——注解注入输出
流水线位置。 解析阶段,在组件解析完成之后、注解驱动的 Feature 展开运行之前。
输入形状(host → guest)。 一个 AnnotationTransformInput 文档,包含:
targets——注入目标:guest 可以添加注解的已解析组件——即边界直接指定的组件,以及边界的aggregates:下的路由条目路由进来的每个组件,无论该条目是否指定了它——每个都带有其boundary_path、component_name(对于路由进来的组件,是它在构建图中的点分 id,例如metrics.query)以及 Release 在其上编写的annotations,这样 guest 可以在不覆盖作者所写值的前提下决定要添加什么。每个注解值都按原样到达——字符串、子键对象,或者在组件选择退出它本会继承的某个注解时为null——且组件携带的每个键无论其值如何都会出现。由 host 确定性地排序。binding_keys——Manifest 为其注册了绑定的注解键,按作者顺序排列。注册键下的注入会进一步展开为 Feature 挂载,因此 guest 读取此列表以注入会生效的键。host 不要求注入必须指定已注册的键:未注册的注入注解的行为与作者编写的未绑定注解完全相同。sources——挂载在with.sources下声明的定义文件,每个都带有其基本名称路径和内容,按路径排序。settings——挂载在with.settings下声明的自由格式设置对象,原样传递给 guest。
settings 和 sources 与其他所有角色读取的是同一个与引擎无关的 with 通道,当挂载未声明时两者均不存在。由于此角色的输出会影响构建,挂载的设置和源内容会在 pull 时固定到 release 锁文件中,并在构建时从中重建。
输出形状(guest → host)。 一个 AnnotationTransformOutput 文档,包含:
injections——要添加的注解,按顺序排列。每一项指定一个已有的目标坐标(boundary_path和component_name),以及annotation_key及其annotation_value:一个字符串,或一个子键对象,后者用于一次路由多个子键的绑定。
host 只应用注解的添加,只应用到它所提供的坐标上,且每项的值都是作者可以在该注解上编写的值。它读取注入值的方式与读取在 Release 中编写的同一个值完全相同——对象的子键按 guest 写入的顺序——因此展开过程对待它就如同对待作者编写的注解。如果某个注入指定了载荷中不存在的坐标,或携带 null、列表、数字、布尔值或没有子键的对象,构建会中止,并给出指明该坐标和注解的消息,而不是被静默丢弃或应用;在应用任何部分之前会先检查整个输出。正是这种限制界定了该角色:在此挂载插件的运维人员声明的是注解注入,仅此而已。如果构建随后因注入注解的路由方式、因绑定的 Feature 的 schema 不接受的子键值,或因 Release 侧注解不得使用的支柱而拒绝该注入注解,其消息会指明注入它的插件及其所挂载的角色。
线路编码。 此角色的载荷和结果在两个方向上都以 canonical CBOR(RFC 8949 §4.2.1)传输。guest 通过载荷类型自带的入口点读写它——Go 中为 DecodeCBOR 和 EncodeCBOR,Rust 中为 decode_cbor 和 encode_cbor,TypeScript 中为 decodeCBORAnnotationTransformInput 和 encodeCBORAnnotationTransformOutput——因此无需 CBOR 库,也无需手工解析字节。在 Rust 中,导出函数接收并返回 Vec<u8>;在 TypeScript 中,它读取 Host.inputBytes() 并写入 Host.outputBytes(...)。每个目标的 annotations 是 schema 标记为保序的映射,因此它以有序条目列表的形式传输,顺序与目标持有的顺序一致,guest 通过其工具包的保序容器读取它;每个值以其 JSON 的字节传输,与注入的 annotation_value 在另一个方向上的传输方式相同。settings 以其 JSON 文档的字节传输,guest 需要查看其内部时将其按 JSON 解析。不是此编码的 AnnotationTransformOutput 的应答——以 JSON 编写的应答,或带有该形状未声明的顶层字段的应答——会使构建中止,并指明插件及其导出函数,而不是被当作空的注入列表读取。通过 aggrega plugin run-local --export transform_annotations 直接调用时,guest 收到的是作者编写的 JSON 载荷转换成此编码后的结果,其应答按该导出的输出形状读取并以 JSON 打印——不符合该形状的应答会被拒绝并指明该导出,与构建拒绝它的方式相同。
类型定义。 annotation-transform 线路类型——AnnotationTransformInput、AnnotationTransformOutput、AnnotationTarget、AnnotationInjection、AnnotationSource——在全部三个 ABI 包中发布,由同一个编解码器生成,因此三者保持同步。
label-transform 角色——JSONPatch 输出
流水线位置。 拓扑构建阶段,在图被展平之后、IR 图构建之前,因此分析器评估的插槽选择器和 Feature 选择器读取的是它留下的标签。
输入结构(host → guest)。 一个 MutatorInput 文档,包含:
compilation_context——release 标识(release_name、environment)。graph——拓扑节点的MutatorGraph投影:每个节点的 Component、解析后的版本、标签,以及其实例声明的values。settings——挂载在with.settings下声明的自由格式设置对象,原样传递给 guest。sources——该挂载在with.sources下声明的定义文件,每个文件带有其基本名称路径和内容,使 mutator 可以由签入的规则文件或映射文件驱动,而不是由内联设置驱动。
该图是一个投影而非 IR 图:每个节点携带其已解析的标签集以及其实例在 Aggregate 中声明的值,而边和 feature 载荷保留在编译器内部。这些值是 Aggregate 自身的值,其模板已根据其参数求值,因此提升为参数的值会以 Release 所提供的值到达;Component 的 schema 声明的默认值,以及 Recipe 或 Feature 贡献的任何内容都不在其中,不声明任何值的节点不携带 values 键。节点的 Component 声明为敏感的值会与针对图的裁决中完全一样被隐去——它读作 {"aggrega_withheld": "declared"}——而任何声明都未触及的每个同级值都按原样到达。正是这一点让开发者声明的配置能够决定标签——例如,一个其值启用了向量扩展的数据库被提升为 datastore.aggrega.ai/engine: vector。settings 和 sources 是 verdict 角色读取的同一个与引擎无关的 with 通道;host 只传递它们,从不解释其内容。由于 mutator 的输出会影响构建,该挂载的设置和源内容在 pull 时固定到 release lockfile 中,并在构建时从中重建,因此在下一次 pull 之前,mutator 输入不受 pull 之后对二者任何一方所做更改的影响。
输出结构(guest → host)。 一个 MutatorOutput 文档,包含:
patches——一个不透明 JSONPatch 文档(RFC 6902)数组,由 host 仅应用到节点标签上;输入携带的值是只读的。
每个 patch 通过 JSON Pointer (RFC 6901) 定位特定节点的标签;host 按数组顺序应用这些 patch,并将变更后的标签集重新导入 IR 图。label-transform 角色的职责是企业级自动打标签——添加企业策略声明的合规 / 可观测性 / 成本归属标签,而不修改目录内容。标签面是该角色唯一被认可的目标:触及节点标签以外字段、添加或删除节点、或设置非字符串标签值的 patch 会使构建停止,而不是被静默吸收。RFC 6901 是 Aggrega 中每个文档路径面的路径语法基线——包括此处的 Wasm 插件契约、.locals 的 *_path 导出,以及语料库其他地方的 *Path schema 字段。规范的基线声明,以及区分两个编写侧的 *Path / *_path 后缀规则,参见 02-naming-conventions.md 中的“Document-path naming-suffix discipline”。
传输编码。 该角色的载荷和结果在两个方向上都以规范 CBOR(RFC 8949 §4.2.1)传输。规范意味着相同的输入在每一侧都产生相同的字节,这使得载荷可以在三个插件工具包之间进行比较,而不仅仅是往返传输,这也是构建输出保持字节一致的原因。guest 通过其工具包的载荷类型已携带的入口点读写它——Go 中的 DecodeCBOR 和 EncodeCBOR,Rust 中的 decode_cbor 和 encode_cbor,TypeScript 中的 decodeCBORMutatorInput 和 encodeCBORMutatorOutput——因此不需要 CBOR 库,也无需手动解析字节。在 Rust 中,导出函数接收并返回 Vec<u8>;在 TypeScript 中,它读取 Host.inputBytes() 并写入 Host.outputBytes(...)。图的 nodes、每个节点的 labels 以及每个节点的 values 是 schema 标记为保序的映射,因此它们以有序条目列表的形式传输——节点按构建持有它们的顺序(即作者顺序),每个节点的标签按该节点携带它们的顺序,每个节点的值按 Aggregate 编写它们的顺序——guest 通过其工具包的保序容器读取这三者。每个值以其 JSON 文档的字节传输:Go 和 Rust 工具包将其作为该 JSON 交给 guest,由规则按需解析,TypeScript 工具包则交出已解析的值。
有两点不因此改变。patches 数组仍为 JSON:socket 将每个 patch 文档作为不透明内容原样传递,双方都不读取其内部,因此 patch 文档自身的结构与其 socket 所用的编码无关。此外,settings 和 sources 仍按原样传递——settings 以挂载所编写的字节形式到达,guest 如需查看其内部,可将其作为 JSON 解析。
其他每个治理角色都使用相同的编码——annotation-transform 角色和两个 verdict 角色都在各自的章节中说明了这一点——因此服务多个角色的 guest 在其服务的每个角色上都使用规范 CBOR,并通过各自类型的解码入口点读取每个载荷。
类型定义。 mutator 传输类型——MutatorInput、MutatorOutput、CompilationContext、MutatorGraph、MutatorNode——发布在全部三个 ABI 包中(github.com/aggrega-ai/aggrega-abi/go、aggrega-abi crate 和 @aggrega-ai/aggrega-abi),由同一个编解码器生成,使三者保持同步。host 组装输入,并应用 guest 返回的 patch。
verdict 角色——verdict 数组输出
策略 guest 检查一次构建并返回一个 verdict 列表;host 依据 每个 verdict 的严重级别采取行动,从不解读策略本身。完整的 说明——四个角色、严重级别、由运维人员提供的输入通道、为编译器内置的两个引擎之一 编写策略、包装外部策略引擎、参考 guest,以及运维人员如何挂接 策略——见治理插槽页面。本节记录 流水线位置和类型化的线路形态。
流水线位置。 一个策略恰好挂接在一个 verdict 角色上,该角色决定它在何处求值:
ir-verdict——在静态分析阶段、基础渲染之前求值。分析器在每次构建时组装载荷。render-verdict——在渲染之后,针对输出的制品求值。
当工作区挂接了 verdict 角色插件时,流水线将该角色的载荷编组传给插件,并读回其 verdict。
输入形态(host → guest)。 角色决定载荷:
ir-verdict的PolicyInput携带graph——完整的、与能力无关的 IR 图(与 Topology Builder 输出的形态相同),包含编译器持有的每个节点、边和挂接细节,只是作者声明为敏感的值会以隐去状态到达(参见输入标记为敏感的值)——以及precalculated_paths,即分析器同时枚举出的路由路径,使策略无需重新遍历图即可推理可达性。该图是带版本的 IR 图,单一来源于ir-v1beta1schema;IR 形态并非机密(它与aggrega inspect输出的图相同),其中的机密是指针,绝不是明文。render-verdict的RenderPolicyInput携带artifacts——按路径排序的渲染输出文件,使相同输入的多次运行在线路上字节一致。每个条目携带制品的输出path及其渲染后的content;当产生它的 provider 声明了格式时,还携带渲染所用的format,以及tree,即 guest 无法原生读取的格式的已解析规范视图,由 host 通过解析得到的 parser 解析并不透明地传递。二者在不适用时均缺省——guest 能原生读取的格式(JSON、YAML)不做解析,由 guest 从content读取。
两个角色还都携带挂接的 sources(host 在构建时读取并原样交给 guest 的策略定义文件,路径为基本名,内容不透明)和 settings(原样传递的自由格式对象)。挂接未声明时,二者均缺省。
输出形态(guest → host)。 一个 PolicyOutput 文档,携带:
results——Diagnostic条目数组,每个条目带有severity(halt、warn或info)和message字符串。verdict 还可以在同一条目上设置code、rule_id、classification、source_ref、location和suggest;在每条严重级别路由上,host 都会将 verdict 携带的这些字段追加到渲染后的 verdict 中。
只有触发的 verdict 才会出现;允许的求值返回空数组。host 遍历 verdict,并将每个严重级别映射为动作:halt 停止构建(显示每条 halt 消息),warn 标记该 verdict 并让构建继续,info 记录它而不影响结果。halt 通过与选择器或 appliesTo 违规相同的关卡停止构建。
线路编码。 两个角色的载荷,以及 guest 在任一角色返回的 PolicyOutput,均以规范 CBOR(RFC 8949 §4.2.1)传输。guest 通过载荷类型自带的入口点读写它们——Go 中为 DecodeCBOR 和 EncodeCBOR,Rust 中为 decode_cbor 和 encode_cbor,TypeScript 中为 decodeCBORPolicyInput、decodeCBORRenderPolicyInput 和 encodeCBORPolicyOutput——因此无需 CBOR 库,也无需手动解析字节。在 Rust 中,每个导出接收并返回 Vec<u8>;在 TypeScript 中,它读取 Host.inputBytes() 并写入 Host.outputBytes(...)。图中保持顺序的映射,包括其 nodes 和每个节点的 labels,按构建持有它们的顺序以有序条目列表传输,guest 通过其工具包的保序容器读取;在各策略引擎下策略以何种顺序看到它们,见治理插槽页面。settings 以及制品已解析的 tree 以其 JSON 文档的字节传输,guest 需要查看内部时将其按 JSON 解析。不是此编码的 PolicyOutput 的答复——以 JSON 写成的,或携带该形态未声明的顶层字段的——会停止构建并指出插件及其导出,而不会被当作空 verdict 列表读取。通过 aggrega plugin run-local --export verdict_ir 或 --export verdict_render 直接调用时,guest 收到的是转换为此编码的编写好的 JSON 载荷,其答复按该导出的输出形态读取并以 JSON 打印——不符合该形态的答复会被拒绝并指出该导出,与构建拒绝它的方式相同。
类型定义。 策略线路类型发布在同样的三个 ABI 包中:PolicyInput(ir-verdict 角色)、RenderPolicyInput(render-verdict 角色)、共享的 PolicySource,以及 PolicyOutput,其 results 条目为 Diagnostic 值。诊断的严重级别是所有插槽共享的三个值之一——halt、warn 或 info——这三个值在三个包中均作为常量与线路类型一同发布,使 guest 从 host 路由所依据的同一封闭集合中报告。返回其他任何值的 guest 会停止构建,消息中指出插件及其返回的值:无法路由的严重级别是 host 报告的插件缺陷,而不是被丢弃的诊断。
输出形状契约——FeatureRecipe 流水线与 provider 插槽
下列插槽承载编译器在构建时分派的类型化契约接口。FeatureRecipe 和 Recipe 的 pipeline: 步骤在插件流水线中针对已渲染的文档集运行;provider 渲染插槽在基础渲染阶段运行;publishing-linter 在带外运行。
RFC 6902 补丁(插件流水线)
在插件流水线中运行的 FeatureRecipe 和 Recipe pipeline: 步骤针对已渲染的文档集发出 RFC 6902 JSON Patch 操作。宿主将带键的文档集整体交给每个步骤;步骤按内容选择其目标文档,并返回按键寻址的补丁,由应用引擎将其应用到所寻址的文档——通常是追加一个 sidecar 容器、挂载一个 secret 卷或改写一个环境变量。步骤还会返回 side_effects(见下文)、diagnostics(每个条目都采用所有插槽报告问题时共用的 Diagnostic 形状)以及 outputs(见下文)。说明见 examples/04-secrets.md。
当前状态: 可用。每个已声明的步骤都在 aggrega build 期间运行。
线路编码。 步骤的输入(FRPStepInput)及其应答(FRPStepOutput)在两个方向上都以规范 CBOR(RFC 8949 §4.2.1)传输。guest 通过载荷类型自带的入口点解码输入并编码应答——Go 中为 DecodeCBOR 和 EncodeCBOR,Rust 中为 decode_cbor 和 encode_cbor(位于 aggrega-abi crate 发布的类型上),TypeScript 中为 decodeCBORFRPStepInput 和 encodeCBORFRPStepOutput——读写的是字节(Rust 中为 Vec<u8>,TypeScript 中为 Host.inputBytes() 和 Host.outputBytes(...))。无需任何 CBOR 库,也无需手动解析字节。步骤的 with 输入(step_input)、它返回的 outputs,以及 own 和 host 文档集,都是 schema 标记为保序的映射,因此它们以有序的条目列表按流水线持有的顺序传输,guest 通过其工具包的保序容器读写它们——正因如此,步骤的输出才能按步骤返回的顺序到达 .steps.<id>.outputs。每个单元的 tree、step_input 和 outputs 的每个值、补丁的 value、副作用的 crd 以及渲染 context,都以其 JSON 文档的字节形式传输,guest 需将其按 JSON 解析才能查看内部;单元的 bytes 以原始字节序列传输,由生成的解码器填入工具包自身的字段类型——Go 中为字节切片,Rust 和 TypeScript 中为 base64 字符串。每条诊断都以共用的 Diagnostic 形状传输。若应答不是此编码下的 FRPStepOutput——例如以 JSON 写成,或带有该形状未声明的顶层字段——则该步骤失败,并指出它所运行的函数;除非该步骤为 optional,否则构建会因此中止。通过 aggrega plugin run-local --export step 直接调用时,步骤收到的是转换为此编码的、作者编写的 JSON 载荷,其应答按该导出的输出形状读取并以 JSON 打印——不符合该形状的应答会被拒绝并指出该导出,与构建拒绝它的方式相同。
副作用——发出资源(插件流水线中的凭据插件)
凭据 FeatureRecipe 流水线(两段式 Plugin 原则(Two-Part Plugin Principle):Fetcher + Injector)通过步骤的 side_effects 在补丁之外输出完整资源,每一项都声明契约定义的两种类型之一:emit_crd,即由集群在运行时获取的自定义资源文档,例如 ExternalSecret 或 VaultSecret CRD;或 emit_file,即一个写入的文件。返回任何其他类型的步骤会中止构建,并指出节点、副作用的索引及其声明的类型。Fetcher 的步骤输出完整资源;Injector 的步骤返回一个挂载所生成 Kubernetes Secret 的补丁。说明见 examples/04-secrets.md。
当前状态: 可用。
步骤输出(pipeline: 步骤的 outputs 映射)
插件流水线步骤发布具名输出,供后续步骤通过 {{ .steps.<id>.outputs.<key> }} 使用。输出形状由每个插件的 provider 定义;步骤输出的作用域限于同一流水线,且仅按声明顺序对后续步骤可见。文档见 templates/expansion-matrix.md 第 10 行。
当前状态: 可用。
Provider 渲染——由 guest 驱动的插槽
provider 是一个 Wasm guest。渲染仅通过 Wasm 进行:Recipe 的 capability: 名称解析到提供 provider 渲染的 Plugin(pluginType: provider),该 Plugin 在其 spec.provider.capabilities 中列出该名称并公布一个 render_node 导出,由该插件的 guest 渲染节点。宿主内没有可回退的渲染器;若某个 provider 名称没有解析到任何提供服务的 Plugin,构建会在路由时中止。添加一个标准 provider 就是发布一个 .wasm guest 和一个目录 Plugin 实体——宿主不包含任何针对特定 provider 的代码。
provider 提供的 capability 不含冒号,流水线步骤声明自身兼容的 capability 也不含冒号。 Recipe 的 capability: 被解读为:最后一个冒号之前是 capability,之后是版本固定——helm:1.0.0 请求 1.0.0 版本的 helm——因此含冒号的名称是任何 Recipe 都无法请求的。对于 provider 或 pipeline-step guest,宿主会在 guest 加载时以及为发布生成其实体时拒绝 describe() 的 capabilities 中的此类名称,并指出该 guest 和该名称。解析器的 parse:<format> 和导入器的 import:<format> 保留其冒号:它们按格式查找,从不经由 Recipe 的 capability:。
宿主是一个通用路由器。它读取 guest 的 describe() 自报信息——包括其渲染行为契约——并在不理解任何 provider 格式的情况下分派 guest 的导出。该契约以数据形式驱动分派:
input_kinds(sourced、synthesized、artifacts_standalone)——guest 渲染哪些 Recipe 输入类型;宿主依据此集合对节点的输入类型进行把关。boundary_assembly(none|merge|nest)——guest 如何组合一个分派组的输出:merge将每个节点的输出归类为片段,由组装器合并为一个制品;nest将每个节点的文件嵌套在组装好的包装之下;none直接写出每个节点的输出。nest_segment(可选)——对于nest组装,每个贡献者自身的子目录所放置于其下的目录,写作单个目录名;缺省时,每个贡献者的子目录直接位于分派位置。assembly_name_annotation(可选)——一个边界注解,其解析后的值为 guest 从分派组组装出的制品命名;缺省时,guest 仅根据分派路径为其组装结果命名。cross_boundary_linking(可选)——guest 是否通过其link_publish和link_resolve导出连接跨边界的uses边;guest 当且仅当同时导出两者时才将其声明为 true,若标志与导出不一致,加载会拒绝该 guest。artifact_delimiters(可选)——guest 应用于制品正文的 Go 模板分隔符对。reusable_instance(可选)——一个已加载的实例是否可以服务构建中的每一次跨越(见下文确定性与实例复用)。omits(可选)——guest 是否遵从源渲染所带的省略条目(见下文省略已渲染的单元)。boundary_artifacts(可选)——guest 的目标是否接受 Recipe 向其边界共享输出贡献的文件(见下文接受 Recipe 向边界贡献的文件)。source_ignore(可选)——guest 的生态系统从不随其渲染的源一起发布的文件(见下文声明源的生态系统从不发布的内容)。
该插槽是一组固定的导出——一个必需,其余可选,并在 describe() 中公布:
render_node(必需)——将一个 IR 节点渲染为 provider 原生文件。assemble_boundary(可选)——将分派组中每个节点的输出合并为每个路径一个制品(当boundary_assembly为merge或nest时存在)。validate_node_input(可选)——在渲染前对节点输入进行结构校验;halt诊断会中止构建,warn会呈现在构建结果中。carve/reassemble(可选,成对)——guest 自有的、逐字节保真的补丁编解码器,用于渲染后的流水线步骤,仅当两者都已公布时才使用。name_bound(可选)——由 guest 判断宿主提议作为组件标识的名称是否能产生其目标所接受的名称,并以一个约束作答,而不是给出它自己的名称。rendered_name(可选)——由 guest 报告其目标为它针对某个节点渲染的资源所赋予的名称。link_publish/link_resolve(可选,成对)——由 guest 连接一条跨边界的uses边:被消费的端点发布一个句柄,消费端点将其解析到自己的组装输出中。
Recipe 的 artifacts: 通过输入上的 artifacts 投影并入 render_node:宿主负责 $import 读取、Go 模板求值以及来源键/值的计算,并将每个已读取并求值的条目交给 guest;guest 负责以只有它了解的格式进行放置和输出。详见 architecture/13-catalog-and-registry.md。
源渲染的输入在 node.values 上携带节点的值,而 node.values_mapped 说明这些值的来源:当这些值是 Recipe 的 valuesMapping 的输出时(或者,对于附加项自身的渲染,是其 FeatureRecipe 的输出时),它为 true;当这些值是组件自身按原样传递的值时,它不存在。guest 是否读取它,是该 guest 自己的契约。cloudformation 提供程序仅从映射产生的值中绑定源模板的 Parameters,因为组件自身的值可能是为该 Recipe 的其他输入编写的;terraform 提供程序则根据其装配收到的值写入源模块的参数,并不读取该标志。对于从源渲染的节点,这些值会随 assemble_boundary 输入中的每个已渲染节点一起传递:组件的值无论是否由映射产生都会传递,附加的 Feature 的值仅在由其 FeatureRecipe 的 valuesMapping 产生时才传递;同一标志伴随这些值传递,且仅在这些值传递之处传递,因此装配器读到的答案与节点自身渲染读到的相同。cloudformation 提供程序在那里读取该标志,以了解节点的绑定填充了哪些参数,并拒绝堆栈中任何其他位置(包括附加 Feature 的宿主)对其中某个参数的引用。该标志记录值是如何产生的,绝不会从某个键或值推导而来。
传输编码。 该插槽的每个导出都以 canonical CBOR(RFC 8949 §4.2.1)接收输入并返回输出,双向皆然。guest 通过载荷类型已提供的入口点解码输入并编码输出——Go 中为 DecodeCBOR 和 EncodeCBOR,Rust 中为 decode_cbor 和 encode_cbor,TypeScript 中为每个类型的 decodeCBOR 和 encodeCBOR 函数,例如 decodeCBORRenderNodeInput 和 encodeCBORRenderNodeOutput——读写的是字节(Rust 中为 Vec<u8>,TypeScript 中为 Host.inputBytes() 和 Host.outputBytes(...))。无需任何 CBOR 库,也无需手工解析字节。已渲染文件的 content 以及其他所有字节字段,都以原始字节序列传输,由生成的解码器填入工具包自身的字段类型:Go 中为字节切片,Rust 和 TypeScript 中为 base64 字符串。schema 标记为保序的映射——其中包括节点的 values、features 和 uses,应答的 derived_keys,以及组装贡献者的 values——按构建持有它们的顺序以有序条目列表传输,guest 通过其工具包的保序容器读取它们。节点 values 的每个值都以其自身 JSON 文档的字节传输,因此值内部的键保持其编写时的顺序;features 的每个附件条目、渲染上下文、解析后的 workload、每条增强边、每个切分单元和每个补丁操作也是如此,guest 将它们作为 JSON 解析以查看内容。每条诊断都以共享的 Diagnostic 形状传输。若应答不是该导出在此编码下的输出形状——例如以 JSON 编写,或带有该形状未声明的顶层字段——则会中止构建,并指明所调用的导出。本页中的载荷示例为便于阅读以 JSON 编写。使用 aggrega plugin run-local --export render_node 或该插槽的任何其他导出直接调用时,guest 会收到转换为此编码的编写好的 JSON 载荷,其应答按该导出的输出形状读取并以 JSON 打印——不符合该形状的应答会被拒绝,并指明该导出,与构建拒绝它的方式相同。
当前状态: 所有五个 provider 均可用。helm guest 将来源 chart(解析 chart 根目录)、合成的 workload 和独立工件渲染为扁平的 Kubernetes 清单。helm-chart guest 组装一个伞形 chart,将每个节点的来源 chart 嵌套为子 chart,并带有字节保真的补丁编解码器和方括号([[ ]])工件分隔符。compose guest 渲染来源 compose 文件和合成的 workload,将一个分发组合并为一个 docker-compose.yaml,并将服务接入其 x-aggrega-networks-of 所指定组件的网络。terraform guest 原样输出 Terraform 配置(HCL 或 JSON),或引入来源模块并将其输入作为该组件的模块块参数提供,在渲染前对来源模块的 HCL 做结构校验,并将一个边界组合为一个根配置,将每个组件声明为引用该组件自身子目录的模块块。cloudformation guest 渲染来源模板和独立的堆栈片段,将一个分发组合并为一个堆栈模板,并通过 link_publish 和 link_resolve 连接跨边界的 uses 边。每个 guest 都离线且确定性地渲染。
声明 guest 派生的名称
provider guest 通常会根据节点标识及其正在输出的资源,派生出其输出所需但无人编写的名称——目标用来定位某个资源的标识符,某个输出为供另一方引用而发布时所用的名称。只要两个节点派生名称所依据的各部分一致,它们就可能得到同一个名称;而由于该名称位于 host 原样写入的文件字节之中,host 无法发现这一冲突:它必须解析 provider 的格式才能找到冲突,而这恰恰是留在 guest 中的知识。
因此,render_node 在其输出中返回一个可选的 derived_keys,方向随之反转——不是由 host 检查输出,而是由 guest 声明、host 校验:
{ "files": [ { "path": "stack.yaml", "content": "..." } ], "derived_keys": { "logical-ids": ["paymentsapiQueue", "paymentsapiTopic"], "export-names": ["aggrega--prod--api--orders-db--host"] }}derived_keys 的每个键是 guest 命名的一个键空间,每个空间按派生顺序列出 guest 派生到其中的名称。空间名称及其中的名称都属于你的词汇:host 只把它们当作字符串,在同一空间内比较是否相等。它不解析名称,不了解空间或名称的含义,也从不自行派生名称——因此一次检查即可覆盖每个 provider 派生的每种名称,新的 provider 也无需新增 host 代码。在已发布的类型中,derived_keys 是一个保持顺序的映射,因此各空间按你的 guest 设置它们的顺序传递。
host 对它们所做的只是回答一个问题:在同一空间内,输出合并到同一装配中的各贡献者所声明的每个名称是否互不相同?两个贡献者在同一空间中声明同一名称会使构建中止,中止信息会指出该空间、该名称以及这两个贡献者,因此作者无需阅读 provider 即可采取行动。互不相同的名称,以及恰好在两个不同空间中相同的名称,均可通过。
在决定声明哪些内容时,值得了解以下三个特性:
- 范围是一个装配输出——即文件合并在一起的贡献者集合。若 guest 需要在比这更窄或更宽的范围内保证唯一性,可在其声明的空间名称中表达该范围,从而由你而不是 host 来做这一选择。
- 同一贡献者可以自由重复某个名称。 一个节点可以跨多次调用进行渲染——一次源渲染、一次 workload 合成、一次 artifacts 放置——这些声明会合并。同一贡献者两次声明同一名称,是该贡献者对同一资源的两次描述,而不是冲突。
- 声明不改变任何字节。 该字段是对 guest 所派生内容的断言,从不改变其输出内容,因此无论 guest 是否声明,其渲染输出都完全相同。省略
derived_keys是合法的,对该 guest 而言检查不起作用。
报告 guest 所输出内容的事实
关于节点渲染的某些信息只有生成它的 provider 才能看到——它所写文档包含什么、定义了哪些名称、某种东西输出了多少个——因为要从文件字节中读出这些信息,就必须理解 provider 的格式。render_node 可以自行报告这类信息,放在其文件旁边的可选 render_facts 列表中:
{ "files": [ { "path": "stack.yaml", "content": "..." } ], "render_facts": [ { "name": "exported_outputs", "value": ["QueueUrl", "TopicArn"] }, { "name": "stacks", "value": [ { "name": "payments-api", "resources": 2 } ] } ]}每个事实由一个 name 和一个 value 组成,两者都归你的 provider 所有:报告哪些事实、每个名称的含义以及每个条目包含什么,都是你的 provider 自身已记录契约的一部分,因此请为将要读取它们的作者编写文档。
将每个事实的值报告为列表——一个 JSON 数组——即使它只包含一个条目。 同一名称可能由一个组件的多次渲染报告:组件自身的渲染可能包含多次调用——例如一次 chart 渲染和一次 artifacts 放置——而附加到该组件的每个 Feature 都通过各自的 provider 调用进行渲染。任何 provider 在渲染时都无法知道自己的报告是否会是某个名称下唯一的一份,因此每份报告都是列表,编译器会把同一名称得到的各个列表合并成一个列表。值为其他任何类型——对象、字符串、数字、布尔值、null——的事实,在你的 guest 返回时即被拒绝:构建以简短代码 E0325 中止,指出该事实、该节点和你的 guest,并说明该值是什么。列表中的条目可以是符合你所记录形状的任意 JSON 值。
值是列表,这是编译器对它所了解的唯一一点。编译器按名称为事实建立索引,并把每个列表交给读取它的模板——宿主组件的事实交给附加到它的每个 Feature,每个调用方的事实交给声明读取其调用方渲染事实的 Feature,每个目标的事实交给声明读取其宿主所连接组件的渲染事实的 Feature,如模板上下文所述——并将每个列表解码为模板可以遍历的值。它从不了解名称或条目的含义,也从不自行派生事实,因此新的 provider 可以报告新的事实,而编译器一侧无需任何改动。附加到节点的 Feature 从其自身渲染中报告的事实,与节点自身渲染所报告的事实分开保存。
在决定报告哪些内容时,值得了解以下四个特性:
- 顺序由你决定。 事实保持你的 guest 列出它们的顺序,每个值保持其自身字节——列表条目的顺序以及每个对象键的顺序,就是你的 guest 写入的顺序。请以固定顺序列出事实,并以固定的键顺序写入每个条目,使相同的输入产生相同的字节;之所以使用事实列表而非映射,正是为了让顺序在每个工具包自身的序列类型中无需任何标记即可保留,而映射只有在其 schema 将其标记为保持顺序、且 guest 填充其工具包的保持顺序的容器时,才会保留 guest 写入的顺序。
- 报告不改变任何字节。 编译器写入的文件就是你的 guest 返回的文件,无论是否附带事实。
- 一个节点可以跨多次调用进行报告。 一个节点可以以源渲染、workload 合成和 artifacts 放置的方式进行渲染;每次调用报告的事实按调用运行的顺序保存,由其中多次调用报告的同一名称,读取时是按该顺序合并它们的一个列表。
- 不报告任何内容也是完整的。 省略
render_facts是合法的,不报告任何内容的 provider 的渲染结果与没有该字段时完全相同。
RenderFact 类型发布在三个 ABI 包中,并由每种语言的插件开发工具包重新导出,这些工具包的渲染示例会在其文件旁报告两个事实。在 Go 中,值就是你的 guest 写入的 JSON;序列化结构体切片而不是映射切片,才能让每个条目的键保持你声明它们的顺序:
type stackFact struct { Name string `json:"name"` Resources int `json:"resources"`}
stacks, err := json.Marshal([]stackFact{{Name: "payments-api", Resources: 2}})if err != nil { pdk.SetError(err) return 1}out := aggrega.RenderNodeOutput{ Files: files, RenderFacts: []aggrega.RenderFact{{Name: "stacks", Value: stacks}},}排除已渲染的单元
源渲染可以指定 provider 必须从其渲染结果中排除的单元,例如获取的 chart 每次渲染都会重新生成的 Secret。某个条目指的是哪个已渲染单元,只有你的 provider 知道,因此这些条目会传给你的 guest,由 guest 负责排除。它们作为 render_node 输入中的可选 omits 列表,与 source_listing 并列传入:
{ "node": { "id": "payments-api" }, "context": { }, "source_listing": { "root": "/acquired/payments-chart", "root_is_dir": true, "entries": [] }, "omits": [ { "kind": "Secret", "name": "payments-api-token", "namespace": "payments" }, { "kind": "ConfigMap", "name": "payments-api-dashboards" } ]}每个条目由 kind、name 和可选的 namespace 组成,已解析为纯字符串,并按作者声明的顺序排列;不适用于本次构建的条目不会传入。这三个字段选中的内容属于你的 provider 自己的契约,即你的目标格式中资源的 kind、name 和 namespace,因此请为编写这些条目的作者记录下来。
作者可以用其声明为敏感的值构建条目的字段,例如以某个敏感设置命名的资源。此类条目会带有 "sensitive": true,你的 guest 应像对待渲染输入中其他所有已标记的值一样对待它(参见输入标记为敏感的值):仍按其字段匹配和计数该条目(这正是条目的用途),同时不让其任何字段出现在拒绝信息、警告或日志行中。该标记覆盖整个条目,因为编译器不会指出是哪个字段由该值生成。没有任何字段由此类值构建时,该标记不存在。
遵循这些条目的 guest 要做三件事:
- 用你的格式的术语,将每个条目与其渲染结果进行匹配。
- 从返回的所有内容中排除每个匹配的单元,包括其
files、在derived_keys中声明的名称以及在render_facts中报告的事实,使编译器收到的内容中不再有任何东西描述它。 - 为每个条目报告一个计数,放在输出中可选的
omitted列表里,顺序与条目传入的顺序一致,每个计数是该条目匹配的单元数,无论其他条目是否也匹配了这些单元,都要计入:
{ "files": [ { "path": "templates/deployment.yaml", "content": "..." } ], "omitted": [1, 0]}零是一个完整的回答:该条目没有匹配到你的 guest 渲染的任何内容。关于被排除内容,回传的只有这些计数;被排除的单元本身只是不出现在 guest 返回的内容中。
完成以上三件事的 provider 在其契约中以 omits: true 声明这一点。Plugin 实体以 spec.provider.contract.omits 记录相同的声明;若该实体带有渲染行为契约,加载时会拒绝 describe() 报告不同值的 guest。这些条目只随源列表一同传入:合成的 workload 或制品集的渲染永远不会携带它们。
**不携带条目的渲染不受这两个字段影响。**这两个字段都是可选的,为空时不存在,因此不携带条目的渲染在穿过 socket 时与这两个字段不存在时逐字节相同,从不读取它们的 guest 也不受其影响。OmitEntry 类型已在三个 ABI 包中发布,并由每种语言的插件开发工具包重新导出。
**编译器如何处理你的回答。**这些条目来自作者在 Recipe 或 FeatureRecipe 上编写的 omits: 键(Recipe → omits: 字段);编译器对每个条目的模板求值,并将适用的条目交给你的 guest。然后它读取你的计数,且只读取计数,从不查看返回的文件来核对:
- 如果计数列表不是为所交出的每个条目各提供一个非负计数,构建会中止,包括缺失、过短、过长或包含小于零的计数,中止信息会指明节点、你的 provider、交出了多少条目以及返回了多少计数。无法对齐的报告无从判断哪个条目排除了什么。参见 A provider’s omitted counts do not match the omits entries it was handed(provider 的 omitted 计数与其收到的 omits 条目不匹配)。
- 零会中止构建,中止信息指明按作者顺序第一个计数为零的条目:节点、你的 provider、该条目在其文档所声明列表中的位置,以及它解析得到的 kind、name 和 namespace。零由你的 guest 报告;中止由编译器执行。参见 An omits entry left out nothing the source rendered(omits 条目未排除源渲染的任何内容)。
- 声明了
omits:但其 provider 未声明omits: true的文档,会在任何渲染开始之前被拒绝,这样作者能立即得知该键不会生效,而不是在输出中发现该文档。编译器在构建中的每个 Recipe 和 FeatureRecipe 都绑定后,从你的describe()读取你的声明,并在第一个 component 渲染之前拒绝,因此未声明该键的 guest 永远不会收到条目。拒绝信息会指明 provider 以及该文档为之渲染的 component;对于为某个边界生成一次的 FeatureRecipe,则指明该边界和挂载点。参见 The provider does not support omits(provider 不支持 omits)。
当前状态: 可用。随编译器分发的 helm、compose 和 cloudformation guest 声明了该能力并遵循这些条目。helm guest 不会将任何条目的任何字段写入其返回的文本。compose 和 cloudformation guest 在拒绝某个条目时会指明该条目的 kind、name 和 namespace,在拒绝仍引用被排除单元的文件或模板时会指明这些单元,并在这些地方将已标记条目的每个字段显示为 <redacted>。helm-chart 和 terraform guest 未声明该能力,因此由它们渲染且声明了 omits: 的文档会被拒绝。
接收 Recipe 为边界贡献的文件
有些文件属于整个边界,而非其中某个 component,例如目标为该边界部署的所有内容只读取一次的 provider 配置。Recipe 将这些文件写在 spec.boundary.artifacts 下,由编译器而非你的 guest 完成工作:它按 artifacts: 条目求值所用的上下文对每个文件求值,按名称合并分派组中每个贡献者声明的文件,并将每个文件在存放该组组装输出的目录中写入一次,与你的 assemble_boundary 返回的内容并列。你的 guest 在任何导出上都不会收到这些文件,也从不会被询问,因此无需实现任何东西,只需就你的目标做出一项声明:
"contract": { "input_kinds": { "sourced": true, "artifacts_standalone": true }, "boundary_assembly": "nest", "boundary_artifacts": true}仅当你的目标会将放在该目录中的文件作为边界输出的一部分读取时,才声明 boundary_artifacts: true。Plugin 实体以 spec.provider.contract.boundaryArtifacts 记录相同的声明;若该实体带有渲染行为契约,加载时会拒绝 describe() 报告不同值的 guest。声明了该块但其 provider 未声明此能力的 Recipe 会在任何渲染开始之前被拒绝,并指明 provider 和 component;参见 The provider does not support boundary artifacts(provider 不支持边界制品)。如果这些合并放置的某个文件所用名称与你的组装也写入的名称相同,构建会作为 two contributors writing one output path(两个贡献者写入同一输出路径) 而停止,因此你的组装所写入的名称是你需要为作者记录的内容之一。
当前状态: 可用。随编译器分发的 terraform guest 声明了该能力,Terraform 会读取边界根配置旁的每个文件;helm、compose、helm-chart 和 cloudformation guest 未声明该能力。
声明源的生态系统从不发布的内容
Recipe 的本地源目录(一个同处一地的 chart、一个模块)随 Recipe 一起发布,但其中并非每个文件都属于它。provider guest 通过其契约上的 source_ignore 声明自身生态系统从不发布的内容,以 .gitignore 所用语法编写的忽略规则表示:
"contract": { "input_kinds": { "sourced": true, "synthesized": false, "artifacts_standalone": false }, "boundary_assembly": "none", "source_ignore": { "patterns": [".git/", ".hg/", ".svn/", ".bzr/", "templates/.?*"], "files": [".helmignore"] }}patterns是从源目录根部读取的规则,按顺序应用,后出现的匹配覆盖先出现的匹配。files指定你的生态系统在源内部遵循的忽略文件。遍历源时每遇到一个这样的文件,就将其各行作为其所在目录的附加规则读取,位于你的 patterns 之后。
**该声明在实体被固定(pin)时读取,而不是在渲染时读取。**作者的 pin 步骤在其工作区中解析为该实体的能力提供服务的插件,将你的规则与作者自己的 .aggregaignore 组合(其各行排在最后,因此在它们指定的任何路径上胜出),并将你的插件名称(不含版本)连同组合后的确切规则,记录在该实体的 entity.lock 中。此后对该实体的每次发布、比较和渲染都应用所记录的规则;宿主负责匹配这些规则,自身对任何生态系统不持任何看法。因此,渲染时交给你的 guest 的文件(清单,以及它请求宿主打包或读取的每个文件)正是该实体的一次发布所携带的文件;规则排除的文件会被答复为不存在,并指明该文件。源下的符号链接会在调用你的 guest 之前被拒绝。
**兼容性由所记录的内容决定。**当 guest 使用相同的 ABI 版本、其契约与其实体的声明一致,并且不需要已发布集合之外的文件时,它就能渲染为其能力发布的 Recipe。需要被该集合排除的文件的 guest 必须明确地使其构建失败并指明该文件:宿主对打包或读取的拒绝会指明该文件,guest 将其带入自身的失败中。当使用方工作区为某能力绑定的插件所声明的规则与实体的 lock 所记录的规则不同时,使用方的 pull 会打印一条警告,指明两个插件及其差异;它从不因此中止。
省略 source_ignore 即不声明任何规则,此时你渲染的源保留作者自身规则所保留的每个文件。该字段是可选的,不需要单独的 ABI 版本:省略它的 guest 按不声明任何内容的方式加载。Plugin 实体以 spec.provider.contract.sourceIgnore 记录相同的声明;记录了时,若 guest 的 describe() 报告的内容不同,加载会拒绝该 guest。
确定性与实例复用
宿主原样使用 guest 的输出字节,因此 guest 必须对相同的输入产生相同的输出。默认情况下,guest 为每个节点重新加载——从构造上保证节点之间不携带任何状态。自行声明 reusable_instance 的 guest 则在每次构建中只加载一次,由其单个实例处理每次跨越,从而省去占主导地位的逐节点实例化开销。由于复用仅对无状态 guest 安全,aggrega build --verify-determinism 会通过同一实例将每个节点渲染两次,若任一节点的两次渲染结果不同则中止构建;默认构建只渲染一次并信任该声明。Wasm 编译缓存基于磁盘且在进程范围内共享,因此 guest 只编译一次,热构建会跳过重新编译。
linter 插槽——发布 linter
linter 插槽以标准的 publishing-linter 形式发布,它是一个带外关卡,通过 aggrega lint 运行,而不是在编译时运行。它接收一个目录实体(在 --pre-publish 模式下还接收该实体当前已发布的版本),返回一组发现项,每项带有严重级别和消息;在 --pre-publish 模式下它还返回版本升级分类。宿主通过内嵌的 Wasm 运行时分派它,与其他所有插槽一样处于同一 AOT 纯度防火墙之后。完整的规则集、严重级别和逐规则退出选项记录在 cli/aggrega-lint.md 中。
linter 是需主动启用的目录规范:编译器在 aggrega build 期间不运行它(唯一的例外是 x-aggrega-* 不建议使用提示,它在构建期间以 warn 严重级别出现,在 aggrega lint --pre-publish 下以 halt 严重级别出现)。由于规则存在于插件中,企业可以让 aggrega lint 指向另一个 linter 插件,以执行自己的规范。
在 aggrega lint 运行的任何范围内,都没有参数值会到达 linter 插件。在交出任何文档之前,宿主会扣留 Aggregate 的参数默认值、它传给所导入的每个模块的值,以及 Release 的参数,只保留每个参数声明的契约(即声明在其嵌套的每一层所写的键)以及任何读取参数的模板文本:参数的值本身可能就是凭据,而挂接在此处的插件可能是并非该工作区编写的代码。每个文档携带的内容详见交给 linter 插件的内容。
**传输编码。**输入和输出都以 canonical CBOR(RFC 8949 §4.2.1)传输。guest 通过其 kit 的 LinterInput 和 LinterOutput 已经提供的入口点解码输入、编码输出——Go 中为 DecodeCBOR 和 EncodeCBOR,Rust 中为 decode_cbor 和 encode_cbor,TypeScript 中为 decodeCBORLinterInput 和 encodeCBORLinterOutput——读写的是字节(Rust 中为 Vec<u8>,TypeScript 中为 Host.inputBytes() 和 Host.outputBytes(...))。无需 CBOR 库,也无需手工解析字节。实体文档(proposed、previous、implemented_component 和 release)以及 components 的每个值都以其 JSON 文档的字节形式跨越,因此 guest 需将其按 JSON 解析才能查看内部。components 是 schema 标记为保持顺序的映射,因此在读取整个 Release 的规则的输入中,它以有序条目列表的形式跨越,顺序为 Aggregate 声明其组件实例的顺序,guest 通过其 kit 的保序容器读取它。policies 以只包含已设置标志的映射形式跨越,因此它未携带的标志读作 false;每个发现项以共享的 Diagnostic 形状跨越。不是此编码下的 LinterOutput 的答复(以 JSON 写成的,或携带该形状未声明的顶层字段的)会使 lint 失败,并指明所调用的导出,而不会被视为一次没有发现任何问题的运行。使用 aggrega plugin run-local --export lint_rules 直接调用时,linter 收到的是转换为此编码的、作者编写的 JSON 负载,其答复按该导出的输出形状读取并以 JSON 打印——不符合该形状的答复会被拒绝,并指明该导出,与构建拒绝它的方式相同。
**当前状态:**可用。publishing-linter 已发布,并通过 aggrega lint 经由宿主运行。
parser 插槽——规范树输出
parser 将以编译器不原生读取的格式编写的源转换为规范的结构化树,使使用方读取该树,而无需自带解析器。host 解析以 parse:<format> 声明所请求格式的 parser,并在三处调用其 parse 导出:当渲染裁决策略收到一个其不原生读取格式的已渲染制品时,当 importer 通过 aggrega_parse_source 向 host 请求树时,以及当识别一个未指定格式的导入时(参见下文的 importer 插槽)。guest 从不自行调用 parser。
输入结构(host → guest)。 一个 ParseInput 文档,包含:
format——所请求的格式,即 parser 的某个parse:<format>能力去掉前缀后的部分。bytes——源字节。options——使用方为 parser 特定行为提供的选项文档,原样传递。使用方未提供时不存在。
输出结构(guest → host)。 一个 ParseOutput 文档,包含 tree(以 JSON 文档表示的已解析源,其顶层可以是对象、数组或标量)、采用共享 Diagnostic 结构的任何诊断、在原始字节中定位树节点的可选源区间,以及解析无法完成时的失败 error。每个字段及其约束见生成的 parser 插槽 schema 参考。
传输编码。 输入和输出都以规范 CBOR(RFC 8949 §4.2.1)传输,这也是 guest 将同一 ParseInput 交给 aggrega_parse_source 时所用的编码。guest 通过其 kit 的 ParseInput 和 ParseOutput 已带有的入口点解码输入、编码输出——Go 中为 DecodeCBOR 和 EncodeCBOR,Rust 中为 decode_cbor 和 encode_cbor,TypeScript 中为 decodeCBORParseInput 和 encodeCBORParseOutput——读写的是字节(Rust 中为 Vec<u8>,TypeScript 中为 Host.inputBytes() 和 Host.outputBytes(...))。无需任何 CBOR 库,也无需手工解析字节。源字节以原始字节序列传输,生成的解码器将其填入 kit 自身的字段类型:Go 中为字节切片,Rust 和 TypeScript 中为 base64 字符串。options 和 tree 以其 JSON 文档的字节传输,因此 parser 写出的树原样到达使用方。无法完成的 parser 在输出的 error 中说明原因,解析随之失败,并指明该 parser 和该消息;不是此编码下的 ParseOutput 的应答——以 JSON 写出的,或带有该结构未声明的顶层字段的——同样使解析失败,并指明该 parser 及其 parse 导出。解析失败会在渲染裁决角色处终止构建,并作为 aggrega_parse_source 返回的失败到达 importer。parser 拒绝的源也是如此——即 parser 在其树旁附带 halt 诊断作答的源:importer 的调用以每个此类诊断的消息失败,按 parser 的顺序排列,且永远不会收到该树。通过 aggrega plugin run-local --export parse 直接调用时,parser 收到的是转换为此编码的所编写 JSON 载荷——载荷中的源以 base64 书写,与 JSON 书写任何字节字段的方式相同——其应答按该导出的输出形状读取并以 JSON 打印——不符合该形状的应答会被拒绝,并指明该导出,与构建拒绝它的方式相同。
类型定义。 parser 传输类型——ParseInput、ParseOutput、NodeSpan 和 SourceSpan——发布在全部三个 ABI 包中,并由每种语言的插件开发工具包重新导出,它们由同一个编解码器生成,因此三者保持同步。每个 kit 的 parse 示例都以这种方式读取输入、写出输出,随二进制文件一同提供的 HCL、TOML、YAML、JSON 及带注释 JSON 的 parser 也是如此。
当前状态: 可用——在渲染裁决角色处针对策略不原生读取格式的制品进行分派,通过 aggrega_parse_source 为 importer 分派,并用于识别未指定格式的导入的格式。
导入器插槽——草稿编写输出
导入器把为其他工具编写的源(例如从智能体构建器导出的流程)转换为 Aggrega 编写文件的草稿。它在带外运行:aggrega import、编辑器会话的 aggrega/import 方法以及面向助手的 import 工具会解析以 import:<format> 声明所请求格式的导入器,并在每次导入时调用一次其 import 导出。构建从不调度它。运行哪个导入器、操作者交给它什么,参见哪个导入器把源转换为草稿。编译器自带的导入器(它读取的每种格式各一个)在核心导入器中介绍:包括有哪些格式、每个导入器读取什么、起草什么、接受哪些设置、它们随每个编译器版本的发布方式,以及导入如何获取并验证本机尚未持有的导入器。
输入结构(宿主 → 客体)。 一个 ImportInput 文档,包含:
format——导入所请求的格式,即导入器某个import:<format>能力去掉前缀后的部分。bytes——源字节:导入文件时为整个文件;导入目录时为空,目录中的文件通过sources传入。name—— 源的名称,前面不带目录,以便 importer 在其报告的内容和起草的内容中指明该源:导入文件时,为读取bytes所用文件的基本名称;导入目录时,为目录自身的基本名称,从其完整路径中读取,因此aggrega import .传入的是其运行所在目录的名称,而目录中的每个文件仍以其自身名称传入。源没有可提供的名称时不存在。sources——具名源,每项携带其名称和字节,放在按名称排序的一个列表中:导入目录时,包括该目录中被导入器声明的文件模式选中的每个文件(工作区的构建输出文件夹除外),以其在目录内用斜杠分隔的路径命名;以及挂载该导入器的plugins.importer条目在with.sources下声明的文件,各以其基本名命名。目录文件与with.sources文件同名时,导入会被拒绝,而不是让一个遮蔽另一个。没有源时不出现。settings——该条目在with.settings下声明的设置对象,作为键已排序的 JSON 文档原样传入。没有条目挂载该导入器或条目未声明设置时不出现。catalog——工作区自身目录所持有 Components 的视图:即导入器本身被选出的那个目录(工作区的目录文件夹;工作区未指定任何目录文件夹时,则为其默认注册表发布并保存在本机上的目录快照),不为视图本身获取任何内容。其components列表按 Component 名称每个名称一项,按名称排序;目录持有某个 Component 的多个版本时,该项描述不带版本引用它时所解析到的版本。每项携带该 Component 的name和version、其labels、其 values 和 provides 声明的顶层键名(values和provides,各自排序),以及其sockets——每个插槽的name和经由它连接的依赖必须满足的标签selector——顺序与该 Component 声明的顺序一致。扩展另一个 Component 的 Component 既携带其声明的内容,也携带其继承的内容,继承的插槽排在前面。该视图只包含名称、版本、标签和选择器——从不包含值、默认值或机密——且顺序固定,因此一个目录产生唯一的字节序列。目录不持有任何 Component 时不出现。
输出结构(客体 → 宿主)。 一个 ImportOutput 文档,携带导入产生的实体(每个都是对现有目录实体的引用或一个起草的主体)、其背后的映射决策、采用共享 Diagnostic 结构的诊断、要写入的脚手架文件,以及导入无法完成时的失败 error。每个字段及其约束见生成的导入器插槽 schema 参考。
线路编码。 输入和输出都以规范 CBOR(RFC 8949 §4.2.1)传输。客体通过其工具包的 ImportInput 和 ImportOutput 已带有的入口点解码输入、编码输出——Go 中为 DecodeCBOR 和 EncodeCBOR,Rust 中为 decode_cbor 和 encode_cbor,TypeScript 中为 decodeCBORImportInput 和 encodeCBORImportOutput——读写字节(Rust 中为 Vec<u8>,TypeScript 中为 Host.inputBytes() 和 Host.outputBytes(...))。无需 CBOR 库,也无需手工解析字节。settings 在二进制文档中以其 JSON 文档的字节传递,因此客体要查看其内容需按 JSON 解析,与其他所有插槽相同。无法完成的导入器在输出的 error 中说明原因,导入随之中止,并给出导入器名称和该消息;不是此编码下 ImportOutput 的回答——以 JSON 写成的,或携带该结构未声明的顶层字段的——同样会中止导入,并给出导入器及其 import 导出的名称。通过 aggrega plugin run-local --export import 直接调用时,导入器收到的是转换为此编码的编写 JSON 载荷,其回答按该导出的输出形状读取并以 JSON 打印——不符合该形状的回答会被拒绝,并给出该导出的名称,与构建拒绝它的方式相同。
如何识别你的格式的源。 导入可以不指定格式,此时宿主根据导入器的声明来识别格式,自身不了解任何格式。导入器在其 describe() 自述中,于 importer(一个 ImporterContract)下声明一个 detect 列表,列出识别其格式之源的签名。每个 DetectSignature 指定:
syntax——解析源所用的语法格式,即某个解析器插件以parse:<syntax>声明的格式,例如json或yaml;files——可选的文件名模式,与源名称的末尾匹配:单段模式与文件自身的名称匹配,多个以斜杠分隔的段与其路径末尾相同数量的段匹配,*、?和[...]在段内匹配。未声明模式的签名适用于单个文件的源(无论其名称为何),不适用于目录中的任何文件;match——解析树必须全部满足的谓词,每个是一个PathMatch,包含一个从树顶起以点连接各键的path(整数段选择数组位置)、一个取值为present、absent、object、array、string、number或boolean的is,以及可选的equals字符串或prefix字符串——两者至多其一。
导入未指定格式时,宿主按身份和版本顺序,匹配该导入可选择的每个导入器——工作区目录中的导入器以及编译器的核心导入器——的签名:对每种语法至多解析一次源,使用目录为该语法提供的解析器,若目录未提供该语法的解析器,则使用编译器自带的解析器;然后在树上求值谓词,并将源读作唯一签名匹配的那个导入器的格式。导入器的 aggrega_parse_source 调用也通过同一个解析器应答,因此导入器通过识别它时所用的解析器读取其源。无法按某种语法解析的源不匹配任何指定该语法的签名;目录和编译器都未提供解析器的语法会终止识别,并指明缺少该解析器。没有签名匹配的源会被拒绝并要求指定格式,被识别为多种格式的源会被拒绝并列出这些格式。签名会把源识别为其导入器声明的每一种格式,因此需要被识别源的导入器只提供一种格式,未声明签名的导入器只能通过指定其格式来使用。
导入器的 Plugin 实体以 spec.importer.detect 记录同一列表;当实体由 guest 生成时,该列表派生自 describe()。识别读取的是这条记录,因此在格式确定之前不会加载 guest。加载和发布 guest 时,若其自报告与实体的记录不同,会被拒绝并指出 importer.detect;未记录任何签名的实体不作任何声明。以下情况下描述符会在加载时被拒绝:该契约声明在一个不是导入器的插件上;某个签名未指定语法或包含格式错误的文件模式;某个谓词未指定路径、is 不属于那七种取值,或同时指定了 equals 和 prefix。
编译器的核心导入器和 Go kit 的 import 示例都以这种方式声明各自的签名。Langflow 导入器将源读作 JSON,并要求 data.nodes 处为数组;Flowise 导入器要求 nodes 和 edges 处为数组,且 data.nodes 处不存在任何内容;n8n 导入器要求 nodes 处为数组、connections 处为对象,且 edges 和 data.nodes 处不存在任何内容;MCP 导入器为每种客户端配置声明一个签名并指定其文件——.mcp.json、claude_desktop_config.json 和 .cursor/mcp.json 读作 JSON,要求 mcpServers 处为对象;.vscode/mcp.json 按 Visual Studio Code 的读取方式读作带注释的 JSON,要求 servers 处为对象——另有一个不指定文件的签名,要求 $schema 字符串以 https://static.modelcontextprotocol.io/schemas/ 开头;Compose 导入器将源读作 YAML,指定 Compose 默认读取的文件——compose.yaml、compose.yml、docker-compose.yml、docker-compose.yaml 及其四个覆盖文件——并要求 services 处为对象;Dify 导入器将源读作 YAML,不指定文件,要求 kind 处为字符串 app,且 app.mode 和 version 处存在内容;CrewAI 导入器指定 config/agents.yaml 和 config/tasks.yaml,读作 YAML 且对树没有任何要求,指定 crew.jsonc 和 crew.json,读作带注释的 JSON 且要求 agents 处为列表,并指定 agents/*.jsonc 和 agents/*.json,读作带注释的 JSON 且要求 role 处存在内容,因此其中任意两个都不会匹配同一个源,而单独导入且未指定格式的文件既会被读作 YAML,也会被读作 JSON;LangGraph 导入器指定 langgraph.json,读作 JSON 且要求 graphs 处为对象,声明一个不指定文件的签名,要求 graphs 处为对象且 $schema 处为字符串 https://langgra.ph/schema.json,并且不指定任何环境文件,因为识别会读取任一导入器的模式所选中的每个文件,若某个模式指定了环境文件,就会打开每个未指定格式导入的目录中的环境文件;Google ADK 导入器指定 root_agent.yaml,读作 YAML,要求 name 和 instruction 处存在内容,或 agent_class 处为字符串且 name 处存在内容,并且不指定其他文件,因为子代理的配置可以任意命名,而指定所有 YAML 文件的模式会打开每个未指定格式导入的目录中的每一个 YAML 文件;Agent Framework 导入器将源读作 YAML,不指定文件,要求 kind 处为字符串 Prompt 且 model 处为对象;Go kit 的 import 示例将源读作 YAML,并要求 kind 处为字符串 DemoSource。在 Go 中:
Importer: &aggrega.ImporterContract{Detect: []aggrega.DetectSignature{{ Syntax: "json", Match: []aggrega.PathMatch{{Path: "data.nodes", Is: "array"}},}}},导入目录时读取哪些内容。 源可以是一个目录,由导入器声明的文件模式决定读取什么:宿主恰好读取该目录中(任意深度)被导入器各签名的某个 files 模式选中的文件——每个文件以其在目录内以斜杠分隔的路径的末尾进行匹配——并按名称顺序以 sources 交出,此时 bytes 为空,name 为目录自身的名称。目录中的其他文件都不会被打开。工作区构建写入其渲染文件的文件夹——工作区根目录下的 dist/——不会作为包含它的目录的一部分被读取:其中的文件都不会被交出或参与识别,指向它的链接会被跳过;因此,已构建过的目录会按其所含的项目读取,而本身就是该文件夹或位于其中的目录则按所指定的那样读取。未声明 files 模式的签名不会选中目录中的任何文件,因此未声明任何模式的导入器只读取单个文件并拒绝目录;不包含任何被其模式选中的文件的目录同样会被拒绝。目录被限定在自身范围内:在要读取的文件中,若有链接(或指向目录的链接)通向目录之外,会在读取任何内容之前被拒绝;指向目录的链接从不进入;指向未被任何模式选中的文件的链接会被跳过、不予读取。识别目录的格式遵循同一规则——每个签名针对其模式选中的文件按名称顺序逐一尝试,每个文件对每种语法至多读取并解析一次,未声明模式的签名不适用于其中任何文件。宿主不设任何上限:对导入器来说过大的目录由导入器自身的运行时限制拒绝。编译器的 Langflow、Flowise、n8n、Dify 和 Agent Framework 导入器都未声明 files 模式,因此各自只读取单个文件;其 MCP 导入器声明了四种客户端配置的文件名,因此会读取目录中包含的每一个此类文件;其 Compose 导入器声明了八个 Compose 文件名,因此会收到目录中包含的每个 Compose 文件,并合并 Compose 会读取的那些文件;其 CrewAI 导入器声明了 CrewAI 项目声明所使用的六个文件名,因此会收到项目的声明,而不会收到其程序的任何部分;其 LangGraph 导入器声明了 langgraph.json,因此会收到应用的配置,而不会收到其任何代码或环境文件,环境文件只能通过其挂载的 with.sources 传入;其 Google ADK 导入器声明了 root_agent.yaml,因此会收到应用的根代理配置,而不会收到其任何代码或环境文件,其子代理所指定的配置只能通过其挂载的 with.sources 传入。
类型定义。 导入器的线上类型——ImportInput、ImportSource、CatalogProjection、CatalogComponent、CatalogSocket、ImportOutput,以及它所携带的实体、决策和脚手架结构——发布在全部三个 ABI 包中,并由每种语言的插件开发工具包重新导出,它们由同一个编解码器生成,因此三者保持同步;描述自报告所携带的识别类型 ImporterContract、DetectSignature 和 PathMatch 也是如此。Go kit 的导入器包 github.com/aggrega-ai/aggrega-pdk/go/pkg/importer 承载了导入器无论何种格式都要做的一切,而编译器的核心导入器全部基于它构建,都以这种方式读取输入、写出输出。
基于 Go kit 构建的导入器以什么为评分对象。 kit 的评分器将每个源节点与 catalog 视图中的 Components 进行比较,而不与其他任何东西比较:候选项就是工作区自己的目录——企业目录的 Components 与标准库的完全同等对待——kit 自身不携带任何候选项。对每个 Component,它读取名称、其 component.aggrega.ai/category 标签所携带的类别、其标签,以及其 values 声明的键名;其 provides 键和 sockets 不参与权衡。添加到目录中的 Component 在下一次导入时即成为候选项,无需重新构建任何导入器。当视图缺失(因为目录中没有任何 Component)时,没有节点拥有候选项:不会引用或提示任何 Component,草稿为其单独分配 Component 的每个节点都会被起草。所有通过 kit 评分的导入器都以这种方式评分——编译器的 Langflow、Flowise、n8n 和 Compose 导入器都在其中,而其 MCP 导入器不权衡任何候选项;不使用 kit 的导入器可以按自己的方式读取该视图。
基于 Go kit 构建的导入器读取平台的 socket 的用途。 socket 在评分中不占任何权重,但 kit 会读取它们来布局草稿。对于平台按原样运行其流程的格式(如 Langflow、Flowise 和 n8n 的格式),默认的草稿是该平台 Component 的一个实例,由它承载该流程;流程的每个部分都连接到第一个满足条件的 socket:按平台的 catalog 条目列出其 sockets 的顺序,取第一个其 selector 能被该部分的 Component 的标签(以视图中携带的标签为准)满足的 socket。只读取选择器和标签;选择器由导入器提供的函数进行匹配,因为 kit 本身不带任何选择器语法。如果视图中没有与平台同名的 Component,则不连接任何部分。核心导入器描述了编译器的 Langflow、Flowise 和 n8n 导入器以这种方式生成的草稿,以及改为将每个节点各自起草为一个 Component 的 layout 设置。
当前状态: 可用——由 aggrega import 调度,也可通过编辑器会话和面向助手的工具中的同一操作调度。
放置标准:linter 插槽与治理裁决角色
文档中有两个插槽的接口相似——都按规则输出结果——但它们在流水线中的位置和阻断语义不同。决定某项检查由哪个插槽承载的标准如下:
- 治理裁决角色(带内,可终止构建)。 专用于终止构建的策略:
halt裁决会停止编译流水线,构建不产出任何制品。适用场景是那些一旦违反就会使输出无法安全应用的策略:合规关卡(PCI / SOC2 边界放置)、拓扑不变量(零信任入口、跨边界认证)、凭据流形态(IR 中不得有明文密钥)等。策略可以基于 IR 图(ir-verdict,在渲染之前)或基于渲染后的制品(render-verdict,在渲染之后)进行推理。 - linter 插槽(带外,CI / IDE,仅供建议)。 专用于最佳实践和可发现性检查:违反时可疑但并不危险的规则——孤立的密钥、未使用的参数、已弃用的标签词汇、用于成本归属的标签完整性、命名约定偏移。检查失败只产生建议性输出;构建仍会产出制品。
用一条规则来概括放置标准:如果检查应当终止构建,它属于治理裁决角色;如果检查应当在不阻断流水线的前提下提醒作者或审阅者,它属于 linter 插槽。
两者目前均可使用。linter 插槽通过 aggrega lint 运行 publishing-linter;当工作区挂载了裁决角色插件时,治理裁决角色会在 aggrega build 期间以带内方式被分派。注意,裁决角色有自己的严重级别——策略本身也可以输出只提供建议而不终止构建的 warn 和 info 裁决——因此上文的“终止与建议”界线是针对整项检查的放置指导,并不意味着策略只能终止构建。严重级别模型参见治理插槽页面。
交叉引用
policy-socket.md— 治理插槽的完整说明:四种角色、裁决严重级别、操作员输入通道、为编译器内置的两种引擎之一编写策略、封装外部策略引擎,以及参考 guest。core-importers.md— 编译器自身的导入器,它读取的每种格式各一个:各自读取的内容、其设置,以及它们随每个编译器版本的发布。10-status.md#compilation-pipeline-phases— 状态页中的插件流水线分类(Wasm 插件流水线运行时就绪情况)。architecture/04-entity-taxonomy.md§“Domain 3: Infrastructure Base”——凭据 FeatureRecipes 的 Two-Part Plugin Principle(双部分 Plugin 原则,Fetcher + Injector 模式)。architecture/13-catalog-and-registry.md— 以 provider 段开头的 OCI 分类体系。entities/featurerecipe.md— FeatureRecipe 的pipeline:编写接口。when-to-use-a-pipeline-step.md— 决策指南:流水线步骤与模板化 FeatureRecipe 的取舍。templates/expansion-matrix.md— 插件流水线pipeline:with:块的模板求值规则及.steps访问语义。examples/04-secrets.md— 凭据 FeatureRecipe 可以采用的 Fetcher + Injector 流水线结构。errors/error-translation.md— 插件 guest 所参与的错误转换规范。