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

导入答案文件

有些值任何源都无法提供:用你自己的代码构建的应用程序镜像、所有者账户的电子邮件、源中未指明的模型、Kubernetes Secret 的名称。aggrega import 将每个这样的值起草为空字符串,并在其上方加一条注释说明它是什么,然后只向你获取一次——从答案文件中获取,或在终端中提问获取。答案保存在答案文件 import-answers.yaml 中,因此之后对同一源的每次导入都会从那里读取,不再提问。

本页说明该文件位于何处、包含什么、值如何写入其中,以及当某个值仍然缺失时导入会做什么。导入的用途,以及从源到构建的演练,请参见导入。

哪些值待提供

起草完成后,导入会根据每个起草文档自身的 schema,以及该文档声明的每个 Component、Feature 和连接的目录 schema 来检查该文档。当某个值在该 schema 要求有值的地方仍为空,或在 schema 声明了该键而没有任何来源提供它时,该值即为待提供。每个待提供的值都由 schema 自身对其键的描述来说明;schema 未给出描述时,则由草稿在该键上方写入的注释来说明。

只要还有值待提供,导入就不会拉取所起草 Release 的依赖;一旦每个值都有了答案,它就会拉取这些依赖(参见重新运行与 --sync)。

文件所在位置

源是应答文件是
一个文件与源文件位于同一目录中的 import-answers.yaml
一个目录源目录中的 import-answers.yaml

--answers <file> 指定另一个文件。相对路径相对于你运行命令时所在的目录进行解析。当草稿中有待填的值,且应答文件不是源旁边的默认文件时,导入在草稿旁写入的记录 .aggrega-import.json 会指明该文件,因此之后在同一目录中运行的 aggrega import --sync 无需再次指定即可读取它。该记录从不包含任何应答。

密钥的应答是密钥来源的名称,而绝不是密钥本身(参见密钥),因此应答文件可以与源一起保存在版本控制中。

文件内容

该文件为 YAML 格式。其顶层键是起草出的文件,以每个文件的起草路径表示。在每个顶层键之下,一个键是该文档中某个待填值的点分键路径,其值就是应答。schema 对该键的描述以注释形式写在键的上方。为空、或包含句点、空白字符或引号的键路径段,会写在双引号中。不符合此结构的文件会使导入停止,并指出该文件及原因,且不写入任何内容。

例如,使用 --target helm 起草的 Google ADK 导入在其 Release 中有两个待填值:你从项目构建的代理镜像,以及代理的 Gemini API 密钥的来源。两者都填好后,源目录 support_agent/ 中的应答文件内容如下:

# Values the import could not draft from the source, keyed by the drafted file and the key path inside
# it. Write each one beside its key; an import of the same source, and a sync, read them from here and
# ask nothing. A secret is never written here: its key asks where the secret comes from — a variable
# name, ${NAME}, or the name of a Kubernetes Secret.
release.yaml:
# Container image running the application built on ADK, serving its API on infra.port on every
# interface.
spec.components.support-agent.infra.image: "ghcr.io/example/support-agent:1.0.0"
# The origin of the secret value, written by the operator in the Release. Read exactly as
# values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes
# from, never the value.
spec.components.support-agent.uses.model.gemini-2-5-flash.features.credential.infra.origin: "google-api-key"

这两个应答都由你决定:ghcr.io/example/support-agent:1.0.0 代表你构建并推送的镜像,google-api-key 代表在你部署到的命名空间中保存该密钥的 Kubernetes Secret 的名称。

每个应答是一个值,导入将其作为字符串写入草稿,替换空值,草稿中的其他内容不做任何改动。写入起草出的 Aggregate 中的应答,读回时与你输入的完全一致,包括 {{。空应答会使该值仍处于待填状态。

值如何填入

导入首先从应答文件中为每个待填值获取应答。对于文件中未作应答的每个值,它会逐一向你提问——但仅当标准输入和标准输出都是终端,且未指定 --dry-run 时:

  • 每个问题都会指明起草出的文件和键路径,其措辞依据 schema 的描述;
  • 问题写入标准错误,因此标准输出只包含导入的结果;
  • 按 Enter 键可将该值留待以后填写,结束输入则停止提问。

你给出的每个应答都会写入草稿和应答文件,并且应答文件会列在已写入的文件之中。如果一次运行未对应答文件做任何更改,则不会再次写入该文件。

密钥

机密的值 — 即其模式标记为敏感的值 — 以该机密的来源作答,绝不以机密本身作答。它的问题询问的正是这一点,答案是以下名称之一:

答案示例
变量名OPENAI_API_KEY
对变量的引用${OPENAI_API_KEY}
Kubernetes Secret 的名称openai-api-key

导入会检查答案是否具有这些名称之一的形式,并拒绝其他任何内容:

  • 在终端中,答案被拒绝,显示原因,并再次提出问题;
  • 在答案文件中,导入会停止,并指出答案文件、草拟的文件和键 — 绝不指出答案本身,因为它可能就是机密 — 且不写入任何内容。

该检查读取的是答案的形式,因此碰巧看起来像名称的机密无法与名称区分开来。机密本身保留在名称所指向的位置:变量中,或 Secret 中。

无终端时

在持续集成中、通过管道以及从助手的导入工具(aggrega mcp)中,都不会提问,编辑器的导入在运行期间也不会提问。读取答案文件后仍欠缺值的导入会:

  • 写入草稿,每个欠缺的值留空;
  • 写入答案文件,其中包含每个欠缺的键,其答案为空;
  • 在标准错误上列出每个欠缺的值,作为一条警告,指出草拟的文件、键路径及其描述;
  • 不拉取草拟的 Release 的依赖项;
  • 以状态 1 退出,并输出一句话,说明欠缺多少个值以及在何处写入它们:
2 values the drafts leave empty are still owed, listed in the answers file <path>/support_agent/import-answers.yaml: write each beside its key there, then run the import again

在每个键旁边写入其答案,然后在同一目录中运行 aggrega import <source> --sync:它会为先前导入所指定的目标起草,把每个答案写入草稿,且不询问任何问题。在已包含草拟的 Aggregate 的目录中运行普通的 aggrega import 会停止,提示 --sync,且不写入任何内容。导入到新的输出目录时同样会读取答案文件:默认的答案文件,或 --answers 指定的答案文件。

助手的导入工具以 answers 接收答案文件,可相对于工作区根目录指定,也可使用绝对路径。仍欠缺值的调用会以该句话失败,并在其旁附带导入结果,包括警告。编辑器的导入同样接收答案文件,并以同一句话结束其诊断信息。

两者还会以数据形式在 owed 下列出每个仍欠缺的值:草拟的文件、以键列表表示的键路径、问题、该值是否属于某个密钥,以及对于密钥,其答案必须是什么(编辑器中为 secretAdvice,助手的导入工具中为 secret_advice)。在 answered 下回传每个答案——草拟的文件、键路径和答案——并带上 sync,导入会检查它,将其保留在答案文件中并写入草稿,与在终端中键入的答案的处理方式相同。密钥的答案若不是一个名称,则既不保留也不写入:该值仍留在 owed 中,原因会取代其建议。

在写入草稿的导入之后,编辑器会提出在各自的输入框中询问每个仍欠缺的值,并以这种方式发回答案;在预览之后则不会提出任何提议,因为在 --dry-run 下不会提问。回答导入仍欠缺的值介绍了这些问题。

在 --dry-run 下,不提问也不写入任何内容,包括答案文件。每个欠缺的值仍会在标准错误上列出,退出状态即为试运行本身的状态。

重新运行与 --sync

aggrega import --sync 读取与之前那次导入相同的答案文件:优先使用 --answers 指定的文件,否则使用草稿旁记录所指定的文件,否则使用源旁边的默认文件。它将每个答案写入草稿,替换空值;当答案文件回答了所有欠缺的值时,它不提任何问题。

一旦不再欠缺任何值且工作区不处于离线状态,导入会像 aggrega pull 那样拉取草拟的 Release 的依赖项并写入 release.lock,因此 aggrega validate 和 aggrega build 可立即在草稿上运行。在 --offline 下不拉取任何内容,导入会给出接下来要运行的 aggrega pull --release <path>。

一个答案文件用于多个目标

同一来源针对不同目标草拟时,可能欠缺不同的值:上文的 Google ADK Release 以 --target compose 草拟时只欠缺镜像,而同一 Release 以 --target helm 草拟时还欠缺智能体的 Gemini API 密钥的来源。一个答案文件可同时服务两者:

  • 导入会添加其草稿欠缺的键,并设置它收到的答案;
  • 针对这些草稿并不欠缺的键的答案会保留在文件中但不会应用;
  • 文件中的其他所有键和注释保持原样。

只有当草稿欠缺某个值时才会读取答案文件。此时,标准错误上的一条信息行会指出每个保留但未应用的答案——这里是以 --target compose 起草的 Flowise 导入,它只欠缺所有者的电子邮件,所读取的答案文件还指定了同一导入在 --target helm 下欠缺的两个 Kubernetes Secret:

info: the answers file <path>/import-answers.yaml also answers spec.components.flowise.features.owner_password.infra.origin in release.yaml, spec.components.flowise.uses.model.chatopenai-0.features.credential.infra.origin in release.yaml, which these drafts do not leave empty; those answers are kept there and not applied

当草稿不欠缺任何值时——例如以 --target compose 起草的 Langflow 导入,它从变量读取每个密钥——不会读取答案文件,不会打印此类信息行,文件保持原样。

另请参阅

  • aggrega import — 该命令的参考,包括所有标志。
  • 导入 — 导入会草拟哪些内容,以及每种源格式的分步演练。