运行时集成功能组合系统规范¶
意图¶
定义可复用的运行时集成功能组合规则 —— 集成在其默认清单之外还能贡献的 CLI 能力。每个功能都是集成模块中的一个命名导出,并且是可选的、与 astryx.config 中匹配的字段。多个处理器以叠加方式组合:每个已配置且符合条件的处理器都独立运行,失败按处理器分别上报,而该功能定义一个聚合的命令结果,不会让任一处理器掩盖其他处理器。
本规范首先描述通用组合契约,然后记录 gapReport 的特定需求;gapReport 是第一个基于该契约构建的功能。
非目标¶
- 替换默认导出的清单或其贡献模型(组件、模板、codemods、文档)。这些由
Project接缝加载,不在本规范范围内。 - 为任何处理器定义传输协议、网络目标或持久化格式。
- 提供带有生命周期钩子、依赖排序或处理器间通信的插件系统。
需求¶
通用组合规则¶
以下规则适用于遵循本规范的每个运行时集成功能。一个功能由来自 astryx.integration.{ts,mjs,js} 的命名导出标识,并可选择地在 astryx.config 中拥有匹配的字段。
命名导出 + 匹配的项目配置字段¶
功能被声明为集成模块中的 命名导出。同一功能也可以作为字段出现在使用者的 astryx.config 中,用于项目级处理器。较旧的 CLI 版本若不识别该命名导出,会忽略它并继续加载默认清单。
叠加组合¶
有效集合中的每个处理器都会收到一个有序的投递结果。项目处理器排在首位,随后是按各集成在 astryx.config 中出现的顺序排列的每个集成处理器。符合条件的处理器会运行;未获得同意时,公开处理器会记录 consent_required,而不会被调用。没有任何处理器会覆盖或取代另一个处理器。
按 handle 函数进行身份去重¶
当同一个 handle 函数引用在有效集合中出现多次时(例如项目配置重新导出了某个集成的处理器),它只运行一次,位置在其首次出现处。
每处理器独立的 structuredClone 副本¶
每个处理器都会收到事件的一份独立 structuredClone 副本。修改自身输入的处理器不会影响任何其他处理器。
失败隔离 + 聚合响应¶
抛出异常、超时或行为异常的处理器会为该处理器产生一条失败的投递记录。后续处理器仍然会运行。命令的聚合响应会收集每个处理器的投递记录,从而使调用方能够准确看到哪些处理器成功、哪些失败以及失败原因。
生命周期 / 异步¶
- 超时: 每个处理器有 30 秒的墙钟超时,并会收到一个在该时间预算耗尽时触发的
AbortSignal。 - 异步: 处理器可以是异步的;CLI 会等待每一个处理器。
- 执行顺序: 处理器按有效集合顺序依次运行。某个处理器的失败不会跳过后续处理器。
每处理器同意元数据¶
每个处理器声明 audience 为 'internal' 或 'public'。CLI 按处理器强制执行同意:除非调用方已明确确认公开写入,否则不会调用 public 受众的处理器。internal 处理器不需要额外确认。
可检查的同意(consent_required 投递)¶
当调用方尚未确认同意且某个处理器需要同意时,CLI 会在不调用该处理器的情况下为其记录一条 consent_required 投递。调用方可以在带确认重新运行前检查哪些处理器需要同意。
回退行为¶
内置回退(例如通过 issuesUrl 打开 GitHub issue)仅在去重后的有效处理器集合为空时激活。任何已配置处理器(项目或集成)的存在都会完全抑制该回退。
issuesUrl 是目标元数据¶
集成清单或项目配置上的 issuesUrl 描述人类可读 issue 链接的目标位置。它是关于目标包的元数据,而非处理器实现。处理器将其作为上下文使用;CLI 将其用于回退路由。
变异敏感测试¶
针对基于此组合模型构建的功能的测试 MUST 覆盖扇出顺序、隔离、去重、超时、同意门控、consent-required 检查、回退抑制以及聚合响应形态。移除 fail-closed 防护 MUST 使某个测试失败。
gapReport 特定需求¶
gapReport 是第一个基于上述通用组合规则构建的功能。
-
FR1 — 处理器类型。 gap-report 处理器是符合
GapReportHandler的普通对象:{ audience: 'internal' | 'public', handle: (event: GapReport, context: { signal: AbortSignal }) => GapReportHandlerReceipt | Promise<GapReportHandlerReceipt> }。GapReportHandler取代GapReportWriter。 -
FR2 — 事件形状。
GapReport事件携带schemaVersion: 1、普通的 camelCase 字段名、规范化值,以及一个包含{ package, version, issuesUrl }的target对象。不使用 snake_case、不使用缩写、不使用嵌套的调试上下文。 -
FR3 — 回执契约。 处理器 MUST 返回一个
GapReportHandlerReceipt:{ status: 'filed' | 'routed_only' | 'skipped', url?: string, message?: string }。其他 status 值均不被接受。url和message是可选的,并携带人类可读的上下文。 -
FR4 — 处理器隔离。 每个处理器都在隔离环境中运行:
- 每个处理器在自己的 worker 中运行。
stdout被重定向到stderr,process.exit、process.exitCode以及迟到的 promise 延续都被限制在该 worker 内。 - 抛出异常或超时(30 秒)会为该处理器产生一条失败的投递记录。CLI 会先中止该处理器的 signal,然后在启动下一个处理器之前终止其 worker。
- 失败的处理器不影响命令自身的退出码或其他处理器。
- 每个处理器在自己的 worker 中运行。
-
FR5 — 无继承处理器的选择退出机制。不存在与
inheritDebug类似的 gap-report 处理器选择退出机制。有效集合中的每个内部处理器都会运行,每个公共处理器都会收到仅受显式同意门控的结果。package.json中的inheritDebug字段是针对debug功能的兼容性例外(参见决策日志 DEC-2);它不为其他功能开创先例。 -
FR6 — 有效集合。有效处理器集合为:项目配置的
gapReport处理器优先(如果存在),然后按astryx.config集成顺序排列的各集成的gapReport命名导出。按handle函数身份进行去重。 -
FR7 — 目标选择。gap report 的目标包按以下方式选择:显式
--package标志 → 当只有一个包拥有该组件时的唯一组件所有者 → 默认使用 Core。目标选择不基于处理器数量或处理器来源。 -
FR8 — 内置 GitHub 回退。当有效处理器集合为空(去重后为零个处理器),且目标具有 GitHub
issuesUrl时,CLI 会提供通过gh issue create提交的选项。此回退受同意门控(public受众)。任何其他issuesUrl方案都会生成routed_only回执。当至少存在一个处理器时,该回退被完全抑制。astryx swizzle的回执会在gh位于 PATH 时提供其gh issue create命令行,无论其登录状态如何。已退出登录的gh在该命令行运行时要求其自身登录。文本回执显示命令;JSON 回执保留命令和 issues URL。 -
FR9 — 项目配置字段。
astryx.config新增一个gapReport字段,接受GapReportHandler。这是项目级处理器,在有效集合中首先运行。 -
FR10 — 集成命名导出。集成从其集成模块中声明其处理器为
export const gapReport: GapReportHandler。该命名导出故意不是默认清单字段,与debug功能的导出约定一致。 -
FR11 — 逐处理器同意。每个处理器的
audience被独立评估。混合受众的扇出会无条件调用internal处理器,并根据调用者同意门控public处理器。未门控的处理器即使在门控的兄弟处理器被阻止时仍会运行。 -
FR12 — 聚合响应。命令的响应包含一个
deliveries数组,每个有效处理器或回退对应一个条目。每个投递记录handlerType、handler、audience、status、url和message。响应形状在--json和人类可读输出模式中相同。 -
FR13 — 调用者指定的目标。当调用者使用
--to指定目标时,该目标替换该报告的处理器和 FR8 回退。architecture:cli-surfaceINV36 规定了该选项以及谁选择目标。
平台支持¶
- 受支持:Node >= 22.13,CLI 支持的任何操作系统。
- 不受支持:依赖网络访问、原生二进制文件或平台特定 API 的处理器由处理器作者负责;CLI 提供隔离,但不提供能力检测。
当前状态影响¶
debug 已经将一个项目函数与每个集成命名导出组合在一起,采用项目优先/配置顺序投递,具有身份去重和逐处理器副本。其同步进程退出生命周期和现有的 inheritDebug 兼容性开关保持不变。
PR #6200 最初选择了一个可执行的 gap 写入器。本规范在发布前替换该模型:gapReport 变为一个项目处理器加上每个已加载的集成处理器,每个处理器返回自己的回执。没有处理器的现有消费者保留受同意门控的 issuesUrl 回退。由于单写入器形态尚未发布,因此不需要迁移任何已发布的配置或集成 API。
验证¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1–FR3 | gap-report 处理器类型和回执契约测试 | 有效处理器;缺少 audience;错误的 status 值;非对象返回 | 无效的处理器形状或回执被静默接受 |
| FR4 | 处理器隔离测试 | 处理器写入 stdout;处理器调用 process.exit;处理器抛出异常;处理器超过 30 秒 | stdout 污染到达 JSON 信封,或退出/抛出会阻止后续处理器 |
| FR5 | 无选择退出断言测试 | 项目在 package.json 中设置 inheritDebug: false;gap-report 处理器仍然运行 |
选择退出机制抑制了 gap-report 处理器 |
| FR6 | 有效集合排序和去重测试 | 项目 + 两个集成;重复的 handle 引用;仅项目;仅集成 | 顺序错误、重复执行或缺少处理器 |
| FR7 | 目标选择测试 | 显式包;唯一所有者;需要 --package 的歧义所有者;无组件匹配 |
处理器数量影响目标、猜测歧义,或未知组件无法默认使用 Core |
| FR8 | 回退激活与抑制测试 | 零处理器 + GitHub issuesUrl;零处理器 + 非 GitHub issuesUrl;存在一个处理器 | 存在处理器时回退仍触发,或非 GitHub issuesUrl 声称已提交 |
| FR9–FR10 | 配置字段与命名导出加载测试 | 项目配置含 gapReport;集成使用命名导出;两者同时存在;两者均不存在 | 配置字段被忽略、命名导出被忽略,或旧版 CLI 在命名导出时出错 |
| FR11 | 混合受众同意测试 | 全部内部;全部公开且已获同意;全部公开但未获同意;混合且部分同意 | 公开处理器在未获同意时运行,或内部处理器被同意机制阻止 |
| FR12 | 聚合响应结构测试 | 全部成功;一个失败;一个超时;存在 consent_required 条目;空集(回退) | 缺少投递条目、来源归属错误,或 --json 与人类可读输出之间的响应结构不一致 |
| FR13 | 命名目的地测试 | --to 指定一个带 GitHub issuesUrl 的集成(无论是否获得同意);一个非 GitHub issuesUrl;一个未知包 |
处理器在带 --to 时运行,或未知目的地发送任何内容 |
| 通用 | 变更敏感的组合测试(structuredClone) | 处理器修改事件字段;处理器向事件添加属性 | 变更泄漏到后续处理器 |
决策日志¶
DEC-1 — 处理器叠加式组合;不采用单一写入者选择¶
参考: spec:AST-031/DEC-1
决策者: josephfarina, 2026-09-10
每个已配置的处理器都会运行。此前的模型基于目标归属选择单一写入者,这意味着集成无法观察到关于其并不拥有的组件的报告。叠加式组合让每个相关方都能收到每份报告,同时将失败隔离到单个投递环节中。
已否决:按目标归属进行单一写入者选择;基于优先级的覆盖,即项目处理器屏蔽集成处理器;“首个匹配获胜”的路由方式。
DEC-2 — 运行时功能没有通用退出机制¶
参考: spec:AST-031/DEC-2
决策者: josephfarina, 2026-09-10
debug 功能现有的 inheritDebug 开关仍是该功能自身负责的兼容性例外。它并不确立通用的 inherit<Feature> 约定。缺口报告是一项显式命令,其目的是通知每个已配置的处理器,因此加载集成即表示选择启用其对应的处理器。任何未来的退出机制都需要单独的所有者决策。
已否决:自动将 inheritDebug 克隆为通用的 package.json 模式;增加一个缺口报告退出机制,静默阻止已加载的集成接收显式报告。
DEC-3 — 目标选择使用组件归属,而非处理器数量¶
参考: spec:AST-031/DEC-3
决策者: josephfarina, 2026-09-10
缺口报告的目标包是拥有该组件的包。当多个包声称拥有同一组件名称时,CLI 要求显式指定 --package,而不是自行猜测。没有精确所有者的名称默认归入 Core。处理器数量和处理器顺序绝不会改变目标归属。
已否决:按处理器数量或集成顺序选择目标;静默选择一个存在歧义的所有者;将目标归属分发给每个附带处理器的包。
开放问题¶
无。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx