# comfyui-AICG3D 插件评估报告

- 评估对象：<https://github.com/JGRFW/comfyui-AICG3D>（"AICG3D-Integrated"，MiniMax H3 统一创作工作台）
- 评估日期：2026-09-27
- 评估环境：GPU 机 `192.168.31.31`，ComfyUI **0.37.0** + comfyui-frontend 1.53.6（Python 3.12 venv）
- 评估方式：仓库静态审计（本地克隆 main，463 个受版本控制文件）+ **GPU 机实机加载实测**（用 ComfyUI 自带 venv 直接 import 插件包）

---

## 一、一句话结论

**思路不错、周边很全（提示词/技能/模板库 + 节点合并），但当前代码质量堪忧，直接装 main 分支会 100% 加载失败。**
我实测定位了 3 个真实缺陷（其中 2 个致命），并把修复脚本写好、在 GPU 机上跑通验证（修复后 30 → 34 个节点正常注册）。
就我们这套环境而言：**值得装（用修复版），但不装也不影响现有出片链路。**

**后续补充（同日晚，用户追问"这不是可以直接用的吗"之后补测）**：把我的修复版装好后做了端到端实测 ——
**插件本体确实能出片**（4 步采样出 5.17 秒视频，见第八节）；但**它自带的示例工作流不能直接用**，
按原样提交被 400 拒绝 8 处（见 P1-4），必须自己重选模型/素材/枚举值。所以准确说法是：
**"插件修好 = 能用；自带工作流 ≠ 拿来就用。"**

---

## 二、这是什么

作者（JGRFW）把三套东西合并成一个 ComfyUI 插件包：

| 来源 | 作者 | 许可 | 在包里的实际分量 |
|---|---|---|---|
| ComfyUI-MiniMaxH3-Easy（⭐785） | nkxx188 | MIT | **骨架**：25 个 H3 主节点 |
| Goohai-MiniMax-H3_Integration（⭐196） | goohai（B站 孤海FOTO） | GPL-3.0-or-later | 提示词优化引擎（云端 API + 本地 GGUF）+ 音视频解码 |
| MiniMax-AI/MiniMax-H3 官方 | MiniMax | H3 Community License | 提示词规范 / 技能包 |
| 中文社区提示词合集 | 各原作者 | **未标注** | `prompt_presets/` 144 个模板 |

仓库自带：45 个技能/方案、144 个提示词模板（8 分类、约 **91 万字**）、3 个示例工作流、自绘深色主题面板、`/aicg3d/api/*` 后端接口。
规模：5.8 MB、463 文件；热度 ⭐99 / fork 10；创建 2026-09-12，最后推送 2026-09-25；**7 个 open issue**。

---

## 三、实机验证发现的 3 个问题（含证据）

### 🔴 P0-1：main 分支 `__init__.py` 语法错误 —— 插件整包加载失败

2026-09-25 的提交 `3d53501`（"Update README ... and professional console logs"，署名 **Codex Agent**）把 try 块里的 5 行 `print` 提到了顶格：

```python
    print("\n" + "!"*60)
print("\n" + "="*50 + "\n")      # ← 21 行，顶格，try 块在此中断
print("🚀 [AICG3D-Integrated] System Initialized")
...
except Exception as e:            # ← 于是 except 找不到 try
```

实测（GPU 机，ComfyUI venv）：

```
[A] 未修复版 -> SyntaxError: expected 'except' or 'finally' block (_broken_init.py, line 21)
```

**这不是我推演出来的**：GitHub issue #6《【BUG】今天版本更新后报错》贴的报错和我这里逐字一致，社区用户只能"一直回退到版本号 b376ea8（2026-09-25 9:34:12）"才恢复。也就是说 **main 从 9-25 起就是坏的，到今天仍未修**。

### 🔴 P0-2：README 主打的 "SelfLift 策略增强" 被自己的 mock 顶掉了

`h3easy/nodes.py` 开头有 **3 处** 这种代码（第 46、57、78 行，其中第二处尾部还粘着半句 `# ----------audio`）：

```python
# --- AICG3D Mock for missing sampling_strategies.py ---
SAMPLING_PLAN_TYPE = "default"
SELFLIFT_KIND = "none"
class MiniMaxH3SamplingPlan:
    def __init__(self, *args, **kwargs): pass
def sample_with_sampling_plan(*args, **kwargs):
    return None
```

问题是：**`h3easy/sampling_strategies.py` 就在仓库里，而且与上游 nkxx188 的同名文件逐字节一致**（diff 无差异），上游原本的写法是：

```python
from .sampling_strategies import (
    SAMPLING_PLAN_TYPE, SELFLIFT_KIND, MiniMaxH3SamplingPlan,
    sample_with_plan as sample_with_sampling_plan,
)
```

实测后果（连上 AICG3D_H3SelfLiftStrategy 时）：

| | 修复前 | 修复后 |
|---|---|---|
| `SAMPLING_PLAN_TYPE` | `default`（假常量） | `MINIMAX_H3_SAMPLING_PLAN` |
| `SELFLIFT_KIND` | `none` | `selflift` |
| 采样计划对象字段 | `{}`（空壳） | `kind/cfg/transition_step/lowres_scale/...` 8 个字段 |
| `sample_with_sampling_plan()` | **返回 `None`** | 真实实现（来自 `h3easy.sampling_strategies`） |

**连上 SelfLift 的渲染节点会拿到 `None` 当 latent 往下传**，不是"效果弱"，而是执行到采样那一步直接出问题。换句话说：这个节点在面板上看得见、连得上，但一用就废。

### 🟠 P1-3：合并进来的 4 个 Goohai 节点，永远注册不上

`h3goohai/nodes.py` 用的是 ComfyUI 新式 V3 接口，靠文件末尾的 `comfy_entrypoint()` 暴露 4 个节点：
`MiniMaxH3IntegrationGH`、`MiniMaxH3IntegrationAdapterGH`、`MiniMaxH3DualClockT8GH`、`MiniMaxH3AVDecodeT8GH`。

但 ComfyUI 0.37 的加载器（`nodes.py:2293-2337`）**只检查被加载的那个顶层包**（即 `custom_nodes/comfyui-AICG3D/__init__.py`），而且顺序是：

```python
if hasattr(module, "NODE_CLASS_MAPPINGS") and ...:
    ...
    return True                      # ← 本插件走这里就返回了
elif hasattr(module, "comfy_entrypoint"):   # ← 永远到不了
```

本插件的 `__init__.py` 只导出 `NODE_CLASS_MAPPINGS`，`h3goohai` 是子包、谁也没 import 它的 `comfy_entrypoint`。实测：

```
B 结果：注册节点数 = 30
    Goohai 4 个 GH 节点是否注册： 一个都没有
    顶层是否暴露 comfy_entrypoint： False
```

连带后果：`web/minimax_h3_integration.js`（180 KB）配套的那 4 个节点的前端界面成了死代码；`branding.py` 里专门为它们写的配色分类也白写。
（注：Goohai 的**提示词优化能力**仍可用 —— `h3easy/nodes.py` 里动态 `from h3goohai import prompt_optimizer` 直接用到了；丢的是那 4 个独立节点。）

### 🟠 P1-4：自带示例工作流**不能直接用**（连它自己的当前版本都对不上）

`workflows/11.AICG3D_测试样板.json` 是仓库唯一的"综合样板"。我按它的参数原样提交给修复后的本机 ComfyUI，
**HTTP 400 直接被拒**，8 处校验失败：

```
node 1 (AICG3D_H3Loader)  ref2va_model: 'MiniMax/minimax_h3_fused_refdelta_r1024_turbo8_mystic07_int8_convrot.safetensors'
                                        not in (list of length 26)
node 1 (AICG3D_H3Loader)  fl2va_model:  'MiniMax/Minimax-h3_Singularity_ref2va_v1.3_int8.safetensors'
                                        not in (list of length 26)
node 1 (AICG3D_H3Loader)  lora_1:       'minimax\taomate_h3_3step_comfy.safetensors'（Windows 反斜杠）
                                        not in (list of length 30)
node 2 (MediaLoader)      Media Loader cannot find input file:
                          oMAEICyBGQF62YfOAlLAOI7ttFehVAJIIegFBW~noop.jpeg
node 3 (AICG3D_H3)        mode: '图生或首尾帧'                      not in ['image','reference','digital_human']
node 3 (AICG3D_H3)        keyframe_role: '首帧优先'                 not in ['first','last']
node 3 (AICG3D_H3)        ref_image_size: '1K 像素（1024×1024 等比）' not in ['match','1k','1.5k','2k','original']
node 3 (AICG3D_H3)        reference_mention_mode: '按序号'          not in ['filename','index']
node 3 (AICG3D_H3)        prompt_optimizer_scene_guide: '通用'      not in ['none','3d_animation_short',…]
```

两类原因：
1. **引用了作者自己的资产**：主模型、LoRA、输入图在本机都不存在（这正是 GitHub issue #5 报的那个错）。
2. **枚举值是中文、节点现在收英文**：`mode` / `keyframe_role` / `ref_image_size` / `reference_mention_mode` /
   `prompt_optimizer_scene_guide` 五个控件的值全是中文标签，而节点当前版本的合法值是英文 ——
   **样例工作流比插件自身旧了一个版本，作者没同步**。

**改完之后能不能跑？能。** 我把这 8 处换成我们机器的真实资源（并把 steps 3→4 对齐 4-step turbo LoRA）后重新提交：

```
HTTP 200 —— 已进入队列，prompt_id=73f9f21d-…
[410s] status=success completed=True
输出节点 5: {"images":[{"filename":"AICG3D_test_fixed_00001_.mp4","subfolder":"video","type":"output"}]}
```

产出 **1376×768 / 24fps / 5.17s / h264+aac / 1.1 MB** 的正常视频（第 60 帧见 `AICG3D测试成品-第60帧.png`），
采样 4 步、约 70 秒/步，含首次加载 20 GB int8 模型共约 6.8 分钟；成品已自动进相册并补写元数据。
适配版工作流：`11-AICG3D测试样板-本机适配版-20260927.json`（可直接拖进 ComfyUI 打开运行）。

> 结论：**插件本体修好后确实能出片**；但"自带工作流 = 拿来就用"在它这里不成立，必须自己重选模型/素材/枚举值。

### 🟡 P2-5 其它（不影响能否跑起来，但反映工程质量）

1. **文档与实际不符**：`RELEASE_NOTES.md` 列了 11 个示例工作流并逐个说明，实际 `workflows/` 只剩 3 个（09-25 的提交 "Strictly clean workflows: removed all except the two requested templates" 删掉了，README 没同步）；`pyproject.toml` 版本号还写 `1.0.2`，而最新 tag 是 `v1.1.0`。
2. **注释与代码矛盾**：`branding.py` 写"节点 ID 与显示名保持原样"，但 `registry.py` 现在是无条件加 `AICG3D_H3` 前缀（v1.1.0 里还是"没冲突才加"）。
3. **依赖没声明**：`requirements.txt` 是**空文件**。本地 GGUF 提示词优化需要 `llama-cpp-python` —— 本机**未安装**（实测 `ModuleNotFoundError: No module named 'llama_cpp'`），`ComfyUI/models/llm` 目录也是空的，所以"本地模式"开箱即用是**不可能**的（issue #1 就是这个：用户找不到模型该放哪）。云端模式要自备 API Key。
4. **会外发数据**：云端模式下提示词 + 被引用素材会发给 OpenAI/Gemini/OpenRouter/DashScope/硅基流动/RunningHub；另外 `prompt_optimizer.py` 会去查 `api.github.com` 的 llama-cpp-python release（本网 GitHub 直连不通，会走到超时失败）。
5. **开发残留**：仓库根目录留着 `fix_all_imports.py`、`debug_load_test.py` 这类一次性脚本。
6. **许可瑕疵**：`prompt_presets/` 144 个模板，仓库自己在 NOTICE 里写明"**未从任何权利人处取得明示授权**"；技能/提示词方案含 MiniMax 官方内容，受 H3 Community License 约束（有地域限制，中国大陆可用）。整合 MIT + GPL 代码后整包为 GPL-3.0-or-later。
7. **代码体量**：`h3easy/nodes.py` 单文件 **481 KB**；mock 块重复 3 次且带粘连残留 —— 典型的"AI 批量改文件"痕迹（09-25 那天 6 个提交全部署名 Codex Agent，其中一个搞崩仓库、一个删光工作流）。

---

## 四、对我们这套环境的具体影响

| 检查项 | 结果 |
|---|---|
| 会不会与现有插件撞名 | **不会**。新命名空间 `AICG3D_H3*`；实测 GPU 机 `custom_nodes/` 全库**没有任何 AICG3D 字符串** |
| ComfyUI 版本兼容 | **可以**。0.37.0 下修复后完整加载（依赖 `comfy_extras.nodes_minimax_h3`、`comfy_api.latest` 均满足） |
| 会不会再次引发 GPU 掉总线 | **不会**。全仓 grep：**不含任何 SageAttention 补丁节点**（当年元凶 `PathchSageAttentionKJ` / `MiniMaxH3MemoryEfficientSageAttentionPatch` 一个都没有） |
| 装完节点数 | 原版 30 个；补回 Goohai 后 34 个 |
| 装它会影响现有出片链路吗 | 不影响。它是**增量**节点包，不改 ComfyUI 核心；我们现在走的是官方 Director 工作流 + dasiwa V18，互不干扰 |
| 装之前要做什么 | ComfyUI **现在正在运行**（8189 返回 200）；装完需重启（GPU 机 `bash ~/restart_comfy.sh`）+ 浏览器 `Ctrl+F5` |
| 磁盘/依赖代价 | 仅 5.8 MB 代码；**不装任何 Python 包**（requirements 为空），不动模型 |

---

## 五、修复方案（已实机验证）

交付脚本：`apply_fixes.py`（本目录），用法：

```bash
# 1) 把插件放到 ComfyUI/custom_nodes/ 下（GitHub 直连不通时可用下载中心中转）
cd /home/zyw/ComfyUI/custom_nodes
git clone https://github.com/JGRFW/comfyui-AICG3D.git

# 2) 先试运行看报告，再正式修
python3 apply_fixes.py comfyui-AICG3D --dry-run
python3 apply_fixes.py comfyui-AICG3D            # 修 P0-1 + P0-2（必做）
python3 apply_fixes.py comfyui-AICG3D --with-gh  # 顺便补回 4 个 Goohai 节点（实验性）

# 3) 重启 ComfyUI + 浏览器 Ctrl+F5
```

修复脚本做三件事：
1. 把 `__init__.py` 里被提出 try 块的 5 行 `print` 收回原处（只影响打印，不动逻辑）；
2. 用正则删掉 **全部 3 处** mock 块（注意第二处尾部粘连了 `# ----audio`，普通字符串替换会漏，第一版脚本就漏过一次），换成指向真实 `h3easy.sampling_strategies` 的 import；
3. `--with-gh` 时往 `registry.py` 的 `build()` 注入 4 个 Goohai 节点的 `NODE_CLASS_MAPPINGS` 注册（绕开 ComfyUI 只认顶层 `comfy_entrypoint` 的限制）。

**实测前后对比（GPU 机真实加载）**

```
修复前：SyntaxError: expected 'except' or 'finally' block (__init__.py, line 21)

修复后：
  [1] __init__.py 修复 5 行缩进
  [2] 移除 3 处 mock，接入真实 sampling_strategies
  [3] 已在 registry.py 插入 Goohai 4 节点补注册
  语法检查：全部通过 ✔
  SAMPLING_PLAN_TYPE = MINIMAX_H3_SAMPLING_PLAN | SELFLIFT_KIND = selflift
  sample_with_sampling_plan 来自 = h3easy.sampling_strategies
  📦 Loaded 34 production-ready nodes
  GH 节点 = ['MiniMaxH3AVDecodeT8GH','MiniMaxH3DualClockT8GH','MiniMaxH3IntegrationAdapterGH','MiniMaxH3IntegrationGH']
```

**诚实标注两处局限**：
- `--with-gh` 只验证到"节点注册成功、`INPUT_TYPES` 齐全"；这 4 个 V3 节点走 V1 通道**真正执行**是否 100% 正常，还需要真跑一次工作流才算数。
- 修复脚本只解决我实测到的 3 个问题；`prompt_presets/` 的授权、文档不符等属于作者侧问题，脚本不动。

---

## 六、优点（值得肯定的部分）

- **加载器面板**：一个模型下拉 + LoRA 槽位 `− 1 +`（最多 9 个），LoRA 直接叠在 loader 内，不用再外挂 `LoraLoaderModelOnly`；旧工作流的 5 个 widget 顺序没动，不会串位。
- **素材引用体验**：缩略图单击即把 `@图片1` 写进提示词编辑器，配"素材库"面板。
- **技能库 / 模板库**：45 个技能方案 + 144 个模板（91 万字）收进一个面板，点选即用 —— 这部分对我们搞 H3 提示词确实省事。
- **节点合并**：`AICG-采样器（高级）` 把 `RandomNoise/BasicScheduler/KSamplerSelect/BasicGuider/SamplerCustomAdvanced` 五个节点合成一个；`AICG-渲染器（高级）` 单线出片，v1.1.0 还加了**实时预览 + 百分比进度条**（H3 采样好几分钟，这个很实用）。
- **来源标注诚实**：README 明说"骨架是 nkxx188 的、提示词引擎是 goohai 的，我们只是拼起来"，还附了逐文件修改清单和第三方许可原文。这比偷码不说来源强得多。
- **不引入 SageAttention 补丁**：对我们这台机器是实打实的加分项。

---

## 七、建议

**路线 A（推荐，若你想用它的面板/提示词库）**：克隆 → `apply_fixes.py` 修复 → 重启。预计 10 分钟，风险低；一旦不满意，删目录重启即可完全回退（它不写 ComfyUI 核心、不装依赖、不动模型）。

**路线 B（最稳）**：只要功能不要"整合"，直接装上游 —— `nkxx188/ComfyUI-MiniMaxH3-Easy`（⭐785，骨架正主）和 `goohai/Goohai-MiniMax-H3_Integration`（⭐196，那 4 个节点在这里是正常注册的）。代价是两套面板分别装、没有统一的技能/模板库。

**路线 C（不装）**：我们现有 H3 链路（官方 Director 工作流 + dasiwa V18 + FaceRefine + 相册归档）已经跑通，AICG3D 的价值集中在**外围便利**（提示词库、素材 @ 引用、单节点化），不改变出片质量本身。如果最近没有"批量做 H3 提示词"的需求，可以先放着。

**无论走哪条，都不要直接 `git clone` 完就用 main**（现在是坏的）；若不想自己打补丁，退到 commit `b376ea8` 或 tag `v1.1.0` 也能跑（但会缺后面的 PromptSplit 分段、无限段落顺序生成等特性，且 `AICG3D_H3*` 节点 ID 规则与 main 不同）。

---

## 八、安装记录（2026-09-27 已执行，修复版）

经确认后已在 GPU 机安装修复版（`/home/zyw/ComfyUI/custom_nodes/comfyui-AICG3D`，main 快照 + `apply_fixes.py --with-gh`）。
**未装任何 Python 包、未动模型**；GitHub 不可直连，改用下载中心经局域网中转。分两步重启验证：

| 步骤 | 结果 |
|---|---|
| 只打 P0-1 / P0-2 补丁 → 重启 | 启动日志 `📦 Loaded 30 nodes`，零报错；`/object_info` 30 个 AICG3D 节点；`/aicg3d/api/meta` → `skills 21 / presets 144 / prompt_guides 18 / loras 27`；前端 `aicg3d-core.js`、`minimax_h3_easy_ui.js` 均 200 |
| 再加 `--with-gh` → 重启 | `📦 Loaded 34 nodes`，4 个 GH 节点出现在 `/object_info`（分类 `AICG3D/H3 集成`，输入输出齐全），零报错 |
| 自带工作流依赖检查 | `11.测试样板` 依赖齐全；`13/15` 报缺 `Label (rgthree)`/`MarkdownNote` —— **误报**，这两个是前端虚拟节点，本就不在后端节点表里（本机已装 rgthree-comfy） |
| **端到端生成（补测）** | 自带工作流原样提交 → **400 拒绝（8 处）**；换成我们机器的资源后提交 → `execution_success`，产出 `output/video/AICG3D_test_fixed_00001_.mp4`（1376×768 / 24fps / 5.17s / 1.1 MB，4 步采样，含首次加载模型约 6.8 分钟），并已自动进相册 |

仍未做的验证：GH 那 4 个 V3 节点只验证到注册层面，`--with-gh` 的 V1 通道执行是否端到端正常未验证
（本次端到端跑的是主链路 `AICG3D_H3Loader → MediaLoader → AICG3D_H3 → RenderAdvanced → SaveVideo`，不含 GH 节点）。
回滚：`cp aicg3d/registry.py.bak-pre-gh aicg3d/registry.py` 或整目录删除后 `bash ~/restart_comfy.sh`。
完整记录见 `dl-hub/06-ComfyUI-H3运维记录/2026-09-27-comfyui-AICG3D插件安装记录.md`。

**使用前置动作**：浏览器 `Ctrl+F5` 强刷一次，节点搜索框输入 `AICG3D`。

---

## 九、附：本次评估的证据与脚本

| 文件 | 说明 |
|---|---|
| `apply_fixes.py` | 修复脚本（P0-1 `/` P0-2 `/` `--with-gh`），实机验证通过 |
| `11-AICG3D测试样板-本机适配版-20260927.json` | 自带样板改成"本机可直接跑"的版本（换 3 个资产 + 5 个中文枚举 + steps/seed） |
| `附件-实测脚本/aicg3d_run.py` | 端到端提交脚本：`original`（复现 400 拒绝）/ `fixed`（跑通出片） |
| `AICG3D测试成品-5.17s-1376x768.mp4` · `AICG3D测试成品-第60帧.png` | 修复版实际产出（相册里也有：http://192.168.31.76:8900 目录 `video/`） |
| `附件-实测脚本/aicg3d-probe.tgz` | 我打包的插件快照（`_init_broken.py.orig` 即 main 原版坏文件，可复现实验） |
| `附件-实测脚本/probe_load.py` | 第一轮探针：语法错误 + 节点清单 + GH 缺失 + SelfLift mock |
| `附件-实测脚本/verify_fixes.py` | 第二轮探针：就地修复并复验 |
| `附件-实测脚本/verify3.py` | 第三轮探针：修复后常量/节点数复验 |

外部参考：
- 仓库：<https://github.com/JGRFW/comfyui-AICG3D>
- 崩溃反馈（与本报告 P0-1 一致）：<https://github.com/JGRFW/comfyui-AICG3D/issues/6>
- 上游骨架：<https://github.com/nkxx188/ComfyUI-MiniMaxH3-Easy> · 上游集成：<https://github.com/goohai/Goohai-MiniMax-H3_Integration>