这段时间一直在折腾 Antigravity + Blender MCP 这条链路，目标很明确：用自然语言指挥 AI 在 Blender 里搭建智慧仓储数字孪生场景。以前做这类 3D 可视化，建模师手动堆要按周算，写定制脚本又只能服务单一项目，改一个货架尺寸就要翻代码。现在把 Antigravity 的 Agent 当成项目经理，把 Blender MCP 当成伸进建模软件里的那双手，流程变成：你交代需求，Agent 拆任务，Blender 实时出模型。
这篇是系列上篇，先把整体思路、环境搭建、工具设计讲透，最后给一个最小可复现的仓储场景 Demo。适合正在做数字孪生项目的前端工程师、工业软件开发者，以及想用 AI 代工 3D 场景的建模师。下篇我会补上数据接入和动态刷新部分，让场景跟着真实库存状态跳动。
1. 项目整体拆解：这条链路的价值与边界
1.1 智慧仓储数字孪生在现实里到底要解决什么
不少人一听“数字孪生”就往大屏和炫酷渲染上靠，但仓储场景真正的问题从来不是“看”，而是“状态可查、策略可算、结果可练”。真实业务里，仓库负责人想知道的不只是仓库长什么样，而是某个库位现在有没有货、AGV 按当前路径走会不会撞车、如果临时加一排货架对通道宽度有什么影响。
这些诉求落到数字孪生上，会拆成三个基本能力：第一，空间结构可视化，库位、货架、设备都有准确的 3D 表达；第二，布局参数可调，货架尺寸、通道宽度、排布数量能快速修改；第三，状态能关联外部数据，至少能对应到库存系统里的库位编号。很多团队一上来就追求高精度渲染，反而忽略了后两条，结果项目做完变成一次性效果图，业务侧完全无法复用。
我在这篇里不打算引入点云拉框和结构光相机采集，那是中篇、下篇的话题。先把场景骨架做出来，能够响应仓库布局变化、货架尺寸调整、库位编号切换，就已经覆盖了大部分演示和方案验证需求。骨架稳定之后，如果你手里有真实点云扫描或拉框后的目标框数据，再逐层替换成实测模型，工作量会小很多。
1.2 为什么选 Antigravity + Blender MCP，而不是 Unity/Unreal/three.js
我的第一版选型其实不是 Blender。当时想直接用 three.js 做 Web 端，因为前端交付快；后来发现需求不断变化，每个布局改动都要改代码堆模型，three.js 的抽象层级太低，建模这种重活做起来非常别扭。Unity/Unreal 的问题是工程环境太重，为了搭一个仓储原型要拉起整个游戏引擎管线，敏捷迭代成本太高，而且 MCP 生态几乎空白。
Blender 恰好卡在一个很舒服的位置：建模能力全面，Python API 覆盖几乎所有操作，社区又有成熟的 MCP 实现可以直接连。Antigravity 则负责把大模型变成可部署、可调用的 Agent 服务，两边通过 MCP 协议对接，形成一条低成本、高可控的自动化建模链路。
| 方案 | 优势 | 劣势 |
|---|---|---|
| three.js | 纯前端即时展示、交互强 | 建模脚本工作量大，缺少专业建模工具链 |
| Unity/Unreal | 实时渲染强、物理引擎成熟 | 重型工程环境，迭代成本高，MCP 生态弱 |
| Blender | 建模能力全面，Python API 完整，MCP 社区活跃 | 实时交互不如游戏引擎，需要额外导出到 Web |
这个选型还有一个隐性收益：Blender 的建模结果可以直接导出 glTF 或 USD，喂给 three.js、model-viewer 或者其它前端数字孪生网站框架，不需要二次建模。等于 AI 在 Blender 里生成一次资产，Web、渲染、汇报三个场景都能复用。
1.3 总体架构：Agent 拆需求，MCP 执行建模
这条链路的完整数据流是：用户自然语言指令进入 Antigravity Agent，大模型负责规划任务、生成工具调用序列；这些调用通过 MCP 协议封装成 JSON-RPC 消息，发给 Blender MCP Server；Server 把消息翻译成 Blender 的 Python API 操作，驱动 Blender 生成或修改物体；执行结果再原路返回给 Agent，Agent 据此决定下一步动作。
用生活化的比喻，Antigravity 的 Agent 是餐厅里的客人，MCP 是点餐系统，Blender 是后厨。客人不会直接冲进厨房炒菜，而是通过点餐系统下单；厨房做完菜，再由服务员端回来。MCP 的价值不在于它有多智能，而在于它定义了一套标准的“菜单”，让 Agent 能按规范调用外部工具，不用关心 Blender 内部实现。
值得强调的是，MCP 本身不负责理解业务，它只负责把工具暴露出来。真正做决策的是 Antigravity 里的 Agent，它根据用户需求决定“先建货架、再铺地面、最后加灯光”这样的执行顺序。所以整个项目的核心工作，其实不是写建模代码，而是设计一套足够好用的 MCP 工具集合，外加一份把常识写清楚的系统提示词。
2. 环境准备：把 Antigravity、MCP 与 Blender 接入同一条链路
2.1 前置清单与版本选择
动手之前，先把依赖捋清楚。我实测下来最稳的组合是这样的：
- Blender 4.2 LTS，4.5 之后的版本能用但插件兼容性需要验证，不建议新手直接冲最新；
- 一个社区版的 Blender MCP 扩展，通常包含 Blender 插件和 Python Server 两部分，不用额外付费；
- Python 3.10 以上环境，用来跑 MCP Server 进程，注意和 Blender 自带的 Python 解释器区分开；
- Antigravity 账号，以及创建 Agent 和发布工具连接的权限；
- 一台能同时跑 Blender 和 Agent 联调的机器，本机调试最省事，先别急着上公网。
安装顺序有讲究，我的建议是先装 Blender 插件、再启动 MCP Server、最后才去 Antigravity 里建 Agent。如果顺序反过来，Agent 配置好却发现连不上工具端点，排查起来会多一道弯。
2.2 安装并启动 Blender MCP 服务端
Blender MCP 的安装分为两步。第一步是打开 Blender 的偏好设置，选择“安装扩展”，把下载好的 MCP 插件 zip 包装进去；安装完成后去“插件设置”里确认启用，这时插件会要求你填一个端口号，默认一般是 9876，保持默认即可。
第二步是启动 MCP Server 进程。在项目目录下建一个虚拟环境，安装依赖后把 Server 跑起来，再用一条命令确认链路通没通：
curl http://localhost:9876/sse如果返回正常的 SDK 信息，说明 Server 已经就绪。这里有个和很多新手预期不一样的点：MCP Server 和 Blender 并不总是同一个进程，Server 是通过 Blender 的 Python API 远程调度的，所以 Blender 必须保持打开状态，并且启用了 MCP 插件。我把 Blender 最小化之后，Agent 还是能正常建模型；但如果我把 Blender 直接关掉，所有工具调用都会报连接失败。
注意：Blender 的 MCP 服务端不要暴露到公网裸奔。本机调试时监听 localhost 足够；如果一定要远程调用，走内网或者受控网络，不要把 API Key 和端口直接放在公开配置里。
2.3 在 Antigravity 中创建 Agent 并接入 MCP
Antigravity 这侧要做的事比较标准：登录控制台、新建 Agent、在工具配置里选择 MCP 类型的连接器、填入刚才启动的 Server 地址。创建完成后，建议先给 Agent 写一段系统提示词，把项目里最容易出问题的尺寸常识写进去。我目前用的是这样一段：
你是仓储数字孪生建模助手。所有尺寸单位一律使用米。场景原点固定为仓库入口处，X 轴正方向为仓库纵深，Y 轴正方向为仓库横向，Z 轴正方向为垂直向上。默认库位深度 0.8 米，宽度 1.2 米，层高 0.45 米。执行任何建模操作前，先查询场景中已有对象，避免重复创建同名物体。
这段提示词看起来简单，实际效果非常明显。我最早调的时候没有写单位和原点约束，AI 建出来的货架要么尺寸离谱，要么朝向随机。写上之后，这些问题几乎不再出现。
配置完成后，可以直接在 Antigravity 的聊天窗口里测试，也可以把 Agent 发布成 OpenAPI 端点，供外部脚本调用。我的做法是先聊天窗口跑通一两个建模任务，确认 MCP 工具调用正常，再考虑发布。
3. 核心细节解析：把“自然语言”翻译成“建模动作”
3.1 不要给 Agent 一个“建仓库”工具，要给它 20 个原子工具
我见过不少类似的尝试，第一步就是封装一个create_warehouse()大函数，想一次把所有东西建完。这个思路听起来省事，实际上非常难用。原因在于大函数把所有参数都固定在代码里，Agent 只能在一个高度受限的壳里做选择题，用户换一种布局、改一个尺寸，函数就要改源码。
正确做法是把操作拆成原子工具：create_cube、set_location、set_rotation、set_scale、set_material、set_name、assign_parent、duplicate_object、delete_object、list_objects。Agent 根据需求自由组合这些工具，就像用乐高颗粒搭东西，而不是拿一个整装模型。原子化还有一个好处是失败可重试：某个工具调用出错了，Agent 可以针对那一步单独修正，不用整个任务推倒重来。
我实际测试下来，哪怕是最简单的“建一个货架”，Agent 也会拆成七八步：创建立柱、定位、缩放、复制、设材质、改名。过程看起来绕，但每一小步都可审计、可回溯，比一次生成一大坨对象靠谱得多。
3.2 一定要有查询类工具：让 AI 能看见正在搭建的场景
这一点是我踩坑最深的教训。刚开始设计工具集时，我只给 Agent 提供了增删改的工具，没有提供任何查询工具。结果就是 AI 反复新建同名物体，或者连续给同一个对象设置互相矛盾的属性，因为它完全看不到场景里已经有什么。
后来我加了list_objects、get_object_info、get_scene_stats这类查询工具，问题立刻缓解。Agent 在执行建模指令前会先查询场景状态，发现某个名字的物体已存在就选用已有对象，或者先删除再重建。这个“先查询、再执行”的习惯，和人类建模师的工作方式完全一致，只是需要通过工具把它变成 Agent 的默认行为。
如果你也在设计自己的 Blender MCP 工具集，我建议查询类工具的比例至少占到三分之一。没有上下文感知能力的 Agent，就像一个闭眼搭积木的人，手感再好也会翻车。
3.3 坐标、尺寸与命名的三个硬规范
自然语言描述天生带歧义，因此必须给 Agent 立三个硬规范。
第一是单位规范。Blender 场景默认单位是米，但很多仓储图纸习惯用毫米或者厘米。MCP 工具层要做统一的单位转换，我的做法是把所有外部输入的 cm/mm 一律换算成米再传给 Blender，禁止把原始数值直接塞进坐标。
第二是基准规范。每个场景都要定义原点、轴向和正方向。没有这个基准，Agent 说“往左挪一点”，它和你理解的“左”可能完全不是一回事。把“仓库入口在原点，X 轴是纵深，Y 轴是横向”写进系统提示词，是成本最低、见效最快的一步。
第三是命名规范。所有对象名必须带语义前缀和序号，例如rack_01_level_04。这个规范不是强迫症，而是为了后续数据对接。真实库存系统里每个库位都有编号，如果 3D 场景里的对象名和业务编号对不上，后面做状态映射会非常痛苦。
4. 实操演示：用自然语言生成一个迷你智慧仓储场景
4.1 第一步：描述需求并让 Agent 动工
环境配置好之后，我们来跑一个最小可复现的例子。我给 Agent 的指令是：
在原点附近建一块 20 米 x 12 米的仓储库区。库区入口在 X 轴负方向。内部放置 3 排双面货架，每排 12 个库位，货架尺寸为长 8 米、宽 0.9 米、高 3.6 米，共 4 层。货架之间通道宽度 2.4 米。货架立柱用灰色材质，横梁用橙色材质。
预期中，Agent 会执行一系列原子工具调用。我实测的序列大致是：
create_cube(name="rack_01_post_01", ...)创建第一根立柱；set_scale调整立柱尺寸，set_location放到指定坐标；- 复制并偏移，生成一排立柱；
create_cube生成横梁，set_material设成橙色；- 复制横梁并移动到对应层高；
- 整组复制并在 Y 轴方向生成三排货架。
你会看到 Agent 并不会一次性生成完整对象，而是一个部件一个部件地搭。这个过程比想象中慢，但每步都在可控范围内。如果你希望它更高效，可以在指令里明确写“先建一个货架，然后用数组复制生成三排”，Agent 会优先选择复制路线而不是逐个生成。
4.2 第二步：让布局数据从 JSON 进来，而不是靠自然语言
真实项目里你不会用自然语言去描述几百个库位，那既不准确也不优雅。更合理的做法是让 Agent 读一份布局数据文件，按数据批量建模。我准备的 JSON 片段长这样：
{ "warehouse": { "unit": "m", "origin": [0, 0, 0], "shelves": [ { "id": "A-01", "x": 2.0, "length": 8.0, "width": 0.9, "height": 3.6, "levels": 4, "bays": 12 }, { "id": "B-01", "x": 11.2, "length": 8.0, "width": 0.9, "height": 3.6, "levels": 4, "bays": 12 } ] } }然后我给 Agent 的指令是：“读取这份 JSON，按 id 字段命名每个货架对象，并根据 length、width、height 生成货架外轮廓。每排货架先不建细节，只建双面骨架和层板。”结果 Agent 会自动生成A-01、B-01这样的命名对象组，而不是代码里写死的 rack_01。
这个做法的好处非常明显：数据结构和业务系统一致，后续从 WMS 系统拿真实库位数据时，只需要替换 JSON 内容，建模逻辑完全不用动。AI 在这里干的活，本质上是从“结构化数据”到“3D 表达”的转换器。
4.3 第三步：渲染与外送
场景搭建完成后，先在 Blender 里做基础检查。打开线框模式看结构有没有重叠，切换到材质预览看颜色是否正确，最后用 Cycle 渲染出一张静态图确认整体观感。如果只是做方案汇报，到这里其实已经可以交付了。
后续如果要把场景放到前端数字孪生网站上，推荐导出 glTF 格式（.glb）。Blender 对 glTF 的支持很成熟，three.js 和 model-viewer 都能直接用，不需要额外付费插件。如果面对的是工业级数据交换场景，导出 USD 格式更合适，它保留了更完整的场景层级和单位信息。
注意：导出 glTF 前，把 Blender 的场景单位确认成“米”，并用“仅导出选中物体”或者集合分组导出，避免把灯光、相机等辅助对象一股脑塞进交付文件里。
5. 常见问题与排查技巧实录（含避坑）
5.1 “403 / verify your account / authentication failed” 类报错怎么查
我在 Antigravity 控制台调用 Agent 时，确实遇到过 403 和“verify your account to continue”这类的身份验证提示。刚开始怀疑是配置问题，把 Agent 删了重建，来回折腾了半小时，后来才定位清楚：这类提示绝大部分说的是身份验证状态需要刷新，以及账号的访问范围没有覆盖到当前使用的资源。
建议的排查顺序是这样的：先重新进入 Antigravity 控制台，看一下账号是否还需要完成最新的身份验证流程；如果账号状态正常，再去检查 Agent 的权限范围，确认当前要调用的工具确实在该 Agent 的允许清单里；然后检查 MCP Server 的地址是否还处于有效状态，有没有因为 Blender 关闭导致服务不可用；最后确认账号配额没有耗尽，免费额度用完之后调用也会被拒。
不要跳步。我从登录态开始查，发现 80% 的情况是会话过期或者验证步骤没走完，而不是服务本身故障。这类报错从设计上就是安全机制的一部分，正确的处理方式是先确认自身的身份凭证和权限，而不是尝试绕过校验。
5.2 agent execution terminated due to error 是什么原因
这个报错出现的场景五花八门，但根因通常逃不出三类。第一类是 MCP Server 进程“静默死亡”，Blender 还开着，但 Server 已经断了，Agent 后续所有工具调用都会失败；第二类是单个工具执行超时，比如复杂布尔运算或者大量对象复制在 Blender 里卡顿，Agent 等待太久直接判定任务终止；第三类是上下文会话被塞爆，工具调用轮次太多，来回传的数据量超过了单次会话承载上限。
处理办法也对应有三条：一条是给 Agent 的任务拆小，一个指令只做一件事，不要一条命令建完整个园区；另一条是给 MCP Server 加一个守护脚本，异常退出自动重启；第三条是让 Agent 在长任务里定期调用get_scene_stats汇报进度，既能确认端点存活，也能压缩上下文中的重复信息。
5.3 模型错位和尺寸失控排查表
这类问题几乎每个接触过 Blender MCP 的人都会遇到，我把最常见的几种症状和对应处理方式列成了一张表：
| 症状 | 可能原因 | 处理方式 |
|---|---|---|
| 整层模型偏移 | 原点、轴向没有在提示词里定义 | 固定原点与坐标轴定义，写入系统提示词 |
| 尺寸大得离谱 | 单位没统一，cm 被当成 m 使用 | 工具层强制转换单位，禁止外部原始数值直传 |
| 对象叠名、互相覆盖 | 缺少查询工具，Agent 不知道场景现状 | 添加 list_objects，执行前先查询 |
| 材质颜色不对 | 材质名不匹配，或材质未赋给正确面 | 内置材质库前缀，统一命名，工具内预判 |
这张表并不神秘，核心思路是“把人类的直觉变成 Agent 的默认规则”。AI 不会主动知道你的“高层货架”是 3.6 米还是 30 米，也不会知道原点在哪里。所有行业常识，都要通过系统提示词和工具设计显式告诉它。
5.4 上篇收尾：一个一定要记住的分水岭
我个人在这套链路里踩得最深的一个坑，是过于相信自然语言描述。AI 再聪明，也不会知道你心里的“高层货架”是多高。把关键尺寸、坐标系和命名规范写进系统提示词，甚至直接做成 JSON 模板，是让这套玩法从“好看”变成“能用”的分水岭。
下一篇我会把重点放在数据接入：如何把真实仓储系统的库位状态，比如占用/空闲、AGV 当前位置，通过 Antigravity 的定时任务写回 Blender，让建模结果变成可以跟着业务数据跳动的活孪生。如果你也在折腾 Blender MCP 和 AI Agent，建议先把这篇的环境和工具规范跑通，后面我们才好在一个稳定的地基上继续加东西。
