跳转至

集成模板与组件替换系统规范

意图

让已安装的集成为 Core 模板或 Core 组件提供项目特定的实现,同时不使通用查找产生歧义,也不移除对 Core 原始模板或组件的访问。

非目标

  • 替换参考文档主题。该领域拥有自己的契约。
  • 重写消费者已经复制到应用中的模板或组件源码。
  • 当集成模板或组件的源码或元数据无效时,使其可用。
  • 选择项目既未配置也未自动链接的集成。

要求

  • FR1 — 模板声明自身的替换。 集成模板可以(MAY)在其自身元数据中将 replaces 设置为一个已有的 Core 模板 id。不存在包级映射来声明替换(spec:AST-039/FR11)。该字段属于严格模板元数据对象的一部分,因此 0.6.4 之前的稳定 CLI 会拒绝它;使用该字段的集成 MUST 声明一个 @astryxdesign/cli 的 peer 范围,其最低允许版本至少为 0.6.4,这是应用该字段的第一个稳定版本(DEC-7)。
  • FR2 — 有效替换负责默认发现。 当有一条有效声明适用时,非限定模板查找和默认模板投影 MUST 针对 Core id 使用集成模板。集成模板 MUST 仍可通过其自身 id 寻址。列表、搜索、构建建议、项目发现和块布局查找 MUST 投影出同一个胜出者。
  • FR3 — 显式包选择保留替代项。 选择 @astryxdesign/core MUST 访问原始 Core 模板。选择集成包 MUST 保留通过其自身 id 访问其被遮蔽或被拒绝模板的能力。
  • FR4 — 无效声明失败关闭。 缺少 Core 目标、模板类型不匹配、针对无法使用模板的声明,或一个包内对同一目标的多个声明 MUST 视为错误。无效集合 MUST NOT 替换 Core。当仅替换元数据无效时,有效的集成模板仍可通过其自身 id 使用。
  • FR5 — 优先级是确定性的。 当多个显式配置的集成有效地替换同一目标时,较晚配置的集成胜出,CLI 报告警告。显式配置的替换 MUST 胜出自动链接的替换。当只有自动链接的集成有效地替换同一目标时,package.json 中较晚列出的依赖胜出并产生警告;在 astryx.config 中指定预期包可使优先级显式化。无效的自动链接声明仍可报告,但 MUST NOT 禁用有效的显式替换。
  • FR6 — 省略保留有效集成的选择行为。 没有 replaces 时,有效模板选择和包感知歧义保持不变。FR9 有意改变失败隔离,无论该字段是否存在。
  • FR7 — 在支持开始之前,诊断保留已发布的契约。 现有的同 id 冲突在整个 0.6.x 中 MUST 保持已发布的仅警告响应形态。替换专用诊断可以为实现预发布验证而实现,但它们的 relationship、可选 replaces 和 severity: 'info' 字段在 0.7.0 之前不会进入稳定的冲突 API。达到 0.7.0 MUST NOT 仅凭版本号扩展 schema:一次有意的投影变更 MUST 同时更新响应类型、生成的引用、终端输出、消费者文档和测试。从该受支持边界开始,astryx doctor integration templates MUST 报告有意替换、缺失目标、针对无法使用模板的声明、类型不匹配和同包歧义。错误发现 MUST 产生退出码 1,并且 MUST NOT 随后输出虚假成功消息。
  • FR8 — 公共 schema 投影在其受支持边界上完整。 有效的 template.list 条目可以包含可选的 replaces;添加该可选字段是非破坏性的。在 0.7.0 或之后,一次显式的投影更新 MUST 同时更改响应类型、生成的清单、终端投影、消费者文档和测试;仅进行包版本号提升 MUST 保持仅警告响应不变。
  • FR9 — 失败隔离保留有效贡献。 一种贡献类型中的错误 MUST 仍可报告,同时不移除该集成其他有效的贡献类型。在模板和组件发现中,一个不可用的文件 MUST NOT 移除有效的同级文件。其他类型保持其现有的按类型原子性。清单加载失败仍会撤回该集成,因为没有贡献根是可信任的。无论是否有模板声明 replaces,此规则均适用。
  • FR10 — 组件声明自身的替换,CLI 下限开启它。 集成组件可以(MAY)在其自身 ComponentDoc 中将 replaces 设置为 Core 组件目录中某个组件的确切 name。仅当该组件的包声明了 @astryxdesign/cli peer 范围,且其最低允许版本至少是应用组件替换的第一个稳定 CLI 版本(COMPONENT_REPLACES_CLI)时,替换才适用。该范围是包的 opt-in 机制。低于该版本的稳定 CLI 接受该字段,并让组件保留在其自身名称下。
  • FR11 — 已应用的组件替换负责非限定组件查找。 替换组件在组件详情和批量选择器中响应 Core 组件的名称,在每一个组件列表详情层级占据 Core 组件的槽位,是该名称的组件搜索结果,是非限定 swizzle <Name> 所复制的组件,也是 gap-report 路由针对该名称发送报告的位置。它仍可通过自身名称寻址。这些结果中的每一个都指明替换组件自身的包(architecture:cli-surface INV28)。
  • FR12 — 显式 Core 选择保留原始组件。 在组件详情、批量选择器和 swizzle 中选择 @astryxdesign/core MUST 访问原始 Core 组件。swizzle --list 列出 Core 的组件,包括被替换的组件。
  • FR13 — 对选择加入的包,无效组件声明失败关闭。 对于具有 FR10 范围的包,replaces 未命名 Core 目录中的任何组件、值不是非空字符串、组件自身名称是另一个不同的 Core 组件,以及一个包内对同一目标的多个声明,每一项 MUST 在 astryx doctor integration components 中成为错误,随后以退出码 1 退出。无效集合 MUST NOT 替换 Core。有效组件仍可通过自身名称使用(FR9)。
  • FR14 — 组件优先级是确定性的。 当多个具有 FR10 范围的包有效地替换同一 Core 组件时,按 FR5 顺序决定胜出者:显式配置的包胜出自动链接的包;在配置的包中,较晚配置的包胜出;在自动链接的包中,较晚列出的依赖胜出。只要有多个包竞争,Doctor 就会警告。无效的自动链接声明 MUST NOT 禁用有效的显式替换。来自另一个包、其自身名称是被替换的 Core 名称的集成组件,在非限定查找中被遮蔽,仍可通过其包寻址,Doctor 会发出警告。
  • FR15 — 未达到下限的包保持其已发布行为。 其组件 replaces 声明永不适用,加载该包的应用程序不会从它们看到任何新输出。关于它们的每一项发现(包括指明 FR10 范围的那一项)都是由 astryx doctor integration components 报告给包作者的警告,因此没有任何命令的结果或退出码会因它们而改变。当组件设置 replaces 且包的 peer 范围允许更早的稳定 CLI 时,integration pack --check 会警告,且永不失败。

平台支持

  • 对于其模板声明了 replaces 的集成,最低受支持的 CLI 为 @astryxdesign/cli >=0.6.4。更早的稳定版 CLI 会严格解析模板元数据:它们会拒绝该字段,打印一条警告,丢弃该模板,并拒绝提供该包的文档主题,而其其他模板和组件仍会加载。
  • 稳定版 0.6.x 冲突响应保留其仅警告形态。替换专属冲突模式在 0.7.0 时才具备进行显式、完整投影更新的资格;仅版本号不会激活它。
  • 组件替换:@astryxdesign/cli >=0.6.7 既是最低受支持的 CLI,也是选择启用机制(FR10)。更早的稳定版 CLI 会接受组件的 replaces 并将该组件保留在其自身名称下,同时仍选择 Core 组件。
  • 浏览器证据:不适用于目录选择。生成的消费方应用在其选定模板渲染集成自有导航时,MUST 仍能构建或运行。

当前状态影响

模板元数据类型和解析器接受一个可选字段 replaces。共享模板解析负责替换验证、优先级、别名和默认发现视图。模板命令、搜索/构建、Project、布局、Doctor、响应文档以及集成编写指南均体现这一结果。Project 会报告无效贡献,同时保留其他有效的贡献类型和有效的模板或组件同级项。

该字段是可选的,当它缺失时,有效模板保持其选择行为。从 0.6.4 开始的稳定版会应用声明的替换,而使用替换的集成包要求 @astryxdesign/cli >=0.6.4,该范围排除了所有拒绝该字段的稳定版。模板获胜者是可变的目录数据,因此替换选择不会产生已发布的失败方。可选的 TemplateListEntry.replaces 字段是增量式新增的。

已发布的 IntegrationTemplateConflict 响应则不同:现有的同 ID 冲突已经稳定。最终 0.6.x 保留其仅警告形态。必需的 relationship 字段和 severity: 'info' 值仍处于分阶段状态,等待在 0.7.0 或之后进行刻意的完整投影更新。仅提升包版本不会改变仅警告投影。在 spec:AST-017/FR1、FR2、FR5、FR7 和 FR9–FR13 下,该能力及其兼容性门槛是一个 [feat] 补丁,而非破坏性的 minor 版本。

组件发现会从每个有效组件文档中读取 replaces,并由一个解析器决定组件替换、优先级和发现结果。组件详情、批量选择器、每个列表详情级别、搜索、swizzle 复制、gap-report 路由、Project 问题以及 astryx doctor integration components 都会读取其结果。早于 COMPONENT_REPLACES_CLI 的稳定版 CLI 会接受组件 replaces 并忽略它。一个包若其版本范围允许上述某个版本,则该包的组件名称保持不变,Core 组件仍被选中,加载该包的应用看不到新输出,其作者会在包检查中看到警告。一个包若其版本范围本来就从更晚的版本开始,例如之前由 integration add theme 和 integration add doc --parent 写入的 >=0.7.0,则会原样选择启用;其范围排除了所有忽略该字段的 CLI,因此没有受支持的组合会发生变化。在 spec:AST-017/FR1、FR5 和 FR12 下,组件替换是一个 [feat] 补丁。

验证

Contract 验证 代表性状态 变更或失败预期
FR1, FR6 模板解析器和发现测试、下限表测试、已发布 CLI 的消费方运行 字段存在、字段缺失、已发布的 0.6.3 与 0.6.4 CLI、peer 版本范围在等于或低于下限时 替换从模板自身元数据以外的任何位置被采纳,或验证接受低于下限的范围
FR2, FR3 模板 API/CLI 与真实消费方应用测试 目标 ID、自身 ID、Core 包、集成包 查找变得有歧义,或 Core 原始项不可达
FR4, FR7 Doctor 和发现测试,外加 0.6.x 响应形态 fixture 缺失本地/源、缺失目标、类型错误、重复、同 ID 拒绝、发布前替换 无效元数据触发替换、Doctor 报告成功,或 0.6.x 冲突获得暂定字段
FR5 多集成与自动链接测试 配置顺序、显式与自动链接、无效落败方 文件/显示顺序选择获胜者,或无效自动链接使显式意图失效
FR2, FR8 列表、搜索/构建、Project、布局、响应和生成文档检查 别名与未声明的精确 ID 冲突、页面与块、显式 0.7 模式投影 两个投影不一致、公共字段没有文档,或仅版本号就扩展冲突模式
FR9 Project 发现与问题顺序测试 无效组件/模板同级项、有效贡献类型和同级项 一个错误贡献移除了无关的有效输出
FR10, FR15 底价表测试、解析器测试,以及一次已发布的 CLI 消费者运行 底价处的范围、无范围、较低范围;带有该字段的最新稳定版 CLI 没有范围的包会获得替换、报错,或退出码发生变化
FR11, FR12 组件、批次、列表、搜索、swizzle 与缺口报告测试,再加上一次打包后的消费者运行 目标名称、自身名称、Core 包选择器、每个列表详情级别 某个表面选择了与组件详情不同的所有者,某个结果遗漏了所有者包,或 Core 不可达
FR13 解析器测试和 doctor integration components 测试 缺少目标、无效值、自身名称是另一个 Core 组件、一个包中包含两个声明 无效元数据替换了 Core,或 Doctor 在发现错误时仍以退出码 0 退出
FR14 多集成解析器测试 已配置顺序、显式与自动链接、仅自动链接、无效的自动链接失败者、被遮蔽的同名组件 文件或显示顺序决定胜者,或无效的自动链接声明使显式意图失效

决策日志

DEC-1 — 替换声明位于集成清单上

参考: spec:AST-035/DEC-1 提出者: josephfarina,2026-09-11 被以下决策取代: spec:AST-035/DEC-3 和 spec:AST-039/DEC-4,2026-09-24

在集成清单上使用 templateReplacements: Record<integrationTemplateId, coreTemplateId>。这使意图显式化。从 0.5.3 开始的 CLI 会在不认识该字段时忽略它,而不会拒绝已理解的内容;使用该字段的集成不得声称与 0.5.2 或更早版本兼容。受支持的集成使用从 0.7.0 开始;实现可以提前发布以进行前瞻性验证。

已拒绝:直接在 TemplateDoc 上添加 replaces。在该字段之前发布的 CLI 会拒绝严格的元数据对象,从而使集成模板不可用,而不是干净地降级。

DEC-2 — 显式项目配置拥有替换优先级

参考: spec:AST-035/DEC-2 提出者: josephfarina,2026-09-11

当多个显式配置的包替换同一目标时,使用配置顺序,并且任何显式替换都优先于自动链接。这使消费者编写的配置保持权威性,同时使有效冲突具有确定性和可见性。

已拒绝:使所有跨包替换都具有歧义。这会阻止消费者按声明顺序有意组合集成。同样被拒绝:仅因为自动链接在发现过程中较晚追加,就让它覆盖显式配置。

DEC-3 — 模板声明自身的替换

参考: spec:AST-035/DEC-3 提出者: josephfarina,2026-09-24

将 replaces 放在集成模板自身的元数据中。每个集成项都将其逐项元数据保留在自己的描述符中(spec:AST-039/FR11),而文档主题已经用相同字段声明替换。代价是:0.6.4 之前的稳定 CLI 会拒绝未知字段、丢弃该模板,并扣留该包的文档主题,而清单映射可以让它回退到自身 ID 访问。集成主题、章节 ID 和命名空间文档已经需要 0.6.4 CLI,因此这不会增加新的破坏类型;使用 replaces 的集成在 DEC-7 中声明 CLI 下限。

已拒绝:在清单中使用 templateReplacements(DEC-1)。它是逐项数据的中央目录,而 spec:AST-039/FR11 对所有类型都禁止这种做法。

DEC-4 — 发布前的替换支持是补丁兼容的

参考: spec:AST-035/DEC-4 决策者: josephfarina,2026-09-29 部分被以下决策取代: spec:AST-035/DEC-7,2026-10-09

在受支持的 0.7.0 集成包边界之前,集成模板替换并不是完全发布的 API。因此在最终 0.6.x 中发布其实现是增量式的且补丁兼容的:不存在任何有效的、最新稳定版集成消费者的受支持行为会发生变化。模板胜者是可变目录数据,可选列表字段是增量式的。

这并不会放宽围绕未发布能力的稳定 CLI 模式。现有的相同 ID IntegrationTemplateConflict 响应在 0.6.x 中保持仅警告的形状。在 0.7.0 或之后,替换特有的 relationship、replaces 和 severity: 'info' 需要在运行时、类型、生成的参考、终端输出、文档和测试中进行一次有意的投影变更;仅版本号不会激活它们。使用 replaces 的集成包仍要求 @astryxdesign/cli >=0.7.0,以保护较旧的严格元数据读取器。

已拒绝:仅仅因为其未来模式不同就将未发布的替换行为视为破坏性变更;在 0.6.x 中暴露扩展后的冲突模式;或者在受支持的包边界和稳定模式适配器已经保护已发布消费者的情况下,对所有替换实现加以门控。

DEC-5 — 组件声明自身的替换,CLI 下限即选择加入

DEC-5 — 包的组件替换从其 CLI 范围的第一个发布版本开始应用

参考: spec:AST-035/DEC-5 决策者: josephfarina、2026-10-07

组件的 replaces 存在于其自身的 ComponentDoc 中,正如模板的 replaces 一样(DEC-3)。低于下限的稳定发布版本接受该字段并记录替换,但不应用它;因此,一次性应用所有声明会改变那些版本范围允许这些版本的包的替换选取。CLI 仅当包的 @astryxdesign/cli peer 范围起始于应用这些替换的第一个发布版本时,才应用该包的组件替换。范围允许更早 CLI 的包保持其原有行为;已经起始于更晚版本的范围(如 >=0.7.0)会排除所有忽略该字段的 CLI,因此任何受支持的组合都不会改变。新包获得一个文档化的开关,而它们本来就为其他功能管理该开关。

已否决:立即应用所有声明的 replaces —— 这会在包未要求的情况下改变已发布的替换选取。 已否决:添加应用配置键 —— 包已经表明了自身意图,且 spec:AST-017/FR19 仅在存在证据时才允许引入配置。

DEC-6 — 组件替换采用模板替换的优先级和失败规则

参考: spec:AST-035/DEC-6 决策者: josephfarina、2026-10-07

单一解析器将 FR4、FR5 和 FR9 应用于组件,并加入 FR13 的组件特定检查,所有组件表面都读取其结果。集成作者只需学习一套适用于两类对象的规则,且任意两个组件表面都不会对胜出者产生分歧。

已否决:按表面分别解析 —— 组件、搜索和 swizzle 会逐渐产生分歧。

DEC-7 — 模板替换下限是应用它的第一个发布版本

参考: spec:AST-035/DEC-7 决策者: josephfarina、2026-10-09

模板设置了 replaces 的集成声明其 @astryxdesign/cli peer 范围起始于 0.6.4,以取代 DEC-4 的 >=0.7.0。已发布的 0.6.4 至 0.6.7 会将 FR2 和 FR3 应用于声明的替换;已发布的 0.6.3 及更早版本则拒绝该字段。若下限没有任何已发布版本满足,npm 会在安装了该包的应用中保持 CLI 未安装状态。从 0.6.4 起,replaces 声明、替换选取以及可选的列表投影是 spec:AST-017/FR24 下的已发布表面;扩展的冲突字段保持预发布状态,直到 0.7.0 或之后由 FR7 和 FR8 带来的投影变更落地。

已否决:在 0.7.0 发布之前一直保持 >=0.7.0,因为 npm 会从安装了此类包的 0.6.x 应用中移除 CLI。

开放问题

无。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx