内容
# 宇宙全景智能代理工作室
一个**基于Web的智能代理AI编辑器**，用于NVIDIA Isaac Sim。在浏览器中与大型语言模型对话，并实时编辑OpenUSD场景 - 当Isaac Sim通过WebRTC流式传输视口，Blender通过USD往返传输资产，代理通过MCP工具驱动两者。
```
┌────────────────────────────────────────────────────────────────────────┐
│ 您的网页浏览器 │
│ ┌──────────────┐ ┌────────────────────┐ ┌─────────────────────┐ │
│ │ 场景图 │ │ Isaac Sim 流 │ │ 与代理聊天 │ │
│ │ /World │ │ ┌──────────────┐ │ │ > 添加一个红色立方体 │ │
│ │ ├ 地面 │ │ │ (WebRTC) │ │ │ > 导出为USD │ │
│ │ └ 机器人 │ │ └──────────────┘ │ │ │ │
│ └──────┬───────┘ └─────────┬──────────┘ └──────────┬──────────┘ │
└──────────┼─────────────────────┼─────────────────────────┼─────────────┘
│ │ │
▼ HTTP ▼ WebRTC 49100/47998 ▼ SSE
┌─────────────────────────────────────────────────────────────┐
│ 代理（FastAPI + Claude） │
│ 通过流媒体HTTP调用MCP工具 │
└──┬───────────────────────────┬──────────────────────┬───────┘
│ │ │
┌─────▼──────────┐ ┌───────▼────────┐ ┌───────▼────────┐
│ usd-mcp :8001 │ │ blender-mcp │ │ Isaac Sim │
│ （13个工具在 │ │ :8002 (11 │ │ 运行无头 │
│ usd-core） │ │ 通过socket桥接 │ │ --实时流媒体 │
│ │ │ │ │ │
└───────┬────────┘ └────┬───────────┘ └────────┬───────┘
│ │ │
└──────────────────────┼──────────────────────────┘
▼
共享 ./stages/ 卷（USD文件）
```
## 开始前您需要
宇宙全景智能代理工作室需要一个真正的NVIDIA GPU来运行Isaac Sim。**它不能在macOS上运行，也不能在没有GPU直通的虚拟机或仅限CPU的机器上运行。** 如果您只有Mac，您可以阅读代码并运行测试，但您将看不到流媒体视口。
### 硬件
| 组件 | 最低要求 | 推荐配置 |
| --- | --- | --- |
| GPU | NVIDIA RTX 3070（8 GB）— 使用Isaac Sim 4.5备用 | **NVIDIA RTX 4080（16 GB）** — 需要Isaac Sim 6.0 |
| RAM | 16 GB | 32 GB |
| 磁盘 | 30 GB可用空间 | 50 GB SSD |
| CPU | 4核 | 8+核 |
> **不支持**：A100，H100或任何数据中心GPU。这些没有NVENC编码器，因此WebRTC流媒体静默失败。您需要一个消费者或工作站RTX卡。
### 软件
| 平台 | 支持 | 备注 |
| --- | --- | --- |
| Ubuntu 22.04 / 24.04 | 是，一流支持 | 最简单的路径 |
| Windows 10 / 11 | 是，通过WSL 2 | 需要WSL 2 + Docker Desktop |
| macOS | 否（Isaac Sim不会启动） | 代码和单元测试仍然可以运行 |
### 账户
在安装前，您需要**两个免费账户**：
1. **NVIDIA NGC** — 用于拉取Isaac Sim Docker镜像。
在 <https://ngc.nvidia.com/signup> 注册并在 <https://org.ngc.nvidia.com/setup/api-keys> 生成API密钥。
2. **Anthropic** （推荐）或 **OpenAI** — 用于驱动代理的大型语言模型。
在 <https://console.anthropic.com> 注册并创建API密钥。OpenAI也可以作为备用。
请记住这两个密钥 — 稍后您将把它们粘贴到 `.env` 中。
## 分步安装（Ubuntu 22.04 / 24.04）
如果您使用的是Windows，请跳转到 [Windows部分](#分步安装-windows-10--11)。在macOS上，您只能运行测试套件 — 请参见 [运行测试](#运行测试-any-os)。
### 1. 克隆仓库
```bash
git clone https://github.com/JinwangMok/omniverse-agent-studio.git
cd omniverse-agent-studio
```
### 2. 运行预检查
```bash
./scripts/preflight-check.sh
```
这将打印GPU、驱动程序、Docker和内存的`PASS` / `WARN` / `FAIL`表格。如果任何内容显示`FAIL`，请在继续之前修复它。常见的修复方法：
- **`nvidia-smi not found`** → 安装NVIDIA驱动程序：
`sudo apt install nvidia-driver-550` （或更新版本）并重启。
- **`Docker not installed`** → 让安装程序在下一步中处理此问题。
- **`GPU VRAM < 8 GB`** → 您的卡太小。请停止此处。
### 3. 运行安装程序
```bash
./scripts/install-linux.sh
```
脚本是**交互式且幂等的** — 它在每个破坏性步骤之前都会询问，并跳过已经安装的任何内容。它安装：
- Docker引擎（通过 `get.docker.com`）
- NVIDIA容器工具包（需要 `--gpus all`）
- `uv` （快速Python包管理器，用于本地开发）
- Node.js 20（用于Web UI）
- Blender 4.2.10 LTS（原生CLI，用于脚本编写，无需Docker）
- `usd-core` 在 `~/.venvs/openusd` （用于在终端中运行USD脚本）
在最后，它将提示您输入NGC密钥并运行 `docker login nvcr.io`。
### 4. 配置环境
```bash
cp .env.example .env
```
在编辑器中打开 `.env` 并至少填写以下四个值：
```bash
NGC_API_KEY=nvapi-XXXXXXXXXXXXXXXXXXXXXXXXXXXX # 来自步骤：NVIDIA NGC
ANTHROPIC_API_KEY=sk-ant-XXXXXXXXXXXXXXXXXXXXX # 来自Anthropic控制台
ISAACSIM_HOST=192.168.1.50 # 本机IP地址
# （使用 `hostname -I | awk '{print $1}'`）
ACCEPT_EULA=Y # 您接受NVIDIA的Isaac Sim最终用户许可协议
```
> **为什么 `ISAACSIM_HOST` 需要一个真实的IP地址？** WebRTC媒体通过UDP在47998端口传输，不能通过 `127.0.0.1` 工作，当浏览器和Isaac Sim在不同的Docker网络命名空间中时。使用浏览器可以访问的接口IP地址。
### 5. 启动所有服务
```bash
make up
```
这将运行 `docker compose up -d`。第一次运行将下载约12 GB的Isaac Sim镜像 — 请抓杯咖啡。可以使用以下命令查看进度：
```bash
make logs # 尾随所有服务日志
docker compose ps # 检查每个服务的健康状况
```
所有五个服务应该在第一次启动后2-3分钟内显示 `healthy`。
### 6. 打开浏览器
前往 **<http://localhost:3000>**。
您应该看到一个三列布局：左侧是场景图，中间是Isaac Sim流，右侧是聊天。等待5-10秒让流连接（您将在查看器的底部看到“Connected”绿色提示）。
尝试在聊天中说：
> `添加一个名为MyBox的红色立方体，位置为（0, 1, 0），然后将相机聚焦到它。`
您应该看到代理调用 `create_mesh`、`set_transform` 和 `emit_isaac_event` — 立方体应该出现在流媒体视口中。
## 分步安装（Windows 10 / 11）
Windows无法原生运行Isaac Sim，但WSL 2配合GPU直通效果良好。
### 1. 安装WSL 2和Docker Desktop
以管理员身份打开PowerShell并运行：
```powershell
git clone https://github.com/JinwangMok/omniverse-agent-studio.git
cd omniverse-agent-studio
./scripts/install-windows.ps1
```
这将启用WSL 2，安装Ubuntu 22.04，安装Docker Desktop，并验证您的NVIDIA驱动程序。**当它要求时，请重启**。
### 2. 切换到WSL 2
重启后：
```powershell
wsl -d Ubuntu-22.04
```
在WSL shell中：
```bash
cd /mnt/c/path/to/omniverse-agent-studio
./scripts/preflight-check.sh
./scripts/install-linux.sh
```
### 3. 配置和启动
与上面的Linux指南中的步骤4-6相同。
> **Windows网络问题**：设置 `ISAACSIM_HOST=$(hostname -I | awk '{print $1}')` — WSL 2 IP，而不是 `localhost` 或您的Windows IP。
## 运行测试（任意操作系统）
Python服务和Web前端都有真正的测试套件，不需要GPU。使用这些来验证您的checkout或贡献：
```bash
# USD MCP服务器（12个测试，在macOS / Linux / Windows上运行）
cd services/usd-mcp && python3.11 -m venv .venv && source .venv/bin/activate
pip install -e . pytest && pytest -q
# Blender MCP服务器（15个测试，模拟Blender — 不需要安装）
cd services/blender-mcp && python3.11 -m venv .venv && source .venv/bin/activate
pip install -e . pytest && pytest -q
# 代理编排器（12个测试）
cd services/agent && python3.11 -m venv .venv && source .venv/bin/activate
pip install -e . pytest pytest-asyncio && pytest -q
# Web前端（类型检查）
cd web && npm install --ignore-scripts && npx tsc --noEmit
```
您应该看到 `12 passed`、`15 passed`、`12 passed` 和干净的TypeScript检查。
## 服务和端口
| 服务 | 端口 | 描述 | 源代码 |
| --- | --- | --- | --- |
| web | 3000 | Next.js 15 + AppStreamer查看器 + 聊天 | `web/` |
| agent | 8080 | FastAPI + Claude工具使用循环，SSE | `services/agent/` |
| usd-mcp | 8001 | OpenUSD MCP（13个工具，`usd-core` 26.3） | `services/usd-mcp/` |
| blender-mcp | 8002 | Blender MCP（11个工具） | `services/blender-mcp/` |
| blender-mcp桥接 | 9876 | 到Blender插件的TCP套接字（内部） | `services/blender-mcp/src/blender_mcp/addon.py` |
| isaac-sim信号 | 49100/tcp | WebRTC信号（主机网络） | `services/isaac-sim/` |
| isaac-sim媒体 | 47998/udp | WebRTC媒体流（主机网络） | — |
| isaac-sim查看器 | 8210 | 内置Web查看器（调试） | — |
## 代理可以做什么？
总共24个工具 — 请参见 [docs/AGENT-TOOLS.md](docs/AGENT-TOOLS.md) 获取完整签名。
- **场景编辑（USD MCP，13个工具）** — 创建/打开/保存阶段，列出prims，创建Xforms和网格（立方体，球体，平面，圆柱体），设置变换，添加引用，管理变体集。
- **建模（Blender MCP，11个工具）** — 在Blender中创建原语，分配材料，运行任意 `bpy` 代码，捕获视口截图，通过 `bpy.ops.wm.usd_export` / `usd_import` 往返。
- **视口控制（Isaac Sim事件）** — 代理可以发送 `focus_prim`、`reload_stage` 等到浏览器，浏览器通过 `AppStreamer.sendMessage` 将它们转发到Isaac Sim。
## 常见首次使用问题
| 症状 | 原因 | 修复方法 |
| --- | --- | --- |
| `docker pull nvcr.io/...` 显示“未授权” | 未登录NGC | `./scripts/login-ngc.sh` |
| 查看器显示“Disconnected”一直 | `ISAACSIM_HOST` 错误或防火墙阻止49100/47998 | 设置 `ISAACSIM_HOST` 为可访问的IP地址，打开端口 |
| 代理聊天回复“500服务器错误” | `ANTHROPIC_API_KEY` 缺失或无效 | 检查 `.env`，重启 `make down && make up` |
| Isaac Sim容器立即退出 | 缺少 `.env` 中的 `ACCEPT_EULA=Y` | 添加它，重新运行 `make up` |
| `make up` 显示“nvidia-container-cli: requirement error” | `nvidia-container-toolkit` 未配置 | 再次运行 `./scripts/install-linux.sh` 或 `sudo nvidia-ctk runtime configure --runtime=docker && sudo systemctl restart docker` |
| 流媒体工作但看起来模糊 | 默认分辨率为1280x720 | 在AppStreamer URL中添加 `&resolution=1920x1080&fps=60` |
更多帮助： [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)。
## 停止和清理
```bash
make down # 停止所有服务
make clean # 还删除容器、网络和卷（!!!）
```
`make clean` 删除缓存的Isaac Sim着色器 — 下一个 `make up` 将重新编译它们（~30秒）。它不触及您的 `stages/` 文件夹。
## 进一步阅读
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — 深入了解数据流和设计决策。
- [docs/INSTALL.md](docs/INSTALL.md) — 详细的安装参考。
- [docs/USAGE.md](docs/USAGE.md) — 示例聊天工作流。
- [docs/AGENT-TOOLS.md](docs/AGENT-TOOLS.md) — 每个MCP工具及其输入模式。
- [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) — 扩展故障排除。
用于设计项目的研发笔记： [`.omc/research/`](.omc/research/) （Isaac Sim WebRTC流媒体，Blender MCP模式，OpenUSD工具）。
## 许可证
MIT — 请参见 [LICENSE](LICENSE)。Isaac Sim本身受NVIDIA Omniverse许可证管辖；您通过设置 `ACCEPT_EULA=Y` 接受它。
