# HLORO-AI控制助手 — 项目说明

> **版本**: v0.3.0

---

## 一、项目概述

HLORO-AI控制助手 是一套基于 MCP (Model Context Protocol) 的工业机器人控制系统。通过 DeepSeek 大语言模型把自然语言翻译为机器人控制指令，控制 HRB400 三轴 SCARA 工业机械臂。

**核心能力**：
- 自然语言 → 机器人运动指令（DeepSeek V4 驱动）
- PySide6 桌面 GUI（微信风格聊天界面）+ CLI 客户端
- 安全边界校验 + 急停锁机制
- MCP Server：STDIO / HTTP / OAuth 2.1 三种传输模式

> ⚠️ **当前状态**：`src/server.py` 目前固定运行 **仿真模式**（`SimRobotArm`）。仓库内含远程桥接（`robot_bridge.py`）与硬件适配器（`robot_remote.py` / `robot_hardware.py`），但**尚未接入 server.py**。下文的"远程控制"为**目标架构**，接线后生效。

---

## 二、系统架构

### 目标架构（远程控制，待接线）

```
Windows PC (192.168.1.100)               Raspberry Pi (192.168.1.101)
┌────────────────────────────┐  HTTP     ┌──────────────────────────┐
│ robot-assistant.exe        │◄────────►│ robot_bridge.py          │
│  ├─ GUI (PySide6)          │  :3000    │  ├─ HTTPServer :3000     │
│  ├─ MCP Server (FastMCP)   │           │  ├─ robot_lib 翻译层     │
│  ├─ RemoteRobotArm ⚠️未接入 │           │  └─ numpy→JSON 安全转换  │
│  └─ DeepSeek API (云端)    │           │           ↓              │
└────────────────────────────┘           │  pi_share → CAN → HRB400│
                                         └──────────────────────────┘
```

### 当前实际链路（仿真）

```
GUI / CLI → STDIO → server.py (FastMCP) → SimRobotArm（内存状态）
                                                ↓
                                        SafetyChecker 边界校验
```

---

## 三、运行模式

| 模式 | 适配器 | 接线状态 |
|------|--------|---------|
| **sim**（默认） | `SimRobotArm` | ✅ 已接入 server.py |
| remote | `RemoteRobotArm` + Pi `robot_bridge.py` | ⚠️ 模块已开发，未接入 |
| hardware | `HRB400RobotArm`（Pi 本地直连） | ⚠️ 模块已开发，未接入 |

三个适配器方法签名完全一致，接入 `server.py` 时按 `ROBOT_MODE` 选择即可，其余代码零改动。

---

## 四、项目文件结构

```
D:\mcp-robot-server\
├── main.py                    MCP Server 入口
├── robot_bridge.py            ★ Pi 端桥接服务（零依赖 stdlib）⚠️ 未接入
├── build.spec                 PyInstaller 打包配置
├── config.yaml                HRB400 工作范围 / 速度 / 硬件参数
├── .env                       环境变量（ROBOT_MODE / BRIDGE_URL / DEEPSEEK_API_KEY）
├── .mcp.json                  Claude Code MCP 连接配置
│
├── src/
│   ├── server.py              ★ FastMCP Server: 11 tools + 4 resources + 3 prompts
│   ├── robot.py               SimRobotArm（仿真模式，当前唯一接入）
│   ├── robot_remote.py        RemoteRobotArm（HTTP 远程桥接）⚠️ 未接入
│   ├── robot_hardware.py      HRB400RobotArm（Pi 本地直连）⚠️ 未接入
│   ├── safety.py              SafetyChecker 安全边界校验
│   ├── types.py               Position / RobotStatus / ActionResult
│   ├── config.py              AppConfig（config.yaml 驱动）
│   ├── logging.py             日志输出（stderr）
│   └── auth/                  OAuth 2.1 授权（LocalJWT / Introspection）
│
├── gui/                       PySide6 桌面端（聊天 + 状态面板）
├── client/                    CLI 客户端（DeepSeek 驱动）
├── tests/                     单元测试（103 passed, 4 skipped）
├── dist/                      robot-assistant.exe + HLORO-AI 部署包（未跟踪）
└── offline_mcp/               离线安装 wheels（未跟踪）
```

---

## 五、MCP 工具列表（11）

| 工具 | 参数 | 说明 |
|------|------|------|
| `move_to` | x, y, z, speed? | 绝对移动 (mm) |
| `move_relative` | dx, dy, dz, speed? | 相对移动 (mm) |
| `move_joint` | joint_id, angle | 单关节旋转 (°) |
| `home` | - | 回零 |
| `stop` | - | 减速停止 |
| `emergency_stop` | - | 急停 + 锁定 |
| `unlock` | - | 解除锁定 |
| `gripper_open` | - | 张开夹爪 |
| `gripper_close` | - | 夹紧夹爪 |
| `ping` | - | 连接检测（只读） |
| `get_status` | - | 完整状态（只读） |

**资源（4）**：`robot-arm://status` / `//position` / `//config` / `//dashboard`（HTML 仪表盘，3 秒自动刷新）
**Prompt（3）**：`robot-home` / `robot-status` / `robot-emergency`

---

## 六、安全机制

| 层级 | 机制 |
|------|------|
| 坐标校验 | SafetyChecker（服务器端预检） |
| 速度校验 | 10 ~ 200 mm/s 范围限制 |
| 急停锁 | 软件 `locked` 状态，急停后所有运动被拒，需 `unlock` |
| 工具注解 | `readOnlyHint` / `destructiveHint` / `idempotentHint` 供客户端识别 |
| 错误码 | 标准 JSON-RPC 错误码（-32602 参数 / -32603 内部 / -32000 急停锁） |
| OAuth | HTTP 模式可选 Bearer token 验证（Local JWT / RFC 7662 Introspection） |

---

## 七、测试

```bash
cd D:\mcp-robot-server
uv run pytest tests/ -v        # 103 passed, 4 skipped
```

测试覆盖：仿真机械臂（`test_robot.py`）、安全边界（`test_safety.py`）、MCP 集成（`test_server.py`）、OAuth（`test_auth.py`）、HTTP+OAuth 端到端（`test_http_server.py`）、客户端（`test_client.py`）、硬件适配器（`test_robot_hardware.py`，需 pi_share 环境）。

---

## 八、Pi 端部署（目标架构，待接线）

### robot_bridge.py

**位置**：Pi 上 `/home/hr400/robot_bridge.py`
**依赖**：仅 pi_share 项目的 .venv（无需额外安装）
**功能**：监听 `0.0.0.0:3000`，接收 JSON-RPC 调用，翻译为 robot_lib API 调用，自动转换坐标单位（m ↔ mm），numpy 数组安全转 JSON。

**启动**：
```bash
/home/hr400/HRobotStudiov1.0-rc.2/.venv/bin/python3 /home/hr400/robot_bridge.py
```

启动成功输出：
```
Robot Bridge -> 0.0.0.0:3000
  pi_share: /home/hr400/HRobotStudiov1.0-rc.2
  robot online: True
```

### 开机自启（可选）

```bash
sudo nano /etc/systemd/system/robot-bridge.service
```
```ini
[Unit]
Description=HLORO Robot Bridge
After=network.target

[Service]
Type=simple
User=hr400
ExecStart=/home/hr400/HRobotStudiov1.0-rc.2/.venv/bin/python3 /home/hr400/robot_bridge.py
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
```
```bash
sudo systemctl enable robot-bridge
sudo systemctl start robot-bridge
```

---

## 九、Windows 端启动

**方式一：直接运行 exe**
双击 `dist\robot-assistant.exe`

**方式二：源码运行**
```bash
cd D:\mcp-robot-server
uv run python gui/main.py        # GUI 桌面端
uv run python main.py            # MCP Server（STDIO）
uv run robot-client              # CLI 客户端
```

> 注意：源码运行时 server 为**仿真模式**，`get_status` 返回内存中的模拟位置。接入真实机械臂需先完成"运行模式"接线。

---

## 十、常见问题

| 问题 | 解决 |
|------|------|
| GUI 无法连接服务端 | 检查服务端是否能启动：`uv run python main.py` |
| 位置数据全为 0 | 仿真模式正常现象；接真机需接线远程适配器 |
| DeepSeek API 错误 | 检查 `.env` 中 `DEEPSEEK_API_KEY` 是否有效 |
| 打包 exe | `uv run pyinstaller build.spec --noconfirm` |
| 测试失败 | 确认 `config.yaml` 为 HRB400 工作范围（X[-50,300] 等） |

---

## 十一、依赖清单

**Windows 端（uv）**：`httpx, mcp[cli], openai, pyjwt, python-dotenv, pyyaml, pyside6, pyinstaller, numpy`
**Pi 端（robot_bridge.py）**：仅需 pi_share 项目已有的 .venv，无需额外安装。