lib/
├── app.dart                    # 主应用入口
├── main.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     # 车辆状态信息
├── 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          # 车控命令服务
│   ├── 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/                      # 工具类
│   ├── common_util.dart            # 通用工具
│   ├── tts_engine_manager.dart     # TTS 引擎管理
│   └── tts_util.dart               # TTS 工具
└── widgets/                    # UI 组件
    ├── assistant_avatar.dart       # AI 助手头像
    ├── chat_box.dart              # 聊天框
    ├── chat_bubble.dart           # 聊天气泡
    ├── chat_footer.dart           # 聊天底部
    ├── chat_header.dart           # 聊天头部
    ├── floating_icon.dart         # 浮动图标
    ├── floating_icon_with_wave.dart # 带波纹的浮动图标
    ├── gradient_background.dart    # 渐变背景
    └── large_audio_wave.dart      # 大音频波形

🎯 核心架构设计

1. 服务层架构 (Services Layer)

MessageService: 核心消息管理服务，负责统一管理聊天消息、语音识别、AI 对话流程
ChatSseService: SSE 流式通信服务，处理与 AI 后端的实时对话
CommandService: 车控命令处理服务，提供车辆控制命令的回调机制
TTSService: 语音合成服务，支持中英文语音播报
VoiceRecognitionService: 语音识别服务，处理音频转文字

2. UI 层架构 (UI Layer)

浮动图标模式: 主界面显示可拖拽的 AI 助手浮动图标
部分屏幕模式: 点击图标显示简化聊天界面
全屏模式: 完整的聊天界面，支持历史记录、操作按钮等

3. 状态管理 (State Management)

基于 Provider 模式的响应式状态管理：

消息状态管理
语音识别状态
AI 对话状态
车控命令执行状态

🚗 支持的车控命令

命令类型	中文描述	英文描述
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.6.2
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 - 文件路径管理

自定义包

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/app.dart';
import 'package:ai_chat_assistant/services/message_service.dart';
import 'package:ai_chat_assistant/enums/vehicle_command_type.dart';
import 'package:provider/provider.dart';
import 'package:permission_handler/permission_handler.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 请求麦克风权限
  if (!await Permission.microphone.isGranted) {
    await Permission.microphone.request();
  }

  // 初始化 AI Chat Assistant，注册车控命令回调
  ChatAssistantApp.initialize(
    commandCallback: (VehicleCommandType type, Map<String, dynamic>? params) async {
      // 处理车控命令的业务逻辑
      print('收到车控命令: $type, 参数: $params');
      
      // 返回执行结果
      return (true, {'message': '命令已执行'});
    },
  );

  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/floating_icon.dart';

class MyHomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Stack(
        children: [
          // 您的现有 UI
          YourExistingWidget(),
          
          // AI 助手浮动图标
          const FloatingIcon(),
        ],
      ),
    );
  }
}

📖 示例项目

项目包含完整的示例应用，位于 example/ 目录下：

cd example
flutter run

示例展示了：

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

🎨 UI 组件

浮动图标 (FloatingIcon)

可拖拽的 AI 助手图标，支持：

拖拽定位
点击展开聊天界面
动态图标切换
波纹动画效果

聊天界面组件

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

动画组件

FloatingIconWithWave: 带波纹效果的浮动图标
LargeAudioWave: 大音频波形动画
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 (自动语音识别) 功能
原生音频处理
系统权限管理

插件架构

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

📝 API 文档

MessageService

核心消息管理服务：

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

CommandService

车控命令服务：

class CommandService {
  // 注册命令回调
  static void registerCallback(CommandCallback callback);
  
  // 执行车控命令
  static Future<(bool, Map<String, dynamic>?)> executeCommand(
    VehicleCommandType type, 
    {Map<String, dynamic>? params}
  );
}

🐛 调试和故障排除

常见问题

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

日志调试

启用详细日志：

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

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
打开 Pull Request

📄 许可证

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

🔗 相关链接

注意: 本插件专为车载系统设计，某些功能可能需要特定的硬件环境支持。

README.md Unescape Escape

AI Chat Assistant Flutter Plugin

📱 功能特性

🏗️ 项目架构

📁 目录结构