VoxMesh

VoxMesh — это платформонезависимый голосовой шлюз для AI-агентов на основе искусственного интеллекта.

Проект предназначен для соединения речевого ввода, преобразования речи в текст, AI-агента, MCP-инструментов, преобразования текста в речь и голосового вывода, сохраняя при этом ядро агента (Agent Core) независимым от оборудования, операционных систем и поставщиков AI-решений.

Статус проекта

VoxMesh имеет начальный вертикальный срез в Mock Mode для разработки и проверки архитектуры. Он включает:

• монорепозиторий на основе pnpm и TypeScript

• сервер Fastify и веб-консоль React

• первичную настройку пароля администратора и аутентификацию сеансов

• хранение разговоров и журналов в SQLite

• контракты Agent Core, независимые от поставщика

• детерминированное выполнение Mock LLM и Mock MCP-инструментов

• запись голоса в Mock-режиме через браузер с Mock STT и генерацией WAV-ответа

• выбираемые режимы голосового конвейера Composed и Mock Native Multimodal

• страницы Dashboard, Chat, Conversations и Logs

• страницу Settings для смены пароля и настройки Mock/Azure OpenAI

• обработку ключа API Azure OpenAI только на запись и проверку соединения

• универсальную настройку LLM, совместимую с OpenAI, включая Alibaba Cloud Model Studio

• локализацию веб-консоли на английский и упрощённый китайский языки

• определение языка браузера и сохранение выбранного языка

• режимы оформления Light, Dark и System

• сохранение выбора оформления с синхронизацией с операционной системой в реальном времени

• функционально-ориентированные React-компоненты, выполняющие одну задачу

• поведенческие тесты React Testing Library для каждого текущего UI-компонента

• TanStack Router с Browser History и страницами с глубокими ссылками

• TanStack Query для удалённого состояния сервера и инвалидации кэша

• TanStack Form для сложных рабочих процессов в Settings

• модульные, интеграционные и сквозные тесты Playwright

Azure Speech, универсальные внешние MCP-транспорты, физический звук и упаковка для развёртывания остаются запланированной работой.

Архитектура рассчитана на:

• разработку в macOS, Linux и Windows

• развёртывание на Linux amd64 и arm64

• развёртывание через Docker Compose и нативный systemd

• Mock Mode без оборудования и учётных данных внешних сервисов

Related MCP server: Pipecat MCP Server

Требования

• Node.js 22.12 или новее

• pnpm 10.27

Быстрый старт

pnpm install
pnpm build
pnpm --filter @voxmesh/server start

Откройте http://127.0.0.1:3000, создайте пароль первого администратора, войдите в систему и используйте Chat. Введите Check the light status, чтобы выполнить поток Mock LLM -> Mock MCP -> Mock LLM.

Страница Chat также предоставляет элементы управления Start recording, Stop recording и Play response. В Mock Mode записанный звук проверяется, преобразуется в детерминированную тестовую фразу, обрабатывается через Agent Core и Mock MCP и возвращается сгенерированным тестовым WAV-файлом.

Используйте Settings, чтобы изменить пароль администратора или переключить Chat между Mock и Azure OpenAI. Azure OpenAI требует HTTPS-конечную точку, имя развёртывания, версию API и ключ API. Ключ API хранится в локальной базе данных SQLite, никогда не возвращается в браузер и защищён правами доступа файловой системы хоста.

Поставщик LLM также может использовать API, совместимый с OpenAI. Для Alibaba Cloud Model Studio настройте базовый URL региона/рабочей области, ключ API и имя модели, например qwen-plus.

Речь Alibaba Cloud использует выделенного поставщика STT/TTS Alibaba Cloud Model Studio, а не совместимый с OpenAI Audio API. Настройте конечную точку WebSocket рабочей области, ключ API, модель ASR или TTS реального времени, язык и голос независимо для STT и TTS.

Используйте селектор языка на экране настройки, входа в систему или в Settings, чтобы переключиться между английским и упрощённым китайским. Предпочтение сохраняется в браузере и применяется немедленно.

Используйте селектор оформления в Settings, чтобы выбрать Light, Dark или System. System — значение по умолчанию, которое следует за изменениями темы операционной системы в реальном времени.

Для разработки фронтенда и бэкенда с автоматической перезагрузкой:

pnpm dev

Веб-консоль доступна по адресу http://127.0.0.1:5173 и проксирует API-запросы на сервер через порт 3000.

Страницы веб-консоли используют стабильные URL, такие как /dashboard, /chat, /conversations, /conversations/<id>, /logs и /settings. Поддерживаются прямой переход, обновление страницы, а также кнопки назад и вперёд в браузере.

Конфигурация

Скопируйте значения из .env.example в ваше окружение или менеджер процессов:

Первый пароль администратора должен содержать не менее 10 символов. Пароли хранятся в виде хешей scrypt с солью. Cookie сеанса имеют атрибуты HttpOnly и SameSite=Strict.

Смена пароля администратора аннулирует все активные сеансы. Настройки Azure OpenAI вступают в силу при следующем запросе в Chat. Действие проверки соединения отправляет небольшой запрос к настроенному развёртыванию и может привести к расходам на использование поставщика.

Проверка

pnpm format:check
pnpm lint
pnpm typecheck
pnpm test:unit
pnpm test:integration
pnpm build
pnpm test:e2e

Запустите все необходимые проверки с помощью:

pnpm validate

Playwright MCP

Файл .mcp.json на уровне репозитория настраивает Playwright MCP для исследования браузера через структурированные снимки доступности. Copilot CLI и Claude Code обнаруживают этот файл из корня репозитория после подтверждения доверия к рабочей области.

Сервер использует последний официальный выпуск пакета и изолированные сеансы браузера, поэтому cookie и состояние входа не сохраняются между MCP-сеансами. Перезапустите MCP-клиент после изменения конфигурации.

Тесты по умолчанию и Mock Mode не требуют учётных данных AI, внешних MCP-серверов или аудиооборудования.

Рабочая область

apps/server           Fastify API, authentication, and composition root
apps/web              React and Vite Web Console
apps/web/src/features Feature-oriented pages, forms, and settings components
apps/web/src/components Shared layout components
apps/web/src/router.tsx Typed TanStack Router route tree and guards
apps/web/src/query.ts Typed TanStack Query keys and query options
packages/agent-core   Provider-independent agent runtime and mocks
packages/shared       Runtime schemas and shared contracts
packages/storage      SQLite storage adapter
tests/e2e             Browser end-to-end tests

Документация

• Спецификация разработки MVP

• План реализации

• Обязательные правила разработки

• Технологический стек и руководство по разработке

• Стандарт доступности и аудит

• Руководство по разработке в Mock Mode

• Руководство по настройке Azure OpenAI

• План поставщика Alibaba Cloud Model Studio

• Архитектура голосового конвейера

Инструкции для агентов написания кода

• Общие инструкции и инструкции для Codex

• Инструкции для Claude Code

• Инструкции для GitHub Copilot

Политика разработки

Перед реализацией функционального изменения:

1. Обсудите и подтвердите его поведение, область действия, риски, критерии приёмки и требования к тестированию.

2. Создайте отдельную ветку от последней main; никогда не редактируйте main и не выполняйте push напрямую в main.

3. Весь контент репозитория и комментарии в коде должны быть на английском языке.

4. Добавьте полные модульные тесты, интеграционные тесты, где применимо, и сквозные тесты.

5. Добавьте документацию для разработчиков на английском языке и полезные комментарии JSDoc или пояснения причин для публичных контрактов, конфигурации, архитектуры, ограничений безопасности и неочевидного поведения.

6. Запустите все применимые проверки форматирования, линтера, типов, тестов и production-сборки.

7. Используйте сообщения коммитов и заголовки PR в стиле Conventional Commit и разбивайте несвязанные изменения на отдельные коммиты.

8. Получите отдельное явное одобрение перед коммитом, push, созданием pull request, слиянием или релизом.

Полную обязательную политику см. в Правилах разработки.