# OpenSpec：完整全双工 Agent 语音助手架构

## 功能目标

### 完整业务价值

当前 Owner 语音桌宠已经从最初的“唤醒词 -> VAD -> STT -> LLM -> TTS -> 播放”演进到可真实运行的 `run-live`，并具备本地唤醒、实时字幕、噪音过滤、连续追问、结束提示音和初步播报打断规划。但现有核心仍然是 turn-based 语音桌宠：用户先唤醒，系统听完一段话，识别完再思考，回复播放完再决定是否继续。这个模型能完成普通问答，但距离“小爱同学式持续对话”和完整 Agent 仍有明显差距。

本变更的业务目标是把现有语音桌宠规划升级为完整全双工 Agent 语音助手：麦克风持续输入、播放端持续输出、WebRTC APM 提供 AEC/NS/AGC 音频底座、Streaming STT 实时生成用户话语、LLM 流式回复按句进入 Streaming TTS、用户在 AI 讲话时可以自然打断，长期记忆和 Tool Router 让助手不只聊天，还能在安全边界内检索记忆、执行只读系统任务、调用 Open Interpreter 外部后端和 Playwright 浏览器自动化。

本阶段只产出 OpenSpec 审核材料，不改运行代码、不安装依赖、不下载模型、不接入工具执行、不把本地未跟踪的 `openinterpreter/` 复制进 Owner 代码，也不提交该目录。`openinterpreter/` 在本变更中只被定义为外部 CLI/子进程工具后端候选。

### 目标用户场景

1. 用户在 macOS 上启动语音助手后，不需要按住说话；麦克风常驻监听，系统通过本地唤醒或持续 VAD/STT 管理输入。
2. 用户听 AI 回复时可以直接插话；系统在 200 ms 目标延迟内停止 TTS 播放、取消当前 LLM/TTS 任务，并把用户新话语作为下一轮输入。
3. AI 自己的扬声器声音不会被误当成用户输入；WebRTC APM 的 AEC 使用播放 reference 音频消除回声，NS 降低环境噪声，AGC 统一麦克风音量。
4. 用户可以连续追问，不必每轮都说“小杰小杰”；Conversation Manager 根据状态机和上下文判断当前是继续听、执行工具、播报结果还是恢复待机。
5. 助手可长期记住非敏感偏好、事实、项目摘要和任务摘要；重启后仍可通过 FAISS+SQLite 召回相关记忆，但敏感信息默认不自动保存。
6. 用户要求“整理下载目录”“查一下项目文件”“打开网页抓取内容”时，Tool Router 先做安全分类，低风险只读工具可执行，高风险写操作、删除、上传、交易、权限变更必须要求确认，第一版不自动做 GUI 点击/键盘控制。
7. 后续桌宠 GUI 可订阅同一事件流展示听、想、说、工具执行、被打断、等待确认等状态，而不是重新实现 pipeline 逻辑。

### 量化成功指标 KPI

1. 打断延迟：在可控音频测试环境中，`speaking` 状态下检测到有效用户语音后，进入 `interrupted` 并停止播放的 P95 延迟目标小于 200 ms。
2. 回声抑制：播放 reference 音频注入 AEC 后，纯助手回放不触发用户 VAD/STT，不产生有效 `barge_in_detected`。
3. 实时识别：用户开始说话后，Streaming STT 首个稳定 partial transcript 的 P95 目标小于 800 ms。
4. 端到端首音：LLM 首个可播报句子产生后，Streaming TTS 首个可播放 PCM chunk 的 P95 目标小于 1000 ms。
5. 流式播报：LLM 不等待完整回复；中文回复按句切分进入 TTS，第一句可播放后立即播放。
6. 取消可靠性：用户打断时，当前 LLM stream、TTS synthesis、playback、工具执行候选任务均收到 cancellation token；被取消内容不得继续写入上下文。
7. 记忆召回准确性：保存的偏好/事实/项目摘要在相关查询中可被 Top-K 检索召回；关闭记忆时不得读写 SQLite/FAISS。
8. 工具安全：未授权工具、越权路径、写操作、删除操作、账号/上传/交易类任务必须被拒绝或进入确认流程；自动化测试覆盖非法工具拒绝、防循环、超时、输出截断。
9. 兼容性：现有 turn-based `run-live` 语义在迁移期不得被破坏；新全双工入口可分阶段实现，允许先以 feature flag 启用。
10. OpenSpec 完整性：`openspec validate add-full-duplex-agent-voice-assistant --strict` 与 `openspec validate --all --strict` 必须通过。

### 预期影响

1. 主规范 `voice-pet-pipeline` 将从“Python 桌宠语音 pipeline”升级为“全双工 Agent 语音助手 pipeline”，覆盖音频底座、并发模型、记忆、工具和安全策略。
2. 后续实现将新增 WebRTC APM provider、全双工音频环形缓冲、Streaming STT/TTS provider、Conversation Manager、MemoryManager、ToolRouter、Open Interpreter adapter、Playwright browser adapter。
3. 现有 GTCRN 降噪、主说话人音色门控和本地 KWS 保留为 fallback 或局部能力，不再作为完整全双工回声消除的主方案。
4. 当前进程内临时上下文保留，但长期记忆成为独立层；临时会话历史和长期记忆必须有清楚边界。
5. 工具执行引入新的安全面，必须规划确认策略、权限边界、路径限制、超时、输出截断、审计日志和敏感信息脱敏。
6. 第一版电脑控制不做 GUI 点击/键盘/屏幕控制；只预留 `ComputerControlProvider`。Codex Computer Use 只参考安全确认策略，不复制私有或捆绑实现。

### 对现有问题的系统性总结

1. 性能问题：现有 turn-based pipeline 在录音结束后才进入 final STT 和 LLM，用户感知延迟集中爆发；全双工架构要求持续识别和流式回复。
2. 打断问题：当前打断规划仍围绕播放 chunk 检查或后台监听补丁，缺少全局 cancellation graph；用户插话无法统一取消 LLM、TTS、播放和工具任务。
3. 回声问题：现有音色门控只能降低误触发，无法从音频底座消除扬声器回放；没有 AEC reference，后续 VAD/STT 容易被 AI 自己声音污染。
4. 噪音问题：GTCRN 只覆盖正式问题采集阶段；全双工持续监听需要系统级 NS/AGC，避免背景噪声导致持续 STT 和打断误判。
5. 架构问题：现有 pipeline 仍以“轮次”为主，状态机缺少 `tool_running`、`interrupted`、`recovering` 等 Agent 必需状态。
6. 记忆问题：当前上下文只存在于本次进程内；无法记住长期偏好、项目背景和任务摘要，也没有隐私分类和删除策略。
7. 工具问题：当前 LLM 只能生成自然语言；没有结构化工具协议、工具路由、安全策略、执行预算、防循环机制和工具结果回注。
8. Open Interpreter 边界问题：本地 `openinterpreter/` 是未跟踪外部仓库，不能复制进 Owner；需要把它规划为可选外部 CLI 后端并限制风险。
9. UI/UX 问题：后续桌宠如果直接绑定 runtime 方法，会继续重复逻辑；需要统一事件总线承载状态、字幕、音频、打断、工具和确认请求。
10. 安全问题：长期记忆和工具执行都会扩大数据面与操作面；必须默认最小权限、敏感内容不自动保存、高风险操作确认、日志脱敏。

## 详细需求

### 功能需求

1. 系统 SHALL 新增完整全双工 Agent 语音助手架构规划，保留现有 turn-based 能力作为迁移期兼容路径。
2. 系统 SHALL 规划 `ContinuousAudioRuntime`，负责麦克风持续输入、扬声器播放 reference、音频环形缓冲、状态机事件和任务取消。
3. 系统 SHALL 规划 `WebRtcAudioProcessingStage`，默认 `OWNER_AUDIO_APM_PROVIDER=webrtc`，开启 AEC、NS、AGC。
4. 播放链路 SHALL 把 TTS PCM/render audio 提供给 AEC reference，麦克风 capture 音频经过 APM 后再进入 VAD、STT 和打断检测。
5. 系统 SHALL 规划全双工状态机：`idle`、`listening`、`thinking`、`speaking`、`interrupted`、`tool_running`、`recovering`。
6. 任意状态下检测到有效用户说话 SHALL 能进入 `interrupted`，但 `tool_running` 的中断语义必须区分可取消工具和不可安全取消工具。
7. 系统 SHALL 规划 Silero VAD 或等价本地 VAD 作为打断触发的主要人声检测层；打断检测先判断“有人开始说话”，不依赖已识别出完整文本。
8. 打断目标 SHALL 是在 `OWNER_BARGE_IN_TARGET_LATENCY_MS=200` 内停止播放和取消当前回复。
9. 系统 SHALL 规划 Streaming STT provider；开发默认候选为 `faster-whisper`，产品候选为 `SenseVoice`，保留现有 `sherpa-onnx` 兼容 adapter。
10. Streaming STT SHALL 输出 partial transcript、stable partial transcript 和 final transcript；只有 final transcript 或明确提交的 stable transcript 可进入 LLM。
11. 系统 SHALL 规划 Streaming TTS provider；目标候选为 `CosyVoice`，支持句子级和流式 PCM 输出。
12. LLM SHALL 流式输出 token；Sentence Segmenter SHALL 在检测到完整中文/英文句子或安全停顿时，把文本片段送入 TTS，不等待整段回复完成。
13. TTS 播放 SHALL 支持中途停止；停止后未完整播出的 assistant 文本不得写入短期上下文或长期记忆。
14. 系统 SHALL 规划 `ConversationManager`，负责短期会话历史、长期记忆召回、工具调用闭环和状态推进。
15. 系统 SHALL 规划 `MemoryManager`，默认 `OWNER_MEMORY_PROVIDER=faiss_sqlite`，SQLite 存文本和元数据，FAISS 存向量索引。
16. 记忆类型 SHALL 至少包含 `preference`、`fact`、`project`、`task_summary`。
17. 每轮用户输入进入 LLM 前 SHALL 根据当前用户文本、会话摘要和任务上下文检索 Top-K 长期记忆，并以明确的 memory context 注入 LLM。
18. 敏感内容 SHALL 默认不自动保存；记忆写入必须经过分类器、安全策略或用户明确指令。
19. 系统 SHALL 规划 `ToolRouter` 和结构化工具调用协议，工具请求包含 name、arguments、risk_level、requires_confirmation、timeout_ms、budget、cancellation_policy。
20. 第一版工具 SHALL 以安全工具为主：`memory.search`、`memory.save`、`shell.readonly`、`openinterpreter.run`、`browser.playwright`。
21. `shell.readonly` SHALL 限制为只读命令和允许目录，禁止删除、写文件、修改权限、网络上传、安装依赖等高风险行为。
22. `openinterpreter.run` SHALL 作为外部 CLI/子进程 adapter，默认只允许低风险、受限目录、超时和输出截断任务。
23. `browser.playwright` SHALL 作为浏览器自动化 adapter，默认只允许可审计、非支付、非账号敏感的浏览和提取流程。
24. 第一版 SHALL NOT 实现 GUI 点击/键盘/屏幕控制；只在规范中预留 `ComputerControlProvider`，后续可基于 macOS Accessibility、Playwright、trycua 等公共能力实现。
25. Codex Computer Use 能力 SHALL 仅作为安全确认策略参考，不复制私有实现、捆绑脚本或内部协议。
26. 系统 SHALL 规划工具结果回注：工具输出进入 Tool Result Message，经过脱敏和长度限制后返回 LLM；工具失败进入可恢复错误路径。
27. 系统 SHALL 规划防循环策略：单轮最大工具调用次数、最大总耗时、最大输出字节、重复工具调用检测。
28. 系统 SHALL 规划安全确认策略：写文件、删除、上传、交易、账号、权限、联网提交、安装依赖、执行任意代码等高风险操作必须确认，第一版默认拒绝自动执行。
29. 系统 SHALL 规划桌宠/终端共用事件总线，事件覆盖 audio、vad、stt、llm、tts、playback、memory、tool、confirmation、interruption、recovery。
30. 本阶段 SHALL 只创建 OpenSpec 文档；不得创建或修改 `src/`、`tests/`、`scripts/`、`pyproject.toml`、`.env`、模型文件、音频资产或运行时代码。

### 非功能需求

1. 性能优化：全双工音频处理必须以固定帧长和环形缓冲为基础，避免 Python 线程阻塞导致播放卡顿或输入积压。
2. 延迟目标：VAD frame interval 默认不超过 20 ms；播放停止 chunk 默认不超过 30 ms；整体打断目标小于 200 ms。
3. 稳定性：所有 provider 必须支持超时、取消、关闭和资源释放；异常必须进入 `recovering`，不得让后台线程泄漏。
4. 可扩展性：APM、VAD、STT、TTS、LLM、Memory、Tool adapter 都必须是可替换 provider，不能把具体模型硬编码进状态机。
5. UI/UX：终端和未来 GUI 不直接调用 provider，只消费事件；显示文案、字幕、工具确认和桌宠动画均由事件驱动。
6. 安全：API key、Authorization header、原始音频、声纹特征、工具敏感输出不得写入日志或长期记忆。
7. 隐私：默认不保存原始麦克风音频；长期记忆只保存文本摘要和必要元数据；用户必须能关闭记忆。
8. 兼容性：现有 `.env` 中 LLM 配置继续可用；新增配置必须有默认值和迁移说明。
9. 可测试性：每个并发 stage 必须可用 fake provider 和虚拟时钟测试；端到端模拟不依赖真实麦克风、扬声器或外部工具。
10. 可观测性：事件必须携带 turn/session id、stage、时间戳、latency、error code 和脱敏 payload，便于定位卡顿、误触发和工具风险。

### 边缘案例

1. APM 初始化失败：系统必须报告 `AUDIO_APM_UNAVAILABLE`，可按配置降级到现有 GTCRN/音色门控 fallback 或拒绝进入全双工模式。
2. AEC reference 丢失：播放中没有 reference 音频时，系统必须降低打断置信度或临时禁用高风险 barge-in，避免 AI 自己声音触发。
3. 麦克风权限缺失：启动失败并提示设备检查，不进入假监听状态。
4. 用户在 AI 说第一个字前打断：取消 LLM/TTS stream，未播报文本不写入上下文。
5. 用户在工具执行中打断：可取消工具立即取消；不可安全取消工具进入“正在收尾/等待结果”状态，并向用户播报或显示限制。
6. LLM 已发起工具调用但用户打断：未执行工具调用应取消；已执行且低风险的只读工具结果可丢弃或标记为 stale。
7. 记忆库损坏：FAISS 或 SQLite 不可用时，系统可禁用长期记忆并继续基本语音对话，但必须报告结构化错误。
8. 记忆召回命中敏感内容：默认不注入 LLM，除非用户明确要求并通过安全策略。
9. Open Interpreter 路径缺失：`openinterpreter.run` adapter 标记不可用，不影响其他工具。
10. 工具输出过长：按配置截断并附 `truncated=true` 元数据，不把完整大输出塞进 LLM。
11. Playwright 未安装或浏览器不可用：工具返回可恢复错误，不影响语音主循环。
12. TTS 输出卡顿：播放队列应能反压 TTS 合成；卡顿事件必须可观测，不能阻塞麦克风监听线程。
13. Streaming STT partial 抖动：只显示稳定 partial；final transcript 才进入对话。
14. 网络 LLM 慢或断线：取消和超时必须生效；恢复后回到 listening 或 idle。
15. 多人同时说话：第一版不承诺身份鉴权，只要求 AEC 后的人声触发和用户体验合理；多人区分列为需人工澄清。

### 输入输出规格

新增或规划配置：

1. `OWNER_ASSISTANT_MODE=full_duplex_agent`
2. `OWNER_AUDIO_APM_PROVIDER=webrtc`
3. `OWNER_AUDIO_AEC_ENABLED=1`
4. `OWNER_AUDIO_NS_ENABLED=1`
5. `OWNER_AUDIO_AGC_ENABLED=1`
6. `OWNER_AUDIO_FRAME_MS=20`
7. `OWNER_AUDIO_RING_BUFFER_MS=3000`
8. `OWNER_VAD_PROVIDER=silero`
9. `OWNER_INTERRUPT_ENABLED=1`
10. `OWNER_INTERRUPT_TARGET_LATENCY_MS=200`
11. `OWNER_STREAMING_STT_PROVIDER=faster_whisper`
12. `OWNER_STREAMING_STT_PRODUCT_CANDIDATE=sensevoice`
13. `OWNER_STREAMING_TTS_PROVIDER=cosyvoice`
14. `OWNER_LLM_STREAMING_ENABLED=1`
15. `OWNER_MEMORY_ENABLED=1`
16. `OWNER_MEMORY_PROVIDER=faiss_sqlite`
17. `OWNER_MEMORY_TOP_K=5`
18. `OWNER_MEMORY_AUTO_SAVE_SENSITIVE=0`
19. `OWNER_TOOL_ROUTER_ENABLED=1`
20. `OWNER_TOOL_MAX_CALLS_PER_TURN=5`
21. `OWNER_TOOL_TIMEOUT_MS=30000`
22. `OWNER_OPENINTERPRETER_ENABLED=0`
23. `OWNER_OPENINTERPRETER_COMMAND=openinterpreter`
24. `OWNER_BROWSER_PLAYWRIGHT_ENABLED=0`
25. `OWNER_COMPUTER_CONTROL_ENABLED=0`

核心事件输出：

1. `audio_capture_started`
2. `audio_apm_started`
3. `listening_started`
4. `speech_started`
5. `stt_partial`
6. `stt_final`
7. `llm_stream_started`
8. `llm_sentence_ready`
9. `tts_chunk_ready`
10. `playback_started`
11. `interrupt_detected`
12. `playback_cancelled`
13. `llm_cancelled`
14. `memory_retrieved`
15. `tool_call_requested`
16. `tool_confirmation_required`
17. `tool_call_started`
18. `tool_call_finished`
19. `tool_call_rejected`
20. `session_recovered`

### 数据验证规则

1. Provider 配置必须在启动前校验，不允许未知 provider 静默回退。
2. APM 输出帧采样率、声道数、帧长必须与 VAD/STT 输入一致；不一致必须显式 resample 或报错。
3. Streaming STT partial 不得进入长期记忆；final transcript 必须经过空文本、重复文本、敏感内容和最小置信度检查。
4. TTS 播报文本必须经过现有 TTS sanitizer；emoji、表情包和 Markdown 图片不得进入语音。
5. 长期记忆写入必须包含 type、text、source_turn_id、created_at、sensitivity、embedding_model、checksum。
6. FAISS index 和 SQLite metadata 必须可一致性检查；缺失或 checksum 不匹配时不得返回伪造记忆。
7. Tool Router arguments 必须按工具 schema 校验；未知字段、路径越界、命令注入风险必须拒绝。
8. 工具结果进入 LLM 前必须截断、脱敏，并标注工具名、耗时、退出码和是否截断。
9. 所有 cancellation token 必须可幂等触发，多次取消不得抛出未处理异常。

### 需人工澄清

1. 全双工入口是替换 `run-live`，还是新增 `run-agent-live` 并保留 `run-live` 为稳定 turn-based 入口。
2. WebRTC APM Python 绑定优先选择哪个包或本地封装，是否允许引入需要系统编译的依赖。
3. 产品阶段是否确定采用 SenseVoice 和 CosyVoice，还是只在规范中保留候选。
4. 长期记忆是否需要用户可视化管理、删除、导出和禁用命令。
5. Open Interpreter CLI 的实际本机命令、工作目录、沙箱策略和是否允许写操作需要人工确认。
6. Playwright 浏览器工具是否允许使用用户当前 Chrome 登录态，还是只允许独立 browser context。
7. 多人说话场景是否需要主人声纹注册；本变更默认不做身份鉴权。
8. 桌宠 GUI 和电脑控制是否必须同期开工；本变更建议第一版先做音频全双工、记忆和安全工具。

## 设计方案

### 文字版全新架构图

```text
Microphone
  -> Capture Ring Buffer
  -> WebRtcAudioProcessingStage(AEC + NS + AGC, render reference from Speaker)
  -> SileroVadStage
      -> InterruptDetector
      -> StreamingSttStage(faster-whisper dev / SenseVoice candidate / sherpa fallback)
  -> ConversationManager
      -> ShortTermSessionContext
      -> MemoryManager(SQLite metadata + FAISS vectors)
      -> LlmStage(streaming OpenAI-compatible provider)
      -> ToolRouter(memory.search/save, shell.readonly, openinterpreter.run, browser.playwright)
  -> ResponseStream
  -> SentenceSegmenter
  -> StreamingTtsStage(CosyVoice candidate / local fallback)
  -> Playback Ring Buffer
  -> Speaker
  -> Render Reference back to WebRtcAudioProcessingStage
```

### 数据流

1. `ContinuousAudioRuntime` 启动后初始化 capture device、playback device、APM、VAD、STT、TTS、LLM、Memory、ToolRouter。
2. 麦克风音频以固定 20 ms 帧写入 capture ring buffer；播放 PCM 以相同时间轴写入 render reference buffer。
3. `WebRtcAudioProcessingStage` 使用 render reference 对 capture frame 执行 AEC，再执行 NS/AGC。
4. APM 后音频同时进入 VAD、Streaming STT 和 Interrupt Detector。
5. `listening` 状态下，VAD/STT 产生用户输入；final transcript 进入 Conversation Manager。
6. Conversation Manager 召回短期上下文和长期记忆，生成 LLM streaming request。
7. LLM delta 进入 Sentence Segmenter；完整句子进入 Streaming TTS；TTS chunk 立即入 playback queue。
8. 播放开始后，播放 PCM 仍持续进入 render reference，使 AEC 能抑制助手回声。
9. 如果用户讲话，Interrupt Detector 发出 `interrupt_detected`，Cancellation Graph 同时取消 LLM stream、未完成 TTS、播放队列和可取消工具。
10. Tool Router 在 LLM 请求工具时执行 schema 校验、安全分类、确认策略、执行、结果脱敏和回注。
11. 任何 stage 失败进入 `recovering`，释放后台任务和音频资源后回到 `listening` 或 `idle`。

### 接口定义

```text
AudioFrame:
  samples: float32 PCM
  sample_rate: int
  channels: int
  timestamp_monotonic_ms: int
  frame_id: str
```

```text
WebRtcAudioProcessingStage.process_capture(frame: AudioFrame) -> AudioFrame
WebRtcAudioProcessingStage.process_render(frame: AudioFrame) -> None
WebRtcAudioProcessingStage.reset_stream() -> None
Errors:
  AUDIO_APM_UNAVAILABLE
  AUDIO_APM_FORMAT_MISMATCH
  AUDIO_APM_PROCESS_FAILED
```

```text
StreamingSttProvider.start_session(session_id: str) -> StreamingSttSession
StreamingSttSession.accept_audio(frame: AudioFrame) -> list[TranscriptEvent]
StreamingSttSession.finish() -> TranscriptFinal
StreamingSttSession.cancel(reason: str) -> None
```

```text
StreamingTtsProvider.start_stream(voice: str, sample_rate: int) -> StreamingTtsSession
StreamingTtsSession.accept_text(text: str) -> list[AudioFrame]
StreamingTtsSession.flush() -> list[AudioFrame]
StreamingTtsSession.cancel(reason: str) -> None
```

```text
MemoryManager.search(query: str, *, top_k: int, filters: dict) -> list[MemoryRecord]
MemoryManager.save(record: MemoryRecordInput) -> MemoryRecord
MemoryManager.delete(memory_id: str) -> None
MemoryManager.health_check() -> MemoryHealth
```

```text
ToolRouter.route(call: ToolCallRequest, context: ToolContext) -> ToolDecision
ToolRouter.execute(decision: ToolDecision, cancellation: CancellationToken) -> ToolResult
ToolDecision:
  action: execute | reject | require_confirmation
  risk_level: low | medium | high | forbidden
  reason: str
```

### 状态机

```text
idle
  -> listening
listening
  -> thinking        on final user transcript
  -> interrupted     on explicit cancel or new speech over assistant residue
  -> recovering      on audio/STT failure
thinking
  -> speaking        on first playable TTS chunk
  -> tool_running    on approved tool call
  -> interrupted     on user speech
  -> recovering      on LLM failure
speaking
  -> listening       on reply finished and no follow-up/tool pending
  -> interrupted     on valid user speech
  -> recovering      on TTS/playback failure
tool_running
  -> thinking        on tool result returned to LLM
  -> interrupted     on cancellable tool interrupted
  -> recovering      on tool failure
interrupted
  -> listening       after current tasks cancelled and buffered user audio retained
recovering
  -> listening       after cleanup when runtime can continue
  -> idle            when required provider unavailable
```

### 关键算法

1. AEC reference 对齐：播放 PCM 写入 render buffer 时记录 monotonic timestamp；capture frame 处理前取最近 reference window，丢帧或漂移超过阈值时发 `audio_reference_drift`。
2. 打断检测：APM 后音频先经 VAD 判断人声起点；连续人声超过最小阈值后结合 STT stable partial 或能量/频谱置信度触发 interrupt；纯 render echo 在 AEC 后应低于阈值。
3. 句子切分：LLM delta 累积到中文句号、问号、感叹号、英文终止标点或最大等待阈值时切句；代码块、URL、数字小数点不得误切。
4. 取消传播：每轮创建 root cancellation token；LLM、TTS、playback、tool 子任务注册 child token；用户打断时 root token 广播，所有 stage 幂等收尾。
5. 长期记忆召回：用户 final transcript 生成 embedding，FAISS 取 Top-N，SQLite 取 metadata，按类型、敏感度、最近使用、相似度重排后注入 LLM。
6. 记忆写入：Conversation Manager 在回合结束后提取候选记忆，按敏感分类和用户意图决定是否保存；敏感或不确定默认不保存。
7. 工具路由：LLM tool call 先过 schema，再做风险分类和权限判断；低风险可执行，高风险进入确认，禁止类直接拒绝。

### 数据库/状态管理变更

1. SQLite 表 `memories`：`id`、`type`、`text`、`summary`、`metadata_json`、`sensitivity`、`source_turn_id`、`created_at`、`updated_at`、`last_used_at`、`embedding_id`、`checksum`。
2. SQLite 表 `tool_audit_logs`：记录工具名、风险、确认状态、耗时、退出码、截断标记和脱敏摘要，不保存密钥。
3. FAISS index 文件保存 embedding vectors；SQLite 保存 index 版本和 embedding model，启动时做一致性检查。
4. 短期会话上下文仍在内存中，进程退出丢弃；长期记忆独立存储，可按配置禁用。

### UI 组件重构方案

1. 终端 reporter 只订阅事件，不直接读取 pipeline 内部状态。
2. 未来桌宠 GUI 使用同一事件流展示 `listening`、`thinking`、`speaking`、`interrupted`、`tool_running`、`recovering`。
3. 工具确认必须作为事件暴露，终端可先实现文本确认，GUI 后续实现按钮确认。
4. 实时字幕分为 partial、stable partial、final 三种显示层级，避免把抖动 partial 当作最终用户输入。

### 依赖影响分析

1. WebRTC APM：新增依赖风险最高，需确认 Python/macOS 可用绑定或自建 native wrapper。
2. Silero VAD：新增本地模型依赖，需评估 ONNX Runtime 或 torch 路线。
3. Faster Whisper：开发体验好，但模型体积和 Metal/CPU 性能需评估。
4. SenseVoice：中文效果强，产品候选；需确认 license、模型大小、macOS 部署成本。
5. CosyVoice：TTS 效果强，依赖较重；第一阶段可先保留现有本地 TTS fallback。
6. FAISS：macOS 安装和 wheel 兼容性需评估；必要时提供 sqlite-only 或 numpy fallback。
7. Playwright：浏览器自动化依赖和浏览器安装体积需评估；第一版默认关闭。
8. Open Interpreter：作为外部 CLI 后端，不作为 Owner 包内依赖；路径缺失时 adapter 不可用。

## 风险与权衡

| 风险 | 概率 | 影响 | 缓解措施 |
| --- | --- | --- | --- |
| WebRTC APM Python/macOS 绑定不可用或编译复杂 | 高 | 高 | OpenSpec 中把 provider 抽象出来；先验证 fake APM 和最小 native 方案；保留 GTCRN/音色门控 fallback。 |
| AEC reference 与 capture 时钟不同步 | 中 | 高 | 使用 monotonic timestamp、ring buffer drift 监控、reference gap 事件和回声测试 fixture。 |
| 全双工并发导致线程泄漏或播放卡顿 | 中 | 高 | 所有 stage 必须支持 cancellation token、bounded queue、backpressure 和统一 shutdown。 |
| Streaming TTS 依赖过重导致落地慢 | 中 | 中 | 第一阶段先按句分段合成，CosyVoice 作为目标 provider，保留现有 Mac TTS fallback。 |
| Faster Whisper/SenseVoice 模型性能不足 | 中 | 中 | 规范要求 provider 可替换，测试记录 partial/final latency，产品候选不在第一阶段强绑定。 |
| 长期记忆保存敏感信息 | 中 | 高 | 默认敏感不自动保存；记忆写入前分类；用户可关闭；日志和记忆脱敏。 |
| Tool Router 执行危险操作 | 中 | 高 | 默认安全工具优先，高风险确认，禁止类拒绝，目录限制，超时，输出截断，审计日志。 |
| Open Interpreter 外部后端越权 | 中 | 高 | 默认关闭；只允许受限目录、低风险任务；写操作必须确认或拒绝；不复制外部仓库进 Owner。 |
| Playwright 使用登录态带来账号风险 | 中 | 高 | 第一版默认独立 context；涉及账号、支付、购买、提交必须确认或拒绝。 |
| 用户期望立即实现完整 GUI 控制 | 中 | 中 | 本变更明确第一版不做 GUI 点击/键盘/屏幕控制，只预留公共 provider。 |
| FAISS 与 SQLite 一致性损坏 | 低 | 中 | 启动 health check、checksum、index rebuild 任务和 sqlite-only 降级。 |
| LLM 工具循环 | 中 | 中 | 单轮最大工具次数、重复调用检测、总耗时预算和可恢复拒绝。 |
| 不确定是否继续对话造成体验不稳 | 中 | 中 | Conversation Manager 规则优先，LLM 分类兜底，不确定默认 listening/idle 策略需人工确认。 |
| OpenSpec scope 过大导致实现周期过长 | 高 | 中 | 实施计划分阶段：先音频全双工，再流式 STT/TTS，再记忆和工具，再电脑控制。 |

## 任务分解

> 本节定义 proposal 里的主要功能组或里程碑阶段。后续 `tasks.md` 必须把每组拆成不超过 1 小时的原子任务，并在完成每个大模块后按 Git 提交规范立即提交。

### 1. OpenSpec 与边界冻结

目标：只产出 `add-full-duplex-agent-voice-assistant` 文档，不改代码、不装依赖、不下载模型、不提交 `openinterpreter/`。

验收：OpenSpec 变更目录包含 proposal、design、tasks、spec delta；严格校验通过。

### 2. WebRTC APM 与全双工音频底座规划

目标：定义 capture/render ring buffer、AEC reference、NS、AGC、音频格式、时钟对齐和 fallback 策略。

验收：spec 包含 APM SHALL 要求、fake reference 测试场景和回声不触发 VAD/STT 场景。

### 3. 全双工状态机、事件总线与取消机制规划

目标：定义 `idle/listening/thinking/speaking/interrupted/tool_running/recovering` 状态机、事件模型、cancellation graph 和 recovery。

验收：design 包含状态转移表和取消传播；tasks 包含状态机、事件顺序和错误恢复测试。

### 4. Streaming STT 与低延迟打断规划

目标：定义 Streaming STT provider、Silero VAD、partial/final transcript、打断检测和 200 ms 目标。

验收：spec 包含 partial/final 行为、speaking 中用户说话进入 interrupted、纯回声不打断。

### 5. Streaming TTS 与响应流规划

目标：定义 LLM token stream、句子切分、Streaming TTS、播放队列、可中断播放和上下文写入边界。

验收：spec 包含不等待完整回复、未播完文本不写上下文、TTS 卡顿可观测。

### 6. 长期记忆规划

目标：定义 MemoryManager、FAISS+SQLite、记忆类型、召回、写入安全、禁用和删除策略。

验收：spec 包含保存、检索、重启召回、关闭记忆不读写、敏感内容不自动保存。

### 7. Tool Router 与安全工具规划

目标：定义结构化工具协议、安全路由、工具预算、防循环、工具结果回注，以及 `memory.search/save`、`shell.readonly`、`openinterpreter.run`、`browser.playwright`。

验收：spec 包含合法工具执行、非法工具拒绝、确认策略、Open Interpreter 缺失处理和 Playwright 安全边界。

### 8. Open Interpreter 与电脑控制边界规划

目标：明确 `openinterpreter/` 是外部未跟踪后端候选，不复制进 Owner；第一版不做 GUI 控制，只预留 `ComputerControlProvider`。

验收：proposal/design/tasks 均写明边界；git 提交不包含 `openinterpreter/`。

### 9. 测试、性能、安全和验收规划

目标：定义 fake APM、VAD、STT、TTS、memory、tool、Open Interpreter、Playwright、端到端模拟、性能指标和安全验证。

验收：tasks 中每项有前置条件、优先级、验收标准和测试要点；validation 命令明确。

## Spec Deltas

### Capabilities

#### New Capabilities

本变更不创建独立新 capability 文件。原因：用户明确要求 delta 文件路径为 `specs/voice-pet-pipeline/spec.md`，且全双工音频、长期记忆和 Tool Router 都作为语音助手 pipeline 的能力升级纳入同一现有 capability。

#### Modified Capabilities

- `voice-pet-pipeline`：从 turn-based Python 桌宠语音 pipeline 扩展为完整全双工 Agent 语音助手 pipeline，新增 WebRTC APM、持续监听、Streaming STT/TTS、低延迟打断、长期记忆、Tool Router、Open Interpreter 外部后端适配和安全工具执行要求。

### 与现有 `openspec/specs/voice-pet-pipeline/spec.md` 的精确差异

1. 修改 `Local microphone and speaker transport`：从本机麦克风/扬声器 transport 扩展为 capture/render reference 双向音频流，播放音频必须提供给 AEC。
2. 修改 `VAD speech endpoint detection`：从 turn-based 端点检测扩展为持续 VAD、打断检测和全双工 listening。
3. 修改 `Local STT transcription`：从 captured segment final STT 扩展为 Streaming STT partial/stable/final。
4. 修改 `Cloud LLM streaming reply`：从流式 LLM 输出扩展为 token-to-sentence-to-TTS response stream，并要求可取消。
5. 修改 `Local TTS synthesis and playback`：从整段或分句播放扩展为 Streaming TTS、PCM chunk 播放和中途停止。
6. 修改 `Pipeline state machine`：新增 `listening`、`tool_running`、`recovering` 等全双工 Agent 状态，明确 `speaking -> interrupted`。
7. 修改 `Audio feedback suppression`：从播放期间抑制输入扩展为 AEC + VAD + interrupt，允许用户有效打断。
8. 修改 `Conversation context management`：保留进程内上下文，同时新增长期记忆召回的边界。
9. 修改 `Security and privacy`：新增长期记忆、工具执行、Open Interpreter 和浏览器自动化安全要求。
10. 修改 `Performance targets`：新增打断延迟、Streaming STT 首字、TTS 首 chunk、APM 帧处理等指标。
11. 新增 requirement：`WebRTC audio processing foundation`。
12. 新增 requirement：`Full-duplex agent state machine`。
13. 新增 requirement：`Streaming STT and realtime transcript`。
14. 新增 requirement：`Low-latency interruption and cancellation`。
15. 新增 requirement：`Streaming response and TTS playback`。
16. 新增 requirement：`Long-term memory with FAISS and SQLite`。
17. 新增 requirement：`Tool Router and structured tool execution`。
18. 新增 requirement：`Open Interpreter external adapter`。
19. 新增 requirement：`Browser automation tool boundary`。
20. 新增 requirement：`Computer control reservation`。

### 推翻重做的理由

1. turn-based VAD/STT/TTS 无法自然支持“AI 讲话时用户插话”，只能不断添加补丁。
2. 音色门控不能替代 AEC；没有 render reference 的系统无法稳定区分助手回放和真实用户。
3. 只靠 final STT 会让用户等待过久；完整助手需要持续识别和实时字幕。
4. 没有 Tool Router 和 MemoryManager 的语音助手只能聊天，不能完成 Agent 任务。
5. 工具和记忆如果后补，会难以补齐安全边界；必须在 OpenSpec 阶段先定义。

## 实施计划

### 分阶段优先级顺序

1. 阶段 A：OpenSpec 文档和边界冻结。
2. 阶段 B：全双工音频底座和 fake APM 测试。
3. 阶段 C：状态机、事件总线、取消机制和模拟端到端。
4. 阶段 D：Streaming STT、VAD 打断和回声抑制测试。
5. 阶段 E：Streaming LLM/TTS、句子切分和可中断播放。
6. 阶段 F：长期记忆 FAISS+SQLite、记忆召回和隐私策略。
7. 阶段 G：Tool Router、安全工具、Open Interpreter adapter 和 Playwright adapter。
8. 阶段 H：文档、性能验收、安全审计和迁移收尾。

### 里程碑估时

| 里程碑 | 乐观 | 最可能 | 悲观 |
| --- | ---: | ---: | ---: |
| A OpenSpec 文档 | 0.5 天 | 1 天 | 1.5 天 |
| B 音频底座 | 2 天 | 4 天 | 8 天 |
| C 状态机与取消 | 2 天 | 3 天 | 6 天 |
| D Streaming STT 与打断 | 3 天 | 5 天 | 10 天 |
| E Streaming TTS | 3 天 | 5 天 | 10 天 |
| F 长期记忆 | 2 天 | 4 天 | 8 天 |
| G Tool Router | 3 天 | 6 天 | 12 天 |
| H 验收与收尾 | 2 天 | 4 天 | 8 天 |

总耗时预估：乐观 17.5 天，最可能 32 天，悲观 63.5 天。

### 数据/状态迁移策略

1. 现有进程内上下文不迁移为长期记忆，避免未经确认的历史被自动保存。
2. 新长期记忆库首次启动为空；用户明确要求保存或分类器确认低敏偏好后才写入。
3. 现有 `.env` 继续可用，新增变量采用默认值；全双工模式可通过 feature flag 启用。
4. 现有 turn-based `run-live` 在迁移期保留，直到全双工验收稳定后再决定是否替换默认入口。
5. `openinterpreter/` 外部仓库不纳入 Owner 迁移；只记录 adapter 配置和安全策略。

## Git 提交规范

1. 每完成一个大模块，必须立即执行构建或相应验证，然后执行 git commit。
2. 大模块定义为 proposal “任务分解”中的主要功能组或实施计划中的里程碑阶段。
3. 提交信息必须使用中文，格式为：`[模块名]：完成[具体功能描述]，包含[关键变更]`。
4. 提交前必须保证本模块验证通过，避免任何未提交的中间状态。
5. 本 OpenSpec-only 阶段完成后提交信息固定为：`[全双工Agent架构]：完成完整语音助手OpenSpec计划，包含WebRTC音频底座、长期记忆和Tool Router设计`。
6. 本次提交只允许包含 `openspec/changes/add-full-duplex-agent-voice-assistant/` 下的规划文档，不得提交 `openinterpreter/`、模型文件、依赖锁文件、`.env` 或运行代码。