实现契约：从课程到可验证系统¶

DL-Hub 是一个可运行的深度学习课程与模型注册仓库。它的主线不是堆叠论文名称， 而是让一个主题沿着同一条路径落地：问题定义 → 数据 → 模型机制 → 训练与评估 → 运行产物 → 证据与升级。每个名称都应说明代码实际做了什么，不能用规模感或论文名 替代机制证据。

三个互不替代的维度¶

三者必须分别陈述。例如，“使用 synthetic 数据完成 smoke”只证明离线链路能运行， 不会让模型自动变成低保真实现；同样，compact 模型通过 smoke 也不等于论文完整配置的 benchmark 复现。

代码命名规则¶

• Compact* / compact_*：保留课程所讲的核心计算路径，同时缩小宽度、深度、 输入尺寸或训练预算。课程目录采用这一命名，明确它是可研究、可运行的缩放实现。
• build_baseline_* / *_baseline.py：多个注册入口共享的领域基线。它描述代码角色， 不是保真度等级；论文名若仅委托给它，台账必须标为 baseline-alias。
• Synthetic* / synthetic_*：只描述程序生成的数据、标注或数据辅助模块， 不用于给模型能力或课程规模命名。
• smoke：只描述快速运行验证，不用于模型、数据集或课程名称。

旧的随意规模标签已从维护中的路径、API 和文档移除，也不保留双重兼容别名。 这样导入路径、日志、文档链接与课程名称只有一个事实来源。

一节课的完整叙事¶

1. 定位问题：课程 README 说明任务、输入输出、核心机制与验收边界。
2. 选择数据：真实数据课程可以提供 fake 离线路径；无需外部数据的课程使用 synthetic 生成器，并明确生成规则与标签含义。
3. 实现机制：model.py 暴露任务模型；紧凑课程保留关键计算，而不是只返回形状正确的 占位张量。共享模型通过清晰的 baseline 工厂复用。
4. 运行实验：train.py 连接数据、损失、优化器与任务指标，并把配置、指标、检查点和 可选可视化写入 outputs/<track>/<lesson>/<run_name>/。
5. 分层验证：静态 contract 检查仓库结构；smoke 检查最短链路；针对性测试验证本次修改 的关键行为；只有正式数据、训练配方和指标对齐后才谈 benchmark。
6. 留下证据：Model Zoo 注册量只表示可寻址配置。源码审计结果进入保真度台账，记录 已实现机制、缺失机制与下一步，而不是靠类名推断完成度；数据路由、运行快照和正式 benchmark 结果分别进入数据与 Benchmark 证据。

从基线走向参考实现¶

升级必须对应可观察的代码与行为变化：

1. baseline-alias → compact：补上该方法的标志机制，并用最小行为检查证明机制实际生效。
2. compact → reference：继续核对论文或官方实现的关键计算路径、默认配置和稳定接口。
3. benchmark 声明：另外记录数据版本、训练预算、评估协议、权重与复现实验结果。

仅复制文件、修改类名、增加注册 ID 或让随机输入通过前向，都不能提升保真度等级。 当前逐项审计证据见 Model Zoo 保真度审计。

维护入口¶

# 检查维护代码中是否重新出现旧命名，并验证文档/导入里的 lesson 路径
python scripts/narrative_check.py

# 检查课程结构与 Model Zoo 保真度元数据
python scripts/lesson_contracts.py --check
python scripts/model_fidelity.py --check
python scripts/benchmark_profiles.py --check

# 一次运行 lint 与以上静态/元数据检查（不启动 pytest）
make verify

这些命令是静态或元数据检查，不启动训练，也不替代针对本次改动的最小必要测试。