# 🦊 MoFox Bot 记忆图可视化工具

这是一个交互式的Web界面,用于可视化和探索MoFox Bot的记忆图结构。

## ✨ 功能特性

- **交互式图形可视化**: 使用Vis.js展示节点和边的关系
- **实时数据**: 直接从记忆管理器读取最新数据
- **节点类型分类**: 不同颜色区分不同类型的节点
  - 🔴 主体 (SUBJECT)
  - 🔵 主题 (TOPIC)
  - 🟢 客体 (OBJECT)
  - 🟠 属性 (ATTRIBUTE)
  - 🟣 值 (VALUE)
- **搜索功能**: 快速查找相关记忆
- **过滤器**: 按节点类型过滤显示
- **统计信息**: 实时显示图的统计数据
- **节点详情**: 点击节点查看详细信息
- **自由缩放拖动**: 支持图形的交互式操作
- **数据导出**: 导出当前图形数据为JSON

## 🚀 快速开始

### 1. 安装依赖

```bash
pip install flask flask-cors
```

### 2. 启动服务器

在项目根目录运行:

```bash
python tools/memory_visualizer/visualizer_server.py
```

或者使用便捷脚本:

```bash
python run_visualizer.py
```

### 3. 打开浏览器

访问: http://127.0.0.1:5000

## 📊 界面说明

### 主界面布局

```
┌─────────────────────────────────────────────────┐
│  侧边栏                  │  主内容区              │
│  - 搜索框               │  - 控制按钮             │
│  - 统计信息             │  - 图形显示             │
│  - 节点类型图例          │                        │
│  - 过滤器               │                        │
│  - 节点详情             │                        │
└─────────────────────────────────────────────────┘
```

### 操作说明

- **🔍 搜索**: 在搜索框输入关键词,点击"搜索"按钮查找相关记忆
- **🔄 刷新图形**: 重新加载最新的记忆图数据
- **📐 适应窗口**: 自动调整图形大小以适应窗口
- **💾 导出数据**: 将当前图形数据导出为JSON文件
- **✅ 过滤器**: 勾选/取消勾选不同类型的节点来过滤显示
- **👆 点击节点**: 点击任意节点查看详细信息
- **🖱️ 拖动**: 按住鼠标拖动节点或整个图形
- **🔍 缩放**: 使用鼠标滚轮缩放图形

## 🔧 配置说明

### 修改服务器配置

在 `visualizer_server.py` 的最后:

```python
if __name__ == '__main__':
    run_server(
        host='127.0.0.1',  # 监听地址
        port=5000,         # 端口号
        debug=True         # 调试模式
    )
```

### API端点

- `GET /` - 主页面
- `GET /api/graph/full` - 获取完整记忆图数据
- `GET /api/memory/<memory_id>` - 获取特定记忆详情
- `GET /api/search?q=<query>&limit=<n>` - 搜索记忆
- `GET /api/stats` - 获取统计信息

## 📝 技术栈

- **后端**: Flask (Python Web框架)
- **前端**: 
  - Vis.js (图形可视化库)
  - 原生JavaScript
  - CSS3 (渐变、动画、响应式布局)
- **数据**: 直接从MoFox Bot记忆管理器读取

## 🐛 故障排除

### 问题: 无法启动服务器

**原因**: 记忆系统未启用或配置错误

**解决**: 检查 `config/bot_config.toml` 确保:

```toml
[memory]
enable = true
data_dir = "data/memory_graph"
```

### 问题: 图形显示空白

**原因**: 没有记忆数据

**解决**: 
1. 先运行Bot让其生成一些记忆
2. 或者运行测试脚本生成测试数据

### 问题: 节点太多,图形混乱

**解决**: 
1. 使用过滤器只显示某些类型的节点
2. 使用搜索功能定位特定记忆
3. 调整物理引擎参数(在visualizer.html中)

## 🎨 自定义样式

修改 `templates/visualizer.html` 中的样式定义:

```javascript
const nodeColors = {
    'SUBJECT': '#FF6B6B',    // 主体颜色
    'TOPIC': '#4ECDC4',      // 主题颜色
    'OBJECT': '#45B7D1',     // 客体颜色
    'ATTRIBUTE': '#FFA07A',  // 属性颜色
    'VALUE': '#98D8C8'       // 值颜色
};
```

## 📈 性能优化

对于大型图形(>1000节点):

1. **禁用物理引擎**: 在stabilization完成后自动禁用
2. **限制显示节点**: 使用过滤器或搜索
3. **分页加载**: 修改API使用分页

## 🤝 贡献

欢迎提交Issue和Pull Request!

## 📄 许可

与MoFox Bot主项目相同的许可证