Blender 控制技能（实时 GUI + 无头 CLI）

Blender 控制技能（实时 GUI + 无头 CLI） 是做什么的？

本工作区以两种互补模式控制 Blender 5.2.1 LTS（/Applications/Blender.app/Contents/MacOS/Blender、Python 3.13、Apple M1 Pro 16核 Metal GPU）：

1. 实时 GUI 模式（默认且首选）：通过 127.0.0.1:9876 向运行在打开的 Blender.app 窗口中的 blender_control_bridge.py 发送命令。对象、着色器、动画和相机取景会立即呈现在用户面前。
2. 无头 CLI 模式：运行 /Applications/Blender.app/Contents/MacOS/Blender --background 进行隔离的批量渲染或繁重后台作业，不影响活动的 GUI 会话。

在编写适用于 Blender 5.2 的 bpy 脚本之前，请查看 blender_5_2_api_guide.md 了解关键的 5.2 API 更改（Principled BSDF 插槽名称、Slotted Actions channelbag、media_type = 'VIDEO' 以及 Metal GPU 设置）。

---

第 1 步：验证或连接到打开的 Blender 应用程序

始终先验证实时桥接连接：

python3 .agents/skills/blender-control/scripts/blender_cli.py ping

如果 ping 失败（例如，Blender 尚未打开，或者在安装启动桥接之前已启动），请运行安装程序/连接脚本：

bash .agents/skills/blender-control/scripts/install_bridge.sh

• 将 blender_control_bridge.py 复制到 ~/Library/Application Support/Blender/5.2/scripts/startup/，以便每次 GUI 启动都会自动在 127.0.0.1:9876 上启动桥接。
• 安全地连接或启动 Blender.app（open -g -a Blender），不会抢夺窗口焦点。
• 如果 Blender.app 已打开一个未保存的 .blend 文件但桥接未加载，请要求用户点击 macOS 菜单栏中的 Blender -> 系统 -> 重新加载脚本。

---

第 2 步：通过 blender_cli.py 检查并控制实时场景

对所有实时操作使用 blender_cli.py：

# 1. 检查当前对象、相机、材质、帧范围和渲染引擎
python3 .agents/skills/blender-control/scripts/blender_cli.py info

# 2. 干净地清除实时场景（移除所有对象和孤立数据块）
python3 .agents/skills/blender-control/scripts/blender_cli.py reset

# 3. 在 Blender 的主 UI 线程上实时执行场景构建器 Python 脚本
python3 .agents/skills/blender-control/scripts/blender_cli.py run projects/my_scene/build.py

# 4. 执行快速内联 Python 表达式/代码片段
python3 .agents/skills/blender-control/scripts/blender_cli.py exec "RESULT = [o.name for o in bpy.data.objects]"

# 5. 将用户的实时 Blender 3D 视口切换到材质预览或渲染相机视图
python3 .agents/skills/blender-control/scripts/blender_cli.py viewport --shading MATERIAL

# 6. 在实时 GUI 中保存或打开 .blend 项目文件
python3 .agents/skills/blender-control/scripts/blender_cli.py save projects/my_scene/scene.blend
python3 .agents/skills/blender-control/scripts/blender_cli.py open projects/my_scene/scene.blend

---

第 3 步：渲染静态图像、视口预览和动画

快速视口预览 (<0.2s)

在运行完整的光线追踪渲染之前，先使用视口截图来验证相机取景、对象放置和裁剪：

python3 .agents/skills/blender-control/scripts/blender_cli.py screenshot /tmp/preview.png

使用 read_file 检查 /tmp/preview.png 以视觉确认构图和光照！

高质量静态图像渲染（Cycles Metal GPU 或 EEVEE）

# Cycles 搭配自动 Apple M1 Pro 16核 Metal GPU 加速
python3 .agents/skills/blender-control/scripts/blender_cli.py render projects/my_scene/render.png \
  --engine CYCLES --samples 64 --width 1920 --height 1080

# 使用 EEVEE 的快速实时 PBR 渲染
python3 .agents/skills/blender-control/scripts/blender_cli.py render projects/my_scene/render.png \
  --engine BLENDER_EEVEE --samples 32 --width 1920 --height 1080

MP4（H.264）动画渲染

python3 .agents/skills/blender-control/scripts/blender_cli.py render-anim projects/my_scene/animation.mp4 \
  --engine BLENDER_EEVEE --samples 32 --width 1280 --height 720 --start 1 --end 120 --fps 30

无头批处理模式（隔离进程）

当渲染繁重作业且不希望阻塞实时 GUI 视口时：

python3 .agents/skills/blender-control/scripts/blender_cli.py run projects/my_scene/build.py --headless

---

第 4 步：场景构建与验证清单

1. 自包含构建器脚本：将每个项目存储在 projects/<project_name>/build.py 中，这样场景可以 100% 重现，并与渲染输出和 .blend 文件一起友好地纳入 Git 管理。
2. 相机瞄准（TRACK_TO 或四元数）：始终使用 (target - cam.location).to_track_quat('-Z', 'Y') 将相机可靠地指向目标空物体或世界坐标，并设置 scene.camera = cam。
3. 三点/工作室照明和世界：切勿留下黑暗的默认灰色背景；配置世界着色器节点 + 区域光/太阳光，使用符合实际的瓦特数（根据场景比例在 100W–1500W 之间），并采用 AgX 或 Filmic 色彩管理（scene.view_settings.view_transform = 'AgX'，look = 'AgX - Medium High Contrast'）。
4. 视觉验证：在完成之前，务必使用 read_file 检查渲染的 .png 或 .mp4 输出，以确认构图、曝光、材质和运动。
5. GitHub 同步：创建或更新项目/技能后，运行 ./scripts/sync_github.sh "<提交信息>" 以保持本地和 origin/main 同步。