如果要验证一个“移动到目标附近、抓取物体、运输并投放”的机器人流程，除了看最终动画，还需要知道：动作推进到了哪一步，暂停后能否继续，不同控制入口看到的状态是否一致，以及视觉函数到底输出了什么。

这次分享的 PickGo Lab，围绕这些问题整理了一个轻量实验环境。它包含浏览器里的底盘与机械臂运动学仿真、本机 Python 服务、MCP 工具入口，以及复用原代码的视觉验证页面。

项目地址：[williamtymhuabian/pickgo-lab](https://github.com/williamtymhuabian/pickgo-lab)。

当前项目适合学习和验证任务流程、初步几何可达性及接口联调。自动搬运使用简化场景中的几何位置；视觉检测可以单独验证，尚未接入搬运动作的反馈闭环。下面按实际运行方式介绍。

 一、先跑起来：离线演示与共享仿真

最简单的体验方式，是下载项目后用现代浏览器打开根目录的 `index.html`。这个页面可以单文件离线运行，无需安装 Python、Node.js 或 npm 依赖。

页面中可以选择红、蓝、黄方块，观察机械臂取物、托盘固定、底盘绕障运输和投放流程，也可以手动调姿、暂停、继续、停止和导出状态。

如果希望网页、Python 脚本和 MCP 客户端控制同一个场景，则需要运行本机服务。先准备 Python 3.10+ 和 Node.js 18+，再执行：

git clone https://github.com/williamtymhuabian/pickgo-lab.git
cd pickgo-lab
python -B app.py

浏览器打开 [本机运动仿真页面](http://127.0.0.1:8767/)。服务仅监听本机地址，其他读者需要在自己的电脑上启动；这个地址不是公共在线演示。

共享运动仿真不需要安装 NumPy 或 OpenCV，也不需要执行 `npm install`。视觉功能的依赖可以按需安装。

如果默认端口被占用，可以运行 `python -B app.py --port 8768`，并把浏览器和 MCP 配置中的端口一起改成 8768。按 Ctrl+C 可以关闭服务。

二、一个搬运任务怎样推进

运动核心在 `simulator-core.js` 中，包含简化四轴机械臂与差速底盘模型、正逆运动学、底盘 A* 寻路，以及任务状态机。

一段搬运任务会经过取物、放置到托盘、收臂、移动、再次取物、投放和收拢等动作。把这些动作组织成状态机，便于观察中间状态，也能处理重复启动、暂停和取消。

- `RUNNING`：任务正在推进。
- `PAUSED`：暂停，保持当前位置，之后可以继续。
- `SUCCEEDED`：后置条件校验通过，目标已投放且机械臂已收拢。
- `FAILED`：任务执行或后置条件校验失败。
- `CANCELED`：任务被停止，保留当前物体状态。

这里需要区分“停止”和“重置”。停止会保留当前状态；重置才恢复初始场景。持物过程中停止任务，不能直接假定物体已经回到原位。

底盘路径规划使用 A*，并按障碍膨胀后的间隙检查路径；运动中也有收臂互锁和底盘碰撞边界检查。机械臂仍是简化运动学模型，没有完整的机械臂碰撞检测，也不计算抓取力、摩擦和惯性。

三、让网页、Python 与 MCP 使用同一份状态

项目中的控制链路可以概括为：

网页操作 ───────────────────────→ app.py
Python 脚本 → utils.py ─────────→ app.py
MCP 客户端 → mcp_server.py
                    ↓
                 utils.py ─────→ app.py
                                    ↓
                           simulator-worker.cjs
                                    ↓
                            simulator-core.js

默认共享模式下，`app.py` 持有仿真进程，网页、Python 动作函数和 MCP 入口读取同一场景的状态。

`instance_id` 用来区分场景实例，`task_id` 用来区分某一次搬运。发起任务后，接口会立即返回任务标识，再通过 `get_robot_state` 查询运行结果。

任务标识也用于避免误判：如果查询时 `task_id` 已经改变或清空，说明原任务可能被重置或替换，不能据此宣布原任务成功。

在共享模式下，关闭网页或断开 MCP 客户端，不会取消已经被服务接收的任务。需要停止时，应显式调用停止操作。

如果只想用 Python 调用项目动作，可以先启动 `app.py`，再打开第二个终端执行现成示例：

python -B examples/pick_and_send.py

这个示例展示了初始化、启动红色目标搬运、按任务标识查询结果，以及超时或中断时停止对应任务的处理。

四、MCP 接入：把动作作为工具暴露出来

PickGo Lab 提供轻量的 stdio MCP 服务。下面是常见 `mcpServers` 配置形式，脚本路径需要替换成你自己电脑上的项目绝对路径：

{
  "mcpServers": {
    "pickgo-lab": {
      "command": "python",
      "args": [
        "-B",
        "C:/projects/pickgo-lab/mcp_server.py",
        "--server-url",
        "http://127.0.0.1:8767"
      ]
    }
  }
}

先运行 `app.py`，再让客户端启动 `mcp_server.py`。不同客户端的配置位置可能不同；仓库提供的是服务入口和配置示例，不能把这份 JSON 当作所有客户端通用的安装步骤。

当前可用工具包括：

- `get_capabilities`：读取当前仿真能力和限制。
- `get_robot_state`：查询场景与任务状态。
- `grab_and_send`：启动指定目标的搬运任务。
- `pause_task`、`resume_task`、`stop_task`：管理任务生命周期。
- `reset_scene`：恢复初始场景。
- `det_color`：对传入图像运行原视觉检测函数。

例如，`grab_and_send` 的工具参数可以是：

{
  "target": "blue",
  "speed": 3
}

目标支持 `red`、`blue`、`yellow`，速度支持 1、3、6。启动成功后要继续查询状态，不能把“工具调用已返回”当作“物体已搬运完成”。通信失败时也不自动重发动作，应先查询当前状态。

当前服务实现经典 MCP 的 stdio/tools 子集，不是完整 MCP 实现。`task_id` 是本项目的业务字段，不代表支持 MCP tasks 扩展；本机 `/api/*` 接口也不是 MCP HTTP 传输端点。具体范围见仓库的 [MCP 接入说明](https://github.com/williamtymhuabian/pickgo-lab/blob/main/docs/mcp.md)。

另有 `--standalone` 模式，会建立独立场景；它与已经打开的网页不是同一个场景。需要网页与工具同步时，使用前面的共享模式。

五、视觉验证：复用原函数，单独检查输入输出

如果需要视觉功能，在项目目录安装可选依赖后启动服务：

python -m pip install -r requirements.txt
python -B app.py

然后打开 [本机视觉验证页面](http://127.0.0.1:8767/vision.html)。

页面支持合成 RGB-D 测试图、本地 RGB 图片、目标颜色与位置变化，以及无目标、无效深度等情况。输出包括检测框、中心、像素偏差、原始矩形角度和有效深度。

项目复用 `legacy/utils.py` 中的 `det_color`、`det_rect` 和 `col_dict_daylight_shelf_1`。适配层通过 AST 白名单提取指定定义，不导入整个原模块，避免触发原工程的 ROS、串口或机器人初始化。

原文件按字节保留，来源清单记录了 SHA256，测试也会检查一致性。原代码与新实现的范围在 README 中分别说明，原始代码的归属沿用源项目。

视觉验证当前使用可控二维 RGB-D 输入，没有生成三维场景的真实相机投影，也没有把检测结果用于自动搬运闭环。没有有效深度时，接口不会补造距离。这样可以先把函数本身的行为检查清楚，再讨论后续系统集成。

六、如何验证这个项目

仓库附带三组测试：运动核心、视觉接口和 MCP／共享状态集成测试。本次整理后，27 项现有测试已在本机运行通过。

node tests/simulation.test.cjs
python -B tests/test_vision.py
python -B tests/test_mcp.py

- 运动测试 9 项：检查正逆运动学、绕障、三种目标搬运、互锁、暂停和取消等。
- 视觉测试 9 项：检查颜色、中心、角度、有效深度、空轮廓和原文件完整性等。
- MCP 与集成测试 9 项：检查协议握手、工具参数、任务生命周期、本机接口，以及网页与 MCP 共用状态等。

这些测试验证的是当前程序的行为，不代表实体机器人上的效果。实际运行环境、边界条件和硬件接入仍需分别验证。

七、当前阶段与后续方向

这一版把离线演示、共享控制和视觉函数验证整理到了同一个项目中，方便分别运行、观察和复现。原生厂家 SDK、ROS 工程和真实设备后端没有包含在这个轻量仓库里。

后续可以继续探索三件事：生成与三维场景一致的相机投影；让检测结果参与搬运反馈；在完善模型、限制和状态校验后，通过独立后端接入真实设备。这些属于后续工作，当前版本尚未实现。

如果你对底盘与机械臂协作、任务状态机或 MCP 工具接入感兴趣，可以从离线页面开始，再尝试本机共享模式。也欢迎围绕具体输入、操作步骤和实际结果交流。

源码与运行说明：[PickGo Lab](https://github.com/williamtymhuabian/pickgo-lab)。

---
原文：https://williamtymhuabian.github.io/personal-site/#/post/pickgo-lab
作者：Williamtym