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）

---

七、测试

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。

启动：

/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

开机自启（可选）

sudo nano /etc/systemd/system/robot-bridge.service

[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

sudo systemctl enable robot-bridge
sudo systemctl start robot-bridge

---

九、Windows 端启动

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

方式二：源码运行

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，无需额外安装。