# XB 📊 硬件监控面板 — 使用说明书

> **节点名称**: `XB_MemoryVisualization`  
> **显示名称**: `XB 📊 硬件监控面板 (Memory Visualization)`  
> **分类**: `XB_ToolBox/Dashboard`  
> **基于**: [ComfyUI-MemoryVisualization](https://github.com/kijai/ComfyUI-MemoryVisualization)  
> **适配**: 小白工具箱 (XB_ToolBox) / NVIDIA + AMD 双卡支持

---

## 目录

1. [功能概览](#1-功能概览)
2. [安装与依赖](#2-安装与依赖)
3. [快速上手](#3-快速上手)
4. [面板布局详解](#4-面板布局详解)
5. [右键菜单](#5-右键菜单)
6. [迷你栏 (Mini Bar)](#6-迷你栏-mini-bar)
7. [模型列表](#7-模型列表)
8. [历史图表](#8-历史图表)
9. [主题切换](#9-主题切换)
10. [AMD GPU 用户须知](#10-amd-gpu-用户须知)
11. [常见问题](#11-常见问题)

---

## 1. 功能概览

硬件监控面板是一个**实时、可拖拽、可缩放**的系统资源监控窗口，在 ComfyUI 界面右下角自动显示。

### 核心功能

| 功能 | 说明 |
|------|------|
| **VRAM 显存监控** | 实时显示 GPU 显存使用量、分段占比（模型/Torch/缓存/其他） |
| **RAM 内存监控** | 系统内存、进程内存、固定内存、Python 占用 |
| **GPU 状态** | 利用率、温度、功耗（NVIDIA 全支持 / AMD 需 LibreHardwareMonitor） |
| **CPU 状态** | CPU 使用率、型号识别 |
| **磁盘监控** | 磁盘读写速率、各分区剩余空间 |
| **页面文件** | 虚拟内存使用情况 |
| **模型详情** | 已加载模型列表、每个模型的 VRAM/内存分段占用 |
| **历史图表** | VRAM 使用量趋势图（面积图/柱状图/K线图/点阵图） |
| **快捷操作** | 一键卸载模型、清除缓存、执行/中断工作流 |

### 界面截图说明

```
┌─────────────────────────────────────────┐
│ ≡ 硬件监控              [▶] [卸载▾] [⤤] [−] │  ← 标题栏（可拖拽）
├─────────────────────────────────────────┤
│ 内存  32.5GB|64.0GB                     │
│ ████████░░░░░░░░░░░░░░ 固定/已加载/...   │  ← 内容区
│ 显存  9.0GB|15.9GB                      │
│ ██████████████░░░░░░░░ 模型/Torch/...    │
│ 峰值: 12.3GB  缓存: 1.2GB  GPU 45%  55°C │
│ 页面文件  2.1GB|16.0GB                   │
├─────────────────────────────────────────┤
│ 14:30          14:32 · 9.0GB    实时     │  ← 图表时间轴
│ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓    │  ← 历史图表
│ ─────── ⬌ 拖拽调整图表高度 ───────       │
├─────────────────────────────────────────┤
│ ▸ AutoencodingEngine         320 MB     │  ← 模型列表
│ ▸ Lumina2                    5.7 GB     │
│ ▸ ZImageT2IModel             4.1 GB     │
└─────────────────────────────────────────┘
```

---

## 2. 安装与依赖

### 自动安装

面板**无需放置节点即可自动加载**。ComfyUI 启动后，监控窗口自动出现在界面右下角。

### 必备依赖

**第一步：安装 .NET 运行时（AMD GPU 必需）**

下载并安装 Windows Desktop Runtime 10.0.10：
```
https://builds.dotnet.microsoft.com/dotnet/WindowsDesktop/10.0.10/windowsdesktop-runtime-10.0.10-win-x64.exe
```

**第二步：安装 Python 依赖**

```bash
pip install psutil pythonnet
```

| 依赖 | 用途 | 必需 |
|------|------|------|
| `psutil` | CPU/内存/磁盘/进程信息 | ✅ 是 |
| `pythonnet` | .NET 桥接，驱动 LibreHardwareMonitor | ✅ 是 |
| `.NET Windows Desktop Runtime 10.0.10` | pythonnet 运行所需 | ✅ 是 |
| `LibreHardwareMonitorLib.dll` | GPU 传感器读取（已内置） | ✅ 是 |
| `nvidia-ml-py` | NVIDIA GPU 精准显存数据 | ⚠️ 可选 |

> `LibreHardwareMonitorLib.dll` 已内置在 `XB_ToolBox\` 目录中，无需额外下载。

### NVIDIA 用户（可选）

```bash
pip install nvidia-ml-py
```

安装后可获得设备级显存数据（而非进程级），Windows WDDM 下尤其有用。

---

## 3. 快速上手

### 3.1 启动面板

1. 启动 ComfyUI
2. 面板**自动出现**在界面右下角
3. 如果没有看到，检查 ComfyUI 控制台是否有报错

### 3.2 面板操作

| 操作 | 方法 |
|------|------|
| **移动面板** | 拖拽标题栏 |
| **调整大小** | 拖拽面板左/右/下边缘或右下角 |
| **折叠/展开** | 点击标题栏 `−` / `+` 按钮 |
| **弹出窗口** | 点击 `⤤` 按钮（画中画模式） |
| **运行工作流** | 点击 `▶` 按钮 |
| **取消运行** | 运行中点击 `■` 按钮 |
| **打开菜单** | 右键点击面板任意位置 |

### 3.3 工作流节点（可选）

你也可以将 `XB 📊 硬件监控面板` 节点拖入工作流：
- 节点本身**不产生任何输出**
- 执行节点时会在控制台打印当前 VRAM 状态
- 主要用作工作流中的"书签"标记

---

## 4. 面板布局详解

### 4.1 标题栏

```
≡ 硬件监控              [▶] [卸载▾] [⤤] [−]
```

| 元素 | 功能 |
|------|------|
| `≡` | 拖拽手柄（停靠模式下可见） |
| `硬件监控` | 面板标题 |
| `▶` / `■` | 执行/中断工作流按钮 |
| `卸载▾` | 卸载模型菜单 |
| `⤤` | 弹出画中画窗口 |
| `−` / `+` | 折叠/展开面板 |

> 注：标题文字默认**不显示**（避免占用顶栏横向空间，实测可省约 108~132px），可在右键菜单「迷你视图 → 头部显示」中开启。

### 4.2 内容区

#### 内存行
```
内存  32.5GB|64.0GB
████████░░░░░░░░░░░░░░░░░░░░
■ 固定 9.9GB  ■ 已加载 0KB  ■ Python 11.3GB  ■ 其他 11.3GB
```

- **固定内存 (Pinned)**：用于 GPU 快速传输的锁页内存
- **已加载 (Loaded)**：已从磁盘加载到 RAM 的模型数据
- **Python**：Python 进程自身占用
- **其他**：系统及其他进程占用

#### 显存行
```
显存 (AMD Radeon RX 7900 XTX)  9.0GB|15.9GB
████████████████░░░░░░░░░░░░░░░░
■ 模型 5.7GB  ■ Torch 2.1GB  ■ 缓存 0.5GB  ■ 其他 0.7GB
峰值: 12.3GB  缓存: 1.2GB  GPU 45%  55°C  9W  ● 运行中
```

- **模型 (Models)**：已加载模型占用的 VRAM
- **Torch**：PyTorch 活跃分配
- **缓存 (Cache)**：PyTorch 缓存池（可释放）
- **其他 (Other)**：驱动及其他进程占用

底部信息行：
| 项目 | 说明 |
|------|------|
| `峰值` | 自面板启动以来的 VRAM 最大使用量 |
| `缓存` | PyTorch 缓存池大小 |
| `GPU XX%` | GPU 核心利用率（点击可切换图表上的 GPU 曲线） |
| `XX°C` | GPU 温度 |
| `XX W` | GPU 功耗 |
| `● 运行中` / `● 空闲` | 工作流执行状态 |

#### 页面文件行
```
页面文件  2.1GB|16.0GB
████████░░░░░░░░░░░░░░░░░░░░░░
```
仅当系统启用了页面文件时显示。

---

## 5. 右键菜单

右键点击面板任意位置打开配置菜单：

```
┌─────────────────────┐
│ 缩放          ▸     │  面板整体缩放 (50%~200%)
│ 字号          ▸     │  字体大小 (10px~20px)
│ 轮询间隔      ▸     │  数据刷新频率 (100ms~5s)
│ 显示          ▸     │  显示选项
│ 迷你视图      ▸     │  折叠状态下的迷你栏选项
│ 图表          ▸     │  图表样式和颜色
│ 主题          ▸     │  配色方案
│ 停靠宽度      ▸     │  停靠到顶栏时的宽度
│ ✓ 停靠到顶栏        │  切换浮动/停靠模式
│   重置历史          │  清除图表历史数据
└─────────────────────┘
```

### 5.1 缩放子菜单

| 选项 | 效果 |
|------|------|
| 50% ~ 200% | 面板整体缩放，包括所有文字和图表 |

### 5.2 字号子菜单

| 选项 | 适用场景 |
|------|----------|
| 10px ~ 12px | 小屏幕 / 紧凑布局 |
| 13px ~ 14px | 正常阅读 |
| 16px ~ 20px | 大屏 / 远距离观看 |

> 字号与缩放独立：字号只改变文字大小，缩放改变整个面板尺寸。

### 5.3 轮询间隔子菜单

| 选项 | 说明 |
|------|------|
| 100ms ~ 250ms | 极快刷新，CPU 开销较大 |
| **500ms** | 默认，平衡刷新率和性能 |
| 1s ~ 5s | 低频刷新，适合长时间监控 |

### 5.4 显示子菜单

| 选项 | 默认 | 说明 |
|------|------|------|
| 模型条着色 | ☐ | 按模型类型着色进度条 |
| 模型边框着色 | ☑ | 按模型类型着色边框 |
| 模型名着色 | ☑ | 按模型类型着色名称 |
| 显示图例 | ☑ | 显示分段图例文字 |
| 执行按钮 | ☐ | 显示播放/停止按钮 |

### 5.5 迷你视图子菜单

控制面板折叠后迷你栏中显示哪些内容：

| 选项 | 说明 |
|------|------|
| RAM | 内存进度条 |
| VRAM | 显存进度条 |
| CPU | CPU 使用率 |
| 页面文件 | 虚拟内存 |
| GPU ▸ | GPU 子菜单（利用率/温度/功耗） |
| 磁盘 ▸ | 磁盘子菜单（I/O + 各分区空间） |
| 设备名称 | 显示 GPU/CPU 型号 |
| 类型标签 | 显示 RAM/VRAM/CPU 标签 |
| 数值显示 | 显示具体数值 |
| 单位显示 | 显示 GB/MB/°C/W 单位 |
| 分隔线 | 显示分组分隔线 |
| 头部显示 | 显示顶栏开头的面板标题（默认关闭，节省横向空间） |

### 5.6 图表子菜单

| 选项 | 说明 |
|------|------|
| 面积图 (堆叠) | 默认，aimdo+Torch+其他分层显示 |
| 柱状图 | 每3个采样点聚合为一个柱子 |
| K线图 | 类似股票K线，显示开盘/收盘/最高/最低 |
| 点阵 (渐变) | 由上到下渐变的点阵密度图 |
| 显存颜色 | 自定义 VRAM 区域颜色 |
| 总量颜色 | 自定义总量曲线颜色 |
| 平滑度 | 总量曲线的移动平均窗口大小 (0~20) |

### 5.7 主题子菜单

| 主题 | 风格 |
|------|------|
| **default** | 深色主题，橙/绿/蓝配色 |
| comfy | 跟随 ComfyUI 自身主题 |
| light | 亮色主题 |
| sepia | 复古暖色调 |
| fallout | 哔哔小子辐射风（绿色 CRT） |
| pink | 粉色少女风 |
| lucifer | 黑底红字暗黑风 |

---

## 6. 迷你栏 (Mini Bar)

面板折叠后显示的精简状态栏：

```
RAM ████████░░░░  32.5|64.0GB  │  VRAM ██████░░░░  9.0|15.9GB  │  CPU ████░░  45%
```

迷你栏中的 GPU 区域支持**多行模式**（同时显示利用率/温度/功耗时自动启用更紧凑的排版）。

---

## 7. 模型列表

展开面板后，底部显示所有已加载模型的详细信息：

```
▸ AutoencodingEngine                    320 MB  [×]
  ████████████████████████████████████░░░░░░░░
  ■ VRAM 320MB  ■ pinned 0KB  ■ loaded 0KB  ■ RAM 0KB

▾ Lumina2                               5.7 GB  [×]
  ██████████████████████████████████░░░░░░░░░░
  ■ VRAM 5.6GB  ■ pinned 103MB  ■ loaded 0KB  ■ unloaded 4KB
  
  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░  ← aimdo 页级驻留（需 aimdo）
  ■ VRAM 5.6GB  ■ unloaded 4KB
```

| 元素 | 说明 |
|------|------|
| `▸` / `▾` | 点击模型名展开/折叠详情 |
| `[×]` | 卸载该模型 |
| 彩色进度条 | VRAM(橙) / 固定内存(蓝) / 已加载(深蓝) / 未加载(灰) |
| 小方块网格 | aimdo 页面驻留可视化（需安装 comfy_aimdo） |
| `(static)` | 标记为非动态加载的模型 |

---

## 8. 历史图表

图表区域显示 VRAM 使用量随时间变化的趋势：

```
14:30                              14:32 · 9.0GB    实时
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
───────────────────────  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─   ← 虚线 = 总显存上限
────────────────⬌ 拖拽调整图表高度 ────────────────
```

| 操作 | 方法 |
|------|------|
| 查看历史 | 在图表上**左右拖拽**浏览历史数据 |
| 回到实时 | 拖到最右侧自动恢复实时模式 |
| 悬停详情 | 鼠标悬停在图表上查看具体时间/数值 |
| 调整高度 | 拖拽图表下方的分隔条 |
| 执行标记 | 绿色竖线 = 开始执行，红色竖线 = 执行结束 |

### 图表样式

| 样式 | 特点 |
|------|------|
| **面积图** | 堆叠显示 aimdo+Torch+其他，直观 |
| 柱状图 | 每3秒聚合，干净简洁 |
| K线图 | 精确显示波动范围 |
| 点阵图 | 由上到下密度渐变，艺术感强 |

---

## 9. AMD GPU 用户须知

### 支持的 GPU

| GPU 系列 | 架构 | 利用率 | 温度 | 功耗 | VRAM |
|----------|------|--------|------|------|------|
| RX 7000 系列 | RDNA 3 | ✅ | ✅ | ✅ | ✅ |
| RX 6000 系列 | RDNA 2 | ✅ | ✅ | ✅ | ✅ |
| RX 5000 系列 | RDNA 1 | ✅ | ✅ | ✅ | ✅ |
| Vega / Radeon VII | GCN | ✅ | ✅ | ✅ | ✅ |

### 监控原理

AMD GPU 监控通过 **LibreHardwareMonitor** 实现（一个跨厂商的开源硬件监控库）。原理是直接读取 GPU 的 SMU（System Management Unit）传感器数据，与 AMD Adrenalin 驱动面板使用相同的底层接口。

### 如果数据不显示

1. 确认 `XB_ToolBox\LibreHardwareMonitorLib.dll` 存在
2. 确认已安装 `pythonnet`：`pip install pythonnet`
3. 尝试**以管理员身份**运行 ComfyUI
4. 查看 ComfyUI 控制台是否有 `aimdo-viz: LibreHardwareMonitor` 相关日志

### 功耗显示的差异

AMD 功耗显示为 **GPU Package**（整个显卡的总功耗），单位是瓦特 (W)，没有功率上限对比。这与 NVIDIA 的显示格式略有不同（NVIDIA 有 `功耗/上限` 格式）。

---

## 10. 常见问题

### Q: 面板没有自动出现？

A: 检查 ComfyUI 控制台是否有 JavaScript 报错。常见原因：
- `pythonnet` 未安装
- `LibreHardwareMonitorLib.dll` 缺失
- JS 文件加载失败（检查 `js/xb_memory_viz.js` 是否存在）

### Q: GPU 利用率/温度/功耗都显示"无数据"？

A: 
- **NVIDIA**：安装 `nvidia-ml-py` 并重启
- **AMD**：确认 `pythonnet` 已安装且 .NET Windows Desktop Runtime 10.0.10 已安装，查看控制台日志

### Q: 面板太大/太小？

A: 右键 → **缩放** 调整面板大小，或右键 → **字号** 仅调整文字大小。

### Q: 如何让面板固定在顶栏？

A: 拖拽面板到顶部 ComfyUI 操作栏的"停靠左侧"或"停靠右侧"区域释放，或右键 → 停靠到顶栏。

### Q: 图表不更新？

A: 检查轮询间隔设置（右键 → 轮询间隔）。确保未将面板拖拽到历史数据中（右侧显示"实时"即为实时模式）。

### Q: 节点放到工作流中有用吗？

A: 面板**不需要**节点即可工作。节点的作用是：
- 作为工作流书签
- 执行时在控制台打印 VRAM 状态

---

## 附录：键盘与鼠标操作速查

| 操作 | 快捷键/方法 |
|------|------------|
| 移动面板 | 拖拽标题栏 |
| 快速拖拽（任意位置） | `Ctrl` + 拖拽（仅浮动模式；停靠时锁定在顶栏，需 `≡` 手柄拖出或右键→取消停靠） |
| 调整宽度 | 拖拽左/右边缘 |
| 调整高度 | 拖拽底部边缘 |
| 同时调整宽高 | 拖拽右下角 |
| 折叠/展开 | 点击 `−` / `+` |
| 弹出画中画 | 点击 `⤤` |
| 打开菜单 | 右键面板 |
| 关闭菜单 | 点击菜单外部 |
| 浏览图表历史 | 在图表上左右拖拽 |
| 图表悬停详情 | 鼠标悬停图表 |
| 切换图表 GPU 曲线 | 点击 `GPU XX%` 文字 |
| 折叠模型详情 | 点击模型名称 |
| 卸载单个模型 | 点击模型行 `[×]` |