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

编写 Aggrega 文件

在 Aggrega 中编写是一个简短、可重复的循环。无论你编写的是哪种实体——开发者的 Aggregate、架构师的 Component、运维的 Recipe,还是运营者的 Release——同样的五个步骤都能让你从空白文件走到通过验证的文件:

  1. 选择你的角色负责的实体。
  2. 通过 JSON Schema 和参考页面了解其结构。
  3. 从骨架开始,而不是从空白文件开始。
  4. 填写你的角色负责的字段,其余字段留给它们的负责人。
  5. 验证,然后编译。

本页将完整走一遍这个循环,既面向手动编写的人员,也面向通过 Model Context Protocol 服务器编写的 AI 助手。这两条路径是基于相同参考资料的同一个循环。两者都需要 aggrega 二进制文件:安装二进制文件只需一条命令即可完成安装。

1. 选择你的角色负责的实体

Aggrega 将编写工作划分为四个协作角色——开发者意图、平台目录、基础设施配方和部署连接。每个角色通常负责一组特定的实体类型。如果你已经清楚自己的角色,可直接跳到所需的实体;如果不清楚,请阅读角色画像了解这四个角色,并阅读按角色划分的实体查看完整的类型到角色映射。

这种划分只是指导,而不是编译器强制执行的规则。单独的编写者可以身兼数职,一次性编写所有实体;编译器接受任何通过 schema 验证的编写方式。设立这些角色是为了让关注点清晰,而不是为了限制你可以编写的内容。

2. 了解其结构

每种实体类型都有一个规范的 JSON Schema 和一个逐字段说明的参考页面。编写之前请阅读这两者:

  • schema 是确切的结构:必填字段、允许的值以及嵌套。在命令行中,aggrega get-schema <kind> 会打印它;aggrega get-schema --list 会列出你可以查询的所有类型。助手从 schema://<kind> 资源读取相同的字节。参见 aggrega get-schema 参考。
  • 参考页面解释每个字段的含义以及字段之间的关系。实体页面位于 language-reference/entities/ 下——例如 component 或 aggregate。助手从 langref://entities/<kind> 资源读取相同的页面。

schema 告诉你什么在结构上有效;参考告诉你什么是合理的。阅读 schema 可避免在验证时被拒绝,阅读参考则可编写出符合你意图的内容。

3. 从骨架开始

从骨架开始比从空白文件开始更快,也更不容易出错。连接到 MCP 服务器的助手会使用类型和名称调用 scaffold 工具,获得一个最小的起点,其中包含该类型要求的所有字段,尚待提供值的地方使用占位符。手动编写时,aggrega scaffold <kind> <name> 会将同样的起点打印到标准输出,因此请将其重定向到文件中;或者复制最接近的示例,并删减到你需要的内容。

无论哪种方式,骨架都已以正确的结构包含必需的顶层字段(apiVersion、kind、metadata.name),这样你可以把注意力放在你的角色负责的字段上,而不是样板代码上。

4. 填写你的角色负责的字段

只填写你的角色负责的支柱,其余的留给它们的负责人。开发者提供应用意图和值;架构师声明契约——开发者可以提供的值、组件提供的输出、组件暴露的插槽;运维在不改变面向开发者的接口的情况下,将该契约映射到特定的 provider;运营者连接部署。按角色划分的实体针对每种类型详细说明了哪些支柱属于哪个角色。

将每个值保留在其负责人控制的支柱中,正是同一开发者意图能够在不同环境中面向不同基础设施、而开发者的文件无需改变的原因。这也是编写接口需要拆分的根本原因。

**将描述控制在几个简短的段落内。**实体的 metadata.description 是读者在选择它之前看到的文字:它作为可搜索的描述随实体一起发布,aggrega search 会将查询与之匹配。请为这一时刻编写,使用简短的段落——在折叠的 description: > 块中,空行开始新段落——说明该实体是什么、读者如何使用它、它在哪里实现以及它不做什么。读者在选择该实体前必须了解的限制也应简要写在这里。其他所有内容——某个默认值为何如此、某个设置在某个目标上的行为、某个值在各种实现下的含义——都写在它所解释的字段或块旁边的 YAML 注释中,使用该字段的人会在那里读到。编译器不会限制描述的长度,也不会根据其内容采取任何行动,因此保持简短是为了读者着想。

5. 验证,然后编译

在依赖文件之前先检查它:

  • 助手调用 validate 工具,该工具会内联报告 schema 和引用错误,以便助手在交回草稿之前进行修正。
  • 手动操作时,aggrega validate <file> 检查单个 Component、Feature、Recipe、FeatureRecipe、Workload 或 Plugin 文件,aggrega validate --release <release> 检查一个 Release 所涉及的一切,包括其 Aggregate 和 Manifest。aggrega lint 对目录实体运行发布规范规则,aggrega inspect 会解析并展示编译器看到的内容。当整个拓扑准备就绪后,aggrega pull --release <release> 解析其依赖并写入锁文件,然后 aggrega build --release <release> 将 Release 编译为按边界划分的产物——构建失败时会准确指出需要修复的内容。

尽早验证比后期构建失败代价更低。编写、验证、修正,然后再编译。

使用 AI 助手编写

aggrega mcp 命令运行一个 Model Context Protocol 服务器,可将任何支持 MCP 的客户端变成了解 Aggrega 的编写助手。连接后,助手可以:

  • 通过内置的编写提示词扮演角色——每个角色画像(开发者、架构师、运维)各一个,外加一个针对单个实体的专用模板。每个提示词都会设定角色,并引导助手参考 schema、参考页面和本指南,使其建议保持在该角色负责的支柱范围内。
  • 通过资源阅读参考:schema://<kind> 获取某类型的 JSON Schema,langref://<path> 获取任意参考页面,authoring://<topic> 获取本指南。
  • 通过工具操作你的工作区:scaffold 创建正确的骨架,validate 检查草稿,describe 查看目录实体,get-schema 按类型获取 schema。

助手读取的所有内容都由你的本机提供:schema 内置于二进制文件中,指南和参考页面来自保存在本机缓存中的文档包;服务器启动时若在缓存中找不到副本,会从 registry 获取该文档包。阅读页面、生成骨架和校验都不会访问网络;无法获取文档包时,schema 仍会提供,而页面则不会。要连接客户端,请参阅连接 MCP 服务器;你的助手可以用 Aggrega 做什么介绍了助手能使用的其余内容。有关该命令本身,请参见 aggrega mcp 参考。

后续步骤