docs: 记录音频通路卡死导致语音输入输出失效的根因与 SIGSTOP 复现手法

补充长时间运行后 TTS/ASR 一起失效的真实根因（播放阶段缺超时兜底
导致 aplay 卡死、isSpeaking 永久卡住、僵尸进程拖垮 PulseAudio），
以及用 kill -STOP/-CONT 冻结下游服务来可控复现"子进程偶发挂死"
类 bug 的通用排查手法。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QeoAy5KmkHuKWHAktpEsaN

CLAUDE.md

@@ -207,6 +207,16 @@ const vectors = await Promise.all(texts.map((t, i) => fetchOne(t, i)))
 
 **调试这类"实际发声内容对不对"的问题时的教训**：想在渲染进程 monkey-patch `window.electronAPI.xxx` 来拦截调用做验证是无效的——`contextBridge.exposeInMainWorld` 暴露的对象默认被冻结，赋值会静默失败、不报错，很容易误判成"这条代码路径没走到"。真正能验证的办法是去主进程对应的 `ipcMain.handle(...)` 里临时加 `console.log`（验证完记得删），或者用 CDP 的 `Input.dispatchMouseEvent` 模拟真实点击、`Runtime.evaluate` 读 DOM/计算样式——这两种都是从"实际发生的效果"验证，不依赖能否篡改渲染进程里的 API 对象。
 
+### 长时间运行后语音输入输出一起失效（systemTts.ts）
+
+真机反馈：pad 跑了一两周之后语音输入输出全部失效。现场诊断：pulseaudio 占 49% CPU，系统里积压了 70 个从几天前就存在的 `aplay -t raw` 残留进程。
+
+**根因跟 `WAKE_IDLE_THRESHOLD_MS` 那条注释里提到的"PulseAudio 大约 5 秒空闲就挂起音频设备"是同一件事**：`speakWithVits`/`speakWithPiperStreaming` 每播一个分句就 spawn 一个 aplay，写完数据后调用 `stdin.end()`，然后完全依赖 aplay 自己触发 `'exit'` 事件才清理 `isSpeaking` 状态——没有任何超时兜底（合成侧 `vitsWorker` 倒是本来就有 60 秒超时）。长时间运行后一旦某次"唤醒音频通路"没成功，aplay 会卡在往挂死的 PulseAudio 写数据，`'exit'` 永远不触发，`isSpeaking` 永久卡 `true`，`playNext()` 不再处理队列，TTS 直接哑掉。**ASR 走的是渲染进程 `getUserMedia`/`AudioContext`，和 TTS 共用同一个被拖垮的 PulseAudio 实例**，所以语音输入也一起失效。更麻烦的是 `systemTtsStop()` 原来只发 `SIGTERM`，卡在系统调用里的 aplay 根本杀不掉——每次打断播报（每次提问前都会调一次）都可能攒下一个杀不死的僵尸进程，日积月累到 70 个，把 PulseAudio 彻底拖垮。
+
+**修复**：播放阶段加 `PLAYER_EXIT_TIMEOUT_MS`（8 秒）看门狗，`stdin.end()` 后超时未触发 `'exit'` 就判定通路卡死，`SIGKILL` 强杀并 `done(error)` 收尾；`systemTtsStop()` 加 `killWithEscalation()`，先 `SIGTERM`，1.5 秒宽限期后还没退出就 `SIGKILL`。
+
+**验证方法**：真机上拿 `kill -STOP <pulseaudio_pid>` 故意冻结 PulseAudio，模拟"音频通路卡死"的真实场景，再用 CDP 触发一次播报，确认看门狗在约 8 秒后正确强杀卡住的 aplay、队列自动继续、最终无残留进程，`kill -CONT` 解冻收尾。**这个冻结/解冻手法可以复用**：任何"子进程偶发挂死"的 bug，不必真的等它在真机自然复现，直接 `SIGSTOP` 它依赖的下游服务就能可控地造出卡死场景。
+
 ### 系统提示词：查不到内容时的答复
 
 提示词要求"说明手册中暂未查到，并给一条可操作的建议"，而不是硬邦邦一句"我不知道"。