验证

介绍

验证证据应和改动 surface 成比例：足够小，可以本地运行；足够具体，可以抓到回归；对跳过的重型阶段要明确说明。

按变更类型选择证据

• 只改文档 — npm run types:check、npm run build、受影响 route 返回 200。提升状态时的额外证据：布局或交互变化需要浏览器截图。
• CLI 或 runner — 公开 CLI 目录检查加代表性 evaluate 命令。提升状态时的额外证据：如果输出契约变化，再跑 existing-results 和 model-mode runs。
• Model manifest — zoo model-show、zoo model-download --check-local。提升状态时的额外证据：Clone、checkpoint、demo parity、runner parity、benchmark run。
• Model runtime integration — 仓内 runtime import、无机器本地 source checkout 依赖、带 backend_stage 的 runtime profile，以及聚焦回归。提升状态时的额外证据：Checkpoint-backed run 和一份 normalized benchmark scorecard。
• Benchmark manifest — zoo benchmark-show、preflight runtime --profile <benchmark-id>。提升状态时的额外证据：Clone、dataset、official runtime、normalized scorecard。
• Benchmark runner — zoo benchmark-run --mode official-validation 或 --mode official-run。提升状态时的额外证据：Official result import、official runtime 和 full-suite fairness gate。
• Suite 或 matrix — run --all-benchmarks --plan-only --json。提升状态时的额外证据：规划选中的 cells，然后用可运行 benchmark 路径验证 artifacts。

公开测试

一方测试源码统一存放在 tests/，随仓库和 sdist 发布，采用仓库的 Apache-2.0 许可证。wheel 只包含运行时包。

python -m pip install -e ".[test]"
make test
# 开发时可以单独运行某项测试：
python -m pytest -q tests/runtime/test_geometry_regression_impact.py

默认 CPU 门禁覆盖进程日志、模拟 GPU 租约、checkpoint staging、任务持久化、Conda dispatch、推理取消与超时、worker 退出和打包边界。它不需要 CUDA、模型下载、Torch 或 API 凭据，CI 使用同一选择。make test-infer 是别名；系统的 python 仍为 Python 2 时，使用 make test PYTHON=python3。

make test 还包含覆盖策略、官方推理证据、固定历史参考和 JUnit 验证器的测试。Make 门禁先独立收集完整节点清单，再执行测试，拒绝 skip、collection error、少跑、多跑、重复节点、源码改变和旧报告。TEST_ARGS 只影响执行阶段，使用 -k 或 -m 漏跑节点仍会失败。CI 发布完整清单及 JUnit。标准库成功 subtest 保留父节点，失败或跳过的 subtest 仍使门禁失败。

扩展测试可能依赖 eval_core、ui、模型专用环境、本地 assets 或 CUDA。部分历史断言还涉及私有 training / benchmark 实现或旧布局；公开 CPU 门禁是当前支持的 CI 基线，安装 test extra 不会准备这些额外资源。

python -m pytest -q tests/eval_core/test_evaluate_runner.py
python -m pytest -q tests/studio/test_conda_dispatch.py
python -m pytest --collect-only tests
PYTHONPATH=. python tests/manual/test_wan_2p2.py
PYTHONPATH=. python tests/stream/test_wan2p2_stream.py
WORLDFOUNDRY_DOCKER_GPUS=none tests/run_tests_docker.sh
WORLDFOUNDRY_DOCKER_EXTRAS=test,eval_core tests/run_tests_docker.sh make:test-eval-core

manual/ 和 stream/ 不参加递归 pytest collection。直接运行前需要准备模型环境；脚本可能下载 weights、占用 GPU、调用真实 API 并写出产物。凭据使用 provider 的环境变量。MiniMax H3 的真实权重测试使用 MINIMAX_H3_CKPT_DIR，默认 ~/.cache/worldfoundry/checkpoints/minimax-h3-components。

新增确定性回归放在对应模块目录，小型文本 fixture 放在该 suite 内。导入时直接执行推理的脚本放入 manual/ 或 stream/。checkpoint 路径使用环境变量，资源不可用时跳过真实权重测试；缓存、日志、输出、凭据和 weights 不进入 Git 或源码发行物。

推理契约与 CUDA 快速检查

仅安装公开测试依赖、CPU Torch、safetensors 和 einops，即可运行张量测试，不需要 checkpoint、渲染器或 GPU：

python -m pip install "torch==2.7.1" --index-url https://download.pytorch.org/whl/cpu
python -m pip install -e ".[test]" "safetensors>=0.4" "einops>=0.7,<0.9"
make test-infer-tensors

在已准备的 3D 模型环境中继续运行结果导出和 CUDA 测试。结果导出会导入该环境的模型和渲染依赖，包括 plyfile 和 gsplat：

make test-infer-contracts PYTHON=/path/to/model-env/bin/python
make test-infer-cuda-contracts PYTHON=/path/to/model-env/bin/python

第一个目标使用小张量和已知几何，不加载模型权重，覆盖 checkpoint 往返与 meta 参数赋值、加载失败前的原子校验、键重命名冲突、相机坐标约定、带 mask 的 PLY 和原始数组导出、跨进程结果序列化、异常恢复和并发提交。CUDA 目标检查 producer event 的先后顺序、pinned-memory 拷贝、失败 fallback，以及回调报错后已入队工作的同步。CUDA 不可用时该目标直接失败，不能用整个 suite 都被 skip 来表示通过。

设置下文的 checkpoint 和输入目录后，还可以运行短的真实 Pi3X 测试，比较复用模型和新加载模型，覆盖换输入、失败请求和重复推理：

python -m pytest -q tests/pipelines/test_pi3x_real_inference.py

这是请求状态隔离检查，不代表结果质量已经验收。模型行为发生变化时仍需运行固定权重的数值回归门禁。

Video generation 与 world model

LTX 的 timestep-conditioned VAE 在解码时也会注入噪声。视频、音视频和带请求的张量解码现在使用 latent 所在设备上的独立 generator，seed 来自当前请求。真实小型 VAE 测试覆盖分块与不分块解码、A/B/A seed、全局随机状态隔离，以及与原 VAE 在相同随机状态下的精确一致性。不分块的张量解码直接调用 decoder。旧 LTX RGB 受未固定的全局随机状态影响；建立确定性 reference 时必须记录这一行为修复，并独立证明 latent 与受控解码的一致性，不能静默替换失败基准。

make test-infer-tensors 同时运行视频共享组件的数值测试；只运行这一部分可用 make test-infer-video-tensors。它用小型真实 Wan 网络比较融合 QKV、静态 cross-KV 缓存与原始网络，覆盖不同 batch、时间/空间 shape、非连续 layout、换 prompt 和重复请求。VAE 因果卷积与独立全序列卷积对比，并检查未来帧不会改变过去输出。采样与 CFG 使用已知解析结果，检查 UniPC 的状态重置、失败请求清理及全局 RNG 隔离。显式传入零或负数的尺寸、帧数、步数和 fps 必须在模型推理前失败，只有 None 使用默认值。

同一个 tests/manual/geometry_regression_cases.json 现在包含几何、视频和世界模型案例。原有脚本和 GEOMETRY_* 名称继续可用；plan-inference、replay-inference 和 verify-inference 是覆盖更广的入口。新增短案例分别声明 Wan 2.1 1.3B、Wan 2.2 TI2V 5B、LTX 0.9.8 I2V、CogVideoX 2B、Cosmos Predict 2.5 2B、Matrix Game 2 和 DreamX World 5B AR。LTX 保留原生两阶段十步配方，其他采样参数也由案例显式固定。这些短案例比较 latent、原始帧、导出的 RGB 像素和 fps，检查换条件后输出变化、A/B/A 请求、失败恢复，以及因果块的延续、reset 与重放。它们验证具体输入下的集成和请求隔离，不验证完整 demo 的生成质量。

额外案例声明 Cosmos Transfer 2.5 的 general/edge 2B 权重、Gamma 已发布的四步因果权重，以及 Oasis 500M 的视频 prompt 入口。Gamma 按权重要求固定每视角 189 帧，检查两个 320×480 视角，以及拒绝短请求后重放。Transfer 先采样最小 93 帧窗口（24 个 latent 帧），再裁剪出请求的 17 个 RGB 帧。请在 WORLDFOUNDRY_REGRESSION_INPUT_ROOT 下准备至少 17 帧的 control.mp4（更长的视频还可检查条件读取是否有界）；在 gamma-world/buildHouse_flat 下放置官方样本的 first_frame.png、prompt.txt、action_left.json、action_right.json。Oasis 使用多帧 open-oasis/context.mp4 和两行、每行 25 列的 open-oasis/forward.one_hot_actions.json：第 11 列（从 0 开始，forward）为 1，其余列为 0。适配器读取一个 prompt 帧，将末行动作延续到六帧输出。各案例显式列出权重及编码器、tokenizer 路径。这些声明用于选择待执行的回归，不代表 GPU 已运行或其他变体已覆盖。

视频案例可以用 sequence 替代单次 call。每一步包含唯一 name、method（默认 __call__）、call 和需要记录的 outputs。outputs: [] 用于只配置或重置会话；expect_error 必须指定精确异常类型与消息模式，其他异常仍会失败。返回的 CPU buffer 会立即复制，后续请求不能覆盖前一次证据。comparisons 的 equal / different 是单次运行内的约束；array_contracts 声明 shape、dtype、数值范围或精确 values，例如 fps 的分子/分母。export_artifacts 声明本次运行目录内需要完整解码并比较的 MP4。参考与候选仍要求数值完全一致。

只返回视频路径的生成器可以用 output_arrays 选择运行目录内的 MP4、WebM、MOV 或 MKV。回归工具完整解码后，将 artifact.<相对路径>.frames 和 .fps 保存到 arrays.npz，因此路径或计划本身不能满足必需数值输出。还应在 export_artifacts 中声明视频，比较导出文件解码后的像素及帧率。Oasis 的子进程只返回 MP4，没有内存张量，因此使用此入口；生成器的随机种子固定为 0。

make coverage-inference PYTHON=python3
make plan-inference PYTHON=python3 INFERENCE_BASE=<comparison-commit>
make replay-inference PYTHON=/path/to/prepared-env/bin/python \
  INFERENCE_PROFILE=/private/path/inference-regression.json
make verify-inference PYTHON=python3 \
  INFERENCE_PROFILE=/private/path/inference-regression.json \
  INFERENCE_REPORT=/private/path/completed-run/report.json

覆盖报告按 catalog 的 native binding 和同一 pipeline class 下注册的 variant 列出缺口。相同 class、模型家族、alias 或历史 verified 状态都不会自动给另一个 model ID 分配案例。case_defined 只表示有测试配方；报告不会将其提升成 reference 已验收或 GPU 已通过。固定基线保留既有缺口，同时 CI 拒绝新增未覆盖身份、既有配方退化，以及实际受影响却没有可执行数值回放的 native 变体。需要完整覆盖的发布可添加 --require-complete，存在缺口时退出码为 2。

Runtime profile 按声明的 model ID 和 pipeline binding 识别归属，并纳入 source_repos[].in_tree_path，覆盖静态 import 图无法发现的子进程代码。这些声明补充静态依赖；未知路径仍保守扩大选择，受影响的 native 变体没有真实权重回放时仍失败。

追加案例及组件声明时，只有实际提交前后的定义能证明全部既有配方、归属和全局规则未变，才只选择新增案例。测试编排工具改动还要求提交中的 runtime、环境和 assets 不变，工作文件与提交一致，并通过对应 CPU 契约和真实 MG2 smoke 回放。生产代码变更仍独立加入选择；未提交定义、删除或重新分类都会保留完整回放范围。

旧 InSpatio、LingBot Cam/Act/V2 和 ATI 案例分别加载各自发布的 checkpoint。WORLDFOUNDRY_REGRESSION_INSPATIO_SCENE_ROOT 指向含 video_example_00/input/{video.mp4,target_tcw.txt} 的已验收场景；WORLDFOUNDRY_REGRESSION_LINGBOT_CONTROLS 包含 21 帧的 poses.npy、intrinsics.npy，Act 还使用 action.npy。ATI 的固定量化 packed-NPZ tracks 文件由 WORLDFOUNDRY_REGRESSION_ATI_TRACKS 指定。输入与权重均保存哈希；这些短数值案例不代表完整 demo 质量或其他 variant 已通过。

verify-inference 检查可信 GPU 主机生成的报告与当前 commit、源码 tree、案例矩阵、依赖声明和固定 reference index 一致，选中案例全部执行，且所有数值字段完全一致。预检查、过期 commit、少跑案例、放宽容差和失败结果不能通过。公开 CPU 与张量门禁仍必须分别通过。

Hosted CI 的 inference-replay 必须读取维护者通过控制 workflow dispatch 发布的官方 Actions artifact；缺失、过期、外部来源或旧提交的证据都会失败。专用 dispatch 检查候选 commit、tree、比较基线及固定 reference index 后发布 trusted-inference-evidence，只运行 attestation，普通 CI 再消费它。真实回放在已准备的可信 GPU 主机执行。仓库须配置 INFERENCE_EVIDENCE_CONTROL_REF、INFERENCE_EVIDENCE_WORKFLOW_PATH 和 INFERENCE_REFERENCE_INDEX_SHA256，并在合并分支保护中要求 inference-replay 及 CPU 检查；仅添加 workflow 不会自动启用分支保护。未覆盖或未执行的变体仍是缺口。

MG2 改动及其数值契约改动还必须通过六条真实图像、12-block 轨迹的固定历史参考检查。门禁锁定已验收报告的完整 digest，逐步精确比较 flow/x0、全部滚动缓存、条件、latent/video/RGB 像素、VAE 状态和连续 RNG。两条当前路径互相一致不足以通过。此独立检查与公开 pipeline 的 A/B/A 回放都必须完成，不能互相代替，也不会自动更新参考。

先提交候选再跑两项 GPU 门禁，用 tests/manual/inference_actions_evidence.py compact 传入 --base、--head、--conditioned-report、--junit、--generic-replay 和 --output，环境中设置固定的 INFERENCE_REFERENCE_INDEX_SHA256。在控制分支 dispatch CI，三个输入为候选 source_revision、比较 base_revision 及压缩报告 evidence_json。官方 dispatch 成功后重试该候选的 inference-replay job。配套 inference-evidence-verified.yml 部署到默认分支后会自动重试；部署前需要显式重试。

验证门禁要求使用 --base 生成的 commit diff 计划，并重新计算实际变更路径。手工列举或遗漏变更文件的计划无法绕过受影响案例检查。

持续优化时如何验证

用最近一次成功回放的 source_hashes 辅助判断影响范围，再结合显式组件/能力声明和静态依赖。动态记录只覆盖实际执行的路径，无法覆盖未执行分支或动态选择的 backend；依赖关系无法确认时保留为未覆盖，并扩大对应组件的测试。保留参考实现供差分测试和 fallback 使用。精确优化与有损优化分开：后者必须明确数值和任务质量阈值，不能静默放宽容差或重新生成基准。

GitHub CI 在 PR、main 和 release/** 的 push，以及手动触发时，自动运行公开 CPU、CPU Torch 张量和打包门禁，并发布受影响案例计划。真实权重回放和更广的模型 benchmark 依赖已准备的模型环境；定时 GPU 回归通过下面的主机定时任务执行。

自动选择受影响案例

make plan-geometry PYTHON=python3 GEOMETRY_BASE=<comparison-commit>
# 可选：叠加已通过回放的实际导入记录。
python3 tests/manual/geometry_regression_impact.py --base <comparison-commit> \
  --evidence /absolute/path/to/successful-runs --output tmp/3d-regression-plan.json

选例结合 tests/manual/geometry_regression_dependencies.json 中的组件声明、条件和相对导入、字符串形式的 lazy import、父包初始化文件及可选的实际导入记录。Git rename 和删除会保留旧路径。共享 infra 或案例矩阵变化选择全部案例；新增案例必须声明依赖。未知路径或无法解析的导入图会扩展到全部案例，并以 uncovered 非零退出，需要补上覆盖缺口。只有文档变化时可以返回 no_inference_changes，CPU 门禁仍需通过。

只有 planner 和源码快照编排工具具有较窄的验证规则：不可变 Git entries 必须证明全部运行时代码、环境、assets、案例及依赖定义完全不变，完整 diff 及检查的工具文件也必须与提交 blob 一致。此类改动仍要求完整 CPU 契约和 MG2 两项 GPU 门禁，验证完整工具链。缺少历史、案例定义变化或混入任何生产改动，仍保留原来的全量保守模型选择。

CI 即使选例失败也会上传 geometry-impact，其中是必须执行的回归计划，不能当作 GPU 推理通过的证据。执行器拒绝源码树或规则哈希过期、状态与空选例矛盾，以及漏掉当前规则和导入图要求的案例的计划。

在模型主机上定时执行 GPU 回归

使用与参考结果相同的模型 Python、已验收 assets 和环境。先将明确验收过的结果复制到持久化的私有目录：

python3 tests/manual/geometry_regression_schedule.py import-reference \
  --source /absolute/path/to/accepted-runs \
  --destination /absolute/path/to/private-state/reference

导入器保留原始结果，只迁移导出产物路径，验证数值完全一致，并记录复制后每个文件的 SHA-256。目标目录已存在时拒绝覆盖。将返回的 reference_index_sha256 写入私有 profile，例如 ~/.config/worldfoundry/geometry-regression.json：

{
  "source_root": "/absolute/path/to/WorldFoundry",
  "source_ref": "refs/heads/your-validated-branch",
  "python": "/absolute/path/to/model-env/bin/python",
  "matrix": "tests/manual/geometry_regression_cases.json",
  "dependencies": "tests/manual/geometry_regression_dependencies.json",
  "reference": "/absolute/path/to/private-state/reference",
  "reference_index_sha256": "<import-reference 返回的 SHA-256>",
  "state_root": "/absolute/path/to/private-state",
  "cuda_visible_devices": "0",
  "env": {
    "WORLDFOUNDRY_REGRESSION_CHECKPOINT_ROOT": "/accepted/checkpoints",
    "WORLDFOUNDRY_REGRESSION_INPUT_ROOT": "/accepted/multiview-frames",
    "WORLDFOUNDRY_REGRESSION_INPUT_IMAGE": "/accepted/input.png",
    "WORLDFOUNDRY_REGRESSION_PANORAMA": "/accepted/panorama.jpg",
    "WORLDFOUNDRY_REGRESSION_LYRA_INPUT_IMAGE": "/accepted/lyra-input.jpg"
  },
  "case_timeout_seconds": 1800,
  "suite_timeout_seconds": 7200,
  "retain_runs": 7
}

可选的 gpu_holder 配置指定原有 gg 脚本的绝对 script、字符串列表 start_args、包括 GG_PYTHON 的 env，以及可选的日志就绪标记 ready_patterns。回放期间停止该脚本；成功、失败、超时或中断后，以独立 session 恢复。若推理子进程无法清理或 GPU 租约无法释放，执行器报告失败，并推迟占卡脚本恢复，直到残留资源清理完成。

将必要的 LD_LIBRARY_PATH、CUDA_HOME 等运行变量保存在私有 profile 的 env 中。cron 任务保留已准备的工具 PATH。CUDA 预检查会在加载权重和停止占卡脚本前，逐项检查 Python、Torch、CUDA、cuDNN、GPU 和包版本是否与全部选中基准一致；环境变化直接失败，不放宽比较条件。

在不同 Python/Torch 环境中验收的模型使用私有 case_environments 覆盖，例如 "case_environments": {"flashworld": {"python": "/absolute/path/to/flashworld-env/bin/python"}, "worldfm": {"python": "/absolute/path/to/worldfm-env/bin/python"}}。每个覆盖还可以提供 env，叠加到默认环境之上。每种选中环境分别进行预检查，案例使用各自配置的解释器运行；未知案例 ID 会被拒绝。

# 先用一个案例验证执行器，再开启每日完整短矩阵。
python3 tests/manual/geometry_regression_suite.py \
  --profile ~/.config/worldfoundry/geometry-regression.json --preflight-only
python3 tests/manual/geometry_regression_suite.py \
  --profile ~/.config/worldfoundry/geometry-regression.json --case-id pi3x
python3 tests/manual/geometry_regression_schedule.py install \
  --profile ~/.config/worldfoundry/geometry-regression.json --hour 3 --minute 0
python3 tests/manual/geometry_regression_schedule.py status \
  --profile ~/.config/worldfoundry/geometry-regression.json
# 只删除带 WorldFoundry 标记的 cron 区块。
python3 tests/manual/geometry_regression_schedule.py remove \
  --profile ~/.config/worldfoundry/geometry-regression.json

安装保留其他 cron 条目，时区为 Asia/Shanghai。控制脚本来自已提交版本；控制脚本变化后需要重新安装。每次运行从指定的本地已提交 ref 生成隔离快照，不自动 pull/reset，也不执行工作区未提交代码。案例各自使用独立模型进程，共用主机上的物理 GPU 租约锁，有单案例和整套超时，并接受严格数值和导入源码审计。每日运行完整短矩阵；按需执行时可传 --plan 使用受影响案例计划。

latest.json 在开始时记录 running，结束时记录最终结果；runs/ 保存日志、源码版本和比较报告。默认保留最近七次运行目录，更早的简要报告归档到 history/。已验收基准必须位于可清理的运行目录之外，执行器不会重新生成或覆盖它。profile、本地 assets、权重和数值证据不进入 Git。

--preflight-only 检查全部选中案例的 assets 和环境，不加载模型权重；其 preflight_passed 状态不能当作数值推理通过的证据。

主机 profile 还应固定数值环境配置，包括 OMP_NUM_THREADS 和 MKL_NUM_THREADS；即使所有包版本一致，CPU 深度重建也可能随线程数改变。为不同 Python/Torch/CUDA/C++ ABI 使用独立的 TORCH_EXTENSIONS_DIR，并保证扩展编译器采用 Torch 的 C++ ABI；单独新建缓存无法纠正编译器的 ABI 默认值。DreamX 在调用者显式启用确定性算法时关闭 cuDNN 自动选算法，避免不同进程选择不同卷积算法。确定性策略变化后的参考结果须另存，附上与受控原实现的数值对齐证明；不能覆盖旧参考或放宽阈值掩盖差异。

短案例覆盖的是已声明输入和能力。Lyra-2 案例仍关闭 3D 重建；接受新 backend、更新集成状态或发布时，仍需要完整 demo 和质量 benchmark。

准备可选 CPU eval-core 测试环境

先从 PyTorch 官方 CPU wheel index 安装 Torch/Torchvision，再从正常 package index 安装已声明的测试 extra：

python -m pip install --index-url https://download.pytorch.org/whl/cpu \
  "torch>=2.7,<2.12.0" "torchvision>=0.22,<0.27.0"
python -m pip install -e ".[eval_core]"

拆成两条命令是有意为之：Python package metadata 不能指定 CPU 专用 wheel index；如果把整个 extra 都指向 PyTorch index，pytest、NumPy 等包反而可能不可见。

几何、视频和世界模型的数值回归

CPU 门禁和 mock 测试不能证明真实权重的推理结果保持正确。修改模型加载、预处理、推理、相机转换或导出代码时，使用 tests/manual/geometry_regression.py 在两个独立进程中复跑同一个已验收案例。tests/manual/geometry_regression_cases.json 提供 Depth Anything、Pi3/Pi3X、VGGT、CUT3R、LoGeR、LingBotMap、Hunyuan Mirror、HY-WorldMirror 2.0、FlashWorld 和 WorldFM 的固定案例。额外的 Lyra-2 案例只验证视频生成和相机轨迹，关闭了 3D 重建；模型环境和本地 assets 需要另行准备。

# 使用先前已验收的代码版本；不要在正在工作的目录中 reset。
git worktree add --detach /tmp/worldfoundry-3d-reference <validated-revision>
export WORLDFOUNDRY_REGRESSION_CHECKPOINT_ROOT=/absolute/path/to/checkpoints
export WORLDFOUNDRY_REGRESSION_INPUT_IMAGE=/absolute/path/to/accepted-image.png
# 多视角案例使用固定的 frame-0.png、frame-16.png、frame-32.png。
export WORLDFOUNDRY_REGRESSION_INPUT_ROOT=/absolute/path/to/accepted-sequence
# 先根据 nvidia-smi 将 REGRESSION_GPU_ID 设为可用 GPU 的编号或 UUID。
export CUDA_VISIBLE_DEVICES="${REGRESSION_GPU_ID}"

# 用同一个模型专用 Python 环境执行三条命令。
python tests/manual/geometry_regression.py run \
  --case tests/manual/geometry_regression_cases.json --case-id pi3x \
  --source-root /tmp/worldfoundry-3d-reference --output-dir tmp/3d-replay/reference/pi3x
python tests/manual/geometry_regression.py run \
  --case tests/manual/geometry_regression_cases.json --case-id pi3x \
  --source-root . --output-dir tmp/3d-replay/candidate/pi3x
python tests/manual/geometry_regression.py compare \
  --reference tmp/3d-replay/reference/pi3x --candidate tmp/3d-replay/candidate/pi3x \
  --report tmp/3d-replay/comparison.json

完成全部受影响案例后，用矩阵门禁检查覆盖率和证据是否仍匹配当前源码：

make test-geometry PYTHON=/path/to/model-env/bin/python \
  GEOMETRY_REFERENCE=tmp/3d-replay/reference \
  GEOMETRY_CANDIDATE=tmp/3d-replay/candidate

这个门禁要求根目录下存在每个矩阵 case id 的运行子目录。缺少任何案例、案例参数改变或实际导入的源码哈希改变都会失败。可用 GEOMETRY_MATRIX 指定本次影响范围的案例矩阵；共享推理组件改动时使用完整矩阵。它检查已经完成的真实推理证据，不代替前面的推理命令。

每次运行保存输入和权重的 SHA-256、案例参数和 seed、依赖版本、CUDA/精度设置、实际导入源码的哈希，以及原始数值输出。比较时要求输入、权重、参数和环境一致，并检查深度、点云、置信度、mask、相机参数的字段、shape、dtype、有限值和逐项数值。设置 save 的案例还比较保存后的 PLY 数值、图像和 NumPy 产物。缺少 assets、推理失败、空输出、NaN、丢失字段或被修改的证据都会失败，不能记为通过。参考目录不会被自动覆盖。

默认要求完全一致。案例可以设置 deterministic: true，要求 Torch 使用确定性算法，并在 CUDA 初始化前配置 cuBLAS；不支持确定性执行的算子会失败。Hunyuan Mirror 和 WorldFM 案例使用这一设置。WorldFM 还在模型加载后固定推理 seed，避免仅在加载前设置 seed 时受到模型初始化影响。其全景输入使用 WORLDFOUNDRY_REGRESSION_PANORAMA，Lyra-2 使用 WORLDFOUNDRY_REGRESSION_LYRA_INPUT_IMAGE。

存在 GPU 非确定性时，先在参考版本上重复运行，测量同版本的数值波动，再为浮点输出选择有依据的 --atol / --rtol；布尔 mask 和整数输出仍要求完全一致。矩阵门禁始终严格比较，不会继承单独 comparison 报告的容差。不要通过扩大容差或用失败产物更新 reference 来消除失败。

新增模型案例使用 target（module:Class）、load、call、assets 和 required_outputs。${OUTPUT_DIR} 指向本次运行目录；其他路径使用环境变量。extra_calls 可以补充原始深度，capture_modules 可以捕获只返回产物路径的模型的原始 forward 输出。生成式模型还应固定 prompt、轨迹、采样步数和精度，并对渲染结果做质量验收。

已验证状态只适用于具体代码、权重、输入和运行环境。共享组件改变后，复跑所有受影响的模型及 variant；没有复跑的模型保留为未覆盖。GitHub CI 运行公开 CPU 门禁；真实推理需要在有本地权重的 GPU 主机上单独运行，并在接受推理改动前通过 make test-geometry。数值一致证明已验收案例没有发生回归，不能证明任意输入都没有 bug，也不能替代带真实深度和相机标定的质量 benchmark。先用官方结果、质量指标和人工检查验收 reference，再将它作为回归基线。

发布门禁

轻量 editable checkout 在运行 core 门禁前，先安装声明的测试依赖：

python -m pip install -e ".[dev,test]"

make test
make lint
make compile-eval
make cli-entrypoint-check
make cli-check
conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval evaluate --results-path tmp/results.jsonl --output-dir tmp/worldfoundry_evaluate --json
conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval zoo benchmarks --json

cd docs/fumadocs
npm run models:check
npm run types:check
npm run build
curl -I http://localhost:8013/docs
curl -I http://localhost:8013/zh/docs

conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval zoo model-show --model-id <model-id> --include-manifest --json
conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval zoo model-download --model-id <model-id> --check-local --json

conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval zoo benchmark-show --benchmark-id <benchmark-id> --include-spec --json
conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval zoo benchmarks --json
conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval preflight runtime --profile <benchmark-id> --manifest worldfoundry/data/benchmarks/runtime_profiles/official/<benchmark-id>.yaml --output-dir tmp/preflight/runtime/<benchmark-id> --json
conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval zoo benchmark-run --benchmark-id <benchmark-id> --mode official-validation --official-results-path <official_results.json> --generated-artifact-dir <generated_artifacts> --output-dir tmp/benchmark_zoo/official_validation/<benchmark-id> --json

产物验收

• run_manifest.json — 任意 evaluation run。通过标准：Command、ids、status、timestamps、counts 和 output paths 与 run 一致。
• execution_plan.json — Runner 或 suite 变化。通过标准：Resolved model、benchmark、metrics 和 requests 是确定性的。
• sample_ledger.jsonl — 部分失败 review。通过标准：Failed/skipped samples 有可见原因。
• metrics/summary.json — Metric 变化。通过标准：Aggregates、failed counts 和 metric keys 符合预期 schema。
• scorecard.json — 可发布 evaluation evidence。通过标准：Eligibility、leaderboard state、metrics 和 blockers 存在。
• report.json — Model/benchmark validation。通过标准：Stage status、command、repo/checkpoint/dataset refs 和 blockers 已记录。
• suite_report.json — Suite 或 matrix 变化。通过标准：每个选中 cell 都是 pass、fail 或 skipped，并带原因。

集成声明规则

integrated 只用于可 review 的已实现 support surface，不能只靠 source URL 或 plan 声明。对模型 runtime，模型架构或 runtime glue、启动路径、环境契约、checkpoint/input/output contract，以及最小真实推理证据，都必须能从仓库和声明资产中 review。对 benchmark，仓内 runner、official command、隔离 importer 或 official-result normalizer 只要 CLI 路径、artifact/data requirements 和 scorecard 输出都有证据，就可以是 integrated。

不要把 integrated 当成 leaderboard 同义词。Normalizer-only benchmark integration 必须保持 verification_status=normalizer_only 和 leaderboard_valid=false，直到完整 official scorer 或 judge 已运行，且具体 scorecard 证明 eligibility。

Runner 证据

失败策略

• Pass — 必需阶段已运行，并产出预期产物。发布处理：可以支撑对应 claim。
• Partial — 有阶段因为 network、credentials、data、GPU 或 license review 被跳过。发布处理：可用于开发，不能支撑更强公开 claim。
• Blocked — 必需 source、dataset、license、dependency、checkpoint 或 API 条件不可用。发布处理：Manifest 保持 blocked 或 planned。
• Stale — Report hash、manifest hash、git commit、validator script 或 timestamp 不再匹配。发布处理：重新运行验证后才能计入。
• Runner-only — Schema 和 runner path 通过，但 official runtime 未运行。发布处理：不是 leaderboard evidence。

Validation matrix

Matrix 是 model-zoo 和 benchmark-zoo readiness 的 release gate。它会合并 manifest entries 和 staged validation reports，并重新计算 integration status。

conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval run \
  --all-benchmarks \
    --plan-only \
  --output-dir tmp/worldfoundry_plan_matrix \
  --json

conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval validate-artifact \
  tmp/worldfoundry_plan_matrix/suite_manifest.json \
  --kind suite-manifest \
  --strict \
  --json

• accepted_integrated — Fresh report 通过所有必需阶段，manifest 也声明 integrated。Maintainer action: 保持证据 fresh。
• accepted_variant_integrated — 一个或多个 scoped variants 通过，但 parent family 仍是 planned。Maintainer action: 继续验证剩余 variants。
• validated_but_manifest_not_promoted — Report 通过，但 manifest 仍是 planned 或 blocked。Maintainer action: Artifact review 后再提升。
• manifest_integrated_without_report — Manifest 声称 integrated，但没有 fresh validation report。Maintainer action: 运行 staged validation 或降级。
• manifest_overclaims_integration — Manifest 声称 integrated，但 computed stages 不通过。Maintainer action: 降级或重新运行 full validation。
• report_overclaims_integration — Report 声称 integrated，但 staged evidence 不完整。Maintainer action: 丢弃或重跑 report。
• stale_report — Report hash、script、git commit、schema 或 manifest entry 改变。Maintainer action: 重新运行验证。
• partial_or_blocked — Report 存在，但 stages 失败或被跳过。Maintainer action: 按 next_action 处理。
• not_validated — Manifest entry 没有 report。Maintainer action: 运行对应 runtime preflight 和 official validation run。

清单