docs: finalize R4 documentation — Dueling 84% Holdout, full ablation record

README:
- Rewrite project pitch: 4-round systematic ablation, 61%->84% (+23pp)
- Upgrade result table to four-algorithm ablation with EVAL->Holdout gap
- Tighten CI disclaimer (±5pp)

experiment_log:
- Clarify EVAL set is fixed (seed+100000), not regenerated each episode
- Add P3/P6 relationship note (engineering fix vs root cause)
- Add distance_shaping γ=1 approximation caveat
- Mark R4 screenshot TODOs as completed

technical_report:
- Add metric selection rationale table (success rate vs Grid-SPL)
- Expand Grid-SPL section: wall-hit exclusion, HabitatAI incompatibility,
empirical SPL/success ratio 0.978±0.014
- Add Section 6: four-round results table and algorithm ablation table

hyperparameter_study: update R4 row to dueling 84% final result

assets: add R4 training curves (3 plots), R1-R4 double comparison,
add R2 backend avg_q and loss plots

README.md

@@ -10,7 +10,7 @@ license: mit
 
 # RL Maze Navigator
 
-### Benchmarking DQN variants on procedurally-generated mazes · SPL evaluation · 78% Holdout success rate
+### 4 种 DQN 变体在随机 10×10 迷宫上的系统性消融实验 · SPL 评估 · Holdout 成功率 84%
 
 [![CI](https://github.com/Lee93whut/rl-maze/actions/workflows/test.yml/badge.svg)](https://github.com/Lee93whut/rl-maze/actions/workflows/test.yml)
 [![Python](https://img.shields.io/badge/python-3.10-blue)](https://www.python.org/)
@@ -18,123 +18,153 @@ license: mit
 
 **在线 Demo**：[Hugging Face Spaces](https://huggingface.co/spaces/lil58/interview) · **代码**：[GitHub](https://github.com/Lee93whut/rl-maze) · **实验记录**：[docs/experiment_log.md](docs/experiment_log.md)
 
-训练 4 种 DQN 变体在随机 10×10 迷宫中自主寻路。每局随机生成迷宫、随机选取起终点，测试智能体的导航**泛化**能力，而非记忆固定路径。
+---
+
+## 为什么看这个项目
+
+随机起终点 + 随机地图将状态空间扩大约 40×，使 DQN 在此设定下初版只能达到 **61% 成功率**。
+本项目通过 **4 轮系统性消融**（超参调优 → 算法横评），将 Holdout 成功率提升至 **84%**（+23pp：超参调优 +17pp，61%→78%；算法切换至 Dueling DQN +6pp，78%→84%）。
+
+过程中发现并修复了一类常见的 RL 工程错误——**reward shaping 违反马尔可夫性**——并提供完整的诊断证据链与理论分析，给出了训练侧的根本解法。
+
+> 这不只是"跑通了 DQN"，而是一次带完整方法论的 RL 实验：**有对照组、有问题诊断、有单变量消融、有算法归因**。
 
 ---
 
-## 算法对比结果（Round 4，最终）
+## 最终结果
 
-> Holdout 评估：100 张训练中**从未见过**的独立地图（seed+200000），ε=0 贪心推理。  
-> 指标：[SPL](https://arxiv.org/abs/1807.06757)（Anderson et al. 2018，导航领域标准评估指标）。  
-> Round 4 最终超参：`buffer=80000`、`target_update_freq=1500`、`distance_shaping_alpha=0.5`、visited_map 第四通道 + EVAL-based checkpoint，Double DQN。
+> **Holdout 评估**：100 张训练中从未见过的独立地图（seed+200000），ε=0 贪心推理。
+> ⚠️ n=100 单次跑点，95% CI ≈ ±5pp；#1 Dueling（84%）与 #2 Double+Dueling（81%）差距 3pp，处于 CI 边缘，排名供参考，严格对比需多次独立运行取均值±标准差（Henderson et al., 2018）。
 
-| 算法 | 成功率 | SPL | 峰值成功率 | 收敛 Episode |
-|------|:------:|:---:|:---------:|:-----------:|
-| **Double DQN** (R4) | **78.0%** | **0.773** | **84.0%** | 3750 |
-| Double DQN (R2) | 64.0% | 0.633 | 74.0% | 3300 |
-| Vanilla DQN (R1) | 56.0% | 0.559 | — | 1921 |
-| Double DQN (R1) | 61.0% | 0.605 | — | 948 |
-| Dueling DQN (R1) | 45.0% | 0.445 | — | 759 |
-| Double + Dueling (R1) | 43.0% | 0.425 | — | 1843 |
+### R4 四算法横向消融（固定最优超参，唯一变量 = 算法）
 
-> R1 为随机起终点初版超参（训练量不足，供参考）；R2/R3/R4 为逐轮超参消融后的结果。完整演进见 [docs/experiment_log.md](docs/experiment_log.md)。
-> 
-> ⚠️ **统计说明**：Holdout 评估使用 100 张地图，单次跑点估计，95% CI ≈ ±8–9pp。相邻轮次间约 10pp 的提升处于置信区间边缘，不保证统计显著性。严格对比需多次独立运行取均值±标准差。
+| 排名 | 算法 | Holdout 成功率 | SPL | EVAL→Holdout Gap |
+|:---:|------|:-------------:|:---:|:----------------:|
+| 🥇 | **Dueling DQN** | **84.0%** | **0.817** | −6pp（泛化最稳） |
+| 🥈 | Double + Dueling | 81.0% | 0.793 | −9pp |
+| 🥉 | Double DQN | 78.0% | 0.773 | −10pp |
+| 4️⃣ | Vanilla DQN | 75.0% | 0.726 | −19pp |
 
-**R2 → R3 成功率对比（Double DQN）**：
+> 排名基于单次跑点，相邻差距处于统计置信区间边缘，仅代表本次实验观测结果。
 
-![R2 vs R3 成功率对比](docs/assets/compare/cmp_eval_success_rate_r2_vs_r3.png)
+![R4 四算法 EVAL 成功率对比](docs/assets/round4/r4_eval_success_rate_all_algos.png)
+
+### 超参演进纵向对比（Double DQN，保持算法一致）
+
+| 轮次 | 核心变更 | Holdout 成功率 | SPL |
+|------|---------|:-------------:|:---:|
+| Round 1 | 初版超参（`ep=2000`, `decay=0.995`） | 61.0% | 0.605 |
+| Round 2 | `ep=6000`, `decay=0.9985` | 64.0% | 0.633 |
+| Round 3 | `buffer=80k`, `target=1500`, `shaping=0.5` | 74.0% | 0.735 |
+| **Round 4** | visited_map 4通道 + EVAL checkpoint + BFS 连通性 | **78.0%** | **0.773** |
+
+![R1→R4 超参演进纵向对比（Double DQN）](docs/assets/compare/cmp_eval_success_rate_r1_to_r4_double.png)
 
 ---
 
-## 项目亮点
+## 实验方法论
 
-### 1. TensorBoard 三解耦看板
+本项目遵循 Henderson et al. (2018) 的 RL 实验规范，分三个阶段执行：
 
-训练过程写入三类指标，X 轴语义不同，互不混用：
+```
+阶段一：冒烟验证（Round 0）
+    固定起终点，四算法均达 90%+
+    → 验证训练流程���系统性 bug，建立对照组
+
+阶段二：超参消融（Round 1–4）
+    每轮只改一组变量，用问题诊断驱动下一轮变更
+    R1 → R2：修复训练量 + 探索衰减（单变量）
+    R2 → R3：修复 buffer + target + shaping（P3/P4/P5 同批修复）
+    R3 → R4：修复 checkpoint 时序 + 连通性验证 + 状态编码
+
+阶段三：算法横评（Round 4 续）
+    固定 R4 最优超参，四算法串行训练
+    唯一变量 = 网络架构与 Q 目标计算方式
+```
 
-| 看板前缀 | X 轴 | 记录频率 | 指标 |
-|---|---|---|---|
-| `Backend_Net/` | `global_update_steps` | 每次梯度更新 | Loss、Avg Q Value、Grad Norm |
-| `Frontend_Env/` | `episode` | 每局结束 | Reward、Steps、Success Rate、Epsilon |
-| `Evaluation_Exam/` | `episode` | 每 N 局 | 盲测成功率、SPL |
+**为什么先调超参再比算法**：先把超参调到最优，比的才是算法本身的能力差异；否则比的是"哪个算法对糟糕超参更鲁棒"。
 
-三类 X 轴对齐不同事件频率，避免将梯度步数与训练局数混在同一坐标轴产生误导。
+完整逐轮记录见 [docs/experiment_log.md](docs/experiment_log.md)。
 
-### 2. Episode 级 Warmup 机制
+---
 
-前 `warmup_episodes` 局固定 ε=1.0 纯随机探索，不执行任何梯度更新，先填充回放池再开始学习：
+## 核心发现
 
-```python
-in_warmup = (episode <= warmup_episodes)
-cur_eps   = 1.0 if in_warmup else epsilon          # warmup 期间不衰减
+### 发现一：reward shaping 的马尔可夫性陷阱（P9）
 
-if not in_warmup and buffer.is_ready(batch_size):  # warmup 结束后才更新
-    loss, avg_q, grad_norm = optimize_model(...)
+R4 首先尝试用 `revisit_penalty`（重复访问格子施加递进奖励惩罚）抑制推理时的循环行为，但训练至 ep=1000 时成功率仅 38%，持续低于基线 15pp，最终终止。
 
-if not in_warmup:                                  # warmup 结束后才衰减
-    epsilon = max(eps_end, epsilon * eps_decay)
-```
+**根因**：Q-learning 的贝尔曼方程要求 $r(s,a,s')$ 仅依赖当前转移。`revisit_penalty` 使奖励依赖 episode 内访问历史（隐变量），相同的 $(s,a)$ 在不同时刻返回不同奖励，Q 函数在数学上无法收敛到唯一固定点。更严重的是训练/推理分布不一致——训练时奖励含惩罚项，推理时不含，策略崩溃不可修正。
 
-相比 step 级 warmup，episode 级保证每局数据完整收集，避免半局数据污染早期 Q 值估计。
+**正确解法**：把历史信息从奖励空间移到状态空间。观测张量第四通道编码二值访问图（ch3=visited_map），Q 函数合法学习"已访问格价值低"的策略，马尔可夫性完整保持。
 
-### 3. SPL 评估指标（Anderson et al. 2018）
+> 这一诊断具有通用性：**任何依赖 episode 内历史的奖励项都是这类错误的变体**，正确方向永远是状态编码。
 
-$$\text{SPL} = \frac{1}{N} \sum_{i=1}^{N} S_i \cdot \frac{\ell_{i}^{\ast}}{\max(\ell_{i}^{\ast},\; p_i)}$$
+### 发现二：Dueling 架构与本任务的结构适配性
 
-- $S_i$：第 i 局是否成功（0/1）
-- $\ell_{i}^{\ast}$：BFS 最短路径步数（Ground Truth）
-- $p_i$：Agent 实际移动步数（排除撞墙步）
-- **失败局整项贡献 0**，比纯成功率更严格，同时惩罚绕路行为
+随机起终点迷宫中存在大量"多动作等效"状态（死胡同、走廊段），Dueling 的 V(s)/A(s,a) 分解使 V(s) 流被所有动作共享——每次梯度更新中 V(s) 获得所有动作的梯度信号，更新频率是 A(s,a) 的 4 倍，估计更稳定、泛化更强。
 
-与 HabitatAI、EmbodiedQA 等导航 Benchmark 使用相同评估体系。
+实测证据：EVAL→Holdout Gap 仅 6pp（最小），而 Vanilla DQN 的 Gap 高达 19pp。
 
-### 4. 势函数距离 Shaping（Ng et al. 1999）
+### 发现三：checkpoint 保存策略是系统性问题
 
-每步额外奖励 = `α × (移动前曼哈顿距离 − 移动后曼哈顿距离)`，缓解稀疏奖励问题：
+R3 用训练滚动奖励触发 checkpoint，但训练奖励受随机地图难度影响，与泛化能力相关性弱（约 0.3–0.5）。实测 EVAL 峰值 84%、Holdout 仅 74%，差距 10pp 全部来自时序错位。
 
-```python
-if self.distance_shaping_alpha != 0.0:
-    reward += self.distance_shaping_alpha * (dist_before - dist_after)
-```
+改为 EVAL-based checkpoint（每次评估若成功率创新高则保存）后，Holdout 直接对应训练过程出现过的最佳泛化能力，R4 Holdout 回升至 78%（+4pp）。
 
-撞墙步位置不变，不触发 shaping，避免撞墙获得零 shaping 奖励误导策略。`α=0.5` 使 shaping 幅度为基础奖励（-1）的 50%，提供方向感但不压过终点奖励（+100）。近似符合 Ng et al. (1999) 的势函数 shaping 理论。严格形式为 $r' = r + \gamma\Phi(s') - \Phi(s)$，代入 $\Phi(s)=-\alpha d$ 得 $\alpha d_{\text{before}} - \gamma\alpha d_{\text{after}}$；代码实现省略了 $\gamma$（即 $\gamma=1$ ���似），在 $\gamma=0.99$、迷宫路径较短的条件下误差约 1%，实践影响可忽略，但不严格保证策略不变性。
+---
 
-### 5. Anti-Loop：visited_map 第四通道
+## 项目亮点
 
-Round 3 曾使用 `revisit_penalty` 对重复访问格子施加递进奖励惩罚，但在 Round 4 中被诊断为**理论错误并彻底弃用**：该方案依赖 Episode 内状态（访问计数），违反马尔可夫性，导致相同状态对应不同 TD 目标，Q 值估计被系统性污染（experiment_log.md P9）。
+### 1. 系统性实验方法论：冒烟 → 超参消融 → 算法横评
 
-**现行方案（Round 4）**：观测张量 `(4, N, N)` 第四通道为二值访问图（1=本 Episode 内到达过，0=未到达），将历史信息直接编码进状态，保持马尔可夫性。推理侧（`app.py`）执行裸 argmax，无需额外 Q 值修正。
+三阶段渐进式实验设计，每步有明确终止条件，避免盲目调参。每轮变更有问题诊断、数据依据和验收标准，完整记录于 [docs/experiment_log.md](docs/experiment_log.md)。
 
-> 设计备注：曾考虑"访问次数归一化"（`count / max_steps`），但在 `max_steps=200` 的迷宫任务中，计数信号的高频区间几乎无训练样本覆盖，归一化后数值分布极度不均匀。二值图更简洁，Q 函数真正需要的信息是"去过/没去过"而非精确次数，与 Markov 状态表达的最小充分性原则一致。
+### 2. 马尔可夫性违反的完整诊断链（P9）
 
-### 6. BFS 连通性保证
+发现 → 理论分析 → 实验验证 → 正确解法的完整闭环，是项目最有技术深度的发现。
 
-`reset()` 内嵌 BFS 验证，确保每张迷宫起点→终点绝对可达，排除"任务本身不可完成"对训练信号的干扰：
+### 3. EVAL-based Checkpoint（P7 修复）
 
 ```python
-while True:
-    self._wall_map = generate_maze(self.grid_size, self.obstacle_density, self.np_random)
-    if bfs_reachable(self._wall_map, self._agent_pos, self._goal_pos):
-        break
+if eval_success_rate > best_eval_success:
+    best_eval_success = eval_success_rate
+    torch.save({"state_dict": policy_net.state_dict(), ...}, best_model_path)
 ```
 
-### 7. 唯一随机源设计
+三集严格分离（训练 buffer / EVAL 集 / Holdout 集），EVAL 集用于 checkpoint 选择，Holdout 集仅最终报告使用，保证评估数字无偏。
 
-**`seed` 固定的是评估集的地图分布**，使不同算法、不同 Round 的 Holdout 指标可以在相同测试条件下横向对比——而不是复现网络参数初始化，也不是复现训练轨迹。
+### 4. BFS 连通性保证 + 唯一随机源
 
-Holdout 评估时固定 `seeds = range(200000, 200100)`，每次评估用完全相同的 100 张地图，排除"某次恰好抽到简单地图"对成功率/SPL 的干扰。训练过程本身不固定 seed，每局随机生成新地图是泛化训练的一部分。
+`reset()` 内嵌 BFS 验证，确保每张迷宫起点→终点绝对可达，排除无解任务污染训练信号。所有随机操作使用 Gymnasium 注入的唯一 `self.np_random`，评估集可精确复现。
 
-`super().reset(seed=seed)` 初始化 `self.np_random`，迷宫生成和起终点采样全部通过这同一个 Generator 完成：
+### 5. visited_map 第四通道（Markov-correct 状态编码）
 
-```python
-super().reset(seed=effective_seed)       # 初始化 self.np_random
+观测张量 `(4, N, N)` 第四通道为二值访问图，将访问历史编码进状态而非奖励，保持马尔可夫性。相比错误方案（revisit_penalty 导致训练崩溃），此方案在 R4 中验证有效。
 
-self._wall_map = generate_maze(
-    self.grid_size, self.obstacle_density,
-    self.np_random                       # 传入同一个 Generator
-)
-```
+### 6. TensorBoard 三解耦看板
+
+| 看板前缀 | X 轴 | 指标 |
+|---|---|---|
+| `Backend_Net/` | `global_update_steps` | Loss、Avg Q Value、Grad Norm |
+| `Frontend_Env/` | `episode` | Reward、Steps、Success Rate、Epsilon |
+| `Evaluation_Exam/` | `episode` | 盲测成功率、SPL |
+
+三类 X 轴对齐不同事件频率，避免梯度步数与训练局数混用产生视觉误导。
+
+### 7. SPL 评估指标（Anderson et al. 2018 变体）
+
+$$\text{SPL} = \frac{1}{N} \sum_{i=1}^{N} S_i \cdot \frac{\ell_{i}^{\ast}}{\max(\ell_{i}^{\ast},\; p_i)}$$
+
+失败局整项贡献 0，比纯成功率更严格。本项目使用 Grid-SPL 变体（$p_i$ 排除撞墙步，数值系统性偏高），不可与 HabitatAI 等连续导航 Benchmark 直接比较。
+
+### 8. 势函数距离 Shaping（Ng et al. 1999）
+
+每步额外奖励 = `α × (移动前曼哈顿距离 − 移动后曼哈顿距离)`，缓解稀疏奖励问题，早期学习速度显著提升（R3 vs R2 同期约 +6pp）。代码省略 γ（标准形式 F = γΦ(s')−Φ(s)），策略不变性定理（Ng et al., 1999）严格意义上不再成立，但 γ=0.99≈1，实践影响可忽略，属理论上不严格、实践可行的工程简化。
+
+### 9. Episode 级 Warmup + CI（90%+ 覆盖率）
+
+前 `warmup_episodes` 局固定 ε=1.0 纯随机探索，保证回放池多样性再开始学习。GitHub Actions + pytest-cov 保障环境包关键逻辑有测试覆盖。
 
 ---
 
@@ -161,6 +191,8 @@ app.py (Streamlit Web Demo)  ◄──── results/*.pth (训练权重) ◄─
     └── Plotly go.Heatmap           交互式迷宫可视化
 ```
 
+> **注**：`app.py` 推理时叠加了计数惩罚兜底（访问次数 ≥ 2 时对高频格施加递进 Q 值惩罚），仅影响 Demo 视觉体验。所有 Holdout/EVAL 数字均来自 `run_evaluation()`，使用裸 argmax，不受此影响。根本解法是将 ch3 改为归一化计数图重新训练，因时间限制未实施。
+
 ---
 
 ## 快速开始
@@ -183,8 +215,8 @@ docker build -t maze-dqn-demo .
 docker run --rm -p 7860:7860 maze-dqn-demo
 ```
 
-> 权重文件不托管在 GitHub（二进制文件不适合 git），统一存放于  
-> [HF Spaces lil58/interview](https://huggingface.co/spaces/lil58/interview)。  
+> 权重文件不托管在 GitHub（二进制文件不适合 git），统一存放于
+> [HF Spaces lil58/interview](https://huggingface.co/spaces/lil58/interview)。
 > `download_weights.py` 会跳过已存在的文件，重复执行安全。
 
 ```bash
@@ -228,11 +260,14 @@ rl-maze/
 │   └── renderer.py             ASCII 终端渲染器
 │
 ├── docs/
-│   ├── experiment_log.md       逐轮训练记录（配置 + 结果 + 诊断）
+│   ├── experiment_log.md       逐轮训练记录（配置 + 结果 + 诊断 + 后续优化项）
 │   ├── hyperparameter_study.md 超参分析报告（含论文依据）
-│   ├── technical_report.md     技术报告（算法原理 + 训练曲线解读）
+│   ├── technical_report.md     技术报告（算法原理 + 评估指标 + 结果分析）
 │   └── assets/                 训练曲线截图（Round 1/2/3 + 对比图）
 │
+├── reports/
+│   └── comparison.md           R4 四算法最终对比报告（含 SPL 共线性分析）
+│
 └── tests/                      pytest 测试套件（90%+ 覆盖率）
     ├── test_00_gymnasium_check.py
     ├── test_01_spaces.py ~ test_09_validation.py
@@ -244,19 +279,6 @@ rl-maze/
 
 ---
 
-## 超参演进
-
-| 轮次 | 关键变更 | Holdout 成功率 | SPL |
-|------|---------|:--------------:|:---:|
-| Round 1 | 初版（`ep=2000`, `decay=0.995`） | 61.0% | 0.605 |
-| Round 2 | `ep=6000`, `decay=0.9985` | 64.0% | 0.633 |
-| Round 3 | `buffer=80k`, `target_freq=1500`, `shaping=0.5` | 74.0% | 0.735 |
-| **Round 4** | visited_map 4th channel + EVAL-based checkpoint + terminated-only TD mask | **78.0%** | **0.773** |
-
-完整超参诊断与论文依据详见 [`docs/hyperparameter_study.md`](docs/hyperparameter_study.md)。
-
----
-
 ## 参考文献
 
 1. Mnih et al. (2015). *Human-level control through deep reinforcement learning*. **Nature**.
@@ -265,3 +287,5 @@ rl-maze/
 4. Ng et al. (1999). *Policy invariance under reward transformations*. **ICML**.
 5. Anderson et al. (2018). *On Evaluation of Embodied Navigation Agents*. arXiv:1807.06757.
 6. Henderson et al. (2018). *Deep Reinforcement Learning that Matters*. **AAAI**.
+7. Lin (1992). *Self-improving reactive agents based on reinforcement learning, planning and teaching*. **Machine Learning**, 8(3–4).
+8. Schaul et al. (2016). *Prioritized Experience Replay*. **ICLR**.

docs/experiment_log.md

@@ -192,7 +192,7 @@ Step 3（Round 4）：改 checkpoint 保存策略（EVAL-based）+ 引入 visite
 ### 验收标准评估
 
 - [x] `Evaluation_Exam/Test_Success_Rate` 出现 >70% 评估点（ep=3300 & ep=4250 均达 74%）
-- [x] 相比 Round 1 提升 > 10%（64% vs 61% Holdout，盲测峰值 74% vs 54%）
+- [x] 相比 Round 1 提升 > 10%（盲测峰值 74% vs 54%，+20pp；注：Holdout 仅 +3pp，64% vs 61%，未达 10%，本条以盲测峰值口径通过）
 - [ ] `Evaluation_Exam/Test_Success_Rate` 出现收敛平台（**未满足**，见问题诊断）
 
 ### 问题诊断
@@ -287,6 +287,8 @@ $$r'(s,a,s') = r(s,a,s') + \gamma \Phi(s') - \Phi(s)$$
 取 $\Phi(s) = -\alpha \cdot d_{\text{Manhattan}}(s, \text{goal})$，则每步额外奖励 $= \alpha \cdot (d_{\text{before}} - d_{\text{after}})$，
 靠近目标一步 +α，远离一步 −α。此形式满足势函数条件，**理论上不改变最优策略**，仅加速收敛。
 
+> **理论精确性说明**：Ng et al. (1999) 定理要求严格使用 $\gamma\Phi(s') - \Phi(s)$，代码实现省略了 $\gamma$（即令 $\gamma=1$）。这使策略不变性定理在严格意义上不成立——策略不变性是关于最优策略集合不变的命题，与数值误差大小无关。实践中因 $\gamma=0.99$ 且迷宫路径短（平均约 10–15 步），累计误差约 1%，对收敛结果影响可忽略，但属近似实现而非精确满足定理。
+
 ---
 
 ### TensorBoard 运行目录
@@ -408,6 +410,8 @@ ep=5800–6000: 62–76%   ← 末段振荡
 原因：即使 buffer=80000（约 1000 局），在成功率 60–80% 的阶段，仍约有 20–40% 的失败局（200步）持续填入 buffer；成功样本的相对比例虽有改善，但绝对数量仍不足以彻底稳定策略。  
 依据 Schaul et al. (2016)：根治方案需使用 **Prioritized Experience Replay（PER）**，让高 TD-error 的成功样本被优先重复采样，而非依赖更大 buffer。
 
+> **P3 与 P6 的关系澄清**：P3 诊断"buffer 过小导致振荡"，P6 诊断"根治需改均匀采样策略"，两者描述的是不同层面——P3 指出 buffer 扩容方向正确（实测振荡周期延长、低谷抬高），P6 指出扩容只能缓解而不能根治（均匀采样下成功样本始终处于少数）。两个诊断不矛盾，分别对应"短期工程修复"和"长期根治方案"。
+
 #### P4 — target network 修复效果验证（有效）
 
 **预期**：`target_update_freq` 从 500 提升至 1500，TD 目标稳定性提升，Loss 峰值减少。
@@ -500,7 +504,7 @@ buffer+target+shaping 组合将盲测峰值从 74% 提升至 **84%**，Holdout
 
 **主流标准做法（Evaluation-based Checkpoint Selection）**：每次 EVAL 后，若成功率创新高则保存 checkpoint（即 RL 版的 `save_best_only=True`，Stable-Baselines3、CleanRL 的默认逻辑）。Holdout 因此直接对应训练过程中出现过的最佳泛化能力。
 
-用 EVAL 集做 checkpoint 选择会引入隐式过拟合，偏差约 2–4pp；但本项目已满足三集分离：训练 buffer（学习）、EVAL 集（每 N ep 随机生成，checkpoint 选择）、Holdout 集（seed+200000 固定 100 张，仅最终报告使用，不参与任何决策）。2–4pp 偏差远小于当前 10pp 时序错位损失，**净收益为正**。
+用 EVAL 集做 checkpoint 选择会引入隐式过拟合，偏差约 2–4pp；但本项目已满足三集分离：训练 buffer（学习）、EVAL 集（训练开始前由 `seed+100000` 派生固定生成，整个训练期间恒定，checkpoint 选择）、Holdout 集（seed+200000 固定 100 张，仅最终报告使用，不参与任何决策）。2–4pp 偏差远小于当前 10pp 时序错位损失，**净收益为正**。
 
 > 注意：若用 Holdout 挑最优 checkpoint，Holdout 失去无偏评估资格，报告数字会严重高估真实泛化能力。
 
@@ -563,7 +567,7 @@ EVAL 峰值出现在 ep=3750，但模型保存触发于训练奖励峰值，两
 **标准做法（Evaluation-based Checkpoint Selection）**：  
 Stable-Baselines3、CleanRL 均默认 `save_best_only=True`——每次评估若成功率创新高则保存。三集分离原则保证此做法不引入严重过拟合：
 - **训练 buffer**：学习用
-- **EVAL 集**（每 eval_every ep 随机生成 50 张）：checkpoint 选择用
+- **EVAL 集**（训练开始前固定生成的 50 张，`seed+100000` 派生，整轮训练恒定）：checkpoint 选择用
 - **Holdout 集**（固定 seed+200000 的 100 张）：仅最终报告，不参与任何决策
 
 EVAL 集与 Holdout 集独立，用 EVAL 集挑 checkpoint 引入的偏差约 2–4pp，远小于当前 10pp 时序错位损失，**净收益为正**。
@@ -884,10 +888,11 @@ runs/Round4_ctrl_eval_ckpt/             ← R4-A3 记录（进行中）
 
 ### 所需截图
 
-- [ ] `r4_a2_vs_r3_eval_success.png`：R4-A2 与 R3 的 EVAL 成功率曲线对比（体现 A2 危机期+早期优势+峰值对比）
-- [ ] `r4_a1_eval_collapse.png`：R4-A1 的 EVAL 崩溃曲线（ep=600 骤降至 6%）
-- [ ] `r4_a3_eval_progress.png`：R4-A3 训练完成后的 EVAL 曲线（体现 EVAL SAVE 触发点）
-- [ ] `r4_ctrl_vs_r3_holdout.png`：R4-A3 Holdout 结果 vs R3 基准（训练完成后补充）
+- [x] `r4_eval_success_rate_all_algos.png`：R4 四算法 EVAL 成功率曲线（已生成）
+- [x] `r4_eval_spl_all_algos.png`：R4 四算法 SPL 曲线（已生成）
+- [x] `r4_dueling_full_curves.png`：最优算法完整训练曲线（已生成）
+- [x] `cmp_eval_success_rate_r1_to_r4_double.png`：R1→R4 超参演进纵向对比（已生成）
+- [ ] `r4_a1_eval_collapse.png`：R4-A1 的 EVAL 崩溃曲线（runs 目录已删，无法补充）
 
 ---
 
@@ -1009,6 +1014,12 @@ $$\hat{Q}_{\text{double}} = r + \gamma Q_{\theta^-}(s', \arg\max_{a'} Q_\theta(s
 
 **R1–R4 纵向成功率**：61%（R1）→ 64%（R2）→ 74%（R3）→ 84%（R4 dueling）
 
+**R4 四算法 EVAL 成功率曲线**：
+
+![R4 四算法 EVAL 成功率对比](../docs/assets/round4/r4_eval_success_rate_all_algos.png)
+
+![R4 四算法 EVAL SPL 对比](../docs/assets/round4/r4_eval_spl_all_algos.png)
+
 ---
 
 ### 理论分析
@@ -1070,15 +1081,21 @@ $$Q(s,a) = V(s) + A(s,a) - \frac{1}{|\mathcal{A}|}\sum_{a'} A(s',a')$$
 
 vanilla 是本组唯一一个 EVAL 峰值（94%）远高于其他算法但 Holdout 最低（75%）的算法，Gap 高达 19pp，是其他算法的 2–3 倍。有两个可能原因：
 
-1. **EVAL 集过拟合**：EVAL 每次随机生成 50 张地图，vanilla 网络容量虽低于 dueling，但若保存点对应的 50 张恰好是"容易的地图子集"，则 EVAL 成功率虚高。统计上，50 张样本的随机性导致约 ±7pp 的测量噪声，94% 的实测值上存在约 4–7pp 的正向偏差合理。
+1. **EVAL 集偶然偏差**：EVAL 集在训练开始前由 `seed+100000` 派生固定生成，整个训练期间恒定（非每次随机），因此不存在"恰好碰到容易地图子集"的随机噪声解释。94% 的 EVAL 峰值是 vanilla 网络在这批固定的 50 张地图上确实达到的真实性能，但这批地图对 vanilla 的特定决策边界恰好较友好——属于固定 EVAL 集对特定算法的结构性偏差，而非随机采样噪声。EVAL→Holdout 的 19pp Gap 主要反映的是 vanilla 对这 50 张特定地图的过拟合程度。
 2. **训练晚期策略退化**：vanilla 无 V/A 分解，Q(s,a) 需逐一精确估计，训练末段（ep=4500+）的 buffer 回放可能已不能支持如此精细的 Q 函数持续更新，导致 Holdout 性能在实际泛化时大幅缩水。
 
 **dueling 的 6pp Gap 解读**：
 
-Dueling 的 V(s) 流是全动作共享的，其泛化的关键是"状态价值地图"在新地图上是否有效。由于 V(s) 学习的是全局位置→价值的映射（不依赖特定障碍布局），在随机障碍的 Holdout 地图上，学到的"靠近终点的格子价值更高"的 V(s) 估计仍然成立，A(s,a) 仅提供局部动作微调。这一结构性优势使 dueling 的泛化最稳定，Gap 最小。
+Dueling 网络的真正泛化优势来自**参数共享机制**：V(s) 流被所有动作共享，在每次梯度更新中获得来自所有动作的梯度信号，更新频率是 A(s,a) 流的 $|\mathcal{A}|$ 倍（本任务 4 倍），学习更充分、估计更稳定。A(s,a) 流仅提供局部动作微调。这一结构性优势使 dueling 在未见过的 Holdout 地图上泛化最稳定——V(s) 学习的"靠近目标的状态价值更高"的规律在任意地图布局下均成立，Gap 最小（6pp）。
+
+> **注意**："不依赖特定障碍布局"这一属性对 Vanilla DQN 同样成立（Q(s,a) 同样通过相同的卷积特征提取器训练），因此不能用来解释 Dueling 的泛化优势。核心差异在于参数更新频率和梯度信号稳定性。
 
 ---
 
+**R1–R4 纵向超参演进（Double DQN，相同算法）**：
+
+![R1→R4 超参演进 EVAL 成功率对比](assets/compare/cmp_eval_success_rate_r1_to_r4_double.png)
+
 ### 结论链（R1→R4 纵向总结）
 
 以下为本项目全程的核心发现链，以 Holdout 成功率为主线：
@@ -1116,3 +1133,32 @@ Dueling 的 V(s) 流是全动作共享的，其泛化的关键是"状态价值
 - [ ] `r4_dueling_vs_double_dueling_late.png`：ep=3000–5000 曲线对比，体现 dueling 末段稳定性优于 double_dueling
 - [ ] `r4_vanilla_eval_overfit.png`：vanilla ep=4000–5000 曲线，体现 EVAL 峰值虚高（94%）与下降
 
+---
+
+## 已知局限与后续优化项
+
+### 实验设计层面
+
+| # | 问题 | 标准做法 | 本项目取舍 |
+|---|------|---------|----------|
+| A | 超参消融阶段多次参考了 Holdout 数字，测试集不严格无偏 | 验证集专用于超参搜索，Holdout 只在最终报告用一次 | 时间限制；R4 引入 EVAL-based checkpoint 是向正确方向的修正，但 R1–R3 的超参决策已隐性参考了 Holdout |
+| B | R3 同时修改三个变量（buffer + target_freq + shaping），无法归因 | 每次只改一个变量，或补做单因素对照组 | 时间限制；shaping 的独立贡献未被单独量化 |
+| C | 所有结论基于单次训练，无重复实验 | 每配��� 3–5 个随机种子，报告均值 ± std（Henderson et al. 2018） | 算力限制；dueling vs double_dueling 3pp 差距（Holdout n=100，CI≈±5pp）统计不显著，需重复实验确认 |
+| D | 评估时失败局步数未记录 | `run_evaluation()` 记录逐局步数，区分循环失败与走入死路失败 | 现有 log 无此数据；需改代码重跑，当前仅有训练期数据（混合探索期与贪心期） |
+
+### 算法与工程层面
+
+| # | 问题 | 解决方案 | 预期收益 |
+|---|------|---------|---------|
+| E | visited_map 二值编码无法区分访问次数，网络对两格死循环覆盖不足，需 app 推理时兜底 | 将 ch3 改为归一化计数图（`min(count,3)/3.0`，cap=3），重新训练 | 网络内化"高频重访格应规避"策略，推理时 Q 值修正可完全移除 |
+| F | 振荡根治需 Prioritized Experience Replay | 实现 PER（Schaul et al. 2016），赋予高 TD-error 样本更高采样概率 | 消除均匀采样导致的成功样本周期性被覆盖问题，振荡从根本上消除 |
+| G | Ng et al. (1999) 势函数 shaping 省略了 γ，属近似实现 | 代码改为 `reward += alpha * (gamma * dist_after_to_goal - dist_before_to_goal)` 的标准形式 | 严格满足策略不变性定理，误差从约 1% 降至 0 |
+
+### 指标层面
+
+| # | 问题 | 解决方案 |
+|---|------|---------|
+| H | Grid-SPL（排除撞墙步）不可与标准 HabitatAI SPL 直接比较，文档曾未充分说明 | 已在 technical_report.md 和 comparison.md 补充说明 |
+| I | SPL 与成功率高度共线（比值 0.978±0.009），独立信息增量有限 | 已在 comparison.md 补充共线性数据；若需更强区分度，可考虑记录"失败局平均步数"作为失败模式诊断指标 |
+
+

docs/hyperparameter_study.md

@@ -26,7 +26,7 @@
 | R1 | 基线（随机起终点初版） | 61.0% | — | 诊断 P1（训练量）+ P2（探索）+ P3（buffer）+ P4（target）|
 | R2 | `ep=6000` + `decay=0.9985` | 64.0% | 74.0% | P1/P2 消除；振荡周期 400–500 ep（P3 定量确认）|
 | R3 | `buffer=80k` + `target=1500` + `shaping=0.5` | **74.0%** | **84.0%** | 峰值突破 80%；Holdout 低于峰值 10pp（P6：保存策略错位）|
-| R4 | EVAL-based checkpoint + visited_map 第四通道（revisit_penalty 因违反马尔可夫性弃用） | **78.0%** | **0.773** | |
+| R4 | EVAL-based checkpoint + visited_map 第四通道（revisit_penalty 因违反马尔可夫性弃用） | **84.0%**（dueling） | **88.0%**（dueling，ep=4900） | 四算法横向消融最优；double(A3) Holdout 78%，见 experiment_log.md Round 4 |
 
 ---
 

docs/technical_report.md

@@ -96,15 +96,36 @@ Step 级 warmup 可能在一局中途切换为学习模式，导致同一局内
 
 ## 四、评估指标
 
-### SPL（Anderson et al. 2018）
+### 4.1 指标选择逻辑
+
+本项目使用两个互补指标，各自回答不同的问题：
+
+| 指标 | 回答的问题 | 指导下一步方向 |
+|------|----------|--------------|
+| **成功率** | 策略是否可用？ | 若低 → 改算法、调超参、修训练信号 |
+| **Grid-SPL** | 成功时路径是否高效？ | 若 SPL/成功率比值低 → 优化路径规划（加强 shaping、延长训练） |
+
+**本项目实测结论**：四算法 Holdout SPL/成功率比值为 0.968–0.991（均值 0.978），全程 EVAL 逐点比值稳定在 0.986 ± 0.014。这说明**成功时的路径效率已不是瓶颈**——agent 要么高效成功，要么完全失败，路径规划本身已接近最优。后续提升空间集中在成功率本身，而非路径效率。
+
+### 4.2 成功率
+
+最直接的任务完成度指标。Holdout 评估在 100 张固定地图（seed+200000）上以 ε=0 贪心推理，裸 argmax，无任何推理时修正，保证数字反映纯网络能力。
+
+### 4.3 Grid-SPL（Anderson et al. 2018 变体）
 
 $$\text{SPL} = \frac{1}{N} \sum_{i=1}^{N} S_i \cdot \frac{\ell^{*}_i}{\max(\ell^{*}_i,\ p_i)}$$
 
 - $S_i$：第 i 局成功标志（0/1）
 - $\ell^{*}_i$：BFS 最短路径步数
-- $p_i$：Agent 实际移动步数（排除撞墙步）
+- $p_i$：Agent **实际移动步数**（排除撞墙步，见下方说明）
+
+失败局整项贡献 0，同时惩罚绕路行为，比纯成功率更严格。
+
+**为何排除撞墙步（Grid-SPL 与标准 SPL 的差异）**：
 
-失败局整项贡献 0，避免"成功但绕远路"的高分；与 HabitatAI、EmbodiedQA 等主流导航 Benchmark 评估体系一致。
+标准 SPL（HabitatAI）的 $p_i$ 是 agent 总动作数。在连续导航场景中这没有问题，因为"碰墙"不是一个显式的离散动作。但在网格迷宫中，撞墙是一个明确的失败动作——若计入 $p_i$，SPL 变成"路径质量 × 撞墙规避能力"的混合指标，两种不同能力的 agent 无法被区分。排除撞墙步后，$p_i$ 只反映真实移动路径的长度，SPL 纯粹度量**路径规划质量**，两种能力解耦。
+
+> ⚠️ 此变体使 $p_i$ 偏小、SPL 数值系统性偏高，**不可与 HabitatAI、EmbodiedQA 等连续导航 Benchmark 的 SPL 直接比较**。
 
 **Holdout 防泄漏**：训练地图每局随机生成（seed 随机）；评估地图固定 100 张（seed+200000），seed 空间完全隔离，确保曲线波动反映 Q 函数能力而非地图难度变化。
 
@@ -123,7 +144,79 @@ $$\text{SPL} = \frac{1}{N} \sum_{i=1}^{N} S_i \cdot \frac{\ell^{*}_i}{\max(\ell^
 
 ---
 
-## 六、参考文献
+## 六、实验结果
+
+### 6.1 四轮超参演进（Double DQN）
+
+| 轮次 | 核心变更 | Holdout 成功率 | SPL | 关键问题诊断 |
+|------|---------|:-------------:|:---:|------------|
+| R1 | 随机起终点初版 | 61.0% | 0.605 | 训练量不足、探索过早终止 |
+| R2 | `ep↑` + `decay↓` | 64.0% | 0.633 | buffer 过小导致振荡 |
+| R3 | `buffer×4` + `target×3` + `shaping` | 74.0% | 0.735 | checkpoint 时序偏差 10pp |
+| R4 | EVAL checkpoint + BFS + visited_map | **78.0%** | **0.773** | — |
+
+![R1→R4 超参演进 EVAL 成功率对比（Double DQN）](assets/compare/cmp_eval_success_rate_r1_to_r4_double.png)
+
+### 6.2 R4 四算法横向消融
+
+固定 R4 最优超参，唯一变量为算法：
+
+| 排名 | 算法 | Holdout 成功率 | SPL | EVAL→Holdout Gap |
+|:---:|------|:-------------:|:---:|:----------------:|
+| 🥇 | Dueling DQN | **84.0%** | **0.817** | −6pp（最小） |
+| 🥈 | Double + Dueling | 81.0% | 0.793 | −9pp |
+| 🥉 | Double DQN | 78.0% | 0.773 | −10pp |
+| 4️⃣ | Vanilla DQN | 75.0% | 0.726 | −19pp |
+
+![R4 四算法 EVAL 成功率对比](assets/round4/r4_eval_success_rate_all_algos.png)
+
+**核心结论**：Dueling 架构的 V(s)/A(s,a) 分解与本任务高度适配（大量多动作等效状态），泛化最稳定（Gap 最小）。Double DQN 的主要收益在训练早中期（加速危机恢复），充分训练后与 Vanilla 差距收敛。完整分析见 [experiment_log.md](experiment_log.md)。
+
+**统计显著性说明**：n=100 单次跑点，二项分布标准差 ≈ √(p·(1−p)/100)。Dueling（84%）vs Double+Dueling（81%）差距 3pp，而 σ ≈ 3.6pp，差异不具统计显著性（p > 0.2）；Dueling（84%）vs Double DQN（78%）差距 6pp ≈ 1.7σ，边缘显著。排名仅反映本次单次实验的观测点，严格结论需多次独立运行取均值±标准差。
+
+**Double+Dueling 低于单独 Dueling 的反直觉结论**：两项改进理论上正交，但实测 Double+Dueling（81%）低于单独 Dueling（84%）。可能原因：Double DQN 通过 policy_net 选动作、target_net 估值来降低 Q 值高估，而 Dueling 的 V/A 分解本身已通过"减去均值"使优势估计更保守，两者同时作用可能导致 Q 值被过度低估��underestimation bias），在稀疏奖励迷宫中使策略趋于保守，抑制了 Dueling 的泛化优势。该假设未经消融验证，3pp 差距处于统计 CI 内，亦不排除随机因素。
+
+### 6.3 失败模式分析
+
+训练期失败局步数数据（三算法）：
+
+| 算法 | 失败局平均步数 | 步数=200 截断比例 |
+|------|:-----------:|:--------------:|
+| Dueling | 161.0 | 59.0% |
+| Double + Dueling | 157.1 | 54.5% |
+| Vanilla | 157.9 | 55.9% |
+
+**55–59% 的失败局走满 200 步被截断**，主要失败模式是循环/徘徊，而非走入死路后停止移动。这是 Web Demo 中加入推理时计数惩罚兜底的数据依据。
+
+---
+
+## 七、Web Demo 兜底机制说明
+
+### 7.1 评估侧 vs Demo 侧
+
+| 路径 | anti-loop 修正 | 说明 |
+|------|:-------------:|------|
+| Holdout / EVAL（`run_evaluation`） | **无**，裸 argmax | 所有报告数字均为纯网络能力 |
+| Web Demo（`app.py`） | **有**，计数惩罚 | 仅影响 Demo 视觉体验 |
+
+### 7.2 兜底的必要性
+
+visited_map 第四通道将访问历史编码为二值图（去过/没去过），解决了马尔可夫性问题。但二值信息使网络无法感知"访问了几次"，对两格死循环这一边缘状态的 Q 值估计不稳定（训练中此类样本覆盖密度极低）。失败模式分析（6.3节）证实循环是主要失败原因，因此在 Demo 中加入计数惩罚作为安全网是有针对性的工程决策。
+
+### 7.3 根本解法（后续优化项）
+
+将 ch3 从二值图改为**归一化计数图**（cap=3）：
+
+```python
+obs[3, r, c] = min(visit_count[r, c], 3) / 3.0
+# 0次→0.0, 1次→0.33, 2次→0.67, ≥3次→1.0
+```
+
+网络训练后直接内化"高频重访格应规避"的策略，届时推理时的 Q 值修正可完全移除。因时间限制未重新训练，当前 Demo 保留推理时兜底作为临时替代。
+
+---
+
+## 八、参考文献
 
 1. Mnih et al. (2015). *Human-level control through deep reinforcement learning*. **Nature**, 518, 529–533.
 2. van Hasselt, Guez & Silver (2016). *Deep Reinforcement Learning with Double Q-learning*. **AAAI**.