P0: project plan, hardware BOM, dual-GPU topology (3080 home + 3090 training), one-click env setup, CLI reference

.gitattributes

@@ -0,0 +1,8 @@
+# 换行统一：仓库内一律 LF，Linux 上脚本直接可跑
+* text=auto
+*.sh text eol=lf
+*.py text eol=lf
+*.md text
+*.toml text
+*.yaml text
+*.yml text

.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+
+# LeRobot 仓库 clone（各 GPU 机自己 clone，不入库）
+lerobot/
+
+# 数据集 / 模型 / 视频媒体（走 HF Hub / rsync，不走 git）
+data/
+datasets/
+media/
+videos/
+outputs/
+models/
+*.ckpt
+*.safetensors
+*.mp4
+*.parquet
+
+# 日志 / 临时 / 缓存
+*.log
+tmp/
+.cache/
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

PLAN.md

@@ -0,0 +1,222 @@
+# 方案：LeRobot 双臂移动 VLA 机器人（可自行训练）
+
+> 本文件是项目的「单一事实来源」(single source of truth)。所有决策、预算、阶段、命令、待办都以此为准，随进展更新。
+> 最后更新：_P0 定稿（双 GPU 机版：3080 主家 + 3090 训练）_
+
+---
+
+## 0. 目标（一句话）
+
+复刻 LeRobot 工作流，造一台**会走（LeKiwi 底盘）+ 双手协作（2×SO-101）+ 语言/视觉驱动（VLA）+ 能自己采集数据并训练**的移动操作机器人。
+
+**核心思路**：不重写 LeRobot，而是**站在 LeRobot 框架上组装这台特定机器人**；架构上采用「**瘦边 + 厚芯**」——机器人只带一块便宜的驱动板(RPi 5)做实时控制，**推理放 3080 主家（挨着机器人）、训练放 3090（24GB）**，走局域网。
+
+**协作模型**（详见 [env/machines.md](env/machines.md)）：
+- **3080 机（10GB · 本地 Ubuntu · 机器人旁）= 主家**：开发 + 臂(USB) + 遥操/采数 + **推理部署** + P4 policy server。
+- **3090 机（24GB · 远程 SSH · 同局域网）= 训练专用**：只跑训练；数据集/模型经 HF Hub（或 rsync）流转。
+- **本 Windows 机 = 写字台**：我(agent)写代码/配置/文档 → **你 push 到 git 库** → 两台 GPU 机 clone/pull。
+- 我无外网 → **我产出，你在两台机器上跑并粘回输出，我迭代**。
+
+---
+
+## 1. 决策总表（已拍板）
+
+| 项 | 决策 | 备注 |
+|---|---|---|
+| 框架 | **LeRobot**（HF 官方，Py3.12, Transformers v5；最新 0.6.0） | 官方旗舰生态；装时取最新 stable |
+| 机械臂 | **4× SO-101**（2 leader + 2 follower） | 双臂遥操 = 2 主 + 2 从；6DOF + 夹爪；自印有 3D 打印机 |
+| 底盘 | **LeKiwi**（三轮全向，Feetech STS3215，Seeed 12V 版） | SO-101 专用移动底盘，LeRobot 原生 `.[lekiwi]` |
+| 上机驱动板 | **RPi 5 (8GB)** + 有源 USB Hub | 只管实时控制/采图/执行/fail-safe，不做 ML |
+| 主家(开发+推理) | **3080 机（本地 Ubuntu · 10GB · 机器人旁）** | 臂 USB 直插；遥操/采数/推理部署；P4 policy server 在它上面 |
+| 训练专用 | **3090 机（远程 SSH · 24GB）** | 只跑 lerobot-train；与 3080 同局域网（rsync 直传 / π0 代推） |
+| 富余算力 | **AWU408 双 DRIVE Orin**（空闲，非关键路径） | 3090 忙训练时可顶推理 / 或做固定台 |
+| 相机 | **3× USB 相机**（1 前置全局 + 2 腕部） | USB 最通用，适配 RPi5/3080 |
+| VLA 主力 | **SmolVLA (4.5亿)** | 单卡可全量训、10GB 卡可推理、异步分块天生适合分布式 |
+| VLA 验证/起步 | **ACT**（小、快） | P1 先证明"能学会" |
+| VLA 上限 | **π0-FAST**（自回归，~3B，LoRA 微调） | 算力宽裕后的 SOTA |
+| 架构演进 | P1/P2 **单机**(3080 直连臂) → P4 **拆分**(RPi5↔局域网↔3080) | 先最快出结果，再长成分布式 |
+| 预算 | **~¥6500-8000**（自印可更低） | 落在 ¥5000–10000 内（详见 [hw/bom.md](hw/bom.md)） |
+
+---
+
+## 2. 硬件 BOM（采购清单）
+
+> 完整链接/店铺/状态见 **[hw/bom.md](hw/bom.md)**。这里给概览。
+
+| # | 部件 | 数量 | 参考价 (¥) | 小计 | 说明 |
+|---|---|---|---|---|---|
+| 1 | SO-ARM101（含 3D 打印件+舵机+驱动板+电源） | 4 | ~879 | **~3500** | 2L+2F；淘宝现货树脂版最省；自印可降 |
+| 2 | LeKiwi 底盘（12V，Seeed 含打印件+电池） | 1 | ~1800 | **~1800** | 或 base-only 12V ~¥1501 自印结构件 |
+| 3 | RPi 5 (8GB) + 27W 电源 + 有源 USB Hub + 存储 | 1 套 | ~800 | **~800** | 上机驱动板 |
+| 4 | USB 相机（1 前置 + 2 腕部） | 3 | ~130 | **~400** | 1080P 免驱；或 ¥138 双相机套件 |
+| 5 | 线束/夹具/耗材/电源/网线 等杂项 | — | — | **~600** | |
+| | **合计** | | | **~¥7100-8000** | P1 起步(2臂)~¥3300 |
+
+**已拥有（0 成本）**：3080 机（10GB·主家）、3090 机（24GB·训练）、AWU408 双 Orin、3D 打印机、本 Windows 开发机。
+
+**关键提醒**：
+- SO-101 **打印件**：官方 STL 可 FDM(PLA) 或光固化；Leader 臂用**轻负载齿轮**才捏得动；**电机 ID 按顺序烧录**。
+- 4 条臂 = **2 leader（遥操主手）+ 2 follower（执行从手）**。P1 先买/用 2 条(1L+1F)，P2 再补 2 条。
+- LeKiwi 顶板 **M3 螺孔**直接固定 SO-101 底座；12V 底盘自带 12V→5V 降压给 5V 臂。
+
+---
+
+## 3. 系统架构
+
+### 3.1 目标态（P4 整机自主）——瘦边 + 厚芯
+
+```
+  算力层（拆两台，同一局域网）
+ ┌─────────────────────────────────────────────┐
+  │  3080(10GB)＝推理芯 · 挨着机器人：            │
+  │   · 遥操（P1/P2：接 leader 臂）/ 采数          │
+  │   · policy server（obs→action chunk）        │
+  │   · 数据集管理 / HF Hub 上传下载              │
+  │  3090(24GB)＝训练芯：                         │
+  │   · SmolVLA 全量 / π0-FAST LoRA               │
+  │   （数据集·模型经 HF Hub / rsync 两机流转）     │
+  └────────────────────────┬────────────────────┘
+                           │  局域网 (1Gbps 有线最稳)
+        上行: 3相机 + 本体状态(低频~10Hz)
+        下行: 动作chunk(每 200~500ms 一批 K 步)
+                           │
+  ┌────────────────────────┴────────────────────┐
+  │  移动机器人 ＝ LeKiwi 底盘 + 2×SO-101(follower) │
+  │  RPi 5 驱动板:                                │
+  │   · USB: 左/右臂舵机 + 3 底盘轮 (实时 20~30Hz)  │
+  │   · USB: 3 相机 (采集 → 推给算力层)            │
+  │   · 执行: 收 chunk → 实时插值下发              │
+  │   · 安全: 断链 watchdog → 底盘停 / 臂缓回中位   │
+  └─────────────────────────────────────────────┘
+```
+
+**为什么这样**：VLA 每 200~500ms 只算"一小批"未来动作(异步分块)，网络只传"几张图 + 一小批动作"，带宽占用极小；实时伺服与安全 100% 留在机器人本地(RPi 5)，断网即停。训练/推理拆两台：训练吃显存只有 3090 干得动，推理不吃显存 3080 足够，还挨着机器人。
+
+### 3.2 起步态（P1/P2）——单机，最快闭环
+
+P1/P2 底盘还没上、臂在固定夹/桌上时，**3080 主家直接用 USB 接臂**（1L+1F / 4 条），单机跑 遥操→采集→推理；**训练丢给同局域网的 3090**（数据集经 HF Hub / rsync 过去，模型拉回来），最快打通闭环。等 P3/P4 上 LeKiwi 移动，才切到 3.1 的分布式。
+
+---
+
+## 4. VLA 模型路线（训练：3090 24GB · 推理：3080 10GB）
+
+| 阶段 | 模型 | 训练（3090 · 24GB） | 推理显存（3080 · 10GB） | 作用 |
+|---|---|---|---|---|
+| P1 起步 | **ACT** | 全量，几分钟~数十分钟 | **<1GB ✅** | 最快证明"采集→训练→会动"闭环 |
+| P1→P4 主力 | **SmolVLA** | 全量微调（24GB 舒适） | **fp16 ~2GB ✅** | 语言+视觉驱动，异步推理，部署主力 |
+| 上限/进阶 | **π0-FAST** | LoRA 微调（24GB 为此而生） | **~7GB ⚠️ 紧张** | SOTA 泛化，算力富余后上 |
+
+- 数据统一走 **HF Hub**（`lerobot-record` 直接 push）；两台 GPU 机同局域网，大数据集/模型也可 rsync 直传。
+- SmolVLA 的 **Real-Time Chunking / 异步推理** 正是为"算力层算、机器人执行"这种拆分设计的，天然契合 3.1。
+- π0-FAST 推理在 10GB 上紧张的 3 条后路：**4-bit 量化** / batch=1+bf16 硬试 / **3090 同局域网代推**。
+
+---
+
+## 5. 分阶段实施计划
+
+> 假设业余时间（每周若干小时）。**采购前置**：3D 打印件/套件到货周期可能 1~6 周，P0 期间就下单。
+> 每阶段有明确「验收标准」，达到再进下一阶段。
+
+### P0 · 环境 & 工具链（~1~2 周，含下单等货）
+**目标**：软件环境全通 + git 库建好 + 硬件下单。
+- [ ] **建 git 库**：把本仓库推到你的私库（Gitee/GitHub），3080/3090 clone——此后代码同步全走它
+- [ ] **两台 GPU 机装环境**（同一脚本 [env/setup_lerobot.sh](env/setup_lerobot.sh)：自动探测→国内镜像自适应→Py3.12 venv→clone LeRobot→装 `feetech,lekiwi,dataset,smolvla,pi0`→验证 GPU/CLI）：**先 3080 主家**（P1 在它上面跑），**再 3090**（训练用）；各把 [1]~[7] 输出粘回
+- [ ] **HF 登录**：两台机器都 `huggingface-cli login`（HF_ENDPOINT=hf-mirror）
+- [ ] **固定官方 CLI 命令**（find-port / find-cameras / calibrate / teleoperate / record / train / eval|rollout 的确切 flag，以装好后的 `--help` 实测为准）
+- [ ] **下单硬件**（[hw/bom.md](hw/bom.md)，**先 2 条 SO-ARM101 起步**）
+- [ ] （可选）验证 AWU408 能否跑 Ubuntu+CUDA+PyTorch（只影响"富余算力"，不阻塞主线）
+**验收**：两台 GPU 机 `torch.cuda.is_available()==True`；LeRobot CLI 全 OK；git 库建好且两机已 clone；硬件已下单。
+
+### P1 · 单臂 SO-101 闭环（~2~4 周）⭐核心
+**目标**：1 leader + 1 follower，把 **采集→训练→部署** 整条闭环跑通。
+- [ ] 组装+校准 1 follower + 1 leader（`lerobot-calibrate`），USB 直连 3080 主家
+- [ ] 接 1 相机；遥操作（`lerobot-teleoperate`）验证跟手
+- [ ] 采集第一个数据集（简单任务：抓方块 / 放杯子 / 按按钮），`lerobot-record` → push HF Hub
+- [ ] 3090 上先训 **ACT** 快速验证能学 → 再训 **SmolVLA**
+- [ ] 推理部署（3080 单机直连 follower），手臂独立完成任务
+**验收**：**follower 独立完成一个抓取/放置任务**（无人工逐帧干预）；能稳定记录新 episode 并增量再训。
+
+### P2 · 双臂 BiSO-101（~2~4 周）
+**目标**：双手协作。
+- [ ] 加装 2 条 leader + 1 条 follower（凑 2L+2F），接 3 相机（1 前 + 2 腕）
+- [ ] 上 **bimanual 驱动**（`left_*`/`right_*` 前缀；参考 Maker-Mods / Xbotics 的 BiSO-101，移植进 LeRobot）
+- [ ] 采集双臂数据（双手递物 / 协同开盒 / 双手抓取）
+- [ ] 3090 训双臂 SmolVLA，3080 测双手协作任务
+**验收**：双臂协同完成一个需要两手配合的任务。
+
+### P3 · 底盘 LeKiwi（~2~3 周）
+**目标**：会走 + 底盘与臂联动。
+- [ ] 组装 LeKiwi + 校准（3 轮 STS3215）
+- [ ] 上 **LeKiwi 底盘驱动**（LeRobot 原生 `.[lekiwi]` / 或 lerobot-ros 桥），`cmd_vel`/`odom` 跑通
+- [ ] 底盘 + **单臂** 联动：边走边摆臂（先不拆网，3080 直连）
+- [ ] （可选）雷达 + SLAM / nav2
+**验收**：机器人能"边走边完成一个臂任务"。
+
+### P4 · 整机整合（分布式落地）（~3~6 周）
+**目标**：把 3.1 的「瘦边+厚芯」跑通，整机自主。
+- [ ] 双臂固定到 LeKiwi 顶板，统一 **state/action 空间**（左/右臂关节 + 夹爪 + 底盘速度）
+- [ ] 写 **policy server**（**3080 主家**上，FastAPI/GRPC：obs→action chunk；训练仍归 3090）+ **thin client**（RPi 5：推图+收 chunk+实时执行+**fail-safe watchdog**）
+- [ ] RPi 5 上机（USB 接 2 臂+3 轮+3 相机），以太网接 3080
+- [ ] 采集"整机"遥操数据（人在 leader 处，臂+底盘在 RPi5 处，走网），训一个**同时控制双臂+底盘**的 VLA
+- [ ] 端到端任务：**走到桌边 → 双手抓取 → 移动到目标点放下**
+**验收**：**无人干预**下，移动机器人完成"走+双手抓取+移动放置"的端到端任务；断网能安全停机。
+
+### P5 · 打磨 / 规模化（持续）
+- [ ] 多任务、多数据集、课程式学习
+- [ ] 异步推理提速、动作 chunk 调参、fail-safe 加固
+- [ ] （可选）sim2real（IsaacLab-Arena / EnvHub）、力控/触觉扩展、π0-FAST 上限冲刺
+
+---
+
+## 6. 目录结构约定
+
+```
+（本 Windows 写字台 & 两台 GPU 机共用同一仓库，GPU 机上放 ~/robot/）
+robot/
+├─ PLAN.md                    # 本方案（单一事实来源）
+├─ README.md                  # 仓库导览
+├─ hw/
+│  └─ bom.md                 # 采购清单/链接/到货状态
+├─ env/
+│  ├─ machines.md            # 机器拓扑 + 协作模型
+│  └─ setup_lerobot.sh       # GPU 机一键装环境（3080/3090 都跑）
+├─ lerobot/                  # LeRobot 仓库 clone（各 GPU 机自己 clone，不入库）
+├─ robots/
+│  └─ bi_so101_lekiwi/       # 本机器人的 LeRobot robot 定义（双臂+底盘驱动，P2/P3）
+├─ configs/
+│  ├─ teleop/  record/  train/  eval/   # 各场景的 .toml/.yaml 配置
+├─ server/                   # policy server（3080 主家上，P4）
+├─ client/                   # thin client + 执行 + fail-safe（RPi 5 上，P4）
+└─ docs/                     # 组装/校准/CLI参考/踩坑笔记
+```
+
+> 说明：**3080 主家与 3090 训练机都 clone 本仓库 + LeRobot**（目录统一 `~/robot/`）；本 Windows `D:\robot\lerobot` 是源头，你 push 到 git 库后两机 pull。**数据集/模型不入 git**（走 HF Hub / rsync）。
+
+---
+
+## 7. 风险 & 待验证项
+
+| # | 风险/未知 | 影响 | 对策 |
+|---|---|---|---|
+| 1 | **两台 GPU 机都不在我沙箱里（无外网）** | 我无法直接跑命令 | **协作**：我写 → 你 push git → 3080/3090 跑 → 粘回输出（见 machines.md） |
+| 2 | **CLI flag 随版本变**（0.5→0.6 有差异） | 照旧文档会报错 | 装好后以 `--help` 实测为准（记到 docs/cli_reference.md） |
+| 3 | **双臂驱动非官方内置**（靠社区 BiSO-101 移植） | P2 要多写/改驱动 | 参考 Maker-Mods/Xbotics，必要时自写 `bi_so101_follower` |
+| 4 | **LeKiwi 驱动**：LeRobot 原生 `.[lekiwi]` vs lerobot-ros 桥 | P3 集成方式 | 优先 LeRobot 原生 lekiwi；不行再上 ROS2 桥 |
+| 5 | **局域网可靠性**（WiFi 抖动 → 臂卡顿） | P4 体验/安全 | 优先**有线 1G**；client 带 watchdog 断链即停 |
+| 6 | **AWU408 能否跑 Ubuntu+PyTorch**（常出厂 QNX/DRIVE OS） | 只影响"富余算力" | 非阻塞；跑不了就不管它 |
+| 7 | **硬件到货周期**（3D 打印件 1~6 周） | 拖慢 P1 起步 | P0 立即下单，等货期间把软件全搭好 |
+| 8 | **RPi 5 USB 口不够**（2臂+3轮+3相机≈6-8 设备） | 上机接线 | 用**有源 USB 3.0 Hub**；相机降到 2 个 USB3 口 |
+| 9 | **GPU 机网络可达性**（能否直连 pip/HF/github） | 装环境速度/成败 | `setup_lerobot.sh` 自动探测并切国内镜像 |
+| 10 | **π0-FAST 推理 ~7GB，3080 10GB 紧张** | P5 上限模型部署 | 4-bit 量化 / batch=1+bf16 / 3090 同局域网代推 |
+
+---
+
+## 8. 下一步（P0 第一步 · 现在就能做）
+
+1. **建 git 库**：把 `D:\robot\lerobot` 推到你的私库（Gitee 国内快 / GitHub 均可），两台 GPU 机 clone。
+2. **两台 GPU 机装环境**：clone 后在 **3080 主家** 与 **3090** 各跑一遍 `env/setup_lerobot.sh`，各把 **[1]~[7] 完整输出粘回**。
+3. **下单**：[hw/bom.md](hw/bom.md) 先买 **2 条 SO-ARM101（1L+1F）** 起步。
+4. **HF 登录**：两台机器都 `huggingface-cli login`（脚本已配 hf-mirror）。
+
+> **协作**：我(本机)写 → 你 push git → 3080/3090 跑 → 粘回输出 → 我迭代。
+> 装环境输出回来后，我就铺 **P1 的具体命令/配置**（第一条臂的 find-port / 校准 / 遥操 / 采集）。

README.md

@@ -0,0 +1,31 @@
+# LeRobot 双臂移动 VLA 机器人（可自行训练）
+
+会走（LeKiwi 底盘）+ 双手协作（2×SO-101）+ VLA（SmolVLA / π0-FAST）+ 可自行采集数据并训练。
+基于 HuggingFace **LeRobot** 框架组装；架构「**瘦边 + 厚芯**」：RPi 5 只做实时控制，**推理在 3080 主家、训练在 3090**，走局域网。
+
+## 导览
+
+| 文件 | 内容 |
+|---|---|
+| [PLAN.md](PLAN.md) | ⭐ 单一事实来源：决策 / 预算 / 架构 / P0–P5 阶段 / 风险 |
+| [hw/bom.md](hw/bom.md) | 采购清单（链接 / 价格 / 到货状态） |
+| [env/machines.md](env/machines.md) | 机器拓扑 + 人机协作模型 |
+| [env/setup_lerobot.sh](env/setup_lerobot.sh) | GPU 机一键装环境（3080 / 3090 都跑） |
+| [docs/cli_reference.md](docs/cli_reference.md) | SO-101 全流程 CLI 命令 |
+| `robots/` `configs/` | 机器人定义与各场景配置（P2/P3 填充） |
+| `server/` `client/` | P4：policy server（3080）+ thin client（RPi5） |
+
+## 机器分工
+
+- **3080（10GB · 本地 Ubuntu · 机器人旁）**＝主家：开发 + 臂 USB + 遥操/采数 + 推理部署
+- **3090（24GB · 远程 SSH · 同局域网）**＝训练专用：只跑 `lerobot-train`
+- **RPi 5（P3/P4）**＝上机驱动板：实时控制 + fail-safe
+- **数据流**：采数@3080 → HF Hub（hf-mirror）→ 训练@3090 → 模型 → 推理@3080
+- **代码流**：Windows 写字台 → git 库 → 两台 GPU 机 pull
+
+## 快速开始（GPU 机上）
+
+```bash
+git clone <本仓库地址> ~/robot/proj
+bash ~/robot/proj/env/setup_lerobot.sh   # 自动装环境（国内镜像自适应）
+```

docs/cli_reference.md

@@ -0,0 +1,74 @@
+# LeRobot CLI 命令参考（SO-101 · 默认在 3080 主家跑；训练命令在 3090）
+
+> ⚠️ LeRobot 从 v0.3/0.4 的 `python -m lerobot.xxx` 改成了独立 **`lerobot-*` 控制台命令**（v0.5/0.6）。
+> 下列命令基于调研，**确切 flag 以装好后 `<命令> --help` 实测为准**——跑完 setup 后先 `lerobot-record --help` 等核对一遍，把差异记回来。
+> 前置：`source ~/robot/.venv/bin/activate && cd ~/robot/lerobot && export HF_ENDPOINT=https://hf-mirror.com`
+
+## 0. 常用准备
+```bash
+pip install pynput            # 采数时用键盘 空格/回车 开始/停止 episode
+huggingface-cli login         # HF token（推/拉 数据集、模型）
+```
+
+## 1. 探测硬件
+```bash
+lerobot-find-port             # 列出 USB 串口，认出手臂(和底盘轮)的 /dev/tty*
+lerobot-find-cameras          # 列出 USB 相机及其 index
+```
+> 记住每个设备对应的端口/索引，下面命令要用。多设备时**电机 ID 按顺序烧录**，别串。
+
+## 2. 校准（每条臂都要）
+```bash
+# follower（执行从手）
+lerobot-calibrate --robot.type=so101_follower --robot.port=<PORT_F> --robot.id=my_follower
+# leader（遥操主手）
+lerobot-calibrate --robot.type=so101_leader  --robot.port=<PORT_L> --robot.id=my_leader
+```
+> 校准会引导你把每个关节到极限位置、记 min/max/mid。产物存到 `--calibration_dir`（默认 `calibrations/`），**别丢**。
+
+## 3. 遥操作（验证跟手）
+```bash
+lerobot-teleoperate \
+  --robot.type=so101_follower   --robot.port=<PORT_F> --robot.id=my_follower \
+  --teleop.type=so101_leader    --teleop.port=<PORT_L> --teleop.id=my_leader
+```
+> 拿 leader 摆位 → follower 应同步跟上。**跟手不顺先查 ID/齿轮/校准**，别急着采数。
+
+## 4. 采数（P1 核心）
+```bash
+lerobot-record \
+  --robot.type=so101_follower   --robot.port=<PORT_F> --robot.id=my_follower \
+  --teleop.type=so101_leader    --teleop.port=<PORT_L> --teleop.id=my_leader \
+  --dataset.repo_id=$HF_USER/so101_<task> \
+  --dataset.num_episodes=30 \
+  --dataset.single_task="put the red brick in a bowl" \
+  --robot.cameras="{front:{type:opencv,index_or_path:0,width:640,height:480,fps:30}}"
+```
+- 键盘：**空格=开始 episode，回车=保存**。
+- 多相机（P2 双臂）：`--robot.cameras="{front:{...},left_wrist:{...},right_wrist:{...}}"`（index 以 `find-cameras` 为准）。
+- 采完自动 push 到 HF Hub（`$HF_USER/...`），3090 上即可训练。
+
+## 5. 训练（在 3090 训练机上跑，数据集从 Hub 拉）
+```bash
+# ACT（P1 快速验证）
+lerobot-train --policy.type=act    --dataset.repo_id=$HF_USER/so101_<task>
+# SmolVLA（主力，24GB 单卡全量微调）
+lerobot-train --policy.type=smolvla --dataset.repo_id=$HF_USER/so101_<task>
+```
+> 3090 24GB：SmolVLA 全量、π0-FAST 用 LoRA。GPU 不足时降 batch / 用 `--policy.batch_size`。
+
+## 6. 评测 / 部署到真机（在 3080 主家跑，臂插它）
+```bash
+# 两种名字都见过（随版本），用 --help 确认当前是哪个
+lerobot-eval    --policy.path=<trained_model_dir> --robot.type=so101_follower --robot.port=<PORT_F> --robot.id=my_follower
+# 或
+lerobot-rollout --policy.path=<trained_model_dir> --robot.type=so101_follower --robot.port=<PORT_F> --robot.id=my_follower
+```
+> 3090 单机直连 follower，让**没被遥操的 follower** 独立完成任务 = P1 验收。
+
+---
+
+## P4 分布式（薄边厚芯）命令形态
+- **3080 主家（推理芯）**：policy server —— 不是官方 `lerobot-*`，而是我们自写（`server/`），内部调 LeRobot 的 policy 推理，输入 obs 输出 action chunk；**训练仍归 3090**。
+- **RPi5（机器人）**：thin client（`client/`）—— 采 3 相机 + 本体状态 → 推 3080 → 收 chunk → 实时插值下发舵机/底盘 + 断链 fail-safe。
+- 复用：3080 上仍用 `lerobot-record`（遥操采集）；训练丢给 3090 的 `lerobot-train`。

env/machines.md

@@ -0,0 +1,129 @@
+# 机器拓扑 & 环境 & 协作模型
+
+> 本文件记录各机器角色、连接方式、软件环境，以及**我和你的协作方式**。**每次改动后更新。**
+> `[待补]` = 需要你在对应机器上跑命令后回填。
+
+## ⭐ 协作模型（先读这个）
+
+| 角色 | 机器 | 谁操作 |
+|---|---|---|
+| **主家（开发+臂+推理）** | **② 3080 机（10GB · 本地 Ubuntu · 机器人旁）** | **你**（本地终端） |
+| **训练专用** | **③ 3090 机（24GB · 远程 SSH）** | **你**（SSH） |
+| 写字台（写代码/规划/文档） | ① 本 Windows 机 `D:\robot\lerobot` | **我（agent）** |
+| 富余算力（非关键路径） | ⑤ AWU408 双 Orin | 暂不用 |
+| 上机驱动板（P3/P4 起） | ④ RPi 5 | P3/P4 前你配 |
+
+**关键约束**：我的沙箱**无外网**，够不到你任何一台 GPU 机。工作流：
+
+```
+我(①写字台)写代码/配置 ──你 push──▶ git 库 ──clone/pull──▶ ② 3080 & ③ 3090
+你在 ②/③ 执行（本地终端 / SSH）──粘回完整输出──▶ 我诊断/迭代
+```
+
+**约定**：
+1. 我给**自包含、复制即跑**的脚本/命令块（尽量一次给全）。
+2. **代码/配置**走 git 库（你 push，两机 pull）；**数据集/模型**走 HF Hub（hf-mirror）或局域网 rsync（两机互通，大文件直传更快）。
+3. 两台 GPU 机目录统一 `~/robot/`：本仓库 + lerobot clone + `.venv`。
+
+---
+
+## 拓扑总览
+
+```
+┌──────────────────────┐  push   ┌───────┐ clone/pull ┌─────────────────────────┐
+│ ① Windows 写字台       │ ──────▶ │ git 库 │ ──────────▶ │ ② 3080 主家 (10GB)        │
+│   D:\robot\lerobot    │         └───────┘   ⟨同一库⟩  │   本地 Ubuntu · 机器人旁   │
+│   我写代码/文档/规划     │                    ┌────────┴─────────────────────────┐
+└──────────────────────┘                    │ ③ 3090 训练 (24GB) · 远程 SSH      │
+                                            └───────────────────────────────────┘
+     ② ↔ ③ 同一局域网：rsync 直传数据集/模型；π0 推理紧张时 3090 可代推
+
+② 3080 主家（推理芯，挨着机器人 = 低延迟）:
+   开发 · 臂 USB 直连 · 遥操 · 采数 · 推理部署 · P4 policy server
+③ 3090 训练（训练芯）:
+   只跑 lerobot-train：ACT / SmolVLA 全量 / π0-FAST LoRA
+数据流: 采数@② → HF Hub(或 rsync) → 训练@③ → 模型 → 推理@②
+```
+
+**为什么这样拆**：训练吃显存（参数+梯度+优化器+激活 ≈ 推理的 4~8 倍），推理不吃。
+- 3090 24GB：SmolVLA 全量微调 / π0-FAST LoRA —— 只有它干得动。
+- 3080 10GB：ACT(<1GB) / SmolVLA fp16(~2GB) 推理绰绰有余；遥操/采数几乎不占 GPU。
+
+---
+
+## ② 3080 机（主家 · 10GB · 本地 Ubuntu · 机器人旁）
+
+| 项 | 值 |
+|---|---|
+| 位置 | **机器人/工作台旁**（SO-101 臂 USB 直插它） |
+| 主机名 / IP | `[待补]` |
+| Ubuntu 版本 | `[待补]`（建议 22.04） |
+| GPU | **3080（10GB）** —— 开发 + 推理 |
+| 驱动 / CUDA | `[待补]`（setup 脚本会打印） |
+| Python | **3.12**（venv，脚本自建） |
+| LeRobot | `[待补]`（预期 0.6.x） |
+| HF 账号 | `huggingface-cli login`（HF_ENDPOINT=hf-mirror） |
+| 目录 | `~/robot/`（本仓库 + lerobot + .venv） |
+
+**跑什么**：日常开发、`lerobot-teleoperate` / `lerobot-record`（臂插这）、`lerobot-eval|rollout`（推理部署）、P4 的 policy server。
+**显存预算**：ACT <1GB ✅ / SmolVLA fp16 ~2GB ✅ / π0-FAST ~7GB ⚠️（fallback 见文末）。
+
+## ③ 3090 机（训练专用 · 24GB · 远程 SSH）
+
+| 项 | 值 |
+|---|---|
+| 访问 | **SSH**（远程，与 ② 同局域网互通） |
+| 主机名 / IP | `[待补]` |
+| Ubuntu 版本 | `[待补]` |
+| GPU | **3090（24GB）** —— 只管训练 |
+| Python / LeRobot | 与 ② 同一 setup 脚本 |
+| 目录 | `~/robot/`（同一 git 库） |
+
+**跑什么**：只跑 `lerobot-train`（拉数据集 → 训 → 推模型回 Hub）。
+**兜底角色**：π0-FAST 推理在 ② 放不下时**代推**（同局域网+异步分块，多一跳延迟可接受）；② 忙时也可顶 ACT / SmolVLA-LoRA 训练。
+
+### 两机传大文件（同局域网，比 HF Hub 快）
+```bash
+# ② → ③ 推数据集
+rsync -avzP ~/robot/data/  <user>@<3090-ip>:~/robot/data/
+# ③ → ② 拉训练好的模型
+rsync -avzP <user>@<3090-ip>:~/robot/outputs/train/<exp>/  ~/robot/models/<exp>/
+```
+
+## ① 本 Windows 机（`D:\robot\lerobot` · 我的写字台）
+
+| 项 | 值 |
+|---|---|
+| 角色 | 写代码 / 规划 / 文档；**不跑 LeRobot** |
+| Python | 3.14（LR 要 3.12；本机只编辑） |
+| git | 2.51.0 ✅ |
+| 外网 | ❌ 沙箱无外网 |
+| 同步 | **你从本机 push 到 git 库** → ② ③ pull |
+
+## ④ RPi 5（上机驱动板 · P3/P4 起）
+
+| 项 | 值 |
+|---|---|
+| OS | Raspberry Pi OS 64-bit |
+| 连接 | USB（有源 Hub）：2 臂 + 3 轮 + 3 相机；**以太网 → ② 3080**（policy server 在它上面） |
+| 软件 | LeRobot `.[feetech,lekiwi,dataset]` + thin client（推图/收 chunk/执行/fail-safe） |
+| 静态 IP | `[待补]` |
+
+## ⑤ AWU408（富余算力，非关键路径）
+- 双 DRIVE Orin（508 TOPS）+ Aurix TC397。默认不用。
+- 用途：3090 忙训练时顶推理 / 固定台。
+- **待验证**：能否刷 Ubuntu+CUDA+PyTorch（常出厂 QNX/DRIVE OS）；跑不通就不管它。
+
+---
+
+## 国内网络 / 镜像（两台 GPU 机通用，setup 脚本自动处理）
+| 用途 | 直连不可达时的镜像 |
+|---|---|
+| pip | `https://pypi.tuna.tsinghua.edu.cn/simple`（或 Aliyun） |
+| HF dataset/weights | `HF_ENDPOINT=https://hf-mirror.com` |
+| git clone lerobot | `https://ghproxy.com/https://github.com/huggingface/lerobot.git` |
+
+## π0-FAST 推理在 3080(10GB) 放不下时的 fallback（P5 才需要）
+1. **4-bit 量化**（权重 6.6GB → ~2GB，立刻宽裕）
+2. **batch=1 + bf16 硬试**（~8-9GB，可能刚好）
+3. **3090 代推**：policy server 起在 ③，② 只做遥操/采数（同局域网，异步分块下延迟可接受）

env/setup_lerobot.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# ============================================================
+#  LeRobot 一键环境 — 3080 主家 / 3090 训练机（两台 Ubuntu 都跑一遍）
+#  用法:
+#    nano ~/robot/setup_lerobot.sh   # 粘入本文件
+#    bash ~/robot/setup_lerobot.sh
+#  跑完把【整段输出】粘回给助手，我带你走 P1。
+# ============================================================
+set -uo pipefail
+
+WORKDIR="${HOME}/robot"
+LEROBOT_DIR="${WORKDIR}/lerobot"
+VENV="${WORKDIR}/.venv"
+PY=3.12
+# LeRobot extras：feetech(SO-101) + lekiwi(底盘) + dataset(采数) + smolvla(主力VLA) + pi0(π0/π0-FAST)
+EXTRAS="feetech,lekiwi,dataset,smolvla,pi0"
+
+hr(){ echo; echo "========== $* =========="; }
+
+hr "[1/7] 环境探测"
+if [ -r /etc/os-release ]; then . /etc/os-release; echo "OS: ${PRETTY_NAME:-?}"; fi
+if command -v nvidia-smi >/dev/null 2>&1; then
+  nvidia-smi --query-gpu=name,memory.total,driver_version --format=csv,noheader
+else
+  echo "!! 未检测到 nvidia-smi —— GPU 驱动可能没装（3090 应能识别）。先装驱动再继续。"
+fi
+echo "系统 python3: $(python3 --version 2>&1)"
+echo "有 python3.12: $([ -x "$(command -v python3.12)" ] && echo 是 || echo 否)"
+echo "有 uv:          $([ -x "$(command -v uv)" ] && echo 是 || echo 否)"
+echo "有 git:         $(git --version 2>&1)"
+echo "有 ffmpeg:      $([ -x "$(command -v ffmpeg)" ] && echo 是 || echo 否)"
+
+hr "[2/7] 网络/镜像策略（直连 vs 国内镜像）"
+PIP_URL="https://pypi.org/simple"
+if curl -fsS --max-time 6 https://pypi.org >/dev/null 2>&1; then
+  echo "pypi 直连可达 → 官方源"
+else
+  echo "pypi 直连不可达 → 清华镜像"; PIP_URL="https://pypi.tuna.tsinghua.edu.cn/simple"
+fi
+if curl -fsS --max-time 6 https://huggingface.co >/dev/null 2>&1; then
+  echo "HF 直连可达 → 官方"; HF_ENDPOINT="https://huggingface.co"
+else
+  echo "HF 直连不可达 → hf-mirror"; HF_ENDPOINT="https://hf-mirror.com"
+fi
+export HF_ENDPOINT
+echo "→ PIP_URL=$PIP_URL"; echo "→ HF_ENDPOINT=$HF_ENDPOINT"
+
+hr "[3/7] Python ${PY} venv (${VENV})"
+mkdir -p "${WORKDIR}"
+if [ -d "${VENV}" ]; then echo "venv 已存在，复用"; else
+  if command -v uv >/dev/null 2>&1; then
+    uv venv --python ${PY} "${VENV}"
+  elif command -v python3.12 >/dev/null 2>&1; then
+    python3.12 -m venv "${VENV}"
+  elif command -v python3.11 >/dev/null 2>&1; then
+    echo "无 3.12，用 3.11 兜底（LeRobot 要 3.12，可能装不上，建议装 uv 或 deadsnakes 3.12）"
+    python3.11 -m venv "${VENV}"
+  else
+    echo "!! 没有 3.12/3.11/uv。装 uv:  curl -LsSf https://astral.sh/uv/install.sh | sh   然后重跑"; exit 1
+  fi
+fi
+# shellcheck disable=SC1091
+source "${VENV}/bin/activate"
+python -m pip install -U pip -i "${PIP_URL}"
+echo "venv python: $(python --version)  ($(which python))"
+
+hr "[4/7] clone LeRobot → ${LEROBOT_DIR}"
+if [ -d "${LEROBOT_DIR}/.git" ]; then
+  echo "已存在 → git pull 更新"; ( cd "${LEROBOT_DIR}" && git pull ) || true
+else
+  if curl -fsS --max-time 6 https://github.com >/dev/null 2>&1; then
+    git clone https://github.com/huggingface/lerobot.git "${LEROBOT_DIR}"
+  else
+    echo "github 直连慢/不可达 → 走 ghproxy 加速"
+    git clone https://ghproxy.com/https://github.com/huggingface/lerobot.git "${LEROBOT_DIR}"
+  fi
+fi
+cd "${LEROBOT_DIR}"
+echo "当前 commit: $(git log -1 --oneline 2>/dev/null)"
+
+hr "[5/7] 安装 LeRobot [${EXTRAS}]"
+pip install -e ".[${EXTRAS}]" -i "${PIP_URL}" 2>&1 | tail -n 25
+# ffmpeg（LeRobot 编视频需要）
+if ! command -v ffmpeg >/dev/null 2>&1; then
+  echo "装 ffmpeg ..."; ( sudo apt-get install -y ffmpeg 2>&1 || conda install -y -c conda-forge ffmpeg 2>&1 ) | tail -n 5
+fi
+
+hr "[6/7] 验证"
+python - <<'PY'
+import importlib, torch
+print("torch", torch.__version__,
+      "| cuda", torch.cuda.is_available(),
+      "| gpu", (torch.cuda.get_device_name(0) if torch.cuda.is_available() else "N/A"),
+      "| vram_GB", round(torch.cuda.get_device_properties(0).total_memory/1e9,1) if torch.cuda.is_available() else 0)
+try:
+    import lerobot; print("lerobot", getattr(lerobot, "__version__", "?"))
+except Exception as e:
+    print("lerobot import 失败:", e)
+for m in ["lerobot.policies.smolvla","lerobot.policies.pi0","lerobot.policies.act"]:
+    try: importlib.import_module(m); print("OK ", m)
+    except Exception as e: print("MISS", m, "->", e)
+PY
+echo "--- CLI 命令 ---"
+for c in lerobot-find-port lerobot-find-cameras lerobot-calibrate lerobot-teleoperate lerobot-record lerobot-train lerobot-eval lerobot-rollout; do
+  command -v "$c" >/dev/null 2>&1 && echo "OK   $c" || echo "MISS $c"
+done
+
+hr "[7/7] 完成 — 之后每次用 3090 前先:"
+cat <<EOF
+  source ${VENV}/bin/activate
+  cd ${LEROBOT_DIR}
+  export HF_ENDPOINT=${HF_ENDPOINT}
+  huggingface-cli login      # 首次: 输你的 HF token
+EOF
+echo "✅ 把上面 [1]~[7] 的完整输出粘回给助手。"
+echo "   若全 OK，我们就进 P1：插第一条 SO-101 → lerobot-find-port → 校准 → 遥操。"

hw/bom.md

@@ -0,0 +1,75 @@
+# 采购清单 (BOM) — 双臂移动 VLA 机器人
+
+> 状态图例：⬜ 未下单 · 🟨 已下单待发货 · 🟩 已到货 · ✅ 已组装
+> 价格为 2025 国内参考价，**下单前按链接核当期价/库存**。
+> **采购策略**：P1 先买 **2 条 SO-ARM101（1 Leader + 1 Follower）** 打通单臂闭环；P2 再补 2 条。LeKiwi / RPi5 在 P3 前买即可（等货期正好用来搭软件）。
+
+---
+
+## A. 机械臂 — SO-ARM101（LeRobot 官方 6DOF + 夹爪，Feetech STS3215）
+
+| # | 状态 | 部件 | 数量 | 参考价(¥) | 链接 / 店铺 |
+|---|---|---|---|---|---|
+| A1 | ⬜ | SO-ARM101 **Follower**（执行从手，含 3D 打印件+舵机+驱动板+电源） | 1 | ~879 | 淘宝搜「SO-ARM101 LeRobot」¥879-899 现货树脂打印版 |
+| A2 | ⬜ | SO-ARM101 **Leader**（遥操主手，轻齿轮、带握把） | 1 | ~879 | 同上（买 **Leader 版**） |
+| A3 | ⬜ | (P2 补) SO-ARM101 Follower #2 | 1 | ~879 | 同上 |
+| A4 | ⬜ | (P2 补) SO-ARM101 Leader #2 | 1 | ~879 | 同上 |
+| A5 | ⬜ | (可选) 舵机调试板 TTL/USB | 1-2 | ~49 | 淘宝「幻尔 SO-ARM101 调试板」 |
+
+- **官方备选**：Seeed SO-ARM101（3D-printed parts $35 / SKU 114993668；舵机散件 SKU 114993667）；Waveshare SO-ARM100/101 ~¥1406（带相机）。
+- **自印省钱**：有打印机则只买「舵机+电子件」散件(~¥500/条)，自己打印结构件（官方 STL 支持 FDM/PLA，或树脂更佳）。
+- **Leader 用轻负载齿轮**才捏得动（SO-101 已优化，无需外置齿轮箱）；**电机 ID 要按顺序烧录**（装时注意）。
+
+## B. 移动底盘 — LeKiwi（三轮全向，SO-101 专用，SIGRobotics-UIUC × HF）
+
+| # | 状态 | 部件 | 数量 | 参考价(¥) | 链接 / 说明 |
+|---|---|---|---|---|---|
+| B1 | ⬜ | LeKiwi 底盘 **12V（Seeed 含 3D 打印件+电池）** | 1 | ~1600-2000 | Seeed「LeKiwi Kit(12V)」SKU SS114090065 |
+| B2 | ⬜ | (省) LeKiwi **base-only 12V**（自印结构件） | 1 | ~1501 | SIGRobotics-UIUC/LeKiwi → BOM(CN) |
+| | | 内含：3× STS3215 1:345 12V 舵机 / 全向轮 / 电池 / 分线盒 / 12V转5V 降压 | | | 见 BOM |
+
+- LeRobot 有**原生 `.[lekiwi]` extra**（P3 时装）。底盘顶板 **M3 螺孔**直接固定 SO-101 底座。
+- **新手官方建议**：若臂用 5V，底盘用 12V + 自带 12V→5V 降压模块（套件提供）；舵机统一 12V。
+
+## C. 上机驱动板 — Raspberry Pi 5（实时控制 + 采图 + 执行 + 联网）
+
+| # | 状态 | 部件 | 数量 | 参考价(¥) |
+|---|---|---|---|---|
+| C1 | ⬜ | Raspberry Pi 5 (8GB) | 1 | ~550-650 |
+| C2 | ⬜ | RPi5 官方电源 (27W/5A USB-C) | 1 | ~100 |
+| C3 | ⬜ | **有源 USB 3.0 Hub**（4-7 口，独立供电） | 1 | ~80-150 |
+| C4 | ⬜ | 128G+ microSD / 或 NVMe SSD（系统+数据集） | 1 | ~60-150 |
+
+> RPi5 **不做 ML**（ML 在 4090 算力中心）；它只跑 LeRobot robot 驱动 + 动作执行 + fail-safe。
+> USB 设备数：2 臂 + 3 底盘轮 + 3 相机 ≈ 6-8 → **必须有源 Hub**。
+
+## D. 相机 ×3（LeRobot `--robot.cameras` 用 opencv 类型配置）
+
+| # | 状态 | 部件 | 数量 | 参考价(¥) |
+|---|---|---|---|---|
+| D1 | ⬜ | 腕部 USB 相机（1080P 免驱） | 2 | ~58-138 |
+| D2 | ⬜ | 前置全局 USB 相机（广角 1080P） | 1 | ~100 |
+| | | (可选) 「SO-101 双相机 USB 广角套件」 | — | 淘宝 ~¥138 |
+
+> 相机名 `front` / `left_wrist` / `right_wrist`，与 P4 的 state/action 对齐。
+
+## E. 杂项
+
+| # | 部件 | 说明 |
+|---|---|---|
+| E1 | USB-C 数据线 ×4-6 | 臂/底盘/相机连 RPi5 |
+| E2 | 桌夹 / 台夹 ×4 | P1/P2 把臂固定在桌/台面 |
+| E3 | 3D 打印耗材（PLA / 或树脂） | 自印结构件 / 相机支架 / 分线盒 |
+| E4 | 5V / 12V 电源适配器 | 散件自供时用 |
+| E5 | (P4) 短 1G 网线 / PoE 模块 | RPi5 ↔ 4090 算力中心，尽量有线 |
+
+---
+
+## 合计
+
+| 采购批次 | 内容 | 小计(¥) |
+|---|---|---|
+| **P1 起步** | 2 臂 + 2 相机 + RPi5 套 + 杂项 | **~3300** |
+| **完整整机** | 4 臂 + LeKiwi + RPi5 + 3 相机 + 杂项 | **~6500-8000** |
+
+> **已拥有（0 成本）**：4090/3090 Ubuntu 机（算力中心）、AWU408 双 Orin（富余算力）、3D 打印机、本 Windows 机（写代码）。