ComfyUI-Henjicc

ComfyUI-Henjicc · 痕继痕迹

面向 ComfyUI 图片、视频和音频工作流的自定义节点包。把素材选择、提示词引用、参考图处理和尺寸设置集中起来，配合原生节点完成生成与编辑。

简明安装指南 · 安装 · 快速开始 · 节点一览 · 常见问题 · 问题反馈

主要功能

• 一个面板管理多种素材：上传、粘贴、拖放或从资源库选择图片、视频与音频，在提示词中引用具体素材。
• 多图参考与尺寸控制：按每张图的比例和像素预算处理参考图，将图片列表分配到独立接口，用尺寸画板设置输出宽高。
• 本地资源库：浏览 ComfyUI 的 input、output、temp，搜索文件与标签，评分、批量标记并预览音视频；也可从原生 LoadImage 打开。
• 提示词助手：使用本地 Qwen3-VL 或 Qwen2.5-Omni 理解素材、整理描述和改写提示词。
• MiniMax H3 与音频辅助：准备参考素材、首尾帧和角色替换输入，同步裁切生成音画，混合人声与伴奏。

界面和节点名称跟随 ComfyUI 的中文 / 英文设置，分类显示为“痕继痕迹”或“Henjicc”。

环境要求

| 项目 | 要求 | | --- | --- | | Python | 基础节点要求 3.10 或更高版本，见 依赖声明 | | ComfyUI | 需提供 V3 节点接口 comfy_api.latest；模型适配功能还需对应的原生节点 | | 基础依赖 | aiohttp、av、numpy、Pillow | | PyTorch / torchaudio | 由 ComfyUI 环境提供；音频功能需要与 PyTorch 匹配的 torchaudio | | 前端 | 直接使用 ComfyUI 扩展机制，无需 npm 安装或前端构建 | | 模型与算力 | 按实际使用的生成模型或提示词助手准备；素材整理、参考图处理和尺寸计算不需要加载生成模型 |

本包未声明覆盖所有系统、架构和 ComfyUI 版本。Qwen2.5-Omni 等可选功能还须满足其依赖包的 Python 要求。

安装

通过 Manager 安装

将分享的工作流 .json 拖入 ComfyUI，或通过菜单打开。若提示缺少本包节点，打开 Manager → 安装缺失节点（Install Missing Custom Nodes），找到本包后安装；也可以在 Manager 的自定义节点列表搜索 comfyui-henjicc 或 Henjicc。

安装完成后重启 ComfyUI、刷新网页，再打开工作流。Registry 节点页可查看发布版本。版本待审核（Pending）、需复核（Flagged）、目录同步或节点识别尚未完成时，可能暂时搜不到或无法通过 Manager 安装；请先查看 Registry 状态，也可使用下面的手动安装方法。工作流所用的其他节点和模型需另外准备。

手动安装

1. 放入自定义节点目录

在 ComfyUI 根目录执行：

git clone https://github.com/henjicc/ComfyUI-Henjicc.git custom_nodes/ComfyUI-Henjicc

也可以下载仓库 ZIP，解压后将目录命名为 ComfyUI-Henjicc，放入 ComfyUI/custom_nodes/。最终应能找到：

ComfyUI/
└── custom_nodes/
    └── ComfyUI-Henjicc/
        ├── __init__.py
        ├── pyproject.toml
        └── web/

已有同名目录时先确认它是否为当前安装，避免嵌套解压或安装两份。

2. 安装基础依赖

先激活 运行 ComfyUI 的 Python 环境，再执行：

python -m pip install aiohttp av numpy Pillow

这些是当前 pyproject.toml 中的基础依赖。若使用便携版或独立解释器，请将 python 替换为 ComfyUI 实际使用的 Python 路径，不要装进系统里的另一个环境。本包放入 custom_nodes 后由 ComfyUI 加载，无需额外执行 pip install .。

使用 Qwen2.5-Omni 助手时，另外准备 omni 可选依赖组及完整本地模型，详见下文。其他节点不需要为此安装 Omni 模型。

3. 重启并确认加载

重启 ComfyUI，然后刷新浏览器。在节点库中搜索 Henjicc，应能看到“超级输入”“参考图处理”“尺寸画板”等节点。原生 LoadImage 也会出现“资源库”入口。

模型与权重不随本包分发，节点注册不会自动下载模型。安装本包不需要替换 ComfyUI 的 Python、PyTorch 或 CUDA 环境。

快速开始

先完成一次不加载模型的图片处理

1. 在空白工作流中添加“超级输入”“参考图处理”和原生“预览图像”（PreviewImage）。

2. 在“超级输入”中上传一张图片。

3. 按下面的接口连接：

   超级输入［素材］ → ［素材］参考图处理
   参考图处理［图片组］ → ［images］预览图像
   

4. 将“每张参考图百万像素”设为 1、对齐倍数设为 32，点击运行。

5. 预览节点应显示处理后的图片。图片保持原始比例，并按像素预算和对齐规则调整尺寸；这一步不会运行图像生成模型。

要处理多张图片，继续在同一个“超级输入”面板中添加素材即可，无需为每张图新建输入节点。

接入已有生成工作流

• 千问图片：将处理后的图片组接到“图片组分配”，再接原生千问编码器的参考图接口；将“参考图处理”的提示词和自动文生图模式用于对应的文本、模式分支。
• 尺寸设置：将“尺寸画板”的宽度、高度接到工作流的画布或生成节点。“超级输入”的预设尺寸也可以接到尺寸画板。
• MiniMax H3：将素材接到本包对应的 H3 适配节点，并准备宿主原生 H3 节点所需的模型、编码器及 VAE。

这些节点负责素材和参数适配，模型加载、采样与最终保存由已有工作流完成。仓库不附带个人工作流、素材或模型权重。

节点一览

| 节点 | 内部 ID | 用途 | | --- | --- | --- | | 超级输入 | HenjiccSuperLoader | 聚合图片、视频、音频、提示词和预设尺寸 | | 参考图处理 | HenjiccQwenReferenceList | 输出有序 IMAGE 列表、首张原图、提示词及自动文生图模式 | | 图片组分配 | HenjiccImageListToSlots | 聚合 IMAGE 列表或 batch，分配至十个独立 IMAGE 接口 | | 尺寸画板 | HenjiccResolutionBoard | 根据预设、参考图或手动设置计算宽高 | | MiniMax H3 素材适配 | HenjiccMiniMaxMedia | 为原生 H3 参考生视频、首尾帧生成准备条件 | | MiniMax H3 角色替换素材 | HenjiccH3RoleInputs | 准备角色图片、参考视频时序和模型帧数 | | MiniMax H3 成片时序 | HenjiccH3VideoOutput | 按原生 24 fps 同步裁切生成画面与音轨，输出 VIDEO | | Qwen3-VL 提示词优化助手 | HenjiccVisualPrompt | 理解图片或视频抽帧拼图，输出文本、图片列表和更新提示词后的素材 | | Qwen2.5-Omni 多模态提示词助手 | HenjiccOmniPrompt | 联合理解图片、视频、音频，输出文本 | | 人声与伴奏混音 | HenjiccAudioMix | 调整两路增益、人声偏移及峰值，按伴奏长度混音 |

注册清单以 扩展入口 为准。中文显示名可以变化，内部 ID 用于工作流兼容。

使用要点

超级输入与素材引用

在提示词中输入 @ 或点击素材编号可插入引用，也支持 图片1、<image1>、<image_1> 等手写标签。拖动或按 Alt + 方向键可以调整素材顺序；稳定引用随素材移动，不会因排序指向另一张图。

移除素材只解除引用，不删除磁盘原文件。删除了仍被提示词引用的素材后，需要移除或替换该引用才能运行。视频原声默认关闭，开启后才参与音频引用；没有音轨的视频会明确报错。

模式根据实际下游连接识别：只接通用参考图处理时保持通用模式，连接千问、Fibo 2.0 编码器或 MiniMax 适配时切换到对应模式。MiniMax 的参考 / 首尾帧任务仍需显式选择；同一个输入同时连接不同模型会报错。

提示词预设可包含尺寸，不保存模型、种子或采样参数。自定义预设随节点属性保存；清除预设会解除尺寸绑定，保留素材与提示词。

资源库与文件操作

资源库支持文件名 / 标签搜索、排序、评分、批量标签及音视频预览。显示文件名、缩略图、悬停播放和单击使用等行为可在“设置 → 痕继痕迹 → 资源库”调整。原生 LoadImage 的资源库增强也可关闭，恢复原生选择控件；其 IMAGE / MASK 输出不变。

| 操作 | 对磁盘文件的影响 | | --- | --- | | 上传到 input | 保存新素材，不覆盖同名文件 | | 在超级输入中移除素材 | 只移除引用，保留原文件 | | 选用 output / temp 中的素材 | 复制到 input 的 henjicc/imports，保留源文件 | | 在资源库删除 input 素材 | 确认后永久删除原文件 | | 浏览 output / temp | 只读，不提供源文件删除 |

评分、标签按来源分别保存在当前 ComfyUI 用户目录的 henjicc/image-library*.sqlite3，音频波形缓存位于 henjicc/cache/waveforms；移动文件不会自动迁移元数据。

资源接口限制来源和文件路径，但这些限制不代替账户鉴权。是否允许其他设备访问，由 ComfyUI 的部署设置决定。

多图与尺寸

参考图按每张图独立处理，保留比例和顺序。参考图像素预算与输出画布尺寸分别设置；尺寸画板支持手动尺寸、参考图比例、锁定比例、横竖交换、常见比例和尺寸对齐。

IMAGE 列表与 IMAGE batch 的执行语义不同。要让多张图共同参与一次生成，应通过“图片组分配”接到编码器的独立参考槽，避免意外变成逐图生成。分配器提供 16 个独立槽；千问仍按模型约定限制为 10 张。HENJICC_MEDIA 是本包素材类型，不能直接接普通 IMAGE 输入。

本地提示词助手

| 助手 | 输入与模型要求 | 使用边界 | | --- | --- | --- | | Qwen3-VL | 宿主 CLIP 加载器提供的完整 Qwen3-VL；可共享兼容的千问图片编码器 | 忽略音频和视频原声；按时间戳抽帧、分段拼图并控制总像素预算，不是原生视频时序推理 | | Qwen2.5-Omni | 完整本地 Qwen2.5-Omni-3B 或 Qwen2.5-Omni-7B，以及 omni 可选依赖组 | 使用 BF16 和 Transformers SDPA，分析音视频开头 1–15 秒；不自动下载模型 |

Omni 模型放在宿主模型根目录下的 LLM/Qwen2.5-Omni-3B/ 或 LLM/Qwen2.5-Omni-7B/，需要包含分片权重、配置及 spk_dict.pt 等完整文件。可选依赖见 pyproject.toml。

Qwen3-VL 的文本生成需要完整语言模型；缺少输出头的专用条件编码器不能直接用作提示词助手。助手输出仍需人工核对，自动任务根据下游连接解析，自定义任务需填写要求。

已知限制

• 通用素材面板最多 24 项，单文件最多 512 MiB；素材状态序列化上限为 1 MiB。
• 千问素材链路仅接受图片，最多十张；这是本包链路的限制，不代表所有千问模型的统一上限。
• MiniMax 参考链路最多九图、三视频、三独立音频，合计十二项；首尾帧模式支持零至两张图片。
• 视频、音频还受具体适配节点的解码、时长及像素预算约束；输出按 H3 原生 24 fps 处理。
• 人声与伴奏混音不会自动对齐拍点、改变旋律速度、分离人声或转换音色。这些能力需要对应的原生或第三方节点。

常见问题

安装后找不到节点？

先查看 ComfyUI 启动日志，确认本包没有导入失败，且依赖安装在宿主实际使用的 Python 中。若缺少 comfy_api.latest，说明宿主不提供所需 V3 接口。后端加载成功后，再刷新浏览器节点库。

节点存在，但没有资源库或自定义控件？

确认没有安装两份同名扩展，刷新页面，并检查资源库增强是否关闭。前端脚本无需构建；仅修改前端时先刷新页面，Python 或翻译文件变化后需要重启宿主。

能看到模型名称，为什么运行仍然失败？

节点注册、模型枚举和真实推理是不同步骤。检查模型是否完整、编码器类型是否匹配，以及宿主和可选依赖是否兼容；提示词助手尤其需要支持文本生成的完整模型。

开发与贡献

Python 按职责组织在 image/、media/、video/、audio/、text/；共享资源服务位于 library/，前端和翻译位于 web/、locales/。入口显式注册节点，不扫描目录自动注册。

修改前阅读 AGENTS.md 和 项目上下文。依赖只在 pyproject.toml 中维护；测试使用合成数据，不提交个人工作流、素材、模型、生成历史或凭据。

在本仓库根目录运行后端测试前，将实际 ComfyUI 根目录加入 PYTHONPATH，并使用宿主的 Python 环境。下面是 PowerShell 示例，先把第一行路径替换为你的宿主根目录：

$env:PYTHONPATH = 'C:\path\to\ComfyUI'
python -m unittest discover -s tests -v

前端回归测试使用 Node.js，在同一目录执行：

node --test tests/*.test.mjs

发布更新

发布由 GitHub Actions 执行，使用仓库的 Actions secret REGISTRY_ACCESS_TOKEN；密钥不写入代码。首次配置或密钥失效时，维护者需将 Registry 发布密钥保存至 GitHub 仓库的 Settings → Secrets and variables → Actions。

准备发布时，更新 pyproject.toml 中的 version（如 0.1.1 → 0.1.2），在 更新记录 添加对应版本说明，再推送到 main。只有版本号变化才自动上传；普通代码、文档或其他元数据改动不会上传。可在 Actions 手动运行以重试，已上传的版本会跳过。上传成功后仍需等待 Registry 审核及 Manager 目录同步。

问题反馈

请在 GitHub Issues 提交问题。提供 ComfyUI、Python、PyTorch 版本，相关节点名称、复现步骤和脱敏后的错误日志；能复现问题的最小工作流比整套日常工作流更方便排查。

分享工作流前检查提示词、素材名称和预设中是否含有不想公开的内容，不要上传账号凭据或私有素材。

许可证

本项目采用 MIT 许可证，允许使用、修改和商用，分发时需保留版权及许可声明。