ComfyUI/
└── custom_nodes/
    └── LLS_Nodes/        ← 将本目录内容放在这里
        ├── __init__.py
        ├── nodes.py
        ├── upscale/
        ├── utils/
        └── ...

目录结构

node/
├── __init__.py           ← 插件入口：自动汇总所有子包的 NODE_CLASS_MAPPINGS
├── nodes.py              ← 共享工具函数（不含节点类）
│
├── model_loader/         ← 第 1 节：模型加载与管理
├── conditioning/         ← 第 2 节：文本编码与条件生成
├── sampling/             ← 第 3 节：图像采样与去噪
├── latent/               ← 第 4 节：Latent 空间操作
├── image/                ← 第 5 节：图像处理与后处理
├── upscale/              ← 第 5 节（超分子域）：图像超分辨率放大
├── mask/                 ← 第 6 节：遮罩操作
├── controlnet/           ← 第 7 节：ControlNet / 控制引导
├── lora/                 ← 第 8 节：LoRA / Hypernetwork / Adapter
├── video/                ← 第 10 节：视频生成与帧处理
├── audio/                ← 第 11 节：音频处理
└── utils/                ← 第 14 节：数据类型与逻辑工具

已实现节点

LLS/Upscale

节点名	说明
`LLS Upscale Switcher`	在 upscale_model 与 PyTorch 插值之间切换的超分节点

输入参数：

参数	类型	默认值	说明
`image`	IMAGE	—	输入图像
`mode`	选项	`upscale_model`	`upscale_model`（模型超分）或 `pytorch`（插值放大）
`scale`	FLOAT	2.0	放大倍数（仅 pytorch 模式生效）
`interpolation`	选项	`bilinear`	插值算法（仅 pytorch 模式生效）
`model_name`	选项	—	超分模型名（从 `models/upscale_models/` 读取）
`tile`	INT	512	分块大小，越小显存越省（仅 upscale_model 模式生效）
`overlap`	INT	32	分块重叠像素（仅 upscale_model 模式生效）

输出： IMAGE

LLS/Utils

节点名	说明
`LLS String Literal`	输出一个字符串常量，可复用于多个下游节点
`LLS Int Literal`	输出一个整数常量
`LLS Float Literal`	输出一个浮点数常量
`LLS Resolution Selector`	从常用分辨率预设中选择，或输入自定义宽高，返回 width 和 height

Image Repair

LLS-node 现在提供一套面向本地工作流的修复链路，由以下节点组成：

LLS Simple Mask Draw
LLS Simple Repair Prepare
LLS Simple KSampler
LLS Simple Repair Finish

修复工作流不是从 LLS Simple Empty Latent 开始，而是从 image + mask + vae 开始。LLS Simple Repair Prepare 会把这些输入转换为带有 repair_info 的修复态 latent，再交给同一个 LLS Simple KSampler 继续采样。

`LLS Simple Mask Draw`

LLS Simple Mask Draw 是一个面向局部重绘的交互式遮罩输入节点，用来直接在输入图像上手动画 mask，并把结果输出给后续修复链路。

推荐工作流：

Load Image -> LLS Simple Mask Draw -> Preview Image
Load Image -> LLS Simple Mask Draw -> LLS Simple Repair Prepare

推荐连接方式：

Load Image.image -> LLS Simple Mask Draw.image
LLS Simple Mask Draw.image -> LLS Simple Repair Prepare.image
LLS Simple Mask Draw.mask -> LLS Simple Repair Prepare.mask

输入：

名称	类型	说明
`image`	`IMAGE`	必填，原图输入
`input_mask`	`MASK`	可选，已有遮罩；节点会在这个遮罩基础上继续编辑

输出：

名称	类型	说明
`image`	`IMAGE`	原图透传
`mask`	`MASK`	最终遮罩，白色 / `1` 表示要重绘，黑色 / `0` 表示不重绘
`preview_image`	`IMAGE`	原图与半透明红色遮罩叠加后的预览图

当前支持的交互功能：

直接在图像上绘制白色遮罩
brush / erase 两种模式
调整 brush_size
调整 brush_softness
调整 overlay_alpha
预览半透明红色遮罩叠加
Clear
Undo
Redo
Invert
在已有 input_mask 基础上继续补画或擦除

如何手动画 mask：

连接 Load Image 到 LLS Simple Mask Draw.image
如果有已有遮罩，可再连接到 input_mask
在节点预览区域直接涂抹需要修复的区域
用 erase 擦除不需要重绘的部分
用 Clear / Undo / Redo / Invert 调整最终结果
将 mask 输出接到 LLS Simple Repair Prepare.mask

典型用途：

手动指定删除区域
手动指定修复区域
手动指定去阴影区域
手动指定局部增强区域

当前版本限制：

第一版只支持 brush 和 erase
还没有实现 polygon、rectangle、ellipse
还没有实现魔棒、自动分割、智能抠图

Minimal Repair Workflow

Load Image -> Load Mask -> LLS Simple Checkpoint Loader -> LLS Simple Prompt Encode -> LLS Simple Repair Prepare -> LLS Simple KSampler -> VAE Decode -> LLS Simple Repair Finish -> Preview Image

Minimal Manual Mask Workflow

Load Image -> LLS Simple Mask Draw -> LLS Simple Repair Prepare -> LLS Simple KSampler -> VAE Decode -> LLS Simple Repair Finish -> Preview Image

`repair_scope`

region：在原图边界内直接修复
crop：围绕 mask 裁剪局部工作区，提高局部细节修复精度
canvas：扩展画布后修复新增区域或缺失区域

`repair_kernel`

latent_mask：对工作图做 VAE encode，并附带 latent noise mask
vae_inpaint：使用兼容 VAE inpaint 的 latent 准备方式
native_fill：当后端原生支持 fill/inpaint 时优先请求原生能力，否则回退并发出 warning

`denoise_mode`

manual：直接使用 sampler 上的 denoise
auto_from_repair：使用 repair_info["recommended_denoise"]

Compatibility

未连接 repair_info 时，现有 txt2img 工作流保持不变。
未连接 repair_info 时，现有 img2img 工作流保持不变。
同一个 LLS Simple KSampler 同时处理 txt2img、img2img 和 repair。

Pro Image Edit / Inpaint

LLS-node 也提供一套更严格的专业局部编辑链路，针对真正支持原生 image edit / inpaint 语义的模型：

LLS Pro Image Edit Prepare
LLS Pro KSampler Bridge
LLS Pro Image Edit Finish

Simple vs Pro

Simple = lightweight masked latent resampling
Pro = true image edit / inpaint pipeline

当模型本身具备真实的局部编辑能力，而且你更在意遮罩区域内的提示词跟随和原生 inpaint / image-edit 行为时，用 Pro 链；如果你只是需要兼容性更高、约束更少的局部重绘流程，继续使用 Simple 链。

Professional Workflow

Load Image -> Load Mask or LLS Simple Mask Draw -> LLS Simple Checkpoint Loader -> LLS Simple Prompt Encode -> LLS Pro Image Edit Prepare -> LLS Pro KSampler Bridge -> VAE Decode -> LLS Pro Image Edit Finish -> Preview Image

Backend Selection

backend_mode = auto | sdxl | flux
auto 会根据 capability metadata 自动路由，找不到专业后端时直接报错，不会静默降级到旧的 Simple repair 逻辑
sdxl 和 flux 会强制指定后端，但仍然会验证当前模型是否兼容

Capability Requirements

model_role
supports_inpaint_native
supports_image_edit_native
preferred_edit_backend

这些字段可以来自：

model_info
LLS Simple Checkpoint Loader 写入到对象上的 _lls_* 元信息
utils/model_info.py 里的 family / name 推断逻辑

Adding new professional edit models

在 utils/model_info.py 里补充或修正角色与 capability 推断规则
确认 LLS Simple Checkpoint Loader 会把正确的 _lls_* capability tags 写到 model / clip / vae
优先用 backend_mode=auto 验证 capability metadata 是否足以自动识别
调试阶段可临时改用 backend_mode=sdxl 或 backend_mode=flux，快速确认显式路由是否匹配预期

Notes

LLSSimple* 修复链保持不变，不会被这套新链覆盖
LLS Pro Image Edit Finish 负责真实的区域混合、裁剪回贴和扩图 canvas 合成
LLS Pro KSampler Bridge 支持 denoise_mode = manual | auto_from_edit

扩展节点

在对应子包的 nodes.py 中添加节点类并注册到 NODE_CLASS_MAPPINGS，重启 ComfyUI 自动生效。

# 示例：在 sampling/nodes.py 中添加节点
class LLSKSampler:
    CATEGORY = "LLS/Sampling"
    FUNCTION = "sample"
    RETURN_TYPES = ("LATENT",)

    @classmethod
    def INPUT_TYPES(cls):
        return { "required": { ... } }

    def sample(self, ...):
        return (latent,)

NODE_CLASS_MAPPINGS = { "LLSKSampler": LLSKSampler }
NODE_DISPLAY_NAME_MAPPINGS = { "LLSKSampler": "LLS KSampler" }

新增功能域只需新建子目录 + __init__.py，并将目录名追加到顶层 __init__.py 的 _SUBPACKAGES 列表。

语法检查

python -m py_compile __init__.py nodes.py upscale/nodes.py utils/nodes.py

节点命名规范

范围	格式	示例
CATEGORY（UI 分组）	`LLS/<域名>`	`LLS/Sampling`
类名	`LLS` + PascalCase	`LLSKSampler`
显示名称（搜索）	`LLS` + 描述	`LLS KSampler`
注册 Key	与类名相同	`"LLSKSampler"`

README.md Unescape Escape

LLS ComfyUI Custom Nodes

安装方法