导入
aggrega import 读取以另一种格式编写的项目——从 Langflow 导出的流程、MCP 客户端的配置、Compose 文件,以及下面列出的其他格式——并据此写出 Aggrega 文件:一个 Aggregate、一个 Release,以及针对 --target 所指定目标的一个 Manifest。只要回答了任何来源都无法包含的少数几个值,它们合起来就是一个按原样即可通过验证并完成构建的工作区:导入会对其中每个值只询问一次,并把答案保存在答案文件中。它不部署任何东西,也不连接任何集群或云账户。草稿是你工作区中的普通文件,接下来如何处理它们由你决定。
- LangGraph
- CrewAI
- n8n
- Dify
- Langflow
- Flowise
- Google ADK
- Microsoft Agent Framework
- MCP client configurations
- Compose
aggrega importAggrega 草稿文件
供你审阅和编辑
输入你现有的项目,输出 Aggrega 草稿文件。不会部署任何东西;你先审阅草稿。
它为你提供什么
- 你的项目无需手工重写即可进入 Aggrega。 起草出的 Aggregate、Release 和 Manifest 与你自己编写的文件属于同一类。它们按原样即可针对导入所指定的目标进行构建,而你的工作区所附加的每条治理策略都会像对待其他构建一样评判该构建。
- 来源所陈述的内容会被沿用。 若目录中有与某个节点或服务强匹配的条目,该节点或服务就会引用那个目录 Component,并带上来源为其提供的值,例如流程所指定的模型。来源所运行的平台会以目录中针对该平台的 Recipes 所运行的镜像来起草。密钥会被起草为指向其来源位置的引用,而绝不是其值。
- 只会就任何来源都无法包含的内容询问你,且只问一次。答案保存在来源旁边的答案文件中,因此下次导入同一来源时不会再询问任何内容。
- 草稿归你所有。 它们是你工作区中的普通 YAML,不会留下任何构建所依赖的东西。你可以编辑、重命名并提交它们。
- 草稿可以跟随其来源。
aggrega import --sync会根据已更改的来源更新先前一次导入的草稿,只更改导入所写的内容。如果来源更改了你编辑过的部分,它会停下并指出该部分,而不会覆盖你的编辑。
它不做什么
导入会起草来源所陈述的内容以及你的目录所决定的内容,其余的则会询问。每份草稿都会在值旁边的注释中说明其起草的值来自何处。
- 它不会猜测你的来源无法陈述的内容。 没有任何来源会指定 Release 部署到的环境,因此起草的 Release 指定
development,并附有注释说明这是一个需要更改的默认值。目录要求而任何来源都不包含的值——所有者账户的电子邮件、由你自己的代码构建的应用程序镜像、Kubernetes Secret 的名称——会被起草为空并加以询问,如下文导入如何运行所述。 - 它不读取代码。 流程或项目自身的程序不会被读取:CrewAI crew 的程序、LangGraph 应用的图代码,以及 Langflow 组件的源代码——除了将其随流程一起携带之外。
- 它不评判值的含义。 每个节点或服务都会与你工作区目录中的 Components 进行比对——比对它们的名称、类别、标签以及它们所声明的值的名称。高档位的匹配会在草稿中被引用;较弱的匹配则写成注释,注明该 Component 及其分数,由你来选择。
- 它不会为了跟随来源而更改平台所运行的版本。 平台的镜像会按已知目录中针对该平台的 Recipes 可运行的版本起草;若来源指定了其他版本,镜像旁边的注释会注明该版本。
- 它不会替你把凭据从来源中移出。 默认情况下,可能携带密钥的值——环境值、请求头、MCP 服务器的命令行——会按原样带入草稿,导入会在
credential-carried警告中逐一指出它们,但从不写出其值。导入器的empty_credentials设置会改为将它们写为空(设置)。在分享草稿之前,请阅读这些警告。 - 它不部署或运行任何东西。 它读取来源和你的目录,并写出文件。构建草稿以及运行构建所写出的内容,是你另行执行的步骤。
导入如何运行
你可以使用下面的命令运行导入,也可以让你的 AI 助手替你运行。
-
从工作区开始。 导入会将草稿写入其运行所在工作区的根目录之下——即包含带有
workspace键的.aggrega-config.yaml的文件夹——或写入--output-dir指定的目录之下。它从不覆盖已存在的 Aggregate。 -
用于比对的目录。 导入只将你的来源与工作区目录中的 Components 进行评分比对,此外别无其他。如果工作区没有指定自己的目录文件夹,该目录就是标准库目录,从工作区的默认注册表读取:目录的每次发布都会发布整个目录的一个签名快照,第一次导入会获取该快照、验证其签名、将其保存在工作区的内容缓存中,并在它写在草稿旁的记录中以摘要指明该快照,因此之后对同一批草稿的导入会读取同一个目录,而无需再次询问注册表。基于该目录,PostgreSQL 服务会被匹配到
core/datastore/postgres,并且--target会根据该目录的 Recipes 起草一个 Manifest。如果没有目录,导入就没有可匹配的对象,--target也会被拒绝,因为没有 Recipe 绑定到该目标。指定了自己的目录文件夹的工作区则改为与这些文件夹比对导入,且不获取任何快照:即
workspace.catalog_dirs列出的目录、工作区根目录下的catalog文件夹,或AGGREGA_CATALOG_DIRS指定的目录。对于希望以文件夹形式获得标准库目录自身文件的工作区,这些文件就是aggrega-hub仓库的aggrega-catalog文件夹,https://github.com/aggrega-ai/aggrega-hub。--upgrade会获取注册表发布的最新快照,并从此以它为准进行导入;在--offline下,需要获取快照的导入会停止,并指出应运行什么。 -
运行导入。 指定文件或目录:
Terminal window aggrega import compose.yaml --target compose格式根据文件的名称和内容识别;无法识别时,由
--format指定。--target指定一种提供程序能力,例如compose或helm,并起草一个 Manifest,将草稿所需的每种组件类型和功能类型映射到你的目录为其提供的该能力的 Recipe:只有一个时就是那一个,有多个时则是以该类型命名的那一个。起草的 Release 会指明该 Manifest,草稿所含的内容随目标而定:在compose上,密钥是 Docker Compose 从你的 shell 填充的变量引用;在helm上,则是 Kubernetes Secret 的名称。导入会在标准错误上指出它读取的格式、每条警告,以及它映射的每个节点各一行;在标准输出上列出它写出的文件。 -
回答任何来源都不包含的内容。 目录要求但任何来源都无法包含的值——所有者账户的电子邮件、由你自己的代码构建的应用程序的镜像、Kubernetes Secret 的名称——只需回答一次。导入从来源旁边的
import-answers.yaml读取答案,或从--answers指定的文件读取;在终端中,它会逐个询问仍然缺少的每个值,并将你的答案写入该文件。密钥的回答是它的来源——一个变量或一个 Secret 的名称——而绝不是它的值。在无法提问的地方——持续集成中、通过管道、来自助手或编辑器——导入会写出答案文件,其中包含每个缺失值的键和一个空答案,列出它们,并以状态 1 退出;填写它们后再次运行导入。一个答案文件服务于所有目标:某个目标的草稿不需要的答案会保留在文件中,不被使用。导入答案文件完整描述了该文件。 -
导入会拉取构建所需的内容。 一旦不再缺少任何内容,导入就会像
aggrega pull那样拉取起草的 Release 的依赖项,并在其旁边写出release.lock。在--offline下,它不拉取任何内容,并指出要运行的aggrega pull命令。 -
验证并构建。 在包含草稿的文件夹中:
Terminal window aggrega validate --release release.yamlaggrega build --release release.yaml两者都通过后,构建已将目标的文件写入
dist/下。拒绝会在你需要修改的文档中指出要修改什么以及在哪里修改。 -
运行构建写出的内容。 面向 Docker Compose 的构建会写出
dist/compose/docker-compose.yaml,而该文件没有指定 Compose 项目名,因此请用-p指定一个:Terminal window docker compose -p <name> -f dist/compose/docker-compose.yaml up -d如果不使用
-p,Docker Compose 会以存放该文件的文件夹compose为项目命名,因此以这种方式启动的两个工作区会共用一个项目。各服务位于同一个网络中,Docker Compose 以项目为该网络命名,即<name>_compose。构建未为其发布端口的服务,可以从该网络内部访问,使用docker compose -p <name> -f dist/compose/docker-compose.yaml exec <service> …,也可以从你在该网络上启动的容器中访问,使用docker run --network <name>_compose …。演练中的“运行”和“测试”两节会给出其自身构建的命令。当一次运行的
core/ai-model/openai模型指向同一项目中由 Ollama 提供的一个小模型时,该运行无需 OpenAI 密钥即可给出回答,为此需要对起草的文件做三处修改,使用--auto-pull进行一次构建(它会拉取所添加组件需要的内容),并在栈运行起来后执行一条命令:- 在 Aggregate 中,再加一个不连接任何对象的组件:
local-model,类型为core/ai-model/ollama,其values中设置model: qwen2.5:0.5b; - 在 Manifest 中,加入它的 Compose Recipe:
core/ai-model/ollama: compose/ollama; - 在 Release 中,加入
local-model: {},并将 OpenAI 模型infra下的endpoint设为该服务器兼容 OpenAI 的地址http://local-model:11434/v1; - 堆栈运行后,将拉取的模型复制为构建中 OpenAI 模型所指定的模型名称
<model>,例如gpt-4o-mini或gpt-4.1:docker compose -p <name> -f dist/compose/docker-compose.yaml exec local-model ollama cp qwen2.5:0.5b <model>。
OPENAI_API_KEY随后可以设为你自己选定的任意非空值:本地服务器不做任何校验。n8n 工作流从其模型节点所选的凭据中读取模型的地址和密钥,而不是从endpoint提供的地址读取,因此也要把服务器地址交给该凭据,即在其data中apiKey旁边加上一个url。core/ai-model/ollama默认运行的 Ollama 服务器除了 Chat Completions 之外还提供 OpenAI 的 Responses API,因此声明了apiType: Responses的 Agent Framework 声明式智能体按原样即可访问它。面向 Kubernetes 的构建,即
helm目标,写出的是普通清单而不是 chart,如 helm 提供方所述:写在dist/helm/下;对于 Release 放入某个边界的组件,则写在dist/boundaries/<boundary>/helm/下,其中一些位于其下各自的文件夹中。未指定命名空间的文件(MCP 和 Dify 构建的文件就是如此)会进入你的kubectl上下文所指定的命名空间,若上下文未指定则进入default;请先在那里创建它们读取的 Secrets,然后应用该文件夹:Terminal window kubectl apply -R -f dist/helm/-R会处理这些文件夹中的文件。ClusterIP类型的 Service(MCP 和 Dify 构建为其运行的服务器所设的类型)只能从集群内部访问:要从你的机器访问它,请使用kubectl port-forward svc/<service> <local port>:<port>将一个本地端口转发给它,该命令会一直运行,直到你将其停止。 - 在 Aggregate 中,再加一个不连接任何对象的组件:
导入会在草稿旁边写出 .aggrega-import.json,即其所写内容的记录。只要你打算运行 aggrega import --sync,就请保留它;该命令会读取它来区分你的编辑和导入自己写入的内容。也请保留答案文件:它不包含任何密钥,因此可以与来源一起放在版本控制中,之后对该来源的每次导入都会读取它。
借助 AI 助手
配置了 Aggrega 工具的 AI 助手也可以完成同样的操作:将下面的提示词粘贴给它。
只使用 Aggrega 工具,不要自行创建任何文件夹。调用 `import` 工具,将 `source` 设为 `compose.yaml`,将 `target` 设为 `compose`:它会把草稿写入 Workspace 文件夹。如果它提示仍有值待填,请逐一告诉我每个值及其含义,并等待我在它指明的答案文件中各键旁边写下答案;然后以同样的方式再次调用 `import` 工具。接着调用 `validate` 工具,将 `release` 设为 `release.yaml`;再调用 `build` 工具,将 `release` 设为 `release.yaml`,将 `write` 设为 true。告诉我构建写出了哪些文件;它们位于 Workspace 文件夹的 `dist/` 下。在 VS Code 中打开
安装 Aggrega 的 Visual Studio Code 扩展后,在 VS Code 中打开运行导入的工作区——即包含其 .aggrega-config.yaml 的文件夹:草稿就在其中,位于其根目录或 --output-dir 指定的文件夹中。工作区只包含一个 Release 时,编辑器会替你选中它;包含多个时,用 Aggrega: Select Release… 选择编辑器要处理的那个。编辑器会在你编辑草稿时根据所选 Release 检查它们,并在文件和“问题”面板中标出发现的问题。命令面板中的 Aggrega: Show topology graph 会绘制所选 Release 的组件及其之间的连接。Aggrega: Build、Aggrega: Preview build 和 Aggrega: Pull 作用于同一个 Release,并且每个也是活动栏中 Aggrega 视图的 Commands 面板上的按钮;Build 会把文件写入工作区的 dist/。在 Visual Studio Code 中使用 Aggrega 介绍了其余内容。
导入器从何而来
每种格式都由一个导入器插件读取。编译器的核心导入器(下表中每种格式各一个)随每个编译器版本一起发布,并在每个工作区中为其格式提供服务,无需在你的目录中添加任何条目。第一次需要某个导入器的导入会从工作区的默认注册表中按编译器自身的版本获取它,对其进行验证,并将其保存在工作区的内容缓存中,因此之后的每次导入都从那里读取它,无需为此访问网络。如果模块根本无法获取——例如工作区处于离线状态——导入会停止并指出将其放到机器上的两种方法。核心导入器完整描述了每个导入器,以及通过 plugins.importer 条目提供给导入器的设置。
格式
| 格式 | 读取的内容 | 分步演练 |
|---|---|---|
| Compose | Compose 文件及其覆盖文件,或包含它们的目录 | 导入 Compose 项目 |
| MCP 客户端配置 | .mcp.json、claude_desktop_config.json、.vscode/mcp.json、.cursor/mcp.json,或 MCP 注册表的 server.json | 导入 MCP 客户端配置 |
| Langflow | 从 Langflow 导出的 flow,格式为 JSON | 导入 Langflow 流程 |
| Flowise | 从 Flowise 导出的 chatflow 或 agentflow,格式为 JSON | 导入 Flowise chatflow |
| n8n | 从 n8n 导出的 workflow,格式为 JSON | 导入 n8n 工作流 |
| Dify | 以 Dify DSL 从 Dify 导出的应用,格式为 YAML | 导入 Dify 应用 |
| CrewAI | CrewAI 项目的智能体声明和任务声明 | 导入 CrewAI 项目 |
| LangGraph | LangGraph 应用的 langgraph.json | 导入 LangGraph 应用 |
| Google ADK | 基于 Google ADK 构建的应用的 Agent Config 文件,从 root_agent.yaml 开始 | 导入 Google ADK 智能体 |
| Microsoft Agent Framework | 声明式智能体,即类型为 Prompt 的 YAML 文档 | 导入 Microsoft Agent Framework 声明式智能体 |
aggrega import 是该命令的完整参考:每个标志、如何识别来源、--sync 会更改什么以及它会拒绝什么。导入应答文件 介绍应答文件:它位于何处、包含什么,以及如何应答一个机密。