polywright-blender 是做什么的？
Blender 是主力工具：免费、支持所有操作系统、可脚本化到最后一个按钮。AI代理最适合以无头方式运行，在副本上操作，生成简短的文本报告，而不是通过截取实时会话的屏幕截图。
返回中心：../polywright/SKILL.md。 深入阅读：references/bpy-api-traps.md、references/bpy-recipes.md、 references/bpy-recipes-scenes.md 和 references/bpy-recipes-physics.md （每个配方都由测试套件运行）、 references/mcp-bridges.md、 references/tools-by-os.md。
步骤 1：确定Blender版本
python ../polywright/scripts/pw.py doctor 会找到它（通过 POLYWRIGHT_BLENDER、PATH、Windows、macOS 和 Linux 上的安装文件夹）并打印版本。目标是当前的 LTS 版本（5.2，支持到2028年7月）。将版本号写入脚本的第一个注释中；以下API事实针对5.2版本。
步骤 2：无头运行脚本
python ../polywright/scripts/pw.py bpy build.py [--blend in.blend] [--timeout 1800] -- <script args>
pw.py 自身的选项可以放在脚本名称之前或之后；-- 之后的所有内容都会传递给脚本。
它执行 blender --background --factory-startup --python-exit-code 3 --python build.py -- args，去除
Blender 的日志噪音，并返回 ok、脚本自身的输出行和回溯信息。如果没有
--python-exit-code，Blender 内部的 Python 错误仍然会以退出码 0 结束：切勿仅凭退出码判断成功与否。
为你需要的数值（尺寸、计数、检查）打印你自己的 [pw] 行。
脚本规则：
- 从
bpy.ops.wm.read_factory_settings(use_empty=True)或一个显式的.blend文件开始；永远不要依赖用户的启动文件。 - 优先使用
bpy.data和bmesh而不是bpy.ops。当必须使用操作符时，先设置活动对象和选择集，或使用with bpy.context.temp_override(...)。 - 视口操作符在无头模式下会失败（
view3d.*、screen.screenshot、render.opengl）：自行通过边界框设置摄像机（如pw.py render所做的那样）。 - 通过枚举项来读取而非猜测名称：
m.bl_rna.properties["solver"].enum_items。 - 真实尺寸以米为单位；在测量前应用变换；glTF 导入时，轴修正会放在父级上，对象以四元数模式导入：清除父级并保持变换，然后应用，最后测量。
- 将每个输出路径写为绝对路径（
os.path.abspath），并在之后打印文件是否存在：相对路径render.filepath报告成功但什么也没写出来（L-004）。 - 在每个里程碑处将带编号的
.blend文件保存到work/目录；从中重新启动，而不是维持长时间的实时会话。 - 在渲染之前烘焙模拟，确保缓存文件夹与
.blend文件相邻（默认是临时的，退出后会丢失）。烘焙进度会淹没标准输出，而pw.py bpy会截断中间部分：将结果写入 JSON 文件。 - 遇到回溯时重试两次；然后查阅 API（陷阱文件、内省、官方 MCP 的文档搜索），而不是第三次猜测。
步骤 3：陷阱（简短列表；完整列表见陷阱文件）
| 旧写法 | 5.x 中的用法 |
|---|---|
bpy.ops.import_scene.obj、import_mesh.stl、import_mesh.ply、wm.collada_* | wm.obj_import、wm.stl_import、wm.ply_import；Collada 已移除 |
BLENDER_EEVEE_NEXT | BLENDER_EEVEE |
import bgl | gpu 模块 |
Principled Specular、Subsurface、Transmission、Emission、Clearcoat | Specular IOR Level、Subsurface Weight、Transmission Weight、Emission Color、Coat Weight |
action.fcurves | 槽位动作：层、条带、通道袋 |
几何节点上的 mod["Socket_2"] = x | mod.properties.inputs.Socket_2.value = x |
import_image.to_plane | image.import_as_mesh_planes |
Workbench shading.show_shadow | shading.show_shadows |
obj.select = True、scene.objects.active、mesh.use_auto_smooth、scene.node_tree（2.7x 书籍） | select_set、view_layer.objects.active、shade_auto_smooth 或 set_sharp_from_angle、scene.compositing_node_group |
transform_apply(scale=True) 单独使用 | 同时会应用位置和旋转：传入 location=False, rotation=False |
步骤 4：常见任务
pw.py 已经支持检查、渲染、转换、LOD、可打印对象和联合操作。对于其他任务，从 references/bpy-recipes.md 中选取配方：按比例参考图像、修饰符及应用、使用 Manifold 求解器并回退到 EXACT 的布尔运算、体素重网格、QuadriFlow、智能 UV 和光照贴图 UV、从高模到低模的法线和 AO 烘焙、带有 5.x 插槽的材质、转台静帧、用于视频的深度和法线通道、按引擎导出，以及根据文字描述设计道具（车削、扫掠、镜像；L-003）。场景：references/bpy-recipes-scenes.md：几何节点散布、反深度、遮罩、一次渲染中的雾和法线、通过材质覆盖的粘土效果、线条艺术、通过 Blender 自带的 FFmpeg 输出 MP4。物理和绑定：references/bpy-recipes-physics.md：刚体和布料烘焙、为什么 Rigify 绑定不是游戏骨骼、手动绑定到骨架、体积重网格。父子关系、F-修改器动画和驱动器：references/bpy-recipes-motion.md。包含镜像零件的模型图纸：将侧摄像机抬高 10 到 15 度，否则一个零件会遮挡另一个（L-005）。
步骤 5：实时会话（MCP）
存在两个服务器：Blender Lab 的官方 MCP（v1.0.3，Blender 5.1+，场景分析和 API 文档搜索）和社区版的 mcp-for-blender（原名 blender-mcp；资源搜索和生成器钩子）。两者都运行模型发送的任何 Python 代码，没有沙箱，端口为 9876。使用其中一个，切勿同时使用两个；仅当用户正在观看 Blender 并希望进行实时编辑时才使用；切勿将从下载文件中粘贴文本到其代码中。设置和故障模式：references/mcp-bridges.md。在实时会话中，将编辑器绑定的操作符包装在 context.temp_override(window=w, area=a, region=r) 中；模态操作符和 bpy.app.timers 只能在那里运行，在 -b 下永远无法运行。
其他工具
无需 Blender 的网格检查和修复：trimesh + manifold3d（+ PyMeshLab）；网络传输：gltf-transform 或 gltfpack；实体建模：OpenSCAD、build123d、CadQuery、FreeCAD；切片器有命令行接口。版本信息以及在哪些操作系统上运行：references/tools-by-os.md。在 macOS 上，Blender 5.x 和 bpy wheel 仅适用于 Apple Silicon；bpy wheel 需要与 Blender 捆绑的 Python 版本完全一致（5.2 版本为 Python 3.13）。
维护
常青单元，等级为 moderate（每四个月发布一次 Blender 版本；每次发布时检查）。配套文件：RESEARCH.md、CHANGELOG.md、LEARNINGS.md、TESTS.md
包含 evals/evals.json、MAINTENANCE.md、状态存于 evergreen.json。每次使用时读取 evergreen.json；到期时刷新。