feat: 添加 ASR 项目架构总结文档

ARCHITECTURE_SUMMARY.md

@@ -0,0 +1,175 @@
+# ASR 项目架构总结
+
+## 概述
+
+该仓库包含一个实时语音识别和 AI 助手系统，主要由以下部分组成：
+
+1. `asr_agent/` - 后端 ASR + LLM + TTS Worker 逻辑。
+2. `flutter_asr_client/` - Flutter 移动客户端应用。
+3. `livekit-server/` - LiveKit 部署配置。
+
+系统使用 LiveKit 进行实时音频传输和数据通道消息传递，并结合本地 ASR 和可选的云服务备用方案。
+
+---
+
+## 1. 后端 (`asr_agent/`)
+
+### 1.1 入口与服务层
+
+- `dispatcher.py`
+  - 提供 `POST /connect`：创建唯一房间、生成 LiveKit token，并启动对应房间的 `Worker`。
+  - 提供 `GET /health`：检查并清理已结束的 Worker。
+  - 使用 `aiohttp` 提供 HTTP 接口。
+
+### 1.2 Worker 运行时
+
+- `worker.py`
+  - `Worker` 作为机器人连接到 LiveKit 房间。
+  - 监听参与者的远端音频轨道。
+  - 执行管道：VAD -> ASR -> LLM -> TTS。
+  - 通过 LiveKit 数据通道发布实时转写和回复事件。
+  - 通过本地音频轨道发布合成语音。
+
+### 1.3 语音处理流水线
+
+- VAD：优先使用 Silero VAD ONNX 模型，否则回退到能量检测。
+- ASR：
+  - 默认使用本地 `Qwen3-ASR` 模型，封装在 `whisper_asr/qwen_engine.py`。
+  - 可通过 `ASR_PROVIDER=mimo` 切换为远程 Mimo ASR。
+- LLM：
+  - 默认使用本地 vLLM REST/SSE 接口（`VLLM_URL`）。
+  - 可通过 `LLM_PROVIDER=mimo` 切换为云端 Mimo LLM。
+- TTS：
+  - 使用 Mimo API 进行语音合成。
+  - `_TTSSegmenter` 实现二级分句，保证语音播放更流畅。
+
+### 1.4 支持模块
+
+- `whisper_asr/audio_processor.py`
+  - 负责音频缓冲、PCM 转换、语音活动检测、队列管理。
+- `whisper_asr/qwen_engine.py`
+  - 封装 Qwen3-ASR 模型加载和转写接口。
+
+### 1.5 关键技术
+
+- `livekit` Python RTC 客户端
+- `onnxruntime` + Silero VAD
+- `qwen_asr` 本地语音模型
+- `aiohttp` 异步 Web 服务器
+- `pyjwt` 生成 LiveKit token
+
+---
+
+## 2. Flutter 客户端 (`flutter_asr_client/`)
+
+### 2.1 应用入口与路由
+
+- `lib/main.dart`
+  - 启动 `ProviderScope`，并注入 `LiveKitServiceImpl`。
+- `lib/app.dart`
+  - 使用 Riverpod 和 GoRouter 创建 `MaterialApp.router`。
+- `lib/router/app_router.dart`
+  - 定义主应用导航：
+    - `/tasks`
+    - `/records`
+    - `/reports`
+    - `/profile`
+    - `/recording`
+
+### 2.2 状态与业务逻辑
+
+- `lib/providers/livekit_providers.dart`
+  - 定义 `LiveKitService` 抽象。
+  - 暴露消息流和房间名提供者。
+- `lib/providers/settings_providers.dart`
+  - 提供应用设置和服务 URL。
+- `lib/pages/recording/notifiers/recording_notifier.dart`
+  - 管理录音生命周期。
+  - 请求 Dispatcher 房间信息。
+  - 连接 LiveKit 并订阅服务端消息流。
+  - 处理实时转写、AI 回复、暂停/恢复和结束录音。
+
+### 2.3 LiveKit 服务封装
+
+- `lib/services/livekit_service.dart`
+  - 实现 `LiveKitService`。
+  - 连接 LiveKit 并发布麦克风音频。
+  - 监听数据通道中的 `transcription` 消息。
+  - 包含开发环境下的 JWT 生成逻辑。
+
+### 2.4 音频采集服务
+
+- `lib/services/audio_capture_service.dart`
+  - 使用 `record` 插件采集 PCM16 音频。
+  - 暴露音量流和录音开始/停止方法。
+  - 注意：应用真实音频传输路径是通过 LiveKit 麦克风发布。
+
+### 2.5 UI 层
+
+- `lib/pages/shell/app_shell.dart`
+  - 底部导航壳，带中央 FAB 进入录音。
+- `lib/pages/recording/recording_page.dart`
+  - 录音页面，显示实时话语、AI 回复、连接状态和控制按钮。
+
+### 2.6 数据模型
+
+- `lib/models/websocket_message.dart`
+  - 定义客户端请求消息与服务端消息类型。
+  - 服务端消息包括 `connected`、`partial`、`utterance`、`reply`、`reply_partial`、`transcript`、`error`。
+
+---
+
+## 3. LiveKit 部署
+
+- `livekit-server/docker-compose.yml`
+- `livekit-server/livekit.yaml`
+
+这些文件配置了应用和后端使用的 LiveKit 实时音频房间服务。
+
+---
+
+## 4. 端到端流程
+
+1. Flutter 应用进入录音页面。
+2. `RecordingNotifier` 调用 Dispatcher 的 `/connect`。
+3. Dispatcher 创建 LiveKit 房间并返回 URL/room/token。
+4. Flutter 连接 LiveKit 并发布麦克风音频流。
+5. Dispatcher 为该房间启动一个 `Worker`。
+6. Worker 加入房间，订阅参与者音频并运行 VAD。
+7. 语音片段通过 ASR 转写。
+8. 转写与回复更新通过 LiveKit 数据通道传递给客户端。
+9. Worker 还可能合成回复音频并发布到房间。
+10. 客户端显示实时文本，并可听到 AI 语音。
+
+---
+
+## 5. 系统特性
+
+- 房间级 Worker 模型：每次连接创建一个 Worker。
+- 音频轨道 + 数据通道结合架构。
+- 本地/云混合能力：本地 Qwen ASR / vLLM，可选 Mimo 备用。
+- Flutter 前端使用 Riverpod 状态管理和 GoRouter 路由。
+- 后端通过环境变量配置，前端通过 SharedPreferences 配置。
+
+---
+
+## 6. 配置点
+
+- 后端环境变量：
+  - `LIVEKIT_URL`、`PUBLIC_LIVEKIT_URL`
+  - `ASR_MODEL_PATH`
+  - `VLLM_URL`、`LLM_MODEL`
+  - `MIMO_KEY`、`MIMO_API_BASE`
+  - `LLM_PROVIDER`、`ASR_PROVIDER`
+- Flutter 设置：
+  - Dispatcher URL
+  - LiveKit URL
+  - WebSocket 后端 host/port
+
+---
+
+## 7. 备注
+
+- Dispatcher 使用开发 JWT 密钥和房间创建逻辑，生产环境应替换。
+- Flutter 应用中录音状态包含固定测试/演示元数据。
+- 后端 Worker 目前将转写与 AI 回复生成放在同一个服务流中。