VoxMesh

VoxMesh ist ein plattformunabhängiges, sprachgesteuertes AI-Agent-Gateway.

Das Projekt ist darauf ausgelegt, Spracheingabe, Speech-to-Text, einen AI-Agenten, MCP-Tools, Text-to-Speech und Sprachausgabe zu verbinden, während der Agent Core unabhängig von Hardware, Betriebssystemen und AI-Anbietern bleibt.

Projektstatus

VoxMesh verfügt über einen ersten Mock-Mode-Vertikalschnitt für Entwicklung und Architekturvalidierung. Er umfasst:

• ein pnpm- und TypeScript-Monorepo

• einen Fastify-Server und eine React-Web-Konsole

• Ersteinrichtung des Administratorpassworts und Sitzungsauthentifizierung

• SQLite-Persistenz für Konversationen und Protokolle

• anbieterunabhängige Agent-Core-Verträge

• deterministische Mock-LLM- und Mock-MCP-Tool-Ausführung

• Browser-Mock-Voice-Aufnahme mit Mock-STT und generierter WAV-Antwort

• wählbare Composed- und Mock-Native-Multimodal-Sprachpipeline-Modi

• Dashboard-, Chat-, Konversations- und Protokollseiten

• Einstellungsseite für Passwortrotation und Mock-/Azure-OpenAI-Konfiguration

• Schreibgeschützte Azure-OpenAI-API-Schlüsselverwaltung und Verbindungstests

• generische OpenAI-kompatible LLM-Konfiguration, einschließlich Alibaba Cloud Model Studio

• Lokalisierung der Web-Konsole in Englisch und vereinfachtem Chinesisch

• Browser-Spracherkennung und gespeicherte Sprachauswahl

• Helle, dunkle und System-Erscheinungsmodi

• gespeicherte Erscheinungsauswahl mit Live-Synchronisierung mit dem Betriebssystem

• funktionsorientierte, zweckgebundene React-Komponenten

• React-Testing-Library-Verhaltenstests für jede aktuelle UI-Komponente

• TanStack Router mit Browser-History und tief verlinkbaren Seiten

• TanStack Query für entfernten Serverstatus und Cache-Invalidierung

• TanStack Form für komplexe Einstellungsworkflows

• Unit-, Integrations- und Playwright-End-to-End-Tests

Azure Speech, generische externe MCP-Transports, physisches Audio und Bereitstellungspakete bleiben geplante Arbeiten.

Die Architektur ist ausgelegt für:

• macOS-, Linux- und Windows-Entwicklung

• Linux-amd64- und arm64-Bereitstellung

• Docker-Compose- und native systemd-Bereitstellung

• Mock-Modus ohne Hardware oder externe Dienstanmeldedaten

Related MCP server: Pipecat MCP Server

Anforderungen

• Node.js 22.12 oder neuer

• pnpm 10.27

Schnellstart

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

Öffnen Sie http://127.0.0.1:3000, erstellen Sie das erste Administratorpasswort, melden Sie sich an und verwenden Sie Chat. Geben Sie Check the light status ein, um den Mock-LLM -> Mock-MCP -> Mock-LLM-Ablauf auszuführen.

Die Chat-Seite bietet außerdem die Steuerelemente Aufnahme starten, Aufnahme stoppen und Antwort abspielen. Im Mock-Modus wird aufgenommenes Audio validiert, in einen deterministischen Testausdruck transkribiert, über Agent Core und Mock-MCP verarbeitet und mit einer generierten Test-WAV zurückgegeben.

Verwenden Sie Einstellungen, um das Administratorpasswort zu ändern oder Chat zwischen Mock und Azure OpenAI umzuschalten. Azure OpenAI erfordert einen HTTPS-Endpunkt, einen Bereitstellungsnamen, eine API-Version und einen API-Schlüssel. Der API-Schlüssel wird in der lokalen SQLite-Datenbank gespeichert, niemals an den Browser zurückgegeben und durch Dateisystemberechtigungen des Hosts geschützt.

Der LLM-Anbieter kann auch eine OpenAI-kompatible API verwenden. Konfigurieren Sie für Alibaba Cloud Model Studio die Basis-URL der Region/des Arbeitsbereichs, den API-Schlüssel und den Modellnamen wie qwen-plus.

Alibaba-Cloud-Sprache verwendet den dedizierten Alibaba Cloud Model Studio-STT/TTS-Anbieter, nicht die OpenAI-kompatible Audio-API. Konfigurieren Sie den WebSocket-Endpunkt des Arbeitsbereichs, den API-Schlüssel, das Echtzeit-ASR- oder TTS-Modell, die Sprache und die Stimme unabhängig für STT und TTS.

Verwenden Sie den Sprachwähler bei der Einrichtung, Anmeldung oder in den Einstellungen, um zwischen Englisch und vereinfachtem Chinesisch zu wechseln. Die Präferenz wird im Browser gespeichert und sofort angewendet.

Verwenden Sie den Erscheinungsbild-Wähler in den Einstellungen, um Hell, Dunkel oder System zu wählen. System ist die Standardeinstellung und folgt Live-Änderungen des Betriebssystem-Designs.

Für Frontend- und Backend-Entwicklung mit automatischem Neuladen:

pnpm dev

Die Web-Konsole ist unter http://127.0.0.1:5173 verfügbar und leitet API-Anfragen an den Server auf Port 3000 weiter.

Web-Konsolenseiten verwenden stabile URLs wie /dashboard, /chat, /conversations, /conversations/<id>, /logs und /settings. Direktes Laden, Aktualisieren sowie Zurück- oder Vorwärtsnavigation im Browser werden unterstützt.

Konfiguration

Kopieren Sie die Werte aus .env.example in Ihre Umgebung oder Ihren Prozessmanager:

Das erste Administratorpasswort muss mindestens 10 Zeichen enthalten. Passwörter werden als gesalzene scrypt-Hashes gespeichert. Sitzungscookies sind HttpOnly und SameSite=Strict.

Das Ändern des Administratorpassworts widerruft jede aktive Sitzung. Azure-OpenAI-Einstellungen werden bei der nächsten Chat-Anfrage wirksam. Die Verbindungstest-Aktion sendet eine kleine Anfrage an die konfigurierte Bereitstellung und kann Anbieter-Nutzungskosten verursachen.

Validierung

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

Führen Sie alle erforderlichen Prüfungen aus mit:

pnpm validate

Playwright MCP

Die repository-weite .mcp.json konfiguriert Playwright MCP für die Browser-Untersuchung über strukturierte Barrierefreiheits-Snapshots. Copilot CLI und Claude Code erkennen diese Datei vom Repository-Stammverzeichnis aus, nachdem die Arbeitsbereichsvertrauensstellung genehmigt wurde.

Der Server verwendet die neueste offizielle Paketversion und isolierte Browsersitzungen, sodass Cookies und Anmeldestatus nicht zwischen MCP-Sitzungen beibehalten werden. Starten Sie den MCP-Client nach einer Konfigurationsänderung neu.

Standardtests und der Mock-Modus erfordern keine AI-Anmeldedaten, externen MCP-Server oder Audio-Hardware.

Arbeitsbereich

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

Dokumentation

• MVP-Entwicklungsspezifikation

• Implementierungsplan

• Verbindliche Entwicklungsregeln

• Technologiestack und Entwicklungsleitfaden

• Barrierefreiheitsstandard und Audit

• Mock-Modus-Entwicklungsleitfaden

• Azure-OpenAI-Konfigurationsleitfaden

• Alibaba-Cloud-Model-Studio-Anbieterplan

• Sprachpipeline-Architektur

Anweisungen für Coding-Agenten

• Gemeinsame und Codex-Anweisungen

• Claude-Code-Anweisungen

• GitHub-Copilot-Anweisungen

Entwicklungspolitik

Bevor Sie eine funktionale Änderung implementieren:

1. Besprechen und bestätigen Sie deren Verhalten, Umfang, Risiken, Abnahmekriterien und Testanforderungen.

2. Erstellen Sie einen dedizierten Branch vom neuesten main; bearbeiten oder pushen Sie niemals direkt auf main.

3. Halten Sie sämtliche Repository-Inhalte und Code-Kommentare auf Englisch.

4. Fügen Sie vollständige Unit-, gegebenenfalls Integrations- und End-to-End-Tests hinzu.

5. Fügen Sie englische Entwicklerdokumentation und nützliche JSDoc- oder Begründungskommentare für öffentliche Verträge, Konfiguration, Architektur, Sicherheitseinschränkungen und nicht offensichtliches Verhalten hinzu.

6. Führen Sie alle zutreffenden Format-, Lint-, Typprüfungs-, Test- und Produktions-Build-Prüfungen aus.

7. Verwenden Sie Commit-Nachrichten und PR-Titel im Conventional-Commit-Stil und teilen Sie nicht zusammenhängende Änderungen in fokussierte Commits auf.

8. Holen Sie vor dem Committen, Pushen, Erstellen eines Pull-Requests, Zusammenführen oder Veröffentlichen eine separate ausdrückliche Genehmigung ein.

Die vollständige verbindliche Politik finden Sie unter Entwicklungsregeln.