# comfyui-SelfLift 下载与安装记录

- 日期：2026-09-17
- 目标机：GPU 机 `192.168.31.31`（ComfyUI 0.35.0 / Python 3.12.3 / torch 2.11.0+cu130）
- 关联报告：同目录 `comfyui-SelfLift调研报告-20260917.md`

---

## 一、下载了什么，落在哪

| 内容 | 位置 | 状态 |
|---|---|---|
| **上游插件** `facok/comfyui-SelfLift` | GPU 机 `/home/zyw/ComfyUI/custom_nodes/comfyui-SelfLift`（git clone，可 `git pull` 更新） | **已安装** |
| 上游源码备份副本 | DSH 机 `~/Downloads/selflift-repos/upstream-selflift` | 仅存档，供本地读码 |
| **Avatar 实验分支** Release ZIP | GPU 机 `/home/zyw/Downloads/selflift-repos/selflift-Avatar-v0.1.1-experimental.zip` | **已下载未安装**（避免多注册 3 个节点） |

### 版本锁定（关键，因为上游无 tag / 无 Release）

- 上游 commit：**`19ec540505dcbc261aaecf450d83c7536be2826d`**
  - 提交时间：2026-09-12 23:56:11 +0800
  - 提交信息：`Revert "Drop guide color mean correction"`
  - 与远端 `git ls-remote HEAD` 一致 → 即当时最新 master
- Avatar ZIP：
  - 大小 `44018` 字节，**16 个文件**
  - `sha256 = 9c0c47e96563b5388f0aca5a63a521fc368e2c440ca98f773a45c3e603dc57f5`
  - ZIP 完整性检测（python `zipfile.testzip()`）：**通过，无损坏**

---

## 二、安装后验证（都已实跑）

| 检查项 | 结果 |
|---|---|
| 网络 | GPU 机 **可直连 github.com**（无需代理），`git ls-remote` 返回正常 |
| 文件齐全 | `__init__.py` `nodes.py` `selflift.py` `h3_upscaler.py` `h3_tiling.py` `h3_tst.py` `diagnostics.py` + README×2，全部就位 |
| 语法编译 | `venv/bin/python -m py_compile` 7 个文件 **全部 OK** |
| ComfyUI 依赖 API | `comfy.nested_tensor` / `comfy.k_diffusion.sampling` / `comfy.model_management` / `comfy.model_patcher` / `comfy.model_sampling` **全部可导入**；`NestedTensor` 类存在 |
| **真实加载插件**（模拟 ComfyUI 导入 `__init__.py`） | **导入成功**，注册 3 个节点：<br>`SelfLiftH3Sampler` → SelfLift Progressive Sampler (MiniMax H3)<br>`SelfLiftImageSampler` → SelfLift Progressive Sampler (Image)<br>`SelfLiftH3TST` → H3 Temporal State Transport (TST) |

**结论：插件在 ComfyUI 0.35.0 上可以干净加载，无缺 API、无语法问题。**

---

## 三、外部 H3 upscaler 已就绪（无需再下载）

GPU 机 `ComfyUI/models/latent_upscale_models/` 现有：

```
ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors   950 MB   （名字不含 h3，不会被默认选中）
minimax_h3_latent_upscaler_3d_bf16.safetensors            659 MB
minimax_h3_latent_upscaler_3d_fp16.safetensors            659 MB
```

源码 `nodes.py:69-72` 的默认值逻辑：把所有候选按名字 **`sorted()` 排序**，取**第一个名字含 `h3`** 的作为默认值。
⇒ 排序后 `..._bf16` 在 `..._fp16` 之前，**节点默认选中的是 `minimax_h3_latent_upscaler_3d_bf16.safetensors`**（fp16 仍可在下拉里手动选）。Blackwell 上 bf16 没有精度劣势，用默认即可。

含义：**H3 节点的"外部 lifter"实用路线开箱即用**（`rho=0` + 默认 upscaler），不需要再装 LBH-123-AI 的节点包——SelfLift 自己在 `h3_upscaler.py` 里实现了该 upscaler 的推理。

---

## 四、⚠️ 当前尚未生效：必须重启 ComfyUI

- 正在运行的实例：PID `17332`，**启动时间 2026-09-16 06:48:36**，早于插件落地时间；
- ⇒ **插件代码尚未被加载**，现在打开网页看不到任何 `selflift` 节点；
- **只刷新网页无效**，必须重启后端。

重启入口（已核对，脚本里的启动参数与当前运行实例**完全一致**，且额外注入 nvrtc 库路径修复）：

```bash
bash ~/restart_comfy.sh     # 内含 pkill 防自杀匹配 + 等待 38s + 自检 HTTP 状态
```

脚本行为：备份旧日志 → 停旧实例 → `setsid nohup` 起新实例（`--lowvram --force-fp16 --reserve-vram 1.0 --fast-disk --cache-lru 2 --disable-pinned-memory --preview-method none --enable-manager`）→ 打印实例数与 `HTTP code`。

---

## 五、回退方式（一条命令）

```bash
# 卸载上游插件
mv /home/zyw/ComfyUI/custom_nodes/comfyui-SelfLift /home/zyw/Downloads/selflift-repos/discarded-comfyui-SelfLift
# 然后 bash ~/restart_comfy.sh
```

或按 commit 精确回退：`cd custom_nodes/comfyui-SelfLift && git checkout 19ec5405...`

若之后要试 Avatar 分支：解压 ZIP 得到 `selflift-Avatar/` 放进 `custom_nodes/` 即可（**注册 ID 与上游不同，可并存**；但**绝不能放两份 Avatar 副本**，会节点重复注册）。

---

## 六、下一步测试提醒（沿用调研报告的结论）

1. **最低风险先试 TST**：只接 `SelfLiftH3TST`，`tau=0.2`，采样器不动；对照 `不接 / tau=0 / tau=0.2` 三组，固定 seed。
2. **⚠️ 本机有"注意力补丁→GPU 掉总线"前科**（SageAttention patch 事件）：TST 是注意力注入型补丁，首跑务必**单独、短片段**，同时盯 `nvidia-smi`。
3. SelfLift 两个采样器**只吃标准 Euler + `s_churn=0`**；`noise_mask`、`highres_tiling`、TST 三者互斥（TST 与 tiling 不兼容）。
4. H3 数字人/换人场景**必须单独验收音频**（上游 issue #9「音频全是电子噪音」至今 0 回复未解决）。