SuperAPI AI 工具集

adr-verify

编程与开发

查看项目

更新于 10-15 15:49

技能介绍

ADR Verify 是 ADR 索引流程的读回校验技能,配套 adr-index 使用。

用途:在导入后读取持久化的 adr-patterns 与 adr-edges 命名空间,暴露图完整性缺陷。可检查三类问题:悬空引用(边指向 adr-patterns 中不存在的 ADR ID,常见原因是所引用的 ADR 位于同级仓库或已被删除);supersede 循环(ADR-A 取代 ADR-B 且 ADR-B 取代 ADR-A,或更长的循环,属于数据损坏);状态不匹配(某 ADR 是 supersedes 边的源,但自身状态并非 Superseded,通常是后继 ADR 晋升时漏改状态)。

无法检测的情况:若某 ADR 已从磁盘删除,其对应的 adr-patterns 行仍存在,且没有任何入边或出边引用它,上述所有检查都无法发现。若报告中的 ADR 数量高于磁盘实际数量,应运行 adr-reindex,而非再次运行 adr-verify。

使用方式:在刚运行 adr-index 后使用以确认图健康;也可放入 CI 作为 fail-closed 门禁(VERIFY_STRICT=1 时任何问题都以退出码 1 失败);发布 ADR 相关版本前使用。

命令:node plugins/ruflo-adr/scripts/verify.mjs

可选环境变量:VERIFY_FORMAT=json 输出 JSON 而非 Markdown;VERIFY_STRICT=1 出现任何问题时退出码 1(默认仅在循环时)。

退出码:0 表示图健康,或在非严格模式下存在悬空引用/状态不匹配;1 表示检测到 supersede 循环,或严格模式且存在任何问题。

相关:adr-index 填充本技能所校验的数据;scripts/import.mjs 自带 dry-run 校验,本技能是读回配套;adr-reindex 用于协调 adr-verify 无法检测的已删除 ADR。