Aggrega 工作区配置 schema
自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。
Schema id:https://aggrega.ai/schemas/aggrega-config-v1beta1.schema.json
由 aggrega CLI 读取的每个工作区的配置文件,位于 .aggrega-config.yaml。workspace 块是根标记:它的存在标记工作区根目录,且它只包含目录(catalog directories)。其他所有键都是设置,位于顶层,分为以下几类——内容从何处获取、如何固定和缓存(registry 选择、离线、自动拉取和固定行为、制品与已编译模块缓存的位置及大小上限),内容如何被信任(签名及签名验证行为),编写内容的评判有多严格(按规则的 lint 调节项、弃用的严格程度以及编写所用 release 的提示),哪些 Wasm 插件在整个工作区范围内挂载(治理、linter、导入器以及按目标的 provider 渲染绑定),以及 CLI 如何运行(并发、服务以及守护进程解析缓存的淘汰上限)。下面的属性是完整且权威的列表;本摘要列出的是类别而非键,因此新增键不会使其失实。扁平的顶层结构,没有 apiVersion/kind 外层封装,与 catalog 内容不同。Schema 演进准则:新增顶层键属于 SemVer 次版本(MINOR)升级(增量式);移除或迁移某个键,或收紧某个约束,属于 SemVer 主版本(MAJOR)破坏性变更。
顶层类型: object
属性
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
workspace | object | 否 | 工作区根标记。仅凭它的存在即可将该目录标记为工作区根;它只承载定义根的目录目录——即工作区自身的目录,以及为某个 Release 单独指定的目录。所有不定义根的设置都位于顶层,而不在此处。写 workspace: {} 可标记一个没有 vendored 目录目录的根。 |
default_registry | string | 否 | 当实体未显式指定注册表时,实体发布到并从中解析依赖的默认 OCI 注册表:aggrega push 发布到该处,aggrega pull 从该处获取。默认为 hub.aggrega.ai。可以写 registries 下某个条目的 name(此时代表该条目的 host);也可以写主机本身;或写主机后跟 / 和仓库路径,例如 ghcr.io/acme 或 harbor.example.com/platform。名称优先匹配:一个值如果是某个条目的 name,即代表该条目的主机,即使它的拼写也像一个主机,因此发布、拉取、签名验证以及每个按注册表的信任设置都使用这一个主机;如果有两个条目以该值命名,则因歧义而被拒绝;名称后跟路径也会被拒绝,因为名称代表条目的主机,而不代表其下的某个位置。其他任何值都必须是主机,且按其信任策略所保存的拼写书写:包含点的小写主机名(registry.example.com)、localhost、单个名称后跟端口(registry:5000)、IPv4 地址,或放在方括号中的 IPv6 地址([::1]),均可带可选的 :port,且不含协议、凭据、空白或大写字母——之后可选地跟一个仓库路径:由 / 连接的一个或多个由小写字母和数字组成的段,段内可用 .、_、__ 或短横线分隔,不含标签、摘要或末尾的 /。路径是发布和获取内容的位置:通过默认注册表发布的每个实体都发布在 <host>/<path>/ 下,通过它解析的每个实体也从该处获取,因此一方发布的内容另一方能够找到。路径从不参与注册表的信任判定:适用策略的 registries 条目、登录、签名要求和受信任身份都仅按主机查找。对于通过 HTTPS 访问的主机,端口 443 是该主机的默认端口,写出它会被拒绝,并给出不带端口时应写的拼写;localhost 及其他回环地址通过纯 HTTP 访问,因此 443 在那里是普通端口,会被保留。空值表示不指定默认注册表。该值在配置加载时判定,而不是由本 schema 判定,因为名称所指的条目可能声明在另一个配置文件中:它在读取所有配置文件和 AGGREGA_DEFAULT_REGISTRY 环境变量之后读取,无论由哪一处设置,都以相同措辞拒绝,并指明该文件或该变量。为单次调用指定发布目标的 --registry 标志也以同样方式与条目名称匹配;它携带的其他任何值可以是一个引用,该引用所指的主机同样须符合上述拼写,发布即落在该主机上,不带仓库路径。主机仅按拼写判定:不检查该名称能否解析,也不检查那里是否有注册表响应。默认值:"hub.aggrega.ai" |
offline | 布尔值 | 否 | 为 true 时,构建不联系任何注册表;只查询缓存的制品和 vendored 的目录内容。默认为 false。默认值:false |
auto_pull | 布尔值 | 否 | 为 false(默认)时,aggrega build 是只读的:它从不写入源固定(pin),缺失或不完整的按 Release 锁文件会使构建显式中止,并给出诊断,提示先运行 aggrega pull --release <release>。为 true 时,aggrega build 在构建前于进程内运行一个拉取步骤——将该 Release 的依赖解析到锁文件和缓存中——因此首次针对某个 Release 构建时无需显式的拉取步骤。同样的单次构建选择也可在命令行上通过 aggrega build --auto-pull 启用;pull 仍是锁文件的唯一写入者。offline: true 不会关闭拉取步骤:它基于本机已有的内容——缓存和本地目录目录——运行,而不访问注册表;两者都不包含的引用会使构建中止,并给出拉取自身的拒绝信息,指明该引用。默认值:false |
pin_sources_at_pull | 布尔值 | 否 | 为 false(默认)时,拉取不会在实体旁记录任何固定:对于该 Release 构建的、位于本工作区某个目录目录中的 Recipe 或 FeatureRecipe,如果实体旁的 entity.lock 没有为实体读取的每个输入记录固定——坐标完整写出的远程 source:、某个 artifacts 条目导入的文件,或实体旁本地 source: 的每个文件——拉取就会中止,并指明该实体、每个输入及其类别,以及作为记录步骤的 aggrega pin。固定是实体作者的步骤,因此无人固定的实体尚不能被使用。为 true 时,本工作区中的每次拉取都会改为对相同的实体运行该步骤,写入与 aggrega pin 相同的 entity.lock 字节;工作区若要使用他人未固定的实体,就是通过这种方式一次性记录其固定,而不是中止。填充自身锁文件的构建也是一次拉取,遵循此设置。无论此设置如何,aggrega pull --pin-sources 都会为单次调用执行固定,--pin-sources=false 则为单次调用执行中止。从缓存而非目录目录解析的实体没有可写入锁的位置,拉取从不对其固定或因其中止。默认值:false |
pin_sources_at_push | 布尔值 | 否 | 为 true 时,本工作区中的每次 aggrega push 都会在打包前对其发布的实体运行实体作者的固定步骤,因此该步骤写在实体旁的 entity.lock 会成为发布内容的一部分;为 false(默认)时,push 不运行固定步骤,并拒绝 entity.lock 未记录该步骤本应记录的全部固定的 Recipe 或 FeatureRecipe,同时指明 aggrega pin。该步骤写在实体旁,因此只在实体拥有可写位置时运行,而 push 总是具备这一点:它发布的是由其文档指定的实体。无论此设置如何,aggrega push --pin-sources 都会为单次调用执行固定,--pin-sources=false 则不执行。该步骤与 aggrega pin 运行的步骤相同,写入相同的字节。默认值:false |
artifact_cache_dir | string | 否 | 本地制品/内容缓存目录(注册表拉取内容、OCI 清单、编译后的 fixture)。默认为 .aggrega/cache。按照约定应加入 gitignore。无论命令从何处运行,该路径都相对于工作区根解释;绝对值会在配置加载时被拒绝,因为此设置的每个读取方都相对该根解析它,绝对路径会指向它们永远到不了的位置。缓存可以位于某个目录目录之内——默认值即是如此,因为目录目录通常就是工作区根——但它本身不能就是一个目录目录:目录扫描会跳过缓存,因此指向某个目录目录的值会将该目录的全部内容排除在扫描之外。指向工作区根本身的值(.,或任何可归约为它的写法)正是出于这个原因会在配置加载时被拒绝。指向其他任何目录目录的值不会被拒绝:它会正常加载,随后扫描在该目录中找不到任何内容,因此需要你自行确保缓存不在 workspace.catalog_dirs 所列的目录中。区别于 parse_cache(限制守护进程的内存解析缓存)和 compiled_module_cache(限制全机范围的编译模块存储)。默认值:".aggrega/cache" |
skip_signature_verification | 布尔值 | 否 | 全局的、显式告警的签名验证退出开关。为 true 时,所有注册表的签名验证都会被禁用,包括强制性的 hub 基线。用于紧急破例和开发场景;它从不静默——凡是拉取本应检查签名之处,都会发出警告,说明验证已被全局禁用。默认为 false。默认值:false |
build | object | 否 | 构建时的严格程度调节项和编写提示。authoring_release 为 LSP 提供一个 current Release 提示,用于内联诊断;halt_on_deprecated_severity 控制构建如何应对已弃用实体的使用;yaml_indent 设置每个渲染出的 YAML 产物的缩进宽度。 |
plugins | object | 否 | 工作区级别的 Wasm 插件挂载。每个插槽(governance、linter、importer)接受一个插件引用数组;构建按照各插槽的契约调用每个插件文档所述的入口函数。providers 列表将能力绑定到为其提供服务的 provider 渲染插件。 |
lint | object | 否 | 按规则设置的严格程度调节项。 |
parse_cache | object | 否 | 守护进程解析缓存的淘汰上限。两个上限同时生效——每次插入缓存后都会运行 LRU 淘汰循环,移除最近最少使用的条目,直到条目数和字节总量都在限制之内。任一项为零即表示 unbounded on that axis,适用于缓存只存在于单次调用的 CI 场景。不同于 artifact_cache_dir,后者是磁盘上的内容缓存。 |
compiled_module_cache | object | 否 | 磁盘上已编译模块缓存的大小上限。该缓存是编译器复用的机器码存储,使 Wasm 插件在每台机器上只编译一次,而不是每次构建都编译。它由机器上的所有工作区共享,因此如果你希望整台机器使用同一个值,应将此键放在全局配置文件中。该上限在每次调用时于加载任何插件之前应用一次,按编译时间从早到晚移除整个条目,直到剩余部分符合上限——绝不会在构建正在编译时进行。移除一个条目的代价只是之后的一次重新编译,因此可以安全地调低上限。aggrega cache status 报告存储的当前大小,aggrega cache evict --max-size 按命令行给出的上限按需裁剪它。不同于 artifact_cache_dir(拉取的注册表内容)和 parse_cache(守护进程的内存解析缓存)。 |
concurrency | object | 否 | 守护进程请求分发的并发设置。守护进程从单一 stdin 流读取请求,并通过一个消费有界请求队列的工作池处理每个请求;无论完成顺序如何,响应都按请求到达顺序输出。 |
serve | object | 否 | 守护进程(aggrega serve)的行为设置,用于供 IDE 集成使用的编译器即服务。 |
mcp | object | 否 | Model Context Protocol 服务器(aggrega mcp)的设置。transport 选择服务器的访问方式——通过进程的标准输入输出,或通过 HTTP——无论选择哪种都会读取它。announce_tools 在两种传输方式下也都会读取,因为客户端能看到哪些工具是服务器的属性,而与客户端如何访问它无关。其他所有键都用于配置 HTTP 传输启动的监听器,在服务器通过标准输入输出通信时不会使用——listen 也是如此,在那种情况下读取它只是为了让服务器能在错误流上用一行说明该地址未被使用。下面的每个键都会说明它属于哪一种。不同于 serve,后者配置编辑器后端守护进程。 |
registries | RegistryConfig[] | 否 | 按注册表主机划分的设置和签名信任策略。未在此列出的注册表使用默认值:存在的签名会被验证,缺失的签名会被容忍;hub.aggrega.ai 除外,即使没有显式条目,其内置基线也要求签名经过验证。为某个主机显式添加的条目会覆盖该主机的基线。默认值:[] |
signing | SigningConfig | 否 | 顶层签名块,适用于所有注册表:无密钥服务的 URL、可选的密钥文件路径,以及适用于所有注册表的信任立场(required 和 kinds)。按注册表设置的 signing 块会覆盖该主机的端点默认值,并携带作用于该主机的相同 required/kinds 立场——同一个名称,同一个职责,作用域由位置决定。顶层的 required/kinds 策略在配置层叠中单调地组合。安全性:此块不包含任何机密内容——OIDC 身份令牌从不作为配置字段(它在运行时通过标志或环境中的 OIDC 提供),而 key_path 是指向密钥文件的路径,从不是内联的密钥字节。 |
不允许其他属性。
aggrega-config.workspace
工作区根标记。仅凭它的存在即可将该目录标记为工作区根;它只承载定义根的目录目录——即工作区自身的目录,以及为某个 Release 单独指定的目录。所有不定义根的设置都位于顶层,而不在此处。写 workspace: {} 可标记一个没有 vendored 目录目录的根。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
catalog_dirs | string[] | 否 | 可选的目录(catalog)目录列表,此工作区从中读取本地实体,在回退到注册表之前查询。每个条目是一个文件系统路径,相对于声明它的文件解析。该列表是一个有序的先到先得搜索栈:最早列出且声明了某个标识的目录拥有该标识,后续目录中的相同标识会被遮蔽。工作区根目录下的 catalog 目录也会被读取,位于所有列出条目之后,且仅在其存在时读取——除非某个列出的条目已经包含它,此时它作为该条目的一部分被读取——因此列出一个目录是在工作区已读取内容的基础上增加,而不是替换。省略此键与将其写为空列表是两种不同的声明:省略时,工作区仍会读取 catalog;写为 [] 时,它完全不读取本地目录,工作区以此表明自己没有本地目录。在 releases 下拥有自己目录的 Release 会读取那些目录,而不是此列表。作用域为根:本地目录属于此工作区根,因此它们位于根标记上,而不是顶层。 |
catalog_dirs_append | string[] | 否 | 对生效的 catalog_dirs 列表的可选追加项。在每个优先级层,这里的条目会被拼接到已解析的基础列表之后,使工作区配置和全局配置能够组合目录,而不是相互遮蔽。同层交互:当在同一层同时指定 catalog_dirs 和 catalog_dirs_append 时,该层的解析值为基础列表后接追加列表。默认值:[] |
releases | ReleaseCatalogConfig 映射 | 否 | 某个 Release 自己的可选目录列表,适用于并列保存多个目录变体、并让每个 Release 基于其中之一构建的工作区。每个键是一个 Release 文件,写为相对于声明它的文件的路径;每个值包含 catalog_dirs 和 catalog_dirs_append,含义与它们在此块上的含义相同,作用域限于该 Release。此处列出的 Release 读取自己的 catalog_dirs,而不是此块的列表,随后读取自己的 catalog_dirs_append;省略 catalog_dirs 的条目保留此块的列表,并在其后追加自己的 catalog_dirs_append。搜索顺序、工作区根目录下的 catalog 目录以及空列表的含义,都与此块自身的列表相同;此映射未列出的 Release 仍完全按原样读取此块的列表。无论 Release 如何构建——在终端中、在编辑器中通过 aggrega serve,或通过 aggrega mcp——它都会读取这些目录,而 --catalog 目录在单次调用中仍优先于它们被搜索。指向不存在文件的条目会在配置加载时被拒绝,并指出该条目和文件,因此重命名 Release 不会悄无声息地改变它构建所基于的目录。跨配置文件时,每个 Release 的条目按此块自身键的方式组合:较近文件中该 Release 的 catalog_dirs 替换较远文件中的,而每个文件中针对它的 catalog_dirs_append 按级联顺序追加。AGGREGA_CATALOG_DIRS 设置此块的列表,不影响此处的任何条目。不涉及单个 Release 的操作——对整个目录的 lint 或验证、按名称查找实体,或编辑器列出工作区实体——读取此块的列表,而不是这些条目。 |
不允许其他属性。
aggrega-config.build
构建时的严格程度调节项和编写提示。authoring_release 为 LSP 提供一个 current Release 提示,用于内联诊断;halt_on_deprecated_severity 控制构建如何应对已弃用实体的使用;yaml_indent 设置每个渲染出的 YAML 产物的缩进宽度。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
authoring_release | string | 否 | Release YAML 文件的路径,LSP 将其视为内联诊断的 current Release 上下文。可选。 |
yaml_indent | integer | 否 | 每个渲染出的 YAML 制品的缩进宽度(以空格计)——docker-compose 文件、Helm chart 模板和 values,以及 Kubernetes manifests。默认为 2,即这些格式的约定宽度。最小值:2。最大值:9。默认值:2 |
halt_on_deprecated_severity | string(枚举) | 否 | 严重级别,取自有序集合 warning < error < retracted,已记录的弃用标记达到或高于该级别时会中止构建。它同时管控记录标记的两个位置:lockfile,用于构建逐字节复现的一切内容;以及其旁边的插件信任记录,用于以返回接受或拒绝裁决的角色挂载的插件——在 ir-verdict 或 render-verdict 处的 plugins.governance 挂载,以及每个 plugins.linter 挂载。一个开关,一条规则,覆盖两个存储。默认未设置,未设置意味着任何已记录的标记都不会中止构建:标记是针对你已固定的版本记录的,因此曾经成功的构建会继续成功。通知与解析是两个独立的维度,都不属于此开关。每个读取这两种记录之一的界面都会报告它固定的每个已弃用引用以及每个带有标记的受信任插件——无论严重级别——并给出其名称、严重级别和消息:aggrega build、aggrega validate --release、aggrega lint --release、面向编辑器的守护进程,以及 AI 原生的 build、describe 和 validate 工具。因此提高此阈值不会减少你得到的信息。此开关只管控构建:它会中止 aggrega build(以及 AI 原生的 build 工具,二者是同一操作),而报告类界面只会指出标记并继续运行。只有 retracted 标记会影响引用解析到哪个版本,且这发生在 aggrega pull 选择版本时,而非构建时。允许的值:"warning"、"error"、"retracted" |
不允许其他属性。
aggrega-config.plugins
工作区级别的 Wasm 插件挂载。每个插槽(governance、linter、importer)接受一个插件引用数组;构建按照各插槽的契约调用每个插件文档所述的入口函数。providers 列表将能力绑定到为其提供服务的 provider 渲染插件。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
governance | PluginRef[] | 否 | 治理插槽插件。每个条目指明它所挂接的流水线 role(annotation-transform、label-transform、ir-verdict 或 render-verdict);该角色同时决定插件可以输出的内容及其默认入口函数(annotation-transform → transform_annotations;label-transform → mutate;ir-verdict → verdict_ir;render-verdict → verdict_render)。默认值:[] |
governance_append | PluginRef[] | 否 | 对有效 governance 列表的仅追加补充。此处的条目在每个优先级层上被拼接到解析后的基础列表之后,使工作区配置和全局配置能够组合治理挂接,而不是相互遮蔽。默认值:[] |
linter | PluginRef[] | 否 | Linter 插槽插件。默认入口函数:lint_rules。linter 插件的导出必须以 lint_ 开头,因此这些条目上的 function: 指定的是带有该前缀的导出。默认值:[] |
linter_append | PluginRef[] | 否 | 对有效 linter 列表的仅追加补充。与 governance_append 具有相同的“组合而不遮蔽”语义。默认值:[] |
importer | FixedEntryPluginRef[] | 否 | Importer 插槽插件。该插槽调用 import 入口函数;挂接条目不指定入口函数。默认值:[] |
importer_append | FixedEntryPluginRef[] | 否 | 对有效 importer 列表的仅追加补充。与 governance_append 具有相同的“组合而不遮蔽”语义。默认值:[] |
providers | FixedEntryPluginRef[] | 否 | 按能力选择 provider。每个条目将一个 provider 能力(Recipe 通过 spec.capability 绑定的裸能力名,例如 helm 或 compose)绑定到提供该能力的 provider 渲染插件的裸标识(Plugin 实体的标识,即用斜杠连接的 metadata.pluginType 和 metadata.name,例如 provider/helm),并可在末尾附加 :version,其形式与版本固定相同,共三种(裸形式、精确版本 :1.0.0,或主版本兼容范围 :^1.0.0)。这是联邦目录中多个 provider 插件提供同一能力时用于消歧和覆盖的入口:该绑定选择由哪个发布者的插件渲染该能力。当某个能力只由一个 provider 插件提供时,无需任何条目。在组合后的列表中,每个能力只允许一个条目;重复的能力会使解析明确中止。解析发生在 pull 时:pull 将解析出的绑定记录到每个 Release 的锁文件中,build 读取该锁文件——pull 之后对此处的修改要到下一次 pull 才会生效,因此构建输出不受其影响(确定性输出)。每次构建和每次验证 Release 时,也会检查此处的每个条目,无论是否有 Recipe 请求其能力:若条目指定的插件为构建所持有,但该插件不提供该条目的能力,则中止,并指出该插件提供的能力,以及存在时一处编辑之差的拼写;若条目只指定能力而未指定插件,且构建读取的 provider 插件中没有提供该能力的,则报告为警告而不中止,因为提供该能力的插件可能只有另一个 Release 会读取;若条目对应的能力有插件提供,但本 Release 从未请求,则合法且不报告任何内容,因为条目是为整个工作区编写的,而一次构建只针对一个 Release。包含冒号的 capability 会在加载配置时被拒绝:Recipe 的 spec.capability 被解读为最后一个冒号之前的能力加上其后的版本固定,因此没有 Recipe 能够匹配这样的条目。对于无歧义提供的能力,缺少条目不是错误;对于有歧义提供的能力,缺少条目会使 pull 明确中止,并列出候选插件。版本共存得以保留:绑定按能力选择插件仓库,而每个 Recipe 自身的 spec.capability 版本固定在该仓库内选择版本,因此固定同一 provider 不同版本的两个 Recipes 仍可共存。默认值:[] |
providers_append | FixedEntryPluginRef[] | 否 | 对有效 providers 列表的仅追加补充。此处的条目在每个优先级层上被拼接到解析后的基础列表之后,使工作区配置和全局配置能够组合 provider 绑定,而不是相互遮蔽。与 governance_append 具有相同的“组合而不遮蔽”语义。每个能力一个条目的规则适用于组合后的列表,因此追加的条目若指定了已由较低层绑定的能力,会使解析明确中止。默认值:[] |
cli | CLIPluginRef[] | 否 | 作为顶层 aggrega 命令安装的 CLI 扩展插件。每个条目通过已解析且固定版本的制品引用,以及安装时该引用解析得到的 guest 字节的内容摘要,固定一个 CLI 插件。与其他四个横切插槽列表不同(它们的基础列表在配置级联中整体替换),CLI 列表是组合的:全局配置中的 CLI 插件在每个工作区注册其命令,工作区配置中的插件只在该项目中注册,两者会一起注册——因此它不需要 _append 配套键。每个插件提供的命令名和帮助来自插件自身的自描述,从以 digest 为键的磁盘 describe 缓存中读取(缓存冷启动时回退为加载 guest);列表只保存固定信息。调用命令时,会重新计算已解析字节的哈希并与 digest 比较;不匹配时命令明确中止并提示重新固定,因此字节在固定之后发生变化的插件绝不会在不被察觉的情况下运行。默认值:[] |
不允许其他属性。
aggrega-config.lint
按规则设置的严格程度调节项。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
publishing_discipline | object | 否 | 发布 linter 规则集的工作区级开关。allow_* 标志可放宽单项不鼓励检查。制品不可变性不能在此配置:aggrega push 无条件拒绝覆盖已发布的版本。 |
不允许其他属性。
aggrega-config.lint.publishing_discipline
发布 linter 规则集的工作区级开关。allow_* 标志可放宽单项不鼓励检查。制品不可变性不能在此配置:aggrega push 无条件拒绝覆盖已发布的版本。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
allow_dynamic_refs | 布尔值 | 否 | 为 true 时,publishing-linter 接受目录内容中的 $dynamicRef / $dynamicAnchor JSON Schema 构造。默认为 false;不建议使用这些构造,因为它们使编译期的 schema 组合变为非局部的。默认值:false |
allow_id_overrides | 布尔值 | 否 | 为 true 时,publishing-linter 接受实体 schema 内容中子 schema 上的 $id 覆盖。默认为 false;$id 覆盖会破坏解析器和 JSON Schema 验证器都依赖的“每个 schema 一个规范标识符”约定。默认值:false |
allow_direct_x_aggrega_extensions | 布尔值 | 否 | 为 true 时,构建期的不建议用法检查接受直接写在 schema 内容中的 x-aggrega-selector 和 x-aggrega-inject 关键字。默认为 false;推荐的编写方式是 usesSchema(用于依赖插槽)或 featuresSchema(用于凭据绑定),编译器会将其组合为这些关键字。默认值:false |
allow_aggrega_ai_prefix | 布尔值 | 否 | 为 true 时,publishing-linter 接受在其规范上下文之外使用保留的 aggrega.ai/ 和 feature.aggrega.ai/ 命名空间的注解键。保留前缀规则检查目录实体的 metadata.annotations:裸 aggrega.ai/ 前缀为平台原生(无论此标志如何,知名注解键均豁免);feature.aggrega.ai/ 前缀仅在 Feature 类型上是规范的。默认为 false。当企业工具确有需要使用保留前缀时,运维人员可设置此项;它会同时放宽这两个前缀。默认值:false |
allow_nonstandard_names | 布尔值 | 否 | 为 true 时,publishing-linter 接受不遵循项目文档所述命名约定的目录实体名称。默认为 false;一致的命名对解析器、标签选择和评审者的使用体验至关重要。默认值:false |
allow_category_mismatches | 布尔值 | 否 | 为 true 时,publishing-linter 不再应用 category-matches-directory 规则。标准目录约定要求 core/false |
allow_undeclared_recipe_provides | 布尔值 | 否 | 为 true 时,publishing-linter 不再应用 provides-declared-by-component 规则。该规则会报告 Recipe 在 spec.provides 中发布、但其 spec.implements 所指 Component 未在其 spec.schema 的 provides 支柱中声明的每个键。两者是不同的面:Recipe 发布的是使用方收到的值,而 Component 声明的是 inject from: 引用所据以检查的输出契约——因此一个已发布但未声明的键会使此类引用中止。除此之外,Recipe 发布的内容多于其 Component 所声明的,在构建时是被接受的,这就是该发现仅为建议、而非拒绝发布的原因。默认为 false。默认值:false |
allow_connection_credential_mismatches | 布尔值 | 否 | 为 true 时,publishing-linter 不再应用 connection-credential-matches-target-key 规则,该规则由 aggrega lint --release 对其指定的 Release 运行:包括该 Release、它部署的 Aggregate,以及该 Aggregate 的实例所使用的 Components。对于目标声明了其要求调用方提供的密钥的每个连接,该规则比较两端所引用的内容:连接出示的凭据,以及目标在其自身槽位中持有的密钥。它会报告两端指向不同 secret 的情况,以及只在一端声明了密钥的情况,且从不引用其中任何一个的内容。两端都看不到对方的附加项,因此两者只能依靠编写规范保持一致——通常由同一个参数同时提供给两端——而构建无论如何都会接受它们,这就是该发现仅为建议的原因。两端有意不同的工作区可在此选择退出。默认为 false。默认值:false |
不允许其他属性。
aggrega-config.parse_cache
守护进程解析缓存的淘汰上限。两个上限同时生效——每次插入缓存后都会运行 LRU 淘汰循环,移除最近最少使用的条目,直到条目数和字节总量都在限制之内。任一项为零即表示 unbounded on that axis,适用于缓存只存在于单次调用的 CI 场景。不同于 artifact_cache_dir,后者是磁盘上的内容缓存。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
max_entries | integer | 否 | 缓存的解析结果数量上限。默认 1000。0 禁用条目数维度(不会因条目数触发淘汰)。最小值:0。默认值:1000 |
max_bytes | integer | 否 | 缓存所持有文档的累计大小上限,以字节为单位。默认 100000000(100 MB)。0 禁用字节维度(不会因字节总数触发淘汰)。最小值:0。默认值:100000000 |
不允许其他属性。
aggrega-config.compiled_module_cache
磁盘上已编译模块缓存的大小上限。该缓存是编译器复用的机器码存储,使 Wasm 插件在每台机器上只编译一次,而不是每次构建都编译。它由机器上的所有工作区共享,因此如果你希望整台机器使用同一个值,应将此键放在全局配置文件中。该上限在每次调用时于加载任何插件之前应用一次,按编译时间从早到晚移除整个条目,直到剩余部分符合上限——绝不会在构建正在编译时进行。移除一个条目的代价只是之后的一次重新编译,因此可以安全地调低上限。aggrega cache status 报告存储的当前大小,aggrega cache evict --max-size 按命令行给出的上限按需裁剪它。不同于 artifact_cache_dir(拉取的注册表内容)和 parse_cache(守护进程的内存解析缓存)。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
max_bytes | integer | 否 | 已编译模块缓存在磁盘上所占字节数的上限。默认 53687091200(50 GiB),这是一个阻止无限增长的上限,而非需要时刻感知的预算——单个已编译插件可达数百 MB,因此构建大量插件版本的机器会累积数 GB。应将其设置为高于单次构建所编译的量:上限在构建编译任何内容之前应用,因此低于单次构建自身工作集的上限会使每次构建都丢弃并重新编译相同的模块,缓存也就不再节省任何东西。由于上限先被应用,构建随后才写入其编译的内容,因此在两次构建之间缓存可能超过上限;它会在下一次构建开始时再次被修剪。0 禁用上限(缓存无限增长,且不会自动删除任何内容)。由于缓存是所有工作区共享的一个目录,即使项目自身的文件设置了此上限,它也不是按项目生效的:该值的解析方式与其他所有键相同,更近的文件优先,但缓存仍只有一个大小。生效的上限来自最近一次构建,因此两个设置了不同上限的项目会轮流生效,其中一个项目的较低上限会丢弃另一个项目编译的机器码。在全局配置文件中设置一次,才能让整台机器得到统一的值。aggrega config show --origin 会列出每项设置的生效值来自哪个文件。最小值:0。默认值:53687091200 |
不允许其他属性。
aggrega-config.concurrency
守护进程请求分发的并发设置。守护进程从单一 stdin 流读取请求,并通过一个消费有界请求队列的工作池处理每个请求;无论完成顺序如何,响应都按请求到达顺序输出。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
pool_size | integer | 否 | 处理请求队列的工作线程数。默认为 4,即最多并发分派四个请求;设为 1 则按到达顺序串行运行请求。小于 1 的值会在守护进程启动时提升为 1。最小值:1。默认值:4 |
不允许其他属性。
aggrega-config.serve
守护进程(aggrega serve)的行为设置,用于供 IDE 集成使用的编译器即服务。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
build_on_inspect | 布尔值 | 否 | 守护进程在检查 IR 图时是否运行制品渲染阶段,从而使 aggrega build 在渲染时产生的建议也作为编辑器问题显示。它不会增加任何导致构建中止的检查。无论哪种设置都不会向磁盘写入任何内容——没有渲染的制品、没有输出目录、没有锁文件——并且渲染阶段从不修改图,因此当检查返回图时,两种情况下返回的是同一个图。默认为 false,与 aggrega inspect 一致:该终端命令在检查图时不会进入渲染阶段,因此同样不会产生此类建议,而不产生建议的编辑器检查向你显示的内容与终端相同。设为 true 可要求编辑器提供这一额外层。默认值:false |
lint_on_validate | 布尔值 | 否 | 守护进程在验证目录实体时是否运行发布约定检查,从而使 aggrega lint 针对该实体报告的发现也作为编辑器问题显示。这些发现仅为建议:引发它们的文档仍然通过验证,其 Release 仍然可以解析和渲染。只运行读取本地内容的检查——不查询任何注册表、不获取任何内容、也不写入任何内容——并且它针对编辑器持有的缓冲区而非磁盘上的文件进行评估,因此你更正的名称在保存之前就不再被报告。默认为 false:编辑器会话报告文档是否正确,在你要求第二层之前,不说明实体是否可发布。设为 true 即可要求。与此键无关,编辑器始终可以直接请求该检查,这也是与先前已发布版本进行发布前比较的途径。默认值:false |
不允许其他属性。
aggrega-config.mcp
Model Context Protocol 服务器(aggrega mcp)的设置。transport 选择服务器的访问方式——通过进程的标准输入输出,或通过 HTTP——无论选择哪种都会读取它。announce_tools 在两种传输方式下也都会读取,因为客户端能看到哪些工具是服务器的属性,而与客户端如何访问它无关。其他所有键都用于配置 HTTP 传输启动的监听器,在服务器通过标准输入输出通信时不会使用——listen 也是如此,在那种情况下读取它只是为了让服务器能在错误流上用一行说明该地址未被使用。下面的每个键都会说明它属于哪一种。不同于 serve,后者配置编辑器后端守护进程。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
transport | string(枚举) | 否 | 服务器的访问方式:stdio 通过进程的标准输入和输出使用该协议,以子进程方式启动该命令的客户端即通过这种方式访问它;http 在 listen 指定的地址上通过 HTTP 提供服务,当 tls 指定了证书和密钥时则通过 HTTPS 提供服务。aggrega mcp --transport stdio|http 会在单次调用中覆盖此键。默认为 stdio,因此从不指定传输方式的工作区无论此块包含什么,都通过标准输入和输出提供服务——只有在此处或命令行上选择了 http 时才会启动监听器。任何其他值都会在加载配置时被拒绝。对于调用方通过网络访问的服务器,请在其配置中设置 http;在客户端自行启动服务器的情况下请不要设置:选择 stdio 时,listen 中的地址不会被使用,服务器会在其错误流上用一行说明这一点。允许的值:"stdio"、"http" 默认值:"stdio" |
listen | string | 否 | 选择 HTTP 传输时监听器绑定的地址。它指定在何处监听,不做任何选择:传输方式由 transport 选择,选择 stdio 时此键不会被使用。接受两种形式:用于 TCP 地址的 host:port,以及 unix: 后跟文件系统路径,用于 Unix 域套接字。aggrega mcp --listen <address> 会在单次调用中覆盖此键。默认为空,HTTP 传输需要从两者之一获得地址:两者都没有时,选择它的启动会在任何绑定之前被拒绝。明文地址——即 tls 下没有证书和密钥的地址——只在回环地址(127.0.0.1、::1,或解析为其中之一的 localhost)或 Unix 套接字上被接受,这是前置代理终止 TLS 时服务器采用的形式;任何其他地址都会在任何绑定之前被拒绝,并指出 mcp.tls.cert_file 和 mcp.tls.key_file。设置了 authorization.trusted_proxy 时,无论是否有证书,都只接受这两种形式,因为只有在除代理之外无人能设置某个标头时,该标头才能作为凭据被信任。默认值:"" |
tls | object | 否 | 用于在服务进程内终止 TLS 的证书和密钥。同时设置两者即可直接从 listen 指定的监听器提供 HTTPS 服务。两者都不设置则提供明文服务,这会将 listen 限制在回环地址或 Unix 套接字上——这是前置代理持有证书时应采用的形式。两个键都是磁盘上文件的路径;两者都不内联保存密钥材料。 |
allowed_origins | string[] | 否 | 请求的 Origin 标头中接受的源。Origin 标头指定了此列表未包含的源的请求会以 403 被拒绝;指定了列表中的源,或完全不带 Origin 标头的请求会得到服务。条目与标头精确比较,因此每个条目都应按浏览器发送源的方式书写:小写的协议、://、小写的主机——名称、IPv4 地址或方括号中的 IPv6 地址——以及端口不是协议默认端口时的 : 加端口,其后不带任何内容。例如 https://app.example.com 或 http://localhost:3000。任何其他形式的条目都永远不可能等于浏览器发送的内容,因此会在加载配置文件时被拒绝,并指出该文件和该条目:带有末尾 / 或路径的条目(https://app.example.com/)、没有协议的条目(app.example.com),以及包含大写字母或空格的条目。默认为空,因此不接受任何源,只有不发送 Origin 标头的调用方才会得到服务。因此,基于浏览器的客户端需要在此处列出其源;非浏览器客户端不发送此类标头,不需要条目。每个条目都匹配模式 ^[a-z][a-z0-9+.-]*://(?:[a-z0-9._-]+|\[[0-9a-f:.]+\])(?::[0-9]{1,5})?$。默认值:[] |
limits | object | 否 | HTTP 监听器对其接受的流量施加的上限,使单个调用方无法耗尽服务进程。它们限制单个请求的大小、同时运行的请求数量,以及单个调用方的发送速度。这些上限都无法关闭。 |
authorization | object | 否 | 此服务器就其调用方所出示的 bearer 令牌所做的声明:由哪个授权服务器签发令牌、此服务器为自身发布的地址(即令牌所针对的资源),可选地指定一个用于读取该授权服务器验证密钥的文件,以及可选地指定前置代理在代为验证令牌时所设置的标头。只要选择了 HTTP 传输,issuer 和 resource 就是必需的,缺少它们时监听器会在绑定任何地址之前被拒绝;通过标准输入输出通信的服务器不读取其中任何一项。两者都会发布在监听器提供的 OAuth 受保护资源元数据文档中,这是 HTTP 调用方无需提供凭据即可获得的唯一响应,因为客户端要读取它才能得知从何处获取令牌。此块不包含任何机密材料:令牌由调用方在其发出的请求中出示,从不是配置字段;jwks_file 指定的是公开的验证密钥,而非任何用于签名的内容。 |
deny_reach | string (enum)[] | 否 | 无论调用方的令牌如何声明,此服务器都不承载的作用范围类型。每个操作都声明其自身影响所及的范围——none 表示只读取或渲染、不留下任何内容的操作,workspace 表示在此进程所服务的工作区内写入的操作,registry 表示发布、签名或撤回的操作,machine 表示更改主机上所有工作区共享内容的操作——在此指定某一类型,即从此服务器中撤回该类型的所有工具。被撤回的工具对所有调用方都不会出现在工具列表中,也不会出现在 describe-capabilities 的应答中;若仍然调用,请求会被拒绝并指明此设置,因为没有任何 scope 能够允许它。默认为空,因此服务器承载其调用方 scope 所允许的一切。这是服务器对自身设置的限制,叠加在 scope 为每个调用方设置的限制之上:只提供读取的服务器在此列出三种写入类型,此后即使调用方的令牌携带所有 scope,也无法发布。指定 machine 会被接受但不改变任何东西——该类型的工具根本不会通过 HTTP 提供,这是传输方式的属性而非一项设置。在监听器启动时读取:四种取值之外的值会在加载配置时被拒绝,更改它需要重启。服务器通过标准输入输出通信时完全不读取此项,此时调用方就是启动该进程的人。每个条目允许的值:"none"、"workspace"、"registry"、"machine"。默认值:[] |
announce_tools | string[] | 否 | 此服务器公布的工具,名称与工具列表报告的完全一致。省略此键,则公布此服务器承载的所有工具,这正是遵循该协议的客户端所期望的:客户端获取完整的工具列表,并自行决定向模型呈现其中多少。写入一个列表,则恰好公布这些工具——未列出的工具不会出现在工具列表中,不会出现在 describe-capabilities 的应答中,按名称调用时会被拒绝并指明此设置。写入空列表,则不公布任何工具。当另一端的客户端限制其注册的工具数量时(有些客户端将该上限应用于其同时连接的所有服务器),设置此项并列出该客户端所需的工具。它只缩小公布的范围,仅此而已:它无法放宽 deny_reach(后者直接撤回某项能力),也无法放宽调用方令牌携带的 scope。在此列出但属于 deny_reach 所撤回类型的工具仍不出现在工具列表中,调用时会被拒绝并指明该设置;在此列出但调用方 scope 不允许的工具仍会列出,对它的调用会被拒绝并指明可允许它的 scope。每个名称都必须是此二进制文件所承载的:没有对应工具的名称会在服务器启动时被拒绝,否则要求更窄接口的人会在毫无提示的情况下得到另一个接口。cli- 系列中的名称(在单独进程中运行 aggrega 命令)在两种传输上都会被接受,但通过 HTTP 不公布任何内容,因为 HTTP 上不向任何调用方提供此类工具。在两种传输上都于服务器启动时读取,因此公布的集合在进程生命周期内固定,更改它需要重启。 |
health | object | 否 | 监管程序询问此进程是否存活、是否已准备好响应调用的位置。这两项检查在单独的地址上应答,从不在 listen 指定的地址上应答:发往该端点的每个请求都携带 bearer 令牌,若在那里应答探测,就会让任何能访问该端点的一方无需认证即可读取进程状态,并且可以随意让它干活。无论是否携带令牌,该端点对 /healthz 和 /readyz 都返回与其对所有不提供服务的路径相同的 404。 |
不允许其他属性。
aggrega-config.mcp.tls
用于在服务进程内终止 TLS 的证书和密钥。同时设置两者即可直接从 listen 指定的监听器提供 HTTPS 服务。两者都不设置则提供明文服务,这会将 listen 限制在回环地址或 Unix 套接字上——这是前置代理持有证书时应采用的形式。两个键都是磁盘上文件的路径;两者都不内联保存密钥材料。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
cert_file | string | 否 | 监听器所出示的 PEM 证书链的路径,在进程启动时读取。须与 key_file 一起设置。默认为空,此时监听器提供明文服务,listen 仅限于回环地址或 Unix 套接字。默认值:"" |
key_file | string | 否 | cert_file 中证书对应的 PEM 私钥的路径,在进程启动时读取。须与其一起设置。这是文件路径,从不是内联的密钥材料。默认为空,此时监听器提供明文服务,listen 仅限于回环地址或 Unix 套接字。默认值:"" |
不允许其他属性。
aggrega-config.mcp.limits
HTTP 监听器对其接受的流量施加的上限,使单个调用方无法耗尽服务进程。它们限制单个请求的大小、同时运行的请求数量,以及单个调用方的发送速度。这些上限都无法关闭。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
max_body_bytes | integer | 否 | 监听器接受的最大请求体,以字节为单位。请求体超过此值的请求会以 413 被拒绝,且超出上限的部分不会被读取。默认为 4194304(4 MiB),远高于携带完整编写文档的工具调用,又远低于足以让单个调用方占用进程大量内存的大小。最小值为 1,因此没有任何值能关闭此上限;如果调用方确实需要发送更大的文档,请调高此值。最小值:1。默认值:4194304 |
max_concurrent_requests | integer | 否 | 监听器同时运行的请求数。当已有这么多请求在处理时到达的请求会以 503 被拒绝而不是排队,这样调用方会被告知重试,而不是在其看不到的工作后面等待。默认为 16,既为若干并发工具调用留出空间,又能让小型主机保持响应;在更大的主机上可调高此值。最小值为 1,因此没有任何值能关闭此上限。最小值:1。默认值:16 |
requests_per_minute | integer | 否 | 单个调用方每分钟可发送的请求数。它按调用方而非按服务器计数——依据调用方令牌所指定的主体,或可信代理所声明的身份——因此一个繁忙的调用方不会耗尽另一个调用方的配额。调用方可以一次突发发送这么多请求;之后配额会匀速补充,每 60 / requests_per_minute 秒增加一个请求,配额用尽时到达的请求会以 429 被拒绝。默认为 120,即持续每秒两个:远高于驱动工作区的助手所发送的量,同时仍能限制陷入循环的客户端。最小值为 1,因此没有任何值能关闭此上限。最小值:1。默认值:120 |
不允许其他属性。
aggrega-config.mcp.authorization
此服务器就其调用方所出示的 bearer 令牌所做的声明:由哪个授权服务器签发令牌、此服务器为自身发布的地址(即令牌所针对的资源),可选地指定一个用于读取该授权服务器验证密钥的文件,以及可选地指定前置代理在代为验证令牌时所设置的标头。只要选择了 HTTP 传输,issuer 和 resource 就是必需的,缺少它们时监听器会在绑定任何地址之前被拒绝;通过标准输入输出通信的服务器不读取其中任何一项。两者都会发布在监听器提供的 OAuth 受保护资源元数据文档中,这是 HTTP 调用方无需提供凭据即可获得的唯一响应,因为客户端要读取它才能得知从何处获取令牌。此块不包含任何机密材料:令牌由调用方在其发出的请求中出示,从不是配置字段;jwks_file 指定的是公开的验证密钥,而非任何用于签名的内容。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
issuer | string | 否 | 签发此监听器所接受令牌的授权服务器的地址,按该服务器声明其自身颁发者标识符的方式书写,例如 https://login.example.com。它发布在受保护资源元数据文档的 authorization_servers 列表中,客户端由此得知从何处为此监听器获取令牌。默认为空,这不是可用的值:除非此项包含完整地址(含 scheme 和主机),否则监听器会在任何绑定发生之前被拒绝。除非授权服务器运行在本机上,否则它必须是 https 地址:普通 http 仅接受回环主机,例如 localhost、127.0.0.1 或 ::1;任何其他主机上的普通 http 颁发者都会在任何绑定发生之前被拒绝,并指明此键、要求提供 https 地址。无论密钥是从颁发者读取、从 jwks_file 读取,还是由前置的 trusted_proxy 检查令牌,这一点都成立,因为每个客户端都会被引导至颁发者获取其令牌。默认值:"" |
resource | string | 否 | 此服务器为自身发布的地址,即调用方访问它时所用的地址,例如 https://mcp.example.com/mcp。请写调用方实际使用的地址,包括前置代理所呈现的主机,因为这是客户端在为此服务器申请令牌时交给授权服务器的标识符,并且它会原样发布为受保护资源元数据文档的 resource 字段。该文档的提供位置由此地址推导而来,即在主机与路径之间插入 /.well-known/oauth-protected-resource:发布为 https://mcp.example.com/mcp 的服务器在 https://mcp.example.com/.well-known/oauth-protected-resource/mcp 提供该文档,同时也在其后不带任何内容的该 well-known 路径上提供,这是客户端第二个查找的位置。仅当此地址位于令牌所列的受众之中时,令牌才会被接受。默认为空,这不是可用的值:除非此项包含完整地址(含 scheme 和主机),否则监听器会在任何绑定发生之前被拒绝。默认值:"" |
jwks_file | string | 否 | 一个文件的路径,该文件保存用于验证此服务器所接受令牌的 JSON Web Key Set,在进程启动时读取。默认为空,这是通常情况:密钥从授权服务器本身读取,方法是询问 issuer 在何处发布密钥并从其指明的地址获取;当到达的令牌由当前持有的密钥集中没有的密钥标识符签名时,会重新读取一次。在工作区离线时设置此项,此时若未设置,监听器会在任何绑定发生之前被拒绝,因为离线工作区不发出任何网络请求,没有其他方式获取密钥;此时该文件保存唯一被接受的密钥,且永远不会联系授权服务器。该文件保存公开的验证密钥,绝不保存任何用于签名的内容。相对路径相对于声明它的配置文件所在目录解析。默认值:"" |
trusted_proxy | object | 否 | 从前置代理设置的请求头中读取调用方身份,而不是在此处验证 bearer 令牌。仅在以下两点同时成立时设置此项:前置代理自行验证令牌,并且除该代理外没有任何东西能访问监听器。设置此项后,listen 必须是回环地址或 Unix 套接字,任何其他地址都会在任何绑定发生之前被拒绝,并指明这两个设置。一个请求头的可信程度恰好取决于能够设置它的调用方集合,而在网络可达的地址上,每个调用方都能设置任意请求头,因此在此类地址上以此模式运行的监听器会让每个调用方都能冒充任何人。设置此项后完全不读取令牌:既不从 Authorization 请求头读取,也不从其他任何地方读取,也不获取任何密钥集;调用方身份即 principal_header 的值,未携带该请求头的请求会得到 401 响应,并且只读取此处指定的两个请求头。省略此项(即默认情况),此服务器将自行验证 bearer 令牌。 |
不允许其他属性。
aggrega-config.mcp.authorization.trusted_proxy
从前置代理设置的请求头中读取调用方身份,而不是在此处验证 bearer 令牌。仅在以下两点同时成立时设置此项:前置代理自行验证令牌,并且除该代理外没有任何东西能访问监听器。设置此项后,listen 必须是回环地址或 Unix 套接字,任何其他地址都会在任何绑定发生之前被拒绝,并指明这两个设置。一个请求头的可信程度恰好取决于能够设置它的调用方集合,而在网络可达的地址上,每个调用方都能设置任意请求头,因此在此类地址上以此模式运行的监听器会让每个调用方都能冒充任何人。设置此项后完全不读取令牌:既不从 Authorization 请求头读取,也不从其他任何地方读取,也不获取任何密钥集;调用方身份即 principal_header 的值,未携带该请求头的请求会得到 401 响应,并且只读取此处指定的两个请求头。省略此项(即默认情况),此服务器将自行验证 bearer 令牌。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
principal_header | string | 是 | 前置代理放入调用方身份的请求头,例如 X-Forwarded-User。它按 HTTP 请求头名称书写:字母、数字和连字符,以及请求头名称可包含的其他字符(!#$%&'*+.^_|~ 和反引号),不含空格、冒号或其他分隔符。任何其他形式的名称都会在配置文件加载时被拒绝,并指明该文件和键,因为没有请求能携带这样的请求头。空名称同样会被拒绝:它会让此服务器在配置块声明由前置代理检查令牌的同时仍自行检查令牌。要关闭此模式,请省略 trusted_proxy。请求头的值按原样采用,不与任何内容比较,这与此服务器自行验证的令牌的主体被记录且不与任何内容比较的方式相同。在此模式下它就是全部凭据,因此只要设置了 trusted_proxy 就必须提供它,未携带它到达的请求会得到 401 响应。模式:^[!#$%&'*+.^_`|~0-9A-Za-z-]+$。 |
scopes_header | string | 否 | 前置代理放入调用方被授予的 scope 的请求头,以空格分隔,例如 X-Forwarded-Scopes。它按 HTTP 请求头名称书写,形式与 principal_header 相同,或留空。任何其他形式的名称都会在配置文件加载时被拒绝,并指明该文件和键,因为没有请求能携带这样的请求头,也就没有调用方会被授予任何 scope。默认为空,即不为任何调用方声明 scope。无论其名称为何,除此请求头和 principal_header 外不读取任何其他请求头。模式:^[!#$%&'*+.^_`|~0-9A-Za-z-]*$。默认值:"" |
不允许其他属性。
aggrega-config.mcp.health
监管程序询问此进程是否存活、是否已准备好响应调用的位置。这两项检查在单独的地址上应答,从不在 listen 指定的地址上应答:发往该端点的每个请求都携带 bearer 令牌,若在那里应答探测,就会让任何能访问该端点的一方无需认证即可读取进程状态,并且可以随意让它干活。无论是否携带令牌,该端点对 /healthz 和 /readyz 都返回与其对所有不提供服务的路径相同的 404。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
listen | string | 否 | 应答存活检查和就绪检查的地址,采用与 listen 相同的两种形式:host:port,或 unix: 后跟文件系统路径。默认为空,此时不启动第二个监听器,两项检查在任何地方都不应答。设置地址后,从进程开始运行起,GET /healthz 即应答 200;GET /readyz 在工作区完成解析且端点完成绑定之前应答 503,此后应答 200——这正是监管程序所需的区分,因为已启动的进程尚不一定能应答调用。每个应答都是一个状态码加空的响应体,不要求令牌,也不读取任何请求头;此地址上的任何其他路径应答 404,这两个路径上的任何其他方法应答 405。与 listen 不同,此地址不限于回环地址或 Unix socket,也不会因此拒绝任何地址:请将其指向这两者之一,这正是它的用途;并请注意,凡是能访问你所选地址的一方,都能读取这两项应答。默认值:"" |
不允许其他属性。
定义
ReleaseCatalogConfig
单个 Release 自己的目录(catalog)目录:与 workspace 块所带的两个键相同,作用范围限定于该 Release。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
catalog_dirs | string[] | 否 | 该 Release 从中读取本地实体的目录(catalog)目录,用以代替工作区的 catalog_dirs,每一项都相对于声明它的文件解析。与工作区列表相同,是一个有序、先匹配者胜出的搜索栈;当工作区根目录下的 catalog 目录存在且列出的条目都不包含它时,会在列表之后读取该目录。省略时,该 Release 沿用工作区的列表;写为 [] 时,它完全不读取任何本地目录。 |
catalog_dirs_append | string[] | 否 | 追加在该 Release 列表之后的目录(catalog)目录——该列表在条目写了自己的 catalog_dirs 时为其自身的列表,否则为工作区的列表——每一项都相对于声明它的文件解析。默认值:[] |
不允许其他属性。
RegistryConfig
作用范围限定于单个 OCI 镜像仓库主机的设置和签名信任策略。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
host | string | 是 | 这些设置所适用的镜像仓库主机(例如 hub.aggrega.ai)。它与推送/拉取目标的镜像仓库主机进行匹配,因此须按该匹配所用的写法书写:包含点号的小写主机名、localhost、后跟端口的单个名称(registry:5000)、IPv4 地址,或放在方括号中的 IPv6 地址,每种都可带一个可选的 :port——不得包含协议、路径、凭据、空白字符或大写字母。对于通过 HTTPS 访问的主机,443 端口是该主机的默认端口,写出该端口会在加载配置时被拒绝,并指出应不带端口书写的主机名,因为以这种写法书写的条目永远不会被匹配到;localhost 和其他回环地址通过普通 HTTP 访问,因此 443 在那里是普通端口,会被保留。aggrega registry add 和 aggrega config init --registry 以其参数所指的主机作为条目的键,并拒绝不符合此写法的主机。主机仅按其写法判断:不检查该名称能否解析,也不检查那里是否有镜像仓库响应。模式:^(?:(?:(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?|localhost|(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])(?:\.(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])){3}|\[(?:(?:[0-9a-f]{1,4}:){7}[0-9a-f]{1,4}|(?:[0-9a-f]{1,4}:){1,7}:|(?:[0-9a-f]{1,4}:){1,6}:[0-9a-f]{1,4}|(?:[0-9a-f]{1,4}:){1,5}(?::[0-9a-f]{1,4}){1,2}|(?:[0-9a-f]{1,4}:){1,4}(?::[0-9a-f]{1,4}){1,3}|(?:[0-9a-f]{1,4}:){1,3}(?::[0-9a-f]{1,4}){1,4}|(?:[0-9a-f]{1,4}:){1,2}(?::[0-9a-f]{1,4}){1,5}|[0-9a-f]{1,4}:(?::[0-9a-f]{1,4}){1,6}|:(?:(?::[0-9a-f]{1,4}){1,7}|:))\])(?::(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?|[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?:(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))$。 |
name | string | 否 | 该镜像仓库的可选友好别名。主机才是身份标识;name 是一个便捷选择器,凡是指名镜像仓库之处(例如 --registry 或 default_registry),它都会解析为该条目的主机。别名在所有条目中必须唯一。 |
trusted_identities | TrustedIdentity[] | 否 | 对从该镜像仓库拉取的制品所接受的无密钥签名身份的“或”集合。签名的证书与其中任意一个条目匹配时,签名即验证通过。由无密钥验证路径使用。默认值:[] |
trusted_deprecation_identities | TrustedIdentity[] | 否 | 额外被接受、可为从该镜像仓库拉取的制品签署追溯性弃用标记的无密钥身份的“或”集合。弃用标记的签名与原制品的签名者匹配,或与此处任一条目匹配时,该标记即被认可——这样,镜像仓库所有者或安全团队可以撤回原发布者已无法触及的制品,而无需被信任来签署制品本身。仅由弃用发现路径使用;它从不扩大制品签名的信任集合。默认值:[] |
public_key | string | 否 | 用于密钥模式镜像仓库的固定的、与 cosign 兼容的公钥,以 PEM 块的形式内联书写:从 -----BEGIN PUBLIC KEY----- 行(或 -----BEGIN RSA PUBLIC KEY-----)到与之匹配的 -----END 行之间的文本,与 aggrega registry add --key 从密钥文件中复制的内容相同。设置后,来自该镜像仓库的签名将离线地依据此密钥验证,而不是依据无密钥身份验证。不含 -----BEGIN … PUBLIC KEY----- 行的值会在加载配置文件时被拒绝,并指出文件和条目;误粘贴到此处的私钥同样会被拒绝。该行可以位于值中的任意位置,因为密钥是从值所带的 PEM 块中读取的,该块之前的任何文本都会被忽略。此处只检查该行:该块中是否含有可解码的密钥,要等到依据它验证来自该镜像仓库的签名时才会发现。该值被声明为敏感值(x-aggrega-sensitive),因此被拒绝的值——尤其是误选的私钥——绝不会被引用:拒绝信息会指出文件、条目以及该值未满足的约束(上述模式或字符串类型),并在原本显示值的位置显示 <redacted>。能够加载的公钥会按原样读取和显示。模式:-----BEGIN [A-Z ]*PUBLIC KEY-----。 |
trusted_root | string | 否 | 指向固定的 Sigstore 信任根包的可选路径,用于隔离网络环境中的无密钥验证。设置后,无密钥信任锚会在不使用网络的情况下从该文件加载;为空时,会获取并缓存公益信任根。 |
advisory | 布尔值 | 否 | 为 true 时,该镜像仓库的签名验证失败会降级为警告,而不会中止拉取。验证仍会执行,失败也会被报告;拉取继续进行。默认为 false。默认值:false |
skip_signature_verification | 布尔值 | 否 | 按主机设置的紧急跳过签名验证开关——与全局开关相同的 skip_signature_verification 开关,通过放置位置将作用范围限定于该主机。它不会使顶层的 signing.required 策略失效:无论此开关如何,组织要求的签名在该主机上仍会被验证;只有全局开关可以禁用它。允许在同一主机上将此开关与按镜像仓库设置的 signing.required 一起设置,这会将推送时要求签名与拉取时跳过验证结合起来:在验证一侧,跳过生效,因为按主机设置的要求立场(与顶层的不同)不能免于按主机设置的跳过。默认为 false。默认值:false |
signing | SigningConfig | 否 | 该镜像仓库的签名块:无密钥服务 URL、可选的密钥路径,以及按主机设置的信任立场。对推送到该主机的操作,端点字段会覆盖全局 signing 块;CLI 标志会覆盖两者。required 和 kinds 的含义由放置位置决定——在镜像仓库条目之下,它们将这一信任立场的作用范围限定于该主机(发布范围内的未签名制品会被拒绝,使用未签名的制品也会被拒绝),这与顶层 signing 块对所有镜像仓库所承载的概念相同。 |
不允许其他属性。
SigningConfig
签名块:keyless 服务 URL、指向密钥文件的可选指针,以及信任立场(required 和 kinds)。放在顶层时适用于所有注册表;放在某个 registries[] 条目下时适用于该主机——每个字段都从所在位置读取其作用域。required 是一个覆盖两个方向的信任立场(范围内未签名的推送会被拒绝,范围内未签名的拉取也会被拒绝)。安全性:它不保存任何机密材料——OIDC 身份令牌从来不是配置字段(短期有效,在运行时提供),key_path 是指向密钥文件的路径,从不是内联的密钥字节。这与验证端的不对称相对应:验证端允许内联 public_key,而签名端只携带密钥路径。通过 HTTP 访问的 aggrega mcp 服务器在任一位置都不会读取 key_path,因此无法通过这类监听器进行密钥签名:它响应的调用只能使用该调用自身携带的身份令牌签名。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
fulcio_url | string | 否 | 用于 keyless 签名的 Fulcio 证书颁发机构 URL。未设置时,使用公共 Fulcio 实例。它写作绝对 https URL:https://、主机,以及可选的端口和路径,不含空白——例如 https://fulcio.sigstore.dev。任何其他形式的值,例如没有协议(fulcio.example.com)或以 http:// 开头的值,都会在加载配置文件时被拒绝,并指明文件和键。该文件会在其上叠加任何其他内容之前接受检查,因此通过 AGGREGA_SIGNING_FULCIO_URL、--fulcio-url 标志,或在来自编辑器或助手的发布请求中提供的同一端点,不受此形式约束。模式:^https://[^\s/?#]+(?:[/?#]\S*)?$。 |
rekor_url | string | 否 | 用于 keyless 签名的 Rekor 透明日志 URL。未设置时,使用公共 Rekor 实例。它写作绝对 https URL:https://、主机,以及可选的端口和路径,不含空白——例如 https://rekor.sigstore.dev。任何其他形式的值,例如没有协议(rekor.example.com)或以 http:// 开头的值,都会在加载配置文件时被拒绝,并指明文件和键。该文件会在其上叠加任何其他内容之前接受检查,因此通过 AGGREGA_SIGNING_REKOR_URL、--rekor-url 标志,或在来自编辑器或助手的发布请求中提供的同一端点,不受此形式约束。模式:^https://[^\s/?#]+(?:[/?#]\S*)?$。 |
timestamp_url | string | 否 | 用于 keyless 签名的 RFC3161 时间戳颁发机构 URL。它没有默认值:未设置时,不联系任何时间戳颁发机构,keyless 签名的可信时间来自其透明日志条目。它写作绝对 https URL:https://、主机,以及可选的端口和路径,不含空白——例如 https://tsa.example.com/api/v1/timestamp。任何其他形式的值,例如没有协议(tsa.example.com)或以 http:// 开头的值,都会在加载配置文件时被拒绝,并指明文件和键。该文件会在其上叠加任何其他内容之前接受检查,因此通过 AGGREGA_SIGNING_TIMESTAMP_URL、--timestamp-url 标志,或在来自编辑器或助手的发布请求中提供的同一端点,不受此形式约束。模式:^https://[^\s/?#]+(?:[/?#]\S*)?$。 |
key_path | string | 否 | 用于离线密钥签名的 ECDSA P-256 私钥 PEM 文件路径。它是文件路径,从不是内联密钥材料。未设置时,使用 keyless 路径。通过 HTTP 访问的 aggrega mcp 服务器从不读取此密钥,无论它设置在何处——顶层 signing 块、注册表条目的签名块,或通过 AGGREGA_SIGNING_KEY_PATH:这类监听器响应的调用只能使用调用自身携带的身份令牌签名,否则会被拒绝。通过标准输入和输出访问的服务器会像终端一样使用该密钥签名。 |
required | 布尔值 | 否 | 此块作用域的唯一信任立场:为 true 时,发布范围内的制品类型需要签名(范围内未签名的推送会被拒绝),使用这类制品也需要签名(范围内未签名的拉取会被拒绝)。作用域从所在位置读取——在顶层 signing 块上覆盖所有注册表;在某个 registries[] 条目的 signing 块下覆盖该主机。一个名称,一项职责,两种作用域。顶层策略在配置级联中单调组合——任何将其设为 true 的层都会使其实际生效为 true,任何优先级更低的层都无法再将其关闭——因此无法通过普通的配置编辑移除。默认为 false。默认值:false |
kinds | string[] | 否 | 将 required 限定于特定制品类型。为空或只有一个 all 条目表示所有可签名类型;否则该立场恰好适用于所列类型,与实体的 kind: 值匹配(例如 Component、Feature、Recipe、FeatureRecipe、SchemaLibrary、MappingLibrary、Aggregate、Plugin)。在顶层 signing 块上,它在级联中以并集方式组合——某一层可以扩大作用域,但不能缩小。作用域从所在位置读取,与 required 相同。默认值:[] |
不允许其他属性。
TrustedIdentity
一个可接受的 keyless 签名身份:证书主体(OIDC 身份)与为其担保的 OIDC 颁发者配对。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
identity | string | 否 | 精确的证书主体备用名称——绑定到短期签名证书中的 OIDC 身份(例如维护者电子邮件或 CI 工作流 URI)。 |
identity_regexp | string | 否 | 与证书主体匹配的正则表达式,用于代替精确的 identity(例如接受某个组织下的任意工作流)。 |
issuer | string | 是 | 颁发身份令牌的 OIDC 颁发者 URL(例如 https://accounts.google.com 或 https://token.actions.githubusercontent.com)。 |
不允许其他属性。
PluginRef
对挂接在某个插槽上的 Wasm 插件的引用,该插槽的入口函数可由挂接项指定,即 governance 和 linter 列表。入口点固定的插槽改用 FixedEntryPluginRef,它携带相同的字段,但不含 function。uri 和 capability 共同选择插件:仅有 uri 时为直接挂接(该标识对应的插件按原样挂接,这是横切插槽的方式,因为其插件不声明所提供的能力);仅有 capability 时解析提供该能力的插件(即 Recipe 通过 spec.capability 绑定的裸能力名,例如 helm);两者同时给出时用于消除歧义:在有多个插件提供该能力的联邦目录中,capability 指定要解析的内容,uri 通过插件的裸标识选择由哪个发布者的插件提供该能力。function 覆盖插槽的默认入口函数;省略时采用该插槽文档所述的默认值,在 governance 条目上,该默认值由 role 决定。role 指定 governance 挂接角色,仅在 governance 条目上读取。with 携带插件读取的可选挂接时输入。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
uri | string | 否 | 插件标识符:Plugin 实体的裸标识(即 <pluginType>/<name> 路径,例如 governance/redact 或 provider/helm)、本地文件系统路径或注册表别名。可选:条目也可以改为通过 capability 选择插件。可选的尾部 :version 用于固定版本,其形式与任何版本固定相同,共三种(裸版本、精确版本 :1.0.0 或主版本兼容范围 :^1.0.0)。 |
role | string(枚举) | 否 | governance 挂接所绑定的流水线角色,仅在 governance 条目上读取:annotation-transform 在注解展开之前向已解析的 components 注入注解,使绑定的注入成为 Feature 挂接;label-transform 在构建拓扑时自动为拓扑图节点标签打标;ir-verdict 在静态分析阶段对 IR 图给出接受/拒绝裁决;render-verdict 在渲染阶段对渲染产物给出裁决。决定插件可以输出什么的是角色,而不是插件声明的种类:裁决角色的输出只能作为裁决读取,绝不会作为变更应用;转换角色的输出由宿主限定在其所属方面(注解或标签)。角色还决定默认入口函数(annotation-transform → transform_annotations;label-transform → mutate;ir-verdict → verdict_ir;render-verdict → verdict_render)。允许的值:"annotation-transform"、"label-transform"、"ir-verdict"、"render-verdict" |
capability | string | 否 | 该条目为其选择插件的 provider 能力,即 Recipe 通过 spec.capability 绑定的裸能力名(例如 helm、compose)。可选:条目也可以改为通过 uri 直接挂接插件。provider 绑定用它在联邦目录中选择由哪个发布者的插件提供某项能力;横切插槽将其留空,并通过 uri 挂接。 |
function | string | 否 | 可选,用于覆盖插槽的默认入口函数。省略时采用该插槽文档所述的默认值(governance annotation-transform → transform_annotations,governance label-transform → mutate,governance ir-verdict → verdict_ir,governance render-verdict → verdict_render,linter → lint_rules)。覆盖值可以指定插件声明的任意导出,但所指定的导出必须返回该插槽读取的输出结构:如果输出中含有该结构未声明的顶层字段,构建会中止,并指出所调用的导出和意外的字段。该检查只读取存在哪些顶层字段名,不检查缺少哪些字段或其下嵌套的内容,因此并不是对输出的完整校验。 |
with | PluginRefWith | 否 | 插件读取的可选挂接时输入。两个成员都是可选的,且与插槽无关,因此任何插槽都可以复用这一接口。 |
不允许其他属性。
FixedEntryPluginRef
对挂接在某个插槽上的 Wasm 插件的引用,该插槽的入口点是固定的,而非由挂接项指定,即 importer 列表和 providers 绑定。它携带与 PluginRef 相同的字段,但不含 function:importer 插槽调用其插槽契约指定的唯一入口函数,而 provider 驱动一组按阶段区分的固定导出,而不是单个可选入口,因此两个列表上都没有可供 function 指定的入口,该键在这里也不被接受。uri 和 capability 共同选择插件:仅有 uri 时为直接挂接(该标识对应的插件按原样挂接,这是 importer 插槽的方式,因为其插件不声明所提供的能力);仅有 capability 时解析提供该能力的插件(即 Recipe 通过 spec.capability 绑定的裸能力名,例如 helm);两者同时给出时用于消除歧义:在有多个插件提供该能力的联邦目录中,capability 指定要解析的内容,uri 通过插件的裸标识选择由哪个发布者的插件提供该能力。role 在这里被接受,但在此结构所服务的两个列表上都不会读取:它所指定的 governance 挂接角色在 governance 条目上读取,而该条目使用 PluginRef,因此在这些条目上设置的角色不起作用。with 携带插件读取的可选挂接时输入;provider 绑定则从 Recipe 获取其渲染配置,因此在 provider 绑定上设置 with: 会在加载时被拒绝。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
uri | string | 否 | 插件标识符:Plugin 实体的裸标识(即 <pluginType>/<name> 路径,例如 governance/redact 或 provider/helm)、本地文件系统路径或注册表别名。可选:条目也可以改为通过 capability 选择插件。可选的尾部 :version 用于固定版本,其形式与任何版本固定相同,共三种(裸版本、精确版本 :1.0.0 或主版本兼容范围 :^1.0.0)。 |
role | string(枚举) | 否 | governance 挂接角色。使用此结构的两个列表都不会读取它:角色在 governance 条目上读取,而这些条目使用 PluginRef,因此在这里设置的角色会被接受,但不起作用。允许的值是四种 governance 角色,各自的含义见 PluginRef。允许的值:"annotation-transform"、"label-transform"、"ir-verdict"、"render-verdict" |
capability | string | 否 | 该条目为其选择插件的 provider 能力,即 Recipe 通过 spec.capability 绑定的裸能力名(例如 helm、compose)。可选:条目也可以改为通过 uri 直接挂接插件。provider 绑定用它在联邦目录中选择由哪个发布者的插件提供某项能力;横切插槽将其留空,并通过 uri 挂接。 |
with | PluginRefWith | 否 | 插件读取的可选挂接时输入。两个成员都是可选的,且与插槽无关,因此任何插槽都可以复用这一接口。 |
不允许其他属性。
CLIPluginRef
一个已固定版本的 CLI 扩展插件,作为顶层 aggrega 命令安装:包含该命令解析并运行的、已解析且固定版本的制品引用,以及该引用在安装时解析到的 guest 字节的内容摘要。二者共同精确固定命令执行的字节;该摘要还作为 describe 缓存的键,该缓存无需加载 guest 即可提供命令的名称和帮助信息。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
uri | string | 是 | 该命令解析并运行的、已解析且固定版本的制品引用,例如 oci://hub.aggrega.ai/plugin/cli/<name>:1.2.0,在安装时固定。 |
digest | string | 是 | 该引用在安装时解析到的 guest .wasm 字节的内容摘要,写作 sha256: 后跟这些字节的 SHA-256 的 64 位小写十六进制数字——这是 aggrega plugin add cli 记录的写法,也是与解析所得字节进行比较时使用的写法。任何其他写法的摘要——不带 sha256: 前缀的纯十六进制、大写字母或长度不同——都不可能与之相等,因此会在配置文件加载时被拒绝,并指出该文件和该条目。它固定命令运行的确切字节——之后某次解析的字节哈希值不同时,命令会中止——并且是 describe 缓存的键,该缓存无需加载 guest 即可渲染命令的帮助信息。模式:^sha256:[0-9a-f]{64}$。 |
不允许其他属性。
PluginRefWith
插件读取的可选挂载时输入。两个成员均为可选,且该接口是通用的,因此任何 socket 都可以复用它。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
sources | string[] | 否 | 宿主在编译时读取并交给插件的定义文件路径。每个条目都是一个文件系统路径,相对于声明它的配置文件所在目录进行解析。 |
settings | object | 否 | 原样交给插件的自由格式设置对象。宿主不解释其结构;插件定义其读取的键。 |
不允许其他属性。