# edge-agent

**Repository Path**: halo-iot/edge-agent

## Basic Information

- **Project Name**: edge-agent
- **Description**: edge agent 边缘智能体
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-07
- **Last Updated**: 2026-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Edge Agent - 智能物联网中控系统

> 基于 AI 的智能物联网边缘计算中控系统，支持语音交互、自动化规则、多模型 LLM 集成

## ✨ 核心特性

- 🤖 **AI 语音助手** - 基于 Web Speech API 的语音交互，支持自然语言控制设备；会话记录持久化存储
- 📱 **设备管理** - 完整的 IoT 设备生命周期管理（注册、配网、状态监控）
- 🏗️ **物模型系统** - 支持为设备定义属性、功能、事件，结构化描述设备能力
- ⚡ **自动化规则** - IF-THEN 规则引擎，支持条件触发和动作执行
- 🧠 **多模型 LLM 支持** - 支持 Ollama、OpenAI、DeepSeek、Qwen、MiniMax 等多种模型，可配置思考功能开关
- 📊 **时序数据存储** - 基于 InfluxDB 的传感器数据存储和可视化
- 🔐 **双认证模式** - 支持 JWT 登录或 API Token 免登录（适合智能体场景）
- 🌐 **MQTT 通信** - 基于 MQTT 协议的设备实时通信
- 🎨 **主题切换** - 支持亮色 / 暗色主题切换
- 📱 **响应式界面** - 基于 Tailwind CSS 的现代化响应式 Web 界面

## 🏗️ 系统架构

```
┌─────────────────────────────────────────────────────────────┐
│                   前端层 (React + Tailwind CSS)              │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────────────┐ │
│  │ 语音控制 │  │ 设备管理 │  │ 规则配置 │  │ AI 模型配置     │ │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────────┬────────┘ │
└───────┼────────────┼────────────┼────────────────┼──────────┘
        │            │            │                │
        └────────────┴─────┬──────┴────────────────┘
                           │ REST API
        ┌──────────────────┴──────────────────┐
        │           后端层 (FastAPI)           │
        │  ┌──────────┐ ┌──────────┐ ┌───────┐ │
        │  │ 设备服务  │ │ 规则引擎  │ │ Agent │ │
        │  │ 认证服务  │ │ 数据服务  │ │ LLM   │ │
        │  └──────────┘ └──────────┘ └───────┘ │
        └──────────────────┬──────────────────┘
                           │
        ┌──────────────────┴──────────────────┐
        │           数据层                     │
        │  ┌─────────┐ ┌─────────┐ ┌────────┐ │
        │  │ SQLite  │ │InfluxDB │ │ MQTT   │ │
        │  │ (配置)   │ │(时序数据)│ │ Broker │ │
        │  └─────────┘ └─────────┘ └────────┘ │
        └─────────────────────────────────────┘
```

## 🚀 快速开始

### 环境要求

- Python 3.12+
- Node.js 18+
- pnpm 8+
- Docker & Docker Compose (可选，用于部署依赖服务)

### 1. 克隆项目

```bash
git clone <repository-url>
cd edge_agent
```

### 2. 启动依赖服务（可选）

使用 Docker Compose 一键启动 MQTT、InfluxDB、Ollama：

```bash
docker-compose up -d mqtt influxdb ollama
```

### 3. 配置后端

```bash
cd backend

# 创建虚拟环境
python -m venv venv

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 配置环境变量（复制 .env 并修改）
cp .env.example .env
```

**关键配置项** (`backend/.env`):

```env
# API Token 认证（智能体免登录模式）
API_TOKEN=sk-your-secret-token

# LLM 配置
LLM_PROVIDER=ollama
LLM_BASE_URL=http://localhost:11434
LLM_MODEL=llama3.1:8b

# MQTT 配置
MQTT_BROKER_URL=mqtt://localhost:1883

# InfluxDB 配置
INFLUXDB_URL=http://localhost:8086
INFLUXDB_TOKEN=your-influxdb-token
```

### 4. 启动后端

```bash
python main.py
```

后端服务将在 <http://localhost:8000> 启动，API 文档访问 <http://localhost:8000/docs>

### 5. 配置前端

```bash
cd frontend

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev
```

前端将在 <http://localhost:3000> 启动

## 📖 使用指南

### 认证方式

系统支持两种认证方式：

#### 方式一：API Token（推荐用于智能体）

1. 在 `backend/.env` 中设置 `API_TOKEN`
2. 访问前端时输入相同的 Token
3. 无需登录即可使用所有功能

#### 方式二：JWT 登录（传统方式）

1. 首次访问需要注册账号
2. 使用账号密码登录
3. 获取 JWT Token 访问 API

### 语音控制

1. 进入"语音控制"页面
2. 点击麦克风图标或按住空格键
3. 说出指令，例如：
   - "打开客厅的灯"
   - "把温度调到 25 度"
   - "查询所有设备状态"
4. 对话记录会自动持久化保存，支持跨会话历史回顾

### 设备管理与物模型

1. 进入"设备管理"页面，创建设备
2. 在设备详情页点击"编辑物模型"，定义：
   - **属性**：如温度、湿度、亮度（支持实时值展示）
   - **功能**：如开关、调节亮度（支持参数化调用）
   - **事件**：如报警、预警（支持实时推送）
3. 物模型编辑后，系统会自动关联遥测数据的单位、范围等信息

### 自动化规则

1. 进入"规则配置"页面
2. 创建 IF-THEN 规则：
   - **条件**: 选择设备属性，如 `温度 > 30°C`
   - **动作**: 选择目标设备和命令，如 `打开空调`
3. 启用规则，系统通过 MQTT 实时订阅并自动执行

### AI 模型配置

1. 进入"AI 模型配置"页面
2. 选择模型提供商：
   - **Ollama**: 本地部署，无需 API Key
   - **OpenAI**: 需要 API Key
   - **DeepSeek**: 需要 API Key
   - **Qwen**: 阿里云模型
   - **MiniMax**: MiniMax 模型
3. 配置模型参数（温度、最大 Token、系统提示词）
4. **思考功能**：可开启/关闭模型的链式思考（Chain-of-Thought），默认关闭
5. 点击"测试连接"验证配置

### 主题切换

1. 进入"系统设置"页面
2. 点击主题切换按钮，在**亮色**与**暗色**之间切换
3. 主题偏好会自动保存到浏览器本地存储

## 🔧 项目结构

```
edge_agent/
├── backend/                 # FastAPI 后端
│   ├── app/
│   │   ├── api/            # API 路由
│   │   │   ├── auth.py     # 认证接口
│   │   │   ├── devices.py  # 设备管理
│   │   │   ├── rules.py    # 规则引擎
│   │   │   ├── sensors.py  # 传感器数据查询与遥测注入
│   │   │   ├── voice.py    # 语音 / AI 对话与会话管理
│   │   │   └── llm.py      # LLM 配置
│   │   ├── crud/           # 数据库操作
│   │   ├── models/         # SQLAlchemy 模型
│   │   │   ├── chat_session.py   # AI 会话持久化
│   │   │   ├── device.py         # IoT 设备（含物模型）
│   │   │   ├── rule.py           # 自动化规则
│   │   │   └── user.py           # 用户与系统配置
│   │   ├── schemas/        # Pydantic 模型
│   │   └── services/       # 业务服务
│   │       ├── agent.py        # AI Agent 服务
│   │       ├── influxdb.py     # InfluxDB 读写
│   │       ├── mqtt.py         # MQTT 客户端
│   │       ├── telemetry.py    # 遥测数据解析与持久化
│   │       ├── llm_factory.py  # LLM 多提供商工厂
│   │       └── rule_engine.py  # 规则引擎
│   ├── config.py           # 应用配置
│   └── main.py             # 入口文件
│
├── frontend/               # React 前端
│   ├── src/
│   │   ├── api/           # API 客户端
│   │   ├── components/    # 通用组件
│   │   ├── pages/         # 页面组件
│   │   │   ├── VoiceControlPage.tsx    # 语音助手 / AI 对话
│   │   │   ├── DevicesPage.tsx         # 设备列表
│   │   │   ├── DeviceDetailPage.tsx    # 设备详情（物模型、实时值、历史趋势）
│   │   │   ├── RulesPage.tsx           # 规则引擎配置
│   │   │   ├── LLMConfigPage.tsx       # AI 模型配置
│   │   │   ├── HistoryPage.tsx         # 历史数据查询
│   │   │   ├── SettingsPage.tsx        # 系统设置（主题切换等）
│   │   │   ├── SystemMonitorPage.tsx   # 系统监控（资源、状态）
│   │   │   └── LoginPage.tsx           # 登录 / 注册
│   │   ├── stores/        # Zustand 状态管理
│   │   └── types/         # TypeScript 类型
│   └── package.json
│
├── design/                # 设计文档
│   ├── architecture.md    # 架构设计
│   └── prd.md            # 产品需求文档
│
└── docker-compose.yml     # Docker 部署配置
```

## 🔌 API 接口

### 认证

```http
# API Token 认证（Header）
X-API-Token: sk-your-token

# 或 JWT 认证
Authorization: Bearer <jwt-token>
```

### 主要接口

| 接口                          | 方法             | 说明           |
| --------------------------- | -------------- | ------------ |
| `/api/v1/auth/login`        | POST           | 用户登录         |
| `/api/v1/auth/register`     | POST           | 用户注册         |
| `/api/v1/devices/`          | GET/POST       | 设备列表/创建      |
| `/api/v1/devices/{id}`      | GET/PUT/DELETE | 设备详情/更新/删除   |
| `/api/v1/rules/`            | GET/POST       | 规则列表/创建      |
| `/api/v1/rules/{id}/toggle` | PUT            | 启用/禁用规则      |
| `/api/v1/voice/chat`        | POST           | AI 对话 / 语音指令   |
| `/api/v1/voice/sessions`    | GET            | 查询会话列表       |
| `/api/v1/sensors/data`      | GET            | 历史时序数据查询    |
| `/api/v1/sensors/latest`    | GET            | 最新数据点查询      |
| `/api/v1/sensors/ingest`    | POST           | 直接注入遥测数据    |
| `/api/v1/llm/providers`     | GET            | 获取 LLM 提供商列表 |
| `/api/v1/llm/config`        | GET/PUT        | 获取/更新 LLM 配置 |
| `/api/v1/llm/test`          | POST           | 测试 LLM 连接    |

完整 API 文档访问：<http://localhost:8000/docs>

## 🛠️ 开发指南

### 后端开发

```bash
cd backend

# 运行测试
pytest

# 代码格式化
black app/
isort app/

# 初始化数据库
python scripts/init_db.py
```

### 前端开发

```bash
cd frontend

# 类型检查
pnpm tsc --noEmit

# 构建生产版本
pnpm build

# 预览生产构建
pnpm preview
```

## 🐳 Docker 部署

### 完整部署

```bash
# 启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f backend

# 停止服务
docker-compose down
```

### 仅部署依赖服务

```bash
# 只启动 MQTT、InfluxDB、Ollama
docker-compose up -d mqtt influxdb ollama

# 本地开发后端和前端
```

## 📚 技术栈

### 后端

| 技术              | 版本      | 说明       |
| --------------- | ------- | -------- |
| FastAPI         | 0.109.0 | Web 框架   |
| SQLAlchemy      | 2.0.25  | ORM      |
| Paho-MQTT       | 1.6.1   | MQTT 客户端 |
| LangChain       | 0.3.0   | LLM 框架   |
| InfluxDB Client | 1.38.0  | 时序数据库    |
| Python-JOSE     | 3.3.0   | JWT 认证   |

### 前端

| 技术            | 版本     | 说明            |
| ------------- | ------ | --------------- |
| React         | 18.2.0 | UI 框架         |
| TypeScript    | 5.3.0  | 类型系统          |
| Tailwind CSS  | 3.4.x  | 原子化 CSS 框架   |
| lucide-react  | latest | 图标库           |
| Vite          | 5.0.0  | 构建工具          |
| Zustand       | 4.4.0  | 状态管理          |
| Axios         | 1.6.0  | HTTP 客户端       |
| Recharts      | latest | 数据可视化图表库    |

## 🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 📄 许可证

本项目基于 [Apache License 2.0](LICENSE) 开源许可证。

```
Copyright 2024 Edge Agent Contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```

## 🙏 致谢

- [FastAPI](https://fastapi.tiangolo.com/) - 高性能 Python Web 框架
- [React](https://react.dev/) - 用户界面库
- [Tailwind CSS](https://tailwindcss.com/) - 原子化 CSS 框架
- [LangChain](https://langchain.com/) - LLM 应用框架
- [Ollama](https://ollama.ai/) - 本地大模型运行平台
- [InfluxDB](https://www.influxdata.com/) - 时序数据库
- [EMQX](https://www.emqx.io/) - MQTT 消息 Broker

***

> 💡 **提示**: 如需了解更多详细信息，请查看 [design/architecture.md](design/architecture.md) 架构设计文档。