21. 附录 B: 详细安装指南¶

21.1. 环境要求¶

21.1.1. Python 版本¶

Python 3.10+
推荐 Python 3.11

21.1.2. 操作系统支持¶

Linux: Ubuntu 20.04+, Debian 11+
macOS: macOS 11+
Windows: Windows 10+ (WSL2 推荐)

21.1.3. 系统依赖¶

C++ 编译器 (gcc/g++ 或 clang)
CMake 3.15+
Git

21.2. 安装方式¶

21.2.1. 使用 uv 安装 (推荐)¶

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆仓库
git clone <repository-url>
cd simkit

# 安装依赖
UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv sync

21.2.2. 使用 pip 安装¶

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate  # Windows

# 安装
pip install -e .

21.2.3. 从源码安装¶

# 克隆仓库
git clone <repository-url>
cd simkit

# 安装
pip install -e .

21.3. 开发环境配置¶

21.3.1. 克隆仓库¶

git clone <repository-url>
cd simkit

21.3.2. 安装开发依赖¶

uv sync --dev
# 或
pip install -e ".[dev]"

21.3.3. 运行测试¶

uv run python -m pytest test/
# 或
python -m pytest test/

21.3.4. 代码风格检查¶

# 格式化
uv run ruff format .

# Lint
uv run ruff check .

21.4. 仿真器安装¶

21.4.1. ManiSkill 安装与配置¶

# 安装 ManiSkill
pip install mani_skill

# 验证安装
python -c "import mani_skill; print(mani_skill.__version__)"

21.4.2. SAPIEN 安装与配置¶

# 安装 SAPIEN
pip install sapien

# 验证安装
python -c "import sapien; print(sapien.__version__)"

21.4.3. MuJoCo 安装与配置¶

# 安装 MuJoCo
pip install mujoco

# 获取许可证 (可选，用于高级功能)
# 访问 https://www.roboti.us/license.html

21.5. 常见问题¶

21.5.1. 安装失败排查¶

Python 版本不匹配
```
python --version  # 确保 >= 3.10
```
依赖冲突
```
# 使用 uv 自动解决冲突
uv sync
```

C++ 编译器缺失

# Ubuntu/Debian
sudo apt install build-essential

# macOS
xcode-select --install

21.5.2. 依赖冲突解决¶

# 清除缓存
pip cache purge

# 重新安装
pip install --force-reinstall -e .

21.5.3. stale editable install / 路径不一致¶

如果在临时目录或历史脚本中遇到 ModuleNotFoundError: No module named 'simkit'，或发现旧 editable finder 指向历史路径 /root/.openclaw/workspace-simkit，请以当前仓库为准重新同步环境：

cd /root/.openclaw/workspace/simkit
uv sync

# 不在仓库目录内运行脚本时，显式指定当前项目路径
PYTHONPATH=/root/.openclaw/workspace/simkit \
  /root/.openclaw/workspace/simkit/.venv/bin/python your_script.py

验证当前 venv 的导入路径：

cd /tmp
/root/.openclaw/workspace/simkit/.venv/bin/python -c \
  "import pathlib, simkit; print(pathlib.Path(simkit.__file__).resolve())"
# 期望输出：/root/.openclaw/workspace/simkit/simkit/__init__.py

21.5.4. 仿真器特定问题¶

ManiSkill: 确保 Vulkan 驱动已安装

Vulkan 诊断测试

SAPIEN: 确保 OpenGL 支持 MuJoCo: 许可证文件放置在 ~/.mujoco/

21.6. GPU 加速配置 (可选)¶

21.6.1. CUDA 要求¶

CUDA 11.8+
NVIDIA 驱动 520+

21.6.2. PyTorch GPU 版本安装¶

# 安装 GPU 版 PyTorch
pip install torch --index-url https://download.pytorch.org/whl/cu118

21.6.3. 验证 GPU 支持¶

import torch
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"CUDA version: {torch.version.cuda}")