159 lines
7.7 KiB
Markdown
159 lines
7.7 KiB
Markdown
# 00 — 项目概述与架构
|
||
|
||
> 对应主项目 Phase 5（v1.5 → v2.0）Android 客户端
|
||
> 主项目文档：`../../docs/dev-plan/04-voice-system-plan.md`
|
||
|
||
---
|
||
|
||
## 1. 项目定位
|
||
|
||
Cyrene for Android 是昔涟的官方 Android 客户端，定位为 **可替换系统自带语音助手的智能体 APP**（替代 Google Assistant / Bixby）。
|
||
|
||
核心差异点：
|
||
- 不是传统 APP（以桌面图标为主要入口），而是**系统级语音助手**
|
||
- 除常规全屏 Activity 外，通过 `VoiceInteractionSession` 提供悬浮式覆盖层交互
|
||
- 支持息屏热词唤醒、长按 Home / 电源键呼出
|
||
|
||
## 2. 技术栈
|
||
|
||
| 层 | 技术 | 版本要求 |
|
||
|----|------|---------|
|
||
| 语言 | Kotlin | 2.0+ |
|
||
| UI 框架 | Jetpack Compose + Material Design 3 | BOM 2025+ |
|
||
| 构建 | Gradle (Kotlin DSL) | 8.7+ |
|
||
| 架构模式 | MVVM + Repository | — |
|
||
| 依赖注入 | Hilt / Koin (待定) | — |
|
||
| 网络 | Retrofit + OkHttp | — |
|
||
| 实时通信 | OkHttp WebSocket | — |
|
||
| 本地存储 | Room (SQLite) + DataStore | — |
|
||
| 推送 | FCM (Firebase Cloud Messaging) | — |
|
||
| 系统语音 | VoiceInteractionService | API 23+ |
|
||
| 热词唤醒 | Always-On Hotword Detection | API 23+ |
|
||
| 语音识别 | 服务端 (Whisper API) + 本地兜底 | — |
|
||
|
||
## 3. 最低系统要求
|
||
|
||
| 项目 | 要求 |
|
||
|------|------|
|
||
| minSdk | 26 (Android 8.0) |
|
||
| targetSdk | 35+ |
|
||
| compileSdk | 35+ |
|
||
| JDK | 17 |
|
||
| Gradle | 8.7+ |
|
||
|
||
注：`VoiceInteractionService` 基础 API 要求 23，`AssistAction` 热词唤醒要求 23。minSdk 设为 26 以覆盖绝大多数活跃设备并简化兼容性。
|
||
|
||
## 4. 项目结构
|
||
|
||
```
|
||
android/
|
||
├── app/
|
||
│ ├── src/main/
|
||
│ │ ├── java/com/cyrene/app/
|
||
│ │ │ ├── CyreneApplication.kt # Application 初始化
|
||
│ │ │ ├── MainActivity.kt # 全屏主界面 (桌面图标入口)
|
||
│ │ │ ├── ui/
|
||
│ │ │ │ ├── theme/ # MD3 主题 (Color / Type / Shape)
|
||
│ │ │ │ ├── screens/ # 全屏页面 (Compose)
|
||
│ │ │ │ │ ├── chat/ # 对话页
|
||
│ │ │ │ │ ├── home/ # 首页 / IoT 面板
|
||
│ │ │ │ │ ├── settings/ # 设置页
|
||
│ │ │ │ │ └── login/ # 登录/注册
|
||
│ │ │ │ ├── overlay/ # 悬浮窗对话界面 (VoiceInteractionSession)
|
||
│ │ │ │ └── components/ # 共享组件库
|
||
│ │ │ ├── viewmodel/ # ViewModel 层
|
||
│ │ │ ├── domain/ # 领域层 (UseCase / Repository 接口)
|
||
│ │ │ ├── data/
|
||
│ │ │ │ ├── remote/ # API 接口定义 + DTO
|
||
│ │ │ │ ├── local/ # Room DAO + DataStore
|
||
│ │ │ │ └── repository/ # Repository 实现
|
||
│ │ │ ├── service/
|
||
│ │ │ │ ├── CyreneVoiceInteractionService.kt
|
||
│ │ │ │ ├── CyreneVoiceInteractionSession.kt
|
||
│ │ │ │ ├── CyreneAssistService.kt
|
||
│ │ │ │ └── WebSocketService.kt
|
||
│ │ │ ├── voice/
|
||
│ │ │ │ ├── hotword/ # 热词唤醒引擎
|
||
│ │ │ │ ├── stt/ # 语音识别客户端
|
||
│ │ │ │ └── tts/ # 语音合成客户端
|
||
│ │ │ ├── di/ # DI 模块定义
|
||
│ │ │ └── util/ # 工具类
|
||
│ │ ├── res/ # 资源文件
|
||
│ │ └── AndroidManifest.xml
|
||
│ └── build.gradle.kts
|
||
├── gradle/
|
||
│ ├── libs.versions.toml # 版本目录
|
||
│ └── wrapper/
|
||
├── build.gradle.kts # 根构建脚本
|
||
├── settings.gradle.kts
|
||
└── gradle.properties
|
||
```
|
||
|
||
## 5. 架构分层
|
||
|
||
```
|
||
┌──────────────────────────────────────────────┐
|
||
│ UI Layer (Compose) │
|
||
│ ├─ Screens (全屏 Activity) │
|
||
│ └─ Overlay (VoiceInteractionSession 悬浮窗) │
|
||
├──────────────────────────────────────────────┤
|
||
│ ViewModel Layer │
|
||
│ ├─ ChatViewModel │
|
||
│ ├─ HomeViewModel (IoT) │
|
||
│ ├─ SettingsViewModel │
|
||
│ └─ OverlayViewModel │
|
||
├──────────────────────────────────────────────┤
|
||
│ Domain Layer │
|
||
│ ├─ UseCase (SendMessage, ControlIoT, ...) │
|
||
│ └─ Repository Interfaces │
|
||
├──────────────────────────────────────────────┤
|
||
│ Data Layer │
|
||
│ ├─ Remote: Retrofit API + WebSocket │
|
||
│ ├─ Local: Room + DataStore │
|
||
│ └─ Repository Implementation │
|
||
├──────────────────────────────────────────────┤
|
||
│ Service Layer │
|
||
│ ├─ VoiceInteractionService (系统助手) │
|
||
│ ├─ WebSocketService (长连接) │
|
||
│ └─ FCMMessagingService (推送) │
|
||
└──────────────────────────────────────────────┘
|
||
```
|
||
|
||
UI 层和 Service 层通过 ViewModel 解耦——全屏 Activity 和悬浮窗 Overlay 复用同一组 ViewModel，只是 UI 布局不同。
|
||
|
||
## 6. 与后端的关系
|
||
|
||
```
|
||
Android Client
|
||
│
|
||
├─ HTTP REST ──────────► Gateway (:8080) # 登录、CRUD、配置
|
||
├─ WebSocket ──────────► Gateway (:8080) # 实时对话、IoT 状态推送
|
||
├─ STT Audio ──────────► Voice Service (:8093) # 语音识别
|
||
└─ TTS Stream ◄──────── Voice Service (:8093) # 语音合成
|
||
```
|
||
|
||
WebSocket 长连接是核心通信通道：对话消息、通知、IoT 状态广播均通过同一连接。HTTP 仅用于一次性操作（登录、文件上传/下载）。
|
||
|
||
## 7. 关键设计决策
|
||
|
||
| 决策 | 选择 | 理由 |
|
||
|------|------|------|
|
||
| UI 框架 | Jetpack Compose + MD3 | 声明式 UI，与悬浮窗的 ComposeView 集成简单 |
|
||
| 架构 | MVVM + Repository | Google 官方推荐，ViewModel 可在 Activity 和 Session 间复用 |
|
||
| 语音框架 | VoiceInteractionService（系统 API） | 原生支持替换系统助手，无需自定义悬浮窗权限 |
|
||
| 热词方案 | 系统 Always-On Hotword API | 息屏低功耗监听，不用自建音频采集 |
|
||
| 网络 | OkHttp WebSocket | 比 FCM 更实时，与主项目 Gateway 已有 WS Hub 对应 |
|
||
| 最低 API | 26 | 覆盖 95%+ 活跃设备，VoiceInteractionService 兼容 |
|
||
|
||
## 8. 排期参考
|
||
|
||
对应主项目路线图：
|
||
|
||
```
|
||
2026 Q4 ─ v1.3 多平台接入（前置依赖）
|
||
2027 Q1 ─ v1.8 语音模型训练完成（后端依赖）
|
||
2027 Q2 ─ v2.0 开始 Android 客户端开发
|
||
2027 Q3 ─ v2.3 语音助手 APP MVP 版本
|
||
2027 Q4 ─ v3.0 APP 上架（Google Play / 国内应用商店）
|
||
```
|