> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Blender Bridge

> blender-bridge — 通过 MCP 把 Profy 接到本机 Blender：场景检查、视口截图、bpy 脚本、GLB 导出

# Blender Bridge

把 Profy 接到你本机正在运行的 Blender，让专家能检查场景图、执行 Python（bpy）、截视口图验证效果、导出 GLB。

这与 Profy 云端的 3D 能力是两条正交路线：`profy-visualize` / `profy-game-studio` 在沙箱里用 Three.js 造**网页可运行**的 3D；Blender Bridge 操作的是你桌面上那个真实的 `.blend` 文件。

<Warning>
  **当前实现状态（核对于 2026-08-11）**：本插件的 `mcpServers` 声明（`uvx blender-mcp`）在代码库中**没有任何消费方**——agent-runtime 的 `PluginManifest.mcp_servers` 字段被解析但从未被读取，Core 侧的 MCP 装配只处理社区插件安装（`buildCommunityMcpToolsAndConfig`），不覆盖内置 manifest。

  也就是说：勾选本插件后，你会得到它的**技能与提示词**（下面的工作流纪律、安全规则、导出参数都会生效并影响模型行为），但**不会得到可调用的 Blender 工具**。把它当作「Blender 协作方法论」而不是「远程遥控器」，直到接线补齐。
</Warning>

## 声明与激活

```json theme={null}
{
  "id": "blender-bridge",
  "name": "Blender Bridge",
  "version": "1.0.0",
  "mcpServers": [{ "name": "blender", "command": "uvx", "args": ["blender-mcp"] }],
  "activation": { "requires": { "desktop_connected": true }, "user_selectable": true }
}
```

两道门必须同时通过：

| 门                                  | 判定                                                           | 不满足时            |
| ---------------------------------- | ------------------------------------------------------------ | --------------- |
| `user_selectable: true`            | 插件 ID 必须出现在本次对话勾选的插件里                                        | 整个 manifest 被跳过 |
| `requires.desktop_connected: true` | 运行时 `desktop_connected` 为真，即 `PROFY_DESKTOP` 环境变量等于 `"true"` | 整个 manifest 被跳过 |

第二道门意味着**它只在 Profy Desktop 里存在**。云端网页对话勾不到、也激活不了——因为要操作的 Blender 在你的机器上，云端沙箱够不着。

## 环境前置

| 要求                   | 说明                       |
| -------------------- | ------------------------ |
| Blender 4.x 或更高      | 需处于运行状态，不是被动读文件          |
| BlenderMCP addon 已启用 | 由它在 Blender 内暴露 MCP 端点   |
| Python `uv` 已安装      | `uvx` 用于拉起 `blender-mcp` |
| Profy Desktop        | 云端不可用，见上文激活条件            |

`marketplace.installMode` 为 `ON_INSTALL`，即安装时就完成准备，不是首次调用时才装。

## 工作流纪律（技能层，当前即生效）

插件带的 `blender-workflow` 技能规定了模型的操作节奏。核心是**每步都要看**：

```
1. 检查当前场景 → 搞清楚已经有什么
2. 把改动拆成小步
3. 一次只执行一个操作
4. 每步之后截视口图 → 肉眼验证
5. 不对就撤销重来
6. 满意了再保存，需要时导出
```

### Vision in the Loop

技能里写死了一条硬规则：**每一次建模操作之后都要截图**，然后自问形状对不对、位置对不对、材质有没有生效；有问题先修再往下走。

> 永远不要假设某个操作成功了——一定要视觉确认。

这条纪律的价值不依赖 MCP 接线：它约束的是模型在任何 3D 任务里的自我验证习惯。

## 能力清单（MCP 接线补齐后可用）

| 类别   | 内容                                   |
| ---- | ------------------------------------ |
| 场景检查 | 物体列表、变换、材质、灯光                        |
| 物体创建 | 网格基本体、曲线、空物体                         |
| 建模   | 修改器：细分、布尔、阵列、镜像                      |
| 材质   | PBR 金属度-粗糙度工作流（基础色/金属度/粗糙度/法线）       |
| 灯光   | HDRI 环境、面光/点光/聚光                     |
| 脚本   | 执行任意 bpy Python                      |
| 导出   | GLB / FBX / OBJ                      |
| 资产库  | Poly Haven（HDRI、贴图、模型）、Hyper3D Rodin |

## Web 导出参数

给网页用的模型有明确参数，不是「随便导一下」：

| 项  | 取值                  | 原因            |
| -- | ------------------- | ------------- |
| 格式 | GLB（二进制 glTF）       | 单文件，浏览器原生支持   |
| 压缩 | 开启 Draco            | 几何体体积大幅下降     |
| 贴图 | 内嵌，最大 2048×2048     | 超过这个尺寸移动端得不偿失 |
| 变换 | 导出前 Apply           | 否则下游拿到的变换是错的  |
| 验证 | 导出后在 Three.js 里打开确认 | 导出成功 ≠ 加载正常   |

完整链路是：Blender 建模 → 优化（减面、烘焙贴图）→ 导出 GLB → 在 Profy 的 `visualize` / `game-studio` 里加载 → 通过 Sites 发布。

## 安全规则

技能里的四条硬约束，模型会遵守：

* 不经询问不覆盖文件——新版本一律「另存为」
* 不经确认不删除物体
* 不修改项目目录之外的文件
* 在副本上作业，不动原始文件

## 边界与失败态

* **没有 Desktop 就没有这个插件**。云端对话里它不出现在插件面板，不是 bug。
* **Blender 没开 = 前置检查就失败**。技能要求先调一次场景检查确认连通，连不上应立刻停下报错，而不是继续「假装在建模」。
* **MCP 声明当前未接线**（见页头警告），所以「模型说要截图但没有截图工具」是当前的预期行为，不是模型偷懒。
* **多边形预算要自己把关**。Web 导出没有自动减面兜底，超预算的模型照样能导出，只是加载会卡。

### 排错

| 症状                      | 原因                    | 处理                                   |
| ----------------------- | --------------------- | ------------------------------------ |
| 插件面板里找不到 Blender Bridge | 不在 Desktop 中，或未连接     | 用 Profy Desktop 打开，确认 Desktop 状态为已连接 |
| 勾选了但模型说没有 Blender 工具    | `mcpServers` 未接线（见页头） | 当前预期行为；技能层仍生效                        |
| `uvx` 找不到               | Python `uv` 未安装       | 先装 `uv`，再确认 `uvx blender-mcp` 能手动跑通  |
| 导出的 GLB 在 Three.js 里是空的 | 导出前没有 Apply 变换，或选中集为空 | 按上表逐项核对导出参数                          |

## 验证你的配置

1. 在 Profy Desktop 里开一个新对话，插件面板中应能看到 Blender Bridge——**看不到就说明 Desktop 未连接**，后面都不用试了。
2. 勾选后问「当前 Blender 场景里有哪些物体」。若返回的是方法建议而非实际场景数据，说明命中了页头描述的未接线状态。
3. 让它给一段「把选中物体导出为 Web 用 GLB」的操作步骤。正确的回答应该包含 Draco、2048 贴图上限、Apply 变换这三项——这能验证技能层确实加载了。

## 相关页面

<CardGroup cols={2}>
  <Card title="3D 与可视化开发" href="/zh/documentation/plugins/3d-development">
    云端的 visualize / game-studio / AI 3D 生成
  </Card>

  <Card title="Godot Bridge" href="/zh/documentation/plugins/godot-bridge">
    同族桥接：游戏引擎与确定性回放测试
  </Card>
</CardGroup>

<Note>
  核对日期 2026-08-11。来源：`services/agent-runtime/src/plugins/builtin/blender-bridge/plugin.json`、`skills/blender-workflow/SKILL.md`、`prompts/BLENDER.md`、`services/agent-runtime/src/plugins/registry.py`（`_check_activation`）、`services/agent-runtime/src/plugins/utils/types.py`。
</Note>