# Client

**Repository Path**: qingyu_rag/client

## Basic Information

- **Project Name**: Client
- **Description**: 青宇知识库客户端
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-31
- **Last Updated**: 2026-02-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Qingyu RAG Client

青羽 RAG 智能助手客户端，基于 Vue 3 + Vite 构建的现代化聊天应用。

## 项目简介

这是一个使用 Vue 3 和 Vite 构建的 RAG（检索增强生成）智能助手前端应用，采用 pnpm 作为包管理器，并使用 rolldown-vite 作为构建工具以提供更快的构建速度。应用集成了流式输出的 AI 对话功能，支持多种 AI 提供商选择。

## 技术栈

- **前端框架**: Vue 3.5.24
- **构建工具**: Vite (rolldown-vite 7.2.5)
- **开发工具**: @vitejs/plugin-vue 6.0.1
- **包管理器**: pnpm
- **HTTP 代理**: Vite Dev Server Proxy

## 项目结构

```
Client/
├── public/                 # 静态资源目录
│   └── vite.svg           # Vite logo
├── src/                   # 源代码目录
│   ├── assets/            # 资源文件（图标、图片等）
│   ├── components/        # 组件目录
│   ├── App.vue            # 根组件（聊天界面）
│   ├── main.js            # 应用入口文件
│   └── style.css          # 全局样式
├── .gitignore             # Git 忽略文件配置
├── index.html             # HTML 模板
├── package.json           # 项目配置和依赖
├── pnpm-lock.yaml         # 依赖锁定文件
├── README.md              # 项目文档
└── vite.config.js         # Vite 配置文件
```

## 功能特性

### 1. RAG 智能对话
- 集成后台 RAG 接口，提供智能问答服务
- 支持自然语言查询，返回精准答案
- 实时显示对话历史

### 2. AI 提供商选择
- DeepSeek
- OpenAI
- Anthropic

### 3. 参数配置
- **TopK 参数**: 可调节检索返回的相关文档数量（1-10）
- **AI 提供商**: 灵活切换不同的 AI 模型

### 4. 流式输出效果
- 打字机式逐字显示 AI 回复
- 平滑的动画效果
- 提升用户体验

### 5. 现代化 UI 设计
- 渐变色主题设计
- 响应式布局，适配不同屏幕尺寸
- 深色/浅色模式自适应
- 流畅的交互动画

### 6. 用户体验优化
- Enter 键快速发送（Shift+Enter 换行）
- 加载状态提示
- 错误信息友好提示
- 发送中禁用输入防止重复提交

## 核心文件说明

### 1. 应用入口 (`src/main.js`)
```javascript
import { createApp } from 'vue'
import './style.css'
import App from './App.vue'

createApp(App).mount('#app')
```
- 创建 Vue 应用实例
- 挂载全局样式
- 将应用挂载到 `#app` DOM 节点

### 2. 根组件 (`src/App.vue`)
**主要功能：**
- 聊天界面布局和样式
- 用户输入处理
- 后台接口调用（`/api/rag/chat`）
- 消息状态管理
- 流式输出效果实现

**核心方法：**
- `sendMessage()`: 发送消息到后台
- `streamResponse()`: 实现流式输出效果
- `handleKeyPress()`: 处理键盘事件

**接口参数：**
```json
{
  "query": "用户问题",
  "aiProvider": "deepseek",
  "topK": 1
}
```

**返回值：**
```json
{
  "answer": "AI 回复内容"
}
```

### 3. 全局样式 (`src/style.css`)
- 定义主题颜色（支持亮色/暗色模式）
- 设置全局字体和排版
- 基础组件样式重置

### 4. Vite 配置 (`vite.config.js`)
```javascript
export default defineConfig({
  plugins: [vue()],
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true,
        rewrite: (path) => path
      }
    }
  }
})
```

**配置说明：**
- 使用 `@vitejs/plugin-vue` 插件支持 Vue 单文件组件
- 配置代理解决跨域问题：将 `/api` 开头的请求转发到 `http://localhost:3000`
- `changeOrigin: true` 修改请求头的 origin 为目标地址

### 5. HTML 模板 (`index.html`)
- 页面基础结构
- 引入 Vite logo 作为 favicon
- 设置响应式 viewport
- 加载应用入口脚本

### 6. 依赖管理 (`package.json`)
```json
{
  "dependencies": {
    "vue": "^3.5.24"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^6.0.1",
    "vite": "npm:rolldown-vite@7.2.5"
  }
}
```

**特殊配置：**
- 使用 `rolldown-vite` 替代标准 Vite 以提升构建性能
- 通过 pnpm overrides 统一使用 rolldown-vite

## 快速开始

### 环境要求
- Node.js >= 16.x
- pnpm >= 8.x
- 后台服务运行在 `http://localhost:3000`

### 安装依赖

```bash
pnpm install
```

### 开发

启动开发服务器：

```bash
pnpm dev
```

开发服务器默认运行在 `http://localhost:5173`

**注意事项：**
- 确保 Vite 代理配置正确（`vite.config.js`）
- 确保后台服务正常运行
- 修改 `vite.config.js` 后需要重启开发服务器

### 构建

构建生产版本：

```bash
pnpm build
```

构建产物将输出到 `dist/` 目录。

### 预览

预览生产构建：

```bash
pnpm preview
```

## 接口说明

### 聊天接口

**地址**: `/api/rag/chat`（代理转发到 `http://localhost:3000/api/rag/chat`）

**方法**: POST

**请求头**:
```json
{
  "Content-Type": "application/json"
}
```

**请求参数**:
```json
{
  "query": "PMO技术组都有谁？",
  "aiProvider": "deepseek",
  "topK": 1
}
```

**参数说明**:
- `query`: 用户问题（必填）
- `aiProvider`: AI 提供商，可选值：deepseek、openai、anthropic
- `topK`: 检索返回的相关文档数量，范围 1-10

**返回值**:
```json
{
  "answer": "AI 回复内容"
}
```

**错误响应**:
```json
{
  "message": "错误信息"
}
```

## 跨域问题解决

开发环境使用 Vite 代理解决跨域问题：

1. 前端请求 `/api/rag/chat`
2. Vite 开发服务器代理转发到 `http://localhost:3000/api/rag/chat`
3. 后端返回数据，代理转发给前端

**生产环境注意事项**：
- 需要在后端配置 CORS
- 或使用 Nginx 等反向代理服务器

## 功能更新记录

### 版本 0.0.0
- 初始化项目结构
- 配置 Vue 3 + Vite 开发环境
- 创建基础组件和样式
- 实现计数器示例功能
- 创建 RAG 聊天页面
- 集成后台接口 `/api/rag/chat` 进行对话
- 支持选择 AI 提供商（deepseek、openai、anthropic）和 topK 参数
- 配置 Vite 代理解决跨域问题
- 实现流式输出效果（打字机式显示）

## 开发建议

### 代码风格
- 使用 `<script setup>` 语法
- 遵循 Vue 3 Composition API 最佳实践
- 组件文件使用 PascalCase 命名
- 样式文件使用 kebab-case 命名

### 性能优化
- 生产构建使用 rolldown-vite 获得更快的构建速度
- 合理使用 Vue 的响应式特性
- 避免不必要的组件重渲染

### 调试
- 使用 Vue DevTools 进行调试
- 浏览器开发者工具查看网络请求
- 控制台查看错误信息

## 注意事项

- 本项目使用 pnpm 作为包管理器，请确保已安装 pnpm
- 项目使用 rolldown-vite 作为构建工具，提供更快的构建速度
- 开发时支持热模块替换（HMR），修改代码后浏览器会自动更新
- 修改 `vite.config.js` 后需要重启开发服务器
- 确保后台服务正常运行在 `http://localhost:3000`
- 生产环境需要单独配置 CORS 或反向代理

## 故障排除

### 接口调用失败
1. 检查后台服务是否正常启动
2. 检查 `vite.config.js` 代理配置是否正确
3. 重启开发服务器
4. 查看浏览器控制台错误信息

### 样式加载异常
1. 检查 `style.css` 文件是否存在
2. 清除浏览器缓存
3. 重新启动开发服务器

### 依赖安装失败
1. 删除 `node_modules` 和 `pnpm-lock.yaml`
2. 重新运行 `pnpm install`
3. 确保网络连接正常

## 相关链接

- [Vue 3 官方文档](https://vuejs.org/)
- [Vite 官方文档](https://vite.dev/)
- [pnpm 官方文档](https://pnpm.io/)
- [@vitejs/plugin-vue 文档](https://github.com/vitejs/vite-plugin-vue)

## 许可证

本项目仅供学习和内部使用。