跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

aggrega scaffold

为某实体种类起草起始文档,或将可运行示例写入新目录

概要

aggrega scaffold <kind> [name] | --example <name> [dir] | --example --list [flags]

说明

Draft a starter document for an entity kind from its schema, or write one of the documentation's runnable examples into a new directory.
Drafting a starter document
The kind is the lowercase-hyphenated schema token — for example component, aggregate, release, recipe, manifest, or feature. Run aggrega get-schema --list to print the whole set; a token no schema answers to is refused with that set in the message, so a typo is corrected without a second lookup.
The document is derived from that kind's own contract and from nothing else. It carries exactly the fields that kind's schema requires, with the fixed apiVersion and kind filled in and a placeholder everywhere a value is needed. It is not a worked example: there is no namespace, no category, no label set and no commented suggestion of what people usually write, because a catalog decides those for itself and a starter document that guessed at them would teach a requirement that does not exist.
The optional name seeds metadata.name for a kind whose schema requires one. Every other required value is left as a placeholder to fill in.
Nothing is written to disk. The document goes to standard output, so a redirect decides where it lands:
aggrega scaffold component my-service > my-service.yaml
The same starter document is served to an assistant by the scaffold tool that aggrega mcp exposes, which returns these bytes alongside a machine-readable payload; this command is the terminal route to the same drafting.
Writing a runnable example
With --example, the argument is the name of one of the runnable examples the documentation publishes, and the command writes that example's files into a new directory — the second argument, or a directory named after the example in the current directory when there is none — then prints the commands the example's own page gives for building it:
aggrega scaffold --example redis-cache
The directory must not exist yet, or must be empty; a directory holding anything is refused and left as it is. With --list, the command prints every example there is, each with its level and the first sentence of its page, and writes nothing:
aggrega scaffold --example --list
The examples are read from the documentation bundle published for this version of aggrega on the default registry — or, where none is published for it, the newest one published for an earlier version. It is kept in the cache every project on this machine shares, so a second example needs no second download. It is fetched through the same network settings as every other registry read, and verified against this workspace's signature policy before it is kept or read; a bundle that does not verify is refused, never used. Offline, an example is written only from a copy already cached on this machine.
An example's files are written only as files and directories inside the directory named: a bundle carrying an entry that would land outside it, or a link, is refused whole and nothing is written.
The scaffold tool that aggrega mcp exposes, and the editor's language server that aggrega serve runs, write and list the examples on the same terms, with the directory named relative to the workspace root, and answer with the files written and these same commands.

标志

标志默认值描述
--examplefalse将参数指定的可运行示例写入新目录,示例从已签名的文档包中读取
--listfalse与 —example 一起使用时,打印文档发布的所有可运行示例,不写入任何内容

功能说明

该命令有两种形式。aggrega scaffold <kind> 根据某个 kind 的 schema 起草一份初始文档并将其打印出来,这正是本节及后续三节所介绍的内容。aggrega scaffold --example <name> 则将文档中的一个可运行示例写入新目录——参见从可运行示例开始。

aggrega scaffold <kind> 将某一实体种类的起始文档输出到标准输出。该文档恰好包含该种类 schema 所要求的字段:apiVersion 和 kind 已填好,因为 schema 固定了它们;其他每个必需值都留作占位符,由你替换。

对于 schema 要求 metadata.name 的种类,可选的 [name] 用于预填该字段:

Terminal window
aggrega scaffold component my-service
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: my-service
version: ""
labels:
component.aggrega.ai/type: ""
spec: {}

种类是小写连字符形式的 schema 标识符——component、aggregate、release、recipe、manifest、feature 等。aggrega get-schema --list 会输出完整集合;没有 schema 对应的标识符会被拒绝,并在消息中列出该集合,因此无需再次查找即可纠正拼写错误。

它返回什么,不返回什么

该文档只来自该种类自身的契约,别无其他来源。 它不是完整示例。不会为你填写命名空间、类别或标签值,也没有关于人们通常写法的注释建议——因为这些都不是编译器所要求的。目录自行选择命名、类别和目录结构;schema 决定字段,而该命令只读取 schema。一个猜测其余部分的起始文档会教给你一条并不存在的规则。

起草不写入任何文件。 文档输出到标准输出,因此由重定向决定它写到哪里,未经你要求,磁盘上的任何内容都不会被替换:

Terminal window
aggrega scaffold component my-service > my-service.yaml

它不是完成的实体,这正是占位符的含义。 空的必需值不是值,因此对原样输出的文档运行 aggrega validate 会拒绝它,并一次性列出每个仍待填写的占位符及其所需内容——上例中为版本和 component 类型:

Entity: my-service.yaml
Kind: Component
[E0215]
document envelope validation failed: 2 placeholders still owed in my-service.yaml; an empty required value is not a value, so each of these needs one before the document validates:
5:3: metadata.version takes a semantic version, such as 1.0.0
7:5: metadata.labels.component.aggrega.ai/type takes one of: server, worker, task, function, stateful-server, resource

每个值所需的内容从该种类自身的 schema 中读取:schema 列出可接受值时为这些值,要求语义化版本时为语义化版本,否则为 schema 自身对该字段的描述。提供这些值后,同一命令即会接受该文档。其结构无需任何改动,因为结构来自 schema。

即使 schema 接受空值,也仍需填写值。 起草的 Recipe 或 FeatureRecipe 带有空的 capability 和 implements。其 schema 允许空字符串,但空字符串既不指明 provider 也不指明类型,因此在你填写之前,aggrega validate 会将两者列为仍待填写。这一判断仅适用于验证单个实体文件:对整个目录的运行、aggrega validate --release 和 aggrega build 不会应用它。其适用范围参见仍待填写的占位符。起草的 Recipe 也未声明其 schema 要求至少声明一种的任何输入类型——source、valuesMapping、workload 或 artifacts——因为选择哪一种由你决定,所以在你添加一种之前,aggrega validate 会拒绝其 spec。

从助手或编辑器获得同一文档

无论由哪个界面请求,起始文档的字节都相同。通过 aggrega mcp 连接的 AI 助手以 scaffold 工具访问它,该工具以文本形式返回文档,并附带机器可读的负载。驱动 aggrega serve 的编辑器通过 aggrega/scaffoldEntity 访问它。文档只从 schema 派生一次,因此你在终端起草的文档与助手为你起草的文档逐字节相同。

编写和列出可运行示例也在这些相同的接口上提供,字段名沿用该命令自身的用词。向 scaffold 工具或 aggrega/scaffoldEntity 发送 example(而不是 kind)即可写入一个示例,发送 dir 可指定新目录相对于工作区根目录的路径——未发送时,使用工作区根目录下以该示例命名的目录——而仅发送 list: true 则会得到所有示例。示例从同一个文档包读取,按同一策略校验,并由同一解包过程写入,因此写入的文件和接下来的命令与在终端中完全相同,拒绝情形也相同:目录中已有任何内容、某个条目指向目录之外或是一个链接、文档包不被你的策略接受、离线工作区中没有任何缓存。回答是结构化的:对于列表,是 examples,每项包含 name、level 和 summary;对于写入,是 example、dir、files——写入的文件,相对于 dir——next,即示例页面给出的命令,以及 version,即读取该示例所用的文档版本。scaffold 工具对写入的回答还带有 output_dir,即该目录所在的位置——通过标准输入输出时为完整路径,这样以相对于自己看不到的工作区的路径指定它的助手也能知道示例写到了哪里;通过 HTTP 时则相对于工作区根目录。scaffold 工具的文本就是此命令打印的说明,当该位置与 dir 不同时,末尾会有一行指明该位置。同时发送属于两种形式的字段——例如 kind 与 example——会在读取任何内容之前被拒绝,两种接口上的措辞相同。编辑器在示例形式下通过请求的 workspaceRoot 指明工作区,dir 必须是一个停留在工作区之内、且不会经由链接通向工作区之外的相对路径;通过 HTTP 时,该工具同样将 dir 限制在其所服务的工作区内,而通过标准输入输出时,它按所给的值接受 dir,正如它接受每一个路径那样。能力索引因该形式将 scaffold 工具报告为会写入,并将在单独进程中运行此命令的 cli-scaffold 同样报告为会写入。

从可运行示例开始

文档附带可运行示例——每个示例都是一个目录,其中包含一个 Aggregate、它的 Releases 以及构建它所依据的其他任何内容,并配有一个说明如何构建它的页面。--example 将其中一个写入新目录,这样你就可以从一个能运行的项目开始,而不是从空白项目开始:

Terminal window
aggrega scaffold --example redis-cache
Wrote the example redis-cache into redis-cache (12 files).
Next:
cd redis-cache
# Local development (Docker Compose), no authentication
aggrega build --release release-compose.yaml --auto-pull
...
Its page, redis-cache/README.md, explains what it shows.

写入什么,写到哪里。 示例的文件按文档中的原样写入你作为第二个参数指定的目录——如果未指定,则写入运行命令所在文件夹中以该示例命名的目录。该目录必须尚不存在,或者必须为空。其他任何情况都会被拒绝,并保持原样不动:目录中有文件、该路径上已有一个文件,或者是一个链接。其上层尚不存在的目录会被创建。示例的任何文件都不会留在其他地方,并且在全部文件写完之前不会有任何文件就位:它们先写到一旁,等每一个都写好后再移入。

它接下来打印的命令就是示例自身页面给出的命令:页面 ## Build 标题下的第一个 sh、bash 或 shell 代码块,保持页面的原样(包括注释),并放在一条进入该目录的 cd 之后。页面中没有此类代码块的示例,则改为给出其页面的路径。

有哪些示例。 --list 按文档讲授它们的顺序打印每个示例,每个只打印一次——包括其名称、其页面声明的级别以及其页面的第一句话——且不写入任何内容:

Terminal window
aggrega scaffold --example --list
EXAMPLE LEVEL DESCRIPTION
...
redis-cache start This lean example compiles a single **Redis** in-memory cache (Redis wire protocol) from one Developer-authored `Aggregate` to two realizations.
...

该列表就是文档自身的示例列表,即与示例一同发布的按产品和能力分类的示例。文档包中没有对应示例的名称会被拒绝,并提示你使用 --list,且不写入任何内容。

示例从何而来。 它们读取自文档包——即已发布文档的签名归档,aggrega explain 也从中读取其讲解——该文档包发布在你的工作区的默认注册表上。读取的文档包是为你正在运行的 aggrega 版本发布的那一个。如果没有为该版本发布文档包,则读取为更早版本发布的最新文档包,并且命令会在标准错误输出中说明这一点:

note: no documentation is published for 0.9.1; the examples are read from the documentation published for 0.9.0, the newest before it

由某个发布版本之后的若干提交构建的 aggrega——其 aggrega version 显示类似 0.9.0-12-g1a2b3c4d——读取它所基于的那个发布版本的文档,此处为 0.9.0,若该版本的文档未发布,则读取更早的版本。由某个预发布版本(例如候选发布版本)之后的若干提交构建的版本——其 aggrega version 显示类似 0.9.0-rc.6-4-gc9db2f597——读取该预发布版本的文档,此处为 0.9.0-rc.6;若该文档未发布,则读取在它之前发布的最新文档,包括更早的预发布版本。其他任何构建只有在其本身就是某个预发布版本时,才读取该预发布版本的文档。未标记发布版本号的构建只读取其自身版本的文档,若没有则不读取。aggrega explain 也以同样的方式选择其读取分步讲解所用的文档包。

如果没有为你的版本发布的文档包,而更早版本中最新的那个采用了此版本 aggrega 不再读取的格式——例如在其自身文档发布之前运行的候选发布版本——命令会拒绝,用一句话同时说明这两点,并且不写入任何内容:

[E0137]
hub.aggrega.ai/docs/aggrega-docs publishes no documentation bundle for 0.9.1-rc.1, and the newest earlier one, 0.8.11, is in a format this version of aggrega no longer reads, so the examples cannot be read

使用前先经过校验。 文档包通过与其他所有注册表读取相同的网络设置获取,其签名在保存之前会依据你的工作区针对该注册表的签名策略进行检查——在读取本机已有的副本之前也会再次检查,因此由另一个项目更宽松的策略放入的副本不会在你的策略下被使用。你的策略不接受的文档包会被拒绝,且不写入任何内容。

每台机器只获取一次。 文档包保存在本机所有 Aggrega 项目共享的缓存中——参见 aggrega cache——因此第二个示例或第二个项目无需再次下载,并且在两者读取同一版本时,aggrega explain 读取的是同一份副本。

离线时只读取已缓存的内容。 在离线工作区中不会获取任何内容:示例从本机已有且你的策略允许的副本写入——对应此版本的那一份,否则为已缓存的更早版本中最新的一份——如果一份都没有,命令将以每次网络读取都会给出的离线拒绝而拒绝,并说明如何允许网络访问。

携带意外内容的文档包会被整体拒绝。 文档包来自注册表,因此解包过程不信任其布局的任何方面:名称会落到你指定的目录之外或文档包之外的条目,以及属于链接或文件、目录之外任何其他类型的条目,都会导致整个示例被拒绝,并指明该条目,且不写入任何内容。示例中的可执行文件仍保持可执行。

会读取工作区的配置。 默认注册表和签名策略都来自该配置,因此如果配置文件是一个通向工作区之外的链接,示例形式会被阻止,正如读取配置的其他所有命令都会被阻止一样——参见工作区边界。

示例

起草一个未命名的 Release 并在终端中查看:

Terminal window
aggrega scaffold release

将一个 Recipe 直接起草到文件中:

Terminal window
aggrega scaffold recipe postgres-helm > postgres-helm.yaml

在填写任何内容之前,检查仍需填写哪些值:

Terminal window
aggrega scaffold component my-service > my-service.yaml
aggrega validate my-service.yaml

查看有哪些可运行示例,然后将其中一个写入你选择的目录:

Terminal window
aggrega scaffold --example --list
aggrega scaffold --example redis-cache my-cache

关于该命令开启的编写循环——起草结构、填写占位符、验证——参见编写 Aggrega 文件。