AI_POC/ai_chat_assistant
11
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

UPDATE README

Browse Source
This commit is contained in:
guangfei.zhao
2025-09-23 10:58:47 +08:00
parent 6523f8e512
commit 87cc15dd53
3 changed files with 274 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
LICENSE Normal file
View File

@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2025 AI Chat Assistant
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

217
README.md
View File

@@ -20,7 +20,12 @@
```
lib/
├── app.dart # 主应用入口
├── main.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 # 消息状态
@@ -30,12 +35,12 @@ lib/
│ ├── vehicle_cmd.dart # 车控命令模型
│ ├── vehicle_cmd_response.dart # 车控命令响应
│ └── vehicle_status_info.dart # 车辆状态信息
├── pages/ # 页面
│ └── full_screen.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 # 车控命令服务
@@ -49,19 +54,28 @@ lib/
├── 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 # 大音频波形
├── large_audio_wave.dart # 大音频波形
├── mini_audio_wave.dart # 小音频波形
├── rotating_image.dart # 旋转图片组件
├── voice_animation.dart # 语音动画
└── _hole_overlay.dart # 洞穴遮罩层
```
### 🎯 核心架构设计
@@ -72,21 +86,26 @@ lib/
- **ChatSseService**: SSE 流式通信服务，处理与 AI 后端的实时对话
- **CommandService**: 车控命令处理服务，提供车辆控制命令的回调机制
- **TTSService**: 语音合成服务，支持中英文语音播报
- **VoiceRecognitionService**: 语音识别服务，处理音频转文字
- **VoiceRecognitionService**: 语音识别服务，基于阿里云SDK处理音频转文字
#### 2. UI 层架构 (UI Layer)
#### 2. 状态管理架构 (State Management)
- **浮动图标模式**: 主界面显示可拖拽的 AI 助手浮动图标
- **部分屏幕模式**: 点击图标显示简化聊天界面
- **EasyBloc**: 轻量级状态管理框架，支持事件驱动和状态流
- **EasyCubit**: 简化的状态管理，用于单一状态变更
- **AIChatCommandCubit**: 专门处理车控命令的状态管理
- **MessageService**: 基于Provider的消息状态管理
#### 3. UI 层架构 (UI Layer)
- **ChatPopup**: 主要的聊天弹出层组件，集成浮动图标和聊天窗口
- **ChatFloatingIcon**: 可拖拽的浮动图标
- **ChatWindowContent**: 聊天窗口内容组件
- **全屏模式**: 完整的聊天界面，支持历史记录、操作按钮等
#### 3. 状态管理 (State Management)
#### 4. 管理器模式 (Manager Pattern)
基于 Provider 模式的响应式状态管理：
- 消息状态管理
- 语音识别状态
- AI 对话状态
- 车控命令执行状态
- **AIChatAssistantManager**: 单例管理器，负责整体协调
- **VehicleCommandHandler**: 抽象的车控命令处理器，支持自定义实现
## 🚗 支持的车控命令
@@ -118,7 +137,7 @@ lib/
### 核心依赖
- **Flutter SDK**: ^3.6.2
- **Flutter SDK**: ^3.5.0
- **Provider**: ^6.1.5 - 状态管理
- **HTTP**: ^1.4.0 - 网络请求
- **Record**: ^6.0.0 - 音频录制
@@ -129,6 +148,7 @@ lib/
- **Flutter Markdown**: ^0.7.7+1 - Markdown 渲染
- **FlutterToast**: ^8.2.12 - 消息提示
- **Path Provider**: ^2.1.5 - 文件路径管理
- **Meta**: ^1.15.0 - 元数据注解
### 自定义包
@@ -161,12 +181,44 @@ dependencies:
```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: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();
@@ -175,15 +227,9 @@ void main() async {
await Permission.microphone.request();
}
// 初始化 AI Chat Assistant，注册车控命令回调
ChatAssistantApp.initialize(
commandCallback: (VehicleCommandType type, Map<String, dynamic>? params) async {
// 处理车控命令的业务逻辑
print('收到车控命令: $type, 参数: $params');
// 返回执行结果
return (true, {'message': '命令已执行'});
},
// 初始化 AI Chat Assistant，注册车控命令处理器
AIChatAssistantManager.instance.setupCommandHandle(
commandHandler: MyVehicleCommandHandler(),
);
runApp(
@@ -209,10 +255,10 @@ class MyApp extends StatelessWidget {
### 4. 自定义集成
如果您想在现有应用中集成聊天助手，可以使用浮动图标：
如果您想在现有应用中集成聊天助手，可以使用聊天弹出层：
```dart
import 'package:ai_chat_assistant/widgets/floating_icon.dart';
import 'package:ai_chat_assistant/widgets/chat_popup.dart';
class MyHomePage extends StatelessWidget {
@override
@@ -223,8 +269,8 @@ class MyHomePage extends StatelessWidget {
// 您的现有 UI
YourExistingWidget(),
// AI 助手浮动图标
const FloatingIcon(),
// AI 助手聊天弹出层
const ChatPopup(),
],
),
);
@@ -249,16 +295,23 @@ flutter run
## 🎨 UI 组件
### 浮动图标 (FloatingIcon)
### 聊天弹出层 (ChatPopup)
可拖拽的 AI 助手图标，支持：
集成式聊天弹出层组件，包含：
- 浮动图标 (ChatFloatingIcon)
- 聊天窗口 (ChatWindowContent)
- 拖拽定位
- 点击展开聊天界面
- 动态图标切换
- 波纹动画效果
- 动画效果
### 浮动图标相关组件
- **ChatFloatingIcon**: 专用聊天浮动图标
- **FloatingIcon**: 通用浮动图标
- **FloatingIconWithWave**: 带波纹效果的浮动图标
### 聊天界面组件
- **ChatWindowContent**: 聊天窗口内容组件
- **ChatBubble**: 聊天气泡组件
- **ChatBox**: 聊天输入框
- **ChatHeader**: 聊天头部
@@ -267,8 +320,10 @@ flutter run
### 动画组件
- **FloatingIconWithWave**: 带波纹效果的浮动图标
- **VoiceAnimation**: 语音动画组件
- **LargeAudioWave**: 大音频波形动画
- **MiniAudioWave**: 小音频波形动画
- **RotatingImage**: 旋转图片组件
- **GradientBackground**: 渐变背景
## ⚙️ 配置选项
@@ -310,10 +365,16 @@ flutter:
### Android 平台
项目包含 Android 原生代码，支持：
- ASR (自动语音识别) 功能
- ASR (自动语音识别) 功能，基于阿里云SDK
- 原生音频处理
- 系统权限管理
### 阿里云SDK集成
使用阿里云语音识别SDK，配置文件在：
- `android/libs/nui-release-1.0.0.aar`
- `android/libs/fastjson-1.1.46.android.jar`
### 插件架构
```yaml
@@ -326,6 +387,35 @@ plugin:
## 📝 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
核心消息管理服务：
@@ -346,20 +436,28 @@ class MessageService extends ChangeNotifier {
}
```
### CommandService
### EasyBloc / EasyCubit
车控命令服务：
轻量级状态管理框架：
```dart
class CommandService {
// 注册命令回调
static void registerCallback(CommandCallback callback);
// 基于事件的状态管理
class MyBloc extends EasyBloc<MyEvent, MyState> {
MyBloc(MyState initialState) : super(initialState);
// 执行车控命令
static Future<(bool, Map<String, dynamic>?)> executeCommand(
VehicleCommandType type,
{Map<String, dynamic>? params}
);
@override
void _mapEventToState(MyEvent event) {
// 处理事件并发射新状态
}
}
// 简化的状态管理
class MyCubit extends EasyCubit<MyState> {
MyCubit(MyState initialState) : super(initialState);
void updateState(MyState newState) {
emit(newState);
}
}
```
@@ -411,7 +509,26 @@ void main() {
- [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 国际化包的兼容

96
example/README.md
View File

@@ -1,16 +1,92 @@
# example
# AI Chat Assistant Example
A new Flutter project.
这是 AI Chat Assistant Flutter 插件的示例应用，展示了如何集成和使用 AI 聊天助手功能。
## Getting Started
## 🚀 快速开始
This project is a starting point for a Flutter application.
### 1. 安装依赖
A few resources to get you started if this is your first Flutter project:
```bash
cd example
flutter pub get
```
- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook)
### 2. 运行应用
For help getting started with Flutter development, view the
[online documentation](https://docs.flutter.dev/), which offers tutorials,
samples, guidance on mobile development, and a full API reference.
```bash
flutter run
```
## 📱 示例功能
### 车控命令处理器示例
本示例展示了如何实现自定义的车控命令处理器：
```dart
class VehicleCommandClent 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': '命令已执行'});
}
}
```
### 初始化示例
```dart
void main() async {
WidgetsFlutterBinding.ensureInitialized();
// 请求麦克风权限
if (!await Permission.microphone.isGranted) {
await Permission.microphone.request();
}
// 初始化 AI Chat Assistant，注册车控命令处理器
AIChatAssistantManager.instance.setupCommandHandle(
commandHandler: VehicleCommandClent()
);
runApp(const MyApp());
}
```
## 🎯 示例特性
- ✅ 完整的车控命令处理示例
- ✅ 权限管理示例
- ✅ 状态管理集成
- ✅ AI 聊天界面集成
- ✅ 语音识别功能
- ✅ TTS 语音播报
## 📖 了解更多
- 查看主项目 [README](../README.md) 了解完整的功能特性
- 查看 [API 文档](../README.md#-api-文档) 了解接口使用方法