# 问题3/4 强化学习选点（PPO + CUDA）

## 0. 摘要

本项目在保持 P0–P5 保守性与可解释证明不变的前提下，为问题3（全向源）与
问题4（定向源）增加了一个可选的**强化学习测量点选择策略**：

- 把“下一检测点去哪”建模为离散决策马尔可夫决策过程（MDP）；
- 状态由逐频道信念的几何特征 + 60 个候选检测点的几何特征组成（401 维）；
- 动作为 60 选 1（保证接收盘环候选、对称交会候选、定向遮挡环探候选）；
- 使用 Stable-Baselines3 的 PPO 训练，MLP 策略与价值网络在 **CUDA GPU**
  （本机 RTX 4060 Laptop, CUDA 12.8 / torch 2.11.0+cu128）上更新；
- 训练环境基于自建评测机 `referee`（内存回环，与真实 HTTP 协议同边界）；
- 运行闭环仅替换既有选点排序器，覆盖证明、清除证书、定向后备清除全部保留。

结论（自建配对消融，5 个种子）：Q3 用 12 万步随机初始化 PPO（与 `bayes`
基本持平，+1.18%）；Q4 用**专家行为克隆初始化 + PPO 微调**，混合源平均
虚拟时间相对 `directional` 基线降低 **7.16%**（14250.1s → 13230.2s）。
Q3 的 BC 初始化在消融中反而退化，因此保留随机初始化模型；Q4 的 BC 初始化
是当前最优。官方演练验证见 §5：两次 Q4 演练（3 定向混合源、10 定向全定向
场景）与一次 Q3 演练均全清，且通过离线审计。

## 1. 环境搭建（CUDA）

```powershell
# 安装可选依赖组 rl（PyTorch CUDA 12.8 + stable-baselines3 + gymnasium）
uv sync --group rl --group dev

# 验证 CUDA
uv run python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"
```

`pyproject.toml` 中 `[tool.uv.sources] torch = { index = "pytorch-cu128" }`
与 `[[tool.uv.index]]` 指向 PyTorch 官方 CUDA 12.8 轮子；下载约 2.6 GB，
首次同步建议 `$env:UV_HTTP_TIMEOUT='300'`。默认 PyPI 的 Windows torch 轮子
为 `+cpu`，不能直接训练。

## 2. MDP 定义

训练环境：`src/mcm26b/rl/env.py::LocalizationEnv`。

| 项 | 定义 |
| --- | --- |
| 初始状态 | 自建模拟器随机布设一个源（Q3 全向；Q4 定向比例可调，训练默认 1.0），机器狗完成一次保证得到 `direction` 的首测 |
| 观测 | 401 维：21 个全局特征 + 20 维频道 one-hot + 60×6 维候选点特征（见 `features.py`） |
| 动作 | `Discrete(60)`：0=候选集 MEC 圆心，1..36=保证接收盘 3 环×12 方向，37..51=对称交会 15 点，52..59=定向遮挡环探 8 点 |
| 转移 | 按动作位置调用 `/measure`，用 `BeliefState` 保守更新候选集；Q4 保证接收盘内 `no_signal` 记为朝向遮挡并进入 `blocked` 序列；证书达标后自动 `/clear`；遮挡梯子用尽后模拟 20m 网格后备清除 |
| 奖励 | `-Δvirtual_time/100`（移动+检测+换频+清除真实耗时）、候选半径收缩加成、首次遮挡证据 +2、重复测点 -0.75、清除成功 +10、失败/截断负奖励 |

约束说明：候选点全部来自既有几何生成器（`planner.candidate_points`、
`planner.safe_disk_radius`、定向环探梯子），RL 不生成新的空间候选；它只做
排序。因此 RL 决策不能破坏“保证接收盘内必收到方向”与清除证书的数学保证。

## 3. 训练与自建模拟器逻辑利用

```powershell
# 1) 用自建模拟器上的手写专家生成 (观测, 动作) 并行为克隆
uv run python scripts/pretrain_rl_expert.py --problem 3 --episodes 3000
uv run python scripts/pretrain_rl_expert.py --problem 4 --episodes 3000

# 2) 从 BC 初始化继续 PPO 微调（CUDA）
uv run python scripts/train_rl.py --problem 4 --timesteps 40000 \
    --init output/rl/q4_ppo_bc_init.zip

# Q3 保留随机初始化长训练版本：
uv run python scripts/train_rl.py --problem 3 --timesteps 120000
```

专家逻辑与自建模拟器同源：Q3 用 worst-posterior 选点器，Q4 用对跖/环探
遮挡梯子；`pretrain_rl_expert.py` 在 `LocalizationEnv` 上记录每个状态的
专家动作，训练与 PPO policy_net/action_net 同构的 MLP，再把权重拷入 PPO
作为初始化。产物位于 `output/rl/bc/` 与 `output/rl/q{3,4}_ppo_bc_init.zip`。

实测：Q3 专家数据 5141 条、BC 验证准确率 38.9%，微调后自建消融退化
（保留 12 万步随机初始化模型）；Q4 专家数据 14181 条、BC 验证准确率
65.3%，微调后自建消融从 −3.84% 提升到 **−7.16%**。这说明自建模拟器逻辑
在遮挡分支上可直接转化为 RL 的强先验，而全向分支的随机 PPO 已足够。

输出：`output/rl/q3_ppo.zip`、`output/rl/q4_ppo.zip` 及同名 JSON 报告；
训练脚本先打印 `train_start`（含 device/gpu 字段），再执行 PPO 并在独立
种子场景上确定性评估成功率、平均步数与平均回报。Q4 4 万步微调约 236s；
Q3 12 万步约 625s（RTX 4060 Laptop，2 个 CPU 环境）。

## 4. 运行闭环接入

- Q3：`uv run mcm26b run --robot-id 2026001 --self-test --strategy rl`
  `RLBayesLoop` 继承 `BayesLoop`（七点覆盖 + 网格粒子滤波 + 滚动 2-opt），
  仅 `_select_point` 改由 PPO 输出候选编号。
- Q4：`uv run mcm26b run --robot-id 2026001 --self-test --problem 4 --q4-strategy rl`
  `RLDirectionalLoop` 继承 `DirectionalExtension`（49 点覆盖 + 遮挡梯子 +
  20m 有限圆盘后备清除），仅 `_next_probe` 改由 PPO 输出。
- 模型加载时校验观测 401 维 / 动作 60 维，失配直接拒绝运行。
- 默认运行路径不导入 torch/referee；只有显式选择 `rl` 才惰性导入，项目
  运行时依赖仍保持 `requests` 一项。

## 5. 消融基准

```powershell
uv run python scripts/benchmark_rl.py --seeds 5
```

同种子同场景配对比较，结果写入 `output/rl/benchmark.json`。当前版本：

| 场景 | 基线 | 平均虚拟时间（基线 / RL） | 相对差 | 全清 |
| --- | --- | --- | --- | --- |
| Q3（10 源全向 ×5 种子，scratch PPO） | `bayes` | 3088.3s / 3124.8s | +1.18% | 5/5 |
| Q4（10 源、3 定向 ×5 种子，BC+PPO） | `directional` | 14250.1s / 13230.2s | −7.16% | 5/5 |

训练局评估：Q3 单源 40 局成功率 100%、平均 3.55 步；Q4 定向单源 40 局
成功率 90%、平均 4.45 步（其余由后备清除/二次定位兜底）。随机策略对照：
Q3 平均回报 13.28 vs PPO 17.71；Q4 平均回报 8.72 vs BC+PPO 12.62。

### 5.1 官方模拟器演练验证（仅演练，未触碰正式测试）

使用目录内官方 `jammers-simulator-full` 的**演练测试**（不限次数），通过
官方 HTTP 接口运行同一闭环；官方产物按原名归档并离线审计：

| 问题 | 案例 | 场景真值（演练结束后可见） | 结果 | 虚拟时间 | 请求数 | 审计 |
| --- | --- | --- | --- | --- | --- | --- |
| Q3 | `F38Y-9Q9J-B82V-CB9Z` | 13 全向 | 13/13 全清 | 3538.8s | 124 | ✅ |
| Q4 | `X43X-VMRF-8GRZ-3SYA` | 7 全向 + 3 定向 | 10/10 全清 | 14003.1s | 619 | ✅ |
| Q4(BC) | `BXSA-TFQ3-2DJ6-DHH7` | **10 定向** | 10/10 全清 | 14562.8s | 691 | ✅ |

前两次为随机初始化模型，第三次为 BC 初始化微调模型。两个 Q4 官方案例的
源构成不同（3 定向 vs 10 定向），**虚拟时间不可直接相减比较**；可确认的
是 RL 在官方混合源与全定向源演练中都能完成全部清除，且
`all_timestamps_match_microsecond_recomputation`、官方 `.jlog` 的
SHA-256 校验全部通过。归档目录：`output/rl/official-practice/`。

### 5.2 自建 referee 演练验证

`uv run mcm26b run --local-judge` 走自建 referee 的 `q3_practice` /
`q4_practice` 模块（与官方相同的演练生命周期，真值在结束后可见）：

| 问题 | 案例 | 场景 | 结果 | 虚拟时间 | 归档 |
| --- | --- | --- | --- | --- | --- |
| Q3 | `FKUY-K8KJ-RXRL-FMBM` | 10 全向 | 10/10 全清 | 3317.6s | `output/rl/local-practice/q3/20260911-rl-01` |
| Q4 | `3J8T-L9GY-HRGL-LYVZ` | 7 全向 + 3 定向 | 10/10 全清 | 11942.8s | `output/rl/local-practice/q4/20260911-rl-01` |
| Q4(BC) | `VM2G-UVC6-4N7R-TVGW` | 7 全向 + 3 定向 | 10/10 全清 | 12520.8s | `output/rl/local-practice/q4/20260911-rl-bc-01` |

不同案例仍不可直接比较；成对可比的提升证据是 §5 的 5 种子同场景消融。

## 6. 结论与边界

- RL 已接入问题3/4 完整闭环，并在自建 referee 演练与官方模拟器演练中
  全清验证；这是方法验证，不是对正式成绩的承诺。
- 利用自建模拟器逻辑做专家行为克隆，对 Q4 遮挡分支带来明确收益
  （−3.84% → −7.16%）；Q3 全向分支空间有限，BC 初始化无收益，保留随机
  初始化的长训练模型。
- 训练环境使用自建场景假设（源均匀分布、逐点固定误差场、定向源朝向随机）；
  官方隐藏分布未必相同。正式测试仍应默认使用经过演练验证的手写策略；
  `--strategy rl` / `--q4-strategy rl` 适合消融、方法对比与后续调参。
- 官方演练仅使用“演练测试”按钮与开放接口，从未点击“正式测试”；官方
  `.jlog/.result.json` 保持原样，未解密。
- 保守性不变式：RL 只改变选点排序，不改变覆盖账本、候选集更新、清除证书
  与后备清除的数学证明；所有策略均以 `/exit` 与完整日志收尾。