MuJoCo Web 仿真平台

以 WebAssembly 为运行核心的本地机器人仿真、控制与强化学习调试平台。浏览器直接加载 MJCF、URDF、文件夹或 ZIP 工程，使用 Three.js 渲染，并通过 MuJoCo WASM 在本地执行物理仿真。

本仓库是面向 Web 产品的应用仓库，不再镜像 MuJoCo 的原生 C++、Python、MJX、Unity、桌面模拟器和上游测试源码。MuJoCo 运行时由官方 npm 包 @mujoco/mujoco 提供。

功能概览

• MJCF/XML、URDF、文件夹和 ZIP 工程导入
• ROS package://、常见 URDF 兼容转换及 DAE 降级处理
• Three.js 模型、碰撞体、坐标系、关节轴、质心和惯量可视化
• 播放、暂停、单步、重置、变速、关节拖动与外力交互
• 统一地图资产库：工程地图、认证资产、内置地图及 9 类系统参数化地形共用点击/拖放、场景树、轻量预览、实例变换、放弃和一次编译事务
• 工程地图包：静态 MJCF/OBJ/STL/高度场碰撞层、GLB 视觉层和机器人出生点；同源实例拥有独立位姿，物理/视觉/出生点同步变换
• V3 地图创作层：认证资产可在程序地形上自动重力落位，共用右侧属性和视口操纵器，支持源内容编辑、空白取消选择及导出地图 ZIP
• 通用机器人数值接口、本机控制桥接与 LeKiwi / LeRobot 0.6.1 仿真插件（不接实体硬件）
• 浏览器内 Python 控制器（Pyodide）
• ONNX 强化学习策略推理（ONNX Runtime Web）
• 独立移动操作 RL 实验页：机器人 ZIP 热切换、物体/目标拖动、固定观测/动作契约及原生 Python 对称环境
• 内置 Go2 PPO 任务的本机 mjlab 训练桥接服务，以及 DeepSeek 驱动的奖励函数自调参、固定评估和 TensorBoard 风格独立工作台
• 响应式工作区、源码编辑、性能监控和中文诊断

网站版

内置 LeKiwi 直达链接：https://cadworld-sim.robotquan.com/?robot=lekiwi-v1。对外参数为 robot=lekiwi-v1，打开即从服务器下载内置模型、自动配置并导入仿真，无需上传或确认弹窗；默认暂停，不自动执行指令；左下角可切换前置/腕部两路摄像头。不带参数时仍为空白工作台。参数与资产说明。

生产网站：https://cadworld-sim.robotquan.com。公开访问，无需终端或填写密钥，模型由服务器固定配置。

语言控制 v2 已上线（20260924T065821Z-language-v2）：本地/网站统一“控制台 → 机器人语言控制”，载入预设后输入“把方块搬到 B 区”或“把方块搬到 (0.25,0.50) 米”；仍支持“前进0.5米”“左转90度”。LLM 任务解析 → Jev Choice/Noul/Score → 本地 IK/限速技能，真实支撑区域内可用连续世界坐标，不重置物体执行旧演示。只保留预设、文字、执行/停止与状态。公网非付费检查已通过，真实 v2 模型抓放尚未验收。发布记录 · 范围与验收 · 本地同源启动。

npm run build:website 输出 website-dist/，隐藏训练、调参和本机外控；本地训练/外控功能保留。仿真仍在浏览器，服务器密钥不进入网页或发布包；默认 DeepSeek flash＋Jev 1.13，全站共享每小时 60/每日 600 次调用限额，费用由站长承担。支持空旷平地、单次 0.01–1 米平移或 1–180 度转向，以及预设支撑区域内的单方块搬运，目标含糊时询问；不宣称任意自然语言任务/避障。 部署/回滚/隐私边界 · 同源 API · 最新实测与限制。

快速开始

环境要求：Node.js 24（版本见 .nvmrc）和 npm 11.17；仅使用本机桥接服务或执行 Python 检查时需要 Python 3.12。

nvm use
npm install --global npm@11.17.0
npm ci
npm run dev

打开 Vite 输出的地址，默认是 http://localhost:5173/。

常用命令

npm run dev                  # 启动开发服务器
npm run build                # 生产构建到 web-platform-dist/
npm run preview              # 预览生产构建
npm run typecheck            # TypeScript 检查
npm run lint                 # ESLint
npm run check:format         # Prettier 格式检查
npm test                     # Vitest 单元测试
npm run test:coverage        # 核心模块覆盖率检查
npm run test:e2e             # Playwright Chromium 浏览器测试
npm run test:control-bridge   # 轻量机器人桥接测试，不依赖 LeRobot
npm run control-bridge        # 本机数值桥，默认 8766
npm run test:training-server # Python 训练桥接服务测试
npm run check                # 除 E2E 和 Ruff 外的完整检查

# Python 服务/插件/示例检查（使用项目 .venv）
python3 -m pip install -r requirements-dev.txt
npm run lint:python

仓库结构

.
├── web_platform/      React、TypeScript、Three.js 前端与测试夹具
├── training_server/   本机训练桥接服务及内置 Go2 PPO 训练代码/资产
├── controllers/       可导入平台的 Python 控制器示例
├── contracts/         跨语言机器人协议与 fixtures
├── robot_profiles/    唯一模型参数/单位/来源清单
├── control_bridge/    独立本机数值控制桥与通用 Python SDK
├── integrations/      可选上游集成（LeRobot）
├── examples/lekiwi/   资产准备、隔离环境安装及无硬件演示
├── package.json       根目录统一开发入口
└── LICENSE            Apache License 2.0

核心前端采用“应用壳 + 业务域 + 共享组件”分层：

• web_platform/src/app/：工作区编排、侧栏外壳、工具栏和全局对话框
• web_platform/src/components/ui/：无业务依赖的共享 UI 基础组件
• web_platform/src/project/：工程导入、路径规范化、项目树和 MEMFS
• web_platform/src/simulation/：MuJoCo WASM 会话、仿真调度及执行器控制 UI
• web_platform/src/viewer/：Three.js 渲染、选择和物理交互
• web_platform/src/map/：地图加载、创作、校验及对应 UI
• web_platform/src/robot/：机器人契约、profile、实时运行时及外部控制客户端/面板
• web_platform/src/controller/：Pyodide 控制器运行时及控制面板
• web_platform/src/rl/：ONNX 策略运行时、任务绑定及策略面板
• web_platform/src/training/：本地训练服务客户端、类型及训练面板
• web_platform/src/telemetry/：遥测数据源、记录器、导出与数据面板
• web_platform/src/stores/：跨业务域的应用状态

组件和测试优先与所属业务域共置；app/components/ 仅保留跨域编排和应用壳组件，避免业务逻辑继续集中到单一侧栏文件。

详细使用说明见 web_platform/README.md，前端依赖边界见 web_platform/ARCHITECTURE.md，训练服务说明见 training_server/README.md。

LeKiwi / LeRobot

按 LeKiwi 示例 重建固定版本模型、安装 build/venvs/lerobot/ CPU 环境，再从工作台文件导入、选择 profile、连接本机桥并明确授权。已有训练 .venv 不安装 LeRobot，也不修改上游代码。支持底盘、臂、夹爪与实测状态；外控桥不提供相机、dataset、锁步或训练 RPC；RL 训练走下述独立训练服务。

通用接口/能力矩阵 · 桥接协议与安全 · LeRobot 插件 · URDF 变体支持与控制边界。LeKiwi profile 支持换色/格式等机械语义等价变体，但拒绝拓扑、轴向、几何和动力学变化；New_urdf 的七关节新臂不兼容旧控制。普通 CI 不安装重型上游依赖；npm run test:e2e:lekiwi 是独立的真实物理/60 秒兼容验收。

移动操作强化学习

训练统一在主工作台「控制台 → 强化学习任务」：导入 ZIP、选择 LeKiwi v1/Bundle 移动操作场景，连接训练服务后一键启动、查看日志/Loss、导入 ONNX 并运行。不再下载训练包或手动运行训练脚本；使用 --mobile-python 隔离 MuJoCo 3.11/SB3 依赖，不改 Go2 环境。支持原始 lekiwi-v1 和 Link1…Link4 新臂 bundle 独立适配，不改变旧外控 profile 的来源/拓扑限制。

v2 固定92维观测、12维动作，策略严格匹配机器人变体和安全动作语义。默认先训练底盘接近，评估达标后依次训练末端接近、抓取放置；见 分阶段训练。旧68维策略需重新训练。独立 /mobile.html 产品页已移除，RL/ONNX 底层和 /physics/mobile.html 测试夹具保留。主工作台新版「控制台 → 机器人语言控制」提供预设单方块搬运和世界坐标目标，见 语言控制；本轮已验证真实物理＋假模型闭环，真实 LLM/Jev 尚未验收。历史 v1 API 与订阅登录记录在该文档单独保留，不代表新版验证结果。不包含已收敛的抓取策略，不承诺跨机器人泛化。

架构、数学契约、依赖隔离、训练与验证指南。真实浏览器回归：npm run test:e2e:mobile（需要本地 ZIP）。

数据与安全边界

模型、资源、Python 控制器和 ONNX 策略默认只在当前浏览器会话中处理。用户点击移动操作训练时，会将组合后的模型与资产快照自动上传到所连接的本地训练服务；上传有认证、大小和路径校验。训练桥接服务只监听本机回环地址，并仅执行服务端允许列表中的任务。启用自调参时，DeepSeek 只接收脱敏后的奖励参数、曲线摘要和评估数值；API key 仅存在训练服务环境中，不进入浏览器、URL、SQLite 或训练日志。

机器人控制桥与训练桥是两个服务（分别 8766 / 8765），不共享令牌或训练执行能力。控制令牌只保存在页面内存；外控超时、隐藏、暂停、重载均撤销授权，必须手动重新允许。

上游与许可证

本项目使用 Google DeepMind 的 MuJoCo WebAssembly npm 包，并保留 Apache License 2.0 许可证。MuJoCo 是 Google DeepMind 的开源项目；本仓库不是 Google 官方支持的产品。