sim2lerobot

具身智能 8 层 pipeline 中 Layer 2 数据生成层 + Layer 3 数据处理层 的教学型实现。

定位：说明性仓库，目标是让任何新人看到代码和 docs 就能理解 L2/L3 在做什么、并跑通每一步。详细背景见 docs/guide/pipeline.md。

数据流

L0 USD assets (Franka, DexCube, ...)
  │
  ▼
L1 IsaacLab env (Isaac-Lift-Cube-Franka-IK-Abs-v0)
  │
  ▼ env.step() + RecorderManager
L2 三种轨迹来源（并列、可混合）
   ├─ l2/scripted/   手写 SM / motion planner
   ├─ l2/rl/         训练 policy + rollout 录制
   └─ l2/teleop/     人类遥操作
  │
  ▼ 每条 pipeline 产出
data/demos/<source>_<task>.hdf5   ← L2 中间产物（IsaacLab 官方 HDF5 schema）
  │
  ▼ l3/convert.py（独立 venv）
data/lerobot/<dataset>/           ← L3 最终产物（LeRobot dataset v2.1，GR00T 1.7 魔改 schema*）
  │
  ▼ （仓库范围之外）
GR00T N1.7 LoRA finetune

*"v2.1 magic version + v2.0 风格全局 meta/stats.json(带 q01/q99 6 字段)" 的混合体——是 NVIDIA 自家魔改,不是纯 lerobot v2.1。详见 GR00T 1.7 Dataset 约束。

双 venv 架构

venv	路径	装什么	干什么
L2 venv	`./l2/.venv/`	IsaacSim 6.0.0 + IsaacLab + torch 2.10 cu128	L2 三个子目录共享
L3 venv	`./l3/.venv/`	`lerobot==0.3.3` + CPU torch	L3 HDF5 → LeRobot v2 转换

为什么拆：LeRobot 的依赖与 IsaacSim 冲突；分开后用 HDF5 文件作为两个 venv 之间的边界。详见 LeRobot 版本研究。

实现状态

维护约定：每次新增 / 调整 / 砍掉某个能力,都要同步本小节。这是新人入口的"真相"—— README 与代码不一致比没有 README 还误导。详见 CLAUDE.md "工作约定"。

图例:✅ 已完成、🚧 进行中、📋 计划、⏭️ 不在范围。

L2 数据生成层

子目录	状态	要点
`l2/scripted/`	✅	Pick-and-Lift SM,8d IK-abs action,产 `scripted_lift_cube.hdf5`
`l2/rl/`	✅	rsl_rl PPO (joint_pos task) + rollout 录制重写成 8d IK-abs,产 `rl_lift_cube.hdf5`。详见 `l2/rl/README.md`
`l2/teleop/`	✅	keyboard 最小版,30Hz,8d IK-abs (rel→abs 在 adapter 里做),产 `teleop_lift_cube.hdf5`
相机 obs (`obs/images/*`)	📋	scripted/rl/teleop 三来源都没出 RGB;VLA 训练必需。`l2/scripted/env_cfg.py` 已留 `--with_camera` 扩展点注释
SpaceMouse / VR / OpenXR teleop	⏭️	接口跟 keyboard 同形 (7d delta),需硬件验证,留给生产仓库

L3 数据处理层

组件	状态	要点
`l3/convert.py`	✅	HDF5 → LeRobot v2.1,GR00T N1.7 兼容(全局 `stats.json` + 6 字段)
三来源合并端到端 e2e	🚧	单来源已分别 verify,把 `scripted_.hdf5 + rl_.hdf5 + teleop_*.hdf5` 一次性合到同一个 dataset 还没正式跑过
质量过滤 (噪声 / 抖动 episode 剔除)	📋	CLAUDE.md 列入硬性要求,目前 `convert.py` 只格式转换
统计 / 可视化工具	📋	episode 长度分布、success/failure 比例、action 范围
Cosmos 视觉增强接口文档	📋	CLAUDE.md 说"即使不实现也要在 doc 中说明接口和数据流向"

跨层 / 文档

项	状态	要点
`tools/h5_inspect.py`	✅	跨来源用,看 HDF5 schema 是否对齐
`l2/verify_isaac.py`	✅	L2 venv 烟雾测试
`docs/` 体系	✅	guide / schema / research 三目录全部就位
仓库根 README pipeline 总览图	✅	见上方"数据流"

跑通顺序（建议第一次走这条线）

bash

# 0. 装 L2 venv(只跑一次)
cd l2 && uv sync && cd ..

# 1. 验证主 venv（IsaacLab reset/step 烟雾测试）
uv run --project l2 python l2/verify_isaac.py

# 2. 用 scripted SM 采一批种子轨迹（默认 4 envs，10 个 success 大约 30 秒）
uv run --project l2 python l2/scripted/collect.py --num_demos 10 --num_envs 4

# 3. 看一眼 HDF5 schema 是否符合预期
uv run --project l2 python tools/h5_inspect.py data/demos/scripted_lift_cube.hdf5

# 4. 切到 L3 venv，转 LeRobot v2
cd l3 && uv sync
uv run python convert.py ../data/demos/scripted_lift_cube.hdf5 ../data/lerobot/lift_cube_v0/

# 5. RL 来源（先训 PPO,再 rollout 录数据）
uv run --project l2 python l2/rl/train.py
uv run --project l2 python l2/rl/rollout_and_record.py --checkpoint l2/rl/checkpoints/lift_cube/latest.pt --num_demos 100

# 6. teleop 来源（手动键盘操作,WASDQE/ZXTGCV 移动 + K 切夹爪）
uv run --project l2 python l2/teleop/record.py --num_demos 5

目录结构

sim2lerobot/
├── README.md                       # 本文件
├── CLAUDE.md                       # 给 Claude 的契约（重要约定都在这）
├── package.json                    # VitePress 文档站
├── .vitepress/                     # VitePress 配置 + 构建产物（dist/ 已 gitignored）
├── docs/                           # 系统性文档（"为什么这么设计"）
│   ├── guide/                      # 入门、环境（00 / 05 / 10）
│   ├── schema/                     # 字段定义 / 硬性契约（20–50）
│   └── research/                   # 调研留痕（60 / 70）
├── data/                           # 产物（gitignored）
│   ├── demos/                      # L2 中间产物（HDF5）
│   └── lerobot/                    # L3 最终产物（LeRobot dataset v2.1）
├── tools/                          # 跨 venv 的小工具
│   └── h5_inspect.py               # HDF5 schema 检查（L2 / L3 venv 都能跑）
├── l2/                             # L2 数据生成层（共享 venv）
│   ├── pyproject.toml              # IsaacSim + IsaacLab + rsl-rl
│   ├── verify_isaac.py             # L2 venv 烟雾测试
│   ├── scripted/                   # L2 来源 #1
│   ├── rl/                         # L2 来源 #2
│   └── teleop/                     # L2 来源 #3
├── l3/                             # L3 数据处理层（独立 venv：lerobot + CPU torch）
│   ├── pyproject.toml
│   └── convert.py                  # HDF5 → LeRobot dataset v2.1
└── IsaacLab/                       # 上游源码（gitignored）

每个子目录有自己的 README，讲清"做什么、怎么跑、坑在哪、产物在哪"。

在浏览器里看文档

仓库根带一个 VitePress 静态文档站,把所有 markdown 渲染成可搜索、有 TOC、深浅色主题的网页。

bash

pnpm install            # 第一次装,只跑一次(用 corepack 启用的 pnpm)
pnpm dev                # 起 http://127.0.0.1:5173

改任何 markdown 都会热刷新。配置在 .vitepress/config.mts,build 产物在 .vitepress/dist/(gitignored)。

sim2lerobot ​

数据流 ​

双 venv 架构 ​

实现状态 ​

L2 数据生成层 ​

L3 数据处理层 ​

跨层 / 文档 ​

跑通顺序（建议第一次走这条线） ​

目录结构 ​

在浏览器里看文档 ​