[Voice] 建立可插拔实时音频与 Linx/xiaozhi Provider 契约

[ZhaoXingPeng]

结论与下一步

本子 Issue 冻结语音模块的可迁移 Port、会话状态和 Provider 能力契约，目标板仍是已连接的 ESP32-S3。下一步先提交可编译的 TDD 契约骨架，再接入 Linx XRobot WebSocket 与小智音频实现，真实音频、网络重连和播放结果必须用真机证据补齐。

真实场景

• 开发者需要把 ESP32-S3 的 I2S/AFE 音频接到 Linx，同时保留小智协议作为可回退 Provider；
• Linx 或 IM 平台变化时，VoiceLife 核心不应出现供应商字段或 SDK 类型；
• 播放 TTS 时用户唤醒或按键打断，旧 generation 的迟到音频不能污染新会话；
• 没有板子或云服务时，主机测试仍应覆盖状态迁移、鉴权配置校验、帧序列和错误降级。

本期范围

做：定义 VoiceSession、AudioInput/AudioOutput、VoiceTransport、SpeechProvider、ASRAdapter、TTSAdapter、RealtimeAdapter、Codec、CapabilityProfile 和 VoiceEvidence 的平台无关契约；以编译期 Provider Registry/Factory 选择实现，启动时校验能力与凭据引用；固定 Linx WebSocket 的 hello、Bearer/Device-Id/Client-Id、OPUS/PCM、listen、stt、tts、abort 和重连边界；保留小智采集/编码/发送与接收/解码/播放队列的迁移边界；用主机 TDD 覆盖状态、generation、打断和失败回滚。

明确不做：不承诺任意非 ESP32 板卡可运行；不把 Linx token、设备身份或网络凭据写进代码、日志和 Profile；不在本 PR 完成真实 WebSocket TLS、Opus/AEC/DSP 或整机音频验收。

关键决策

决策	选择	原因
外部协议	Adapter + Anti-Corruption Layer	Linx 与小智字段、错误和生命周期不同，不能泄漏到核心
Provider 选择	编译期注册 + Profile Factory	ESP32 无动态插件收益，需可估算内存和启动行为
编解码	Codec Strategy	OPUS/PCM 由 Profile 能力选择，核心只处理 AudioFrame
会话并发	Generation + State	重连/打断后丢弃旧帧，避免迟到数据串入新会话
音频调度	有界队列、采集/编码/发送与接收/解码/播放分离	参考 xiaozhi-esp32 实测结构，避免数据库或业务写入阻塞实时任务

参考资料

• Linx WebSocket 协议：https://linx.qiniu.com/docs/xrobot/platform/websocket
• Linx 设备接入指南：https://linx.qiniu.com/docs/xrobot/guide/xiaozhi-firmware
• xiaozhi-esp32 音频服务：https://github.com/78/xiaozhi-esp32/blob/main/main/audio/audio_service.h
• ESP-IDF I2S：https://docs.espressif.com/projects/esp-idf/en/v6.0.2/esp32s3/api-reference/peripherals/i2s.html

验收标准

• 主机契约测试在无 ESP-IDF 环境通过，且证明非法状态、旧 generation 和重复 Stop 被拒绝或幂等；
• Profile 只能声明已注册 Provider 和真实能力，缺能力返回明确错误；
• Linx hello/listen/stt/tts/abort 字段和超时/重连边界有文档与解析测试；
• ESP32-S3 真实板完成采集、上行、ASR、TTS 播放、打断、断线重连和恢复记录；
• PR 关联本 Issue，包含测试命令、未完成项和非作者 Review。

Refs #91