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

配置

aggrega 从哪里读取设置,以及某项设置应放在哪个文件中。

简单情形

两个文件,大多数项目不需要别的。

项目中的一个文件,名为 .aggrega-config.yaml,位于项目根目录。它保存本项目的构建方式:哪些目录存放 vendored 的目录内容,哪些插件渲染哪些目标,放宽了哪些 lint 规则,本地缓存放在哪里。该文件会被提交,因此克隆项目的队友会以相同方式构建它。

它的 workspace: 块用于将该目录标记为项目根目录:

# <project>/.aggrega-config.yaml
workspace:
catalog_dirs:
- ./catalog
auto_pull: true

该块只包含定义根目录的目录(catalog)路径;其他所有设置都位于其旁边的顶层。不 vendor 任何目录内容的项目仍要写出该块,保持为空——workspace: {}——因为该块的存在本身就是标记。

机器上的一个全局文件,位于 ~/.config/aggrega/config.yaml——在 Windows 上,位于 APPDATA 环境变量所指目录中的 aggrega\config.yaml。该机器上的每个工作区都通过它解析,它保存属于机器而非某个项目的设置——你从中拉取的注册表及各自的签名信任策略、已编译模块存储可增长到多大,以及你安装的任何命令扩展插件。无论你在哪里工作,这些设置都相同,因此只需声明一次。该文件存在时会自动加载,不存在时也不会出错。

~/.config/aggrega/config.yaml
registries:
- host: hub.aggrega.ai
signing:
required: true

aggrega config init 会为你写入该全局文件,注册一个注册表及其公布的签名信任策略,并告诉你该文件在机器上的位置以及机器级缓存的存放位置。aggrega config show 打印当前生效的设置,aggrega config show --origin 说明每项设置由哪个文件——或哪个环境变量——决定。

机密不属于配置。 注册表密码和签名身份令牌从不作为任一文件中的字段;它们在需要时通过环境变量或标志提供。参见 environment-variables.md。

从何处读取本地实体

保存自有目录内容——一个 Component、一个 Feature、一个 Recipe 或某种库类型——的项目有两种方式说明这些内容所在位置,第一种完全不需要配置。

项目根目录下的 catalog 目录无论是否被指定都会被读取。 将实体放在 <project>/catalog/ 下,每个加载目录的命令都会读取它,包括 workspace: 块为空的项目。目录会被递归读取,因此其中子目录如何组织由你决定。

workspace.catalog_dirs 下列出的目录也会被读取,并且先被读取。 该列表是一个有序的搜索栈:第一个声明某个标识的目录拥有它,后续目录中的同一标识被遮蔽。catalog 在所有列出的目录之后读取——除非某个列出的目录已包含它,此时它作为该目录的一部分被读取——因此列出目录是在原有内容之上添加,而非替换。命令行上可重复的 --catalog <dir> 先于两者读取,在此给出的相对路径相对于你运行命令的目录解析,因为没有配置文件声明它。被多次指定的目录——在命令行和列表中,或在列表中出现两次——只读取一次,位于首次被指定的位置,因此其中的内容不会被报告为被自身遮蔽:遮蔽总是指两个不同文件声明同一标识。同一目录的两种写法、经由链接指向它的路径,以及——在忽略大小写的文件系统上——不同大小写的写法,都指同一个目录。位于另一个列出目录内部的目录仍作为独立条目读取。为每个 Release 保留一个目录变体的项目,可以改为给每个 Release 一个自己的列表——参见为 Release 指定其自己的目录。

列出目录是项目读取其外部实体的方式。 列出的目录可以位于任何地方——同级检出、与其他项目共享的目录——并在其所在位置被读取,即使它本身是符号链接。除此之外没有任何方式能触及那么远:项目内指向别处的链接不会被跟随读取,按路径指向项目外文件的文档会被拒绝,因此保存在别处的实体通过列出其所在目录并按名称引用该实体来访问。项目外列出的目录本身就是一个根,因此其下指向其外部的链接也不会被读取。工作区边界给出了完整规则。

列出的目录必须是目录。 列出的路径如果什么都不存在,或者那里是一个文件或一个不指向任何地方的链接,都会在读取或写入任何内容之前被每个读取所列目录的命令拒绝——拉取、构建、验证、检查、lint,以及通过 aggrega serve 从编辑器或通过 aggrega mcp 从助手驱动的相同操作——因此构建永远不会在比你列出的更少的目录上运行。拒绝信息会指明按原样书写的条目、它解析到的路径、列出它的配置文件和行,以及它所在的列表:

<project>/.aggrega-config.yaml:4: the `workspace.catalog_dirs` entry "../shared/aggrega-catalog" names <directory>, which does not exist; create that directory, or remove the entry: workspace configuration is invalid

创建该目录,或删除该条目:在不带它所列出的同级检出的情况下复制的项目会删除该条目,并从注册表解析该检出本应提供的内容。Release 自身条目列出的目录、由你的流水线所拥有的配置文件或全局文件添加的目录,以及 AGGREGA_CATALOG_DIRS 携带的目录同样如此;对于后者,拒绝信息会指明该变量而不是某个文件。配置本身仍会加载,因此不读取任何目录的命令仍可运行。不存在的 --catalog 目录是为单个命令输入的,aggrega build 会拒绝它并指明该目录。存在但无法读取的已列出目录会被加载全部目录的命令拒绝,并指明该目录。

将列表写为空表示该项目完全没有本地目录,这也是唯一能使 catalog 同样不被读取的写法:

# <project>/.aggrega-config.yaml
workspace:
catalog_dirs: []

省略该键则是另一种表述:省略列表是普通情形,catalog 仍会被读取。

构建、拉取、验证或 aggrega inspect 在找不到你所用名称对应的实体时,会说明该项目从何处读取本地实体,以及需要更改什么才能读取你指定的实体。如果你写了空列表,它不会给出此类提示——不读取本地目录正是你在那里声明的,建议更改它就是在与你争辩。如果声明该名称的文档已被读取但被拒绝,它也不会给出此类提示:该文档已位于目录读取的位置,因此报告会指出该文档违反了什么,即行号和约束,移动它无济于事。如果某个文档格式严重错误,以至于其声明的名称根本无法读取,它就无法与你所用的名称匹配,因此仍会给出上述说明——而如果该文档声明了 Aggrega 的 apiVersion,对 Release 的构建、拉取或验证会在说明旁指出该文档,并附上解析器自身给出的原因,因为它可能正是需要打开的文件。找到了实体但无法接受它的失败——注册表现在在你的锁文件固定的版本下提供了不同的字节,实体携带的某个文件无法读取——也不是实体缺失,它只报告自己的解决办法。

拉取或推送是否固定实体

Recipe 或 FeatureRecipe 在其旁边的 entity.lock 中保存其所读输入的固定信息——完整写出的远程 source:、artifacts 条目导入的文件、其旁边 source: 的文件——记录这些信息是实体作者的步骤,即 aggrega pin。默认情况下,pull 和 push 都不运行该步骤:拉取会在锁文件未固定的实体上停止,推送会拒绝发布它。两个键(每个命令一个)可使运行该步骤成为相应命令的默认行为:

# <project>/.aggrega-config.yaml
workspace: {}
pin_sources_at_pull: true
pin_sources_at_push: true

每个键只管控自己的命令,每个命令的 --pin-sources 可在两个方向上覆盖其对应的键——--pin-sources=false 在配置为固定的项目中为单次运行关闭该步骤。填充自身锁文件的构建属于拉取,遵循 pin_sources_at_pull。这些键应放在项目文件而非全局文件中:项目的拉取是否记录固定信息是该项目的策略,克隆它的队友应得到相同结果。pin_sources_at_pull 也是使用他人未固定目录的项目一次性记录这些固定信息、而不是每次拉取都停止的方式。

哪个插件渲染某个 capability

Recipe 会指明它渲染所经由的 capability(capability: helm),由提供该 capability 的插件来渲染它。如果恰好只有一个插件提供某个 capability,则无需任何配置。如果有多个插件提供,则由 plugins.providers 条目按插件的标识指明使用哪一个:

# <project>/.aggrega-config.yaml
workspace: {}
plugins:
providers:
- capability: helm
uri: provider/helm

pull 会解析该条目,并把所选的插件记录到该 Release 的 lockfile 中,而 build 按 lockfile 记录的内容进行渲染,因此在这里所做的修改会在下一次 pull 时生效。

uri 按插件的标识 provider/<name> 指明插件,而绝不按插件发布的位置指明。 aggrega plugin add provider <query> --capability <capability> 以这种形式写入条目,不带版本:条目选择由哪个插件提供该 capability,版本则是 Recipe 固定的版本,否则为可用的最高版本,而 lockfile 记录 pull 所选的版本。编译器内置的插件以编译器自身的版本提供,因此为这类插件的条目写上的版本,只有恰为该版本时才能解析。uri 为注册表位置(oci://hub.aggrega.ai/plugin/provider/helm)的条目没有指明任何插件的标识,会在文件加载时被拒绝,并指出该条目以及应写的形式。

条目对整个项目只写一次,而一次 build 只针对一个 Release,因此为当前 Release 从未请求的 capability 编写条目是合法的(项目中的另一个 Release 会读取它),并且不会报告任何内容。每次 build 和每次 aggrega validate --release 确实会检查每一个条目,无论是否有 Recipe 请求其 capability,并根据条目所指明的内容进行检查:

  • 如果条目指明的插件并不提供其 capability,build 会停止,验证也会失败。 pull 会解析每个指明了插件的条目,并拒绝无法解析的条目,因此条目一旦经过 pull,build 就持有其插件并知道它提供什么;如果条目指明的插件 build 尚未持有,则在 pull 获取它之后再进行判断。 消息会指明该条目、该插件、 该插件实际提供的内容,以及在存在时一处只差一次编辑的拼写,这正是 hlem 误写为 helm 这类拼写错误的形态。
  • 如果条目只指明了一个 capability,而 build 读取的插件中没有任何一个提供它,则给出警告, build 继续进行。提供它的插件可能只被另一个 Release 读取,而本次 build 看不到它;并且未指明插件的条目所选择的,不会超出没有该条目时 capability 解析本来就会选择的内容。

这里的 capability 绝不包含冒号,包含冒号的会在文件加载时被拒绝。Recipe 的 capability: 被解读为:最后一个冒号之前是 capability,之后是版本固定,因此键为 helm:1.0.0 的条目永远无法被查找到。请改为在插件上固定版本(uri: provider/helm:1.0.0),或在 Recipe 中固定。

哪个导入器把源转换为草稿

aggrega import 会把源交给声明支持该源格式的导入器:可以是你的 catalog 中的导入器,也可以是编译器的某个核心导入器,例如用于 Langflow flow 的 import:langflow。如果恰好只有一个导入器声明支持该格式,则无需任何配置。plugins.importer 条目通过在其 uri 中以标识和版本指明导入器来挂接它,并把 with 下的内容交给它:

# <project>/.aggrega-config.yaml
workspace: {}
plugins:
importer:
- uri: importer/agent-flows:1.2.0
with:
settings:
target_namespace: payments

aggrega plugin add importer 正是以这种形式写入 uri。版本可以是精确版本(:1.2.0),也可以是范围(:^1.2.0 表示同一主版本内不低于它的最高版本)。请写其中之一:在此列表中,不含冒号的 uri 会被解读为文件系统路径,如相对路径指向何处所述,并且不指明任何导入器。

条目的作用取决于它所指明的导入器是否声明支持某次导入所请求的格式:

  • 支持:运行的就是该导入器,版本为 uri 所指明的版本,无论 catalog 中还有多少其他 导入器也声明支持该格式,并且会把条目的 with.sources 和 with.settings 交给它。如果工作区的 catalog 联合了两个发布者针对同一格式的导入器,就通过条目来说明使用其中哪一个。
  • 不支持(它指明的是另一种格式的导入器、另一种类型的插件,或者既不在你的 catalog 中、也不由编译器自带的内容):该条目不参与这次导入。 它不做任何选择,其 with 也 不会交给任何导入器。条目的设置只会到达它所指明的导入器,因此为每种格式挂接一个导入器的工作区 可以分别配置每个导入器,而不会让一个导入器的设置到达另一个。

如果有多个导入器声明支持该格式,而其中没有唯一一个被挂接(一个都没有,或者条目指明了其中两个),导入会被拒绝,并指明无法在其间做出选择的导入器。如果条目指明的导入器声明支持该格式,但其版本无法由 catalog 中该导入器的任何版本满足(catalog 中没有的精确版本,或者没有任何版本落入的范围),同样会被拒绝,并指明该版本,而不会改为运行另一个版本;根本不是版本的值,例如 :latest,会作为格式错误被拒绝。编译器某个核心导入器的 Plugin 实体,如果在其 catalog 文件夹中旁边没有模块,就不是候选:在编译器自身的版本上,由核心导入器代替它运行;在任何其他版本上,只有当某个条目恰好指明该版本,或者没有任何可运行的同名导入器声明支持该格式时,该实体才仍是候选,详见与你自己的导入器并存时运行哪一个。

每个导入器由一个条目挂接。 两个条目指明同一个导入器(相同标识,无论是同一版本还是两个版本)会在配置加载时被拒绝,无论是哪个命令读取配置,并指明这两个条目及其所在的文件。该规则涵盖为此列表提供内容的每个文件:全局文件中的条目、项目文件中的条目、importer_append 下的条目,以及流水线的 .aggrega-config-append-ci.yaml 中的条目都计算在内,因此把导入器升级到新版本意味着修改它唯一那个条目上的版本。当 aggrega plugin add importer 所写入文件的 plugins.importer 列表中已经指明该导入器时,它正是这样做的:它把该条目改为所解析出的版本,保留条目的位置及其 with,而不是再添加一个条目。它不读取其他列表,因此在 importer_append 下或在流水线的 .aggrega-config-append-ci.yaml 中挂接的导入器,会被该命令再挂接一次,这一对条目会在配置加载时被拒绝;对于这样的条目,请在其所在之处修改版本。uri 为文件系统路径的条目不指明任何导入器,不参与比较;plugins.governance 和 plugins.linter 列表也不受此规则约束:同一插件可以多次挂接到这些列表,每次带有各自的 with。

导入所经由的解析器无需条目。 导入器读取其源(未指明格式的导入也通过它识别格式)时,会使用针对该源语法的解析器:如果你的 catalog 为该语法提供了解析器,就使用它;如果你的 catalog 没有为某种语法提供解析器,就使用编译器自带的解析器,其中包括 JSON。因此,catalog 中没有任何解析器的工作区,无需任何配置即可导入 Langflow 或 Flowise flow。没有列表用于挂接解析器:你的 catalog 为某种语法提供的解析器就是所使用的解析器,而两个名称不同却服务于同一语法的解析器会被拒绝,如 A parse or import format is advertised by more than one plugin(某个解析或导入格式由多个插件声明支持)所述。

从零开始

刚安装的 aggrega 两个文件都没有,这是一种可用的状态,而非损坏的状态:每项设置都会回退到内置默认值,命令照常运行。缺少的是一个用于拉取 catalog 内容的注册表,以及说明接受哪些签名的信任策略,而这正是 aggrega config init 所写入的内容。

你无需事先知道这一点。读取配置却在任何位置都找不到文件的命令,会在标准错误上提示一次,并指出 aggrega config init 是创建配置文件的方式。这是建议而非失败:标准输出不受影响,不会向你询问任何内容,退出状态与该命令本来会报告的一致。它只在标准错误是终端时才会写出,因此会在你使用键盘时提示你,而绝不会堆积在流水线的日志中。一旦任一文件存在(你的项目文件或全局文件),它就不再出现。

要用官方 hub 及该 hub 声明的信任策略初始化全局文件:

Terminal window
aggrega config init

传入 --registry <host> 可初始化另一个注册表,传入 --workspace 可把条目写入本项目的文件而非全局文件,传入 --dry-run 可查看将要写入的内容而不创建任何文件。aggrega-config.md 完整介绍了该命令。

如何书写镜像仓库主机

每个 registries[].host 指定一个镜像仓库主机。default_registry 也是如此(其后可选地跟一个仓库路径),除非它改为指定这些条目之一(见下文)。主机按主机本身书写,采用该镜像仓库的信任策略所登记的唯一拼写:

  • 包含点号的小写主机名,例如 registry.example.com;
  • localhost,或单个名称后跟端口,例如 registry:5000;
  • IPv4 地址,例如 127.0.0.1,或用方括号括起的 IPv6 地址,例如 [::1];

每种都可带一个可选的 :port,此外不含任何内容:没有协议、没有路径、没有凭据、没有空白,也没有大写字母。不带端口的单个名称不是镜像仓库主机,因为这是目录实体名称第一段的形式(core/web-api 中的 core),两者绝不能被相互误读。

# <project>/.aggrega-config.yaml
workspace: {}
default_registry: registry.example.com
registries:
- host: registry.example.com
signing:
required: true

拼写是策略的一部分。 一个 registries 条目适用于其 host: 所指定的主机,官方 hub 内置的签名要求适用于 hub.aggrega.ai,因此以其他任何方式书写的主机虽然能到达正确的镜像仓库,却会错过为其编写的策略。因此它会在配置加载时被拒绝,拒绝信息会给出应写的拼写:HUB.AGGREGA.AI 和 https://registry.example.com 被拒绝时分别给出 hub.aggrega.ai 和 registry.example.com;作为 registries[].host 的 registry.example.com/charts 同样如此,因为该键不带路径。端口 443 是通过 HTTPS 访问的主机的默认端口,因此 hub.aggrega.ai:443 也以同样方式被拒绝,并给出 hub.aggrega.ai。localhost 及其他回环地址则通过普通 HTTP 访问,443 在此是普通端口,因此 localhost:443 按原样被接受。空的 default_registry 表示不指定默认镜像仓库。

default_registry 可以带仓库路径。 许多镜像仓库将所有仓库置于某个所有者或项目之下(ghcr.io/<owner>,Harbor 上的 <host>/<project>),位于其中之一的默认镜像仓库写作主机后跟该路径:

# <project>/.aggrega-config.yaml
workspace: {}
default_registry: ghcr.io/acme
registries:
- host: ghcr.io
signing:
required: true

该路径是内容发布和获取的位置。通过这一默认值,aggrega push 将 core/api-server 版本 1.0.0 发布到 ghcr.io/acme/component/core/api-server:1.0.0,解析 core/api-server 的 pull 也从同一位置获取它,因此发布时附加的签名也能在那里找到。该路径是 OCI 分发语法中的仓库路径:由一个或多个以 / 连接的段组成,每段由小写字母和数字构成,段内可用 .、_、__ 或连字符分隔,不带标签、摘要或末尾的 /。

路径从不参与镜像仓库的信任判定。 适用其策略的 registries 条目、aggrega login 存储的凭据、签名要求以及受信任的身份,都仅按主机查找,因此上文 ghcr.io 的条目管辖 ghcr.io/acme 以及该主机上的所有其他路径,任何路径拼写都无法绕过它;条目的 host: 本身不带路径。路径前的主机若以其他拼写书写,会被拒绝并给出应写的位置(GHCR.io/acme 和 https://ghcr.io/acme 给出 ghcr.io/acme);主机之后的内容若不是仓库路径,会被拒绝并给出其前面的主机。

default_registry 也可以改为指定一个条目。 写作 registries 下某条目的 name: 时,它代表该条目的 host:。发布、拉取、签名验证以及每个按镜像仓库的信任设置随后都使用该主机,不会从拼写与该名称相同的主机获取任何内容:

# <project>/.aggrega-config.yaml
workspace: {}
default_registry: local
registries:
- name: local
host: 127.0.0.1:5000

名称先于主机拼写进行匹配,与 --registry 标志的匹配方式相同,因此作为某条目 name: 的值即使同时拼写得像主机,也代表该条目。被两个条目共用的名称会因歧义而被拒绝,并给出两个主机。条目可位于任一文件中(项目的 default_registry 可以指定全局文件声明的条目),因为该名称只在读取所有文件和环境之后,针对生效的条目读取一次。既不是条目名称也不是镜像仓库主机(单独出现或后跟仓库路径)的值会被拒绝,拒绝信息会说明两者任一均可修正。名称后跟路径(例如 local/acme)也会被拒绝:名称代表其条目的主机,而不代表其下的某个位置,因此拒绝信息会给出两种应改写的拼写:local,或条目的主机后跟路径 127.0.0.1:5000/acme。用 aggrega registry remove 移除条目时,default_registry 保持原写法不变,因此指定了被移除条目的默认值此后不再指向任何内容,在被改写之前会一直被拒绝。

每一层都遵循同样的拼写。 无论值来自配置文件、AGGREGA_DEFAULT_REGISTRY,还是指定某次 aggrega push 或 aggrega push-artifact 目标的 --registry 标志,都会以相同的措辞被拒绝。该标志指定主机,由它引导的发布会落在该主机上而不带仓库路径:路径属于 default_registry。aggrega registry add 和 aggrega config init --registry 也要求传给它们的主机遵循这一拼写;它们还接受以引用代替主机,并将条目登记在该引用所指的主机下。来自文件的拒绝会给出文件和键;来自环境的拒绝会给出变量。schema 在 registries[].host 上以模式声明主机形式,而在 default_registry 上不声明任何模式,因为其值可以是任一条目的名称,所以仅读取 schema 的编辑器不会标出拼错的默认值,拒绝它的是配置加载。

主机仅按其拼写判断,路径也是如此。 配置加载时不检查名称能否解析、该处是否有镜像仓库响应,也不检查路径在其上是否存在。

覆盖关系

CLI flag > environment variable > configuration file > built-in default

标志是最明确的信号,直接胜出。环境变量覆盖已提交的文件,这使流水线无需编辑受跟踪的文件即可更改设置。未设置(或设置为空字符串)的变量会落到下一层,而不是清空已配置的值。在两个文件之间,你的项目文件优先于全局文件。

标志因被输入而胜出,而不是因其携带的值,对于布尔设置,这决定了是否存在可用的顶层。--offline 在一次运行中开启该模式;在已提交的文件或导出的变量开启了它时,--offline=false 在一次运行中将其关闭。仅读取值的层无法区分“关闭”与“未提及”,因此每条命令看起来都像请求了该标志的默认值,也就根本无法撤销已配置的设置。

这就是单台机器上单个项目的完整模型。下文的一切都是为超出这一范围的项目而设。

超出两个文件之外

这些机制是为更大的形态而构建的——由相关项目组成的 monorepo、贡献自身设置的流水线、多个项目共同扩展的共享目录。在你遇到某个机制所解决的问题时再使用它。

项目内的多个配置文件

从项目根目录到命令运行所在目录之间的每个 .aggrega-config.yaml 都会参与配置,较近的文件覆盖较远的文件。因此子项目可以带有自己的文件,调整根目录声明的内容,而无需重复声明。

只有带 workspace: 块的文件才会标记根目录。不带该块的文件仍然贡献其设置——只是不会把所在目录变成项目根目录,这样子项目的设置文件就不会重新定义项目的起点。

传入 --workspace-root 除了跳过发现过程,还会改变这一点:只收集所指定根目录自身的配置文件,其下各目录中的文件不参与配置。 这样,无论从何处运行命令,固定根目录的配置都保持一致。

以这种方式收集的每个文件都从项目内部读取。若某个文件是指向项目外部的符号链接——或位于经由此类链接到达的目录中——则不会读取它,每个读取配置的命令都会在此停止并指出该链接,而不是用剩余文件配置项目;下文流水线的文件同样如此。少数从不读取配置的命令,例如 aggrega version 和 aggrega help,会照常运行并给出指出该链接的警告。编辑器的语言服务器和助手的工具以相同方式读取配置,但仍会在此类项目上启动,以便将其列出:它们的 Release 和实体列表会在不加任何配置的情况下读取并作答,并在未读取的链接中列出该文件,而由配置决定的其他所有请求都会在此停止并指出该链接。保存在项目外部的配置,可以通过将其指定为全局文件来读取,如显式指定全局文件所述。参见工作区边界。

扩展列表而非替换列表

列表值设置与其他所有设置的行为相同:较近文件的值替换较远文件的值。当你想在外层文件声明的内容上追加而非重新声明时,请使用其旁边的追加配套项:

列表设置其追加配套项
workspace.catalog_dirscatalog_dirs_append
plugins.governancegovernance_append
plugins.linterlinter_append
plugins.importerimporter_append
plugins.providersproviders_append

配套项下的条目会在每一层拼接到已解析的列表上,而不是遮蔽它,因此子项目可以在根目录已声明的内容基础上添加一个 linter:

# <project>/services/api/.aggrega-config.yaml
plugins:
linter_append:
- uri: ./lint/api-rules.wasm

若同一文件同时设置了基础列表及其配套项,则该文件的值为基础列表后接追加的条目。

workspace: 块是配套项可写位置的例外。带有该块的文件会将其所在目录标记为项目根目录,因此若子项目的文件写了 workspace.catalog_dirs_append,就会开启一个自己的项目,而不是追加到外层项目。目录配套项在你的全局文件与项目根文件之间组合。

plugins.cli 列表会自行跨文件组合,没有配套项:在全局文件中声明的命令扩展会在每个项目中注册其命令,在某个项目中声明的只在该项目中注册,两者会一起注册。每个条目固定一个插件:它解析的 uri,以及 aggrega plugin add cli 校验过的字节的 digest,写作 sha256: 后接 64 位小写十六进制数字。任何其他写法的摘要都不可能等于解析出的字节的哈希摘要,因此会在文件加载时被拒绝,并指出该文件和条目。

为 Release 指定自己的目录

一个项目可以并存多个目录变体——每个目标一个,各自包含为不同 provider 渲染相同 Components 的 Recipes——并针对其中之一构建每个 Release。在 workspace.releases 下为每个 Release 命名,并为其指定自己的 catalog_dirs:

# <project>/.aggrega-config.yaml
workspace:
releases:
release-compose.yaml:
catalog_dirs:
- ./catalog-compose
release-helm.yaml:
catalog_dirs:
- ./catalog-helm

每个键是一个 Release 文件,相对于指定它的配置文件书写。与 build.authoring_release 一样,键可以指定保存在项目外部的 Release,在此处指定它正是项目访问它的方式:项目内指向它的链接会被读取而不是跳过,如 工作区边界所述。其下的两个键与在 workspace: 块上的含义相同,作用范围限于该 Release:

  • catalog_dirs 为该 Release 替换工作区的列表。搜索顺序、其后读取的 catalog 目录,以及空列表的含义,都与工作区自身的列表相同。
  • catalog_dirs_append 在该 Release 的列表之后读取。只写 catalog_dirs_append 的条目保留工作区的列表并在其上追加。

映射中未指定的 Release 读取工作区自己的 workspace.catalog_dirs。映射中指定的 Release 无论以何种方式构建——在终端中使用 aggrega build 或 aggrega pull,编辑器通过 aggrega serve,助手通过 aggrega mcp——都读取其自己的目录,因此它们都不需要标志就能找到其目录。命令行上的 --catalog <dir> 在该次调用中仍先于该 Release 的目录被搜索。若按你使用的名称查找不到实体,提示会指出该 Release 的条目,作为列出包含该实体的目录的位置。

指定了不存在文件的条目会在配置加载时被拒绝,并指出该条目和文件。因此,重命名 Release 会使所有命令停止,直到条目随之重命名,而不是让该 Release 在无任何提示的情况下针对工作区的列表构建。条目列出的目录必须确实是目录,与工作区列表指定的目录一样:不是目录的,会被每个读取该 Release 目录库的命令拒绝,并指出该条目及其所在行。

不涉及单个 Release 的操作仍读取工作区的列表:对整个目录的 lint 或校验、按名称查找实体、单独检查某个 Aggregate,以及编辑器对工作区实体的列出。AGGREGA_CATALOG_DIRS 设置工作区的列表,不会影响此处的任何条目,而由流水线拥有的配置文件根本不读取该映射。

由流水线拥有的配置文件

名为 .aggrega-config-append-ci.yaml 的文件可以放在遍历访问到的任何目录中、手写文件的旁边。它是一个单独的文件,以便自动化流水线可以拥有并整体覆盖它,而绝不触碰人工编写的内容。

它仅做追加。其中针对上述五个列表设置的条目会拼接到已解析的列表上;它不能删除任何内容,也不能覆盖标量。其中写入的标量或映射键没有追加含义,因此会被忽略并在警告中指出,而不是被悄悄应用。它也从不标记项目根目录,因此把它放入某个目录只会添加挂载项,而不会移动项目的起点。

相对路径指向何处

相对文件系统路径相对于声明它的文件所在目录解析——不是相对于项目根目录,也不是相对于你运行命令的目录。 这条规则值得读两遍,因为一个看似相对于项目的路径会解析到别处,而构建仍然成功,针对的却是你并未打算使用的内容。

它适用于 workspace.catalog_dirs,适用于以 workspace.releases 为键的 Release 文件及每个条目列出的目录,适用于 plugins.governance 或 plugins.linter 挂载上的本地文件系统路径——指向磁盘上 .wasm 文件的 uri,以及该挂载 with.sources 下的每个条目——也适用于 plugins.importer 挂载的 with.sources 下的每个条目。在这三个列表上,不含冒号、不指向任何注册表的 uri—— importer/agent-flows 与 ./lint/api-rules.wasm 都是如此——就是这样的路径;而按身份指定插件的 uri 在冒号后带有版本,如 importer/agent-flows:1.2.0,并完全按原样保留。importer 挂载的 uri 指定它所挂载的 importer,如 哪个 importer 将源转换为草稿所述;导入不会从写在那里的路径读取任何模块。 该规则同样适用于追加配套项下的条目,每个条目都锚定到各自声明它的文件,而不是合并恰好结束时所在的文件。它还适用于 mcp.tls.cert_file、mcp.tls.key_file 和 mcp.authorization.jwks_file,因此无论服务器从何处启动,都能找到位于声明文件旁边的文件。

因此,对于如下布局:

myproject/
├── .aggrega-config.yaml
└── services/
├── .aggrega-config.yaml
└── catalog/

若 ./catalog 写在根文件中,该路径指向 myproject/catalog。若写在 services/.aggrega-config.yaml 中,完全相同的文本指向 myproject/services/catalog。绝对路径按原样保留,注册表引用也是如此,例如 oci://hub.aggrega.ai/plugins/helm:1.0.0。

以下设置有意不遵循此规则,因为它们没有可锚定的声明文件,或者它们的每个读取方都在别处解析它们:

  • artifact_cache_dir 相对于项目根目录解释,无论命令从何处运行, 因此缓存只有一个目录,而不是每个调用位置各一个。绝对值 会在加载配置时被拒绝。
  • AGGREGA_CATALOG_DIRS 来自环境变量,完全没有声明文件,因此请 在其中提供绝对路径。
  • mcp.listen 完全按原样使用,包括其 unix:<path> 形式中的文件系统路径。同一地址也可来自 aggrega mcp --listen,而它没有 声明文件,因此若仅锚定配置中的写法,同一个字符串会因来源不同而指向两个 不同的位置。请为套接字提供绝对路径。

存储共享的一项设置

几乎每项设置所管理的都属于你正在工作的项目——它通过哪些目录解析目录内容、哪些插件渲染它的目标、其内容的评判有多严格、守护进程的内存缓存可以增长到多大。项目文件中的值管理该项目自己的事物,无需留意什么。

compiled_module_cache.max_bytes 是唯一的例外,因为它所限制的并非按项目划分。 编译后的插件代码保存在你机器上每个项目都复用的单一目录中,因此一个给定插件只编译一次,而不是每个项目各编译一次。该上限本身的解析方式与其他设置相同——写在某个项目的文件中,该值就对该项目生效——但存储仍然只有一个大小,而生效的大小来自最近一次构建。两个设置不同上限的项目会轮流生效,较低的上限会丢弃另一个项目已付出代价编译的代码。

因此,当你希望对所构建的一切采用同一个值时,请将它放在全局文件中,并使其高于单次构建所编译的量。aggrega cache status 报告存储当前所含内容, aggrega config show --origin 告诉你当前运行所依据的上限实际来自哪个文件。

供他人访问的服务器的设置

aggrega mcp 使用 Model Context Protocol。在你自己的机器上,客户端将其作为子进程启动,并通过标准输入和输出与之通信,这是默认方式,而影响这种形态的设置只有保持该默认值的 mcp.transport 和 mcp.announce_tools。mcp 块的其余部分用于另一种形态,由 mcp.transport: http 选择:在主机上长期运行的一个进程,由不在其键盘前的调用方通过 HTTP 访问。

# <project>/.aggrega-config.yaml
mcp:
transport: http
listen: 127.0.0.1:7777
authorization:
issuer: https://login.example.com
resource: https://mcp.example.com/mcp
allowed_origins:
- https://studio.example.com
limits:
max_concurrent_requests: 32
deny_reach:
- registry
announce_tools:
- list-entities
- get-schema
- validate
- build
health:
listen: 127.0.0.1:7778

mcp.transport 负责选择传输方式。 http 启动监听器;默认值 stdio 通过标准输入和输出通信,这正是子进程客户端所期望的。任何其他值都会在加载此文件时被拒绝。aggrega mcp --transport <stdio|http> 对单次调用起相同作用,并优先于该键,正如每个标志都优先于每个文件。

mcp.listen 指定该监听器绑定的位置,不选择任何东西。 为其提供 host:port 地址或 unix:<path> 套接字;aggrega mcp --listen <address> 在单次调用中优先于它。 若选择了 http 而两者都未提供地址,启动会在任何绑定之前被拒绝。若选择了 stdio,显式输入的 --listen 会被拒绝,而仅由此键指定的地址则不被使用—— 服务器会在其错误流上用一行说明这一点,并指出此文件和 mcp.transport: http。因此,供他人访问的服务器会如上同时设置两个键,而从该文件覆盖的目录中启动的客户端仍通过自身的流访问服务器。unix: 路径按原样使用,不进行锚定—— 参见相对路径指向何处。

mcp.tls.cert_file 和 mcp.tls.key_file 将 TLS 放入进程中。 同时设置两者,监听器将自行提供 HTTPS 服务。两者都不设置,则提供明文服务,这仅在回环地址或 Unix 套接字上被接受——即前置代理持有证书并转发到进程时所用的形态。任何其他地址上的明文监听器都会在绑定前被拒绝,并指出这两个键;只设置其中一个而未设置另一个也同样被拒绝。两者都是文件系统路径,遵循上述规则:相对路径相对于声明它的文件所在目录解析,因此提交在该文件旁边的证书无论服务器从何处启动都能找到。若证书在项目外部管理,请将它们写为绝对路径。

mcp.authorization.issuer 和 mcp.authorization.resource 说明调用方出示的令牌由谁签发,以及本服务器作为令牌所针对的资源叫什么。 只要选择了 http 传输,这两项就都是必需的;缺少它们时,监听器会在绑定任何内容之前被拒绝,因为对该端点的每个请求都会以 bearer 令牌质询作答,而一个没有指明去向的质询是客户端无法据以行动的。请写完整地址,包括 scheme 和主机:issuer 与该授权服务器声明的自身标识符完全一致,resource 则是调用方实际访问的地址——如果前面有代理,就是代理呈现的主机,而不是本进程绑定的地址。两者都会发布在监听器提供的 OAuth 受保护资源元数据文档中,无需任何凭据即可读取,客户端正是在这里查找从何处获取令牌。两者都不包含任何机密:令牌随出示它的请求到达,从不写入配置文件。issuer 必须是 https 地址,除非授权服务器运行在本机——localhost、127.0.0.1 或 ::1;一个在其他任何主机上指定普通 http issuer 的监听器,无论以何种方式读取其密钥和调用方,都会在绑定任何内容之前被拒绝:每个客户端都会被引导到 issuer 获取令牌,因此通过普通 http,其授权码和令牌会不受保护地穿越网络;而如果密钥也从那里读取,位于该路径上的任何人都可能替换它们。

mcp.authorization.jwks_file 指定一个文件,其中保存用于验证令牌的密钥,而不是从授权服务器读取。省略它时,服务器会从该授权服务器的 well-known 地址读取元数据,并按其中发布的 jwks_uri 获取密钥,这是有网络访问的工作区的做法。该密钥地址遵循与 issuer 相同的规则,任一读取被重定向到的地址也同样如此:位于其他主机上的普通 http 地址永远不会被请求,需要这些密钥的令牌会得到 503 应答,直到授权服务器通过 https 发布其元数据和密钥。设置它后,授权服务器永远不会被联系——这正是声明了 offline: true 的工作区所需要的,而这样的工作区除非此项指定了文件,否则会在其监听器绑定之前被拒绝。它是一个路径,遵循上面的规则:相对路径以声明它的文件所在目录为基准解析,因此提交在该文件旁边的密钥集,无论从哪里启动服务器都能找到。该文件保存的是公开的验证密钥,也就是授权服务器发布的内容——不包含任何可用于签名的东西,也不包含任何机密。

mcp.allowed_origins 仅在请求携带 Origin 头时才会被查阅,实际上这意味着请求由浏览器发出。在此列出你所服务的 origin;指定了未列出 origin 的请求会被拒绝,而不携带该头的请求无论如何都会被处理。非浏览器客户端不会发送该头,也无需任何条目。条目与该头按精确匹配比较,因此请按浏览器发送的方式书写:小写的 scheme、://、小写的主机,仅当端口不是该 scheme 的默认端口时才加上 : 和端口——例如 https://studio.example.com,或者对于在你本机上提供的页面使用 http://localhost:3000——不带路径,也不带末尾的 /。任何其他形式的条目都永远无法匹配,会在加载此文件时被拒绝,并指出该条目。

mcp.limits 限制单个调用方可以请求的量——单个请求体可以多大、同时运行多少个请求,以及一个调用方每分钟可以发送多少个请求。这三项始终生效;没有任何值可以解除它们。第三项 requests_per_minute 按每个调用方分别计数,因此一个调用方大量发送请求不会影响其他调用方。

mcp.authorization.trusted_proxy 从前置代理读取调用方身份,而不是在此处校验令牌。 将 principal_header 设置为该代理用于说明调用方身份的头,并可选地将 scopes_header 设置为携带该调用方 scope 的头。两者都是 HTTP 头名称,例如 X-Forwarded-User——由字母、数字、连字符以及头名称允许的少数其他字符组成,不含空格或冒号;任何其他形式的名称会在加载此文件时被拒绝,并指出该键,因为没有请求能携带它。在该模式下完全不读取令牌,缺少 principal 头的请求会被拒绝。由于此时该头就是全部凭据,只有在其他任何东西都无法设置它的地方它才可信:除非 mcp.listen 是回环地址或 Unix socket,否则进程会在绑定之前被拒绝。省略该块时,本服务器自行校验令牌,这是默认行为;principal_header 为空的块会被拒绝,而不会被当作该默认行为。

mcp.deny_reach 从本部署中撤除某类作用范围。 服务器执行的每个操作都声明了其自身影响能波及多远——none 表示只读取或渲染、不留下任何东西的操作,workspace 表示在本进程所服务的工作区内写入的操作,registry 表示发布、签名或撤回的操作,machine 表示改变主机上所有工作区共享内容的操作。在此指定某一类,就会撤除所有达到该范围的工具:无论调用方的令牌携带什么,该工具都不会出现在任何调用方的工具列表中,对它的调用会被拒绝,并指出此设置。这使它成为部署的边界而非调用方的边界,任何凭据都无法解除它——一个只用于提供读取的服务器在此列出三个写入类,之后即使调用方的令牌携带所有 scope 也无法发布。省略它(默认)时,本部署承载调用方 scope 所允许的一切。不属于这四类之一的值会在加载此文件时被拒绝,而不是被忽略。无论此处如何设置,machine 类的操作都不会通过 HTTP 提供,因此指定它会被接受但不改变任何东西;aggrega-mcp.md 列出了各类范围以及允许它们的 scope。

mcp.announce_tools 收窄服务器公布的内容,它是与上面那个键不同的边界。 列出本服务器要公布的工具,按工具列表报告的写法书写,则恰好公布这些工具:被省略的工具不会出现在任何调用方的工具列表中,如果仍按名称调用它,会被拒绝,并指出此设置。省略该键(默认)时,服务器承载的每个工具都会被公布;写一个空列表则一个都不公布,因此这两种写法是不同的声明,不会替你填入默认值。它与 deny_reach 的区别在于各自拿走的东西。deny_reach 拿走的是能力:被撤除类别的操作在这里根本不被承载,任何凭据都无法恢复。announce_tools 只拿走公布——它省略的工具仍是服务器具备的能力——它针对的是限制自己注册工具数量的客户端,这种限制有时跨越它同时连接的所有服务器。两者都设置时以撤除为准,因此被撤除类别的工具无论此键如何指定都不会出现。没有任何工具对应的名称会让服务器在提供任何服务之前停止,并列出它实际拥有的工具,而不是留给你一个比你所要求的更窄的接口。与这里其他配置 http 传输所启动监听器的键不同,无论服务器使用哪种传输都会读取它,因为收窄所针对的客户端通常正是通过自身标准输入输出启动该进程的那个客户端;aggrega-mcp.md 说明了其余内容。

**mcp.health.listen 把存活检查和就绪检查放到单独的地址上。**为它指定一个采用 mcp.listen 两种形式之一的地址,第二个监听器就会在那里响应 GET /healthz(从进程运行起即返回 200)和 GET /readyz(在工作区解析完成且端点绑定之前返回 503,此后返回 200),这样负载均衡器就能在进程真正能够响应调用之前暂不转发流量。省略它,则任何地方都不响应这两项检查。它们永远不会在 mcp.listen 指定的地址上响应,该地址对它们返回 404,与它不提供服务的每个路径相同:在那里探测,就等于对一个拒绝其他一切请求的监听器进行未经认证的读取。与 mcp.listen 不同,这个地址不受限制,也不会拒绝任何地址——请将它指向回环地址或 Unix 套接字,这正是与本进程并列运行的监管程序所能访问的,并请注意,凡是能访问你所选地址的,都能读取这两项应答。

schema/other/aggrega-config.md 列出了上述每个键及其默认值(如有)。

识别项目根目录的其他方式

--workspace-root <path> 或与之对应的 AGGREGA_WORKSPACE_ROOT 直接指定根目录,并跳过发现过程。它指定的文件夹必须存在:路径不指向任何内容或指向文件时,命令会在执行任何其他操作之前被拒绝,拒绝信息会指明两者中是哪一个提供了该值,并按原样引用它。否则,发现过程从工作目录向上遍历,各类锚点按类别相互排序,而不是按远近排序:

  • 带有 workspace: 块的 .aggrega-config.yaml 直接胜出,无论它位于哪一层。即使已经越过下文所述类型的标记,遍历仍会继续向上查找这样的文件,因此上层显式标记的根目录总是优先于其下方偶然存在的标记。
  • 若没有,则由最近的下列标记确定根目录,在同一目录内按以下顺序排序:.aggrega/ 目录,然后是 aggregate*.yaml,然后是 release*.yaml,最后是 manifest*.yaml。
  • 如果都不满足,则使用工作目录——命令会运行,而不是拒绝启动。结果取决于工作区的命令——读取或写入工作区文档、读取或填充其制品缓存,或为其提供服务的命令——会在标准错误上警告一次:warning: <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace。结果不取决于哪个文件夹是根目录的命令则不输出任何内容,即使它读取配置也是如此:其中包括 aggrega version、aggrega config show、aggrega plugin list、aggrega registry list、aggrega explain 和 aggrega login。aggrega config capture 的工作是写入工作区自身的配置文件,它在这样的文件夹中不写入任何内容,并以一条说明这一点的错误退出。

在这样的文件夹中,不会向制品缓存写入任何内容。.aggrega/ 目录本身就是上述标记之一,因此在那里写入缓存,会仅仅因为曾在其中获取过某些内容而使该文件夹成为工作区。会填充缓存的命令——aggrega pull、先解析依赖项的构建、aggrega registry update、从注册表添加命令扩展插件——会在获取任何内容之前被拒绝,并指明该文件夹及两种解决办法:用 --workspace-root 或 AGGREGA_WORKSPACE_ROOT 指定工作区,或者为该文件夹添加一个带有 workspace: 块的 .aggrega-config.yaml。aggrega pin,以及对 Recipe 或 FeatureRecipe 执行的 aggrega push(它受旁边 entity.lock 所记录的固定版本约束),只会用实体完整写出的远程源填充缓存,即固定其版本或比较其固定版本时所获取的源:在它们将要获取此类源时,会以同样的方式在获取之前被拒绝。没有此类源的实体——完全没有源、只有本地源,或其坐标由各个 Release 填写——在那里的固定或发布与在其他地方无异。在那里进行的构建不会被拒绝,但其锁文件固定、而缓存中已不再保存的外部输入不会为修复而重新获取:渲染会收到同一句话来代替该输入,就像它收到离线状态的那句话一样,并报告这一情况。artifact_cache_dir 将缓存放在何处对此没有影响,因为该目录会拼接到所找到的根目录上。仅执行读取的命令仍会响应。

最后这种回退有一个例外。当没有任何方式指定根目录、且工作目录也不构成任何锚点时,针对单个 Release 或单个实体文档、并以绝对路径指定该文件的命令,会从该文件所在的文件夹向上重新发现根目录,并使用所找到的结果:该文件所属的工作区,或者若都没有,则使用该文件夹。该文件是指:aggrega build 和 aggrega pull 上 --release 指定的文件;传给 aggrega validate、aggrega lint 和 aggrega inspect 的 Release,否则为传给它们的文件;以及传给 aggrega pin、aggrega push 和 aggrega edit-document 的文档。因此,从项目外部构建项目的 Release 时,读取的是该项目自己的配置,与在项目内部运行命令时相同,命令输出的配置警告也属于该工作区。若该文件自己的文件夹也不构成任何锚点,该文件夹就是命令提示中指明的文件夹,也是不写入缓存的文件夹。相对路径按你运行命令所在的目录解析,不改变任何行为;已指定的根目录,或本身位于某个工作区内的工作目录,按原样使用。助手服务器对以绝对路径指定其 Release 或文档的调用应用同样的规则。

用 workspace: 块标记根目录是显式的选择,也是首选方式;文件和目录标记让尚未声明根目录的项目仍然可以构建。

显式指定全局文件

全局层按以下顺序解析:

  1. --config <path>,按单次调用指定的形式。
  2. AGGREGA_CONFIG 环境变量。
  3. 默认位置:在 Windows 上为 APPDATA 环境变量所指目录中的 aggrega\config.yaml,在其他平台上为 XDG_CONFIG_HOME 所指目录中的 aggrega/config.yaml,否则回退到 ~/.config/aggrega/config.yaml。

前两种方式指定的是明确的文件,因此不存在的路径会明确报错,而不是静默回退——你要求的是某个特定文件。读取配置的命令会停止并输出一句以该路径结尾的话,方便你复制。aggrega config init 是例外,因为创建该文件正是它的用途:它会创建指定的文件并加以说明。默认位置的文件存在时即被加载,不存在时则静默跳过。无论解析到哪个文件,你项目中的文件仍会叠加在它之上。

当以上都无法解析时——未指定任何文件,且读取默认位置所依据的变量也未设置——写入全局文件的命令会停止,并指明需要设置什么。环境变量按平台列出了每个位置所依据的变量。

这一选择同样决定了写入配置的命令写到哪里。使用 --config <path> 运行的命令从该文件读取配置,并将更改应用到同一个文件,因此一个命令写入的内容就是下一个命令读回的内容。

命令默认写入两个文件中的哪一个,取决于设置的性质:注册表等机器范围的工具配置写入全局文件,而 provider 绑定或套接字挂载等参与构建的设置写入项目中提交的文件,从而随项目一起流转。传入 --global 或 --workspace 可覆盖默认行为,命令会输出它所写入的文件。

另请参阅