183 lines
6.6 KiB
Markdown
183 lines
6.6 KiB
Markdown
# Cyrene for Android
|
||
|
||
昔涟在安卓设备上的载体 —— 随时随地与昔涟对话、操控 IoT 设备、接收实时通知。
|
||
|
||
## 概述
|
||
|
||
Cyrene for Android 是 [Cyrene（昔涟）](https://github.com/Cyrene/Cyrene) 项目的官方 Android 客户端。Cyrene 是一个开源的基于 LLM 平台的智能体，提供多人格对话、IoT 设备操控、记忆管理、自动化规则、知识库、语音交互等功能。
|
||
|
||
Android 客户端的目标是成为用户的**默认语音助手**，完全替代系统自带的助手（Google Assistant / Bixby 等），同时提供：
|
||
|
||
- **系统级语音助手** — 注册为 `VoiceInteractionService`，可通过长按 Home / 侧滑呼出
|
||
- **语音唤醒** — 息屏热词唤醒、免提交互（类似 "Hey Google"，使用 "昔涟" 等唤醒词）
|
||
- **随时对话** — 通过文字或语音与昔涟交流
|
||
- **IoT 控制** — 远程操控家中的智能设备
|
||
- **实时通知** — 接收昔涟的主动消息、提醒、IoT 状态变更
|
||
- **后台连接** — 即使 APP 在后台，仍保持通知推送与语音服务就绪
|
||
|
||
## 开发状态
|
||
|
||
> **当前阶段**：项目初始化，尚未开始正式开发。
|
||
|
||
根据主项目的[开发路线图](../docs/dev-plan/00-development-roadmap.md)，Android 客户端计划在 **Phase 5（v1.5 → v2.0）** 开始开发，预计时间窗口为 **2027 Q2-Q3**。
|
||
|
||
## 技术栈 (规划)
|
||
|
||
| 层 | 技术 |
|
||
|----|------|
|
||
| 语言 | Kotlin |
|
||
| UI 框架 | Jetpack Compose + Material Design 3 |
|
||
| 架构 | MVVM + Repository |
|
||
| 网络 | OkHttp / Retrofit + WebSocket |
|
||
| 本地存储 | Room (SQLite) + DataStore |
|
||
| 推送 | FCM (Firebase Cloud Messaging) |
|
||
| 语音 | VoiceInteractionService + 热词唤醒 + STT + TTS |
|
||
| 构建 | Gradle (Kotlin DSL) |
|
||
|
||
## 功能路线图
|
||
|
||
- [ ] 用户认证与登录
|
||
- [ ] 实时文字对话 (WebSocket)
|
||
- [ ] VoiceInteractionService 注册（替换系统语音助手）
|
||
- [ ] 间接启动悬浮窗（VoiceInteractionSession 全屏覆盖层）
|
||
- [ ] 热词唤醒（息屏 / 亮屏）+ 唤醒词自定义
|
||
- [ ] 语音识别 (STT)
|
||
- [ ] 语音合成 (TTS)
|
||
- [ ] IoT 设备控制面板
|
||
- [ ] 推送通知 (FCM)
|
||
- [ ] 后台连接与通知
|
||
- [ ] 锁屏 / 息屏语音交互
|
||
- [ ] PWA 保底方案 (短期替代)
|
||
|
||
## 交互模式
|
||
|
||
APP 有两种界面呈现方式，根据启动来源自动切换：
|
||
|
||
| 启动方式 | 界面模式 | 说明 |
|
||
|---------|---------|------|
|
||
| 桌面图标 / 最近任务 | **全屏 Activity** | 常规 APP 模式，完整功能入口 |
|
||
| 语音唤醒 / 长按 Home / 侧滑 / 长按电源键 / 耳机按键 | **悬浮窗 (VoiceInteractionSession)** | 全屏覆盖层，半透明背景透出底层 APP，不影响当前任务栈 |
|
||
|
||
悬浮窗模式的要点：
|
||
- 借助 `VoiceInteractionSession` 系统窗口，不压入 Activity 返回栈
|
||
- 对话结束后窗口收起，用户回到触发前的界面
|
||
- 底层 APP 内容半透明可见（模糊遮罩），让用户保持上下文感知
|
||
- 窗口高度自适应对话内容，类似 Google Assistant 的卡片式覆盖
|
||
|
||
## 设计规范
|
||
|
||
- **设计语言**：Material Design 3 (Material You)
|
||
- **主题**：动态配色（Dynamic Color），跟随系统壁纸或手动选择主题色
|
||
- **暗黑模式**：支持 Light / Dark 双主题，跟随系统或手动切换
|
||
- **组件**：全面使用 `androidx.compose.material3` 组件库
|
||
- **图标**：Material Icons + 自定义图标
|
||
- **动效**：遵循 MD3 动效规范（过渡动画、涟漪效果、Shared Elements）
|
||
- **字体**：系统默认字体（Roboto / Google Sans），支持动态字体缩放
|
||
|
||
## 项目结构 (规划)
|
||
|
||
```
|
||
android/
|
||
├── app/
|
||
│ ├── src/main/
|
||
│ │ ├── java/com/cyrene/app/
|
||
│ │ │ ├── ui/ # Compose UI 层
|
||
│ │ │ ├── viewmodel/ # ViewModel 层
|
||
│ │ │ ├── repository/ # 数据仓库层
|
||
│ │ │ ├── data/ # 数据模型 & API 接口
|
||
│ │ │ ├── service/ # VoiceInteractionService & WebSocket & FCM
|
||
│ │ │ ├── voice/ # 热词唤醒 (Hotword) & STT & TTS
|
||
│ │ │ └── di/ # 依赖注入
|
||
│ │ └── res/ # 资源文件
|
||
│ └── build.gradle.kts
|
||
├── build.gradle.kts
|
||
├── settings.gradle.kts
|
||
└── gradle.properties
|
||
```
|
||
|
||
## 环境要求
|
||
|
||
- Android Studio Hedgehog (2023.1.1) 或更高版本
|
||
- Kotlin 2.0+
|
||
- JDK 17+
|
||
- Android SDK (target: 34+, min: 26+)
|
||
|
||
## 网络配置（中国大陆用户）
|
||
|
||
Gradle、Google Maven、Maven Central 等服务器在国内访问缓慢或不可达，首次同步前需配置镜像。
|
||
|
||
### Gradle Wrapper
|
||
|
||
`gradle/wrapper/gradle-wrapper.properties`：
|
||
|
||
```properties
|
||
# 将 services.gradle.org 替换为腾讯/阿里镜像
|
||
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip
|
||
# 或阿里: https\://mirrors.aliyun.com/macports/distfiles/gradle/gradle-8.7-bin.zip
|
||
```
|
||
|
||
### 仓库镜像
|
||
|
||
`settings.gradle.kts` 顶部添加：
|
||
|
||
```kotlin
|
||
pluginManagement {
|
||
repositories {
|
||
maven { url = uri("https://mirrors.cloud.tencent.com/gradle/plugins") }
|
||
maven { url = uri("https://mirrors.tencent.com/nexus/repository/maven-public") }
|
||
google()
|
||
mavenCentral()
|
||
gradlePluginPortal()
|
||
}
|
||
}
|
||
dependencyResolutionManagement {
|
||
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
|
||
repositories {
|
||
maven { url = uri("https://mirrors.tencent.com/nexus/repository/maven-public") }
|
||
google()
|
||
mavenCentral()
|
||
}
|
||
}
|
||
```
|
||
|
||
### Gradle 属性
|
||
|
||
`gradle.properties`：
|
||
|
||
```properties
|
||
# HTTP 代理（如使用 Clash/V2Ray，通常不需要）
|
||
# systemProp.http.proxyHost=127.0.0.1
|
||
# systemProp.http.proxyPort=7890
|
||
# systemProp.https.proxyHost=127.0.0.1
|
||
# systemProp.https.proxyPort=7890
|
||
```
|
||
|
||
### Android SDK Proxy
|
||
|
||
若 Android SDK Manager 也下载缓慢，可在 Android Studio 中设置：
|
||
**Settings → Appearance & Behavior → System Settings → HTTP Proxy**
|
||
|
||
配置为 `mirrors.cloud.tencent.com` 或 `mirrors.neusoft.edu.cn`，端口 `80`。
|
||
|
||
## 快速开始
|
||
|
||
> 项目尚未包含可构建的源码，以下为后续开发的参考步骤。
|
||
|
||
1. 用 Android Studio 打开 `android/` 目录
|
||
2. 按上述"网络配置"替换国内镜像
|
||
3. 等待 Gradle 同步完成
|
||
4. 启动主项目后端服务（参考[主项目 README](../README.md)）
|
||
5. 在 `local.properties` 中配置 `baseUrl` 指向 Gateway 地址
|
||
6. 选择模拟器或设备，点击 Run
|
||
|
||
## 相关链接
|
||
|
||
- [Cyrene 主项目](../) — 后端服务、前端、部署文档
|
||
- [开发路线图](../docs/dev-plan/00-development-roadmap.md)
|
||
- [多平台接入方案](../docs/dev-plan/03-multi-platform-integration.md)
|
||
- [语音系统计划](../docs/dev-plan/04-voice-system-plan.md)
|
||
|
||
## License
|
||
|
||
Apache-2.0
|