Owner/openspec/changes/separate-wake-and-realtime-transcript/tasks.md

独立本地唤醒与终端转写显示任务

1. OpenSpec 修正与提交

• 1.1 编写 proposal.md；前置条件：用户明确唤醒使用本地模型；验收标准：覆盖功能目标、详细需求、设计方案、风险与权衡、任务分解、Spec Deltas、实施计划、Git 提交规范；测试要点：人工检查不再把 ASR 唤醒作为默认方案；优先级：P0；预计：50 分钟。
• 1.2 编写 design.md；前置条件：proposal 完成；验收标准：明确本地 KWS 模型、Runtime 生命周期、接口、错误处理和测试策略；测试要点：设计可映射到代码任务；优先级：P0；预计：35 分钟。
• 1.3 编写 specs/voice-pet-pipeline/spec.md delta；前置条件：主 spec 已读；验收标准：修改 Wake word、模型管理、live runtime、终端状态和 testability 要求；测试要点：OpenSpec strict 通过；优先级：P0；预计：35 分钟。
• 1.4 编写 tasks.md 原子任务；前置条件：design/spec 完成；验收标准：每项不超过 1 小时，包含前置条件、优先级、验收标准、测试要点；优先级：P0；预计：25 分钟。
• 1.5 校验并提交 OpenSpec；前置条件：1.1 至 1.4 完成；验收标准：openspec validate separate-wake-and-realtime-transcript --strict 和 openspec validate --all --strict 通过后 commit；测试要点：中文提交信息；优先级：P0；预计：15 分钟。

2. 本地 KWS 模型与配置

• 2.1 扩展 speech_models.py manifest 和路径 helper；前置条件：OpenSpec 提交完成；验收标准：包含 KWS URL、目录、tokens、encoder、decoder、joiner、keywords；测试要点：manifest/default paths 测试；优先级：P0；预计：45 分钟。
• 2.2 扩展 download_speech_models.py 下载 KWS 模型并写入 keywords 文件；前置条件：2.1 完成；验收标准：脚本幂等，能补齐 models/wake；测试要点：真实下载或 skip existing；优先级：P0；预计：60 分钟。
• 2.3 扩展 AppConfig 和 .env.example wake 配置；前置条件：字段确定；验收标准：默认 local_kws；测试要点：配置加载测试；优先级：P0；预计：30 分钟。
• 2.4 扩展 model-check 检查 wake 模型并尝试加载；前置条件：2.1 至 2.3；验收标准：完整模型通过，缺模型结构化失败；测试要点：临时目录和真实模型；优先级：P0；预计：45 分钟。
• 2.5 验证并提交“本地唤醒模型”模块；前置条件：2.1 至 2.4 完成；验收标准：compileall、相关 unittest、security-check、model-check、OpenSpec 通过后 commit；优先级：P0；预计：20 分钟。

3. Runtime 独立唤醒与实时转写

• 3.1 实现 SherpaOnnxKeywordWakeWordProvider；前置条件：KWS 路径 helper 完成；验收标准：可加载 KWS 模型，缺文件结构化失败；测试要点：missing/fake provider 测试；优先级：P0；预计：60 分钟。
• 3.2 修改 LiveVoiceRuntime 注入并使用 wake provider；前置条件：3.1 完成；验收标准：wake 阶段不调用 STT，唤醒命中后录正式问题；测试要点：两轮 runtime STT 调用次数；优先级：P0；预计：60 分钟。
• 3.3 增加 RuntimeReporter.transcript；前置条件：3.2 完成；验收标准：转写结果在 LLM 前输出；测试要点：reporter 状态顺序；优先级：P0；预计：40 分钟。
• 3.4 增加唤醒词污染回归测试；前置条件：3.2 完成；验收标准：LLM user message 不含 wake 音频文本；测试要点：fake wake metadata；优先级：P0；预计：30 分钟。
• 3.5 验证并提交“独立唤醒与转写显示”模块；前置条件：3.1 至 3.4 完成；验收标准：compileall、unittest、security-check、OpenSpec 通过后 commit；优先级：P0；预计：20 分钟。

4. 文档、真实验收与归档

• 4.1 更新 README；前置条件：实现完成；验收标准：说明本地 KWS、模型下载、model-check、run-live 输出；测试要点：命令可复制；优先级：P0；预计：30 分钟。
• 4.2 下载并验收 KWS 模型；前置条件：下载脚本完成；验收标准：python3.11 scripts/download_speech_models.py --dir models 和 model-check 通过；测试要点：输出不泄露 key；优先级：P0；预计：60 分钟。
• 4.3 执行真实 run-live 验收；前置条件：模型、设备、.env 齐全；验收标准：唤醒命中使用本地模型，终端显示转写结果；测试要点：单轮或两轮状态输出；优先级：P0；预计：60 分钟。
• 4.4 最终门禁；前置条件：全部实现完成；验收标准：compileall、unittest、security-check、model-check、device-check、OpenSpec strict 全通过；优先级：P0；预计：30 分钟。
• 4.5 归档变更并提交；前置条件：4.4 通过；验收标准：主 spec 更新，archive 完成，最终 commit，git status --short 为空；测试要点：中文提交信息；优先级：P0；预计：20 分钟。

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 分钟。

7. 开源语音助手式 Pipeline 重构

• 7.1 更新 OpenSpec 以描述 stage 化 pipeline、事件总线、TurnController 和主说话人端点；前置条件：公开参考已确认；验收标准：proposal/design/spec/tasks 覆盖新架构和任务；测试要点：OpenSpec strict；优先级：P0；预计：45 分钟。
• 7.2 实现 pipeline event bus 和终端事件映射；前置条件：7.1 完成；验收标准：所有 live 用户可见状态由事件产生；测试要点：事件顺序和终端文案测试；优先级：P0；预计：60 分钟。
• 7.3 实现 TurnController 和 VoiceAssistantPipeline；前置条件：7.2 完成；验收标准：run-live 使用统一 pipeline，成功/失败 turn 均恢复待机；测试要点：两轮 fake runtime、错误恢复、上下文回归；优先级：P0；预计：60 分钟。
• 7.4 实现本轮主说话人端点；前置条件：7.3 完成；验收标准：主说话人音色消失约 300 ms 后结束采集；测试要点：一次提问后背景噪声不拖尾、短暂停顿不断句、画像不足回退；优先级：P0；预计：60 分钟。
• 7.5 更新 README、.env.example、本地 .env 非密钥配置；前置条件：7.2 至 7.4 完成；验收标准：运行说明匹配新 pipeline；测试要点：--show-config 不泄露 key；优先级：P0；预计：30 分钟。
• 7.6 验证并提交“Pipeline 文档验收”模块；前置条件：7.1 至 7.5 完成；验收标准：compileall、unittest、security-check、model-check、device-check、OpenSpec strict 全通过；优先级：P0；预计：30 分钟。

8. 低延迟端点与首句保留修正

• 8.1 更新 OpenSpec 描述首句保留和低延迟端点；前置条件：真人 run-live 日志确认首句/端点仍慢；验收标准：proposal/design/spec/tasks 明确 ACK 后不额外丢弃音频、主说话人画像独立阈值、批量读帧和真人验收后再归档；测试要点：OpenSpec strict；优先级：P0；预计：35 分钟。
• 8.2 实现 ACK 后首句保留和 SoundDevice 批量读帧；前置条件：8.1 完成；验收标准：默认 OWNER_POST_PLAYBACK_DRAIN_MS=0，SoundDeviceAudioTransport.read_frames() 能一次返回积压帧，播放后不额外读丢正式问题；测试要点：transport 单测和 ACK 后首句回归；优先级：P0；预计：45 分钟。
• 8.3 实现主说话人画像独立就绪阈值；前置条件：8.2 完成；验收标准：新增 OWNER_SPEAKER_PROFILE_MIN_MS=120，主说话人缺席结束不再被 OWNER_VAD_MIN_DURATION_MS 拖慢；测试要点：短首句、背景噪声和重复提问不合并；优先级：P0；预计：45 分钟。
• 8.4 补充配置文档、回归测试和门禁验证；前置条件：8.1 至 8.3 完成；验收标准：.env.example、README、配置显示和测试匹配新默认值；测试要点：compileall、unittest、security-check、model-check、device-check、OpenSpec strict；优先级：P0；预计：45 分钟。
• 8.5 提交“低延迟端点”模块；前置条件：8.4 门禁通过；验收标准：中文 commit 信息为 [低延迟端点]：完成首句保留和快速结束修正，包含ACK缓冲策略、批量读帧和主说话人端点回归测试，提交后 git status --short 为空；优先级：P0；预计：10 分钟。

9. 录音期间实时转写显示

• 9.1 更新 OpenSpec 描述 partial transcript；前置条件：用户要求“实时显示用户说话转换的结果”；验收标准：proposal/design/spec/tasks 明确录音期间输出 transcript_partial，最终 transcript_final 仍用于 LLM；测试要点：OpenSpec strict；优先级：P0；预计：30 分钟。
• 9.2 实现 realtime transcript 事件和终端显示；前置条件：9.1 完成；验收标准：新增 transcript_partial 事件，终端输出 实时转写：<文本>，重复 partial 不刷屏；测试要点：事件顺序和 reporter 测试；优先级：P0；预计：45 分钟。
• 9.3 实现本地 streaming STT partial provider；前置条件：本地 STT 模型已由 model-check 覆盖；验收标准：SherpaOnnxSttProvider 支持 streaming session，cloud final ASR 模式下仍使用本地 streaming STT 做 partial；测试要点：fake session 与 metadata partial 单测；优先级：P0；预计：60 分钟。
• 9.4 接入 VoiceAssistantPipeline 捕获循环；前置条件：9.2 至 9.3 完成；验收标准：用户说话期间持续 feed 已开始录音的帧，partial 在 speech_started 后、transcript_final 前输出；测试要点：live runtime partial 顺序测试；优先级：P0；预计：45 分钟。
• 9.5 补充配置、README、门禁并提交；前置条件：9.1 至 9.4 完成；验收标准：新增 OWNER_REALTIME_TRANSCRIPT_ENABLED=1，compileall、unittest、security-check、model-check、device-check、OpenSpec strict 通过后中文 commit；优先级：P0；预计：45 分钟。