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

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`。