VoxMesh

VoxMesh es una puerta de enlace de agentes de IA centrada en la voz e independiente de la plataforma.

El proyecto está diseñado para conectar entrada de voz, conversión de voz a texto, un agente de IA, herramientas MCP, conversión de texto a voz y salida de voz, manteniendo el Agent Core independiente del hardware, los sistemas operativos y los proveedores de IA.

Estado del proyecto

VoxMesh dispone de un corte vertical inicial de Mock Mode para el desarrollo y la validación de la arquitectura. Incluye:

• un monorepo de pnpm y TypeScript

• un servidor Fastify y una consola web React

• configuración de la contraseña de administrador en el primer arranque y autenticación de sesión

• persistencia de conversaciones y registros en SQLite

• contratos de Agent Core independientes del proveedor

• ejecución determinista de herramientas Mock LLM y Mock MCP

• grabación de voz simulada en el navegador con Mock STT y respuesta WAV generada

• modos seleccionables de canalización de voz Composed y Mock Native Multimodal

• páginas Dashboard, Chat, Conversations y Logs

• página Settings para la rotación de contraseña y la configuración de Mock/Azure OpenAI

• manejo de la clave de API de Azure OpenAI de solo escritura y prueba de conexión

• configuración genérica de LLM compatible con OpenAI, incluido Alibaba Cloud Model Studio

• localización de la consola web en inglés y chino simplificado

• detección del idioma del navegador y selección de idioma persistente

• modos de apariencia Light, Dark y System

• selección de apariencia persistente con sincronización en vivo con el sistema operativo

• componentes React orientados a funciones y de propósito único

• pruebas de comportamiento de React Testing Library para cada componente de interfaz actual

• TanStack Router con Browser History y páginas con enlaces profundos

• TanStack Query para el estado remoto del servidor y la invalidación de caché

• TanStack Form para flujos de trabajo complejos de Settings

• pruebas unitarias, de integración y de extremo a extremo con Playwright

Azure Speech, los transportes MCP externos genéricos, el audio físico y el empaquetado de despliegue siguen siendo trabajo planificado.

La arquitectura está diseñada para:

• desarrollo en macOS, Linux y Windows

• despliegue en Linux amd64 y arm64

• despliegue con Docker Compose y systemd nativo

• Mock Mode sin hardware ni credenciales de servicios externos

Related MCP server: Pipecat MCP Server

Requisitos

• Node.js 22.12 o posterior

• pnpm 10.27

Inicio rápido

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

Abra http://127.0.0.1:3000, cree la primera contraseña de administrador, inicie sesión y use Chat. Introduzca Check the light status para ejercitar el flujo Mock LLM -> Mock MCP -> Mock LLM.

La página Chat también proporciona los controles Start recording, Stop recording y Play response. En Mock Mode, el audio grabado se valida, se transcribe a una frase de prueba determinista, se procesa a través de Agent Core y Mock MCP, y se devuelve con un WAV de prueba generado.

Use Settings para cambiar la contraseña de administrador o alternar Chat entre Mock y Azure OpenAI. Azure OpenAI requiere un endpoint HTTPS, nombre de despliegue, versión de API y clave de API. La clave de API se almacena en la base de datos SQLite local, nunca se devuelve al navegador y está protegida por los permisos del sistema de archivos del host.

El proveedor de LLM también puede usar una API compatible con OpenAI. Para Alibaba Cloud Model Studio, configure la URL base de la región/espacio de trabajo, la clave de API y el nombre del modelo, como qwen-plus.

El habla de Alibaba Cloud usa el proveedor STT/TTS dedicado Alibaba Cloud Model Studio, no la API de Audio compatible con OpenAI. Configure el endpoint WebSocket del espacio de trabajo, la clave de API, el modelo ASR o TTS en tiempo real, el idioma y la voz de forma independiente para STT y TTS.

Use el selector de idioma en la configuración inicial, el inicio de sesión o Settings para alternar entre inglés y chino simplificado. La preferencia se almacena en el navegador y se aplica de inmediato.

Use el selector de apariencia en Settings para elegir Light, Dark o System. System es el valor predeterminado y sigue los cambios de tema del sistema operativo en vivo.

Para el desarrollo de frontend y backend con recarga automática:

pnpm dev

La consola web está disponible en http://127.0.0.1:5173 y envía las solicitudes de API al servidor en el puerto 3000.

Las páginas de la consola web usan URL estables como /dashboard, /chat, /conversations, /conversations/<id>, /logs y /settings. Se admiten la carga directa, la actualización y la navegación hacia atrás o hacia adelante del navegador.

Configuración

Copie los valores de .env.example en su entorno o gestor de procesos:

La primera contraseña de administrador debe contener al menos 10 caracteres. Las contraseñas se almacenan como hashes scrypt con sal. Las cookies de sesión son HttpOnly y SameSite=Strict.

Cambiar la contraseña de administrador revoca todas las sesiones activas. La configuración de Azure OpenAI surte efecto en la siguiente solicitud de Chat. La acción de prueba de conexión envía una solicitud pequeña al despliegue configurado y puede generar costes de uso del proveedor.

Validación

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

Ejecute todas las comprobaciones necesarias con:

pnpm validate

Playwright MCP

El .mcp.json a nivel de repositorio configura Playwright MCP para la investigación del navegador mediante instantáneas de accesibilidad estructuradas. Copilot CLI y Claude Code descubren este archivo desde la raíz del repositorio después de aprobar la confianza del espacio de trabajo.

El servidor usa la última versión oficial del paquete y sesiones de navegador aisladas, de modo que las cookies y el estado de inicio de sesión no se conservan entre sesiones de MCP. Reinicie el cliente MCP después de cambiar la configuración.

Las pruebas predeterminadas y Mock Mode no requieren credenciales de IA, servidores MCP externos ni hardware de audio.

Espacio de trabajo

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

Documentación

• Especificación de desarrollo de MVP

• Plan de implementación

• Reglas de desarrollo obligatorias

• Pila tecnológica y guía de desarrollo

• Estándar y auditoría de accesibilidad

• Guía de desarrollo de Mock Mode

• Guía de configuración de Azure OpenAI

• Plan del proveedor Alibaba Cloud Model Studio

• Arquitectura de canalizaciones de voz

Instrucciones para agentes de codificación

• Instrucciones compartidas y de Codex

• Instrucciones de Claude Code

• Instrucciones de GitHub Copilot

Política de desarrollo

Antes de implementar un cambio funcional:

1. Discuta y confirme su comportamiento, alcance, riesgos, criterios de aceptación y requisitos de prueba.

2. Cree una rama dedicada desde la última main; nunca edite ni haga push directamente a main.

3. Mantenga todo el contenido del repositorio y los comentarios de código en inglés.

4. Añada pruebas unitarias completas, de integración cuando corresponda y de extremo a extremo.

5. Añada documentación de desarrollo en inglés y comentarios útiles de JSDoc o de razonamiento para contratos públicos, configuración, arquitectura, restricciones de seguridad y comportamiento no evidente.

6. Ejecute todas las comprobaciones aplicables de formato, lint, verificación de tipos, pruebas y compilación de producción.

7. Use mensajes de commit y títulos de PR de estilo Conventional Commit, y divida los cambios no relacionados en commits enfocados.

8. Obtenga una aprobación explícita por separado antes de hacer commit, push, crear una pull request, fusionar o publicar.

Consulte Reglas de desarrollo para conocer la política obligatoria completa.