WeChat RAG Agent - Frontend

Warning

重要免责声明 / IMPORTANT DISCLAIMER

本项目仅供技术学习和研究之用，严禁用于任何商业或非法用途。 This project is for educational and research purposes ONLY. Commercial or illegal use is strictly prohibited.

微信聊天记录包含大量个人隐私信息。您在使用本项目时，必须承担所有数据安全和隐私泄露的风险。开发者不对任何数据丢失、泄露或滥用负责。 WeChat chat history contains extensive private information. By using this project, you assume all risks related to data security and privacy breaches. The developers are not responsible for any data loss, leakage, or misuse.

强烈建议您在完全隔离的本地环境中运行本项目，切勿将其部署在任何可公开访问的服务器上。 It is STRONGLY recommended that you run this project in a completely isolated, local environment. DO NOT deploy it on any publicly accessible server.

项目简介

WeChat RAG Agent Frontend 是一个基于 Next.js 15 和 React 19 构建的现代化聊天界面，为 WeChat RAG Agent 后端 提供用户友好的 Web 界面。通过流式对话、实时进度监控和智能聊天记录检索，为用户提供基于历史微信聊天内容的智能问答体验。

界面预览

现代化的聊天界面，支持实时流式回答和智能聊天记录检索

该前端提供了：

• 🎨 现代化聊天界面：流畅的对话体验和实时流式回答
• 📊 实时进度监控：向量化处理进度的可视化展示
• ⚙️ 简化配置流程：一步式设置向导，快速配置 API 服务
• 📱 响应式设计：完美适配桌面和移动设备

相关项目

• 后端API服务: wechat-rag-agent - Spring Boot 后端服务
• 前端Web界面: wechat-rag-frontend - 本项目
• 微信数据提取: chatlog-new - 微信聊天记录提取工具

核心特性

• ⚡ 流式对话：基于 Server-Sent Events 的实时流式聊天响应
• 🔄 实时同步监控：向量化处理进度的实时跟踪和可视化
• 🎯 智能设置管理：本地持久化设置存储，一次配置持久使用
• 🏗️ 模块化架构：基于 React Context 的状态管理和 Hook 模式
• 🎨 shadcn/ui 组件：基于 Radix UI 的高质量组件库
• 📱 移动端优化：响应式设计，支持移动设备操作
• 🔧 开发友好：TypeScript 严格模式，完整的类型安全
• 🐳 容器化部署：Docker 支持，一键部署

技术栈

前端框架

• Next.js 15 - React 全栈框架，支持 App Router
• React 19 - 最新的 React 版本，支持 Server Components
• TypeScript 5 - 静态类型检查，严格模式配置

UI 组件和样式

• Tailwind CSS 4 - 原子化 CSS 框架
• shadcn/ui - 基于 Radix UI 的高质量组件库
• Lucide React - 现代化的图标库

状态管理和表单

• React Context - 全局状态管理
• React Hook Form - 高性能表单处理
• Zod - TypeScript 优先的模式验证

通信和数据处理

• Server-Sent Events - 实时流式数据传输
• Fetch API - 现代化的 HTTP 客户端
• react-markdown - Markdown 渲染支持

架构设计

组件架构

agent-ui/
├── app/                    # Next.js 15 App Router
│   ├── api/               # API 路由处理
│   ├── layout.tsx         # 根布局组件
│   └── page.tsx           # 主页面路由
├── components/            # React 组件
│   ├── chat/             # 聊天相关组件
│   ├── setup/            # 设置向导组件
│   ├── sync/             # 同步监控组件
│   ├── help/             # 帮助和FAQ组件
│   ├── default/          # 默认视图组件
│   └── ui/               # 基础UI组件 (shadcn/ui)
├── contexts/             # React Context 提供者
├── hooks/                # 自定义 React Hooks
├── lib/                  # 工具库和API客户端
└── docker/               # Docker 配置文件

API 集成模式

代理 API 架构：

Frontend → Next.js API Routes → Backend Services

主要 API 路由：

• /api/config - 运行时环境变量配置
• /api/backend/proxy/[...path] - 后端服务代理
• /api/wechat/proxy/[...path] - 微信 API 代理
• /api/backend/sse/chat - 流式聊天接口
• /api/backend/sse/vectorization - 向量化进度流

快速开始

前置条件

1. Node.js 18+ - JavaScript 运行环境
2. npm 或 yarn - 包管理器
3. 后端服务 - WeChat RAG Agent 后端 需要先运行
4. 微信API服务 - 端口 5030 的微信数据提取服务

本地开发

1. 克隆项目

git clone https://github.com/WechatRagAgent/agent-ui
cd agent-ui

2. 安装依赖

npm install
# 或
yarn install

3. 配置环境变量

创建 .env 文件：

# 后端服务地址
BACKEND_API_URL=http://127.0.0.1:8080

# 微信API服务地址
WECHAT_API_URL=http://127.0.0.1:5030

# OpenRouter API 密钥 (可选，可在界面中配置)
OPENROUTER_API_KEY=your_openrouter_api_key

4. 启动开发服务器

npm run dev

访问 http://localhost:3000 查看应用。

5. 构建生产版本

npm run build
npm start

Docker 部署

1. 独立部署

# 构建镜像
docker build -t agent-ui .

# 运行容器
docker run -p 3000:3000 \
  -e BACKEND_API_URL=http://host.docker.internal:8080 \
  -e WECHAT_API_URL=http://host.docker.internal:5030 \
  agent-ui

2. 使用 Docker Compose（推荐）

如果后端服务已在 wechat-rag 网络中运行：

# 启动前端服务
docker-compose up --build

# 后台运行
docker-compose up -d --build

docker-compose.yml 配置了：

• 自动连接到 wechat-rag 网络
• 环境变量配置
• 端口映射和服务依赖

使用指南

首次设置

1. 访问应用：打开 http://localhost:3000
2. 配置向导：首次访问会进入设置向导
3. API配置：
   • 后端服务地址：http://localhost:8080
   • 微信API地址：http://localhost:5030
   • OpenRouter API密钥：获取地址
4. 测试连接：系统会自动测试各服务连接状态
5. 开始使用：配置完成后即可开始聊天

主要功能

智能聊天

• 输入问题，基于微信聊天记录获得智能回答
• 支持流式回答，实时展示生成过程
• 自动保存对话历史到本地存储

数据同步

• 点击"同步数据"开始向量化处理
• 实时监控处理进度和状态
• 支持按好友昵称和时间范围过滤

设置管理

• 所有设置自动保存到 localStorage
• 支持重新配置 API 服务地址和密钥
• 连接状态实时检测和显示

开发指南

项目结构说明

核心文件

• app/page.tsx - 主页面，视图路由逻辑
• contexts/app-context.tsx - 全局状态管理
• lib/types.ts - TypeScript 类型定义
• lib/api/ - API 客户端封装

组件组织

• 功能组件 (components/chat/, components/setup/)：业务逻辑组件
• UI组件 (components/ui/)：基于 shadcn/ui 的通用组件
• 上下文提供者 (contexts/)：状态管理和数据流

开发命令

# 开发服务器 (支持 Turbopack)
npm run dev

# 类型检查
npx tsc --noEmit

# 生产构建
npm run build

环境变量

变量名	描述	默认值
BACKEND_API_URL	后端 API 服务地址	http://127.0.0.1:8080
BACKEND_URL	API 路由使用的后端地址	http://127.0.0.1:8080
WECHAT_API_URL	微信 API 服务地址	http://127.0.0.1:5030
OPENROUTER_API_KEY	OpenRouter API 密钥	-

注意：运行时环境变量通过 /api/config 端点提供给客户端，支持 Docker 环境下的动态配置。

故障排除

常见问题

1. 无法连接后端服务

问题：前端显示后端服务连接失败

解决方案：

# 检查后端服务状态
curl http://localhost:8080/actuator/health

# 检查环境变量配置
cat .env.local

# 重启开发服务器
npm run dev

2. 流式聊天中断

问题：聊天回答中途停止或连接断开

解决方案：

• 检查 OpenRouter API 密钥是否有效
• 确认网络连接稳定
• 查看浏览器开发者工具的网络面板

3. 向量化进度不更新

问题：同步进度卡住不动

解决方案：

# 检查微信API服务
curl http://localhost:5030/health

# 查看后端服务日志
docker-compose logs -f wechat-rag-agent

4. 样式显示异常

问题：页面样式错乱或组件显示不正常

解决方案：

# 清理缓存并重新安装依赖
rm -rf .next node_modules package-lock.json
npm install
npm run dev

许可证

本项目采用 MIT License 开源许可证。

致谢

感谢以下开源项目和服务：

• Next.js - React 全栈开发框架
• React - 用户界面构建库
• Tailwind CSS - 实用优先的 CSS 框架
• shadcn/ui - 高质量 React 组件库
• Radix UI - 无样式、可访问的 UI 原语
• Lucide - 美观的开源图标库

免责声明

⚠️ 请再次注意：

1. 隐私保护：本前端界面用于处理微信聊天记录，包含极其敏感的个人隐私信息，使用前请确保充分理解相关风险。

2. 本地运行：强烈建议仅在本地隔离环境中运行，不要将包含真实聊天数据的服务暴露到公网。

3. 合规使用：请确保您的使用方式符合当地法律法规和微信用户协议。

4. 数据安全：开发者不对任何数据泄露、丢失或滥用承担责任。

5. 学习目的：本项目仅供技术学习和研究使用，禁止用于任何商业用途。

---

如果此项目对您有帮助，请给我们一个 ⭐ Star！

_{Built with ❤️ for learning and research purposes only}