[文档、验收与归档]：完成真实运行说明和OpenSpec归档，包含README、最终门禁和主规范更新

README.md

@@ -1,57 +1,102 @@
 # Owner 语音桌宠
 
-这是 `add-voice-pet-pipeline` OpenSpec 变更交付的 Python 桌宠语音 Pipeline。
+这是一个 Python 语音桌宠运行程序。当前第一版先提供无 GUI 的真实实时语音循环：
 
-当前实现覆盖：
+`小杰小杰` 唤醒 -> 麦克风录音 -> VAD 切分 -> ASR 转文字 -> 携带本次进程内临时历史调用 LLM -> TTS 生成语音 -> 本机扬声器播放 -> 回到待机继续监听。
 
-- “小杰小杰”唤醒词入口
-- 本机音频 Transport 抽象和文件/内存回放测试通道
-- VAD 人声端点检测
-- 本地 STT Provider 边界和测试 Provider
-- OpenAI/NewAPI 兼容 LLM Provider
-- 本地 TTS Provider 边界和测试 TTS
-- 桌宠状态映射、无 GUI fallback、透明 PNG 状态资产
-- OpenSpec 主规范、自动化测试、CLI 验收和安全扫描
+## 当前能力
 
-## 配置
+- `owner_voice_pet run-live`：真实常驻语音循环。
+- `owner_voice_pet run-live --once`：只跑一轮，便于验收。
+- `.env` 直接读取配置，不要求导出 shell 环境变量。
+- `OWNER_SPEECH_PROVIDER=cloud|local`：选择云端语音模型或本地语音模型。
+- 默认云端语音模型：`mimo-v2.5-asr`、`mimo-v2.5-tts`。
+- 本地设备：`sounddevice` 读取麦克风，扬声器或 `afplay` 播放。
+- 本地模型：`models/` 存放 `sherpa-onnx` VAD/STT 模型，目录不提交 Git。
+- 临时上下文：同一次 `run-live` 进程内携带最近 user/assistant 历史，退出即清空。
 
-密钥不得写入仓库。运行时默认读取项目根目录的 `.env` 文件：
-
-- `OWNER_LLM_BASE_URL`
-- `OWNER_LLM_API_KEY`
-- `OWNER_LLM_MODEL`
-- `OWNER_LLM_API_STYLE`
-
-默认配置面向当前 NewAPI：
+## 首次准备
 
 ```bash
+python3.11 -m venv .venv
+.venv/bin/python -m pip install --upgrade pip
+.venv/bin/python -m pip install -e '.[speech]'
 cp .env.example .env
-# 然后编辑 .env，填入 OWNER_LLM_API_KEY
-OWNER_LLM_BASE_URL=https://newapi.mkbk.shop
-OWNER_LLM_MODEL=gpt-5.4-mini
-OWNER_LLM_API_STYLE=chat_completions
 ```
 
-## 验收命令
+然后编辑 `.env`，填写本地密钥和模型配置。当前默认示例：
+
+```dotenv
+OWNER_LLM_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1
+OWNER_LLM_API_KEY=
+OWNER_LLM_MODEL=mimo-v2.5
+OWNER_LLM_API_STYLE=chat_completions
+OWNER_SPEECH_PROVIDER=cloud
+OWNER_ASR_MODEL=mimo-v2.5-asr
+OWNER_TTS_MODEL=mimo-v2.5-tts
+OWNER_TTS_VOICE=mimo_default
+```
+
+`OWNER_SPEECH_PROVIDER=cloud` 会把 VAD 切出来的语音片段发送到云端 ASR；不会上传连续麦克风流。改成 `local` 时使用项目 `models/` 下的本地语音模型路径。
+
+## 本地模型
+
+即使默认走云端语音，也可以准备本地模型，便于切换到 `OWNER_SPEECH_PROVIDER=local`：
 
 ```bash
-PYTHONPATH=src python3.11 -m compileall src tests scripts
-PYTHONPATH=src python3.11 -m unittest discover -s tests
-PYTHONPATH=src python3.11 -m owner_voice_pet acceptance
-PYTHONPATH=src python3.11 -m owner_voice_pet validate-assets
-PYTHONPATH=src python3.11 -m owner_voice_pet security-check
+python3.11 scripts/download_speech_models.py --dir models
+.venv/bin/python -m owner_voice_pet model-check --models-dir models
+```
+
+`models/` 已在 `.gitignore` 中，不会提交大模型文件。
+
+## 设备检查
+
+```bash
+.venv/bin/python -m owner_voice_pet device-check
+```
+
+输出里 `ok=true` 表示已检测到可用麦克风和扬声器。
+
+## 运行
+
+单轮验收：
+
+```bash
+.venv/bin/python -m owner_voice_pet run-live --once
+```
+
+常驻重复对话：
+
+```bash
+.venv/bin/python -m owner_voice_pet run-live
+```
+
+运行后终端会显示待机、唤醒命中、录音中、转写中、思考中、播放中、恢复待机等状态。说“小杰小杰”后提问；听到回复后可以再次说“小杰小杰”继续下一轮。本次进程内会携带临时历史，程序退出后不保存。
+
+## 验证
+
+```bash
+.venv/bin/python -m compileall src tests scripts
+.venv/bin/python -m unittest discover -s tests
+.venv/bin/python -m owner_voice_pet acceptance
+.venv/bin/python -m owner_voice_pet validate-assets
+.venv/bin/python -m owner_voice_pet security-check
+.venv/bin/python -m owner_voice_pet model-check --models-dir models
+.venv/bin/python -m owner_voice_pet device-check
 openspec validate --all --strict
 ```
 
-真实 NewAPI smoke 测试示例：
+LLM smoke：
 
 ```bash
-PYTHONPATH=src python3.11 -m owner_voice_pet llm-smoke --no-stream --message '用一句中文回复：小杰在线。'
+.venv/bin/python -m owner_voice_pet llm-smoke --no-stream --message '用一句中文回复：小杰在线。'
 ```
 
 ## 安全约束
 
-- API key 只从环境变量读取。
-- 仓库内不保存真实密钥。
-- 默认不持久化原始麦克风音频。
-- `security-check` 会扫描已跟踪文本文件中的 `sk-...` 形式密钥。
+- API key 只写入本地 `.env`，`.env` 不提交 Git。
+- `models/`、`.venv/` 和临时音频文件不提交 Git。
+- 默认不持久化麦克风原始音频。
+- 云端 ASR 只接收 VAD 切分后的语音片段。
+- `security-check` 会扫描已跟踪文本文件中的 `sk-...` 和 `tp-...` 形式密钥。