# 语音对话悬浮球模块

**Repository Path**: bmscj/voice-chat-floating-module

## Basic Information

- **Project Name**: 语音对话悬浮球模块
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-13
- **Last Updated**: 2025-12-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI悬浮小机器人模块

## 1. 模块简介

AI悬浮小机器人是一个可拖拽、支持语音交互的智能机器人组件，能够与AI服务进行交互，提供语音识别、AI对话等功能。该模块采用模块化设计，支持多种环境（Vue项目、小程序、Web应用），可快速集成到各种项目中。

## 2. 功能特性

### 2.1 核心功能
- ✅ 可拖拽悬浮机器人UI（支持鼠标和触摸拖动）
- ✅ 语音录音与识别
- ✅ AI对话交互
- ✅ 响应式弹窗
- ✅ 录音状态反馈
- ✅ 可配置的外观和行为

### 2.2 技术特性
- 📱 跨平台兼容（Vue、小程序、Web）
- 🎨 可定制的主题和样式
- 🎯 简单易用的API
- 🔧 模块化设计，易于扩展
- 📦 支持多种导入方式
- ⚡ 高性能，低资源占用

## 3. 目录结构

```
/robot/
├── components/           # 组件目录
│   └── FloatingRobot.vue # 悬浮机器人主组件
├── services/             # 服务目录
│   └── AIService.js      # AI服务交互
├── utils/                # 工具目录
│   └── recorder.js       # 录音功能封装
├── styles/               # 样式目录
│   └── index.scss        # 主题样式
├── index.js              # 模块入口
├── package.json          # 配置文件
└── README.md             # 说明文档
```

## 4. 安装方法

### 4.1 直接复制目录

将 `robot` 目录复制到您的项目中，然后通过相对路径引入即可。

### 4.2 支持的项目类型

- Vue 2.x 项目
- Vue 3.x 项目（兼容模式）
- uni-app 项目
- 微信小程序项目
- 普通 Web 项目

## 5. 使用示例

### 5.1 Vue组件方式（推荐）

```vue
<template>
  <div>
    <!-- 其他页面内容 -->
    <FloatingRobot 
      :api-base-url="'http://121.43.121.164:7100'"
      :bot-id="'7450776744908570662'"
      :initial-position="{ x: 100, y: 200 }"
      :config="robotConfig"
    />
  </div>
</template>

<script>
// 导入组件
import { FloatingRobot } from './robot';

export default {
  name: 'App',
  components: {
    FloatingRobot
  },
  data() {
    return {
      robotConfig: {
        imgSrc: '/static/image/airobot.gif',
        width: 80,
        height: 80,
        enableDrag: true,
        autoHidePopup: true,
        popupHideDelay: 5000
      }
    };
  }
};
</script>
```

### 5.2 全局注册

```javascript
// main.js
import Vue from 'vue';
import FloatingRobotModule from './robot';

// 全局注册组件
Vue.use(FloatingRobotModule, {
  // 全局配置选项（可选）
  apiBaseUrl: 'http://121.43.121.164:7100',
  botId: '7450776744908570662'
});

// 之后在任何组件中都可以直接使用
// <FloatingRobot />
```

### 5.3 直接使用服务

```javascript
import { AIService, Recorder } from './robot';

// 创建AI服务实例
const aiService = new AIService({
  apiBaseUrl: 'http://your-ai-server:port',
  botId: 'your-bot-id'
});

// 创建录音器实例
const recorder = new Recorder({
  format: 'm4a',
  duration: 60000,
  audioToTextUrl: 'http://your-ai-server:port/audioToText/use'
});

// 初始化AI会话
aiService.initConversation().then(conversationId => {
  console.log('会话ID:', conversationId);
});

// 发送消息到AI
aiService.chatWithAI('你好').then(response => {
  console.log('AI响应:', response);
});
```

### 5.4 直接挂载到页面（仅返回服务实例）

```javascript
import FloatingRobotModule from './robot';

// 直接挂载到页面（仅返回服务实例）
const robotInstance = FloatingRobotModule.mount({
  aiConfig: {
    apiBaseUrl: 'http://your-ai-server:port',
    botId: 'your-bot-id'
  },
  recorderConfig: {
    format: 'm4a',
    duration: 60000
  }
});

// mount方法当前仅返回服务实例，不自动创建DOM元素
console.log('AI服务实例:', robotInstance.aiService);
console.log('录音器实例:', robotInstance.recorder);
```

**注意事项：**
- `mount`方法目前仅返回AI服务和录音器实例，不自动创建DOM元素
- 建议使用Vue组件方式引入，以获得完整功能
- 当前调用mount方法会在控制台输出警告："直接挂载功能暂未实现，建议使用Vue组件方式引入"

## 6. API文档

### 6.1 FloatingRobot组件

#### 6.1.1 属性

| 属性名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| apiBaseUrl | String | '' | AI服务基础地址 |
| botId | String | '' | 机器人ID（DeepSeek API使用API Key，此参数保留用于兼容） |
| userId | Number | 1 | 用户ID |
| initialPosition | Object | { x: 0, y: 400 } | 初始位置 |
| config | Object | {} | 机器人配置 |

#### 6.1.2 Config配置项

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| imgSrc | String | '/static/image/airobot.gif' | 机器人图片路径 |
| width | Number | 80 | 机器人宽度（px） |
| height | Number | 80 | 机器人高度（px） |
| enableDrag | Boolean | true | 是否启用拖拽 |
| autoHidePopup | Boolean | true | 是否自动隐藏弹窗 |
| popupHideDelay | Number | 5000 | 弹窗自动隐藏延迟（ms） |

#### 6.1.3 方法

| 方法名 | 参数 | 返回值 | 说明 |
|--------|------|--------|------|
| getRobotState | 无 | Object | 获取机器人当前状态 |
| setRobotConfig | config: Object | 无 | 设置机器人配置 |
| sendMessage | text: String | Promise | 发送消息到AI |
| sendDefaultMessage | 无 | 无 | 发送默认消息 |
| showAIResponse | content: String | 无 | 显示AI响应弹窗 |
| closePopup | 无 | 无 | 关闭弹窗 |
| startRecording | 无 | Promise | 开始录音 |
| stopRecording | 无 | 无 | 停止录音 |

### 6.2 AIService服务

#### 6.2.1 构造函数

```javascript
const aiService = new AIService(config);
```

**配置选项：**

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| apiBaseUrl | String | '' | AI服务基础地址 |
| botId | String | '' | 机器人ID（DeepSeek API使用API Key，此参数保留用于兼容） |
| userId | Number | 1 | 用户ID |
| conversationId | String | null | 会话ID（自动初始化） |

#### 6.2.2 方法

| 方法名 | 参数 | 返回值 | 说明 |
|--------|------|--------|------|
| initConversation | 无 | Promise<String> | 初始化AI会话 |
| chatWithAI | text: String, role: String, contentType: String | Promise<Object> | 发送消息到AI |
| setConfig | newConfig: Object | 无 | 设置配置 |
| on | callbacks: Object | 无 | 设置事件回调 |
| resetConversation | 无 | 无 | 重置会话 |
| getConfig | 无 | Object | 获取当前配置 |

#### 6.2.3 事件回调

```javascript
aiService.on({
  onResponse: (response) => { /* AI响应回调 */ },
  onError: (error) => { /* 错误回调 */ },
  onConversationInit: (conversationId) => { /* 会话初始化回调 */ }
});
```

### 6.3 Recorder录音器

#### 6.3.1 构造函数

```javascript
const recorder = new Recorder(config);
```

**配置选项：**

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| format | String | 'm4a' | 录音格式 |
| duration | Number | 60000 | 最长录音时间（ms） |
| sampleRate | Number | 16000 | 采样率 |
| numberOfChannels | Number | 1 | 声道数 |
| encodeBitRate | Number | 96000 | 编码比特率 |
| audioToTextUrl | String | '' | 语音转文本URL，默认会根据apiBaseUrl自动生成 |

#### 6.3.2 方法

| 方法名 | 参数 | 返回值 | 说明 |
|--------|------|--------|------|
| start | 无 | Promise<Boolean> | 开始录音 |
| stop | 无 | 无 | 停止录音 |
| setConfig | newConfig: Object | 无 | 设置配置 |
| on | callbacks: Object | 无 | 设置事件回调 |
| getState | 无 | Object | 获取录音状态 |
| destroy | 无 | 无 | 销毁录音器 |

#### 6.3.3 事件回调

```javascript
recorder.on({
  onStart: () => { /* 录音开始回调 */ },
  onStop: (res) => { /* 录音停止回调 */ },
  onTextReceived: (text) => { /* 文本接收回调 */ },
  onError: (error) => { /* 错误回调 */ },
  onRecording: (data) => { /* 录音中回调 */ }
});
```

## 7. 实际使用场景

### 7.1 在线客服场景

**场景描述**：在电商网站或企业官网中，使用AI悬浮机器人作为在线客服，为用户提供24小时自动答疑服务。

**配置建议**：
- 设置较大的机器人尺寸（100px×100px），提高可见性
- 关闭自动隐藏弹窗，确保用户可以随时查看对话历史
- 配置醒目的主题色，与网站整体风格保持一致

**代码示例**：

```vue
<template>
  <div>
    <!-- 网站内容 -->
    <FloatingRobot 
      :api-base-url="process.env.VUE_APP_AI_API_URL"
      :bot-id="process.env.VUE_APP_AI_BOT_ID"
      :initial-position="{ x: 100, y: 200 }"
      :config="{
        imgSrc: '/static/image/customer-service-robot.gif',
        width: 100,
        height: 100,
        enableDrag: true,
        autoHidePopup: false,
        popupHideDelay: 0
      }"
    />
  </div>
</template>
```

### 7.2 智能助手场景

**场景描述**：在智能办公系统中，使用AI悬浮机器人作为个人智能助手，帮助用户管理日程、查询信息、撰写文档等。

**配置建议**：
- 设置中等尺寸的机器人（80px×80px）
- 启用自动隐藏弹窗，减少对办公界面的干扰
- 配置专业的主题色，与办公系统风格匹配

**代码示例**：

```vue
<template>
  <div>
    <!-- 办公系统内容 -->
    <FloatingRobot 
      :api-base-url="process.env.VUE_APP_AI_API_URL"
      :bot-id="process.env.VUE_APP_AI_BOT_ID"
      :initial-position="{ x: 100, y: 200 }"
      :config="{
        imgSrc: '/static/image/assistant-robot.gif',
        width: 80,
        height: 80,
        enableDrag: true,
        autoHidePopup: true,
        popupHideDelay: 10000
      }"
    />
  </div>
</template>
```

### 7.3 学习辅导场景

**场景描述**：在在线教育平台中，使用AI悬浮机器人作为学习辅导助手，为学生提供解题思路、知识点讲解、学习建议等。

**配置建议**：
- 设置友好的机器人形象，吸引学生使用
- 配置较长的弹窗隐藏延迟，确保学生有足够时间阅读解答
- 使用明亮活泼的主题色，营造轻松的学习氛围

**代码示例**：

```vue
<template>
  <div>
    <!-- 教育平台内容 -->
    <FloatingRobot 
      :api-base-url="process.env.VUE_APP_AI_API_URL"
      :bot-id="process.env.VUE_APP_AI_BOT_ID"
      :initial-position="{ x: 100, y: 200 }"
      :config="{
        imgSrc: '/static/image/teacher-robot.gif',
        width: 90,
        height: 90,
        enableDrag: true,
        autoHidePopup: true,
        popupHideDelay: 15000
      }"
    />
  </div>
</template>
```

## 8. 主题与样式

### 8.1 自定义样式

可以通过覆盖CSS变量或直接修改样式文件来自定义机器人的外观：

```scss
// 导入默认样式
@import './robot/styles/index.scss';

// 覆盖主题色
$theme-colors: (
  primary: #your-color,
  // 其他颜色...
);

// 重新编译样式
```

### 8.2 尺寸变体

```vue
<!-- 小型机器人 -->
<FloatingRobot :config="{ width: 60, height: 60 }" />

<!-- 中型机器人（默认） -->
<FloatingRobot :config="{ width: 80, height: 80 }" />

<!-- 大型机器人 -->
<FloatingRobot :config="{ width: 100, height: 100 }" />
```

## 9. 浏览器兼容性

| 浏览器 | 版本 | 支持情况 |
|--------|------|----------|
| Chrome | 60+ | ✅ 支持 |
| Firefox | 55+ | ✅ 支持 |
| Safari | 12+ | ✅ 支持 |
| Edge | 79+ | ✅ 支持 |
| IE | 11 | ❌ 不支持 |

## 10. 性能优化建议

### 10.1 懒加载机器人

在页面加载完成后延迟初始化机器人，避免影响页面初始加载速度：

```vue
<template>
  <div>
    <!-- 网站内容 -->
    <FloatingRobot 
      v-if="showRobot" 
      :api-base-url="process.env.VUE_APP_AI_API_URL"
      :bot-id="process.env.VUE_APP_AI_BOT_ID"
    />
  </div>
</template>

<script>
export default {
  data() {
    return {
      showRobot: false
    };
  },
  mounted() {
    // 页面加载完成后延迟1秒显示机器人
    setTimeout(() => {
      this.showRobot = true;
    }, 1000);
  }
};
</script>
```

### 10.2 限制机器人的使用频率

为机器人添加使用频率限制，避免频繁调用AI服务导致性能问题：

```javascript
// 在使用AIService时添加频率限制
import { AIService } from './robot';

const aiService = new AIService({
  apiBaseUrl: 'http://your-api-address:port',
  botId: 'your-actual-bot-id'
});

// 添加请求节流
let lastRequestTime = 0;
const THROTTLE_TIME = 1000; // 1秒内只能发送一次请求

async function sendMessageWithThrottle(text) {
  const now = Date.now();
  if (now - lastRequestTime < THROTTLE_TIME) {
    console.warn('请求过于频繁，请稍后再试');
    return;
  }
  lastRequestTime = now;
  
  try {
    const response = await aiService.chatWithAI(text);
    console.log('AI响应:', response);
  } catch (error) {
    console.error('发送消息失败:', error);
  }
}
```

### 10.3 优化录音功能

录音功能可能会占用较多资源，建议根据实际需求进行优化：

- 限制最长录音时间（默认60秒）
- 在录音开始前添加用户确认
- 录音完成后及时释放资源
- 仅在需要时初始化录音器

```javascript
// 优化录音器使用
import { Recorder } from './robot';

let recorder = null;

// 仅在需要时初始化录音器
function initRecorder() {
  if (!recorder) {
    recorder = new Recorder({
      format: 'm4a',
      duration: 30000, // 缩短录音时间到30秒
      sampleRate: 16000
    });
  }
  return recorder;
}

// 录音完成后释放资源
async function startRecording() {
  const recorder = initRecorder();
  await recorder.start();
}

async function stopRecording() {
  if (recorder) {
    await recorder.stop();
    // 录音完成后可以选择释放资源
    // recorder.destroy();
    // recorder = null;
  }
}
```

### 10.4 优化机器人的渲染

- 使用CSS transform替代top/left进行位置更新，减少重排
- 避免在机器人组件中使用过于复杂的动画效果
- 合理设置机器人的z-index值，避免影响页面其他元素
- 当机器人不可见时，暂停不必要的动画和轮询

## 11. 常见问题

### 11.1 为什么录音功能不能使用？

- 请检查浏览器是否支持MediaRecorder API
- 请确保已经获得麦克风权限
- 请检查录音配置是否正确

### 11.2 为什么AI没有响应？

- 请检查API地址是否正确
- 请检查网络连接是否正常
- 请检查botId是否有效
- 请查看浏览器控制台是否有错误信息

### 11.3 如何自定义机器人图片？

通过 `config` 属性的 `imgSrc` 配置项设置自定义图片路径：

```vue
<FloatingRobot :config="{ imgSrc: '/path/to/your/image.gif' }" />
```

### 11.4 URL无法访问怎么办？

如果遇到 `http://121.43.121.164:7100` 访问返回404或无法连接的问题：

- **联系服务提供商**：获取最新的API地址、端口和有效botId
- **检查本地网络**：确保网络连接正常，尝试ping或telnet测试连通性
- **使用替代AI服务**：根据项目需求选择其他可用的AI服务提供商
- **部署本地AI服务**：如果条件允许，考虑部署本地AI服务或使用开源方案

### 11.5 如何更换botId？

#### 方法1：Vue组件方式（推荐）

```vue
<template>
  <div>
    <FloatingRobot 
      :api-base-url="'http://your-api-address:port'"
      :bot-id="'your-actual-bot-id'"
      :initial-position="{ x: 100, y: 200 }"
      :config="robotConfig"
    />
  </div>
</template>
```

#### 方法2：直接使用AIService

```javascript
import { AIService } from './robot';

// 创建AI服务实例，使用自定义botId
const aiService = new AIService({
  apiBaseUrl: 'http://your-api-address:port',
  botId: 'your-actual-bot-id',
  userId: 1
});
```

#### 方法3：全局注册方式

```javascript
// main.js
import Vue from 'vue';
import FloatingRobotModule from './robot';

// 全局注册组件并配置
Vue.use(FloatingRobotModule, {
  apiBaseUrl: 'http://your-api-address:port',
  botId: 'your-actual-bot-id'
});
```

### 11.6 如何使用环境变量管理配置？

在实际项目中，建议使用环境变量管理API地址和botId，便于不同环境部署：

```vue
<template>
  <FloatingRobot 
    :api-base-url="process.env.VUE_APP_AI_API_URL"
    :bot-id="process.env.VUE_APP_AI_BOT_ID"
  />
</template>
```

### 11.7 如何添加配置验证？

建议在AIService中添加配置验证，确保API地址和botId有效：

```javascript
// robot/services/AIService.js
constructor(config = {}) {
  // 默认配置
  this.defaultConfig = {
    apiBaseUrl: 'http://121.43.121.164:7100',
    botId: '7450776744908570662',
    userId: 1,
    conversationId: null
  };
  
  // 合并配置
  this.config = { ...this.defaultConfig, ...config };
  
  // 配置验证
  this.validateConfig();
  
  // ...其他初始化代码
}

validateConfig() {
  if (!this.config.apiBaseUrl) {
    throw new Error('AI服务地址（apiBaseUrl）不能为空');
  }
  
  if (!this.config.botId) {
    throw new Error('机器人ID（botId）不能为空');
  }
  
  // 简单的URL格式验证
  try {
    new URL(this.config.apiBaseUrl);
  } catch (error) {
    throw new Error(`无效的API地址格式：${this.config.apiBaseUrl}`);
  }
}
```

## 12. 版本更新日志

### v1.0.0 (2025-12-23)

- ✨ 初始版本发布
- ✅ 实现悬浮机器人基本功能
- ✅ 支持语音录音和识别
- ✅ 支持AI对话交互
- ✅ 支持拖拽功能
- ✅ 支持响应式弹窗

## 13. 贡献指南
欢迎欢迎提交Issue和Pull Request来帮助改进这个项目！

### 13.1 贡献步骤

1. **Fork项目**：在GitHub上Fork本项目到您的账号
2. **克隆代码**：将Fork后的项目克隆到本地
3. **安装依赖**：
   ```bash
   # 安装项目依赖
   npm install
   
   # 安装演示项目依赖
   npm run demo:install
   ```
4. **运行演示项目**：
   ```bash
   npm run dev
   ```
5. **创建分支**：创建一个新的分支来开发您的功能或修复
6. **开发代码**：实现您的功能或修复
7. **测试代码**：确保您的修改不会破坏现有功能
8. **提交代码**：遵循提交规范提交您的代码
9. **创建Pull Request**：将您的修改提交到本项目