VelaClaw

VelaClaw 是一个面向 openvela AI Agent 的智能家居控制系统参赛项目。它把自然语言请求转化为 Agent 计划、Tool 调用、设备状态变化和可审计日志，展示端侧嵌入式 Agent 在智能家居场景中的落地能力。

作品亮点

Agentic 闭环： 自然语言 -> intent -> plan -> Tool -> state delta -> response。
6 个智能家居工具： 灯光、环境传感、空调、场景、安防、能耗。
4 个 Skill 场景： 晨起、离家、睡眠、节能。
openvela 可迁移： 提供 C Tool overlay、Skill Markdown、QuickApp / UI 和 manifest 映射说明。
可复现评测： 内置 mock planner、golden demo、unittest 测试和多 LLM 对比矩阵。
展示友好： 提供本地 dashboard、视频脚本、PPT 大纲和提交 checklist。

快速开始

无需 openvela workspace，也无需真实开发板，先运行参考实现：

python3 -m reference_runtime.velaclaw state
python3 -m reference_runtime.velaclaw ask "我要睡觉了"
python3 -m reference_runtime.velaclaw demo
python3 -m reference_runtime.velaclaw eval
python3 -m unittest discover -s reference_runtime/tests

一键运行全部检查：

scripts/run_checks.sh

启动本地可视化控制台：

python3 -m reference_runtime.velaclaw dashboard --port 8765

打开：

http://127.0.0.1:8765

项目结构

.
├── docs/                         # 故事线、架构、迁移、演示、评测
├── reference_runtime/            # 本地可运行参考实现
│   ├── velaclaw/                 # Agent runtime、tools、planner、dashboard
│   └── tests/                    # 工具契约和场景测试
├── openvela_overlay/             # 可迁移到官方参赛仓的 overlay
│   ├── packages_ai_agent/        # C Tool 注册实现
│   ├── agent_skills/             # Markdown Skill 文件
│   ├── quickapp/                 # UI 展示骨架
│   └── manifest_notes/           # 官方仓映射说明
├── examples/                     # golden prompts 和日志生成说明
└── submission/                   # 视频脚本、PPT 大纲、提交 checklist

典型演示

输入：

我要睡觉了

输出会包含：

intent: sleep_mode
tool: home_scene_apply
args: {"scene": "sleep"}
state delta: 卧室灯光、卧室空调、客厅灯光、书房灯光、安防模式
response: 对用户的自然语言确认

与赛题评分项对应

评分项	VelaClaw 证据
自定义工具可用	`openvela_overlay/packages_ai_agent/src/tools/tool_home.c` 和 Python 工具契约
自然语言闭环	`reference_runtime.velaclaw ask/demo`
Skill 文件	`openvela_overlay/agent_skills/*.md`
多设备协作	`NodeSimulator` 和迁移说明
MCP 扩展	`MockMcpContext`，包含天气、日历、电价
多 LLM 后端适配	`MultiBackendComparator` 的契约矩阵
安全增强	schema 校验、错误码、恢复建议、审计事件
UI 展示	Python dashboard 和 QuickApp dashboard mock
工程化与文档	README、架构、迁移、评测、提交材料

openvela 迁移

迁移入口：

拿到官方 contest2026_<编号>_<队伍名> 仓后，将 overlay 映射进对应目录，再在 openvela workspace 中启用 AI Agent、MCP、Node 或 UI 配置。

故事线

核心记忆点：

VelaClaw 让资源受限的 openvela 设备从「听懂命令」升级为「理解家庭目标，并自主调用工具完成多设备协作」的智能家居 Agent。

完整故事见 docs/story.md。

许可证

本项目采用 Apache License 2.0。详见 LICENSE、NOTICE 和 THIRD_PARTY.md。

Conflicts:

README.md