feat:v1.0.0

wei_ai_app/优化.md

@@ -0,0 +1,85 @@
+ 我已经详细阅读了整个 interaction
+  模块和相关服务代码，以下是完整的架构分析和优化建议：
+
+  ---
+  架构概览
+
+  screens/interaction/
+  ├── interaction_screen.dart          # 文字聊天 UI
+  ├── voice_mode_overlay.dart          # 语音通话 UI
+  └── voice_session_controller.dart    # 语音状态编排
+
+  core/services/
+  ├── chat_service.dart                # LLM API (SSE 流式)
+  ├── chat_storage_service.dart        # SharedPreferences 持久化
+  ├── stt_service.dart                 # 系统 STT (已废弃)
+  ├── vad_stt_service.dart             # Silero VAD + Google Cloud STT
+  ├── tts_service.dart                 # TTS 门面 + 引擎选择
+  └── tts/
+      ├── tts_engine.dart              # 抽象接口
+      ├── minimax_tts_engine.dart      # MiniMax WebSocket 流式 TTS
+      ├── system_tts_engine.dart       # 系统 TTS 兜底
+      └── ws_client_*.dart             # 跨平台 WebSocket
+
+  整体评价: 服务分层清晰，TTS 的抽象接口设计不错，语音对话的"句子级 TTS +
+  预连接"体验优化做得挺好。但有几个明显需要处理的问题：
+
+  ---
+  需要优化的问题 (按优先级)
+
+  P0 - 安全问题
+
+  1. API Key 硬编码 — minimax_config.dart 中 MiniMax JWT 和 vad_stt_service.dart
+   中 Google Cloud STT API Key 直接写在代码里。APK 反编译即可提取，存在严重的
+  Key 被盗刷风险。
+    - 建议: 所有第三方 API 调用走后端代理，客户端不存放任何 Key
+
+  P1 - 潜在 Bug
+
+  2. 消息重复保存 — InteractionScreen._sendMessage() 会保存消息到
+  storage，语音流程中 VoiceSessionController._processUserMessage()
+  也通过回调保存。如果两个流程不小心交叉，可能产生重复消息。
+    - 建议: 统一消息保存入口，只在一处写入
+  3. 句子缓冲丢失 — _sentenceBuffer
+  在流式结束或网络中断时，未说完的文本会丢失（TTS 不完整但文字显示完整）。
+    - 建议: 流结束时 flush 残留 buffer，增加超时机制（如 2s 无标点则强制切句）
+  4. 语音打断时资源泄漏 — 用户在 TTS 播放中关闭语音界面，_speakCompleter
+  可能不会被 complete，定时器可能继续运行。
+    - 建议: dispose() 中强制 complete 所有 Completer，取消所有 Timer
+  5. WebSocket 连接泄漏 — 退出语音模式后 TTS WebSocket
+  连接没有显式关闭，可能造成连接泄漏。
+    - 建议: 退出语音模式时显式调用 disconnect
+
+  P2 - 架构优化
+
+  6. 状态管理不统一 — InteractionScreen 用 Riverpod + setState
+  混合，VoiceSessionController 用 ChangeNotifier。风格不一致，维护成本高。
+    - 建议: 统一用 Riverpod，VoiceSessionController 迁移为 StateNotifierProvider
+  7. 服务紧耦合 — VoiceSessionController 直接 new VadSttService() /
+  TTSService()，无法做单元测试。
+    - 建议: 通过依赖注入 (Riverpod Provider) 注入服务实例
+  8. 存储性能 — SharedPreferences 每次写入都序列化整个 session
+  JSON，消息多了会卡。
+    - 建议: 考虑换用 Isar/Hive 等本地数据库，支持增量写入和分页加载
+
+  P3 - 体验优化
+
+  9. 无重试机制 — Google STT API
+  调用失败时没有重试逻辑，网络抖动直接导致语音识别失败。
+    - 建议: 增加 1-2 次重试，带指数退避
+  10. 未完成功能 — VoiceModeOverlay 的扬声器切换按钮是空实现 (onPressed: ()
+  {})，波形动画是固定的不跟实际音频挂钩。
+  11. 流式响应类型安全 — ChatService._sendStreamRequest() 中 JSON 解析用了
+  dynamic 类型，API 返回异常格式时可能 crash。
+
+  ---
+  做得好的地方
+
+  - TTS 引擎抽象 + MiniMax/System 自动降级兜底
+  - WebSocket 预连接 降低首次语音响应延迟
+  - 句子级流式 TTS 而非等全文，对话体感自然
+  - 30s keep-alive ping 保持连接复用
+  - LLM 流式渲染 + 打字动画，用户反馈及时
+
+  ---
+  要我针对某个具体问题开始修复吗？比如先处理 P1 的 bug 或 P2 的架构重构？