# VirtualRobot

**Repository Path**: c21w/virtual-robot

## Basic Information

- **Project Name**: VirtualRobot
- **Description**: 我的小车
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-29
- **Last Updated**: 2026-06-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🤖 基于 LangChain 的多模态虚拟机器人小车 (Virtual Robot Car)

这是一个纯软件运行的“虚拟机器人小车”Demo。在没有任何物理硬件的情况下，该项目利用您电脑的屏幕（Pygame 画布）、麦克风、扬声器和摄像头（或虚拟占位图）来模拟机器人的各种传感器和执行器，并基于 LangChain 框架与大语言模型（如 `gpt-4o-mini`）构建了具备“听、说、看、动”能力的具身智能（Embodied AI）控制中枢。

---

## 🌟 核心功能

1. **虚拟小车状态机与 2D 模拟器**：在内存中维护小车的 $(X, Y)$ 坐标和朝向角度，利用 `Pygame` 在独立线程中实时绘制小车。
2. **多模态环境感知与表达**：
   * **眼睛 (Camera)**：调用 OpenCV 捕获摄像头画面并转换为 Base64 格式，供大模型进行视觉场景分析（若无摄像头，可自动生成虚拟模拟画面）。
   * **耳朵 (Ear)**：通过麦克风录入语音并借助 `SpeechRecognition` 进行语音识别（若无麦克风或依赖缺失，可降级为键盘输入）。
   * **嘴巴 (Mouth)**：借助 `edge-tts`（微软高拟真语音合成）将大模型的思考结果实时转为语音播放。
3. **LangChain 智能决策大脑**：构建具备对话记忆（Memory）的 `Tool Calling Agent`，能听懂人类的模糊自然语言，并将其拆解、规划为一系列具体的工具调用（移动、旋转、拍照、联网搜索等）。

---

## 📂 项目目录结构

```text
virtual_robot_car/
│
├── config.py                 # 配置文件：管理 API Key、API 代理地址与模型名称
├── main.py                   # 主程序入口：协调多线程，运行 “听->想->动/说” 闭环控制
├── README.md                 # 项目说明文档
│
├── robot/                    # 1. 机器人物理与渲染模块
│   ├── __init__.py
│   ├── state.py              # 虚拟小车状态机 (VirtualRobot 类)
│   └── simulator.py          # Pygame 模拟窗口 (RobotSimulator 类)
│
├── perception/               # 2. 感知与表达模块（眼睛、耳朵、嘴巴）
│   ├── __init__.py
│   ├── camera.py             # 视觉：OpenCV 摄像头捕获与编码
│   ├── ear.py                # 听觉：麦克风录音与语音识别 (STT)
│   └── mouth.py              # 表达：文本转语音并播报 (TTS)
│
└── agent/                    # 3. 决策大脑模块（LangChain 框架）
    ├── __init__.py
    ├── tools.py              # 机器人动作及感知工具封装 (LangChain Tools)
    └── brain.py              # 带上下文记忆的 Tool Calling Agent
```
## 🛠️ 安装与配置

### 1. 安装依赖库
#### 在您的终端中执行以下命令安装运行所需的第三方库：
```text
uv add pygame opencv-python SpeechRecognition langchain langchain-openai langchain-community duckduckgo-search edge-tts
```
#### 注意：部分系统在安装麦克风依赖（PyAudio）时可能遇到困难。如果安装失败无需担心，程序在运行时会自动捕获异常并降级为键盘打字输入，不影响核心逻辑的运行。

### 2. 配置大模型参数
#### 打开根目录下的 config.py，配置您的大模型 API Key。建议使用支持 Tool Calling 与多模态视觉的 gpt-4o-mini：
```text
# config.py

# 请配置您的大模型 API 密钥和接口地址
OPENAI_API_KEY = "您的_API_KEY_在这里"
OPENAI_BASE_URL = "https://api.openai.com/v1"  # 如果使用国内中转代理，请在此替换

MODEL_NAME = "gpt-4o-mini"
```


## 🛠🚀 运行与测试
#### 项目采用了分阶段渐进式开发。您可以依次运行以下测试脚本以验证各模块的完备性：
### 阶段 1：测试物理状态与 Pygame 渲染
#### 验证小车在内存中的位移算法是否正确，以及 Pygame 窗口是否能平滑绘制小车的正方形运动轨迹。
```text
# 运行第一阶段测试：
python test_stage1.py
```

### 阶段 2：测试感官（眼睛、耳朵、嘴巴）
#### 测试微软 TTS 语音合成、OpenCV 拍照存盘以及麦克风录音解析是否正常。
```text
# 运行第二阶段测试：
python test_stage2.py
```

### 阶段 3：测试大模型工具调用与决策
#### 测试大模型是否能将一长串复杂的自然语言（例如：“先前进 100 再向右转 90 度然后往回倒车 50”）拆解并自动触发对应的物理工具。

```text
# 运行第三阶段测试：
python test_stage3.py
```

### 阶段 4：启动系统主控（完整闭环）
#### 运行主程序，开启您的多模态虚拟机器人小车声控之旅！
```text
python main.py
```

## 💬 推荐测试指令
#### 在主程序 main.py 运行时，您可以尝试向小车发送以下指令：

### 单步移动："向前移动 120 像素。"
### 复杂复合指令："帮我走一个 L 型：先向前移动 100 像素，然后向右急转弯 90 度，接着再向前移动 50 像素。"
### 多模态视觉观察："你现在看看周围，向我汇报你看到了什么？" 或者 "帮我拍照看看你面前有什么。"
### 联网检索与知识问答："你知道今天东京的气温怎么样吗？" 或者 "帮我查一下最近有什么科技新闻吗？"
### 结束交互："再见"、"退出" 或 "拜拜"。