aggrega plugin
检查 CLI 可解析的 Wasm 插件
概要
aggrega plugin说明
Work with the WebAssembly plugins this CLI can resolve.
All of Aggrega's provider-specific and policy-specific behaviour lives in Wasmplugins rather than in the binary, so this is where you see which ones arereachable, add or remove a workspace binding, and check a guest before youpublish it.
Plugins reach the CLI two ways. Some are compiled into the binary and resolvewith no filesystem, cache or network access. The rest are workspace bindings in.aggrega-config.yaml, resolved through the plugin cascade. "aggrega plugin list"shows both groups together.
The subcommands below cover the whole life of a binding: list what is reachable,add and remove bindings, run a local guest export directly, sync themachine-owned records in a Plugin entity with its .wasm, and generate Plugincatalog entities from a guest's own metadata.子命令
| 命令 | 描述 |
|---|---|
aggrega plugin add | 在注册表中查找指定类型的插件并添加 |
aggrega plugin gen-catalog | 根据 guest 的 describe() 加上编写的覆盖层生成 Plugin 目录实体 |
aggrega plugin list | 列出 CLI 可解析的插件及其 describe() 元数据 |
aggrega plugin remove | 移除已配置的指定类型插件 |
aggrega plugin run-local | 加载本地 .wasm guest 并调用其某个导出 |
aggrega plugin sync | 将插件实体文件中由机器维护的记录(宿主函数、CLI 命令)与其 .wasm 同步 |
aggrega plugin add 说明
Find a plugin of the named type in the configured registry and add it to yourconfiguration.
Examples: aggrega plugin add cli moo # add the moo command aggrega plugin add cli moo:0.2.4 # a specific version aggrega plugin add governance rego --role render-verdict
Arguments: <type> The plugin socket to add for. One of: provider, governance, linter, importer, or cli. The governance type requires --role. <query> The plugin's name, optionally followed by :<version> to add that version rather than the latest published one. The name is looked up directly first. Where no plugin of the chosen type has that name, it is matched as a case-insensitive substring against the plugin names of that type, which reads the registry's whole catalog and must resolve to exactly one plugin — otherwise the command lists the candidates so you can narrow it. A query naming a version is never matched that way. The provider type takes no version.
What add writes depends on the type:
- A socket type (governance, linter, importer) pins the version the query names, or else the latest published version, and adds the bare plugin identity (<type>/<name>:<version>) to the plugins.<type> list. The latest is never taken from pre-release versions, so a plugin that publishes only those is added by naming one. A governance entry also records its --role, one of annotation-transform, label-transform, ir-verdict, or render-verdict. An importer the plugins.importer list already names keeps its one entry, moved to the pinned version with its place and what it carries under with. - The provider type adds a plugins.providers entry naming the plugin by its bare identity (provider/<name>) with no version; --capability names the capability the binding serves, preserving existing settings. The version is the one the Recipe pins, or else the highest available, and the lockfile records the one a pull chose. - The cli type fetches the plugin from the registry, verifies it, and caches its bytes, then pins it into the plugins.cli list as a top-level aggrega command — no separate pull step. Its resolved reference and the content digest of the verified bytes are recorded so the command runs those exact bytes, resolving from the local cache on later runs with no further network access. A cli plugin defaults to the global config, so its command is available in every workspace; --workspace pins it to this project instead. It needs no workspace: run outside one, its bytes are cached in the machine-wide cache rather than in the folder you ran it in. Its declared capabilities are confirmed before installing, and --accept-capabilities or --yes skips that prompt for non-interactive use.
A provider or socket attachment is written to a workspace's own configurationunless --global is passed, so outside a workspace it is refused before theregistry is reached; so is anything else that can be refused without it.
A provider or socket attachment is configuration you go on editing, so --dry-rundoes everything the plain command does except write: it hands back theconfiguration the write would have produced, creating and modifying nothing. Theanswer names the file that content is for — which matters here, because a--global attachment targets the config shared across every workspace. A callerthat keeps its own document model puts the content there, where it is visiblebefore it is saved and can be amended or undone. The registry is still searched,and for a socket type the version still resolved, since the returned documentcarries the identity a write would have written.
Under --dry-run standard output carries that content and nothing else, so it staysparseable; a version substitution is announced on standard error instead. The clitype does not accept --dry-run: what it records is the content digest of the bytesit verified, which is a record the machine maintains rather than content youedit.aggrega plugin add 标志
| 标志 | 默认值 | 描述 |
|---|---|---|
--accept-capabilities | false | 无需交互式提示即接受 cli 插件声明的能力(仅限 cli 类型) |
--capability | — | provider 绑定所服务的能力(provider 类型必需,且仅对该类型有效) |
--dry-run | false | 执行除写入外的所有操作:将生成的配置作为内容返回,并注明其对应的文件,不创建或修改任何内容。不使用此标志时,附加项会写入解析得到的配置文件。不适用于 cli 类型。 |
--global | false | 将附加项写入所有工作区共享的全局配置。 |
--role | — | 治理附加项角色:annotation-transform、label-transform、ir-verdict 或 render-verdict(governance 类型必需,且仅对该类型有效) |
--workspace | false | 将附加项写入本项目的工作区配置。provider 或 socket 附加项默认写入此处;cli 插件默认写入全局配置。 |
--yes | false | 跳过 cli 能力确认提示,用于非交互式场景(仅限 cli 类型) |
aggrega plugin gen-catalog 说明
Generate one Plugin entity per selected Wasm guest.
Each entity's contract fields — pluginType, abiVersion, capabilities, exports,and contract — are derived from the guest's describe() self-report, so theentity can never promise a capability the binary does not provide. The entity'sidentity (metadata.name), runtime limits, and provider block come from an authoredper-plugin overlay; the entity version is the guest's describe() self-reportversion. The plugin-level description, when the guest reports one, is emitted asmetadata.description and omitted cleanly when it does not.
Two selection modes:
--from-embedded generate an entity for every guest embedded in this binary. The overlay path is a directory; each overlay is matched to a guest by its metadata.name identity, and, where overlays in several socket directories (<socket>/<name>.yaml) declare one name, by the directory naming the guest's socket. --plugin <f.wasm> generate a single entity for one non-embedded guest. The overlay path is a single overlay file.
The output is written under <output-dir>/<pluginType>/<name>/<version>/plugin.yamland carries a generated-output banner. The leading pluginType segment keeps twosame-named plugins in different sockets apart, since a bare plugin name is uniqueonly within its own socket. Regenerating over unchanged inputs yieldsbyte-identical files.
A generated entity is a catalog document you own and go on editing, so --dry-rundoes everything gen-catalog does except write: it hands the content back, creatingand modifying nothing, and the answer names the file each document is for. Acaller that keeps its own document model — an editor, for instance — puts thecontent there, where it is visible before it is saved and can be amended orundone. Every other behaviour is the write's — the same guests are read and thesame overlays matched — so a selection gen-catalog would refuse is refused under--dry-run too. Without the flag the entities are written, because a caller at aterminal has nowhere better to put them.aggrega plugin gen-catalog 标志
| 标志 | 默认值 | 描述 |
|---|---|---|
--dry-run | false | 执行除写入外的所有操作:将生成的实体作为内容返回,并注明每个实体对应的文件,不创建或修改任何内容。其他行为均与写入相同,因此写入会拒绝的选择在此同样会被拒绝。不使用此标志时,实体会写入 —output-dir 下。 |
--from-embedded | false | 为此二进制文件中嵌入的每个 guest 生成一个实体 |
--output-dir | — | 生成的实体写入的目录(必需) |
--overlay | — | 编写的覆盖层目录(—from-embedded)或文件(—plugin)(必需) |
--plugin | — | 为此路径下的 .wasm guest 生成单个实体 |
aggrega plugin list 说明
List every Wasm plugin the CLI can see and, for each, its self-reporteddescribe() metadata.
Two groups are printed. Embedded built-ins are the provider and linter guestscompiled into the binary; they resolve with no filesystem, cache, or networkaccess. Configured plugins are the workspace bindings — the provider and linterbindings and the CLI-extension commands — resolved through the plugin cascade.Each plugin's type appears in the TYPE column, so a CLI-extension command(type cli) is legible alongside the socket plugins; a CLI plugin also carries astatus of its own — ready, unresolved, describe-failed, or digest-drift whenits bytes changed since it was pinned at install.
The default output is a scannable table with one row per plugin, showing itstype, name, served capabilities, and version. The output is read-only anddeterministic. A plugin that fails to resolve or describe is listed with itsfailure status rather than halting the whole listing.
With -o json, the output is a structured object carrying the full per-plugindetail — type, name, version, commit, capabilities, input kinds, boundaryassembly, exports, origin, readiness, and any resolve or describe error —grouped as embedded and configured. It is suitable for programmaticconsumption and documentation generation.aggrega plugin list 标志
| 标志 | 默认值 | 描述 |
|---|---|---|
--output, -o | table | 输出格式:table|json。 |
aggrega plugin remove 说明
Remove a configured plugin of the named type from a config file so it no longerparticipates.
The type is one of provider, governance, linter, importer, or cli — the sameset 'plugin add' accepts. The query identifies the entry to remove: the plugin'sshort name (matched against 'add's short name so remove is symmetric with add),its full pinned reference, or, for the provider type, the capability the bindingserves. A query that matches nothing halts and leaves the config untouched, so atypo never silently removes the wrong plugin.
A provider or socket attachment defaults to this project's workspace config; a clicommand defaults to the global config shared across every workspace. --global and--workspace force the file the removal targets, overriding the default.aggrega plugin remove 标志
| 标志 | 默认值 | 描述 |
|---|---|---|
--global | false | 从所有工作区共享的全局配置中移除。 |
--workspace | false | 从本项目的工作区配置中移除。provider 或 socket 附加项默认作用于此处;cli 命令默认作用于全局配置。 |
aggrega plugin run-local 说明
Load a .wasm guest from a filesystem path, call one of its declaredexports with an optional payload, and write the guest's answer to stdout.
The guest is addressed directly by --plugin path; it is not resolved throughthe workspace plugin cascade. The export named by --export must be one theguest advertises in its describe() self-report, or the call is rejected beforethe guest runs.
The command has two forms. The artifact form takes no positional argument andloads the guest bare. The entity form takes a Plugin entity file as its onepositional argument: the entity is schema-validated, and its declaredmetadata.pluginType and export contract are cross-checked against the guest'sdescribe() before the guest runs. In both forms the guest bytes come from--plugin; the entity carries no artifact path.
The payload is supplied with --with, and it is always written as JSON. A valuebeginning with @ reads the payload bytes from a file (--with @input.json); anyother value is taken as a literal inline JSON payload (--with '{"k":1}'). When--with is omitted, the export receives the minimal empty JSON object {}. Theresolved payload is validated as JSON before the guest runs, so malformed inputis reported up front.
An export a socket calls with a payload reads it in a binary encoding ratherthan as JSON; a CLI plugin's cli_run export is the exception, and reads JSON.Which encoding an export reads is fixed by the socket that export serves, so noflag selects it: the resolved payload is converted into the encoding the namedexport reads before the guest is called. The conversion reads the payload'sshape from the export's name, so it covers each export a socket calls bydefault; an entry function an attachment or a pipeline step names under a nameof its own receives the payload as written. The authored payload stays JSONeither way.
The answer is converted the same way in reverse. An export a socket callsanswers in that binary encoding, so its answer is read as the export's outputshape and written to stdout as indented JSON; an answer that is not that shapeis reported as an error naming the export rather than printed. A cli_runexport's answer, and an entry function under a name of its own, are written tostdout exactly as the guest wrote them. When the guest exits non-zero, what itwrote is passed through unchanged.
In the artifact form, --type optionally names a plugin type the guest'sdescribe() self-report must agree with, or the load is rejected before theguest runs; when omitted, no type expectation is imposed. In the entity form--type is rejected, because the entity's metadata.pluginType supplies the type.
The guest's clean exit code becomes this command's exit status, so a failureinside the plugin is distinguishable from a failure of aggrega itself.aggrega plugin run-local 标志
| 标志 | 默认值 | 描述 |
|---|---|---|
--export | — | 要调用的已声明导出 |
--plugin | — | .wasm 制品的文件系统路径 |
--type | — | guest 的 describe() 自报必须匹配的插件类型 |
--with | — | 导出的负载:内联 JSON,或用 @ |
aggrega plugin sync 说明
Sync a plugin's machine-owned records in a Plugin entity file with its .wasm.
Two records are not authored by hand: the set of host functions a plugin maycall, derived from the plugin's .wasm import section, and the top-level commands aCLI plugin contributes, read from the plugin's describe() self-report. Both areground truth in the binary. This command reads the .wasm, derives thehost-function set in canonical form and the command mirror in describe()-declaredorder, and aligns the entity's spec.runtime.hostFunctions and spec.commands withthem — creating the runtime block when the file has none. Only those blockschange; every comment, blank line, and other field is preserved byte-for-byte. Aplugin that imports no host functions or contributes no commands records anexplicit empty list, so each field is always present and reviewable.
The write is idempotent: re-running when the records already match the .wasmleaves the file untouched. Commit the result; publish (aggrega push) then onlyverifies the committed records against the .wasm and refuses to publish a filewhose records are out of sync with its binary.aggrega plugin sync 标志
| 标志 | 默认值 | 描述 |
|---|---|---|
--plugin | — | 插件 .wasm 制品的路径,其导入和 describe() 决定所记录的宿主函数和命令 |
importer 条目的作用
aggrega plugin add importer 将插件的标识及其已发布的最新版本,或你以 <name>:<version> 形式指定的版本(importer/<name>:<version>)写入 plugins.importer 列表。该条目挂接它所指定的 importer:请求该 importer 所声明格式的导入会运行这个 importer 的该版本,即使你的目录中还有其他 importer 也声明了该格式;并且只有这个 importer 会收到该条目在 with 下携带的内容。哪个 importer 将源转换为草稿完整描述了该条目。
一个 importer 由一个条目挂接,因此,如果所写入文件的 plugins.importer 列表已指定某个 importer(无论是任意版本还是通过版本范围),再次添加它不会产生第二个条目。命令会改为将该条目更新到它解析出的版本:该条目保留其在列表中的位置及其在 with 下携带的所有内容。如果添加的 importer 版本与其条目已指定的版本相同,则该条目保持不变。
CLI 插件的命令及其标志
每次 aggrega 启动时,它都会为已配置的 cli 插件所提供的每个命令添加一个对应命令,并从插件的 describe() 自我报告中读取这些命令及其标志:当 describe 缓存中存有该插件的固定摘要时从缓存读取,否则通过对插件执行 describe 获得。每个声明的标志都会声明在其所属命令上,因此 aggrega help <command> 会像列出内置命令的标志那样列出它;插件仍然接收未经解析的参数,并自行读取自己的标志。
固定摘要位于配置的 plugins.cli 列表中插件引用的旁边,写作 sha256: 后跟 64 位小写十六进制数字,即 aggrega plugin add cli 所记录的写法。以其他任何方式书写的摘要,例如不带 sha256: 前缀的纯十六进制,会在加载配置文件时被拒绝,并指明该文件和该条目;在其被修正之前,不会添加任何已配置插件的命令,并会在标准错误输出上发出一条包含该拒绝信息的警告。
在添加插件的任何命令之前,aggrega 会检查每个命令所声明的每个标志。声明未通过检查的插件会被跳过:其命令一个都不会被添加,标准错误输出上会出现一条警告,指明该插件、该命令、该标志及其问题所在,而其他所有命令(无论是内置命令还是来自其他插件的命令)照常运行:
warning: CLI plugin "oci://hub.aggrega.ai/plugin/cli/greet:1.2.0" was not added as a command: its command "greet" declares the flag "--verbose" with the shorthand "vv"; a shorthand is a single ASCII letter or digit标志声明在以下情况下通过检查:
- 该标志有名称,且同一命令的其他标志都不使用该名称;
- 其简写(如果有)是单个 ASCII 字母或数字,且同一命令的其他标志都不使用它;
- 其名称和简写都不与每个
aggrega命令已有的标志重复,即--help、-h以及全局标志; - 其类型(如果声明了)为
string、bool或int;未声明类型的标志为字符串标志; - 其默认值(如果声明了)是其类型的一个值。
在配置固定到该插件某个声明能通过检查的版本之前,每次调用都会重复跳过该插件并发出警告。标志声明所包含的字段在 Plugin 实体页面的 spec.commands 下有说明。
生成实体与同步记录:两种不同的操作
这些子命令中有两个会生成文件,而它们生成的东西并不属于同一类。
plugin gen-catalog —— 生成的实体由你编辑
aggrega plugin gen-catalog 生成 Plugin 目录实体。实体是一个目录文档:你将它归档、审阅,并与目录的其余部分一起继续编辑。由于它是你拥有的内容,该命令可以把它交给你,而不是写入磁盘。
--dry-run 执行 gen-catalog 所做的一切,唯独不写入。它将生成的实体作为内容返回——不创建文件,也不创建目录——并且返回结果中的每个文档都会指明它对应的文件,因此调用方知道每个文档应放在哪里。维护自身文档模型的调用方(例如编辑器)会把内容放入该模型,你可以在保存前看到它,并可以修改或撤销。不带该标志时,实体会写入 --output-dir 下,因为终端中的调用方没有更好的地方存放它们。
返回的内容与写入的字节是同一份内容:--dry-run 返回的是写入本应产生的结果,而不是单独组装的预览。其他所有行为也与写入相同——读取相同的 guest,匹配相同的 overlay,并且两种情况下都必须提供 --output-dir,因为每个返回的文档仍会指明它对应的文件,而该路径正是由它组合而成的。
所有实体都会在任何一个被交付之前完成组合和验证,因此一次运行要么生成整个集合,要么什么也不生成。导致生成中止的 overlay——缺失的 overlay,或其标识与所合并的 guest 不匹配的 overlay——不会留下需要清理的部分写入的输出。
plugin sync —— 机器拥有的记录归编译器所有
aggrega plugin sync 使插件中机器拥有的记录与其模块保持一致:从模块的导入段推导出的宿主函数集,以及从插件自身的自我报告中读取的命令镜像。两者都是二进制文件中的事实依据,而不是任何人选择的值。
它总是执行写入,并且不提供 --dry-run。即使它写入的是你编写的实体文件内部,也是如此——界限划在内容上,而不是文件上。编译器维护的关于其自身的记录不由你编辑,因此在写入之前没有需要审阅的内容;周围的文档逐字节保持不变,只有这些块会改变。