UPDATE README

2025-09-23 10:58:47 +08:00
parent 6523f8e512
commit 87cc15dd53
3 changed files with 274 additions and 60 deletions
--- 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<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 国际化包的兼容