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

语言参考

Aggrega 的“是什么”和“如何使用”:语法、CLI 调用、错误目录、完整示例。

初次学习时,请按顺序阅读下列各章。参考子目录列在其所属章节之下——查找某个特定的实体、关键字、provider、CLI 命令或错误时,可直接跳转。

在按顺序阅读各章之前,请先查阅语言状态,了解当前的就绪情况——哪些语言功能现已可用,哪些已被接受但编译器尚未对其执行处理,哪些计划在未来的迭代中提供。兼容性说明了一个版本对模式、命令行、助手工具、错误代码和插件工具包所作的承诺。

实体层级模型

Aggrega 的编写实体类型按采用进程分为三个层级(见下文)。与之并列的是平台拥有的 Workload,它本身不是一种编写类型——它是 Recipe 合成输入所采用的形态,通过 form: 词汇(stateless、stateful、daemon、scheduled、task、reference)表达计算形态。分层是一种文档和入门机制,而非运行时约束:每种实体类型都是语言的一等公民;编译器对它们一视同仁;开源的 Aggrega 支持所有层级,不设许可或功能门槛。层级标记用于导航,表示“高级;不需要可跳过”,而不代表能力。

层级实体类型何时采用
第 1 层——最小可用表面Aggregate, Component, Recipe, Manifest, Release第 1 天——独立创始人和小团队仅用第 1 层即可交付可运行的软件。心智模型:“我有一个应用;我想部署它;方法如下。”
第 2 层——角色分离Feature, FeatureRecipe, Plugin第 30 天——角色开始分工的小团队(开发 + 运维 + 有时还有安全)。第 2 层通过以下方式引入:用于 provider 渲染的 Plugins(运维在 Helm、helm-chart、Compose、Terraform 和 CloudFormation 之间选择)、Features(安全团队将凭据与应用配置分开管理),以及 FeatureRecipes(按 provider 进行绑定时定制)。
第 3 层——跨 Component 复用SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary第 365 天——常见形态在众多实体中反复出现的成熟目录。阈值并不正式:当某个形态(例如 PodResources)出现在 5 个以上的 Components 中、协调更新成为负担时,一个 SchemaLibrary 条目就有了存在的理由。

每一步进阶都是可选的。独立创始人永远不会被迫去看第 3 层;企业目录则可按需完全使用第 3 层。对于独立创始人的用例,第 1 层是完整的——开发者仅用第 1 层实体即可交付可运行的应用。这是一项重要的设计特性:第 1 层不是“能编译的子集”,而是“能交付软件的子集”。

由五个实体组成的第 1 层表面有一定的入门成本——Aggregate + Component + Recipe + Manifest + Release 比“放一个 YAML 文件,得到一个运行中的服务”更繁琐。这一成本是四域编写分离(开发者意图 / 平台目录 / 平台运维 / 路由)的代价,正是这种分离使 Aggrega 有别于直接使用 Helm 或 Terraform。第 1 层教程会明确地逐步讲解五实体的设置。

在第 3 层中,spec.templates / $instantiate: 机制(SchemaLibrary 中的参数化辅助)作为更高级的子功能单独记录。大多数第 3 层采用者起初不会用到 spec.templates;阈值是“当你的库中有 6 个以上的 schema 共享参数化结构时”。

阅读顺序

  1. 如何使用本参考
  2. 命名约定
  3. 实体参考概览
  4. 词汇概览
  5. 模板概览
  6. Providers 概览
  7. CLI 概览
  8. 错误概览
  9. 示例概览

Plugin 编写参考

Wasm 插件接口与章节序列并列,而不位于其中:插件作者可以独立于实体编写路径阅读它。plugin 实体页面介绍目录编写接口;以下页面介绍插槽、载荷以及作者工作流。

  • plugin-contract — 插件所挂接的插槽、它们在流水线中的位置,以及每个插槽的输入和输出结构。
  • plugin-developer-guide — 端到端的作者工作流:describe()、能力声明、运行时限制、publish/pull/build 生命周期、签名、版本管理。
  • policy-socket — 深入介绍治理插槽:它的四种角色、裁决严重级别、操作员输入通道,以及为编译器内置的任一引擎编写策略。
  • governance-attachment-facts — 治理策略从构建图中读取的每个挂接的事实,包括敏感性标记的三个单元,以及为什么缺少标记并不等于许可。
  • when-to-use-a-pipeline-step — 在流水线步骤与模板化的 FeatureRecipe 之间如何选择。
  • embedded-plugins — 随编译器二进制文件一同提供的插件。
  • tagging-plugins——两个无需策略即可写入标签的内置治理插件 governance/label-injector 和 governance/selector-tagger:它们的设置以及各自写入的内容。
  • core-importers — 编译器的十个导入器,从 Langflow、Flowise 和 n8n 到 Compose、MCP 以及各智能体框架:各自读取和起草的内容、它们的设置,以及它们随每个编译器版本的发布。
  • authoring-a-provider-walkthrough——编写 provider guest 的完整演练,从一个空目录一直到写出该 provider 所渲染文件的构建。
  • writing-a-governance-plugin——基于插件工具包的适配器骨架编写你自己的治理插件:一条规则、手动运行每个角色的导出、工作区目录中的一个 Plugin 实体,以及一次被它拒绝的构建。
  • compatibility — 插件工具包如何进行版本管理:工具包的补丁版本和次要版本可以更改什么,以及什么能让已构建的插件继续加载。