# sug_v6_1_2_8 可视化工具

## 概述

这是 `sug_v6_1_2_8.py` 的配套可视化工具。**基于 v6.1.2.5 的 React Flow 可视化引擎**，通过数据转换层将 v6.1.2.8 的轮次数据转换为图结构，实现美观的交互式可视化。

## 🎯 核心特性

### 1. 智能数据转换
- 自动检测数据格式（v6.1.2.5 或 v6.1.2.8）
- 将轮次数据（rounds）转换为节点-边图结构
- 保留完整的轮次信息和来源追踪

### 2. 多类型节点支持
| 节点类型 | 颜色 | 说明 |
|---------|------|------|
| `root` | 紫色 (#6b21a8) | 原始问题根节点 |
| `seg` | 绿色 (#10b981) | 初始分词结果 |
| `q` | 蓝色 (#3b82f6) | 查询节点 |
| `search` | 深紫 (#8b5cf6) | 搜索操作节点 |
| `note` | 粉色 (#ec4899) | 帖子结果节点 |

### 3. 来源标识
清楚展示每个Query的来源：
- **seg** - 来自分词
- **add** - 加词生成
- **sug** - 建议词生成

### 4. 交互功能
继承 v6.1.2.5 的所有交互功能：
- ✅ 节点拖拽和缩放
- ✅ 按层级筛选
- ✅ 节点搜索
- ✅ 路径高亮
- ✅ 目录树导航
- ✅ 节点折叠/展开
- ✅ 聚焦功能

## 📁 文件结构

```
visualization/sug_v6_1_2_8/
├── index.js                  # 主可视化脚本（支持格式检测）
├── convert_v8_to_graph.js   # 数据转换层
├── package.json             # 依赖配置
├── node_modules/            # 依赖包（React Flow, esbuild等）
└── README.md               # 本文档
```

## 🚀 使用方式

### 方式1：通过主脚本自动生成

```bash
# 运行脚本并自动生成可视化
python sug_v6_1_2_8.py --max-rounds 2 --sug-threshold 0.5 --visualize
```

### 方式2：手动生成可视化

```bash
# 从 run_context.json 生成可视化
node visualization/sug_v6_1_2_8/index.js \
  input/简单扣图/output/sug_v6_1_2_8/20251031/164016_6e/run_context.json \
  output.html
```

## 📊 数据转换说明

### 输入格式（v6.1.2.8）

```json
{
  "o": "快速进行图片背景移除和替换",
  "rounds": [
    {
      "round_num": 0,
      "type": "initialization",
      "seg_list": [
        {"text": "快速", "score": 0.1},
        {"text": "图片", "score": 0.1}
      ],
      "q_list_1": [...]
    },
    {
      "round_num": 1,
      "input_q_list": [...],
      "output_q_list": [
        {"text": "快速图片", "score": 0.2, "from": "add"}
      ],
      "search_count": 3
    }
  ]
}
```

### 转换后格式（图结构）

```json
{
  "nodes": {
    "root_o": {
      "type": "root",
      "query": "快速进行图片背景移除和替换",
      "level": 0
    },
    "seg_快速_0": {
      "type": "seg",
      "query": "快速",
      "level": 1
    },
    "q_快速图片_r2_0": {
      "type": "q",
      "query": "快速图片",
      "level": 2,
      "from_source": "add"
    }
  },
  "edges": [
    {
      "from": "root_o",
      "to": "seg_快速_0",
      "edge_type": "root_to_seg"
    },
    {
      "from": "seg_快速_0",
      "to": "q_快速_r1",
      "edge_type": "seg_to_q"
    }
  ]
}
```

## 🎨 可视化效果

### 图布局
- **水平布局**：从左到右按轮次展开
- **层次化**：相同轮次的节点纵向排列
- **自动布局**：使用 dagre 算法自动计算最佳位置

### 节点样式
- **边框颜色**：根据节点类型区分
- **标签内容**：显示 Query 文本、分数、策略
- **特殊标识**：
  - 未选中的节点：红色 "未选中" 标签
  - Search 节点：显示搜索次数和帖子数

### 边样式
- **虚线**：表示不同类型的关系
- **颜色**：根据策略类型着色
- **箭头**：指示数据流向

## 📦 依赖

所有依赖已包含在 `node_modules/` 中：
- `react` + `react-dom` - UI 框架
- `@xyflow/react` - 流程图库
- `dagre` - 图布局算法
- `esbuild` - 打包工具
- `zustand` - 状态管理

总大小：约 33MB

## 🔧 技术实现

### 转换层（convert_v8_to_graph.js）
- 解析 rounds 数据
- 创建图节点和边
- 维护轮次信息（iterations）

### 可视化层（index.js）
- 格式检测和自动转换
- React Flow 渲染
- 交互功能实现

### 优势
- ✅ 复用成熟的可视化引擎
- ✅ 保持视觉一致性
- ✅ 完整的交互功能
- ✅ 易于维护和扩展

## 📝 更新日志

### v1.0.0 (2025-10-31)
- 基于 v6.1.2.5 可视化引擎
- 实现轮次数据到图结构的转换
- 支持新的节点类型（root, seg, q, search）
- 自动格式检测和转换
- 完整的交互功能

## 🤝 兼容性

| 版本 | 支持 | 说明 |
|------|------|------|
| v6.1.2.5 | ✅ | 直接渲染 query_graph.json |
| v6.1.2.8 | ✅ | 自动转换 run_context.json |

## 📧 问题反馈

如有问题或建议，请查看主项目 README 或提交 Issue。