Blender CLI Modeling

让智能体通过 Blender CLI、bpy 与可选 MCP 完成可复现、可验证的三维建模工作

An Agent Skill for Blender CLI automation, MCP interaction, and independent verification

中文 · English

中文说明

blender-cli-modeling 是一套面向智能体的 Blender 双通道工作流。它可以通过 Blender 自带的 Python 环境批量运行 bpy，也可以借助可选的 Blender MCP 连接，在已经打开的场景中观察、修改和继续迭代。

CLI 模式无需常驻服务或 Blender 插件，适合新建场景、无界面执行和最终验收。MCP 模式适合连续微调与实时视口反馈。无论使用哪种模式，生成的 .blend 文件和渲染结果都要经过独立验证。

它能做什么

• 使用 bpy 创建或修改 Blender 场景
• 在后台模式下渲染图片、动画或导出模型
• 通过可选 MCP 读取当前场景、对象信息和视口截图
• 在打开的 Blender 场景中进行小步修改和快速反馈
• 自动寻找常见 macOS Blender 安装位置
• 将 Python 异常正确传递为非零退出码
• 重新打开生成的 .blend 文件，检查对象、材质、灯光和相机
• 检查渲染文件是否存在、尺寸是否正确，并在需要时进行视觉复核

为什么使用这套工作流

Blender 自动化脚本即使正常退出，也可能留下错误的场景；MCP 视口截图看起来正确，也不能证明保存后的文件完整。这个 Skill 把交互效率和交付验证拆开：MCP 负责快速迭代，CLI 负责可复现执行和最终复查。

快速开始

Codex

git clone https://github.com/Wonham/blender-cli-modeling.git \
  ~/.codex/skills/blender-cli-modeling

重启 Codex，然后在任务中调用 $blender-cli-modeling。

其他智能体环境

将仓库克隆到智能体使用的 Skills 目录，并把仓库根目录注册为一个 Agent Skill。该环境需要能够读取根目录下的 SKILL.md，并允许执行本地 shell 脚本。

不同智能体平台的安装入口可能不同。本仓库提供通用的 Skill 指令与脚本，当前经过完整验证的集成环境是 Codex、macOS Apple Silicon 和 Blender 5.2 LTS。

可选的 Blender MCP

Blender MCP 不是使用本 Skill 的前置条件。已经安装并连接 MCP 时，Skill 会在连续微调、对象检查和实时视口反馈中优先使用它；新建大型场景、无界面任务及最终验收仍使用 CLI。

安装或升级前请阅读 references/blender-mcp.md，并以 ahujasid/blender-mcp 的当前文档为准。MCP 默认必须启用安全模式并关闭遥测：

BLENDER_MCP_SAFE_MODE=1
DISABLE_TELEMETRY=true

Skill 不会擅自安装插件、修改智能体配置、启用外部素材服务或保存 API 密钥。

CLI 调用方式

智能体会为具体任务编写独立的 bpy 脚本，再通过统一的包装器交给 Blender 执行：

SKILL_DIR="$HOME/.codex/skills/blender-cli-modeling"

"$SKILL_DIR/scripts/run_blender.sh" \
  --python /absolute/path/create_scene.py -- \
  /absolute/path/render.png \
  /absolute/path/scene.blend

如果 Blender 安装在非标准位置，可以显式指定可执行文件：

export BLENDER_CLI_BIN="/absolute/path/to/Blender.app/Contents/MacOS/Blender"

标准工作流

1. 检查输入文件和参考图，明确目标对象、不变量与输出路径。
2. 已打开场景的连续微调使用 MCP；批处理和无界面任务使用 CLI。
3. MCP 按“观察、修改、再观察”循环工作，并在风险操作前保存检查点。
4. CLI 使用最小化的任务脚本，并将非零退出码或 Python 异常视为失败。
5. 最终结果另存到明确路径，再用新的 Blender CLI 进程重新打开。
6. 核对对象、材质、相机和渲染设置；视觉结果重要时查看最终图片。

CLI 默认安全参数

包装器会自动加入以下 Blender 参数：

--background --factory-startup --disable-autoexec --python-exit-code 1

它们分别用于后台执行、隔离用户启动配置、禁止自动运行场景内脚本，以及让 Python 异常返回明确的失败状态。

环境要求

• 支持 SKILL.md 工作流的智能体环境
• macOS 与 zsh
• Blender
• 可选：支持本地 MCP Server 的智能体客户端与 Blender MCP 插件

当前验证环境为 macOS Apple Silicon 与 Blender 5.2 LTS。其他 Blender 版本或操作系统需要重新检查可执行文件路径、渲染引擎标识和命令行参数。

仓库结构

.
├── README.md
├── LICENSE
├── SKILL.md
├── agents/
│   └── openai.yaml
├── references/
│   ├── blender-5.2-macos.md
│   └── blender-mcp.md
└── scripts/
    ├── run_blender.sh
    └── smoke_scene.py

• SKILL.md 定义工作流、验证要求和常见问题处理方式。
• run_blender.sh 负责寻找 Blender 并使用安全参数启动它。
• smoke_scene.py 用于检查新安装或 Blender 版本变化，不作为真实项目模板。
• blender-5.2-macos.md 记录当前已验证环境的细节。
• blender-mcp.md 定义 MCP 的启用条件、安全边界、操作循环和 CLI 回退策略。

English

blender-cli-modeling is an Agent Skill for creating, editing, rendering, exporting, and verifying Blender scenes through the Blender CLI, bpy, and an optional Blender MCP connection.

CLI mode handles deterministic batch work, headless execution, and final verification. MCP mode provides low-latency inspection and iterative changes in an open Blender scene. MCP remains optional, and every deliverable still passes through a fresh-process CLI verification gate.

The repository follows the SKILL.md format and can be integrated with agent environments that support local skills and shell execution. Codex on macOS Apple Silicon with Blender 5.2 LTS is the currently verified setup. See the Blender MCP operating guide before enabling the optional integration.

License

MIT