小玄智能平台

基于 Vue 3 + TypeScript 的现代化 AI 智能交互平台

集成 Live2D 虚拟形象 · 智能对话系统 · 设备管理 · Agent 中心

快速开始 · 功能特性 · 开发指南 · 部署文档

---

📖 目录

• 项目简介
• 核心亮点
• 功能特性
• 技术栈
• 快速开始
• 项目结构
• 环境配置
• 开发指南
• 部署指南
• 常见问题
• 更新日志

---

💡 项目简介

小玄智能平台 是一个基于 Vue 3 + TypeScript 构建的现代化智能交互平台。项目集成了 Live2D 虚拟形象、AI 智能对话、设备管理等功能,采用响应式设计,完美支持桌面端和移动端访问。

项目规模

• 代码行数: 50,000+ 行
• 文件数量: 1,000+ 文件
• 核心页面: 15+ 页面组件
• API 接口: 30+ 接口

---

✨ 核心亮点

• 🎨 现代化 UI 设计 - 精美的粉蓝渐变主题,优雅流畅的用户体验
• 🤖 Live2D 虚拟形象 - 基于 PixiJS 的高性能 2D 虚拟角色渲染,支持 26 种情感表达
• 💬 智能对话系统 - AI 驱动的实时对话,支持上下文理解与情感交互
• 🎙️ 语音交互 - 集成语音识别与 TTS 语音播放,提供自然的语音交互体验
• 📱 移动端优化 - 完整的移动端适配,支持触摸操作,自适应布局
• 🔐 安全认证 - JWT Token 认证,自动刷新机制,登录过期自动跳转
• ⚡ 性能优化 - 代码分割、懒加载、资源压缩,虚拟滚动优化长列表

---

🎯 功能特性

用户系统

• ✅ 用户注册/登录 (手机号/邮箱)
• ✅ 密码找回与重置
• ✅ 个人中心管理
• ✅ 头像上传
• ✅ Token 自动刷新
• ✅ 登录状态保持

智能交互

• ✅ AI 实时对话
• ✅ Live2D 虚拟形象展示
• ✅ 26 种情感表达动作
• ✅ 语音识别 (STT)
• ✅ 语音播放 (TTS)
• ✅ Markdown 消息渲染
• ✅ 消息分段显示
• ✅ 聊天历史记录

设备管理

• ✅ 设备列表查看
• ✅ 设备绑定 (扫码/手动)
• ✅ 设备解绑
• ✅ 远程设备控制
• ✅ 设备信息查看

Agent 中心

• ✅ Agent 创建
• ✅ Agent 管理 (编辑/删除)
• ✅ Agent 对话交互
• ✅ 情感配置

其他功能

• ✅ 社区广场
• ✅ 商城系统
• ✅ 多端适配 (桌面端/移动端)

---

🛠️ 技术栈

前端框架

技术	版本	说明
Vue.js	3.5.22	渐进式 JavaScript 框架
TypeScript	5.9.3	JavaScript 的类型安全超集
Vite	7.1.12	下一代前端构建工具
Vue Router	4.6.3	Vue.js 官方路由管理器

核心依赖

技术	版本	用途
Axios	1.13.1	HTTP 客户端
PixiJS	6.5.10	2D WebGL 渲染引擎
pixi-live2d-display	0.4.0	Live2D 模型渲染库
marked	17.0.0	Markdown 解析器
vue-virtual-scroller	2.0.0-beta.8	虚拟滚动组件

开发工具

• 构建工具: Vite
• 代码压缩: Terser
• CSS 处理: Autoprefixer
• 类型检查: vue-tsc
• 开发服务器: 支持 HTTPS

---

🚀 快速开始

环境要求

• Node.js: >= 16.x
• npm: >= 8.x (或使用 yarn/pnpm)
• 浏览器: Chrome/Firefox/Safari/Edge (最新版本)

安装步骤

1. 克隆项目

git clone <repository-url>
cd X0001-web

2. 安装依赖

npm install

3. 配置环境变量

# 复制环境变量模板
cp .env.example .env.development

# 编辑 .env.development 文件,配置必要的环境变量

4. 启动开发服务器

npm run dev

5. 访问应用

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

HTTPS 开发环境 (可选)

如需启用 HTTPS,运行证书生成脚本:

Windows (PowerShell):

.\generate-cert.ps1

Linux/macOS:

chmod +x generate-cert.sh
./generate-cert.sh

生成证书后重启开发服务器,访问: https://localhost:5173

---

📁 项目结构

X0001-web/
├── public/                   # 静态资源
│   └── live2d/              # Live2D 模型文件
│       └── xuan9.0/         # 小玄 9.0 模型
├── src/                     # 源代码
│   ├── api/                 # API 服务层
│   │   ├── config.ts       # API 配置
│   │   ├── request.ts      # Axios 封装
│   │   ├── userService.ts  # 用户接口
│   │   ├── deviceService.ts # 设备接口
│   │   ├── sessionService.ts # 会话接口
│   │   └── agentService.ts # Agent 接口
│   ├── components/          # 公共组件
│   │   ├── Live2DPanel.vue # Live2D 渲染组件
│   │   ├── AudioPlayer.vue # 音频播放器
│   │   ├── VoiceRecorder.vue # 语音录制器
│   │   └── CyberBackground.vue # 赛博背景
│   ├── views/               # 页面组件
│   │   ├── Login.vue       # 登录页
│   │   ├── Register.vue    # 注册页
│   │   ├── Dashboard.vue   # 桌面端主页
│   │   ├── DashboardMobile.vue # 移动端主页
│   │   ├── Chat.vue        # 桌面端对话
│   │   ├── ChatMobile.vue  # 移动端对话
│   │   ├── DeviceCenter.vue # 设备中心
│   │   ├── Matrix.vue      # Agent 中心
│   │   ├── MatrixMobile.vue # 移动端 Agent
│   │   ├── Profile.vue     # 个人中心
│   │   ├── Community.vue   # 社区
│   │   ├── Mall.vue        # 商城
│   │   └── NotFound.vue    # 404 页面
│   ├── router/              # 路由配置
│   │   └── index.ts        # 路由定义
│   ├── utils/               # 工具函数
│   │   ├── errorHandler.ts # 错误处理
│   │   ├── enhancedErrorHandler.ts # 增强错误处理
│   │   ├── errorCodes.ts   # 错误码映射
│   │   ├── authGuard.ts    # 路由守卫
│   │   ├── messageSegmenter.ts # 消息分段
│   │   ├── voiceRecorder.ts # 语音录制
│   │   └── speechRecognition.ts # 语音识别
│   ├── composables/         # 组合式函数
│   │   └── useCyberTheme.ts # 赛博主题
│   ├── config/              # 配置文件
│   │   └── live2d.ts       # Live2D 配置
│   ├── types/               # TypeScript 类型定义
│   │   └── index.ts        # 全局类型
│   ├── styles/              # 全局样式
│   │   └── global.css      # 全局 CSS
│   ├── App.vue              # 根组件
│   └── main.ts              # 应用入口
├── docs/                    # 文档目录
│   ├── 用户协议.md          # 用户协议
│   ├── 隐私政策.md          # 隐私政策
│   └── 情感映射关系表.md    # Live2D 情感系统文档
├── .env.development         # 开发环境配置
├── .env.production          # 生产环境配置
├── .env.example             # 环境变量模板
├── vite.config.ts           # Vite 配置
├── tsconfig.json            # TypeScript 配置
├── package.json             # 项目配置
└── README.md                # 项目说明

---

⚙️ 环境配置

环境变量说明

创建 .env.development 和 .env.production 文件,配置以下变量:

变量名	说明	示例值	必填
VITE_API_BASE_URL	后端 API 地址	http://www.xuanxiaotech.cc:8950	✅
VITE_WS_URL	WebSocket 地址	wss://www.xuanxiaotech.cc/ws/frontend	✅
VITE_LIVE2D_MODEL_URL	Live2D 模型路径	/live2d/xuan9.0/xuan9.0.model3.json	✅
VITE_APP_TITLE	应用标题	小玄智能平台	❌
VITE_APP_VERSION	应用版本号	1.0.0	❌
VITE_API_TIMEOUT	API 请求超时时间(ms)	10000	❌
VITE_DEBUG	是否启用调试模式	true / false	❌

开发环境配置示例

.env.development:

VITE_API_BASE_URL=
VITE_WS_URL=wss://www.xuanxiaotech.cc/ws/frontend
VITE_LIVE2D_MODEL_URL=/live2d/xuan9.0/xuan9.0.model3.json
VITE_APP_TITLE=小玄智能平台
VITE_APP_VERSION=1.0.0
VITE_API_TIMEOUT=10000
VITE_DEBUG=true

生产环境配置示例

.env.production:

VITE_API_BASE_URL=https://api.production.com
VITE_WS_URL=wss://www.xuanxiaotech.cc/ws/frontend
VITE_LIVE2D_MODEL_URL=/live2d/xuan9.0/xuan9.0.model3.json
VITE_APP_TITLE=小玄智能平台
VITE_APP_VERSION=1.0.0
VITE_API_TIMEOUT=10000
VITE_DEBUG=false

---

💻 开发指南

开发命令

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 类型检查
npm run type-check

# 构建生产版本
npm run build

# 预览生产构建
npm run preview

代码规范

• 使用 TypeScript 编写代码
• 遵循 Vue 3 Composition API 风格
• 组件命名采用 PascalCase
• 文件命名采用 camelCase 或 kebab-case
• 添加必要的类型注释和 JSDoc 注释

添加新页面

1. 在 src/views/ 创建页面组件:

<!-- src/views/NewPage.vue -->
<template>
  <div class="new-page">
    <h1>新页面</h1>
  </div>
</template>

<script setup lang="ts">
// 页面逻辑
</script>

<style scoped>
.new-page {
  /* 样式 */
}
</style>

2. 在 src/router/index.ts 添加路由:

{
  path: '/new-page',
  name: 'NewPage',
  component: () => import('@/views/NewPage.vue'),
  meta: { requiresAuth: true } // 是否需要登录
}

添加新 API

1. 在 src/api/ 创建服务文件:

// src/api/newService.ts
import request from './request'

export const newService = {
  getData: () => request.get('/api/data'),
  postData: (data: any) => request.post('/api/data', data)
}

2. 在组件中使用:

import { newService } from '@/api/newService'

const fetchData = async () => {
  try {
    const response = await newService.getData()
    console.log(response.data)
  } catch (error) {
    console.error('请求失败:', error)
  }
}

Live2D 集成

使用 Live2D 组件:

<template>
  <Live2DPanel
    :model-url="modelUrl"
    :width="800"
    :height="600"
    @model-loaded="onModelLoaded"
  />
</template>

<script setup lang="ts">
import Live2DPanel from '@/components/Live2DPanel.vue'

const modelUrl = '/live2d/xuan9.0/xuan9.0.model3.json'

const onModelLoaded = () => {
  console.log('Live2D 模型加载完成')
}
</script>

错误处理

项目使用增强的错误处理系统:

import { enhancedErrorHandler } from '@/utils/enhancedErrorHandler'

try {
  const response = await api.someRequest()
} catch (error) {
  const errorCode = enhancedErrorHandler.handleNetworkError(
    error, 
    { component: 'ComponentName', action: 'doSomething' }
  )
  console.error('错误:', errorCode.message)
}

---

📦 部署指南

构建项目

npm run build

构建产物位于 dist/ 目录。

部署到 Nginx

1. 上传文件

将 dist/ 目录下的所有文件上传到服务器。

2. 配置 Nginx

server {
    listen 80;
    server_name your-domain.com;
    root /path/to/dist;
    index index.html;

    # Gzip 压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml;
    gzip_comp_level 6;
    gzip_min_length 1000;

    # SPA 路由支持
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 代理
    location /api {
        proxy_pass http://backend-server:8950;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

3. HTTPS 配置 (推荐)

server {
    listen 443 ssl http2;
    server_name your-domain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    
    # 其他配置同上
}

# HTTP 重定向到 HTTPS
server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

Docker 部署

1. 创建 Dockerfile

# 构建阶段
FROM node:16-alpine as build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# 生产阶段
FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

2. 构建镜像

docker build -t xiaoxuan-web:latest .

3. 运行容器

docker run -d -p 80:80 --name xiaoxuan-web xiaoxuan-web:latest

性能优化建议

• ✅ 启用 Gzip/Brotli 压缩
• ✅ 配置静态资源缓存
• ✅ 使用 CDN 加速静态资源
• ✅ 启用 HTTP/2
• ✅ 配置 HTTPS
• ✅ 优化图片资源 (WebP 格式)
• ✅ 使用懒加载加载路由和组件

---

❓ 常见问题

Q: 如何解决 CORS 跨域问题？

A: 开发环境已在 vite.config.ts 中配置代理。生产环境需要在后端配置 CORS 或使用 Nginx 反向代理。

Q: Live2D 模型加载失败怎么办？

A:

1. 检查模型文件路径是否正确
2. 确认 public/live2d/ 目录下有对应的模型文件
3. 查看浏览器控制台是否有错误信息
4. 检查 .env 文件中的 VITE_LIVE2D_MODEL_URL 配置

Q: 登录后刷新页面为什么会退出登录？

A:

1. 检查 Token 是否正确存储在 localStorage
2. 确认路由守卫逻辑是否正确
3. 查看 Token 是否过期

Q: 如何启用 HTTPS 开发环境？

A: 运行 ./generate-cert.ps1 (Windows) 或 ./generate-cert.sh (Linux/macOS) 生成证书,然后重启开发服务器。

Q: 构建后部署访问 404？

A:

1. 确保服务器配置了 SPA 路由回退 (所有路由返回 index.html)
2. 检查 vite.config.ts 中的 base 配置是否正确
3. Nginx 需要配置 try_files $uri $uri/ /index.html;

Q: 如何调试生产环境的错误？

A:

1. 在 .env.production 中设置 VITE_DEBUG=true
2. 在 vite.config.ts 中启用 sourcemap: build.sourcemap = true
3. 使用浏览器开发者工具查看网络请求和控制台日志

---

📝 更新日志

v1.0.0 (2025-12-02)

新增功能

• ✨ 完整的用户认证系统 (登录、注册、密码找回)
• ✨ Live2D 虚拟形象集成
• ✨ AI 智能对话功能
• ✨ 设备管理中心
• ✨ Agent 创建与管理
• ✨ 移动端完整适配
• ✨ 语音识别与播放 (STT/TTS)
• ✨ 情感表达系统 (26 种情感)
• ✨ Markdown 消息渲染
• ✨ 虚拟滚动优化

优化改进

• ⚡ 代码分割与懒加载优化
• ⚡ 构建产物压缩与优化
• ⚡ 增强的错误处理机制
• ⚡ 登录过期自动跳转
• ⚡ 统一的错误码映射系统
• ⚡ Token 自动刷新机制
• 🎨 粉蓝渐变主题设计
• 📱 响应式布局优化

修复问题

• 🐛 修复密码错误提示显示"未知错误"的问题
• 🐛 修复 ICP 备案号显示样式问题
• 🐛 修复登录过期跳转逻辑
• 🐛 修复移动端键盘弹出时布局错位
• 🐛 修复 Safari 兼容性问题

---

📄 许可证

本项目采用 MIT License 开源协议。

MIT License

Copyright (c) 2025 小玄智能平台

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

🤝 贡献指南

欢迎贡献代码！请遵循以下步骤:

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

---

📞 联系方式

• 官方网站: https://www.xuanxiaotech.cc
• ICP备案: 粤ICP备2025488753号-5

---

⭐ 如果这个项目对你有帮助,请给一个 Star!

Made with ❤️ by 小玄智能平台团队