mkbk
184 lines
10 KiB
Markdown
184 lines
10 KiB
Markdown
# 完整全双工 Agent 语音助手运行时
|
||
|
||
## 功能目标
|
||
|
||
当前 `run-agent-live` 已能进入无唤醒监听并在 TTS 播放阶段尝试后台打断，但真实架构仍是轮次式：先录完整句话，再 final STT，再 LLM，再 TTS 播放。播放期打断依赖临时 `AsyncBargeInMonitor` 从同一个 Transport 队列抢帧，无法保证麦克风输入、VAD、STT、回声抑制和播放取消之间的并发边界稳定。用户实际反馈“完全没有打断”，说明继续调参数不能解决根因。
|
||
|
||
本变更目标是把 `run-agent-live` 替换为完整全双工 Agent 运行时。目标用户是 macOS 本地桌面语音助手使用者，核心场景是用户可以直接说话、助手边生成边播报、用户随时插话打断、系统取消当前回复并立即处理新问题，同时保留长期记忆和安全工具调用能力。
|
||
|
||
量化成功指标：
|
||
|
||
1. 打断延迟：在自测 fixture 中，用户语音开始到播放停止的 P95 小于 200 ms。
|
||
2. 回声隔离：纯助手回放 reference 不触发用户打断、不产生有效用户 transcript。
|
||
3. 帧分发正确性：AudioHub 多消费者订阅时，VAD、STT、interrupt detector 不互相抢帧。
|
||
4. 响应首音：LLM 输出首个可播报句子后，TTS 首个 PCM chunk 在 1000 ms 内进入播放队列。
|
||
5. 自测覆盖：`agent-self-test --profile full-duplex --turns 3` 能无真人完成 STT、LLM、TTS、barge-in、memory、tool router 验收。
|
||
6. 安全边界：工具调用默认执行低风险工具，高风险工具进入确认或拒绝；日志不泄露 `.env` 密钥、raw PCM 或敏感记忆。
|
||
|
||
## 详细需求
|
||
|
||
功能需求：
|
||
|
||
1. `run-agent-live` SHALL 使用新的 `FullDuplexAgentRuntime`，不得继续调用 `VoiceAssistantPipeline.run_agent_turn()`。
|
||
2. `run-live` SHALL 保持旧 wake-word turn-based 稳定入口。
|
||
3. 系统 SHALL 新增 `AudioHub`，作为唯一麦克风输入拥有者，内部维护 20 ms、16 kHz、mono、int16 capture ring buffer。
|
||
4. VAD、STT、interrupt detector 和诊断录制 SHALL 从 AudioHub 获取独立订阅，不得直接抢读 Transport 队列。
|
||
5. 系统 SHALL 新增 render ring buffer，播放 PCM 写入 speaker 的同时写入 AEC reference。
|
||
6. `run-agent-live` SHALL 初始化 WebRTC APM；当 `OWNER_AUDIO_APM_PROVIDER=webrtc` 且 `OWNER_AUDIO_APM_REQUIRED=1` 时，真实 provider 不可用必须启动失败，不得静默回退为伪全双工。
|
||
7. fake APM SHALL 只用于测试、自测和显式 `OWNER_AUDIO_APM_PROVIDER=fake`。
|
||
8. 持续 VAD SHALL 在 listening/thinking/speaking/tool_running 阶段持续判断用户是否开始说话。
|
||
9. Streaming STT SHALL 输出 partial、stable partial、final 三层事件；final 或明确提交 stable transcript 才能进入 LLM。
|
||
10. 打断 SHALL 不依赖 partial STT；VAD + APM 后有效人声即可触发 cancellation。
|
||
11. LLM、TTS、播放队列、可取消工具 SHALL 共享 cancellation graph；打断时全部取消。
|
||
12. LLM SHALL 默认启用 streaming。
|
||
13. TTS SHALL 使用可分块 PCM provider；CosyVoice 为目标 provider，macOS `say` 只做 fallback。
|
||
14. 播放 SHALL 每 20-30 ms chunk 检查 cancellation，并把 render chunk 写入 APM reference。
|
||
15. Conversation Manager SHALL 统一短期上下文、长期记忆、LLM、tool call、TTS 和打断恢复。
|
||
16. MemoryManager SHALL 支持 SQLite 文本/元数据和 FAISS 向量索引；默认启用但敏感内容不自动保存。
|
||
17. ToolRouter SHALL 接入 LLM tool call loop，第一批工具包括 `memory.search`、`memory.save`、`shell.readonly`、`openinterpreter.run`、`browser.playwright`。
|
||
18. Open Interpreter、Playwright 默认关闭；显式启用后仍受风险分类、目录限制、超时、输出截断和确认策略约束。
|
||
19. README 和 `.env.example` SHALL 统一说明 `run-agent-live` 是完整全双工入口，`run-live` 是旧入口。
|
||
20. 新增 `agent-self-test` 和 `audio-self-test`，作为无人值守验收命令。
|
||
|
||
非功能需求：
|
||
|
||
1. 音频回调不得执行阻塞 STT、LLM、TTS 或工具逻辑。
|
||
2. Capture/render ring buffer 必须有容量上限，溢出丢弃旧帧并发诊断事件。
|
||
3. 所有后台线程/任务必须可关闭；测试后不得残留线程。
|
||
4. 事件 payload 必须脱敏，不输出 API key、Authorization、raw PCM、完整工具敏感输出。
|
||
5. 无 APM、无 STT 模型、无 TTS provider、无设备权限时必须给结构化错误。
|
||
6. 旧 `simulate-live`、`real-live-check`、`run-live` 不得被新 runtime 破坏。
|
||
|
||
边缘案例：
|
||
|
||
1. 用户在 LLM 尚未开始播放时插话：取消 thinking，保留新用户音频，重启当前输入。
|
||
2. 用户在 TTS 合成中插话：取消 TTS，未播文本不进上下文。
|
||
3. 用户和助手声音重叠：APM 后用户声有效时触发打断；纯回声不得触发。
|
||
4. 工具运行中插话：可取消工具取消；不可安全取消工具进入确认/等待结果后恢复。
|
||
5. STT final 空文本：不调用 LLM，回 listening。
|
||
6. Memory index 损坏：禁用长期记忆并发 health error，不影响基本对话。
|
||
|
||
## 设计方案
|
||
|
||
文字架构图：
|
||
|
||
```text
|
||
Microphone
|
||
-> AudioHub raw capture ring
|
||
-> WebRtcAudioProcessingStage(AEC/NS/AGC, render reference)
|
||
-> processed capture ring
|
||
-> Continuous VAD
|
||
-> Streaming STT
|
||
-> ConversationManager
|
||
-> MemoryManager(SQLite + FAISS)
|
||
-> LLM streaming + ToolRouter
|
||
-> SentenceSegmenter
|
||
-> Streaming TTS
|
||
-> InterruptiblePlaybackQueue
|
||
-> Speaker + render reference ring
|
||
```
|
||
|
||
主状态机：
|
||
|
||
```text
|
||
idle -> listening -> thinking -> speaking -> listening
|
||
speaking -> interrupted -> listening
|
||
thinking -> interrupted -> listening
|
||
tool_running -> interrupted/recovering/listening
|
||
any recoverable error -> recovering -> listening
|
||
```
|
||
|
||
关键接口：
|
||
|
||
1. `AudioHub.subscribe(kind: str) -> AudioSubscription`
|
||
- 参数：`kind` 为 `processed_capture`、`raw_capture`、`render_reference`、`debug`。
|
||
- 返回：独立 cursor 的 frame reader。
|
||
- 错误：设备缺失、buffer closed、format mismatch。
|
||
2. `AudioProcessingProvider.process_capture(frame) -> AudioFrame`
|
||
- 输入：raw capture frame。
|
||
- 输出：AEC/NS/AGC 后 frame。
|
||
- 错误：`AUDIO_APM_UNAVAILABLE`、`AUDIO_APM_PROCESS_FAILED`。
|
||
3. `StreamingSttSession.accept_frame(frame) -> list[TranscriptEvent]`
|
||
- 输出：partial/stable/final。
|
||
- 错误：模型缺失、推理失败、取消。
|
||
4. `StreamingTtsSession.accept_text(text) -> list[AudioFrame]`
|
||
- 输出：可播放 PCM chunks。
|
||
- 错误：provider 缺失、合成失败、取消。
|
||
5. `ToolRouter.route(call) -> ToolDecision`
|
||
- 输出：execute/reject/require_confirmation。
|
||
|
||
性能优化路径：
|
||
|
||
1. 音频输入只写 ring buffer，不做重计算。
|
||
2. STT 和 VAD 消费 processed capture ring，互不阻塞。
|
||
3. 播放 chunk 与 render reference 同步写入，避免打断检测依赖播放回调抢帧。
|
||
4. LLM streaming + sentence segmentation 让首句尽早进入 TTS。
|
||
5. Self-test 记录 interrupt latency、STT first partial、TTS first chunk。
|
||
|
||
UI/UX 路径：
|
||
|
||
1. 终端输出仍由 event bus 驱动。
|
||
2. 打断事件输出 `检测到用户打断`、`取消当前回复`、`继续听你说`。
|
||
3. debug 模式输出 APM provider、echo suppression、interrupt latency。
|
||
4. 未来 GUI 桌宠订阅同一事件总线。
|
||
|
||
## 风险与权衡
|
||
|
||
| 风险 | 概率 | 影响 | 缓解措施 |
|
||
|---|---:|---:|---|
|
||
| macOS 上没有可用 WebRTC APM Python binding | 高 | 高 | 完整模式启动失败并说明安装要求；self-test 使用 fake APM；旧 `run-live` 保留 |
|
||
| Faster Whisper 流式能力不是真正低延迟 streaming | 中 | 中 | 先实现稳定 provider contract；允许 sherpa-onnx fallback；SenseVoice 作为后续 provider |
|
||
| CosyVoice 本地依赖重、安装慢 | 高 | 中 | provider 可配置；macOS say fallback 标记为降级，不宣称完整全双工默认 |
|
||
| AudioHub 并发复杂导致线程泄漏 | 中 | 高 | 所有后台任务使用 cancellation graph；单元测试检查 shutdown |
|
||
| AEC 质量不足仍误触发 | 中 | 高 | 增加 echo self-test、render drift 诊断、阈值调试输出 |
|
||
| FAISS/SQLite 不一致 | 中 | 中 | health-check 和 checksum；不返回未验证记忆 |
|
||
| 工具调用误执行高风险动作 | 中 | 高 | 默认关闭 Open Interpreter/Playwright；风险分类和确认策略；只读 shell allowlist |
|
||
| 旧 run-live 回归 | 低 | 高 | 保持代码路径分离；旧测试继续跑 |
|
||
|
||
## 任务分解
|
||
|
||
详见 `tasks.md`。所有任务拆到不超过 1 小时，按 OpenSpec、音频底座、持续识别与打断、流式回复、记忆工具、自测文档分阶段完成。每个阶段完成后验证并中文 commit。
|
||
|
||
## Spec Deltas
|
||
|
||
新增：
|
||
|
||
1. `Complete full-duplex agent runtime`
|
||
2. `AudioHub fanout`
|
||
3. `Required WebRTC APM for full-duplex`
|
||
4. `Always-on interruption controller`
|
||
5. `Streaming STT/TTS runtime`
|
||
6. `Conversation manager with memory and tools`
|
||
7. `Self-test commands`
|
||
|
||
修改：
|
||
|
||
1. `Live run-agent-live runtime` 从“可真实启动并播放期打断”升级为“完整全双工主入口”。
|
||
2. `WebRTC audio processing foundation` 从规划/fake provider 验证升级为运行时启动要求。
|
||
3. `Tool Router` 从模块级测试升级为 LLM tool-call 主链路要求。
|
||
|
||
删除/推翻：
|
||
|
||
1. 推翻 `AsyncBargeInMonitor` 作为主打断架构；保留为 legacy fallback 或删除。
|
||
2. 推翻 `run-agent-live` 复用 `VoiceAssistantPipeline.run_agent_turn()` 的实现边界。
|
||
3. 推翻“真实运行仍走 run-live”的 README 旧描述。
|
||
|
||
## 实施计划
|
||
|
||
1. M1 OpenSpec：0.5 天。
|
||
2. M2 AudioHub + APM：1-1.5 天。
|
||
3. M3 Continuous VAD/STT + interrupt：1-2 天。
|
||
4. M4 Streaming response/TTS/playback：1 天。
|
||
5. M5 Memory + Tool Router：1-1.5 天。
|
||
6. M6 self-test/docs/final gates：0.5-1 天。
|
||
|
||
乐观总耗时 5 天，最可能 7 天，悲观 10 天。没有数据迁移；长期记忆首次启用时创建 SQLite/FAISS 文件，旧短期上下文不迁移。
|
||
|
||
## Git 提交规范
|
||
|
||
每完成一个主要阶段必须立即验证并提交，提交信息格式：
|
||
|
||
`[模块名]：完成[具体功能描述]，包含[关键变更]`
|
||
|
||
提交前至少运行该阶段相关单测；最终阶段运行完整门禁并保证 `git status --short` 为空。
|