# Blender Bench v0.4 · Wave 1 脚本

对应任务书：<https://www.cl.cam.ac.uk/~fy277/blender_bench/task/>。这里覆盖 Wave 1 中除 MOD-01（已测完）以外的全部题目：

TOP-01、MOD-02、MOD-04B、UV-01、BAKE-01、RIG-01、MOD-03、DIAG-01、JUDGE-01。

每道题都有三类脚本：

- **出题**（prepare）：从素材生成给 agent 的 `cases/<id>/`，以及不给 agent 的 `private/<id>/`；
- **基线**（B0 / B1 / B0′）；
- **评测器**（evaluate / score）。

另外有一个运行器，它在 `production_v1/bench.py` 的基础上改写，Codex 调用方式完全不变。

所有脚本于 2026-11-02 在 Linux 上用 Blender 4.3.2 实测过，测试数据是 Human Base Meshes、tool pack 1 的扳手和脚本自建的素材，结果见第 5 节。Mac 上没有实际跑过，第一次使用请先跑 `tests/selftest.sh`，约 1.5 分钟。

---

## 1. 目录

```text
code/
├── README.md
├── config.example.json         复制为 config.json：Blender 路径、codex、模型、推理强度
├── bb/                         共享库（在 Blender 内运行）
│   ├── common.py               参数、IO、求值网格、烘焙对象、写干净 .blend
│   ├── topo.py                 拓扑统计、边界环、边环行走（严格 / 容忍极点）、关节环
│   ├── face.py                 地标自动定位、眼 / 口语义环、可见极点
│   ├── headeval.py             TOP-01 / MOD-03 共用的头部 goal 与 probe 检查
│   ├── deform.py               固定探针：闭眼、张嘴、微笑、肢体弯曲
│   ├── geom.py                 采样、双向距离、轮廓 IoU、自交、离散平均曲率与异常簇
│   ├── uvm.py                  UV 岛、缝、失真、密度、利用率、间距、缝可见度、logo 探针
│   ├── bake.py                 无渲染器的烘焙明暗误差（切线空间解码）、Cycles 烘焙
│   ├── rig.py                  22 个身体角色位、解剖姿态、评测端自做 LBS、权重卫生
│   ├── identity.py             对象身份签名（改稿题）
│   ├── degrade.py              去参数化（细分 → 三角化 → Decimate → 抖动 → 打乱）
│   ├── render.py               相机、线框叠加、斑马纹材质、高亮环
│   ├── grade.py                gate → goal → probe 分层评分记录
│   └── case.py                 case 目录、prompt 模板、B2 校准工具
├── tasks/<TASK>/               prepare.py、evaluate.py（或 score.py）、baseline_*.py、prompt*.md、feedback*.md
├── harness/
│   ├── bench_v04.py            运行器：freeze / start / branch / status / stop / resume / grade
│   ├── baselines.py            捷径审计：B2 校准 + 生成并评测全部基线
│   ├── collect_results.py      汇总为 results.csv 和 results.md
│   ├── prepare_wave1.sh        Wave 1 全部出题命令（带 TODO 的需要先填对象名）
│   ├── suite_wave1.json        case 列表和四个根目录
│   └── templates/self_prompt.md  V1-S 自主检查的统一文本
├── tools/
│   ├── inspect_blend.py        Phase 0 入场检查：逐对象统计面数、四边比例、UV、骨架、形态键、修改器、缺图
│   ├── landmarks.py            地标：猜测 → GUI 里拖动 → 导出 JSON；预览渲染
│   └── step_split.py           STEP 按实体拆成 STL（在 CadQuery venv 里运行）
└── tests/
    ├── selftest.sh             复现本页第 5 节的验证
    └── make_synthetic_mouse.py 仅供测试的合成 SubD 外壳
```

## 2. 一次完整流程

所有 Blender 脚本都按 `blender -b --factory-startup --python <脚本> -- <参数>` 运行。

1. **配置**：`cp code/config.example.json code/config.json`，然后修改 `harness/suite_wave1.json` 里的四个根目录。
   - **`private_root` 必须放在 Codex 所用账号读不到的位置**，比如另一个 macOS 用户的目录，或另一块盘。
2. **入场检查**：对每件要用的素材运行 `tools/inspect_blend.py --file X.blend --out intake/X.json`，从输出中确认对象名、UV、骨架和修改器。
3. **出题**：运行 `bash code/harness/prepare_wave1.sh`。
   - 已能直接运行的：TOP-01 dev/test1、MOD-03 dev/test2、MOD-04B test2（自建外壳）、BAKE-01 dev/test1、RIG-01 hb。
   - 其余标了 TODO，要先填对象名、角色映射和 edits.json。
4. **捷径审计**：运行 `python3 code/harness/baselines.py --suite code/harness/suite_wave1.json`。它会：
   - 先在 B2 上运行 `--calibrate`，把探针限值存入 `private/<id>/calibration.json`；
   - 生成并评测全部基线；
   - 写出 `baselines/<id>/audit_summary.json`。
   **只有 `freeze_ok: true`（B2 通过、所有基线失败）的 case 才能进入 test。**
5. **冻结**：`python3 code/harness/bench_v04.py freeze --suite ...`，记录输入哈希。之后输入一旦变动，`start` 会拒绝运行。
6. **跑 V0**：`python3 code/harness/bench_v04.py start --suite ... --phases V0 [--cases TOP-01__dev] [--repeat 2]`。
   - worker 在后台串行运行；每个阶段结束后自动评测（`grade.json`、`evidence/`），并审计是否调用了 B0 工具（`audit.json`）。
7. **看 V0、写反馈**：编辑 `cases/<id>/feedback.md`，把模板里的选项和数字替换成最终反馈，并先确认 V0 还没有满足它。
   - 模板没改时，V1-F 会停在 `needs_feedback` 状态，不会发出去。
8. **跑 V1**：`python3 code/harness/bench_v04.py branch --run <run> --phases V1-F,V1-S`；补写反馈后用 `resume`。
9. **只读题**：
   - DIAG-01：先写 spec，再运行 `tasks/DIAG-01/inject.py`；
   - JUDGE-01：在对应生成题全部跑完后，用 `tasks/JUDGE-01/assemble.py` 组装候选（把模型的 V0 混进去）。
   - 两者都用 `score.py` 评分，普通 python3 即可。
10. **汇总**：`python3 code/harness/collect_results.py --suite ... --runs <run> --out results_v04`。

## 3. 每道题的脚本

| 题 | 出题（prepare） | 基线 | 评测：gate / goal / probe |
|---|---|---|---|
| TOP-01 | 美术头部 → 去参数化 20 万三角的 `Sculpt` + 眼球 + 公开地标；B2 = 原布线；面数预算 = 1.1 × B2；需要的环数和极点限值由 B2 校准 | B0a QuadriFlow（同预算）、B0b 体素 + Decimate | Sculpt / 眼球不变、预算、流形、单件 / 双向距离、眼口语义环、可见极点 / 闭眼、张嘴 15°、微笑（限值相对 B2） |
| MOD-03 | 美术头部（或全身切颈）→ 正、侧 2048 正交参考图 + 2D 地标；隐藏参考 = 细节曲面；B2 = 美术控制笼 | B1 球 + 椭球 + 布尔，B0′ 在隐藏参考上跑 QuadriFlow | 单一 `Head`、不得伪造细节 / 距离（头高的 1.5%）、在提交上检测地标的误差、语义环、极点 / 同 TOP-01 |
| MOD-02 | SubD 控制笼（或 CAD 曲面）→ 四视图（含折痕强调）+ dims.json + 斑马纹审查场景；隐藏参考 = 3 级细分或 CAD 曲面 | B1 椭球 + 布尔 + Bevel，B0′ QuadriFlow | Subdivision 实时、控制笼预算 / 距离（按 120 mm 缩放）、平底、顶面极点、曲率异常簇 / E1 后部隆起 +4 mm（≤ 2 条环）、E2 开孔前移 5 mm、E3 三级细分 |
| MOD-04B | 美术工程原样给出 + changes.md + **自动生成的 drawover**（改前渲染上用红线标出与目标的差异）；隐藏 target.blend + edits.json | B1 应用全部修改器后缩放 | 未授权对象完全不变、修改器栈实时且顺序不变 / edits.json 中的每项测量（修改器值、包围盒增量、凹陷深度、单侧性、与 target 的距离）/ 可选骨骼探针 |
| UV-01 | 美术头部 → 去掉 UV；Region_Face / Region_Neck 顶点组；6 个展示相机；COLOR_GRID 测试图 | B0 Smart UV，B0′ 无缝 Unwrap | 几何不变、UV_Main、UV 在 0–1 内 / 缝可见比例、脸正面无缝、脸为单岛、密度比、失真 P95、利用率、间距、无重叠 / 左颊 logo 探针 |
| BAKE-01 | 美术高低模配对 → 输入只给 `High`；B2 = 美术低模 + **评测端用 cage 重新烘焙的贴图**；三角面预算 = 1.1 × B2；纹素密度取 B2 实测 | B0 Decimate + Smart UV + 无 cage 烘焙 | 预算、贴图、glb / 12 向轮廓 IoU、sharp 边 ⊂ UV 缝、密度、padding、明暗误差（6 视角 × 8 光，含“法线贴图必须改善明暗”）、AO / glTF-Validator（需要 CLI）+ 重新导入 |
| RIG-01 | 角色网格（去掉骨架、组、驱动器）+ 22 个角色位 + 8 个姿态；B2 = 原骨架 + 原权重（需要角色映射 JSON） | B0 Rigify metarig 按包围盒缩放 + 自动权重，B1 按身体切片放关节 + 自动权重 | 几何不变、单一骨架、bone_map 完整 / 关节误差（≤ 2% 身高）、未蒙皮、≤ 4 影响、归一化、杂散权重 / 8 个姿态由评测端自做 LBS（半径比、腋下与腹股沟拉伸、翻转、自交、布料与身体穿插） |
| DIAG-01 | 按 spec 向工程注入缺陷（10 类）并记录真值；混入干净文件；文件名匿名 | — | 召回率、精确率、定位 IoU、干净文件上的误报 |
| JUDGE-01 | 同一形状的 4 个候选匿名后随机排序（B2 / B0 / B1 / 模型 V0） | — | Kendall τ（真值来自评测器结果）、探针预测准确率、自我偏好 |

## 4. 实测中发现的问题，以及对任务书的修订

1. **TOP-01 手臂变体没有通过捷径审计**：
   - QuadriFlow（B0a）在 Human Base 手臂上全部通过，包括肘部环和弯曲探针。原因是管状形体天然产生环向布线。
   - 按 v0.4 P1，这个变体降为对照，或者需要重新设计。代码保留（`--kind arm`），但 TOP-01 的实例改用头部。
2. **Human Base 头部是闭合网格**：
   - 眼睑翻进眼窝、嘴唇翻进口腔袋，没有“边界孔”。
   - 因此语义环的定义改为：从眼开口或唇线开始的、可见的嵌套闭合边环；一次环选可以穿过不超过 2 个极点（美术常把极点放在外眼角）。
   - 该定义在 3 个 B2 头部上校准过，题面也同步改为“开孔或眼窝都可以”。
3. **B2 不一定达到 v0.4 的固定阈值**（例如写实动画头的右眼只有 2 条完整环）。
   - 因此每个实例的环数要求 = min(3, B2 实测值)，并写进该实例的 prompt；
   - 极点限值 = B2 + 2；
   - 探针限值相对 B2（`calibration.json`）。这就是 v0.4 P9 的落实方式。
4. **UV-01：Human Base 的 UV 在脸部中线切开，不满足本题合同，不能作为 B2。** UV-01 的 B2 要用生产角色（Q-UBC / ST-*），并先跑 B2 评测确认能通过。
5. **BAKE-01：美术自带的法线贴图包含 `High` 里没有的细节**（刻字、点蚀），用它对比 `High` 反而更差。
   - 因此 B2 改为“美术低模 + 用 cage 重新烘焙的贴图”，美术原图另存为 `artist_normal.png` 备查。
   - 美术低模的轮廓 IoU 只有 0.93，sharp 边有 2 条不在缝上，这两项限值跟随 B2。
6. **QuadriFlow 拒绝真实尺度的小网格**：头部只有几毫米的边会被它判为“非流形”。基线脚本先放大 100 倍再缩回。模型在跑题时很可能踩到同样的坑，值得在轨迹里观察。
7. **MOD-02 只在合成外壳上验证过**，m510、Ploopy 和 Moudabella 需要在 Mac 上实际出题和校准。glTF-Validator 在本机没有安装，因此 BAKE-01 的验证器检查在这里显示为“跳过”。
8. **RIG-01 没有带骨架的 B2 可以测**（Human Base 没有骨架），只验证了 B0 / B1 和整条评测流程。ST 角色需要写角色映射，模板见 `tasks/RIG-01/role_map_rigify_template.json`；Blender Studio 的骨骼名可能不同，以 `inspect_blend` 的输出为准。

## 5. 本机验证结果（Linux，Blender 4.3.2，2026-11-02）

| case | B2 | 基线 | 捷径审计 |
|---|---|---|---|
| TOP-01 头（GEO-head_stylized） | 全部通过（10/10、7/7、4/4） | B0a gate 失败（分成两件，没有眼环和口环）；B0b goal 失败（距离、环） | ✅ |
| TOP-01 臂（stylized 男体） | 全部通过 | **B0a 全部通过**；B0b 失败 | ❌ 降级 |
| MOD-03（stylized 女体切颈） | 全部通过 | B1 goal 失败（距离 18% 头高、没有环）；B0′ gate 失败（分成两件），距离通过但没有环 | ✅ |
| MOD-02（合成外壳） | 全部通过 | B1 失败（距离 16.6 mm、曲率异常、E1/E2）；B0′ 失败（距离、开孔丢失） | ✅（仅合成数据） |
| MOD-04B（自建外壳） | 全部通过 | B1 gate 失败（修改器栈）；什么都不改则 goal 全部失败 | ✅ |
| UV-01（HB 头） | **失败**（HB UV 不合合同） | B0 / B0′ 失败 | ⚠️ 需要换 B2 素材 |
| BAKE-01（扳手） | 全部通过（校准后） | B0 失败（明暗 P95 0.77、padding 0.6 px、密度） | ✅ |
| RIG-01（HB 男体，无 B2） | — | B0 失败（关节错位导致塌缩）；B1 goal 失败（> 4 影响、杂散权重），姿态 1/8 通过 | 待 B2 |
| DIAG-01（5 个文件、8 处缺陷） | — | 假报告：召回 0.5、精确 0.8、干净文件误报 1，与构造一致 | ✅ |
| JUDGE-01（TOP-01 三个候选） | — | 真值排序 B2 > B0b > B0a；假判断 τ = 1.0 | ✅ |
| 运行器 | 用假 Codex 跑通了 V0 → 评测 → needs_feedback → 写反馈 → resume → V1-F | | ✅ |

## 6. 注意事项

- **隔离**：运行器只把 `cases/<id>/input` 复制进工作目录，并在 prompt 里禁止读外部文件。但这仍然只是提示级隔离，`private_root` 请放在 agent 账号无权读取的位置。
- **评测器只在副本上操作**，不修改提交文件；证据图写在 `grade.json` 旁的 `evidence/`。
- 所有阈值都是初值，冻结前必须先过 `baselines.py`；B2 没通过时，先查素材，再决定是否调阈值，不要为了让 B2 通过而改题意。
- 许可：Tripo 结果仅限 share-only，原始 glb 不要再分发；Blender Studio 角色是 CC-BY，作者页未核实；Prusa 零件是 GPL，Ploopy 是 CERN-OHL。
