# 提示词:在 Windows 机器上部署 Blender MCP + skill

> 用法:把 `blender-mcp-bundle` 整个文件夹拷到 Windows 机器(例如 `C:\Users\<用户名>\blender-mcp-bundle\`),
> 然后把下面 **「给 MCode 的提示词」** 整段复制粘贴给那台机器上的 MCode。

---

## 给 MCode 的提示词(直接复制这一整段)

> 我要在**这台 Windows 机器**上部署 Blender 的 MCP 集成和配套 skill。
> 安装包已经放在本机:`C:\Users\<用户名>\blender-mcp-bundle\`(路径按实际存放位置替换)。
> 请按下面的步骤做,**先分析再动手**,每一步做完向我汇报,不要一次性闷头跑完。

### 第 1 步:环境体检(只读,不改任何东西)

先确认这台机器的现状,把结果整理成一张表报给我:

```powershell
cd C:\Users\<用户名>\blender-mcp-bundle
python install_blender_mcp.py --check
```

这个脚本会检查并汇报:Blender 是否安装及版本与路径、uv/uvx、Node.js、
`~\.minimax\mcp.json` 里有没有 blender 条目、skill 装没装、
Blender 的 add-on 文件在不在、startup 脚本在不在、9876 端口有没有被占用。

如果 `--check` 报错说找不到 Blender,先装 **Blender 5.1.x**(官网下载,
Windows 装完默认在 `C:\Program Files\Blender Foundation\Blender 5.1\blender.exe`),
装完重跑 `--check`。如果提示没有 uv/uvx,装一下:`winget install astral-sh.uv`。

### 第 2 步:安装

体检通过后执行(仍然**不要**启动 GUI 窗口):

```powershell
python install_blender_mcp.py --install
```

它会做四件事,每件都该有日志:

1. `uvx mcp-for-blender install-addon` 把 add-on 文件复制进 Blender 的用户 addons 目录
   (注意:这一步**只复制文件,不会启用**);
2. 用 **headless Blender** 跑一段脚本启用插件并 `save_userpref()`(不开 GUI 窗口);
3. 把 `enable_asset_libraries.py` 放进 Blender 的 `scripts\startup\`;
4. 把 `blender` skill 复制到 `~\.minimax\skills\blender\`(同时复制一份到 `~\.codex\skills\blender\`,
   这两个位置 MCode 都会读),并在 `~\.minimax\mcp.json` 里注册 blender MCP 服务器
   (`uvx blender-mcp`,stdio,timeout 60000);改之前会自动备份成 `mcp.json.bak-<时间戳>`。

### 第 3 步:启动与验证

1. 启动 Blender(可以让我来:`python install_blender_mcp.py --install --launch`,
   或者你自己双击)。插件会自动起桥接,监听 `127.0.0.1:9876`。
2. **重启 MCode 会话**,让新的 MCP 服务器生效(工具列表里应该出现 blender 的
   `get_addon_status` / `execute_blender_code` / `look` / `search_assets` / `import_asset` 等)。
3. 验证:调用 `get_addon_status`,应该看到
   `up_to_date: true`、`protocol_version: 13`、`addon_version: [1, 8]`、
   `libraries: { polyhaven: "on", sketchfab: "off", polypizza: "off" }`。
4. 再验证资产库开关是否持久:新开一个 Blender 文件后,`libraries.polyhaven` 仍应是 `on`
   (这一步能证明 startup 脚本生效了)。
5. 渲染管线冒烟测试(**必须 headless,不要在 GUI 里渲染**):

   ```powershell
   node ~\.minimax\skills\blender\scripts\blender-render.js --help
   ```

   以及一次真实出图:

   ```powershell
   node ~\..minimax\skills\blender\scripts\blender-render.js `
     --build studio --polyhaven studio_small_09 `
     --out-dir "$env:TEMP\blender_smoke" --angles three_quarter,front `
     --engine CYCLES --samples 32 --res 800x600
   ```

   跑完检查 `$env:TEMP\blender_smoke\render_report.json` 的 `ok` 字段是 `true`,
   并把 PNG 路径告诉我。

### 第 4 步:资产库 API key(可选)

Poly Pizza / Sketchfab 的 key 存在 Blender add-on 的偏好里
(`bpy.context.preferences.addons['blender_mcp'].preferences.polypizza_api_key`),
可以用参数直接写入:

```powershell
python install_blender_mcp.py --install --polypizza-key "<KEY>" --sketchfab-key "<TOKEN>"
```

**如果没有 key,不要卡住**——Poly Haven 是 CC0 且完全免 key,先用它验证整条链路即可。
key 的获取方式:
- Poly Pizza:`https://poly.pizza/settings/api` → 同意 API 条款 → Create New App → 复制 key(只显示一次)
- Sketchfab:`https://sketchfab.com/settings/password`(My Settings → Password & API,32 位 token)。
  注意 Sketchfab **新账号只能通过 Epic Games 注册**,邮箱表单只做登录。

---

## 这套东西的硬规则(请严格遵守)

1. **绝不在 GUI 里的 `execute_blender_code` 中调用 `bpy.ops.render.render()`。**
   add-on 是用 `bpy.app.timers` 回调在主线程 drain 命令队列的,渲染是阻塞式算子,
   跑在那个回调里会占死主事件循环:桥接对所有请求返回 `-32001` 超时,而 Blender 进程
   还活着、9876 端口也还开着,**看起来一切正常但每个调用都超时**。
   恢复:`taskkill /F /IM blender.exe`,再重新启动 Blender(插件会自动起桥接)。
   所有出图都走 `scripts/blender-render.js` 的 headless 进程。

2. **Blender 5.1 的几个反直觉点**:
   - 节点名是本地化的,`nodes.get("Principled BSDF")` 在中文界面返回 None,
     要用 `n.type == 'BSDF_PRINCIPLED'`;`BACKGROUND` / `TEX_ENVIRONMENT` / `OUTPUT_WORLD` 同理。
   - Cycles 是动态注册的,`RenderSettings.engine.enum_items` 里**看不到** CYCLES,
     这不代表没装,直接 `sc.render.engine = 'CYCLES'` 就行。
   - `bpy.app.timers` 和非 `@persistent` 的 handler 在**加载文件时会被清空**,
     所以 startup 脚本必须重新武装自己。
   - Blender 5.1 要求 startup 脚本提供 `register()` / `unregister()`,
     否则启动时会报 "has no register function"。

3. **add-on 的集成开关是 scene 属性**(`blendermcp_use_polyhaven` / `_polypizza` / `_sketchfab`),
   换文件就重置为 off。`enable_asset_libraries.py` 就是干这个的:
   它轮询等 add-on 注册完属性,再强制打开三个开关,并在每次加载文件后重新武装。
   如果 `get_addon_status` 报告某个库是 off,先查这个文件在不在,再重启 Blender。

4. **MCP 服务器注册在 `~\.minimax\mcp.json`**,key 名是 `mcpServers`。
   改它之前一定先备份(安装脚本已经自动备份了)。

5. **MCP 的 stdio 子进程会残留**。每调用一次 Blender MCP 工具就可能拉起一个
   `uvx blender-mcp` 进程,运行时不回收,跑久了会堆几百个白占内存。
   收工时用 `taskkill /F /IM blender.exe` 加上清理 `blender-mcp` 进程。

6. **不要在 GUI Blender 跑测试时去抢用户前台**。优先用 headless
   (`blender -b --python-expr ...`),确实需要窗口再提前说一声。

---

## 装完之后的日常用法

- 在 MCode 里用 `blender` skill:它带全套操作规则(桥接接线、渲染管线、资产库)。
- 渲染(任何时候都不要在 GUI 里渲):
  ```powershell
  node ~\..minimax\skills\blender\scripts\blender-render.js --blend scene.blend --out-dir out\ --angles front,three_quarter,side,top --engine CYCLES --samples 64 --res 1200x900
  ```
  Windows 下 Blender 路径用 `--blender "C:\Program Files\Blender Foundation\Blender 5.1\blender.exe"`,
  或设环境变量 `$env:BLENDER_BIN`。
- 改 skill 后跑一次 lint:
  ```powershell
  node ~\..minimax\.builtin-skills\skill-creator\scripts\lint-skill.js ~\..minimax\skills\blender
  ```
  (Windows 上内置 skill 的路径可能不同,用 `Get-ChildItem -Recurse -Filter lint-skill.js ~\.minimax` 找一下。)

---

## 交付清单

请在完成后给我一份简短报告,包含:

- [ ] 体检结果表(Blender 版本/路径、uv、Node、mcp.json 现状)
- [ ] 装了哪些东西(add-on 启用结果、startup 脚本、skill 两个位置、mcp.json 条目)
- [ ] `get_addon_status` 的完整返回
- [ ] 冒烟渲染的 `render_report.json` 里的 `ok` 与 PNG 路径
- [ ] 复现步骤(万一以后要重装)
- [ ] 遗留问题(比如 key 没配、Blender 版本不是 5.1 等)