# LeRobot 双臂移动操作项目方案

> 决策与阶段验收以本文件为准。更新：2026-09-08，设计评审修订。
> 当前 P0：已有规划与环境脚本，尚无 GPU 环境、训练效果或真机验收结果。

## 1. 目标与边界

基于 LeRobot，完成“人工遥操示范 → 数据采集 → 策略训练 → 真机执行”的闭环，逐步扩展至桌面双臂与移动操作。

首个交付是单臂固定场景抓放；整机首个交付是“移动到位 → 停稳 → 抓取 → 收臂 → 移动 → 放置”。边移动边双臂操作、一个 VLA 统一控制整机，列为后续探索目标。

“可自行训练”指使用自己的示范数据训练模型。自主探索、自动成功判定、自动恢复与持续学习尚无实现，不作为当前交付承诺。

## 2. 技术决策

| 项目 | 决策 | 约束 |
|---|---|---|
| 框架 | LeRobot **0.6.1 / Python 3.12** | 锁定依赖，不自动跟随 main；升级必须复验 |
| 单臂基线 | ACT | 模仿学习策略，不作为语言理解证明 |
| VLA | SmolVLA 450M 预训练基座微调 | 记录冻结模块；默认微调不等于全参数解冻 |
| 大模型 | π0-FAST 等仅作后续候选 | LoRA、量化支持、显存及任务收益均需实测 |
| 机械臂 | P1：1 leader + 1 follower；P2 再加各 1 条 | SO-101 为 5 个臂关节 + 夹爪，共 6 个电机 |
| 底盘 | LeKiwi | 双臂安装、重心、供电与桌面可达性先验证 |
| 采集/推理 | 3080 10GB，机器人旁 Ubuntu 主机 | P1/P2 USB 直连；测实际显存和延迟 |
| 训练 | 3090 24GB，同局域网 Ubuntu 主机 | 小 batch 起步，按峰值显存调参 |
| 上机计算 | RPi 5，P3 前采购 | 采图、驱动、执行和超时处理；不宣称硬实时 |
| 调度与导航 | 先状态机；有定位/建图/避障需求再考虑 ROS 2/Nav2 | 导航与学习策略分层验收 |
| 网络推理 | 优先官方 PolicyServer/RobotClient | 验证锁定版本支持范围，仅补组合适配与故障处理 |
| 数据流 | 同局域网优先 rsync，HF Hub 可选 | 数据、模型、处理器、配置与校准成套留存 |
| Orin | 不在关键路径 | 另行验证系统和运行时兼容性 |

v0.6.1 已有 `BiSOFollower`，P2 优先复用；双臂加底盘的组合 robot、遥操与动作定义仍需适配。LeKiwi 已有远程链路，不从零实现整个网络层。Async 与 RTC 是不同机制，先跑同步基线，再分别评估。

## 3. 架构与接口

P1/P2：leader/follower/相机 → USB → 3080（采集与执行）；数据经 rsync 到 3090 训练，checkpoint 与处理器回传 3080。

P3/P4：RPi 负责本机硬件，3080 负责操作策略；状态机负责移动、到位确认、操作与失败退出。优先复用 LeKiwi 与官方异步接口，避免叠加不必要的图像转发链路。`server/`、`client/` 目前仅是占位目录。

实施前固定以下契约并写入版本化配置：

- 状态/动作字段顺序、左右臂前缀、关节单位、夹爪范围、底盘坐标系与速度单位；训练与执行使用同一归一化及处理器。
- 相机名、序列号/稳定设备路径、分辨率、帧率、曝光与安装位置；相机变化视为数据分布变化。
- 图像和本体状态时间、观测编号、动作对应观测编号、动作序号与有效期；跨主机时钟对齐方式及误差。
- 关节限位、每步最大变化量、底盘限速、队列长度、过期丢弃、队列耗尽和重连规则。

网络预算：三路 640×480 RGB 10fps 原始图像约 221Mbps；三路 1080p 同配置约 1.49Gbps（不含协议开销）。明确压缩格式，测编码、传输、解码、推理与执行延迟，记录 P50/P95/P99、丢帧与队列耗尽次数。10Hz 观测、20–30Hz 执行、200–500ms 分块仅为候选参数，不是已满足指标。

### 故障处理

本机执行约束不能依赖模型服务在线。网络超时/动作过期时底盘停止，旧队列失效；手臂根据姿态与负载采用经验证的保持/受控停止，不默认回中位或直接失去支撑。重连需显式重新使能，不继续播放旧动作。

P1 起验证停止手段、限位、限速与人工接管。P3 前定义最大允许停车时间和距离。P4 注入断网、推理进程退出、相机卡死、乱序/过期动作和队列耗尽；记录触发到停止的时间及位移。Python watchdog 不等于完整硬件安全保证。

## 4. 阶段与验收

时间按实际进度滚动估计。每阶段达标后再扩大任务，P3/P4 先做试验再估工时。

### P0：环境与采购确认

- [ ] 两台补齐 OS、驱动、GPU、Python、uv 信息（[机器记录](env/machines.md)）。
- [ ] 3080 用 `env/setup_lerobot.sh --resolve` 生成依赖锁并通过软件冒烟检查，保留报告。
- [ ] 将锁文件和输入指纹同步到 3090，以默认模式安装，核对两台锁的 SHA256。
- [ ] 完成短视频编码/解码、小样本训练和模型加载；解决 CUDA/FFmpeg/TorchCodec 兼容性后再认可该锁。
- [ ] 验证过的锁、指纹与精简环境记录入 git，不提交凭据或原始日志。
- [ ] 确认实际套件的 leader/follower 电机、供电规格，先买一对臂、相机和夹具。

验收：两台同锁、CUDA 运算与 CLI 加载通过，小样本管线可运行。脚本通过不等于真机验收通过。

### P1：单臂抓放闭环

- [ ] 完成电机 ID/波特率设置、组装、校准、稳定设备路径和停止手段验证。
- [ ] 相机覆盖全过程，遥操无异常；备份校准与安装照片。
- [ ] 首轮约 50 条一致示范，例如 5 个位置各 10 条；逐条检查画面、动作和时间对齐。
- [ ] ACT 建立基线，记录数据版本、步数、batch、随机种子、显存、耗时与 checkpoint。
- [ ] 按 [评测协议](docs/evaluation.md) 独立测试 20 次，成功至少 16 次、碰撞为 0；干预计失败并完整记录。
- [ ] 同数据和测试协议比较 SmolVLA，不用训练 loss 代替真机成功率。

验收：上述指标达标，能补采示范并复现实验。调参试验与最终验收分开。

### P2：桌面双臂

- [ ] 新增 **1 leader + 1 follower**，总数 2L+2F；按遮挡需求扩展至前置+两腕相机。
- [ ] 复用官方双臂驱动，验证校准、镜像方向、动作顺序与碰撞区域。
- [ ] 选择需要两手协作的短任务，先验证遥操和数据质量，再训练。
- [ ] 固定初始条件范围，独立测试 20 次，至少成功 16 次、无碰撞。

验收：一个桌面协作任务可复现；不默认单臂 checkpoint 能直接用于双臂。

### P3：底盘、机械与网络

- [ ] 采购前验证安装空间、臂展与桌高，检查伸臂负载时重心、顶板刚度和线束。
- [ ] 按实际电机电压设计供电，测峰值电流、压降、发热与续航；确认 RPi/Hub 的移动供电。
- [ ] 底盘独立遥操，测限速、停车距离与故障停止；仅采用 ROS 桥后才要求 `cmd_vel`/`odom`。
- [ ] 固定位置测试 RPi↔3080，再有限范围有线移动；有线测试不算无线自主移动验收。
- [ ] 实现“移动 → 停稳确认 → 单臂操作”，暂不要求边走边操作。

验收：先根据 P1 抓取容差和制动试验定义到位误差、停稳条件、停车上限，填入评测记录。重复 20 次到位测试，报告误差分布并符合阈值后再连接操作任务。

### P4：分阶段整机任务

- [ ] 组合双臂与底盘，复用上游链路，为缺口补适配与本机故障处理。
- [ ] 状态机：移动到位 → 停稳 → 双臂抓取 → 收臂 → 移动 → 放置；每步有成功条件、超时、失败退出和人工接管。
- [ ] 采集实际整机安装状态下的示范，不默认桌面策略直接迁移。
- [ ] 第 3 节故障注入全部符合预定义停止上限，且不自动恢复动作。
- [ ] 固定任务范围内独立测试 20 次，至少成功 16 次、无碰撞；报告全程及子阶段成功率与干预次数。

验收：分阶段任务可复现，故障停止通过；不描述成开放环境通用自主能力。

### P5：探索与扩展

按失败数据选择：物体/光照变化、语言对照任务、失败检测与恢复、无线链路、Async/RTC、导航扩展。最后探索边移动边操作、统一整机 VLA、大模型、LoRA/量化与仿真迁移，分别立项并测量。

## 5. 预算与风险

历史基础 BOM 粗估 ¥6500–8000，未核实现价；另预留 20%–30% 结构、电源和备件费，规划约 ¥7800–10400。若上限 ¥10000，应先拿报价并缩减非必要项。P1 暂缓 RPi/底盘，详见 [BOM](hw/bom.md)。

主要风险依次为机械可达性/稳定性、示范质量、长任务失败累积、时序与故障处理、依赖兼容性。显存和训练时长作为测量项，不承诺“24GB 全量舒适”“几分钟训好”或“量化必定可用”。

## 6. 参考与下一步

下一步：3080 完成 P0 首次解析和报告，再同步 3090；同时确认 P1 型号。未经测试的项保持未勾选。

- [v0.6.1 依赖](https://github.com/huggingface/lerobot/blob/v0.6.1/pyproject.toml)
- [v0.6.1 双臂源码](https://github.com/huggingface/lerobot/blob/v0.6.1/src/lerobot/robots/bi_so_follower/bi_so_follower.py)
- [v0.6.1 SmolVLA](https://github.com/huggingface/lerobot/blob/v0.6.1/docs/source/smolvla.mdx)
- [v0.6.1 Async](https://github.com/huggingface/lerobot/blob/v0.6.1/docs/source/async.mdx)
- [LeKiwi](https://huggingface.co/docs/lerobot/lekiwi)（接口以安装版本为准）