ai_chat_assistant/README.md

# AI Chat Assistant Flutter Plugin

一个功能丰富的 AI 聊天助手 Flutter 插件，专为车载系统设计，支持语音识别、AI 对话、车控命令执行、语音合成等功能。

## 📱 功能特性

- 🎤 **语音识别 (ASR)**: 支持实时语音转文字，自动停止检测
- 🤖 **AI 对话**: 基于 SSE (Server-Sent Events) 的流式 AI 对话
- 🚗 **车控命令**: 支持 20+ 种车辆控制命令（空调、车窗、车门、座椅加热等）
- 🔊 **语音合成 (TTS)**: 支持中英文语音播报
- 🎨 **精美 UI**: 浮动图标、波纹动画、渐变背景
- 📱 **多界面模式**: 支持全屏和部分屏幕聊天界面
- 🌐 **国际化**: 支持中英文切换
- 📊 **状态管理**: 基于 Provider 的状态管理

## 🏗️ 项目架构

### 📁 目录结构

```
lib/
├── app.dart                    # 主应用入口
├── main.dart                   # 程序启动入口
├── enums/                      # 枚举定义
│   ├── message_service_state.dart    # 消息服务状态
│   ├── message_status.dart           # 消息状态
│   └── vehicle_command_type.dart     # 车控命令类型
├── models/                     # 数据模型
│   ├── chat_message.dart            # 聊天消息模型
│   ├── vehicle_cmd.dart             # 车控命令模型
│   ├── vehicle_cmd_response.dart    # 车控命令响应
│   └── vehicle_status_info.dart     # 车辆状态信息
├── screens/                    # 界面页面
│   ├── full_screen.dart             # 全屏聊天界面
│   ├── main_screen.dart             # 主界面
│   └── part_screen.dart             # 部分屏聊天界面
├── services/                   # 核心服务
│   ├── audio_recorder_service.dart   # 音频录制服务
│   ├── chat_sse_service.dart         # SSE 聊天服务
│   ├── classification_service.dart   # 分类服务
│   ├── command_service.dart          # 车控命令服务
│   ├── control_recognition_service.dart # 控制识别服务
│   ├── location_service.dart         # 位置服务
│   ├── message_service.dart          # 消息管理服务
│   ├── redis_service.dart            # Redis 服务
│   ├── tts_service.dart              # 语音合成服务
│   ├── vehicle_state_service.dart    # 车辆状态服务
│   └── voice_recognition_service.dart # 语音识别服务
├── themes/                     # 主题样式
│   └── AppTheme.dart               # 应用主题定义
├── utils/                      # 工具类
│   ├── common_util.dart            # 通用工具
│   ├── tts_engine_manager.dart     # TTS 引擎管理
│   └── tts_util.dart               # TTS 工具
└── widgets/                    # UI 组件
    ├── assistant_avatar.dart       # AI 助手头像
    ├── chat_box.dart              # 聊天框
    ├── chat_bubble.dart           # 聊天气泡
    ├── chat_footer.dart           # 聊天底部
    ├── chat_header.dart           # 聊天头部
    ├── floating_icon.dart         # 浮动图标
    ├── floating_icon_with_wave.dart # 带波纹的浮动图标
    ├── gradient_background.dart    # 渐变背景
    └── large_audio_wave.dart      # 大音频波形
```

### 🎯 核心架构设计

#### 1. 服务层架构 (Services Layer)

- **MessageService**: 核心消息管理服务，负责统一管理聊天消息、语音识别、AI 对话流程
- **ChatSseService**: SSE 流式通信服务，处理与 AI 后端的实时对话
- **CommandService**: 车控命令处理服务，提供车辆控制命令的回调机制
- **TTSService**: 语音合成服务，支持中英文语音播报
- **VoiceRecognitionService**: 语音识别服务，处理音频转文字

#### 2. UI 层架构 (UI Layer)

- **浮动图标模式**: 主界面显示可拖拽的 AI 助手浮动图标
- **部分屏幕模式**: 点击图标显示简化聊天界面
- **全屏模式**: 完整的聊天界面，支持历史记录、操作按钮等

#### 3. 状态管理 (State Management)

基于 Provider 模式的响应式状态管理：
- 消息状态管理
- 语音识别状态
- AI 对话状态
- 车控命令执行状态

## 🚗 支持的车控命令

| 命令类型 | 中文描述 | 英文描述 |
|---------|---------|---------|
| lock | 上锁车门 | lock |
| unlock | 解锁车门 | unlock |
| openWindow | 打开车窗 | open window |
| closeWindow | 关闭车窗 | close window |
| appointAC | 预约空调 | appoint AC |
| openAC | 打开空调 | open AC |
| closeAC | 关闭空调 | close AC |
| changeACTemp | 修改空调温度 | change AC temperature |
| coolSharply | 极速降温 | cool sharply |
| prepareCar | 一键备车 | prepare car |
| meltSnow | 一键融雪 | melt snow |
| openTrunk | 打开后备箱 | open trunk |
| closeTrunk | 关闭后备箱 | close trunk |
| honk | 鸣笛 | honk |
| locateCar | 定位车辆 | locate car |
| openWheelHeat | 开启方向盘加热 | open wheel heat |
| closeWheelHeat | 关闭方向盘加热 | close wheel heat |
| openMainSeatHeat | 开启主座椅加热 | open main seat heat |
| closeMainSeatHeat | 关闭主座椅加热 | close main seat heat |
| openMinorSeatHeat | 开启副座椅加热 | open minor seat heat |
| closeMinorSeatHeat | 关闭副座椅加热 | close minor seat heat |

## 🔧 技术栈

### 核心依赖

- **Flutter SDK**: ^3.6.2
- **Provider**: ^6.1.5 - 状态管理
- **HTTP**: ^1.4.0 - 网络请求
- **Record**: ^6.0.0 - 音频录制
- **AudioPlayers**: ^5.2.1 - 音频播放
- **Flutter TTS**: ^4.2.0 - 语音合成
- **Permission Handler**: ^12.0.0 - 权限管理
- **UUID**: ^3.0.5 - 唯一标识符生成
- **Flutter Markdown**: ^0.7.7+1 - Markdown 渲染
- **FlutterToast**: ^8.2.12 - 消息提示
- **Path Provider**: ^2.1.5 - 文件路径管理

### 自定义包

- **basic_intl**: 基础国际化支持包

## 🚀 快速开始

### 1. 添加依赖

在您的 `pubspec.yaml` 文件中添加：

```yaml
dependencies:
  ai_chat_assistant:
    path: path/to/ai_chat_assistant
```

### 2. 权限配置

#### Android 权限 (android/app/src/main/AndroidManifest.xml)

```xml
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
```

### 3. 基础集成

```dart
import 'package:flutter/material.dart';
import 'package:ai_chat_assistant/app.dart';
import 'package:ai_chat_assistant/services/message_service.dart';
import 'package:ai_chat_assistant/enums/vehicle_command_type.dart';
import 'package:provider/provider.dart';
import 'package:permission_handler/permission_handler.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 请求麦克风权限
  if (!await Permission.microphone.isGranted) {
    await Permission.microphone.request();
  }

  // 初始化 AI Chat Assistant，注册车控命令回调
  ChatAssistantApp.initialize(
    commandCallback: (VehicleCommandType type, Map<String, dynamic>? params) async {
      // 处理车控命令的业务逻辑
      print('收到车控命令: $type, 参数: $params');
      
      // 返回执行结果
      return (true, {'message': '命令已执行'});
    },
  );

  runApp(
    ChangeNotifierProvider(
      create: (_) => MessageService(),
      child: const MyApp(),
    ),
  );
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My Car App',
      home: const ChatAssistantApp(), // 直接使用 AI 助手
    );
  }
}
```

### 4. 自定义集成

如果您想在现有应用中集成聊天助手，可以使用浮动图标：

```dart
import 'package:ai_chat_assistant/widgets/floating_icon.dart';

class MyHomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Stack(
        children: [
          // 您的现有 UI
          YourExistingWidget(),
          
          // AI 助手浮动图标
          const FloatingIcon(),
        ],
      ),
    );
  }
}
```

## 📖 示例项目

项目包含完整的示例应用，位于 `example/` 目录下：

```bash
cd example
flutter run
```

示例展示了：
- 基础集成方法
- 车控命令处理
- 自定义 UI 主题
- 权限管理

## 🎨 UI 组件

### 浮动图标 (FloatingIcon)

可拖拽的 AI 助手图标，支持：
- 拖拽定位
- 点击展开聊天界面
- 动态图标切换
- 波纹动画效果

### 聊天界面组件

- **ChatBubble**: 聊天气泡组件
- **ChatBox**: 聊天输入框
- **ChatHeader**: 聊天头部
- **ChatFooter**: 聊天底部操作栏
- **AssistantAvatar**: AI 助手头像

### 动画组件

- **FloatingIconWithWave**: 带波纹效果的浮动图标
- **LargeAudioWave**: 大音频波形动画
- **GradientBackground**: 渐变背景

## ⚙️ 配置选项

### 主题自定义

```dart
// 在 AppTheme.dart 中自定义主题
class AppTheme {
  static ThemeData get lightTheme => ThemeData(
    // 自定义浅色主题
  );
  
  static ThemeData get darkTheme => ThemeData(
    // 自定义深色主题
  );
}
```

### 资源文件

确保在 `pubspec.yaml` 中包含必要的资源：

```yaml
flutter:
  assets:
    - assets/images/
  fonts:
    - family: VWHead_Bold
      fonts:
        - asset: assets/fonts/VWHead-Bold.otf
    - family: VWHead_Regular  
      fonts:
        - asset: assets/fonts/VWHead-Regular.otf
```

## 🔌 Native 平台集成

### Android 平台

项目包含 Android 原生代码，支持：
- ASR (自动语音识别) 功能
- 原生音频处理
- 系统权限管理

### 插件架构

```yaml
plugin:
  platforms:
    android:
      package: com.example.ai_assistant_plugin
      pluginClass: AiAssistantPlugin
```

## 📝 API 文档

### MessageService

核心消息管理服务：

```dart
class MessageService extends ChangeNotifier {
  // 发送消息
  Future<void> sendMessage(String text);
  
  // 开始语音识别
  Future<void> startVoiceRecognition();
  
  // 停止语音识别
  void stopVoiceRecognition();
  
  // 获取聊天历史
  List<ChatMessage> get messages;
}
```

### CommandService

车控命令服务：

```dart
class CommandService {
  // 注册命令回调
  static void registerCallback(CommandCallback callback);
  
  // 执行车控命令
  static Future<(bool, Map<String, dynamic>?)> executeCommand(
    VehicleCommandType type, 
    {Map<String, dynamic>? params}
  );
}
```

## 🐛 调试和故障排除

### 常见问题

1. **麦克风权限问题**
   - 确保在 AndroidManifest.xml 中添加了录音权限
   - 在应用启动时请求权限

2. **网络连接问题**
   - 检查网络权限配置
   - 确认 SSE 服务端地址配置正确

3. **TTS 播放问题**
   - 检查音频播放权限
   - 确认设备支持 TTS 功能

### 日志调试

启用详细日志：

```dart
// 在 main.dart 中启用调试日志
void main() {
  debugPrint('AI Chat Assistant 启动中...');
  // ... 其他初始化代码
}
```

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

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

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🔗 相关链接

- [Flutter 官方文档](https://flutter.dev/docs)
- [Provider 状态管理](https://pub.dev/packages/provider)
- [Flutter TTS](https://pub.dev/packages/flutter_tts)
- [Record 插件](https://pub.dev/packages/record)

---

**注意**: 本插件专为车载系统设计，某些功能可能需要特定的硬件环境支持。