VoxMesh

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 dev

Web 控制台可通过 http://127.0.0.1:5173 访问，并将 API 请求代理到 3000 端口上的服务器。

Web 控制台页面使用稳定的 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 配置后，请重启 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

文档

• MVP 开发规范

• 实施计划

• 强制开发规则

• 技术栈与开发指南

• 无障碍标准与审计

• Mock 模式开发指南

• Azure OpenAI 配置指南

• 阿里云百炼提供商计划

• 语音流水线架构

编码代理说明

• Shared 和 Codex 说明

• Claude Code 说明

• GitHub Copilot 说明

开发政策

在实施任何功能变更之前：

1. 讨论并确认其行为、范围、风险、验收标准和测试要求。

2. 从最新的 main 分支创建专用分支；绝不直接编辑或推送到 main。

3. 保持所有仓库内容和代码注释为英文。

4. 添加完整的单元测试、适用的集成测试和端到端测试。

5. 添加英文开发者文档，并为公共契约、配置、架构、安全约束和非显而易见的逻辑编写有用的 JSDoc 或推理注释。

6. 运行所有适用的格式检查、代码检查、类型检查、测试和生产构建检查。

7. 使用 Conventional Commit 风格的提交信息和 PR 标题，并将不相关的更改拆分为独立的提交。

8. 在提交、推送、创建拉取请求、合并或发布之前，需获得明确的单独批准。

完整的强制性政策请参阅 开发规则。