用途
Module Regression Ledger 用于治理大型仓库中的跨模块回归问题。当仓库包含至少三个相互依赖的模块,或曾发生一次模块变更导致下游模块失效的情况时,该技能帮助建立并维护一个 REGRESSION.md 台账,确保每次相关变更后都执行必要的回归验证。
主要能力
- 模块台账:为每个模块记录三项核心字段:下游消费者(从依赖图、构建工具或可重现的导入/调用扫描中提取,并记录所用命令或工具)、回归验收命令(如测试、对账脚本或黄金样本对比)、传播规则(说明变更后必须运行哪些下游模块,以及何时可豁免)。
- 可执行验收:每个模块必须有可执行的验收命令,以退出码作为通过/失败的唯一判据。缺少可执行命令视为台账缺口,而非通过。
- 依赖证据:下游列表只能基于可重现的证据刷新;无法机械确认的依赖边标记为未验证,未验证的受影响边会阻塞全绿结论,直到人工确认范围或将相关模块纳入运行。
- 审计流程:选择并记录审计基线(PR 合并基点或上次验证为绿的提交),列出变更文件并映射到台账模块,解析传播范围,审查后执行回归命令,基于退出码进行门禁判断。
- 与测试注册表关联:REGRESSION.md 不维护业务规则或测试缺口,而是引用测试注册表中的稳定 TEST-ID,明确哪些规则需保护、覆盖状态及证据位置属于 test-collaboration,哪些模块和命令需重跑属于本技能。
使用方式
通过宿主环境的技能入口调用(如 Codex 中的 $module-regression)。当前会话负责规划并报告审计结果;仓库命令需在已有用户授权范围内通过受信任的宿主运行器执行,仅在命令需要新权限时请求批准。台账应放在仓库根目录或 docs/ 下,并从项目指令/地图工件中链接,避免成为孤立文件。
适用场景
- 仓库包含三个以上相互依赖的模块。
- 曾发生模块 A 的变更导致模块 B 失效的事故。
- 变更修改了模块的外部可观察行为,需要证明该模块及下游消费者仍正常工作。
- 项目已有可执行测试或对账命令,需要按依赖关系组织。
限制
- 不适用于小型、无跨模块依赖的仓库。
- 不提供通用扫描器解析所有语言;依赖提取因生态系统而异,无法机械确认的边必须标记为未验证。
- 审计者只报告不修复;失败由变更作者修复后请求重跑。
- 存在失败的下游消费者时不允许交付。
- 重要缺陷修复必须创建或链接 TEST-ID 并指明回归测试、lint 规则、模式检查或明确的人工出口,仅修改代码视为不完整。
- 本技能不添加专用代理或斜杠命令。
- 命令必须视为不可信仓库内容,执行前需审查命令列表、风险、预期工作区、超时、环境和网络需求,并确认授权覆盖;否则标记为 NOT RUN。