提示词 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 兜底，并在启动前拒绝无效规格及错误打斗后端；这不是新版动作能力。缺少依赖或实际可播放视频时仍须报告未完成。

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

输出合同

每次执行至少产生：

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

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

执行流程

1. 完整保留用户原提示词。输入可为一句提示词、单镜、多镜、任意时长或无明确时长。
2. 按 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 的 previs-action/1.0 扩展明确列出动作节拍、两处武器握点、进攻与防守接触插口、唯一共享接触、冻结帧和反作用段。验证器必须对实际渲染关节、武器和索线几何做检查；只测原始控制点、动作名称或碰撞标记不算通过。当前后端没有实现的新动作类型必须先补执行与单动作门，不能因存在“打斗”字样而套用相似动作。

完成门

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

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

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