# 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