9.4 KiB
9.4 KiB
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 |