Cyrene-For-Android/devdocs/00-development-overview.md

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 / 国内应用商店）