RoboCasa 仿真控制插件 for DeepSeek Harness

前言¶

在用对话控制机器人仿真时，需要实时感知场景、移动机械臂、检查任务状态。现有方案要么需要自己写 Python worker，要么接口不统一。robocasa-control 把 RoboCasa 的仿真环境封装成一组工具，通过 JSON-RPC 与 DSH Agent 对话。

这是什么¶

这是 Chat-driven RoboCasa simulation control plugin for DeepSeek Harness。由 only-one-over 维护，将 MuJoCo 仿真、运动规划、感知定位和 Web 监控整合成一个 DSH 插件。它解决的是「如何从对话流里直接操控 RoboCasa 场景」的问题，让 Agent 不需要自己维护仿真进程，也不需要自己实现运动控制逻辑。

核心功能¶

仿真进程与状态¶

插件内部维护一个常驻的 worker 进程（Python），负责运行 RoboCasa / Robosuite。DSH Agent 通过 index.js 注册的工具与 worker 通信，使用 JSON 行协议（JSON-RPC over stdio）。仿真状态在进程内保持连续，多次工具调用之间物理状态不会丢失。

结构如下：

robocasa-control/
├── index.js          # Host 插件：注册工具，管理 worker 进程
├── worker.py         # 常驻仿真进程
├── cordis.patch.yml  # Loader 配置
└── locale/{en,zh}.json

环境体检¶

robocasa_doctor 工具会逐项检查环境：

Python >= 3.10
numpy / mujoco / robosuite / robocasa 能否 import 及版本
资产目录是否存在
剩余磁盘空间
渲染后端（EGL / MUJOCO_GL）

检查结果用 ✅ / ⚠️ / ❌ 标记，失败时会给出对应的安装命令。deep=true 会额外建一个 64×64 的场景并渲染一帧，用于验证整条链路。

场景管理¶

robocasa_open 打开场景，参数包括 task / seed / layout / style / camera / 分辨率，并创建运行目录与 manifest。

每次 open 都会生成一个运行目录：

<run dir>/
├── manifest.json     # 场景、版本、统计、事件
└── frames/           # 截图

manifest.json 记录场景配置、环境版本（python / numpy / mujoco / robosuite / robocasa）、步数、截图数、move/act/rotate/restart/reset 次数、事件时间线（上限 200 条）。

感知与定位¶

robocasa_locate 是感知层的第一个接口，返回结构化几何而不是像素：

物体：位置、包围盒尺寸、top_z、pre_grasp、grasp、长轴 yaw
夹具：位置、尺寸、interior 各层区域中心

默认返回 ground truth（读仿真状态），也可以用 backend="vision" 跑开放词表检测器（grounding-dino-tiny）。视觉检测会返回多个候选，每个带 2D 框、分数、像素、深度和反投影出的世界坐标。插件不会自动替调用方选实例，调用方需要根据场景和置信度做选择。

运动控制¶

robocasa_move(x, y, z)：闭环移动到世界坐标（米），可指定绝对朝向（yaw_deg 或四元数 quat）。
robocasa_rotate(angle_deg)：闭环相对旋转（度），默认容差 0.03 rad。
robocasa_act(dx, dy, dz)：原始控制器量（归一化，1.0 ≈ 5 cm/步），方向已从世界系旋到 base 系。
robocasa_grasp(yaw_deg, offsets=[0, -30, 30])：多假设抓取，依次尝试不同角度，用「物体是否跟随」验证。

坐标系约定：robocasa_move / robocasa_status 使用世界坐标。robocasa_act 的输入参考系是 base，内部用 origin_ori 把世界增量旋到 base 系。

投放与脱困¶

robocasa_drop 把持有的物体送到指定点上方再松爪，用于手腕下不去的容器（如水槽盆）。x/y 给容器中心，z 给开口高度而不是底部。

move 支持卡死脱困：记录伺服里实际走了多远，失败后依次尝试退让点（沿背离目标方向退 8 cm、14 cm，再退上方 10 cm、左上 6 cm），每个退让点之后再重新伺服一次原目标。返回里的 recovered 表示是否是脱困后才成功的。

运动规划¶

move 先直接伺服；残差超过阈值时自动用 RRT-Connect 规划一条无碰撞绕行路径。手里的物体按「附着碰撞体」处理，它和环境的接触算碰撞，但不会被误判成机械臂自身碰撞。

插件还提供 planner.py 离线验证脚本，重实现了 MuJoCo 之上的运动规划栈：正运动学 / 雅可比、碰撞检测、逆运动学（DLS）、采样规划（RRT-Connect + 捷径化）、轨迹（梯形速度限制）。test_planner.py 是离线验证脚本，不需要启动插件。

状态与生命周期¶

robocasa_status：返回步数、末端位姿、任务成功、物体世界坐标与包围盒尺寸。
robocasa_reset：新开一局（重新随机化场景），并把 restart 锚点移到新一局开头。
robocasa_restart：回到当前这一局的开头（open 或最近一次 reset 时的快照），逐位还原。
robocasa_close：关闭仿真，释放进程。

Web 面板¶

插件自带一个 DSH 内置面板：侧栏图标 → 主区域显示「RoboCasa 仿真」。

实时画面：GET /robocasa/frame.mjpg（MJPEG，320×240，约 11 fps）
实时状态：GET /robocasa/state（每秒轮询）
预览模式按钮：POST /robocasa/preview {"mode": "third_person"}

控制面板提供 X± / Y± / Z±（末端点动 5 cm）、转 ±15°（绕竖直轴）、开爪 / 合爪、抓取目标、新开一局 / 回开局 / 关闭场景等按钮。动作层使用绝对关节位置控制（JOINT_POSITION + input_type: “absolute”，kp 400），13 维动作空间（右臂 7 + 夹爪 1 + 底盘 3 + 躯干 1）。末端稳态误差约 0.6 mm，比 OSC 的 10–20 mm 更精。

安装与启用¶

从 GitHub 安装（推荐）：

pnpm add github:only-one-over/robocasa-control

或直接在 DSH 里：

plugin_manager install_bundle github:only-one-over/robocasa-control

安装后需要在 cordis.patch.yml 中配置：

- insert:
    - id: robocasa-control
      name: '@local/robocasa-control'
      config:
        pythonPath: /home/zhu/miniconda3/envs/robocasa/bin/python
        shotsDir: /home/zhu/桌面/harness-skills-demo/robocasa-shots

可选参数：workerScript、cwd。

典型用法¶

打开场景并体检：

robocasa_open(task="pick_place_cereal", seed=5, camera="robot0_eye_in_hand")
robocasa_doctor(deep=true)

定位物体并移动：

loc = robocasa_locate("cereal_box")
robocasa_move(x=loc.world.x, y=loc.world.y, z=loc.world.z, yaw_deg=loc.long_axis_yaw)
robocasa_rotate(-90)
robocasa_act(dx=0.05)  # 闭合夹爪

多假设抓取：

robocasa_grasp(yaw_deg=0, offsets=[-30, 30])

检查状态：

status = robocasa_status()
print(f"步数: {status.step}, 成功: {status.success}")

回开局：

robocasa_restart()

适用场景与注意¶

适合在 DSH Agent 开发中需要直接操控 RoboCasa 仿真环境的场景：需要实时感知、精细运动控制、任务验证和日志记录。

注意：插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。RTX 50 系（sm_120）必须用 CUDA 12.8 的 PyTorch 构建，否则会退回 CPU。视觉检测首次调用（含加载）约 2.4 秒，后续调用在 GPU 热状态时可到 93 ms。

总结¶

robocasa-control 把 RoboCasa 的仿真环境完整接入 DSH，提供环境体检、场景管理、感知定位、运动控制、状态监控和 Web 面板。开发者可以通过对话流直接操控仿真场景，而不需要自己维护进程和实现运动逻辑。完整文档见 GitHub 仓库。