blackbird/robot_agent

robot_agent — 基于 libhttp 的 DeepSeek 视觉机器人 Agent

C++20 机器人智能体骨架：命令行输入任务，调用 DeepSeek 视觉大模型（deepseek-v4-flash-vision-exp），通过工具循环驱动摄像头识图、状态查询、命令行执行与文件读写，后续可扩展硬件控制。

架构

用户任务（CLI 参数或 --prompt-file 文件）
  └─ 主代理（run_chat_loop 工具循环）
       ├─ capture_image     拍照识图（真实摄像头 / 模拟图片）
       ├─ get_robot_status  查询机器人状态
       └─ spawn_subagent    委派任务给子代理
            └─ 子代理（技能超集，独立工具循环）
                 ├─ run_command  执行 shell 命令（超时 + 输出截断）
                 ├─ read_file / write_file
                 ├─ capture_image / get_robot_status
                 └─ 返回结论 → 主代理综合回答

• 工具循环：模型返回 tool_calls → agent 执行工具 → 结果回传 → 继续，直到模型给出最终回答（--max-turns 限轮）。
• 图片注入：OpenAI 协议的 tool 消息只允许文本，工具返回的图片由主循环作为 image_url 注入下一轮。
• 时间戳：会话开始时向 system prompt 注入一次当前时间（会话内不变）；每个工具结果附 工具执行时间，供模型判断数据新旧。
• 摄像头：V4L2 直采，优先 MJPEG（硬件编码零转码，最快），回退 YUYV + libjpeg 编码；设备常开复用；/dev/video* 自动探测。

依赖与构建

• g++（C++20）、libhttp（libus_httpclient.so）、Boost.JSON、libcurl、OpenSSL、libjpeg、pthread
• libhttp 需先编译：cd ../libhttp && make

make          # 生成 ./robot_agent
make clean

使用

export DEEPSEEK_API_KEY=sk-xxx   # 或用 --key

./robot_agent "看看环境里有什么"                    # 真实摄像头识图
./robot_agent "报告状态"                            # 状态查询
./robot_agent "列出当前目录文件"                     # 自动委派子代理执行命令
./robot_agent --prompt-file /tmp/task.txt          # 从文件读取任务
./robot_agent "描述图片" --camera ./test.png        # 模拟摄像头（读文件，便于离线测试）

参数	说明	默认
--prompt-file <文件>	从文件读取任务（与位置参数互斥）	—
--camera <文件>	模拟摄像头：拍照工具读该图片	空 = 真实摄像头
--camera-device <设备>	摄像头设备	自动探测 /dev/video*
--model <名称>	模型名	deepseek-v4-flash-vision-exp
--key <API_KEY>	API key	环境变量 DEEPSEEK_API_KEY
--endpoint <URL>	接口地址	https://api.deepseek.com/chat/completions
--max-turns <N>	最大工具轮次	8

工具日志输出到 stderr（[主代理][工具] / [子代理][工具]），stdout 只输出最终回答，便于脚本管道。

代码结构

文件	职责
main.cpp	CLI 解析、主代理工具注册
agent.hpp/cpp	run_chat_loop 工具循环（主/子代理共用）、消息构造、时间戳注入
subagent.hpp/cpp	子代理：技能超集 + 独立提示词
tools.hpp/cpp	Tool/ToolRegistry 与全部工具实现
camera.hpp/cpp	V4L2 抓帧（MJPEG/YUYV、mmap、超时保护）

扩展

• 加工具：实现 Tool{name, description, parameters(JSON Schema), execute} 后 registry.add(...)。
• 工具返回图片：ToolResult.image_data_url 填 data URL，主循环自动注入下一轮。
• 加子代理类型：仿照 subagent.cpp 组装不同工具集与提示词。
• 接真实硬件：把 capture_image/get_robot_status 的实现换成设备驱动调用即可，接口不变。

安全注意

run_command 会执行任意 shell 命令且无白名单/审批，仅建议在可信环境（你自己的机器人主机）运行；后续如需对外暴露，应先加命令审批或沙箱。