校验器与发布门禁
为什么每项能力都带有断言行为与接线的可执行检查,以及发布门禁如何决定哪些检查必须通过。
Kernlift 的每项能力都带有一个校验器,即检查功能可用且可访问的可执行脚本。发布门禁决定其中哪些检查必须通过。完整脚本列表见校验器。
每项能力一个校验器
scripts/validate/*.ts 中每项能力一个检查,每个都以 validate:* 脚本形式出现在 package.json 中,并串入 pnpm validate:all。校验器存在并通过之前,改动不算完成。模块也自带校验器,在其清单中列出。
校验器会报告它运行的每项检查,大多以 JSON 报告形式列出各项检查及其证据,任何检查失败时以非零状态退出。
断言行为与接线,而不是文件存在
只断言文件存在的检查,在文件没有被任何路由引用时照样通过。这个仓库不止一次交付过这种 bug,所以校验器断言行为与接线。常见形态有:
| 形态 | 证明什么 |
|---|---|
用 validate- 前缀的夹具在真实数据库上运行仓储或服务,然后清理 | 逻辑在真实表上可用,包括失败路径 |
| 用真实营销快照在两种语言下渲染页面 | 页面在中英文下展示真实数据,没有写死的价格 |
| 读取路由、壳与字典 | 功能可访问:已路由、已守卫、在导航中且已翻译 |
校验器从不伪造服务商。需要真实凭据的检查放在外部验证中。
发布门禁
目前并非每个校验器都能通过。pnpm validate:all 运行整条链并在第一个失败处停止,在已知有检查失败时不能作为门禁。CI 运行 pnpm validate:gate:
| 分组 | 门禁如何处理 |
|---|---|
| 未列为已知失败的校验器 | 必须通过;任何失败都算回归 |
scripts/validate/known-failures.json 中的校验器 | 同样运行;开始通过的必须从列表中移除 |
validate:all、validate:gate、validate:storage-drivers | 门禁不运行。存储驱动检查会向存储桶写入真实对象,所以只在有意为之时运行 |
每个已知失败都写明了原因和修复所需的工作。这个列表只能缩短。开始失败的校验器必须修复,不能加进列表。做改动时,记录改动前后的通过与失败集合,确认没有把通过的检查变红。
外部验证
本地校验器检查状态机和未配置路径。针对真实服务商的检查需要沙箱或生产凭据,通过 pnpm validate:external 单独运行。没有凭据时这些检查报告为跳过,EXTERNAL_VALIDATE_STRICT=true 会让跳过的检查失败。见运行时与数据库适配器。
重要的校验器
| 脚本 | 证明 |
|---|---|
validate:auth-boundary | 每个 API 路由要么有守卫,要么显式公开并说明理由 |
validate:migrations | 两条迁移链都能重放并与 schema 一致 |
validate:billing-fulfilment | 计费对每个已启用的履约插件只通知一次,失败会被记录并由定时任务重试 |
validate:optional-agent | 不部署 Agent 服务时 Web 应用完整可用,定时任务凭一把锁运行 |
validate:plugins | 插件注册表拒绝冲突,停用会级联,每个贡献的入口都指向真实的路由文件 |
validate:store-boundary | 销售 Kernlift 的那部分没有回到模板里 |
validate:products | 服务端定价、授权签发与撤销、全量授权展开 |
validate:registry | 底座加模块能重现仓库;底座可以单独通过类型检查 |
validate:init-cli | 令牌从不出现在 argv 中、拒绝未授权项、升级保留本地修改 |
validate:skills | 技能只引用真实存在的脚本、路径、路由和命令 |
validate:module-catalog | 模块页面基于真实快照渲染,没有价格字面量 |
validate:docs | 双语导航与链接可解析;模块、Agent API、数据表和环境变量参考与源码一致 |
validate:landing-blocks | 首页上的数字是从仓库实际统计出来的 |
validate:products、validate:module-catalog、validate:docs 和 validate:landing-blocks 属于商店项目,由模板创建的项目里没有它们。
相关文件
change-path.ts 能同时解析进行中和已归档的 OpenSpec 变更,所以没有任何校验器写死变更目录。render.ts 在服务端渲染页面,让检查可以对渲染出的标记做断言。fixtures.ts 创建并清理检查需要的 validate 前缀数据行,所以检查不依赖种子数据。