# Blender MCP + skill 部署包(给另一台 Windows 机器)

这个包把本机( macOS )已经跑通的 Blender MCP 集成,搬到另一台 Windows 机器上。
包含:**安装脚本 + 体检脚本 + skill 全文 + startup 脚本 + 给 MCode 的提示词**。

## 用法(3 步)

### 1. 拷贝到 Windows 机器

把整个 `blender-mcp-bundle` 文件夹拷过去,例如:

```
C:\Users\<用户名>\blender-mcp-bundle\
```

### 2. 在 Windows 机器上打开 MCode,把 `PROMPT.md` 里「给 MCode 的提示词」那一整段
复制粘贴给它。

它会先跑体检(`--check`,只读),把现状报给你;你确认后再跑 `--install` 安装。

### 3. 或者自己手动装(不想用 MCode 的话)

```powershell
cd C:\Users\<用户名>\blender-mcp-bundle
python install_blender_mcp.py --check        # 体检
python install_blender_mcp.py --install       # 安装
python install_blender_mcp.py --install --launch   # 装完顺便把 Blender 拉起来
```

## 包里有什么

| 文件 | 作用 |
|---|---|
| `PROMPT.md` | **给 MCode 的提示词**(主交付物) + 硬规则 + 验收清单 |
| `install_blender_mcp.py` | 跨平台体检 + 一键安装(Windows/macOS/Linux) |
| `skill/blender/SKILL.md` | skill 全文(操作规则、渲染管线、资产库、踩过的坑) |
| `skill/blender/scripts/blender-render.js` | headless 渲染管线(799 行) |
| `startup/enable_asset_libraries.py` | Blender startup 脚本,常开 polyhaven/polypizza/sketchfab |

## 安装脚本会做什么

1. `uvx mcp-for-blender install-addon` —— 把 add-on 文件复制进 Blender 用户 addons 目录
2. headless Blender 跑一段脚本**启用插件并保存 userpref**(不弹窗口)
3. `enable_asset_libraries.py` → Blender 的 `scripts\startup\`
4. skill → `%USERPROFILE%\.minimax\skills\blender\` 和 `%USERPROFILE%\.codex\skills\blender\`
5. `mcp.json` 注册 `blender` 服务器(`uvx blender-mcp`, stdio, timeout 60000),
   **改之前自动备份**成 `mcp.json.bak-<时间戳>`
6. 可选:`--polypizza-key` / `--sketchfab-key` 写进 add-on 偏好

## 前置依赖

| 依赖 | 用途 | Windows 安装方式 |
|---|---|---|
| Blender **5.1.x** | 被控对象 | 官网下载,默认装到 `C:\Program Files\Blender Foundation\Blender 5.1\` |
| uv / uvx | 跑 MCP 服务器和安装器 | `winget install astral-sh.uv` |
| Node.js | 只有渲染管线需要 | `winget install OpenJS.NodeJS.LTS` |
| Python 3 | 装这个包 | Blender 自带的也行,或 `winget install Python.Python.3.12` |

## 已知坑(都写进 PROMPT.md 了,让对面的 agent 别再踩)

- **绝不在 GUI 里渲染** —— 会静默占死桥接,表现为「进程和端口都正常但每个调用都超时」
- `install-addon` **只复制文件不启用插件**,启用要用 headless Blender 跑 `addon_enable` + `save_userpref`
- Blender 5.1 的 startup 脚本必须提供 `register()` / `unregister()`
- 节点名本地化,取 Principled BSDF 要用 `n.type` 而不是名字
- Cycles 动态注册,`engine.enum_items` 里看不到它不代表没装
- 加载文件会清空 timer 和非 persistent handler,startup 脚本要重新武装
- MCP 的 stdio 子进程会残留几百个,收工要单独清
- skill 里原本写死的 macOS 路径,在 Windows 上全部换成了 `%APPDATA%` / `%USERPROFILE%` 形式

## 许可与署名

- `skill/blender/SKILL.md`、`blender-render.js`、`enable_asset_libraries.py`:本机原创,随包带走即可。
- Poly Pizza / Sketchfab 的 API key 属于**账号**,同一把 key 在两台机器上都能用
  (本机那把存在 `blender_smoke/asset-library-credentials.txt`,没打进包里,需要时再给)。