# HRL P0+P1 执行报告（本地自建评测机）

日期：2026-09-11（本机工作区）
范围：按用户确认，仅完成 P0 正确性回归 + P1 最小可训练/可评测闭环；
P2 的 BC、完整课程长训、Optuna、正式消融与正式测试表留待下一阶段。

## 1. 本轮代码交付

| 文件 | 内容 |
| --- | --- |
| `scripts/benchmark_hrl.py` | 同一 manifest 真值场景复用；`hrl`/`hrl_heuristic`/`bayes`/`directional` 配对评测；写 `results.json`、`aggregate.json/csv`、每局 `summary.json` 与 `session.jsonl` |
| `scripts/train_hrl_high.py` | 高层 MaskablePPO 训练；`--problem/--stage/--envs/--vec-env/--device/--config-profile/--reward-profile/--model/--resume/--init/--eval-manifest`；模型元数据固化 feature/action/reward 版本；墙钟硬上限 |
| `src/mcm26b/hrl/constants.py` | 新增 `ACTION_LAYOUT_VERSION=1`、`REWARD_VERSION=1` |
| `src/mcm26b/hrl/policy.py` | 高层模型严格校验元数据；低层模型保持独立基础校验 |
| `src/mcm26b/cli.py` | 新增 `--strategy hrl`、`--q4-strategy hrl`、`--hrl-model`、`--hrl-low-model`、`--hrl-device`、`--trace-low` |
| `src/mcm26b/hrl/hierarchical_env.py` | 新增 `HRLReward.time_only()`：P0.4 建议的纯时间目标，去掉逐源清除/发现/熵减塑形 |
| `project/` | 严格目录树薄兼容层，转发真实实现，不复制算法 |
| `tests/test_hrl_p1.py` | manifest 往返、真值隔离、纯时间奖励、project re-export 回归 |

## 2. 全量回归

```bash
.venv/bin/python -m pytest -q --tb=short
# 275 passed in 124.57s
```

## 3. P1 smoke 训练（本机 Apple MPS）

```bash
.venv/bin/python scripts/train_hrl_high.py \
  --problem 3 --stage 1 --timesteps 2048 --seed 320001 \
  --envs 1 --vec-env dummy --device mps \
  --config-profile production --reward-profile time \
  --model output/hrl/p1-smoke-time/q3.zip \
  --eval-episodes 2 --rollout-steps 128 --batch-size 128 \
  --n-epochs 3 --max-wall-s 800 --verbose 0
```

结果：

- `actual_timesteps=2048`，墙钟 `260.069 s`；
- 保存后确定性评估 2/2 成功，`accounted=20`，无异常；
- 模型元数据含 `feature_version=4`、`action_layout_version=1`、
  `reward_version=1`、`reward_profile=time`、`model_sha256`。

模型重载已由以下两条路径验证；`--resume` 的 `--timesteps` 是增量步数
（SB3 `reset_num_timesteps=False` 语义），元数据写 `timesteps_semantics="additional"`：

```bash
.venv/bin/python -m mcm26b.cli run \
  --robot-id 2026001 --self-test --strategy hrl \
  --hrl-model output/hrl/p1-smoke-time/q3.zip --hrl-device mps \
  --sources 3 --seed 1 --summary-steps 5

python scripts/benchmark_hrl.py --variants hrl \
  --hrl-model output/hrl/p1-smoke-time/q3.zip --hrl-device mps \
  --problem 3 --scenes 1 --sources 3 --output output/hrl/p1-bench-hrl
```

## 4. 多轮本地配对测试

### Q3：3 个独立场景 × 3 个变体

```bash
python scripts/benchmark_hrl.py --variants hrl,hrl_heuristic,bayes \
  --hrl-model output/hrl/p1-smoke-time/q3.zip --hrl-device mps \
  --problem 3 --scenes 3 --sources 3 --start-seed 91000 \
  --output output/hrl/p1-multiround-q3
```

| variant | episodes | valid_rate | cleared_mean | virtual_time_mean_s | virtual_time_std_s | program_run_time_mean_s |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| bayes | 3 | 1.0 | 3.0 | 2518.371 | 74.183 | 0.748 |
| hrl_heuristic | 3 | 1.0 | 3.0 | 2518.371 | 74.183 | 0.883 |
| hrl | 3 | 1.0 | 3.0 | 3731.380 | 120.536 | 1.853 |

结论：P1 模型只在 stage 1 单源课程上训练 2048 步，可直接重载并在 3 源场景保持 3/3 有效全清；
但用时明显未优于 bayes/heuristic，符合本轮不做正式性能声明的边界。

### Q4：3 个独立混合源场景 × 2 个变体

```bash
python scripts/benchmark_hrl.py --variants hrl_heuristic,directional \
  --problem 4 --scenes 3 --sources 3 --directional 1 --start-seed 92000 \
  --output output/hrl/p1-multiround-q4 --force
```

| variant | episodes | valid_rate | cleared_mean | virtual_time_mean_s | virtual_time_std_s | program_run_time_mean_s |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| directional | 3 | 1.0 | 3.0 | 13442.997 | 263.902 | 1.063 |
| hrl_heuristic | 3 | 1.0 | 3.0 | 12292.198 | 344.827 | 6.284 |

说明：Q4 高层 PPO 尚未训练；本轮只验证 Q4 的 `hrl_heuristic` 与 `directional` 闭环、真值隔离与计时审计。

## 5. P0 状态

- `--resume` 重载：16 步起步模型续训 32 增量步后 `actual_timesteps=48`，
  校验 `feature_version/action_layout_version/reward_version` 后保存；

- 槽位唯一性：`test_hrl.py` 覆盖 channel 17–20 与 1–4 同时 clear/locate 不丢；
- 清除事件一次且仅一次：fallback 成功写 `_step_clears` 已有回归；
- 候选快照：`test_opportunity_measure_precedes_candidate_snapshot` 已覆盖；
- 奖励对齐：新增 `HRLReward.time_only()`，训练脚本默认 `--reward-profile time`；
- 终止/安全网：现有 `HierarchicalEnv` 回合测试继续通过；
- 训练/部署配置：`--config-profile production` 使用生产配置，`coarse-pretrain`
  显式映射到 fast 评分配置并写入模型元数据；
- 依赖守卫：全量测试 275 项在 dev+rl 环境通过。

## 6. 未完成 / P2 待办

- `scripts/pretrain_hrl_expert.py` 已建可 `--help` 的接口占位，专家轨迹 + BC 功能待实现；
- `scripts/ablate_hrl.py` 已建接口占位，无信息增益/无掩码/无课程/无粒子统计消融待实现；
- `scripts/tune_hrl.py` 已建接口占位，Optuna TPE 搜索待实现；
- Q3→Q4 迁移训练与配对实验；
- 完整 10–16 源课程训练、多个训练种子、冻结测试清单；
- 官方三次正式测试表：必须有真实官方案例码与导出日志后才能填写；
  本地 `referee` 结果只标 `local_self_test`。