VoxMesh

VoxMesh는 플랫폼 독립적인 음성 우선 AI 에이전트 게이트웨이입니다.

이 프로젝트는 음성 입력, 음성-텍스트 변환, AI 에이전트, MCP 도구, 텍스트-음성 변환, 음성 출력을 연결하면서 Agent Core를 하드웨어, 운영 체제, AI 제공업체로부터 독립적으로 유지하도록 설계되었습니다.

프로젝트 상태

VoxMesh는 개발 및 아키텍처 검증을 위한 초기 Mock Mode 수직 슬라이스를 보유하고 있습니다. 여기에는 다음이 포함됩니다:

• pnpm 및 TypeScript 모노레포

• Fastify 서버 및 React Web Console

• 최초 실행 관리자 비밀번호 설정 및 세션 인증

• SQLite 대화 및 로그 영속화

• 제공업체 독립적인 Agent Core 계약

• 결정적 Mock LLM 및 Mock MCP 도구 실행

• Mock STT 및 생성된 WAV 응답을 포함한 브라우저 Mock Voice 녹음

• 선택 가능한 Composed 및 Mock Native Multimodal 음성 파이프라인 모드

• Dashboard, Chat, Conversations, Logs 페이지

• 비밀번호 변경 및 Mock/Azure OpenAI 구성을 위한 Settings 페이지

• 쓰기 전용 Azure OpenAI API 키 처리 및 연결 테스트

• Alibaba Cloud Model Studio를 포함한 일반 OpenAI 호환 LLM 구성

• 영문 및 중국어 간체 Web Console 현지화

• 브라우저 언어 감지 및 유지되는 언어 선택

• Light, Dark, System 표시 모드

• 운영 체제 실시간 동기화와 함께 유지되는 표시 선택

• 기능 중심의 단일 목적 React 컴포넌트

• 모든 현재 UI 컴포넌트에 대한 React Testing Library 동작 테스트

• Browser History 및 딥링크 가능한 페이지를 갖춘 TanStack Router

• 원격 서버 상태 및 캐시 무효화를 위한 TanStack Query

• 복잡한 Settings 워크플로우를 위한 TanStack Form

• 단위, 통합, 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 제공업체는 OpenAI 호환 API를 사용할 수도 있습니다. Alibaba Cloud Model Studio의 경우 지역/워크스페이스 기본 URL, API 키, qwen-plus와 같은 모델 이름을 구성하세요.

Alibaba Cloud 음성은 OpenAI 호환 Audio API가 아닌 전용 Alibaba Cloud Model Studio STT/TTS 제공업체를 사용합니다. 워크스페이스 WebSocket 엔드포인트, API 키, 실시간 ASR 또는 TTS 모델, 언어, 음성을 STT와 TTS에 대해 각각 독립적으로 구성하세요.

설정, 로그인 또는 Settings에서 언어 선택기를 사용하여 영어와 중국어 간체 사이를 전환하세요. 기본 설정은 브라우저에 저장되며 즉시 적용됩니다.

Settings의 표시 선택기를 사용하여 Light, Dark, System 중에서 선택하세요. System이 기본값이며 운영 체제 테마 변경을 실시간으로 따릅니다.

자동 리로드가 포함된 프론트엔드 및 백엔드 개발의 경우:

pnpm dev

Web Console은 http://127.0.0.1:5173에서 사용할 수 있으며 API 요청을 포트 3000의 서버로 프록시합니다.

Web Console 페이지는 /dashboard, /chat, /conversations, /conversations/<id>, /logs, /settings와 같은 안정적인 URL을 사용합니다. 직접 로드, 새로고침, 브라우저 뒤로/앞으로 탐색이 지원됩니다.

구성

.env.example 값을 환경 또는 프로세스 관리자에 복사하세요:

첫 번째 관리자 비밀번호는 최소 10자 이상이어야 합니다. 비밀번호는 솔티드 scrypt 해시로 저장됩니다. 세션 쿠키는 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는 워크스페이스 신뢰가 승인된 후 저장소 루트에서 이 파일을 발견합니다.

서버는 최신 공식 패키지 릴리스와 격리된 브라우저 세션을 사용하므로 쿠키와 로그인 상태가 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에 직접 편집하거나 푸시하지 마세요.

3. 모든 저장소 콘텐츠와 코드 주석을 영어로 유지하세요.

4. 완전한 단위 테스트, 해당되는 경우 통합 테스트, 엔드투엔드 테스트를 추가하세요.

5. 공개 계약, 구성, 아키텍처, 보안 제약 조건, 비자명한 동작에 대한 영문 개발자 문서와 유용한 JSDoc 또는 추론 주석을 추가하세요.

6. 모든 해당 형식, 린트, 타입 검사, 테스트, 프로덕션 빌드 검사를 실행하세요.

7. Conventional Commit 스타일의 커밋 메시지와 PR 제목을 사용하고, 관련 없는 변경 사항을 집중된 커밋으로 분리하세요.

8. 커밋, 푸시, 풀 리퀘스트 생성, 병합, 릴리스 전에 별도의 명시적 승인을 받으세요.

전체 필수 정책은 개발 규칙을 참조하세요.