mkbk
64 lines
3.1 KiB
Markdown
64 lines
3.1 KiB
Markdown
# 完整全双工 Agent 运行时设计
|
||
|
||
## 背景
|
||
|
||
当前 `run-agent-live` 通过 `build_live_runtime(config).run_agent()` 复用旧 `VoiceAssistantPipeline`。这条路径只在 TTS 播放时启动临时监听，无法满足持续监听、持续识别、全局可取消和 WebRTC APM 音频底座要求。本设计新增独立 `FullDuplexAgentRuntime`，将旧 pipeline 降级为 `run-live` 专用稳定路径。
|
||
|
||
## 数据流
|
||
|
||
1. `SoundDeviceAudioTransport` 只负责设备 I/O。
|
||
2. `AudioHub` 读取麦克风 raw frame，写 raw capture ring。
|
||
3. `WebRtcAudioProcessingStage` 使用 render reference 处理 raw capture，写 processed capture ring。
|
||
4. `ContinuousVadWorker` 消费 processed capture，发布 speech_start/speech_end。
|
||
5. `StreamingSttWorker` 消费同一 processed capture，发布 partial/stable/final transcript。
|
||
6. `InterruptController` 订阅 VAD 事件和 state machine，在 thinking/speaking/tool_running 中触发 cancellation。
|
||
7. `ConversationManager` 收到 final transcript 后构建短期上下文、memory context、LLM request。
|
||
8. LLM streaming delta 进入 sentence segmenter。
|
||
9. Streaming TTS 产出 PCM chunk，`InterruptiblePlaybackQueue` 播放并写 render reference。
|
||
10. Tool calls 进入 `ToolRouter`，结果回注入 LLM。
|
||
|
||
## 并发模型
|
||
|
||
后台任务：
|
||
|
||
1. `audio_capture_task`
|
||
2. `apm_process_task`
|
||
3. `vad_task`
|
||
4. `streaming_stt_task`
|
||
5. `conversation_task`
|
||
6. `playback_task`
|
||
7. `tool_task`，按需创建
|
||
|
||
所有任务使用 `CancellationGraph` 管理。用户打断时取消当前 response 子图，不关闭 audio hub；进程退出时取消 root token 并关闭所有订阅。
|
||
|
||
## 状态管理
|
||
|
||
状态机使用现有 `PipelineState` 枚举，不再在 `run-agent-live` 中用隐式 list 记录状态。每个转移必须发 event。非法转移在测试中失败。
|
||
|
||
## Provider 策略
|
||
|
||
1. APM：`webrtc` 为完整模式默认且 required；`fake` 仅 self-test；`disabled` 只允许开发降级，不算完整验收。
|
||
2. STT：`faster_whisper` 为开发默认；`sherpa_onnx` fallback；`sensevoice` 预留。
|
||
3. TTS：`cosyvoice` 为默认目标；缺失时完整模式失败，除非显式配置 fallback。
|
||
4. Memory：`faiss_sqlite` 默认；如果 FAISS 不可用则 memory health error，基本对话可继续但 self-test 标记失败。
|
||
5. Tools：默认启用 ToolRouter，但高风险 adapter 默认 disabled。
|
||
|
||
## 错误处理
|
||
|
||
1. 音频设备错误：启动失败或 recovery 到 idle。
|
||
2. APM 不可用：完整模式启动失败。
|
||
3. STT final 空文本：丢弃 utterance，回 listening。
|
||
4. LLM/TTS 错误：取消 response，发 stage_error，回 listening。
|
||
5. Tool high-risk：发 confirmation_required；第一版终端拒绝自动执行。
|
||
6. Memory health error：禁用 memory context，继续基本对话并报告诊断。
|
||
|
||
## 自测设计
|
||
|
||
`agent-self-test` 使用 fake AudioHub/APM/STT/TTS/LLM/tool/memory，必须模拟三轮：
|
||
|
||
1. 正常问答。
|
||
2. 播放时用户打断。
|
||
3. memory.search tool call。
|
||
|
||
`audio-self-test` 检查真实设备、APM provider health、fake echo suppression、interrupt latency 统计。无真实 WebRTC binding 时输出失败 JSON，不伪造通过。
|