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 目录）

P0-1 __init__.py 语法错误：把被提出 try 块的 5 行 print 收回原处（对应 GitHub issue #6）。
P0-2 SelfLift 采样被 mock：删掉 h3easy/nodes.py 里 3 处 Mock for missing sampling_strategies.py （第二处尾部粘连 # ----audio，普通字符串替换会漏），改为 from h3easy.sampling_strategies import ...。该文件与上游 nkxx188 版本逐字节一致，本来就躺在仓库里。
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 即可跑）。

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

四、回滚办法

# 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 报错的两大成因）。用法：

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（插件修复）。

2026-09-27-comfyui-AICG3D插件安装记录.md