# 本机机器人控制桥接

独立于 `training_server` 的实时数值接口。默认监听 `127.0.0.1:8766`；不导入 LeRobot、PyTorch 或训练任务，不执行代码、Shell 或服务器文件路径。

## 启动

从仓库根目录执行（Python 3.12）：

```bash
source .venv/bin/activate
python -m pip install -e ./control_bridge
python -m mujoco_control_bridge
# 或 npm run control-bridge
```

未设置 `MUJOCO_CONTROL_TOKEN` 时，服务生成至少 256 bit 随机 token，只在启动终端显示一次。也可通过该环境变量提供自己的 token（16–4096 个可打印 ASCII 字符，不含空白）。`--port 0` 自动分配端口，仅测试需要；不能配置非回环监听地址。

1. 在本机 HTTP 工作台加载受支持的机器人，显式选择 profile 并通过编译校验。
2. 在“控制台 → 开源项目 / 外部控制”填写地址和 token，连接桥接。
3. 播放，然后点击“允许外部控制”。接管会停止 Python/ONNX、锁定 1×并禁止冲突写入。
4. 在另一终端给 SDK 设置相同 token（不要把 token 放进 URL、源码或命令历史）：

```bash
read -rsp '控制 token: ' MUJOCO_CONTROL_TOKEN; echo
export MUJOCO_CONTROL_TOKEN
export MUJOCO_CONTROL_ENDPOINT=http://127.0.0.1:8766
```

## 通用 Python SDK

客户端路径仅使用 Python 标准库；HTTP 不使用环境代理，也不跟随重定向。接口不依赖 LeKiwi 的通道名称或数量。

```python
import os
import time
from mujoco_control_bridge import SimRobotClient

with SimRobotClient(os.environ["MUJOCO_CONTROL_ENDPOINT"]) as robot:
    descriptor = robot.describe()
    values = {
        channel["id"]: min(channel["max"], max(channel["min"], 0.0))
        for channel in descriptor["actionChannels"]
    }
    start = time.monotonic()
    for i in range(90):
        measured = robot.get_observation()  # 实际状态，不是目标回显
        accepted = robot.send_action(values)  # 物理步后确认，包含已接受的限幅目标
        time.sleep(max(0, start + (i + 1) / 30 - time.monotonic()))
```

通用 SDK 要求提交完整通道集合；部分动作的保持/默认语义由具体插件处理。`robot.reset()` 返回新 `modelEpoch` 的暂停观测，并清除租约；必须在浏览器重新播放、授权，再连接。`is_connected` 不是永久健康承诺：距成功动作超过 500 ms 会在本地失效。

## 边界与故障处理

- HTTP Bearer token；WS 首帧认证。校验本机 Host/Origin，拒绝查询字符串 token、远程页面和未经认证的预检/连接。
- 一个浏览器后端、一个 Python 写入者；读取状态不取得写权限。不能自动抢占已有控制者。
- 64 KiB 帧/请求、每租约至多 100 动作/秒、8 个在途 RPC、一个最新待应用动作；旧目标被替换时返回 `SUPERSEDED`，不会堆积无限队列。
- 浏览器注册/认证有绝对超时；1 秒 RPC 确认期限、500 ms 动作/观测新鲜度边界。同序号心跳不刷新观测年龄。
- 暂停、断连、进程崩溃、重载、页面隐藏、冻结超时均撤销授权。轮目标归零、臂/夹爪保持实测姿态，并暂停外控仿真；**不是把所有位置伺服置零**。
- 回到页面或重新连接不会恢复旧命令。先检查错误、恢复关节限位，再播放/授权。
- 无 HTTPS/WSS、跨机器访问、锁步、图像流、LeRobot 数据集或训练 API。不要使用端口转发或反向代理扩大此 V1 的信任边界。
- 浏览器控制 token 仅在页面内存；不写入 `localStorage`/`sessionStorage`、工程导出或应用日志。拥有 token 的本机进程仍被视为可信控制者。

测试：`python -m unittest discover -s control_bridge/tests -v`。完整消息结构、错误码和扩展点见 [机器人接口](../docs/robot-interface.md)；LeRobot 用法见 [LeKiwi 示例](../examples/lekiwi/README.md)。