目录
master
分支1
标签0
+ 疑修
Web IDE
CCF OpenVela Demo
Complete reproducibility and DeepSeek evidence
3个月前4次提交
README.md

openvela 智能家居 AI Agent

本仓库是 CCF/GitLink openvela AI Agent 智能家居赛题的初赛技术提交物。方案为 openvela AI Agent 增加三个智能家居工具和内存态设备模拟器，并在 goldfish-arm64 模拟器上完成了两条闭环验证：

  • 真实 DeepSeek Agent 模式：DeepSeek 理解自然语言并生成工具调用，openvela Agent 执行工具、更新状态、回传结果，再由模型生成反馈；
  • 无 Key 的确定性离线模式：smarthome_nl 用受限词表映射意图，但复用同一个工具注册表和状态模型，便于评审在无外网环境复现。

已保存的真实日志证明了客厅灯从初始 off 变为 on 并成功回读、查询卧室温湿度，以及卧室空调开启请求获得 Agent 反馈并回读 ac.power:on。该次日志中的卧室空调初始状态已经是 on/sleep，因此它证明“请求与回读成功”，但不能单独证明空调发生了 off -> on 跃迁。API Key 已从仓库和证据日志中删除。

公开 GitLink 仓库：https://www.gitlink.org.cn/whuuuuuuu/openvela-smarthome-agent

English Summary

This competition deliverable adds three simulated smart-home tools to the openvela AI Agent and verifies them on the goldfish-arm64 emulator. It supports a real DeepSeek-backed ReAct loop and a deterministic offline fallback. The host bridge only adapts and forwards OpenAI-compatible HTTP traffic; model reasoning and tool selection are produced by DeepSeek, while tool dispatch and execution remain inside openvela.

功能

  • smart_light_control：控制 living_room、bedroom、kitchen 的模拟灯光；
  • smart_env_query：查询温度、湿度、照度、灯光和空调状态；
  • smart_ac_control：控制模拟空调的电源、模式、目标温度和风速；
  • tools：打印 openvela Agent 中注册的工具 schema；
  • tool_call <name> [json]：不经 LLM 直接执行注册工具，用于异常与确定性验证；
  • smarthome_nl <text>：无 Key 的离线自然语言回退；
  • ask <text>：上游 AI Agent 的真实 LLM/ReAct 入口。

所有设备状态都保存在 openvela 进程内存中。本项目不依赖真实灯具、空调、MQTT、MCP、飞书或微信；模拟器重启后状态恢复为初始值。

架构

真实模式：自然语言 -> openvela Agent -> DeepSeek -> tool_call
                                        -> openvela tool_registry
                                        -> 智能家居内存状态
                                        -> 工具结果 -> DeepSeek 最终反馈

离线模式：smarthome_nl -> 确定性意图映射 -> 同一个 tool_registry -> 工具结果

远端 goldfish 环境直连 DeepSeek 曾出现网络/TLS 超时，因此真实演示使用 scripts/deepseek_openai_bridge.py：

  • openvela 向 http://10.0.2.2:18081/v1/chat/completions 发送 OpenAI-compatible 请求；
  • 宿主机桥把请求转发到 https://api.deepseek.com/v1/chat/completions，并回传状态码、Content-Type 和响应体；
  • 桥仅用 Python 标准库，不进行推理、不选择或执行工具，也不伪造模型输出；
  • 推理与 ReAct 工具选择来自真实 DeepSeek，注册表调度、参数校验和设备状态修改发生在 openvela Agent 中。

10.0.2.2 是本演示 goldfish/QEMU 网络中从 guest 访问宿主机的地址。端口和地址可通过环境变量覆盖。

固定上游版本

路径 上游 commit
工作区 manifest open-vela/manifests（上游分支 trunk） 58c85bf035a5c2ea88db646bb6b405694f2f9af7
packages/ai_agent open-vela/packages_ai_agent 964117fb5f441d67d35c461178b918ea7dd7c834
vendor/openvela open-vela/vendor_openvela 83592f988037cfcbbe308139add12079fb103791

应用补丁前必须分别核对这两个路径。完整命令见 docs/reproducibility.md。

快速复现

以下命令在 Linux 宿主机执行。/path/to/openvela 是包含 packages/ai_agent、vendor/openvela、build.sh 和 emulator.sh 的完整 openvela 工作区。

1. 应用补丁并构建

./scripts/apply_patches.sh /path/to/openvela
./scripts/build_goldfish.sh /path/to/openvela

目标配置：

vendor/openvela/boards/vela/configs/goldfish-arm64-v8a-ap/

2A. 真实 DeepSeek Agent 模式

先在当前 shell 中安全设置环境变量，不要把真实 Key 写进命令示例、脚本或配置文件：

read -rsp 'DeepSeek API Key: ' DEEPSEEK_API_KEY
echo
export DEEPSEEK_API_KEY
./scripts/run_deepseek_demo.sh /path/to/openvela
unset DEEPSEEK_API_KEY

唯一必需环境变量是 DEEPSEEK_API_KEY。可选项：

变量 默认值 用途
OPENVELA_ROOT /root/autodl-tmp/ccf-openvela/openvela 省略位置参数时的工作区
DEEPSEEK_MODEL deepseek-chat 覆盖真实演示模型
BRIDGE_BIND_HOST 0.0.0.0 宿主机桥监听地址
BRIDGE_PORT 18081 宿主机桥监听端口
EMULATOR_BRIDGE_HOST 10.0.2.2 模拟器访问宿主机的地址
LOG_DIR demo/logs 证据日志目录

脚本启动桥和无头模拟器，执行三组自然语言任务，流式脱敏输出，并在退出前执行 config_reset。结果写入 demo/logs/emulator_deepseek_agent.log。

真实闭环关键结果（从完整日志中抽取，省略调试行）：

打开客厅灯 -> smart_light_control -> power:on
查询客厅状态 -> smart_env_query -> light.power:on
查询卧室温湿度 -> smart_env_query -> temperature_c / humidity
请求打开卧室空调 -> Agent 反馈当前为 on（并说明此前已配置）
查询卧室状态 -> smart_env_query -> ac.power:on

日志没有输出内部 tool-call telemetry，且卧室空调编译初始值已经为 on/sleep，因此不把这一次 AC 结果夸大为已观察到 off -> on 状态变化。当前 run_deepseek_demo.sh 已在真实 AC 请求前用确定性工具把空调设为 off 并回读；使用有效 Key 重新运行可生成更强的 off -> on 证据。

已提交日志的短原文摘录：

LLM backend: 10.0.2.2:18081/v1/chat/completions (model: deepseek-chat) [router slot 0]
Sent to agent: Turn on living room light
[Agent]: Living room light is **on** at **80% brightness**
{"ok":true,"tool":"smart_env_query","state":{"room":"living_room","light":{"power":"on","brightness":80,"color_temp_k":4000},...}}

Sent to agent: Query bedroom temperature
- Temperature: **25.8°C**
- Humidity: **61%**

Sent to agent: Turn on bedroom AC
[Agent]: Bedroom AC is now **on**
Already was configured nicely for sleeping.
{"ok":true,"tool":"smart_env_query","state":{"room":"bedroom",...,"ac":{"power":"on","mode":"sleep","target_temp_c":25,"fan_speed":"low"}}}

省略号仅用于 README 压缩展示；可审计的完整原始行保存在 demo/logs/emulator_deepseek_agent.log。

2B. 无 Key 的确定性离线模式

最短复现命令：

./scripts/run_smarthome_demo.sh /path/to/openvela

它生成 demo/logs/emulator_smarthome_demo.log。单轮输出示例：

smarthome_nl turn on living room light
{"stage":"intent_understanding","text":"turn on living room light"}
{"stage":"tool_selection","tool":"smart_light_control","input":{"room":"living_room","power":"on","brightness":78,"color_temp_k":4200}}
{"ok":true,"tool":"smart_light_control","room":"living_room","power":"on","brightness":78,"color_temp_k":4200}
{"stage":"result_feedback","message":"light command applied"}

中文关键词同样受支持；自动采集日志默认用英文，减少无头串口编码差异。

3. 运行异常处理证据

./scripts/run_error_cases.sh /path/to/openvela

脚本重启无头模拟器并验证非法 JSON、未知房间、目标温度/亮度越界、未知工具和不支持意图，输出 demo/logs/emulator_error_cases.log。

{"ok":false,"error":"invalid JSON"}
{"ok":false,"error":"unknown room","supported_rooms":["living_room","bedroom","kitchen"]}
{"ok":true,"tool":"smart_ac_control",...,"target_temp_c":30,...}
Error: unknown tool 'unknown_tool'
{"ok":false,"error":"unsupported smart home intent","supported_examples":[...]}
{"ok":true,"tool":"smart_light_control",...,"brightness":100,...}

4. 校验证据

./scripts/verify_demo.sh

校验脚本检查必要文件、完整许可证、上游 commit 记录、日志脱敏和成功/异常证据。它不需要 API Key，也不会替代实际构建或真实 LLM 重跑。

已验证环境与资源

项目 已验证情况
宿主机 Ubuntu 22.04.1 LTS x86_64 AutoDL CPU 云主机，AMD EPYC 7642；宿主视图可见 192 个逻辑处理器
容器配额 cgroup cpu.max 对应约 20 CPU，memory.max 约 90 GiB；这是该实例实测配额，不是最低要求
构建并发 保存的构建日志使用 -j192，但 CPU cgroup 配额约 20；复现时可按实际配额降低并发
构建时间 已保存的增量构建成功并报告 17 seconds；首次同步和全量构建时间依网络、缓存与并发而异
内存 宿主视图可见 755 GiB，容器 cgroup 上限约 90 GiB；两者都不是经边界测试得出的最低值
磁盘 /root/autodl-tmp 容量 80G、实测可用 44G；openvela 工作区约 37G，其中 goldfish 构建输出约 3.0G；根 overlay 30G、可用 22G
工具版本 Git 2.34.1、repo launcher 2.17、CMake 3.22.1、Ninja 1.10.1、GNU Make 4.3、Python 3.10.12、pip 26.1.2；本次流程未安装或要求 Java
真实模式网络 宿主机可访问 api.deepseek.com:443，模拟器可访问宿主机桥端口

完整 openvela 工作区远大于本补丁仓库。评审应预留高于工作区实际占用的磁盘空间；资源不足时降低构建并发，而不是照搬 -j192。

证据文件

  • demo/logs/build_goldfish_ai_agent.log：goldfish 目标构建成功；
  • demo/logs/emulator_ai_agent_cli.log：NSH、AI Agent CLI 和工具 schema；
  • demo/logs/emulator_smarthome_demo.log：离线自然语言和直接工具调用；
  • demo/logs/emulator_deepseek_agent.log：真实 DeepSeek ReAct 闭环；
  • demo/logs/emulator_error_cases.log：非法 JSON、未知房间、越界值、未知工具和不支持意图。

仓库结构

  • patches/：对两个固定上游组件的补丁；
  • scripts/apply_patches.sh：幂等应用补丁；
  • scripts/build_goldfish.sh：构建 goldfish 目标；
  • scripts/run_smarthome_demo.sh：运行无 Key 离线演示；
  • scripts/run_error_cases.sh：运行异常和数值边界演示；
  • scripts/deepseek_openai_bridge.py：宿主机 OpenAI-compatible 转发桥；
  • scripts/run_deepseek_demo.sh：运行真实 DeepSeek 演示并脱敏；
  • scripts/verify_demo.sh：提交前静态和证据检查；
  • docs/：设计、复现和提交说明；
  • demo/logs/：构建、正常闭环、真实 LLM 和异常证据。

安全要求

  • API Key 必须通过 DEEPSEEK_API_KEY 环境变量提供，严禁硬编码或提交；
  • 不要把包含真实 Key 的 set_llm 命令复制到终端记录、截图或视频；
  • 桥不得记录 Authorization 头；运行脚本必须在日志落盘前脱敏；
  • 默认桥监听 0.0.0.0 以供 QEMU guest 访问，只应在受信宿主/防火墙环境短时运行，完成后由脚本关闭；
  • 演示结束执行 config_reset，并从宿主机 shell 中 unset DEEPSEEK_API_KEY；
  • 发布前按 SUBMISSION_CHECKLIST.md 检查 API Key、SSH 密码、主机地址、Cookie 和令牌。

常见问题

直连 DeepSeek 超时

远端 goldfish 的 guest 网络/TLS 路径可能无法稳定直连公网。使用 run_deepseek_demo.sh 启动宿主机桥，让 guest 访问 10.0.2.2:18081，由宿主机完成 HTTPS。先确认宿主机能访问 api.deepseek.com:443。

模拟器无法连接桥

确认 bridge 仍在运行、BRIDGE_PORT 未被占用、宿主机防火墙允许模拟器 NAT 网络访问，并核对 EMULATOR_BRIDGE_HOST。若改变端口，guest 配置和桥监听端口必须一致。

串口命令被截断或参数异常

NSH CLI 的行缓冲和参数数量有限。使用单行紧凑 JSON，不粘贴多行或超长提示；自动演示脚本已经控制命令长度。中文出现乱码时优先使用等价英文命令采证。

补丁无法干净应用

先核对两个固定 commit 和本地未提交修改。apply_patches.sh 会识别已应用补丁；既不满足 git apply --check、也找不到已应用标志时会退出，不应强行忽略。

没有 API Key

运行 run_smarthome_demo.sh。离线模式能复核意图、工具选择、执行和反馈，但报告结果时应明确它不是 LLM 推理。

开源合规

本仓库根目录包含完整 Apache License 2.0 正文。第三方来源、准确 commit、MimiClaw MIT 归属、补丁上下文与原创边界、闭源代码声明及 AI 辅助开发说明见 THIRD_PARTY_NOTICES.md；简要归属见 NOTICE。

关于
shell
README.md
110.0 KB
邀请码
    Gitlink（确实开源）
  • 加入我们
  • 官网邮箱：gitlink@ccf.org.cn
    • QQ群
  • QQ群
    • 公众号
  • 公众号

版权所有：中国计算机学会技术支持：开源发展技术委员会
京ICP备13000930号-9 京公网安备 11010802047560号