polywright-blender 是做什麼的？
Blender 是主力工具：免費、支援所有作業系統、可腳本化到每個按鈕。代理最好以無頭模式驅動它，在副本上執行，並產生簡短的文字報告，而非透過即時畫面的螢幕截圖。 返回中心：../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 錯誤仍會以 exit 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所做的那樣）。 - 讀取 enum 項目而非猜測名稱：
m.bl_rna.properties["solver"].enum_items。 - 真實尺寸以公尺為單位；在測量前套用變換；glTF 匯入時會以四元數模式導入，並在一個父物體上進行軸向修正：先清除父物體並保留變換，然後套用，最後再測量。
- 將每個輸出路徑寫成絕對路徑（
os.path.abspath），並在之後列印檔案是否存在：相對路徑的render.filepath可能會回報成功但實際卻未寫入任何可見內容（L-004）。 - 在
work/中為每個里程碑儲存一個帶編號的.blend檔案；從該檔案重新啟動，而非維持一個長時間執行的即時工作階段。 - 在渲染之前先烘焙模擬，並將快取資料夾放在
.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；切片機有 CLI。版本與各作業系統的執行情況：references/tools-by-os.md。在 macOS 上，Blender 5.x 和 bpy wheel 僅支援 Apple Silicon；bpy wheel 需要恰好是 Blender 搭載的 Python 版本（5.2 為 3.13）。
維護
常青單元，層級 moderate（Blender 每四個月發行一次；每次發行時檢查）。伴隨檔案：RESEARCH.md、CHANGELOG.md、LEARNINGS.md、TESTS.md（內含 evals/evals.json）、MAINTENANCE.md、狀態位於 evergreen.json。每次使用時請讀取 evergreen.json；到期時重新整理。