# 工单：FastH3 V2 替代老 fasth3 —— KAP profile 正式切换（wt/fasth3v2）

## 0. 任务性质

实施批（非设计批）。把 KAP `/api/production/minimax-h3/*` 的 `fasth3` profile 从旧实现（dense DMD2 蒸馏 LoRA，SigmaShift+LoRA 链）**替换**为新实现（FastH3 V2 全量 checkpoint + BlockSparseAttention VSA 稀疏注意力链）。profile 名保持 `fasth3` 不变，KMC 消费方无感。

## 1. 背景事实（全部 operator 实测，直接采用勿重新推导）

1. **仓库与 worktree**：真源仓 `/data/workspace/kais-aigc-platform`，工作线 `feat/ui-direct-action-fix`（HEAD=7c575949）。你的 worktree 已建好：`/data/workspace/kais-aigc-platform-wt/fasth3v2`（分支 `wt/fasth3v2-integration`，基于 7c575949）。node_modules 已 symlink 到主仓。开工先 `git log --oneline -3` 认环境。
2. **老实现考古锚**：`src/routes/production/minimax-h3/config.ts` L391-434 `H3_FASTH3` 常量区（LoRA：minimax_h3_fasth3_4step_dense_datafree_comfyui.safetensors，5步 SigmaShift+LoRA 链走 `buildH3WorkflowLightX2V` 拓扑）；`generate.ts` L1306-1311 `rawProfile === "fasth3"` → `loraShiftConfig = H3_FASTH3` 分支；profile 定义 config.ts L792-798。2026-09-09 集成 commit 可 `git log --all --oneline --grep="fasth3"` 考古。
3. **V2 新实现 = 全新链路，非换参数**：权重 `fastvideo_fasth3_8step_v2_pruned_int8_convrot.safetensors`（22.1GB int8_convrot 全量 checkpoint，非 LoRA），已入 comfyui-primary 容器 `/root/ComfyUI/models/diffusion_models/`（UNETLoader 裸文件名引用）。
4. **已验证的 ground truth 工作流**（配方真源，抄参数勿凭描述重写）：`/home/kai/shared/2026-09-16/fasth3v2-kap-integration/validated_workflow_ground_truth.json`（15 节点）。该图在真机两次渲染 success：1216×704/124f 与 1344×768 探针均过，输出 H.264+AAC 无块噪。节点链：
   `5 UNETLoader(V2 checkpoint) → 7 ModelAttentionBackend(attention="comfy kitchen attention") → 8 BlockSparseAttention(selection="vsa", selection.keep_percent=10, start_percent=0.2, end_percent=1.0, dense_blocks="", min_tokens=12288, extra_tokens=256, sink_conditioning="exact_kv_and_rows", verbose=true) → 9 MiniMaxH3SigmaShift(shift_video=10.0, shift_audio=3.0) → 12 KSampler(steps=8, cfg=1.0, sampler_name="res_multistep", scheduler="simple", denoise=1.0)`；CLIP=6 CLIPLoader(qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors, type="minimax")；latent=11 EmptyMiniMaxH3LatentAV；解码=15 VAEDecode(vae minimax_h3_video_vae_fp16.safetensors) + 21 VAEDecodeAudio(vae minimax_h3_audio_vae_fp32.safetensors)；尾段=22 CreateVideo(fps 24) → 23 SaveVideo。负面=13 ConditioningZeroOut。
5. **⚠️ V3 DynamicCombo API 格式**（区块 Sparse/SaveVideo 的 inputs 形状）：combo 主输入=裸 key 字符串，子参数=`父.子` 点前缀提升到节点顶层。照 ground truth JSON 逐字抄即可；**禁**用 UI 元组式 `["vsa", {...}]`（校验全绿但执行期 TypeError）。SaveVideo 必须 `format:"auto"` + `"format.codec":"auto"`。
6. **下载兼容性**：SaveVideo outputs 落 `images` 键（单文件含音轨）。`replace-audio.ts downloadVideoFromOutputs`（generate.ts L1427 消费）已兼容 videos/gifs/images 三键且 `-audio` 优先逻辑对单文件回落 list[0] = 正确。**下载侧零改动**。
7. **per-mode 400 守卫已存在**（t2va.ts L413-418 / i2va.ts L446-451 / ref2va.ts 同构）：`fasth3` 在 per-mode 路由 400 拒绝，文案写 "FastH3 loraShift workflow chain"。本批保持守卫语义不变，仅文案同步（loraShift → checkpoint+VSA）。
8. **i2va/ref2va conditioning 段**：ground truth 是纯 t2va 图。i2va/ref2va 需要 conditioning 节点（ImageToVideo / ReferenceToVideo），**参考 `buildH3WorkflowNative`（generate.ts L389 起）的 conditioning 构造方式**——把 conditioning 输出接新链 KSampler 的 positive/latent_image 槽位（KSampler 槽位结构与 native 相同）。此组合（VSA 链 × conditioning 节点）operator 未真机验证，属割接冒烟项（见 §5）。
9. **基线证据**（同目录 /home/kai/shared/2026-09-16/fasth3v2-kap-integration/）：`tsc_baseline.txt`（TSC_RC=0）、`test_baseline.txt`（fasth3Profile.test.ts 1/1 pass, RC=0）。
10. **shift 口径**：V2 用 shift_video=10.0 / shift_audio=3.0（V2 包内蓝图口径），**非**老 fasth3 的 6/3。步数 8（权重名 8step，蓝图口径）。cfg=1.0。
11. 长度/分辨率边界：本批**不新增** length 硬边界（同老 fasth3 语义走全局 1216×672/362f 家族逻辑）。V2 真机只验证过 124f@两分辨率，362f 未测（operator 割接冒烟用默认 5s/124f）。

## 2. 任务

- **C1 config.ts**：新增 `H3_FASTH3_V2` 常量区（checkpoint 文件名/steps 8/shift 10,3/sampler res_multistep/scheduler simple/cfg 1.0/VSA 参数组 keep_percent=10, start=0.2, end=1.0, min_tokens=12288, extra_tokens=256, sink=exact_kv_and_rows/attention="comfy kitchen attention"），注释含 ground truth 路径与验证记录。`H3_PROFILES["fasth3"]` 档位改写：label/steps=8/其余布尔同旧（skipFoley=true, turbo/native/tespeed=false）。删除 `H3_FASTH3` 旧常量（先 grep 确认仅 fasth3 分支消费）。`H3_EXPOSED_PROFILES` 白名单不动（fasth3 已在内）。
- **C2 generate.ts**：新增 `buildH3WorkflowFastH3V2(opts)` builder（第五个 builder，导出供测试直调，同 buildH3WorkflowLightX2V 先例）：按 §1.4 节点链构图 + native builder 式 conditioning 段支持 t2va/i2va/ref2va 三 mode（ref2va 时 MiniMaxH3ReferenceToVideo）。分派：`rawProfile === "fasth3"` → V2 builder（替换原 loraShiftConfig 分支，H3_FASTH3 引用一并清除）。模型名常量沿用 H3_DEFAULTS（clip/ref2va 语义对齐 native builder 现状）。
- **C3 per-mode 守卫文案**：t2va/i2va/ref2va 三处错误文案 "loraShift workflow chain" → 与新链路一致（如 "FastH3 V2 checkpoint+VSA workflow chain"）。守卫逻辑本身零改动。
- **C4 fasth3Profile.test.ts 重写**：断言 V2 构图（逐节点 class_type/关键 inputs 对 ground truth JSON）、H3_FASTH3_V2 常量值、H3_PROFILES.fasth3 档位、per-mode 三路由 400 守卫、三 mode 构图差异（i2va 有 ImageToVideo / ref2va 有 ReferenceToVideo）。参考现测试文件结构。
- **C5 交付文档** `docs/fasth3v2-integration.md`：改动清单（逐文件）、与老实现的差异表、operator 割接序列（merge → tsc → 测试 → KAP 部署 → curl /workflows 验证 → POST /generate profile=fasth3 三 mode 冒烟）+ 回滚序列。

## 3. 红线（逐文件正面白名单）

- 只可修改/新增：`src/routes/production/minimax-h3/config.ts`、`generate.ts`、`t2va.ts`、`i2va.ts`、`ref2va.ts`、`__tests__/fasth3Profile.test.ts`、`docs/fasth3v2-integration.md`。其余任何文件一律不动（workflows.ts 的能力清单 API 读白名单自动反映，无需动——若实测需动，停手写进交付文档待批）。
- **禁 GPU 渲染任务**：禁向 ComfyUI :8188/:8190 提交任何渲染、禁 curl /prompt、禁 docker GPU 操作。真机冒烟归 operator 割接。
- 禁 push、禁 restart 任何服务/容器、禁碰主仓（提交只进你的 worktree 分支 `wt/fasth3v2-integration`）。
- worktree 内 node_modules 是 symlink，勿删除勿替换。
- 提交前缀 `feat(fasth3v2):`。

## 4. 验证命令（operator 验收将原样独立复跑）

```bash
cd /data/workspace/kais-aigc-platform-wt/fasth3v2
npx tsc --noEmit                                            # 基线 RC=0，不得新增失败
node --import tsx --test src/routes/production/minimax-h3/__tests__/fasth3Profile.test.ts   # 全绿
node --import tsx --test "src/routes/production/minimax-h3/__tests__/*.test.ts"             # 邻域全家桶不回归
```

## 5. 边界声明

- i2va/ref2va × VSA 链的真机验证、362f 长度边界、KAP 部署与冒烟 = operator 割接阶段执行，不在本批。
- 老 LoRA 权重文件（/data/models/comfyui/loras/minimax_h3_fasth3_4step_dense_datafree_comfyui.safetensors）本批不删（operator 退役清理另行处理）。
- VSA verbose=true 保留（日志可观测），如 ComfyUI 日志噪音问题由 operator 后续调。