# Python 桌宠语音 Pipeline 实施任务

## 1. OpenSpec 与项目骨架

- [x] 1.1 将 OpenSpec 工件从“只写计划”修正为“实施并验收 change”；前置条件：确认最新目标要求完整完成；验收标准：proposal、design、spec 不再把文档完成当作最终交付；测试要点：`openspec validate add-voice-pet-pipeline --strict` 通过；优先级：P0；预计：30 分钟。
- [x] 1.2 创建 Python 3.11+ 项目骨架；前置条件：本机 `python3.11` 可用；验收标准：存在 `pyproject.toml`、包目录、测试目录和命令入口；测试要点：`python3.11 -m compileall src tests` 通过；优先级：P0；预计：45 分钟。
- [x] 1.3 定义核心数据模型、状态枚举、错误码和 Provider 协议；前置条件：项目骨架已创建；验收标准：AudioFrame、AudioSegment、Transcript、Message、ReplyDelta、PipelineState、ProviderError 可被测试导入；测试要点：单元测试覆盖基础构造和错误码；优先级：P0；预计：60 分钟。
- [x] 1.4 实现配置加载和密钥边界；前置条件：核心模型已定义；验收标准：base URL、API key、模型名、设备、资产路径均来自环境变量或配置，API key 不写入仓库；测试要点：缺失 key 时返回结构化配置错误；优先级：P0；预计：45 分钟。
- [x] 1.5 完成“OpenSpec 与项目骨架”模块提交；前置条件：1.1 至 1.4 已完成；验收标准：先通过 compileall、单元测试和 OpenSpec strict 校验，再立即执行 Git commit；测试要点：提交信息使用“`[OpenSpec 与项目骨架]：完成[具体功能描述]，包含[关键变更]`”格式；优先级：P0；预计：20 分钟。

## 2. 音频 Transport

- [ ] 2.1 实现 `AudioTransport` 协议和本机音频错误对象；前置条件：核心模型已提交；验收标准：协议包含输入启动、帧读取、PCM 播放、停止、健康检查；测试要点：协议和错误码可导入；优先级：P0；预计：45 分钟。
- [ ] 2.2 实现内存/文件回放 Transport；前置条件：AudioTransport 协议已定义；验收标准：测试可注入音频帧并捕获播放结果，不依赖真实麦克风；测试要点：回放帧顺序、超时和播放队列通过单元测试；优先级：P0；预计：60 分钟。
- [ ] 2.3 实现可选本机 Transport 适配层；前置条件：Transport 协议已定义；验收标准：未安装音频依赖或无设备时返回结构化错误，不影响测试模式；测试要点：无依赖环境下导入不崩溃；优先级：P1；预计：60 分钟。
- [ ] 2.4 实现音频环形缓冲和格式校验；前置条件：音频模型和 Transport 已定义；验收标准：保留最近音频帧并校验采样率、声道、时间戳；测试要点：缓冲容量、顺序和非法帧测试通过；优先级：P0；预计：60 分钟。
- [ ] 2.5 完成“音频 Transport”模块提交；前置条件：2.1 至 2.4 已完成；验收标准：先通过相关测试、compileall 和 OpenSpec strict 校验，再立即执行 Git commit；测试要点：提交信息使用“`[音频 Transport]：完成[具体功能描述]，包含[关键变更]`”格式；优先级：P0；预计：20 分钟。

## 3. Wake/VAD/STT

- [ ] 3.1 实现本地唤醒词 Provider；前置条件：Transport 测试路径可用；验收标准：支持“小杰小杰”关键词事件和置信度阈值；测试要点：命中、未命中、模型失败场景通过；优先级：P0；预计：60 分钟。
- [ ] 3.2 实现 VAD Provider 和端点检测；前置条件：音频帧可回放；验收标准：检测说话开始、连续静音结束、无语音超时和最大录音保护；测试要点：四类 VAD 场景通过；优先级：P0；预计：60 分钟。
- [ ] 3.3 实现 STT Provider 协议、测试 Provider 和可选本地模型适配入口；前置条件：AudioSegment 可构造；验收标准：测试 Provider 能从 fixture metadata 转写，可选本地模型缺失时返回结构化错误；测试要点：成功、空文本、Provider 失败场景通过；优先级：P0；预计：60 分钟。
- [ ] 3.4 实现 STT 文本验证规则；前置条件：STT Provider 已实现；验收标准：空文本、纯标点、过短音频不会进入 LLM；测试要点：文本验证和 pipeline 跳过 LLM 测试通过；优先级：P0；预计：45 分钟。
- [ ] 3.5 完成“Wake/VAD/STT”模块提交；前置条件：3.1 至 3.4 已完成；验收标准：先通过相关测试、compileall 和 OpenSpec strict 校验，再立即执行 Git commit；测试要点：提交信息使用“`[Wake/VAD/STT]：完成[具体功能描述]，包含[关键变更]`”格式；优先级：P0；预计：20 分钟。

## 4. LLM/TTS 与对话闭环

- [ ] 4.1 实现 ConversationContext；前置条件：Message 模型已定义；验收标准：追加 user/assistant、构造 LLM messages、按预算截断；测试要点：上下文保留 system prompt 和最近轮次；优先级：P0；预计：45 分钟。
- [ ] 4.2 实现 OpenAI/NewAPI 兼容 LLM Provider；前置条件：配置加载已完成；验收标准：base URL、API key、model 均配置化，支持流式或非流式解析，不记录密钥；测试要点：mock HTTP 和可选真实 smoke 测试通过；优先级：P0；预计：60 分钟。
- [ ] 4.3 实现分句缓冲；前置条件：LLM delta 模型已定义；验收标准：中文标点、换行和长度阈值触发 TTS chunk；测试要点：空分句、超长句、连续 delta 测试通过；优先级：P0；预计：45 分钟。
- [ ] 4.4 实现本地 TTS Provider；前置条件：AudioSegment 模型和 Transport 可用；验收标准：提供 macOS `say` 可选 Provider 和 deterministic 测试 Provider；测试要点：非空文本生成非空音频，空文本报错；优先级：P0；预计：60 分钟。
- [ ] 4.5 实现 Pipeline 状态机和自抑制；前置条件：Wake/VAD/STT、Context、LLM、TTS、Transport 均可测试；验收标准：正常链路、空转写、LLM 失败、TTS 失败、播放期自抑制均可验证；测试要点：状态序列和错误恢复测试通过；优先级：P0；预计：60 分钟。
- [ ] 4.6 完成“LLM/TTS 与对话闭环”模块提交；前置条件：4.1 至 4.5 已完成；验收标准：先通过相关测试、compileall、真实或 mock LLM smoke 和 OpenSpec strict 校验，再立即执行 Git commit；测试要点：提交信息使用“`[LLM/TTS 与对话闭环]：完成[具体功能描述]，包含[关键变更]`”格式；优先级：P0；预计：20 分钟。

## 5. 桌宠 UI 与生图资产

- [ ] 5.1 实现桌宠状态控制器；前置条件：PipelineState 已定义；验收标准：idle/listening/recording/transcribing/thinking/speaking/error 状态映射到可显示 UI 状态；测试要点：状态映射单元测试通过；优先级：P0；预计：45 分钟。
- [ ] 5.2 实现可选桌面窗口入口和无 GUI fallback；前置条件：状态控制器已实现；验收标准：未安装 PySide6 时 CLI/测试不崩溃，安装后保留透明置顶窗口入口；测试要点：无 PySide6 环境导入和 fallback 测试通过；优先级：P1；预计：60 分钟。
- [ ] 5.3 使用 `imagegen` 生成可爱 3D 桌宠透明资产并保存到项目；前置条件：资产目录已定义；验收标准：项目中存在 idle/listening/thinking/speaking/error 可引用 PNG 或生成失败时有明确记录；测试要点：资产存在性和 alpha/格式校验通过；优先级：P0；预计：60 分钟。
- [ ] 5.4 实现资产清单和校验命令；前置条件：资产已保存；验收标准：运行验收命令可检查资产路径、状态覆盖和透明度元数据；测试要点：缺失资产时测试失败；优先级：P0；预计：45 分钟。
- [ ] 5.5 完成“桌宠 UI 与生图资产”模块提交；前置条件：5.1 至 5.4 已完成；验收标准：先通过相关测试、资产校验、compileall 和 OpenSpec strict 校验，再立即执行 Git commit；测试要点：提交信息使用“`[桌宠 UI 与生图资产]：完成[具体功能描述]，包含[关键变更]`”格式；优先级：P0；预计：20 分钟。

## 6. 测试、性能、安全、验收与归档

- [ ] 6.1 完成自动化测试套件；前置条件：所有模块已实现；验收标准：覆盖核心模型、配置、Transport、Wake/VAD/STT、Context、LLM/TTS、Pipeline、UI、资产；测试要点：`python3.11 -m unittest discover -s tests` 通过；优先级：P0；预计：60 分钟。
- [ ] 6.2 完成端到端验收命令；前置条件：Pipeline 可用；验收标准：fixture 音频链路可从“小杰小杰”走到播放输出和上下文更新；测试要点：CLI acceptance 命令退出码为 0；优先级：P0；预计：45 分钟。
- [ ] 6.3 完成 OpenAI/NewAPI smoke 验收；前置条件：提供临时 API key 环境变量；验收标准：调用配置的 base URL 获得非空 LLM 回复，失败时输出结构化诊断且不泄露 key；测试要点：真实 smoke 或可解释的网络失败证据；优先级：P0；预计：45 分钟。
- [ ] 6.4 完成安全检查；前置条件：全部代码已实现；验收标准：仓库中不包含 API key，日志脱敏，默认不持久化原始音频；测试要点：secret grep、配置测试和日志脱敏测试通过；优先级：P0；预计：30 分钟。
- [ ] 6.5 完成 OpenSpec archive；前置条件：所有任务完成并验证通过；验收标准：`openspec archive add-voice-pet-pipeline` 后主 spec 更新，change 进入 archive；测试要点：`openspec validate --all --strict` 通过；优先级：P0；预计：30 分钟。
- [ ] 6.6 完成最终验收提交；前置条件：6.1 至 6.5 已完成；验收标准：完整测试、OpenSpec strict 校验、git status 审计通过后立即 commit；测试要点：提交信息使用“`[测试、性能、安全、验收与归档]：完成[具体功能描述]，包含[关键变更]`”格式；优先级：P0；预计：20 分钟。