# 附录 B: 详细安装指南

## 环境要求

### Python 版本
- Python 3.10+
- 推荐 Python 3.11

### 操作系统支持
- **Linux**: Ubuntu 20.04+, Debian 11+
- **macOS**: macOS 11+
- **Windows**: Windows 10+ (WSL2 推荐)

### 系统依赖
- C++ 编译器 (gcc/g++ 或 clang)
- CMake 3.15+
- Git

---

## 安装方式

### 使用 uv 安装 (推荐)

```bash
# 安装 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
```

### 使用 pip 安装

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

# 安装
pip install -e .
```

### 从源码安装

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

# 安装
pip install -e .
```

---

## 开发环境配置

### 克隆仓库

```bash
git clone <repository-url>
cd simkit
```

### 安装开发依赖

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

### 运行测试

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

### 代码风格检查

```bash
# 格式化
uv run ruff format .

# Lint
uv run ruff check .
```

---

## 仿真器安装

### ManiSkill 安装与配置

```bash
# 安装 ManiSkill
pip install mani_skill

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

### SAPIEN 安装与配置

```bash
# 安装 SAPIEN
pip install sapien

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

### MuJoCo 安装与配置

```bash
# 安装 MuJoCo
pip install mujoco

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

---

## 常见问题

### 安装失败排查

1. **Python 版本不匹配**
   ```bash
   python --version  # 确保 >= 3.10
   ```

2. **依赖冲突**
   ```bash
   # 使用 uv 自动解决冲突
   uv sync
   ```

3. **C++ 编译器缺失**
   ```bash
   # Ubuntu/Debian
   sudo apt install build-essential
   
   # macOS
   xcode-select --install
   ```

### 依赖冲突解决

```bash
# 清除缓存
pip cache purge

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

### stale editable install / 路径不一致

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

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

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

验证当前 venv 的导入路径：

```bash
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
```

### 仿真器特定问题

**ManiSkill**: 确保 Vulkan 驱动已安装

![Vulkan 诊断](_static/features/analysis/vulkan_diag_test.png)
*Vulkan 诊断测试*

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

---

## GPU 加速配置 (可选)

### CUDA 要求
- CUDA 11.8+
- NVIDIA 驱动 520+

### PyTorch GPU 版本安装

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

### 验证 GPU 支持

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