# comfyui-AICG3D 插件安装记录（2026-09-27）

> 关联评估报告：`dl-hub/59-comfyui-AICG3D插件评估/comfyui-AICG3D插件评估报告-20260927.md`
> 背景：该插件 main 分支自 2026-09-25 起 `__init__.py` 有语法错误，且把自带的 SelfLift 采样模块 mock 掉了，
> 直接安装无法加载。本次按报告结论安装**修复版**并分两步重启验证。

## 一、装了什么

| 项 | 值 |
|---|---|
| 来源 | GitHub `JGRFW/comfyui-AICG3D` main 分支快照（2026-09-25 最后推送，commit `ce2f362`） |
| 传递方式 | GitHub 在本网不可直连 → 本机（76）克隆后打包，经下载中心 8899 中转给 GPU 机 |
| 安装路径 | `/home/zyw/ComfyUI/custom_nodes/comfyui-AICG3D` |
| 体量 | 约 5.8 MB，463 文件（含 144 个提示词模板、45 个技能/方案） |
| 额外依赖 | **无**（`requirements.txt` 为空，未装任何 Python 包） |
| 模型改动 | **无** |

## 二、做的修复（`apply_fixes.py`，脚本已存 59 目录）

1. **P0-1 `__init__.py` 语法错误**：把被提出 `try` 块的 5 行 `print` 收回原处（对应 GitHub issue #6）。
2. **P0-2 SelfLift 采样被 mock**：删掉 `h3easy/nodes.py` 里 **3 处** `Mock for missing sampling_strategies.py`
   （第二处尾部粘连 `# ----audio`，普通字符串替换会漏），改为 `from h3easy.sampling_strategies import ...`。
   该文件与上游 nkxx188 版本逐字节一致，本来就躺在仓库里。
3. **P1-3 补注册 4 个 Goohai 节点**（`--with-gh`，实验性）：在 `aicg3d/registry.py` 的 `build()` 里把
   `MiniMaxH3IntegrationGH / MiniMaxH3IntegrationAdapterGH / MiniMaxH3DualClockT8GH / MiniMaxH3AVDecodeT8GH`
   塞进 `NODE_CLASS_MAPPINGS` —— 因为 ComfyUI 0.37 只在**顶层模块**查 `comfy_entrypoint`，而本插件会走
   V1 分支提前 `return`，`h3goohai` 子包的 entrypoint 永远调不到。

备份：`aicg3d/registry.py.bak-pre-gh`（打第 3 项补丁前的原件）。

## 三、验证结果（GPU 机 8189 实测）

```
启动日志：🚀 [AICG3D-Integrated] System Initialized / 📦 Loaded 34 production-ready nodes
报错检查：grep "Cannot import|Traceback|FATAL ERROR|An error occurred while retrieving information" → 0 条

/object_info：AICG3D_* 30 个 + Goohai GH 4 个 = 34 个，分类 AICG3D/H3 工作流、AICG3D/提示词与 Skill、AICG3D/H3 集成
  MiniMaxH3AVDecodeT8GH        | av_latent, video_vae, audio_vae
  MiniMaxH3DualClockT8GH       | model, av_latent, steps, shift_video, shift_audio
  MiniMaxH3IntegrationAdapterGH| integration
  MiniMaxH3IntegrationGH       | main_mode, clip_name, video_vae_name, ... ref_image_size

后端接口：/aicg3d/api/{skills,presets,prompt-guides,loras,media} 全部 HTTP 200
  → {"version":"1.0.0","skills":21,"presets":144,"prompt_guides":18,"loras":27}
前端资源：/extensions/comfyui-AICG3D/aicg3d-core.js 200 (38567 B)、minimax_h3_easy_ui.js 200 (497603 B)

自带工作流依赖：
  11.AICG3D_测试样板.json        5 节点  依赖齐全 ✔
  13.AICG3D_渲染器_二采高清放大  15 节点 缺 Label (rgthree) / MarkdownNote
  15.AICG3D_无限000.json         12 节点 同上
  （这两个是前端虚拟节点，本就不在 /object_info 里，属误报；本机已装 rgthree-comfy）
```

**未做的验证**：没有真跑一次 H3 生成（避免与占用显存的其它服务冲突）。
GH 那 4 个 V3 节点只验证到"注册成功、接口齐全"，**走 V1 通道实际执行是否正常尚未端到端验证** ——
首次使用时如报错，请优先怀疑这一点，回滚办法见下。

### 端到端生成实测（同日补测，已跑通）

用自带样板 `workflows/11.AICG3D_测试样板.json` 做了两组提交：

| 提交 | 结果 |
|---|---|
| 原样提交（工作流 JSON 里的值） | **HTTP 400 拒绝**，8 处 `value_not_in_list`：主模型 ×2、LoRA ×1（还是 Windows 反斜杠）、输入图找不到 ×1、中文枚举值 ×5（mode/keyframe_role/ref_image_size/reference_mention_mode/scene_guide） |
| 换成本机资源后提交 | **HTTP 200 → execution_success**，产出 `output/video/AICG3D_test_fixed_00001_.mp4`：1376×768 / 24fps / 5.17s / h264+aac / 1.1 MB，4 步采样（约 70 s/步），含首次加载 20 GB int8 模型共约 6.8 分钟；已自动进相册（family `MiniMax H3`，id `063093290afe4988961e66cd`） |

用的替换值：`fl2va_model=minimax_h3_fl2va_pruned_int8_convrot.safetensors`、
`ref2va_model=minimax_h3_ref2va_pruned_int8_convrot.safetensors`、
`lora_1=minimax_h3_fl2v_turbo_4step_v1.0_768p_comfyui_bf16.safetensors`（steps 3→4）、
参考图 `input/h3_rv2v_char_grok.jpg`、`mode=image / keyframe_role=first / ref_image_size=match /
reference_mention_mode=index / scene_guide=none`。
适配好的工作流：`dl-hub/59-comfyui-AICG3D插件评估/11-AICG3D测试样板-本机适配版-20260927.json`（拖进 ComfyUI 即可跑）。

结论：**插件本体能用，自带工作流不能拿来就用**（引用的是作者自己的模型/素材，且枚举值是旧版中文）。

## 四、回滚办法

```bash
# A) 只回滚 Goohai 补注册（保留 P0 修复）
cp /home/zyw/ComfyUI/custom_nodes/comfyui-AICG3D/aicg3d/registry.py.bak-pre-gh \
   /home/zyw/ComfyUI/custom_nodes/comfyui-AICG3D/aicg3d/registry.py
bash ~/restart_comfy.sh

# B) 完全卸载
rm -rf /home/zyw/ComfyUI/custom_nodes/comfyui-AICG3D
bash ~/restart_comfy.sh
```

## 五、使用提示

- 浏览器需 **Ctrl+F5 强刷**一次，前端面板（加载器自绘 UI、技能库、模板库）才会生效。
- 节点搜索框输入 **AICG3D** 即可看到整套节点。
- 本地 GGUF 提示词优化**不可用**（本机未装 `llama-cpp-python`，`models/llm` 为空）；云端模式需自备 API Key，
  且会把提示词与被引用素材发往第三方。
- 它的节点 ID 是 `AICG3D_H3*` 新命名空间，**不影响**现有官方 Director / dasiwa V18 / FaceRefine 工作流。

## 六、示例工作流的可见性修复（同日追加）

**现象**：用户在 ComfyUI 里"工作流"列表看不到 AICG3D 的任何样板。

**原因**：插件自带的 `custom_nodes/comfyui-AICG3D/workflows/` 目录 **ComfyUI 不会扫描** ——
工作流浏览器只读 `ComfyUI/user/default/workflows/`（递归）。这是所有 ComfyUI 插件的通病，不是本插件独有。

**处理**：把 3 个原版 + 3 个本机适配版全部放进 `ComfyUI/user/default/workflows/AICG3D/`：

```
AICG3D/11.AICG3D_测试样板.json                ✗ 5 处旧版中文枚举非法
AICG3D/11.AICG3D_测试样板_本机适配版.json      ✓ 全部合法（已实跑出片）
AICG3D/13.AICG3D_渲染器_二采高清放大.json      ✗ 3 个作者资产 + 5 处中文枚举
AICG3D/13.AICG3D_渲染器_二采高清放大_本机适配版.json  ✓ 全部合法（未实跑）
AICG3D/15.AICG3D_无限000.json                 ✗ 3 个作者资产
AICG3D/15.AICG3D_无限000_本机适配版.json       ✓ 全部合法（未实跑）
```

适配内容：`fl2va_model`/`ref2va_model`/`lora_1` 三个作者资产换成本机实际文件；
`AICG3D_H3` 的 5 个中文枚举换成英文（`图生或首尾帧→image`、`首帧优先→first`、
`1K 像素（…）→1k`、`按序号→index`、`通用→none`）。

**新增体检工具** `workflow_check.py`（59 目录 `附件-实测脚本/`）：对着 `/object_info` 逐节点核对
工作流里的控件值是否还属于合法枚举（能同时揪出"枚举改名"和"引用了不存在的模型/LoRA"两类问题，
这正是 issue #5 报错的两大成因）。用法：

```bash
python3 workflow_check.py --dir /home/zyw/ComfyUI/user/default/workflows/AICG3D
```

> 以后从网上下载的任何 AICG3D（或任意插件）工作流，跑之前先过一遍这个脚本，能省掉反复被 400 拒绝的排查。

## 七、补齐作者工作流引用的权重（同日追加）

**先回答一个常见误解：作者只提供工作流，不提供任何模型权重。** AICG3D 仓库里只有 3 个 `workflows/*.json`，
里面引用的模型/LoRA 全是社区公开权重。三份来源已核实：

| 工作流里写的 | 公开来源（HuggingFace） | 体积 | 处理 |
|---|---|---|---|
| `MiniMax/Minimax-h3_Singularity_ref2va_v1.3_int8.safetensors` | `WarmBloodAban/Minimax-h3_Singularity` | 31.67 GiB | **未下载**；本机已有同版本剪枝版 `Minimax-h3_Singularity_ref2va_Pruned_v1.3_int8.safetensors`（19.53 GiB，抖音测评作者用的正是这份），用**软链**顶上作者的文件名，省 31.67 GiB |
| `MiniMax/minimax_h3_fused_refdelta_r1024_turbo8_mystic07_int8_convrot.safetensors` | `MATLOWAI/minimax-h3-fused-turbo-int8-convrot` | 19.54 GiB | **已下载** → `models/diffusion_models/MiniMax/`，20,980,178,976 B |
| `minimax\taomate_h3_3step_comfy.safetensors`（Windows 反斜杠） | `Robert1212star/TaoMate-H3-3Step-ComfyUI` | 2.31 GiB | **已下载** → `models/loras/minimax/taomate_h3_3step_comfy.safetensors`（2,481,007,456 B，与 HF 逐字节一致）；另在 `loras/` 根建同名**反斜杠软链**，让作者那种 Windows 写法也能匹配 |

下载走 **hf-mirror.com**（HF 官方域名在本网不通），实测 ~19 MB/s，20 GiB 约 20 分钟。下载后必须**重启 ComfyUI**，
新权重才会进节点下拉列表。

**端到端验证**（`aicg3d_run.py author`）：直接用作者写在 13 号工作流里的三个原值 + 本机参考图提交 ——

```
HTTP 200 → execution_success（约 7 分钟，含加载 20 GiB 模型）
输出: output/video/AICG3D_author_assets_00001_.mp4  1376×768 / 24fps / 5.17s / 3.8 MB
```

即"作者原值"现在完全能跑（3 步采样，TaoMate 3-step LoRA）。成品已进相册（id `79ccac07de979a8a63701142`）。

⚠️ 仍然存在、且**无法靠下载解决**的一处：作者工作流里 `AICG3D_H3` 节点的 5 个控件值仍是旧版中文
（`图生或首尾帧` / `首帧优先` / `1K 像素（…）` / `按序号` / `通用`），当前节点收到的是英文枚举。
浏览器里前端会做中文→英文的翻译（所以界面上只报加载器那 3 个错），但**走 API 直接提交会被拒**。
用 `apply_fixes.py` 产出的适配版（或把 5 个值改成 `image/first/1k/index/none`）才能彻底干净。

磁盘：本次占用 +22 GiB，`/` 使用率 91% → **92%**（剩余 92 GB）。

## 八、GPU 机整机重启与 ComfyUI 重新拉起（追加）

2026-09-26 19:35 GPU 机**整机重启**（`uptime -s` = 19:35:20，内核日志里 nvidia 驱动同一时刻重新加载），
ComfyUI 随之中断 —— 用户在 UI 里的那次运行停在 `Model Initializing 0/3`，是被重启打断的，
**不是插件/工作流把 ComfyUI 搞崩的**（重启前的日志无 CUDA error / OOM；重启后 dmesg 已清空，看不到更早证据）。

重启后重新拉起：`bash ~/restart_comfy.sh`。冷启动约 **2 分钟**（脚本内置 38 秒探活会显示 `HTTP 000`，
属正常，继续等即可）。启动后自检全绿：

```
AICG3D 节点 30 + Goohai GH 4 = 34；导入错误 0
三个作者权重全部可识别（Singularity 软链名 / refdelta 实体文件 / TaoMate LoRA 的正反斜杠两个名字）
工作流列表：AICG3D-11 / -13 / -15 三个「可用版」
GPU：44°C、空闲显存 154MiB、无 Xid/ECC；掉总线防护 NVreg_DynamicPowerManagement=0x00 仍生效
```

⚠️ 整机重启会清空 `/tmp`。工具已留持久副本：`/home/zyw/workflow_check.py`（工作流体检）、
`/home/zyw/aicg3d-apply-fixes.py`（插件修复）。