Whitebox Previs Executor

---
name: whitebox-previs-executor
description: 在用户明确要求3D白模预演时，将已有视频提示词、镜头描述或分镜编译为可播放的机位与基础走位预演；创意镜头思路、方案讨论或Skill测试本身不触发渲染。动作密集打斗必须通过骨骼、武器约束、共享接触点和单动作门，否则拒绝或标为诊断，不用体块位移冒充打戏。
---

# 提示词 3D 白模预演器

**Public experimental package.** This package is an explicit test executor, not a stable promise of arbitrary choreography. It contains the twelve runtime files only; the local workbench and Blender binaries are not bundled.

## 可配置运行依赖

- 普通或关节预演需要已安装的 Blender。定位顺序是 `--blender`、`WHITEBOX_BLENDER` 环境变量、`PATH`，最后是当前任务下的 `_runtime/blender-*-windows-x64/blender.exe`。指定的路径无效时直接报错，不暗换版本。
- 两个启动器要求显式 `--runtime-dir`，并将子进程临时目录及应用配置定向其中；在结构、后端路由或依赖检查失败时不创建运行缓存。
- 历史软件渲染器的 FFmpeg 定位顺序为 `--ffmpeg`、`WHITEBOX_FFMPEG`、`PATH`；探测器为 `--ffprobe`、`WHITEBOX_FFPROBE`、`PATH` 或 FFmpeg 同目录的对应可执行文件。公开包不查找作者电脑的软件路径。
- 相较本地副本，公开包仅增加依赖环境变量、移除本机 FFmpeg 兜底，并在启动前拒绝无效规格及错误打斗后端；这不是新版动作能力。缺少依赖或实际可播放视频时仍须报告未完成。

只有当前请求明确要实际白模预演时才执行；已有提示词、创意思路或“看看方案效果”不单独构成渲染授权。创意讨论按当前文字阶段交思路，不因缺Blender或视频平台而阻塞。

进入预演后，用户只需提供已经写好的视频提示词或镜头。第一交付层是用户可直接播放的 `MP4`；不要先让用户操作Blender、查看编辑器、填写坐标或审查JSON。

## 输出合同

每次执行至少产生：

- 可播放的3D白模 `MP4`；
- `previs_compiled.json`：提示词的可审计3D执行解释；
- `previs_validation.json`：时长、帧数、分辨率、切点、实际解码和观看检查；
- 可选 `.blend` 工程，只作为可编辑后台产物，不代替视频。

截图、编辑器界面、工程文件、参数表、静态关键帧、2.5D推拉、软件功能说明或内存编码探针均不能替代MP4。

## 执行流程

1. 完整保留用户原提示词。输入可为一句提示词、单镜、多镜、任意时长或无明确时长。
2. 按 [references/prompt-to-previs.md](references/prompt-to-previs.md) 编译为 `previs-compiler/1.0` 合同。只执行提示词中已有的镜头意图；默认值必须可追踪，不得冒充正式视频模型的预测。
3. 运行 `scripts/validate_compiled_previs.py`。时间重叠、镜头空档、缺摄影机、人物引用错误或不可执行关键歧义必须在渲染前拒绝。
4. 普通走位与摄影机预演用 `scripts/run_blender_previs.py` 调用 `scripts/blender_previs_adapter.py`。包含合格 `previs-action/1.0` 动作扩展的打斗规格改用 `scripts/run_blender_rigged_fight.py` 调用 `scripts/blender_rigged_fight_adapter.py`；该后端逐帧求解肩肘腕、髋膝踝、双手握点、武器和共享接触。动作后端失败时必须停止，不能暗中回退到普通体块路径。
5. 用实际解码器核对MP4的帧数、帧率、分辨率和时长；再检查每镜首帧、中点、尾帧及切镜前后。
6. 第一回复直接展示或链接MP4，再说明默认值和边界。缺少可播放视频时，只能报告未完成。

## 编译边界

- 明确时长按原文执行；未写时长时，单镜默认4秒，多镜默认每镜3秒，并标记 `deterministic_default`。
- 只有镜号、时间码、硬切、切到或明确转场才自动拆镜。“随后、然后、接着”默认只是同镜动作先后。
- 未写摄影机运动时保持静止，不自动添加电影感漂移。
- 未写场景时只生成地面网格和必要空间参照，不编造环境美术。
- 当前公开包已实现人形／人形机甲和双臂悬浮类代理。四足、车辆或其他未实现类别须在编译阶段报出能力缺口，不承诺已有对应后端，也不得改成人形或球体冒充原主体。除非提示词主体就是球体，不得用球替代人形主体。
- 人物和场景可以粗糙，火柴人级精度允许；但请求了运镜时，前中后景必须提供足够参照，让视差和摄影机运动在视频中肉眼可见。
- 预演证明的是当前编译解释中的镜头、空间、走位、切镜和节奏，不证明正式模型会生成相同像素、表演、材质或特效。

## 动作密集打斗门

普通走位与摄影机预演可以使用粗代理；打斗不能只移动人物根节点和切换摄影机。动作密集提示词在渲染前必须证明执行层具备：

- 有关节枢轴或骨骼的进攻、格挡和受击姿势；
- 武器与双手的握持约束，武器不能漂浮；
- 进攻武器和防守肢体共享同一个实际接触点；
- 接触前蓄力与减速、接触时冻结、恢复后的双向反作用；
- 未读提示词的观看者仅凭视频就能说清“谁用什么攻击、谁如何格挡、在哪里接触、双方如何弹开”。

上述任一项缺失时，只允许输出失败诊断，不得称为打斗预演。完整打斗序列开始前，先用一个2—4秒单动作镜头过门；单动作门未通过，不得扩成长打戏或多镜头全片。

动作规格必须按 [references/prompt-to-previs.md](references/prompt-to-previs.md) 的 `previs-action/1.0` 扩展明确列出动作节拍、两处武器握点、进攻与防守接触插口、唯一共享接触、冻结帧和反作用段。验证器必须对实际渲染关节、武器和索线几何做检查；只测原始控制点、动作名称或碰撞标记不算通过。当前后端没有实现的新动作类型必须先补执行与单动作门，不能因存在“打斗”字样而套用相似动作。

## 完成门

只有同时满足以下条件才能写“提示词预演视频已生成”：

- MP4存在、非空并由实际解码器打开；
- 时长、帧率、分辨率和镜头边界与编译合同一致；
- 请求的摄影机运动来自真实3D相机位移或旋转，不是二维平移或变焦冒充；
- 人物起点、中点、终点以及切镜前后状态可见；
- 场景参照产生可感知的三维视差；
- 已观看完整视频或逐镜检查首帧、中点和尾帧；
- 已明确所有默认值、未解决项和不证明的边界。
- 若内容是打斗，未读提示词的独立观看者能辨认进攻方、武器、格挡方、接触点和反作用；只看见方块靠近、穿插或弹开不算通过。
- 若内容包含持物、缠绕或抓取，握点与接触点必须落在最终渲染几何上，并跨相关帧保持；控制点坐标正确但最终线段、手或武器在画面中脱离，仍判失败。

旧版 `references/previs-spec.md`、`scripts/validate_spec.py` 和 `scripts/render_previs.py` 仅用于读取历史 `0.1` 合同和失败回归，不再作为新提示词预演的首选生产路线。