feat: 添加具有服务器和简单模式的内存图可视化工具
-实现了用于启动内存图可视化工具的PowerShell脚本（visualizer.ps1）。 -开发了一个完整的服务器（visualizer_server.py），为可视化内存图数据提供了web API。 -创建了一个简单的独立版本（visualizer_simple.py），可以直接从存储的数据文件生成可视化。 -添加了用于获取完整图形数据、内存详细信息、搜索内存和检索统计信息的端点。 -包括列出可用数据文件和选择特定文件进行可视化的功能。 -在整个服务器和简单的可视化脚本中增强错误处理和日志记录。
This commit is contained in:
Windpicker-owo
201
tools/memory_visualizer/README.md
Normal file
201
tools/memory_visualizer/README.md
Normal file
@@ -0,0 +1,201 @@
|
||||
# 🦊 记忆图可视化工具
|
||||
|
||||
一个交互式的 Web 可视化工具，用于查看和分析 MoFox Bot 的记忆图结构。
|
||||
|
||||
## 📁 目录结构
|
||||
|
||||
```
|
||||
tools/memory_visualizer/
|
||||
├── visualizer.ps1 # 统一启动脚本（主入口）⭐
|
||||
├── visualizer_simple.py # 独立版服务器（推荐）
|
||||
├── visualizer_server.py # 完整版服务器
|
||||
├── generate_sample_data.py # 测试数据生成器
|
||||
├── test_visualizer.py # 测试脚本
|
||||
├── requirements.txt # Python 依赖
|
||||
├── templates/ # HTML 模板
|
||||
│ └── visualizer.html # 可视化界面
|
||||
├── docs/ # 文档目录
|
||||
│ ├── VISUALIZER_README.md
|
||||
│ ├── VISUALIZER_GUIDE.md
|
||||
│ └── VISUALIZER_INSTALL_COMPLETE.md
|
||||
├── README.md # 本文件
|
||||
├── QUICKSTART.md # 快速开始指南
|
||||
└── CHANGELOG.md # 更新日志
|
||||
```
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 方式 1：交互式菜单（推荐）
|
||||
|
||||
```powershell
|
||||
# 在项目根目录运行
|
||||
.\visualizer.ps1
|
||||
|
||||
# 或在工具目录运行
|
||||
cd tools\memory_visualizer
|
||||
.\visualizer.ps1
|
||||
```
|
||||
|
||||
### 方式 2：命令行参数
|
||||
|
||||
```powershell
|
||||
# 启动独立版（推荐，快速）
|
||||
.\visualizer.ps1 -Simple
|
||||
|
||||
# 启动完整版（需要 MemoryManager）
|
||||
.\visualizer.ps1 -Full
|
||||
|
||||
# 生成测试数据
|
||||
.\visualizer.ps1 -Generate
|
||||
|
||||
# 运行测试
|
||||
.\visualizer.ps1 -Test
|
||||
|
||||
# 查看帮助
|
||||
.\visualizer.ps1 -Help
|
||||
```
|
||||
|
||||
## 📊 两个版本的区别
|
||||
|
||||
### 独立版（Simple）- 推荐
|
||||
- ✅ **快速启动**：直接读取数据文件，无需初始化 MemoryManager
|
||||
- ✅ **轻量级**：只依赖 Flask 和 vis.js
|
||||
- ✅ **稳定**：不依赖主系统运行状态
|
||||
- 📌 **端口**：5001
|
||||
- 📁 **数据源**：`data/memory_graph/*.json`
|
||||
|
||||
### 完整版（Full）
|
||||
- 🔄 **实时数据**：使用 MemoryManager 获取最新数据
|
||||
- 🔌 **集成**：与主系统深度集成
|
||||
- ⚡ **功能完整**：支持所有高级功能
|
||||
- 📌 **端口**：5000
|
||||
- 📁 **数据源**：MemoryManager
|
||||
|
||||
## ✨ 主要功能
|
||||
|
||||
1. **交互式图形可视化**
|
||||
- 🎨 5 种节点类型（主体、主题、客体、属性、值）
|
||||
- 🔗 完整路径高亮显示
|
||||
- 🔍 点击节点查看连接关系
|
||||
- 📐 自动布局和缩放
|
||||
|
||||
2. **高级筛选**
|
||||
- ☑️ 按节点类型筛选
|
||||
- 🔎 关键词搜索
|
||||
- 📊 统计信息实时更新
|
||||
|
||||
3. **智能高亮**
|
||||
- 💡 点击节点高亮所有连接路径（递归探索）
|
||||
- 👻 无关节点变为半透明
|
||||
- 🎯 自动聚焦到相关子图
|
||||
|
||||
4. **物理引擎优化**
|
||||
- 🚀 智能布局算法
|
||||
- ⏱️ 自动停止防止持续运行
|
||||
- 🔄 筛选后自动重新布局
|
||||
|
||||
5. **数据管理**
|
||||
- 📂 多文件选择器
|
||||
- 💾 导出图形数据
|
||||
- 🔄 实时刷新
|
||||
|
||||
## 🔧 依赖安装
|
||||
|
||||
脚本会自动检查并安装依赖，也可以手动安装：
|
||||
|
||||
```powershell
|
||||
# 激活虚拟环境
|
||||
.\.venv\Scripts\Activate.ps1
|
||||
|
||||
# 安装依赖
|
||||
pip install -r tools/memory_visualizer/requirements.txt
|
||||
```
|
||||
|
||||
**所需依赖：**
|
||||
- Flask >= 2.3.0
|
||||
- flask-cors >= 4.0.0
|
||||
|
||||
## 📖 使用说明
|
||||
|
||||
### 1. 查看记忆图
|
||||
1. 启动服务器（推荐独立版）
|
||||
2. 在浏览器打开 http://127.0.0.1:5001
|
||||
3. 等待数据加载完成
|
||||
|
||||
### 2. 探索连接关系
|
||||
1. **点击节点**：查看与该节点相关的所有连接路径
|
||||
2. **点击空白处**：恢复所有节点显示
|
||||
3. **使用筛选器**：按类型过滤节点
|
||||
|
||||
### 3. 搜索记忆
|
||||
1. 在搜索框输入关键词
|
||||
2. 点击搜索按钮
|
||||
3. 相关节点会自动高亮
|
||||
|
||||
### 4. 查看统计
|
||||
- 左侧面板显示实时统计信息
|
||||
- 节点数、边数、记忆数
|
||||
- 图密度等指标
|
||||
|
||||
## 🎨 节点颜色说明
|
||||
|
||||
- 🔴 **主体（SUBJECT）**：红色 (#FF6B6B)
|
||||
- 🔵 **主题（TOPIC）**：青色 (#4ECDC4)
|
||||
- 🟦 **客体（OBJECT）**：蓝色 (#45B7D1)
|
||||
- 🟠 **属性（ATTRIBUTE）**：橙色 (#FFA07A)
|
||||
- 🟢 **值（VALUE）**：绿色 (#98D8C8)
|
||||
|
||||
## 🐛 常见问题
|
||||
|
||||
### 问题 1：没有数据显示
|
||||
**解决方案：**
|
||||
1. 检查 `data/memory_graph/` 目录是否存在数据文件
|
||||
2. 运行 `.\visualizer.ps1 -Generate` 生成测试数据
|
||||
3. 确保 Bot 已经运行过并生成了记忆数据
|
||||
|
||||
### 问题 2：物理引擎一直运行
|
||||
**解决方案：**
|
||||
- 新版本已修复此问题
|
||||
- 物理引擎会在稳定后自动停止（最多 5 秒）
|
||||
|
||||
### 问题 3：筛选后节点排版错乱
|
||||
**解决方案：**
|
||||
- 新版本已修复此问题
|
||||
- 筛选后会自动重新布局
|
||||
|
||||
### 问题 4：无法查看完整连接路径
|
||||
**解决方案：**
|
||||
- 新版本使用 BFS 算法递归探索所有连接
|
||||
- 点击节点即可查看完整路径
|
||||
|
||||
## 📝 开发说明
|
||||
|
||||
### 添加新功能
|
||||
1. 编辑 `visualizer_simple.py` 或 `visualizer_server.py`
|
||||
2. 修改 `templates/visualizer.html` 更新界面
|
||||
3. 更新 `requirements.txt` 添加新依赖
|
||||
4. 运行测试：`.\visualizer.ps1 -Test`
|
||||
|
||||
### 调试
|
||||
```powershell
|
||||
# 启动 Flask 调试模式
|
||||
$env:FLASK_DEBUG = "1"
|
||||
python tools/memory_visualizer/visualizer_simple.py
|
||||
```
|
||||
|
||||
## 📚 相关文档
|
||||
|
||||
- [快速开始指南](QUICKSTART.md)
|
||||
- [更新日志](CHANGELOG.md)
|
||||
- [详细使用指南](docs/VISUALIZER_GUIDE.md)
|
||||
|
||||
## 🆘 获取帮助
|
||||
|
||||
遇到问题？
|
||||
1. 查看 [常见问题](#常见问题)
|
||||
2. 运行 `.\visualizer.ps1 -Help` 查看帮助
|
||||
3. 查看项目文档目录
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
与 MoFox Bot 主项目相同
|
||||
Reference in New Issue
Block a user