# lab-robot

**基于 MCP 的实验室视觉机器人助手：语音交互、云端 VLM 图像问答与 Opentrons 设备接入。**

[![CI](https://github.com/zbbio/lab-robot/actions/workflows/ci.yml/badge.svg)](https://github.com/zbbio/lab-robot/actions/workflows/ci.yml)
[![Release container](https://github.com/zbbio/lab-robot/actions/workflows/release-container.yml/badge.svg)](https://github.com/zbbio/lab-robot/actions/workflows/release-container.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

## 演示

[![实验室视觉机器人与实验设备](docs/demo/robot-overview.png)](docs/demo/visual-robot-demo.mp4)

**[观看完整演示视频（约 57 秒，MP4）](docs/demo/visual-robot-demo.mp4)** · [版本与下载](https://github.com/zbbio/lab-robot/releases)

## 功能与架构

- 将“看看当前画面”等自然语言请求交给 MCP 摄像头工具，获取现场图像并调用云端 VLM 返回文字回答。
- 使用 ONVIF 连接网络摄像头、获取 RTSP 地址；支持本地截图与可选 PTZ 云台控制。
- 通过已固定版本的 `opentrons-mcp` 接入协议上传、运行查询与执行控制工具。
- 使用小智客户端桥接工具与语音终端；Python 和 Node.js 服务可通过单个 Docker 镜像部署。

```mermaid
flowchart LR
    ESP[ESP32 语音终端\nESP-IDF / C] <--> Cloud[小智云端对话服务]
    Cloud <--> Bridge[小智 MCP 桥接客户端]
    Bridge <--> Camera[MCP 摄像头工具\nNode.js / Python]
    Camera <--> IP[ONVIF / RTSP 网络摄像头]
    Camera --> VLM[OpenAI GPT-4o 直连\n或小智 VLM 网关]
    Bridge <--> OT[Opentrons MCP]
    OT <--> Robot[Opentrons 实验设备]
```

VLM 负责图像理解；OpenCV 仅用于取帧、JPEG 编码等图像处理，不在本地加载模型权重。支持两种视觉通道：

- `VISION_PROVIDER=xiaozhi`（默认）：沿用小智 `/vision/explain` 网关，以 multipart 表单提交 `file` 和 `question`，读取返回的 `text`。源码没有指定网关背后的模型，不能由此确认使用了 GPT-4o。
- `VISION_PROVIDER=openai`：通过 OpenAI Responses API 直连，默认模型 `gpt-4o`；将 JPEG 编码为 Base64 data URL，与文字问题一起发送，读取返回消息中的 `output_text`，统一返回 `{success, text}`。

视觉通道的切换不改变 MCP 工具接口。使用语音终端时，小智仍承担语音对话和 MCP 桥接；选择 OpenAI 后，图片识别请求由 Python 直接发送给 OpenAI。

本仓库整理的是机器人设备接入与视觉工具部分。ESP32 固件、机械结构和接线图尚未包含；BinderAgent 的蛋白设计、RAG 和 LangGraph 编排也不在此仓库中。

## 硬件与运行条件

| 组件 | 用途 | 复现范围 |
| --- | --- | --- |
| 电脑或服务器 | 运行 Python、Node.js MCP 工具与桥接客户端 | 必需，或使用 Docker |
| ONVIF / RTSP 摄像头 | 获取实验现场画面 | 使用摄像头功能时必需；PTZ 需设备本身支持 |
| ESP32 + ESP-IDF / C 语音终端 | 视频中整机的语音入口 | 复现语音体验时需要；单独测试 MCP 工具不需要 |
| 小智服务接入点 | 连接语音终端和 MCP 工具 | 使用语音桥接时需要 |
| OpenAI API 或小智 VLM 网关 | 图像问答 | 使用图像理解时需要；本地截图不需要 |
| Opentrons 设备 | 执行实验协议 | 实验联调时需要；工具发现测试不需要 |

容器需能访问摄像头和机器人所在网络。摄像头是网络设备，不需要映射 USB 摄像头。开发板具体型号、外壳结构与固件工程需另外准备。

## Docker 快速开始

```bash
git clone https://github.com/zbbio/lab-robot.git
cd lab-robot
cp .env.example .env
# 编辑 .env，填写小智接入点、摄像头参数，并选择视觉通道与认证信息。
docker compose pull
docker compose up -d
docker compose logs -f
```

Windows PowerShell 使用 `Copy-Item .env.example .env` 复制模板。

首次配置需要填写 `XIAOZHI_MCP_ENDPOINT`；摄像头功能需要 `ONVIF_CAMERA_IP`、用户名和密码。

**直连 GPT-4o**：在本机 `.env` 中设置：

```dotenv
VISION_PROVIDER=openai
OPENAI_API_KEY=你的OpenAI_API密钥
OPENAI_MODEL=gpt-4o
```

请求固定发送到 `https://api.openai.com/v1/responses`，不使用 `VISION_API_URL`、`VISION_API_TOKEN` 或 `VISION_DEVICE_ID`。实现使用现有 `requests`，无需新增 SDK；包含连接/读取超时、缺少密钥检查、HTTP/JSON 错误处理、未完成/拒绝/空回答检查及错误日志密钥脱敏。设置 `store=false`，不启用 Responses 的响应存储；这不等于服务端无任何日志。API 密钥与模型权限需在 OpenAI 平台开通，ChatGPT 订阅不替代 API 认证。

**使用小智视觉网关**：保持 `VISION_PROVIDER=xiaozhi`；若网关需要认证，填写 `VISION_API_TOKEN`。`VISION_DEVICE_ID` 可固定设备身份，避免容器重建后 MAC 地址变化影响服务端绑定。

更新已有部署的 `.env` 后，执行 `docker compose up -d --force-recreate` 使环境变量生效；本地运行时重启 MCP 进程。图像输入与模型接口依据 [OpenAI 官方视觉文档](https://developers.openai.com/api/docs/guides/images-vision) 和 [GPT-4o 模型文档](https://developers.openai.com/api/docs/models/gpt-4o)。

打开 **http://127.0.0.1:9999** 查看上游小智客户端管理界面。该界面管理工具与连接配置；端口默认只绑定本机。接入点和缓存写入 Docker 数据卷，截图位于数据卷的 `captures/` 下。

也可以本地构建：

```bash
docker compose up --build -d
```

健康检查验证管理界面已启动；摄像头连接、VLM 服务和实验设备需在配置完成后分别联调。

## 本地开发

需要 Node.js 22+、Python 3.11+ 与 [uv](https://docs.astral.sh/uv/)。建议使用 Python 3.12。

```bash
npm ci
uv sync --frozen --python 3.12
cp .env.example .env
# 在 .env 中设置 Python 路径：Windows 为 .venv/Scripts/python.exe，Linux 为 .venv/bin/python。
npm start
```

如果只想将摄像头工具接入其他 MCP 客户端，将其启动命令配置为：

```json
{
  "mcpServers": {
    "lab-robot-camera": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env-file", "/absolute/path/to/.env", "ghcr.io/zbbio/lab-robot:v0.2.0", "node", "camera/node/camera.js"]
    }
  }
}
```

`stdio` 需要保留输入连接；使用 `-i`，不要加 `-t`。此模式不会启动小智桥接或管理页面。

## 工具

| 工具 | 行为 |
| --- | --- |
| `camera_tool(question)` | 获取当前画面，将图片与问题发送给云端 VLM |
| `camera_status()` | 检查 ONVIF 连接，不执行云台动作 |
| `capture_image(filename?)` | 保存 JPEG，不调用 VLM |
| `adjust_the_camera_view_tool(direction, speed)` | PTZ 开启后提供，移动一秒后停止 |
| Opentrons 工具 | 来自 `opentrons-mcp@1.0.24`，由桥接客户端加载 |

PTZ 默认关闭，设置 `ONVIF_CAMERA_PTZ_ENABLED=true` 后注册。设置 `OPENTRONS_ENABLED=false` 可只运行摄像头接入。Docker 使用 headless 图像依赖，不暴露本地 GUI 实时预览工具。

## 验证与发布

```bash
uv run python -m unittest discover -s tests -p 'test_*.py' -v
# 运行 npm test 前，保证 PYTHON_VENV_PATH 指向上述虚拟环境中的 Python。
npm test
npm run smoke
python scripts/check_release.py
```

CI 验证小智网关与 OpenAI 直连的请求格式、模型、图片、问题、认证与超时设置，缺失配置、异常响应和密钥脱敏，本地截图，MCP 初始化和工具发现；然后构建镜像，运行容器 MCP 测试与管理界面启动检查。测试使用模拟响应，不连接真实摄像头、云端 VLM 或机器人，也不执行实验协议。

与 MedAgent 的发布方式一致：推送版本标签后重跑验证，全部通过再发布 `ghcr.io/zbbio/lab-robot:<版本>`。普通代码推送只运行 CI。

```bash
git tag v0.2.0
git push origin v0.2.0
```

升级或回退时，在 `.env` 修改 `LAB_ROBOT_IMAGE` 为目标版本，再执行 `docker compose pull && docker compose up -d --no-build`。保留同一个数据卷即可保留运行数据。

## 来源与许可

本项目基于小智客户端生态整理实验室设备接入，相关来源及保留的许可见 [NOTICE](NOTICE) 和 [LICENSE](LICENSE)。演示媒体用于展示项目效果；不包含生产认证信息或实验原始数据。