贡献规则

PR 前检查

提交 PR 前，请确认：

• 范围 — 一次只改一个 pipeline、benchmark path、runner layer 或文档区域。
• Runtime — 写清目标环境：runtime profile、hosted API、checkpoint-backed local run，以及任何 official repo provenance。
• 资产 — 不提交 checkpoint、生成视频、本地 cache、凭据或大型下载数据集。生成资产和 benchmark 数据要明确、可复现，并放在 git 之外。
• 证据 — PR 描述中包含命令、输出路径、跳过阶段和 blocker。

代码要求

• Python — 模型或 benchmark 有重依赖时保持 lazy import。
• 公开入口 — 用户可见 runtime class 放在 worldfoundry/pipelines/；评测适配器放在 worldfoundry/evaluation/。
• Model runtimes — worldfoundry/synthesis/** 下的 runtime integration 必须仓内实现。不要依赖机器本地的外部 checkout；外部仓库/checkpoint 在移植或 vendor review 前只能记录为 provenance 或 acquisition metadata。
• Vendored code — 已 review 的 thirdparty/ 代码按隔离代码处理。许可名称和上游 URL 记录在第三方许可与来源所链接的仓库声明与来源文件中，不要在源码旁再放 LICENSE、COPYING、NOTICE、UPSTREAM.md 或 README.md。大型、独立版本的上游优先用 git submodule；只有需要重度打补丁时才仓内拷贝。不要再复制已经在 worldfoundry/base_models/ 或 worldfoundry/synthesis/ 里的代码。当前树：FlashAttention 是外部安装（scripts/setup/install_flash_attn.sh）；diff-gaussian-rasterization/ 是带深度的规范高斯光栅器；simple-knn/ 是 CUDA KNN 扩展；fastvideo-kernel/ 是可选的 STA / VSA / VMoBA / TurboDiffusion kernel 树（CUDA_HOME + ./build.sh；ThunderKittens 只在非 aarch64 的 Hopper sm_90a；FP4 attention 只在 Blackwell sm_120a 且 CUDA ≥ 12.8）。
• Synthesis — 保持 worldfoundry/synthesis/** 仅用于推理：runtime wrapper、推理所需模型代码、checkpoint/path helper 和最小 runtime config。不要添加 training launcher、dataset builder、demo 媒体、notebook 或生成输出。本地 demo 资产放在已被 Git 忽略的 testcase/ 目录。
• Formatting — 避免无关大规模格式化；除非任务需要，不重写生成文件或 vendored 文件。
• Naming — 优先使用 canonical id 和直接 runner path；公开名称变化时，写 migration 说明，而不是长期保留 compatibility map。

验证方式

按变更类型选择验证证据：

• Runner、scorecard、tasks、registry — 使用公开 CLI 的 discovery、plan 和 artifact validation 命令。
• 单 pipeline run — 使用最小的文档化验证脚本及其生成 manifest。
• Stateful / interactive pipeline — 使用文档化 stream 命令，并提供有界 runtime 证据。
• Benchmark runner — Runner execution；需要 normalizer review 时，用 official-shaped result files 跑 zoo benchmark-run --mode official-validation。
• Model runner — Resolver/manifest validation，并为缺 checkpoint/credentials 提供 skipped path。

文档要求

Fumadocs 是唯一维护的文档面。新增或修改页面时，在 docs/fumadocs/content/docs 下维护英文和中文成对页面。本仓库只允许根目录那一份 README.md。不要在源码、vendor 树、fixture 或模型网络旁再加 README.md、readme.md 或 README_*。

行为变更时，更新对应 owning page：

• 新模型或 runtime profile — guides/supported-models、对应的 guides/supported-models/<model-id>.mdx（及 .zh.mdx）、reference/environments，行为变化时更新模型指南。先用 npm --prefix docs/fumadocs run models:generate 刷新已检入的 homepage recipes 和生成的模型页，再用 npm --prefix docs/fumadocs run models:check 验证。手写模型文请先把 frontmatter 的 pageSource 设为 authored，以免再次 generate 时被覆盖。论文标题与配图用 npm --prefix docs/fumadocs run models:media 在 generate 之后刷新。
• 新 benchmark — evaluation/benchmark-hub/<benchmark-id>、benchmark 指南；内部实现变化时同步维护者架构页。
• CLI 或输出 schema — reference/cli，以及拥有相关行为的 architecture 页面。
• 内部 workflow — maintainers/architecture（尤其是 workflow 与 evaluation-core）。

基于 Python 的文档 codegen 与漂移检查（api:*、models:*、coverage:* 和 cli:screenshots）统一经 docs/fumadocs/scripts/run-python.sh 调用解释器。需要覆盖时， 解析顺序为 WF_DOCS_PYTHON、PYTHON、python3、python。

快速站点迭代

模型演示视频由 GitHub CDN 提供，文档开发不需要执行 git lfs pull。

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/OpenEnvision/WorldFoundry.git

WorldFoundry 目前只维护 一个 Web 站点：docs/fumadocs/ 下的 Fumadocs 文档应用。Homepage、benchmark hub、模型目录和 API 参考都是该应用内的路由，不是独立构建目标。Studio（worldfoundry/studio/）是 Python FastAPI 应用，不属于 Next.js 站点。

每个站点都应在仓库内保留 快速迭代 的 npm 脚本。生产 CI 路径不变（scripts/docs/build.sh → deploy-docs.yml）。

在仓库根目录也可使用 make docs-dev-fast、make docs-dev-ssd、make docs-dev-local 或 make docs-build-fast。

文档站点包含数百个中英双语模型与 benchmark 页面，以及体积较大的生成 JSON 目录。在共享文件系统上，每次 npm run dev 都可能重跑 MDX codegen 并冷启动 webpack 缓存，体感较慢。

共享存储上最快的 dev（推荐）：

cd docs/fumadocs
npm run dev:ssd
# 或从仓库根目录：make docs-dev-ssd

dev:ssd 将热点路径符号链接到本地 SSD（默认 ~/.cache/worldfoundry-docs/<checkout-id>）：tmp/（Next.js + webpack）、.source/（MDX codegen）、node_modules/.cache。源码仍留在共享 checkout，每次启动不做全量 rsync。首次运行会迁移已有 .source/ 产物；Next.js 与 webpack 缓存会在 SSD 上重建。

日常 UI/CSS 打磨（已在本地快盘时）：

cd docs/fumadocs
npm run dev:fast

dev:fast 直接复用已有 .source/，不检查内容是否更新，并在 generated/python-api.json 存在时复用它。新增页面或修改导航、frontmatter 后需要重新生成 MDX。开发缓存默认放在 tmp/；共享存储上优先用 dev:ssd 将缓存放到本地 SSD。

若 node_modules 读写也慢，可将整个站点镜像到本地 SSD：

cd docs/fumadocs
npm run dev:local

dev:local 会刷新 /tmp/wf-docs-dev/<checkout-id>/WorldFoundry 下当前 checkout 专用镜像的源码，并复用已安装依赖。可通过 WF_DOCS_LOCAL_ROOT 指定其他镜像根目录。

本地快速验证静态导出（不跑 CI 漂移检查）：

cd docs/fumadocs
npm run build:fast

常用环境变量（WF_DOCS_*）：

SSD 缓存辅助命令：npm run ssd:setup、npm run ssd:status、npm run ssd:clean（加 -- --purge 可删除 SSD 上的缓存数据）。

修改模型 manifest 后，先运行一次 npm run models:generate，再执行 WF_DOCS_REFRESH_MDX=1 npm run dev（或在停掉 dev server 后运行 npm run mdx:generate）。开发中编辑已有 MDX 页面可直接热更新，无需重新生成 .source/；新增页面或修改 meta.json 时需设置 WF_DOCS_REFRESH_MDX=1。

npm run dev:turbo 尝试使用 Turbopack 替代 webpack，目前视为实验性；生产 GitHub Pages 仍走 npm run build（webpack + 静态导出）。

新增站点

在 docs/<name>/ 下新增 Next.js 或静态站点时：

1. 添加 dev:fast、dev:local（可选 SSD 镜像脚本）和 build:fast npm 脚本。
2. 跳过/刷新类环境变量使用 WF_<SITE>_ 前缀（例如 WF_STUDIO_SKIP_MDX=1）。
3. 提供 predev.mjs（或等价逻辑），在输出已是最新时智能跳过 codegen。
4. 若需从仓库根目录常用，添加对应的 make docs-<site>-dev-fast 目标。
5. 在本节站点目录（中英文页面）中补充一条。

生产部署速度是另一回事：CI 仍会跑完整的 types:check、目录漂移检查和全页静态导出，该路径未改动。

本地验证

bash scripts/setup/conda_install.sh --preset slim --env-name worldfoundry
make lint
make docs-check
cd docs/fumadocs && npm run types:check && npm run build

公开版本的 CPU 检查无需模型权重：

python -m pip install -e ".[dev,test]"
make test-infer
make cli-check cli-entrypoint-check packaging-check

模型/profile audit：

worldfoundry-eval run --all-benchmarks --plan-only \
  --output-dir tmp/worldfoundry_plan_matrix \
  --json
worldfoundry-eval validate-artifact tmp/worldfoundry_plan_matrix/suite_manifest.json \
  --kind suite-manifest \
  --strict \
  --json

分阶段 zoo 验证：

conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval zoo models --json
conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval zoo benchmarks --json
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

PR 证据模板

## Scope
- Changed:
- Not changed:

## Evidence
- Command:
- Output:
- Scorecard/report:
- Skipped stages:
- Blockers:

## Docs
- English page:
- Chinese page:

测试源码统一放在公开的 tests/；模型权重、测试媒体和生成的回放记录留在 git 之外。推理变更需回放受影响的真实权重案例，并针对已接受的基准通过 make test-geometry。数值比较及源码哈希检查见验证指南。