跳转至

组件审计契约回填与自动合并系统规范

意图

仅定义为安全运行整组件审计所需的额外行为:哪些组件参与、当组件契约缺失或不完整时审计如何进行、哪些修复可以随审计一起流转,以及 Night Watch 审计何时可以自动合并。

本规范建立在现有组件规范体系之上。组件契约形态、权威来源、所有权、审批、冲突处理以及语义 API 规则仍由以下内容所有:

非目标

  • 定义第二种组件规范格式、编写指南、模式或审批路径。
  • 将组件、家族、设计、架构、消费者文档或审计事实复制到新记录中。
  • 在观察性回填期间添加、改进、移除或重新解释组件行为。
  • 替换评级、晋升或复核模式下的 issue 和台账规则。
  • 决定通用组件测试质量评估标准。

要求

  • FR1 — 单一审计名册。 审计队列和 Component Audits 沙箱表必须使用一份已检入的公共组件名册。目标名册包括 Core、Lab、Charts、Rich Text 和 Vega。一个包只有在现有规范知识系统识别并验证其组件记录位置之后,才能进入活跃审计名册;审计不得发明仅用于审计的 spec 路径。
  • FR2 — 现有组件契约保持规范地位。 审计必须从最近的当前组件或模块契约开始,并沿其链接到达当前家族、设计、架构和系统权威来源。审计必须使用现有组件模板和模式,而不是创建并行的契约形态。
  • FR3 — 缺失契约使用现有规范流程。 当组件契约缺失或不完整时,审计人员可以使用现有模板、模式、权威规则以及精确 HEAD 所有者审批流程,准备或完成一份 <Name>.spec.md 草案。缺失的草案不得阻止基于当前权威来源和可核查证据进行评级。
  • FR4 — 回填仅具有观察性。 由审计撰写的组件契约必须描述经过验证的已交付行为,且不得添加、改进、移除或重新解释行为。拟议含义仍是一个开放问题,或属于所有者的单独决定。草案不能将审计发现作为已定政策予以清除。
  • FR5 — 审计完整性记录在组件契约之外。 审计 PR 必须携带一份闭环证据回执。其有限清单来自公共导出与类型、有文档记录的概念与变体、通过公共 API 可达的状态与转换,以及从这些表面可达的实现分支。等效输入只有在证据表明其具有相同可观察契约时,才可以共享同一行。每一行需注明相关来源、现有测试、消费者文档、渲染证据、适用的当前权威来源或客观标准,以及任何冲突或缺口。该回执属于审计证据;它不会向 component-spec 模式添加必需章节。
  • FR6 — 现有权威来源解决冲突。 审计人员必须应用 architecture:knowledge-contracts 和 spec:AST-002。当前共享的权威来源与客观标准规定其适用范围。当前记录之间的冲突,或需要新的 API、兼容性、所有权或设计判断的问题,会中止客观修复并将其转交所有者。
  • FR7 — 客观修复可与审计 PR 共享。 一个 Night Watch PR 可以将观察性组件契约编辑与缺失的行为测试、稳定的视觉回归覆盖率、消费者文档漂移修复,以及所需结果已经确定的实现缺陷组合在一起。基线证据与每项修复的前后证明必须保持区分。
  • FR8 — 人工边界采用失败关闭原则。 公共 API 的含义或形态、默认值、兼容性或迁移承诺、所有权边界或冲突,以及主观的呈现、比例、密度或交互手感决策,必须保持人工复核,且不得自动合并。
  • FR9 — 审计模式保持区分。 Night Watch 不为普通逐项发现保留 issue,只记录其修复后的台账结果。评级和晋升保留其现有的按 BLOCK 记录的 issue 与记录流程。共享审计提示词必须保留所选模式。
  • FR10 — 自动合并需要精确 HEAD 资格报告。 Night Watch 审计器必须输出一份带版本号、机器可读的报告,其中包含:组件与包、审计模式与评估标准版本、被审计仓库与组件契约的 HEAD、FR5 清单闭合情况、未解决的客观与人工缺口、修复措施及其前后证据、必需的审批状态、必需的检查状态,以及带原因的失败关闭(fail-closed)资格判定。受信任的检查必须对照当前 PR 和 HEAD 验证该报告,在其摘要中公布每一项未满足的条件,并标注所需的 audit-eligibility 状态。该报告可以存放于受信任的 PR/检查元数据中;它不得要求第二份已检入的审计记录。任何缺失、过期、不一致或不符合资格的报告都会使 PR 保持打开状态,以待人工复核。
  • FR11 — 激活是独立、明确且原子化的。 自动合并始终保持不可用,直到该记录同时满足 authority: current 与 phase: shipped,并且激活变更已一并落地审计提示词、wiki 流程、规范化包/spec 覆盖、名册消费者、资格检查与针对性测试。未经完整激活的批准不会改变运行行为;每个审计 PR 仍仅限人工复核。本规范不要求进行组件模板或模式迁移,因为 FR5 将仅用于审计的证据保留在组件契约之外。

  • FR13 — 审计数据遵循现有存储权威。 持久的产品行为保留在组件 .spec.md 中。根据 architecture:knowledge-contracts,自动化 wiki component-scores.json 仍然是当前修复后分数和未解决发现的操作性数据存储;未激活的逐组件审计文件不是迁移目标。审计 PR 存储可审查的运行证据,受信任的 Check Run 存储 FR10 精确头部机器报告。任何未来的数据存储变更都需要单独的自动化迁移和切换契约。

  • FR14 — 评分使用组装后的适用契约。 每个审计部分 MUST 对来自当前全局权威和客观标准、当前家族契约以及当前组件/模块契约的适用需求进行评分。每条需求映射到一个评分细则部分和一个证据结果,因此同一个缺陷不会被计算两次。N/A 需求被排除;不可用的证据使用评分细则现有的 not_measured 行为。现有的严重级别、权重、等级区间和 BLOCK 上限保持不变,除非评分细则明确对评分变更进行版本化。

  • FR15 — 权威变更会使受影响的分数失效,而不会使全局量表失效。 对当前组件/模块契约的变更会使该组件的审计失效。当前家族或全局权威的变更会使每个关联的适用组件失效。评分细则版本仅在评分方法、权重、严重级别或证据处理方式变更时发生变化;单独的权威变更会在同一量表上触发有针对性的重新审计。

平台支持

  • 受支持的功能/引擎下限:仓库支持的 Node、浏览器和 CI。
  • 不支持的行为:无法解析的组件或缺失的证据仍然是明确的审计缺口,而不是消失或通过。
  • 浏览器证据:可见性和交互性声明使用审计评分细则和适用的当前记录所要求的真实浏览器证据。

当前状态影响

本已接受的规范不会改变任何审计自动化或组件契约模式。后续实现将更新共享审计名册及其沙箱视图、审计提示与模式处理、Night Watch 流程以及故障关闭(fail-closed)资格检查。这些更改仍与本规范 PR 分开。

验证

契约 验证 代表性状态 变更或失败预期
FR1 规范知识路径覆盖以及名册和沙箱一致性测试 全部五个目标包;不支持的包;新组件;私有辅助工具 某个包在其组件记录成为规范之前就被审计,队列与沙箱分叉,或符合条件的组件消失。
FR2–FR6 使用现有组件记录的审计固件 当前;草稿;缺失;有限的公共状态清单;等效输入;本地漂移;冲突 审计凭空生成第二种契约形态,遗漏可到达的公共状态,草稿变成策略,或冲突被奉为规范。
FR7–FR10 模式、报告模式、可信验证和资格测试 安全的目标修复;API/默认值/所有权/设计边界;带缺口的回执;过期的 head;缺少批准 不安全或不完整的工作自动合并,过期的报告清除状态,或一种模式接入了另一种模式的生命周期。
FR11 权威/阶段与激活测试 草稿;当前/提议;当前/已接受;当前/已发布且部分接线;完全激活 自动合并在显式状态之前激活,并且所有必需的表层同时落地。
FR12 TDD 追踪与行为测试审查 已确定的接缝;未确定的接缝;红色失败;最小绿色切片;与实现耦合的测试 生产变更先于红色出现,发明了未确定的接缝,或测试未观察契约就通过。
FR13 存储边界测试 wiki 账本;PR 证据;Check Run 报告;尝试性的逐组件日志 审计数据被重复写入、写入错误的属主名下,或从未经批准的数据存储中读取。
FR14–FR15 评分与新鲜度测试 全局/家族/组件需求;N/A;未测量;局部与共享权威变更 缺陷被计算两次,需求被遗漏,或受影响的分数仍被错误地视为最新。

决策日志

DEC-1 — 审计复用现有组件规范系统

参考: spec:AST-029/DEC-1 决策者: cixzhang,2026-09-06

审计回填使用现有的组件模板、模式、权威模型和组件记录。仅用于审计的完整性证据保留在审计回执中。

已否决:创建第二份组件规范指南,或向每个组件契约添加审计工作流字段。

DEC-2 — 回填与已确定的修复可一并推进

参考: spec:AST-029/DEC-2 决策者: cixzhang,2026-09-06

一份审计 PR 可以描述经核实的已发布行为,并使用前后对比证据修复客观缺陷。新的判断仍在该自动路径之外。

已否决:仅仅因为同一次审计发现了缺失的契约,就拆分一个安全修复。

DEC-3 — 自动合并使用结构化报告,而无需重复的已检入记录

参考: spec:AST-029/DEC-3 决策者: cixzhang,2026-09-07

Night Watch 以 FR10 中定义的版本化资格格式输出。受信任的检查会将其绑定到确切的 PR head,对照仓库状态进行验证,并发布所需的状态和原因。报告存放在受信任的 PR/check 元数据中,而不是第二个已检入的审计文件。评级与升级保持其现有的 issue 和 ledger 规则。

已否决:将非结构化文本作为自动合并输入、创建第二个仓库审计记录,或仅基于绿色 CI 的资格判定。

DEC-4 — 审计驱动的行为测试使用 Matt Pocock 的 TDD 技能

参考: spec:AST-029/DEC-4 决策者: cixzhang,2026-09-07

Night Watch 使用固定的公共 tdd 技能进行行为测试修复。当前契约或既定的公共接口决定了接缝;审计者不会自行发明。每个周期都会先在生产变更前验证红灯,然后通过可观察行为实现一个最小的垂直切片。

已否决:在实现之后再编写测试、测试内部实现,或在从第一个垂直切片获得经验之前生成所有测试。

DEC-5 — 审计数据仍按所有权拆分

参考: spec:AST-029/DEC-5 决策者: cixzhang,2026-09-07

自动化 wiki ledger 仍然是当前组件审计状态的操作型数据存储。审计 PR 存储一次运行的可人工审查证据,受信任的 Check Run 存储精确 head 的机器决策。组件契约仅存储持久的产品行为。任何未来的数据存储变更都需要显式的自动化迁移和切换契约。

已否决:为每个组件建立影子 ledger、在组件规格中存储屏幕截图或运行矩阵,或将瞬态 CI 产物视为唯一的审查记录。

DEC-6 — 评分保持稳定,同时动态组装适用的权威

参考: spec:AST-029/DEC-6 决策者: cixzhang,2026-09-07

评分标准保留其现有的部分、权重、严重级别、成绩区间以及对未计量项的处理方式。每次审计都会从适用的当前全局、家族、组件和模块需求中填充这些部分。权威变更会使关联的组件审计失效;只有评分方法的变更才会对评分标准量表进行版本化。

已否决:将每个本地需求复制到 wiki 评分标准中、当组件有更多需求时静默更改权重,或将规格编辑视为全局评分版本更改。

开放问题

无。

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