编写 provider:完整演练
本页完整演示编写一个 provider guest 的全过程,从一个空目录开始,直到构建写出由该 provider 渲染的文件。它是插件开发者指南的实践配套,该指南记录实体与生命周期;它也是插件契约的实践配套,该契约记录各个 socket。
这里构建的 provider 足够小,一次就能读完,同时又做实际的工作:它渲染环境文件。这个目标很适合作为第一个 provider,因为它的转换确实与格式相关——环境文件有自己的键语法、自己的引号规则,也没有可以存放构建来源信息的元数据块——因此 guest 必须做出大型 provider 要做的每一个决定,而又没有大量代码将这些决定掩盖起来。
**关于本页中的代码块。**每个显示输出的代码块都复制自按下文步骤顺序实际运行的结果,并遵循输出约定:一个代码块要么是完整的,要么是标明了省略行位置的摘录。这是一个需要你自己动手组装的演练,而不是一个可以克隆的工作区,因此源代码块是需要你创建的文件,而不是需要检出的文件。
你需要准备的内容
- Go 工具链,它无需额外工具即可编译为 WebAssembly。
- 插件开发套件的一份检出副本(插件开发者指南对其有介绍),以及该套件所基于的 ABI 包的检出副本:下面 guest 的
go.mod指向这两者。 aggrega二进制文件。
成品的形态
一个 provider 由两个制品组成:一个 .wasm guest,以及一个把它带入目录的 Plugin 实体。除此之外别无他物——无需修改宿主,无需注册,也无需重新构建编译器。添加一个 provider,就是把这两个文件放到构建能看到的位置。
本演练最终得到的工作区:
dotenv-walkthrough/ guest/ the Go module that compiles to the .wasm go.mod go.sum main.go catalog/ the Component and Recipe you author component/example/compute/checkout/1.0.0/component.yaml recipe/dotenv/checkout/1.0.0/recipe.yaml dev-catalog/ the generated Plugin entity, with the .wasm beside it plugin/provider/dotenv/0.1.0/plugin.yaml plugin/provider/dotenv/0.1.0/provider--dotenv.wasm dotenv.wasm the compiled guest overlay.yaml the identity you supply to the entity generator aggregate.yaml manifest.yaml release.yaml .aggrega-config.yaml1. guest 的自我报告
每个插件都导出 describe()。宿主在加载
guest 时调用它一次,并把返回结果视为 guest 对自身是什么的说明。对于
provider,该结果中有四个部分很重要。
创建 guest/main.go:
// A provider guest that renders environment-file artifacts.package main
import ( "bytes" "fmt" "sort" "strings"
pdk "github.com/extism/go-pdk"
"github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega")
func descriptor() aggrega.PluginDescriptor { return aggrega.PluginDescriptor{ AbiVersion: aggrega.APIVersion, PluginType: "provider", Description: "Render artifact bodies into environment files, quoting and escaping each value as the format requires.", Capabilities: []string{"dotenv"}, Exports: []aggrega.PluginExport{ {Name: "render_node"}, }, Metadata: &aggrega.PluginDescriptorMeta{License: "Apache-2.0"}, }}
//go:wasmexport describefunc describe() int32 { out, err := aggrega.MarshalDescriptor(descriptor()) if err != nil { pdk.SetError(err) return 1 } pdk.Output(out) return 0}PluginType 说明该 guest 服务于哪个插槽。Capabilities 是
Recipe 据以解析的列表:spec.capability 为 dotenv 的 Recipe 将被
路由到该 guest。Exports 列出宿主可以分派到的入口点;render_node 是每个 provider 都必须具备的入口点。
这个描述符是有意不完整的,就像初稿通常 那样。下面的第一次构建会暴露这一点。
2. 渲染节点
构建通过此 provider 渲染的每个 component 都会调用一次 render_node。它接收节点的身份标识、渲染上下文,以及所绑定的 Recipe 声明的预先求值的输入——此处是一个 artifact 集合,宿主已读取它并将其作为模板求值。
guest 的全部工作就是决定输出哪些字节。在 guest/main.go 中添加:
// needsQuoting reports whether a value cannot be written bare in an// environment file. A bare value ends at the first space, so anything// carrying whitespace has to be quoted; the quote characters, the comment// introducer and the expansion introducer would each be read as syntax.func needsQuoting(v string) bool { if v == "" { return true } return strings.ContainsAny(v, " \t\n\r\"'#$\\")}
// quote wraps a value in double quotes and escapes what the format reads as// syntax inside them. Order matters: the backslash is escaped first, or the// escapes introduced afterwards would be escaped a second time.func quote(v string) string { v = strings.ReplaceAll(v, `\`, `\\`) v = strings.ReplaceAll(v, `"`, `\"`) v = strings.ReplaceAll(v, "\n", `\n`) v = strings.ReplaceAll(v, "\r", `\r`) v = strings.ReplaceAll(v, "\t", `\t`) return `"` + v + `"`}
// normaliseKey maps an authored key into the environment-variable grammar:// upper case, with the separators an author reaches for folded to// underscores. It reports an error rather than correcting a key that still// does not fit, because a silently-renamed variable is one the application// never reads.func normaliseKey(k string) (string, error) { n := strings.ToUpper(k) n = strings.NewReplacer("-", "_", ".", "_", "/", "_").Replace(n) if n == "" { return "", fmt.Errorf("empty key") } for i, r := range n { switch { case r >= 'A' && r <= 'Z', r == '_': case r >= '0' && r <= '9' && i > 0: default: return "", fmt.Errorf("key %q maps to %q, which is not a valid environment-variable name", k, n) } } return n, nil}该片段中的三个决定属于 provider 自身,其他任何层都无法做出。哪些字符需要强制加引号,是环境文件本身的事实。变量名语法也是如此;对于不符合语法的键选择拒绝而不是重命名,同样如此——被重命名的变量是应用程序会去查找却找不到的变量,这比构建中止更糟。
接下来是剩下的两部分:来源信息放在哪里,以及导出函数本身。
// provenanceComment renders the build-provenance key set the host computed as// comment lines. An environment file has no metadata block, so a comment// header is where provenance can go; the keys are emitted in sorted order so// the bytes are identical across runs of identical input.func provenanceComment(annotations map[string]string) []byte { if len(annotations) == 0 { return nil } keys := make([]string, 0, len(annotations)) for k := range annotations { keys = append(keys, k) } sort.Strings(keys) var out bytes.Buffer for _, k := range keys { fmt.Fprintf(&out, "# %s=%s\n", k, annotations[k]) } out.WriteByte('\n') return out.Bytes()}
// renderBody translates one artifact body into environment-file lines. A// blank line and a comment pass through untouched; every other line is// KEY=value, and a line carrying no separator is a loud failure rather than a// line the guest guesses at.func renderBody(name string, body []byte) ([]byte, error) { var out bytes.Buffer for i, raw := range strings.Split(string(body), "\n") { line := strings.TrimSpace(raw) if line == "" || strings.HasPrefix(line, "#") { continue } k, v, found := strings.Cut(line, "=") if !found { return nil, fmt.Errorf("%s line %d: %q declares no value; an entry is KEY=value", name, i+1, line) } key, err := normaliseKey(strings.TrimSpace(k)) if err != nil { return nil, fmt.Errorf("%s line %d: %w", name, i+1, err) } val := strings.TrimSpace(v) if needsQuoting(val) { val = quote(val) } fmt.Fprintf(&out, "%s=%s\n", key, val) } return out.Bytes(), nil}
//go:wasmexport render_nodefunc render_node() int32 { var in aggrega.RenderNodeInput if err := in.DecodeCBOR(pdk.Input()); err != nil { pdk.SetError(fmt.Errorf("dotenv: decode RenderNodeInput: %w", err)) return 1 }
if in.ArtifactsProjection == nil || len(in.ArtifactsProjection.Entries) == 0 { pdk.SetError(fmt.Errorf("dotenv: node %q supplied no artifacts to render", in.Node.ID)) return 1 }
var files []aggrega.RenderedFile for _, e := range in.ArtifactsProjection.Entries { body, err := renderBody(e.Name, e.Content) if err != nil { pdk.SetError(fmt.Errorf("dotenv: %w", err)) return 1 } files = append(files, aggrega.RenderedFile{ Path: e.Name, Content: append(provenanceComment(e.Annotations), body...), Format: "text", }) }
outputBytes, err := aggrega.RenderNodeOutput{Files: files}.EncodeCBOR() if err != nil { pdk.SetError(fmt.Errorf("dotenv: encode RenderNodeOutput: %w", err)) return 1 } pdk.Output(outputBytes) return 0}
func main() {}载荷以二进制编码传递,由 kit 负责读写。
宿主以规范 CBOR 形式将输入交给 render_node,并以相同编码读取应答,因此 guest 使用输入类型的 DecodeCBOR 解码,使用输出类型的 EncodeCBOR 编码——无需 CBOR 库,也无需手动解析。文件的 Content 是一个字节切片,guest 在其中填入要写入的确切字节;编码器将其作为原始字节传递,宿主原样写入。
宿主交给 guest 的是已求值的内容。 每个 artifact 条目的 Content 是编写的正文,其中的模板表达式已根据渲染上下文解析——guest 从不求值模板,也从不读取文件。正是这一点保持了编译器 ahead-of-time 边界的完整:guest 是从载荷到字节的纯函数。
确定性由 guest 负责。 在普通构建中,没有任何机制替你检查它。此处的确定性来自在输出前对来源信息的键进行排序,以及按载荷携带的顺序遍历 artifact 条目;本页末尾的检查会衡量其结果。
guest/go.mod 引用你本地检出的 kit:
module example.com/dotenv-provider
go 1.26.0
require ( github.com/aggrega-ai/aggrega-pdk/go v0.0.0 github.com/extism/go-pdk v1.1.3)
require github.com/aggrega-ai/aggrega-abi/go v0.0.0 // indirect
replace github.com/aggrega-ai/aggrega-pdk/go => /path/to/aggrega-pdk/go
replace github.com/aggrega-ai/aggrega-abi/go => /path/to/aggrega-abi/go3. 构建 guest
guest 就是一次选择了 WebAssembly 目标的普通 Go 构建:
cd guestgo mod tidyGOWORK=off GOOS=wasip1 GOARCH=wasm go build -trimpath -buildvcs=false \ -ldflags "-X github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega.Version=0.1.0 \ -X github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega.Commit=walkthru" \ -buildmode=c-shared -o ../dotenv.wasm ./go mod tidy 写入 go.sum,即依赖项的校验和,缺少它构建将拒绝运行。-trimpath 和 -buildvcs=false 让构建路径和版本控制标记不进入二进制文件,因此同一提交下的相同源码会产生相同的字节。两个 -ldflags 值把 guest 自身的版本写入其中,下一步会读取它。
继续之前,先确认导出项:
aggrega inspect --plugin dotenv.wasmPlugin .wasm: dotenv.wasmExports: render_nodehostFunctions (derived from binary, not yet recorded by aggrega plugin sync): (none)这个 guest 不导入任何宿主函数,这是最小权限的默认做法:它既不需要文件系统,也不需要网络,因为它渲染的一切内容都随 payload 一起到达。
4. 生成 Plugin 实体
实体的契约字段不是手写的——它们从 guest 中读取,因此实体不可能承诺二进制文件没有做到的事情。你只需在一个小型 overlay 中提供身份信息。
overlay.yaml:
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: dotenvaggrega plugin gen-catalog --plugin dotenv.wasm \ --overlay overlay.yaml --output-dir dev-catalog/plugingenerated dev-catalog/plugin/provider/dotenv/0.1.0/plugin.yaml生成的实体:
# Generated from the plugin by `aggrega plugin gen-catalog`. You may narrow its capability lists; edit nothing else here.apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: dotenv version: 0.1.0 pluginType: provider description: Render artifact bodies into environment files, quoting and escaping each value as the format requires.spec: abiVersion: v1beta1 exports: - name: render_node provider: capabilities: - dotenv注意其中没有什么:任何指向 .wasm 的指针。插件的位置由其身份推导而来——即 pluginType/name 坐标加上所配置的注册表——因此没有需要编写的位置字段,也就不会写错。内容摘要在解析 Release 时记录在该 Release 的锁文件中,而不是记录在实体中。
5. 把 guest 放到构建会查找的位置
在开发 guest 期间,还没有已发布的内容可供获取,因此构建从一个目录目录中读取它:即紧挨着其实体放置、以 socket 和插件命名的 .wasm。
dev-catalog/plugin/provider/dotenv/0.1.0/plugin.yamldev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasmcp dotenv.wasm dev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasm文件名同时包含 socket 和名称,是因为单独的插件名称只在其自身的 socket 内唯一——位于不同 socket、都叫 dotenv 的两个插件必须指向两个文件。
把构建好的文件复制到那里,而不是链接到它。该位置上的链接只有指向工作区内部某处时才会被跟随——或者,对于列在工作区之外的目录目录,只有指向该目录内部某处时才会被跟随;指向更外部位置的链接会使构建和拉取停止,并指出该链接,如工作区边界所述。
目录中的 provider 插件实体从不固定版本,pull 和 build 都不会获取它的 .wasm,因此在解析 Release 时该文件必须已经存在。pull 在写入 lockfile 之前会进行检查:如果它既没有在实体旁边、也没有在 build 读取插件的任何其他位置找到 .wasm,就会停止,并指出它所期望的文件和目录,如
A plugin’s .wasm is not on this machine(插件的 Wasm 文件不在本机上)
所述。
在 .aggrega-config.yaml 中让工作区指向这两个目录目录:
workspace: catalog_dirs: - catalog - dev-catalogauto_pull: trueauto_pull 让 aggrega build 在进程内解析 Release,因此首次构建不需要单独的解析步骤。
6. 以该 provider 为目标的文档
共四个文件。Component 声明作者可以设置什么;Recipe 绑定能力并编写制品;Aggregate 陈述意图;Release 对其进行放置。
catalog/component/example/compute/checkout/1.0.0/component.yaml:
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: example/compute/checkout version: 1.0.0 description: An application whose configuration is delivered as an environment file. labels: component.aggrega.ai/type: server component.aggrega.ai/category: computespec: schema: values: service_name: type: string default: checkout description: The name the application reports itself under. log_level: type: string default: info description: The application's log verbosity. greeting: type: string default: hello description: A value carrying characters the environment-file format must quote. infra: endpoint: type: string default: http://localhost:8080 description: The endpoint the operator points the application at.catalog/recipe/dotenv/checkout/1.0.0/recipe.yaml:
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: checkout version: 1.0.0 description: Renders the application's configuration as an environment file.spec: capability: dotenv implements: example/compute/checkout:1.0.0
artifacts: app.env: | service-name = {{ .values.service_name }} log.level = {{ .values.log_level }} greeting = {{ .values.greeting }} endpoint = {{ .infra.endpoint }}spec.capability: dotenv 就是全部绑定。它指定的是一项能力,而不是一个插件:构建会将其解析为声明了该能力的那个 provider 插件。如果恰好只有一个插件声明了它(如本例),就不需要其他任何配置。
这里编写的键有意没有采用环境变量的形式。service-name 和 log.level 是作者自然会写出的拼写,对它们进行规范化是 provider 的工作。
aggregate.yaml:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: aggregate version: "1.0.0" description: One application whose configuration is an environment file.spec: components: app: type: example/compute/checkout values: service_name: checkout log_level: debug greeting: hello worldmanifest.yaml:
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: manifest version: "1.0.0" description: Binds the component type to the environment-file recipe.spec: mappings: components: type: example/compute/checkout:1.0.0: checkout:1.0.0release.yaml:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: walkthrough environment: production version: "1.0.0"spec: aggregate: aggregate manifest: manifest boundaries: infra: directory: infra components: app: infra: endpoint: "https://checkout.example.net"7. 第一次构建,以及它拒绝了什么
aggrega build --release release.yaml --auto-pull warning: plugin "provider/dotenv" resolved from local with no recorded digest to check it against, so it runs unverified; it is read from beside its Plugin entity in a catalog directory on every build, and a pull records its digest only for a plugin attached at a transform role; otherwise publish the plugin and reference the published entity to have its digest recorded[… omitted: the notice saying the Release could not be rendered to discover its external inputs, carrying the error below beneath its first line]Pull complete: release.lock (entities=5, source_artifacts=0, external_inputs=0)[… omitted: a line saying again that external inputs were not fully discovered][CATALOG_ERROR E0265] instance app provider does not support the node's input kind (node "app"). provider "dotenv" does not support artifacts-only recipes (this provider supports: none); declare one of the supported input kinds, or target a provider that supports artifacts-only请分别阅读这两行,因为它们说的是不同的事情。
开发期间出现这条警告是预期之中的,而且它不会消失。 它表示该 guest 在运行时没有可供校验的已记录内容摘要,这正是一分钟前刚构建的 guest 的实际情况:没有任何东西发布过它,因此没有记录在案的摘要。它还说明了为什么重新解析该 Release 不会改变这一点——从 catalog 目录中其实体旁边读取的 guest 会被每次构建重新读取,而拉取操作只会为挂接在 transform 角色上的治理插件记录摘要,而这个 guest 不是这样的插件——以及什么才能改变这一点:发布该插件并引用已发布的实体。应将这条警告理解为构建正确地拒绝声称自己执行了并未执行的校验;只要 guest 仍在本地,就会一直看到它。
错误才是真正的发现,括号里的内容就是诊断。 该 provider 已被找到、加载,并被询问它渲染什么,而它回答了 none——this provider supports: none。开头编写的描述符指明了 socket、capability 和导出项,但从未说明该 guest 处理三种 Recipe 输入类型中的哪几种。宿主不会猜测:输入类型关卡读取 guest 声明的集合,并拒绝该 guest 从未声明的节点。
这就是大多数首个 provider 失败的样子。guest 本身没有问题;问题在于它的自我报告不完整。describe() 不是宿主容忍的一项形式——它是一个与格式无关的宿主决定将什么发送到哪里的全部依据。
8. 声明渲染行为契约
在 guest/main.go 的描述符中加入该契约:
Capabilities: []string{"dotenv"}, Contract: &aggrega.ProviderContract{ InputKinds: aggrega.InputKinds{ Sourced: false, Synthesized: false, ArtifactsStandalone: true, }, BoundaryAssembly: "none", }, Exports: []aggrega.PluginExport{ArtifactsStandalone: true 正是关卡在寻找的声明。两个
false 值同样是声明,而明确写出它们正是关键所在:一个内嵌源码树的 Recipe,或一个声明了 workload 的 Recipe,现在会在任何渲染运行之前就被拒绝,并给出指明该 provider 的消息——而不是进入
render_node 后在其内部某处失败。
BoundaryAssembly: "none" 表示每个节点的输出都写到其落点,没有需要合并的内容。将多个 component 合并为一个文档的 provider 则声明 merge 或 nest,并导出 assemble_boundary 来完成合并。这是该 provider 接下来自然要添加的功能,其说明见插件契约。
重新构建 guest,重新生成实体,并将新的 .wasm 放回实体旁边:
cd guestGOWORK=off GOOS=wasip1 GOARCH=wasm go build -trimpath -buildvcs=false \ -ldflags "-X github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega.Version=0.1.0 \ -X github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega.Commit=walkthru" \ -buildmode=c-shared -o ../dotenv.wasm ./cd ..aggrega plugin gen-catalog --plugin dotenv.wasm \ --overlay overlay.yaml --output-dir dev-catalog/plugincp dotenv.wasm dev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasm重新生成的实体现在带有从二进制文件中读取的契约:
[… omitted: the header comments and the metadata block, unchanged from the first generation]spec: abiVersion: v1beta1 exports: - name: render_node provider: capabilities: - dotenv contract: inputKinds: artifactsStandalone: true boundaryAssembly: none**每次重新构建 guest 后重新生成实体,是开发循环的一部分。**实体重述二进制文件所报告的内容,二者会在 guest 加载时交叉校验:实体声称而二进制文件未报告的导出或契约值是一种不匹配,构建会因此中止并指出该声明。实体省略的声明不受检查,因此在一次向二进制文件添加了内容的重新构建(如本步骤)之后遗留的实体仍能加载,只是不再描述该二进制文件。
9. 完成渲染的构建
aggrega build --release release.yaml --auto-pull warning: plugin "provider/dotenv" resolved from local with no recorded digest to check it against, so it runs unverified; it is read from beside its Plugin entity in a catalog directory on every build, and a pull records its digest only for a plugin attached at a transform role; otherwise publish the plugin and reference the published entity to have its digest recordedPull complete: release.lock (entities=5, source_artifacts=0, external_inputs=0)[… omitted: a line reporting total build time, which differs on every run]Build completed: 1 file written to <workspace>/dist最后一行给出输出目录的完整路径,其中 <workspace> 表示
工作区根目录。其下渲染出的目录树:
dist/infra/dotenv/app/app.env以及该 provider 写出的文件全文:
# aggrega.ai/boundary-path=infraSERVICE_NAME=checkoutLOG_LEVEL=debugGREETING="hello world"ENDPOINT=https://checkout.example.netguest 所做的每一个决定都体现在这七行中。
service-name和log.level按编写时的样子传入,输出为SERVICE_NAME和LOG_LEVEL。作者从不需要编写目标格式的 语法。GREETING加了引号,其他三个没有。hello world含有一个 空格,不加引号的话会在hello处截断;endpoint 不含任何 该格式视为语法的字符,加引号只会增加噪音。- 两个来源键是注释,因为环境文件没有 其他地方可以放置它们。若 provider 的输出有元数据块,则会把 同样的键放在那里。键由宿主计算;放置位置由 guest 决定。
- 这些值来自两位不同的作者。
service_name、log_level和greeting是开发者意图,来自 Aggregate。endpoint属于 运维人员,来自 Release。guest 看不到这两者的区别——它收到的 是一个已求值的主体。
10. 信任它之前值得检查的两件事
它是确定性的。 捕获输出,重新构建,然后比较:
cp -r dist ../capture && rm -rf distaggrega build --release release.yamldiff -r ../capture distdiff 不输出任何内容,就是你想要的结果。确定性是 guest 的
契约,而不是 host 的;一个在其输出路径中某处遍历 Go map 的 guest,
在单次构建中看起来完全正确,却无法通过这项检查。
它的拒绝是明确报出的。 破坏该 Recipe 的 artifact 中的一行,使其 不声明任何值:
artifacts: app.env: | service-name = {{ .values.service_name }} this line declares no value[… omitted: the unverified-plugin warning, and the pull's lines saying the Release could not be rendered to discover its external inputs][CATALOG_ERROR] instance app rendering node "app" caused by: wasm: plugin "provider/dotenv:0.1.0" call to render_node: dotenv: app.env line 2: "this line declares no value" declares no value; an entry is KEY=valueguest 自己的消息会完整地传达给作者,并附带它所来自的文件和行。 值得有意检查这一点,因为另一种失败方式——guest 悄悄跳过一行无法解析的内容——会产生一次 成功的构建和一个缺少变量的部署,而输出中没有任何内容 指出这一点。
11. 接下来可以添加什么
这里构建的 provider 是完整的,但只是最小实现。以下内容大致按需求频率排序:
-
assemble_boundary,用于将多个 component 的输出合并为一个 文档,通过BoundaryAssembly声明。 -
validate_node_input,用于在任何渲染运行之前对节点的输入进行结构检查, 使格式错误的输入在编写边界处报告, 而不是在渲染中途报告。 -
渲染事实(Render facts),用于报告 guest 所写内容中只有 该 provider 对环境文件格式的了解才能看到的信息——在这里是 每个文件定义的变量名。一个事实由一个名称和一个列表组成,二者都是该 provider 自己的词汇,与文件一并返回——其值 始终是一个 JSON 数组,即使只有一项也是如此,否则构建会中止:
// names lists the variables the files define, in the order they were written.value, err := json.Marshal(names)if err != nil {pdk.SetError(fmt.Errorf("dotenv: marshal render fact: %w", err))return 1}out := aggrega.RenderNodeOutput{Files: files,RenderFacts: []aggrega.RenderFact{{Name: "variable_names", Value: value}},}编译器按 guest 列出事实的顺序保存它们,只检查 每个值是否为列表,将这些列表交给读取它们的 Feature 模板, 并且无论是否报告事实,写出的文件都相同。请将每个事实的名称及其条目所含内容作为 provider 契约的一部分记录在文档中。
-
省略条目(Omit entries),在 provider 渲染源之后适用。源渲染的 输入可以在其
SourceListing旁携带Omits,即指定要省略的渲染单元的条目; 支持它们的 provider 会从返回结果中省略每个匹配的单元, 在Omitted中为每个条目报告一个计数,并且 在其契约中声明Omits: true。它们从不伴随 像本 provider 这样仅含 artifact 的渲染,因此只有在它 渲染带源的输入之后才会遇到它们。插件契约中的省略渲染单元 给出了完整结构。 -
发布,将本地的
dev-catalog布置转换为 一个经摘要固定、由 Release 解析并验证的 artifact。 插件开发者指南在发布、拉取和构建阶段下 介绍了这一生命周期。
每个 socket 的载荷和结果结构见 插件契约。
相关参考
- Wasm 插件开发者指南 —
Plugin实体、能力接口面以及发布生命周期。 - Plugin 契约——每个 socket 的输入和输出 结构。
- Provider 架构——provider 如何融入 编译流水线。
- Provider 参考索引——每个 标准库 provider 生成的内容。
- 阅读这些页面上的输出 — 上文 输出块所遵循的约定。