# 2026-09-15 ComfyUI 升级 v0.34.0 → v0.35.0-42 + T8 节点包更新到 main

## 一、做了什么

| 项 | 升级前 | 升级后 |
|---|---|---|
| ComfyUI 核心 | `ec803fc9` = **v0.34.0-29**（2026-09-02） | `b2da2b42` = **v0.35.0-42-gb2da2b42**（2026-09-15/16，落后 105 个提交已全部拉入） |
| 前端包 `comfyui-frontend-package` | 1.51.9 | **1.52.7** |
| T8 节点包 | `custom_nodes/ComfyUI-MinimaxH3AudioT8`（非 git 安装，版本落后 main；缺 96 个节点类） | `custom_nodes/minimax-h3-audio-T8`（**git clone main** @ `1464a9f`，2026-09-15） |
| 已注册节点类 | 3361 | **3500**（+139） |
| 节点导入失败 | — | **0 个** |
| 队列/任务 | 升级前队列为空（未打断任何任务） | — |

## 二、本地补丁必须保留（重要）

`comfy/ops.py` 有一处**本机专用修改**，是 2026-09-09 为解决
**Qwen3-VL 文本编码（GQA + attention_mask）在 RTX 5060 Ti 上报 cuDNN "No valid execution plans built"** 而加的。

> **2026-09-15 已在本机逐条复现验证**（详见
> `2026-09-09-TextGenerate-cuDNN-NoValidExecutionPlans修复.md` 的「2026-09-15 复盘」一节）：
> - 关键条件是 `sdpa_kernel(优先级, **set_priority=True**)` —— 上游 ComfyUI 就是这么调的；
>   不带 `set_priority` 时 cuDNN 的失败会被容忍并落到 MATH，所以**必须带这个参数才能复现**；
> - 触发条件三段缺一不可：GQA+mask 下 flash/efficient 都无内核（实测 False/False）+ **`can_use_cudnn_attention` 谎报 True**
>   → 上游的 GQA 保护据此跳过手工展开 KV 头 → cuDNN 建图失败直接抛异常；
> - 去掉 CUDNN 后同一调用 **✅ 成功**（FLASH 失败 → EFFICIENT 失败 → MATH 兜底）；
> - `TORCH_CUDNN_SDPA_ENABLED=0` 在 torch 2.11 上**无效**，没有免改代码的等价开关。

```
No valid execution plans built  ← cuDNN frontend 直接报错，而不是回退到 MATH
```

修改内容：从 `SDPA_BACKEND_PRIORITY` 里**移除 `CUDNN_ATTENTION`**，并额外
`torch.backends.cuda.enable_cudnn_sdp(False)`。

**升级后新版 `comfy/ops.py` 仍然把 `CUDNN_ATTENTION` 排在 `FLASH_ATTENTION` 之后第一位
—— 也就是上游没修，所以补丁已用 `git apply` 原样装回**（`Hunk #1 succeeded at 68 (offset 1 line)`，干净应用）。

- 补丁留档：`/home/zyw/comfyui-update-20260915/ops-py-cudnnfix.patch`
- ⚠️ **以后每次 `git pull` ComfyUI 后都要重新 `git apply` 这个补丁**（否则 Qwen3-VL 文本编码可能崩）

## 三、回滚方法（完整可逆）

```bash
cd /home/zyw/ComfyUI
# 1) 核心回滚到升级前提交
git reset --hard ec803fc97ee3e5a923a90753ab3620d431109f85
# 2) 前端回滚
venv/bin/pip install comfyui-frontend-package==1.51.9
# 3) T8 节点包回滚（旧包已移出 custom_nodes，避免两个包同时注册同一个节点类）
mv custom_nodes/minimax-h3-audio-T8 /home/zyw/h3-t8/_bak/minimax-h3-audio-T8-new-20260915
mv /home/zyw/h3-t8/_bak/ComfyUI-MinimaxH3AudioT8-20260915 custom_nodes/ComfyUI-MinimaxH3AudioT8
# 4) 重启
bash /home/zyw/restart_comfy.sh
```

留档文件（`/home/zyw/comfyui-update-20260915/`）：
- `HEAD-before.txt`（升级前提交 `ec803fc97ee3e5a923a90753ab3620d431109f85`）
- `ops-py-cudnnfix.patch`（本地补丁，19 行）
- `pip-freeze-before.txt`（升级前 308 个包）

⚠️ 注意：旧 T8 包是**移动**到 `~/h3-t8/_bak/` 而不是留在 `custom_nodes` 里改名——
因为 ComfyUI 会扫描 `custom_nodes` 下所有带 `__init__.py` 的目录，两份同名节点包会**重复注册、互相冲突**。

## 四、工作流落地

`/home/zyw/ComfyUI/user/default/workflows/T8-H3精选/`（16 个工作流 + 14 份 README，468 KB）：

| 模式 | 文件 |
|---|---|
| 01-basic-generation | `2026-08-06_H3_Turbo_EXP_4V10A.json` |
| 02-audio-control | `2026-08-13_H3_Scheduled_Audio_Injection_Advanced_EXP.json` |
| 03-image-video-edit | `2026-08-28_H3_CADS_Visual_Reference_Annealing_Advanced_EXP.json` |
| 04-long-video | `2026-08-28_H3_FreeNoise_Prompt_Relay_EAV_Long_Video_Advanced_EXP.json` |
| 05-speech-dialogue | `2026-08-22_H3_Audio_Integrity_Audit_Advanced.json` |
| 08-multi-keyframe | `2026-08-09_H3_MultiKeyframe_Advanced_EXP.json` |
| 10-speed | `2026-08-19_H3_SPEED_FL2VA_Remix_Stock20_Advanced_EXP.json` |
| 12-system-memory | `2026-08-13_H3_Activation_Chunk_Advanced.json` |
| 13-latent-upscale | `2026-08-21_H3_Learned_Latent_TwoPass_Hybrid_Lock_Source_Advanced_EXP.json` |
| 14-prompt-relay | `2026-08-23_H3_Prompt_Provider_Router_Advanced_EXP.json` |
| 18-audio-refine | `2026-08-29_H3_Audio_Refine_EAV_Turbo8_Advanced_EXP.json` |
| **24-mv-lipsync** | `VocalLock_V3_Official_Ref2V_Turbo4`（**推荐**）、`VocalLock_V2_8Step`、`LipSync_Ref2VA_Turbo4`（旧兼容路线，作者说**不能**作为口型验收） |
| 28-progressive-sampling | `2026-09-09_H3_Progressive_I2VA_6plus2_EXP.json` |
| 33-selflift-taomate | `2026-09-14_H3_SelfLift_I2VA_Core_Sage_4plus4_EXP.json` |

**验证结果：升级后 16/16 全部可干净打开**（升级前有 3 个缺节点）。

## 五、遗留风险（升级带来的）

1. **T8 Prompt Relay 的 tokenizer 校验 bug**：社区 issue #20 报告在 **ComfyUI 0.35.0** 上复发
   （`native MiniMax H3 tokenizer lacks the byte-token contract`），**至今 open、作者 0 回复**。
   你现在正好是 0.35.0-42 → **`MiniMax H3 Prompt Relay Conditioning` 节点运行时可能报这个错**。
   规避：暂时别用该节点（`14-prompt-relay` 那个工作流其余部分可用），或等 T8 修复。
2. **T8 列过的上游破坏点已全部包含在本次 105 个提交里**：`efd4e951a`、`2504e68d4`、
   `e308cc73b`（Sol-Attn/SLA/VSA 合并为原生 Block Sparse Attention）、`804eb5513`；
   本次升级后 **0 节点导入失败**，但**新功能（outpaint/DLSS/VDN 等）只做过注册检查，没跑过真实生成**。
3. **两个节点仍未注册**（属预期，非本次遗漏）：
   - `MiniMaxH3BlockCacheT8` → 来自**另一个仓库** `comfyui-minimax-h3-blockcache-T8`，未安装
     （已克隆在 `~/h3-t8/`，要装再说；它默认 `cache_device=cpu`、音视频分别判稳）
   - 个别 EXP 节点同属未安装的独立包

## 六、待你决定

- 是否装 `blockcache` 独立包（+它要求 ComfyUI ≥0.30.0，你已满足）
- 是否做一次**真实生成冒烟测试**（挑一个小工作流跑通，确认 105 个提交的跳跃 + T8 新包在真机上没问题）
- 之前悬着的三件：KJNodes 低显存节点接入 / 功耗墙 144W / 关 `MiniMaxH3Cache` 做基准

---

## 七、升级后的第一个兼容故障：Director 报 `TypeError: unsupported operand type(s) for //: 'str' and 'int'`

**现象**（2026-09-16 04:54）：Director rv2v 任务一提交就失败，25–33 秒即报错：

```
File "comfy_extras/nodes_minimax_h3.py", line 86, in _empty_av_latent
    video = torch.zeros([batch_size, 24, latent_t, height // 16, width // 16], ...)
TypeError: unsupported operand type(s) for //: 'str' and 'int'
```

**根因：ComfyUI 0.35 把 H3 核心节点迁移到新的 V3 `io.ComfyNode` schema API，参数顺序变了**

| | 参数顺序 |
|---|---|
| 0.34（旧） | `(clip, vae, audio_vae, prompt, width, height, length, ref_image_size, …)` |
| 0.35（新） | `(clip, prompt, width, height, length, ref_image_size, vae=None, audio_vae=None, …)` ← **vae / audio_vae 挪到后面** |

旧 Director（`b8f721c`）用**位置参数**调用 → 错位后 `height` 收到的是 **prompt 字符串** → `height // 16` 抛 TypeError。

**修复：把 Director 更新到上游 `5a8e380`（2026-09-16）** —— 上游**已经修过并留了注释**：

```python
# Keyword args: official execute() moved vae/audio_vae after
# ref_image_size. Positional calls send prompt into height
# (`TypeError: ... for //: 'str' and 'int'` in _empty_av_latent).
out = MiniMaxH3ReferenceToVideo.execute(clip=clip, prompt=prompt, width=width,
    height=height, length=length, ref_image_size=ref_image_size,
    vae=vae, audio_vae=audio_vae, ref_images=..., ref_videos=...,
    ref_video_audios=..., ref_audios=...)
```

- 命令：`cd ~/ComfyUI/custom_nodes/ComfyUI_MiniMaxH3_Director && git pull --ff-only origin main`
- 变更量：**42 文件 / +6006 −812**；版本 `b8f721c` → `5a8e380`
- 备份：`/home/zyw/comfyui-update-20260915/conditioning.py.before-director-update`；回滚 `git reset --hard b8f721c`
- 验证：重启后 **0 导入失败**、3500 节点类、`MiniMaxH3Director` 已注册

**同类风险排查**：全 `custom_nodes` 里对核心 H3 节点 `*.execute(` 的调用只有两处——Director（已修）与
`CRT-Nodes/py/MiniMaxH3_Unified_Sampler.py`（**用的是关键字参数，不受影响 ✅**）。

**顺带获得的上游改进**（落后 20+ 提交）：一采缓存识别外接组、二采前清理显存（默认关）、
**段间引导低频对齐改 GPU 批量计算（1080p 段 427s → 0.37s）**、SigmaShift clone 复用避免显存泄漏警告、
r2v 参考图最长边 1024/1280/1536 选项、**自定义帧率同步修复**（正好解释日志里那个怪异的
`1001 frames @ 60.00 fps`）、Linux 分段导出不再写空目录。

**教训（写进升级流程）**：**ComfyUI 大版本升级后，第一件事是拿一个真实工作流跑冒烟测试**——
像本节的参数错位，光看"0 个节点导入失败"是发现不了的（节点能注册，但运行时签名不兼容）。