# isaaclab-soarm101

Adopt this skill: https://proskills.md/skills/other/osrbot-seir

Page: https://proskills.md/skills/other/osrbot-seir
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 4120
sha: 8e94f13581313b0ce619c37490f45edf03cde7b6
upstream: https://github.com/osrbot/seir/blob/HEAD/SKILL.md

````text
---
name: isaaclab-soarm101
description: 通过 HTTP API 控制 IsaacLab 仿真中的 SO-ARM101 机械臂
emoji: 🦾
requires:
  bins:
   - curl
---

# IsaacLab 机械臂控制

通过 HTTP API 控制运行在 IsaacLab 仿真中的 SO-ARM101 6自由度机械臂

## 配置

机械臂服务器地址:`http://127.0.0.1:8000`

## 可用命令

### 1.获取机械臂状态(每次操作前必须先执行)

在发送任何运动指令前，先查看当前关节位置:

```bash
curl -s http://127.0.0.1:8000/state
```

返回 JSON，包含 `joint_positions` (6个关节角度，单位弧度)， `joint_velocities` (关节速度)
`gripper_position` (夹爪位置) 和 `timestamp` (时间戳)。

## 2.移动手臂 - 关节位置控制

发送6个关节角（单位弧度）:

```bash
curl -s -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command_type":"joint_position","target":[J1,J2,J3,J4,J5,J6]}'
```

添加 'duration' 参数实现平滑运动 (单位秒):

```bash
curl -s -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command_type":"joint_position","target":[J1,J2,J3,J4,J5,J6],"duration":2.0}'
```

### 3.夹爪控制

打开夹爪：
```bash
curl -s -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command_type":"gripper","target":[1.0]}'
```

关闭夹爪：
```bash
curl -s -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command_type":"gripper","target":[0.0]}'
```

### 4. 回到初始位置

返回默认安全姿态：
```bash
curl -s -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command_type":"home"}'
```

### 5.等待指令

在多步骤任务中，插入等待时间 (单位秒):

```bash
curl -s -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command_type":"wait","duration":1.5}'
```


### 6.重置仿真
重置整个仿真环境：
```bash
curl -s -X POST http://127.0.0.1:8000/reset
```

### 7.健康检查
```bash
curl -s http://127.0.0.1:8000/health
```

### 8.获取机械臂配置信息
```bash
curl -s http://127.0.0.1:8000/config
```

## SO-ARM101 关节参考

|关节|名称 |功能 | 大致范围(弧度)|
|J1|shoulder_pan|底座旋转(左右转动)|-3.14 到 3.14|
|J2|shoulder_lift|肩部俯仰(前后倾斜)|-1.57 到 1.57|
|J3|elbow_flex|肘部弯曲|-1.57 到 1.57|
|J4|wrist_flex|腕部俯仰|-1.57 到 1.57|
|J5|wrist_roll|腕部旋转|-3.14 到 3.14|
|J6|gripper|夹爪 (0.0=打开, 0.5=关闭)|0.0 到 0.5|

默认初始位置(home): `[0.0, 0.0, 0.0, 1.57, 0.0, 0.0]`

## 重要规则

1.**操作前必须先获取状态** - 发送运动指令前，必须先调用 state 接口了解当前位置。
2.**小幅增量运动** - 每次每个关节的变化量不要超过 0.3-0.5 弧度，避免剧烈运动。
3.**使用 duration实现平滑运动** 例如`"duration":20`表示2秒内平滑过渡到目标位置。
4.**不要超出关节限位** - 超出范围的值会导致不可预测的行为。
5.**不确定时先回到初始位置** - 发送 `home` 指令回到已知的安全姿态。
6. 当用户说"抬起手臂"、"向左移动"、"向前伸"等自然语言时，根据上面的关节功能描述将其转换为关节角度变化。
7. 对于多步骤运动(如抓取物体)，规划并依次执行一系列小幅运动，每步之间检查状态确认到位。

## 交互示例

用户："把机械臂抬起来"

操作步骤：
1. 获取当前状态 - 读取关节位置
2. J2（肩部俯仰）控制上下运动，当前值可能是 0.0。要抬起手臂，增加J2（如 0.5）。
3. 发送 `{"command_type":"joint_position","target":[0.0, 0.5, 0.0, 1.57, 0.0, 0.0],"duration":2.0}`
4. 再次获取状态，确认手臂已经移动到位。

用户："打开夹爪"

发送: `{"command_type":"gripper","target":[1.0]}`

用户:“回到初始位置”

发送: `{"command_type":"home"}`
````

## File: README.md
size: 7228
sha: f995d6da65995585772f9b5bc1fc5700ba5c467b
upstream: https://github.com/osrbot/seir/blob/HEAD/README.md

````text
# IsaacLab x OpenClaw 机械臂控制

## 导语
欢迎来到本期项目！今天我们将解析如何将强大的物理仿真引擎 **IsaacLab** 与大模型智能体框架 **OpenClaw** 无缝链接起来。我们将深入探讨关键工程代码（`isaaclab_server_50.py` 和 `SKILL.md`），学习如何通过自然语言赋予机械臂“灵魂”。

---

## 核心议题一：如何设计 SKILL 将 IsaacLab 环境与 OpenClaw 链接？

### 1. 架构设计：HTTP API + 共享内存队列
要让 OpenClaw（大模型驱动的智能体）能无缝、非阻塞地控制基于 Python 的 IsaacLab 仿真环境，最解耦、最稳定的做法是**将仿真环境封装为一个独立的 HTTP 服务**。

在工程实现中（如 `isaaclab_server_50.py`），我们采用了**双线程架构**：
- **API 线程 (FastAPI + Uvicorn):** 监听 OpenClaw 智能体发送的 HTTP 请求（如经过大模型推理后生成的 `curl` 命令）。
- **仿真线程 (IsaacLab):** 运行严格的物理步进（如 120Hz）和场景渲染。

#### 交互架构图

```mermaid
graph TD
    A[OpenClaw Agent\n大模型推理] -->|生成相应的 curl 命令| B[FastAPI Server\n端口 8000]
    B -->|指令解析与校验格式| C((Command Queue\n线程安全保护))
    D[IsaacLab 仿真引擎\n物理仿真循环] -->|从队列非阻塞获取指令| C
    D -->|更新机械臂物理状态| E((Latest State\n全局共享数据字典))
    E -->|加锁供 GET /state 读取| B
```

### 2. 关键工程实现细节
- **指令队列解耦 (`command_queue`)**: 利用 Python 原生的 `queue.Queue`。API 接收到移动或抓取指令后，将其塞入队列即刻返回响应，这能绝对防止 API 阻塞底层的物理循环渲染。
- **状态读写锁 (`state_lock`)**: 使用 `threading.Lock()`，确保智能体在读取最新机械臂状态（关节位置、夹爪开合度）时，不与仿真渲染帧写入发生数据冲突（线程安全）。
- **无头与渲染支持 (`--headless`)**: 支持无头后台模式运行，便于部署于云端或容器；亦支持桌面级可视化展示效果。

---

## 核心议题二：对于使用自然语言控制机械臂，该如何设计一个 SKILL？

### 1. 什么是 SKILL？
在 OpenClaw 体系中，SKILL 就是大模型的“**使用说明书与物理常识库**”（对应代码库中的 `SKILL.md`）。它不仅要告诉大模型“有哪些 API 端点可以调用”，更要赋予它“物理直觉”。

### 2. SKILL 设计的三大核心要素
为了让自然语言（如：“把那个杯子拿起来，然后往左边放”）成功有效转化为精准的机械臂动作，我们在 `SKILL.md` 中设计了以下机制：

#### 要素 1：物理语义的拟人化映射（关节词典）
大模型不懂 `J1~J6` 在现实中对应什么运动，因此要将各关节的名称与人类空间认知强绑定：
> - **J1 -> shoulder_pan**: 底座左右旋转
> - **J2 -> shoulder_lift**: 肩部上下俯仰
> - **J3 -> elbow_flex**: 肘部弯曲
> - **J6 -> gripper**: 夹爪控制 (0.0=打开, 0.5=关闭)

#### 要素 2：严格的控制准则（System Prompt Rules）
大模型在推理时往往存在幻觉，必须在 SKILL 中制定出不容违背的强规则：
- **闭环强制规则:** 发送运动指令前，**必须先执行获取状态** (`GET /state`)，知晓自身绝对位置。
- **安全阈值规则:** 小幅增量运动，要求大模型每次修改每个关节的变化量不要超过 0.3-0.5 弧度（防穿模、防自死锁）。
- **平滑插值机制:** 提供 `duration` 属性（如设置为 `2.0` 秒），让控制器在此时间内平滑过渡目标点。
- **灾备退路:** 不确定指令效果时，优先发送 `home` 指令回到已知的安全姿态点。

#### 要素 3：思维链基准示例 (Few-Shot CoT)
在 SKILL 文件中手把手演绎如何分析人类指令：
> **用户：“把机械臂抬起来”**<br>
> **逻辑链：**<br>
> 1. 读取当前位置信息（例如此时 J2 = 0.0）。<br>
> 2. 词元解析：“抬起”对应 J2（即肩部俯仰角）增加。<br>
> 3. 构造请求：向 API 发送指令，目标角度在原有基础增加0.5，如 `{"command_type":"joint_position","target":[0.0, 0.5, 0.0, 1.57, 0.0, 0.0],"duration":2.0}`。<br>
> 4. 等待完成，再次轮询状态。

---

## 核心议题三：为了配合 SKILL 的使用，仿真环境需要提供哪些接口？

为了让大模型形成闭环的“感知 - 思考 - 行动”（Perceive - Think - Act），底层仿真环境（FastAPI端）需暴露出极其标准化的 RESTful 接口：

### 1. 状态感知接口 (Perception Layer)
- **获取实时状态 (`GET /state`)**
  返回机器人当前的 `joint_positions` (各关节弧度绝对值) 和 `gripper_position`。大模型进行上抬下放、左右平移推理时，极其依赖该当前位置快照。
- **获取机器人身位信息 (`GET /config`)**
  一次性读取机械臂种类信息：自由度 (DOF)、关节初始位置(`home_position`)。这使 SKILL 具有通用性，更换不同的末端执行器或机械臂型号（如 UR5，熊猫机械臂）时能够被感知。

### 2. 物理控制接口 (Action Layer)
- **统一入口 (`POST /command`)**
  提供一个强大的中央指令集，通过 `command_type` 字段进行逻辑分发处理：
  - `joint_position`: 配合 target 传入数组，控制最基础的正向运动(FK)。
  - `end_effector_delta`: 传入[dx,dy,dz]坐标差，在底层提供逆运动学(IK)解析逻辑，实现更贴近人类语言的高级指令！
  - `gripper`: 控制末端执行器。
  - `wait` & `home`: 用于大模型规划的连续性任务调度策略。

### 3. 环境生命周期与容错接口 (Lifecycle & Resilience)
- **环境重置 (`POST /reset`)**
  一旦大模型发现动作导致机械手臂碰撞，或者某个强化学习回合任务失败，能够以此接口快速将整个 IsaacLab 物理世界“恢复出厂设置”。
- **健康探针 (`GET /health`)**
  供 Agent 检测服务可用性，在心跳异常时告警，防止死板等待或一直报错。

### 底层转化 (数据 -> 渲染帧)
在 FastAPI 接收到合法的 HTTP 载荷后，底层的真实驱动代码：
```python
# 1. API线程放入请求对象 cmd_data
# 2. 仿真引擎获取该设定值
current_joint_cmd = command_queue.get_nowait()
target_joint_pos = torch.tensor([current_joint_cmd["target"]]).to(sim.device)

# 3. 驱动底层 Articulation 控制器
robot.set_joint_position_target(target_joint_pos)
sim.step()
scene.update(dt)
```

---

## 结语与作业
通过 **1 个解耦的 HTTP 物理仿真 Server** + **1 份高质量带“物理常识”的 SKILL 提示词指南**，我们完美解决了自然语言控制复杂空间自由度机械臂的痛点。大模型借助 SKILL 具备了空间推理能力，而 OpenClaw 借由 HTTP 协议长出了一双可以拨弄物理世界的“手”！

🎒 **课后作业**：目前 `end_effector_delta` (末端三维平移控制) 仅在 API 定义了结构，尝试在 IsaacLab 仿真循环中补全逆运动学（IK）算法的代码映射逻辑！
````

## File: isaaclab_server_45.py
size: 8946
sha: cd8805a1d7614ce22365dface48b269fa3499d66
upstream: https://github.com/osrbot/seir/blob/HEAD/isaaclab_server_45.py

```text
import argparse
import json
import threading
import time
from queue import Queue, Empty
from typing import Optional

import torch
import numpy as np
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel, Field
import uvicorn

# ----------------------------------------------------------------
# 数据模型
# ----------------------------------------------------------------

class RobotCommand(BaseModel):
    """控制指令"""
    command_type: str = Field(
        ..., 
        description="指令类型: joint_position | end_effector_delta | gripper | wait | reset | home"
    )
    target: Optional[list[float]] = Field(
        None, 
        description="目标值。joint_position: 6个关节角度(rad); "
                    "end_effector_delta: [dx, dy, dz] 末端位移增量(m); "
                    "gripper: [1.0]-打开 / [0.0]-关闭"
    )
    duration: Optional[float] = Field(
        None, 
        description="执行持续时间(秒)，用于插值平滑运动，默认立即执行"
    )

class RobotState(BaseModel):
    """机械臂状态"""
    joint_positions: list[float]
    joint_velocities: list[float]
    gripper_position: list[float]
    timestamp: float

class CommandResponse(BaseModel):
    status: str
    message: str
    queue_size: int

# ----------------------------------------------------------------
# 全局共享状态
# ----------------------------------------------------------------

command_queue: Queue = Queue(maxsize=100)
latest_state: dict = {
    "joint_positions": [],
    "joint_velocities": [],
    "gripper_position": [],
    "timestamp": 0.0
}
state_lock = threading.Lock()
robot_config: dict = {} # 启动后填充

# SO-ARM101 默认关节位置 (home pose)
SO_ARM101_HOME = [0.0, 0.0, 0.0, 1.57, 0.0, 0.0]

# ----------------------------------------------------------------
# FastAPI 应用
# ----------------------------------------------------------------

app = FastAPI(title="IsaacLab Robot Server", version="1.0")

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

@app.get("/health")
def health():
    return {"status": "ok", "sim_running": True, "timestamp": time.time()}

@app.get("/config")
def get_config():
    """返回机械臂配置，供 OpenClaw Agent 了解能力边界"""
    return robot_config

@app.get("/state", response_model=RobotState)
def get_state():
    with state_lock:
        return RobotState(**latest_state)

@app.post("/command", response_model=CommandResponse)
def send_command(cmd: RobotCommand):
    # --- 校验逻辑 ---
    if cmd.command_type == "joint_position":
        if cmd.target is None or len(cmd.target) != 6:
            raise HTTPException(status_code=400, detail="joint_position 需要 6 个关节角度值")
    
    elif cmd.command_type == "end_effector_delta":
        if cmd.target is None or len(cmd.target) != 3:
            raise HTTPException(status_code=400, detail="end_effector_delta 需要 [dx, dy, dz]")
    
    elif cmd.command_type == "gripper":
        if cmd.target is None or len(cmd.target) != 1:
            raise HTTPException(status_code=400, detail="gripper 需要 [1.0] 打开 或 [0.0] 关闭")
    
    elif cmd.command_type == "wait":
        if cmd.duration is None:
            raise HTTPException(status_code=400, detail="wait 指令需要 duration 参数")
    
    elif cmd.command_type in ["reset", "home"]:
        pass # 无需 target
    
    else:
        raise HTTPException(status_code=400, detail=f"未知 command_type: {cmd.command_type}")

    # --- 入队 ---
    if command_queue.full():
        raise HTTPException(status_code=429, detail="指令队列已满，请稍后再试")
    
    command_queue.put(cmd.model_dump())
    return CommandResponse(
        status="accepted",
        message=f"{cmd.command_type} 指令已入队",
        queue_size=command_queue.qsize()
    )

@app.post("/reset")
def reset_env():
    command_queue.put({"command_type": "reset", "target": None, "duration": None})
    return {"status": "accepted", "message": "重置指令已入队"}

# ----------------------------------------------------------------
# IsaacLab 仿真循环
# ----------------------------------------------------------------

def run_simulation(task_name: str, num_envs: int, headless: bool):
    """
    主仿真循环 - 使用底层 IsaacLab API 创建干净的机械臂场景。
    不使用 ManagerBasedRLEnv (因为它自带有 event/termination manager 导致自动 reset)。
    """
    # --- 初始化 Isaac Sim ---
    from omni.isaac.lab.app import AppLauncher
    launcher = AppLauncher(headless=headless)
    simulation_app = launcher.app

    import isaaclab.sim as sim_utils
    from omni.isaac.lab.scene import InteractiveScene, InteractiveSceneCfg
    from omni.isaac.lab.assets import ArticulationCfg, Articulation
    from omni.isaac.lab.sim import SimulationCfg
    from omni.isaac.lab.utils import configclass

    # 尝试导入 SO-ARM101 配置
    from isaac_so_arm101.robots.trs_so101.so_arm101 import SO_ARM101_CFG

    @configclass
    class RobotSceneCfg(InteractiveSceneCfg):
        """最简场景: SO-ARM101"""
        robot: ArticulationCfg = SO_ARM101_CFG.replace(
            prim_path="{ENV_REGEX_NS}/Robot"
        )

    # 配置仿真
    sim_cfg = SimulationCfg(dt=1.0 / 120.0)
    sim = sim_utils.SimulationContext(sim_cfg)
    sim.set_camera_view(eye=[2.5, 2.5, 2.5], target=[0.0, 0.0, 0.5])

    # 手动生成地面和灯光
    sim_utils.spawn_ground_plane("/World/GroundPlane", sim_utils.GroundPlaneCfg())
    sim_utils.spawn_light("/World/DomeLight", sim_utils.DomeLightCfg(intensity=2000.0, color=(0.75, 0.75, 0.75)))

    # 创建场景与机器人
    scene = InteractiveScene(RobotSceneCfg(num_envs=num_envs))
    robot = scene["robot"]

    sim.reset()
    
    # 填充机器人配置信息供 API 使用
    global robot_config
    robot_config.update({
        "robot_name": "SO-ARM101",
        "dof": robot.num_joints,
        "home_position": SO_ARM101_HOME,
        "joint_names": robot.joint_names
    })

    # 控制变量初始化
    target_joint_pos = torch.tensor([SO_ARM101_HOME], device=sim.device).repeat(num_envs, 1)
    wait_until = 0.0

    print("[INFO] IsaacLab 仿真循环已启动...")
    
    while simulation_app.is_running():
        # 1. 提取指令
        current_time = time.time()
        if current_time >= wait_until:
            try:
                cmd_data = command_queue.get_nowait()
                ctype = cmd_data["command_type"]
                
                if ctype == "joint_position":
                    target_joint_pos = torch.tensor([cmd_data["target"]], device=sim.device).repeat(num_envs, 1)
                elif ctype == "home":
                    target_joint_pos = torch.tensor([SO_ARM101_HOME], device=sim.device).repeat(num_envs, 1)
                elif ctype == "wait":
                    wait_until = current_time + cmd_data["duration"]
                elif ctype == "reset":
                    sim.reset()
                    scene.reset()
                # 注意：gripper 和 end_effector_delta 的具体 IK/位移逻辑需在此根据需求补全
            except Empty:
                pass

        # 2. 应用控制 (假设为关节位置控制)
        robot.set_joint_position_target(target_joint_pos)
        scene.write_data_to_sim()
        
        # 3. 物理步进
        sim.step()
        scene.update(dt=sim_cfg.dt)

        # 4. 更新全局状态
        with state_lock:
            latest_state.update({
                "joint_positions": robot.data.joint_pos[0].cpu().numpy().tolist(),
                "joint_velocities": robot.data.joint_vel[0].cpu().numpy().tolist(),
                "gripper_position": [0.04], # 示例值
                "timestamp": time.time()
            })

    simulation_app.close()

# ----------------------------------------------------------------
# 入口函数
# ----------------------------------------------------------------

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--task", type=str, default="Isaac-SoArm-101-Lift-v0")
    parser.add_argument("--num_envs", type=int, default=1)
    parser.add_argument("--headless", action="store_true", default=False)
    args = parser.parse_args()

    # 启动 API 线程
    server_thread = threading.Thread(
        target=lambda: uvicorn.run(app, host="0.0.0.0", port=8000), 
        daemon=True
    )
    server_thread.start()

    # 启动仿真
    run_simulation(args.task, args.num_envs, args.headless)
```

## File: isaaclab_server_50.py
size: 9887
sha: a182ba9a70af3e85687f7d387fc886108304d617
upstream: https://github.com/osrbot/seir/blob/HEAD/isaaclab_server_50.py

```text
import argparse
import json
import threading
import time
from queue import Queue, Empty
from typing import Optional

import torch
import numpy as np
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel, Field
import uvicorn

# ----------------------------------------------------------------
# 数据模型
# ----------------------------------------------------------------

class RobotCommand(BaseModel):
    """控制指令"""
    command_type: str = Field(
        ..., 
        description="指令类型: joint_position | end_effector_delta | gripper | wait | reset | home"
    )
    target: Optional[list[float]] = Field(
        None, 
        description="目标值。joint_position: 6个关节角度(rad); "
                    "end_effector_delta: [dx, dy, dz] 末端位移增量(m); "
                    "gripper: [1.0]-打开 / [0.0]-关闭"
    )
    duration: Optional[float] = Field(
        None, 
        description="执行持续时间(秒)，用于插值平滑运动，默认立即执行"
    )

class RobotState(BaseModel):
    """机械臂状态"""
    joint_positions: list[float]
    joint_velocities: list[float]
    gripper_position: list[float]
    timestamp: float

class CommandResponse(BaseModel):
    status: str
    message: str
    queue_size: int

# ----------------------------------------------------------------
# 全局共享状态
# ----------------------------------------------------------------

command_queue: Queue = Queue(maxsize=100)
latest_state: dict = {
    "joint_positions": [],
    "joint_velocities": [],
    "gripper_position": [],
    "timestamp": 0.0
}
state_lock = threading.Lock()
robot_config: dict = {} # 启动后填充

# SO-ARM101 默认关节位置 (home pose)
SO_ARM101_HOME = [0.0, 0.0, 0.0, 1.57, 0.0, 0.0]

# ----------------------------------------------------------------
# FastAPI 应用
# ----------------------------------------------------------------

app = FastAPI(title="IsaacLab Robot Server", version="1.0")

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

@app.get("/health")
def health():
    return {"status": "ok", "sim_running": True, "timestamp": time.time()}

@app.get("/config")
def get_config():
    """返回机械臂配置，供 OpenClaw Agent 了解能力边界"""
    return robot_config

@app.get("/state", response_model=RobotState)
def get_state():
    with state_lock:
        return RobotState(**latest_state)

@app.post("/command", response_model=CommandResponse)
def send_command(cmd: RobotCommand):
    # --- 校验逻辑 ---
    if cmd.command_type == "joint_position":
        if cmd.target is None or len(cmd.target) != 6:
            raise HTTPException(status_code=400, detail="joint_position 需要 6 个关节角度值")
    
    elif cmd.command_type == "end_effector_delta":
        if cmd.target is None or len(cmd.target) != 3:
            raise HTTPException(status_code=400, detail="end_effector_delta 需要 [dx, dy, dz]")
    
    elif cmd.command_type == "gripper":
        if cmd.target is None or len(cmd.target) != 1:
            raise HTTPException(status_code=400, detail="gripper 需要 [1.0] 打开 或 [0.0] 关闭")
    
    elif cmd.command_type == "wait":
        if cmd.duration is None:
            raise HTTPException(status_code=400, detail="wait 指令需要 duration 参数")
    
    elif cmd.command_type in ["reset", "home"]:
        pass # 无需 target
    
    else:
        raise HTTPException(status_code=400, detail=f"未知 command_type: {cmd.command_type}")

    # --- 入队 ---
    if command_queue.full():
        raise HTTPException(status_code=429, detail="指令队列已满，请稍后再试")
    
    command_queue.put(cmd.model_dump())
    return CommandResponse(
        status="accepted",
        message=f"{cmd.command_type} 指令已入队",
        queue_size=command_queue.qsize()
    )

@app.post("/reset")
def reset_env():
    command_queue.put({"command_type": "reset", "target": None, "duration": None})
    return {"status": "accepted", "message": "重置指令已入队"}

# ----------------------------------------------------------------
# IsaacLab 仿真循环
# ----------------------------------------------------------------

def run_simulation(task_name: str, num_envs: int, headless: bool):
    """
    主仿真循环 - 使用底层 IsaacLab API 创建干净的机械臂场景。
    不使用 ManagerBasedRLEnv (因为它自带有 event/termination manager 导致自动 reset)。
    """
    # --- 初始化 Isaac Sim ---
    from isaaclab.app import AppLauncher
    launcher = AppLauncher(headless=headless)
    simulation_app = launcher.app

    import isaaclab.sim as sim_utils
    from isaaclab.scene import InteractiveScene, InteractiveSceneCfg
    from isaaclab.assets import ArticulationCfg, Articulation
    from isaaclab.sim import SimulationCfg
    from isaaclab.utils import configclass

    # 尝试导入 SO-ARM101 配置
    from isaac_so_arm101.robots.trs_so101.so_arm101 import SO_ARM101_CFG

    @configclass
    class RobotSceneCfg(InteractiveSceneCfg):
        """最简场景: SO-ARM101"""
        env_spacing = 2.5
        robot: ArticulationCfg = SO_ARM101_CFG.replace(
            prim_path="{ENV_REGEX_NS}/Robot"
        )

    # 配置仿真
    sim_cfg = SimulationCfg(dt=1.0 / 120.0)
    sim = sim_utils.SimulationContext(sim_cfg)
    sim.set_camera_view(eye=[2.5, 2.5, 2.5], target=[0.0, 0.0, 0.5])

    # 手动生成地面和灯光
    # 注意: spawn_ground_plane 在 Isaac Sim 5.0 存在兼容问题 (SphereLight/ChangePropertyCommand)
    # 直接用底层 API 创建地面
    import isaacsim.core.utils.prims as prim_utils
    from isaaclab.utils.assets import ISAAC_NUCLEUS_DIR
    ground_usd = f"{ISAAC_NUCLEUS_DIR}/Environments/Grid/default_environment.usd"
    prim_utils.create_prim("/World/GroundPlane", usd_path=ground_usd)

    sim_utils.spawn_light("/World/DomeLight", sim_utils.DomeLightCfg(intensity=2000.0, color=(0.75, 0.75, 0.75)))

    # 创建场景与机器人
    scene = InteractiveScene(RobotSceneCfg(num_envs=num_envs))
    robot = scene["robot"]

    sim.reset()
    
    # 填充机器人配置信息供 API 使用
    global robot_config
    robot_config.update({
        "robot_name": "SO-ARM101",
        "dof": robot.num_joints,
        "home_position": SO_ARM101_HOME,
        "joint_names": robot.joint_names
    })

    # 控制变量初始化
    target_joint_pos = torch.tensor([SO_ARM101_HOME], device=sim.device).repeat(num_envs, 1)
    wait_until = 0.0

    print("[INFO] IsaacLab 仿真循环已启动...")
    
    while simulation_app.is_running():
        # 1. 提取指令
        current_time = time.time()
        if current_time >= wait_until:
            try:
                cmd_data = command_queue.get_nowait()
                ctype = cmd_data["command_type"]
                
                if ctype == "joint_position":
                    target_joint_pos = torch.tensor([cmd_data["target"]], device=sim.device).repeat(num_envs, 1)
                elif ctype == "home":
                    target_joint_pos = torch.tensor([SO_ARM101_HOME], device=sim.device).repeat(num_envs, 1)
                elif ctype == "wait":
                    wait_until = current_time + cmd_data["duration"]
                elif ctype == "reset":
                    sim.reset()
                    scene.reset()
                # 注意：gripper 和 end_effector_delta 的具体 IK/位移逻辑需在此根据需求补全
            except Empty:
                pass

        # 2. 应用控制 (假设为关节位置控制)
        robot.set_joint_position_target(target_joint_pos)
        scene.write_data_to_sim()
        
        # 3. 物理步进
        sim.step()
        scene.update(dt=sim_cfg.dt)

        # 4. 更新全局状态
        with state_lock:
            latest_state.update({
                "joint_positions": robot.data.joint_pos[0].cpu().numpy().tolist(),
                "joint_velocities": robot.data.joint_vel[0].cpu().numpy().tolist(),
                "gripper_position": [0.04], # 示例值
                "timestamp": time.time()
            })

    simulation_app.close()

# ----------------------------------------------------------------
# 入口函数
# ----------------------------------------------------------------

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--task", type=str, default="Isaac-SoArm-101-Lift-v0")
    parser.add_argument("--num_envs", type=int, default=1)
    parser.add_argument("--headless", action="store_true", default=False)
    args = parser.parse_args()

    # 清理可能残留的旧进程占用的端口
    import socket, signal, os
    def _kill_port(port):
        """尝试关闭占用指定端口的旧进程"""
        try:
            s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
            s.settimeout(1)
            result = s.connect_ex(('127.0.0.1', port))
            s.close()
            if result == 0:
                # 端口被占用，尝试用 fuser 杀掉
                os.system(f"fuser -k {port}/tcp >/dev/null 2>&1")
                time.sleep(0.5)
        except Exception:
            pass
    _kill_port(8000)

    # 启动 API 线程
    server_thread = threading.Thread(
        target=lambda: uvicorn.run(app, host="0.0.0.0", port=8000), 
        daemon=True
    )
    server_thread.start()

    # 启动仿真
    run_simulation(args.task, args.num_envs, args.headless)
```

## File: LICENSE
size: 35823
sha: 3877ae0a7ff6f94ac222fd704e112723db776114
upstream: https://github.com/osrbot/seir/blob/HEAD/LICENSE

Content is not inlined in the catalog. Read the upstream file: https://github.com/osrbot/seir/blob/HEAD/LICENSE

## File: README_SIMPLY.md
size: 4916
sha: 0609300e71870ce703c033694c02f5dd3f8711e0
upstream: https://github.com/osrbot/seir/blob/HEAD/README_SIMPLY.md

```text
# 🎮 硬核科普：怎么让 AI 听懂人话去抓娃娃？

想象一下，你现在有两个神器：
一个是 **IsaacLab**，它就像是一个极其逼真的“3D物理游戏机”，里面有一台机械臂。
另一个是 **OpenClaw (大模型)**，它是一个极其聪明的“学霸玩家”，但它被蒙上了眼睛，手里也没有手柄。

我们今天的目标，就是让这个学霸玩家能听懂你的话（比如你说：“帮我把瓶子拿起来”），然后精准地在游戏机里操作机械臂。怎么做？分三步走！

---

## 🕹️ 第一问：怎么把“大模型”和“游戏机”连起来？

学霸玩家（大模型）在云端，游戏机（IsaacLab）在本地电脑上，这俩语言不通啊。

**解法：建一个“传达室”（也就是 HTTP API + 队列）**

如果不建传达室，大模型直接去抢游戏机的手柄，游戏机很容易卡死。所以我们写了一段代码（双线程架构），把它们隔开：
1. **接线员（FastAPI）**：专门站在外边，24小时接听大模型从微信（HTTP网络）发来的指令。
2. **游戏引擎（IsaacLab）**：就在屋子里疯狂打游戏（一秒钟刷新120次物理动作）。
3. **投递箱（Queue 队列机制）**：接线员接到大模型的命令：“让他往前走一步”，就把小纸条塞进投递箱。屋里的游戏机每跑一帧，就去投递箱里看一眼有没有新纸条，有就照做。
*这样一来，接微信的只管接微信，打游戏的只管打游戏，完美解耦，谁也不卡谁！*

---

## 📖 第二问：大模型怎么听懂人话？你需要写一本“游戏攻略”（SKILL）

大模型虽然上知天文下知地理，但它对这台具体的机械臂是“高分低能”的。它不知道啥是“J1关节”，也不知道人类说的“往左转”对应哪个电机。
所以我们要给它写一份**《保姆级通关攻略》（这就是 SKILL 文件）**。

这份攻略里必须要写这三样东西：

1. **翻译词典（把枯燥的代码变成人的动作）**
   不要跟大模型发牢骚说“转动 Joint_1”，你要在攻略里写明：
   > “嘿，老兄，J1 就是人类身体的**左右转肩膀**，J3 就是**弯曲手肘**，J6 就是**夹娃娃的爪子**（0是张开，0.5是捏紧）。”
2. **保命铁律（System Prompt Rules）**
   大模型有个坏毛病就是喜欢“闭眼瞎猜”（幻觉），所以攻略第一页必须用红字写着：
   - 🚫 **动之前先看雷达！** 没获取自己当前位置前，绝对不许发移动指令。
   - 🚫 **步子迈小点！** 每次发力最多只能动 0.5 个角度，发力过猛容易“扯着蛋”（模型崩溃或撞毁）。
   - 🚫 **迷路了就回城！** 发现情况不对，无脑触发 `home` 指令，退回安全姿势。
3. **打样示范（教它怎么拆解动作）**
   > 人类：“把手抬起来” <br>
   > 大模型的脑内小剧场： <br>
   > (1) 先看一眼现在的肩膀角度是 0 度。<br>
   > (2) 抬起来？攻略说抬起来对应 J2 增加。<br>
   > (3) 发送指令！把 J2 变成 0.5度！完美！

---

## 🎛️ 第三问：为了配合 AI 玩游戏，游戏机得提供什么面板？

光有攻略不行，游戏机（仿真环境）自己还得提供“查状态”和“能按键”的接口（API端点）。

1. **“我在哪？”—— 仪表盘接口（感知/Perception）**
   - `/state` 接口：大模型只要一戳这个接口，游戏机就返回：“你现在手臂举在半空，爪子是张开的”。大模型必须靠这个来盲打。
   - `/config` 接口：告诉大模型这台机器人的极限在哪，比如这台机器胳膊只有6个关节，不要给第7个关节发号施令。
2. **“动起来！”—— 手柄按键（行动/Action）**
   - `/command` 接口：这是绝对的核心！相当于游戏手柄的组合键。大模型可以通过它发出：
     - `joint_position`：单独扭动某个关节（像提线木偶）。
     - `gripper`：命令爪子一键死死咬住。
     - `wait`：让机器手等一秒钟（等杯子放稳了再松手）。
3. **“网断没？/玩砸了重来”—— 护航按键（生命周期）**
   - `/health` 接口：大模型时不时戳一下，如果返回报错，说明游戏机已经卡死了，别白费力气了。
   - `/reset` 接口：如果机械臂一头撞在桌子上，大模型可以大喊一声“重开！”，一键让整个场景时光倒流，回到最初。

---
**总结一下：**
我们搭了一个“传达室”（网络接口），给大模型发了一本“打游戏攻略”（SKILL），并在游戏机上安装了“仪表盘和手柄键”。这样，你随便说一句句人话，大模型在云端稍微一思考，就能精准操控千里之外的 3D 机械臂啦！
```
