Owner/openspec/changes/complete-live-repeat-voice-runtime/tasks.md

# 补齐真实可重复对话的实时语音运行版任务

## 1. OpenSpec 修正与提交

- [x] 1.1 编写 `proposal.md`，完整说明真实重复语音运行版的业务目标、需求、设计、风险、任务、Spec Deltas、实施计划和 Git 提交规范；前置条件：确认 `add-voice-pet-pipeline` 已 archive；验收标准：文档明确当前变更是修改既有 `voice-pet-pipeline` 能力，不是新增能力；测试要点：人工检查不再把 acceptance 当完整；优先级：P0；预计：45 分钟。
- [x] 1.2 编写 `design.md`，细化 live runtime、sounddevice、sherpa 模型、macOS TTS、临时上下文和状态机；前置条件：proposal 完成；验收标准：接口、状态、错误码、依赖影响明确；测试要点：设计能映射到后续代码任务；优先级：P0；预计：45 分钟。
- [x] 1.3 编写 `specs/voice-pet-pipeline/spec.md` delta；前置条件：proposal 确认 modified capability；验收标准：包含 `run-live`、重复对话、临时上下文、模型/设备检查、错误恢复、安全隐私和性能指标 SHALL；测试要点：OpenSpec strict 校验通过；优先级：P0；预计：45 分钟。
- [x] 1.4 编写 `tasks.md` 原子任务；前置条件：design/spec 完成；验收标准：任务按阶段排序，每项不超过 1 小时，包含前置条件、优先级、验收标准、测试要点；测试要点：OpenSpec apply 能读取任务；优先级：P0；预计：45 分钟。
- [x] 1.5 执行 OpenSpec 校验并提交；前置条件：1.1 至 1.4 完成；验收标准：`openspec validate complete-live-repeat-voice-runtime --strict` 和 `openspec validate --all --strict` 通过后立即 commit；测试要点：提交信息为中文格式；优先级：P0；预计：20 分钟。

## 2. 依赖、模型和配置规划落地

- [x] 2.1 更新 `.gitignore` 忽略 `models/`、`.venv/`、TTS 临时音频和 Python 缓存；前置条件：OpenSpec 提交完成；验收标准：模型和本地密钥不会出现在 git status；测试要点：`git status --short` 不列出模型大文件；优先级：P0；预计：20 分钟。
- [x] 2.2 更新 `.env.example`，加入模型目录、上下文预算和 live runtime 相关配置；前置条件：配置字段确认；验收标准：用户复制后可填写 key 并运行；测试要点：配置加载测试覆盖默认值；优先级：P0；预计：30 分钟。
- [x] 2.3 新增 `scripts/download_speech_models.py --dir models`；前置条件：确认模型来源；验收标准：脚本能创建模型目录、下载/解压模型、写入 manifest；测试要点：脚本参数解析和 manifest 测试通过；优先级：P0；预计：60 分钟。
- [x] 2.4 在项目本地 `.venv` 安装 `sounddevice`、`numpy`、`sherpa-onnx`；前置条件：`python3.11` 可用；验收标准：`.venv/bin/python -c` 可导入三个依赖；测试要点：不污染全局环境；优先级：P0；预计：30 分钟。
- [x] 2.5 下载模型到 `models/` 并运行 `model-check` 预备验证；前置条件：下载脚本完成；验收标准：模型文件存在且未进入 Git；测试要点：`git status --short` 不列出模型文件；优先级：P0；预计：60 分钟。
- [x] 2.6 验证并提交“依赖、模型和配置”模块；前置条件：2.1 至 2.5 完成；验收标准：compileall、相关测试、security-check、OpenSpec strict 通过后 commit；测试要点：提交信息为中文格式；优先级：P0；预计：20 分钟。

## 3. 本机音频 Transport 与设备检查

- [ ] 3.1 实现 `device-check` CLI；前置条件：sounddevice 依赖可导入或可诊断；验收标准：输出输入/输出设备可用性和失败原因；测试要点：mock sounddevice 成功/失败；优先级：P0；预计：45 分钟。
- [ ] 3.2 完善 `SoundDeviceAudioTransport` 输入流；前置条件：现有 Transport 协议已读；验收标准：可打开麦克风并读取 16 kHz 单声道帧；测试要点：fake sounddevice 测试帧队列和关闭；优先级：P0；预计：60 分钟。
- [ ] 3.3 完善 `SoundDeviceAudioTransport` 播放路径；前置条件：AudioSegment 播放格式确定；验收标准：可播放 PCM 或交给 `afplay` 播放临时文件；测试要点：播放成功/失败返回结构化结果；优先级：P0；预计：60 分钟。
- [ ] 3.4 增加设备和 Transport 错误恢复测试；前置条件：3.1 至 3.3 完成；验收标准：无设备、缺依赖、播放失败均不抛未捕获异常；测试要点：unittest 覆盖；优先级：P0；预计：45 分钟。
- [ ] 3.5 验证并提交“本机音频 Transport”模块；前置条件：3.1 至 3.4 完成；验收标准：compileall、transport tests、device-check、OpenSpec strict 通过后 commit；测试要点：提交信息为中文格式；优先级：P0；预计：20 分钟。

## 4. Wake/VAD/STT 与模型检查

- [ ] 4.1 实现 `model-check` CLI；前置条件：模型 manifest 和路径约定完成；验收标准：检查依赖、目录、关键文件和 Provider 可加载性；测试要点：缺模型、缺依赖、成功三类测试；优先级：P0；预计：45 分钟。
- [ ] 4.2 实现 `SherpaOnnxVadProvider` 或等价本地 VAD 适配；前置条件：模型文件可用；验收标准：可分析帧并输出 speech/silence；测试要点：fake 模型或短音频 fixture；优先级：P0；预计：60 分钟。
- [ ] 4.3 实现 `SherpaOnnxSttProvider` 真实转写；前置条件：STT 模型文件可用；验收标准：可从 AudioSegment 返回中文文本；测试要点：空音频、无模型、成功 fixture；优先级：P0；预计：60 分钟。
- [ ] 4.4 实现 live 唤醒检测策略；前置条件：STT/VAD 可用；验收标准：能从实时音频中识别“小杰小杰”并进入录音，不把唤醒词传给 LLM；测试要点：命中/未命中测试；优先级：P0；预计：60 分钟。
- [ ] 4.5 增加 VAD 端点和 STT 文本有效性测试；前置条件：4.1 至 4.4 完成；验收标准：无语音、空文本、最大录音时长均可恢复待机；测试要点：runtime 状态断言；优先级：P0；预计：45 分钟。
- [ ] 4.6 验证并提交“Wake/VAD/STT 与模型检查”模块；前置条件：4.1 至 4.5 完成；验收标准：compileall、wake/vad/stt tests、model-check、OpenSpec strict 通过后 commit；测试要点：提交信息为中文格式；优先级：P0；预计：20 分钟。

## 5. Live runtime、LLM/TTS 与临时上下文

- [ ] 5.1 新增 `LiveVoiceRuntime` 常驻循环；前置条件：Transport、Wake/VAD/STT 可用；验收标准：默认循环、`--once` 单轮、Ctrl-C 清理；测试要点：fake runtime 两轮；优先级：P0；预计：60 分钟。
- [ ] 5.2 新增 `run-live` CLI；前置条件：LiveVoiceRuntime 可构造；验收标准：读取 `.env`、构造 Provider、输出中文状态；测试要点：CLI 参数和错误码测试；优先级：P0；预计：60 分钟。
- [ ] 5.3 接入 LLM 请求临时历史；前置条件：ConversationContext 可复用；验收标准：第二轮请求包含第一轮 user/assistant；新 runtime 上下文为空；测试要点：temporary-context 和 process-local 测试；优先级：P0；预计：60 分钟。
- [ ] 5.4 接入 macOS `say/afplay` TTS 播放；前置条件：TTS Provider 已有边界；验收标准：非空回复可生成并播放音频；测试要点：mock subprocess 成功/失败；优先级：P0；预计：45 分钟。
- [ ] 5.5 增加 live 错误恢复；前置条件：runtime 主流程完成；验收标准：STT 空文本、LLM 失败、TTS 失败、播放失败后都恢复待机；测试要点：状态序列测试；优先级：P0；预计：60 分钟。
- [ ] 5.6 验证并提交“Live runtime 与临时上下文”模块；前置条件：5.1 至 5.5 完成；验收标准：compileall、unittest、security-check、OpenSpec strict 通过后 commit；测试要点：提交信息为中文格式；优先级：P0；预计：20 分钟。

## 6. 文档、真实验收、归档

- [ ] 6.1 更新 README 中文运行说明；前置条件：CLI 和脚本完成；验收标准：包含 `.venv`、`.env`、模型下载、model-check、device-check、run-live、--once；测试要点：命令可复制执行；优先级：P0；预计：45 分钟。
- [ ] 6.2 执行本地模型验收；前置条件：模型已下载；验收标准：`python3.11 scripts/download_speech_models.py --dir models` 和 `model-check` 通过或给出明确设备/模型失败证据；测试要点：输出不泄露 key；优先级：P0；预计：60 分钟。
- [ ] 6.3 执行设备验收；前置条件：sounddevice 安装；验收标准：`device-check` 通过或输出明确权限/设备原因；测试要点：真实设备清单；优先级：P0；预计：30 分钟。
- [ ] 6.4 执行真实运行验收；前置条件：`.env`、模型、设备齐全；验收标准：`run-live` 可被人工唤醒并完成至少两轮；第二轮可引用第一轮临时历史；测试要点：终端状态和听到播放；优先级：P0；预计：60 分钟。
- [ ] 6.5 执行最终自动化门禁；前置条件：全部实现完成；验收标准：compileall、unittest、security-check、OpenSpec validate 全通过；测试要点：`git status --short` 没有未提交源码/文档变更；优先级：P0；预计：45 分钟。
- [ ] 6.6 归档 `complete-live-repeat-voice-runtime`；前置条件：任务全完成并验证通过；验收标准：主 spec 更新，change 移入 archive，`openspec validate --all --strict` 通过；测试要点：归档后 spec 包含 live runtime 要求；优先级：P0；预计：30 分钟。
- [ ] 6.7 最终提交“文档、验收与归档”模块；前置条件：6.1 至 6.6 完成；验收标准：最终门禁通过后 commit，工作树干净；测试要点：提交信息为中文格式；优先级：P0；预计：20 分钟。