# Knowledge Search Traverse 可视化工具

## 概述

这是 `knowledge_search_traverse.py` (v6.1.2.125) 的配套可视化工具。**基于 v6.1.2.121 的 React Flow 可视化引擎**，通过数据转换层将语义分段跨域组词的执行数据转换为图结构，实现美观的交互式可视化。

### 🆕 新增功能：多模态图片提取展示

支持展示帖子图片的文字提取和AI语义描述，提供更丰富的内容分析能力。

## 🎯 核心特性

### 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
# 运行脚本并自动生成可视化
python3 knowledge_search_traverse.py --visualize
```

可视化HTML会自动生成在输出目录中。

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

```bash
# 从 run_context.json 生成可视化
node visualization/knowledge_search_traverse/index.js \
  path/to/run_context.json \
  path/to/output.html \
  [--simplified]
```

参数说明：
- `path/to/run_context.json`：运行上下文文件路径（必需）
- `path/to/output.html`：输出HTML文件路径（可选，默认为 `query_graph_output.html`）
- `--simplified`：使用简化视图（可选）

## 📦 数据来源

可视化工具会读取以下文件：

1. **run_context.json**（必需）：主要的运行上下文数据
2. **search_results.json**（可选）：搜索结果详情
3. **search_extract.json**（可选）：🆕 图片提取结果

## 🖼️ 多模态图片提取展示

如果存在 `search_extract.json` 文件，可视化会展示：

- **提取文字**：图片中的所有可见文字内容
- **图片描述**：AI生成的图片详细描述
- **原图展示**：点击可查看原始图片

### search_extract.json 格式

```json
{
  "note_id_xxx": {
    "note_id": "xxx",
    "note_url": "https://...",
    "title": "帖子标题",
    "body_text": "帖子正文",
    "type": "normal",
    "extraction_time": "2025-01-11T15:00:00",
    "images": [
      {
        "image_index": 0,
        "original_url": "https://...",
        "description": "图片的详细语义描述...",
        "extract_text": "图片中提取的文字内容..."
      }
    ]
  }
}
```

### 扩展图片提取展示

如需自定义图片提取结果的展示方式，可以修改 `index.js` 中的React组件，添加图片展示的UI和交互逻辑。

示例位置：
```javascript
// 读取提取结果
const extractPath = path.join(path.dirname(inputFile), 'search_extract.json');
let extractData = {};
if (fs.existsSync(extractPath)) {
    extractData = JSON.parse(fs.readFileSync(extractPath, 'utf-8'));
}
```

## 📊 数据转换说明

### 输入格式（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 节点：显示搜索次数和帖子数

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

## 📦 依赖

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

**安装依赖：**
```bash
cd visualization/sug_v6_1_2_121
npm install
```

总大小：约 34MB

## 🔧 技术实现

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

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

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

## 📝 更新日志

### v1.2.0 (knowledge_search_traverse - 2025-01-11)
- 🆕 集成多模态图片提取功能
- 📦 添加 search_extract.json 数据支持
- 📝 更新文档说明多模态展示方式
- 🔧 修改脚本路径为 knowledge_search_traverse

### v1.1.0 (2025-11-11)
- ✨ 新增目录树卡片交错布局（之字形排列）
- ✨ 新增目录树卡片拖动功能（支持垂直拖动）
- 🔧 增加卡片间距从 8px 到 20px
- 📦 添加 react-draggable 依赖

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

## 🤝 兼容性

| 版本 | 支持 | 说明 |
|------|------|------|
| v6.1.2.121 | ✅ | 直接渲染（语义分段跨域组词版） |
| v6.1.2.125 | ✅ | 完全兼容 + 多模态图片提取 |
| knowledge_search_traverse | ✅ | 当前版本，完整支持 |

## 📧 问题反馈

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