diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..761052b --- /dev/null +++ b/LICENSE @@ -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. \ No newline at end of file diff --git a/README.md b/README.md index a9279b3..9be9cae 100644 --- a/README.md +++ b/README.md @@ -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?)> 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? 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 get commandStateStream; +} +``` + +### VehicleCommandHandler + +车控命令处理器抽象类： + +```dart +abstract class VehicleCommandHandler { + AIChatCommandCubit? commandCubit; + + // 执行车辆控制命令 + Future<(bool, Map?)> 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 { + MyBloc(MyState initialState) : super(initialState); - // 执行车控命令 - static Future<(bool, Map?)> executeCommand( - VehicleCommandType type, - {Map? params} - ); + @override + void _mapEventToState(MyEvent event) { + // 处理事件并发射新状态 + } +} + +// 简化的状态管理 +class MyCubit extends EasyCubit { + 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 国际化包的兼容 diff --git a/example/README.md b/example/README.md index 2b3fce4..1fa6243 100644 --- a/example/README.md +++ b/example/README.md @@ -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?)> 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-文档) 了解接口使用方法