535 lines
16 KiB
Markdown
535 lines
16 KiB
Markdown
# 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 启动中...');
|
||
// ... 其他初始化代码
|
||
}
|
||
```
|
||
|
||
## 🤝 贡献指南
|
||
|
||
欢迎提交 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)
|
||
- [阿里云语音识别SDK](https://ai.aliyun.com/nls)
|
||
|
||
## 📋 更新日志
|
||
|
||
### v1.0.0+1 (2025-09-23)
|
||
|
||
#### 新增功能
|
||
- 🎯 新增轻量级状态管理框架 (EasyBloc/EasyCubit)
|
||
- 🔧 新增 AIChatAssistantManager 单例管理器
|
||
- 📦 新增 ChatPopup 集成组件
|
||
- 🎨 新增多个动画组件 (VoiceAnimation, MiniAudioWave, RotatingImage 等)
|
||
- 💾 集成阿里云语音识别SDK
|
||
|
||
#### 架构改进
|
||
- 🏗️ 采用管理器模式替代回调模式
|
||
- 🔄 支持面向对象的车控命令处理器
|
||
- 📱 优化聊天界面组件结构
|
||
- 🎵 改进语音识别和TTS服务
|
||
|
||
#### 技术栈更新
|
||
- 📦 Flutter SDK 升级到 ^3.5.0
|
||
- 🔧 添加 Meta 注解支持
|
||
- 🌐 保持与 basic_intl 国际化包的兼容
|