257 lines
8.1 KiB
Markdown
257 lines
8.1 KiB
Markdown
# 01 — 系统语音助手集成规范
|
||
|
||
> **目标**：让昔涟成为 Android 系统级默认语音助手，替换 Google Assistant / Bixby
|
||
> **核心 API**：`VoiceInteractionService` + `VoiceInteractionSession`
|
||
|
||
---
|
||
|
||
## 1. 功能目标
|
||
|
||
- 用户可在 **系统设置 → 默认应用 → 数字助理** 中选择昔涟
|
||
- 长按 Home 键呼出昔涟（非全屏，悬浮覆盖层）
|
||
- 屏幕底部两角向内滑动触发昔涟
|
||
- 长按电源键可配置为呼出昔涟
|
||
- 息屏状态下热词唤醒昔涟
|
||
- 有线/蓝牙耳机按键呼出昔涟
|
||
|
||
## 2. AndroidManifest.xml 声明
|
||
|
||
```xml
|
||
<!-- VoiceInteractionService -->
|
||
<service
|
||
android:name=".service.CyreneVoiceInteractionService"
|
||
android:exported="true"
|
||
android:permission="android.permission.BIND_VOICE_INTERACTION">
|
||
|
||
<meta-data
|
||
android:name="android.voice_interaction"
|
||
android:resource="@xml/voice_interaction_config" />
|
||
|
||
<intent-filter>
|
||
<action android:name="android.service.voice.VoiceInteractionService" />
|
||
</intent-filter>
|
||
</service>
|
||
|
||
<!-- AssistService (Android 14+) -->
|
||
<service
|
||
android:name=".service.CyreneAssistService"
|
||
android:exported="true"
|
||
android:permission="android.permission.BIND_ASSIST">
|
||
|
||
<intent-filter>
|
||
<action android:name="android.service.voice.AssistService" />
|
||
</intent-filter>
|
||
</service>
|
||
```
|
||
|
||
## 3. 配置文件
|
||
|
||
### res/xml/voice_interaction_config.xml
|
||
|
||
```xml
|
||
<?xml version="1.0" encoding="utf-8"?>
|
||
<voice-interaction-service
|
||
xmlns:android="http://schemas.android.com/apk/res/android"
|
||
android:sessionService=".service.CyreneVoiceInteractionSession"
|
||
android:recognitionService=".service.CyreneRecognitionService"
|
||
android:supportsAssist="true"
|
||
android:supportsLaunchVoiceAssistFromKeyguard="true"
|
||
android:supportsLocalRecognition="true"
|
||
android:serviceIcon="@drawable/ic_cyrene"
|
||
android:serviceLabel="@string/voice_assistant_name" />
|
||
```
|
||
|
||
## 4. VoiceInteractionService 实现
|
||
|
||
```kotlin
|
||
class CyreneVoiceInteractionService : VoiceInteractionService() {
|
||
|
||
override fun onReady() {
|
||
super.onReady()
|
||
// 服务就绪，可在此初始化 TTS 引擎等
|
||
}
|
||
|
||
override fun onCreateSession(args: Bundle?): VoiceInteractionSession {
|
||
return CyreneVoiceInteractionSession(this)
|
||
}
|
||
|
||
override fun onLaunchVoiceAssistFromKeyguard() {
|
||
// 锁屏启动 → 进入简化模式，仅显示对话，IoT 控制等需先解锁
|
||
}
|
||
|
||
// Android 14+: AssistAction 回调
|
||
override fun onHandleAssist(
|
||
request: AssistRequest?,
|
||
cancellationSignal: CancellationSignal?,
|
||
callback: OutcomeCallback<AssistResult?>?
|
||
) {
|
||
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
|
||
request?.let {
|
||
val assistContent = it.assistContent
|
||
// 提取当前屏幕上下文（可选，用于后续上下文感知）
|
||
callback?.onResult(AssistResult(assistContent))
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 5. VoiceInteractionSession 实现（悬浮窗界面）
|
||
|
||
```kotlin
|
||
class CyreneVoiceInteractionSession(context: Context) :
|
||
VoiceInteractionSession(context) {
|
||
|
||
override fun onCreateContentView(): View {
|
||
// 返回 ComposeView 作为悬浮窗的内容
|
||
return ComposeView(context).apply {
|
||
setContent {
|
||
CyreneTheme {
|
||
OverlayScreen(
|
||
viewModel = overlayViewModel,
|
||
onDismiss = { finish() }
|
||
)
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
override fun onShow(args: Bundle?, showFlags: Int) {
|
||
super.onShow(args, showFlags)
|
||
// 设置窗口属性：透明背景 + 底部卡片式布局
|
||
window?.apply {
|
||
// 半透明遮罩
|
||
setBackgroundDrawable(ColorDrawable(0x80000000.toInt()))
|
||
// FLAG_DIM_BEHIND 可实现模糊效果
|
||
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
|
||
addSystemGestureExclusionRects(...)
|
||
}
|
||
}
|
||
}
|
||
|
||
override fun onComputeInsets(outInsets: Insets?) {
|
||
super.onComputeInsets(outInsets)
|
||
// 控制悬浮窗内容区域
|
||
}
|
||
|
||
override fun onHide() {
|
||
super.onHide()
|
||
// 悬浮窗隐藏时清理状态
|
||
}
|
||
}
|
||
```
|
||
|
||
### 关键窗口属性
|
||
|
||
| 属性 | 值 | 说明 |
|
||
|------|-----|------|
|
||
| 背景 | `ColorDrawable(0x80000000)` | 半透明黑色遮罩，透出底层 APP |
|
||
| 内容区域 | 自适应高度 | 底部弹出，类似 Google Assistant |
|
||
| 触摸外区域行为 | 关闭悬浮窗 | 用户点击遮罩区域关闭 |
|
||
| 键盘弹出 | 推高内容区域 | 文本输入时自动调整 |
|
||
|
||
## 6. 权限清单
|
||
|
||
```xml
|
||
<!-- 核心语音助手权限 -->
|
||
<uses-permission android:name="android.permission.BIND_VOICE_INTERACTION" />
|
||
<uses-permission android:name="android.permission.BIND_ASSIST" />
|
||
|
||
<!-- 音频相关 -->
|
||
<uses-permission android:name="android.permission.RECORD_AUDIO" />
|
||
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
|
||
|
||
<!-- 热词唤醒 -->
|
||
<uses-permission android:name="android.permission.CAPTURE_AUDIO_HOTWORD" />
|
||
|
||
<!-- 后台服务 -->
|
||
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
|
||
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
|
||
|
||
<!-- 网络 -->
|
||
<uses-permission android:name="android.permission.INTERNET" />
|
||
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
|
||
|
||
<!-- 推送 -->
|
||
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
|
||
|
||
<!-- 锁屏交互 -->
|
||
<uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT" />
|
||
```
|
||
|
||
## 7. 引导用户设为默认助手
|
||
|
||
首次启动时检测并引导：
|
||
|
||
```kotlin
|
||
fun checkAndPromptDefaultAssistant(context: Context) {
|
||
val isDefault = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
|
||
val componentName = ComponentName(context, CyreneVoiceInteractionService::class.java)
|
||
context.packageManager
|
||
.queryIntentServices(
|
||
Intent(VoiceInteractionService.SERVICE_INTERFACE),
|
||
PackageManager.MATCH_DEFAULT_ONLY
|
||
)
|
||
.any { it.serviceInfo.packageName == context.packageName }
|
||
} else {
|
||
false
|
||
}
|
||
|
||
if (!isDefault) {
|
||
// 显示引导 UI → 跳转到 Settings.ACTION_VOICE_INPUT_SETTINGS
|
||
val intent = Intent(Settings.ACTION_VOICE_INPUT_SETTINGS)
|
||
context.startActivity(intent)
|
||
}
|
||
}
|
||
```
|
||
|
||
## 8. 热词唤醒检测
|
||
|
||
### 方案选型
|
||
|
||
| 方案 | 优点 | 缺点 | 适用场景 |
|
||
|------|------|------|---------|
|
||
| 系统 Always-On Hotword API | 低功耗、系统级支持 | 限 Android 8+，某些 ROM 不支持 | **首选** |
|
||
| Porcupine (Picovoice) | 跨平台、离线 | 商业许可，需额外集成 | 兜底 |
|
||
| 自建模型 (openWakeWord) | 完全可控、低成本 | 需要本地推理能力 | 长期方案 |
|
||
|
||
### 唤醒词配置
|
||
|
||
| 优先级 | 唤醒词 | 说明 |
|
||
|--------|--------|------|
|
||
| P0 | "昔涟" (Xī Lián) | 角色名，默认唤醒词 |
|
||
| P1 | "Hey 昔涟" | 与 "Hey Google" 习惯对齐 |
|
||
| P2 | 自定义 | 用户可在设置中自定义 |
|
||
|
||
### 息屏唤醒流程
|
||
|
||
```
|
||
用户说出唤醒词
|
||
→ HotwordDetector 识别成功（<800ms）
|
||
→ 系统触发 VoiceInteractionService
|
||
→ CyreneVoiceInteractionSession.onCreateContentView()
|
||
→ Overlay 显示，播放连接提示音
|
||
→ 用户说话 → STT → AI-Core → TTS → 语音回复
|
||
→ 对话结束 → finish() → 息屏
|
||
```
|
||
|
||
## 9. Dismiss 时机
|
||
|
||
悬浮窗在以下情况关闭：
|
||
|
||
| 条件 | 行为 |
|
||
|------|------|
|
||
| 用户说"再见" / "退下" | 自然对话结束，收起悬浮窗 |
|
||
| 用户点击遮罩区域 | 立即关闭 |
|
||
| 对话静默 10 秒 | 自动收起 |
|
||
| 用户主动滑动关闭 | 手势关闭，同 Google Assistant |
|
||
| 收到系统电话等中断 | 暂停语音，进入后台等待 |
|
||
|
||
## 10. 降级策略
|
||
|
||
当系统不支持 `VoiceInteractionService` 或未设为默认助手时：
|
||
|
||
- **保底方案**：PWA（利用主项目已有的 PWA 支持）
|
||
- **WebView 封装**：内嵌 H5 对话界面作为过渡
|
||
- **通知栏常驻**：提供快速对话入口，但功能受限
|