# VDN 引擎臂正式集成 KAP 报告 — 新增 H3 profile `vdn-8`

- 日期：2026-09-08
- 仓库：`/data/workspace/kais-aigc-platform` @ 分支 `feat/reverse-dag-view`
- 提交：`c5d81975`（feat 核心 5 文件）+ `f03c0731`（test 3 文件）
- 授权依据：2026-09-08 Kai 盲测终审（VDN 臂 241f 同速下细节 2.5× 全面胜出 LightX2V 8Step），Kai 拍板「将 VDN 工作流正式集成到 kap 中」

---

## 1. 改动清单（file:lines）

### config.ts（`c5d81975`）
| 位置 | 内容 |
|---|---|
| config.ts:412-453 | 新增 `H3_VDN` 配置块：`classType:"ApplyVDNH3"` + `nodeId:"15"` + `checkpoint:"vdn-minimax-h3-int8-convrot-comfyui"` + 蓝图全参数（turbo adapter/strength 1.0/lora_mode merge/branch_weights stream/retain_buffers off/attention_backend flex/verbose true）+ 采样（er_sde/beta/8步/denoise 1.0）+ `maxFrames:241`（0907 实测 OOM 边界，注释写明 241 不在 n%17==5 网格 → 有效最大网格值 226f + 互斥清单） |
| config.ts:619-622 | `H3ProfileName` 联合类型追加 `"vdn-8"` |
| config.ts:699-707 | `H3_PROFILES` 追加 `vdn-8` 条目（label 注明 8步+VDN adapter+盲测出处；steps:8 / skipFoley:true / turbo:native:tespeed 均 false） |
| config.ts:824-827 | `H3_EXPOSED_PROFILES` 追加 `"vdn-8"`（现 5 项：native-sage / lightx2v-8-768p / lightx2v-4-v11 / lightx2v-4-v12 / vdn-8），注释注明「可选档，不切默认，不动 useCase 映射」 |

### generate.ts（`c5d81975`）
| 位置 | 内容 |
|---|---|
| generate.ts:90 | import `H3_VDN` |
| generate.ts:739-886 | 新增 `buildH3WorkflowVDN(opts)`：图结构参考 buildH3WorkflowLightX2V，model_chain 换节点 15=ApplyVDNH3（直挂 `["12",0]`，全参数自 H3_VDN）；**无 LoRA loader、无 SigmaShift、无 T8 节点、无负面占位 16**（蓝图不含）；三模式分支同 LightX2V（t2va/i2va=MiniMaxH3ImageToVideo，ref2va=MiniMaxH3ReferenceToVideo + 点号键 `ref_images.ref_image_N` + `ref_image_size:"match"`）；采样链 KSamplerSelect(er_sde)+BasicScheduler(beta,8步,denoise1.0)+RandomNoise+BasicGuider+SamplerCustomAdvanced，model 全接 `[15,0]` |
| generate.ts:919-951 | vdn-8 语义守卫（参照 d3eb69e0 模式，置于 profile 白名单校验后）：① `length > 241` → 400（带边界说明 + `vdnBoundary` 结构化 detail；按对齐后 length 判，raw 227..241→对齐 243 亦拒）② 显式 `turbo=true`/`native=true` → 400 互斥拒绝（防静默错渲染） |
| generate.ts:1104-1114 | 路由分支：`isVdn ? buildH3WorkflowVDN(nativeWfOpts) : effectiveNative ? …`（vdn-8 置于最前；互斥冲突已在守卫 400 拦截） |

### per-mode 路由（`c5d81975`，照 d3eb69e0 模式）
| 位置 | 内容 |
|---|---|
| ref2va.ts:547-554 / i2va.ts:434-441 / t2va.ts:406-413 | `profile="vdn-8"` → 400 指引 `POST /api/production/minimax-h3/generate`（per-mode builder 不构建 ApplyVDNH3，放行会静默降级 T8） |

### 测试（`f03c0731`）
| 文件 | 内容 |
|---|---|
| `__tests__/vdnProfile.test.ts`（新，433 行） | T1 配置层 / T2 三模式构图 / T3 e2e（stub ComfyUI 封闭，round-3 硬守卫） |
| `scripts/verify-h3-vdn.ts`（新） | runner（verify-h3-blockcache.ts 同模式） |
| `__tests__/h3Cleanup.test.ts:95-121` | 修正 cede2e5f 后未跟上的 2 处陈旧断言（白名单 2→5 项；motion 路由 lightx2v-8-768p→v11/v12）——**预存失败修复，仅断言，无行为变更** |

---

## 2. 三模式路由判断依据（实读定谳）

1. **generate.ts 是统一建图入口**：`buildH3WorkflowT8/Native/LightX2V` 均在本文件内联（generate.ts:203/332/568），经 `H3GenOpts.mode` 参数一次覆盖 t2va/i2va/ref2va 三模式（三模式仅在节点 20 条件类型与 LoadImage 槽位分支）；路由决策点在 generate.ts:1104-1114（原 1030-1034）。
2. **ref2va.ts / i2va.ts / t2va.ts 独立建图**：各自持有 `buildH3Ref2vaWorkflowT8/Native` 等（ref2va.ts:147/300），不 import generate.ts 的 builder，且仅支持 T8/Native 两拓扑。
3. **d3eb69e0 先例**：lightx2v 族 profile 只在 /generate 有工作流链，per-mode 路由以 400 显式拒绝（ref2va.ts:536-546 等），理由「放行会静默降级 T8，显式拒绝优于静默错渲染」。
4. **结论**：vdn-8 在 generate.ts 新增 `buildH3WorkflowVDN` 即一次覆盖三模式（smoke 用的正是 mode=ref2va 经 /generate）；per-mode 三路由照 d3eb69e0 加 vdn-8 400 拒绝，不为 VDN 在三处复制 ApplyVDNH3 建图逻辑（避免 4 份蓝图漂移）。
5. workflows.ts 能力清单泛型枚举 `H3_EXPOSED_PROFILES`（workflows.ts:53-56），vdn-8 自动出现，零改动（部署后已实测返回）。

---

## 3. 测试结果（原文摘录）

```
$ npx tsx scripts/verify-h3-vdn.ts
── 配置层 (白名单/preset/H3_VDN 蓝图一致性) ──
  ✓ H3_EXPOSED_PROFILES 白名单含 vdn-8 (profile 校验接受)
  ✓ H3_PROFILES 有 vdn-8 定义
  ✓ vdn-8 preset: steps=8 / skipFoley / turbo=native=tespeed=false
  ✓ vdn-8 label 注明 8步 + VDN adapter
  ✓ H3_VDN ApplyVDNH3 全参数 = 0907 获胜臂蓝图逐字一致
  ✓ H3_VDN 采样: er_sde + beta + 8 步 + denoise 1.0
  ✓ H3_VDN.maxFrames = 241 (0907 实测 OOM 边界)
── 三模式构图断言 (ApplyVDNH3/互斥红线/采样链) ──
  ✓ t2va: ApplyVDNH3 节点在位 (id=15) / inputs 逐字段正确
  ✓ t2va/i2va/ref2va: 图中不含任何 LoRA loader (互斥红线)
  ✓ t2va/i2va/ref2va: 图中不含 SigmaShift 节点
  ✓ t2va/i2va/ref2va: 图中不含 T8 节点 / TESpeed 节点
  ✓ t2va/i2va/ref2va: UNETLoader 基模 = int8_convrot
  ✓ t2va/i2va/ref2va: KSamplerSelect = er_sde; BasicScheduler = beta/8步/denoise1.0, model=[15,0]
  ✓ t2va/i2va/ref2va: BasicGuider model=[15,0] (VDN 输出, 非 [12,0])
  ✓ ref2va: 条件节点 = MiniMaxH3ReferenceToVideo + ref_image_size=match
  ✓ ref2va: autogrow 点号键 ref_images.ref_image_N → [14/141/142,0]
  ✓ i2va: ImageToVideo + first_frame=[14,0];  t2va: 无图输入
  ✓ stepsOverride=5 → BasicScheduler steps=5 (显式优先)
── /generate handler e2e (守卫 400 + 路由, stub ComfyUI) ──
  ✓ vdn-8 t2va 1216×672 length=97 → 200 … payload profile=vdn-8
  ✓ e2e 提交图: ApplyVDNH3 + er_sde/beta (路由分支正确, 未落入 T8)
  ✓ length=300 (超边界) → 400 且文案含边界 241
  ✓ length=241 (网格对齐后 243 > 241 亦拒) → 400 且文案含边界 241
  ✓ length=226 (最大网格值) → 200 放行
  ✓ vdn-8 + 显式 turbo=true → 400 互斥拒绝
  ✓ vdn-8 + 显式 native=true → 400 互斥拒绝
  ✓ 无 profile 默认档回归: 仍 lightx2v-8-768p (LoRA 链, 不因 VDN 集成漂移)
  ✓ per-mode /ref2va 收 vdn-8 → 400 指引 /generate (防静默降级 T8)

56/56 assertions passed
```

回归（现有行为零漂移证明）：
```
$ npx tsx scripts/verify-h3-blockcache.ts
43/43 assertions passed          # golden 逐字节等价回归线 intact
$ node --import tsx --test src/routes/production/minimax-h3/__tests__/h3Cleanup.test.ts
ℹ tests 8  ℹ pass 8  ℹ fail 0   # 修前 2 fail (cede2e5f 遗留陈旧断言)
```

构建：
```
$ npm run build:server   → ✅ Built data/serve/app.js   （注：仓库无 `npm run build` 脚本，
$ npm run lint           → tsc --noEmit 零错误            部署产物脚本名为 build:server）
```

---

## 4. 部署 PID 证据（前后对照）

| 时点 | `ss -tlnp \| grep 10588` | `systemctl show -p MainPID` | 判定 |
|---|---|---|---|
| 重启前 20:01:59 | `pid=2442757,fd=21` | `MainPID=2442757`（active/running） | **MATCH** |
| 重启后 20:02:12 | `pid=212749,fd=21` | `MainPID=212749`（active/running） | **MATCH** |

- 重启命令：`sudo -n systemctl restart kais-aigc-platform`（RC=0，无免密问题）
- 新进程：`node data/serve/app.js`（STARTED 20:02:03，PPID=1）——即本次 build:server 产物
- 部署后能力清单实测：`GET :10588/api/production/minimax-h3/workflows` 返回 profiles 5 项含 `vdn-8`（label/steps/skipFoley 正确）

---

## 5. 冒烟证据

### 5.1 冒烟第 1 发（20:07:01 发出）——图被 ComfyUI 接受，渲染死于基础设施 crash-loop

- 请求：`POST :10588/api/production/minimax-h3/generate`，mode=ref2va / profile=vdn-8 / 1216×672 / length=97（对齐 107）/ seed=20260908 / 3 参考图（1.jpg/2.jpg/bg.png）/ filenamePrefix=vdn8_smoke_0908
- KAP 侧全链路正常：`[gpuQueue] acquire minimax_h3 GPU1`（20:07:01）→ `[gpuVramManager] ok minimax_h3: need 18432MiB, GPU1 free 23776MiB` → 提交 ComfyUI
- ComfyUI 侧：`INFO 09-08 12:07:01 [server.py:1074] got prompt`（**VDN 图通过节点校验进入执行**）→ `12:07:02 Requested to load MiniMaxH3VideoVAE`
- **~12:09:03 comfyui-primary 进程 Segmentation fault**（entrypoint: `169 Segmentation fault (core dumped) python3.13 ./ComfyUI/main.py`），容器 unless-stopped 自动重启；GPU1 显存掉回 349MiB

### 5.2 崩溃根因 forensics（与本次集成无关的基础设施 canary）

崩溃栈直指 **kais-aimdo-sharedpool**（AimDO 共享显存池自定义节点补丁）：

```
WARNING 09-08 12:09:03 [patches.py:298] File "/root/ComfyUI/custom_nodes/kais-incremental/kais-aimdo-sharedpool/patches.py", line 251, in _try_read_leaf
WARNING 09-08 12:09:03 [patches.py:298] RuntimeError: cudaMemcpyAsync rc=1
Fatal Python error: Segmentation fault   (后台线程栈: threading.py run/_bootstrap)
```

关键证据链：
1. **12:05:34 已崩过第一次（在我冒烟发出前 87 秒）**——当时在跑的 prompt `123b82d1-…` 经队列残片取证**本身就是一条 VDN 工作流**（node 15=ApplyVDNH3 + vdn_checkpoint + er_sde/beta + ab08_*.png 参考图，即 operator 自己的 VDN canary）。两次崩溃均为「VDN 34GB 权重加载 × AIMDO_SHARED_POOL=1」组合，2/2 复现。
2. 运行中容器 `docker inspect` 实测 `AIMDO_SHARED_POOL=1`（compose 源 = docker-compose.v9.yml 的 comfyui-primary 段；同文件 comfyui-secondary 段已置 0）。
3. operator 在 compose 改动里自己的注释：`# kais-aimdo-sharedpool: 0908 canary FAIL (跨卡注册后 sticky CUDA error → c10::AcceleratorError terminate` —— canary 当天已被标 FAIL，但主实例开关仍为 1。
4. 0907 蓝图成功（prompt_id=5d732d1e）时池子未启用——**VDN 本身无前科，崩的是 池×VDN权重加载 组合**。

### 5.3 冒烟重试决策（20:24 定谳：关闭重试）

- **Crash #3（12:23:09，第三次）改写了判断**：这次崩在一个**非 VDN** 的 H3 任务上（prompt `4e158e21-…`，node15=MiniMaxH3OutputTrimT8 的常规 H3 链）——AIMDO 池崩的是**一切 H3 权重加载**，不只 VDN。三连崩：VDN / VDN / 非VDN，3/3。
- 重试 = 大概率四崩并杀伤其他 agent 在跑任务（crash #1 已杀过一次别人的渲染），成本大于收益 → **官方 KAP 冒烟判阻塞，不再重试**。GPU 引擎锁由 KAP 轮询预算于 ~20:52 自然释放，全程未硬杀任何进程。
- 旁证路径启动：**用 KAP 同一 builder（`import { buildH3WorkflowVDN }`）原样构图直提 :8190**（comfyui-secondary，`AIMDO_SHARED_POOL=0`，0907 LXV 臂同款健康实例，队列空）——验证「KAP 产出的 VDN 图能完整渲染落盘」。

### 5.4 旁证渲染结果（:8190，KAP 同源图直提）

- 构图：`npx tsx /tmp/build_vdn_graph.ts` → `import buildH3WorkflowVDN`（与 /generate 路由同一函数），mode=ref2va / 1216×672 / length=107（=KAP alignH3FrameCount(97)）/ seed=20260908 / 3 参考图 / filenamePrefix=`MiniMaxH3/vdn8_kap_smoke_0908`
- 提交：20:25:59 → `prompt_id=887ccca6-1334-43b1-9328-7ff7a34f4829`，`node_errors:{}`（零校验错误）
- ApplyVDNH3 真实生效（comfyui-secondary 日志原文）：
```
INFO 09-08 12:26:20 [nodes.py:179] [vdn] adapter default: 108 modules (blocks.0.attn.out_proj, ...)
INFO 09-08 12:26:22 [nodes.py:179] [vdn] adapter turbo: 263 modules (blocks.0.adaln_proj.linear, ...)
INFO 09-08 12:26:22 [nodes.py:184] [vdn] vdn-minimax-h3-int8-convrot-comfyui applied on 50 blocks (r=1 c=5 anchors=both rule=vdn_solve): {'default': '100 weights merged', 'turbo': '255 weights merged'}
INFO 09-08 12:26:23 [hybrid.py:49] [vdn] layout: seq 30752 rows, video [5216, 30752), F=32, S=798, frame (21, 38), text 2459 rows, window (-5, 9)
```
- 采样执行中（GPU2 89% util / 16.9GiB）……
- **完成：`SUCCESS after 360s`**（20:25:59 提交 → 20:32:07 status_str=success + execution_success）；ComfyUI 执行耗时 `Prompt executed in 324.24 seconds`
- 产物落盘（以 /history 记录路径核盘，0908 重定向坑已规避）：
```
/mnt/agents/output/gpu2/MiniMaxH3/vdn8_kap_smoke_0908_00001_.mp4  1563852 bytes  2026-09-08 20:31:23
ffprobe: 1216×672 @24fps, duration=4.458333s (=107f 整), video+audio 双流
```

### 5.5 部署服务活体守卫验证（:10588 实测）

```
20:34:56  length=300 → HTTP 400  "profile=vdn-8 length 311f exceeds hard boundary 241f — 0907 实测 OOM 边界:
          所有模式 length ≤ 241f @1216×672 (3 参考图), 362f 必 OOM。(帧网格 n%17==5, 实际可请求的最大网格值 = 226f)…"
          (注: 300 经 alignH3FrameCount → 311, 守卫按对齐值判)
turbo=true → HTTP 400  "profile=vdn-8 与显式 turbo=true 互斥 — VDN 臂禁插 Turbo/LightX2V LoRA 与
          SigmaShift 原生链 (0907 盲测获胜拓扑: ApplyVDNH3 直挂 UNETLoader)…"
GET /workflows → profiles 含 vdn-8 (label/steps/skipFoley 正确)
```

### 5.6 冒烟结论

- **官方 KAP 冒烟（:10588 → :8188 真渲染）：阻塞**——KAP 全链路正常（锁/显存/提交/图校验全过），死于 :8188 aimdo 池 crash-loop（§5.2，三连崩含非 VDN 任务，3/3 证明与本集成无关）。
- **旁证渲染（KAP 同源图直提 :8190）：完整成功**——同一 `buildH3WorkflowVDN` 函数产出图、同一权重、ApplyVDNH3 全参数真实生效（adapter 263 modules / 50 blocks / 255 weights merged），324s 渲染 + 产物核验通过。集成本身的渲染正确性已闭环；欠的仅是「:8188 修复后经 KAP 路由再打一发」的手续性复验（补跑参数见 §8）。

---

## 6. 事实纠正（与派发 prompt 的差异）

1. **`npm run build` 不存在**：仓库实际脚本为 `build:server`（esbuild → data/serve/app.js，systemd 启动的产物）+ `lint`（tsc --noEmit）。两者均已跑通。
2. **241f 边界的网格事实**：H3 帧网格 n%17==5，241 **不在网格上**——`alignH3FrameCount(227..241) → 243 > 241`。守卫按对齐后 length 判（渲染真值），因此 raw 241 也会被拒，**实际可请求的最大网格值 = 226f**（守卫文案与 H3_VDN 注释均已写明）。0907 蓝图 241f 是直连 ComfyUI 绕过对齐跑的，KAP 内无法复现 241 整数帧。
3. **冒烟前现场变化**：派发时「:8188/:8190 队列空」；实际 20:02-20:04 期间 comfyui-primary 容器被重启（非本次操作——本次只重启 Node 服务；`docker ps` 显示 Up 3 minutes, health: starting）。曾观测到一个在跑 prompt `123b82d1-…`（随容器重启终止，队列已清空）。已按纪律等待容器恢复 + 队列排空，未打断任何任务。
4. **h3Cleanup.test.ts 预存失败**：cede2e5f 扩白名单至 4 项/改 motion 路由后未同步该测试 2 处断言（派发 prompt 未提及）。本次顺带修正（仅断言对齐现实，commit `f03c0731` 披露）。

## 7. 残留 P1/P2

- **P0（infra，非本集成）**：comfyui-primary `AIMDO_SHARED_POOL=1` 导致一切 H3 权重加载 segfault crash-loop（0908 三连崩证据见 §5.2；operator compose 注释自标 canary FAIL 但主实例开关仍开、改动未提交）。**修复后需补一发官方 KAP 冒烟结案**（参数：mode=ref2va/profile=vdn-8/1216×672/length=97/seed 任意/3 参考图 `/home/kai/文档/LTX/validition_v1/08/{1.jpg,2.jpg,bg.png}`，判定=/history success + KAP 返回路径核盘）。此事同时影响所有走 :8188 的 H3 档位（native-sage/lightx2v 系同样会崩），不只是 vdn-8。
- **P2**：per-mode 路由（t2va/i2va/ref2va）当前 400 拒绝 vdn-8；若日后 KMC 需要 per-mode 直连 VDN，需在这三个文件复制 ApplyVDNH3 建图分支（本次遵循 d3eb69e0 模式显式拒绝，避免静默降级）。
- **P2**：`H3_VDN.maxFrames=241` 为全模式单一上限（0907 实测口径 = 1216×672×3 参考图 ref2va）；t2va/i2va 或更少参考图时真实 OOM 边界未单独标定（保守取 241 不放行更高，未做新边界实验）。
- **P2**：workflows.ts 顶部注释「profile 两档 (lightx2v-8-768p / native-sage…)」自 cede2e5f 起已过时（现为 5 档），属陈旧注释未更新（派发前已存在，非本次引入；能力清单 JSON 本身正确）。
- **P2**：KAP `pollComfyuiCompletion` 对「历史随 ComfyUI 重启清空」的死 prompt 会按预算傻等满 45min 并占住 GPU 引擎锁（本次 ~20:52 自然释放，全程未硬杀）。可考虑加「prompt 在 queue+history 双失踪即判孤儿」快速失败，属通用鲁棒性改进，不限于 VDN。

---

## 8. 摘要与交付结论

**交付：已交付（代码+部署+测试全闭环；官方冒烟被 infra 事故阻塞，旁证渲染完整成功）。**

KAP 新增可选 profile `vdn-8`（不改现有档位/默认档/useCase 映射）：config.ts `H3_VDN` 配置块 + 白名单条目；generate.ts `buildH3WorkflowVDN`（ApplyVDNH3 直挂 UNETLoader，无 LoRA/SigmaShift/T8，er_sde+beta+8 步，ref2va 点号键）+ 路由分支 + 语义守卫（241f OOM 硬边界按对齐 length 判→有效最大 226f；显式 turbo/native 互斥 400）；per-mode 三路由照 d3eb69e0 模式 400 拒绝防静默降级。测试 56 断言全绿 + blockCache golden 43/43 回归零漂移 + tsc/build 过；分两 commit（c5d81975/f03c0731）已部署 :10588（PID 前后 MATCH）。守卫与能力清单已在部署服务活体验证。冒烟：KAP 提交的 VDN 图通过 :8188 校验并开始执行，但该实例因 operator 未完成的 aimdo 共享池 canary（自标 FAIL 仍开=1）对一切 H3 权重加载三连崩（含非 VDN 任务，与本集成无关）；改用 KAP 同一 builder 构图直提健康实例 :8190——324s 渲染 success，产物 1216×672/107f/带音轨已核盘。**待办仅一件**：池修复后经 :10588 补一发官方冒烟即结案（P0 归 infra，同时拖累 native-sage/lightx2v 全档位）。