blender-core

Blender Core（5.2 LTS+）

路由到专用技能

任务	技能
单位、集合、命名、链接、资产库	blender-scene-setup
硬表面建模、倒角、布尔、法线	blender-hardsurface-modeling
雕刻、多分辨率、重构网格	blender-sculpting
拓扑重构、UV 展开、纹素密度	blender-retopology-uv
PBR 材质、色彩空间、纹理集	blender-pbr-materials
烘焙高模→低模贴图（法线、AO、曲率等）	blender-texture-baking
Geometry Nodes、程序化建模	blender-geometry-nodes
身体绑定、Rigify、权重绘制	blender-character-rigging
面部绑定、形态键、ARKit、viseme	blender-facial-shapekeys
关键帧、动作、NLA、烘焙、根运动	blender-animation
多边形预算、LOD、绘制调用、清理	blender-game-optimization
导出：将 glTF/FBX/USD 导出到 Roblox、Unity、Unreal、Godot、web	blender-export-pipelines
Cycles/EEVEE 设置、合成器、批量渲染	blender-rendering
灯光、HDRI、摄像机、转台	blender-lighting-lookdev
一天中的时间、夜晚、日落、雾、氛围（赛博朋克、恐怖等）	blender-time-of-day
雨、雪、潮湿表面、水坑、闪电、灰尘/余烬	blender-weather-fx
布料、刚体、流体、头发、GN 物理	blender-simulation
编写插件/扩展	blender-addon-development
批处理/无头流程、文件转换	blender-pipeline-automation
交付前检查网格/资产（始终执行）	blender-asset-qa
端到端操作指南（道具、角色、Roblox、产品镜头）	blender-workflow-recipes

执行

实时（blender-mcp execute_blender_code）：分小步操作，只打印所需内容。调用技能脚本时，导入它：

import sys, importlib; sys.path.insert(0, r"<skills_dir>/blender-asset-qa/scripts")
import qa_check; importlib.reload(qa_check); print(qa_check.run(objects=["Chair"]))

每次 MCP 调用都会在全新的命名空间中运行：每次调用都要重新 import。这开销很小，因为模块会缓存在 sys.modules 中。只有在编辑脚本后才使用 reload。 无头模式（任何带 shell 的 Agent）：只打印脚本的 JSON（@@JSON@@ 行）：

python <skills_dir>/blender-core/scripts/run_in_blender.py --blend in.blend <script.py> -- --objects Chair --save out.blend
python <skills_dir>/blender-core/scripts/run_in_blender.py --expr "import bpy; print(len(bpy.data.objects))"

原始形式：blender -b in.blend --factory-startup --python-exit-code 1 -P x.py -- args。此处的每个脚本都提供 run(**kw) -> dict，并支持 -- 后的相同标志。 会话中的首次调用：scripts/env_report.py，它会返回版本、引擎、GPU、插件、单位、色彩管理和场景计数。

规则

• 优先使用数据 API，而非运算符：使用 bpy.data、bmesh、mesh.attributes 和配合 numpy 的 foreach_get/set。运算符依赖上下文和选择状态，而且很多运算符需要 3D 视图，而后台模式没有 3D 视图。
• 如果无法避免使用运算符：with bpy.context.temp_override(object=ob, active_object=ob, selected_objects=[ob], selected_editable_objects=[ob]): bpy.ops...。检查结果是否为 {'FINISHED'}。
• 隔离编辑模式：处于编辑模式时，ob.data 不会更新。使用 bmesh.from_edit_mesh + bmesh.update_edit_mesh，或者在读取前切换到 OBJECT 模式。
• 节点：通过 type 查找节点（n.type == "BSDF_PRINCIPLED"），绝不要通过 name 查找，因为名称会本地化。Socket 可以使用英文名称或 identifier。
• 枚举：使用 [i.identifier for i in T.bl_rna.properties[p].enum_items] 读取有效值。动态枚举（render.engine、view_transform、look）报告的值不完整，因此应在 try/except TypeError 中赋值（错误消息会列出有效值）。
• 引擎：BLENDER_EEVEE、CYCLES、BLENDER_WORKBENCH。Cycles 设备：scene.cycles.device = "GPU" + 首选项 compute_device_type。
• 求值后的数据：使用 ob.evaluated_get(depsgraph)，然后调用 .to_mesh()，最后务必调用 .to_mesh_clear()。修改后读取 matrix_world 前，先调用 view_layer.update()。
• 已释放的数据：应用或移除修改器，或移除对象或 ID，都会释放数据。先收集名称（[m.name for m in ob.modifiers]），之后绝不要再访问旧的 Python 引用，因为它会返回垃圾数据或导致崩溃。
• 绝不要相信默认名称（"Cube.001"）。保留对象引用，明确重命名，并通过 bpy.data.objects[name] 查找对象。
• 缩放：1 个单位 = 1 m。倒角、带距离参数的修改器、绑定、物理模拟、烘焙和导出之前，先应用旋转/缩放（transform_apply）。
• 路径：bpy.path.abspath("//textures/x.png") 会将路径解析为相对于 .blend 文件的路径。明确保存；使用 save_as_mainfile(filepath=..., copy=True) 创建备份。
• 实时会话中的内容属于用户：绝不要调用 read_factory_settings，绝不要删除自己未创建的数据，并在进行破坏性批量编辑前保存备份副本。
• 后台模式中的 GPU 模块：先调用 gpu.init()（5.2+）。bgl 已不再存在。
• 大型网格：不要逐顶点调用 bpy.ops。使用 numpy foreach_get（参见 references/bpy-patterns.md）。

会导致旧教程/LLM 记忆失效的 5.x API 变更

action.fcurves → channelbags · scene.node_tree → scene.compositing_node_group · material.use_nodes 已弃用（新材质已默认带有节点）· mod["Socket_2"] → mod.properties.inputs.Socket_2.value（5.2）· BLENDER_EEVEE_NEXT → BLENDER_EEVEE · 布尔值 FAST → FLOAT · 骨骼层 → 骨骼集合 · bl_info 插件 → 扩展（blender_manifest.toml）· bpy.props 的值不再支持字典访问（scene["cycles"]）。完整表格：references/api-changes-5x.md。

验证（声称“完成”前必须执行）

1. 报告数字，而非形容词：三角面数、对象数、材质数、尺寸（ob.dimensions）以及写入的输出文件。
2. 几何发生变化 → 运行 blender-asset-qa qa_check.py（检查 z-fighting、部件脱离、非流形、法线翻转和缩放）。
3. 查看效果：使用 MCP look（mode="angles"，着色方式为 material/wireframe）。无头模式：blender-asset-qa/scripts/review_shots.py 会渲染联系表。
4. 重新检查自己的输出：确认导出的文件存在且大小非零。

参考

• references/api-changes-5x.md：4.x→5.2 迁移表。代码出现 AttributeError/KeyError 时加载此表。
• references/bpy-patterns.md：经过验证的 bmesh、属性、numpy、temp_override、depsgraph、驱动器、追加/链接、处理程序和计时器代码片段。