提示词 3D 白模预演器

Public experimental package. This package is a test executor with bounded backends. The local workbench, Blender binaries and third-party visual assets are not bundled.

先选执行范围

• 忠实复现（faithful）：保留用户原文、镜头顺序、时长、动作因果和点名交付物。不能为了套用示例改成另一场追逐或打斗。补齐的参数标明来源。
• 建议修改：复现暴露出遮挡、构图或接触问题时，先给具体失败证据，再在已授权范围内另存候选修订；原输入、忠实版与建议版分开。用户已经授权重新设计时可直接设计，不能倒称为原文复现。
• 新输入仍走既有编译器及其已实现后端。明确重放或研究三个原创案例时，按需读取 references/original-cases.md，用 scripts/run_case.py。案例后端是固定场景模板；它不支持任意人物坐标、任意车辆或新招式输入，不能因为模板能运行而声称通用能力已接入。
• 白模有建场景、求解、渲染和观看成本。需要判断空间、复杂运镜、持物交接或动作接触时使用；只需文本答复或简单提示词修改时不强加白模。先低清或关键事件帧看结果，再局部修补，最后按交付需要渲染全片。
• 输入和交付图数由当前任务锁定。一图任务只交一图；多图任务按要求逐图绑定；三个案例中的单图交付不能升级为所有任务的图数规则。

可配置运行依赖

• 普通或关节预演需要已安装的 Blender。定位顺序是 --blender、WHITEBOX_BLENDER 环境变量、PATH，最后是当前任务下的 _runtime/blender-*-windows-x64/blender.exe。指定的路径无效时直接报错，不暗换版本。
• 两个启动器要求显式 --runtime-dir，并将子进程临时目录及应用配置定向其中；在结构、后端路由或依赖检查失败时不创建运行缓存。
• 原创案例入口要求显式 --blender、--ffmpeg 和新的 --output-dir；几何审计、缓存、日志、MP4、抽帧与可重放源码都落在该目录，路径可含空格。--mode frames 是片段取样，--mode build 只建工程；这两种模式都不能当成完整预演交付。
• 历史软件渲染器的 FFmpeg 定位顺序为 --ffmpeg、WHITEBOX_FFMPEG、PATH；探测器为 --ffprobe、WHITEBOX_FFPROBE、PATH 或 FFmpeg 同目录的对应可执行文件。公开包不查找作者电脑的软件路径。
• 普通／旧打斗启动器的兼容行为保持。新增案例使用独立 whitebox-case/1.0 执行记录，不扩展旧 previs-action/1.0 的支持承诺。缺少依赖或实际可播放视频时仍须报告未完成。

用户只需提供已经写好的视频提示词。第一交付层必须是用户可直接播放的 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。
• 只有镜号、时间码、硬切、切到或明确转场才自动拆镜。“随后、然后、接着”默认只是同镜动作先后。
• 未写摄影机运动时保持静止，不自动添加电影感漂移。
• 未写场景时只生成地面网格和必要空间参照，不编造环境美术。
• 通用编译后端已实现人形／人形机甲和双臂悬浮类代理。原创 chase 案例另有两辆固定车与道路算法，但不等于通用车辆编译器。四足、任意车辆或其他未实现类别须在编译阶段报出能力缺口，不得改成人形或球体冒充原主体。除非提示词主体就是球体，不得用球替代人形主体。
• 人物和场景可以粗糙，火柴人级精度允许；但请求了运镜时，前中后景必须提供足够参照，让视差和摄影机运动在视频中肉眼可见。
• 预演证明的是当前编译解释中的镜头、空间、走位、切镜和节奏，不证明正式模型会生成相同像素、表演、材质或特效。

动作密集打斗门

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

• 有关节枢轴或骨骼的进攻、格挡和受击姿势；
• 与动作相符的握持约束，武器不能漂浮；单手、双手、松手和换手必须按具体动作确定；
• 进攻武器和防守肢体共享同一个实际接触点；
• 接触前的准备、接触中的阻力或卸力、接触后的反作用与支撑；定格、短暂停顿和速度变化只在该动作需要时使用；
• 未读提示词的观看者仅凭视频就能说清“谁用什么攻击、谁如何格挡、在哪里接触、双方如何弹开”。

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

既有两个双握接触 profile 的规格仍按 references/prompt-to-previs.md 的 previs-action/1.0 扩展列出动作节拍、两处握点、共享接触、冻结帧与反作用段；这是它们的执行边界，不是所有动作的物理规则。原创棍术案例使用独立 case 记录，包括滑移卸力和本例的双握。任何路径都要检查实际渲染关节、武器及适用的索线几何；只测原始控制点、动作名称或碰撞标记不算通过。新动作须先补执行与单动作验证，不能因存在“打斗”字样而套用相似动作。

完成门

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

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

验收分别记录：数值／最终几何、媒体全片解码、抽帧可读性、连续观看、用户接受、正式视频模型生成。自动入口只能更新它实际执行过的层；解码成功不代表看过，抽帧通过不代表看完整片，白模通过不代表用户审美接受或正式视频已生成。连续观看尚未完成时明确标出，不写“完整观看验收通过”。

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