# 04 — 功能规格说明书

> **版本**：MVP v0.1 → Stable v1.0  
> **优先级定义**：P0 = 不可缺失 | P1 = 首个正式版必需 | P2 = 后续版本

---

## 1. 功能总览

### MVP (v0.1) — 核心语音助手

| # | 功能 | 优先级 | 说明 |
|---|------|--------|------|
| F01 | VoiceInteractionService 注册 | P0 | 系统可识别并设为默认助手 |
| F02 | 语音唤醒（热词"昔涟"） | P0 | 息屏/亮屏唤醒 |
| F03 | 悬浮覆盖层对话 | P0 | VoiceInteractionSession 界面 |
| F04 | STT 语音识别 | P0 | 实时语音转文字 |
| F05 | TTS 语音合成 | P0 | 文字转语音回复 |
| F06 | 实时文字对话 | P0 | WebSocket 双向通信 |
| F07 | 用户认证与登录 | P0 | Token 持久化 |

### v0.5 — 功能完善

| # | 功能 | 优先级 | 说明 |
|---|------|--------|------|
| F08 | IoT 设备状态查询 | P1 | 只读查询设备状态 |
| F09 | IoT 设备控制 | P1 | 开关/调节设备 |
| F10 | 推送通知 (FCM) | P1 | 昔涟主动消息、提醒 |
| F11 | 多会话历史 | P1 | 查看历史对话记录 |
| F12 | 提醒管理 | P1 | 创建/查看/删除提醒 |
| F13 | 全屏 Activity 模式 | P1 | 桌面图标入口、完整功能 |
| F14 | 暗黑模式 | P1 | 跟随系统 / 手动切换 |
| F15 | 自定义唤醒词 | P2 | 用户可修改唤醒词 |

### v1.0 — 正式版

| # | 功能 | 优先级 | 说明 |
|---|------|--------|------|
| F16 | 记忆查看 | P1 | 浏览昔涟的记忆 |
| F17 | 自动化规则 | P2 | 查看/触发自动化场景 |
| F18 | 知识库查询 | P2 | 检索知识文档 |
| F19 | 文件上传 | P2 | 图片上传与分析 |
| F20 | 后台思考展示 | P2 | 查看昔涟的思考内容 |
| F21 | 多设备同步 | P2 | Web 端和 Android 端对话同步 |
| F22 | 画中画语音通话 | P2 | 持续语音对话的 PIP 模式 |
| F23 | 主题自定义 | P2 | 预设主题色切换 |
| F24 | 离线兜底 | P2 | 无网络时的本地回复 |

---

## 2. P0 功能详细规格

### F01 · VoiceInteractionService 注册

**用户故事**：作为用户，我可以在系统设置中将昔涟设为默认语音助手。

**验收标准**：
- [ ] AndroidManifest.xml 正确声明 `VoiceInteractionService`
- [ ] 系统 **设置 → 默认应用 → 数字助理** 列表中可见 "昔涟"
- [ ] 选中后，长按 Home 键可触发昔涟
- [ ] 选中后，底部两角滑动可触发昔涟
- [ ] 未设为默认时，APP 内显示引导卡片并一键跳转设置页

**技术依赖**：无

---

### F02 · 语音唤醒

**用户故事**：作为用户，我可以在息屏或使用其他 APP 时说"昔涟"直接唤起助手。

**验收标准**：
- [ ] 息屏状态下说出"昔涟"可唤醒（成功率 ≥ 95%，安静环境）
- [ ] 亮屏使用其他 APP 时说出"昔涟"可唤醒
- [ ] 唤醒后显示悬浮覆盖层，播放提示音
- [ ] 10 分钟无交互自动停止热词监听以省电
- [ ] 用户可在设置中开启/关闭息屏唤醒
- [ ] 误唤醒率 ≤ 5 次/天（正常使用环境）

**技术依赖**：F01 (VoiceInteractionService)，`CAPTURE_AUDIO_HOTWORD` 权限

---

### F03 · 悬浮覆盖层对话

**用户故事**：作为用户，语音唤醒昔涟后看到半透明覆盖层，不影响当前使用的 APP。

**验收标准**：
- [ ] 底部滑入动画 300ms，覆盖层显示
- [ ] 半透明黑色遮罩透出底层 APP 内容
- [ ] 对话卡片顶部圆角 28dp，自适应高度（最大 70% 屏幕）
- [ ] 点击遮罩区域关闭覆盖层
- [ ] 下滑卡片关闭覆盖层
- [ ] 静默 10 秒自动收起
- [ ] 用户说"再见"/"退下"自然结束对话
- [ ] 关闭后回到触发前状态，不压入任何 Activity 栈

**技术依赖**：F01 (VoiceInteractionService)

---

### F04 · STT 语音识别

**用户故事**：作为用户，我可以对昔涟说话，她会实时将我的语音转成文字。

**验收标准**：
- [ ] 覆盖层显示时自动开始监听
- [ ] 实时显示识别中间结果（流式 STT）
- [ ] 语音结束（静默 1.5s）后自动提交识别结果
- [ ] 识别结果以用户气泡形式显示在对话中
- [ ] 安静环境识别准确率 ≥ 95%（中文普通话）
- [ ] 支持噪音环境降噪

**技术依赖**：后端 Whisper API (voice-service :8093)，`RECORD_AUDIO` 权限

---

### F05 · TTS 语音合成

**用户故事**：作为用户，昔涟可以用自然的声音读出她的回复。

**验收标准**：
- [ ] 流式 TTS：收到 LLM 第一个 token 即开始合成
- [ ] 语音自然流畅，无机械感（使用后端 Edge-TTS 或训练模型）
- [ ] 播放完毕自动进入下一轮监听
- [ ] 播放期间自动降低其他音频音量（Audio Focus）
- [ ] 用户可在设置中调整语速、音量

**技术依赖**：后端 TTS API (voice-service :8093)

---

### F06 · 实时文字对话

**用户故事**：作为用户，我可以打字与昔涟交流，并实时看到她的回复。

**验收标准**：
- [ ] WebSocket 连接建立后保持心跳 (30s ping)
- [ ] 文本消息发送后 200ms 内显示用户气泡
- [ ] 昔涟回复流式显示（逐字/逐 token 渲染）
- [ ] 正确处理 `chat`、`action`、`thinking` 三种消息类型
- [ ] 断线自动重连（指数退避，最多 5 次）
- [ ] 连接状态在界面实时指示
- [ ] 多条消息按时间顺序排列
- [ ] 支持消息滚动到顶部加载历史

**技术依赖**：后端 Gateway WebSocket (:8080)

---

### F07 · 用户认证与登录

**用户故事**：作为用户，我可以登录我的 Cyrene 账号以同步数据。

**验收标准**：
- [ ] 首次启动显示登录页
- [ ] 支持输入 Gateway 地址 + 账号 + 密码
- [ ] 登录成功保存 JWT Token 到 EncryptedDataStore
- [ ] Token 过期自动刷新（refresh token）
- [ ] 再次启动自动登录（skip login page）
- [ ] 登录失败显示明确错误信息
- [ ] 支持退出登录并清除本地数据

**技术依赖**：后端 Gateway Auth API (:8080)

---

## 3. P1 功能详细规格

### F08 · IoT 设备状态查询

**验收标准**：
- [ ] 全屏 Activity 中 IoT Tab 显示所有设备卡片
- [ ] 实时显示设备状态（开/关、亮度、温度等）
- [ ] 通过 WebSocket 接收状态变更推送
- [ ] 覆盖层模式下支持语音查询（"灯开着吗？"）
- [ ] 覆盖层模式下 IoT 查询结果以文字+卡片形式展示
- [ ] 锁屏状态下仅允许查询

### F09 · IoT 设备控制

**验收标准**：
- [ ] 设备卡片上可直接开关/调节
- [ ] 支持语音控制（"打开客厅灯"）
- [ ] 控制结果实时反馈（成功/失败）
- [ ] 锁屏状态下禁止控制，提示解锁
- [ ] 支持设备白名单（每用户可控制的设备不同）

### F10 · 推送通知 (FCM)

**验收标准**：
- [ ] 接收昔涟主动消息推送
- [ ] 接收提醒到期推送
- [ ] 接收 IoT 状态变更推送
- [ ] 点击通知打开对应界面
- [ ] 通知渠道分组（对话 / 提醒 / IoT / 系统）
- [ ] 用户可独立控制各渠道开关

### F11 · 多会话历史

**验收标准**：
- [ ] 对话列表页展示所有历史会话
- [ ] 每条会话显示标题、最后一条消息预览、时间
- [ ] 点击进入对应会话详情
- [ ] 支持删除会话
- [ ] 与 Web 端历史同步

### F12 · 提醒管理

**验收标准**：
- [ ] 可以语音创建提醒（"提醒我下午三点开会"）
- [ ] 列表展示所有活跃提醒
- [ ] 支持删除/标记完成
- [ ] 到期时 FCM 推送 + 覆盖层显示

### F13 · 全屏 Activity 模式

**验收标准**：
- [ ] 桌面图标启动进入全屏界面
- [ ] BottomNav 三 Tab（对话 / IoT / 我的）
- [ ] 完整的设置页
- [ ] 与覆盖层共享同一 WebSocket 连接和 ViewModel

### F14 · 暗黑模式

**验收标准**：
- [ ] 跟随系统暗黑模式自动切换
- [ ] 用户可在设置中手动选择 Light / Dark / Auto
- [ ] 覆盖层同步使用当前主题
- [ ] 对话气泡、卡片、输入框颜色正确适配

---

## 4. P2 功能概要

| # | 功能 | 关键验收标准 |
|---|------|------------|
| F15 | 自定义唤醒词 | 设置页可输入自定义词，验证唯一性，测试唤醒效果 |
| F16 | 记忆查看 | 时间线展示昔涟记忆，支持搜索过滤 |
| F17 | 自动化规则 | 查看规则列表，手动触发，查看执行日志 |
| F18 | 知识库查询 | 搜索文档，查看内容，语音问答 |
| F19 | 文件上传 | 图片选择/拍照，缩略图预览，AI 分析结果 |
| F20 | 后台思考 | 展示昔涟后台思考片段，可折叠面板 |
| F21 | 多设备同步 | Web 端和 Android 端对话实时同步 |
| F22 | PIP 语音通话 | 切换到 PIP 窗口进行持续语音对话 |
| F23 | 主题自定义 | 从预设色中选择，实时预览 |
| F24 | 离线兜底 | 无网络时显示离线提示，缓存本地回复模板 |

---

## 5. 按开发阶段分组

### Sprint 1 (MVP)：F01 → F07 (P0 全部)
目标：可设为系统默认助手，能语音唤醒并对话

### Sprint 2：F08 → F14 (P1 全部)
目标：IoT 控制、全屏界面、推送通知上线

### Sprint 3+：F15 → F24 (P2 逐个)
目标：体验完善、高级功能

## 6. 非功能需求

| 类别 | 需求 | 指标 |
|------|------|------|
| 性能 | 覆盖层冷启动 | < 500ms |
| 性能 | 语音识别端到端延迟 | < 2s (STT + LLM + TTS) |
| 性能 | WebSocket 消息延迟 | < 100ms |
| 稳定性 | 崩溃率 | < 0.5% |
| 电量 | 热词监听功耗 | < 3% 电池/小时 (息屏) |
| 网络 | 支持弱网 | 切换到低码率 TTS |
| 兼容性 | 国内 ROM 适配 | MIUI / ColorOS / OriginOS / HarmonyOS |