first commit
This commit is contained in:
383
app_car/ai_chat_assistant.md
Normal file
383
app_car/ai_chat_assistant.md
Normal file
@@ -0,0 +1,383 @@
|
||||
# AI Chat Assistant - AI 聊天助手模块文档
|
||||
|
||||
## 模块概述
|
||||
|
||||
`ai_chat_assistant` 是 OneApp 车辆模块群中的智能交互模块，提供基于人工智能的语音和文字聊天功能。该模块集成了语音识别、自然语言处理、车辆控制等技术，为用户提供智能化的车辆助手服务。
|
||||
|
||||
### 基本信息
|
||||
- **模块名称**: ai_chat_assistant
|
||||
- **模块路径**: oneapp_app_car/ai_chat_assistant
|
||||
- **类型**: Flutter Package Module
|
||||
- **主要功能**: 智能语音交互、车辆控制、自然语言问答
|
||||
|
||||
### 核心特性
|
||||
- **智能语音识别**: 集成阿里云语音识别SDK
|
||||
- **车辆智能控制**: 支持20+种车辆控制命令
|
||||
- **自然语言处理**: 基于OpenAI GPT的智能问答
|
||||
- **多语言支持**: 中英文双语交互
|
||||
- **实时流式响应**: 基于SSE的实时对话体验
|
||||
- **权限智能管理**: 自动处理麦克风等系统权限
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
ai_chat_assistant/
|
||||
├── lib/
|
||||
│ ├── ai_chat_assistant.dart # 模块入口文件
|
||||
│ ├── app.dart # 应用配置
|
||||
│ ├── manager.dart # 全局管理器
|
||||
│ ├── bloc/ # BLoC状态管理
|
||||
│ │ ├── ai_chat_cubit.dart
|
||||
│ │ ├── easy_bloc.dart
|
||||
│ │ └── command_state.dart
|
||||
│ ├── enums/ # 枚举定义
|
||||
│ │ ├── message_status.dart
|
||||
│ │ ├── message_service_state.dart
|
||||
│ │ └── vehicle_command_type.dart
|
||||
│ ├── models/ # 数据模型
|
||||
│ │ ├── chat_message.dart
|
||||
│ │ ├── vehicle_cmd.dart
|
||||
│ │ ├── vehicle_cmd_response.dart
|
||||
│ │ └── vehicle_status_info.dart
|
||||
│ ├── screens/ # 界面组件
|
||||
│ │ ├── full_screen.dart
|
||||
│ │ ├── part_screen.dart
|
||||
│ │ └── main_screen.dart
|
||||
│ ├── services/ # 业务服务层
|
||||
│ │ ├── message_service.dart
|
||||
│ │ ├── command_service.dart
|
||||
│ │ ├── chat_sse_service.dart
|
||||
│ │ └── classification_service.dart
|
||||
│ ├── utils/ # 工具类
|
||||
│ │ ├── common_util.dart
|
||||
│ │ └── tts_util.dart
|
||||
│ └── widgets/ # UI组件
|
||||
│ ├── chat_box.dart
|
||||
│ ├── chat_bubble.dart
|
||||
│ ├── assistant_avatar.dart
|
||||
│ └── floating_icon.dart
|
||||
└── pubspec.yaml # 依赖配置
|
||||
```
|
||||
|
||||
## 核心架构组件
|
||||
|
||||
### 1. 消息状态枚举 (MessageStatus)
|
||||
|
||||
```dart
|
||||
enum MessageStatus {
|
||||
normal('普通消息', 'Normal'),
|
||||
listening('聆听中', 'Listening'),
|
||||
recognizing('识别中', 'Recognizing'),
|
||||
thinking('思考中', 'Thinking'),
|
||||
completed('完成回答', 'Completed'),
|
||||
executing('执行中', 'Executing'),
|
||||
success('执行成功', 'Success'),
|
||||
failure('执行失败', 'Failure'),
|
||||
aborted('已中止', 'Aborted');
|
||||
|
||||
const MessageStatus(this.chinese, this.english);
|
||||
final String chinese;
|
||||
final String english;
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 车辆控制命令枚举 (VehicleCommandType)
|
||||
|
||||
```dart
|
||||
enum VehicleCommandType {
|
||||
unknown('未知', 'unknown'),
|
||||
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');
|
||||
|
||||
const VehicleCommandType(this.chinese, this.english);
|
||||
final String chinese;
|
||||
final String english;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 聊天消息模型 (ChatMessage)
|
||||
|
||||
```dart
|
||||
class ChatMessage {
|
||||
final String id;
|
||||
final String text;
|
||||
final bool isUser;
|
||||
final DateTime timestamp;
|
||||
MessageStatus status;
|
||||
|
||||
ChatMessage({
|
||||
required this.id,
|
||||
required this.text,
|
||||
required this.isUser,
|
||||
required this.timestamp,
|
||||
this.status = MessageStatus.normal,
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## 核心服务类
|
||||
|
||||
### 1. 消息服务 (MessageService)
|
||||
|
||||
MessageService是AI聊天助手的核心服务，采用单例模式，负责管理整个对话流程：
|
||||
|
||||
```dart
|
||||
class MessageService extends ChangeNotifier {
|
||||
static MessageService? _instance;
|
||||
static MessageService get instance => _instance ??= MessageService._internal();
|
||||
factory MessageService() => instance;
|
||||
|
||||
// 核心方法
|
||||
Future<void> startVoiceInput() async
|
||||
Future<void> stopAndProcessVoiceInput() async
|
||||
Future<void> reply(String text) async
|
||||
Future<void> handleVehicleControl(String text, bool isChinese) async
|
||||
Future<bool> processCommand(VehicleCommand command, bool isChinese) async
|
||||
}
|
||||
```
|
||||
|
||||
**主要功能模块:**
|
||||
|
||||
#### 语音交互流程
|
||||
1. **录音开始**: `startVoiceInput()` - 检查麦克风权限，开启阿里云ASR
|
||||
2. **录音识别**: `stopAndProcessVoiceInput()` - 停止录音并获取识别结果
|
||||
3. **文本分类**: 通过 `TextClassificationService` 判断用户意图
|
||||
4. **响应生成**: 根据分类结果调用相应处理方法
|
||||
|
||||
#### 消息状态管理
|
||||
- **listening**: 正在聆听用户语音输入
|
||||
- **recognizing**: 语音识别中
|
||||
- **thinking**: AI思考回复中
|
||||
- **executing**: 车辆控制命令执行中
|
||||
- **completed**: 对话完成
|
||||
|
||||
#### 车辆控制处理
|
||||
```dart
|
||||
Future<void> handleVehicleControl(String text, bool isChinese) async {
|
||||
final vehicleCommandResponse = await _vehicleCommandService.getCommandFromText(text);
|
||||
if (vehicleCommandResponse != null) {
|
||||
// 更新消息状态为执行中
|
||||
replaceMessage(id: _latestAssistantMessageId!,
|
||||
text: vehicleCommandResponse.tips!,
|
||||
status: MessageStatus.executing);
|
||||
|
||||
// 执行车辆控制命令
|
||||
for (var command in vehicleCommandResponse.commands) {
|
||||
if (command.type != VehicleCommandType.unknown && command.error.isEmpty) {
|
||||
bool isSuccess = await processCommand(command, isChinese);
|
||||
// 处理执行结果
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. BLoC状态管理 (AIChatCommandCubit)
|
||||
|
||||
```dart
|
||||
class AIChatCommandCubit extends EasyCubit<AIChatCommandState> {
|
||||
AIChatCommandCubit() : super(const AIChatCommandState());
|
||||
|
||||
void reset() {
|
||||
emit(const AIChatCommandState());
|
||||
}
|
||||
|
||||
String _generateCommandId() {
|
||||
return '${DateTime.now().millisecondsSinceEpoch}_${state.commandType?.name ?? 'unknown'}';
|
||||
}
|
||||
|
||||
bool get isExecuting => state.status == AIChatCommandStatus.executing;
|
||||
String? get currentCommandId => state.commandId;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 主屏幕界面 (MainScreen)
|
||||
|
||||
```dart
|
||||
class MainScreen extends StatefulWidget {
|
||||
const MainScreen({super.key});
|
||||
|
||||
@override
|
||||
State<MainScreen> createState() => _MainScreenState();
|
||||
}
|
||||
|
||||
class _MainScreenState extends State<MainScreen> {
|
||||
@override
|
||||
Widget build(BuildContext context) {
|
||||
return Scaffold(
|
||||
backgroundColor: Colors.transparent,
|
||||
body: Stack(
|
||||
children: [
|
||||
Container(
|
||||
decoration: const BoxDecoration(
|
||||
image: DecorationImage(
|
||||
image: AssetImage('assets/images/bg.jpg', package: 'ai_chat_assistant'),
|
||||
fit: BoxFit.cover,
|
||||
),
|
||||
),
|
||||
),
|
||||
FloatingIcon(), // 浮动聊天入口
|
||||
],
|
||||
),
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 技术集成
|
||||
|
||||
### 阿里云语音识别集成
|
||||
```dart
|
||||
// 方法通道配置
|
||||
static const MethodChannel _asrChannel = MethodChannel('com.example.ai_chat_assistant/ali_sdk');
|
||||
|
||||
// ASR回调处理
|
||||
Future<dynamic> _handleMethodCall(MethodCall call) async {
|
||||
switch (call.method) {
|
||||
case "onAsrResult":
|
||||
replaceMessage(id: _latestUserMessageId!,
|
||||
text: call.arguments,
|
||||
status: MessageStatus.normal);
|
||||
break;
|
||||
case "onAsrStop":
|
||||
if (_asrCompleter != null && !_asrCompleter!.isCompleted) {
|
||||
_asrCompleter!.complete(messages.last.text);
|
||||
}
|
||||
break;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 权限管理
|
||||
```dart
|
||||
Future<void> startVoiceInput() async {
|
||||
if (await Permission.microphone.status == PermissionStatus.denied) {
|
||||
PermissionStatus status = await Permission.microphone.request();
|
||||
if (status == PermissionStatus.permanentlyDenied) {
|
||||
await Fluttertoast.showToast(msg: "请在设置中开启麦克风权限");
|
||||
}
|
||||
return;
|
||||
}
|
||||
// 继续语音输入流程
|
||||
}
|
||||
```
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 1. 模块导入
|
||||
```dart
|
||||
import 'package:ai_chat_assistant/ai_chat_assistant.dart';
|
||||
```
|
||||
|
||||
### 2. 服务初始化
|
||||
```dart
|
||||
// 获取消息服务实例
|
||||
final messageService = MessageService.instance;
|
||||
|
||||
// 监听消息变化
|
||||
messageService.addListener(() {
|
||||
// 处理消息更新
|
||||
});
|
||||
```
|
||||
|
||||
### 3. 语音交互
|
||||
```dart
|
||||
// 开始语音输入
|
||||
await messageService.startVoiceInput();
|
||||
|
||||
// 停止并处理语音输入
|
||||
await messageService.stopAndProcessVoiceInput();
|
||||
```
|
||||
|
||||
### 4. 文本交互
|
||||
```dart
|
||||
// 直接发送文本消息
|
||||
await messageService.reply("帮我打开空调");
|
||||
```
|
||||
|
||||
## 依赖配置
|
||||
|
||||
### pubspec.yaml 关键依赖
|
||||
```yaml
|
||||
dependencies:
|
||||
flutter:
|
||||
sdk: flutter
|
||||
# 状态管理
|
||||
provider: ^6.0.0
|
||||
|
||||
# 权限管理
|
||||
permission_handler: ^10.0.0
|
||||
|
||||
# 网络请求
|
||||
dio: ^5.0.0
|
||||
|
||||
# 提示消息
|
||||
fluttertoast: ^8.0.0
|
||||
|
||||
# UUID生成
|
||||
uuid: ^3.0.0
|
||||
|
||||
# 国际化
|
||||
basic_intl:
|
||||
path: ../../oneapp_basic_utils/basic_intl
|
||||
```
|
||||
|
||||
## 扩展开发指南
|
||||
|
||||
### 1. 新增车辆控制命令
|
||||
|
||||
1. 在 `VehicleCommandType` 枚举中添加新命令：
|
||||
```dart
|
||||
enum VehicleCommandType {
|
||||
// 现有命令...
|
||||
newCommand('新命令', 'new command'),
|
||||
}
|
||||
```
|
||||
|
||||
2. 在 `MessageService.processCommand` 中添加处理逻辑。
|
||||
|
||||
### 2. 自定义对话界面
|
||||
|
||||
继承或修改现有的Screen组件，实现自定义的对话界面布局。
|
||||
|
||||
### 3. 集成其他AI服务
|
||||
|
||||
通过修改 `ChatSseService` 或新增服务类，可以集成其他AI对话服务。
|
||||
|
||||
## 性能优化建议
|
||||
|
||||
1. **内存管理**: MessageService使用单例模式，注意在适当时机清理消息历史
|
||||
2. **网络优化**: SSE连接在不使用时应及时断开
|
||||
3. **权限缓存**: 避免重复请求已获取的权限
|
||||
4. **语音资源**: 及时释放语音录制和播放资源
|
||||
|
||||
## 问题排查
|
||||
|
||||
### 常见问题
|
||||
1. **语音识别失效**: 检查麦克风权限和阿里云SDK配置
|
||||
2. **车辆控制失败**: 确认车辆连接状态和控制权限
|
||||
3. **SSE连接断开**: 检查网络状态和服务端配置
|
||||
|
||||
### 调试技巧
|
||||
- 启用详细日志输出
|
||||
- 使用Flutter Inspector检查Widget状态
|
||||
- 通过MethodChannel调试原生交互
|
||||
Reference in New Issue
Block a user