1919810

docs/training-ui.md

@@ -80,6 +80,24 @@ uv run python -m mcm26b.training_ui --print-preview  # 只看离线示例快照
 - 产物路径限定在仓库根下解析，模型输出沿用训练脚本自身的 `--force`/`--resume`
   语义（两者互斥，由后端校验）。
 
+## 停止与落盘保证
+
+训练前端的「停止」是对独立进程组发 SIGTERM。`train_hrl_high.py` 有三层兜底，
+点一下「停止」不再等于这一局白跑：
+
+| 机制 | 行为 |
+| --- | --- |
+| 定期 checkpoint | `--checkpoint-every`（默认 20000 环境步）在 `<模型目录>/checkpoints/` 落 `*_ckpt_<步数>.zip` + 同名元数据；`--checkpoint-keep` 只保留最近 K 个（默认 3），`--checkpoint-dir` 可改目录 |
+| 优雅停止 | subproc worker 忽略 SIGTERM/SIGINT，主进程收到信号后在 step 边界收尾，保存最终模型与元数据（`stopped_by_signal=true`、`stop_signal`、`checkpoint_files`）并正常关闭环境；收尾阶段恢复默认处理器，再按一次可立即强杀 |
+| 异常兜底 | `learn()` 抛出任何异常时先落 `*_emergency.zip` + 元数据，再写 `training_failure.json` 并抛出 |
+
+checkpoint 与最终模型共用同一份 json 契约，因此 `--resume <checkpoint.zip>` 直接
+续训（`--timesteps` 为增量步数）。注意 `--resume`/`--init` 会沿用 checkpoint 内的
+PPO 超参（`n_steps`/`batch_size`/`n_epochs`）：命令行这三项被忽略，脚本会打一条
+`hyperparams_from_checkpoint` 事件说明差异，元数据 `ppo_hyperparams` 记录**实际生效**值。
+回归测试见 `tests/test_hrl_checkpoint.py`，
+其中端到端用例真起 subproc 子进程并用 `killpg(SIGTERM)` 复现前端的停止路径。
+
 ## 测试
 
 ```bash