# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概览

西交利物浦大学（XJTLU）课程作业仓库，包含三个独立子项目：

| 子目录 | 课程 | 任务 | 算法 |
|--------|------|------|------|
| `CW1_id_name/` | DTS307TC RL | CarRacing-v3 自动驾驶 | PPO（从零实现） |
| `强化学习个人项目报告（Atari 游戏方向）/` | DTS307TC RL | Space Invaders 游戏 | DQN / Double DQN / Dueling |
| `强化学习个人课程作业报告/` | DTS304TC ML | 健康保险保费风险预测 | XGBoost + Optuna 调参 |

## Python 环境

- **默认环境**: `D:\ProgramData\anaconda3\envs\my_env`
- **包管理器**: `uv`（位置: `D:\settings\uv`）
- **GPU**: RTX 4060 Laptop, CUDA 12.1, PyTorch 2.4.0+cu121
- 安装依赖时必须指定 Python 路径，避免库装到用户目录

## 常用命令

### CW1 - PPO CarRacing

```powershell
# 安装依赖（注意 box2d 编译问题，Windows 下可能需要先装 swig）
pip install -r CW1_id_name/requirements.txt

# 向量化训练（推荐）
python CW1_id_name/train_vec.py --n-envs 4 --total-steps 500000 --run-name vec_main --anneal-lr --anneal-ent --reward-clip 1.0

# 评估
python CW1_id_name/evaluate.py --ckpt CW1_id_name/models/vec_main_v3/final.pt
python CW1_id_name/evaluate.py --ckpt CW1_id_name/models/vec_main_v3/final.pt --video  # 生成 demo.mp4

# TensorBoard 监控
tensorboard --logdir=CW1_id_name/runs --port=6006
```

### Atari DQN

```powershell
# 训练
python "强化学习个人项目报告（Atari 游戏方向）/train.py" --steps 2000000

# 评估 checkpoint
python "强化学习个人项目报告（Atari 游戏方向）/evaluate_checkpoints.py"

# 生成训练曲线图
python "强化学习个人项目报告（Atari 游戏方向）/generate_plots.py"
```

### 保险保费预测（ML 作业）

```powershell
# 使用 uv 安装依赖
cd "强化学习个人课程作业报告"
uv pip install -r pyproject.toml

# 主 notebook
jupyter notebook "强化学习个人课程作业报告/notebooks/insurance_premium_risk.ipynb"
```

## 架构说明

### CW1_id_name（PPO）

核心组件在 `src/` 下，**不依赖 Stable-Baselines3**（SB3 仅用于外部 baseline 对比）：
- `networks.py` — 共享 CNN 的 ActorCritic 网络
- `ppo_agent.py` — PPO-Clip 智能体（act / update / lr schedule）
- `vec_rollout_buffer.py` — 向量化 rollout 缓冲区 + GAE
- `vec_env_wrappers.py` — AsyncVectorEnv 工厂
- `env_wrappers.py` — SkipFrame / GrayScaleResize / FrameStack
- `eval_utils.py` — 评估、绘图、录像

**重要**: `train_vec.py` 底部必须有 `if __name__ == "__main__"` 保护，否则 Windows 上 AsyncVectorEnv 会无限 spawn 子进程。

### Atari DQN

核心组件在 `强化学习个人项目报告（Atari 游戏方向）/src/` 下：
- `network.py` — QNetwork 和 DuelingQNetwork
- `agent.py` — DQN 智能体（ε-greedy + Double DQN）
- `replay_buffer.py` — 经验回放 + 优先经验回放（PER）
- `trainer.py` — 训练循环
- `evaluate.py` — 模型评估

### 保险保费预测

- 主逻辑在 `notebooks/insurance_premium_risk.ipynb`
- `src/` 下有 notebook_runner 和 runtime_paths 辅助模块
- 输出在 `outputs/`（figures / tables / predictions）

## 注意事项

- `.gitignore` 排除了 `*.pt` / `*.pth` 模型文件，但当前 git 中仍有已追踪的模型
- 训练日志（TensorBoard events）在 `runs/` 目录下
- 代码注释使用中文