# Design: 完整全双工 Agent 语音助手架构

## Context

当前 Owner 项目已经具备真实语音桌宠的基础能力：本地唤醒词、麦克风采集、VAD/端点、实时字幕、final STT、云端 LLM、本地 TTS、播报、连续追问和初步打断规划。现有实现仍以 turn-based 轮次为中心：用户唤醒后系统录一段、识别、生成、播放，再回到待机或短暂追问窗口。

完整 Agent 语音助手需要更强的架构边界：

1. 音频输入和输出必须同时运行，而不是录完再播。
2. 播放音频必须回注给 AEC reference，避免助手自己的声音污染麦克风输入。
3. VAD、STT、LLM、TTS、工具执行和播放都必须能被统一取消。
4. 长期记忆和工具执行必须纳入安全策略，而不是让 LLM 随意执行文本命令。
5. 终端、未来 GUI 桌宠和自动测试必须消费同一事件流。

本设计仅用于 OpenSpec 规划。本阶段不修改 `src/`、不安装依赖、不下载模型、不运行外部工具、不接入 Open Interpreter，也不提交本地未跟踪的 `openinterpreter/`。

## Goals / Non-Goals

**Goals:**

1. 定义全双工音频底座：麦克风 capture、扬声器 render reference、WebRTC APM AEC/NS/AGC、环形缓冲和时钟对齐。
2. 定义状态机：`idle/listening/thinking/speaking/interrupted/tool_running/recovering`。
3. 定义并发任务模型：音频输入、STT、LLM、TTS、播放、工具执行相互独立但可被统一取消。
4. 定义低延迟打断：用户在 `speaking` 中说话时，VAD 快速触发 interruption，目标小于 200 ms。
5. 定义 Streaming STT/TTS：partial/final transcript、LLM token stream、句子切分、TTS chunk 播放。
6. 定义长期记忆：SQLite 保存文本和元数据，FAISS 保存向量索引，敏感内容默认不自动保存。
7. 定义 Tool Router：结构化工具调用协议、安全分类、确认策略、执行预算、防循环、结果脱敏回注。
8. 定义 Open Interpreter 外部 adapter：只作为 CLI/子进程后端候选，不复制外部仓库。
9. 定义 Playwright browser adapter 和未来 `ComputerControlProvider` 预留边界。
10. 定义测试策略：fake APM/VAD/STT/TTS/memory/tool、端到端模拟、性能指标和安全回归。

**Non-Goals:**

1. 本阶段不实现运行代码。
2. 本阶段不安装 WebRTC APM、Silero、Faster Whisper、SenseVoice、CosyVoice、FAISS、Playwright 或 Open Interpreter。
3. 本阶段不下载模型。
4. 本阶段不改变 `.env`、`pyproject.toml`、`src/`、`tests/`、`scripts/`。
5. 第一版规划不做 GUI 点击、键盘、屏幕控制，只预留公共 provider。
6. 第一版不做长期主人声纹注册和多人身份鉴权。
7. 第一版不自动执行高风险电脑控制、上传、交易、删除、权限修改或账号操作。

## Decisions

### Decision 1: WebRTC APM 作为默认音频底座

采用 `WebRtcAudioProcessingStage` 作为全双工默认音频预处理层，启用 AEC、NS、AGC。

**理由：**

1. AEC 需要播放 reference 才能可靠消除助手自己的声音，音色门控只能做后验抑制。
2. NS 能降低风扇、环境声和麦克风底噪对持续 VAD/STT 的影响。
3. AGC 能减少用户远近变化导致的阈值不稳定。

**替代方案：**

1. 继续使用 GTCRN 降噪：能改善噪音，但不能处理扬声器回声。
2. 继续使用音色门控：实现成本低，但对不同扬声器、房间回声和 TTS 音色变化不稳定。
3. 只靠 VAD/STT 置信度：误触发风险高，不适合作为全双工底座。

### Decision 2: capture/render 双环形缓冲

设计 `CaptureRingBuffer` 和 `RenderReferenceRingBuffer`。麦克风帧和播放帧都按 monotonic timestamp 写入，APM 处理 capture frame 时读取相邻 render reference。

**理由：**

1. 全双工需要持续输入和持续输出，不能用同步读写阻塞。
2. AEC 对 reference 时序敏感，必须保留时间戳和 drift 监控。
3. Ring buffer 可为 STT、VAD、打断检测和测试提供一致帧来源。

**替代方案：**

1. 直接从 sounddevice callback 推到各 stage：耦合高，难测试，易阻塞。
2. 文件式临时 wav：延迟高，不适合全双工。

### Decision 3: 统一状态机和事件总线

新增 `FullDuplexAgentStateMachine` 和 `PipelineEventBus`。状态机只负责合法转移，事件总线承载终端、GUI 和测试可观察行为。

**理由：**

1. 现有 turn-based 状态无法表达 `tool_running` 和 `interrupted`。
2. 终端和未来 GUI 必须共享事件，不应各自读取内部字段。
3. 测试可以断言事件顺序、耗时和错误恢复。

### Decision 4: Cancellation Graph 管理所有可中断任务

每个用户输入 turn 创建 root cancellation token，LLM、TTS、playback、tool 子任务挂在 root 下。用户打断时 root token 广播取消。

**理由：**

1. 播放停止但 LLM 继续生成会浪费资源并污染上下文。
2. TTS 合成继续运行会造成卡顿和旧回复残留。
3. 工具执行必须区分可取消和不可安全取消。

### Decision 5: Streaming STT 分层输出

`StreamingSttProvider` 输出 `partial`、`stable_partial` 和 `final`。终端可展示 stable partial；LLM 默认只接收 final。

**理由：**

1. 用户需要实时看到系统听到了什么。
2. partial 抖动不能直接写入上下文。
3. final 是唯一可靠的 LLM 用户输入。

**开发候选：**

1. `faster-whisper`：开发阶段优先，生态成熟。
2. `SenseVoice`：产品候选，中文和情绪能力更强，需要评估部署成本。
3. `sherpa-onnx`：保留当前兼容 adapter，降低迁移风险。

### Decision 6: LLM token stream 按句进入 Streaming TTS

LLM delta 进入 `SentenceSegmenter`。达到完整句子、语义停顿或最大等待阈值后，将净化后的文本交给 TTS。

**理由：**

1. 不等待完整回复能显著缩短首音延迟。
2. 句子级 TTS 比 token 级 TTS 更自然。
3. 现有 TTS sanitizer 可复用，避免表情包、emoji 被读出。

### Decision 7: 长期记忆使用 FAISS + SQLite

SQLite 保存记忆文本、类型、敏感度、来源、时间和 checksum；FAISS 保存 embedding 向量。

**理由：**

1. SQLite 适合可审计元数据和删除。
2. FAISS 适合向量相似检索。
3. 两者分离便于一致性检查和索引重建。

**替代方案：**

1. 只用 SQLite FTS：部署简单，但语义召回弱。
2. 直接把历史对话全文塞进 prompt：隐私和成本都不可控。
3. 使用外部向量数据库：当前单机桌宠不需要额外服务复杂度。

### Decision 8: Tool Router 先安全工具后电脑控制

第一版只规划低风险工具：`memory.search`、`memory.save`、`shell.readonly`、`openinterpreter.run`、`browser.playwright`。GUI 电脑控制只预留。

**理由：**

1. 语音助手执行工具的风险高于文本聊天，必须先定义确认策略。
2. Open Interpreter 能节省电脑任务开发时间，但必须被当成外部受限后端。
3. GUI 点击/键盘/屏幕控制需要 Accessibility 权限和更复杂安全策略，不适合第一阶段自动执行。

### Decision 9: Open Interpreter 作为外部 CLI adapter

本地 `openinterpreter/` 是未跟踪新 Rust 版 Open Interpreter。Owner 不复制、不 vendoring、不提交它，只在后续实现中通过命令路径调用外部 CLI。

**理由：**

1. 避免把外部大型仓库混入 Owner。
2. 保持 Owner 的工具边界清晰。
3. 可以对 CLI 调用做超时、目录限制、输出截断和确认策略。

### Decision 10: Codex Computer Use 只参考安全策略

Codex App 的 Computer Use 能力可作为“需要确认、限制高风险操作、避免私自执行 GUI 动作”的安全策略参考，但不复制私有实现。

**理由：**

1. 用户希望从 Codex 控制电脑技能中复刻思路，而不是复制私有实现。
2. 公共落地路线应基于 macOS Accessibility、Playwright、trycua 等能力。
3. 第一版先不做 GUI 控制可降低安全和实现风险。

## Concurrent Task Model

### Runtime task groups

1. `audio_capture_task`：从麦克风读取帧，写入 capture ring buffer。
2. `audio_render_task`：从 playback queue 取 PCM，送扬声器并写入 render reference buffer。
3. `apm_task`：处理 capture frames，输出 cleaned frames。
4. `vad_interrupt_task`：对 cleaned frames 做 VAD 和打断检测。
5. `stt_task`：消费 cleaned frames，输出 partial/stable/final transcript。
6. `llm_task`：消费 final transcript、记忆和工具结果，输出 token stream 或 tool call。
7. `tts_task`：消费句子片段，输出 PCM chunks。
8. `tool_task`：执行已批准工具，输出脱敏结果。
9. `event_task`：聚合事件、指标和 reporter 输出。

### Backpressure

1. Ring buffer 有固定容量，超出容量丢弃最旧非关键帧并发出 `audio_buffer_overrun`。
2. TTS queue 超限时暂停 LLM sentence enqueue 或请求 LLM stream 暂停/取消。
3. Tool output 超限时截断并返回 `truncated=true`。

### Cancellation

1. `interrupt_detected` 触发 root cancellation。
2. LLM stream 立即关闭连接或停止读取。
3. TTS session 停止合成并释放资源。
4. Playback queue 清空未播放 chunks，保留已播放文本边界。
5. 可取消工具收到 token 后停止；不可取消工具标记为 pending cleanup。

## Audio Ring Buffer Design

### Frame format

1. 默认 16 kHz 或 48 kHz 内部采样率需在实现前确认。
2. 默认 mono capture；render reference 可 mono 或 stereo downmix。
3. 默认 frame size 为 20 ms。
4. 每帧包含 `frame_id`、`timestamp_monotonic_ms`、`sample_rate`、`channels`、`samples`。

### Reference alignment

1. render frame 写入 reference buffer 时记录实际播放排队时间和预计播放时间。
2. capture frame 进入 APM 时按 timestamp 查找 reference window。
3. drift 超过阈值时发 `audio_reference_drift`，并降低打断置信度。

### Fallback

1. APM 不可用时，若 `OWNER_AUDIO_APM_REQUIRED=1`，全双工模式启动失败。
2. 若允许 fallback，则使用现有 GTCRN denoiser、assistant playback gate 和 conservative VAD，但必须标记 `apm_fallback=true`。

## Tool Router Protocol

### Tool call request

```text
ToolCallRequest:
  id: str
  name: str
  arguments: dict
  requested_by_turn_id: str
  natural_language_intent: str
  timeout_ms: int
```

### Tool decision

```text
ToolDecision:
  action: execute | reject | require_confirmation
  risk_level: low | medium | high | forbidden
  reason: str
  sanitized_arguments: dict
  confirmation_prompt: str | null
```

### Tool result

```text
ToolResult:
  id: str
  status: success | failed | cancelled | rejected | confirmation_required
  output_text: str
  output_truncated: bool
  error_code: str | null
  duration_ms: int
  audit_summary: str
```

### First-version tools

1. `memory.search`：只读，低风险。
2. `memory.save`：低到中风险，敏感内容需要确认。
3. `shell.readonly`：低到中风险，只允许 allowlist 只读命令。
4. `openinterpreter.run`：默认中风险，第一版默认关闭；执行前必须经过目录、意图和风险校验。
5. `browser.playwright`：默认中风险，第一版默认关闭；账号、支付、提交、购买流程必须确认或拒绝。

## Memory Retrieval Chain

1. 用户 final transcript 进入 `MemoryQueryBuilder`。
2. Query builder 结合当前任务、会话摘要和用户文本生成检索 query。
3. Embedding provider 生成 query vector。
4. FAISS 返回候选 ids。
5. SQLite 读取 metadata，过滤 disabled、sensitive、expired、low-confidence records。
6. Re-ranker 按相似度、类型、最近使用、用户显式偏好排序。
7. Top-K 以独立 `memory_context` 注入 LLM。
8. LLM 回复完成后，`MemoryWriteCandidateExtractor` 生成候选记忆。
9. Safety classifier 决定保存、丢弃或请求确认。

## Migration Plan

1. 保留现有 turn-based `run-live` 作为稳定路径。
2. `run-agent-live` 是真实全双工 Agent 入口；`--check-config` 只做配置检查，不带该参数时必须启动运行时。
3. 先落地 fake provider 和模拟端到端，再接真实 WebRTC APM。
4. STT/TTS provider 先用兼容 adapter 接现有能力，再替换为 streaming provider。
5. 长期记忆默认关闭或空库启动，完成删除/禁用/隐私文档后再默认开启。
6. Tool Router 默认只启用 `memory.search`；其他工具按风险逐步开放。
7. Open Interpreter 和 Playwright adapter 默认关闭，用户显式配置后才可用。
8. GUI 电脑控制另开 OpenSpec 变更，不混入第一版全双工音频和安全工具验收。

## Live Runtime Revision

第一版真实 `run-agent-live` 采用软件 render-reference gate，不新增 WebRTC APM 重依赖。播放队列把已播放 PCM chunk 写入进程内 render reference；后台麦克风监听持续读取 capture frames，先用 VAD 判断有效人声，再与近期 render reference 做相似度/能量门控。候选音频不像助手回放且持续达到最短人声时长时，立即设置 playback stop event；STT 只用于打断后的用户文本识别，不再作为停止播放的前置条件。

`run-live` 保持旧 wake/turn-based 入口。`run-agent-live` 跳过唤醒词和 ACK，常驻 `listening -> thinking -> speaking -> interrupted/listening`，打断后把已确认的用户音频接到下一轮 capture，避免丢首字。长期记忆、Tool Router、Open Interpreter 仍默认关闭。

## Rollback Strategy

1. 若全双工音频不稳定，可通过配置回退 turn-based `run-live`。
2. 若 APM provider 失败，可禁用 full-duplex mode 或启用 fallback 标记的旧链路。
3. 若长期记忆异常，可设置 `OWNER_MEMORY_ENABLED=0`，继续短期对话。
4. 若 Tool Router 风险过高，可设置 `OWNER_TOOL_ROUTER_ENABLED=0`，保留纯聊天。
5. 若 Open Interpreter 或 Playwright adapter 出错，只禁用对应工具，不影响语音主循环。

## Risks / Trade-offs

1. WebRTC APM 依赖复杂 -> 通过 provider 抽象、fake APM 测试和 fallback 降低风险。
2. 全双工并发复杂 -> 通过 bounded queue、cancellation graph、虚拟时钟测试和事件指标控制。
3. 流式 STT/TTS 模型较重 -> 分阶段实现，先 provider interface 和 fake tests，再接真实模型。
4. 长期记忆有隐私风险 -> 默认敏感不保存、可禁用、可删除、可审计。
5. 工具执行有安全风险 -> 安全工具优先，高风险确认或拒绝，输出脱敏和审计日志。
6. Open Interpreter 能力强但风险大 -> 默认关闭、低风险受限执行、外部 CLI adapter、禁止复制仓库。
7. Playwright 登录态风险 -> 第一版不默认使用用户登录态，敏感流程确认或拒绝。
8. 第一阶段 scope 大 -> 按音频、状态机、STT/TTS、记忆、工具拆分里程碑，每个里程碑独立提交。

## Open Questions

1. 全双工入口是否命名为 `run-agent-live`，还是通过 `run-live --mode full-duplex` 启用。
2. WebRTC APM 的具体 Python/macOS 绑定选择需要验证。
3. 内部采样率统一用 16 kHz 还是 48 kHz，需要结合 APM、STT、TTS provider 决定。
4. SenseVoice 和 CosyVoice 是否作为产品强依赖，还是只保留候选。
5. 长期记忆是否默认开启，需要用户确认隐私预期。
6. Open Interpreter 是否允许写操作；若允许，确认流程和 sandbox 需要单独设计。
7. Playwright 是否允许使用现有 Chrome 登录态。
8. 后续 ComputerControlProvider 是否采用 macOS Accessibility、trycua 或其他公共方案。