AI导哈

语音控制智能家居界面

通过渐进式Web应用（PWA）和Node.js后端实现Control4智能家居系统的语音控制接口，通常部署在群晖NAS上并调用c4-mcp HTTP服务器。

  • by randybritsch
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 randybritsch/c4-mcp-app

使用说明

C4 MCP应用程序-语音控制智能家居界面

通过Progressive Web App（PWA）+Node.js后端实现Control4自动化的语音控制智能家居界面，通常部署在Synology NAS上并调用 c4-mcp HTTP服务器。

不可协商的规则

  1. c4-mcp 必须始终与 c4-mcp-app.
  • 边界仅为HTTP(C4_MCP_BASE_URL)，没有共享代码。
  1. 双子座（人工智能）做出决定； c4-mcp 执行。
  • 后端解释用户命令（意图→ 工具选择→ args）使用Gemini。
  • 然后后端调用 c4-mcp 执行计划的工具。

项目结构

c4-mcp-app/
├── backend/                 # Node.js backend service
│   ├── src/
│   │   ├── config/         # Configuration management
│   │   ├── middleware/     # Express middleware
│   │   ├── routes/         # API routes
│   │   ├── services/       # Business logic (STT, LLM, MCP)
│   │   ├── utils/          # Utilities (logger, errors)
│   │   ├── app.js          # Express app setup
│   │   ├── server.js       # Server entry point
│   │   └── websocket.js    # WebSocket server
│   ├── scripts/            # Deployment and utility scripts
│   ├── package.json
│   ├── .env.example
│   └── README.md
│
├── frontend/                # PWA frontend
│   ├── css/                # Stylesheets
│   ├── js/                 # JavaScript modules
│   ├── icons/              # PWA icons (generate these)
│   ├── index.html
│   ├── manifest.json       # PWA manifest
│   └── service-worker.js   # Service worker
│
├── docs/                    # Comprehensive documentation
│   ├── architecture.md
│   ├── project_overview.md
│   ├── bootstrap_summary.md
│   ├── conventions_guardrails.md
│   ├── modules/
│   ├── api/
│   ├── data/
│   ├── ops/
│   └── ...
│
└── scripts/                 # Deployment scripts
    ├── deploy-backend.sh
    └── deploy-frontend.sh

快速开始

先决条件

  • Synology DS218+ DSM 7.x
  • Node.js v22 （通过Synology软件包中心安装）
  • API密钥：
    • Google Cloud STT API或Azure语音服务
    • OpenAI API（使用 gpt-4o-mini)
    • 已配置并可访问Control4 MCP（c4 MCP）

后端设置

cd backend
npm install
# First run only (avoid overwriting an existing .env)
test -f .env || cp .env.example .env
# Edit .env with your API keys / endpoints
npm start

前端设置

只需将前端文件复制到Synology Web Station目录：

# See scripts/deploy-frontend.sh for detailed instructions

发展模式

# Backend (with auto-reload)
cd backend
npm run dev

# Frontend
# Serve frontend/ directory with any static file server
# or open index.html directly in browser

测试

cd backend
npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

部署到Synology DS218+

请参阅详细的部署说明：

笔记：

  • 当前参考部署使用 Synology容器管理器 使用Docker Compose项目（请参见 compose.nas.yaml).
  • 后端与 c4-mcp 作为一个独立的HTTP服务，通过 C4_MCP_BASE_URL （无需共享代码）。
  • 此设置中的典型LAN端口：
    • 后端： http://<NAS_IP>:3002
    • c4 mcp： http://<NAS_IP>:3334

API文档

  • REST API： 看 docs/api/endpoints.md
  • Websocket： 实时流式语音命令 /ws?token=...
  • 身份验证： JWT令牌（集 JWT_EXPIRY=never 非到期）

建筑

  • 前端： 带MediaRecorder API的PWA，用于语音捕获
  • 后端： Node.js Express服务编排：
    1. 语音转文本（Google/AAzure）
    2. 意图解析（OpenAI；用 gpt-4o-mini)
    3. 命令执行（通过控制4 MCP c4-mcp HTTP）
  • 消除歧义的用户体验： 当Control4名称解析不明确时（例如，多个“地下室”房间），UI会提示选择并确定性地重试。
  • 部署： Synology容器管理器（Docker Compose）是参考设置；本机进程部署也是可能的。

主要特点

✅ 语音控制智能家居命令
✅ 实时WebSocket流媒体
✅ 首次离线PWA，配备Service Worker
✅ JWT身份验证
✅ 使用Winston进行结构化日志记录
✅ 全面的错误处理
✅ 互动消歧（“哪个地下室？”）
✅ 速率限制和安全
✅ 80%+测试覆盖率

文档

完整的文档可在 /docs 文件夹：

贡献

这是Control4家庭自动化的个人项目。看 文档/约定_护栏.md 用于编码标准。

许可证

麻省理工学院

作者

Randy Britsch

技术栈： Node.js v22、Express.js、WebSocket、PWA（HTML/CSS/js）、Google/AAzure STT、OpenAI(gpt-4o-mini)，控制4 MCP(c4-mcp)
平台： Synology DS218+（2GB内存，双核Realtek RTD1296）
部署： Synology容器管理器（Docker Compose）。原生Synology工具（Web Station/任务调度器）是传统的。

相关 MCP