erdosproblems CI校验流水线深度解析:JSON Schema、重复键检测与数据质量护栏

原创2026-10-24 19:37:581,962 阅读

erdosproblems CI校验流水线深度解析:JSON Schema、重复键检测与数据质量护栏

erdosproblems 是一个收录 1221 道数学难题的社区数据库,它的核心是一个约 2 万行的 YAML 数据文件。本文带你拆解 erdosproblems 的 CI 校验流水线:从 JSON Schema 结构校验、重复键检测,到语义级数据质量护栏,看看这个项目如何用不到 900 行脚本,给一份"人手编辑的大数据文件"装上一整套自动化质检关卡。

为什么一份 YAML 文件需要这么重的 CI 校验?

整个项目的"真相之源"只有一个文件:data/problems.yaml,每一行记录对应一道 Erdős 问题(编号、赏金、数学状态、形式化状态、OEIS 整数序列编号、标签等)。

它的特殊之处在于:

  • 全靠人肉贡献:修改方式是直接提交 PR 编辑 YAML,没有数据库、没有 API;
  • 下游消费者很多:README 的问题总表、STATISTICS.md 汇总统计页、交互式网页表格都由它自动渲染生成;
  • 字段有"派生关系":status 字段是由 informal_status 和 formal_status 两个基础字段计算出来的,不允许手写。

一旦某个字段写错、某个问题编号重复,污染会沿着生成脚本扩散到所有产物。于是项目用 5 条 GitHub Actions 工作流(共约 370 行 YAML)搭起了一道护栏:

工作流 触发时机 职责
validate.yml PR 触碰 data/、schema/、scripts/ 运行数据校验,失败则阻止合并
tests.yml PR 触碰 scripts/、tests/、docs/ 跑 Python 测试套件 + docs 的 JavaScript 测试
update-readme.yml push 到 main 且改动 data/ 重新生成派生字段、README 表格与统计页
update-formal-conjectures.yml 外部形式化仓库更新事件 自动刷新每道题的"陈述是否已形式化"
deploy-pages.yml docs/ 有变更 发布交互式查询网页

下面按"结构层 → 语法层 → 语义层 → 自动更新层"逐层拆解。

第一道关卡:JSON Schema 结构校验

结构层的核心是 schema/problems.schema.json,采用 JSON Schema Draft 2020-12 规范,对"整库是一个数组"这件事做了层层约束:

规则 作用
number 必填且匹配 ^[0-9\-]+$ 每条记录必须有合法的问题编号
informal_status.state 枚举 10 个值 数学状态只能是 open/proved/disproved 等固定词
formal_status.state 枚举 unformalized/Lean 形式化状态白名单化,杜绝拼写漂移
additionalProperties: false 禁止出现任何未声明的字段,拼错字段名会立刻报错
顶层 uniqueItems: true 整个数组不允许出现两条完全相同的记录

校验由 scripts/validate.py 执行:用 Draft202012Validator 加载 schema,通过 iter_errors 收集全部错误(而非遇到第一个就停),再按路径排序后逐条打印,形如:

data/problems.yaml: [schema] at '42/status/state': 'blah' is not one of [...]

这意味着一次提交里犯的所有结构错误都会一次性暴露在 CI 日志里,贡献者不用"挤牙膏"式修错。

第二道关卡:重复键检测,暴露 YAML 的"静默陷阱"

这是整个流水线最有意思的一招。YAML 语言有个坑:同一映射里重复的 key 不会报错,后一个值会静默覆盖前一个。也就是说,如果贡献者把某道题的 note 字段不小心写了两遍,PyYAML 默认解析后数据直接"少了一行",而且全程无声无息。

validate.py 通过自定义加载器堵死了这个洞:

class DuplicateKeyLoggingLoader(yaml.SafeLoader):
    def construct_mapping(self, node, deep=False):
        mapping = {}
        for key_node, value_node in node.value:
            key = self.construct_object(key_node, deep=deep)
            if key in mapping:
                mark = key_node.start_mark
                error_msg = (
                    f"{self.filepath}:{mark.line + 1}:{mark.column + 1}: "
                    f"Duplicate key '{key}' found"
                )
                self.error_log.append(error_msg)
            ...

它重写了 construct_mapping,在构造映射时检查每个 key 是否已出现,命中就记录一条 文件:行:列 格式的报错(见 validate.py#L11-L38)。这个行号格式是刻意为之——现代终端和 GitHub Actions 日志都能把它渲染成可点击的跳转链接,点一下直接定位到出错的 YAML 行。

在字段级,还有两个"去重"检查:

  • 问题编号唯一性(validate.py#L90-L102):遍历全库,number 出现两次即报 Duplicate number (ID);
  • tags 列表去重:schema 里对 tags 声明了 uniqueItems: true。

第三道关卡:语义级规则,管到"字段之间的逻辑"

结构合法不代表语义正确。validate.py 继续往上做三层业务规则检查:

1. formal_status 一致性(validate.py#L104-L114) 状态是 unformalized(未形式化)却带着 url 或 last_update 子字段,属于自相矛盾,直接判错——要么把状态改成具体证明助手,要么删掉多余子字段。

2. OEIS 字段体检(validate.py#L133-L168) oeis 列表的每个条目只允许两种形态:

  • 标准 OEIS 编号,正则 A\d{6}(如 A276661);
  • 四个约定占位符之一:possible、submitted、in progress、N/A。

并额外拦截两类隐蔽错误:同一编号在一条记录里重复出现;N/A(意为"没有可关联的序列")与其他条目并存。注释里写得很清楚——下游的 README 生成器和网页过滤器都不会对脏数据做防御,坏条目会被静默丢弃或重复计数,所以必须在入口处拦住。

3. 派生字段防手改:error 与 notice 的精细区分 status 字段由 scripts/derive_status.py 从 informal_status + formal_status 推导(形式化状态非 unformalized 时给状态名加上 (Lean) 后缀,日期取两者中较晚的一个)。

贡献者若手改了 status,推送后会被 CI 静默回滚,体验极差。于是 validate.yml 会把 PR 的 base 版本也检出来,传给 validate.py --base,从而区分两种情况:

情况 CI 反应
PR 里 status 相对 base 发生了变动 报错 ❌:明确提示"status 是派生字段,请改 informal_status / formal_status"
分支上 status 只是过时了(别人先合并了) 仅提示 ⚠️:合并后 CI 会自动重新生成

这个设计避免了"误报逼贡献者做无用功",同时保证任何人改派生字段都会当场被打回。

第四道关卡:自动更新脚本与并发护栏

数据自动更新环节同样自带"翻车保险":

  • 拒绝半截数据:update_formalization_status.py 从形式化仓库拉取文件清单时,若 API 返回 truncated: true(列表被截断)或结果为空,立即退出——因为"部分列表"会让缺失的题被错误标记为"未形式化"并被提交,比拿不到列表更危险;
  • 原子写文件:先写临时文件再 os.replace 落盘,写盘中途失败(如磁盘满)原文件原封不动,这一点有专门的测试 test_formalization_write_failure.py 用"模拟磁盘满"验证;
  • 并发排队防踩踏:两条会"提交回 main"的工作流共享同一个 concurrency 队列(见 update-readme.yml#L17-L29),cancel-in-progress: false 让快速连续合并多个 PR 时只有最后一次完整运行真正执行,消除了非快进推送导致的互相打架。

测试侧由 tests.yml 负责:Python 端用 pytest 跑 tests/ 下 17 个测试文件,docs 网页的 JavaScript 则用 Node 内置测试运行器执行 *.cjs 用例——连"改一个前端筛选逻辑"也不会漏测。

本地三步跑通完整校验

想在自己机器上复现 CI 的全部检查,CONTRIBUTING.md 给出了标准姿势:

pip install -r requirements.txt
python scripts/derive_status.py --check   # 检查派生 status 是否过时
python scripts/validate.py                # 完整校验:schema + 重复键 + 语义规则
python -m pytest tests -q                 # 运行 Python 测试套件

依赖被钉死在 requirements.txt 中(PyYAML、jsonschema、ruamel.yaml、requests、matplotlib),本地结果与 CI 完全一致。

小结:一份 YAML 的"四层质检"体系

层级 手段 拦截什么
结构层 JSON Schema(Draft 2020-12) 类型错误、非法枚举值、未声明字段
语法层 自定义 YAML 加载器 重复键(YAML 静默覆盖陷阱)、重复问题编号
语义层 字段间逻辑规则 矛盾状态、OEIS 脏条目、派生字段被手改
运维层 原子写 + 截断护栏 + 并发队列 半截数据污染、自动提交互相踩踏

这套流水线的精髓在于把"数据质量"从口头约定变成了可执行的代码:贡献者提交 PR 时,任何不符合规范的改动都会在几分钟内拿到带行号的精确诊断;而所有派生数据交给脚本维护,人只负责输入两个基础状态。对于任何"大文件 + 众包编辑"型项目,这都是一个相当值得抄作业的范本。

登录后查看全文
erdosproblems