voice-dialog

给 AI Agent 加语音对话能力的 MCP server，也能当命令行工具用。Agent 干完活可以说话告诉你，也能开口问你、听你回答。识别跑在本地的 whisper 上，合成用系统自带的 TTS，全程不联网、不传音频。

它能做什么

你（没看屏幕）："搞定了吗？"
Agent（出声）："代码写完了，测试全过。要提交吗？"      ← ask_by_voice
你："先不提交，我看看再说"                             ← listen 收到，本地转写
Agent（出声）："好，先留着。"                          ← speak

工具	用途
speak	单向播报（任务完成、里程碑）
listen	录音+识别（你口述指令）
ask_by_voice	原子问答：说一句→听一次，绝不自动续听（防死循环）
init	一键初始化（见下）
doctor	环境体检（只查不装）

快速开始

git clone https://github.com/VictorHuang0843/voice-dialog.git
cd voice-dialog

# 没装 uv？先来这个（Windows 用 install.ps1）：
#   curl -LsSf https://astral.sh/uv/install.sh | sh

uv run voice-dialog init

init 是 7 步全自动引导：装 uv → 装依赖（uv 连 Python 都帮你装好）→ 下载 whisper 模型（464MB，中国网络自动走 hf-mirror）→ 麦克风权限实测 → TTS 出声实测 → 打印 MCP 注册命令。哪步失败就给哪步的修复命令，修好重跑即可。

试一句：

uv run voice-dialog speak "语音系统就绪" --lang zh
uv run voice-dialog ask "请说话" --wait-start 60
# 你会听到：高亮上扬"叮↑"= 开始说话 → 停 3 秒 → 低沉"咚…咚↓"= 录音结束

接入你的 Agent

任何 MCP 客户端（Claude Code、Codex、Cursor、LoopX……）：

{
  "mcpServers": {
    "voice-dialog": {
      "command": "uv",
      "args": ["--project", "/你的路径/voice-dialog", "run", "voice-dialog", "serve"]
    }
  }
}

Claude Code 一行注册：

claude mcp add voice-dialog -s user -- uv --project /你的路径/voice-dialog run voice-dialog serve

不支持 MCP 的工具：直接调 CLI，uv run voice-dialog speak/listen/ask "..."。

Claude Code Skill（可选，教 Agent 何时说/何时听）：把 skills/voice-dialog/ 拷到 ~/.claude/skills/。

支持的平台

	macOS	Windows	Linux
语音识别	实测通过	可用	可用
语音合成	系统TTS	SAPI	需装 espeak-ng
提示音	可用	可用	需 ffmpeg

语言自动检测（whisper 支持 ~100 种语言），VD_LANG=zh 可钉死；模型大小 VD_MODEL=small 可调。

常见问题

症状	解法
init 报 uv 未装	跑上面 curl 安装命令，装完重开终端
麦克风探针失败	macOS：系统设置→隐私与安全性→麦克风→勾选你的终端；Windows：设置→隐私→麦克风
模型下载失败/超慢	export HF_ENDPOINT=https://hf-mirror.com 后重跑
TTS 无声	检查系统输出设备是否被虚拟声卡（BlackHole 等）劫持
改了代码不生效	MCP server 是常驻进程：pkill -f "voice-dialog serve"

隐私

语音在本地识别（faster-whisper），文本用系统 TTS 播放，不调用任何云端 API，不上传任何音频。

License

MIT

模型说明

默认下载什么？ whisper small（int8 量化，约 464MB），中英文识别效果和速度的平衡点。首次 listen/init 时自动下载，之后缓存在本地（macOS/Linux：~/.cache/huggingface/hub/，Windows：%USERPROFILE%\.cache\huggingface\hub\），永不再下。

下载源怎么选？ 代码里不写死下载逻辑——WhisperModel("small", ...) 构造时由 faster-whisper 库自动从 HuggingFace 下载。默认走官方源 huggingface.co；官方源连不上时代码自动切国内镜像 hf-mirror.com 重试（通过设置 HF_ENDPOINT 环境变量实现）。国内用户也可以提前手动钉死：

export HF_ENDPOINT=https://hf-mirror.com   # 加进 ~/.zshrc 一劳永逸

换更大的模型？ 环境变量 VD_MODEL 控制，重跑生效：

VD_MODEL	大小	特点
tiny	~75MB	最快，精度一般
base	~142MB	快，日常够用
small（默认）	~464MB	平衡，推荐
medium	~1.5GB	更准，M 芯片秒级转写变十秒级
large-v3	~3GB	最准最慢，短对话不建议

VD_MODEL=base uv run voice-dialog listen   # 单次用 base

从 zip 安装（不用 git clone）

下载 zip（或朋友直接发你）→ 解压到想放的地方，比如 ~/tools/ → 打开终端进目录，后面交给 AI：

在 Claude Code（或任何能执行命令的 AI 编程工具）里，把下面这段原样发给它：

帮我安装这个目录里的 voice-dialog 项目：
1. cd 到这个目录跑 uv run voice-dialog init（没装 uv 就先装：curl -LsSf https://astral.sh/uv/install.sh | sh）
2. init 全绿后，把打印出来的 claude mcp add 命令执行掉
3. 最后跑 uv run voice-dialog doctor 给我看结果

它会装好一切并注册到 Claude Code，重启会话即可用。

也可以手动，就两条命令：

cd 解压后的目录
uv run voice-dialog init        # 结束时打印注册命令，复制执行

Mac 上不熟悉终端的话：解压后在文件夹上右键 → 服务 → 新建位于文件夹位置的终端窗口，就到目录了。