openvela-smarthome · 基于 openvela 智能体的自然语言智能家居控制系统

面向 2026 CCF 开源创新大赛「基于 openvela 智能体的智能家居控制系统」 的初赛参赛作品。

一句话：用自然语言控制模拟智能家居设备——「打开客厅的灯」「现在客厅多少度」「全部设备什么状态」， openvela 智能体（ai_agent）理解意图、调用工具、反馈结果，全程可在 QEMU goldfish-arm64 模拟器 上跑，无需硬件。

团队 / 单位：程柯雷（太原理工大学）｜单人参赛
许可证：Apache-2.0（与 openvela 一致）
赛题仓库：https://www.gitlink.org.cn/openvela

亮点

3 个模拟家居工具（要求 ≥2）：light_control 灯光开关/亮度、read_temp_humidity 温湿度读取、device_status_query 设备状态查询。
自然语言闭环：意图理解 → 工具调用 → 结果反馈，多轮、带澄清。
确定性命令校验门：工具执行前统一过闸（设备存在/在线、动作合法、参数在域、白名单），把「LLM 可能说错」和「真实执行」隔开——对应 openvela tool_guard。
可插拔多 LLM 后端：DeepSeek / Kimi / 通义千问，OpenAI 兼容，Key 走环境变量、绝不入库。
两套实现，同一套语义：
- host/（Python，零第三方依赖）——无模拟器即可一键跑通全闭环，作 Demo 与行为基准；
- openvela_tools/（C）——注册进 openvela ai_agent、跑在 QEMU goldfish-arm64 上的设备端落地。
基本异常处理：设备不存在/离线、参数越界、工具报错、LLM 超时/鉴权失败均有兜底，不崩溃。

快速开始（60 秒，无需模拟器、无需硬件）

方式一：离线一键跑（无需任何 API Key）

cd host
python3 main.py --demo --mock

用离线规则后端跑完整演示脚本，覆盖开关灯 / 读温湿度 / 查状态 / 越界被拦，日志落到 demo/logs/。适合评审在没有 Key 的机器上复现闭环。

方式二：接真实 LLM（推荐，展示真实推理）

cp config.example.env config.env      # config.env 已被 .gitignore，不会入库
# 编辑 config.env，填入 DEEPSEEK_API_KEY（或 Kimi / 通义千问的 Key）
cd host
python3 main.py --demo                 # 跑演示脚本
python3 main.py                        # 交互式，自己输入指令

也可不写 config.env，直接用环境变量：

cd host
LLM_PROVIDER=deepseek DEEPSEEK_API_KEY=sk-xxx python3 main.py

交互示例：

> 打开客厅的灯
[LLM→工具] light_control  参数={"device_id": "living_room_light", "action": "on"}
[执行] light_control → {"power": "on", ...}
[助手] 好的，客厅主灯已经打开。

> 帮我打开阳台的灯
[助手] 没找到「阳台」的灯。当前可用：客厅主灯 / 卧室灯 / 厨房灯，你想开哪个？

真实运行日志样例见 demo/sample-run-deepseek.log（DeepSeek 实跑）与 demo/sample-run-mock.log（离线复现）。

方式三：设备端在 openvela 模拟器上运行

见 openvela_tools/INTEGRATION.md：把 C 工具注册进 open-vela/packages_ai_agent，用官方 build.sh / emulator.sh 在 QEMU goldfish-arm64 上运行。

项目结构

openvela-smarthome/
├── README.md                 本文件
├── LICENSE / NOTICE          Apache-2.0 + 版权与适配声明
├── THIRD_PARTY.md            第三方依赖与原创性声明
├── config.example.env        LLM 后端配置模板（复制为 config.env 填 Key，不入库）
├── host/                     上位机参考实现（Python，零第三方依赖，可无模拟器直接跑）
│   ├── main.py               入口：--demo / --mock / 交互式
│   ├── demo_script.txt       演示指令脚本（9 条，含正常/越界/幻觉设备/模糊指令）
│   └── smarthome/
│       ├── devices.py        内存态设备表 + 设备能力表
│       ├── tools.py          三个工具的定义与注册（工具契约）
│       ├── gate.py           确定性命令校验门
│       ├── llm.py            多 LLM 后端客户端（OpenAI 兼容）+ 离线 MockLLM
│       ├── agent.py          Agent 主循环（意图→工具→反馈，ReAct 式）
│       └── errors.py         统一异常
├── openvela_tools/           设备端 C 工具（注册进 openvela ai_agent，跑 QEMU goldfish-arm64）
│   ├── smarthome_device.h/.c 内存态设备表（C，与 host 同模型）
│   ├── smarthome_tools.h/.c  三工具 + 命令校验门 + 注册入口
│   ├── Kconfig / Make.defs / CMakeLists.txt   构建接入
│   └── INTEGRATION.md        接入与在模拟器运行的完整步骤
├── docs/
│   ├── architecture.md       架构概览与数据流
│   └── openvela-agent-notes.md   openvela ai_agent 调研记录（已核实 vs 待实测）
└── demo/
    ├── sample-run-deepseek.log   DeepSeek 实跑日志
    ├── sample-run-mock.log       离线复现日志
    ├── sample-selftest-c.log     设备端 C 工具宿主机自测输出
    └── logs/                     运行时日志输出目录

架构一览

自然语言 → LLM(意图理解, 产出受约束工具调用) → 命令校验门(确定性过闸) → 工具执行(读写设备表) → 回喂 LLM → 自然语言反馈

工具注册：每个工具声明 name / description / 入参 JSON-Schema / 执行函数，供 LLM 自主选择调用。
命令校验门：设备存在/在线、动作被该设备类型支持、参数在合法域、命中工具白名单——不过则驳回带原因。
设备表：内存态，预置 3 灯 + 2 温湿度传感器 + 1 空调（多房间）；工具只读写这张表，不触真实硬件，故可确定性复现。

细节见 docs/architecture.md。openvela ai_agent 的调研与适配说明见 docs/openvela-agent-notes.md。

LLM 后端配置

后端	`LLM_PROVIDER`	Key 环境变量	默认模型	Base URL
DeepSeek	`deepseek`	`DEEPSEEK_API_KEY`	`deepseek-chat`	`https://api.deepseek.com`
Kimi/Moonshot	`kimi`	`MOONSHOT_API_KEY`	`moonshot-v1-8k`	`https://api.moonshot.cn/v1`
通义千问	`qwen`	`DASHSCOPE_API_KEY`	`qwen-turbo`	`https://dashscope.aliyuncs.com/compatible-mode/v1`
离线规则	`mock`	无需 Key	—	本地

可用 LLM_MODEL / LLM_BASE_URL 覆盖默认值。设备端在模拟器里用 set_llm <provider> <key> 配置。

运行环境

上位机 Demo：**Python 3.8+**，无需 pip 安装任何包。
设备端：openvela SDK + QEMU goldfish-arm64（官方镜像），cJSON（openvela 自带）。

许可证与合规

Apache-2.0，见 LICENSE / NOTICE。原创为主，第三方依赖仅为平台 SDK 与通用 JSON 库（cJSON, MIT），详见 THIRD_PARTY.md。