# apex-controller

**Repository Path**: freen/apex-controller

## Basic Information

- **Project Name**: apex-controller
- **Description**: APEX 智能体中控系统充当智能体服务商与智能体设备中间衔接层，已打通通信、控制、安全完整链路；适配 apex-esp32-s3-v6 固件，无需复杂软件开发，快速搭建带认证、权限、指令锁、优先级机制的智能体操控硬件，一天出原型、一周落地量产。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-12
- **Last Updated**: 2026-06-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# APEX 智能体中控系统

> **APEX 底层框架 + 智能体中控** —— 一天搭建原型，一周产品落地的智能体设备开发体系  
> 配合 APEX 底层固件框架（如 [`apex-esp32-s3-v6`](https://gitee.com/freen/apex-esp32-s3-v6)），快速打造可由豆包/千问/元宝等顶流 AI App 操控的智能设备

[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Architecture](https://img.shields.io/badge/Architecture-MCP%20Standard-orange.svg)](https://modelcontextprotocol.io/)
[![Protocol](https://img.shields.io/badge/Protocol-MQTT%2FWebSocket-green.svg)](https://mqtt.org/)
[![Security](https://img.shields.io/badge/Security-AES--256%2BRBAC%2B指令锁-red.svg)]()
[![Platform](https://img.shields.io/badge/Platform-APEX%20Framework-blue.svg)]()

---

## 目录

- [APEX 中控是什么？](#apex-中控是什么)
- [为什么需要 APEX 中控？](#为什么需要-apex-中控)
- [系统架构](#系统架构)
  - [云端智能体服务模式](#云端智能体服务模式)
  - [本地智能体服务模式](#本地智能体服务模式)
- [十大核心能力](#十大核心能力)
- [技术栈](#技术栈)
- [项目目录结构](#项目目录结构)
- [设备接入](#设备接入)
- [核心模块详解](#核心模块详解)
- [项目定位与扩展性](#项目定位与扩展性)

---

## APEX 中控是什么？

**APEX 智能体中控系统** 充当智能体服务商与智能体设备之间的**中间衔接层**，已打通通信、控制、安全完整链路；适配 [`apex-esp32-s3-v6`](https://gitee.com/freen/apex-esp32-s3-v6) 固件，无需复杂软件开发，快速搭建带认证、权限、指令锁、优先级机制的智能体操控硬件，一天出原型、一周落地量产。

> **通俗地说**：AI App（豆包、千问、元宝等）想控制你的智能设备，但不懂你的设备协议；你的设备能联网，但不懂 AI 的意图。APEX 中控就是二者之间的"翻译官 + 调度中心 + 安全管家"。

**四大安全基石**：

| 能力 | 说明 |
|------|------|
| **身份认证** | 智能体/用户/设备三级身份绑定，精准识别指令归属 |
| **权限管控** | 管理员/用户/访客多级 RBAC，指令级权限校验，越权自动拦截 |
| **指令锁** | 设备状态锁定 + 指令槽位管理，防止并发冲突，独占操作互斥保护 |
| **指令优先级** | FORCE 紧急指令（急停/断电保护）优先执行，ALWAYS_ALLOWED 只读查询不受限 |

**核心定位**：
- 对**智能体服务商**：无须对接海量物联网设备、无须关心物联网生态壁垒，只需提供基础智能体能力（如 MCP 接口、知识库能力），即可让用户拥有控制智能设备的能力
- 对**物联网设备厂商**：无须搭建智能体团队、无须开发 App，只需要关心你的硬件业务，你的用户即可通过豆包、千问、元宝等顶流 AI App 入口，直接控制你的硬件设备
- 对**终端用户**：拥有更加安全、便捷的智能体验 —— 密钥安全、权限安全、指令安全，全程无忧

> **智连物联网**：在获得具体物联网生态授权的情况下，这套体系也能快速兼容物联网设备，实现「智连物联网」的目标。

---

### 官方QQ群

入群答案：`APEX智能体设备`

| 群名称 | 群号 |
|--------|------|
| 官方1群 | 882419824 |

## 为什么需要 APEX 中控？

当前大模型、各类智能体服务商快速发展，同时物联网行业历经数十年迭代，生态成熟、架构稳固。两大体系存在**天然融合壁垒**：

| 壁垒 | 问题 | APEX 中控解决 |
|------|------|--------------|
| **协议鸿沟** | 智能体不懂 MQTT/CoAP/Zigbee，设备不懂自然语言 | 中控统一翻译，双向语义转换 |
| **时延冲突** | 大模型推理慢（秒级），设备控制要求快（毫秒级） | 分层解耦，实时控制本地兜底 |
| **安全真空** | 老旧设备无密钥、无权限，直接暴露给 AI 风险极高 | 中控统一托管密钥、校验权限、拦截非法指令 |
| **场景割裂** | 家居、办公、工业协议各异，智能体需重复适配 | 场景化物模型 + MCP 标准接口，一次接入全场景通用 |
| **离线失控** | 断网后云端智能体无法操控设备 | 本地直控 + 边缘智能体，断网不断控 |

### 核心优势

1. **🔗 智连物联网** — 在获得物联网生态授权的情况下，快速兼容物联网协议，实现「智连物联网」的目标
2. **🛡️ 全链路安全** — 密钥托管、权限隔离、指令风控、防篡改防重放，构建安全闭环
3. **📦 架构通用** — 标准化 MCP 接口 + 场景化物模型，横向拓展至家居、办公、工业
4. **⚡ 权责清晰** — 分层设计隔离实时控制与高层决策，规避大模型性能短板带来的风险

---

## 系统架构

APEX 中控系统支持两种智能体服务模式，满足不同网络环境下的设备控制需求：

### 云端智能体服务模式

适用于需要远程控制、跨网络访问的场景，设备通过 MQTT 与云端智能体服务保持长连接。

```
┌────────────────────────────────────────────────────────────────────────────┐
│                           用户交互层                                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                                  │
│  │  豆包 App │  │ 千问 App │  │  元宝 App │  ← 用户通过 AI App 发送语音/文字指令 │
│  └──────────┘  └──────────┘  └──────────┘                                  │
└────────────────────────────────────────────────────────────────────────────┘
                      │← AI 理解用户意图，转换为标准化设备指令
        ┌─────────────▼─────────────┐
        │   agent-plat.com 指令转发   │
        └─────────────┬─────────────┘
                      │
        ┌─────────────▼─────────────┐
        │                           │  ← 隔离密钥与敏感信息
        │      智能体中控平台设备      │    智能体权限验证
        │                           │    指令锁 / 指令优先级验证
        └─────────────┬─────────────┘
                      │ MQTT
        ┌─────────────▼─────────────┐
        │      设备端 (ESP32-S3)     │
        │  ┌─────────────────────┐  │
        │  │   apex_cmd_executor │  │  ← 指令解密、解析、分发、执行、响应
        │  │    (指令调度中枢)     │  │
        │  └─────────────────────┘  │
        │  ┌─────────────────────┐  │
        │  │    业务模块组件       │  │  ← 电机控制、传感器读取、LED 驱动等
        │  │   (Components)      │  │
        │  └─────────────────────┘  │
        │  ┌─────────────────────┐  │
        │  │  WiFi / MQTT / OTA  │  │  ← 网络连接、远程通信、固件升级
        │  │   (Infrastructure)  │  │
        │  └─────────────────────┘  │
        └───────────────────────────┘
                      │
        ┌─────────────▼─────────────┐
        │        硬件外设            │  ← GPIO、I2C、SPI、PWM、ADC 等
        │    (Peripherals)          │
        └───────────────────────────┘
```

**流程说明**：
1. 用户在豆包/千问/元宝 App 中通过自然语言发出控制指令（如"打开客厅的灯"）
2. 云端智能体服务解析用户意图，转换为 APEX 标准指令格式，通过 MCP 接口 下发至智能体中控平台
3. 智能体中控平台验证指令合法性，智能体权限，指令权限后，将指令分发至设备端
4. 设备端 `apex_cmd_executor` 接收加密指令，解密、解析后匹配对应业务 handler
5. 业务模块执行硬件操作，结果通过 MQTT 同步给智能体中控，智能体中控将结果同步回传云端，App 实时反馈执行状态

---

### 本地智能体服务模式

适用于局域网内控制、隐私敏感或断网场景，设备内置 Web 服务提供本地智能体交互能力。

```

        ┌───────────────────────────┐
        │    本地智能体服务系统        │  ← 本地 Agent 引擎，意图识别，指令下发
        │   (Local Agent Service)   │
        └─────────────┬─────────────┘
                      │ COMMAND
        ┌─────────────▼─────────────┐
        │                           │  ← 隔离密钥与敏感信息
        │     智能体中控平台系统设备    │    智能体权限验证
        │                           │    指令锁 / 指令优先级验证
        └─────────────┬─────────────┘
                      │ MQTT
        ┌─────────────▼─────────────┐
        │      设备端 (ESP32-S3)     │
        │  ┌─────────────────────┐  │
        │  │   apex_cmd_executor │  │  ← 本地指令解析与调度   
        │  │    (指令调度中枢)     │  │
        │  └─────────────────────┘  │
        │  ┌─────────────────────┐  │
        │  │    业务模块组件       │  │  ← 电机控制、传感器读取、LED 驱动等     
        │  │   (Components)      │  │
        │  └─────────────────────┘  │
        │  ┌─────────────────────┐  │
        │  │  WiFi Manager (AP)  │  │  ← AP 模式配网，或 STA 连接路由器       
        │  └─────────────────────┘  │
        └───────────────────────────┘
                      │
        ┌─────────────▼─────────────┐
        │        硬件外设            │  ← GPIO、I2C、SPI、PWM、ADC 等
        │    (Peripherals)          │
        └───────────────────────────┘
```

**流程说明**：
1. 用户向本地智能体发出自然语言指令
2. 本地智能体通过工具向智能体中控发出解析后的指令
3. 中控经过身份校验、权限校验、指令安全校验后，向设备发送指令
4. 设备执行结果通过中控回传至本地智能体，反馈给用户
5. 全程数据不离开本地网络，断网场景下设备依然可控，隐私安全有保障

---

## 十大核心能力

### 1. 时延与时序冲突解决

**分层解耦，各司其职**：
- **物联网底层**：全权负责毫秒级实时控制、应急安全处置（如燃气熄火断气、设备异常停机），本地规则直接执行，不依赖上层智能体，兜底各类实时风险
- **智能体 / 大模型层**：仅负责人意图理解、全局规划、复杂任务编排等非强实时工作。即便大模型存在推理延迟，也不会引发设备安全事故

### 2. 异构设备数据语义转换

依托中控系统 + **场景化物模型** 完成数据标准化：
- 设备接入后，系统基于统一功能模型，将原生设备物模型自动转换为标准 JSON 对象
- 以切片形式存入智能体知识库，完成物联网原始数据到智能体可识别语义数据的翻译
- **屏蔽设备数据格式差异**，智能体无需关心设备品牌、协议、数据格式

### 3. 设备执行状态同步

通过**同步指令、异步指令双模式**闭环管理：
- **同步指令**：下发后即时获取设备执行结果，状态实时同步
- **异步指令**：中控先反馈指令下发成功，设备完成 / 失败后主动回传状态，由中控二次同步至智能体，全流程可追溯

### 4. 离线 / 云端故障适配（边缘容灾）

搭建**本地直控 + 边缘轻量化智能体**双重保障：
- 中控原生具备设备操控能力，断网、云端智能体离线时，可直接下发开关等简单指令
- 复杂指令可搭配本地智能体服务，实现自然语义理解、解析指令后下发至中控设备，全程不依赖云端

### 5. 老旧无安全底座设备兼容

**无需改造硬件，在平台层补齐安全能力**：
- 针对无密钥、无权限体系的传统存量设备，由中控统一分配密钥、搭建权限体系
- 所有下行指令均经过中控拦截与校验，杜绝非法操控，为老旧设备补上安全屏障

### 6. 多级权限与身份隔离

**密钥统一由中控托管**，智能体仅负责意图解析与指令发起，全权限管控收敛至中控：
- 智能体与用户绑定，系统可精准识别指令归属主体
- 预设管理员、普通用户，匹配不同操作权限
- 指令下发时依次校验智能体身份、所属用户、权限等级，实现**设备、多智能体、多用户三层隔离**，自动拦截越权操作

### 7. 指令全链路安全防护

| 防护维度 | 机制 |
|----------|------|
| **防篡改** | 采用 AES-256 高阶密钥加密，对指令时间、长度等核心字段做加密保护 |
| **防重放** | 基于 MQTT 架构，叠加时间戳 + 随机串、全局指令序号、专属会话绑定三重规则；搭配消息哈希摘要二次校验 |
| **行为风控** | 设备行为规则校验，指令留存日志 |

### 8. 标准化接口解耦（MCP）

规避重复协议适配工作：
- 平台自建**场景化设备方法模型**，不同于传统物联网模型，在物联网生态授权的情况下，该模型可基于物联网协议进行二次封装，实现「智连物联网」
- 为所有设备提供标准化接入能力，封装结果同步至知识库
- 实现架构解耦，不用针对不同设备、协议重复定制开发

### 9. 链路异常降级与容错

按故障类型分级处理：
- **云端 / 智能体断线**：本地方案无须联网，用户可通过标准化操作界面向设备直接下发指令，不受云端状态影响
- **局域网单设备离线**：中控实时检测设备状态，同步告知智能体并禁止对该设备下发指令
- **配套优化**：增加心跳检测、告警、日志记录

### 10. 多场景适配（家居 / 办公 / 工业）

基于**场景化物模型 + 分层架构**，一套系统适配全场景需求：
- **场景定制**：划分家居、办公、工业等专属智能体，由场景使用者定义智能体业务规则与工作范围，实现专业化分工
- **能力分层**：工业等高要求场景的低时延、高安全需求，依旧由物联网底层承载；智能体仅负责上层调度，统一架构无需针对场景重构，兼顾通用性与场景专业性

---

## 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| 开发语言 | **C** | 智能体设备核心逻辑使用 C 语言实现 |
| 核心架构 | **事件驱动 + 分层解耦** | 实时控制与高层决策分离，状态流转、指令调度解耦高效 |
| 通信协议 | **MQTT over TLS** | 设备长连接通信，加密传输 |
| 本地服务 | **HTTP / WebSocket / mDNS** | 局域网设备发现、本地配置与指令下发 |
| 数据格式 | **JSON (cJSON)** | 指令参数解析、响应数据构造、物模型标准化 |
| 安全机制 | **AES-256 + RBAC + 防重放** | 高阶加密、角色权限、时间戳随机串、全局序号 |
| 标准接口 | **MCP (Model Context Protocol)** | 统一协议封装，智能体即插即用 |
| 边缘智能 | **轻量化 LLM / 规则引擎** | 本地意图解析，离线场景决策 |
| 知识库 | **向量数据库 + 物模型切片** | 设备能力语义化存储，智能体实时检索 |


> 配套智能体设备项目：[`apex-esp32-s3-v6`](https://gitee.com/freen/apex-esp32-s3-v6) — 智能体设备底层固件框架 具体点击连接查看

---

## 项目目录结构

项目采用**分层模块化设计**，各目录职责独立、边界清晰：

```
apex-central-control/
├── main/
│   └── main.c                          # 程序启动入口，统一初始化各模块
│
├── apex_frame/                         # 核心功能模块（核心层）
│   ├── apex_cmd_executor/              # 指令执行引擎 — 系统核心调度中枢
│   │   ├── include/
│   │   │   └── apex_cmd_executor.h
│   │   ├── apex_cmd_executor.c
│   │   └── CMakeLists.txt
│   ├── apex_thing_model/               # 设备物模型转换器 — 异构数据语义标准化
│   ├── apex_identity/                  # 权限与身份中心 — RBAC、多级账号、指令归属
│   ├── apex_security/                  # 安全网关 — 加密、防篡改、防重放、行为风控
│   ├── apex_mcp_gateway/               # MCP 标准接口 — 统一协议封装、知识库同步
│   ├── apex_edge_agent/                # 边缘智能体 — 轻量化本地决策、离线容灾
│   ├── apex_wifi_mgr/                  # 网络管理 — AP/STA 双模式、局域网发现
│   ├── apex_mqtt/                      # MQTT 通信 — 设备长连接、状态上报
│   ├── apex_web_server/                # Web 服务 — 本地配置、HTTP 指令下发
│   ├── apex_ota_update/                # OTA 升级 — 中控固件远程迭代
│   ├── apex_fault_tolerance/           # 容错降级 — 心跳检测、故障切换、自锁策略
│   └── apex_logger/                    # 日志中心 — 指令审计、异常告警、行为分析
│
├── common/                             # 通用基础组件（基础层）
│   ├── cjson/                          # JSON 解析与封装库
│   ├── crypto/                         # 加密解密模块（AES-256、哈希、随机串）
│   ├── utils/                          # 通用工具函数库
│   └── vector_db/                      # 向量数据库接口 — 物模型语义存储
│
├── components/                         # 业务示例组件（应用层）
│   ├── sync_add/                       # 同步指令开发示例
│   └── async_add/                      # 异步指令开发示例
│
└── build/                              # 编译输出目录
```

### 目录职责说明

| 目录 | 层级 | 职责 |
|------|------|------|
| `apex_frame/` | **核心层** | 中控核心能力底座，所有基础功能独立封装为子模块 |
| `common/` | **基础层** | 全局通用工具与依赖库，为业务模块提供基础能力支撑 |
| `components/` | **应用层** | 官方标准开发示例，指导开发者快速开发自定义业务模块 |
| `main/` | **入口层** | 程序启动入口，负责模块初始化顺序管理 |

---

## 设备接入

1. 智能体设备接入本地网络后，动态获取 IP 地址
2. 在浏览器中访问 mDNS 地址：[`agent-plat.local`](http://agent-plat.local) 进入控制台
3. 使用默认账号登录（用户名：`admin`，密码：`admin123`）
4. 进入控制台后可进行网络配置、设备管理、权限设置等详细操作
5. 详细操作视频（发布后可访问）：`[视频链接预留]`

---

## 核心模块详解

### 指令执行引擎 (apex_cmd_executor)

`apex_cmd_executor` 是整个中控系统的**指令调度核心、业务执行中枢**。所有云端/本地指令均通过该模块完成**解密 → 解析 → 分发 → 执行 → 响应**全流程。


## 项目定位与扩展性

### 当前项目定位

**APEX 智能体中控系统** 定位为智能体与物联网的**中间衔接层**，专为以下场景设计：

- **智能家居** — 灯具、插座、窗帘、空调、安防等全屋智能中控
- **智慧办公** — 会议室设备、工位环境、门禁考勤等办公场景集中控制
- **工业物联网** — PLC、传感器、执行器等工业设备的安全智能调度

> **两种落地方式**：① 在**物联网生态授权**下，通过标准化物模型快速对接现有生态设备；② 在**未获授权**时，基于 APEX 中控的**开源自建场景化模型**能力，独立搭建智能体控制体系，无需依赖封闭生态。

### 框架扩展性

APEX 中控设计为**平台无关、协议无关**的通用架构：

| 当前实现 | 可扩展目标 |
|----------|-----------|
| 嵌入式中控（ESP32-S3 等） | 边缘服务器（ARM/x86 Linux）、云端集群（K8s 微服务） |
| MQTT 协议 | 扩展 CoAP、HTTP/3、Zigbee、Matter、Modbus 等 |
| 豆包/千问/元宝 | ChatGPT、Claude、Gemini、文心一言等更多 AI 平台，以及 LLaMA、Qwen 等开源模型自建智能体 |
| 家居场景 | 办公、工业、农业、医疗等全场景适配 |

### 与 APEX 硬件框架的关系

| 项目 | 定位 | 关系 |
|------|------|------|
| [`apex-esp32-s3-v6`](https://gitee.com/freen/apex-esp32-s3-v6) | **智能体设备底层框架** | 设备端固件，负责硬件控制、传感器采集、本地执行 |
| `apex-central-control` | **智能体中控系统** | 平台层软件，负责协议翻译、权限管控、安全加密、智能体对接 |
| **组合使用** | **完整的产品开发体系** | 底层框架 + 中控系统 = 一天搭建原型，一周产品落地 |

> **一句话**：[`apex-esp32-s3-v6`](https://gitee.com/freen/apex-esp32-s3-v6) 管硬件，`apex-central-control` 管安全与调度，二者组合即可快速搭建由豆包/千问/元宝操控的、有认证有权限有指令锁的智能体设备。

---

## 已落地能力

✅ **豆包 App 智能体控制** — 已完整实现对接，用户可通过豆包 App 直接控制 APEX 中控管理的设备


> **APEX 智能体中控系统** — 配合 [APEX 底层框架](https://gitee.com/freen/apex-esp32-s3-v6)，快速搭建由顶流 AI 操控的、有认证有权限有指令锁的智能体设备。