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

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

## 1. OpenSpec 修正与提交

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

## 2. 本地 KWS 模型与配置

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

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

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

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

- [x] 4.1 更新 README；前置条件：实现完成；验收标准：说明本地 KWS、模型下载、model-check、run-live 输出；测试要点：命令可复制；优先级：P0；预计：30 分钟。
- [x] 4.2 下载并验收 KWS 模型；前置条件：下载脚本完成；验收标准：`python3.11 scripts/download_speech_models.py --dir models` 和 `model-check` 通过；测试要点：输出不泄露 key；优先级：P0；预计：60 分钟。
- [ ] 4.3 执行真实 run-live 验收；前置条件：模型、设备、.env 齐全；验收标准：唤醒命中使用本地模型，终端显示转写结果；测试要点：单轮或两轮状态输出；优先级：P0；预计：60 分钟。
- [x] 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. 唤醒应答与快速端点修正

- [x] 5.1 增加唤醒后本地语音应答；前置条件：本地 KWS 已可唤醒；验收标准：wake 命中后播放“我在”再进入录音；测试要点：fake runtime 播放顺序；优先级：P0；预计：45 分钟。
- [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 分钟。

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

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

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

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

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

- [x] 9.1 更新 OpenSpec 描述 partial transcript；前置条件：用户要求“实时显示用户说话转换的结果”；验收标准：proposal/design/spec/tasks 明确录音期间输出 `transcript_partial`，最终 `transcript_final` 仍用于 LLM；测试要点：OpenSpec strict；优先级：P0；预计：30 分钟。
- [x] 9.2 实现 realtime transcript 事件和终端显示；前置条件：9.1 完成；验收标准：新增 `transcript_partial` 事件，终端输出 `实时转写：<文本>`，重复 partial 不刷屏；测试要点：事件顺序和 reporter 测试；优先级：P0；预计：45 分钟。
- [x] 9.3 实现本地 streaming STT partial provider；前置条件：本地 STT 模型已由 `model-check` 覆盖；验收标准：`SherpaOnnxSttProvider` 支持 streaming session，cloud final ASR 模式下仍使用本地 streaming STT 做 partial；测试要点：fake session 与 metadata partial 单测；优先级：P0；预计：60 分钟。
- [x] 9.4 接入 `VoiceAssistantPipeline` 捕获循环；前置条件：9.2 至 9.3 完成；验收标准：用户说话期间持续 feed 已开始录音的帧，partial 在 `speech_started` 后、`transcript_final` 前输出；测试要点：live runtime partial 顺序测试；优先级：P0；预计：45 分钟。
- [x] 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. 本地语音链路、高质量实时转写与噪音过滤

- [x] 10.1 更新 OpenSpec 描述本地语音链路和降噪阶段；前置条件：真人日志确认旧本地 14M partial 会产生 `家/家确` 等噪声误识别；验收标准：proposal/design/spec/tasks 明确 wake/VAD/STT/partial/TTS/denoise 全本地、LLM 云端、正式问题阶段默认降噪；测试要点：OpenSpec strict；优先级：P0；预计：45 分钟。
- [x] 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 分钟。
- [x] 10.3 实现 `AudioPreprocessStage`；前置条件：10.2 完成；验收标准：新增可注入的 no-op 和 sherpa-onnx GTCRN online denoiser provider，正式问题帧在进入 VAD、partial STT、final STT 前共用同一份降噪后音频；测试要点：fake denoiser 验证 capture/STT 收到降噪后帧；优先级：P0；预计：60 分钟。
- [x] 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 分钟。
- [x] 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 分钟。
- [x] 10.6 更新 README、`.env.example` 和本地 `.env` 非密钥配置；前置条件：10.5 完成；验收标准：中文运行说明包含本地语音默认值、降噪开关、模型下载、model-check、run-live 验收；测试要点：命令可复制，`.env` 不进入提交；优先级：P0；预计：35 分钟。
- [x] 10.7 下载/校验新本地模型并执行门禁；前置条件：10.2 至 10.6 完成；验收标准：下载脚本、compileall、unittest、security-check、model-check、device-check、OpenSpec strict、git diff check 通过或记录真实设备失败原因；测试要点：输出不泄露 key，模型文件不进 Git；优先级：P0；预计：60 分钟。
- [x] 10.8 提交“本地语音降噪”模块；前置条件：10.7 门禁通过；验收标准：中文 commit 信息为 `[本地语音降噪]：完成本地语音链路和噪音过滤，包含降噪模型、本地ASR和实时字幕稳定策略`，提交后除本地 `.env` 非提交修改外无未提交源码/文档中间状态；优先级：P0；预计：10 分钟。

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

- [x] 11.1 更新 OpenSpec 描述模拟麦克风验收；前置条件：用户要求“自己一直测试到完整正常，自己弄模拟音频给麦克风”；验收标准：proposal/design/spec/tasks 明确新增可重复 `simulate-live`，覆盖两轮 live pipeline、实时字幕、降噪、上下文和恢复待机；测试要点：OpenSpec strict；优先级：P0；预计：35 分钟。
- [x] 11.2 实现模拟麦克风帧生成和 bounded transport；前置条件：live pipeline 已 stage 化；验收标准：模拟输入包含 wake、正式问题、短噪声 partial、背景噪声、两轮 turn，空队列不会无限等待；测试要点：失败时命令返回非 0；优先级：P0；预计：50 分钟。
- [x] 11.3 新增 `owner_voice_pet simulate-live` CLI；前置条件：11.2 完成；验收标准：默认两轮模拟，输出 JSON checks，可写入/回放 JSONL fixture；测试要点：CLI 单测和真实命令；优先级：P0；预计：40 分钟。
- [x] 11.4 补充 README 和自动化测试；前置条件：11.3 完成；验收标准：README 包含模拟验收命令，测试验证两轮闭环、partial 噪声过滤、第二轮临时上下文、fixture 写入/回放；测试要点：unittest；优先级：P0；预计：35 分钟。
- [x] 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 缓冲修正

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

## 13. 固化真实 Provider 完整流程 CLI

- [x] 13.1 更新 OpenSpec 和 README 描述 `real-live-check`；前置条件：12 组发现临时脚本证据不可重复；验收标准：proposal/design/spec/tasks/README 明确命令用途、默认真实播放、`--no-playback` 和 JSON 检查项；测试要点：OpenSpec strict；优先级：P0；预计：35 分钟。
- [x] 13.2 实现 `owner_voice_pet real-live-check`；前置条件：13.1 完成；验收标准：命令从 `.env` 读取配置，生成 wake/question PCM，运行真实 KWS/VAD/denoise/STT/LLM/TTS/pipeline/playback，并输出结构化 JSON；测试要点：CLI wiring 测试、transport 单测；优先级：P0；预计：60 分钟。
- [x] 13.3 执行真实命令验收和全量门禁；前置条件：13.2 完成；验收标准：`real-live-check --turns 2`、compileall、unittest、simulate-live、security-check、model-check、device-check、OpenSpec strict、git diff check 通过；优先级：P0；预计：60 分钟。
- [x] 13.4 提交“真实流程命令”模块；前置条件：13.3 通过；验收标准：中文 commit 信息为 `[真实流程命令]：完成完整链路自测入口，包含真实Provider CLI、播放验收和文档测试`，提交后 `git status --short` 为空；优先级：P0；预计：10 分钟。

## 14. 真实流程命令计时输出

- [x] 14.1 更新 OpenSpec 和 README 描述真实流程计时字段；前置条件：`real-live-check` 已可运行；验收标准：proposal/design/spec/tasks/README 明确 `started_at`、`finished_at`、`duration_ms`、`stage_timings`、`llm_request_timings.sent_at`；测试要点：OpenSpec strict；优先级：P0；预计：30 分钟。
- [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 分钟。