# XB_ToolBox

**Repository Path**: CHll/XB_ToolBox

## Basic Information

- **Project Name**: XB_ToolBox
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-21
- **Last Updated**: 2026-06-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

🌐 [English](README.md) | [简体中文](README_zh.md)

# 🧰 ComfyUI XB-BOX (小白工具箱)

---

## 🌟 核心理念

**XB_ToolBox** 的主旨是帮助刚接触 ComfyUI 的新手 AI 玩家快速上手工作流，让本地部署运行更简单便捷，是一个包含前端交互和底层内存调度的综合型 ComfyUI 扩展套件。

- **参数大一统**：整合了工作流中使用频率高但分散的参数节点，通过一个中枢节点即可设置常用的图片/视频基础参数。
- **可视化教学**：提供了可视化分块预览和参数雷达节点，让新手更直观地理解解码器/编码器的时空分块以及重叠（Overlap）的底层原理。
- **操作体验革命**：首创“镜像克隆台”，可将复杂工作流中的主要操作节点一键克隆至统一面板，让创作面板极度整洁高效。
- **极限显存压榨**：通过 **“时空分块劫持”、“UNet / Checkpoint 动态显存外包”** 以及 **“LiteGraph 交互深度定制”**，让消费级显卡也能流畅运行原本会直接 OOM 的 14B~22B 超大 3D-DiT 视频大模型。

---

![界面截图](docs/01.png)
![界面截图](docs/02.png)
![界面截图](docs/03.png)
![界面截图](docs/04.png)

![界面截图](docs/05.png)
![界面截图](docs/06.png)

---

### ✨ 核心节点

#### 1. 🎬 媒体参数与时空可视化

- **🖼️ 图片参数大全**：提供宽度、高度、生成数量、控制力度等核心参数。所有参数强制步长锁定，避免新手输入错误导致崩溃；选择固定宽高比时会自动对齐长边尺寸。
- **🎬 视频参数大全**：提供宽、高、帧数、帧率（支持浮点和整数）。内置极客级“手自一体换挡引擎”，在官方预训练的“黄金桶分辨率”（如 480x832, 720x1280）之间平滑切挡，并严格锁定 `1+8N` 的物理安全帧数。根据帧率即时推算并显示视频物理时长。
- **🧊 时空分块预览 (Chunk Visualization)**：独创双区雷达！左侧通过 2D 展示图像分块和重叠数值的可视化效果，右侧通过 3D 画家算法渲染时间圆柱堆叠。彻底终结新手盲目调试参数导致的精力耗费。
- **🧊 分镜图片切割**：提供多种模式，可以将常见的四宫格、六宫格、九宫格..图片一次性切割，并输出多个图片，更加方便图生视频或者首尾帧视频，对于做短剧十分有效。
- **📟 可用显存计算 & 数据雷达**：预判 WAN / LTX 等模型在不同量化（FP8/GGUF）下的显存驻留，并提供精确到 MB 级别的张量体积称重。方便新手根据显存容量精准选择模型，大幅降低试错成本。

#### 2. 🧊 显存优化

- **🧊 采样分块大师 (Sampler Chunk Master)**：专为 WAN / LTX 深度开发。在潜空间（Latent）执行时空双轴切割（Spatial Tiles & Temporal Chunks）。原地劫持模型参数，内置 `rocm_optimized` 极致显存回收策略，彻底打破大张量 OOM 魔咒。
- **✂️ 模型分块交换 (Block Swap)**：支持 UNet 与 Checkpoint 模式。可将前 N 个核心块（Transformer Blocks）以及 Text/Image 嵌入层强制卸载至系统物理内存（RAM），用时间换取空间。
- **🧹 显存清理大师 (VRAM Cleaner)**：战前清场必备。提供“核爆级清理”，深度调用 `gc.collect()` 与 `torch.cuda.empty_cache()`，强行粉碎 PyTorch 缓存碎片。

#### 3. 🎛️ 工作流部署助手

- **🪄 XB 远程控制中心 (Dashboard Zen)**：利用 LiteGraph 底层特性开发的“镜像克隆台”。可将工作流中分散的任意组件批量“克隆”到一个固定面板中。双向数据同步，大动脉直连，打造简洁易用的定制化监控台。
- **🎛️ 动态总线 (Dynamic Bus)**：极度压缩尺寸的 N进N出 `AnyType` 万能接线端。提供 UI 自定义类型标签与一键通道增减，拯救杂乱无章的节点面条线。

---

### 📦 安装指南 (Installation)

**方法一：通过 ComfyUI Manager (推荐)**  
在管理器中搜索 `XB_ToolBox` 或 `小白工具箱` 进行一键安装。

**方法二：手动 Git 安装**  
进入你的 ComfyUI `custom_nodes` 目录，执行以下命令：

```bash
git clone https://github.com/wjluoxiao/XB_ToolBox.git
```

*(注：本插件纯粹依赖 ComfyUI 原生生态，通过精妙的 Python/JS 架构实现，**无需安装任何额外 pip 依赖！** 纯净、即插即用。)*

---

### 📝 许可证 (License)

本项目基于 **Apache-2.0 License** 开源。在极度自由分享的同时，保障了核心架构代码的专利防御权。

---