scenario-blender-expert

Blender 专家（路由器和 Agent 协议）

Blender 专家级工作是一个循环，而不是一段脚本：先构建大型结构，再逐步处理细节；每个阶段都要旋转模型、测量并修正，然后再添加细节。这项技能是每个 Blender 任务都要遵循的协议，也是领域技能的索引图。这些技能提炼自 Blender Studio 艺术家、Blender Conference 演讲和顶尖讲师的经验（来源见各技能）。如果你可用的技能中缺少此处提到的同级技能，请让用户安装 （npx skills add scenario-labs/skills --skill <name>）；如果无人值守，则根据工具架构继续操作，并标明缺失的技能。

1. 执行通道

• 实时 GUI Blender（通过 MCP 桥接使用用户的会话），用于任何交互式操作：真实的雕刻／绘画笔刷、权重绘制、视口截图。每次调用只运行一个简短、幂等的脚本，并返回精简的结果字典。按名称获取或创建对象。绝不触碰你未创建的对象。每个阶段完成后，保存一个阶段备份：bpy.ops.wm.save_as_mainfile(filepath=..., copy=True)。
• 无头辅助程序 blender -b [file] --factory-startup --python-exit-code 1 -P x.py -- args，用于渲染、审查、批量操作，以及任何没有桥接服务的情况。使用 --factory-startup，避免用户的插件和偏好设置影响运行（插件可能调用网络或更改默认值）；但 Scenario Blender Plugin 的无头服务 blender --background scene.blend --command scenario_blender 除外，因为它需要加载该扩展。不加 --python-exit-code 时，即使脚本失败，进程仍会以 0 退出。打印一行最终的机器可读结果。

绝不要在用户的机器上打开自己的 GUI Blender 窗口来测试：窗口会抢占焦点，还会越开越多。实时操作通过用户已经运行的 Blender 进行；其他操作则在无头模式下运行，每个 Agent 同一时间只运行一个 Blender 进程（同一台机器上的其他会话可能正在渲染）。

实时通道：Scenario Blender Plugin。 用户的 Blender 运行 Scenario Blender Plugin 时，其本地 MCP 服务 scenario-blender 就是桥接服务。设置、报价、生成和放置结果由 scenario-blender 技能负责；本节介绍 bpy 侧的操作（指南见 blender.scenario.com）。它的工具名称不同于其他 Blender MCP 服务：没有 execute_blender_code、get_scene_info、get_viewport_screenshot 或 import_asset。

步骤	插件工具和主要参数
操作前读取场景	scene_summary，然后对单个对象调用 object_detail 并传入 name，再调用 datablocks_summary 获取数量
编写脚本前检查 API	调用 blender_api_help 并传入 path，例如 bpy.types.BevelModifier
运行 bpy	调用 execute_python 并传入 code；已预加载 bpy 和 result = {}，因此请填写 result
查看	screenshot_viewport（带叠加层的视口）、render_still 并传入 source（CAMERA 或 VIEWPORT）、width 和 height；两者都需要 GUI
选择、移动时间线	调用 select_objects 并传入 names（列表），调用 set_frame 并传入 frame

首次调用每个工具前，请先从服务端读取其输入架构：这是可选参数的参考。

• execute_python 在用户于插件偏好设置中启用 Allow connected agents to run Python 之前始终处于关闭状态。出现 PermissionError 时，请请求用户启用该选项，或仅使用特定工具。拼写被拒绝（退出、恢复出厂设置、删除文件）不会造成任何更改：请重写调用。
• 为每次调用控制好时间：插件会在 120 s 后停止调用，有些 Agent 客户端会在 60 s 后停止等待。每次调用只做一项逻辑更改，以便一次撤销即可还原；烘焙、在高密度网格上运行 QuadriFlow、转台动画、视口预览和最终渲染，都交给在已保存副本上运行的无头 Blender 处理。
• 调用超时意味着结果未知：重试前重新读取场景，切勿盲目重发。
• 插件的工具绝不会保存用户自己的文件。实时通道的阶段性备份（通过 execute_python 调用 save_as_mainfile(..., copy=True)）会写入单独的文件，不会影响已打开文件及其未保存状态；它也是无头处理的起始保存副本。在关键节点请用户保存自己的文件；如果无法询问用户，请继续使用副本，并在报告中说明已打开的文件仍未保存。

先检查 bpy.app.version；这套技能适用于 5.2 LTS，而 Scenario Blender Plugin 也支持 5.0 和 5.1（scene_summary 会报告版本），因此使用较新的 API 前，请先查看差异中的版本时间线。专家录制的许多教程使用 2.8x 到 4.2 的界面：在依赖记忆中的任何操作符、笔刷名称或 API 之前，请阅读 references/blender-5.2-deltas.md。

已验证的功能矩阵（Blender 5.2.1）：

操作	无头	GUI 会话
体素重构网格、QuadriFlow、多级精度细分、修改器、bmesh、带编辑模式上下文的 UV 操作、Cycles/EEVEE/Workbench 渲染、烘焙	是	是
bpy.ops.brush.asset_activate、动态拓扑开关	是	是
笔刷笔触（sculpt.brush_stroke、paint.image_paint、paint.weight_paint）	否（轮询失败）	是，通过 scripts/bx_gui.py
paint.mask_flood_fill、sculpt.mesh_filter	会导致 Blender 崩溃	是，通过 bx_gui.run()
对网格数据进行程序化雕刻	是，scenario-blender-sculpting/scripts/bx_sculpt.py	是

2. 专家工作循环（适用于所有领域）

1. 以数字明确任务要求：用途（电影、游戏引擎、静帧、动画）、预算（三角面数、纹理尺寸、帧范围）、风格（风格化或写实）和参考资料。如果任务要求中没有说明，就从该领域技能中选择有文档记录的默认值，并写下来。
2. 规划该领域技能定义的各个阶段。切勿从细节着手。
3. 构建一个阶段，并使用能完成该任务的最精简脚本。
4. 检查阶段成果：运行可量化的检查（网格使用 scripts/bx_audit.py，其他情况使用该领域自己的检查），并生成审核图表（scripts/bx_review.py：从正面、侧面、四分之三角度和低角度查看轮廓、材质球和线框），然后用图像读取器打开。专家会不断环绕查看；审核图表就是 Agent 的环绕视图。读取的每张图像都会保留在 Agent 的上下文中：快速查看时，使用 render_still，宽度约为 768 px，或使用 screenshot_viewport；审核图表保持在约 1600 px（四个视角、三种模式时使用 res=400）。依据该领域的 references/critique.md 进行评判。
5. 修复问题后再继续。在灰盒阶段发现的问题只需修改一个脚本；纹理制作后才发现则需要重做整个阶段。
6. 提供交付证据：在导出或移交前，对资产的各个部分运行交付检查（下文的 bx_audit.deliverable），并修复所有错误。然后报告最终渲染结果、检查关卡和审计数值，以及未经验证的内容。

未查看过模型、绑定、动画或渲染结果的图像，切勿报告其已完成。

3. Persona 工作流

Persona / 简介	技能链	交付成果
角色艺术家，风格化或写实风格	scenario-blender-sculpting, scenario-blender-retopology, scenario-blender-uv-baking, scenario-blender-texturing-shading, scenario-blender-hair	雕刻模型、适合动画制作的低多边形模型、UV、烘焙贴图、材质
AI 网格模型精修师（将 Scenario 3D 输出用于制作）	验收生成的资产、scenario-blender-retopology（或清理 + 重建网格）、scenario-blender-uv-baking（从生成的高模烘焙）、scenario-blender-texturing-shading；生成本身：scenario-3d	达到指定预算的干净、带 UV、已烘焙资产
游戏资产艺术家	scenario-blender-hard-surface 或 scenario-blender-sculpting, scenario-blender-retopology（游戏预算）, scenario-blender-uv-baking, scenario-blender-texturing-shading, scenario-blender-export	低多边形模型 + PBR 贴图集，导出为 glTF/FBX
绑定师 / 角色技术总监	scenario-blender-rigging	带控制器的骨架绑定、权重、变形测试
动画师	scenario-blender-previs-storyboard（镜头规划）, scenario-blender-animation	完成 Blocking、曲线调整和润色的镜头 + 播放预览
故事 / 预演艺术家	scenario-blender-previs-storyboard, scenario-blender-grease-pencil	镜头、摄像机、动态分镜
视觉开发与灯光艺术家	scenario-blender-texturing-shading, scenario-blender-lighting-rendering	完成布光、色彩管理和合成的渲染图
技术美术 / 程序化制作	scenario-blender-geometry-nodes	节点组资产、程序化系统
2D / 2.5D 动画师	scenario-blender-grease-pencil	GP 动画

本集合之外的相关技能：scenario-3d（生成网格后在此处完成精修）、scenario-textures（AI 贴图）。

4. 共享工具包（scripts/，均已在 5.2.1 上测试）

• bx_audit.py：audit(obj, high=None) 返回四边面百分比、N 边形、极点（价数为 3 / 5+ / 6+）、非流形、游离几何、重复几何、翻转面、自相交、边界环、对称百分比、边长变异系数，以及与高模的保真度；verdict(report) 列出问题。命令行用法： blender -b f.blend --python bx_audit.py -- --object Name [--high Sculpt] [--json out.json]。
• bx_audit.deliverable(objs, profile="game")：交付检查门禁。audit 评估拓扑；此函数评估引擎、渲染器或切片软件最终接收的内容，检查单个资产的各个部件：
  • 所有配置都视为错误的情况：应用修改器后没有面的网格、悬浮部件和碎片、封闭部件内外翻转、负缩放；除 print 外，各处部件之间的 Z-fighting；
  • 按配置检查（game、render、print、roblox）：未应用的缩放、指向部件内部的面（占其表面积 0.1% 起为错误，低于此值为警告，但 print 除外）、重复面、使用图像纹理但没有 UV 贴图、print 和 roblox 的开放边界、print 中部件之间的任何间隙、Roblox 20,000 个三角形的网格上限（于 2026-10-18 检查）。
  • 返回 {pass, errors, warnings, per_object}。容差按资产对角线缩放。检查前会焊接 glTF 导入产生的 UV 缝拆分，因此接缝不会被误判为孔洞。
  • 分别逐个检查独立道具：除最大的道具外，其余都会被判定为悬浮。
  • 命令行用法，失败时退出码为 2： blender -b --factory-startup --python-exit-code 1 -P bx_audit.py -- --deliverable [--import model.glb | --objects A B] --profile game [--json out.json]。
  • 修复方法：应用缩放（obj.data.transform(Matrix.Diagonal(obj.scale).to_4x4())，然后设置 obj.scale = (1, 1, 1)；如果提示的缩放位于父对象上，则选择父对象及其子对象，运行 bpy.ops.object.transform_apply(scale=True)）、对内外翻转的部件运行 bmesh.ops.recalc_face_normals、对指向内部的面运行 bmesh.ops.reverse_faces（per_object[name]["inward_faces_at"]）、删除或偏移 Z-fighting 面对中的隐藏面、合并或移动悬浮部件、删除碎片。
  • 引擎会剔除背面：若要查看实际绘制效果，请渲染 bx_review.review(parts, out, culling=True)（洋红色会透过指向内部的面显示），并与不启用剔除的渲染结果进行比较。
• bx_review.py：review(objs, out_dir, views, modes, culling=False) 接受对象或名称，并在临时场景中生成一张联系表（行 = 模式，列 = 视图），不会改动用户设置；playblast(out_path, res_pct=50)；turntable(obj, out_path, frames=72, res=720)。只有 review 支持命令行：其他函数请通过简短的包装脚本调用。
• bx_gui.py：在实时会话中使用真实笔刷：set_view、activate_brush(mode, name)、stroke(mode, world_points, size, strength)、run(op, **kw)、set_paint_color、screenshot。

导入方式：import sys; sys.path.append("<this skill>/scripts"); import bx_audit, bx_review。 将 <this skill> 替换为已安装技能文件夹的绝对路径：Blender 的 Python 与 Agent 的工作目录并不共用同一目录；通过实时桥接时，代码会在用户的 Blender 内运行。请在首次调用时检查路径（result["ok"] = os.path.isdir(path)），并在技能更新后对模块调用 importlib.reload。

5. 会让大多数记忆中的代码失效的版本陷阱

• 笔刷是资产（4.3）： bpy.ops.brush.asset_activate(asset_library_type='ESSENTIALS', asset_library_identifier="", relative_asset_identifier="brushes/essentials_brushes-mesh_sculpt.blend/Brush/Clay Strips")； 笔刷大小指直径（5.0）；Flatten、Fill 和 Scrape 已合并到 Plane 类型。
• Auto Smooth 已移除（4.1）：mesh.shade_smooth() / Smooth by Angle 修改器；体素重构网格的输出默认采用平面着色，直到调用 shade_smooth()。
• Principled BSDF v2（4.0）：按名称访问插槽；Emission strength 默认为 0。
• 在 5.x 中，BLENDER_EEVEE 是 EEVEE Next 的标识符（BLENDER_EEVEE_NEXT 会失败）。
• 合成器是一个节点组（5.0）：使用 scene.compositing_node_group，而非 scene.node_tree。
• 视频输出：先将 image_settings.media_type = 'VIDEO'，再设置 file_format = 'FFMPEG'（5.0）。
• 动作槽（4.4）中，action.fcurves 已移除（5.0）：使用 bpy_extras.anim_utils.action_get_channelbag_for_slot(action, slot)。
• 骨骼集合取代骨架图层（4.0）；Grease Pencil v3 的标识符为 GREASEPENCIL，使用 bpy.ops.grease_pencil.*（4.3）。
• 运算符不再支持位置参数形式的上下文字典：使用 with bpy.context.temp_override(...)。
• 设置位置或缩放后，obj.matrix_world 会立即变为过期值，直到调用 view_layer.update()。

参考资料

• references/bpy-reliability.md：包含可靠使用 bpy 的检查清单和经过测试的流程（运算符与数据 API、过期引用、求值数据与原始数据、幂等无头任务、numpy 批量访问、节点树、持久化）。编写任何非简单脚本前请先加载。
• references/blender-5.2-deltas.md：按领域列出从 2.8x 到 5.2 的完整变更，并附有引用（根据记忆编写代码或参照旧教程前请先加载）。