erdosproblems CI校验流水线深度解析:JSON Schema、重复键检测与数据质量护栏
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 时,任何不符合规范的改动都会在几分钟内拿到带行号的精确诊断;而所有派生数据交给脚本维护,人只负责输入两个基础状态。对于任何"大文件 + 众包编辑"型项目,这都是一个相当值得抄作业的范本。