@@ -0,0 +1,152 @@
# 训练前缺陷修复设计（video-split → Video-MME 900 自进化训练）
> 2026-07-16。两轮审查（接线预检 + 8 维度多代理审查）共确认 19 bug + 接线缺口 + 切分层优化，本设计一次性覆盖。
> **目标**：让 video-split 冻结切分驱动的 Video-MME 900 题自进化训练**一次跑出有效结果**（不崩、不静默失效、信号不被污染）。
## 1. 背景与问题总览
自进化训练对标 PyTorch 训练循环（出题=DataLoader / 推理=forward / 诊断=backward / 进化=optimizer.step）。审查发现三类根问题：
| 类别 | 代表 | 后果 |
|------|------|------|
| **进化引擎哑火 ** | 5 个 evolve/momentum 模板 TRM4→TRM5 迁移遗漏，`else ""` 静默兜底 | 3 epochs 跑完但 skills 零进化，best 恒 v1 |
| **诊断链路坍缩 ** | traces 表从不写入（TracePlugin 未迁移） | 诊断瀑布拿空轨迹，算法保真 #7 失效 |
| **崩溃与信号污染 ** | 微型题型断言崩、prediction 非标量击穿、缓存跨 epoch 重放、SSE 截断毒化等 | 训练中途崩溃或统计信号失真 |
叠加**接线缺口**：冻结 `pools.json` 无路径进入训练 workspace（ `--fresh` 从 seed 重建不带切分），直接训练会静默丢弃标定成果、按 unit 重切。
## 2. 设计目标与非目标
**目标 ** ：修复全部 23 项确认缺陷 + 接线；切分层做三处优化（可训练性门槛、val_ratio、tier 感知分配）提升信号质量；产出零参可复现的训练入口。
**非目标 ** ：不改 gate/EMA 核心数学（算法保真 #4/ #5 ）；不实现 epoch 层 per-skill best 混搭（见 §9 future work）；不引入向后兼容（P4 显式优于隐式，直接改）。
## 3. 架构：四工作包按依赖序
``` mermaid
graph LR
WP1[WP1 资产迁移<br/>模板+fail-loud+死字段] --> WP3[WP3 训练循环与进化引擎]
WP2[WP2 切分与接线<br/>产出训练输入] --> RUN[训练启动]
WP3 --> RUN
WP4[WP4 韧性与持久化] --> RUN
WP1 -.集成测试依赖.-> WP3
```
WP1 零风险纯搬运先解锁引擎；WP2/WP4 与 WP3 无代码交集可并行；WP3 主体修复依赖 WP1 模板做集成测试。
## 4. WP1 —— 资产迁移（修 P0-1 / P0-6）
从 `/home/iomgaa/Projects/Video-Tree-TRM4/prompts/` 拷 5 文件到 TRM5 根 `prompts/` ： `evolve_skill/system/tool/rank.md` 、`slow_momentum.md` （进化引导 prompt = 引擎一部分，不参与版本化进化）。
- **迁移验收（强制）**：逐个核对模板输出契约与 TRM5 解析代码期望——`evolve_*` 的 `{suggestions, edits}` 结构 vs `_parse_llm_json` /`_apply_one` ； `slow_momentum.md` vs `run_slow_momentum` 。TRM4→TRM5 代码有漂移，裸拷贝不核对 = 新 bug。
- **加载器 fail-loud**： `_load_evolve_prompts` /`_load_diagnose_prompts` 的 `else ""` 改 `FileNotFoundError` （列缺失文件名）。
- **死字段清理**：删 `EvolvePrompts.consolidate_system` （ `DiagnosePrompts.span_eval_user` （无消费点）及对应 runner 加载行。
## 5. WP2 —— 切分与接线
### 5.1 tier 感知切分（`split_selection.py` / `build_split.py`）
trainval 内部视频组分配从"correctness 分层随机"升级为 **tier 感知确定性贪心 ** （纯函数、固定 seed）：
```
输入: 视频组（t2_count/t1_count/wrong_count/question_count，
目标: 最大化 diag 池 T2 捕获
约束: ①视频原子 ②val 题数 ≈ val_ratio ③val 错题 ≥ val_wrong_min 否则 fail loud
算法: 按 (t2_count desc, wrong_count desc, video_id) 排序装入 diag 至题数预算满 → 余下进 val
→ 校验③，违反则从 diag 尾部换出低 T2 组直至满足；有限步无解 → InfeasibleSplitError
```
配置：`config/video_split.yaml` `val_ratio: 0.3 → 0.4` （甜点：val 错题 29→~38 让整包终审更抗噪，diag 错题 64→~56 进化信号仍过剩；0.5 过冲、迭代次数受损）。tier 感知不加开关（无扫动需求，YAGNI）。重切零 LLM 成本（诊断已按指纹落库）。
### 5.2 冻结产物覆盖保护（修 P2-1）
`build_split` 冻结前检查产物存在性：存在且内容指纹不同 → 报错并提示 `--force` （ `--force` 时旧产物重命名 `pools.json.bak.<旧指纹前8>` 再写。
### 5.3 seed 携带切分（接线核心）
| 项 | 设计 |
|----|------|
| `init_seed` | 新增可选 `pools_json` /`split_manifest` ，提供则拷入 seed 目录 |
| `init_workspace_from_seed` | seed 目录有 `pools.json` 则连 manifest 拷入 workspace（拷 baseline.db 之后） |
| `build_or_load_pools` （ #2 ） `baseline_run_id` 匹配 seed；有 manifest 时校验 `sha256(pools.json)==manifest.pools_sha256` |
| 新 seed `adhoc-baseline` | `extract_run_db` 加 `dedupe_per_question` （每 qid 按 rowid 取首行，902→900 对齐 canonical） `init_seed(baseline_run_id='infer_adhoc', pools_json=…)` |
seed 最终形态：`seed.json / baseline.db(900) / pools.json / split_manifest.json / skills/v1 / prompts/v1` 。
## 6. WP3 —— 训练循环与进化引擎
| # | 缺陷 | 修法 |
|---|------|------|
| P0-3 | 微型题型三连雷 | `train()` 加**可训练性预检**（纯函数）：题型 `n_val<eval_min_per_class(2)` 或 `n_units<trainable_min_units(8)` → 从 diag/val + gate task_types 剔除并打印清单；断言/空阶梯保留作纵深防御；test 池不过滤 |
| P0-4 | prediction 非标量击穿 | 落库前 `_to_text_field` 归一化；`log.insert` 移入单题 try 块，绑定异常记 error 不击穿 gather |
| P0-5 | early_stop 单位错误 | step→**epoch** 计数（`epochs_since_best_improved` ），config 注释对齐，checkpoint 字段同步改名 |
| P0-2 | traces 空 | 复用离线管线 `StepsJsonRunLog` 适配器包装训练 RunLog， `get_traces` 空时从 steps_json 转换，算法 #7 恢复 |
| holdout | 四向重复评估 | baseline 从 seed 基线预测推导(0 推理)； ；
| P1-5 | 诊断降级误入 defect | `cause_category=None` (judge 基础设施异常)与 `degraded=True` 错题按 **lapse 方向分流 ** ；
| P2-3/#5 | step 重跑双计 + 慢更新非幂等 | `_run_step` 开始先 `DELETE ... WHERE run_id=<本step>` ； `_refresh_gate_ladder` 保存 gate_pools 后**立即**原子落盘 checkpoint(`gate_epoch_observed=True` ) 消除双计窗口 |
`run_holdout_eval` 保持开启（去重版），逐 epoch test 曲线四线齐全，成本从 2400 降至 600~1200 次/epoch。
## 7. WP3 —— 进化引擎 patch 加固（修 P1-6，算法 #8 防御）
| 层 | 改动 |
|----|------|
| 跨度判定 | `_in_ranges` 从"只查起点"改为"整个 target 跨度 [pos,pos+len) 与保护区相交即拒"； `_do_insert_after` 同 |
| 注入检查 | edit payload/target 含 `APPENDIX_START/END` 、`MOMENTUM_START/END` 字面量 → 拒绝该 edit |
| 最后防线 | `validate_skill` 增 marker 完整性校验（成对、有序、各至多一对），违反整体 reject |
不改"保护跨度"语义方向，只把已声明的保护做完整。
## 8. WP4 —— 韧性与持久化
| # | 缺陷 | 修法 |
|---|------|------|
| P1-1 | 缓存跨 epoch 重放 | `chat()` 加 `cache_salt` ；训练 rollout/val/test 链路注入 `f"{run_id}:e{epoch}"` （跨 epoch 真实重采样、同 epoch 续跑仍命中）；judge/evolve/离线切分无盐。TTL 修：`REDIS_CACHE_TTL≤0` 启动即 ValueError（消灭"0=永不过期"隐式语义）。**同步改 `.env` /`.env.example` 给正整数**（当前值 0，不改则修复后启动即崩），训练场景建议 ≥ 单次训练时长|
| P1-2 | SSE 截断毒化 | `_consume_stream` 校验 `[DONE]` /finish_reason 才算成功；流耗尽未完成抛 `_SseAnomaly` 进重试梯，**绝不写缓存** |
| P1-3 | 断连不重试 | `_is_transient_error` 扩为 `httpx.TimeoutException` +`httpx.TransportError` 两族 |
| P2-6 | 熔断半开烧穿 | cooldown 到期只放行 1 探针（half-open 锁），成功才闭合 |
| P1-4 | 基线臂 INFRA 污染 | INFRA 单元不写 BaselineCache、不计 W/L；护栏检查移到写缓存**之前** |
| P1-7 | manifest 非原子写 | `update_manifest/record_run/update_best/_scaffold` 统一 tmp+`os.replace` （复用 checkpoint 模式）|
| P2-2 | 基线元数据被改写 | 只读查询基线的两处改走只读连接，不经 `HarnessLog.__init__` upsert |
| P2-5 | dual_metric 口径歧义 | 慢更新 R2 行 `version_kind` 改 `slow_candidate` ， `final` 恢复唯一语义 |
| P2-4 | 离线 uncertain 不可重试 | `video_split_cli` 加 `--retry-uncertain` （
## 9. Rejected alternatives / Future work
| 选项 | 为何不做 |
|------|---------|
| epoch 层 per-skill best 混搭 | per-class val 样本太小(中类 5-10 题)终审频繁选错；prompts 随慢更新漂移致跨 epoch 成绩不可拼接。合理形态是训练**结束后**一次性 final assembly（每类取 gate 末次接受版本 + 最终 prompts，全 val 评一次比 best_hard），成本一次推理、不动循环 → **记 future work ** |
| val_ratio 0.5 | 每类 3 epochs 仅 ~4 次进化机会，迭代受损；val 错题 38→46 边际收益趋零 |
| 确定性评估(temp=0) | 统计效率最高但基线用默认温度采，换口径要重烧全部基线，本轮不可行 |
| 会计层去重替代 epoch 盐 | 需动 gate/EMA 保真区且造不出新信息（每题永远只见一次抽样）|
## 10. 非功能四维（全设计汇总）
| 维度 | 保障 |
|------|------|
| **持久化 ** | 冻结产物/manifest/checkpoint 全 tmp+replace 原子写；holdout 备忘录入 checkpoint |
| **幂等 ** | step 重跑先 DELETE 后写；seed/冻结产物存在即拒覆盖(--force 显式)；诊断按指纹 upsert 不变 |
| **断点续跑 ** | epoch 盐保同 epoch 命中；gate_epoch_observed 在 gate_pools 保存后立即落盘，消除慢更新双计窗口 |
| **原子性 ** | manifest 补齐原子写（对齐 checkpoint 先例）；pools 冻结沿用现有原子写 |
## 11. 测试策略
| 层 | 覆盖 |
|----|------|
| 单元(新增) | tier 选择器(真实 baseline_diagnosis 二次构造：T2 捕获/val 错题≥20/视频原子)；可训练性预检(真实 pools 驱动，5 微型类被剔)；patch 三层校验；SSE 未完成流拒收；瞬时错误清单；缓存盐入键；extract_run_db 去重；seed 携带拷贝；holdout 备忘录 |
| 单元(改语义) | early_stop 按 epoch；加载器 fail-loud；
| 集成 | fake-LLM 小池 train 冒烟(预检→模板→traces 适配→holdout 去重计数→step DELETE)；
| 回归 | 全量 1473 保持绿；agent/LLM 测试产 MD 到 `tests/outputs/` |
## 12. 训练启动 runbook（修复完成后）
```
1. 四工作包完成 + make test 绿
2. 备份 workspaces/video-split/ → 改 val_ratio:0.4 → 重跑 build_video_split.sh(诊断命中缓存秒级)
→ 核对: val 错题≥20 / T2 入 diag 数 / 预检模拟的可训类清单
3. 建 seed: extract_run_db(infer_adhoc,dedupe) + init_seed('adhoc-baseline', pools_json=…)
4. 新增 config/train_videomme.yaml + scripts/train_videomme.sh(零参可复现):
epochs=3, early_stop_patience=2(epoch), run_holdout_eval=true(去重版),
trainable_min_units=8, 其余 gate/batch 沿用 default.yaml
5. tmux: CUDA_VISIBLE_DEVICES=0 bash scripts/train_videomme.sh
```
