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                    # 主应用入口
├── manager.dart                # AI 聊天助手管理器
├── ai_chat_assistant.dart      # 导出文件
├── bloc/                       # 状态管理
│   ├── easy_bloc.dart             # 自定义轻量级状态管理框架
│   ├── ai_chat_cubit.dart         # AI 聊天命令状态管理
│   └── command_state.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     # 车辆状态信息
├── pages/                      # 页面
│   └── full_screen.dart             # 全屏聊天页面
├── screens/                    # 界面页面
│   ├── main_screen.dart             # 主界面
│   └── part_screen.dart             # 部分屏聊天界面
├── services/                   # 核心服务
│   ├── 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/                      # 工具类
│   ├── assets_util.dart            # 资源工具
│   ├── common_util.dart            # 通用工具
│   ├── tts_engine_manager.dart     # TTS 引擎管理
│   └── tts_util.dart               # TTS 工具
└── widgets/                    # UI 组件
    ├── chat/                       # 聊天相关组件
    │   └── chat_window_content.dart   # 聊天窗口内容
    ├── assistant_avatar.dart       # AI 助手头像
    ├── chat_box.dart              # 聊天框
    ├── chat_bubble.dart           # 聊天气泡
    ├── chat_floating_icon.dart    # 聊天浮动图标
    ├── chat_footer.dart           # 聊天底部
    ├── chat_header.dart           # 聊天头部
    ├── chat_popup.dart            # 聊天弹出层
    ├── floating_icon.dart         # 浮动图标
    ├── floating_icon_with_wave.dart # 带波纹的浮动图标
    ├── gradient_background.dart    # 渐变背景
    ├── large_audio_wave.dart      # 大音频波形
    ├── mini_audio_wave.dart       # 小音频波形
    ├── rotating_image.dart        # 旋转图片组件
    ├── voice_animation.dart       # 语音动画
    └── _hole_overlay.dart         # 洞穴遮罩层
```

### 🎯 核心架构设计

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

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

#### 2. 状态管理架构 (State Management)

- **EasyBloc**: 轻量级状态管理框架，支持事件驱动和状态流
- **EasyCubit**: 简化的状态管理，用于单一状态变更
- **AIChatCommandCubit**: 专门处理车控命令的状态管理
- **MessageService**: 基于Provider的消息状态管理

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

- **ChatPopup**: 主要的聊天弹出层组件，集成浮动图标和聊天窗口
- **ChatFloatingIcon**: 可拖拽的浮动图标
- **ChatWindowContent**: 聊天窗口内容组件
- **全屏模式**: 完整的聊天界面，支持历史记录、操作按钮等

#### 4. 管理器模式 (Manager Pattern)

- **AIChatAssistantManager**: 单例管理器，负责整体协调
- **VehicleCommandHandler**: 抽象的车控命令处理器，支持自定义实现

## 🚗 支持的车控命令

| 命令类型 | 中文描述 | 英文描述 |
|---------|---------|---------|
| 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.5.0
- **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 - 文件路径管理
- **Meta**: ^1.15.0 - 元数据注解

### 自定义包

- **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/ai_chat_assistant.dart';
import 'package:provider/provider.dart';
import 'package:permission_handler/permission_handler.dart';

// 实现车控命令处理器
class MyVehicleCommandHandler extends VehicleCommandHandler {
  @override
  Future<(bool, Map<String, dynamic>?)> executeCommand(VehicleCommand command) async {
    // 处理车控命令的业务逻辑
    print('收到车控命令: ${command.type}, 参数: ${command.params}');
    
    // 更新命令状态为执行中
    commandCubit?.emit(AIChatCommandState(
      commandId: command.commandId,
      commandType: command.type,
      params: command.params,
      status: AIChatCommandStatus.executing,
      timestamp: DateTime.now(),
    ));
    
    // 模拟命令执行
    await Future.delayed(const Duration(seconds: 2));
    
    // 更新命令状态为成功
    commandCubit?.emit(AIChatCommandState(
      commandId: command.commandId,
      commandType: command.type,
      params: command.params,
      status: AIChatCommandStatus.success,
      timestamp: DateTime.now(),
      result: {'message': '命令执行成功'},
    ));
    
    // 返回执行结果
    return (true, {'message': '命令已执行'});
  }
}

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

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

  // 初始化 AI Chat Assistant，注册车控命令处理器
  AIChatAssistantManager.instance.setupCommandHandle(
    commandHandler: MyVehicleCommandHandler(),
  );

  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/chat_popup.dart';

class MyHomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Stack(
        children: [
          // 您的现有 UI
          YourExistingWidget(),
          
          // AI 助手聊天弹出层
          const ChatPopup(),
        ],
      ),
    );
  }
}
```

## 📖 示例项目

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

```bash
cd example
flutter run
```

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

## 🎨 UI 组件

### 聊天弹出层 (ChatPopup)

集成式聊天弹出层组件，包含：
- 浮动图标 (ChatFloatingIcon)
- 聊天窗口 (ChatWindowContent)
- 拖拽定位
- 动画效果

### 浮动图标相关组件

- **ChatFloatingIcon**: 专用聊天浮动图标
- **FloatingIcon**: 通用浮动图标
- **FloatingIconWithWave**: 带波纹效果的浮动图标

### 聊天界面组件

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

### 动画组件

- **VoiceAnimation**: 语音动画组件
- **LargeAudioWave**: 大音频波形动画
- **MiniAudioWave**: 小音频波形动画
- **RotatingImage**: 旋转图片组件
- **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 (自动语音识别) 功能，基于阿里云SDK
- 原生音频处理
- 系统权限管理

### 阿里云SDK集成

使用阿里云语音识别SDK，配置文件在：
- `android/libs/nui-release-1.0.0.aar`
- `android/libs/fastjson-1.1.46.android.jar`

### 插件架构

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

## 📝 API 文档

### AIChatAssistantManager

核心管理器（单例模式）：

```dart
class AIChatAssistantManager {
  static final instance = AIChatAssistantManager._internal();
  
  // 设置命令处理器
  void setupCommandHandle({required VehicleCommandHandler commandHandler});
  
  // 获取命令状态流
  Stream<AIChatCommandState> get commandStateStream;
}
```

### VehicleCommandHandler

车控命令处理器抽象类：

```dart
abstract class VehicleCommandHandler {
  AIChatCommandCubit? commandCubit;
  
  // 执行车辆控制命令
  Future<(bool, Map<String, dynamic>?)> executeCommand(VehicleCommand command);
}
```

### MessageService

核心消息管理服务：

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

### EasyBloc / EasyCubit

轻量级状态管理框架：

```dart
// 基于事件的状态管理
class MyBloc extends EasyBloc<MyEvent, MyState> {
  MyBloc(MyState initialState) : super(initialState);
  
  @override
  void _mapEventToState(MyEvent event) {
    // 处理事件并发射新状态
  }
}

// 简化的状态管理
class MyCubit extends EasyCubit<MyState> {
  MyCubit(MyState initialState) : super(initialState);
  
  void updateState(MyState newState) {
    emit(newState);
  }
}
```

## 🐛 调试和故障排除

### 常见问题

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

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

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

### 日志调试

启用详细日志：

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

## 📄 许可证

本项目采用 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)
- [阿里云语音识别SDK](https://ai.aliyun.com/nls)

## 📋 更新日志

### v1.0.0+1 (2025-09-23)

#### 新增功能
- 🎯 新增轻量级状态管理框架 (EasyBloc/EasyCubit)
- 🔧 新增 AIChatAssistantManager 单例管理器
- 📦 新增 ChatPopup 集成组件
- 🎨 新增多个动画组件 (VoiceAnimation, MiniAudioWave, RotatingImage 等)
- 💾 集成阿里云语音识别SDK

#### 架构改进
- 🏗️ 采用管理器模式替代回调模式
- 🔄 支持面向对象的车控命令处理器
- 📱 优化聊天界面组件结构
- 🎵 改进语音识别和TTS服务

#### 技术栈更新
- 🔧 添加 Meta 注解支持
- 🌐 保持与 basic_intl 国际化包的兼容