Extensions/MOSS Storyboard
ComfyUI Extension

MOSS Storyboard

Storyboard grid nodes for MOSS-Image: 3, 4, 6, 8 or 9 panels in one generation, with per-panel layout control and exact panel crops.

By ZenHG·Created a day ago·Updated a day ago· 2
ZenHG/ComfyUI-MOSS-Storyboard
Nodes—
On cloudLocal install
Stars2
Updateda day ago
Readme

ComfyUI-MOSS-Storyboard

🌐 中文 · English (condensed)

给 MOSS-Image 用的故事板宫格节点包：跑一次，得到一张图，图里整齐分成 3、4、6、8 或 9 格，同时把每一格单独裁出来。

「故事板」也常被叫作分镜图、宫格图、漫画格。本包做的是同一件事。

| 项 | 值 | |---|---| | 版本 | 0.1.2 | | 许可 | MIT（第三方出处见 THIRD-PARTY-NOTICES.md） | | 宿主 | ComfyUI ≥ 0.42.0（MOSS-Image 原生支持自 PR #17095 起） | | 依赖 | 零额外 pip 依赖（torch / comfy* 由宿主提供） |

先看这三条，能省掉大多数误解

  1. 不是生成 n 张图再拼起来。 是一次生成一张画布，画布内部被分成 n 格。 所以格数越多，每格分到的像素越少（8 格时每格约 496×272）。
  2. 宫格线不是模型画的。 采样解码之后，节点按同一份坐标重画一遍线和缝—— 线宽、位置 100% 确定，不会歪也不会断。
  3. 每格画什么，靠 MOSS 自己的「布局能力」。 节点把每格描述转成 MOSS 原生的 JSON 布局框（告诉模型"第 3 格这个区域画特写"）。这项能力官方标为 experimental， 不保证每格都严格照办。这也是本包唯一没做量化评测的地方。

核心功能

| 能力 | 说明 | |---|---| | 3 / 4 / 6 / 8 / 9 格 | 格数是输入（panels），排法与画布尺寸自动算，宽高全部对齐 16 | | 每格单独描述 | 提示词里按 [PANEL 1]…[PANEL n] 分段，自动转成 MOSS 原生布局框 | | 宫格线确定 | 解码后按坐标重绘，白缝位置与生成时一致 | | 逐格裁切 | 行优先输出，与整图画布逐像素对齐；spec 一根线传完几何，下游不会错位 | | 中英双语界面 | 每个本包节点上有「中 / EN」按钮，只改显示、不改存档 | | 零 GPU 机检 | 8 套自动断言（见 CONTRIBUTING.md） |

三个节点。最小工作流只需要「生成」一个 —— 它自带全套几何参数。 「宫格几何」是可选的前置：用来先看宫格形状，或把几何固化成一根 spec 传给多个下游。

| 节点（中文界面显示） | 代码名 | 必需？ | 作用 | |---|---|---|---| | 🎬 故事板 · 生成 | MossStoryboardSampler | 必需 | 模型 + 文本编码器 + VAE + 正面提示词 → 整图 + 逐格。没接 spec 时用自己的格数参数算几何 | | 🎬 故事板 · 宫格几何 | MossStoryboardLayout | 可选（推荐） | 算尺寸和每格坐标，出布局提示词与宫格模板图。不加载模型，秒出 | | 🎬 故事板 · 裁格 | MossStoryboardCrop | 可选 | 只裁格。接 spec 就与生成时逐像素一致，也能切已有的宫格图 |

节点名在英文界面下是 MOSS Storyboard Layout / Sampler / Crop。 接了 spec 就以 spec 为准，「生成」节点上的格数等几何参数会被忽略——这是最常踩的坑。

环境依赖

| 依赖 | 必需 | 放哪 | |---|---|---| | ComfyUI ≥ 0.42.0 | ✅ | 更低版本没有 moss_image 这个文本编码器类型 | | moss_image_sft_bf16.safetensors | ✅ | models/unet/（或 models/diffusion_models/） | | qwen3.5_9b_int8_convrot.safetensors | ✅ | models/clip/ | | flux2-vae.safetensors | ✅ | models/vae/ | | 额外 pip 包 | ❌ | 无 |

模型权重不随包分发。可选的 4 步蒸馏 LoRA 也不是本包的一部分： 交付工作流里预置了 LoraLoaderModelOnly 节点但默认旁路，没装不影响跑， 装了就选中它按 Ctrl+B 取消旁路。

安装

cd <你的 ComfyUI>/custom_nodes
git clone https://github.com/ZenHG/ComfyUI-MOSS-Storyboard

重启 ComfyUI。节点菜单 moss/storyboard 下出现三个节点，启动日志里有一行：

[MOSS SB] v0.1.0 已加载｜节点 3 个（出口 v3）｜3/4/6/8/9 宫格

没这行 = 包没加载，这比任何配置检查都直接。 要退回旧的 V1 接口：设环境变量 MOSSSB_NODE_API=v1。

5 分钟跑通

① 接线

| 节点 | 填什么 | |---|---| | UNETLoader | moss_image_sft_bf16.safetensors | | CLIPLoader | qwen3.5_9b_int8_convrot.safetensors，type 必须选 moss_image | | VAELoader | flux2-vae.safetensors |

② 选格数：在「🎬 故事板 · 生成」上改 格数（panels）。出厂默认 8， 仓库里那份示例工作流设成了 4。画布尺寸会自动算——不用手填宽高。

想先确认宫格形状对不对，再在「🎬 故事板 · 宫格几何」上连一根 spec 过来： 它的 template 输出是一张预览图，看得见每格在哪、缝多宽。

③ 写提示词：填在「🎬 故事板 · 生成」的 正面提示词（positive）里：

雨夜咖啡店，单一画布分成严格对称的 4 格，细白线分隔；
苏晚：黑发低马尾、米白高领针织衫；陈屿：深灰外套、黑衬衫；
35mm 胶片、真实演员、自然皮肤纹理、浅景深

[PANEL 1]: 中景，两人对坐，她把柠檬水杯推向正中
[PANEL 2]: 特写，她的眼睫与玻璃雨痕
[PANEL 3]: 过肩，他抬眼看向窗外
[PANEL 4]: 桌面特写，两只手停在杯沿

④ 跑。输出端两路：grid（整张宫格）+ panels（逐格，数量 = 格数）。

也可以直接用现成工作流：examples/moss-storyboard-4panels-ui.json，拖进 ComfyUI 即可 （已分好组、带画布内说明）。

提示词怎么写

规则只有三条

  1. 第一个 [PANEL …] 之前的内容，全部算全局描述（角色长相、场景、画风、相机）。 写不写 [STYLE]: 都行——它只是个便于阅读的标签，程序按位置算。
  2. [PANEL n] 后面跟这一格的描述：景别 + 主体 + 动作。
  3. 编号不必连续，也不必从 1 开始；真正决定顺序的是出现的先后（行优先：先左到右，再上到下）。

合法的写法都长这样

| 你写的 | 结果 | |---|---| | [PANEL 1]: … [PANEL 2]: … | 2 段描述 → 前 2 格有描述 | | [画面 1]: … [分镜 1]: … | 一样有效（中英文标记都认） | | 不写任何 [PANEL] | 整段当普通提示词，不生成布局框（等于纯文生图，report 会告诉你） | | 8 格只写了 4 段 | 前 4 格有描述，后 4 格没有（不是报错） | | 一格写了好几行 | 合并成一段，不影响 |

两条经验

  • 角色在不同格里不一致，先改全局描述那一段——它的权重最大。
  • 一格只写一个镜头。写"中景 + 特写"这种复合描述，模型会自己挑一个。

格数 → 画布尺寸

下表是单格 16:9、单格长边 496、缝 8、外边距 8（交付工作流的 1024 档）：

| 格数 | 排列形状 | 画布 | 百万像素 | 每格大小 | |---|---|---|---|---| | 3 | 竖条（上下 3 格） | 512 × 848 | 0.43 | 496 × 272 | | 4 | 田字（2 × 2） | 1024 × 576 | 0.59 | 496 × 272 | | 6 | 横条（上 2 行、每行 3 格） | 1520 × 576 | 0.88 | 496 × 272 | | 8 | 横条（上 2 行、每行 4 格） | 2032 × 576 | 1.17 | 496 × 272 | | 9 | 九宫格（3 × 3） | 1520 × 848 | 1.29 | 496 × 272 |

以上全部落在 MOSS 的 1–2 百万像素训练区间内。

换成竖构图（单格 9:16）：整体转 90°——3 格变横条（848 × 512），6 格变 2 列 × 3 行（576 × 1520）， 8 格变 2 列 × 4 行（576 × 2032），4 格与 9 格不变。

三个可调项

| 想改什么 | 调哪个 | 说明 | |---|---|---| | 每格大一点 | 单格长边（panel_edge） | 128–2048，步进 16。画布自动跟着变，不用手算 | | 强行换排法 | 列数（columns） | 填想要的列数，行数（rows）留 0 自动补齐；两者相乘必须等于格数 | | 只要横排 3 格 | 列数 = 3 | 3 格默认是竖条：横排 3 个 16:9 会让画布变成 1520 × 288（约 5.3:1），超出包内 4:1 的容忍线 |

为什么尺寸都能被 16 整除：MOSS 的 VAE 把图缩小 16 倍，宽高不是 16 的倍数就会错位。 节点自动对齐；多出来的 0–15 像素只加在右边和下边的外边距（和宫格线同色，看不出来）， 绝不改动单格尺寸——否则每格坐标会漂。

节点与参数

🎬 故事板 · 宫格几何（MossStoryboardLayout，不加载模型）

输出：width height columns rows spec layout_json template report

| 参数 | 说明 | |---|---| | 格数 panels | 3 / 4 / 6 / 8 / 9（也接受 1，见常见问题） | | 单格比例 panel_aspect | 10 种：16:9 3:2 4:3 1:1 4:5 3:4 2:3 9:16 21:9 2.39:1 | | 单格长边 panel_edge | 每格长边像素，默认 512 | | 缝宽 gutter / 外边距 margin | 宫格线宽度 / 画布到第一格的距离 | | 提示词 prompt | 留空是对的：这个节点只算尺寸。填了也只是给 layout_json 用 |

三个输出值得单独说：

  • spec：一串文字，把格数、画布、每格坐标全带上（MOSS-SB1 panels=4 w=1024 h=576 cols=2 …）。 接给下游节点，就绝不会和生成时错位。
  • layout_json：和宿主原生 MOSS-Image Layout Prompt 同格式， 可以直接接 CLIPTextEncode，也可以和 Create Bounding Boxes 混用。
  • report：给人看的一行总结——格数、画布、像素数、提示词对齐了几段、有没有超像素警告。

🎬 故事板 · 生成（MossStoryboardSampler）

输出：grid（整图）panels（逐格）latent spec prompt_used report

下表是节点的出厂默认值。仓库里那份交付工作流已经调好了 4 格 / 4 步 / 单格长边 496， 照它跑不用逐项改。

| 参数 | 出厂默认 | 说明 | |---|---|---| | 正面提示词 positive | 空 | 故事板稿，写法见上一节 | | 格数 panels | 8 | 没接 spec 时生效 | | 单格比例 panel_aspect | 16:9 | 没接 spec 时生效（10 种比例可选） | | 单格长边 panel_edge | 512 | 没接 spec 时生效 | | 画布比例 canvas_aspect | auto | 没接 spec 时生效：auto 会挑最接近的排法 | | 缝宽 gutter / 外边距 margin | 8 / 8 | 没接 spec 时生效 | | 步数 steps | 35 | 配 4 步蒸馏 LoRA 时改成 4。两种配错都会出糊图或黑图 | | CFG cfg | 1.0 | 实测配方。调到 >1 才需要负面提示词（负面在「高级」里） | | 锁定方式 init | auto | 见下表 | | 降噪强度 denoise | 1.0 | 1.0 = 完全重画。小于 1 才保留起点图的成分 | | 复绘宫格线 reborder | 开 | 解码后重画线。关掉就只能指望模型把线画直 | | 负面提示词 negative | 空 | 在**「高级」**折叠区里。cfg=1.0 时填了也不生效（见下） |

init（送提示词的方式）三个选项

| 选项 | 界面显示 | 实际做什么 | |---|---|---| | auto | 自动（纯布局） | 默认。把每格描述转成布局框，纯生成。等价于 layout | | layout | 纯布局 | 同上，显式写法 | | plain | 原样提示词 | 整段提示词直接送模型，不转布局框。等于普通文生图 |

本包不做图生图。 起点恒为空 latent，denoise 留 1.0。 MOSS 不以参考图条件化（官方 limitation 明写"不支持编辑"），模板图只作为 MossStoryboardLayout 的一路 IMAGE 输出，用来肉眼核对格子位置，不进采样器。 想从一张已有图改内容，请换支持 img2img 的模型，而不是在本包上试 denoise。

为什么 negative 默认收起来：MOSS 实测用 cfg=1.0，而 ComfyUI 在 cfg=1 时 直接跳过负面分支，那段根本不进计算图。摆在明面上只会让人以为"写了就生效"。 想用负面：把 cfg 调到 >1，再展开节点上的「高级」。

🎬 故事板 · 裁格（MossStoryboardCrop）

输出：panels（逐格 IMAGE）preview（带裁切线的整图）report（切了几格、每格坐标）

  • 接 spec ⇒ 与生成时逐像素一致。
  • 不接 spec ⇒ 按列数 × 行数整除图像；除不尽直接报错，不会凑出差 1 像素的格子。

节点中英切换

每个本包节点的标题栏上有一个「中 / EN」按钮。点一下，本包三个节点的 标题、参数标签、下拉框显示、悬浮提示一起切换。默认跟随 ComfyUI 的语言设置。

  • 只改本包节点，官方和别人的节点一个字节都不动。
  • 只改显示，不改图：只动标签、标题、提示、输入框占位文字；参数名和下拉框的值从不改 ⇒ 工作流 JSON 一个字节都不变。你自己改过的节点标题也会保留。
  • 升级后必须刷新浏览器页面（F5）。重启 ComfyUI 进程不算——前端是单页应用， 页面开着就一直跑旧 JS。
  • 不用前端也能用：后端文案是英文，JS 加载失败只是没有中文，不会报错； API 提交（/prompt）本来就用不上按钮。

看不到按钮、或者想改词表：见 docs/04（含三行诊断命令）。

已知边界（报 bug 前先看这里）

实测通过的

| 项 | 结论 | 量 | |---|---|---| | 3/4/6/8/9 格 · 横竖构图 · 无缝 · 粗缝 · 小画布 · plain 路线 | 全部真跑成功，尺寸与理论值逐像素一致 | 15 次真跑 | | 宫格线 | 复绘后缝与外框为纯白 | 每个用例采样 | | 随机种子 | 换种子 → 整图 md5 不同 | 2 次对照 |

这一版做不到的

  • 🔴 不做图生图。 MOSS 不以参考图条件化（官方 limitation 明写"不支持编辑"）。实测三组： 35 步 / 降噪 0.85 → 纯黑；12 步 / 0.6 与 4 步 / 0.5 → 模板残影——只要降噪真的截断了 sigma， 模型就不改动画面。所以 0.1.2 起直接移除了这条通路，init 不再有 template / both， 采样器也不再接受模板输入。
  • ⚠ 官方非蒸馏配方（50 步 / cfg 3）本机跑出来是崩坏扭曲的。 原因未确认，社区有能跑通的报告。 默认配置是 4 步（配蒸馏 LoRA）或 35 步 / cfg=1；想试 50/3 请自己出小样对比，别直接量产。
  • ⚠ 低步数时「降噪强度」会被静默吃掉。 宿主按 int(步数 / 降噪) 重算， 4 步时 int(4/0.85)=4 ⇒ 一段都没截，实际等于 1.0。 report 会打印「名义 x / 实际 y」，以实际值为准。既然没有图生图，denoise 请留 1.0。
  • 每格画什么只是"大体照办"。 MOSS 的布局能力官方标 experimental，本包没做成片评分。
  • 8/9 格每格只有约 496×272。 小字、细纹理最先糊——这是分辨率账，不是节点 bug。

硬约束

  • 画布与单格的宽高必须是 16 的倍数（节点已强制；手改 spec 会被拒绝）。
  • 整图超过 2 百万像素会提示，超过 4 百万像素会强提示：MOSS 训练在 1–2 百万像素，官方外推约 4 百万。

常见问题

Q：跑出来一片黑。 先看 report 的「降噪 名义/实际」和步数。常见两种：① 把 cfg 调到了 >1 或 steps 调到 50 （本机实测会崩坏，见「这一版做不到的」）；② 装了 4 步 LoRA 却用了 35 步，或者没装 LoRA 却用了 4 步。

Q：格子数量对，但内容串了 / 全挤在一格里。 布局框只是"建议"，模型可能不照办。先把每格描述写短、写具体（一个镜头一句话）， 再检查 report 里"解析了几段面板描述"是否等于格数。

Q：生成出来的图和预览的宫格形状不一样。 检查是否同时接了「宫格几何」的 spec；接了就以 spec 为准，采样器上的格数参数会被忽略。

Q：找不到节点。 节点在 moss/storyboard 分类下。搜索框打 故事板、storyboard、宫格 都能找到 （本包注册了中英搜索别名）。还是找不到，先看启动日志有没有 [MOSS SB] 那行。

Q：没有「中 / EN」按钮。 ① 刷新浏览器（F5）；② 确认只有本包节点上才有按钮，官方节点不会有； ③ 控制台看有没有 [MOSS SB] i18n: 就绪，细节见 docs/04。

Q：能不能用我自己的负面提示词？ 能，但要先把 CFG 调到 >1，再在节点的「高级」里展开「负面提示词」。cfg=1.0 时它不进计算图。

Q：能不能只生成一张普通图，不分格？ 可以：格数选 1（panels=1），或者把 init 设为 plain。

目录结构

ComfyUI-MOSS-Storyboard/
├── __init__.py            加载入口（V3 默认，V1 一行回退）
├── nodes.py               节点定义（参数表的唯一来源）
├── core/                  纯 Python 内核：几何 / 提示词 / 像素 / 采样
├── v3/                    V3 接口外壳
├── web/                   前端扩展（中英切换）
├── tests/ tools/          自动机检与开发脚本
├── examples/              可直接载入的工作流
├── docs/                  机理与实测记录
└── pyproject.toml         元数据 + 宿主版本要求

许可与出处

  • 本包代码 MIT。
  • 思路参考与代码归属见 THIRD-PARTY-NOTICES.md（未复制任何第三方代码）。
  • 模型权重（MOSS-Image / Qwen3.5 / FLUX.2 VAE）不随包分发，请遵守各自许可。
  • 宿主 ComfyUI 为 GPL-3.0，本包只在进程内 import，不复制其源码。

文档索引

| 文档 | 内容 | |---|---| | docs/01 | 宫格几何数学、spec 格式、旧实现 11 项缺陷 | | docs/02 | 端到端矩阵实测记录（每条用例的参数与产物） | | docs/03 | 开源就绪度自查（覆盖了什么、没覆盖什么） | | docs/04 | 中英切换与控件机理（维护者向） | | docs/05 | 本地开发与维护：单一副本、两件"重载"、改动验证顺序、写作规范 | | AGENTS.md | 本仓开发规范：改动入口、铁律、验收清单 | | CONTRIBUTING.md | 怎么跑机检、提交前必须过哪几条 | | CHANGES.md | 变更记录 |