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

10. 本地语音链路、高质量实时转写与噪音过滤

• 10.1 更新 OpenSpec 描述本地语音链路和降噪阶段；前置条件：真人日志确认旧本地 14M partial 会产生 家/家确 等噪声误识别；验收标准：proposal/design/spec/tasks 明确 wake/VAD/STT/partial/TTS/denoise 全本地、LLM 云端、正式问题阶段默认降噪；测试要点：OpenSpec strict；优先级：P0；预计：45 分钟。
• 10.2 升级 speech model manifest 和下载脚本；前置条件：确认 sherpa-onnx 官方 2025 中文 CTC int8 模型和 GTCRN denoiser URL；验收标准：models/manifest.json 默认 STT 指向 CTC model.int8.onnx，新增 denoise/gtcrn_simple.onnx required file；测试要点：manifest、required files、下载脚本单测/真实下载；优先级：P0；预计：60 分钟。
• 10.3 实现 AudioPreprocessStage；前置条件：10.2 完成；验收标准：新增可注入的 no-op 和 sherpa-onnx GTCRN online denoiser provider，正式问题帧在进入 VAD、partial STT、final STT 前共用同一份降噪后音频；测试要点：fake denoiser 验证 capture/STT 收到降噪后帧；优先级：P0；预计：60 分钟。
• 10.4 扩展本地 STT Provider 支持 CTC 模型和 partial 稳定过滤；前置条件：10.2 完成；验收标准：SherpaOnnxSttProvider 可按 manifest 加载 transducer 或 zipformer2 CTC，partial 不显示单字噪声和短暂跳变；测试要点：fake sherpa CTC、single-char partial filter、transient partial filter；优先级：P0；预计：60 分钟。
• 10.5 修改 runtime 默认本地语音链路；前置条件：10.3 至 10.4 完成；验收标准：默认 OWNER_SPEECH_PROVIDER=local，TTS 使用 MacSayTtsProvider，云端只用于 LLM，--show-config 显示噪音过滤配置且不泄露 key；测试要点：build runtime provider 类型、cloud ASR/TTS 不被调用；优先级：P0；预计：45 分钟。
• 10.6 更新 README、.env.example 和本地 .env 非密钥配置；前置条件：10.5 完成；验收标准：中文运行说明包含本地语音默认值、降噪开关、模型下载、model-check、run-live 验收；测试要点：命令可复制，.env 不进入提交；优先级：P0；预计：35 分钟。
• 10.7 下载/校验新本地模型并执行门禁；前置条件：10.2 至 10.6 完成；验收标准：下载脚本、compileall、unittest、security-check、model-check、device-check、OpenSpec strict、git diff check 通过或记录真实设备失败原因；测试要点：输出不泄露 key，模型文件不进 Git；优先级：P0；预计：60 分钟。
• 10.8 提交“本地语音降噪”模块；前置条件：10.7 门禁通过；验收标准：中文 commit 信息为 [本地语音降噪]：完成本地语音链路和噪音过滤，包含降噪模型、本地ASR和实时字幕稳定策略，提交后除本地 .env 非提交修改外无未提交源码/文档中间状态；优先级：P0；预计：10 分钟。

11. 模拟麦克风自动验收与自调试

• 11.1 更新 OpenSpec 描述模拟麦克风验收；前置条件：用户要求“自己一直测试到完整正常，自己弄模拟音频给麦克风”；验收标准：proposal/design/spec/tasks 明确新增可重复 simulate-live，覆盖两轮 live pipeline、实时字幕、降噪、上下文和恢复待机；测试要点：OpenSpec strict；优先级：P0；预计：35 分钟。
• 11.2 实现模拟麦克风帧生成和 bounded transport；前置条件：live pipeline 已 stage 化；验收标准：模拟输入包含 wake、正式问题、短噪声 partial、背景噪声、两轮 turn，空队列不会无限等待；测试要点：失败时命令返回非 0；优先级：P0；预计：50 分钟。
• 11.3 新增 owner_voice_pet simulate-live CLI；前置条件：11.2 完成；验收标准：默认两轮模拟，输出 JSON checks，可写入/回放 JSONL fixture；测试要点：CLI 单测和真实命令；优先级：P0；预计：40 分钟。
• 11.4 补充 README 和自动化测试；前置条件：11.3 完成；验收标准：README 包含模拟验收命令，测试验证两轮闭环、partial 噪声过滤、第二轮临时上下文、fixture 写入/回放；测试要点：unittest；优先级：P0；预计：35 分钟。
• 11.5 执行全量门禁并提交“模拟麦克风验收”模块；前置条件：11.1 至 11.4 完成；验收标准：simulate-live --turns 2、compileall、unittest、security-check、model-check、device-check、OpenSpec strict、git diff check 通过后中文 commit；优先级：P0；预计：45 分钟。

12. 真实完整链路自测与 ACK 缓冲修正

• 12.1 更新 OpenSpec 描述真实完整链路自测和 ACK 零时长 flush 偏差；前置条件：模拟验收已提交且本机模型齐全；验收标准：proposal/design/spec/tasks/spec delta 覆盖真实 provider 验收、0ms flush、模拟预排帧隔离和 ACK 禁用边缘案例；测试要点：OpenSpec strict；优先级：P0；预计：35 分钟。
• 12.2 修正 VoiceAssistantPipeline 和兼容 LiveVoiceRuntime 播放后输入清理；前置条件：12.1 完成；验收标准：ACK/TTS 播放后即使 OWNER_POST_PLAYBACK_DRAIN_MS=0 也执行一次 flush，ACK 文本为空时不执行 post-playback drain；测试要点：零时长 flush 单测、ACK 禁用不清空单测；优先级：P0；预计：45 分钟。
• 12.3 调整 MemoryAudioTransport 和模拟验收；前置条件：12.2 完成；验收标准：默认 flush 仍清空输入，模拟 live 显式保留预排帧并记录 flush 调用次数；测试要点：transport flush 双语义测试、两轮 simulated live 回归；优先级：P0；预计：35 分钟。
• 12.4 执行真实 provider 脚本化闭环验收；前置条件：本地模型、.env LLM key、macOS TTS/播放可用；验收标准：生成 wake/question 音频帧驱动真实 KWS、VAD、denoiser、本地 STT、云端 LLM、本地 TTS、播放，两轮上下文可引用第一轮历史；测试要点：输出不泄露 key，模型文件不进 Git；优先级：P0；预计：60 分钟。
• 12.5 执行全量门禁并提交“真实链路自测”模块；前置条件：12.1 至 12.4 完成；验收标准：compileall、unittest、simulate-live、security-check、model-check、device-check、OpenSpec strict、git diff check 全通过后中文 commit；优先级：P0；预计：45 分钟。