ComfyUI-OnePromptStoryboard 是一款专为 ComfyUI 环境设计的非官方辅助自定义节点。其核心功能是将单一的自然语言请求，转化为标准化的四镜头共享脚本，并据此分别生成 MOSS 的故事板图像指令与 MiniMax H3 Ref2VA 的视频生成指令。该仓库仅提供自定义节点代码，不包含模型权重、外部节点或 Python 依赖的自动安装程序。
- GitHub：https://github.com/sepiablue-ai/ComfyUI-OnePromptStoryboard
核心节点功能概述
该工具包注册了四个主要节点，协同完成从文本规划到指令输出的流程：
- StoryboardPromptPlanner（脚本规划器）：接收用户请求，利用兼容的本地文本生成 CLIP（标准示例使用 Qwen3.5，可选支持 Gemma4）创建共享脚本。输出包含 MOSS 指令、H3 指令、脚本 JSON 以及行列数配置。
- StoryboardPromptText（提示词编辑器）：允许用户在不依赖模型的情况下，手动编辑并输出 H3 提示词。
- StoryboardPlanCompile（计划编译器）：支持从已保存的脚本 JSON 文件中恢复两个模型的指令，避免重复运行 LLM 消耗算力。
- StoryboardOptionalLora（可选 LoRA 管理器）：用于添加可选的 MOSS LoRA 及其触发词。默认处于禁用状态，用户可复制并链接该节点槽位以扩展数量。
规划器底层调用 ComfyUI 内置的 comfy_extras.nodes_textgen.TextGenerate。需确保当前 ComfyUI 版本原生支持 MOSS/H3 及 TextGenerate API，旧版本可能需要进行升级。
环境配置与安装步骤
正确部署节点及其依赖环境是工作流正常运行的前提。请严格按以下步骤执行。
1. 节点安装
在 ComfyUI 的 custom_nodes 目录下执行以下命令，随后重启 ComfyUI 服务：
cd ComfyUI/custom_nodes
git clone https://github.com/sepiablue-ai/ComfyUI-OnePromptStoryboard.git
替代方案：也可下载仓库 ZIP 压缩包，直接解压至 custom_nodes/ComfyUI-OnePromptStoryboard。确保 __init__.py 位于该文件夹根目录。此节点注册无需额外的 pip 依赖。
2. 前置环境与外部依赖要求
若要运行一体化示例，需自行安装并配置以下组件（需遵循各项目的许可协议）：
- ComfyUI 核心：需包含对 MOSS、MiniMax H3、Ref2VA、BlockSparseAttention 和 TextGenerate 的支持。
- ComfyUI-MOSS-Storyboard：提供
MossStoryboardSampler和MossStoryboardLayout节点。 - ComfyUI-FastH3-OmniRef-Accel：提供 H3 加速、LBH（Latent Block-wise Hierarchical）支持及示例中的视频保存功能。需查阅该仓库了解 LBH 潜在放大器等具体要求。
- 视频编码环境：需具备 NVIDIA NVENC 能力，并安装 FFmpeg 及 FastH3 所需的其他系统级依赖。
- 注：若仅运行 H3 示例，则无需安装 MOSS 及其相关模型。提示词编辑节点本身不依赖 Qwen，但 H3 工作流仍需配置其专属的文本编码器。
模型权重部署与精度校验
请严格按照以下路径存放模型权重，并使用原始分发文件名。若存放于子文件夹，需手动更新工作流中的模型选择路径。
| 文件名称 | ComfyUI 存放路径 | 备注说明 |
|---|---|---|
moss_image_sft_int8_convrot.safetensors | models/diffusion_models | MOSS SFT INT8 模型 |
lora.safetensors | models/loras | SFT 的 8 步 DMD 蒸馏 LoRA（来自 lodestones） |
qwen3.5_9b_int8_convrot.safetensors | models/text_encoders | 标准示例使用的文本编码器 |
flux2-vae.safetensors | models/vae | MOSS 兼容 VAE |
fasth3_omniref_8step_pruned_int8_convrot.safetensors | models/diffusion_models | FastH3 扩散模型 |
qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors | models/text_encoders | H3 文本编码器 |
minimax_h3_video_vae_int8_convrot.safetensors | models/vae | H3 视频 VAE |
minimax_h3_audio_vae_fp32.safetensors | models/vae | H3 音频 VAE |
minimax_h3_latent_upscaler_3d_conv_v1_fp16.safetensors | models/latent_upscale_models | LBH 潜在放大器（需保持原名） |
realesr-animevideov3.pth | models/upscale_models | 视频超分模型 |
文件验证与精度说明：
2026-10-26 的测试中，权重文件已通过分发源的 LFS SHA-256 哈希校验（例如 SFT DMD lora 哈希为 4abb14e...，LBH upscaler 哈希为 043e5a4...）。
当前官方模型卡建议使用标准 ComfyUI LoRA 加载器以强度 1.0 应用 lora.safetensors。早期弃用的方法要求 FP32 加载以规避 BF16 舍入误差，但本仓库示例采用 INT8 基础模型并单独应用 LoRA。此配置的质量未与分发商的 FP32 配置进行直接对比，精度和应用方法的差异可能影响最终输出质量。
工作流操作指南
1. 从单一请求生成全流程
以 workflows/all_in_one_magic_battle.json（标准示例，使用共享 Qwen 编码器）为例：
- 输入请求：在标记为“作りたい動画をここに1つ入力”（在此输入你想制作的视频）的节点中编辑故事请求。
- 配置布局：选择“横一列4コマ”（四格横排）或“縦一列4コマ”（四格竖排），并核对所选模型路径。
- 执行生成：运行工作流。数据流向为：处理请求 → 生成共享脚本 → MOSS 生成静态图像 → 将该单张图像作为参考输入 H3 → 保存最终视频。
- 结果保存：若结果符合预期，需手动将预览区生成的 H3 提示词（生成されたH3プロンプト）和共享脚本（自動生成した共通台本・確認用）复制并保存至本地文本文件。当前节点未实现脚本和提示词的自动持久化保存。
注：工作流固定设计为四个镜头，时长约 14 秒，不支持任意数量的镜头配置。包含的示例涵盖魔法少女战斗、男孩遇见女孩及浪漫电影题材。
2. 系统提示与可选 LoRA 配置
- 系统提示：编辑请求节点中的
system_prompt字段可调整脚本的导演策略。对于常规使用，直接输入故事即可，节点会自动附加所需的四镜头 JSON 格式指令。 - 可选 LoRA：该区域包含三个默认禁用的槽位。若要启用，需选择兼容的 MOSS LoRA，设置
strength_model和trigger_words，并将enabled设为开启。触发词将直接追加至 MOSS 提示词中，不影响 H3 提示词。禁用状态下不加载额外 LoRA。如需更多槽位，可复制节点并链接其 MODEL 和 STRING 输出。8 步生成所需的 SFT DMD LoRA 保持默认启用，需单独安装。
3. 保留故事板并仅重新生成 H3 视频
若需基于已生成的静态故事板重新渲染视频，加载 workflows/h3_from_saved_storyboard.json：
- 在“保存済みストーリーボードを1枚選択”节点中加载目标图像（如
storyboard.png）。 - 在“H3プロンプトを編集・元の指示をここへコピー”节点中，粘贴随该图像保存的原始 H3 提示词。若更换图像，需同步替换提示词内容。
- 保持面板顺序及角色/服装对应关系，可微调动作、相机运镜或声音描述。若使用垂直四格布局，需确保指令顺序与从上到下的面板顺序匹配。
- 运行工作流。此流程断开与 MOSS 及脚本生成的连接，仅执行 H3 视频生成。
备选方案：若仅保存了脚本 JSON，可将其粘贴至StoryboardPlanCompile节点并选择原始布局以恢复 H3 指令，预览后复制到编辑字段进行修改，无需重新生成脚本。
运行机制与技术限制
为保证客观评估，需明确该工具的数据流向与工程边界：
- 信息隔离机制：Qwen 文本编码器无法看到生成的图像。共享脚本分别向 MOSS 发送静态图像构图指令，向 H3 发送包含运动和相机工作的视频指令。
- 固定模板约束：固定模板会告知 H3，参考图像 1 包含四个面板，分别对应镜头 1 至 4，且应扩展为无边框的全帧视频。完整 MOSS 图像的输出 0 作为单张参考图像直接连接至 Ref2VA，面板不会为 FL2VA 拆分。
- 错误处理缺失：若 MOSS 生成的面板数量错误或内容发生偏移，系统没有自动检测或纠正机制。节点不具备分析任意图像布局或自动读取图像内文本描述的能力。无效的脚本 JSON 或少于四个镜头的输入将直接导致错误并终止执行。
- 音频与后期限制：BGM 输出字段目前固定为 N/A，请求中的音乐描述不会传递给 H3。MOSS 生成时使用
reborder=false，禁用生成后的边框重绘。本仓库不包含图像修复或视频合成逻辑，H3 示例依赖 FastH3 的 LBH 潜在放大、Real-ESRGAN、尺寸调整、中心裁剪及 NVENC 保存流程。
性能验证与测试数据
2026-10-27 的标准化验证测试数据如下：
- 全流程测试：使用共享 Qwen 编码器、所有可选 LoRA 禁用、默认系统提示和固定种子运行
all_in_one示例。工作流在 203.80 秒内成功保存故事板图像与最终视频。 - 独立 H3 测试：在仅更改图像选择和匹配的生成 H3 提示词后，保存图像 H3 示例在 173.04 秒内成功执行。
- 输出规格：两个测试生成的视频均为 1024×1792 分辨率，24 fps，持续时长 14.375 秒。所有 345 个视频帧和 450 个音频帧均解码成功，且视频文件具有相同的 SHA-256 哈希值。
- 代码级验证：16 个单元测试和前端命名控件恢复测试在全新克隆环境中全部通过。测试通过 API 执行生成，并进行 GUI 连接和命名值静态比较，无需额外模型即可运行（命令：
python -m unittest discover -p "test_*.py" -v）。
注：成功执行代码逻辑不保证绝对的视觉质量，也不代表支持所有非标准的硬件或软件环境配置。
© 版权声明
文章版权归作者所有，未经允许请勿转载。
