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 文件中添加：

dependencies:
  ai_chat_assistant:
    path: path/to/ai_chat_assistant

2. 权限配置

Android 权限 (android/app/src/main/AndroidManifest.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. 基础集成

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. 自定义集成

如果您想在现有应用中集成聊天助手，可以使用聊天弹出层：

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/ 目录下：

cd example
flutter run

示例展示了：

基础集成方法
车控命令处理
自定义 UI 主题
权限管理

🎨 UI 组件

聊天弹出层 (ChatPopup)

集成式聊天弹出层组件，包含：

浮动图标 (ChatFloatingIcon)
聊天窗口 (ChatWindowContent)
拖拽定位
动画效果

浮动图标相关组件

ChatFloatingIcon: 专用聊天浮动图标
FloatingIcon: 通用浮动图标
FloatingIconWithWave: 带波纹效果的浮动图标

聊天界面组件

ChatWindowContent: 聊天窗口内容组件
ChatBubble: 聊天气泡组件
ChatBox: 聊天输入框
ChatHeader: 聊天头部
ChatFooter: 聊天底部操作栏
AssistantAvatar: AI 助手头像

动画组件

VoiceAnimation: 语音动画组件
LargeAudioWave: 大音频波形动画
MiniAudioWave: 小音频波形动画
RotatingImage: 旋转图片组件
GradientBackground: 渐变背景

⚙️ 配置选项

主题自定义

// 在 AppTheme.dart 中自定义主题
class AppTheme {
  static ThemeData get lightTheme => ThemeData(
    // 自定义浅色主题
  );
  
  static ThemeData get darkTheme => ThemeData(
    // 自定义深色主题
  );
}

资源文件

确保在 pubspec.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

插件架构

plugin:
  platforms:
    android:
      package: com.example.ai_assistant_plugin
      pluginClass: AiAssistantPlugin

📝 API 文档

AIChatAssistantManager

核心管理器（单例模式）：

class AIChatAssistantManager {
  static final instance = AIChatAssistantManager._internal();
  
  // 设置命令处理器
  void setupCommandHandle({required VehicleCommandHandler commandHandler});
  
  // 获取命令状态流
  Stream<AIChatCommandState> get commandStateStream;
}

VehicleCommandHandler

车控命令处理器抽象类：

abstract class VehicleCommandHandler {
  AIChatCommandCubit? commandCubit;
  
  // 执行车辆控制命令
  Future<(bool, Map<String, dynamic>?)> executeCommand(VehicleCommand command);
}

MessageService

核心消息管理服务：

class MessageService extends ChangeNotifier {
  // 发送消息
  Future<void> sendMessage(String text);
  
  // 开始语音识别
  Future<void> startVoiceRecognition();
  
  // 停止语音识别
  void stopVoiceRecognition();
  
  // 获取聊天历史
  List<ChatMessage> get messages;
}

EasyBloc / EasyCubit

轻量级状态管理框架：

// 基于事件的状态管理
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);
  }
}

🐛 调试和故障排除

常见问题

麦克风权限问题
- 确保在 AndroidManifest.xml 中添加了录音权限
- 在应用启动时请求权限
网络连接问题
- 检查网络权限配置
- 确认 SSE 服务端地址配置正确
TTS 播放问题
- 检查音频播放权限
- 确认设备支持 TTS 功能

日志调试

启用详细日志：

// 在 main.dart 中启用调试日志
void main() {
  debugPrint('AI Chat Assistant 启动中...');
  // ... 其他初始化代码
}

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🔗 相关链接

📋 更新日志

v1.0.0+1 (2025-09-23)

新增功能

🎯 新增轻量级状态管理框架 (EasyBloc/EasyCubit)
🔧 新增 AIChatAssistantManager 单例管理器
📦 新增 ChatPopup 集成组件
🎨 新增多个动画组件 (VoiceAnimation, MiniAudioWave, RotatingImage 等)
💾 集成阿里云语音识别SDK

架构改进

🏗️ 采用管理器模式替代回调模式
🔄 支持面向对象的车控命令处理器
📱 优化聊天界面组件结构
🎵 改进语音识别和TTS服务

技术栈更新

🔧 添加 Meta 注解支持
🌐 保持与 basic_intl 国际化包的兼容

README.md Unescape Escape

AI Chat Assistant Flutter Plugin

📱 功能特性

🏗️ 项目架构

📁 目录结构