VoxMesh 是一个与平台无关的、以语音为先的 AI 代理网关。
该项目旨在连接语音输入、语音转文本、AI 代理、MCP 工具、文本转语音和语音输出，同时保持 Agent Core 与硬件、操作系统和 AI 提供商无关。
VoxMesh 拥有一个用于架构验证的初始 Mock 模式垂直切片。它包括：
一个 pnpm 和 TypeScript monorepo
一个 Fastify 服务器和 React Web 控制台
首次运行的管理员密码设置和会话认证
SQLite 会话和日志持久化
与提供商无关的 Agent Core 契约
确定性的 Mock LLM 和 Mock MCP 工具执行
浏览器 Mock 语音录制，带 Mock STT 和生成的 WAV 响应
可选择的 Composed 和 Mock Native Multimodal 语音流水线模式
Dashboard、Chat、Conversations 和 Logs 页面
用于密码轮换和 Mock/Azure OpenAI 配置的 Settings 页面
只写的 Azure OpenAI API 密钥处理和连接测试
通用的 OpenAI 兼容 LLM 配置，包括阿里云百炼
英文和简体中文 Web 控制台本地化
浏览器语言检测和持久化的语言选择
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 模式
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 模式下，录制的音频会被验证，转写为确定性的测试短语，经 Agent Core 和 Mock MCP 处理后，返回一个生成的测试 WAV 文件。
使用 Settings 更改管理员密码，或在 Mock 和 Azure OpenAI 之间切换 Chat。Azure OpenAI 需要 HTTPS 端点、部署名称、API 版本和 API 密钥。API 密钥存储在本地 SQLite 数据库中，绝不会返回给浏览器，并受主机文件系统权限保护。
LLM 提供商也可以使用兼容 OpenAI 的 API。对于阿里云百炼，请配置区域/工作空间基础 URL、API 密钥和模型名称，例如 qwen-plus。
阿里云语音使用专用的 阿里云百炼 STT/TTS 提供商，而非兼容 OpenAI 的 Audio API。请为 STT 和 TTS 分别配置工作空间 WebSocket 端点、API 密钥、实时 ASR 或 TTS 模型、语言和语音。
在设置、登录或 Settings 页面使用语言选择器，可在英文和简体中文之间切换。语言偏好存储在浏览器中并立即生效。
在 Settings 页面使用外观选择器，可选择 Light、Dark 或 System。System 为默认选项，并实时跟随操作系统主题变化。
对于前端和后端开发，均支持自动重载：
pnpm devWeb 控制台可通过 http://127.0.0.1:5173 访问，并将 API 请求代理到 3000 端口上的服务器。
Web 控制台页面使用稳定的 URL，例如 /dashboard、/chat、/conversations、/conversations/<id>、/logs 和 /settings。支持直接加载、刷新以及浏览器前进/后退导航。
将 .env.example 中的值复制到你的环境或进程管理器中：
变量 | 默认值 | 描述 |
|
| 服务器监听地址 |
|
| 服务器监听端口 |
|
| SQLite 数据库路径 |
|
| 管理员会话有效期 |
|
| 要求会话 Cookie 使用 HTTPS |
首个管理员密码必须至少包含 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仓库级别的 .mcp.json 为 Playwright MCP 配置了浏览器调查功能，通过结构化的无障碍快照进行。Copilot CLI 和 Claude Code 会在工作区信任批准后，从仓库根目录发现此文件。
服务器使用最新的官方软件包版本和隔离的浏览器会话，因此 Cookie 和登录状态不会在 MCP 会话之间保留。更改 MCP 配置后，请重启 MCP 客户端。
默认测试和 Mock 模式不需要任何 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在实施任何功能变更之前：
讨论并确认其行为、范围、风险、验收标准和测试要求。
从最新的 main 分支创建专用分支；绝不直接编辑或推送到 main。
保持所有仓库内容和代码注释为英文。
添加完整的单元测试、适用的集成测试和端到端测试。
添加英文开发者文档，并为公共契约、配置、架构、安全约束和非显而易见的逻辑编写有用的 JSDoc 或推理注释。
运行所有适用的格式检查、代码检查、类型检查、测试和生产构建检查。
使用 Conventional Commit 风格的提交信息和 PR 标题，并将不相关的更改拆分为独立的提交。
在提交、推送、创建拉取请求、合并或发布之前，需获得明确的单独批准。
完整的强制性政策请参阅 开发规则。
This server cannot be deployed
Human-input bridge for AI agents with voice-first answer links, MCP tools, and HTTP APIs.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Command your AI agents by voice: PTT rooms, channels, direct messages, agent email, memory (mRAG).
AI voice generation: text-to-speech and voice cloning from any MCP client.
