[真实全双工运行时]：完成run-agent-live可打断语音闭环，包含持续监听、软件回声抑制和播放取消验证

2026-06-18 22:56:01 +08:00
parent e730883c64
commit a489f8eee1
11 changed files with 378 additions and 46 deletions
@@ -273,7 +273,7 @@ ToolResult:
 ## Migration Plan

 1. 保留现有 turn-based `run-live` 作为稳定路径。
-2. 后续实现新增 feature flag 或新入口启用全双工 Agent。
+2. `run-agent-live` 是真实全双工 Agent 入口；`--check-config` 只做配置检查，不带该参数时必须启动运行时。
 3. 先落地 fake provider 和模拟端到端，再接真实 WebRTC APM。
 4. STT/TTS provider 先用兼容 adapter 接现有能力，再替换为 streaming provider。
 5. 长期记忆默认关闭或空库启动，完成删除/禁用/隐私文档后再默认开启。
@@ -281,6 +281,12 @@ ToolResult:
 7. Open Interpreter 和 Playwright adapter 默认关闭，用户显式配置后才可用。
 8. GUI 电脑控制另开 OpenSpec 变更，不混入第一版全双工音频和安全工具验收。

+## Live Runtime Revision
+
+第一版真实 `run-agent-live` 采用软件 render-reference gate，不新增 WebRTC APM 重依赖。播放队列把已播放 PCM chunk 写入进程内 render reference；后台麦克风监听持续读取 capture frames，先用 VAD 判断有效人声，再与近期 render reference 做相似度/能量门控。候选音频不像助手回放且持续达到最短人声时长时，立即设置 playback stop event；STT 只用于打断后的用户文本识别，不再作为停止播放的前置条件。
+
+`run-live` 保持旧 wake/turn-based 入口。`run-agent-live` 跳过唤醒词和 ACK，常驻 `listening -> thinking -> speaking -> interrupted/listening`，打断后把已确认的用户音频接到下一轮 capture，避免丢首字。长期记忆、Tool Router、Open Interpreter 仍默认关闭。
+
 ## Rollback Strategy

 1. 若全双工音频不稳定，可通过配置回退 turn-based `run-live`。
@@ -427,6 +427,12 @@ recovering

 验收：tasks 中每项有前置条件、优先级、验收标准和测试要点；validation 命令明确。

+### 10. 真实全双工运行时落地
+
+目标：撤销“只完成骨架即完成”的边界，把 `run-agent-live` 接成可真人运行的全双工语音入口；保留 `run-live` 作为旧 turn-based 稳定入口。
+
+验收：`run-agent-live` 不带 `--check-config` 不再返回 `FULL_DUPLEX_RUNTIME_NOT_IMPLEMENTED`，而是启动持续 listening；播放中检测到有效用户说话时，在软件回声抑制通过后先停止播放，再把用户打断音频接入下一轮 STT；只有助手回放 reference 时不触发打断。
+
 ## Spec Deltas

 ### Capabilities
@@ -461,6 +467,8 @@ recovering
 18. 新增 requirement：`Open Interpreter external adapter`。
 19. 新增 requirement：`Browser automation tool boundary`。
 20. 新增 requirement：`Computer control reservation`。
+21. 新增 requirement：`Live run-agent-live runtime`。
+22. 新增 requirement：`Software render-reference interruption gate`。

 ### 推翻重做的理由

@@ -482,6 +490,7 @@ recovering
 6. 阶段 F：长期记忆 FAISS+SQLite、记忆召回和隐私策略。
 7. 阶段 G：Tool Router、安全工具、Open Interpreter adapter 和 Playwright adapter。
 8. 阶段 H：文档、性能验收、安全审计和迁移收尾。
+9. 阶段 I：真实 `run-agent-live` 运行时、软件回声抑制和真人打断验收。

 ### 里程碑估时

@@ -495,8 +504,9 @@ recovering
 | F 长期记忆 | 2 天 | 4 天 | 8 天 |
 | G Tool Router | 3 天 | 6 天 | 12 天 |
 | H 验收与收尾 | 2 天 | 4 天 | 8 天 |
+| I 真实全双工运行时 | 1 天 | 2 天 | 4 天 |

-总耗时预估：乐观 17.5 天，最可能 32 天，悲观 63.5 天。
+总耗时预估：乐观 18.5 天，最可能 34 天，悲观 67.5 天。

 ### 数据/状态迁移策略

@@ -377,3 +377,37 @@ The full-duplex Agent architecture SHALL be testable with fake audio devices, fa
 #### Scenario: OpenSpec validation runs
 - **WHEN** this planning change is complete
 - **THEN** `openspec validate add-full-duplex-agent-voice-assistant --strict` and `openspec validate --all --strict` SHALL pass
+
+### Requirement: Live run-agent-live runtime
+The system SHALL provide a real `run-agent-live` runtime entry point that starts continuous listening, handles user speech without a wake word, streams the assistant reply through interruptible playback, and returns to listening after completion or interruption.
+
+#### Scenario: Agent live runtime starts
+- **WHEN** the user runs `.venv/bin/python -m owner_voice_pet run-agent-live`
+- **THEN** the command SHALL start the full-duplex Agent runtime instead of returning `FULL_DUPLEX_RUNTIME_NOT_IMPLEMENTED`
+
+#### Scenario: Agent check-config remains diagnostic
+- **WHEN** the user runs `.venv/bin/python -m owner_voice_pet run-agent-live --check-config`
+- **THEN** the command SHALL validate and print non-secret full-duplex configuration without opening the microphone
+
+#### Scenario: Legacy live runtime remains available
+- **WHEN** the user runs `.venv/bin/python -m owner_voice_pet run-live`
+- **THEN** the existing wake-word turn-based runtime SHALL remain available during migration
+
+### Requirement: Software render-reference interruption gate
+The first live full-duplex runtime SHALL use software render-reference gating to prevent assistant playback from triggering user interruption while still stopping playback quickly when real user speech is detected.
+
+#### Scenario: User interrupts assistant playback
+- **WHEN** valid user speech is detected during assistant playback and it is not classified as assistant render-reference echo
+- **THEN** playback SHALL stop at the next configured chunk boundary and the captured user frames SHALL be retained for the next STT pass
+
+#### Scenario: STT partial is unavailable during interruption
+- **WHEN** VAD and render-reference gating indicate valid user speech but realtime STT has not produced a partial transcript yet
+- **THEN** the runtime SHALL still stop playback and SHALL use final STT on the buffered user audio afterward
+
+#### Scenario: Assistant echo is present
+- **WHEN** microphone input during playback matches recent assistant render-reference audio and no user speech is present
+- **THEN** the runtime SHALL NOT emit `barge_in_detected` and SHALL continue playback
+
+#### Scenario: Interrupted assistant text is committed
+- **WHEN** playback is stopped before a sentence is fully played
+- **THEN** only fully played assistant text SHALL be written to short-term context
@@ -100,3 +100,14 @@
 - [x] 10.7 执行安全和模型检查；前置条件：相关命令实现完成；优先级：P0；验收标准：security-check、model-check、device-check 按阶段通过或给出明确跳过理由；测试要点：不泄露密钥。
 - [x] 10.8 执行 OpenSpec 校验；前置条件：docs 和 spec 更新完成；优先级：P0；验收标准：`openspec validate add-full-duplex-agent-voice-assistant --strict` 与 `openspec validate --all --strict` 通过；测试要点：无 spec 格式错误。
 - [x] 10.9 按模块提交；前置条件：对应模块验证通过；优先级：P0；验收标准：提交信息符合 `[模块名]：完成[具体功能描述]，包含[关键变更]`；测试要点：`git status --short` 不含本模块未提交改动。
+
+## 11. 真实 run-agent-live 全双工运行时
+
+- [x] 11.1 更新 OpenSpec 真实运行边界；前置条件：用户确认 `run-agent-live` 为真实入口；优先级：P0；验收标准：proposal/design/spec/tasks 明确骨架不等于完成、`run-agent-live` 必须真实启动；测试要点：OpenSpec strict。
+- [x] 11.2 实现 `run-agent-live` 真实运行路径；前置条件：11.1 完成；优先级：P0；验收标准：不带 `--check-config` 不再返回 `FULL_DUPLEX_RUNTIME_NOT_IMPLEMENTED`，支持 `--once` 测试退出；测试要点：CLI 单元测试。
+- [x] 11.3 实现无唤醒 Agent turn；前置条件：11.2 完成；优先级：P0；验收标准：启动后直接 listening，用户说话后进入 STT/LLM/TTS，回复后回 listening；测试要点：fake audio 两轮闭环。
+- [x] 11.4 重做播放打断触发；前置条件：11.3 完成；优先级：P0；验收标准：VAD + 非助手回放即可先 stop playback，不等待 realtime STT partial；测试要点：无 partial 也能打断。
+- [x] 11.5 增加软件 render-reference gate；前置条件：11.4 完成；优先级：P0；验收标准：只有助手回放 reference 不触发打断，用户叠加回放可触发；测试要点：echo-only、user-over-echo。
+- [x] 11.6 保留打断用户音频和上下文边界；前置条件：11.5 完成；优先级：P0；验收标准：打断帧进入下一轮 STT，未完整播报 assistant 文本不入上下文；测试要点：上下文和 transcript 断言。
+- [x] 11.7 更新 README 和验收命令；前置条件：运行行为完成；优先级：P1；验收标准：README 明确 `run-agent-live` 真实入口、`run-live` 旧入口、软件回声抑制限制；测试要点：命令示例准确。
+- [x] 11.8 执行最终门禁并提交；前置条件：实现和文档完成；优先级：P0；验收标准：compileall、unittest、simulate-live、real-live-check、security/model/device check、OpenSpec strict 通过并中文 commit；测试要点：`git status --short` 干净。