feat: 添加README以及example项目，修复plugin的路径，新建basic_intl的本地依赖
This commit is contained in:
421
README.md
421
README.md
@@ -1,16 +1,417 @@
|
||||
# app003
|
||||
# AI Chat Assistant Flutter Plugin
|
||||
|
||||
A new Flutter project.
|
||||
一个功能丰富的 AI 聊天助手 Flutter 插件，专为车载系统设计，支持语音识别、AI 对话、车控命令执行、语音合成等功能。
|
||||
|
||||
## Getting Started
|
||||
## 📱 功能特性
|
||||
|
||||
This project is a starting point for a Flutter application.
|
||||
- 🎤 **语音识别 (ASR)**: 支持实时语音转文字，自动停止检测
|
||||
- 🤖 **AI 对话**: 基于 SSE (Server-Sent Events) 的流式 AI 对话
|
||||
- 🚗 **车控命令**: 支持 20+ 种车辆控制命令（空调、车窗、车门、座椅加热等）
|
||||
- 🔊 **语音合成 (TTS)**: 支持中英文语音播报
|
||||
- 🎨 **精美 UI**: 浮动图标、波纹动画、渐变背景
|
||||
- 📱 **多界面模式**: 支持全屏和部分屏幕聊天界面
|
||||
- 🌐 **国际化**: 支持中英文切换
|
||||
- 📊 **状态管理**: 基于 Provider 的状态管理
|
||||
|
||||
A few resources to get you started if this is your first Flutter project:
|
||||
## 🏗️ 项目架构
|
||||
|
||||
- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
|
||||
- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook)
|
||||
### 📁 目录结构
|
||||
|
||||
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.
|
||||
```
|
||||
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` 文件中添加：
|
||||
|
||||
```yaml
|
||||
dependencies:
|
||||
ai_chat_assistant:
|
||||
path: path/to/ai_chat_assistant
|
||||
```
|
||||
|
||||
### 2. 权限配置
|
||||
|
||||
#### Android 权限 (android/app/src/main/AndroidManifest.xml)
|
||||
|
||||
```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. 基础集成
|
||||
|
||||
```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: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. 自定义集成
|
||||
|
||||
如果您想在现有应用中集成聊天助手，可以使用浮动图标：
|
||||
|
||||
```dart
|
||||
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/` 目录下：
|
||||
|
||||
```bash
|
||||
cd example
|
||||
flutter run
|
||||
```
|
||||
|
||||
示例展示了：
|
||||
- 基础集成方法
|
||||
- 车控命令处理
|
||||
- 自定义 UI 主题
|
||||
- 权限管理
|
||||
|
||||
## 🎨 UI 组件
|
||||
|
||||
### 浮动图标 (FloatingIcon)
|
||||
|
||||
可拖拽的 AI 助手图标，支持：
|
||||
- 拖拽定位
|
||||
- 点击展开聊天界面
|
||||
- 动态图标切换
|
||||
- 波纹动画效果
|
||||
|
||||
### 聊天界面组件
|
||||
|
||||
- **ChatBubble**: 聊天气泡组件
|
||||
- **ChatBox**: 聊天输入框
|
||||
- **ChatHeader**: 聊天头部
|
||||
- **ChatFooter**: 聊天底部操作栏
|
||||
- **AssistantAvatar**: AI 助手头像
|
||||
|
||||
### 动画组件
|
||||
|
||||
- **FloatingIconWithWave**: 带波纹效果的浮动图标
|
||||
- **LargeAudioWave**: 大音频波形动画
|
||||
- **GradientBackground**: 渐变背景
|
||||
|
||||
## ⚙️ 配置选项
|
||||
|
||||
### 主题自定义
|
||||
|
||||
```dart
|
||||
// 在 AppTheme.dart 中自定义主题
|
||||
class AppTheme {
|
||||
static ThemeData get lightTheme => ThemeData(
|
||||
// 自定义浅色主题
|
||||
);
|
||||
|
||||
static ThemeData get darkTheme => ThemeData(
|
||||
// 自定义深色主题
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### 资源文件
|
||||
|
||||
确保在 `pubspec.yaml` 中包含必要的资源：
|
||||
|
||||
```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 (自动语音识别) 功能
|
||||
- 原生音频处理
|
||||
- 系统权限管理
|
||||
|
||||
### 插件架构
|
||||
|
||||
```yaml
|
||||
plugin:
|
||||
platforms:
|
||||
android:
|
||||
package: com.example.ai_assistant_plugin
|
||||
pluginClass: AiAssistantPlugin
|
||||
```
|
||||
|
||||
## 📝 API 文档
|
||||
|
||||
### MessageService
|
||||
|
||||
核心消息管理服务：
|
||||
|
||||
```dart
|
||||
class MessageService extends ChangeNotifier {
|
||||
// 发送消息
|
||||
Future<void> sendMessage(String text);
|
||||
|
||||
// 开始语音识别
|
||||
Future<void> startVoiceRecognition();
|
||||
|
||||
// 停止语音识别
|
||||
void stopVoiceRecognition();
|
||||
|
||||
// 获取聊天历史
|
||||
List<ChatMessage> get messages;
|
||||
}
|
||||
```
|
||||
|
||||
### CommandService
|
||||
|
||||
车控命令服务：
|
||||
|
||||
```dart
|
||||
class CommandService {
|
||||
// 注册命令回调
|
||||
static void registerCallback(CommandCallback callback);
|
||||
|
||||
// 执行车控命令
|
||||
static Future<(bool, Map<String, dynamic>?)> executeCommand(
|
||||
VehicleCommandType type,
|
||||
{Map<String, dynamic>? params}
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## 🐛 调试和故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
1. **麦克风权限问题**
|
||||
- 确保在 AndroidManifest.xml 中添加了录音权限
|
||||
- 在应用启动时请求权限
|
||||
|
||||
2. **网络连接问题**
|
||||
- 检查网络权限配置
|
||||
- 确认 SSE 服务端地址配置正确
|
||||
|
||||
3. **TTS 播放问题**
|
||||
- 检查音频播放权限
|
||||
- 确认设备支持 TTS 功能
|
||||
|
||||
### 日志调试
|
||||
|
||||
启用详细日志：
|
||||
|
||||
```dart
|
||||
// 在 main.dart 中启用调试日志
|
||||
void main() {
|
||||
debugPrint('AI Chat Assistant 启动中...');
|
||||
// ... 其他初始化代码
|
||||
}
|
||||
```
|
||||
|
||||
## 🤝 贡献指南
|
||||
|
||||
欢迎提交 Issue 和 Pull Request！
|
||||
|
||||
1. Fork 本仓库
|
||||
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
|
||||
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
|
||||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||||
5. 打开 Pull Request
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
|
||||
|
||||
## 🔗 相关链接
|
||||
|
||||
- [Flutter 官方文档](https://flutter.dev/docs)
|
||||
- [Provider 状态管理](https://pub.dev/packages/provider)
|
||||
- [Flutter TTS](https://pub.dev/packages/flutter_tts)
|
||||
- [Record 插件](https://pub.dev/packages/record)
|
||||
|
||||
---
|
||||
|
||||
**注意**: 本插件专为车载系统设计，某些功能可能需要特定的硬件环境支持。
|
||||
|
||||
Reference in New Issue
Block a user