[实时字幕端点]：完成无新文字快速结束录音，包含1.5秒停滞配置、Capture端点和回归测试

2026-06-18 11:23:20 +08:00
parent 39da9dd09f
commit 1e956f5eb6
13 changed files with 151 additions and 5 deletions
@@ -147,6 +147,18 @@ The first implementation is a per-turn heuristic endpoint, not persistent voicep
 4. `VoiceAssistantPipeline` 在 `speech_started` 后把 capture 阶段已开始录音的帧 feed 给 realtime STT session；当 partial 文本变化时才 emit，避免刷屏。
 5. `OWNER_REALTIME_TRANSCRIPT_ENABLED=1` 默认启用；设置为 `0` 可临时回退到只显示 final transcript。

+## Realtime Transcript Idle Endpoint
+
+真人 `run-live` 日志显示，用户已看到实时字幕完整推进后，capture 仍可能继续等待 VAD 或主说话人端点。新增 `OWNER_REALTIME_TRANSCRIPT_IDLE_TIMEOUT_MS` 作为文本级端点，默认 `1500` ms：
+
+1. CaptureStage 只在已经输出过至少一次有效 `transcript_partial` 后启用该端点。
+2. 每次 `transcript_partial` 真实发出时，记录该帧的音频时间戳为 `last_partial_ms`。
+3. 后续已开始录音但没有新的 partial 文本输出时，如果当前帧时间戳与 `last_partial_ms` 的差值达到配置阈值，调用 `VadRecorder.finish("partial_transcript_idle")` 构建当前录音片段。
+4. 构建出的 segment 继续走 final STT、LLM、TTS，不把 partial 文本写入上下文。
+5. 配置为 `0` 时关闭该端点，保留只依赖主说话人/VAD 的旧行为。
+
+该端点使用音频帧时间戳而不是 wall-clock，避免批量读帧或 CPU 抖动导致误判。它不会在没有 partial 的场景提前结束，避免 STT 尚未给出第一段文本时切掉用户开头。
+
 ## Model Files

 ```text
@@ -107,6 +107,7 @@
 42. `real-live-check --no-playback` SHALL 仍执行本地 TTS 合成和 pipeline 播放事件记录，但不实际向扬声器发声，便于自动化测试和无声环境排查。
 43. `real-live-check` SHALL 输出命令级开始/结束时间、总耗时、阶段耗时、pipeline 事件时间线和按 turn/stage 聚合的响应耗时。
 44. `real-live-check` SHALL 输出每次云端 LLM 请求真正发出的 `sent_at`、首个文本回复耗时和请求总耗时，且不得泄露 API key。
+45. `run-live` capture 阶段 SHALL 支持实时字幕停滞端点：当已经输出过 `transcript_partial` 后，如果 `OWNER_REALTIME_TRANSCRIPT_IDLE_TIMEOUT_MS` 时间内没有新的实时字幕文本输出，当前正式问题采集必须立即结束并进入 final STT。

 ### 非功能需求

@@ -163,6 +164,7 @@
 17. `OWNER_NOISE_FILTER_ENABLED=1`：正式问题阶段默认启用本地降噪。
 18. `OWNER_WAKE_DENOISE_ENABLED=0`：wake 阶段默认不启用降噪。
 19. `OWNER_NOISE_FILTER_PROVIDER=sherpa_onnx_gtcrn`：第一版本地降噪 provider。
+20. `OWNER_REALTIME_TRANSCRIPT_IDLE_TIMEOUT_MS=1500`：已有实时字幕后，若 1.5 秒没有新的文字输出，则结束本轮录音；设置为 `0` 可关闭该端点。

 终端输出：

@@ -304,6 +306,7 @@ standby
 12. partial 稳定过滤：实时字幕会先去除空白和标点，计算有效字符数；有效字符数小于 2 的文本直接忽略；若新文本比上一次已显示文本短且不构成稳定前缀推进，也忽略，避免把瞬时噪声显示给用户。
 13. 零时长播放后清理：`_drain_input_after_playback()` 先执行一次 `transport.flush_input()`；若 `post_playback_drain_ms <= 0` 立即返回；若配置为正数，才按用户显式配置继续 read/drop drain window 并最终再次 flush。
 14. 模拟 flush 隔离：`MemoryAudioTransport` 默认保持 flush 清空语义；模拟 live pipeline 显式设置 `flush_clears_input=False`，只记录 flush 调用，不删除预排帧，避免将真实时间队列与离线 fixture 序列混淆。
+15. 实时字幕停滞端点：CaptureStage 记录最后一次成功输出 `transcript_partial` 的音频时间戳；后续已开始录音但没有新的 partial 文本推进时，若当前帧时间戳与最后 partial 输出时间差达到 `OWNER_REALTIME_TRANSCRIPT_IDLE_TIMEOUT_MS`，调用 recorder `finish("partial_transcript_idle")` 构建当前片段并发出 `speech_ended`。

 ### 数据库/状态管理变更

@@ -451,6 +454,13 @@ standby
 - [ ] 14.3 实现 LLM 请求发送时间和响应耗时；前置条件：14.2 完成；验收标准：每次 LLM 调用记录 `sent_at`、`first_delta_ms`、`duration_ms`、最后 user 预览，且不包含 key；测试要点：RecordingLlmProvider 单测；优先级：P0；预计：35 分钟。
 - [ ] 14.4 执行真实命令验收和全量门禁并提交；前置条件：14.1 至 14.3 完成；验收标准：`real-live-check --turns 2 --no-playback` 和默认播放版本均输出 timing 且成功，全量门禁通过后中文提交；优先级：P0；预计：60 分钟。

+### 15. 实时字幕停滞端点
+
+- [ ] 15.1 更新 OpenSpec 和 README 描述 1.5 秒无新实时字幕即结束录音；前置条件：真人 `run-live` 日志确认 final STT 前仍等待过久；验收标准：proposal/design/spec/tasks/README 明确 `OWNER_REALTIME_TRANSCRIPT_IDLE_TIMEOUT_MS=1500`、关闭方式和 end_reason；测试要点：OpenSpec strict；优先级：P0；预计：30 分钟。
+- [ ] 15.2 实现配置与 capture 端点；前置条件：15.1 完成；验收标准：`AppConfig`、`.env.example`、`--show-config` 支持新配置，`VoiceAssistantPipeline` 在已有 partial 后 1500 ms 无新文本时调用 recorder finish；测试要点：配置解析和 show-config 单测；优先级：P0；预计：45 分钟。
+- [ ] 15.3 补充 recorder finish 和回归测试；前置条件：15.2 完成；验收标准：持续有语音但 partial 不再推进时，segment end_reason 为 `partial_transcript_idle`，final STT 仍执行且 partial 不进上下文；测试要点：live runtime 单测；优先级：P0；预计：45 分钟。
+- [ ] 15.4 执行门禁并提交“实时字幕端点”模块；前置条件：15.1 至 15.3 完成；验收标准：compileall、unittest、simulate-live、security-check、OpenSpec strict、git diff check 通过后中文提交；优先级：P0；预计：45 分钟。
+
 ## Spec Deltas

 ### 新增能力
@@ -474,6 +484,7 @@ standby
 13. `Real provider live fixture acceptance`：新增真实 provider 脚本化闭环验收和 ACK/TTS 播放后 0ms flush 语义，确保真实本地模型、云端 LLM、本地 TTS/播放在同一 pipeline 中可连续运行。
 14. `Real live check CLI`：新增 `real-live-check` 可重复命令，把完整真实 Provider 链路验收从一次性脚本升级为仓库内正式工具。
 15. `Real live check timing`：新增真实流程命令计时输出，覆盖命令发起时间、LLM 请求发送时间、各阶段响应耗时和 pipeline 事件时间线。
+16. `Realtime transcript idle endpoint`：新增已有实时字幕后 1.5 秒无新文字即结束录音的端点要求，避免用户已停说但 capture 继续等待 VAD/音色端点。

 ### 删除项

@@ -498,6 +509,7 @@ standby
 11. M11：真实 provider 脚本化闭环和 ACK 缓冲修正完成后提交；仍保留用户真人 `run-live` 体验验收，不在用户确认前归档。
 12. M12：`real-live-check` 正式 CLI、文档、测试和真实命令验收完成后提交；仍保留物理麦克风 `run-live` 真人体验验收。
 13. M13：`real-live-check` 计时输出完成后提交，使后续排查可以直接看到每段耗时。
+14. M14：实时字幕停滞端点完成后提交，用户真实 `run-live` 若已有 partial 后 1.5 秒无新文字，应快速进入 final STT。

 估时：

@@ -56,6 +56,11 @@ The live runtime SHALL display recognized user utterance text in the terminal bo
 - **WHEN** a partial transcript is emitted
 - **THEN** it SHALL be treated as user-visible feedback only and SHALL NOT be appended to the conversation context or sent to the LLM

+#### Scenario: Realtime transcript stops advancing
+- **WHEN** the user utterance has started, at least one partial transcript has been displayed, and no new partial transcript text is emitted for `OWNER_REALTIME_TRANSCRIPT_IDLE_TIMEOUT_MS`
+- **THEN** capture SHALL end the current utterance with end reason `partial_transcript_idle`
+- **AND** the runtime SHALL proceed to final STT for the captured audio instead of waiting for VAD maximum recording duration
+
 #### Scenario: User utterance is transcribed
 - **WHEN** a live turn captures a user utterance and STT returns non-empty text
 - **THEN** the terminal output SHALL include a transcript message containing the recognized text before the thinking/LLM status is emitted
@@ -111,3 +111,10 @@
 - [x] 14.2 实现命令级和事件级计时；前置条件：14.1 完成；验收标准：`real-live-check` JSON 包含命令总耗时、生成音频/build/pipeline phase 耗时、每轮 wake/ACK/capture/STT/LLM/TTS/turn_total 耗时；测试要点：stage timing 单测；优先级：P0；预计：45 分钟。
 - [x] 14.3 实现 LLM 请求发送时间和响应耗时；前置条件：14.2 完成；验收标准：每次 LLM 调用记录 `sent_at`、`first_delta_ms`、`duration_ms`、最后 user 预览，且不包含 key；测试要点：RecordingLlmProvider 单测；优先级：P0；预计：35 分钟。
 - [x] 14.4 执行真实命令验收和全量门禁并提交；前置条件：14.1 至 14.3 完成；验收标准：`real-live-check --turns 2 --no-playback` 和默认播放版本均输出 timing 且成功，全量门禁通过后中文提交；优先级：P0；预计：60 分钟。
+
+## 15. 实时字幕停滞端点
+
+- [x] 15.1 更新 OpenSpec 和 README 描述 1.5 秒无新实时字幕即结束录音；前置条件：真人 `run-live` 日志确认 final STT 前仍等待过久；验收标准：proposal/design/spec/tasks/README 明确 `OWNER_REALTIME_TRANSCRIPT_IDLE_TIMEOUT_MS=1500`、关闭方式和 end_reason；测试要点：OpenSpec strict；优先级：P0；预计：30 分钟。
+- [x] 15.2 实现配置与 capture 端点；前置条件：15.1 完成；验收标准：`AppConfig`、`.env.example`、`--show-config` 支持新配置，`VoiceAssistantPipeline` 在已有 partial 后 1500 ms 无新文本时调用 recorder finish；测试要点：配置解析和 show-config 单测；优先级：P0；预计：45 分钟。
+- [x] 15.3 补充 recorder finish 和回归测试；前置条件：15.2 完成；验收标准：持续有语音但 partial 不再推进时，segment end_reason 为 `partial_transcript_idle`，final STT 仍执行且 partial 不进上下文；测试要点：live runtime 单测；优先级：P0；预计：45 分钟。
+- [x] 15.4 执行门禁并提交“实时字幕端点”模块；前置条件：15.1 至 15.3 完成；验收标准：compileall、unittest、simulate-live、security-check、OpenSpec strict、git diff check 通过后中文提交；优先级：P0；预计：45 分钟。