Voice Control Agent — Development skill for Claude Code

Voice Control Agent

给 Codex 桌面 App 接一个可喊名字的 Mac 语音入口。当前应用名和默认唤醒词为 **小 C**。

喊「小 C」 → 提示音 → 说指令 → 停顿后转文字 → 发到你绑定的同一个 Codex 会话 → 自动朗读最终回复。

这是一个通用语音入口，不限于控制投影仪。能执行什么，取决于目标会话里的 Agent、工具、Skill 和你的授权。非 OpenAI 官方产品。

已验证的能力

• 本机中文唤醒和说话结束检测；唤醒后的指令音频交给火山语音识别。
• codex queue 按固定会话 ID 投递，在切换聊天、重启发送程序和连续投递时仍进入同一会话。
• 专用会话回复完成后只朗读一次；启动时跳过旧回复。
• 朗读/试听期间屏蔽唤醒，避免把自己的声音作为新指令。
• 菜单栏入口、暂停、手动唤醒、停止朗读、声音试听、设置面板。
• Mac 睡眠暂停监听，恢复后按之前状态重新启动。

开发中已通过一次用户真人唤醒和发送测试，以及回复朗读测试。不同麦克风、距离和电视背景声下的识别率需要自行调整；不保证永不误唤醒。

环境

• Apple Silicon Mac，macOS 14+，Xcode Command Line Tools。
• Python 3.12+；构建在线朗读助手需要 uv（https://docs.astral.sh/uv/）。
• 已安装并登录 Codex 桌面 App，其自带 CLI 必须支持 queue --thread --message 和 App Server 的 thread/turns/list。
• 你自己的火山语音识别服务配置及相应资源权限。App 不包含任何 API 凭据。
• Mac 保持唤醒、麦克风可用、网络可用。睡眠或退出后不能响应唤醒词。

Codex CLI 与 App Server 会随版本变化，本项目按开发时本机版本验证。普通独立 CLI 与桌面 App 自带 CLI 不一定有同样能力；缺少 queue 或读取接口时，不会改用模拟键盘盲投递。

从源码构建

git clone https://github.com/Wechat-ggGitHub/voice-control-agent.git
cd voice-control-agent
python3.12 prepare.py
python3.12 build.py

`prepare.py` 从上游下载 sherpa-onnx 1.13.8、关键词模型、Silero VAD 和 C API 头文件；`build.py` 生成图标和提示音，构建本机库和 Swift App。首次会经 `build_speech.py` 使用 uv 创建 Python 3.12 环境并下载 edge-tts 7.3.1、PyInstaller 等，用于打包可替换的在线朗读助手及许可文件。

得到 `dist/小C.app`。将它复制到应用程序目录并打开。构建过程不启动麦克风、不读取钥匙串、不发送 Codex 消息，也不自动安装。

构建产物采用临时签名、未经 Developer ID 公证。请检查源码并通过 macOS 正常的打开确认流程使用，无需关闭系统整体安全保护。Intel Mac 尚未验证。

第一次配置

公开版默认会话为空、自动监听关闭，采用独立设置和钥匙串域，不会读取作者个人版的会话或密钥。

1. 在 Codex 桌面 App 创建一个本地专用会话，确认你希望它使用的工具和权限。
2. 从该会话链接 codex://threads/ 获取 ID，填写到小 C 的「专用会话」。不要填作者的 ID，也不需要另建一个 ChatGPT 网页聊天。
3. 设置桌面 App 自带的 codex 可执行文件。默认候选位置为 /Applications/ChatGPT.app/Contents/Resources/codex-cli/bin/codex；若你的安装位置不同，按本机实际位置填写。
4. 在「语音识别」填自己的火山 App ID + Access Token，或受支持的 API Key，选择对应接口和 Resource ID。Resource ID 必须与你开通的资源一致。
5. 若本机安装了闪电说，也可以主动点击导入其火山配置。公开版不会启动时自动读取它。
6. 保存后点击开始监听，允许麦克风权限。先说「小 C」，听到提示音后说「只回复测试收到」，停顿约 1.6 秒。
7. 查看固定 Codex 会话，确认文字进入正确位置，再确认自动朗读。

默认唤醒词目前在 build.py 生成