# HUSKY: Humanoid Skateboarding System via Physics-Aware Whole-Body Control

基于 [HUSKY](https://arxiv.org/abs/2602.03205) 思路的人形滑板全身控制实验代码：mjlab 训练、`rsl_rl` 与 MuJoCo 评测脚本。本仓库包含个人开发与 **Docker** 封装。

**目录：** [`src/mjlab_husky`](src/mjlab_husky) · [`rsl_rl/`](rsl_rl/) · [`dataset/`](dataset/) · [`test_scene/`](test_scene/) · [`ckpts/`](ckpts/)

---

## 本地安装（Ubuntu 22.04，推荐 `uv`）

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/<你的用户名>/humanoid_skateboarding.git
cd humanoid_skateboarding
uv sync && uv pip install -e .
```

**（可选）LeRobot v3 导出 / 边播边录** 需要额外安装 `lerobot`（不在默认依赖里，以免与现有 PyTorch/CUDA 栈冲突）：

```bash
uv pip install lerobot
```

若安装 `lerobot` 等包后出现 `import torch` 报 **NCCL 符号错误**（例如 `undefined symbol: ncclDevCommDestroy`）：多为 **`nvidia-nccl-cu12` 与 `torch`（cu13）并存**，二者都往 `site-packages/nvidia/nccl/lib/` 装 `libnccl.so.2`，旧库覆盖了新库。可卸载 cu12 并重装 cu13 的 NCCL：

```bash
uv pip uninstall nvidia-nccl-cu12
uv pip install --force-reinstall "nvidia-nccl-cu13>=2.29"
```

---

## 训练

```bash
cd humanoid_skateboarding
uv run train Mjlab-Skater-Flat-Unitree-G1 --env.scene.num-envs 4096
```

查看全部参数：

```bash
uv run train Mjlab-Skater-Flat-Unitree-G1 --help
```

---

## 回放 `play`

任务名固定为 **`Mjlab-Skater-Flat-Unitree-G1`**（注册在 `mjlab_husky.tasks`）。

### 通用

```bash
uv run play Mjlab-Skater-Flat-Unitree-G1 --checkpoint_file ckpts/test.pt
```

- **`--viewer auto`**（默认）：有 `DISPLAY` / `WAYLAND_DISPLAY` 时用 **native**，否则 **rerun**。
- **`--viewer native`**：本机有图形界面时使用 MuJoCo 原生窗口。
- **`--viewer rerun`**：Rerun Web Viewer（无头服务器常用）。
- **`--viewer rerun_native`**：同一套 mjlab 仿真与策略步进，**同时**打开仓库自带的 **MuJoCo 原生 viewer**（`NativeMujocoViewer` / GLFW）并把离屏相机 / qpos **推到 Rerun**。与「两个进程各跑一套仿真」无关：仍是 **单一 `env`/单一仿真循环**。**不能**与 `--lerobot-record` 共用。
- **`--viewer viser`**：Viser（浏览器三维面板，另一种自带前端）。
- **`--viewer rerun_viser`**：**同一进程、单一仿真**，同时在浏览器里打开 **Rerun**（`--rerun-web-port` / `--rerun-grpc-port`）与 **Viser mjlab 面板**（`--viser-port`）。三者各占不同端口；适合 RoboHub 左 Rerun、右 Mujoco 双 iframe。  
  - **注意**：`rerun_native` 里的 **native 是 GLFW 桌面窗口，不占用 HTTP 端口**；若你要「两个端口都是网页服务」，用 **`rerun_viser`**，不要用 `rerun_native` 来凑端口。

`rerun_native` 示例（端口与 `rerun` 相同，见下节 SSH 转发）：

```bash
uv run play Mjlab-Skater-Flat-Unitree-G1 --checkpoint_file ckpts/test.pt \
  --viewer rerun_native --rerun-web-port 18080 --rerun-grpc-port 19876
```

`rerun_viser` 示例（**三个端口**：Rerun Web、Rerun gRPC、Viser，互不重复）：

```bash
uv run play Mjlab-Skater-Flat-Unitree-G1 --checkpoint_file ckpts/test.pt \
  --viewer rerun_viser \
  --rerun-web-port 18080 \
  --rerun-grpc-port 19876 \
  --viser-port 19090
```

远程浏览器需 **三个** 本地转发（把示例端口换成你实际用的）：

```bash
ssh -N \
  -L 18080:127.0.0.1:18080 \
  -L 19876:127.0.0.1:19876 \
  -L 19090:127.0.0.1:19090 \
  user@云主机
```

**SSH / 无桌面 / RoboHub 技能里 `RuntimeError: … DISPLAY`：**  
`rerun_native` 里的「自带 viewer」是 **本机 X11/Wayland 上的 GLFW 窗口**，不是 Rerun 网页。若 shell 里 **没有** `DISPLAY` 或 `WAYLAND_DISPLAY`（很多容器/编排默认不传），会报错。处理方式：

- **只想要浏览器里看 Rerun**（单后端、无 MuJoCo 小窗）：用 `--viewer rerun`。
- **仍要 `rerun_native` 但机器无物理桌面**：可装 `xvfb` 用虚拟显示，例如：  
  `xvfb-run -a uv run play Mjlab-Skater-Flat-Unitree-G1 ... --viewer rerun_native`  
  （具体以你镜像是否已含 `xvfb` 为准。）
- **RoboHub 侧**：需在技能/容器环境注入 `DISPLAY` 或把启动命令包在 `xvfb-run` 里，否则与本地终端直跑表现一致。

完整参数：

```bash
uv run play Mjlab-Skater-Flat-Unitree-G1 --help
```

### 无头 OpenGL（MuJoCo 离屏相机）

在无 `DISPLAY` / `WAYLAND_DISPLAY` 的 Linux 上，`play` 等在 **`import mujoco` 之前** 调用 `mujlab_husky/mujoco_gl.py`：未设置 `MUJOCO_GL` 时默认 **`osmesa`**。仅设 `MUJOCO_GL` 不够：无头时 PyOpenGL 仍可能按 `linux` 选 **GLX**，导致 `glGetError` / `eglQueryString`；因此脚本会同步设置 **`PYOPENGL_PLATFORM=osmesa`**（或在你使用 `MUJOCO_GL=egl` 时为 **`egl`**）。可按需手动指定：

```bash
export MUJOCO_GL=egl          # GPU + 可用 NVIDIA EGL 时（更快）
# 未设置时由 mujoco_gl 默认 osmesa；或显式 CPU 光栅：
export MUJOCO_GL=osmesa       # 需系统已装 libosmesa6（见下）
```

**Ubuntu（OSMesa）**：若仍报 OpenGL / `glGetError`，请先安装运行时：

```bash
sudo apt-get update && sudo apt-get install -y libosmesa6
```

若报错 **`mjENBL_MULTICCD`**：来自 **MuJoCo Python 枚举与 `mujoco-warp` Git 修订不一致**。本项目用 PyPI `mujoco==3.8.x` 时，`uv.lock` 已将 **`mujoco-warp` 固定为上游标签 `v3.8.0`**；若在别处自行 `uv lock --upgrade-package mjlab`，需再次确认锁里两处一致。

### Rerun：端口与远程浏览器

Rerun 需要 **两个端口**：**Web**（默认 `8080`）+ **gRPC**（默认多为 `9876`，以终端打印为准）。

**浏览器与 `play` 在同一台机器**：直接打开终端里 **`http://127.0.0.1:<web_port>/?url=...`** 完整链接（不要只打开无 `?url=` 的首页）。

**浏览器在自己电脑、`play` 在云主机**：必须在本机做 **SSH 双端口转发**（把 `user@host` 换成你的登录方式，端口与 `play` 一致）：

```bash
ssh -N -L 8080:127.0.0.1:8080 -L 9876:127.0.0.1:9876 user@云主机IP
```

若使用 `~/.ssh/config` 里的 `Host` 别名（例如 `Seoul`）：

```bash
ssh -N -L 8080:127.0.0.1:8080 -L 9876:127.0.0.1:9876 Seoul
```

指定密钥时：

```bash
ssh -i ~/.ssh/你的_key -N -L 8080:127.0.0.1:8080 -L 9876:127.0.0.1:9876 ubuntu@云主机IP
```

**本机 8080/9876 已被占用**时，改用空闲本地端口，并同时改 `?url=` 里 gRPC 端口，例如：

```bash
ssh -N -L 18080:127.0.0.1:18080 -L 19876:127.0.0.1:19876 user@云主机IP
```

云主机上 `play` 需一致：

```bash
uv run play Mjlab-Skater-Flat-Unitree-G1 --checkpoint_file ckpts/test.pt \
  --viewer rerun \
  --rerun-web-port 18080 \
  --rerun-grpc-port 19876
```

**不经 SSH、浏览器直连公网**：安全组放行 Web + gRPC 端口，并指定（示例）：

```bash
uv run play ... --viewer rerun --rerun-connect-host <云主机公网IP>
```

### Rerun 常用性能参数（可选）

```bash
uv run play Mjlab-Skater-Flat-Unitree-G1 --checkpoint_file ckpts/test.pt \
  --viewer rerun \
  --rerun-viewer-width 640 --rerun-viewer-height 360 \
  --rerun-camera-log-stride 4 --rerun-qpos-log-stride 8 \
  --rerun-camera-max-side 480 \
  --no-rerun-open-browser
```

说明：本项目 CLI 使用 **tyro**，布尔开关一般为 **`--xxx` / `--no-xxx`**（例如 `--lerobot-record`、`--no-rerun-open-browser`），不要写成 `--lerobot-record True`。

---

## LeRobot v3 数据（`lerobot_data/`）

LeRobot **v3** 为 **Parquet + `meta/`**（不是 HDF5）。本仓库提供两种方式写入 **`observation.state`（qpos，float32 向量）**。

### 1）离线批量导出（不跑 Rerun）

需已 `uv pip install lerobot`。

```bash
uv run python -m mjlab_husky.scripts.export_lerobot_qpos \
  --task-id Mjlab-Skater-Flat-Unitree-G1 \
  --checkpoint-file ckpts/test.pt \
  --out-dir lerobot_data \
  --dataset-name mjlab_husky_skater_qpos \
  --episodes 1 \
  --steps-per-episode 1000 \
  --overwrite
```

### 2）`play` + Rerun 同时边播边录

```bash
uv run play Mjlab-Skater-Flat-Unitree-G1 \
  --checkpoint_file ckpts/test.pt \
  --viewer rerun \
  --rerun-web-port 18080 \
  --rerun-grpc-port 19876 \
  --lerobot-record \
  --lerobot-out-dir lerobot_data \
  --lerobot-dataset-name mjlab_husky_live \
  --lerobot-overwrite
```

要点：

- **`--lerobot-overwrite`**：每次启动会 **删除** 同名数据集目录；要 **累积** 多次运行，请 **去掉** 该参数，或换 `--lerobot-dataset-name`。
- 默认每录满 **`--lerobot-steps-per-episode`**（默认 1000）帧会 `save_episode()` 一次；仿真里多次 `reset` **不会**自动切分，除非打开 **`--lerobot-save-on-env-reset`**。
- 退出 `play`（如 Ctrl+C）时会 `finalize()`，避免 Parquet 不完整。

按仿真每次 `done -> reset` 存成一个 LeRobot episode：

```bash
uv run play Mjlab-Skater-Flat-Unitree-G1 ... --lerobot-record --lerobot-save-on-env-reset
```

### 检查数据集是否可读（行数 / episode）

```bash
uv run python -c "
from pathlib import Path
import json
info = json.loads(Path('lerobot_data/mjlab_husky_live/meta/info.json').read_text())
print('total_episodes', info.get('total_episodes'), 'total_frames', info.get('total_frames'))
"
```

---

## Docker（推荐）

基础环境：Ubuntu 22.04、CUDA 13、`uv` 与项目依赖。镜像 **`MUJOCO_GL=egl`**，默认 **`CMD`** 为 **Rerun** 回放（`--no-rerun-open-browser`）。

**构建**

```bash
docker build -t husky-skate:latest .
```

**GPU 运行**（需 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)）

```bash
docker run --gpus all -it --rm -p 8080:8080 -p 9876:9876 husky-skate:latest
```

在**宿主机浏览器**打开容器日志里打印的 **`http://127.0.0.1:8080/?url=...`**（若浏览器不在宿主机，需自行把对应端口转发到本机）。

**宿主机 8080/9876 已被占用**（例如已有其他容器映射）：换主机端口 + 覆盖容器内 `play` 端口，例如：

```bash
docker run --gpus all -it --rm -p 18080:18080 -p 19876:19876 husky-skate:latest \
  uv run play Mjlab-Skater-Flat-Unitree-G1 --checkpoint_file ckpts/test.pt \
    --viewer rerun \
    --rerun-web-port 18080 \
    --rerun-grpc-port 19876 \
    --no-rerun-open-browser
```

**仅 CPU**（较慢）

```bash
docker run -it --rm -p 8080:8080 -p 9876:9876 husky-skate:latest
```

**进入容器 Shell**

```bash
docker run --gpus all -it --rm --entrypoint /bin/bash husky-skate:latest
```

**容器内训练**

```bash
docker run --gpus all -it --rm husky-skate:latest \
  uv run train Mjlab-Skater-Flat-Unitree-G1 --env.scene.num-envs 4096
```

**（可选）容器内录 LeRobot**：需先安装 `lerobot`，并把目录挂载出来，例如：

```bash
docker run --gpus all -it --rm \
  -p 18080:18080 -p 19876:19876 \
  -v "$(pwd)/lerobot_data:/app/lerobot_data" \
  husky-skate:latest \
  bash -lc 'uv pip install lerobot && uv run play Mjlab-Skater-Flat-Unitree-G1 \
    --checkpoint_file ckpts/test.pt --viewer rerun \
    --rerun-web-port 18080 --rerun-grpc-port 19876 --no-rerun-open-browser \
    --lerobot-record --lerobot-out-dir lerobot_data --lerobot-dataset-name mjlab_docker_live \
    --lerobot-overwrite'
```

---

## PyTorch / CUDA 提示

若日志出现 **driver too old（如 12080）** 且 `torch.cuda.is_available()` 为 `False`，多为 **PyTorch cu13x 与当前驱动 API 不匹配**。可选：

- 安装与驱动匹配的 **cu12x** 轮子，例如：  
  `uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124`
- 或升级宿主机 NVIDIA 驱动以匹配当前 PyTorch 所要求的 CUDA。

仿真侧 **Warp/MuJoCo** 仍可能显示 `cpu`，与 **`torch.cuda.is_available()` 为 `play` 选的 device** 一致。

---

## 轻量 MuJoCo 评测

```bash
bash test_scene/sim.sh your-onnx-path
```

| Viser | MuJoCo |
|-------|--------|
| ![](media/viser.gif) | ![](media/mjc.gif) |

---

## 论文引用（原论文）

```bibtex
@article{han2026husky,
  title={HUSKY: Humanoid Skateboarding System via Physics-Aware Whole-Body Control},
  author={Jinrui Han and Dewei Wang and Chenyun Zhang and Xinzhe Liu and Ping Luo and Chenjia Bai and Xuelong Li},
  journal={arXiv preprint arXiv:2602.03205},
  year={2026}
}
```