# 工单：KMC final 档 vdn-8 自动路由副档（0916 定谳落地）

## 背景（已定谳，勿重议）

2026-09-16 gpunoise 9case 四臂盲选（同seed同refs·uncontended·33/33实收）：
- vdn-8 得分率 72.2% 全场最高；与 lxv 直接对拍 6 镜 13:13 平 → 质量平局。
- val 组同 case 速度 vdn 快 1.3~1.4×（591/675/681s vs lxv 848/921/911s）。
- vdn 硬边界 241f（0907 两次 OOM 定谳）；引擎已有 `_cap_vdn_frames`（length≤226f 预钳）。
- rh-v4 条件路由已落地（`_route_rh`：单人+对白∨非人物，+中高动）。

## 任务：给 final 档加 vdn 自动路由（quality-parity 速度副档）

**文件**：`/data/workspace/kais-hermes-skills/plugins/kais_aigc/video_engine.py`（1017 行）

### 1. 新增 `_route_vdn_final(shot, episode_config, use_case) -> bool`

场景路由（仅 final 档自动路由，预览档永不自动 vdn）：
- `use_case != "final-shot"` → 直接 False
- 判据（全部满足）：
  a. 人物数 ≤1（`character_refs` 列表长度；缺字段按 1 —— 语义抄 `_route_rh`）
  b. 细节敏感信号任一命中：
     - 对白镜：`dialogue_text` / `dialogue_note` 非空（抄 `_route_rh` 的 has_dialogue）
     - 特写景别：`shot_scale` / `shot_type` 上大写化后子串含 {"CU", "MCU", "INSERT"} 之一
     - 低动：`_classify_motion(shot) == "low"`
  c. 硬边界保护：`_cap_vdn_frames` 钳后 length 仍 > 226 → False（防边界拒单打穿扇出；
     帧数算法规抄 `_compute_expected_frames`，钳制语义照 `_cap_vdn_frames`）
- 无命中回退 False（保守回退，同 `_route_rh`）
- 日志：`logger.info("h3_engine: %s scene-route h3_vdn_final=%s ...", ...)` 带 `use_case` 与命中信号

### 2. `_resolve_h3vdn(shot, episode_config, use_case)` 重构

家族语义照抄 `_resolve_h3rh`：
- shot 级 `h3_vdn` > episode 级 `h3_vdn` > `_route_vdn_final` 自动路由
- 键存在即独占决定权（显式 False/"off" 抑制不回落）；真值解析 bool/"on"/"true"/"1" 同构
- **语义变化点**（向后兼容说明写进 docstring）：原 `_resolve_vdn` 无显式配置=永远 False；
  新逻辑无显式配置=自动路由判定。显式全量开（episode 级 h3_vdn=true）行为不变（preview 也 vdn）。
- **优先级不变**：显式双开时 vdn > rh（render 分支现有顺序零改动）
- render() 消费点：现有 vdn 判定换调 `_resolve_h3vdn`，日志注明三态来源（auto/shot/episode）

### 3. 测试（tests/test_video_engine.py 追加 TestH3VdnFinalRouting，≥10 断言）

- final + 单人 + 对白 → auto True
- final + 单人 + CU 景别 → auto True
- final + 单人 + 低动 → auto True
- **preview + 同信号 → False**（预览不自动 vdn，回退现有链）
- final + 多人（character_refs 长度 2）+ 对白 → False
- final + 单人 + 中动非特写无对白 → False
- **final + 细节镜 + 钳后 >226f → False**（硬边界保护生效）
- final + 细节镜 + 钳后 ≤226f → True
- shot 级 h3_vdn=False 抑制：即使 auto 信号全命中 → False 且不回落 episode 级 true
- shot 级 h3_vdn=True 全量：preview 也 True（显式开关行为不变）
- episode 级 h3_vdn=true：无 shot 覆盖时全量 True（行为不变）
- 显式双开 vdn>rh 优先级回归（render 分支既有测试不破）

### 验收

1. `pytest plugins/kais_aigc/tests/test_video_engine.py` 全文件绿（新类全过 + 既有 h3_vdn/h3_rh 测试零回归）
2. 冒烟渲染由 agent 侧做（司机不用跑渲染）
3. commit 规范：
   `feat(kmc-final-vdn-sub-tier): 0916 定谳落地 — final 细节镜 vdn-8 自动路由（质量平局速度副档）+ 226f 硬边界保护`

## 纪律

- 不动 KAP；不动 preview 链路现有行为；不碰 rh 路由逻辑
- 不改 `_cap_vdn_frames`/`_compute_expected_frames` 本体，只调用
- 仓内直接提交（kais-hermes-skills 单 commit），不 push