Edge AI Ecosystem Platform

开源边缘 AI 平台 —— 构建"硬件—模型—应用"三层闭环，统一接入异构边缘设备，在端侧/边缘运行模型，支撑上层智能应用。

---

Prerequisites

工具 / 服务	版本 / 说明
Go	>= 1.22（CI 环境为 1.26）
Rust	stable（edge-agent）
Docker	>= 20.10
kind	用于本地 Kubernetes 集群
keadm	KubeEdge 安装工具（CloudCore/EdgeCore）
Make	GNU Make
ANTHROPIC_API_KEY	（可选）用于 ai-service 的 Claude 后端

---

Quickstart

# 1. 克隆仓库
git clone https://github.com/your-org/ai-ecosystem.git
cd ai-ecosystem

# 2. 编译所有组件
make build

# 3. 运行全部测试
make test

# 4. 启动本地 KubeEdge 开发环境（kind + CloudCore）
make dev
kubectl get nodes

单独运行服务

# control-plane（自动选择空闲端口）
make docker-run

# ai-service（需要设置 ANTHROPIC_API_KEY）
export ANTHROPIC_API_KEY="your-key"
make ai-run

# 本地 MQTT broker（用于设备通信测试）
make mqtt-broker

详细部署说明见 deploy/README.md

---

Architecture Overview

                   ┌──────────── 中心（云/自托管）────────────┐
                   │  ┌──────────────┐   ┌──────────────────┐ │
   应用/开发者 ──►  │  │ control-plane│◄──►│ KubeEdge CloudCore│ │
                   │  │  设备注册      │   │  云边协同          │ │
                   │  │  影子管理      │   │  设备管理(DMI)     │ │
                   │  └──────────────┘   └────────┬─────────┘ │
                   │  ┌──────────────┐            │ 云边隧道    │
                   │  │  ai-service  │            │            │
                   │  │  流式对话 API │            │            │
                   │  └──────────────┘            │            │
                   └─────────────────────────────┼────────────┘
                                                  ▼
                   ┌──────────── 边缘节点 ─────────────────────┐
                   │  KubeEdge EdgeCore  +  edge-agent (Rust)  │
                   │   MQTT 订阅 sensor/#                       │
                   │   数据上行 → control-plane /events         │
                   └──────┬────────────────────────────────────┘
                    (MQTT) │
                    ┌──────▼──────┐
                    │ MQTT 传感器  │  (temp / humidity / ...)
                    └─────────────┘

• control-plane：设备注册、影子管理（desired/reported）、事件接收，暴露 Prometheus /metrics。
• ai-service：流式对话 API，对接 Claude LLM 后端。
• edge-agent：Rust 常驻进程，订阅 MQTT sensor/#，解析 JSON payload，上行到控制面设备影子。

---

Project Structure

.
├── .github/workflows/    # GitHub Actions CI
├── ai-service/           # Go AI 对话服务（Claude 流式 API）
├── control-plane/        # Go 控制面（设备注册/影子/事件）
├── edge-agent/           # Rust 边缘代理（MQTT 订阅 + 上行）
├── deploy/               # 本地 kind + KubeEdge 配置
├── device-profiles/      # 设备类型定义（M2+）
├── docs/plans/           # 架构设计与迭代计划
├── examples/             # 使用示例（M2+）
├── Makefile              # 统一构建、测试、运行入口
└── README.md

---

Development Guide

运行测试

make test

# 单独测试
cd control-plane && go test ./... -race -count=1
cd ai-service && go test ./... -race -count=1
cd edge-agent && cargo test

端到端 Demo（MQTT → edge-agent → 控制面影子）

# 1. 起 MQTT broker
make mqtt-broker

# 2. 起控制面
cd control-plane && go run ./cmd/controlplane &

# 3. 注册设备
curl -X POST http://localhost:8080/v1/devices \
  -H 'Content-Type: application/json' \
  -d '{"id":"sensor-01","type":"mqtt-sensor"}'

# 4. 起 edge-agent
cd edge-agent && MQTT_BROKER=localhost CONTROL_PLANE_URL=http://localhost:8080 cargo run &

# 5. 模拟传感器上报
docker exec mosquitto mosquitto_pub -t sensor/sensor-01 -m '{"temp":28.5,"humidity":60}'

# 6. 查看设备影子
curl http://localhost:8080/v1/devices/sensor-01

代码风格 / Lint

cd control-plane && golangci-lint run ./...
cd ai-service && golangci-lint run ./...
cd edge-agent && cargo clippy -- -D warnings && cargo fmt --check

---

Contributing

1. Fork 并创建特性分支（git checkout -b feat/my-feature）
2. 确保 make test 全绿
3. 新增功能请补充单元测试
4. 提交遵循 Conventional Commits
5. 发起 PR 到 main，描述变更内容和测试情况

---

里程碑进展

• M0 — 骨架：控制面 /health /metrics，CI，本地 KubeEdge 环境
• M1 — 设备接入闭环：设备注册/影子/事件 API，edge-agent MQTT 插件，端到端 demo 验证
• M2 — 模型下发与端侧推理（规划中）

---

许可证：待定 | 问题反馈：GitHub Issues