agent-voice-mcp-minus

улучшенная версия agent-voice-mcp · Локальный MCP-сервис голосового озвучивания, предоставляющий ИИ-ассистентам программирования (Trae / Claude Desktop / Cursor и др.) возможность голосового оповещения о прогрессе задач, глубоко адаптированный под большую модель синтеза речи Doubao от Volcano Engine (seed-tts).

Этот проект — форк al96169/agent-voice-mcp (автор Antonio Liang, лицензия MIT), на основе которого выполнена масштабная практическая оптимизация под интерфейс v3 Volcano Engine и реальные сценарии использования. Оригинал — это основа, данный проект — основа + практические улучшения; все улучшения можно отключить через конфигурацию и вернуться к поведению, близкому к оригиналу.

1. Установка

Предварительные требования

• Node.js ≥ 18 (скачать)

• Windows (облачный синтез работает кроссплатформенно; резерв SAPI и звуковой сигнал — только для Windows, на других платформах автоматическая деградация)

• Аккаунт Volcano Engine (требуется активировать сервис большой модели синтеза речи, см. шаг 2)

Шаг 1: Настройка MCP-клиента

Способ A · запуск напрямую через npx (рекомендуется, без клонирования)

В конфигурацию MCP-клиента добавьте (для Trae — .trae/mcp.json в каталоге проекта; для Claude Desktop — claude_desktop_config.json; для Cursor — .cursor/mcp.json):

{
  "mcpServers": {
    "agent-voice": {
      "command": "npx",
      "args": ["-y", "github:doer1296/agent-voice-mcp-minus"]
    }
  }
}

Способ B · локальный запуск из клонированного репозитория (рекомендуется тем, кому нужно менять код)

git clone https://github.com/doer1296/agent-voice-mcp-minus.git
cd agent-voice-mcp-minus
npm install

В конфигурации MCP замените на прямое подключение к node (запуск быстрее и не зависит от npm-репозитория):

{
  "mcpServers": {
    "agent-voice": {
      "command": "node",
      "args": ["D:/your/path/agent-voice-mcp-minus/dist/index.js"]
    }
  }
}

После настройки перезапустите клиент / откройте новую сессию. При запуске MCP-сервис озвучит: «сервис agent-voice запущен» — это означает готовность.

Шаг 2: Получение учётных данных Volcano Engine

1. Зарегистрируйтесь / войдите в Volcano Engine

2. В консоли найдите «Speech Technology» → активируйте сервис «большая модель синтеза речи» (у новых пользователей есть бесплатная квота)

3. На странице «управление API Key» создайте и получите X-Api-Key

4. Важно: нужно активировать модельный ресурс, соответствующий используемому голосу (seed-tts-1.0 или seed-tts-2.0, см. настройку большой модели)

Бесплатная альтернатива: в оригинале встроен движок Edge TTS (бесплатный онлайн-синтез от Microsoft, не требует API Key, сотни голосов). Установите engine в "edge-tts" — и можно пользоваться; подробности в README оригинала.

Шаг 3: Создание файла конфигурации

Скопируйте config.example.json из этого репозитория в:

Windows: C:\Users\<你的用户名>\.agent-voice\config.json
macOS / Linux: ~/.agent-voice/config.json

Затем замените поле apiKey на ваш X-Api-Key (один из двух вариантов):

• Открытым текстом: "apiKey": "你的key"

• Через переменную окружения (рекомендуется): оставьте "${VOLCANO_API_KEY}", затем задайте системную переменную окружения VOLCANO_API_KEY=你的key (файл конфигурации поддерживает синтаксис ${任意环境变量名}, чтобы key не хранился открытым текстом)

2. Как вызывать (на стороне агента)

MCP-сервис регистрирует инструмент speak; агент вызывает его — и происходит озвучивание:

Рекомендация: с помощью правил проекта настройте агента на автоматическое озвучивание жизненного цикла задач. Добавьте в .trae/rules/project_rules.md (для Trae) или в CLAUDE.md (для Claude):

在每次任务中，调用 agent-voice MCP 进行语音播报：
1. 任务开始时 — scene="task_start"
2. 每个子任务完成时 — scene="milestone"
3. 任务全部完成时 — scene="task_complete"
4. 遇到错误时 — scene="task_error"
5. 需要用户确认时 — scene="need_interaction"

Пример вызова:

speak(text="开始执行任务：重构登录模块", scene="task_start", emotion="calm")
speak(text="任务完成，测试全部通过", scene="task_complete", emotion="happy")

Другие инструменты: stop (останавливает текущее озвучивание и очищает очередь), get_voices (показывает доступные голоса), get_roles (показывает настроенные роли).

3. Настройка большой модели (выбор модели)

Поле cloud.resourceId в config.json определяет, какая большая модель синтеза речи будет использоваться:

⚠️ Голос и версия модели должны совпадать: голос _moon_bigtts с seed-tts-2.0 (или наоборот) вызовет ошибку HTTP 403 «ресурс не авторизован». При смене модели не забудьте синхронно сменить ID голоса, а также активировать соответствующий модельный сервис в консоли Volcano.

Рекомендации по выбору: 1.0 стабильна, богата голосами и имеет зрелую документацию; 2.0 поддерживает новые возможности, такие как клонирование голоса. Все практические оптимизации в этом проекте основаны на 1.0.

4. Как сменить голос

Измените cloud.voice в config.json (а также поля voice в настройках сцен) и убедитесь, что голос соответствует версии resourceId:

seed-tts-1.0 示例：
  zh_female_daimengchuanmei_moon_bigtts   呆萌川妹（甜美女声，本项目默认）
  zh_female_qingxinnvsheng_mars_bigtts    清新女声

seed-tts-2.0 示例：
  zh_female_vv_uranus_bigtts              温柔女声
  zh_male_*.uranus_bigtts                 男声系列

Полный список голосов см. в документации библиотеки голосов Volcano Engine.

5. Регулировка громкости / скорости речи

Громкость volume (по умолчанию 1.3):

• Соотношение: loudness_rate = (volume − 1) × 100, то есть 1.0 = исходная громкость, 1.3 = +30% (фактический прирост RMS около +29%, почти линейный)

• Рекомендуемый диапазон значений 0.5 – 2.0; 2.0 = +100% (верхний предел на стороне сервера)

• Глобальное значение по умолчанию находится в верхнем уровне volume; каждый сценарий можно переопределить отдельно (scenes.*.volume)

Скорость речи rate (по умолчанию 200):

• Соотношение: speech_rate = (rate / 200 − 1) × 100, то есть 200 = исходная скорость, 220 = +10%, 180 = −10%

• Градиент сцен по умолчанию (рекомендация по результатам тестов этого проекта): начало 190 → взаимодействие 200 → веха/ошибка 210 → завершение 220

6. Передняя тишина Bluetooth (важно)

cloud.leadingSilence (по умолчанию 1500, то есть 1,5 секунды):

Этот параметр предназначен для пользователей Bluetooth-наушников. Установление аудиоканала Bluetooth занимает примерно 1–2 секунды; в начале озвучивания наушники часто ещё не подключены, поэтому первый слог съедается шумом подключения. Данный параметр вставляет в начало голосовых данных полную тишину указанной длительности в миллисекундах, и речь начинается только после готовности Bluetooth-канала.

• Для пользователей Bluetooth-наушников: оставьте 1500 (если слоги всё ещё проглатываются, можно увеличить до 2000)

• Для проводных наушников / динамиков: установите 0 — озвучивание станет более компактным

• Сигнал перед озвучиванием сам по себе является аудиовыходом, он заранее активирует Bluetooth-канал и работает в связке с этим параметром

7. Полная таблица параметров

Резервный канал озвучивания (watcher, опционально)

watcher/voice-watcher.mjs — это резидентный слушатель, не зависящий от MCP-соединения: он опрашивает ~/.trae-cn/work/.voice-reader/pending.txt и, обнаружив помеченное содержимое, озвучивает его через тот же облачный движок, что и основной сервис (конфигурация, голос и громкость берутся из того же источника в реальном времени; при сбое облака также используется резерв SAPI).

Назначение: когда инструменты MCP недоступны в сессии агента (например, при смене модели или сбое MCP-сервиса), вы всё ещё можете записать маркер в этот файл, чтобы запустить озвучивание; это создаёт резервный канал:

[VOICE_READER_START:success]
要播报的文本
[VOICE_READER_END]

Поддерживаются типы info / success / error / warning, которые сопоставляются параметрам сцен task_start / task_complete / task_error / need_interaction соответственно.

Как включить: в config.json задайте "watcher": { "enabled": true }. Основной MCP-сервис при запуске автоматически поднимает watcher как дочерний процесс и завершает его при выходе (TCP-гард единственного экземпляра на порту 47613 — при нескольких сессиях запущена только одна копия). Можно также запустить отдельно: node watcher/voice-watcher.mjs.

Переносимость путей: все пути вычисляются относительно или через os.homedir(), без жёстко заданных абсолютных путей. Переменные окружения могут переопределять их: AGENT_VOICE_CONFIG (путь к файлу конфигурации), AGENT_VOICE_PENDING_DIR (каталог, в котором находится pending.txt; по умолчанию ~/.trae-cn/work/.voice-reader; подходит для других MCP-клиентов).

Примечания

1. Конфигурация загружается один раз при запуске MCP. После изменения config.json необходимо перезапустить клиент / открыть новую сессию, чтобы изменения вступили в силу (файл не перечитывается перед каждым объявлением).

2. Частота дискретизации и каналы: фактическая полоса этого голоса ≤ 12 кГц; запрос 32/44,1/48 кГц даёт лишь интерполяционный апсемплинг без улучшения качества (подтверждено многоконным FFT-анализом полос); API поддерживает только моно, при воспроизведении система автоматически микширует на два уха. Оставляйте 24000 — это оптимально.

3. Эмоции реализованы на стороне клиента: интерфейс v3 в seed-tts-1.0 не поддерживает серверный параметр emotion (по факту переданное значение молча игнорируется). Этот проект выражает шесть эмоций комбинацией высоты тона (pitch ±12) + смещения скорости/громкости, а emotionIntensity управляет интенсивностью.

4. Не включайте SSML: тег паузы SSML <break> в потоковом интерфейсе 1.0 + v3 (по факту) обрезает аудио (синтезируется только первое предложение). Паузы для длинных текстов уже реализованы клиентским решением, SSML не нужен.

5. Квоты и тарификация: Volcano Engine тарифицируется по символам, поэтому текст объявлений о задачах рекомендуется делать кратким (отчасти поэтому в проекте по умолчанию обрезается 200 символов); при исчерпании квоты автоматически происходит переход на локальный голос SAPI (тембр изменится — это нормально).

6. Зависимость от Windows: для звукового сигнала используется System.Console::Beep, для воспроизведения речи — PowerShell Media.SoundPlayer — это встроено в Windows, но если PowerShell отключён групповой политикой, соответствующие функции деградируют.

7. Выходной каталог: синтезированное аудио записывается во временный каталог системы, после воспроизведения автоматически удаляется, без остатков.

Благодарности

• agent-voice-mcp и оригинальный автор Antonio Liang — этот проект улучшает их MIT-код с открытым исходным кодом; такие ключевые разработки, как голосовые роли и мультидвижковая архитектура, взяты из оригинала

• Volcano Engine · Модель синтеза речи Doubao

License

MIT (наследует лицензию исходного проекта, сохраняет указание оригинального автора)