[唤醒灵敏度与端点恢复]：完成唤醒提示顺序和Hybrid VAD优化，包含阈值默认值、缓冲时序和测试覆盖

2026-06-17 21:00:28 +08:00
parent 44f708a3dc
commit 95e4996434
13 changed files with 145 additions and 29 deletions
@@ -27,7 +27,7 @@ run-live
  -> AppConfig(.env)
  -> SoundDeviceAudioTransport
  -> SherpaOnnxKeywordWakeWordProvider(local models/wake)
-  -> VadRecorder(user utterance)
+  -> VadRecorder(user utterance, hybrid local+energy VAD by default)
  -> CloudAsrSttProvider or SherpaOnnxSttProvider
  -> TerminalRuntimeReporter.transcript()
  -> ConversationContext
@@ -45,7 +45,7 @@ run-live
 5. Open microphone stream.
 6. Wait for KWS wake event by feeding frames directly into wake provider.
 7. On wake hit, reset wake stream and VAD recorder.
-8. Record user utterance with VAD.
+8. Record user utterance with VAD. The default provider is `hybrid`: project-local `sherpa-onnx` VAD remains the primary detector, and an energy threshold fallback prevents low microphone gain from being treated as no speech.
 9. Transcribe user utterance.
 10. Emit transcript to terminal.
 11. Append user text and call LLM.
@@ -98,6 +98,7 @@ models/
 3. KWS runtime failure: `WAKE_MODEL_LOAD_FAILED` with retryable true.
 4. Empty user STT: existing `STT_EMPTY_TRANSCRIPT`.
 5. Invalid wake provider config: `CONFIG_MISSING_VALUE`.
+6. Real microphone VAD miss: default `OWNER_VAD_PROVIDER=hybrid` SHALL accept speech when either the local model or the energy fallback detects speech.

 ## Testing Strategy

@@ -196,6 +196,8 @@ standby
 | --- | --- | --- | --- |
 | KWS 关键词拼音格式不匹配模型 | 中 | 高 | 默认写入 sherpa 示例格式；保留 keywords 文件可编辑；测试下载后用真实模型加载；README 标明关键词文件位置 |
 | KWS 模型误唤醒或漏唤醒 | 中 | 中 | 暴露 threshold/score 配置；保留状态输出；后续可替换 KWS Provider |
+| 唤醒应答期间用户抢说被缓冲清理吞掉 | 中 | 高 | 终端提示顺序改为“唤醒命中 -> 应答中 -> 请说出问题 -> 录音中”，用户只在应答完成后收到提问提示；默认播放后排水从 250 ms 降为 50 ms |
+| 本地 VAD 对真实麦克风音量过保守 | 中 | 高 | 默认 VAD provider 改为 `hybrid`，本地模型判断和能量阈值兜底任一命中即认为有语音；保留 `local` 和 `energy` 可配置回退 |
 | 本地 KWS 增加启动加载时间 | 低 | 中 | 模型约 15 MB，启动加载一次；不在每轮重复加载 |
 | 正式问题和唤醒词连在同一句导致问题前半段丢失 | 中 | 中 | 第一版交互明确为先唤醒再提问；后续可做 pre-roll buffer，但不得把 wake 音频直接进 LLM |
 | 终端转写不是逐字流式 | 中 | 低 | 第一版至少在 LLM 前即时显示最终 STT 文本；后续可接入本地 streaming STT partial |
@@ -232,6 +234,20 @@ standby
 - [ ] 4.3 执行 run-live 单轮/两轮验收；前置条件：模型、设备、.env 齐全；验收标准：唤醒命中不等待云 ASR，终端显示转写结果；优先级：P0；预计：60 分钟。
 - [ ] 4.4 最终门禁、归档、提交；前置条件：全部任务完成；验收标准：compileall、unittest、security-check、model-check、device-check、OpenSpec strict、工作树干净；优先级：P0；预计：45 分钟。

+### 5. 唤醒应答与快速端点修正
+
+- [ ] 5.1 增加唤醒后本地语音应答；前置条件：本地 KWS 已可唤醒；验收标准：wake 命中后播放“我在”再进入录音；测试要点：fake runtime 播放顺序；优先级：P0；预计：45 分钟。
+- [ ] 5.2 清理应答播放期间的麦克风缓冲；前置条件：5.1 完成；验收标准：应答音频不进入正式问题 VAD/STT；测试要点：transport flush 测试；优先级：P0；预计：45 分钟。
+- [ ] 5.3 live 默认改用本地 `sherpa-onnx` VAD 并缩短静音端点；前置条件：模型已下载；验收标准：`.env` 可配置 VAD provider、静音结束时间和最大录音时长；测试要点：配置和 runtime 构造测试；优先级：P0；预计：45 分钟。
+- [ ] 5.4 验证并提交“唤醒应答与快速端点”模块；前置条件：5.1 至 5.3 完成；验收标准：compileall、unittest、security-check、model-check、OpenSpec strict 通过后 commit；优先级：P0；预计：20 分钟。
+
+### 6. 灵敏度与录音端点恢复
+
+- [ ] 6.1 调整唤醒提示顺序；前置条件：真人验收暴露用户会在“我在”播放前抢说；验收标准：终端顺序为“唤醒命中 -> 应答中：我在 -> 请说出问题 -> 录音中：正在听取问题”；测试要点：runtime reporter 顺序断言；优先级：P0；预计：30 分钟。
+- [ ] 6.2 降低默认 KWS 阈值；前置条件：真人反馈唤醒难触发；验收标准：默认 `OWNER_WAKE_KWS_THRESHOLD=0.15`，README 说明 0.10 至 0.20 调参范围；测试要点：配置默认值测试；优先级：P0；预计：20 分钟。
+- [ ] 6.3 增加 `hybrid` VAD；前置条件：真人验收出现 `VAD_TIMEOUT_NO_SPEECH`；验收标准：本地 VAD 和能量阈值任一判断为语音即可开始录音，默认 `OWNER_VAD_PROVIDER=hybrid`；测试要点：能量兜底单测；优先级：P0；预计：45 分钟。
+- [ ] 6.4 验证并提交“唤醒灵敏度与端点恢复”模块；前置条件：6.1 至 6.3 完成；验收标准：compileall、unittest、security-check、model-check、device-check、OpenSpec strict 通过后 commit；优先级：P0；预计：30 分钟。
+
 ## Spec Deltas

 ### 新增能力
@@ -244,6 +260,8 @@ standby
 2. `Live terminal state reporting`：新增终端转写结果输出要求。
 3. `Local speech model management`：新增 wake KWS 模型和关键词文件管理。
 4. `Testability`：新增 wake/STT 分离测试和唤醒污染回归测试。
+5. `Wake acknowledgement before recording`：明确“请说出问题”必须在应答播放完成后输出，避免用户抢说被清缓冲。
+6. `Fast user utterance endpointing`：默认 VAD provider 改为 `hybrid`，用能量阈值兜底真实麦克风音量差异。

 ### 删除项

@@ -259,6 +277,7 @@ standby
 2. M2：KWS 模型下载、manifest、config、model-check 完成并提交。
 3. M3：Runtime 独立 wake provider 和转写输出完成并提交。
 4. M4：README、真实验收、archive 和最终提交完成。
+5. M5：真人验收反馈修正唤醒提示顺序、KWS 阈值和 hybrid VAD，并在门禁通过后提交。

 估时：

@@ -23,7 +23,7 @@ The live runtime SHALL provide an audible local acknowledgement after local wake
 - **THEN** the runtime SHALL clear buffered microphone input captured during acknowledgement playback before starting VAD recording for the user's question

 ### Requirement: Fast user utterance endpointing
-The live runtime SHALL use the project-local VAD model by default for user utterance endpoint detection and SHALL expose configurable silence timing so the recording stops promptly after the user stops speaking.
+The live runtime SHALL use project-local VAD capability with an energy-threshold fallback by default for user utterance endpoint detection and SHALL expose configurable silence timing so the recording stops promptly after the user stops speaking.

 #### Scenario: User stops speaking after wake
 - **WHEN** VAD observes the configured continuous silence duration after a started utterance
@@ -33,6 +33,14 @@ The live runtime SHALL use the project-local VAD model by default for user utter
 - **WHEN** `OWNER_VAD_PROVIDER=local`
 - **THEN** the runtime SHALL use the project-local `sherpa-onnx` VAD model rather than a raw energy threshold for live user utterance endpointing

+#### Scenario: Hybrid VAD is configured
+- **WHEN** `OWNER_VAD_PROVIDER=hybrid`
+- **THEN** the runtime SHALL load both the project-local VAD model and an energy-threshold fallback and SHALL treat a frame as speech when either detector reports speech
+
+#### Scenario: Wake acknowledgement prompt ordering
+- **WHEN** local wake detection succeeds and `OWNER_WAKE_ACK_TEXT` is non-empty
+- **THEN** the terminal SHALL emit wake hit, acknowledgement, question prompt, and recording states in that order so the user is cued to speak only after acknowledgement playback
+
 ## MODIFIED Requirements

 ### Requirement: Wake word detection
@@ -38,3 +38,10 @@
 - [x] 5.2 清理应答播放期间的麦克风缓冲；前置条件：5.1 完成；验收标准：应答音频不进入正式问题 VAD/STT；测试要点：transport flush 测试；优先级：P0；预计：45 分钟。
 - [x] 5.3 live 默认改用本地 `sherpa-onnx` VAD 并缩短静音端点；前置条件：模型已下载；验收标准：`.env` 可配置 VAD provider、静音结束时间和最大录音时长；测试要点：配置和 runtime 构造测试；优先级：P0；预计：45 分钟。
 - [x] 5.4 验证并提交“唤醒应答与快速端点”模块；前置条件：5.1 至 5.3 完成；验收标准：compileall、unittest、security-check、model-check、OpenSpec strict 通过后 commit；优先级：P0；预计：20 分钟。
+
+## 6. 灵敏度与录音端点恢复
+
+- [x] 6.1 调整唤醒提示顺序；前置条件：真人验收显示用户可能在“我在”播放前抢说；验收标准：终端顺序为“唤醒命中 -> 应答中：我在 -> 请说出问题 -> 录音中：正在听取问题”；测试要点：runtime reporter 顺序断言；优先级：P0；预计：30 分钟。
+- [x] 6.2 降低默认 KWS 阈值；前置条件：真人反馈“小杰小杰”难触发；验收标准：默认 `OWNER_WAKE_KWS_THRESHOLD=0.15`，README 给出 `0.10` 至 `0.20` 调参建议；测试要点：配置默认值测试；优先级：P0；预计：20 分钟。
+- [x] 6.3 增加 `hybrid` VAD 并设为默认；前置条件：真人验收出现 `VAD_TIMEOUT_NO_SPEECH`；验收标准：本地 VAD 和能量阈值任一判断为语音即可开始/继续录音，默认 `OWNER_VAD_PROVIDER=hybrid`；测试要点：能量兜底单测、配置校验测试；优先级：P0；预计：45 分钟。
+- [x] 6.4 验证并提交“唤醒灵敏度与端点恢复”模块；前置条件：6.1 至 6.3 完成；验收标准：compileall、unittest、security-check、model-check、device-check、OpenSpec strict 通过后 commit；优先级：P0；预计：30 分钟。