可扩展性
生态系统可扩展性与编译器护栏
1. 通用 WebAssembly (Wasm) 接口
为确保整个生态系统在架构上的对称性,Aggrega 采用一套标准化的执行契约,统一适用于编译器流水线中的每个 Wasm 插槽。
调用任何插件的 YAML 接口都依赖两个经过明确选择的关键字:function 和 with。
function: Aggrega 内嵌了一个 Wasm 运行时(基于 Wazero 引擎的 Extism 工具包),直接在内存中执行 Wasm,因此不会启动任何操作系统进程。function指定 Go 宿主调用的导出项:Wasm 模块显式导出的函数。with: 插件自身的输入,与 Developer 的values以及 Release 所满足的parameters相互分离。该关键字遵循 GitHub Actions 的约定(with:);当插件为其输入声明了 JSON Schema 时,宿主会在执行前依据该 schema 校验输入。
Wasm Plugins 的类型:
这一通用的 function 与 with 接口支持编译器中的每一个可编程插槽:
| Plugin 类型 | 运行位置 | 用途 | 预期输出 |
|---|---|---|---|
Provider (provider) | 渲染(生成) | 将最终的内存中 IR 转换为目标格式(Helm、Terraform、Compose)的实体字符串化文件。 | 字符串化文件的数组。 |
FeatureRecipe 流水线步骤 (pipeline-step) | Recipe 或 FeatureRecipe 的插件流水线 | 按顺序执行的步骤,用于获取密钥或向基础 AST 注入 sidecar。 | 针对键控文档集的 RFC 6902 patches,以及 side_effects(发出新文档或文件)、diagnostics 和供后续步骤读取的 outputs。步骤输入携带该键控文档集以及该步骤渲染后的 with 输入。 |
治理 (governance) | 注解展开之前、拓扑构建、静态分析或渲染阶段 | 承担构建流水线中的治理角色。在注解展开之前,它将注解注入已解析的组件;在拓扑构建时,它为节点自动打上合规或环境标签(两者均由运维人员选择启用)。在静态分析或渲染阶段,它充当显式护栏(Loud Guardrail):依据安全边界评估图的边、路径和标签,或评估渲染产物。决定它可以发出什么的是它所挂载的角色,而不是它的类型。 | 在注解展开之前,为注解注入。在拓扑构建时,为针对 metadata.labels 的 JSONPatch 数组。在静态分析或渲染阶段,为 halt、warn 或 info 严重级别的判定(Rego 策略将其收集在 deny、warn 和 audit 之下);halt 会中止构建。 |
Linter (linter) | 带外 | 可选的 FinOps 或规范性检查(例如基于 .infra 的云成本估算)以及发布时的规范约束。 | 警告字符串或致命中止。 |
CLI 扩展 (cli) | 运行时(aggrega <command>) | 由经过签名、沙箱化的插件提供的即插即用顶层命令,宿主中无需为每个命令编写 Go 代码。 | 流式输出的标准输出和标准错误,以及 guest 的退出码。 |
解析器 (parser) | 按需运行,在任何读取外部格式的地方 | 将外部源文本(HCL、TOML、YAML、JSON、带注释的 JSON)转换为规范的 JSON 树。 | tree 加 diagnostics,以及可选的源 spans。 |
导入器 (importer) | 按需运行,在任何构建之外(aggrega import、编辑器以及助手的 import 工具) | 将外部基础设施或智能体定义源(Langflow、Flowise、n8n、MCP 配置、Compose 应用、Dify 应用、CrewAI 项目中声明的智能体、LangGraph 应用的配置、Google ADK 应用的智能体配置、Agent Framework 声明式智能体)转换为 Aggrega 编写文件草稿,并以 import:<format> 能力声明其可处理的格式。 | Aggregate / Component / Release 实体草稿,或对其复用的目录 Components 的引用、其背后的映射决策、诊断信息,以及要写入的脚手架文件。 |
宿主运行时:一个拒绝授予能力的沙箱。 Aggrega 将 Wasm 宿主以运行在 Wazero 引擎之上的 Extism 工具包形式内嵌;宿主二进制保持纯 Go 实现,不依赖原生工具链,因此 aggrega 可以干净地交叉编译。每个插槽都运行在一道 AOT 纯净性防火墙之后:宿主拒绝授予插件任何运行时访问能力——没有网络、没有文件系统、没有挂钟时间、没有环境变量、没有标准 I/O——因此本会使用此类能力的调用会失败,而从宿主未提供的宿主接口导入的插件会在加载时被拒绝。无法访问网络或读取时钟的插件,就无法破坏编译器的预先(ahead-of-time)保证,即相同输入产生相同输出。对于需要少量无害启动导入的语言运行时,这些导入运行在拒绝能力的配置下:宿主固定可观察的挂钟时间,提供真实的熵,丢弃标准 I/O,且不授予文件系统、参数或环境变量访问——因此插件无法触及任何在不同构建间会变化的宿主能力。熵被有意保留为真实值而非固定值:固定熵会使 guest 语言运行时的内部哈希种子和 map 迭代顺序保持稳定,从而掩盖一个自身输出不可复现的插件,而不是让问题以不同输出的形式暴露出来。结果依赖于熵的插件属于编写层面的确定性问题,此配置的设计目的正是揭示它而不是掩盖它。
基于宿主编写:PDK。 插件作者无需手写 Wasm 内存 ABI。Aggrega 提供三种语言(Go、Rust 和 TypeScript)的插件开发工具包(Plugin Development Kit),这些轻量封装呈现每个插槽的类型化输入和输出,让作者只需编写普通函数。上文的 function / with 接口是 Aggregate 或 FeatureRecipe 用来调用插件的方式;PDK 则是插件作者构建时所依赖的工具。
各插槽在何处运行。 每个插槽都通过同一个宿主运行:发布 linter 在 aggrega lint 下运行;治理角色、渲染 provider 以及 Recipe 和 FeatureRecipe 的流水线步骤在 aggrega build 期间运行;解析器在读取外部格式的任何地方运行;导入器在 aggrega import 下运行;CLI 插件则作为顶级命令运行。各插槽的就绪情况参见语言状态。
哪些插件被锁定,哪些由你的环境选择。 Aggrega 按插件是否改变你交付的输出来划分插件。塑造输出的插件(渲染 Providers、以转换角色挂载的治理插件(label-transform、annotation-transform),以及 FeatureRecipe 和 Recipe 的流水线步骤)会在你执行 aggrega pull 时锁定在 release 锁文件中,并在 aggrega build 和 aggrega serve 时仅凭该锁文件逐字节一致地重现。有两类插件不被锁定,因为每次构建都从同一位置读取它们:由编译器二进制文件内部提供的渲染 provider,以及其 Plugin 实体编写在你自己某个目录目录中的 provider 或流水线步骤。要更改适用的塑造输出的插件,你需要重新 pull;pull 之后对工作区配置的更改在下一次 pull 之前不会改变构建的输出。门控插件(策略和 lint)只评判构建而不改变其字节,因此它们在 pull 时被缓存(这样构建仍可离线运行它们;编译器二进制文件自带的,或编写在你自己目录目录中的,则改为从那里读取),但不被锁定:运行哪个门控由你的环境在构建时选择,因此“开发宽松 / CI 严格”的划分只是普通的配置选择,而无需重新 pull,并且切换门控永远不会改变通过的构建所产出的输出。仅作用于编写输入的 Plugins(例如导入器和 CLI 扩展)不塑造任何构建输出,既不被锁定,也不属于构建的缓存集合。
2. FeatureRecipe Plugin 流水线
FeatureRecipes 将抽象的运维意图(例如挂载安全代理或注入 sidecar)绑定到带版本的 WebAssembly(Wasm)插件流水线。运维人员声明一个 Feature 在具体 provider 目标上所需的内容;编译器针对扁平的 IR 图执行所声明的流水线。
这种绑定为生态系统带来三个结果:
- 解耦演进。 基础设施词汇通过外部 Wasm 插件增长,无需发布 Aggrega 编译器的核心版本。新的 provider、新的 sidecar 和新的安全集成作为独立的 Wasm 二进制文件,基于稳定的 Wasm ABI 发布。
- 语义化版本。 FeatureRecipes 按版本引用 Wasm 插件——精确版本(
:1.0.0)或插入符范围(:^1.0.0,即与之兼容的最高版本)。使用插入符范围时,运维人员锁定一个主版本,同时在每次用aggrega pull --upgrade重新解析锁文件时获取其次版本和补丁版本。 - 转移复杂性。 厂商特定的 CRD 生成或复杂渲染(厂商特定的策略对象、provider 原生的路由资源)位于作用于扁平 IR 图的纯 Wasm 插件中,而不是贯穿于组件定义内部的 schema 声明或模板逻辑。
流水线链接——在插件之间分离关注点。 一个 FeatureRecipe 流水线可以按顺序链接多个 Wasm 插件,每个插件都从编译器接收相同的 IR 节点上下文。标准模式会拆分职责,使单个插件不会同时承担某个 feature 的语义意图和特定目标环境的物理流量拦截机制。
一个典型的双插件链如下:
- 一个配置插件,输出该 feature 的语义规则(安全策略规则、审计模式、限流阈值)。它理解 feature 的意图;它不理解目标环境的流量拦截结构。
- 一个路由插件,输出承载这些规则的物理网格配置(网关 CRD、sidecar 注入补丁、防火墙规则)。它理解目标环境的结构;它不理解 feature 的语义意图。
两个插件按顺序从编译器接收相同的 IR 节点上下文,因此它们可以干净地组合,彼此之间没有直接耦合。编译器编排流水线;插件承载领域知识。
3. 流量拦截:HTTPRoute 目标
Aggrega 的可扩展性模型以 Kubernetes Gateway API 的 HTTPRoute 标准作为网格级流量拦截的跨 provider 产物。标准库通过 core/http-route Feature 输出 HTTPRoute 对象,其 helm FeatureRecipe 为每个附加的组件渲染一条路由;使用 Gateway API 的目标环境会将 HTTPRoute 转换为其原生结构。
4. Plugin 自主性:标签解析
当 Wasm 插件从 IR 图生成物理资源时,SRE 需要将正在运行的 Kubernetes Pod 或云资源追溯到 Aggregate 中开发者的语义意图。Aggrega 的可扩展性模型将这种转换完全交由 Wasm 插件作者控制。
编译器将完整的 IR 图 labels 字典不加解释地传入 Wasm 沙箱。插件作者(即平台运维)从这里决定映射逻辑:原样传递所有标签,按特定领域前缀(*.aggrega.ai/*)过滤,或将图标签直接映射到原生 provider 标记 schema(把 IR 标签转换为 AWS tags、Kubernetes annotations 或某种云特定的元数据机制)。编译器对生成产物的标记方式不施加任何限制。
这种自主性将领域特定的智能——哪些标签对可观测性重要、哪些映射到原生标记约定、哪些属于平台内部——保留在 Wasm 插件层中,生态系统在这一层独立于 Go 编译器的发布节奏演进。
5. CLI 扩展:运行时命令
上述插槽运行于构建之内——编译器在解析、变更、验证和渲染 Aggregate 时调度它们。CLI 扩展插槽在性质上不同:它运行于终端,在任何构建之外,即操作员输入 aggrega <command> 时。aggrega 命令界面本身正是借此在无需核心版本发布的情况下扩展。
CLI 扩展是什么。 CLI 扩展是由经过签名、在沙箱中运行的 Wasm 插件提供的即插即用 aggrega <command>。它采取与渲染插槽相同的由 guest 负责的即插即用立场:领域逻辑完全位于 guest 中,Go 宿主不为任何命令提供代码。添加一个新的顶级命令只需要三样东西——一个 .wasm 二进制文件、一个声明 pluginType: cli 的 Plugin 实体(参见 Plugin),以及一次显式的 aggrega plugin add cli。宿主根据已安装插件的自我报告发现该命令;没有任何命令被编译进二进制文件。
为什么运行时插槽能做构建插槽做不到的事。 由于编译期插槽在构建期间运行,它们保持无权限且确定性:Aggrega 是一个预先(ahead-of-time)编译器,相同的输入必须始终产生相同的输出(参见架构不变量)。因此,渲染或策略插件无法访问网络、读取时钟或向终端流式输出——任何随运行而变化的东西都会破坏这一保证。CLI 扩展运行于该边界之后和之外,由提示符前的人而非确定性流水线驱动。这正是 CLI 插件可以在运行时流式输出标准输出和标准错误并返回进程退出码的原因:不存在任何其逐字节稳定性可能受这些效果威胁的构建产物。
安装、运行和发现。 aggrega plugin add cli <query> 在已配置的注册表中搜索匹配的 cli 插件,根据注册表的信任策略对其进行验证,并将其安装为顶级命令——会先打印插件声明的能力,让操作员在命令落地前确认它被允许做什么。安装后,aggrega <command> 会像任何内置命令一样运行它。CLI 插件在其 describe() 自我报告中声明自己的命令及其标志,宿主在 aggrega help <command> 中渲染每个命令的标志,方式与内置命令完全相同,因此操作员以同样的方式发现已安装命令的 --flags。要查找可安装的命令和目录内容,aggrega search 会查询已配置注册表的本地索引——--kind plugin --plugin-type cli 将结果缩小到可安装的 CLI 插件,未过滤的搜索则涵盖目录实体;aggrega plugin list 显示已安装的内容。各命令的标志和输出形式见这些参考页面。
能力模型。 CLI 扩展从一个固定的基线开始,每个命令无需声明、无需提示即可获得该基线:
| 基线能力 | 授予 |
|---|---|
| 传入命令行参数 | 始终 |
| 流式输出的标准输出和标准错误 | 始终 |
| 传出进程退出码 | 始终 |
基线之外的任何能力默认关闭。需要更多能力的插件须显式声明每项额外能力,宿主仅在安装时展示并经操作员确认后才授予。在基线之外新增的能力类别——环境、文件系统或网络访问、交互式输入——都位于相同的“声明并确认”关卡之后授予,因此命令永远不会悄然获得操作员未批准的权限范围。
内置命令始终优先。 已安装的插件永远不能遮蔽内置命令。由拒绝列表支撑的保留名称防护保护内置命令以及一组为内置命令保留的名称,冲突会在安装时被拒绝,而不会被允许覆盖核心行为。无论在其上安装了什么,操作员所依赖的命令界面都保持稳定。
6. Parser Plugins:读取外部格式
编译器经常需要读取以非自身编写的格式书写的文本——HCL 格式的 Terraform 模块、TOML 格式的配置文件、YAML 或 JSON 格式的清单。解析器插槽提供这种读取能力,而无需让编译器核心学习任何特定格式。解析器是一个无状态插件,它将外部源文本转换为结构化的 JSON 树:把 HCL 文件的字节交给它,它就以 JSON 对象返回相同的内容,而流水线的其余部分已经知道如何遍历这种对象。编译器中任何需要读取非原生解析格式的部分,都会请求一棵解析后的树,并以此为基础工作。
格式是一种能力,而不是编译器功能。 解析器将其处理的格式作为能力进行通告——parse:hcl、parse:toml 等——宿主按所请求的格式解析出解析器,运行它,并将树交回。这与渲染提供方和 CLI 插件所采用的即插即用、能力通告模型相同:编译器核心不持有内置格式列表,因此添加一种格式就是发布一个新的解析器插件,而绝不是核心版本发布。HCL、TOML、YAML、JSON 以及带注释的 JSON 的解析器作为入门集随二进制文件一起提供;需要其他格式的企业可以发布一个通告该格式的解析器插件。
格式选择是声明式的,从不猜测。 宿主从不检查文件内容来判断其类型。它按照固定的优先顺序,通过声明的信号选择格式。渲染提供方可以声明其输出的每个文件的格式,宿主会直接优先采用这一由生产方声明的格式——写下这些字节的提供方就是如何读取它们的权威。对于生产方未标记的文件,回退方案是一个固定的文件扩展名映射——.tf 选择 HCL,.toml 选择 TOML,.yaml 选择 YAML,.json 选择 JSON。按声明的格式或固定扩展名进行选择,使解析保持确定性和可读性:相同的输入始终路由到相同的解析器,操作员无需了解文件内部的字节即可知道将运行哪个解析器。内容嗅探会使选择取决于负载内容,Aggrega 不这样做。
解析器是纯语法层面的。 输出是一棵 JSON 树加上诊断信息,以及可选的每个节点的源位置。解析器不携带任何 Aggrega 语义——它报告文本在结构上说了什么,而不涉及它作为 Component、Recipe 或任何其他实体意味着什么。将解析后的树转换为 Aggrega 实体是另一个独立的关注点,位于别处;解析器的唯一职责是忠实地将语法转换为 JSON。读取方向本着同样的精神是单向的:解析器将格式读入树,而不会把格式写回。
一个使用方:针对 Terraform HCL 的策略。 需要检查构建所产生的 Terraform 的渲染阶段策略,自身无需学习 HCL。宿主通过解析器插槽解析 HCL 产物,并将策略插件已能读取的 JSON 树交给它,使策略在与其他所有插槽相同形式的结构化数据上进行推理。外部格式的新读取者也以同样的方式组合——向宿主请求树,然后在 JSON 中工作——因此编译器理解格式的能力通过添加解析器插件来增长,而不是通过扩充核心。
7. Importer Plugins:从外部来源起草编写文件
团队很少从零开始。其智能体架构往往已存在于别处——一个 Langflow 或 Flowise 流程、一个 n8n 工作流、一个 Dify 应用、某个客户端所配置的 MCP 服务器、一个 Compose 应用、某个框架配置所声明的智能体。导入器插槽将这类外部来源转化为 Aggrega 编写的起点:它读取来源并生成初稿 Aggregate 和 Component 实体,并且根据 MCP 配置、Compose 应用或框架声明的配置生成一份草稿 Release,供作者审阅和完善,从而让团队把已有的内容延续到 Aggrega 中,而不必手工重新编写。导入器映射的是含义——它读取来源节点是什么,并提出代表它的 Aggrega 实体,或将其留在草稿平台所承载的流程之中;编译器不透明地传递所输出的实体,正如它与任何插件产出的内容无关。
格式是一种能力,而非编译器特性。 导入器将其处理的格式作为能力进行声明——import:langflow、import:flowise、import:n8n、import:mcp、import:compose、import:dify、import:crewai、import:langgraph、import:google-adk、import:agent-framework 等——宿主按请求的格式解析出导入器,运行它,并取回它起草的实体。这与解析器插槽通过 parse:<format> 采用的模型相同,即即插即用、按能力声明:编译器核心不持有内置的可导入格式列表,因此支持一种新格式只需发布一个声明该格式的导入器插件,而无需发布核心版本。
导入器通过解析器插槽读取,而不重新解析。 导入器需要其来源的结构化形态,但不会重新实现对生态已能解析的格式的读取。需要语法树时,它请求宿主运行匹配的解析器——即工作区目录为该来源语法提供的解析器,若目录未提供,则为编译器自带的解析器——通过管道其余部分所用的同一宿主中介解析能力完成,并基于返回的 JSON 树工作。读取(语法到树)仍是解析器的职责;映射(树到 Aggrega 实体)是导入器的职责。两个插槽相互组合而不重复:导入器为某个来源添加映射逻辑,并依靠现有解析器处理字节。
格式依据其导入器的声明来识别,绝不猜测。 导入时可以直接指定来源格式。未指定时,格式依据各导入器在其自报信息中声明、并由其 Plugin 实体记录的签名来识别:来源所用的语法、签名适用的文件名,以及解析树必须或不得包含的路径。宿主自身不认识任何格式。它针对签名所指的每种语法,通过工作区目录提供的解析器(若目录未提供,则用编译器自带的解析器)解析来源,在返回的树上求值所声明的谓词,并将来源视为签名匹配的那唯一一个导入器的格式。声明的签名取代了解析器插槽中固定文件扩展名映射的位置,因为导入所读取的格式可能共用扩展名——Langflow 导出文件、Flowise 导出文件和 n8n 工作流都是 JSON 文件。没有任何签名匹配的来源会被拒绝,并要求指定格式、列出各导入器声明的格式——若来源是文件夹,则要求单独指定其中一个文件,或指定一个其导入器声明了文件模式的格式,并只列出这些格式;被多个格式的签名同时匹配的来源也会被拒绝,并列出这些格式。识别过程只读取来源,不访问任何网络,因此识别一种新格式只是新导入器附带的一项声明,而无需修改宿主。编写签名的规则见导入器插槽。
目录通过其导入器声明的文件来读取。 来源是一个文件或一个目录。文件会整体交给导入器。目录会被读取为若干具名来源——恰好是导入器签名的文件模式所选中的那些文件,每个以其在目录内的路径命名,按排序顺序排列——目录中的其他文件不会被打开;会使读取越出目录的链接在读取任何内容之前即被拒绝。未声明文件模式的导入器只读取单个文件并拒绝目录;不含任何被导入器模式选中文件的目录同样会被拒绝。编译器自带的 Langflow、Flowise、n8n、Dify 和 Agent Framework 导入器均未声明文件模式,因此每个只读取一个导出的流程、工作流或应用文件,或一个声明式智能体;其 MCP 导入器声明了它所读取的 MCP 客户端配置的文件名,因此项目目录通过其中的配置来读取;其 Compose 导入器声明了 Compose 默认读取的文件名,因此项目目录通过其 Compose 文件以及 Compose 合并于其上的覆盖文件来读取;其 CrewAI 导入器声明了 CrewAI 项目声明智能体和任务所用的文件名,因此项目目录通过这些声明来读取,其程序从不被读取;其 LangGraph 导入器声明了 langgraph.json,因此应用目录仅通过其配置来读取,其代码和环境文件从不被读取,配置所指定的环境文件只有在其挂载的 with.sources 交付时才会到达导入器,且仅用于变量名;其 Google ADK 导入器声明了 root_agent.yaml,因此应用目录仅通过其根智能体的配置来读取,其子智能体所指定的配置只有在其挂载的 with.sources 交付时才会到达导入器,其代码和环境文件均从不被读取。
映射是确定性的、带置信度评分的,并以你自己的目录为依据进行权衡。 宿主向导入器提供工作区自身目录所含 Components 的视图——即选出该导入器的那个目录——工作区的目录文件夹,或在工作区未指定任何目录文件夹时,其默认 registry 发布的目录快照——企业目录的 Components 与标准库的待遇完全相同。该视图包含每个 Component 的名称、版本和标签、其 values 和 provides 所声明的键名,以及其插槽的选择器,但绝不包含值、默认值或密钥;除该快照外,不会为此获取任何内容,且其顺序固定,因此一个目录只产生一个视图。基于 Go PDK 导入器包构建的导入器——包括编译器自带的 Langflow、Flowise、n8n 和 Compose 导入器——仅以这些 Components 为依据权衡来源中的每个节点,采用确定性的、不依赖模型的置信度模型,并将决策——它权衡过的候选项、它判定的匹配等级以及它所做的选择——记录为作者可阅读和修改的可审阅提示。目录新增的 Component 在下次导入时即成为候选项,无需重新构建任何导入器。默认只给出提示:导入负责提议,作者负责决定。高置信度的匹配可以写成对现有目录组件的引用,而不是新起草的主体,但仅在操作员选择启用时——且始终是由作者把关的、明确且可撤销的建议,绝不是静默改写。由于评分不涉及模型和运行时查找,同一来源针对同一目录评分,总是产生相同的提示。
flow 被起草为运行它的平台。 Langflow flow、Flowise chatflow 和 n8n workflow 都运行在某个平台上,默认情况下,导入起草的是该平台,而不是 flow 的节点:标准库平台 Component 的一个实例——core/ai-agent/langflow、core/ai-agent/flowise 或 core/ai-agent/n8n——在其 flow_definition 值中按导出时的原样携带该 flow,平台在部署时加载它。flow 中由平台某个插槽接收的每个部分——在标准库的平台上,即模型、MCP 服务器或其他通过 HTTP 访问的工具,以及向量存储——都成为一个独立的 Component,按映射的决定被引用或起草,并在平台的 uses 下连接到该插槽。因此,flow 对模型、工具或存储的每次调用都是该 Aggregate 声明的一个连接:评判该图的治理插件会像看待其他任何边一样看到它;而标准库的出口允许列表由 attach_egress_allowlist 设置附加到平台上,只允许平台连接到其连接所达之处、它自己的 pod 以及集群的 DNS。在格式允许的情况下,草稿会在所携带的 flow 中写入使 flow 通过相应连接到达各部分的内容。其他所有节点——agent、chain、trigger——都留在所携带的 flow 中,不成为 Component,其决策记录了与之比较过的候选项。Dify 应用也以同样方式起草,采用整个安装的形式:标准库组装的 Dify 安装 core/dify 中的一个条目,在其 app_definition 参数中携带该应用,由安装自行连接其连接。导入器附加项的 layout 设置选择草稿形式:默认的 platform,或 nodes——后者将源中的每个节点起草为独立的 Component,flow 的每条边成为一个 uses 连接,且不携带 flow。携带 flow 的平台说明了哪些节点成为部分以及各自连接到何处。
代码优先的框架通过其声明的配置读取,绝不读取其程序。 CrewAI、LangGraph、Google ADK 和 Agent Framework 将应用的行为保存在程序中,并在旁边的配置中声明其 agent、图和模型。它们的导入器只读取这些声明——CrewAI 项目的 agent 和 task 文件、LangGraph 应用的 langgraph.json、Google ADK 应用的 agent 配置、Agent Framework 声明式 agent——并围绕一个它们从不打开的程序起草该框架的标准库 agent,连接到声明所指定的内容:agent 请求的模型(在 agent 的 model 插槽接受该模型的情况下),以及 LangGraph checkpointer 保存状态的数据存储。Agent Framework agent 指定的 MCP 服务器由模型提供方作为托管工具访问,因此草稿在注释中列出它,而不为其连接任何内容。程序运行在 Release 指定的镜像中。只有程序才表达的内容——task 的逻辑、代码定义的工具、代码构建的 agent——会在草稿的注释和决策中列出,不成为 Component;将其写入编写文件是作者的工作,可以手动完成,也可以借助代表作者编写的 AI 助手通过 aggrega mcp 完成,它会读取参考文档并搭建和验证实体。
源中关于其各部分如何运行的陈述会落入草稿 Release。 运行输入由 Release 提供,因此 MCP、Compose、CrewAI、LangGraph、Google ADK 和 Agent Framework 导入器会在 Aggregate 旁起草一个 Release,其 spec.aggregate 指向该 Aggregate:Release 携带源所陈述的内容——服务器的命令行或地址、通用服务器的镜像和端口、模型的端点——并在每个条目上方的注释中写出源陈述了、但起草的 Component 没有任何键接收的内容,例如服务的卷或配置的环境。任何源都未陈述的内容——运行框架程序的镜像、连接出示的凭据、Release 的 metadata.environment 和 spec.manifest——会在相应位置的注释中列出,由运维人员提供;构建会停止,并指出镜像、环境和 manifest 中仍未设置的那些。平台草稿不写入 Release:平台实例上方的注释列出 Release 需提供的内容——平台自身的输入,例如它运行的镜像或其所有者账户、每个已连接 MCP 服务器的地址,以及每个连接出示的凭据。
源中持有的凭据值按原样携带,除非要求移除。 导入器会定位源中每个可能携带凭据的值,每个值属于一个类别:格式标记为凭据的内容、MCP 服务器配置的成员,或格式标记为非凭据但仍可能携带凭据的输入,例如请求的标头。默认情况下不会写为空:每个有内容的值都按原样携带——在平台携带的 flow 或应用中,或在草稿 Release 中——并在 credential-carried 警告中按其所在位置列出——其节点、服务器、服务或 agent,以及其字段——绝不列出其值,同时给出将其写为空的设置值。empty_credentials 设置按类别开启移除:marked 将格式标记为凭据的内容以及 MCP 服务器配置的每个成员写为空,all 还会将标记为非凭据的输入写为空,每个被写为空的值都以 credential-emptied 报告。草稿为使 flow 到达其连接而写入的内容属于连接配置,无论设置如何都会写入;草稿中的连接不携带凭据:由 Release 附加每个连接出示的凭据。源仅指向的文件,例如环境文件,只在被读取时读取其变量名;逐节点生成的草稿不读取任何值。导入器定位范围之外的内容——自定义组件的代码、提示词——需由作者在分享草稿前审查,详见flow 持有的凭据值。
命令、编辑器和助手执行的是同一个导入。aggrega import <file or directory> 在终端中执行导入;编辑器通过其会话的 aggrega/import 请求执行同一操作,AI 助手则通过 aggrega mcp 的 import 工具执行。三者以相同方式选择导入器,范围是工作区目录中的导入器以及编译器的核心导入器:若某个 plugins.importer 附加项指定了一个声明支持该格式的导入器,就选它;否则选择唯一声明支持该格式的导入器的最高版本——若同一格式有两个不同名称的导入器且都未被附加,导入将停止并列出两者,详见哪个导入器把源转换为草稿。三者都会在草稿旁报告映射决策。命令在标准错误输出上为每个已映射节点打印一行,列出为其选择的 Component 或草稿、它是被引用还是被起草、匹配层级,以及在导入器权衡过候选项时最佳候选项的得分;编辑器显示相同的行,编辑器会话的结果和助手的回答则完整携带每项决策。因此,无论在哪个界面执行导入,作者无需打开草稿即可看到导入在哪里做了猜测。--format 显式指定源格式——例如 langflow、flowise、n8n、mcp、compose、dify、crewai、langgraph、google-adk 或 agent-framework——以代替自动识别。命令将导入生成的实体和任何脚手架文件写入工作区根目录下,或写入 --output-dir 指定的目录下;--dry-run 执行命令的全部操作但不写入,而是将起草的文件作为内容返回并注明每个文件的目标路径,使作者能在向工作树提交任何内容之前审阅脚手架。
**核心导入器。**编译器自带的核心导入器读取以下格式,每种格式一个导入器:
- Langflow —— 从 Langflow 导出的流,起草为标准库中携带该流的 Langflow 平台,流中由某个插槽接收的每个部分都连接到该插槽。
- Flowise —— 从 Flowise 导出的 chatflow 或 agentflow,起草为标准库中携带它的 Flowise 平台,其中由某个插槽接收的每个部分都连接到该插槽。
- n8n —— 从 n8n 导出的工作流,起草为标准库中携带它的 n8n 平台,其中由某个插槽接收的每个部分都连接到该插槽。
- Dify —— 从 Dify 导出的应用,起草为标准库组装的、携带该应用的 Dify 安装,其指定的模型、工具和知识库报告为在 Dify 内部配置。
- MCP —— MCP 客户端的配置或 MCP 注册表服务器描述,每个服务器起草为标准库 MCP 工具的一个实例,并附带一个携带每个服务器命令行、地址或镜像的
Release。 - Compose —— 一种基础设施格式,Compose 应用的每个服务起草为其镜像所匹配的目录 Component——通过导入器携带的一张表进行匹配,该表在构建导入器时由标准目录的 Compose Recipes 和 Components 生成——或起草为运行其镜像的通用服务器,并附带一个
Release,携带每个通用服务器的镜像和端口,并在注释中列出每个服务声明的端口、卷和环境。 - CrewAI —— CrewAI 项目在其配置文件中声明的智能体,每个起草为标准库的 CrewAI 智能体,携带其角色、目标和背景故事,并连接到其指定的模型;项目的任务和工具报告为属于其程序,程序本身从不读取;并附带一个
Release,将运行程序的镜像留给运维人员指定。 - LangGraph —— LangGraph 应用的配置所声明的图,每个起草为标准库的 LangGraph 智能体,携带其图的导入路径,并连接到其 checkpointer 保存状态的数据存储;附带一个
Release,在注释中说明配置声明的环境;图的代码从不读取。 - Google ADK —— Google ADK 应用的智能体配置所声明的智能体树,每个起草为标准库的 ADK 智能体;若 ADK 将其指定模型的请求发送到 Gemini API,则连接到该模型,而以其他任何方式访问的模型(例如通过 LiteLLM 模型字符串)会在注释中列出,其连接留给作者;附带一个
Release,将运行该应用的镜像留给运维人员指定;应用的代码从不读取。 - Agent Framework —— 一个 Agent Framework 声明式智能体,起草为标准库的 Agent Framework 智能体,连接到其指定的 OpenAI 模型;它指定的每个 MCP 服务器都写在注释中,因为模型的提供方将其作为托管工具访问;附带一个携带模型端点、并在注释中写明每个服务器地址的
Release;应用的代码从不读取。
它们与其他导入器插件无异——特定于格式的映射逻辑位于其中,而不在核心中——由编译器源码构建,并随每个编译器版本以该版本号发布。它们都不编译进二进制文件:二进制文件携带每个导入器的 Plugin 实体及其所接受的唯一模块的摘要,因此每个导入器无需目录条目即可在每个工作区中服务其格式。首次需要本机尚未持有的导入器时,导入会从工作区的默认注册表获取它,将其锁定到该摘要,像 pull 验证所获取的插件那样验证它——依据该注册表的信任策略验证其签名,并检查其使用的宿主函数——然后将其保存在工作区的内容缓存中;之后的每次导入都从缓存读取它,无需为它访问网络。导入不固定任何导入器:不会为它写入其他任何东西——没有锁文件条目,也没有受信任插件记录——pull 不会缓存它,构建也不会读取它。未通过验证的模块会被拒绝,且不保存任何内容。若无法获取模块——工作区处于离线状态、无法访问其注册表,或注册表中没有该模块——导入将停止,并列出导入器、其版本以及如何将其模块放到本机上。选择权仍在工作区:其目录中以其他名称为这些格式之一持有的导入器,在某个 plugins.importer 附加项指定它时运行;与核心导入器同名同版本的导入器则代替核心导入器运行。
初建与扩充目录
目录不必从零开始构建。为新环境初建 Recipes 和插件,大部分工作是搭建脚手架和复用,而不是 手工编写每一个二进制文件。
将外部来源导入为草稿编写文件。 aggrega import <file or directory> 读取一个声明式智能体定义来源——Langflow 或 Flowise 流程、n8n 工作流、MCP 客户端的配置或注册表服务器描述——、Compose 应用、Dify 应用、CrewAI 项目声明的智能体、LangGraph 应用配置声明的图、Google ADK 应用的智能体配置声明的智能体,或 Agent Framework 声明式智能体,并生成初稿 Aggregate 和 Component YAML;对于 MCP、Compose、CrewAI、LangGraph、Google ADK 或 Agent Framework 来源,还会生成一份草稿 Release,供作者审阅并完成,使团队能够沿用已有的内容,而不必手工重新编写。对于流程的每个节点以及 Compose 应用的每个服务,它会对工作区自身目录中的 Components 打分——企业目录与标准库同等对待——使用一个确定性的、不依赖模型的置信度模型,并将决策——它权衡过的候选项、它分配的等级以及它做出的选择——记录为可审阅的提示,命令、编辑器和助手都会报告这些提示;当操作者选择启用时,高置信度匹配可以写为目录引用,但始终是一个由作者把关的、显式且可撤销的建议,而不是静默改写。目录新增的每个 Component 都是下一次导入要权衡的候选项。特定于格式的映射智能位于导入器插件中:编译器自带的 Langflow、Flowise、n8n、MCP、Compose、Dify、CrewAI、LangGraph、Google ADK 和 Agent Framework 导入器在每个工作区中服务这些格式,在首次使用时获取并验证;目录通过持有一个声明支持某格式的导入器插件来新增该格式。目录来源通过其导入器声明的文件模式读取;Langflow、Flowise、n8n、Dify 和 Agent Framework 导入器不声明任何模式,各自读取一个导出文件或声明式智能体;而 MCP 导入器读取目录中的客户端配置,Compose 导入器读取其中的 Compose 文件,并按 Compose 的方式合并,CrewAI 导入器读取项目的声明,从不读取其程序,LangGraph 导入器读取应用的配置,从不读取其代码或环境文件——只有当其挂接把该文件交给它时,才会读取其中的名称——Google ADK 导入器读取应用的根智能体配置,从不读取其代码或其环境文件,子智能体的配置在其挂接交给它时读取——ADK 声明这种配置是实验性的,其智能体默认使用 Gemini 模型,并通过 ADK 自有的类按名称访问其他提供方的模型,或通过 LiteLLM 模型字符串访问。
大部分插件工作是模板,而不是编译代码。 很大一部分特性只是注入一个静态 sidecar、环境变量或标签——即一个不含条件逻辑的普通 JSONPatch。一个可配置的 patcher 插件,只需编写一次、以声明式 JSONPatch 模板作为其 with 输入,就能覆盖这种常见情况,而无需为每个特性编译一个独立的二进制文件:作者编写一个模板;对于许多 CRD 风格的目标,一个 valuesMapping 模板(通常引用某个 MappingLibrary 条目中的共享片段)本身就足够。专门编写的 PDK 插件用于真正需要条件逻辑的其余情况。
参考成熟的工具。 编写新的插件逻辑时,作者可以 查阅成熟开源工具公开记录的输出形态—— 这些工具已知会生成的 CRD、补丁或模板的结构—— 作为新插件必须生成的目标形态的参考,同时遵守 每个项目的许可证。Sidecar 注入 webhook、更高层的构造 库、operator CRD 生成器以及 trait 或组合目录都公开了 与同类 FeatureRecipe 或插件需要生成的内容高度对应的 输出结构。目标是匹配一个易于理解的输出契约,而不是复制 任何项目的实现。