README_MODERN.md

Conversation Viewer Modern

现代极简风格的多模态对话历史可视化应用

✨ 新特性

相比原版，现代化版本带来了：

• 🎨 现代极简设计 - 采用 Tailwind CSS + Alpine.js，玻璃拟态效果
• 🌓 暗色模式 - 支持明暗主题切换，自动保存偏好
• 🔍 实时搜索 - 快速过滤对话列表
• 📱 完全响应式 - 完美适配桌面和移动设备
• ⚡ 流畅动画 - AOS 滚动动画，提升用户体验
• 🎯 紧凑模式 - 可切换信息密度
• 💡 智能交互 - 悬浮操作、一键复制、图片灯箱
• 🔄 自动刷新 - 可配置的自动更新机制

🚀 快速开始

前置要求

• Python 3.7+
• uv (推荐) 或 pip

安装依赖

# 使用 uv (推荐)
uv sync

# 或使用 pip
pip install -r requirements.txt

启动服务

# 使用启动脚本
# Windows:
start_english.bat

# Linux/Mac:
./start.sh

# 或直接运行
python app.py --port 9052

访问应用

打开浏览器访问: http://localhost:9052

默认端口为 9052，以避免与原版冲突。可通过 --port 参数修改。

📁 目录结构

conversation-viewer-modern/
├── app.py                    # FastAPI 后端
├── requirements.txt          # Python 依赖
├── start_english.bat        # Windows 启动脚本
├── start.sh                 # Linux/Mac 启动脚本
├── README_MODERN.md         # 本说明文档
├── data/
│   └── files/              # 多媒体文件（符号链接或复制）
├── hist/                   # 对话历史 JSON 文件
├── static/                 # 静态资源（备用）
└── templates/              # HTML 模板
    ├── index.html         # 对话列表页（现代版）
    └── conversation.html  # 对话详情页（现代版）

🎨 设计亮点

1. 玻璃拟态卡片

• 半透明背景 + 模糊效果
• 细腻的阴影和边框
• 悬浮时的微妙 lift 效果

2. 智能主题切换

• 点击导航栏月亮/太阳图标切换
• 自动检测系统主题偏好
• 偏好设置持久化保存

3. 流畅的动画效果

• AOS 滚动入场动画
• 平滑的过渡效果
• 细腻的微交互

4. 优化的信息展示

• 统计卡片一目了然
• 颜色编码的消息类型
• 响应式网格布局

5. 强大的详情页

• Markdown 实时渲染
• JSON 语法高亮
• 媒体附件网格展示
• 图片灯箱预览
• 一键复制内容

🔧 配置说明

端口配置

默认使用 9052 端口，可通过以下方式修改：

1. 命令行参数：

   python app.py --port 9060
   

2. 修改启动脚本： 编辑 start_english.bat 或 start.sh 中的端口号

文件路径

后端代码与原始版本完全兼容，数据目录配置相同：

BASE_DIR = Path(__file__).parent
FILES_DIR = BASE_DIR / "data" / "files"  # 多媒体文件
HIST_DIR = BASE_DIR / "hist"             # 对话历史

数据准备

与方法一相同，支持两种方式：

方法 A: 符号链接（推荐）

# Windows
mklink /J data\files ..\..\data\files

# Linux/Mac
ln -s ../../data/files data/files

方法 B: 复制文件

# 复制多媒体文件
copy ..\..\data\files\* data\files\

# 复制对话历史
copy *.json hist\

📱 响应式设计

• 桌面端: 3列网格布局，宽屏展示
• 平板端: 2列网格布局
• 移动端: 单列布局，优化的触控体验

🎯 核心功能

对话列表

• 📊 统计卡片展示总数、用户、AI、工具消息数
• 🔍 实时搜索过滤
• 📅 按时间倒序排列
• 🏷️ 文件大小和预览信息

对话详情

• 💬 区分用户、AI、工具、步骤消息样式
• 📎 多媒体附件预览（图片、视频、音频）
• 📋 一键复制文本内容
• 🌙 暗色模式支持
• 📱 紧凑模式切换

媒体播放

• 🖼️ 图片灯箱预览（点击放大）
• 🎬 视频内嵌播放器
• 🎵 音频播放控件
• 💾 附件下载功能

⌨️ 快捷键

• R - 刷新页面（仅在列表页）
• Esc - 关闭图片灯箱

🐛 疑难解答

图片/视频无法显示

• 检查 data/files/ 目录是否存在对应文件
• 确认文件权限设置正确
• 查看浏览器控制台错误信息

对话列表为空

• 确认 hist/ 目录中有 JSON 文件
• 检查 JSON 文件编码是否为 UTF-8
• 验证 JSON 格式是否正确

服务启动失败

• 检查 Python 版本 (需要 3.7+)
• 确认依赖已安装: pip install -r requirements.txt
• 端口被占用时使用 --port 指定其他端口

🔒 安全特性

• ✅ 路径遍历攻击防护
• ✅ 文件名安全检查
• ✅ 静态文件访问限制
• ✅ 敏感信息不泄露

📊 API 接口

与原始版本完全兼容：

• GET / - 对话列表页
• GET /conversation/{filename} - 对话详情页
• GET /api/conversations - 获取对话列表 JSON
• GET /api/conversation/{filename} - 获取对话详情 JSON
• GET /files/{file_id} - 获取多媒体文件
• GET /health - 健康检查

🛠️ 技术栈

• 后端: FastAPI + Uvicorn
• 前端: Tailwind CSS + Alpine.js
• 动画: AOS (Animate On Scroll)
• 图标: Lucide Icons
• Markdown: Marked.js
• 字体: Inter (Google Fonts)

📄 许可证

MIT License (同原项目)

🙏 致谢

原版 conversation-viewer 项目提供了坚实的数据基础和 API 设计，本现代化版本在保留所有后端功能的前提下，专注于提供更优质的前端用户体验。

---

提示: 本版本与原始版本完全兼容，可以并行运行（只需使用不同端口）。