---

作品简介

VelaClaw Smart Home Agent Control System 面向 CCF 2026 openvela 赛题 track2_2026openvela01，实现一个自然语言驱动的智能家居控制原型系统。

用户以中文自然语言表达目标，系统通过 planner 选择智能家居 Tool，由本地 VelaClaw-style executor 执行设备控制，再将设备状态、传感器观测、规则复算、安全确认和 Agent 回答返回到前端页面与日志。项目主线聚焦 意图理解 -> Tool 调用 -> 设备状态更新 -> 结果反馈 的 Agent 控制闭环，而不是单纯的智能家居 UI。

赛题对应

官方任务方向	本仓库交付物	位置
自定义智能家居 Tool	10 个 VelaClaw-style Tool，覆盖灯光、环境、门锁、空调、窗帘、场景、规则、安全确认和告警	velaclaw_tool_skeleton/tools/
自然语言控制闭环	DeepSeek planner API、host executor、QEMU home_intent 和演示前端形成闭环证据	host/、demo/、tests/
Skill 文件扩展	2 个 Markdown Skill，覆盖夜间守护和晨间天气空调场景	velaclaw_tool_skeleton/skills/
openvela / VelaClaw 迁移	Tool schema、planner/executor、反馈通道、安全确认和 OpenClaw 节点契约	docs/openvela_velaclaw_openclaw_migration.md
可复现运行与演示	一键演示脚本、验证脚本、日志、PPT、演示视频网盘链接、提交包	scripts/、logs/、presentation/

主交付物是自然语言智能家居 Agent 控制闭环。前端页面用于展示 Agent 回答、Tool 调用链、设备状态和告警反馈；核心能力由 Tool schema、planner、executor、状态反馈和验证脚本支撑。

交付要求导航

评审关注点	当前证据
至少 2 个智能家居 Tool	已提供 10 个 Tool descriptor，并在 QEMU / host 侧验证调用链
意图理解 -> 工具调用 -> 结果反馈	DeepSeek-backed /api/intent、QEMU home_intent、前端 Agent Trace 和日志共同覆盖
可运行系统	scripts/run_demo_server.ps1、scripts/run_preliminary_demo.ps1、QEMU 验证脚本
异常处理与安全增强	门锁解锁二次确认、烟雾告警、未知意图、规则复算和日志脱敏
文档与演示	README、技术方案、测试说明、使用说明、演示脚本、PPT、视频、提交包
开源合规	LICENSE、NOTICE.md、docs/THIRD_PARTY_DEPENDENCIES.md

核心交付

模块	内容	价值
Agent 控制闭环	自然语言输入、DeepSeek planner、Tool 调用、状态反馈、Agent Trace	贴合赛题“自然语言驱动智能家居控制”主线
VelaClaw Tool 骨架	Tool JSON、C 风格 handler、planner/executor 合约、Skill 文件	便于迁移到 openvela AI Agent / VelaClaw
智能家居域模型	8 个设备、6 个场景、8 条规则、2 条安全确认路径	覆盖灯光、门锁、空调、窗帘、空气质量和烟雾告警
QEMU / openvela 证据	ai_agent 启动、Tool 注册、Tool 调用、Skill 读取、自然语言样例日志	为初赛可复现性提供运行证据
演示与提交材料	一键脚本、PPT、百度网盘视频链接、提交 zip、SHA256	降低评委复核和平台提交成本

工作流概览

用户自然语言
      |
      v
Agent planner / DeepSeek tool-calling
      |
      v
VelaClaw-style Tool schema
      |
      v
Smart-home executor
      |
      +-- 设备状态更新
      +-- 传感器观测
      +-- 规则复算
      +-- 安全确认
      |
      v
Agent 回答 / 前端状态 / Trace / 日志

快速演示

前后端联动演示

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\run_demo_server.ps1

打开页面：

http://127.0.0.1:8765/

启用 DeepSeek-backed Tool 选择时，在启动前设置环境变量；不要在录屏里展示真实 key。

$env:DEEPSEEK_API_KEY="YOUR_DEEPSEEK_API_KEY"
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\run_demo_server.ps1

验证同一条 API 路径：

powershell -NoProfile -ExecutionPolicy Bypass -File .\tests\verify_demo_deepseek_planner_api.ps1 -RequireKey

初赛一键演示

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\run_preliminary_demo.ps1

脚本会按评审关注点输出 Tool registry evidence、2 个以上 Tool 调用、自然语言样例、结果反馈、异常处理、安全确认、QEMU / DeepSeek / QuickApp 验证摘要。最新演示日志位于 logs/。

演示视频和 PPT

材料	位置
演示视频网盘	GoGoGo_openvela_SmartHome演示视频，提取码：1017
展示 PPT	presentation/VelaClaw_SmartHome_Work_Demo_20260710.pptx
PPT 预览图	presentation/previews_20260710/

验证结果

指标	结果
智能家居设备模型	8
自定义 Tool	10
Skill 文件	2
场景模式	6
自动化规则	8
安全确认路径	2
QEMU Tool 验证	43/43 PASS
QEMU 自然语言闭环验证	66/66 PASS
QuickApp Tool 路径验证	19/19 PASS
Host-side DeepSeek ReAct 验证	12/12 PASS
DeepSeek demo backend planner API	17/17 PASS
初赛一键演示验证组	6/6 PASS

项目结构

路径	说明
demo/	智能家居控制台前端，展示设备状态、Agent 回答、Tool 调用链和告警
host/	本地演示后端，提供 /api/intent、/api/state、/api/confirm 等接口
velaclaw_tool_skeleton/	VelaClaw / OpenClaw 可迁移骨架，包含 Tool、Skill、OpenClaw 节点和安全策略
configs/	设备、Tool、规则、场景、LLM backend 和协议节点配置
scripts/	演示、QEMU、DeepSeek、打包和证据生成脚本
tests/	本地、DeepSeek、QEMU、QuickApp、Skill 和 OpenClaw 验证脚本
docs/	技术方案、测试说明、使用说明、最终报告、官方题面对齐和提交检查
logs/	可复现运行日志和验证输出
presentation/	展示 PPT 和预览图
submission/packages/	历史提交包和最新版提交包

交付材料

材料	文件
官方题面对齐	docs/official/OFFICIAL_TOPIC_ALIGNMENT.md
官方要求追踪	docs/official/OFFICIAL_REQUIREMENTS_TRACEABILITY.md
技术方案	docs/technical_solution.md
测试说明	docs/testing.md
使用说明	docs/usage.md
演示脚本	docs/demo_script.md
最终报告	docs/final_report.md
量化指标	docs/metrics.md
提交检查表	docs/submission_checklist.md
演示运行报告	docs/reports/PRELIMINARY_DEMO_RUN_REPORT_20260710.md
第三方依赖声明	docs/THIRD_PARTY_DEPENDENCIES.md

关键验证命令

powershell -NoProfile -ExecutionPolicy Bypass -File .\tests\verify_qemu_10_tools_runtime.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\tests\verify_qemu_home_intent_runtime.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\tests\verify_qemu_launch_quickapp_tool_vapp_fallback.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\tests\verify_deepseek_react_tool_call.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\tests\verify_demo_deepseek_planner_api.ps1 -RequireKey
powershell -NoProfile -ExecutionPolicy Bypass -File .\tests\verify_qemu_dual_node_openvela_smoke.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\tests\verify_qemu_llm_ask_smarthome.ps1 -AllowAttemptBoundary

提交包

材料	位置
最新提交包	submission/packages/ 中最新的 submission_verified_*.zip
历史提交包	submission/packages/
打包脚本	scripts/package_submission.ps1

重新生成提交包：

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\package_submission.ps1

验证边界

• 已完成证据覆盖本地前后端演示、DeepSeek-backed Tool 选择、QEMU ai_agent Tool 调用、QEMU 自然语言样例、Skill 读取和演示视频。
• VelaClaw / OpenClaw 迁移材料以 Tool schema、Skill、planner/executor、反馈通道、安全策略和节点契约形式组织，便于后续接入官方运行环境。
• 开发板适配不属于本次提交包范围；当前提交以 QEMU、host runner、日志和文档复现为主。
• 涉及 API key 的脚本只从环境变量读取；验证日志和演示材料不写入真实密钥。

License

本仓库使用 Apache-2.0 许可证，见 LICENSE。第三方依赖和素材说明见 NOTICE.md 与 docs/THIRD_PARTY_DEPENDENCIES.md。