docs/voice/overview.md

语音系统

概述

Codev 的语音系统支持语音转文字（STT, Speech-to-Text） 和 文字转语音（TTS, Text-to-Speech） 功能。语音录制使用底层音频捕获库（cpal），含有 SoX 和 arecord 回退方案。语音识别支持多个提供商，包括云端 API 和本地模型；语音合成同样支持多个引擎，涵盖 Edge TTS 和 DashScope TTS。

注意：部分功能受构建特性门控（feature gate）限制，仅在 ant-internal 构建中可用。

---

语音录制（Voice Recording）

核心文件：src/services/voice.ts

录音模块使用分层策略：

层级	方案	适用平台
原生	audio-capture-napi（cpal）	macOS, Linux, Windows
回退 1	SoX rec	Linux (有 SoX)
回退 2	arecord (ALSA)	Linux (有 ALSA)

关键特征：

• 懒加载原生模块：loadAudioNapi() 在首次按键时异步加载 audio-capture-napi，避免启动时阻塞（dlopen 可能耗时 1-8 秒）。
• 静音检测：使用 SoX 或 arecord 时启用静音检测（阈值 3%，持续时间 2 秒），自动结束录音。
• 录音常量：采样率 16000 Hz，单声道，16-bit PCM。
• 依赖检查：checkVoiceDependencies() 探测可用性，显示每个方案的可用状态。

---

STT 提供商（Speech-to-Text）

抽象接口

文件：src/services/voice/providers.ts

interface TranscriptionProvider {
  name: string
  transcribe(wavPath: string, language?: string): Promise<TranscriptionResult>
}

所有 STT 提供商实现此接口，LocalWhisperSTT 和 DoubaoSTTProvider 是内置实现。

---

1. Groq Whisper（云端）

文件：src/services/voice/groqSTT.ts

通过官方 groq-sdk npm 包调用 Groq LPU API，使用 Whisper 模型。

模型回退：

1. 优先使用 whisper-large-v3
2. 遇到 429（限速）或 5xx（服务端错误）时自动回退到 whisper-large-v3-turbo
3. 其他错误（4xx）直接抛出，不重试

API 密钥解析（优先级从高到低）：

1. 显式传入的 apiKey 参数
2. friend.json 中的 groqApiKey 配置
3. 环境变量 GROQ_API_KEY
4. ~/.claude/settings.json 中的 env.groqApiKey

核心流程：

• connectGroqStream() 返回 VoiceStreamConnection 接口
• 接收 PCM 音频块并缓冲
• finalize() 时将 PCM 转换为 WAV（pcmToWav()，16-bit 单声道，16000 Hz）
• 通过 File API 上传 WAV 到 Groq

---

2. Local Whisper（本地模型）

文件：src/services/voice/whisperSTT.ts

基于 Python openai-whisper 的本地部署方案。

架构：

• 启动一个长期运行的 Python 子进程（whisper_server.py）
• 通过 stdin/stdout 的 JSON 行协议通信
• 支持预加载模型（preloadWhisperModel()）

通信协议：

• {"type":"load","model":"small"} —— 加载模型
• {"type":"transcribe","wav":"/path/to/audio.wav","language":"en"} —— 转写
• 服务端以 {"type":"result","text":"...","language":"..."} 或 {"type":"error","message":"..."} 响应

进程管理：

• 进程崩溃后自动重启
• 30 秒超时保护
• 临时文件自动清理

可用性检查：使用 Python importlib.util.find_spec("whisper") 探测 whisper 模块是否可导入，避免加载 PyTorch 的耗时。

---

3. Anthropic Voice Stream（WebSocket）

文件：src/services/voiceStreamSTT.ts

通过 Anthropic 的 voice_stream WebSocket 端点传输语音，仅在 ant-internal 构建中可用（由 feature('VOICE_MODE') 门控）。

WebSocket 协议：

• 端点：wss://api.anthropic.com/api/ws/speech_to_text/voice_stream
• 认证：OAuth Bearer Token（与 Claude Code 共享凭证）
• 消息类型：
  • KeepAlive —— 每 8 秒发送保持连接
  • CloseStream —— 结束流
  • 服务端推送 TranscriptText、TranscriptEndpoint、TranscriptError

连接生命周期：

1. connectVoiceStream() 建立 WebSocket 连接
2. send(audioChunk) 发送二进制音频帧
3. finalize() 发送 CloseStream，等待服务端返回 TranscriptEndpoint
4. FinalizeSource 枚举标识解析路径：post_closestream_endpoint、no_data_timeout、safety_timeout、ws_close、ws_already_closed

Deepgram Nova 3 门控：通过 GrowthBook 特性标记 deepgram_nova_3_gate 控制是否使用 Deepgram Nova 3 模型。

Voice Keyterms：通过查询参数传递关键词列表，提高领域术语的识别准确率。

---

4. Doubao（豆包 STT）

文件：src/services/voice/doubaoSTT.ts

此文件是一个自动生成的存根（stub），对应 ant-internal 的 feature() 门控模块。外部构建中所有代码路径在 DCE（死代码消除）后不会实际执行。

存根使用 JavaScript Proxy 将任何属性访问、函数调用、构造操作映射到无操作（noop）处理器。导出 connectDoubaoStream、normalizeLanguageForSTT 等函数作为占位符。

DoubaoSTTProvider（在 providers.ts 中）封装了此存根的调用逻辑，通过动态导入（import('./doubaoSTT.js')）在运行时解析。

---

TTS 提供商（Text-to-Speech）

抽象接口

文件：src/services/voice/providers.ts

interface TTSProvider {
  name: string
  synthesize(text: string): Promise<SynthesisResult>
}

EdgeTTSProvider 和 CommandTTSProvider 是内置实现。

---

1. Edge TTS（微软神经网络语音）

文件：src/services/voice/providers.ts（类 EdgeTTSProvider）

实现路径一（Provider 接口）：

• 直接调用 edge-tts 命令行工具
• 使用 Node.js child_process.spawn 执行子进程
• 通过 --voice、--text、--write-media 参数控制输出
• 默认语音：en-US-AriaNeural

实现路径二（独立函数）： 文件：src/services/voice/edgeTTS.ts（speakWithEdgeTTS()）

• 调用 scripts/speak.py Python 脚本
• 依赖 .venv/bin/python 或系统 Python
• 返回标准化的 TTSResult 接口

实现路径三（Friend 模块）： 文件：src/friend/tts.ts（edgeTts()）

• 使用 node-edge-tts npm 包（Node.js 原生实现，无需 Python）
• 默认语音：zh-CN-XiaoxiaoNeural（中文语音）
• 输出为 MP3 文件

播放功能（src/services/voice/edgeTTS.ts playAudioFile()）：

平台	播放器	说明
macOS	afplay	原生
Linux	ffplay	先 pkill 已有进程，再启动新进程
Windows	start	系统默认播放器

---

2. Qwen DashScope TTS（通义千问语音合成）

文件：src/friend/tts.ts（qwenTts()）

调用阿里云 DashScope API 进行语音合成。

API 信息：

• 国内端点：https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
• 国际端点：https://dashscope-intl.aliyuncs.com/...
• 默认模型：qwen3-tts-flash
• 默认语音：Cherry
• 认证：Bearer Token（apiKey）

参数：

• voice：语音角色（如 Cherry, Polly 等）
• model：模型版本
• language：语言（zh 或 en），决定端点选择和 language_type

流程：

1. POST 请求获取合成音频的 URL
2. 从 URL 下载音频数据
3. 保存为 WAV 临时文件
4. 支持 30 秒超时保护

音频文件注册：registerAudioFile() 将文件路径注册到内存映射，5 分钟后自动过期，用于跨模块引用。

---

3. Command TTS（命令模板回退）

文件：src/services/voice/providers.ts（类 CommandTTSProvider）

通用 shell 命令 TTS，支持模板占位符：

• {input} / {input_path} —— 输入文本文件路径
• {output_path} —— 输出音频文件路径

适用于调用任意外部 TTS 命令行工具。

---

Voice Stream 协议

文件：src/services/voiceStreamSTT.ts

Voice Stream 是 Anthropic 的 WebSocket 协议，用于实时语音识别。

消息类型

方向	类型	说明
客户端 → 服务端	KeepAlive	心跳，每 8 秒
客户端 → 服务端	CloseStream	结束音频流
客户端 → 服务端	二进制帧	PCM 音频数据
服务端 → 客户端	TranscriptText	转写文本片段
服务端 → 客户端	TranscriptEndpoint	转写结束标记
服务端 → 客户端	TranscriptError	错误信息

FinalizeSource 枚举

finalize() 方法的解析路径：

值	说明
post_closestream_endpoint	正常流程：发送 CloseStream 后收到 TranscriptEndpoint
no_data_timeout	发送 CloseStream 后 1.5 秒无响应
safety_timeout	WebSocket 挂起超过 5 秒
ws_close	WebSocket 连接关闭
ws_already_closed	已关闭的连接被重复调用

Keyterms（关键词）

通过 WebSocket 查询参数 keyterms 传递关键词列表，格式为逗号分隔的 URL 编码值。关键词可提高模型对特定术语的识别准确率。

---

Voice Mode（语音模式）

语音模式是 Push-to-Talk（按住说话）的实现：

1. 开始录音：用户按下语音快捷键
2. 音频采集：底层 cpal 或回退方案开始采集 16kHz 单声道 PCM 音频
3. 音频传输：音频块通过 Voice Stream WebSocket 实时发送
4. 释放停止：用户松开快捷键，发送 CloseStream
5. 等待转写：接收服务端返回的 TranscriptText 和 TranscriptEndpoint
6. 提交文本：转写文本进入对话输入流

当使用本地 Whisper 时，流程类似但使用子进程通信而非 WebSocket。

---

提供商注册与选择

文件：src/services/voice/providers.ts

系统通过 TranscriptionProvider 和 TTSProvider 接口实现多提供商支持。每个提供商有自己的名称（name 属性）和实现逻辑。选择策略在调用方（如 useVoice hook）中决定，根据可用性和用户配置选择合适的提供商。