BWM-Forge: Agentic World Programming for Embodied Intelligence
English | 简体中文
[](https://bwm-forge.github.io/)
[](https://arxiv.org/abs/2611.16221)
[](LICENSE)
**BWM-Forge** 通过*对世界进行编程*生成可控的机器人视频,而不是端到端地预测像素。编程智能体编写可编辑的 Blender 场景程序,明确指定物体、机器人运动和相机;Blender 将其渲染为**白模视频(proxy video)**;视频生成模型再基于这些结构与运动添加真实感外观。
几何、运动和视角都显式保留在代码中,因此你可以移动某个物体、更换机器人,或用新的相机视角拍摄同一段交互,而无需从头开始。本仓库提供完整流程与本地 Gradio 工作区,将输入处理、Blender 建模、视频生成、人工审核和可复用的经验库整合在一起。
## 📖 目录
- [项目亮点](#highlights)
- [框架](#framework)
- [Demo](#demo)
- [快速开始](#quick-start)
- [使用指南](#user-guide)
- [贡献者](#contributors)
- [引用](#citation)
- [许可证](#license)
---
## 🌟 项目亮点
- **三种范式**:根据空间语义、运动先验或真实示范生成动作。
- **多种机器人形态**:支持机械臂、人形机器人、机械狗与灵巧手,可导入包含网格资源的本地 URDF。
- **分阶段、可编辑的建模**:场景、机器人和组合动画分别在独立的 Blender 阶段中构建。每轮保留 `.blend` 工程、脚本和预览,便于在已有结果上修改,无需重新生成。
- **视角控制**:通过修改指令更换相机,同时保持场景布局、机器人姿态和动画不变;也可以重新加载已完成的任务,从其他视角拍摄。
- **先评估,再修改**:使用白模视频和参考图像生成视频,结合本地客观指标与模型视觉评估指导修改。
- **轮次追踪与经验复用**:从已完成任务中提炼建模与渲染规则,供后续任务检索使用。
## 🧩 框架
应用按顺序运行四个阶段:**Input → Blender(Scene → Robot → Composed)→ Render → Harness**。
## 🎬 Demo
https://github.com/user-attachments/assets/419fc098-b061-4e2d-940e-27fd8a4a3cbf
## 🚀 快速开始
### 环境准备
当前以 Windows 本地使用为主,界面与程序运行在同一台计算机上。
| 依赖 | 说明 |
| --- | --- |
| Python | 3.11 或更高版本,建议使用独立环境 |
| Blender | 需要可执行文件及其内置 Python,路径在 `config.py` 中配置 |
| Python 依赖 | 见 [requirements.txt](requirements.txt) |
| 模型服务 | 支持 Responses API 的模型服务,以及与当前接口实现兼容的视频生成服务 |
| Cloudflared | Render 阶段用于临时发布白模视频。从[官方发布页](https://github.com/cloudflare/cloudflared/releases)下载 `cloudflared.exe`,放入 `Render/tools/` |
模型请求和视频生成需要联网。完整流程会通过 Cloudflare 临时隧道提供所选白模视频,供视频服务读取。
### 1. 安装依赖
克隆或下载仓库后,在仓库根目录执行:
```bash
conda create -n bwm python=3.11 -y
conda activate bwm
python -m pip install -r requirements.txt
```
安装 Blender,并确认可以在本机启动。Blender 是独立安装的软件,不包含在 Python 依赖中。
### 2. 配置模型与服务
运行参数集中在 [config.py](config.py)。首次使用时至少修改以下配置:
| 配置 | 用途 |
| --- | --- |
| `OPENAI_BASE_URL` | Responses API 的根地址,例如 `https://your-provider.example/v1` |
| `OPENAI_AUTH_FILE` | 通用模型服务共用的认证文件路径 |
| `INPUT_MODEL` | 首帧分析模型,需要支持图像输入 |
| `BLENDER_MODEL` | Blender 建模使用的 Codex 模型 |
| `BLENDER_EXE` | 本机 Blender 可执行文件的完整路径 |
| `RENDER_MODEL` | 视频视觉评估与阶段总结使用的模型,需要支持图像输入 |
| `HARNESS_MODEL` | 经验整理与更新使用的模型 |
| `SEEDANCE_BASE_URL` | 视频生成服务根地址 |
| `SEEDANCE_MODEL` | 视频生成模型名称 |
| `SEEDANCE_AUTH_FILE` | 视频服务认证文件路径 |
模型名称按服务商实际支持的名称填写。通用模型地址填写 API 根地址,程序会追加 `/responses`,无需填写完整请求端点。
默认情况下,Input、Blender、Render 和 Harness 共用 `OPENAI_BASE_URL` 与 `OPENAI_AUTH_FILE`。如需分别配置,可修改各阶段的 `*_OPENAI_BASE_URL` 和 `*_OPENAI_AUTH_FILE`。配置修改后需要重启程序。
视频服务使用独立的请求协议,具体接口见 [Render/seedance.py](Render/seedance.py)。更换服务商时,需要确认其提交、任务查询和媒体输入格式与当前实现兼容。
### 3. 填写 API 密钥
创建 `assets/api/` 文件夹,并在其中添加以下两个文件;也可以将 `config.py` 中的 `OPENAI_AUTH_FILE` 和 `SEEDANCE_AUTH_FILE` 指向其他位置。
`assets/api/auth.json`:
```json
{ "OPENAI_API_KEY": "REPLACE_WITH_YOUR_API_KEY" }
```
`assets/api/seedance_auth.json`:
```json
{ "SEEDANCE_API_KEY": "REPLACE_WITH_YOUR_API_KEY" }
```
### 4. 启动
在仓库根目录执行:
```bash
python -m gui.app
```
浏览器会自动打开;若未打开,请访问 。服务仅监听本机地址。
## 🧭 使用指南
### 使用流程

#### 1. 准备输入
选择机器人类型和资产,填写任务描述,再选择输入模式:
| 模式 | 所需输入 | 动作来源 |
| --- | --- | --- |
| 空间语义驱动 | 首帧图像、机器人资产、任务描述 | 根据图像与描述生成动作 |
| 运动先验驱动 | 首帧图像、机器人资产、任务描述、NPZ / Parquet 轨迹、采样率 | 使用提供的动作轨迹作为参考 |
| 真实示范驱动 | 机器人资产、任务描述、MP4 / MOV 演示视频 | 根据演示视频生成动画 |
首帧图像支持 PNG、JPG 和 WebP。点击 **Create task and run Input** 创建任务。
导入新资产时,选择 **Import local robot asset**,填写运行程序这台计算机上的 URDF 路径和资产名称。请使用已展开的 URDF,并保留其与 `meshes/`、纹理等资源的相对目录关系;资源引用应能在本地解析。
#### 2. 审核 Blender 结果
Blender 按以下顺序完成建模:
1. **Scene**:生成场景,审核预览图。
2. **Robot**:准备机器人模型,审核预览图。
3. **Composed**:组合场景与机器人,生成动作并审核完整白模视频。
点击 **Accept and continue** 接受当前结果,或填写修改意见、按需附加参考图像后点击 **Submit revision**。每轮工程、脚本、预览和反馈会保存在任务目录中。
#### 3. 生成并确认视频
Blender 完成后,点击 **Continue generation** 手动启动视频生成。程序将白模视频与参考首帧发送给视频生成服务,再对结果进行评估。初版客观评分低于配置阈值时,流程最多自动生成一次修正版,之后进入完整评估与人工审核。
可以在界面中重新评估、提交修改,或点击 **Confirm final video** 确认最终视频。确认和阶段总结完成后,Harness 会归档结果并更新经验库。
#### 4. 从历史任务继续
点击 **Load historical task**,选择一个任务,再点击 **Load as new task**。这会将已完成任务的 Blender 结果复制到新任务中,并重新打开 Composed 审核,便于继续修改或更换相机视角拍摄场景。
单个工作区一次运行一个任务,等待人工审核时也会占用执行名额。
### 轨迹格式
运动先验驱动模式接受 NPZ 和 Parquet 两种文件格式:
设 `T` 为帧数,`n` 为轨迹中提供的关节数。数据必须为有限数值,不能包含 NaN、Inf 或对象数组。采样率在界面中显式填写。
| 本体 | 运动表示 | 字段及维度 | 含义 |
| --- | --- | --- | --- |
| 机械臂 | `joint` | `action`: `(T, n)` | 关节绝对位置;按界面中关节名顺序排列 |
| 机械臂 | `eef` | `action`: `(T, 7)` | 基座坐标系下 TCP:`x, y, z, roll, pitch, yaw, gripper` |
| 灵巧手 | `joint` | `joint`: `(T, n)` | 手指关节绝对位置;若手腕/手掌移动,另需 `base` |
| 灵巧手 | 手腕/手掌 + 手指关节 | `joint`: `(T, n)`;`base`: `(T, 7)` | 在关节轨迹上增加整体位姿;固定手腕时省略 `base` |
| 机械狗 | 机身 + 关节 | `joint`: `(T, n)`;`base`: `(T, 7)` | 同步描述机身移动和各关节运动 |
| 人形机器人 | 根节点 + 关节 | `joint`: `(T, n)`;`base`: `(T, 7)` | 同步描述根节点移动和各关节运动 |
`joint` 每列对应一个 URDF 独立关节,并按界面填写的关节名顺序排列。`base` 固定为 `(T, 7)`,列顺序为 `x, y, z, qw, qx, qy, qz`,表示世界坐标系下根链接的绝对位姿。
关节位置为绝对值;旋转关节单位为 rad,移动关节单位为 m。`eef` 位置单位为 m,欧拉角单位为 rad,旋转顺序为 `Rz @ Ry @ Rx`。`eef` 仅用于机械臂;夹爪列以 `0` 闭合、`1` 张开作为约定参考,实际驱动映射取决于资产结构与标定信息。
### 输出与经验库
每个任务保存在 `output//` 下,主要产物包括:
| 路径 | 内容 |
| --- | --- |
| `task.json` | 任务元数据与阶段状态 |
| `input/input.json` | 输入阶段交接数据 |
| `blender/final.blend` | 最终 Blender 工程 |
| `blender/white_model.mp4` | 最终白模视频 |
| `blender/run.json`、`blender/stages/` | 建模轮次与审核记录 |
| `render/` | 生成视频、版本记录及评估文件 |
| `harness/result.json`、`harness/runs/` | 归档结果、经验处理记录及报告 |
建议通过任务记录和界面查看各版本的最终路径;Render 的修改版本会使用独立文件名。
经验库默认位于 `assets/experience-store/`,以 JSONL 文件保存通用经验和适用于特定情境的经验。Blender 建模轮次与 Render 视频版本会检索相关经验,Harness 在任务结束后根据阶段记录决定如何更新经验库。
### 使用说明
- 任务文件包含本机路径和状态信息,运行中请保留输入、资产与任务目录的位置。
- 修改 URDF 或网格后,如资产目录中已有 `blender/robot.blend`,请删除对应缓存后重新建模。
- 模型请求、视频生成和修改会使用用户自己的服务额度。具体模型能力、服务可用性及生成耗时取决于所配置的服务商。
## 👥 贡献者
| Role | Contributors |
| :--- | :--- |
| **Project Leader** | Lanyun Zhu |
| **Core Contributors** | Chenming Li, Jianhao Song, Xuanyi Liu, Zhixuan Xu |
| **Contributors** | Yichen An, Youyuan Jiang, Haotian Zhang, Ziming Wei, Enci Xie, Hongye Fang, Yueyang Li, Zixuan Zhang, Xun Jiang, Xuancheng Xu, Zengrong Lin, Baixu Ji, Chengxing Xie, Yi Guan, Zesi Shen |
| **Corresponding Authors** | Lanyun Zhu, Xing Xu, Heng Tao Shen |
## 📚 引用
如果本项目对你的研究有所帮助,欢迎引用我们的论文:
```bibtex
@misc{bwmforge,
title = {{BWM-Forge}: Agentic World Programming for Embodied Intelligence},
author = {{BWM Team}},
year = {2026},
eprint = {2611.16221},
archivePrefix = {arXiv},
primaryClass = {cs.RO},
url = {https://arxiv.org/abs/2611.16221}
}
```
## 📜 许可证
Copyright 2026 BWM-Forge contributors.
本项目的原创代码与文档采用 [Apache License 2.0](LICENSE)。