方案 v2.4 修订：按评审意见修正 8 处

评审指出的问题，逐条修正：

1. AEC 结论过早
   原文写"WebRTC 自带 AEC，因此解决 P2"，这是把"框架有实现"当成了
   "链路配置正确"。补充了三个前提：麦克风采集与播放参考要正确送入、
   XVF3800 自身 AEC 路由需实测（两处 AEC 串联可能互相干扰）、
   打断判定依赖 AEC 输出质量。P2 该行改标"待验证"。

2. 音频路径旧描述
   第 157 行仍写"N5095 的 TTS"，已改为完整链路：
   服务器 Qwen3-TTS → WebRTC → N5095 USB 播放端点 → XVF3800 AUX → 音箱。
   并补一条：AEC 所需播放参考必须在 N5095 本地可得，不能依赖服务器回放时钟
   （两侧时钟不同步会导致参考信号对不齐）。

3. "N5095 不跑任何推理"不准确
   方案自己安排 N5095 跑 VAD、唤醒、人脸检测，这些也是推理。
   改为"不运行 STT/TTS/LLM 等重型推理"。

4. 架构变更理由说过重
   原文称"N5095 跑不动可用的语音模型"，但 P0 数据证明它能跑
   Zipformer STT（RTF 0.22）和 Piper TTS（RTF 0.36）。
   改为"N5095 能完成低配本地语音，但达不到当前的目标音质与延迟"——
   音质达标的 Qwen3-TTS 在它上面 RTF 1.86，在服务器上 0.09。

5. 客户端/服务器音频边界未定义（新增一节）
   传什么（持续音频 vs 带预卷的语音段）、唤醒在哪端、打断谁判定、
   断线抖动如何恢复——四个问题列了选项与权衡，给出当前倾向，
   并标注必须在做 WebRTC 客户端之前定稿，否则接口要返工。

6. STT 是最大功能风险
   在 §5 表格和 §10 各标出：中文真人识别率至今无可信数据，
   音频硬件到手后应优先录制本人语音算 CER，并与 SenseVoice /
   faster-whisper large-v3 对比。

7. 首音延迟需按真实链路重测
   当前 1545ms 是非流式、无 VAD、无传输、无播放缓冲的数据。
   补入必须计入分句等待、WebRTC 抖动、播放缓冲，并测 P50/P95。

8. 尾部旧状态与重复段
   §10 重写：原文还写"继续确认 Ubuntu 版本""未做实机测试"，
   与 v2.4 实际进度冲突。改为已完成/下一步/风险/待办四段。
   删除 §5 中完全重复的 P0 测试说明段。

同时采纳评审给出的下一步顺序：先闭环实时语音链路
（WebRTC 客户端 → 真实音频 → AEC/打断/STT 正确率），
再推 ESP32 表情，最后摄像头/多人/电机。

有趣的项目/AI桌面陪伴助手/AI桌面陪伴助手方案.md

@@ -12,8 +12,16 @@
 > 原方案备份：AI桌面陪伴助手方案.v1备份.md。本版指标为拟定目标，不是已测性能。
 >
 > **本版重大变更：架构从"单机"改为"服务器即助手、本地为客户端"。**
-> 起因是实测发现 N5095（无 AVX2）跑不动可用的语音模型——详见
+>
-> `P0-语音基准报告.md`。变更后 N5095 只做 USB 外设接入与网络桥接。
+> 起因要说得准确：**N5095 并非跑不动本地语音**。实测证明它能跑
+> Zipformer STT（RTF 0.22）和 Piper TTS（RTF 0.36），是一条可用的低配本地链路。
+> 真正的问题是——**它达不到当前的目标音质与延迟**：音质令人满意的
+> Qwen3-TTS 在 N5095 上 RTF 高达 1.86（慢于实时），而服务器上只有 0.09。
+> 所以是"本地语音可用但不够好"，不是"本地语音不可行"。
+> 详见 `P0-语音基准报告.md`。
+>
+> 变更后 N5095 只做 USB 外设接入与网络桥接，**不运行 STT/TTS/LLM 等重型推理**
+> （轻量推理仍在本地，见 §1）。
 > 详细部署现状见代码仓库里的 `部署说明.md`，实测数据见本目录的四份 P0 报告。
 
 ## 1. 范围与待讨论事项
@@ -24,7 +32,7 @@
 |---|---|---|
 | **主机分工** | **服务器（cadadmin-server）跑助手本体；N5095 降为客户端/外设桥** | **v2.4 重大变更，见 §2** |
 | 服务器 | i9-14900K / 32线程 / 188G / RTX 3090 24G，局域网延迟 1–2ms | 与 N5095 同局域网，1ms 级 |
-| N5095 角色 | USB 麦克风阵列、USB 摄像头、DoA 读取、WebRTC 客户端、串口给 ESP32 | 不跑任何推理 |
+| N5095 角色 | USB 麦克风阵列、USB 摄像头、DoA 读取、WebRTC 客户端、串口给 ESP32 | **不运行 STT/TTS/LLM 等重型推理**；本地仍跑 VAD、唤醒词、人脸检测等轻量推理（这些延迟敏感或依赖本地硬件，放服务器反而更慢） |
 | 使用人数 | 本人使用为主，同时考虑多人扩展 | 首版基础多人，身份与会话从一开始分离 |
 | 新增预算 | 服务器为复用已有机器，不算追加采购 | 音频优先，其次屏幕，再机械 |
 | 操作系统、现有外设 | Ubuntu 24.04 已确认；麦克风、音箱、摄像头都没有；屏幕已到货 | 需采购音频与摄像头 |
@@ -68,8 +76,16 @@ ESP32-S3：本地表情、运动轨迹、限位、心跳超时处理
 - **分工原则：延迟敏感且硬件绑定的留在本地**（音频进出、唤醒、VAD、
   插话检测、DoA、表情/动作），**算力密集的放服务器**（STT、TTS、LLM 调用、记忆）。
 - Pipecat作为唯一会话管线框架。服务器侧用 WebRTC 传输（SmallWebRTC），
-  **WebRTC 自带 AEC、抖动缓冲、丢包恢复**——这解决了方案 P2 要求的 AEC 难题，
+  它**自带** AEC、抖动缓冲、丢包恢复的实现，省去了自行编写。
-  原本需要自行实现。[传输选型](https://docs.pipecat.ai/client/concepts/choosing-a-transport)
+  [传输选型](https://docs.pipecat.ai/client/concepts/choosing-a-transport)
+- ⚠️ **但"WebRTC 自带 AEC"不等于 AEC 问题已解决。** 框架有实现，不代表
+  链路配置对了。至少要满足：
+  1. N5095 的 WebRTC 客户端把**麦克风采集**和**扬声器播放参考信号**都正确
+     送入音频处理模块——播放参考缺失或时间戳不对齐，AEC 就不会工作；
+  2. XVF3800 自身的 AEC 路由要实测（它自己也会做回声消除，两处 AEC
+     串联可能互相干扰，需要确认该用哪一个、另一个是否要关）；
+  3. 打断检测依赖 AEC 的输出质量，AEC 不对，打断就会误触发或漏触发。
+  **P2 的 AEC 项保持"待验证"，在真实麦克风+音箱接上并实测前不算通过。**
 - 不叠加Vision Agents：它是Stream的独立框架，不是Pipecat官方扩展。人脸检测另选轻量本地模型。[项目官方仓库](https://github.com/GetStream/vision-agents)
 - STT/TTS采用可替换适配器（本地/远端两种后端已实现）。LLM 为 DeepSeek
   `deepseek-flash`；这是可更新别名，实施时记录实际版本并做流式/工具调用验证。
@@ -101,7 +117,7 @@ ESP32-S3：本地表情、运动轨迹、限位、心跳超时处理
 |---|---|---|---|
 | P0 环境与服务 | 盘点Ubuntu版本/USB；固定依赖；本地STT/TTS基准及DeepSeek请求 | 样例音频/文本先测试；设备到货后10次录放测试；记录RTF、首音延迟、CPU和内存 | 🔶 **环境盘点、STT/TTS/LLM 基准、DeepSeek 四条路径均已实测**；缺 10 次录放（无音频硬件）。**STT 中文识别率仍是未闭合项** |
 | P1 基础语音 | 按键启动；流式回复；停止按钮；超时提示 | 20轮固定中文用例至少18轮完成；短问答结束到首段有声回复，目标P50≤2秒、P95≤4秒 | 🔶 **链路已跑通**（文本/音频 → STT → 记忆 → LLM → TTS → 音频，16/16 通过）；缺实时音频进出、按键、20 轮用例。首音实测约 1.5s，加 VAD 后 **2.0–2.2s，卡在目标线** |
-| P2 外放与表情 | AEC、打断、唤醒；听/想/说/离线/静音表情 | 指定距离音量下20次打断至少18次成功；检测到有效用户语音至停播目标≤300ms；30分钟外放无自我触发；运行2小时稳定 | ⬜ 未开始。**AEC 计划由 WebRTC 提供**（不自行实现） |
+| P2 外放与表情 | AEC、打断、唤醒；听/想/说/离线/静音表情 | 指定距离音量下20次打断至少18次成功；检测到有效用户语音至停播目标≤300ms；30分钟外放无自我触发；运行2小时稳定 | ⬜ 未开始。**AEC 待验证**——WebRTC 有现成实现，但需要麦克风采集与播放参考正确送入、且 XVF3800 自身的 AEC 路由要实测（见 §2） |
 | P3 多用户记忆 | 用户档案、显式切换、偏好/摘要/修改/遗忘 | 两个用户同一问题得到各自偏好；未知用户无私人记忆；重启保留、更正/删除有效 | 🔶 数据层已实现并测试（身份隔离、越权删除、级联清理、候选不参与检索共 28 项）；缺"修改/遗忘"的用户入口 |
 | P4 一轴转头 | 静态DoA/人脸验证，再接电机；锁定和限位 | 左/中/右各10次唤醒至少27次转向正确区域；轻微移动不频繁摆动；断联/重启不撞限位；运动时重复P2测试 | ⬜ 未开始，待摄像头与电机 |
 | P4a 基础多人/身份试验 | 2～3张脸跟踪；轮流发言；可选录入式人脸识别 | 20次轮流唤醒至少18次选中正确目标；同方向/交叉/遮挡时允许拒判；未知人、身份切换不得串记忆 | 🔶 `IdentityProvider` 接口与手动切换已实现（人脸候选**不自动切换**已测试）；缺人脸检测 |
@@ -154,7 +170,17 @@ P2的30分钟/2小时测试仅是初步门槛，不能证明长期稳定。阶
 
 阵列官方资料列出USB音频、DoA主机控制、可接耳机/有源音箱的AUX输出。采购成品板，不能仅凭XMOS芯片名替代。[Seeed官方文档](https://wiki.seeedstudio.com/respeaker_xvf3800_introduction/)
 
-拟定路径：N5095的TTS → 阵列USB播放端点 → AUX → 有源音箱。AEC需要实际播放参考；同一板卡也要验证固件/通道配置，不能假定接上即成功。[XMOS官方指南](https://www.xmos.com/documentation/XM-014888-PC/pdf/xvf3800_user_guide_v3.2.1.pdf)
+拟定路径（v2.4 修正：TTS 已不在 N5095）：
+
+```
+服务器 Qwen3-TTS → WebRTC → N5095 → 阵列 USB 播放端点 → AUX → 有源音箱
+```
+
+AEC 需要实际播放参考；同一板卡也要验证固件/通道配置，不能假定接上即成功。[XMOS官方指南](https://www.xmos.com/documentation/XM-014888-PC/pdf/xvf3800_user_guide_v3.2.1.pdf)
+
+**注意**：播放链路跨了服务器和客户端两侧，AEC 所需的"播放参考信号"必须在
+N5095 本地可得（即从阵列 USB 播放端点或本地播放缓冲取），**不能依赖服务器侧的回放时钟**——
+两侧时钟不同步，参考信号就对不齐。[详见 §2 的 AEC 说明]
 
 不为了阵列额外购买XIAO ESP32S3，主机直接接USB即可。最终内置喇叭/功放留到结构阶段，按接口、电压、阻抗和功率匹配。
 
@@ -183,15 +209,19 @@ P2的30分钟/2小时测试仅是初步门槛，不能证明长期稳定。阶
 
 ### 语音方案（v2.4 已实测定稿）
 
-STT是语音转文字，TTS是文字转语音。**v2.4 起语音推理全部在服务器**，
+STT是语音转文字，TTS是文字转语音。**v2.4 起重型语音推理（STT/TTS/LLM）全在服务器**，
-N5095 只做音频进出——实测证明 N5095 跑不动可用的语音模型，见 `P0-语音基准报告.md`。
+N5095 只做音频进出与本地轻量推理。
+
+准确的表述是：**N5095 能完成低配本地语音，但达不到当前的目标音质与延迟**。
+实测它能跑 Zipformer STT（RTF 0.22）和 Piper TTS（RTF 0.36）；而音质达标的
+Qwen3-TTS 在它上面 RTF 1.86（慢于实时），在服务器上只有 0.09。见 `P0-语音基准报告.md`。
 
 | 模块 | 采用方案 | 实测 | 备选与限制 |
 |---|---|---|---|
 | VAD | 本地轻量VAD | — | 单独处理唤醒和说完判断 |
 | 唤醒 | sherpa-onnx中文关键词检测作为候选 | — | 单独模型/词表，用户确定称呼后调阈值；普通STT不会自动等于唤醒引擎 |
-| STT | **Zipformer 中英双语 int8**（服务器 CPU 4线程） | RTF 0.03 | **仍是 2023 年模型，中文识别率从未测过**（无参考文本）。候选：SenseVoice / faster-whisper large-v3，已下载未测 |
+| STT | **Zipformer 中英双语 int8**（服务器 CPU 4线程） | RTF 0.03 | ⚠️ **最大功能风险**：仍是 2023 年模型，**中文真人识别率至今无可信数据**。音频硬件到手后优先录制本人语音算 CER，并与 SenseVoice / faster-whisper large-v3 对比（已下载待测） |
-| TTS | **Qwen3-TTS 1.7B-CustomVoice**（服务器 3090，独立 HTTP 服务） | RTF 0.55–0.94 | 音色 Serena + 指令"用轻快活泼的语气说"（用户试听选定）。备选：vits-zh-ll（RTF 0.09 但音色不满意）、CosyVoice 2/3（未测） |
+| TTS | **Qwen3-TTS 1.7B-CustomVoice**（服务器 3090，独立 HTTP 服务） | RTF 0.55–0.94 | 音色 Serena + 指令"用轻快活泼的语气说"（用户试听选定）。备选：vits-zh-ll（RTF 0.09 但音色不满意）、CosyVoice 2/3（未测）。**首音延迟需按真实链路重测**，见 §10 |
 | LLM | **DeepSeek `deepseek-flash`**（云端，关思考） | 首 token 0.8–1.2s | 本机 Qwen3.8-27B 的 vLLM 已停用——GPU 让给 TTS。可改 `AI_LLM_PRIMARY=local` 切回，但切回后 GPU 不够跑 Qwen3-TTS |
 
 [sherpa-onnx官方功能](https://k2-fsa.github.io/sherpa/intro.html)、[SenseVoice模型说明](https://k2-fsa.github.io/sherpa/onnx/sense-voice/pretrained.html)、[中文VITS模型](https://k2-fsa.github.io/sherpa/onnx/tts/pretrained_models/vits.html)。以上说明模型/运行时支持，不构成性能保证。
@@ -210,7 +240,6 @@ N5095 只做音频进出——实测证明 N5095 跑不动可用的语音模型
 P0测试10～20条不同长度中文，覆盖数字、日期、中英混读。记录STT识别错误、语音结束后等待时间、TTS首段耗时和RTF（生成/处理耗时除以音频时长，低于1表示平均快于实时）。音频与视觉并发时重测，限制推理线程和视觉帧率，避免CPU争抢。
 **v2.4 补充：STT 与 TTS 的线程配置必须分别调**——实测两者线程扩展方向相反。
 
-P0测试10～20条不同长度中文，覆盖数字、日期、中英混读。记录STT识别错误、语音结束后等待时间、TTS首段耗时和RTF（生成/处理耗时除以音频时长，低于1表示平均快于实时）。音频与视觉并发时重测，限制推理线程和视觉帧率，避免CPU争抢。
 
 TTS按语义短句合成并播放，不把整段一次合成称为原生流式；分句仍要测首音等待、接句停顿及取消响应。本地效果不达标时先调整模型/线程/分句，再讨论是否开启云端后备，不自动发送音频到第三方。
 
@@ -227,6 +256,26 @@ TTS按语义短句合成并播放，不把整段一次合成称为原生流式
 - 网络失败给简短提示，本地按键、静音和屏幕继续工作，不反复播旧回复。
 - 麦克风、音箱、电机尽量机械隔离；软件静音和真实物理断麦需明确区分。
 
+### 客户端/服务器的音频边界（v2.4 新增，待定稿）
+
+**架构改了，但这条边界还没定义。** N5095 与服务器之间传什么、谁判定、
+断了怎么办——这个接口不定下来，WebRTC、AEC、唤醒和首音延迟都没法正确实现。
+
+需要明确的四件事：
+
+| 问题 | 选项 | 权衡 |
+|---|---|---|
+| **传什么** | (a) 持续发送全部音频<br>(b) 只发 VAD 判定后的有效语音段（带 0.5–1s 预卷） | (a) 网络流量大、隐私面宽，但服务端可做更好的端点判定；<br>(b) 省带宽、隐私好，但 VAD 误判会切掉话头，且打断判定只能靠客户端 |
+| **唤醒在哪** | (a) 本地（N5095）<br>(b) 服务器 | 本地唤醒延迟低、断网也能响应；但唤醒词模型要跑在 N5095 上（轻量，可行）。**倾向本地** |
+| **打断谁判定** | (a) 客户端本地判定后发信号<br>(b) 服务端从音频流判定 | (a) 快（不受网络抖动影响），但需要客户端知道"助手正在说话"这个状态；(b) 准，但受网络延迟影响。**方案要求 ≤300ms，倾向 (a)** |
+| **断线/抖动恢复** | 需要定义缓冲深度、重连策略、播放中的音频怎么办 | 缓冲换稳定性，但直接加首音延迟 |
+
+**当前倾向**（待实测确认）：**本地做唤醒与 VAD，只在检测到有效语音时发送
+带预卷的语音段；打断由客户端本地判定；播放缓冲初始 100–200ms，按实测抖动调整。**
+
+这条边界会直接决定首音延迟预算，**必须在做 WebRTC 客户端之前定下来**，
+否则接口要返工。
+
 ## 6. 朝向与机械
 
 DoA是声源来向，不代表身份或距离。阵列固定底座，摄像头随头部转动。
@@ -302,10 +351,58 @@ P5通过Home Assistant统一调用。按实际设备比较官方Xiaomi Home和Xi
 
 ## 10. 运行维护与当前下一步
 
-- 固定依赖版本，记录板卡SKU、固件、通道、引脚及接线图。
+### 已完成（截至 2026-09-15）
-- Ubuntu优先先以普通用户的本机环境打通音频/USB，再确定常驻部署，暂不增加容器设备映射。核对Ubuntu版本、Python兼容性和CPU指令要求；模型文件授权与运行时授权分别记录。
+
-- 日志保存耗时、错误、费用、连接事件并轮转，不默认保存完整私人对话。
+- Ubuntu 24.04 已确认，USB 接口已盘点；依赖版本固定在代码仓库的 `requirements.txt`
-- P2后配置开机启动、异常重启、音频/串口重连，测试拔插、断网、主机重启恢复。
+- 助手本体在服务器上实现并跑通，端到端测试 16/16（**用文件音频，非实时链路**）
-- 已确认Ubuntu和四类缺失外设，不再重复询问。继续确认Ubuntu版本、USB接口和使用距离；按清单核价音频/屏幕/摄像头。基础多人和多用户数据结构纳入本次开发，自动身份能力以实测为准。
+- STT/TTS/LLM 三方基准实测；DeepSeek 四条路径验证
-- 不等待上述答案也能先推进表情和协议设计，通用原型件按缺口采购。
+- 记忆与身份的数据层实现并测试（88 项断言）
-- 本次只更新规划和采购条件；未安装依赖、重装系统、购买硬件或做实机测试。
+- 代码剥离为独立仓库 `~/workspace/ai-companion/`
+
+### 下一步顺序（按风险从高到低）
+
+评审建议的顺序，认可并采纳——**先把风险最大的实时语音链路闭环**：
+
+1. **N5095 的 WebRTC 音频客户端**（尚未开始）
+   含：音频采集/播放接入、与服务器的信令、VAD/唤醒的本地边界
+2. **接入真实麦克风与音箱**，验证 AEC、打断、唤醒
+   这是唯一能证伪 P2 的步骤，也是当前最大的未知
+3. **验证 STT 中文识别正确率**（见下"最大功能风险"）
+4. ESP32 表情串口（硬件已到货，可独立推进）
+5. 摄像头、多人跟踪、电机
+
+**理由**：语音链路是全局瓶颈。它若走不通，后面的表情、转头做得再好也没用；
+而它若走通，其余部分都是可分解的独立工作。
+
+### 最大功能风险：STT 中文识别率
+
+Zipformer 的速度没问题（服务器 RTF 0.03），但**中文真人识别率至今没有可信数据**——
+自带的 4 段测试音频没有参考文本，而 TTS→STT 往返法在这个模型上不成立
+（合成音频会触发大量重复字，真人录音却正常）。
+
+音频硬件到手后应优先做：**录一组本人语音**，覆盖普通话、数字、日期、中英混读、
+以及真实桌面距离（0.5–2m）与背景噪声，计算 CER，并**同时与 SenseVoice、
+faster-whisper large-v3 对比**（两者已下载待测）。这是 P0 唯一未闭合的功能项。
+
+### 首音延迟必须按真实链路重测
+
+当前 1545ms 是**非流式、无 VAD、无网络传输、无播放缓冲**的链路数据。
+真实对话还要加上：分句等待、WebRTC 传输抖动、N5095 侧播放缓冲。
+**必须测 P50/P95，不能只看 RTF。** 加 VAD 后已处在 2 秒目标边缘，
+这些额外开销很可能把它推过线。
+
+### 运维待办
+
+- **没有常驻服务**：TTS 服务和助手本体都没有 systemd 开机自启
+  （方案要求 P2 后配置）。服务器重启后需手动拉起
+- 日志保存耗时、错误、费用、连接事件并轮转，不默认保存完整私人对话
+- P2 后配置异常重启、音频/串口重连，测试拔插、断网、主机重启恢复
+- 记录板卡 SKU、固件、通道、引脚及接线图（ESP32 部分已有记录）
+- 模型文件授权与运行时授权分别记录（Qwen3-TTS 为 Apache-2.0；
+  Matcha 用的 Baker 数据集**标注仅限非商用**，若将来产品化需换音色）
+
+### 仍未确认
+
+- **屏幕最终形态**：2.8 寸方屏 vs 原定 1.28 寸圆屏，影响外壳与转台设计
+- **使用距离**：暂按 0.5–2m 设计，未实测确认
+- 音频套件与摄像头的具体 SKU 与核价