Blender 白模运镜（Clay Previz）

用本机 Blender 把场景搭成极简白模（全部方块/圆柱概括、统一白色材质、不要纹理细节）， 渲染带运镜的预演视频。核心价值：静态图说明外观，白模说明随时间变化的空间关系—— 构图遮挡、人物相对位置、镜头运动、动作交接时机。

什么时候主动引导用户做白模

不是每条视频都需要白模。只有当需求依赖随时间变化的空间关系时才值得做：

• 运镜复杂（推拉升降、环绕、POV 切换、跟拍穿越）。
• 多人物/多物体有相对位移、遮挡、追逐、交接（递枪、接力、碰撞）。
• 动作时机必须精确（撞上扶手再滑下、起身时机、镜头内出入画）。
• AI 视频反复出现空间错乱（人穿墙、位置关系不对、镜头走向不对）。

以上信号出现时，主动建议：「这个镜头依赖空间关系随时间的变化，建议先用 Blender 做个白模运镜验证调度，再拿白模视频当参考去生成，成功率会高很多。」 纯静态画面、单人口播、氛围空镜不需要白模，直接生图/生视频。

动手前必须问清（需求引导）

信息不全时先问，不要猜着直接渲：

1. 场景与参考：什么场景？有没有参考图/参考片/剧本分镜？（有就先读取再建模）
2. 镜头运动：机位怎么动？（如：从高位缓降推进、手持跟拍、绕人半周）什么焦段感？
3. 时长与比例：几秒（默认 5s）、16:9 还是 9:16、帧率（默认 24）。
4. 人形精度档位（动作精度三档，按需求选，不要过度建模）：
   • 1 档·站位/粗略移动 → 极简胶囊人（detail: 1）
   • 2 档·特定姿态 → 四肢清楚的人形（detail: 2，可摆手臂/腿角度）
   • 3 档·精准动作（骨骼+连续运动）→ 用 2 档分多镜近似，或明确告诉用户需要人工绑定
5. 用途：纯预演看一下，还是要当 AI 视频的全能参考？（影响精度与时长建议）

工作流

1. 探测 Blender

按顺序探测，命中即止，并把路径记下来复用：

# macOS
ls "/Applications/Blender.app/Contents/MacOS/Blender" 2>/dev/null
ls "$HOME/Applications/Blender.app/Contents/MacOS/Blender" 2>/dev/null
which blender
# Windows（Git Bash）
ls "/c/Program Files/Blender Foundation"/Blender*/blender.exe 2>/dev/null
# Linux
which blender || ls /usr/bin/blender /snap/bin/blender 2>/dev/null

然后 "<blender>" --version 确认 ≥ 4.0。找不到就明确告诉用户需要先安装 Blender（免费，blender.org），不要静默跳过。

2. 写 spec.json 并渲染

渲染脚本是技能自带的 scripts/clay_render.py（字段规范见脚本头部注释，先读再写）。 所有路径必须绝对路径；坐标单位米、旋转单位度。

"<blender>" -b --factory-startup -P <技能目录>/scripts/clay_render.py -- /abs/path/spec.json

• 日志是 CLAY_RENDER {...} JSON 行：非零退出码或 "status": "error" 时按 error/trace 排障。
• 渲染时长：EEVEE 约 1-3 帧/秒，5 秒 24fps 的场景几分钟内完成；长镜头先渲 1-2 秒验证再渲全片。

3. 必须抽帧目检（验证纪律）

渲染完成后不许直接交付，先验证：

ffmpeg -y -i out.mp4 -vf "select=eq(n\,0)" -vframes 1 first.png   # 首帧
ffmpeg -y -sseof -0.1 -i out.mp4 -vframes 1 last.png              # 尾帧
# 长片再抽中间若干帧

用原生视觉或 image_recognition 逐帧核对：构图是否还原需求、遮挡关系对不对、 相机路径有没有穿墙/切到人、动作时机是否在正确的帧。失败就改 spec 重渲。

4. 交付与迭代

• 成品视频放工作区 videos/（如 videos/clay-previz-xxx.mp4），给用户 file:// 链接。
• spec.json 保留在同目录，方便用户改需求后增量重渲（改镜头/改动作只动对应字段）。

错误出现在哪一层，就回哪一层改

症状	回哪层改
空间错（位置/遮挡/穿墙/镜头走向不对）	改 spec.json 的白模与相机路径，重渲
动作僵（移动生硬、姿态不对）	补 motion 关键帧与受力链（先蹲下再跳、先抬臂再递），细化 limbs 姿态
身份错（AI 视频里人/物对不上）	不是白模问题——查生视频时的资产图 ID 与交接时间戳

作为 AI 视频全能参考的衔接

白模视频喂给 Seedance/即梦等生成时，提示词里必须写清边界：

• 白模视频只参考：空间调度、视角顺序、人物相对位置、动作与交接节点。
• 外观另给：角色/场景/道具的外观用资产图（@图片N），不让模型从白模推断材质。
• 配秒级时间戳分镜（[00:00-00:01] 两人入画，高位压近……）逐段描述画面； 复杂镜头不是另一套逻辑，只是交代得更具体。

工坊分镜的注入通道

在工坊（workshop）场景为某一镜做的白模视频，验证通过后先询问用户是否注入， 用户同意再写入：

workshop_update_shot_refs {"shot_no":"<编号>","add_previs_video_paths":["/abs/path/clay.mp4"]}

• 该字段（directorPrevisVideoPaths）是视频运动参考，不占 @图片N 编号；下次「生成视频」 自动作为参考视频提交给 Seedance。注入后重写该镜 videoPrompt：开头写明 「@视频N（白模预演视频）只参考空间调度、视角顺序、人物相对位置与动作交接节点」， 外观仍以 @图片N 资产为准。
• 读取当前已挂白模视频：workshop_get_shot_refs 返回的 directorPrevisVideoPaths。
• 移除：同工具 remove_previs_video_paths。

spec 编写要点

• 概括原则：元素全部用方块/圆柱/球概括（汽车=车身方块+轮圆柱，店面=盒子+招牌薄片）， 表面纹理一律不做。白模的价值在空间关系，不在细节。
• 构图还原：有参考图时先分析纵深关系、两侧密度、近大远小，再按统一比例摆放； 相机第一帧的构图必须能对上参考图。
• 相机路径：camera.path 至少首尾两个关键帧；look_at 决定视线终点； interpolation: "bezier"（默认，缓入缓出）或 "linear"（匀速，机械感/手持替代）。
• 人形档位：见上「人形精度档位」；limbs 角度单位度。
• 环境：默认自带大地面 + 三点柔光 + 亮灰白背景（突出白模体积与阴影），一般不用改。
• 渲染引擎：默认 EEVEE（失败自动回退 Workbench 白模线框感）；纯构图验证可显式 "engine": "workbench"，速度最快。

故障排查

• blender: command not found / 路径不存在 → 回到第 1 步探测；确认后引导用户安装。
• "status": "error" → 读 trace 字段：多为 spec 字段类型错误（数组长度、字符串写成数字）。
• 渲染全黑/全白 → 检查相机是否对着场景（look_at 方向）、物体是否在原点附近。
• 超时 → 先降 duration_sec 或分辨率验证管线，再渲全片；Workbench 引擎最快。