Mofox-Core/tools/memory_visualizer

🦊 记忆图可视化工具

一个交互式的 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：交互式菜单（推荐）

# 在项目根目录运行
.\visualizer.ps1

# 或在工具目录运行
cd tools\memory_visualizer
.\visualizer.ps1

方式 2：命令行参数

# 启动独立版（推荐，快速）
.\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. 数据管理

   • 📂 多文件选择器
   • 💾 导出图形数据
   • 🔄 实时刷新

🔧 依赖安装

脚本会自动检查并安装依赖，也可以手动安装：

# 激活虚拟环境
.\.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

调试

# 启动 Flask 调试模式
$env:FLASK_DEBUG = "1"
python tools/memory_visualizer/visualizer_simple.py

📚 相关文档

• 快速开始指南
• 更新日志
• 详细使用指南

🆘 获取帮助

遇到问题？

1. 查看 常见问题
2. 运行 .\visualizer.ps1 -Help 查看帮助
3. 查看项目文档目录

📄 许可证

与 MoFox Bot 主项目相同