scenario-blender-blockout

用于视频生成流程的 Blender 粗模

粗模是引导片段：视频模型会复制镜头运动路径、构图、镜头质感、缓动、剪切点、镜头时长、每个体块的位置和比例、人物朝向以及每条运动轨迹，并根据文本和图像补全其余内容（材质、光线、天气、每个代理物体的真实身份、面孔、服装、临演、声音）。因此，粗模对运动和布局有完全的决定权，对视觉效果则毫无决定权。模糊不清会毁掉生成效果；粗糙本身不会：弯曲的路灯会变成蛇，松散的肢体方块会变成额外人物，未标记的汽车会倒着开。先用几何体明确物体身份，再用提示词文本补充说明，并通过将动画预览和视频同步并排播放来评估结果，绝不要只在视口中判断。如果这里提到的某个相关技能不在你可用的技能中，请让用户安装它（npx skills add scenario-labs/skills --skill <name>）；若无法等待，则根据工具架构继续操作，并标明缺失项。

必需背景知识： scenario-blender-expert（执行通道、审查循环、5.2 API 变更）。 视频生成：scenario-blender（插件的报价、生成和放置流程）、scenario 技能（连接、上传、任务）以及 scenario-seedance（参考视频字段）。

工具包：scripts/bx_blockout.py： import sys; sys.path.insert(0, "<this skill>/scripts"); [sys.modules.pop(m, None) for m in ("bx_blockout", "bx_kits")]; import bx_blockout as B， 其中 <this skill> 是已安装技能文件夹的绝对路径。弹出模块可清除 Blender 单个 Python 环境中上一次运行留下的副本。构建器会按名称创建或获取对象，因此可重复调用；如果名称已被用户自己的内容占用，则会拒绝使用（名称在整个文件中全局唯一）。审计结果为空即表示通过。调用顺序见模块文档字符串。 scripts/bx_kits.py（import bx_kits as K，规则相同）可添加建筑、摊位、树木、路灯、岩石和车辆，并提供三个精细度等级、四种角色风格的人物、群众、交通、配色方案以及 K.audit_budget。四个由简到精的完整场景及其渲染通道结果：示例（工具脚本、1、2、3、4）。

应使用哪个技能。 本技能：为视频模型提供指导。由导演和剪辑师评估的故事预演和动画分镜：scenario-blender-previs-storyboard；必须用于指导视频模型的已批准动画分镜，应在此处重建。

1. 将需求重述为构建计划

在进行任何调用之前，先写下：

• 元素及其基本形态：“巴士 = 带有标记车头的长方体”，“人物 = 彩色胶囊体”。不要建模超出需求描述范围的内容。
• 所有内容的尺寸，单位为米；需求未说明时，采用合同表中的尺寸，并注明来源。
• 格式：整数帧率、画面比例、秒数。范围为 1 到帧率 × 秒数（24 fps、8 秒：1..192）。
• 镜头：数量、运动、镜头、构图约束（“主角始终在画面内，完整呈现全身”）、剪辑方式；将节拍固定到秒，并立即换算为帧。
• 等级：密度（简单、中等、高级、专家级：占地面积、元素、主角、配角、镜头）、保真度（粗略、成形、精细）和配色方案；从需求中判断并设定：参见等级。需求未说明时（仅列出主角和镜头也算未说明）：采用高级、成形、类别配色，并注明；仅当场景中只有一个角色时，才降为简单或中等。专家级意味着元素、运动物体和剪辑很多，而不是使用更精细的方块。
• 视频模型，现在确定：角色风格和提示词语法取决于它（在插件通道上调用 list_models，在托管路由上调用 recommend）。
• 每个角色的形象风格（角色形象）：有四肢的替身会让模型模仿其步态；没有四肢的替身则会让模型自行生成身体和动作。主角默认使用彩色胶囊体；当角色需要彼此区分或要携带推动故事发展的物品时，使用特征鲜明的造型（两到三个标志性特征，如护目镜、兜帽、手提灯）；只有在需要由灰色骨架人偶控制肢体动作时，才使用这种造型。告知用户所选风格、它对控制力的影响，以及其他风格可以在较短片段上进行 A/B 测试。
• 身份颜色：主角用红色，接着依次为蓝色、绿色、黄色、紫色、青色。
• 视频模型需要补全的刻意留白，以及需求中说明的验收测试：这些都必须纳入审核。

判断需求中尚未明确的内容，并记录决定；不要停下来询问。费用是例外：Scenario 价格会展示给用户并由其批准（第 3 节）。提供参考图时：列出图中的主要形体，以合理的比例搭建它们，匹配摄像机高度和镜头，使用该摄像机调用 render_still，进行比对并调整，直到构图匹配，然后再制作动画。

2. 输出约定

四项交付内容：场景、锁定的摄像机时间线、播放预览、交接表。

• 场景规范。 使用角色前缀（ENV_、FIG_、PRP_、CAM_、CRV_、RIG_、NULL_target_，完整表格见约定），并建立一个根集合及按角色划分的子集合。用 B.park 收起默认的 Cube、Light 和 Camera，切勿删除。如果文件中有其他内容，则用 B.make_scene 新建场景，现有内容一律不动；每个对象都必须能追溯到你的某个制作阶段。
• 比例。 单位为米，Z 轴向上，地面位于 z = 0，角色根节点位于脚底。模型在保持各部分尺寸不变的前提下，保留它们的现状，包括错误。不要使用任何熟悉的物体作为比例参照：添加一个 REF_ 人物。
• 颜色用于区分块面和标识身份。 每个主角使用一种饱和色（B.PALETTE，主角红色），布景使用一个 K.scheme（默认按类别使用色相、按身份使用灰色，或使用材质颜色），额外角色使用中灰色，场景使用一盏灯和深色世界背景。B.paint 和各套件会设置对象颜色与材质；套件包含多种颜色，因此 Solid 视图需要将颜色类型设为 Material（这是 B.solid_view() 和播放预览的默认值）。全灰色播放预览说明身份信息已丢失。通过套件参数重新着色：同一颜色共用材质。仅在摄像机移动且需要表现景深的位置使用网格或棋盘格纹理，并在交接表中注明“替换，绝不继承”。
• 时间线。 在创建任何几何体之前调用 B.lock_format：帧率为整数，帧范围为 1 到 fps x 秒，分辨率为 1920x1080（21:9 使用 2520x1080），缩放为 100%。每个镜头使用一台摄像机，并将其绑定到该镜头首帧上的 CUT_ 标记（B.bind_cuts）；使用硬切，转场帧数为零。
• 摄像机架。 轨道式：B.rail_camera（曲线、沿 Follow Path 移动的滑轨、使用 Track To 瞄准、摄像机）。手持跟拍、直线推进和多镜头主场景的制作流程见约定。通过移动瞄准目标重新构图，切勿旋转摄像机。
• 镜头。 根据景别为每个镜头选择一个焦距（B.lens_for_coverage；环绕镜头用 28 mm，越肩镜头用 42 到 45 mm，室内镜头用 24 到 30 mm，微距镜头用 85 mm），clip_start 设为 0.05。切换焦距只能通过切换摄像机实现：切镜帧上绝不为焦距打关键帧。镜头焦距可在镜头内部平滑变化（有意的变焦），绝不能跳变。
• 缓动。 使用带自动钳制控制柄的 Bezier 关键帧（B.smooth_keys）；轨道上的速度由关键帧间距决定（B.key_rail），暂停时使用两个近似相等的数值。仅对逐帧烘焙的移动（车辆、车轮）使用 LINEAR。关键帧应延伸至每个切镜点之外，确保边界处不会停止。
• 手持摄影使用 NOISE F 曲线修改器，绝不使用抖动关键帧。使用 B.audit_handheld 根据约定中的预算测量效果；animation_data_clear() 会移除修改器，因此重新设置关键帧后要重新添加。

3. 渠道：插件或无头模式

当前使用的渠道是插件的本地 Scenario MCP 服务 scenario-blender（blender.scenario.com 上的指南将该插件称为 Scenario for Blender）。工具表、调用限制和超时后的恢复方法：见 插件。最先要注意的两点：在用户启用 Allow connected agents to run Python 前，execute_python 始终不可用（出现 PermissionError 就应询问用户）；调用会在 120 s 后停止，因此每次调用只发送一个阶段，并在每个阶段后运行 B.stage_backup(label)。

插件自带的工具（见 插件）：其付费版 Blockout 适用于通用的 Stage 2 场景，不含人物、摄像机或身份色；camera_path 围绕静态中心为单个镜头设置关键帧，不支持跟踪或多镜头（使用 B.rail_camera）；Render Video 是视频渲染流程。

无头模式，不使用插件：通过 scenario-blender-expert 的无头辅助工具运行每个阶段。加载前一个 .blend，使用 B.guard 检查，再进行扩展，然后保存新的 B.stage_backup(label)，供下一阶段使用。示例脚本框架 仅适用于从工厂启动状态开始的一次性构建：start() 会删除所有对象，包括此前阶段的对象。切勿用它恢复备份。120 s 限制仅适用于插件。

4. 构建顺序

每个阶段后都要备份；重置后从最近的备份恢复（见约定）。每次调用或阶段脚本都要以 B.guard(expected_file=..., scene=...) 开始：排队的调用会作用于当前打开的文件。

0. 探查，只读：scene_summary、datablocks_summary（无头模式：bpy.data）。若场景中已有其他作品：新建场景。
1. 格式与脚手架：B.make_scene、B.lock_format、B.collection 树、B.park、暗色世界。
2. 场景布置：按选定的精细度制作套件（K.building、K.stall、K.tree），或用厚实的方块（B.box）按真实比例搭建；重复物件使用链接副本（K.instance）。也可用插件的 Blockout 搭建通用场景。
3. 人物：按选定的角色风格为每位主角创建 K.figure(..., style=, features=)，根节点位于脚部，面向移动方向（见角色）。使用 K.walk_path，并传入由（帧、位置）组成的表格进行移动；步行时步幅为身高的 0.42 倍，奔跑时约为 0.7 倍；用 K.pose 制作手势，用 K.crowd(style=...) 添加群演。
4. 道具与车辆：在真实位置放置基本几何体。在车辆几何结构中标明车头（车头处有灯块和格栅，车尾处为暗红色）；车轮位于 z = 半径处，只有近景能看出旋转时才单独添加一个旋转通道（套件中的车轮属于车身网格）。人物附近不要放置散落的方块。
5. 灯光：一个面光；只有当需求中包含灯光设计时，才命名为主光、补光和轮廓光。
6. 摄像机：按镜头设置机架和镜头，使用 B.bind_cuts。
7. 动作润色：使用 B.key_rail 和 B.smooth_keys；在剪辑点之后设置关键帧、添加手持晃动，并让车辆沿一条单调曲线逐帧移动。
8. 审查（第 5 节），直至无问题。如果场景布置遮住了主角，就移开遮挡物并保留摄像机方案。
9. 最终处理：设置为第 1 帧、第 1 个镜头的摄像机，运行 B.audit_frames、B.state_audit，创建最终备份，然后生成播放预览并交付说明表。

5. 审计：先看数字，再看画面

检查项	辅助工具
帧数计算和分辨率	B.audit_frames(seconds, fps)
标记边界、切换、镜头、跳变	B.audit_cuts()（当需求要求使用同一镜头时，设为 same_lens_across_cuts=True）
每个镜头中的主体	对完整人物使用 B.audit_framing({"CAM_s1": ["FIG_red"]}, whole=True)
头部始终不被遮挡	B.audit_occlusion("FIG_red")
距离过近、超出合法范围	B.audit_distance(subject, volume=...)（仅适用于完整人物镜头）
相互穿插	B.audit_intersections(names)
脚和车轮着地	B.audit_ground(names)
手持摄影幅度	B.audit_handheld("CAM_s1")
交接前的人物清点	B.state_audit()

审计每个镜头中对应的主体（微距镜头检查车轮，插入镜头检查手）。然后查看画面： 使用 set_frame 和 render_still 检查每个镜头的第一帧、中间帧和最后一帧，并留意数字检查遗漏的内容：车辆的正面、彼此相连的人物、缺少有机曲线的刚性道具、画面边缘没有多余物体，以及结尾和开场一样稳定。阈值和读数见： audits。审计每隔 step 帧抽样一次；镜头较长时，增大 step 以避免超过调用次数限制。

6. Playblast、交接表、视频生成

Playblast。 使用无头模式，在最新的 B.stage_backup 副本上，通过 scenario-blender-expert 的 bx_review.playblast(out_path, res_pct=100) 生成 H.264 MP4：在 Workbench 中，场景摄像机按帧范围拍摄，剪辑点遵循已绑定的标记。使用会话的二进制文件（bpy.app.binary_path）：PATH 上较旧的 blender 会拒绝打开该文件。没有 shell 时，通过 execute_python 调用同一函数会在 Blender 渲染期间阻塞：只处理短片段，超时后先查找文件，再决定是否重新运行。在每个镜头的起始、中间和结束位置添加摄像机静帧。

交接表，根据场景生成（模板）：与参考图像对应的颜色图例、K.cast() 行、来自 B.cut_list() 且包含精确时间的剪辑列表、哪些实体已被阻挡以及哪些仅存在于文字中、每个产物及其时间码、用文字描述的每种动作状态（“缓慢移动”“静止不动”），以及用于消除歧义的条款（“如果文字和视频对动作的描述不一致，以视频为准”）。

视频生成，始终通过 Scenario 进行，并且必须先获得用户对确切价格的批准。无人值守时，在报价处停止（estimate_cost 或 dry_run），报告价格，并跳过需要用户选择文件的本地上传：

• 插件，Render Video 流程：调用 B.solid_view()，确保录制画面显示身份颜色；将 force_solid 设为 false（否则所有内容都会变成灰色）；设置模型可接受的时间线长度；然后依次执行 list_models、model_schema、render_form（通过 configure 设置 parameters {"duration": <clip seconds>}，然后执行 prepare、inspect）、estimate_cost、generate、wait_for_job 和结果应用，步骤详见 交接 路线 1。录制内容是静音的 1280x720 视频片段。
• 托管版 Scenario MCP，用于全分辨率 playblast：按照 scenario 技能的说明上传 playblast，找到支持参考视频的模型，依次调用 model_schema_get、先运行 dry_run 的 model_run、jobs_wait 和 asset_download。

提示词应以动作描述为主：视频片段是排练素材，演员应按角色和动作来描述，绝不要描述代理模型的形状；风格应来自四格风格板，而不是经过重新风格化的单帧。胶囊演员还需附加替身说明（胶囊只标示位置、高度、速度和朝向）以及步态说明（演员）。在插件流程中，插件会自行说明视频片段和图像各自的用途，因此 look 只包含演员和风格。语法、条款和已测试的限制：见交接。

实例

简述：“10 s，24 fps：仓库中，一个红色跑者在货箱排之间冲刺并朝镜头跑来；第 6 秒，一个蓝色守卫走出来；手持 35 mm 镜头后退。”

1. scene_summary {"fields": ["type"], "limit": 100}：该文件中还有其他工作，因此在旁边新建场景。
2. execute_python：B.make_scene("BLK_warehouse")；下一次调用 B.guard(scene="BLK_warehouse")、 B.lock_format(24, 10)（1..240）、集合和备份。
3. 地面尺寸为 34 x 20 m，墙高 7 m，摆放两排 1.2 m 货箱，使用 B.box；备份。
4. K.figure("red", 1.8, (0, 15, 0), style="featured", features=("hood",))，然后调用 K.walk_path，让角色在第 200 帧前走到 (0, 1)，步幅设置为冲刺步幅（1.3 m）；蓝色守卫是胶囊模型，在第 144 到 156 帧间走进通道；备份。
5. B.rail_camera("s1", [(0, 3, 1.5), (0, -1, 1.5), (0, -4, 1.5)], follow="FIG_red", target_offset=(0, 0, 1.2), lens=35)、 B.key_rail("RIG_dolly_s1", [(1, 0), (260, 1)])、B.bind_cuts([(1, "CAM_s1")])，手持抖动控制在预算范围内。
6. 执行 B.audit_frames(10, 24)、B.audit_cuts()、 B.audit_framing({"CAM_s1": ["FIG_red", "FIG_blue"]}, whole=True)、 B.audit_occlusion("FIG_red")、B.audit_handheld("CAM_s1")；移动货箱，直到画面达到要求。
7. 将 set_frame 设为 1、120、240，并分别调用 render_still，然后查看画面。备份，生成无头 playblast，并将 B.cut_list() 内容写入交接表。

常见错误和下游误读

• 身份信息不在几何形态中：漂浮的头部或板状手臂；人物附近松散的方块会被看成其他人；没有标明车头的汽车会被看成在倒车；不透明车厢后的乘客会消失（为车厢设置 alpha）。
• 镜头语法：剪辑帧上的关键帧会让画面中的动作定格；俯拍环绕会被看成剪辑；反向镜头中的座椅会左右镜像；对话中凭空出现反向镜头；最后几秒出现漂移。
• 动作含糊不清：缓慢的代理动作可能被看成在滚动，也可能被看成静止；应以说明表为准。
• 肢体复制：在参考视频模型中，逐帧移动或循环的腿部会显得僵硬、步调一致或滑动；将该角色改用胶囊体（角色阵容）。
• 细节脆弱：亚像素部件在不同风格重绘之间会改变身份；暗示有文字的风格会生成乱码。
• 开场帧虚构：“从门口开始”要求第 1 帧后方有门道；平坦地面上方的高机位镜头会显得很平。
• 状态漂移：渲染探测会导致分辨率或文件路径改变；将预先存在的对象当作自己的对象；Blender 5 中的槽式动作会隐藏 F 曲线（使用 B.fcurves）。