Owner/openspec/changes/complete-full-duplex-agent-runtime/design.md

完整全双工 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，不伪造通过。