Blender 建模技能 — 完整操作规范（AGENTS.md）

本文件是 blender-modeling 技能的唯一权威完整规范。SKILL.md 只是入口；动手前必须整篇读完，再按阶段 0 → 阶段 9 执行。 环境：Windows + Blender 4.0.2（C:\Program Files\Blender Foundation\Blender 4.0\blender.exe）+ 系统 Python 3.12；本文命令均在本机实测过；kit 函数以 lib/blender_kit.py 的公开 API（__all__ 与 docstring）为准。

0. 这是什么 / 交付物定义

0.1 技能做什么

把用户的一句自然语言提示词，变成真实、可交付、可复现的 3D 模型：几何 + 材质 + 灯光相机 + 多角度渲染图 + .blend / .glb 导出。全部由本机 Blender 以 headless bpy 脚本完成，不依赖图形界面手工操作。

一句话边界：模型必须由 <输出目录>/model.py 这个脚本生成。手改 .blend、只在日志里"看起来对"、没有渲染图，都不算交付。

技能有两种模式：模式 A（默认）从零新建，走阶段 0 → 9；模式 B 修改已有模型，用 templates/edit_model_template.py 打开现成 .blend 改完再渲染导出，见第 10.5 节（其余闸门与交付要求相同）。

0.2 交付物（缺一即未完成）

0.3 七条铁律（违反任一条 = 任务失败）

1. 先读规范再动手：执行阶段 0 前读完本文件；不得跳阶段。
2. 脚本是唯一真源：所有几何/材质/灯光/相机都写在 model.py 里；删掉输出目录后重跑同一条命令必须得到同样的模型。
3. 必须真看图：每轮渲染后用 read_image 打开 renders/view-*.png 逐张检查；禁止只看日志或 BM_RESULT 就宣称模型没问题。
4. 必须过闸门：scripts/doctor.py 0 ERROR、scripts/check_output.py 0 ERROR（含视觉指标闸门与迭代记录校验）、第 14 节看图自检清单全 PASS，才允许向用户交付。
5. 禁止硬编码绝对路径：model.py 中出现 <技能目录>/<工作区> 字面量或写死 Blender 安装路径，一律打回。用 os.environ["BLENDER_KIT_DIR"] / BLENDER_OUT_DIR。
6. 禁止把产物写进 <技能目录>：<技能目录> 只读；产物只写到 <工作区>/blender-models/<slug>/。
7. SAFE_MODE 边界：model.py 不得使用 subprocess / os.system / eval / exec / 网络库 / __import__ / shutil.copyfile|copy|copytree；写文件只允许 renders/ exports/ 等白名单目录或单段 report.json / brief.md，不得用绝对路径、盘符相对路径（如 C:evil.txt）、.. 或无法静态确定的变量路径（含 Path.open / write_text，SAFE003/004/006 均为 ERROR）；交付前 python scripts/safe_check.py 必须 0 ERROR（仓库 ci_check.py 也会审 templates/ 与 examples/*/model.py）。

1. 路径约定

1.1 三个路径（先想清楚再动手）

slug 规则：全小写 ASCII 连字符，<风格>-<题材>，如 lowpoly-coffee-mug、stylized-robot、lowpoly-cabin；同题材改版用 <slug>-v2；不要用中文、空格、下划线。同一 slug 重跑 = 覆盖该输出目录。

1.2 输出目录固定结构

<输出目录>/
├── brief.md                 # 阶段 1/2 产出：需求理解 + 假设 + 尺寸 + 部件表 + 迭代记录
├── model.py                 # 唯一建模脚本（PARAMS 集中）
├── renders/                 # view-front.png / view-right.png / view-iso.png / final-*.png
├── exports/                 # model.blend + model.glb（必需）；model.stl/fbx/obj 按需
├── logs/                    # run_blender.py 写出的 <label>-<时间戳>.log
├── history/                 # （可选）snapshot.py 的迭代快照 v1/v2/...
├── best.json                # （可选）snapshot.py 维护的最佳版本基线
└── report.json              # kit 生成的场景 + 渲染 + vision 视觉统计 + 导出记录

1.3 路径写法铁律

• 文档/命令里的脚本路径一律写成 scripts/xxx.py（相对 <技能目录>）；不在该目录时把前缀换成 <技能目录>\scripts\xxx.py。给路径加引号（本机工作区路径含空格：F:\DeepSeek Harness）。
• model.py 内只用环境变量推导路径，标准写法（与 lib/blender_kit.py 的环境变量约定一致）：

import os
import sys

SKILL_DIR = os.environ.get("BLENDER_SKILL_DIR", "")
KIT_DIR = os.environ.get("BLENDER_KIT_DIR", os.path.join(SKILL_DIR, "lib"))
if KIT_DIR and KIT_DIR not in sys.path:
    sys.path.insert(0, KIT_DIR)

OUT_DIR = os.environ.get("BLENDER_OUT_DIR", os.path.join(os.getcwd(), "blender-models", "mymodel"))
RENDERS_DIR = os.path.join(OUT_DIR, "renders")
EXPORTS_DIR = os.path.join(OUT_DIR, "exports")

2. 流程总览（阶段 0 → 阶段 9）

flowchart TD
    A["阶段 0 环境体检<br/>doctor.py 0 ERROR"] --> B["阶段 1 提示词解析<br/>brief.md + slug"]
    B --> C["阶段 2 结构拆解<br/>四层 + 部件表"]
    C --> D["阶段 3 写 model.py<br/>复制模板 + PARAMS"]
    D --> E["阶段 4 build 自检<br/>run_blender --stage build"]
    E -- "errors 非空" --> D
    E -- "ok:true" --> F["阶段 5 预览渲染<br/>--stage render + read_image"]
    F --> G["看图自检<br/>第 14 节清单"]
    G -- "有问题且轮次 < 4" --> H["阶段 6 迭代<br/>每轮只改 1-2 类"] --> F
    G -- "清单全 PASS" --> I["阶段 7 终渲与导出<br/>--stage full"]
    I --> J["阶段 8 check_output 闸门<br/>0 ERROR"]
    J -- "ERROR" --> D
    J -- "0 ERROR" --> K["阶段 9 交付<br/>文件清单 + 怎么看 + 怎么改"]

每阶段的产物与通过条件见第 3-12 节各阶段末尾的验收条件，汇总见第 17 节闸门表；不满足条件不得进入下一阶段。

模式 B（改已有模型）：不是从阶段 1 开始，而是阶段 0 体检 → 直接跳到第 10.5 节，用 templates/edit_model_template.py 打开已有 .blend 改完，再走第 11 节交付闸门与第 12 节交付说明。

3. 阶段 0：环境体检

目标：确认 Blender、Python、kit、模板可用、当前工作目录可写；环境不通过不许开工。

doctor 只验证**当前工作目录（cwd）**可写；真正的 <输出目录> 在阶段 1 建目录时验证。

# 在 <技能目录> 下执行；不在该目录时把 scripts/ 换成 <技能目录>\scripts\
cd "F:\DeepSeek Harness\blender-modeling"
python scripts/doctor.py
# 首次在新机器/新会话上再跑一次端到端冒烟（64x64 CYCLES 渲染）
python scripts/doctor.py --smoke
# 视觉探针：零依赖解码 examples/*/renders，证明渲染图真的可读、尺寸对、非空白（不需要 Blender/Pillow）
python scripts/doctor.py --vision

怎么读：逐项 [PASS] / [FAIL] / [WARN]，再读汇总行如 === 结果: 6 PASS / 0 ERROR / 1 WARN ===（汇总行之后还会打印一行「下一步」提示；有 ERROR 时末尾是逐条 ERROR: 明细）；存在 ERROR 时退出码 1。

验收条件

• 汇总行 0 ERROR，退出码 0；--smoke 模式下包含 64×64 CYCLES 端到端渲染 PASS（kit/模板缺失会在这里暴露）。
• 加 --vision 时，默认目标（examples/*/renders）与 --vision-out/--vision-dir 指定的目录全部 PASS——每张 PNG 可解码、像素尺寸与 report.json 声明一致、非空白（唯一色 ≥8 且亮度 std ≥2）。
• WARN 可以带过，但必须在 brief.md 的"环境"小节记录一条。

失败处理：Blender 找不到 → 设置 $env:BLENDER_EXE（或 run_blender.py --blender <路径>）；kit/模板缺失 → 检查 <技能目录>\lib\blender_kit.py、templates\model_template.py 是否存在；输出目录不可写 → 把 <工作区> 换到可写磁盘。doctor 的 ERROR 逐条修完后重新跑，不许带着 ERROR 开工。

4. 阶段 1：提示词解析与 brief.md

目标：把用户提示词（可能只有一句话）翻译成一份量化建模简报，落到 <输出目录>/brief.md。

4.1 提示词解析规则

1. 默认不追问。尺寸、颜色、风格、用途缺失时按 references/prompt-to-model.md 的默认值表自行决定，并写进 brief 的"假设与默认决策"。
2. 只有两种情况允许问 1 个问题（问完立即开工，不等第二个问题）：对象本身不明确（如"做个好看的"——不知道做什么物件）；需求自相矛盾（如"写实低多边形 100 万面"）。
3. 用户的每个风格词都要量化成参数：可爱 → 圆角/短粗比例/高饱和；科幻 → 硬表面/切角/发光条；写实 → 真实尺寸/高分段/粗糙度差异。量化表见 references/prompt-to-model.md。
4. 一句话里有多个物件时，取用户最强调的一个作主体，其余进"场景层"或明确告诉用户"本轮只做主体"。

4.2 建目录 + 写 brief.md

$OUT = "<工作区>\blender-models\<slug>"
New-Item -ItemType Directory -Force -Path $OUT, "$OUT\renders", "$OUT\exports", "$OUT\logs" | Out-Null

用 write 工具写 $OUT\brief.md（禁止 shell 重定向）。必填小节：## 需求原句、## 一句话目标、## 风格与量化参数、## 尺寸（米）、## 颜色与材质、## 结构四层、## 部件表、## 假设与默认决策、## 环境（doctor 的 WARN 记这里，0 WARN 写「0 WARN」）、## 验收标准、## 迭代记录。模板与示例见 references/prompt-to-model.md。

验收条件

• brief.md 存在，11 个小节齐全（迭代记录 可先空表）；尺寸表中每个数值都带单位 m，与最终 report.json 的 dimensions 三轴误差 ≤ 10%。
• 假设小节至少 1 条（默认不追问必然有假设）；slug 与输出目录名一致。

5. 阶段 2：结构拆解（四层 + 部件表）

目标：把"一个物件"拆成可建模的部件清单。先拆再写代码，不许边写边想。

5.1 四层拆解法

领域题材：建筑、人物、动物、植物四类有专门的领域技巧文档（references/architecture-modeling.md、references/character-modeling.md、references/animal-modeling.md、references/plant-modeling.md）。这类提示词先读对应文档的结构拆解模板与比例尺寸表，再按 5.1 四层法填 5.2 部件表；文档里的技巧库与配方骨架可直接复用。

5.2 部件表（追加进 brief.md）

固定 9 列，一行一个部件：

规则：每行必须能对应到 model.py 里一次 kit 调用（或一段 bmesh 构造），写不成图元的拆法不成立；主体先建模先渲染，细节层等阶段 4/5 通过后再加；层内编号连续，join 合并逻辑组时在"依赖"列注明。

验收条件：四个层都有结论（"无"也要写）；表格 9 列无空格；主体层每行尺寸与 brief 总尺寸自洽；部件总数 ≤ 15（低多边形默认）。

6. 阶段 3：写 model.py

目标：从模板复制出 <输出目录>/model.py，用 kit API 把部件表翻译成代码。

Copy-Item "<技能目录>\templates\model_template.py" "$OUT\model.py"

6.1 脚本骨架（照抄结构，替换 build 里的内容）

# -*- coding: utf-8 -*-
"""lowpoly-coffee-mug — 低多边形马克杯（由 templates/model_template.py 生成）。"""
import os
import sys

SKILL_DIR = os.environ.get("BLENDER_SKILL_DIR", "")
KIT_DIR = os.environ.get("BLENDER_KIT_DIR", os.path.join(SKILL_DIR, "lib"))
if KIT_DIR and KIT_DIR not in sys.path:
    sys.path.insert(0, KIT_DIR)

from blender_kit import (  # noqa: E402
    reset_scene, setup_scene, mat, assign, cylinder, torus,
    add_bevel, apply_modifiers, set_origin, join, render_views, export_all,
    save_report, stage, script_args,
)

OUT_DIR = os.environ["BLENDER_OUT_DIR"]
RENDERS_DIR = os.path.join(OUT_DIR, "renders")
EXPORTS_DIR = os.path.join(OUT_DIR, "exports")

PARAMS = {
    "mug": {"radius": 0.045, "height": 0.09, "wall_bevel": 0.002},
    "handle": {"major_radius": 0.030, "minor_radius": 0.006, "offset_x": 0.048},
    "colors": {"body": (0.92, 0.92, 0.90), "accent": (0.20, 0.45, 0.75)},
    "render": {"preview": (512, 16), "final": (960, 48)},
}

def build():
    reset_scene()
    setup_scene(target=(-0.02, 0, 0.045), distance=3.0, lens=50)
    # 说明：distance 只影响布光半径与地台尺寸；三视角取景由 render_views 按模型 bbox 自动完成
    white = mat("mug_white", color=PARAMS["colors"]["body"], roughness=0.35)
    p, h = PARAMS["mug"], PARAMS["handle"]
    body = cylinder("mug_body", radius=p["radius"], depth=p["height"],
                    vertices=24, location=(0, 0, p["height"] / 2), material=white)
    add_bevel(body, width=p["wall_bevel"], segments=2)
    body = apply_modifiers(body)  # join 前必须落地修改器，否则 join 只保留首对象修改器
    handle = torus("mug_handle", major_radius=h["major_radius"],
                   minor_radius=h["minor_radius"],
                   location=(h["offset_x"], 0, p["height"] * 0.55),
                   rotation=(90, 0, 0), material=white)
    mug = set_origin(join([body, handle], "mug"), "BOTTOM")
    assign(mug, white)
    return mug

def main():
    st = stage()
    build()
    w, s = PARAMS["render"]["preview"]
    if st in ("render", "full"):
        render_views(RENDERS_DIR, prefix="view", engine="CYCLES", samples=s, resolution=(w, w))
    if st == "full":
        w, s = PARAMS["render"]["final"]
        render_views(RENDERS_DIR, prefix="final", engine="CYCLES", samples=s, resolution=(w, w))
        export_all(EXPORTS_DIR, stem="model")
        save_report(OUT_DIR)

if __name__ == "__main__":
    main()

6.2 写代码的硬性要求

• 参数集中：所有尺寸、颜色、采样数、分辨率、位置偏移放 PARAMS；函数体内只引用 PARAMS，不出现魔法数字（0/1//2 等结构性常量除外）。
• stage 分支：stage() 返回 build / render / full。build 分支不渲染、不导出（要快，用于快速验错）；render 只渲染预览；full 终渲 + 导出 + 保存报告。注意 export_all() 内部已经写过一份 report.json，save_report() 再写一次是覆盖并补充 extra 字段——两者都调是无害的，不要误以为重复。
• 每个逻辑组 join 后 set_origin(group, "BOTTOM")，方便摆放与检查。
• join 前先 apply_modifiers：join() 只保留第一个对象的修改器；多件合并前必须把倒角/细分等落地（obj = apply_modifiers(obj)），否则除首件外修改器静默丢失——0.002 级倒角在预览里几乎看不出来，很难事后发现。
• 只用 lib/blender_kit.py 的公开函数：几何 cube/cylinder/sphere/cone/torus/plane/tube/text、变换/修改器、材质、渲染、导出/报告。kit 缺的能力用 bpy/bmesh 裸写（见第 15 节），但不要绕开 reset_scene / stage() / 输出路径约定。
• 透传参数用 script_args() 读，例如 python scripts/run_blender.py ... -- --mug-size large，按需覆盖 PARAMS；中文注释、英文标识符；脚本必须 # -*- coding: utf-8 -*-。

验收条件

• 文件非空且含 BLENDER_KIT_DIR 或 blender_kit 字样（check_output.py 会检查）；用 grep 搜 [A-Za-z]:\\ 命中数 = 0（绝对路径为零，注释里的示例也不留）。
• 部件表每一行的部件名都在 model.py 里出现；PARAMS 覆盖全部尺寸数值；脚本第二遍运行不报"对象已存在/材质重复"类错误。

7. 阶段 4：build 自检

目标：只验证"建模脚本能跑通、场景能建出来"，不渲染不导出，快速暴露语法/API/几何错误。

cd "F:\DeepSeek Harness\blender-modeling"
$OUT = "<工作区>\blender-models\<slug>"
python scripts/run_blender.py --script "$OUT\model.py" --out "$OUT" --stage build --label build

怎么读结果：进程退出码 0 = 成功、1 = 失败；最后一行 BM_RESULT {...} 是机器可读 JSON，关键字段 ok、exit_code、stage、log、duration_s、errors、warnings、renders、exports；失败时 ok:false、errors 是数组（会过滤 TBBmalloc 噪音，并含 Traceback (most recent call last): / Error: 行），log 给出完整日志路径。

验收条件

• 退出码 0；BM_RESULT 中 ok:true 且 errors:[]；renders:[]、exports:[]（该阶段不产图不导出是正确的）。注意 renders/exports 是目录快照：在同一输出目录重跑 build 时会列出上一次遗留的文件，不等于本阶段产物，不要据此判失败。
• duration_s 建议 < 60s；明显超时说明脚本在做渲染/重计算，检查 stage 分支。

失败处理：打开 log 路径，从日志末尾往上找 Traceback 与最后一条 Error:/RuntimeError，修 model.py 对应行，重跑。同类错误连续 2 次立即转第 15 节降级路径，不要第三次硬试。

8. 阶段 5：预览渲染 + 看图自检

目标：用低分辨率快速渲染三视角，然后必须用 read_image 真看每个文件，按第 14 节清单找问题。

python scripts/run_blender.py --script "$OUT\model.py" --out "$OUT" --stage render --label preview

随后逐张打开（三张都要看，缺一张不算自检）：

read_image <输出目录>\renders\view-front.png
read_image <输出目录>\renders\view-right.png
read_image <输出目录>\renders\view-iso.png

本机实测参考：CYCLES CPU 512×512 / 16 samples / denoise 约 1 秒/张，三张预览通常 3-5 秒；慢一个数量级说明分辨率/采样/物体数失控。

验收条件

• BM_RESULT ok:true、renders 至少 3 项，每个 path 文件真实存在且 > 15 KB；三张图都用 read_image 看过（迭代记录写"已看 view-front/right/iso"）。
• 第 14 节清单逐项有结论；有"需修"项 → 进阶段 6。

常见首轮问题与动作：全黑图 → 查灯光/相机/world（troubleshooting T-8）；主体偏小/偏边 → 三视角由 render_views 按 bbox 自动取景（自动忽略 setup_floor 地台），出现异常多半是自建地台或离群道具/隐藏对象被算进取景，改用 setup_floor 或移走离群件；手动相机 + render_still 时才用 fit_camera(camera, objects, margin=1.2~1.5)；部件悬空/穿插 → 先修位置；材质全灰 → 检查 mat 颜色是否 0-1 且已 assign。

9. 阶段 6：迭代

目标：以看图结论为依据，一轮修 1-2 类问题，最多 4 轮。

迭代规则（硬性）

1. 每轮必须先有"上一轮图片证据"才能改；禁止无证据大改。
2. 每轮只改 1-2 类问题，按优先级：整体比例/布局 → 部件完整性 → 颜色材质 → 细节（倒角/平滑/分段）→ 灯光/构图 → 导出一致性。
3. 每次修改必须落到 model.py 的 PARAMS 或对应函数；手改 .blend 无效。
4. 每轮结束重跑 --stage render + read_image，并在 brief.md 迭代记录表登记。每轮必须写清「看了哪几张图」与「关键量化值」（主体占比/留白/亮度等看 report.json.vision，或跑 python scripts/vision_metrics.py --out "$OUT" --write 重算）：

check_output.py 的 check_iteration_records 会校验：记录里显式写出的 renders/xxx.png 必须真实存在；若 report.json 含 vision 字段且不是 backfill 补写，还会检查每轮是否写了图名、提到的视角在 renders/ 里是否有对应图、是否写了数字，且迭代表不能是空的（新产物至少 1 轮数据行，否则 ERROR）。每轮迭代通过闸门后可用 python scripts/snapshot.py --out "$OUT" 打快照（--list 看版本、--rollback 回退最佳版本；rollback 只还原 model.py / renders/ / report.json，不还原 exports/，回滚后重跑 --stage full 重新导出）。

存量项目迁移（backfill）：旧项目没有 report.json.vision 时只做宽松校验。想启用新量化校验，先跑 python scripts/vision_metrics.py --out "$OUT" --write 手工补写；补写的 vision 会带 backfill: true 与 backfilled_at 标记，此时 check_output 只校验迭代记录里的图片引用，不强制新 5 列表格。下一次 --stage full 会自动重算并去掉 backfill 标记，严格校验随即生效；不要手改 report.json.vision 里的数值。

5. 第 4 轮后仍不达标：停止迭代，交付当前最佳结果，并在交付说明里写清遗留问题与下一步改法。不允许为了"更完美"无限循环。

10. 阶段 7：终渲与导出

目标：出正式渲染图、.blend、.glb、report.json。

python scripts/run_blender.py --script "$OUT\model.py" --out "$OUT" --stage full --label final --timeout 900

验收条件

• BM_RESULT ok:true、errors:[]；renders 至少包含 view-* 三张；final-*.png 建议 960×960（或按用户要求），全部 > 15 KB。
• exports 至少包含 exports/model.blend 与 exports/model.glb，两个文件非空；<输出目录>/report.json 存在且合法 JSON，dimensions 三轴为正、有相机与灯光。
• 打开 final-iso.png 再看一遍，与预览一致、无新问题。
• 交付 GLB 只含几何体：kit 1.1.0 起 export_glb/export_stl/export_fbx/export_obj 默认排除 kit_role="floor" 的摄影棚地台与布尔 cutter（.blend 仍保留完整场景方便重渲）；真要带地台时显式传 include_floor=True。交付前确认 glb 里没有 Floor / FloorMat / 布尔 cutter / .001 重名：仓库 examples/ 的 glb 由 ci_check.py 的交付资产检查把关；check_output.py 只查导出文件是否存在/魔数/体积（不解析 glb 内部对象名），自己输出目录的 glb 需用 Blender 导入确认。

10.5 模式 B：修改已有模型

什么时候用：用户说"改一下这个模型 / 把杯子把手加长 / 换个颜色"，并且手上已有现成 .blend（例如上次交付的 exports/model.blend，或 examples/ 里的样例）。

步骤

1. 建输出目录（沿第 1.2 节结构），brief.md 里写清：源文件路径、要改什么、不改什么、验收标准（不要用"新建模型"的 brief 模板）。

2. 复制 templates/edit_model_template.py 到 <输出目录>/model.py，只改顶部 EDITS 字典（对象名 → 操作）与 EXPORT_STEM。支持的操作：

   操作	值	说明
   translate	(dx, dy, dz) 米	按世界坐标平移
   rotate	(rx, ry, rz) 度	按欧拉角旋转
   scale	(sx, sy, sz)	缩放
   material	("材质名", (r,g,b), roughness)	给该对象所有网格换材质（颜色是线性 Base Color）
   hide	True	隐藏（不参与渲染与导出）

3. 先跑 --stage build：日志会打印场景对象名列表与统计，确认要改的对象名（第一次改必然要先看这一行）。

   python scripts/run_blender.py --script "$OUT\model.py" --out "$OUT" --stage build --label edit-build -- --blend "<源模型>\exports\model.blend"

4. 填好 EDITS 后跑 --stage full（或先 --stage render 看预览图），产物是 model-edited.blend / model-edited.glb / view-*.png / report.json。
5. 之后与模式 A 完全一样：第 11 节 check_output.py 0 ERROR、第 12 节交付说明（写明"基于哪个源文件改的、改了哪些对象"）。

注意：open_blend 打开后原地操作，reset_scene() 不会自动调用；不要在该模式下重新建场景，否则源模型会被清掉。源文件损坏时 open_blend 会返回 {} 并打印警告，此时应让用户重新提供 .blend。

11. 阶段 8：check_output.py 闸门（0 ERROR）

目标：交付前最后一道机器闸门。

python scripts/check_output.py --out "$OUT"
# 可选：提高渲染图数量要求（默认 3）
python scripts/check_output.py --out "$OUT" --min-views 4
# 可选：跳过视觉指标（未装 Pillow / 只需查文件时）
python scripts/check_output.py --out "$OUT" --no-vision

判读：逐项 [PASS] / [ERROR] / [WARN]；任何 ERROR → 退出码 1，必须修到 0 ERROR 才可交付。

闸门除文件/报告检查外还包含三组结构检查：check_vision 用 scripts/vision_metrics.py 重算「主体占比/四边留白/底部留白/亮度」并逐字段与 report.json.vision 对照（不一致为 ERROR；任一声明的渲染图无法解码即 ERROR——全部无法解码为 VISION008、部分无法解码为 VISION009，都不再当作 SKIP/WARN 放行）；check_iteration_records 校验 brief 迭代记录引用的渲染图真实存在、每轮写清看了哪张图与量化值（旧产物无 vision 字段、或 vision 带 backfill 迁移标记时只查引用）；check_snapshot 校验 history/ 与 best.json 结构（只 WARN）。

WARN 可以带过，但要在交付说明里写明原因。视觉类 WARN（底部留白 45%-55%、亮度异常、对比度低）、report.vision.ok 与实测不一致、report.vision 缺少视角、SNAP0xx 快照结构 都属于「可以带过但要解释」；report.vision 与实测不一致 与 report.renders 统计与渲染图不符 已升级为 ERROR（report 生成后又重渲/替换了图），按上表重跑 --stage full 或 vision_metrics.py --write 消除。Pillow 缺失时 report.renders 重算降级为不检查（不误报），完整判定需要 Pillow（CI 已安装）。若 vision 带 backfill: true（存量补写），仅校验图片引用，不要求新 5 列表格；下次 --stage full 自动重算后严格校验生效。

12. 阶段 9：交付

目标：把"文件 + 怎么看 + 还能怎么改"一次说清。给用户的交付说明必须包含：

1. 一句话：做了什么物件、风格、面数规模（report.json 的 total_tris）。
2. 文件清单表：绝对路径 + 用途（.blend 可编辑、.glb 给引擎/网页、renders/*.png 预览、report.json 统计）。
3. 怎么看：.blend 用 Blender 4.0 打开；.glb 可在 Blender 文件 → 导入 → glTF 2.0，或拖进 Three.js / Unity / UE；预览图直接看 png。
4. 已知简化：哪些细节是简化的、为什么（面数/时间/提示词未指定）。
5. 怎么改：指出 model.py 的 PARAMS 位置，给出改完后的重跑命令（--stage full）；附迭代记录（跑了几轮、每轮修了什么、遗留什么）。

13. 建模质量基线（验收的底线）

14. 看图自检量化清单（每轮渲染后逐项过）

工具：read_image 打开每张 renders/view-*.png；数值证据看 report.json.renders[]（std、black_ratio）与 report.json.vision（主体占比/四边留白/底部留白/亮度分位；run_blender.py --stage full 自动写入，也可 python scripts/vision_metrics.py --out "$OUT" --write 重算。手工补写的 vision 带 backfill: true 标记；check_output 会逐字段对照实测值，不一致为 ERROR）。另外 check_output 在 Pillow 可用时还会用 sRGB 亮度公式从 PNG 重算 report.renders[] 的 mean/std/black_ratio（与 kit 保存口径一致），记录值偏差超过容差（mean/std 1.0、black_ratio 0.01）即 ERROR，说明 report 陈旧或图被替换。

15. 失败处理与降级路径

15.1 错误定位三步

1. 看 BM_RESULT：ok、errors、log、duration_s。
2. 打开 log 文件，从末尾往上找 Traceback (most recent call last):、最后一条 Error:/RuntimeError，定位到 model.py 行号。
3. 首次出现先修一次；同类错误连续 2 次 → 立即降级（15.2），不要重复第三次。

15.2 降级路径（连续 2 次同类失败时强制启用）

15.3 超时与限时

• 默认 --timeout 600；终渲用 --timeout 900。超时表现为 ok:false、errors 含 TIMEOUT 字样、退出码 1；先降负载，仍超时则拆阶段跑（--stage build 定位建模，正常则问题在渲染）。
• 单步操作连续失败超过 20 分钟，向 Lead 报告当前卡点、已试方案与证据（日志末 20 行 + 图片路径）。

16. 参考文档索引

17. 校验闸门表

18. 最后提醒

各阶段小节里的命令块按顺序复制即可，不再单独维护一页命令卡。记住：脚本可复现 > 图片好看 > 文字说明；任何"看起来没问题"都必须先有一张真看过的图和一次 0 ERROR 的闸门。